Subversion Repositories or1k_old

\input texinfo

@setfilename stabs.info

@c @finalout

@ifinfo

@format

START-INFO-DIR-ENTRY

* Stabs: (stabs).                 The "stabs" debugging information format.

END-INFO-DIR-ENTRY

@end format

@end ifinfo

@ifinfo

This document describes the stabs debugging symbol tables.

Copyright 1992,1993,1994,1995,1997,1998,2000,2001

   Free Software Foundation, Inc.

Contributed by Cygnus Support.  Written by Julia Menapace, Jim Kingdon,

and David MacKenzie.

Permission is granted to copy, distribute and/or modify this document

under the terms of the GNU Free Documentation License, Version 1.1 or

any later version published by the Free Software Foundation; with no

Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,''

and with the Back-Cover Texts as in (a) below.

(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify

this GNU Manual, like GNU software.  Copies published by the Free

Software Foundation raise funds for GNU development.''

@end ifinfo

@setchapternewpage odd

@settitle STABS

@titlepage

@title The ``stabs'' debug format

@author Julia Menapace, Jim Kingdon, David MacKenzie

@author Cygnus Support

@page

@tex

\def\$#1${{#1}}  % Kluge: collect RCS revision info without $...$

\xdef\manvers{\$Revision: 1.2 $}  % For use in headers, footers too

{\parskip=0pt

\hfill Cygnus Support\par

\hfill \manvers\par

\hfill \TeX{}info \texinfoversion\par

}

@end tex

@vskip 0pt plus 1filll

Copyright @copyright{} 1992,1993,1994,1995,1997,1998,2000,2001 Free Software Foundation, Inc.

Contributed by Cygnus Support.

Permission is granted to copy, distribute and/or modify this document

under the terms of the GNU Free Documentation License, Version 1.1 or

any later version published by the Free Software Foundation; with no

Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,''

and with the Back-Cover Texts as in (a) below.

(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify

this GNU Manual, like GNU software.  Copies published by the Free

Software Foundation raise funds for GNU development.''

@end titlepage

@ifinfo

@node Top

@top The "stabs" representation of debugging information

This document describes the stabs debugging format.

@menu

* Overview::                    Overview of stabs

* Program Structure::           Encoding of the structure of the program

* Constants::                   Constants

* Variables::

* Types::                       Type definitions

* Symbol Tables::               Symbol information in symbol tables

* Cplusplus::                   Stabs specific to C++

* Stab Types::                  Symbol types in a.out files

* Symbol Descriptors::          Table of symbol descriptors

* Type Descriptors::            Table of type descriptors

* Expanded Reference::          Reference information by stab type

* Questions::                   Questions and anomalies

* Stab Sections::               In some object file formats, stabs are

                                in sections.

* Symbol Types Index::          Index of symbolic stab symbol type names.

@end menu

@end ifinfo

@c TeX can handle the contents at the start but makeinfo 3.12 can not

@iftex

@contents

@end iftex

@node Overview

@chapter Overview of Stabs

@dfn{Stabs} 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} Pascal

debugger; the format has spread widely since then.

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 (@pxref{Symbol Descriptors}) and type

descriptors (@pxref{Type Descriptors}) 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.

@c FIXME: Need to document all OS9000 stuff in GDB; see all references

@c to os9k_stabs in stabsread.c.

Other sources of information on stabs are @cite{Dbx and Dbxtool

Interfaces}, 2nd edition, by Sun, 1988, and @cite{AIX Version 3.2 Files

Reference}, 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.

@menu

* Flow::                        Overview of debugging information flow

* Stabs Format::                Overview of stab format

* String Field::                The string field

* C Example::                   A simple example in C source

* Assembly Code::               The simple example at the assembly level

@end menu

@node Flow

@section Overview of Debugging Information Flow

The GNU C compiler compiles C source in a @file{.c} file into assembly

language in a @file{.s} file, which the assembler translates into

a @file{.o} file, which the linker combines with other @file{.o} files and

libraries to produce an executable file.

With the @samp{-g} option, GCC puts in the @file{.s} 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.

For some object file formats, the debugging information is encapsulated

in assembler directives known collectively as @dfn{stab} (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.

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

@file{.o} file it is building.  The linker consolidates the @file{.o}

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.

@node Stabs Format

@section Overview of Stab Format

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} (string), @code{.stabn} (number), or @code{.stabd}

(dot).  IBM's XCOFF assembler uses @code{.stabx} (and some other

directives such as @code{.file} and @code{.bi}) instead of

