DW_AT_c* in attribute table now linked per DWARF4.
[dwarf-doc.git] / dwarf5 / latexdoc / dataobject.tex
1 \chapter[Data Object and Object List]{Data Object and Object List Entries}
2 \label{chap:dataobjectandobjectlistentries}
3
4 This section presents the debugging information entries that
5 describe individual data objects: variables, parameters and
6 constants, and lists of those objects that may be grouped in
7 a single declaration, such as 
8 a common \livelink{chap:commonblockentry}{block}.
9
10 \section{Data Object Entries}
11 \label{chap:dataobjectentries}
12
13
14 Program variables, formal parameters and constants are
15 represented by debugging information entries with the tags
16 \livetarg{chap:DWTAGvariable}{DW\-\_TAG\-\_variable}, 
17 \livetarg{chap:DWTAGformalparameter}{DW\-\_TAG\-\_formal\-\_parameter} and 
18 \livetarg{chap:DWTAGconstant}{DW\-\_TAG\-\_constant},
19 respectively.
20
21 \textit{The tag \livelink{chap:DWTAGconstant}{DW\-\_TAG\-\_constant} is used for languages that
22 have true named constants.}
23
24 The debugging information entry for a program variable,
25 formal parameter or constant may have the following attributes:
26 \begin{enumerate}[1.]
27 \item A \livelink{chap:DWATname}{DW\-\_AT\-\_name} attribute, whose value is a null-terminated
28 string, containing the data object name as it appears in the
29 source program.  If a variable entry describes an anonymous
30 union, the name attribute is omitted or consists of a single
31 zero byte.
32
33 \item A \livelink{chap:DWATexternal}{DW\-\_AT\-\_external} attribute, 
34 which is a \livelink{chap:flag}{flag}, if the name
35 of a variable is visible outside of its enclosing compilation
36 unit.  The definitions of C++ static data members of structures
37 or classes are represented by variable entries \nolink{flagged} as
38 external. Both file static and local variables in C and C++
39 are represented by non-external variable entries.
40
41 \item A \livelink{chap:DWATdeclaration}{DW\-\_AT\-\_declaration} attribute, 
42 which is a \livelink{chap:flag}{flag} that
43 indicates whether this entry represents a non-defining
44 declaration of an object.
45
46 \item A \livelink{chap:DWATlocation}{DW\-\_AT\-\_location} attribute, whose value describes the
47 location of a variable or parameter at run-time.  In a variable
48 entry representing the definition of a variable (that is,
49 with no \livelink{chap:DWATdeclaration}{DW\-\_AT\-\_declaration} attribute) if no location attribute
50 is present, or if the location attribute is present but has
51 an empty location description (as described in Section 2.6),
52 the variable is assumed to exist in the source code but not
53 in the executable program (but see number 10, below).
54
55 In a variable entry representing a non-defining declaration of a variable, the location
56 specified modifies the location specified by the defining declaration and only applies for the
57 scope of the variable entry; if no location is specified, then the location specified in the
58 defining declaration applies.
59 The location of a variable may be further specified with a \livelink{chap:DWATsegment}{DW\-\_AT\-\_segment} attribute, if
60 appropriate.
61
62 \item A \livelink{chap:DWATtype}{DW\-\_AT\-\_type} attribute describing the type of the variable,
63 constant or formal parameter.
64
65 \item If the variable entry represents the defining declaration
66 for a C++ static data member of a structure, class or union,
67 the entry has a \livelink{chap:DWATspecification}{DW\-\_AT\-\_specification} attribute, whose value is a
68 reference to the debugging information entry representing the
69 declaration of this data member. The referenced entry has the
70 tag \livelink{chap:DWTAGmember}{DW\-\_TAG\-\_member} and will be a child of some class, structure
71 or union type entry.  If the variable entry represents a
72 non-defining declaration, \livelink{chap:DWATspecification}{DW\-\_AT\-\_specification} may be used
73 to reference the defining declaration of the variable. If
74 no \livelink{chap:DWATspecification}{DW\-\_AT\-\_specification} attribute is present, the defining
75 declaration may be found as a global definition either in the
76 current compilation unit or in another compilation unit with
77 the \livelink{chap:DWATexternal}{DW\-\_AT\-\_external} attribute.  Variable entries containing
78 the \livelink{chap:DWATspecification}{DW\-\_AT\-\_specification} attribute do not need to duplicate
79 information provided by the declaration entry referenced by
80 the specification attribute. In particular, such variable
81 entries do not need to contain attributes for the name or
82 type of the data member whose definition they represent.
83
84 \item A \livelink{chap:DWATvariableparameter}{DW\-\_AT\-\_variable\-\_parameter} attribute, 
85 which is a \livelink{chap:flag}{flag},
86 if a formal parameter entry represents a parameter whose
87 value in the calling function may be modified by the callee..
88 The absence of this attribute implies that the parameter’s
89 value in the calling function cannot be modified by the callee.
90
91 \item A \livelink{chap:DWATisoptional}{DW\-\_AT\-\_is\-\_optional} attribute, 
92 which is a \livelink{chap:flag}{flag}, if a
93 parameter entry represents an optional parameter.
94
95 \item A \livelink{chap:DWATdefaultvalue}{DW\-\_AT\-\_default\-\_value} attribute for a formal parameter
96 entry. The value of this attribute is a reference to the
97 debugging information entry for a variable or subroutine,
98 or the value may be a constant. If the attribute form is of
99 class reference, the default value of the parameter is the
100 value of the referenced variable (which may be constant) or
101 the value returned by the referenced subroutine; a reference
102 value of 0 means that no default value has been specified.
103 If the value is of class constant, that constant is interpreted
104 as a default value of the type of the formal parameter.
105
106 \textit{For a constant form there is no way to 
107 express the absence of a default value.}
108
109 \item A \livelink{chap:DWATconstvalue}{DW\-\_AT\-\_const\-\_value} attribute 
110 for 
111 \hypertarget{chap:DWATconstvalueconstantobject}
112 an entry describing a
113 variable or formal parameter whose value is constant and not
114 represented by an object in the address space of the program,
115 or an entry describing a named constant. (Note that such
116 an entry does not have a location attribute.) The value of
117 this attribute may be a string or any of the constant data
118 or data \livelink{chap:block}{block} forms, 
119 as appropriate for the representation
120 of the variable’s value. The value is the actual constant
121 value of the variable, represented as it would be on the
122 target architecture.  One way in which a formal parameter
123 with a constant value and no location can arise is for a
124 formal parameter of an inlined subprogram that corresponds
125 to a constant actual parameter of a call that is inlined.
126
127 \item A \livelink{chap:DWATstartscope}{DW\-\_AT\-\_start\-\_scope} attribute if the scope of an
128 object is smaller than (that is, is a subset of the addresses
129 of) the scope most closely enclosing the object. There are
130 two cases:
131 \begin{enumerate}[a)]
132 \item If the scope of the object entry includes all of the
133 containing scope except for a contiguous sequence of bytes at
134 the beginning of that containing scope, then the scope of the
135 object is specified using a value of class constant. If the
136 containing scope is contiguous, the value of this attribute
137 is the offset in bytes of the beginning of the scope for the
138 object from the low pc value of the debugging information
139 entry that defines its scope. If the containing scope
140 is non-contiguous (see Section 2.17.3), the value of this
141 attribute is the offset in bytes of the beginning of the scope
142 for the object from the beginning of the first range list entry
143 that is not a base selection entry or an end of list entry.
144
145 \item Otherwise, the scope of the object is specified using
146 a value of class \livelink{chap:rangelistptr}{rangelistptr}. This value indicates the
147 beginning of a range list (see Section 2.17.3).
148 \end{enumerate}
149
150
151 \textit{The scope of a variable may begin somewhere in the middle of
152 a lexical \livelink{chap:lexicalblock}{block} in a language 
153 that allows executable code in a
154 \nolink{block} before a variable declaration, or where one declaration
155 containing initialization code may change the scope of a
156 subsequent declaration.  For example, in the following C code:}
157
158 \begin{lstlisting}
159 float x = 99.99;
160 int myfunc()
161 {
162     float f = x;
163     float x = 88.99;
164     return 0;
165 }
166 \end{lstlisting}
167
168 \textit{C scoping rules require that the value of the variable x
169 assigned to the variable f in the initialization sequence is
170 the value of the global variable x, rather than the local x,
171 because the scope of the local variable x only starts after
172 the full declarator for the local x.}
173
174 \textit{Due to optimization, the scope of an object may be
175 non-contiguous and require use of a range list even when
176 the containing scope is contiguous. Conversely, the scope of
177 an object may not require its own range list even when the
178 containing scope is non\dash contiguous.}
179
180 \item A \livelink{chap:DWATendianity}{DW\-\_AT\-\_endianity} attribute, whose value is a constant
181 that specifies the endianity of the object. The value of
182 this attribute specifies an ABI\dash defined byte ordering for
183 the value of the object. If omitted, the default endianity
184 of data for the given type is assumed.  The set of values
185 and their meaning for this attribute is given in 
186 Figure \refersec{fig:endianityattributevalues}.
187
188 \begin{figure}[here]
189 \centering
190 \begin{tabular}{lp{9cm}}
191 Name&Meaning\\ \hline
192 \livetarg{chap:DWENDdefault}{DW\-\_END\-\_default} &  Default endian encoding
193   (equivalent to the absence of a 
194   \livelink{chap:DWATendianity}{DW\-\_AT\-\_endianity} attribute) \\
195 \livetarg{chap:DWENDbig}{DW\-\_END\-\_big} & Big\dash endian encoding \\
196 \livetarg{chap:DWENDlittle}{DW\-\_END\-\_little}& Little-endian encoding \\
197 \end{tabular}
198 \caption{Endianity attribute values}
199 \label{fig:endianityattributevalues}
200 \end{figure}
201
202
203 These represent the default encoding formats as defined by
204 the target architecture’s ABI or processor definition. The
205 exact definition of these formats may differ in subtle ways
206 for different architectures.
207
208
209 \item A \livelink{chap:DWATconstexpr}{DW\-\_AT\-\_const\-\_expr} attribute, 
210 which 
211 \hypertarget{chap:DWATconstexprcompiletimeconstantobject}
212 is a \livelink{chap:flag}{flag}, if a
213 variable entry represents a C++ object declared with the
214 \textit{constexpr} specifier. This attributes indicates that the
215 variable can be evaluated as a compile\dash time constant.  
216
217 \textit{In C++,
218 a variable declared with constexpr is implicitly const. Such a
219 variable has a \livelink{chap:DWATtype}{DW\-\_AT\-\_type} attribute whose value is a reference
220 to a debugging information entry}
221
222 \item A \livelink{chap:DWATlinkagename}{DW\-\_AT\-\_linkage\-\_name} attribute for a 
223 variable or constant entry as described in 
224 Section \refersec{chap:linkagenames}.
225
226 \end{enumerate}
227
228 \section{Common Block Entries}
229 \label{chap:commonblockentries}
230 A Fortran \livetargi{chap:fortrancommonblock}{common}{Fortran!common block} \livetargi{chap:commonblockentry}{block}{common block entry} 
231 may be described by a debugging
232 information entry with the 
233 tag \livetarg{chap:DWTAGcommonblock}{DW\-\_TAG\-\_common\-\_block}. 
234 The
235 common \nolink{block} 
236 entry has a \livelink{chap:DWATname}{DW\-\_AT\-\_name} attribute whose value
237 is a null-terminated string containing the 
238 \livetargi{chap:commonblockreferenceattribute}{common}{common block reference attribute} \nolink{block}
239 name as it appears in the source program. It may also have a
240 \livelink{chap:DWATlinkagename}{DW\-\_AT\-\_linkage\-\_name} attribute as described in 
241 Section \refersec{chap:linkagenames}. 
242 It
243 also has a \livelink{chap:DWATlocation}{DW\-\_AT\-\_location} attribute whose value describes the
244 location of the beginning of the common \nolink{block}. The common
245 \nolink{block} entry owns debugging information entries describing
246 the variables contained within the common \nolink{block}.
247
248 \section{Namelist Entries}
249 \label{chap:namelistentries}
250 \textit{At least one language, Fortran 90, has the concept of a
251 namelist. A namelist is an ordered list of the names of some
252 set of declared objects. The namelist object itself may be used
253 as a replacement for the list of names in various contexts.}
254
255 A namelist is represented by a debugging information entry
256 with the 
257 tag \livetarg{chap:DWTAGnamelist}{DW\-\_TAG\-\_namelist}. 
258 If the namelist itself has a
259 name, the namelist entry has a \livelink{chap:DWATname}{DW\-\_AT\-\_name} attribute, whose
260 value is a null-terminated string containing the namelist’s
261 name as it appears in the source program.
262
263 Each name that is part of the namelist is represented
264 by a debugging information entry with the tag
265 \livetarg{chap:DWTAGnamelistitem}{DW\-\_TAG\-\_namelist\-\_item}. 
266 Each such entry is a child of the
267 namelist entry, and all of the namelist item entries for a
268 given namelist are ordered as were the list of names they
269 correspond to in the source program.
270
271 Each namelist item entry contains a \livelink{chap:DWATnamelistitem}{DW\-\_AT\-\_namelist\-\_item}
272 attribute whose value is a reference to the debugging
273 information entry representing the declaration of the item
274 whose name appears in the namelist.
275
276