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
70 * Constants:: Constants
72 * Example:: A comprehensive example in C
75 * Symbol tables:: Symbol information in symbol tables
76 * GNU Cplusplus stabs::
79 * Example2.c:: Source code for extended example
80 * Example2.s:: Assembly code for extended example
81 * Quick reference:: Various refernce tables
82 * Expanded reference:: Reference information by stab type
83 * Questions:: Questions and anomolies
84 * xcoff-differences:: Differences between GNU stabs in a.out
85 and GNU stabs in xcoff
86 * Sun-differences:: Differences between GNU stabs and Sun
93 @chapter Overview of stabs
95 @dfn{Stabs} refers to a format for information that describes a program
96 to a debugger. This format was apparently invented by
97 @c FIXME! <<name of inventor>> at
98 the University of California at Berkeley, for the @code{pdx} Pascal
99 debugger; the format has spread widely since then.
102 * Flow:: Overview of debugging information flow
103 * Stabs format:: Overview of stab format
104 * C example:: A simple example in C source
105 * Assembly code:: The simple example at the assembly level
109 @section Overview of debugging information flow
111 The GNU C compiler compiles C source in a @file{.c} file into assembly
112 language in a @file{.s} file, which is translated by the assembler into
113 a @file{.o} file, and then linked with other @file{.o} files and
114 libraries to produce an executable file.
116 With the @samp{-g} option, GCC puts additional debugging information in
117 the @file{.s} file, which is slightly transformed by the assembler and
118 linker, and carried through into the final executable. This debugging
119 information describes features of the source file like line numbers,
120 the types and scopes of variables, and functions, their parameters and
123 For some object file formats, the debugging information is
124 encapsulated in assembler directives known collectively as `stab' (symbol
125 table) directives, interspersed with the generated code. Stabs are
126 the native format for debugging information in the a.out and xcoff
127 object file formats. The GNU tools can also emit stabs in the coff
128 and ecoff object file formats.
130 The assembler adds the information from stabs to the symbol information
131 it places by default in the symbol table and the string table of the
132 @file{.o} file it is building. The linker consolidates the @file{.o}
133 files into one executable file, with one symbol table and one string
134 table. Debuggers use the symbol and string tables in the executable as
135 a source of debugging information about the program.
138 @section Overview of stab format
140 There are three overall formats for stab assembler directives
141 differentiated by the first word of the stab. The name of the directive
142 describes what combination of four possible data fields will follow. It
143 is either @code{.stabs} (string), @code{.stabn} (number), or
146 The overall format of each class of stab is:
149 .stabs "@var{string}",@var{type},0,@var{desc},@var{value}
150 .stabn @var{type},0,@var{desc},@var{value}
151 .stabd @var{type},0,@var{desc}
154 In general, in @code{.stabs} the @var{string} field contains name and type
155 information. For @code{.stabd} the value field is implicit and has the value
156 of the current file location. Otherwise the value field often
157 contains a relocatable address, frame pointer offset, or register
158 number, that maps to the source code element described by the stab.
160 The number in the type field gives some basic information about what
161 type of stab this is (or whether it @emph{is} a stab, as opposed to an
162 ordinary symbol). Each possible type number defines a different stab
163 type. The stab type further defines the exact interpretation of, and
164 possible values for, any remaining @code{"@var{string}"}, @var{desc}, or
165 @var{value} fields present in the stab. Table A (@pxref{Stab
166 types,,Table A: Symbol types from stabs}) lists in numeric order the
167 possible type field values for stab directives. The reference section
168 that follows Table A describes the meaning of the fields for each stab
169 type in detail. The examples that follow this overview introduce the
170 stab types in terms of the source code elements they describe.
172 For @code{.stabs} the @code{"@var{string}"} field holds the meat of the
173 debugging information. The generally unstructured nature of this field
174 is what makes stabs extensible. For some stab types the string field
175 contains only a name. For other stab types the contents can be a great
178 The overall format is of the @code{"@var{string}"} field is:
181 "@var{name}@r{[}:@var{symbol_descriptor}@r{]}
182 @r{[}@var{type_number}@r{[}=@var{type_descriptor} @r{@dots{}]]}"
185 @var{name} is the name of the symbol represented by the stab.
186 @var{name} can be omitted, which means the stab represents an unnamed
187 object. For example, @code{":t10=*2"} defines type 10 as a pointer to
188 type 2, but does not give the type a name. Omitting the @var{name}
189 field is supported by AIX dbx and GDB after about version 4.8, but not
192 The @var{symbol_descriptor} following the @samp{:} is an alphabetic
193 character that tells more specifically what kind of symbol the stab
194 represents. If the @var{symbol_descriptor} is omitted, but type
195 information follows, then the stab represents a local variable. For a
196 list of symbol_descriptors, see @ref{Symbol descriptors,,Table C: Symbol
199 The @samp{c} symbol descriptor is an exception in that it is not
200 followed by type information. @xref{Constants}.
202 Type information is either a @var{type_number}, or a
203 @samp{@var{type_number}=}. The @var{type_number} alone is a type
204 reference, referring directly to a type that has already been defined.
206 The @samp{@var{type_number}=} is a type definition, where the number
207 represents a new type which is about to be defined. The type definition
208 may refer to other types by number, and those type numbers may be
209 followed by @samp{=} and nested definitions.
211 In a type definition, if the character that follows the equals sign is
212 non-numeric then it is a @var{type_descriptor}, and tells what kind of
213 type is about to be defined. Any other values following the
214 @var{type_descriptor} vary, depending on the @var{type_descriptor}. If
215 a number follows the @samp{=} then the number is a @var{type_reference}.
216 This is described more thoroughly in the section on types. @xref{Type
217 Descriptors,,Table D: Type Descriptors}, for a list of
218 @var{type_descriptor} values.
220 There is an AIX extension for type attributes. Following the @samp{=}
221 is any number of type attributes. Each one starts with @samp{@@} and
222 ends with @samp{;}. Debuggers, including AIX's dbx, skip any type
223 attributes they do not recognize. The attributes are:
226 @item a@var{boundary}
227 @var{boundary} is an integer specifying the alignment. I assume that
228 applies to all variables of this type.
231 Size in bits of a variabe of this type.
234 Pointer class (for checking). Not sure what this means, or how
235 @var{integer} is interpreted.
238 Indicate this is a packed type, meaning that structure fields or array
239 elements are placed more closely in memory, to save memory at the
243 All this can make the @code{"@var{string}"} field quite long. All
244 versions of GDB, and some versions of DBX, can handle arbitrarily long
245 strings. But many versions of DBX cretinously limit the strings to
246 about 80 characters, so compilers which must work with such DBX's need
247 to split the @code{.stabs} directive into several @code{.stabs}
248 directives. Each stab duplicates exactly all but the
249 @code{"@var{string}"} field. The @code{"@var{string}"} field of
250 every stab except the last is marked as continued with a
251 double-backslash at the end. Removing the backslashes and concatenating
252 the @code{"@var{string}"} fields of each stab produces the original,
256 @section A simple example in C source
258 To get the flavor of how stabs describe source information for a C
259 program, let's look at the simple program:
264 printf("Hello world");
268 When compiled with @samp{-g}, the program above yields the following
269 @file{.s} file. Line numbers have been added to make it easier to refer
270 to parts of the @file{.s} file in the description of the stabs that
274 @section The simple example at the assembly level
278 2 .stabs "/cygint/s1/users/jcm/play/",100,0,0,Ltext0
279 3 .stabs "hello.c",100,0,0,Ltext0
282 6 .stabs "int:t1=r1;-2147483648;2147483647;",128,0,0,0
283 7 .stabs "char:t2=r2;0;127;",128,0,0,0
284 8 .stabs "long int:t3=r1;-2147483648;2147483647;",128,0,0,0
285 9 .stabs "unsigned int:t4=r1;0;-1;",128,0,0,0
286 10 .stabs "long unsigned int:t5=r1;0;-1;",128,0,0,0
287 11 .stabs "short int:t6=r1;-32768;32767;",128,0,0,0
288 12 .stabs "long long int:t7=r1;0;-1;",128,0,0,0
289 13 .stabs "short unsigned int:t8=r1;0;65535;",128,0,0,0
290 14 .stabs "long long unsigned int:t9=r1;0;-1;",128,0,0,0
291 15 .stabs "signed char:t10=r1;-128;127;",128,0,0,0
292 16 .stabs "unsigned char:t11=r1;0;255;",128,0,0,0
293 17 .stabs "float:t12=r1;4;0;",128,0,0,0
294 18 .stabs "double:t13=r1;8;0;",128,0,0,0
295 19 .stabs "long double:t14=r1;8;0;",128,0,0,0
296 20 .stabs "void:t15=15",128,0,0,0
299 23 .ascii "Hello, world!\12\0"
314 38 sethi %hi(LC0),%o1
315 39 or %o1,%lo(LC0),%o0
326 50 .stabs "main:F1",36,0,0,_main
327 51 .stabn 192,0,0,LBB2
328 52 .stabn 224,0,0,LBE2
331 This simple ``hello world'' example demonstrates several of the stab
332 types used to describe C language source files.
334 @node Program structure
335 @chapter Encoding for the structure of the program
338 * Source file:: The path and name of the source file
345 @section The path and name of the source file
354 The first stabs in the .s file contain the name and path of the source
355 file that was compiled to produce the .s file. This information is
356 contained in two records of stab type N_SO (100).
359 .stabs "path_name", N_SO, NIL, NIL, Code_address_of_program_start
360 .stabs "file_name:", N_SO, NIL, NIL, Code_address_of_program_start
364 2 .stabs "/cygint/s1/users/jcm/play/",100,0,0,Ltext0
365 3 .stabs "hello.c",100,0,0,Ltext0
371 @section Line Numbers
380 The start of source lines is represented by the @code{N_SLINE} (68) stab
384 .stabn N_SLINE, NIL, @var{line}, @var{address}
387 @var{line} is a source line number; @var{address} represents the code
388 address for the start of that source line.
400 All of the following stabs use the @samp{N_FUN} symbol type.
402 A function is represented by a @samp{F} symbol descriptor for a global
403 (extern) function, and @samp{f} for a static (local) function. The next
404 @samp{N_SLINE} symbol can be used to find the line number of the start
405 of the function. The value field is the address of the start of the
406 function. The type information of the stab represents the return type
407 of the function; thus @samp{foo:f5} means that foo is a function
410 The AIX documentation also defines symbol descriptor @samp{J} as an
411 internal function. I assume this means a function nested within another
412 function. It also says Symbol descriptor @samp{m} is a module in
413 Modula-2 or extended Pascal.
415 Procedures (functions which do not return values) are represented as
416 functions returning the void type in C. I don't see why this couldn't
417 be used for all languages (inventing a void type for this purpose if
418 necessary), but the AIX documentation defines @samp{I}, @samp{P}, and
419 @samp{Q} for internal, global, and static procedures, respectively.
420 These symbol descriptors are unusual in that they are not followed by
423 After the symbol descriptor and the type information, there is
424 optionally a comma, followed by the name of the procedure, followed by a
425 comma, followed by a name specifying the scope. The first name is local
426 to the scope specified. I assume then that the name of the symbol
427 (before the @samp{:}), if specified, is some sort of global name. I
428 assume the name specifying the scope is the name of a function
429 specifying that scope. This feature is an AIX extension, and this
430 information is based on the manual; I haven't actually tried it.
432 The stab representing a procedure is located immediately following the
433 code of the procedure. This stab is in turn directly followed by a
434 group of other stabs describing elements of the procedure. These other
435 stabs describe the procedure's parameters, its block local variables and
443 The @code{.stabs} entry after this code fragment shows the @var{name} of
444 the procedure (@code{main}); the type descriptor @var{desc} (@code{F},
445 for a global procedure); a reference to the predefined type @code{int}
446 for the return type; and the starting @var{address} of the procedure.
448 Here is an exploded summary (with whitespace introduced for clarity),
449 followed by line 50 of our sample assembly output, which has this form:
453 @var{desc} @r{(global proc @samp{F})}
454 @var{return_type_ref} @r{(int)}
460 50 .stabs "main:F1",36,0,0,_main
463 @node Block Structure
464 @section Block Structure
470 @code{N_LBRAC}, @code{N_RBRAC}
473 The program's block structure is represented by the @code{N_LBRAC} (left
474 brace) and the @code{N_RBRAC} (right brace) stab types. The following code
475 range, which is the body of @code{main}, is labeled with @samp{LBB2:} at the
476 beginning and @samp{LBE2:} at the end.
480 38 sethi %hi(LC0),%o1
481 39 or %o1,%lo(LC0),%o0
489 The @code{N_LBRAC} and @code{N_RBRAC} stabs that describe the block
490 scope of the procedure are located after the @code{N_FUNC} stab that
491 represents the procedure itself. The @code{N_LBRAC} uses the
492 @code{LBB2} label as the code address in its value field, and the
493 @code{N_RBRAC} uses @code{LBE2}.
496 50 .stabs "main:F1",36,0,0,_main
500 .stabn N_LBRAC, NIL, NIL, @var{left-brace-address}
501 .stabn N_RBRAC, NIL, NIL, @var{right-brace-address}
505 51 .stabn 192,0,0,LBB2
506 52 .stabn 224,0,0,LBE2
512 The @samp{c} symbol descriptor indicates that this stab represents a
513 constant. This symbol descriptor is an exception to the general rule
514 that symbol descriptors are followed by type information. Instead, it
515 is followed by @samp{=} and one of the following:
519 Boolean constant. @var{value} is a numeric value; I assume it is 0 for
523 Character constant. @var{value} is the numeric value of the constant.
525 @item e@var{type-information},@var{value}
526 Enumeration constant. @var{type-information} is the type of the
527 constant, as it would appear after a symbol descriptor
528 (@pxref{Overview}). @var{value} is the numeric value of the constant.
531 Integer constant. @var{value} is the numeric value.
534 Real constant. @var{value} is the real value, which can be @samp{INF}
535 (optionally preceded by a sign) for infinity, @samp{QNAN} for a quiet
536 NaN (not-a-number), or @samp{SNAN} for a signalling NaN. If it is a
537 normal number the format is that accepted by the C library function
541 String constant. @var{string} is a string enclosed in either @samp{'}
542 (in which case @samp{'} characters within the string are represented as
543 @samp{\'} or @samp{"} (in which case @samp{"} characters within the
544 string are represented as @samp{\"}).
546 @item S@var{type-information},@var{elements},@var{bits},@var{pattern}
547 Set constant. @var{type-information} is the type of the constant, as it
548 would appear after a symbol descriptor (@pxref{Overview}).
549 @var{elements} is the number of elements in the set (is this just the
550 number of bits set in @var{pattern}? Or redundant with the type? I
551 don't get it), @var{bits} is the number of bits in the constant (meaning
552 it specifies the length of @var{pattern}, I think), and @var{pattern} is
553 a hexadecimal representation of the set. AIX documentation refers to a
554 limit of 32 bytes, but I see no reason why this limit should exist.
557 The boolean, character, string, and set constants are not supported by
558 GDB 4.9, but it will ignore them. GDB 4.8 and earlier gave an error
559 message and refused to read symbols from the file containing the
562 This information is followed by @samp{;}.
565 @chapter Simple types
568 * Basic types:: Basic type definitions
569 * Range types:: Range types defined by min and max value
570 * Float "range" types:: Range type defined by size in bytes
574 @section Basic type definitions
581 @item Symbol Descriptor:
585 The basic types for the language are described using the @code{N_LSYM} stab
586 type. They are boilerplate and are emited by the compiler for each
587 compilation unit. Basic type definitions are not always a complete
588 description of the type and are sometimes circular. The debugger
589 recognizes the type anyway, and knows how to read bits as that type.
591 Each language and compiler defines a slightly different set of basic
592 types. In this example we are looking at the basic types for C emited
593 by the GNU compiler targeting the Sun4. Here the basic types are
594 mostly defined as range types.
598 @section Range types defined by min and max value
601 @item Type Descriptor:
605 When defining a range type, if the number after the first semicolon is
606 smaller than the number after the second one, then the two numbers
607 represent the smallest and the largest values in the range.
614 @var{descriptor} @r{(type)}
621 N_LSYM, NIL, NIL, NIL
623 6 .stabs "int:t1=r1;-2147483648;2147483647;",128,0,0,0
624 7 .stabs "char:t2=r2;0;127;",128,0,0,0
627 Here the integer type (@code{1}) is defined as a range of the integer
628 type (@code{1}). Likewise @code{char} is a range of @code{char}. This
629 part of the definition is circular, but at least the high and low bound
630 values of the range hold more information about the type.
632 Here short unsigned int is defined as type number 8 and described as a
633 range of type @code{int}, with a minimum value of 0 and a maximum of 65535.
636 13 .stabs "short unsigned int:t8=r1;0;65535;",128,0,0,0
639 @node Float "range" types
640 @section Range type defined by size in bytes
643 @item Type Descriptor:
647 In a range definition, if the first number after the semicolon is
648 positive and the second is zero, then the type being defined is a
649 floating point type, and the number after the first semicolon is the
650 number of bytes needed to represent the type. Note that this does not
651 provide a way to distinguish 8-byte real floating point types from
652 8-byte complex floating point types.
663 N_LSYM, NIL, NIL, NIL
665 17 .stabs "float:t12=r1;4;0;",128,0,0,0
666 18 .stabs "double:t13=r1;8;0;",128,0,0,0
667 19 .stabs "long double:t14=r1;8;0;",128,0,0,0
670 Cosmically enough, the @code{void} type is defined directly in terms of
680 20 .stabs "void:t15=15",128,0,0,0
685 @chapter A Comprehensive Example in C
687 Now we'll examine a second program, @code{example2}, which builds on the
688 first example to introduce the rest of the stab types, symbol
689 descriptors, and type descriptors used in C.
690 @xref{Example2.c} for the complete @file{.c} source,
691 and @pxref{Example2.s} for the @file{.s} assembly code.
692 This description includes parts of those files.
694 @section Flow of control and nested scopes
700 @code{N_SLINE}, @code{N_LBRAC}, @code{N_RBRAC} (cont.)
703 Consider the body of @code{main}, from @file{example2.c}. It shows more
704 about how @code{N_SLINE}, @code{N_RBRAC}, and @code{N_LBRAC} stabs are used.
708 21 static float s_flap;
710 23 for (times=0; times < s_g_repeat; times++)@{
712 25 printf ("Hello world\n");
717 Here we have a single source line, the @samp{for} line, that generates
718 non-linear flow of control, and non-contiguous code. In this case, an
719 @code{N_SLINE} stab with the same line number proceeds each block of
720 non-contiguous code generated from the same source line.
722 The example also shows nested scopes. The @code{N_LBRAC} and
723 @code{N_LBRAC} stabs that describe block structure are nested in the
724 same order as the corresponding code blocks, those of the for loop
725 inside those for the body of main.
728 This is the label for the @code{N_LBRAC} (left brace) stab marking the
729 start of @code{main}.
736 In the first code range for C source line 23, the @code{for} loop
737 initialize and test, @code{N_SLINE} (68) records the line number:
744 58 .stabn 68,0,23,LM2
748 62 sethi %hi(_s_g_repeat),%o0
750 64 ld [%o0+%lo(_s_g_repeat)],%o0
755 @exdent label for the @code{N_LBRAC} (start block) marking the start of @code{for} loop
758 69 .stabn 68,0,25,LM3
760 71 sethi %hi(LC0),%o1
761 72 or %o1,%lo(LC0),%o0
764 75 .stabn 68,0,26,LM4
767 @exdent label for the @code{N_RBRAC} (end block) stab marking the end of the @code{for} loop
773 Now we come to the second code range for source line 23, the @code{for}
774 loop increment and return. Once again, @code{N_SLINE} (68) records the
778 .stabn, N_SLINE, NIL,
782 78 .stabn 68,0,23,LM5
790 86 .stabn 68,0,27,LM6
793 @exdent label for the @code{N_RBRAC} (end block) stab marking the end of the @code{for} loop
796 89 .stabn 68,0,27,LM7
801 94 .stabs "main:F1",36,0,0,_main
802 95 .stabs "argc:p1",160,0,0,68
803 96 .stabs "argv:p20=*21=*2",160,0,0,72
804 97 .stabs "s_flap:V12",40,0,0,_s_flap.0
805 98 .stabs "times:1",128,0,0,-20
809 Here is an illustration of stabs describing nested scopes. The scope
810 nesting is reflected in the nested bracketing stabs (@code{N_LBRAC},
814 .stabn N_LBRAC,NIL,NIL,
815 @var{block-start-address}
817 99 .stabn 192,0,0,LBB2 ## begin proc label
818 100 .stabs "inner:1",128,0,0,-24
819 101 .stabn 192,0,0,LBB3 ## begin for label
823 @code{N_RBRAC} (224), ``right brace'' ends a lexical block (scope).
826 .stabn N_RBRAC,NIL,NIL,
827 @var{block-end-address}
829 102 .stabn 224,0,0,LBE3 ## end for label
830 103 .stabn 224,0,0,LBE2 ## end proc label
837 * Automatic variables:: locally scoped
839 * Register variables::
840 * Initialized statics::
841 * Un-initialized statics::
845 @node Automatic variables
846 @section Locally scoped automatic variables
853 @item Symbol Descriptor:
858 In addition to describing types, the @code{N_LSYM} stab type also
859 describes locally scoped automatic variables. Refer again to the body
860 of @code{main} in @file{example2.c}. It allocates two automatic
861 variables: @samp{times} is scoped to the body of @code{main}, and
862 @samp{inner} is scoped to the body of the @code{for} loop.
863 @samp{s_flap} is locally scoped but not automatic, and will be discussed
868 21 static float s_flap;
870 23 for (times=0; times < s_g_repeat; times++)@{
872 25 printf ("Hello world\n");
877 The @code{N_LSYM} stab for an automatic variable is located just before the
878 @code{N_LBRAC} stab describing the open brace of the block to which it is
882 @exdent @code{N_LSYM} (128): automatic variable, scoped locally to @code{main}
887 @var{frame-pointer-offset}
889 98 .stabs "times:1",128,0,0,-20
890 99 .stabn 192,0,0,LBB2 ## begin `main' N_LBRAC
892 @exdent @code{N_LSYM} (128): automatic variable, scoped locally to the @code{for} loop
897 @var{frame-pointer-offset}
899 100 .stabs "inner:1",128,0,0,-24
900 101 .stabn 192,0,0,LBB3 ## begin `for' loop N_LBRAC
903 Since the character in the string field following the colon is not a
904 letter, there is no symbol descriptor. This means that the stab
905 describes a local variable, and that the number after the colon is a
906 type reference. In this case it a a reference to the basic type @code{int}.
907 Notice also that the frame pointer offset is negative number for
911 @node Global Variables
912 @section Global Variables
919 @item Symbol Descriptor:
923 Global variables are represented by the @code{N_GSYM} stab type. The symbol
924 descriptor, following the colon in the string field, is @samp{G}. Following
925 the @samp{G} is a type reference or type definition. In this example it is a
926 type reference to the basic C type, @code{char}. The first source line in
934 yields the following stab. The stab immediately precedes the code that
935 allocates storage for the variable it describes.
938 @exdent @code{N_GSYM} (32): global symbol
943 N_GSYM, NIL, NIL, NIL
945 21 .stabs "g_foo:G2",32,0,0,0
952 The address of the variable represented by the @code{N_GSYM} is not contained
953 in the @code{N_GSYM} stab. The debugger gets this information from the
954 external symbol for the global variable.
956 @node Register variables
957 @section Register variables
959 Register variables have their own stab type, @code{N_RSYM}, and their
960 own symbol descriptor, @code{r}. The stab's value field contains the
961 number of the register where the variable data will be stored.
963 The value is the register number.
965 AIX defines a separate symbol descriptor @samp{d} for floating point
966 registers. This seems incredibly stupid--why not just just give
967 floating point registers different register numbers.
969 If the register is explicitly allocated to a global variable, but not
973 register int g_bar asm ("%g5");
976 the stab may be emitted at the end of the object file, with
977 the other bss symbols.
979 @node Initialized statics
980 @section Initialized static variables
987 @item Symbol Descriptors:
988 @code{S} (file scope), @code{V} (procedure scope)
991 Initialized static variables are represented by the @code{N_STSYM} stab
992 type. The symbol descriptor part of the string field shows if the
993 variable is file scope static (@samp{S}) or procedure scope static
994 (@samp{V}). The source line
997 3 static int s_g_repeat = 2;
1001 yields the following code. The stab is located immediately preceding
1002 the storage for the variable it represents. Since the variable in
1003 this example is file scope static the symbol descriptor is @samp{S}.
1006 @exdent @code{N_STSYM} (38): initialized static variable (data seg w/internal linkage)
1014 26 .stabs "s_g_repeat:S1",38,0,0,_s_g_repeat
1021 @node Un-initialized statics
1022 @section Un-initialized static variables
1029 @item Symbol Descriptors:
1030 @code{S} (file scope), @code{V} (procedure scope)
1033 Un-initialized static variables are represented by the @code{N_LCSYM}
1034 stab type. The symbol descriptor part of the string shows if the
1035 variable is file scope static (@samp{S}) or procedure scope static
1036 (@samp{V}). In this example it is procedure scope static. The source
1037 line allocating @code{s_flap} immediately follows the open brace for the
1038 procedure @code{main}.
1042 21 static float s_flap;
1045 The code that reserves storage for the variable @code{s_flap} precedes the
1046 body of body of @code{main}.
1049 39 .reserve _s_flap.0,4,"bss",4
1052 But since @code{s_flap} is scoped locally to @code{main}, its stab is
1053 located with the other stabs representing symbols local to @code{main}.
1054 The stab for @code{s_flap} is located just before the @code{N_LBRAC} for
1058 @exdent @code{N_LCSYM} (40): uninitialized static var (BSS seg w/internal linkage)
1066 97 .stabs "s_flap:V12",40,0,0,_s_flap.0
1067 98 .stabs "times:1",128,0,0,-20
1068 99 .stabn 192,0,0,LBB2 # N_LBRAC for main.
1071 @c ............................................................
1076 The symbol descriptor @samp{p} is used to refer to parameters which are
1077 in the arglist. Symbols have symbol type @samp{N_PSYM}. The value of
1078 the symbol is the offset relative to the argument list.
1080 If the parameter is passed in a register, then the traditional way to do
1081 this is to provide two symbols for each argument:
1084 .stabs "arg:p1" . . . ; N_PSYM
1085 .stabs "arg:r1" . . . ; N_RSYM
1088 Debuggers are expected to use the second one to find the value, and the
1089 first one to know that it is an argument.
1091 Because this is kind of ugly, some compilers use symbol descriptor
1092 @samp{P} or @samp{R} to indicate an argument which is in a register.
1093 The symbol value is the register number. @samp{P} and @samp{R} mean the
1094 same thing, the difference is that @samp{P} is a GNU invention and
1095 @samp{R} is an IBM (xcoff) invention. As of version 4.9, GDB should
1096 handle either one. Symbol type @samp{C_RPSYM} is used with @samp{R} and
1097 @samp{N_RSYM} is used with @samp{P}.
1099 AIX, according to the documentation, uses @samp{D} for a parameter
1100 passed in a floating point register. This strikes me as incredibly
1101 bogus---why doesn't it just use @samp{R} with a register number which
1102 indicates that it's a floating point register? I haven't verified
1103 whether the system actually does what the documentation indicates.
1105 There is at least one case where GCC uses a @samp{p}/@samp{r} pair
1106 rather than @samp{P}; this is where the argument is passed in the
1107 argument list and then loaded into a register.
1109 On the sparc and hppa, for a @samp{P} symbol whose type is a structure
1110 or union, the register contains the address of the structure. On the
1111 sparc, this is also true of a @samp{p}/@samp{r} pair (using Sun cc) or a
1112 @samp{p} symbol. However, if a (small) structure is really in a
1113 register, @samp{r} is used. And, to top it all off, on the hppa it
1114 might be a structure which was passed on the stack and loaded into a
1115 register and for which there is a @samp{p}/@samp{r} pair! I believe
1116 that symbol descriptor @samp{i} is supposed to deal with this case, (it
1117 is said to mean "value parameter by reference, indirect access", I don't
1118 know the source for this information) but I don't know details or what
1119 compilers or debuggers use it, if any (not GDB or GCC). It is not clear
1120 to me whether this case needs to be dealt with differently than
1121 parameters passed by reference (see below).
1123 There is another case similar to an argument in a register, which is an
1124 argument which is actually stored as a local variable. Sometimes this
1125 happens when the argument was passed in a register and then the compiler
1126 stores it as a local variable. If possible, the compiler should claim
1127 that it's in a register, but this isn't always done. Some compilers use
1128 the pair of symbols approach described above ("arg:p" followed by
1129 "arg:"); this includes gcc1 (not gcc2) on the sparc when passing a small
1130 structure and gcc2 (sometimes) when the argument type is float and it is
1131 passed as a double and converted to float by the prologue (in the latter
1132 case the type of the "arg:p" symbol is double and the type of the "arg:"
1133 symbol is float). GCC, at least on the 960, uses a single @samp{p}
1134 symbol descriptor for an argument which is stored as a local variable
1135 but uses @samp{N_LSYM} instead of @samp{N_PSYM}. In this case the value
1136 of the symbol is an offset relative to the local variables for that
1137 function, not relative to the arguments (on some machines those are the
1138 same thing, but not on all).
1140 If the parameter is passed by reference (e.g. Pascal VAR parameters),
1141 then type symbol descriptor is @samp{v} if it is in the argument list,
1142 or @samp{a} if it in a register. Other than the fact that these contain
1143 the address of the parameter other than the parameter itself, they are
1144 identical to @samp{p} and @samp{R}, respectively. I believe @samp{a} is
1145 an AIX invention; @samp{v} is supported by all stabs-using systems as
1148 @c Is this paragraph correct? It is based on piecing together patchy
1149 @c information and some guesswork
1150 Conformant arrays refer to a feature of Modula-2, and perhaps other
1151 languages, in which the size of an array parameter is not known to the
1152 called function until run-time. Such parameters have two stabs, a
1153 @samp{x} for the array itself, and a @samp{C}, which represents the size
1154 of the array. The value of the @samp{x} stab is the offset in the
1155 argument list where the address of the array is stored (it this right?
1156 it is a guess); the value of the @samp{C} stab is the offset in the
1157 argument list where the size of the array (in elements? in bytes?) is
1160 The following are also said to go with @samp{N_PSYM}:
1163 "name" -> "param_name:#type"
1166 -> X (function result variable)
1167 -> b (based variable)
1169 value -> offset from the argument pointer (positive).
1172 As a simple example, the code
1184 .stabs "main:F1",36,0,0,_main ; 36 is N_FUN
1185 .stabs "argc:p1",160,0,0,68 ; 160 is N_PSYM
1186 .stabs "argv:p20=*21=*2",160,0,0,72
1189 The type definition of argv is interesting because it contains several
1190 type definitions. Type 21 is pointer to type 2 (char) and argv (type 20) is
1193 @node Aggregate Types
1194 @chapter Aggregate Types
1196 Now let's look at some variable definitions involving complex types.
1197 This involves understanding better how types are described. In the
1198 examples so far types have been described as references to previously
1199 defined types or defined in terms of subranges of or pointers to
1200 previously defined types. The section that follows will talk about
1201 the various other type descriptors that may follow the = sign in a
1214 @section Array types
1220 @code{N_GSYM}, @code{N_LSYM}
1221 @item Symbol Descriptor:
1223 @item Type Descriptor:
1227 As an example of an array type consider the global variable below.
1230 15 char char_vec[3] = @{'a','b','c'@};
1233 Since the array is a global variable, it is described by the N_GSYM
1234 stab type. The symbol descriptor G, following the colon in stab's
1235 string field, also says the array is a global variable. Following the
1236 G is a definition for type (19) as shown by the equals sign after the
1239 After the equals sign is a type descriptor, a, which says that the type
1240 being defined is an array. Following the type descriptor for an array
1241 is the type of the index, a semicolon, and the type of the array elements.
1243 The type of the index is often a range type, expressed as the letter r
1244 and some parameters. It defines the size of the array. In in the
1245 example below, the range @code{r1;0;2;} defines an index type which is
1246 a subrange of type 1 (integer), with a lower bound of 0 and an upper
1247 bound of 2. This defines the valid range of subscripts of a
1248 three-element C array.
1250 The array definition above generates the assembly language that
1254 @exdent <32> N_GSYM - global variable
1255 @exdent .stabs "name:sym_desc(global)type_def(19)=type_desc(array)
1256 @exdent index_type_ref(range of int from 0 to 2);element_type_ref(char)";
1257 @exdent N_GSYM, NIL, NIL, NIL
1259 32 .stabs "char_vec:G19=ar1;0;2;2",32,0,0,0
1260 33 .global _char_vec
1269 @section Enumerations
1276 @item Symbol Descriptor:
1278 @item Type Descriptor:
1282 The source line below declares an enumeration type. It is defined at
1283 file scope between the bodies of main and s_proc in example2.c.
1284 Because the N_LSYM is located after the N_RBRAC that marks the end of
1285 the previous procedure's block scope, and before the N_FUN that marks
1286 the beginning of the next procedure's block scope, the N_LSYM does not
1287 describe a block local symbol, but a file local one. The source line:
1290 29 enum e_places @{first,second=3,last@};
1294 generates the following stab, located just after the N_RBRAC (close
1295 brace stab) for main. The type definition is in an N_LSYM stab
1296 because type definitions are file scope not global scope.
1299 <128> N_LSYM - local symbol
1300 .stab "name:sym_dec(type)type_def(22)=sym_desc(enum)
1301 enum_name:value(0),enum_name:value(3),enum_name:value(4),;",
1302 N_LSYM, NIL, NIL, NIL
1306 104 .stabs "e_places:T22=efirst:0,second:3,last:4,;",128,0,0,0
1309 The symbol descriptor (T) says that the stab describes a structure,
1310 enumeration, or type tag. The type descriptor e, following the 22= of
1311 the type definition narrows it down to an enumeration type. Following
1312 the e is a list of the elements of the enumeration. The format is
1313 name:value,. The list of elements ends with a ;.
1315 @node Structure tags
1316 @section Structure Tags
1323 @item Symbol Descriptor:
1325 @item Type Descriptor:
1329 The following source code declares a structure tag and defines an
1330 instance of the structure in global scope. Then a typedef equates the
1331 structure tag with a new type. A seperate stab is generated for the
1332 structure tag, the structure typedef, and the structure instance. The
1333 stabs for the tag and the typedef are emited when the definitions are
1334 encountered. Since the structure elements are not initialized, the
1335 stab and code for the structure variable itself is located at the end
1336 of the program in .common.
1342 9 char s_char_vec[8];
1343 10 struct s_tag* s_next;
1346 13 typedef struct s_tag s_typedef;
1349 The structure tag is an N_LSYM stab type because, like the enum, the
1350 symbol is file scope. Like the enum, the symbol descriptor is T, for
1351 enumeration, struct or tag type. The symbol descriptor s following
1352 the 16= of the type definition narrows the symbol type to struct.
1354 Following the struct symbol descriptor is the number of bytes the
1355 struct occupies, followed by a description of each structure element.
1356 The structure element descriptions are of the form name:type, bit
1357 offset from the start of the struct, and number of bits in the
1362 <128> N_LSYM - type definition
1363 .stabs "name:sym_desc(struct tag) Type_def(16)=type_desc(struct type)
1365 elem_name:type_ref(int),bit_offset,field_bits;
1366 elem_name:type_ref(float),bit_offset,field_bits;
1367 elem_name:type_def(17)=type_desc(array)
1368 index_type(range of int from 0 to 7);
1369 element_type(char),bit_offset,field_bits;;",
1372 30 .stabs "s_tag:T16=s20s_int:1,0,32;s_float:12,32,32;
1373 s_char_vec:17=ar1;0;7;2,64,64;s_next:18=*16,128,32;;",128,0,0,0
1376 In this example, two of the structure elements are previously defined
1377 types. For these, the type following the name: part of the element
1378 description is a simple type reference. The other two structure
1379 elements are new types. In this case there is a type definition
1380 embedded after the name:. The type definition for the array element
1381 looks just like a type definition for a standalone array. The s_next
1382 field is a pointer to the same kind of structure that the field is an
1383 element of. So the definition of structure type 16 contains an type
1384 definition for an element which is a pointer to type 16.
1394 @item Symbol Descriptor:
1398 Here is the stab for the typedef equating the structure tag with a
1402 <128> N_LSYM - type definition
1403 .stabs "name:sym_desc(type name)type_ref(struct_tag)",N_LSYM,NIL,NIL,NIL
1407 31 .stabs "s_typedef:t16",128,0,0,0
1410 And here is the code generated for the structure variable.
1413 <32> N_GSYM - global symbol
1414 .stabs "name:sym_desc(global)type_ref(struct_tag)",N_GSYM,NIL,NIL,NIL
1418 136 .stabs "g_an_s:G16",32,0,0,0
1419 137 .common _g_an_s,20,"bss"
1422 Notice that the structure tag has the same type number as the typedef
1423 for the structure tag. It is impossible to distinguish between a
1424 variable of the struct type and one of its typedef by looking at the
1425 debugging information.
1436 @item Symbol Descriptor:
1438 @item Type Descriptor:
1442 Next let's look at unions. In example2 this union type is declared
1443 locally to a procedure and an instance of the union is defined.
1453 This code generates a stab for the union tag and a stab for the union
1454 variable. Both use the N_LSYM stab type. Since the union variable is
1455 scoped locally to the procedure in which it is defined, its stab is
1456 located immediately preceding the N_LBRAC for the procedure's block
1459 The stab for the union tag, however is located preceding the code for
1460 the procedure in which it is defined. The stab type is N_LSYM. This
1461 would seem to imply that the union type is file scope, like the struct
1462 type s_tag. This is not true. The contents and position of the stab
1463 for u_type do not convey any infomation about its procedure local
1468 .stabs "name:sym_desc(union tag)type_def(22)=type_desc(union)
1470 elem_name:type_ref(int),bit_offset(0),bit_size(32);
1471 elem_name:type_ref(float),bit_offset(0),bit_size(32);
1472 elem_name:type_ref(ptr to char),bit_offset(0),bit_size(32);;"
1473 N_LSYM, NIL, NIL, NIL
1477 105 .stabs "u_tag:T23=u4u_int:1,0,32;u_float:12,0,32;u_char:21,0,32;;",
1481 The symbol descriptor, T, following the name: means that the stab
1482 describes an enumeration, struct or type tag. The type descriptor u,
1483 following the 23= of the type definition, narrows it down to a union
1484 type definition. Following the u is the number of bytes in the union.
1485 After that is a list of union element descriptions. Their format is
1486 name:type, bit offset into the union, and number of bytes for the
1489 The stab for the union variable follows. Notice that the frame
1490 pointer offset for local variables is negative.
1493 <128> N_LSYM - local variable (with no symbol descriptor)
1494 .stabs "name:type_ref(u_tag)", N_LSYM, NIL, NIL, frame_ptr_offset
1498 130 .stabs "an_u:23",128,0,0,-20
1501 @node Function types
1502 @section Function types
1508 The last type descriptor in C which remains to be described is used
1509 for function types. Consider the following source line defining a
1510 global function pointer.
1516 It generates the following code. Since the variable is not
1517 initialized, the code is located in the common area at the end of the
1521 <32> N_GSYM - global variable
1522 .stabs "name:sym_desc(global)type_def(24)=ptr_to(25)=
1523 type_def(func)type_ref(int)
1527 134 .stabs "g_pf:G24=*25=f1",32,0,0,0
1528 135 .common _g_pf,4,"bss"
1531 Since the variable is global, the stab type is N_GSYM and the symbol
1532 descriptor is G. The variable defines a new type, 24, which is a
1533 pointer to another new type, 25, which is defined as a function
1537 @chapter Symbol information in symbol tables
1539 This section examines more closely the format of symbol table entries
1540 and how stab assembler directives map to them. It also describes what
1541 transformations the assembler and linker make on data from stabs.
1543 Each time the assembler encounters a stab in its input file it puts
1544 each field of the stab into corresponding fields in a symbol table
1545 entry of its output file. If the stab contains a string field, the
1546 symbol table entry for that stab points to a string table entry
1547 containing the string data from the stab. Assembler labels become
1548 relocatable addresses. Symbol table entries in a.out have the format:
1551 struct internal_nlist @{
1552 unsigned long n_strx; /* index into string table of name */
1553 unsigned char n_type; /* type of symbol */
1554 unsigned char n_other; /* misc info (usually empty) */
1555 unsigned short n_desc; /* description field */
1556 bfd_vma n_value; /* value of symbol */
1560 For .stabs directives, the n_strx field holds the character offset
1561 from the start of the string table to the string table entry
1562 containing the "string" field. For other classes of stabs (.stabn and
1563 .stabd) this field is null.
1565 Symbol table entries with n_type fields containing a value greater or
1566 equal to 0x20 originated as stabs generated by the compiler (with one
1567 random exception). Those with n_type values less than 0x20 were
1568 placed in the symbol table of the executable by the assembler or the
1571 The linker concatenates object files and does fixups of externally
1572 defined symbols. You can see the transformations made on stab data by
1573 the assembler and linker by examining the symbol table after each pass
1574 of the build, first the assemble and then the link.
1576 To do this use nm with the -ap options. This dumps the symbol table,
1577 including debugging information, unsorted. For stab entries the
1578 columns are: value, other, desc, type, string. For assembler and
1579 linker symbols, the columns are: value, type, string.
1581 There are a few important things to notice about symbol tables. Where
1582 the value field of a stab contains a frame pointer offset, or a
1583 register number, that value is unchanged by the rest of the build.
1585 Where the value field of a stab contains an assembly language label,
1586 it is transformed by each build step. The assembler turns it into a
1587 relocatable address and the linker turns it into an absolute address.
1588 This source line defines a static variable at file scope:
1591 3 static int s_g_repeat
1595 The following stab describes the symbol.
1598 26 .stabs "s_g_repeat:S1",38,0,0,_s_g_repeat
1602 The assembler transforms the stab into this symbol table entry in the
1603 @file{.o} file. The location is expressed as a data segment offset.
1606 21 00000084 - 00 0000 STSYM s_g_repeat:S1
1610 in the symbol table entry from the executable, the linker has made the
1611 relocatable address absolute.
1614 22 0000e00c - 00 0000 STSYM s_g_repeat:S1
1617 Stabs for global variables do not contain location information. In
1618 this case the debugger finds location information in the assembler or
1619 linker symbol table entry describing the variable. The source line:
1629 21 .stabs "g_foo:G2",32,0,0,0
1632 The variable is represented by the following two symbol table entries
1633 in the object file. The first one originated as a stab. The second
1634 one is an external symbol. The upper case D signifies that the n_type
1635 field of the symbol table contains 7, N_DATA with local linkage (see
1636 Table B). The value field following the file's line number is empty
1637 for the stab entry. For the linker symbol it contains the
1638 rellocatable address corresponding to the variable.
1641 19 00000000 - 00 0000 GSYM g_foo:G2
1642 20 00000080 D _g_foo
1646 These entries as transformed by the linker. The linker symbol table
1647 entry now holds an absolute address.
1650 21 00000000 - 00 0000 GSYM g_foo:G2
1652 215 0000e008 D _g_foo
1655 @node GNU Cplusplus stabs
1656 @chapter GNU C++ stabs
1659 * Basic Cplusplus types::
1662 * Methods:: Method definition
1664 * Method Modifiers:: (const, volatile, const volatile)
1667 * Virtual Base Classes::
1672 @subsection Symbol descriptors added for C++ descriptions:
1675 P - register parameter.
1678 @subsection type descriptors added for C++ descriptions
1682 method type (two ## if minimal debug)
1689 @node Basic Cplusplus types
1690 @section Basic types for C++
1692 << the examples that follow are based on a01.C >>
1695 C++ adds two more builtin types to the set defined for C. These are
1696 the unknown type and the vtable record type. The unknown type, type
1697 16, is defined in terms of itself like the void type.
1699 The vtable record type, type 17, is defined as a structure type and
1700 then as a structure tag. The structure has four fields, delta, index,
1701 pfn, and delta2. pfn is the function pointer.
1703 << In boilerplate $vtbl_ptr_type, what are the fields delta,
1704 index, and delta2 used for? >>
1706 This basic type is present in all C++ programs even if there are no
1707 virtual methods defined.
1710 .stabs "struct_name:sym_desc(type)type_def(17)=type_desc(struct)struct_bytes(8)
1711 elem_name(delta):type_ref(short int),bit_offset(0),field_bits(16);
1712 elem_name(index):type_ref(short int),bit_offset(16),field_bits(16);
1713 elem_name(pfn):type_def(18)=type_desc(ptr to)type_ref(void),
1714 bit_offset(32),field_bits(32);
1715 elem_name(delta2):type_def(short int);bit_offset(32),field_bits(16);;"
1720 .stabs "$vtbl_ptr_type:t17=s8
1721 delta:6,0,16;index:6,16,16;pfn:18=*15,32,32;delta2:6,32,16;;"
1726 .stabs "name:sym_dec(struct tag)type_ref($vtbl_ptr_type)",N_LSYM,NIL,NIL,NIL
1730 .stabs "$vtbl_ptr_type:T17",128,0,0,0
1733 @node Simple classes
1734 @section Simple class definition
1736 The stabs describing C++ language features are an extension of the
1737 stabs describing C. Stabs representing C++ class types elaborate
1738 extensively on the stab format used to describe structure types in C.
1739 Stabs representing class type variables look just like stabs
1740 representing C language variables.
1742 Consider the following very simple class definition.
1748 int Ameth(int in, char other);
1752 The class baseA is represented by two stabs. The first stab describes
1753 the class as a structure type. The second stab describes a structure
1754 tag of the class type. Both stabs are of stab type N_LSYM. Since the
1755 stab is not located between an N_FUN and a N_LBRAC stab this indicates
1756 that the class is defined at file scope. If it were, then the N_LSYM
1757 would signify a local variable.
1759 A stab describing a C++ class type is similar in format to a stab
1760 describing a C struct, with each class member shown as a field in the
1761 structure. The part of the struct format describing fields is
1762 expanded to include extra information relevent to C++ class members.
1763 In addition, if the class has multiple base classes or virtual
1764 functions the struct format outside of the field parts is also
1767 In this simple example the field part of the C++ class stab
1768 representing member data looks just like the field part of a C struct
1769 stab. The section on protections describes how its format is
1770 sometimes extended for member data.
1772 The field part of a C++ class stab representing a member function
1773 differs substantially from the field part of a C struct stab. It
1774 still begins with `name:' but then goes on to define a new type number
1775 for the member function, describe its return type, its argument types,
1776 its protection level, any qualifiers applied to the method definition,
1777 and whether the method is virtual or not. If the method is virtual
1778 then the method description goes on to give the vtable index of the
1779 method, and the type number of the first base class defining the
1782 When the field name is a method name it is followed by two colons
1783 rather than one. This is followed by a new type definition for the
1784 method. This is a number followed by an equal sign and then the
1785 symbol descriptor `##', indicating a method type. This is followed by
1786 a type reference showing the return type of the method and a
1789 The format of an overloaded operator method name differs from that
1790 of other methods. It is "op$::XXXX." where XXXX is the operator name
1791 such as + or +=. The name ends with a period, and any characters except
1792 the period can occur in the XXXX string.
1794 The next part of the method description represents the arguments to
1795 the method, preceeded by a colon and ending with a semi-colon. The
1796 types of the arguments are expressed in the same way argument types
1797 are expressed in C++ name mangling. In this example an int and a char
1800 This is followed by a number, a letter, and an asterisk or period,
1801 followed by another semicolon. The number indicates the protections
1802 that apply to the member function. Here the 2 means public. The
1803 letter encodes any qualifier applied to the method definition. In
1804 this case A means that it is a normal function definition. The dot
1805 shows that the method is not virtual. The sections that follow
1806 elaborate further on these fields and describe the additional
1807 information present for virtual methods.
1811 .stabs "class_name:sym_desc(type)type_def(20)=type_desc(struct)struct_bytes(4)
1812 field_name(Adat):type(int),bit_offset(0),field_bits(32);
1814 method_name(Ameth)::type_def(21)=type_desc(method)return_type(int);
1815 :arg_types(int char);
1816 protection(public)qualifier(normal)virtual(no);;"
1821 .stabs "baseA:t20=s4Adat:1,0,32;Ameth::21=##1;:ic;2A.;;",128,0,0,0
1823 .stabs "class_name:sym_desc(struct tag)",N_LSYM,NIL,NIL,NIL
1825 .stabs "baseA:T20",128,0,0,0
1828 @node Class instance
1829 @section Class instance
1831 As shown above, describing even a simple C++ class definition is
1832 accomplished by massively extending the stab format used in C to
1833 describe structure types. However, once the class is defined, C stabs
1834 with no modifications can be used to describe class instances. The
1844 yields the following stab describing the class instance. It looks no
1845 different from a standard C stab describing a local variable.
1848 .stabs "name:type_ref(baseA)", N_LSYM, NIL, NIL, frame_ptr_offset
1852 .stabs "AbaseA:20",128,0,0,-20
1856 @section Method defintion
1858 The class definition shown above declares Ameth. The C++ source below
1863 baseA::Ameth(int in, char other)
1870 This method definition yields three stabs following the code of the
1871 method. One stab describes the method itself and following two
1872 describe its parameters. Although there is only one formal argument
1873 all methods have an implicit argument which is the `this' pointer.
1874 The `this' pointer is a pointer to the object on which the method was
1875 called. Note that the method name is mangled to encode the class name
1876 and argument types. << Name mangling is not described by this
1877 document - Is there already such a doc? >>
1880 .stabs "name:symbol_desriptor(global function)return_type(int)",
1881 N_FUN, NIL, NIL, code_addr_of_method_start
1883 .stabs "Ameth__5baseAic:F1",36,0,0,_Ameth__5baseAic
1886 Here is the stab for the `this' pointer implicit argument. The name
1887 of the `this' pointer is always `this.' Type 19, the `this' pointer is
1888 defined as a pointer to type 20, baseA, but a stab defining baseA has
1889 not yet been emited. Since the compiler knows it will be emited
1890 shortly, here it just outputs a cross reference to the undefined
1891 symbol, by prefixing the symbol name with xs.
1894 .stabs "name:sym_desc(register param)type_def(19)=
1895 type_desc(ptr to)type_ref(baseA)=
1896 type_desc(cross-reference to)baseA:",N_RSYM,NIL,NIL,register_number
1898 .stabs "this:P19=*20=xsbaseA:",64,0,0,8
1901 The stab for the explicit integer argument looks just like a parameter
1902 to a C function. The last field of the stab is the offset from the
1903 argument pointer, which in most systems is the same as the frame
1907 .stabs "name:sym_desc(value parameter)type_ref(int)",
1908 N_PSYM,NIL,NIL,offset_from_arg_ptr
1910 .stabs "in:p1",160,0,0,72
1913 << The examples that follow are based on A1.C >>
1916 @section Protections
1919 In the simple class definition shown above all member data and
1920 functions were publicly accessable. The example that follows
1921 contrasts public, protected and privately accessable fields and shows
1922 how these protections are encoded in C++ stabs.
1924 Protections for class member data are signified by two characters
1925 embeded in the stab defining the class type. These characters are
1926 located after the name: part of the string. /0 means private, /1
1927 means protected, and /2 means public. If these characters are omited
1928 this means that the member is public. The following C++ source:
1942 generates the following stab to describe the class type all_data.
1945 .stabs "class_name:sym_desc(type)type_def(19)=type_desc(struct)struct_bytes
1946 data_name:/protection(private)type_ref(int),bit_offset,num_bits;
1947 data_name:/protection(protected)type_ref(char),bit_offset,num_bits;
1948 data_name:(/num omited, private)type_ref(float),bit_offset,num_bits;;"
1953 .stabs "all_data:t19=s12
1954 priv_dat:/01,0,32;prot_dat:/12,32,8;pub_dat:12,64,32;;",128,0,0,0
1957 Protections for member functions are signified by one digit embeded in
1958 the field part of the stab describing the method. The digit is 0 if
1959 private, 1 if protected and 2 if public. Consider the C++ class
1963 class all_methods @{
1965 int priv_meth(int in)@{return in;@};
1967 char protMeth(char in)@{return in;@};
1969 float pubMeth(float in)@{return in;@};
1973 It generates the following stab. The digit in question is to the left
1974 of an `A' in each case. Notice also that in this case two symbol
1975 descriptors apply to the class name struct tag and struct type.
1978 .stabs "class_name:sym_desc(struct tag&type)type_def(21)=
1979 sym_desc(struct)struct_bytes(1)
1980 meth_name::type_def(22)=sym_desc(method)returning(int);
1981 :args(int);protection(private)modifier(normal)virtual(no);
1982 meth_name::type_def(23)=sym_desc(method)returning(char);
1983 :args(char);protection(protected)modifier(normal)virual(no);
1984 meth_name::type_def(24)=sym_desc(method)returning(float);
1985 :args(float);protection(public)modifier(normal)virtual(no);;",
1990 .stabs "all_methods:Tt21=s1priv_meth::22=##1;:i;0A.;protMeth::23=##2;:c;1A.;
1991 pubMeth::24=##12;:f;2A.;;",128,0,0,0
1994 @node Method Modifiers
1995 @section Method Modifiers (const, volatile, const volatile)
1999 In the class example described above all the methods have the normal
2000 modifier. This method modifier information is located just after the
2001 protection information for the method. This field has four possible
2002 character values. Normal methods use A, const methods use B, volatile
2003 methods use C, and const volatile methods use D. Consider the class
2009 int ConstMeth (int arg) const @{ return arg; @};
2010 char VolatileMeth (char arg) volatile @{ return arg; @};
2011 float ConstVolMeth (float arg) const volatile @{return arg; @};
2015 This class is described by the following stab:
2018 .stabs "class(A):sym_desc(struct)type_def(20)=type_desc(struct)struct_bytes(1)
2019 meth_name(ConstMeth)::type_def(21)sym_desc(method)
2020 returning(int);:arg(int);protection(public)modifier(const)virtual(no);
2021 meth_name(VolatileMeth)::type_def(22)=sym_desc(method)
2022 returning(char);:arg(char);protection(public)modifier(volatile)virt(no)
2023 meth_name(ConstVolMeth)::type_def(23)=sym_desc(method)
2024 returning(float);:arg(float);protection(public)modifer(const volatile)
2025 virtual(no);;", @dots{}
2029 .stabs "A:T20=s1ConstMeth::21=##1;:i;2B.;VolatileMeth::22=##2;:c;2C.;
2030 ConstVolMeth::23=##12;:f;2D.;;",128,0,0,0
2033 @node Virtual Methods
2034 @section Virtual Methods
2036 << The following examples are based on a4.C >>
2038 The presence of virtual methods in a class definition adds additional
2039 data to the class description. The extra data is appended to the
2040 description of the virtual method and to the end of the class
2041 description. Consider the class definition below:
2047 virtual int A_virt (int arg) @{ return arg; @};
2051 This results in the stab below describing class A. It defines a new
2052 type (20) which is an 8 byte structure. The first field of the class
2053 struct is Adat, an integer, starting at structure offset 0 and
2056 The second field in the class struct is not explicitly defined by the
2057 C++ class definition but is implied by the fact that the class
2058 contains a virtual method. This field is the vtable pointer. The
2059 name of the vtable pointer field starts with $vf and continues with a
2060 type reference to the class it is part of. In this example the type
2061 reference for class A is 20 so the name of its vtable pointer field is
2062 $vf20, followed by the usual colon.
2064 Next there is a type definition for the vtable pointer type (21).
2065 This is in turn defined as a pointer to another new type (22).
2067 Type 22 is the vtable itself, which is defined as an array, indexed by
2068 a range of integers between 0 and 1, and whose elements are of type
2069 17. Type 17 was the vtable record type defined by the boilerplate C++
2070 type definitions, as shown earlier.
2072 The bit offset of the vtable pointer field is 32. The number of bits
2073 in the field are not specified when the field is a vtable pointer.
2075 Next is the method definition for the virtual member function A_virt.
2076 Its description starts out using the same format as the non-virtual
2077 member functions described above, except instead of a dot after the
2078 `A' there is an asterisk, indicating that the function is virtual.
2079 Since is is virtual some addition information is appended to the end
2080 of the method description.
2082 The first number represents the vtable index of the method. This is a
2083 32 bit unsigned number with the high bit set, followed by a
2086 The second number is a type reference to the first base class in the
2087 inheritence hierarchy defining the virtual member function. In this
2088 case the class stab describes a base class so the virtual function is
2089 not overriding any other definition of the method. Therefore the
2090 reference is to the type number of the class that the stab is
2093 This is followed by three semi-colons. One marks the end of the
2094 current sub-section, one marks the end of the method field, and the
2095 third marks the end of the struct definition.
2097 For classes containing virtual functions the very last section of the
2098 string part of the stab holds a type reference to the first base
2099 class. This is preceeded by `~%' and followed by a final semi-colon.
2102 .stabs "class_name(A):type_def(20)=sym_desc(struct)struct_bytes(8)
2103 field_name(Adat):type_ref(int),bit_offset(0),field_bits(32);
2104 field_name(A virt func ptr):type_def(21)=type_desc(ptr to)type_def(22)=
2105 sym_desc(array)index_type_ref(range of int from 0 to 1);
2106 elem_type_ref(vtbl elem type),
2108 meth_name(A_virt)::typedef(23)=sym_desc(method)returning(int);
2109 :arg_type(int),protection(public)normal(yes)virtual(yes)
2110 vtable_index(1);class_first_defining(A);;;~%first_base(A);",
2115 .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
2119 @section Inheritence
2121 Stabs describing C++ derived classes include additional sections that
2122 describe the inheritence hierarchy of the class. A derived class stab
2123 also encodes the number of base classes. For each base class it tells
2124 if the base class is virtual or not, and if the inheritence is private
2125 or public. It also gives the offset into the object of the portion of
2126 the object corresponding to each base class.
2128 This additional information is embeded in the class stab following the
2129 number of bytes in the struct. First the number of base classes
2130 appears bracketed by an exclamation point and a comma.
2132 Then for each base type there repeats a series: two digits, a number,
2133 a comma, another number, and a semi-colon.
2135 The first of the two digits is 1 if the base class is virtual and 0 if
2136 not. The second digit is 2 if the derivation is public and 0 if not.
2138 The number following the first two digits is the offset from the start
2139 of the object to the part of the object pertaining to the base class.
2141 After the comma, the second number is a type_descriptor for the base
2142 type. Finally a semi-colon ends the series, which repeats for each
2145 The source below defines three base classes A, B, and C and the
2153 virtual int A_virt (int arg) @{ return arg; @};
2159 virtual int B_virt (int arg) @{return arg; @};
2165 virtual int C_virt (int arg) @{return arg; @};
2168 class D : A, virtual B, public C @{
2171 virtual int A_virt (int arg ) @{ return arg+1; @};
2172 virtual int B_virt (int arg) @{ return arg+2; @};
2173 virtual int C_virt (int arg) @{ return arg+3; @};
2174 virtual int D_virt (int arg) @{ return arg; @};
2178 Class stabs similar to the ones described earlier are generated for
2181 @c FIXME!!! the linebreaks in the following example probably make the
2182 @c examples literally unusable, but I don't know any other way to get
2183 @c them on the page.
2185 .stabs "A:T20=s8Adat:1,0,32;$vf20:21=*22=ar1;0;1;17,32;
2186 A_virt::23=##1;:i;2A*-2147483647;20;;;~%20;",128,0,0,0
2188 .stabs "B:Tt25=s8Bdat:1,0,32;$vf25:21,32;B_virt::26=##1;
2189 :i;2A*-2147483647;25;;;~%25;",128,0,0,0
2191 .stabs "C:Tt28=s8Cdat:1,0,32;$vf28:21,32;C_virt::29=##1;
2192 :i;2A*-2147483647;28;;;~%28;",128,0,0,0
2195 In the stab describing derived class D below, the information about
2196 the derivation of this class is encoded as follows.
2199 .stabs "derived_class_name:symbol_descriptors(struct tag&type)=
2200 type_descriptor(struct)struct_bytes(32)!num_bases(3),
2201 base_virtual(no)inheritence_public(no)base_offset(0),
2202 base_class_type_ref(A);
2203 base_virtual(yes)inheritence_public(no)base_offset(NIL),
2204 base_class_type_ref(B);
2205 base_virtual(no)inheritence_public(yes)base_offset(64),
2206 base_class_type_ref(C); @dots{}
2209 @c FIXME! fake linebreaks.
2211 .stabs "D:Tt31=s32!3,000,20;100,25;0264,28;$vb25:24,128;Ddat:
2212 1,160,32;A_virt::32=##1;:i;2A*-2147483647;20;;B_virt:
2213 :32:i;2A*-2147483647;25;;C_virt::32:i;2A*-2147483647;
2214 28;;D_virt::32:i;2A*-2147483646;31;;;~%20;",128,0,0,0
2217 @node Virtual Base Classes
2218 @section Virtual Base Classes
2220 A derived class object consists of a concatination in memory of the
2221 data areas defined by each base class, starting with the leftmost and
2222 ending with the rightmost in the list of base classes. The exception
2223 to this rule is for virtual inheritence. In the example above, class
2224 D inherits virtually from base class B. This means that an instance
2225 of a D object will not contain it's own B part but merely a pointer to
2226 a B part, known as a virtual base pointer.
2228 In a derived class stab, the base offset part of the derivation
2229 information, described above, shows how the base class parts are
2230 ordered. The base offset for a virtual base class is always given as
2231 0. Notice that the base offset for B is given as 0 even though B is
2232 not the first base class. The first base class A starts at offset 0.
2234 The field information part of the stab for class D describes the field
2235 which is the pointer to the virtual base class B. The vbase pointer
2236 name is $vb followed by a type reference to the virtual base class.
2237 Since the type id for B in this example is 25, the vbase pointer name
2240 @c FIXME!! fake linebreaks below
2242 .stabs "D:Tt31=s32!3,000,20;100,25;0264,28;$vb25:24,128;Ddat:1,
2243 160,32;A_virt::32=##1;:i;2A*-2147483647;20;;B_virt::32:i;
2244 2A*-2147483647;25;;C_virt::32:i;2A*-2147483647;28;;D_virt:
2245 :32:i;2A*-2147483646;31;;;~%20;",128,0,0,0
2248 Following the name and a semicolon is a type reference describing the
2249 type of the virtual base class pointer, in this case 24. Type 24 was
2250 defined earlier as the type of the B class `this` pointer. The
2251 `this' pointer for a class is a pointer to the class type.
2254 .stabs "this:P24=*25=xsB:",64,0,0,8
2257 Finally the field offset part of the vbase pointer field description
2258 shows that the vbase pointer is the first field in the D object,
2259 before any data fields defined by the class. The layout of a D class
2260 object is a follows, Adat at 0, the vtable pointer for A at 32, Cdat
2261 at 64, the vtable pointer for C at 96, the virtual ase pointer for B
2262 at 128, and Ddat at 160.
2265 @node Static Members
2266 @section Static Members
2268 The data area for a class is a concatenation of the space used by the
2269 data members of the class. If the class has virtual methods, a vtable
2270 pointer follows the class data. The field offset part of each field
2271 description in the class stab shows this ordering.
2273 << How is this reflected in stabs? See Cygnus bug #677 for some info. >>
2276 @appendix Example2.c - source code for extended example
2280 2 register int g_bar asm ("%g5");
2281 3 static int s_g_repeat = 2;
2287 9 char s_char_vec[8];
2288 10 struct s_tag* s_next;
2291 13 typedef struct s_tag s_typedef;
2293 15 char char_vec[3] = @{'a','b','c'@};
2295 17 main (argc, argv)
2299 21 static float s_flap;
2301 23 for (times=0; times < s_g_repeat; times++)@{
2303 25 printf ("Hello world\n");
2307 29 enum e_places @{first,second=3,last@};
2309 31 static s_proc (s_arg, s_ptr_arg, char_vec)
2311 33 s_typedef* s_ptr_arg;
2325 @appendix Example2.s - assembly code for extended example
2329 2 .stabs "/cygint/s1/users/jcm/play/",100,0,0,Ltext0
2330 3 .stabs "example2.c",100,0,0,Ltext0
2333 6 .stabs "int:t1=r1;-2147483648;2147483647;",128,0,0,0
2334 7 .stabs "char:t2=r2;0;127;",128,0,0,0
2335 8 .stabs "long int:t3=r1;-2147483648;2147483647;",128,0,0,0
2336 9 .stabs "unsigned int:t4=r1;0;-1;",128,0,0,0
2337 10 .stabs "long unsigned int:t5=r1;0;-1;",128,0,0,0
2338 11 .stabs "short int:t6=r1;-32768;32767;",128,0,0,0
2339 12 .stabs "long long int:t7=r1;0;-1;",128,0,0,0
2340 13 .stabs "short unsigned int:t8=r1;0;65535;",128,0,0,0
2341 14 .stabs "long long unsigned int:t9=r1;0;-1;",128,0,0,0
2342 15 .stabs "signed char:t10=r1;-128;127;",128,0,0,0
2343 16 .stabs "unsigned char:t11=r1;0;255;",128,0,0,0
2344 17 .stabs "float:t12=r1;4;0;",128,0,0,0
2345 18 .stabs "double:t13=r1;8;0;",128,0,0,0
2346 19 .stabs "long double:t14=r1;8;0;",128,0,0,0
2347 20 .stabs "void:t15=15",128,0,0,0
2348 21 .stabs "g_foo:G2",32,0,0,0
2353 26 .stabs "s_g_repeat:S1",38,0,0,_s_g_repeat
2357 @c FIXME! fake linebreak in line 30
2358 30 .stabs "s_tag:T16=s20s_int:1,0,32;s_float:12,32,32;s_char_vec:
2359 17=ar1;0;7;2,64,64;s_next:18=*16,128,32;;",128,0,0,0
2360 31 .stabs "s_typedef:t16",128,0,0,0
2361 32 .stabs "char_vec:G19=ar1;0;2;2",32,0,0,0
2362 33 .global _char_vec
2368 39 .reserve _s_flap.0,4,"bss",4
2372 43 .ascii "Hello world\12\0"
2377 48 .stabn 68,0,20,LM1
2380 51 save %sp,-144,%sp
2387 58 .stabn 68,0,23,LM2
2391 62 sethi %hi(_s_g_repeat),%o0
2393 64 ld [%o0+%lo(_s_g_repeat)],%o0
2398 69 .stabn 68,0,25,LM3
2400 71 sethi %hi(LC0),%o1
2401 72 or %o1,%lo(LC0),%o0
2404 75 .stabn 68,0,26,LM4
2407 78 .stabn 68,0,23,LM5
2415 86 .stabn 68,0,27,LM6
2418 89 .stabn 68,0,27,LM7
2423 94 .stabs "main:F1",36,0,0,_main
2424 95 .stabs "argc:p1",160,0,0,68
2425 96 .stabs "argv:p20=*21=*2",160,0,0,72
2426 97 .stabs "s_flap:V12",40,0,0,_s_flap.0
2427 98 .stabs "times:1",128,0,0,-20
2428 99 .stabn 192,0,0,LBB2
2429 100 .stabs "inner:1",128,0,0,-24
2430 101 .stabn 192,0,0,LBB3
2431 102 .stabn 224,0,0,LBE3
2432 103 .stabn 224,0,0,LBE2
2433 104 .stabs "e_places:T22=efirst:0,second:3,last:4,;",128,0,0,0
2434 @c FIXME: fake linebreak in line 105
2435 105 .stabs "u_tag:T23=u4u_int:1,0,32;u_float:12,0,32;u_char:21,0,32;;",
2440 109 .stabn 68,0,35,LM8
2443 112 save %sp,-120,%sp
2449 118 .stabn 68,0,41,LM9
2452 121 .stabn 68,0,41,LM10
2457 126 .stabs "s_proc:f1",36,0,0,_s_proc
2458 127 .stabs "s_arg:p16",160,0,0,0
2459 128 .stabs "s_ptr_arg:p18",160,0,0,72
2460 129 .stabs "char_vec:p21",160,0,0,76
2461 130 .stabs "an_u:23",128,0,0,-20
2462 131 .stabn 192,0,0,LBB4
2463 132 .stabn 224,0,0,LBE4
2464 133 .stabs "g_bar:r1",64,0,0,5
2465 134 .stabs "g_pf:G24=*25=f1",32,0,0,0
2466 135 .common _g_pf,4,"bss"
2467 136 .stabs "g_an_s:G16",32,0,0,0
2468 137 .common _g_an_s,20,"bss"
2472 @node Quick reference
2473 @appendix Quick reference
2476 * Stab types:: Table A: Symbol types from stabs
2477 * Assembler types:: Table B: Symbol types from assembler and linker
2478 * Symbol descriptors:: Table C
2479 * Type Descriptors:: Table D
2483 @section Table A: Symbol types from stabs
2485 Table A lists stab types sorted by type number. Stab type numbers are
2486 32 and greater. This is the full list of stab numbers, including stab
2487 types that are used in languages other than C.
2489 The #define names for these stab types are defined in:
2490 devo/include/aout/stab.def
2493 type type #define used to describe
2494 dec hex name source program feature
2495 ------------------------------------------------
2496 32 0x20 N_GYSM global symbol
2497 34 0X22 N_FNAME function name (for BSD Fortran)
2498 36 0x24 N_FUN function name or text segment variable for C
2499 38 0x26 N_STSYM static symbol (data segment w/internal linkage)
2500 40 0x28 N_LCSYM .lcomm symbol(BSS-seg variable w/internal linkage)
2501 42 0x2a N_MAIN Name of main routine (not used in C)
2502 48 0x30 N_PC global symbol (for Pascal)
2503 50 0x32 N_NSYMS number of symbols (according to Ultrix V4.0)
2504 52 0x34 N_NOMAP no DST map for sym (according to Ultrix V4.0)
2505 64 0x40 N_RSYM register variable
2506 66 0x42 N_M2C Modula-2 compilation unit
2507 68 0x44 N_SLINE line number in text segment
2508 70 0x46 N_DSLINE line number in data segment
2510 72 0x48 N_BSLINE line number in bss segment
2511 72 0x48 N_BROWS Sun source code browser, path to .cb file
2513 74 0x4a N_DEFD GNU Modula2 definition module dependency
2515 80 0x50 N_EHDECL GNU C++ exception variable
2516 80 0x50 N_MOD2 Modula2 info "for imc" (according to Ultrix V4.0)
2518 84 0x54 N_CATCH GNU C++ "catch" clause
2519 96 0x60 N_SSYM structure of union element
2520 100 0x64 N_SO path and name of source file
2521 128 0x80 N_LSYM automatic var in the stack
2522 (also used for type desc.)
2523 130 0x82 N_BINCL beginning of an include file (Sun only)
2524 132 0x84 N_SOL Name of sub-source (#include) file.
2525 160 0xa0 N_PSYM parameter variable
2526 162 0xa2 N_EINCL end of an include file
2527 164 0xa4 N_ENTRY alternate entry point
2528 192 0xc0 N_LBRAC beginning of a lexical block
2529 194 0xc2 N_EXCL place holder for a deleted include file
2530 196 0xc4 N_SCOPE modula2 scope information (Sun linker)
2531 224 0xe0 N_RBRAC end of a lexical block
2532 226 0xe2 N_BCOMM begin named common block
2533 228 0xe4 N_ECOMM end named common block
2534 232 0xe8 N_ECOML end common (local name)
2536 << used on Gould systems for non-base registers syms >>
2537 240 0xf0 N_NBTEXT ??
2538 242 0xf2 N_NBDATA ??
2544 @node Assembler types
2545 @section Table B: Symbol types from assembler and linker
2547 Table B shows the types of symbol table entries that hold assembler
2550 The #define names for these n_types values are defined in
2551 /include/aout/aout64.h
2555 n_type n_type name used to describe
2556 ------------------------------------------
2557 1 0x0 N_UNDF undefined symbol
2558 2 0x2 N_ABS absolute symbol -- defined at a particular address
2559 3 0x3 extern " (vs. file scope)
2560 4 0x4 N_TEXT text symbol -- defined at offset in text segment
2561 5 0x5 extern " (vs. file scope)
2562 6 0x6 N_DATA data symbol -- defined at offset in data segment
2563 7 0x7 extern " (vs. file scope)
2564 8 0x8 N_BSS BSS symbol -- defined at offset in zero'd segment
2565 9 extern " (vs. file scope)
2567 12 0x0C N_FN_SEQ func name for Sequent compilers (stab exception)
2569 49 0x12 N_COMM common sym -- visable after shared lib dynamic link
2570 31 0x1f N_FN file name of a .o file
2573 @node Symbol descriptors
2574 @section Table C: Symbol descriptors
2576 @c Please keep this alphabetical
2579 Local variable, @xref{Automatic variables}.
2582 Parameter passed by reference in register, @xref{Parameters}.
2585 Constant, @xref{Constants}.
2588 Conformant array bound, @xref{Parameters}.
2591 Floating point register variable, @xref{Register variables}.
2594 Parameter in floating point register, @xref{Parameters}.
2597 Static function, @xref{Procedures}.
2600 Global function, @xref{Procedures}.
2603 Global variable, @xref{Global Variables}.
2609 Internal (nested) procedure, @xref{Procedures}.
2612 Internal (nested) function, @xref{Procedures}.
2615 Label name (documented by AIX, no further information known).
2618 Module, @xref{Procedures}.
2621 Argument list parameter @xref{Parameters}.
2630 Global Procedure (AIX), @xref{Procedures}.
2631 Register parameter (GNU), @xref{Parameters}.
2634 Static Procedure, @xref{Procedures}.
2637 Register parameter @xref{Parameters}.
2640 Register variable, @xref{Register variables}.
2643 Static file scope variable @xref{Initialized statics},
2644 @xref{Un-initialized statics}.
2647 Type name, @xref{Typedefs}.
2650 enumeration, struct or union tag, @xref{Unions}.
2653 Call by reference, @xref{Parameters}.
2656 Static procedure scope variable @xref{Initialized statics},
2657 @xref{Un-initialized statics}.
2660 Conformant array, @xref{Parameters}.
2663 Function return variable, @xref{Parameters}.
2666 @node Type Descriptors
2667 @section Table D: Type Descriptors
2671 Type reference, @xref{Overview}.
2677 Type Attributes (AIX), @xref{Overview}.
2678 Some C++ thing (GNU).
2696 Union specifications.
2700 @node Expanded reference
2701 @appendix Expanded reference by stab type.
2705 The first line is the symbol type expressed in decimal, hexadecimal,
2706 and as a #define (see devo/include/aout/stab.def).
2708 The second line describes the language constructs the symbol type
2711 The third line is the stab format with the significant stab fields
2712 named and the rest NIL.
2714 Subsequent lines expand upon the meaning and possible values for each
2715 significant stab field. # stands in for the type descriptor.
2717 Finally, any further information.
2720 * N_GSYM:: Global variable
2721 * N_FNAME:: Function name (BSD Fortran)
2722 * N_FUN:: C Function name or text segment variable
2723 * N_STSYM:: Initialized static symbol
2724 * N_LCSYM:: Uninitialized static symbol
2725 * N_MAIN:: Name of main routine (not for C)
2726 * N_PC:: Pascal global symbol
2727 * N_NSYMS:: Number of symbols
2728 * N_NOMAP:: No DST map
2729 * N_RSYM:: Register variable
2730 * N_M2C:: Modula-2 compilation unit
2731 * N_SLINE:: Line number in text segment
2732 * N_DSLINE:: Line number in data segment
2733 * N_BSLINE:: Line number in bss segment
2734 * N_BROWS:: Path to .cb file for Sun source code browser
2735 * N_DEFD:: GNU Modula2 definition module dependency
2736 * N_EHDECL:: GNU C++ exception variable
2737 * N_MOD2:: Modula2 information "for imc"
2738 * N_CATCH:: GNU C++ "catch" clause
2739 * N_SSYM:: Structure or union element
2740 * N_SO:: Source file containing main
2741 * N_LSYM:: Automatic variable
2742 * N_BINCL:: Beginning of include file (Sun only)
2743 * N_SOL:: Name of include file
2744 * N_PSYM:: Parameter variable
2745 * N_EINCL:: End of include file
2746 * N_ENTRY:: Alternate entry point
2747 * N_LBRAC:: Beginning of lexical block
2748 * N_EXCL:: Deleted include file
2749 * N_SCOPE:: Modula2 scope information (Sun only)
2750 * N_RBRAC:: End of lexical block
2751 * N_BCOMM:: Begin named common block
2752 * N_ECOMM:: End named common block
2753 * N_ECOML:: End common
2754 * Gould:: non-base register symbols used on Gould systems
2755 * N_LENG:: Length of preceding entry
2759 @section 32 - 0x20 - N_GYSM
2764 .stabs "name", N_GSYM, NIL, NIL, NIL
2768 "name" -> "symbol_name:#type"
2772 Only the "name" field is significant. The location of the variable is
2773 obtained from the corresponding external symbol.
2776 @section 34 - 0x22 - N_FNAME
2777 Function name (for BSD Fortran)
2780 .stabs "name", N_FNAME, NIL, NIL, NIL
2784 "name" -> "function_name"
2787 Only the "name" field is significant. The location of the symbol is
2788 obtained from the corresponding extern symbol.
2791 @section 36 - 0x24 - N_FUN
2793 Function name (@pxref{Procedures}) or text segment variable
2794 (@pxref{Variables}).
2796 @exdent @emph{For functions:}
2797 "name" -> "proc_name:#return_type"
2798 # -> F (global function)
2800 desc -> line num for proc start. (GCC doesn't set and DBX doesn't miss it.)
2801 value -> Code address of proc start.
2803 @exdent @emph{For text segment variables:}
2804 <<How to create one?>>
2808 @section 38 - 0x26 - N_STSYM
2809 Initialized static symbol (data segment w/internal linkage).
2812 .stabs "name", N_STSYM, NIL, NIL, value
2816 "name" -> "symbol_name#type"
2817 # -> S (scope global to compilation unit)
2818 -> V (scope local to a procedure)
2819 value -> Data Address
2823 @section 40 - 0x28 - N_LCSYM
2824 Unitialized static (.lcomm) symbol(BSS segment w/internal linkage).
2827 .stabs "name", N_LCLSYM, NIL, NIL, value
2831 "name" -> "symbol_name#type"
2832 # -> S (scope global to compilation unit)
2833 -> V (scope local to procedure)
2834 value -> BSS Address
2838 @section 42 - 0x2a - N_MAIN
2839 Name of main routine (not used in C)
2842 .stabs "name", N_MAIN, NIL, NIL, NIL
2846 "name" -> "name_of_main_routine"
2850 @section 48 - 0x30 - N_PC
2851 Global symbol (for Pascal)
2854 .stabs "name", N_PC, NIL, NIL, value
2858 "name" -> "symbol_name" <<?>>
2859 value -> supposedly the line number (stab.def is skeptical)
2865 global pascal symbol: name,,0,subtype,line
2870 @section 50 - 0x32 - N_NSYMS
2871 Number of symbols (according to Ultrix V4.0)
2874 0, files,,funcs,lines (stab.def)
2878 @section 52 - 0x34 - N_NOMAP
2879 no DST map for sym (according to Ultrix V4.0)
2882 name, ,0,type,ignored (stab.def)
2886 @section 64 - 0x40 - N_RSYM
2890 .stabs "name:type",N_RSYM,0,RegSize,RegNumber (Sun doc)
2894 @section 66 - 0x42 - N_M2C
2895 Modula-2 compilation unit
2898 .stabs "name", N_M2C, 0, desc, value
2902 "name" -> "unit_name,unit_time_stamp[,code_time_stamp]
2904 value -> 0 (main unit)
2909 @section 68 - 0x44 - N_SLINE
2910 Line number in text segment
2913 .stabn N_SLINE, 0, desc, value
2918 value -> code_address (relocatable addr where the corresponding code starts)
2921 For single source lines that generate discontiguous code, such as flow
2922 of control statements, there may be more than one N_SLINE stab for the
2923 same source line. In this case there is a stab at the start of each
2924 code range, each with the same line number.
2927 @section 70 - 0x46 - N_DSLINE
2928 Line number in data segment
2931 .stabn N_DSLINE, 0, desc, value
2936 value -> data_address (relocatable addr where the corresponding code
2940 See comment for N_SLINE above.
2943 @section 72 - 0x48 - N_BSLINE
2944 Line number in bss segment
2947 .stabn N_BSLINE, 0, desc, value
2952 value -> bss_address (relocatable addr where the corresponding code
2956 See comment for N_SLINE above.
2959 @section 72 - 0x48 - N_BROWS
2960 Sun source code browser, path to .cb file
2963 "path to associated .cb file"
2965 Note: type field value overlaps with N_BSLINE
2968 @section 74 - 0x4a - N_DEFD
2969 GNU Modula2 definition module dependency
2971 GNU Modula-2 definition module dependency. Value is the modification
2972 time of the definition file. Other is non-zero if it is imported with
2973 the GNU M2 keyword %INITIALIZE. Perhaps N_M2C can be used if there
2974 are enough empty fields?
2977 @section 80 - 0x50 - N_EHDECL
2978 GNU C++ exception variable <<?>>
2980 "name is variable name"
2982 Note: conflicts with N_MOD2.
2985 @section 80 - 0x50 - N_MOD2
2986 Modula2 info "for imc" (according to Ultrix V4.0)
2988 Note: conflicts with N_EHDECL <<?>>
2991 @section 84 - 0x54 - N_CATCH
2992 GNU C++ "catch" clause
2994 GNU C++ `catch' clause. Value is its address. Desc is nonzero if
2995 this entry is immediately followed by a CAUGHT stab saying what
2996 exception was caught. Multiple CAUGHT stabs means that multiple
2997 exceptions can be caught here. If Desc is 0, it means all exceptions
3001 @section 96 - 0x60 - N_SSYM
3002 Structure or union element
3004 Value is offset in the structure.
3006 <<?looking at structs and unions in C I didn't see these>>
3009 @section 100 - 0x64 - N_SO
3010 Path and name of source file containing main routine
3013 .stabs "name", N_SO, NIL, NIL, value
3017 "name" -> /source/directory/
3020 value -> the starting text address of the compilation.
3023 These are found two in a row. The name field of the first N_SO contains
3024 the directory that the source file is relative to. The name field of
3025 the second N_SO contains the name of the source file itself.
3027 Only some compilers (e.g. gcc2, Sun cc) include the directory; this
3028 symbol can be distinguished by the fact that it ends in a slash.
3029 According to a comment in GDB's partial-stab.h, other compilers
3030 (especially unnamed C++ compilers) put out useless N_SO's for
3031 nonexistent source files (after the N_SO for the real source file).
3034 @section 128 - 0x80 - N_LSYM
3035 Automatic var in the stack (also used for type descriptors.)
3038 .stabs "name" N_LSYM, NIL, NIL, value
3042 @exdent @emph{For stack based local variables:}
3044 "name" -> name of the variable
3045 value -> offset from frame pointer (negative)
3047 @exdent @emph{For type descriptors:}
3049 "name" -> "name_of_the_type:#type"
3052 type -> type_ref (or) type_def
3054 type_ref -> type_number
3055 type_def -> type_number=type_desc etc.
3058 Type may be either a type reference or a type definition. A type
3059 reference is a number that refers to a previously defined type. A
3060 type definition is the number that will refer to this type, followed
3061 by an equals sign, a type descriptor and the additional data that
3062 defines the type. See the Table D for type descriptors and the
3063 section on types for what data follows each type descriptor.
3066 @section 130 - 0x82 - N_BINCL
3068 Beginning of an include file (Sun only)
3070 Beginning of an include file. Only Sun uses this. In an object file,
3071 only the name is significant. The Sun linker puts data into some of
3075 @section 132 - 0x84 - N_SOL
3077 Name of a sub-source file (#include file). Value is starting address
3082 @section 160 - 0xa0 - N_PSYM
3084 Parameter variable. @xref{Parameters}.
3087 @section 162 - 0xa2 - N_EINCL
3089 End of an include file. This and N_BINCL act as brackets around the
3090 file's output. In an ojbect file, there is no significant data in
3091 this entry. The Sun linker puts data into some of the fields.
3095 @section 164 - 0xa4 - N_ENTRY
3097 Alternate entry point.
3098 Value is its address.
3102 @section 192 - 0xc0 - N_LBRAC
3104 Beginning of a lexical block (left brace). The variable defined
3105 inside the block precede the N_LBRAC symbol. Or can they follow as
3106 well as long as a new N_FUNC was not encountered. <<?>>
3109 .stabn N_LBRAC, NIL, NIL, value
3113 value -> code address of block start.
3117 @section 194 - 0xc2 - N_EXCL
3119 Place holder for a deleted include file. Replaces a N_BINCL and
3120 everything up to the corresponding N_EINCL. The Sun linker generates
3121 these when it finds multiple indentical copies of the symbols from an
3122 included file. This appears only in output from the Sun linker.
3126 @section 196 - 0xc4 - N_SCOPE
3128 Modula2 scope information (Sun linker)
3132 @section 224 - 0xe0 - N_RBRAC
3134 End of a lexical block (right brace)
3137 .stabn N_RBRAC, NIL, NIL, value
3141 value -> code address of the end of the block.
3145 @section 226 - 0xe2 - N_BCOMM
3147 Begin named common block.
3149 Only the name is significant.
3153 @section 228 - 0xe4 - N_ECOMM
3155 End named common block.
3157 Only the name is significant and it should match the N_BCOMM
3161 @section 232 - 0xe8 - N_ECOML
3163 End common (local name)
3169 @section Non-base registers on Gould systems
3170 << used on Gould systems for non-base registers syms, values assigned
3171 at random, need real info from Gould. >>
3175 240 0xf0 N_NBTEXT ??
3176 242 0xf2 N_NBDATA ??
3183 @section - 0xfe - N_LENG
3185 Second symbol entry containing a length-value for the preceding entry.
3186 The value is the length.
3189 @appendix Questions and anomalies
3193 For GNU C stabs defining local and global variables (N_LSYM and
3194 N_GSYM), the desc field is supposed to contain the source line number
3195 on which the variable is defined. In reality the desc field is always
3196 0. (This behavour is defined in dbxout.c and putting a line number in
3197 desc is controlled by #ifdef WINNING_GDB which defaults to false). Gdb
3198 supposedly uses this information if you say 'list var'. In reality
3199 var can be a variable defined in the program and gdb says `function
3203 In GNU C stabs there seems to be no way to differentiate tag types:
3204 structures, unions, and enums (symbol descriptor T) and typedefs
3205 (symbol descriptor t) defined at file scope from types defined locally
3206 to a procedure or other more local scope. They all use the N_LSYM
3207 stab type. Types defined at procedure scope are emited after the
3208 N_RBRAC of the preceding function and before the code of the
3209 procedure in which they are defined. This is exactly the same as
3210 types defined in the source file between the two procedure bodies.
3211 GDB overcompensates by placing all types in block #1, the block for
3212 symbols of file scope. This is true for default, -ansi and
3213 -traditional compiler options. (Bugs gcc/1063, gdb/1066.)
3216 What ends the procedure scope? Is it the proc block's N_RBRAC or the
3217 next N_FUN? (I believe its the first.)
3220 The comment in xcoff.h says DBX_STATIC_CONST_VAR_CODE is used for
3221 static const variables. DBX_STATIC_CONST_VAR_CODE is set to N_FUN by
3222 default, in dbxout.c. If included, xcoff.h redefines it to N_STSYM.
3223 But testing the default behaviour, my Sun4 native example shows
3224 N_STSYM not N_FUN is used to describe file static initialized
3225 variables. (the code tests for TREE_READONLY(decl) &&
3226 !TREE_THIS_VOLATILE(decl) and if true uses DBX_STATIC_CONST_VAR_CODE).
3229 Global variable stabs don't have location information. This comes
3230 from the external symbol for the same variable. The external symbol
3231 has a leading underbar on the _name of the variable and the stab does
3232 not. How do we know these two symbol table entries are talking about
3233 the same symbol when their names are different?
3236 Can gcc be configured to output stabs the way the Sun compiler
3237 does, so that their native debugging tools work? <NO?> It doesn't by
3238 default. GDB reads either format of stab. (gcc or SunC). How about
3242 @node xcoff-differences
3243 @appendix Differences between GNU stabs in a.out and GNU stabs in xcoff
3245 @c FIXME: Merge *all* these into the main body of the document.
3246 @c Progress report: I have merged all the information from the
3247 @c "dbx stabstring grammar" section of the AIX documentation into
3248 @c the main body of this document, except the types.
3249 (The AIX/RS6000 native object file format is xcoff with stabs). This
3250 appendix only covers those differences which are not covered in the main
3251 body of this document.
3255 Instead of .stabs, xcoff uses .stabx.
3258 The data fields of an xcoff .stabx are in a different order than an
3259 a.out .stabs. The order is: string, value, type. The desc and null
3260 fields present in a.out stabs are missing in xcoff stabs. For N_GSYM
3261 the value field is the name of the symbol.
3264 BSD a.out stab types correspond to AIX xcoff storage classes. In general the
3265 mapping is N_STABTYPE becomes C_STABTYPE. Some stab types in a.out
3266 are not supported in xcoff. See Table E. for full mappings.
3269 initialised static N_STSYM and un-initialized static N_LCSYM both map
3270 to the C_STSYM storage class. But the destinction is preserved
3271 because in xcoff N_STSYM and N_LCSYM must be emited in a named static
3272 block. Begin the block with .bs s[RW] data_section_name for N_STSYM
3273 or .bs s bss_section_name for N_LCSYM. End the block with .es
3276 xcoff stabs describing tags and typedefs use the N_DECL (0x8c)instead
3277 of N_LSYM stab type.
3280 xcoff uses N_RPSYM (0x8e) instead of the N_RSYM stab type for register
3281 variables. If the register variable is also a value parameter, then
3282 use R instead of P for the symbol descriptor.
3285 xcoff uses negative numbers as type references to the basic types.
3286 There are no boilerplate type definitions emited for these basic
3287 types. << make table of basic types and type numbers for C >>
3290 xcoff .stabx sometimes don't have the name part of the string field.
3293 xcoff uses a .file stab type to represent the source file name. There
3294 is no stab for the path to the source file.
3297 xcoff uses a .line stab type to represent source lines. The format
3298 is: .line line_number.
3301 xcoff emits line numbers relative to the start of the current
3302 function. The start of a function is marked by .bf. If a function
3303 includes lines from a seperate file, then those line numbers are
3304 absolute line numbers in the <<sub-?>> file being compiled.
3307 The start of current include file is marked with: .bi "filename" and
3308 the end marked with .ei "filename"
3311 If the xcoff stab is a N_FUN (C_FUN) then follow the string field with
3312 ,. instead of just ,
3316 (I think that's it for .s file differences. They could stand to be
3317 better presented. This is just a list of what I have noticed so far.
3318 There are a *lot* of differences in the information in the symbol
3319 tables of the executable and object files.)
3321 Table E: mapping a.out stab types to xcoff storage classes
3324 stab type storage class
3325 -------------------------------
3334 N_RPSYM (0x8e) C_RPSYM
3344 N_DECL (0x8c) C_DECL
3361 @node Sun-differences
3362 @appendix Differences between GNU stabs and Sun native stabs.
3364 @c FIXME: Merge all this stuff into the main body of the document.
3368 GNU C stabs define *all* types, file or procedure scope, as
3369 N_LSYM. Sun doc talks about using N_GSYM too.
3372 Stabs describing block scopes, N_LBRAC and N_RBRAC are supposed to
3373 contain the nesting level of the block in the desc field, re Sun doc.
3374 GNU stabs always have 0 in that field. dbx seems not to care.
3377 Sun C stabs use type number pairs in the format (a,b) where a is a
3378 number starting with 1 and incremented for each sub-source file in the
3379 compilation. b is a number starting with 1 and incremented for each
3380 new type defined in the compilation. GNU C stabs use the type number
3381 alone, with no source file number.