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
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 @c FIXME! "too long" below introduced at J Gilmore's request; used to
212 @c say "more than 80 chars". Why is vaguer better?
213 All this can make the @code{"@var{string}"} field quite long. When the
214 @code{"@var{string}"} part of a stab is too long, the compiler splits
215 the @code{.stabs} directive into two @code{.stabs} directives. Both
216 stabs duplicate exactly all but the @code{"@var{string}"} field. The
217 @code{"@var{string}"} field of the first stab contains the first part of
218 the overlong string, marked as continued with a double-backslash at the
219 end. The @code{"@var{string}"} field of the second stab holds the
220 second half of the overlong string.
223 @section A simple example in C source
225 To get the flavor of how stabs describe source information for a C
226 program, let's look at the simple program:
231 printf("Hello world");
235 When compiled with @samp{-g}, the program above yields the following
236 @file{.s} file. Line numbers have been added to make it easier to refer
237 to parts of the @file{.s} file in the description of the stabs that
241 @section The simple example at the assembly level
245 2 .stabs "/cygint/s1/users/jcm/play/",100,0,0,Ltext0
246 3 .stabs "hello.c",100,0,0,Ltext0
249 6 .stabs "int:t1=r1;-2147483648;2147483647;",128,0,0,0
250 7 .stabs "char:t2=r2;0;127;",128,0,0,0
251 8 .stabs "long int:t3=r1;-2147483648;2147483647;",128,0,0,0
252 9 .stabs "unsigned int:t4=r1;0;-1;",128,0,0,0
253 10 .stabs "long unsigned int:t5=r1;0;-1;",128,0,0,0
254 11 .stabs "short int:t6=r1;-32768;32767;",128,0,0,0
255 12 .stabs "long long int:t7=r1;0;-1;",128,0,0,0
256 13 .stabs "short unsigned int:t8=r1;0;65535;",128,0,0,0
257 14 .stabs "long long unsigned int:t9=r1;0;-1;",128,0,0,0
258 15 .stabs "signed char:t10=r1;-128;127;",128,0,0,0
259 16 .stabs "unsigned char:t11=r1;0;255;",128,0,0,0
260 17 .stabs "float:t12=r1;4;0;",128,0,0,0
261 18 .stabs "double:t13=r1;8;0;",128,0,0,0
262 19 .stabs "long double:t14=r1;8;0;",128,0,0,0
263 20 .stabs "void:t15=15",128,0,0,0
266 23 .ascii "Hello, world!\12\0"
281 38 sethi %hi(LC0),%o1
282 39 or %o1,%lo(LC0),%o0
293 50 .stabs "main:F1",36,0,0,_main
294 51 .stabn 192,0,0,LBB2
295 52 .stabn 224,0,0,LBE2
298 This simple ``hello world'' example demonstrates several of the stab
299 types used to describe C language source files.
301 @node Program structure
302 @chapter Encoding for the structure of the program
305 * Source file:: The path and name of the source file
312 @section The path and name of the source file
321 The first stabs in the .s file contain the name and path of the source
322 file that was compiled to produce the .s file. This information is
323 contained in two records of stab type N_SO (100).
326 .stabs "path_name", N_SO, NIL, NIL, Code_address_of_program_start
327 .stabs "file_name:", N_SO, NIL, NIL, Code_address_of_program_start
331 2 .stabs "/cygint/s1/users/jcm/play/",100,0,0,Ltext0
332 3 .stabs "hello.c",100,0,0,Ltext0
338 @section Line Numbers
347 The start of source lines is represented by the @code{N_SLINE} (68) stab
351 .stabn N_SLINE, NIL, @var{line}, @var{address}
354 @var{line} is a source line number; @var{address} represents the code
355 address for the start of that source line.
372 @item Symbol Descriptors:
373 @code{f} (local), @code{F} (global)
376 Procedures are described by the @code{N_FUN} stab type. The symbol
377 descriptor for a procedure is @samp{F} if the procedure is globally
378 scoped and @samp{f} if the procedure is static (locally scoped).
380 The @code{N_FUN} stab representing a procedure is located immediately
381 following the code of the procedure. The @code{N_FUN} stab is in turn
382 directly followed by a group of other stabs describing elements of the
383 procedure. These other stabs describe the procedure's parameters, its
384 block local variables and its block structure.
391 The @code{.stabs} entry after this code fragment shows the @var{name} of
392 the procedure (@code{main}); the type descriptor @var{desc} (@code{F},
393 for a global procedure); a reference to the predefined type @code{int}
394 for the return type; and the starting @var{address} of the procedure.
396 Here is an exploded summary (with whitespace introduced for clarity),
397 followed by line 50 of our sample assembly output, which has this form:
401 @var{desc} @r{(global proc @samp{F})}
402 @var{return_type_ref} @r{(int)}
408 50 .stabs "main:F1",36,0,0,_main
411 @node Block Structure
412 @section Block Structure
418 @code{N_LBRAC}, @code{N_RBRAC}
421 The program's block structure is represented by the @code{N_LBRAC} (left
422 brace) and the @code{N_RBRAC} (right brace) stab types. The following code
423 range, which is the body of @code{main}, is labeled with @samp{LBB2:} at the
424 beginning and @samp{LBE2:} at the end.
428 38 sethi %hi(LC0),%o1
429 39 or %o1,%lo(LC0),%o0
437 The @code{N_LBRAC} and @code{N_RBRAC} stabs that describe the block
438 scope of the procedure are located after the @code{N_FUNC} stab that
439 represents the procedure itself. The @code{N_LBRAC} uses the
440 @code{LBB2} label as the code address in its value field, and the
441 @code{N_RBRAC} uses @code{LBE2}.
444 50 .stabs "main:F1",36,0,0,_main
448 .stabn N_LBRAC, NIL, NIL, @var{left-brace-address}
449 .stabn N_RBRAC, NIL, NIL, @var{right-brace-address}
453 51 .stabn 192,0,0,LBB2
454 52 .stabn 224,0,0,LBE2
458 @chapter Simple types
461 * Basic types:: Basic type definitions
462 * Range types:: Range types defined by min and max value
463 * Bit-ranges:: Range type defined by number of bits
467 @section Basic type definitions
474 @item Symbol Descriptor:
478 The basic types for the language are described using the @code{N_LSYM} stab
479 type. They are boilerplate and are emited by the compiler for each
480 compilation unit. Basic type definitions are not always a complete
481 description of the type and are sometimes circular. The debugger
482 recognizes the type anyway, and knows how to read bits as that type.
484 Each language and compiler defines a slightly different set of basic
485 types. In this example we are looking at the basic types for C emited
486 by the GNU compiler targeting the Sun4. Here the basic types are
487 mostly defined as range types.
491 @section Range types defined by min and max value
494 @item Type Descriptor:
498 When defining a range type, if the number after the first semicolon is
499 smaller than the number after the second one, then the two numbers
500 represent the smallest and the largest values in the range.
507 @var{descriptor} @r{(type)}
514 N_LSYM, NIL, NIL, NIL
516 6 .stabs "int:t1=r1;-2147483648;2147483647;",128,0,0,0
517 7 .stabs "char:t2=r2;0;127;",128,0,0,0
520 Here the integer type (@code{1}) is defined as a range of the integer
521 type (@code{1}). Likewise @code{char} is a range of @code{char}. This
522 part of the definition is circular, but at least the high and low bound
523 values of the range hold more information about the type.
525 Here short unsigned int is defined as type number 8 and described as a
526 range of type @code{int}, with a minimum value of 0 and a maximum of 65535.
529 13 .stabs "short unsigned int:t8=r1;0;65535;",128,0,0,0
533 @section Range type defined by number of bits
536 @item Type Descriptor:
540 In a range definition, if the number after the second semicolon is 0,
541 then the number after the first semicolon is the number of bits needed
542 to represent the type.
553 N_LSYM, NIL, NIL, NIL
555 17 .stabs "float:t12=r1;4;0;",128,0,0,0
556 18 .stabs "double:t13=r1;8;0;",128,0,0,0
557 19 .stabs "long double:t14=r1;8;0;",128,0,0,0
560 Cosmically enough, the @code{void} type is defined directly in terms of
570 20 .stabs "void:t15=15",128,0,0,0
575 @chapter A Comprehensive Example in C
577 Now we'll examine a second program, @code{example2}, which builds on the
578 first example to introduce the rest of the stab types, symbol
579 descriptors, and type descriptors used in C.
580 @xref{Example2.c} for the complete @file{.c} source,
581 and @pxref{Example2.s} for the @file{.s} assembly code.
582 This description includes parts of those files.
584 @section Flow of control and nested scopes
590 @code{N_SLINE}, @code{N_LBRAC}, @code{N_RBRAC} (cont.)
593 Consider the body of @code{main}, from @file{example2.c}. It shows more
594 about how @code{N_SLINE}, @code{N_RBRAC}, and @code{N_LBRAC} stabs are used.
598 21 static float s_flap;
600 23 for (times=0; times < s_g_repeat; times++)@{
602 25 printf ("Hello world\n");
607 Here we have a single source line, the @samp{for} line, that generates
608 non-linear flow of control, and non-contiguous code. In this case, an
609 @code{N_SLINE} stab with the same line number proceeds each block of
610 non-contiguous code generated from the same source line.
612 The example also shows nested scopes. The @code{N_LBRAC} and
613 @code{N_LBRAC} stabs that describe block structure are nested in the
614 same order as the corresponding code blocks, those of the for loop
615 inside those for the body of main.
618 This is the label for the @code{N_LBRAC} (left brace) stab marking the
619 start of @code{main}.
626 In the first code range for C source line 23, the @code{for} loop
627 initialize and test, @code{N_SLINE} (68) records the line number:
634 58 .stabn 68,0,23,LM2
638 62 sethi %hi(_s_g_repeat),%o0
640 64 ld [%o0+%lo(_s_g_repeat)],%o0
645 @exdent label for the @code{N_LBRAC} (start block) marking the start of @code{for} loop
648 69 .stabn 68,0,25,LM3
650 71 sethi %hi(LC0),%o1
651 72 or %o1,%lo(LC0),%o0
654 75 .stabn 68,0,26,LM4
657 @exdent label for the @code{N_RBRAC} (end block) stab marking the end of the @code{for} loop
663 Now we come to the second code range for source line 23, the @code{for}
664 loop increment and return. Once again, @code{N_SLINE} (68) records the
668 .stabn, N_SLINE, NIL,
672 78 .stabn 68,0,23,LM5
680 86 .stabn 68,0,27,LM6
683 @exdent label for the @code{N_RBRAC} (end block) stab marking the end of the @code{for} loop
686 89 .stabn 68,0,27,LM7
691 94 .stabs "main:F1",36,0,0,_main
692 95 .stabs "argc:p1",160,0,0,68
693 96 .stabs "argv:p20=*21=*2",160,0,0,72
694 97 .stabs "s_flap:V12",40,0,0,_s_flap.0
695 98 .stabs "times:1",128,0,0,-20
699 Here is an illustration of stabs describing nested scopes. The scope
700 nesting is reflected in the nested bracketing stabs (@code{N_LBRAC},
704 .stabn N_LBRAC,NIL,NIL,
705 @var{block-start-address}
707 99 .stabn 192,0,0,LBB2 ## begin proc label
708 100 .stabs "inner:1",128,0,0,-24
709 101 .stabn 192,0,0,LBB3 ## begin for label
713 @code{N_RBRAC} (224), ``right brace'' ends a lexical block (scope).
716 .stabn N_RBRAC,NIL,NIL,
717 @var{block-end-address}
719 102 .stabn 224,0,0,LBE3 ## end for label
720 103 .stabn 224,0,0,LBE2 ## end proc label
727 * Automatic variables:: locally scoped
729 * Register variables::
730 * Initialized statics::
731 * Un-initialized statics::
735 @node Automatic variables
736 @section Locally scoped automatic variables
743 @item Symbol Descriptor:
748 In addition to describing types, the @code{N_LSYM} stab type also
749 describes locally scoped automatic variables. Refer again to the body
750 of @code{main} in @file{example2.c}. It allocates two automatic
751 variables: @samp{times} is scoped to the body of @code{main}, and
752 @samp{inner} is scoped to the body of the @code{for} loop.
753 @samp{s_flap} is locally scoped but not automatic, and will be discussed
758 21 static float s_flap;
760 23 for (times=0; times < s_g_repeat; times++)@{
762 25 printf ("Hello world\n");
767 The @code{N_LSYM} stab for an automatic variable is located just before the
768 @code{N_LBRAC} stab describing the open brace of the block to which it is
772 @exdent @code{N_LSYM} (128): automatic variable, scoped locally to @code{main}
777 @var{frame-pointer-offset}
779 98 .stabs "times:1",128,0,0,-20
780 99 .stabn 192,0,0,LBB2 ## begin `main' N_LBRAC
782 @exdent @code{N_LSYM} (128): automatic variable, scoped locally to the @code{for} loop
787 @var{frame-pointer-offset}
789 100 .stabs "inner:1",128,0,0,-24
790 101 .stabn 192,0,0,LBB3 ## begin `for' loop N_LBRAC
793 Since the character in the string field following the colon is not a
794 letter, there is no symbol descriptor. This means that the stab
795 describes a local variable, and that the number after the colon is a
796 type reference. In this case it a a reference to the basic type @code{int}.
797 Notice also that the frame pointer offset is negative number for
801 @node Global Variables
802 @section Global Variables
809 @item Symbol Descriptor:
813 Global variables are represented by the @code{N_GSYM} stab type. The symbol
814 descriptor, following the colon in the string field, is @samp{G}. Following
815 the @samp{G} is a type reference or type definition. In this example it is a
816 type reference to the basic C type, @code{char}. The first source line in
824 yields the following stab. The stab immediately precedes the code that
825 allocates storage for the variable it describes.
828 @exdent @code{N_GSYM} (32): global symbol
833 N_GSYM, NIL, NIL, NIL
835 21 .stabs "g_foo:G2",32,0,0,0
842 The address of the variable represented by the @code{N_GSYM} is not contained
843 in the @code{N_GSYM} stab. The debugger gets this information from the
844 external symbol for the global variable.
846 @node Register variables
847 @section Global register variables
854 @item Symbol Descriptor:
858 The following source line defines a global variable, @code{g_bar}, which is
859 explicitly allocated in global register @code{%g5}.
862 2 register int g_bar asm ("%g5");
865 Register variables have their own stab type, @code{N_RSYM}, and their own
866 symbol descriptor, @code{r}. The stab's value field contains the number of
867 the register where the variable data will be stored. Since the
868 variable was not initialized in this compilation unit, the stab is
869 emited at the end of the object file, with the stabs for other
870 uninitialized globals (@code{bcc}).
873 @exdent @code{N_RSYM} (64): register variable
881 133 .stabs "g_bar:r1",64,0,0,5
885 @node Initialized statics
886 @section Initialized static variables
893 @item Symbol Descriptors:
894 @code{S} (file scope), @code{V} (procedure scope)
897 Initialized static variables are represented by the @code{N_STSYM} stab
898 type. The symbol descriptor part of the string field shows if the
899 variable is file scope static (@samp{S}) or procedure scope static
900 (@samp{V}). The source line
903 3 static int s_g_repeat = 2;
907 yields the following code. The stab is located immediately preceding
908 the storage for the variable it represents. Since the variable in
909 this example is file scope static the symbol descriptor is @samp{S}.
912 @exdent @code{N_STSYM} (38): initialized static variable (data seg w/internal linkage)
920 26 .stabs "s_g_repeat:S1",38,0,0,_s_g_repeat
927 @node Un-initialized statics
928 @section Un-initialized static variables
935 @item Symbol Descriptors:
936 @code{S} (file scope), @code{V} (procedure scope)
939 Un-initialized static variables are represented by the @code{N_LCSYM}
940 stab type. The symbol descriptor part of the string shows if the
941 variable is file scope static (@samp{S}) or procedure scope static
942 (@samp{V}). In this example it is procedure scope static. The source
943 line allocating @code{s_flap} immediately follows the open brace for the
944 procedure @code{main}.
948 21 static float s_flap;
951 The code that reserves storage for the variable @code{s_flap} precedes the
952 body of body of @code{main}.
955 39 .reserve _s_flap.0,4,"bss",4
958 But since @code{s_flap} is scoped locally to @code{main}, its stab is
959 located with the other stabs representing symbols local to @code{main}.
960 The stab for @code{s_flap} is located just before the @code{N_LBRAC} for
964 @exdent @code{N_LCSYM} (40): uninitialized static var (BSS seg w/internal linkage)
972 97 .stabs "s_flap:V12",40,0,0,_s_flap.0
973 98 .stabs "times:1",128,0,0,-20
974 99 .stabn 192,0,0,LBB2 # N_LBRAC for main.
977 @c ............................................................
987 @item Symbol Descriptor:
991 Procedure parameters are represented by the N_PSYM stab type. The
992 following source lines show the parameters of the main routine.
1001 The N_PSYM stabs describing parameters to a function directly follow
1002 the N_FUN stab that represents the procedure itself. The N_FUN stab
1003 immediately follows the code of the procedure it describes. Following
1004 the N_PSYM parameter stabs are any N_LSYM stabs representing local
1008 @exdent <36> N_FUN - describing the procedure main
1010 94 .stabs "main:F1",36,0,0,_main
1012 @exdent <160> N_PSYM - parameters
1013 @exdent .stabs "name:sym_desc(value_param)type_ref(int)", N_PSYM,
1014 @exdent NIL, NIL, frame_ptr_offset
1016 95 .stabs "argc:p1",160,0,0,68
1018 @exdent <160> N_PSYM - parameter
1019 @exdent .stabs "name:sym_desc(value_param)type_def(20)=ptr_to type_def(21)=
1020 @exdent ptr_to type_ref(char)
1022 96 .stabs "argv:p20=*21=*2",160,0,0,72
1025 The type definition of argv is interesting because it defines two new
1026 types in terms of an existing one. The array argv contains character
1027 pointers. The type of the array name is a pointer to the type the
1028 array holds. Thus the type of argv is ptr to ptr to char. The stab
1029 for argv contains nested type_definitions. Type 21 is ptr to type 2
1030 (char) and argv (type 20) is ptr to type 21.
1032 @node Aggregate Types
1033 @chapter Aggregate Types
1035 Now let's look at some variable definitions involving complex types.
1036 This involves understanding better how types are described. In the
1037 examples so far types have been described as references to previously
1038 defined types or defined in terms of subranges of or pointers to
1039 previously defined types. The section that follows will talk about
1040 the various other type descriptors that may follow the = sign in a
1053 @section Array types
1059 @code{N_GSYM}, @code{N_LSYM}
1060 @item Symbol Descriptor:
1062 @item Type Descriptor:
1066 As an example of an array type consider the global variable below.
1069 15 char char_vec[3] = @{'a','b','c'@};
1072 Since the array is a global variable, it is described by the N_GSYM
1073 stab type. The symbol descriptor G, following the colon in stab's
1074 string field, also says the array is a global variable. Following the
1075 G is a definition for type (19) as shown by the equals sign after the
1078 After the equals sign is a type descriptor, ar, which says that the
1079 type being defined is an array. Following the type descriptor for an
1080 array is the type of the index, a null field, the upper bound of the
1081 array indexing, and the type of the array elements.
1083 The array definition above generates the assembly language that
1087 @exdent <32> N_GSYM - global variable
1088 @exdent .stabs "name:sym_desc(global)type_def(19)=type_desc(array)
1089 @exdent index_type_ref(int);NIL;high_bound(2);element_type_ref(char)";
1090 @exdent N_GSYM, NIL, NIL, NIL
1092 32 .stabs "char_vec:G19=ar1;0;2;2",32,0,0,0
1093 33 .global _char_vec
1102 @section Enumerations
1109 @item Symbol Descriptor:
1111 @item Type Descriptor:
1115 The source line below declares an enumeration type. It is defined at
1116 file scope between the bodies of main and s_proc in example2.c.
1117 Because the N_LSYM is located after the N_RBRAC that marks the end of
1118 the previous procedure's block scope, and before the N_FUN that marks
1119 the beginning of the next procedure's block scope, the N_LSYM does not
1120 describe a block local symbol, but a file local one. The source line:
1123 29 enum e_places @{first,second=3,last@};
1127 generates the following stab, located just after the N_RBRAC (close
1128 brace stab) for main. The type definition is in an N_LSYM stab
1129 because type definitions are file scope not global scope.
1132 <128> N_LSYM - local symbol
1133 .stab "name:sym_dec(type)type_def(22)=sym_desc(enum)
1134 enum_name:value(0),enum_name:value(3),enum_name:value(4),;",
1135 N_LSYM, NIL, NIL, NIL
1139 104 .stabs "e_places:T22=efirst:0,second:3,last:4,;",128,0,0,0
1142 The symbol descriptor (T) says that the stab describes a structure,
1143 enumeration, or type tag. The type descriptor e, following the 22= of
1144 the type definition narrows it down to an enumeration type. Following
1145 the e is a list of the elements of the enumeration. The format is
1146 name:value,. The list of elements ends with a ;.
1148 @node Structure tags
1149 @section Structure Tags
1156 @item Symbol Descriptor:
1158 @item Type Descriptor:
1162 The following source code declares a structure tag and defines an
1163 instance of the structure in global scope. Then a typedef equates the
1164 structure tag with a new type. A seperate stab is generated for the
1165 structure tag, the structure typedef, and the structure instance. The
1166 stabs for the tag and the typedef are emited when the definitions are
1167 encountered. Since the structure elements are not initialized, the
1168 stab and code for the structure variable itself is located at the end
1169 of the program in .common.
1175 9 char s_char_vec[8];
1176 10 struct s_tag* s_next;
1179 13 typedef struct s_tag s_typedef;
1182 The structure tag is an N_LSYM stab type because, like the enum, the
1183 symbol is file scope. Like the enum, the symbol descriptor is T, for
1184 enumeration, struct or tag type. The symbol descriptor s following
1185 the 16= of the type definition narrows the symbol type to struct.
1187 Following the struct symbol descriptor is the number of bytes the
1188 struct occupies, followed by a description of each structure element.
1189 The structure element descriptions are of the form name:type, bit
1190 offset from the start of the struct, and number of bits in the
1195 <128> N_LSYM - type definition
1196 .stabs "name:sym_desc(struct tag) Type_def(16)=type_desc(struct type)
1198 elem_name:type_ref(int),bit_offset,field_bits;
1199 elem_name:type_ref(float),bit_offset,field_bits;
1200 elem_name:type_def(17)=type_desc(dynamic array) index_type(int);NIL;
1201 high_bound(7);element_type(char),bit_offset,field_bits;;",
1204 30 .stabs "s_tag:T16=s20s_int:1,0,32;s_float:12,32,32;
1205 s_char_vec:17=ar1;0;7;2,64,64;s_next:18=*16,128,32;;",128,0,0,0
1208 In this example, two of the structure elements are previously defined
1209 types. For these, the type following the name: part of the element
1210 description is a simple type reference. The other two structure
1211 elements are new types. In this case there is a type definition
1212 embedded after the name:. The type definition for the array element
1213 looks just like a type definition for a standalone array. The s_next
1214 field is a pointer to the same kind of structure that the field is an
1215 element of. So the definition of structure type 16 contains an type
1216 definition for an element which is a pointer to type 16.
1226 @item Symbol Descriptor:
1230 Here is the stab for the typedef equating the structure tag with a
1234 <128> N_LSYM - type definition
1235 .stabs "name:sym_desc(type name)type_ref(struct_tag)",N_LSYM,NIL,NIL,NIL
1239 31 .stabs "s_typedef:t16",128,0,0,0
1242 And here is the code generated for the structure variable.
1245 <32> N_GSYM - global symbol
1246 .stabs "name:sym_desc(global)type_ref(struct_tag)",N_GSYM,NIL,NIL,NIL
1250 136 .stabs "g_an_s:G16",32,0,0,0
1251 137 .common _g_an_s,20,"bss"
1254 Notice that the structure tag has the same type number as the typedef
1255 for the structure tag. It is impossible to distinguish between a
1256 variable of the struct type and one of its typedef by looking at the
1257 debugging information.
1268 @item Symbol Descriptor:
1270 @item Type Descriptor:
1274 Next let's look at unions. In example2 this union type is declared
1275 locally to a procedure and an instance of the union is defined.
1285 This code generates a stab for the union tag and a stab for the union
1286 variable. Both use the N_LSYM stab type. Since the union variable is
1287 scoped locally to the procedure in which it is defined, its stab is
1288 located immediately preceding the N_LBRAC for the procedure's block
1291 The stab for the union tag, however is located preceding the code for
1292 the procedure in which it is defined. The stab type is N_LSYM. This
1293 would seem to imply that the union type is file scope, like the struct
1294 type s_tag. This is not true. The contents and position of the stab
1295 for u_type do not convey any infomation about its procedure local
1300 .stabs "name:sym_desc(union tag)type_def(22)=type_desc(union)
1302 elem_name:type_ref(int),bit_offset(0),bit_size(32);
1303 elem_name:type_ref(float),bit_offset(0),bit_size(32);
1304 elem_name:type_ref(ptr to char),bit_offset(0),bit_size(32);;"
1305 N_LSYM, NIL, NIL, NIL
1309 105 .stabs "u_tag:T23=u4u_int:1,0,32;u_float:12,0,32;u_char:21,0,32;;",
1313 The symbol descriptor, T, following the name: means that the stab
1314 describes an enumeration struct or type tag. The type descriptor u,
1315 following the 23= of the type definition, narrows it down to a union
1316 type definition. Following the u is the number of bytes in the union.
1317 After that is a list of union element descriptions. Their format is
1318 name:type, bit offset into the union, and number of bytes for the
1321 The stab for the union variable follows. Notice that the frame
1322 pointer offset for local variables is negative.
1325 <128> N_LSYM - local variable (with no symbol descriptor)
1326 .stabs "name:type_ref(u_tag)", N_LSYM, NIL, NIL, frame_ptr_offset
1330 130 .stabs "an_u:23",128,0,0,-20
1333 @node Function types
1334 @section Function types
1340 The last type descriptor in C which remains to be described is used
1341 for function types. Consider the following source line defining a
1342 global function pointer.
1348 It generates the following code. Since the variable is not
1349 initialized, the code is located in the common area at the end of the
1353 <32> N_GSYM - global variable
1354 .stabs "name:sym_desc(global)type_def(24)=ptr_to(25)=
1355 type_def(func)type_ref(int)
1359 134 .stabs "g_pf:G24=*25=f1",32,0,0,0
1360 135 .common _g_pf,4,"bss"
1363 Since the variable is global, the stab type is N_GSYM and the symbol
1364 descriptor is G. The variable defines a new type, 24, which is a
1365 pointer to another new type, 25, which is defined as a function
1369 @chapter Symbol information in symbol tables
1371 This section examines more closely the format of symbol table entries
1372 and how stab assembler directives map to them. It also describes what
1373 transformations the assembler and linker make on data from stabs.
1375 Each time the assembler encounters a stab in its input file it puts
1376 each field of the stab into corresponding fields in a symbol table
1377 entry of its output file. If the stab contains a string field, the
1378 symbol table entry for that stab points to a string table entry
1379 containing the string data from the stab. Assembler labels become
1380 relocatable addresses. Symbol table entries in a.out have the format:
1383 struct internal_nlist @{
1384 unsigned long n_strx; /* index into string table of name */
1385 unsigned char n_type; /* type of symbol */
1386 unsigned char n_other; /* misc info (usually empty) */
1387 unsigned short n_desc; /* description field */
1388 bfd_vma n_value; /* value of symbol */
1392 For .stabs directives, the n_strx field holds the character offset
1393 from the start of the string table to the string table entry
1394 containing the "string" field. For other classes of stabs (.stabn and
1395 .stabd) this field is null.
1397 Symbol table entries with n_type fields containing a value greater or
1398 equal to 0x20 originated as stabs generated by the compiler (with one
1399 random exception). Those with n_type values less than 0x20 were
1400 placed in the symbol table of the executable by the assembler or the
1403 The linker concatenates object files and does fixups of externally
1404 defined symbols. You can see the transformations made on stab data by
1405 the assembler and linker by examining the symbol table after each pass
1406 of the build, first the assemble and then the link.
1408 To do this use nm with the -ap options. This dumps the symbol table,
1409 including debugging information, unsorted. For stab entries the
1410 columns are: value, other, desc, type, string. For assembler and
1411 linker symbols, the columns are: value, type, string.
1413 There are a few important things to notice about symbol tables. Where
1414 the value field of a stab contains a frame pointer offset, or a
1415 register number, that value is unchanged by the rest of the build.
1417 Where the value field of a stab contains an assembly language label,
1418 it is transformed by each build step. The assembler turns it into a
1419 relocatable address and the linker turns it into an absolute address.
1420 This source line defines a static variable at file scope:
1423 3 static int s_g_repeat
1427 The following stab describes the symbol.
1430 26 .stabs "s_g_repeat:S1",38,0,0,_s_g_repeat
1434 The assembler transforms the stab into this symbol table entry in the
1435 @file{.o} file. The location is expressed as a data segment offset.
1438 21 00000084 - 00 0000 STSYM s_g_repeat:S1
1442 in the symbol table entry from the executable, the linker has made the
1443 relocatable address absolute.
1446 22 0000e00c - 00 0000 STSYM s_g_repeat:S1
1449 Stabs for global variables do not contain location information. In
1450 this case the debugger finds location information in the assembler or
1451 linker symbol table entry describing the variable. The source line:
1461 21 .stabs "g_foo:G2",32,0,0,0
1464 The variable is represented by the following two symbol table entries
1465 in the object file. The first one originated as a stab. The second
1466 one is an external symbol. The upper case D signifies that the n_type
1467 field of the symbol table contains 7, N_DATA with local linkage (see
1468 Table B). The value field following the file's line number is empty
1469 for the stab entry. For the linker symbol it contains the
1470 rellocatable address corresponding to the variable.
1473 19 00000000 - 00 0000 GSYM g_foo:G2
1474 20 00000080 D _g_foo
1478 These entries as transformed by the linker. The linker symbol table
1479 entry now holds an absolute address.
1482 21 00000000 - 00 0000 GSYM g_foo:G2
1484 215 0000e008 D _g_foo
1488 @chapter GNU C++ stabs
1494 * Methods:: Method definition
1496 * Method modifiers:: (const, volatile, const volatile)
1499 * Virtual base classes::
1505 @subsection Symbol descriptors added for C++ descriptions:
1508 P - register parameter.
1511 @subsection type descriptors added for C++ descriptions
1515 method type (two ## if minimal debug)
1521 @node Basic C++ types
1522 @section Basic types for C++
1524 << the examples that follow are based on a01.C >>
1527 C++ adds two more builtin types to the set defined for C. These are
1528 the unknown type and the vtable record type. The unknown type, type
1529 16, is defined in terms of itself like the void type.
1531 The vtable record type, type 17, is defined as a structure type and
1532 then as a structure tag. The structure has four fields, delta, index,
1533 pfn, and delta2. pfn is the function pointer.
1535 << In boilerplate $vtbl_ptr_type, what are the fields delta,
1536 index, and delta2 used for? >>
1538 This basic type is present in all C++ programs even if there are no
1539 virtual methods defined.
1542 .stabs "struct_name:sym_desc(type)type_def(17)=type_desc(struct)struct_bytes(8)
1543 elem_name(delta):type_ref(short int),bit_offset(0),field_bits(16);
1544 elem_name(index):type_ref(short int),bit_offset(16),field_bits(16);
1545 elem_name(pfn):type_def(18)=type_desc(ptr to)type_ref(void),
1546 bit_offset(32),field_bits(32);
1547 elem_name(delta2):type_def(short int);bit_offset(32),field_bits(16);;"
1552 .stabs "$vtbl_ptr_type:t17=s8
1553 delta:6,0,16;index:6,16,16;pfn:18=*15,32,32;delta2:6,32,16;;"
1558 .stabs "name:sym_dec(struct tag)type_ref($vtbl_ptr_type)",N_LSYM,NIL,NIL,NIL
1562 .stabs "$vtbl_ptr_type:T17",128,0,0,0
1565 @node Simple classes
1566 @section Simple class definition
1568 The stabs describing C++ language features are an extension of the
1569 stabs describing C. Stabs representing C++ class types elaborate
1570 extensively on the stab format used to describe structure types in C.
1571 Stabs representing class type variables look just like stabs
1572 representing C language variables.
1574 Consider the following very simple class definition.
1580 int Ameth(int in, char other);
1584 The class baseA is represented by two stabs. The first stab describes
1585 the class as a structure type. The second stab describes a structure
1586 tag of the class type. Both stabs are of stab type N_LSYM. Since the
1587 stab is not located between an N_FUN and a N_LBRAC stab this indicates
1588 that the class is defined at file scope. If it were, then the N_LSYM
1589 would signify a local variable.
1591 A stab describing a C++ class type is similar in format to a stab
1592 describing a C struct, with each class member shown as a field in the
1593 structure. The part of the struct format describing fields is
1594 expanded to include extra information relevent to C++ class members.
1595 In addition, if the class has multiple base classes or virtual
1596 functions the struct format outside of the field parts is also
1599 In this simple example the field part of the C++ class stab
1600 representing member data looks just like the field part of a C struct
1601 stab. The section on protections describes how its format is
1602 sometimes extended for member data.
1604 The field part of a C++ class stab representing a member function
1605 differs substantially from the field part of a C struct stab. It
1606 still begins with `name:' but then goes on to define a new type number
1607 for the member function, describe its return type, its argument types,
1608 its protection level, any qualifiers applied to the method definition,
1609 and whether the method is virtual or not. If the method is virtual
1610 then the method description goes on to give the vtable index of the
1611 method, and the type number of the first base class defining the
1614 When the field name is a method name it is followed by two colons
1615 rather than one. This is followed by a new type definition for the
1616 method. This is a number followed by an equal sign and then the
1617 symbol descriptor `##', indicating a method type. This is followed by
1618 a type reference showing the return type of the method and a
1621 The format of an overloaded operator method name differs from that
1622 of other methods. It is "op$::XXXX." where XXXX is the operator name
1623 such as + or +=. The name ends with a period, and any characters except
1624 the period can occur in the XXXX string.
1626 The next part of the method description represents the arguments to
1627 the method, preceeded by a colon and ending with a semi-colon. The
1628 types of the arguments are expressed in the same way argument types
1629 are expressed in C++ name mangling. In this example an int and a char
1632 This is followed by a number, a letter, and an asterisk or period,
1633 followed by another semicolon. The number indicates the protections
1634 that apply to the member function. Here the 2 means public. The
1635 letter encodes any qualifier applied to the method definition. In
1636 this case A means that it is a normal function definition. The dot
1637 shows that the method is not virtual. The sections that follow
1638 elaborate further on these fields and describe the additional
1639 information present for virtual methods.
1643 .stabs "class_name:sym_desc(type)type_def(20)=type_desc(struct)struct_bytes(4)
1644 field_name(Adat):type(int),bit_offset(0),field_bits(32);
1646 method_name(Ameth)::type_def(21)=type_desc(method)return_type(int);
1647 :arg_types(int char);
1648 protection(public)qualifier(normal)virtual(no);;"
1653 .stabs "baseA:t20=s4Adat:1,0,32;Ameth::21=##1;:ic;2A.;;",128,0,0,0
1655 .stabs "class_name:sym_desc(struct tag)",N_LSYM,NIL,NIL,NIL
1657 .stabs "baseA:T20",128,0,0,0
1660 @node Class instance
1661 @section Class instance
1663 As shown above, describing even a simple C++ class definition is
1664 accomplished by massively extending the stab format used in C to
1665 describe structure types. However, once the class is defined, C stabs
1666 with no modifications can be used to describe class instances. The
1676 yields the following stab describing the class instance. It looks no
1677 different from a standard C stab describing a local variable.
1680 .stabs "name:type_ref(baseA)", N_LSYM, NIL, NIL, frame_ptr_offset
1684 .stabs "AbaseA:20",128,0,0,-20
1688 @section Method defintion
1690 The class definition shown above declares Ameth. The C++ source below
1695 baseA::Ameth(int in, char other)
1702 This method definition yields three stabs following the code of the
1703 method. One stab describes the method itself and following two
1704 describe its parameters. Although there is only one formal argument
1705 all methods have an implicit argument which is the `this' pointer.
1706 The `this' pointer is a pointer to the object on which the method was
1707 called. Note that the method name is mangled to encode the class name
1708 and argument types. << Name mangling is not described by this
1709 document - Is there already such a doc? >>
1712 .stabs "name:symbol_desriptor(global function)return_type(int)",
1713 N_FUN, NIL, NIL, code_addr_of_method_start
1715 .stabs "Ameth__5baseAic:F1",36,0,0,_Ameth__5baseAic
1718 Here is the stab for the `this' pointer implicit argument. The name
1719 of the `this' pointer is always $t. Type 19, the `this' pointer is
1720 defined as a pointer to type 20, baseA, but a stab defining baseA has
1721 not yet been emited. Since the compiler knows it will be emited
1722 shortly, here it just outputs a cross reference to the undefined
1723 symbol, by prefixing the symbol name with xs.
1726 .stabs "name:sym_desc(register param)type_def(19)=
1727 type_desc(ptr to)type_ref(baseA)=
1728 type_desc(cross-reference to)baseA:",N_RSYM,NIL,NIL,register_number
1730 .stabs "$t:P19=*20=xsbaseA:",64,0,0,8
1733 The stab for the explicit integer argument looks just like a parameter
1734 to a C function. The last field of the stab is the offset from the
1735 argument pointer, which in most systems is the same as the frame
1739 .stabs "name:sym_desc(value parameter)type_ref(int)",
1740 N_PSYM,NIL,NIL,offset_from_arg_ptr
1742 .stabs "in:p1",160,0,0,72
1745 << The examples that follow are based on A1.C >>
1748 @section Protections
1751 In the simple class definition shown above all member data and
1752 functions were publicly accessable. The example that follows
1753 contrasts public, protected and privately accessable fields and shows
1754 how these protections are encoded in C++ stabs.
1756 Protections for class member data are signified by two characters
1757 embeded in the stab defining the class type. These characters are
1758 located after the name: part of the string. /0 means private, /1
1759 means protected, and /2 means public. If these characters are omited
1760 this means that the member is public. The following C++ source:
1774 generates the following stab to describe the class type all_data.
1777 .stabs "class_name:sym_desc(type)type_def(19)=type_desc(struct)struct_bytes
1778 data_name:/protection(private)type_ref(int),bit_offset,num_bits;
1779 data_name:/protection(protected)type_ref(char),bit_offset,num_bits;
1780 data_name:(/num omited, private)type_ref(float),bit_offset,num_bits;;"
1785 .stabs "all_data:t19=s12
1786 priv_dat:/01,0,32;prot_dat:/12,32,8;pub_dat:12,64,32;;",128,0,0,0
1789 Protections for member functions are signified by one digit embeded in
1790 the field part of the stab describing the method. The digit is 0 if
1791 private, 1 if protected and 2 if public. Consider the C++ class
1795 class all_methods @{
1797 int priv_meth(int in)@{return in;@};
1799 char protMeth(char in)@{return in;@};
1801 float pubMeth(float in)@{return in;@};
1805 It generates the following stab. The digit in question is to the left
1806 of an `A' in each case. Notice also that in this case two symbol
1807 descriptors apply to the class name struct tag and struct type.
1810 .stabs "class_name:sym_desc(struct tag&type)type_def(21)=
1811 sym_desc(struct)struct_bytes(1)
1812 meth_name::type_def(22)=sym_desc(method)returning(int);
1813 :args(int);protection(private)modifier(normal)virtual(no);
1814 meth_name::type_def(23)=sym_desc(method)returning(char);
1815 :args(char);protection(protected)modifier(normal)virual(no);
1816 meth_name::type_def(24)=sym_desc(method)returning(float);
1817 :args(float);protection(public)modifier(normal)virtual(no);;",
1822 .stabs "all_methods:Tt21=s1priv_meth::22=##1;:i;0A.;protMeth::23=##2;:c;1A.;
1823 pubMeth::24=##12;:f;2A.;;",128,0,0,0
1826 @node Method Modifiers
1827 @section Method Modifiers (const, volatile, const volatile)
1831 In the class example described above all the methods have the normal
1832 modifier. This method modifier information is located just after the
1833 protection information for the method. This field has four possible
1834 character values. Normal methods use A, const methods use B, volatile
1835 methods use C, and const volatile methods use D. Consider the class
1841 int ConstMeth (int arg) const @{ return arg; @};
1842 char VolatileMeth (char arg) volatile @{ return arg; @};
1843 float ConstVolMeth (float arg) const volatile @{return arg; @};
1847 This class is described by the following stab:
1850 .stabs "class(A):sym_desc(struct)type_def(20)=type_desc(struct)struct_bytes(1)
1851 meth_name(ConstMeth)::type_def(21)sym_desc(method)
1852 returning(int);:arg(int);protection(public)modifier(const)virtual(no);
1853 meth_name(VolatileMeth)::type_def(22)=sym_desc(method)
1854 returning(char);:arg(char);protection(public)modifier(volatile)virt(no)
1855 meth_name(ConstVolMeth)::type_def(23)=sym_desc(method)
1856 returning(float);:arg(float);protection(public)modifer(const volatile)
1857 virtual(no);;", @dots{}
1861 .stabs "A:T20=s1ConstMeth::21=##1;:i;2B.;VolatileMeth::22=##2;:c;2C.;
1862 ConstVolMeth::23=##12;:f;2D.;;",128,0,0,0
1865 @node Virtual Methods
1866 @section Virtual Methods
1868 << The following examples are based on a4.C >>
1870 The presence of virtual methods in a class definition adds additional
1871 data to the class description. The extra data is appended to the
1872 description of the virtual method and to the end of the class
1873 description. Consider the class definition below:
1879 virtual int A_virt (int arg) @{ return arg; @};
1883 This results in the stab below describing class A. It defines a new
1884 type (20) which is an 8 byte structure. The first field of the class
1885 struct is Adat, an integer, starting at structure offset 0 and
1888 The second field in the class struct is not explicitly defined by the
1889 C++ class definition but is implied by the fact that the class
1890 contains a virtual method. This field is the vtable pointer. The
1891 name of the vtable pointer field starts with $vf and continues with a
1892 type reference to the class it is part of. In this example the type
1893 reference for class A is 20 so the name of its vtable pointer field is
1894 $vf20, followed by the usual colon.
1896 Next there is a type definition for the vtable pointer type (21).
1897 This is in turn defined as a pointer to another new type (22).
1899 Type 22 is the vtable itself, which is defined as an array, indexed by
1900 integers, with a high bound of 1, and elements of type 17. Type 17
1901 was the vtable record type defined by the boilerplate C++ type
1902 definitions, as shown earlier.
1904 The bit offset of the vtable pointer field is 32. The number of bits
1905 in the field are not specified when the field is a vtable pointer.
1907 Next is the method definition for the virtual member function A_virt.
1908 Its description starts out using the same format as the non-virtual
1909 member functions described above, except instead of a dot after the
1910 `A' there is an asterisk, indicating that the function is virtual.
1911 Since is is virtual some addition information is appended to the end
1912 of the method description.
1914 The first number represents the vtable index of the method. This is a
1915 32 bit unsigned number with the high bit set, followed by a
1918 The second number is a type reference to the first base class in the
1919 inheritence hierarchy defining the virtual member function. In this
1920 case the class stab describes a base class so the virtual function is
1921 not overriding any other definition of the method. Therefore the
1922 reference is to the type number of the class that the stab is
1925 This is followed by three semi-colons. One marks the end of the
1926 current sub-section, one marks the end of the method field, and the
1927 third marks the end of the struct definition.
1929 For classes containing virtual functions the very last section of the
1930 string part of the stab holds a type reference to the first base
1931 class. This is preceeded by `~%' and followed by a final semi-colon.
1934 .stabs "class_name(A):type_def(20)=sym_desc(struct)struct_bytes(8)
1935 field_name(Adat):type_ref(int),bit_offset(0),field_bits(32);
1936 field_name(A virt func ptr):type_def(21)=type_desc(ptr to)type_def(22)=
1937 sym_desc(array)index_type_ref(int);NIL;elem_type_ref(vtbl elem type);
1939 meth_name(A_virt)::typedef(23)=sym_desc(method)returning(int);
1940 :arg_type(int),protection(public)normal(yes)virtual(yes)
1941 vtable_index(1);class_first_defining(A);;;~%first_base(A);",
1946 .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
1950 @section Inheritance
1952 Stabs describing C++ derived classes include additional sections that
1953 describe the inheritence hierarchy of the class. A derived class stab
1954 also encodes the number of base classes. For each base class it tells
1955 if the base class is virtual or not, and if the inheritence is private
1956 or public. It also gives the offset into the object of the portion of
1957 the object corresponding to each base class.
1959 This additional information is embeded in the class stab following the
1960 number of bytes in the struct. First the number of base classes
1961 appears bracketed by an exclamation point and a comma.
1963 Then for each base type there repeats a series: two digits, a number,
1964 a comma, another number, and a semi-colon.
1966 The first of the two digits is 1 if the base class is virtual and 0 if
1967 not. The second digit is 2 if the derivation is public and 0 if not.
1969 The number following the first two digits is the offset from the start
1970 of the object to the part of the object pertaining to the base class.
1972 After the comma, the second number is a type_descriptor for the base
1973 type. Finally a semi-colon ends the series, which repeats for each
1976 The source below defines three base classes A, B, and C and the
1984 virtual int A_virt (int arg) @{ return arg; @};
1990 virtual int B_virt (int arg) @{return arg; @};
1996 virtual int C_virt (int arg) @{return arg; @};
1999 class D : A, virtual B, public C @{
2002 virtual int A_virt (int arg ) @{ return arg+1; @};
2003 virtual int B_virt (int arg) @{ return arg+2; @};
2004 virtual int C_virt (int arg) @{ return arg+3; @};
2005 virtual int D_virt (int arg) @{ return arg; @};
2009 Class stabs similar to the ones described earlier are generated for
2012 @c FIXME!!! the linebreaks in the following example probably make the
2013 @c examples literally unusable, but I don't know any other way to get
2014 @c them on the page.
2016 .stabs "A:T20=s8Adat:1,0,32;$vf20:21=*22=ar1;0;1;17,32;
2017 A_virt::23=##1;:i;2A*-2147483647;20;;;~%20;",128,0,0,0
2019 .stabs "B:Tt25=s8Bdat:1,0,32;$vf25:21,32;B_virt::26=##1;
2020 :i;2A*-2147483647;25;;;~%25;",128,0,0,0
2022 .stabs "C:Tt28=s8Cdat:1,0,32;$vf28:21,32;C_virt::29=##1;
2023 :i;2A*-2147483647;28;;;~%28;",128,0,0,0
2026 In the stab describing derived class D below, the information about
2027 the derivation of this class is encoded as follows.
2030 .stabs "derived_class_name:symbol_descriptors(struct tag&type)=
2031 type_descriptor(struct)struct_bytes(32)!num_bases(3),
2032 base_virtual(no)inheritence_public(no)base_offset(0),
2033 base_class_type_ref(A);
2034 base_virtual(yes)inheritence_public(no)base_offset(NIL),
2035 base_class_type_ref(B);
2036 base_virtual(no)inheritence_public(yes)base_offset(64),
2037 base_class_type_ref(C); @dots{}
2040 @c FIXME! fake linebreaks.
2042 .stabs "D:Tt31=s32!3,000,20;100,25;0264,28;$vb25:24,128;Ddat:
2043 1,160,32;A_virt::32=##1;:i;2A*-2147483647;20;;B_virt:
2044 :32:i;2A*-2147483647;25;;C_virt::32:i;2A*-2147483647;
2045 28;;D_virt::32:i;2A*-2147483646;31;;;~%20;",128,0,0,0
2048 @node Virtual base classes
2049 @section Virtual Base Classes
2051 A derived class object consists of a concatination in memory of the
2052 data areas defined by each base class, starting with the leftmost and
2053 ending with the rightmost in the list of base classes. The exception
2054 to this rule is for virtual inheritence. In the example above, class
2055 D inherits virtually from base class B. This means that an instance
2056 of a D object will not contain it's own B part but merely a pointer to
2057 a B part, known as a virtual base pointer.
2059 In a derived class stab, the base offset part of the derivation
2060 information, described above, shows how the base class parts are
2061 ordered. The base offset for a virtual base class is always given as
2062 0. Notice that the base offset for B is given as 0 even though B is
2063 not the first base class. The first base class A starts at offset 0.
2065 The field information part of the stab for class D describes the field
2066 which is the pointer to the virtual base class B. The vbase pointer
2067 name is $vb followed by a type reference to the virtual base class.
2068 Since the type id for B in this example is 25, the vbase pointer name
2071 @c FIXME!! fake linebreaks below
2073 .stabs "D:Tt31=s32!3,000,20;100,25;0264,28;$vb25:24,128;Ddat:1,
2074 160,32;A_virt::32=##1;:i;2A*-2147483647;20;;B_virt::32:i;
2075 2A*-2147483647;25;;C_virt::32:i;2A*-2147483647;28;;D_virt:
2076 :32:i;2A*-2147483646;31;;;~%20;",128,0,0,0
2079 Following the name and a semicolon is a type reference describing the
2080 type of the virtual base class pointer, in this case 24. Type 24 was
2081 defined earlier as the type of the B class `this` pointer, $t. The
2082 `this' pointer for a class is a pointer to the class type.
2085 .stabs "$t:P24=*25=xsB:",64,0,0,8
2088 Finally the field offset part of the vbase pointer field description
2089 shows that the vbase pointer is the first field in the D object,
2090 before any data fields defined by the class. The layout of a D class
2091 object is a follows, Adat at 0, the vtable pointer for A at 32, Cdat
2092 at 64, the vtable pointer for C at 96, the virtual ase pointer for B
2093 at 128, and Ddat at 160.
2096 @node Static Members
2097 @section Static Members
2100 << re-arrange - this has nothing to do with static members >>
2102 The data area for a class is a concatenation of the space used by the
2103 data members of the class. If the class has virtual methods a vtable
2104 pointer follows the class data. The field offset part of each field
2105 description in the class stab shows this ordering.
2107 << how is this reflected in stabs? >>
2110 @section Nested types
2112 C++ allows a type to be defined nested "inside" a class.
2113 Such types follow the same naming rule as class members:
2114 The name of a nested type is only visible inside the class,
2115 or when qualified using @code{::} notation. In that respect,
2116 a nested type "member" is rather like a static member.
2117 In fact, the stabs syntax used for nested types is similar to
2118 that used for static members.
2131 ios::io_state Fail()
2133 return ios::failbit;
2139 The relevant part of the assembly code is:
2141 .stabs ":t20=ebadbit:4,failbit:2,eofbit:1,goodbit:0,;",128,0,0,0
2142 .stabs "ios:T21=s4state:20,0,32;io_state:/220:!'ios::io_state';;",128,0,0,0
2143 .stabs "ios:Tt21",128,0,0,0
2144 .stabs "Fail__Fv:F20",36,0,0,_Fail__Fv
2145 .stabs "my_ios:G21",32,0,0,0
2146 .common _my_ios,4,"bss"
2149 The first line declares type 20 to be an enum. It gives it the
2150 name @code{ios::io_state}. The name is suppressed because @code{io_state}
2151 is not a globally visible name.)
2153 The second line defines the @code{ios} type.
2154 The text @code{io_state:/220:!'ios::io_state';} declares that
2155 @code{io_state} is a type "member". The @code{/2} specifies
2156 public visibility, just like a regular member.
2157 This is followed by the type being defined (type 20), the
2158 magic characters @code{:!} to indicate that we're declaring a nested
2159 type, followed by the complete name of the type.
2160 Single quotes surrond the name, because of the embedded @code{::}.
2162 Teh debugger uses the name @code{ios::io_state} to back-patch the name
2166 @appendix Example2.c - source code for extended example
2170 2 register int g_bar asm ("%g5");
2171 3 static int s_g_repeat = 2;
2177 9 char s_char_vec[8];
2178 10 struct s_tag* s_next;
2181 13 typedef struct s_tag s_typedef;
2183 15 char char_vec[3] = @{'a','b','c'@};
2185 17 main (argc, argv)
2189 21 static float s_flap;
2191 23 for (times=0; times < s_g_repeat; times++)@{
2193 25 printf ("Hello world\n");
2197 29 enum e_places @{first,second=3,last@};
2199 31 static s_proc (s_arg, s_ptr_arg, char_vec)
2201 33 s_typedef* s_ptr_arg;
2215 @appendix Example2.s - assembly code for extended example
2219 2 .stabs "/cygint/s1/users/jcm/play/",100,0,0,Ltext0
2220 3 .stabs "example2.c",100,0,0,Ltext0
2223 6 .stabs "int:t1=r1;-2147483648;2147483647;",128,0,0,0
2224 7 .stabs "char:t2=r2;0;127;",128,0,0,0
2225 8 .stabs "long int:t3=r1;-2147483648;2147483647;",128,0,0,0
2226 9 .stabs "unsigned int:t4=r1;0;-1;",128,0,0,0
2227 10 .stabs "long unsigned int:t5=r1;0;-1;",128,0,0,0
2228 11 .stabs "short int:t6=r1;-32768;32767;",128,0,0,0
2229 12 .stabs "long long int:t7=r1;0;-1;",128,0,0,0
2230 13 .stabs "short unsigned int:t8=r1;0;65535;",128,0,0,0
2231 14 .stabs "long long unsigned int:t9=r1;0;-1;",128,0,0,0
2232 15 .stabs "signed char:t10=r1;-128;127;",128,0,0,0
2233 16 .stabs "unsigned char:t11=r1;0;255;",128,0,0,0
2234 17 .stabs "float:t12=r1;4;0;",128,0,0,0
2235 18 .stabs "double:t13=r1;8;0;",128,0,0,0
2236 19 .stabs "long double:t14=r1;8;0;",128,0,0,0
2237 20 .stabs "void:t15=15",128,0,0,0
2238 21 .stabs "g_foo:G2",32,0,0,0
2243 26 .stabs "s_g_repeat:S1",38,0,0,_s_g_repeat
2247 @c FIXME! fake linebreak in line 30
2248 30 .stabs "s_tag:T16=s20s_int:1,0,32;s_float:12,32,32;s_char_vec:
2249 17=ar1;0;7;2,64,64;s_next:18=*16,128,32;;",128,0,0,0
2250 31 .stabs "s_typedef:t16",128,0,0,0
2251 32 .stabs "char_vec:G19=ar1;0;2;2",32,0,0,0
2252 33 .global _char_vec
2258 39 .reserve _s_flap.0,4,"bss",4
2262 43 .ascii "Hello world\12\0"
2267 48 .stabn 68,0,20,LM1
2270 51 save %sp,-144,%sp
2277 58 .stabn 68,0,23,LM2
2281 62 sethi %hi(_s_g_repeat),%o0
2283 64 ld [%o0+%lo(_s_g_repeat)],%o0
2288 69 .stabn 68,0,25,LM3
2290 71 sethi %hi(LC0),%o1
2291 72 or %o1,%lo(LC0),%o0
2294 75 .stabn 68,0,26,LM4
2297 78 .stabn 68,0,23,LM5
2305 86 .stabn 68,0,27,LM6
2308 89 .stabn 68,0,27,LM7
2313 94 .stabs "main:F1",36,0,0,_main
2314 95 .stabs "argc:p1",160,0,0,68
2315 96 .stabs "argv:p20=*21=*2",160,0,0,72
2316 97 .stabs "s_flap:V12",40,0,0,_s_flap.0
2317 98 .stabs "times:1",128,0,0,-20
2318 99 .stabn 192,0,0,LBB2
2319 100 .stabs "inner:1",128,0,0,-24
2320 101 .stabn 192,0,0,LBB3
2321 102 .stabn 224,0,0,LBE3
2322 103 .stabn 224,0,0,LBE2
2323 104 .stabs "e_places:T22=efirst:0,second:3,last:4,;",128,0,0,0
2324 @c FIXME: fake linebreak in line 105
2325 105 .stabs "u_tag:T23=u4u_int:1,0,32;u_float:12,0,32;u_char:21,0,32;;",
2330 109 .stabn 68,0,35,LM8
2333 112 save %sp,-120,%sp
2339 118 .stabn 68,0,41,LM9
2342 121 .stabn 68,0,41,LM10
2347 126 .stabs "s_proc:f1",36,0,0,_s_proc
2348 127 .stabs "s_arg:p16",160,0,0,0
2349 128 .stabs "s_ptr_arg:p18",160,0,0,72
2350 129 .stabs "char_vec:p21",160,0,0,76
2351 130 .stabs "an_u:23",128,0,0,-20
2352 131 .stabn 192,0,0,LBB4
2353 132 .stabn 224,0,0,LBE4
2354 133 .stabs "g_bar:r1",64,0,0,5
2355 134 .stabs "g_pf:G24=*25=f1",32,0,0,0
2356 135 .common _g_pf,4,"bss"
2357 136 .stabs "g_an_s:G16",32,0,0,0
2358 137 .common _g_an_s,20,"bss"
2362 @node Quick reference
2363 @appendix Quick reference
2366 * Stab types:: Table A: Symbol types from stabs
2367 * Assembler types:: Table B: Symbol types from assembler and linker
2368 * Symbol descriptors:: Table C
2369 * Type Descriptors:: Table D
2373 @section Table A: Symbol types from stabs
2375 Table A lists stab types sorted by type number. Stab type numbers are
2376 32 and greater. This is the full list of stab numbers, including stab
2377 types that are used in languages other than C.
2379 The #define names for these stab types are defined in:
2380 devo/include/aout/stab.def
2383 type type #define used to describe
2384 dec hex name source program feature
2385 ------------------------------------------------
2386 32 0x20 N_GYSM global symbol
2387 34 0X22 N_FNAME function name (for BSD Fortran)
2388 36 0x24 N_FUN function name or text segment variable for C
2389 38 0x26 N_STSYM static symbol (data segment w/internal linkage)
2390 40 0x28 N_LCSYM .lcomm symbol(BSS-seg variable w/internal linkage)
2391 42 0x2a N_MAIN Name of main routine (not used in C)
2392 48 0x30 N_PC global symbol (for Pascal)
2393 50 0x32 N_NSYMS number of symbols (according to Ultrix V4.0)
2394 52 0x34 N_NOMAP no DST map for sym (according to Ultrix V4.0)
2395 64 0x40 N_RSYM register variable
2396 66 0x42 N_M2C Modula-2 compilation unit
2397 68 0x44 N_SLINE line number in text segment
2398 70 0x46 N_DSLINE line number in data segment
2400 72 0x48 N_BSLINE line number in bss segment
2401 72 0x48 N_BROWS Sun source code browser, path to .cb file
2403 74 0x4a N_DEFD GNU Modula2 definition module dependency
2405 80 0x50 N_EHDECL GNU C++ exception variable
2406 80 0x50 N_MOD2 Modula2 info "for imc" (according to Ultrix V4.0)
2408 84 0x54 N_CATCH GNU C++ "catch" clause
2409 96 0x60 N_SSYM structure of union element
2410 100 0x64 N_SO path and name of source file
2411 128 0x80 N_LSYM automatic var in the stack
2412 (also used for type desc.)
2413 130 0x82 N_BINCL beginning of an include file (Sun only)
2414 132 0x84 N_SOL Name of sub-source (#include) file.
2415 160 0xa0 N_PSYM parameter variable
2416 162 0xa2 N_EINCL end of an include file
2417 164 0xa4 N_ENTRY alternate entry point
2418 192 0xc0 N_LBRAC beginning of a lexical block
2419 194 0xc2 N_EXCL place holder for a deleted include file
2420 196 0xc4 N_SCOPE modula2 scope information (Sun linker)
2421 224 0xe0 N_RBRAC end of a lexical block
2422 226 0xe2 N_BCOMM begin named common block
2423 228 0xe4 N_ECOMM end named common block
2424 232 0xe8 N_ECOML end common (local name)
2426 << used on Gould systems for non-base registers syms >>
2427 240 0xf0 N_NBTEXT ??
2428 242 0xf2 N_NBDATA ??
2434 @node Assembler types
2435 @section Table B: Symbol types from assembler and linker
2437 Table B shows the types of symbol table entries that hold assembler
2440 The #define names for these n_types values are defined in
2441 /include/aout/aout64.h
2445 n_type n_type name used to describe
2446 ------------------------------------------
2447 1 0x0 N_UNDF undefined symbol
2448 2 0x2 N_ABS absolute symbol -- defined at a particular address
2449 3 0x3 extern " (vs. file scope)
2450 4 0x4 N_TEXT text symbol -- defined at offset in text segment
2451 5 0x5 extern " (vs. file scope)
2452 6 0x6 N_DATA data symbol -- defined at offset in data segment
2453 7 0x7 extern " (vs. file scope)
2454 8 0x8 N_BSS BSS symbol -- defined at offset in zero'd segment
2455 9 extern " (vs. file scope)
2457 12 0x0C N_FN_SEQ func name for Sequent compilers (stab exception)
2459 49 0x12 N_COMM common sym -- visable after shared lib dynamic link
2460 31 0x1f N_FN file name of a .o file
2463 @node Symbol descriptors
2464 @section Table C: Symbol descriptors
2468 -------------------------------------------------
2469 (empty) local variable
2475 S static global variable
2477 T enumeration, struct or type tag
2478 V static local variable
2481 @node Type Descriptors
2482 @section Table D: Type Descriptors
2486 -------------------------------------
2487 (empty) type reference
2493 u union specifications
2498 @node Expanded reference
2499 @appendix Expanded reference by stab type.
2503 The first line is the symbol type expressed in decimal, hexadecimal,
2504 and as a #define (see devo/include/aout/stab.def).
2506 The second line describes the language constructs the symbol type
2509 The third line is the stab format with the significant stab fields
2510 named and the rest NIL.
2512 Subsequent lines expand upon the meaning and possible values for each
2513 significant stab field. # stands in for the type descriptor.
2515 Finally, any further information.
2518 * N_GSYM:: Global variable
2519 * N_FNAME:: Function name (BSD Fortran)
2520 * N_FUN:: C Function name or text segment variable
2521 * N_STSYM:: Initialized static symbol
2522 * N_LCSYM:: Uninitialized static symbol
2523 * N_MAIN:: Name of main routine (not for C)
2524 * N_PC:: Pascal global symbol
2525 * N_NSYMS:: Number of symbols
2526 * N_NOMAP:: No DST map
2527 * N_RSYM:: Register variable
2528 * N_M2C:: Modula-2 compilation unit
2529 * N_SLINE:: Line number in text segment
2530 * N_DSLINE:: Line number in data segment
2531 * N_BSLINE:: Line number in bss segment
2532 * N_BROWS:: Path to .cb file for Sun source code browser
2533 * N_DEFD:: GNU Modula2 definition module dependency
2534 * N_EHDECL:: GNU C++ exception variable
2535 * N_MOD2:: Modula2 information "for imc"
2536 * N_CATCH:: GNU C++ "catch" clause
2537 * N_SSYM:: Structure or union element
2538 * N_SO:: Source file containing main
2539 * N_LSYM:: Automatic variable
2540 * N_BINCL:: Beginning of include file (Sun only)
2541 * N_SOL:: Name of include file
2542 * N_PSYM:: Parameter variable
2543 * N_EINCL:: End of include file
2544 * N_ENTRY:: Alternate entry point
2545 * N_LBRAC:: Beginning of lexical block
2546 * N_EXCL:: Deleted include file
2547 * N_SCOPE:: Modula2 scope information (Sun only)
2548 * N_RBRAC:: End of lexical block
2549 * N_BCOMM:: Begin named common block
2550 * N_ECOMM:: End named common block
2551 * N_ECOML:: End common
2552 * Gould:: non-base register symbols used on Gould systems
2553 * N_LENG:: Length of preceding entry
2557 @section 32 - 0x20 - N_GYSM
2562 .stabs "name", N_GSYM, NIL, NIL, NIL
2566 "name" -> "symbol_name:#type"
2570 Only the "name" field is significant. the location of the variable is
2571 obtained from the corresponding external symbol.
2574 @section 34 - 0x22 - N_FNAME
2575 Function name (for BSD Fortran)
2578 .stabs "name", N_FNAME, NIL, NIL, NIL
2582 "name" -> "function_name"
2585 Only the "name" field is significant. The location of the symbol is
2586 obtained from the corresponding extern symbol.
2589 @section 36 - 0x24 - N_FUN
2590 Function name or text segment variable for C.
2593 .stabs "name", N_FUN, NIL, desc, value
2597 @exdent @emph{For functions:}
2598 "name" -> "proc_name:#return_type"
2599 # -> F (global function)
2601 desc -> line num for proc start. (GCC doesn't set and DBX doesn't miss it.)
2602 value -> Code address of proc start.
2604 @exdent @emph{For text segment variables:}
2605 <<How to create one?>>
2609 @section 38 - 0x26 - N_STSYM
2610 Initialized static symbol (data segment w/internal linkage).
2613 .stabs "name", N_STSYM, NIL, NIL, value
2617 "name" -> "symbol_name#type"
2618 # -> S (scope global to compilation unit)
2619 -> V (scope local to a procedure)
2620 value -> Data Address
2624 @section 40 - 0x28 - N_LCSYM
2625 Unitialized static (.lcomm) symbol(BSS segment w/internal linkage).
2628 .stabs "name", N_LCLSYM, NIL, NIL, value
2632 "name" -> "symbol_name#type"
2633 # -> S (scope global to compilation unit)
2634 -> V (scope local to procedure)
2635 value -> BSS Address
2639 @section 42 - 0x2a - N_MAIN
2640 Name of main routine (not used in C)
2643 .stabs "name", N_MAIN, NIL, NIL, NIL
2647 "name" -> "name_of_main_routine"
2651 @section 48 - 0x30 - N_PC
2652 Global symbol (for Pascal)
2655 .stabs "name", N_PC, NIL, NIL, value
2659 "name" -> "symbol_name" <<?>>
2660 value -> supposedly the line number (stab.def is skeptical)
2666 global pascal symbol: name,,0,subtype,line
2671 @section 50 - 0x32 - N_NSYMS
2672 Number of symbols (according to Ultrix V4.0)
2675 0, files,,funcs,lines (stab.def)
2679 @section 52 - 0x34 - N_NOMAP
2680 no DST map for sym (according to Ultrix V4.0)
2683 name, ,0,type,ignored (stab.def)
2687 @section 64 - 0x40 - N_RSYM
2691 .stabs "name:type",N_RSYM,0,RegSize,RegNumber (Sun doc)
2695 @section 66 - 0x42 - N_M2C
2696 Modula-2 compilation unit
2699 .stabs "name", N_M2C, 0, desc, value
2703 "name" -> "unit_name,unit_time_stamp[,code_time_stamp]
2705 value -> 0 (main unit)
2710 @section 68 - 0x44 - N_SLINE
2711 Line number in text segment
2714 .stabn N_SLINE, 0, desc, value
2719 value -> code_address (relocatable addr where the corresponding code starts)
2722 For single source lines that generate discontiguous code, such as flow
2723 of control statements, there may be more than one N_SLINE stab for the
2724 same source line. In this case there is a stab at the start of each
2725 code range, each with the same line number.
2728 @section 70 - 0x46 - N_DSLINE
2729 Line number in data segment
2732 .stabn N_DSLINE, 0, desc, value
2737 value -> data_address (relocatable addr where the corresponding code
2741 See comment for N_SLINE above.
2744 @section 72 - 0x48 - N_BSLINE
2745 Line number in bss segment
2748 .stabn N_BSLINE, 0, desc, value
2753 value -> bss_address (relocatable addr where the corresponding code
2757 See comment for N_SLINE above.
2760 @section 72 - 0x48 - N_BROWS
2761 Sun source code browser, path to .cb file
2764 "path to associated .cb file"
2766 Note: type field value overlaps with N_BSLINE
2769 @section 74 - 0x4a - N_DEFD
2770 GNU Modula2 definition module dependency
2772 GNU Modula-2 definition module dependency. Value is the modification
2773 time of the definition file. Other is non-zero if it is imported with
2774 the GNU M2 keyword %INITIALIZE. Perhaps N_M2C can be used if there
2775 are enough empty fields?
2778 @section 80 - 0x50 - N_EHDECL
2779 GNU C++ exception variable <<?>>
2781 "name is variable name"
2783 Note: conflicts with N_MOD2.
2786 @section 80 - 0x50 - N_MOD2
2787 Modula2 info "for imc" (according to Ultrix V4.0)
2789 Note: conflicts with N_EHDECL <<?>>
2792 @section 84 - 0x54 - N_CATCH
2793 GNU C++ "catch" clause
2795 GNU C++ `catch' clause. Value is its address. Desc is nonzero if
2796 this entry is immediately followed by a CAUGHT stab saying what
2797 exception was caught. Multiple CAUGHT stabs means that multiple
2798 exceptions can be caught here. If Desc is 0, it means all exceptions
2802 @section 96 - 0x60 - N_SSYM
2803 Structure or union element
2805 Value is offset in the structure.
2807 <<?looking at structs and unions in C I didn't see these>>
2810 @section 100 - 0x64 - N_SO
2811 Path and name of source file containing main routine
2814 .stabs "name", N_SO, NIL, NIL, value
2818 "name" -> /path/to/source/file
2819 -> source_file_terminal_name
2821 value -> the starting text address of the compilation.
2824 These are found two in a row. The name field of the first N_SO
2825 contains the path to the source file. The name field of the second
2826 N_SO contains the terminal name of the source file itself.
2829 @section 128 - 0x80 - N_LSYM
2830 Automatic var in the stack (also used for type descriptors.)
2833 .stabs "name" N_LSYM, NIL, NIL, value
2837 @exdent @emph{For stack based local variables:}
2839 "name" -> name of the variable
2840 value -> offset from frame pointer (negative)
2842 @exdent @emph{For type descriptors:}
2844 "name" -> "name_of_the_type:#type"
2847 type -> type_ref (or) type_def
2849 type_ref -> type_number
2850 type_def -> type_number=type_desc etc.
2853 Type may be either a type reference or a type definition. A type
2854 reference is a number that refers to a previously defined type. A
2855 type definition is the number that will refer to this type, followed
2856 by an equals sign, a type descriptor and the additional data that
2857 defines the type. See the Table D for type descriptors and the
2858 section on types for what data follows each type descriptor.
2861 @section 130 - 0x82 - N_BINCL
2863 Beginning of an include file (Sun only)
2865 Beginning of an include file. Only Sun uses this. In an object file,
2866 only the name is significant. The Sun linker puts data into some of
2870 @section 132 - 0x84 - N_SOL
2872 Name of a sub-source file (#include file). Value is starting address
2877 @section 160 - 0xa0 - N_PSYM
2882 stabs. "name", N_PSYM, NIL, NIL, value
2886 "name" -> "param_name:#type"
2887 # -> p (value parameter)
2888 -> i (value parameter by reference, indirect access)
2889 -> v (variable parameter by reference)
2890 -> C ( read-only parameter, conformant array bound)
2891 -> x (confomant array value parameter)
2894 -> X (function result variable)
2895 -> b (based variable)
2897 value -> offset from the argument pointer (positive).
2900 On most machines the argument pointer is the same as the frame
2904 @section 162 - 0xa2 - N_EINCL
2906 End of an include file. This and N_BINCL act as brackets around the
2907 file's output. In an ojbect file, there is no significant data in
2908 this entry. The Sun linker puts data into some of the fields.
2912 @section 164 - 0xa4 - N_ENTRY
2914 Alternate entry point.
2915 Value is its address.
2919 @section 192 - 0xc0 - N_LBRAC
2921 Beginning of a lexical block (left brace). The variable defined
2922 inside the block precede the N_LBRAC symbol. Or can they follow as
2923 well as long as a new N_FUNC was not encountered. <<?>>
2926 .stabn N_LBRAC, NIL, NIL, value
2930 value -> code address of block start.
2934 @section 194 - 0xc2 - N_EXCL
2936 Place holder for a deleted include file. Replaces a N_BINCL and
2937 everything up to the corresponding N_EINCL. The Sun linker generates
2938 these when it finds multiple indentical copies of the symbols from an
2939 included file. This appears only in output from the Sun linker.
2943 @section 196 - 0xc4 - N_SCOPE
2945 Modula2 scope information (Sun linker)
2949 @section 224 - 0xe0 - N_RBRAC
2951 End of a lexical block (right brace)
2954 .stabn N_RBRAC, NIL, NIL, value
2958 value -> code address of the end of the block.
2962 @section 226 - 0xe2 - N_BCOMM
2964 Begin named common block.
2966 Only the name is significant.
2970 @section 228 - 0xe4 - N_ECOMM
2972 End named common block.
2974 Only the name is significant and it should match the N_BCOMM
2978 @section 232 - 0xe8 - N_ECOML
2980 End common (local name)
2986 @section Non-base registers on Gould systems
2987 << used on Gould systems for non-base registers syms, values assigned
2988 at random, need real info from Gould. >>
2992 240 0xf0 N_NBTEXT ??
2993 242 0xf2 N_NBDATA ??
3000 @section - 0xfe - N_LENG
3002 Second symbol entry containing a length-value for the preceding entry.
3003 The value is the length.
3006 @appendix Questions and anomalies
3010 For GNU C stabs defining local and global variables (N_LSYM and
3011 N_GSYM), the desc field is supposed to contain the source line number
3012 on which the variable is defined. In reality the desc field is always
3013 0. (This behavour is defined in dbxout.c and putting a line number in
3014 desc is controlled by #ifdef WINNING_GDB which defaults to false). Gdb
3015 supposedly uses this information if you say 'list var'. In reality
3016 var can be a variable defined in the program and gdb says `function
3020 In GNU C stabs there seems to be no way to differentiate tag types:
3021 structures, unions, and enums (symbol descriptor T) and typedefs
3022 (symbol descriptor t) defined at file scope from types defined locally
3023 to a procedure or other more local scope. They all use the N_LSYM
3024 stab type. Types defined at procedure scope are emited after the
3025 N_RBRAC of the preceding function and before the code of the
3026 procedure in which they are defined. This is exactly the same as
3027 types defined in the source file between the two procedure bodies.
3028 GDB overcompensates by placing all types in block #1 the block for
3029 symbols of file scope. This is true for default, -ansi and
3030 -traditional compiler options. (p0001063-gcc, p0001066-gdb)
3033 What ends the procedure scope? Is it the proc block's N_RBRAC or the
3034 next N_FUN? (I believe its the first.)
3037 The comment in xcoff.h says DBX_STATIC_CONST_VAR_CODE is used for
3038 static const variables. DBX_STATIC_CONST_VAR_CODE is set to N_FUN by
3039 default, in dbxout.c. If included, xcoff.h redefines it to N_STSYM.
3040 But testing the default behaviour, my Sun4 native example shows
3041 N_STSYM not N_FUN is used to describe file static initialized
3042 variables. (the code tests for TREE_READONLY(decl) &&
3043 !TREE_THIS_VOLATILE(decl) and if true uses DBX_STATIC_CONST_VAR_CODE).
3046 Global variable stabs don't have location information. This comes
3047 from the external symbol for the same variable. The external symbol
3048 has a leading underbar on the _name of the variable and the stab does
3049 not. How do we know these two symbol table entries are talking about
3050 the same symbol when their names are different?
3053 Can gcc be configured to output stabs the way the Sun compiler
3054 does, so that their native debugging tools work? <NO?> It doesn't by
3055 default. GDB reads either format of stab. (gcc or SunC). How about
3059 @node xcoff-differences
3060 @appendix Differences between GNU stabs in a.out and GNU stabs in xcoff
3062 (The AIX/RS6000 native object file format is xcoff with stabs)
3066 Instead of .stabs, xcoff uses .stabx.
3069 The data fields of an xcoff .stabx are in a different order than an
3070 a.out .stabs. The order is: string, value, type. The desc and null
3071 fields present in a.out stabs are missing in xcoff stabs. For N_GSYM
3072 the value field is the name of the symbol.
3075 BSD a.out stab types correspond to AIX xcoff storage classes. In general the
3076 mapping is N_STABTYPE becomes C_STABTYPE. Some stab types in a.out
3077 are not supported in xcoff. See Table E. for full mappings.
3080 initialised static N_STSYM and un-initialized static N_LCSYM both map
3081 to the C_STSYM storage class. But the destinction is preserved
3082 because in xcoff N_STSYM and N_LCSYM must be emited in a named static
3083 block. Begin the block with .bs s[RW] data_section_name for N_STSYM
3084 or .bs s bss_section_name for N_LCSYM. End the block with .es
3087 xcoff stabs describing tags and typedefs use the N_DECL (0x8c)instead
3088 of N_LSYM stab type.
3091 xcoff uses N_RPSYM (0x8e) instead of the N_RSYM stab type for register
3092 variables. If the register variable is also a value parameter, then
3093 use R instead of P for the symbol descriptor.
3096 xcoff uses negative numbers as type references to the basic types.
3097 There are no boilerplate type definitions emited for these basic
3098 types. << make table of basic types and type numbers for C >>
3101 xcoff .stabx sometimes don't have the name part of the string field.
3104 xcoff uses a .file stab type to represent the source file name. There
3105 is no stab for the path to the source file.
3108 xcoff uses a .line stab type to represent source lines. The format
3109 is: .line line_number.
3112 xcoff emits line numbers relative to the start of the current
3113 function. The start of a function is marked by .bf. If a function
3114 includes lines from a seperate file, then those line numbers are
3115 absolute line numbers in the <<sub-?>> file being compiled.
3118 The start of current include file is marked with: .bi "filename" and
3119 the end marked with .ei "filename"
3122 If the xcoff stab is a N_FUN (C_FUN) then follow the string field with
3123 ,. instead of just ,
3126 The symbol descriptor for register parameters is P for a.out and R for
3131 (I think that's it for .s file differences. They could stand to be
3132 better presented. This is just a list of what I have noticed so far.
3133 There are a *lot* of differences in the information in the symbol
3134 tables of the executable and object files.)
3136 Table E: mapping a.out stab types to xcoff storage classes
3139 stab type storage class
3140 -------------------------------
3149 N_RPSYM (0x8e) C_RPSYM
3159 N_DECL (0x8c) C_DECL
3176 @node Sun-differences
3177 @appendix Differences between GNU stabs and Sun native stabs.
3181 GNU C stabs define *all* types, file or procedure scope, as
3182 N_LSYM. Sun doc talks about using N_GSYM too.
3185 GNU C stabs use `ar' as type descriptor when defining arrays vs. just
3189 Stabs describing block scopes, N_LBRAC and N_RBRAC are supposed to
3190 contain the nesting level of the block in the desc field, re Sun doc.
3191 GNU stabs always have 0 in that field.
3194 Sun C stabs use type number pairs in the format (a,b) where a is a
3195 number starting with 1 and incremented for each sub-source file in the
3196 compilation. b is a number starting with 1 and incremented for each
3197 new type defined in the compilation. GNU C stabs use the type number
3198 alone, with no source file number.