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