@code{.stabs}, @code{.stabn} or @code{.stabd}.

The overall format of each class of stab is:

@example

.stabs "@var{string}",@var{type},@var{other},@var{desc},@var{value}

.stabn @var{type},@var{other},@var{desc},@var{value}

.stabd @var{type},@var{other},@var{desc}

.stabx "@var{string}",@var{value},@var{type},@var{sdb-type}

@end example

@c what is the correct term for "current file location"?  My AIX

@c assembler manual calls it "the value of the current location counter".

For @code{.stabn} and @code{.stabd}, there is no @var{string} (the

@code{n_strx} field is zero; see @ref{Symbol Tables}).  For

@code{.stabd}, the @var{value} field is implicit and has the value of

the current file location.  For @code{.stabx}, the @var{sdb-type} field

is unused for stabs and can always be set to zero.  The @var{other}

field is almost always unused and can be set to zero.

The number in the @var{type} field gives some basic information about

which type of stab this is (or whether it @emph{is} 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{desc}, or

@var{value} fields present in the stab.  @xref{Stab Types}, for a list

in numeric order of the valid @var{type} field values for stab directives.

@node String Field

@section The String Field

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.

The overall format of the string field for most stab types is:

@example

"@var{name}:@var{symbol-descriptor} @var{type-information}"

@end example

@var{name} is the name of the symbol represented by the stab; it can

contain a pair of colons (@pxref{Nested Symbols}).  @var{name} can be

omitted, which means the stab represents an unnamed object.  For

example, @samp{:t10=*2} defines type 10 as a pointer to type 2, but does

not give the type a name.  Omitting the @var{name} 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.

The @var{symbol-descriptor} following the @samp{:} is an alphabetic

character that tells more specifically what kind of symbol the stab

represents. If the @var{symbol-descriptor} is omitted, but type

information follows, then the stab represents a local variable.  For a

list of symbol descriptors, see @ref{Symbol Descriptors}.  The @samp{c}

symbol descriptor is an exception in that it is not followed by type

information.  @xref{Constants}.

@var{type-information} is either a @var{type-number}, or

@samp{@var{type-number}=}.  A @var{type-number} alone is a type

reference, referring directly to a type that has already been defined.

The @samp{@var{type-number}=} 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{=} and nested definitions.  Also, the Lucid

compiler will repeat @samp{@var{type-number}=} more than once if it

wants to define several type numbers at once.

In a type definition, if the character that follows the equals sign is

non-numeric then it is a @var{type-descriptor}, and tells what kind of

type is about to be defined.  Any other values following the

@var{type-descriptor} vary, depending on the @var{type-descriptor}.

@xref{Type Descriptors}, for a list of @var{type-descriptor} values.  If

a number follows the @samp{=} then the number is a @var{type-reference}.

For a full description of types, @ref{Types}.

A @var{type-number} is often a single number.  The GNU and Sun tools

additionally permit a @var{type-number} to be a pair

(@var{file-number},@var{filetype-number}) (the parentheses appear in the

string, and serve to distinguish the two cases).  The @var{file-number}

is 0 for the base source file, 1 for the first included file, 2 for the

next, and so on.  The @var{filetype-number} 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} optimization to succeed more often; see @ref{Include

Files}).

