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