\input texinfo
@setfilename stabs.info
+@setchapternewpage odd
+@settitle STABS
@c @finalout
@c This is a dir.info fragment to support semi-automated addition of
@c manuals to an info tree.
-@dircategory Programming & development tools.
+@dircategory Software development
@direntry
* Stabs: (stabs). The "stabs" debugging information format.
@end direntry
-@ifinfo
-This document describes the stabs debugging symbol tables.
-
-Copyright 1992,1993,1994,1995,1997,1998,2000,2001
- Free Software Foundation, Inc.
+@copying
+Copyright @copyright{} 1992-2013 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
+under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
Texts. A copy of the license is included in the section entitled ``GNU
Free Documentation License''.
-@end ifinfo
+@end copying
+
+@ifnottex
+This document describes the stabs debugging symbol tables.
+
+@insertcopying
+@end ifnottex
-@setchapternewpage odd
-@settitle STABS
@titlepage
@title The ``stabs'' debug format
@author Julia Menapace, Jim Kingdon, David MacKenzie
@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 no Front-Cover Texts, and with no Back-Cover
-Texts. A copy of the license is included in the section entitled ``GNU
-Free Documentation License''.
+@insertcopying
@end titlepage
-@ifinfo
+@ifnottex
@node Top
@top The "stabs" representation of debugging information
* Constants:: Constants
* Variables::
* Types:: Type definitions
+* Macro define and undefine:: Representation of #define and #undef
* Symbol Tables:: Symbol information in symbol tables
* Cplusplus:: Stabs specific to C++
* Stab Types:: Symbol types in a.out files
* 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.
* GNU Free Documentation License:: The license for this documentation
+* Symbol Types Index:: Index of symbolic stab symbol type names.
@end menu
-@end ifinfo
+@end ifnottex
-@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
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 use the desc field to indicate the language of the
+source file. Sun's compilers started this usage, and the first
+constants are derived from their documentation. Languages added
+by gcc/gdb start at 0x32 to avoid conflict with languages Sun may
+add in the future. A desc field with a value 0 indicates that no
+language has been specified via this mechanism.
+
+@table @asis
+@item @code{N_SO_AS} (0x1)
+Assembly language
+@item @code{N_SO_C} (0x2)
+K&R traditional C
+@item @code{N_SO_ANSI_C} (0x3)
+ANSI C
+@item @code{N_SO_CC} (0x4)
+C++
+@item @code{N_SO_FORTRAN} (0x5)
+Fortran
+@item @code{N_SO_PASCAL} (0x6)
+Pascal
+@item @code{N_SO_FORTRAN90} (0x7)
+Fortran90
+@item @code{N_SO_OBJC} (0x32)
+Objective-C
+@item @code{N_SO_OBJCPLUS} (0x33)
+Objective-C++
+@end table
Some compilers (for example, GCC2 and SunOS4 @file{/bin/cc}) also
include the directory in which the source was compiled, in a second
plans to have the linker stop relocating stabs; I suspect that their the
debugger gets the address from the corresponding ELF (not stab) symbol.
I'm not sure how to find which symbol of that name is the right one.
-The clean way to do all this would be to have a the value of a symbol
+The clean way to do all this would be to have the value of a symbol
descriptor @samp{S} symbol be an offset relative to the start of the
file, just like everything else, but that introduces obvious
compatibility problems. For more information on linker stab relocation,
The variable defines a new type, 24, which is a pointer to another new
type, 25, which is a function returning @code{int}.
+@node Macro define and undefine
+@chapter Representation of #define and #undef
+
+This section describes the stabs support for macro define and undefine
+information, supported on some systems. (e.g., with @option{-g3}
+@option{-gstabs} when using GCC).
+
+A @code{#define @var{macro-name} @var{macro-body}} is represented with
+an @code{N_MAC_DEFINE} stab with a string field of
+@code{@var{macro-name} @var{macro-body}}.
+@findex N_MAC_DEFINE
+
+An @code{#undef @var{macro-name}} is represented with an
+@code{N_MAC_UNDEF} stabs with a string field of simply
+@code{@var{macro-name}}.
+@findex N_MAC_UNDEF
+
+For both @code{N_MAC_DEFINE} and @code{N_MAC_UNDEF}, the desc field is
+the line number within the file where the corresponding @code{#define}
+or @code{#undef} occurred.
+
+For example, the following C code:
+
+@example
+ #define NONE 42
+ #define TWO(a, b) (a + (a) + 2 * b)
+ #define ONE(c) (c + 19)
+
+ main(int argc, char *argv[])
+ @{
+ func(NONE, TWO(10, 11));
+ func(NONE, ONE(23));
+
+ #undef ONE
+ #define ONE(c) (c + 23)
+
+ func(NONE, ONE(-23));
+
+ return (0);
+ @}
+
+ int global;
+
+ func(int arg1, int arg2)
+ @{
+ global = arg1 + arg2;
+ @}
+@end example
+
+@noindent
+produces the following stabs (as well as many others):
+
+@example
+ .stabs "NONE 42",54,0,1,0
+ .stabs "TWO(a,b) (a + (a) + 2 * b)",54,0,2,0
+ .stabs "ONE(c) (c + 19)",54,0,3,0
+ .stabs "ONE",58,0,10,0
+ .stabs "ONE(c) (c + 23)",54,0,11,0
+@end example
+
+@noindent
+NOTE: In the above example, @code{54} is @code{N_MAC_DEFINE} and
+@code{58} is @code{N_MAC_UNDEF}.
+
@node Symbol Tables
@chapter Symbol Information in Symbol Tables
@node Member Type Descriptor
@section The @samp{@@} Type Descriptor
-The @samp{@@} type descriptor is used together with the @samp{*} type
-descriptor for a pointer-to-non-static-member-data type. It is followed
+The @samp{@@} type descriptor is used for a
+pointer-to-non-static-member-data type. It is followed
by type information for the class (or union), a comma, and type
information for the member data.
generates the following stab:
@smallexample
-.stabs "int_in_a:t20=*21=@@19,1",128,0,0,0
+.stabs "int_in_a:t20=21=@@19,1",128,0,0,0
@end smallexample
Note that there is a conflict between this and type attributes
@item 0x34 N_NOMAP
No DST map; see @ref{N_NOMAP}.
+@item 0x36 N_MAC_DEFINE
+Name and body of a @code{#define}d macro; see @ref{Macro define and undefine}.
+
@c FIXME: describe this solaris feature in the body of the text (see
@c comments in include/aout/stab.def).
@item 0x38 N_OBJ
Object file (Solaris2).
+@item 0x3a N_MAC_UNDEF
+Name of an @code{#undef}ed macro; see @ref{Macro define and undefine}.
+
@c See include/aout/stab.def for (a little) more info.
@item 0x3c N_OPT
Debugger options (Solaris2).
solves the problem of having to associate the ELF and stab symbols.
However, no one has yet designed or implemented such a scheme.
+@node GNU Free Documentation License
+@appendix GNU Free Documentation License
@include fdl.texi
@node Symbol Types Index
@printindex fn
-@c TeX can handle the contents at the start but makeinfo 3.12 can not
-@ifinfo
-@contents
-@end ifinfo
-@ifhtml
-@contents
-@end ifhtml
-
@bye