There is an AIX extension for type attributes.  Following the @samp{=}

are any number of type attributes.  Each one starts with @samp{@@} and

ends with @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++

(@pxref{Cplusplus}), new attributes should not be defined which begin

with a digit, @samp{(}, or @samp{-}; GDB may be unable to distinguish

those from the C++ type descriptor @samp{@@}.  The attributes are:

@table @code

@item a@var{boundary}

@var{boundary} is an integer specifying the alignment.  I assume it

applies to all variables of this type.

@item p@var{integer}

Pointer class (for checking).  Not sure what this means, or how

@var{integer} is interpreted.

@item P

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.

@item s@var{size}

Size in bits of a variable of this type.  This is fully supported by GDB

4.11 and later.

@item S

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.

@item V

Indicate that this type is a vector instead of an array.  The only

major difference between vectors and arrays is that vectors are

passed by value instead of by reference (vector coprocessor extension).

@end table

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} directive

into several @code{.stabs} 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{?} instead of backslash.

@node C Example

@section A Simple Example in C Source

To get the flavor of how stabs describe source information for a C

program, let's look at the simple program:

@example

main()

@{

        printf("Hello world");

@}

@end example

When compiled with @samp{-g}, the program above yields the following

@file{.s} file.  Line numbers have been added to make it easier to refer

to parts of the @file{.s} file in the description of the stabs that

follows.

@node Assembly Code

@section The Simple Example at the Assembly Level

This simple ``hello world'' example demonstrates several of the stab

types used to describe C language source files.

@example

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

@end example

@node Program Structure

@chapter Encoding the Structure of the Program

The elements of the program structure that stabs encode include the name

of the main function, the names of the source and include files, the

line numbers, procedure names and types, and the beginnings and ends of

blocks of code.

@menu

* Main Program::                Indicate what the main program is

* Source Files::                The path and name of the source file

* Include Files::               Names of include files

* Line Numbers::

* Procedures::

* Nested Procedures::

* Block Structure::

* Alternate Entry Points::      Entering procedures except at the beginning.

@end menu

@node Main Program

@section Main Program

@findex N_MAIN

Most languages allow the main program to have any name.  The

@code{N_MAIN} stab type tells the debugger the name that is used in this

program.  Only the string field is significant; it is the name of

a function which is the main program.  Most C compilers do not use this

stab (they expect the debugger to assume that the name is @code{main}),

but some C compilers emit an @code{N_MAIN} stab for the @code{main}

function.  I'm not sure how XCOFF handles this.

@node Source Files

@section Paths and Names of the Source Files

@findex N_SO

Before any other stabs occur, there must be a stab specifying the source

file.  This information is contained in a symbol of stab type

@code{N_SO}; the string field contains the name of the file.  The

value of the symbol is the start address of the portion of the

text section corresponding to that file.

With the Sun Solaris2 compiler, the desc field contains a

source-language code.

@c Do the debuggers use it?  What are the codes? -djm

Some compilers (for example, GCC2 and SunOS4 @file{/bin/cc}) also

include the directory in which the source was compiled, in a second

@code{N_SO} symbol preceding the one containing the file name.  This

symbol can be distinguished by the fact that it ends in a slash.  Code

from the @code{cfront} C++ compiler can have additional @code{N_SO} symbols for

nonexistent source files after the @code{N_SO} for the real source file;

these are believed to contain no useful information.

For example:

@example

.stabs "/cygint/s1/users/jcm/play/",100,0,0,Ltext0     # @r{100 is N_SO}

.stabs "hello.c",100,0,0,Ltext0

        .text

Ltext0:

@end example

@findex C_FILE

Instead of @code{N_SO} symbols, XCOFF uses a @code{.file} assembler

directive which assembles to a @code{C_FILE} symbol; explaining this in

detail is outside the scope of this document.

@c FIXME: Exactly when should the empty N_SO be used?  Why?

If it is useful to indicate the end of a source file, this is done with

