<HTML> <HEAD> <!-- This HTML file has been created by texi2html 1.51 from /mnt/apple/gdb/source/gdb.apple/source/gdb/gdb/doc/stabs.texinfo on 23 November 1999 --> <TITLE>STABS - Overview of Stabs</TITLE> </HEAD> <BODY> Go to the first, previous, <A HREF="stabs_2.html">next</A>, <A HREF="stabs_14.html">last</A> section, <A HREF="stabs_toc.html">table of contents</A>. <P><HR><P> <P> Copyright (C) 1992, 93, 94, 95, 97, 1998 Free Software Foundation, Inc. Contributed by Cygnus Support. </P> <P> Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. </P> <H1><A NAME="SEC1" HREF="stabs_toc.html#TOC1">Overview of Stabs</A></H1> <P> <STRONG>Stabs</STRONG> refers to a format for information that describes a program to a debugger. This format was apparently invented by Peter Kessler at the University of California at Berkeley, for the <CODE>pdx</CODE> Pascal debugger; the format has spread widely since then. </P> <P> This document is one of the few published sources of documentation on stabs. It is believed to be comprehensive for stabs used by C. The lists of symbol descriptors (see section <A HREF="stabs_9.html#SEC70">Table of Symbol Descriptors</A>) and type descriptors (see section <A HREF="stabs_10.html#SEC71">Table of Type Descriptors</A>) are believed to be completely comprehensive. Stabs for COBOL-specific features and for variant records (used by Pascal and Modula-2) are poorly documented here. </P> <P> Other sources of information on stabs are <CITE>Dbx and Dbxtool Interfaces</CITE>, 2nd edition, by Sun, 1988, and <CITE>AIX Version 3.2 Files Reference</CITE>, Fourth Edition, September 1992, "dbx Stabstring Grammar" in the a.out section, page 2-31. This document is believed to incorporate the information from those two sources except where it explicitly directs you to them for more information. </P> <H2><A NAME="SEC2" HREF="stabs_toc.html#TOC2">Overview of Debugging Information Flow</A></H2> <P> The GNU C compiler compiles C source in a <TT>`.c'</TT> file into assembly language in a <TT>`.s'</TT> file, which the assembler translates into a <TT>`.o'</TT> file, which the linker combines with other <TT>`.o'</TT> files and libraries to produce an executable file. </P> <P> With the <SAMP>`-g'</SAMP> option, GCC puts in the <TT>`.s'</TT> file additional debugging information, which is slightly transformed by the assembler and linker, and carried through into the final executable. This debugging information describes features of the source file like line numbers, the types and scopes of variables, and function names, parameters, and scopes. </P> <P> For some object file formats, the debugging information is encapsulated in assembler directives known collectively as <STRONG>stab</STRONG> (symbol table) directives, which are interspersed with the generated code. Stabs are the native format for debugging information in the a.out and XCOFF object file formats. The GNU tools can also emit stabs in the COFF and ECOFF object file formats. </P> <P> The assembler adds the information from stabs to the symbol information it places by default in the symbol table and the string table of the <TT>`.o'</TT> file it is building. The linker consolidates the <TT>`.o'</TT> files into one executable file, with one symbol table and one string table. Debuggers use the symbol and string tables in the executable as a source of debugging information about the program. </P> <H2><A NAME="SEC3" HREF="stabs_toc.html#TOC3">Overview of Stab Format</A></H2> <P> There are three overall formats for stab assembler directives, differentiated by the first word of the stab. The name of the directive describes which combination of four possible data fields follows. It is either <CODE>.stabs</CODE> (string), <CODE>.stabn</CODE> (number), or <CODE>.stabd</CODE> (dot). IBM's XCOFF assembler uses <CODE>.stabx</CODE> (and some other directives such as <CODE>.file</CODE> and <CODE>.bi</CODE>) instead of <CODE>.stabs</CODE>, <CODE>.stabn</CODE> or <CODE>.stabd</CODE>. </P> <P> The overall format of each class of stab is: </P> <PRE> .stabs "<VAR>string</VAR>",<VAR>type</VAR>,<VAR>other</VAR>,<VAR>desc</VAR>,<VAR>value</VAR> .stabn <VAR>type</VAR>,<VAR>other</VAR>,<VAR>desc</VAR>,<VAR>value</VAR> .stabd <VAR>type</VAR>,<VAR>other</VAR>,<VAR>desc</VAR> .stabx "<VAR>string</VAR>",<VAR>value</VAR>,<VAR>type</VAR>,<VAR>sdb-type</VAR> </PRE> <P> For <CODE>.stabn</CODE> and <CODE>.stabd</CODE>, there is no <VAR>string</VAR> (the <CODE>n_strx</CODE> field is zero; see section <A HREF="stabs_6.html#SEC46">Symbol Information in Symbol Tables</A>). For <CODE>.stabd</CODE>, the <VAR>value</VAR> field is implicit and has the value of the current file location. For <CODE>.stabx</CODE>, the <VAR>sdb-type</VAR> field is unused for stabs and can always be set to zero. The <VAR>other</VAR> field is almost always unused and can be set to zero. </P> <P> The number in the <VAR>type</VAR> field gives some basic information about which type of stab this is (or whether it <EM>is</EM> a stab, as opposed to an ordinary symbol). Each valid type number defines a different stab type; further, the stab type defines the exact interpretation of, and possible values for, any remaining <VAR>string</VAR>, <VAR>desc</VAR>, or <VAR>value</VAR> fields present in the stab. See section <A HREF="stabs_8.html#SEC67">Table of Stab Types</A>, for a list in numeric order of the valid <VAR>type</VAR> field values for stab directives. </P> <H2><A NAME="SEC4" HREF="stabs_toc.html#TOC4">The String Field</A></H2> <P> For most stabs the string field holds the meat of the debugging information. The flexible nature of this field is what makes stabs extensible. For some stab types the string field contains only a name. For other stab types the contents can be a great deal more complex. </P> <P> The overall format of the string field for most stab types is: </P> <PRE> "<VAR>name</VAR>:<VAR>symbol-descriptor</VAR> <VAR>type-information</VAR>" </PRE> <P> <VAR>name</VAR> is the name of the symbol represented by the stab; it can contain a pair of colons (see section <A HREF="stabs_7.html#SEC54">Defining a Symbol Within Another Type</A>). <VAR>name</VAR> can be omitted, which means the stab represents an unnamed object. For example, <SAMP>`:t10=*2'</SAMP> defines type 10 as a pointer to type 2, but does not give the type a name. Omitting the <VAR>name</VAR> field is supported by AIX dbx and GDB after about version 4.8, but not other debuggers. GCC sometimes uses a single space as the name instead of omitting the name altogether; apparently that is supported by most debuggers. </P> <P> The <VAR>symbol-descriptor</VAR> following the <SAMP>`:'</SAMP> is an alphabetic character that tells more specifically what kind of symbol the stab represents. If the <VAR>symbol-descriptor</VAR> is omitted, but type information follows, then the stab represents a local variable. For a list of symbol descriptors, see section <A HREF="stabs_9.html#SEC70">Table of Symbol Descriptors</A>. The <SAMP>`c'</SAMP> symbol descriptor is an exception in that it is not followed by type information. See section <A HREF="stabs_3.html#SEC16">Constants</A>. </P> <P> <VAR>type-information</VAR> is either a <VAR>type-number</VAR>, or <SAMP>`<VAR>type-number</VAR>='</SAMP>. A <VAR>type-number</VAR> alone is a type reference, referring directly to a type that has already been defined. </P> <P> The <SAMP>`<VAR>type-number</VAR>='</SAMP> form is a type definition, where the number represents a new type which is about to be defined. The type definition may refer to other types by number, and those type numbers may be followed by <SAMP>`='</SAMP> and nested definitions. Also, the Lucid compiler will repeat <SAMP>`<VAR>type-number</VAR>='</SAMP> more than once if it wants to define several type numbers at once. </P> <P> In a type definition, if the character that follows the equals sign is non-numeric then it is a <VAR>type-descriptor</VAR>, and tells what kind of type is about to be defined. Any other values following the <VAR>type-descriptor</VAR> vary, depending on the <VAR>type-descriptor</VAR>. See section <A HREF="stabs_10.html#SEC71">Table of Type Descriptors</A>, for a list of <VAR>type-descriptor</VAR> values. If a number follows the <SAMP>`='</SAMP> then the number is a <VAR>type-reference</VAR>. For a full description of types, section <A HREF="stabs_5.html#SEC29">Defining Types</A>. </P> <P> A <VAR>type-number</VAR> is often a single number. The GNU and Sun tools additionally permit a <VAR>type-number</VAR> to be a pair (<VAR>file-number</VAR>,<VAR>filetype-number</VAR>) (the parentheses appear in the string, and serve to distinguish the two cases). The <VAR>file-number</VAR> is a number starting with 1 which is incremented for each seperate source file in the compilation (e.g., in C, each header file gets a different number). The <VAR>filetype-number</VAR> is a number starting with 1 which is incremented for each new type defined in the file. (Separating the file number and the type number permits the <CODE>N_BINCL</CODE> optimization to succeed more often; see section <A HREF="stabs_2.html#SEC10">Names of Include Files</A>). </P> <P> There is an AIX extension for type attributes. Following the <SAMP>`='</SAMP> are any number of type attributes. Each one starts with <SAMP>`@'</SAMP> and ends with <SAMP>`;'</SAMP>. Debuggers, including AIX's dbx and GDB 4.10, skip any type attributes they do not recognize. GDB 4.9 and other versions of dbx may not do this. Because of a conflict with C++ (see section <A HREF="stabs_7.html#SEC52">GNU C++ Stabs</A>), new attributes should not be defined which begin with a digit, <SAMP>`('</SAMP>, or <SAMP>`-'</SAMP>; GDB may be unable to distinguish those from the C++ type descriptor <SAMP>`@'</SAMP>. The attributes are: </P> <DL COMPACT> <DT><CODE>a<VAR>boundary</VAR></CODE> <DD> <VAR>boundary</VAR> is an integer specifying the alignment. I assume it applies to all variables of this type. <DT><CODE>p<VAR>integer</VAR></CODE> <DD> Pointer class (for checking). Not sure what this means, or how <VAR>integer</VAR> is interpreted. <DT><CODE>P</CODE> <DD> Indicate this is a packed type, meaning that structure fields or array elements are placed more closely in memory, to save memory at the expense of speed. <DT><CODE>s<VAR>size</VAR></CODE> <DD> Size in bits of a variable of this type. This is fully supported by GDB 4.11 and later. <DT><CODE>S</CODE> <DD> Indicate that this type is a string instead of an array of characters, or a bitstring instead of a set. It doesn't change the layout of the data being represented, but does enable the debugger to know which type it is. </DL> <P> All of this can make the string field quite long. All versions of GDB, and some versions of dbx, can handle arbitrarily long strings. But many versions of dbx (or assemblers or linkers, I'm not sure which) cretinously limit the strings to about 80 characters, so compilers which must work with such systems need to split the <CODE>.stabs</CODE> directive into several <CODE>.stabs</CODE> directives. Each stab duplicates every field except the string field. The string field of every stab except the last is marked as continued with a backslash at the end (in the assembly code this may be written as a double backslash, depending on the assembler). Removing the backslashes and concatenating the string fields of each stab produces the original, long string. Just to be incompatible (or so they don't have to worry about what the assembler does with backslashes), AIX can use <SAMP>`?'</SAMP> instead of backslash. </P> <H2><A NAME="SEC5" HREF="stabs_toc.html#TOC5">A Simple Example in C Source</A></H2> <P> To get the flavor of how stabs describe source information for a C program, let's look at the simple program: </P> <PRE> main() { printf("Hello world"); } </PRE> <P> When compiled with <SAMP>`-g'</SAMP>, the program above yields the following <TT>`.s'</TT> file. Line numbers have been added to make it easier to refer to parts of the <TT>`.s'</TT> file in the description of the stabs that follows. </P> <H2><A NAME="SEC6" HREF="stabs_toc.html#TOC6">The Simple Example at the Assembly Level</A></H2> <P> This simple "hello world" example demonstrates several of the stab types used to describe C language source files. </P> <PRE> 1 gcc2_compiled.: 2 .stabs "/cygint/s1/users/jcm/play/",100,0,0,Ltext0 3 .stabs "hello.c",100,0,0,Ltext0 4 .text 5 Ltext0: 6 .stabs "int:t1=r1;-2147483648;2147483647;",128,0,0,0 7 .stabs "char:t2=r2;0;127;",128,0,0,0 8 .stabs "long int:t3=r1;-2147483648;2147483647;",128,0,0,0 9 .stabs "unsigned int:t4=r1;0;-1;",128,0,0,0 10 .stabs "long unsigned int:t5=r1;0;-1;",128,0,0,0 11 .stabs "short int:t6=r1;-32768;32767;",128,0,0,0 12 .stabs "long long int:t7=r1;0;-1;",128,0,0,0 13 .stabs "short unsigned int:t8=r1;0;65535;",128,0,0,0 14 .stabs "long long unsigned int:t9=r1;0;-1;",128,0,0,0 15 .stabs "signed char:t10=r1;-128;127;",128,0,0,0 16 .stabs "unsigned char:t11=r1;0;255;",128,0,0,0 17 .stabs "float:t12=r1;4;0;",128,0,0,0 18 .stabs "double:t13=r1;8;0;",128,0,0,0 19 .stabs "long double:t14=r1;8;0;",128,0,0,0 20 .stabs "void:t15=15",128,0,0,0 21 .align 4 22 LC0: 23 .ascii "Hello, world!\12\0" 24 .align 4 25 .global _main 26 .proc 1 27 _main: 28 .stabn 68,0,4,LM1 29 LM1: 30 !#PROLOGUE# 0 31 save %sp,-136,%sp 32 !#PROLOGUE# 1 33 call ___main,0 34 nop 35 .stabn 68,0,5,LM2 36 LM2: 37 LBB2: 38 sethi %hi(LC0),%o1 39 or %o1,%lo(LC0),%o0 40 call _printf,0 41 nop 42 .stabn 68,0,6,LM3 43 LM3: 44 LBE2: 45 .stabn 68,0,6,LM4 46 LM4: 47 L1: 48 ret 49 restore 50 .stabs "main:F1",36,0,0,_main 51 .stabn 192,0,0,LBB2 52 .stabn 224,0,0,LBE2 </PRE> <P><HR><P> Go to the first, previous, <A HREF="stabs_2.html">next</A>, <A HREF="stabs_14.html">last</A> section, <A HREF="stabs_toc.html">table of contents</A>. </BODY> </HTML>