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