an @code{N_SO} symbol with an empty string for the name.  The value is

the address of the end of the text section for the file.  For some

systems, there is no indication of the end of a source file, and you

just need to figure it ended when you see an @code{N_SO} for a different

source file, or a symbol ending in @code{.o} (which at least some

linkers insert to mark the start of a new @code{.o} file).

@node Include Files

@section Names of Include Files

There are several schemes for dealing with include files: the

traditional @code{N_SOL} approach, Sun's @code{N_BINCL} approach, and the

XCOFF @code{C_BINCL} approach (which despite the similar name has little in

common with @code{N_BINCL}).

@findex N_SOL

An @code{N_SOL} symbol specifies which include file subsequent symbols

refer to.  The string field is the name of the file and the value is the

text address corresponding to the end of the previous include file and

the start of this one.  To specify the main source file again, use an

@code{N_SOL} symbol with the name of the main source file.

@findex N_BINCL

@findex N_EINCL

@findex N_EXCL

The @code{N_BINCL} approach works as follows.  An @code{N_BINCL} symbol

specifies the start of an include file.  In an object file, only the

string is significant; the linker puts data into some of the other

fields.  The end of the include file is marked by an @code{N_EINCL}

symbol (which has no string field).  In an object file, there is no

significant data in the @code{N_EINCL} symbol.  @code{N_BINCL} and

@code{N_EINCL} can be nested.

If the linker detects that two source files have identical stabs between

an @code{N_BINCL} and @code{N_EINCL} pair (as will generally be the case

for a header file), then it only puts out the stabs once.  Each

additional occurrence is replaced by an @code{N_EXCL} symbol.  I believe

the GNU linker and the Sun (both SunOS4 and Solaris) linker are the only

ones which supports this feature.

A linker which supports this feature will set the value of a

@code{N_BINCL} symbol to the total of all the characters in the stabs

strings included in the header file, omitting any file numbers.  The

value of an @code{N_EXCL} symbol is the same as the value of the

@code{N_BINCL} symbol it replaces.  This information can be used to

match up @code{N_EXCL} and @code{N_BINCL} symbols which have the same

filename.  The @code{N_EINCL} value, and the values of the other and

description fields for all three, appear to always be zero.

@findex C_BINCL

@findex C_EINCL

For the start of an include file in XCOFF, use the @file{.bi} assembler

directive, which generates a @code{C_BINCL} symbol.  A @file{.ei}

directive, which generates a @code{C_EINCL} symbol, denotes the end of

the include file.  Both directives are followed by the name of the

source file in quotes, which becomes the string for the symbol.

The value of each symbol, produced automatically by the assembler

and linker, is the offset into the executable of the beginning

