A few "See Section" things were not proper \refersec, fixed thouse.
A few instances of "something" were present and those are now
in latex form ``something'' . Except in examples, where "" is
fine as is.
\textbf{Section Group Names}
-Section groups must have a section group name. For the subsequent C++ example, a name like
+Section groups must have a section group name. For the subsequent
+\addtoindex{C++} example, a name like
<producer-prefix>.<file-designator>.<gid-number>
declarations is a good candidate to be represented using
\livelink{chap:DWTAGcompileunit}{DW\-\_TAG\-\_compile\-\_unit}.
However, an \#include appearing inside
-a C++ namespace declaration or a function, for example, is
+a \addtoindex{C++} namespace declaration or a function, for example, is
not a good candidate because the entities included are not
necessarily file level entities.
\subsubsection{C++ Example}
-The C++ source in
+The addtoindex{C++} source in
Section \refersec{app:duplicateeliminationexample1csource}
is used to illustrate the DWARF
representation intended to allow duplicate elimination.
This example uses \livelink{chap:DWTAGcompileunit}{DW\-\_TAG\-\_compile\-\_unit} for the section group,
implying that the contents of the compilation unit are
-globally visible (in accordance with C++ language rules).
+globally visible (in accordance with
+\addtoindex{C++} language rules).
\livelink{chap:DWTAGpartialunit}{DW\-\_TAG\-\_partial\-\_unit} is not needed for the same reason.
\subsubsection{Fortran Example}
\subsubsection{C Example}
-The C++ example in this Section might appear to be equally
-valid as a C example. However, it is prudent to include
-a \livelink{chap:DWTAGimportedunit}{DW\-\_TAG\-\_imported\-\_unit} in the primary unit (see Figure 84)
+The \addtoindex{C++} example in this Section might appear to be equally
+valid as a \addtoindex{C} example. However, it is prudent to include
+a \livelink{chap:DWTAGimportedunit}{DW\-\_TAG\-\_imported\-\_unit}
+in the primary unit
+(see Figure \refersec{app:duplicateeliminationexample1primarycompilationunit})
with an \livelink{chap:DWATimport}{DW\-\_AT\-\_import} attribute that refers to the proper unit
in the section group.
-\textit{The C rules for consistency of global (file scope) symbols
+\textit{The \addtoindex{C} rules for consistency of global (file scope) symbols
across compilations are less strict than for C++; inclusion
of the import unit attribute assures that the declarations of
the proper section group are considered before declarations
\subsection{Signature Computation Example}
\label{app:signaturecomputationexample}
-As an example, consider a C++ header file
+As an example, consider a \addtoindex{C++} header file
containing the type definitions shown
in Section \refersec{app:typesignatureexamplescsource}.
\subsection{\#include compression}
\label{app:includecompression}
-C++ has a much greater problem than C with the number and
+\addtoindex{C++} has a much greater
+problem than
+\addtoindex{C} with the number and
size of the headers included and the amount of data in each,
-but even with C there is substantial header file information
+but even with \addtoindex{C}
+there is substantial header file information
duplication.
A reasonable approach is to put each header file in its own
is the offset in bytes of the beginning of the scope for the
object from the low pc value of the debugging information
entry that defines its scope. If the containing scope
-is non-contiguous (see Section 2.17.3), the value of this
+is non-contiguous
+(see \refersec{chap:noncontiguousaddressranges})
+the value of this
attribute is the offset in bytes of the beginning of the scope
for the object from the beginning of the first range list entry
that is not a base selection entry or an end of list entry.
\item Otherwise, the scope of the object is specified using
a value of class \livelink{chap:rangelistptr}{rangelistptr}. This value indicates the
-beginning of a range list (see Section 2.17.3).
+beginning of a range list
+(see \refersec{chap:noncontiguousaddressranges}).
\end{enumerate}
an object may not require its own range list even when the
containing scope is non\dash contiguous.}
-\item A \livelink{chap:DWATendianity}{DW\-\_AT\-\_endianity} attribute, whose value is a constant
+\item A \livelink{chap:DWATendianity}{DW\-\_AT\-\_endianity} attribute,
+whose value
\hypertarget{chap:DWATendianityendianityofdata}
-that specifies the endianity of the object. The value of
+is a constant
+\addtoindexx{endianity attribute}
+that
+\addtoindexx{big-endian encoding|see{endianity attribute}}
+specifies
+the endianity of the object. The value of
this attribute specifies an ABI\dash defined byte ordering for
the value of the object. If omitted, the default endianity
of data for the given type is assumed. The set of values
The Pascal source in
Figure \refersec{fig:packedrecordexamplesourcefragment}
-is used to illustrate the representation of packed unaligned bit
-fields.
+is used to illustrate the representation of packed unaligned
+\addtoindex{bit fields}.
\begin{figure}[here]
\begin{lstlisting}
TYPE T : PACKED RECORD ! bit size is 2
\livelink{chap:DWATlowerbound}{DW\-\_AT\-\_lower\-\_bound}(0)
\livelink{chap:DWATupperbound}{DW\-\_AT\-\_upper\-\_bound}(1)
\livelink{chap:DWATbitstride}{DW\-\_AT\-\_bit\-\_stride}(2)
- \livelink{chap:DWATbitsize}{DW\-\_AT\-\_bit\-\_size}(4)
+ \livelink{chap:DWATbitsize}{DW\-\_AT\-\_bit\-\_size}(4) \addtoindexx{bit size attribute}
23\$: \livelink{chap:DWTAGstructuretype}{DW\-\_TAG\-\_structure\-\_type} ! anonymous type for V
- \livelink{chap:DWATbitsize}{DW\-\_AT\-\_bit\-\_size}(39)
+ \livelink{chap:DWATbitsize}{DW\-\_AT\-\_bit\-\_size}(39) \addtoindexx{bit size attribute}
\livelink{chap:DWTAGmember}{DW\-\_TAG\-\_member}
\livelink{chap:DWATname}{DW\-\_AT\-\_name}("F1")
\livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to 10\$)
\livelink{chap:DWATname}{DW\-\_AT\-\_name}("F7")
\livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to 20\$) ! type T
\livelink{chap:DWATdatabitoffset}{DW\-\_AT\-\_data\-\_bit\-\_offset}(37)
- \livelink{chap:DWATbitsize}{DW\-\_AT\-\_bit\-\_size}(2) ! may be omitted
+ \livelink{chap:DWATbitsize}{DW\-\_AT\-\_bit\-\_size}(2) \addtoindexx{bit size attribute}! may be omitted
\livelink{chap:DWTAGvariable}{DW\-\_TAG\-\_variable}
\livelink{chap:DWATname}{DW\-\_AT\-\_name}("V")
\livelink{chap:DWATtype}{DW\-\_AT\-\_type}(reference to 23\$)
\\
\livetargi{chap:constant}{constant}{constant class}
&One, two, four or eight bytes of uninterpreted data, or data
-encoded in the variable length format known as LEB128 (see
-Section 7.6.).
+encoded in the variable length format known as LEB128
+(see Section \refersec{datarep:variablelengthdata}).
\textit{Most constant values are integers of one kind or
another (codes, offsets, counts, and so on); these are
by flattening it in prefix order.
Each debugging information
entry is defined either to have child entries or not to have
-child entries (see Section 7.5.3).
+child entries (see Section \refersec{datarep:abbreviationstables}).
If an entry is defined not
to have children, the next physically succeeding entry is a
sibling.
operation uses the main executable's thread\dash local storage
\nolink{block}; if the expression belongs to a shared library's
DWARF info, then it uses that shared library's thread\dash local
-storage \nolink{block}. Some implementations of C and C++ support a
+storage \nolink{block}. Some implementations of
+\addtoindex{C} and \addtoindex{C++} support a
\_\_thread storage class. Variables with this storage class
have distinct values and addresses in distinct threads, much
as automatic variables have distinct values and addresses in
\hypertarget{chap:DWATdeclarationincompletenondefiningorseparateentitydeclaration}
an expression correctly.
-\textit{As an example, consider the following fragment of C code:}
+\textit{As an example, consider the following fragment of \addtoindex{C} code:}
\begin{lstlisting}
void myfunc()
\end{lstlisting}
-\textit{C scoping rules require that the
+\textit{\addtoindex{C} scoping rules require that the
value of the variable x passed to the function g is the value of the
global variable x rather than of the local version.}
a file number from the line number information table for the
compilation unit containing the debugging information entry and
represents the source file in which the declaration appeared
-(see Section 6.2). The value 0 indicates that no source file
+(see Section \refersec{chap:linenumberinformation}).
+The value 0 indicates that no source file
has been specified.
The value of the \livelink{chap:DWATdeclline}{DW\-\_AT\-\_decl\-\_line} attribute represents
common \livelink{chap:commonblockentry}{block}
may have a
\livelink{chap:DWATlocation}{DW\-\_AT\-\_location} attribute, whose value is a location description
-(see Section 2.6).
+(see Section \refersec{chap:locationdescriptions}).
A DWARF procedure is represented by any
kind of debugging information entry that has a \livelink{chap:DWATlocation}{DW\-\_AT\-\_location}
\textit{A base address selection entry and an end of list entry for
a range list are identical to a base address selection entry
and end of list entry, respectively, for a location list
-(see Section 2.6.2) in interpretation and representation.}
+(see Section \refersec{chap:locationlists})
+in interpretation and representation.}
Many debugging information entries allow either a
\livelink{chap:DWATbytesize}{DW\-\_AT\-\_byte\-\_size} attribute or a \livelink{chap:DWATbitsize}{DW\-\_AT\-\_bit\-\_size} attribute,
whose integer constant value
-(see \refersec{chap:staticanddynamicvaluesofattributes})
+(see Section \refersec{chap:staticanddynamicvaluesofattributes})
specifies an
amount of storage. The value of the \livelink{chap:DWATbytesize}{DW\-\_AT\-\_byte\-\_size} attribute
is interpreted in bytes and the value of the \livelink{chap:DWATbitsize}{DW\-\_AT\-\_bit\-\_size}
\section{Linkage Names}
\label{chap:linkagenames}
-\textit{Some language implementations, notably C++ and similar
+\textit{Some language implementations, notably
+\addtoindex{C++} and similar
languages, make use of implementation defined names within
object files that are different from the identifier names
-(see \refersec{chap:identifiernames}) of entities as they appear in the
+(see Section \refersec{chap:identifiernames}) of entities as they appear in the
source. Such names, sometimes known as mangled names,
are used in various ways, such as: to encode additional
information about an entity, to distinguish multiple entities
different languages in a unified fashion by requiring language
independent debugging information whenever possible.
Aspects
-of individual languages, such as C++ virtual functions or
-Fortran common \nolink{blocks}, are accommodated by creating attributes
+of individual languages, such as \addtoindex{C++} virtual functions or
+\addtoindex{Fortran} common
+\nolink{blocks}, are accommodated by creating attributes
that are used only for those languages.
This document is
believed to cover most debugging information needs of
addtoindex{Ada},
-C, C++, COBOL, and Fortran; it also covers the basic needs
+\addtoindex{C}, \addtoindex{C++}, \addtoindex{COBOL},
+and \addtoindex{Fortran}; it also covers the basic needs
of various other languages.
This document describes DWARF Version 4, the fourth generation
array and pointer types.
\item
-Add additional base types for C (as revised for 1999).
+Add additional base types for \addtoindex{C} (as revised for 1999).
\item
-Add support for Java and COBOL.
+Add support for \addtoindex{Java} and \addtoindex{COBOL}.
\item
-Add namespace support for C++.
+Add namespace support for \addtoindex{C++}.
\item
Add an optional section for global type names (similar to
\section{Macro Information}
\label{chap:macroinformation}
-\textit{Some languages, such as C and C++, provide a way to replace
+\textit{Some languages, such as
+\addtoindex{C} and
+addtoindex{C++}, provide a way to replace
text in the source program with macros defined either in the
source file itself, or in another file included by the source
file. Because these macros are not themselves defined in the
programmer wrote it. The macro information table provides a way
of preserving the original source in the debugging information.}
-As described in Section 3.1.1, the macro information for a
+As described in
+Section \refersec{chap:normalandpartialcompilationunitentries},
+the macro information for a
given compilation unit is represented in the
\addtoindex{.debug\_macinfo}
section of an object file. The macro information for each
of the program. If more than one compilation unit contains
this \nolink{flag}, any one of them may contain the starting function.
-\textit{Fortran has a PROGRAM statement which is used
+\textit{\addtoindex{Fortran} has a PROGRAM statement which is used
to specify and provide a user\dash specified name for the main
-subroutine of a program. C uses the name “main” to identify
+subroutine of a program.
+\addtoindex{C} uses the name “main” to identify
the main subprogram of a program. Some other languages provide
similar or other means to identify the main subprogram of
a program.}
\subsection{Module Entries}
\label{chap:moduleentries}
\textit{Several languages have the concept of a ``module.''
+\addtoindexx{Modula-2}
A Modula\dash 2 definition module may be represented by a module
entry containing a declaration attribute (\livelink{chap:DWATdeclaration}{DW\-\_AT\-\_declaration}). A
-Fortran 90 module may also be represented by a module entry
-(but no declaration attribute is warranted because Fortran
+\addtoindex{Fortran 90} module may also be represented by a module entry
+(but no declaration attribute is warranted because \addtoindex{Fortran}
has no concept of a corresponding module body).}
A module is represented by a debugging information entry
\subsection{Namespace Entries}
\label{chap:namespaceentries}
-\textit{C++ has the notion of a namespace, which provides a way to
+\textit{\addtoindex{C++} has the notion of a namespace, which provides a way to
implement name hiding, so that names of unrelated things
do not accidentally clash in the global namespace when an
application is linked together.}
debugging information entries describing program entities
whose declarations occur in the namespace.
-\textit{For C++, such owned program entities may be declarations,
+\textit{For \addtoindex{C++}, such
+owned program entities may be declarations,
including certain declarations that are also object or
function definitions.}
to duplicate information provided by the declaration entry
referenced by the specification attribute.
-\textit{The C++ global namespace (the namespace referred to by
+\textit{The \addtoindex{C++} global namespace
+(the namespace referred to by
``::f'', for example) is not explicitly represented in
DWARF with a namespace entry (thus mirroring the situation
-in C++ source). Global items may be simply declared with no
+in \addtoindex{C++} source).
+Global items may be simply declared with no
reference to a namespace.}
-\textit{The C++ compilation unit specific ``unnamed namespace'' may
+\textit{The \addtoindex{C++}
+compilation unit specific ``unnamed namespace'' may
be represented by a namespace entry with no name attribute in
the original namespace declaration entry (and therefore no name
attribute in any namespace extension entry of this namespace).
quality\dash of\dash implementation issue and no specific requirements
are given here. If only the final namespace is represented,
it is impossible for a debugger to interpret using declaration
-references in exactly the manner defined by the C++ language.
+references in exactly the manner defined by the
+\addtoindex{C++} language.
}
\textit{Emitting all namespace declaration information in all
compilation units can result in a significant increase in the
size of the debug information and significant duplication of
-information across compilation units. The C++ namespace std,
+information across compilation units.
+The \addtoindex{C++} namespace std,
for example, is large and will probably be referenced in
-every C++ compilation unit.
+every \addtoindex{C++} compilation unit.
}
-\textit{For a C++ namespace example, see Appendix \refersec{app:namespaceexample}.
+\textit{For a \addtoindex{C++} namespace example,
+see Appendix \refersec{app:namespaceexample}.
}
an entity, regardless of the context in which the importing
declaration or the imported entity occurs.
-\textit{A C++ namespace alias may be represented by an imported
+\textit{A \addtoindex{C++} namespace alias may be represented by an imported
\hypertarget{chap:DWATimportnamespacealias}
declaration entry with a name attribute whose value is
a null\dash terminated string containing the alias name as it
namespace extension entry.
}
-\textit{A C++ using declaration may be represented by one or more
+\textit{A \addtoindex{C++} using declaration may be represented by one or more
\hypertarget{chap:DWATimportnamespaceusingdeclaration}
imported declaration entries. When the using declaration
refers to an overloaded function, there is one imported
declaration entry corresponding to each overloading. Each
imported declaration entry has no name attribute but it does
have an import attribute that refers to the entry for the
-entity being imported. (C++ provides no means to ``rename''
+entity being imported. (\addtoindex{C++}
+provides no means to ``rename''
an imported entity, other than a namespace).
}
-\textit{A Fortran use statement with an ``only list'' may be
+\textit{A \addtoindex{Fortran} use statement with an ``only list'' may be
represented by a series of imported declaration entries,
one (or more) for each entity that is imported. An entity
that is renamed in the importing context may be represented
renamed in this way is known in the context of the imported
module entry by the same name as it is declared in the module.
-\textit{A C++ using directive may be represented by an imported module
+\textit{A \addtoindex{C++} using directive
+may be represented by an imported module
\hypertarget{chap:DWATimportnamespaceusingdirective}
entry, with an import attribute referring to the namespace
entry of the appropriate extension of the namespace (which
might be the original namespace entry) and no owned entries.
}
-\textit{A Fortran use statement with a “rename list” may be
+\textit{A \addtoindex{Fortran} use statement with a “rename list” may be
represented by an imported module entry with an import
attribute referring to the module and owned entries
corresponding to those entities that are renamed as part of
being imported.
}
-\textit{A Fortran use statement with neither a “rename list” nor
+\textit{A \addtoindex{Fortran} use statement
+with neither a “rename list” nor
an “only list” may be represented by an imported module
entry with an import attribute referring to the module and
no owned child entries.
in Section \refersec{chap:importedorrenameddeclarationentries}.
}
-\textit{A Fortran use statement for an entity in a module that is
+\textit{A \addtoindex{Fortran} use statement for an entity in a module that is
itself imported by a use statement without an explicit mention
may be represented by an imported declaration entry that refers
to the original debugging information entry. For example, given
directly to the variable declaration entry for A in module A
because there is no explicit representation for X in module B.
-A similar situation arises for a C++ using declaration that
+A similar situation arises for a \addtoindex{C++} using declaration that
imports an entity in terms of a namespace alias. See
Appendix \refersec{app:namespaceexample}
for an example.
\nolink{flag},
any one of them may be the starting subroutine of the program.
-\textit{Fortran has a PROGRAM statement which is used to specify
+\textit{\addtoindex{Fortran} has a PROGRAM statement which is used to specify
and provide a user\dash supplied name for the main subroutine of
a program.
}
may have a calling convention attribute whose value is the
constant \livetarg{chap:DWCCprogram}{DW\-\_CC\-\_program}.
-\textit{The \livelink{chap:DWCCprogram}{DW\-\_CC\-\_program} value is intended to support Fortran main
+\textit{The \livelink{chap:DWCCprogram}{DW\-\_CC\-\_program} value is intended to support \addtoindex{Fortran} main
programs which in some implementations may not be callable
or which must be invoked in a special way. It is not intended
as a way of finding the entry address for the program.
}
-\textit{In C there is a difference between the types of functions
+\textit{In \addtoindex{C}
+there is a difference between the types of functions
declared using function prototype style declarations and
those declared using non\dash prototype declarations.
}
\livelink{chap:DWATprototyped}{DW\-\_AT\-\_prototyped} attribute, which is
a \livelink{chap:flag}{flag}.
-\textit{The Fortran language allows the keywords elemental, pure
+\textit{The \addtoindex{Fortran}
+language allows the keywords elemental, pure
and recursive to be included as part of the declaration of
a subroutine; these attributes reflect that usage. These
attributes are not relevant for languages that do not support
similar keywords or syntax. In particular, the \livelink{chap:DWATrecursive}{DW\-\_AT\-\_recursive}
attribute is neither needed nor appropriate in languages such
-as C where functions support recursion by default.
+as \addtoindex{C}
+where functions support recursion by default.
}
A subprogram entry
value, then its debugging information entry has a \livelink{chap:DWATtype}{DW\-\_AT\-\_type}
attribute to denote the type returned by that function.
-\textit{Debugging information entries for C void functions should
+\textit{Debugging information entries for
+\addtoindex{C} void functions should
not have an attribute for the return type. }
\livetarg{chap:DWTAGunspecifiedparameters}{DW\-\_TAG\-\_unspecified\-\_parameters}.
The entry for a subroutine that includes a
-Fortran \livelink{chap:fortrancommonblock}{common} \livelink{chap:commonblockentry}{block}
+\addtoindex{Fortran}
+\livelink{chap:fortrancommonblock}{common}
+\livelink{chap:commonblockentry}{block}
\addtoindexx{common block|see{Fortran common block}}
has a child entry with the
tag \livetarg{chap:DWTAGcommoninclusion}{DW\-\_TAG\-\_common\-\_inclusion}.
\subsection{Types Thrown by Exceptions}
\label{chap:typesthrownbyexceptions}
-\textit{In C++ a subroutine may declare a set of types which
+\textit{In \addtoindex{C++} a subroutine may declare a set of types which
it may validly throw.}
If a subroutine explicitly declares that it may throw
\subsection{Function Template Instantiations}
\label{chap:functiontemplateinstantiations}
-\textit{In C++, a function template is a generic definition of
+\textit{In \addtoindex{C++}, a function template is a generic definition of
a function that is instantiated differently when called with
values of different types. DWARF does not represent the generic
template definition, but does represent each instantiation.}
\end{tabular}
\end{figure}
-\textit{In C++, a function or a constructor declared with
+\textit{In \addtoindex{C++}, a function or a constructor declared with
constexpr is implicitly declared inline. The abstract inline
instance (see below) is represented by a debugging information
entry with the tag \livelink{chap:DWTAGsubprogram}{DW\-\_TAG\-\_subprogram}. Such an entry has a
tree (which gives a context for the root) or uses
\livelink{chap:DWATspecification}{DW\-\_AT\-\_specification} to refer to the declaration in context.
-\textit{For example, in C++ the context might be a namespace
+\textit{For example, in \addtoindex{C++} the context might be a namespace
declaration or a class declaration.}
\textit{Abstract instance trees are defined so that no entry is part
this attribute is the actual return value of the subroutine,
represented as it would be on the target architecture.
-\textit{In C++, if a function or a constructor declared with constexpr
+\textit{In \addtoindex{C++}, if a function or a constructor declared with constexpr
is called with constant expressions, then the corresponding
concrete inlined instance has a \livelink{chap:DWATconstexpr}{DW\-\_AT\-\_const\-\_expr} attribute,
as well as a \livelink{chap:DWATconstvalue}{DW\-\_AT\-\_const\-\_value} attribute whose value represents
concrete instances of inlined subroutines are referred to as
``concrete out\dash of\dash line instances.''
-\textit{In C++, for example, taking the address of a function declared
+\textit{In \addtoindex{C++}, for example,
+taking the address of a function declared
to be inline can necessitate the generation of a concrete
out\dash of\dash line instance of the given function.}
of trampolines necessarily ends with a non\dash trampoline
subprogram.)
-\textit{In C++, trampolines may be used to implement derived virtual
+\textit{In \addtoindex{C++}, trampolines may be used
+to implement derived virtual
member functions; such trampolines typically adjust the
implicit this pointer parameter in the course of passing
control. Other languages and environments may use trampolines
\textit{A lexical \livetargi{chap:lexicalblock}{block}{lexical block} is a bracketed sequence of source statements
that may contain any number of declarations. In some languages
-(including C and C++), \nolink{blocks} can be nested within other
+(including \addtoindex{C} and \addtoindex{C++}),
+\nolink{blocks} can be nested within other
\nolink{blocks} to any depth.}
% We do not need to link to the preceeding paragraph.
as it appears in
the source program.
-\textit{This is not the same as a C or C++ label (see below).}
+\textit{This is not the same as a \addtoindex{C} or
+\addtoindex{C++} label (see below).}
The lexical \livelink{chap:lexicalblockentry}{block} entry owns
debugging information entries that
\section{With Statement Entries}
\label{chap:withstatemententries}
-\textit{Both Pascal and Modula\dash 2 support the concept of a ``with''
+\textit{Both \addtoindex{Pascal} and
+\addtoindexx{Modula-2}
+Modula\dash 2 support the concept of a ``with''
statement. The with statement specifies a sequence of
executable statements within which the fields of a record
variable may be referenced, unqualified by the name of the
\section{Try and Catch Block Entries}
\label{chap:tryandcatchblockentries}
-\textit{In C++ a lexical \livelink{chap:lexicalblock}{block} may be
+\textit{In \addtoindex{C++} a lexical \livelink{chap:lexicalblock}{block} may be
designated as a ``catch \nolink{block}.''
A catch \livetargi{chap:catchblock}{block}{catch block} is an
exception handler that handles
Notes:
\begin{itemize}
-\item "V2" means DWARF Version 2, published July 1993.
-\item "V3" means DWARF Version 3, published December 2005.
-\item "V4" means DWARF Version 4, published June 2010.
-\item "-" means that a version number is not applicable
+\item ``V2'' means DWARF Version 2, published July 1993.
+\item ``V3'' means DWARF Version 3, published December 2005.
+\item ``V4'' means DWARF Version 4, published June 2010.
+\item ``-'' means that a version number is not applicable
(the section's header does not include a version).
-\item "x" means that the section was not defined in that
+\item ``x'' means that the section was not defined in that
version of the DWARF standard.
\item The version numbers for the \addtoindex{.debug\_info} and \addtoindex{.debug\_types}
and following text.
A base type entry
-may have a \livelink{chap:DWATendianity}{DW\-\_AT\-\_endianity} attribute as described in
+may have a \livelink{chap:DWATendianity}{DW\-\_AT\-\_endianity} attribute
+\addtoindexx{endianity attribute}
+as described in
Section \refersec{chap:dataobjectentries}.
If omitted, the encoding assumes the representation that
is the default for the target architecture.
\hypertarget{chap:DWATbytesizedataobjectordatatypesize}
either a \livelink{chap:DWATbytesize}{DW\-\_AT\-\_byte\-\_size} attribute
\hypertarget{chap:DWATbitsizebasetypebitsize}
-or a \livelink{chap:DWATbitsize}{DW\-\_AT\-\_bit\-\_size} attribute whose integer constant value
+or a \livelink{chap:DWATbitsize}{DW\-\_AT\-\_bit\-\_size} attribute
+\addtoindex{bit size attribute}
+whose integer constant value
(see Section \refersec{chap:byteandbitsizes})
is the amount of storage needed to hold
a value of the type.
-\textit{For example, the C type int on a machine that uses 32\dash bit
+\textit{For example, the
+\addtoindex{C} type int on a machine that uses 32\dash bit
integers is represented by a base type entry with a name
attribute whose value is “int”, an encoding attribute
whose value is \livelink{chap:DWATEsigned}{DW\-\_ATE\-\_signed} and a byte size attribute whose
If the value of an object of the given type does not fully
occupy the storage described by a byte size attribute,
\hypertarget{chap:DWATdatabitoffsetbasetypebitlocation}
-the base type entry may also have a
+the base type entry may also have
+\addtoindexx{bit size attribute}
+a
\livelink{chap:DWATbitsize}{DW\-\_AT\-\_bit\-\_size} and a
-\livelink{chap:DWATdatabitoffset}{DW\-\_AT\-\_data\-\_bit\-\_offset} attribute, both of whose values are
+\livelink{chap:DWATdatabitoffset}{DW\-\_AT\-\_data\-\_bit\-\_offset} attribute,
+both of whose values are
integer constant values (
see Section \refersec{chap:staticanddynamicvaluesofattributes}).
The bit size
value. If this attribute is omitted a default data bit offset
of zero is assumed.
-\textit{Attribute \livelink{chap:DWATdatabitoffset}{DW\-\_AT\-\_data\-\_bit\-\_offset} is new in DWARF Version 4 and
+\textit{Attribute
+\livelink{chap:DWATdatabitoffset}{DW\-\_AT\-\_data\-\_bit\-\_offset}
+is
+\addtoindexx{bit offset attribute}
+new in DWARF Version 4 and
is also used for bit field members
(see Section \refersec{chap:datamemberentries}).
It
\hypertarget{chap:DWATbitoffsetbasetypebitlocation}
-replaces the attribute \livelink{chap:DWATbitoffset}{DW\-\_AT\-\_bit\-\_offset} when used for base
+replaces the attribute
+\livelink{chap:DWATbitoffset}{DW\-\_AT\-\_bit\-\_offset}
+when used for base
+\addtoindexx{bit offset attribute (V3)}
types as defined in DWARF V3 and earlier. The earlier attribute
is defined in a manner suitable for bit field members on
big\dash endian architectures but which is wasteful for use on
\begin{myindentpara}{1cm}
\textit{A base type entry has a \livelink{chap:DWATbytesize}{DW\-\_AT\-\_byte\-\_size} attribute, whose value
-(see Section 2.19) is the size in bytes of the storage unit
+(see Section \refersec{chap:staticanddynamicvaluesofattributes})
+is the size in bytes of the storage unit
used to represent an object of the given type.}
\textit{If the value of an object of the given type does not fully
occupy the storage unit described by the byte size attribute,
-the base type entry may have a \livelink{chap:DWATbitsize}{DW\-\_AT\-\_bit\-\_size} attribute and a
-\livelink{chap:DWATbitoffset}{DW\-\_AT\-\_bit\-\_offset} attribute, both of whose values (see Section
-2.19) are integers. The bit size attribute describes the actual
+the base type entry may have a
+\livelink{chap:DWATbitsize}{DW\-\_AT\-\_bit\-\_size} attribute
+\addtoindexx{bit size attribute (V3)}
+and a
+\livelink{chap:DWATbitoffset}{DW\-\_AT\-\_bit\-\_offset} attribute, both of whose values
+(see Section \refersec{chap:staticanddynamicvaluesofattributes})
+are integers. The bit size attribute describes the actual
size in bits used to represent a value of the given type.
The bit offset attribute describes the offset in bits of the
high order bit of a value of the given type from the high
\textit{The \livelink{chap:DWATEUTF}{DW\-\_ATE\-\_UTF} encoding is intended for Unicode string
encodings (see the Universal Character Set standard,
-ISO/IEC 10646\dash 1:1993). For example, the C++ type char16\_t is
+ISO/IEC 10646\dash 1:1993). For example, the
+\addtoindex{C++} type char16\_t is
represented by a base type entry with a name attribute whose
value is “char16\_t”, an encoding attribute whose value
is \livelink{chap:DWATEUTF}{DW\-\_ATE\-\_UTF} and a byte size attribute whose value is 2.}
\hypertarget{chap:DWATbinaryscalebinaryscalefactorforfixedpointtype}
For a data type with a binary scale factor, the fixed
+\addtoindexx{binary scale attribute}
binary type entry has a \livelink{chap:DWATbinaryscale}{DW\-\_AT\-\_binary\-\_scale} attribute. The
\livelink{chap:DWATbinaryscale}{DW\-\_AT\-\_binary\-\_scale} attribute is an integer constant value
that represents the exponent of the base two scale factor to
The interpretation of this debugging information entry is
intentionally left flexible to allow it to be interpreted
-appropriately in different languages. For example, in C and C++
+appropriately in different languages. For example, in
+\addtoindex{C} and \addtoindex{C++}
the language implementation can provide an unspecified type
entry with the name “void” which can be referenced by the
type attribute of pointer types and typedef declarations for
a constrained type and other terms. A type name declared with
no defining details may be termed an incomplete, forward
or hidden type. While the DWARF \livelink{chap:DWTAGtypedef}{DW\-\_TAG\-\_typedef} entry was
-originally inspired by the like named construct in C and C++,
+originally inspired by the like named construct in
+\addtoindex{C} and \addtoindex{C++},
it is broadly suitable for similar constructs (by whatever
source syntax) in other languages.}
object of the
\hypertarget{chap:DWATbytestridearrayelementstrideofarraytype}
indicated element type, then the array type
-entry has either a \livelink{chap:DWATbytestride}{DW\-\_AT\-\_byte\-\_stride} or a \livelink{chap:DWATbitstride}{DW\-\_AT\-\_bit\-\_stride}
-attribute, whose value
+\addtoindexx{bit stride attribute}
+entry has either a
+\livelink{chap:DWATbytestride}{DW\-\_AT\-\_byte\-\_stride}
+or
+\addtoindexx{byte stride attribute}
+a \livelink{chap:DWATbitstride}{DW\-\_AT\-\_bit\-\_stride}
+attribute,
+\addtoindexx{bit stride attribute}
+whose value
(see Section \refersec{chap:staticanddynamicvaluesofattributes})
is the size of each
element of the array.
\section{ Structure, Union, Class and Interface Type Entries}
\label{chap:structureunionclassandinterfacetypeentries}
-\textit{The languages C, C++, and Pascal, among others, allow the
+\textit{The languages
+\addtoindex{C},
+\addtoindex{C++}, and
+\addtoindex{Pascal}, among others, allow the
programmer to define types that are collections of related
-components. In C and C++, these collections are called
-“structures.” In Pascal, they are called “records.”
+components. In \addtoindex{C} and \addtoindex{C++}, these collections are called
+“structures.” In \addtoindex{Pascal}, they are called “records.”
The components may be of different types. The components are
-called “members” in C and C++, and “fields” in Pascal.}
+called “members” in \addtoindex{C} and
+\addtoindex{C++}, and “fields” in \addtoindex{Pascal}.}
\textit{The components of these collections each exist in their
own space in computer memory. The components of a C or C++
“union” all coexist in the same memory.}
-\textit{Pascal and other languages have a “discriminated union,”
+\textit{\addtoindex{Pascal} and
+other languages have a “discriminated union,”
also called a “variant record.” Here, selection of a
number of alternative substructures (“variants”) is based
on the value of a component that is not part of any of those
substructures (the “discriminant”).}
-\textit{C++ and Java have the notion of "class”, which is in some
+\textit{\addtoindex{C++} and
+\addtoindex{Java} have the notion of ``class'', which is in some
ways similar to a structure. A class may have “member
functions” which are subroutines that are within the scope
of a class or structure.}
-\textit{The C++ notion of structure is more general than in C, being
+\textit{The \addtoindex{C++} notion of
+structure is more general than in \addtoindex{C}, being
equivalent to a class with minor differences. Accordingly,
-in the following discussion statements about C++ classes may
-be understood to apply to C++ structures as well.}
+in the following discussion statements about
+\addtoindex{C++} classes may
+be understood to apply to \addtoindex{C++} structures as well.}
\subsection{Structure, Union and Class Type Entries}
\label{chap:structureunionandclasstypeentries}
class or union they represent if such information is already
provided in the declaration.
-\textit{For C and C++, data member declarations occurring within
+\textit{For \addtoindex{C} and \addtoindex{C++},
+data member declarations occurring within
the declaration of a structure, union or class type are
considered to be “definitions” of those members, with
the exception of “static” data members, whose definitions
\subsection{Interface Type Entries}
\label{chap:interfacetypeentries}
-\textit{The Java language defines "interface" types. An interface
-in Java is similar to a C++ or Java class with only abstract
+\textit{The \addtoindex{Java} language defines ``interface'' types.
+An interface
+in Java is similar to a \addtoindex{C++} or
+\addtoindex{Java} class with only abstract
methods and constant data members.}
Interface types are represented by debugging information
\subsection{Derived or Extended Structs, Classes and Interfaces}
\label{chap:derivedorextendedstructsclasesandinterfaces}
-\textit{In C++, a class (or struct) may be ``derived from'' or be a
+\textit{In \addtoindex{C++}, a class (or struct) may be ``derived from'' or be a
``subclass of'' another class. In Java, an interface may ``extend''
-one or more other interfaces, and a class may "extend" another
-class and/or "implement" one or more interfaces. All of these
+one or more other interfaces, and a class may ``extend'' another
+class and/or ``implement'' one or more interfaces. All of these
relationships may be described using the following. Note that
in Java, the distinction between extends and implements is
implied by the entities at the two ends of the relationship.}
If
\hypertarget{chap:DWATvirtualityvirtualityofbaseclass}
the class referenced by the inheritance entry serves
-as a C++ virtual base class, the inheritance entry has a
+as a \addtoindex{C++} virtual base class, the inheritance entry has a
\livelink{chap:DWATvirtuality}{DW\-\_AT\-\_virtuality} attribute.
-\textit{For a C++ virtual base, the data member location attribute
+\textit{For a \addtoindex{C++} virtual base, the data member location attribute
will usually consist of a non-trivial location description.}
\subsection{Access Declarations}
\label{chap:accessdeclarations}
-\textit{In C++, a derived class may contain access declarations that
+\textit{In \addtoindex{C++}, a derived class may contain access declarations that
\addtoindex{access declaration entry}
change the accessibility of individual class members from the
overall accessibility specified by the inheritance declaration.
This attribute indicates whether the data
member was declared with the mutable storage class specifier.
-The
+The beginning of a data member
\addtoindex{beginning of a data member}
is described relative to
+\addtoindexx{beginning of an object}
the beginning of the object in which it is immediately
contained. In general, the beginning is characterized by
both an address and a bit offset within the byte at that
If the size of a data member is not the same as the size
of the type given for the data member, the data member has
-either a \livelink{chap:DWATbytesize}{DW\-\_AT\-\_byte\-\_size} or a \livelink{chap:DWATbitsize}{DW\-\_AT\-\_bit\-\_size} attribute whose
+\addtoindexx{bit size attribute}
+either a \livelink{chap:DWATbytesize}{DW\-\_AT\-\_byte\-\_size}
+or a \livelink{chap:DWATbitsize}{DW\-\_AT\-\_bit\-\_size} attribute whose
integer constant value
(see Section \refersec{chap:staticanddynamicvaluesofattributes})
is the amount
of storage needed to hold the value of the data member.
-\textit{C and C++ bit fields typically require the use of the
+\textit{\addtoindex{C} and \addtoindex{C++}
+\addtoindex{bit fields}
+typically require the use of the
\livelink{chap:DWATdatabitoffset}{DW\-\_AT\-\_data\-\_bit\-\_offset} and \livelink{chap:DWATbitsize}{DW\-\_AT\-\_bit\-\_size} attributes.}
\textit{This Standard uses the following bit numbering and direction
\end{itemize}
-\textit{In either case, the bit so identified is defined as the beginning of the object.}
+\textit{In either case, the bit so identified is defined as the
+\addtoindexx{beginning of an object}
+beginning of the object.}
-\textit{For example, take one possible representation of the following C structure definition in both big\dash and little\dash endian byte orders:}
+\textit{For example, take one possible representation of the following
+\addtoindex{C} structure definition
+in both big\dash and little\dash endian byte orders:}
\begin{lstlisting}
struct S {
entry has the following attributes:}
\begin{itemize}
-\item \textit{A \livelink{chap:DWATbytesize}{DW\-\_AT\-\_byte\-\_size} attribute whose value (see Section
-2.19) is the number of bytes that contain an instance of the
+\item \textit{A \livelink{chap:DWATbytesize}{DW\-\_AT\-\_byte\-\_size}
+attribute whose value
+(see Section \refersec{chap:staticanddynamicvaluesofattributes})
+is the number of bytes that contain an instance of the
bit field and any padding bits.}
\textit{The byte size attribute may be omitted if the size of the
object containing the bit field can be inferred from the type
attribute of the data member containing the bit field.}
-\item \textit{A \livelink{chap:DWATbitoffset}{DW\-\_AT\-\_bit\-\_offset} attribute whose value (see Section
-2.19) is the number of bits to the left of the leftmost
+\item \textit{A \livelink{chap:DWATbitoffset}{DW\-\_AT\-\_bit\-\_offset}
+attribute
+\addtoindexx{bit offset attribute (V3)}
+whose value
+(see Section \refersec{chap:staticanddynamicvaluesofattributes})
+is the number of bits to the left of the leftmost
(most significant) bit of the bit field value.}
-\item \textit{A \livelink{chap:DWATbitsize}{DW\-\_AT\-\_bit\-\_size} attribute whose value (see Section
-2.19) is the number of bits occupied by the bit field value.}
+\item \textit{A \livelink{chap:DWATbitsize}{DW\-\_AT\-\_bit\-\_size}
+attribute
+\addtoindexx{bit size attribute (V3)}
+whose value
+(see Section \refersec{chap:staticanddynamicvaluesofattributes})
+is the number of bits occupied by the bit field value.}
\end{itemize}
whose value is a reference to the formal parameter entry
that corresponds to the object for which the function is
called. The name attribute of that formal parameter is defined
-by the current language (for example, this for C++ or self
-for Objective C and some other languages). That parameter
+by the current language (for example,
+this for \addtoindex{C++} or self
+for \addtoindex{Objective C}
+and some other languages). That parameter
also has a \livelink{chap:DWATartificial}{DW\-\_AT\-\_artificial} attribute whose value is true.
Conversely, if the member function entry describes a static
\subsection{Class Template Instantiations}
\label{chap:classtemplateinstantiations}
-\textit{In C++ a class template is a generic definition of a class
+\textit{In \addtoindex{C++} a class template is a generic definition of a class
type that may be instantiated when an instance of the class
is declared or defined. The generic description of the
class may include both parameterized types and parameterized
one kind of enumeration declaration, this attribute is not
required.
-\textit{In C or C++, the underlying type will be the appropriate
+\textit{In \addtoindex{C} or \addtoindex{C++},
+the underlying type will be the appropriate
integral type determined by the compiler from the properties of
\hypertarget{chap:DWATenumclasstypesafeenumerationdefinition}
-the enumeration literal values. A C++ type declaration written
+the enumeration literal values. A \addtoindex{C++} type declaration written
using enum class declares a strongly typed enumeration and
is represented using \livelink{chap:DWTAGenumerationtype}{DW\-\_TAG\-\_enumeration\-\_type} in combination
with \livelink{chap:DWATenumclass}{DW\-\_AT\-\_enum\-\_class}.}
is different than what would otherwise be determined, then
\hypertarget{chap:DWATbitstrideenumerationstridedimensionofarraytype}
the enumeration type entry has either a \livelink{chap:DWATbytestride}{DW\-\_AT\-\_byte\-\_stride}
-or \livelink{chap:DWATbitstride}{DW\-\_AT\-\_bit\-\_stride} attribute which specifies the separation
+or \livelink{chap:DWATbitstride}{DW\-\_AT\-\_bit\-\_stride} attribute
+\addtoindexx{bit stride attribute}
+which specifies the separation
between successive elements along the dimension as described
in
Section \refersec{chap:visibilityofdeclarations}.
-The value of the \livelink{chap:DWATbitstride}{DW\-\_AT\-\_bit\-\_stride} attribute
-is interpreted as bits and the value of the \livelink{chap:DWATbytestride}{DW\-\_AT\-\_byte\-\_stride}
+The value of the
+\livelink{chap:DWATbitstride}{DW\-\_AT\-\_bit\-\_stride} attribute
+\addtoindexx{bit stride attribute}
+is interpreted as bits and the value of
+\addtoindexx{byte stride attribute}
+the
+\livelink{chap:DWATbytestride}{DW\-\_AT\-\_byte\-\_stride}
attribute is interpreted as bytes.
\section{Subroutine Type Entries}
\label{chap:subroutinetypeentries}
-It is possible in C to declare pointers to subroutines
-that return a value of a specific type. In both C and C++,
+It is possible in \addtoindex{C}
+to declare pointers to subroutines
+that return a value of a specific type. In both
+\addtoindex{C} and \addtoindex{C++},
it is possible to declare pointers to subroutines that not
only return a value of a specific type, but accept only
arguments of specific types. The type of such pointers would
order that the corresponding argument types appear in the
source program.
-In C there is a difference between the types of functions
+In \addtoindex{C} there
+is a difference between the types of functions
declared using function prototype style declarations and
those declared using non\dash prototype declarations.
\hypertarget{chap:DWATbytestridesubrangestridedimensionofarraytype}
different than what would otherwise be determined, then
\hypertarget{chap:DWATbitstridesubrangestridedimensionofarraytype}
-the subrange type entry has either a \livelink{chap:DWATbytestride}{DW\-\_AT\-\_byte\-\_stride} or
-\livelink{chap:DWATbitstride}{DW\-\_AT\-\_bit\-\_stride} attribute which specifies the separation
+the subrange type entry has either
+\addtoindexx{byte stride attribute}
+a
+\livelink{chap:DWATbytestride}{DW\-\_AT\-\_byte\-\_stride} or
+\livelink{chap:DWATbitstride}{DW\-\_AT\-\_bit\-\_stride} attribute
+\addtoindexx{bit stride attribute}
+which specifies the separation
between successive elements along the dimension as described
in
Section \refersec{chap:byteandbitsizes}.
\section{Pointer to Member Type Entries}
\label{chap:pointertomembertypeentries}
-\textit{In C++, a pointer to a data or function member of a class or
+\textit{In \addtoindex{C++}, a pointer to a data or function member of a class or
structure is a unique type.}
A debugging information entry representing the type of an
The file type entry has a \livelink{chap:DWATtype}{DW\-\_AT\-\_type} attribute describing
the type of the objects contained in the file.
-The file type entry also has a \livelink{chap:DWATbytesize}{DW\-\_AT\-\_byte\-\_size} or
+The file type entry also
+\addtoindexx{byte size}
+has
+\addtoindexx{bit size}
+a
+\livelink{chap:DWATbytesize}{DW\-\_AT\-\_byte\-\_size} or
\livelink{chap:DWATbitsize}{DW\-\_AT\-\_bit\-\_size} attribute, whose value
(see Section \refersec{chap:staticanddynamicvaluesofattributes})
is the amount of storage need to hold a value of the file type.
DWARF Git Projects / dwarf-doc.git / commitdiff