From: David MacKenzie Date: Tue, 31 Aug 1993 20:26:16 +0000 (+0000) Subject: * stabs.texinfo: Initial-caps all words in node names and X-Git-Url: https://git.libre-soc.org/?a=commitdiff_plain;h=bf9d25378e65e0c5b96cc0f4cbbaa485b98913ba;p=binutils-gdb.git * stabs.texinfo: Initial-caps all words in node names and non-trivial words in section names. --- diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog index d59192d3e47..dfb04497659 100644 --- a/gdb/doc/ChangeLog +++ b/gdb/doc/ChangeLog @@ -1,3 +1,8 @@ +Tue Aug 31 13:21:06 1993 David J. Mackenzie (djm@thepub.cygnus.com) + + * stabs.texinfo: Initial-caps all words in node names and + non-trivial words in section names. + Mon Aug 30 11:13:16 1993 Jim Kingdon (kingdon@lioth.cygnus.com) * stabs.texinfo: Many minor cleanups. diff --git a/gdb/doc/stabs.texinfo b/gdb/doc/stabs.texinfo index dca60940a24..3a29afc3c59 100644 --- a/gdb/doc/stabs.texinfo +++ b/gdb/doc/stabs.texinfo @@ -68,29 +68,29 @@ This document describes the stabs debugging format. @menu * Overview:: Overview of stabs -* Program structure:: Encoding of the structure of the program +* Program Structure:: Encoding of the structure of the program * Constants:: Constants * Variables:: * Types:: Type definitions -* Symbol tables:: Symbol information in symbol tables +* Symbol Tables:: Symbol information in symbol tables * Cplusplus:: Appendixes: -* Stab types:: Symbol types in a.out files -* Symbol descriptors:: Table of symbol descriptors -* Type descriptors:: Table of type descriptors -* Expanded reference:: Reference information by stab type +* Stab Types:: Symbol types in a.out files +* Symbol Descriptors:: Table of symbol descriptors +* Type Descriptors:: Table of type descriptors +* Expanded Reference:: Reference information by stab type * Questions:: Questions and anomolies -* XCOFF differences:: Differences between GNU stabs in a.out +* XCOFF Differences:: Differences between GNU stabs in a.out and GNU stabs in XCOFF -* Sun differences:: Differences between GNU stabs and Sun +* Sun Differences:: Differences between GNU stabs and Sun native stabs -* Stabs in ELF:: Stabs in an ELF file. -* Symbol Types Index:: Index of symbolic stab symbol type names. +* Stabs In ELF:: Stabs in an ELF file. +* Symbol Types Index:: Index of symbolic stab symbol type names. @end menu @end ifinfo @node Overview -@chapter Overview of stabs +@chapter Overview of Stabs @dfn{Stabs} refers to a format for information that describes a program to a debugger. This format was apparently invented by @@ -100,8 +100,8 @@ debugger; the format has spread widely since then. This document is one of the few published sources of documentation on stabs. It is believed to be comprehensive for stabs used by C. The -lists of symbol descriptors (@pxref{Symbol descriptors}) and type -descriptors (@pxref{Type descriptors}) are believed to be completely +lists of symbol descriptors (@pxref{Symbol Descriptors}) and type +descriptors (@pxref{Type Descriptors}) are believed to be completely comprehensive. Stabs for COBOL-specific features and for variant records (used by Pascal and Modula-2) are poorly documented here. @@ -114,14 +114,14 @@ you to them for more information. @menu * Flow:: Overview of debugging information flow -* Stabs format:: Overview of stab format -* String field:: The string field -* C example:: A simple example in C source -* Assembly code:: The simple example at the assembly level +* Stabs Format:: Overview of stab format +* String Field:: The string field +* C Example:: A simple example in C source +* Assembly Code:: The simple example at the assembly level @end menu @node Flow -@section Overview of debugging information flow +@section Overview of Debugging Information Flow The GNU C compiler compiles C source in a @file{.c} file into assembly language in a @file{.s} file, which the assembler translates into @@ -149,8 +149,8 @@ files into one executable file, with one symbol table and one string table. Debuggers use the symbol and string tables in the executable as a source of debugging information about the program. -@node Stabs format -@section Overview of stab format +@node Stabs Format +@section Overview of Stab Format There are three overall formats for stab assembler directives, differentiated by the first word of the stab. The name of the directive @@ -172,7 +172,7 @@ The overall format of each class of stab is: @c what is the correct term for "current file location"? My AIX @c assembler manual calls it "the value of the current location counter". For @code{.stabn} and @code{.stabd}, there is no @var{string} (the -@code{n_strx} field is zero; see @ref{Symbol tables}). For +@code{n_strx} field is zero; see @ref{Symbol Tables}). For @code{.stabd}, the @var{value} field is implicit and has the value of the current file location. For @code{.stabx}, the @var{sdb-type} field is unused for stabs and can always be set to zero. The @var{other} @@ -183,10 +183,10 @@ which type of stab this is (or whether it @emph{is} a stab, as opposed to an ordinary symbol). Each valid type number defines a different stab type; further, the stab type defines the exact interpretation of, and possible values for, any remaining @var{string}, @var{desc}, or -@var{value} fields present in the stab. @xref{Stab types}, for a list +@var{value} fields present in the stab. @xref{Stab Types}, for a list in numeric order of the valid @var{type} field values for stab directives. -@node String field +@node String Field @section The String Field For most stabs the string field holds the meat of the @@ -214,7 +214,7 @@ The @var{symbol-descriptor} following the @samp{:} is an alphabetic character that tells more specifically what kind of symbol the stab represents. If the @var{symbol-descriptor} is omitted, but type information follows, then the stab represents a local variable. For a -list of symbol descriptors, see @ref{Symbol descriptors}. The @samp{c} +list of symbol descriptors, see @ref{Symbol Descriptors}. The @samp{c} symbol descriptor is an exception in that it is not followed by type information. @xref{Constants}. @@ -231,7 +231,7 @@ In a type definition, if the character that follows the equals sign is non-numeric then it is a @var{type-descriptor}, and tells what kind of type is about to be defined. Any other values following the @var{type-descriptor} vary, depending on the @var{type-descriptor}. -@xref{Type descriptors}, for a list of @var{type-descriptor} values. If +@xref{Type Descriptors}, for a list of @var{type-descriptor} values. If a number follows the @samp{=} then the number is a @var{type-reference}. For a full description of types, @ref{Types}. @@ -274,8 +274,8 @@ double-backslash at the end. Removing the backslashes and concatenating the string fields of each stab produces the original, long string. -@node C example -@section A simple example in C source +@node C Example +@section A Simple Example in C Source To get the flavor of how stabs describe source information for a C program, let's look at the simple program: @@ -292,8 +292,8 @@ When compiled with @samp{-g}, the program above yields the following to parts of the @file{.s} file in the description of the stabs that follows. -@node Assembly code -@section The simple example at the assembly level +@node Assembly Code +@section The Simple Example at the Assembly Level This simple ``hello world'' example demonstrates several of the stab types used to describe C language source files. @@ -353,8 +353,8 @@ types used to describe C language source files. 52 .stabn 224,0,0,LBE2 @end example -@node Program structure -@chapter Encoding the structure of the program +@node Program Structure +@chapter Encoding the Structure of the Program The elements of the program structure that stabs encode include the name of the main function, the names of the source and include files, the @@ -362,17 +362,17 @@ line numbers, procedure names and types, and the beginnings and ends of blocks of code. @menu -* Main program:: Indicate what the main program is -* Source files:: The path and name of the source file -* Include files:: Names of include files -* Line numbers:: +* Main Program:: Indicate what the main program is +* Source Files:: The path and name of the source file +* Include Files:: Names of include files +* Line Numbers:: * Procedures:: -* Nested procedures:: -* Block structure:: +* Nested Procedures:: +* Block Structure:: @end menu -@node Main program -@section Main program +@node Main Program +@section Main Program @findex N_MAIN Most languages allow the main program to have any name. The @@ -383,8 +383,8 @@ stab (they expect the debugger to assume that the name is @code{main}), but some C compilers emit an @code{N_MAIN} stab for the @code{main} function. -@node Source files -@section Paths and names of the source files +@node Source Files +@section Paths and Names of the Source Files @findex N_SO Before any other stabs occur, there must be a stab specifying the source @@ -418,8 +418,8 @@ Instead of @code{N_SO} symbols, XCOFF uses a @code{.file} assembler directive which assembles to a standard COFF @code{.file} symbol; explaining this in detail is outside the scope of this document. -@node Include files -@section Names of include files +@node Include Files +@section Names of Include Files There are several schemes for dealing with include files: the traditional @code{N_SOL} approach, Sun's @code{N_BINCL} approach, and the @@ -467,8 +467,8 @@ and linker, is the offset into the executable of the beginning of the portion of the COFF line table that corresponds to this include file. @code{C_BINCL} and @code{C_EINCL} do not nest. -@node Line numbers -@section Line numbers +@node Line Numbers +@section Line Numbers @findex N_SLINE An @code{N_SLINE} symbol represents the start of a source line. The @@ -495,7 +495,7 @@ start of each code range, each with the same line number. XCOFF uses COFF line numbers, which are outside the scope of this document, ammeliorated by adequate marking of include files -(@pxref{Include files}). +(@pxref{Include Files}). @node Procedures @section Procedures @@ -552,7 +552,7 @@ Solaris compiler uses symbol descriptor @samp{P} followed by the return type of the function, followed by the arguments, each preceded by @samp{;}, as in a stab with symbol descriptor @samp{f} or @samp{F}. This use of symbol descriptor @samp{P} can be distinguished from its use -for register parameters (@pxref{Register parameters}) by the fact that it has +for register parameters (@pxref{Register Parameters}) by the fact that it has symbol type @code{N_FUN}. The AIX documentation also defines symbol descriptor @samp{J} as an @@ -583,8 +583,8 @@ group of other stabs describing elements of the procedure. These other stabs describe the procedure's parameters, its block local variables, and its block structure. -@node Nested procedures -@section Nested procedures +@node Nested Procedures +@section Nested Procedures For any of the symbol descriptors representing procedures, after the symbol descriptor and the type information is optionally a scope @@ -622,8 +622,8 @@ produces the stabs: .stabs "foo:F1",36,0,0,_foo @end example -@node Block structure -@section Block structure +@node Block Structure +@section Block Structure @findex N_LBRAC @findex N_RBRAC @@ -667,7 +667,7 @@ Character constant. @var{value} is the numeric value of the constant. @item e @var{type-information} , @var{value} Constant whose value can be represented as integral. @var{type-information} is the type of the constant, as it would appear -after a symbol descriptor (@pxref{String field}). @var{value} is the +after a symbol descriptor (@pxref{String Field}). @var{value} is the numeric value of the constant. GDB 4.9 does not actually get the right value if @var{value} does not fit in a host @code{int}, but it does not do anything violent, and future debuggers could be extended to accept @@ -695,7 +695,7 @@ string are represented as @samp{\"}). @item S @var{type-information} , @var{elements} , @var{bits} , @var{pattern} Set constant. @var{type-information} is the type of the constant, as it -would appear after a symbol descriptor (@pxref{String field}). +would appear after a symbol descriptor (@pxref{String Field}). @var{elements} is the number of elements in the set (does this means how many bits of @var{pattern} are actually used, which would be redundant with the type, or perhaps the number of bits set in @@ -723,21 +723,21 @@ allocated: on the stack, globally, in registers, in common blocks, statically, or as arguments to a function. @menu -* Stack variables:: Variables allocated on the stack. -* Global variables:: Variables used by more than one source file. -* Register variables:: Variables in registers. -* Common blocks:: Variables statically allocated together. +* Stack Variables:: Variables allocated on the stack. +* Global Variables:: Variables used by more than one source file. +* Register Variables:: Variables in registers. +* Common Blocks:: Variables statically allocated together. * Statics:: Variables local to one source file. * Parameters:: Variables for arguments to functions. @end menu -@node Stack variables -@section Automatic variables allocated on the stack +@node Stack Variables +@section Automatic Variables Allocated on the Stack If a variable's scope is local to a function and its lifetime is only as long as that function executes (C calls such variables @dfn{automatic}), it can be allocated in a register (@pxref{Register -variables}) or on the stack. +Variables}) or on the stack. @findex N_LSYM Each variable allocated on the stack has a stab with the symbol @@ -752,7 +752,7 @@ Stabs for stack variables use the @code{N_LSYM} stab type. The value of the stab is the offset of the variable within the local variables. On most machines this is an offset from the frame pointer and is negative. The location of the stab specifies which block -it is defined in; see @ref{Block structure}. +it is defined in; see @ref{Block Structure}. For example, the following C code: @@ -774,17 +774,17 @@ produces the following stabs: @end example @xref{Procedures} for more information on the @code{N_FUN} stab, and -@ref{Block structure} for more information on the @code{N_LBRAC} and +@ref{Block Structure} for more information on the @code{N_LBRAC} and @code{N_RBRAC} stabs. -@node Global variables -@section Global variables +@node Global Variables +@section Global Variables @findex N_GSYM A variable whose scope is not specific to just one source file is represented by the @samp{G} symbol descriptor. These stabs use the @code{N_GSYM} stab type. The type information for the stab -(@pxref{String field}) gives the type of the variable. +(@pxref{String Field}) gives the type of the variable. For example, the following source code: @@ -809,8 +809,8 @@ from the external symbol for the global variable. In the example above, the @code{.global _g_foo} and @code{_g_foo:} lines tell the assembler to produce an external symbol. -@node Register variables -@section Register variables +@node Register Variables +@section Register Variables @findex N_RSYM @c According to an old version of this manual, AIX uses C_RPSYM instead @@ -836,8 +836,8 @@ register int g_bar asm ("%g5"); then the stab may be emitted at the end of the object file, with the other bss symbols. -@node Common blocks -@section Common blocks +@node Common Blocks +@section Common Blocks A common block is a statically allocated section of memory which can be referred to by several source files. It may contain several variables. @@ -861,7 +861,7 @@ one would use @samp{S} if not local to a function (that is, if a common block @emph{can} be anything other than local to a function). @node Statics -@section Static variables +@section Static Variables Initialized static variables are represented by the @samp{S} and @samp{V} symbol descriptors. @samp{S} means file scope static, and @@ -959,14 +959,14 @@ value -> offset from the argument pointer (positive). @end example @menu -* Register parameters:: -* Local variable parameters:: -* Reference parameters:: -* Conformant arrays:: +* Register Parameters:: +* Local Variable Parameters:: +* Reference Parameters:: +* Conformant Arrays:: @end menu -@node Register parameters -@subsection Passing parameters in registers +@node Register Parameters +@subsection Passing Parameters in Registers If the parameter is passed in a register, then traditionally there are two symbols for each argument: @@ -1013,10 +1013,10 @@ case (it is said to mean "value parameter by reference, indirect access"; I don't know the source for this information), but I don't know details or what compilers or debuggers use it, if any (not GDB or GCC). It is not clear to me whether this case needs to be dealt with -differently than parameters passed by reference (@pxref{Reference parameters}). +differently than parameters passed by reference (@pxref{Reference Parameters}). -@node Local variable parameters -@subsection Storing parameters as local variables +@node Local Variable Parameters +@subsection Storing Parameters as Local Variables There is a case similar to an argument in a register, which is an argument that is actually stored as a local variable. Sometimes this @@ -1039,8 +1039,8 @@ is an offset relative to the local variables for that function, not relative to the arguments; on some machines those are the same thing, but not on all. -@node Reference parameters -@subsection Passing parameters by reference +@node Reference Parameters +@subsection Passing Parameters by Reference If the parameter is passed by reference (e.g., Pascal @code{VAR} parameters), then the symbol descriptor is @samp{v} if it is in the @@ -1050,8 +1050,8 @@ parameter itself, they are identical to @samp{p} and @samp{R}, respectively. I believe @samp{a} is an AIX invention; @samp{v} is supported by all stabs-using systems as far as I know. -@node Conformant arrays -@subsection Passing conformant array parameters +@node Conformant Arrays +@subsection Passing Conformant Array Parameters @c Is this paragraph correct? It is based on piecing together patchy @c information and some guesswork @@ -1066,7 +1066,7 @@ argument list where the size of the array (in elements? in bytes?) is stored. @node Types -@chapter Defining types +@chapter 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 @@ -1074,9 +1074,9 @@ previously defined types. This chapter describes the other type descriptors that may follow the @samp{=} 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. +* 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. @@ -1084,11 +1084,11 @@ descriptors that may follow the @samp{=} in a type definition. * Structures:: An aggregate type of different-typed elements. * Typedefs:: Giving a type a name. * Unions:: Different types sharing storage. -* Function types:: +* Function Types:: @end menu -@node Builtin types -@section Builtin types +@node Builtin Types +@section Builtin Types Certain types are built in (@code{int}, @code{short}, @code{void}, @code{float}, etc.); the debugger recognizes these types and knows how @@ -1105,25 +1105,25 @@ 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 +* 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 @end menu -@node Traditional builtin types -@subsection Traditional builtin types +@node Traditional Builtin Types +@subsection 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 @code{void}. @menu -* Traditional integer types:: -* Traditional other types:: +* Traditional Integer Types:: +* Traditional Other Types:: @end menu -@node Traditional integer types -@subsubsection Traditional integer types +@node Traditional Integer Types +@subsubsection Traditional Integer Types Often types are defined as subranges of themselves. If the bounding values fit within an @code{int}, then they are given normally. For example: @@ -1168,8 +1168,8 @@ convention for @code{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. -@node Traditional other types -@subsubsection Traditional other types +@node Traditional Other Types +@subsubsection 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 @@ -1199,8 +1199,8 @@ The C @code{void} type is defined as itself: I'm not sure how a boolean type is represented. -@node Builtin type descriptors -@subsection Defining builtin types using builtin type descriptors +@node Builtin Type Descriptors +@subsection Defining Builtin Types Using Builtin Type Descriptors This is the method used by Sun's @code{acc} for defining builtin types. These are the type descriptors to define builtin types: @@ -1223,14 +1223,14 @@ type. @var{offset} seems to always be zero. @var{nbits} is the number of bits in the type. Note that type descriptor @samp{b} used for builtin types conflicts with -its use for Pascal space types (@pxref{Miscellaneous types}); they can +its use for Pascal space types (@pxref{Miscellaneous Types}); they can be distinguished because the character following the type descriptor will be a digit, @samp{(}, or @samp{-} for a Pascal space type, or @samp{u} or @samp{s} for a builtin type. @item w Documented by AIX to define a wide character type, but their compiler -actually uses negative type numbers (@pxref{Negative type numbers}). +actually uses negative type numbers (@pxref{Negative Type Numbers}). @item R @var{fp-type} ; @var{bytes} ; Define a floating point type. @var{fp-type} has one of the following values: @@ -1265,11 +1265,11 @@ understand @var{fp-type}. @item g @var{type-information} ; @var{nbits} Documented by AIX to define a floating type, but their compiler actually -uses negative type numbers (@pxref{Negative type numbers}). +uses negative type numbers (@pxref{Negative Type Numbers}). @item c @var{type-information} ; @var{nbits} Documented by AIX to define a complex type, but their compiler actually -uses negative type numbers (@pxref{Negative type numbers}). +uses negative type numbers (@pxref{Negative Type Numbers}). @end table The C @code{void} type is defined as a signed integral type 0 bits long: @@ -1283,8 +1283,8 @@ where it ends. I'm not sure how a boolean type is represented. -@node Negative type numbers -@subsection Negative type numbers +@node Negative Type Numbers +@subsection 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 @@ -1425,16 +1425,16 @@ floating point values. Unicode?). @end table -@node Miscellaneous types -@section Miscellaneous types +@node Miscellaneous Types +@section Miscellaneous Types @table @code @item b @var{type-information} ; @var{bytes} Pascal space type. This is documented by IBM; what does it mean? This use of the @samp{b} type descriptor can be distinguished -from its use for builtin integral types (@pxref{Builtin type -descriptors}) because the character following the type descriptor is +from its use for builtin integral types (@pxref{Builtin Type +Descriptors}) because the character following the type descriptor is always a digit, @samp{(}, or @samp{-}. @item B @var{type-information} @@ -1455,7 +1455,7 @@ extension. A variable with a const-qualified type cannot be modified. Multiple instance type. The type seems to composed of @var{length} repetitions of @var{type-information}, for example @code{character*3} is represented by @samp{M-2;3}, where @samp{-2} is a reference to a -character type (@pxref{Negative type numbers}). I'm not sure how this +character type (@pxref{Negative Type Numbers}). I'm not sure how this differs from an array. This appears to be a Fortran feature. @var{length} is a bound, like those in range types; see @ref{Subranges}. @@ -1468,8 +1468,8 @@ specified by the number of elements in @var{type-information}. Pointer to @var{type-information}. @end table -@node Cross-references -@section Cross-references to other types +@node Cross-References +@section 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 @@ -1505,10 +1505,10 @@ the type. This differs from merely naming the type (@pxref{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 -(@pxref{String field}), or what. The symbol ends with @samp{;}. +(@pxref{String Field}), or what. The symbol ends with @samp{;}. @node Subranges -@section Subrange types +@section Subrange Types The @samp{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 @@ -1541,10 +1541,10 @@ The bound is passed by value in register number @var{register-number}. There is no bound. @end table -Subranges are also used for builtin types; see @ref{Traditional builtin types}. +Subranges are also used for builtin types; see @ref{Traditional Builtin Types}. @node Arrays -@section Array types +@section Array Types Arrays use the @samp{a} type descriptor. Following the type descriptor is the type of the index and the type of the array elements. If the @@ -1563,7 +1563,7 @@ 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 (@pxref{String field}) (that is, it need not start with +type information (@pxref{String Field}) (that is, it need not start with @samp{@var{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 @samp{ar1;1;10;ar1;1;10;4} as a legitimate way to express a two @@ -1601,7 +1601,7 @@ 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 -(@pxref{String field}). In the case of arrays, another is to use the +(@pxref{String Field}). In the case of arrays, another is to use the @samp{P} type descriptor instead of @samp{a}. Other than specifying a packed array, @samp{P} is identical to @samp{a}. @@ -1695,7 +1695,7 @@ 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). There should be a way to specify an enumeration type of another size; type attributes would be one way to do this. @xref{Stabs -format}. +Format}. @node Structures @section Structures @@ -1752,10 +1752,10 @@ 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. @node Typedefs -@section Giving a type a name +@section Giving a Type a Name To give a type a name, use the @samp{t} symbol descriptor. The type -is specified by the type information (@pxref{String field}) for the stab. +is specified by the type information (@pxref{String Field}) for the stab. For example, @example @@ -1773,7 +1773,7 @@ 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 @samp{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 (@pxref{String field})? There +descriptor used with a nameless stab (@pxref{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 @@ -1827,10 +1827,10 @@ The stab for the union variable is: @end example @samp{-20} specifies where the variable is stored (@pxref{Stack -variables}). +Variables}). -@node Function types -@section Function types +@node Function Types +@section Function Types Various types can be defined for function variables. These types are not used in defining functions (@pxref{Procedures}); they are used for @@ -1873,20 +1873,20 @@ generates the following code: The variable defines a new type, 24, which is a pointer to another new type, 25, which is a function returning @code{int}. -@node Symbol tables -@chapter Symbol information in symbol tables +@node Symbol Tables +@chapter 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:: +* Symbol Table Format:: +* Transformations On Symbol Tables:: @end menu -@node Symbol table format -@section Symbol table format +@node Symbol Table Format +@section 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 @@ -1917,8 +1917,8 @@ 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. -@node Transformations on symbol tables -@section Transformations on symbol tables +@node Transformations On Symbol Tables +@section Transformations on Symbol Tables The linker concatenates object files and does fixups of externally defined symbols. @@ -1942,12 +1942,12 @@ 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:: +* Transformations On Static Variables:: +* Transformations On Global Variables:: @end menu -@node Transformations on static variables -@subsection Transformations on static variables +@node Transformations On Static Variables +@subsection Transformations on Static Variables This source line defines a static variable at file scope: @@ -1978,8 +1978,8 @@ relocatable address absolute. 0000e00c - 00 0000 STSYM s_g_repeat:S1 @end example -@node Transformations on global variables -@subsection Transformations on global variables +@node Transformations On Global Variables +@subsection 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 @@ -2020,19 +2020,19 @@ entry now holds an absolute address: @end example @node Cplusplus -@chapter GNU C++ stabs +@chapter GNU C++ Stabs @menu -* Basic cplusplus types:: -* Simple classes:: -* Class instance:: +* Basic Cplusplus Types:: +* Simple Classes:: +* Class Instance:: * Methods:: Method definition * Protections:: -* Method modifiers:: -* Virtual methods:: +* Method Modifiers:: +* Virtual Methods:: * Inheritence:: -* Virtual base classes:: -* Static members:: +* Virtual Base Classes:: +* Static Members:: @end menu Type descriptors added for C++ descriptions: @@ -2048,14 +2048,14 @@ 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 -(@pxref{String field}); both use type descriptor @samp{@@}. +(@pxref{String Field}); both use type descriptor @samp{@@}. Fortunately, the @samp{@@} type descriptor used in this C++ sense always will be followed by a digit, @samp{(}, or @samp{-}, and type attributes never start with those things. @end table -@node Basic cplusplus types -@section Basic types for C++ +@node Basic Cplusplus Types +@section Basic Types For C++ << the examples that follow are based on a01.C >> @@ -2098,8 +2098,8 @@ virtual methods defined. .stabs "$vtbl_ptr_type:T17",128,0,0,0 @end example -@node Simple classes -@section Simple class definition +@node Simple Classes +@section Simple Class Definition The stabs describing C++ language features are an extension of the stabs describing C. Stabs representing C++ class types elaborate @@ -2196,8 +2196,8 @@ information present for virtual methods. .stabs "baseA:T20",128,0,0,0 @end smallexample -@node Class instance -@section Class instance +@node Class Instance +@section Class Instance As shown above, describing even a simple C++ class definition is accomplished by massively extending the stab format used in C to @@ -2224,7 +2224,7 @@ different from a standard C stab describing a local variable. @end example @node Methods -@section Method defintion +@section Method Defintion The class definition shown above declares Ameth. The C++ source below defines Ameth: @@ -2372,8 +2372,8 @@ descriptors apply to the class name struct tag and struct type. pubMeth::24=##12;:f;2A.;;",128,0,0,0 @end smallexample -@node Method modifiers -@section Method modifiers (@code{const}, @code{volatile}, @code{const volatile}) +@node Method Modifiers +@section Method Modifiers (@code{const}, @code{volatile}, @code{const volatile}) << based on a6.C >> @@ -2411,8 +2411,8 @@ This class is described by the following stab: ConstVolMeth::23=##12;:f;2D.;;",128,0,0,0 @end example -@node Virtual methods -@section Virtual methods +@node Virtual Methods +@section Virtual Methods << The following examples are based on a4.C >> @@ -2600,8 +2600,8 @@ the derivation of this class is encoded as follows. 28;;D_virt::32:i;2A*-2147483646;31;;;~%20;",128,0,0,0 @end smallexample -@node Virtual base classes -@section Virtual base classes +@node Virtual Base Classes +@section 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 @@ -2649,8 +2649,8 @@ class object is a follows, @code{Adat} at 0, the vtable pointer for virtual base pointer for @code{B} at 128, and @code{Ddat} at 160. -@node Static members -@section Static members +@node Static Members +@section 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 @@ -2659,8 +2659,8 @@ description in the class stab shows this ordering. << How is this reflected in stabs? See Cygnus bug #677 for some info. >> -@node Stab types -@appendix Table of stab types +@node Stab Types +@appendix Table of Stab Types The following are all the possible values for the stab type field, for @code{a.out} files, in numeric order. This does not apply to XCOFF, but @@ -2670,12 +2670,12 @@ it does apply to stabs in ELF. Stabs in ECOFF use these values but add The symbolic names are defined in the file @file{include/aout/stabs.def}. @menu -* Non-stab symbol types:: Types from 0 to 0x1f -* Stab symbol types:: Types from 0x20 to 0xff +* Non-Stab Symbol Types:: Types from 0 to 0x1f +* Stab Symbol Types:: Types from 0x20 to 0xff @end menu -@node Non-stab symbol types -@appendixsec Non-stab symbol types +@node Non-Stab Symbol Types +@appendixsec 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 @@ -2746,8 +2746,8 @@ Print a warning message during linking File name of a @file{.o} file @end table -@node Stab symbol types -@appendixsec Stab symbol types +@node Stab Symbol Types +@appendixsec 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 @@ -2755,7 +2755,7 @@ languages other than C. @table @code @item 0x20 N_GSYM -Global symbol; see @ref{Global variables}. +Global symbol; see @ref{Global Variables}. @item 0x22 N_FNAME Function name (for BSD Fortran); see @ref{Procedures}. @@ -2771,7 +2771,7 @@ Data segment file-scope variable; see @ref{Statics}. BSS segment file-scope variable; see @ref{Statics}. @item 0x2a N_MAIN -Name of main routine; see @ref{Main program}. +Name of main routine; see @ref{Main Program}. @c FIXME: discuss this in the Statics node where we talk about @c the fact that the n_type indicates the section. @@ -2797,19 +2797,19 @@ Object file (Solaris2). Debugger options (Solaris2). @item 0x40 N_RSYM -Register variable; see @ref{Register variables}. +Register variable; see @ref{Register Variables}. @item 0x42 N_M2C Modula-2 compilation unit; see @ref{N_M2C}. @item 0x44 N_SLINE -Line number in text segment; see @ref{Line numbers}. +Line number in text segment; see @ref{Line Numbers}. @item 0x46 N_DSLINE -Line number in data segment; see @ref{Line numbers}. +Line number in data segment; see @ref{Line Numbers}. @item 0x48 N_BSLINE -Line number in bss segment; see @ref{Line numbers}. +Line number in bss segment; see @ref{Line Numbers}. @item 0x48 N_BROWS Sun source code browser, path to @file{.cb} file; see @ref{N_BROWS}. @@ -2836,46 +2836,46 @@ Structure of union element; see @ref{N_SSYM}. Last stab for module (Solaris2). @item 0x64 N_SO -Path and name of source file; see @ref{Source files}. +Path and name of source file; see @ref{Source Files}. @item 0x80 N_LSYM -Stack variable (@pxref{Stack variables}) or type (@pxref{Typedefs}). +Stack variable (@pxref{Stack Variables}) or type (@pxref{Typedefs}). @item 0x82 N_BINCL -Beginning of an include file (Sun only); see @ref{Include files}. +Beginning of an include file (Sun only); see @ref{Include Files}. @item 0x84 N_SOL -Name of include file; see @ref{Include files}. +Name of include file; see @ref{Include Files}. @item 0xa0 N_PSYM Parameter variable; see @ref{Parameters}. @item 0xa2 N_EINCL -End of an include file; see @ref{Include files}. +End of an include file; see @ref{Include Files}. @item 0xa4 N_ENTRY Alternate entry point; see @ref{N_ENTRY}. @item 0xc0 N_LBRAC -Beginning of a lexical block; see @ref{Block structure}. +Beginning of a lexical block; see @ref{Block Structure}. @item 0xc2 N_EXCL -Place holder for a deleted include file; see @ref{Include files}. +Place holder for a deleted include file; see @ref{Include Files}. @item 0xc4 N_SCOPE Modula2 scope information (Sun linker); see @ref{N_SCOPE}. @item 0xe0 N_RBRAC -End of a lexical block; see @ref{Block structure}. +End of a lexical block; see @ref{Block Structure}. @item 0xe2 N_BCOMM -Begin named common block; see @ref{Common blocks}. +Begin named common block; see @ref{Common Blocks}. @item 0xe4 N_ECOMM -End named common block; see @ref{Common blocks}. +End named common block; see @ref{Common Blocks}. @item 0xe8 N_ECOML -Member of a common block; see @ref{Common blocks}. +Member of a common block; see @ref{Common Blocks}. @c FIXME: How does this really work? Move it to main body of document. @item 0xea N_WITH @@ -2902,11 +2902,11 @@ Gould non-base registers; see @ref{Gould}. @tableindent=.8in @end iftex -@node Symbol descriptors -@appendix Table of symbol descriptors +@node Symbol Descriptors +@appendix 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. @xref{String field}, +stabs, and which tells what kind of stab it is. @xref{String Field}, for more information about their use. @c Please keep this alphabetical @@ -2918,25 +2918,25 @@ for more information about their use. @item @var{digit} @itemx ( @itemx - -Variable on the stack; see @ref{Stack variables}. +Variable on the stack; see @ref{Stack Variables}. @item a -Parameter passed by reference in register; see @ref{Reference parameters}. +Parameter passed by reference in register; see @ref{Reference Parameters}. @item c Constant; see @ref{Constants}. @item C Conformant array bound (Pascal, maybe other languages); @ref{Conformant -arrays}. Name of a caught exception (GNU C++). These can be +Arrays}. Name of a caught exception (GNU C++). These can be distinguished because the latter uses @code{N_CATCH} and the former uses another symbol type. @item d -Floating point register variable; see @ref{Register variables}. +Floating point register variable; see @ref{Register Variables}. @item D -Parameter in floating point register; see @ref{Register parameters}. +Parameter in floating point register; see @ref{Register Parameters}. @item f File scope function; see @ref{Procedures}. @@ -2945,16 +2945,16 @@ File scope function; see @ref{Procedures}. Global function; see @ref{Procedures}. @item G -Global variable; see @ref{Global variables}. +Global variable; see @ref{Global Variables}. @item i -@xref{Register parameters}. +@xref{Register Parameters}. @item I -Internal (nested) procedure; see @ref{Nested procedures}. +Internal (nested) procedure; see @ref{Nested Procedures}. @item J -Internal (nested) function; see @ref{Nested procedures}. +Internal (nested) function; see @ref{Nested Procedures}. @item L Label name (documented by AIX, no further information known). @@ -2983,10 +2983,10 @@ referenced by this file (Sun @code{acc}) (symbol type @code{N_FUN}). Static Procedure; see @ref{Procedures}. @item R -Register parameter; see @ref{Register parameters}. +Register parameter; see @ref{Register Parameters}. @item r -Register variable; see @ref{Register variables}. +Register variable; see @ref{Register Variables}. @item S File scope variable; see @ref{Statics}. @@ -2998,44 +2998,44 @@ Type name; see @ref{Typedefs}. Enumeration, structure, or union tag; see @ref{Typedefs}. @item v -Parameter passed by reference; see @ref{Reference parameters}. +Parameter passed by reference; see @ref{Reference Parameters}. @item V Procedure scope static variable; see @ref{Statics}. @item x -Conformant array; see @ref{Conformant arrays}. +Conformant array; see @ref{Conformant Arrays}. @item X Function return variable; see @ref{Parameters}. @end table -@node Type descriptors -@appendix Table of type descriptors +@node Type Descriptors +@appendix 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. -@xref{String field}, for more information about their use. +@xref{String Field}, for more information about their use. @table @code @item @var{digit} @itemx ( -Type reference; see @ref{String field}. +Type reference; see @ref{String Field}. @item - -Reference to builtin type; see @ref{Negative type numbers}. +Reference to builtin type; see @ref{Negative Type Numbers}. @item # Method (C++); see @ref{Cplusplus}. @item * -Pointer; see @ref{Miscellaneous types}. +Pointer; see @ref{Miscellaneous Types}. @item & Reference (C++). @item @@ -Type Attributes (AIX); see @ref{String field}. Member (class and variable) +Type Attributes (AIX); see @ref{String Field}. Member (class and variable) type (GNU C++); see @ref{Cplusplus}. @item a @@ -3045,20 +3045,20 @@ Array; see @ref{Arrays}. Open array; see @ref{Arrays}. @item b -Pascal space type (AIX); see @ref{Miscellaneous types}. Builtin integer -type (Sun); see @ref{Builtin type descriptors}. +Pascal space type (AIX); see @ref{Miscellaneous Types}. Builtin integer +type (Sun); see @ref{Builtin Type Descriptors}. @item B -Volatile-qualified type; see @ref{Miscellaneous types}. +Volatile-qualified type; see @ref{Miscellaneous Types}. @item c -Complex builtin type; see @ref{Builtin type descriptors}. +Complex builtin type; see @ref{Builtin Type Descriptors}. @item C COBOL Picture type. See AIX documentation for details. @item d -File type; see @ref{Miscellaneous types}. +File type; see @ref{Miscellaneous Types}. @item D N-dimensional dynamic array; see @ref{Arrays}. @@ -3070,28 +3070,28 @@ Enumeration type; see @ref{Enumerations}. N-dimensional subarray; see @ref{Arrays}. @item f -Function type; see @ref{Function types}. +Function type; see @ref{Function Types}. @item F -Pascal function parameter; see @ref{Function types} +Pascal function parameter; see @ref{Function Types} @item g -Builtin floating point type; see @ref{Builtin type descriptors}. +Builtin floating point type; see @ref{Builtin Type Descriptors}. @item G COBOL Group. See AIX documentation for details. @item i -Imported type; see @ref{Cross-references}. +Imported type; see @ref{Cross-References}. @item k -Const-qualified type; see @ref{Miscellaneous types}. +Const-qualified type; see @ref{Miscellaneous Types}. @item K COBOL File Descriptor. See AIX documentation for details. @item M -Multiple instance type; see @ref{Miscellaneous types}. +Multiple instance type; see @ref{Miscellaneous Types}. @item n String type; see @ref{Strings}. @@ -3103,7 +3103,7 @@ Stringptr; see @ref{Strings}. Opaque type; see @ref{Typedefs}. @item p -Procedure; see @ref{Function types}. +Procedure; see @ref{Function Types}. @item P Packed array; see @ref{Arrays}. @@ -3112,8 +3112,8 @@ Packed array; see @ref{Arrays}. Range type; see @ref{Subranges}. @item R -Builtin floating type; see @ref{Builtin type descriptors} (Sun). Pascal -subroutine parameter; see @ref{Function types} (AIX). Detecting this +Builtin floating type; see @ref{Builtin Type Descriptors} (Sun). Pascal +subroutine parameter; see @ref{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). @@ -3122,7 +3122,7 @@ descriptor never will). Structure type; see @ref{Structures}. @item S -Set type; see @ref{Miscellaneous types}. +Set type; see @ref{Miscellaneous Types}. @item u Union; see @ref{Unions}. @@ -3132,22 +3132,22 @@ 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. @item w -Wide character; see @ref{Builtin type descriptors}. +Wide character; see @ref{Builtin Type Descriptors}. @item x -Cross-reference; see @ref{Cross-references}. +Cross-reference; see @ref{Cross-References}. @item z gstring; see @ref{Strings}. @end table -@node Expanded reference -@appendix Expanded reference by stab type +@node Expanded Reference +@appendix Expanded Reference by Stab Type @c FIXME: This appendix should go away; see N_PSYM or N_SO for an example. For a full list of stab types, and cross-references to where they are -described, see @ref{Stab types}. This appendix just duplicates certain +described, see @ref{Stab Types}. This appendix just duplicates certain information from the main body of this document; eventually the information will all be in one place. @@ -3377,7 +3377,7 @@ The value is the length. @end deffn @node Questions -@appendix Questions and anomalies +@appendix Questions and Anomalies @itemize @bullet @item @@ -3428,8 +3428,8 @@ knows that external symbols have leading underbars). @c dbx? @end itemize -@node XCOFF differences -@appendix Differences between GNU stabs in a.out and GNU stabs in XCOFF +@node XCOFF Differences +@appendix Differences Between GNU Stabs in a.out and GNU Stabs in XCOFF @c FIXME: Merge *all* these into the main body of the document. The AIX/RS6000 native object file format is XCOFF with stabs. This @@ -3447,7 +3447,7 @@ Some stab types in a.out are not supported in XCOFF; most of these use @c used (I suspect not), explain clearly, and move to node Statics. Exception: initialised static @code{N_STSYM} and un-initialized static @code{N_LCSYM} both map to the @code{C_STSYM} storage class. But the -destinction is preserved because in XCOFF @code{N_STSYM} and +distinction is preserved because in XCOFF @code{N_STSYM} and @code{N_LCSYM} must be emited in a named static block. Begin the block with @samp{.bs s[RW] data_section_name} for @code{N_STSYM} or @samp{.bs s bss_section_name} for @code{N_LCSYM}. End the block with @samp{.es}. @@ -3504,8 +3504,8 @@ N_ECOML C_ECOML N_LENG unknown @end example -@node Sun differences -@appendix Differences between GNU stabs and Sun native stabs +@node Sun Differences +@appendix Differences Between GNU Stabs and Sun Native Stabs @c FIXME: Merge all this stuff into the main body of the document. @@ -3522,8 +3522,8 @@ incremented for each new type defined in the compilation. GNU C stabs use the type number alone, with no source file number. @end itemize -@node Stabs in ELF -@appendix Using stabs with the ELF object file format +@node Stabs In ELF +@appendix Using Stabs With The ELF Object File Format The ELF object file format allows tools to create object files with custom sections containing any arbitrary data. To use stabs in ELF