(inclusive, as you'd expect) or end (inclusive, as you would not expect)

of the portion of the COFF line table that corresponds to this include

file.  @code{C_BINCL} and @code{C_EINCL} do not nest.

@node Line Numbers

@section Line Numbers

@findex N_SLINE

An @code{N_SLINE} symbol represents the start of a source line.  The

desc field contains the line number and the value contains the code

address for the start of that source line.  On most machines the address

is absolute; for stabs in sections (@pxref{Stab Sections}), it is

relative to the function in which the @code{N_SLINE} symbol occurs.

@findex N_DSLINE

@findex N_BSLINE

GNU documents @code{N_DSLINE} and @code{N_BSLINE} symbols for line

numbers in the data or bss segments, respectively.  They are identical

to @code{N_SLINE} but are relocated differently by the linker.  They

were intended to be used to describe the source location of a variable

declaration, but I believe that GCC2 actually puts the line number in

the desc field of the stab for the variable itself.  GDB has been

ignoring these symbols (unless they contain a string field) since

at least GDB 3.5.

For single source lines that generate discontiguous code, such as flow

of control statements, there may be more than one line number entry for

the same source line.  In this case there is a line number entry at the

start of each code range, each with the same line number.

XCOFF does not use stabs for line numbers.  Instead, it uses COFF line

numbers (which are outside the scope of this document).  Standard COFF

line numbers cannot deal with include files, but in XCOFF this is fixed

with the @code{C_BINCL} method of marking include files (@pxref{Include

Files}).

@node Procedures

@section Procedures

@findex N_FUN, for functions

@findex N_FNAME

@findex N_STSYM, for functions (Sun acc)

@findex N_GSYM, for functions (Sun acc)

All of the following stabs normally use the @code{N_FUN} symbol type.

However, Sun's @code{acc} compiler on SunOS4 uses @code{N_GSYM} and

@code{N_STSYM}, which means that the value of the stab for the function

is useless and the debugger must get the address of the function from

the non-stab symbols instead.  On systems where non-stab symbols have

leading underscores, the stabs will lack underscores and the debugger

needs to know about the leading underscore to match up the stab and the

non-stab symbol.  BSD Fortran is said to use @code{N_FNAME} with the

same restriction; the value of the symbol is not useful (I'm not sure it

really does use this, because GDB doesn't handle this and no one has

complained).

@findex C_FUN

A function is represented by an @samp{F} symbol descriptor for a global

(extern) function, and @samp{f} for a static (local) function.  For

a.out, the value of the symbol is the address of the start of the

function; it is already relocated.  For stabs in ELF, the SunPRO

compiler version 2.0.1 and GCC put out an address which gets relocated

by the linker.  In a future release SunPRO is planning to put out zero,

in which case the address can be found from the ELF (non-stab) symbol.

Because looking things up in the ELF symbols would probably be slow, I'm

not sure how to find which symbol of that name is the right one, and

this doesn't provide any way to deal with nested functions, it would

probably be better to make the value of the stab an address relative to

the start of the file, or just absolute.  See @ref{ELF Linker

Relocation} for more information on linker relocation of stabs in ELF

files.  For XCOFF, the stab uses the @code{C_FUN} storage class and the

value of the stab is meaningless; the address of the function can be

found from the csect symbol (XTY_LD/XMC_PR).

The type information of the stab represents the return type of the

function; thus @samp{foo:f5} means that foo is a function returning type

5.  There is no need to try to get the line number of the start of the

function from the stab for the function; it is in the next

@code{N_SLINE} symbol.

@c FIXME: verify whether the "I suspect" below is true or not.

Some compilers (such as Sun's Solaris compiler) support an extension for

specifying the types of the arguments.  I suspect this extension is not

used for old (non-prototyped) function definitions in C.  If the

extension is in use, the type information of the stab for the function

is followed by type information for each argument, with each argument

preceded by @samp{;}.  An argument type of 0 means that additional

arguments are being passed, whose types and number may vary (@samp{...}

in ANSI C).  GDB has tolerated this extension (parsed the syntax, if not

necessarily used the information) since at least version 4.8; I don't

know whether all versions of dbx tolerate it.  The argument types given

here are not redundant with the symbols for the formal parameters

(@pxref{Parameters}); they are the types of the arguments as they are

passed, before any conversions might take place.  For example, if a C

function which is declared without a prototype takes a @code{float}

argument, the value is passed as a @code{double} but then converted to a

@code{float}.  Debuggers need to use the types given in the arguments

when printing values, but when calling the function they need to use the

types given in the symbol defining the function.

If the return type and types of arguments of a function which is defined

in another source file are specified (i.e., a function prototype in ANSI

C), traditionally compilers emit no stab; the only way for the debugger

to find the information is if the source file where the function is

defined was also compiled with debugging symbols.  As an extension the

Solaris compiler uses symbol descriptor @samp{P} followed by the return

type of the function, followed by the arguments, each preceded by

@samp{;}, as in a stab with symbol descriptor @samp{f} or @samp{F}.

This use of symbol descriptor @samp{P} can be distinguished from its use

for register parameters (@pxref{Register Parameters}) by the fact that it has

symbol type @code{N_FUN}.

The AIX documentation also defines symbol descriptor @samp{J} as an

internal function.  I assume this means a function nested within another

function.  It also says symbol descriptor @samp{m} is a module in

Modula-2 or extended Pascal.

Procedures (functions which do not return values) are represented as

functions returning the @code{void} type in C.  I don't see why this couldn't

be used for all languages (inventing a @code{void} type for this purpose if

necessary), but the AIX documentation defines @samp{I}, @samp{P}, and

@samp{Q} for internal, global, and static procedures, respectively.

These symbol descriptors are unusual in that they are not followed by

type information.

The following example shows a stab for a function @code{main} which

returns type number @code{1}.  The @code{_main} specified for the value

is a reference to an assembler label which is used to fill in the start

address of the function.

@example

.stabs "main:F1",36,0,0,_main      # @r{36 is N_FUN}

@end example

The stab representing a procedure is located immediately following the

code of the procedure.  This stab is in turn directly followed by a

group of other stabs describing elements of the procedure.  These other

stabs describe the procedure's parameters, its block local variables, and

its block structure.

If functions can appear in different sections, then the debugger may not

be able to find the end of a function.  Recent versions of GCC will mark

the end of a function with an @code{N_FUN} symbol with an empty string

for the name.  The value is the address of the end of the current

function.  Without such a symbol, there is no indication of the address

of the end of a function, and you must assume that it ended at the

starting address of the next function or at the end of the text section

for the program.

@node Nested Procedures

@section Nested Procedures

For any of the symbol descriptors representing procedures, after the

symbol descriptor and the type information is optionally a scope

specifier.  This consists of a comma, the name of the procedure, another

comma, and the name of the enclosing procedure.  The first name is local

to the scope specified, and seems to be redundant with the name of the

symbol (before the @samp{:}).  This feature is used by GCC, and

presumably Pascal, Modula-2, etc., compilers, for nested functions.

If procedures are nested more than one level deep, only the immediately

containing scope is specified.  For example, this code:

@example

int

foo (int x)

@{

  int bar (int y)

    @{

      int baz (int z)

        @{

          return x + y + z;

        @}

      return baz (x + 2 * y);

    @}

  return x + bar (3 * x);

@}

@end example

@noindent

produces the stabs:

@example

.stabs "baz:f1,baz,bar",36,0,0,_baz.15         # @r{36 is N_FUN}

.stabs "bar:f1,bar,foo",36,0,0,_bar.12

.stabs "foo:F1",36,0,0,_foo

@end example

@node Block Structure

@section Block Structure

@findex N_LBRAC

@findex N_RBRAC

@c For GCC 2.5.8 or so stabs-in-coff, these are absolute instead of

@c function relative (as documented below).  But GDB has never been able

@c to deal with that (it had wanted them to be relative to the file, but

@c I just fixed that (between GDB 4.12 and 4.13)), so it is function

@c relative just like ELF and SOM and the below documentation.

The program's block structure is represented by the @code{N_LBRAC} (left

brace) and the @code{N_RBRAC} (right brace) stab types.  The variables

defined inside a block precede the @code{N_LBRAC} symbol for most

compilers, including GCC.  Other compilers, such as the Convex, Acorn

RISC machine, and Sun @code{acc} compilers, put the variables after the

@code{N_LBRAC} symbol.  The values of the @code{N_LBRAC} and

@code{N_RBRAC} symbols are the start and end addresses of the code of

the block, respectively.  For most machines, they are relative to the

starting address of this source file.  For the Gould NP1, they are

absolute.  For stabs in sections (@pxref{Stab Sections}), they are

relative to the function in which they occur.

The @code{N_LBRAC} and @code{N_RBRAC} stabs that describe the block

scope of a procedure are located after the @code{N_FUN} stab that

represents the procedure itself.

Sun documents the desc field of @code{N_LBRAC} and

@code{N_RBRAC} symbols as containing the nesting level of the block.

However, dbx seems to not care, and GCC always sets desc to

zero.

@findex .bb

@findex .be

@findex C_BLOCK

For XCOFF, block scope is indicated with @code{C_BLOCK} symbols.  If the

name of the symbol is @samp{.bb}, then it is the beginning of the block;

if the name of the symbol is @samp{.be}; it is the end of the block.

@node Alternate Entry Points

@section Alternate Entry Points

@findex N_ENTRY

@findex C_ENTRY

Some languages, like Fortran, have the ability to enter procedures at

some place other than the beginning.  One can declare an alternate entry

point.  The @code{N_ENTRY} stab is for this; however, the Sun FORTRAN

compiler doesn't use it.  According to AIX documentation, only the name

of a @code{C_ENTRY} stab is significant; the address of the alternate

entry point comes from the corresponding external symbol.  A previous

revision of this document said that the value of an @code{N_ENTRY} stab

was the address of the alternate entry point, but I don't know the

source for that information.

@node Constants

@chapter Constants

The @samp{c} symbol descriptor indicates that this stab represents a

constant.  This symbol descriptor is an exception to the general rule

that symbol descriptors are followed by type information.  Instead, it

is followed by @samp{=} and one of the following:

@table @code

@item b @var{value}

Boolean constant.  @var{value} is a numeric value; I assume it is 0 for

false or 1 for true.

@item c @var{value}

Character constant.  @var{value} is the numeric value of the constant.

@item e @var{type-information} , @var{value}

Constant whose value can be represented as integral.

@var{type-information} is the type of the constant, as it would appear

after a symbol descriptor (@pxref{String Field}).  @var{value} is the

numeric value of the constant.  GDB 4.9 does not actually get the right

value if @var{value} does not fit in a host @code{int}, but it does not

do anything violent, and future debuggers could be extended to accept

integers of any size (whether unsigned or not).  This constant type is

usually documented as being only for enumeration constants, but GDB has

never imposed that restriction; I don't know about other debuggers.

@item i @var{value}

Integer constant.  @var{value} is the numeric value.  The type is some

sort of generic integer type (for GDB, a host @code{int}); to specify

the type explicitly, use @samp{e} instead.

@item r @var{value}

Real constant.  @var{value} is the real value, which can be @samp{INF}

(optionally preceded by a sign) for infinity, @samp{QNAN} for a quiet

NaN (not-a-number), or @samp{SNAN} for a signalling NaN.  If it is a

normal number the format is that accepted by the C library function

@code{atof}.

@item s @var{string}

String constant.  @var{string} is a string enclosed in either @samp{'}

(in which case @samp{'} characters within the string are represented as

@samp{\'} or @samp{"} (in which case @samp{"} characters within the

string are represented as @samp{\"}).

@item S @var{type-information} , @var{elements} , @var{bits} , @var{pattern}

Set constant.  @var{type-information} is the type of the constant, as it

would appear after a symbol descriptor (@pxref{String Field}).

@var{elements} is the number of elements in the set (does this means

how many bits of @var{pattern} are actually used, which would be

redundant with the type, or perhaps the number of bits set in

@var{pattern}?  I don't get it), @var{bits} is the number of bits in the

constant (meaning it specifies the length of @var{pattern}, I think),

and @var{pattern} is a hexadecimal representation of the set.  AIX

documentation refers to a limit of 32 bytes, but I see no reason why

this limit should exist.  This form could probably be used for arbitrary

constants, not just sets; the only catch is that @var{pattern} should be

understood to be target, not host, byte order and format.

@end table

The boolean, character, string, and set constants are not supported by

GDB 4.9, but it ignores them.  GDB 4.8 and earlier gave an error

message and refused to read symbols from the file containing the

constants.

The above information is followed by @samp{;}.

@node Variables

@chapter Variables

Different types of stabs describe the various ways that variables can be

allocated: on the stack, globally, in registers, in common blocks,

statically, or as arguments to a function.

@menu

* Stack Variables::             Variables allocated on the stack.

* Global Variables::            Variables used by more than one source file.

* Register Variables::          Variables in registers.

* Common Blocks::               Variables statically allocated together.

* Statics::                     Variables local to one source file.

* Based Variables::             Fortran pointer based variables.

* Parameters::                  Variables for arguments to functions.

@end menu

@node Stack Variables

@section Automatic Variables Allocated on the Stack

If a variable's scope is local to a function and its lifetime is only as

long as that function executes (C calls such variables

@dfn{automatic}), it can be allocated in a register (@pxref{Register

Variables}) or on the stack.

@findex N_LSYM, for stack variables

@findex C_LSYM

Each variable allocated on the stack has a stab with the symbol

descriptor omitted.  Since type information should begin with a digit,

@samp{-}, or @samp{(}, only those characters precluded from being used

for symbol descriptors.  However, the Acorn RISC machine (ARM) is said

to get this wrong: it puts out a mere type definition here, without the

preceding @samp{@var{type-number}=}.  This is a bad idea; there is no

guarantee that type descriptors are distinct from symbol descriptors.

Stabs for stack variables use the @code{N_LSYM} stab type, or

@code{C_LSYM} for XCOFF.

The value of the stab is the offset of the variable within the

local variables.  On most machines this is an offset from the frame

pointer and is negative.  The location of the stab specifies which block

it is defined in; see @ref{Block Structure}.

For example, the following C code:

@example

int

main ()

@{

  int x;

@}

@end example

produces the following stabs:

@example

.stabs "main:F1",36,0,0,_main   # @r{36 is N_FUN}

.stabs "x:1",128,0,0,-12        # @r{128 is N_LSYM}

.stabn 192,0,0,LBB2             # @r{192 is N_LBRAC}

.stabn 224,0,0,LBE2             # @r{224 is N_RBRAC}

@end example

See @ref{Procedures} for more information on the @code{N_FUN} stab, and

@ref{Block Structure} for more information on the @code{N_LBRAC} and

@code{N_RBRAC} stabs.

@node Global Variables

@section Global Variables

@findex N_GSYM

@findex C_GSYM

@c FIXME: verify for sure that it really is C_GSYM on XCOFF

A variable whose scope is not specific to just one source file is

represented by the @samp{G} symbol descriptor.  These stabs use the

@code{N_GSYM} stab type (C_GSYM for XCOFF).  The type information for

the stab (@pxref{String Field}) gives the type of the variable.

For example, the following source code:

@example

char g_foo = 'c';

@end example

@noindent

yields the following assembly code:

@example

.stabs "g_foo:G2",32,0,0,0     # @r{32 is N_GSYM}

     .global _g_foo

     .data

_g_foo:

     .byte 99

@end example

The address of the variable represented by the @code{N_GSYM} is not

contained in the @code{N_GSYM} stab.  The debugger gets this information

from the external symbol for the global variable.  In the example above,

the @code{.global _g_foo} and @code{_g_foo:} lines tell the assembler to

produce an external symbol.

Some compilers, like GCC, output @code{N_GSYM} stabs only once, where

the variable is defined.  Other compilers, like SunOS4 /bin/cc, output a

@code{N_GSYM} stab for each compilation unit which references the

variable.

@node Register Variables

@section Register Variables

@findex N_RSYM

@findex C_RSYM

@c According to an old version of this manual, AIX uses C_RPSYM instead

@c of C_RSYM.  I am skeptical; this should be verified.

Register variables have their own stab type, @code{N_RSYM}

(@code{C_RSYM} for XCOFF), and their own symbol descriptor, @samp{r}.

The stab's value is the number of the register where the variable data

will be stored.