* stabs.texinfo (Parameters): Keep trying to get this right.
[binutils-gdb.git] / gdb / doc / stabs.texinfo
1 \input texinfo
2 @setfilename stabs.info
3
4 @ifinfo
5 @format
6 START-INFO-DIR-ENTRY
7 * Stabs: (stabs). The "stabs" debugging information format.
8 END-INFO-DIR-ENTRY
9 @end format
10 @end ifinfo
11
12 @ifinfo
13 This document describes GNU stabs (debugging symbol tables) in a.out files.
14
15 Copyright 1992 Free Software Foundation, Inc.
16 Contributed by Cygnus Support. Written by Julia Menapace.
17
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.
21
22 @ignore
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).
27
28 @end ignore
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).
32 @end ifinfo
33
34 @setchapternewpage odd
35 @settitle STABS
36 @titlepage
37 @title The ``stabs'' debug format
38 @author Julia Menapace
39 @author Cygnus Support
40 @page
41 @tex
42 \def\$#1${{#1}} % Kluge: collect RCS revision info without $...$
43 \xdef\manvers{\$Revision$} % For use in headers, footers too
44 {\parskip=0pt
45 \hfill Cygnus Support\par
46 \hfill \manvers\par
47 \hfill \TeX{}info \texinfoversion\par
48 }
49 @end tex
50
51 @vskip 0pt plus 1filll
52 Copyright @copyright{} 1992 Free Software Foundation, Inc.
53 Contributed by Cygnus Support.
54
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.
58
59 @end titlepage
60
61 @ifinfo
62 @node Top
63 @top The "stabs" representation of debugging information
64
65 This document describes the GNU stabs debugging format in a.out files.
66
67 @menu
68 * Overview:: Overview of stabs
69 * Program structure:: Encoding of the structure of the program
70 * Simple types::
71 * Example:: A comprehensive example in C
72 * Variables::
73 * Aggregate Types::
74 * Symbol tables:: Symbol information in symbol tables
75 * GNU Cplusplus stabs::
76
77 Appendixes:
78 * Example2.c:: Source code for extended example
79 * Example2.s:: Assembly code for extended example
80 * Quick reference:: Various refernce tables
81 * Expanded reference:: Reference information by stab type
82 * Questions:: Questions and anomolies
83 * xcoff-differences:: Differences between GNU stabs in a.out
84 and GNU stabs in xcoff
85 * Sun-differences:: Differences between GNU stabs and Sun
86 native stabs
87 @end menu
88 @end ifinfo
89
90
91 @node Overview
92 @chapter Overview of stabs
93
94 @dfn{Stabs} refers to a format for information that describes a program
95 to a debugger. This format was apparently invented by
96 @c FIXME! <<name of inventor>> at
97 the University of California at Berkeley, for the @code{pdx} Pascal
98 debugger; the format has spread widely since then.
99
100 @menu
101 * Flow:: Overview of debugging information flow
102 * Stabs format:: Overview of stab format
103 * C example:: A simple example in C source
104 * Assembly code:: The simple example at the assembly level
105 @end menu
106
107 @node Flow
108 @section Overview of debugging information flow
109
110 The GNU C compiler compiles C source in a @file{.c} file into assembly
111 language in a @file{.s} file, which is translated by the assembler into
112 a @file{.o} file, and then linked with other @file{.o} files and
113 libraries to produce an executable file.
114
115 With the @samp{-g} option, GCC puts additional debugging information in
116 the @file{.s} file, which is slightly transformed by the assembler and
117 linker, and carried through into the final executable. This debugging
118 information describes features of the source file like line numbers,
119 the types and scopes of variables, and functions, their parameters and
120 their scopes.
121
122 For some object file formats, the debugging information is
123 encapsulated in assembler directives known collectively as `stab' (symbol
124 table) directives, interspersed with the generated code. Stabs are
125 the native format for debugging information in the a.out and xcoff
126 object file formats. The GNU tools can also emit stabs in the coff
127 and ecoff object file formats.
128
129 The assembler adds the information from stabs to the symbol information
130 it places by default in the symbol table and the string table of the
131 @file{.o} file it is building. The linker consolidates the @file{.o}
132 files into one executable file, with one symbol table and one string
133 table. Debuggers use the symbol and string tables in the executable as
134 a source of debugging information about the program.
135
136 @node Stabs format
137 @section Overview of stab format
138
139 There are three overall formats for stab assembler directives
140 differentiated by the first word of the stab. The name of the directive
141 describes what combination of four possible data fields will follow. It
142 is either @code{.stabs} (string), @code{.stabn} (number), or
143 @code{.stabd} (dot).
144
145 The overall format of each class of stab is:
146
147 @example
148 .stabs "@var{string}",@var{type},0,@var{desc},@var{value}
149 .stabn @var{type},0,@var{desc},@var{value}
150 .stabd @var{type},0,@var{desc}
151 @end example
152
153 In general, in @code{.stabs} the @var{string} field contains name and type
154 information. For @code{.stabd} the value field is implicit and has the value
155 of the current file location. Otherwise the value field often
156 contains a relocatable address, frame pointer offset, or register
157 number, that maps to the source code element described by the stab.
158
159 The real key to decoding the meaning of a stab is the number in its type
160 field. Each possible type number defines a different stab type. The
161 stab type further defines the exact interpretation of, and possible
162 values for, any remaining @code{"@var{string}"}, @var{desc}, or
163 @var{value} fields present in the stab. Table A (@pxref{Stab
164 types,,Table A: Symbol types from stabs}) lists in numeric order
165 the possible type field values for stab directives. The reference
166 section that follows Table A describes the meaning of the fields for
167 each stab type in detail. The examples that follow this overview
168 introduce the stab types in terms of the source code elements they
169 describe.
170
171 For @code{.stabs} the @code{"@var{string}"} field holds the meat of the
172 debugging information. The generally unstructured nature of this field
173 is what makes stabs extensible. For some stab types the string field
174 contains only a name. For other stab types the contents can be a great
175 deal more complex.
176
177 The overall format is of the @code{"@var{string}"} field is:
178
179 @example
180 "@var{name}@r{[}:@var{symbol_descriptor}@r{]}
181 @r{[}@var{type_number}@r{[}=@var{type_descriptor} @r{@dots{}]]}"
182 @end example
183
184 @var{name} is the name of the symbol represented by the stab.
185
186 The @var{symbol_descriptor} following the @samp{:} is an alphabetic
187 character that tells more specifically what kind of symbol the stab
188 represents. If the @var{symbol_descriptor} is omitted, but type
189 information follows, then the stab represents a local variable. For a
190 list of symbol_descriptors, see @ref{Symbol descriptors,,Table C: Symbol
191 descriptors}.
192
193 Type information is either a @var{type_number}, or a
194 @samp{@var{type_number}=}. The @var{type_number} alone is a type
195 reference, referring directly to a type that has already been defined.
196
197 The @samp{@var{type_number}=} is a type definition, where the number
198 represents a new type which is about to be defined. The type definition
199 may refer to other types by number, and those type numbers may be
200 followed by @samp{=} and nested definitions.
201
202 In a type definition, if the character that follows the equals sign is
203 non-numeric then it is a @var{type_descriptor}, and tells what kind of
204 type is about to be defined. Any other values following the
205 @var{type_descriptor} vary, depending on the @var{type_descriptor}. If
206 a number follows the @samp{=} then the number is a @var{type_reference}.
207 This is described more thoroughly in the section on types. @xref{Type
208 Descriptors,,Table D: Type Descriptors}, for a list of
209 @var{type_descriptor} values.
210
211 All this can make the @code{"@var{string}"} field quite long. All
212 versions of GDB, and some versions of DBX, can handle arbitrarily long
213 strings. But many versions of DBX cretinously limit the strings to
214 about 80 characters, so compilers which must work with such DBX's need
215 to split the @code{.stabs} directive into several @code{.stabs}
216 directives. Each stab duplicates exactly all but the
217 @code{"@var{string}"} field. The @code{"@var{string}"} field of the
218 every stab except the last is marked as continued with a
219 double-backslash at the end. Removing the backslashes and concatenating
220 the @code{"@var{string}"} fields of each stab produces the original,
221 long string.
222
223 @node C example
224 @section A simple example in C source
225
226 To get the flavor of how stabs describe source information for a C
227 program, let's look at the simple program:
228
229 @example
230 main()
231 @{
232 printf("Hello world");
233 @}
234 @end example
235
236 When compiled with @samp{-g}, the program above yields the following
237 @file{.s} file. Line numbers have been added to make it easier to refer
238 to parts of the @file{.s} file in the description of the stabs that
239 follows.
240
241 @node Assembly code
242 @section The simple example at the assembly level
243
244 @example
245 1 gcc2_compiled.:
246 2 .stabs "/cygint/s1/users/jcm/play/",100,0,0,Ltext0
247 3 .stabs "hello.c",100,0,0,Ltext0
248 4 .text
249 5 Ltext0:
250 6 .stabs "int:t1=r1;-2147483648;2147483647;",128,0,0,0
251 7 .stabs "char:t2=r2;0;127;",128,0,0,0
252 8 .stabs "long int:t3=r1;-2147483648;2147483647;",128,0,0,0
253 9 .stabs "unsigned int:t4=r1;0;-1;",128,0,0,0
254 10 .stabs "long unsigned int:t5=r1;0;-1;",128,0,0,0
255 11 .stabs "short int:t6=r1;-32768;32767;",128,0,0,0
256 12 .stabs "long long int:t7=r1;0;-1;",128,0,0,0
257 13 .stabs "short unsigned int:t8=r1;0;65535;",128,0,0,0
258 14 .stabs "long long unsigned int:t9=r1;0;-1;",128,0,0,0
259 15 .stabs "signed char:t10=r1;-128;127;",128,0,0,0
260 16 .stabs "unsigned char:t11=r1;0;255;",128,0,0,0
261 17 .stabs "float:t12=r1;4;0;",128,0,0,0
262 18 .stabs "double:t13=r1;8;0;",128,0,0,0
263 19 .stabs "long double:t14=r1;8;0;",128,0,0,0
264 20 .stabs "void:t15=15",128,0,0,0
265 21 .align 4
266 22 LC0:
267 23 .ascii "Hello, world!\12\0"
268 24 .align 4
269 25 .global _main
270 26 .proc 1
271 27 _main:
272 28 .stabn 68,0,4,LM1
273 29 LM1:
274 30 !#PROLOGUE# 0
275 31 save %sp,-136,%sp
276 32 !#PROLOGUE# 1
277 33 call ___main,0
278 34 nop
279 35 .stabn 68,0,5,LM2
280 36 LM2:
281 37 LBB2:
282 38 sethi %hi(LC0),%o1
283 39 or %o1,%lo(LC0),%o0
284 40 call _printf,0
285 41 nop
286 42 .stabn 68,0,6,LM3
287 43 LM3:
288 44 LBE2:
289 45 .stabn 68,0,6,LM4
290 46 LM4:
291 47 L1:
292 48 ret
293 49 restore
294 50 .stabs "main:F1",36,0,0,_main
295 51 .stabn 192,0,0,LBB2
296 52 .stabn 224,0,0,LBE2
297 @end example
298
299 This simple ``hello world'' example demonstrates several of the stab
300 types used to describe C language source files.
301
302 @node Program structure
303 @chapter Encoding for the structure of the program
304
305 @menu
306 * Source file:: The path and name of the source file
307 * Line numbers::
308 * Procedures::
309 * Block Structure::
310 @end menu
311
312 @node Source file
313 @section The path and name of the source file
314
315 @table @strong
316 @item Directive:
317 @code{.stabs}
318 @item Type:
319 @code{N_SO}
320 @end table
321
322 The first stabs in the .s file contain the name and path of the source
323 file that was compiled to produce the .s file. This information is
324 contained in two records of stab type N_SO (100).
325
326 @example
327 .stabs "path_name", N_SO, NIL, NIL, Code_address_of_program_start
328 .stabs "file_name:", N_SO, NIL, NIL, Code_address_of_program_start
329 @end example
330
331 @example
332 2 .stabs "/cygint/s1/users/jcm/play/",100,0,0,Ltext0
333 3 .stabs "hello.c",100,0,0,Ltext0
334 4 .text
335 5 Ltext0:
336 @end example
337
338 @node Line numbers
339 @section Line Numbers
340
341 @table @strong
342 @item Directive:
343 @code{.stabn}
344 @item Type:
345 @code{N_SLINE}
346 @end table
347
348 The start of source lines is represented by the @code{N_SLINE} (68) stab
349 type.
350
351 @example
352 .stabn N_SLINE, NIL, @var{line}, @var{address}
353 @end example
354
355 @var{line} is a source line number; @var{address} represents the code
356 address for the start of that source line.
357
358 @example
359 27 _main:
360 28 .stabn 68,0,4,LM1
361 29 LM1:
362 30 !#PROLOGUE# 0
363 @end example
364
365 @node Procedures
366 @section Procedures
367
368 @table @strong
369 @item Directive:
370 @code{.stabs}
371 @item Type:
372 @code{N_FUN}
373 @item Symbol Descriptors:
374 @code{f} (local), @code{F} (global)
375 @end table
376
377 Procedures are described by the @code{N_FUN} stab type. The symbol
378 descriptor for a procedure is @samp{F} if the procedure is globally
379 scoped and @samp{f} if the procedure is static (locally scoped).
380
381 The @code{N_FUN} stab representing a procedure is located immediately
382 following the code of the procedure. The @code{N_FUN} stab is in turn
383 directly followed by a group of other stabs describing elements of the
384 procedure. These other stabs describe the procedure's parameters, its
385 block local variables and its block structure.
386
387 @example
388 48 ret
389 49 restore
390 @end example
391
392 The @code{.stabs} entry after this code fragment shows the @var{name} of
393 the procedure (@code{main}); the type descriptor @var{desc} (@code{F},
394 for a global procedure); a reference to the predefined type @code{int}
395 for the return type; and the starting @var{address} of the procedure.
396
397 Here is an exploded summary (with whitespace introduced for clarity),
398 followed by line 50 of our sample assembly output, which has this form:
399
400 @example
401 .stabs "@var{name}:
402 @var{desc} @r{(global proc @samp{F})}
403 @var{return_type_ref} @r{(int)}
404 ",N_FUN, NIL, NIL,
405 @var{address}
406 @end example
407
408 @example
409 50 .stabs "main:F1",36,0,0,_main
410 @end example
411
412 @node Block Structure
413 @section Block Structure
414
415 @table @strong
416 @item Directive:
417 @code{.stabn}
418 @item Types:
419 @code{N_LBRAC}, @code{N_RBRAC}
420 @end table
421
422 The program's block structure is represented by the @code{N_LBRAC} (left
423 brace) and the @code{N_RBRAC} (right brace) stab types. The following code
424 range, which is the body of @code{main}, is labeled with @samp{LBB2:} at the
425 beginning and @samp{LBE2:} at the end.
426
427 @example
428 37 LBB2:
429 38 sethi %hi(LC0),%o1
430 39 or %o1,%lo(LC0),%o0
431 40 call _printf,0
432 41 nop
433 42 .stabn 68,0,6,LM3
434 43 LM3:
435 44 LBE2:
436 @end example
437
438 The @code{N_LBRAC} and @code{N_RBRAC} stabs that describe the block
439 scope of the procedure are located after the @code{N_FUNC} stab that
440 represents the procedure itself. The @code{N_LBRAC} uses the
441 @code{LBB2} label as the code address in its value field, and the
442 @code{N_RBRAC} uses @code{LBE2}.
443
444 @example
445 50 .stabs "main:F1",36,0,0,_main
446 @end example
447
448 @example
449 .stabn N_LBRAC, NIL, NIL, @var{left-brace-address}
450 .stabn N_RBRAC, NIL, NIL, @var{right-brace-address}
451 @end example
452
453 @example
454 51 .stabn 192,0,0,LBB2
455 52 .stabn 224,0,0,LBE2
456 @end example
457
458 @node Simple types
459 @chapter Simple types
460
461 @menu
462 * Basic types:: Basic type definitions
463 * Range types:: Range types defined by min and max value
464 * Float "range" types:: Range type defined by size in bytes
465 @end menu
466
467 @node Basic types
468 @section Basic type definitions
469
470 @table @strong
471 @item Directive:
472 @code{.stabs}
473 @item Type:
474 @code{N_LSYM}
475 @item Symbol Descriptor:
476 @code{t}
477 @end table
478
479 The basic types for the language are described using the @code{N_LSYM} stab
480 type. They are boilerplate and are emited by the compiler for each
481 compilation unit. Basic type definitions are not always a complete
482 description of the type and are sometimes circular. The debugger
483 recognizes the type anyway, and knows how to read bits as that type.
484
485 Each language and compiler defines a slightly different set of basic
486 types. In this example we are looking at the basic types for C emited
487 by the GNU compiler targeting the Sun4. Here the basic types are
488 mostly defined as range types.
489
490
491 @node Range types
492 @section Range types defined by min and max value
493
494 @table @strong
495 @item Type Descriptor:
496 @code{r}
497 @end table
498
499 When defining a range type, if the number after the first semicolon is
500 smaller than the number after the second one, then the two numbers
501 represent the smallest and the largest values in the range.
502
503 @example
504 4 .text
505 5 Ltext0:
506
507 .stabs "@var{name}:
508 @var{descriptor} @r{(type)}
509 @var{type-def}=
510 @var{type-desc}
511 @var{type-ref};
512 @var{low-bound};
513 @var{high-bound};
514 ",
515 N_LSYM, NIL, NIL, NIL
516
517 6 .stabs "int:t1=r1;-2147483648;2147483647;",128,0,0,0
518 7 .stabs "char:t2=r2;0;127;",128,0,0,0
519 @end example
520
521 Here the integer type (@code{1}) is defined as a range of the integer
522 type (@code{1}). Likewise @code{char} is a range of @code{char}. This
523 part of the definition is circular, but at least the high and low bound
524 values of the range hold more information about the type.
525
526 Here short unsigned int is defined as type number 8 and described as a
527 range of type @code{int}, with a minimum value of 0 and a maximum of 65535.
528
529 @example
530 13 .stabs "short unsigned int:t8=r1;0;65535;",128,0,0,0
531 @end example
532
533 @node Float "range" types
534 @section Range type defined by size in bytes
535
536 @table @strong
537 @item Type Descriptor:
538 @code{r}
539 @end table
540
541 In a range definition, if the first number after the semicolon is
542 positive and the second is zero, then the type being defined is a
543 floating point type, and the number after the first semicolon is the
544 number of bytes needed to represent the type. Note that this does not
545 provide a way to distinguish 8-byte real floating point types from
546 8-byte complex floating point types.
547
548 @example
549 .stabs "@var{name}:
550 @var{desc}
551 @var{type-def}=
552 @var{type-desc}
553 @var{type-ref};
554 @var{bit-count};
555 0;
556 ",
557 N_LSYM, NIL, NIL, NIL
558
559 17 .stabs "float:t12=r1;4;0;",128,0,0,0
560 18 .stabs "double:t13=r1;8;0;",128,0,0,0
561 19 .stabs "long double:t14=r1;8;0;",128,0,0,0
562 @end example
563
564 Cosmically enough, the @code{void} type is defined directly in terms of
565 itself.
566
567 @example
568 .stabs "@var{name}:
569 @var{symbol-desc}
570 @var{type-def}=
571 @var{type-ref}
572 ",N_LSYM,NIL,NIL,NIL
573
574 20 .stabs "void:t15=15",128,0,0,0
575 @end example
576
577
578 @node Example
579 @chapter A Comprehensive Example in C
580
581 Now we'll examine a second program, @code{example2}, which builds on the
582 first example to introduce the rest of the stab types, symbol
583 descriptors, and type descriptors used in C.
584 @xref{Example2.c} for the complete @file{.c} source,
585 and @pxref{Example2.s} for the @file{.s} assembly code.
586 This description includes parts of those files.
587
588 @section Flow of control and nested scopes
589
590 @table @strong
591 @item Directive:
592 @code{.stabn}
593 @item Types:
594 @code{N_SLINE}, @code{N_LBRAC}, @code{N_RBRAC} (cont.)
595 @end table
596
597 Consider the body of @code{main}, from @file{example2.c}. It shows more
598 about how @code{N_SLINE}, @code{N_RBRAC}, and @code{N_LBRAC} stabs are used.
599
600 @example
601 20 @{
602 21 static float s_flap;
603 22 int times;
604 23 for (times=0; times < s_g_repeat; times++)@{
605 24 int inner;
606 25 printf ("Hello world\n");
607 26 @}
608 27 @};
609 @end example
610
611 Here we have a single source line, the @samp{for} line, that generates
612 non-linear flow of control, and non-contiguous code. In this case, an
613 @code{N_SLINE} stab with the same line number proceeds each block of
614 non-contiguous code generated from the same source line.
615
616 The example also shows nested scopes. The @code{N_LBRAC} and
617 @code{N_LBRAC} stabs that describe block structure are nested in the
618 same order as the corresponding code blocks, those of the for loop
619 inside those for the body of main.
620
621 @noindent
622 This is the label for the @code{N_LBRAC} (left brace) stab marking the
623 start of @code{main}.
624
625 @example
626 57 LBB2:
627 @end example
628
629 @noindent
630 In the first code range for C source line 23, the @code{for} loop
631 initialize and test, @code{N_SLINE} (68) records the line number:
632
633 @example
634 .stabn N_SLINE, NIL,
635 @var{line},
636 @var{address}
637
638 58 .stabn 68,0,23,LM2
639 59 LM2:
640 60 st %g0,[%fp-20]
641 61 L2:
642 62 sethi %hi(_s_g_repeat),%o0
643 63 ld [%fp-20],%o1
644 64 ld [%o0+%lo(_s_g_repeat)],%o0
645 65 cmp %o1,%o0
646 66 bge L3
647 67 nop
648
649 @exdent label for the @code{N_LBRAC} (start block) marking the start of @code{for} loop
650
651 68 LBB3:
652 69 .stabn 68,0,25,LM3
653 70 LM3:
654 71 sethi %hi(LC0),%o1
655 72 or %o1,%lo(LC0),%o0
656 73 call _printf,0
657 74 nop
658 75 .stabn 68,0,26,LM4
659 76 LM4:
660
661 @exdent label for the @code{N_RBRAC} (end block) stab marking the end of the @code{for} loop
662
663 77 LBE3:
664 @end example
665
666 @noindent
667 Now we come to the second code range for source line 23, the @code{for}
668 loop increment and return. Once again, @code{N_SLINE} (68) records the
669 source line number:
670
671 @example
672 .stabn, N_SLINE, NIL,
673 @var{line},
674 @var{address}
675
676 78 .stabn 68,0,23,LM5
677 79 LM5:
678 80 L4:
679 81 ld [%fp-20],%o0
680 82 add %o0,1,%o1
681 83 st %o1,[%fp-20]
682 84 b,a L2
683 85 L3:
684 86 .stabn 68,0,27,LM6
685 87 LM6:
686
687 @exdent label for the @code{N_RBRAC} (end block) stab marking the end of the @code{for} loop
688
689 88 LBE2:
690 89 .stabn 68,0,27,LM7
691 90 LM7:
692 91 L1:
693 92 ret
694 93 restore
695 94 .stabs "main:F1",36,0,0,_main
696 95 .stabs "argc:p1",160,0,0,68
697 96 .stabs "argv:p20=*21=*2",160,0,0,72
698 97 .stabs "s_flap:V12",40,0,0,_s_flap.0
699 98 .stabs "times:1",128,0,0,-20
700 @end example
701
702 @noindent
703 Here is an illustration of stabs describing nested scopes. The scope
704 nesting is reflected in the nested bracketing stabs (@code{N_LBRAC},
705 192, appears here).
706
707 @example
708 .stabn N_LBRAC,NIL,NIL,
709 @var{block-start-address}
710
711 99 .stabn 192,0,0,LBB2 ## begin proc label
712 100 .stabs "inner:1",128,0,0,-24
713 101 .stabn 192,0,0,LBB3 ## begin for label
714 @end example
715
716 @noindent
717 @code{N_RBRAC} (224), ``right brace'' ends a lexical block (scope).
718
719 @example
720 .stabn N_RBRAC,NIL,NIL,
721 @var{block-end-address}
722
723 102 .stabn 224,0,0,LBE3 ## end for label
724 103 .stabn 224,0,0,LBE2 ## end proc label
725 @end example
726
727 @node Variables
728 @chapter Variables
729
730 @menu
731 * Automatic variables:: locally scoped
732 * Global Variables::
733 * Register variables::
734 * Initialized statics::
735 * Un-initialized statics::
736 * Parameters::
737 @end menu
738
739 @node Automatic variables
740 @section Locally scoped automatic variables
741
742 @table @strong
743 @item Directive:
744 @code{.stabs}
745 @item Type:
746 @code{N_LSYM}
747 @item Symbol Descriptor:
748 none
749 @end table
750
751
752 In addition to describing types, the @code{N_LSYM} stab type also
753 describes locally scoped automatic variables. Refer again to the body
754 of @code{main} in @file{example2.c}. It allocates two automatic
755 variables: @samp{times} is scoped to the body of @code{main}, and
756 @samp{inner} is scoped to the body of the @code{for} loop.
757 @samp{s_flap} is locally scoped but not automatic, and will be discussed
758 later.
759
760 @example
761 20 @{
762 21 static float s_flap;
763 22 int times;
764 23 for (times=0; times < s_g_repeat; times++)@{
765 24 int inner;
766 25 printf ("Hello world\n");
767 26 @}
768 27 @};
769 @end example
770
771 The @code{N_LSYM} stab for an automatic variable is located just before the
772 @code{N_LBRAC} stab describing the open brace of the block to which it is
773 scoped.
774
775 @example
776 @exdent @code{N_LSYM} (128): automatic variable, scoped locally to @code{main}
777
778 .stabs "@var{name}:
779 @var{type-ref}",
780 N_LSYM, NIL, NIL,
781 @var{frame-pointer-offset}
782
783 98 .stabs "times:1",128,0,0,-20
784 99 .stabn 192,0,0,LBB2 ## begin `main' N_LBRAC
785
786 @exdent @code{N_LSYM} (128): automatic variable, scoped locally to the @code{for} loop
787
788 .stabs "@var{name}:
789 @var{type-ref}",
790 N_LSYM, NIL, NIL,
791 @var{frame-pointer-offset}
792
793 100 .stabs "inner:1",128,0,0,-24
794 101 .stabn 192,0,0,LBB3 ## begin `for' loop N_LBRAC
795 @end example
796
797 Since the character in the string field following the colon is not a
798 letter, there is no symbol descriptor. This means that the stab
799 describes a local variable, and that the number after the colon is a
800 type reference. In this case it a a reference to the basic type @code{int}.
801 Notice also that the frame pointer offset is negative number for
802 automatic variables.
803
804
805 @node Global Variables
806 @section Global Variables
807
808 @table @strong
809 @item Directive:
810 @code{.stabs}
811 @item Type:
812 @code{N_GSYM}
813 @item Symbol Descriptor:
814 @code{G}
815 @end table
816
817 Global variables are represented by the @code{N_GSYM} stab type. The symbol
818 descriptor, following the colon in the string field, is @samp{G}. Following
819 the @samp{G} is a type reference or type definition. In this example it is a
820 type reference to the basic C type, @code{char}. The first source line in
821 @file{example2.c},
822
823 @example
824 1 char g_foo = 'c';
825 @end example
826
827 @noindent
828 yields the following stab. The stab immediately precedes the code that
829 allocates storage for the variable it describes.
830
831 @example
832 @exdent @code{N_GSYM} (32): global symbol
833
834 .stabs "@var{name}:
835 @var{descriptor}
836 @var{type-ref}",
837 N_GSYM, NIL, NIL, NIL
838
839 21 .stabs "g_foo:G2",32,0,0,0
840 22 .global _g_foo
841 23 .data
842 24 _g_foo:
843 25 .byte 99
844 @end example
845
846 The address of the variable represented by the @code{N_GSYM} is not contained
847 in the @code{N_GSYM} stab. The debugger gets this information from the
848 external symbol for the global variable.
849
850 @node Register variables
851 @section Global register variables
852
853 @table @strong
854 @item Directive:
855 @code{.stabs}
856 @item Type:
857 @code{N_RSYM}
858 @item Symbol Descriptor:
859 @code{r}
860 @end table
861
862 The following source line defines a global variable, @code{g_bar}, which is
863 explicitly allocated in global register @code{%g5}.
864
865 @example
866 2 register int g_bar asm ("%g5");
867 @end example
868
869 Register variables have their own stab type, @code{N_RSYM}, and their own
870 symbol descriptor, @code{r}. The stab's value field contains the number of
871 the register where the variable data will be stored. Since the
872 variable was not initialized in this compilation unit, the stab is
873 emited at the end of the object file, with the stabs for other
874 uninitialized globals (@code{bcc}).
875
876 @example
877 @exdent @code{N_RSYM} (64): register variable
878
879 .stabs "@var{name}:
880 @var{descriptor}
881 @var{type-ref}",
882 N_RSYM, NIL, NIL,
883 @var{register}
884
885 133 .stabs "g_bar:r1",64,0,0,5
886 @end example
887
888
889 @node Initialized statics
890 @section Initialized static variables
891
892 @table @strong
893 @item Directive:
894 @code{.stabs}
895 @item Type:
896 @code{N_STSYM}
897 @item Symbol Descriptors:
898 @code{S} (file scope), @code{V} (procedure scope)
899 @end table
900
901 Initialized static variables are represented by the @code{N_STSYM} stab
902 type. The symbol descriptor part of the string field shows if the
903 variable is file scope static (@samp{S}) or procedure scope static
904 (@samp{V}). The source line
905
906 @example
907 3 static int s_g_repeat = 2;
908 @end example
909
910 @noindent
911 yields the following code. The stab is located immediately preceding
912 the storage for the variable it represents. Since the variable in
913 this example is file scope static the symbol descriptor is @samp{S}.
914
915 @example
916 @exdent @code{N_STSYM} (38): initialized static variable (data seg w/internal linkage)
917
918 .stabs "@var{name}:
919 @var{descriptor}
920 @var{type-ref}",
921 N_STSYM,NIL,NIL,
922 @var{address}
923
924 26 .stabs "s_g_repeat:S1",38,0,0,_s_g_repeat
925 27 .align 4
926 28 _s_g_repeat:
927 29 .word 2
928 @end example
929
930
931 @node Un-initialized statics
932 @section Un-initialized static variables
933
934 @table @strong
935 @item Directive:
936 @code{.stabs}
937 @item Type:
938 @code{N_LCSYM}
939 @item Symbol Descriptors:
940 @code{S} (file scope), @code{V} (procedure scope)
941 @end table
942
943 Un-initialized static variables are represented by the @code{N_LCSYM}
944 stab type. The symbol descriptor part of the string shows if the
945 variable is file scope static (@samp{S}) or procedure scope static
946 (@samp{V}). In this example it is procedure scope static. The source
947 line allocating @code{s_flap} immediately follows the open brace for the
948 procedure @code{main}.
949
950 @example
951 20 @{
952 21 static float s_flap;
953 @end example
954
955 The code that reserves storage for the variable @code{s_flap} precedes the
956 body of body of @code{main}.
957
958 @example
959 39 .reserve _s_flap.0,4,"bss",4
960 @end example
961
962 But since @code{s_flap} is scoped locally to @code{main}, its stab is
963 located with the other stabs representing symbols local to @code{main}.
964 The stab for @code{s_flap} is located just before the @code{N_LBRAC} for
965 @code{main}.
966
967 @example
968 @exdent @code{N_LCSYM} (40): uninitialized static var (BSS seg w/internal linkage)
969
970 .stabs "@var{name}:
971 @var{descriptor}
972 @var{type-ref}",
973 N_LCSYM, NIL, NIL,
974 @var{address}
975
976 97 .stabs "s_flap:V12",40,0,0,_s_flap.0
977 98 .stabs "times:1",128,0,0,-20
978 99 .stabn 192,0,0,LBB2 # N_LBRAC for main.
979 @end example
980
981 @c ............................................................
982
983 @node Parameters
984 @section Parameters
985
986 The symbol descriptor @samp{p} is used to refer to parameters which are
987 in the arglist. Symbols have symbol type @samp{N_PSYM}. The value of
988 the symbol is the offset relative to the argument list.
989
990 If the parameter is passed in a register, then the traditional way to do
991 this is to provide two symbols for each argument:
992
993 @example
994 .stabs "arg:p1" . . . ; N_PSYM
995 .stabs "arg:r1" . . . ; N_RSYM
996 @end example
997
998 Debuggers are expected to use the second one to find the value, and the
999 first one to know that it is an argument.
1000
1001 Because this is kind of ugly, some compilers use symbol descriptor
1002 @samp{P} or @samp{R} to indicate an argument which is in a register.
1003 The symbol value is the register number. @samp{P} and @samp{R} mean the
1004 same thing, the difference is that @samp{P} is a GNU invention and
1005 @samp{R} is an IBM (xcoff) invention. As of version 4.9, GDB should
1006 handle either one. Symbol type @samp{C_RPSYM} is used with @samp{R} and
1007 @samp{N_RSYM} is used with @samp{P}.
1008
1009 There is at least one case where GCC uses a @samp{p}/@samp{r} pair
1010 rather than @samp{P}; this is where the argument is passed in the
1011 argument list and then loaded into a register.
1012
1013 There is another case similar to an argument in a register, which is an
1014 argument which is actually stored as a local variable. Sometimes this
1015 happens when the argument was passed in a register and then the compiler
1016 stores it as a local variable. If possible, the compiler should claim
1017 that it's in a register, but this isn't always done. Some compilers use
1018 the pair of symbols approach described above ("arg:p" followed by
1019 "arg:"); this includes gcc1 (not gcc2) on the sparc when passing a small
1020 structure and gcc2 when the argument type is float and it is passed as a
1021 double and converted to float by the prologue (in the latter case the
1022 type of the "arg:p" symbol is double and the type of the "arg:" symbol
1023 is float). GCC, at least on the 960, uses a single @samp{p} symbol
1024 descriptor for an argument which is stored as a local variable but uses
1025 @samp{N_LSYM} instead of @samp{N_PSYM}. In this case the value of the
1026 symbol is an offset relative to the local variables for that function,
1027 not relative to the arguments (on some machines those are the same
1028 thing, but not on all).
1029
1030 The following are said to go with @samp{N_PSYM}:
1031
1032 @example
1033 "name" -> "param_name:#type"
1034 # -> p (value parameter)
1035 -> i (value parameter by reference, indirect access)
1036 -> v (variable parameter by reference)
1037 -> C (read-only parameter, conformant array bound)
1038 -> x (conformant array value parameter)
1039 -> pP (<<??>>)
1040 -> pF (<<??>>)
1041 -> X (function result variable)
1042 -> b (based variable)
1043
1044 value -> offset from the argument pointer (positive).
1045 @end example
1046
1047 As a simple example, the code
1048
1049 @example
1050 main (argc, argv)
1051 int argc;
1052 char **argv;
1053 @{
1054 @end example
1055
1056 produces the stabs
1057
1058 @example
1059 .stabs "main:F1",36,0,0,_main ; 36 is N_FUN
1060 .stabs "argc:p1",160,0,0,68 ; 160 is N_PSYM
1061 .stabs "argv:p20=*21=*2",160,0,0,72
1062 @end example
1063
1064 The type definition of argv is interesting because it contains several
1065 type definitions. Type 21 is pointer to type 2 (char) and argv (type 20) is
1066 pointer to type 21.
1067
1068 @node Aggregate Types
1069 @chapter Aggregate Types
1070
1071 Now let's look at some variable definitions involving complex types.
1072 This involves understanding better how types are described. In the
1073 examples so far types have been described as references to previously
1074 defined types or defined in terms of subranges of or pointers to
1075 previously defined types. The section that follows will talk about
1076 the various other type descriptors that may follow the = sign in a
1077 type definition.
1078
1079 @menu
1080 * Arrays::
1081 * Enumerations::
1082 * Structure tags::
1083 * Typedefs::
1084 * Unions::
1085 * Function types::
1086 @end menu
1087
1088 @node Arrays
1089 @section Array types
1090
1091 @table @strong
1092 @item Directive:
1093 @code{.stabs}
1094 @item Types:
1095 @code{N_GSYM}, @code{N_LSYM}
1096 @item Symbol Descriptor:
1097 @code{T}
1098 @item Type Descriptor:
1099 @code{a}
1100 @end table
1101
1102 As an example of an array type consider the global variable below.
1103
1104 @example
1105 15 char char_vec[3] = @{'a','b','c'@};
1106 @end example
1107
1108 Since the array is a global variable, it is described by the N_GSYM
1109 stab type. The symbol descriptor G, following the colon in stab's
1110 string field, also says the array is a global variable. Following the
1111 G is a definition for type (19) as shown by the equals sign after the
1112 type number.
1113
1114 After the equals sign is a type descriptor, a, which says that the type
1115 being defined is an array. Following the type descriptor for an array
1116 is the type of the index, a semicolon, and the type of the array elements.
1117
1118 The type of the index is often a range type, expressed as the letter r
1119 and some parameters. It defines the size of the array. In in the
1120 example below, the range @code{r1;0;2;} defines an index type which is
1121 a subrange of type 1 (integer), with a lower bound of 0 and an upper
1122 bound of 2. This defines the valid range of subscripts of a
1123 three-element C array.
1124
1125 The array definition above generates the assembly language that
1126 follows.
1127
1128 @example
1129 @exdent <32> N_GSYM - global variable
1130 @exdent .stabs "name:sym_desc(global)type_def(19)=type_desc(array)
1131 @exdent index_type_ref(range of int from 0 to 2);element_type_ref(char)";
1132 @exdent N_GSYM, NIL, NIL, NIL
1133
1134 32 .stabs "char_vec:G19=ar1;0;2;2",32,0,0,0
1135 33 .global _char_vec
1136 34 .align 4
1137 35 _char_vec:
1138 36 .byte 97
1139 37 .byte 98
1140 38 .byte 99
1141 @end example
1142
1143 @node Enumerations
1144 @section Enumerations
1145
1146 @table @strong
1147 @item Directive:
1148 @code{.stabs}
1149 @item Type:
1150 @code{N_LSYM}
1151 @item Symbol Descriptor:
1152 @code{T}
1153 @item Type Descriptor:
1154 @code{e}
1155 @end table
1156
1157 The source line below declares an enumeration type. It is defined at
1158 file scope between the bodies of main and s_proc in example2.c.
1159 Because the N_LSYM is located after the N_RBRAC that marks the end of
1160 the previous procedure's block scope, and before the N_FUN that marks
1161 the beginning of the next procedure's block scope, the N_LSYM does not
1162 describe a block local symbol, but a file local one. The source line:
1163
1164 @example
1165 29 enum e_places @{first,second=3,last@};
1166 @end example
1167
1168 @noindent
1169 generates the following stab, located just after the N_RBRAC (close
1170 brace stab) for main. The type definition is in an N_LSYM stab
1171 because type definitions are file scope not global scope.
1172
1173 @display
1174 <128> N_LSYM - local symbol
1175 .stab "name:sym_dec(type)type_def(22)=sym_desc(enum)
1176 enum_name:value(0),enum_name:value(3),enum_name:value(4),;",
1177 N_LSYM, NIL, NIL, NIL
1178 @end display
1179
1180 @example
1181 104 .stabs "e_places:T22=efirst:0,second:3,last:4,;",128,0,0,0
1182 @end example
1183
1184 The symbol descriptor (T) says that the stab describes a structure,
1185 enumeration, or type tag. The type descriptor e, following the 22= of
1186 the type definition narrows it down to an enumeration type. Following
1187 the e is a list of the elements of the enumeration. The format is
1188 name:value,. The list of elements ends with a ;.
1189
1190 @node Structure tags
1191 @section Structure Tags
1192
1193 @table @strong
1194 @item Directive:
1195 @code{.stabs}
1196 @item Type:
1197 @code{N_LSYM}
1198 @item Symbol Descriptor:
1199 @code{T}
1200 @item Type Descriptor:
1201 @code{s}
1202 @end table
1203
1204 The following source code declares a structure tag and defines an
1205 instance of the structure in global scope. Then a typedef equates the
1206 structure tag with a new type. A seperate stab is generated for the
1207 structure tag, the structure typedef, and the structure instance. The
1208 stabs for the tag and the typedef are emited when the definitions are
1209 encountered. Since the structure elements are not initialized, the
1210 stab and code for the structure variable itself is located at the end
1211 of the program in .common.
1212
1213 @example
1214 6 struct s_tag @{
1215 7 int s_int;
1216 8 float s_float;
1217 9 char s_char_vec[8];
1218 10 struct s_tag* s_next;
1219 11 @} g_an_s;
1220 12
1221 13 typedef struct s_tag s_typedef;
1222 @end example
1223
1224 The structure tag is an N_LSYM stab type because, like the enum, the
1225 symbol is file scope. Like the enum, the symbol descriptor is T, for
1226 enumeration, struct or tag type. The symbol descriptor s following
1227 the 16= of the type definition narrows the symbol type to struct.
1228
1229 Following the struct symbol descriptor is the number of bytes the
1230 struct occupies, followed by a description of each structure element.
1231 The structure element descriptions are of the form name:type, bit
1232 offset from the start of the struct, and number of bits in the
1233 element.
1234
1235
1236 @example
1237 <128> N_LSYM - type definition
1238 .stabs "name:sym_desc(struct tag) Type_def(16)=type_desc(struct type)
1239 struct_bytes
1240 elem_name:type_ref(int),bit_offset,field_bits;
1241 elem_name:type_ref(float),bit_offset,field_bits;
1242 elem_name:type_def(17)=type_desc(array)
1243 index_type(range of int from 0 to 7);
1244 element_type(char),bit_offset,field_bits;;",
1245 N_LSYM,NIL,NIL,NIL
1246
1247 30 .stabs "s_tag:T16=s20s_int:1,0,32;s_float:12,32,32;
1248 s_char_vec:17=ar1;0;7;2,64,64;s_next:18=*16,128,32;;",128,0,0,0
1249 @end example
1250
1251 In this example, two of the structure elements are previously defined
1252 types. For these, the type following the name: part of the element
1253 description is a simple type reference. The other two structure
1254 elements are new types. In this case there is a type definition
1255 embedded after the name:. The type definition for the array element
1256 looks just like a type definition for a standalone array. The s_next
1257 field is a pointer to the same kind of structure that the field is an
1258 element of. So the definition of structure type 16 contains an type
1259 definition for an element which is a pointer to type 16.
1260
1261 @node Typedefs
1262 @section Typedefs
1263
1264 @table @strong
1265 @item Directive:
1266 @code{.stabs}
1267 @item Type:
1268 @code{N_LSYM}
1269 @item Symbol Descriptor:
1270 @code{t}
1271 @end table
1272
1273 Here is the stab for the typedef equating the structure tag with a
1274 type.
1275
1276 @display
1277 <128> N_LSYM - type definition
1278 .stabs "name:sym_desc(type name)type_ref(struct_tag)",N_LSYM,NIL,NIL,NIL
1279 @end display
1280
1281 @example
1282 31 .stabs "s_typedef:t16",128,0,0,0
1283 @end example
1284
1285 And here is the code generated for the structure variable.
1286
1287 @display
1288 <32> N_GSYM - global symbol
1289 .stabs "name:sym_desc(global)type_ref(struct_tag)",N_GSYM,NIL,NIL,NIL
1290 @end display
1291
1292 @example
1293 136 .stabs "g_an_s:G16",32,0,0,0
1294 137 .common _g_an_s,20,"bss"
1295 @end example
1296
1297 Notice that the structure tag has the same type number as the typedef
1298 for the structure tag. It is impossible to distinguish between a
1299 variable of the struct type and one of its typedef by looking at the
1300 debugging information.
1301
1302
1303 @node Unions
1304 @section Unions
1305
1306 @table @strong
1307 @item Directive:
1308 @code{.stabs}
1309 @item Type:
1310 @code{N_LSYM}
1311 @item Symbol Descriptor:
1312 @code{T}
1313 @item Type Descriptor:
1314 @code{u}
1315 @end table
1316
1317 Next let's look at unions. In example2 this union type is declared
1318 locally to a procedure and an instance of the union is defined.
1319
1320 @example
1321 36 union u_tag @{
1322 37 int u_int;
1323 38 float u_float;
1324 39 char* u_char;
1325 40 @} an_u;
1326 @end example
1327
1328 This code generates a stab for the union tag and a stab for the union
1329 variable. Both use the N_LSYM stab type. Since the union variable is
1330 scoped locally to the procedure in which it is defined, its stab is
1331 located immediately preceding the N_LBRAC for the procedure's block
1332 start.
1333
1334 The stab for the union tag, however is located preceding the code for
1335 the procedure in which it is defined. The stab type is N_LSYM. This
1336 would seem to imply that the union type is file scope, like the struct
1337 type s_tag. This is not true. The contents and position of the stab
1338 for u_type do not convey any infomation about its procedure local
1339 scope.
1340
1341 @display
1342 <128> N_LSYM - type
1343 .stabs "name:sym_desc(union tag)type_def(22)=type_desc(union)
1344 byte_size(4)
1345 elem_name:type_ref(int),bit_offset(0),bit_size(32);
1346 elem_name:type_ref(float),bit_offset(0),bit_size(32);
1347 elem_name:type_ref(ptr to char),bit_offset(0),bit_size(32);;"
1348 N_LSYM, NIL, NIL, NIL
1349 @end display
1350
1351 @smallexample
1352 105 .stabs "u_tag:T23=u4u_int:1,0,32;u_float:12,0,32;u_char:21,0,32;;",
1353 128,0,0,0
1354 @end smallexample
1355
1356 The symbol descriptor, T, following the name: means that the stab
1357 describes an enumeration, struct or type tag. The type descriptor u,
1358 following the 23= of the type definition, narrows it down to a union
1359 type definition. Following the u is the number of bytes in the union.
1360 After that is a list of union element descriptions. Their format is
1361 name:type, bit offset into the union, and number of bytes for the
1362 element;.
1363
1364 The stab for the union variable follows. Notice that the frame
1365 pointer offset for local variables is negative.
1366
1367 @display
1368 <128> N_LSYM - local variable (with no symbol descriptor)
1369 .stabs "name:type_ref(u_tag)", N_LSYM, NIL, NIL, frame_ptr_offset
1370 @end display
1371
1372 @example
1373 130 .stabs "an_u:23",128,0,0,-20
1374 @end example
1375
1376 @node Function types
1377 @section Function types
1378
1379 @display
1380 type descriptor f
1381 @end display
1382
1383 The last type descriptor in C which remains to be described is used
1384 for function types. Consider the following source line defining a
1385 global function pointer.
1386
1387 @example
1388 4 int (*g_pf)();
1389 @end example
1390
1391 It generates the following code. Since the variable is not
1392 initialized, the code is located in the common area at the end of the
1393 file.
1394
1395 @display
1396 <32> N_GSYM - global variable
1397 .stabs "name:sym_desc(global)type_def(24)=ptr_to(25)=
1398 type_def(func)type_ref(int)
1399 @end display
1400
1401 @example
1402 134 .stabs "g_pf:G24=*25=f1",32,0,0,0
1403 135 .common _g_pf,4,"bss"
1404 @end example
1405
1406 Since the variable is global, the stab type is N_GSYM and the symbol
1407 descriptor is G. The variable defines a new type, 24, which is a
1408 pointer to another new type, 25, which is defined as a function
1409 returning int.
1410
1411 @node Symbol tables
1412 @chapter Symbol information in symbol tables
1413
1414 This section examines more closely the format of symbol table entries
1415 and how stab assembler directives map to them. It also describes what
1416 transformations the assembler and linker make on data from stabs.
1417
1418 Each time the assembler encounters a stab in its input file it puts
1419 each field of the stab into corresponding fields in a symbol table
1420 entry of its output file. If the stab contains a string field, the
1421 symbol table entry for that stab points to a string table entry
1422 containing the string data from the stab. Assembler labels become
1423 relocatable addresses. Symbol table entries in a.out have the format:
1424
1425 @example
1426 struct internal_nlist @{
1427 unsigned long n_strx; /* index into string table of name */
1428 unsigned char n_type; /* type of symbol */
1429 unsigned char n_other; /* misc info (usually empty) */
1430 unsigned short n_desc; /* description field */
1431 bfd_vma n_value; /* value of symbol */
1432 @};
1433 @end example
1434
1435 For .stabs directives, the n_strx field holds the character offset
1436 from the start of the string table to the string table entry
1437 containing the "string" field. For other classes of stabs (.stabn and
1438 .stabd) this field is null.
1439
1440 Symbol table entries with n_type fields containing a value greater or
1441 equal to 0x20 originated as stabs generated by the compiler (with one
1442 random exception). Those with n_type values less than 0x20 were
1443 placed in the symbol table of the executable by the assembler or the
1444 linker.
1445
1446 The linker concatenates object files and does fixups of externally
1447 defined symbols. You can see the transformations made on stab data by
1448 the assembler and linker by examining the symbol table after each pass
1449 of the build, first the assemble and then the link.
1450
1451 To do this use nm with the -ap options. This dumps the symbol table,
1452 including debugging information, unsorted. For stab entries the
1453 columns are: value, other, desc, type, string. For assembler and
1454 linker symbols, the columns are: value, type, string.
1455
1456 There are a few important things to notice about symbol tables. Where
1457 the value field of a stab contains a frame pointer offset, or a
1458 register number, that value is unchanged by the rest of the build.
1459
1460 Where the value field of a stab contains an assembly language label,
1461 it is transformed by each build step. The assembler turns it into a
1462 relocatable address and the linker turns it into an absolute address.
1463 This source line defines a static variable at file scope:
1464
1465 @example
1466 3 static int s_g_repeat
1467 @end example
1468
1469 @noindent
1470 The following stab describes the symbol.
1471
1472 @example
1473 26 .stabs "s_g_repeat:S1",38,0,0,_s_g_repeat
1474 @end example
1475
1476 @noindent
1477 The assembler transforms the stab into this symbol table entry in the
1478 @file{.o} file. The location is expressed as a data segment offset.
1479
1480 @example
1481 21 00000084 - 00 0000 STSYM s_g_repeat:S1
1482 @end example
1483
1484 @noindent
1485 in the symbol table entry from the executable, the linker has made the
1486 relocatable address absolute.
1487
1488 @example
1489 22 0000e00c - 00 0000 STSYM s_g_repeat:S1
1490 @end example
1491
1492 Stabs for global variables do not contain location information. In
1493 this case the debugger finds location information in the assembler or
1494 linker symbol table entry describing the variable. The source line:
1495
1496 @example
1497 1 char g_foo = 'c';
1498 @end example
1499
1500 @noindent
1501 generates the stab:
1502
1503 @example
1504 21 .stabs "g_foo:G2",32,0,0,0
1505 @end example
1506
1507 The variable is represented by the following two symbol table entries
1508 in the object file. The first one originated as a stab. The second
1509 one is an external symbol. The upper case D signifies that the n_type
1510 field of the symbol table contains 7, N_DATA with local linkage (see
1511 Table B). The value field following the file's line number is empty
1512 for the stab entry. For the linker symbol it contains the
1513 rellocatable address corresponding to the variable.
1514
1515 @example
1516 19 00000000 - 00 0000 GSYM g_foo:G2
1517 20 00000080 D _g_foo
1518 @end example
1519
1520 @noindent
1521 These entries as transformed by the linker. The linker symbol table
1522 entry now holds an absolute address.
1523
1524 @example
1525 21 00000000 - 00 0000 GSYM g_foo:G2
1526 @dots{}
1527 215 0000e008 D _g_foo
1528 @end example
1529
1530 @node GNU Cplusplus stabs
1531 @chapter GNU C++ stabs
1532
1533 @menu
1534 * Basic Cplusplus types::
1535 * Simple classes::
1536 * Class instance::
1537 * Methods:: Method definition
1538 * Protections::
1539 * Method Modifiers:: (const, volatile, const volatile)
1540 * Virtual Methods::
1541 * Inheritence::
1542 * Virtual Base Classes::
1543 * Static Members::
1544 @end menu
1545
1546
1547 @subsection Symbol descriptors added for C++ descriptions:
1548
1549 @display
1550 P - register parameter.
1551 @end display
1552
1553 @subsection type descriptors added for C++ descriptions
1554
1555 @table @code
1556 @item #
1557 method type (two ## if minimal debug)
1558
1559 @item xs
1560 cross-reference
1561 @end table
1562
1563
1564 @node Basic Cplusplus types
1565 @section Basic types for C++
1566
1567 << the examples that follow are based on a01.C >>
1568
1569
1570 C++ adds two more builtin types to the set defined for C. These are
1571 the unknown type and the vtable record type. The unknown type, type
1572 16, is defined in terms of itself like the void type.
1573
1574 The vtable record type, type 17, is defined as a structure type and
1575 then as a structure tag. The structure has four fields, delta, index,
1576 pfn, and delta2. pfn is the function pointer.
1577
1578 << In boilerplate $vtbl_ptr_type, what are the fields delta,
1579 index, and delta2 used for? >>
1580
1581 This basic type is present in all C++ programs even if there are no
1582 virtual methods defined.
1583
1584 @display
1585 .stabs "struct_name:sym_desc(type)type_def(17)=type_desc(struct)struct_bytes(8)
1586 elem_name(delta):type_ref(short int),bit_offset(0),field_bits(16);
1587 elem_name(index):type_ref(short int),bit_offset(16),field_bits(16);
1588 elem_name(pfn):type_def(18)=type_desc(ptr to)type_ref(void),
1589 bit_offset(32),field_bits(32);
1590 elem_name(delta2):type_def(short int);bit_offset(32),field_bits(16);;"
1591 N_LSYM, NIL, NIL
1592 @end display
1593
1594 @smallexample
1595 .stabs "$vtbl_ptr_type:t17=s8
1596 delta:6,0,16;index:6,16,16;pfn:18=*15,32,32;delta2:6,32,16;;"
1597 ,128,0,0,0
1598 @end smallexample
1599
1600 @display
1601 .stabs "name:sym_dec(struct tag)type_ref($vtbl_ptr_type)",N_LSYM,NIL,NIL,NIL
1602 @end display
1603
1604 @example
1605 .stabs "$vtbl_ptr_type:T17",128,0,0,0
1606 @end example
1607
1608 @node Simple classes
1609 @section Simple class definition
1610
1611 The stabs describing C++ language features are an extension of the
1612 stabs describing C. Stabs representing C++ class types elaborate
1613 extensively on the stab format used to describe structure types in C.
1614 Stabs representing class type variables look just like stabs
1615 representing C language variables.
1616
1617 Consider the following very simple class definition.
1618
1619 @example
1620 class baseA @{
1621 public:
1622 int Adat;
1623 int Ameth(int in, char other);
1624 @};
1625 @end example
1626
1627 The class baseA is represented by two stabs. The first stab describes
1628 the class as a structure type. The second stab describes a structure
1629 tag of the class type. Both stabs are of stab type N_LSYM. Since the
1630 stab is not located between an N_FUN and a N_LBRAC stab this indicates
1631 that the class is defined at file scope. If it were, then the N_LSYM
1632 would signify a local variable.
1633
1634 A stab describing a C++ class type is similar in format to a stab
1635 describing a C struct, with each class member shown as a field in the
1636 structure. The part of the struct format describing fields is
1637 expanded to include extra information relevent to C++ class members.
1638 In addition, if the class has multiple base classes or virtual
1639 functions the struct format outside of the field parts is also
1640 augmented.
1641
1642 In this simple example the field part of the C++ class stab
1643 representing member data looks just like the field part of a C struct
1644 stab. The section on protections describes how its format is
1645 sometimes extended for member data.
1646
1647 The field part of a C++ class stab representing a member function
1648 differs substantially from the field part of a C struct stab. It
1649 still begins with `name:' but then goes on to define a new type number
1650 for the member function, describe its return type, its argument types,
1651 its protection level, any qualifiers applied to the method definition,
1652 and whether the method is virtual or not. If the method is virtual
1653 then the method description goes on to give the vtable index of the
1654 method, and the type number of the first base class defining the
1655 method.
1656
1657 When the field name is a method name it is followed by two colons
1658 rather than one. This is followed by a new type definition for the
1659 method. This is a number followed by an equal sign and then the
1660 symbol descriptor `##', indicating a method type. This is followed by
1661 a type reference showing the return type of the method and a
1662 semi-colon.
1663
1664 The format of an overloaded operator method name differs from that
1665 of other methods. It is "op$::XXXX." where XXXX is the operator name
1666 such as + or +=. The name ends with a period, and any characters except
1667 the period can occur in the XXXX string.
1668
1669 The next part of the method description represents the arguments to
1670 the method, preceeded by a colon and ending with a semi-colon. The
1671 types of the arguments are expressed in the same way argument types
1672 are expressed in C++ name mangling. In this example an int and a char
1673 map to `ic'.
1674
1675 This is followed by a number, a letter, and an asterisk or period,
1676 followed by another semicolon. The number indicates the protections
1677 that apply to the member function. Here the 2 means public. The
1678 letter encodes any qualifier applied to the method definition. In
1679 this case A means that it is a normal function definition. The dot
1680 shows that the method is not virtual. The sections that follow
1681 elaborate further on these fields and describe the additional
1682 information present for virtual methods.
1683
1684
1685 @display
1686 .stabs "class_name:sym_desc(type)type_def(20)=type_desc(struct)struct_bytes(4)
1687 field_name(Adat):type(int),bit_offset(0),field_bits(32);
1688
1689 method_name(Ameth)::type_def(21)=type_desc(method)return_type(int);
1690 :arg_types(int char);
1691 protection(public)qualifier(normal)virtual(no);;"
1692 N_LSYM,NIL,NIL,NIL
1693 @end display
1694
1695 @smallexample
1696 .stabs "baseA:t20=s4Adat:1,0,32;Ameth::21=##1;:ic;2A.;;",128,0,0,0
1697
1698 .stabs "class_name:sym_desc(struct tag)",N_LSYM,NIL,NIL,NIL
1699
1700 .stabs "baseA:T20",128,0,0,0
1701 @end smallexample
1702
1703 @node Class instance
1704 @section Class instance
1705
1706 As shown above, describing even a simple C++ class definition is
1707 accomplished by massively extending the stab format used in C to
1708 describe structure types. However, once the class is defined, C stabs
1709 with no modifications can be used to describe class instances. The
1710 following source:
1711
1712 @example
1713 main () @{
1714 baseA AbaseA;
1715 @}
1716 @end example
1717
1718 @noindent
1719 yields the following stab describing the class instance. It looks no
1720 different from a standard C stab describing a local variable.
1721
1722 @display
1723 .stabs "name:type_ref(baseA)", N_LSYM, NIL, NIL, frame_ptr_offset
1724 @end display
1725
1726 @example
1727 .stabs "AbaseA:20",128,0,0,-20
1728 @end example
1729
1730 @node Methods
1731 @section Method defintion
1732
1733 The class definition shown above declares Ameth. The C++ source below
1734 defines Ameth:
1735
1736 @example
1737 int
1738 baseA::Ameth(int in, char other)
1739 @{
1740 return in;
1741 @};
1742 @end example
1743
1744
1745 This method definition yields three stabs following the code of the
1746 method. One stab describes the method itself and following two
1747 describe its parameters. Although there is only one formal argument
1748 all methods have an implicit argument which is the `this' pointer.
1749 The `this' pointer is a pointer to the object on which the method was
1750 called. Note that the method name is mangled to encode the class name
1751 and argument types. << Name mangling is not described by this
1752 document - Is there already such a doc? >>
1753
1754 @example
1755 .stabs "name:symbol_desriptor(global function)return_type(int)",
1756 N_FUN, NIL, NIL, code_addr_of_method_start
1757
1758 .stabs "Ameth__5baseAic:F1",36,0,0,_Ameth__5baseAic
1759 @end example
1760
1761 Here is the stab for the `this' pointer implicit argument. The name
1762 of the `this' pointer is always `this.' Type 19, the `this' pointer is
1763 defined as a pointer to type 20, baseA, but a stab defining baseA has
1764 not yet been emited. Since the compiler knows it will be emited
1765 shortly, here it just outputs a cross reference to the undefined
1766 symbol, by prefixing the symbol name with xs.
1767
1768 @example
1769 .stabs "name:sym_desc(register param)type_def(19)=
1770 type_desc(ptr to)type_ref(baseA)=
1771 type_desc(cross-reference to)baseA:",N_RSYM,NIL,NIL,register_number
1772
1773 .stabs "this:P19=*20=xsbaseA:",64,0,0,8
1774 @end example
1775
1776 The stab for the explicit integer argument looks just like a parameter
1777 to a C function. The last field of the stab is the offset from the
1778 argument pointer, which in most systems is the same as the frame
1779 pointer.
1780
1781 @example
1782 .stabs "name:sym_desc(value parameter)type_ref(int)",
1783 N_PSYM,NIL,NIL,offset_from_arg_ptr
1784
1785 .stabs "in:p1",160,0,0,72
1786 @end example
1787
1788 << The examples that follow are based on A1.C >>
1789
1790 @node Protections
1791 @section Protections
1792
1793
1794 In the simple class definition shown above all member data and
1795 functions were publicly accessable. The example that follows
1796 contrasts public, protected and privately accessable fields and shows
1797 how these protections are encoded in C++ stabs.
1798
1799 Protections for class member data are signified by two characters
1800 embeded in the stab defining the class type. These characters are
1801 located after the name: part of the string. /0 means private, /1
1802 means protected, and /2 means public. If these characters are omited
1803 this means that the member is public. The following C++ source:
1804
1805 @example
1806 class all_data @{
1807 private:
1808 int priv_dat;
1809 protected:
1810 char prot_dat;
1811 public:
1812 float pub_dat;
1813 @};
1814 @end example
1815
1816 @noindent
1817 generates the following stab to describe the class type all_data.
1818
1819 @display
1820 .stabs "class_name:sym_desc(type)type_def(19)=type_desc(struct)struct_bytes
1821 data_name:/protection(private)type_ref(int),bit_offset,num_bits;
1822 data_name:/protection(protected)type_ref(char),bit_offset,num_bits;
1823 data_name:(/num omited, private)type_ref(float),bit_offset,num_bits;;"
1824 N_LSYM,NIL,NIL,NIL
1825 @end display
1826
1827 @smallexample
1828 .stabs "all_data:t19=s12
1829 priv_dat:/01,0,32;prot_dat:/12,32,8;pub_dat:12,64,32;;",128,0,0,0
1830 @end smallexample
1831
1832 Protections for member functions are signified by one digit embeded in
1833 the field part of the stab describing the method. The digit is 0 if
1834 private, 1 if protected and 2 if public. Consider the C++ class
1835 definition below:
1836
1837 @example
1838 class all_methods @{
1839 private:
1840 int priv_meth(int in)@{return in;@};
1841 protected:
1842 char protMeth(char in)@{return in;@};
1843 public:
1844 float pubMeth(float in)@{return in;@};
1845 @};
1846 @end example
1847
1848 It generates the following stab. The digit in question is to the left
1849 of an `A' in each case. Notice also that in this case two symbol
1850 descriptors apply to the class name struct tag and struct type.
1851
1852 @display
1853 .stabs "class_name:sym_desc(struct tag&type)type_def(21)=
1854 sym_desc(struct)struct_bytes(1)
1855 meth_name::type_def(22)=sym_desc(method)returning(int);
1856 :args(int);protection(private)modifier(normal)virtual(no);
1857 meth_name::type_def(23)=sym_desc(method)returning(char);
1858 :args(char);protection(protected)modifier(normal)virual(no);
1859 meth_name::type_def(24)=sym_desc(method)returning(float);
1860 :args(float);protection(public)modifier(normal)virtual(no);;",
1861 N_LSYM,NIL,NIL,NIL
1862 @end display
1863
1864 @smallexample
1865 .stabs "all_methods:Tt21=s1priv_meth::22=##1;:i;0A.;protMeth::23=##2;:c;1A.;
1866 pubMeth::24=##12;:f;2A.;;",128,0,0,0
1867 @end smallexample
1868
1869 @node Method Modifiers
1870 @section Method Modifiers (const, volatile, const volatile)
1871
1872 << based on a6.C >>
1873
1874 In the class example described above all the methods have the normal
1875 modifier. This method modifier information is located just after the
1876 protection information for the method. This field has four possible
1877 character values. Normal methods use A, const methods use B, volatile
1878 methods use C, and const volatile methods use D. Consider the class
1879 definition below:
1880
1881 @example
1882 class A @{
1883 public:
1884 int ConstMeth (int arg) const @{ return arg; @};
1885 char VolatileMeth (char arg) volatile @{ return arg; @};
1886 float ConstVolMeth (float arg) const volatile @{return arg; @};
1887 @};
1888 @end example
1889
1890 This class is described by the following stab:
1891
1892 @display
1893 .stabs "class(A):sym_desc(struct)type_def(20)=type_desc(struct)struct_bytes(1)
1894 meth_name(ConstMeth)::type_def(21)sym_desc(method)
1895 returning(int);:arg(int);protection(public)modifier(const)virtual(no);
1896 meth_name(VolatileMeth)::type_def(22)=sym_desc(method)
1897 returning(char);:arg(char);protection(public)modifier(volatile)virt(no)
1898 meth_name(ConstVolMeth)::type_def(23)=sym_desc(method)
1899 returning(float);:arg(float);protection(public)modifer(const volatile)
1900 virtual(no);;", @dots{}
1901 @end display
1902
1903 @example
1904 .stabs "A:T20=s1ConstMeth::21=##1;:i;2B.;VolatileMeth::22=##2;:c;2C.;
1905 ConstVolMeth::23=##12;:f;2D.;;",128,0,0,0
1906 @end example
1907
1908 @node Virtual Methods
1909 @section Virtual Methods
1910
1911 << The following examples are based on a4.C >>
1912
1913 The presence of virtual methods in a class definition adds additional
1914 data to the class description. The extra data is appended to the
1915 description of the virtual method and to the end of the class
1916 description. Consider the class definition below:
1917
1918 @example
1919 class A @{
1920 public:
1921 int Adat;
1922 virtual int A_virt (int arg) @{ return arg; @};
1923 @};
1924 @end example
1925
1926 This results in the stab below describing class A. It defines a new
1927 type (20) which is an 8 byte structure. The first field of the class
1928 struct is Adat, an integer, starting at structure offset 0 and
1929 occupying 32 bits.
1930
1931 The second field in the class struct is not explicitly defined by the
1932 C++ class definition but is implied by the fact that the class
1933 contains a virtual method. This field is the vtable pointer. The
1934 name of the vtable pointer field starts with $vf and continues with a
1935 type reference to the class it is part of. In this example the type
1936 reference for class A is 20 so the name of its vtable pointer field is
1937 $vf20, followed by the usual colon.
1938
1939 Next there is a type definition for the vtable pointer type (21).
1940 This is in turn defined as a pointer to another new type (22).
1941
1942 Type 22 is the vtable itself, which is defined as an array, indexed by
1943 a range of integers between 0 and 1, and whose elements are of type
1944 17. Type 17 was the vtable record type defined by the boilerplate C++
1945 type definitions, as shown earlier.
1946
1947 The bit offset of the vtable pointer field is 32. The number of bits
1948 in the field are not specified when the field is a vtable pointer.
1949
1950 Next is the method definition for the virtual member function A_virt.
1951 Its description starts out using the same format as the non-virtual
1952 member functions described above, except instead of a dot after the
1953 `A' there is an asterisk, indicating that the function is virtual.
1954 Since is is virtual some addition information is appended to the end
1955 of the method description.
1956
1957 The first number represents the vtable index of the method. This is a
1958 32 bit unsigned number with the high bit set, followed by a
1959 semi-colon.
1960
1961 The second number is a type reference to the first base class in the
1962 inheritence hierarchy defining the virtual member function. In this
1963 case the class stab describes a base class so the virtual function is
1964 not overriding any other definition of the method. Therefore the
1965 reference is to the type number of the class that the stab is
1966 describing (20).
1967
1968 This is followed by three semi-colons. One marks the end of the
1969 current sub-section, one marks the end of the method field, and the
1970 third marks the end of the struct definition.
1971
1972 For classes containing virtual functions the very last section of the
1973 string part of the stab holds a type reference to the first base
1974 class. This is preceeded by `~%' and followed by a final semi-colon.
1975
1976 @display
1977 .stabs "class_name(A):type_def(20)=sym_desc(struct)struct_bytes(8)
1978 field_name(Adat):type_ref(int),bit_offset(0),field_bits(32);
1979 field_name(A virt func ptr):type_def(21)=type_desc(ptr to)type_def(22)=
1980 sym_desc(array)index_type_ref(range of int from 0 to 1);
1981 elem_type_ref(vtbl elem type),
1982 bit_offset(32);
1983 meth_name(A_virt)::typedef(23)=sym_desc(method)returning(int);
1984 :arg_type(int),protection(public)normal(yes)virtual(yes)
1985 vtable_index(1);class_first_defining(A);;;~%first_base(A);",
1986 N_LSYM,NIL,NIL,NIL
1987 @end display
1988
1989 @example
1990 .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
1991 @end example
1992
1993 @node Inheritence
1994 @section Inheritence
1995
1996 Stabs describing C++ derived classes include additional sections that
1997 describe the inheritence hierarchy of the class. A derived class stab
1998 also encodes the number of base classes. For each base class it tells
1999 if the base class is virtual or not, and if the inheritence is private
2000 or public. It also gives the offset into the object of the portion of
2001 the object corresponding to each base class.
2002
2003 This additional information is embeded in the class stab following the
2004 number of bytes in the struct. First the number of base classes
2005 appears bracketed by an exclamation point and a comma.
2006
2007 Then for each base type there repeats a series: two digits, a number,
2008 a comma, another number, and a semi-colon.
2009
2010 The first of the two digits is 1 if the base class is virtual and 0 if
2011 not. The second digit is 2 if the derivation is public and 0 if not.
2012
2013 The number following the first two digits is the offset from the start
2014 of the object to the part of the object pertaining to the base class.
2015
2016 After the comma, the second number is a type_descriptor for the base
2017 type. Finally a semi-colon ends the series, which repeats for each
2018 base class.
2019
2020 The source below defines three base classes A, B, and C and the
2021 derived class D.
2022
2023
2024 @example
2025 class A @{
2026 public:
2027 int Adat;
2028 virtual int A_virt (int arg) @{ return arg; @};
2029 @};
2030
2031 class B @{
2032 public:
2033 int B_dat;
2034 virtual int B_virt (int arg) @{return arg; @};
2035 @};
2036
2037 class C @{
2038 public:
2039 int Cdat;
2040 virtual int C_virt (int arg) @{return arg; @};
2041 @};
2042
2043 class D : A, virtual B, public C @{
2044 public:
2045 int Ddat;
2046 virtual int A_virt (int arg ) @{ return arg+1; @};
2047 virtual int B_virt (int arg) @{ return arg+2; @};
2048 virtual int C_virt (int arg) @{ return arg+3; @};
2049 virtual int D_virt (int arg) @{ return arg; @};
2050 @};
2051 @end example
2052
2053 Class stabs similar to the ones described earlier are generated for
2054 each base class.
2055
2056 @c FIXME!!! the linebreaks in the following example probably make the
2057 @c examples literally unusable, but I don't know any other way to get
2058 @c them on the page.
2059 @smallexample
2060 .stabs "A:T20=s8Adat:1,0,32;$vf20:21=*22=ar1;0;1;17,32;
2061 A_virt::23=##1;:i;2A*-2147483647;20;;;~%20;",128,0,0,0
2062
2063 .stabs "B:Tt25=s8Bdat:1,0,32;$vf25:21,32;B_virt::26=##1;
2064 :i;2A*-2147483647;25;;;~%25;",128,0,0,0
2065
2066 .stabs "C:Tt28=s8Cdat:1,0,32;$vf28:21,32;C_virt::29=##1;
2067 :i;2A*-2147483647;28;;;~%28;",128,0,0,0
2068 @end smallexample
2069
2070 In the stab describing derived class D below, the information about
2071 the derivation of this class is encoded as follows.
2072
2073 @display
2074 .stabs "derived_class_name:symbol_descriptors(struct tag&type)=
2075 type_descriptor(struct)struct_bytes(32)!num_bases(3),
2076 base_virtual(no)inheritence_public(no)base_offset(0),
2077 base_class_type_ref(A);
2078 base_virtual(yes)inheritence_public(no)base_offset(NIL),
2079 base_class_type_ref(B);
2080 base_virtual(no)inheritence_public(yes)base_offset(64),
2081 base_class_type_ref(C); @dots{}
2082 @end display
2083
2084 @c FIXME! fake linebreaks.
2085 @smallexample
2086 .stabs "D:Tt31=s32!3,000,20;100,25;0264,28;$vb25:24,128;Ddat:
2087 1,160,32;A_virt::32=##1;:i;2A*-2147483647;20;;B_virt:
2088 :32:i;2A*-2147483647;25;;C_virt::32:i;2A*-2147483647;
2089 28;;D_virt::32:i;2A*-2147483646;31;;;~%20;",128,0,0,0
2090 @end smallexample
2091
2092 @node Virtual Base Classes
2093 @section Virtual Base Classes
2094
2095 A derived class object consists of a concatination in memory of the
2096 data areas defined by each base class, starting with the leftmost and
2097 ending with the rightmost in the list of base classes. The exception
2098 to this rule is for virtual inheritence. In the example above, class
2099 D inherits virtually from base class B. This means that an instance
2100 of a D object will not contain it's own B part but merely a pointer to
2101 a B part, known as a virtual base pointer.
2102
2103 In a derived class stab, the base offset part of the derivation
2104 information, described above, shows how the base class parts are
2105 ordered. The base offset for a virtual base class is always given as
2106 0. Notice that the base offset for B is given as 0 even though B is
2107 not the first base class. The first base class A starts at offset 0.
2108
2109 The field information part of the stab for class D describes the field
2110 which is the pointer to the virtual base class B. The vbase pointer
2111 name is $vb followed by a type reference to the virtual base class.
2112 Since the type id for B in this example is 25, the vbase pointer name
2113 is $vb25.
2114
2115 @c FIXME!! fake linebreaks below
2116 @smallexample
2117 .stabs "D:Tt31=s32!3,000,20;100,25;0264,28;$vb25:24,128;Ddat:1,
2118 160,32;A_virt::32=##1;:i;2A*-2147483647;20;;B_virt::32:i;
2119 2A*-2147483647;25;;C_virt::32:i;2A*-2147483647;28;;D_virt:
2120 :32:i;2A*-2147483646;31;;;~%20;",128,0,0,0
2121 @end smallexample
2122
2123 Following the name and a semicolon is a type reference describing the
2124 type of the virtual base class pointer, in this case 24. Type 24 was
2125 defined earlier as the type of the B class `this` pointer. The
2126 `this' pointer for a class is a pointer to the class type.
2127
2128 @example
2129 .stabs "this:P24=*25=xsB:",64,0,0,8
2130 @end example
2131
2132 Finally the field offset part of the vbase pointer field description
2133 shows that the vbase pointer is the first field in the D object,
2134 before any data fields defined by the class. The layout of a D class
2135 object is a follows, Adat at 0, the vtable pointer for A at 32, Cdat
2136 at 64, the vtable pointer for C at 96, the virtual ase pointer for B
2137 at 128, and Ddat at 160.
2138
2139
2140 @node Static Members
2141 @section Static Members
2142
2143 The data area for a class is a concatenation of the space used by the
2144 data members of the class. If the class has virtual methods, a vtable
2145 pointer follows the class data. The field offset part of each field
2146 description in the class stab shows this ordering.
2147
2148 << How is this reflected in stabs? See Cygnus bug #677 for some info. >>
2149
2150 @node Example2.c
2151 @appendix Example2.c - source code for extended example
2152
2153 @example
2154 1 char g_foo = 'c';
2155 2 register int g_bar asm ("%g5");
2156 3 static int s_g_repeat = 2;
2157 4 int (*g_pf)();
2158 5
2159 6 struct s_tag @{
2160 7 int s_int;
2161 8 float s_float;
2162 9 char s_char_vec[8];
2163 10 struct s_tag* s_next;
2164 11 @} g_an_s;
2165 12
2166 13 typedef struct s_tag s_typedef;
2167 14
2168 15 char char_vec[3] = @{'a','b','c'@};
2169 16
2170 17 main (argc, argv)
2171 18 int argc;
2172 19 char* argv[];
2173 20 @{
2174 21 static float s_flap;
2175 22 int times;
2176 23 for (times=0; times < s_g_repeat; times++)@{
2177 24 int inner;
2178 25 printf ("Hello world\n");
2179 26 @}
2180 27 @};
2181 28
2182 29 enum e_places @{first,second=3,last@};
2183 30
2184 31 static s_proc (s_arg, s_ptr_arg, char_vec)
2185 32 s_typedef s_arg;
2186 33 s_typedef* s_ptr_arg;
2187 34 char* char_vec;
2188 35 @{
2189 36 union u_tag @{
2190 37 int u_int;
2191 38 float u_float;
2192 39 char* u_char;
2193 40 @} an_u;
2194 41 @}
2195 42
2196 43
2197 @end example
2198
2199 @node Example2.s
2200 @appendix Example2.s - assembly code for extended example
2201
2202 @example
2203 1 gcc2_compiled.:
2204 2 .stabs "/cygint/s1/users/jcm/play/",100,0,0,Ltext0
2205 3 .stabs "example2.c",100,0,0,Ltext0
2206 4 .text
2207 5 Ltext0:
2208 6 .stabs "int:t1=r1;-2147483648;2147483647;",128,0,0,0
2209 7 .stabs "char:t2=r2;0;127;",128,0,0,0
2210 8 .stabs "long int:t3=r1;-2147483648;2147483647;",128,0,0,0
2211 9 .stabs "unsigned int:t4=r1;0;-1;",128,0,0,0
2212 10 .stabs "long unsigned int:t5=r1;0;-1;",128,0,0,0
2213 11 .stabs "short int:t6=r1;-32768;32767;",128,0,0,0
2214 12 .stabs "long long int:t7=r1;0;-1;",128,0,0,0
2215 13 .stabs "short unsigned int:t8=r1;0;65535;",128,0,0,0
2216 14 .stabs "long long unsigned int:t9=r1;0;-1;",128,0,0,0
2217 15 .stabs "signed char:t10=r1;-128;127;",128,0,0,0
2218 16 .stabs "unsigned char:t11=r1;0;255;",128,0,0,0
2219 17 .stabs "float:t12=r1;4;0;",128,0,0,0
2220 18 .stabs "double:t13=r1;8;0;",128,0,0,0
2221 19 .stabs "long double:t14=r1;8;0;",128,0,0,0
2222 20 .stabs "void:t15=15",128,0,0,0
2223 21 .stabs "g_foo:G2",32,0,0,0
2224 22 .global _g_foo
2225 23 .data
2226 24 _g_foo:
2227 25 .byte 99
2228 26 .stabs "s_g_repeat:S1",38,0,0,_s_g_repeat
2229 27 .align 4
2230 28 _s_g_repeat:
2231 29 .word 2
2232 @c FIXME! fake linebreak in line 30
2233 30 .stabs "s_tag:T16=s20s_int:1,0,32;s_float:12,32,32;s_char_vec:
2234 17=ar1;0;7;2,64,64;s_next:18=*16,128,32;;",128,0,0,0
2235 31 .stabs "s_typedef:t16",128,0,0,0
2236 32 .stabs "char_vec:G19=ar1;0;2;2",32,0,0,0
2237 33 .global _char_vec
2238 34 .align 4
2239 35 _char_vec:
2240 36 .byte 97
2241 37 .byte 98
2242 38 .byte 99
2243 39 .reserve _s_flap.0,4,"bss",4
2244 40 .text
2245 41 .align 4
2246 42 LC0:
2247 43 .ascii "Hello world\12\0"
2248 44 .align 4
2249 45 .global _main
2250 46 .proc 1
2251 47 _main:
2252 48 .stabn 68,0,20,LM1
2253 49 LM1:
2254 50 !#PROLOGUE# 0
2255 51 save %sp,-144,%sp
2256 52 !#PROLOGUE# 1
2257 53 st %i0,[%fp+68]
2258 54 st %i1,[%fp+72]
2259 55 call ___main,0
2260 56 nop
2261 57 LBB2:
2262 58 .stabn 68,0,23,LM2
2263 59 LM2:
2264 60 st %g0,[%fp-20]
2265 61 L2:
2266 62 sethi %hi(_s_g_repeat),%o0
2267 63 ld [%fp-20],%o1
2268 64 ld [%o0+%lo(_s_g_repeat)],%o0
2269 65 cmp %o1,%o0
2270 66 bge L3
2271 67 nop
2272 68 LBB3:
2273 69 .stabn 68,0,25,LM3
2274 70 LM3:
2275 71 sethi %hi(LC0),%o1
2276 72 or %o1,%lo(LC0),%o0
2277 73 call _printf,0
2278 74 nop
2279 75 .stabn 68,0,26,LM4
2280 76 LM4:
2281 77 LBE3:
2282 78 .stabn 68,0,23,LM5
2283 79 LM5:
2284 80 L4:
2285 81 ld [%fp-20],%o0
2286 82 add %o0,1,%o1
2287 83 st %o1,[%fp-20]
2288 84 b,a L2
2289 85 L3:
2290 86 .stabn 68,0,27,LM6
2291 87 LM6:
2292 88 LBE2:
2293 89 .stabn 68,0,27,LM7
2294 90 LM7:
2295 91 L1:
2296 92 ret
2297 93 restore
2298 94 .stabs "main:F1",36,0,0,_main
2299 95 .stabs "argc:p1",160,0,0,68
2300 96 .stabs "argv:p20=*21=*2",160,0,0,72
2301 97 .stabs "s_flap:V12",40,0,0,_s_flap.0
2302 98 .stabs "times:1",128,0,0,-20
2303 99 .stabn 192,0,0,LBB2
2304 100 .stabs "inner:1",128,0,0,-24
2305 101 .stabn 192,0,0,LBB3
2306 102 .stabn 224,0,0,LBE3
2307 103 .stabn 224,0,0,LBE2
2308 104 .stabs "e_places:T22=efirst:0,second:3,last:4,;",128,0,0,0
2309 @c FIXME: fake linebreak in line 105
2310 105 .stabs "u_tag:T23=u4u_int:1,0,32;u_float:12,0,32;u_char:21,0,32;;",
2311 128,0,0,0
2312 106 .align 4
2313 107 .proc 1
2314 108 _s_proc:
2315 109 .stabn 68,0,35,LM8
2316 110 LM8:
2317 111 !#PROLOGUE# 0
2318 112 save %sp,-120,%sp
2319 113 !#PROLOGUE# 1
2320 114 mov %i0,%o0
2321 115 st %i1,[%fp+72]
2322 116 st %i2,[%fp+76]
2323 117 LBB4:
2324 118 .stabn 68,0,41,LM9
2325 119 LM9:
2326 120 LBE4:
2327 121 .stabn 68,0,41,LM10
2328 122 LM10:
2329 123 L5:
2330 124 ret
2331 125 restore
2332 126 .stabs "s_proc:f1",36,0,0,_s_proc
2333 127 .stabs "s_arg:p16",160,0,0,0
2334 128 .stabs "s_ptr_arg:p18",160,0,0,72
2335 129 .stabs "char_vec:p21",160,0,0,76
2336 130 .stabs "an_u:23",128,0,0,-20
2337 131 .stabn 192,0,0,LBB4
2338 132 .stabn 224,0,0,LBE4
2339 133 .stabs "g_bar:r1",64,0,0,5
2340 134 .stabs "g_pf:G24=*25=f1",32,0,0,0
2341 135 .common _g_pf,4,"bss"
2342 136 .stabs "g_an_s:G16",32,0,0,0
2343 137 .common _g_an_s,20,"bss"
2344 @end example
2345
2346
2347 @node Quick reference
2348 @appendix Quick reference
2349
2350 @menu
2351 * Stab types:: Table A: Symbol types from stabs
2352 * Assembler types:: Table B: Symbol types from assembler and linker
2353 * Symbol descriptors:: Table C
2354 * Type Descriptors:: Table D
2355 @end menu
2356
2357 @node Stab types
2358 @section Table A: Symbol types from stabs
2359
2360 Table A lists stab types sorted by type number. Stab type numbers are
2361 32 and greater. This is the full list of stab numbers, including stab
2362 types that are used in languages other than C.
2363
2364 The #define names for these stab types are defined in:
2365 devo/include/aout/stab.def
2366
2367 @smallexample
2368 type type #define used to describe
2369 dec hex name source program feature
2370 ------------------------------------------------
2371 32 0x20 N_GYSM global symbol
2372 34 0X22 N_FNAME function name (for BSD Fortran)
2373 36 0x24 N_FUN function name or text segment variable for C
2374 38 0x26 N_STSYM static symbol (data segment w/internal linkage)
2375 40 0x28 N_LCSYM .lcomm symbol(BSS-seg variable w/internal linkage)
2376 42 0x2a N_MAIN Name of main routine (not used in C)
2377 48 0x30 N_PC global symbol (for Pascal)
2378 50 0x32 N_NSYMS number of symbols (according to Ultrix V4.0)
2379 52 0x34 N_NOMAP no DST map for sym (according to Ultrix V4.0)
2380 64 0x40 N_RSYM register variable
2381 66 0x42 N_M2C Modula-2 compilation unit
2382 68 0x44 N_SLINE line number in text segment
2383 70 0x46 N_DSLINE line number in data segment
2384
2385 72 0x48 N_BSLINE line number in bss segment
2386 72 0x48 N_BROWS Sun source code browser, path to .cb file
2387
2388 74 0x4a N_DEFD GNU Modula2 definition module dependency
2389
2390 80 0x50 N_EHDECL GNU C++ exception variable
2391 80 0x50 N_MOD2 Modula2 info "for imc" (according to Ultrix V4.0)
2392
2393 84 0x54 N_CATCH GNU C++ "catch" clause
2394 96 0x60 N_SSYM structure of union element
2395 100 0x64 N_SO path and name of source file
2396 128 0x80 N_LSYM automatic var in the stack
2397 (also used for type desc.)
2398 130 0x82 N_BINCL beginning of an include file (Sun only)
2399 132 0x84 N_SOL Name of sub-source (#include) file.
2400 160 0xa0 N_PSYM parameter variable
2401 162 0xa2 N_EINCL end of an include file
2402 164 0xa4 N_ENTRY alternate entry point
2403 192 0xc0 N_LBRAC beginning of a lexical block
2404 194 0xc2 N_EXCL place holder for a deleted include file
2405 196 0xc4 N_SCOPE modula2 scope information (Sun linker)
2406 224 0xe0 N_RBRAC end of a lexical block
2407 226 0xe2 N_BCOMM begin named common block
2408 228 0xe4 N_ECOMM end named common block
2409 232 0xe8 N_ECOML end common (local name)
2410
2411 << used on Gould systems for non-base registers syms >>
2412 240 0xf0 N_NBTEXT ??
2413 242 0xf2 N_NBDATA ??
2414 244 0xf4 N_NBBSS ??
2415 246 0xf6 N_NBSTS ??
2416 248 0xf8 N_NBLCS ??
2417 @end smallexample
2418
2419 @node Assembler types
2420 @section Table B: Symbol types from assembler and linker
2421
2422 Table B shows the types of symbol table entries that hold assembler
2423 and linker symbols.
2424
2425 The #define names for these n_types values are defined in
2426 /include/aout/aout64.h
2427
2428 @smallexample
2429 dec hex #define
2430 n_type n_type name used to describe
2431 ------------------------------------------
2432 1 0x0 N_UNDF undefined symbol
2433 2 0x2 N_ABS absolute symbol -- defined at a particular address
2434 3 0x3 extern " (vs. file scope)
2435 4 0x4 N_TEXT text symbol -- defined at offset in text segment
2436 5 0x5 extern " (vs. file scope)
2437 6 0x6 N_DATA data symbol -- defined at offset in data segment
2438 7 0x7 extern " (vs. file scope)
2439 8 0x8 N_BSS BSS symbol -- defined at offset in zero'd segment
2440 9 extern " (vs. file scope)
2441
2442 12 0x0C N_FN_SEQ func name for Sequent compilers (stab exception)
2443
2444 49 0x12 N_COMM common sym -- visable after shared lib dynamic link
2445 31 0x1f N_FN file name of a .o file
2446 @end smallexample
2447
2448 @node Symbol descriptors
2449 @section Table C: Symbol descriptors
2450
2451 @c Please keep this alphabetical
2452 @table @code
2453 @item (empty)
2454 Local variable, @xref{Automatic variables}.
2455
2456 @item C
2457 @xref{Parameters}.
2458
2459 @item f
2460 Local function, @xref{Procedures}.
2461
2462 @item F
2463 Global function, @xref{Procedures}.
2464
2465 @item G
2466 Global variable, @xref{Global Variables}.
2467
2468 @item i
2469 @xref{Parameters}.
2470
2471 @item p
2472 Argument list parameter @xref{Parameters}.
2473
2474 @item pP
2475 @xref{Parameters}.
2476
2477 @item pF
2478 @xref{Parameters}.
2479
2480 @item P
2481 @itemx R
2482 Register parameter @xref{Parameters}.
2483
2484 @item r
2485 Register variable, @xref{Register variables}.
2486
2487 @item S
2488 Static file scope variable @xref{Initialized statics},
2489 @xref{Un-initialized statics}.
2490
2491 @item t
2492 Type name, @xref{Typedefs}.
2493
2494 @item T
2495 enumeration, struct or union tag, @xref{Unions}.
2496
2497 @item v
2498 Call by reference, @xref{Parameters}.
2499
2500 @item V
2501 Static procedure scope variable @xref{Initialized statics},
2502 @xref{Un-initialized statics}.
2503
2504 @item X
2505 Function return variable, @xref{Parameters}.
2506 @end table
2507
2508 @node Type Descriptors
2509 @section Table D: Type Descriptors
2510
2511 @example
2512 descriptor meaning
2513 -------------------------------------
2514 (empty) type reference
2515 a array type
2516 e enumeration type
2517 f function type
2518 r range type
2519 s structure type
2520 u union specifications
2521 * pointer type
2522 @end example
2523
2524
2525 @node Expanded reference
2526 @appendix Expanded reference by stab type.
2527
2528 Format of an entry:
2529
2530 The first line is the symbol type expressed in decimal, hexadecimal,
2531 and as a #define (see devo/include/aout/stab.def).
2532
2533 The second line describes the language constructs the symbol type
2534 represents.
2535
2536 The third line is the stab format with the significant stab fields
2537 named and the rest NIL.
2538
2539 Subsequent lines expand upon the meaning and possible values for each
2540 significant stab field. # stands in for the type descriptor.
2541
2542 Finally, any further information.
2543
2544 @menu
2545 * N_GSYM:: Global variable
2546 * N_FNAME:: Function name (BSD Fortran)
2547 * N_FUN:: C Function name or text segment variable
2548 * N_STSYM:: Initialized static symbol
2549 * N_LCSYM:: Uninitialized static symbol
2550 * N_MAIN:: Name of main routine (not for C)
2551 * N_PC:: Pascal global symbol
2552 * N_NSYMS:: Number of symbols
2553 * N_NOMAP:: No DST map
2554 * N_RSYM:: Register variable
2555 * N_M2C:: Modula-2 compilation unit
2556 * N_SLINE:: Line number in text segment
2557 * N_DSLINE:: Line number in data segment
2558 * N_BSLINE:: Line number in bss segment
2559 * N_BROWS:: Path to .cb file for Sun source code browser
2560 * N_DEFD:: GNU Modula2 definition module dependency
2561 * N_EHDECL:: GNU C++ exception variable
2562 * N_MOD2:: Modula2 information "for imc"
2563 * N_CATCH:: GNU C++ "catch" clause
2564 * N_SSYM:: Structure or union element
2565 * N_SO:: Source file containing main
2566 * N_LSYM:: Automatic variable
2567 * N_BINCL:: Beginning of include file (Sun only)
2568 * N_SOL:: Name of include file
2569 * N_PSYM:: Parameter variable
2570 * N_EINCL:: End of include file
2571 * N_ENTRY:: Alternate entry point
2572 * N_LBRAC:: Beginning of lexical block
2573 * N_EXCL:: Deleted include file
2574 * N_SCOPE:: Modula2 scope information (Sun only)
2575 * N_RBRAC:: End of lexical block
2576 * N_BCOMM:: Begin named common block
2577 * N_ECOMM:: End named common block
2578 * N_ECOML:: End common
2579 * Gould:: non-base register symbols used on Gould systems
2580 * N_LENG:: Length of preceding entry
2581 @end menu
2582
2583 @node N_GSYM
2584 @section 32 - 0x20 - N_GYSM
2585
2586 @display
2587 Global variable.
2588
2589 .stabs "name", N_GSYM, NIL, NIL, NIL
2590 @end display
2591
2592 @example
2593 "name" -> "symbol_name:#type"
2594 # -> G
2595 @end example
2596
2597 Only the "name" field is significant. The location of the variable is
2598 obtained from the corresponding external symbol.
2599
2600 @node N_FNAME
2601 @section 34 - 0x22 - N_FNAME
2602 Function name (for BSD Fortran)
2603
2604 @display
2605 .stabs "name", N_FNAME, NIL, NIL, NIL
2606 @end display
2607
2608 @example
2609 "name" -> "function_name"
2610 @end example
2611
2612 Only the "name" field is significant. The location of the symbol is
2613 obtained from the corresponding extern symbol.
2614
2615 @node N_FUN
2616 @section 36 - 0x24 - N_FUN
2617 Function name or text segment variable for C.
2618
2619 @display
2620 .stabs "name", N_FUN, NIL, desc, value
2621 @end display
2622
2623 @example
2624 @exdent @emph{For functions:}
2625 "name" -> "proc_name:#return_type"
2626 # -> F (global function)
2627 f (local function)
2628 desc -> line num for proc start. (GCC doesn't set and DBX doesn't miss it.)
2629 value -> Code address of proc start.
2630
2631 @exdent @emph{For text segment variables:}
2632 <<How to create one?>>
2633 @end example
2634
2635 @node N_STSYM
2636 @section 38 - 0x26 - N_STSYM
2637 Initialized static symbol (data segment w/internal linkage).
2638
2639 @display
2640 .stabs "name", N_STSYM, NIL, NIL, value
2641 @end display
2642
2643 @example
2644 "name" -> "symbol_name#type"
2645 # -> S (scope global to compilation unit)
2646 -> V (scope local to a procedure)
2647 value -> Data Address
2648 @end example
2649
2650 @node N_LCSYM
2651 @section 40 - 0x28 - N_LCSYM
2652 Unitialized static (.lcomm) symbol(BSS segment w/internal linkage).
2653
2654 @display
2655 .stabs "name", N_LCLSYM, NIL, NIL, value
2656 @end display
2657
2658 @example
2659 "name" -> "symbol_name#type"
2660 # -> S (scope global to compilation unit)
2661 -> V (scope local to procedure)
2662 value -> BSS Address
2663 @end example
2664
2665 @node N_MAIN
2666 @section 42 - 0x2a - N_MAIN
2667 Name of main routine (not used in C)
2668
2669 @display
2670 .stabs "name", N_MAIN, NIL, NIL, NIL
2671 @end display
2672
2673 @example
2674 "name" -> "name_of_main_routine"
2675 @end example
2676
2677 @node N_PC
2678 @section 48 - 0x30 - N_PC
2679 Global symbol (for Pascal)
2680
2681 @display
2682 .stabs "name", N_PC, NIL, NIL, value
2683 @end display
2684
2685 @example
2686 "name" -> "symbol_name" <<?>>
2687 value -> supposedly the line number (stab.def is skeptical)
2688 @end example
2689
2690 @display
2691 stabdump.c says:
2692
2693 global pascal symbol: name,,0,subtype,line
2694 << subtype? >>
2695 @end display
2696
2697 @node N_NSYMS
2698 @section 50 - 0x32 - N_NSYMS
2699 Number of symbols (according to Ultrix V4.0)
2700
2701 @display
2702 0, files,,funcs,lines (stab.def)
2703 @end display
2704
2705 @node N_NOMAP
2706 @section 52 - 0x34 - N_NOMAP
2707 no DST map for sym (according to Ultrix V4.0)
2708
2709 @display
2710 name, ,0,type,ignored (stab.def)
2711 @end display
2712
2713 @node N_RSYM
2714 @section 64 - 0x40 - N_RSYM
2715 register variable
2716
2717 @display
2718 .stabs "name:type",N_RSYM,0,RegSize,RegNumber (Sun doc)
2719 @end display
2720
2721 @node N_M2C
2722 @section 66 - 0x42 - N_M2C
2723 Modula-2 compilation unit
2724
2725 @display
2726 .stabs "name", N_M2C, 0, desc, value
2727 @end display
2728
2729 @example
2730 "name" -> "unit_name,unit_time_stamp[,code_time_stamp]
2731 desc -> unit_number
2732 value -> 0 (main unit)
2733 1 (any other unit)
2734 @end example
2735
2736 @node N_SLINE
2737 @section 68 - 0x44 - N_SLINE
2738 Line number in text segment
2739
2740 @display
2741 .stabn N_SLINE, 0, desc, value
2742 @end display
2743
2744 @example
2745 desc -> line_number
2746 value -> code_address (relocatable addr where the corresponding code starts)
2747 @end example
2748
2749 For single source lines that generate discontiguous code, such as flow
2750 of control statements, there may be more than one N_SLINE stab for the
2751 same source line. In this case there is a stab at the start of each
2752 code range, each with the same line number.
2753
2754 @node N_DSLINE
2755 @section 70 - 0x46 - N_DSLINE
2756 Line number in data segment
2757
2758 @display
2759 .stabn N_DSLINE, 0, desc, value
2760 @end display
2761
2762 @example
2763 desc -> line_number
2764 value -> data_address (relocatable addr where the corresponding code
2765 starts)
2766 @end example
2767
2768 See comment for N_SLINE above.
2769
2770 @node N_BSLINE
2771 @section 72 - 0x48 - N_BSLINE
2772 Line number in bss segment
2773
2774 @display
2775 .stabn N_BSLINE, 0, desc, value
2776 @end display
2777
2778 @example
2779 desc -> line_number
2780 value -> bss_address (relocatable addr where the corresponding code
2781 starts)
2782 @end example
2783
2784 See comment for N_SLINE above.
2785
2786 @node N_BROWS
2787 @section 72 - 0x48 - N_BROWS
2788 Sun source code browser, path to .cb file
2789
2790 <<?>>
2791 "path to associated .cb file"
2792
2793 Note: type field value overlaps with N_BSLINE
2794
2795 @node N_DEFD
2796 @section 74 - 0x4a - N_DEFD
2797 GNU Modula2 definition module dependency
2798
2799 GNU Modula-2 definition module dependency. Value is the modification
2800 time of the definition file. Other is non-zero if it is imported with
2801 the GNU M2 keyword %INITIALIZE. Perhaps N_M2C can be used if there
2802 are enough empty fields?
2803
2804 @node N_EHDECL
2805 @section 80 - 0x50 - N_EHDECL
2806 GNU C++ exception variable <<?>>
2807
2808 "name is variable name"
2809
2810 Note: conflicts with N_MOD2.
2811
2812 @node N_MOD2
2813 @section 80 - 0x50 - N_MOD2
2814 Modula2 info "for imc" (according to Ultrix V4.0)
2815
2816 Note: conflicts with N_EHDECL <<?>>
2817
2818 @node N_CATCH
2819 @section 84 - 0x54 - N_CATCH
2820 GNU C++ "catch" clause
2821
2822 GNU C++ `catch' clause. Value is its address. Desc is nonzero if
2823 this entry is immediately followed by a CAUGHT stab saying what
2824 exception was caught. Multiple CAUGHT stabs means that multiple
2825 exceptions can be caught here. If Desc is 0, it means all exceptions
2826 are caught here.
2827
2828 @node N_SSYM
2829 @section 96 - 0x60 - N_SSYM
2830 Structure or union element
2831
2832 Value is offset in the structure.
2833
2834 <<?looking at structs and unions in C I didn't see these>>
2835
2836 @node N_SO
2837 @section 100 - 0x64 - N_SO
2838 Path and name of source file containing main routine
2839
2840 @display
2841 .stabs "name", N_SO, NIL, NIL, value
2842 @end display
2843
2844 @example
2845 "name" -> /source/directory/
2846 -> source_file
2847
2848 value -> the starting text address of the compilation.
2849 @end example
2850
2851 These are found two in a row. The name field of the first N_SO contains
2852 the directory that the source file is relative to. The name field of
2853 the second N_SO contains the name of the source file itself.
2854
2855 Only some compilers (e.g. gcc2, Sun cc) include the directory; this
2856 symbol can be distinguished by the fact that it ends in a slash.
2857 According to a comment in GDB's partial-stab.h, other compilers
2858 (especially unnamed C++ compilers) put out useless N_SO's for
2859 nonexistent source files (after the N_SO for the real source file).
2860
2861 @node N_LSYM
2862 @section 128 - 0x80 - N_LSYM
2863 Automatic var in the stack (also used for type descriptors.)
2864
2865 @display
2866 .stabs "name" N_LSYM, NIL, NIL, value
2867 @end display
2868
2869 @example
2870 @exdent @emph{For stack based local variables:}
2871
2872 "name" -> name of the variable
2873 value -> offset from frame pointer (negative)
2874
2875 @exdent @emph{For type descriptors:}
2876
2877 "name" -> "name_of_the_type:#type"
2878 # -> t
2879
2880 type -> type_ref (or) type_def
2881
2882 type_ref -> type_number
2883 type_def -> type_number=type_desc etc.
2884 @end example
2885
2886 Type may be either a type reference or a type definition. A type
2887 reference is a number that refers to a previously defined type. A
2888 type definition is the number that will refer to this type, followed
2889 by an equals sign, a type descriptor and the additional data that
2890 defines the type. See the Table D for type descriptors and the
2891 section on types for what data follows each type descriptor.
2892
2893 @node N_BINCL
2894 @section 130 - 0x82 - N_BINCL
2895
2896 Beginning of an include file (Sun only)
2897
2898 Beginning of an include file. Only Sun uses this. In an object file,
2899 only the name is significant. The Sun linker puts data into some of
2900 the other fields.
2901
2902 @node N_SOL
2903 @section 132 - 0x84 - N_SOL
2904
2905 Name of a sub-source file (#include file). Value is starting address
2906 of the compilation.
2907 <<?>>
2908
2909 @node N_PSYM
2910 @section 160 - 0xa0 - N_PSYM
2911
2912 Parameter variable. @xref{Parameters}.
2913
2914 @node N_EINCL
2915 @section 162 - 0xa2 - N_EINCL
2916
2917 End of an include file. This and N_BINCL act as brackets around the
2918 file's output. In an ojbect file, there is no significant data in
2919 this entry. The Sun linker puts data into some of the fields.
2920 <<?>>
2921
2922 @node N_ENTRY
2923 @section 164 - 0xa4 - N_ENTRY
2924
2925 Alternate entry point.
2926 Value is its address.
2927 <<?>>
2928
2929 @node N_LBRAC
2930 @section 192 - 0xc0 - N_LBRAC
2931
2932 Beginning of a lexical block (left brace). The variable defined
2933 inside the block precede the N_LBRAC symbol. Or can they follow as
2934 well as long as a new N_FUNC was not encountered. <<?>>
2935
2936 @display
2937 .stabn N_LBRAC, NIL, NIL, value
2938 @end display
2939
2940 @example
2941 value -> code address of block start.
2942 @end example
2943
2944 @node N_EXCL
2945 @section 194 - 0xc2 - N_EXCL
2946
2947 Place holder for a deleted include file. Replaces a N_BINCL and
2948 everything up to the corresponding N_EINCL. The Sun linker generates
2949 these when it finds multiple indentical copies of the symbols from an
2950 included file. This appears only in output from the Sun linker.
2951 <<?>>
2952
2953 @node N_SCOPE
2954 @section 196 - 0xc4 - N_SCOPE
2955
2956 Modula2 scope information (Sun linker)
2957 <<?>>
2958
2959 @node N_RBRAC
2960 @section 224 - 0xe0 - N_RBRAC
2961
2962 End of a lexical block (right brace)
2963
2964 @display
2965 .stabn N_RBRAC, NIL, NIL, value
2966 @end display
2967
2968 @example
2969 value -> code address of the end of the block.
2970 @end example
2971
2972 @node N_BCOMM
2973 @section 226 - 0xe2 - N_BCOMM
2974
2975 Begin named common block.
2976
2977 Only the name is significant.
2978 <<?>>
2979
2980 @node N_ECOMM
2981 @section 228 - 0xe4 - N_ECOMM
2982
2983 End named common block.
2984
2985 Only the name is significant and it should match the N_BCOMM
2986 <<?>>
2987
2988 @node N_ECOML
2989 @section 232 - 0xe8 - N_ECOML
2990
2991 End common (local name)
2992
2993 value is address.
2994 <<?>>
2995
2996 @node Gould
2997 @section Non-base registers on Gould systems
2998 << used on Gould systems for non-base registers syms, values assigned
2999 at random, need real info from Gould. >>
3000 <<?>>
3001
3002 @example
3003 240 0xf0 N_NBTEXT ??
3004 242 0xf2 N_NBDATA ??
3005 244 0xf4 N_NBBSS ??
3006 246 0xf6 N_NBSTS ??
3007 248 0xf8 N_NBLCS ??
3008 @end example
3009
3010 @node N_LENG
3011 @section - 0xfe - N_LENG
3012
3013 Second symbol entry containing a length-value for the preceding entry.
3014 The value is the length.
3015
3016 @node Questions
3017 @appendix Questions and anomalies
3018
3019 @itemize @bullet
3020 @item
3021 For GNU C stabs defining local and global variables (N_LSYM and
3022 N_GSYM), the desc field is supposed to contain the source line number
3023 on which the variable is defined. In reality the desc field is always
3024 0. (This behavour is defined in dbxout.c and putting a line number in
3025 desc is controlled by #ifdef WINNING_GDB which defaults to false). Gdb
3026 supposedly uses this information if you say 'list var'. In reality
3027 var can be a variable defined in the program and gdb says `function
3028 var not defined'
3029
3030 @item
3031 In GNU C stabs there seems to be no way to differentiate tag types:
3032 structures, unions, and enums (symbol descriptor T) and typedefs
3033 (symbol descriptor t) defined at file scope from types defined locally
3034 to a procedure or other more local scope. They all use the N_LSYM
3035 stab type. Types defined at procedure scope are emited after the
3036 N_RBRAC of the preceding function and before the code of the
3037 procedure in which they are defined. This is exactly the same as
3038 types defined in the source file between the two procedure bodies.
3039 GDB overcompensates by placing all types in block #1, the block for
3040 symbols of file scope. This is true for default, -ansi and
3041 -traditional compiler options. (Bugs gcc/1063, gdb/1066.)
3042
3043 @item
3044 What ends the procedure scope? Is it the proc block's N_RBRAC or the
3045 next N_FUN? (I believe its the first.)
3046
3047 @item
3048 The comment in xcoff.h says DBX_STATIC_CONST_VAR_CODE is used for
3049 static const variables. DBX_STATIC_CONST_VAR_CODE is set to N_FUN by
3050 default, in dbxout.c. If included, xcoff.h redefines it to N_STSYM.
3051 But testing the default behaviour, my Sun4 native example shows
3052 N_STSYM not N_FUN is used to describe file static initialized
3053 variables. (the code tests for TREE_READONLY(decl) &&
3054 !TREE_THIS_VOLATILE(decl) and if true uses DBX_STATIC_CONST_VAR_CODE).
3055
3056 @item
3057 Global variable stabs don't have location information. This comes
3058 from the external symbol for the same variable. The external symbol
3059 has a leading underbar on the _name of the variable and the stab does
3060 not. How do we know these two symbol table entries are talking about
3061 the same symbol when their names are different?
3062
3063 @item
3064 Can gcc be configured to output stabs the way the Sun compiler
3065 does, so that their native debugging tools work? <NO?> It doesn't by
3066 default. GDB reads either format of stab. (gcc or SunC). How about
3067 dbx?
3068 @end itemize
3069
3070 @node xcoff-differences
3071 @appendix Differences between GNU stabs in a.out and GNU stabs in xcoff
3072
3073 @c FIXME: Merge *all* these into the main body of the document.
3074 (The AIX/RS6000 native object file format is xcoff with stabs). This
3075 appendix only covers those differences which are not covered in the main
3076 body of this document.
3077
3078 @itemize @bullet
3079 @item
3080 Instead of .stabs, xcoff uses .stabx.
3081
3082 @item
3083 The data fields of an xcoff .stabx are in a different order than an
3084 a.out .stabs. The order is: string, value, type. The desc and null
3085 fields present in a.out stabs are missing in xcoff stabs. For N_GSYM
3086 the value field is the name of the symbol.
3087
3088 @item
3089 BSD a.out stab types correspond to AIX xcoff storage classes. In general the
3090 mapping is N_STABTYPE becomes C_STABTYPE. Some stab types in a.out
3091 are not supported in xcoff. See Table E. for full mappings.
3092
3093 exception:
3094 initialised static N_STSYM and un-initialized static N_LCSYM both map
3095 to the C_STSYM storage class. But the destinction is preserved
3096 because in xcoff N_STSYM and N_LCSYM must be emited in a named static
3097 block. Begin the block with .bs s[RW] data_section_name for N_STSYM
3098 or .bs s bss_section_name for N_LCSYM. End the block with .es
3099
3100 @item
3101 xcoff stabs describing tags and typedefs use the N_DECL (0x8c)instead
3102 of N_LSYM stab type.
3103
3104 @item
3105 xcoff uses N_RPSYM (0x8e) instead of the N_RSYM stab type for register
3106 variables. If the register variable is also a value parameter, then
3107 use R instead of P for the symbol descriptor.
3108
3109 6.
3110 xcoff uses negative numbers as type references to the basic types.
3111 There are no boilerplate type definitions emited for these basic
3112 types. << make table of basic types and type numbers for C >>
3113
3114 @item
3115 xcoff .stabx sometimes don't have the name part of the string field.
3116
3117 @item
3118 xcoff uses a .file stab type to represent the source file name. There
3119 is no stab for the path to the source file.
3120
3121 @item
3122 xcoff uses a .line stab type to represent source lines. The format
3123 is: .line line_number.
3124
3125 @item
3126 xcoff emits line numbers relative to the start of the current
3127 function. The start of a function is marked by .bf. If a function
3128 includes lines from a seperate file, then those line numbers are
3129 absolute line numbers in the <<sub-?>> file being compiled.
3130
3131 @item
3132 The start of current include file is marked with: .bi "filename" and
3133 the end marked with .ei "filename"
3134
3135 @item
3136 If the xcoff stab is a N_FUN (C_FUN) then follow the string field with
3137 ,. instead of just ,
3138 @end itemize
3139
3140
3141 (I think that's it for .s file differences. They could stand to be
3142 better presented. This is just a list of what I have noticed so far.
3143 There are a *lot* of differences in the information in the symbol
3144 tables of the executable and object files.)
3145
3146 Table E: mapping a.out stab types to xcoff storage classes
3147
3148 @example
3149 stab type storage class
3150 -------------------------------
3151 N_GSYM C_GSYM
3152 N_FNAME unknown
3153 N_FUN C_FUN
3154 N_STSYM C_STSYM
3155 N_LCSYM C_STSYM
3156 N_MAIN unkown
3157 N_PC unknown
3158 N_RSYM C_RSYM
3159 N_RPSYM (0x8e) C_RPSYM
3160 N_M2C unknown
3161 N_SLINE unknown
3162 N_DSLINE unknown
3163 N_BSLINE unknown
3164 N_BROWSE unchanged
3165 N_CATCH unknown
3166 N_SSYM unknown
3167 N_SO unknown
3168 N_LSYM C_LSYM
3169 N_DECL (0x8c) C_DECL
3170 N_BINCL unknown
3171 N_SOL unknown
3172 N_PSYM C_PSYM
3173 N_EINCL unknown
3174 N_ENTRY C_ENTRY
3175 N_LBRAC unknown
3176 N_EXCL unknown
3177 N_SCOPE unknown
3178 N_RBRAC unknown
3179 N_BCOMM C_BCOMM
3180 N_ECOMM C_ECOMM
3181 N_ECOML C_ECOML
3182
3183 N_LENG unknown
3184 @end example
3185
3186 @node Sun-differences
3187 @appendix Differences between GNU stabs and Sun native stabs.
3188
3189 @c FIXME: Merge all this stuff into the main body of the document.
3190
3191 @itemize @bullet
3192 @item
3193 GNU C stabs define *all* types, file or procedure scope, as
3194 N_LSYM. Sun doc talks about using N_GSYM too.
3195
3196 @item
3197 Stabs describing block scopes, N_LBRAC and N_RBRAC are supposed to
3198 contain the nesting level of the block in the desc field, re Sun doc.
3199 GNU stabs always have 0 in that field. dbx seems not to care.
3200
3201 @item
3202 Sun C stabs use type number pairs in the format (a,b) where a is a
3203 number starting with 1 and incremented for each sub-source file in the
3204 compilation. b is a number starting with 1 and incremented for each
3205 new type defined in the compilation. GNU C stabs use the type number
3206 alone, with no source file number.
3207 @end itemize
3208
3209 @contents
3210 @bye