2 @setfilename stabs.info
7 * Stabs: (stabs). The "stabs" debugging information format.
13 This document describes GNU stabs (debugging symbol tables) in a.out files.
15 Copyright 1992 Free Software Foundation, Inc.
16 Contributed by Cygnus Support. Written by Julia Menapace.
18 Permission is granted to make and distribute verbatim copies of
19 this manual provided the copyright notice and this permission notice
20 are preserved on all copies.
23 Permission is granted to process this file through Tex and print the
24 results, provided the printed document carries copying permission
25 notice identical to this one except for the removal of this paragraph
26 (this paragraph not being relevant to the printed manual).
29 Permission is granted to copy or distribute modified versions of this
30 manual under the terms of the GPL (for which purpose this text may be
31 regarded as a program in the language TeX).
34 @setchapternewpage odd
37 @title The ``stabs'' debug format
38 @author Julia Menapace
39 @author Cygnus Support
42 \def\$#1${{#1}} % Kluge: collect RCS revision info without $...$
43 \xdef\manvers{\$Revision$} % For use in headers, footers too
45 \hfill Cygnus Support\par
47 \hfill \TeX{}info \texinfoversion\par
51 @vskip 0pt plus 1filll
52 Copyright @copyright{} 1992 Free Software Foundation, Inc.
53 Contributed by Cygnus Support.
55 Permission is granted to make and distribute verbatim copies of
56 this manual provided the copyright notice and this permission notice
57 are preserved on all copies.
63 @top The "stabs" representation of debugging information
65 This document describes the GNU stabs debugging format in a.out files.
68 * Overview:: Overview of stabs
69 * Program structure:: Encoding of the structure of the program
71 * Example:: A comprehensive example in C
74 * Symbol tables:: Symbol information in symbol tables
75 * GNU Cplusplus stabs::
78 * Example2.c:: Source code for extended example
79 * Example2.s:: Assembly code for extended example
80 * Quick reference:: Various refernce tables
81 * Expanded reference:: Reference information by stab type
82 * Questions:: Questions and anomolies
83 * xcoff-differences:: Differences between GNU stabs in a.out
84 and GNU stabs in xcoff
85 * Sun-differences:: Differences between GNU stabs and Sun
92 @chapter Overview of stabs
94 @dfn{Stabs} refers to a format for information that describes a program
95 to a debugger. This format was apparently invented by
96 @c FIXME! <<name of inventor>> at
97 the University of California at Berkeley, for the @code{pdx} Pascal
98 debugger; the format has spread widely since then.
101 * Flow:: Overview of debugging information flow
102 * Stabs format:: Overview of stab format
103 * C example:: A simple example in C source
104 * Assembly code:: The simple example at the assembly level
108 @section Overview of debugging information flow
110 The GNU C compiler compiles C source in a @file{.c} file into assembly
111 language in a @file{.s} file, which is translated by the assembler into
112 a @file{.o} file, and then linked with other @file{.o} files and
113 libraries to produce an executable file.
115 With the @samp{-g} option, GCC puts additional debugging information in
116 the @file{.s} file, which is slightly transformed by the assembler and
117 linker, and carried through into the final executable. This debugging
118 information describes features of the source file like line numbers,
119 the types and scopes of variables, and functions, their parameters and
122 For some object file formats, the debugging information is
123 encapsulated in assembler directives known collectively as `stab' (symbol
124 table) directives, interspersed with the generated code. Stabs are
125 the native format for debugging information in the a.out and xcoff
126 object file formats. The GNU tools can also emit stabs in the coff
127 and ecoff object file formats.
129 The assembler adds the information from stabs to the symbol information
130 it places by default in the symbol table and the string table of the
131 @file{.o} file it is building. The linker consolidates the @file{.o}
132 files into one executable file, with one symbol table and one string
133 table. Debuggers use the symbol and string tables in the executable as
134 a source of debugging information about the program.
137 @section Overview of stab format
139 There are three overall formats for stab assembler directives
140 differentiated by the first word of the stab. The name of the directive
141 describes what combination of four possible data fields will follow. It
142 is either @code{.stabs} (string), @code{.stabn} (number), or
145 The overall format of each class of stab is:
148 .stabs "@var{string}",@var{type},0,@var{desc},@var{value}
149 .stabn @var{type},0,@var{desc},@var{value}
150 .stabd @var{type},0,@var{desc}
153 In general, in @code{.stabs} the @var{string} field contains name and type
154 information. For @code{.stabd} the value field is implicit and has the value
155 of the current file location. Otherwise the value field often
156 contains a relocatable address, frame pointer offset, or register
157 number, that maps to the source code element described by the stab.
159 The real key to decoding the meaning of a stab is the number in its type
160 field. Each possible type number defines a different stab type. The
161 stab type further defines the exact interpretation of, and possible
162 values for, any remaining @code{"@var{string}"}, @var{desc}, or
163 @var{value} fields present in the stab. Table A (@pxref{Stab
164 types,,Table A: Symbol types from stabs}) lists in numeric order
165 the possible type field values for stab directives. The reference
166 section that follows Table A describes the meaning of the fields for
167 each stab type in detail. The examples that follow this overview
168 introduce the stab types in terms of the source code elements they
171 For @code{.stabs} the @code{"@var{string}"} field holds the meat of the
172 debugging information. The generally unstructured nature of this field
173 is what makes stabs extensible. For some stab types the string field
174 contains only a name. For other stab types the contents can be a great
177 The overall format is of the @code{"@var{string}"} field is:
180 "@var{name}@r{[}:@var{symbol_descriptor}@r{]}
181 @r{[}@var{type_number}@r{[}=@var{type_descriptor} @r{@dots{}]]}"
184 @var{name} is the name of the symbol represented by the stab.
186 The @var{symbol_descriptor} following the @samp{:} is an alphabetic
187 character that tells more specifically what kind of symbol the stab
188 represents. If the @var{symbol_descriptor} is omitted, but type
189 information follows, then the stab represents a local variable. For a
190 list of symbol_descriptors, see @ref{Symbol descriptors,,Table C: Symbol
193 Type information is either a @var{type_number}, or a
194 @samp{@var{type_number}=}. The @var{type_number} alone is a type
195 reference, referring directly to a type that has already been defined.
197 The @samp{@var{type_number}=} is a type definition, where the number
198 represents a new type which is about to be defined. The type definition
199 may refer to other types by number, and those type numbers may be
200 followed by @samp{=} and nested definitions.
202 In a type definition, if the character that follows the equals sign is
203 non-numeric then it is a @var{type_descriptor}, and tells what kind of
204 type is about to be defined. Any other values following the
205 @var{type_descriptor} vary, depending on the @var{type_descriptor}. If
206 a number follows the @samp{=} then the number is a @var{type_reference}.
207 This is described more thoroughly in the section on types. @xref{Type
208 Descriptors,,Table D: Type Descriptors}, for a list of
209 @var{type_descriptor} values.
211 All this can make the @code{"@var{string}"} field quite long. All
212 versions of GDB, and some versions of DBX, can handle arbitrarily long
213 strings. But many versions of DBX cretinously limit the strings to
214 about 80 characters, so compilers which must work with such DBX's need
215 to split the @code{.stabs} directive into several @code{.stabs}
216 directives. Each stab duplicates exactly all but the
217 @code{"@var{string}"} field. The @code{"@var{string}"} field of the
218 every stab except the last is marked as continued with a
219 double-backslash at the end. Removing the backslashes and concatenating
220 the @code{"@var{string}"} fields of each stab produces the original,
224 @section A simple example in C source
226 To get the flavor of how stabs describe source information for a C
227 program, let's look at the simple program:
232 printf("Hello world");
236 When compiled with @samp{-g}, the program above yields the following
237 @file{.s} file. Line numbers have been added to make it easier to refer
238 to parts of the @file{.s} file in the description of the stabs that
242 @section The simple example at the assembly level
246 2 .stabs "/cygint/s1/users/jcm/play/",100,0,0,Ltext0
247 3 .stabs "hello.c",100,0,0,Ltext0
250 6 .stabs "int:t1=r1;-2147483648;2147483647;",128,0,0,0
251 7 .stabs "char:t2=r2;0;127;",128,0,0,0
252 8 .stabs "long int:t3=r1;-2147483648;2147483647;",128,0,0,0
253 9 .stabs "unsigned int:t4=r1;0;-1;",128,0,0,0
254 10 .stabs "long unsigned int:t5=r1;0;-1;",128,0,0,0
255 11 .stabs "short int:t6=r1;-32768;32767;",128,0,0,0
256 12 .stabs "long long int:t7=r1;0;-1;",128,0,0,0
257 13 .stabs "short unsigned int:t8=r1;0;65535;",128,0,0,0
258 14 .stabs "long long unsigned int:t9=r1;0;-1;",128,0,0,0
259 15 .stabs "signed char:t10=r1;-128;127;",128,0,0,0
260 16 .stabs "unsigned char:t11=r1;0;255;",128,0,0,0
261 17 .stabs "float:t12=r1;4;0;",128,0,0,0
262 18 .stabs "double:t13=r1;8;0;",128,0,0,0
263 19 .stabs "long double:t14=r1;8;0;",128,0,0,0
264 20 .stabs "void:t15=15",128,0,0,0
267 23 .ascii "Hello, world!\12\0"
282 38 sethi %hi(LC0),%o1
283 39 or %o1,%lo(LC0),%o0
294 50 .stabs "main:F1",36,0,0,_main
295 51 .stabn 192,0,0,LBB2
296 52 .stabn 224,0,0,LBE2
299 This simple ``hello world'' example demonstrates several of the stab
300 types used to describe C language source files.
302 @node Program structure
303 @chapter Encoding for the structure of the program
306 * Source file:: The path and name of the source file
313 @section The path and name of the source file
322 The first stabs in the .s file contain the name and path of the source
323 file that was compiled to produce the .s file. This information is
324 contained in two records of stab type N_SO (100).
327 .stabs "path_name", N_SO, NIL, NIL, Code_address_of_program_start
328 .stabs "file_name:", N_SO, NIL, NIL, Code_address_of_program_start
332 2 .stabs "/cygint/s1/users/jcm/play/",100,0,0,Ltext0
333 3 .stabs "hello.c",100,0,0,Ltext0
339 @section Line Numbers
348 The start of source lines is represented by the @code{N_SLINE} (68) stab
352 .stabn N_SLINE, NIL, @var{line}, @var{address}
355 @var{line} is a source line number; @var{address} represents the code
356 address for the start of that source line.
373 @item Symbol Descriptors:
374 @code{f} (local), @code{F} (global)
377 Procedures are described by the @code{N_FUN} stab type. The symbol
378 descriptor for a procedure is @samp{F} if the procedure is globally
379 scoped and @samp{f} if the procedure is static (locally scoped).
381 The @code{N_FUN} stab representing a procedure is located immediately
382 following the code of the procedure. The @code{N_FUN} stab is in turn
383 directly followed by a group of other stabs describing elements of the
384 procedure. These other stabs describe the procedure's parameters, its
385 block local variables and its block structure.
392 The @code{.stabs} entry after this code fragment shows the @var{name} of
393 the procedure (@code{main}); the type descriptor @var{desc} (@code{F},
394 for a global procedure); a reference to the predefined type @code{int}
395 for the return type; and the starting @var{address} of the procedure.
397 Here is an exploded summary (with whitespace introduced for clarity),
398 followed by line 50 of our sample assembly output, which has this form:
402 @var{desc} @r{(global proc @samp{F})}
403 @var{return_type_ref} @r{(int)}
409 50 .stabs "main:F1",36,0,0,_main
412 @node Block Structure
413 @section Block Structure
419 @code{N_LBRAC}, @code{N_RBRAC}
422 The program's block structure is represented by the @code{N_LBRAC} (left
423 brace) and the @code{N_RBRAC} (right brace) stab types. The following code
424 range, which is the body of @code{main}, is labeled with @samp{LBB2:} at the
425 beginning and @samp{LBE2:} at the end.
429 38 sethi %hi(LC0),%o1
430 39 or %o1,%lo(LC0),%o0
438 The @code{N_LBRAC} and @code{N_RBRAC} stabs that describe the block
439 scope of the procedure are located after the @code{N_FUNC} stab that
440 represents the procedure itself. The @code{N_LBRAC} uses the
441 @code{LBB2} label as the code address in its value field, and the
442 @code{N_RBRAC} uses @code{LBE2}.
445 50 .stabs "main:F1",36,0,0,_main
449 .stabn N_LBRAC, NIL, NIL, @var{left-brace-address}
450 .stabn N_RBRAC, NIL, NIL, @var{right-brace-address}
454 51 .stabn 192,0,0,LBB2
455 52 .stabn 224,0,0,LBE2
459 @chapter Simple types
462 * Basic types:: Basic type definitions
463 * Range types:: Range types defined by min and max value
464 * Float "range" types:: Range type defined by size in bytes
468 @section Basic type definitions
475 @item Symbol Descriptor:
479 The basic types for the language are described using the @code{N_LSYM} stab
480 type. They are boilerplate and are emited by the compiler for each
481 compilation unit. Basic type definitions are not always a complete
482 description of the type and are sometimes circular. The debugger
483 recognizes the type anyway, and knows how to read bits as that type.
485 Each language and compiler defines a slightly different set of basic
486 types. In this example we are looking at the basic types for C emited
487 by the GNU compiler targeting the Sun4. Here the basic types are
488 mostly defined as range types.
492 @section Range types defined by min and max value
495 @item Type Descriptor:
499 When defining a range type, if the number after the first semicolon is
500 smaller than the number after the second one, then the two numbers
501 represent the smallest and the largest values in the range.
508 @var{descriptor} @r{(type)}
515 N_LSYM, NIL, NIL, NIL
517 6 .stabs "int:t1=r1;-2147483648;2147483647;",128,0,0,0
518 7 .stabs "char:t2=r2;0;127;",128,0,0,0
521 Here the integer type (@code{1}) is defined as a range of the integer
522 type (@code{1}). Likewise @code{char} is a range of @code{char}. This
523 part of the definition is circular, but at least the high and low bound
524 values of the range hold more information about the type.
526 Here short unsigned int is defined as type number 8 and described as a
527 range of type @code{int}, with a minimum value of 0 and a maximum of 65535.
530 13 .stabs "short unsigned int:t8=r1;0;65535;",128,0,0,0
533 @node Float "range" types
534 @section Range type defined by size in bytes
537 @item Type Descriptor:
541 In a range definition, if the first number after the semicolon is
542 positive and the second is zero, then the type being defined is a
543 floating point type, and the number after the first semicolon is the
544 number of bytes needed to represent the type. Note that this does not
545 provide a way to distinguish 8-byte real floating point types from
546 8-byte complex floating point types.
557 N_LSYM, NIL, NIL, NIL
559 17 .stabs "float:t12=r1;4;0;",128,0,0,0
560 18 .stabs "double:t13=r1;8;0;",128,0,0,0
561 19 .stabs "long double:t14=r1;8;0;",128,0,0,0
564 Cosmically enough, the @code{void} type is defined directly in terms of
574 20 .stabs "void:t15=15",128,0,0,0
579 @chapter A Comprehensive Example in C
581 Now we'll examine a second program, @code{example2}, which builds on the
582 first example to introduce the rest of the stab types, symbol
583 descriptors, and type descriptors used in C.
584 @xref{Example2.c} for the complete @file{.c} source,
585 and @pxref{Example2.s} for the @file{.s} assembly code.
586 This description includes parts of those files.
588 @section Flow of control and nested scopes
594 @code{N_SLINE}, @code{N_LBRAC}, @code{N_RBRAC} (cont.)
597 Consider the body of @code{main}, from @file{example2.c}. It shows more
598 about how @code{N_SLINE}, @code{N_RBRAC}, and @code{N_LBRAC} stabs are used.
602 21 static float s_flap;
604 23 for (times=0; times < s_g_repeat; times++)@{
606 25 printf ("Hello world\n");
611 Here we have a single source line, the @samp{for} line, that generates
612 non-linear flow of control, and non-contiguous code. In this case, an
613 @code{N_SLINE} stab with the same line number proceeds each block of
614 non-contiguous code generated from the same source line.
616 The example also shows nested scopes. The @code{N_LBRAC} and
617 @code{N_LBRAC} stabs that describe block structure are nested in the
618 same order as the corresponding code blocks, those of the for loop
619 inside those for the body of main.
622 This is the label for the @code{N_LBRAC} (left brace) stab marking the
623 start of @code{main}.
630 In the first code range for C source line 23, the @code{for} loop
631 initialize and test, @code{N_SLINE} (68) records the line number:
638 58 .stabn 68,0,23,LM2
642 62 sethi %hi(_s_g_repeat),%o0
644 64 ld [%o0+%lo(_s_g_repeat)],%o0
649 @exdent label for the @code{N_LBRAC} (start block) marking the start of @code{for} loop
652 69 .stabn 68,0,25,LM3
654 71 sethi %hi(LC0),%o1
655 72 or %o1,%lo(LC0),%o0
658 75 .stabn 68,0,26,LM4
661 @exdent label for the @code{N_RBRAC} (end block) stab marking the end of the @code{for} loop
667 Now we come to the second code range for source line 23, the @code{for}
668 loop increment and return. Once again, @code{N_SLINE} (68) records the
672 .stabn, N_SLINE, NIL,
676 78 .stabn 68,0,23,LM5
684 86 .stabn 68,0,27,LM6
687 @exdent label for the @code{N_RBRAC} (end block) stab marking the end of the @code{for} loop
690 89 .stabn 68,0,27,LM7
695 94 .stabs "main:F1",36,0,0,_main
696 95 .stabs "argc:p1",160,0,0,68
697 96 .stabs "argv:p20=*21=*2",160,0,0,72
698 97 .stabs "s_flap:V12",40,0,0,_s_flap.0
699 98 .stabs "times:1",128,0,0,-20
703 Here is an illustration of stabs describing nested scopes. The scope
704 nesting is reflected in the nested bracketing stabs (@code{N_LBRAC},
708 .stabn N_LBRAC,NIL,NIL,
709 @var{block-start-address}
711 99 .stabn 192,0,0,LBB2 ## begin proc label
712 100 .stabs "inner:1",128,0,0,-24
713 101 .stabn 192,0,0,LBB3 ## begin for label
717 @code{N_RBRAC} (224), ``right brace'' ends a lexical block (scope).
720 .stabn N_RBRAC,NIL,NIL,
721 @var{block-end-address}
723 102 .stabn 224,0,0,LBE3 ## end for label
724 103 .stabn 224,0,0,LBE2 ## end proc label
731 * Automatic variables:: locally scoped
733 * Register variables::
734 * Initialized statics::
735 * Un-initialized statics::
739 @node Automatic variables
740 @section Locally scoped automatic variables
747 @item Symbol Descriptor:
752 In addition to describing types, the @code{N_LSYM} stab type also
753 describes locally scoped automatic variables. Refer again to the body
754 of @code{main} in @file{example2.c}. It allocates two automatic
755 variables: @samp{times} is scoped to the body of @code{main}, and
756 @samp{inner} is scoped to the body of the @code{for} loop.
757 @samp{s_flap} is locally scoped but not automatic, and will be discussed
762 21 static float s_flap;
764 23 for (times=0; times < s_g_repeat; times++)@{
766 25 printf ("Hello world\n");
771 The @code{N_LSYM} stab for an automatic variable is located just before the
772 @code{N_LBRAC} stab describing the open brace of the block to which it is
776 @exdent @code{N_LSYM} (128): automatic variable, scoped locally to @code{main}
781 @var{frame-pointer-offset}
783 98 .stabs "times:1",128,0,0,-20
784 99 .stabn 192,0,0,LBB2 ## begin `main' N_LBRAC
786 @exdent @code{N_LSYM} (128): automatic variable, scoped locally to the @code{for} loop
791 @var{frame-pointer-offset}
793 100 .stabs "inner:1",128,0,0,-24
794 101 .stabn 192,0,0,LBB3 ## begin `for' loop N_LBRAC
797 Since the character in the string field following the colon is not a
798 letter, there is no symbol descriptor. This means that the stab
799 describes a local variable, and that the number after the colon is a
800 type reference. In this case it a a reference to the basic type @code{int}.
801 Notice also that the frame pointer offset is negative number for
805 @node Global Variables
806 @section Global Variables
813 @item Symbol Descriptor:
817 Global variables are represented by the @code{N_GSYM} stab type. The symbol
818 descriptor, following the colon in the string field, is @samp{G}. Following
819 the @samp{G} is a type reference or type definition. In this example it is a
820 type reference to the basic C type, @code{char}. The first source line in
828 yields the following stab. The stab immediately precedes the code that
829 allocates storage for the variable it describes.
832 @exdent @code{N_GSYM} (32): global symbol
837 N_GSYM, NIL, NIL, NIL
839 21 .stabs "g_foo:G2",32,0,0,0
846 The address of the variable represented by the @code{N_GSYM} is not contained
847 in the @code{N_GSYM} stab. The debugger gets this information from the
848 external symbol for the global variable.
850 @node Register variables
851 @section Global register variables
858 @item Symbol Descriptor:
862 The following source line defines a global variable, @code{g_bar}, which is
863 explicitly allocated in global register @code{%g5}.
866 2 register int g_bar asm ("%g5");
869 Register variables have their own stab type, @code{N_RSYM}, and their own
870 symbol descriptor, @code{r}. The stab's value field contains the number of
871 the register where the variable data will be stored. Since the
872 variable was not initialized in this compilation unit, the stab is
873 emited at the end of the object file, with the stabs for other
874 uninitialized globals (@code{bcc}).
877 @exdent @code{N_RSYM} (64): register variable
885 133 .stabs "g_bar:r1",64,0,0,5
889 @node Initialized statics
890 @section Initialized static variables
897 @item Symbol Descriptors:
898 @code{S} (file scope), @code{V} (procedure scope)
901 Initialized static variables are represented by the @code{N_STSYM} stab
902 type. The symbol descriptor part of the string field shows if the
903 variable is file scope static (@samp{S}) or procedure scope static
904 (@samp{V}). The source line
907 3 static int s_g_repeat = 2;
911 yields the following code. The stab is located immediately preceding
912 the storage for the variable it represents. Since the variable in
913 this example is file scope static the symbol descriptor is @samp{S}.
916 @exdent @code{N_STSYM} (38): initialized static variable (data seg w/internal linkage)
924 26 .stabs "s_g_repeat:S1",38,0,0,_s_g_repeat
931 @node Un-initialized statics
932 @section Un-initialized static variables
939 @item Symbol Descriptors:
940 @code{S} (file scope), @code{V} (procedure scope)
943 Un-initialized static variables are represented by the @code{N_LCSYM}
944 stab type. The symbol descriptor part of the string shows if the
945 variable is file scope static (@samp{S}) or procedure scope static
946 (@samp{V}). In this example it is procedure scope static. The source
947 line allocating @code{s_flap} immediately follows the open brace for the
948 procedure @code{main}.
952 21 static float s_flap;
955 The code that reserves storage for the variable @code{s_flap} precedes the
956 body of body of @code{main}.
959 39 .reserve _s_flap.0,4,"bss",4
962 But since @code{s_flap} is scoped locally to @code{main}, its stab is
963 located with the other stabs representing symbols local to @code{main}.
964 The stab for @code{s_flap} is located just before the @code{N_LBRAC} for
968 @exdent @code{N_LCSYM} (40): uninitialized static var (BSS seg w/internal linkage)
976 97 .stabs "s_flap:V12",40,0,0,_s_flap.0
977 98 .stabs "times:1",128,0,0,-20
978 99 .stabn 192,0,0,LBB2 # N_LBRAC for main.
981 @c ............................................................
986 The symbol descriptor @samp{p} is used to refer to parameters which are
987 in the arglist. Symbols have symbol type @samp{N_PSYM}. The value of
988 the symbol is the offset relative to the argument list.
990 If the parameter is passed in a register, then the traditional way to do
991 this is to provide two symbols for each argument:
994 .stabs "arg:p1" . . . ; N_PSYM
995 .stabs "arg:r1" . . . ; N_RSYM
998 Debuggers are expected to use the second one to find the value, and the
999 first one to know that it is an argument.
1001 Because this is kind of ugly, some compilers use symbol descriptor
1002 @samp{P} or @samp{R} to indicate an argument which is in a register.
1003 The symbol value is the register number. @samp{P} and @samp{R} mean the
1004 same thing, the difference is that @samp{P} is a GNU invention and
1005 @samp{R} is an IBM (xcoff) invention. As of version 4.9, GDB should
1006 handle either one. Symbol type @samp{C_RPSYM} is used with @samp{R} and
1007 @samp{N_RSYM} is used with @samp{P}.
1009 There is at least one case where GCC uses a @samp{p}/@samp{r} pair
1010 rather than @samp{P}; this is where the argument is passed in the
1011 argument list and then loaded into a register.
1013 On the sparc and hppa, for a @samp{P} symbol whose type is a structure
1014 or union, the register contains the address of the structure. On the
1015 sparc, this is also true of a @samp{p}/@samp{r} pair (using Sun cc) or a
1016 @samp{p} symbol. However, if a (small) structure is really in a
1017 register, @samp{r} is used. And, to top it all off, on the hppa it
1018 might be a structure which was passed on the stack and loaded into a
1019 register and for which there is a @samp{p}/@samp{r} pair! I believe
1020 that symbol descriptor @samp{i} is supposed to deal with this case, but
1021 I don't know details or what compilers or debuggers use it, if any (not
1024 There is another case similar to an argument in a register, which is an
1025 argument which is actually stored as a local variable. Sometimes this
1026 happens when the argument was passed in a register and then the compiler
1027 stores it as a local variable. If possible, the compiler should claim
1028 that it's in a register, but this isn't always done. Some compilers use
1029 the pair of symbols approach described above ("arg:p" followed by
1030 "arg:"); this includes gcc1 (not gcc2) on the sparc when passing a small
1031 structure and gcc2 when the argument type is float and it is passed as a
1032 double and converted to float by the prologue (in the latter case the
1033 type of the "arg:p" symbol is double and the type of the "arg:" symbol
1034 is float). GCC, at least on the 960, uses a single @samp{p} symbol
1035 descriptor for an argument which is stored as a local variable but uses
1036 @samp{N_LSYM} instead of @samp{N_PSYM}. In this case the value of the
1037 symbol is an offset relative to the local variables for that function,
1038 not relative to the arguments (on some machines those are the same
1039 thing, but not on all).
1041 The following are said to go with @samp{N_PSYM}:
1044 "name" -> "param_name:#type"
1045 # -> p (value parameter)
1046 -> i (value parameter by reference, indirect access)
1047 -> v (variable parameter by reference)
1048 -> C (read-only parameter, conformant array bound)
1049 -> x (conformant array value parameter)
1052 -> X (function result variable)
1053 -> b (based variable)
1055 value -> offset from the argument pointer (positive).
1058 As a simple example, the code
1070 .stabs "main:F1",36,0,0,_main ; 36 is N_FUN
1071 .stabs "argc:p1",160,0,0,68 ; 160 is N_PSYM
1072 .stabs "argv:p20=*21=*2",160,0,0,72
1075 The type definition of argv is interesting because it contains several
1076 type definitions. Type 21 is pointer to type 2 (char) and argv (type 20) is
1079 @node Aggregate Types
1080 @chapter Aggregate Types
1082 Now let's look at some variable definitions involving complex types.
1083 This involves understanding better how types are described. In the
1084 examples so far types have been described as references to previously
1085 defined types or defined in terms of subranges of or pointers to
1086 previously defined types. The section that follows will talk about
1087 the various other type descriptors that may follow the = sign in a
1100 @section Array types
1106 @code{N_GSYM}, @code{N_LSYM}
1107 @item Symbol Descriptor:
1109 @item Type Descriptor:
1113 As an example of an array type consider the global variable below.
1116 15 char char_vec[3] = @{'a','b','c'@};
1119 Since the array is a global variable, it is described by the N_GSYM
1120 stab type. The symbol descriptor G, following the colon in stab's
1121 string field, also says the array is a global variable. Following the
1122 G is a definition for type (19) as shown by the equals sign after the
1125 After the equals sign is a type descriptor, a, which says that the type
1126 being defined is an array. Following the type descriptor for an array
1127 is the type of the index, a semicolon, and the type of the array elements.
1129 The type of the index is often a range type, expressed as the letter r
1130 and some parameters. It defines the size of the array. In in the
1131 example below, the range @code{r1;0;2;} defines an index type which is
1132 a subrange of type 1 (integer), with a lower bound of 0 and an upper
1133 bound of 2. This defines the valid range of subscripts of a
1134 three-element C array.
1136 The array definition above generates the assembly language that
1140 @exdent <32> N_GSYM - global variable
1141 @exdent .stabs "name:sym_desc(global)type_def(19)=type_desc(array)
1142 @exdent index_type_ref(range of int from 0 to 2);element_type_ref(char)";
1143 @exdent N_GSYM, NIL, NIL, NIL
1145 32 .stabs "char_vec:G19=ar1;0;2;2",32,0,0,0
1146 33 .global _char_vec
1155 @section Enumerations
1162 @item Symbol Descriptor:
1164 @item Type Descriptor:
1168 The source line below declares an enumeration type. It is defined at
1169 file scope between the bodies of main and s_proc in example2.c.
1170 Because the N_LSYM is located after the N_RBRAC that marks the end of
1171 the previous procedure's block scope, and before the N_FUN that marks
1172 the beginning of the next procedure's block scope, the N_LSYM does not
1173 describe a block local symbol, but a file local one. The source line:
1176 29 enum e_places @{first,second=3,last@};
1180 generates the following stab, located just after the N_RBRAC (close
1181 brace stab) for main. The type definition is in an N_LSYM stab
1182 because type definitions are file scope not global scope.
1185 <128> N_LSYM - local symbol
1186 .stab "name:sym_dec(type)type_def(22)=sym_desc(enum)
1187 enum_name:value(0),enum_name:value(3),enum_name:value(4),;",
1188 N_LSYM, NIL, NIL, NIL
1192 104 .stabs "e_places:T22=efirst:0,second:3,last:4,;",128,0,0,0
1195 The symbol descriptor (T) says that the stab describes a structure,
1196 enumeration, or type tag. The type descriptor e, following the 22= of
1197 the type definition narrows it down to an enumeration type. Following
1198 the e is a list of the elements of the enumeration. The format is
1199 name:value,. The list of elements ends with a ;.
1201 @node Structure tags
1202 @section Structure Tags
1209 @item Symbol Descriptor:
1211 @item Type Descriptor:
1215 The following source code declares a structure tag and defines an
1216 instance of the structure in global scope. Then a typedef equates the
1217 structure tag with a new type. A seperate stab is generated for the
1218 structure tag, the structure typedef, and the structure instance. The
1219 stabs for the tag and the typedef are emited when the definitions are
1220 encountered. Since the structure elements are not initialized, the
1221 stab and code for the structure variable itself is located at the end
1222 of the program in .common.
1228 9 char s_char_vec[8];
1229 10 struct s_tag* s_next;
1232 13 typedef struct s_tag s_typedef;
1235 The structure tag is an N_LSYM stab type because, like the enum, the
1236 symbol is file scope. Like the enum, the symbol descriptor is T, for
1237 enumeration, struct or tag type. The symbol descriptor s following
1238 the 16= of the type definition narrows the symbol type to struct.
1240 Following the struct symbol descriptor is the number of bytes the
1241 struct occupies, followed by a description of each structure element.
1242 The structure element descriptions are of the form name:type, bit
1243 offset from the start of the struct, and number of bits in the
1248 <128> N_LSYM - type definition
1249 .stabs "name:sym_desc(struct tag) Type_def(16)=type_desc(struct type)
1251 elem_name:type_ref(int),bit_offset,field_bits;
1252 elem_name:type_ref(float),bit_offset,field_bits;
1253 elem_name:type_def(17)=type_desc(array)
1254 index_type(range of int from 0 to 7);
1255 element_type(char),bit_offset,field_bits;;",
1258 30 .stabs "s_tag:T16=s20s_int:1,0,32;s_float:12,32,32;
1259 s_char_vec:17=ar1;0;7;2,64,64;s_next:18=*16,128,32;;",128,0,0,0
1262 In this example, two of the structure elements are previously defined
1263 types. For these, the type following the name: part of the element
1264 description is a simple type reference. The other two structure
1265 elements are new types. In this case there is a type definition
1266 embedded after the name:. The type definition for the array element
1267 looks just like a type definition for a standalone array. The s_next
1268 field is a pointer to the same kind of structure that the field is an
1269 element of. So the definition of structure type 16 contains an type
1270 definition for an element which is a pointer to type 16.
1280 @item Symbol Descriptor:
1284 Here is the stab for the typedef equating the structure tag with a
1288 <128> N_LSYM - type definition
1289 .stabs "name:sym_desc(type name)type_ref(struct_tag)",N_LSYM,NIL,NIL,NIL
1293 31 .stabs "s_typedef:t16",128,0,0,0
1296 And here is the code generated for the structure variable.
1299 <32> N_GSYM - global symbol
1300 .stabs "name:sym_desc(global)type_ref(struct_tag)",N_GSYM,NIL,NIL,NIL
1304 136 .stabs "g_an_s:G16",32,0,0,0
1305 137 .common _g_an_s,20,"bss"
1308 Notice that the structure tag has the same type number as the typedef
1309 for the structure tag. It is impossible to distinguish between a
1310 variable of the struct type and one of its typedef by looking at the
1311 debugging information.
1322 @item Symbol Descriptor:
1324 @item Type Descriptor:
1328 Next let's look at unions. In example2 this union type is declared
1329 locally to a procedure and an instance of the union is defined.
1339 This code generates a stab for the union tag and a stab for the union
1340 variable. Both use the N_LSYM stab type. Since the union variable is
1341 scoped locally to the procedure in which it is defined, its stab is
1342 located immediately preceding the N_LBRAC for the procedure's block
1345 The stab for the union tag, however is located preceding the code for
1346 the procedure in which it is defined. The stab type is N_LSYM. This
1347 would seem to imply that the union type is file scope, like the struct
1348 type s_tag. This is not true. The contents and position of the stab
1349 for u_type do not convey any infomation about its procedure local
1354 .stabs "name:sym_desc(union tag)type_def(22)=type_desc(union)
1356 elem_name:type_ref(int),bit_offset(0),bit_size(32);
1357 elem_name:type_ref(float),bit_offset(0),bit_size(32);
1358 elem_name:type_ref(ptr to char),bit_offset(0),bit_size(32);;"
1359 N_LSYM, NIL, NIL, NIL
1363 105 .stabs "u_tag:T23=u4u_int:1,0,32;u_float:12,0,32;u_char:21,0,32;;",
1367 The symbol descriptor, T, following the name: means that the stab
1368 describes an enumeration, struct or type tag. The type descriptor u,
1369 following the 23= of the type definition, narrows it down to a union
1370 type definition. Following the u is the number of bytes in the union.
1371 After that is a list of union element descriptions. Their format is
1372 name:type, bit offset into the union, and number of bytes for the
1375 The stab for the union variable follows. Notice that the frame
1376 pointer offset for local variables is negative.
1379 <128> N_LSYM - local variable (with no symbol descriptor)
1380 .stabs "name:type_ref(u_tag)", N_LSYM, NIL, NIL, frame_ptr_offset
1384 130 .stabs "an_u:23",128,0,0,-20
1387 @node Function types
1388 @section Function types
1394 The last type descriptor in C which remains to be described is used
1395 for function types. Consider the following source line defining a
1396 global function pointer.
1402 It generates the following code. Since the variable is not
1403 initialized, the code is located in the common area at the end of the
1407 <32> N_GSYM - global variable
1408 .stabs "name:sym_desc(global)type_def(24)=ptr_to(25)=
1409 type_def(func)type_ref(int)
1413 134 .stabs "g_pf:G24=*25=f1",32,0,0,0
1414 135 .common _g_pf,4,"bss"
1417 Since the variable is global, the stab type is N_GSYM and the symbol
1418 descriptor is G. The variable defines a new type, 24, which is a
1419 pointer to another new type, 25, which is defined as a function
1423 @chapter Symbol information in symbol tables
1425 This section examines more closely the format of symbol table entries
1426 and how stab assembler directives map to them. It also describes what
1427 transformations the assembler and linker make on data from stabs.
1429 Each time the assembler encounters a stab in its input file it puts
1430 each field of the stab into corresponding fields in a symbol table
1431 entry of its output file. If the stab contains a string field, the
1432 symbol table entry for that stab points to a string table entry
1433 containing the string data from the stab. Assembler labels become
1434 relocatable addresses. Symbol table entries in a.out have the format:
1437 struct internal_nlist @{
1438 unsigned long n_strx; /* index into string table of name */
1439 unsigned char n_type; /* type of symbol */
1440 unsigned char n_other; /* misc info (usually empty) */
1441 unsigned short n_desc; /* description field */
1442 bfd_vma n_value; /* value of symbol */
1446 For .stabs directives, the n_strx field holds the character offset
1447 from the start of the string table to the string table entry
1448 containing the "string" field. For other classes of stabs (.stabn and
1449 .stabd) this field is null.
1451 Symbol table entries with n_type fields containing a value greater or
1452 equal to 0x20 originated as stabs generated by the compiler (with one
1453 random exception). Those with n_type values less than 0x20 were
1454 placed in the symbol table of the executable by the assembler or the
1457 The linker concatenates object files and does fixups of externally
1458 defined symbols. You can see the transformations made on stab data by
1459 the assembler and linker by examining the symbol table after each pass
1460 of the build, first the assemble and then the link.
1462 To do this use nm with the -ap options. This dumps the symbol table,
1463 including debugging information, unsorted. For stab entries the
1464 columns are: value, other, desc, type, string. For assembler and
1465 linker symbols, the columns are: value, type, string.
1467 There are a few important things to notice about symbol tables. Where
1468 the value field of a stab contains a frame pointer offset, or a
1469 register number, that value is unchanged by the rest of the build.
1471 Where the value field of a stab contains an assembly language label,
1472 it is transformed by each build step. The assembler turns it into a
1473 relocatable address and the linker turns it into an absolute address.
1474 This source line defines a static variable at file scope:
1477 3 static int s_g_repeat
1481 The following stab describes the symbol.
1484 26 .stabs "s_g_repeat:S1",38,0,0,_s_g_repeat
1488 The assembler transforms the stab into this symbol table entry in the
1489 @file{.o} file. The location is expressed as a data segment offset.
1492 21 00000084 - 00 0000 STSYM s_g_repeat:S1
1496 in the symbol table entry from the executable, the linker has made the
1497 relocatable address absolute.
1500 22 0000e00c - 00 0000 STSYM s_g_repeat:S1
1503 Stabs for global variables do not contain location information. In
1504 this case the debugger finds location information in the assembler or
1505 linker symbol table entry describing the variable. The source line:
1515 21 .stabs "g_foo:G2",32,0,0,0
1518 The variable is represented by the following two symbol table entries
1519 in the object file. The first one originated as a stab. The second
1520 one is an external symbol. The upper case D signifies that the n_type
1521 field of the symbol table contains 7, N_DATA with local linkage (see
1522 Table B). The value field following the file's line number is empty
1523 for the stab entry. For the linker symbol it contains the
1524 rellocatable address corresponding to the variable.
1527 19 00000000 - 00 0000 GSYM g_foo:G2
1528 20 00000080 D _g_foo
1532 These entries as transformed by the linker. The linker symbol table
1533 entry now holds an absolute address.
1536 21 00000000 - 00 0000 GSYM g_foo:G2
1538 215 0000e008 D _g_foo
1541 @node GNU Cplusplus stabs
1542 @chapter GNU C++ stabs
1545 * Basic Cplusplus types::
1548 * Methods:: Method definition
1550 * Method Modifiers:: (const, volatile, const volatile)
1553 * Virtual Base Classes::
1558 @subsection Symbol descriptors added for C++ descriptions:
1561 P - register parameter.
1564 @subsection type descriptors added for C++ descriptions
1568 method type (two ## if minimal debug)
1575 @node Basic Cplusplus types
1576 @section Basic types for C++
1578 << the examples that follow are based on a01.C >>
1581 C++ adds two more builtin types to the set defined for C. These are
1582 the unknown type and the vtable record type. The unknown type, type
1583 16, is defined in terms of itself like the void type.
1585 The vtable record type, type 17, is defined as a structure type and
1586 then as a structure tag. The structure has four fields, delta, index,
1587 pfn, and delta2. pfn is the function pointer.
1589 << In boilerplate $vtbl_ptr_type, what are the fields delta,
1590 index, and delta2 used for? >>
1592 This basic type is present in all C++ programs even if there are no
1593 virtual methods defined.
1596 .stabs "struct_name:sym_desc(type)type_def(17)=type_desc(struct)struct_bytes(8)
1597 elem_name(delta):type_ref(short int),bit_offset(0),field_bits(16);
1598 elem_name(index):type_ref(short int),bit_offset(16),field_bits(16);
1599 elem_name(pfn):type_def(18)=type_desc(ptr to)type_ref(void),
1600 bit_offset(32),field_bits(32);
1601 elem_name(delta2):type_def(short int);bit_offset(32),field_bits(16);;"
1606 .stabs "$vtbl_ptr_type:t17=s8
1607 delta:6,0,16;index:6,16,16;pfn:18=*15,32,32;delta2:6,32,16;;"
1612 .stabs "name:sym_dec(struct tag)type_ref($vtbl_ptr_type)",N_LSYM,NIL,NIL,NIL
1616 .stabs "$vtbl_ptr_type:T17",128,0,0,0
1619 @node Simple classes
1620 @section Simple class definition
1622 The stabs describing C++ language features are an extension of the
1623 stabs describing C. Stabs representing C++ class types elaborate
1624 extensively on the stab format used to describe structure types in C.
1625 Stabs representing class type variables look just like stabs
1626 representing C language variables.
1628 Consider the following very simple class definition.
1634 int Ameth(int in, char other);
1638 The class baseA is represented by two stabs. The first stab describes
1639 the class as a structure type. The second stab describes a structure
1640 tag of the class type. Both stabs are of stab type N_LSYM. Since the
1641 stab is not located between an N_FUN and a N_LBRAC stab this indicates
1642 that the class is defined at file scope. If it were, then the N_LSYM
1643 would signify a local variable.
1645 A stab describing a C++ class type is similar in format to a stab
1646 describing a C struct, with each class member shown as a field in the
1647 structure. The part of the struct format describing fields is
1648 expanded to include extra information relevent to C++ class members.
1649 In addition, if the class has multiple base classes or virtual
1650 functions the struct format outside of the field parts is also
1653 In this simple example the field part of the C++ class stab
1654 representing member data looks just like the field part of a C struct
1655 stab. The section on protections describes how its format is
1656 sometimes extended for member data.
1658 The field part of a C++ class stab representing a member function
1659 differs substantially from the field part of a C struct stab. It
1660 still begins with `name:' but then goes on to define a new type number
1661 for the member function, describe its return type, its argument types,
1662 its protection level, any qualifiers applied to the method definition,
1663 and whether the method is virtual or not. If the method is virtual
1664 then the method description goes on to give the vtable index of the
1665 method, and the type number of the first base class defining the
1668 When the field name is a method name it is followed by two colons
1669 rather than one. This is followed by a new type definition for the
1670 method. This is a number followed by an equal sign and then the
1671 symbol descriptor `##', indicating a method type. This is followed by
1672 a type reference showing the return type of the method and a
1675 The format of an overloaded operator method name differs from that
1676 of other methods. It is "op$::XXXX." where XXXX is the operator name
1677 such as + or +=. The name ends with a period, and any characters except
1678 the period can occur in the XXXX string.
1680 The next part of the method description represents the arguments to
1681 the method, preceeded by a colon and ending with a semi-colon. The
1682 types of the arguments are expressed in the same way argument types
1683 are expressed in C++ name mangling. In this example an int and a char
1686 This is followed by a number, a letter, and an asterisk or period,
1687 followed by another semicolon. The number indicates the protections
1688 that apply to the member function. Here the 2 means public. The
1689 letter encodes any qualifier applied to the method definition. In
1690 this case A means that it is a normal function definition. The dot
1691 shows that the method is not virtual. The sections that follow
1692 elaborate further on these fields and describe the additional
1693 information present for virtual methods.
1697 .stabs "class_name:sym_desc(type)type_def(20)=type_desc(struct)struct_bytes(4)
1698 field_name(Adat):type(int),bit_offset(0),field_bits(32);
1700 method_name(Ameth)::type_def(21)=type_desc(method)return_type(int);
1701 :arg_types(int char);
1702 protection(public)qualifier(normal)virtual(no);;"
1707 .stabs "baseA:t20=s4Adat:1,0,32;Ameth::21=##1;:ic;2A.;;",128,0,0,0
1709 .stabs "class_name:sym_desc(struct tag)",N_LSYM,NIL,NIL,NIL
1711 .stabs "baseA:T20",128,0,0,0
1714 @node Class instance
1715 @section Class instance
1717 As shown above, describing even a simple C++ class definition is
1718 accomplished by massively extending the stab format used in C to
1719 describe structure types. However, once the class is defined, C stabs
1720 with no modifications can be used to describe class instances. The
1730 yields the following stab describing the class instance. It looks no
1731 different from a standard C stab describing a local variable.
1734 .stabs "name:type_ref(baseA)", N_LSYM, NIL, NIL, frame_ptr_offset
1738 .stabs "AbaseA:20",128,0,0,-20
1742 @section Method defintion
1744 The class definition shown above declares Ameth. The C++ source below
1749 baseA::Ameth(int in, char other)
1756 This method definition yields three stabs following the code of the
1757 method. One stab describes the method itself and following two
1758 describe its parameters. Although there is only one formal argument
1759 all methods have an implicit argument which is the `this' pointer.
1760 The `this' pointer is a pointer to the object on which the method was
1761 called. Note that the method name is mangled to encode the class name
1762 and argument types. << Name mangling is not described by this
1763 document - Is there already such a doc? >>
1766 .stabs "name:symbol_desriptor(global function)return_type(int)",
1767 N_FUN, NIL, NIL, code_addr_of_method_start
1769 .stabs "Ameth__5baseAic:F1",36,0,0,_Ameth__5baseAic
1772 Here is the stab for the `this' pointer implicit argument. The name
1773 of the `this' pointer is always `this.' Type 19, the `this' pointer is
1774 defined as a pointer to type 20, baseA, but a stab defining baseA has
1775 not yet been emited. Since the compiler knows it will be emited
1776 shortly, here it just outputs a cross reference to the undefined
1777 symbol, by prefixing the symbol name with xs.
1780 .stabs "name:sym_desc(register param)type_def(19)=
1781 type_desc(ptr to)type_ref(baseA)=
1782 type_desc(cross-reference to)baseA:",N_RSYM,NIL,NIL,register_number
1784 .stabs "this:P19=*20=xsbaseA:",64,0,0,8
1787 The stab for the explicit integer argument looks just like a parameter
1788 to a C function. The last field of the stab is the offset from the
1789 argument pointer, which in most systems is the same as the frame
1793 .stabs "name:sym_desc(value parameter)type_ref(int)",
1794 N_PSYM,NIL,NIL,offset_from_arg_ptr
1796 .stabs "in:p1",160,0,0,72
1799 << The examples that follow are based on A1.C >>
1802 @section Protections
1805 In the simple class definition shown above all member data and
1806 functions were publicly accessable. The example that follows
1807 contrasts public, protected and privately accessable fields and shows
1808 how these protections are encoded in C++ stabs.
1810 Protections for class member data are signified by two characters
1811 embeded in the stab defining the class type. These characters are
1812 located after the name: part of the string. /0 means private, /1
1813 means protected, and /2 means public. If these characters are omited
1814 this means that the member is public. The following C++ source:
1828 generates the following stab to describe the class type all_data.
1831 .stabs "class_name:sym_desc(type)type_def(19)=type_desc(struct)struct_bytes
1832 data_name:/protection(private)type_ref(int),bit_offset,num_bits;
1833 data_name:/protection(protected)type_ref(char),bit_offset,num_bits;
1834 data_name:(/num omited, private)type_ref(float),bit_offset,num_bits;;"
1839 .stabs "all_data:t19=s12
1840 priv_dat:/01,0,32;prot_dat:/12,32,8;pub_dat:12,64,32;;",128,0,0,0
1843 Protections for member functions are signified by one digit embeded in
1844 the field part of the stab describing the method. The digit is 0 if
1845 private, 1 if protected and 2 if public. Consider the C++ class
1849 class all_methods @{
1851 int priv_meth(int in)@{return in;@};
1853 char protMeth(char in)@{return in;@};
1855 float pubMeth(float in)@{return in;@};
1859 It generates the following stab. The digit in question is to the left
1860 of an `A' in each case. Notice also that in this case two symbol
1861 descriptors apply to the class name struct tag and struct type.
1864 .stabs "class_name:sym_desc(struct tag&type)type_def(21)=
1865 sym_desc(struct)struct_bytes(1)
1866 meth_name::type_def(22)=sym_desc(method)returning(int);
1867 :args(int);protection(private)modifier(normal)virtual(no);
1868 meth_name::type_def(23)=sym_desc(method)returning(char);
1869 :args(char);protection(protected)modifier(normal)virual(no);
1870 meth_name::type_def(24)=sym_desc(method)returning(float);
1871 :args(float);protection(public)modifier(normal)virtual(no);;",
1876 .stabs "all_methods:Tt21=s1priv_meth::22=##1;:i;0A.;protMeth::23=##2;:c;1A.;
1877 pubMeth::24=##12;:f;2A.;;",128,0,0,0
1880 @node Method Modifiers
1881 @section Method Modifiers (const, volatile, const volatile)
1885 In the class example described above all the methods have the normal
1886 modifier. This method modifier information is located just after the
1887 protection information for the method. This field has four possible
1888 character values. Normal methods use A, const methods use B, volatile
1889 methods use C, and const volatile methods use D. Consider the class
1895 int ConstMeth (int arg) const @{ return arg; @};
1896 char VolatileMeth (char arg) volatile @{ return arg; @};
1897 float ConstVolMeth (float arg) const volatile @{return arg; @};
1901 This class is described by the following stab:
1904 .stabs "class(A):sym_desc(struct)type_def(20)=type_desc(struct)struct_bytes(1)
1905 meth_name(ConstMeth)::type_def(21)sym_desc(method)
1906 returning(int);:arg(int);protection(public)modifier(const)virtual(no);
1907 meth_name(VolatileMeth)::type_def(22)=sym_desc(method)
1908 returning(char);:arg(char);protection(public)modifier(volatile)virt(no)
1909 meth_name(ConstVolMeth)::type_def(23)=sym_desc(method)
1910 returning(float);:arg(float);protection(public)modifer(const volatile)
1911 virtual(no);;", @dots{}
1915 .stabs "A:T20=s1ConstMeth::21=##1;:i;2B.;VolatileMeth::22=##2;:c;2C.;
1916 ConstVolMeth::23=##12;:f;2D.;;",128,0,0,0
1919 @node Virtual Methods
1920 @section Virtual Methods
1922 << The following examples are based on a4.C >>
1924 The presence of virtual methods in a class definition adds additional
1925 data to the class description. The extra data is appended to the
1926 description of the virtual method and to the end of the class
1927 description. Consider the class definition below:
1933 virtual int A_virt (int arg) @{ return arg; @};
1937 This results in the stab below describing class A. It defines a new
1938 type (20) which is an 8 byte structure. The first field of the class
1939 struct is Adat, an integer, starting at structure offset 0 and
1942 The second field in the class struct is not explicitly defined by the
1943 C++ class definition but is implied by the fact that the class
1944 contains a virtual method. This field is the vtable pointer. The
1945 name of the vtable pointer field starts with $vf and continues with a
1946 type reference to the class it is part of. In this example the type
1947 reference for class A is 20 so the name of its vtable pointer field is
1948 $vf20, followed by the usual colon.
1950 Next there is a type definition for the vtable pointer type (21).
1951 This is in turn defined as a pointer to another new type (22).
1953 Type 22 is the vtable itself, which is defined as an array, indexed by
1954 a range of integers between 0 and 1, and whose elements are of type
1955 17. Type 17 was the vtable record type defined by the boilerplate C++
1956 type definitions, as shown earlier.
1958 The bit offset of the vtable pointer field is 32. The number of bits
1959 in the field are not specified when the field is a vtable pointer.
1961 Next is the method definition for the virtual member function A_virt.
1962 Its description starts out using the same format as the non-virtual
1963 member functions described above, except instead of a dot after the
1964 `A' there is an asterisk, indicating that the function is virtual.
1965 Since is is virtual some addition information is appended to the end
1966 of the method description.
1968 The first number represents the vtable index of the method. This is a
1969 32 bit unsigned number with the high bit set, followed by a
1972 The second number is a type reference to the first base class in the
1973 inheritence hierarchy defining the virtual member function. In this
1974 case the class stab describes a base class so the virtual function is
1975 not overriding any other definition of the method. Therefore the
1976 reference is to the type number of the class that the stab is
1979 This is followed by three semi-colons. One marks the end of the
1980 current sub-section, one marks the end of the method field, and the
1981 third marks the end of the struct definition.
1983 For classes containing virtual functions the very last section of the
1984 string part of the stab holds a type reference to the first base
1985 class. This is preceeded by `~%' and followed by a final semi-colon.
1988 .stabs "class_name(A):type_def(20)=sym_desc(struct)struct_bytes(8)
1989 field_name(Adat):type_ref(int),bit_offset(0),field_bits(32);
1990 field_name(A virt func ptr):type_def(21)=type_desc(ptr to)type_def(22)=
1991 sym_desc(array)index_type_ref(range of int from 0 to 1);
1992 elem_type_ref(vtbl elem type),
1994 meth_name(A_virt)::typedef(23)=sym_desc(method)returning(int);
1995 :arg_type(int),protection(public)normal(yes)virtual(yes)
1996 vtable_index(1);class_first_defining(A);;;~%first_base(A);",
2001 .stabs "A:t20=s8Adat:1,0,32;$vf20:21=*22=ar1;0;1;17,32;A_virt::23=##1;:i;2A*-2147483647;20;;;~%20;",128,0,0,0
2005 @section Inheritence
2007 Stabs describing C++ derived classes include additional sections that
2008 describe the inheritence hierarchy of the class. A derived class stab
2009 also encodes the number of base classes. For each base class it tells
2010 if the base class is virtual or not, and if the inheritence is private
2011 or public. It also gives the offset into the object of the portion of
2012 the object corresponding to each base class.
2014 This additional information is embeded in the class stab following the
2015 number of bytes in the struct. First the number of base classes
2016 appears bracketed by an exclamation point and a comma.
2018 Then for each base type there repeats a series: two digits, a number,
2019 a comma, another number, and a semi-colon.
2021 The first of the two digits is 1 if the base class is virtual and 0 if
2022 not. The second digit is 2 if the derivation is public and 0 if not.
2024 The number following the first two digits is the offset from the start
2025 of the object to the part of the object pertaining to the base class.
2027 After the comma, the second number is a type_descriptor for the base
2028 type. Finally a semi-colon ends the series, which repeats for each
2031 The source below defines three base classes A, B, and C and the
2039 virtual int A_virt (int arg) @{ return arg; @};
2045 virtual int B_virt (int arg) @{return arg; @};
2051 virtual int C_virt (int arg) @{return arg; @};
2054 class D : A, virtual B, public C @{
2057 virtual int A_virt (int arg ) @{ return arg+1; @};
2058 virtual int B_virt (int arg) @{ return arg+2; @};
2059 virtual int C_virt (int arg) @{ return arg+3; @};
2060 virtual int D_virt (int arg) @{ return arg; @};
2064 Class stabs similar to the ones described earlier are generated for
2067 @c FIXME!!! the linebreaks in the following example probably make the
2068 @c examples literally unusable, but I don't know any other way to get
2069 @c them on the page.
2071 .stabs "A:T20=s8Adat:1,0,32;$vf20:21=*22=ar1;0;1;17,32;
2072 A_virt::23=##1;:i;2A*-2147483647;20;;;~%20;",128,0,0,0
2074 .stabs "B:Tt25=s8Bdat:1,0,32;$vf25:21,32;B_virt::26=##1;
2075 :i;2A*-2147483647;25;;;~%25;",128,0,0,0
2077 .stabs "C:Tt28=s8Cdat:1,0,32;$vf28:21,32;C_virt::29=##1;
2078 :i;2A*-2147483647;28;;;~%28;",128,0,0,0
2081 In the stab describing derived class D below, the information about
2082 the derivation of this class is encoded as follows.
2085 .stabs "derived_class_name:symbol_descriptors(struct tag&type)=
2086 type_descriptor(struct)struct_bytes(32)!num_bases(3),
2087 base_virtual(no)inheritence_public(no)base_offset(0),
2088 base_class_type_ref(A);
2089 base_virtual(yes)inheritence_public(no)base_offset(NIL),
2090 base_class_type_ref(B);
2091 base_virtual(no)inheritence_public(yes)base_offset(64),
2092 base_class_type_ref(C); @dots{}
2095 @c FIXME! fake linebreaks.
2097 .stabs "D:Tt31=s32!3,000,20;100,25;0264,28;$vb25:24,128;Ddat:
2098 1,160,32;A_virt::32=##1;:i;2A*-2147483647;20;;B_virt:
2099 :32:i;2A*-2147483647;25;;C_virt::32:i;2A*-2147483647;
2100 28;;D_virt::32:i;2A*-2147483646;31;;;~%20;",128,0,0,0
2103 @node Virtual Base Classes
2104 @section Virtual Base Classes
2106 A derived class object consists of a concatination in memory of the
2107 data areas defined by each base class, starting with the leftmost and
2108 ending with the rightmost in the list of base classes. The exception
2109 to this rule is for virtual inheritence. In the example above, class
2110 D inherits virtually from base class B. This means that an instance
2111 of a D object will not contain it's own B part but merely a pointer to
2112 a B part, known as a virtual base pointer.
2114 In a derived class stab, the base offset part of the derivation
2115 information, described above, shows how the base class parts are
2116 ordered. The base offset for a virtual base class is always given as
2117 0. Notice that the base offset for B is given as 0 even though B is
2118 not the first base class. The first base class A starts at offset 0.
2120 The field information part of the stab for class D describes the field
2121 which is the pointer to the virtual base class B. The vbase pointer
2122 name is $vb followed by a type reference to the virtual base class.
2123 Since the type id for B in this example is 25, the vbase pointer name
2126 @c FIXME!! fake linebreaks below
2128 .stabs "D:Tt31=s32!3,000,20;100,25;0264,28;$vb25:24,128;Ddat:1,
2129 160,32;A_virt::32=##1;:i;2A*-2147483647;20;;B_virt::32:i;
2130 2A*-2147483647;25;;C_virt::32:i;2A*-2147483647;28;;D_virt:
2131 :32:i;2A*-2147483646;31;;;~%20;",128,0,0,0
2134 Following the name and a semicolon is a type reference describing the
2135 type of the virtual base class pointer, in this case 24. Type 24 was
2136 defined earlier as the type of the B class `this` pointer. The
2137 `this' pointer for a class is a pointer to the class type.
2140 .stabs "this:P24=*25=xsB:",64,0,0,8
2143 Finally the field offset part of the vbase pointer field description
2144 shows that the vbase pointer is the first field in the D object,
2145 before any data fields defined by the class. The layout of a D class
2146 object is a follows, Adat at 0, the vtable pointer for A at 32, Cdat
2147 at 64, the vtable pointer for C at 96, the virtual ase pointer for B
2148 at 128, and Ddat at 160.
2151 @node Static Members
2152 @section Static Members
2154 The data area for a class is a concatenation of the space used by the
2155 data members of the class. If the class has virtual methods, a vtable
2156 pointer follows the class data. The field offset part of each field
2157 description in the class stab shows this ordering.
2159 << How is this reflected in stabs? See Cygnus bug #677 for some info. >>
2162 @appendix Example2.c - source code for extended example
2166 2 register int g_bar asm ("%g5");
2167 3 static int s_g_repeat = 2;
2173 9 char s_char_vec[8];
2174 10 struct s_tag* s_next;
2177 13 typedef struct s_tag s_typedef;
2179 15 char char_vec[3] = @{'a','b','c'@};
2181 17 main (argc, argv)
2185 21 static float s_flap;
2187 23 for (times=0; times < s_g_repeat; times++)@{
2189 25 printf ("Hello world\n");
2193 29 enum e_places @{first,second=3,last@};
2195 31 static s_proc (s_arg, s_ptr_arg, char_vec)
2197 33 s_typedef* s_ptr_arg;
2211 @appendix Example2.s - assembly code for extended example
2215 2 .stabs "/cygint/s1/users/jcm/play/",100,0,0,Ltext0
2216 3 .stabs "example2.c",100,0,0,Ltext0
2219 6 .stabs "int:t1=r1;-2147483648;2147483647;",128,0,0,0
2220 7 .stabs "char:t2=r2;0;127;",128,0,0,0
2221 8 .stabs "long int:t3=r1;-2147483648;2147483647;",128,0,0,0
2222 9 .stabs "unsigned int:t4=r1;0;-1;",128,0,0,0
2223 10 .stabs "long unsigned int:t5=r1;0;-1;",128,0,0,0
2224 11 .stabs "short int:t6=r1;-32768;32767;",128,0,0,0
2225 12 .stabs "long long int:t7=r1;0;-1;",128,0,0,0
2226 13 .stabs "short unsigned int:t8=r1;0;65535;",128,0,0,0
2227 14 .stabs "long long unsigned int:t9=r1;0;-1;",128,0,0,0
2228 15 .stabs "signed char:t10=r1;-128;127;",128,0,0,0
2229 16 .stabs "unsigned char:t11=r1;0;255;",128,0,0,0
2230 17 .stabs "float:t12=r1;4;0;",128,0,0,0
2231 18 .stabs "double:t13=r1;8;0;",128,0,0,0
2232 19 .stabs "long double:t14=r1;8;0;",128,0,0,0
2233 20 .stabs "void:t15=15",128,0,0,0
2234 21 .stabs "g_foo:G2",32,0,0,0
2239 26 .stabs "s_g_repeat:S1",38,0,0,_s_g_repeat
2243 @c FIXME! fake linebreak in line 30
2244 30 .stabs "s_tag:T16=s20s_int:1,0,32;s_float:12,32,32;s_char_vec:
2245 17=ar1;0;7;2,64,64;s_next:18=*16,128,32;;",128,0,0,0
2246 31 .stabs "s_typedef:t16",128,0,0,0
2247 32 .stabs "char_vec:G19=ar1;0;2;2",32,0,0,0
2248 33 .global _char_vec
2254 39 .reserve _s_flap.0,4,"bss",4
2258 43 .ascii "Hello world\12\0"
2263 48 .stabn 68,0,20,LM1
2266 51 save %sp,-144,%sp
2273 58 .stabn 68,0,23,LM2
2277 62 sethi %hi(_s_g_repeat),%o0
2279 64 ld [%o0+%lo(_s_g_repeat)],%o0
2284 69 .stabn 68,0,25,LM3
2286 71 sethi %hi(LC0),%o1
2287 72 or %o1,%lo(LC0),%o0
2290 75 .stabn 68,0,26,LM4
2293 78 .stabn 68,0,23,LM5
2301 86 .stabn 68,0,27,LM6
2304 89 .stabn 68,0,27,LM7
2309 94 .stabs "main:F1",36,0,0,_main
2310 95 .stabs "argc:p1",160,0,0,68
2311 96 .stabs "argv:p20=*21=*2",160,0,0,72
2312 97 .stabs "s_flap:V12",40,0,0,_s_flap.0
2313 98 .stabs "times:1",128,0,0,-20
2314 99 .stabn 192,0,0,LBB2
2315 100 .stabs "inner:1",128,0,0,-24
2316 101 .stabn 192,0,0,LBB3
2317 102 .stabn 224,0,0,LBE3
2318 103 .stabn 224,0,0,LBE2
2319 104 .stabs "e_places:T22=efirst:0,second:3,last:4,;",128,0,0,0
2320 @c FIXME: fake linebreak in line 105
2321 105 .stabs "u_tag:T23=u4u_int:1,0,32;u_float:12,0,32;u_char:21,0,32;;",
2326 109 .stabn 68,0,35,LM8
2329 112 save %sp,-120,%sp
2335 118 .stabn 68,0,41,LM9
2338 121 .stabn 68,0,41,LM10
2343 126 .stabs "s_proc:f1",36,0,0,_s_proc
2344 127 .stabs "s_arg:p16",160,0,0,0
2345 128 .stabs "s_ptr_arg:p18",160,0,0,72
2346 129 .stabs "char_vec:p21",160,0,0,76
2347 130 .stabs "an_u:23",128,0,0,-20
2348 131 .stabn 192,0,0,LBB4
2349 132 .stabn 224,0,0,LBE4
2350 133 .stabs "g_bar:r1",64,0,0,5
2351 134 .stabs "g_pf:G24=*25=f1",32,0,0,0
2352 135 .common _g_pf,4,"bss"
2353 136 .stabs "g_an_s:G16",32,0,0,0
2354 137 .common _g_an_s,20,"bss"
2358 @node Quick reference
2359 @appendix Quick reference
2362 * Stab types:: Table A: Symbol types from stabs
2363 * Assembler types:: Table B: Symbol types from assembler and linker
2364 * Symbol descriptors:: Table C
2365 * Type Descriptors:: Table D
2369 @section Table A: Symbol types from stabs
2371 Table A lists stab types sorted by type number. Stab type numbers are
2372 32 and greater. This is the full list of stab numbers, including stab
2373 types that are used in languages other than C.
2375 The #define names for these stab types are defined in:
2376 devo/include/aout/stab.def
2379 type type #define used to describe
2380 dec hex name source program feature
2381 ------------------------------------------------
2382 32 0x20 N_GYSM global symbol
2383 34 0X22 N_FNAME function name (for BSD Fortran)
2384 36 0x24 N_FUN function name or text segment variable for C
2385 38 0x26 N_STSYM static symbol (data segment w/internal linkage)
2386 40 0x28 N_LCSYM .lcomm symbol(BSS-seg variable w/internal linkage)
2387 42 0x2a N_MAIN Name of main routine (not used in C)
2388 48 0x30 N_PC global symbol (for Pascal)
2389 50 0x32 N_NSYMS number of symbols (according to Ultrix V4.0)
2390 52 0x34 N_NOMAP no DST map for sym (according to Ultrix V4.0)
2391 64 0x40 N_RSYM register variable
2392 66 0x42 N_M2C Modula-2 compilation unit
2393 68 0x44 N_SLINE line number in text segment
2394 70 0x46 N_DSLINE line number in data segment
2396 72 0x48 N_BSLINE line number in bss segment
2397 72 0x48 N_BROWS Sun source code browser, path to .cb file
2399 74 0x4a N_DEFD GNU Modula2 definition module dependency
2401 80 0x50 N_EHDECL GNU C++ exception variable
2402 80 0x50 N_MOD2 Modula2 info "for imc" (according to Ultrix V4.0)
2404 84 0x54 N_CATCH GNU C++ "catch" clause
2405 96 0x60 N_SSYM structure of union element
2406 100 0x64 N_SO path and name of source file
2407 128 0x80 N_LSYM automatic var in the stack
2408 (also used for type desc.)
2409 130 0x82 N_BINCL beginning of an include file (Sun only)
2410 132 0x84 N_SOL Name of sub-source (#include) file.
2411 160 0xa0 N_PSYM parameter variable
2412 162 0xa2 N_EINCL end of an include file
2413 164 0xa4 N_ENTRY alternate entry point
2414 192 0xc0 N_LBRAC beginning of a lexical block
2415 194 0xc2 N_EXCL place holder for a deleted include file
2416 196 0xc4 N_SCOPE modula2 scope information (Sun linker)
2417 224 0xe0 N_RBRAC end of a lexical block
2418 226 0xe2 N_BCOMM begin named common block
2419 228 0xe4 N_ECOMM end named common block
2420 232 0xe8 N_ECOML end common (local name)
2422 << used on Gould systems for non-base registers syms >>
2423 240 0xf0 N_NBTEXT ??
2424 242 0xf2 N_NBDATA ??
2430 @node Assembler types
2431 @section Table B: Symbol types from assembler and linker
2433 Table B shows the types of symbol table entries that hold assembler
2436 The #define names for these n_types values are defined in
2437 /include/aout/aout64.h
2441 n_type n_type name used to describe
2442 ------------------------------------------
2443 1 0x0 N_UNDF undefined symbol
2444 2 0x2 N_ABS absolute symbol -- defined at a particular address
2445 3 0x3 extern " (vs. file scope)
2446 4 0x4 N_TEXT text symbol -- defined at offset in text segment
2447 5 0x5 extern " (vs. file scope)
2448 6 0x6 N_DATA data symbol -- defined at offset in data segment
2449 7 0x7 extern " (vs. file scope)
2450 8 0x8 N_BSS BSS symbol -- defined at offset in zero'd segment
2451 9 extern " (vs. file scope)
2453 12 0x0C N_FN_SEQ func name for Sequent compilers (stab exception)
2455 49 0x12 N_COMM common sym -- visable after shared lib dynamic link
2456 31 0x1f N_FN file name of a .o file
2459 @node Symbol descriptors
2460 @section Table C: Symbol descriptors
2462 @c Please keep this alphabetical
2465 Local variable, @xref{Automatic variables}.
2471 Local function, @xref{Procedures}.
2474 Global function, @xref{Procedures}.
2477 Global variable, @xref{Global Variables}.
2483 Argument list parameter @xref{Parameters}.
2493 Register parameter @xref{Parameters}.
2496 Register variable, @xref{Register variables}.
2499 Static file scope variable @xref{Initialized statics},
2500 @xref{Un-initialized statics}.
2503 Type name, @xref{Typedefs}.
2506 enumeration, struct or union tag, @xref{Unions}.
2509 Call by reference, @xref{Parameters}.
2512 Static procedure scope variable @xref{Initialized statics},
2513 @xref{Un-initialized statics}.
2516 Function return variable, @xref{Parameters}.
2519 @node Type Descriptors
2520 @section Table D: Type Descriptors
2524 -------------------------------------
2525 (empty) type reference
2531 u union specifications
2536 @node Expanded reference
2537 @appendix Expanded reference by stab type.
2541 The first line is the symbol type expressed in decimal, hexadecimal,
2542 and as a #define (see devo/include/aout/stab.def).
2544 The second line describes the language constructs the symbol type
2547 The third line is the stab format with the significant stab fields
2548 named and the rest NIL.
2550 Subsequent lines expand upon the meaning and possible values for each
2551 significant stab field. # stands in for the type descriptor.
2553 Finally, any further information.
2556 * N_GSYM:: Global variable
2557 * N_FNAME:: Function name (BSD Fortran)
2558 * N_FUN:: C Function name or text segment variable
2559 * N_STSYM:: Initialized static symbol
2560 * N_LCSYM:: Uninitialized static symbol
2561 * N_MAIN:: Name of main routine (not for C)
2562 * N_PC:: Pascal global symbol
2563 * N_NSYMS:: Number of symbols
2564 * N_NOMAP:: No DST map
2565 * N_RSYM:: Register variable
2566 * N_M2C:: Modula-2 compilation unit
2567 * N_SLINE:: Line number in text segment
2568 * N_DSLINE:: Line number in data segment
2569 * N_BSLINE:: Line number in bss segment
2570 * N_BROWS:: Path to .cb file for Sun source code browser
2571 * N_DEFD:: GNU Modula2 definition module dependency
2572 * N_EHDECL:: GNU C++ exception variable
2573 * N_MOD2:: Modula2 information "for imc"
2574 * N_CATCH:: GNU C++ "catch" clause
2575 * N_SSYM:: Structure or union element
2576 * N_SO:: Source file containing main
2577 * N_LSYM:: Automatic variable
2578 * N_BINCL:: Beginning of include file (Sun only)
2579 * N_SOL:: Name of include file
2580 * N_PSYM:: Parameter variable
2581 * N_EINCL:: End of include file
2582 * N_ENTRY:: Alternate entry point
2583 * N_LBRAC:: Beginning of lexical block
2584 * N_EXCL:: Deleted include file
2585 * N_SCOPE:: Modula2 scope information (Sun only)
2586 * N_RBRAC:: End of lexical block
2587 * N_BCOMM:: Begin named common block
2588 * N_ECOMM:: End named common block
2589 * N_ECOML:: End common
2590 * Gould:: non-base register symbols used on Gould systems
2591 * N_LENG:: Length of preceding entry
2595 @section 32 - 0x20 - N_GYSM
2600 .stabs "name", N_GSYM, NIL, NIL, NIL
2604 "name" -> "symbol_name:#type"
2608 Only the "name" field is significant. The location of the variable is
2609 obtained from the corresponding external symbol.
2612 @section 34 - 0x22 - N_FNAME
2613 Function name (for BSD Fortran)
2616 .stabs "name", N_FNAME, NIL, NIL, NIL
2620 "name" -> "function_name"
2623 Only the "name" field is significant. The location of the symbol is
2624 obtained from the corresponding extern symbol.
2627 @section 36 - 0x24 - N_FUN
2628 Function name or text segment variable for C.
2631 .stabs "name", N_FUN, NIL, desc, value
2635 @exdent @emph{For functions:}
2636 "name" -> "proc_name:#return_type"
2637 # -> F (global function)
2639 desc -> line num for proc start. (GCC doesn't set and DBX doesn't miss it.)
2640 value -> Code address of proc start.
2642 @exdent @emph{For text segment variables:}
2643 <<How to create one?>>
2647 @section 38 - 0x26 - N_STSYM
2648 Initialized static symbol (data segment w/internal linkage).
2651 .stabs "name", N_STSYM, NIL, NIL, value
2655 "name" -> "symbol_name#type"
2656 # -> S (scope global to compilation unit)
2657 -> V (scope local to a procedure)
2658 value -> Data Address
2662 @section 40 - 0x28 - N_LCSYM
2663 Unitialized static (.lcomm) symbol(BSS segment w/internal linkage).
2666 .stabs "name", N_LCLSYM, NIL, NIL, value
2670 "name" -> "symbol_name#type"
2671 # -> S (scope global to compilation unit)
2672 -> V (scope local to procedure)
2673 value -> BSS Address
2677 @section 42 - 0x2a - N_MAIN
2678 Name of main routine (not used in C)
2681 .stabs "name", N_MAIN, NIL, NIL, NIL
2685 "name" -> "name_of_main_routine"
2689 @section 48 - 0x30 - N_PC
2690 Global symbol (for Pascal)
2693 .stabs "name", N_PC, NIL, NIL, value
2697 "name" -> "symbol_name" <<?>>
2698 value -> supposedly the line number (stab.def is skeptical)
2704 global pascal symbol: name,,0,subtype,line
2709 @section 50 - 0x32 - N_NSYMS
2710 Number of symbols (according to Ultrix V4.0)
2713 0, files,,funcs,lines (stab.def)
2717 @section 52 - 0x34 - N_NOMAP
2718 no DST map for sym (according to Ultrix V4.0)
2721 name, ,0,type,ignored (stab.def)
2725 @section 64 - 0x40 - N_RSYM
2729 .stabs "name:type",N_RSYM,0,RegSize,RegNumber (Sun doc)
2733 @section 66 - 0x42 - N_M2C
2734 Modula-2 compilation unit
2737 .stabs "name", N_M2C, 0, desc, value
2741 "name" -> "unit_name,unit_time_stamp[,code_time_stamp]
2743 value -> 0 (main unit)
2748 @section 68 - 0x44 - N_SLINE
2749 Line number in text segment
2752 .stabn N_SLINE, 0, desc, value
2757 value -> code_address (relocatable addr where the corresponding code starts)
2760 For single source lines that generate discontiguous code, such as flow
2761 of control statements, there may be more than one N_SLINE stab for the
2762 same source line. In this case there is a stab at the start of each
2763 code range, each with the same line number.
2766 @section 70 - 0x46 - N_DSLINE
2767 Line number in data segment
2770 .stabn N_DSLINE, 0, desc, value
2775 value -> data_address (relocatable addr where the corresponding code
2779 See comment for N_SLINE above.
2782 @section 72 - 0x48 - N_BSLINE
2783 Line number in bss segment
2786 .stabn N_BSLINE, 0, desc, value
2791 value -> bss_address (relocatable addr where the corresponding code
2795 See comment for N_SLINE above.
2798 @section 72 - 0x48 - N_BROWS
2799 Sun source code browser, path to .cb file
2802 "path to associated .cb file"
2804 Note: type field value overlaps with N_BSLINE
2807 @section 74 - 0x4a - N_DEFD
2808 GNU Modula2 definition module dependency
2810 GNU Modula-2 definition module dependency. Value is the modification
2811 time of the definition file. Other is non-zero if it is imported with
2812 the GNU M2 keyword %INITIALIZE. Perhaps N_M2C can be used if there
2813 are enough empty fields?
2816 @section 80 - 0x50 - N_EHDECL
2817 GNU C++ exception variable <<?>>
2819 "name is variable name"
2821 Note: conflicts with N_MOD2.
2824 @section 80 - 0x50 - N_MOD2
2825 Modula2 info "for imc" (according to Ultrix V4.0)
2827 Note: conflicts with N_EHDECL <<?>>
2830 @section 84 - 0x54 - N_CATCH
2831 GNU C++ "catch" clause
2833 GNU C++ `catch' clause. Value is its address. Desc is nonzero if
2834 this entry is immediately followed by a CAUGHT stab saying what
2835 exception was caught. Multiple CAUGHT stabs means that multiple
2836 exceptions can be caught here. If Desc is 0, it means all exceptions
2840 @section 96 - 0x60 - N_SSYM
2841 Structure or union element
2843 Value is offset in the structure.
2845 <<?looking at structs and unions in C I didn't see these>>
2848 @section 100 - 0x64 - N_SO
2849 Path and name of source file containing main routine
2852 .stabs "name", N_SO, NIL, NIL, value
2856 "name" -> /source/directory/
2859 value -> the starting text address of the compilation.
2862 These are found two in a row. The name field of the first N_SO contains
2863 the directory that the source file is relative to. The name field of
2864 the second N_SO contains the name of the source file itself.
2866 Only some compilers (e.g. gcc2, Sun cc) include the directory; this
2867 symbol can be distinguished by the fact that it ends in a slash.
2868 According to a comment in GDB's partial-stab.h, other compilers
2869 (especially unnamed C++ compilers) put out useless N_SO's for
2870 nonexistent source files (after the N_SO for the real source file).
2873 @section 128 - 0x80 - N_LSYM
2874 Automatic var in the stack (also used for type descriptors.)
2877 .stabs "name" N_LSYM, NIL, NIL, value
2881 @exdent @emph{For stack based local variables:}
2883 "name" -> name of the variable
2884 value -> offset from frame pointer (negative)
2886 @exdent @emph{For type descriptors:}
2888 "name" -> "name_of_the_type:#type"
2891 type -> type_ref (or) type_def
2893 type_ref -> type_number
2894 type_def -> type_number=type_desc etc.
2897 Type may be either a type reference or a type definition. A type
2898 reference is a number that refers to a previously defined type. A
2899 type definition is the number that will refer to this type, followed
2900 by an equals sign, a type descriptor and the additional data that
2901 defines the type. See the Table D for type descriptors and the
2902 section on types for what data follows each type descriptor.
2905 @section 130 - 0x82 - N_BINCL
2907 Beginning of an include file (Sun only)
2909 Beginning of an include file. Only Sun uses this. In an object file,
2910 only the name is significant. The Sun linker puts data into some of
2914 @section 132 - 0x84 - N_SOL
2916 Name of a sub-source file (#include file). Value is starting address
2921 @section 160 - 0xa0 - N_PSYM
2923 Parameter variable. @xref{Parameters}.
2926 @section 162 - 0xa2 - N_EINCL
2928 End of an include file. This and N_BINCL act as brackets around the
2929 file's output. In an ojbect file, there is no significant data in
2930 this entry. The Sun linker puts data into some of the fields.
2934 @section 164 - 0xa4 - N_ENTRY
2936 Alternate entry point.
2937 Value is its address.
2941 @section 192 - 0xc0 - N_LBRAC
2943 Beginning of a lexical block (left brace). The variable defined
2944 inside the block precede the N_LBRAC symbol. Or can they follow as
2945 well as long as a new N_FUNC was not encountered. <<?>>
2948 .stabn N_LBRAC, NIL, NIL, value
2952 value -> code address of block start.
2956 @section 194 - 0xc2 - N_EXCL
2958 Place holder for a deleted include file. Replaces a N_BINCL and
2959 everything up to the corresponding N_EINCL. The Sun linker generates
2960 these when it finds multiple indentical copies of the symbols from an
2961 included file. This appears only in output from the Sun linker.
2965 @section 196 - 0xc4 - N_SCOPE
2967 Modula2 scope information (Sun linker)
2971 @section 224 - 0xe0 - N_RBRAC
2973 End of a lexical block (right brace)
2976 .stabn N_RBRAC, NIL, NIL, value
2980 value -> code address of the end of the block.
2984 @section 226 - 0xe2 - N_BCOMM
2986 Begin named common block.
2988 Only the name is significant.
2992 @section 228 - 0xe4 - N_ECOMM
2994 End named common block.
2996 Only the name is significant and it should match the N_BCOMM
3000 @section 232 - 0xe8 - N_ECOML
3002 End common (local name)
3008 @section Non-base registers on Gould systems
3009 << used on Gould systems for non-base registers syms, values assigned
3010 at random, need real info from Gould. >>
3014 240 0xf0 N_NBTEXT ??
3015 242 0xf2 N_NBDATA ??
3022 @section - 0xfe - N_LENG
3024 Second symbol entry containing a length-value for the preceding entry.
3025 The value is the length.
3028 @appendix Questions and anomalies
3032 For GNU C stabs defining local and global variables (N_LSYM and
3033 N_GSYM), the desc field is supposed to contain the source line number
3034 on which the variable is defined. In reality the desc field is always
3035 0. (This behavour is defined in dbxout.c and putting a line number in
3036 desc is controlled by #ifdef WINNING_GDB which defaults to false). Gdb
3037 supposedly uses this information if you say 'list var'. In reality
3038 var can be a variable defined in the program and gdb says `function
3042 In GNU C stabs there seems to be no way to differentiate tag types:
3043 structures, unions, and enums (symbol descriptor T) and typedefs
3044 (symbol descriptor t) defined at file scope from types defined locally
3045 to a procedure or other more local scope. They all use the N_LSYM
3046 stab type. Types defined at procedure scope are emited after the
3047 N_RBRAC of the preceding function and before the code of the
3048 procedure in which they are defined. This is exactly the same as
3049 types defined in the source file between the two procedure bodies.
3050 GDB overcompensates by placing all types in block #1, the block for
3051 symbols of file scope. This is true for default, -ansi and
3052 -traditional compiler options. (Bugs gcc/1063, gdb/1066.)
3055 What ends the procedure scope? Is it the proc block's N_RBRAC or the
3056 next N_FUN? (I believe its the first.)
3059 The comment in xcoff.h says DBX_STATIC_CONST_VAR_CODE is used for
3060 static const variables. DBX_STATIC_CONST_VAR_CODE is set to N_FUN by
3061 default, in dbxout.c. If included, xcoff.h redefines it to N_STSYM.
3062 But testing the default behaviour, my Sun4 native example shows
3063 N_STSYM not N_FUN is used to describe file static initialized
3064 variables. (the code tests for TREE_READONLY(decl) &&
3065 !TREE_THIS_VOLATILE(decl) and if true uses DBX_STATIC_CONST_VAR_CODE).
3068 Global variable stabs don't have location information. This comes
3069 from the external symbol for the same variable. The external symbol
3070 has a leading underbar on the _name of the variable and the stab does
3071 not. How do we know these two symbol table entries are talking about
3072 the same symbol when their names are different?
3075 Can gcc be configured to output stabs the way the Sun compiler
3076 does, so that their native debugging tools work? <NO?> It doesn't by
3077 default. GDB reads either format of stab. (gcc or SunC). How about
3081 @node xcoff-differences
3082 @appendix Differences between GNU stabs in a.out and GNU stabs in xcoff
3084 @c FIXME: Merge *all* these into the main body of the document.
3085 (The AIX/RS6000 native object file format is xcoff with stabs). This
3086 appendix only covers those differences which are not covered in the main
3087 body of this document.
3091 Instead of .stabs, xcoff uses .stabx.
3094 The data fields of an xcoff .stabx are in a different order than an
3095 a.out .stabs. The order is: string, value, type. The desc and null
3096 fields present in a.out stabs are missing in xcoff stabs. For N_GSYM
3097 the value field is the name of the symbol.
3100 BSD a.out stab types correspond to AIX xcoff storage classes. In general the
3101 mapping is N_STABTYPE becomes C_STABTYPE. Some stab types in a.out
3102 are not supported in xcoff. See Table E. for full mappings.
3105 initialised static N_STSYM and un-initialized static N_LCSYM both map
3106 to the C_STSYM storage class. But the destinction is preserved
3107 because in xcoff N_STSYM and N_LCSYM must be emited in a named static
3108 block. Begin the block with .bs s[RW] data_section_name for N_STSYM
3109 or .bs s bss_section_name for N_LCSYM. End the block with .es
3112 xcoff stabs describing tags and typedefs use the N_DECL (0x8c)instead
3113 of N_LSYM stab type.
3116 xcoff uses N_RPSYM (0x8e) instead of the N_RSYM stab type for register
3117 variables. If the register variable is also a value parameter, then
3118 use R instead of P for the symbol descriptor.
3121 xcoff uses negative numbers as type references to the basic types.
3122 There are no boilerplate type definitions emited for these basic
3123 types. << make table of basic types and type numbers for C >>
3126 xcoff .stabx sometimes don't have the name part of the string field.
3129 xcoff uses a .file stab type to represent the source file name. There
3130 is no stab for the path to the source file.
3133 xcoff uses a .line stab type to represent source lines. The format
3134 is: .line line_number.
3137 xcoff emits line numbers relative to the start of the current
3138 function. The start of a function is marked by .bf. If a function
3139 includes lines from a seperate file, then those line numbers are
3140 absolute line numbers in the <<sub-?>> file being compiled.
3143 The start of current include file is marked with: .bi "filename" and
3144 the end marked with .ei "filename"
3147 If the xcoff stab is a N_FUN (C_FUN) then follow the string field with
3148 ,. instead of just ,
3152 (I think that's it for .s file differences. They could stand to be
3153 better presented. This is just a list of what I have noticed so far.
3154 There are a *lot* of differences in the information in the symbol
3155 tables of the executable and object files.)
3157 Table E: mapping a.out stab types to xcoff storage classes
3160 stab type storage class
3161 -------------------------------
3170 N_RPSYM (0x8e) C_RPSYM
3180 N_DECL (0x8c) C_DECL
3197 @node Sun-differences
3198 @appendix Differences between GNU stabs and Sun native stabs.
3200 @c FIXME: Merge all this stuff into the main body of the document.
3204 GNU C stabs define *all* types, file or procedure scope, as
3205 N_LSYM. Sun doc talks about using N_GSYM too.
3208 Stabs describing block scopes, N_LBRAC and N_RBRAC are supposed to
3209 contain the nesting level of the block in the desc field, re Sun doc.
3210 GNU stabs always have 0 in that field. dbx seems not to care.
3213 Sun C stabs use type number pairs in the format (a,b) where a is a
3214 number starting with 1 and incremented for each sub-source file in the
3215 compilation. b is a number starting with 1 and incremented for each
3216 new type defined in the compilation. GNU C stabs use the type number
3217 alone, with no source file number.