Merge branch 'HEAD' of dwarfgit@dwarfstd.org:dwarf-doc.git
[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 
8 \livelink{chap:commonblockentry}{common 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 \DWTAGvariableTARG\addtoindexx{variable entry}, 
19 \DWTAGformalparameterTARG\addtoindexx{formal parameter entry} and 
20 \DWTAGconstantTARG\addtoindexx{constant (data) entry},
21 respectively.
22
23 \textit{The tag \DWTAGconstant{} 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 \DWATname{} attribute,\addtoindexx{name attribute}
30 whose value is a null-terminated string containing the data object 
31 name.
32
33 If a variable entry describes an anonymous object (for example
34 an \addtoindex{anonymous union}),
35 the name attribute is omitted or its value consists of a single
36 zero byte.
37
38 \item \hypertarget{chap:DWATexternalexternalvariable}{}
39 A \DWATexternalDEFN{} attribute,\addtoindexx{external attribute} 
40 which is a \livelink{chap:classflag}{flag}, if the name
41 of a variable is visible outside of its enclosing compilation
42 unit.  
43
44 \textit{The definitions of \addtoindex{C++} static data members 
45 of structures or classes are represented by variable entries 
46 \nolink{flagged} as external. Both file static and local variables 
47 in \addtoindex{C} and \addtoindex{C++} are represented by 
48 non-external variable entries.}
49
50 \item A \DWATdeclaration{} attribute, 
51 \addtoindexx{declaration attribute}
52 which is a \livelink{chap:classflag}{flag} that
53 indicates whether this entry represents a non-defining
54 declaration of an object.
55
56 \item A \DWATlocation{} attribute,
57 \addtoindexx{location attribute}
58 whose value describes the location of a variable or parameter at run-time.
59
60 If no location attribute is present in a variable 
61 entry representing the definition of a variable (that is,
62 \addtoindexx{declaration attribute}
63 with no 
64 \DWATdeclaration{} attribute),
65 or if the location attribute is present but has
66 an empty location description (as described in Section 
67 \refersec{chap:locationdescriptions}),
68 \addtoindexx{unallocated variable}
69 the variable is assumed to exist in the source code but not
70 in the executable program (but see number 10, below).
71
72 In a variable entry representing a non-defining declaration 
73 of a variable, the location specified supersedes the location 
74 specified by the defining declaration but only within the
75 scope of the variable entry; if no location is specified, 
76 then the location specified in the defining declaration 
77 applies.
78
79 \textit{This can occur, for example, for a \addtoindex{C} 
80 or \addtoindex{C++} external variable (one that is defined 
81 and allocated in another compilation unit) and whose location 
82 varies in the current unit due to optimization.}
83
84 The location of a variable may be further specified with 
85 \addtoindexx{segment attribute!and data segment}
86 a \DWATsegment{} attribute, if appropriate.
87
88 \item A \DWATtype{} attribute describing the type of the variable,
89 constant or formal parameter.
90
91 \item If the variable entry represents the defining declaration
92 for a C++ static data member of a structure, class or union,
93 the entry has a \DWATspecification{} attribute, whose value is a
94 \livelink{chap:classreference}{reference} to the debugging information entry representing the
95 declaration of this data member. The referenced entry has the
96 tag \DWTAGmember{} and will be a child of some class, structure
97 or union type entry.
98
99 If the variable entry represents a
100 non-defining declaration, \DWATspecification{} may be used
101 to reference the defining declaration of the variable. If
102 no \DWATspecification{} attribute is present, the defining
103 declaration may be found as a global definition either in the
104 current compilation unit or in another compilation unit with
105 the \DWATexternal{} attribute.  
106
107 Variable entries containing
108 the \DWATspecification{} attribute do not need to duplicate
109 information provided by the declaration entry referenced by
110 the specification attribute. In particular, such variable
111 entries do not need to contain attributes for the name or
112 type of the data member whose definition they represent.
113
114 \needlines{4}
115 \item \hypertarget{chap:DWATvariableparameternonconstantparameterflag}{}
116 A \DWATvariableparameterDEFN{}
117 attribute\addtoindexx{variable parameter attribute}, 
118 which is a \livelink{chap:classflag}{flag},
119 if a formal parameter entry represents a parameter whose
120 value in the calling function may be modified by the callee.
121 The absence of this attribute implies that the parameter\textquoteright s
122 value in the calling function cannot be modified by the callee.
123
124 \item \hypertarget{chap:DWATisoptionaloptionalparameter}{}
125 A \DWATisoptionalDEFN{} attribute,\addtoindexx{is optional attribute} 
126 which is a \livelink{chap:classflag}{flag}, if a
127 parameter entry represents an \addtoindex{optional parameter}.
128
129 \item \hypertarget{chap:DWATdefaultvaluedefaultvalueofparameter}{}
130 A \DWATdefaultvalueDEFN{} attribute\addtoindexx{default value attribute}
131 for \addtoindexx{formal parameter entry!with default value}
132 a formal parameter entry. 
133 The value of this attribute may be a constant, or a reference to the
134 debugging information entry for a variable, or a reference to a
135 debugging information entry containing a DWARF procedure.  If the
136 attribute form is of class constant, that constant is interpreted as
137 a value whose type is the same as 
138 the type of the formal parameter. If the attribute
139 form is of class reference, and the referenced entry is for a
140 variable, the default value of the parameter is the value of the
141 referenced variable.  If the reference value is 0, no default value
142 has been specified.  Otherwise, the attribute represents an implicit
143 \DWOPcallref{} to the referenced debugging information entry, and
144 the default value of the parameter is the value returned by that
145 DWARF procedure, interpreted as a value of the type of the formal
146 parameter.
147
148 \textit{For a constant form there is no way to 
149 express the absence of a default value.}
150
151 \item \hypertarget{chap:DWATconstvalueconstantobject}{}
152 A \DWATconstvalueDEFN{} attribute
153 \addtoindexx{constant value attribute}  
154 for an entry describing a
155 variable or formal parameter whose value is constant and not
156 represented by an object in the address space of the program,
157 or an entry describing a named constant. (Note that such
158 an entry does not have a location attribute.) The value of
159 this attribute may be a string or any of the constant data
160 or data block forms, 
161 as appropriate for the representation
162 of the variable's value. The value is the actual constant
163 value of the variable, represented as it would be on the
164 target architecture.  
165
166 \textit{One way in which a formal parameter
167 with a constant value and no location can arise is for a
168 formal parameter of an inlined subprogram that corresponds
169 to a constant actual parameter of a call that is inlined.}
170
171 \item \hypertarget{chap:DWATendianityendianityofdata}{}
172 A \DWATendianityDEFN{} attribute,
173 \addtoindexx{endianity attribute}
174 whose value is a constant that 
175 \addtoindexx{big-endian encoding|see{endianity attribute}}
176 specifies the endianity of the object. The value of
177 this attribute specifies an ABI-defined 
178 \byteorder{ing} \addtoindexx{ordering attribute} for
179 the value of the object. If omitted, the default endianity
180 of data for the given type is assumed.  
181
182 The set of values
183 and their meaning for this attribute is given in 
184 Table \ref{tab:endianityattributevalues}.
185 These represent the default encoding formats as defined by
186 the target architecture's ABI or processor definition. The
187 exact definition of these formats may differ in subtle ways
188 for different architectures.
189
190 \begin{table}[ht]
191 \caption{Endianity attribute values}
192 \label{tab:endianityattributevalues}
193 \centering
194 \begin{tabular}{l|P{9cm}}
195 \hline
196 Name&Meaning\\ \hline
197 \DWENDdefaultTARG{} &  Default endian encoding
198   (equivalent to the \mbox{absence} of a 
199   \DWATendianity{} attribute) \\
200 \DWENDbigTARG{} & Big-endian encoding \\
201 \DWENDlittleTARG& Little-endian encoding \\
202 \hline
203 \end{tabular}
204 \end{table}
205
206
207 \needlines{6}
208 \item \hypertarget{chap:DWATconstexprcompiletimeconstantobject}{}
209 A \DWATconstexprDEFN{} attribute,
210 \addtoindex{constant expression attribute}
211 which is a \CLASSflag, if a
212 variable entry represents a \addtoindex{C++} object declared with the
213 \texttt{constexpr} specifier. This attribute indicates that the
214 variable can be evaluated as a compile\dash time constant.  
215
216 \textit{In \addtoindex{C++},
217 a variable declared with \texttt{constexpr} is implicitly 
218 \texttt{const}. Such a variable has a \DWATtype{} attribute 
219 whose value is a \CLASSreference{} to a debugging information 
220 entry describing a \texttt{const} qualified type.}
221
222 \item A \DWATlinkagename{} 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 
231 \livetargi{chap:fortrancommonblock}{common}{Fortran!common block}
232 \livetargi{chap:commonblockentry}{block}{common block entry} 
233 may 
234 \addtoindexx{Fortran!common block}
235 be described by a debugging information entry with the 
236 tag \DWTAGcommonblockTARG. 
237
238 The common \nolink{block} 
239 entry has a \DWATname{} attribute\addtoindexx{name attribute}
240 whose value is a null-terminated string containing the
241 \livetargi{chap:commonblockreferenceattribute}{common block}{common block reference attribute} 
242 name. It may also have a \DWATlinkagename{} attribute as described 
243 in Section \refersec{chap:linkagenames}. 
244
245 A common block entry also has a \DWATlocation{} attribute
246 \addtoindexx{location attribute}
247 whose value describes the
248 location of the beginning of the common \nolink{block}. 
249
250 The common
251 \nolink{block} entry owns debugging information entries describing
252 the variables contained within the common \nolink{block}.
253
254 \textit{\addtoindex{Fortran} allows each declarer of a common block 
255 to independently define its contents; thus, common blocks are not types.}
256
257 \needlines{8}
258 \section{Namelist Entries}
259 \label{chap:namelistentries}
260 \textit{At least one language, Fortran 90, has the concept of a
261 namelist. A namelist is an ordered list of the names of some
262 set of declared objects. The namelist object itself may be used
263 as a replacement for the list of names in various contexts.}
264
265 A namelist is represented by a debugging information entry
266 with the tag \DWTAGnamelistTARG.\addtoindexx{namelist entry}
267 If the namelist itself has a
268 name, the namelist entry has a \DWATname{} attribute,
269 \addtoindexx{name attribute}
270 whose value is a null-terminated
271 string containing the namelist\textquoteright{}s
272 name.
273
274 Each\hypertarget{chap:DWATnamelistitemnamelistitem}{}
275 name that is part of the namelist is represented
276 by a debugging information entry with the tag
277 \DWTAGnamelistitemTARG. 
278 Each such entry is a child of the
279 namelist entry, and all of the 
280 namelist item entries for a
281 \addtoindexx{namelist item entry}
282 given namelist are ordered as were the list of names they
283 correspond to in the source program.
284
285 Each namelist item entry contains a 
286 \DWATnamelistitemDEFN{} attribute
287 \addtoindexx{namelist item attribute}
288 whose 
289 \addtoindexx{namelist item entry}
290 value is a \livelink{chap:classreference}{reference} to the debugging
291 information entry representing the declaration of the item
292 whose name appears in the namelist.
293
294