]>
Commit | Line | Data |
---|---|---|
64d5610f ML |
1 | \input texinfo @c -*-texinfo-*- |
2 | @c %**start of header | |
3 | @setfilename gnat_rm.info | |
4 | @documentencoding UTF-8 | |
5 | @ifinfo | |
1acce141 | 6 | @*Generated by Sphinx 4.3.2.@* |
64d5610f ML |
7 | @end ifinfo |
8 | @settitle GNAT Reference Manual | |
9 | @defindex ge | |
10 | @paragraphindent 0 | |
11 | @exampleindent 4 | |
12 | @finalout | |
13 | @dircategory GNU Ada Tools | |
14 | @direntry | |
15 | * gnat_rm: (gnat_rm.info). gnat_rm | |
16 | @end direntry | |
17 | ||
1acce141 YM |
18 | @definfoenclose strong,`,' |
19 | @definfoenclose emph,`,' | |
64d5610f ML |
20 | @c %**end of header |
21 | ||
22 | @copying | |
23 | @quotation | |
1acce141 | 24 | GNAT Reference Manual , Dec 14, 2023 |
64d5610f ML |
25 | |
26 | AdaCore | |
27 | ||
4e053a7e | 28 | Copyright @copyright{} 2008-2024, Free Software Foundation |
64d5610f ML |
29 | @end quotation |
30 | ||
31 | @end copying | |
32 | ||
33 | @titlepage | |
34 | @title GNAT Reference Manual | |
35 | @insertcopying | |
36 | @end titlepage | |
37 | @contents | |
38 | ||
39 | @c %** start of user preamble | |
40 | ||
41 | @c %** end of user preamble | |
42 | ||
43 | @ifnottex | |
44 | @node Top | |
45 | @top GNAT Reference Manual | |
46 | @insertcopying | |
47 | @end ifnottex | |
48 | ||
49 | @c %**start of body | |
50 | @anchor{gnat_rm doc}@anchor{0} | |
1acce141 | 51 | @emph{GNAT, The GNU Ada Development Environment} |
64d5610f ML |
52 | |
53 | ||
54 | @include gcc-common.texi | |
55 | GCC version @value{version-GCC}@* | |
56 | AdaCore | |
57 | ||
58 | Permission is granted to copy, distribute and/or modify this document | |
59 | under the terms of the GNU Free Documentation License, Version 1.3 or | |
60 | any later version published by the Free Software Foundation; with no | |
61 | Invariant Sections, with the Front-Cover Texts being “GNAT Reference | |
62 | Manual”, and with no Back-Cover Texts. A copy of the license is | |
63 | included in the section entitled @ref{1,,GNU Free Documentation License}. | |
64 | ||
65 | @menu | |
66 | * About This Guide:: | |
67 | * Implementation Defined Pragmas:: | |
68 | * Implementation Defined Aspects:: | |
69 | * Implementation Defined Attributes:: | |
70 | * Standard and Implementation Defined Restrictions:: | |
71 | * Implementation Advice:: | |
72 | * Implementation Defined Characteristics:: | |
73 | * Intrinsic Subprograms:: | |
74 | * Representation Clauses and Pragmas:: | |
75 | * Standard Library Routines:: | |
76 | * The Implementation of Standard I/O:: | |
77 | * The GNAT Library:: | |
78 | * Interfacing to Other Languages:: | |
79 | * Specialized Needs Annexes:: | |
80 | * Implementation of Specific Ada Features:: | |
81 | * Implementation of Ada 2012 Features:: | |
b71d4b62 | 82 | * GNAT language extensions:: |
64d5610f ML |
83 | * Security Hardening Features:: |
84 | * Obsolescent Features:: | |
85 | * Compatibility and Porting Guide:: | |
86 | * GNU Free Documentation License:: | |
87 | * Index:: | |
88 | ||
89 | @detailmenu | |
90 | --- The Detailed Node Listing --- | |
91 | ||
92 | About This Guide | |
93 | ||
94 | * What This Reference Manual Contains:: | |
95 | * Conventions:: | |
96 | * Related Information:: | |
97 | ||
98 | Implementation Defined Pragmas | |
99 | ||
100 | * Pragma Abort_Defer:: | |
101 | * Pragma Abstract_State:: | |
102 | * Pragma Ada_83:: | |
103 | * Pragma Ada_95:: | |
104 | * Pragma Ada_05:: | |
105 | * Pragma Ada_2005:: | |
106 | * Pragma Ada_12:: | |
107 | * Pragma Ada_2012:: | |
108 | * Pragma Ada_2022:: | |
109 | * Pragma Aggregate_Individually_Assign:: | |
110 | * Pragma Allow_Integer_Address:: | |
111 | * Pragma Annotate:: | |
112 | * Pragma Assert:: | |
113 | * Pragma Assert_And_Cut:: | |
114 | * Pragma Assertion_Policy:: | |
115 | * Pragma Assume:: | |
116 | * Pragma Assume_No_Invalid_Values:: | |
117 | * Pragma Async_Readers:: | |
118 | * Pragma Async_Writers:: | |
119 | * Pragma Attribute_Definition:: | |
120 | * Pragma C_Pass_By_Copy:: | |
121 | * Pragma Check:: | |
122 | * Pragma Check_Float_Overflow:: | |
123 | * Pragma Check_Name:: | |
124 | * Pragma Check_Policy:: | |
125 | * Pragma Comment:: | |
126 | * Pragma Common_Object:: | |
127 | * Pragma Compile_Time_Error:: | |
128 | * Pragma Compile_Time_Warning:: | |
129 | * Pragma Complete_Representation:: | |
130 | * Pragma Complex_Representation:: | |
131 | * Pragma Component_Alignment:: | |
132 | * Pragma Constant_After_Elaboration:: | |
133 | * Pragma Contract_Cases:: | |
134 | * Pragma Convention_Identifier:: | |
135 | * Pragma CPP_Class:: | |
136 | * Pragma CPP_Constructor:: | |
137 | * Pragma CPP_Virtual:: | |
138 | * Pragma CPP_Vtable:: | |
139 | * Pragma CPU:: | |
140 | * Pragma Deadline_Floor:: | |
64d5610f ML |
141 | * Pragma Debug:: |
142 | * Pragma Debug_Policy:: | |
6f089469 | 143 | * Pragma Default_Initial_Condition:: |
64d5610f ML |
144 | * Pragma Default_Scalar_Storage_Order:: |
145 | * Pragma Default_Storage_Pool:: | |
146 | * Pragma Depends:: | |
147 | * Pragma Detect_Blocking:: | |
148 | * Pragma Disable_Atomic_Synchronization:: | |
149 | * Pragma Dispatching_Domain:: | |
150 | * Pragma Effective_Reads:: | |
151 | * Pragma Effective_Writes:: | |
152 | * Pragma Elaboration_Checks:: | |
153 | * Pragma Eliminate:: | |
154 | * Pragma Enable_Atomic_Synchronization:: | |
155 | * Pragma Export_Function:: | |
156 | * Pragma Export_Object:: | |
157 | * Pragma Export_Procedure:: | |
158 | * Pragma Export_Valued_Procedure:: | |
159 | * Pragma Extend_System:: | |
160 | * Pragma Extensions_Allowed:: | |
161 | * Pragma Extensions_Visible:: | |
162 | * Pragma External:: | |
163 | * Pragma External_Name_Casing:: | |
164 | * Pragma Fast_Math:: | |
165 | * Pragma Favor_Top_Level:: | |
166 | * Pragma Finalize_Storage_Only:: | |
167 | * Pragma Float_Representation:: | |
168 | * Pragma Ghost:: | |
169 | * Pragma Global:: | |
170 | * Pragma Ident:: | |
171 | * Pragma Ignore_Pragma:: | |
172 | * Pragma Implementation_Defined:: | |
173 | * Pragma Implemented:: | |
174 | * Pragma Implicit_Packing:: | |
175 | * Pragma Import_Function:: | |
176 | * Pragma Import_Object:: | |
177 | * Pragma Import_Procedure:: | |
178 | * Pragma Import_Valued_Procedure:: | |
179 | * Pragma Independent:: | |
180 | * Pragma Independent_Components:: | |
181 | * Pragma Initial_Condition:: | |
182 | * Pragma Initialize_Scalars:: | |
183 | * Pragma Initializes:: | |
184 | * Pragma Inline_Always:: | |
185 | * Pragma Inline_Generic:: | |
186 | * Pragma Interface:: | |
187 | * Pragma Interface_Name:: | |
188 | * Pragma Interrupt_Handler:: | |
189 | * Pragma Interrupt_State:: | |
190 | * Pragma Invariant:: | |
191 | * Pragma Keep_Names:: | |
192 | * Pragma License:: | |
193 | * Pragma Link_With:: | |
194 | * Pragma Linker_Alias:: | |
195 | * Pragma Linker_Constructor:: | |
196 | * Pragma Linker_Destructor:: | |
197 | * Pragma Linker_Section:: | |
198 | * Pragma Lock_Free:: | |
199 | * Pragma Loop_Invariant:: | |
200 | * Pragma Loop_Optimize:: | |
201 | * Pragma Loop_Variant:: | |
202 | * Pragma Machine_Attribute:: | |
203 | * Pragma Main:: | |
204 | * Pragma Main_Storage:: | |
205 | * Pragma Max_Queue_Length:: | |
206 | * Pragma No_Body:: | |
207 | * Pragma No_Caching:: | |
208 | * Pragma No_Component_Reordering:: | |
209 | * Pragma No_Elaboration_Code_All:: | |
210 | * Pragma No_Heap_Finalization:: | |
211 | * Pragma No_Inline:: | |
212 | * Pragma No_Return:: | |
213 | * Pragma No_Strict_Aliasing:: | |
214 | * Pragma No_Tagged_Streams:: | |
215 | * Pragma Normalize_Scalars:: | |
216 | * Pragma Obsolescent:: | |
217 | * Pragma Optimize_Alignment:: | |
218 | * Pragma Ordered:: | |
219 | * Pragma Overflow_Mode:: | |
220 | * Pragma Overriding_Renamings:: | |
64d5610f | 221 | * Pragma Part_Of:: |
6f089469 | 222 | * Pragma Partition_Elaboration_Policy:: |
64d5610f ML |
223 | * Pragma Passive:: |
224 | * Pragma Persistent_BSS:: | |
225 | * Pragma Post:: | |
226 | * Pragma Postcondition:: | |
227 | * Pragma Post_Class:: | |
228 | * Pragma Pre:: | |
229 | * Pragma Precondition:: | |
230 | * Pragma Predicate:: | |
231 | * Pragma Predicate_Failure:: | |
232 | * Pragma Preelaborable_Initialization:: | |
233 | * Pragma Prefix_Exception_Messages:: | |
234 | * Pragma Pre_Class:: | |
235 | * Pragma Priority_Specific_Dispatching:: | |
236 | * Pragma Profile:: | |
237 | * Pragma Profile_Warnings:: | |
238 | * Pragma Propagate_Exceptions:: | |
239 | * Pragma Provide_Shift_Operators:: | |
240 | * Pragma Psect_Object:: | |
241 | * Pragma Pure_Function:: | |
242 | * Pragma Rational:: | |
243 | * Pragma Ravenscar:: | |
244 | * Pragma Refined_Depends:: | |
245 | * Pragma Refined_Global:: | |
246 | * Pragma Refined_Post:: | |
247 | * Pragma Refined_State:: | |
248 | * Pragma Relative_Deadline:: | |
249 | * Pragma Remote_Access_Type:: | |
250 | * Pragma Rename_Pragma:: | |
251 | * Pragma Restricted_Run_Time:: | |
252 | * Pragma Restriction_Warnings:: | |
253 | * Pragma Reviewable:: | |
254 | * Pragma Secondary_Stack_Size:: | |
255 | * Pragma Share_Generic:: | |
256 | * Pragma Shared:: | |
257 | * Pragma Short_Circuit_And_Or:: | |
258 | * Pragma Short_Descriptors:: | |
04d6c745 | 259 | * Pragma Side_Effects:: |
64d5610f ML |
260 | * Pragma Simple_Storage_Pool_Type:: |
261 | * Pragma Source_File_Name:: | |
262 | * Pragma Source_File_Name_Project:: | |
263 | * Pragma Source_Reference:: | |
264 | * Pragma SPARK_Mode:: | |
265 | * Pragma Static_Elaboration_Desired:: | |
266 | * Pragma Stream_Convert:: | |
267 | * Pragma Style_Checks:: | |
268 | * Pragma Subtitle:: | |
269 | * Pragma Suppress:: | |
270 | * Pragma Suppress_All:: | |
271 | * Pragma Suppress_Debug_Info:: | |
272 | * Pragma Suppress_Exception_Locations:: | |
273 | * Pragma Suppress_Initialization:: | |
274 | * Pragma Task_Name:: | |
275 | * Pragma Task_Storage:: | |
276 | * Pragma Test_Case:: | |
277 | * Pragma Thread_Local_Storage:: | |
278 | * Pragma Time_Slice:: | |
279 | * Pragma Title:: | |
280 | * Pragma Type_Invariant:: | |
281 | * Pragma Type_Invariant_Class:: | |
282 | * Pragma Unchecked_Union:: | |
283 | * Pragma Unevaluated_Use_Of_Old:: | |
9daee425 | 284 | * Pragma User_Aspect_Definition:: |
64d5610f ML |
285 | * Pragma Unimplemented_Unit:: |
286 | * Pragma Universal_Aliasing:: | |
287 | * Pragma Unmodified:: | |
288 | * Pragma Unreferenced:: | |
289 | * Pragma Unreferenced_Objects:: | |
290 | * Pragma Unreserve_All_Interrupts:: | |
291 | * Pragma Unsuppress:: | |
64d5610f | 292 | * Pragma Unused:: |
6f089469 | 293 | * Pragma Use_VADS_Size:: |
64d5610f ML |
294 | * Pragma Validity_Checks:: |
295 | * Pragma Volatile:: | |
296 | * Pragma Volatile_Full_Access:: | |
297 | * Pragma Volatile_Function:: | |
298 | * Pragma Warning_As_Error:: | |
299 | * Pragma Warnings:: | |
300 | * Pragma Weak_External:: | |
301 | * Pragma Wide_Character_Encoding:: | |
302 | ||
303 | Implementation Defined Aspects | |
304 | ||
305 | * Aspect Abstract_State:: | |
306 | * Aspect Annotate:: | |
307 | * Aspect Async_Readers:: | |
308 | * Aspect Async_Writers:: | |
309 | * Aspect Constant_After_Elaboration:: | |
310 | * Aspect Contract_Cases:: | |
311 | * Aspect Depends:: | |
312 | * Aspect Default_Initial_Condition:: | |
313 | * Aspect Dimension:: | |
314 | * Aspect Dimension_System:: | |
315 | * Aspect Disable_Controlled:: | |
316 | * Aspect Effective_Reads:: | |
317 | * Aspect Effective_Writes:: | |
318 | * Aspect Extensions_Visible:: | |
319 | * Aspect Favor_Top_Level:: | |
320 | * Aspect Ghost:: | |
067d80d8 | 321 | * Aspect Ghost_Predicate:: |
64d5610f ML |
322 | * Aspect Global:: |
323 | * Aspect Initial_Condition:: | |
324 | * Aspect Initializes:: | |
325 | * Aspect Inline_Always:: | |
326 | * Aspect Invariant:: | |
327 | * Aspect Invariant’Class:: | |
328 | * Aspect Iterable:: | |
329 | * Aspect Linker_Section:: | |
9daee425 | 330 | * Aspect Local_Restrictions:: |
64d5610f ML |
331 | * Aspect Lock_Free:: |
332 | * Aspect Max_Queue_Length:: | |
333 | * Aspect No_Caching:: | |
334 | * Aspect No_Elaboration_Code_All:: | |
335 | * Aspect No_Inline:: | |
336 | * Aspect No_Tagged_Streams:: | |
337 | * Aspect No_Task_Parts:: | |
338 | * Aspect Object_Size:: | |
339 | * Aspect Obsolescent:: | |
340 | * Aspect Part_Of:: | |
341 | * Aspect Persistent_BSS:: | |
342 | * Aspect Predicate:: | |
343 | * Aspect Pure_Function:: | |
344 | * Aspect Refined_Depends:: | |
345 | * Aspect Refined_Global:: | |
346 | * Aspect Refined_Post:: | |
347 | * Aspect Refined_State:: | |
348 | * Aspect Relaxed_Initialization:: | |
349 | * Aspect Remote_Access_Type:: | |
350 | * Aspect Secondary_Stack_Size:: | |
351 | * Aspect Scalar_Storage_Order:: | |
352 | * Aspect Shared:: | |
04d6c745 | 353 | * Aspect Side_Effects:: |
64d5610f ML |
354 | * Aspect Simple_Storage_Pool:: |
355 | * Aspect Simple_Storage_Pool_Type:: | |
356 | * Aspect SPARK_Mode:: | |
357 | * Aspect Suppress_Debug_Info:: | |
358 | * Aspect Suppress_Initialization:: | |
359 | * Aspect Test_Case:: | |
360 | * Aspect Thread_Local_Storage:: | |
361 | * Aspect Universal_Aliasing:: | |
362 | * Aspect Unmodified:: | |
363 | * Aspect Unreferenced:: | |
364 | * Aspect Unreferenced_Objects:: | |
9daee425 | 365 | * Aspect User_Aspect:: |
64d5610f ML |
366 | * Aspect Value_Size:: |
367 | * Aspect Volatile_Full_Access:: | |
368 | * Aspect Volatile_Function:: | |
369 | * Aspect Warnings:: | |
370 | ||
371 | Implementation Defined Attributes | |
372 | ||
373 | * Attribute Abort_Signal:: | |
374 | * Attribute Address_Size:: | |
375 | * Attribute Asm_Input:: | |
376 | * Attribute Asm_Output:: | |
377 | * Attribute Atomic_Always_Lock_Free:: | |
378 | * Attribute Bit:: | |
379 | * Attribute Bit_Position:: | |
380 | * Attribute Code_Address:: | |
381 | * Attribute Compiler_Version:: | |
382 | * Attribute Constrained:: | |
383 | * Attribute Default_Bit_Order:: | |
384 | * Attribute Default_Scalar_Storage_Order:: | |
385 | * Attribute Deref:: | |
386 | * Attribute Descriptor_Size:: | |
387 | * Attribute Elaborated:: | |
388 | * Attribute Elab_Body:: | |
389 | * Attribute Elab_Spec:: | |
390 | * Attribute Elab_Subp_Body:: | |
391 | * Attribute Emax:: | |
392 | * Attribute Enabled:: | |
393 | * Attribute Enum_Rep:: | |
394 | * Attribute Enum_Val:: | |
395 | * Attribute Epsilon:: | |
396 | * Attribute Fast_Math:: | |
397 | * Attribute Finalization_Size:: | |
398 | * Attribute Fixed_Value:: | |
399 | * Attribute From_Any:: | |
400 | * Attribute Has_Access_Values:: | |
401 | * Attribute Has_Discriminants:: | |
402 | * Attribute Has_Tagged_Values:: | |
403 | * Attribute Img:: | |
404 | * Attribute Initialized:: | |
405 | * Attribute Integer_Value:: | |
406 | * Attribute Invalid_Value:: | |
407 | * Attribute Iterable:: | |
408 | * Attribute Large:: | |
409 | * Attribute Library_Level:: | |
410 | * Attribute Loop_Entry:: | |
411 | * Attribute Machine_Size:: | |
412 | * Attribute Mantissa:: | |
413 | * Attribute Maximum_Alignment:: | |
414 | * Attribute Max_Integer_Size:: | |
415 | * Attribute Mechanism_Code:: | |
416 | * Attribute Null_Parameter:: | |
417 | * Attribute Object_Size:: | |
418 | * Attribute Old:: | |
419 | * Attribute Passed_By_Reference:: | |
420 | * Attribute Pool_Address:: | |
421 | * Attribute Range_Length:: | |
422 | * Attribute Restriction_Set:: | |
423 | * Attribute Result:: | |
424 | * Attribute Safe_Emax:: | |
425 | * Attribute Safe_Large:: | |
426 | * Attribute Safe_Small:: | |
427 | * Attribute Scalar_Storage_Order:: | |
428 | * Attribute Simple_Storage_Pool:: | |
429 | * Attribute Small:: | |
430 | * Attribute Small_Denominator:: | |
431 | * Attribute Small_Numerator:: | |
432 | * Attribute Storage_Unit:: | |
433 | * Attribute Stub_Type:: | |
434 | * Attribute System_Allocator_Alignment:: | |
435 | * Attribute Target_Name:: | |
436 | * Attribute To_Address:: | |
437 | * Attribute To_Any:: | |
438 | * Attribute Type_Class:: | |
439 | * Attribute Type_Key:: | |
440 | * Attribute TypeCode:: | |
441 | * Attribute Unconstrained_Array:: | |
442 | * Attribute Universal_Literal_String:: | |
443 | * Attribute Unrestricted_Access:: | |
444 | * Attribute Update:: | |
445 | * Attribute Valid_Value:: | |
446 | * Attribute Valid_Scalars:: | |
447 | * Attribute VADS_Size:: | |
448 | * Attribute Value_Size:: | |
449 | * Attribute Wchar_T_Size:: | |
450 | * Attribute Word_Size:: | |
451 | ||
452 | Standard and Implementation Defined Restrictions | |
453 | ||
454 | * Partition-Wide Restrictions:: | |
455 | * Program Unit Level Restrictions:: | |
456 | ||
457 | Partition-Wide Restrictions | |
458 | ||
459 | * Immediate_Reclamation:: | |
460 | * Max_Asynchronous_Select_Nesting:: | |
461 | * Max_Entry_Queue_Length:: | |
462 | * Max_Protected_Entries:: | |
463 | * Max_Select_Alternatives:: | |
464 | * Max_Storage_At_Blocking:: | |
465 | * Max_Task_Entries:: | |
466 | * Max_Tasks:: | |
467 | * No_Abort_Statements:: | |
468 | * No_Access_Parameter_Allocators:: | |
469 | * No_Access_Subprograms:: | |
470 | * No_Allocators:: | |
471 | * No_Anonymous_Allocators:: | |
472 | * No_Asynchronous_Control:: | |
473 | * No_Calendar:: | |
474 | * No_Coextensions:: | |
475 | * No_Default_Initialization:: | |
476 | * No_Delay:: | |
477 | * No_Dependence:: | |
478 | * No_Direct_Boolean_Operators:: | |
479 | * No_Dispatch:: | |
480 | * No_Dispatching_Calls:: | |
481 | * No_Dynamic_Attachment:: | |
482 | * No_Dynamic_Priorities:: | |
483 | * No_Entry_Calls_In_Elaboration_Code:: | |
484 | * No_Enumeration_Maps:: | |
485 | * No_Exception_Handlers:: | |
486 | * No_Exception_Propagation:: | |
487 | * No_Exception_Registration:: | |
488 | * No_Exceptions:: | |
489 | * No_Finalization:: | |
490 | * No_Fixed_Point:: | |
491 | * No_Floating_Point:: | |
492 | * No_Implicit_Conditionals:: | |
493 | * No_Implicit_Dynamic_Code:: | |
494 | * No_Implicit_Heap_Allocations:: | |
495 | * No_Implicit_Protected_Object_Allocations:: | |
496 | * No_Implicit_Task_Allocations:: | |
497 | * No_Initialize_Scalars:: | |
498 | * No_IO:: | |
499 | * No_Local_Allocators:: | |
500 | * No_Local_Protected_Objects:: | |
501 | * No_Local_Tagged_Types:: | |
502 | * No_Local_Timing_Events:: | |
503 | * No_Long_Long_Integers:: | |
504 | * No_Multiple_Elaboration:: | |
505 | * No_Nested_Finalization:: | |
506 | * No_Protected_Type_Allocators:: | |
507 | * No_Protected_Types:: | |
508 | * No_Recursion:: | |
509 | * No_Reentrancy:: | |
510 | * No_Relative_Delay:: | |
511 | * No_Requeue_Statements:: | |
512 | * No_Secondary_Stack:: | |
513 | * No_Select_Statements:: | |
514 | * No_Specific_Termination_Handlers:: | |
515 | * No_Specification_of_Aspect:: | |
516 | * No_Standard_Allocators_After_Elaboration:: | |
517 | * No_Standard_Storage_Pools:: | |
518 | * No_Stream_Optimizations:: | |
519 | * No_Streams:: | |
520 | * No_Tagged_Type_Registration:: | |
521 | * No_Task_Allocators:: | |
522 | * No_Task_At_Interrupt_Priority:: | |
523 | * No_Task_Attributes_Package:: | |
524 | * No_Task_Hierarchy:: | |
525 | * No_Task_Termination:: | |
526 | * No_Tasking:: | |
527 | * No_Terminate_Alternatives:: | |
528 | * No_Unchecked_Access:: | |
529 | * No_Unchecked_Conversion:: | |
530 | * No_Unchecked_Deallocation:: | |
73918baf | 531 | * No_Use_Of_Attribute:: |
64d5610f | 532 | * No_Use_Of_Entity:: |
73918baf | 533 | * No_Use_Of_Pragma:: |
64d5610f ML |
534 | * Pure_Barriers:: |
535 | * Simple_Barriers:: | |
536 | * Static_Priorities:: | |
537 | * Static_Storage_Size:: | |
538 | ||
539 | Program Unit Level Restrictions | |
540 | ||
541 | * No_Elaboration_Code:: | |
542 | * No_Dynamic_Accessibility_Checks:: | |
543 | * No_Dynamic_Sized_Objects:: | |
544 | * No_Entry_Queue:: | |
545 | * No_Implementation_Aspect_Specifications:: | |
546 | * No_Implementation_Attributes:: | |
547 | * No_Implementation_Identifiers:: | |
548 | * No_Implementation_Pragmas:: | |
549 | * No_Implementation_Restrictions:: | |
550 | * No_Implementation_Units:: | |
551 | * No_Implicit_Aliasing:: | |
552 | * No_Implicit_Loops:: | |
553 | * No_Obsolescent_Features:: | |
554 | * No_Wide_Characters:: | |
555 | * Static_Dispatch_Tables:: | |
556 | * SPARK_05:: | |
557 | ||
558 | Implementation Advice | |
559 | ||
560 | * RM 1.1.3(20); Error Detection: RM 1 1 3 20 Error Detection. | |
561 | * RM 1.1.3(31); Child Units: RM 1 1 3 31 Child Units. | |
562 | * RM 1.1.5(12); Bounded Errors: RM 1 1 5 12 Bounded Errors. | |
563 | * RM 2.8(16); Pragmas: RM 2 8 16 Pragmas. | |
564 | * RM 2.8(17-19); Pragmas: RM 2 8 17-19 Pragmas. | |
565 | * RM 3.5.2(5); Alternative Character Sets: RM 3 5 2 5 Alternative Character Sets. | |
566 | * RM 3.5.4(28); Integer Types: RM 3 5 4 28 Integer Types. | |
567 | * RM 3.5.4(29); Integer Types: RM 3 5 4 29 Integer Types. | |
568 | * RM 3.5.5(8); Enumeration Values: RM 3 5 5 8 Enumeration Values. | |
569 | * RM 3.5.7(17); Float Types: RM 3 5 7 17 Float Types. | |
570 | * RM 3.6.2(11); Multidimensional Arrays: RM 3 6 2 11 Multidimensional Arrays. | |
571 | * RM 9.6(30-31); Duration’Small: RM 9 6 30-31 Duration’Small. | |
572 | * RM 10.2.1(12); Consistent Representation: RM 10 2 1 12 Consistent Representation. | |
573 | * RM 11.4.1(19); Exception Information: RM 11 4 1 19 Exception Information. | |
574 | * RM 11.5(28); Suppression of Checks: RM 11 5 28 Suppression of Checks. | |
575 | * RM 13.1 (21-24); Representation Clauses: RM 13 1 21-24 Representation Clauses. | |
576 | * RM 13.2(6-8); Packed Types: RM 13 2 6-8 Packed Types. | |
577 | * RM 13.3(14-19); Address Clauses: RM 13 3 14-19 Address Clauses. | |
578 | * RM 13.3(29-35); Alignment Clauses: RM 13 3 29-35 Alignment Clauses. | |
579 | * RM 13.3(42-43); Size Clauses: RM 13 3 42-43 Size Clauses. | |
580 | * RM 13.3(50-56); Size Clauses: RM 13 3 50-56 Size Clauses. | |
581 | * RM 13.3(71-73); Component Size Clauses: RM 13 3 71-73 Component Size Clauses. | |
582 | * RM 13.4(9-10); Enumeration Representation Clauses: RM 13 4 9-10 Enumeration Representation Clauses. | |
583 | * RM 13.5.1(17-22); Record Representation Clauses: RM 13 5 1 17-22 Record Representation Clauses. | |
584 | * RM 13.5.2(5); Storage Place Attributes: RM 13 5 2 5 Storage Place Attributes. | |
585 | * RM 13.5.3(7-8); Bit Ordering: RM 13 5 3 7-8 Bit Ordering. | |
586 | * RM 13.7(37); Address as Private: RM 13 7 37 Address as Private. | |
587 | * RM 13.7.1(16); Address Operations: RM 13 7 1 16 Address Operations. | |
588 | * RM 13.9(14-17); Unchecked Conversion: RM 13 9 14-17 Unchecked Conversion. | |
589 | * RM 13.11(23-25); Implicit Heap Usage: RM 13 11 23-25 Implicit Heap Usage. | |
590 | * RM 13.11.2(17); Unchecked Deallocation: RM 13 11 2 17 Unchecked Deallocation. | |
591 | * RM 13.13.2(1.6); Stream Oriented Attributes: RM 13 13 2 1 6 Stream Oriented Attributes. | |
592 | * RM A.1(52); Names of Predefined Numeric Types: RM A 1 52 Names of Predefined Numeric Types. | |
593 | * RM A.3.2(49); Ada.Characters.Handling: RM A 3 2 49 Ada Characters Handling. | |
594 | * RM A.4.4(106); Bounded-Length String Handling: RM A 4 4 106 Bounded-Length String Handling. | |
595 | * RM A.5.2(46-47); Random Number Generation: RM A 5 2 46-47 Random Number Generation. | |
596 | * RM A.10.7(23); Get_Immediate: RM A 10 7 23 Get_Immediate. | |
597 | * RM A.18; Containers: RM A 18 Containers. | |
598 | * RM B.1(39-41); Pragma Export: RM B 1 39-41 Pragma Export. | |
599 | * RM B.2(12-13); Package Interfaces: RM B 2 12-13 Package Interfaces. | |
600 | * RM B.3(63-71); Interfacing with C: RM B 3 63-71 Interfacing with C. | |
601 | * RM B.4(95-98); Interfacing with COBOL: RM B 4 95-98 Interfacing with COBOL. | |
602 | * RM B.5(22-26); Interfacing with Fortran: RM B 5 22-26 Interfacing with Fortran. | |
603 | * RM C.1(3-5); Access to Machine Operations: RM C 1 3-5 Access to Machine Operations. | |
604 | * RM C.1(10-16); Access to Machine Operations: RM C 1 10-16 Access to Machine Operations. | |
605 | * RM C.3(28); Interrupt Support: RM C 3 28 Interrupt Support. | |
606 | * RM C.3.1(20-21); Protected Procedure Handlers: RM C 3 1 20-21 Protected Procedure Handlers. | |
607 | * RM C.3.2(25); Package Interrupts: RM C 3 2 25 Package Interrupts. | |
608 | * RM C.4(14); Pre-elaboration Requirements: RM C 4 14 Pre-elaboration Requirements. | |
609 | * RM C.5(8); Pragma Discard_Names: RM C 5 8 Pragma Discard_Names. | |
610 | * RM C.7.2(30); The Package Task_Attributes: RM C 7 2 30 The Package Task_Attributes. | |
611 | * RM D.3(17); Locking Policies: RM D 3 17 Locking Policies. | |
612 | * RM D.4(16); Entry Queuing Policies: RM D 4 16 Entry Queuing Policies. | |
613 | * RM D.6(9-10); Preemptive Abort: RM D 6 9-10 Preemptive Abort. | |
614 | * RM D.7(21); Tasking Restrictions: RM D 7 21 Tasking Restrictions. | |
615 | * RM D.8(47-49); Monotonic Time: RM D 8 47-49 Monotonic Time. | |
616 | * RM E.5(28-29); Partition Communication Subsystem: RM E 5 28-29 Partition Communication Subsystem. | |
617 | * RM F(7); COBOL Support: RM F 7 COBOL Support. | |
618 | * RM F.1(2); Decimal Radix Support: RM F 1 2 Decimal Radix Support. | |
619 | * RM G; Numerics: RM G Numerics. | |
620 | * RM G.1.1(56-58); Complex Types: RM G 1 1 56-58 Complex Types. | |
621 | * RM G.1.2(49); Complex Elementary Functions: RM G 1 2 49 Complex Elementary Functions. | |
622 | * RM G.2.4(19); Accuracy Requirements: RM G 2 4 19 Accuracy Requirements. | |
623 | * RM G.2.6(15); Complex Arithmetic Accuracy: RM G 2 6 15 Complex Arithmetic Accuracy. | |
624 | * RM H.6(15/2); Pragma Partition_Elaboration_Policy: RM H 6 15/2 Pragma Partition_Elaboration_Policy. | |
625 | ||
626 | Intrinsic Subprograms | |
627 | ||
628 | * Intrinsic Operators:: | |
629 | * Compilation_ISO_Date:: | |
630 | * Compilation_Date:: | |
631 | * Compilation_Time:: | |
632 | * Enclosing_Entity:: | |
633 | * Exception_Information:: | |
634 | * Exception_Message:: | |
635 | * Exception_Name:: | |
636 | * File:: | |
637 | * Line:: | |
638 | * Shifts and Rotates:: | |
639 | * Source_Location:: | |
640 | ||
641 | Representation Clauses and Pragmas | |
642 | ||
643 | * Alignment Clauses:: | |
644 | * Size Clauses:: | |
645 | * Storage_Size Clauses:: | |
646 | * Size of Variant Record Objects:: | |
647 | * Biased Representation:: | |
648 | * Value_Size and Object_Size Clauses:: | |
649 | * Component_Size Clauses:: | |
650 | * Bit_Order Clauses:: | |
651 | * Effect of Bit_Order on Byte Ordering:: | |
652 | * Pragma Pack for Arrays:: | |
653 | * Pragma Pack for Records:: | |
654 | * Record Representation Clauses:: | |
655 | * Handling of Records with Holes:: | |
656 | * Enumeration Clauses:: | |
657 | * Address Clauses:: | |
658 | * Use of Address Clauses for Memory-Mapped I/O:: | |
659 | * Effect of Convention on Representation:: | |
660 | * Conventions and Anonymous Access Types:: | |
661 | * Determining the Representations chosen by GNAT:: | |
662 | ||
663 | The Implementation of Standard I/O | |
664 | ||
665 | * Standard I/O Packages:: | |
666 | * FORM Strings:: | |
667 | * Direct_IO:: | |
668 | * Sequential_IO:: | |
669 | * Text_IO:: | |
670 | * Wide_Text_IO:: | |
671 | * Wide_Wide_Text_IO:: | |
672 | * Stream_IO:: | |
673 | * Text Translation:: | |
674 | * Shared Files:: | |
675 | * Filenames encoding:: | |
676 | * File content encoding:: | |
677 | * Open Modes:: | |
678 | * Operations on C Streams:: | |
679 | * Interfacing to C Streams:: | |
680 | ||
681 | Text_IO | |
682 | ||
683 | * Stream Pointer Positioning:: | |
684 | * Reading and Writing Non-Regular Files:: | |
685 | * Get_Immediate:: | |
686 | * Treating Text_IO Files as Streams:: | |
687 | * Text_IO Extensions:: | |
688 | * Text_IO Facilities for Unbounded Strings:: | |
689 | ||
690 | Wide_Text_IO | |
691 | ||
692 | * Stream Pointer Positioning: Stream Pointer Positioning<2>. | |
693 | * Reading and Writing Non-Regular Files: Reading and Writing Non-Regular Files<2>. | |
694 | ||
695 | Wide_Wide_Text_IO | |
696 | ||
697 | * Stream Pointer Positioning: Stream Pointer Positioning<3>. | |
698 | * Reading and Writing Non-Regular Files: Reading and Writing Non-Regular Files<3>. | |
699 | ||
700 | The GNAT Library | |
701 | ||
702 | * Ada.Characters.Latin_9 (a-chlat9.ads): Ada Characters Latin_9 a-chlat9 ads. | |
703 | * Ada.Characters.Wide_Latin_1 (a-cwila1.ads): Ada Characters Wide_Latin_1 a-cwila1 ads. | |
eeba836b | 704 | * Ada.Characters.Wide_Latin_9 (a-cwila9.ads): Ada Characters Wide_Latin_9 a-cwila9 ads. |
64d5610f ML |
705 | * Ada.Characters.Wide_Wide_Latin_1 (a-chzla1.ads): Ada Characters Wide_Wide_Latin_1 a-chzla1 ads. |
706 | * Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads): Ada Characters Wide_Wide_Latin_9 a-chzla9 ads. | |
707 | * Ada.Containers.Bounded_Holders (a-coboho.ads): Ada Containers Bounded_Holders a-coboho ads. | |
708 | * Ada.Command_Line.Environment (a-colien.ads): Ada Command_Line Environment a-colien ads. | |
709 | * Ada.Command_Line.Remove (a-colire.ads): Ada Command_Line Remove a-colire ads. | |
710 | * Ada.Command_Line.Response_File (a-clrefi.ads): Ada Command_Line Response_File a-clrefi ads. | |
711 | * Ada.Direct_IO.C_Streams (a-diocst.ads): Ada Direct_IO C_Streams a-diocst ads. | |
712 | * Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads): Ada Exceptions Is_Null_Occurrence a-einuoc ads. | |
713 | * Ada.Exceptions.Last_Chance_Handler (a-elchha.ads): Ada Exceptions Last_Chance_Handler a-elchha ads. | |
714 | * Ada.Exceptions.Traceback (a-exctra.ads): Ada Exceptions Traceback a-exctra ads. | |
715 | * Ada.Sequential_IO.C_Streams (a-siocst.ads): Ada Sequential_IO C_Streams a-siocst ads. | |
716 | * Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads): Ada Streams Stream_IO C_Streams a-ssicst ads. | |
717 | * Ada.Strings.Unbounded.Text_IO (a-suteio.ads): Ada Strings Unbounded Text_IO a-suteio ads. | |
718 | * Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads): Ada Strings Wide_Unbounded Wide_Text_IO a-swuwti ads. | |
719 | * Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads): Ada Strings Wide_Wide_Unbounded Wide_Wide_Text_IO a-szuzti ads. | |
720 | * Ada.Task_Initialization (a-tasini.ads): Ada Task_Initialization a-tasini ads. | |
721 | * Ada.Text_IO.C_Streams (a-tiocst.ads): Ada Text_IO C_Streams a-tiocst ads. | |
722 | * Ada.Text_IO.Reset_Standard_Files (a-tirsfi.ads): Ada Text_IO Reset_Standard_Files a-tirsfi ads. | |
723 | * Ada.Wide_Characters.Unicode (a-wichun.ads): Ada Wide_Characters Unicode a-wichun ads. | |
724 | * Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads): Ada Wide_Text_IO C_Streams a-wtcstr ads. | |
725 | * Ada.Wide_Text_IO.Reset_Standard_Files (a-wrstfi.ads): Ada Wide_Text_IO Reset_Standard_Files a-wrstfi ads. | |
726 | * Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads): Ada Wide_Wide_Characters Unicode a-zchuni ads. | |
727 | * Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads): Ada Wide_Wide_Text_IO C_Streams a-ztcstr ads. | |
728 | * Ada.Wide_Wide_Text_IO.Reset_Standard_Files (a-zrstfi.ads): Ada Wide_Wide_Text_IO Reset_Standard_Files a-zrstfi ads. | |
729 | * GNAT.Altivec (g-altive.ads): GNAT Altivec g-altive ads. | |
730 | * GNAT.Altivec.Conversions (g-altcon.ads): GNAT Altivec Conversions g-altcon ads. | |
731 | * GNAT.Altivec.Vector_Operations (g-alveop.ads): GNAT Altivec Vector_Operations g-alveop ads. | |
732 | * GNAT.Altivec.Vector_Types (g-alvety.ads): GNAT Altivec Vector_Types g-alvety ads. | |
733 | * GNAT.Altivec.Vector_Views (g-alvevi.ads): GNAT Altivec Vector_Views g-alvevi ads. | |
734 | * GNAT.Array_Split (g-arrspl.ads): GNAT Array_Split g-arrspl ads. | |
735 | * GNAT.AWK (g-awk.ads): GNAT AWK g-awk ads. | |
736 | * GNAT.Binary_Search (g-binsea.ads): GNAT Binary_Search g-binsea ads. | |
737 | * GNAT.Bind_Environment (g-binenv.ads): GNAT Bind_Environment g-binenv ads. | |
738 | * GNAT.Branch_Prediction (g-brapre.ads): GNAT Branch_Prediction g-brapre ads. | |
739 | * GNAT.Bounded_Buffers (g-boubuf.ads): GNAT Bounded_Buffers g-boubuf ads. | |
740 | * GNAT.Bounded_Mailboxes (g-boumai.ads): GNAT Bounded_Mailboxes g-boumai ads. | |
741 | * GNAT.Bubble_Sort (g-bubsor.ads): GNAT Bubble_Sort g-bubsor ads. | |
742 | * GNAT.Bubble_Sort_A (g-busora.ads): GNAT Bubble_Sort_A g-busora ads. | |
743 | * GNAT.Bubble_Sort_G (g-busorg.ads): GNAT Bubble_Sort_G g-busorg ads. | |
744 | * GNAT.Byte_Order_Mark (g-byorma.ads): GNAT Byte_Order_Mark g-byorma ads. | |
745 | * GNAT.Byte_Swapping (g-bytswa.ads): GNAT Byte_Swapping g-bytswa ads. | |
746 | * GNAT.Calendar (g-calend.ads): GNAT Calendar g-calend ads. | |
747 | * GNAT.Calendar.Time_IO (g-catiio.ads): GNAT Calendar Time_IO g-catiio ads. | |
748 | * GNAT.CRC32 (g-crc32.ads): GNAT CRC32 g-crc32 ads. | |
749 | * GNAT.Case_Util (g-casuti.ads): GNAT Case_Util g-casuti ads. | |
750 | * GNAT.CGI (g-cgi.ads): GNAT CGI g-cgi ads. | |
751 | * GNAT.CGI.Cookie (g-cgicoo.ads): GNAT CGI Cookie g-cgicoo ads. | |
752 | * GNAT.CGI.Debug (g-cgideb.ads): GNAT CGI Debug g-cgideb ads. | |
753 | * GNAT.Command_Line (g-comlin.ads): GNAT Command_Line g-comlin ads. | |
754 | * GNAT.Compiler_Version (g-comver.ads): GNAT Compiler_Version g-comver ads. | |
755 | * GNAT.Ctrl_C (g-ctrl_c.ads): GNAT Ctrl_C g-ctrl_c ads. | |
756 | * GNAT.Current_Exception (g-curexc.ads): GNAT Current_Exception g-curexc ads. | |
757 | * GNAT.Debug_Pools (g-debpoo.ads): GNAT Debug_Pools g-debpoo ads. | |
758 | * GNAT.Debug_Utilities (g-debuti.ads): GNAT Debug_Utilities g-debuti ads. | |
759 | * GNAT.Decode_String (g-decstr.ads): GNAT Decode_String g-decstr ads. | |
760 | * GNAT.Decode_UTF8_String (g-deutst.ads): GNAT Decode_UTF8_String g-deutst ads. | |
761 | * GNAT.Directory_Operations (g-dirope.ads): GNAT Directory_Operations g-dirope ads. | |
762 | * GNAT.Directory_Operations.Iteration (g-diopit.ads): GNAT Directory_Operations Iteration g-diopit ads. | |
763 | * GNAT.Dynamic_HTables (g-dynhta.ads): GNAT Dynamic_HTables g-dynhta ads. | |
764 | * GNAT.Dynamic_Tables (g-dyntab.ads): GNAT Dynamic_Tables g-dyntab ads. | |
765 | * GNAT.Encode_String (g-encstr.ads): GNAT Encode_String g-encstr ads. | |
766 | * GNAT.Encode_UTF8_String (g-enutst.ads): GNAT Encode_UTF8_String g-enutst ads. | |
767 | * GNAT.Exception_Actions (g-excact.ads): GNAT Exception_Actions g-excact ads. | |
768 | * GNAT.Exception_Traces (g-exctra.ads): GNAT Exception_Traces g-exctra ads. | |
769 | * GNAT.Exceptions (g-except.ads): GNAT Exceptions g-except ads. | |
770 | * GNAT.Expect (g-expect.ads): GNAT Expect g-expect ads. | |
771 | * GNAT.Expect.TTY (g-exptty.ads): GNAT Expect TTY g-exptty ads. | |
772 | * GNAT.Float_Control (g-flocon.ads): GNAT Float_Control g-flocon ads. | |
773 | * GNAT.Formatted_String (g-forstr.ads): GNAT Formatted_String g-forstr ads. | |
774 | * GNAT.Generic_Fast_Math_Functions (g-gfmafu.ads): GNAT Generic_Fast_Math_Functions g-gfmafu ads. | |
775 | * GNAT.Heap_Sort (g-heasor.ads): GNAT Heap_Sort g-heasor ads. | |
776 | * GNAT.Heap_Sort_A (g-hesora.ads): GNAT Heap_Sort_A g-hesora ads. | |
777 | * GNAT.Heap_Sort_G (g-hesorg.ads): GNAT Heap_Sort_G g-hesorg ads. | |
778 | * GNAT.HTable (g-htable.ads): GNAT HTable g-htable ads. | |
779 | * GNAT.IO (g-io.ads): GNAT IO g-io ads. | |
780 | * GNAT.IO_Aux (g-io_aux.ads): GNAT IO_Aux g-io_aux ads. | |
781 | * GNAT.Lock_Files (g-locfil.ads): GNAT Lock_Files g-locfil ads. | |
782 | * GNAT.MBBS_Discrete_Random (g-mbdira.ads): GNAT MBBS_Discrete_Random g-mbdira ads. | |
783 | * GNAT.MBBS_Float_Random (g-mbflra.ads): GNAT MBBS_Float_Random g-mbflra ads. | |
784 | * GNAT.MD5 (g-md5.ads): GNAT MD5 g-md5 ads. | |
785 | * GNAT.Memory_Dump (g-memdum.ads): GNAT Memory_Dump g-memdum ads. | |
786 | * GNAT.Most_Recent_Exception (g-moreex.ads): GNAT Most_Recent_Exception g-moreex ads. | |
787 | * GNAT.OS_Lib (g-os_lib.ads): GNAT OS_Lib g-os_lib ads. | |
788 | * GNAT.Perfect_Hash_Generators (g-pehage.ads): GNAT Perfect_Hash_Generators g-pehage ads. | |
789 | * GNAT.Random_Numbers (g-rannum.ads): GNAT Random_Numbers g-rannum ads. | |
790 | * GNAT.Regexp (g-regexp.ads): GNAT Regexp g-regexp ads. | |
791 | * GNAT.Registry (g-regist.ads): GNAT Registry g-regist ads. | |
792 | * GNAT.Regpat (g-regpat.ads): GNAT Regpat g-regpat ads. | |
793 | * GNAT.Rewrite_Data (g-rewdat.ads): GNAT Rewrite_Data g-rewdat ads. | |
794 | * GNAT.Secondary_Stack_Info (g-sestin.ads): GNAT Secondary_Stack_Info g-sestin ads. | |
795 | * GNAT.Semaphores (g-semaph.ads): GNAT Semaphores g-semaph ads. | |
796 | * GNAT.Serial_Communications (g-sercom.ads): GNAT Serial_Communications g-sercom ads. | |
797 | * GNAT.SHA1 (g-sha1.ads): GNAT SHA1 g-sha1 ads. | |
798 | * GNAT.SHA224 (g-sha224.ads): GNAT SHA224 g-sha224 ads. | |
799 | * GNAT.SHA256 (g-sha256.ads): GNAT SHA256 g-sha256 ads. | |
800 | * GNAT.SHA384 (g-sha384.ads): GNAT SHA384 g-sha384 ads. | |
801 | * GNAT.SHA512 (g-sha512.ads): GNAT SHA512 g-sha512 ads. | |
802 | * GNAT.Signals (g-signal.ads): GNAT Signals g-signal ads. | |
803 | * GNAT.Sockets (g-socket.ads): GNAT Sockets g-socket ads. | |
804 | * GNAT.Source_Info (g-souinf.ads): GNAT Source_Info g-souinf ads. | |
805 | * GNAT.Spelling_Checker (g-speche.ads): GNAT Spelling_Checker g-speche ads. | |
806 | * GNAT.Spelling_Checker_Generic (g-spchge.ads): GNAT Spelling_Checker_Generic g-spchge ads. | |
807 | * GNAT.Spitbol.Patterns (g-spipat.ads): GNAT Spitbol Patterns g-spipat ads. | |
808 | * GNAT.Spitbol (g-spitbo.ads): GNAT Spitbol g-spitbo ads. | |
809 | * GNAT.Spitbol.Table_Boolean (g-sptabo.ads): GNAT Spitbol Table_Boolean g-sptabo ads. | |
810 | * GNAT.Spitbol.Table_Integer (g-sptain.ads): GNAT Spitbol Table_Integer g-sptain ads. | |
811 | * GNAT.Spitbol.Table_VString (g-sptavs.ads): GNAT Spitbol Table_VString g-sptavs ads. | |
812 | * GNAT.SSE (g-sse.ads): GNAT SSE g-sse ads. | |
813 | * GNAT.SSE.Vector_Types (g-ssvety.ads): GNAT SSE Vector_Types g-ssvety ads. | |
814 | * GNAT.String_Hash (g-strhas.ads): GNAT String_Hash g-strhas ads. | |
815 | * GNAT.Strings (g-string.ads): GNAT Strings g-string ads. | |
816 | * GNAT.String_Split (g-strspl.ads): GNAT String_Split g-strspl ads. | |
817 | * GNAT.Table (g-table.ads): GNAT Table g-table ads. | |
818 | * GNAT.Task_Lock (g-tasloc.ads): GNAT Task_Lock g-tasloc ads. | |
819 | * GNAT.Time_Stamp (g-timsta.ads): GNAT Time_Stamp g-timsta ads. | |
820 | * GNAT.Threads (g-thread.ads): GNAT Threads g-thread ads. | |
821 | * GNAT.Traceback (g-traceb.ads): GNAT Traceback g-traceb ads. | |
822 | * GNAT.Traceback.Symbolic (g-trasym.ads): GNAT Traceback Symbolic g-trasym ads. | |
eeba836b RD |
823 | * GNAT.UTF_32 (g-utf_32.ads): GNAT UTF_32 g-utf_32 ads. |
824 | * GNAT.UTF_32_Spelling_Checker (g-u3spch.ads): GNAT UTF_32_Spelling_Checker g-u3spch ads. | |
64d5610f ML |
825 | * GNAT.Wide_Spelling_Checker (g-wispch.ads): GNAT Wide_Spelling_Checker g-wispch ads. |
826 | * GNAT.Wide_String_Split (g-wistsp.ads): GNAT Wide_String_Split g-wistsp ads. | |
827 | * GNAT.Wide_Wide_Spelling_Checker (g-zspche.ads): GNAT Wide_Wide_Spelling_Checker g-zspche ads. | |
828 | * GNAT.Wide_Wide_String_Split (g-zistsp.ads): GNAT Wide_Wide_String_Split g-zistsp ads. | |
829 | * Interfaces.C.Extensions (i-cexten.ads): Interfaces C Extensions i-cexten ads. | |
830 | * Interfaces.C.Streams (i-cstrea.ads): Interfaces C Streams i-cstrea ads. | |
831 | * Interfaces.Packed_Decimal (i-pacdec.ads): Interfaces Packed_Decimal i-pacdec ads. | |
832 | * Interfaces.VxWorks (i-vxwork.ads): Interfaces VxWorks i-vxwork ads. | |
833 | * Interfaces.VxWorks.Int_Connection (i-vxinco.ads): Interfaces VxWorks Int_Connection i-vxinco ads. | |
834 | * Interfaces.VxWorks.IO (i-vxwoio.ads): Interfaces VxWorks IO i-vxwoio ads. | |
835 | * System.Address_Image (s-addima.ads): System Address_Image s-addima ads. | |
836 | * System.Assertions (s-assert.ads): System Assertions s-assert ads. | |
837 | * System.Atomic_Counters (s-atocou.ads): System Atomic_Counters s-atocou ads. | |
838 | * System.Memory (s-memory.ads): System Memory s-memory ads. | |
839 | * System.Multiprocessors (s-multip.ads): System Multiprocessors s-multip ads. | |
840 | * System.Multiprocessors.Dispatching_Domains (s-mudido.ads): System Multiprocessors Dispatching_Domains s-mudido ads. | |
841 | * System.Partition_Interface (s-parint.ads): System Partition_Interface s-parint ads. | |
842 | * System.Pool_Global (s-pooglo.ads): System Pool_Global s-pooglo ads. | |
843 | * System.Pool_Local (s-pooloc.ads): System Pool_Local s-pooloc ads. | |
844 | * System.Restrictions (s-restri.ads): System Restrictions s-restri ads. | |
845 | * System.Rident (s-rident.ads): System Rident s-rident ads. | |
846 | * System.Strings.Stream_Ops (s-ststop.ads): System Strings Stream_Ops s-ststop ads. | |
847 | * System.Unsigned_Types (s-unstyp.ads): System Unsigned_Types s-unstyp ads. | |
848 | * System.Wch_Cnv (s-wchcnv.ads): System Wch_Cnv s-wchcnv ads. | |
849 | * System.Wch_Con (s-wchcon.ads): System Wch_Con s-wchcon ads. | |
850 | ||
851 | Interfacing to Other Languages | |
852 | ||
853 | * Interfacing to C:: | |
854 | * Interfacing to C++:: | |
855 | * Interfacing to COBOL:: | |
856 | * Interfacing to Fortran:: | |
857 | * Interfacing to non-GNAT Ada code:: | |
858 | ||
859 | Implementation of Specific Ada Features | |
860 | ||
861 | * Machine Code Insertions:: | |
862 | * GNAT Implementation of Tasking:: | |
863 | * GNAT Implementation of Shared Passive Packages:: | |
864 | * Code Generation for Array Aggregates:: | |
865 | * The Size of Discriminated Records with Default Discriminants:: | |
866 | * Image Values For Nonscalar Types:: | |
867 | * Strict Conformance to the Ada Reference Manual:: | |
868 | ||
869 | GNAT Implementation of Tasking | |
870 | ||
871 | * Mapping Ada Tasks onto the Underlying Kernel Threads:: | |
872 | * Ensuring Compliance with the Real-Time Annex:: | |
873 | * Support for Locking Policies:: | |
874 | ||
875 | Code Generation for Array Aggregates | |
876 | ||
877 | * Static constant aggregates with static bounds:: | |
878 | * Constant aggregates with unconstrained nominal types:: | |
879 | * Aggregates with static bounds:: | |
880 | * Aggregates with nonstatic bounds:: | |
881 | * Aggregates in assignment statements:: | |
882 | ||
b71d4b62 RA |
883 | GNAT language extensions |
884 | ||
885 | * How to activate the extended GNAT Ada superset:: | |
886 | * Curated Extensions:: | |
887 | * Experimental Language Extensions:: | |
888 | ||
889 | Curated Extensions | |
890 | ||
9105cd90 | 891 | * Local Declarations Without Block:: |
b71d4b62 RA |
892 | * Conditional when constructs:: |
893 | * Case pattern matching:: | |
894 | * Fixed lower bounds for array types and subtypes:: | |
895 | * Prefixed-view notation for calls to primitive subprograms of untagged types:: | |
896 | * Expression defaults for generic formal functions:: | |
897 | * String interpolation:: | |
898 | * Constrained attribute for generic objects:: | |
899 | * Static aspect on intrinsic functions:: | |
900 | ||
901 | Experimental Language Extensions | |
902 | ||
903 | * Pragma Storage_Model:: | |
904 | * Simpler accessibility model:: | |
905 | ||
64d5610f ML |
906 | Security Hardening Features |
907 | ||
908 | * Register Scrubbing:: | |
909 | * Stack Scrubbing:: | |
910 | * Hardened Conditionals:: | |
911 | * Hardened Booleans:: | |
912 | * Control Flow Redundancy:: | |
913 | ||
914 | Obsolescent Features | |
915 | ||
916 | * pragma No_Run_Time:: | |
917 | * pragma Ravenscar:: | |
918 | * pragma Restricted_Run_Time:: | |
919 | * pragma Task_Info:: | |
920 | * package System.Task_Info (s-tasinf.ads): package System Task_Info s-tasinf ads. | |
921 | ||
922 | Compatibility and Porting Guide | |
923 | ||
924 | * Writing Portable Fixed-Point Declarations:: | |
925 | * Compatibility with Ada 83:: | |
926 | * Compatibility between Ada 95 and Ada 2005:: | |
927 | * Implementation-dependent characteristics:: | |
928 | * Compatibility with Other Ada Systems:: | |
929 | * Representation Clauses:: | |
930 | * Compatibility with HP Ada 83:: | |
931 | ||
932 | Compatibility with Ada 83 | |
933 | ||
934 | * Legal Ada 83 programs that are illegal in Ada 95:: | |
935 | * More deterministic semantics:: | |
936 | * Changed semantics:: | |
937 | * Other language compatibility issues:: | |
938 | ||
939 | Implementation-dependent characteristics | |
940 | ||
941 | * Implementation-defined pragmas:: | |
942 | * Implementation-defined attributes:: | |
943 | * Libraries:: | |
944 | * Elaboration order:: | |
945 | * Target-specific aspects:: | |
946 | ||
947 | @end detailmenu | |
948 | @end menu | |
949 | ||
950 | @node About This Guide,Implementation Defined Pragmas,Top,Top | |
951 | @anchor{gnat_rm/about_this_guide doc}@anchor{2}@anchor{gnat_rm/about_this_guide about-this-guide}@anchor{3}@anchor{gnat_rm/about_this_guide gnat-reference-manual}@anchor{4}@anchor{gnat_rm/about_this_guide id1}@anchor{5} | |
952 | @chapter About This Guide | |
953 | ||
954 | ||
955 | ||
956 | This manual contains useful information in writing programs using the | |
957 | GNAT compiler. It includes information on implementation dependent | |
958 | characteristics of GNAT, including all the information required by | |
959 | Annex M of the Ada language standard. | |
960 | ||
961 | GNAT implements Ada 95, Ada 2005 and Ada 2012, and it may also be | |
962 | invoked in Ada 83 compatibility mode. | |
963 | By default, GNAT assumes Ada 2012, | |
964 | but you can override with a compiler switch | |
965 | to explicitly specify the language version. | |
1acce141 | 966 | (Please refer to the @emph{GNAT User’s Guide} for details on these switches.) |
64d5610f ML |
967 | Throughout this manual, references to ‘Ada’ without a year suffix |
968 | apply to all the Ada versions of the language. | |
969 | ||
970 | Ada is designed to be highly portable. | |
971 | In general, a program will have the same effect even when compiled by | |
972 | different compilers on different platforms. | |
973 | However, since Ada is designed to be used in a | |
974 | wide variety of applications, it also contains a number of system | |
975 | dependent features to be used in interfacing to the external world. | |
976 | ||
977 | @geindex Implementation-dependent features | |
978 | ||
979 | @geindex Portability | |
980 | ||
981 | Note: Any program that makes use of implementation-dependent features | |
982 | may be non-portable. You should follow good programming practice and | |
983 | isolate and clearly document any sections of your program that make use | |
984 | of these features in a non-portable manner. | |
985 | ||
986 | @menu | |
987 | * What This Reference Manual Contains:: | |
988 | * Conventions:: | |
989 | * Related Information:: | |
990 | ||
991 | @end menu | |
992 | ||
993 | @node What This Reference Manual Contains,Conventions,,About This Guide | |
994 | @anchor{gnat_rm/about_this_guide what-this-reference-manual-contains}@anchor{6} | |
995 | @section What This Reference Manual Contains | |
996 | ||
997 | ||
998 | This reference manual contains the following chapters: | |
999 | ||
1000 | ||
1001 | @itemize * | |
1002 | ||
1003 | @item | |
1004 | @ref{7,,Implementation Defined Pragmas}, lists GNAT implementation-dependent | |
1005 | pragmas, which can be used to extend and enhance the functionality of the | |
1006 | compiler. | |
1007 | ||
1008 | @item | |
1009 | @ref{8,,Implementation Defined Attributes}, lists GNAT | |
1010 | implementation-dependent attributes, which can be used to extend and | |
1011 | enhance the functionality of the compiler. | |
1012 | ||
1013 | @item | |
1014 | @ref{9,,Standard and Implementation Defined Restrictions}, lists GNAT | |
1015 | implementation-dependent restrictions, which can be used to extend and | |
1016 | enhance the functionality of the compiler. | |
1017 | ||
1018 | @item | |
1019 | @ref{a,,Implementation Advice}, provides information on generally | |
1020 | desirable behavior which are not requirements that all compilers must | |
1021 | follow since it cannot be provided on all systems, or which may be | |
1022 | undesirable on some systems. | |
1023 | ||
1024 | @item | |
1025 | @ref{b,,Implementation Defined Characteristics}, provides a guide to | |
1026 | minimizing implementation dependent features. | |
1027 | ||
1028 | @item | |
1029 | @ref{c,,Intrinsic Subprograms}, describes the intrinsic subprograms | |
1030 | implemented by GNAT, and how they can be imported into user | |
1031 | application programs. | |
1032 | ||
1033 | @item | |
1034 | @ref{d,,Representation Clauses and Pragmas}, describes in detail the | |
1035 | way that GNAT represents data, and in particular the exact set | |
1036 | of representation clauses and pragmas that is accepted. | |
1037 | ||
1038 | @item | |
1039 | @ref{e,,Standard Library Routines}, provides a listing of packages and a | |
1040 | brief description of the functionality that is provided by Ada’s | |
1041 | extensive set of standard library routines as implemented by GNAT. | |
1042 | ||
1043 | @item | |
1044 | @ref{f,,The Implementation of Standard I/O}, details how the GNAT | |
1045 | implementation of the input-output facilities. | |
1046 | ||
1047 | @item | |
1048 | @ref{10,,The GNAT Library}, is a catalog of packages that complement | |
1049 | the Ada predefined library. | |
1050 | ||
1051 | @item | |
1052 | @ref{11,,Interfacing to Other Languages}, describes how programs | |
1053 | written in Ada using GNAT can be interfaced to other programming | |
1054 | languages. | |
1055 | ||
1056 | @item | |
1057 | @ref{12,,Specialized Needs Annexes}, describes the GNAT implementation of all | |
1058 | of the specialized needs annexes. | |
1059 | ||
1060 | @item | |
1061 | @ref{13,,Implementation of Specific Ada Features}, discusses issues related | |
1062 | to GNAT’s implementation of machine code insertions, tasking, and several | |
1063 | other features. | |
1064 | ||
1065 | @item | |
1066 | @ref{14,,Implementation of Ada 2012 Features}, describes the status of the | |
1067 | GNAT implementation of the Ada 2012 language standard. | |
1068 | ||
1069 | @item | |
1070 | @ref{15,,Security Hardening Features} documents GNAT extensions aimed | |
1071 | at security hardening. | |
1072 | ||
1073 | @item | |
1074 | @ref{16,,Obsolescent Features} documents implementation dependent features, | |
1075 | including pragmas and attributes, which are considered obsolescent, since | |
1076 | there are other preferred ways of achieving the same results. These | |
1077 | obsolescent forms are retained for backwards compatibility. | |
1078 | ||
1079 | @item | |
1080 | @ref{17,,Compatibility and Porting Guide} presents some guidelines for | |
1081 | developing portable Ada code, describes the compatibility issues that | |
1082 | may arise between GNAT and other Ada compilation systems (including those | |
1083 | for Ada 83), and shows how GNAT can expedite porting applications | |
1084 | developed in other Ada environments. | |
1085 | ||
1086 | @item | |
1087 | @ref{1,,GNU Free Documentation License} contains the license for this document. | |
1088 | @end itemize | |
1089 | ||
1090 | @geindex Ada 95 Language Reference Manual | |
1091 | ||
1092 | @geindex Ada 2005 Language Reference Manual | |
1093 | ||
1094 | This reference manual assumes a basic familiarity with the Ada 95 language, as | |
1095 | described in the | |
1096 | @cite{International Standard ANSI/ISO/IEC-8652:1995}. | |
1097 | It does not require knowledge of the new features introduced by Ada 2005 or | |
1098 | Ada 2012. | |
1099 | All three reference manuals are included in the GNAT documentation | |
1100 | package. | |
1101 | ||
1102 | @node Conventions,Related Information,What This Reference Manual Contains,About This Guide | |
1103 | @anchor{gnat_rm/about_this_guide conventions}@anchor{18} | |
1104 | @section Conventions | |
1105 | ||
1106 | ||
1107 | @geindex Conventions | |
1108 | @geindex typographical | |
1109 | ||
1110 | @geindex Typographical conventions | |
1111 | ||
1112 | Following are examples of the typographical and graphic conventions used | |
1113 | in this guide: | |
1114 | ||
1115 | ||
1116 | @itemize * | |
1117 | ||
1118 | @item | |
1119 | @code{Functions}, @code{utility program names}, @code{standard names}, | |
1120 | and @code{classes}. | |
1121 | ||
1122 | @item | |
1123 | @code{Option flags} | |
1124 | ||
1125 | @item | |
1126 | @code{File names} | |
1127 | ||
1128 | @item | |
1129 | @code{Variables} | |
1130 | ||
1131 | @item | |
1acce141 | 1132 | @emph{Emphasis} |
64d5610f ML |
1133 | |
1134 | @item | |
1135 | [optional information or parameters] | |
1136 | ||
1137 | @item | |
1138 | Examples are described by text | |
1139 | ||
1140 | @example | |
1141 | and then shown this way. | |
1142 | @end example | |
1143 | ||
1144 | @item | |
1145 | Commands that are entered by the user are shown as preceded by a prompt string | |
1146 | comprising the @code{$} character followed by a space. | |
1147 | @end itemize | |
1148 | ||
1149 | @node Related Information,,Conventions,About This Guide | |
1150 | @anchor{gnat_rm/about_this_guide related-information}@anchor{19} | |
1151 | @section Related Information | |
1152 | ||
1153 | ||
1154 | See the following documents for further information on GNAT: | |
1155 | ||
1156 | ||
1157 | @itemize * | |
1158 | ||
1159 | @item | |
1160 | @cite{GNAT User’s Guide for Native Platforms}, | |
1161 | which provides information on how to use the | |
1162 | GNAT development environment. | |
1163 | ||
1164 | @item | |
1165 | @cite{Ada 95 Reference Manual}, the Ada 95 programming language standard. | |
1166 | ||
1167 | @item | |
1168 | @cite{Ada 95 Annotated Reference Manual}, which is an annotated version | |
1169 | of the Ada 95 standard. The annotations describe | |
1170 | detailed aspects of the design decision, and in particular contain useful | |
1171 | sections on Ada 83 compatibility. | |
1172 | ||
1173 | @item | |
1174 | @cite{Ada 2005 Reference Manual}, the Ada 2005 programming language standard. | |
1175 | ||
1176 | @item | |
1177 | @cite{Ada 2005 Annotated Reference Manual}, which is an annotated version | |
1178 | of the Ada 2005 standard. The annotations describe | |
1179 | detailed aspects of the design decision. | |
1180 | ||
1181 | @item | |
1182 | @cite{Ada 2012 Reference Manual}, the Ada 2012 programming language standard. | |
1183 | ||
1184 | @item | |
1185 | @cite{DEC Ada@comma{} Technical Overview and Comparison on DIGITAL Platforms}, | |
1186 | which contains specific information on compatibility between GNAT and | |
1187 | DEC Ada 83 systems. | |
1188 | ||
1189 | @item | |
1190 | @cite{DEC Ada@comma{} Language Reference Manual}, part number AA-PYZAB-TK, which | |
1191 | describes in detail the pragmas and attributes provided by the DEC Ada 83 | |
1192 | compiler system. | |
1193 | @end itemize | |
1194 | ||
1195 | @node Implementation Defined Pragmas,Implementation Defined Aspects,About This Guide,Top | |
1196 | @anchor{gnat_rm/implementation_defined_pragmas doc}@anchor{1a}@anchor{gnat_rm/implementation_defined_pragmas id1}@anchor{1b}@anchor{gnat_rm/implementation_defined_pragmas implementation-defined-pragmas}@anchor{7} | |
1197 | @chapter Implementation Defined Pragmas | |
1198 | ||
1199 | ||
1200 | Ada defines a set of pragmas that can be used to supply additional | |
1201 | information to the compiler. These language defined pragmas are | |
1202 | implemented in GNAT and work as described in the Ada Reference Manual. | |
1203 | ||
1204 | In addition, Ada allows implementations to define additional pragmas | |
1205 | whose meaning is defined by the implementation. GNAT provides a number | |
1206 | of these implementation-defined pragmas, which can be used to extend | |
1207 | and enhance the functionality of the compiler. This section of the GNAT | |
1208 | Reference Manual describes these additional pragmas. | |
1209 | ||
1210 | Note that any program using these pragmas might not be portable to other | |
1211 | compilers (although GNAT implements this set of pragmas on all | |
1212 | platforms). Therefore if portability to other compilers is an important | |
1213 | consideration, the use of these pragmas should be minimized. | |
1214 | ||
1215 | @menu | |
1216 | * Pragma Abort_Defer:: | |
1217 | * Pragma Abstract_State:: | |
1218 | * Pragma Ada_83:: | |
1219 | * Pragma Ada_95:: | |
1220 | * Pragma Ada_05:: | |
1221 | * Pragma Ada_2005:: | |
1222 | * Pragma Ada_12:: | |
1223 | * Pragma Ada_2012:: | |
1224 | * Pragma Ada_2022:: | |
1225 | * Pragma Aggregate_Individually_Assign:: | |
1226 | * Pragma Allow_Integer_Address:: | |
1227 | * Pragma Annotate:: | |
1228 | * Pragma Assert:: | |
1229 | * Pragma Assert_And_Cut:: | |
1230 | * Pragma Assertion_Policy:: | |
1231 | * Pragma Assume:: | |
1232 | * Pragma Assume_No_Invalid_Values:: | |
1233 | * Pragma Async_Readers:: | |
1234 | * Pragma Async_Writers:: | |
1235 | * Pragma Attribute_Definition:: | |
1236 | * Pragma C_Pass_By_Copy:: | |
1237 | * Pragma Check:: | |
1238 | * Pragma Check_Float_Overflow:: | |
1239 | * Pragma Check_Name:: | |
1240 | * Pragma Check_Policy:: | |
1241 | * Pragma Comment:: | |
1242 | * Pragma Common_Object:: | |
1243 | * Pragma Compile_Time_Error:: | |
1244 | * Pragma Compile_Time_Warning:: | |
1245 | * Pragma Complete_Representation:: | |
1246 | * Pragma Complex_Representation:: | |
1247 | * Pragma Component_Alignment:: | |
1248 | * Pragma Constant_After_Elaboration:: | |
1249 | * Pragma Contract_Cases:: | |
1250 | * Pragma Convention_Identifier:: | |
1251 | * Pragma CPP_Class:: | |
1252 | * Pragma CPP_Constructor:: | |
1253 | * Pragma CPP_Virtual:: | |
1254 | * Pragma CPP_Vtable:: | |
1255 | * Pragma CPU:: | |
1256 | * Pragma Deadline_Floor:: | |
64d5610f ML |
1257 | * Pragma Debug:: |
1258 | * Pragma Debug_Policy:: | |
6f089469 | 1259 | * Pragma Default_Initial_Condition:: |
64d5610f ML |
1260 | * Pragma Default_Scalar_Storage_Order:: |
1261 | * Pragma Default_Storage_Pool:: | |
1262 | * Pragma Depends:: | |
1263 | * Pragma Detect_Blocking:: | |
1264 | * Pragma Disable_Atomic_Synchronization:: | |
1265 | * Pragma Dispatching_Domain:: | |
1266 | * Pragma Effective_Reads:: | |
1267 | * Pragma Effective_Writes:: | |
1268 | * Pragma Elaboration_Checks:: | |
1269 | * Pragma Eliminate:: | |
1270 | * Pragma Enable_Atomic_Synchronization:: | |
1271 | * Pragma Export_Function:: | |
1272 | * Pragma Export_Object:: | |
1273 | * Pragma Export_Procedure:: | |
1274 | * Pragma Export_Valued_Procedure:: | |
1275 | * Pragma Extend_System:: | |
1276 | * Pragma Extensions_Allowed:: | |
1277 | * Pragma Extensions_Visible:: | |
1278 | * Pragma External:: | |
1279 | * Pragma External_Name_Casing:: | |
1280 | * Pragma Fast_Math:: | |
1281 | * Pragma Favor_Top_Level:: | |
1282 | * Pragma Finalize_Storage_Only:: | |
1283 | * Pragma Float_Representation:: | |
1284 | * Pragma Ghost:: | |
1285 | * Pragma Global:: | |
1286 | * Pragma Ident:: | |
1287 | * Pragma Ignore_Pragma:: | |
1288 | * Pragma Implementation_Defined:: | |
1289 | * Pragma Implemented:: | |
1290 | * Pragma Implicit_Packing:: | |
1291 | * Pragma Import_Function:: | |
1292 | * Pragma Import_Object:: | |
1293 | * Pragma Import_Procedure:: | |
1294 | * Pragma Import_Valued_Procedure:: | |
1295 | * Pragma Independent:: | |
1296 | * Pragma Independent_Components:: | |
1297 | * Pragma Initial_Condition:: | |
1298 | * Pragma Initialize_Scalars:: | |
1299 | * Pragma Initializes:: | |
1300 | * Pragma Inline_Always:: | |
1301 | * Pragma Inline_Generic:: | |
1302 | * Pragma Interface:: | |
1303 | * Pragma Interface_Name:: | |
1304 | * Pragma Interrupt_Handler:: | |
1305 | * Pragma Interrupt_State:: | |
1306 | * Pragma Invariant:: | |
1307 | * Pragma Keep_Names:: | |
1308 | * Pragma License:: | |
1309 | * Pragma Link_With:: | |
1310 | * Pragma Linker_Alias:: | |
1311 | * Pragma Linker_Constructor:: | |
1312 | * Pragma Linker_Destructor:: | |
1313 | * Pragma Linker_Section:: | |
1314 | * Pragma Lock_Free:: | |
1315 | * Pragma Loop_Invariant:: | |
1316 | * Pragma Loop_Optimize:: | |
1317 | * Pragma Loop_Variant:: | |
1318 | * Pragma Machine_Attribute:: | |
1319 | * Pragma Main:: | |
1320 | * Pragma Main_Storage:: | |
1321 | * Pragma Max_Queue_Length:: | |
1322 | * Pragma No_Body:: | |
1323 | * Pragma No_Caching:: | |
1324 | * Pragma No_Component_Reordering:: | |
1325 | * Pragma No_Elaboration_Code_All:: | |
1326 | * Pragma No_Heap_Finalization:: | |
1327 | * Pragma No_Inline:: | |
1328 | * Pragma No_Return:: | |
1329 | * Pragma No_Strict_Aliasing:: | |
1330 | * Pragma No_Tagged_Streams:: | |
1331 | * Pragma Normalize_Scalars:: | |
1332 | * Pragma Obsolescent:: | |
1333 | * Pragma Optimize_Alignment:: | |
1334 | * Pragma Ordered:: | |
1335 | * Pragma Overflow_Mode:: | |
1336 | * Pragma Overriding_Renamings:: | |
64d5610f | 1337 | * Pragma Part_Of:: |
6f089469 | 1338 | * Pragma Partition_Elaboration_Policy:: |
64d5610f ML |
1339 | * Pragma Passive:: |
1340 | * Pragma Persistent_BSS:: | |
1341 | * Pragma Post:: | |
1342 | * Pragma Postcondition:: | |
1343 | * Pragma Post_Class:: | |
1344 | * Pragma Pre:: | |
1345 | * Pragma Precondition:: | |
1346 | * Pragma Predicate:: | |
1347 | * Pragma Predicate_Failure:: | |
1348 | * Pragma Preelaborable_Initialization:: | |
1349 | * Pragma Prefix_Exception_Messages:: | |
1350 | * Pragma Pre_Class:: | |
1351 | * Pragma Priority_Specific_Dispatching:: | |
1352 | * Pragma Profile:: | |
1353 | * Pragma Profile_Warnings:: | |
1354 | * Pragma Propagate_Exceptions:: | |
1355 | * Pragma Provide_Shift_Operators:: | |
1356 | * Pragma Psect_Object:: | |
1357 | * Pragma Pure_Function:: | |
1358 | * Pragma Rational:: | |
1359 | * Pragma Ravenscar:: | |
1360 | * Pragma Refined_Depends:: | |
1361 | * Pragma Refined_Global:: | |
1362 | * Pragma Refined_Post:: | |
1363 | * Pragma Refined_State:: | |
1364 | * Pragma Relative_Deadline:: | |
1365 | * Pragma Remote_Access_Type:: | |
1366 | * Pragma Rename_Pragma:: | |
1367 | * Pragma Restricted_Run_Time:: | |
1368 | * Pragma Restriction_Warnings:: | |
1369 | * Pragma Reviewable:: | |
1370 | * Pragma Secondary_Stack_Size:: | |
1371 | * Pragma Share_Generic:: | |
1372 | * Pragma Shared:: | |
1373 | * Pragma Short_Circuit_And_Or:: | |
1374 | * Pragma Short_Descriptors:: | |
04d6c745 | 1375 | * Pragma Side_Effects:: |
64d5610f ML |
1376 | * Pragma Simple_Storage_Pool_Type:: |
1377 | * Pragma Source_File_Name:: | |
1378 | * Pragma Source_File_Name_Project:: | |
1379 | * Pragma Source_Reference:: | |
1380 | * Pragma SPARK_Mode:: | |
1381 | * Pragma Static_Elaboration_Desired:: | |
1382 | * Pragma Stream_Convert:: | |
1383 | * Pragma Style_Checks:: | |
1384 | * Pragma Subtitle:: | |
1385 | * Pragma Suppress:: | |
1386 | * Pragma Suppress_All:: | |
1387 | * Pragma Suppress_Debug_Info:: | |
1388 | * Pragma Suppress_Exception_Locations:: | |
1389 | * Pragma Suppress_Initialization:: | |
1390 | * Pragma Task_Name:: | |
1391 | * Pragma Task_Storage:: | |
1392 | * Pragma Test_Case:: | |
1393 | * Pragma Thread_Local_Storage:: | |
1394 | * Pragma Time_Slice:: | |
1395 | * Pragma Title:: | |
1396 | * Pragma Type_Invariant:: | |
1397 | * Pragma Type_Invariant_Class:: | |
1398 | * Pragma Unchecked_Union:: | |
1399 | * Pragma Unevaluated_Use_Of_Old:: | |
9daee425 | 1400 | * Pragma User_Aspect_Definition:: |
64d5610f ML |
1401 | * Pragma Unimplemented_Unit:: |
1402 | * Pragma Universal_Aliasing:: | |
1403 | * Pragma Unmodified:: | |
1404 | * Pragma Unreferenced:: | |
1405 | * Pragma Unreferenced_Objects:: | |
1406 | * Pragma Unreserve_All_Interrupts:: | |
1407 | * Pragma Unsuppress:: | |
64d5610f | 1408 | * Pragma Unused:: |
6f089469 | 1409 | * Pragma Use_VADS_Size:: |
64d5610f ML |
1410 | * Pragma Validity_Checks:: |
1411 | * Pragma Volatile:: | |
1412 | * Pragma Volatile_Full_Access:: | |
1413 | * Pragma Volatile_Function:: | |
1414 | * Pragma Warning_As_Error:: | |
1415 | * Pragma Warnings:: | |
1416 | * Pragma Weak_External:: | |
1417 | * Pragma Wide_Character_Encoding:: | |
1418 | ||
1419 | @end menu | |
1420 | ||
1421 | @node Pragma Abort_Defer,Pragma Abstract_State,,Implementation Defined Pragmas | |
1422 | @anchor{gnat_rm/implementation_defined_pragmas pragma-abort-defer}@anchor{1c} | |
1423 | @section Pragma Abort_Defer | |
1424 | ||
1425 | ||
1426 | @geindex Deferring aborts | |
1427 | ||
1428 | Syntax: | |
1429 | ||
1430 | @example | |
1431 | pragma Abort_Defer; | |
1432 | @end example | |
1433 | ||
1434 | This pragma must appear at the start of the statement sequence of a | |
1435 | handled sequence of statements (right after the @code{begin}). It has | |
1436 | the effect of deferring aborts for the sequence of statements (but not | |
1437 | for the declarations or handlers, if any, associated with this statement | |
1438 | sequence). This can also be useful for adding a polling point in Ada code, | |
1439 | where asynchronous abort of tasks is checked when leaving the statement | |
1440 | sequence, and is lighter than, for example, using @code{delay 0.0;}, since with | |
1441 | zero-cost exception handling, propagating exceptions (implicitly used to | |
1442 | implement task abort) cannot be done reliably in an asynchronous way. | |
1443 | ||
1444 | An example of usage would be: | |
1445 | ||
1446 | @example | |
1447 | -- Add a polling point to check for task aborts | |
1448 | ||
1449 | begin | |
1450 | pragma Abort_Defer; | |
1451 | end; | |
1452 | @end example | |
1453 | ||
1454 | @node Pragma Abstract_State,Pragma Ada_83,Pragma Abort_Defer,Implementation Defined Pragmas | |
1455 | @anchor{gnat_rm/implementation_defined_pragmas id2}@anchor{1d}@anchor{gnat_rm/implementation_defined_pragmas pragma-abstract-state}@anchor{1e} | |
1456 | @section Pragma Abstract_State | |
1457 | ||
1458 | ||
1459 | Syntax: | |
1460 | ||
1461 | @example | |
1462 | pragma Abstract_State (ABSTRACT_STATE_LIST); | |
1463 | ||
1464 | ABSTRACT_STATE_LIST ::= | |
1465 | null | |
1466 | | STATE_NAME_WITH_OPTIONS | |
1467 | | (STATE_NAME_WITH_OPTIONS @{, STATE_NAME_WITH_OPTIONS@} ) | |
1468 | ||
1469 | STATE_NAME_WITH_OPTIONS ::= | |
1470 | STATE_NAME | |
1471 | | (STATE_NAME with OPTION_LIST) | |
1472 | ||
1473 | OPTION_LIST ::= OPTION @{, OPTION@} | |
1474 | ||
1475 | OPTION ::= | |
1476 | SIMPLE_OPTION | |
1477 | | NAME_VALUE_OPTION | |
1478 | ||
1479 | SIMPLE_OPTION ::= Ghost | Synchronous | |
1480 | ||
1481 | NAME_VALUE_OPTION ::= | |
1482 | Part_Of => ABSTRACT_STATE | |
1483 | | External [=> EXTERNAL_PROPERTY_LIST] | |
1484 | ||
1485 | EXTERNAL_PROPERTY_LIST ::= | |
1486 | EXTERNAL_PROPERTY | |
1487 | | (EXTERNAL_PROPERTY @{, EXTERNAL_PROPERTY@} ) | |
1488 | ||
1489 | EXTERNAL_PROPERTY ::= | |
1490 | Async_Readers [=> static_boolean_EXPRESSION] | |
1491 | | Async_Writers [=> static_boolean_EXPRESSION] | |
1492 | | Effective_Reads [=> static_boolean_EXPRESSION] | |
1493 | | Effective_Writes [=> static_boolean_EXPRESSION] | |
1494 | others => static_boolean_EXPRESSION | |
1495 | ||
1496 | STATE_NAME ::= defining_identifier | |
1497 | ||
1498 | ABSTRACT_STATE ::= name | |
1499 | @end example | |
1500 | ||
1501 | For the semantics of this pragma, see the entry for aspect @code{Abstract_State} in | |
1502 | the SPARK 2014 Reference Manual, section 7.1.4. | |
1503 | ||
1504 | @node Pragma Ada_83,Pragma Ada_95,Pragma Abstract_State,Implementation Defined Pragmas | |
1505 | @anchor{gnat_rm/implementation_defined_pragmas pragma-ada-83}@anchor{1f} | |
1506 | @section Pragma Ada_83 | |
1507 | ||
1508 | ||
1509 | Syntax: | |
1510 | ||
1511 | @example | |
1512 | pragma Ada_83; | |
1513 | @end example | |
1514 | ||
1515 | A configuration pragma that establishes Ada 83 mode for the unit to | |
1516 | which it applies, regardless of the mode set by the command line | |
1517 | switches. In Ada 83 mode, GNAT attempts to be as compatible with | |
1518 | the syntax and semantics of Ada 83, as defined in the original Ada | |
1519 | 83 Reference Manual as possible. In particular, the keywords added by Ada 95 | |
1520 | and Ada 2005 are not recognized, optional package bodies are allowed, | |
1521 | and generics may name types with unknown discriminants without using | |
1522 | the @code{(<>)} notation. In addition, some but not all of the additional | |
1523 | restrictions of Ada 83 are enforced. | |
1524 | ||
1525 | Ada 83 mode is intended for two purposes. Firstly, it allows existing | |
1526 | Ada 83 code to be compiled and adapted to GNAT with less effort. | |
1527 | Secondly, it aids in keeping code backwards compatible with Ada 83. | |
1528 | However, there is no guarantee that code that is processed correctly | |
1529 | by GNAT in Ada 83 mode will in fact compile and execute with an Ada | |
1530 | 83 compiler, since GNAT does not enforce all the additional checks | |
1531 | required by Ada 83. | |
1532 | ||
1533 | @node Pragma Ada_95,Pragma Ada_05,Pragma Ada_83,Implementation Defined Pragmas | |
1534 | @anchor{gnat_rm/implementation_defined_pragmas pragma-ada-95}@anchor{20} | |
1535 | @section Pragma Ada_95 | |
1536 | ||
1537 | ||
1538 | Syntax: | |
1539 | ||
1540 | @example | |
1541 | pragma Ada_95; | |
1542 | @end example | |
1543 | ||
1544 | A configuration pragma that establishes Ada 95 mode for the unit to which | |
1545 | it applies, regardless of the mode set by the command line switches. | |
1546 | This mode is set automatically for the @code{Ada} and @code{System} | |
1547 | packages and their children, so you need not specify it in these | |
1548 | contexts. This pragma is useful when writing a reusable component that | |
1549 | itself uses Ada 95 features, but which is intended to be usable from | |
1550 | either Ada 83 or Ada 95 programs. | |
1551 | ||
1552 | @node Pragma Ada_05,Pragma Ada_2005,Pragma Ada_95,Implementation Defined Pragmas | |
1553 | @anchor{gnat_rm/implementation_defined_pragmas pragma-ada-05}@anchor{21} | |
1554 | @section Pragma Ada_05 | |
1555 | ||
1556 | ||
1557 | Syntax: | |
1558 | ||
1559 | @example | |
1560 | pragma Ada_05; | |
1561 | pragma Ada_05 (local_NAME); | |
1562 | @end example | |
1563 | ||
1564 | A configuration pragma that establishes Ada 2005 mode for the unit to which | |
1565 | it applies, regardless of the mode set by the command line switches. | |
1566 | This pragma is useful when writing a reusable component that | |
1567 | itself uses Ada 2005 features, but which is intended to be usable from | |
1568 | either Ada 83 or Ada 95 programs. | |
1569 | ||
1570 | The one argument form (which is not a configuration pragma) | |
1571 | is used for managing the transition from | |
1572 | Ada 95 to Ada 2005 in the run-time library. If an entity is marked | |
1573 | as Ada_2005 only, then referencing the entity in Ada_83 or Ada_95 | |
1574 | mode will generate a warning. In addition, in Ada_83 or Ada_95 | |
1575 | mode, a preference rule is established which does not choose | |
1576 | such an entity unless it is unambiguously specified. This avoids | |
1577 | extra subprograms marked this way from generating ambiguities in | |
1578 | otherwise legal pre-Ada_2005 programs. The one argument form is | |
1579 | intended for exclusive use in the GNAT run-time library. | |
1580 | ||
1581 | @node Pragma Ada_2005,Pragma Ada_12,Pragma Ada_05,Implementation Defined Pragmas | |
1582 | @anchor{gnat_rm/implementation_defined_pragmas pragma-ada-2005}@anchor{22} | |
1583 | @section Pragma Ada_2005 | |
1584 | ||
1585 | ||
1586 | Syntax: | |
1587 | ||
1588 | @example | |
1589 | pragma Ada_2005; | |
1590 | @end example | |
1591 | ||
1592 | This configuration pragma is a synonym for pragma Ada_05 and has the | |
1593 | same syntax and effect. | |
1594 | ||
1595 | @node Pragma Ada_12,Pragma Ada_2012,Pragma Ada_2005,Implementation Defined Pragmas | |
1596 | @anchor{gnat_rm/implementation_defined_pragmas pragma-ada-12}@anchor{23} | |
1597 | @section Pragma Ada_12 | |
1598 | ||
1599 | ||
1600 | Syntax: | |
1601 | ||
1602 | @example | |
1603 | pragma Ada_12; | |
1604 | pragma Ada_12 (local_NAME); | |
1605 | @end example | |
1606 | ||
1607 | A configuration pragma that establishes Ada 2012 mode for the unit to which | |
1608 | it applies, regardless of the mode set by the command line switches. | |
1609 | This mode is set automatically for the @code{Ada} and @code{System} | |
1610 | packages and their children, so you need not specify it in these | |
1611 | contexts. This pragma is useful when writing a reusable component that | |
1612 | itself uses Ada 2012 features, but which is intended to be usable from | |
1613 | Ada 83, Ada 95, or Ada 2005 programs. | |
1614 | ||
1615 | The one argument form, which is not a configuration pragma, | |
1616 | is used for managing the transition from Ada | |
1617 | 2005 to Ada 2012 in the run-time library. If an entity is marked | |
1618 | as Ada_2012 only, then referencing the entity in any pre-Ada_2012 | |
1619 | mode will generate a warning. In addition, in any pre-Ada_2012 | |
1620 | mode, a preference rule is established which does not choose | |
1621 | such an entity unless it is unambiguously specified. This avoids | |
1622 | extra subprograms marked this way from generating ambiguities in | |
1623 | otherwise legal pre-Ada_2012 programs. The one argument form is | |
1624 | intended for exclusive use in the GNAT run-time library. | |
1625 | ||
1626 | @node Pragma Ada_2012,Pragma Ada_2022,Pragma Ada_12,Implementation Defined Pragmas | |
1627 | @anchor{gnat_rm/implementation_defined_pragmas pragma-ada-2012}@anchor{24} | |
1628 | @section Pragma Ada_2012 | |
1629 | ||
1630 | ||
1631 | Syntax: | |
1632 | ||
1633 | @example | |
1634 | pragma Ada_2012; | |
1635 | @end example | |
1636 | ||
1637 | This configuration pragma is a synonym for pragma Ada_12 and has the | |
1638 | same syntax and effect. | |
1639 | ||
1640 | @node Pragma Ada_2022,Pragma Aggregate_Individually_Assign,Pragma Ada_2012,Implementation Defined Pragmas | |
1641 | @anchor{gnat_rm/implementation_defined_pragmas pragma-ada-2022}@anchor{25} | |
1642 | @section Pragma Ada_2022 | |
1643 | ||
1644 | ||
1645 | Syntax: | |
1646 | ||
1647 | @example | |
1648 | pragma Ada_2022; | |
1649 | pragma Ada_2022 (local_NAME); | |
1650 | @end example | |
1651 | ||
1652 | A configuration pragma that establishes Ada 2022 mode for the unit to which | |
1653 | it applies, regardless of the mode set by the command line switches. | |
1654 | This mode is set automatically for the @code{Ada} and @code{System} | |
1655 | packages and their children, so you need not specify it in these | |
1656 | contexts. This pragma is useful when writing a reusable component that | |
1657 | itself uses Ada 2022 features, but which is intended to be usable from | |
1658 | Ada 83, Ada 95, Ada 2005 or Ada 2012 programs. | |
1659 | ||
1660 | The one argument form, which is not a configuration pragma, | |
1661 | is used for managing the transition from Ada | |
1662 | 2012 to Ada 2022 in the run-time library. If an entity is marked | |
1663 | as Ada_2022 only, then referencing the entity in any pre-Ada_2022 | |
1664 | mode will generate a warning. In addition, in any pre-Ada_2012 | |
1665 | mode, a preference rule is established which does not choose | |
1666 | such an entity unless it is unambiguously specified. This avoids | |
1667 | extra subprograms marked this way from generating ambiguities in | |
1668 | otherwise legal pre-Ada_2022 programs. The one argument form is | |
1669 | intended for exclusive use in the GNAT run-time library. | |
1670 | ||
1671 | @node Pragma Aggregate_Individually_Assign,Pragma Allow_Integer_Address,Pragma Ada_2022,Implementation Defined Pragmas | |
1672 | @anchor{gnat_rm/implementation_defined_pragmas pragma-aggregate-individually-assign}@anchor{26} | |
1673 | @section Pragma Aggregate_Individually_Assign | |
1674 | ||
1675 | ||
1676 | Syntax: | |
1677 | ||
1678 | @example | |
1679 | pragma Aggregate_Individually_Assign; | |
1680 | @end example | |
1681 | ||
1682 | Where possible, GNAT will store the binary representation of a record aggregate | |
1683 | in memory for space and performance reasons. This configuration pragma changes | |
1684 | this behavior so that record aggregates are instead always converted into | |
1685 | individual assignment statements. | |
1686 | ||
1687 | @node Pragma Allow_Integer_Address,Pragma Annotate,Pragma Aggregate_Individually_Assign,Implementation Defined Pragmas | |
1688 | @anchor{gnat_rm/implementation_defined_pragmas pragma-allow-integer-address}@anchor{27} | |
1689 | @section Pragma Allow_Integer_Address | |
1690 | ||
1691 | ||
1692 | Syntax: | |
1693 | ||
1694 | @example | |
1695 | pragma Allow_Integer_Address; | |
1696 | @end example | |
1697 | ||
1698 | In almost all versions of GNAT, @code{System.Address} is a private | |
1699 | type in accordance with the implementation advice in the RM. This | |
1700 | means that integer values, | |
1701 | in particular integer literals, are not allowed as address values. | |
1702 | If the configuration pragma | |
1703 | @code{Allow_Integer_Address} is given, then integer expressions may | |
1704 | be used anywhere a value of type @code{System.Address} is required. | |
1705 | The effect is to introduce an implicit unchecked conversion from the | |
1706 | integer value to type @code{System.Address}. The reverse case of using | |
1707 | an address where an integer type is required is handled analogously. | |
1708 | The following example compiles without errors: | |
1709 | ||
1710 | @example | |
1711 | pragma Allow_Integer_Address; | |
1712 | with System; use System; | |
1713 | package AddrAsInt is | |
1714 | X : Integer; | |
1715 | Y : Integer; | |
1716 | for X'Address use 16#1240#; | |
1717 | for Y use at 16#3230#; | |
1718 | m : Address := 16#4000#; | |
1719 | n : constant Address := 4000; | |
1720 | p : constant Address := Address (X + Y); | |
1721 | v : Integer := y'Address; | |
1722 | w : constant Integer := Integer (Y'Address); | |
1723 | type R is new integer; | |
1724 | RR : R := 1000; | |
1725 | Z : Integer; | |
1726 | for Z'Address use RR; | |
1727 | end AddrAsInt; | |
1728 | @end example | |
1729 | ||
1730 | Note that pragma @code{Allow_Integer_Address} is ignored if @code{System.Address} | |
1731 | is not a private type. In implementations of @code{GNAT} where | |
1732 | System.Address is a visible integer type, | |
1733 | this pragma serves no purpose but is ignored | |
1734 | rather than rejected to allow common sets of sources to be used | |
1735 | in the two situations. | |
1736 | ||
1737 | @node Pragma Annotate,Pragma Assert,Pragma Allow_Integer_Address,Implementation Defined Pragmas | |
1738 | @anchor{gnat_rm/implementation_defined_pragmas id3}@anchor{28}@anchor{gnat_rm/implementation_defined_pragmas pragma-annotate}@anchor{29} | |
1739 | @section Pragma Annotate | |
1740 | ||
1741 | ||
1742 | Syntax: | |
1743 | ||
1744 | @example | |
1745 | pragma Annotate (IDENTIFIER [, IDENTIFIER @{, ARG@}] [, entity => local_NAME]); | |
1746 | ||
1747 | ARG ::= NAME | EXPRESSION | |
1748 | @end example | |
1749 | ||
1750 | This pragma is used to annotate programs. IDENTIFIER identifies | |
1751 | the type of annotation. GNAT verifies that it is an identifier, but does | |
1752 | not otherwise analyze it. The second optional identifier is also left | |
1753 | unanalyzed, and by convention is used to control the action of the tool to | |
1754 | which the annotation is addressed. The remaining ARG arguments | |
1755 | can be either string literals or more generally expressions. | |
1756 | String literals (and concatenations of string literals) are assumed to be | |
1757 | either of type | |
1758 | @code{Standard.String} or else @code{Wide_String} or @code{Wide_Wide_String} | |
1759 | depending on the character literals they contain. | |
1760 | All other kinds of arguments are analyzed as expressions, and must be | |
1761 | unambiguous. The last argument if present must have the identifier | |
1762 | @code{Entity} and GNAT verifies that a local name is given. | |
1763 | ||
1764 | The analyzed pragma is retained in the tree, but not otherwise processed | |
1765 | by any part of the GNAT compiler, except to generate corresponding note | |
1766 | lines in the generated ALI file. For the format of these note lines, see | |
1767 | the compiler source file lib-writ.ads. This pragma is intended for use by | |
1768 | external tools, including ASIS. The use of pragma Annotate does not | |
1769 | affect the compilation process in any way. This pragma may be used as | |
1770 | a configuration pragma. | |
1771 | ||
1772 | @node Pragma Assert,Pragma Assert_And_Cut,Pragma Annotate,Implementation Defined Pragmas | |
1773 | @anchor{gnat_rm/implementation_defined_pragmas pragma-assert}@anchor{2a} | |
1774 | @section Pragma Assert | |
1775 | ||
1776 | ||
1777 | Syntax: | |
1778 | ||
1779 | @example | |
1780 | pragma Assert ( | |
1781 | boolean_EXPRESSION | |
1782 | [, string_EXPRESSION]); | |
1783 | @end example | |
1784 | ||
1785 | The effect of this pragma depends on whether the corresponding command | |
1786 | line switch is set to activate assertions. The pragma expands into code | |
1787 | equivalent to the following: | |
1788 | ||
1789 | @example | |
1790 | if assertions-enabled then | |
1791 | if not boolean_EXPRESSION then | |
1792 | System.Assertions.Raise_Assert_Failure | |
1793 | (string_EXPRESSION); | |
1794 | end if; | |
1795 | end if; | |
1796 | @end example | |
1797 | ||
1798 | The string argument, if given, is the message that will be associated | |
1799 | with the exception occurrence if the exception is raised. If no second | |
1800 | argument is given, the default message is @code{file}:@code{nnn}, | |
1801 | where @code{file} is the name of the source file containing the assert, | |
1802 | and @code{nnn} is the line number of the assert. | |
1803 | ||
1804 | Note that, as with the @code{if} statement to which it is equivalent, the | |
1805 | type of the expression is either @code{Standard.Boolean}, or any type derived | |
1806 | from this standard type. | |
1807 | ||
1808 | Assert checks can be either checked or ignored. By default they are ignored. | |
1acce141 | 1809 | They will be checked if either the command line switch @emph{-gnata} is |
64d5610f ML |
1810 | used, or if an @code{Assertion_Policy} or @code{Check_Policy} pragma is used |
1811 | to enable @code{Assert_Checks}. | |
1812 | ||
1813 | If assertions are ignored, then there | |
1814 | is no run-time effect (and in particular, any side effects from the | |
1815 | expression will not occur at run time). (The expression is still | |
1816 | analyzed at compile time, and may cause types to be frozen if they are | |
1817 | mentioned here for the first time). | |
1818 | ||
1819 | If assertions are checked, then the given expression is tested, and if | |
1820 | it is @code{False} then @code{System.Assertions.Raise_Assert_Failure} is called | |
1821 | which results in the raising of @code{Assert_Failure} with the given message. | |
1822 | ||
1823 | You should generally avoid side effects in the expression arguments of | |
1824 | this pragma, because these side effects will turn on and off with the | |
1825 | setting of the assertions mode, resulting in assertions that have an | |
1826 | effect on the program. However, the expressions are analyzed for | |
1827 | semantic correctness whether or not assertions are enabled, so turning | |
1828 | assertions on and off cannot affect the legality of a program. | |
1829 | ||
1830 | Note that the implementation defined policy @code{DISABLE}, given in a | |
1831 | pragma @code{Assertion_Policy}, can be used to suppress this semantic analysis. | |
1832 | ||
1833 | Note: this is a standard language-defined pragma in versions | |
1834 | of Ada from 2005 on. In GNAT, it is implemented in all versions | |
1835 | of Ada, and the DISABLE policy is an implementation-defined | |
1836 | addition. | |
1837 | ||
1838 | @node Pragma Assert_And_Cut,Pragma Assertion_Policy,Pragma Assert,Implementation Defined Pragmas | |
1839 | @anchor{gnat_rm/implementation_defined_pragmas pragma-assert-and-cut}@anchor{2b} | |
1840 | @section Pragma Assert_And_Cut | |
1841 | ||
1842 | ||
1843 | Syntax: | |
1844 | ||
1845 | @example | |
1846 | pragma Assert_And_Cut ( | |
1847 | boolean_EXPRESSION | |
1848 | [, string_EXPRESSION]); | |
1849 | @end example | |
1850 | ||
1851 | The effect of this pragma is identical to that of pragma @code{Assert}, | |
1852 | except that in an @code{Assertion_Policy} pragma, the identifier | |
1853 | @code{Assert_And_Cut} is used to control whether it is ignored or checked | |
1854 | (or disabled). | |
1855 | ||
1856 | The intention is that this be used within a subprogram when the | |
1857 | given test expresion sums up all the work done so far in the | |
1858 | subprogram, so that the rest of the subprogram can be verified | |
1859 | (informally or formally) using only the entry preconditions, | |
1860 | and the expression in this pragma. This allows dividing up | |
1861 | a subprogram into sections for the purposes of testing or | |
1862 | formal verification. The pragma also serves as useful | |
1863 | documentation. | |
1864 | ||
1865 | @node Pragma Assertion_Policy,Pragma Assume,Pragma Assert_And_Cut,Implementation Defined Pragmas | |
1866 | @anchor{gnat_rm/implementation_defined_pragmas pragma-assertion-policy}@anchor{2c} | |
1867 | @section Pragma Assertion_Policy | |
1868 | ||
1869 | ||
1870 | Syntax: | |
1871 | ||
1872 | @example | |
1873 | pragma Assertion_Policy (CHECK | DISABLE | IGNORE | SUPPRESSIBLE); | |
1874 | ||
1875 | pragma Assertion_Policy ( | |
1876 | ASSERTION_KIND => POLICY_IDENTIFIER | |
1877 | @{, ASSERTION_KIND => POLICY_IDENTIFIER@}); | |
1878 | ||
1879 | ASSERTION_KIND ::= RM_ASSERTION_KIND | ID_ASSERTION_KIND | |
1880 | ||
1881 | RM_ASSERTION_KIND ::= Assert | | |
1882 | Static_Predicate | | |
1883 | Dynamic_Predicate | | |
1884 | Pre | | |
1885 | Pre'Class | | |
1886 | Post | | |
1887 | Post'Class | | |
1888 | Type_Invariant | | |
1889 | Type_Invariant'Class | | |
1890 | Default_Initial_Condition | |
1891 | ||
1892 | ID_ASSERTION_KIND ::= Assertions | | |
1893 | Assert_And_Cut | | |
1894 | Assume | | |
1895 | Contract_Cases | | |
1896 | Debug | | |
1897 | Ghost | | |
1898 | Initial_Condition | | |
1899 | Invariant | | |
1900 | Invariant'Class | | |
1901 | Loop_Invariant | | |
1902 | Loop_Variant | | |
1903 | Postcondition | | |
1904 | Precondition | | |
1905 | Predicate | | |
1906 | Refined_Post | | |
1907 | Statement_Assertions | | |
1908 | Subprogram_Variant | |
1909 | ||
1910 | POLICY_IDENTIFIER ::= Check | Disable | Ignore | Suppressible | |
1911 | @end example | |
1912 | ||
1913 | This is a standard Ada 2012 pragma that is available as an | |
1914 | implementation-defined pragma in earlier versions of Ada. | |
1915 | The assertion kinds @code{RM_ASSERTION_KIND} are those defined in | |
1916 | the Ada standard. The assertion kinds @code{ID_ASSERTION_KIND} | |
1917 | are implementation defined additions recognized by the GNAT compiler. | |
1918 | ||
1919 | The pragma applies in both cases to pragmas and aspects with matching | |
1920 | names, e.g. @code{Pre} applies to the Pre aspect, and @code{Precondition} | |
1921 | applies to both the @code{Precondition} pragma | |
1922 | and the aspect @code{Precondition}. Note that the identifiers for | |
1923 | pragmas Pre_Class and Post_Class are Pre’Class and Post’Class (not | |
1924 | Pre_Class and Post_Class), since these pragmas are intended to be | |
1925 | identical to the corresponding aspects. | |
1926 | ||
1927 | If the policy is @code{CHECK}, then assertions are enabled, i.e. | |
1928 | the corresponding pragma or aspect is activated. | |
1929 | If the policy is @code{IGNORE}, then assertions are ignored, i.e. | |
1930 | the corresponding pragma or aspect is deactivated. | |
1acce141 | 1931 | This pragma overrides the effect of the @emph{-gnata} switch on the |
64d5610f ML |
1932 | command line. |
1933 | If the policy is @code{SUPPRESSIBLE}, then assertions are enabled by default, | |
1acce141 | 1934 | however, if the @emph{-gnatp} switch is specified all assertions are ignored. |
64d5610f ML |
1935 | |
1936 | The implementation defined policy @code{DISABLE} is like | |
1937 | @code{IGNORE} except that it completely disables semantic | |
1938 | checking of the corresponding pragma or aspect. This is | |
1939 | useful when the pragma or aspect argument references subprograms | |
1940 | in a with’ed package which is replaced by a dummy package | |
1941 | for the final build. | |
1942 | ||
1943 | The implementation defined assertion kind @code{Assertions} applies to all | |
1944 | assertion kinds. The form with no assertion kind given implies this | |
1945 | choice, so it applies to all assertion kinds (RM defined, and | |
1946 | implementation defined). | |
1947 | ||
1948 | The implementation defined assertion kind @code{Statement_Assertions} | |
1949 | applies to @code{Assert}, @code{Assert_And_Cut}, | |
1950 | @code{Assume}, @code{Loop_Invariant}, and @code{Loop_Variant}. | |
1951 | ||
1952 | @node Pragma Assume,Pragma Assume_No_Invalid_Values,Pragma Assertion_Policy,Implementation Defined Pragmas | |
1953 | @anchor{gnat_rm/implementation_defined_pragmas pragma-assume}@anchor{2d} | |
1954 | @section Pragma Assume | |
1955 | ||
1956 | ||
1957 | Syntax: | |
1958 | ||
1959 | @example | |
1960 | pragma Assume ( | |
1961 | boolean_EXPRESSION | |
1962 | [, string_EXPRESSION]); | |
1963 | @end example | |
1964 | ||
1965 | The effect of this pragma is identical to that of pragma @code{Assert}, | |
1966 | except that in an @code{Assertion_Policy} pragma, the identifier | |
1967 | @code{Assume} is used to control whether it is ignored or checked | |
1968 | (or disabled). | |
1969 | ||
1970 | The intention is that this be used for assumptions about the | |
1971 | external environment. So you cannot expect to verify formally | |
1972 | or informally that the condition is met, this must be | |
1973 | established by examining things outside the program itself. | |
1974 | For example, we may have code that depends on the size of | |
1975 | @code{Long_Long_Integer} being at least 64. So we could write: | |
1976 | ||
1977 | @example | |
1978 | pragma Assume (Long_Long_Integer'Size >= 64); | |
1979 | @end example | |
1980 | ||
1981 | This assumption cannot be proved from the program itself, | |
1982 | but it acts as a useful run-time check that the assumption | |
1983 | is met, and documents the need to ensure that it is met by | |
1984 | reference to information outside the program. | |
1985 | ||
1986 | @node Pragma Assume_No_Invalid_Values,Pragma Async_Readers,Pragma Assume,Implementation Defined Pragmas | |
1987 | @anchor{gnat_rm/implementation_defined_pragmas pragma-assume-no-invalid-values}@anchor{2e} | |
1988 | @section Pragma Assume_No_Invalid_Values | |
1989 | ||
1990 | ||
1991 | @geindex Invalid representations | |
1992 | ||
1993 | @geindex Invalid values | |
1994 | ||
1995 | Syntax: | |
1996 | ||
1997 | @example | |
1998 | pragma Assume_No_Invalid_Values (On | Off); | |
1999 | @end example | |
2000 | ||
2001 | This is a configuration pragma that controls the assumptions made by the | |
2002 | compiler about the occurrence of invalid representations (invalid values) | |
2003 | in the code. | |
2004 | ||
2005 | The default behavior (corresponding to an Off argument for this pragma), is | |
2006 | to assume that values may in general be invalid unless the compiler can | |
2007 | prove they are valid. Consider the following example: | |
2008 | ||
2009 | @example | |
2010 | V1 : Integer range 1 .. 10; | |
2011 | V2 : Integer range 11 .. 20; | |
2012 | ... | |
2013 | for J in V2 .. V1 loop | |
2014 | ... | |
2015 | end loop; | |
2016 | @end example | |
2017 | ||
2018 | if V1 and V2 have valid values, then the loop is known at compile | |
2019 | time not to execute since the lower bound must be greater than the | |
2020 | upper bound. However in default mode, no such assumption is made, | |
2021 | and the loop may execute. If @code{Assume_No_Invalid_Values (On)} | |
2022 | is given, the compiler will assume that any occurrence of a variable | |
2023 | other than in an explicit @code{'Valid} test always has a valid | |
2024 | value, and the loop above will be optimized away. | |
2025 | ||
2026 | The use of @code{Assume_No_Invalid_Values (On)} is appropriate if | |
2027 | you know your code is free of uninitialized variables and other | |
2028 | possible sources of invalid representations, and may result in | |
2029 | more efficient code. A program that accesses an invalid representation | |
2030 | with this pragma in effect is erroneous, so no guarantees can be made | |
2031 | about its behavior. | |
2032 | ||
2033 | It is peculiar though permissible to use this pragma in conjunction | |
2034 | with validity checking (-gnatVa). In such cases, accessing invalid | |
2035 | values will generally give an exception, though formally the program | |
2036 | is erroneous so there are no guarantees that this will always be the | |
2037 | case, and it is recommended that these two options not be used together. | |
2038 | ||
2039 | @node Pragma Async_Readers,Pragma Async_Writers,Pragma Assume_No_Invalid_Values,Implementation Defined Pragmas | |
2040 | @anchor{gnat_rm/implementation_defined_pragmas id4}@anchor{2f}@anchor{gnat_rm/implementation_defined_pragmas pragma-async-readers}@anchor{30} | |
2041 | @section Pragma Async_Readers | |
2042 | ||
2043 | ||
2044 | Syntax: | |
2045 | ||
2046 | @example | |
2047 | pragma Async_Readers [ (static_boolean_EXPRESSION) ]; | |
2048 | @end example | |
2049 | ||
2050 | For the semantics of this pragma, see the entry for aspect @code{Async_Readers} in | |
2051 | the SPARK 2014 Reference Manual, section 7.1.2. | |
2052 | ||
2053 | @node Pragma Async_Writers,Pragma Attribute_Definition,Pragma Async_Readers,Implementation Defined Pragmas | |
2054 | @anchor{gnat_rm/implementation_defined_pragmas id5}@anchor{31}@anchor{gnat_rm/implementation_defined_pragmas pragma-async-writers}@anchor{32} | |
2055 | @section Pragma Async_Writers | |
2056 | ||
2057 | ||
2058 | Syntax: | |
2059 | ||
2060 | @example | |
2061 | pragma Async_Writers [ (static_boolean_EXPRESSION) ]; | |
2062 | @end example | |
2063 | ||
2064 | For the semantics of this pragma, see the entry for aspect @code{Async_Writers} in | |
2065 | the SPARK 2014 Reference Manual, section 7.1.2. | |
2066 | ||
2067 | @node Pragma Attribute_Definition,Pragma C_Pass_By_Copy,Pragma Async_Writers,Implementation Defined Pragmas | |
2068 | @anchor{gnat_rm/implementation_defined_pragmas pragma-attribute-definition}@anchor{33} | |
2069 | @section Pragma Attribute_Definition | |
2070 | ||
2071 | ||
2072 | Syntax: | |
2073 | ||
2074 | @example | |
2075 | pragma Attribute_Definition | |
2076 | ([Attribute =>] ATTRIBUTE_DESIGNATOR, | |
2077 | [Entity =>] LOCAL_NAME, | |
2078 | [Expression =>] EXPRESSION | NAME); | |
2079 | @end example | |
2080 | ||
2081 | If @code{Attribute} is a known attribute name, this pragma is equivalent to | |
2082 | the attribute definition clause: | |
2083 | ||
2084 | @example | |
2085 | for Entity'Attribute use Expression; | |
2086 | @end example | |
2087 | ||
2088 | If @code{Attribute} is not a recognized attribute name, the pragma is | |
2089 | ignored, and a warning is emitted. This allows source | |
2090 | code to be written that takes advantage of some new attribute, while remaining | |
2091 | compilable with earlier compilers. | |
2092 | ||
2093 | @node Pragma C_Pass_By_Copy,Pragma Check,Pragma Attribute_Definition,Implementation Defined Pragmas | |
2094 | @anchor{gnat_rm/implementation_defined_pragmas pragma-c-pass-by-copy}@anchor{34} | |
2095 | @section Pragma C_Pass_By_Copy | |
2096 | ||
2097 | ||
2098 | @geindex Passing by copy | |
2099 | ||
2100 | Syntax: | |
2101 | ||
2102 | @example | |
2103 | pragma C_Pass_By_Copy | |
2104 | ([Max_Size =>] static_integer_EXPRESSION); | |
2105 | @end example | |
2106 | ||
2107 | Normally the default mechanism for passing C convention records to C | |
2108 | convention subprograms is to pass them by reference, as suggested by RM | |
2109 | B.3(69). Use the configuration pragma @code{C_Pass_By_Copy} to change | |
2110 | this default, by requiring that record formal parameters be passed by | |
2111 | copy if all of the following conditions are met: | |
2112 | ||
2113 | ||
2114 | @itemize * | |
2115 | ||
2116 | @item | |
2117 | The size of the record type does not exceed the value specified for | |
2118 | @code{Max_Size}. | |
2119 | ||
2120 | @item | |
2121 | The record type has @code{Convention C}. | |
2122 | ||
2123 | @item | |
2124 | The formal parameter has this record type, and the subprogram has a | |
2125 | foreign (non-Ada) convention. | |
2126 | @end itemize | |
2127 | ||
2128 | If these conditions are met the argument is passed by copy; i.e., in a | |
2129 | manner consistent with what C expects if the corresponding formal in the | |
2130 | C prototype is a struct (rather than a pointer to a struct). | |
2131 | ||
2132 | You can also pass records by copy by specifying the convention | |
2133 | @code{C_Pass_By_Copy} for the record type, or by using the extended | |
2134 | @code{Import} and @code{Export} pragmas, which allow specification of | |
2135 | passing mechanisms on a parameter by parameter basis. | |
2136 | ||
2137 | @node Pragma Check,Pragma Check_Float_Overflow,Pragma C_Pass_By_Copy,Implementation Defined Pragmas | |
2138 | @anchor{gnat_rm/implementation_defined_pragmas pragma-check}@anchor{35} | |
2139 | @section Pragma Check | |
2140 | ||
2141 | ||
2142 | @geindex Assertions | |
2143 | ||
2144 | @geindex Named assertions | |
2145 | ||
2146 | Syntax: | |
2147 | ||
2148 | @example | |
2149 | pragma Check ( | |
2150 | [Name =>] CHECK_KIND, | |
2151 | [Check =>] Boolean_EXPRESSION | |
2152 | [, [Message =>] string_EXPRESSION] ); | |
2153 | ||
2154 | CHECK_KIND ::= IDENTIFIER | | |
2155 | Pre'Class | | |
2156 | Post'Class | | |
2157 | Type_Invariant'Class | | |
2158 | Invariant'Class | |
2159 | @end example | |
2160 | ||
2161 | This pragma is similar to the predefined pragma @code{Assert} except that an | |
2162 | extra identifier argument is present. In conjunction with pragma | |
2163 | @code{Check_Policy}, this can be used to define groups of assertions that can | |
2164 | be independently controlled. The identifier @code{Assertion} is special, it | |
2165 | refers to the normal set of pragma @code{Assert} statements. | |
2166 | ||
2167 | Checks introduced by this pragma are normally deactivated by default. They can | |
1acce141 | 2168 | be activated either by the command line option @emph{-gnata}, which turns on |
64d5610f ML |
2169 | all checks, or individually controlled using pragma @code{Check_Policy}. |
2170 | ||
2171 | The identifiers @code{Assertions} and @code{Statement_Assertions} are not | |
2172 | permitted as check kinds, since this would cause confusion with the use | |
2173 | of these identifiers in @code{Assertion_Policy} and @code{Check_Policy} | |
2174 | pragmas, where they are used to refer to sets of assertions. | |
2175 | ||
2176 | @node Pragma Check_Float_Overflow,Pragma Check_Name,Pragma Check,Implementation Defined Pragmas | |
2177 | @anchor{gnat_rm/implementation_defined_pragmas pragma-check-float-overflow}@anchor{36} | |
2178 | @section Pragma Check_Float_Overflow | |
2179 | ||
2180 | ||
2181 | @geindex Floating-point overflow | |
2182 | ||
2183 | Syntax: | |
2184 | ||
2185 | @example | |
2186 | pragma Check_Float_Overflow; | |
2187 | @end example | |
2188 | ||
2189 | In Ada, the predefined floating-point types (@code{Short_Float}, | |
2190 | @code{Float}, @code{Long_Float}, @code{Long_Long_Float}) are | |
1acce141 | 2191 | defined to be @emph{unconstrained}. This means that even though each |
64d5610f ML |
2192 | has a well-defined base range, an operation that delivers a result |
2193 | outside this base range is not required to raise an exception. | |
2194 | This implementation permission accommodates the notion | |
2195 | of infinities in IEEE floating-point, and corresponds to the | |
2196 | efficient execution mode on most machines. GNAT will not raise | |
2197 | overflow exceptions on these machines; instead it will generate | |
2198 | infinities and NaN’s as defined in the IEEE standard. | |
2199 | ||
2200 | Generating infinities, although efficient, is not always desirable. | |
2201 | Often the preferable approach is to check for overflow, even at the | |
2202 | (perhaps considerable) expense of run-time performance. | |
2203 | This can be accomplished by defining your own constrained floating-point subtypes – i.e., by supplying explicit | |
2204 | range constraints – and indeed such a subtype | |
2205 | can have the same base range as its base type. For example: | |
2206 | ||
2207 | @example | |
2208 | subtype My_Float is Float range Float'Range; | |
2209 | @end example | |
2210 | ||
2211 | Here @code{My_Float} has the same range as | |
2212 | @code{Float} but is constrained, so operations on | |
2213 | @code{My_Float} values will be checked for overflow | |
2214 | against this range. | |
2215 | ||
2216 | This style will achieve the desired goal, but | |
2217 | it is often more convenient to be able to simply use | |
2218 | the standard predefined floating-point types as long | |
2219 | as overflow checking could be guaranteed. | |
2220 | The @code{Check_Float_Overflow} | |
2221 | configuration pragma achieves this effect. If a unit is compiled | |
2222 | subject to this configuration pragma, then all operations | |
2223 | on predefined floating-point types including operations on | |
2224 | base types of these floating-point types will be treated as | |
2225 | though those types were constrained, and overflow checks | |
2226 | will be generated. The @code{Constraint_Error} | |
2227 | exception is raised if the result is out of range. | |
2228 | ||
2229 | This mode can also be set by use of the compiler | |
1acce141 | 2230 | switch @emph{-gnateF}. |
64d5610f ML |
2231 | |
2232 | @node Pragma Check_Name,Pragma Check_Policy,Pragma Check_Float_Overflow,Implementation Defined Pragmas | |
2233 | @anchor{gnat_rm/implementation_defined_pragmas pragma-check-name}@anchor{37} | |
2234 | @section Pragma Check_Name | |
2235 | ||
2236 | ||
2237 | @geindex Defining check names | |
2238 | ||
2239 | @geindex Check names | |
2240 | @geindex defining | |
2241 | ||
2242 | Syntax: | |
2243 | ||
2244 | @example | |
2245 | pragma Check_Name (check_name_IDENTIFIER); | |
2246 | @end example | |
2247 | ||
2248 | This is a configuration pragma that defines a new implementation | |
2249 | defined check name (unless IDENTIFIER matches one of the predefined | |
2250 | check names, in which case the pragma has no effect). Check names | |
2251 | are global to a partition, so if two or more configuration pragmas | |
2252 | are present in a partition mentioning the same name, only one new | |
2253 | check name is introduced. | |
2254 | ||
2255 | An implementation defined check name introduced with this pragma may | |
2256 | be used in only three contexts: @code{pragma Suppress}, | |
2257 | @code{pragma Unsuppress}, | |
2258 | and as the prefix of a @code{Check_Name'Enabled} attribute reference. For | |
2259 | any of these three cases, the check name must be visible. A check | |
2260 | name is visible if it is in the configuration pragmas applying to | |
2261 | the current unit, or if it appears at the start of any unit that | |
2262 | is part of the dependency set of the current unit (e.g., units that | |
2263 | are mentioned in @code{with} clauses). | |
2264 | ||
2265 | Check names introduced by this pragma are subject to control by compiler | |
2266 | switches (in particular -gnatp) in the usual manner. | |
2267 | ||
2268 | @node Pragma Check_Policy,Pragma Comment,Pragma Check_Name,Implementation Defined Pragmas | |
2269 | @anchor{gnat_rm/implementation_defined_pragmas pragma-check-policy}@anchor{38} | |
2270 | @section Pragma Check_Policy | |
2271 | ||
2272 | ||
2273 | @geindex Controlling assertions | |
2274 | ||
2275 | @geindex Assertions | |
2276 | @geindex control | |
2277 | ||
2278 | @geindex Check pragma control | |
2279 | ||
2280 | @geindex Named assertions | |
2281 | ||
2282 | Syntax: | |
2283 | ||
2284 | @example | |
2285 | pragma Check_Policy | |
2286 | ([Name =>] CHECK_KIND, | |
2287 | [Policy =>] POLICY_IDENTIFIER); | |
2288 | ||
2289 | pragma Check_Policy ( | |
2290 | CHECK_KIND => POLICY_IDENTIFIER | |
2291 | @{, CHECK_KIND => POLICY_IDENTIFIER@}); | |
2292 | ||
2293 | ASSERTION_KIND ::= RM_ASSERTION_KIND | ID_ASSERTION_KIND | |
2294 | ||
2295 | CHECK_KIND ::= IDENTIFIER | | |
2296 | Pre'Class | | |
2297 | Post'Class | | |
2298 | Type_Invariant'Class | | |
2299 | Invariant'Class | |
2300 | ||
2301 | The identifiers Name and Policy are not allowed as CHECK_KIND values. This | |
2302 | avoids confusion between the two possible syntax forms for this pragma. | |
2303 | ||
2304 | POLICY_IDENTIFIER ::= ON | OFF | CHECK | DISABLE | IGNORE | |
2305 | @end example | |
2306 | ||
2307 | This pragma is used to set the checking policy for assertions (specified | |
2308 | by aspects or pragmas), the @code{Debug} pragma, or additional checks | |
2309 | to be checked using the @code{Check} pragma. It may appear either as | |
2310 | a configuration pragma, or within a declarative part of package. In the | |
2311 | latter case, it applies from the point where it appears to the end of | |
2312 | the declarative region (like pragma @code{Suppress}). | |
2313 | ||
2314 | The @code{Check_Policy} pragma is similar to the | |
2315 | predefined @code{Assertion_Policy} pragma, | |
2316 | and if the check kind corresponds to one of the assertion kinds that | |
2317 | are allowed by @code{Assertion_Policy}, then the effect is identical. | |
2318 | ||
2319 | If the first argument is Debug, then the policy applies to Debug pragmas, | |
2320 | disabling their effect if the policy is @code{OFF}, @code{DISABLE}, or | |
2321 | @code{IGNORE}, and allowing them to execute with normal semantics if | |
2322 | the policy is @code{ON} or @code{CHECK}. In addition if the policy is | |
2323 | @code{DISABLE}, then the procedure call in @code{Debug} pragmas will | |
2324 | be totally ignored and not analyzed semantically. | |
2325 | ||
2326 | Finally the first argument may be some other identifier than the above | |
2327 | possibilities, in which case it controls a set of named assertions | |
2328 | that can be checked using pragma @code{Check}. For example, if the pragma: | |
2329 | ||
2330 | @example | |
2331 | pragma Check_Policy (Critical_Error, OFF); | |
2332 | @end example | |
2333 | ||
2334 | is given, then subsequent @code{Check} pragmas whose first argument is also | |
2335 | @code{Critical_Error} will be disabled. | |
2336 | ||
2337 | The check policy is @code{OFF} to turn off corresponding checks, and @code{ON} | |
2338 | to turn on corresponding checks. The default for a set of checks for which no | |
2339 | @code{Check_Policy} is given is @code{OFF} unless the compiler switch | |
1acce141 | 2340 | @emph{-gnata} is given, which turns on all checks by default. |
64d5610f ML |
2341 | |
2342 | The check policy settings @code{CHECK} and @code{IGNORE} are recognized | |
2343 | as synonyms for @code{ON} and @code{OFF}. These synonyms are provided for | |
2344 | compatibility with the standard @code{Assertion_Policy} pragma. The check | |
2345 | policy setting @code{DISABLE} causes the second argument of a corresponding | |
2346 | @code{Check} pragma to be completely ignored and not analyzed. | |
2347 | ||
2348 | @node Pragma Comment,Pragma Common_Object,Pragma Check_Policy,Implementation Defined Pragmas | |
2349 | @anchor{gnat_rm/implementation_defined_pragmas pragma-comment}@anchor{39} | |
2350 | @section Pragma Comment | |
2351 | ||
2352 | ||
2353 | Syntax: | |
2354 | ||
2355 | @example | |
2356 | pragma Comment (static_string_EXPRESSION); | |
2357 | @end example | |
2358 | ||
2359 | This is almost identical in effect to pragma @code{Ident}. It allows the | |
2360 | placement of a comment into the object file and hence into the | |
2361 | executable file if the operating system permits such usage. The | |
2362 | difference is that @code{Comment}, unlike @code{Ident}, has | |
2363 | no limitations on placement of the pragma (it can be placed | |
2364 | anywhere in the main source unit), and if more than one pragma | |
2365 | is used, all comments are retained. | |
2366 | ||
2367 | @node Pragma Common_Object,Pragma Compile_Time_Error,Pragma Comment,Implementation Defined Pragmas | |
2368 | @anchor{gnat_rm/implementation_defined_pragmas pragma-common-object}@anchor{3a} | |
2369 | @section Pragma Common_Object | |
2370 | ||
2371 | ||
2372 | Syntax: | |
2373 | ||
2374 | @example | |
2375 | pragma Common_Object ( | |
2376 | [Internal =>] LOCAL_NAME | |
2377 | [, [External =>] EXTERNAL_SYMBOL] | |
2378 | [, [Size =>] EXTERNAL_SYMBOL] ); | |
2379 | ||
2380 | EXTERNAL_SYMBOL ::= | |
2381 | IDENTIFIER | |
2382 | | static_string_EXPRESSION | |
2383 | @end example | |
2384 | ||
2385 | This pragma enables the shared use of variables stored in overlaid | |
2386 | linker areas corresponding to the use of @code{COMMON} | |
2387 | in Fortran. The single | |
2388 | object @code{LOCAL_NAME} is assigned to the area designated by | |
2389 | the @code{External} argument. | |
2390 | You may define a record to correspond to a series | |
2391 | of fields. The @code{Size} argument | |
2392 | is syntax checked in GNAT, but otherwise ignored. | |
2393 | ||
2394 | @code{Common_Object} is not supported on all platforms. If no | |
2395 | support is available, then the code generator will issue a message | |
2396 | indicating that the necessary attribute for implementation of this | |
2397 | pragma is not available. | |
2398 | ||
2399 | @node Pragma Compile_Time_Error,Pragma Compile_Time_Warning,Pragma Common_Object,Implementation Defined Pragmas | |
2400 | @anchor{gnat_rm/implementation_defined_pragmas compile-time-error}@anchor{3b}@anchor{gnat_rm/implementation_defined_pragmas pragma-compile-time-error}@anchor{3c} | |
2401 | @section Pragma Compile_Time_Error | |
2402 | ||
2403 | ||
2404 | Syntax: | |
2405 | ||
2406 | @example | |
2407 | pragma Compile_Time_Error | |
2408 | (boolean_EXPRESSION, static_string_EXPRESSION); | |
2409 | @end example | |
2410 | ||
2411 | This pragma can be used to generate additional compile time | |
2412 | error messages. It | |
2413 | is particularly useful in generics, where errors can be issued for | |
2414 | specific problematic instantiations. The first parameter is a boolean | |
2415 | expression. The pragma ensures that the value of an expression | |
2416 | is known at compile time, and has the value False. The set of expressions | |
2417 | whose values are known at compile time includes all static boolean | |
2418 | expressions, and also other values which the compiler can determine | |
2419 | at compile time (e.g., the size of a record type set by an explicit | |
2420 | size representation clause, or the value of a variable which was | |
2421 | initialized to a constant and is known not to have been modified). | |
2422 | If these conditions are not met, an error message is generated using | |
2423 | the value given as the second argument. This string value may contain | |
2424 | embedded ASCII.LF characters to break the message into multiple lines. | |
2425 | ||
2426 | @node Pragma Compile_Time_Warning,Pragma Complete_Representation,Pragma Compile_Time_Error,Implementation Defined Pragmas | |
2427 | @anchor{gnat_rm/implementation_defined_pragmas pragma-compile-time-warning}@anchor{3d} | |
2428 | @section Pragma Compile_Time_Warning | |
2429 | ||
2430 | ||
2431 | Syntax: | |
2432 | ||
2433 | @example | |
2434 | pragma Compile_Time_Warning | |
2435 | (boolean_EXPRESSION, static_string_EXPRESSION); | |
2436 | @end example | |
2437 | ||
2438 | Same as pragma Compile_Time_Error, except a warning is issued instead | |
1acce141 | 2439 | of an error message. If switch @emph{-gnatw_C} is used, a warning is only issued |
64d5610f ML |
2440 | if the value of the expression is known to be True at compile time, not when |
2441 | the value of the expression is not known at compile time. | |
2442 | Note that if this pragma is used in a package that | |
2443 | is with’ed by a client, the client will get the warning even though it | |
2444 | is issued by a with’ed package (normally warnings in with’ed units are | |
2445 | suppressed, but this is a special exception to that rule). | |
2446 | ||
2447 | One typical use is within a generic where compile time known characteristics | |
2448 | of formal parameters are tested, and warnings given appropriately. Another use | |
2449 | with a first parameter of True is to warn a client about use of a package, | |
2450 | for example that it is not fully implemented. | |
2451 | ||
1acce141 | 2452 | In previous versions of the compiler, combining @emph{-gnatwe} with |
64d5610f ML |
2453 | Compile_Time_Warning resulted in a fatal error. Now the compiler always emits |
2454 | a warning. You can use @ref{3b,,Pragma Compile_Time_Error} to force the generation of | |
2455 | an error. | |
2456 | ||
2457 | @node Pragma Complete_Representation,Pragma Complex_Representation,Pragma Compile_Time_Warning,Implementation Defined Pragmas | |
2458 | @anchor{gnat_rm/implementation_defined_pragmas pragma-complete-representation}@anchor{3e} | |
2459 | @section Pragma Complete_Representation | |
2460 | ||
2461 | ||
2462 | Syntax: | |
2463 | ||
2464 | @example | |
2465 | pragma Complete_Representation; | |
2466 | @end example | |
2467 | ||
2468 | This pragma must appear immediately within a record representation | |
2469 | clause. Typical placements are before the first component clause | |
2470 | or after the last component clause. The effect is to give an error | |
2471 | message if any component is missing a component clause. This pragma | |
2472 | may be used to ensure that a record representation clause is | |
2473 | complete, and that this invariant is maintained if fields are | |
2474 | added to the record in the future. | |
2475 | ||
2476 | @node Pragma Complex_Representation,Pragma Component_Alignment,Pragma Complete_Representation,Implementation Defined Pragmas | |
2477 | @anchor{gnat_rm/implementation_defined_pragmas pragma-complex-representation}@anchor{3f} | |
2478 | @section Pragma Complex_Representation | |
2479 | ||
2480 | ||
2481 | Syntax: | |
2482 | ||
2483 | @example | |
2484 | pragma Complex_Representation | |
2485 | ([Entity =>] LOCAL_NAME); | |
2486 | @end example | |
2487 | ||
2488 | The @code{Entity} argument must be the name of a record type which has | |
2489 | two fields of the same floating-point type. The effect of this pragma is | |
2490 | to force gcc to use the special internal complex representation form for | |
2491 | this record, which may be more efficient. Note that this may result in | |
2492 | the code for this type not conforming to standard ABI (application | |
2493 | binary interface) requirements for the handling of record types. For | |
2494 | example, in some environments, there is a requirement for passing | |
2495 | records by pointer, and the use of this pragma may result in passing | |
2496 | this type in floating-point registers. | |
2497 | ||
2498 | @node Pragma Component_Alignment,Pragma Constant_After_Elaboration,Pragma Complex_Representation,Implementation Defined Pragmas | |
2499 | @anchor{gnat_rm/implementation_defined_pragmas pragma-component-alignment}@anchor{40} | |
2500 | @section Pragma Component_Alignment | |
2501 | ||
2502 | ||
2503 | @geindex Alignments of components | |
2504 | ||
2505 | @geindex Pragma Component_Alignment | |
2506 | ||
2507 | Syntax: | |
2508 | ||
2509 | @example | |
2510 | pragma Component_Alignment ( | |
2511 | [Form =>] ALIGNMENT_CHOICE | |
2512 | [, [Name =>] type_LOCAL_NAME]); | |
2513 | ||
2514 | ALIGNMENT_CHOICE ::= | |
2515 | Component_Size | |
2516 | | Component_Size_4 | |
2517 | | Storage_Unit | |
2518 | | Default | |
2519 | @end example | |
2520 | ||
2521 | Specifies the alignment of components in array or record types. | |
2522 | The meaning of the @code{Form} argument is as follows: | |
2523 | ||
2524 | @quotation | |
2525 | ||
2526 | @geindex Component_Size (in pragma Component_Alignment) | |
2527 | @end quotation | |
2528 | ||
2529 | ||
2530 | @table @asis | |
2531 | ||
1acce141 | 2532 | @item @emph{Component_Size} |
64d5610f ML |
2533 | |
2534 | Aligns scalar components and subcomponents of the array or record type | |
2535 | on boundaries appropriate to their inherent size (naturally | |
2536 | aligned). For example, 1-byte components are aligned on byte boundaries, | |
2537 | 2-byte integer components are aligned on 2-byte boundaries, 4-byte | |
2538 | integer components are aligned on 4-byte boundaries and so on. These | |
2539 | alignment rules correspond to the normal rules for C compilers on all | |
2540 | machines except the VAX. | |
2541 | ||
2542 | @geindex Component_Size_4 (in pragma Component_Alignment) | |
2543 | ||
1acce141 | 2544 | @item @emph{Component_Size_4} |
64d5610f ML |
2545 | |
2546 | Naturally aligns components with a size of four or fewer | |
2547 | bytes. Components that are larger than 4 bytes are placed on the next | |
2548 | 4-byte boundary. | |
2549 | ||
2550 | @geindex Storage_Unit (in pragma Component_Alignment) | |
2551 | ||
1acce141 | 2552 | @item @emph{Storage_Unit} |
64d5610f ML |
2553 | |
2554 | Specifies that array or record components are byte aligned, i.e., | |
2555 | aligned on boundaries determined by the value of the constant | |
2556 | @code{System.Storage_Unit}. | |
2557 | ||
2558 | @geindex Default (in pragma Component_Alignment) | |
2559 | ||
1acce141 | 2560 | @item @emph{Default} |
64d5610f ML |
2561 | |
2562 | Specifies that array or record components are aligned on default | |
2563 | boundaries, appropriate to the underlying hardware or operating system or | |
2564 | both. The @code{Default} choice is the same as @code{Component_Size} (natural | |
2565 | alignment). | |
2566 | @end table | |
2567 | ||
2568 | If the @code{Name} parameter is present, @code{type_LOCAL_NAME} must | |
2569 | refer to a local record or array type, and the specified alignment | |
2570 | choice applies to the specified type. The use of | |
2571 | @code{Component_Alignment} together with a pragma @code{Pack} causes the | |
2572 | @code{Component_Alignment} pragma to be ignored. The use of | |
2573 | @code{Component_Alignment} together with a record representation clause | |
2574 | is only effective for fields not specified by the representation clause. | |
2575 | ||
2576 | If the @code{Name} parameter is absent, the pragma can be used as either | |
2577 | a configuration pragma, in which case it applies to one or more units in | |
2578 | accordance with the normal rules for configuration pragmas, or it can be | |
2579 | used within a declarative part, in which case it applies to types that | |
2580 | are declared within this declarative part, or within any nested scope | |
2581 | within this declarative part. In either case it specifies the alignment | |
2582 | to be applied to any record or array type which has otherwise standard | |
2583 | representation. | |
2584 | ||
2585 | If the alignment for a record or array type is not specified (using | |
2586 | pragma @code{Pack}, pragma @code{Component_Alignment}, or a record rep | |
2587 | clause), the GNAT uses the default alignment as described previously. | |
2588 | ||
2589 | @node Pragma Constant_After_Elaboration,Pragma Contract_Cases,Pragma Component_Alignment,Implementation Defined Pragmas | |
2590 | @anchor{gnat_rm/implementation_defined_pragmas id6}@anchor{41}@anchor{gnat_rm/implementation_defined_pragmas pragma-constant-after-elaboration}@anchor{42} | |
2591 | @section Pragma Constant_After_Elaboration | |
2592 | ||
2593 | ||
2594 | Syntax: | |
2595 | ||
2596 | @example | |
2597 | pragma Constant_After_Elaboration [ (static_boolean_EXPRESSION) ]; | |
2598 | @end example | |
2599 | ||
2600 | For the semantics of this pragma, see the entry for aspect | |
2601 | @code{Constant_After_Elaboration} in the SPARK 2014 Reference Manual, section 3.3.1. | |
2602 | ||
2603 | @node Pragma Contract_Cases,Pragma Convention_Identifier,Pragma Constant_After_Elaboration,Implementation Defined Pragmas | |
2604 | @anchor{gnat_rm/implementation_defined_pragmas id7}@anchor{43}@anchor{gnat_rm/implementation_defined_pragmas pragma-contract-cases}@anchor{44} | |
2605 | @section Pragma Contract_Cases | |
2606 | ||
2607 | ||
2608 | @geindex Contract cases | |
2609 | ||
2610 | Syntax: | |
2611 | ||
2612 | @example | |
2613 | pragma Contract_Cases (CONTRACT_CASE @{, CONTRACT_CASE@}); | |
2614 | ||
2615 | CONTRACT_CASE ::= CASE_GUARD => CONSEQUENCE | |
2616 | ||
2617 | CASE_GUARD ::= boolean_EXPRESSION | others | |
2618 | ||
2619 | CONSEQUENCE ::= boolean_EXPRESSION | |
2620 | @end example | |
2621 | ||
2622 | The @code{Contract_Cases} pragma allows defining fine-grain specifications | |
2623 | that can complement or replace the contract given by a precondition and a | |
2624 | postcondition. Additionally, the @code{Contract_Cases} pragma can be used | |
2625 | by testing and formal verification tools. The compiler checks its validity and, | |
2626 | depending on the assertion policy at the point of declaration of the pragma, | |
2627 | it may insert a check in the executable. For code generation, the contract | |
2628 | cases | |
2629 | ||
2630 | @example | |
2631 | pragma Contract_Cases ( | |
2632 | Cond1 => Pred1, | |
2633 | Cond2 => Pred2); | |
2634 | @end example | |
2635 | ||
2636 | are equivalent to | |
2637 | ||
2638 | @example | |
2639 | C1 : constant Boolean := Cond1; -- evaluated at subprogram entry | |
2640 | C2 : constant Boolean := Cond2; -- evaluated at subprogram entry | |
2641 | pragma Precondition ((C1 and not C2) or (C2 and not C1)); | |
2642 | pragma Postcondition (if C1 then Pred1); | |
2643 | pragma Postcondition (if C2 then Pred2); | |
2644 | @end example | |
2645 | ||
2646 | The precondition ensures that one and only one of the case guards is | |
2647 | satisfied on entry to the subprogram. | |
2648 | The postcondition ensures that for the case guard that was True on entry, | |
2649 | the corresponding consequence is True on exit. Other consequence expressions | |
2650 | are not evaluated. | |
2651 | ||
2652 | A precondition @code{P} and postcondition @code{Q} can also be | |
2653 | expressed as contract cases: | |
2654 | ||
2655 | @example | |
2656 | pragma Contract_Cases (P => Q); | |
2657 | @end example | |
2658 | ||
2659 | The placement and visibility rules for @code{Contract_Cases} pragmas are | |
2660 | identical to those described for preconditions and postconditions. | |
2661 | ||
2662 | The compiler checks that boolean expressions given in case guards and | |
2663 | consequences are valid, where the rules for case guards are the same as | |
2664 | the rule for an expression in @code{Precondition} and the rules for | |
2665 | consequences are the same as the rule for an expression in | |
2666 | @code{Postcondition}. In particular, attributes @code{'Old} and | |
2667 | @code{'Result} can only be used within consequence expressions. | |
2668 | The case guard for the last contract case may be @code{others}, to denote | |
2669 | any case not captured by the previous cases. The | |
2670 | following is an example of use within a package spec: | |
2671 | ||
2672 | @example | |
2673 | package Math_Functions is | |
2674 | ... | |
2675 | function Sqrt (Arg : Float) return Float; | |
2676 | pragma Contract_Cases (((Arg in 0.0 .. 99.0) => Sqrt'Result < 10.0, | |
2677 | Arg >= 100.0 => Sqrt'Result >= 10.0, | |
2678 | others => Sqrt'Result = 0.0)); | |
2679 | ... | |
2680 | end Math_Functions; | |
2681 | @end example | |
2682 | ||
2683 | The meaning of contract cases is that only one case should apply at each | |
2684 | call, as determined by the corresponding case guard evaluating to True, | |
2685 | and that the consequence for this case should hold when the subprogram | |
2686 | returns. | |
2687 | ||
2688 | @node Pragma Convention_Identifier,Pragma CPP_Class,Pragma Contract_Cases,Implementation Defined Pragmas | |
2689 | @anchor{gnat_rm/implementation_defined_pragmas pragma-convention-identifier}@anchor{45} | |
2690 | @section Pragma Convention_Identifier | |
2691 | ||
2692 | ||
2693 | @geindex Conventions | |
2694 | @geindex synonyms | |
2695 | ||
2696 | Syntax: | |
2697 | ||
2698 | @example | |
2699 | pragma Convention_Identifier ( | |
2700 | [Name =>] IDENTIFIER, | |
2701 | [Convention =>] convention_IDENTIFIER); | |
2702 | @end example | |
2703 | ||
2704 | This pragma provides a mechanism for supplying synonyms for existing | |
2705 | convention identifiers. The @code{Name} identifier can subsequently | |
2706 | be used as a synonym for the given convention in other pragmas (including | |
2707 | for example pragma @code{Import} or another @code{Convention_Identifier} | |
2708 | pragma). As an example of the use of this, suppose you had legacy code | |
2709 | which used Fortran77 as the identifier for Fortran. Then the pragma: | |
2710 | ||
2711 | @example | |
2712 | pragma Convention_Identifier (Fortran77, Fortran); | |
2713 | @end example | |
2714 | ||
2715 | would allow the use of the convention identifier @code{Fortran77} in | |
2716 | subsequent code, avoiding the need to modify the sources. As another | |
2717 | example, you could use this to parameterize convention requirements | |
2718 | according to systems. Suppose you needed to use @code{Stdcall} on | |
2719 | windows systems, and @code{C} on some other system, then you could | |
2720 | define a convention identifier @code{Library} and use a single | |
2721 | @code{Convention_Identifier} pragma to specify which convention | |
2722 | would be used system-wide. | |
2723 | ||
2724 | @node Pragma CPP_Class,Pragma CPP_Constructor,Pragma Convention_Identifier,Implementation Defined Pragmas | |
2725 | @anchor{gnat_rm/implementation_defined_pragmas pragma-cpp-class}@anchor{46} | |
2726 | @section Pragma CPP_Class | |
2727 | ||
2728 | ||
2729 | @geindex Interfacing with C++ | |
2730 | ||
2731 | Syntax: | |
2732 | ||
2733 | @example | |
2734 | pragma CPP_Class ([Entity =>] LOCAL_NAME); | |
2735 | @end example | |
2736 | ||
2737 | The argument denotes an entity in the current declarative region that is | |
2738 | declared as a record type. It indicates that the type corresponds to an | |
2739 | externally declared C++ class type, and is to be laid out the same way | |
2740 | that C++ would lay out the type. If the C++ class has virtual primitives | |
2741 | then the record must be declared as a tagged record type. | |
2742 | ||
2743 | Types for which @code{CPP_Class} is specified do not have assignment or | |
2744 | equality operators defined (such operations can be imported or declared | |
2745 | as subprograms as required). Initialization is allowed only by constructor | |
2746 | functions (see pragma @code{CPP_Constructor}). Such types are implicitly | |
2747 | limited if not explicitly declared as limited or derived from a limited | |
2748 | type, and an error is issued in that case. | |
2749 | ||
2750 | See @ref{47,,Interfacing to C++} for related information. | |
2751 | ||
2752 | Note: Pragma @code{CPP_Class} is currently obsolete. It is supported | |
2753 | for backward compatibility but its functionality is available | |
2754 | using pragma @code{Import} with @code{Convention} = @code{CPP}. | |
2755 | ||
2756 | @node Pragma CPP_Constructor,Pragma CPP_Virtual,Pragma CPP_Class,Implementation Defined Pragmas | |
2757 | @anchor{gnat_rm/implementation_defined_pragmas pragma-cpp-constructor}@anchor{48} | |
2758 | @section Pragma CPP_Constructor | |
2759 | ||
2760 | ||
2761 | @geindex Interfacing with C++ | |
2762 | ||
2763 | Syntax: | |
2764 | ||
2765 | @example | |
2766 | pragma CPP_Constructor ([Entity =>] LOCAL_NAME | |
2767 | [, [External_Name =>] static_string_EXPRESSION ] | |
2768 | [, [Link_Name =>] static_string_EXPRESSION ]); | |
2769 | @end example | |
2770 | ||
2771 | This pragma identifies an imported function (imported in the usual way | |
2772 | with pragma @code{Import}) as corresponding to a C++ constructor. If | |
2773 | @code{External_Name} and @code{Link_Name} are not specified then the | |
2774 | @code{Entity} argument is a name that must have been previously mentioned | |
2775 | in a pragma @code{Import} with @code{Convention} = @code{CPP}. Such name | |
2776 | must be of one of the following forms: | |
2777 | ||
2778 | ||
2779 | @itemize * | |
2780 | ||
2781 | @item | |
1acce141 | 2782 | @strong{function} @code{Fname} @strong{return} T` |
64d5610f ML |
2783 | |
2784 | @item | |
1acce141 | 2785 | @strong{function} @code{Fname} @strong{return} T’Class |
64d5610f ML |
2786 | |
2787 | @item | |
1acce141 | 2788 | @strong{function} @code{Fname} (…) @strong{return} T` |
64d5610f ML |
2789 | |
2790 | @item | |
1acce141 | 2791 | @strong{function} @code{Fname} (…) @strong{return} T’Class |
64d5610f ML |
2792 | @end itemize |
2793 | ||
2794 | where @code{T} is a limited record type imported from C++ with pragma | |
2795 | @code{Import} and @code{Convention} = @code{CPP}. | |
2796 | ||
2797 | The first two forms import the default constructor, used when an object | |
2798 | of type @code{T} is created on the Ada side with no explicit constructor. | |
2799 | The latter two forms cover all the non-default constructors of the type. | |
2800 | See the GNAT User’s Guide for details. | |
2801 | ||
2802 | If no constructors are imported, it is impossible to create any objects | |
2803 | on the Ada side and the type is implicitly declared abstract. | |
2804 | ||
2805 | Pragma @code{CPP_Constructor} is intended primarily for automatic generation | |
2806 | using an automatic binding generator tool (such as the @code{-fdump-ada-spec} | |
2807 | GCC switch). | |
2808 | See @ref{47,,Interfacing to C++} for more related information. | |
2809 | ||
2810 | Note: The use of functions returning class-wide types for constructors is | |
2811 | currently obsolete. They are supported for backward compatibility. The | |
2812 | use of functions returning the type T leave the Ada sources more clear | |
2813 | because the imported C++ constructors always return an object of type T; | |
2814 | that is, they never return an object whose type is a descendant of type T. | |
2815 | ||
2816 | @node Pragma CPP_Virtual,Pragma CPP_Vtable,Pragma CPP_Constructor,Implementation Defined Pragmas | |
2817 | @anchor{gnat_rm/implementation_defined_pragmas pragma-cpp-virtual}@anchor{49} | |
2818 | @section Pragma CPP_Virtual | |
2819 | ||
2820 | ||
2821 | @geindex Interfacing to C++ | |
2822 | ||
2823 | This pragma is now obsolete and, other than generating a warning if warnings | |
2824 | on obsolescent features are enabled, is completely ignored. | |
2825 | It is retained for compatibility | |
2826 | purposes. It used to be required to ensure compatibility with C++, but | |
2827 | is no longer required for that purpose because GNAT generates | |
2828 | the same object layout as the G++ compiler by default. | |
2829 | ||
2830 | See @ref{47,,Interfacing to C++} for related information. | |
2831 | ||
2832 | @node Pragma CPP_Vtable,Pragma CPU,Pragma CPP_Virtual,Implementation Defined Pragmas | |
2833 | @anchor{gnat_rm/implementation_defined_pragmas pragma-cpp-vtable}@anchor{4a} | |
2834 | @section Pragma CPP_Vtable | |
2835 | ||
2836 | ||
2837 | @geindex Interfacing with C++ | |
2838 | ||
2839 | This pragma is now obsolete and, other than generating a warning if warnings | |
2840 | on obsolescent features are enabled, is completely ignored. | |
2841 | It used to be required to ensure compatibility with C++, but | |
2842 | is no longer required for that purpose because GNAT generates | |
2843 | the same object layout as the G++ compiler by default. | |
2844 | ||
2845 | See @ref{47,,Interfacing to C++} for related information. | |
2846 | ||
2847 | @node Pragma CPU,Pragma Deadline_Floor,Pragma CPP_Vtable,Implementation Defined Pragmas | |
2848 | @anchor{gnat_rm/implementation_defined_pragmas pragma-cpu}@anchor{4b} | |
2849 | @section Pragma CPU | |
2850 | ||
2851 | ||
2852 | Syntax: | |
2853 | ||
2854 | @example | |
2855 | pragma CPU (EXPRESSION); | |
2856 | @end example | |
2857 | ||
2858 | This pragma is standard in Ada 2012, but is available in all earlier | |
2859 | versions of Ada as an implementation-defined pragma. | |
2860 | See Ada 2012 Reference Manual for details. | |
2861 | ||
6f089469 | 2862 | @node Pragma Deadline_Floor,Pragma Debug,Pragma CPU,Implementation Defined Pragmas |
64d5610f ML |
2863 | @anchor{gnat_rm/implementation_defined_pragmas pragma-deadline-floor}@anchor{4c} |
2864 | @section Pragma Deadline_Floor | |
2865 | ||
2866 | ||
2867 | Syntax: | |
2868 | ||
2869 | @example | |
2870 | pragma Deadline_Floor (time_span_EXPRESSION); | |
2871 | @end example | |
2872 | ||
2873 | This pragma applies only to protected types and specifies the floor | |
2874 | deadline inherited by a task when the task enters a protected object. | |
2875 | It is effective only when the EDF scheduling policy is used. | |
2876 | ||
6f089469 RD |
2877 | @node Pragma Debug,Pragma Debug_Policy,Pragma Deadline_Floor,Implementation Defined Pragmas |
2878 | @anchor{gnat_rm/implementation_defined_pragmas pragma-debug}@anchor{4d} | |
64d5610f ML |
2879 | @section Pragma Debug |
2880 | ||
2881 | ||
2882 | Syntax: | |
2883 | ||
2884 | @example | |
2885 | pragma Debug ([CONDITION, ]PROCEDURE_CALL_WITHOUT_SEMICOLON); | |
2886 | ||
2887 | PROCEDURE_CALL_WITHOUT_SEMICOLON ::= | |
2888 | PROCEDURE_NAME | |
2889 | | PROCEDURE_PREFIX ACTUAL_PARAMETER_PART | |
2890 | @end example | |
2891 | ||
2892 | The procedure call argument has the syntactic form of an expression, meeting | |
2893 | the syntactic requirements for pragmas. | |
2894 | ||
2895 | If debug pragmas are not enabled or if the condition is present and evaluates | |
2896 | to False, this pragma has no effect. If debug pragmas are enabled, the | |
2897 | semantics of the pragma is exactly equivalent to the procedure call statement | |
2898 | corresponding to the argument with a terminating semicolon. Pragmas are | |
2899 | permitted in sequences of declarations, so you can use pragma @code{Debug} to | |
2900 | intersperse calls to debug procedures in the middle of declarations. Debug | |
1acce141 | 2901 | pragmas can be enabled either by use of the command line switch @emph{-gnata} |
64d5610f ML |
2902 | or by use of the pragma @code{Check_Policy} with a first argument of |
2903 | @code{Debug}. | |
2904 | ||
6f089469 RD |
2905 | @node Pragma Debug_Policy,Pragma Default_Initial_Condition,Pragma Debug,Implementation Defined Pragmas |
2906 | @anchor{gnat_rm/implementation_defined_pragmas pragma-debug-policy}@anchor{4e} | |
64d5610f ML |
2907 | @section Pragma Debug_Policy |
2908 | ||
2909 | ||
2910 | Syntax: | |
2911 | ||
2912 | @example | |
2913 | pragma Debug_Policy (CHECK | DISABLE | IGNORE | ON | OFF); | |
2914 | @end example | |
2915 | ||
2916 | This pragma is equivalent to a corresponding @code{Check_Policy} pragma | |
2917 | with a first argument of @code{Debug}. It is retained for historical | |
2918 | compatibility reasons. | |
2919 | ||
6f089469 RD |
2920 | @node Pragma Default_Initial_Condition,Pragma Default_Scalar_Storage_Order,Pragma Debug_Policy,Implementation Defined Pragmas |
2921 | @anchor{gnat_rm/implementation_defined_pragmas id8}@anchor{4f}@anchor{gnat_rm/implementation_defined_pragmas pragma-default-initial-condition}@anchor{50} | |
2922 | @section Pragma Default_Initial_Condition | |
2923 | ||
2924 | ||
2925 | Syntax: | |
2926 | ||
2927 | @example | |
2928 | pragma Default_Initial_Condition [ (null | boolean_EXPRESSION) ]; | |
2929 | @end example | |
2930 | ||
2931 | For the semantics of this pragma, see the entry for aspect | |
2932 | @code{Default_Initial_Condition} in the SPARK 2014 Reference Manual, section 7.3.3. | |
2933 | ||
2934 | @node Pragma Default_Scalar_Storage_Order,Pragma Default_Storage_Pool,Pragma Default_Initial_Condition,Implementation Defined Pragmas | |
64d5610f ML |
2935 | @anchor{gnat_rm/implementation_defined_pragmas pragma-default-scalar-storage-order}@anchor{51} |
2936 | @section Pragma Default_Scalar_Storage_Order | |
2937 | ||
2938 | ||
2939 | @geindex Default_Scalar_Storage_Order | |
2940 | ||
2941 | @geindex Scalar_Storage_Order | |
2942 | ||
2943 | Syntax: | |
2944 | ||
2945 | @example | |
2946 | pragma Default_Scalar_Storage_Order (High_Order_First | Low_Order_First); | |
2947 | @end example | |
2948 | ||
2949 | Normally if no explicit @code{Scalar_Storage_Order} is given for a record | |
2950 | type or array type, then the scalar storage order defaults to the ordinary | |
2951 | default for the target. But this default may be overridden using this pragma. | |
2952 | The pragma may appear as a configuration pragma, or locally within a package | |
2953 | spec or declarative part. In the latter case, it applies to all subsequent | |
2954 | types declared within that package spec or declarative part. | |
2955 | ||
2956 | The following example shows the use of this pragma: | |
2957 | ||
2958 | @example | |
2959 | pragma Default_Scalar_Storage_Order (High_Order_First); | |
2960 | with System; use System; | |
2961 | package DSSO1 is | |
2962 | type H1 is record | |
2963 | a : Integer; | |
2964 | end record; | |
2965 | ||
2966 | type L2 is record | |
2967 | a : Integer; | |
2968 | end record; | |
2969 | for L2'Scalar_Storage_Order use Low_Order_First; | |
2970 | ||
2971 | type L2a is new L2; | |
2972 | ||
2973 | package Inner is | |
2974 | type H3 is record | |
2975 | a : Integer; | |
2976 | end record; | |
2977 | ||
2978 | pragma Default_Scalar_Storage_Order (Low_Order_First); | |
2979 | ||
2980 | type L4 is record | |
2981 | a : Integer; | |
2982 | end record; | |
2983 | end Inner; | |
2984 | ||
2985 | type H4a is new Inner.L4; | |
2986 | ||
2987 | type H5 is record | |
2988 | a : Integer; | |
2989 | end record; | |
2990 | end DSSO1; | |
2991 | @end example | |
2992 | ||
1acce141 YM |
2993 | In this example record types with names starting with @emph{L} have @cite{Low_Order_First} scalar |
2994 | storage order, and record types with names starting with @emph{H} have @code{High_Order_First}. | |
64d5610f ML |
2995 | Note that in the case of @code{H4a}, the order is not inherited |
2996 | from the parent type. Only an explicitly set @code{Scalar_Storage_Order} | |
2997 | gets inherited on type derivation. | |
2998 | ||
2999 | If this pragma is used as a configuration pragma which appears within a | |
3000 | configuration pragma file (as opposed to appearing explicitly at the start | |
3001 | of a single unit), then the binder will require that all units in a partition | |
3002 | be compiled in a similar manner, other than run-time units, which are not | |
3003 | affected by this pragma. Note that the use of this form is discouraged because | |
3004 | it may significantly degrade the run-time performance of the software, instead | |
3005 | the default scalar storage order ought to be changed only on a local basis. | |
3006 | ||
3007 | @node Pragma Default_Storage_Pool,Pragma Depends,Pragma Default_Scalar_Storage_Order,Implementation Defined Pragmas | |
3008 | @anchor{gnat_rm/implementation_defined_pragmas pragma-default-storage-pool}@anchor{52} | |
3009 | @section Pragma Default_Storage_Pool | |
3010 | ||
3011 | ||
3012 | @geindex Default_Storage_Pool | |
3013 | ||
3014 | Syntax: | |
3015 | ||
3016 | @example | |
3017 | pragma Default_Storage_Pool (storage_pool_NAME | null); | |
3018 | @end example | |
3019 | ||
3020 | This pragma is standard in Ada 2012, but is available in all earlier | |
3021 | versions of Ada as an implementation-defined pragma. | |
3022 | See Ada 2012 Reference Manual for details. | |
3023 | ||
3024 | @node Pragma Depends,Pragma Detect_Blocking,Pragma Default_Storage_Pool,Implementation Defined Pragmas | |
3025 | @anchor{gnat_rm/implementation_defined_pragmas id9}@anchor{53}@anchor{gnat_rm/implementation_defined_pragmas pragma-depends}@anchor{54} | |
3026 | @section Pragma Depends | |
3027 | ||
3028 | ||
3029 | Syntax: | |
3030 | ||
3031 | @example | |
3032 | pragma Depends (DEPENDENCY_RELATION); | |
3033 | ||
3034 | DEPENDENCY_RELATION ::= | |
3035 | null | |
3036 | | (DEPENDENCY_CLAUSE @{, DEPENDENCY_CLAUSE@}) | |
3037 | ||
3038 | DEPENDENCY_CLAUSE ::= | |
3039 | OUTPUT_LIST =>[+] INPUT_LIST | |
3040 | | NULL_DEPENDENCY_CLAUSE | |
3041 | ||
3042 | NULL_DEPENDENCY_CLAUSE ::= null => INPUT_LIST | |
3043 | ||
3044 | OUTPUT_LIST ::= OUTPUT | (OUTPUT @{, OUTPUT@}) | |
3045 | ||
3046 | INPUT_LIST ::= null | INPUT | (INPUT @{, INPUT@}) | |
3047 | ||
3048 | OUTPUT ::= NAME | FUNCTION_RESULT | |
3049 | INPUT ::= NAME | |
3050 | ||
3051 | where FUNCTION_RESULT is a function Result attribute_reference | |
3052 | @end example | |
3053 | ||
3054 | For the semantics of this pragma, see the entry for aspect @code{Depends} in the | |
3055 | SPARK 2014 Reference Manual, section 6.1.5. | |
3056 | ||
3057 | @node Pragma Detect_Blocking,Pragma Disable_Atomic_Synchronization,Pragma Depends,Implementation Defined Pragmas | |
3058 | @anchor{gnat_rm/implementation_defined_pragmas pragma-detect-blocking}@anchor{55} | |
3059 | @section Pragma Detect_Blocking | |
3060 | ||
3061 | ||
3062 | Syntax: | |
3063 | ||
3064 | @example | |
3065 | pragma Detect_Blocking; | |
3066 | @end example | |
3067 | ||
3068 | This is a standard pragma in Ada 2005, that is available in all earlier | |
3069 | versions of Ada as an implementation-defined pragma. | |
3070 | ||
3071 | This is a configuration pragma that forces the detection of potentially | |
3072 | blocking operations within a protected operation, and to raise Program_Error | |
3073 | if that happens. | |
3074 | ||
3075 | @node Pragma Disable_Atomic_Synchronization,Pragma Dispatching_Domain,Pragma Detect_Blocking,Implementation Defined Pragmas | |
3076 | @anchor{gnat_rm/implementation_defined_pragmas pragma-disable-atomic-synchronization}@anchor{56} | |
3077 | @section Pragma Disable_Atomic_Synchronization | |
3078 | ||
3079 | ||
3080 | @geindex Atomic Synchronization | |
3081 | ||
3082 | Syntax: | |
3083 | ||
3084 | @example | |
3085 | pragma Disable_Atomic_Synchronization [(Entity)]; | |
3086 | @end example | |
3087 | ||
3088 | Ada requires that accesses (reads or writes) of an atomic variable be | |
3089 | regarded as synchronization points in the case of multiple tasks. | |
3090 | Particularly in the case of multi-processors this may require special | |
3091 | handling, e.g. the generation of memory barriers. This capability may | |
3092 | be turned off using this pragma in cases where it is known not to be | |
3093 | required. | |
3094 | ||
3095 | The placement and scope rules for this pragma are the same as those | |
3096 | for @code{pragma Suppress}. In particular it can be used as a | |
3097 | configuration pragma, or in a declaration sequence where it applies | |
3098 | till the end of the scope. If an @code{Entity} argument is present, | |
3099 | the action applies only to that entity. | |
3100 | ||
3101 | @node Pragma Dispatching_Domain,Pragma Effective_Reads,Pragma Disable_Atomic_Synchronization,Implementation Defined Pragmas | |
3102 | @anchor{gnat_rm/implementation_defined_pragmas pragma-dispatching-domain}@anchor{57} | |
3103 | @section Pragma Dispatching_Domain | |
3104 | ||
3105 | ||
3106 | Syntax: | |
3107 | ||
3108 | @example | |
3109 | pragma Dispatching_Domain (EXPRESSION); | |
3110 | @end example | |
3111 | ||
3112 | This pragma is standard in Ada 2012, but is available in all earlier | |
3113 | versions of Ada as an implementation-defined pragma. | |
3114 | See Ada 2012 Reference Manual for details. | |
3115 | ||
3116 | @node Pragma Effective_Reads,Pragma Effective_Writes,Pragma Dispatching_Domain,Implementation Defined Pragmas | |
3117 | @anchor{gnat_rm/implementation_defined_pragmas id10}@anchor{58}@anchor{gnat_rm/implementation_defined_pragmas pragma-effective-reads}@anchor{59} | |
3118 | @section Pragma Effective_Reads | |
3119 | ||
3120 | ||
3121 | Syntax: | |
3122 | ||
3123 | @example | |
3124 | pragma Effective_Reads [ (static_boolean_EXPRESSION) ]; | |
3125 | @end example | |
3126 | ||
3127 | For the semantics of this pragma, see the entry for aspect @code{Effective_Reads} in | |
3128 | the SPARK 2014 Reference Manual, section 7.1.2. | |
3129 | ||
3130 | @node Pragma Effective_Writes,Pragma Elaboration_Checks,Pragma Effective_Reads,Implementation Defined Pragmas | |
3131 | @anchor{gnat_rm/implementation_defined_pragmas id11}@anchor{5a}@anchor{gnat_rm/implementation_defined_pragmas pragma-effective-writes}@anchor{5b} | |
3132 | @section Pragma Effective_Writes | |
3133 | ||
3134 | ||
3135 | Syntax: | |
3136 | ||
3137 | @example | |
3138 | pragma Effective_Writes [ (static_boolean_EXPRESSION) ]; | |
3139 | @end example | |
3140 | ||
3141 | For the semantics of this pragma, see the entry for aspect @code{Effective_Writes} | |
3142 | in the SPARK 2014 Reference Manual, section 7.1.2. | |
3143 | ||
3144 | @node Pragma Elaboration_Checks,Pragma Eliminate,Pragma Effective_Writes,Implementation Defined Pragmas | |
3145 | @anchor{gnat_rm/implementation_defined_pragmas pragma-elaboration-checks}@anchor{5c} | |
3146 | @section Pragma Elaboration_Checks | |
3147 | ||
3148 | ||
3149 | @geindex Elaboration control | |
3150 | ||
3151 | Syntax: | |
3152 | ||
3153 | @example | |
3154 | pragma Elaboration_Checks (Dynamic | Static); | |
3155 | @end example | |
3156 | ||
3157 | This is a configuration pragma which specifies the elaboration model to be | |
3158 | used during compilation. For more information on the elaboration models of | |
1acce141 YM |
3159 | GNAT, consult the chapter on elaboration order handling in the @emph{GNAT User’s |
3160 | Guide}. | |
64d5610f ML |
3161 | |
3162 | The pragma may appear in the following contexts: | |
3163 | ||
3164 | ||
3165 | @itemize * | |
3166 | ||
3167 | @item | |
3168 | Configuration pragmas file | |
3169 | ||
3170 | @item | |
3171 | Prior to the context clauses of a compilation unit’s initial declaration | |
3172 | @end itemize | |
3173 | ||
3174 | Any other placement of the pragma will result in a warning and the effects of | |
3175 | the offending pragma will be ignored. | |
3176 | ||
3177 | If the pragma argument is @code{Dynamic}, then the dynamic elaboration model is in | |
3178 | effect. If the pragma argument is @code{Static}, then the static elaboration model | |
3179 | is in effect. | |
3180 | ||
3181 | @node Pragma Eliminate,Pragma Enable_Atomic_Synchronization,Pragma Elaboration_Checks,Implementation Defined Pragmas | |
3182 | @anchor{gnat_rm/implementation_defined_pragmas pragma-eliminate}@anchor{5d} | |
3183 | @section Pragma Eliminate | |
3184 | ||
3185 | ||
3186 | @geindex Elimination of unused subprograms | |
3187 | ||
3188 | Syntax: | |
3189 | ||
3190 | @example | |
3191 | pragma Eliminate ( | |
3192 | [ Unit_Name => ] IDENTIFIER | SELECTED_COMPONENT , | |
3193 | [ Entity => ] IDENTIFIER | | |
3194 | SELECTED_COMPONENT | | |
3195 | STRING_LITERAL | |
3196 | [, Source_Location => SOURCE_TRACE ] ); | |
3197 | ||
3198 | SOURCE_TRACE ::= STRING_LITERAL | |
3199 | @end example | |
3200 | ||
3201 | This pragma indicates that the given entity is not used in the program to be | |
3202 | compiled and built, thus allowing the compiler to | |
3203 | eliminate the code or data associated with the named entity. Any reference to | |
3204 | an eliminated entity causes a compile-time or link-time error. | |
3205 | ||
3206 | The pragma has the following semantics, where @code{U} is the unit specified by | |
3207 | the @code{Unit_Name} argument and @code{E} is the entity specified by the @code{Entity} | |
3208 | argument: | |
3209 | ||
3210 | ||
3211 | @itemize * | |
3212 | ||
3213 | @item | |
3214 | @code{E} must be a subprogram that is explicitly declared either: | |
3215 | ||
3216 | ||
3217 | @itemize * | |
3218 | ||
3219 | @item | |
3220 | Within @code{U}, or | |
3221 | ||
3222 | @item | |
3223 | Within a generic package that is instantiated in @code{U}, or | |
3224 | ||
3225 | @item | |
3226 | As an instance of generic subprogram instantiated in @code{U}. | |
3227 | @end itemize | |
3228 | ||
3229 | Otherwise the pragma is ignored. | |
3230 | ||
3231 | @item | |
3232 | If @code{E} is overloaded within @code{U} then, in the absence of a | |
3233 | @code{Source_Location} argument, all overloadings are eliminated. | |
3234 | ||
3235 | @item | |
3236 | If @code{E} is overloaded within @code{U} and only some overloadings | |
3237 | are to be eliminated, then each overloading to be eliminated | |
3238 | must be specified in a corresponding pragma @code{Eliminate} | |
3239 | with a @code{Source_Location} argument identifying the line where the | |
3240 | declaration appears, as described below. | |
3241 | ||
3242 | @item | |
3243 | If @code{E} is declared as the result of a generic instantiation, then | |
3244 | a @code{Source_Location} argument is needed, as described below. | |
3245 | @end itemize | |
3246 | ||
3247 | Pragma @code{Eliminate} allows a program to be compiled in a system-independent | |
3248 | manner, so that unused entities are eliminated but without | |
3249 | needing to modify the source text. Normally the required set of | |
3250 | @code{Eliminate} pragmas is constructed automatically using the @code{gnatelim} tool. | |
3251 | ||
3252 | Any source file change that removes, splits, or | |
3253 | adds lines may make the set of @code{Eliminate} pragmas invalid because their | |
3254 | @code{Source_Location} argument values may get out of date. | |
3255 | ||
3256 | Pragma @code{Eliminate} may be used where the referenced entity is a dispatching | |
3257 | operation. In this case all the subprograms to which the given operation can | |
3258 | dispatch are considered to be unused (are never called as a result of a direct | |
3259 | or a dispatching call). | |
3260 | ||
3261 | The string literal given for the source location specifies the line number | |
3262 | of the declaration of the entity, using the following syntax for @code{SOURCE_TRACE}: | |
3263 | ||
3264 | @example | |
3265 | SOURCE_TRACE ::= SOURCE_REFERENCE [ LBRACKET SOURCE_TRACE RBRACKET ] | |
3266 | ||
3267 | LBRACKET ::= '[' | |
3268 | RBRACKET ::= ']' | |
3269 | ||
3270 | SOURCE_REFERENCE ::= FILE_NAME : LINE_NUMBER | |
3271 | ||
3272 | LINE_NUMBER ::= DIGIT @{DIGIT@} | |
3273 | @end example | |
3274 | ||
3275 | Spaces around the colon in a @code{SOURCE_REFERENCE} are optional. | |
3276 | ||
3277 | The source trace that is given as the @code{Source_Location} must obey the | |
3278 | following rules (or else the pragma is ignored), where @code{U} is | |
3279 | the unit @code{U} specified by the @code{Unit_Name} argument and @code{E} is the | |
3280 | subprogram specified by the @code{Entity} argument: | |
3281 | ||
3282 | ||
3283 | @itemize * | |
3284 | ||
3285 | @item | |
3286 | @code{FILE_NAME} is the short name (with no directory | |
3287 | information) of the Ada source file for @code{U}, using the required syntax | |
3288 | for the underlying file system (e.g. case is significant if the underlying | |
3289 | operating system is case sensitive). | |
3290 | If @code{U} is a package and @code{E} is a subprogram declared in the package | |
3291 | specification and its full declaration appears in the package body, | |
3292 | then the relevant source file is the one for the package specification; | |
3293 | analogously if @code{U} is a generic package. | |
3294 | ||
3295 | @item | |
3296 | If @code{E} is not declared in a generic instantiation (this includes | |
3297 | generic subprogram instances), the source trace includes only one source | |
3298 | line reference. @code{LINE_NUMBER} gives the line number of the occurrence | |
3299 | of the declaration of @code{E} within the source file (as a decimal literal | |
3300 | without an exponent or point). | |
3301 | ||
3302 | @item | |
3303 | If @code{E} is declared by a generic instantiation, its source trace | |
3304 | (from left to right) starts with the source location of the | |
3305 | declaration of @code{E} in the generic unit and ends with the source | |
3306 | location of the instantiation, given in square brackets. This approach is | |
3307 | applied recursively with nested instantiations: the rightmost (nested | |
3308 | most deeply in square brackets) element of the source trace is the location | |
3309 | of the outermost instantiation, and the leftmost element (that is, outside | |
3310 | of any square brackets) is the location of the declaration of @code{E} in | |
3311 | the generic unit. | |
3312 | @end itemize | |
3313 | ||
3314 | Examples: | |
3315 | ||
3316 | @quotation | |
3317 | ||
3318 | @example | |
3319 | pragma Eliminate (Pkg0, Proc); | |
3320 | -- Eliminate (all overloadings of) Proc in Pkg0 | |
3321 | ||
3322 | pragma Eliminate (Pkg1, Proc, | |
3323 | Source_Location => "pkg1.ads:8"); | |
3324 | -- Eliminate overloading of Proc at line 8 in pkg1.ads | |
3325 | ||
3326 | -- Assume the following file contents: | |
3327 | -- gen_pkg.ads | |
3328 | -- 1: generic | |
3329 | -- 2: type T is private; | |
3330 | -- 3: package Gen_Pkg is | |
3331 | -- 4: procedure Proc(N : T); | |
3332 | -- ... ... | |
3333 | -- ... end Gen_Pkg; | |
3334 | -- | |
3335 | -- q.adb | |
3336 | -- 1: with Gen_Pkg; | |
3337 | -- 2: procedure Q is | |
3338 | -- 3: package Inst_Pkg is new Gen_Pkg(Integer); | |
3339 | -- ... -- No calls on Inst_Pkg.Proc | |
3340 | -- ... end Q; | |
3341 | ||
3342 | -- The following pragma eliminates Inst_Pkg.Proc from Q | |
3343 | pragma Eliminate (Q, Proc, | |
3344 | Source_Location => "gen_pkg.ads:4[q.adb:3]"); | |
3345 | @end example | |
3346 | @end quotation | |
3347 | ||
3348 | @node Pragma Enable_Atomic_Synchronization,Pragma Export_Function,Pragma Eliminate,Implementation Defined Pragmas | |
3349 | @anchor{gnat_rm/implementation_defined_pragmas pragma-enable-atomic-synchronization}@anchor{5e} | |
3350 | @section Pragma Enable_Atomic_Synchronization | |
3351 | ||
3352 | ||
3353 | @geindex Atomic Synchronization | |
3354 | ||
3355 | Syntax: | |
3356 | ||
3357 | @example | |
3358 | pragma Enable_Atomic_Synchronization [(Entity)]; | |
3359 | @end example | |
3360 | ||
3361 | Ada requires that accesses (reads or writes) of an atomic variable be | |
3362 | regarded as synchronization points in the case of multiple tasks. | |
3363 | Particularly in the case of multi-processors this may require special | |
3364 | handling, e.g. the generation of memory barriers. This synchronization | |
3365 | is performed by default, but can be turned off using | |
3366 | @code{pragma Disable_Atomic_Synchronization}. The | |
3367 | @code{Enable_Atomic_Synchronization} pragma can be used to turn | |
3368 | it back on. | |
3369 | ||
3370 | The placement and scope rules for this pragma are the same as those | |
3371 | for @code{pragma Unsuppress}. In particular it can be used as a | |
3372 | configuration pragma, or in a declaration sequence where it applies | |
3373 | till the end of the scope. If an @code{Entity} argument is present, | |
3374 | the action applies only to that entity. | |
3375 | ||
3376 | @node Pragma Export_Function,Pragma Export_Object,Pragma Enable_Atomic_Synchronization,Implementation Defined Pragmas | |
3377 | @anchor{gnat_rm/implementation_defined_pragmas pragma-export-function}@anchor{5f} | |
3378 | @section Pragma Export_Function | |
3379 | ||
3380 | ||
3381 | @geindex Argument passing mechanisms | |
3382 | ||
3383 | Syntax: | |
3384 | ||
3385 | @example | |
3386 | pragma Export_Function ( | |
3387 | [Internal =>] LOCAL_NAME | |
3388 | [, [External =>] EXTERNAL_SYMBOL] | |
3389 | [, [Parameter_Types =>] PARAMETER_TYPES] | |
3390 | [, [Result_Type =>] result_SUBTYPE_MARK] | |
3391 | [, [Mechanism =>] MECHANISM] | |
3392 | [, [Result_Mechanism =>] MECHANISM_NAME]); | |
3393 | ||
3394 | EXTERNAL_SYMBOL ::= | |
3395 | IDENTIFIER | |
3396 | | static_string_EXPRESSION | |
3397 | | "" | |
3398 | ||
3399 | PARAMETER_TYPES ::= | |
3400 | null | |
3401 | | TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} | |
3402 | ||
3403 | TYPE_DESIGNATOR ::= | |
3404 | subtype_NAME | |
3405 | | subtype_Name ' Access | |
3406 | ||
3407 | MECHANISM ::= | |
3408 | MECHANISM_NAME | |
3409 | | (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) | |
3410 | ||
3411 | MECHANISM_ASSOCIATION ::= | |
3412 | [formal_parameter_NAME =>] MECHANISM_NAME | |
3413 | ||
3414 | MECHANISM_NAME ::= Value | Reference | |
3415 | @end example | |
3416 | ||
3417 | Use this pragma to make a function externally callable and optionally | |
3418 | provide information on mechanisms to be used for passing parameter and | |
3419 | result values. We recommend, for the purposes of improving portability, | |
3420 | this pragma always be used in conjunction with a separate pragma | |
3421 | @code{Export}, which must precede the pragma @code{Export_Function}. | |
3422 | GNAT does not require a separate pragma @code{Export}, but if none is | |
3423 | present, @code{Convention Ada} is assumed, which is usually | |
3424 | not what is wanted, so it is usually appropriate to use this | |
3425 | pragma in conjunction with a @code{Export} or @code{Convention} | |
3426 | pragma that specifies the desired foreign convention. | |
3427 | Pragma @code{Export_Function} | |
3428 | (and @code{Export}, if present) must appear in the same declarative | |
3429 | region as the function to which they apply. | |
3430 | ||
3431 | The @code{internal_name} must uniquely designate the function to which the | |
3432 | pragma applies. If more than one function name exists of this name in | |
3433 | the declarative part you must use the @code{Parameter_Types} and | |
3434 | @code{Result_Type} parameters to achieve the required | |
3435 | unique designation. The @cite{subtype_mark}s in these parameters must | |
3436 | exactly match the subtypes in the corresponding function specification, | |
3437 | using positional notation to match parameters with subtype marks. | |
3438 | The form with an @code{'Access} attribute can be used to match an | |
3439 | anonymous access parameter. | |
3440 | ||
3441 | @geindex Suppressing external name | |
3442 | ||
3443 | Special treatment is given if the EXTERNAL is an explicit null | |
3444 | string or a static string expressions that evaluates to the null | |
3445 | string. In this case, no external name is generated. This form | |
3446 | still allows the specification of parameter mechanisms. | |
3447 | ||
3448 | @node Pragma Export_Object,Pragma Export_Procedure,Pragma Export_Function,Implementation Defined Pragmas | |
3449 | @anchor{gnat_rm/implementation_defined_pragmas pragma-export-object}@anchor{60} | |
3450 | @section Pragma Export_Object | |
3451 | ||
3452 | ||
3453 | Syntax: | |
3454 | ||
3455 | @example | |
3456 | pragma Export_Object ( | |
3457 | [Internal =>] LOCAL_NAME | |
3458 | [, [External =>] EXTERNAL_SYMBOL] | |
3459 | [, [Size =>] EXTERNAL_SYMBOL]); | |
3460 | ||
3461 | EXTERNAL_SYMBOL ::= | |
3462 | IDENTIFIER | |
3463 | | static_string_EXPRESSION | |
3464 | @end example | |
3465 | ||
3466 | This pragma designates an object as exported, and apart from the | |
3467 | extended rules for external symbols, is identical in effect to the use of | |
3468 | the normal @code{Export} pragma applied to an object. You may use a | |
3469 | separate Export pragma (and you probably should from the point of view | |
3470 | of portability), but it is not required. @code{Size} is syntax checked, | |
3471 | but otherwise ignored by GNAT. | |
3472 | ||
3473 | @node Pragma Export_Procedure,Pragma Export_Valued_Procedure,Pragma Export_Object,Implementation Defined Pragmas | |
3474 | @anchor{gnat_rm/implementation_defined_pragmas pragma-export-procedure}@anchor{61} | |
3475 | @section Pragma Export_Procedure | |
3476 | ||
3477 | ||
3478 | Syntax: | |
3479 | ||
3480 | @example | |
3481 | pragma Export_Procedure ( | |
3482 | [Internal =>] LOCAL_NAME | |
3483 | [, [External =>] EXTERNAL_SYMBOL] | |
3484 | [, [Parameter_Types =>] PARAMETER_TYPES] | |
3485 | [, [Mechanism =>] MECHANISM]); | |
3486 | ||
3487 | EXTERNAL_SYMBOL ::= | |
3488 | IDENTIFIER | |
3489 | | static_string_EXPRESSION | |
3490 | | "" | |
3491 | ||
3492 | PARAMETER_TYPES ::= | |
3493 | null | |
3494 | | TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} | |
3495 | ||
3496 | TYPE_DESIGNATOR ::= | |
3497 | subtype_NAME | |
3498 | | subtype_Name ' Access | |
3499 | ||
3500 | MECHANISM ::= | |
3501 | MECHANISM_NAME | |
3502 | | (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) | |
3503 | ||
3504 | MECHANISM_ASSOCIATION ::= | |
3505 | [formal_parameter_NAME =>] MECHANISM_NAME | |
3506 | ||
3507 | MECHANISM_NAME ::= Value | Reference | |
3508 | @end example | |
3509 | ||
3510 | This pragma is identical to @code{Export_Function} except that it | |
3511 | applies to a procedure rather than a function and the parameters | |
3512 | @code{Result_Type} and @code{Result_Mechanism} are not permitted. | |
3513 | GNAT does not require a separate pragma @code{Export}, but if none is | |
3514 | present, @code{Convention Ada} is assumed, which is usually | |
3515 | not what is wanted, so it is usually appropriate to use this | |
3516 | pragma in conjunction with a @code{Export} or @code{Convention} | |
3517 | pragma that specifies the desired foreign convention. | |
3518 | ||
3519 | @geindex Suppressing external name | |
3520 | ||
3521 | Special treatment is given if the EXTERNAL is an explicit null | |
3522 | string or a static string expressions that evaluates to the null | |
3523 | string. In this case, no external name is generated. This form | |
3524 | still allows the specification of parameter mechanisms. | |
3525 | ||
3526 | @node Pragma Export_Valued_Procedure,Pragma Extend_System,Pragma Export_Procedure,Implementation Defined Pragmas | |
3527 | @anchor{gnat_rm/implementation_defined_pragmas pragma-export-valued-procedure}@anchor{62} | |
3528 | @section Pragma Export_Valued_Procedure | |
3529 | ||
3530 | ||
3531 | Syntax: | |
3532 | ||
3533 | @example | |
3534 | pragma Export_Valued_Procedure ( | |
3535 | [Internal =>] LOCAL_NAME | |
3536 | [, [External =>] EXTERNAL_SYMBOL] | |
3537 | [, [Parameter_Types =>] PARAMETER_TYPES] | |
3538 | [, [Mechanism =>] MECHANISM]); | |
3539 | ||
3540 | EXTERNAL_SYMBOL ::= | |
3541 | IDENTIFIER | |
3542 | | static_string_EXPRESSION | |
3543 | | "" | |
3544 | ||
3545 | PARAMETER_TYPES ::= | |
3546 | null | |
3547 | | TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} | |
3548 | ||
3549 | TYPE_DESIGNATOR ::= | |
3550 | subtype_NAME | |
3551 | | subtype_Name ' Access | |
3552 | ||
3553 | MECHANISM ::= | |
3554 | MECHANISM_NAME | |
3555 | | (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) | |
3556 | ||
3557 | MECHANISM_ASSOCIATION ::= | |
3558 | [formal_parameter_NAME =>] MECHANISM_NAME | |
3559 | ||
3560 | MECHANISM_NAME ::= Value | Reference | |
3561 | @end example | |
3562 | ||
3563 | This pragma is identical to @code{Export_Procedure} except that the | |
3564 | first parameter of @code{LOCAL_NAME}, which must be present, must be of | |
3565 | mode @code{out}, and externally the subprogram is treated as a function | |
3566 | with this parameter as the result of the function. GNAT provides for | |
3567 | this capability to allow the use of @code{out} and @code{in out} | |
3568 | parameters in interfacing to external functions (which are not permitted | |
3569 | in Ada functions). | |
3570 | GNAT does not require a separate pragma @code{Export}, but if none is | |
3571 | present, @code{Convention Ada} is assumed, which is almost certainly | |
3572 | not what is wanted since the whole point of this pragma is to interface | |
3573 | with foreign language functions, so it is usually appropriate to use this | |
3574 | pragma in conjunction with a @code{Export} or @code{Convention} | |
3575 | pragma that specifies the desired foreign convention. | |
3576 | ||
3577 | @geindex Suppressing external name | |
3578 | ||
3579 | Special treatment is given if the EXTERNAL is an explicit null | |
3580 | string or a static string expressions that evaluates to the null | |
3581 | string. In this case, no external name is generated. This form | |
3582 | still allows the specification of parameter mechanisms. | |
3583 | ||
3584 | @node Pragma Extend_System,Pragma Extensions_Allowed,Pragma Export_Valued_Procedure,Implementation Defined Pragmas | |
3585 | @anchor{gnat_rm/implementation_defined_pragmas pragma-extend-system}@anchor{63} | |
3586 | @section Pragma Extend_System | |
3587 | ||
3588 | ||
3589 | @geindex System | |
3590 | @geindex extending | |
3591 | ||
3592 | @geindex DEC Ada 83 | |
3593 | ||
3594 | Syntax: | |
3595 | ||
3596 | @example | |
3597 | pragma Extend_System ([Name =>] IDENTIFIER); | |
3598 | @end example | |
3599 | ||
3600 | This pragma is used to provide backwards compatibility with other | |
3601 | implementations that extend the facilities of package @code{System}. In | |
3602 | GNAT, @code{System} contains only the definitions that are present in | |
3603 | the Ada RM. However, other implementations, notably the DEC Ada 83 | |
3604 | implementation, provide many extensions to package @code{System}. | |
3605 | ||
3606 | For each such implementation accommodated by this pragma, GNAT provides a | |
1acce141 | 3607 | package @code{Aux_@emph{xxx}}, e.g., @code{Aux_DEC} for the DEC Ada 83 |
64d5610f ML |
3608 | implementation, which provides the required additional definitions. You |
3609 | can use this package in two ways. You can @code{with} it in the normal | |
3610 | way and access entities either by selection or using a @code{use} | |
3611 | clause. In this case no special processing is required. | |
3612 | ||
3613 | However, if existing code contains references such as | |
1acce141 | 3614 | @code{System.@emph{xxx}} where @emph{xxx} is an entity in the extended |
64d5610f ML |
3615 | definitions provided in package @code{System}, you may use this pragma |
3616 | to extend visibility in @code{System} in a non-standard way that | |
3617 | provides greater compatibility with the existing code. Pragma | |
3618 | @code{Extend_System} is a configuration pragma whose single argument is | |
3619 | the name of the package containing the extended definition | |
3620 | (e.g., @code{Aux_DEC} for the DEC Ada case). A unit compiled under | |
3621 | control of this pragma will be processed using special visibility | |
1acce141 YM |
3622 | processing that looks in package @code{System.Aux_@emph{xxx}} where |
3623 | @code{Aux_@emph{xxx}} is the pragma argument for any entity referenced in | |
64d5610f ML |
3624 | package @code{System}, but not found in package @code{System}. |
3625 | ||
3626 | You can use this pragma either to access a predefined @code{System} | |
3627 | extension supplied with the compiler, for example @code{Aux_DEC} or | |
3628 | you can construct your own extension unit following the above | |
3629 | definition. Note that such a package is a child of @code{System} | |
3630 | and thus is considered part of the implementation. | |
1acce141 | 3631 | To compile it you will have to use the @emph{-gnatg} switch |
64d5610f ML |
3632 | for compiling System units, as explained in the |
3633 | GNAT User’s Guide. | |
3634 | ||
3635 | @node Pragma Extensions_Allowed,Pragma Extensions_Visible,Pragma Extend_System,Implementation Defined Pragmas | |
b71d4b62 | 3636 | @anchor{gnat_rm/implementation_defined_pragmas id12}@anchor{64}@anchor{gnat_rm/implementation_defined_pragmas pragma-extensions-allowed}@anchor{65} |
64d5610f ML |
3637 | @section Pragma Extensions_Allowed |
3638 | ||
3639 | ||
3640 | @geindex Ada Extensions | |
3641 | ||
3642 | @geindex GNAT Extensions | |
3643 | ||
3644 | Syntax: | |
3645 | ||
3646 | @example | |
3647 | pragma Extensions_Allowed (On | Off | All); | |
3648 | @end example | |
3649 | ||
3650 | This configuration pragma enables (via the “On” or “All” argument) or disables | |
3651 | (via the “Off” argument) the implementation extension mode; the pragma takes | |
b71d4b62 | 3652 | precedence over the @code{-gnatX} and @code{-gnatX0} command switches. |
64d5610f | 3653 | |
b71d4b62 RA |
3654 | If an argument of @code{"On"} is specified, the latest version of the Ada language |
3655 | is implemented (currently Ada 2022) and, in addition, a curated set of GNAT | |
3656 | specific extensions are recognized. (See the list here | |
3657 | @ref{66,,here}) | |
64d5610f | 3658 | |
b71d4b62 RA |
3659 | An argument of @code{"All"} has the same effect except that some extra |
3660 | experimental extensions are enabled (See the list here | |
3661 | @ref{67,,here}) | |
64d5610f | 3662 | |
b71d4b62 RA |
3663 | @node Pragma Extensions_Visible,Pragma External,Pragma Extensions_Allowed,Implementation Defined Pragmas |
3664 | @anchor{gnat_rm/implementation_defined_pragmas id13}@anchor{68}@anchor{gnat_rm/implementation_defined_pragmas pragma-extensions-visible}@anchor{69} | |
3665 | @section Pragma Extensions_Visible | |
64d5610f | 3666 | |
64d5610f | 3667 | |
b71d4b62 | 3668 | Syntax: |
64d5610f | 3669 | |
b71d4b62 RA |
3670 | @example |
3671 | pragma Extensions_Visible [ (static_boolean_EXPRESSION) ]; | |
3672 | @end example | |
64d5610f | 3673 | |
b71d4b62 RA |
3674 | For the semantics of this pragma, see the entry for aspect @code{Extensions_Visible} |
3675 | in the SPARK 2014 Reference Manual, section 6.1.7. | |
64d5610f | 3676 | |
b71d4b62 RA |
3677 | @node Pragma External,Pragma External_Name_Casing,Pragma Extensions_Visible,Implementation Defined Pragmas |
3678 | @anchor{gnat_rm/implementation_defined_pragmas pragma-external}@anchor{6a} | |
3679 | @section Pragma External | |
64d5610f | 3680 | |
64d5610f | 3681 | |
b71d4b62 | 3682 | Syntax: |
64d5610f ML |
3683 | |
3684 | @example | |
b71d4b62 RA |
3685 | pragma External ( |
3686 | [ Convention =>] convention_IDENTIFIER, | |
3687 | [ Entity =>] LOCAL_NAME | |
3688 | [, [External_Name =>] static_string_EXPRESSION ] | |
3689 | [, [Link_Name =>] static_string_EXPRESSION ]); | |
64d5610f ML |
3690 | @end example |
3691 | ||
b71d4b62 RA |
3692 | This pragma is identical in syntax and semantics to pragma |
3693 | @code{Export} as defined in the Ada Reference Manual. It is | |
3694 | provided for compatibility with some Ada 83 compilers that | |
3695 | used this pragma for exactly the same purposes as pragma | |
3696 | @code{Export} before the latter was standardized. | |
64d5610f | 3697 | |
b71d4b62 RA |
3698 | @node Pragma External_Name_Casing,Pragma Fast_Math,Pragma External,Implementation Defined Pragmas |
3699 | @anchor{gnat_rm/implementation_defined_pragmas pragma-external-name-casing}@anchor{6b} | |
3700 | @section Pragma External_Name_Casing | |
64d5610f | 3701 | |
64d5610f | 3702 | |
b71d4b62 | 3703 | @geindex Dec Ada 83 casing compatibility |
64d5610f | 3704 | |
b71d4b62 RA |
3705 | @geindex External Names |
3706 | @geindex casing | |
64d5610f | 3707 | |
b71d4b62 | 3708 | @geindex Casing of External names |
64d5610f | 3709 | |
b71d4b62 | 3710 | Syntax: |
64d5610f | 3711 | |
b71d4b62 RA |
3712 | @example |
3713 | pragma External_Name_Casing ( | |
3714 | Uppercase | Lowercase | |
3715 | [, Uppercase | Lowercase | As_Is]); | |
3716 | @end example | |
64d5610f | 3717 | |
b71d4b62 RA |
3718 | This pragma provides control over the casing of external names associated |
3719 | with Import and Export pragmas. There are two cases to consider: | |
64d5610f | 3720 | |
64d5610f | 3721 | |
b71d4b62 | 3722 | @itemize * |
64d5610f ML |
3723 | |
3724 | @item | |
b71d4b62 | 3725 | Implicit external names |
64d5610f | 3726 | |
b71d4b62 RA |
3727 | Implicit external names are derived from identifiers. The most common case |
3728 | arises when a standard Ada Import or Export pragma is used with only two | |
3729 | arguments, as in: | |
64d5610f ML |
3730 | |
3731 | @example | |
b71d4b62 | 3732 | pragma Import (C, C_Routine); |
64d5610f ML |
3733 | @end example |
3734 | ||
b71d4b62 RA |
3735 | Since Ada is a case-insensitive language, the spelling of the identifier in |
3736 | the Ada source program does not provide any information on the desired | |
3737 | casing of the external name, and so a convention is needed. In GNAT the | |
3738 | default treatment is that such names are converted to all lower case | |
3739 | letters. This corresponds to the normal C style in many environments. | |
3740 | The first argument of pragma @code{External_Name_Casing} can be used to | |
3741 | control this treatment. If @code{Uppercase} is specified, then the name | |
3742 | will be forced to all uppercase letters. If @code{Lowercase} is specified, | |
3743 | then the normal default of all lower case letters will be used. | |
64d5610f | 3744 | |
b71d4b62 RA |
3745 | This same implicit treatment is also used in the case of extended DEC Ada 83 |
3746 | compatible Import and Export pragmas where an external name is explicitly | |
3747 | specified using an identifier rather than a string. | |
64d5610f ML |
3748 | |
3749 | @item | |
b71d4b62 | 3750 | Explicit external names |
64d5610f | 3751 | |
b71d4b62 RA |
3752 | Explicit external names are given as string literals. The most common case |
3753 | arises when a standard Ada Import or Export pragma is used with three | |
3754 | arguments, as in: | |
64d5610f ML |
3755 | |
3756 | @example | |
b71d4b62 | 3757 | pragma Import (C, C_Routine, "C_routine"); |
64d5610f ML |
3758 | @end example |
3759 | ||
b71d4b62 RA |
3760 | In this case, the string literal normally provides the exact casing required |
3761 | for the external name. The second argument of pragma | |
3762 | @code{External_Name_Casing} may be used to modify this behavior. | |
3763 | If @code{Uppercase} is specified, then the name | |
3764 | will be forced to all uppercase letters. If @code{Lowercase} is specified, | |
3765 | then the name will be forced to all lowercase letters. A specification of | |
3766 | @code{As_Is} provides the normal default behavior in which the casing is | |
3767 | taken from the string provided. | |
3768 | @end itemize | |
64d5610f | 3769 | |
b71d4b62 RA |
3770 | This pragma may appear anywhere that a pragma is valid. In particular, it |
3771 | can be used as a configuration pragma in the @code{gnat.adc} file, in which | |
3772 | case it applies to all subsequent compilations, or it can be used as a program | |
3773 | unit pragma, in which case it only applies to the current unit, or it can | |
3774 | be used more locally to control individual Import/Export pragmas. | |
64d5610f | 3775 | |
b71d4b62 RA |
3776 | It was primarily intended for use with OpenVMS systems, where many |
3777 | compilers convert all symbols to upper case by default. For interfacing to | |
3778 | such compilers (e.g., the DEC C compiler), it may be convenient to use | |
3779 | the pragma: | |
64d5610f ML |
3780 | |
3781 | @example | |
b71d4b62 | 3782 | pragma External_Name_Casing (Uppercase, Uppercase); |
64d5610f | 3783 | @end example |
64d5610f | 3784 | |
b71d4b62 | 3785 | to enforce the upper casing of all external symbols. |
64d5610f | 3786 | |
b71d4b62 RA |
3787 | @node Pragma Fast_Math,Pragma Favor_Top_Level,Pragma External_Name_Casing,Implementation Defined Pragmas |
3788 | @anchor{gnat_rm/implementation_defined_pragmas pragma-fast-math}@anchor{6c} | |
3789 | @section Pragma Fast_Math | |
64d5610f | 3790 | |
64d5610f | 3791 | |
b71d4b62 | 3792 | Syntax: |
64d5610f | 3793 | |
b71d4b62 RA |
3794 | @example |
3795 | pragma Fast_Math; | |
3796 | @end example | |
64d5610f | 3797 | |
b71d4b62 RA |
3798 | This is a configuration pragma which activates a mode in which speed is |
3799 | considered more important for floating-point operations than absolutely | |
3800 | accurate adherence to the requirements of the standard. Currently the | |
3801 | following operations are affected: | |
64d5610f | 3802 | |
64d5610f | 3803 | |
b71d4b62 | 3804 | @table @asis |
64d5610f | 3805 | |
1acce141 | 3806 | @item @emph{Complex Multiplication} |
64d5610f | 3807 | |
b71d4b62 RA |
3808 | The normal simple formula for complex multiplication can result in intermediate |
3809 | overflows for numbers near the end of the range. The Ada standard requires that | |
3810 | this situation be detected and corrected by scaling, but in Fast_Math mode such | |
3811 | cases will simply result in overflow. Note that to take advantage of this you | |
3812 | must instantiate your own version of @code{Ada.Numerics.Generic_Complex_Types} | |
3813 | under control of the pragma, rather than use the preinstantiated versions. | |
3814 | @end table | |
64d5610f | 3815 | |
b71d4b62 RA |
3816 | @node Pragma Favor_Top_Level,Pragma Finalize_Storage_Only,Pragma Fast_Math,Implementation Defined Pragmas |
3817 | @anchor{gnat_rm/implementation_defined_pragmas id14}@anchor{6d}@anchor{gnat_rm/implementation_defined_pragmas pragma-favor-top-level}@anchor{6e} | |
3818 | @section Pragma Favor_Top_Level | |
64d5610f | 3819 | |
64d5610f | 3820 | |
b71d4b62 | 3821 | Syntax: |
64d5610f | 3822 | |
b71d4b62 RA |
3823 | @example |
3824 | pragma Favor_Top_Level (type_NAME); | |
64d5610f | 3825 | @end example |
b7d26cb1 | 3826 | |
b71d4b62 RA |
3827 | The argument of pragma @code{Favor_Top_Level} must be a named access-to-subprogram |
3828 | type. This pragma is an efficiency hint to the compiler, regarding the use of | |
3829 | @code{'Access} or @code{'Unrestricted_Access} on nested (non-library-level) subprograms. | |
3830 | The pragma means that nested subprograms are not used with this type, or are | |
3831 | rare, so that the generated code should be efficient in the top-level case. | |
3832 | When this pragma is used, dynamically generated trampolines may be used on some | |
3833 | targets for nested subprograms. See restriction @code{No_Implicit_Dynamic_Code}. | |
b7d26cb1 | 3834 | |
b71d4b62 RA |
3835 | @node Pragma Finalize_Storage_Only,Pragma Float_Representation,Pragma Favor_Top_Level,Implementation Defined Pragmas |
3836 | @anchor{gnat_rm/implementation_defined_pragmas pragma-finalize-storage-only}@anchor{6f} | |
3837 | @section Pragma Finalize_Storage_Only | |
b7d26cb1 | 3838 | |
b7d26cb1 | 3839 | |
b71d4b62 | 3840 | Syntax: |
b7d26cb1 JM |
3841 | |
3842 | @example | |
b71d4b62 | 3843 | pragma Finalize_Storage_Only (first_subtype_LOCAL_NAME); |
b7d26cb1 JM |
3844 | @end example |
3845 | ||
b71d4b62 RA |
3846 | The argument of pragma @code{Finalize_Storage_Only} must denote a local type which |
3847 | is derived from @code{Ada.Finalization.Controlled} or @code{Limited_Controlled}. The | |
3848 | pragma suppresses the call to @code{Finalize} for declared library-level objects | |
3849 | of the argument type. This is mostly useful for types where finalization is | |
3850 | only used to deal with storage reclamation since in most environments it is | |
3851 | not necessary to reclaim memory just before terminating execution, hence the | |
3852 | name. Note that this pragma does not suppress Finalize calls for library-level | |
3853 | heap-allocated objects (see pragma @code{No_Heap_Finalization}). | |
b7d26cb1 | 3854 | |
b71d4b62 RA |
3855 | @node Pragma Float_Representation,Pragma Ghost,Pragma Finalize_Storage_Only,Implementation Defined Pragmas |
3856 | @anchor{gnat_rm/implementation_defined_pragmas pragma-float-representation}@anchor{70} | |
3857 | @section Pragma Float_Representation | |
b7d26cb1 | 3858 | |
b7d26cb1 | 3859 | |
b71d4b62 | 3860 | Syntax: |
b7d26cb1 | 3861 | |
b71d4b62 RA |
3862 | @example |
3863 | pragma Float_Representation (FLOAT_REP[, float_type_LOCAL_NAME]); | |
b7d26cb1 | 3864 | |
b71d4b62 RA |
3865 | FLOAT_REP ::= VAX_Float | IEEE_Float |
3866 | @end example | |
b7d26cb1 | 3867 | |
b71d4b62 RA |
3868 | In the one argument form, this pragma is a configuration pragma which |
3869 | allows control over the internal representation chosen for the predefined | |
3870 | floating point types declared in the packages @code{Standard} and | |
3871 | @code{System}. This pragma is only provided for compatibility and has no effect. | |
b7d26cb1 | 3872 | |
b71d4b62 RA |
3873 | The two argument form specifies the representation to be used for |
3874 | the specified floating-point type. The argument must | |
3875 | be @code{IEEE_Float} to specify the use of IEEE format, as follows: | |
b7d26cb1 | 3876 | |
b7d26cb1 | 3877 | |
b71d4b62 | 3878 | @itemize * |
b7d26cb1 | 3879 | |
b71d4b62 RA |
3880 | @item |
3881 | For a digits value of 6, 32-bit IEEE short format will be used. | |
b7d26cb1 | 3882 | |
b71d4b62 RA |
3883 | @item |
3884 | For a digits value of 15, 64-bit IEEE long format will be used. | |
b7d26cb1 | 3885 | |
b71d4b62 RA |
3886 | @item |
3887 | No other value of digits is permitted. | |
3888 | @end itemize | |
b7d26cb1 | 3889 | |
b71d4b62 RA |
3890 | @node Pragma Ghost,Pragma Global,Pragma Float_Representation,Implementation Defined Pragmas |
3891 | @anchor{gnat_rm/implementation_defined_pragmas id15}@anchor{71}@anchor{gnat_rm/implementation_defined_pragmas pragma-ghost}@anchor{72} | |
3892 | @section Pragma Ghost | |
b7d26cb1 | 3893 | |
b7d26cb1 | 3894 | |
b71d4b62 | 3895 | Syntax: |
b7d26cb1 | 3896 | |
b71d4b62 RA |
3897 | @example |
3898 | pragma Ghost [ (static_boolean_EXPRESSION) ]; | |
3899 | @end example | |
b7d26cb1 | 3900 | |
b71d4b62 RA |
3901 | For the semantics of this pragma, see the entry for aspect @code{Ghost} in the SPARK |
3902 | 2014 Reference Manual, section 6.9. | |
b7d26cb1 | 3903 | |
b71d4b62 RA |
3904 | @node Pragma Global,Pragma Ident,Pragma Ghost,Implementation Defined Pragmas |
3905 | @anchor{gnat_rm/implementation_defined_pragmas id16}@anchor{73}@anchor{gnat_rm/implementation_defined_pragmas pragma-global}@anchor{74} | |
3906 | @section Pragma Global | |
b7d26cb1 | 3907 | |
b7d26cb1 | 3908 | |
b71d4b62 | 3909 | Syntax: |
b7d26cb1 | 3910 | |
b71d4b62 RA |
3911 | @example |
3912 | pragma Global (GLOBAL_SPECIFICATION); | |
b7d26cb1 | 3913 | |
b71d4b62 RA |
3914 | GLOBAL_SPECIFICATION ::= |
3915 | null | |
3916 | | (GLOBAL_LIST) | |
3917 | | (MODED_GLOBAL_LIST @{, MODED_GLOBAL_LIST@}) | |
b7d26cb1 | 3918 | |
b71d4b62 | 3919 | MODED_GLOBAL_LIST ::= MODE_SELECTOR => GLOBAL_LIST |
b7d26cb1 | 3920 | |
b71d4b62 RA |
3921 | MODE_SELECTOR ::= In_Out | Input | Output | Proof_In |
3922 | GLOBAL_LIST ::= GLOBAL_ITEM | (GLOBAL_ITEM @{, GLOBAL_ITEM@}) | |
3923 | GLOBAL_ITEM ::= NAME | |
3924 | @end example | |
b7d26cb1 | 3925 | |
b71d4b62 RA |
3926 | For the semantics of this pragma, see the entry for aspect @code{Global} in the |
3927 | SPARK 2014 Reference Manual, section 6.1.4. | |
b7d26cb1 | 3928 | |
b71d4b62 RA |
3929 | @node Pragma Ident,Pragma Ignore_Pragma,Pragma Global,Implementation Defined Pragmas |
3930 | @anchor{gnat_rm/implementation_defined_pragmas pragma-ident}@anchor{75} | |
3931 | @section Pragma Ident | |
b7d26cb1 | 3932 | |
b7d26cb1 | 3933 | |
b71d4b62 | 3934 | Syntax: |
b7d26cb1 | 3935 | |
b71d4b62 RA |
3936 | @example |
3937 | pragma Ident (static_string_EXPRESSION); | |
3938 | @end example | |
b7d26cb1 | 3939 | |
b71d4b62 RA |
3940 | This pragma is identical in effect to pragma @code{Comment}. It is provided |
3941 | for compatibility with other Ada compilers providing this pragma. | |
b7d26cb1 | 3942 | |
b71d4b62 RA |
3943 | @node Pragma Ignore_Pragma,Pragma Implementation_Defined,Pragma Ident,Implementation Defined Pragmas |
3944 | @anchor{gnat_rm/implementation_defined_pragmas pragma-ignore-pragma}@anchor{76} | |
3945 | @section Pragma Ignore_Pragma | |
b7d26cb1 | 3946 | |
b7d26cb1 | 3947 | |
b71d4b62 | 3948 | Syntax: |
b7d26cb1 | 3949 | |
b71d4b62 RA |
3950 | @example |
3951 | pragma Ignore_Pragma (pragma_IDENTIFIER); | |
3952 | @end example | |
b7d26cb1 | 3953 | |
b71d4b62 RA |
3954 | This is a configuration pragma |
3955 | that takes a single argument that is a simple identifier. Any subsequent | |
3956 | use of a pragma whose pragma identifier matches this argument will be | |
1acce141 YM |
3957 | silently ignored. Any preceding use of a pragma whose pragma identifier |
3958 | matches this argument will be parsed and then ignored. | |
3959 | This may be useful when legacy code or code intended | |
b71d4b62 RA |
3960 | for compilation with some other compiler contains pragmas that match the |
3961 | name, but not the exact implementation, of a GNAT pragma. The use of this | |
3962 | pragma allows such pragmas to be ignored, which may be useful in CodePeer | |
3963 | mode, or during porting of legacy code. | |
b7d26cb1 | 3964 | |
b71d4b62 RA |
3965 | @node Pragma Implementation_Defined,Pragma Implemented,Pragma Ignore_Pragma,Implementation Defined Pragmas |
3966 | @anchor{gnat_rm/implementation_defined_pragmas pragma-implementation-defined}@anchor{77} | |
3967 | @section Pragma Implementation_Defined | |
b7d26cb1 | 3968 | |
b7d26cb1 | 3969 | |
b71d4b62 | 3970 | Syntax: |
b7d26cb1 | 3971 | |
b71d4b62 RA |
3972 | @example |
3973 | pragma Implementation_Defined (local_NAME); | |
3974 | @end example | |
b7d26cb1 | 3975 | |
b71d4b62 RA |
3976 | This pragma marks a previously declared entity as implementation-defined. |
3977 | For an overloaded entity, applies to the most recent homonym. | |
b7d26cb1 | 3978 | |
b71d4b62 RA |
3979 | @example |
3980 | pragma Implementation_Defined; | |
3981 | @end example | |
b7d26cb1 | 3982 | |
b71d4b62 RA |
3983 | The form with no arguments appears anywhere within a scope, most |
3984 | typically a package spec, and indicates that all entities that are | |
3985 | defined within the package spec are Implementation_Defined. | |
b7d26cb1 | 3986 | |
b71d4b62 RA |
3987 | This pragma is used within the GNAT runtime library to identify |
3988 | implementation-defined entities introduced in language-defined units, | |
3989 | for the purpose of implementing the No_Implementation_Identifiers | |
3990 | restriction. | |
b7d26cb1 | 3991 | |
b71d4b62 RA |
3992 | @node Pragma Implemented,Pragma Implicit_Packing,Pragma Implementation_Defined,Implementation Defined Pragmas |
3993 | @anchor{gnat_rm/implementation_defined_pragmas pragma-implemented}@anchor{78} | |
3994 | @section Pragma Implemented | |
b7d26cb1 | 3995 | |
b7d26cb1 | 3996 | |
b71d4b62 | 3997 | Syntax: |
b7d26cb1 | 3998 | |
b71d4b62 RA |
3999 | @example |
4000 | pragma Implemented (procedure_LOCAL_NAME, implementation_kind); | |
b7d26cb1 | 4001 | |
b71d4b62 RA |
4002 | implementation_kind ::= By_Entry | By_Protected_Procedure | By_Any |
4003 | @end example | |
b7d26cb1 | 4004 | |
b71d4b62 RA |
4005 | This is an Ada 2012 representation pragma which applies to protected, task |
4006 | and synchronized interface primitives. The use of pragma Implemented provides | |
4007 | a way to impose a static requirement on the overriding operation by adhering | |
4008 | to one of the three implementation kinds: entry, protected procedure or any of | |
4009 | the above. This pragma is available in all earlier versions of Ada as an | |
4010 | implementation-defined pragma. | |
b7d26cb1 | 4011 | |
b71d4b62 RA |
4012 | @example |
4013 | type Synch_Iface is synchronized interface; | |
4014 | procedure Prim_Op (Obj : in out Iface) is abstract; | |
4015 | pragma Implemented (Prim_Op, By_Protected_Procedure); | |
b7d26cb1 | 4016 | |
b71d4b62 RA |
4017 | protected type Prot_1 is new Synch_Iface with |
4018 | procedure Prim_Op; -- Legal | |
4019 | end Prot_1; | |
b7d26cb1 | 4020 | |
b71d4b62 RA |
4021 | protected type Prot_2 is new Synch_Iface with |
4022 | entry Prim_Op; -- Illegal | |
4023 | end Prot_2; | |
b7d26cb1 | 4024 | |
b71d4b62 RA |
4025 | task type Task_Typ is new Synch_Iface with |
4026 | entry Prim_Op; -- Illegal | |
4027 | end Task_Typ; | |
4028 | @end example | |
b7d26cb1 | 4029 | |
b71d4b62 RA |
4030 | When applied to the procedure_or_entry_NAME of a requeue statement, pragma |
4031 | Implemented determines the runtime behavior of the requeue. Implementation kind | |
4032 | By_Entry guarantees that the action of requeueing will proceed from an entry to | |
4033 | another entry. Implementation kind By_Protected_Procedure transforms the | |
4034 | requeue into a dispatching call, thus eliminating the chance of blocking. Kind | |
4035 | By_Any shares the behavior of By_Entry and By_Protected_Procedure depending on | |
4036 | the target’s overriding subprogram kind. | |
b7d26cb1 | 4037 | |
b71d4b62 RA |
4038 | @node Pragma Implicit_Packing,Pragma Import_Function,Pragma Implemented,Implementation Defined Pragmas |
4039 | @anchor{gnat_rm/implementation_defined_pragmas pragma-implicit-packing}@anchor{79} | |
4040 | @section Pragma Implicit_Packing | |
b7d26cb1 | 4041 | |
b7d26cb1 | 4042 | |
b71d4b62 | 4043 | @geindex Rational Profile |
b7d26cb1 | 4044 | |
b71d4b62 | 4045 | Syntax: |
b7d26cb1 JM |
4046 | |
4047 | @example | |
b71d4b62 | 4048 | pragma Implicit_Packing; |
b7d26cb1 | 4049 | @end example |
64d5610f | 4050 | |
b71d4b62 RA |
4051 | This is a configuration pragma that requests implicit packing for packed |
4052 | arrays for which a size clause is given but no explicit pragma Pack or | |
4053 | specification of Component_Size is present. It also applies to records | |
4054 | where no record representation clause is present. Consider this example: | |
64d5610f ML |
4055 | |
4056 | @example | |
b71d4b62 RA |
4057 | type R is array (0 .. 7) of Boolean; |
4058 | for R'Size use 8; | |
64d5610f ML |
4059 | @end example |
4060 | ||
b71d4b62 RA |
4061 | In accordance with the recommendation in the RM (RM 13.3(53)), a Size clause |
4062 | does not change the layout of a composite object. So the Size clause in the | |
4063 | above example is normally rejected, since the default layout of the array uses | |
4064 | 8-bit components, and thus the array requires a minimum of 64 bits. | |
64d5610f | 4065 | |
b71d4b62 RA |
4066 | If this declaration is compiled in a region of code covered by an occurrence |
4067 | of the configuration pragma Implicit_Packing, then the Size clause in this | |
4068 | and similar examples will cause implicit packing and thus be accepted. For | |
4069 | this implicit packing to occur, the type in question must be an array of small | |
4070 | components whose size is known at compile time, and the Size clause must | |
4071 | specify the exact size that corresponds to the number of elements in the array | |
4072 | multiplied by the size in bits of the component type (both single and | |
4073 | multi-dimensioned arrays can be controlled with this pragma). | |
64d5610f | 4074 | |
b71d4b62 | 4075 | @geindex Array packing |
64d5610f | 4076 | |
b71d4b62 | 4077 | Similarly, the following example shows the use in the record case |
64d5610f ML |
4078 | |
4079 | @example | |
b71d4b62 RA |
4080 | type r is record |
4081 | a, b, c, d, e, f, g, h : boolean; | |
4082 | chr : character; | |
4083 | end record; | |
4084 | for r'size use 16; | |
64d5610f ML |
4085 | @end example |
4086 | ||
b71d4b62 RA |
4087 | Without a pragma Pack, each Boolean field requires 8 bits, so the |
4088 | minimum size is 72 bits, but with a pragma Pack, 16 bits would be | |
4089 | sufficient. The use of pragma Implicit_Packing allows this record | |
4090 | declaration to compile without an explicit pragma Pack. | |
64d5610f | 4091 | |
b71d4b62 RA |
4092 | @node Pragma Import_Function,Pragma Import_Object,Pragma Implicit_Packing,Implementation Defined Pragmas |
4093 | @anchor{gnat_rm/implementation_defined_pragmas pragma-import-function}@anchor{7a} | |
4094 | @section Pragma Import_Function | |
64d5610f | 4095 | |
64d5610f ML |
4096 | |
4097 | Syntax: | |
4098 | ||
4099 | @example | |
b71d4b62 RA |
4100 | pragma Import_Function ( |
4101 | [Internal =>] LOCAL_NAME, | |
4102 | [, [External =>] EXTERNAL_SYMBOL] | |
4103 | [, [Parameter_Types =>] PARAMETER_TYPES] | |
4104 | [, [Result_Type =>] SUBTYPE_MARK] | |
4105 | [, [Mechanism =>] MECHANISM] | |
4106 | [, [Result_Mechanism =>] MECHANISM_NAME]); | |
64d5610f | 4107 | |
b71d4b62 RA |
4108 | EXTERNAL_SYMBOL ::= |
4109 | IDENTIFIER | |
4110 | | static_string_EXPRESSION | |
64d5610f | 4111 | |
b71d4b62 RA |
4112 | PARAMETER_TYPES ::= |
4113 | null | |
4114 | | TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} | |
64d5610f | 4115 | |
b71d4b62 RA |
4116 | TYPE_DESIGNATOR ::= |
4117 | subtype_NAME | |
4118 | | subtype_Name ' Access | |
64d5610f | 4119 | |
b71d4b62 RA |
4120 | MECHANISM ::= |
4121 | MECHANISM_NAME | |
4122 | | (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) | |
64d5610f | 4123 | |
b71d4b62 RA |
4124 | MECHANISM_ASSOCIATION ::= |
4125 | [formal_parameter_NAME =>] MECHANISM_NAME | |
64d5610f | 4126 | |
b71d4b62 RA |
4127 | MECHANISM_NAME ::= |
4128 | Value | |
4129 | | Reference | |
64d5610f ML |
4130 | @end example |
4131 | ||
b71d4b62 RA |
4132 | This pragma is used in conjunction with a pragma @code{Import} to |
4133 | specify additional information for an imported function. The pragma | |
4134 | @code{Import} (or equivalent pragma @code{Interface}) must precede the | |
4135 | @code{Import_Function} pragma and both must appear in the same | |
4136 | declarative part as the function specification. | |
64d5610f | 4137 | |
b71d4b62 RA |
4138 | The @code{Internal} argument must uniquely designate |
4139 | the function to which the | |
4140 | pragma applies. If more than one function name exists of this name in | |
4141 | the declarative part you must use the @code{Parameter_Types} and | |
4142 | @code{Result_Type} parameters to achieve the required unique | |
4143 | designation. Subtype marks in these parameters must exactly match the | |
4144 | subtypes in the corresponding function specification, using positional | |
4145 | notation to match parameters with subtype marks. | |
4146 | The form with an @code{'Access} attribute can be used to match an | |
4147 | anonymous access parameter. | |
64d5610f | 4148 | |
b71d4b62 RA |
4149 | You may optionally use the @code{Mechanism} and @code{Result_Mechanism} |
4150 | parameters to specify passing mechanisms for the | |
4151 | parameters and result. If you specify a single mechanism name, it | |
4152 | applies to all parameters. Otherwise you may specify a mechanism on a | |
4153 | parameter by parameter basis using either positional or named | |
4154 | notation. If the mechanism is not specified, the default mechanism | |
4155 | is used. | |
64d5610f | 4156 | |
b71d4b62 RA |
4157 | @node Pragma Import_Object,Pragma Import_Procedure,Pragma Import_Function,Implementation Defined Pragmas |
4158 | @anchor{gnat_rm/implementation_defined_pragmas pragma-import-object}@anchor{7b} | |
4159 | @section Pragma Import_Object | |
64d5610f | 4160 | |
64d5610f | 4161 | |
b71d4b62 | 4162 | Syntax: |
64d5610f ML |
4163 | |
4164 | @example | |
b71d4b62 RA |
4165 | pragma Import_Object ( |
4166 | [Internal =>] LOCAL_NAME | |
4167 | [, [External =>] EXTERNAL_SYMBOL] | |
4168 | [, [Size =>] EXTERNAL_SYMBOL]); | |
4169 | ||
4170 | EXTERNAL_SYMBOL ::= | |
4171 | IDENTIFIER | |
4172 | | static_string_EXPRESSION | |
64d5610f ML |
4173 | @end example |
4174 | ||
b71d4b62 RA |
4175 | This pragma designates an object as imported, and apart from the |
4176 | extended rules for external symbols, is identical in effect to the use of | |
4177 | the normal @code{Import} pragma applied to an object. Unlike the | |
4178 | subprogram case, you need not use a separate @code{Import} pragma, | |
4179 | although you may do so (and probably should do so from a portability | |
4180 | point of view). @code{size} is syntax checked, but otherwise ignored by | |
4181 | GNAT. | |
64d5610f | 4182 | |
b71d4b62 RA |
4183 | @node Pragma Import_Procedure,Pragma Import_Valued_Procedure,Pragma Import_Object,Implementation Defined Pragmas |
4184 | @anchor{gnat_rm/implementation_defined_pragmas pragma-import-procedure}@anchor{7c} | |
4185 | @section Pragma Import_Procedure | |
64d5610f ML |
4186 | |
4187 | ||
4188 | Syntax: | |
4189 | ||
4190 | @example | |
b71d4b62 RA |
4191 | pragma Import_Procedure ( |
4192 | [Internal =>] LOCAL_NAME | |
4193 | [, [External =>] EXTERNAL_SYMBOL] | |
4194 | [, [Parameter_Types =>] PARAMETER_TYPES] | |
4195 | [, [Mechanism =>] MECHANISM]); | |
64d5610f | 4196 | |
b71d4b62 RA |
4197 | EXTERNAL_SYMBOL ::= |
4198 | IDENTIFIER | |
4199 | | static_string_EXPRESSION | |
64d5610f | 4200 | |
b71d4b62 RA |
4201 | PARAMETER_TYPES ::= |
4202 | null | |
4203 | | TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} | |
64d5610f | 4204 | |
b71d4b62 RA |
4205 | TYPE_DESIGNATOR ::= |
4206 | subtype_NAME | |
4207 | | subtype_Name ' Access | |
64d5610f | 4208 | |
b71d4b62 RA |
4209 | MECHANISM ::= |
4210 | MECHANISM_NAME | |
4211 | | (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) | |
64d5610f | 4212 | |
b71d4b62 RA |
4213 | MECHANISM_ASSOCIATION ::= |
4214 | [formal_parameter_NAME =>] MECHANISM_NAME | |
64d5610f | 4215 | |
b71d4b62 RA |
4216 | MECHANISM_NAME ::= Value | Reference |
4217 | @end example | |
4218 | ||
4219 | This pragma is identical to @code{Import_Function} except that it | |
4220 | applies to a procedure rather than a function and the parameters | |
4221 | @code{Result_Type} and @code{Result_Mechanism} are not permitted. | |
4222 | ||
4223 | @node Pragma Import_Valued_Procedure,Pragma Independent,Pragma Import_Procedure,Implementation Defined Pragmas | |
4224 | @anchor{gnat_rm/implementation_defined_pragmas pragma-import-valued-procedure}@anchor{7d} | |
4225 | @section Pragma Import_Valued_Procedure | |
64d5610f ML |
4226 | |
4227 | ||
4228 | Syntax: | |
4229 | ||
4230 | @example | |
b71d4b62 RA |
4231 | pragma Import_Valued_Procedure ( |
4232 | [Internal =>] LOCAL_NAME | |
4233 | [, [External =>] EXTERNAL_SYMBOL] | |
4234 | [, [Parameter_Types =>] PARAMETER_TYPES] | |
4235 | [, [Mechanism =>] MECHANISM]); | |
64d5610f | 4236 | |
b71d4b62 RA |
4237 | EXTERNAL_SYMBOL ::= |
4238 | IDENTIFIER | |
4239 | | static_string_EXPRESSION | |
64d5610f | 4240 | |
b71d4b62 RA |
4241 | PARAMETER_TYPES ::= |
4242 | null | |
4243 | | TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} | |
64d5610f | 4244 | |
b71d4b62 RA |
4245 | TYPE_DESIGNATOR ::= |
4246 | subtype_NAME | |
4247 | | subtype_Name ' Access | |
64d5610f | 4248 | |
b71d4b62 RA |
4249 | MECHANISM ::= |
4250 | MECHANISM_NAME | |
4251 | | (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) | |
64d5610f | 4252 | |
b71d4b62 RA |
4253 | MECHANISM_ASSOCIATION ::= |
4254 | [formal_parameter_NAME =>] MECHANISM_NAME | |
4255 | ||
4256 | MECHANISM_NAME ::= Value | Reference | |
64d5610f ML |
4257 | @end example |
4258 | ||
b71d4b62 RA |
4259 | This pragma is identical to @code{Import_Procedure} except that the |
4260 | first parameter of @code{LOCAL_NAME}, which must be present, must be of | |
4261 | mode @code{out}, and externally the subprogram is treated as a function | |
4262 | with this parameter as the result of the function. The purpose of this | |
4263 | capability is to allow the use of @code{out} and @code{in out} | |
4264 | parameters in interfacing to external functions (which are not permitted | |
4265 | in Ada functions). You may optionally use the @code{Mechanism} | |
4266 | parameters to specify passing mechanisms for the parameters. | |
4267 | If you specify a single mechanism name, it applies to all parameters. | |
4268 | Otherwise you may specify a mechanism on a parameter by parameter | |
4269 | basis using either positional or named notation. If the mechanism is not | |
4270 | specified, the default mechanism is used. | |
64d5610f | 4271 | |
b71d4b62 RA |
4272 | Note that it is important to use this pragma in conjunction with a separate |
4273 | pragma Import that specifies the desired convention, since otherwise the | |
4274 | default convention is Ada, which is almost certainly not what is required. | |
4275 | ||
4276 | @node Pragma Independent,Pragma Independent_Components,Pragma Import_Valued_Procedure,Implementation Defined Pragmas | |
4277 | @anchor{gnat_rm/implementation_defined_pragmas pragma-independent}@anchor{7e} | |
4278 | @section Pragma Independent | |
64d5610f ML |
4279 | |
4280 | ||
4281 | Syntax: | |
4282 | ||
4283 | @example | |
b71d4b62 | 4284 | pragma Independent (Local_NAME); |
64d5610f ML |
4285 | @end example |
4286 | ||
b71d4b62 RA |
4287 | This pragma is standard in Ada 2012 mode (which also provides an aspect |
4288 | of the same name). It is also available as an implementation-defined | |
4289 | pragma in all earlier versions. It specifies that the | |
4290 | designated object or all objects of the designated type must be | |
4291 | independently addressable. This means that separate tasks can safely | |
4292 | manipulate such objects. For example, if two components of a record are | |
4293 | independent, then two separate tasks may access these two components. | |
4294 | This may place | |
4295 | constraints on the representation of the object (for instance prohibiting | |
4296 | tight packing). | |
64d5610f | 4297 | |
b71d4b62 RA |
4298 | @node Pragma Independent_Components,Pragma Initial_Condition,Pragma Independent,Implementation Defined Pragmas |
4299 | @anchor{gnat_rm/implementation_defined_pragmas pragma-independent-components}@anchor{7f} | |
4300 | @section Pragma Independent_Components | |
64d5610f | 4301 | |
64d5610f | 4302 | |
b71d4b62 | 4303 | Syntax: |
64d5610f | 4304 | |
b71d4b62 RA |
4305 | @example |
4306 | pragma Independent_Components (Local_NAME); | |
4307 | @end example | |
64d5610f | 4308 | |
b71d4b62 RA |
4309 | This pragma is standard in Ada 2012 mode (which also provides an aspect |
4310 | of the same name). It is also available as an implementation-defined | |
4311 | pragma in all earlier versions. It specifies that the components of the | |
4312 | designated object, or the components of each object of the designated | |
4313 | type, must be | |
4314 | independently addressable. This means that separate tasks can safely | |
4315 | manipulate separate components in the composite object. This may place | |
4316 | constraints on the representation of the object (for instance prohibiting | |
4317 | tight packing). | |
64d5610f | 4318 | |
b71d4b62 RA |
4319 | @node Pragma Initial_Condition,Pragma Initialize_Scalars,Pragma Independent_Components,Implementation Defined Pragmas |
4320 | @anchor{gnat_rm/implementation_defined_pragmas id17}@anchor{80}@anchor{gnat_rm/implementation_defined_pragmas pragma-initial-condition}@anchor{81} | |
4321 | @section Pragma Initial_Condition | |
64d5610f ML |
4322 | |
4323 | ||
4324 | Syntax: | |
4325 | ||
4326 | @example | |
b71d4b62 | 4327 | pragma Initial_Condition (boolean_EXPRESSION); |
64d5610f ML |
4328 | @end example |
4329 | ||
b71d4b62 RA |
4330 | For the semantics of this pragma, see the entry for aspect @code{Initial_Condition} |
4331 | in the SPARK 2014 Reference Manual, section 7.1.6. | |
4332 | ||
4333 | @node Pragma Initialize_Scalars,Pragma Initializes,Pragma Initial_Condition,Implementation Defined Pragmas | |
4334 | @anchor{gnat_rm/implementation_defined_pragmas pragma-initialize-scalars}@anchor{82} | |
4335 | @section Pragma Initialize_Scalars | |
64d5610f | 4336 | |
64d5610f | 4337 | |
b71d4b62 | 4338 | @geindex debugging with Initialize_Scalars |
64d5610f ML |
4339 | |
4340 | Syntax: | |
4341 | ||
4342 | @example | |
b71d4b62 RA |
4343 | pragma Initialize_Scalars |
4344 | [ ( TYPE_VALUE_PAIR @{, TYPE_VALUE_PAIR@} ) ]; | |
64d5610f | 4345 | |
b71d4b62 RA |
4346 | TYPE_VALUE_PAIR ::= |
4347 | SCALAR_TYPE => static_EXPRESSION | |
64d5610f | 4348 | |
b71d4b62 RA |
4349 | SCALAR_TYPE := |
4350 | Short_Float | |
4351 | | Float | |
4352 | | Long_Float | |
4353 | | Long_Long_Flat | |
4354 | | Signed_8 | |
4355 | | Signed_16 | |
4356 | | Signed_32 | |
4357 | | Signed_64 | |
4358 | | Unsigned_8 | |
4359 | | Unsigned_16 | |
4360 | | Unsigned_32 | |
4361 | | Unsigned_64 | |
64d5610f ML |
4362 | @end example |
4363 | ||
b71d4b62 RA |
4364 | This pragma is similar to @code{Normalize_Scalars} conceptually but has two |
4365 | important differences. | |
64d5610f | 4366 | |
b71d4b62 RA |
4367 | First, there is no requirement for the pragma to be used uniformly in all units |
4368 | of a partition. In particular, it is fine to use this just for some or all of | |
4369 | the application units of a partition, without needing to recompile the run-time | |
4370 | library. In the case where some units are compiled with the pragma, and some | |
4371 | without, then a declaration of a variable where the type is defined in package | |
4372 | Standard or is locally declared will always be subject to initialization, as | |
4373 | will any declaration of a scalar variable. For composite variables, whether the | |
4374 | variable is initialized may also depend on whether the package in which the | |
4375 | type of the variable is declared is compiled with the pragma. | |
64d5610f | 4376 | |
b71d4b62 RA |
4377 | The other important difference is that the programmer can control the value |
4378 | used for initializing scalar objects. This effect can be achieved in several | |
4379 | different ways: | |
64d5610f | 4380 | |
64d5610f | 4381 | |
b71d4b62 | 4382 | @itemize * |
64d5610f | 4383 | |
b71d4b62 RA |
4384 | @item |
4385 | At compile time, the programmer can specify the invalid value for a | |
4386 | particular family of scalar types using the optional arguments of the pragma. | |
64d5610f | 4387 | |
b71d4b62 RA |
4388 | The compile-time approach is intended to optimize the generated code for the |
4389 | pragma, by possibly using fast operations such as @code{memset}. Note that such | |
4390 | optimizations require using values where the bytes all have the same binary | |
4391 | representation. | |
64d5610f | 4392 | |
b71d4b62 RA |
4393 | @item |
4394 | At bind time, the programmer has several options: | |
64d5610f | 4395 | |
64d5610f | 4396 | |
b71d4b62 | 4397 | @itemize * |
64d5610f | 4398 | |
b71d4b62 RA |
4399 | @item |
4400 | Initialization with invalid values (similar to Normalize_Scalars, though | |
4401 | for Initialize_Scalars it is not always possible to determine the invalid | |
4402 | values in complex cases like signed component fields with nonstandard | |
4403 | sizes). | |
64d5610f | 4404 | |
b71d4b62 RA |
4405 | @item |
4406 | Initialization with high values. | |
64d5610f | 4407 | |
b71d4b62 RA |
4408 | @item |
4409 | Initialization with low values. | |
64d5610f | 4410 | |
b71d4b62 RA |
4411 | @item |
4412 | Initialization with a specific bit pattern. | |
4413 | @end itemize | |
64d5610f | 4414 | |
b71d4b62 | 4415 | See the GNAT User’s Guide for binder options for specifying these cases. |
64d5610f | 4416 | |
b71d4b62 RA |
4417 | The bind-time approach is intended to provide fast turnaround for testing |
4418 | with different values, without having to recompile the program. | |
64d5610f | 4419 | |
b71d4b62 RA |
4420 | @item |
4421 | At execution time, the programmer can specify the invalid values using an | |
4422 | environment variable. See the GNAT User’s Guide for details. | |
64d5610f | 4423 | |
b71d4b62 RA |
4424 | The execution-time approach is intended to provide fast turnaround for |
4425 | testing with different values, without having to recompile and rebind the | |
4426 | program. | |
4427 | @end itemize | |
64d5610f | 4428 | |
b71d4b62 RA |
4429 | Note that pragma @code{Initialize_Scalars} is particularly useful in conjunction |
4430 | with the enhanced validity checking that is now provided in GNAT, which checks | |
4431 | for invalid values under more conditions. Using this feature (see description | |
1acce141 | 4432 | of the @emph{-gnatV} flag in the GNAT User’s Guide) in conjunction with pragma |
b71d4b62 RA |
4433 | @code{Initialize_Scalars} provides a powerful new tool to assist in the detection |
4434 | of problems caused by uninitialized variables. | |
64d5610f | 4435 | |
b71d4b62 RA |
4436 | Note: the use of @code{Initialize_Scalars} has a fairly extensive effect on the |
4437 | generated code. This may cause your code to be substantially larger. It may | |
4438 | also cause an increase in the amount of stack required, so it is probably a | |
4439 | good idea to turn on stack checking (see description of stack checking in the | |
4440 | GNAT User’s Guide) when using this pragma. | |
4441 | ||
4442 | @node Pragma Initializes,Pragma Inline_Always,Pragma Initialize_Scalars,Implementation Defined Pragmas | |
4443 | @anchor{gnat_rm/implementation_defined_pragmas id18}@anchor{83}@anchor{gnat_rm/implementation_defined_pragmas pragma-initializes}@anchor{84} | |
4444 | @section Pragma Initializes | |
64d5610f ML |
4445 | |
4446 | ||
4447 | Syntax: | |
4448 | ||
4449 | @example | |
b71d4b62 | 4450 | pragma Initializes (INITIALIZATION_LIST); |
64d5610f | 4451 | |
b71d4b62 RA |
4452 | INITIALIZATION_LIST ::= |
4453 | null | |
4454 | | (INITIALIZATION_ITEM @{, INITIALIZATION_ITEM@}) | |
64d5610f | 4455 | |
b71d4b62 | 4456 | INITIALIZATION_ITEM ::= name [=> INPUT_LIST] |
64d5610f | 4457 | |
b71d4b62 RA |
4458 | INPUT_LIST ::= |
4459 | null | |
4460 | | INPUT | |
4461 | | (INPUT @{, INPUT@}) | |
64d5610f | 4462 | |
b71d4b62 | 4463 | INPUT ::= name |
64d5610f ML |
4464 | @end example |
4465 | ||
b71d4b62 RA |
4466 | For the semantics of this pragma, see the entry for aspect @code{Initializes} in the |
4467 | SPARK 2014 Reference Manual, section 7.1.5. | |
64d5610f | 4468 | |
b71d4b62 RA |
4469 | @node Pragma Inline_Always,Pragma Inline_Generic,Pragma Initializes,Implementation Defined Pragmas |
4470 | @anchor{gnat_rm/implementation_defined_pragmas id19}@anchor{85}@anchor{gnat_rm/implementation_defined_pragmas pragma-inline-always}@anchor{86} | |
4471 | @section Pragma Inline_Always | |
64d5610f | 4472 | |
64d5610f ML |
4473 | |
4474 | Syntax: | |
4475 | ||
4476 | @example | |
b71d4b62 | 4477 | pragma Inline_Always (NAME [, NAME]); |
64d5610f ML |
4478 | @end example |
4479 | ||
b71d4b62 RA |
4480 | Similar to pragma @code{Inline} except that inlining is unconditional. |
4481 | Inline_Always instructs the compiler to inline every direct call to the | |
4482 | subprogram or else to emit a compilation error, independently of any | |
1acce141 | 4483 | option, in particular @emph{-gnatn} or @emph{-gnatN} or the optimization level. |
b71d4b62 RA |
4484 | It is an error to take the address or access of @code{NAME}. It is also an error to |
4485 | apply this pragma to a primitive operation of a tagged type. Thanks to such | |
4486 | restrictions, the compiler is allowed to remove the out-of-line body of @code{NAME}. | |
4487 | ||
4488 | @node Pragma Inline_Generic,Pragma Interface,Pragma Inline_Always,Implementation Defined Pragmas | |
4489 | @anchor{gnat_rm/implementation_defined_pragmas pragma-inline-generic}@anchor{87} | |
4490 | @section Pragma Inline_Generic | |
4491 | ||
4492 | ||
4493 | Syntax: | |
64d5610f ML |
4494 | |
4495 | @example | |
b71d4b62 RA |
4496 | pragma Inline_Generic (GNAME @{, GNAME@}); |
4497 | ||
4498 | GNAME ::= generic_unit_NAME | generic_instance_NAME | |
64d5610f ML |
4499 | @end example |
4500 | ||
b71d4b62 RA |
4501 | This pragma is provided for compatibility with Dec Ada 83. It has |
4502 | no effect in GNAT (which always inlines generics), other | |
4503 | than to check that the given names are all names of generic units or | |
4504 | generic instances. | |
64d5610f | 4505 | |
b71d4b62 RA |
4506 | @node Pragma Interface,Pragma Interface_Name,Pragma Inline_Generic,Implementation Defined Pragmas |
4507 | @anchor{gnat_rm/implementation_defined_pragmas pragma-interface}@anchor{88} | |
4508 | @section Pragma Interface | |
64d5610f | 4509 | |
64d5610f | 4510 | |
b71d4b62 | 4511 | Syntax: |
64d5610f ML |
4512 | |
4513 | @example | |
b71d4b62 RA |
4514 | pragma Interface ( |
4515 | [Convention =>] convention_identifier, | |
4516 | [Entity =>] local_NAME | |
4517 | [, [External_Name =>] static_string_expression] | |
4518 | [, [Link_Name =>] static_string_expression]); | |
64d5610f ML |
4519 | @end example |
4520 | ||
b71d4b62 RA |
4521 | This pragma is identical in syntax and semantics to |
4522 | the standard Ada pragma @code{Import}. It is provided for compatibility | |
4523 | with Ada 83. The definition is upwards compatible both with pragma | |
4524 | @code{Interface} as defined in the Ada 83 Reference Manual, and also | |
4525 | with some extended implementations of this pragma in certain Ada 83 | |
4526 | implementations. The only difference between pragma @code{Interface} | |
4527 | and pragma @code{Import} is that there is special circuitry to allow | |
4528 | both pragmas to appear for the same subprogram entity (normally it | |
4529 | is illegal to have multiple @code{Import} pragmas). This is useful in | |
4530 | maintaining Ada 83/Ada 95 compatibility and is compatible with other | |
4531 | Ada 83 compilers. | |
64d5610f | 4532 | |
b71d4b62 RA |
4533 | @node Pragma Interface_Name,Pragma Interrupt_Handler,Pragma Interface,Implementation Defined Pragmas |
4534 | @anchor{gnat_rm/implementation_defined_pragmas pragma-interface-name}@anchor{89} | |
4535 | @section Pragma Interface_Name | |
64d5610f ML |
4536 | |
4537 | ||
4538 | Syntax: | |
4539 | ||
4540 | @example | |
b71d4b62 RA |
4541 | pragma Interface_Name ( |
4542 | [Entity =>] LOCAL_NAME | |
4543 | [, [External_Name =>] static_string_EXPRESSION] | |
4544 | [, [Link_Name =>] static_string_EXPRESSION]); | |
4545 | @end example | |
64d5610f | 4546 | |
b71d4b62 RA |
4547 | This pragma provides an alternative way of specifying the interface name |
4548 | for an interfaced subprogram, and is provided for compatibility with Ada | |
4549 | 83 compilers that use the pragma for this purpose. You must provide at | |
4550 | least one of @code{External_Name} or @code{Link_Name}. | |
64d5610f | 4551 | |
b71d4b62 RA |
4552 | @node Pragma Interrupt_Handler,Pragma Interrupt_State,Pragma Interface_Name,Implementation Defined Pragmas |
4553 | @anchor{gnat_rm/implementation_defined_pragmas pragma-interrupt-handler}@anchor{8a} | |
4554 | @section Pragma Interrupt_Handler | |
64d5610f | 4555 | |
64d5610f | 4556 | |
b71d4b62 | 4557 | Syntax: |
64d5610f | 4558 | |
b71d4b62 RA |
4559 | @example |
4560 | pragma Interrupt_Handler (procedure_LOCAL_NAME); | |
64d5610f ML |
4561 | @end example |
4562 | ||
b71d4b62 RA |
4563 | This program unit pragma is supported for parameterless protected procedures |
4564 | as described in Annex C of the Ada Reference Manual. | |
64d5610f | 4565 | |
b71d4b62 RA |
4566 | @node Pragma Interrupt_State,Pragma Invariant,Pragma Interrupt_Handler,Implementation Defined Pragmas |
4567 | @anchor{gnat_rm/implementation_defined_pragmas pragma-interrupt-state}@anchor{8b} | |
4568 | @section Pragma Interrupt_State | |
64d5610f ML |
4569 | |
4570 | ||
4571 | Syntax: | |
4572 | ||
4573 | @example | |
b71d4b62 RA |
4574 | pragma Interrupt_State |
4575 | ([Name =>] value, | |
4576 | [State =>] SYSTEM | RUNTIME | USER); | |
64d5610f ML |
4577 | @end example |
4578 | ||
b71d4b62 RA |
4579 | Normally certain interrupts are reserved to the implementation. Any attempt |
4580 | to attach an interrupt causes Program_Error to be raised, as described in | |
4581 | RM C.3.2(22). A typical example is the @code{SIGINT} interrupt used in | |
4582 | many systems for an @code{Ctrl-C} interrupt. Normally this interrupt is | |
4583 | reserved to the implementation, so that @code{Ctrl-C} can be used to | |
4584 | interrupt execution. Additionally, signals such as @code{SIGSEGV}, | |
4585 | @code{SIGABRT}, @code{SIGFPE} and @code{SIGILL} are often mapped to specific | |
4586 | Ada exceptions, or used to implement run-time functions such as the | |
4587 | @code{abort} statement and stack overflow checking. | |
64d5610f | 4588 | |
b71d4b62 RA |
4589 | Pragma @code{Interrupt_State} provides a general mechanism for overriding |
4590 | such uses of interrupts. It subsumes the functionality of pragma | |
4591 | @code{Unreserve_All_Interrupts}. Pragma @code{Interrupt_State} is not | |
4592 | available on Windows. On all other platforms than VxWorks, | |
4593 | it applies to signals; on VxWorks, it applies to vectored hardware interrupts | |
4594 | and may be used to mark interrupts required by the board support package | |
4595 | as reserved. | |
64d5610f | 4596 | |
b71d4b62 | 4597 | Interrupts can be in one of three states: |
64d5610f | 4598 | |
64d5610f | 4599 | |
b71d4b62 | 4600 | @itemize * |
64d5610f | 4601 | |
b71d4b62 RA |
4602 | @item |
4603 | System | |
64d5610f | 4604 | |
b71d4b62 RA |
4605 | The interrupt is reserved (no Ada handler can be installed), and the |
4606 | Ada run-time may not install a handler. As a result you are guaranteed | |
4607 | standard system default action if this interrupt is raised. This also allows | |
4608 | installing a low level handler via C APIs such as sigaction(), outside | |
4609 | of Ada control. | |
64d5610f | 4610 | |
b71d4b62 RA |
4611 | @item |
4612 | Runtime | |
64d5610f | 4613 | |
b71d4b62 RA |
4614 | The interrupt is reserved (no Ada handler can be installed). The run time |
4615 | is allowed to install a handler for internal control purposes, but is | |
4616 | not required to do so. | |
64d5610f | 4617 | |
b71d4b62 RA |
4618 | @item |
4619 | User | |
64d5610f | 4620 | |
b71d4b62 RA |
4621 | The interrupt is unreserved. The user may install an Ada handler via |
4622 | Ada.Interrupts and pragma Interrupt_Handler or Attach_Handler to provide | |
4623 | some other action. | |
4624 | @end itemize | |
64d5610f | 4625 | |
b71d4b62 RA |
4626 | These states are the allowed values of the @code{State} parameter of the |
4627 | pragma. The @code{Name} parameter is a value of the type | |
4628 | @code{Ada.Interrupts.Interrupt_ID}. Typically, it is a name declared in | |
4629 | @code{Ada.Interrupts.Names}. | |
64d5610f | 4630 | |
b71d4b62 RA |
4631 | This is a configuration pragma, and the binder will check that there |
4632 | are no inconsistencies between different units in a partition in how a | |
4633 | given interrupt is specified. It may appear anywhere a pragma is legal. | |
64d5610f | 4634 | |
b71d4b62 | 4635 | The effect is to move the interrupt to the specified state. |
64d5610f | 4636 | |
b71d4b62 RA |
4637 | By declaring interrupts to be SYSTEM, you guarantee the standard system |
4638 | action, such as a core dump. | |
64d5610f | 4639 | |
b71d4b62 RA |
4640 | By declaring interrupts to be USER, you guarantee that you can install |
4641 | a handler. | |
64d5610f | 4642 | |
b71d4b62 RA |
4643 | Note that certain signals on many operating systems cannot be caught and |
4644 | handled by applications. In such cases, the pragma is ignored. See the | |
4645 | operating system documentation, or the value of the array @code{Reserved} | |
4646 | declared in the spec of package @code{System.OS_Interface}. | |
64d5610f | 4647 | |
b71d4b62 RA |
4648 | Overriding the default state of signals used by the Ada runtime may interfere |
4649 | with an application’s runtime behavior in the cases of the synchronous signals, | |
4650 | and in the case of the signal used to implement the @code{abort} statement. | |
64d5610f | 4651 | |
b71d4b62 RA |
4652 | @node Pragma Invariant,Pragma Keep_Names,Pragma Interrupt_State,Implementation Defined Pragmas |
4653 | @anchor{gnat_rm/implementation_defined_pragmas id20}@anchor{8c}@anchor{gnat_rm/implementation_defined_pragmas pragma-invariant}@anchor{8d} | |
4654 | @section Pragma Invariant | |
64d5610f | 4655 | |
64d5610f | 4656 | |
b71d4b62 | 4657 | Syntax: |
64d5610f | 4658 | |
b71d4b62 RA |
4659 | @example |
4660 | pragma Invariant | |
4661 | ([Entity =>] private_type_LOCAL_NAME, | |
4662 | [Check =>] EXPRESSION | |
4663 | [,[Message =>] String_Expression]); | |
64d5610f ML |
4664 | @end example |
4665 | ||
b71d4b62 RA |
4666 | This pragma provides exactly the same capabilities as the Type_Invariant aspect |
4667 | defined in AI05-0146-1, and in the Ada 2012 Reference Manual. The | |
4668 | Type_Invariant aspect is fully implemented in Ada 2012 mode, but since it | |
4669 | requires the use of the aspect syntax, which is not available except in 2012 | |
4670 | mode, it is not possible to use the Type_Invariant aspect in earlier versions | |
4671 | of Ada. However the Invariant pragma may be used in any version of Ada. Also | |
4672 | note that the aspect Invariant is a synonym in GNAT for the aspect | |
4673 | Type_Invariant, but there is no pragma Type_Invariant. | |
64d5610f | 4674 | |
b71d4b62 RA |
4675 | The pragma must appear within the visible part of the package specification, |
4676 | after the type to which its Entity argument appears. As with the Invariant | |
4677 | aspect, the Check expression is not analyzed until the end of the visible | |
4678 | part of the package, so it may contain forward references. The Message | |
4679 | argument, if present, provides the exception message used if the invariant | |
4680 | is violated. If no Message parameter is provided, a default message that | |
4681 | identifies the line on which the pragma appears is used. | |
64d5610f | 4682 | |
b71d4b62 RA |
4683 | It is permissible to have multiple Invariants for the same type entity, in |
4684 | which case they are and’ed together. It is permissible to use this pragma | |
4685 | in Ada 2012 mode, but you cannot have both an invariant aspect and an | |
4686 | invariant pragma for the same entity. | |
4687 | ||
4688 | For further details on the use of this pragma, see the Ada 2012 documentation | |
4689 | of the Type_Invariant aspect. | |
4690 | ||
4691 | @node Pragma Keep_Names,Pragma License,Pragma Invariant,Implementation Defined Pragmas | |
4692 | @anchor{gnat_rm/implementation_defined_pragmas pragma-keep-names}@anchor{8e} | |
4693 | @section Pragma Keep_Names | |
64d5610f ML |
4694 | |
4695 | ||
4696 | Syntax: | |
4697 | ||
4698 | @example | |
b71d4b62 | 4699 | pragma Keep_Names ([On =>] enumeration_first_subtype_LOCAL_NAME); |
64d5610f ML |
4700 | @end example |
4701 | ||
b71d4b62 RA |
4702 | The @code{LOCAL_NAME} argument |
4703 | must refer to an enumeration first subtype | |
4704 | in the current declarative part. The effect is to retain the enumeration | |
4705 | literal names for use by @code{Image} and @code{Value} even if a global | |
4706 | @code{Discard_Names} pragma applies. This is useful when you want to | |
4707 | generally suppress enumeration literal names and for example you therefore | |
4708 | use a @code{Discard_Names} pragma in the @code{gnat.adc} file, but you | |
4709 | want to retain the names for specific enumeration types. | |
64d5610f | 4710 | |
b71d4b62 RA |
4711 | @node Pragma License,Pragma Link_With,Pragma Keep_Names,Implementation Defined Pragmas |
4712 | @anchor{gnat_rm/implementation_defined_pragmas pragma-license}@anchor{8f} | |
4713 | @section Pragma License | |
64d5610f ML |
4714 | |
4715 | ||
b71d4b62 | 4716 | @geindex License checking |
64d5610f ML |
4717 | |
4718 | Syntax: | |
4719 | ||
4720 | @example | |
b71d4b62 | 4721 | pragma License (Unrestricted | GPL | Modified_GPL | Restricted); |
64d5610f ML |
4722 | @end example |
4723 | ||
b71d4b62 RA |
4724 | This pragma is provided to allow automated checking for appropriate license |
4725 | conditions with respect to the standard and modified GPL. A pragma | |
4726 | @code{License}, which is a configuration pragma that typically appears at | |
4727 | the start of a source file or in a separate @code{gnat.adc} file, specifies | |
4728 | the licensing conditions of a unit as follows: | |
64d5610f ML |
4729 | |
4730 | ||
4731 | @itemize * | |
4732 | ||
4733 | @item | |
b71d4b62 RA |
4734 | Unrestricted |
4735 | This is used for a unit that can be freely used with no license restrictions. | |
4736 | Examples of such units are public domain units, and units from the Ada | |
4737 | Reference Manual. | |
64d5610f ML |
4738 | |
4739 | @item | |
b71d4b62 RA |
4740 | GPL |
4741 | This is used for a unit that is licensed under the unmodified GPL, and which | |
4742 | therefore cannot be @code{with}ed by a restricted unit. | |
64d5610f ML |
4743 | |
4744 | @item | |
b71d4b62 RA |
4745 | Modified_GPL |
4746 | This is used for a unit licensed under the GNAT modified GPL that includes | |
4747 | a special exception paragraph that specifically permits the inclusion of | |
4748 | the unit in programs without requiring the entire program to be released | |
4749 | under the GPL. | |
64d5610f ML |
4750 | |
4751 | @item | |
b71d4b62 RA |
4752 | Restricted |
4753 | This is used for a unit that is restricted in that it is not permitted to | |
4754 | depend on units that are licensed under the GPL. Typical examples are | |
4755 | proprietary code that is to be released under more restrictive license | |
4756 | conditions. Note that restricted units are permitted to @code{with} units | |
4757 | which are licensed under the modified GPL (this is the whole point of the | |
4758 | modified GPL). | |
64d5610f ML |
4759 | @end itemize |
4760 | ||
b71d4b62 RA |
4761 | Normally a unit with no @code{License} pragma is considered to have an |
4762 | unknown license, and no checking is done. However, standard GNAT headers | |
4763 | are recognized, and license information is derived from them as follows. | |
64d5610f | 4764 | |
b71d4b62 RA |
4765 | A GNAT license header starts with a line containing 78 hyphens. The following |
4766 | comment text is searched for the appearance of any of the following strings. | |
64d5610f | 4767 | |
b71d4b62 RA |
4768 | If the string ‘GNU General Public License’ is found, then the unit is assumed |
4769 | to have GPL license, unless the string ‘As a special exception’ follows, in | |
4770 | which case the license is assumed to be modified GPL. | |
64d5610f | 4771 | |
b71d4b62 RA |
4772 | If one of the strings |
4773 | ‘This specification is adapted from the Ada Semantic Interface’ or | |
4774 | ‘This specification is derived from the Ada Reference Manual’ is found | |
4775 | then the unit is assumed to be unrestricted. | |
64d5610f | 4776 | |
b71d4b62 RA |
4777 | These default actions means that a program with a restricted license pragma |
4778 | will automatically get warnings if a GPL unit is inappropriately | |
4779 | @code{with}ed. For example, the program: | |
64d5610f ML |
4780 | |
4781 | @example | |
b71d4b62 RA |
4782 | with Sem_Ch3; |
4783 | with GNAT.Sockets; | |
4784 | procedure Secret_Stuff is | |
4785 | ... | |
4786 | end Secret_Stuff | |
4787 | @end example | |
64d5610f | 4788 | |
b71d4b62 RA |
4789 | if compiled with pragma @code{License} (@code{Restricted}) in a |
4790 | @code{gnat.adc} file will generate the warning: | |
64d5610f | 4791 | |
b71d4b62 RA |
4792 | @example |
4793 | 1. with Sem_Ch3; | |
4794 | | | |
4795 | >>> license of withed unit "Sem_Ch3" is incompatible | |
64d5610f | 4796 | |
b71d4b62 RA |
4797 | 2. with GNAT.Sockets; |
4798 | 3. procedure Secret_Stuff is | |
64d5610f ML |
4799 | @end example |
4800 | ||
b71d4b62 RA |
4801 | Here we get a warning on @code{Sem_Ch3} since it is part of the GNAT |
4802 | compiler and is licensed under the | |
4803 | GPL, but no warning for @code{GNAT.Sockets} which is part of the GNAT | |
4804 | run time, and is therefore licensed under the modified GPL. | |
64d5610f | 4805 | |
b71d4b62 RA |
4806 | @node Pragma Link_With,Pragma Linker_Alias,Pragma License,Implementation Defined Pragmas |
4807 | @anchor{gnat_rm/implementation_defined_pragmas pragma-link-with}@anchor{90} | |
4808 | @section Pragma Link_With | |
64d5610f ML |
4809 | |
4810 | ||
4811 | Syntax: | |
4812 | ||
4813 | @example | |
b71d4b62 | 4814 | pragma Link_With (static_string_EXPRESSION @{,static_string_EXPRESSION@}); |
64d5610f ML |
4815 | @end example |
4816 | ||
b71d4b62 RA |
4817 | This pragma is provided for compatibility with certain Ada 83 compilers. |
4818 | It has exactly the same effect as pragma @code{Linker_Options} except | |
4819 | that spaces occurring within one of the string expressions are treated | |
4820 | as separators. For example, in the following case: | |
64d5610f ML |
4821 | |
4822 | @example | |
b71d4b62 | 4823 | pragma Link_With ("-labc -ldef"); |
64d5610f ML |
4824 | @end example |
4825 | ||
b71d4b62 RA |
4826 | results in passing the strings @code{-labc} and @code{-ldef} as two |
4827 | separate arguments to the linker. In addition pragma Link_With allows | |
4828 | multiple arguments, with the same effect as successive pragmas. | |
64d5610f | 4829 | |
b71d4b62 RA |
4830 | @node Pragma Linker_Alias,Pragma Linker_Constructor,Pragma Link_With,Implementation Defined Pragmas |
4831 | @anchor{gnat_rm/implementation_defined_pragmas pragma-linker-alias}@anchor{91} | |
4832 | @section Pragma Linker_Alias | |
64d5610f ML |
4833 | |
4834 | ||
4835 | Syntax: | |
4836 | ||
4837 | @example | |
b71d4b62 RA |
4838 | pragma Linker_Alias ( |
4839 | [Entity =>] LOCAL_NAME, | |
4840 | [Target =>] static_string_EXPRESSION); | |
64d5610f ML |
4841 | @end example |
4842 | ||
b71d4b62 RA |
4843 | @code{LOCAL_NAME} must refer to an object that is declared at the library |
4844 | level. This pragma establishes the given entity as a linker alias for the | |
4845 | given target. It is equivalent to @code{__attribute__((alias))} in GNU C | |
4846 | and causes @code{LOCAL_NAME} to be emitted as an alias for the symbol | |
4847 | @code{static_string_EXPRESSION} in the object file, that is to say no space | |
4848 | is reserved for @code{LOCAL_NAME} by the assembler and it will be resolved | |
4849 | to the same address as @code{static_string_EXPRESSION} by the linker. | |
64d5610f | 4850 | |
b71d4b62 RA |
4851 | The actual linker name for the target must be used (e.g., the fully |
4852 | encoded name with qualification in Ada, or the mangled name in C++), | |
4853 | or it must be declared using the C convention with @code{pragma Import} | |
4854 | or @code{pragma Export}. | |
64d5610f | 4855 | |
b71d4b62 RA |
4856 | Not all target machines support this pragma. On some of them it is accepted |
4857 | only if @code{pragma Weak_External} has been applied to @code{LOCAL_NAME}. | |
64d5610f ML |
4858 | |
4859 | @example | |
b71d4b62 | 4860 | -- Example of the use of pragma Linker_Alias |
64d5610f | 4861 | |
b71d4b62 RA |
4862 | package p is |
4863 | i : Integer := 1; | |
4864 | pragma Export (C, i); | |
64d5610f | 4865 | |
b71d4b62 RA |
4866 | new_name_for_i : Integer; |
4867 | pragma Linker_Alias (new_name_for_i, "i"); | |
4868 | end p; | |
4869 | @end example | |
4870 | ||
4871 | @node Pragma Linker_Constructor,Pragma Linker_Destructor,Pragma Linker_Alias,Implementation Defined Pragmas | |
4872 | @anchor{gnat_rm/implementation_defined_pragmas pragma-linker-constructor}@anchor{92} | |
4873 | @section Pragma Linker_Constructor | |
64d5610f ML |
4874 | |
4875 | ||
4876 | Syntax: | |
4877 | ||
4878 | @example | |
b71d4b62 | 4879 | pragma Linker_Constructor (procedure_LOCAL_NAME); |
64d5610f ML |
4880 | @end example |
4881 | ||
b71d4b62 RA |
4882 | @code{procedure_LOCAL_NAME} must refer to a parameterless procedure that |
4883 | is declared at the library level. A procedure to which this pragma is | |
4884 | applied will be treated as an initialization routine by the linker. | |
4885 | It is equivalent to @code{__attribute__((constructor))} in GNU C and | |
4886 | causes @code{procedure_LOCAL_NAME} to be invoked before the entry point | |
4887 | of the executable is called (or immediately after the shared library is | |
4888 | loaded if the procedure is linked in a shared library), in particular | |
4889 | before the Ada run-time environment is set up. | |
64d5610f | 4890 | |
b71d4b62 RA |
4891 | Because of these specific contexts, the set of operations such a procedure |
4892 | can perform is very limited and the type of objects it can manipulate is | |
4893 | essentially restricted to the elementary types. In particular, it must only | |
4894 | contain code to which pragma Restrictions (No_Elaboration_Code) applies. | |
4895 | ||
4896 | This pragma is used by GNAT to implement auto-initialization of shared Stand | |
4897 | Alone Libraries, which provides a related capability without the restrictions | |
4898 | listed above. Where possible, the use of Stand Alone Libraries is preferable | |
4899 | to the use of this pragma. | |
4900 | ||
4901 | @node Pragma Linker_Destructor,Pragma Linker_Section,Pragma Linker_Constructor,Implementation Defined Pragmas | |
4902 | @anchor{gnat_rm/implementation_defined_pragmas pragma-linker-destructor}@anchor{93} | |
4903 | @section Pragma Linker_Destructor | |
64d5610f ML |
4904 | |
4905 | ||
4906 | Syntax: | |
4907 | ||
4908 | @example | |
b71d4b62 | 4909 | pragma Linker_Destructor (procedure_LOCAL_NAME); |
64d5610f ML |
4910 | @end example |
4911 | ||
b71d4b62 RA |
4912 | @code{procedure_LOCAL_NAME} must refer to a parameterless procedure that |
4913 | is declared at the library level. A procedure to which this pragma is | |
4914 | applied will be treated as a finalization routine by the linker. | |
4915 | It is equivalent to @code{__attribute__((destructor))} in GNU C and | |
4916 | causes @code{procedure_LOCAL_NAME} to be invoked after the entry point | |
4917 | of the executable has exited (or immediately before the shared library | |
4918 | is unloaded if the procedure is linked in a shared library), in particular | |
4919 | after the Ada run-time environment is shut down. | |
64d5610f | 4920 | |
b71d4b62 RA |
4921 | See @code{pragma Linker_Constructor} for the set of restrictions that apply |
4922 | because of these specific contexts. | |
64d5610f | 4923 | |
b71d4b62 RA |
4924 | @node Pragma Linker_Section,Pragma Lock_Free,Pragma Linker_Destructor,Implementation Defined Pragmas |
4925 | @anchor{gnat_rm/implementation_defined_pragmas id21}@anchor{94}@anchor{gnat_rm/implementation_defined_pragmas pragma-linker-section}@anchor{95} | |
4926 | @section Pragma Linker_Section | |
64d5610f ML |
4927 | |
4928 | ||
b71d4b62 | 4929 | Syntax: |
64d5610f | 4930 | |
b71d4b62 RA |
4931 | @example |
4932 | pragma Linker_Section ( | |
4933 | [Entity =>] LOCAL_NAME, | |
4934 | [Section =>] static_string_EXPRESSION); | |
4935 | @end example | |
64d5610f | 4936 | |
b71d4b62 RA |
4937 | @code{LOCAL_NAME} must refer to an object, type, or subprogram that is |
4938 | declared at the library level. This pragma specifies the name of the | |
4939 | linker section for the given entity. It is equivalent to | |
4940 | @code{__attribute__((section))} in GNU C and causes @code{LOCAL_NAME} to | |
4941 | be placed in the @code{static_string_EXPRESSION} section of the | |
4942 | executable (assuming the linker doesn’t rename the section). | |
4943 | GNAT also provides an implementation defined aspect of the same name. | |
64d5610f | 4944 | |
b71d4b62 RA |
4945 | In the case of specifying this aspect for a type, the effect is to |
4946 | specify the corresponding section for all library-level objects of | |
4947 | the type that do not have an explicit linker section set. Note that | |
4948 | this only applies to whole objects, not to components of composite objects. | |
64d5610f | 4949 | |
b71d4b62 RA |
4950 | In the case of a subprogram, the linker section applies to all previously |
4951 | declared matching overloaded subprograms in the current declarative part | |
4952 | which do not already have a linker section assigned. The linker section | |
4953 | aspect is useful in this case for specifying different linker sections | |
4954 | for different elements of such an overloaded set. | |
64d5610f | 4955 | |
b71d4b62 RA |
4956 | Note that an empty string specifies that no linker section is specified. |
4957 | This is not quite the same as omitting the pragma or aspect, since it | |
4958 | can be used to specify that one element of an overloaded set of subprograms | |
4959 | has the default linker section, or that one object of a type for which a | |
4960 | linker section is specified should has the default linker section. | |
64d5610f | 4961 | |
b71d4b62 RA |
4962 | The compiler normally places library-level entities in standard sections |
4963 | depending on the class: procedures and functions generally go in the | |
4964 | @code{.text} section, initialized variables in the @code{.data} section | |
4965 | and uninitialized variables in the @code{.bss} section. | |
64d5610f | 4966 | |
b71d4b62 RA |
4967 | Other, special sections may exist on given target machines to map special |
4968 | hardware, for example I/O ports or flash memory. This pragma is a means to | |
4969 | defer the final layout of the executable to the linker, thus fully working | |
4970 | at the symbolic level with the compiler. | |
64d5610f | 4971 | |
b71d4b62 RA |
4972 | Some file formats do not support arbitrary sections so not all target |
4973 | machines support this pragma. The use of this pragma may cause a program | |
4974 | execution to be erroneous if it is used to place an entity into an | |
4975 | inappropriate section (e.g., a modified variable into the @code{.text} | |
4976 | section). See also @code{pragma Persistent_BSS}. | |
64d5610f | 4977 | |
b71d4b62 RA |
4978 | @example |
4979 | -- Example of the use of pragma Linker_Section | |
64d5610f | 4980 | |
b71d4b62 RA |
4981 | package IO_Card is |
4982 | Port_A : Integer; | |
4983 | pragma Volatile (Port_A); | |
4984 | pragma Linker_Section (Port_A, ".bss.port_a"); | |
64d5610f | 4985 | |
b71d4b62 RA |
4986 | Port_B : Integer; |
4987 | pragma Volatile (Port_B); | |
4988 | pragma Linker_Section (Port_B, ".bss.port_b"); | |
64d5610f | 4989 | |
b71d4b62 RA |
4990 | type Port_Type is new Integer with Linker_Section => ".bss"; |
4991 | PA : Port_Type with Linker_Section => ".bss.PA"; | |
4992 | PB : Port_Type; -- ends up in linker section ".bss" | |
64d5610f | 4993 | |
b71d4b62 RA |
4994 | procedure Q with Linker_Section => "Qsection"; |
4995 | end IO_Card; | |
4996 | @end example | |
64d5610f | 4997 | |
b71d4b62 RA |
4998 | @node Pragma Lock_Free,Pragma Loop_Invariant,Pragma Linker_Section,Implementation Defined Pragmas |
4999 | @anchor{gnat_rm/implementation_defined_pragmas id22}@anchor{96}@anchor{gnat_rm/implementation_defined_pragmas pragma-lock-free}@anchor{97} | |
5000 | @section Pragma Lock_Free | |
64d5610f ML |
5001 | |
5002 | ||
5003 | Syntax: | |
b71d4b62 RA |
5004 | This pragma may be specified for protected types or objects. It specifies that |
5005 | the implementation of protected operations must be implemented without locks. | |
5006 | Compilation fails if the compiler cannot generate lock-free code for the | |
5007 | operations. | |
64d5610f | 5008 | |
b71d4b62 | 5009 | The current conditions required to support this pragma are: |
64d5610f | 5010 | |
64d5610f | 5011 | |
b71d4b62 | 5012 | @itemize * |
64d5610f | 5013 | |
b71d4b62 RA |
5014 | @item |
5015 | Protected type declarations may not contain entries | |
64d5610f | 5016 | |
b71d4b62 RA |
5017 | @item |
5018 | Protected subprogram declarations may not have nonelementary parameters | |
5019 | @end itemize | |
64d5610f | 5020 | |
b71d4b62 | 5021 | In addition, each protected subprogram body must satisfy: |
64d5610f ML |
5022 | |
5023 | ||
b71d4b62 | 5024 | @itemize * |
64d5610f | 5025 | |
b71d4b62 RA |
5026 | @item |
5027 | May reference only one protected component | |
64d5610f | 5028 | |
b71d4b62 RA |
5029 | @item |
5030 | May not reference nonconstant entities outside the protected subprogram | |
5031 | scope | |
64d5610f | 5032 | |
b71d4b62 RA |
5033 | @item |
5034 | May not contain address representation items, allocators, or quantified | |
5035 | expressions | |
64d5610f ML |
5036 | |
5037 | @item | |
b71d4b62 | 5038 | May not contain delay, goto, loop, or procedure-call statements |
64d5610f ML |
5039 | |
5040 | @item | |
b71d4b62 | 5041 | May not contain exported and imported entities |
64d5610f ML |
5042 | |
5043 | @item | |
b71d4b62 | 5044 | May not dereferenced access values |
64d5610f ML |
5045 | |
5046 | @item | |
b71d4b62 | 5047 | Function calls and attribute references must be static |
64d5610f ML |
5048 | @end itemize |
5049 | ||
b71d4b62 RA |
5050 | If the Lock_Free aspect is specified to be True for a protected unit |
5051 | and the Ceiling_Locking locking policy is in effect, then the run-time | |
5052 | actions associated with the Ceiling_Locking locking policy (described in | |
5053 | Ada RM D.3) are not performed when a protected operation of the protected | |
5054 | unit is executed. | |
64d5610f | 5055 | |
b71d4b62 RA |
5056 | @node Pragma Loop_Invariant,Pragma Loop_Optimize,Pragma Lock_Free,Implementation Defined Pragmas |
5057 | @anchor{gnat_rm/implementation_defined_pragmas pragma-loop-invariant}@anchor{98} | |
5058 | @section Pragma Loop_Invariant | |
64d5610f | 5059 | |
64d5610f | 5060 | |
b71d4b62 | 5061 | Syntax: |
64d5610f ML |
5062 | |
5063 | @example | |
b71d4b62 | 5064 | pragma Loop_Invariant ( boolean_EXPRESSION ); |
64d5610f ML |
5065 | @end example |
5066 | ||
b71d4b62 RA |
5067 | The effect of this pragma is similar to that of pragma @code{Assert}, |
5068 | except that in an @code{Assertion_Policy} pragma, the identifier | |
5069 | @code{Loop_Invariant} is used to control whether it is ignored or checked | |
5070 | (or disabled). | |
64d5610f | 5071 | |
b71d4b62 RA |
5072 | @code{Loop_Invariant} can only appear as one of the items in the sequence |
5073 | of statements of a loop body, or nested inside block statements that | |
5074 | appear in the sequence of statements of a loop body. | |
5075 | The intention is that it be used to | |
5076 | represent a “loop invariant” assertion, i.e. something that is true each | |
5077 | time through the loop, and which can be used to show that the loop is | |
5078 | achieving its purpose. | |
64d5610f | 5079 | |
b71d4b62 RA |
5080 | Multiple @code{Loop_Invariant} and @code{Loop_Variant} pragmas that |
5081 | apply to the same loop should be grouped in the same sequence of | |
5082 | statements. | |
64d5610f | 5083 | |
b71d4b62 RA |
5084 | To aid in writing such invariants, the special attribute @code{Loop_Entry} |
5085 | may be used to refer to the value of an expression on entry to the loop. This | |
5086 | attribute can only be used within the expression of a @code{Loop_Invariant} | |
5087 | pragma. For full details, see documentation of attribute @code{Loop_Entry}. | |
64d5610f | 5088 | |
b71d4b62 RA |
5089 | @node Pragma Loop_Optimize,Pragma Loop_Variant,Pragma Loop_Invariant,Implementation Defined Pragmas |
5090 | @anchor{gnat_rm/implementation_defined_pragmas pragma-loop-optimize}@anchor{99} | |
5091 | @section Pragma Loop_Optimize | |
64d5610f ML |
5092 | |
5093 | ||
5094 | Syntax: | |
5095 | ||
5096 | @example | |
b71d4b62 RA |
5097 | pragma Loop_Optimize (OPTIMIZATION_HINT @{, OPTIMIZATION_HINT@}); |
5098 | ||
5099 | OPTIMIZATION_HINT ::= Ivdep | No_Unroll | Unroll | No_Vector | Vector | |
64d5610f ML |
5100 | @end example |
5101 | ||
b71d4b62 RA |
5102 | This pragma must appear immediately within a loop statement. It allows the |
5103 | programmer to specify optimization hints for the enclosing loop. The hints | |
5104 | are not mutually exclusive and can be freely mixed, but not all combinations | |
5105 | will yield a sensible outcome. | |
64d5610f | 5106 | |
b71d4b62 | 5107 | There are five supported optimization hints for a loop: |
64d5610f | 5108 | |
64d5610f | 5109 | |
b71d4b62 | 5110 | @itemize * |
64d5610f | 5111 | |
b71d4b62 RA |
5112 | @item |
5113 | Ivdep | |
64d5610f | 5114 | |
b71d4b62 RA |
5115 | The programmer asserts that there are no loop-carried dependencies |
5116 | which would prevent consecutive iterations of the loop from being | |
5117 | executed simultaneously. | |
64d5610f | 5118 | |
b71d4b62 RA |
5119 | @item |
5120 | No_Unroll | |
64d5610f | 5121 | |
b71d4b62 RA |
5122 | The loop must not be unrolled. This is a strong hint: the compiler will not |
5123 | unroll a loop marked with this hint. | |
64d5610f | 5124 | |
b71d4b62 RA |
5125 | @item |
5126 | Unroll | |
64d5610f | 5127 | |
b71d4b62 RA |
5128 | The loop should be unrolled. This is a weak hint: the compiler will try to |
5129 | apply unrolling to this loop preferably to other optimizations, notably | |
5130 | vectorization, but there is no guarantee that the loop will be unrolled. | |
64d5610f | 5131 | |
b71d4b62 RA |
5132 | @item |
5133 | No_Vector | |
64d5610f | 5134 | |
b71d4b62 RA |
5135 | The loop must not be vectorized. This is a strong hint: the compiler will not |
5136 | vectorize a loop marked with this hint. | |
64d5610f | 5137 | |
b71d4b62 RA |
5138 | @item |
5139 | Vector | |
64d5610f | 5140 | |
b71d4b62 RA |
5141 | The loop should be vectorized. This is a weak hint: the compiler will try to |
5142 | apply vectorization to this loop preferably to other optimizations, notably | |
5143 | unrolling, but there is no guarantee that the loop will be vectorized. | |
5144 | @end itemize | |
5145 | ||
5146 | These hints do not remove the need to pass the appropriate switches to the | |
5147 | compiler in order to enable the relevant optimizations, that is to say | |
1acce141 | 5148 | @emph{-funroll-loops} for unrolling and @emph{-ftree-vectorize} for |
b71d4b62 RA |
5149 | vectorization. |
5150 | ||
5151 | @node Pragma Loop_Variant,Pragma Machine_Attribute,Pragma Loop_Optimize,Implementation Defined Pragmas | |
5152 | @anchor{gnat_rm/implementation_defined_pragmas pragma-loop-variant}@anchor{9a} | |
5153 | @section Pragma Loop_Variant | |
64d5610f ML |
5154 | |
5155 | ||
5156 | Syntax: | |
5157 | ||
5158 | @example | |
b71d4b62 RA |
5159 | pragma Loop_Variant ( LOOP_VARIANT_ITEM @{, LOOP_VARIANT_ITEM @} ); |
5160 | LOOP_VARIANT_ITEM ::= CHANGE_DIRECTION => discrete_EXPRESSION | |
5161 | CHANGE_DIRECTION ::= Increases | Decreases | |
64d5610f ML |
5162 | @end example |
5163 | ||
b71d4b62 RA |
5164 | @code{Loop_Variant} can only appear as one of the items in the sequence |
5165 | of statements of a loop body, or nested inside block statements that | |
5166 | appear in the sequence of statements of a loop body. | |
5167 | It allows the specification of quantities which must always | |
5168 | decrease or increase in successive iterations of the loop. In its simplest | |
5169 | form, just one expression is specified, whose value must increase or decrease | |
5170 | on each iteration of the loop. | |
64d5610f | 5171 | |
b71d4b62 RA |
5172 | In a more complex form, multiple arguments can be given which are interpreted |
5173 | in a nesting lexicographic manner. For example: | |
64d5610f | 5174 | |
b71d4b62 RA |
5175 | @example |
5176 | pragma Loop_Variant (Increases => X, Decreases => Y); | |
5177 | @end example | |
64d5610f | 5178 | |
b71d4b62 RA |
5179 | specifies that each time through the loop either X increases, or X stays |
5180 | the same and Y decreases. A @code{Loop_Variant} pragma ensures that the | |
5181 | loop is making progress. It can be useful in helping to show informally | |
5182 | or prove formally that the loop always terminates. | |
5183 | ||
5184 | @code{Loop_Variant} is an assertion whose effect can be controlled using | |
5185 | an @code{Assertion_Policy} with a check name of @code{Loop_Variant}. The | |
5186 | policy can be @code{Check} to enable the loop variant check, @code{Ignore} | |
5187 | to ignore the check (in which case the pragma has no effect on the program), | |
5188 | or @code{Disable} in which case the pragma is not even checked for correct | |
5189 | syntax. | |
5190 | ||
5191 | Multiple @code{Loop_Invariant} and @code{Loop_Variant} pragmas that | |
5192 | apply to the same loop should be grouped in the same sequence of | |
5193 | statements. | |
5194 | ||
5195 | The @code{Loop_Entry} attribute may be used within the expressions of the | |
5196 | @code{Loop_Variant} pragma to refer to values on entry to the loop. | |
5197 | ||
5198 | @node Pragma Machine_Attribute,Pragma Main,Pragma Loop_Variant,Implementation Defined Pragmas | |
5199 | @anchor{gnat_rm/implementation_defined_pragmas pragma-machine-attribute}@anchor{9b} | |
5200 | @section Pragma Machine_Attribute | |
64d5610f ML |
5201 | |
5202 | ||
5203 | Syntax: | |
5204 | ||
5205 | @example | |
b71d4b62 RA |
5206 | pragma Machine_Attribute ( |
5207 | [Entity =>] LOCAL_NAME, | |
5208 | [Attribute_Name =>] static_string_EXPRESSION | |
5209 | [, [Info =>] static_EXPRESSION @{, static_EXPRESSION@}] ); | |
64d5610f ML |
5210 | @end example |
5211 | ||
b71d4b62 RA |
5212 | Machine-dependent attributes can be specified for types and/or |
5213 | declarations. This pragma is semantically equivalent to | |
1acce141 YM |
5214 | @code{__attribute__((@emph{attribute_name}))} (if @code{info} is not |
5215 | specified) or @code{__attribute__((@emph{attribute_name(info})))} | |
5216 | or @code{__attribute__((@emph{attribute_name(info,...})))} in GNU C, | |
5217 | where @emph{attribute_name} is recognized by the compiler middle-end | |
b71d4b62 RA |
5218 | or the @code{TARGET_ATTRIBUTE_TABLE} machine specific macro. Note |
5219 | that a string literal for the optional parameter @code{info} or the | |
5220 | following ones is transformed by default into an identifier, | |
5221 | which may make this pragma unusable for some attributes. | |
5222 | For further information see @cite{GNU Compiler Collection (GCC) Internals}. | |
64d5610f | 5223 | |
b71d4b62 RA |
5224 | @node Pragma Main,Pragma Main_Storage,Pragma Machine_Attribute,Implementation Defined Pragmas |
5225 | @anchor{gnat_rm/implementation_defined_pragmas pragma-main}@anchor{9c} | |
5226 | @section Pragma Main | |
64d5610f ML |
5227 | |
5228 | ||
5229 | Syntax: | |
5230 | ||
5231 | @example | |
b71d4b62 RA |
5232 | pragma Main |
5233 | (MAIN_OPTION [, MAIN_OPTION]); | |
64d5610f | 5234 | |
b71d4b62 RA |
5235 | MAIN_OPTION ::= |
5236 | [Stack_Size =>] static_integer_EXPRESSION | |
5237 | | [Task_Stack_Size_Default =>] static_integer_EXPRESSION | |
5238 | | [Time_Slicing_Enabled =>] static_boolean_EXPRESSION | |
5239 | @end example | |
64d5610f | 5240 | |
b71d4b62 RA |
5241 | This pragma is provided for compatibility with OpenVMS VAX Systems. It has |
5242 | no effect in GNAT, other than being syntax checked. | |
64d5610f | 5243 | |
b71d4b62 RA |
5244 | @node Pragma Main_Storage,Pragma Max_Queue_Length,Pragma Main,Implementation Defined Pragmas |
5245 | @anchor{gnat_rm/implementation_defined_pragmas pragma-main-storage}@anchor{9d} | |
5246 | @section Pragma Main_Storage | |
64d5610f | 5247 | |
64d5610f | 5248 | |
b71d4b62 | 5249 | Syntax: |
64d5610f | 5250 | |
b71d4b62 RA |
5251 | @example |
5252 | pragma Main_Storage | |
5253 | (MAIN_STORAGE_OPTION [, MAIN_STORAGE_OPTION]); | |
64d5610f | 5254 | |
b71d4b62 RA |
5255 | MAIN_STORAGE_OPTION ::= |
5256 | [WORKING_STORAGE =>] static_SIMPLE_EXPRESSION | |
5257 | | [TOP_GUARD =>] static_SIMPLE_EXPRESSION | |
5258 | @end example | |
64d5610f | 5259 | |
b71d4b62 RA |
5260 | This pragma is provided for compatibility with OpenVMS VAX Systems. It has |
5261 | no effect in GNAT, other than being syntax checked. | |
64d5610f | 5262 | |
b71d4b62 RA |
5263 | @node Pragma Max_Queue_Length,Pragma No_Body,Pragma Main_Storage,Implementation Defined Pragmas |
5264 | @anchor{gnat_rm/implementation_defined_pragmas id23}@anchor{9e}@anchor{gnat_rm/implementation_defined_pragmas pragma-max-queue-length}@anchor{9f} | |
5265 | @section Pragma Max_Queue_Length | |
64d5610f | 5266 | |
64d5610f | 5267 | |
b71d4b62 | 5268 | Syntax: |
64d5610f | 5269 | |
b71d4b62 RA |
5270 | @example |
5271 | pragma Max_Entry_Queue (static_integer_EXPRESSION); | |
64d5610f ML |
5272 | @end example |
5273 | ||
b71d4b62 RA |
5274 | This pragma is used to specify the maximum callers per entry queue for |
5275 | individual protected entries and entry families. It accepts a single | |
5276 | integer (-1 or more) as a parameter and must appear after the declaration of an | |
5277 | entry. | |
64d5610f | 5278 | |
b71d4b62 | 5279 | A value of -1 represents no additional restriction on queue length. |
64d5610f | 5280 | |
b71d4b62 RA |
5281 | @node Pragma No_Body,Pragma No_Caching,Pragma Max_Queue_Length,Implementation Defined Pragmas |
5282 | @anchor{gnat_rm/implementation_defined_pragmas pragma-no-body}@anchor{a0} | |
5283 | @section Pragma No_Body | |
64d5610f ML |
5284 | |
5285 | ||
b71d4b62 | 5286 | Syntax: |
64d5610f | 5287 | |
b71d4b62 RA |
5288 | @example |
5289 | pragma No_Body; | |
5290 | @end example | |
64d5610f | 5291 | |
b71d4b62 RA |
5292 | There are a number of cases in which a package spec does not require a body, |
5293 | and in fact a body is not permitted. GNAT will not permit the spec to be | |
5294 | compiled if there is a body around. The pragma No_Body allows you to provide | |
5295 | a body file, even in a case where no body is allowed. The body file must | |
5296 | contain only comments and a single No_Body pragma. This is recognized by | |
5297 | the compiler as indicating that no body is logically present. | |
64d5610f | 5298 | |
b71d4b62 RA |
5299 | This is particularly useful during maintenance when a package is modified in |
5300 | such a way that a body needed before is no longer needed. The provision of a | |
5301 | dummy body with a No_Body pragma ensures that there is no interference from | |
5302 | earlier versions of the package body. | |
64d5610f | 5303 | |
b71d4b62 RA |
5304 | @node Pragma No_Caching,Pragma No_Component_Reordering,Pragma No_Body,Implementation Defined Pragmas |
5305 | @anchor{gnat_rm/implementation_defined_pragmas id24}@anchor{a1}@anchor{gnat_rm/implementation_defined_pragmas pragma-no-caching}@anchor{a2} | |
5306 | @section Pragma No_Caching | |
64d5610f | 5307 | |
64d5610f | 5308 | |
b71d4b62 | 5309 | Syntax: |
64d5610f | 5310 | |
b71d4b62 RA |
5311 | @example |
5312 | pragma No_Caching [ (static_boolean_EXPRESSION) ]; | |
5313 | @end example | |
64d5610f | 5314 | |
b71d4b62 RA |
5315 | For the semantics of this pragma, see the entry for aspect @code{No_Caching} in |
5316 | the SPARK 2014 Reference Manual, section 7.1.2. | |
64d5610f | 5317 | |
b71d4b62 RA |
5318 | @node Pragma No_Component_Reordering,Pragma No_Elaboration_Code_All,Pragma No_Caching,Implementation Defined Pragmas |
5319 | @anchor{gnat_rm/implementation_defined_pragmas pragma-no-component-reordering}@anchor{a3} | |
5320 | @section Pragma No_Component_Reordering | |
64d5610f | 5321 | |
64d5610f | 5322 | |
b71d4b62 | 5323 | Syntax: |
64d5610f | 5324 | |
b71d4b62 RA |
5325 | @example |
5326 | pragma No_Component_Reordering [([Entity =>] type_LOCAL_NAME)]; | |
5327 | @end example | |
64d5610f | 5328 | |
b71d4b62 RA |
5329 | @code{type_LOCAL_NAME} must refer to a record type declaration in the current |
5330 | declarative part. The effect is to preclude any reordering of components | |
5331 | for the layout of the record, i.e. the record is laid out by the compiler | |
5332 | in the order in which the components are declared textually. The form with | |
5333 | no argument is a configuration pragma which applies to all record types | |
5334 | declared in units to which the pragma applies and there is a requirement | |
5335 | that this pragma be used consistently within a partition. | |
64d5610f | 5336 | |
b71d4b62 RA |
5337 | @node Pragma No_Elaboration_Code_All,Pragma No_Heap_Finalization,Pragma No_Component_Reordering,Implementation Defined Pragmas |
5338 | @anchor{gnat_rm/implementation_defined_pragmas id25}@anchor{a4}@anchor{gnat_rm/implementation_defined_pragmas pragma-no-elaboration-code-all}@anchor{a5} | |
5339 | @section Pragma No_Elaboration_Code_All | |
64d5610f ML |
5340 | |
5341 | ||
5342 | Syntax: | |
5343 | ||
5344 | @example | |
b71d4b62 | 5345 | pragma No_Elaboration_Code_All [(program_unit_NAME)]; |
64d5610f ML |
5346 | @end example |
5347 | ||
b71d4b62 RA |
5348 | This is a program unit pragma (there is also an equivalent aspect of the |
5349 | same name) that establishes the restriction @code{No_Elaboration_Code} for | |
5350 | the current unit and any extended main source units (body and subunits). | |
5351 | It also has the effect of enforcing a transitive application of this | |
5352 | aspect, so that if any unit is implicitly or explicitly with’ed by the | |
5353 | current unit, it must also have the No_Elaboration_Code_All aspect set. | |
5354 | It may be applied to package or subprogram specs or their generic versions. | |
64d5610f | 5355 | |
b71d4b62 RA |
5356 | @node Pragma No_Heap_Finalization,Pragma No_Inline,Pragma No_Elaboration_Code_All,Implementation Defined Pragmas |
5357 | @anchor{gnat_rm/implementation_defined_pragmas pragma-no-heap-finalization}@anchor{a6} | |
5358 | @section Pragma No_Heap_Finalization | |
64d5610f ML |
5359 | |
5360 | ||
5361 | Syntax: | |
5362 | ||
5363 | @example | |
b71d4b62 | 5364 | pragma No_Heap_Finalization [ (first_subtype_LOCAL_NAME) ]; |
64d5610f ML |
5365 | @end example |
5366 | ||
b71d4b62 RA |
5367 | Pragma @code{No_Heap_Finalization} may be used as a configuration pragma or as a |
5368 | type-specific pragma. | |
64d5610f | 5369 | |
b71d4b62 RA |
5370 | In its configuration form, the pragma must appear within a configuration file |
5371 | such as gnat.adc, without an argument. The pragma suppresses the call to | |
5372 | @code{Finalize} for heap-allocated objects created through library-level named | |
5373 | access-to-object types in cases where the designated type requires finalization | |
5374 | actions. | |
64d5610f | 5375 | |
b71d4b62 RA |
5376 | In its type-specific form, the argument of the pragma must denote a |
5377 | library-level named access-to-object type. The pragma suppresses the call to | |
5378 | @code{Finalize} for heap-allocated objects created through the specific access type | |
5379 | in cases where the designated type requires finalization actions. | |
64d5610f | 5380 | |
b71d4b62 RA |
5381 | It is still possible to finalize such heap-allocated objects by explicitly |
5382 | deallocating them. | |
64d5610f | 5383 | |
b71d4b62 RA |
5384 | A library-level named access-to-object type declared within a generic unit will |
5385 | lose its @code{No_Heap_Finalization} pragma when the corresponding instance does not | |
5386 | appear at the library level. | |
64d5610f | 5387 | |
b71d4b62 RA |
5388 | @node Pragma No_Inline,Pragma No_Return,Pragma No_Heap_Finalization,Implementation Defined Pragmas |
5389 | @anchor{gnat_rm/implementation_defined_pragmas id26}@anchor{a7}@anchor{gnat_rm/implementation_defined_pragmas pragma-no-inline}@anchor{a8} | |
5390 | @section Pragma No_Inline | |
64d5610f ML |
5391 | |
5392 | ||
5393 | Syntax: | |
5394 | ||
5395 | @example | |
b71d4b62 | 5396 | pragma No_Inline (NAME @{, NAME@}); |
64d5610f ML |
5397 | @end example |
5398 | ||
b71d4b62 RA |
5399 | This pragma suppresses inlining for the callable entity or the instances of |
5400 | the generic subprogram designated by @code{NAME}, including inlining that | |
5401 | results from the use of pragma @code{Inline}. This pragma is always active, | |
1acce141 YM |
5402 | in particular it is not subject to the use of option @emph{-gnatn} or |
5403 | @emph{-gnatN}. It is illegal to specify both pragma @code{No_Inline} and | |
b71d4b62 RA |
5404 | pragma @code{Inline_Always} for the same @code{NAME}. |
5405 | ||
5406 | @node Pragma No_Return,Pragma No_Strict_Aliasing,Pragma No_Inline,Implementation Defined Pragmas | |
5407 | @anchor{gnat_rm/implementation_defined_pragmas pragma-no-return}@anchor{a9} | |
5408 | @section Pragma No_Return | |
64d5610f | 5409 | |
b71d4b62 RA |
5410 | |
5411 | Syntax: | |
64d5610f ML |
5412 | |
5413 | @example | |
b71d4b62 | 5414 | pragma No_Return (procedure_LOCAL_NAME @{, procedure_LOCAL_NAME@}); |
64d5610f ML |
5415 | @end example |
5416 | ||
b71d4b62 RA |
5417 | Each @code{procedure_LOCAL_NAME} argument must refer to one or more procedure |
5418 | declarations in the current declarative part. A procedure to which this | |
5419 | pragma is applied may not contain any explicit @code{return} statements. | |
5420 | In addition, if the procedure contains any implicit returns from falling | |
5421 | off the end of a statement sequence, then execution of that implicit | |
5422 | return will cause Program_Error to be raised. | |
64d5610f | 5423 | |
b71d4b62 RA |
5424 | One use of this pragma is to identify procedures whose only purpose is to raise |
5425 | an exception. Another use of this pragma is to suppress incorrect warnings | |
5426 | about missing returns in functions, where the last statement of a function | |
5427 | statement sequence is a call to such a procedure. | |
64d5610f | 5428 | |
b71d4b62 RA |
5429 | Note that in Ada 2005 mode, this pragma is part of the language. It is |
5430 | available in all earlier versions of Ada as an implementation-defined | |
5431 | pragma. | |
64d5610f | 5432 | |
b71d4b62 RA |
5433 | @node Pragma No_Strict_Aliasing,Pragma No_Tagged_Streams,Pragma No_Return,Implementation Defined Pragmas |
5434 | @anchor{gnat_rm/implementation_defined_pragmas pragma-no-strict-aliasing}@anchor{aa} | |
5435 | @section Pragma No_Strict_Aliasing | |
64d5610f ML |
5436 | |
5437 | ||
5438 | Syntax: | |
5439 | ||
5440 | @example | |
b71d4b62 | 5441 | pragma No_Strict_Aliasing [([Entity =>] type_LOCAL_NAME)]; |
64d5610f ML |
5442 | @end example |
5443 | ||
b71d4b62 RA |
5444 | @code{type_LOCAL_NAME} must refer to an access type |
5445 | declaration in the current declarative part. The effect is to inhibit | |
5446 | strict aliasing optimization for the given type. The form with no | |
5447 | arguments is a configuration pragma which applies to all access types | |
5448 | declared in units to which the pragma applies. For a detailed | |
5449 | description of the strict aliasing optimization, and the situations | |
5450 | in which it must be suppressed, see the section on Optimization and Strict Aliasing | |
5451 | in the @cite{GNAT User’s Guide}. | |
64d5610f | 5452 | |
b71d4b62 RA |
5453 | This pragma currently has no effects on access to unconstrained array types. |
5454 | ||
5455 | @node Pragma No_Tagged_Streams,Pragma Normalize_Scalars,Pragma No_Strict_Aliasing,Implementation Defined Pragmas | |
5456 | @anchor{gnat_rm/implementation_defined_pragmas id27}@anchor{ab}@anchor{gnat_rm/implementation_defined_pragmas pragma-no-tagged-streams}@anchor{ac} | |
5457 | @section Pragma No_Tagged_Streams | |
64d5610f ML |
5458 | |
5459 | ||
5460 | Syntax: | |
5461 | ||
5462 | @example | |
b71d4b62 | 5463 | pragma No_Tagged_Streams [([Entity =>] tagged_type_LOCAL_NAME)]; |
64d5610f ML |
5464 | @end example |
5465 | ||
b71d4b62 RA |
5466 | Normally when a tagged type is introduced using a full type declaration, |
5467 | part of the processing includes generating stream access routines to be | |
5468 | used by stream attributes referencing the type (or one of its subtypes | |
5469 | or derived types). This can involve the generation of significant amounts | |
5470 | of code which is wasted space if stream routines are not needed for the | |
5471 | type in question. | |
64d5610f | 5472 | |
b71d4b62 RA |
5473 | The @code{No_Tagged_Streams} pragma causes the generation of these stream |
5474 | routines to be skipped, and any attempt to use stream operations on | |
5475 | types subject to this pragma will be statically rejected as illegal. | |
64d5610f | 5476 | |
b71d4b62 RA |
5477 | There are two forms of the pragma. The form with no arguments must appear |
5478 | in a declarative sequence or in the declarations of a package spec. This | |
5479 | pragma affects all subsequent root tagged types declared in the declaration | |
5480 | sequence, and specifies that no stream routines be generated. The form with | |
5481 | an argument (for which there is also a corresponding aspect) specifies a | |
5482 | single root tagged type for which stream routines are not to be generated. | |
64d5610f | 5483 | |
b71d4b62 RA |
5484 | Once the pragma has been given for a particular root tagged type, all subtypes |
5485 | and derived types of this type inherit the pragma automatically, so the effect | |
5486 | applies to a complete hierarchy (this is necessary to deal with the class-wide | |
5487 | dispatching versions of the stream routines). | |
64d5610f | 5488 | |
b71d4b62 RA |
5489 | When pragmas @code{Discard_Names} and @code{No_Tagged_Streams} are simultaneously |
5490 | applied to a tagged type its Expanded_Name and External_Tag are initialized | |
5491 | with empty strings. This is useful to avoid exposing entity names at binary | |
5492 | level but has a negative impact on the debuggability of tagged types. | |
64d5610f | 5493 | |
b71d4b62 RA |
5494 | @node Pragma Normalize_Scalars,Pragma Obsolescent,Pragma No_Tagged_Streams,Implementation Defined Pragmas |
5495 | @anchor{gnat_rm/implementation_defined_pragmas pragma-normalize-scalars}@anchor{ad} | |
5496 | @section Pragma Normalize_Scalars | |
64d5610f ML |
5497 | |
5498 | ||
5499 | Syntax: | |
5500 | ||
5501 | @example | |
b71d4b62 | 5502 | pragma Normalize_Scalars; |
64d5610f ML |
5503 | @end example |
5504 | ||
b71d4b62 RA |
5505 | This is a language defined pragma which is fully implemented in GNAT. The |
5506 | effect is to cause all scalar objects that are not otherwise initialized | |
5507 | to be initialized. The initial values are implementation dependent and | |
5508 | are as follows: | |
64d5610f | 5509 | |
64d5610f | 5510 | |
b71d4b62 | 5511 | @table @asis |
64d5610f | 5512 | |
1acce141 | 5513 | @item @emph{Standard.Character} |
64d5610f | 5514 | |
b71d4b62 RA |
5515 | Objects whose root type is Standard.Character are initialized to |
5516 | Character’Last unless the subtype range excludes NUL (in which case | |
5517 | NUL is used). This choice will always generate an invalid value if | |
5518 | one exists. | |
64d5610f | 5519 | |
1acce141 | 5520 | @item @emph{Standard.Wide_Character} |
64d5610f | 5521 | |
b71d4b62 RA |
5522 | Objects whose root type is Standard.Wide_Character are initialized to |
5523 | Wide_Character’Last unless the subtype range excludes NUL (in which case | |
5524 | NUL is used). This choice will always generate an invalid value if | |
5525 | one exists. | |
64d5610f | 5526 | |
1acce141 | 5527 | @item @emph{Standard.Wide_Wide_Character} |
64d5610f | 5528 | |
b71d4b62 RA |
5529 | Objects whose root type is Standard.Wide_Wide_Character are initialized to |
5530 | the invalid value 16#FFFF_FFFF# unless the subtype range excludes NUL (in | |
5531 | which case NUL is used). This choice will always generate an invalid value if | |
5532 | one exists. | |
64d5610f | 5533 | |
1acce141 | 5534 | @item @emph{Integer types} |
64d5610f | 5535 | |
b71d4b62 RA |
5536 | Objects of an integer type are treated differently depending on whether |
5537 | negative values are present in the subtype. If no negative values are | |
5538 | present, then all one bits is used as the initial value except in the | |
5539 | special case where zero is excluded from the subtype, in which case | |
5540 | all zero bits are used. This choice will always generate an invalid | |
5541 | value if one exists. | |
64d5610f | 5542 | |
b71d4b62 RA |
5543 | For subtypes with negative values present, the largest negative number |
5544 | is used, except in the unusual case where this largest negative number | |
5545 | is in the subtype, and the largest positive number is not, in which case | |
5546 | the largest positive value is used. This choice will always generate | |
5547 | an invalid value if one exists. | |
64d5610f | 5548 | |
1acce141 | 5549 | @item @emph{Floating-Point Types} |
64d5610f | 5550 | |
b71d4b62 RA |
5551 | Objects of all floating-point types are initialized to all 1-bits. For |
5552 | standard IEEE format, this corresponds to a NaN (not a number) which is | |
5553 | indeed an invalid value. | |
64d5610f | 5554 | |
1acce141 | 5555 | @item @emph{Fixed-Point Types} |
64d5610f | 5556 | |
b71d4b62 RA |
5557 | Objects of all fixed-point types are treated as described above for integers, |
5558 | with the rules applying to the underlying integer value used to represent | |
5559 | the fixed-point value. | |
64d5610f | 5560 | |
1acce141 | 5561 | @item @emph{Modular types} |
64d5610f ML |
5562 | |
5563 | Objects of a modular type are initialized to all one bits, except in | |
5564 | the special case where zero is excluded from the subtype, in which | |
5565 | case all zero bits are used. This choice will always generate an | |
5566 | invalid value if one exists. | |
5567 | ||
1acce141 | 5568 | @item @emph{Enumeration types} |
64d5610f ML |
5569 | |
5570 | Objects of an enumeration type are initialized to all one-bits, i.e., to | |
5571 | the value @code{2 ** typ'Size - 1} unless the subtype excludes the literal | |
5572 | whose Pos value is zero, in which case a code of zero is used. This choice | |
5573 | will always generate an invalid value if one exists. | |
5574 | @end table | |
5575 | ||
5576 | @node Pragma Obsolescent,Pragma Optimize_Alignment,Pragma Normalize_Scalars,Implementation Defined Pragmas | |
b71d4b62 | 5577 | @anchor{gnat_rm/implementation_defined_pragmas id28}@anchor{ae}@anchor{gnat_rm/implementation_defined_pragmas pragma-obsolescent}@anchor{af} |
64d5610f ML |
5578 | @section Pragma Obsolescent |
5579 | ||
5580 | ||
5581 | Syntax: | |
5582 | ||
5583 | @example | |
5584 | pragma Obsolescent; | |
5585 | ||
5586 | pragma Obsolescent ( | |
5587 | [Message =>] static_string_EXPRESSION | |
5588 | [,[Version =>] Ada_05]); | |
5589 | ||
5590 | pragma Obsolescent ( | |
5591 | [Entity =>] NAME | |
5592 | [,[Message =>] static_string_EXPRESSION | |
5593 | [,[Version =>] Ada_05]]); | |
5594 | @end example | |
5595 | ||
5596 | This pragma can occur immediately following a declaration of an entity, | |
5597 | including the case of a record component. If no Entity argument is present, | |
5598 | then this declaration is the one to which the pragma applies. If an Entity | |
5599 | parameter is present, it must either match the name of the entity in this | |
5600 | declaration, or alternatively, the pragma can immediately follow an enumeration | |
5601 | type declaration, where the Entity argument names one of the enumeration | |
5602 | literals. | |
5603 | ||
5604 | This pragma is used to indicate that the named entity | |
5605 | is considered obsolescent and should not be used. Typically this is | |
5606 | used when an API must be modified by eventually removing or modifying | |
5607 | existing subprograms or other entities. The pragma can be used at an | |
5608 | intermediate stage when the entity is still present, but will be | |
5609 | removed later. | |
5610 | ||
5611 | The effect of this pragma is to output a warning message on a reference to | |
5612 | an entity thus marked that the subprogram is obsolescent if the appropriate | |
5613 | warning option in the compiler is activated. If the @code{Message} parameter is | |
5614 | present, then a second warning message is given containing this text. In | |
5615 | addition, a reference to the entity is considered to be a violation of pragma | |
5616 | @code{Restrictions (No_Obsolescent_Features)}. | |
5617 | ||
5618 | This pragma can also be used as a program unit pragma for a package, | |
5619 | in which case the entity name is the name of the package, and the | |
5620 | pragma indicates that the entire package is considered | |
5621 | obsolescent. In this case a client @code{with}ing such a package | |
5622 | violates the restriction, and the @code{with} clause is | |
5623 | flagged with warnings if the warning option is set. | |
5624 | ||
5625 | If the @code{Version} parameter is present (which must be exactly | |
5626 | the identifier @code{Ada_05}, no other argument is allowed), then the | |
5627 | indication of obsolescence applies only when compiling in Ada 2005 | |
5628 | mode. This is primarily intended for dealing with the situations | |
5629 | in the predefined library where subprograms or packages | |
5630 | have become defined as obsolescent in Ada 2005 | |
5631 | (e.g., in @code{Ada.Characters.Handling}), but may be used anywhere. | |
5632 | ||
5633 | The following examples show typical uses of this pragma: | |
5634 | ||
5635 | @example | |
5636 | package p is | |
5637 | pragma Obsolescent (p, Message => "use pp instead of p"); | |
5638 | end p; | |
5639 | ||
5640 | package q is | |
5641 | procedure q2; | |
5642 | pragma Obsolescent ("use q2new instead"); | |
5643 | ||
5644 | type R is new integer; | |
5645 | pragma Obsolescent | |
5646 | (Entity => R, | |
5647 | Message => "use RR in Ada 2005", | |
5648 | Version => Ada_05); | |
5649 | ||
5650 | type M is record | |
5651 | F1 : Integer; | |
5652 | F2 : Integer; | |
5653 | pragma Obsolescent; | |
5654 | F3 : Integer; | |
5655 | end record; | |
5656 | ||
5657 | type E is (a, bc, 'd', quack); | |
5658 | pragma Obsolescent (Entity => bc) | |
5659 | pragma Obsolescent (Entity => 'd') | |
5660 | ||
5661 | function "+" | |
5662 | (a, b : character) return character; | |
5663 | pragma Obsolescent (Entity => "+"); | |
5664 | end; | |
5665 | @end example | |
5666 | ||
5667 | Note that, as for all pragmas, if you use a pragma argument identifier, | |
5668 | then all subsequent parameters must also use a pragma argument identifier. | |
5669 | So if you specify @code{Entity =>} for the @code{Entity} argument, and a @code{Message} | |
5670 | argument is present, it must be preceded by @code{Message =>}. | |
5671 | ||
5672 | @node Pragma Optimize_Alignment,Pragma Ordered,Pragma Obsolescent,Implementation Defined Pragmas | |
b71d4b62 | 5673 | @anchor{gnat_rm/implementation_defined_pragmas pragma-optimize-alignment}@anchor{b0} |
64d5610f ML |
5674 | @section Pragma Optimize_Alignment |
5675 | ||
5676 | ||
5677 | @geindex Alignment | |
5678 | @geindex default settings | |
5679 | ||
5680 | Syntax: | |
5681 | ||
5682 | @example | |
5683 | pragma Optimize_Alignment (TIME | SPACE | OFF); | |
5684 | @end example | |
5685 | ||
5686 | This is a configuration pragma which affects the choice of default alignments | |
5687 | for types and objects where no alignment is explicitly specified. There is a | |
5688 | time/space trade-off in the selection of these values. Large alignments result | |
5689 | in more efficient code, at the expense of larger data space, since sizes have | |
5690 | to be increased to match these alignments. Smaller alignments save space, but | |
5691 | the access code is slower. The normal choice of default alignments for types | |
5692 | and individual alignment promotions for objects (which is what you get if you | |
5693 | do not use this pragma, or if you use an argument of OFF), tries to balance | |
5694 | these two requirements. | |
5695 | ||
5696 | Specifying SPACE causes smaller default alignments to be chosen in two cases. | |
5697 | First any packed record is given an alignment of 1. Second, if a size is given | |
5698 | for the type, then the alignment is chosen to avoid increasing this size. For | |
5699 | example, consider: | |
5700 | ||
5701 | @example | |
5702 | type R is record | |
5703 | X : Integer; | |
5704 | Y : Character; | |
5705 | end record; | |
5706 | ||
5707 | for R'Size use 5*8; | |
5708 | @end example | |
5709 | ||
5710 | In the default mode, this type gets an alignment of 4, so that access to the | |
5711 | Integer field X are efficient. But this means that objects of the type end up | |
5712 | with a size of 8 bytes. This is a valid choice, since sizes of objects are | |
5713 | allowed to be bigger than the size of the type, but it can waste space if for | |
5714 | example fields of type R appear in an enclosing record. If the above type is | |
5715 | compiled in @code{Optimize_Alignment (Space)} mode, the alignment is set to 1. | |
5716 | ||
5717 | However, there is one case in which SPACE is ignored. If a variable length | |
5718 | record (that is a discriminated record with a component which is an array | |
5719 | whose length depends on a discriminant), has a pragma Pack, then it is not | |
5720 | in general possible to set the alignment of such a record to one, so the | |
5721 | pragma is ignored in this case (with a warning). | |
5722 | ||
5723 | Specifying SPACE also disables alignment promotions for standalone objects, | |
5724 | which occur when the compiler increases the alignment of a specific object | |
5725 | without changing the alignment of its type. | |
5726 | ||
5727 | Specifying SPACE also disables component reordering in unpacked record types, | |
5728 | which can result in larger sizes in order to meet alignment requirements. | |
5729 | ||
5730 | Specifying TIME causes larger default alignments to be chosen in the case of | |
5731 | small types with sizes that are not a power of 2. For example, consider: | |
5732 | ||
5733 | @example | |
5734 | type R is record | |
5735 | A : Character; | |
5736 | B : Character; | |
5737 | C : Boolean; | |
5738 | end record; | |
5739 | ||
5740 | pragma Pack (R); | |
5741 | for R'Size use 17; | |
5742 | @end example | |
5743 | ||
5744 | The default alignment for this record is normally 1, but if this type is | |
5745 | compiled in @code{Optimize_Alignment (Time)} mode, then the alignment is set | |
5746 | to 4, which wastes space for objects of the type, since they are now 4 bytes | |
5747 | long, but results in more efficient access when the whole record is referenced. | |
5748 | ||
5749 | As noted above, this is a configuration pragma, and there is a requirement | |
5750 | that all units in a partition be compiled with a consistent setting of the | |
5751 | optimization setting. This would normally be achieved by use of a configuration | |
5752 | pragma file containing the appropriate setting. The exception to this rule is | |
5753 | that units with an explicit configuration pragma in the same file as the source | |
5754 | unit are excluded from the consistency check, as are all predefined units. The | |
5755 | latter are compiled by default in pragma Optimize_Alignment (Off) mode if no | |
5756 | pragma appears at the start of the file. | |
5757 | ||
5758 | @node Pragma Ordered,Pragma Overflow_Mode,Pragma Optimize_Alignment,Implementation Defined Pragmas | |
b71d4b62 | 5759 | @anchor{gnat_rm/implementation_defined_pragmas pragma-ordered}@anchor{b1} |
64d5610f ML |
5760 | @section Pragma Ordered |
5761 | ||
5762 | ||
5763 | Syntax: | |
5764 | ||
5765 | @example | |
5766 | pragma Ordered (enumeration_first_subtype_LOCAL_NAME); | |
5767 | @end example | |
5768 | ||
5769 | Most enumeration types are from a conceptual point of view unordered. | |
5770 | For example, consider: | |
5771 | ||
5772 | @example | |
5773 | type Color is (Red, Blue, Green, Yellow); | |
5774 | @end example | |
5775 | ||
5776 | By Ada semantics @code{Blue > Red} and @code{Green > Blue}, | |
5777 | but really these relations make no sense; the enumeration type merely | |
5778 | specifies a set of possible colors, and the order is unimportant. | |
5779 | ||
5780 | For unordered enumeration types, it is generally a good idea if | |
5781 | clients avoid comparisons (other than equality or inequality) and | |
1acce141 | 5782 | explicit ranges. (A @emph{client} is a unit where the type is referenced, |
64d5610f ML |
5783 | other than the unit where the type is declared, its body, and its subunits.) |
5784 | For example, if code buried in some client says: | |
5785 | ||
5786 | @example | |
5787 | if Current_Color < Yellow then ... | |
5788 | if Current_Color in Blue .. Green then ... | |
5789 | @end example | |
5790 | ||
5791 | then the client code is relying on the order, which is undesirable. | |
5792 | It makes the code hard to read and creates maintenance difficulties if | |
5793 | entries have to be added to the enumeration type. Instead, | |
5794 | the code in the client should list the possibilities, or an | |
5795 | appropriate subtype should be declared in the unit that declares | |
5796 | the original enumeration type. E.g., the following subtype could | |
5797 | be declared along with the type @code{Color}: | |
5798 | ||
5799 | @example | |
5800 | subtype RBG is Color range Red .. Green; | |
5801 | @end example | |
5802 | ||
5803 | and then the client could write: | |
5804 | ||
5805 | @example | |
5806 | if Current_Color in RBG then ... | |
5807 | if Current_Color = Blue or Current_Color = Green then ... | |
5808 | @end example | |
5809 | ||
5810 | However, some enumeration types are legitimately ordered from a conceptual | |
5811 | point of view. For example, if you declare: | |
5812 | ||
5813 | @example | |
5814 | type Day is (Mon, Tue, Wed, Thu, Fri, Sat, Sun); | |
5815 | @end example | |
5816 | ||
5817 | then the ordering imposed by the language is reasonable, and | |
5818 | clients can depend on it, writing for example: | |
5819 | ||
5820 | @example | |
5821 | if D in Mon .. Fri then ... | |
5822 | if D < Wed then ... | |
5823 | @end example | |
5824 | ||
1acce141 | 5825 | The pragma @emph{Ordered} is provided to mark enumeration types that |
64d5610f ML |
5826 | are conceptually ordered, alerting the reader that clients may depend |
5827 | on the ordering. GNAT provides a pragma to mark enumerations as ordered | |
5828 | rather than one to mark them as unordered, since in our experience, | |
5829 | the great majority of enumeration types are conceptually unordered. | |
5830 | ||
5831 | The types @code{Boolean}, @code{Character}, @code{Wide_Character}, | |
5832 | and @code{Wide_Wide_Character} | |
5833 | are considered to be ordered types, so each is declared with a | |
5834 | pragma @code{Ordered} in package @code{Standard}. | |
5835 | ||
5836 | Normally pragma @code{Ordered} serves only as documentation and a guide for | |
1acce141 | 5837 | coding standards, but GNAT provides a warning switch @emph{-gnatw.u} that |
64d5610f ML |
5838 | requests warnings for inappropriate uses (comparisons and explicit |
5839 | subranges) for unordered types. If this switch is used, then any | |
5840 | enumeration type not marked with pragma @code{Ordered} will be considered | |
5841 | as unordered, and will generate warnings for inappropriate uses. | |
5842 | ||
5843 | Note that generic types are not considered ordered or unordered (since the | |
5844 | template can be instantiated for both cases), so we never generate warnings | |
5845 | for the case of generic enumerated types. | |
5846 | ||
5847 | For additional information please refer to the description of the | |
1acce141 | 5848 | @emph{-gnatw.u} switch in the GNAT User’s Guide. |
64d5610f ML |
5849 | |
5850 | @node Pragma Overflow_Mode,Pragma Overriding_Renamings,Pragma Ordered,Implementation Defined Pragmas | |
b71d4b62 | 5851 | @anchor{gnat_rm/implementation_defined_pragmas pragma-overflow-mode}@anchor{b2} |
64d5610f ML |
5852 | @section Pragma Overflow_Mode |
5853 | ||
5854 | ||
5855 | Syntax: | |
5856 | ||
5857 | @example | |
5858 | pragma Overflow_Mode | |
5859 | ( [General =>] MODE | |
5860 | [,[Assertions =>] MODE]); | |
5861 | ||
5862 | MODE ::= STRICT | MINIMIZED | ELIMINATED | |
5863 | @end example | |
5864 | ||
5865 | This pragma sets the current overflow mode to the given setting. For details | |
5866 | of the meaning of these modes, please refer to the | |
5867 | ‘Overflow Check Handling in GNAT’ appendix in the | |
5868 | GNAT User’s Guide. If only the @code{General} parameter is present, | |
5869 | the given mode applies to all expressions. If both parameters are present, | |
5870 | the @code{General} mode applies to expressions outside assertions, and | |
5871 | the @code{Eliminated} mode applies to expressions within assertions. | |
5872 | ||
5873 | The case of the @code{MODE} parameter is ignored, | |
5874 | so @code{MINIMIZED}, @code{Minimized} and | |
5875 | @code{minimized} all have the same effect. | |
5876 | ||
5877 | The @code{Overflow_Mode} pragma has the same scoping and placement | |
5878 | rules as pragma @code{Suppress}, so it can occur either as a | |
5879 | configuration pragma, specifying a default for the whole | |
5880 | program, or in a declarative scope, where it applies to the | |
5881 | remaining declarations and statements in that scope. | |
5882 | ||
5883 | The pragma @code{Suppress (Overflow_Check)} suppresses | |
5884 | overflow checking, but does not affect the overflow mode. | |
5885 | ||
5886 | The pragma @code{Unsuppress (Overflow_Check)} unsuppresses (enables) | |
5887 | overflow checking, but does not affect the overflow mode. | |
5888 | ||
6f089469 | 5889 | @node Pragma Overriding_Renamings,Pragma Part_Of,Pragma Overflow_Mode,Implementation Defined Pragmas |
b71d4b62 | 5890 | @anchor{gnat_rm/implementation_defined_pragmas pragma-overriding-renamings}@anchor{b3} |
64d5610f ML |
5891 | @section Pragma Overriding_Renamings |
5892 | ||
5893 | ||
5894 | @geindex Rational profile | |
5895 | ||
5896 | @geindex Rational compatibility | |
5897 | ||
5898 | Syntax: | |
5899 | ||
5900 | @example | |
5901 | pragma Overriding_Renamings; | |
5902 | @end example | |
5903 | ||
5904 | This is a GNAT configuration pragma to simplify porting | |
5905 | legacy code accepted by the Rational | |
5906 | Ada compiler. In the presence of this pragma, a renaming declaration that | |
5907 | renames an inherited operation declared in the same scope is legal if selected | |
5908 | notation is used as in: | |
5909 | ||
5910 | @example | |
5911 | pragma Overriding_Renamings; | |
5912 | ... | |
5913 | package R is | |
5914 | function F (..); | |
5915 | ... | |
5916 | function F (..) renames R.F; | |
5917 | end R; | |
5918 | @end example | |
5919 | ||
5920 | even though | |
5921 | RM 8.3 (15) stipulates that an overridden operation is not visible within the | |
5922 | declaration of the overriding operation. | |
5923 | ||
6f089469 | 5924 | @node Pragma Part_Of,Pragma Partition_Elaboration_Policy,Pragma Overriding_Renamings,Implementation Defined Pragmas |
b71d4b62 | 5925 | @anchor{gnat_rm/implementation_defined_pragmas id29}@anchor{b4}@anchor{gnat_rm/implementation_defined_pragmas pragma-part-of}@anchor{b5} |
6f089469 | 5926 | @section Pragma Part_Of |
64d5610f ML |
5927 | |
5928 | ||
5929 | Syntax: | |
5930 | ||
5931 | @example | |
6f089469 | 5932 | pragma Part_Of (ABSTRACT_STATE); |
64d5610f | 5933 | |
6f089469 | 5934 | ABSTRACT_STATE ::= NAME |
64d5610f ML |
5935 | @end example |
5936 | ||
6f089469 RD |
5937 | For the semantics of this pragma, see the entry for aspect @code{Part_Of} in the |
5938 | SPARK 2014 Reference Manual, section 7.2.6. | |
64d5610f | 5939 | |
6f089469 | 5940 | @node Pragma Partition_Elaboration_Policy,Pragma Passive,Pragma Part_Of,Implementation Defined Pragmas |
b71d4b62 | 5941 | @anchor{gnat_rm/implementation_defined_pragmas pragma-partition-elaboration-policy}@anchor{b6} |
6f089469 | 5942 | @section Pragma Partition_Elaboration_Policy |
64d5610f ML |
5943 | |
5944 | ||
5945 | Syntax: | |
5946 | ||
5947 | @example | |
6f089469 | 5948 | pragma Partition_Elaboration_Policy (POLICY_IDENTIFIER); |
64d5610f | 5949 | |
6f089469 | 5950 | POLICY_IDENTIFIER ::= Concurrent | Sequential |
64d5610f ML |
5951 | @end example |
5952 | ||
6f089469 RD |
5953 | This pragma is standard in Ada 2005, but is available in all earlier |
5954 | versions of Ada as an implementation-defined pragma. | |
5955 | See Ada 2012 Reference Manual for details. | |
64d5610f | 5956 | |
6f089469 | 5957 | @node Pragma Passive,Pragma Persistent_BSS,Pragma Partition_Elaboration_Policy,Implementation Defined Pragmas |
b71d4b62 | 5958 | @anchor{gnat_rm/implementation_defined_pragmas pragma-passive}@anchor{b7} |
64d5610f ML |
5959 | @section Pragma Passive |
5960 | ||
5961 | ||
5962 | Syntax: | |
5963 | ||
5964 | @example | |
5965 | pragma Passive [(Semaphore | No)]; | |
5966 | @end example | |
5967 | ||
5968 | Syntax checked, but otherwise ignored by GNAT. This is recognized for | |
5969 | compatibility with DEC Ada 83 implementations, where it is used within a | |
5970 | task definition to request that a task be made passive. If the argument | |
5971 | @code{Semaphore} is present, or the argument is omitted, then DEC Ada 83 | |
5972 | treats the pragma as an assertion that the containing task is passive | |
5973 | and that optimization of context switch with this task is permitted and | |
5974 | desired. If the argument @code{No} is present, the task must not be | |
5975 | optimized. GNAT does not attempt to optimize any tasks in this manner | |
5976 | (since protected objects are available in place of passive tasks). | |
5977 | ||
5978 | For more information on the subject of passive tasks, see the section | |
5979 | ‘Passive Task Optimization’ in the GNAT Users Guide. | |
5980 | ||
5981 | @node Pragma Persistent_BSS,Pragma Post,Pragma Passive,Implementation Defined Pragmas | |
b71d4b62 | 5982 | @anchor{gnat_rm/implementation_defined_pragmas id30}@anchor{b8}@anchor{gnat_rm/implementation_defined_pragmas pragma-persistent-bss}@anchor{b9} |
64d5610f ML |
5983 | @section Pragma Persistent_BSS |
5984 | ||
5985 | ||
5986 | Syntax: | |
5987 | ||
5988 | @example | |
5989 | pragma Persistent_BSS [(LOCAL_NAME)] | |
5990 | @end example | |
5991 | ||
5992 | This pragma allows selected objects to be placed in the @code{.persistent_bss} | |
5993 | section. On some targets the linker and loader provide for special | |
5994 | treatment of this section, allowing a program to be reloaded without | |
5995 | affecting the contents of this data (hence the name persistent). | |
5996 | ||
5997 | There are two forms of usage. If an argument is given, it must be the | |
5998 | local name of a library-level object, with no explicit initialization | |
5999 | and whose type is potentially persistent. If no argument is given, then | |
6000 | the pragma is a configuration pragma, and applies to all library-level | |
6001 | objects with no explicit initialization of potentially persistent types. | |
6002 | ||
6003 | A potentially persistent type is a scalar type, or an untagged, | |
6004 | non-discriminated record, all of whose components have no explicit | |
6005 | initialization and are themselves of a potentially persistent type, | |
6006 | or an array, all of whose constraints are static, and whose component | |
6007 | type is potentially persistent. | |
6008 | ||
6009 | If this pragma is used on a target where this feature is not supported, | |
6010 | then the pragma will be ignored. See also @code{pragma Linker_Section}. | |
6011 | ||
6012 | @node Pragma Post,Pragma Postcondition,Pragma Persistent_BSS,Implementation Defined Pragmas | |
b71d4b62 | 6013 | @anchor{gnat_rm/implementation_defined_pragmas pragma-post}@anchor{ba} |
64d5610f ML |
6014 | @section Pragma Post |
6015 | ||
6016 | ||
6017 | @geindex Post | |
6018 | ||
6019 | @geindex Checks | |
6020 | @geindex postconditions | |
6021 | ||
6022 | Syntax: | |
6023 | ||
6024 | @example | |
6025 | pragma Post (Boolean_Expression); | |
6026 | @end example | |
6027 | ||
6028 | The @code{Post} pragma is intended to be an exact replacement for | |
6029 | the language-defined | |
6030 | @code{Post} aspect, and shares its restrictions and semantics. | |
6031 | It must appear either immediately following the corresponding | |
6032 | subprogram declaration (only other pragmas may intervene), or | |
6033 | if there is no separate subprogram declaration, then it can | |
6034 | appear at the start of the declarations in a subprogram body | |
6035 | (preceded only by other pragmas). | |
6036 | ||
6037 | @node Pragma Postcondition,Pragma Post_Class,Pragma Post,Implementation Defined Pragmas | |
b71d4b62 | 6038 | @anchor{gnat_rm/implementation_defined_pragmas pragma-postcondition}@anchor{bb} |
64d5610f ML |
6039 | @section Pragma Postcondition |
6040 | ||
6041 | ||
6042 | @geindex Postcondition | |
6043 | ||
6044 | @geindex Checks | |
6045 | @geindex postconditions | |
6046 | ||
6047 | Syntax: | |
6048 | ||
6049 | @example | |
6050 | pragma Postcondition ( | |
6051 | [Check =>] Boolean_Expression | |
6052 | [,[Message =>] String_Expression]); | |
6053 | @end example | |
6054 | ||
6055 | The @code{Postcondition} pragma allows specification of automatic | |
6056 | postcondition checks for subprograms. These checks are similar to | |
6057 | assertions, but are automatically inserted just prior to the return | |
6058 | statements of the subprogram with which they are associated (including | |
6059 | implicit returns at the end of procedure bodies and associated | |
6060 | exception handlers). | |
6061 | ||
6062 | In addition, the boolean expression which is the condition which | |
6063 | must be true may contain references to function’Result in the case | |
6064 | of a function to refer to the returned value. | |
6065 | ||
6066 | @code{Postcondition} pragmas may appear either immediately following the | |
6067 | (separate) declaration of a subprogram, or at the start of the | |
6068 | declarations of a subprogram body. Only other pragmas may intervene | |
6069 | (that is appear between the subprogram declaration and its | |
6070 | postconditions, or appear before the postcondition in the | |
6071 | declaration sequence in a subprogram body). In the case of a | |
6072 | postcondition appearing after a subprogram declaration, the | |
6073 | formal arguments of the subprogram are visible, and can be | |
6074 | referenced in the postcondition expressions. | |
6075 | ||
6076 | The postconditions are collected and automatically tested just | |
6077 | before any return (implicit or explicit) in the subprogram body. | |
6078 | A postcondition is only recognized if postconditions are active | |
1acce141 | 6079 | at the time the pragma is encountered. The compiler switch @emph{gnata} |
64d5610f ML |
6080 | turns on all postconditions by default, and pragma @code{Check_Policy} |
6081 | with an identifier of @code{Postcondition} can also be used to | |
6082 | control whether postconditions are active. | |
6083 | ||
6084 | The general approach is that postconditions are placed in the spec | |
6085 | if they represent functional aspects which make sense to the client. | |
6086 | For example we might have: | |
6087 | ||
6088 | @example | |
6089 | function Direction return Integer; | |
6090 | pragma Postcondition | |
6091 | (Direction'Result = +1 | |
6092 | or else | |
6093 | Direction'Result = -1); | |
6094 | @end example | |
6095 | ||
6096 | which serves to document that the result must be +1 or -1, and | |
6097 | will test that this is the case at run time if postcondition | |
6098 | checking is active. | |
6099 | ||
6100 | Postconditions within the subprogram body can be used to | |
6101 | check that some internal aspect of the implementation, | |
6102 | not visible to the client, is operating as expected. | |
6103 | For instance if a square root routine keeps an internal | |
6104 | counter of the number of times it is called, then we | |
6105 | might have the following postcondition: | |
6106 | ||
6107 | @example | |
6108 | Sqrt_Calls : Natural := 0; | |
6109 | ||
6110 | function Sqrt (Arg : Float) return Float is | |
6111 | pragma Postcondition | |
6112 | (Sqrt_Calls = Sqrt_Calls'Old + 1); | |
6113 | ... | |
6114 | end Sqrt | |
6115 | @end example | |
6116 | ||
6117 | As this example, shows, the use of the @code{Old} attribute | |
6118 | is often useful in postconditions to refer to the state on | |
6119 | entry to the subprogram. | |
6120 | ||
6121 | Note that postconditions are only checked on normal returns | |
6122 | from the subprogram. If an abnormal return results from | |
6123 | raising an exception, then the postconditions are not checked. | |
6124 | ||
6125 | If a postcondition fails, then the exception | |
6126 | @code{System.Assertions.Assert_Failure} is raised. If | |
6127 | a message argument was supplied, then the given string | |
6128 | will be used as the exception message. If no message | |
6129 | argument was supplied, then the default message has | |
6130 | the form “Postcondition failed at file_name:line”. The | |
6131 | exception is raised in the context of the subprogram | |
6132 | body, so it is possible to catch postcondition failures | |
6133 | within the subprogram body itself. | |
6134 | ||
6135 | Within a package spec, normal visibility rules | |
6136 | in Ada would prevent forward references within a | |
6137 | postcondition pragma to functions defined later in | |
6138 | the same package. This would introduce undesirable | |
6139 | ordering constraints. To avoid this problem, all | |
6140 | postcondition pragmas are analyzed at the end of | |
6141 | the package spec, allowing forward references. | |
6142 | ||
6143 | The following example shows that this even allows | |
6144 | mutually recursive postconditions as in: | |
6145 | ||
6146 | @example | |
6147 | package Parity_Functions is | |
6148 | function Odd (X : Natural) return Boolean; | |
6149 | pragma Postcondition | |
6150 | (Odd'Result = | |
6151 | (x = 1 | |
6152 | or else | |
6153 | (x /= 0 and then Even (X - 1)))); | |
6154 | ||
6155 | function Even (X : Natural) return Boolean; | |
6156 | pragma Postcondition | |
6157 | (Even'Result = | |
6158 | (x = 0 | |
6159 | or else | |
6160 | (x /= 1 and then Odd (X - 1)))); | |
6161 | ||
6162 | end Parity_Functions; | |
6163 | @end example | |
6164 | ||
6165 | There are no restrictions on the complexity or form of | |
6166 | conditions used within @code{Postcondition} pragmas. | |
6167 | The following example shows that it is even possible | |
6168 | to verify performance behavior. | |
6169 | ||
6170 | @example | |
6171 | package Sort is | |
6172 | ||
6173 | Performance : constant Float; | |
6174 | -- Performance constant set by implementation | |
6175 | -- to match target architecture behavior. | |
6176 | ||
6177 | procedure Treesort (Arg : String); | |
6178 | -- Sorts characters of argument using N*logN sort | |
6179 | pragma Postcondition | |
6180 | (Float (Clock - Clock'Old) <= | |
6181 | Float (Arg'Length) * | |
6182 | log (Float (Arg'Length)) * | |
6183 | Performance); | |
6184 | end Sort; | |
6185 | @end example | |
6186 | ||
6187 | Note: postcondition pragmas associated with subprograms that are | |
6188 | marked as Inline_Always, or those marked as Inline with front-end | |
6189 | inlining (-gnatN option set) are accepted and legality-checked | |
6190 | by the compiler, but are ignored at run-time even if postcondition | |
6191 | checking is enabled. | |
6192 | ||
6193 | Note that pragma @code{Postcondition} differs from the language-defined | |
6194 | @code{Post} aspect (and corresponding @code{Post} pragma) in allowing | |
6195 | multiple occurrences, allowing occurences in the body even if there | |
6196 | is a separate spec, and allowing a second string parameter, and the | |
6197 | use of the pragma identifier @code{Check}. Historically, pragma | |
6198 | @code{Postcondition} was implemented prior to the development of | |
6199 | Ada 2012, and has been retained in its original form for | |
6200 | compatibility purposes. | |
6201 | ||
6202 | @node Pragma Post_Class,Pragma Pre,Pragma Postcondition,Implementation Defined Pragmas | |
b71d4b62 | 6203 | @anchor{gnat_rm/implementation_defined_pragmas pragma-post-class}@anchor{bc} |
64d5610f ML |
6204 | @section Pragma Post_Class |
6205 | ||
6206 | ||
6207 | @geindex Post | |
6208 | ||
6209 | @geindex Checks | |
6210 | @geindex postconditions | |
6211 | ||
6212 | Syntax: | |
6213 | ||
6214 | @example | |
6215 | pragma Post_Class (Boolean_Expression); | |
6216 | @end example | |
6217 | ||
6218 | The @code{Post_Class} pragma is intended to be an exact replacement for | |
6219 | the language-defined | |
6220 | @code{Post'Class} aspect, and shares its restrictions and semantics. | |
6221 | It must appear either immediately following the corresponding | |
6222 | subprogram declaration (only other pragmas may intervene), or | |
6223 | if there is no separate subprogram declaration, then it can | |
6224 | appear at the start of the declarations in a subprogram body | |
6225 | (preceded only by other pragmas). | |
6226 | ||
6227 | Note: This pragma is called @code{Post_Class} rather than | |
6228 | @code{Post'Class} because the latter would not be strictly | |
6229 | conforming to the allowed syntax for pragmas. The motivation | |
6230 | for providing pragmas equivalent to the aspects is to allow a program | |
6231 | to be written using the pragmas, and then compiled if necessary | |
6232 | using an Ada compiler that does not recognize the pragmas or | |
6233 | aspects, but is prepared to ignore the pragmas. The assertion | |
6234 | policy that controls this pragma is @code{Post'Class}, not | |
6235 | @code{Post_Class}. | |
6236 | ||
6237 | @node Pragma Pre,Pragma Precondition,Pragma Post_Class,Implementation Defined Pragmas | |
b71d4b62 | 6238 | @anchor{gnat_rm/implementation_defined_pragmas pragma-pre}@anchor{bd} |
64d5610f ML |
6239 | @section Pragma Pre |
6240 | ||
6241 | ||
6242 | @geindex Pre | |
6243 | ||
6244 | @geindex Checks | |
6245 | @geindex preconditions | |
6246 | ||
6247 | Syntax: | |
6248 | ||
6249 | @example | |
6250 | pragma Pre (Boolean_Expression); | |
6251 | @end example | |
6252 | ||
6253 | The @code{Pre} pragma is intended to be an exact replacement for | |
6254 | the language-defined | |
6255 | @code{Pre} aspect, and shares its restrictions and semantics. | |
6256 | It must appear either immediately following the corresponding | |
6257 | subprogram declaration (only other pragmas may intervene), or | |
6258 | if there is no separate subprogram declaration, then it can | |
6259 | appear at the start of the declarations in a subprogram body | |
6260 | (preceded only by other pragmas). | |
6261 | ||
6262 | @node Pragma Precondition,Pragma Predicate,Pragma Pre,Implementation Defined Pragmas | |
b71d4b62 | 6263 | @anchor{gnat_rm/implementation_defined_pragmas pragma-precondition}@anchor{be} |
64d5610f ML |
6264 | @section Pragma Precondition |
6265 | ||
6266 | ||
6267 | @geindex Preconditions | |
6268 | ||
6269 | @geindex Checks | |
6270 | @geindex preconditions | |
6271 | ||
6272 | Syntax: | |
6273 | ||
6274 | @example | |
6275 | pragma Precondition ( | |
6276 | [Check =>] Boolean_Expression | |
6277 | [,[Message =>] String_Expression]); | |
6278 | @end example | |
6279 | ||
6280 | The @code{Precondition} pragma is similar to @code{Postcondition} | |
6281 | except that the corresponding checks take place immediately upon | |
6282 | entry to the subprogram, and if a precondition fails, the exception | |
6283 | is raised in the context of the caller, and the attribute ‘Result | |
6284 | cannot be used within the precondition expression. | |
6285 | ||
6286 | Otherwise, the placement and visibility rules are identical to those | |
6287 | described for postconditions. The following is an example of use | |
6288 | within a package spec: | |
6289 | ||
6290 | @example | |
6291 | package Math_Functions is | |
6292 | ... | |
6293 | function Sqrt (Arg : Float) return Float; | |
6294 | pragma Precondition (Arg >= 0.0) | |
6295 | ... | |
6296 | end Math_Functions; | |
6297 | @end example | |
6298 | ||
6299 | @code{Precondition} pragmas may appear either immediately following the | |
6300 | (separate) declaration of a subprogram, or at the start of the | |
6301 | declarations of a subprogram body. Only other pragmas may intervene | |
6302 | (that is appear between the subprogram declaration and its | |
6303 | postconditions, or appear before the postcondition in the | |
6304 | declaration sequence in a subprogram body). | |
6305 | ||
6306 | Note: precondition pragmas associated with subprograms that are | |
6307 | marked as Inline_Always, or those marked as Inline with front-end | |
6308 | inlining (-gnatN option set) are accepted and legality-checked | |
6309 | by the compiler, but are ignored at run-time even if precondition | |
6310 | checking is enabled. | |
6311 | ||
6312 | Note that pragma @code{Precondition} differs from the language-defined | |
6313 | @code{Pre} aspect (and corresponding @code{Pre} pragma) in allowing | |
6314 | multiple occurrences, allowing occurences in the body even if there | |
6315 | is a separate spec, and allowing a second string parameter, and the | |
6316 | use of the pragma identifier @code{Check}. Historically, pragma | |
6317 | @code{Precondition} was implemented prior to the development of | |
6318 | Ada 2012, and has been retained in its original form for | |
6319 | compatibility purposes. | |
6320 | ||
6321 | @node Pragma Predicate,Pragma Predicate_Failure,Pragma Precondition,Implementation Defined Pragmas | |
b71d4b62 | 6322 | @anchor{gnat_rm/implementation_defined_pragmas id31}@anchor{bf}@anchor{gnat_rm/implementation_defined_pragmas pragma-predicate}@anchor{c0} |
64d5610f ML |
6323 | @section Pragma Predicate |
6324 | ||
6325 | ||
6326 | Syntax: | |
6327 | ||
6328 | @example | |
6329 | pragma Predicate | |
6330 | ([Entity =>] type_LOCAL_NAME, | |
6331 | [Check =>] EXPRESSION); | |
6332 | @end example | |
6333 | ||
6334 | This pragma (available in all versions of Ada in GNAT) encompasses both | |
6335 | the @code{Static_Predicate} and @code{Dynamic_Predicate} aspects in | |
6336 | Ada 2012. A predicate is regarded as static if it has an allowed form | |
6337 | for @code{Static_Predicate} and is otherwise treated as a | |
6338 | @code{Dynamic_Predicate}. Otherwise, predicates specified by this | |
6339 | pragma behave exactly as described in the Ada 2012 reference manual. | |
6340 | For example, if we have | |
6341 | ||
6342 | @example | |
6343 | type R is range 1 .. 10; | |
6344 | subtype S is R; | |
6345 | pragma Predicate (Entity => S, Check => S not in 4 .. 6); | |
6346 | subtype Q is R | |
6347 | pragma Predicate (Entity => Q, Check => F(Q) or G(Q)); | |
6348 | @end example | |
6349 | ||
6350 | the effect is identical to the following Ada 2012 code: | |
6351 | ||
6352 | @example | |
6353 | type R is range 1 .. 10; | |
6354 | subtype S is R with | |
6355 | Static_Predicate => S not in 4 .. 6; | |
6356 | subtype Q is R with | |
6357 | Dynamic_Predicate => F(Q) or G(Q); | |
6358 | @end example | |
6359 | ||
6360 | Note that there are no pragmas @code{Dynamic_Predicate} | |
6361 | or @code{Static_Predicate}. That is | |
6362 | because these pragmas would affect legality and semantics of | |
6363 | the program and thus do not have a neutral effect if ignored. | |
6364 | The motivation behind providing pragmas equivalent to | |
6365 | corresponding aspects is to allow a program to be written | |
6366 | using the pragmas, and then compiled with a compiler that | |
6367 | will ignore the pragmas. That doesn’t work in the case of | |
6368 | static and dynamic predicates, since if the corresponding | |
6369 | pragmas are ignored, then the behavior of the program is | |
6370 | fundamentally changed (for example a membership test | |
6371 | @code{A in B} would not take into account a predicate | |
6372 | defined for subtype B). When following this approach, the | |
6373 | use of predicates should be avoided. | |
6374 | ||
6375 | @node Pragma Predicate_Failure,Pragma Preelaborable_Initialization,Pragma Predicate,Implementation Defined Pragmas | |
b71d4b62 | 6376 | @anchor{gnat_rm/implementation_defined_pragmas pragma-predicate-failure}@anchor{c1} |
64d5610f ML |
6377 | @section Pragma Predicate_Failure |
6378 | ||
6379 | ||
6380 | Syntax: | |
6381 | ||
6382 | @example | |
6383 | pragma Predicate_Failure | |
6384 | ([Entity =>] type_LOCAL_NAME, | |
6385 | [Message =>] String_Expression); | |
6386 | @end example | |
6387 | ||
6388 | The @code{Predicate_Failure} pragma is intended to be an exact replacement for | |
6389 | the language-defined | |
6390 | @code{Predicate_Failure} aspect, and shares its restrictions and semantics. | |
6391 | ||
6392 | @node Pragma Preelaborable_Initialization,Pragma Prefix_Exception_Messages,Pragma Predicate_Failure,Implementation Defined Pragmas | |
b71d4b62 | 6393 | @anchor{gnat_rm/implementation_defined_pragmas pragma-preelaborable-initialization}@anchor{c2} |
64d5610f ML |
6394 | @section Pragma Preelaborable_Initialization |
6395 | ||
6396 | ||
6397 | Syntax: | |
6398 | ||
6399 | @example | |
6400 | pragma Preelaborable_Initialization (DIRECT_NAME); | |
6401 | @end example | |
6402 | ||
6403 | This pragma is standard in Ada 2005, but is available in all earlier | |
6404 | versions of Ada as an implementation-defined pragma. | |
6405 | See Ada 2012 Reference Manual for details. | |
6406 | ||
6407 | @node Pragma Prefix_Exception_Messages,Pragma Pre_Class,Pragma Preelaborable_Initialization,Implementation Defined Pragmas | |
b71d4b62 | 6408 | @anchor{gnat_rm/implementation_defined_pragmas pragma-prefix-exception-messages}@anchor{c3} |
64d5610f ML |
6409 | @section Pragma Prefix_Exception_Messages |
6410 | ||
6411 | ||
6412 | @geindex Prefix_Exception_Messages | |
6413 | ||
6414 | @geindex exception | |
6415 | ||
6416 | @geindex Exception_Message | |
6417 | ||
6418 | Syntax: | |
6419 | ||
6420 | @example | |
6421 | pragma Prefix_Exception_Messages; | |
6422 | @end example | |
6423 | ||
6424 | This is an implementation-defined configuration pragma that affects the | |
6425 | behavior of raise statements with a message given as a static string | |
6426 | constant (typically a string literal). In such cases, the string will | |
6427 | be automatically prefixed by the name of the enclosing entity (giving | |
6428 | the package and subprogram containing the raise statement). This helps | |
6429 | to identify where messages are coming from, and this mode is automatic | |
6430 | for the run-time library. | |
6431 | ||
6432 | The pragma has no effect if the message is computed with an expression other | |
6433 | than a static string constant, since the assumption in this case is that | |
6434 | the program computes exactly the string it wants. If you still want the | |
6435 | prefixing in this case, you can always call | |
6436 | @code{GNAT.Source_Info.Enclosing_Entity} and prepend the string manually. | |
6437 | ||
6438 | @node Pragma Pre_Class,Pragma Priority_Specific_Dispatching,Pragma Prefix_Exception_Messages,Implementation Defined Pragmas | |
b71d4b62 | 6439 | @anchor{gnat_rm/implementation_defined_pragmas pragma-pre-class}@anchor{c4} |
64d5610f ML |
6440 | @section Pragma Pre_Class |
6441 | ||
6442 | ||
6443 | @geindex Pre_Class | |
6444 | ||
6445 | @geindex Checks | |
6446 | @geindex preconditions | |
6447 | ||
6448 | Syntax: | |
6449 | ||
6450 | @example | |
6451 | pragma Pre_Class (Boolean_Expression); | |
6452 | @end example | |
6453 | ||
6454 | The @code{Pre_Class} pragma is intended to be an exact replacement for | |
6455 | the language-defined | |
6456 | @code{Pre'Class} aspect, and shares its restrictions and semantics. | |
6457 | It must appear either immediately following the corresponding | |
6458 | subprogram declaration (only other pragmas may intervene), or | |
6459 | if there is no separate subprogram declaration, then it can | |
6460 | appear at the start of the declarations in a subprogram body | |
6461 | (preceded only by other pragmas). | |
6462 | ||
6463 | Note: This pragma is called @code{Pre_Class} rather than | |
6464 | @code{Pre'Class} because the latter would not be strictly | |
6465 | conforming to the allowed syntax for pragmas. The motivation | |
6466 | for providing pragmas equivalent to the aspects is to allow a program | |
6467 | to be written using the pragmas, and then compiled if necessary | |
6468 | using an Ada compiler that does not recognize the pragmas or | |
6469 | aspects, but is prepared to ignore the pragmas. The assertion | |
6470 | policy that controls this pragma is @code{Pre'Class}, not | |
6471 | @code{Pre_Class}. | |
6472 | ||
6473 | @node Pragma Priority_Specific_Dispatching,Pragma Profile,Pragma Pre_Class,Implementation Defined Pragmas | |
b71d4b62 | 6474 | @anchor{gnat_rm/implementation_defined_pragmas pragma-priority-specific-dispatching}@anchor{c5} |
64d5610f ML |
6475 | @section Pragma Priority_Specific_Dispatching |
6476 | ||
6477 | ||
6478 | Syntax: | |
6479 | ||
6480 | @example | |
6481 | pragma Priority_Specific_Dispatching ( | |
6482 | POLICY_IDENTIFIER, | |
6483 | first_priority_EXPRESSION, | |
6484 | last_priority_EXPRESSION) | |
6485 | ||
6486 | POLICY_IDENTIFIER ::= | |
6487 | EDF_Across_Priorities | | |
6488 | FIFO_Within_Priorities | | |
6489 | Non_Preemptive_Within_Priorities | | |
6490 | Round_Robin_Within_Priorities | |
6491 | @end example | |
6492 | ||
6493 | This pragma is standard in Ada 2005, but is available in all earlier | |
6494 | versions of Ada as an implementation-defined pragma. | |
6495 | See Ada 2012 Reference Manual for details. | |
6496 | ||
6497 | @node Pragma Profile,Pragma Profile_Warnings,Pragma Priority_Specific_Dispatching,Implementation Defined Pragmas | |
b71d4b62 | 6498 | @anchor{gnat_rm/implementation_defined_pragmas pragma-profile}@anchor{c6} |
64d5610f ML |
6499 | @section Pragma Profile |
6500 | ||
6501 | ||
6502 | Syntax: | |
6503 | ||
6504 | @example | |
6505 | pragma Profile (Ravenscar | Restricted | Rational | Jorvik | | |
6506 | GNAT_Extended_Ravenscar | GNAT_Ravenscar_EDF ); | |
6507 | @end example | |
6508 | ||
6509 | This pragma is standard in Ada 2005, but is available in all earlier | |
6510 | versions of Ada as an implementation-defined pragma. This is a | |
6511 | configuration pragma that establishes a set of configuration pragmas | |
6512 | that depend on the argument. @code{Ravenscar} is standard in Ada 2005. | |
6513 | @code{Jorvik} is standard in Ada 202x. | |
6514 | The other possibilities (@code{Restricted}, @code{Rational}, | |
6515 | @code{GNAT_Extended_Ravenscar}, @code{GNAT_Ravenscar_EDF}) | |
6516 | are implementation-defined. @code{GNAT_Extended_Ravenscar} is an alias for @code{Jorvik}. | |
6517 | ||
6518 | The set of configuration pragmas is defined in the following sections. | |
6519 | ||
6520 | ||
6521 | @itemize * | |
6522 | ||
6523 | @item | |
6524 | Pragma Profile (Ravenscar) | |
6525 | ||
6526 | The @code{Ravenscar} profile is standard in Ada 2005, | |
6527 | but is available in all earlier | |
6528 | versions of Ada as an implementation-defined pragma. This profile | |
6529 | establishes the following set of configuration pragmas: | |
6530 | ||
6531 | ||
6532 | @itemize * | |
6533 | ||
6534 | @item | |
6535 | @code{Task_Dispatching_Policy (FIFO_Within_Priorities)} | |
6536 | ||
6537 | [RM D.2.2] Tasks are dispatched following a preemptive | |
6538 | priority-ordered scheduling policy. | |
6539 | ||
6540 | @item | |
6541 | @code{Locking_Policy (Ceiling_Locking)} | |
6542 | ||
6543 | [RM D.3] While tasks and interrupts execute a protected action, they inherit | |
6544 | the ceiling priority of the corresponding protected object. | |
6545 | ||
6546 | @item | |
6547 | @code{Detect_Blocking} | |
6548 | ||
6549 | This pragma forces the detection of potentially blocking operations within a | |
6550 | protected operation, and to raise Program_Error if that happens. | |
6551 | @end itemize | |
6552 | ||
6553 | plus the following set of restrictions: | |
6554 | ||
6555 | ||
6556 | @itemize * | |
6557 | ||
6558 | @item | |
6559 | @code{Max_Entry_Queue_Length => 1} | |
6560 | ||
6561 | No task can be queued on a protected entry. | |
6562 | ||
6563 | @item | |
6564 | @code{Max_Protected_Entries => 1} | |
6565 | ||
6566 | @item | |
6567 | @code{Max_Task_Entries => 0} | |
6568 | ||
6569 | No rendezvous statements are allowed. | |
6570 | ||
6571 | @item | |
6572 | @code{No_Abort_Statements} | |
6573 | ||
6574 | @item | |
6575 | @code{No_Dynamic_Attachment} | |
6576 | ||
6577 | @item | |
6578 | @code{No_Dynamic_Priorities} | |
6579 | ||
6580 | @item | |
6581 | @code{No_Implicit_Heap_Allocations} | |
6582 | ||
6583 | @item | |
6584 | @code{No_Local_Protected_Objects} | |
6585 | ||
6586 | @item | |
6587 | @code{No_Local_Timing_Events} | |
6588 | ||
6589 | @item | |
6590 | @code{No_Protected_Type_Allocators} | |
6591 | ||
6592 | @item | |
6593 | @code{No_Relative_Delay} | |
6594 | ||
6595 | @item | |
6596 | @code{No_Requeue_Statements} | |
6597 | ||
6598 | @item | |
6599 | @code{No_Select_Statements} | |
6600 | ||
6601 | @item | |
6602 | @code{No_Specific_Termination_Handlers} | |
6603 | ||
6604 | @item | |
6605 | @code{No_Task_Allocators} | |
6606 | ||
6607 | @item | |
6608 | @code{No_Task_Hierarchy} | |
6609 | ||
6610 | @item | |
6611 | @code{No_Task_Termination} | |
6612 | ||
6613 | @item | |
6614 | @code{Simple_Barriers} | |
6615 | @end itemize | |
6616 | ||
6617 | The Ravenscar profile also includes the following restrictions that specify | |
6618 | that there are no semantic dependencies on the corresponding predefined | |
6619 | packages: | |
6620 | ||
6621 | ||
6622 | @itemize * | |
6623 | ||
6624 | @item | |
6625 | @code{No_Dependence => Ada.Asynchronous_Task_Control} | |
6626 | ||
6627 | @item | |
6628 | @code{No_Dependence => Ada.Calendar} | |
6629 | ||
6630 | @item | |
6631 | @code{No_Dependence => Ada.Execution_Time.Group_Budget} | |
6632 | ||
6633 | @item | |
6634 | @code{No_Dependence => Ada.Execution_Time.Timers} | |
6635 | ||
6636 | @item | |
6637 | @code{No_Dependence => Ada.Task_Attributes} | |
6638 | ||
6639 | @item | |
6640 | @code{No_Dependence => System.Multiprocessors.Dispatching_Domains} | |
6641 | @end itemize | |
6642 | ||
6643 | This set of configuration pragmas and restrictions correspond to the | |
6644 | definition of the ‘Ravenscar Profile’ for limited tasking, devised and | |
6645 | published by the @cite{International Real-Time Ada Workshop@comma{} 1997}. | |
6646 | A description is also available at | |
6647 | @indicateurl{http://www-users.cs.york.ac.uk/~burns/ravenscar.ps}. | |
6648 | ||
6649 | The original definition of the profile was revised at subsequent IRTAW | |
6650 | meetings. It has been included in the ISO | |
6651 | @cite{Guide for the Use of the Ada Programming Language in High Integrity Systems}, | |
6652 | and was made part of the Ada 2005 standard. | |
6653 | The formal definition given by | |
6654 | the Ada Rapporteur Group (ARG) can be found in two Ada Issues (AI-249 and | |
6655 | AI-305) available at | |
6656 | @indicateurl{http://www.ada-auth.org/cgi-bin/cvsweb.cgi/ais/ai-00249.txt} and | |
6657 | @indicateurl{http://www.ada-auth.org/cgi-bin/cvsweb.cgi/ais/ai-00305.txt}. | |
6658 | ||
6659 | The above set is a superset of the restrictions provided by pragma | |
6660 | @code{Profile (Restricted)}, it includes six additional restrictions | |
6661 | (@code{Simple_Barriers}, @code{No_Select_Statements}, | |
6662 | @code{No_Calendar}, @code{No_Implicit_Heap_Allocations}, | |
6663 | @code{No_Relative_Delay} and @code{No_Task_Termination}). This means | |
6664 | that pragma @code{Profile (Ravenscar)}, like the pragma | |
6665 | @code{Profile (Restricted)}, | |
6666 | automatically causes the use of a simplified, | |
6667 | more efficient version of the tasking run-time library. | |
6668 | ||
6669 | @item | |
6670 | Pragma Profile (Jorvik) | |
6671 | ||
6672 | @code{Jorvik} is the new profile added to the Ada 202x draft standard, | |
6673 | previously implemented under the name @code{GNAT_Extended_Ravenscar}. | |
6674 | ||
6675 | The @code{No_Implicit_Heap_Allocations} restriction has been replaced | |
6676 | by @code{No_Implicit_Task_Allocations} and | |
6677 | @code{No_Implicit_Protected_Object_Allocations}. | |
6678 | ||
6679 | The @code{Simple_Barriers} restriction has been replaced by | |
6680 | @code{Pure_Barriers}. | |
6681 | ||
6682 | The @code{Max_Protected_Entries}, @code{Max_Entry_Queue_Length}, and | |
6683 | @code{No_Relative_Delay} restrictions have been removed. | |
6684 | ||
6685 | Details on the rationale for @code{Jorvik} and implications for use may be | |
6686 | found in @cite{A New Ravenscar-Based Profile} by P. Rogers, J. Ruiz, | |
6687 | T. Gingold and P. Bernardi, in @cite{Reliable Software Technologies – Ada Europe 2017}, Springer-Verlag Lecture Notes in Computer Science, | |
6688 | Number 10300. | |
6689 | ||
6690 | @item | |
6691 | Pragma Profile (GNAT_Ravenscar_EDF) | |
6692 | ||
6693 | This profile corresponds to the Ravenscar profile but using | |
6694 | EDF_Across_Priority as the Task_Scheduling_Policy. | |
6695 | ||
6696 | @item | |
6697 | Pragma Profile (Restricted) | |
6698 | ||
6699 | This profile corresponds to the GNAT restricted run time. It | |
6700 | establishes the following set of restrictions: | |
6701 | ||
6702 | ||
6703 | @itemize * | |
6704 | ||
6705 | @item | |
6706 | @code{No_Abort_Statements} | |
6707 | ||
6708 | @item | |
6709 | @code{No_Entry_Queue} | |
6710 | ||
6711 | @item | |
6712 | @code{No_Task_Hierarchy} | |
6713 | ||
6714 | @item | |
6715 | @code{No_Task_Allocators} | |
6716 | ||
6717 | @item | |
6718 | @code{No_Dynamic_Priorities} | |
6719 | ||
6720 | @item | |
6721 | @code{No_Terminate_Alternatives} | |
6722 | ||
6723 | @item | |
6724 | @code{No_Dynamic_Attachment} | |
6725 | ||
6726 | @item | |
6727 | @code{No_Protected_Type_Allocators} | |
6728 | ||
6729 | @item | |
6730 | @code{No_Local_Protected_Objects} | |
6731 | ||
6732 | @item | |
6733 | @code{No_Requeue_Statements} | |
6734 | ||
6735 | @item | |
6736 | @code{No_Task_Attributes_Package} | |
6737 | ||
6738 | @item | |
6739 | @code{Max_Asynchronous_Select_Nesting = 0} | |
6740 | ||
6741 | @item | |
6742 | @code{Max_Task_Entries = 0} | |
6743 | ||
6744 | @item | |
6745 | @code{Max_Protected_Entries = 1} | |
6746 | ||
6747 | @item | |
6748 | @code{Max_Select_Alternatives = 0} | |
6749 | @end itemize | |
6750 | ||
6751 | This set of restrictions causes the automatic selection of a simplified | |
6752 | version of the run time that provides improved performance for the | |
6753 | limited set of tasking functionality permitted by this set of restrictions. | |
6754 | ||
6755 | @item | |
6756 | Pragma Profile (Rational) | |
6757 | ||
6758 | The Rational profile is intended to facilitate porting legacy code that | |
6759 | compiles with the Rational APEX compiler, even when the code includes non- | |
6760 | conforming Ada constructs. The profile enables the following three pragmas: | |
6761 | ||
6762 | ||
6763 | @itemize * | |
6764 | ||
6765 | @item | |
6766 | @code{pragma Implicit_Packing} | |
6767 | ||
6768 | @item | |
6769 | @code{pragma Overriding_Renamings} | |
6770 | ||
6771 | @item | |
6772 | @code{pragma Use_VADS_Size} | |
6773 | @end itemize | |
6774 | @end itemize | |
6775 | ||
6776 | @node Pragma Profile_Warnings,Pragma Propagate_Exceptions,Pragma Profile,Implementation Defined Pragmas | |
b71d4b62 | 6777 | @anchor{gnat_rm/implementation_defined_pragmas pragma-profile-warnings}@anchor{c7} |
64d5610f ML |
6778 | @section Pragma Profile_Warnings |
6779 | ||
6780 | ||
6781 | Syntax: | |
6782 | ||
6783 | @example | |
6784 | pragma Profile_Warnings (Ravenscar | Restricted | Rational); | |
6785 | @end example | |
6786 | ||
6787 | This is an implementation-defined pragma that is similar in | |
6788 | effect to @code{pragma Profile} except that instead of | |
6789 | generating @code{Restrictions} pragmas, it generates | |
6790 | @code{Restriction_Warnings} pragmas. The result is that | |
6791 | violations of the profile generate warning messages instead | |
6792 | of error messages. | |
6793 | ||
6794 | @node Pragma Propagate_Exceptions,Pragma Provide_Shift_Operators,Pragma Profile_Warnings,Implementation Defined Pragmas | |
b71d4b62 | 6795 | @anchor{gnat_rm/implementation_defined_pragmas pragma-propagate-exceptions}@anchor{c8} |
64d5610f ML |
6796 | @section Pragma Propagate_Exceptions |
6797 | ||
6798 | ||
6799 | @geindex Interfacing to C++ | |
6800 | ||
6801 | Syntax: | |
6802 | ||
6803 | @example | |
6804 | pragma Propagate_Exceptions; | |
6805 | @end example | |
6806 | ||
6807 | This pragma is now obsolete and, other than generating a warning if warnings | |
6808 | on obsolescent features are enabled, is ignored. | |
6809 | It is retained for compatibility | |
6810 | purposes. It used to be used in connection with optimization of | |
6811 | a now-obsolete mechanism for implementation of exceptions. | |
6812 | ||
6813 | @node Pragma Provide_Shift_Operators,Pragma Psect_Object,Pragma Propagate_Exceptions,Implementation Defined Pragmas | |
b71d4b62 | 6814 | @anchor{gnat_rm/implementation_defined_pragmas pragma-provide-shift-operators}@anchor{c9} |
64d5610f ML |
6815 | @section Pragma Provide_Shift_Operators |
6816 | ||
6817 | ||
6818 | @geindex Shift operators | |
6819 | ||
6820 | Syntax: | |
6821 | ||
6822 | @example | |
6823 | pragma Provide_Shift_Operators (integer_first_subtype_LOCAL_NAME); | |
6824 | @end example | |
6825 | ||
6826 | This pragma can be applied to a first subtype local name that specifies | |
6827 | either an unsigned or signed type. It has the effect of providing the | |
6828 | five shift operators (Shift_Left, Shift_Right, Shift_Right_Arithmetic, | |
6829 | Rotate_Left and Rotate_Right) for the given type. It is similar to | |
6830 | including the function declarations for these five operators, together | |
6831 | with the pragma Import (Intrinsic, …) statements. | |
6832 | ||
6833 | @node Pragma Psect_Object,Pragma Pure_Function,Pragma Provide_Shift_Operators,Implementation Defined Pragmas | |
b71d4b62 | 6834 | @anchor{gnat_rm/implementation_defined_pragmas pragma-psect-object}@anchor{ca} |
64d5610f ML |
6835 | @section Pragma Psect_Object |
6836 | ||
6837 | ||
6838 | Syntax: | |
6839 | ||
6840 | @example | |
6841 | pragma Psect_Object ( | |
6842 | [Internal =>] LOCAL_NAME, | |
6843 | [, [External =>] EXTERNAL_SYMBOL] | |
6844 | [, [Size =>] EXTERNAL_SYMBOL]); | |
6845 | ||
6846 | EXTERNAL_SYMBOL ::= | |
6847 | IDENTIFIER | |
6848 | | static_string_EXPRESSION | |
6849 | @end example | |
6850 | ||
6851 | This pragma is identical in effect to pragma @code{Common_Object}. | |
6852 | ||
6853 | @node Pragma Pure_Function,Pragma Rational,Pragma Psect_Object,Implementation Defined Pragmas | |
b71d4b62 | 6854 | @anchor{gnat_rm/implementation_defined_pragmas id32}@anchor{cb}@anchor{gnat_rm/implementation_defined_pragmas pragma-pure-function}@anchor{cc} |
64d5610f ML |
6855 | @section Pragma Pure_Function |
6856 | ||
6857 | ||
6858 | Syntax: | |
6859 | ||
6860 | @example | |
6861 | pragma Pure_Function ([Entity =>] function_LOCAL_NAME); | |
6862 | @end example | |
6863 | ||
6864 | This pragma appears in the same declarative part as a function | |
6865 | declaration (or a set of function declarations if more than one | |
6866 | overloaded declaration exists, in which case the pragma applies | |
6867 | to all entities). It specifies that the function @code{Entity} is | |
6868 | to be considered pure for the purposes of code generation. This means | |
6869 | that the compiler can assume that there are no side effects, and | |
6870 | in particular that two identical calls produce the same result in | |
6871 | the same context. It also means that the function can be used in | |
6872 | an address clause. | |
6873 | ||
6874 | Note that, quite deliberately, there are no static checks to try | |
6875 | to ensure that this promise is met, so @code{Pure_Function} can be used | |
6876 | with functions that are conceptually pure, even if they do modify | |
6877 | global variables. For example, a square root function that is | |
6878 | instrumented to count the number of times it is called is still | |
6879 | conceptually pure, and can still be optimized, even though it | |
6880 | modifies a global variable (the count). Memo functions are another | |
6881 | example (where a table of previous calls is kept and consulted to | |
6882 | avoid re-computation). | |
6883 | ||
6884 | Note also that the normal rules excluding optimization of subprograms | |
6885 | in pure units (when parameter types are descended from System.Address, | |
6886 | or when the full view of a parameter type is limited), do not apply | |
6887 | for the Pure_Function case. If you explicitly specify Pure_Function, | |
6888 | the compiler may optimize away calls with identical arguments, and | |
6889 | if that results in unexpected behavior, the proper action is not to | |
6890 | use the pragma for subprograms that are not (conceptually) pure. | |
6891 | ||
6892 | Note: Most functions in a @code{Pure} package are automatically pure, and | |
6893 | there is no need to use pragma @code{Pure_Function} for such functions. One | |
6894 | exception is any function that has at least one formal of type | |
6895 | @code{System.Address} or a type derived from it. Such functions are not | |
6896 | considered pure by default, since the compiler assumes that the | |
6897 | @code{Address} parameter may be functioning as a pointer and that the | |
6898 | referenced data may change even if the address value does not. | |
6899 | Similarly, imported functions are not considered to be pure by default, | |
6900 | since there is no way of checking that they are in fact pure. The use | |
6901 | of pragma @code{Pure_Function} for such a function will override these default | |
6902 | assumption, and cause the compiler to treat a designated subprogram as pure | |
6903 | in these cases. | |
6904 | ||
6905 | Note: If pragma @code{Pure_Function} is applied to a renamed function, it | |
6906 | applies to the underlying renamed function. This can be used to | |
6907 | disambiguate cases of overloading where some but not all functions | |
6908 | in a set of overloaded functions are to be designated as pure. | |
6909 | ||
6910 | If pragma @code{Pure_Function} is applied to a library-level function, the | |
6911 | function is also considered pure from an optimization point of view, but the | |
6912 | unit is not a Pure unit in the categorization sense. So for example, a function | |
6913 | thus marked is free to @code{with} non-pure units. | |
6914 | ||
6915 | @node Pragma Rational,Pragma Ravenscar,Pragma Pure_Function,Implementation Defined Pragmas | |
b71d4b62 | 6916 | @anchor{gnat_rm/implementation_defined_pragmas pragma-rational}@anchor{cd} |
64d5610f ML |
6917 | @section Pragma Rational |
6918 | ||
6919 | ||
6920 | Syntax: | |
6921 | ||
6922 | @example | |
6923 | pragma Rational; | |
6924 | @end example | |
6925 | ||
6926 | This pragma is considered obsolescent, but is retained for | |
6927 | compatibility purposes. It is equivalent to: | |
6928 | ||
6929 | @example | |
6930 | pragma Profile (Rational); | |
6931 | @end example | |
6932 | ||
6933 | @node Pragma Ravenscar,Pragma Refined_Depends,Pragma Rational,Implementation Defined Pragmas | |
b71d4b62 | 6934 | @anchor{gnat_rm/implementation_defined_pragmas pragma-ravenscar}@anchor{ce} |
64d5610f ML |
6935 | @section Pragma Ravenscar |
6936 | ||
6937 | ||
6938 | Syntax: | |
6939 | ||
6940 | @example | |
6941 | pragma Ravenscar; | |
6942 | @end example | |
6943 | ||
6944 | This pragma is considered obsolescent, but is retained for | |
6945 | compatibility purposes. It is equivalent to: | |
6946 | ||
6947 | @example | |
6948 | pragma Profile (Ravenscar); | |
6949 | @end example | |
6950 | ||
6951 | which is the preferred method of setting the @code{Ravenscar} profile. | |
6952 | ||
6953 | @node Pragma Refined_Depends,Pragma Refined_Global,Pragma Ravenscar,Implementation Defined Pragmas | |
b71d4b62 | 6954 | @anchor{gnat_rm/implementation_defined_pragmas id33}@anchor{cf}@anchor{gnat_rm/implementation_defined_pragmas pragma-refined-depends}@anchor{d0} |
64d5610f ML |
6955 | @section Pragma Refined_Depends |
6956 | ||
6957 | ||
6958 | Syntax: | |
6959 | ||
6960 | @example | |
6961 | pragma Refined_Depends (DEPENDENCY_RELATION); | |
6962 | ||
6963 | DEPENDENCY_RELATION ::= | |
6964 | null | |
6965 | | (DEPENDENCY_CLAUSE @{, DEPENDENCY_CLAUSE@}) | |
6966 | ||
6967 | DEPENDENCY_CLAUSE ::= | |
6968 | OUTPUT_LIST =>[+] INPUT_LIST | |
6969 | | NULL_DEPENDENCY_CLAUSE | |
6970 | ||
6971 | NULL_DEPENDENCY_CLAUSE ::= null => INPUT_LIST | |
6972 | ||
6973 | OUTPUT_LIST ::= OUTPUT | (OUTPUT @{, OUTPUT@}) | |
6974 | ||
6975 | INPUT_LIST ::= null | INPUT | (INPUT @{, INPUT@}) | |
6976 | ||
6977 | OUTPUT ::= NAME | FUNCTION_RESULT | |
6978 | INPUT ::= NAME | |
6979 | ||
6980 | where FUNCTION_RESULT is a function Result attribute_reference | |
6981 | @end example | |
6982 | ||
6983 | For the semantics of this pragma, see the entry for aspect @code{Refined_Depends} in | |
6984 | the SPARK 2014 Reference Manual, section 6.1.5. | |
6985 | ||
6986 | @node Pragma Refined_Global,Pragma Refined_Post,Pragma Refined_Depends,Implementation Defined Pragmas | |
b71d4b62 | 6987 | @anchor{gnat_rm/implementation_defined_pragmas id34}@anchor{d1}@anchor{gnat_rm/implementation_defined_pragmas pragma-refined-global}@anchor{d2} |
64d5610f ML |
6988 | @section Pragma Refined_Global |
6989 | ||
6990 | ||
6991 | Syntax: | |
6992 | ||
6993 | @example | |
6994 | pragma Refined_Global (GLOBAL_SPECIFICATION); | |
6995 | ||
6996 | GLOBAL_SPECIFICATION ::= | |
6997 | null | |
6998 | | (GLOBAL_LIST) | |
6999 | | (MODED_GLOBAL_LIST @{, MODED_GLOBAL_LIST@}) | |
7000 | ||
7001 | MODED_GLOBAL_LIST ::= MODE_SELECTOR => GLOBAL_LIST | |
7002 | ||
7003 | MODE_SELECTOR ::= In_Out | Input | Output | Proof_In | |
7004 | GLOBAL_LIST ::= GLOBAL_ITEM | (GLOBAL_ITEM @{, GLOBAL_ITEM@}) | |
7005 | GLOBAL_ITEM ::= NAME | |
7006 | @end example | |
7007 | ||
7008 | For the semantics of this pragma, see the entry for aspect @code{Refined_Global} in | |
7009 | the SPARK 2014 Reference Manual, section 6.1.4. | |
7010 | ||
7011 | @node Pragma Refined_Post,Pragma Refined_State,Pragma Refined_Global,Implementation Defined Pragmas | |
b71d4b62 | 7012 | @anchor{gnat_rm/implementation_defined_pragmas id35}@anchor{d3}@anchor{gnat_rm/implementation_defined_pragmas pragma-refined-post}@anchor{d4} |
64d5610f ML |
7013 | @section Pragma Refined_Post |
7014 | ||
7015 | ||
7016 | Syntax: | |
7017 | ||
7018 | @example | |
7019 | pragma Refined_Post (boolean_EXPRESSION); | |
7020 | @end example | |
7021 | ||
7022 | For the semantics of this pragma, see the entry for aspect @code{Refined_Post} in | |
7023 | the SPARK 2014 Reference Manual, section 7.2.7. | |
7024 | ||
7025 | @node Pragma Refined_State,Pragma Relative_Deadline,Pragma Refined_Post,Implementation Defined Pragmas | |
b71d4b62 | 7026 | @anchor{gnat_rm/implementation_defined_pragmas id36}@anchor{d5}@anchor{gnat_rm/implementation_defined_pragmas pragma-refined-state}@anchor{d6} |
64d5610f ML |
7027 | @section Pragma Refined_State |
7028 | ||
7029 | ||
7030 | Syntax: | |
7031 | ||
7032 | @example | |
7033 | pragma Refined_State (REFINEMENT_LIST); | |
7034 | ||
7035 | REFINEMENT_LIST ::= | |
7036 | (REFINEMENT_CLAUSE @{, REFINEMENT_CLAUSE@}) | |
7037 | ||
7038 | REFINEMENT_CLAUSE ::= state_NAME => CONSTITUENT_LIST | |
7039 | ||
7040 | CONSTITUENT_LIST ::= | |
7041 | null | |
7042 | | CONSTITUENT | |
7043 | | (CONSTITUENT @{, CONSTITUENT@}) | |
7044 | ||
7045 | CONSTITUENT ::= object_NAME | state_NAME | |
7046 | @end example | |
7047 | ||
7048 | For the semantics of this pragma, see the entry for aspect @code{Refined_State} in | |
7049 | the SPARK 2014 Reference Manual, section 7.2.2. | |
7050 | ||
7051 | @node Pragma Relative_Deadline,Pragma Remote_Access_Type,Pragma Refined_State,Implementation Defined Pragmas | |
b71d4b62 | 7052 | @anchor{gnat_rm/implementation_defined_pragmas pragma-relative-deadline}@anchor{d7} |
64d5610f ML |
7053 | @section Pragma Relative_Deadline |
7054 | ||
7055 | ||
7056 | Syntax: | |
7057 | ||
7058 | @example | |
7059 | pragma Relative_Deadline (time_span_EXPRESSION); | |
7060 | @end example | |
7061 | ||
7062 | This pragma is standard in Ada 2005, but is available in all earlier | |
7063 | versions of Ada as an implementation-defined pragma. | |
7064 | See Ada 2012 Reference Manual for details. | |
7065 | ||
7066 | @node Pragma Remote_Access_Type,Pragma Rename_Pragma,Pragma Relative_Deadline,Implementation Defined Pragmas | |
b71d4b62 | 7067 | @anchor{gnat_rm/implementation_defined_pragmas id37}@anchor{d8}@anchor{gnat_rm/implementation_defined_pragmas pragma-remote-access-type}@anchor{d9} |
64d5610f ML |
7068 | @section Pragma Remote_Access_Type |
7069 | ||
7070 | ||
7071 | Syntax: | |
7072 | ||
7073 | @example | |
7074 | pragma Remote_Access_Type ([Entity =>] formal_access_type_LOCAL_NAME); | |
7075 | @end example | |
7076 | ||
7077 | This pragma appears in the formal part of a generic declaration. | |
7078 | It specifies an exception to the RM rule from E.2.2(17/2), which forbids | |
7079 | the use of a remote access to class-wide type as actual for a formal | |
7080 | access type. | |
7081 | ||
7082 | When this pragma applies to a formal access type @code{Entity}, that | |
7083 | type is treated as a remote access to class-wide type in the generic. | |
7084 | It must be a formal general access type, and its designated type must | |
7085 | be the class-wide type of a formal tagged limited private type from the | |
7086 | same generic declaration. | |
7087 | ||
7088 | In the generic unit, the formal type is subject to all restrictions | |
7089 | pertaining to remote access to class-wide types. At instantiation, the | |
7090 | actual type must be a remote access to class-wide type. | |
7091 | ||
7092 | @node Pragma Rename_Pragma,Pragma Restricted_Run_Time,Pragma Remote_Access_Type,Implementation Defined Pragmas | |
b71d4b62 | 7093 | @anchor{gnat_rm/implementation_defined_pragmas pragma-rename-pragma}@anchor{da} |
64d5610f ML |
7094 | @section Pragma Rename_Pragma |
7095 | ||
7096 | ||
7097 | @geindex Pragmas | |
7098 | @geindex synonyms | |
7099 | ||
7100 | Syntax: | |
7101 | ||
7102 | @example | |
7103 | pragma Rename_Pragma ( | |
7104 | [New_Name =>] IDENTIFIER, | |
7105 | [Renamed =>] pragma_IDENTIFIER); | |
7106 | @end example | |
7107 | ||
7108 | This pragma provides a mechanism for supplying new names for existing | |
7109 | pragmas. The @code{New_Name} identifier can subsequently be used as a synonym for | |
7110 | the Renamed pragma. For example, suppose you have code that was originally | |
7111 | developed on a compiler that supports Inline_Only as an implementation defined | |
7112 | pragma. And suppose the semantics of pragma Inline_Only are identical to (or at | |
7113 | least very similar to) the GNAT implementation defined pragma | |
7114 | Inline_Always. You could globally replace Inline_Only with Inline_Always. | |
7115 | ||
7116 | However, to avoid that source modification, you could instead add a | |
7117 | configuration pragma: | |
7118 | ||
7119 | @example | |
7120 | pragma Rename_Pragma ( | |
7121 | New_Name => Inline_Only, | |
7122 | Renamed => Inline_Always); | |
7123 | @end example | |
7124 | ||
7125 | Then GNAT will treat “pragma Inline_Only …” as if you had written | |
7126 | “pragma Inline_Always …”. | |
7127 | ||
7128 | Pragma Inline_Only will not necessarily mean the same thing as the other Ada | |
7129 | compiler; it’s up to you to make sure the semantics are close enough. | |
7130 | ||
7131 | @node Pragma Restricted_Run_Time,Pragma Restriction_Warnings,Pragma Rename_Pragma,Implementation Defined Pragmas | |
b71d4b62 | 7132 | @anchor{gnat_rm/implementation_defined_pragmas pragma-restricted-run-time}@anchor{db} |
64d5610f ML |
7133 | @section Pragma Restricted_Run_Time |
7134 | ||
7135 | ||
7136 | Syntax: | |
7137 | ||
7138 | @example | |
7139 | pragma Restricted_Run_Time; | |
7140 | @end example | |
7141 | ||
7142 | This pragma is considered obsolescent, but is retained for | |
7143 | compatibility purposes. It is equivalent to: | |
7144 | ||
7145 | @example | |
7146 | pragma Profile (Restricted); | |
7147 | @end example | |
7148 | ||
7149 | which is the preferred method of setting the restricted run time | |
7150 | profile. | |
7151 | ||
7152 | @node Pragma Restriction_Warnings,Pragma Reviewable,Pragma Restricted_Run_Time,Implementation Defined Pragmas | |
b71d4b62 | 7153 | @anchor{gnat_rm/implementation_defined_pragmas pragma-restriction-warnings}@anchor{dc} |
64d5610f ML |
7154 | @section Pragma Restriction_Warnings |
7155 | ||
7156 | ||
7157 | Syntax: | |
7158 | ||
7159 | @example | |
7160 | pragma Restriction_Warnings | |
7161 | (restriction_IDENTIFIER @{, restriction_IDENTIFIER@}); | |
7162 | @end example | |
7163 | ||
7164 | This pragma allows a series of restriction identifiers to be | |
7165 | specified (the list of allowed identifiers is the same as for | |
7166 | pragma @code{Restrictions}). For each of these identifiers | |
7167 | the compiler checks for violations of the restriction, but | |
7168 | generates a warning message rather than an error message | |
7169 | if the restriction is violated. | |
7170 | ||
7171 | One use of this is in situations where you want to know | |
7172 | about violations of a restriction, but you want to ignore some of | |
7173 | these violations. Consider this example, where you want to set | |
7174 | Ada_95 mode and enable style checks, but you want to know about | |
7175 | any other use of implementation pragmas: | |
7176 | ||
7177 | @example | |
7178 | pragma Restriction_Warnings (No_Implementation_Pragmas); | |
7179 | pragma Warnings (Off, "violation of No_Implementation_Pragmas"); | |
7180 | pragma Ada_95; | |
7181 | pragma Style_Checks ("2bfhkM160"); | |
7182 | pragma Warnings (On, "violation of No_Implementation_Pragmas"); | |
7183 | @end example | |
7184 | ||
7185 | By including the above lines in a configuration pragmas file, | |
7186 | the Ada_95 and Style_Checks pragmas are accepted without | |
7187 | generating a warning, but any other use of implementation | |
7188 | defined pragmas will cause a warning to be generated. | |
7189 | ||
7190 | @node Pragma Reviewable,Pragma Secondary_Stack_Size,Pragma Restriction_Warnings,Implementation Defined Pragmas | |
b71d4b62 | 7191 | @anchor{gnat_rm/implementation_defined_pragmas pragma-reviewable}@anchor{dd} |
64d5610f ML |
7192 | @section Pragma Reviewable |
7193 | ||
7194 | ||
7195 | Syntax: | |
7196 | ||
7197 | @example | |
7198 | pragma Reviewable; | |
7199 | @end example | |
7200 | ||
7201 | This pragma is an RM-defined standard pragma, but has no effect on the | |
7202 | program being compiled, or on the code generated for the program. | |
7203 | ||
7204 | To obtain the required output specified in RM H.3.1, the compiler must be | |
7205 | run with various special switches as follows: | |
7206 | ||
7207 | ||
7208 | @itemize * | |
7209 | ||
7210 | @item | |
1acce141 | 7211 | @emph{Where compiler-generated run-time checks remain} |
64d5610f | 7212 | |
1acce141 | 7213 | The switch @emph{-gnatGL} |
64d5610f ML |
7214 | may be used to list the expanded code in pseudo-Ada form. |
7215 | Runtime checks show up in the listing either as explicit | |
7216 | checks or operators marked with @{@} to indicate a check is present. | |
7217 | ||
7218 | @item | |
1acce141 | 7219 | @emph{An identification of known exceptions at compile time} |
64d5610f | 7220 | |
1acce141 | 7221 | If the program is compiled with @emph{-gnatwa}, |
64d5610f ML |
7222 | the compiler warning messages will indicate all cases where the compiler |
7223 | detects that an exception is certain to occur at run time. | |
7224 | ||
7225 | @item | |
1acce141 | 7226 | @emph{Possible reads of uninitialized variables} |
64d5610f ML |
7227 | |
7228 | The compiler warns of many such cases, but its output is incomplete. | |
7229 | @end itemize | |
7230 | ||
7231 | ||
7232 | A supplemental static analysis tool | |
7233 | may be used to obtain a comprehensive list of all | |
7234 | possible points at which uninitialized data may be read. | |
7235 | ||
7236 | ||
7237 | @itemize * | |
7238 | ||
7239 | @item | |
1acce141 | 7240 | @emph{Where run-time support routines are implicitly invoked} |
64d5610f | 7241 | |
1acce141 | 7242 | In the output from @emph{-gnatGL}, |
64d5610f ML |
7243 | run-time calls are explicitly listed as calls to the relevant |
7244 | run-time routine. | |
7245 | ||
7246 | @item | |
1acce141 | 7247 | @emph{Object code listing} |
64d5610f | 7248 | |
1acce141 | 7249 | This may be obtained either by using the @emph{-S} switch, |
64d5610f ML |
7250 | or the objdump utility. |
7251 | ||
7252 | @item | |
1acce141 | 7253 | @emph{Constructs known to be erroneous at compile time} |
64d5610f | 7254 | |
1acce141 | 7255 | These are identified by warnings issued by the compiler (use @emph{-gnatwa}). |
64d5610f ML |
7256 | |
7257 | @item | |
1acce141 | 7258 | @emph{Stack usage information} |
64d5610f ML |
7259 | |
7260 | Static stack usage data (maximum per-subprogram) can be obtained via the | |
1acce141 YM |
7261 | @emph{-fstack-usage} switch to the compiler. |
7262 | Dynamic stack usage data (per task) can be obtained via the @emph{-u} switch | |
64d5610f ML |
7263 | to gnatbind |
7264 | @end itemize | |
7265 | ||
7266 | ||
7267 | ||
7268 | @itemize * | |
7269 | ||
7270 | @item | |
1acce141 | 7271 | @emph{Object code listing of entire partition} |
64d5610f | 7272 | |
1acce141 | 7273 | This can be obtained by compiling the partition with @emph{-S}, |
64d5610f ML |
7274 | or by applying objdump |
7275 | to all the object files that are part of the partition. | |
7276 | ||
7277 | @item | |
1acce141 | 7278 | @emph{A description of the run-time model} |
64d5610f ML |
7279 | |
7280 | The full sources of the run-time are available, and the documentation of | |
7281 | these routines describes how these run-time routines interface to the | |
7282 | underlying operating system facilities. | |
7283 | ||
7284 | @item | |
1acce141 | 7285 | @emph{Control and data-flow information} |
64d5610f ML |
7286 | @end itemize |
7287 | ||
7288 | ||
7289 | A supplemental static analysis tool | |
7290 | may be used to obtain complete control and data-flow information, as well as | |
7291 | comprehensive messages identifying possible problems based on this | |
7292 | information. | |
7293 | ||
7294 | @node Pragma Secondary_Stack_Size,Pragma Share_Generic,Pragma Reviewable,Implementation Defined Pragmas | |
b71d4b62 | 7295 | @anchor{gnat_rm/implementation_defined_pragmas id38}@anchor{de}@anchor{gnat_rm/implementation_defined_pragmas pragma-secondary-stack-size}@anchor{df} |
64d5610f ML |
7296 | @section Pragma Secondary_Stack_Size |
7297 | ||
7298 | ||
7299 | Syntax: | |
7300 | ||
7301 | @example | |
7302 | pragma Secondary_Stack_Size (integer_EXPRESSION); | |
7303 | @end example | |
7304 | ||
7305 | This pragma appears within the task definition of a single task declaration | |
7306 | or a task type declaration (like pragma @code{Storage_Size}) and applies to all | |
7307 | task objects of that type. The argument specifies the size of the secondary | |
7308 | stack to be used by these task objects, and must be of an integer type. The | |
7309 | secondary stack is used to handle functions that return a variable-sized | |
7310 | result, for example a function returning an unconstrained String. | |
7311 | ||
7312 | Note this pragma only applies to targets using fixed secondary stacks, like | |
7313 | VxWorks 653 and bare board targets, where a fixed block for the | |
7314 | secondary stack is allocated from the primary stack of the task. By default, | |
7315 | these targets assign a percentage of the primary stack for the secondary stack, | |
7316 | as defined by @code{System.Parameter.Sec_Stack_Percentage}. With this pragma, | |
7317 | an @code{integer_EXPRESSION} of bytes is assigned from the primary stack instead. | |
7318 | ||
7319 | For most targets, the pragma does not apply as the secondary stack grows on | |
7320 | demand: allocated as a chain of blocks in the heap. The default size of these | |
7321 | blocks can be modified via the @code{-D} binder option as described in | |
7322 | @cite{GNAT User’s Guide}. | |
7323 | ||
7324 | Note that no check is made to see if the secondary stack can fit inside the | |
7325 | primary stack. | |
7326 | ||
7327 | Note the pragma cannot appear when the restriction @code{No_Secondary_Stack} | |
7328 | is in effect. | |
7329 | ||
7330 | @node Pragma Share_Generic,Pragma Shared,Pragma Secondary_Stack_Size,Implementation Defined Pragmas | |
b71d4b62 | 7331 | @anchor{gnat_rm/implementation_defined_pragmas pragma-share-generic}@anchor{e0} |
64d5610f ML |
7332 | @section Pragma Share_Generic |
7333 | ||
7334 | ||
7335 | Syntax: | |
7336 | ||
7337 | @example | |
7338 | pragma Share_Generic (GNAME @{, GNAME@}); | |
7339 | ||
7340 | GNAME ::= generic_unit_NAME | generic_instance_NAME | |
7341 | @end example | |
7342 | ||
7343 | This pragma is provided for compatibility with Dec Ada 83. It has | |
7344 | no effect in GNAT (which does not implement shared generics), other | |
7345 | than to check that the given names are all names of generic units or | |
7346 | generic instances. | |
7347 | ||
7348 | @node Pragma Shared,Pragma Short_Circuit_And_Or,Pragma Share_Generic,Implementation Defined Pragmas | |
b71d4b62 | 7349 | @anchor{gnat_rm/implementation_defined_pragmas id39}@anchor{e1}@anchor{gnat_rm/implementation_defined_pragmas pragma-shared}@anchor{e2} |
64d5610f ML |
7350 | @section Pragma Shared |
7351 | ||
7352 | ||
7353 | This pragma is provided for compatibility with Ada 83. The syntax and | |
7354 | semantics are identical to pragma Atomic. | |
7355 | ||
7356 | @node Pragma Short_Circuit_And_Or,Pragma Short_Descriptors,Pragma Shared,Implementation Defined Pragmas | |
b71d4b62 | 7357 | @anchor{gnat_rm/implementation_defined_pragmas pragma-short-circuit-and-or}@anchor{e3} |
64d5610f ML |
7358 | @section Pragma Short_Circuit_And_Or |
7359 | ||
7360 | ||
7361 | Syntax: | |
7362 | ||
7363 | @example | |
7364 | pragma Short_Circuit_And_Or; | |
7365 | @end example | |
7366 | ||
7367 | This configuration pragma causes any occurrence of the AND operator applied to | |
7368 | operands of type Standard.Boolean to be short-circuited (i.e. the AND operator | |
7369 | is treated as if it were AND THEN). Or is similarly treated as OR ELSE. This | |
7370 | may be useful in the context of certification protocols requiring the use of | |
7371 | short-circuited logical operators. If this configuration pragma occurs locally | |
7372 | within the file being compiled, it applies only to the file being compiled. | |
7373 | There is no requirement that all units in a partition use this option. | |
7374 | ||
04d6c745 | 7375 | @node Pragma Short_Descriptors,Pragma Side_Effects,Pragma Short_Circuit_And_Or,Implementation Defined Pragmas |
b71d4b62 | 7376 | @anchor{gnat_rm/implementation_defined_pragmas pragma-short-descriptors}@anchor{e4} |
64d5610f ML |
7377 | @section Pragma Short_Descriptors |
7378 | ||
7379 | ||
7380 | Syntax: | |
7381 | ||
7382 | @example | |
7383 | pragma Short_Descriptors; | |
7384 | @end example | |
7385 | ||
7386 | This pragma is provided for compatibility with other Ada implementations. It | |
7387 | is recognized but ignored by all current versions of GNAT. | |
7388 | ||
04d6c745 YM |
7389 | @node Pragma Side_Effects,Pragma Simple_Storage_Pool_Type,Pragma Short_Descriptors,Implementation Defined Pragmas |
7390 | @anchor{gnat_rm/implementation_defined_pragmas id40}@anchor{e5}@anchor{gnat_rm/implementation_defined_pragmas pragma-side-effects}@anchor{e6} | |
7391 | @section Pragma Side_Effects | |
7392 | ||
7393 | ||
7394 | Syntax: | |
7395 | ||
7396 | @example | |
7397 | pragma Side_Effects [ (static_boolean_EXPRESSION) ]; | |
7398 | @end example | |
7399 | ||
7400 | For the semantics of this pragma, see the entry for aspect | |
7401 | @code{Side_Effects} in the SPARK Reference Manual, section 6.1.11. | |
7402 | ||
7403 | @node Pragma Simple_Storage_Pool_Type,Pragma Source_File_Name,Pragma Side_Effects,Implementation Defined Pragmas | |
7404 | @anchor{gnat_rm/implementation_defined_pragmas id41}@anchor{e7}@anchor{gnat_rm/implementation_defined_pragmas pragma-simple-storage-pool-type}@anchor{e8} | |
64d5610f ML |
7405 | @section Pragma Simple_Storage_Pool_Type |
7406 | ||
7407 | ||
7408 | @geindex Storage pool | |
7409 | @geindex simple | |
7410 | ||
7411 | @geindex Simple storage pool | |
7412 | ||
7413 | Syntax: | |
7414 | ||
7415 | @example | |
7416 | pragma Simple_Storage_Pool_Type (type_LOCAL_NAME); | |
7417 | @end example | |
7418 | ||
7419 | A type can be established as a ‘simple storage pool type’ by applying | |
7420 | the representation pragma @code{Simple_Storage_Pool_Type} to the type. | |
7421 | A type named in the pragma must be a library-level immutably limited record | |
7422 | type or limited tagged type declared immediately within a package declaration. | |
7423 | The type can also be a limited private type whose full type is allowed as | |
7424 | a simple storage pool type. | |
7425 | ||
7426 | For a simple storage pool type @code{SSP}, nonabstract primitive subprograms | |
7427 | @code{Allocate}, @code{Deallocate}, and @code{Storage_Size} can be declared that | |
7428 | are subtype conformant with the following subprogram declarations: | |
7429 | ||
7430 | @example | |
7431 | procedure Allocate | |
7432 | (Pool : in out SSP; | |
7433 | Storage_Address : out System.Address; | |
7434 | Size_In_Storage_Elements : System.Storage_Elements.Storage_Count; | |
7435 | Alignment : System.Storage_Elements.Storage_Count); | |
7436 | ||
7437 | procedure Deallocate | |
7438 | (Pool : in out SSP; | |
7439 | Storage_Address : System.Address; | |
7440 | Size_In_Storage_Elements : System.Storage_Elements.Storage_Count; | |
7441 | Alignment : System.Storage_Elements.Storage_Count); | |
7442 | ||
7443 | function Storage_Size (Pool : SSP) | |
7444 | return System.Storage_Elements.Storage_Count; | |
7445 | @end example | |
7446 | ||
7447 | Procedure @code{Allocate} must be declared, whereas @code{Deallocate} and | |
7448 | @code{Storage_Size} are optional. If @code{Deallocate} is not declared, then | |
7449 | applying an unchecked deallocation has no effect other than to set its actual | |
7450 | parameter to null. If @code{Storage_Size} is not declared, then the | |
7451 | @code{Storage_Size} attribute applied to an access type associated with | |
7452 | a pool object of type SSP returns zero. Additional operations can be declared | |
7453 | for a simple storage pool type (such as for supporting a mark/release | |
7454 | storage-management discipline). | |
7455 | ||
7456 | An object of a simple storage pool type can be associated with an access | |
7457 | type by specifying the attribute | |
04d6c745 | 7458 | @ref{e9,,Simple_Storage_Pool}. For example: |
64d5610f ML |
7459 | |
7460 | @example | |
7461 | My_Pool : My_Simple_Storage_Pool_Type; | |
7462 | ||
7463 | type Acc is access My_Data_Type; | |
7464 | ||
7465 | for Acc'Simple_Storage_Pool use My_Pool; | |
7466 | @end example | |
7467 | ||
04d6c745 | 7468 | See attribute @ref{e9,,Simple_Storage_Pool} |
64d5610f ML |
7469 | for further details. |
7470 | ||
7471 | @node Pragma Source_File_Name,Pragma Source_File_Name_Project,Pragma Simple_Storage_Pool_Type,Implementation Defined Pragmas | |
04d6c745 | 7472 | @anchor{gnat_rm/implementation_defined_pragmas id42}@anchor{ea}@anchor{gnat_rm/implementation_defined_pragmas pragma-source-file-name}@anchor{eb} |
64d5610f ML |
7473 | @section Pragma Source_File_Name |
7474 | ||
7475 | ||
7476 | Syntax: | |
7477 | ||
7478 | @example | |
7479 | pragma Source_File_Name ( | |
7480 | [Unit_Name =>] unit_NAME, | |
7481 | Spec_File_Name => STRING_LITERAL, | |
7482 | [Index => INTEGER_LITERAL]); | |
7483 | ||
7484 | pragma Source_File_Name ( | |
7485 | [Unit_Name =>] unit_NAME, | |
7486 | Body_File_Name => STRING_LITERAL, | |
7487 | [Index => INTEGER_LITERAL]); | |
7488 | @end example | |
7489 | ||
7490 | Use this to override the normal naming convention. It is a configuration | |
7491 | pragma, and so has the usual applicability of configuration pragmas | |
7492 | (i.e., it applies to either an entire partition, or to all units in a | |
7493 | compilation, or to a single unit, depending on how it is used). | |
7494 | @code{unit_name} is mapped to @code{file_name_literal}. The identifier for | |
7495 | the second argument is required, and indicates whether this is the file | |
7496 | name for the spec or for the body. | |
7497 | ||
7498 | The optional Index argument should be used when a file contains multiple | |
7499 | units, and when you do not want to use @code{gnatchop} to separate then | |
7500 | into multiple files (which is the recommended procedure to limit the | |
7501 | number of recompilations that are needed when some sources change). | |
7502 | For instance, if the source file @code{source.ada} contains | |
7503 | ||
7504 | @example | |
7505 | package B is | |
7506 | ... | |
7507 | end B; | |
7508 | ||
7509 | with B; | |
7510 | procedure A is | |
7511 | begin | |
7512 | .. | |
7513 | end A; | |
7514 | @end example | |
7515 | ||
7516 | you could use the following configuration pragmas: | |
7517 | ||
7518 | @example | |
7519 | pragma Source_File_Name | |
7520 | (B, Spec_File_Name => "source.ada", Index => 1); | |
7521 | pragma Source_File_Name | |
7522 | (A, Body_File_Name => "source.ada", Index => 2); | |
7523 | @end example | |
7524 | ||
7525 | Note that the @code{gnatname} utility can also be used to generate those | |
7526 | configuration pragmas. | |
7527 | ||
7528 | Another form of the @code{Source_File_Name} pragma allows | |
7529 | the specification of patterns defining alternative file naming schemes | |
7530 | to apply to all files. | |
7531 | ||
7532 | @example | |
7533 | pragma Source_File_Name | |
7534 | ( [Spec_File_Name =>] STRING_LITERAL | |
7535 | [,[Casing =>] CASING_SPEC] | |
7536 | [,[Dot_Replacement =>] STRING_LITERAL]); | |
7537 | ||
7538 | pragma Source_File_Name | |
7539 | ( [Body_File_Name =>] STRING_LITERAL | |
7540 | [,[Casing =>] CASING_SPEC] | |
7541 | [,[Dot_Replacement =>] STRING_LITERAL]); | |
7542 | ||
7543 | pragma Source_File_Name | |
7544 | ( [Subunit_File_Name =>] STRING_LITERAL | |
7545 | [,[Casing =>] CASING_SPEC] | |
7546 | [,[Dot_Replacement =>] STRING_LITERAL]); | |
7547 | ||
7548 | CASING_SPEC ::= Lowercase | Uppercase | Mixedcase | |
7549 | @end example | |
7550 | ||
7551 | The first argument is a pattern that contains a single asterisk indicating | |
7552 | the point at which the unit name is to be inserted in the pattern string | |
7553 | to form the file name. The second argument is optional. If present it | |
7554 | specifies the casing of the unit name in the resulting file name string. | |
7555 | The default is lower case. Finally the third argument allows for systematic | |
7556 | replacement of any dots in the unit name by the specified string literal. | |
7557 | ||
7558 | Note that Source_File_Name pragmas should not be used if you are using | |
7559 | project files. The reason for this rule is that the project manager is not | |
7560 | aware of these pragmas, and so other tools that use the project file would not | |
7561 | be aware of the intended naming conventions. If you are using project files, | |
7562 | file naming is controlled by Source_File_Name_Project pragmas, which are | |
7563 | usually supplied automatically by the project manager. A pragma | |
04d6c745 | 7564 | Source_File_Name cannot appear after a @ref{ec,,Pragma Source_File_Name_Project}. |
64d5610f ML |
7565 | |
7566 | For more details on the use of the @code{Source_File_Name} pragma, see the | |
7567 | sections on @cite{Using Other File Names} and @cite{Alternative File Naming Schemes} | |
7568 | in the @cite{GNAT User’s Guide}. | |
7569 | ||
7570 | @node Pragma Source_File_Name_Project,Pragma Source_Reference,Pragma Source_File_Name,Implementation Defined Pragmas | |
04d6c745 | 7571 | @anchor{gnat_rm/implementation_defined_pragmas id43}@anchor{ed}@anchor{gnat_rm/implementation_defined_pragmas pragma-source-file-name-project}@anchor{ec} |
64d5610f ML |
7572 | @section Pragma Source_File_Name_Project |
7573 | ||
7574 | ||
7575 | This pragma has the same syntax and semantics as pragma Source_File_Name. | |
7576 | It is only allowed as a stand-alone configuration pragma. | |
04d6c745 | 7577 | It cannot appear after a @ref{eb,,Pragma Source_File_Name}, and |
64d5610f ML |
7578 | most importantly, once pragma Source_File_Name_Project appears, |
7579 | no further Source_File_Name pragmas are allowed. | |
7580 | ||
7581 | The intention is that Source_File_Name_Project pragmas are always | |
7582 | generated by the Project Manager in a manner consistent with the naming | |
7583 | specified in a project file, and when naming is controlled in this manner, | |
7584 | it is not permissible to attempt to modify this naming scheme using | |
7585 | Source_File_Name or Source_File_Name_Project pragmas (which would not be | |
7586 | known to the project manager). | |
7587 | ||
7588 | @node Pragma Source_Reference,Pragma SPARK_Mode,Pragma Source_File_Name_Project,Implementation Defined Pragmas | |
04d6c745 | 7589 | @anchor{gnat_rm/implementation_defined_pragmas pragma-source-reference}@anchor{ee} |
64d5610f ML |
7590 | @section Pragma Source_Reference |
7591 | ||
7592 | ||
7593 | Syntax: | |
7594 | ||
7595 | @example | |
7596 | pragma Source_Reference (INTEGER_LITERAL, STRING_LITERAL); | |
7597 | @end example | |
7598 | ||
7599 | This pragma must appear as the first line of a source file. | |
7600 | @code{integer_literal} is the logical line number of the line following | |
7601 | the pragma line (for use in error messages and debugging | |
7602 | information). @code{string_literal} is a static string constant that | |
7603 | specifies the file name to be used in error messages and debugging | |
7604 | information. This is most notably used for the output of @code{gnatchop} | |
1acce141 | 7605 | with the @emph{-r} switch, to make sure that the original unchopped |
64d5610f ML |
7606 | source file is the one referred to. |
7607 | ||
7608 | The second argument must be a string literal, it cannot be a static | |
7609 | string expression other than a string literal. This is because its value | |
7610 | is needed for error messages issued by all phases of the compiler. | |
7611 | ||
7612 | @node Pragma SPARK_Mode,Pragma Static_Elaboration_Desired,Pragma Source_Reference,Implementation Defined Pragmas | |
04d6c745 | 7613 | @anchor{gnat_rm/implementation_defined_pragmas id44}@anchor{ef}@anchor{gnat_rm/implementation_defined_pragmas pragma-spark-mode}@anchor{f0} |
64d5610f ML |
7614 | @section Pragma SPARK_Mode |
7615 | ||
7616 | ||
7617 | Syntax: | |
7618 | ||
7619 | @example | |
7620 | pragma SPARK_Mode [(On | Off)] ; | |
7621 | @end example | |
7622 | ||
7623 | In general a program can have some parts that are in SPARK 2014 (and | |
7624 | follow all the rules in the SPARK Reference Manual), and some parts | |
7625 | that are full Ada 2012. | |
7626 | ||
7627 | The SPARK_Mode pragma is used to identify which parts are in SPARK | |
7628 | 2014 (by default programs are in full Ada). The SPARK_Mode pragma can | |
7629 | be used in the following places: | |
7630 | ||
7631 | ||
7632 | @itemize * | |
7633 | ||
7634 | @item | |
7635 | As a configuration pragma, in which case it sets the default mode for | |
7636 | all units compiled with this pragma. | |
7637 | ||
7638 | @item | |
7639 | Immediately following a library-level subprogram spec | |
7640 | ||
7641 | @item | |
7642 | Immediately within a library-level package body | |
7643 | ||
7644 | @item | |
7645 | Immediately following the @code{private} keyword of a library-level | |
7646 | package spec | |
7647 | ||
7648 | @item | |
7649 | Immediately following the @code{begin} keyword of a library-level | |
7650 | package body | |
7651 | ||
7652 | @item | |
7653 | Immediately within a library-level subprogram body | |
7654 | @end itemize | |
7655 | ||
7656 | Normally a subprogram or package spec/body inherits the current mode | |
7657 | that is active at the point it is declared. But this can be overridden | |
7658 | by pragma within the spec or body as above. | |
7659 | ||
7660 | The basic consistency rule is that you can’t turn SPARK_Mode back | |
7661 | @code{On}, once you have explicitly (with a pragma) turned if | |
7662 | @code{Off}. So the following rules apply: | |
7663 | ||
7664 | If a subprogram spec has SPARK_Mode @code{Off}, then the body must | |
7665 | also have SPARK_Mode @code{Off}. | |
7666 | ||
7667 | For a package, we have four parts: | |
7668 | ||
7669 | ||
7670 | @itemize * | |
7671 | ||
7672 | @item | |
7673 | the package public declarations | |
7674 | ||
7675 | @item | |
7676 | the package private part | |
7677 | ||
7678 | @item | |
7679 | the body of the package | |
7680 | ||
7681 | @item | |
7682 | the elaboration code after @code{begin} | |
7683 | @end itemize | |
7684 | ||
7685 | For a package, the rule is that if you explicitly turn SPARK_Mode | |
7686 | @code{Off} for any part, then all the following parts must have | |
7687 | SPARK_Mode @code{Off}. Note that this may require repeating a pragma | |
7688 | SPARK_Mode (@code{Off}) in the body. For example, if we have a | |
7689 | configuration pragma SPARK_Mode (@code{On}) that turns the mode on by | |
7690 | default everywhere, and one particular package spec has pragma | |
7691 | SPARK_Mode (@code{Off}), then that pragma will need to be repeated in | |
7692 | the package body. | |
7693 | ||
7694 | @node Pragma Static_Elaboration_Desired,Pragma Stream_Convert,Pragma SPARK_Mode,Implementation Defined Pragmas | |
04d6c745 | 7695 | @anchor{gnat_rm/implementation_defined_pragmas pragma-static-elaboration-desired}@anchor{f1} |
64d5610f ML |
7696 | @section Pragma Static_Elaboration_Desired |
7697 | ||
7698 | ||
7699 | Syntax: | |
7700 | ||
7701 | @example | |
7702 | pragma Static_Elaboration_Desired; | |
7703 | @end example | |
7704 | ||
7705 | This pragma is used to indicate that the compiler should attempt to initialize | |
7706 | statically the objects declared in the library unit to which the pragma applies, | |
7707 | when these objects are initialized (explicitly or implicitly) by an aggregate. | |
7708 | In the absence of this pragma, aggregates in object declarations are expanded | |
7709 | into assignments and loops, even when the aggregate components are static | |
7710 | constants. When the aggregate is present the compiler builds a static expression | |
7711 | that requires no run-time code, so that the initialized object can be placed in | |
7712 | read-only data space. If the components are not static, or the aggregate has | |
7713 | more that 100 components, the compiler emits a warning that the pragma cannot | |
7714 | be obeyed. (See also the restriction No_Implicit_Loops, which supports static | |
7715 | construction of larger aggregates with static components that include an others | |
7716 | choice.) | |
7717 | ||
7718 | @node Pragma Stream_Convert,Pragma Style_Checks,Pragma Static_Elaboration_Desired,Implementation Defined Pragmas | |
04d6c745 | 7719 | @anchor{gnat_rm/implementation_defined_pragmas pragma-stream-convert}@anchor{f2} |
64d5610f ML |
7720 | @section Pragma Stream_Convert |
7721 | ||
7722 | ||
7723 | Syntax: | |
7724 | ||
7725 | @example | |
7726 | pragma Stream_Convert ( | |
7727 | [Entity =>] type_LOCAL_NAME, | |
7728 | [Read =>] function_NAME, | |
7729 | [Write =>] function_NAME); | |
7730 | @end example | |
7731 | ||
7732 | This pragma provides an efficient way of providing user-defined stream | |
7733 | attributes. Not only is it simpler to use than specifying the attributes | |
7734 | directly, but more importantly, it allows the specification to be made in such | |
7735 | a way that the predefined unit Ada.Streams is not loaded unless it is actually | |
7736 | needed (i.e. unless the stream attributes are actually used); the use of | |
7737 | the Stream_Convert pragma adds no overhead at all, unless the stream | |
7738 | attributes are actually used on the designated type. | |
7739 | ||
7740 | The first argument specifies the type for which stream functions are | |
7741 | provided. The second parameter provides a function used to read values | |
7742 | of this type. It must name a function whose argument type may be any | |
7743 | subtype, and whose returned type must be the type given as the first | |
7744 | argument to the pragma. | |
7745 | ||
7746 | The meaning of the @code{Read} parameter is that if a stream attribute directly | |
7747 | or indirectly specifies reading of the type given as the first parameter, | |
7748 | then a value of the type given as the argument to the Read function is | |
7749 | read from the stream, and then the Read function is used to convert this | |
7750 | to the required target type. | |
7751 | ||
7752 | Similarly the @code{Write} parameter specifies how to treat write attributes | |
7753 | that directly or indirectly apply to the type given as the first parameter. | |
7754 | It must have an input parameter of the type specified by the first parameter, | |
7755 | and the return type must be the same as the input type of the Read function. | |
7756 | The effect is to first call the Write function to convert to the given stream | |
7757 | type, and then write the result type to the stream. | |
7758 | ||
7759 | The Read and Write functions must not be overloaded subprograms. If necessary | |
7760 | renamings can be supplied to meet this requirement. | |
7761 | The usage of this attribute is best illustrated by a simple example, taken | |
7762 | from the GNAT implementation of package Ada.Strings.Unbounded: | |
7763 | ||
7764 | @example | |
7765 | function To_Unbounded (S : String) return Unbounded_String | |
7766 | renames To_Unbounded_String; | |
7767 | ||
7768 | pragma Stream_Convert | |
7769 | (Unbounded_String, To_Unbounded, To_String); | |
7770 | @end example | |
7771 | ||
7772 | The specifications of the referenced functions, as given in the Ada | |
7773 | Reference Manual are: | |
7774 | ||
7775 | @example | |
7776 | function To_Unbounded_String (Source : String) | |
7777 | return Unbounded_String; | |
7778 | ||
7779 | function To_String (Source : Unbounded_String) | |
7780 | return String; | |
7781 | @end example | |
7782 | ||
7783 | The effect is that if the value of an unbounded string is written to a stream, | |
7784 | then the representation of the item in the stream is in the same format that | |
7785 | would be used for @code{Standard.String'Output}, and this same representation | |
7786 | is expected when a value of this type is read from the stream. Note that the | |
7787 | value written always includes the bounds, even for Unbounded_String’Write, | |
7788 | since Unbounded_String is not an array type. | |
7789 | ||
7790 | Note that the @code{Stream_Convert} pragma is not effective in the case of | |
7791 | a derived type of a non-limited tagged type. If such a type is specified then | |
7792 | the pragma is silently ignored, and the default implementation of the stream | |
7793 | attributes is used instead. | |
7794 | ||
7795 | @node Pragma Style_Checks,Pragma Subtitle,Pragma Stream_Convert,Implementation Defined Pragmas | |
04d6c745 | 7796 | @anchor{gnat_rm/implementation_defined_pragmas pragma-style-checks}@anchor{f3} |
64d5610f ML |
7797 | @section Pragma Style_Checks |
7798 | ||
7799 | ||
7800 | Syntax: | |
7801 | ||
7802 | @example | |
7803 | pragma Style_Checks (string_LITERAL | ALL_CHECKS | | |
7804 | On | Off [, LOCAL_NAME]); | |
7805 | @end example | |
7806 | ||
7807 | This pragma is used in conjunction with compiler switches to control the | |
7808 | built in style checking provided by GNAT. The compiler switches, if set, | |
7809 | provide an initial setting for the switches, and this pragma may be used | |
7810 | to modify these settings, or the settings may be provided entirely by | |
7811 | the use of the pragma. This pragma can be used anywhere that a pragma | |
7812 | is legal, including use as a configuration pragma (including use in | |
7813 | the @code{gnat.adc} file). | |
7814 | ||
7815 | The form with a string literal specifies which style options are to be | |
7816 | activated. These are additive, so they apply in addition to any previously | |
7817 | set style check options. The codes for the options are the same as those | |
1acce141 | 7818 | used in the @emph{-gnaty} switch to @emph{gcc} or @emph{gnatmake}. |
64d5610f ML |
7819 | For example the following two methods can be used to enable |
7820 | layout checking: | |
7821 | ||
7822 | ||
7823 | @itemize * | |
7824 | ||
7825 | @item | |
7826 | @example | |
7827 | pragma Style_Checks ("l"); | |
7828 | @end example | |
7829 | ||
7830 | @item | |
7831 | @example | |
7832 | gcc -c -gnatyl ... | |
7833 | @end example | |
7834 | @end itemize | |
7835 | ||
7836 | The form @code{ALL_CHECKS} activates all standard checks (its use is equivalent | |
7837 | to the use of the @code{gnaty} switch with no options. | |
7838 | See the @cite{GNAT User’s Guide} for details.) | |
7839 | ||
7840 | Note: the behavior is slightly different in GNAT mode (@code{-gnatg} used). | |
7841 | In this case, @code{ALL_CHECKS} implies the standard set of GNAT mode style check | |
7842 | options (i.e. equivalent to @code{-gnatyg}). | |
7843 | ||
7844 | The forms with @code{Off} and @code{On} | |
7845 | can be used to temporarily disable style checks | |
7846 | as shown in the following example: | |
7847 | ||
7848 | @example | |
7849 | pragma Style_Checks ("k"); -- requires keywords in lower case | |
7850 | pragma Style_Checks (Off); -- turn off style checks | |
7851 | NULL; -- this will not generate an error message | |
7852 | pragma Style_Checks (On); -- turn style checks back on | |
7853 | NULL; -- this will generate an error message | |
7854 | @end example | |
7855 | ||
7856 | Finally the two argument form is allowed only if the first argument is | |
7857 | @code{On} or @code{Off}. The effect is to turn of semantic style checks | |
7858 | for the specified entity, as shown in the following example: | |
7859 | ||
7860 | @example | |
7861 | pragma Style_Checks ("r"); -- require consistency of identifier casing | |
7862 | Arg : Integer; | |
7863 | Rf1 : Integer := ARG; -- incorrect, wrong case | |
7864 | pragma Style_Checks (Off, Arg); | |
7865 | Rf2 : Integer := ARG; -- OK, no error | |
7866 | @end example | |
7867 | ||
7868 | @node Pragma Subtitle,Pragma Suppress,Pragma Style_Checks,Implementation Defined Pragmas | |
04d6c745 | 7869 | @anchor{gnat_rm/implementation_defined_pragmas pragma-subtitle}@anchor{f4} |
64d5610f ML |
7870 | @section Pragma Subtitle |
7871 | ||
7872 | ||
7873 | Syntax: | |
7874 | ||
7875 | @example | |
7876 | pragma Subtitle ([Subtitle =>] STRING_LITERAL); | |
7877 | @end example | |
7878 | ||
7879 | This pragma is recognized for compatibility with other Ada compilers | |
7880 | but is ignored by GNAT. | |
7881 | ||
7882 | @node Pragma Suppress,Pragma Suppress_All,Pragma Subtitle,Implementation Defined Pragmas | |
04d6c745 | 7883 | @anchor{gnat_rm/implementation_defined_pragmas pragma-suppress}@anchor{f5} |
64d5610f ML |
7884 | @section Pragma Suppress |
7885 | ||
7886 | ||
7887 | Syntax: | |
7888 | ||
7889 | @example | |
7890 | pragma Suppress (Identifier [, [On =>] Name]); | |
7891 | @end example | |
7892 | ||
7893 | This is a standard pragma, and supports all the check names required in | |
7894 | the RM. It is included here because GNAT recognizes some additional check | |
7895 | names that are implementation defined (as permitted by the RM): | |
7896 | ||
7897 | ||
7898 | @itemize * | |
7899 | ||
7900 | @item | |
7901 | @code{Alignment_Check} can be used to suppress alignment checks | |
7902 | on addresses used in address clauses. Such checks can also be suppressed | |
7903 | by suppressing range checks, but the specific use of @code{Alignment_Check} | |
7904 | allows suppression of alignment checks without suppressing other range checks. | |
7905 | Note that @code{Alignment_Check} is suppressed by default on machines (such as | |
7906 | the x86) with non-strict alignment. | |
7907 | ||
7908 | @item | |
7909 | @code{Atomic_Synchronization} can be used to suppress the special memory | |
7910 | synchronization instructions that are normally generated for access to | |
7911 | @code{Atomic} variables to ensure correct synchronization between tasks | |
7912 | that use such variables for synchronization purposes. | |
7913 | ||
7914 | @item | |
7915 | @code{Duplicated_Tag_Check} Can be used to suppress the check that is generated | |
7916 | for a duplicated tag value when a tagged type is declared. | |
7917 | ||
7918 | @item | |
7919 | @code{Container_Checks} Can be used to suppress all checks within Ada.Containers | |
7920 | and instances of its children, including Tampering_Check. | |
7921 | ||
7922 | @item | |
7923 | @code{Tampering_Check} Can be used to suppress tampering check in the containers. | |
7924 | ||
7925 | @item | |
7926 | @code{Predicate_Check} can be used to control whether predicate checks are | |
7927 | active. It is applicable only to predicates for which the policy is | |
7928 | @code{Check}. Unlike @code{Assertion_Policy}, which determines if a given | |
7929 | predicate is ignored or checked for the whole program, the use of | |
7930 | @code{Suppress} and @code{Unsuppress} with this check name allows a given | |
7931 | predicate to be turned on and off at specific points in the program. | |
7932 | ||
7933 | @item | |
7934 | @code{Validity_Check} can be used specifically to control validity checks. | |
7935 | If @code{Suppress} is used to suppress validity checks, then no validity | |
7936 | checks are performed, including those specified by the appropriate compiler | |
7937 | switch or the @code{Validity_Checks} pragma. | |
7938 | ||
7939 | @item | |
7940 | Additional check names previously introduced by use of the @code{Check_Name} | |
7941 | pragma are also allowed. | |
7942 | @end itemize | |
7943 | ||
7944 | Note that pragma Suppress gives the compiler permission to omit | |
7945 | checks, but does not require the compiler to omit checks. The compiler | |
7946 | will generate checks if they are essentially free, even when they are | |
7947 | suppressed. In particular, if the compiler can prove that a certain | |
7948 | check will necessarily fail, it will generate code to do an | |
7949 | unconditional ‘raise’, even if checks are suppressed. The compiler | |
7950 | warns in this case. | |
7951 | ||
7952 | Of course, run-time checks are omitted whenever the compiler can prove | |
7953 | that they will not fail, whether or not checks are suppressed. | |
7954 | ||
7955 | @node Pragma Suppress_All,Pragma Suppress_Debug_Info,Pragma Suppress,Implementation Defined Pragmas | |
04d6c745 | 7956 | @anchor{gnat_rm/implementation_defined_pragmas pragma-suppress-all}@anchor{f6} |
64d5610f ML |
7957 | @section Pragma Suppress_All |
7958 | ||
7959 | ||
7960 | Syntax: | |
7961 | ||
7962 | @example | |
7963 | pragma Suppress_All; | |
7964 | @end example | |
7965 | ||
7966 | This pragma can appear anywhere within a unit. | |
7967 | The effect is to apply @code{Suppress (All_Checks)} to the unit | |
7968 | in which it appears. This pragma is implemented for compatibility with DEC | |
7969 | Ada 83 usage where it appears at the end of a unit, and for compatibility | |
7970 | with Rational Ada, where it appears as a program unit pragma. | |
7971 | The use of the standard Ada pragma @code{Suppress (All_Checks)} | |
7972 | as a normal configuration pragma is the preferred usage in GNAT. | |
7973 | ||
7974 | @node Pragma Suppress_Debug_Info,Pragma Suppress_Exception_Locations,Pragma Suppress_All,Implementation Defined Pragmas | |
04d6c745 | 7975 | @anchor{gnat_rm/implementation_defined_pragmas id45}@anchor{f7}@anchor{gnat_rm/implementation_defined_pragmas pragma-suppress-debug-info}@anchor{f8} |
64d5610f ML |
7976 | @section Pragma Suppress_Debug_Info |
7977 | ||
7978 | ||
7979 | Syntax: | |
7980 | ||
7981 | @example | |
7982 | pragma Suppress_Debug_Info ([Entity =>] LOCAL_NAME); | |
7983 | @end example | |
7984 | ||
7985 | This pragma can be used to suppress generation of debug information | |
7986 | for the specified entity. It is intended primarily for use in debugging | |
7987 | the debugger, and navigating around debugger problems. | |
7988 | ||
7989 | @node Pragma Suppress_Exception_Locations,Pragma Suppress_Initialization,Pragma Suppress_Debug_Info,Implementation Defined Pragmas | |
04d6c745 | 7990 | @anchor{gnat_rm/implementation_defined_pragmas pragma-suppress-exception-locations}@anchor{f9} |
64d5610f ML |
7991 | @section Pragma Suppress_Exception_Locations |
7992 | ||
7993 | ||
7994 | Syntax: | |
7995 | ||
7996 | @example | |
7997 | pragma Suppress_Exception_Locations; | |
7998 | @end example | |
7999 | ||
8000 | In normal mode, a raise statement for an exception by default generates | |
8001 | an exception message giving the file name and line number for the location | |
8002 | of the raise. This is useful for debugging and logging purposes, but this | |
8003 | entails extra space for the strings for the messages. The configuration | |
8004 | pragma @code{Suppress_Exception_Locations} can be used to suppress the | |
8005 | generation of these strings, with the result that space is saved, but the | |
8006 | exception message for such raises is null. This configuration pragma may | |
8007 | appear in a global configuration pragma file, or in a specific unit as | |
8008 | usual. It is not required that this pragma be used consistently within | |
8009 | a partition, so it is fine to have some units within a partition compiled | |
8010 | with this pragma and others compiled in normal mode without it. | |
8011 | ||
8012 | @node Pragma Suppress_Initialization,Pragma Task_Name,Pragma Suppress_Exception_Locations,Implementation Defined Pragmas | |
04d6c745 | 8013 | @anchor{gnat_rm/implementation_defined_pragmas id46}@anchor{fa}@anchor{gnat_rm/implementation_defined_pragmas pragma-suppress-initialization}@anchor{fb} |
64d5610f ML |
8014 | @section Pragma Suppress_Initialization |
8015 | ||
8016 | ||
8017 | @geindex Suppressing initialization | |
8018 | ||
8019 | @geindex Initialization | |
8020 | @geindex suppression of | |
8021 | ||
8022 | Syntax: | |
8023 | ||
8024 | @example | |
8025 | pragma Suppress_Initialization ([Entity =>] variable_or_subtype_Name); | |
8026 | @end example | |
8027 | ||
8028 | Here variable_or_subtype_Name is the name introduced by a type declaration | |
8029 | or subtype declaration or the name of a variable introduced by an | |
8030 | object declaration. | |
8031 | ||
8032 | In the case of a type or subtype | |
8033 | this pragma suppresses any implicit or explicit initialization | |
8034 | for all variables of the given type or subtype, | |
8035 | including initialization resulting from the use of pragmas | |
8036 | Normalize_Scalars or Initialize_Scalars. | |
8037 | ||
8038 | This is considered a representation item, so it cannot be given after | |
8039 | the type is frozen. It applies to all subsequent object declarations, | |
8040 | and also any allocator that creates objects of the type. | |
8041 | ||
8042 | If the pragma is given for the first subtype, then it is considered | |
8043 | to apply to the base type and all its subtypes. If the pragma is given | |
8044 | for other than a first subtype, then it applies only to the given subtype. | |
8045 | The pragma may not be given after the type is frozen. | |
8046 | ||
8047 | Note that this includes eliminating initialization of discriminants | |
8048 | for discriminated types, and tags for tagged types. In these cases, | |
8049 | you will have to use some non-portable mechanism (e.g. address | |
8050 | overlays or unchecked conversion) to achieve required initialization | |
8051 | of these fields before accessing any object of the corresponding type. | |
8052 | ||
8053 | For the variable case, implicit initialization for the named variable | |
8054 | is suppressed, just as though its subtype had been given in a pragma | |
8055 | Suppress_Initialization, as described above. | |
8056 | ||
8057 | @node Pragma Task_Name,Pragma Task_Storage,Pragma Suppress_Initialization,Implementation Defined Pragmas | |
04d6c745 | 8058 | @anchor{gnat_rm/implementation_defined_pragmas pragma-task-name}@anchor{fc} |
64d5610f ML |
8059 | @section Pragma Task_Name |
8060 | ||
8061 | ||
8062 | Syntax | |
8063 | ||
8064 | @example | |
8065 | pragma Task_Name (string_EXPRESSION); | |
8066 | @end example | |
8067 | ||
8068 | This pragma appears within a task definition (like pragma | |
8069 | @code{Priority}) and applies to the task in which it appears. The | |
8070 | argument must be of type String, and provides a name to be used for | |
8071 | the task instance when the task is created. Note that this expression | |
8072 | is not required to be static, and in particular, it can contain | |
8073 | references to task discriminants. This facility can be used to | |
8074 | provide different names for different tasks as they are created, | |
8075 | as illustrated in the example below. | |
8076 | ||
8077 | The task name is recorded internally in the run-time structures | |
8078 | and is accessible to tools like the debugger. In addition the | |
8079 | routine @code{Ada.Task_Identification.Image} will return this | |
8080 | string, with a unique task address appended. | |
8081 | ||
8082 | @example | |
8083 | -- Example of the use of pragma Task_Name | |
8084 | ||
8085 | with Ada.Task_Identification; | |
8086 | use Ada.Task_Identification; | |
8087 | with Text_IO; use Text_IO; | |
8088 | procedure t3 is | |
8089 | ||
8090 | type Astring is access String; | |
8091 | ||
8092 | task type Task_Typ (Name : access String) is | |
8093 | pragma Task_Name (Name.all); | |
8094 | end Task_Typ; | |
8095 | ||
8096 | task body Task_Typ is | |
8097 | Nam : constant String := Image (Current_Task); | |
8098 | begin | |
8099 | Put_Line ("-->" & Nam (1 .. 14) & "<--"); | |
8100 | end Task_Typ; | |
8101 | ||
8102 | type Ptr_Task is access Task_Typ; | |
8103 | Task_Var : Ptr_Task; | |
8104 | ||
8105 | begin | |
8106 | Task_Var := | |
8107 | new Task_Typ (new String'("This is task 1")); | |
8108 | Task_Var := | |
8109 | new Task_Typ (new String'("This is task 2")); | |
8110 | end; | |
8111 | @end example | |
8112 | ||
8113 | @node Pragma Task_Storage,Pragma Test_Case,Pragma Task_Name,Implementation Defined Pragmas | |
04d6c745 | 8114 | @anchor{gnat_rm/implementation_defined_pragmas pragma-task-storage}@anchor{fd} |
64d5610f ML |
8115 | @section Pragma Task_Storage |
8116 | ||
8117 | ||
8118 | Syntax: | |
8119 | ||
8120 | @example | |
8121 | pragma Task_Storage ( | |
8122 | [Task_Type =>] LOCAL_NAME, | |
8123 | [Top_Guard =>] static_integer_EXPRESSION); | |
8124 | @end example | |
8125 | ||
8126 | This pragma specifies the length of the guard area for tasks. The guard | |
8127 | area is an additional storage area allocated to a task. A value of zero | |
8128 | means that either no guard area is created or a minimal guard area is | |
8129 | created, depending on the target. This pragma can appear anywhere a | |
8130 | @code{Storage_Size} attribute definition clause is allowed for a task | |
8131 | type. | |
8132 | ||
8133 | @node Pragma Test_Case,Pragma Thread_Local_Storage,Pragma Task_Storage,Implementation Defined Pragmas | |
04d6c745 | 8134 | @anchor{gnat_rm/implementation_defined_pragmas id47}@anchor{fe}@anchor{gnat_rm/implementation_defined_pragmas pragma-test-case}@anchor{ff} |
64d5610f ML |
8135 | @section Pragma Test_Case |
8136 | ||
8137 | ||
8138 | @geindex Test cases | |
8139 | ||
8140 | Syntax: | |
8141 | ||
8142 | @example | |
8143 | pragma Test_Case ( | |
8144 | [Name =>] static_string_Expression | |
8145 | ,[Mode =>] (Nominal | Robustness) | |
8146 | [, Requires => Boolean_Expression] | |
8147 | [, Ensures => Boolean_Expression]); | |
8148 | @end example | |
8149 | ||
8150 | The @code{Test_Case} pragma allows defining fine-grain specifications | |
8151 | for use by testing tools. | |
8152 | The compiler checks the validity of the @code{Test_Case} pragma, but its | |
8153 | presence does not lead to any modification of the code generated by the | |
8154 | compiler. | |
8155 | ||
8156 | @code{Test_Case} pragmas may only appear immediately following the | |
8157 | (separate) declaration of a subprogram in a package declaration, inside | |
8158 | a package spec unit. Only other pragmas may intervene (that is appear | |
8159 | between the subprogram declaration and a test case). | |
8160 | ||
8161 | The compiler checks that boolean expressions given in @code{Requires} and | |
8162 | @code{Ensures} are valid, where the rules for @code{Requires} are the | |
8163 | same as the rule for an expression in @code{Precondition} and the rules | |
8164 | for @code{Ensures} are the same as the rule for an expression in | |
8165 | @code{Postcondition}. In particular, attributes @code{'Old} and | |
8166 | @code{'Result} can only be used within the @code{Ensures} | |
8167 | expression. The following is an example of use within a package spec: | |
8168 | ||
8169 | @example | |
8170 | package Math_Functions is | |
8171 | ... | |
8172 | function Sqrt (Arg : Float) return Float; | |
8173 | pragma Test_Case (Name => "Test 1", | |
8174 | Mode => Nominal, | |
8175 | Requires => Arg < 10000.0, | |
8176 | Ensures => Sqrt'Result < 10.0); | |
8177 | ... | |
8178 | end Math_Functions; | |
8179 | @end example | |
8180 | ||
8181 | The meaning of a test case is that there is at least one context where | |
8182 | @code{Requires} holds such that, if the associated subprogram is executed in | |
8183 | that context, then @code{Ensures} holds when the subprogram returns. | |
8184 | Mode @code{Nominal} indicates that the input context should also satisfy the | |
8185 | precondition of the subprogram, and the output context should also satisfy its | |
8186 | postcondition. Mode @code{Robustness} indicates that the precondition and | |
8187 | postcondition of the subprogram should be ignored for this test case. | |
8188 | ||
8189 | @node Pragma Thread_Local_Storage,Pragma Time_Slice,Pragma Test_Case,Implementation Defined Pragmas | |
04d6c745 | 8190 | @anchor{gnat_rm/implementation_defined_pragmas id48}@anchor{100}@anchor{gnat_rm/implementation_defined_pragmas pragma-thread-local-storage}@anchor{101} |
64d5610f ML |
8191 | @section Pragma Thread_Local_Storage |
8192 | ||
8193 | ||
8194 | @geindex Task specific storage | |
8195 | ||
8196 | @geindex TLS (Thread Local Storage) | |
8197 | ||
8198 | @geindex Task_Attributes | |
8199 | ||
8200 | Syntax: | |
8201 | ||
8202 | @example | |
8203 | pragma Thread_Local_Storage ([Entity =>] LOCAL_NAME); | |
8204 | @end example | |
8205 | ||
8206 | This pragma specifies that the specified entity, which must be | |
8207 | a variable declared in a library-level package, is to be marked as | |
8208 | “Thread Local Storage” (@code{TLS}). On systems supporting this (which | |
8209 | include Windows, Solaris, GNU/Linux, and VxWorks), this causes each | |
8210 | thread (and hence each Ada task) to see a distinct copy of the variable. | |
8211 | ||
8212 | The variable must not have default initialization, and if there is | |
8213 | an explicit initialization, it must be either @code{null} for an | |
8214 | access variable, a static expression for a scalar variable, or a fully | |
8215 | static aggregate for a composite type, that is to say, an aggregate all | |
8216 | of whose components are static, and which does not include packed or | |
8217 | discriminated components. | |
8218 | ||
8219 | This provides a low-level mechanism similar to that provided by | |
8220 | the @code{Ada.Task_Attributes} package, but much more efficient | |
8221 | and is also useful in writing interface code that will interact | |
8222 | with foreign threads. | |
8223 | ||
8224 | If this pragma is used on a system where @code{TLS} is not supported, | |
8225 | then an error message will be generated and the program will be rejected. | |
8226 | ||
8227 | @node Pragma Time_Slice,Pragma Title,Pragma Thread_Local_Storage,Implementation Defined Pragmas | |
04d6c745 | 8228 | @anchor{gnat_rm/implementation_defined_pragmas pragma-time-slice}@anchor{102} |
64d5610f ML |
8229 | @section Pragma Time_Slice |
8230 | ||
8231 | ||
8232 | Syntax: | |
8233 | ||
8234 | @example | |
8235 | pragma Time_Slice (static_duration_EXPRESSION); | |
8236 | @end example | |
8237 | ||
8238 | For implementations of GNAT on operating systems where it is possible | |
8239 | to supply a time slice value, this pragma may be used for this purpose. | |
8240 | It is ignored if it is used in a system that does not allow this control, | |
8241 | or if it appears in other than the main program unit. | |
8242 | ||
8243 | @node Pragma Title,Pragma Type_Invariant,Pragma Time_Slice,Implementation Defined Pragmas | |
04d6c745 | 8244 | @anchor{gnat_rm/implementation_defined_pragmas pragma-title}@anchor{103} |
64d5610f ML |
8245 | @section Pragma Title |
8246 | ||
8247 | ||
8248 | Syntax: | |
8249 | ||
8250 | @example | |
8251 | pragma Title (TITLING_OPTION [, TITLING OPTION]); | |
8252 | ||
8253 | TITLING_OPTION ::= | |
8254 | [Title =>] STRING_LITERAL, | |
8255 | | [Subtitle =>] STRING_LITERAL | |
8256 | @end example | |
8257 | ||
8258 | Syntax checked but otherwise ignored by GNAT. This is a listing control | |
8259 | pragma used in DEC Ada 83 implementations to provide a title and/or | |
8260 | subtitle for the program listing. The program listing generated by GNAT | |
8261 | does not have titles or subtitles. | |
8262 | ||
8263 | Unlike other pragmas, the full flexibility of named notation is allowed | |
8264 | for this pragma, i.e., the parameters may be given in any order if named | |
8265 | notation is used, and named and positional notation can be mixed | |
8266 | following the normal rules for procedure calls in Ada. | |
8267 | ||
8268 | @node Pragma Type_Invariant,Pragma Type_Invariant_Class,Pragma Title,Implementation Defined Pragmas | |
04d6c745 | 8269 | @anchor{gnat_rm/implementation_defined_pragmas pragma-type-invariant}@anchor{104} |
64d5610f ML |
8270 | @section Pragma Type_Invariant |
8271 | ||
8272 | ||
8273 | Syntax: | |
8274 | ||
8275 | @example | |
8276 | pragma Type_Invariant | |
8277 | ([Entity =>] type_LOCAL_NAME, | |
8278 | [Check =>] EXPRESSION); | |
8279 | @end example | |
8280 | ||
8281 | The @code{Type_Invariant} pragma is intended to be an exact | |
8282 | replacement for the language-defined @code{Type_Invariant} | |
8283 | aspect, and shares its restrictions and semantics. It differs | |
8284 | from the language defined @code{Invariant} pragma in that it | |
8285 | does not permit a string parameter, and it is | |
8286 | controlled by the assertion identifier @code{Type_Invariant} | |
8287 | rather than @code{Invariant}. | |
8288 | ||
8289 | @node Pragma Type_Invariant_Class,Pragma Unchecked_Union,Pragma Type_Invariant,Implementation Defined Pragmas | |
04d6c745 | 8290 | @anchor{gnat_rm/implementation_defined_pragmas id49}@anchor{105}@anchor{gnat_rm/implementation_defined_pragmas pragma-type-invariant-class}@anchor{106} |
64d5610f ML |
8291 | @section Pragma Type_Invariant_Class |
8292 | ||
8293 | ||
8294 | Syntax: | |
8295 | ||
8296 | @example | |
8297 | pragma Type_Invariant_Class | |
8298 | ([Entity =>] type_LOCAL_NAME, | |
8299 | [Check =>] EXPRESSION); | |
8300 | @end example | |
8301 | ||
8302 | The @code{Type_Invariant_Class} pragma is intended to be an exact | |
8303 | replacement for the language-defined @code{Type_Invariant'Class} | |
8304 | aspect, and shares its restrictions and semantics. | |
8305 | ||
8306 | Note: This pragma is called @code{Type_Invariant_Class} rather than | |
8307 | @code{Type_Invariant'Class} because the latter would not be strictly | |
8308 | conforming to the allowed syntax for pragmas. The motivation | |
8309 | for providing pragmas equivalent to the aspects is to allow a program | |
8310 | to be written using the pragmas, and then compiled if necessary | |
8311 | using an Ada compiler that does not recognize the pragmas or | |
8312 | aspects, but is prepared to ignore the pragmas. The assertion | |
8313 | policy that controls this pragma is @code{Type_Invariant'Class}, | |
8314 | not @code{Type_Invariant_Class}. | |
8315 | ||
8316 | @node Pragma Unchecked_Union,Pragma Unevaluated_Use_Of_Old,Pragma Type_Invariant_Class,Implementation Defined Pragmas | |
04d6c745 | 8317 | @anchor{gnat_rm/implementation_defined_pragmas pragma-unchecked-union}@anchor{107} |
64d5610f ML |
8318 | @section Pragma Unchecked_Union |
8319 | ||
8320 | ||
8321 | @geindex Unions in C | |
8322 | ||
8323 | Syntax: | |
8324 | ||
8325 | @example | |
8326 | pragma Unchecked_Union (first_subtype_LOCAL_NAME); | |
8327 | @end example | |
8328 | ||
8329 | This pragma is used to specify a representation of a record type that is | |
8330 | equivalent to a C union. It was introduced as a GNAT implementation defined | |
8331 | pragma in the GNAT Ada 95 mode. Ada 2005 includes an extended version of this | |
8332 | pragma, making it language defined, and GNAT fully implements this extended | |
8333 | version in all language modes (Ada 83, Ada 95, and Ada 2005). For full | |
8334 | details, consult the Ada 2012 Reference Manual, section B.3.3. | |
8335 | ||
9daee425 | 8336 | @node Pragma Unevaluated_Use_Of_Old,Pragma User_Aspect_Definition,Pragma Unchecked_Union,Implementation Defined Pragmas |
04d6c745 | 8337 | @anchor{gnat_rm/implementation_defined_pragmas pragma-unevaluated-use-of-old}@anchor{108} |
64d5610f ML |
8338 | @section Pragma Unevaluated_Use_Of_Old |
8339 | ||
8340 | ||
8341 | @geindex Attribute Old | |
8342 | ||
8343 | @geindex Attribute Loop_Entry | |
8344 | ||
8345 | @geindex Unevaluated_Use_Of_Old | |
8346 | ||
8347 | Syntax: | |
8348 | ||
8349 | @example | |
8350 | pragma Unevaluated_Use_Of_Old (Error | Warn | Allow); | |
8351 | @end example | |
8352 | ||
8353 | This pragma controls the processing of attributes Old and Loop_Entry. | |
8354 | If either of these attributes is used in a potentially unevaluated | |
8355 | expression (e.g. the then or else parts of an if expression), then | |
8356 | normally this usage is considered illegal if the prefix of the attribute | |
8357 | is other than an entity name. The language requires this | |
8358 | behavior for Old, and GNAT copies the same rule for Loop_Entry. | |
8359 | ||
8360 | The reason for this rule is that otherwise, we can have a situation | |
8361 | where we save the Old value, and this results in an exception, even | |
8362 | though we might not evaluate the attribute. Consider this example: | |
8363 | ||
8364 | @example | |
8365 | package UnevalOld is | |
8366 | K : Character; | |
8367 | procedure U (A : String; C : Boolean) -- ERROR | |
8368 | with Post => (if C then A(1)'Old = K else True); | |
8369 | end; | |
8370 | @end example | |
8371 | ||
8372 | If procedure U is called with a string with a lower bound of 2, and | |
8373 | C false, then an exception would be raised trying to evaluate A(1) | |
8374 | on entry even though the value would not be actually used. | |
8375 | ||
8376 | Although the rule guarantees against this possibility, it is sometimes | |
8377 | too restrictive. For example if we know that the string has a lower | |
8378 | bound of 1, then we will never raise an exception. | |
8379 | The pragma @code{Unevaluated_Use_Of_Old} can be | |
8380 | used to modify this behavior. If the argument is @code{Error} then an | |
8381 | error is given (this is the default RM behavior). If the argument is | |
8382 | @code{Warn} then the usage is allowed as legal but with a warning | |
8383 | that an exception might be raised. If the argument is @code{Allow} | |
8384 | then the usage is allowed as legal without generating a warning. | |
8385 | ||
8386 | This pragma may appear as a configuration pragma, or in a declarative | |
8387 | part or package specification. In the latter case it applies to | |
8388 | uses up to the end of the corresponding statement sequence or | |
8389 | sequence of package declarations. | |
8390 | ||
9daee425 SB |
8391 | @node Pragma User_Aspect_Definition,Pragma Unimplemented_Unit,Pragma Unevaluated_Use_Of_Old,Implementation Defined Pragmas |
8392 | @anchor{gnat_rm/implementation_defined_pragmas pragma-user-aspect-definition}@anchor{109} | |
8393 | @section Pragma User_Aspect_Definition | |
8394 | ||
8395 | ||
8396 | Syntax: | |
8397 | ||
8398 | @example | |
8399 | pragma User_Aspect_Definition | |
8400 | (Identifier @{, Identifier [(Identifier @{, Identifier@})]@}); | |
8401 | @end example | |
8402 | ||
8403 | This configuration pragma defines a new aspect, making it available for | |
8404 | subsequent use in a User_Aspect aspect specification. The first | |
8405 | identifier is the name of the new aspect. Any subsequent arguments | |
8406 | specify the names of other aspects. A subsequent name for which no parenthesized | |
8407 | arguments are given shall denote either a Boolean-valued | |
8408 | non-representation aspect or an aspect that has been defined by another | |
8409 | User_Aspect_Definition pragma. A name for which one or more arguments are | |
8410 | given shall be either Annotate or Local_Restrictions (and the arguments shall | |
8411 | be appropriate for the named aspect). This pragma, together with the | |
8412 | User_Aspect aspect, provides a mechanism for | |
8413 | avoiding textual duplication if some set of aspect specifications is needed | |
8414 | in multiple places. This is somewhat analogous to how profiles allow avoiding | |
8415 | duplication of Restrictions pragmas. The visibility rules for an aspect | |
8416 | defined by a User_Aspect_Definition pragma are the same as for a check name | |
8417 | introduced by a Check_Name pragma. If multiple | |
8418 | definitions are visible for some aspect at some point, then the | |
8419 | definitions must agree. A predefined aspect cannot be redefined. | |
8420 | ||
8421 | @node Pragma Unimplemented_Unit,Pragma Universal_Aliasing,Pragma User_Aspect_Definition,Implementation Defined Pragmas | |
8422 | @anchor{gnat_rm/implementation_defined_pragmas pragma-unimplemented-unit}@anchor{10a} | |
64d5610f ML |
8423 | @section Pragma Unimplemented_Unit |
8424 | ||
8425 | ||
8426 | Syntax: | |
8427 | ||
8428 | @example | |
8429 | pragma Unimplemented_Unit; | |
8430 | @end example | |
8431 | ||
8432 | If this pragma occurs in a unit that is processed by the compiler, GNAT | |
8433 | aborts with the message @code{xxx not implemented}, where | |
8434 | @code{xxx} is the name of the current compilation unit. This pragma is | |
8435 | intended to allow the compiler to handle unimplemented library units in | |
8436 | a clean manner. | |
8437 | ||
8438 | The abort only happens if code is being generated. Thus you can use | |
8439 | specs of unimplemented packages in syntax or semantic checking mode. | |
8440 | ||
8441 | @node Pragma Universal_Aliasing,Pragma Unmodified,Pragma Unimplemented_Unit,Implementation Defined Pragmas | |
9daee425 | 8442 | @anchor{gnat_rm/implementation_defined_pragmas id50}@anchor{10b}@anchor{gnat_rm/implementation_defined_pragmas pragma-universal-aliasing}@anchor{10c} |
64d5610f ML |
8443 | @section Pragma Universal_Aliasing |
8444 | ||
8445 | ||
8446 | Syntax: | |
8447 | ||
8448 | @example | |
8449 | pragma Universal_Aliasing [([Entity =>] type_LOCAL_NAME)]; | |
8450 | @end example | |
8451 | ||
8452 | @code{type_LOCAL_NAME} must refer to a type declaration in the current | |
8453 | declarative part. The effect is to inhibit strict type-based aliasing | |
8454 | optimization for the given type. In other words, the effect is as though | |
8455 | access types designating this type were subject to pragma No_Strict_Aliasing. | |
8456 | For a detailed description of the strict aliasing optimization, and the | |
8457 | situations in which it must be suppressed, see the section on | |
8458 | @code{Optimization and Strict Aliasing} in the @cite{GNAT User’s Guide}. | |
8459 | ||
8460 | @node Pragma Unmodified,Pragma Unreferenced,Pragma Universal_Aliasing,Implementation Defined Pragmas | |
9daee425 | 8461 | @anchor{gnat_rm/implementation_defined_pragmas id51}@anchor{10d}@anchor{gnat_rm/implementation_defined_pragmas pragma-unmodified}@anchor{10e} |
64d5610f ML |
8462 | @section Pragma Unmodified |
8463 | ||
8464 | ||
8465 | @geindex Warnings | |
8466 | @geindex unmodified | |
8467 | ||
8468 | Syntax: | |
8469 | ||
8470 | @example | |
8471 | pragma Unmodified (LOCAL_NAME @{, LOCAL_NAME@}); | |
8472 | @end example | |
8473 | ||
8474 | This pragma signals that the assignable entities (variables, | |
8475 | @code{out} parameters, @code{in out} parameters) whose names are listed are | |
8476 | deliberately not assigned in the current source unit. This | |
8477 | suppresses warnings about the | |
8478 | entities being referenced but not assigned, and in addition a warning will be | |
8479 | generated if one of these entities is in fact assigned in the | |
8480 | same unit as the pragma (or in the corresponding body, or one | |
8481 | of its subunits). | |
8482 | ||
8483 | This is particularly useful for clearly signaling that a particular | |
8484 | parameter is not modified, even though the spec suggests that it might | |
8485 | be. | |
8486 | ||
8487 | For the variable case, warnings are never given for unreferenced variables | |
8488 | whose name contains one of the substrings | |
8489 | @code{DISCARD, DUMMY, IGNORE, JUNK, UNUSE, TMP, TEMP} in any casing. Such names | |
8490 | are typically to be used in cases where such warnings are expected. | |
8491 | Thus it is never necessary to use @code{pragma Unmodified} for such | |
8492 | variables, though it is harmless to do so. | |
8493 | ||
8494 | @node Pragma Unreferenced,Pragma Unreferenced_Objects,Pragma Unmodified,Implementation Defined Pragmas | |
9daee425 | 8495 | @anchor{gnat_rm/implementation_defined_pragmas id52}@anchor{10f}@anchor{gnat_rm/implementation_defined_pragmas pragma-unreferenced}@anchor{110} |
64d5610f ML |
8496 | @section Pragma Unreferenced |
8497 | ||
8498 | ||
8499 | @geindex Warnings | |
8500 | @geindex unreferenced | |
8501 | ||
8502 | Syntax: | |
8503 | ||
8504 | @example | |
8505 | pragma Unreferenced (LOCAL_NAME @{, LOCAL_NAME@}); | |
8506 | pragma Unreferenced (library_unit_NAME @{, library_unit_NAME@}); | |
8507 | @end example | |
8508 | ||
8509 | This pragma signals that the entities whose names are listed are | |
8510 | deliberately not referenced in the current source unit after the | |
8511 | occurrence of the pragma. This | |
8512 | suppresses warnings about the | |
8513 | entities being unreferenced, and in addition a warning will be | |
8514 | generated if one of these entities is in fact subsequently referenced in the | |
8515 | same unit as the pragma (or in the corresponding body, or one | |
8516 | of its subunits). | |
8517 | ||
8518 | This is particularly useful for clearly signaling that a particular | |
8519 | parameter is not referenced in some particular subprogram implementation | |
8520 | and that this is deliberate. It can also be useful in the case of | |
8521 | objects declared only for their initialization or finalization side | |
8522 | effects. | |
8523 | ||
8524 | If @code{LOCAL_NAME} identifies more than one matching homonym in the | |
8525 | current scope, then the entity most recently declared is the one to which | |
8526 | the pragma applies. Note that in the case of accept formals, the pragma | |
8527 | Unreferenced may appear immediately after the keyword @code{do} which | |
8528 | allows the indication of whether or not accept formals are referenced | |
8529 | or not to be given individually for each accept statement. | |
8530 | ||
8531 | The left hand side of an assignment does not count as a reference for the | |
8532 | purpose of this pragma. Thus it is fine to assign to an entity for which | |
8533 | pragma Unreferenced is given. However, use of an entity as an actual for | |
8534 | an out parameter does count as a reference unless warnings for unread output | |
8535 | parameters are enabled via @code{-gnatw.o}. | |
8536 | ||
8537 | Note that if a warning is desired for all calls to a given subprogram, | |
8538 | regardless of whether they occur in the same unit as the subprogram | |
8539 | declaration, then this pragma should not be used (calls from another | |
8540 | unit would not be flagged); pragma Obsolescent can be used instead | |
b71d4b62 | 8541 | for this purpose, see @ref{af,,Pragma Obsolescent}. |
64d5610f ML |
8542 | |
8543 | The second form of pragma @code{Unreferenced} is used within a context | |
8544 | clause. In this case the arguments must be unit names of units previously | |
8545 | mentioned in @code{with} clauses (similar to the usage of pragma | |
8546 | @code{Elaborate_All}). The effect is to suppress warnings about unreferenced | |
8547 | units and unreferenced entities within these units. | |
8548 | ||
8549 | For the variable case, warnings are never given for unreferenced variables | |
8550 | whose name contains one of the substrings | |
8551 | @code{DISCARD, DUMMY, IGNORE, JUNK, UNUSED} in any casing. Such names | |
8552 | are typically to be used in cases where such warnings are expected. | |
8553 | Thus it is never necessary to use @code{pragma Unreferenced} for such | |
8554 | variables, though it is harmless to do so. | |
8555 | ||
8556 | @node Pragma Unreferenced_Objects,Pragma Unreserve_All_Interrupts,Pragma Unreferenced,Implementation Defined Pragmas | |
9daee425 | 8557 | @anchor{gnat_rm/implementation_defined_pragmas id53}@anchor{111}@anchor{gnat_rm/implementation_defined_pragmas pragma-unreferenced-objects}@anchor{112} |
64d5610f ML |
8558 | @section Pragma Unreferenced_Objects |
8559 | ||
8560 | ||
8561 | @geindex Warnings | |
8562 | @geindex unreferenced | |
8563 | ||
8564 | Syntax: | |
8565 | ||
8566 | @example | |
8567 | pragma Unreferenced_Objects (local_subtype_NAME @{, local_subtype_NAME@}); | |
8568 | @end example | |
8569 | ||
8570 | This pragma signals that for the types or subtypes whose names are | |
8571 | listed, objects which are declared with one of these types or subtypes may | |
8572 | not be referenced, and if no references appear, no warnings are given. | |
8573 | ||
8574 | This is particularly useful for objects which are declared solely for their | |
8575 | initialization and finalization effect. Such variables are sometimes referred | |
8576 | to as RAII variables (Resource Acquisition Is Initialization). Using this | |
8577 | pragma on the relevant type (most typically a limited controlled type), the | |
8578 | compiler will automatically suppress unwanted warnings about these variables | |
8579 | not being referenced. | |
8580 | ||
8581 | @node Pragma Unreserve_All_Interrupts,Pragma Unsuppress,Pragma Unreferenced_Objects,Implementation Defined Pragmas | |
9daee425 | 8582 | @anchor{gnat_rm/implementation_defined_pragmas pragma-unreserve-all-interrupts}@anchor{113} |
64d5610f ML |
8583 | @section Pragma Unreserve_All_Interrupts |
8584 | ||
8585 | ||
8586 | Syntax: | |
8587 | ||
8588 | @example | |
8589 | pragma Unreserve_All_Interrupts; | |
8590 | @end example | |
8591 | ||
8592 | Normally certain interrupts are reserved to the implementation. Any attempt | |
8593 | to attach an interrupt causes Program_Error to be raised, as described in | |
8594 | RM C.3.2(22). A typical example is the @code{SIGINT} interrupt used in | |
8595 | many systems for a @code{Ctrl-C} interrupt. Normally this interrupt is | |
8596 | reserved to the implementation, so that @code{Ctrl-C} can be used to | |
8597 | interrupt execution. | |
8598 | ||
8599 | If the pragma @code{Unreserve_All_Interrupts} appears anywhere in any unit in | |
8600 | a program, then all such interrupts are unreserved. This allows the | |
8601 | program to handle these interrupts, but disables their standard | |
8602 | functions. For example, if this pragma is used, then pressing | |
8603 | @code{Ctrl-C} will not automatically interrupt execution. However, | |
8604 | a program can then handle the @code{SIGINT} interrupt as it chooses. | |
8605 | ||
8606 | For a full list of the interrupts handled in a specific implementation, | |
8607 | see the source code for the spec of @code{Ada.Interrupts.Names} in | |
8608 | file @code{a-intnam.ads}. This is a target dependent file that contains the | |
8609 | list of interrupts recognized for a given target. The documentation in | |
8610 | this file also specifies what interrupts are affected by the use of | |
8611 | the @code{Unreserve_All_Interrupts} pragma. | |
8612 | ||
8613 | For a more general facility for controlling what interrupts can be | |
8614 | handled, see pragma @code{Interrupt_State}, which subsumes the functionality | |
8615 | of the @code{Unreserve_All_Interrupts} pragma. | |
8616 | ||
6f089469 | 8617 | @node Pragma Unsuppress,Pragma Unused,Pragma Unreserve_All_Interrupts,Implementation Defined Pragmas |
9daee425 | 8618 | @anchor{gnat_rm/implementation_defined_pragmas pragma-unsuppress}@anchor{114} |
64d5610f ML |
8619 | @section Pragma Unsuppress |
8620 | ||
8621 | ||
8622 | Syntax: | |
8623 | ||
8624 | @example | |
8625 | pragma Unsuppress (IDENTIFIER [, [On =>] NAME]); | |
8626 | @end example | |
8627 | ||
8628 | This pragma undoes the effect of a previous pragma @code{Suppress}. If | |
8629 | there is no corresponding pragma @code{Suppress} in effect, it has no | |
8630 | effect. The range of the effect is the same as for pragma | |
8631 | @code{Suppress}. The meaning of the arguments is identical to that used | |
8632 | in pragma @code{Suppress}. | |
8633 | ||
8634 | One important application is to ensure that checks are on in cases where | |
8635 | code depends on the checks for its correct functioning, so that the code | |
8636 | will compile correctly even if the compiler switches are set to suppress | |
8637 | checks. For example, in a program that depends on external names of tagged | |
8638 | types and wants to ensure that the duplicated tag check occurs even if all | |
8639 | run-time checks are suppressed by a compiler switch, the following | |
8640 | configuration pragma will ensure this test is not suppressed: | |
8641 | ||
8642 | @example | |
8643 | pragma Unsuppress (Duplicated_Tag_Check); | |
8644 | @end example | |
8645 | ||
8646 | This pragma is standard in Ada 2005. It is available in all earlier versions | |
8647 | of Ada as an implementation-defined pragma. | |
8648 | ||
8649 | Note that in addition to the checks defined in the Ada RM, GNAT recognizes a | |
8650 | number of implementation-defined check names. See the description of pragma | |
8651 | @code{Suppress} for full details. | |
8652 | ||
6f089469 | 8653 | @node Pragma Unused,Pragma Use_VADS_Size,Pragma Unsuppress,Implementation Defined Pragmas |
9daee425 | 8654 | @anchor{gnat_rm/implementation_defined_pragmas id54}@anchor{115}@anchor{gnat_rm/implementation_defined_pragmas pragma-unused}@anchor{116} |
64d5610f ML |
8655 | @section Pragma Unused |
8656 | ||
8657 | ||
8658 | @geindex Warnings | |
8659 | @geindex unused | |
8660 | ||
8661 | Syntax: | |
8662 | ||
8663 | @example | |
8664 | pragma Unused (LOCAL_NAME @{, LOCAL_NAME@}); | |
8665 | @end example | |
8666 | ||
8667 | This pragma signals that the assignable entities (variables, | |
8668 | @code{out} parameters, and @code{in out} parameters) whose names are listed | |
8669 | deliberately do not get assigned or referenced in the current source unit | |
8670 | after the occurrence of the pragma in the current source unit. This | |
8671 | suppresses warnings about the entities that are unreferenced and/or not | |
8672 | assigned, and, in addition, a warning will be generated if one of these | |
8673 | entities gets assigned or subsequently referenced in the same unit as the | |
8674 | pragma (in the corresponding body or one of its subunits). | |
8675 | ||
8676 | This is particularly useful for clearly signaling that a particular | |
8677 | parameter is not modified or referenced, even though the spec suggests | |
8678 | that it might be. | |
8679 | ||
8680 | For the variable case, warnings are never given for unreferenced | |
8681 | variables whose name contains one of the substrings | |
8682 | @code{DISCARD, DUMMY, IGNORE, JUNK, UNUSED} in any casing. Such names | |
8683 | are typically to be used in cases where such warnings are expected. | |
8684 | Thus it is never necessary to use @code{pragma Unused} for such | |
8685 | variables, though it is harmless to do so. | |
8686 | ||
6f089469 | 8687 | @node Pragma Use_VADS_Size,Pragma Validity_Checks,Pragma Unused,Implementation Defined Pragmas |
9daee425 | 8688 | @anchor{gnat_rm/implementation_defined_pragmas pragma-use-vads-size}@anchor{117} |
6f089469 RD |
8689 | @section Pragma Use_VADS_Size |
8690 | ||
8691 | ||
8692 | @geindex Size | |
8693 | @geindex VADS compatibility | |
8694 | ||
8695 | @geindex Rational profile | |
8696 | ||
8697 | Syntax: | |
8698 | ||
8699 | @example | |
8700 | pragma Use_VADS_Size; | |
8701 | @end example | |
8702 | ||
8703 | This is a configuration pragma. In a unit to which it applies, any use | |
8704 | of the ‘Size attribute is automatically interpreted as a use of the | |
8705 | ‘VADS_Size attribute. Note that this may result in incorrect semantic | |
8706 | processing of valid Ada 95 or Ada 2005 programs. This is intended to aid in | |
8707 | the handling of existing code which depends on the interpretation of Size | |
8708 | as implemented in the VADS compiler. See description of the VADS_Size | |
8709 | attribute for further details. | |
8710 | ||
8711 | @node Pragma Validity_Checks,Pragma Volatile,Pragma Use_VADS_Size,Implementation Defined Pragmas | |
9daee425 | 8712 | @anchor{gnat_rm/implementation_defined_pragmas pragma-validity-checks}@anchor{118} |
64d5610f ML |
8713 | @section Pragma Validity_Checks |
8714 | ||
8715 | ||
8716 | Syntax: | |
8717 | ||
8718 | @example | |
8719 | pragma Validity_Checks (string_LITERAL | ALL_CHECKS | On | Off); | |
8720 | @end example | |
8721 | ||
8722 | This pragma is used in conjunction with compiler switches to control the | |
8723 | built-in validity checking provided by GNAT. The compiler switches, if set | |
8724 | provide an initial setting for the switches, and this pragma may be used | |
8725 | to modify these settings, or the settings may be provided entirely by | |
8726 | the use of the pragma. This pragma can be used anywhere that a pragma | |
8727 | is legal, including use as a configuration pragma (including use in | |
8728 | the @code{gnat.adc} file). | |
8729 | ||
8730 | The form with a string literal specifies which validity options are to be | |
8731 | activated. The validity checks are first set to include only the default | |
8732 | reference manual settings, and then a string of letters in the string | |
8733 | specifies the exact set of options required. The form of this string | |
1acce141 | 8734 | is exactly as described for the @emph{-gnatVx} compiler switch (see the |
64d5610f ML |
8735 | GNAT User’s Guide for details). For example the following two |
8736 | methods can be used to enable validity checking for mode @code{in} and | |
8737 | @code{in out} subprogram parameters: | |
8738 | ||
8739 | ||
8740 | @itemize * | |
8741 | ||
8742 | @item | |
8743 | @example | |
8744 | pragma Validity_Checks ("im"); | |
8745 | @end example | |
8746 | ||
8747 | @item | |
8748 | @example | |
8749 | $ gcc -c -gnatVim ... | |
8750 | @end example | |
8751 | @end itemize | |
8752 | ||
8753 | The form ALL_CHECKS activates all standard checks (its use is equivalent | |
8754 | to the use of the @code{gnatVa} switch). | |
8755 | ||
8756 | The forms with @code{Off} and @code{On} can be used to temporarily disable | |
8757 | validity checks as shown in the following example: | |
8758 | ||
8759 | @example | |
8760 | pragma Validity_Checks ("c"); -- validity checks for copies | |
8761 | pragma Validity_Checks (Off); -- turn off validity checks | |
8762 | A := B; -- B will not be validity checked | |
8763 | pragma Validity_Checks (On); -- turn validity checks back on | |
8764 | A := C; -- C will be validity checked | |
8765 | @end example | |
8766 | ||
8767 | @node Pragma Volatile,Pragma Volatile_Full_Access,Pragma Validity_Checks,Implementation Defined Pragmas | |
9daee425 | 8768 | @anchor{gnat_rm/implementation_defined_pragmas id55}@anchor{119}@anchor{gnat_rm/implementation_defined_pragmas pragma-volatile}@anchor{11a} |
64d5610f ML |
8769 | @section Pragma Volatile |
8770 | ||
8771 | ||
8772 | Syntax: | |
8773 | ||
8774 | @example | |
8775 | pragma Volatile (LOCAL_NAME); | |
8776 | @end example | |
8777 | ||
8778 | This pragma is defined by the Ada Reference Manual, and the GNAT | |
8779 | implementation is fully conformant with this definition. The reason it | |
8780 | is mentioned in this section is that a pragma of the same name was supplied | |
8781 | in some Ada 83 compilers, including DEC Ada 83. The Ada 95 / Ada 2005 | |
8782 | implementation of pragma Volatile is upwards compatible with the | |
8783 | implementation in DEC Ada 83. | |
8784 | ||
8785 | @node Pragma Volatile_Full_Access,Pragma Volatile_Function,Pragma Volatile,Implementation Defined Pragmas | |
9daee425 | 8786 | @anchor{gnat_rm/implementation_defined_pragmas id56}@anchor{11b}@anchor{gnat_rm/implementation_defined_pragmas pragma-volatile-full-access}@anchor{11c} |
64d5610f ML |
8787 | @section Pragma Volatile_Full_Access |
8788 | ||
8789 | ||
8790 | Syntax: | |
8791 | ||
8792 | @example | |
8793 | pragma Volatile_Full_Access (LOCAL_NAME); | |
8794 | @end example | |
8795 | ||
8796 | This is similar in effect to pragma Volatile, except that any reference to the | |
8797 | object is guaranteed to be done only with instructions that read or write all | |
8798 | the bits of the object. Furthermore, if the object is of a composite type, | |
8799 | then any reference to a subcomponent of the object is guaranteed to read | |
8800 | and/or write all the bits of the object. | |
8801 | ||
8802 | The intention is that this be suitable for use with memory-mapped I/O devices | |
8803 | on some machines. Note that there are two important respects in which this is | |
8804 | different from @code{pragma Atomic}. First a reference to a @code{Volatile_Full_Access} | |
8805 | object is not a sequential action in the RM 9.10 sense and, therefore, does | |
8806 | not create a synchronization point. Second, in the case of @code{pragma Atomic}, | |
8807 | there is no guarantee that all the bits will be accessed if the reference | |
8808 | is not to the whole object; the compiler is allowed (and generally will) | |
8809 | access only part of the object in this case. | |
8810 | ||
8811 | @node Pragma Volatile_Function,Pragma Warning_As_Error,Pragma Volatile_Full_Access,Implementation Defined Pragmas | |
9daee425 | 8812 | @anchor{gnat_rm/implementation_defined_pragmas id57}@anchor{11d}@anchor{gnat_rm/implementation_defined_pragmas pragma-volatile-function}@anchor{11e} |
64d5610f ML |
8813 | @section Pragma Volatile_Function |
8814 | ||
8815 | ||
8816 | Syntax: | |
8817 | ||
8818 | @example | |
8819 | pragma Volatile_Function [ (static_boolean_EXPRESSION) ]; | |
8820 | @end example | |
8821 | ||
8822 | For the semantics of this pragma, see the entry for aspect @code{Volatile_Function} | |
8823 | in the SPARK 2014 Reference Manual, section 7.1.2. | |
8824 | ||
8825 | @node Pragma Warning_As_Error,Pragma Warnings,Pragma Volatile_Function,Implementation Defined Pragmas | |
9daee425 | 8826 | @anchor{gnat_rm/implementation_defined_pragmas pragma-warning-as-error}@anchor{11f} |
64d5610f ML |
8827 | @section Pragma Warning_As_Error |
8828 | ||
8829 | ||
8830 | Syntax: | |
8831 | ||
8832 | @example | |
8833 | pragma Warning_As_Error (static_string_EXPRESSION); | |
8834 | @end example | |
8835 | ||
8836 | This configuration pragma allows the programmer to specify a set | |
8837 | of warnings that will be treated as errors. Any warning that | |
8838 | matches the pattern given by the pragma argument will be treated | |
8839 | as an error. This gives more precise control than -gnatwe, | |
8840 | which treats warnings as errors. | |
8841 | ||
8842 | This pragma can apply to regular warnings (messages enabled by -gnatw) | |
8843 | and to style warnings (messages that start with “(style)”, | |
8844 | enabled by -gnaty). | |
8845 | ||
8846 | The pattern may contain asterisks, which match zero or more characters | |
8847 | in the message. For example, you can use @code{pragma Warning_As_Error | |
8848 | ("bits of*unused")} to treat the warning message @code{warning: 960 bits of | |
8849 | "a" unused} as an error. All characters other than asterisk are treated | |
8850 | as literal characters in the match. The match is case insensitive; for | |
8851 | example XYZ matches xyz. | |
8852 | ||
8853 | Note that the pattern matches if it occurs anywhere within the warning | |
8854 | message string (it is not necessary to put an asterisk at the start and | |
8855 | the end of the message, since this is implied). | |
8856 | ||
8857 | Another possibility for the static_string_EXPRESSION which works whether | |
1acce141 YM |
8858 | or not error tags are enabled (@emph{-gnatw.d}) is to use a single |
8859 | @emph{-gnatw} tag string, enclosed in brackets, | |
64d5610f ML |
8860 | as shown in the example below, to treat one category of warnings as errors. |
8861 | Note that if you want to treat multiple categories of warnings as errors, | |
8862 | you can use multiple pragma Warning_As_Error. | |
8863 | ||
8864 | The above use of patterns to match the message applies only to warning | |
8865 | messages generated by the front end. This pragma can also be applied to | |
9daee425 | 8866 | warnings provided by the back end and mentioned in @ref{120,,Pragma Warnings}. |
1acce141 | 8867 | By using a single full @emph{-Wxxx} switch in the pragma, such warnings |
64d5610f ML |
8868 | can also be treated as errors. |
8869 | ||
8870 | The pragma can appear either in a global configuration pragma file | |
8871 | (e.g. @code{gnat.adc}), or at the start of a file. Given a global | |
8872 | configuration pragma file containing: | |
8873 | ||
8874 | @example | |
8875 | pragma Warning_As_Error ("[-gnatwj]"); | |
8876 | @end example | |
8877 | ||
8878 | which will treat all obsolescent feature warnings as errors, the | |
8879 | following program compiles as shown (compile options here are | |
1acce141 | 8880 | @emph{-gnatwa.d -gnatl -gnatj55}). |
64d5610f ML |
8881 | |
8882 | @example | |
8883 | 1. pragma Warning_As_Error ("*never assigned*"); | |
8884 | 2. function Warnerr return String is | |
8885 | 3. X : Integer; | |
8886 | | | |
8887 | >>> error: variable "X" is never read and | |
8888 | never assigned [-gnatwv] [warning-as-error] | |
8889 | ||
8890 | 4. Y : Integer; | |
8891 | | | |
8892 | >>> warning: variable "Y" is assigned but | |
8893 | never read [-gnatwu] | |
8894 | ||
8895 | 5. begin | |
8896 | 6. Y := 0; | |
8897 | 7. return %ABC%; | |
8898 | | | |
8899 | >>> error: use of "%" is an obsolescent | |
8900 | feature (RM J.2(4)), use """ instead | |
8901 | [-gnatwj] [warning-as-error] | |
8902 | ||
8903 | 8. end; | |
8904 | ||
8905 | 8 lines: No errors, 3 warnings (2 treated as errors) | |
8906 | @end example | |
8907 | ||
8908 | Note that this pragma does not affect the set of warnings issued in | |
8909 | any way, it merely changes the effect of a matching warning if one | |
8910 | is produced as a result of other warnings options. As shown in this | |
8911 | example, if the pragma results in a warning being treated as an error, | |
8912 | the tag is changed from “warning:” to “error:” and the string | |
8913 | “[warning-as-error]” is appended to the end of the message. | |
8914 | ||
8915 | @node Pragma Warnings,Pragma Weak_External,Pragma Warning_As_Error,Implementation Defined Pragmas | |
9daee425 | 8916 | @anchor{gnat_rm/implementation_defined_pragmas id58}@anchor{121}@anchor{gnat_rm/implementation_defined_pragmas pragma-warnings}@anchor{120} |
64d5610f ML |
8917 | @section Pragma Warnings |
8918 | ||
8919 | ||
8920 | Syntax: | |
8921 | ||
8922 | @example | |
8923 | pragma Warnings ([TOOL_NAME,] DETAILS [, REASON]); | |
8924 | ||
8925 | DETAILS ::= On | Off | |
8926 | DETAILS ::= On | Off, local_NAME | |
8927 | DETAILS ::= static_string_EXPRESSION | |
8928 | DETAILS ::= On | Off, static_string_EXPRESSION | |
8929 | ||
8930 | TOOL_NAME ::= GNAT | GNATprove | |
8931 | ||
8932 | REASON ::= Reason => STRING_LITERAL @{& STRING_LITERAL@} | |
8933 | @end example | |
8934 | ||
8935 | Note: in Ada 83 mode, a string literal may be used in place of a static string | |
8936 | expression (which does not exist in Ada 83). | |
8937 | ||
8938 | Note if the second argument of @code{DETAILS} is a @code{local_NAME} then the | |
8939 | second form is always understood. If the intention is to use | |
8940 | the fourth form, then you can write @code{NAME & ""} to force the | |
1acce141 | 8941 | interpretation as a @emph{static_string_EXPRESSION}. |
64d5610f ML |
8942 | |
8943 | Note: if the first argument is a valid @code{TOOL_NAME}, it will be interpreted | |
8944 | that way. The use of the @code{TOOL_NAME} argument is relevant only to users | |
8945 | of SPARK and GNATprove, see last part of this section for details. | |
8946 | ||
8947 | Normally warnings are enabled, with the output being controlled by | |
8948 | the command line switch. Warnings (@code{Off}) turns off generation of | |
8949 | warnings until a Warnings (@code{On}) is encountered or the end of the | |
8950 | current unit. If generation of warnings is turned off using this | |
8951 | pragma, then some or all of the warning messages are suppressed, | |
8952 | regardless of the setting of the command line switches. | |
8953 | ||
8954 | The @code{Reason} parameter may optionally appear as the last argument | |
8955 | in any of the forms of this pragma. It is intended purely for the | |
8956 | purposes of documenting the reason for the @code{Warnings} pragma. | |
8957 | The compiler will check that the argument is a static string but | |
8958 | otherwise ignore this argument. Other tools may provide specialized | |
8959 | processing for this string. | |
8960 | ||
8961 | The form with a single argument (or two arguments if Reason present), | |
8962 | where the first argument is @code{ON} or @code{OFF} | |
8963 | may be used as a configuration pragma. | |
8964 | ||
8965 | If the @code{LOCAL_NAME} parameter is present, warnings are suppressed for | |
8966 | the specified entity. This suppression is effective from the point where | |
8967 | it occurs till the end of the extended scope of the variable (similar to | |
8968 | the scope of @code{Suppress}). This form cannot be used as a configuration | |
8969 | pragma. | |
8970 | ||
8971 | In the case where the first argument is other than @code{ON} or | |
8972 | @code{OFF}, | |
8973 | the third form with a single static_string_EXPRESSION argument (and possible | |
8974 | reason) provides more precise | |
8975 | control over which warnings are active. The string is a list of letters | |
8976 | specifying which warnings are to be activated and which deactivated. The | |
8977 | code for these letters is the same as the string used in the command | |
8978 | line switch controlling warnings. For a brief summary, use the gnatmake | |
8979 | command with no arguments, which will generate usage information containing | |
8980 | the list of warnings switches supported. For | |
8981 | full details see the section on @code{Warning Message Control} in the | |
8982 | @cite{GNAT User’s Guide}. | |
8983 | This form can also be used as a configuration pragma. | |
8984 | ||
8985 | The warnings controlled by the @code{-gnatw} switch are generated by the | |
8986 | front end of the compiler. The GCC back end can provide additional warnings | |
8987 | and they are controlled by the @code{-W} switch. Such warnings can be | |
8988 | identified by the appearance of a string of the form @code{[-W@{xxx@}]} in the | |
1acce141 YM |
8989 | message which designates the @code{-W@emph{xxx}} switch that controls the message. |
8990 | The form with a single @emph{static_string_EXPRESSION} argument also works for these | |
8991 | warnings, but the string must be a single full @code{-W@emph{xxx}} switch in this | |
64d5610f ML |
8992 | case. The above reference lists a few examples of these additional warnings. |
8993 | ||
8994 | The specified warnings will be in effect until the end of the program | |
8995 | or another pragma @code{Warnings} is encountered. The effect of the pragma is | |
8996 | cumulative. Initially the set of warnings is the standard default set | |
8997 | as possibly modified by compiler switches. Then each pragma Warning | |
8998 | modifies this set of warnings as specified. This form of the pragma may | |
8999 | also be used as a configuration pragma. | |
9000 | ||
9001 | The fourth form, with an @code{On|Off} parameter and a string, is used to | |
9002 | control individual messages, based on their text. The string argument | |
9003 | is a pattern that is used to match against the text of individual | |
1acce141 | 9004 | warning messages (not including the initial “warning: “ tag). |
64d5610f ML |
9005 | |
9006 | The pattern may contain asterisks, which match zero or more characters in | |
9007 | the message. For example, you can use | |
9008 | @code{pragma Warnings (Off, "bits of*unused")} to suppress the warning | |
9009 | message @code{warning: 960 bits of "a" unused}. No other regular | |
9010 | expression notations are permitted. All characters other than asterisk in | |
9011 | these three specific cases are treated as literal characters in the match. | |
9012 | The match is case insensitive, for example XYZ matches xyz. | |
9013 | ||
9014 | Note that the pattern matches if it occurs anywhere within the warning | |
9015 | message string (it is not necessary to put an asterisk at the start and | |
9016 | the end of the message, since this is implied). | |
9017 | ||
9018 | The above use of patterns to match the message applies only to warning | |
9019 | messages generated by the front end. This form of the pragma with a string | |
9020 | argument can also be used to control warnings provided by the back end and | |
1acce141 | 9021 | mentioned above. By using a single full @code{-W@emph{xxx}} switch in the pragma, |
64d5610f ML |
9022 | such warnings can be turned on and off. |
9023 | ||
9024 | There are two ways to use the pragma in this form. The OFF form can be used | |
9025 | as a configuration pragma. The effect is to suppress all warnings (if any) | |
9026 | that match the pattern string throughout the compilation (or match the | |
9027 | -W switch in the back end case). | |
9028 | ||
9029 | The second usage is to suppress a warning locally, and in this case, two | |
9030 | pragmas must appear in sequence: | |
9031 | ||
9032 | @example | |
9033 | pragma Warnings (Off, Pattern); | |
9034 | ... code where given warning is to be suppressed | |
9035 | pragma Warnings (On, Pattern); | |
9036 | @end example | |
9037 | ||
9038 | In this usage, the pattern string must match in the Off and On | |
1acce141 | 9039 | pragmas, and (if @emph{-gnatw.w} is given) at least one matching |
64d5610f ML |
9040 | warning must be suppressed. |
9041 | ||
9042 | Note: if the ON form is not found, then the effect of the OFF form extends | |
9043 | until the end of the file (pragma Warnings is purely textual, so its effect | |
9044 | does not stop at the end of the enclosing scope). | |
9045 | ||
9046 | Note: to write a string that will match any warning, use the string | |
9047 | @code{"***"}. It will not work to use a single asterisk or two | |
9048 | asterisks since this looks like an operator name. This form with three | |
9049 | asterisks is similar in effect to specifying @code{pragma Warnings (Off)} except (if @code{-gnatw.w} is given) that a matching | |
9050 | @code{pragma Warnings (On, "***")} will be required. This can be | |
9051 | helpful in avoiding forgetting to turn warnings back on. | |
9052 | ||
9053 | Note: the debug flag @code{-gnatd.i} can be | |
9054 | used to cause the compiler to entirely ignore all WARNINGS pragmas. This can | |
9055 | be useful in checking whether obsolete pragmas in existing programs are hiding | |
9056 | real problems. | |
9057 | ||
9058 | Note: pragma Warnings does not affect the processing of style messages. See | |
9059 | separate entry for pragma Style_Checks for control of style messages. | |
9060 | ||
9061 | Users of the formal verification tool GNATprove for the SPARK subset of Ada may | |
9062 | use the version of the pragma with a @code{TOOL_NAME} parameter. | |
9063 | ||
9064 | If present, @code{TOOL_NAME} is the name of a tool, currently either @code{GNAT} for the | |
9065 | compiler or @code{GNATprove} for the formal verification tool. A given tool only | |
9066 | takes into account pragma Warnings that do not specify a tool name, or that | |
9067 | specify the matching tool name. This makes it possible to disable warnings | |
9068 | selectively for each tool, and as a consequence to detect useless pragma | |
9069 | Warnings with switch @code{-gnatw.w}. | |
9070 | ||
9071 | @node Pragma Weak_External,Pragma Wide_Character_Encoding,Pragma Warnings,Implementation Defined Pragmas | |
9daee425 | 9072 | @anchor{gnat_rm/implementation_defined_pragmas pragma-weak-external}@anchor{122} |
64d5610f ML |
9073 | @section Pragma Weak_External |
9074 | ||
9075 | ||
9076 | Syntax: | |
9077 | ||
9078 | @example | |
9079 | pragma Weak_External ([Entity =>] LOCAL_NAME); | |
9080 | @end example | |
9081 | ||
9082 | @code{LOCAL_NAME} must refer to an object that is declared at the library | |
9083 | level. This pragma specifies that the given entity should be marked as a | |
9084 | weak symbol for the linker. It is equivalent to @code{__attribute__((weak))} | |
9085 | in GNU C and causes @code{LOCAL_NAME} to be emitted as a weak symbol instead | |
9086 | of a regular symbol, that is to say a symbol that does not have to be | |
9087 | resolved by the linker if used in conjunction with a pragma Import. | |
9088 | ||
9089 | When a weak symbol is not resolved by the linker, its address is set to | |
9090 | zero. This is useful in writing interfaces to external modules that may | |
9091 | or may not be linked in the final executable, for example depending on | |
9092 | configuration settings. | |
9093 | ||
9094 | If a program references at run time an entity to which this pragma has been | |
9095 | applied, and the corresponding symbol was not resolved at link time, then | |
9096 | the execution of the program is erroneous. It is not erroneous to take the | |
9097 | Address of such an entity, for example to guard potential references, | |
9098 | as shown in the example below. | |
9099 | ||
9100 | Some file formats do not support weak symbols so not all target machines | |
9101 | support this pragma. | |
9102 | ||
9103 | @example | |
9104 | -- Example of the use of pragma Weak_External | |
9105 | ||
9106 | package External_Module is | |
9107 | key : Integer; | |
9108 | pragma Import (C, key); | |
9109 | pragma Weak_External (key); | |
9110 | function Present return boolean; | |
9111 | end External_Module; | |
9112 | ||
9113 | with System; use System; | |
9114 | package body External_Module is | |
9115 | function Present return boolean is | |
9116 | begin | |
9117 | return key'Address /= System.Null_Address; | |
9118 | end Present; | |
9119 | end External_Module; | |
9120 | @end example | |
9121 | ||
9122 | @node Pragma Wide_Character_Encoding,,Pragma Weak_External,Implementation Defined Pragmas | |
9daee425 | 9123 | @anchor{gnat_rm/implementation_defined_pragmas pragma-wide-character-encoding}@anchor{123} |
64d5610f ML |
9124 | @section Pragma Wide_Character_Encoding |
9125 | ||
9126 | ||
9127 | Syntax: | |
9128 | ||
9129 | @example | |
9130 | pragma Wide_Character_Encoding (IDENTIFIER | CHARACTER_LITERAL); | |
9131 | @end example | |
9132 | ||
9133 | This pragma specifies the wide character encoding to be used in program | |
9134 | source text appearing subsequently. It is a configuration pragma, but may | |
9135 | also be used at any point that a pragma is allowed, and it is permissible | |
9136 | to have more than one such pragma in a file, allowing multiple encodings | |
9137 | to appear within the same file. | |
9138 | ||
9139 | However, note that the pragma cannot immediately precede the relevant | |
9140 | wide character, because then the previous encoding will still be in | |
9141 | effect, causing “illegal character” errors. | |
9142 | ||
9143 | The argument can be an identifier or a character literal. In the identifier | |
9144 | case, it is one of @code{HEX}, @code{UPPER}, @code{SHIFT_JIS}, | |
9145 | @code{EUC}, @code{UTF8}, or @code{BRACKETS}. In the character literal | |
9146 | case it is correspondingly one of the characters @code{h}, @code{u}, | |
9147 | @code{s}, @code{e}, @code{8}, or @code{b}. | |
9148 | ||
9149 | Note that when the pragma is used within a file, it affects only the | |
9150 | encoding within that file, and does not affect withed units, specs, | |
9151 | or subunits. | |
9152 | ||
9153 | @node Implementation Defined Aspects,Implementation Defined Attributes,Implementation Defined Pragmas,Top | |
9daee425 | 9154 | @anchor{gnat_rm/implementation_defined_aspects doc}@anchor{124}@anchor{gnat_rm/implementation_defined_aspects id1}@anchor{125}@anchor{gnat_rm/implementation_defined_aspects implementation-defined-aspects}@anchor{126} |
64d5610f ML |
9155 | @chapter Implementation Defined Aspects |
9156 | ||
9157 | ||
9158 | Ada defines (throughout the Ada 2012 reference manual, summarized | |
9159 | in Annex K) a set of aspects that can be specified for certain entities. | |
9160 | These language defined aspects are implemented in GNAT in Ada 2012 mode | |
9161 | and work as described in the Ada 2012 Reference Manual. | |
9162 | ||
9163 | In addition, Ada 2012 allows implementations to define additional aspects | |
9164 | whose meaning is defined by the implementation. GNAT provides | |
9165 | a number of these implementation-defined aspects which can be used | |
9166 | to extend and enhance the functionality of the compiler. This section of | |
9167 | the GNAT reference manual describes these additional aspects. | |
9168 | ||
9169 | Note that any program using these aspects may not be portable to | |
9170 | other compilers (although GNAT implements this set of aspects on all | |
9171 | platforms). Therefore if portability to other compilers is an important | |
9172 | consideration, you should minimize the use of these aspects. | |
9173 | ||
9174 | Note that for many of these aspects, the effect is essentially similar | |
9175 | to the use of a pragma or attribute specification with the same name | |
9176 | applied to the entity. For example, if we write: | |
9177 | ||
9178 | @example | |
9179 | type R is range 1 .. 100 | |
9180 | with Value_Size => 10; | |
9181 | @end example | |
9182 | ||
9183 | then the effect is the same as: | |
9184 | ||
9185 | @example | |
9186 | type R is range 1 .. 100; | |
9187 | for R'Value_Size use 10; | |
9188 | @end example | |
9189 | ||
9190 | and if we write: | |
9191 | ||
9192 | @example | |
9193 | type R is new Integer | |
9194 | with Shared => True; | |
9195 | @end example | |
9196 | ||
9197 | then the effect is the same as: | |
9198 | ||
9199 | @example | |
9200 | type R is new Integer; | |
9201 | pragma Shared (R); | |
9202 | @end example | |
9203 | ||
9204 | In the documentation below, such cases are simply marked | |
9205 | as being boolean aspects equivalent to the corresponding pragma | |
9206 | or attribute definition clause. | |
9207 | ||
9208 | @menu | |
9209 | * Aspect Abstract_State:: | |
9210 | * Aspect Annotate:: | |
9211 | * Aspect Async_Readers:: | |
9212 | * Aspect Async_Writers:: | |
9213 | * Aspect Constant_After_Elaboration:: | |
9214 | * Aspect Contract_Cases:: | |
9215 | * Aspect Depends:: | |
9216 | * Aspect Default_Initial_Condition:: | |
9217 | * Aspect Dimension:: | |
9218 | * Aspect Dimension_System:: | |
9219 | * Aspect Disable_Controlled:: | |
9220 | * Aspect Effective_Reads:: | |
9221 | * Aspect Effective_Writes:: | |
9222 | * Aspect Extensions_Visible:: | |
9223 | * Aspect Favor_Top_Level:: | |
9224 | * Aspect Ghost:: | |
067d80d8 | 9225 | * Aspect Ghost_Predicate:: |
64d5610f ML |
9226 | * Aspect Global:: |
9227 | * Aspect Initial_Condition:: | |
9228 | * Aspect Initializes:: | |
9229 | * Aspect Inline_Always:: | |
9230 | * Aspect Invariant:: | |
9231 | * Aspect Invariant’Class:: | |
9232 | * Aspect Iterable:: | |
9233 | * Aspect Linker_Section:: | |
9daee425 | 9234 | * Aspect Local_Restrictions:: |
64d5610f ML |
9235 | * Aspect Lock_Free:: |
9236 | * Aspect Max_Queue_Length:: | |
9237 | * Aspect No_Caching:: | |
9238 | * Aspect No_Elaboration_Code_All:: | |
9239 | * Aspect No_Inline:: | |
9240 | * Aspect No_Tagged_Streams:: | |
9241 | * Aspect No_Task_Parts:: | |
9242 | * Aspect Object_Size:: | |
9243 | * Aspect Obsolescent:: | |
9244 | * Aspect Part_Of:: | |
9245 | * Aspect Persistent_BSS:: | |
9246 | * Aspect Predicate:: | |
9247 | * Aspect Pure_Function:: | |
9248 | * Aspect Refined_Depends:: | |
9249 | * Aspect Refined_Global:: | |
9250 | * Aspect Refined_Post:: | |
9251 | * Aspect Refined_State:: | |
9252 | * Aspect Relaxed_Initialization:: | |
9253 | * Aspect Remote_Access_Type:: | |
9254 | * Aspect Secondary_Stack_Size:: | |
9255 | * Aspect Scalar_Storage_Order:: | |
9256 | * Aspect Shared:: | |
04d6c745 | 9257 | * Aspect Side_Effects:: |
64d5610f ML |
9258 | * Aspect Simple_Storage_Pool:: |
9259 | * Aspect Simple_Storage_Pool_Type:: | |
9260 | * Aspect SPARK_Mode:: | |
9261 | * Aspect Suppress_Debug_Info:: | |
9262 | * Aspect Suppress_Initialization:: | |
9263 | * Aspect Test_Case:: | |
9264 | * Aspect Thread_Local_Storage:: | |
9265 | * Aspect Universal_Aliasing:: | |
9266 | * Aspect Unmodified:: | |
9267 | * Aspect Unreferenced:: | |
9268 | * Aspect Unreferenced_Objects:: | |
9daee425 | 9269 | * Aspect User_Aspect:: |
64d5610f ML |
9270 | * Aspect Value_Size:: |
9271 | * Aspect Volatile_Full_Access:: | |
9272 | * Aspect Volatile_Function:: | |
9273 | * Aspect Warnings:: | |
9274 | ||
9275 | @end menu | |
9276 | ||
9277 | @node Aspect Abstract_State,Aspect Annotate,,Implementation Defined Aspects | |
9daee425 | 9278 | @anchor{gnat_rm/implementation_defined_aspects aspect-abstract-state}@anchor{127} |
64d5610f ML |
9279 | @section Aspect Abstract_State |
9280 | ||
9281 | ||
9282 | @geindex Abstract_State | |
9283 | ||
9284 | This aspect is equivalent to @ref{1e,,pragma Abstract_State}. | |
9285 | ||
9286 | @node Aspect Annotate,Aspect Async_Readers,Aspect Abstract_State,Implementation Defined Aspects | |
9daee425 | 9287 | @anchor{gnat_rm/implementation_defined_aspects aspect-annotate}@anchor{128} |
64d5610f ML |
9288 | @section Aspect Annotate |
9289 | ||
9290 | ||
9291 | @geindex Annotate | |
9292 | ||
9293 | There are three forms of this aspect (where ID is an identifier, | |
9294 | and ARG is a general expression), | |
9295 | corresponding to @ref{29,,pragma Annotate}. | |
9296 | ||
9297 | ||
9298 | @table @asis | |
9299 | ||
1acce141 | 9300 | @item @emph{Annotate => ID} |
64d5610f ML |
9301 | |
9302 | Equivalent to @code{pragma Annotate (ID, Entity => Name);} | |
9303 | ||
1acce141 | 9304 | @item @emph{Annotate => (ID)} |
64d5610f ML |
9305 | |
9306 | Equivalent to @code{pragma Annotate (ID, Entity => Name);} | |
9307 | ||
1acce141 | 9308 | @item @emph{Annotate => (ID ,ID @{, ARG@})} |
64d5610f ML |
9309 | |
9310 | Equivalent to @code{pragma Annotate (ID, ID @{, ARG@}, Entity => Name);} | |
9311 | @end table | |
9312 | ||
9313 | @node Aspect Async_Readers,Aspect Async_Writers,Aspect Annotate,Implementation Defined Aspects | |
9daee425 | 9314 | @anchor{gnat_rm/implementation_defined_aspects aspect-async-readers}@anchor{129} |
64d5610f ML |
9315 | @section Aspect Async_Readers |
9316 | ||
9317 | ||
9318 | @geindex Async_Readers | |
9319 | ||
9320 | This boolean aspect is equivalent to @ref{30,,pragma Async_Readers}. | |
9321 | ||
9322 | @node Aspect Async_Writers,Aspect Constant_After_Elaboration,Aspect Async_Readers,Implementation Defined Aspects | |
9daee425 | 9323 | @anchor{gnat_rm/implementation_defined_aspects aspect-async-writers}@anchor{12a} |
64d5610f ML |
9324 | @section Aspect Async_Writers |
9325 | ||
9326 | ||
9327 | @geindex Async_Writers | |
9328 | ||
9329 | This boolean aspect is equivalent to @ref{32,,pragma Async_Writers}. | |
9330 | ||
9331 | @node Aspect Constant_After_Elaboration,Aspect Contract_Cases,Aspect Async_Writers,Implementation Defined Aspects | |
9daee425 | 9332 | @anchor{gnat_rm/implementation_defined_aspects aspect-constant-after-elaboration}@anchor{12b} |
64d5610f ML |
9333 | @section Aspect Constant_After_Elaboration |
9334 | ||
9335 | ||
9336 | @geindex Constant_After_Elaboration | |
9337 | ||
9338 | This aspect is equivalent to @ref{42,,pragma Constant_After_Elaboration}. | |
9339 | ||
9340 | @node Aspect Contract_Cases,Aspect Depends,Aspect Constant_After_Elaboration,Implementation Defined Aspects | |
9daee425 | 9341 | @anchor{gnat_rm/implementation_defined_aspects aspect-contract-cases}@anchor{12c} |
64d5610f ML |
9342 | @section Aspect Contract_Cases |
9343 | ||
9344 | ||
9345 | @geindex Contract_Cases | |
9346 | ||
9347 | This aspect is equivalent to @ref{44,,pragma Contract_Cases}, the sequence | |
9348 | of clauses being enclosed in parentheses so that syntactically it is an | |
9349 | aggregate. | |
9350 | ||
9351 | @node Aspect Depends,Aspect Default_Initial_Condition,Aspect Contract_Cases,Implementation Defined Aspects | |
9daee425 | 9352 | @anchor{gnat_rm/implementation_defined_aspects aspect-depends}@anchor{12d} |
64d5610f ML |
9353 | @section Aspect Depends |
9354 | ||
9355 | ||
9356 | @geindex Depends | |
9357 | ||
9358 | This aspect is equivalent to @ref{54,,pragma Depends}. | |
9359 | ||
9360 | @node Aspect Default_Initial_Condition,Aspect Dimension,Aspect Depends,Implementation Defined Aspects | |
9daee425 | 9361 | @anchor{gnat_rm/implementation_defined_aspects aspect-default-initial-condition}@anchor{12e} |
64d5610f ML |
9362 | @section Aspect Default_Initial_Condition |
9363 | ||
9364 | ||
9365 | @geindex Default_Initial_Condition | |
9366 | ||
6f089469 | 9367 | This aspect is equivalent to @ref{50,,pragma Default_Initial_Condition}. |
64d5610f ML |
9368 | |
9369 | @node Aspect Dimension,Aspect Dimension_System,Aspect Default_Initial_Condition,Implementation Defined Aspects | |
9daee425 | 9370 | @anchor{gnat_rm/implementation_defined_aspects aspect-dimension}@anchor{12f} |
64d5610f ML |
9371 | @section Aspect Dimension |
9372 | ||
9373 | ||
9374 | @geindex Dimension | |
9375 | ||
9376 | The @code{Dimension} aspect is used to specify the dimensions of a given | |
9377 | subtype of a dimensioned numeric type. The aspect also specifies a symbol | |
9378 | used when doing formatted output of dimensioned quantities. The syntax is: | |
9379 | ||
9380 | @example | |
9381 | with Dimension => | |
9382 | ([Symbol =>] SYMBOL, DIMENSION_VALUE @{, DIMENSION_Value@}) | |
9383 | ||
9384 | SYMBOL ::= STRING_LITERAL | CHARACTER_LITERAL | |
9385 | ||
9386 | DIMENSION_VALUE ::= | |
9387 | RATIONAL | |
9388 | | others => RATIONAL | |
9389 | | DISCRETE_CHOICE_LIST => RATIONAL | |
9390 | ||
9391 | RATIONAL ::= [-] NUMERIC_LITERAL [/ NUMERIC_LITERAL] | |
9392 | @end example | |
9393 | ||
9394 | This aspect can only be applied to a subtype whose parent type has | |
9395 | a @code{Dimension_System} aspect. The aspect must specify values for | |
9396 | all dimensions of the system. The rational values are the powers of the | |
9397 | corresponding dimensions that are used by the compiler to verify that | |
9398 | physical (numeric) computations are dimensionally consistent. For example, | |
9399 | the computation of a force must result in dimensions (L => 1, M => 1, T => -2). | |
9400 | For further examples of the usage | |
9401 | of this aspect, see package @code{System.Dim.Mks}. | |
9402 | Note that when the dimensioned type is an integer type, then any | |
9403 | dimension value must be an integer literal. | |
9404 | ||
9405 | @node Aspect Dimension_System,Aspect Disable_Controlled,Aspect Dimension,Implementation Defined Aspects | |
9daee425 | 9406 | @anchor{gnat_rm/implementation_defined_aspects aspect-dimension-system}@anchor{130} |
64d5610f ML |
9407 | @section Aspect Dimension_System |
9408 | ||
9409 | ||
9410 | @geindex Dimension_System | |
9411 | ||
9412 | The @code{Dimension_System} aspect is used to define a system of | |
9413 | dimensions that will be used in subsequent subtype declarations with | |
9414 | @code{Dimension} aspects that reference this system. The syntax is: | |
9415 | ||
9416 | @example | |
9417 | with Dimension_System => (DIMENSION @{, DIMENSION@}); | |
9418 | ||
9419 | DIMENSION ::= ([Unit_Name =>] IDENTIFIER, | |
9420 | [Unit_Symbol =>] SYMBOL, | |
9421 | [Dim_Symbol =>] SYMBOL) | |
9422 | ||
9423 | SYMBOL ::= CHARACTER_LITERAL | STRING_LITERAL | |
9424 | @end example | |
9425 | ||
9426 | This aspect is applied to a type, which must be a numeric derived type | |
9427 | (typically a floating-point type), that | |
9428 | will represent values within the dimension system. Each @code{DIMENSION} | |
9429 | corresponds to one particular dimension. A maximum of 7 dimensions may | |
9430 | be specified. @code{Unit_Name} is the name of the dimension (for example | |
9431 | @code{Meter}). @code{Unit_Symbol} is the shorthand used for quantities | |
9432 | of this dimension (for example @code{m} for @code{Meter}). | |
9433 | @code{Dim_Symbol} gives | |
9434 | the identification within the dimension system (typically this is a | |
9435 | single letter, e.g. @code{L} standing for length for unit name @code{Meter}). | |
9436 | The @code{Unit_Symbol} is used in formatted output of dimensioned quantities. | |
9437 | The @code{Dim_Symbol} is used in error messages when numeric operations have | |
9438 | inconsistent dimensions. | |
9439 | ||
9440 | GNAT provides the standard definition of the International MKS system in | |
9441 | the run-time package @code{System.Dim.Mks}. You can easily define | |
9442 | similar packages for cgs units or British units, and define conversion factors | |
9443 | between values in different systems. The MKS system is characterized by the | |
9444 | following aspect: | |
9445 | ||
9446 | @example | |
9447 | type Mks_Type is new Long_Long_Float with | |
9448 | Dimension_System => ( | |
9449 | (Unit_Name => Meter, Unit_Symbol => 'm', Dim_Symbol => 'L'), | |
9450 | (Unit_Name => Kilogram, Unit_Symbol => "kg", Dim_Symbol => 'M'), | |
9451 | (Unit_Name => Second, Unit_Symbol => 's', Dim_Symbol => 'T'), | |
9452 | (Unit_Name => Ampere, Unit_Symbol => 'A', Dim_Symbol => 'I'), | |
9453 | (Unit_Name => Kelvin, Unit_Symbol => 'K', Dim_Symbol => '@@'), | |
9454 | (Unit_Name => Mole, Unit_Symbol => "mol", Dim_Symbol => 'N'), | |
9455 | (Unit_Name => Candela, Unit_Symbol => "cd", Dim_Symbol => 'J')); | |
9456 | @end example | |
9457 | ||
9458 | Note that in the above type definition, we use the @code{at} symbol (@code{@@}) to | |
9459 | represent a theta character (avoiding the use of extended Latin-1 | |
9460 | characters in this context). | |
9461 | ||
9462 | See section ‘Performing Dimensionality Analysis in GNAT’ in the GNAT Users | |
9463 | Guide for detailed examples of use of the dimension system. | |
9464 | ||
9465 | @node Aspect Disable_Controlled,Aspect Effective_Reads,Aspect Dimension_System,Implementation Defined Aspects | |
9daee425 | 9466 | @anchor{gnat_rm/implementation_defined_aspects aspect-disable-controlled}@anchor{131} |
64d5610f ML |
9467 | @section Aspect Disable_Controlled |
9468 | ||
9469 | ||
9470 | @geindex Disable_Controlled | |
9471 | ||
9472 | The aspect @code{Disable_Controlled} is defined for controlled record types. If | |
9473 | active, this aspect causes suppression of all related calls to @code{Initialize}, | |
9474 | @code{Adjust}, and @code{Finalize}. The intended use is for conditional compilation, | |
9475 | where for example you might want a record to be controlled or not depending on | |
9476 | whether some run-time check is enabled or suppressed. | |
9477 | ||
9478 | @node Aspect Effective_Reads,Aspect Effective_Writes,Aspect Disable_Controlled,Implementation Defined Aspects | |
9daee425 | 9479 | @anchor{gnat_rm/implementation_defined_aspects aspect-effective-reads}@anchor{132} |
64d5610f ML |
9480 | @section Aspect Effective_Reads |
9481 | ||
9482 | ||
9483 | @geindex Effective_Reads | |
9484 | ||
9485 | This aspect is equivalent to @ref{59,,pragma Effective_Reads}. | |
9486 | ||
9487 | @node Aspect Effective_Writes,Aspect Extensions_Visible,Aspect Effective_Reads,Implementation Defined Aspects | |
9daee425 | 9488 | @anchor{gnat_rm/implementation_defined_aspects aspect-effective-writes}@anchor{133} |
64d5610f ML |
9489 | @section Aspect Effective_Writes |
9490 | ||
9491 | ||
9492 | @geindex Effective_Writes | |
9493 | ||
9494 | This aspect is equivalent to @ref{5b,,pragma Effective_Writes}. | |
9495 | ||
9496 | @node Aspect Extensions_Visible,Aspect Favor_Top_Level,Aspect Effective_Writes,Implementation Defined Aspects | |
9daee425 | 9497 | @anchor{gnat_rm/implementation_defined_aspects aspect-extensions-visible}@anchor{134} |
64d5610f ML |
9498 | @section Aspect Extensions_Visible |
9499 | ||
9500 | ||
9501 | @geindex Extensions_Visible | |
9502 | ||
b71d4b62 | 9503 | This aspect is equivalent to @ref{69,,pragma Extensions_Visible}. |
64d5610f ML |
9504 | |
9505 | @node Aspect Favor_Top_Level,Aspect Ghost,Aspect Extensions_Visible,Implementation Defined Aspects | |
9daee425 | 9506 | @anchor{gnat_rm/implementation_defined_aspects aspect-favor-top-level}@anchor{135} |
64d5610f ML |
9507 | @section Aspect Favor_Top_Level |
9508 | ||
9509 | ||
9510 | @geindex Favor_Top_Level | |
9511 | ||
b71d4b62 | 9512 | This boolean aspect is equivalent to @ref{6e,,pragma Favor_Top_Level}. |
64d5610f | 9513 | |
067d80d8 | 9514 | @node Aspect Ghost,Aspect Ghost_Predicate,Aspect Favor_Top_Level,Implementation Defined Aspects |
9daee425 | 9515 | @anchor{gnat_rm/implementation_defined_aspects aspect-ghost}@anchor{136} |
64d5610f ML |
9516 | @section Aspect Ghost |
9517 | ||
9518 | ||
9519 | @geindex Ghost | |
9520 | ||
b71d4b62 | 9521 | This aspect is equivalent to @ref{72,,pragma Ghost}. |
64d5610f | 9522 | |
067d80d8 | 9523 | @node Aspect Ghost_Predicate,Aspect Global,Aspect Ghost,Implementation Defined Aspects |
9daee425 | 9524 | @anchor{gnat_rm/implementation_defined_aspects aspect-ghost-predicate}@anchor{137} |
067d80d8 YM |
9525 | @section Aspect Ghost_Predicate |
9526 | ||
9527 | ||
9528 | @geindex Ghost_Predicate | |
9529 | ||
9530 | This aspect introduces a subtype predicate that can reference ghost | |
9531 | entities. The subtype cannot appear as a subtype_mark in a membership test. | |
9532 | ||
9533 | For the detailed semantics of this aspect, see the entry for subtype predicates | |
9534 | in the SPARK Reference Manual, section 3.2.4. | |
9535 | ||
9536 | @node Aspect Global,Aspect Initial_Condition,Aspect Ghost_Predicate,Implementation Defined Aspects | |
9daee425 | 9537 | @anchor{gnat_rm/implementation_defined_aspects aspect-global}@anchor{138} |
64d5610f ML |
9538 | @section Aspect Global |
9539 | ||
9540 | ||
9541 | @geindex Global | |
9542 | ||
b71d4b62 | 9543 | This aspect is equivalent to @ref{74,,pragma Global}. |
64d5610f ML |
9544 | |
9545 | @node Aspect Initial_Condition,Aspect Initializes,Aspect Global,Implementation Defined Aspects | |
9daee425 | 9546 | @anchor{gnat_rm/implementation_defined_aspects aspect-initial-condition}@anchor{139} |
64d5610f ML |
9547 | @section Aspect Initial_Condition |
9548 | ||
9549 | ||
9550 | @geindex Initial_Condition | |
9551 | ||
b71d4b62 | 9552 | This aspect is equivalent to @ref{81,,pragma Initial_Condition}. |
64d5610f ML |
9553 | |
9554 | @node Aspect Initializes,Aspect Inline_Always,Aspect Initial_Condition,Implementation Defined Aspects | |
9daee425 | 9555 | @anchor{gnat_rm/implementation_defined_aspects aspect-initializes}@anchor{13a} |
64d5610f ML |
9556 | @section Aspect Initializes |
9557 | ||
9558 | ||
9559 | @geindex Initializes | |
9560 | ||
b71d4b62 | 9561 | This aspect is equivalent to @ref{84,,pragma Initializes}. |
64d5610f ML |
9562 | |
9563 | @node Aspect Inline_Always,Aspect Invariant,Aspect Initializes,Implementation Defined Aspects | |
9daee425 | 9564 | @anchor{gnat_rm/implementation_defined_aspects aspect-inline-always}@anchor{13b} |
64d5610f ML |
9565 | @section Aspect Inline_Always |
9566 | ||
9567 | ||
9568 | @geindex Inline_Always | |
9569 | ||
b71d4b62 | 9570 | This boolean aspect is equivalent to @ref{86,,pragma Inline_Always}. |
64d5610f ML |
9571 | |
9572 | @node Aspect Invariant,Aspect Invariant’Class,Aspect Inline_Always,Implementation Defined Aspects | |
9daee425 | 9573 | @anchor{gnat_rm/implementation_defined_aspects aspect-invariant}@anchor{13c} |
64d5610f ML |
9574 | @section Aspect Invariant |
9575 | ||
9576 | ||
9577 | @geindex Invariant | |
9578 | ||
b71d4b62 | 9579 | This aspect is equivalent to @ref{8d,,pragma Invariant}. It is a |
64d5610f ML |
9580 | synonym for the language defined aspect @code{Type_Invariant} except |
9581 | that it is separately controllable using pragma @code{Assertion_Policy}. | |
9582 | ||
9583 | @node Aspect Invariant’Class,Aspect Iterable,Aspect Invariant,Implementation Defined Aspects | |
9daee425 | 9584 | @anchor{gnat_rm/implementation_defined_aspects aspect-invariant-class}@anchor{13d} |
64d5610f ML |
9585 | @section Aspect Invariant’Class |
9586 | ||
9587 | ||
9588 | @geindex Invariant'Class | |
9589 | ||
04d6c745 | 9590 | This aspect is equivalent to @ref{106,,pragma Type_Invariant_Class}. It is a |
64d5610f ML |
9591 | synonym for the language defined aspect @code{Type_Invariant'Class} except |
9592 | that it is separately controllable using pragma @code{Assertion_Policy}. | |
9593 | ||
9594 | @node Aspect Iterable,Aspect Linker_Section,Aspect Invariant’Class,Implementation Defined Aspects | |
9daee425 | 9595 | @anchor{gnat_rm/implementation_defined_aspects aspect-iterable}@anchor{13e} |
64d5610f ML |
9596 | @section Aspect Iterable |
9597 | ||
9598 | ||
9599 | @geindex Iterable | |
9600 | ||
9601 | This aspect provides a light-weight mechanism for loops and quantified | |
9602 | expressions over container types, without the overhead imposed by the tampering | |
9603 | checks of standard Ada 2012 iterators. The value of the aspect is an aggregate | |
9604 | with six named components, of which the last three are optional: @code{First}, | |
9605 | @code{Next}, @code{Has_Element}, @code{Element}, @code{Last}, and @code{Previous}. | |
9606 | When only the first three components are specified, only the | |
9607 | @code{for .. in} form of iteration over cursors is available. When @code{Element} | |
9608 | is specified, both this form and the @code{for .. of} form of iteration over | |
9609 | elements are available. If the last two components are specified, reverse | |
9610 | iterations over the container can be specified (analogous to what can be done | |
9611 | over predefined containers that support the @code{Reverse_Iterator} interface). | |
9612 | The following is a typical example of use: | |
9613 | ||
9614 | @example | |
9615 | type List is private with | |
9616 | Iterable => (First => First_Cursor, | |
9617 | Next => Advance, | |
9618 | Has_Element => Cursor_Has_Element | |
9619 | [,Element => Get_Element] | |
9620 | [,Last => Last_Cursor] | |
9621 | [,Previous => Retreat]); | |
9622 | @end example | |
9623 | ||
9624 | ||
9625 | @itemize * | |
9626 | ||
9627 | @item | |
9628 | The values of @code{First} and @code{Last} are primitive operations of the | |
9629 | container type that return a @code{Cursor}, which must be a type declared in | |
9630 | the container package or visible from it. For example: | |
9631 | @end itemize | |
9632 | ||
9633 | @example | |
9634 | function First_Cursor (Cont : Container) return Cursor; | |
9635 | function Last_Cursor (Cont : Container) return Cursor; | |
9636 | @end example | |
9637 | ||
9638 | ||
9639 | @itemize * | |
9640 | ||
9641 | @item | |
9642 | The values of @code{Next} and @code{Previous} are primitive operations of the container type that take | |
9643 | both a container and a cursor and yield a cursor. For example: | |
9644 | @end itemize | |
9645 | ||
9646 | @example | |
9647 | function Advance (Cont : Container; Position : Cursor) return Cursor; | |
9648 | function Retreat (Cont : Container; Position : Cursor) return Cursor; | |
9649 | @end example | |
9650 | ||
9651 | ||
9652 | @itemize * | |
9653 | ||
9654 | @item | |
9655 | The value of @code{Has_Element} is a primitive operation of the container type | |
9656 | that takes both a container and a cursor and yields a boolean. For example: | |
9657 | @end itemize | |
9658 | ||
9659 | @example | |
9660 | function Cursor_Has_Element (Cont : Container; Position : Cursor) return Boolean; | |
9661 | @end example | |
9662 | ||
9663 | ||
9664 | @itemize * | |
9665 | ||
9666 | @item | |
9667 | The value of @code{Element} is a primitive operation of the container type that | |
9668 | takes both a container and a cursor and yields an @code{Element_Type}, which must | |
9669 | be a type declared in the container package or visible from it. For example: | |
9670 | @end itemize | |
9671 | ||
9672 | @example | |
9673 | function Get_Element (Cont : Container; Position : Cursor) return Element_Type; | |
9674 | @end example | |
9675 | ||
9676 | This aspect is used in the GNAT-defined formal container packages. | |
9677 | ||
9daee425 SB |
9678 | @node Aspect Linker_Section,Aspect Local_Restrictions,Aspect Iterable,Implementation Defined Aspects |
9679 | @anchor{gnat_rm/implementation_defined_aspects aspect-linker-section}@anchor{13f} | |
64d5610f ML |
9680 | @section Aspect Linker_Section |
9681 | ||
9682 | ||
9683 | @geindex Linker_Section | |
9684 | ||
b71d4b62 | 9685 | This aspect is equivalent to @ref{95,,pragma Linker_Section}. |
64d5610f | 9686 | |
9daee425 SB |
9687 | @node Aspect Local_Restrictions,Aspect Lock_Free,Aspect Linker_Section,Implementation Defined Aspects |
9688 | @anchor{gnat_rm/implementation_defined_aspects aspect-local-restrictions}@anchor{140} | |
9689 | @section Aspect Local_Restrictions | |
9690 | ||
9691 | ||
9692 | @geindex Local_Restrictions | |
9693 | ||
9694 | This aspect may be specified for a subprogram (and for other declarations | |
9695 | as described below). It is used to specify that a particular subprogram does | |
9696 | not violate one or more local restrictions, nor can it call a subprogram | |
9697 | that is not subject to the same requirement. Positional aggregate syntax | |
9698 | (with parentheses, not square brackets) may be used to specify more than one | |
9699 | local restriction, as in | |
9700 | ||
9701 | @example | |
9702 | procedure Do_Something | |
9703 | with Local_Restrictions => (Some_Restriction, Another_Restriction); | |
9704 | @end example | |
9705 | ||
9706 | Parentheses are currently required even in the case of specifying a single | |
9707 | local restriction (this requirement may be relaxed in the future). | |
9708 | Supported local restrictions currently include (only) No_Heap_Allocations and | |
9709 | No_Secondary_Stack. | |
9710 | No_Secondary_Stack corresponds to the GNAT-defined (global) restriction | |
9711 | of the same name. No_Heap_Allocations corresponds to the conjunction of the | |
9712 | Ada-defined restrictions No_Allocators and No_Implicit_Heap_Allocations. | |
9713 | ||
9714 | Additional requirements are imposed in order to ensure that restriction | |
9715 | violations cannot be achieved via overriding dispatching operations, | |
9716 | calling through an access-to-subprogram value, calling a generic formal | |
9717 | subprogram, or calling through a subprogram renaming. | |
9718 | For a dispatching operation, an overrider must be subject to (at least) the | |
9719 | same restrictions as the overridden inherited subprogram; similarly, the | |
9720 | actual subprogram corresponding to a generic formal subprogram | |
9721 | in an instantiation must be subject to (at least) the same restrictions | |
9722 | as the formal subprogram. A call through an access-to-subprogram value | |
9723 | is conservatively assumed to violate all local restrictions; tasking-related | |
9724 | constructs (notably entry calls) are treated similarly. A renaming-as-body is | |
9725 | treated like a subprogram body containing a call to the renamed subprogram. | |
9726 | ||
9727 | The Local_Restrictions aspect can be specified for a package specification, | |
9728 | in which case the aspect specification also applies to all eligible entities | |
9729 | declared with the package. This includes types. Default initialization of an | |
9730 | object of a given type is treated like a call to an implicitly-declared | |
9731 | initialization subprogram. Such a “call” is subject to the same local | |
9732 | restriction checks as any other call. If a type is subject to a local | |
9733 | restriction, then any violations of that restriction within the default | |
9734 | initialization expressions (if any) of the type are rejected. This may | |
9735 | include “calls” to the default initialization subprograms of other types. | |
9736 | ||
9737 | Local_Restrictions aspect specifications are additive (for example, in the | |
9738 | case of a declaration that occurs within nested packages that each have | |
9739 | a Local_Restrictions specification). | |
9740 | ||
9741 | @node Aspect Lock_Free,Aspect Max_Queue_Length,Aspect Local_Restrictions,Implementation Defined Aspects | |
9742 | @anchor{gnat_rm/implementation_defined_aspects aspect-lock-free}@anchor{141} | |
64d5610f ML |
9743 | @section Aspect Lock_Free |
9744 | ||
9745 | ||
9746 | @geindex Lock_Free | |
9747 | ||
b71d4b62 | 9748 | This boolean aspect is equivalent to @ref{97,,pragma Lock_Free}. |
64d5610f ML |
9749 | |
9750 | @node Aspect Max_Queue_Length,Aspect No_Caching,Aspect Lock_Free,Implementation Defined Aspects | |
9daee425 | 9751 | @anchor{gnat_rm/implementation_defined_aspects aspect-max-queue-length}@anchor{142} |
64d5610f ML |
9752 | @section Aspect Max_Queue_Length |
9753 | ||
9754 | ||
9755 | @geindex Max_Queue_Length | |
9756 | ||
b71d4b62 | 9757 | This aspect is equivalent to @ref{9f,,pragma Max_Queue_Length}. |
64d5610f ML |
9758 | |
9759 | @node Aspect No_Caching,Aspect No_Elaboration_Code_All,Aspect Max_Queue_Length,Implementation Defined Aspects | |
9daee425 | 9760 | @anchor{gnat_rm/implementation_defined_aspects aspect-no-caching}@anchor{143} |
64d5610f ML |
9761 | @section Aspect No_Caching |
9762 | ||
9763 | ||
9764 | @geindex No_Caching | |
9765 | ||
b71d4b62 | 9766 | This boolean aspect is equivalent to @ref{a2,,pragma No_Caching}. |
64d5610f ML |
9767 | |
9768 | @node Aspect No_Elaboration_Code_All,Aspect No_Inline,Aspect No_Caching,Implementation Defined Aspects | |
9daee425 | 9769 | @anchor{gnat_rm/implementation_defined_aspects aspect-no-elaboration-code-all}@anchor{144} |
64d5610f ML |
9770 | @section Aspect No_Elaboration_Code_All |
9771 | ||
9772 | ||
9773 | @geindex No_Elaboration_Code_All | |
9774 | ||
b71d4b62 | 9775 | This aspect is equivalent to @ref{a5,,pragma No_Elaboration_Code_All} |
64d5610f ML |
9776 | for a program unit. |
9777 | ||
9778 | @node Aspect No_Inline,Aspect No_Tagged_Streams,Aspect No_Elaboration_Code_All,Implementation Defined Aspects | |
9daee425 | 9779 | @anchor{gnat_rm/implementation_defined_aspects aspect-no-inline}@anchor{145} |
64d5610f ML |
9780 | @section Aspect No_Inline |
9781 | ||
9782 | ||
9783 | @geindex No_Inline | |
9784 | ||
b71d4b62 | 9785 | This boolean aspect is equivalent to @ref{a8,,pragma No_Inline}. |
64d5610f ML |
9786 | |
9787 | @node Aspect No_Tagged_Streams,Aspect No_Task_Parts,Aspect No_Inline,Implementation Defined Aspects | |
9daee425 | 9788 | @anchor{gnat_rm/implementation_defined_aspects aspect-no-tagged-streams}@anchor{146} |
64d5610f ML |
9789 | @section Aspect No_Tagged_Streams |
9790 | ||
9791 | ||
9792 | @geindex No_Tagged_Streams | |
9793 | ||
b71d4b62 | 9794 | This aspect is equivalent to @ref{ac,,pragma No_Tagged_Streams} with an |
64d5610f ML |
9795 | argument specifying a root tagged type (thus this aspect can only be |
9796 | applied to such a type). | |
9797 | ||
9798 | @node Aspect No_Task_Parts,Aspect Object_Size,Aspect No_Tagged_Streams,Implementation Defined Aspects | |
9daee425 | 9799 | @anchor{gnat_rm/implementation_defined_aspects aspect-no-task-parts}@anchor{147} |
64d5610f ML |
9800 | @section Aspect No_Task_Parts |
9801 | ||
9802 | ||
9803 | @geindex No_Task_Parts | |
9804 | ||
9805 | Applies to a type. If True, requires that the type and any descendants | |
9806 | do not have any task parts. The rules for this aspect are the same as | |
9807 | for the language-defined No_Controlled_Parts aspect (see RM-H.4.1), | |
9808 | replacing “controlled” with “task”. | |
9809 | ||
9810 | If No_Task_Parts is True for a type T, then the compiler can optimize | |
9811 | away certain tasking-related code that would otherwise be needed | |
9812 | for T’Class, because descendants of T might contain tasks. | |
9813 | ||
9814 | @node Aspect Object_Size,Aspect Obsolescent,Aspect No_Task_Parts,Implementation Defined Aspects | |
9daee425 | 9815 | @anchor{gnat_rm/implementation_defined_aspects aspect-object-size}@anchor{148} |
64d5610f ML |
9816 | @section Aspect Object_Size |
9817 | ||
9818 | ||
9819 | @geindex Object_Size | |
9820 | ||
9daee425 | 9821 | This aspect is equivalent to @ref{149,,attribute Object_Size}. |
64d5610f ML |
9822 | |
9823 | @node Aspect Obsolescent,Aspect Part_Of,Aspect Object_Size,Implementation Defined Aspects | |
9daee425 | 9824 | @anchor{gnat_rm/implementation_defined_aspects aspect-obsolescent}@anchor{14a} |
64d5610f ML |
9825 | @section Aspect Obsolescent |
9826 | ||
9827 | ||
9828 | @geindex Obsolescent | |
9829 | ||
b71d4b62 | 9830 | This aspect is equivalent to @ref{af,,pragma Obsolescent}. Note that the |
64d5610f ML |
9831 | evaluation of this aspect happens at the point of occurrence, it is not |
9832 | delayed until the freeze point. | |
9833 | ||
9834 | @node Aspect Part_Of,Aspect Persistent_BSS,Aspect Obsolescent,Implementation Defined Aspects | |
9daee425 | 9835 | @anchor{gnat_rm/implementation_defined_aspects aspect-part-of}@anchor{14b} |
64d5610f ML |
9836 | @section Aspect Part_Of |
9837 | ||
9838 | ||
9839 | @geindex Part_Of | |
9840 | ||
b71d4b62 | 9841 | This aspect is equivalent to @ref{b5,,pragma Part_Of}. |
64d5610f ML |
9842 | |
9843 | @node Aspect Persistent_BSS,Aspect Predicate,Aspect Part_Of,Implementation Defined Aspects | |
9daee425 | 9844 | @anchor{gnat_rm/implementation_defined_aspects aspect-persistent-bss}@anchor{14c} |
64d5610f ML |
9845 | @section Aspect Persistent_BSS |
9846 | ||
9847 | ||
9848 | @geindex Persistent_BSS | |
9849 | ||
b71d4b62 | 9850 | This boolean aspect is equivalent to @ref{b9,,pragma Persistent_BSS}. |
64d5610f ML |
9851 | |
9852 | @node Aspect Predicate,Aspect Pure_Function,Aspect Persistent_BSS,Implementation Defined Aspects | |
9daee425 | 9853 | @anchor{gnat_rm/implementation_defined_aspects aspect-predicate}@anchor{14d} |
64d5610f ML |
9854 | @section Aspect Predicate |
9855 | ||
9856 | ||
9857 | @geindex Predicate | |
9858 | ||
b71d4b62 | 9859 | This aspect is equivalent to @ref{c0,,pragma Predicate}. It is thus |
64d5610f ML |
9860 | similar to the language defined aspects @code{Dynamic_Predicate} |
9861 | and @code{Static_Predicate} except that whether the resulting | |
9862 | predicate is static or dynamic is controlled by the form of the | |
9863 | expression. It is also separately controllable using pragma | |
9864 | @code{Assertion_Policy}. | |
9865 | ||
9866 | @node Aspect Pure_Function,Aspect Refined_Depends,Aspect Predicate,Implementation Defined Aspects | |
9daee425 | 9867 | @anchor{gnat_rm/implementation_defined_aspects aspect-pure-function}@anchor{14e} |
64d5610f ML |
9868 | @section Aspect Pure_Function |
9869 | ||
9870 | ||
9871 | @geindex Pure_Function | |
9872 | ||
b71d4b62 | 9873 | This boolean aspect is equivalent to @ref{cc,,pragma Pure_Function}. |
64d5610f ML |
9874 | |
9875 | @node Aspect Refined_Depends,Aspect Refined_Global,Aspect Pure_Function,Implementation Defined Aspects | |
9daee425 | 9876 | @anchor{gnat_rm/implementation_defined_aspects aspect-refined-depends}@anchor{14f} |
64d5610f ML |
9877 | @section Aspect Refined_Depends |
9878 | ||
9879 | ||
9880 | @geindex Refined_Depends | |
9881 | ||
b71d4b62 | 9882 | This aspect is equivalent to @ref{d0,,pragma Refined_Depends}. |
64d5610f ML |
9883 | |
9884 | @node Aspect Refined_Global,Aspect Refined_Post,Aspect Refined_Depends,Implementation Defined Aspects | |
9daee425 | 9885 | @anchor{gnat_rm/implementation_defined_aspects aspect-refined-global}@anchor{150} |
64d5610f ML |
9886 | @section Aspect Refined_Global |
9887 | ||
9888 | ||
9889 | @geindex Refined_Global | |
9890 | ||
b71d4b62 | 9891 | This aspect is equivalent to @ref{d2,,pragma Refined_Global}. |
64d5610f ML |
9892 | |
9893 | @node Aspect Refined_Post,Aspect Refined_State,Aspect Refined_Global,Implementation Defined Aspects | |
9daee425 | 9894 | @anchor{gnat_rm/implementation_defined_aspects aspect-refined-post}@anchor{151} |
64d5610f ML |
9895 | @section Aspect Refined_Post |
9896 | ||
9897 | ||
9898 | @geindex Refined_Post | |
9899 | ||
b71d4b62 | 9900 | This aspect is equivalent to @ref{d4,,pragma Refined_Post}. |
64d5610f ML |
9901 | |
9902 | @node Aspect Refined_State,Aspect Relaxed_Initialization,Aspect Refined_Post,Implementation Defined Aspects | |
9daee425 | 9903 | @anchor{gnat_rm/implementation_defined_aspects aspect-refined-state}@anchor{152} |
64d5610f ML |
9904 | @section Aspect Refined_State |
9905 | ||
9906 | ||
9907 | @geindex Refined_State | |
9908 | ||
b71d4b62 | 9909 | This aspect is equivalent to @ref{d6,,pragma Refined_State}. |
64d5610f ML |
9910 | |
9911 | @node Aspect Relaxed_Initialization,Aspect Remote_Access_Type,Aspect Refined_State,Implementation Defined Aspects | |
9daee425 | 9912 | @anchor{gnat_rm/implementation_defined_aspects aspect-relaxed-initialization}@anchor{153} |
64d5610f ML |
9913 | @section Aspect Relaxed_Initialization |
9914 | ||
9915 | ||
9916 | @geindex Refined_Initialization | |
9917 | ||
9918 | For the syntax and semantics of this aspect, see the SPARK 2014 Reference | |
9919 | Manual, section 6.10. | |
9920 | ||
9921 | @node Aspect Remote_Access_Type,Aspect Secondary_Stack_Size,Aspect Relaxed_Initialization,Implementation Defined Aspects | |
9daee425 | 9922 | @anchor{gnat_rm/implementation_defined_aspects aspect-remote-access-type}@anchor{154} |
64d5610f ML |
9923 | @section Aspect Remote_Access_Type |
9924 | ||
9925 | ||
9926 | @geindex Remote_Access_Type | |
9927 | ||
b71d4b62 | 9928 | This aspect is equivalent to @ref{d9,,pragma Remote_Access_Type}. |
64d5610f ML |
9929 | |
9930 | @node Aspect Secondary_Stack_Size,Aspect Scalar_Storage_Order,Aspect Remote_Access_Type,Implementation Defined Aspects | |
9daee425 | 9931 | @anchor{gnat_rm/implementation_defined_aspects aspect-secondary-stack-size}@anchor{155} |
64d5610f ML |
9932 | @section Aspect Secondary_Stack_Size |
9933 | ||
9934 | ||
9935 | @geindex Secondary_Stack_Size | |
9936 | ||
b71d4b62 | 9937 | This aspect is equivalent to @ref{df,,pragma Secondary_Stack_Size}. |
64d5610f ML |
9938 | |
9939 | @node Aspect Scalar_Storage_Order,Aspect Shared,Aspect Secondary_Stack_Size,Implementation Defined Aspects | |
9daee425 | 9940 | @anchor{gnat_rm/implementation_defined_aspects aspect-scalar-storage-order}@anchor{156} |
64d5610f ML |
9941 | @section Aspect Scalar_Storage_Order |
9942 | ||
9943 | ||
9944 | @geindex Scalar_Storage_Order | |
9945 | ||
9daee425 | 9946 | This aspect is equivalent to a @ref{157,,attribute Scalar_Storage_Order}. |
64d5610f | 9947 | |
04d6c745 | 9948 | @node Aspect Shared,Aspect Side_Effects,Aspect Scalar_Storage_Order,Implementation Defined Aspects |
9daee425 | 9949 | @anchor{gnat_rm/implementation_defined_aspects aspect-shared}@anchor{158} |
64d5610f ML |
9950 | @section Aspect Shared |
9951 | ||
9952 | ||
9953 | @geindex Shared | |
9954 | ||
b71d4b62 | 9955 | This boolean aspect is equivalent to @ref{e2,,pragma Shared} |
64d5610f ML |
9956 | and is thus a synonym for aspect @code{Atomic}. |
9957 | ||
04d6c745 | 9958 | @node Aspect Side_Effects,Aspect Simple_Storage_Pool,Aspect Shared,Implementation Defined Aspects |
9daee425 | 9959 | @anchor{gnat_rm/implementation_defined_aspects aspect-side-effects}@anchor{159} |
04d6c745 YM |
9960 | @section Aspect Side_Effects |
9961 | ||
9962 | ||
9963 | @geindex Side_Effects | |
9964 | ||
9965 | This aspect is equivalent to @ref{e6,,pragma Side_Effects}. | |
9966 | ||
9967 | @node Aspect Simple_Storage_Pool,Aspect Simple_Storage_Pool_Type,Aspect Side_Effects,Implementation Defined Aspects | |
9daee425 | 9968 | @anchor{gnat_rm/implementation_defined_aspects aspect-simple-storage-pool}@anchor{15a} |
64d5610f ML |
9969 | @section Aspect Simple_Storage_Pool |
9970 | ||
9971 | ||
9972 | @geindex Simple_Storage_Pool | |
9973 | ||
04d6c745 | 9974 | This aspect is equivalent to @ref{e9,,attribute Simple_Storage_Pool}. |
64d5610f ML |
9975 | |
9976 | @node Aspect Simple_Storage_Pool_Type,Aspect SPARK_Mode,Aspect Simple_Storage_Pool,Implementation Defined Aspects | |
9daee425 | 9977 | @anchor{gnat_rm/implementation_defined_aspects aspect-simple-storage-pool-type}@anchor{15b} |
64d5610f ML |
9978 | @section Aspect Simple_Storage_Pool_Type |
9979 | ||
9980 | ||
9981 | @geindex Simple_Storage_Pool_Type | |
9982 | ||
04d6c745 | 9983 | This boolean aspect is equivalent to @ref{e8,,pragma Simple_Storage_Pool_Type}. |
64d5610f ML |
9984 | |
9985 | @node Aspect SPARK_Mode,Aspect Suppress_Debug_Info,Aspect Simple_Storage_Pool_Type,Implementation Defined Aspects | |
9daee425 | 9986 | @anchor{gnat_rm/implementation_defined_aspects aspect-spark-mode}@anchor{15c} |
64d5610f ML |
9987 | @section Aspect SPARK_Mode |
9988 | ||
9989 | ||
9990 | @geindex SPARK_Mode | |
9991 | ||
04d6c745 | 9992 | This aspect is equivalent to @ref{f0,,pragma SPARK_Mode} and |
64d5610f ML |
9993 | may be specified for either or both of the specification and body |
9994 | of a subprogram or package. | |
9995 | ||
9996 | @node Aspect Suppress_Debug_Info,Aspect Suppress_Initialization,Aspect SPARK_Mode,Implementation Defined Aspects | |
9daee425 | 9997 | @anchor{gnat_rm/implementation_defined_aspects aspect-suppress-debug-info}@anchor{15d} |
64d5610f ML |
9998 | @section Aspect Suppress_Debug_Info |
9999 | ||
10000 | ||
10001 | @geindex Suppress_Debug_Info | |
10002 | ||
04d6c745 | 10003 | This boolean aspect is equivalent to @ref{f8,,pragma Suppress_Debug_Info}. |
64d5610f ML |
10004 | |
10005 | @node Aspect Suppress_Initialization,Aspect Test_Case,Aspect Suppress_Debug_Info,Implementation Defined Aspects | |
9daee425 | 10006 | @anchor{gnat_rm/implementation_defined_aspects aspect-suppress-initialization}@anchor{15e} |
64d5610f ML |
10007 | @section Aspect Suppress_Initialization |
10008 | ||
10009 | ||
10010 | @geindex Suppress_Initialization | |
10011 | ||
04d6c745 | 10012 | This boolean aspect is equivalent to @ref{fb,,pragma Suppress_Initialization}. |
64d5610f ML |
10013 | |
10014 | @node Aspect Test_Case,Aspect Thread_Local_Storage,Aspect Suppress_Initialization,Implementation Defined Aspects | |
9daee425 | 10015 | @anchor{gnat_rm/implementation_defined_aspects aspect-test-case}@anchor{15f} |
64d5610f ML |
10016 | @section Aspect Test_Case |
10017 | ||
10018 | ||
10019 | @geindex Test_Case | |
10020 | ||
04d6c745 | 10021 | This aspect is equivalent to @ref{ff,,pragma Test_Case}. |
64d5610f ML |
10022 | |
10023 | @node Aspect Thread_Local_Storage,Aspect Universal_Aliasing,Aspect Test_Case,Implementation Defined Aspects | |
9daee425 | 10024 | @anchor{gnat_rm/implementation_defined_aspects aspect-thread-local-storage}@anchor{160} |
64d5610f ML |
10025 | @section Aspect Thread_Local_Storage |
10026 | ||
10027 | ||
10028 | @geindex Thread_Local_Storage | |
10029 | ||
04d6c745 | 10030 | This boolean aspect is equivalent to @ref{101,,pragma Thread_Local_Storage}. |
64d5610f ML |
10031 | |
10032 | @node Aspect Universal_Aliasing,Aspect Unmodified,Aspect Thread_Local_Storage,Implementation Defined Aspects | |
9daee425 | 10033 | @anchor{gnat_rm/implementation_defined_aspects aspect-universal-aliasing}@anchor{161} |
64d5610f ML |
10034 | @section Aspect Universal_Aliasing |
10035 | ||
10036 | ||
10037 | @geindex Universal_Aliasing | |
10038 | ||
9daee425 | 10039 | This boolean aspect is equivalent to @ref{10c,,pragma Universal_Aliasing}. |
64d5610f ML |
10040 | |
10041 | @node Aspect Unmodified,Aspect Unreferenced,Aspect Universal_Aliasing,Implementation Defined Aspects | |
9daee425 | 10042 | @anchor{gnat_rm/implementation_defined_aspects aspect-unmodified}@anchor{162} |
64d5610f ML |
10043 | @section Aspect Unmodified |
10044 | ||
10045 | ||
10046 | @geindex Unmodified | |
10047 | ||
9daee425 | 10048 | This boolean aspect is equivalent to @ref{10e,,pragma Unmodified}. |
64d5610f ML |
10049 | |
10050 | @node Aspect Unreferenced,Aspect Unreferenced_Objects,Aspect Unmodified,Implementation Defined Aspects | |
9daee425 | 10051 | @anchor{gnat_rm/implementation_defined_aspects aspect-unreferenced}@anchor{163} |
64d5610f ML |
10052 | @section Aspect Unreferenced |
10053 | ||
10054 | ||
10055 | @geindex Unreferenced | |
10056 | ||
9daee425 | 10057 | This boolean aspect is equivalent to @ref{110,,pragma Unreferenced}. |
64d5610f ML |
10058 | |
10059 | When using the @code{-gnat2022} switch, this aspect is also supported on formal | |
10060 | parameters, which is in particular the only form possible for expression | |
10061 | functions. | |
10062 | ||
9daee425 SB |
10063 | @node Aspect Unreferenced_Objects,Aspect User_Aspect,Aspect Unreferenced,Implementation Defined Aspects |
10064 | @anchor{gnat_rm/implementation_defined_aspects aspect-unreferenced-objects}@anchor{164} | |
64d5610f ML |
10065 | @section Aspect Unreferenced_Objects |
10066 | ||
10067 | ||
10068 | @geindex Unreferenced_Objects | |
10069 | ||
9daee425 SB |
10070 | This boolean aspect is equivalent to @ref{112,,pragma Unreferenced_Objects}. |
10071 | ||
10072 | @node Aspect User_Aspect,Aspect Value_Size,Aspect Unreferenced_Objects,Implementation Defined Aspects | |
10073 | @anchor{gnat_rm/implementation_defined_aspects aspect-user-aspect}@anchor{165} | |
10074 | @section Aspect User_Aspect | |
10075 | ||
10076 | ||
10077 | @geindex User_Aspect | |
10078 | ||
10079 | This aspect takes an argument that is the name of an aspect defined by a | |
10080 | User_Aspect_Definition configuration pragma. | |
10081 | A User_Aspect aspect specification is semantically equivalent to | |
10082 | replicating the set of aspect specifications associated with the named | |
10083 | pragma-defined aspect. | |
64d5610f | 10084 | |
9daee425 SB |
10085 | @node Aspect Value_Size,Aspect Volatile_Full_Access,Aspect User_Aspect,Implementation Defined Aspects |
10086 | @anchor{gnat_rm/implementation_defined_aspects aspect-value-size}@anchor{166} | |
64d5610f ML |
10087 | @section Aspect Value_Size |
10088 | ||
10089 | ||
10090 | @geindex Value_Size | |
10091 | ||
9daee425 | 10092 | This aspect is equivalent to @ref{167,,attribute Value_Size}. |
64d5610f ML |
10093 | |
10094 | @node Aspect Volatile_Full_Access,Aspect Volatile_Function,Aspect Value_Size,Implementation Defined Aspects | |
9daee425 | 10095 | @anchor{gnat_rm/implementation_defined_aspects aspect-volatile-full-access}@anchor{168} |
64d5610f ML |
10096 | @section Aspect Volatile_Full_Access |
10097 | ||
10098 | ||
10099 | @geindex Volatile_Full_Access | |
10100 | ||
9daee425 | 10101 | This boolean aspect is equivalent to @ref{11c,,pragma Volatile_Full_Access}. |
64d5610f ML |
10102 | |
10103 | @node Aspect Volatile_Function,Aspect Warnings,Aspect Volatile_Full_Access,Implementation Defined Aspects | |
9daee425 | 10104 | @anchor{gnat_rm/implementation_defined_aspects aspect-volatile-function}@anchor{169} |
64d5610f ML |
10105 | @section Aspect Volatile_Function |
10106 | ||
10107 | ||
10108 | @geindex Volatile_Function | |
10109 | ||
9daee425 | 10110 | This boolean aspect is equivalent to @ref{11e,,pragma Volatile_Function}. |
64d5610f ML |
10111 | |
10112 | @node Aspect Warnings,,Aspect Volatile_Function,Implementation Defined Aspects | |
9daee425 | 10113 | @anchor{gnat_rm/implementation_defined_aspects aspect-warnings}@anchor{16a} |
64d5610f ML |
10114 | @section Aspect Warnings |
10115 | ||
10116 | ||
10117 | @geindex Warnings | |
10118 | ||
9daee425 | 10119 | This aspect is equivalent to the two argument form of @ref{120,,pragma Warnings}, |
64d5610f ML |
10120 | where the first argument is @code{ON} or @code{OFF} and the second argument |
10121 | is the entity. | |
10122 | ||
10123 | @node Implementation Defined Attributes,Standard and Implementation Defined Restrictions,Implementation Defined Aspects,Top | |
9daee425 | 10124 | @anchor{gnat_rm/implementation_defined_attributes doc}@anchor{16b}@anchor{gnat_rm/implementation_defined_attributes id1}@anchor{16c}@anchor{gnat_rm/implementation_defined_attributes implementation-defined-attributes}@anchor{8} |
64d5610f ML |
10125 | @chapter Implementation Defined Attributes |
10126 | ||
10127 | ||
10128 | Ada defines (throughout the Ada reference manual, | |
10129 | summarized in Annex K), | |
10130 | a set of attributes that provide useful additional functionality in all | |
10131 | areas of the language. These language defined attributes are implemented | |
10132 | in GNAT and work as described in the Ada Reference Manual. | |
10133 | ||
10134 | In addition, Ada allows implementations to define additional | |
10135 | attributes whose meaning is defined by the implementation. GNAT provides | |
10136 | a number of these implementation-dependent attributes which can be used | |
10137 | to extend and enhance the functionality of the compiler. This section of | |
10138 | the GNAT reference manual describes these additional attributes. It also | |
10139 | describes additional implementation-dependent features of standard | |
10140 | language-defined attributes. | |
10141 | ||
10142 | Note that any program using these attributes may not be portable to | |
10143 | other compilers (although GNAT implements this set of attributes on all | |
10144 | platforms). Therefore if portability to other compilers is an important | |
10145 | consideration, you should minimize the use of these attributes. | |
10146 | ||
10147 | @menu | |
10148 | * Attribute Abort_Signal:: | |
10149 | * Attribute Address_Size:: | |
10150 | * Attribute Asm_Input:: | |
10151 | * Attribute Asm_Output:: | |
10152 | * Attribute Atomic_Always_Lock_Free:: | |
10153 | * Attribute Bit:: | |
10154 | * Attribute Bit_Position:: | |
10155 | * Attribute Code_Address:: | |
10156 | * Attribute Compiler_Version:: | |
10157 | * Attribute Constrained:: | |
10158 | * Attribute Default_Bit_Order:: | |
10159 | * Attribute Default_Scalar_Storage_Order:: | |
10160 | * Attribute Deref:: | |
10161 | * Attribute Descriptor_Size:: | |
10162 | * Attribute Elaborated:: | |
10163 | * Attribute Elab_Body:: | |
10164 | * Attribute Elab_Spec:: | |
10165 | * Attribute Elab_Subp_Body:: | |
10166 | * Attribute Emax:: | |
10167 | * Attribute Enabled:: | |
10168 | * Attribute Enum_Rep:: | |
10169 | * Attribute Enum_Val:: | |
10170 | * Attribute Epsilon:: | |
10171 | * Attribute Fast_Math:: | |
10172 | * Attribute Finalization_Size:: | |
10173 | * Attribute Fixed_Value:: | |
10174 | * Attribute From_Any:: | |
10175 | * Attribute Has_Access_Values:: | |
10176 | * Attribute Has_Discriminants:: | |
10177 | * Attribute Has_Tagged_Values:: | |
10178 | * Attribute Img:: | |
10179 | * Attribute Initialized:: | |
10180 | * Attribute Integer_Value:: | |
10181 | * Attribute Invalid_Value:: | |
10182 | * Attribute Iterable:: | |
10183 | * Attribute Large:: | |
10184 | * Attribute Library_Level:: | |
10185 | * Attribute Loop_Entry:: | |
10186 | * Attribute Machine_Size:: | |
10187 | * Attribute Mantissa:: | |
10188 | * Attribute Maximum_Alignment:: | |
10189 | * Attribute Max_Integer_Size:: | |
10190 | * Attribute Mechanism_Code:: | |
10191 | * Attribute Null_Parameter:: | |
10192 | * Attribute Object_Size:: | |
10193 | * Attribute Old:: | |
10194 | * Attribute Passed_By_Reference:: | |
10195 | * Attribute Pool_Address:: | |
10196 | * Attribute Range_Length:: | |
10197 | * Attribute Restriction_Set:: | |
10198 | * Attribute Result:: | |
10199 | * Attribute Safe_Emax:: | |
10200 | * Attribute Safe_Large:: | |
10201 | * Attribute Safe_Small:: | |
10202 | * Attribute Scalar_Storage_Order:: | |
10203 | * Attribute Simple_Storage_Pool:: | |
10204 | * Attribute Small:: | |
10205 | * Attribute Small_Denominator:: | |
10206 | * Attribute Small_Numerator:: | |
10207 | * Attribute Storage_Unit:: | |
10208 | * Attribute Stub_Type:: | |
10209 | * Attribute System_Allocator_Alignment:: | |
10210 | * Attribute Target_Name:: | |
10211 | * Attribute To_Address:: | |
10212 | * Attribute To_Any:: | |
10213 | * Attribute Type_Class:: | |
10214 | * Attribute Type_Key:: | |
10215 | * Attribute TypeCode:: | |
10216 | * Attribute Unconstrained_Array:: | |
10217 | * Attribute Universal_Literal_String:: | |
10218 | * Attribute Unrestricted_Access:: | |
10219 | * Attribute Update:: | |
10220 | * Attribute Valid_Value:: | |
10221 | * Attribute Valid_Scalars:: | |
10222 | * Attribute VADS_Size:: | |
10223 | * Attribute Value_Size:: | |
10224 | * Attribute Wchar_T_Size:: | |
10225 | * Attribute Word_Size:: | |
10226 | ||
10227 | @end menu | |
10228 | ||
10229 | @node Attribute Abort_Signal,Attribute Address_Size,,Implementation Defined Attributes | |
9daee425 | 10230 | @anchor{gnat_rm/implementation_defined_attributes attribute-abort-signal}@anchor{16d} |
64d5610f ML |
10231 | @section Attribute Abort_Signal |
10232 | ||
10233 | ||
10234 | @geindex Abort_Signal | |
10235 | ||
10236 | @code{Standard'Abort_Signal} (@code{Standard} is the only allowed | |
10237 | prefix) provides the entity for the special exception used to signal | |
10238 | task abort or asynchronous transfer of control. Normally this attribute | |
10239 | should only be used in the tasking runtime (it is highly peculiar, and | |
10240 | completely outside the normal semantics of Ada, for a user program to | |
10241 | intercept the abort exception). | |
10242 | ||
10243 | @node Attribute Address_Size,Attribute Asm_Input,Attribute Abort_Signal,Implementation Defined Attributes | |
9daee425 | 10244 | @anchor{gnat_rm/implementation_defined_attributes attribute-address-size}@anchor{16e} |
64d5610f ML |
10245 | @section Attribute Address_Size |
10246 | ||
10247 | ||
10248 | @geindex Size of `@w{`}Address`@w{`} | |
10249 | ||
10250 | @geindex Address_Size | |
10251 | ||
10252 | @code{Standard'Address_Size} (@code{Standard} is the only allowed | |
10253 | prefix) is a static constant giving the number of bits in an | |
10254 | @code{Address}. It is the same value as System.Address’Size, | |
10255 | but has the advantage of being static, while a direct | |
10256 | reference to System.Address’Size is nonstatic because Address | |
10257 | is a private type. | |
10258 | ||
10259 | @node Attribute Asm_Input,Attribute Asm_Output,Attribute Address_Size,Implementation Defined Attributes | |
9daee425 | 10260 | @anchor{gnat_rm/implementation_defined_attributes attribute-asm-input}@anchor{16f} |
64d5610f ML |
10261 | @section Attribute Asm_Input |
10262 | ||
10263 | ||
10264 | @geindex Asm_Input | |
10265 | ||
10266 | The @code{Asm_Input} attribute denotes a function that takes two | |
10267 | parameters. The first is a string, the second is an expression of the | |
10268 | type designated by the prefix. The first (string) argument is required | |
10269 | to be a static expression, and is the constraint for the parameter, | |
10270 | (e.g., what kind of register is required). The second argument is the | |
10271 | value to be used as the input argument. The possible values for the | |
10272 | constant are the same as those used in the RTL, and are dependent on | |
10273 | the configuration file used to built the GCC back end. | |
9daee425 | 10274 | @ref{170,,Machine Code Insertions} |
64d5610f ML |
10275 | |
10276 | @node Attribute Asm_Output,Attribute Atomic_Always_Lock_Free,Attribute Asm_Input,Implementation Defined Attributes | |
9daee425 | 10277 | @anchor{gnat_rm/implementation_defined_attributes attribute-asm-output}@anchor{171} |
64d5610f ML |
10278 | @section Attribute Asm_Output |
10279 | ||
10280 | ||
10281 | @geindex Asm_Output | |
10282 | ||
10283 | The @code{Asm_Output} attribute denotes a function that takes two | |
10284 | parameters. The first is a string, the second is the name of a variable | |
10285 | of the type designated by the attribute prefix. The first (string) | |
10286 | argument is required to be a static expression and designates the | |
10287 | constraint for the parameter (e.g., what kind of register is | |
10288 | required). The second argument is the variable to be updated with the | |
10289 | result. The possible values for constraint are the same as those used in | |
10290 | the RTL, and are dependent on the configuration file used to build the | |
10291 | GCC back end. If there are no output operands, then this argument may | |
10292 | either be omitted, or explicitly given as @code{No_Output_Operands}. | |
9daee425 | 10293 | @ref{170,,Machine Code Insertions} |
64d5610f ML |
10294 | |
10295 | @node Attribute Atomic_Always_Lock_Free,Attribute Bit,Attribute Asm_Output,Implementation Defined Attributes | |
9daee425 | 10296 | @anchor{gnat_rm/implementation_defined_attributes attribute-atomic-always-lock-free}@anchor{172} |
64d5610f ML |
10297 | @section Attribute Atomic_Always_Lock_Free |
10298 | ||
10299 | ||
10300 | @geindex Atomic_Always_Lock_Free | |
10301 | ||
10302 | The prefix of the @code{Atomic_Always_Lock_Free} attribute is a type. | |
10303 | The result is a Boolean value which is True if the type has discriminants, | |
10304 | and False otherwise. The result indicate whether atomic operations are | |
10305 | supported by the target for the given type. | |
10306 | ||
10307 | @node Attribute Bit,Attribute Bit_Position,Attribute Atomic_Always_Lock_Free,Implementation Defined Attributes | |
9daee425 | 10308 | @anchor{gnat_rm/implementation_defined_attributes attribute-bit}@anchor{173} |
64d5610f ML |
10309 | @section Attribute Bit |
10310 | ||
10311 | ||
10312 | @geindex Bit | |
10313 | ||
10314 | @code{obj'Bit}, where @code{obj} is any object, yields the bit | |
10315 | offset within the storage unit (byte) that contains the first bit of | |
10316 | storage allocated for the object. The value of this attribute is of the | |
1acce141 | 10317 | type @emph{universal_integer} and is always a nonnegative number smaller |
64d5610f ML |
10318 | than @code{System.Storage_Unit}. |
10319 | ||
10320 | For an object that is a variable or a constant allocated in a register, | |
10321 | the value is zero. (The use of this attribute does not force the | |
10322 | allocation of a variable to memory). | |
10323 | ||
10324 | For an object that is a formal parameter, this attribute applies | |
10325 | to either the matching actual parameter or to a copy of the | |
10326 | matching actual parameter. | |
10327 | ||
10328 | For an access object the value is zero. Note that | |
10329 | @code{obj.all'Bit} is subject to an @code{Access_Check} for the | |
10330 | designated object. Similarly for a record component | |
10331 | @code{X.C'Bit} is subject to a discriminant check and | |
10332 | @code{X(I).Bit} and @code{X(I1..I2)'Bit} | |
10333 | are subject to index checks. | |
10334 | ||
10335 | This attribute is designed to be compatible with the DEC Ada 83 definition | |
10336 | and implementation of the @code{Bit} attribute. | |
10337 | ||
10338 | @node Attribute Bit_Position,Attribute Code_Address,Attribute Bit,Implementation Defined Attributes | |
9daee425 | 10339 | @anchor{gnat_rm/implementation_defined_attributes attribute-bit-position}@anchor{174} |
64d5610f ML |
10340 | @section Attribute Bit_Position |
10341 | ||
10342 | ||
10343 | @geindex Bit_Position | |
10344 | ||
10345 | @code{R.C'Bit_Position}, where @code{R} is a record object and @code{C} is one | |
10346 | of the fields of the record type, yields the bit | |
10347 | offset within the record contains the first bit of | |
10348 | storage allocated for the object. The value of this attribute is of the | |
1acce141 | 10349 | type @emph{universal_integer}. The value depends only on the field |
64d5610f ML |
10350 | @code{C} and is independent of the alignment of |
10351 | the containing record @code{R}. | |
10352 | ||
10353 | @node Attribute Code_Address,Attribute Compiler_Version,Attribute Bit_Position,Implementation Defined Attributes | |
9daee425 | 10354 | @anchor{gnat_rm/implementation_defined_attributes attribute-code-address}@anchor{175} |
64d5610f ML |
10355 | @section Attribute Code_Address |
10356 | ||
10357 | ||
10358 | @geindex Code_Address | |
10359 | ||
10360 | @geindex Subprogram address | |
10361 | ||
10362 | @geindex Address of subprogram code | |
10363 | ||
10364 | The @code{'Address} | |
10365 | attribute may be applied to subprograms in Ada 95 and Ada 2005, but the | |
10366 | intended effect seems to be to provide | |
10367 | an address value which can be used to call the subprogram by means of | |
10368 | an address clause as in the following example: | |
10369 | ||
10370 | @example | |
10371 | procedure K is ... | |
10372 | ||
10373 | procedure L; | |
10374 | for L'Address use K'Address; | |
10375 | pragma Import (Ada, L); | |
10376 | @end example | |
10377 | ||
10378 | A call to @code{L} is then expected to result in a call to @code{K}. | |
10379 | In Ada 83, where there were no access-to-subprogram values, this was | |
10380 | a common work-around for getting the effect of an indirect call. | |
10381 | GNAT implements the above use of @code{Address} and the technique | |
10382 | illustrated by the example code works correctly. | |
10383 | ||
10384 | However, for some purposes, it is useful to have the address of the start | |
10385 | of the generated code for the subprogram. On some architectures, this is | |
10386 | not necessarily the same as the @code{Address} value described above. | |
10387 | For example, the @code{Address} value may reference a subprogram | |
10388 | descriptor rather than the subprogram itself. | |
10389 | ||
10390 | The @code{'Code_Address} attribute, which can only be applied to | |
10391 | subprogram entities, always returns the address of the start of the | |
10392 | generated code of the specified subprogram, which may or may not be | |
10393 | the same value as is returned by the corresponding @code{'Address} | |
10394 | attribute. | |
10395 | ||
10396 | @node Attribute Compiler_Version,Attribute Constrained,Attribute Code_Address,Implementation Defined Attributes | |
9daee425 | 10397 | @anchor{gnat_rm/implementation_defined_attributes attribute-compiler-version}@anchor{176} |
64d5610f ML |
10398 | @section Attribute Compiler_Version |
10399 | ||
10400 | ||
10401 | @geindex Compiler_Version | |
10402 | ||
10403 | @code{Standard'Compiler_Version} (@code{Standard} is the only allowed | |
10404 | prefix) yields a static string identifying the version of the compiler | |
10405 | being used to compile the unit containing the attribute reference. | |
10406 | ||
10407 | @node Attribute Constrained,Attribute Default_Bit_Order,Attribute Compiler_Version,Implementation Defined Attributes | |
9daee425 | 10408 | @anchor{gnat_rm/implementation_defined_attributes attribute-constrained}@anchor{177} |
64d5610f ML |
10409 | @section Attribute Constrained |
10410 | ||
10411 | ||
10412 | @geindex Constrained | |
10413 | ||
10414 | In addition to the usage of this attribute in the Ada RM, GNAT | |
10415 | also permits the use of the @code{'Constrained} attribute | |
10416 | in a generic template | |
10417 | for any type, including types without discriminants. The value of this | |
10418 | attribute in the generic instance when applied to a scalar type or a | |
10419 | record type without discriminants is always @code{True}. This usage is | |
10420 | compatible with older Ada compilers, including notably DEC Ada. | |
10421 | ||
10422 | @node Attribute Default_Bit_Order,Attribute Default_Scalar_Storage_Order,Attribute Constrained,Implementation Defined Attributes | |
9daee425 | 10423 | @anchor{gnat_rm/implementation_defined_attributes attribute-default-bit-order}@anchor{178} |
64d5610f ML |
10424 | @section Attribute Default_Bit_Order |
10425 | ||
10426 | ||
10427 | @geindex Big endian | |
10428 | ||
10429 | @geindex Little endian | |
10430 | ||
10431 | @geindex Default_Bit_Order | |
10432 | ||
10433 | @code{Standard'Default_Bit_Order} (@code{Standard} is the only | |
10434 | allowed prefix), provides the value @code{System.Default_Bit_Order} | |
10435 | as a @code{Pos} value (0 for @code{High_Order_First}, 1 for | |
10436 | @code{Low_Order_First}). This is used to construct the definition of | |
10437 | @code{Default_Bit_Order} in package @code{System}. | |
10438 | ||
10439 | @node Attribute Default_Scalar_Storage_Order,Attribute Deref,Attribute Default_Bit_Order,Implementation Defined Attributes | |
9daee425 | 10440 | @anchor{gnat_rm/implementation_defined_attributes attribute-default-scalar-storage-order}@anchor{179} |
64d5610f ML |
10441 | @section Attribute Default_Scalar_Storage_Order |
10442 | ||
10443 | ||
10444 | @geindex Big endian | |
10445 | ||
10446 | @geindex Little endian | |
10447 | ||
10448 | @geindex Default_Scalar_Storage_Order | |
10449 | ||
10450 | @code{Standard'Default_Scalar_Storage_Order} (@code{Standard} is the only | |
10451 | allowed prefix), provides the current value of the default scalar storage | |
10452 | order (as specified using pragma @code{Default_Scalar_Storage_Order}, or | |
10453 | equal to @code{Default_Bit_Order} if unspecified) as a | |
10454 | @code{System.Bit_Order} value. This is a static attribute. | |
10455 | ||
10456 | @node Attribute Deref,Attribute Descriptor_Size,Attribute Default_Scalar_Storage_Order,Implementation Defined Attributes | |
9daee425 | 10457 | @anchor{gnat_rm/implementation_defined_attributes attribute-deref}@anchor{17a} |
64d5610f ML |
10458 | @section Attribute Deref |
10459 | ||
10460 | ||
10461 | @geindex Deref | |
10462 | ||
10463 | The attribute @code{typ'Deref(expr)} where @code{expr} is of type @code{System.Address} yields | |
10464 | the variable of type @code{typ} that is located at the given address. It is similar | |
10465 | to @code{(totyp (expr).all)}, where @code{totyp} is an unchecked conversion from address to | |
10466 | a named access-to-@cite{typ} type, except that it yields a variable, so it can be | |
10467 | used on the left side of an assignment. | |
10468 | ||
10469 | @node Attribute Descriptor_Size,Attribute Elaborated,Attribute Deref,Implementation Defined Attributes | |
9daee425 | 10470 | @anchor{gnat_rm/implementation_defined_attributes attribute-descriptor-size}@anchor{17b} |
64d5610f ML |
10471 | @section Attribute Descriptor_Size |
10472 | ||
10473 | ||
10474 | @geindex Descriptor | |
10475 | ||
10476 | @geindex Dope vector | |
10477 | ||
10478 | @geindex Descriptor_Size | |
10479 | ||
10480 | Nonstatic attribute @code{Descriptor_Size} returns the size in bits of the | |
10481 | descriptor allocated for a type. The result is non-zero only for unconstrained | |
10482 | array types and the returned value is of type universal integer. In GNAT, an | |
10483 | array descriptor contains bounds information and is located immediately before | |
10484 | the first element of the array. | |
10485 | ||
10486 | @example | |
10487 | type Unconstr_Array is array (Short_Short_Integer range <>) of Positive; | |
10488 | Put_Line ("Descriptor size = " & Unconstr_Array'Descriptor_Size'Img); | |
10489 | @end example | |
10490 | ||
10491 | The attribute takes into account any padding due to the alignment of the | |
10492 | component type. In the example above, the descriptor contains two values | |
10493 | of type @code{Short_Short_Integer} representing the low and high bound. But, | |
10494 | since @code{Positive} has an alignment of 4, the size of the descriptor is | |
10495 | @code{2 * Short_Short_Integer'Size} rounded up to the next multiple of 32, | |
10496 | which yields a size of 32 bits, i.e. including 16 bits of padding. | |
10497 | ||
10498 | @node Attribute Elaborated,Attribute Elab_Body,Attribute Descriptor_Size,Implementation Defined Attributes | |
9daee425 | 10499 | @anchor{gnat_rm/implementation_defined_attributes attribute-elaborated}@anchor{17c} |
64d5610f ML |
10500 | @section Attribute Elaborated |
10501 | ||
10502 | ||
10503 | @geindex Elaborated | |
10504 | ||
10505 | The prefix of the @code{'Elaborated} attribute must be a unit name. The | |
10506 | value is a Boolean which indicates whether or not the given unit has been | |
10507 | elaborated. This attribute is primarily intended for internal use by the | |
10508 | generated code for dynamic elaboration checking, but it can also be used | |
10509 | in user programs. The value will always be True once elaboration of all | |
10510 | units has been completed. An exception is for units which need no | |
10511 | elaboration, the value is always False for such units. | |
10512 | ||
10513 | @node Attribute Elab_Body,Attribute Elab_Spec,Attribute Elaborated,Implementation Defined Attributes | |
9daee425 | 10514 | @anchor{gnat_rm/implementation_defined_attributes attribute-elab-body}@anchor{17d} |
64d5610f ML |
10515 | @section Attribute Elab_Body |
10516 | ||
10517 | ||
10518 | @geindex Elab_Body | |
10519 | ||
10520 | This attribute can only be applied to a program unit name. It returns | |
10521 | the entity for the corresponding elaboration procedure for elaborating | |
10522 | the body of the referenced unit. This is used in the main generated | |
10523 | elaboration procedure by the binder and is not normally used in any | |
10524 | other context. However, there may be specialized situations in which it | |
10525 | is useful to be able to call this elaboration procedure from Ada code, | |
10526 | e.g., if it is necessary to do selective re-elaboration to fix some | |
10527 | error. | |
10528 | ||
10529 | @node Attribute Elab_Spec,Attribute Elab_Subp_Body,Attribute Elab_Body,Implementation Defined Attributes | |
9daee425 | 10530 | @anchor{gnat_rm/implementation_defined_attributes attribute-elab-spec}@anchor{17e} |
64d5610f ML |
10531 | @section Attribute Elab_Spec |
10532 | ||
10533 | ||
10534 | @geindex Elab_Spec | |
10535 | ||
10536 | This attribute can only be applied to a program unit name. It returns | |
10537 | the entity for the corresponding elaboration procedure for elaborating | |
10538 | the spec of the referenced unit. This is used in the main | |
10539 | generated elaboration procedure by the binder and is not normally used | |
10540 | in any other context. However, there may be specialized situations in | |
10541 | which it is useful to be able to call this elaboration procedure from | |
10542 | Ada code, e.g., if it is necessary to do selective re-elaboration to fix | |
10543 | some error. | |
10544 | ||
10545 | @node Attribute Elab_Subp_Body,Attribute Emax,Attribute Elab_Spec,Implementation Defined Attributes | |
9daee425 | 10546 | @anchor{gnat_rm/implementation_defined_attributes attribute-elab-subp-body}@anchor{17f} |
64d5610f ML |
10547 | @section Attribute Elab_Subp_Body |
10548 | ||
10549 | ||
10550 | @geindex Elab_Subp_Body | |
10551 | ||
10552 | This attribute can only be applied to a library level subprogram | |
10553 | name and is only allowed in CodePeer mode. It returns the entity | |
10554 | for the corresponding elaboration procedure for elaborating the body | |
10555 | of the referenced subprogram unit. This is used in the main generated | |
10556 | elaboration procedure by the binder in CodePeer mode only and is unrecognized | |
10557 | otherwise. | |
10558 | ||
10559 | @node Attribute Emax,Attribute Enabled,Attribute Elab_Subp_Body,Implementation Defined Attributes | |
9daee425 | 10560 | @anchor{gnat_rm/implementation_defined_attributes attribute-emax}@anchor{180} |
64d5610f ML |
10561 | @section Attribute Emax |
10562 | ||
10563 | ||
10564 | @geindex Ada 83 attributes | |
10565 | ||
10566 | @geindex Emax | |
10567 | ||
10568 | The @code{Emax} attribute is provided for compatibility with Ada 83. See | |
10569 | the Ada 83 reference manual for an exact description of the semantics of | |
10570 | this attribute. | |
10571 | ||
10572 | @node Attribute Enabled,Attribute Enum_Rep,Attribute Emax,Implementation Defined Attributes | |
9daee425 | 10573 | @anchor{gnat_rm/implementation_defined_attributes attribute-enabled}@anchor{181} |
64d5610f ML |
10574 | @section Attribute Enabled |
10575 | ||
10576 | ||
10577 | @geindex Enabled | |
10578 | ||
10579 | The @code{Enabled} attribute allows an application program to check at compile | |
10580 | time to see if the designated check is currently enabled. The prefix is a | |
10581 | simple identifier, referencing any predefined check name (other than | |
10582 | @code{All_Checks}) or a check name introduced by pragma Check_Name. If | |
10583 | no argument is given for the attribute, the check is for the general state | |
10584 | of the check, if an argument is given, then it is an entity name, and the | |
10585 | check indicates whether an @code{Suppress} or @code{Unsuppress} has been | |
10586 | given naming the entity (if not, then the argument is ignored). | |
10587 | ||
10588 | Note that instantiations inherit the check status at the point of the | |
10589 | instantiation, so a useful idiom is to have a library package that | |
10590 | introduces a check name with @code{pragma Check_Name}, and then contains | |
10591 | generic packages or subprograms which use the @code{Enabled} attribute | |
10592 | to see if the check is enabled. A user of this package can then issue | |
10593 | a @code{pragma Suppress} or @code{pragma Unsuppress} before instantiating | |
10594 | the package or subprogram, controlling whether the check will be present. | |
10595 | ||
10596 | @node Attribute Enum_Rep,Attribute Enum_Val,Attribute Enabled,Implementation Defined Attributes | |
9daee425 | 10597 | @anchor{gnat_rm/implementation_defined_attributes attribute-enum-rep}@anchor{182} |
64d5610f ML |
10598 | @section Attribute Enum_Rep |
10599 | ||
10600 | ||
10601 | @geindex Representation of enums | |
10602 | ||
10603 | @geindex Enum_Rep | |
10604 | ||
10605 | Note that this attribute is now standard in Ada 202x and is available | |
10606 | as an implementation defined attribute for earlier Ada versions. | |
10607 | ||
10608 | For every enumeration subtype @code{S}, @code{S'Enum_Rep} denotes a | |
10609 | function with the following spec: | |
10610 | ||
10611 | @example | |
10612 | function S'Enum_Rep (Arg : S'Base) return <Universal_Integer>; | |
10613 | @end example | |
10614 | ||
10615 | It is also allowable to apply @code{Enum_Rep} directly to an object of an | |
10616 | enumeration type or to a non-overloaded enumeration | |
10617 | literal. In this case @code{S'Enum_Rep} is equivalent to | |
10618 | @code{typ'Enum_Rep(S)} where @code{typ} is the type of the | |
10619 | enumeration literal or object. | |
10620 | ||
10621 | The function returns the representation value for the given enumeration | |
10622 | value. This will be equal to value of the @code{Pos} attribute in the | |
10623 | absence of an enumeration representation clause. This is a static | |
10624 | attribute (i.e., the result is static if the argument is static). | |
10625 | ||
10626 | @code{S'Enum_Rep} can also be used with integer types and objects, | |
10627 | in which case it simply returns the integer value. The reason for this | |
10628 | is to allow it to be used for @code{(<>)} discrete formal arguments in | |
10629 | a generic unit that can be instantiated with either enumeration types | |
10630 | or integer types. Note that if @code{Enum_Rep} is used on a modular | |
10631 | type whose upper bound exceeds the upper bound of the largest signed | |
10632 | integer type, and the argument is a variable, so that the universal | |
10633 | integer calculation is done at run time, then the call to @code{Enum_Rep} | |
10634 | may raise @code{Constraint_Error}. | |
10635 | ||
10636 | @node Attribute Enum_Val,Attribute Epsilon,Attribute Enum_Rep,Implementation Defined Attributes | |
9daee425 | 10637 | @anchor{gnat_rm/implementation_defined_attributes attribute-enum-val}@anchor{183} |
64d5610f ML |
10638 | @section Attribute Enum_Val |
10639 | ||
10640 | ||
10641 | @geindex Representation of enums | |
10642 | ||
10643 | @geindex Enum_Val | |
10644 | ||
10645 | Note that this attribute is now standard in Ada 202x and is available | |
10646 | as an implementation defined attribute for earlier Ada versions. | |
10647 | ||
10648 | For every enumeration subtype @code{S}, @code{S'Enum_Val} denotes a | |
10649 | function with the following spec: | |
10650 | ||
10651 | @example | |
10652 | function S'Enum_Val (Arg : <Universal_Integer>) return S'Base; | |
10653 | @end example | |
10654 | ||
10655 | The function returns the enumeration value whose representation matches the | |
10656 | argument, or raises Constraint_Error if no enumeration literal of the type | |
10657 | has the matching value. | |
10658 | This will be equal to value of the @code{Val} attribute in the | |
10659 | absence of an enumeration representation clause. This is a static | |
10660 | attribute (i.e., the result is static if the argument is static). | |
10661 | ||
10662 | @node Attribute Epsilon,Attribute Fast_Math,Attribute Enum_Val,Implementation Defined Attributes | |
9daee425 | 10663 | @anchor{gnat_rm/implementation_defined_attributes attribute-epsilon}@anchor{184} |
64d5610f ML |
10664 | @section Attribute Epsilon |
10665 | ||
10666 | ||
10667 | @geindex Ada 83 attributes | |
10668 | ||
10669 | @geindex Epsilon | |
10670 | ||
10671 | The @code{Epsilon} attribute is provided for compatibility with Ada 83. See | |
10672 | the Ada 83 reference manual for an exact description of the semantics of | |
10673 | this attribute. | |
10674 | ||
10675 | @node Attribute Fast_Math,Attribute Finalization_Size,Attribute Epsilon,Implementation Defined Attributes | |
9daee425 | 10676 | @anchor{gnat_rm/implementation_defined_attributes attribute-fast-math}@anchor{185} |
64d5610f ML |
10677 | @section Attribute Fast_Math |
10678 | ||
10679 | ||
10680 | @geindex Fast_Math | |
10681 | ||
10682 | @code{Standard'Fast_Math} (@code{Standard} is the only allowed | |
10683 | prefix) yields a static Boolean value that is True if pragma | |
10684 | @code{Fast_Math} is active, and False otherwise. | |
10685 | ||
10686 | @node Attribute Finalization_Size,Attribute Fixed_Value,Attribute Fast_Math,Implementation Defined Attributes | |
9daee425 | 10687 | @anchor{gnat_rm/implementation_defined_attributes attribute-finalization-size}@anchor{186} |
64d5610f ML |
10688 | @section Attribute Finalization_Size |
10689 | ||
10690 | ||
10691 | @geindex Finalization_Size | |
10692 | ||
10693 | The prefix of attribute @code{Finalization_Size} must be an object or | |
10694 | a non-class-wide type. This attribute returns the size of any hidden data | |
10695 | reserved by the compiler to handle finalization-related actions. The type of | |
1acce141 | 10696 | the attribute is @emph{universal_integer}. |
64d5610f ML |
10697 | |
10698 | @code{Finalization_Size} yields a value of zero for a type with no controlled | |
10699 | parts, an object whose type has no controlled parts, or an object of a | |
10700 | class-wide type whose tag denotes a type with no controlled parts. | |
10701 | ||
10702 | Note that only heap-allocated objects contain finalization data. | |
10703 | ||
10704 | @node Attribute Fixed_Value,Attribute From_Any,Attribute Finalization_Size,Implementation Defined Attributes | |
9daee425 | 10705 | @anchor{gnat_rm/implementation_defined_attributes attribute-fixed-value}@anchor{187} |
64d5610f ML |
10706 | @section Attribute Fixed_Value |
10707 | ||
10708 | ||
10709 | @geindex Fixed_Value | |
10710 | ||
10711 | For every fixed-point type @code{S}, @code{S'Fixed_Value} denotes a | |
10712 | function with the following specification: | |
10713 | ||
10714 | @example | |
10715 | function S'Fixed_Value (Arg : <Universal_Integer>) return S; | |
10716 | @end example | |
10717 | ||
10718 | The value returned is the fixed-point value @code{V} such that: | |
10719 | ||
10720 | @example | |
10721 | V = Arg * S'Small | |
10722 | @end example | |
10723 | ||
10724 | The effect is thus similar to first converting the argument to the | |
10725 | integer type used to represent @code{S}, and then doing an unchecked | |
10726 | conversion to the fixed-point type. The difference is | |
10727 | that there are full range checks, to ensure that the result is in range. | |
10728 | This attribute is primarily intended for use in implementation of the | |
10729 | input-output functions for fixed-point values. | |
10730 | ||
10731 | @node Attribute From_Any,Attribute Has_Access_Values,Attribute Fixed_Value,Implementation Defined Attributes | |
9daee425 | 10732 | @anchor{gnat_rm/implementation_defined_attributes attribute-from-any}@anchor{188} |
64d5610f ML |
10733 | @section Attribute From_Any |
10734 | ||
10735 | ||
10736 | @geindex From_Any | |
10737 | ||
10738 | This internal attribute is used for the generation of remote subprogram | |
10739 | stubs in the context of the Distributed Systems Annex. | |
10740 | ||
10741 | @node Attribute Has_Access_Values,Attribute Has_Discriminants,Attribute From_Any,Implementation Defined Attributes | |
9daee425 | 10742 | @anchor{gnat_rm/implementation_defined_attributes attribute-has-access-values}@anchor{189} |
64d5610f ML |
10743 | @section Attribute Has_Access_Values |
10744 | ||
10745 | ||
10746 | @geindex Access values | |
10747 | @geindex testing for | |
10748 | ||
10749 | @geindex Has_Access_Values | |
10750 | ||
10751 | The prefix of the @code{Has_Access_Values} attribute is a type. The result | |
10752 | is a Boolean value which is True if the is an access type, or is a composite | |
10753 | type with a component (at any nesting depth) that is an access type, and is | |
10754 | False otherwise. | |
10755 | The intended use of this attribute is in conjunction with generic | |
10756 | definitions. If the attribute is applied to a generic private type, it | |
10757 | indicates whether or not the corresponding actual type has access values. | |
10758 | ||
10759 | @node Attribute Has_Discriminants,Attribute Has_Tagged_Values,Attribute Has_Access_Values,Implementation Defined Attributes | |
9daee425 | 10760 | @anchor{gnat_rm/implementation_defined_attributes attribute-has-discriminants}@anchor{18a} |
64d5610f ML |
10761 | @section Attribute Has_Discriminants |
10762 | ||
10763 | ||
10764 | @geindex Discriminants | |
10765 | @geindex testing for | |
10766 | ||
10767 | @geindex Has_Discriminants | |
10768 | ||
10769 | The prefix of the @code{Has_Discriminants} attribute is a type. The result | |
10770 | is a Boolean value which is True if the type has discriminants, and False | |
10771 | otherwise. The intended use of this attribute is in conjunction with generic | |
10772 | definitions. If the attribute is applied to a generic private type, it | |
10773 | indicates whether or not the corresponding actual type has discriminants. | |
10774 | ||
10775 | @node Attribute Has_Tagged_Values,Attribute Img,Attribute Has_Discriminants,Implementation Defined Attributes | |
9daee425 | 10776 | @anchor{gnat_rm/implementation_defined_attributes attribute-has-tagged-values}@anchor{18b} |
64d5610f ML |
10777 | @section Attribute Has_Tagged_Values |
10778 | ||
10779 | ||
10780 | @geindex Tagged values | |
10781 | @geindex testing for | |
10782 | ||
10783 | @geindex Has_Tagged_Values | |
10784 | ||
10785 | The prefix of the @code{Has_Tagged_Values} attribute is a type. The result is a | |
10786 | Boolean value which is True if the type is a composite type (array or record) | |
10787 | that is either a tagged type or has a subcomponent that is tagged, and is False | |
10788 | otherwise. The intended use of this attribute is in conjunction with generic | |
10789 | definitions. If the attribute is applied to a generic private type, it | |
10790 | indicates whether or not the corresponding actual type has access values. | |
10791 | ||
10792 | @node Attribute Img,Attribute Initialized,Attribute Has_Tagged_Values,Implementation Defined Attributes | |
9daee425 | 10793 | @anchor{gnat_rm/implementation_defined_attributes attribute-img}@anchor{18c} |
64d5610f ML |
10794 | @section Attribute Img |
10795 | ||
10796 | ||
10797 | @geindex Img | |
10798 | ||
10799 | The @code{Img} attribute differs from @code{Image} in that, while both can be | |
10800 | applied directly to an object, @code{Img} cannot be applied to types. | |
10801 | ||
10802 | Example usage of the attribute: | |
10803 | ||
10804 | @example | |
10805 | Put_Line ("X = " & X'Img); | |
10806 | @end example | |
10807 | ||
10808 | which has the same meaning as the more verbose: | |
10809 | ||
10810 | @example | |
10811 | Put_Line ("X = " & T'Image (X)); | |
10812 | @end example | |
10813 | ||
10814 | where @code{T} is the (sub)type of the object @code{X}. | |
10815 | ||
10816 | Note that technically, in analogy to @code{Image}, | |
10817 | @code{X'Img} returns a parameterless function | |
10818 | that returns the appropriate string when called. This means that | |
10819 | @code{X'Img} can be renamed as a function-returning-string, or used | |
10820 | in an instantiation as a function parameter. | |
10821 | ||
10822 | @node Attribute Initialized,Attribute Integer_Value,Attribute Img,Implementation Defined Attributes | |
9daee425 | 10823 | @anchor{gnat_rm/implementation_defined_attributes attribute-initialized}@anchor{18d} |
64d5610f ML |
10824 | @section Attribute Initialized |
10825 | ||
10826 | ||
10827 | @geindex Initialized | |
10828 | ||
10829 | For the syntax and semantics of this attribute, see the SPARK 2014 Reference | |
10830 | Manual, section 6.10. | |
10831 | ||
10832 | @node Attribute Integer_Value,Attribute Invalid_Value,Attribute Initialized,Implementation Defined Attributes | |
9daee425 | 10833 | @anchor{gnat_rm/implementation_defined_attributes attribute-integer-value}@anchor{18e} |
64d5610f ML |
10834 | @section Attribute Integer_Value |
10835 | ||
10836 | ||
10837 | @geindex Integer_Value | |
10838 | ||
10839 | For every integer type @code{S}, @code{S'Integer_Value} denotes a | |
10840 | function with the following spec: | |
10841 | ||
10842 | @example | |
10843 | function S'Integer_Value (Arg : <Universal_Fixed>) return S; | |
10844 | @end example | |
10845 | ||
10846 | The value returned is the integer value @code{V}, such that: | |
10847 | ||
10848 | @example | |
10849 | Arg = V * T'Small | |
10850 | @end example | |
10851 | ||
10852 | where @code{T} is the type of @code{Arg}. | |
10853 | The effect is thus similar to first doing an unchecked conversion from | |
10854 | the fixed-point type to its corresponding implementation type, and then | |
10855 | converting the result to the target integer type. The difference is | |
10856 | that there are full range checks, to ensure that the result is in range. | |
10857 | This attribute is primarily intended for use in implementation of the | |
10858 | standard input-output functions for fixed-point values. | |
10859 | ||
10860 | @node Attribute Invalid_Value,Attribute Iterable,Attribute Integer_Value,Implementation Defined Attributes | |
9daee425 | 10861 | @anchor{gnat_rm/implementation_defined_attributes attribute-invalid-value}@anchor{18f} |
64d5610f ML |
10862 | @section Attribute Invalid_Value |
10863 | ||
10864 | ||
10865 | @geindex Invalid_Value | |
10866 | ||
10867 | For every scalar type S, S’Invalid_Value returns an undefined value of the | |
10868 | type. If possible this value is an invalid representation for the type. The | |
10869 | value returned is identical to the value used to initialize an otherwise | |
10870 | uninitialized value of the type if pragma Initialize_Scalars is used, | |
10871 | including the ability to modify the value with the binder -Sxx flag and | |
10872 | relevant environment variables at run time. | |
10873 | ||
10874 | @node Attribute Iterable,Attribute Large,Attribute Invalid_Value,Implementation Defined Attributes | |
9daee425 | 10875 | @anchor{gnat_rm/implementation_defined_attributes attribute-iterable}@anchor{190} |
64d5610f ML |
10876 | @section Attribute Iterable |
10877 | ||
10878 | ||
10879 | @geindex Iterable | |
10880 | ||
10881 | Equivalent to Aspect Iterable. | |
10882 | ||
10883 | @node Attribute Large,Attribute Library_Level,Attribute Iterable,Implementation Defined Attributes | |
9daee425 | 10884 | @anchor{gnat_rm/implementation_defined_attributes attribute-large}@anchor{191} |
64d5610f ML |
10885 | @section Attribute Large |
10886 | ||
10887 | ||
10888 | @geindex Ada 83 attributes | |
10889 | ||
10890 | @geindex Large | |
10891 | ||
10892 | The @code{Large} attribute is provided for compatibility with Ada 83. See | |
10893 | the Ada 83 reference manual for an exact description of the semantics of | |
10894 | this attribute. | |
10895 | ||
10896 | @node Attribute Library_Level,Attribute Loop_Entry,Attribute Large,Implementation Defined Attributes | |
9daee425 | 10897 | @anchor{gnat_rm/implementation_defined_attributes attribute-library-level}@anchor{192} |
64d5610f ML |
10898 | @section Attribute Library_Level |
10899 | ||
10900 | ||
10901 | @geindex Library_Level | |
10902 | ||
10903 | @code{P'Library_Level}, where P is an entity name, | |
10904 | returns a Boolean value which is True if the entity is declared | |
10905 | at the library level, and False otherwise. Note that within a | |
10906 | generic instantiation, the name of the generic unit denotes the | |
10907 | instance, which means that this attribute can be used to test | |
10908 | if a generic is instantiated at the library level, as shown | |
10909 | in this example: | |
10910 | ||
10911 | @example | |
10912 | generic | |
10913 | ... | |
10914 | package Gen is | |
10915 | pragma Compile_Time_Error | |
10916 | (not Gen'Library_Level, | |
10917 | "Gen can only be instantiated at library level"); | |
10918 | ... | |
10919 | end Gen; | |
10920 | @end example | |
10921 | ||
10922 | @node Attribute Loop_Entry,Attribute Machine_Size,Attribute Library_Level,Implementation Defined Attributes | |
9daee425 | 10923 | @anchor{gnat_rm/implementation_defined_attributes attribute-loop-entry}@anchor{193} |
64d5610f ML |
10924 | @section Attribute Loop_Entry |
10925 | ||
10926 | ||
10927 | @geindex Loop_Entry | |
10928 | ||
10929 | Syntax: | |
10930 | ||
10931 | @example | |
10932 | X'Loop_Entry [(loop_name)] | |
10933 | @end example | |
10934 | ||
10935 | The @code{Loop_Entry} attribute is used to refer to the value that an | |
10936 | expression had upon entry to a given loop in much the same way that the | |
10937 | @code{Old} attribute in a subprogram postcondition can be used to refer | |
10938 | to the value an expression had upon entry to the subprogram. The | |
10939 | relevant loop is either identified by the given loop name, or it is the | |
10940 | innermost enclosing loop when no loop name is given. | |
10941 | ||
10942 | A @code{Loop_Entry} attribute can only occur within an @code{Assert}, | |
10943 | @code{Assert_And_Cut}, @code{Assume}, @code{Loop_Variant} or @code{Loop_Invariant} pragma. | |
10944 | In addition, such a pragma must be one of the items in the sequence | |
10945 | of statements of a loop body, or nested inside block statements that | |
10946 | appear in the sequence of statements of a loop body. | |
10947 | A common use of @code{Loop_Entry} is to compare the current value of objects with | |
10948 | their initial value at loop entry, in a @code{Loop_Invariant} pragma. | |
10949 | ||
10950 | The effect of using @code{X'Loop_Entry} is the same as declaring | |
10951 | a constant initialized with the initial value of @code{X} at loop | |
10952 | entry. This copy is not performed if the loop is not entered, or if the | |
10953 | corresponding pragmas are ignored or disabled. | |
10954 | ||
10955 | @node Attribute Machine_Size,Attribute Mantissa,Attribute Loop_Entry,Implementation Defined Attributes | |
9daee425 | 10956 | @anchor{gnat_rm/implementation_defined_attributes attribute-machine-size}@anchor{194} |
64d5610f ML |
10957 | @section Attribute Machine_Size |
10958 | ||
10959 | ||
10960 | @geindex Machine_Size | |
10961 | ||
10962 | This attribute is identical to the @code{Object_Size} attribute. It is | |
10963 | provided for compatibility with the DEC Ada 83 attribute of this name. | |
10964 | ||
10965 | @node Attribute Mantissa,Attribute Maximum_Alignment,Attribute Machine_Size,Implementation Defined Attributes | |
9daee425 | 10966 | @anchor{gnat_rm/implementation_defined_attributes attribute-mantissa}@anchor{195} |
64d5610f ML |
10967 | @section Attribute Mantissa |
10968 | ||
10969 | ||
10970 | @geindex Ada 83 attributes | |
10971 | ||
10972 | @geindex Mantissa | |
10973 | ||
10974 | The @code{Mantissa} attribute is provided for compatibility with Ada 83. See | |
10975 | the Ada 83 reference manual for an exact description of the semantics of | |
10976 | this attribute. | |
10977 | ||
10978 | @node Attribute Maximum_Alignment,Attribute Max_Integer_Size,Attribute Mantissa,Implementation Defined Attributes | |
9daee425 | 10979 | @anchor{gnat_rm/implementation_defined_attributes attribute-maximum-alignment}@anchor{196}@anchor{gnat_rm/implementation_defined_attributes id2}@anchor{197} |
64d5610f ML |
10980 | @section Attribute Maximum_Alignment |
10981 | ||
10982 | ||
10983 | @geindex Alignment | |
10984 | @geindex maximum | |
10985 | ||
10986 | @geindex Maximum_Alignment | |
10987 | ||
10988 | @code{Standard'Maximum_Alignment} (@code{Standard} is the only | |
10989 | allowed prefix) provides the maximum useful alignment value for the | |
10990 | target. This is a static value that can be used to specify the alignment | |
10991 | for an object, guaranteeing that it is properly aligned in all | |
10992 | cases. | |
10993 | ||
10994 | @node Attribute Max_Integer_Size,Attribute Mechanism_Code,Attribute Maximum_Alignment,Implementation Defined Attributes | |
9daee425 | 10995 | @anchor{gnat_rm/implementation_defined_attributes attribute-max-integer-size}@anchor{198} |
64d5610f ML |
10996 | @section Attribute Max_Integer_Size |
10997 | ||
10998 | ||
10999 | @geindex Max_Integer_Size | |
11000 | ||
11001 | @code{Standard'Max_Integer_Size} (@code{Standard} is the only allowed | |
11002 | prefix) provides the size of the largest supported integer type for | |
11003 | the target. The result is a static constant. | |
11004 | ||
11005 | @node Attribute Mechanism_Code,Attribute Null_Parameter,Attribute Max_Integer_Size,Implementation Defined Attributes | |
9daee425 | 11006 | @anchor{gnat_rm/implementation_defined_attributes attribute-mechanism-code}@anchor{199} |
64d5610f ML |
11007 | @section Attribute Mechanism_Code |
11008 | ||
11009 | ||
11010 | @geindex Return values | |
11011 | @geindex passing mechanism | |
11012 | ||
11013 | @geindex Parameters | |
11014 | @geindex passing mechanism | |
11015 | ||
11016 | @geindex Mechanism_Code | |
11017 | ||
11018 | @code{func'Mechanism_Code} yields an integer code for the | |
11019 | mechanism used for the result of function @code{func}, and | |
11020 | @code{subprog'Mechanism_Code (n)} yields the mechanism | |
1acce141 | 11021 | used for formal parameter number @emph{n} (a static integer value, with 1 |
64d5610f ML |
11022 | meaning the first parameter) of subprogram @code{subprog}. The code returned is: |
11023 | ||
11024 | ||
11025 | @table @asis | |
11026 | ||
1acce141 | 11027 | @item @emph{1} |
64d5610f ML |
11028 | |
11029 | by copy (value) | |
11030 | ||
1acce141 | 11031 | @item @emph{2} |
64d5610f ML |
11032 | |
11033 | by reference | |
11034 | @end table | |
11035 | ||
11036 | @node Attribute Null_Parameter,Attribute Object_Size,Attribute Mechanism_Code,Implementation Defined Attributes | |
9daee425 | 11037 | @anchor{gnat_rm/implementation_defined_attributes attribute-null-parameter}@anchor{19a} |
64d5610f ML |
11038 | @section Attribute Null_Parameter |
11039 | ||
11040 | ||
11041 | @geindex Zero address | |
11042 | @geindex passing | |
11043 | ||
11044 | @geindex Null_Parameter | |
11045 | ||
11046 | A reference @code{T'Null_Parameter} denotes an imaginary object of | |
11047 | type or subtype @code{T} allocated at machine address zero. The attribute | |
11048 | is allowed only as the default expression of a formal parameter, or as | |
11049 | an actual expression of a subprogram call. In either case, the | |
11050 | subprogram must be imported. | |
11051 | ||
11052 | The identity of the object is represented by the address zero in the | |
11053 | argument list, independent of the passing mechanism (explicit or | |
11054 | default). | |
11055 | ||
11056 | This capability is needed to specify that a zero address should be | |
11057 | passed for a record or other composite object passed by reference. | |
11058 | There is no way of indicating this without the @code{Null_Parameter} | |
11059 | attribute. | |
11060 | ||
11061 | @node Attribute Object_Size,Attribute Old,Attribute Null_Parameter,Implementation Defined Attributes | |
9daee425 | 11062 | @anchor{gnat_rm/implementation_defined_attributes attribute-object-size}@anchor{149}@anchor{gnat_rm/implementation_defined_attributes id3}@anchor{19b} |
64d5610f ML |
11063 | @section Attribute Object_Size |
11064 | ||
11065 | ||
11066 | @geindex Size | |
11067 | @geindex used for objects | |
11068 | ||
11069 | @geindex Object_Size | |
11070 | ||
11071 | The size of an object is not necessarily the same as the size of the type | |
11072 | of an object. This is because by default object sizes are increased to be | |
11073 | a multiple of the alignment of the object. For example, | |
11074 | @code{Natural'Size} is | |
11075 | 31, but by default objects of type @code{Natural} will have a size of 32 bits. | |
11076 | Similarly, a record containing an integer and a character: | |
11077 | ||
11078 | @example | |
11079 | type Rec is record | |
11080 | I : Integer; | |
11081 | C : Character; | |
11082 | end record; | |
11083 | @end example | |
11084 | ||
11085 | will have a size of 40 (that is @code{Rec'Size} will be 40). The | |
11086 | alignment will be 4, because of the | |
11087 | integer field, and so the default size of record objects for this type | |
11088 | will be 64 (8 bytes). | |
11089 | ||
11090 | If the alignment of the above record is specified to be 1, then the | |
11091 | object size will be 40 (5 bytes). This is true by default, and also | |
11092 | an object size of 40 can be explicitly specified in this case. | |
11093 | ||
11094 | A consequence of this capability is that different object sizes can be | |
11095 | given to subtypes that would otherwise be considered in Ada to be | |
11096 | statically matching. But it makes no sense to consider such subtypes | |
11097 | as statically matching. Consequently, GNAT adds a rule | |
11098 | to the static matching rules that requires object sizes to match. | |
11099 | Consider this example: | |
11100 | ||
11101 | @example | |
11102 | 1. procedure BadAVConvert is | |
11103 | 2. type R is new Integer; | |
11104 | 3. subtype R1 is R range 1 .. 10; | |
11105 | 4. subtype R2 is R range 1 .. 10; | |
11106 | 5. for R1'Object_Size use 8; | |
11107 | 6. for R2'Object_Size use 16; | |
11108 | 7. type R1P is access all R1; | |
11109 | 8. type R2P is access all R2; | |
11110 | 9. R1PV : R1P := new R1'(4); | |
11111 | 10. R2PV : R2P; | |
11112 | 11. begin | |
11113 | 12. R2PV := R2P (R1PV); | |
11114 | | | |
11115 | >>> target designated subtype not compatible with | |
11116 | type "R1" defined at line 3 | |
11117 | ||
11118 | 13. end; | |
11119 | @end example | |
11120 | ||
11121 | In the absence of lines 5 and 6, | |
11122 | types @code{R1} and @code{R2} statically match and | |
11123 | hence the conversion on line 12 is legal. But since lines 5 and 6 | |
11124 | cause the object sizes to differ, GNAT considers that types | |
11125 | @code{R1} and @code{R2} are not statically matching, and line 12 | |
11126 | generates the diagnostic shown above. | |
11127 | ||
11128 | Similar additional checks are performed in other contexts requiring | |
11129 | statically matching subtypes. | |
11130 | ||
11131 | @node Attribute Old,Attribute Passed_By_Reference,Attribute Object_Size,Implementation Defined Attributes | |
9daee425 | 11132 | @anchor{gnat_rm/implementation_defined_attributes attribute-old}@anchor{19c} |
64d5610f ML |
11133 | @section Attribute Old |
11134 | ||
11135 | ||
11136 | @geindex Old | |
11137 | ||
11138 | In addition to the usage of @code{Old} defined in the Ada 2012 RM (usage | |
11139 | within @code{Post} aspect), GNAT also permits the use of this attribute | |
11140 | in implementation defined pragmas @code{Postcondition}, | |
11141 | @code{Contract_Cases} and @code{Test_Case}. Also usages of | |
11142 | @code{Old} which would be illegal according to the Ada 2012 RM | |
11143 | definition are allowed under control of | |
11144 | implementation defined pragma @code{Unevaluated_Use_Of_Old}. | |
11145 | ||
11146 | @node Attribute Passed_By_Reference,Attribute Pool_Address,Attribute Old,Implementation Defined Attributes | |
9daee425 | 11147 | @anchor{gnat_rm/implementation_defined_attributes attribute-passed-by-reference}@anchor{19d} |
64d5610f ML |
11148 | @section Attribute Passed_By_Reference |
11149 | ||
11150 | ||
11151 | @geindex Parameters | |
11152 | @geindex when passed by reference | |
11153 | ||
11154 | @geindex Passed_By_Reference | |
11155 | ||
11156 | @code{typ'Passed_By_Reference} for any subtype @cite{typ} returns | |
11157 | a value of type @code{Boolean} value that is @code{True} if the type is | |
11158 | normally passed by reference and @code{False} if the type is normally | |
11159 | passed by copy in calls. For scalar types, the result is always @code{False} | |
11160 | and is static. For non-scalar types, the result is nonstatic. | |
11161 | ||
11162 | @node Attribute Pool_Address,Attribute Range_Length,Attribute Passed_By_Reference,Implementation Defined Attributes | |
9daee425 | 11163 | @anchor{gnat_rm/implementation_defined_attributes attribute-pool-address}@anchor{19e} |
64d5610f ML |
11164 | @section Attribute Pool_Address |
11165 | ||
11166 | ||
11167 | @geindex Pool_Address | |
11168 | ||
11169 | @code{X'Pool_Address} for any object @code{X} returns the address | |
11170 | of X within its storage pool. This is the same as | |
11171 | @code{X'Address}, except that for an unconstrained array whose | |
11172 | bounds are allocated just before the first component, | |
11173 | @code{X'Pool_Address} returns the address of those bounds, | |
11174 | whereas @code{X'Address} returns the address of the first | |
11175 | component. | |
11176 | ||
11177 | Here, we are interpreting ‘storage pool’ broadly to mean | |
11178 | @code{wherever the object is allocated}, which could be a | |
11179 | user-defined storage pool, | |
11180 | the global heap, on the stack, or in a static memory area. | |
11181 | For an object created by @code{new}, @code{Ptr.all'Pool_Address} is | |
11182 | what is passed to @code{Allocate} and returned from @code{Deallocate}. | |
11183 | ||
11184 | @node Attribute Range_Length,Attribute Restriction_Set,Attribute Pool_Address,Implementation Defined Attributes | |
9daee425 | 11185 | @anchor{gnat_rm/implementation_defined_attributes attribute-range-length}@anchor{19f} |
64d5610f ML |
11186 | @section Attribute Range_Length |
11187 | ||
11188 | ||
11189 | @geindex Range_Length | |
11190 | ||
11191 | @code{typ'Range_Length} for any discrete type @cite{typ} yields | |
11192 | the number of values represented by the subtype (zero for a null | |
11193 | range). The result is static for static subtypes. @code{Range_Length} | |
11194 | applied to the index subtype of a one dimensional array always gives the | |
11195 | same result as @code{Length} applied to the array itself. | |
11196 | ||
11197 | @node Attribute Restriction_Set,Attribute Result,Attribute Range_Length,Implementation Defined Attributes | |
9daee425 | 11198 | @anchor{gnat_rm/implementation_defined_attributes attribute-restriction-set}@anchor{1a0} |
64d5610f ML |
11199 | @section Attribute Restriction_Set |
11200 | ||
11201 | ||
11202 | @geindex Restriction_Set | |
11203 | ||
11204 | @geindex Restrictions | |
11205 | ||
11206 | This attribute allows compile time testing of restrictions that | |
11207 | are currently in effect. It is primarily intended for specializing | |
11208 | code in the run-time based on restrictions that are active (e.g. | |
11209 | don’t need to save fpt registers if restriction No_Floating_Point | |
11210 | is known to be in effect), but can be used anywhere. | |
11211 | ||
11212 | There are two forms: | |
11213 | ||
11214 | @example | |
11215 | System'Restriction_Set (partition_boolean_restriction_NAME) | |
11216 | System'Restriction_Set (No_Dependence => library_unit_NAME); | |
11217 | @end example | |
11218 | ||
11219 | In the case of the first form, the only restriction names | |
11220 | allowed are parameterless restrictions that are checked | |
11221 | for consistency at bind time. For a complete list see the | |
11222 | subtype @code{System.Rident.Partition_Boolean_Restrictions}. | |
11223 | ||
11224 | The result returned is True if the restriction is known to | |
11225 | be in effect, and False if the restriction is known not to | |
11226 | be in effect. An important guarantee is that the value of | |
11227 | a Restriction_Set attribute is known to be consistent throughout | |
11228 | all the code of a partition. | |
11229 | ||
11230 | This is trivially achieved if the entire partition is compiled | |
11231 | with a consistent set of restriction pragmas. However, the | |
11232 | compilation model does not require this. It is possible to | |
11233 | compile one set of units with one set of pragmas, and another | |
11234 | set of units with another set of pragmas. It is even possible | |
11235 | to compile a spec with one set of pragmas, and then WITH the | |
11236 | same spec with a different set of pragmas. Inconsistencies | |
11237 | in the actual use of the restriction are checked at bind time. | |
11238 | ||
11239 | In order to achieve the guarantee of consistency for the | |
11240 | Restriction_Set pragma, we consider that a use of the pragma | |
11241 | that yields False is equivalent to a violation of the | |
11242 | restriction. | |
11243 | ||
11244 | So for example if you write | |
11245 | ||
11246 | @example | |
11247 | if System'Restriction_Set (No_Floating_Point) then | |
11248 | ... | |
11249 | else | |
11250 | ... | |
11251 | end if; | |
11252 | @end example | |
11253 | ||
11254 | And the result is False, so that the else branch is executed, | |
11255 | you can assume that this restriction is not set for any unit | |
11256 | in the partition. This is checked by considering this use of | |
11257 | the restriction pragma to be a violation of the restriction | |
11258 | No_Floating_Point. This means that no other unit can attempt | |
11259 | to set this restriction (if some unit does attempt to set it, | |
11260 | the binder will refuse to bind the partition). | |
11261 | ||
11262 | Technical note: The restriction name and the unit name are | |
11263 | intepreted entirely syntactically, as in the corresponding | |
11264 | Restrictions pragma, they are not analyzed semantically, | |
11265 | so they do not have a type. | |
11266 | ||
11267 | @node Attribute Result,Attribute Safe_Emax,Attribute Restriction_Set,Implementation Defined Attributes | |
9daee425 | 11268 | @anchor{gnat_rm/implementation_defined_attributes attribute-result}@anchor{1a1} |
64d5610f ML |
11269 | @section Attribute Result |
11270 | ||
11271 | ||
11272 | @geindex Result | |
11273 | ||
11274 | @code{function'Result} can only be used with in a Postcondition pragma | |
11275 | for a function. The prefix must be the name of the corresponding function. This | |
11276 | is used to refer to the result of the function in the postcondition expression. | |
11277 | For a further discussion of the use of this attribute and examples of its use, | |
11278 | see the description of pragma Postcondition. | |
11279 | ||
11280 | @node Attribute Safe_Emax,Attribute Safe_Large,Attribute Result,Implementation Defined Attributes | |
9daee425 | 11281 | @anchor{gnat_rm/implementation_defined_attributes attribute-safe-emax}@anchor{1a2} |
64d5610f ML |
11282 | @section Attribute Safe_Emax |
11283 | ||
11284 | ||
11285 | @geindex Ada 83 attributes | |
11286 | ||
11287 | @geindex Safe_Emax | |
11288 | ||
11289 | The @code{Safe_Emax} attribute is provided for compatibility with Ada 83. See | |
11290 | the Ada 83 reference manual for an exact description of the semantics of | |
11291 | this attribute. | |
11292 | ||
11293 | @node Attribute Safe_Large,Attribute Safe_Small,Attribute Safe_Emax,Implementation Defined Attributes | |
9daee425 | 11294 | @anchor{gnat_rm/implementation_defined_attributes attribute-safe-large}@anchor{1a3} |
64d5610f ML |
11295 | @section Attribute Safe_Large |
11296 | ||
11297 | ||
11298 | @geindex Ada 83 attributes | |
11299 | ||
11300 | @geindex Safe_Large | |
11301 | ||
11302 | The @code{Safe_Large} attribute is provided for compatibility with Ada 83. See | |
11303 | the Ada 83 reference manual for an exact description of the semantics of | |
11304 | this attribute. | |
11305 | ||
11306 | @node Attribute Safe_Small,Attribute Scalar_Storage_Order,Attribute Safe_Large,Implementation Defined Attributes | |
9daee425 | 11307 | @anchor{gnat_rm/implementation_defined_attributes attribute-safe-small}@anchor{1a4} |
64d5610f ML |
11308 | @section Attribute Safe_Small |
11309 | ||
11310 | ||
11311 | @geindex Ada 83 attributes | |
11312 | ||
11313 | @geindex Safe_Small | |
11314 | ||
11315 | The @code{Safe_Small} attribute is provided for compatibility with Ada 83. See | |
11316 | the Ada 83 reference manual for an exact description of the semantics of | |
11317 | this attribute. | |
11318 | ||
11319 | @node Attribute Scalar_Storage_Order,Attribute Simple_Storage_Pool,Attribute Safe_Small,Implementation Defined Attributes | |
9daee425 | 11320 | @anchor{gnat_rm/implementation_defined_attributes attribute-scalar-storage-order}@anchor{157}@anchor{gnat_rm/implementation_defined_attributes id4}@anchor{1a5} |
64d5610f ML |
11321 | @section Attribute Scalar_Storage_Order |
11322 | ||
11323 | ||
11324 | @geindex Endianness | |
11325 | ||
11326 | @geindex Scalar storage order | |
11327 | ||
11328 | @geindex Scalar_Storage_Order | |
11329 | ||
11330 | For every array or record type @code{S}, the representation attribute | |
11331 | @code{Scalar_Storage_Order} denotes the order in which storage elements | |
11332 | that make up scalar components are ordered within S. The value given must | |
11333 | be a static expression of type System.Bit_Order. The following is an example | |
11334 | of the use of this feature: | |
11335 | ||
11336 | @example | |
11337 | -- Component type definitions | |
11338 | ||
11339 | subtype Yr_Type is Natural range 0 .. 127; | |
11340 | subtype Mo_Type is Natural range 1 .. 12; | |
11341 | subtype Da_Type is Natural range 1 .. 31; | |
11342 | ||
11343 | -- Record declaration | |
11344 | ||
11345 | type Date is record | |
11346 | Years_Since_1980 : Yr_Type; | |
11347 | Month : Mo_Type; | |
11348 | Day_Of_Month : Da_Type; | |
11349 | end record; | |
11350 | ||
11351 | -- Record representation clause | |
11352 | ||
11353 | for Date use record | |
11354 | Years_Since_1980 at 0 range 0 .. 6; | |
11355 | Month at 0 range 7 .. 10; | |
11356 | Day_Of_Month at 0 range 11 .. 15; | |
11357 | end record; | |
11358 | ||
11359 | -- Attribute definition clauses | |
11360 | ||
11361 | for Date'Bit_Order use System.High_Order_First; | |
11362 | for Date'Scalar_Storage_Order use System.High_Order_First; | |
11363 | -- If Scalar_Storage_Order is specified, it must be consistent with | |
11364 | -- Bit_Order, so it's best to always define the latter explicitly if | |
11365 | -- the former is used. | |
11366 | @end example | |
11367 | ||
11368 | Other properties are as for the standard representation attribute @code{Bit_Order} | |
11369 | defined by Ada RM 13.5.3(4). The default is @code{System.Default_Bit_Order}. | |
11370 | ||
11371 | For a record type @code{T}, if @code{T'Scalar_Storage_Order} is | |
11372 | specified explicitly, it shall be equal to @code{T'Bit_Order}. Note: | |
11373 | this means that if a @code{Scalar_Storage_Order} attribute definition | |
11374 | clause is not confirming, then the type’s @code{Bit_Order} shall be | |
11375 | specified explicitly and set to the same value. | |
11376 | ||
11377 | Derived types inherit an explicitly set scalar storage order from their parent | |
11378 | types. This may be overridden for the derived type by giving an explicit scalar | |
11379 | storage order for it. However, for a record extension, the derived type must | |
11380 | have the same scalar storage order as the parent type. | |
11381 | ||
11382 | A component of a record type that is itself a record or an array and that does | |
11383 | not start and end on a byte boundary must have have the same scalar storage | |
11384 | order as the record type. A component of a bit-packed array type that is itself | |
11385 | a record or an array must have the same scalar storage order as the array type. | |
11386 | ||
11387 | No component of a type that has an explicit @code{Scalar_Storage_Order} | |
11388 | attribute definition may be aliased. | |
11389 | ||
11390 | A confirming @code{Scalar_Storage_Order} attribute definition clause (i.e. | |
11391 | with a value equal to @code{System.Default_Bit_Order}) has no effect. | |
11392 | ||
11393 | If the opposite storage order is specified, then whenever the value of | |
11394 | a scalar component of an object of type @code{S} is read, the storage | |
11395 | elements of the enclosing machine scalar are first reversed (before | |
11396 | retrieving the component value, possibly applying some shift and mask | |
11397 | operatings on the enclosing machine scalar), and the opposite operation | |
11398 | is done for writes. | |
11399 | ||
11400 | In that case, the restrictions set forth in 13.5.1(10.3/2) for scalar components | |
11401 | are relaxed. Instead, the following rules apply: | |
11402 | ||
11403 | ||
11404 | @itemize * | |
11405 | ||
11406 | @item | |
11407 | the underlying storage elements are those at positions | |
11408 | @code{(position + first_bit / storage_element_size) .. (position + (last_bit + storage_element_size - 1) / storage_element_size)} | |
11409 | ||
11410 | @item | |
11411 | the sequence of underlying storage elements shall have | |
11412 | a size no greater than the largest machine scalar | |
11413 | ||
11414 | @item | |
11415 | the enclosing machine scalar is defined as the smallest machine | |
11416 | scalar starting at a position no greater than | |
11417 | @code{position + first_bit / storage_element_size} and covering | |
11418 | storage elements at least up to @code{position + (last_bit + storage_element_size - 1) / storage_element_size} | |
11419 | ||
11420 | @item | |
11421 | the position of the component is interpreted relative to that machine | |
11422 | scalar. | |
11423 | @end itemize | |
11424 | ||
11425 | If no scalar storage order is specified for a type (either directly, or by | |
11426 | inheritance in the case of a derived type), then the default is normally | |
11427 | the native ordering of the target, but this default can be overridden using | |
11428 | pragma @code{Default_Scalar_Storage_Order}. | |
11429 | ||
11430 | If a component of @code{T} is itself of a record or array type, the specfied | |
1acce141 | 11431 | @code{Scalar_Storage_Order} does @emph{not} apply to that nested type: an explicit |
64d5610f ML |
11432 | attribute definition clause must be provided for the component type as well |
11433 | if desired. | |
11434 | ||
11435 | Representation changes that explicitly or implicitly toggle the scalar storage | |
11436 | order are not supported and may result in erroneous execution of the program, | |
11437 | except when performed by means of an instance of @code{Ada.Unchecked_Conversion}. | |
11438 | ||
11439 | In particular, overlays are not supported and a warning is given for them: | |
11440 | ||
11441 | @example | |
11442 | type Rec_LE is record | |
11443 | I : Integer; | |
11444 | end record; | |
11445 | ||
11446 | for Rec_LE use record | |
11447 | I at 0 range 0 .. 31; | |
11448 | end record; | |
11449 | ||
11450 | for Rec_LE'Bit_Order use System.Low_Order_First; | |
11451 | for Rec_LE'Scalar_Storage_Order use System.Low_Order_First; | |
11452 | ||
11453 | type Rec_BE is record | |
11454 | I : Integer; | |
11455 | end record; | |
11456 | ||
11457 | for Rec_BE use record | |
11458 | I at 0 range 0 .. 31; | |
11459 | end record; | |
11460 | ||
11461 | for Rec_BE'Bit_Order use System.High_Order_First; | |
11462 | for Rec_BE'Scalar_Storage_Order use System.High_Order_First; | |
11463 | ||
11464 | R_LE : Rec_LE; | |
11465 | ||
11466 | R_BE : Rec_BE; | |
11467 | for R_BE'Address use R_LE'Address; | |
11468 | @end example | |
11469 | ||
11470 | @code{warning: overlay changes scalar storage order [enabled by default]} | |
11471 | ||
11472 | In most cases, such representation changes ought to be replaced by an | |
11473 | instantiation of a function or procedure provided by @code{GNAT.Byte_Swapping}. | |
11474 | ||
11475 | Note that the scalar storage order only affects the in-memory data | |
11476 | representation. It has no effect on the representation used by stream | |
11477 | attributes. | |
11478 | ||
11479 | Note that debuggers may be unable to display the correct value of scalar | |
11480 | components of a type for which the opposite storage order is specified. | |
11481 | ||
11482 | @node Attribute Simple_Storage_Pool,Attribute Small,Attribute Scalar_Storage_Order,Implementation Defined Attributes | |
9daee425 | 11483 | @anchor{gnat_rm/implementation_defined_attributes attribute-simple-storage-pool}@anchor{e9}@anchor{gnat_rm/implementation_defined_attributes id5}@anchor{1a6} |
64d5610f ML |
11484 | @section Attribute Simple_Storage_Pool |
11485 | ||
11486 | ||
11487 | @geindex Storage pool | |
11488 | @geindex simple | |
11489 | ||
11490 | @geindex Simple storage pool | |
11491 | ||
11492 | @geindex Simple_Storage_Pool | |
11493 | ||
11494 | For every nonformal, nonderived access-to-object type @code{Acc}, the | |
11495 | representation attribute @code{Simple_Storage_Pool} may be specified | |
11496 | via an attribute_definition_clause (or by specifying the equivalent aspect): | |
11497 | ||
11498 | @example | |
11499 | My_Pool : My_Simple_Storage_Pool_Type; | |
11500 | ||
11501 | type Acc is access My_Data_Type; | |
11502 | ||
11503 | for Acc'Simple_Storage_Pool use My_Pool; | |
11504 | @end example | |
11505 | ||
11506 | The name given in an attribute_definition_clause for the | |
11507 | @code{Simple_Storage_Pool} attribute shall denote a variable of | |
11508 | a ‘simple storage pool type’ (see pragma @cite{Simple_Storage_Pool_Type}). | |
11509 | ||
11510 | The use of this attribute is only allowed for a prefix denoting a type | |
11511 | for which it has been specified. The type of the attribute is the type | |
11512 | of the variable specified as the simple storage pool of the access type, | |
11513 | and the attribute denotes that variable. | |
11514 | ||
11515 | It is illegal to specify both @code{Storage_Pool} and @code{Simple_Storage_Pool} | |
11516 | for the same access type. | |
11517 | ||
11518 | If the @code{Simple_Storage_Pool} attribute has been specified for an access | |
11519 | type, then applying the @code{Storage_Pool} attribute to the type is flagged | |
11520 | with a warning and its evaluation raises the exception @code{Program_Error}. | |
11521 | ||
11522 | If the Simple_Storage_Pool attribute has been specified for an access | |
11523 | type @code{S}, then the evaluation of the attribute @code{S'Storage_Size} | |
11524 | returns the result of calling @code{Storage_Size (S'Simple_Storage_Pool)}, | |
11525 | which is intended to indicate the number of storage elements reserved for | |
11526 | the simple storage pool. If the Storage_Size function has not been defined | |
11527 | for the simple storage pool type, then this attribute returns zero. | |
11528 | ||
11529 | If an access type @code{S} has a specified simple storage pool of type | |
11530 | @code{SSP}, then the evaluation of an allocator for that access type calls | |
11531 | the primitive @code{Allocate} procedure for type @code{SSP}, passing | |
11532 | @code{S'Simple_Storage_Pool} as the pool parameter. The detailed | |
11533 | semantics of such allocators is the same as those defined for allocators | |
11534 | in section 13.11 of the @cite{Ada Reference Manual}, with the term | |
1acce141 | 11535 | @emph{simple storage pool} substituted for @emph{storage pool}. |
64d5610f ML |
11536 | |
11537 | If an access type @code{S} has a specified simple storage pool of type | |
11538 | @code{SSP}, then a call to an instance of the @code{Ada.Unchecked_Deallocation} | |
11539 | for that access type invokes the primitive @code{Deallocate} procedure | |
11540 | for type @code{SSP}, passing @code{S'Simple_Storage_Pool} as the pool | |
11541 | parameter. The detailed semantics of such unchecked deallocations is the same | |
11542 | as defined in section 13.11.2 of the Ada Reference Manual, except that the | |
1acce141 | 11543 | term @emph{simple storage pool} is substituted for @emph{storage pool}. |
64d5610f ML |
11544 | |
11545 | @node Attribute Small,Attribute Small_Denominator,Attribute Simple_Storage_Pool,Implementation Defined Attributes | |
9daee425 | 11546 | @anchor{gnat_rm/implementation_defined_attributes attribute-small}@anchor{1a7} |
64d5610f ML |
11547 | @section Attribute Small |
11548 | ||
11549 | ||
11550 | @geindex Ada 83 attributes | |
11551 | ||
11552 | @geindex Small | |
11553 | ||
11554 | The @code{Small} attribute is defined in Ada 95 (and Ada 2005) only for | |
11555 | fixed-point types. | |
11556 | GNAT also allows this attribute to be applied to floating-point types | |
11557 | for compatibility with Ada 83. See | |
11558 | the Ada 83 reference manual for an exact description of the semantics of | |
11559 | this attribute when applied to floating-point types. | |
11560 | ||
11561 | @node Attribute Small_Denominator,Attribute Small_Numerator,Attribute Small,Implementation Defined Attributes | |
9daee425 | 11562 | @anchor{gnat_rm/implementation_defined_attributes attribute-small-denominator}@anchor{1a8} |
64d5610f ML |
11563 | @section Attribute Small_Denominator |
11564 | ||
11565 | ||
11566 | @geindex Small | |
11567 | ||
11568 | @geindex Small_Denominator | |
11569 | ||
11570 | @code{typ'Small_Denominator} for any fixed-point subtype @cite{typ} yields the | |
11571 | denominator in the representation of @code{typ'Small} as a rational number | |
11572 | with coprime factors (i.e. as an irreducible fraction). | |
11573 | ||
11574 | @node Attribute Small_Numerator,Attribute Storage_Unit,Attribute Small_Denominator,Implementation Defined Attributes | |
9daee425 | 11575 | @anchor{gnat_rm/implementation_defined_attributes attribute-small-numerator}@anchor{1a9} |
64d5610f ML |
11576 | @section Attribute Small_Numerator |
11577 | ||
11578 | ||
11579 | @geindex Small | |
11580 | ||
11581 | @geindex Small_Numerator | |
11582 | ||
11583 | @code{typ'Small_Numerator} for any fixed-point subtype @cite{typ} yields the | |
11584 | numerator in the representation of @code{typ'Small} as a rational number | |
11585 | with coprime factors (i.e. as an irreducible fraction). | |
11586 | ||
11587 | @node Attribute Storage_Unit,Attribute Stub_Type,Attribute Small_Numerator,Implementation Defined Attributes | |
9daee425 | 11588 | @anchor{gnat_rm/implementation_defined_attributes attribute-storage-unit}@anchor{1aa} |
64d5610f ML |
11589 | @section Attribute Storage_Unit |
11590 | ||
11591 | ||
11592 | @geindex Storage_Unit | |
11593 | ||
11594 | @code{Standard'Storage_Unit} (@code{Standard} is the only allowed | |
11595 | prefix) provides the same value as @code{System.Storage_Unit}. | |
11596 | ||
11597 | @node Attribute Stub_Type,Attribute System_Allocator_Alignment,Attribute Storage_Unit,Implementation Defined Attributes | |
9daee425 | 11598 | @anchor{gnat_rm/implementation_defined_attributes attribute-stub-type}@anchor{1ab} |
64d5610f ML |
11599 | @section Attribute Stub_Type |
11600 | ||
11601 | ||
11602 | @geindex Stub_Type | |
11603 | ||
11604 | The GNAT implementation of remote access-to-classwide types is | |
11605 | organized as described in AARM section E.4 (20.t): a value of an RACW type | |
11606 | (designating a remote object) is represented as a normal access | |
11607 | value, pointing to a “stub” object which in turn contains the | |
11608 | necessary information to contact the designated remote object. A | |
11609 | call on any dispatching operation of such a stub object does the | |
11610 | remote call, if necessary, using the information in the stub object | |
11611 | to locate the target partition, etc. | |
11612 | ||
11613 | For a prefix @code{T} that denotes a remote access-to-classwide type, | |
11614 | @code{T'Stub_Type} denotes the type of the corresponding stub objects. | |
11615 | ||
11616 | By construction, the layout of @code{T'Stub_Type} is identical to that of | |
11617 | type @code{RACW_Stub_Type} declared in the internal implementation-defined | |
11618 | unit @code{System.Partition_Interface}. Use of this attribute will create | |
11619 | an implicit dependency on this unit. | |
11620 | ||
11621 | @node Attribute System_Allocator_Alignment,Attribute Target_Name,Attribute Stub_Type,Implementation Defined Attributes | |
9daee425 | 11622 | @anchor{gnat_rm/implementation_defined_attributes attribute-system-allocator-alignment}@anchor{1ac} |
64d5610f ML |
11623 | @section Attribute System_Allocator_Alignment |
11624 | ||
11625 | ||
11626 | @geindex Alignment | |
11627 | @geindex allocator | |
11628 | ||
11629 | @geindex System_Allocator_Alignment | |
11630 | ||
11631 | @code{Standard'System_Allocator_Alignment} (@code{Standard} is the only | |
11632 | allowed prefix) provides the observable guaranteed to be honored by | |
11633 | the system allocator (malloc). This is a static value that can be used | |
11634 | in user storage pools based on malloc either to reject allocation | |
11635 | with alignment too large or to enable a realignment circuitry if the | |
11636 | alignment request is larger than this value. | |
11637 | ||
11638 | @node Attribute Target_Name,Attribute To_Address,Attribute System_Allocator_Alignment,Implementation Defined Attributes | |
9daee425 | 11639 | @anchor{gnat_rm/implementation_defined_attributes attribute-target-name}@anchor{1ad} |
64d5610f ML |
11640 | @section Attribute Target_Name |
11641 | ||
11642 | ||
11643 | @geindex Target_Name | |
11644 | ||
11645 | @code{Standard'Target_Name} (@code{Standard} is the only allowed | |
11646 | prefix) provides a static string value that identifies the target | |
11647 | for the current compilation. For GCC implementations, this is the | |
11648 | standard gcc target name without the terminating slash (for | |
11649 | example, GNAT 5.0 on windows yields “i586-pc-mingw32msv”). | |
11650 | ||
11651 | @node Attribute To_Address,Attribute To_Any,Attribute Target_Name,Implementation Defined Attributes | |
9daee425 | 11652 | @anchor{gnat_rm/implementation_defined_attributes attribute-to-address}@anchor{1ae} |
64d5610f ML |
11653 | @section Attribute To_Address |
11654 | ||
11655 | ||
11656 | @geindex To_Address | |
11657 | ||
11658 | The @code{System'To_Address} | |
11659 | (@code{System} is the only allowed prefix) | |
11660 | denotes a function identical to | |
11661 | @code{System.Storage_Elements.To_Address} except that | |
11662 | it is a static attribute. This means that if its argument is | |
11663 | a static expression, then the result of the attribute is a | |
11664 | static expression. This means that such an expression can be | |
11665 | used in contexts (e.g., preelaborable packages) which require a | |
11666 | static expression and where the function call could not be used | |
11667 | (since the function call is always nonstatic, even if its | |
11668 | argument is static). The argument must be in the range | |
11669 | -(2**(m-1)) .. 2**m-1, where m is the memory size | |
11670 | (typically 32 or 64). Negative values are intepreted in a | |
11671 | modular manner (e.g., -1 means the same as 16#FFFF_FFFF# on | |
11672 | a 32 bits machine). | |
11673 | ||
11674 | @node Attribute To_Any,Attribute Type_Class,Attribute To_Address,Implementation Defined Attributes | |
9daee425 | 11675 | @anchor{gnat_rm/implementation_defined_attributes attribute-to-any}@anchor{1af} |
64d5610f ML |
11676 | @section Attribute To_Any |
11677 | ||
11678 | ||
11679 | @geindex To_Any | |
11680 | ||
11681 | This internal attribute is used for the generation of remote subprogram | |
11682 | stubs in the context of the Distributed Systems Annex. | |
11683 | ||
11684 | @node Attribute Type_Class,Attribute Type_Key,Attribute To_Any,Implementation Defined Attributes | |
9daee425 | 11685 | @anchor{gnat_rm/implementation_defined_attributes attribute-type-class}@anchor{1b0} |
64d5610f ML |
11686 | @section Attribute Type_Class |
11687 | ||
11688 | ||
11689 | @geindex Type_Class | |
11690 | ||
11691 | @code{typ'Type_Class} for any type or subtype @cite{typ} yields | |
11692 | the value of the type class for the full type of @cite{typ}. If | |
11693 | @cite{typ} is a generic formal type, the value is the value for the | |
11694 | corresponding actual subtype. The value of this attribute is of type | |
11695 | @code{System.Aux_DEC.Type_Class}, which has the following definition: | |
11696 | ||
11697 | @example | |
11698 | type Type_Class is | |
11699 | (Type_Class_Enumeration, | |
11700 | Type_Class_Integer, | |
11701 | Type_Class_Fixed_Point, | |
11702 | Type_Class_Floating_Point, | |
11703 | Type_Class_Array, | |
11704 | Type_Class_Record, | |
11705 | Type_Class_Access, | |
11706 | Type_Class_Task, | |
11707 | Type_Class_Address); | |
11708 | @end example | |
11709 | ||
11710 | Protected types yield the value @code{Type_Class_Task}, which thus | |
11711 | applies to all concurrent types. This attribute is designed to | |
11712 | be compatible with the DEC Ada 83 attribute of the same name. | |
11713 | ||
11714 | @node Attribute Type_Key,Attribute TypeCode,Attribute Type_Class,Implementation Defined Attributes | |
9daee425 | 11715 | @anchor{gnat_rm/implementation_defined_attributes attribute-type-key}@anchor{1b1} |
64d5610f ML |
11716 | @section Attribute Type_Key |
11717 | ||
11718 | ||
11719 | @geindex Type_Key | |
11720 | ||
11721 | The @code{Type_Key} attribute is applicable to a type or subtype and | |
11722 | yields a value of type Standard.String containing encoded information | |
11723 | about the type or subtype. This provides improved compatibility with | |
11724 | other implementations that support this attribute. | |
11725 | ||
11726 | @node Attribute TypeCode,Attribute Unconstrained_Array,Attribute Type_Key,Implementation Defined Attributes | |
9daee425 | 11727 | @anchor{gnat_rm/implementation_defined_attributes attribute-typecode}@anchor{1b2} |
64d5610f ML |
11728 | @section Attribute TypeCode |
11729 | ||
11730 | ||
11731 | @geindex TypeCode | |
11732 | ||
11733 | This internal attribute is used for the generation of remote subprogram | |
11734 | stubs in the context of the Distributed Systems Annex. | |
11735 | ||
11736 | @node Attribute Unconstrained_Array,Attribute Universal_Literal_String,Attribute TypeCode,Implementation Defined Attributes | |
9daee425 | 11737 | @anchor{gnat_rm/implementation_defined_attributes attribute-unconstrained-array}@anchor{1b3} |
64d5610f ML |
11738 | @section Attribute Unconstrained_Array |
11739 | ||
11740 | ||
11741 | @geindex Unconstrained_Array | |
11742 | ||
11743 | The @code{Unconstrained_Array} attribute can be used with a prefix that | |
11744 | denotes any type or subtype. It is a static attribute that yields | |
11745 | @code{True} if the prefix designates an unconstrained array, | |
11746 | and @code{False} otherwise. In a generic instance, the result is | |
11747 | still static, and yields the result of applying this test to the | |
11748 | generic actual. | |
11749 | ||
11750 | @node Attribute Universal_Literal_String,Attribute Unrestricted_Access,Attribute Unconstrained_Array,Implementation Defined Attributes | |
9daee425 | 11751 | @anchor{gnat_rm/implementation_defined_attributes attribute-universal-literal-string}@anchor{1b4} |
64d5610f ML |
11752 | @section Attribute Universal_Literal_String |
11753 | ||
11754 | ||
11755 | @geindex Named numbers | |
11756 | @geindex representation of | |
11757 | ||
11758 | @geindex Universal_Literal_String | |
11759 | ||
11760 | The prefix of @code{Universal_Literal_String} must be a named | |
11761 | number. The static result is the string consisting of the characters of | |
11762 | the number as defined in the original source. This allows the user | |
11763 | program to access the actual text of named numbers without intermediate | |
11764 | conversions and without the need to enclose the strings in quotes (which | |
11765 | would preclude their use as numbers). | |
11766 | ||
11767 | For example, the following program prints the first 50 digits of pi: | |
11768 | ||
11769 | @example | |
11770 | with Text_IO; use Text_IO; | |
11771 | with Ada.Numerics; | |
11772 | procedure Pi is | |
11773 | begin | |
11774 | Put (Ada.Numerics.Pi'Universal_Literal_String); | |
11775 | end; | |
11776 | @end example | |
11777 | ||
11778 | @node Attribute Unrestricted_Access,Attribute Update,Attribute Universal_Literal_String,Implementation Defined Attributes | |
9daee425 | 11779 | @anchor{gnat_rm/implementation_defined_attributes attribute-unrestricted-access}@anchor{1b5} |
64d5610f ML |
11780 | @section Attribute Unrestricted_Access |
11781 | ||
11782 | ||
11783 | @geindex Access | |
11784 | @geindex unrestricted | |
11785 | ||
11786 | @geindex Unrestricted_Access | |
11787 | ||
11788 | The @code{Unrestricted_Access} attribute is similar to @code{Access} | |
11789 | except that all accessibility and aliased view checks are omitted. This | |
11790 | is a user-beware attribute. | |
11791 | ||
11792 | For objects, it is similar to @code{Address}, for which it is a | |
11793 | desirable replacement where the value desired is an access type. | |
11794 | In other words, its effect is similar to first applying the | |
11795 | @code{Address} attribute and then doing an unchecked conversion to a | |
11796 | desired access type. | |
11797 | ||
11798 | For subprograms, @code{P'Unrestricted_Access} may be used where | |
11799 | @code{P'Access} would be illegal, to construct a value of a | |
11800 | less-nested named access type that designates a more-nested | |
11801 | subprogram. This value may be used in indirect calls, so long as the | |
11802 | more-nested subprogram still exists; once the subprogram containing it | |
11803 | has returned, such calls are erroneous. For example: | |
11804 | ||
11805 | @example | |
11806 | package body P is | |
11807 | ||
11808 | type Less_Nested is not null access procedure; | |
11809 | Global : Less_Nested; | |
11810 | ||
11811 | procedure P1 is | |
11812 | begin | |
11813 | Global.all; | |
11814 | end P1; | |
11815 | ||
11816 | procedure P2 is | |
11817 | Local_Var : Integer; | |
11818 | ||
11819 | procedure More_Nested is | |
11820 | begin | |
11821 | ... Local_Var ... | |
11822 | end More_Nested; | |
11823 | begin | |
11824 | Global := More_Nested'Unrestricted_Access; | |
11825 | P1; | |
11826 | end P2; | |
11827 | ||
11828 | end P; | |
11829 | @end example | |
11830 | ||
11831 | When P1 is called from P2, the call via Global is OK, but if P1 were | |
11832 | called after P2 returns, it would be an erroneous use of a dangling | |
11833 | pointer. | |
11834 | ||
11835 | For objects, it is possible to use @code{Unrestricted_Access} for any | |
11836 | type. However, if the result is of an access-to-unconstrained array | |
11837 | subtype, then the resulting pointer has the same scope as the context | |
11838 | of the attribute, and must not be returned to some enclosing scope. | |
11839 | For instance, if a function uses @code{Unrestricted_Access} to create | |
11840 | an access-to-unconstrained-array and returns that value to the caller, | |
11841 | the result will involve dangling pointers. In addition, it is only | |
11842 | valid to create pointers to unconstrained arrays using this attribute | |
11843 | if the pointer has the normal default ‘fat’ representation where a | |
11844 | pointer has two components, one points to the array and one points to | |
11845 | the bounds. If a size clause is used to force ‘thin’ representation | |
11846 | for a pointer to unconstrained where there is only space for a single | |
11847 | pointer, then the resulting pointer is not usable. | |
11848 | ||
11849 | In the simple case where a direct use of Unrestricted_Access attempts | |
11850 | to make a thin pointer for a non-aliased object, the compiler will | |
11851 | reject the use as illegal, as shown in the following example: | |
11852 | ||
11853 | @example | |
11854 | with System; use System; | |
11855 | procedure SliceUA2 is | |
11856 | type A is access all String; | |
11857 | for A'Size use Standard'Address_Size; | |
11858 | ||
11859 | procedure P (Arg : A) is | |
11860 | begin | |
11861 | null; | |
11862 | end P; | |
11863 | ||
11864 | X : String := "hello world!"; | |
11865 | X2 : aliased String := "hello world!"; | |
11866 | ||
11867 | AV : A := X'Unrestricted_Access; -- ERROR | |
11868 | | | |
11869 | >>> illegal use of Unrestricted_Access attribute | |
11870 | >>> attempt to generate thin pointer to unaliased object | |
11871 | ||
11872 | begin | |
11873 | P (X'Unrestricted_Access); -- ERROR | |
11874 | | | |
11875 | >>> illegal use of Unrestricted_Access attribute | |
11876 | >>> attempt to generate thin pointer to unaliased object | |
11877 | ||
11878 | P (X(7 .. 12)'Unrestricted_Access); -- ERROR | |
11879 | | | |
11880 | >>> illegal use of Unrestricted_Access attribute | |
11881 | >>> attempt to generate thin pointer to unaliased object | |
11882 | ||
11883 | P (X2'Unrestricted_Access); -- OK | |
11884 | end; | |
11885 | @end example | |
11886 | ||
11887 | but other cases cannot be detected by the compiler, and are | |
11888 | considered to be erroneous. Consider the following example: | |
11889 | ||
11890 | @example | |
11891 | with System; use System; | |
11892 | with System; use System; | |
11893 | procedure SliceUA is | |
11894 | type AF is access all String; | |
11895 | ||
11896 | type A is access all String; | |
11897 | for A'Size use Standard'Address_Size; | |
11898 | ||
11899 | procedure P (Arg : A) is | |
11900 | begin | |
11901 | if Arg'Length /= 6 then | |
11902 | raise Program_Error; | |
11903 | end if; | |
11904 | end P; | |
11905 | ||
11906 | X : String := "hello world!"; | |
11907 | Y : AF := X (7 .. 12)'Unrestricted_Access; | |
11908 | ||
11909 | begin | |
11910 | P (A (Y)); | |
11911 | end; | |
11912 | @end example | |
11913 | ||
11914 | A normal unconstrained array value | |
11915 | or a constrained array object marked as aliased has the bounds in memory | |
11916 | just before the array, so a thin pointer can retrieve both the data and | |
11917 | the bounds. But in this case, the non-aliased object @code{X} does not have the | |
11918 | bounds before the string. If the size clause for type @code{A} | |
11919 | were not present, then the pointer | |
11920 | would be a fat pointer, where one component is a pointer to the bounds, | |
11921 | and all would be well. But with the size clause present, the conversion from | |
11922 | fat pointer to thin pointer in the call loses the bounds, and so this | |
11923 | is erroneous, and the program likely raises a @code{Program_Error} exception. | |
11924 | ||
11925 | In general, it is advisable to completely | |
11926 | avoid mixing the use of thin pointers and the use of | |
11927 | @code{Unrestricted_Access} where the designated type is an | |
11928 | unconstrained array. The use of thin pointers should be restricted to | |
11929 | cases of porting legacy code that implicitly assumes the size of pointers, | |
11930 | and such code should not in any case be using this attribute. | |
11931 | ||
11932 | Another erroneous situation arises if the attribute is | |
11933 | applied to a constant. The resulting pointer can be used to access the | |
11934 | constant, but the effect of trying to modify a constant in this manner | |
11935 | is not well-defined. Consider this example: | |
11936 | ||
11937 | @example | |
11938 | P : constant Integer := 4; | |
11939 | type R is access all Integer; | |
11940 | RV : R := P'Unrestricted_Access; | |
11941 | .. | |
11942 | RV.all := 3; | |
11943 | @end example | |
11944 | ||
11945 | Here we attempt to modify the constant P from 4 to 3, but the compiler may | |
11946 | or may not notice this attempt, and subsequent references to P may yield | |
11947 | either the value 3 or the value 4 or the assignment may blow up if the | |
11948 | compiler decides to put P in read-only memory. One particular case where | |
11949 | @code{Unrestricted_Access} can be used in this way is to modify the | |
11950 | value of an @code{in} parameter: | |
11951 | ||
11952 | @example | |
11953 | procedure K (S : in String) is | |
11954 | type R is access all Character; | |
11955 | RV : R := S (3)'Unrestricted_Access; | |
11956 | begin | |
11957 | RV.all := 'a'; | |
11958 | end; | |
11959 | @end example | |
11960 | ||
11961 | In general this is a risky approach. It may appear to “work” but such uses of | |
11962 | @code{Unrestricted_Access} are potentially non-portable, even from one version | |
11963 | of GNAT to another, so are best avoided if possible. | |
11964 | ||
11965 | @node Attribute Update,Attribute Valid_Value,Attribute Unrestricted_Access,Implementation Defined Attributes | |
9daee425 | 11966 | @anchor{gnat_rm/implementation_defined_attributes attribute-update}@anchor{1b6} |
64d5610f ML |
11967 | @section Attribute Update |
11968 | ||
11969 | ||
11970 | @geindex Update | |
11971 | ||
11972 | The @code{Update} attribute creates a copy of an array or record value | |
11973 | with one or more modified components. The syntax is: | |
11974 | ||
11975 | @example | |
11976 | PREFIX'Update ( RECORD_COMPONENT_ASSOCIATION_LIST ) | |
11977 | PREFIX'Update ( ARRAY_COMPONENT_ASSOCIATION @{, ARRAY_COMPONENT_ASSOCIATION @} ) | |
11978 | PREFIX'Update ( MULTIDIMENSIONAL_ARRAY_COMPONENT_ASSOCIATION | |
11979 | @{, MULTIDIMENSIONAL_ARRAY_COMPONENT_ASSOCIATION @} ) | |
11980 | ||
11981 | MULTIDIMENSIONAL_ARRAY_COMPONENT_ASSOCIATION ::= INDEX_EXPRESSION_LIST_LIST => EXPRESSION | |
11982 | INDEX_EXPRESSION_LIST_LIST ::= INDEX_EXPRESSION_LIST @{| INDEX_EXPRESSION_LIST @} | |
11983 | INDEX_EXPRESSION_LIST ::= ( EXPRESSION @{, EXPRESSION @} ) | |
11984 | @end example | |
11985 | ||
11986 | where @code{PREFIX} is the name of an array or record object, the | |
11987 | association list in parentheses does not contain an @code{others} | |
11988 | choice and the box symbol @code{<>} may not appear in any | |
11989 | expression. The effect is to yield a copy of the array or record value | |
11990 | which is unchanged apart from the components mentioned in the | |
11991 | association list, which are changed to the indicated value. The | |
11992 | original value of the array or record value is not affected. For | |
11993 | example: | |
11994 | ||
11995 | @example | |
11996 | type Arr is Array (1 .. 5) of Integer; | |
11997 | ... | |
11998 | Avar1 : Arr := (1,2,3,4,5); | |
11999 | Avar2 : Arr := Avar1'Update (2 => 10, 3 .. 4 => 20); | |
12000 | @end example | |
12001 | ||
12002 | yields a value for @code{Avar2} of 1,10,20,20,5 with @code{Avar1} | |
12003 | begin unmodified. Similarly: | |
12004 | ||
12005 | @example | |
12006 | type Rec is A, B, C : Integer; | |
12007 | ... | |
12008 | Rvar1 : Rec := (A => 1, B => 2, C => 3); | |
12009 | Rvar2 : Rec := Rvar1'Update (B => 20); | |
12010 | @end example | |
12011 | ||
12012 | yields a value for @code{Rvar2} of (A => 1, B => 20, C => 3), | |
12013 | with @code{Rvar1} being unmodifed. | |
12014 | Note that the value of the attribute reference is computed | |
12015 | completely before it is used. This means that if you write: | |
12016 | ||
12017 | @example | |
12018 | Avar1 := Avar1'Update (1 => 10, 2 => Function_Call); | |
12019 | @end example | |
12020 | ||
12021 | then the value of @code{Avar1} is not modified if @code{Function_Call} | |
12022 | raises an exception, unlike the effect of a series of direct assignments | |
12023 | to elements of @code{Avar1}. In general this requires that | |
12024 | two extra complete copies of the object are required, which should be | |
12025 | kept in mind when considering efficiency. | |
12026 | ||
12027 | The @code{Update} attribute cannot be applied to prefixes of a limited | |
12028 | type, and cannot reference discriminants in the case of a record type. | |
12029 | The accessibility level of an Update attribute result object is defined | |
12030 | as for an aggregate. | |
12031 | ||
12032 | In the record case, no component can be mentioned more than once. In | |
12033 | the array case, two overlapping ranges can appear in the association list, | |
12034 | in which case the modifications are processed left to right. | |
12035 | ||
12036 | Multi-dimensional arrays can be modified, as shown by this example: | |
12037 | ||
12038 | @example | |
12039 | A : array (1 .. 10, 1 .. 10) of Integer; | |
12040 | .. | |
12041 | A := A'Update ((1, 2) => 20, (3, 4) => 30); | |
12042 | @end example | |
12043 | ||
12044 | which changes element (1,2) to 20 and (3,4) to 30. | |
12045 | ||
12046 | @node Attribute Valid_Value,Attribute Valid_Scalars,Attribute Update,Implementation Defined Attributes | |
9daee425 | 12047 | @anchor{gnat_rm/implementation_defined_attributes attribute-valid-value}@anchor{1b7} |
64d5610f ML |
12048 | @section Attribute Valid_Value |
12049 | ||
12050 | ||
12051 | @geindex Valid_Value | |
12052 | ||
12053 | The @code{'Valid_Value} attribute is defined for enumeration types other than | |
12054 | those in package Standard. This attribute is a function that takes | |
12055 | a String, and returns Boolean. @code{T'Valid_Value (S)} returns True | |
12056 | if and only if @code{T'Value (S)} would not raise Constraint_Error. | |
12057 | ||
12058 | @node Attribute Valid_Scalars,Attribute VADS_Size,Attribute Valid_Value,Implementation Defined Attributes | |
9daee425 | 12059 | @anchor{gnat_rm/implementation_defined_attributes attribute-valid-scalars}@anchor{1b8} |
64d5610f ML |
12060 | @section Attribute Valid_Scalars |
12061 | ||
12062 | ||
12063 | @geindex Valid_Scalars | |
12064 | ||
12065 | The @code{'Valid_Scalars} attribute is intended to make it easier to check the | |
12066 | validity of scalar subcomponents of composite objects. The attribute is defined | |
12067 | for any prefix @code{P} which denotes an object. Prefix @code{P} can be any type | |
12068 | except for tagged private or @code{Unchecked_Union} types. The value of the | |
12069 | attribute is of type @code{Boolean}. | |
12070 | ||
12071 | @code{P'Valid_Scalars} yields @code{True} if and only if the evaluation of | |
12072 | @code{C'Valid} yields @code{True} for every scalar subcomponent @code{C} of @code{P}, or if | |
12073 | @code{P} has no scalar subcomponents. Attribute @code{'Valid_Scalars} is equivalent | |
12074 | to attribute @code{'Valid} for scalar types. | |
12075 | ||
12076 | It is not specified in what order the subcomponents are checked, nor whether | |
12077 | any more are checked after any one of them is determined to be invalid. If the | |
12078 | prefix @code{P} is of a class-wide type @code{T'Class} (where @code{T} is the associated | |
12079 | specific type), or if the prefix @code{P} is of a specific tagged type @code{T}, then | |
12080 | only the subcomponents of @code{T} are checked; in other words, components of | |
12081 | extensions of @code{T} are not checked even if @code{T'Class (P)'Tag /= T'Tag}. | |
12082 | ||
12083 | The compiler will issue a warning if it can be determined at compile time that | |
12084 | the prefix of the attribute has no scalar subcomponents. | |
12085 | ||
12086 | Note: @code{Valid_Scalars} can generate a lot of code, especially in the case of | |
12087 | a large variant record. If the attribute is called in many places in the same | |
12088 | program applied to objects of the same type, it can reduce program size to | |
12089 | write a function with a single use of the attribute, and then call that | |
12090 | function from multiple places. | |
12091 | ||
12092 | @node Attribute VADS_Size,Attribute Value_Size,Attribute Valid_Scalars,Implementation Defined Attributes | |
9daee425 | 12093 | @anchor{gnat_rm/implementation_defined_attributes attribute-vads-size}@anchor{1b9} |
64d5610f ML |
12094 | @section Attribute VADS_Size |
12095 | ||
12096 | ||
12097 | @geindex Size | |
12098 | @geindex VADS compatibility | |
12099 | ||
12100 | @geindex VADS_Size | |
12101 | ||
12102 | The @code{'VADS_Size} attribute is intended to make it easier to port | |
12103 | legacy code which relies on the semantics of @code{'Size} as implemented | |
12104 | by the VADS Ada 83 compiler. GNAT makes a best effort at duplicating the | |
12105 | same semantic interpretation. In particular, @code{'VADS_Size} applied | |
12106 | to a predefined or other primitive type with no Size clause yields the | |
12107 | Object_Size (for example, @code{Natural'Size} is 32 rather than 31 on | |
12108 | typical machines). In addition @code{'VADS_Size} applied to an object | |
12109 | gives the result that would be obtained by applying the attribute to | |
12110 | the corresponding type. | |
12111 | ||
12112 | @node Attribute Value_Size,Attribute Wchar_T_Size,Attribute VADS_Size,Implementation Defined Attributes | |
9daee425 | 12113 | @anchor{gnat_rm/implementation_defined_attributes attribute-value-size}@anchor{167}@anchor{gnat_rm/implementation_defined_attributes id6}@anchor{1ba} |
64d5610f ML |
12114 | @section Attribute Value_Size |
12115 | ||
12116 | ||
12117 | @geindex Size | |
12118 | @geindex setting for not-first subtype | |
12119 | ||
12120 | @geindex Value_Size | |
12121 | ||
12122 | @code{type'Value_Size} is the number of bits required to represent | |
12123 | a value of the given subtype. It is the same as @code{type'Size}, | |
12124 | but, unlike @code{Size}, may be set for non-first subtypes. | |
12125 | ||
12126 | @node Attribute Wchar_T_Size,Attribute Word_Size,Attribute Value_Size,Implementation Defined Attributes | |
9daee425 | 12127 | @anchor{gnat_rm/implementation_defined_attributes attribute-wchar-t-size}@anchor{1bb} |
64d5610f ML |
12128 | @section Attribute Wchar_T_Size |
12129 | ||
12130 | ||
12131 | @geindex Wchar_T_Size | |
12132 | ||
12133 | @code{Standard'Wchar_T_Size} (@code{Standard} is the only allowed | |
12134 | prefix) provides the size in bits of the C @code{wchar_t} type | |
12135 | primarily for constructing the definition of this type in | |
12136 | package @code{Interfaces.C}. The result is a static constant. | |
12137 | ||
12138 | @node Attribute Word_Size,,Attribute Wchar_T_Size,Implementation Defined Attributes | |
9daee425 | 12139 | @anchor{gnat_rm/implementation_defined_attributes attribute-word-size}@anchor{1bc} |
64d5610f ML |
12140 | @section Attribute Word_Size |
12141 | ||
12142 | ||
12143 | @geindex Word_Size | |
12144 | ||
12145 | @code{Standard'Word_Size} (@code{Standard} is the only allowed | |
12146 | prefix) provides the value @code{System.Word_Size}. The result is | |
12147 | a static constant. | |
12148 | ||
12149 | @node Standard and Implementation Defined Restrictions,Implementation Advice,Implementation Defined Attributes,Top | |
9daee425 | 12150 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions doc}@anchor{1bd}@anchor{gnat_rm/standard_and_implementation_defined_restrictions id1}@anchor{1be}@anchor{gnat_rm/standard_and_implementation_defined_restrictions standard-and-implementation-defined-restrictions}@anchor{9} |
64d5610f ML |
12151 | @chapter Standard and Implementation Defined Restrictions |
12152 | ||
12153 | ||
12154 | All Ada Reference Manual-defined Restriction identifiers are implemented: | |
12155 | ||
12156 | ||
12157 | @itemize * | |
12158 | ||
12159 | @item | |
12160 | language-defined restrictions (see 13.12.1) | |
12161 | ||
12162 | @item | |
12163 | tasking restrictions (see D.7) | |
12164 | ||
12165 | @item | |
12166 | high integrity restrictions (see H.4) | |
12167 | @end itemize | |
12168 | ||
12169 | GNAT implements additional restriction identifiers. All restrictions, whether | |
12170 | language defined or GNAT-specific, are listed in the following. | |
12171 | ||
12172 | @menu | |
12173 | * Partition-Wide Restrictions:: | |
12174 | * Program Unit Level Restrictions:: | |
12175 | ||
12176 | @end menu | |
12177 | ||
12178 | @node Partition-Wide Restrictions,Program Unit Level Restrictions,,Standard and Implementation Defined Restrictions | |
9daee425 | 12179 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions id2}@anchor{1bf}@anchor{gnat_rm/standard_and_implementation_defined_restrictions partition-wide-restrictions}@anchor{1c0} |
64d5610f ML |
12180 | @section Partition-Wide Restrictions |
12181 | ||
12182 | ||
12183 | There are two separate lists of restriction identifiers. The first | |
12184 | set requires consistency throughout a partition (in other words, if the | |
12185 | restriction identifier is used for any compilation unit in the partition, | |
12186 | then all compilation units in the partition must obey the restriction). | |
12187 | ||
12188 | @menu | |
12189 | * Immediate_Reclamation:: | |
12190 | * Max_Asynchronous_Select_Nesting:: | |
12191 | * Max_Entry_Queue_Length:: | |
12192 | * Max_Protected_Entries:: | |
12193 | * Max_Select_Alternatives:: | |
12194 | * Max_Storage_At_Blocking:: | |
12195 | * Max_Task_Entries:: | |
12196 | * Max_Tasks:: | |
12197 | * No_Abort_Statements:: | |
12198 | * No_Access_Parameter_Allocators:: | |
12199 | * No_Access_Subprograms:: | |
12200 | * No_Allocators:: | |
12201 | * No_Anonymous_Allocators:: | |
12202 | * No_Asynchronous_Control:: | |
12203 | * No_Calendar:: | |
12204 | * No_Coextensions:: | |
12205 | * No_Default_Initialization:: | |
12206 | * No_Delay:: | |
12207 | * No_Dependence:: | |
12208 | * No_Direct_Boolean_Operators:: | |
12209 | * No_Dispatch:: | |
12210 | * No_Dispatching_Calls:: | |
12211 | * No_Dynamic_Attachment:: | |
12212 | * No_Dynamic_Priorities:: | |
12213 | * No_Entry_Calls_In_Elaboration_Code:: | |
12214 | * No_Enumeration_Maps:: | |
12215 | * No_Exception_Handlers:: | |
12216 | * No_Exception_Propagation:: | |
12217 | * No_Exception_Registration:: | |
12218 | * No_Exceptions:: | |
12219 | * No_Finalization:: | |
12220 | * No_Fixed_Point:: | |
12221 | * No_Floating_Point:: | |
12222 | * No_Implicit_Conditionals:: | |
12223 | * No_Implicit_Dynamic_Code:: | |
12224 | * No_Implicit_Heap_Allocations:: | |
12225 | * No_Implicit_Protected_Object_Allocations:: | |
12226 | * No_Implicit_Task_Allocations:: | |
12227 | * No_Initialize_Scalars:: | |
12228 | * No_IO:: | |
12229 | * No_Local_Allocators:: | |
12230 | * No_Local_Protected_Objects:: | |
12231 | * No_Local_Tagged_Types:: | |
12232 | * No_Local_Timing_Events:: | |
12233 | * No_Long_Long_Integers:: | |
12234 | * No_Multiple_Elaboration:: | |
12235 | * No_Nested_Finalization:: | |
12236 | * No_Protected_Type_Allocators:: | |
12237 | * No_Protected_Types:: | |
12238 | * No_Recursion:: | |
12239 | * No_Reentrancy:: | |
12240 | * No_Relative_Delay:: | |
12241 | * No_Requeue_Statements:: | |
12242 | * No_Secondary_Stack:: | |
12243 | * No_Select_Statements:: | |
12244 | * No_Specific_Termination_Handlers:: | |
12245 | * No_Specification_of_Aspect:: | |
12246 | * No_Standard_Allocators_After_Elaboration:: | |
12247 | * No_Standard_Storage_Pools:: | |
12248 | * No_Stream_Optimizations:: | |
12249 | * No_Streams:: | |
12250 | * No_Tagged_Type_Registration:: | |
12251 | * No_Task_Allocators:: | |
12252 | * No_Task_At_Interrupt_Priority:: | |
12253 | * No_Task_Attributes_Package:: | |
12254 | * No_Task_Hierarchy:: | |
12255 | * No_Task_Termination:: | |
12256 | * No_Tasking:: | |
12257 | * No_Terminate_Alternatives:: | |
12258 | * No_Unchecked_Access:: | |
12259 | * No_Unchecked_Conversion:: | |
12260 | * No_Unchecked_Deallocation:: | |
73918baf | 12261 | * No_Use_Of_Attribute:: |
64d5610f | 12262 | * No_Use_Of_Entity:: |
73918baf | 12263 | * No_Use_Of_Pragma:: |
64d5610f ML |
12264 | * Pure_Barriers:: |
12265 | * Simple_Barriers:: | |
12266 | * Static_Priorities:: | |
12267 | * Static_Storage_Size:: | |
12268 | ||
12269 | @end menu | |
12270 | ||
12271 | @node Immediate_Reclamation,Max_Asynchronous_Select_Nesting,,Partition-Wide Restrictions | |
9daee425 | 12272 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions immediate-reclamation}@anchor{1c1} |
64d5610f ML |
12273 | @subsection Immediate_Reclamation |
12274 | ||
12275 | ||
12276 | @geindex Immediate_Reclamation | |
12277 | ||
12278 | [RM H.4] This restriction ensures that, except for storage occupied by | |
12279 | objects created by allocators and not deallocated via unchecked | |
12280 | deallocation, any storage reserved at run time for an object is | |
12281 | immediately reclaimed when the object no longer exists. | |
12282 | ||
12283 | @node Max_Asynchronous_Select_Nesting,Max_Entry_Queue_Length,Immediate_Reclamation,Partition-Wide Restrictions | |
9daee425 | 12284 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions max-asynchronous-select-nesting}@anchor{1c2} |
64d5610f ML |
12285 | @subsection Max_Asynchronous_Select_Nesting |
12286 | ||
12287 | ||
12288 | @geindex Max_Asynchronous_Select_Nesting | |
12289 | ||
12290 | [RM D.7] Specifies the maximum dynamic nesting level of asynchronous | |
12291 | selects. Violations of this restriction with a value of zero are | |
12292 | detected at compile time. Violations of this restriction with values | |
12293 | other than zero cause Storage_Error to be raised. | |
12294 | ||
12295 | @node Max_Entry_Queue_Length,Max_Protected_Entries,Max_Asynchronous_Select_Nesting,Partition-Wide Restrictions | |
9daee425 | 12296 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions max-entry-queue-length}@anchor{1c3} |
64d5610f ML |
12297 | @subsection Max_Entry_Queue_Length |
12298 | ||
12299 | ||
12300 | @geindex Max_Entry_Queue_Length | |
12301 | ||
12302 | [RM D.7] This restriction is a declaration that any protected entry compiled in | |
12303 | the scope of the restriction has at most the specified number of | |
12304 | tasks waiting on the entry at any one time, and so no queue is required. | |
12305 | Note that this restriction is checked at run time. Violation of this | |
12306 | restriction results in the raising of Program_Error exception at the point of | |
12307 | the call. | |
12308 | ||
12309 | @geindex Max_Entry_Queue_Depth | |
12310 | ||
12311 | The restriction @code{Max_Entry_Queue_Depth} is recognized as a | |
12312 | synonym for @code{Max_Entry_Queue_Length}. This is retained for historical | |
12313 | compatibility purposes (and a warning will be generated for its use if | |
12314 | warnings on obsolescent features are activated). | |
12315 | ||
12316 | @node Max_Protected_Entries,Max_Select_Alternatives,Max_Entry_Queue_Length,Partition-Wide Restrictions | |
9daee425 | 12317 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions max-protected-entries}@anchor{1c4} |
64d5610f ML |
12318 | @subsection Max_Protected_Entries |
12319 | ||
12320 | ||
12321 | @geindex Max_Protected_Entries | |
12322 | ||
12323 | [RM D.7] Specifies the maximum number of entries per protected type. The | |
12324 | bounds of every entry family of a protected unit shall be static, or shall be | |
12325 | defined by a discriminant of a subtype whose corresponding bound is static. | |
12326 | ||
12327 | @node Max_Select_Alternatives,Max_Storage_At_Blocking,Max_Protected_Entries,Partition-Wide Restrictions | |
9daee425 | 12328 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions max-select-alternatives}@anchor{1c5} |
64d5610f ML |
12329 | @subsection Max_Select_Alternatives |
12330 | ||
12331 | ||
12332 | @geindex Max_Select_Alternatives | |
12333 | ||
12334 | [RM D.7] Specifies the maximum number of alternatives in a selective accept. | |
12335 | ||
12336 | @node Max_Storage_At_Blocking,Max_Task_Entries,Max_Select_Alternatives,Partition-Wide Restrictions | |
9daee425 | 12337 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions max-storage-at-blocking}@anchor{1c6} |
64d5610f ML |
12338 | @subsection Max_Storage_At_Blocking |
12339 | ||
12340 | ||
12341 | @geindex Max_Storage_At_Blocking | |
12342 | ||
12343 | [RM D.7] Specifies the maximum portion (in storage elements) of a task’s | |
12344 | Storage_Size that can be retained by a blocked task. A violation of this | |
12345 | restriction causes Storage_Error to be raised. | |
12346 | ||
12347 | @node Max_Task_Entries,Max_Tasks,Max_Storage_At_Blocking,Partition-Wide Restrictions | |
9daee425 | 12348 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions max-task-entries}@anchor{1c7} |
64d5610f ML |
12349 | @subsection Max_Task_Entries |
12350 | ||
12351 | ||
12352 | @geindex Max_Task_Entries | |
12353 | ||
12354 | [RM D.7] Specifies the maximum number of entries | |
12355 | per task. The bounds of every entry family | |
12356 | of a task unit shall be static, or shall be | |
12357 | defined by a discriminant of a subtype whose | |
12358 | corresponding bound is static. | |
12359 | ||
12360 | @node Max_Tasks,No_Abort_Statements,Max_Task_Entries,Partition-Wide Restrictions | |
9daee425 | 12361 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions max-tasks}@anchor{1c8} |
64d5610f ML |
12362 | @subsection Max_Tasks |
12363 | ||
12364 | ||
12365 | @geindex Max_Tasks | |
12366 | ||
12367 | [RM D.7] Specifies the maximum number of task that may be created, not | |
12368 | counting the creation of the environment task. Violations of this | |
12369 | restriction with a value of zero are detected at compile | |
12370 | time. Violations of this restriction with values other than zero cause | |
12371 | Storage_Error to be raised. | |
12372 | ||
12373 | @node No_Abort_Statements,No_Access_Parameter_Allocators,Max_Tasks,Partition-Wide Restrictions | |
9daee425 | 12374 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-abort-statements}@anchor{1c9} |
64d5610f ML |
12375 | @subsection No_Abort_Statements |
12376 | ||
12377 | ||
12378 | @geindex No_Abort_Statements | |
12379 | ||
12380 | [RM D.7] There are no abort_statements, and there are | |
12381 | no calls to Task_Identification.Abort_Task. | |
12382 | ||
12383 | @node No_Access_Parameter_Allocators,No_Access_Subprograms,No_Abort_Statements,Partition-Wide Restrictions | |
9daee425 | 12384 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-access-parameter-allocators}@anchor{1ca} |
64d5610f ML |
12385 | @subsection No_Access_Parameter_Allocators |
12386 | ||
12387 | ||
12388 | @geindex No_Access_Parameter_Allocators | |
12389 | ||
12390 | [RM H.4] This restriction ensures at compile time that there are no | |
12391 | occurrences of an allocator as the actual parameter to an access | |
12392 | parameter. | |
12393 | ||
12394 | @node No_Access_Subprograms,No_Allocators,No_Access_Parameter_Allocators,Partition-Wide Restrictions | |
9daee425 | 12395 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-access-subprograms}@anchor{1cb} |
64d5610f ML |
12396 | @subsection No_Access_Subprograms |
12397 | ||
12398 | ||
12399 | @geindex No_Access_Subprograms | |
12400 | ||
12401 | [RM H.4] This restriction ensures at compile time that there are no | |
12402 | declarations of access-to-subprogram types. | |
12403 | ||
12404 | @node No_Allocators,No_Anonymous_Allocators,No_Access_Subprograms,Partition-Wide Restrictions | |
9daee425 | 12405 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-allocators}@anchor{1cc} |
64d5610f ML |
12406 | @subsection No_Allocators |
12407 | ||
12408 | ||
12409 | @geindex No_Allocators | |
12410 | ||
12411 | [RM H.4] This restriction ensures at compile time that there are no | |
12412 | occurrences of an allocator. | |
12413 | ||
12414 | @node No_Anonymous_Allocators,No_Asynchronous_Control,No_Allocators,Partition-Wide Restrictions | |
9daee425 | 12415 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-anonymous-allocators}@anchor{1cd} |
64d5610f ML |
12416 | @subsection No_Anonymous_Allocators |
12417 | ||
12418 | ||
12419 | @geindex No_Anonymous_Allocators | |
12420 | ||
12421 | [RM H.4] This restriction ensures at compile time that there are no | |
12422 | occurrences of an allocator of anonymous access type. | |
12423 | ||
12424 | @node No_Asynchronous_Control,No_Calendar,No_Anonymous_Allocators,Partition-Wide Restrictions | |
9daee425 | 12425 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-asynchronous-control}@anchor{1ce} |
64d5610f ML |
12426 | @subsection No_Asynchronous_Control |
12427 | ||
12428 | ||
12429 | @geindex No_Asynchronous_Control | |
12430 | ||
12431 | [RM J.13] This restriction ensures at compile time that there are no semantic | |
12432 | dependences on the predefined package Asynchronous_Task_Control. | |
12433 | ||
12434 | @node No_Calendar,No_Coextensions,No_Asynchronous_Control,Partition-Wide Restrictions | |
9daee425 | 12435 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-calendar}@anchor{1cf} |
64d5610f ML |
12436 | @subsection No_Calendar |
12437 | ||
12438 | ||
12439 | @geindex No_Calendar | |
12440 | ||
12441 | [GNAT] This restriction ensures at compile time that there are no semantic | |
12442 | dependences on package Calendar. | |
12443 | ||
12444 | @node No_Coextensions,No_Default_Initialization,No_Calendar,Partition-Wide Restrictions | |
9daee425 | 12445 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-coextensions}@anchor{1d0} |
64d5610f ML |
12446 | @subsection No_Coextensions |
12447 | ||
12448 | ||
12449 | @geindex No_Coextensions | |
12450 | ||
12451 | [RM H.4] This restriction ensures at compile time that there are no | |
12452 | coextensions. See 3.10.2. | |
12453 | ||
12454 | @node No_Default_Initialization,No_Delay,No_Coextensions,Partition-Wide Restrictions | |
9daee425 | 12455 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-default-initialization}@anchor{1d1} |
64d5610f ML |
12456 | @subsection No_Default_Initialization |
12457 | ||
12458 | ||
12459 | @geindex No_Default_Initialization | |
12460 | ||
12461 | [GNAT] This restriction prohibits any instance of default initialization | |
12462 | of variables. The binder implements a consistency rule which prevents | |
12463 | any unit compiled without the restriction from with’ing a unit with the | |
12464 | restriction (this allows the generation of initialization procedures to | |
12465 | be skipped, since you can be sure that no call is ever generated to an | |
12466 | initialization procedure in a unit with the restriction active). If used | |
12467 | in conjunction with Initialize_Scalars or Normalize_Scalars, the effect | |
12468 | is to prohibit all cases of variables declared without a specific | |
12469 | initializer (including the case of OUT scalar parameters). | |
12470 | ||
12471 | @node No_Delay,No_Dependence,No_Default_Initialization,Partition-Wide Restrictions | |
9daee425 | 12472 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-delay}@anchor{1d2} |
64d5610f ML |
12473 | @subsection No_Delay |
12474 | ||
12475 | ||
12476 | @geindex No_Delay | |
12477 | ||
12478 | [RM H.4] This restriction ensures at compile time that there are no | |
12479 | delay statements and no semantic dependences on package Calendar. | |
12480 | ||
12481 | @node No_Dependence,No_Direct_Boolean_Operators,No_Delay,Partition-Wide Restrictions | |
9daee425 | 12482 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dependence}@anchor{1d3} |
64d5610f ML |
12483 | @subsection No_Dependence |
12484 | ||
12485 | ||
12486 | @geindex No_Dependence | |
12487 | ||
12488 | [RM 13.12.1] This restriction ensures at compile time that there are no | |
12489 | dependences on a library unit. For GNAT, this includes implicit implementation | |
12490 | dependences on units of the runtime library that are created by the compiler | |
5c6e2616 EB |
12491 | to support specific constructs of the language. Here are some examples: |
12492 | ||
12493 | ||
12494 | @itemize * | |
12495 | ||
12496 | @item | |
12497 | @code{System.Arith_64}: 64-bit arithmetics for 32-bit platforms, | |
12498 | ||
12499 | @item | |
12500 | @code{System.Arith_128}: 128-bit arithmetics for 64-bit platforms, | |
12501 | ||
12502 | @item | |
12503 | @code{System.Memory}: heap memory allocation routines, | |
12504 | ||
12505 | @item | |
12506 | @code{System.Memory_Compare}: memory comparison routine (aka @code{memcmp} for C), | |
12507 | ||
12508 | @item | |
12509 | @code{System.Memory_Copy}: memory copy routine (aka @code{memcpy} for C), | |
12510 | ||
12511 | @item | |
12512 | @code{System.Memory_Move}: memoy move routine (aka @code{memmove} for C), | |
12513 | ||
12514 | @item | |
12515 | @code{System.Memory_Set}: memory set routine (aka @code{memset} for C), | |
12516 | ||
12517 | @item | |
12518 | @code{System.Stack_Checking[.Operations]}: stack checking without MMU, | |
12519 | ||
12520 | @item | |
12521 | @code{System.GCC}: support routines from the GCC library. | |
12522 | @end itemize | |
64d5610f ML |
12523 | |
12524 | @node No_Direct_Boolean_Operators,No_Dispatch,No_Dependence,Partition-Wide Restrictions | |
9daee425 | 12525 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-direct-boolean-operators}@anchor{1d4} |
64d5610f ML |
12526 | @subsection No_Direct_Boolean_Operators |
12527 | ||
12528 | ||
12529 | @geindex No_Direct_Boolean_Operators | |
12530 | ||
12531 | [GNAT] This restriction ensures that no logical operators (and/or/xor) | |
12532 | are used on operands of type Boolean (or any type derived from Boolean). | |
12533 | This is intended for use in safety critical programs where the certification | |
12534 | protocol requires the use of short-circuit (and then, or else) forms for all | |
12535 | composite boolean operations. | |
12536 | ||
12537 | @node No_Dispatch,No_Dispatching_Calls,No_Direct_Boolean_Operators,Partition-Wide Restrictions | |
9daee425 | 12538 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dispatch}@anchor{1d5} |
64d5610f ML |
12539 | @subsection No_Dispatch |
12540 | ||
12541 | ||
12542 | @geindex No_Dispatch | |
12543 | ||
12544 | [RM H.4] This restriction ensures at compile time that there are no | |
12545 | occurrences of @code{T'Class}, for any (tagged) subtype @code{T}. | |
12546 | ||
12547 | @node No_Dispatching_Calls,No_Dynamic_Attachment,No_Dispatch,Partition-Wide Restrictions | |
9daee425 | 12548 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dispatching-calls}@anchor{1d6} |
64d5610f ML |
12549 | @subsection No_Dispatching_Calls |
12550 | ||
12551 | ||
12552 | @geindex No_Dispatching_Calls | |
12553 | ||
12554 | [GNAT] This restriction ensures at compile time that the code generated by the | |
12555 | compiler involves no dispatching calls. The use of this restriction allows the | |
12556 | safe use of record extensions, classwide membership tests and other classwide | |
12557 | features not involving implicit dispatching. This restriction ensures that | |
12558 | the code contains no indirect calls through a dispatching mechanism. Note that | |
12559 | this includes internally-generated calls created by the compiler, for example | |
12560 | in the implementation of class-wide objects assignments. The | |
12561 | membership test is allowed in the presence of this restriction, because its | |
12562 | implementation requires no dispatching. | |
12563 | This restriction is comparable to the official Ada restriction | |
12564 | @code{No_Dispatch} except that it is a bit less restrictive in that it allows | |
12565 | all classwide constructs that do not imply dispatching. | |
12566 | The following example indicates constructs that violate this restriction. | |
12567 | ||
12568 | @example | |
12569 | package Pkg is | |
12570 | type T is tagged record | |
12571 | Data : Natural; | |
12572 | end record; | |
12573 | procedure P (X : T); | |
12574 | ||
12575 | type DT is new T with record | |
12576 | More_Data : Natural; | |
12577 | end record; | |
12578 | procedure Q (X : DT); | |
12579 | end Pkg; | |
12580 | ||
12581 | with Pkg; use Pkg; | |
12582 | procedure Example is | |
12583 | procedure Test (O : T'Class) is | |
12584 | N : Natural := O'Size; -- Error: Dispatching call | |
12585 | C : T'Class := O; -- Error: implicit Dispatching Call | |
12586 | begin | |
12587 | if O in DT'Class then -- OK : Membership test | |
12588 | Q (DT (O)); -- OK : Type conversion plus direct call | |
12589 | else | |
12590 | P (O); -- Error: Dispatching call | |
12591 | end if; | |
12592 | end Test; | |
12593 | ||
12594 | Obj : DT; | |
12595 | begin | |
12596 | P (Obj); -- OK : Direct call | |
12597 | P (T (Obj)); -- OK : Type conversion plus direct call | |
12598 | P (T'Class (Obj)); -- Error: Dispatching call | |
12599 | ||
12600 | Test (Obj); -- OK : Type conversion | |
12601 | ||
12602 | if Obj in T'Class then -- OK : Membership test | |
12603 | null; | |
12604 | end if; | |
12605 | end Example; | |
12606 | @end example | |
12607 | ||
12608 | @node No_Dynamic_Attachment,No_Dynamic_Priorities,No_Dispatching_Calls,Partition-Wide Restrictions | |
9daee425 | 12609 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dynamic-attachment}@anchor{1d7} |
64d5610f ML |
12610 | @subsection No_Dynamic_Attachment |
12611 | ||
12612 | ||
12613 | @geindex No_Dynamic_Attachment | |
12614 | ||
12615 | [RM D.7] This restriction ensures that there is no call to any of the | |
12616 | operations defined in package Ada.Interrupts | |
12617 | (Is_Reserved, Is_Attached, Current_Handler, Attach_Handler, Exchange_Handler, | |
12618 | Detach_Handler, and Reference). | |
12619 | ||
12620 | @geindex No_Dynamic_Interrupts | |
12621 | ||
12622 | The restriction @code{No_Dynamic_Interrupts} is recognized as a | |
12623 | synonym for @code{No_Dynamic_Attachment}. This is retained for historical | |
12624 | compatibility purposes (and a warning will be generated for its use if | |
12625 | warnings on obsolescent features are activated). | |
12626 | ||
12627 | @node No_Dynamic_Priorities,No_Entry_Calls_In_Elaboration_Code,No_Dynamic_Attachment,Partition-Wide Restrictions | |
9daee425 | 12628 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dynamic-priorities}@anchor{1d8} |
64d5610f ML |
12629 | @subsection No_Dynamic_Priorities |
12630 | ||
12631 | ||
12632 | @geindex No_Dynamic_Priorities | |
12633 | ||
12634 | [RM D.7] There are no semantic dependencies on the package Dynamic_Priorities. | |
12635 | ||
12636 | @node No_Entry_Calls_In_Elaboration_Code,No_Enumeration_Maps,No_Dynamic_Priorities,Partition-Wide Restrictions | |
9daee425 | 12637 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-entry-calls-in-elaboration-code}@anchor{1d9} |
64d5610f ML |
12638 | @subsection No_Entry_Calls_In_Elaboration_Code |
12639 | ||
12640 | ||
12641 | @geindex No_Entry_Calls_In_Elaboration_Code | |
12642 | ||
12643 | [GNAT] This restriction ensures at compile time that no task or protected entry | |
12644 | calls are made during elaboration code. As a result of the use of this | |
12645 | restriction, the compiler can assume that no code past an accept statement | |
12646 | in a task can be executed at elaboration time. | |
12647 | ||
12648 | @node No_Enumeration_Maps,No_Exception_Handlers,No_Entry_Calls_In_Elaboration_Code,Partition-Wide Restrictions | |
9daee425 | 12649 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-enumeration-maps}@anchor{1da} |
64d5610f ML |
12650 | @subsection No_Enumeration_Maps |
12651 | ||
12652 | ||
12653 | @geindex No_Enumeration_Maps | |
12654 | ||
12655 | [GNAT] This restriction ensures at compile time that no operations requiring | |
12656 | enumeration maps are used (that is Image and Value attributes applied | |
12657 | to enumeration types). | |
12658 | ||
12659 | @node No_Exception_Handlers,No_Exception_Propagation,No_Enumeration_Maps,Partition-Wide Restrictions | |
9daee425 | 12660 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-exception-handlers}@anchor{1db} |
64d5610f ML |
12661 | @subsection No_Exception_Handlers |
12662 | ||
12663 | ||
12664 | @geindex No_Exception_Handlers | |
12665 | ||
12666 | [GNAT] This restriction ensures at compile time that there are no explicit | |
12667 | exception handlers. It also indicates that no exception propagation will | |
12668 | be provided. In this mode, exceptions may be raised but will result in | |
12669 | an immediate call to the last chance handler, a routine that the user | |
12670 | must define with the following profile: | |
12671 | ||
12672 | @example | |
12673 | procedure Last_Chance_Handler | |
12674 | (Source_Location : System.Address; Line : Integer); | |
12675 | pragma Export (C, Last_Chance_Handler, | |
12676 | "__gnat_last_chance_handler"); | |
12677 | @end example | |
12678 | ||
12679 | The parameter is a C null-terminated string representing a message to be | |
12680 | associated with the exception (typically the source location of the raise | |
12681 | statement generated by the compiler). The Line parameter when nonzero | |
12682 | represents the line number in the source program where the raise occurs. | |
12683 | ||
12684 | @node No_Exception_Propagation,No_Exception_Registration,No_Exception_Handlers,Partition-Wide Restrictions | |
9daee425 | 12685 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-exception-propagation}@anchor{1dc} |
64d5610f ML |
12686 | @subsection No_Exception_Propagation |
12687 | ||
12688 | ||
12689 | @geindex No_Exception_Propagation | |
12690 | ||
12691 | [GNAT] This restriction guarantees that exceptions are never propagated | |
12692 | to an outer subprogram scope. The only case in which an exception may | |
12693 | be raised is when the handler is statically in the same subprogram, so | |
12694 | that the effect of a raise is essentially like a goto statement. Any | |
12695 | other raise statement (implicit or explicit) will be considered | |
12696 | unhandled. Exception handlers are allowed, but may not contain an | |
12697 | exception occurrence identifier (exception choice). In addition, use of | |
12698 | the package GNAT.Current_Exception is not permitted, and reraise | |
12699 | statements (raise with no operand) are not permitted. | |
12700 | ||
12701 | @node No_Exception_Registration,No_Exceptions,No_Exception_Propagation,Partition-Wide Restrictions | |
9daee425 | 12702 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-exception-registration}@anchor{1dd} |
64d5610f ML |
12703 | @subsection No_Exception_Registration |
12704 | ||
12705 | ||
12706 | @geindex No_Exception_Registration | |
12707 | ||
12708 | [GNAT] This restriction ensures at compile time that no stream operations for | |
12709 | types Exception_Id or Exception_Occurrence are used. This also makes it | |
12710 | impossible to pass exceptions to or from a partition with this restriction | |
12711 | in a distributed environment. If this restriction is active, the generated | |
12712 | code is simplified by omitting the otherwise-required global registration | |
12713 | of exceptions when they are declared. | |
12714 | ||
12715 | @node No_Exceptions,No_Finalization,No_Exception_Registration,Partition-Wide Restrictions | |
9daee425 | 12716 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-exceptions}@anchor{1de} |
64d5610f ML |
12717 | @subsection No_Exceptions |
12718 | ||
12719 | ||
12720 | @geindex No_Exceptions | |
12721 | ||
12722 | [RM H.4] This restriction ensures at compile time that there are no | |
12723 | raise statements and no exception handlers and also suppresses the | |
12724 | generation of language-defined run-time checks. | |
12725 | ||
12726 | @node No_Finalization,No_Fixed_Point,No_Exceptions,Partition-Wide Restrictions | |
9daee425 | 12727 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-finalization}@anchor{1df} |
64d5610f ML |
12728 | @subsection No_Finalization |
12729 | ||
12730 | ||
12731 | @geindex No_Finalization | |
12732 | ||
12733 | [GNAT] This restriction disables the language features described in | |
12734 | chapter 7.6 of the Ada 2005 RM as well as all form of code generation | |
12735 | performed by the compiler to support these features. The following types | |
12736 | are no longer considered controlled when this restriction is in effect: | |
12737 | ||
12738 | ||
12739 | @itemize * | |
12740 | ||
12741 | @item | |
12742 | @code{Ada.Finalization.Controlled} | |
12743 | ||
12744 | @item | |
12745 | @code{Ada.Finalization.Limited_Controlled} | |
12746 | ||
12747 | @item | |
12748 | Derivations from @code{Controlled} or @code{Limited_Controlled} | |
12749 | ||
12750 | @item | |
12751 | Class-wide types | |
12752 | ||
12753 | @item | |
12754 | Protected types | |
12755 | ||
12756 | @item | |
12757 | Task types | |
12758 | ||
12759 | @item | |
12760 | Array and record types with controlled components | |
12761 | @end itemize | |
12762 | ||
12763 | The compiler no longer generates code to initialize, finalize or adjust an | |
12764 | object or a nested component, either declared on the stack or on the heap. The | |
12765 | deallocation of a controlled object no longer finalizes its contents. | |
12766 | ||
12767 | @node No_Fixed_Point,No_Floating_Point,No_Finalization,Partition-Wide Restrictions | |
9daee425 | 12768 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-fixed-point}@anchor{1e0} |
64d5610f ML |
12769 | @subsection No_Fixed_Point |
12770 | ||
12771 | ||
12772 | @geindex No_Fixed_Point | |
12773 | ||
12774 | [RM H.4] This restriction ensures at compile time that there are no | |
12775 | occurrences of fixed point types and operations. | |
12776 | ||
12777 | @node No_Floating_Point,No_Implicit_Conditionals,No_Fixed_Point,Partition-Wide Restrictions | |
9daee425 | 12778 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-floating-point}@anchor{1e1} |
64d5610f ML |
12779 | @subsection No_Floating_Point |
12780 | ||
12781 | ||
12782 | @geindex No_Floating_Point | |
12783 | ||
12784 | [RM H.4] This restriction ensures at compile time that there are no | |
12785 | occurrences of floating point types and operations. | |
12786 | ||
12787 | @node No_Implicit_Conditionals,No_Implicit_Dynamic_Code,No_Floating_Point,Partition-Wide Restrictions | |
9daee425 | 12788 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-conditionals}@anchor{1e2} |
64d5610f ML |
12789 | @subsection No_Implicit_Conditionals |
12790 | ||
12791 | ||
12792 | @geindex No_Implicit_Conditionals | |
12793 | ||
12794 | [GNAT] This restriction ensures that the generated code does not contain any | |
12795 | implicit conditionals, either by modifying the generated code where possible, | |
12796 | or by rejecting any construct that would otherwise generate an implicit | |
12797 | conditional. Note that this check does not include run time constraint | |
12798 | checks, which on some targets may generate implicit conditionals as | |
12799 | well. To control the latter, constraint checks can be suppressed in the | |
12800 | normal manner. Constructs generating implicit conditionals include comparisons | |
12801 | of composite objects and the Max/Min attributes. | |
12802 | ||
12803 | @node No_Implicit_Dynamic_Code,No_Implicit_Heap_Allocations,No_Implicit_Conditionals,Partition-Wide Restrictions | |
9daee425 | 12804 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-dynamic-code}@anchor{1e3} |
64d5610f ML |
12805 | @subsection No_Implicit_Dynamic_Code |
12806 | ||
12807 | ||
12808 | @geindex No_Implicit_Dynamic_Code | |
12809 | ||
12810 | @geindex trampoline | |
12811 | ||
12812 | [GNAT] This restriction prevents the compiler from building ‘trampolines’. | |
12813 | This is a structure that is built on the stack and contains dynamic | |
12814 | code to be executed at run time. On some targets, a trampoline is | |
12815 | built for the following features: @code{Access}, | |
12816 | @code{Unrestricted_Access}, or @code{Address} of a nested subprogram; | |
12817 | nested task bodies; primitive operations of nested tagged types. | |
12818 | Trampolines do not work on machines that prevent execution of stack | |
12819 | data. For example, on windows systems, enabling DEP (data execution | |
12820 | protection) will cause trampolines to raise an exception. | |
12821 | Trampolines are also quite slow at run time. | |
12822 | ||
12823 | On many targets, trampolines have been largely eliminated. Look at the | |
12824 | version of system.ads for your target — if it has | |
12825 | Always_Compatible_Rep equal to False, then trampolines are largely | |
12826 | eliminated. In particular, a trampoline is built for the following | |
12827 | features: @code{Address} of a nested subprogram; | |
12828 | @code{Access} or @code{Unrestricted_Access} of a nested subprogram, | |
12829 | but only if pragma Favor_Top_Level applies, or the access type has a | |
12830 | foreign-language convention; primitive operations of nested tagged | |
12831 | types. | |
12832 | ||
12833 | @node No_Implicit_Heap_Allocations,No_Implicit_Protected_Object_Allocations,No_Implicit_Dynamic_Code,Partition-Wide Restrictions | |
9daee425 | 12834 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-heap-allocations}@anchor{1e4} |
64d5610f ML |
12835 | @subsection No_Implicit_Heap_Allocations |
12836 | ||
12837 | ||
12838 | @geindex No_Implicit_Heap_Allocations | |
12839 | ||
12840 | [RM D.7] No constructs are allowed to cause implicit heap allocation. | |
12841 | ||
12842 | @node No_Implicit_Protected_Object_Allocations,No_Implicit_Task_Allocations,No_Implicit_Heap_Allocations,Partition-Wide Restrictions | |
9daee425 | 12843 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-protected-object-allocations}@anchor{1e5} |
64d5610f ML |
12844 | @subsection No_Implicit_Protected_Object_Allocations |
12845 | ||
12846 | ||
12847 | @geindex No_Implicit_Protected_Object_Allocations | |
12848 | ||
12849 | [GNAT] No constructs are allowed to cause implicit heap allocation of a | |
12850 | protected object. | |
12851 | ||
12852 | @node No_Implicit_Task_Allocations,No_Initialize_Scalars,No_Implicit_Protected_Object_Allocations,Partition-Wide Restrictions | |
9daee425 | 12853 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-task-allocations}@anchor{1e6} |
64d5610f ML |
12854 | @subsection No_Implicit_Task_Allocations |
12855 | ||
12856 | ||
12857 | @geindex No_Implicit_Task_Allocations | |
12858 | ||
12859 | [GNAT] No constructs are allowed to cause implicit heap allocation of a task. | |
12860 | ||
12861 | @node No_Initialize_Scalars,No_IO,No_Implicit_Task_Allocations,Partition-Wide Restrictions | |
9daee425 | 12862 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-initialize-scalars}@anchor{1e7} |
64d5610f ML |
12863 | @subsection No_Initialize_Scalars |
12864 | ||
12865 | ||
12866 | @geindex No_Initialize_Scalars | |
12867 | ||
12868 | [GNAT] This restriction ensures that no unit in the partition is compiled with | |
12869 | pragma Initialize_Scalars. This allows the generation of more efficient | |
12870 | code, and in particular eliminates dummy null initialization routines that | |
12871 | are otherwise generated for some record and array types. | |
12872 | ||
12873 | @node No_IO,No_Local_Allocators,No_Initialize_Scalars,Partition-Wide Restrictions | |
9daee425 | 12874 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-io}@anchor{1e8} |
64d5610f ML |
12875 | @subsection No_IO |
12876 | ||
12877 | ||
12878 | @geindex No_IO | |
12879 | ||
12880 | [RM H.4] This restriction ensures at compile time that there are no | |
12881 | dependences on any of the library units Sequential_IO, Direct_IO, | |
12882 | Text_IO, Wide_Text_IO, Wide_Wide_Text_IO, or Stream_IO. | |
12883 | ||
12884 | @node No_Local_Allocators,No_Local_Protected_Objects,No_IO,Partition-Wide Restrictions | |
9daee425 | 12885 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-local-allocators}@anchor{1e9} |
64d5610f ML |
12886 | @subsection No_Local_Allocators |
12887 | ||
12888 | ||
12889 | @geindex No_Local_Allocators | |
12890 | ||
12891 | [RM H.4] This restriction ensures at compile time that there are no | |
12892 | occurrences of an allocator in subprograms, generic subprograms, tasks, | |
12893 | and entry bodies. | |
12894 | ||
12895 | @node No_Local_Protected_Objects,No_Local_Tagged_Types,No_Local_Allocators,Partition-Wide Restrictions | |
9daee425 | 12896 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-local-protected-objects}@anchor{1ea} |
64d5610f ML |
12897 | @subsection No_Local_Protected_Objects |
12898 | ||
12899 | ||
12900 | @geindex No_Local_Protected_Objects | |
12901 | ||
12902 | [RM D.7] This restriction ensures at compile time that protected objects are | |
12903 | only declared at the library level. | |
12904 | ||
12905 | @node No_Local_Tagged_Types,No_Local_Timing_Events,No_Local_Protected_Objects,Partition-Wide Restrictions | |
9daee425 | 12906 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-local-tagged-types}@anchor{1eb} |
64d5610f ML |
12907 | @subsection No_Local_Tagged_Types |
12908 | ||
12909 | ||
12910 | @geindex No_Local_Tagged_Types | |
12911 | ||
12912 | [GNAT] This restriction ensures at compile time that tagged types are only | |
12913 | declared at the library level. | |
12914 | ||
12915 | @node No_Local_Timing_Events,No_Long_Long_Integers,No_Local_Tagged_Types,Partition-Wide Restrictions | |
9daee425 | 12916 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-local-timing-events}@anchor{1ec} |
64d5610f ML |
12917 | @subsection No_Local_Timing_Events |
12918 | ||
12919 | ||
12920 | @geindex No_Local_Timing_Events | |
12921 | ||
12922 | [RM D.7] All objects of type Ada.Real_Time.Timing_Events.Timing_Event are | |
12923 | declared at the library level. | |
12924 | ||
12925 | @node No_Long_Long_Integers,No_Multiple_Elaboration,No_Local_Timing_Events,Partition-Wide Restrictions | |
9daee425 | 12926 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-long-long-integers}@anchor{1ed} |
64d5610f ML |
12927 | @subsection No_Long_Long_Integers |
12928 | ||
12929 | ||
12930 | @geindex No_Long_Long_Integers | |
12931 | ||
12932 | [GNAT] This partition-wide restriction forbids any explicit reference to | |
12933 | type Standard.Long_Long_Integer, and also forbids declaring range types whose | |
12934 | implicit base type is Long_Long_Integer, and modular types whose size exceeds | |
12935 | Long_Integer’Size. | |
12936 | ||
12937 | @node No_Multiple_Elaboration,No_Nested_Finalization,No_Long_Long_Integers,Partition-Wide Restrictions | |
9daee425 | 12938 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-multiple-elaboration}@anchor{1ee} |
64d5610f ML |
12939 | @subsection No_Multiple_Elaboration |
12940 | ||
12941 | ||
12942 | @geindex No_Multiple_Elaboration | |
12943 | ||
12944 | [GNAT] When this restriction is active and the static elaboration model is | |
12945 | used, and -fpreserve-control-flow is not used, the compiler is allowed to | |
12946 | suppress the elaboration counter normally associated with the unit, even if | |
12947 | the unit has elaboration code. This counter is typically used to check for | |
12948 | access before elaboration and to control multiple elaboration attempts. If the | |
12949 | restriction is used, then the situations in which multiple elaboration is | |
12950 | possible, including non-Ada main programs and Stand Alone libraries, are not | |
12951 | permitted and will be diagnosed by the binder. | |
12952 | ||
12953 | @node No_Nested_Finalization,No_Protected_Type_Allocators,No_Multiple_Elaboration,Partition-Wide Restrictions | |
9daee425 | 12954 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-nested-finalization}@anchor{1ef} |
64d5610f ML |
12955 | @subsection No_Nested_Finalization |
12956 | ||
12957 | ||
12958 | @geindex No_Nested_Finalization | |
12959 | ||
12960 | [RM D.7] All objects requiring finalization are declared at the library level. | |
12961 | ||
12962 | @node No_Protected_Type_Allocators,No_Protected_Types,No_Nested_Finalization,Partition-Wide Restrictions | |
9daee425 | 12963 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-protected-type-allocators}@anchor{1f0} |
64d5610f ML |
12964 | @subsection No_Protected_Type_Allocators |
12965 | ||
12966 | ||
12967 | @geindex No_Protected_Type_Allocators | |
12968 | ||
12969 | [RM D.7] This restriction ensures at compile time that there are no allocator | |
12970 | expressions that attempt to allocate protected objects. | |
12971 | ||
12972 | @node No_Protected_Types,No_Recursion,No_Protected_Type_Allocators,Partition-Wide Restrictions | |
9daee425 | 12973 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-protected-types}@anchor{1f1} |
64d5610f ML |
12974 | @subsection No_Protected_Types |
12975 | ||
12976 | ||
12977 | @geindex No_Protected_Types | |
12978 | ||
12979 | [RM H.4] This restriction ensures at compile time that there are no | |
12980 | declarations of protected types or protected objects. | |
12981 | ||
12982 | @node No_Recursion,No_Reentrancy,No_Protected_Types,Partition-Wide Restrictions | |
9daee425 | 12983 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-recursion}@anchor{1f2} |
64d5610f ML |
12984 | @subsection No_Recursion |
12985 | ||
12986 | ||
12987 | @geindex No_Recursion | |
12988 | ||
12989 | [RM H.4] A program execution is erroneous if a subprogram is invoked as | |
12990 | part of its execution. | |
12991 | ||
12992 | @node No_Reentrancy,No_Relative_Delay,No_Recursion,Partition-Wide Restrictions | |
9daee425 | 12993 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-reentrancy}@anchor{1f3} |
64d5610f ML |
12994 | @subsection No_Reentrancy |
12995 | ||
12996 | ||
12997 | @geindex No_Reentrancy | |
12998 | ||
12999 | [RM H.4] A program execution is erroneous if a subprogram is executed by | |
13000 | two tasks at the same time. | |
13001 | ||
13002 | @node No_Relative_Delay,No_Requeue_Statements,No_Reentrancy,Partition-Wide Restrictions | |
9daee425 | 13003 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-relative-delay}@anchor{1f4} |
64d5610f ML |
13004 | @subsection No_Relative_Delay |
13005 | ||
13006 | ||
13007 | @geindex No_Relative_Delay | |
13008 | ||
13009 | [RM D.7] This restriction ensures at compile time that there are no delay | |
13010 | relative statements and prevents expressions such as @code{delay 1.23;} from | |
13011 | appearing in source code. | |
13012 | ||
13013 | @node No_Requeue_Statements,No_Secondary_Stack,No_Relative_Delay,Partition-Wide Restrictions | |
9daee425 | 13014 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-requeue-statements}@anchor{1f5} |
64d5610f ML |
13015 | @subsection No_Requeue_Statements |
13016 | ||
13017 | ||
13018 | @geindex No_Requeue_Statements | |
13019 | ||
13020 | [RM D.7] This restriction ensures at compile time that no requeue statements | |
13021 | are permitted and prevents keyword @code{requeue} from being used in source | |
13022 | code. | |
13023 | ||
13024 | @geindex No_Requeue | |
13025 | ||
13026 | The restriction @code{No_Requeue} is recognized as a | |
13027 | synonym for @code{No_Requeue_Statements}. This is retained for historical | |
13028 | compatibility purposes (and a warning will be generated for its use if | |
13029 | warnings on oNobsolescent features are activated). | |
13030 | ||
13031 | @node No_Secondary_Stack,No_Select_Statements,No_Requeue_Statements,Partition-Wide Restrictions | |
9daee425 | 13032 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-secondary-stack}@anchor{1f6} |
64d5610f ML |
13033 | @subsection No_Secondary_Stack |
13034 | ||
13035 | ||
13036 | @geindex No_Secondary_Stack | |
13037 | ||
13038 | [GNAT] This restriction ensures at compile time that the generated code | |
13039 | does not contain any reference to the secondary stack. The secondary | |
13040 | stack is used to implement functions returning unconstrained objects | |
13041 | (arrays or records) on some targets. Suppresses the allocation of | |
13042 | secondary stacks for tasks (excluding the environment task) at run time. | |
13043 | ||
13044 | @node No_Select_Statements,No_Specific_Termination_Handlers,No_Secondary_Stack,Partition-Wide Restrictions | |
9daee425 | 13045 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-select-statements}@anchor{1f7} |
64d5610f ML |
13046 | @subsection No_Select_Statements |
13047 | ||
13048 | ||
13049 | @geindex No_Select_Statements | |
13050 | ||
13051 | [RM D.7] This restriction ensures at compile time no select statements of any | |
13052 | kind are permitted, that is the keyword @code{select} may not appear. | |
13053 | ||
13054 | @node No_Specific_Termination_Handlers,No_Specification_of_Aspect,No_Select_Statements,Partition-Wide Restrictions | |
9daee425 | 13055 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-specific-termination-handlers}@anchor{1f8} |
64d5610f ML |
13056 | @subsection No_Specific_Termination_Handlers |
13057 | ||
13058 | ||
13059 | @geindex No_Specific_Termination_Handlers | |
13060 | ||
13061 | [RM D.7] There are no calls to Ada.Task_Termination.Set_Specific_Handler | |
13062 | or to Ada.Task_Termination.Specific_Handler. | |
13063 | ||
13064 | @node No_Specification_of_Aspect,No_Standard_Allocators_After_Elaboration,No_Specific_Termination_Handlers,Partition-Wide Restrictions | |
9daee425 | 13065 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-specification-of-aspect}@anchor{1f9} |
64d5610f ML |
13066 | @subsection No_Specification_of_Aspect |
13067 | ||
13068 | ||
13069 | @geindex No_Specification_of_Aspect | |
13070 | ||
13071 | [RM 13.12.1] This restriction checks at compile time that no aspect | |
13072 | specification, attribute definition clause, or pragma is given for a | |
13073 | given aspect. | |
13074 | ||
13075 | @node No_Standard_Allocators_After_Elaboration,No_Standard_Storage_Pools,No_Specification_of_Aspect,Partition-Wide Restrictions | |
9daee425 | 13076 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-standard-allocators-after-elaboration}@anchor{1fa} |
64d5610f ML |
13077 | @subsection No_Standard_Allocators_After_Elaboration |
13078 | ||
13079 | ||
13080 | @geindex No_Standard_Allocators_After_Elaboration | |
13081 | ||
13082 | [RM D.7] Specifies that an allocator using a standard storage pool | |
13083 | should never be evaluated at run time after the elaboration of the | |
13084 | library items of the partition has completed. Otherwise, Storage_Error | |
13085 | is raised. | |
13086 | ||
13087 | @node No_Standard_Storage_Pools,No_Stream_Optimizations,No_Standard_Allocators_After_Elaboration,Partition-Wide Restrictions | |
9daee425 | 13088 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-standard-storage-pools}@anchor{1fb} |
64d5610f ML |
13089 | @subsection No_Standard_Storage_Pools |
13090 | ||
13091 | ||
13092 | @geindex No_Standard_Storage_Pools | |
13093 | ||
13094 | [GNAT] This restriction ensures at compile time that no access types | |
13095 | use the standard default storage pool. Any access type declared must | |
13096 | have an explicit Storage_Pool attribute defined specifying a | |
13097 | user-defined storage pool. | |
13098 | ||
13099 | @node No_Stream_Optimizations,No_Streams,No_Standard_Storage_Pools,Partition-Wide Restrictions | |
9daee425 | 13100 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-stream-optimizations}@anchor{1fc} |
64d5610f ML |
13101 | @subsection No_Stream_Optimizations |
13102 | ||
13103 | ||
13104 | @geindex No_Stream_Optimizations | |
13105 | ||
13106 | [GNAT] This restriction affects the performance of stream operations on types | |
13107 | @code{String}, @code{Wide_String} and @code{Wide_Wide_String}. By default, the | |
13108 | compiler uses block reads and writes when manipulating @code{String} objects | |
13109 | due to their superior performance. When this restriction is in effect, the | |
13110 | compiler performs all IO operations on a per-character basis. | |
13111 | ||
13112 | @node No_Streams,No_Tagged_Type_Registration,No_Stream_Optimizations,Partition-Wide Restrictions | |
9daee425 | 13113 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-streams}@anchor{1fd} |
64d5610f ML |
13114 | @subsection No_Streams |
13115 | ||
13116 | ||
13117 | @geindex No_Streams | |
13118 | ||
13119 | [GNAT] This restriction ensures at compile/bind time that there are no | |
13120 | stream objects created and no use of stream attributes. | |
13121 | This restriction does not forbid dependences on the package | |
13122 | @code{Ada.Streams}. So it is permissible to with | |
13123 | @code{Ada.Streams} (or another package that does so itself) | |
13124 | as long as no actual stream objects are created and no | |
13125 | stream attributes are used. | |
13126 | ||
13127 | Note that the use of restriction allows optimization of tagged types, | |
13128 | since they do not need to worry about dispatching stream operations. | |
13129 | To take maximum advantage of this space-saving optimization, any | |
13130 | unit declaring a tagged type should be compiled with the restriction, | |
13131 | though this is not required. | |
13132 | ||
13133 | @node No_Tagged_Type_Registration,No_Task_Allocators,No_Streams,Partition-Wide Restrictions | |
9daee425 | 13134 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-tagged-type-registration}@anchor{1fe} |
64d5610f ML |
13135 | @subsection No_Tagged_Type_Registration |
13136 | ||
13137 | ||
13138 | @geindex No_Tagged_Type_Registration | |
13139 | ||
13140 | [GNAT] If this restriction is active, then class-wide streaming | |
13141 | attributes are not supported. In addition, the subprograms in | |
13142 | Ada.Tags are not supported. | |
13143 | If this restriction is active, the generated code is simplified by | |
13144 | omitting the otherwise-required global registration of tagged types when they | |
13145 | are declared. This restriction may be necessary in order to also apply | |
13146 | the No_Elaboration_Code restriction. | |
13147 | ||
13148 | @node No_Task_Allocators,No_Task_At_Interrupt_Priority,No_Tagged_Type_Registration,Partition-Wide Restrictions | |
9daee425 | 13149 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-allocators}@anchor{1ff} |
64d5610f ML |
13150 | @subsection No_Task_Allocators |
13151 | ||
13152 | ||
13153 | @geindex No_Task_Allocators | |
13154 | ||
13155 | [RM D.7] There are no allocators for task types | |
13156 | or types containing task subcomponents. | |
13157 | ||
13158 | @node No_Task_At_Interrupt_Priority,No_Task_Attributes_Package,No_Task_Allocators,Partition-Wide Restrictions | |
9daee425 | 13159 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-at-interrupt-priority}@anchor{200} |
64d5610f ML |
13160 | @subsection No_Task_At_Interrupt_Priority |
13161 | ||
13162 | ||
13163 | @geindex No_Task_At_Interrupt_Priority | |
13164 | ||
13165 | [GNAT] This restriction ensures at compile time that there is no | |
13166 | Interrupt_Priority aspect or pragma for a task or a task type. As | |
13167 | a consequence, the tasks are always created with a priority below | |
13168 | that an interrupt priority. | |
13169 | ||
13170 | @node No_Task_Attributes_Package,No_Task_Hierarchy,No_Task_At_Interrupt_Priority,Partition-Wide Restrictions | |
9daee425 | 13171 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-attributes-package}@anchor{201} |
64d5610f ML |
13172 | @subsection No_Task_Attributes_Package |
13173 | ||
13174 | ||
13175 | @geindex No_Task_Attributes_Package | |
13176 | ||
13177 | [GNAT] This restriction ensures at compile time that there are no implicit or | |
13178 | explicit dependencies on the package @code{Ada.Task_Attributes}. | |
13179 | ||
13180 | @geindex No_Task_Attributes | |
13181 | ||
13182 | The restriction @code{No_Task_Attributes} is recognized as a synonym | |
13183 | for @code{No_Task_Attributes_Package}. This is retained for historical | |
13184 | compatibility purposes (and a warning will be generated for its use if | |
13185 | warnings on obsolescent features are activated). | |
13186 | ||
13187 | @node No_Task_Hierarchy,No_Task_Termination,No_Task_Attributes_Package,Partition-Wide Restrictions | |
9daee425 | 13188 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-hierarchy}@anchor{202} |
64d5610f ML |
13189 | @subsection No_Task_Hierarchy |
13190 | ||
13191 | ||
13192 | @geindex No_Task_Hierarchy | |
13193 | ||
13194 | [RM D.7] All (non-environment) tasks depend | |
13195 | directly on the environment task of the partition. | |
13196 | ||
13197 | @node No_Task_Termination,No_Tasking,No_Task_Hierarchy,Partition-Wide Restrictions | |
9daee425 | 13198 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-termination}@anchor{203} |
64d5610f ML |
13199 | @subsection No_Task_Termination |
13200 | ||
13201 | ||
13202 | @geindex No_Task_Termination | |
13203 | ||
13204 | [RM D.7] Tasks that terminate are erroneous. | |
13205 | ||
13206 | @node No_Tasking,No_Terminate_Alternatives,No_Task_Termination,Partition-Wide Restrictions | |
9daee425 | 13207 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-tasking}@anchor{204} |
64d5610f ML |
13208 | @subsection No_Tasking |
13209 | ||
13210 | ||
13211 | @geindex No_Tasking | |
13212 | ||
13213 | [GNAT] This restriction prevents the declaration of tasks or task types | |
13214 | throughout the partition. It is similar in effect to the use of | |
13215 | @code{Max_Tasks => 0} except that violations are caught at compile time | |
13216 | and cause an error message to be output either by the compiler or | |
13217 | binder. | |
13218 | ||
13219 | @node No_Terminate_Alternatives,No_Unchecked_Access,No_Tasking,Partition-Wide Restrictions | |
9daee425 | 13220 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-terminate-alternatives}@anchor{205} |
64d5610f ML |
13221 | @subsection No_Terminate_Alternatives |
13222 | ||
13223 | ||
13224 | @geindex No_Terminate_Alternatives | |
13225 | ||
13226 | [RM D.7] There are no selective accepts with terminate alternatives. | |
13227 | ||
13228 | @node No_Unchecked_Access,No_Unchecked_Conversion,No_Terminate_Alternatives,Partition-Wide Restrictions | |
9daee425 | 13229 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-unchecked-access}@anchor{206} |
64d5610f ML |
13230 | @subsection No_Unchecked_Access |
13231 | ||
13232 | ||
13233 | @geindex No_Unchecked_Access | |
13234 | ||
13235 | [RM H.4] This restriction ensures at compile time that there are no | |
13236 | occurrences of the Unchecked_Access attribute. | |
13237 | ||
13238 | @node No_Unchecked_Conversion,No_Unchecked_Deallocation,No_Unchecked_Access,Partition-Wide Restrictions | |
9daee425 | 13239 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-unchecked-conversion}@anchor{207} |
64d5610f ML |
13240 | @subsection No_Unchecked_Conversion |
13241 | ||
13242 | ||
13243 | @geindex No_Unchecked_Conversion | |
13244 | ||
13245 | [RM J.13] This restriction ensures at compile time that there are no semantic | |
13246 | dependences on the predefined generic function Unchecked_Conversion. | |
13247 | ||
73918baf | 13248 | @node No_Unchecked_Deallocation,No_Use_Of_Attribute,No_Unchecked_Conversion,Partition-Wide Restrictions |
9daee425 | 13249 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-unchecked-deallocation}@anchor{208} |
64d5610f ML |
13250 | @subsection No_Unchecked_Deallocation |
13251 | ||
13252 | ||
13253 | @geindex No_Unchecked_Deallocation | |
13254 | ||
13255 | [RM J.13] This restriction ensures at compile time that there are no semantic | |
13256 | dependences on the predefined generic procedure Unchecked_Deallocation. | |
13257 | ||
73918baf | 13258 | @node No_Use_Of_Attribute,No_Use_Of_Entity,No_Unchecked_Deallocation,Partition-Wide Restrictions |
9daee425 | 13259 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-use-of-attribute}@anchor{209} |
73918baf VI |
13260 | @subsection No_Use_Of_Attribute |
13261 | ||
13262 | ||
13263 | @geindex No_Use_Of_Attribute | |
13264 | ||
13265 | [RM 13.12.1] This is a standard Ada 2012 restriction that is GNAT defined in | |
13266 | earlier versions of Ada. | |
13267 | ||
13268 | @node No_Use_Of_Entity,No_Use_Of_Pragma,No_Use_Of_Attribute,Partition-Wide Restrictions | |
9daee425 | 13269 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-use-of-entity}@anchor{20a} |
64d5610f ML |
13270 | @subsection No_Use_Of_Entity |
13271 | ||
13272 | ||
13273 | @geindex No_Use_Of_Entity | |
13274 | ||
13275 | [GNAT] This restriction ensures at compile time that there are no references | |
13276 | to the entity given in the form | |
13277 | ||
13278 | @example | |
13279 | No_Use_Of_Entity => Name | |
13280 | @end example | |
13281 | ||
13282 | where @code{Name} is the fully qualified entity, for example | |
13283 | ||
13284 | @example | |
13285 | No_Use_Of_Entity => Ada.Text_IO.Put_Line | |
13286 | @end example | |
13287 | ||
73918baf | 13288 | @node No_Use_Of_Pragma,Pure_Barriers,No_Use_Of_Entity,Partition-Wide Restrictions |
9daee425 | 13289 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-use-of-pragma}@anchor{20b} |
73918baf VI |
13290 | @subsection No_Use_Of_Pragma |
13291 | ||
13292 | ||
13293 | @geindex No_Use_Of_Pragma | |
13294 | ||
13295 | [RM 13.12.1] This is a standard Ada 2012 restriction that is GNAT defined in | |
13296 | earlier versions of Ada. | |
13297 | ||
13298 | @node Pure_Barriers,Simple_Barriers,No_Use_Of_Pragma,Partition-Wide Restrictions | |
9daee425 | 13299 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions pure-barriers}@anchor{20c} |
64d5610f ML |
13300 | @subsection Pure_Barriers |
13301 | ||
13302 | ||
13303 | @geindex Pure_Barriers | |
13304 | ||
13305 | [GNAT] This restriction ensures at compile time that protected entry | |
13306 | barriers are restricted to: | |
13307 | ||
13308 | ||
13309 | @itemize * | |
13310 | ||
13311 | @item | |
13312 | components of the protected object (excluding selection from dereferences), | |
13313 | ||
13314 | @item | |
13315 | constant declarations, | |
13316 | ||
13317 | @item | |
13318 | named numbers, | |
13319 | ||
13320 | @item | |
13321 | enumeration literals, | |
13322 | ||
13323 | @item | |
13324 | integer literals, | |
13325 | ||
13326 | @item | |
13327 | real literals, | |
13328 | ||
13329 | @item | |
13330 | character literals, | |
13331 | ||
13332 | @item | |
13333 | implicitly defined comparison operators, | |
13334 | ||
13335 | @item | |
13336 | uses of the Standard.”not” operator, | |
13337 | ||
13338 | @item | |
13339 | short-circuit operator, | |
13340 | ||
13341 | @item | |
13342 | the Count attribute | |
13343 | @end itemize | |
13344 | ||
13345 | This restriction is a relaxation of the Simple_Barriers restriction, | |
13346 | but still ensures absence of side effects, exceptions, and recursion | |
13347 | during the evaluation of the barriers. | |
13348 | ||
13349 | @node Simple_Barriers,Static_Priorities,Pure_Barriers,Partition-Wide Restrictions | |
9daee425 | 13350 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions simple-barriers}@anchor{20d} |
64d5610f ML |
13351 | @subsection Simple_Barriers |
13352 | ||
13353 | ||
13354 | @geindex Simple_Barriers | |
13355 | ||
13356 | [RM D.7] This restriction ensures at compile time that barriers in entry | |
13357 | declarations for protected types are restricted to either static boolean | |
13358 | expressions or references to simple boolean variables defined in the private | |
13359 | part of the protected type. No other form of entry barriers is permitted. | |
13360 | ||
13361 | @geindex Boolean_Entry_Barriers | |
13362 | ||
13363 | The restriction @code{Boolean_Entry_Barriers} is recognized as a | |
13364 | synonym for @code{Simple_Barriers}. This is retained for historical | |
13365 | compatibility purposes (and a warning will be generated for its use if | |
13366 | warnings on obsolescent features are activated). | |
13367 | ||
13368 | @node Static_Priorities,Static_Storage_Size,Simple_Barriers,Partition-Wide Restrictions | |
9daee425 | 13369 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions static-priorities}@anchor{20e} |
64d5610f ML |
13370 | @subsection Static_Priorities |
13371 | ||
13372 | ||
13373 | @geindex Static_Priorities | |
13374 | ||
13375 | [GNAT] This restriction ensures at compile time that all priority expressions | |
13376 | are static, and that there are no dependences on the package | |
13377 | @code{Ada.Dynamic_Priorities}. | |
13378 | ||
13379 | @node Static_Storage_Size,,Static_Priorities,Partition-Wide Restrictions | |
9daee425 | 13380 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions static-storage-size}@anchor{20f} |
64d5610f ML |
13381 | @subsection Static_Storage_Size |
13382 | ||
13383 | ||
13384 | @geindex Static_Storage_Size | |
13385 | ||
13386 | [GNAT] This restriction ensures at compile time that any expression appearing | |
13387 | in a Storage_Size pragma or attribute definition clause is static. | |
13388 | ||
13389 | @node Program Unit Level Restrictions,,Partition-Wide Restrictions,Standard and Implementation Defined Restrictions | |
9daee425 | 13390 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions id3}@anchor{210}@anchor{gnat_rm/standard_and_implementation_defined_restrictions program-unit-level-restrictions}@anchor{211} |
64d5610f ML |
13391 | @section Program Unit Level Restrictions |
13392 | ||
13393 | ||
13394 | The second set of restriction identifiers | |
13395 | does not require partition-wide consistency. | |
13396 | The restriction may be enforced for a single | |
13397 | compilation unit without any effect on any of the | |
13398 | other compilation units in the partition. | |
13399 | ||
13400 | @menu | |
13401 | * No_Elaboration_Code:: | |
13402 | * No_Dynamic_Accessibility_Checks:: | |
13403 | * No_Dynamic_Sized_Objects:: | |
13404 | * No_Entry_Queue:: | |
13405 | * No_Implementation_Aspect_Specifications:: | |
13406 | * No_Implementation_Attributes:: | |
13407 | * No_Implementation_Identifiers:: | |
13408 | * No_Implementation_Pragmas:: | |
13409 | * No_Implementation_Restrictions:: | |
13410 | * No_Implementation_Units:: | |
13411 | * No_Implicit_Aliasing:: | |
13412 | * No_Implicit_Loops:: | |
13413 | * No_Obsolescent_Features:: | |
13414 | * No_Wide_Characters:: | |
13415 | * Static_Dispatch_Tables:: | |
13416 | * SPARK_05:: | |
13417 | ||
13418 | @end menu | |
13419 | ||
13420 | @node No_Elaboration_Code,No_Dynamic_Accessibility_Checks,,Program Unit Level Restrictions | |
9daee425 | 13421 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-elaboration-code}@anchor{212} |
64d5610f ML |
13422 | @subsection No_Elaboration_Code |
13423 | ||
13424 | ||
13425 | @geindex No_Elaboration_Code | |
13426 | ||
13427 | [GNAT] This restriction ensures at compile time that no elaboration code is | |
13428 | generated. Note that this is not the same condition as is enforced | |
13429 | by pragma @code{Preelaborate}. There are cases in which pragma | |
13430 | @code{Preelaborate} still permits code to be generated (e.g., code | |
13431 | to initialize a large array to all zeroes), and there are cases of units | |
13432 | which do not meet the requirements for pragma @code{Preelaborate}, | |
13433 | but for which no elaboration code is generated. Generally, it is | |
13434 | the case that preelaborable units will meet the restrictions, with | |
13435 | the exception of large aggregates initialized with an others_clause, | |
13436 | and exception declarations (which generate calls to a run-time | |
13437 | registry procedure). This restriction is enforced on | |
13438 | a unit by unit basis, it need not be obeyed consistently | |
13439 | throughout a partition. | |
13440 | ||
13441 | In the case of aggregates with others, if the aggregate has a dynamic | |
13442 | size, there is no way to eliminate the elaboration code (such dynamic | |
13443 | bounds would be incompatible with @code{Preelaborate} in any case). If | |
13444 | the bounds are static, then use of this restriction actually modifies | |
13445 | the code choice of the compiler to avoid generating a loop, and instead | |
13446 | generate the aggregate statically if possible, no matter how many times | |
13447 | the data for the others clause must be repeatedly generated. | |
13448 | ||
13449 | It is not possible to precisely document | |
13450 | the constructs which are compatible with this restriction, since, | |
13451 | unlike most other restrictions, this is not a restriction on the | |
13452 | source code, but a restriction on the generated object code. For | |
13453 | example, if the source contains a declaration: | |
13454 | ||
13455 | @example | |
13456 | Val : constant Integer := X; | |
13457 | @end example | |
13458 | ||
13459 | where X is not a static constant, it may be possible, depending | |
13460 | on complex optimization circuitry, for the compiler to figure | |
13461 | out the value of X at compile time, in which case this initialization | |
13462 | can be done by the loader, and requires no initialization code. It | |
13463 | is not possible to document the precise conditions under which the | |
13464 | optimizer can figure this out. | |
13465 | ||
13466 | Note that this the implementation of this restriction requires full | |
13467 | code generation. If it is used in conjunction with “semantics only” | |
13468 | checking, then some cases of violations may be missed. | |
13469 | ||
13470 | When this restriction is active, we are not requesting control-flow | |
13471 | preservation with -fpreserve-control-flow, and the static elaboration model is | |
13472 | used, the compiler is allowed to suppress the elaboration counter normally | |
13473 | associated with the unit. This counter is typically used to check for access | |
13474 | before elaboration and to control multiple elaboration attempts. | |
13475 | ||
13476 | @node No_Dynamic_Accessibility_Checks,No_Dynamic_Sized_Objects,No_Elaboration_Code,Program Unit Level Restrictions | |
9daee425 | 13477 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dynamic-accessibility-checks}@anchor{213} |
64d5610f ML |
13478 | @subsection No_Dynamic_Accessibility_Checks |
13479 | ||
13480 | ||
13481 | @geindex No_Dynamic_Accessibility_Checks | |
13482 | ||
13483 | [GNAT] No dynamic accessibility checks are generated when this restriction is | |
13484 | in effect. Instead, dangling references are prevented via more conservative | |
13485 | compile-time checking. More specifically, existing compile-time checks are | |
13486 | enforced but with more conservative assumptions about the accessibility levels | |
13487 | of the relevant entities. These conservative assumptions eliminate the need for | |
13488 | dynamic accessibility checks. | |
13489 | ||
13490 | These new rules for computing (at compile-time) the accessibility level of an | |
13491 | anonymous access type T are as follows: | |
13492 | ||
13493 | ||
13494 | @itemize * | |
13495 | ||
13496 | @item | |
13497 | If T is a function result type then, from the caller’s perspective, its level | |
13498 | is that of the innermost master enclosing the function call. From the callee’s | |
13499 | perspective, the level of parameters and local variables of the callee is | |
13500 | statically deeper than the level of T. | |
13501 | ||
13502 | For any other accessibility level L such that the level of parameters and local | |
13503 | variables of the callee is statically deeper than L, the level of T (from the | |
13504 | callee’s perspective) is also statically deeper than L. | |
13505 | ||
13506 | @item | |
13507 | If T is the type of a formal parameter then, from the caller’s perspective, | |
13508 | its level is at least as deep as that of the type of the corresponding actual | |
13509 | parameter (whatever that actual parameter might be). From the callee’s | |
13510 | perspective, the level of parameters and local variables of the callee is | |
13511 | statically deeper than the level of T. | |
13512 | ||
13513 | @item | |
13514 | If T is the type of a discriminant then its level is that of the discriminated | |
13515 | type. | |
13516 | ||
13517 | @item | |
13518 | If T is the type of a stand-alone object then its level is the level of the | |
13519 | object. | |
13520 | ||
13521 | @item | |
13522 | In all other cases, the level of T is as defined by the existing rules of Ada. | |
13523 | @end itemize | |
13524 | ||
13525 | @node No_Dynamic_Sized_Objects,No_Entry_Queue,No_Dynamic_Accessibility_Checks,Program Unit Level Restrictions | |
9daee425 | 13526 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dynamic-sized-objects}@anchor{214} |
64d5610f ML |
13527 | @subsection No_Dynamic_Sized_Objects |
13528 | ||
13529 | ||
13530 | @geindex No_Dynamic_Sized_Objects | |
13531 | ||
13532 | [GNAT] This restriction disallows certain constructs that might lead to the | |
13533 | creation of dynamic-sized composite objects (or array or discriminated type). | |
13534 | An array subtype indication is illegal if the bounds are not static | |
13535 | or references to discriminants of an enclosing type. | |
13536 | A discriminated subtype indication is illegal if the type has | |
13537 | discriminant-dependent array components or a variant part, and the | |
13538 | discriminants are not static. In addition, array and record aggregates are | |
13539 | illegal in corresponding cases. Note that this restriction does not forbid | |
13540 | access discriminants. It is often a good idea to combine this restriction | |
13541 | with No_Secondary_Stack. | |
13542 | ||
13543 | @node No_Entry_Queue,No_Implementation_Aspect_Specifications,No_Dynamic_Sized_Objects,Program Unit Level Restrictions | |
9daee425 | 13544 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-entry-queue}@anchor{215} |
64d5610f ML |
13545 | @subsection No_Entry_Queue |
13546 | ||
13547 | ||
13548 | @geindex No_Entry_Queue | |
13549 | ||
13550 | [GNAT] This restriction is a declaration that any protected entry compiled in | |
13551 | the scope of the restriction has at most one task waiting on the entry | |
13552 | at any one time, and so no queue is required. This restriction is not | |
13553 | checked at compile time. A program execution is erroneous if an attempt | |
13554 | is made to queue a second task on such an entry. | |
13555 | ||
13556 | @node No_Implementation_Aspect_Specifications,No_Implementation_Attributes,No_Entry_Queue,Program Unit Level Restrictions | |
9daee425 | 13557 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-aspect-specifications}@anchor{216} |
64d5610f ML |
13558 | @subsection No_Implementation_Aspect_Specifications |
13559 | ||
13560 | ||
13561 | @geindex No_Implementation_Aspect_Specifications | |
13562 | ||
13563 | [RM 13.12.1] This restriction checks at compile time that no | |
13564 | GNAT-defined aspects are present. With this restriction, the only | |
13565 | aspects that can be used are those defined in the Ada Reference Manual. | |
13566 | ||
13567 | @node No_Implementation_Attributes,No_Implementation_Identifiers,No_Implementation_Aspect_Specifications,Program Unit Level Restrictions | |
9daee425 | 13568 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-attributes}@anchor{217} |
64d5610f ML |
13569 | @subsection No_Implementation_Attributes |
13570 | ||
13571 | ||
13572 | @geindex No_Implementation_Attributes | |
13573 | ||
13574 | [RM 13.12.1] This restriction checks at compile time that no | |
13575 | GNAT-defined attributes are present. With this restriction, the only | |
13576 | attributes that can be used are those defined in the Ada Reference | |
13577 | Manual. | |
13578 | ||
13579 | @node No_Implementation_Identifiers,No_Implementation_Pragmas,No_Implementation_Attributes,Program Unit Level Restrictions | |
9daee425 | 13580 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-identifiers}@anchor{218} |
64d5610f ML |
13581 | @subsection No_Implementation_Identifiers |
13582 | ||
13583 | ||
13584 | @geindex No_Implementation_Identifiers | |
13585 | ||
13586 | [RM 13.12.1] This restriction checks at compile time that no | |
13587 | implementation-defined identifiers (marked with pragma Implementation_Defined) | |
13588 | occur within language-defined packages. | |
13589 | ||
13590 | @node No_Implementation_Pragmas,No_Implementation_Restrictions,No_Implementation_Identifiers,Program Unit Level Restrictions | |
9daee425 | 13591 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-pragmas}@anchor{219} |
64d5610f ML |
13592 | @subsection No_Implementation_Pragmas |
13593 | ||
13594 | ||
13595 | @geindex No_Implementation_Pragmas | |
13596 | ||
13597 | [RM 13.12.1] This restriction checks at compile time that no | |
13598 | GNAT-defined pragmas are present. With this restriction, the only | |
13599 | pragmas that can be used are those defined in the Ada Reference Manual. | |
13600 | ||
13601 | @node No_Implementation_Restrictions,No_Implementation_Units,No_Implementation_Pragmas,Program Unit Level Restrictions | |
9daee425 | 13602 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-restrictions}@anchor{21a} |
64d5610f ML |
13603 | @subsection No_Implementation_Restrictions |
13604 | ||
13605 | ||
13606 | @geindex No_Implementation_Restrictions | |
13607 | ||
13608 | [GNAT] This restriction checks at compile time that no GNAT-defined restriction | |
13609 | identifiers (other than @code{No_Implementation_Restrictions} itself) | |
13610 | are present. With this restriction, the only other restriction identifiers | |
13611 | that can be used are those defined in the Ada Reference Manual. | |
13612 | ||
13613 | @node No_Implementation_Units,No_Implicit_Aliasing,No_Implementation_Restrictions,Program Unit Level Restrictions | |
9daee425 | 13614 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-units}@anchor{21b} |
64d5610f ML |
13615 | @subsection No_Implementation_Units |
13616 | ||
13617 | ||
13618 | @geindex No_Implementation_Units | |
13619 | ||
13620 | [RM 13.12.1] This restriction checks at compile time that there is no | |
13621 | mention in the context clause of any implementation-defined descendants | |
13622 | of packages Ada, Interfaces, or System. | |
13623 | ||
13624 | @node No_Implicit_Aliasing,No_Implicit_Loops,No_Implementation_Units,Program Unit Level Restrictions | |
9daee425 | 13625 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-aliasing}@anchor{21c} |
64d5610f ML |
13626 | @subsection No_Implicit_Aliasing |
13627 | ||
13628 | ||
13629 | @geindex No_Implicit_Aliasing | |
13630 | ||
13631 | [GNAT] This restriction, which is not required to be partition-wide consistent, | |
13632 | requires an explicit aliased keyword for an object to which ‘Access, | |
13633 | ‘Unchecked_Access, or ‘Address is applied, and forbids entirely the use of | |
13634 | the ‘Unrestricted_Access attribute for objects. Note: the reason that | |
13635 | Unrestricted_Access is forbidden is that it would require the prefix | |
13636 | to be aliased, and in such cases, it can always be replaced by | |
13637 | the standard attribute Unchecked_Access which is preferable. | |
13638 | ||
13639 | @node No_Implicit_Loops,No_Obsolescent_Features,No_Implicit_Aliasing,Program Unit Level Restrictions | |
9daee425 | 13640 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-loops}@anchor{21d} |
64d5610f ML |
13641 | @subsection No_Implicit_Loops |
13642 | ||
13643 | ||
13644 | @geindex No_Implicit_Loops | |
13645 | ||
13646 | [GNAT] This restriction ensures that the generated code of the unit marked | |
13647 | with this restriction does not contain any implicit @code{for} loops, either by | |
13648 | modifying the generated code where possible, or by rejecting any construct | |
13649 | that would otherwise generate an implicit @code{for} loop. If this restriction is | |
13650 | active, it is possible to build large array aggregates with all static | |
13651 | components without generating an intermediate temporary, and without generating | |
13652 | a loop to initialize individual components. Otherwise, a loop is created for | |
13653 | arrays larger than about 5000 scalar components. Note that if this restriction | |
13654 | is set in the spec of a package, it will not apply to its body. | |
13655 | ||
13656 | @node No_Obsolescent_Features,No_Wide_Characters,No_Implicit_Loops,Program Unit Level Restrictions | |
9daee425 | 13657 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-obsolescent-features}@anchor{21e} |
64d5610f ML |
13658 | @subsection No_Obsolescent_Features |
13659 | ||
13660 | ||
13661 | @geindex No_Obsolescent_Features | |
13662 | ||
13663 | [RM 13.12.1] This restriction checks at compile time that no obsolescent | |
13664 | features are used, as defined in Annex J of the Ada Reference Manual. | |
13665 | ||
13666 | @node No_Wide_Characters,Static_Dispatch_Tables,No_Obsolescent_Features,Program Unit Level Restrictions | |
9daee425 | 13667 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-wide-characters}@anchor{21f} |
64d5610f ML |
13668 | @subsection No_Wide_Characters |
13669 | ||
13670 | ||
13671 | @geindex No_Wide_Characters | |
13672 | ||
13673 | [GNAT] This restriction ensures at compile time that no uses of the types | |
13674 | @code{Wide_Character} or @code{Wide_String} or corresponding wide | |
13675 | wide types | |
13676 | appear, and that no wide or wide wide string or character literals | |
13677 | appear in the program (that is literals representing characters not in | |
13678 | type @code{Character}). | |
13679 | ||
13680 | @node Static_Dispatch_Tables,SPARK_05,No_Wide_Characters,Program Unit Level Restrictions | |
9daee425 | 13681 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions static-dispatch-tables}@anchor{220} |
64d5610f ML |
13682 | @subsection Static_Dispatch_Tables |
13683 | ||
13684 | ||
13685 | @geindex Static_Dispatch_Tables | |
13686 | ||
13687 | [GNAT] This restriction checks at compile time that all the artifacts | |
13688 | associated with dispatch tables can be placed in read-only memory. | |
13689 | ||
13690 | @node SPARK_05,,Static_Dispatch_Tables,Program Unit Level Restrictions | |
9daee425 | 13691 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions spark-05}@anchor{221} |
64d5610f ML |
13692 | @subsection SPARK_05 |
13693 | ||
13694 | ||
13695 | @geindex SPARK_05 | |
13696 | ||
13697 | [GNAT] This restriction no longer has any effect and is superseded by | |
13698 | SPARK 2014, whose restrictions are checked by the tool GNATprove. To check that | |
13699 | a codebase respects SPARK 2014 restrictions, mark the code with pragma or | |
13700 | aspect @code{SPARK_Mode}, and run the tool GNATprove at Stone assurance level, as | |
13701 | follows: | |
13702 | ||
13703 | @example | |
13704 | gnatprove -P project.gpr --mode=stone | |
13705 | @end example | |
13706 | ||
13707 | or equivalently: | |
13708 | ||
13709 | @example | |
13710 | gnatprove -P project.gpr --mode=check_all | |
13711 | @end example | |
13712 | ||
13713 | @node Implementation Advice,Implementation Defined Characteristics,Standard and Implementation Defined Restrictions,Top | |
9daee425 | 13714 | @anchor{gnat_rm/implementation_advice doc}@anchor{222}@anchor{gnat_rm/implementation_advice id1}@anchor{223}@anchor{gnat_rm/implementation_advice implementation-advice}@anchor{a} |
64d5610f ML |
13715 | @chapter Implementation Advice |
13716 | ||
13717 | ||
13718 | The main text of the Ada Reference Manual describes the required | |
13719 | behavior of all Ada compilers, and the GNAT compiler conforms to | |
13720 | these requirements. | |
13721 | ||
13722 | In addition, there are sections throughout the Ada Reference Manual headed | |
13723 | by the phrase ‘Implementation advice’. These sections are not normative, | |
13724 | i.e., they do not specify requirements that all compilers must | |
13725 | follow. Rather they provide advice on generally desirable behavior. | |
13726 | They are not requirements, because they describe behavior that cannot | |
13727 | be provided on all systems, or may be undesirable on some systems. | |
13728 | ||
13729 | As far as practical, GNAT follows the implementation advice in | |
13730 | the Ada Reference Manual. Each such RM section corresponds to a section | |
13731 | in this chapter whose title specifies the | |
13732 | RM section number and paragraph number and the subject of | |
13733 | the advice. The contents of each section consists of the RM text within | |
13734 | quotation marks, | |
13735 | followed by the GNAT interpretation of the advice. Most often, this simply says | |
13736 | ‘followed’, which means that GNAT follows the advice. However, in a | |
13737 | number of cases, GNAT deliberately deviates from this advice, in which | |
13738 | case the text describes what GNAT does and why. | |
13739 | ||
13740 | @geindex Error detection | |
13741 | ||
13742 | @menu | |
13743 | * RM 1.1.3(20); Error Detection: RM 1 1 3 20 Error Detection. | |
13744 | * RM 1.1.3(31); Child Units: RM 1 1 3 31 Child Units. | |
13745 | * RM 1.1.5(12); Bounded Errors: RM 1 1 5 12 Bounded Errors. | |
13746 | * RM 2.8(16); Pragmas: RM 2 8 16 Pragmas. | |
13747 | * RM 2.8(17-19); Pragmas: RM 2 8 17-19 Pragmas. | |
13748 | * RM 3.5.2(5); Alternative Character Sets: RM 3 5 2 5 Alternative Character Sets. | |
13749 | * RM 3.5.4(28); Integer Types: RM 3 5 4 28 Integer Types. | |
13750 | * RM 3.5.4(29); Integer Types: RM 3 5 4 29 Integer Types. | |
13751 | * RM 3.5.5(8); Enumeration Values: RM 3 5 5 8 Enumeration Values. | |
13752 | * RM 3.5.7(17); Float Types: RM 3 5 7 17 Float Types. | |
13753 | * RM 3.6.2(11); Multidimensional Arrays: RM 3 6 2 11 Multidimensional Arrays. | |
13754 | * RM 9.6(30-31); Duration’Small: RM 9 6 30-31 Duration’Small. | |
13755 | * RM 10.2.1(12); Consistent Representation: RM 10 2 1 12 Consistent Representation. | |
13756 | * RM 11.4.1(19); Exception Information: RM 11 4 1 19 Exception Information. | |
13757 | * RM 11.5(28); Suppression of Checks: RM 11 5 28 Suppression of Checks. | |
13758 | * RM 13.1 (21-24); Representation Clauses: RM 13 1 21-24 Representation Clauses. | |
13759 | * RM 13.2(6-8); Packed Types: RM 13 2 6-8 Packed Types. | |
13760 | * RM 13.3(14-19); Address Clauses: RM 13 3 14-19 Address Clauses. | |
13761 | * RM 13.3(29-35); Alignment Clauses: RM 13 3 29-35 Alignment Clauses. | |
13762 | * RM 13.3(42-43); Size Clauses: RM 13 3 42-43 Size Clauses. | |
13763 | * RM 13.3(50-56); Size Clauses: RM 13 3 50-56 Size Clauses. | |
13764 | * RM 13.3(71-73); Component Size Clauses: RM 13 3 71-73 Component Size Clauses. | |
13765 | * RM 13.4(9-10); Enumeration Representation Clauses: RM 13 4 9-10 Enumeration Representation Clauses. | |
13766 | * RM 13.5.1(17-22); Record Representation Clauses: RM 13 5 1 17-22 Record Representation Clauses. | |
13767 | * RM 13.5.2(5); Storage Place Attributes: RM 13 5 2 5 Storage Place Attributes. | |
13768 | * RM 13.5.3(7-8); Bit Ordering: RM 13 5 3 7-8 Bit Ordering. | |
13769 | * RM 13.7(37); Address as Private: RM 13 7 37 Address as Private. | |
13770 | * RM 13.7.1(16); Address Operations: RM 13 7 1 16 Address Operations. | |
13771 | * RM 13.9(14-17); Unchecked Conversion: RM 13 9 14-17 Unchecked Conversion. | |
13772 | * RM 13.11(23-25); Implicit Heap Usage: RM 13 11 23-25 Implicit Heap Usage. | |
13773 | * RM 13.11.2(17); Unchecked Deallocation: RM 13 11 2 17 Unchecked Deallocation. | |
13774 | * RM 13.13.2(1.6); Stream Oriented Attributes: RM 13 13 2 1 6 Stream Oriented Attributes. | |
13775 | * RM A.1(52); Names of Predefined Numeric Types: RM A 1 52 Names of Predefined Numeric Types. | |
13776 | * RM A.3.2(49); Ada.Characters.Handling: RM A 3 2 49 Ada Characters Handling. | |
13777 | * RM A.4.4(106); Bounded-Length String Handling: RM A 4 4 106 Bounded-Length String Handling. | |
13778 | * RM A.5.2(46-47); Random Number Generation: RM A 5 2 46-47 Random Number Generation. | |
13779 | * RM A.10.7(23); Get_Immediate: RM A 10 7 23 Get_Immediate. | |
13780 | * RM A.18; Containers: RM A 18 Containers. | |
13781 | * RM B.1(39-41); Pragma Export: RM B 1 39-41 Pragma Export. | |
13782 | * RM B.2(12-13); Package Interfaces: RM B 2 12-13 Package Interfaces. | |
13783 | * RM B.3(63-71); Interfacing with C: RM B 3 63-71 Interfacing with C. | |
13784 | * RM B.4(95-98); Interfacing with COBOL: RM B 4 95-98 Interfacing with COBOL. | |
13785 | * RM B.5(22-26); Interfacing with Fortran: RM B 5 22-26 Interfacing with Fortran. | |
13786 | * RM C.1(3-5); Access to Machine Operations: RM C 1 3-5 Access to Machine Operations. | |
13787 | * RM C.1(10-16); Access to Machine Operations: RM C 1 10-16 Access to Machine Operations. | |
13788 | * RM C.3(28); Interrupt Support: RM C 3 28 Interrupt Support. | |
13789 | * RM C.3.1(20-21); Protected Procedure Handlers: RM C 3 1 20-21 Protected Procedure Handlers. | |
13790 | * RM C.3.2(25); Package Interrupts: RM C 3 2 25 Package Interrupts. | |
13791 | * RM C.4(14); Pre-elaboration Requirements: RM C 4 14 Pre-elaboration Requirements. | |
13792 | * RM C.5(8); Pragma Discard_Names: RM C 5 8 Pragma Discard_Names. | |
13793 | * RM C.7.2(30); The Package Task_Attributes: RM C 7 2 30 The Package Task_Attributes. | |
13794 | * RM D.3(17); Locking Policies: RM D 3 17 Locking Policies. | |
13795 | * RM D.4(16); Entry Queuing Policies: RM D 4 16 Entry Queuing Policies. | |
13796 | * RM D.6(9-10); Preemptive Abort: RM D 6 9-10 Preemptive Abort. | |
13797 | * RM D.7(21); Tasking Restrictions: RM D 7 21 Tasking Restrictions. | |
13798 | * RM D.8(47-49); Monotonic Time: RM D 8 47-49 Monotonic Time. | |
13799 | * RM E.5(28-29); Partition Communication Subsystem: RM E 5 28-29 Partition Communication Subsystem. | |
13800 | * RM F(7); COBOL Support: RM F 7 COBOL Support. | |
13801 | * RM F.1(2); Decimal Radix Support: RM F 1 2 Decimal Radix Support. | |
13802 | * RM G; Numerics: RM G Numerics. | |
13803 | * RM G.1.1(56-58); Complex Types: RM G 1 1 56-58 Complex Types. | |
13804 | * RM G.1.2(49); Complex Elementary Functions: RM G 1 2 49 Complex Elementary Functions. | |
13805 | * RM G.2.4(19); Accuracy Requirements: RM G 2 4 19 Accuracy Requirements. | |
13806 | * RM G.2.6(15); Complex Arithmetic Accuracy: RM G 2 6 15 Complex Arithmetic Accuracy. | |
13807 | * RM H.6(15/2); Pragma Partition_Elaboration_Policy: RM H 6 15/2 Pragma Partition_Elaboration_Policy. | |
13808 | ||
13809 | @end menu | |
13810 | ||
13811 | @node RM 1 1 3 20 Error Detection,RM 1 1 3 31 Child Units,,Implementation Advice | |
9daee425 | 13812 | @anchor{gnat_rm/implementation_advice rm-1-1-3-20-error-detection}@anchor{224} |
64d5610f ML |
13813 | @section RM 1.1.3(20): Error Detection |
13814 | ||
13815 | ||
13816 | @quotation | |
13817 | ||
13818 | “If an implementation detects the use of an unsupported Specialized Needs | |
13819 | Annex feature at run time, it should raise @code{Program_Error} if | |
13820 | feasible.” | |
13821 | @end quotation | |
13822 | ||
13823 | Not relevant. All specialized needs annex features are either supported, | |
13824 | or diagnosed at compile time. | |
13825 | ||
13826 | @geindex Child Units | |
13827 | ||
13828 | @node RM 1 1 3 31 Child Units,RM 1 1 5 12 Bounded Errors,RM 1 1 3 20 Error Detection,Implementation Advice | |
9daee425 | 13829 | @anchor{gnat_rm/implementation_advice rm-1-1-3-31-child-units}@anchor{225} |
64d5610f ML |
13830 | @section RM 1.1.3(31): Child Units |
13831 | ||
13832 | ||
13833 | @quotation | |
13834 | ||
13835 | “If an implementation wishes to provide implementation-defined | |
13836 | extensions to the functionality of a language-defined library unit, it | |
13837 | should normally do so by adding children to the library unit.” | |
13838 | @end quotation | |
13839 | ||
13840 | Followed. | |
13841 | ||
13842 | @geindex Bounded errors | |
13843 | ||
13844 | @node RM 1 1 5 12 Bounded Errors,RM 2 8 16 Pragmas,RM 1 1 3 31 Child Units,Implementation Advice | |
9daee425 | 13845 | @anchor{gnat_rm/implementation_advice rm-1-1-5-12-bounded-errors}@anchor{226} |
64d5610f ML |
13846 | @section RM 1.1.5(12): Bounded Errors |
13847 | ||
13848 | ||
13849 | @quotation | |
13850 | ||
13851 | “If an implementation detects a bounded error or erroneous | |
13852 | execution, it should raise @code{Program_Error}.” | |
13853 | @end quotation | |
13854 | ||
13855 | Followed in all cases in which the implementation detects a bounded | |
13856 | error or erroneous execution. Not all such situations are detected at | |
13857 | runtime. | |
13858 | ||
13859 | @geindex Pragmas | |
13860 | ||
13861 | @node RM 2 8 16 Pragmas,RM 2 8 17-19 Pragmas,RM 1 1 5 12 Bounded Errors,Implementation Advice | |
9daee425 | 13862 | @anchor{gnat_rm/implementation_advice id2}@anchor{227}@anchor{gnat_rm/implementation_advice rm-2-8-16-pragmas}@anchor{228} |
64d5610f ML |
13863 | @section RM 2.8(16): Pragmas |
13864 | ||
13865 | ||
13866 | @quotation | |
13867 | ||
13868 | “Normally, implementation-defined pragmas should have no semantic effect | |
13869 | for error-free programs; that is, if the implementation-defined pragmas | |
13870 | are removed from a working program, the program should still be legal, | |
13871 | and should still have the same semantics.” | |
13872 | @end quotation | |
13873 | ||
13874 | The following implementation defined pragmas are exceptions to this | |
13875 | rule: | |
13876 | ||
13877 | ||
13878 | @multitable {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxx} | |
13879 | @headitem | |
13880 | ||
13881 | Pragma | |
13882 | ||
13883 | @tab | |
13884 | ||
13885 | Explanation | |
13886 | ||
13887 | @item | |
13888 | ||
1acce141 | 13889 | @emph{Abort_Defer} |
64d5610f ML |
13890 | |
13891 | @tab | |
13892 | ||
13893 | Affects semantics | |
13894 | ||
13895 | @item | |
13896 | ||
1acce141 | 13897 | @emph{Ada_83} |
64d5610f ML |
13898 | |
13899 | @tab | |
13900 | ||
13901 | Affects legality | |
13902 | ||
13903 | @item | |
13904 | ||
1acce141 | 13905 | @emph{Assert} |
64d5610f ML |
13906 | |
13907 | @tab | |
13908 | ||
13909 | Affects semantics | |
13910 | ||
13911 | @item | |
13912 | ||
1acce141 | 13913 | @emph{CPP_Class} |
64d5610f ML |
13914 | |
13915 | @tab | |
13916 | ||
13917 | Affects semantics | |
13918 | ||
13919 | @item | |
13920 | ||
1acce141 | 13921 | @emph{CPP_Constructor} |
64d5610f ML |
13922 | |
13923 | @tab | |
13924 | ||
13925 | Affects semantics | |
13926 | ||
13927 | @item | |
13928 | ||
1acce141 | 13929 | @emph{Debug} |
64d5610f ML |
13930 | |
13931 | @tab | |
13932 | ||
13933 | Affects semantics | |
13934 | ||
13935 | @item | |
13936 | ||
1acce141 | 13937 | @emph{Interface_Name} |
64d5610f ML |
13938 | |
13939 | @tab | |
13940 | ||
13941 | Affects semantics | |
13942 | ||
13943 | @item | |
13944 | ||
1acce141 | 13945 | @emph{Machine_Attribute} |
64d5610f ML |
13946 | |
13947 | @tab | |
13948 | ||
13949 | Affects semantics | |
13950 | ||
13951 | @item | |
13952 | ||
1acce141 | 13953 | @emph{Unimplemented_Unit} |
64d5610f ML |
13954 | |
13955 | @tab | |
13956 | ||
13957 | Affects legality | |
13958 | ||
13959 | @item | |
13960 | ||
1acce141 | 13961 | @emph{Unchecked_Union} |
64d5610f ML |
13962 | |
13963 | @tab | |
13964 | ||
13965 | Affects semantics | |
13966 | ||
13967 | @end multitable | |
13968 | ||
13969 | ||
13970 | In each of the above cases, it is essential to the purpose of the pragma | |
13971 | that this advice not be followed. For details see | |
13972 | @ref{7,,Implementation Defined Pragmas}. | |
13973 | ||
13974 | @node RM 2 8 17-19 Pragmas,RM 3 5 2 5 Alternative Character Sets,RM 2 8 16 Pragmas,Implementation Advice | |
9daee425 | 13975 | @anchor{gnat_rm/implementation_advice rm-2-8-17-19-pragmas}@anchor{229} |
64d5610f ML |
13976 | @section RM 2.8(17-19): Pragmas |
13977 | ||
13978 | ||
13979 | @quotation | |
13980 | ||
13981 | “Normally, an implementation should not define pragmas that can | |
13982 | make an illegal program legal, except as follows: | |
13983 | ||
13984 | ||
13985 | @itemize * | |
13986 | ||
13987 | @item | |
13988 | A pragma used to complete a declaration, such as a pragma @code{Import}; | |
13989 | ||
13990 | @item | |
13991 | A pragma used to configure the environment by adding, removing, or | |
13992 | replacing @code{library_items}.” | |
13993 | @end itemize | |
13994 | @end quotation | |
13995 | ||
9daee425 | 13996 | See @ref{228,,RM 2.8(16); Pragmas}. |
64d5610f ML |
13997 | |
13998 | @geindex Character Sets | |
13999 | ||
14000 | @geindex Alternative Character Sets | |
14001 | ||
14002 | @node RM 3 5 2 5 Alternative Character Sets,RM 3 5 4 28 Integer Types,RM 2 8 17-19 Pragmas,Implementation Advice | |
9daee425 | 14003 | @anchor{gnat_rm/implementation_advice rm-3-5-2-5-alternative-character-sets}@anchor{22a} |
64d5610f ML |
14004 | @section RM 3.5.2(5): Alternative Character Sets |
14005 | ||
14006 | ||
14007 | @quotation | |
14008 | ||
14009 | “If an implementation supports a mode with alternative interpretations | |
14010 | for @code{Character} and @code{Wide_Character}, the set of graphic | |
14011 | characters of @code{Character} should nevertheless remain a proper | |
14012 | subset of the set of graphic characters of @code{Wide_Character}. Any | |
14013 | character set ‘localizations’ should be reflected in the results of | |
14014 | the subprograms defined in the language-defined package | |
14015 | @code{Characters.Handling} (see A.3) available in such a mode. In a mode with | |
14016 | an alternative interpretation of @code{Character}, the implementation should | |
14017 | also support a corresponding change in what is a legal | |
14018 | @code{identifier_letter}.” | |
14019 | @end quotation | |
14020 | ||
14021 | Not all wide character modes follow this advice, in particular the JIS | |
14022 | and IEC modes reflect standard usage in Japan, and in these encoding, | |
14023 | the upper half of the Latin-1 set is not part of the wide-character | |
14024 | subset, since the most significant bit is used for wide character | |
14025 | encoding. However, this only applies to the external forms. Internally | |
14026 | there is no such restriction. | |
14027 | ||
14028 | @geindex Integer types | |
14029 | ||
14030 | @node RM 3 5 4 28 Integer Types,RM 3 5 4 29 Integer Types,RM 3 5 2 5 Alternative Character Sets,Implementation Advice | |
9daee425 | 14031 | @anchor{gnat_rm/implementation_advice rm-3-5-4-28-integer-types}@anchor{22b} |
64d5610f ML |
14032 | @section RM 3.5.4(28): Integer Types |
14033 | ||
14034 | ||
14035 | @quotation | |
14036 | ||
14037 | “An implementation should support @code{Long_Integer} in addition to | |
14038 | @code{Integer} if the target machine supports 32-bit (or longer) | |
14039 | arithmetic. No other named integer subtypes are recommended for package | |
14040 | @code{Standard}. Instead, appropriate named integer subtypes should be | |
14041 | provided in the library package @code{Interfaces} (see B.2).” | |
14042 | @end quotation | |
14043 | ||
14044 | @code{Long_Integer} is supported. Other standard integer types are supported | |
14045 | so this advice is not fully followed. These types | |
14046 | are supported for convenient interface to C, and so that all hardware | |
14047 | types of the machine are easily available. | |
14048 | ||
14049 | @node RM 3 5 4 29 Integer Types,RM 3 5 5 8 Enumeration Values,RM 3 5 4 28 Integer Types,Implementation Advice | |
9daee425 | 14050 | @anchor{gnat_rm/implementation_advice rm-3-5-4-29-integer-types}@anchor{22c} |
64d5610f ML |
14051 | @section RM 3.5.4(29): Integer Types |
14052 | ||
14053 | ||
14054 | @quotation | |
14055 | ||
14056 | “An implementation for a two’s complement machine should support | |
14057 | modular types with a binary modulus up to @code{System.Max_Int*2+2}. An | |
14058 | implementation should support a non-binary modules up to @code{Integer'Last}.” | |
14059 | @end quotation | |
14060 | ||
14061 | Followed. | |
14062 | ||
14063 | @geindex Enumeration values | |
14064 | ||
14065 | @node RM 3 5 5 8 Enumeration Values,RM 3 5 7 17 Float Types,RM 3 5 4 29 Integer Types,Implementation Advice | |
9daee425 | 14066 | @anchor{gnat_rm/implementation_advice rm-3-5-5-8-enumeration-values}@anchor{22d} |
64d5610f ML |
14067 | @section RM 3.5.5(8): Enumeration Values |
14068 | ||
14069 | ||
14070 | @quotation | |
14071 | ||
14072 | “For the evaluation of a call on @code{S'Pos} for an enumeration | |
14073 | subtype, if the value of the operand does not correspond to the internal | |
14074 | code for any enumeration literal of its type (perhaps due to an | |
14075 | un-initialized variable), then the implementation should raise | |
14076 | @code{Program_Error}. This is particularly important for enumeration | |
14077 | types with noncontiguous internal codes specified by an | |
14078 | enumeration_representation_clause.” | |
14079 | @end quotation | |
14080 | ||
14081 | Followed. | |
14082 | ||
14083 | @geindex Float types | |
14084 | ||
14085 | @node RM 3 5 7 17 Float Types,RM 3 6 2 11 Multidimensional Arrays,RM 3 5 5 8 Enumeration Values,Implementation Advice | |
9daee425 | 14086 | @anchor{gnat_rm/implementation_advice rm-3-5-7-17-float-types}@anchor{22e} |
64d5610f ML |
14087 | @section RM 3.5.7(17): Float Types |
14088 | ||
14089 | ||
14090 | @quotation | |
14091 | ||
14092 | “An implementation should support @code{Long_Float} in addition to | |
14093 | @code{Float} if the target machine supports 11 or more digits of | |
14094 | precision. No other named floating point subtypes are recommended for | |
14095 | package @code{Standard}. Instead, appropriate named floating point subtypes | |
14096 | should be provided in the library package @code{Interfaces} (see B.2).” | |
14097 | @end quotation | |
14098 | ||
14099 | @code{Short_Float} and @code{Long_Long_Float} are also provided. The | |
14100 | former provides improved compatibility with other implementations | |
14101 | supporting this type. The latter corresponds to the highest precision | |
14102 | floating-point type supported by the hardware. On most machines, this | |
14103 | will be the same as @code{Long_Float}, but on some machines, it will | |
14104 | correspond to the IEEE extended form. The notable case is all x86 | |
14105 | implementations, where @code{Long_Long_Float} corresponds to the 80-bit | |
14106 | extended precision format supported in hardware on this processor. | |
14107 | Note that the 128-bit format on SPARC is not supported, since this | |
14108 | is a software rather than a hardware format. | |
14109 | ||
14110 | @geindex Multidimensional arrays | |
14111 | ||
14112 | @geindex Arrays | |
14113 | @geindex multidimensional | |
14114 | ||
14115 | @node RM 3 6 2 11 Multidimensional Arrays,RM 9 6 30-31 Duration’Small,RM 3 5 7 17 Float Types,Implementation Advice | |
9daee425 | 14116 | @anchor{gnat_rm/implementation_advice rm-3-6-2-11-multidimensional-arrays}@anchor{22f} |
64d5610f ML |
14117 | @section RM 3.6.2(11): Multidimensional Arrays |
14118 | ||
14119 | ||
14120 | @quotation | |
14121 | ||
14122 | “An implementation should normally represent multidimensional arrays in | |
14123 | row-major order, consistent with the notation used for multidimensional | |
14124 | array aggregates (see 4.3.3). However, if a pragma @code{Convention} | |
14125 | (@code{Fortran}, …) applies to a multidimensional array type, then | |
1acce141 | 14126 | column-major order should be used instead (see B.5, @emph{Interfacing with Fortran}).” |
64d5610f ML |
14127 | @end quotation |
14128 | ||
14129 | Followed. | |
14130 | ||
14131 | @geindex Duration'Small | |
14132 | ||
14133 | @node RM 9 6 30-31 Duration’Small,RM 10 2 1 12 Consistent Representation,RM 3 6 2 11 Multidimensional Arrays,Implementation Advice | |
9daee425 | 14134 | @anchor{gnat_rm/implementation_advice rm-9-6-30-31-duration-small}@anchor{230} |
64d5610f ML |
14135 | @section RM 9.6(30-31): Duration’Small |
14136 | ||
14137 | ||
14138 | @quotation | |
14139 | ||
14140 | “Whenever possible in an implementation, the value of @code{Duration'Small} | |
14141 | should be no greater than 100 microseconds.” | |
14142 | @end quotation | |
14143 | ||
14144 | Followed. (@code{Duration'Small} = 10**(-9)). | |
14145 | ||
14146 | @quotation | |
14147 | ||
14148 | “The time base for @code{delay_relative_statements} should be monotonic; | |
14149 | it need not be the same time base as used for @code{Calendar.Clock}.” | |
14150 | @end quotation | |
14151 | ||
14152 | Followed. | |
14153 | ||
14154 | @node RM 10 2 1 12 Consistent Representation,RM 11 4 1 19 Exception Information,RM 9 6 30-31 Duration’Small,Implementation Advice | |
9daee425 | 14155 | @anchor{gnat_rm/implementation_advice rm-10-2-1-12-consistent-representation}@anchor{231} |
64d5610f ML |
14156 | @section RM 10.2.1(12): Consistent Representation |
14157 | ||
14158 | ||
14159 | @quotation | |
14160 | ||
14161 | “In an implementation, a type declared in a pre-elaborated package should | |
14162 | have the same representation in every elaboration of a given version of | |
14163 | the package, whether the elaborations occur in distinct executions of | |
14164 | the same program, or in executions of distinct programs or partitions | |
14165 | that include the given version.” | |
14166 | @end quotation | |
14167 | ||
14168 | Followed, except in the case of tagged types. Tagged types involve | |
14169 | implicit pointers to a local copy of a dispatch table, and these pointers | |
14170 | have representations which thus depend on a particular elaboration of the | |
14171 | package. It is not easy to see how it would be possible to follow this | |
14172 | advice without severely impacting efficiency of execution. | |
14173 | ||
14174 | @geindex Exception information | |
14175 | ||
14176 | @node RM 11 4 1 19 Exception Information,RM 11 5 28 Suppression of Checks,RM 10 2 1 12 Consistent Representation,Implementation Advice | |
9daee425 | 14177 | @anchor{gnat_rm/implementation_advice rm-11-4-1-19-exception-information}@anchor{232} |
64d5610f ML |
14178 | @section RM 11.4.1(19): Exception Information |
14179 | ||
14180 | ||
14181 | @quotation | |
14182 | ||
14183 | “@code{Exception_Message} by default and @code{Exception_Information} | |
14184 | should produce information useful for | |
14185 | debugging. @code{Exception_Message} should be short, about one | |
14186 | line. @code{Exception_Information} can be long. @code{Exception_Message} | |
14187 | should not include the | |
14188 | @code{Exception_Name}. @code{Exception_Information} should include both | |
14189 | the @code{Exception_Name} and the @code{Exception_Message}.” | |
14190 | @end quotation | |
14191 | ||
14192 | Followed. For each exception that doesn’t have a specified | |
14193 | @code{Exception_Message}, the compiler generates one containing the location | |
14194 | of the raise statement. This location has the form ‘file_name:line’, where | |
14195 | file_name is the short file name (without path information) and line is the line | |
14196 | number in the file. Note that in the case of the Zero Cost Exception | |
14197 | mechanism, these messages become redundant with the Exception_Information that | |
14198 | contains a full backtrace of the calling sequence, so they are disabled. | |
14199 | To disable explicitly the generation of the source location message, use the | |
14200 | Pragma @code{Discard_Names}. | |
14201 | ||
14202 | @geindex Suppression of checks | |
14203 | ||
14204 | @geindex Checks | |
14205 | @geindex suppression of | |
14206 | ||
14207 | @node RM 11 5 28 Suppression of Checks,RM 13 1 21-24 Representation Clauses,RM 11 4 1 19 Exception Information,Implementation Advice | |
9daee425 | 14208 | @anchor{gnat_rm/implementation_advice rm-11-5-28-suppression-of-checks}@anchor{233} |
64d5610f ML |
14209 | @section RM 11.5(28): Suppression of Checks |
14210 | ||
14211 | ||
14212 | @quotation | |
14213 | ||
14214 | “The implementation should minimize the code executed for checks that | |
14215 | have been suppressed.” | |
14216 | @end quotation | |
14217 | ||
14218 | Followed. | |
14219 | ||
14220 | @geindex Representation clauses | |
14221 | ||
14222 | @node RM 13 1 21-24 Representation Clauses,RM 13 2 6-8 Packed Types,RM 11 5 28 Suppression of Checks,Implementation Advice | |
9daee425 | 14223 | @anchor{gnat_rm/implementation_advice rm-13-1-21-24-representation-clauses}@anchor{234} |
64d5610f ML |
14224 | @section RM 13.1 (21-24): Representation Clauses |
14225 | ||
14226 | ||
14227 | @quotation | |
14228 | ||
14229 | “The recommended level of support for all representation items is | |
14230 | qualified as follows: | |
14231 | ||
14232 | An implementation need not support representation items containing | |
14233 | nonstatic expressions, except that an implementation should support a | |
14234 | representation item for a given entity if each nonstatic expression in | |
14235 | the representation item is a name that statically denotes a constant | |
14236 | declared before the entity.” | |
14237 | @end quotation | |
14238 | ||
14239 | Followed. In fact, GNAT goes beyond the recommended level of support | |
14240 | by allowing nonstatic expressions in some representation clauses even | |
14241 | without the need to declare constants initialized with the values of | |
14242 | such expressions. | |
14243 | For example: | |
14244 | ||
14245 | @example | |
14246 | X : Integer; | |
14247 | Y : Float; | |
14248 | for Y'Address use X'Address;>> | |
14249 | ||
14250 | ||
14251 | "An implementation need not support a specification for the `@w{`}Size`@w{`} | |
14252 | for a given composite subtype, nor the size or storage place for an | |
14253 | object (including a component) of a given composite subtype, unless the | |
14254 | constraints on the subtype and its composite subcomponents (if any) are | |
14255 | all static constraints." | |
14256 | @end example | |
14257 | ||
14258 | Followed. Size Clauses are not permitted on nonstatic components, as | |
14259 | described above. | |
14260 | ||
14261 | @quotation | |
14262 | ||
14263 | “An aliased component, or a component whose type is by-reference, should | |
14264 | always be allocated at an addressable location.” | |
14265 | @end quotation | |
14266 | ||
14267 | Followed. | |
14268 | ||
14269 | @geindex Packed types | |
14270 | ||
14271 | @node RM 13 2 6-8 Packed Types,RM 13 3 14-19 Address Clauses,RM 13 1 21-24 Representation Clauses,Implementation Advice | |
9daee425 | 14272 | @anchor{gnat_rm/implementation_advice rm-13-2-6-8-packed-types}@anchor{235} |
64d5610f ML |
14273 | @section RM 13.2(6-8): Packed Types |
14274 | ||
14275 | ||
14276 | @quotation | |
14277 | ||
14278 | “If a type is packed, then the implementation should try to minimize | |
14279 | storage allocated to objects of the type, possibly at the expense of | |
14280 | speed of accessing components, subject to reasonable complexity in | |
14281 | addressing calculations. | |
14282 | ||
14283 | The recommended level of support pragma @code{Pack} is: | |
14284 | ||
14285 | For a packed record type, the components should be packed as tightly as | |
14286 | possible subject to the Sizes of the component subtypes, and subject to | |
1acce141 | 14287 | any @emph{record_representation_clause} that applies to the type; the |
64d5610f ML |
14288 | implementation may, but need not, reorder components or cross aligned |
14289 | word boundaries to improve the packing. A component whose @code{Size} is | |
14290 | greater than the word size may be allocated an integral number of words.” | |
14291 | @end quotation | |
14292 | ||
14293 | Followed. Tight packing of arrays is supported for all component sizes | |
14294 | up to 64-bits. If the array component size is 1 (that is to say, if | |
14295 | the component is a boolean type or an enumeration type with two values) | |
14296 | then values of the type are implicitly initialized to zero. This | |
14297 | happens both for objects of the packed type, and for objects that have a | |
14298 | subcomponent of the packed type. | |
14299 | ||
14300 | @geindex Address clauses | |
14301 | ||
14302 | @node RM 13 3 14-19 Address Clauses,RM 13 3 29-35 Alignment Clauses,RM 13 2 6-8 Packed Types,Implementation Advice | |
9daee425 | 14303 | @anchor{gnat_rm/implementation_advice rm-13-3-14-19-address-clauses}@anchor{236} |
64d5610f ML |
14304 | @section RM 13.3(14-19): Address Clauses |
14305 | ||
14306 | ||
14307 | @quotation | |
14308 | ||
14309 | “For an array @code{X}, @code{X'Address} should point at the first | |
14310 | component of the array, and not at the array bounds.” | |
14311 | @end quotation | |
14312 | ||
14313 | Followed. | |
14314 | ||
14315 | @quotation | |
14316 | ||
14317 | “The recommended level of support for the @code{Address} attribute is: | |
14318 | ||
14319 | @code{X'Address} should produce a useful result if @code{X} is an | |
14320 | object that is aliased or of a by-reference type, or is an entity whose | |
14321 | @code{Address} has been specified.” | |
14322 | @end quotation | |
14323 | ||
14324 | Followed. A valid address will be produced even if none of those | |
14325 | conditions have been met. If necessary, the object is forced into | |
14326 | memory to ensure the address is valid. | |
14327 | ||
14328 | @quotation | |
14329 | ||
14330 | “An implementation should support @code{Address} clauses for imported | |
14331 | subprograms.” | |
14332 | @end quotation | |
14333 | ||
14334 | Followed. | |
14335 | ||
14336 | @quotation | |
14337 | ||
14338 | “Objects (including subcomponents) that are aliased or of a by-reference | |
14339 | type should be allocated on storage element boundaries.” | |
14340 | @end quotation | |
14341 | ||
14342 | Followed. | |
14343 | ||
14344 | @quotation | |
14345 | ||
14346 | “If the @code{Address} of an object is specified, or it is imported or exported, | |
14347 | then the implementation should not perform optimizations based on | |
14348 | assumptions of no aliases.” | |
14349 | @end quotation | |
14350 | ||
14351 | Followed. | |
14352 | ||
14353 | @geindex Alignment clauses | |
14354 | ||
14355 | @node RM 13 3 29-35 Alignment Clauses,RM 13 3 42-43 Size Clauses,RM 13 3 14-19 Address Clauses,Implementation Advice | |
9daee425 | 14356 | @anchor{gnat_rm/implementation_advice rm-13-3-29-35-alignment-clauses}@anchor{237} |
64d5610f ML |
14357 | @section RM 13.3(29-35): Alignment Clauses |
14358 | ||
14359 | ||
14360 | @quotation | |
14361 | ||
14362 | “The recommended level of support for the @code{Alignment} attribute for | |
14363 | subtypes is: | |
14364 | ||
14365 | An implementation should support specified Alignments that are factors | |
14366 | and multiples of the number of storage elements per word, subject to the | |
14367 | following:” | |
14368 | @end quotation | |
14369 | ||
14370 | Followed. | |
14371 | ||
14372 | @quotation | |
14373 | ||
14374 | “An implementation need not support specified Alignments for | |
14375 | combinations of Sizes and Alignments that cannot be easily | |
14376 | loaded and stored by available machine instructions.” | |
14377 | @end quotation | |
14378 | ||
14379 | Followed. | |
14380 | ||
14381 | @quotation | |
14382 | ||
14383 | “An implementation need not support specified Alignments that are | |
14384 | greater than the maximum @code{Alignment} the implementation ever returns by | |
14385 | default.” | |
14386 | @end quotation | |
14387 | ||
14388 | Followed. | |
14389 | ||
14390 | @quotation | |
14391 | ||
14392 | “The recommended level of support for the @code{Alignment} attribute for | |
14393 | objects is: | |
14394 | ||
14395 | Same as above, for subtypes, but in addition:” | |
14396 | @end quotation | |
14397 | ||
14398 | Followed. | |
14399 | ||
14400 | @quotation | |
14401 | ||
14402 | “For stand-alone library-level objects of statically constrained | |
14403 | subtypes, the implementation should support all alignments | |
14404 | supported by the target linker. For example, page alignment is likely to | |
14405 | be supported for such objects, but not for subtypes.” | |
14406 | @end quotation | |
14407 | ||
14408 | Followed. | |
14409 | ||
14410 | @geindex Size clauses | |
14411 | ||
14412 | @node RM 13 3 42-43 Size Clauses,RM 13 3 50-56 Size Clauses,RM 13 3 29-35 Alignment Clauses,Implementation Advice | |
9daee425 | 14413 | @anchor{gnat_rm/implementation_advice rm-13-3-42-43-size-clauses}@anchor{238} |
64d5610f ML |
14414 | @section RM 13.3(42-43): Size Clauses |
14415 | ||
14416 | ||
14417 | @quotation | |
14418 | ||
14419 | “The recommended level of support for the @code{Size} attribute of | |
14420 | objects is: | |
14421 | ||
14422 | A @code{Size} clause should be supported for an object if the specified | |
14423 | @code{Size} is at least as large as its subtype’s @code{Size}, and | |
14424 | corresponds to a size in storage elements that is a multiple of the | |
14425 | object’s @code{Alignment} (if the @code{Alignment} is nonzero).” | |
14426 | @end quotation | |
14427 | ||
14428 | Followed. | |
14429 | ||
14430 | @node RM 13 3 50-56 Size Clauses,RM 13 3 71-73 Component Size Clauses,RM 13 3 42-43 Size Clauses,Implementation Advice | |
9daee425 | 14431 | @anchor{gnat_rm/implementation_advice rm-13-3-50-56-size-clauses}@anchor{239} |
64d5610f ML |
14432 | @section RM 13.3(50-56): Size Clauses |
14433 | ||
14434 | ||
14435 | @quotation | |
14436 | ||
14437 | “If the @code{Size} of a subtype is specified, and allows for efficient | |
14438 | independent addressability (see 9.10) on the target architecture, then | |
14439 | the @code{Size} of the following objects of the subtype should equal the | |
14440 | @code{Size} of the subtype: | |
14441 | ||
14442 | Aliased objects (including components).” | |
14443 | @end quotation | |
14444 | ||
14445 | Followed. | |
14446 | ||
14447 | @quotation | |
14448 | ||
14449 | “@cite{Size} clause on a composite subtype should not affect the | |
14450 | internal layout of components.” | |
14451 | @end quotation | |
14452 | ||
14453 | Followed. But note that this can be overridden by use of the implementation | |
14454 | pragma Implicit_Packing in the case of packed arrays. | |
14455 | ||
14456 | @quotation | |
14457 | ||
14458 | “The recommended level of support for the @code{Size} attribute of subtypes is: | |
14459 | ||
14460 | The @code{Size} (if not specified) of a static discrete or fixed point | |
14461 | subtype should be the number of bits needed to represent each value | |
14462 | belonging to the subtype using an unbiased representation, leaving space | |
14463 | for a sign bit only if the subtype contains negative values. If such a | |
14464 | subtype is a first subtype, then an implementation should support a | |
14465 | specified @code{Size} for it that reflects this representation.” | |
14466 | @end quotation | |
14467 | ||
14468 | Followed. | |
14469 | ||
14470 | @quotation | |
14471 | ||
14472 | “For a subtype implemented with levels of indirection, the @code{Size} | |
14473 | should include the size of the pointers, but not the size of what they | |
14474 | point at.” | |
14475 | @end quotation | |
14476 | ||
14477 | Followed. | |
14478 | ||
14479 | @geindex Component_Size clauses | |
14480 | ||
14481 | @node RM 13 3 71-73 Component Size Clauses,RM 13 4 9-10 Enumeration Representation Clauses,RM 13 3 50-56 Size Clauses,Implementation Advice | |
9daee425 | 14482 | @anchor{gnat_rm/implementation_advice rm-13-3-71-73-component-size-clauses}@anchor{23a} |
64d5610f ML |
14483 | @section RM 13.3(71-73): Component Size Clauses |
14484 | ||
14485 | ||
14486 | @quotation | |
14487 | ||
14488 | “The recommended level of support for the @code{Component_Size} | |
14489 | attribute is: | |
14490 | ||
14491 | An implementation need not support specified @code{Component_Sizes} that are | |
14492 | less than the @code{Size} of the component subtype.” | |
14493 | @end quotation | |
14494 | ||
14495 | Followed. | |
14496 | ||
14497 | @quotation | |
14498 | ||
14499 | “An implementation should support specified Component_Sizes that | |
14500 | are factors and multiples of the word size. For such | |
14501 | Component_Sizes, the array should contain no gaps between | |
14502 | components. For other Component_Sizes (if supported), the array | |
14503 | should contain no gaps between components when packing is also | |
14504 | specified; the implementation should forbid this combination in cases | |
14505 | where it cannot support a no-gaps representation.” | |
14506 | @end quotation | |
14507 | ||
14508 | Followed. | |
14509 | ||
14510 | @geindex Enumeration representation clauses | |
14511 | ||
14512 | @geindex Representation clauses | |
14513 | @geindex enumeration | |
14514 | ||
14515 | @node RM 13 4 9-10 Enumeration Representation Clauses,RM 13 5 1 17-22 Record Representation Clauses,RM 13 3 71-73 Component Size Clauses,Implementation Advice | |
9daee425 | 14516 | @anchor{gnat_rm/implementation_advice rm-13-4-9-10-enumeration-representation-clauses}@anchor{23b} |
64d5610f ML |
14517 | @section RM 13.4(9-10): Enumeration Representation Clauses |
14518 | ||
14519 | ||
14520 | @quotation | |
14521 | ||
14522 | “The recommended level of support for enumeration representation clauses | |
14523 | is: | |
14524 | ||
14525 | An implementation need not support enumeration representation clauses | |
14526 | for boolean types, but should at minimum support the internal codes in | |
14527 | the range @code{System.Min_Int .. System.Max_Int}.” | |
14528 | @end quotation | |
14529 | ||
14530 | Followed. | |
14531 | ||
14532 | @geindex Record representation clauses | |
14533 | ||
14534 | @geindex Representation clauses | |
14535 | @geindex records | |
14536 | ||
14537 | @node RM 13 5 1 17-22 Record Representation Clauses,RM 13 5 2 5 Storage Place Attributes,RM 13 4 9-10 Enumeration Representation Clauses,Implementation Advice | |
9daee425 | 14538 | @anchor{gnat_rm/implementation_advice rm-13-5-1-17-22-record-representation-clauses}@anchor{23c} |
64d5610f ML |
14539 | @section RM 13.5.1(17-22): Record Representation Clauses |
14540 | ||
14541 | ||
14542 | @quotation | |
14543 | ||
14544 | “The recommended level of support for | |
1acce141 | 14545 | @emph{record_representation_clause}s is: |
64d5610f ML |
14546 | |
14547 | An implementation should support storage places that can be extracted | |
14548 | with a load, mask, shift sequence of machine code, and set with a load, | |
14549 | shift, mask, store sequence, given the available machine instructions | |
14550 | and run-time model.” | |
14551 | @end quotation | |
14552 | ||
14553 | Followed. | |
14554 | ||
14555 | @quotation | |
14556 | ||
14557 | “A storage place should be supported if its size is equal to the | |
14558 | @code{Size} of the component subtype, and it starts and ends on a | |
14559 | boundary that obeys the @code{Alignment} of the component subtype.” | |
14560 | @end quotation | |
14561 | ||
14562 | Followed. | |
14563 | ||
14564 | @quotation | |
14565 | ||
14566 | “If the default bit ordering applies to the declaration of a given type, | |
14567 | then for a component whose subtype’s @code{Size} is less than the word | |
14568 | size, any storage place that does not cross an aligned word boundary | |
14569 | should be supported.” | |
14570 | @end quotation | |
14571 | ||
14572 | Followed. | |
14573 | ||
14574 | @quotation | |
14575 | ||
14576 | “An implementation may reserve a storage place for the tag field of a | |
14577 | tagged type, and disallow other components from overlapping that place.” | |
14578 | @end quotation | |
14579 | ||
14580 | Followed. The storage place for the tag field is the beginning of the tagged | |
14581 | record, and its size is Address’Size. GNAT will reject an explicit component | |
14582 | clause for the tag field. | |
14583 | ||
14584 | @quotation | |
14585 | ||
1acce141 | 14586 | “An implementation need not support a @emph{component_clause} for a |
64d5610f ML |
14587 | component of an extension part if the storage place is not after the |
14588 | storage places of all components of the parent type, whether or not | |
14589 | those storage places had been specified.” | |
14590 | @end quotation | |
14591 | ||
14592 | Followed. The above advice on record representation clauses is followed, | |
14593 | and all mentioned features are implemented. | |
14594 | ||
14595 | @geindex Storage place attributes | |
14596 | ||
14597 | @node RM 13 5 2 5 Storage Place Attributes,RM 13 5 3 7-8 Bit Ordering,RM 13 5 1 17-22 Record Representation Clauses,Implementation Advice | |
9daee425 | 14598 | @anchor{gnat_rm/implementation_advice rm-13-5-2-5-storage-place-attributes}@anchor{23d} |
64d5610f ML |
14599 | @section RM 13.5.2(5): Storage Place Attributes |
14600 | ||
14601 | ||
14602 | @quotation | |
14603 | ||
14604 | “If a component is represented using some form of pointer (such as an | |
14605 | offset) to the actual data of the component, and this data is contiguous | |
14606 | with the rest of the object, then the storage place attributes should | |
14607 | reflect the place of the actual data, not the pointer. If a component is | |
14608 | allocated discontinuously from the rest of the object, then a warning | |
14609 | should be generated upon reference to one of its storage place | |
14610 | attributes.” | |
14611 | @end quotation | |
14612 | ||
14613 | Followed. There are no such components in GNAT. | |
14614 | ||
14615 | @geindex Bit ordering | |
14616 | ||
14617 | @node RM 13 5 3 7-8 Bit Ordering,RM 13 7 37 Address as Private,RM 13 5 2 5 Storage Place Attributes,Implementation Advice | |
9daee425 | 14618 | @anchor{gnat_rm/implementation_advice rm-13-5-3-7-8-bit-ordering}@anchor{23e} |
64d5610f ML |
14619 | @section RM 13.5.3(7-8): Bit Ordering |
14620 | ||
14621 | ||
14622 | @quotation | |
14623 | ||
14624 | “The recommended level of support for the non-default bit ordering is: | |
14625 | ||
14626 | If @code{Word_Size} = @code{Storage_Unit}, then the implementation | |
14627 | should support the non-default bit ordering in addition to the default | |
14628 | bit ordering.” | |
14629 | @end quotation | |
14630 | ||
14631 | Followed. Word size does not equal storage size in this implementation. | |
14632 | Thus non-default bit ordering is not supported. | |
14633 | ||
14634 | @geindex Address | |
14635 | @geindex as private type | |
14636 | ||
14637 | @node RM 13 7 37 Address as Private,RM 13 7 1 16 Address Operations,RM 13 5 3 7-8 Bit Ordering,Implementation Advice | |
9daee425 | 14638 | @anchor{gnat_rm/implementation_advice rm-13-7-37-address-as-private}@anchor{23f} |
64d5610f ML |
14639 | @section RM 13.7(37): Address as Private |
14640 | ||
14641 | ||
14642 | @quotation | |
14643 | ||
14644 | “@cite{Address} should be of a private type.” | |
14645 | @end quotation | |
14646 | ||
14647 | Followed. | |
14648 | ||
14649 | @geindex Operations | |
14650 | @geindex on `@w{`}Address`@w{`} | |
14651 | ||
14652 | @geindex Address | |
14653 | @geindex operations of | |
14654 | ||
14655 | @node RM 13 7 1 16 Address Operations,RM 13 9 14-17 Unchecked Conversion,RM 13 7 37 Address as Private,Implementation Advice | |
9daee425 | 14656 | @anchor{gnat_rm/implementation_advice rm-13-7-1-16-address-operations}@anchor{240} |
64d5610f ML |
14657 | @section RM 13.7.1(16): Address Operations |
14658 | ||
14659 | ||
14660 | @quotation | |
14661 | ||
14662 | “Operations in @code{System} and its children should reflect the target | |
14663 | environment semantics as closely as is reasonable. For example, on most | |
14664 | machines, it makes sense for address arithmetic to ‘wrap around’. | |
14665 | Operations that do not make sense should raise @code{Program_Error}.” | |
14666 | @end quotation | |
14667 | ||
14668 | Followed. Address arithmetic is modular arithmetic that wraps around. No | |
14669 | operation raises @code{Program_Error}, since all operations make sense. | |
14670 | ||
14671 | @geindex Unchecked conversion | |
14672 | ||
14673 | @node RM 13 9 14-17 Unchecked Conversion,RM 13 11 23-25 Implicit Heap Usage,RM 13 7 1 16 Address Operations,Implementation Advice | |
9daee425 | 14674 | @anchor{gnat_rm/implementation_advice rm-13-9-14-17-unchecked-conversion}@anchor{241} |
64d5610f ML |
14675 | @section RM 13.9(14-17): Unchecked Conversion |
14676 | ||
14677 | ||
14678 | @quotation | |
14679 | ||
14680 | “The @code{Size} of an array object should not include its bounds; hence, | |
14681 | the bounds should not be part of the converted data.” | |
14682 | @end quotation | |
14683 | ||
14684 | Followed. | |
14685 | ||
14686 | @quotation | |
14687 | ||
14688 | “The implementation should not generate unnecessary run-time checks to | |
14689 | ensure that the representation of @code{S} is a representation of the | |
14690 | target type. It should take advantage of the permission to return by | |
14691 | reference when possible. Restrictions on unchecked conversions should be | |
14692 | avoided unless required by the target environment.” | |
14693 | @end quotation | |
14694 | ||
14695 | Followed. There are no restrictions on unchecked conversion. A warning is | |
14696 | generated if the source and target types do not have the same size since | |
14697 | the semantics in this case may be target dependent. | |
14698 | ||
14699 | @quotation | |
14700 | ||
14701 | “The recommended level of support for unchecked conversions is: | |
14702 | ||
14703 | Unchecked conversions should be supported and should be reversible in | |
14704 | the cases where this clause defines the result. To enable meaningful use | |
14705 | of unchecked conversion, a contiguous representation should be used for | |
14706 | elementary subtypes, for statically constrained array subtypes whose | |
14707 | component subtype is one of the subtypes described in this paragraph, | |
14708 | and for record subtypes without discriminants whose component subtypes | |
14709 | are described in this paragraph.” | |
14710 | @end quotation | |
14711 | ||
14712 | Followed. | |
14713 | ||
14714 | @geindex Heap usage | |
14715 | @geindex implicit | |
14716 | ||
14717 | @node RM 13 11 23-25 Implicit Heap Usage,RM 13 11 2 17 Unchecked Deallocation,RM 13 9 14-17 Unchecked Conversion,Implementation Advice | |
9daee425 | 14718 | @anchor{gnat_rm/implementation_advice rm-13-11-23-25-implicit-heap-usage}@anchor{242} |
64d5610f ML |
14719 | @section RM 13.11(23-25): Implicit Heap Usage |
14720 | ||
14721 | ||
14722 | @quotation | |
14723 | ||
14724 | “An implementation should document any cases in which it dynamically | |
14725 | allocates heap storage for a purpose other than the evaluation of an | |
14726 | allocator.” | |
14727 | @end quotation | |
14728 | ||
14729 | Followed, the only other points at which heap storage is dynamically | |
14730 | allocated are as follows: | |
14731 | ||
14732 | ||
14733 | @itemize * | |
14734 | ||
14735 | @item | |
14736 | At initial elaboration time, to allocate dynamically sized global | |
14737 | objects. | |
14738 | ||
14739 | @item | |
14740 | To allocate space for a task when a task is created. | |
14741 | ||
14742 | @item | |
14743 | To extend the secondary stack dynamically when needed. The secondary | |
14744 | stack is used for returning variable length results. | |
14745 | @end itemize | |
14746 | ||
14747 | ||
14748 | @quotation | |
14749 | ||
14750 | “A default (implementation-provided) storage pool for an | |
14751 | access-to-constant type should not have overhead to support deallocation of | |
14752 | individual objects.” | |
14753 | @end quotation | |
14754 | ||
14755 | Followed. | |
14756 | ||
14757 | @quotation | |
14758 | ||
14759 | “A storage pool for an anonymous access type should be created at the | |
14760 | point of an allocator for the type, and be reclaimed when the designated | |
14761 | object becomes inaccessible.” | |
14762 | @end quotation | |
14763 | ||
14764 | Followed. | |
14765 | ||
14766 | @geindex Unchecked deallocation | |
14767 | ||
14768 | @node RM 13 11 2 17 Unchecked Deallocation,RM 13 13 2 1 6 Stream Oriented Attributes,RM 13 11 23-25 Implicit Heap Usage,Implementation Advice | |
9daee425 | 14769 | @anchor{gnat_rm/implementation_advice rm-13-11-2-17-unchecked-deallocation}@anchor{243} |
64d5610f ML |
14770 | @section RM 13.11.2(17): Unchecked Deallocation |
14771 | ||
14772 | ||
14773 | @quotation | |
14774 | ||
14775 | “For a standard storage pool, @code{Free} should actually reclaim the | |
14776 | storage.” | |
14777 | @end quotation | |
14778 | ||
14779 | Followed. | |
14780 | ||
14781 | @geindex Stream oriented attributes | |
14782 | ||
14783 | @node RM 13 13 2 1 6 Stream Oriented Attributes,RM A 1 52 Names of Predefined Numeric Types,RM 13 11 2 17 Unchecked Deallocation,Implementation Advice | |
9daee425 | 14784 | @anchor{gnat_rm/implementation_advice rm-13-13-2-1-6-stream-oriented-attributes}@anchor{244} |
64d5610f ML |
14785 | @section RM 13.13.2(1.6): Stream Oriented Attributes |
14786 | ||
14787 | ||
14788 | @quotation | |
14789 | ||
14790 | “If not specified, the value of Stream_Size for an elementary type | |
14791 | should be the number of bits that corresponds to the minimum number of | |
14792 | stream elements required by the first subtype of the type, rounded up | |
14793 | to the nearest factor or multiple of the word size that is also a | |
14794 | multiple of the stream element size.” | |
14795 | @end quotation | |
14796 | ||
14797 | Followed, except that the number of stream elements is 1, 2, 3, 4 or 8. | |
14798 | The Stream_Size may be used to override the default choice. | |
14799 | ||
14800 | The default implementation is based on direct binary representations and is | |
14801 | therefore target- and endianness-dependent. To address this issue, GNAT also | |
14802 | supplies an alternate implementation of the stream attributes @code{Read} and | |
14803 | @code{Write}, which uses the target-independent XDR standard representation for | |
14804 | scalar types. This XDR alternative can be enabled via the binder switch -xdr. | |
14805 | ||
14806 | @geindex XDR representation | |
14807 | ||
14808 | @geindex Read attribute | |
14809 | ||
14810 | @geindex Write attribute | |
14811 | ||
14812 | @geindex Stream oriented attributes | |
14813 | ||
14814 | @node RM A 1 52 Names of Predefined Numeric Types,RM A 3 2 49 Ada Characters Handling,RM 13 13 2 1 6 Stream Oriented Attributes,Implementation Advice | |
9daee425 | 14815 | @anchor{gnat_rm/implementation_advice rm-a-1-52-names-of-predefined-numeric-types}@anchor{245} |
64d5610f ML |
14816 | @section RM A.1(52): Names of Predefined Numeric Types |
14817 | ||
14818 | ||
14819 | @quotation | |
14820 | ||
14821 | “If an implementation provides additional named predefined integer types, | |
14822 | then the names should end with @code{Integer} as in | |
14823 | @code{Long_Integer}. If an implementation provides additional named | |
14824 | predefined floating point types, then the names should end with | |
14825 | @code{Float} as in @code{Long_Float}.” | |
14826 | @end quotation | |
14827 | ||
14828 | Followed. | |
14829 | ||
14830 | @geindex Ada.Characters.Handling | |
14831 | ||
14832 | @node RM A 3 2 49 Ada Characters Handling,RM A 4 4 106 Bounded-Length String Handling,RM A 1 52 Names of Predefined Numeric Types,Implementation Advice | |
9daee425 | 14833 | @anchor{gnat_rm/implementation_advice rm-a-3-2-49-ada-characters-handling}@anchor{246} |
64d5610f ML |
14834 | @section RM A.3.2(49): @code{Ada.Characters.Handling} |
14835 | ||
14836 | ||
14837 | @quotation | |
14838 | ||
14839 | “If an implementation provides a localized definition of @code{Character} | |
14840 | or @code{Wide_Character}, then the effects of the subprograms in | |
14841 | @code{Characters.Handling} should reflect the localizations. | |
14842 | See also 3.5.2.” | |
14843 | @end quotation | |
14844 | ||
14845 | Followed. GNAT provides no such localized definitions. | |
14846 | ||
14847 | @geindex Bounded-length strings | |
14848 | ||
14849 | @node RM A 4 4 106 Bounded-Length String Handling,RM A 5 2 46-47 Random Number Generation,RM A 3 2 49 Ada Characters Handling,Implementation Advice | |
9daee425 | 14850 | @anchor{gnat_rm/implementation_advice rm-a-4-4-106-bounded-length-string-handling}@anchor{247} |
64d5610f ML |
14851 | @section RM A.4.4(106): Bounded-Length String Handling |
14852 | ||
14853 | ||
14854 | @quotation | |
14855 | ||
14856 | “Bounded string objects should not be implemented by implicit pointers | |
14857 | and dynamic allocation.” | |
14858 | @end quotation | |
14859 | ||
14860 | Followed. No implicit pointers or dynamic allocation are used. | |
14861 | ||
14862 | @geindex Random number generation | |
14863 | ||
14864 | @node RM A 5 2 46-47 Random Number Generation,RM A 10 7 23 Get_Immediate,RM A 4 4 106 Bounded-Length String Handling,Implementation Advice | |
9daee425 | 14865 | @anchor{gnat_rm/implementation_advice rm-a-5-2-46-47-random-number-generation}@anchor{248} |
64d5610f ML |
14866 | @section RM A.5.2(46-47): Random Number Generation |
14867 | ||
14868 | ||
14869 | @quotation | |
14870 | ||
14871 | “Any storage associated with an object of type @code{Generator} should be | |
14872 | reclaimed on exit from the scope of the object.” | |
14873 | @end quotation | |
14874 | ||
14875 | Followed. | |
14876 | ||
14877 | @quotation | |
14878 | ||
14879 | “If the generator period is sufficiently long in relation to the number | |
14880 | of distinct initiator values, then each possible value of | |
14881 | @code{Initiator} passed to @code{Reset} should initiate a sequence of | |
14882 | random numbers that does not, in a practical sense, overlap the sequence | |
14883 | initiated by any other value. If this is not possible, then the mapping | |
14884 | between initiator values and generator states should be a rapidly | |
14885 | varying function of the initiator value.” | |
14886 | @end quotation | |
14887 | ||
14888 | Followed. The generator period is sufficiently long for the first | |
14889 | condition here to hold true. | |
14890 | ||
14891 | @geindex Get_Immediate | |
14892 | ||
14893 | @node RM A 10 7 23 Get_Immediate,RM A 18 Containers,RM A 5 2 46-47 Random Number Generation,Implementation Advice | |
9daee425 | 14894 | @anchor{gnat_rm/implementation_advice rm-a-10-7-23-get-immediate}@anchor{249} |
64d5610f ML |
14895 | @section RM A.10.7(23): @code{Get_Immediate} |
14896 | ||
14897 | ||
14898 | @quotation | |
14899 | ||
14900 | “The @code{Get_Immediate} procedures should be implemented with | |
14901 | unbuffered input. For a device such as a keyboard, input should be | |
14902 | available if a key has already been typed, whereas for a disk | |
14903 | file, input should always be available except at end of file. For a file | |
14904 | associated with a keyboard-like device, any line-editing features of the | |
14905 | underlying operating system should be disabled during the execution of | |
14906 | @code{Get_Immediate}.” | |
14907 | @end quotation | |
14908 | ||
14909 | Followed on all targets except VxWorks. For VxWorks, there is no way to | |
14910 | provide this functionality that does not result in the input buffer being | |
14911 | flushed before the @code{Get_Immediate} call. A special unit | |
14912 | @code{Interfaces.Vxworks.IO} is provided that contains routines to enable | |
14913 | this functionality. | |
14914 | ||
14915 | @geindex Containers | |
14916 | ||
14917 | @node RM A 18 Containers,RM B 1 39-41 Pragma Export,RM A 10 7 23 Get_Immediate,Implementation Advice | |
9daee425 | 14918 | @anchor{gnat_rm/implementation_advice rm-a-18-containers}@anchor{24a} |
64d5610f ML |
14919 | @section RM A.18: @code{Containers} |
14920 | ||
14921 | ||
14922 | All implementation advice pertaining to Ada.Containers and its | |
14923 | child units (that is, all implementation advice occurring within | |
14924 | section A.18 and its subsections) is followed except for A.18.24(17): | |
14925 | ||
14926 | @quotation | |
14927 | ||
14928 | “Bounded ordered set objects should be implemented without implicit pointers or dynamic allocation. “ | |
14929 | @end quotation | |
14930 | ||
14931 | The implementations of the two Reference_Preserving_Key functions of | |
14932 | the generic package Ada.Containers.Bounded_Ordered_Sets each currently make | |
14933 | use of dynamic allocation; other operations on bounded ordered set objects | |
14934 | follow the implementation advice. | |
14935 | ||
14936 | @geindex Export | |
14937 | ||
14938 | @node RM B 1 39-41 Pragma Export,RM B 2 12-13 Package Interfaces,RM A 18 Containers,Implementation Advice | |
9daee425 | 14939 | @anchor{gnat_rm/implementation_advice rm-b-1-39-41-pragma-export}@anchor{24b} |
64d5610f ML |
14940 | @section RM B.1(39-41): Pragma @code{Export} |
14941 | ||
14942 | ||
14943 | @quotation | |
14944 | ||
14945 | “If an implementation supports pragma @code{Export} to a given language, | |
14946 | then it should also allow the main subprogram to be written in that | |
14947 | language. It should support some mechanism for invoking the elaboration | |
14948 | of the Ada library units included in the system, and for invoking the | |
14949 | finalization of the environment task. On typical systems, the | |
14950 | recommended mechanism is to provide two subprograms whose link names are | |
14951 | @code{adainit} and @code{adafinal}. @code{adainit} should contain the | |
14952 | elaboration code for library units. @code{adafinal} should contain the | |
14953 | finalization code. These subprograms should have no effect the second | |
14954 | and subsequent time they are called.” | |
14955 | @end quotation | |
14956 | ||
14957 | Followed. | |
14958 | ||
14959 | @quotation | |
14960 | ||
14961 | “Automatic elaboration of pre-elaborated packages should be | |
14962 | provided when pragma @code{Export} is supported.” | |
14963 | @end quotation | |
14964 | ||
14965 | Followed when the main program is in Ada. If the main program is in a | |
14966 | foreign language, then | |
14967 | @code{adainit} must be called to elaborate pre-elaborated | |
14968 | packages. | |
14969 | ||
14970 | @quotation | |
14971 | ||
1acce141 | 14972 | “For each supported convention @emph{L} other than @code{Intrinsic}, an |
64d5610f | 14973 | implementation should support @code{Import} and @code{Export} pragmas |
1acce141 YM |
14974 | for objects of @emph{L}-compatible types and for subprograms, and pragma |
14975 | @cite{Convention} for @emph{L}-eligible types and for subprograms, | |
64d5610f ML |
14976 | presuming the other language has corresponding features. Pragma |
14977 | @code{Convention} need not be supported for scalar types.” | |
14978 | @end quotation | |
14979 | ||
14980 | Followed. | |
14981 | ||
14982 | @geindex Package Interfaces | |
14983 | ||
14984 | @geindex Interfaces | |
14985 | ||
14986 | @node RM B 2 12-13 Package Interfaces,RM B 3 63-71 Interfacing with C,RM B 1 39-41 Pragma Export,Implementation Advice | |
9daee425 | 14987 | @anchor{gnat_rm/implementation_advice rm-b-2-12-13-package-interfaces}@anchor{24c} |
64d5610f ML |
14988 | @section RM B.2(12-13): Package @code{Interfaces} |
14989 | ||
14990 | ||
14991 | @quotation | |
14992 | ||
14993 | “For each implementation-defined convention identifier, there should be a | |
14994 | child package of package Interfaces with the corresponding name. This | |
14995 | package should contain any declarations that would be useful for | |
14996 | interfacing to the language (implementation) represented by the | |
14997 | convention. Any declarations useful for interfacing to any language on | |
14998 | the given hardware architecture should be provided directly in | |
14999 | @code{Interfaces}.” | |
15000 | @end quotation | |
15001 | ||
15002 | Followed. | |
15003 | ||
15004 | @quotation | |
15005 | ||
15006 | “An implementation supporting an interface to C, COBOL, or Fortran should | |
15007 | provide the corresponding package or packages described in the following | |
15008 | clauses.” | |
15009 | @end quotation | |
15010 | ||
15011 | Followed. GNAT provides all the packages described in this section. | |
15012 | ||
15013 | @geindex C | |
15014 | @geindex interfacing with | |
15015 | ||
15016 | @node RM B 3 63-71 Interfacing with C,RM B 4 95-98 Interfacing with COBOL,RM B 2 12-13 Package Interfaces,Implementation Advice | |
9daee425 | 15017 | @anchor{gnat_rm/implementation_advice rm-b-3-63-71-interfacing-with-c}@anchor{24d} |
64d5610f ML |
15018 | @section RM B.3(63-71): Interfacing with C |
15019 | ||
15020 | ||
15021 | @quotation | |
15022 | ||
15023 | “An implementation should support the following interface correspondences | |
15024 | between Ada and C.” | |
15025 | @end quotation | |
15026 | ||
15027 | Followed. | |
15028 | ||
15029 | @quotation | |
15030 | ||
15031 | “An Ada procedure corresponds to a void-returning C function.” | |
15032 | @end quotation | |
15033 | ||
15034 | Followed. | |
15035 | ||
15036 | @quotation | |
15037 | ||
15038 | “An Ada function corresponds to a non-void C function.” | |
15039 | @end quotation | |
15040 | ||
15041 | Followed. | |
15042 | ||
15043 | @quotation | |
15044 | ||
15045 | “An Ada @code{in} scalar parameter is passed as a scalar argument to a C | |
15046 | function.” | |
15047 | @end quotation | |
15048 | ||
15049 | Followed. | |
15050 | ||
15051 | @quotation | |
15052 | ||
15053 | “An Ada @code{in} parameter of an access-to-object type with designated | |
15054 | type @code{T} is passed as a @code{t*} argument to a C function, | |
15055 | where @code{t} is the C type corresponding to the Ada type @code{T}.” | |
15056 | @end quotation | |
15057 | ||
15058 | Followed. | |
15059 | ||
15060 | @quotation | |
15061 | ||
15062 | “An Ada access @code{T} parameter, or an Ada @code{out} or @code{in out} | |
15063 | parameter of an elementary type @code{T}, is passed as a @code{t*} | |
15064 | argument to a C function, where @code{t} is the C type corresponding to | |
15065 | the Ada type @code{T}. In the case of an elementary @code{out} or | |
15066 | @code{in out} parameter, a pointer to a temporary copy is used to | |
15067 | preserve by-copy semantics.” | |
15068 | @end quotation | |
15069 | ||
15070 | Followed. | |
15071 | ||
15072 | @quotation | |
15073 | ||
15074 | “An Ada parameter of a record type @code{T}, of any mode, is passed as a | |
15075 | @code{t*} argument to a C function, where @code{t} is the C | |
15076 | structure corresponding to the Ada type @code{T}.” | |
15077 | @end quotation | |
15078 | ||
15079 | Followed. This convention may be overridden by the use of the C_Pass_By_Copy | |
15080 | pragma, or Convention, or by explicitly specifying the mechanism for a given | |
15081 | call using an extended import or export pragma. | |
15082 | ||
15083 | @quotation | |
15084 | ||
15085 | “An Ada parameter of an array type with component type @code{T}, of any | |
15086 | mode, is passed as a @code{t*} argument to a C function, where | |
15087 | @code{t} is the C type corresponding to the Ada type @code{T}.” | |
15088 | @end quotation | |
15089 | ||
15090 | Followed. | |
15091 | ||
15092 | @quotation | |
15093 | ||
15094 | “An Ada parameter of an access-to-subprogram type is passed as a pointer | |
15095 | to a C function whose prototype corresponds to the designated | |
15096 | subprogram’s specification.” | |
15097 | @end quotation | |
15098 | ||
15099 | Followed. | |
15100 | ||
15101 | @geindex COBOL | |
15102 | @geindex interfacing with | |
15103 | ||
15104 | @node RM B 4 95-98 Interfacing with COBOL,RM B 5 22-26 Interfacing with Fortran,RM B 3 63-71 Interfacing with C,Implementation Advice | |
9daee425 | 15105 | @anchor{gnat_rm/implementation_advice rm-b-4-95-98-interfacing-with-cobol}@anchor{24e} |
64d5610f ML |
15106 | @section RM B.4(95-98): Interfacing with COBOL |
15107 | ||
15108 | ||
15109 | @quotation | |
15110 | ||
15111 | “An Ada implementation should support the following interface | |
15112 | correspondences between Ada and COBOL.” | |
15113 | @end quotation | |
15114 | ||
15115 | Followed. | |
15116 | ||
15117 | @quotation | |
15118 | ||
15119 | “An Ada access @code{T} parameter is passed as a @code{BY REFERENCE} data item of | |
15120 | the COBOL type corresponding to @code{T}.” | |
15121 | @end quotation | |
15122 | ||
15123 | Followed. | |
15124 | ||
15125 | @quotation | |
15126 | ||
15127 | “An Ada in scalar parameter is passed as a @code{BY CONTENT} data item of | |
15128 | the corresponding COBOL type.” | |
15129 | @end quotation | |
15130 | ||
15131 | Followed. | |
15132 | ||
15133 | @quotation | |
15134 | ||
15135 | “Any other Ada parameter is passed as a @code{BY REFERENCE} data item of the | |
15136 | COBOL type corresponding to the Ada parameter type; for scalars, a local | |
15137 | copy is used if necessary to ensure by-copy semantics.” | |
15138 | @end quotation | |
15139 | ||
15140 | Followed. | |
15141 | ||
15142 | @geindex Fortran | |
15143 | @geindex interfacing with | |
15144 | ||
15145 | @node RM B 5 22-26 Interfacing with Fortran,RM C 1 3-5 Access to Machine Operations,RM B 4 95-98 Interfacing with COBOL,Implementation Advice | |
9daee425 | 15146 | @anchor{gnat_rm/implementation_advice rm-b-5-22-26-interfacing-with-fortran}@anchor{24f} |
64d5610f ML |
15147 | @section RM B.5(22-26): Interfacing with Fortran |
15148 | ||
15149 | ||
15150 | @quotation | |
15151 | ||
15152 | “An Ada implementation should support the following interface | |
15153 | correspondences between Ada and Fortran:” | |
15154 | @end quotation | |
15155 | ||
15156 | Followed. | |
15157 | ||
15158 | @quotation | |
15159 | ||
15160 | “An Ada procedure corresponds to a Fortran subroutine.” | |
15161 | @end quotation | |
15162 | ||
15163 | Followed. | |
15164 | ||
15165 | @quotation | |
15166 | ||
15167 | “An Ada function corresponds to a Fortran function.” | |
15168 | @end quotation | |
15169 | ||
15170 | Followed. | |
15171 | ||
15172 | @quotation | |
15173 | ||
15174 | “An Ada parameter of an elementary, array, or record type @code{T} is | |
15175 | passed as a @code{T} argument to a Fortran procedure, where @code{T} is | |
15176 | the Fortran type corresponding to the Ada type @code{T}, and where the | |
15177 | INTENT attribute of the corresponding dummy argument matches the Ada | |
15178 | formal parameter mode; the Fortran implementation’s parameter passing | |
15179 | conventions are used. For elementary types, a local copy is used if | |
15180 | necessary to ensure by-copy semantics.” | |
15181 | @end quotation | |
15182 | ||
15183 | Followed. | |
15184 | ||
15185 | @quotation | |
15186 | ||
15187 | “An Ada parameter of an access-to-subprogram type is passed as a | |
15188 | reference to a Fortran procedure whose interface corresponds to the | |
15189 | designated subprogram’s specification.” | |
15190 | @end quotation | |
15191 | ||
15192 | Followed. | |
15193 | ||
15194 | @geindex Machine operations | |
15195 | ||
15196 | @node RM C 1 3-5 Access to Machine Operations,RM C 1 10-16 Access to Machine Operations,RM B 5 22-26 Interfacing with Fortran,Implementation Advice | |
9daee425 | 15197 | @anchor{gnat_rm/implementation_advice rm-c-1-3-5-access-to-machine-operations}@anchor{250} |
64d5610f ML |
15198 | @section RM C.1(3-5): Access to Machine Operations |
15199 | ||
15200 | ||
15201 | @quotation | |
15202 | ||
15203 | “The machine code or intrinsic support should allow access to all | |
15204 | operations normally available to assembly language programmers for the | |
15205 | target environment, including privileged instructions, if any.” | |
15206 | @end quotation | |
15207 | ||
15208 | Followed. | |
15209 | ||
15210 | @quotation | |
15211 | ||
15212 | “The interfacing pragmas (see Annex B) should support interface to | |
15213 | assembler; the default assembler should be associated with the | |
15214 | convention identifier @code{Assembler}.” | |
15215 | @end quotation | |
15216 | ||
15217 | Followed. | |
15218 | ||
15219 | @quotation | |
15220 | ||
15221 | “If an entity is exported to assembly language, then the implementation | |
15222 | should allocate it at an addressable location, and should ensure that it | |
15223 | is retained by the linking process, even if not otherwise referenced | |
15224 | from the Ada code. The implementation should assume that any call to a | |
15225 | machine code or assembler subprogram is allowed to read or update every | |
15226 | object that is specified as exported.” | |
15227 | @end quotation | |
15228 | ||
15229 | Followed. | |
15230 | ||
15231 | @node RM C 1 10-16 Access to Machine Operations,RM C 3 28 Interrupt Support,RM C 1 3-5 Access to Machine Operations,Implementation Advice | |
9daee425 | 15232 | @anchor{gnat_rm/implementation_advice rm-c-1-10-16-access-to-machine-operations}@anchor{251} |
64d5610f ML |
15233 | @section RM C.1(10-16): Access to Machine Operations |
15234 | ||
15235 | ||
15236 | @quotation | |
15237 | ||
15238 | “The implementation should ensure that little or no overhead is | |
15239 | associated with calling intrinsic and machine-code subprograms.” | |
15240 | @end quotation | |
15241 | ||
15242 | Followed for both intrinsics and machine-code subprograms. | |
15243 | ||
15244 | @quotation | |
15245 | ||
15246 | “It is recommended that intrinsic subprograms be provided for convenient | |
15247 | access to any machine operations that provide special capabilities or | |
15248 | efficiency and that are not otherwise available through the language | |
15249 | constructs.” | |
15250 | @end quotation | |
15251 | ||
15252 | Followed. A full set of machine operation intrinsic subprograms is provided. | |
15253 | ||
15254 | @quotation | |
15255 | ||
15256 | “Atomic read-modify-write operations—e.g., test and set, compare and | |
15257 | swap, decrement and test, enqueue/dequeue.” | |
15258 | @end quotation | |
15259 | ||
15260 | Followed on any target supporting such operations. | |
15261 | ||
15262 | @quotation | |
15263 | ||
15264 | “Standard numeric functions—e.g.:, sin, log.” | |
15265 | @end quotation | |
15266 | ||
15267 | Followed on any target supporting such operations. | |
15268 | ||
15269 | @quotation | |
15270 | ||
15271 | “String manipulation operations—e.g.:, translate and test.” | |
15272 | @end quotation | |
15273 | ||
15274 | Followed on any target supporting such operations. | |
15275 | ||
15276 | @quotation | |
15277 | ||
15278 | “Vector operations—e.g.:, compare vector against thresholds.” | |
15279 | @end quotation | |
15280 | ||
15281 | Followed on any target supporting such operations. | |
15282 | ||
15283 | @quotation | |
15284 | ||
15285 | “Direct operations on I/O ports.” | |
15286 | @end quotation | |
15287 | ||
15288 | Followed on any target supporting such operations. | |
15289 | ||
15290 | @geindex Interrupt support | |
15291 | ||
15292 | @node RM C 3 28 Interrupt Support,RM C 3 1 20-21 Protected Procedure Handlers,RM C 1 10-16 Access to Machine Operations,Implementation Advice | |
9daee425 | 15293 | @anchor{gnat_rm/implementation_advice rm-c-3-28-interrupt-support}@anchor{252} |
64d5610f ML |
15294 | @section RM C.3(28): Interrupt Support |
15295 | ||
15296 | ||
15297 | @quotation | |
15298 | ||
15299 | “If the @code{Ceiling_Locking} policy is not in effect, the | |
15300 | implementation should provide means for the application to specify which | |
15301 | interrupts are to be blocked during protected actions, if the underlying | |
15302 | system allows for a finer-grain control of interrupt blocking.” | |
15303 | @end quotation | |
15304 | ||
15305 | Followed. The underlying system does not allow for finer-grain control | |
15306 | of interrupt blocking. | |
15307 | ||
15308 | @geindex Protected procedure handlers | |
15309 | ||
15310 | @node RM C 3 1 20-21 Protected Procedure Handlers,RM C 3 2 25 Package Interrupts,RM C 3 28 Interrupt Support,Implementation Advice | |
9daee425 | 15311 | @anchor{gnat_rm/implementation_advice rm-c-3-1-20-21-protected-procedure-handlers}@anchor{253} |
64d5610f ML |
15312 | @section RM C.3.1(20-21): Protected Procedure Handlers |
15313 | ||
15314 | ||
15315 | @quotation | |
15316 | ||
15317 | “Whenever possible, the implementation should allow interrupt handlers to | |
15318 | be called directly by the hardware.” | |
15319 | @end quotation | |
15320 | ||
15321 | Followed on any target where the underlying operating system permits | |
15322 | such direct calls. | |
15323 | ||
15324 | @quotation | |
15325 | ||
15326 | “Whenever practical, violations of any | |
15327 | implementation-defined restrictions should be detected before run time.” | |
15328 | @end quotation | |
15329 | ||
15330 | Followed. Compile time warnings are given when possible. | |
15331 | ||
15332 | @geindex Package `@w{`}Interrupts`@w{`} | |
15333 | ||
15334 | @geindex Interrupts | |
15335 | ||
15336 | @node RM C 3 2 25 Package Interrupts,RM C 4 14 Pre-elaboration Requirements,RM C 3 1 20-21 Protected Procedure Handlers,Implementation Advice | |
9daee425 | 15337 | @anchor{gnat_rm/implementation_advice rm-c-3-2-25-package-interrupts}@anchor{254} |
64d5610f ML |
15338 | @section RM C.3.2(25): Package @code{Interrupts} |
15339 | ||
15340 | ||
15341 | @quotation | |
15342 | ||
15343 | “If implementation-defined forms of interrupt handler procedures are | |
15344 | supported, such as protected procedures with parameters, then for each | |
15345 | such form of a handler, a type analogous to @code{Parameterless_Handler} | |
15346 | should be specified in a child package of @code{Interrupts}, with the | |
15347 | same operations as in the predefined package Interrupts.” | |
15348 | @end quotation | |
15349 | ||
15350 | Followed. | |
15351 | ||
15352 | @geindex Pre-elaboration requirements | |
15353 | ||
15354 | @node RM C 4 14 Pre-elaboration Requirements,RM C 5 8 Pragma Discard_Names,RM C 3 2 25 Package Interrupts,Implementation Advice | |
9daee425 | 15355 | @anchor{gnat_rm/implementation_advice rm-c-4-14-pre-elaboration-requirements}@anchor{255} |
64d5610f ML |
15356 | @section RM C.4(14): Pre-elaboration Requirements |
15357 | ||
15358 | ||
15359 | @quotation | |
15360 | ||
15361 | “It is recommended that pre-elaborated packages be implemented in such a | |
15362 | way that there should be little or no code executed at run time for the | |
15363 | elaboration of entities not already covered by the Implementation | |
15364 | Requirements.” | |
15365 | @end quotation | |
15366 | ||
15367 | Followed. Executable code is generated in some cases, e.g., loops | |
15368 | to initialize large arrays. | |
15369 | ||
15370 | @node RM C 5 8 Pragma Discard_Names,RM C 7 2 30 The Package Task_Attributes,RM C 4 14 Pre-elaboration Requirements,Implementation Advice | |
9daee425 | 15371 | @anchor{gnat_rm/implementation_advice rm-c-5-8-pragma-discard-names}@anchor{256} |
64d5610f ML |
15372 | @section RM C.5(8): Pragma @code{Discard_Names} |
15373 | ||
15374 | ||
15375 | @quotation | |
15376 | ||
15377 | “If the pragma applies to an entity, then the implementation should | |
15378 | reduce the amount of storage used for storing names associated with that | |
15379 | entity.” | |
15380 | @end quotation | |
15381 | ||
15382 | Followed. | |
15383 | ||
15384 | @geindex Package Task_Attributes | |
15385 | ||
15386 | @geindex Task_Attributes | |
15387 | ||
15388 | @node RM C 7 2 30 The Package Task_Attributes,RM D 3 17 Locking Policies,RM C 5 8 Pragma Discard_Names,Implementation Advice | |
9daee425 | 15389 | @anchor{gnat_rm/implementation_advice rm-c-7-2-30-the-package-task-attributes}@anchor{257} |
64d5610f ML |
15390 | @section RM C.7.2(30): The Package Task_Attributes |
15391 | ||
15392 | ||
15393 | @quotation | |
15394 | ||
15395 | “Some implementations are targeted to domains in which memory use at run | |
15396 | time must be completely deterministic. For such implementations, it is | |
15397 | recommended that the storage for task attributes will be pre-allocated | |
15398 | statically and not from the heap. This can be accomplished by either | |
15399 | placing restrictions on the number and the size of the task’s | |
15400 | attributes, or by using the pre-allocated storage for the first @code{N} | |
15401 | attribute objects, and the heap for the others. In the latter case, | |
15402 | @code{N} should be documented.” | |
15403 | @end quotation | |
15404 | ||
15405 | Not followed. This implementation is not targeted to such a domain. | |
15406 | ||
15407 | @geindex Locking Policies | |
15408 | ||
15409 | @node RM D 3 17 Locking Policies,RM D 4 16 Entry Queuing Policies,RM C 7 2 30 The Package Task_Attributes,Implementation Advice | |
9daee425 | 15410 | @anchor{gnat_rm/implementation_advice rm-d-3-17-locking-policies}@anchor{258} |
64d5610f ML |
15411 | @section RM D.3(17): Locking Policies |
15412 | ||
15413 | ||
15414 | @quotation | |
15415 | ||
15416 | “The implementation should use names that end with @code{_Locking} for | |
15417 | locking policies defined by the implementation.” | |
15418 | @end quotation | |
15419 | ||
15420 | Followed. Two implementation-defined locking policies are defined, | |
15421 | whose names (@code{Inheritance_Locking} and | |
15422 | @code{Concurrent_Readers_Locking}) follow this suggestion. | |
15423 | ||
15424 | @geindex Entry queuing policies | |
15425 | ||
15426 | @node RM D 4 16 Entry Queuing Policies,RM D 6 9-10 Preemptive Abort,RM D 3 17 Locking Policies,Implementation Advice | |
9daee425 | 15427 | @anchor{gnat_rm/implementation_advice rm-d-4-16-entry-queuing-policies}@anchor{259} |
64d5610f ML |
15428 | @section RM D.4(16): Entry Queuing Policies |
15429 | ||
15430 | ||
15431 | @quotation | |
15432 | ||
15433 | “Names that end with @code{_Queuing} should be used | |
15434 | for all implementation-defined queuing policies.” | |
15435 | @end quotation | |
15436 | ||
15437 | Followed. No such implementation-defined queuing policies exist. | |
15438 | ||
15439 | @geindex Preemptive abort | |
15440 | ||
15441 | @node RM D 6 9-10 Preemptive Abort,RM D 7 21 Tasking Restrictions,RM D 4 16 Entry Queuing Policies,Implementation Advice | |
9daee425 | 15442 | @anchor{gnat_rm/implementation_advice rm-d-6-9-10-preemptive-abort}@anchor{25a} |
64d5610f ML |
15443 | @section RM D.6(9-10): Preemptive Abort |
15444 | ||
15445 | ||
15446 | @quotation | |
15447 | ||
1acce141 | 15448 | “Even though the @emph{abort_statement} is included in the list of |
64d5610f ML |
15449 | potentially blocking operations (see 9.5.1), it is recommended that this |
15450 | statement be implemented in a way that never requires the task executing | |
1acce141 | 15451 | the @emph{abort_statement} to block.” |
64d5610f ML |
15452 | @end quotation |
15453 | ||
15454 | Followed. | |
15455 | ||
15456 | @quotation | |
15457 | ||
15458 | “On a multi-processor, the delay associated with aborting a task on | |
15459 | another processor should be bounded; the implementation should use | |
15460 | periodic polling, if necessary, to achieve this.” | |
15461 | @end quotation | |
15462 | ||
15463 | Followed. | |
15464 | ||
15465 | @geindex Tasking restrictions | |
15466 | ||
15467 | @node RM D 7 21 Tasking Restrictions,RM D 8 47-49 Monotonic Time,RM D 6 9-10 Preemptive Abort,Implementation Advice | |
9daee425 | 15468 | @anchor{gnat_rm/implementation_advice rm-d-7-21-tasking-restrictions}@anchor{25b} |
64d5610f ML |
15469 | @section RM D.7(21): Tasking Restrictions |
15470 | ||
15471 | ||
15472 | @quotation | |
15473 | ||
15474 | “When feasible, the implementation should take advantage of the specified | |
15475 | restrictions to produce a more efficient implementation.” | |
15476 | @end quotation | |
15477 | ||
15478 | GNAT currently takes advantage of these restrictions by providing an optimized | |
15479 | run time when the Ravenscar profile and the GNAT restricted run time set | |
15480 | of restrictions are specified. See pragma @code{Profile (Ravenscar)} and | |
15481 | pragma @code{Profile (Restricted)} for more details. | |
15482 | ||
15483 | @geindex Time | |
15484 | @geindex monotonic | |
15485 | ||
15486 | @node RM D 8 47-49 Monotonic Time,RM E 5 28-29 Partition Communication Subsystem,RM D 7 21 Tasking Restrictions,Implementation Advice | |
9daee425 | 15487 | @anchor{gnat_rm/implementation_advice rm-d-8-47-49-monotonic-time}@anchor{25c} |
64d5610f ML |
15488 | @section RM D.8(47-49): Monotonic Time |
15489 | ||
15490 | ||
15491 | @quotation | |
15492 | ||
15493 | “When appropriate, implementations should provide configuration | |
15494 | mechanisms to change the value of @code{Tick}.” | |
15495 | @end quotation | |
15496 | ||
15497 | Such configuration mechanisms are not appropriate to this implementation | |
15498 | and are thus not supported. | |
15499 | ||
15500 | @quotation | |
15501 | ||
15502 | “It is recommended that @code{Calendar.Clock} and @code{Real_Time.Clock} | |
15503 | be implemented as transformations of the same time base.” | |
15504 | @end quotation | |
15505 | ||
15506 | Followed. | |
15507 | ||
15508 | @quotation | |
15509 | ||
15510 | “It is recommended that the best time base which exists in | |
15511 | the underlying system be available to the application through | |
15512 | @code{Clock}. @cite{Best} may mean highest accuracy or largest range.” | |
15513 | @end quotation | |
15514 | ||
15515 | Followed. | |
15516 | ||
15517 | @geindex Partition communication subsystem | |
15518 | ||
15519 | @geindex PCS | |
15520 | ||
15521 | @node RM E 5 28-29 Partition Communication Subsystem,RM F 7 COBOL Support,RM D 8 47-49 Monotonic Time,Implementation Advice | |
9daee425 | 15522 | @anchor{gnat_rm/implementation_advice rm-e-5-28-29-partition-communication-subsystem}@anchor{25d} |
64d5610f ML |
15523 | @section RM E.5(28-29): Partition Communication Subsystem |
15524 | ||
15525 | ||
15526 | @quotation | |
15527 | ||
15528 | “Whenever possible, the PCS on the called partition should allow for | |
15529 | multiple tasks to call the RPC-receiver with different messages and | |
15530 | should allow them to block until the corresponding subprogram body | |
15531 | returns.” | |
15532 | @end quotation | |
15533 | ||
15534 | Followed by GLADE, a separately supplied PCS that can be used with | |
15535 | GNAT. | |
15536 | ||
15537 | @quotation | |
15538 | ||
15539 | “The @code{Write} operation on a stream of type @code{Params_Stream_Type} | |
15540 | should raise @code{Storage_Error} if it runs out of space trying to | |
15541 | write the @code{Item} into the stream.” | |
15542 | @end quotation | |
15543 | ||
15544 | Followed by GLADE, a separately supplied PCS that can be used with | |
15545 | GNAT. | |
15546 | ||
15547 | @geindex COBOL support | |
15548 | ||
15549 | @node RM F 7 COBOL Support,RM F 1 2 Decimal Radix Support,RM E 5 28-29 Partition Communication Subsystem,Implementation Advice | |
9daee425 | 15550 | @anchor{gnat_rm/implementation_advice rm-f-7-cobol-support}@anchor{25e} |
64d5610f ML |
15551 | @section RM F(7): COBOL Support |
15552 | ||
15553 | ||
15554 | @quotation | |
15555 | ||
15556 | “If COBOL (respectively, C) is widely supported in the target | |
15557 | environment, implementations supporting the Information Systems Annex | |
15558 | should provide the child package @code{Interfaces.COBOL} (respectively, | |
15559 | @code{Interfaces.C}) specified in Annex B and should support a | |
15560 | @code{convention_identifier} of COBOL (respectively, C) in the interfacing | |
15561 | pragmas (see Annex B), thus allowing Ada programs to interface with | |
15562 | programs written in that language.” | |
15563 | @end quotation | |
15564 | ||
15565 | Followed. | |
15566 | ||
15567 | @geindex Decimal radix support | |
15568 | ||
15569 | @node RM F 1 2 Decimal Radix Support,RM G Numerics,RM F 7 COBOL Support,Implementation Advice | |
9daee425 | 15570 | @anchor{gnat_rm/implementation_advice rm-f-1-2-decimal-radix-support}@anchor{25f} |
64d5610f ML |
15571 | @section RM F.1(2): Decimal Radix Support |
15572 | ||
15573 | ||
15574 | @quotation | |
15575 | ||
15576 | “Packed decimal should be used as the internal representation for objects | |
15577 | of subtype @code{S} when @code{S}’Machine_Radix = 10.” | |
15578 | @end quotation | |
15579 | ||
15580 | Not followed. GNAT ignores @code{S}’Machine_Radix and always uses binary | |
15581 | representations. | |
15582 | ||
15583 | @geindex Numerics | |
15584 | ||
15585 | @node RM G Numerics,RM G 1 1 56-58 Complex Types,RM F 1 2 Decimal Radix Support,Implementation Advice | |
9daee425 | 15586 | @anchor{gnat_rm/implementation_advice rm-g-numerics}@anchor{260} |
64d5610f ML |
15587 | @section RM G: Numerics |
15588 | ||
15589 | ||
15590 | @quotation | |
15591 | ||
15592 | “If Fortran (respectively, C) is widely supported in the target | |
15593 | environment, implementations supporting the Numerics Annex | |
15594 | should provide the child package @code{Interfaces.Fortran} (respectively, | |
15595 | @code{Interfaces.C}) specified in Annex B and should support a | |
15596 | @code{convention_identifier} of Fortran (respectively, C) in the interfacing | |
15597 | pragmas (see Annex B), thus allowing Ada programs to interface with | |
15598 | programs written in that language.” | |
15599 | @end quotation | |
15600 | ||
15601 | Followed. | |
15602 | ||
15603 | @geindex Complex types | |
15604 | ||
15605 | @node RM G 1 1 56-58 Complex Types,RM G 1 2 49 Complex Elementary Functions,RM G Numerics,Implementation Advice | |
9daee425 | 15606 | @anchor{gnat_rm/implementation_advice rm-g-1-1-56-58-complex-types}@anchor{261} |
64d5610f ML |
15607 | @section RM G.1.1(56-58): Complex Types |
15608 | ||
15609 | ||
15610 | @quotation | |
15611 | ||
15612 | “Because the usual mathematical meaning of multiplication of a complex | |
15613 | operand and a real operand is that of the scaling of both components of | |
15614 | the former by the latter, an implementation should not perform this | |
15615 | operation by first promoting the real operand to complex type and then | |
15616 | performing a full complex multiplication. In systems that, in the | |
15617 | future, support an Ada binding to IEC 559:1989, the latter technique | |
15618 | will not generate the required result when one of the components of the | |
15619 | complex operand is infinite. (Explicit multiplication of the infinite | |
15620 | component by the zero component obtained during promotion yields a NaN | |
15621 | that propagates into the final result.) Analogous advice applies in the | |
15622 | case of multiplication of a complex operand and a pure-imaginary | |
15623 | operand, and in the case of division of a complex operand by a real or | |
15624 | pure-imaginary operand.” | |
15625 | @end quotation | |
15626 | ||
15627 | Not followed. | |
15628 | ||
15629 | @quotation | |
15630 | ||
15631 | “Similarly, because the usual mathematical meaning of addition of a | |
15632 | complex operand and a real operand is that the imaginary operand remains | |
15633 | unchanged, an implementation should not perform this operation by first | |
15634 | promoting the real operand to complex type and then performing a full | |
15635 | complex addition. In implementations in which the @code{Signed_Zeros} | |
15636 | attribute of the component type is @code{True} (and which therefore | |
15637 | conform to IEC 559:1989 in regard to the handling of the sign of zero in | |
15638 | predefined arithmetic operations), the latter technique will not | |
15639 | generate the required result when the imaginary component of the complex | |
15640 | operand is a negatively signed zero. (Explicit addition of the negative | |
15641 | zero to the zero obtained during promotion yields a positive zero.) | |
15642 | Analogous advice applies in the case of addition of a complex operand | |
15643 | and a pure-imaginary operand, and in the case of subtraction of a | |
15644 | complex operand and a real or pure-imaginary operand.” | |
15645 | @end quotation | |
15646 | ||
15647 | Not followed. | |
15648 | ||
15649 | @quotation | |
15650 | ||
15651 | “Implementations in which @code{Real'Signed_Zeros} is @code{True} should | |
15652 | attempt to provide a rational treatment of the signs of zero results and | |
15653 | result components. As one example, the result of the @code{Argument} | |
15654 | function should have the sign of the imaginary component of the | |
15655 | parameter @code{X} when the point represented by that parameter lies on | |
15656 | the positive real axis; as another, the sign of the imaginary component | |
15657 | of the @code{Compose_From_Polar} function should be the same as | |
15658 | (respectively, the opposite of) that of the @code{Argument} parameter when that | |
15659 | parameter has a value of zero and the @code{Modulus} parameter has a | |
15660 | nonnegative (respectively, negative) value.” | |
15661 | @end quotation | |
15662 | ||
15663 | Followed. | |
15664 | ||
15665 | @geindex Complex elementary functions | |
15666 | ||
15667 | @node RM G 1 2 49 Complex Elementary Functions,RM G 2 4 19 Accuracy Requirements,RM G 1 1 56-58 Complex Types,Implementation Advice | |
9daee425 | 15668 | @anchor{gnat_rm/implementation_advice rm-g-1-2-49-complex-elementary-functions}@anchor{262} |
64d5610f ML |
15669 | @section RM G.1.2(49): Complex Elementary Functions |
15670 | ||
15671 | ||
15672 | @quotation | |
15673 | ||
15674 | “Implementations in which @code{Complex_Types.Real'Signed_Zeros} is | |
15675 | @code{True} should attempt to provide a rational treatment of the signs | |
15676 | of zero results and result components. For example, many of the complex | |
15677 | elementary functions have components that are odd functions of one of | |
15678 | the parameter components; in these cases, the result component should | |
15679 | have the sign of the parameter component at the origin. Other complex | |
15680 | elementary functions have zero components whose sign is opposite that of | |
15681 | a parameter component at the origin, or is always positive or always | |
15682 | negative.” | |
15683 | @end quotation | |
15684 | ||
15685 | Followed. | |
15686 | ||
15687 | @geindex Accuracy requirements | |
15688 | ||
15689 | @node RM G 2 4 19 Accuracy Requirements,RM G 2 6 15 Complex Arithmetic Accuracy,RM G 1 2 49 Complex Elementary Functions,Implementation Advice | |
9daee425 | 15690 | @anchor{gnat_rm/implementation_advice rm-g-2-4-19-accuracy-requirements}@anchor{263} |
64d5610f ML |
15691 | @section RM G.2.4(19): Accuracy Requirements |
15692 | ||
15693 | ||
15694 | @quotation | |
15695 | ||
15696 | “The versions of the forward trigonometric functions without a | |
15697 | @code{Cycle} parameter should not be implemented by calling the | |
15698 | corresponding version with a @code{Cycle} parameter of | |
15699 | @code{2.0*Numerics.Pi}, since this will not provide the required | |
15700 | accuracy in some portions of the domain. For the same reason, the | |
15701 | version of @code{Log} without a @code{Base} parameter should not be | |
15702 | implemented by calling the corresponding version with a @code{Base} | |
15703 | parameter of @code{Numerics.e}.” | |
15704 | @end quotation | |
15705 | ||
15706 | Followed. | |
15707 | ||
15708 | @geindex Complex arithmetic accuracy | |
15709 | ||
15710 | @geindex Accuracy | |
15711 | @geindex complex arithmetic | |
15712 | ||
15713 | @node RM G 2 6 15 Complex Arithmetic Accuracy,RM H 6 15/2 Pragma Partition_Elaboration_Policy,RM G 2 4 19 Accuracy Requirements,Implementation Advice | |
9daee425 | 15714 | @anchor{gnat_rm/implementation_advice rm-g-2-6-15-complex-arithmetic-accuracy}@anchor{264} |
64d5610f ML |
15715 | @section RM G.2.6(15): Complex Arithmetic Accuracy |
15716 | ||
15717 | ||
15718 | @quotation | |
15719 | ||
15720 | “The version of the @code{Compose_From_Polar} function without a | |
15721 | @code{Cycle} parameter should not be implemented by calling the | |
15722 | corresponding version with a @code{Cycle} parameter of | |
15723 | @code{2.0*Numerics.Pi}, since this will not provide the required | |
15724 | accuracy in some portions of the domain.” | |
15725 | @end quotation | |
15726 | ||
15727 | Followed. | |
15728 | ||
15729 | @geindex Sequential elaboration policy | |
15730 | ||
15731 | @node RM H 6 15/2 Pragma Partition_Elaboration_Policy,,RM G 2 6 15 Complex Arithmetic Accuracy,Implementation Advice | |
9daee425 | 15732 | @anchor{gnat_rm/implementation_advice rm-h-6-15-2-pragma-partition-elaboration-policy}@anchor{265} |
64d5610f ML |
15733 | @section RM H.6(15/2): Pragma Partition_Elaboration_Policy |
15734 | ||
15735 | ||
15736 | @quotation | |
15737 | ||
15738 | “If the partition elaboration policy is @code{Sequential} and the | |
15739 | Environment task becomes permanently blocked during elaboration then the | |
15740 | partition is deadlocked and it is recommended that the partition be | |
15741 | immediately terminated.” | |
15742 | @end quotation | |
15743 | ||
15744 | Not followed. | |
15745 | ||
15746 | @node Implementation Defined Characteristics,Intrinsic Subprograms,Implementation Advice,Top | |
9daee425 | 15747 | @anchor{gnat_rm/implementation_defined_characteristics doc}@anchor{266}@anchor{gnat_rm/implementation_defined_characteristics id1}@anchor{267}@anchor{gnat_rm/implementation_defined_characteristics implementation-defined-characteristics}@anchor{b} |
64d5610f ML |
15748 | @chapter Implementation Defined Characteristics |
15749 | ||
15750 | ||
15751 | In addition to the implementation dependent pragmas and attributes, and the | |
15752 | implementation advice, there are a number of other Ada features that are | |
15753 | potentially implementation dependent and are designated as | |
15754 | implementation-defined. These are mentioned throughout the Ada Reference | |
15755 | Manual, and are summarized in Annex M. | |
15756 | ||
15757 | A requirement for conforming Ada compilers is that they provide | |
15758 | documentation describing how the implementation deals with each of these | |
15759 | issues. In this chapter you will find each point in Annex M listed, | |
15760 | followed by a description of how GNAT handles the implementation dependence. | |
15761 | ||
15762 | You can use this chapter as a guide to minimizing implementation | |
15763 | dependent features in your programs if portability to other compilers | |
15764 | and other operating systems is an important consideration. The numbers | |
15765 | in each entry below correspond to the paragraph numbers in the Ada | |
15766 | Reference Manual. | |
15767 | ||
15768 | ||
15769 | @itemize * | |
15770 | ||
15771 | @item | |
15772 | “Whether or not each recommendation given in Implementation | |
15773 | Advice is followed. See 1.1.2(37).” | |
15774 | @end itemize | |
15775 | ||
15776 | See @ref{a,,Implementation Advice}. | |
15777 | ||
15778 | ||
15779 | @itemize * | |
15780 | ||
15781 | @item | |
15782 | “Capacity limitations of the implementation. See 1.1.3(3).” | |
15783 | @end itemize | |
15784 | ||
15785 | The complexity of programs that can be processed is limited only by the | |
15786 | total amount of available virtual memory, and disk space for the | |
15787 | generated object files. | |
15788 | ||
15789 | ||
15790 | @itemize * | |
15791 | ||
15792 | @item | |
15793 | “Variations from the standard that are impractical to avoid | |
15794 | given the implementation’s execution environment. See 1.1.3(6).” | |
15795 | @end itemize | |
15796 | ||
15797 | There are no variations from the standard. | |
15798 | ||
15799 | ||
15800 | @itemize * | |
15801 | ||
15802 | @item | |
15803 | “Which code_statements cause external | |
15804 | interactions. See 1.1.3(10).” | |
15805 | @end itemize | |
15806 | ||
1acce141 | 15807 | Any @emph{code_statement} can potentially cause external interactions. |
64d5610f ML |
15808 | |
15809 | ||
15810 | @itemize * | |
15811 | ||
15812 | @item | |
15813 | “The coded representation for the text of an Ada | |
15814 | program. See 2.1(4).” | |
15815 | @end itemize | |
15816 | ||
15817 | See separate section on source representation. | |
15818 | ||
15819 | ||
15820 | @itemize * | |
15821 | ||
15822 | @item | |
15823 | “The semantics of an Ada program whose text is not in | |
15824 | Normalization Form C. See 2.1(4).” | |
15825 | @end itemize | |
15826 | ||
15827 | See separate section on source representation. | |
15828 | ||
15829 | ||
15830 | @itemize * | |
15831 | ||
15832 | @item | |
15833 | “The representation for an end of line. See 2.2(2).” | |
15834 | @end itemize | |
15835 | ||
15836 | See separate section on source representation. | |
15837 | ||
15838 | ||
15839 | @itemize * | |
15840 | ||
15841 | @item | |
15842 | “Maximum supported line length and lexical element | |
15843 | length. See 2.2(15).” | |
15844 | @end itemize | |
15845 | ||
15846 | The maximum line length is 255 characters and the maximum length of | |
15847 | a lexical element is also 255 characters. This is the default setting | |
1acce141 YM |
15848 | if not overridden by the use of compiler switch @emph{-gnaty} (which |
15849 | sets the maximum to 79) or @emph{-gnatyMnn} which allows the maximum | |
64d5610f ML |
15850 | line length to be specified to be any value up to 32767. The maximum |
15851 | length of a lexical element is the same as the maximum line length. | |
15852 | ||
15853 | ||
15854 | @itemize * | |
15855 | ||
15856 | @item | |
15857 | “Implementation defined pragmas. See 2.8(14).” | |
15858 | @end itemize | |
15859 | ||
15860 | See @ref{7,,Implementation Defined Pragmas}. | |
15861 | ||
15862 | ||
15863 | @itemize * | |
15864 | ||
15865 | @item | |
15866 | “Effect of pragma @code{Optimize}. See 2.8(27).” | |
15867 | @end itemize | |
15868 | ||
15869 | Pragma @code{Optimize}, if given with a @code{Time} or @code{Space} | |
15870 | parameter, checks that the optimization flag is set, and aborts if it is | |
15871 | not. | |
15872 | ||
15873 | ||
15874 | @itemize * | |
15875 | ||
15876 | @item | |
15877 | “The message string associated with the Assertion_Error exception raised | |
15878 | by the failure of a predicate check if there is no applicable | |
15879 | Predicate_Failure aspect. See 3.2.4(31).” | |
15880 | @end itemize | |
15881 | ||
15882 | In the case of a Dynamic_Predicate aspect, the string is | |
15883 | “Dynamic_Predicate failed at <source position>”, where | |
15884 | “<source position>” might be something like “foo.adb:123”. | |
15885 | The Static_Predicate case is handled analogously. | |
15886 | ||
15887 | ||
15888 | @itemize * | |
15889 | ||
15890 | @item | |
15891 | “The predefined integer types declared in | |
15892 | @code{Standard}. See 3.5.4(25).” | |
15893 | @end itemize | |
15894 | ||
15895 | ||
15896 | @multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} | |
15897 | @headitem | |
15898 | ||
15899 | Type | |
15900 | ||
15901 | @tab | |
15902 | ||
15903 | Representation | |
15904 | ||
15905 | @item | |
15906 | ||
1acce141 | 15907 | @emph{Short_Short_Integer} |
64d5610f ML |
15908 | |
15909 | @tab | |
15910 | ||
15911 | 8-bit signed | |
15912 | ||
15913 | @item | |
15914 | ||
1acce141 | 15915 | @emph{Short_Integer} |
64d5610f ML |
15916 | |
15917 | @tab | |
15918 | ||
15919 | 16-bit signed | |
15920 | ||
15921 | @item | |
15922 | ||
1acce141 | 15923 | @emph{Integer} |
64d5610f ML |
15924 | |
15925 | @tab | |
15926 | ||
15927 | 32-bit signed | |
15928 | ||
15929 | @item | |
15930 | ||
1acce141 | 15931 | @emph{Long_Integer} |
64d5610f ML |
15932 | |
15933 | @tab | |
15934 | ||
15935 | 64-bit signed (on most 64-bit targets, | |
15936 | depending on the C definition of long) | |
15937 | 32-bit signed (on all other targets) | |
15938 | ||
15939 | @item | |
15940 | ||
1acce141 | 15941 | @emph{Long_Long_Integer} |
64d5610f ML |
15942 | |
15943 | @tab | |
15944 | ||
15945 | 64-bit signed | |
15946 | ||
15947 | @item | |
15948 | ||
1acce141 | 15949 | @emph{Long_Long_Long_Integer} |
64d5610f ML |
15950 | |
15951 | @tab | |
15952 | ||
15953 | 128-bit signed (on 64-bit targets) | |
15954 | 64-bit signed (on 32-bit targets) | |
15955 | ||
15956 | @end multitable | |
15957 | ||
15958 | ||
15959 | ||
15960 | @itemize * | |
15961 | ||
15962 | @item | |
15963 | “Any nonstandard integer types and the operators defined | |
15964 | for them. See 3.5.4(26).” | |
15965 | @end itemize | |
15966 | ||
15967 | There are no nonstandard integer types. | |
15968 | ||
15969 | ||
15970 | @itemize * | |
15971 | ||
15972 | @item | |
15973 | “Any nonstandard real types and the operators defined for | |
15974 | them. See 3.5.6(8).” | |
15975 | @end itemize | |
15976 | ||
15977 | There are no nonstandard real types. | |
15978 | ||
15979 | ||
15980 | @itemize * | |
15981 | ||
15982 | @item | |
15983 | “What combinations of requested decimal precision and range | |
15984 | are supported for floating point types. See 3.5.7(7).” | |
15985 | @end itemize | |
15986 | ||
15987 | The precision and range are defined by the IEEE Standard for Floating-Point | |
15988 | Arithmetic (IEEE 754-2019). | |
15989 | ||
15990 | ||
15991 | @itemize * | |
15992 | ||
15993 | @item | |
15994 | “The predefined floating point types declared in | |
15995 | @code{Standard}. See 3.5.7(16).” | |
15996 | @end itemize | |
15997 | ||
15998 | ||
15999 | @multitable {xxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} | |
16000 | @headitem | |
16001 | ||
16002 | Type | |
16003 | ||
16004 | @tab | |
16005 | ||
16006 | Representation | |
16007 | ||
16008 | @item | |
16009 | ||
1acce141 | 16010 | @emph{Short_Float} |
64d5610f ML |
16011 | |
16012 | @tab | |
16013 | ||
16014 | IEEE Binary32 (Single) | |
16015 | ||
16016 | @item | |
16017 | ||
1acce141 | 16018 | @emph{Float} |
64d5610f ML |
16019 | |
16020 | @tab | |
16021 | ||
16022 | IEEE Binary32 (Single) | |
16023 | ||
16024 | @item | |
16025 | ||
1acce141 | 16026 | @emph{Long_Float} |
64d5610f ML |
16027 | |
16028 | @tab | |
16029 | ||
16030 | IEEE Binary64 (Double) | |
16031 | ||
16032 | @item | |
16033 | ||
1acce141 | 16034 | @emph{Long_Long_Float} |
64d5610f ML |
16035 | |
16036 | @tab | |
16037 | ||
16038 | IEEE Binary64 (Double) on non-x86 architectures | |
16039 | IEEE 80-bit Extended on x86 architecture | |
16040 | ||
16041 | @end multitable | |
16042 | ||
16043 | ||
16044 | The default rounding mode specified by the IEEE 754 Standard is assumed both | |
16045 | for static and dynamic computations (that is, round to nearest, ties to even). | |
16046 | The input routines yield correctly rounded values for Short_Float, Float, and | |
16047 | Long_Float at least. The output routines can compute up to twice as many exact | |
16048 | digits as the value of @code{T'Digits} for any type, for example 30 digits for | |
16049 | Long_Float; if more digits are requested, zeros are printed. | |
16050 | ||
16051 | ||
16052 | @itemize * | |
16053 | ||
16054 | @item | |
16055 | “The small of an ordinary fixed point type. See 3.5.9(8).” | |
16056 | @end itemize | |
16057 | ||
16058 | The small is the largest power of two that does not exceed the delta. | |
16059 | ||
16060 | ||
16061 | @itemize * | |
16062 | ||
16063 | @item | |
16064 | “What combinations of small, range, and digits are | |
16065 | supported for fixed point types. See 3.5.9(10).” | |
16066 | @end itemize | |
16067 | ||
16068 | For an ordinary fixed point type, on 32-bit platforms, the small must lie in | |
16069 | 2.0**(-80) .. 2.0**80 and the range in -9.0E+36 .. 9.0E+36; any combination | |
16070 | is permitted that does not result in a mantissa larger than 63 bits. | |
16071 | ||
16072 | On 64-bit platforms, the small must lie in 2.0**(-127) .. 2.0**127 and the | |
16073 | range in -1.0E+76 .. 1.0E+76; any combination is permitted that does not | |
16074 | result in a mantissa larger than 63 bits, and any combination is permitted | |
16075 | that results in a mantissa between 64 and 127 bits if the small is the | |
16076 | ratio of two integers that lie in 1 .. 2.0**127. | |
16077 | ||
16078 | If the small is the ratio of two integers with 64-bit magnitude on 32-bit | |
16079 | platforms and 128-bit magnitude on 64-bit platforms, which is the case if | |
16080 | no @code{small} clause is provided, then the operations of the fixed point | |
16081 | type are entirely implemented by means of integer instructions. In the | |
16082 | other cases, some operations, in particular input and output, may be | |
16083 | implemented by means of floating-point instructions and may be affected | |
16084 | by accuracy issues on architectures other than x86. | |
16085 | ||
16086 | For a decimal fixed point type, on 32-bit platforms, the small must lie in | |
16087 | 1.0E-18 .. 1.0E+18 and the digits in 1 .. 18. On 64-bit platforms, the | |
16088 | small must lie in 1.0E-38 .. 1.0E+38 and the digits in 1 .. 38. | |
16089 | ||
16090 | ||
16091 | @itemize * | |
16092 | ||
16093 | @item | |
16094 | “The result of @code{Tags.Expanded_Name} for types declared | |
1acce141 | 16095 | within an unnamed @emph{block_statement}. See 3.9(10).” |
64d5610f ML |
16096 | @end itemize |
16097 | ||
1acce141 | 16098 | Block numbers of the form @code{B@emph{nnn}}, where @emph{nnn} is a |
64d5610f ML |
16099 | decimal integer are allocated. |
16100 | ||
16101 | ||
16102 | @itemize * | |
16103 | ||
16104 | @item | |
16105 | “The sequence of characters of the value returned by Tags.Expanded_Name | |
16106 | (respectively, Tags.Wide_Expanded_Name) when some of the graphic | |
16107 | characters of Tags.Wide_Wide_Expanded_Name are not defined in Character | |
16108 | (respectively, Wide_Character). See 3.9(10.1).” | |
16109 | @end itemize | |
16110 | ||
16111 | This is handled in the same way as the implementation-defined behavior | |
16112 | referenced in A.4.12(34). | |
16113 | ||
16114 | ||
16115 | @itemize * | |
16116 | ||
16117 | @item | |
16118 | “Implementation-defined attributes. See 4.1.4(12).” | |
16119 | @end itemize | |
16120 | ||
16121 | See @ref{8,,Implementation Defined Attributes}. | |
16122 | ||
16123 | ||
16124 | @itemize * | |
16125 | ||
16126 | @item | |
16127 | “The value of the parameter to Empty for some container aggregates. | |
16128 | See 4.3.5(40).” | |
16129 | @end itemize | |
16130 | ||
16131 | As per the suggestion given in the Annotated Ada RM, the default value | |
16132 | of the formal parameter is used if one exists and zero is used otherwise. | |
16133 | ||
16134 | ||
16135 | @itemize * | |
16136 | ||
16137 | @item | |
16138 | “The maximum number of chunks for a parallel reduction expression without | |
16139 | a chunk_specification. See 4.5.10(21).” | |
16140 | @end itemize | |
16141 | ||
16142 | Feature unimplemented. | |
16143 | ||
16144 | ||
16145 | @itemize * | |
16146 | ||
16147 | @item | |
16148 | “Rounding of real static expressions which are exactly half-way between | |
16149 | two machine numbers. See 4.9(38).” | |
16150 | @end itemize | |
16151 | ||
16152 | Round to even is used in all such cases. | |
16153 | ||
16154 | ||
16155 | @itemize * | |
16156 | ||
16157 | @item | |
16158 | “The maximum number of chunks for a parallel generalized iterator without | |
16159 | a chunk_specification. See 5.5.2(10).” | |
16160 | @end itemize | |
16161 | ||
16162 | Feature unimplemented. | |
16163 | ||
16164 | ||
16165 | @itemize * | |
16166 | ||
16167 | @item | |
16168 | “The number of chunks for an array component iterator. See 5.5.2(11).” | |
16169 | @end itemize | |
16170 | ||
16171 | Feature unimplemented. | |
16172 | ||
16173 | ||
16174 | @itemize * | |
16175 | ||
16176 | @item | |
16177 | “Any extensions of the Global aspect. See 6.1.2(43).” | |
16178 | @end itemize | |
16179 | ||
16180 | Feature unimplemented. | |
16181 | ||
16182 | ||
16183 | @itemize * | |
16184 | ||
16185 | @item | |
16186 | “The circumstances the implementation passes in the null value for a view | |
16187 | conversion of an access type used as an out parameter. See 6.4.1(19).” | |
16188 | @end itemize | |
16189 | ||
16190 | Difficult to characterize. | |
16191 | ||
16192 | ||
16193 | @itemize * | |
16194 | ||
16195 | @item | |
16196 | “Any extensions of the Default_Initial_Condition aspect. See 7.3.3(11).” | |
16197 | @end itemize | |
16198 | ||
1acce141 | 16199 | SPARK allows specifying @emph{null} as the Default_Initial_Condition |
64d5610f ML |
16200 | aspect of a type. See the SPARK reference manual for further details. |
16201 | ||
16202 | ||
16203 | @itemize * | |
16204 | ||
16205 | @item | |
16206 | “Any implementation-defined time types. See 9.6(6).” | |
16207 | @end itemize | |
16208 | ||
16209 | There are no implementation-defined time types. | |
16210 | ||
16211 | ||
16212 | @itemize * | |
16213 | ||
16214 | @item | |
16215 | “The time base associated with relative delays. See 9.6(20).” | |
16216 | @end itemize | |
16217 | ||
16218 | See 9.6(20). The time base used is that provided by the C library | |
16219 | function @code{gettimeofday}. | |
16220 | ||
16221 | ||
16222 | @itemize * | |
16223 | ||
16224 | @item | |
16225 | “The time base of the type @code{Calendar.Time}. See 9.6(23).” | |
16226 | @end itemize | |
16227 | ||
16228 | The time base used is that provided by the C library function | |
16229 | @code{gettimeofday}. | |
16230 | ||
16231 | ||
16232 | @itemize * | |
16233 | ||
16234 | @item | |
16235 | “The time zone used for package @code{Calendar} | |
16236 | operations. See 9.6(24).” | |
16237 | @end itemize | |
16238 | ||
16239 | The time zone used by package @code{Calendar} is the current system time zone | |
16240 | setting for local time, as accessed by the C library function | |
16241 | @code{localtime}. | |
16242 | ||
16243 | ||
16244 | @itemize * | |
16245 | ||
16246 | @item | |
1acce141 YM |
16247 | “Any limit on @emph{delay_until_statements} of |
16248 | @emph{select_statements}. See 9.6(29).” | |
64d5610f ML |
16249 | @end itemize |
16250 | ||
16251 | There are no such limits. | |
16252 | ||
16253 | ||
16254 | @itemize * | |
16255 | ||
16256 | @item | |
16257 | “The result of Calendar.Formatting.Image if its argument represents more | |
16258 | than 100 hours. See 9.6.1(86).” | |
16259 | @end itemize | |
16260 | ||
16261 | Calendar.Time_Error is raised. | |
16262 | ||
16263 | ||
16264 | @itemize * | |
16265 | ||
16266 | @item | |
16267 | “Implementation-defined conflict check policies. See 9.10.1(5).” | |
16268 | @end itemize | |
16269 | ||
16270 | There are no implementation-defined conflict check policies. | |
16271 | ||
16272 | ||
16273 | @itemize * | |
16274 | ||
16275 | @item | |
16276 | “The representation for a compilation. See 10.1(2).” | |
16277 | @end itemize | |
16278 | ||
16279 | A compilation is represented by a sequence of files presented to the | |
1acce141 | 16280 | compiler in a single invocation of the @emph{gcc} command. |
64d5610f ML |
16281 | |
16282 | ||
16283 | @itemize * | |
16284 | ||
16285 | @item | |
16286 | “Any restrictions on compilations that contain multiple | |
16287 | compilation_units. See 10.1(4).” | |
16288 | @end itemize | |
16289 | ||
16290 | No single file can contain more than one compilation unit, but any | |
16291 | sequence of files can be presented to the compiler as a single | |
16292 | compilation. | |
16293 | ||
16294 | ||
16295 | @itemize * | |
16296 | ||
16297 | @item | |
16298 | “The mechanisms for creating an environment and for adding | |
16299 | and replacing compilation units. See 10.1.4(3).” | |
16300 | @end itemize | |
16301 | ||
16302 | See separate section on compilation model. | |
16303 | ||
16304 | ||
16305 | @itemize * | |
16306 | ||
16307 | @item | |
16308 | “The manner of explicitly assigning library units to a | |
16309 | partition. See 10.2(2).” | |
16310 | @end itemize | |
16311 | ||
16312 | If a unit contains an Ada main program, then the Ada units for the partition | |
16313 | are determined by recursive application of the rules in the Ada Reference | |
16314 | Manual section 10.2(2-6). In other words, the Ada units will be those that | |
16315 | are needed by the main program, and then this definition of need is applied | |
16316 | recursively to those units, and the partition contains the transitive | |
16317 | closure determined by this relationship. In short, all the necessary units | |
16318 | are included, with no need to explicitly specify the list. If additional | |
16319 | units are required, e.g., by foreign language units, then all units must be | |
16320 | mentioned in the context clause of one of the needed Ada units. | |
16321 | ||
16322 | If the partition contains no main program, or if the main program is in | |
16323 | a language other than Ada, then GNAT | |
1acce141 | 16324 | provides the binder options @emph{-z} and @emph{-n} respectively, and in |
64d5610f ML |
16325 | this case a list of units can be explicitly supplied to the binder for |
16326 | inclusion in the partition (all units needed by these units will also | |
16327 | be included automatically). For full details on the use of these | |
1acce141 | 16328 | options, refer to @emph{GNAT Make Program gnatmake} in the |
64d5610f ML |
16329 | @cite{GNAT User’s Guide}. |
16330 | ||
16331 | ||
16332 | @itemize * | |
16333 | ||
16334 | @item | |
16335 | “The implementation-defined means, if any, of specifying which compilation | |
16336 | units are needed by a given compilation unit. See 10.2(2).” | |
16337 | @end itemize | |
16338 | ||
16339 | The units needed by a given compilation unit are as defined in | |
16340 | the Ada Reference Manual section 10.2(2-6). There are no | |
16341 | implementation-defined pragmas or other implementation-defined | |
16342 | means for specifying needed units. | |
16343 | ||
16344 | ||
16345 | @itemize * | |
16346 | ||
16347 | @item | |
16348 | “The manner of designating the main subprogram of a | |
16349 | partition. See 10.2(7).” | |
16350 | @end itemize | |
16351 | ||
16352 | The main program is designated by providing the name of the | |
16353 | corresponding @code{ALI} file as the input parameter to the binder. | |
16354 | ||
16355 | ||
16356 | @itemize * | |
16357 | ||
16358 | @item | |
1acce141 | 16359 | “The order of elaboration of @emph{library_items}. See 10.2(18).” |
64d5610f ML |
16360 | @end itemize |
16361 | ||
16362 | The first constraint on ordering is that it meets the requirements of | |
16363 | Chapter 10 of the Ada Reference Manual. This still leaves some | |
16364 | implementation-dependent choices, which are resolved by analyzing | |
16365 | the elaboration code of each unit and identifying implicit | |
16366 | elaboration-order dependencies. | |
16367 | ||
16368 | ||
16369 | @itemize * | |
16370 | ||
16371 | @item | |
16372 | “Parameter passing and function return for the main | |
16373 | subprogram. See 10.2(21).” | |
16374 | @end itemize | |
16375 | ||
16376 | The main program has no parameters. It may be a procedure, or a function | |
16377 | returning an integer type. In the latter case, the returned integer | |
16378 | value is the return code of the program (overriding any value that | |
16379 | may have been set by a call to @code{Ada.Command_Line.Set_Exit_Status}). | |
16380 | ||
16381 | ||
16382 | @itemize * | |
16383 | ||
16384 | @item | |
16385 | “The mechanisms for building and running partitions. See 10.2(24).” | |
16386 | @end itemize | |
16387 | ||
16388 | GNAT itself supports programs with only a single partition. The GNATDIST | |
16389 | tool provided with the GLADE package (which also includes an implementation | |
16390 | of the PCS) provides a completely flexible method for building and running | |
16391 | programs consisting of multiple partitions. See the separate GLADE manual | |
16392 | for details. | |
16393 | ||
16394 | ||
16395 | @itemize * | |
16396 | ||
16397 | @item | |
16398 | “The details of program execution, including program | |
16399 | termination. See 10.2(25).” | |
16400 | @end itemize | |
16401 | ||
16402 | See separate section on compilation model. | |
16403 | ||
16404 | ||
16405 | @itemize * | |
16406 | ||
16407 | @item | |
16408 | “The semantics of any non-active partitions supported by the | |
16409 | implementation. See 10.2(28).” | |
16410 | @end itemize | |
16411 | ||
16412 | Passive partitions are supported on targets where shared memory is | |
16413 | provided by the operating system. See the GLADE reference manual for | |
16414 | further details. | |
16415 | ||
16416 | ||
16417 | @itemize * | |
16418 | ||
16419 | @item | |
16420 | “The information returned by @code{Exception_Message}. See 11.4.1(10).” | |
16421 | @end itemize | |
16422 | ||
16423 | Exception message returns the null string unless a specific message has | |
16424 | been passed by the program. | |
16425 | ||
16426 | ||
16427 | @itemize * | |
16428 | ||
16429 | @item | |
16430 | “The result of @code{Exceptions.Exception_Name} for types | |
1acce141 | 16431 | declared within an unnamed @emph{block_statement}. See 11.4.1(12).” |
64d5610f ML |
16432 | @end itemize |
16433 | ||
1acce141 YM |
16434 | Blocks have implementation defined names of the form @code{B@emph{nnn}} |
16435 | where @emph{nnn} is an integer. | |
64d5610f ML |
16436 | |
16437 | ||
16438 | @itemize * | |
16439 | ||
16440 | @item | |
16441 | “The information returned by | |
16442 | @code{Exception_Information}. See 11.4.1(13).” | |
16443 | @end itemize | |
16444 | ||
16445 | @code{Exception_Information} returns a string in the following format: | |
16446 | ||
16447 | @example | |
16448 | *Exception_Name:* nnnnn | |
16449 | *Message:* mmmmm | |
16450 | *PID:* ppp | |
16451 | *Load address:* 0xhhhh | |
16452 | *Call stack traceback locations:* | |
16453 | 0xhhhh 0xhhhh 0xhhhh ... 0xhhh | |
16454 | @end example | |
16455 | ||
16456 | where | |
16457 | ||
16458 | @quotation | |
16459 | ||
16460 | ||
16461 | @itemize * | |
16462 | ||
16463 | @item | |
16464 | @code{nnnn} is the fully qualified name of the exception in all upper | |
16465 | case letters. This line is always present. | |
16466 | ||
16467 | @item | |
16468 | @code{mmmm} is the message (this line present only if message is non-null) | |
16469 | ||
16470 | @item | |
16471 | @code{ppp} is the Process Id value as a decimal integer (this line is | |
16472 | present only if the Process Id is nonzero). Currently we are | |
16473 | not making use of this field. | |
16474 | ||
16475 | @item | |
16476 | The Load address line, the Call stack traceback locations line and the | |
16477 | following values are present only if at least one traceback location was | |
16478 | recorded. The Load address indicates the address at which the main executable | |
16479 | was loaded; this line may not be present if operating system hasn’t relocated | |
16480 | the main executable. The values are given in C style format, with lower case | |
16481 | letters for a-f, and only as many digits present as are necessary. | |
16482 | The line terminator sequence at the end of each line, including | |
16483 | the last line is a single @code{LF} character (@code{16#0A#}). | |
16484 | @end itemize | |
16485 | @end quotation | |
16486 | ||
16487 | ||
16488 | @itemize * | |
16489 | ||
16490 | @item | |
16491 | “The sequence of characters of the value returned by | |
16492 | Exceptions.Exception_Name (respectively, Exceptions.Wide_Exception_Name) | |
16493 | when some of the graphic characters of Exceptions.Wide_Wide_Exception_Name | |
16494 | are not defined in Character (respectively, Wide_Character). | |
16495 | See 11.4.1(12.1).” | |
16496 | @end itemize | |
16497 | ||
16498 | This is handled in the same way as the implementation-defined behavior | |
16499 | referenced in A.4.12(34). | |
16500 | ||
16501 | ||
16502 | @itemize * | |
16503 | ||
16504 | @item | |
16505 | “The information returned by Exception_Information. See 11.4.1(13).” | |
16506 | @end itemize | |
16507 | ||
16508 | The exception name and the source location at which the exception was | |
16509 | raised are included. | |
16510 | ||
16511 | ||
16512 | @itemize * | |
16513 | ||
16514 | @item | |
16515 | “Implementation-defined policy_identifiers and assertion_aspect_marks | |
16516 | allowed in a pragma Assertion_Policy. See 11.4.2(9).” | |
16517 | @end itemize | |
16518 | ||
16519 | Implementation-defined assertion_aspect_marks include Assert_And_Cut, | |
16520 | Assume, Contract_Cases, Debug, Ghost, Initial_Condition, Loop_Invariant, | |
16521 | Loop_Variant, Postcondition, Precondition, Predicate, Refined_Post, | |
16522 | Statement_Assertions, and Subprogram_Variant. Implementation-defined | |
16523 | policy_identifiers include Ignore and Suppressible. | |
16524 | ||
16525 | ||
16526 | @itemize * | |
16527 | ||
16528 | @item | |
16529 | “The default assertion policy. See 11.4.2(10).” | |
16530 | @end itemize | |
16531 | ||
16532 | The default assertion policy is Ignore, although this can be overridden | |
16533 | via compiler switches such as “-gnata”. | |
16534 | ||
16535 | ||
16536 | @itemize * | |
16537 | ||
16538 | @item | |
16539 | “Implementation-defined check names. See 11.5(27).” | |
16540 | @end itemize | |
16541 | ||
16542 | The implementation defined check names include Alignment_Check, | |
16543 | Atomic_Synchronization, Duplicated_Tag_Check, Container_Checks, | |
16544 | Tampering_Check, Predicate_Check, and Validity_Check. In addition, a user | |
16545 | program can add implementation-defined check names by means of the pragma | |
16546 | Check_Name. See the description of pragma @code{Suppress} for full details. | |
16547 | ||
16548 | ||
16549 | @itemize * | |
16550 | ||
16551 | @item | |
16552 | “Existence and meaning of second parameter of pragma Unsuppress. | |
16553 | See 11.5(27.1).” | |
16554 | @end itemize | |
16555 | ||
16556 | The legality rules for and semantics of the second parameter of pragma | |
16557 | Unsuppress match those for the second argument of pragma Suppress. | |
16558 | ||
16559 | ||
16560 | @itemize * | |
16561 | ||
16562 | @item | |
16563 | “The cases that cause conflicts between the representation of the | |
16564 | ancestors of a type_declaration. See 13.1(13.1).” | |
16565 | @end itemize | |
16566 | ||
16567 | No such cases exist. | |
16568 | ||
16569 | ||
16570 | @itemize * | |
16571 | ||
16572 | @item | |
16573 | “The interpretation of each representation aspect. See 13.1(20).” | |
16574 | @end itemize | |
16575 | ||
16576 | See separate section on data representations. | |
16577 | ||
16578 | ||
16579 | @itemize * | |
16580 | ||
16581 | @item | |
16582 | “Any restrictions placed upon the specification of representation aspects. | |
16583 | See 13.1(20).” | |
16584 | @end itemize | |
16585 | ||
16586 | See separate section on data representations. | |
16587 | ||
16588 | ||
16589 | @itemize * | |
16590 | ||
16591 | @item | |
16592 | “Implementation-defined aspects, including the syntax for specifying | |
16593 | such aspects and the legality rules for such aspects. See 13.1.1(38).” | |
16594 | @end itemize | |
16595 | ||
9daee425 | 16596 | See @ref{126,,Implementation Defined Aspects}. |
64d5610f ML |
16597 | |
16598 | ||
16599 | @itemize * | |
16600 | ||
16601 | @item | |
16602 | “The set of machine scalars. See 13.3(8.1).” | |
16603 | @end itemize | |
16604 | ||
16605 | See separate section on data representations. | |
16606 | ||
16607 | ||
16608 | @itemize * | |
16609 | ||
16610 | @item | |
16611 | “The meaning of @code{Size} for indefinite subtypes. See 13.3(48).” | |
16612 | @end itemize | |
16613 | ||
16614 | The Size attribute of an indefinite subtype is not less than the Size | |
16615 | attribute of any object of that type. | |
16616 | ||
16617 | ||
16618 | @itemize * | |
16619 | ||
16620 | @item | |
16621 | “The meaning of Object_Size for indefinite subtypes. See 13.3(58).” | |
16622 | @end itemize | |
16623 | ||
16624 | The Object_Size attribute of an indefinite subtype is not less than the | |
16625 | Object_Size attribute of any object of that type. | |
16626 | ||
16627 | ||
16628 | @itemize * | |
16629 | ||
16630 | @item | |
16631 | “The default external representation for a type tag. See 13.3(75).” | |
16632 | @end itemize | |
16633 | ||
16634 | The default external representation for a type tag is the fully expanded | |
16635 | name of the type in upper case letters. | |
16636 | ||
16637 | ||
16638 | @itemize * | |
16639 | ||
16640 | @item | |
16641 | “What determines whether a compilation unit is the same in | |
16642 | two different partitions. See 13.3(76).” | |
16643 | @end itemize | |
16644 | ||
16645 | A compilation unit is the same in two different partitions if and only | |
16646 | if it derives from the same source file. | |
16647 | ||
16648 | ||
16649 | @itemize * | |
16650 | ||
16651 | @item | |
16652 | “Implementation-defined components. See 13.5.1(15).” | |
16653 | @end itemize | |
16654 | ||
16655 | The only implementation defined component is the tag for a tagged type, | |
16656 | which contains a pointer to the dispatching table. | |
16657 | ||
16658 | ||
16659 | @itemize * | |
16660 | ||
16661 | @item | |
16662 | “If @code{Word_Size} = @code{Storage_Unit}, the default bit | |
16663 | ordering. See 13.5.3(5).” | |
16664 | @end itemize | |
16665 | ||
16666 | @code{Word_Size} (32) is not the same as @code{Storage_Unit} (8) for this | |
16667 | implementation, so no non-default bit ordering is supported. The default | |
16668 | bit ordering corresponds to the natural endianness of the target architecture. | |
16669 | ||
16670 | ||
16671 | @itemize * | |
16672 | ||
16673 | @item | |
16674 | “The contents of the visible part of package @code{System}. See 13.7(2).” | |
16675 | @end itemize | |
16676 | ||
16677 | See the definition of package System in @code{system.ads}. | |
16678 | Note that two declarations are added to package System. | |
16679 | ||
16680 | @example | |
16681 | Max_Priority : constant Positive := Priority'Last; | |
16682 | Max_Interrupt_Priority : constant Positive := Interrupt_Priority'Last; | |
16683 | @end example | |
16684 | ||
16685 | ||
16686 | @itemize * | |
16687 | ||
16688 | @item | |
16689 | “The range of Storage_Elements.Storage_Offset, the modulus of | |
16690 | Storage_Elements.Storage_Element, and the declaration of | |
16691 | Storage_Elements.Integer_Address. See 13.7.1(11).” | |
16692 | @end itemize | |
16693 | ||
16694 | See the definition of package System.Storage_Elements in @code{s-stoele.ads}. | |
16695 | ||
16696 | ||
16697 | @itemize * | |
16698 | ||
16699 | @item | |
16700 | “The contents of the visible part of package @code{System.Machine_Code}, | |
1acce141 | 16701 | and the meaning of @emph{code_statements}. See 13.8(7).” |
64d5610f ML |
16702 | @end itemize |
16703 | ||
16704 | See the definition and documentation in file @code{s-maccod.ads}. | |
16705 | ||
16706 | ||
16707 | @itemize * | |
16708 | ||
16709 | @item | |
16710 | “The result of unchecked conversion for instances with scalar result | |
16711 | types whose result is not defined by the language. See 13.9(11).” | |
16712 | @end itemize | |
16713 | ||
16714 | Unchecked conversion between types of the same size | |
16715 | results in an uninterpreted transmission of the bits from one type | |
16716 | to the other. If the types are of unequal sizes, then in the case of | |
16717 | discrete types, a shorter source is first zero or sign extended as | |
16718 | necessary, and a shorter target is simply truncated on the left. | |
16719 | For all non-discrete types, the source is first copied if necessary | |
16720 | to ensure that the alignment requirements of the target are met, then | |
16721 | a pointer is constructed to the source value, and the result is obtained | |
16722 | by dereferencing this pointer after converting it to be a pointer to the | |
16723 | target type. Unchecked conversions where the target subtype is an | |
16724 | unconstrained array are not permitted. If the target alignment is | |
16725 | greater than the source alignment, then a copy of the result is | |
16726 | made with appropriate alignment | |
16727 | ||
16728 | ||
16729 | @itemize * | |
16730 | ||
16731 | @item | |
16732 | “The result of unchecked conversion for instances with nonscalar result | |
16733 | types whose result is not defined by the language. See 13.9(11).” | |
16734 | @end itemize | |
16735 | ||
16736 | See preceding definition for the scalar result case. | |
16737 | ||
16738 | ||
16739 | @itemize * | |
16740 | ||
16741 | @item | |
16742 | “Whether or not the implementation provides user-accessible | |
16743 | names for the standard pool type(s). See 13.11(17).” | |
16744 | @end itemize | |
16745 | ||
16746 | There are 3 different standard pools used by the compiler when | |
16747 | @code{Storage_Pool} is not specified depending whether the type is local | |
16748 | to a subprogram or defined at the library level and whether | |
16749 | @code{Storage_Size`@w{`}is specified or not. See documentation in the runtime | |
16750 | library units `@w{`}System.Pool_Global}, @code{System.Pool_Size} and | |
16751 | @code{System.Pool_Local} in files @code{s-poosiz.ads}, | |
16752 | @code{s-pooglo.ads} and @code{s-pooloc.ads} for full details on the | |
16753 | default pools used. All these pools are accessible by means of @cite{with}ing | |
16754 | these units. | |
16755 | ||
16756 | ||
16757 | @itemize * | |
16758 | ||
16759 | @item | |
16760 | “The meaning of @code{Storage_Size} when neither the Storage_Size nor the | |
16761 | Storage_Pool is specified for an access type. See 13.11(18).” | |
16762 | @end itemize | |
16763 | ||
16764 | @code{Storage_Size} is measured in storage units, and refers to the | |
16765 | total space available for an access type collection, or to the primary | |
16766 | stack space for a task. | |
16767 | ||
16768 | ||
16769 | @itemize * | |
16770 | ||
16771 | @item | |
16772 | “The effect of specifying aspect Default_Storage_Pool on an instance | |
16773 | of a language-defined generic unit. See 13.11.3(5).” | |
16774 | @end itemize | |
16775 | ||
16776 | Instances of language-defined generic units are treated the same as other | |
16777 | instances with respect to the Default_Storage_Pool aspect. | |
16778 | ||
16779 | ||
16780 | @itemize * | |
16781 | ||
16782 | @item | |
16783 | “Implementation-defined restrictions allowed in a pragma | |
16784 | @code{Restrictions}. See 13.12(8.7).” | |
16785 | @end itemize | |
16786 | ||
16787 | See @ref{9,,Standard and Implementation Defined Restrictions}. | |
16788 | ||
16789 | ||
16790 | @itemize * | |
16791 | ||
16792 | @item | |
16793 | “The consequences of violating limitations on | |
16794 | @code{Restrictions} pragmas. See 13.12(9).” | |
16795 | @end itemize | |
16796 | ||
16797 | Restrictions that can be checked at compile time are enforced at | |
16798 | compile time; violations are illegal. For other restrictions, any | |
16799 | violation during program execution results in erroneous execution. | |
16800 | ||
16801 | ||
16802 | @itemize * | |
16803 | ||
16804 | @item | |
16805 | “Implementation-defined usage profiles allowed in a pragma Profile. | |
16806 | See 13.12(15).” | |
16807 | @end itemize | |
16808 | ||
16809 | See @ref{7,,Implementation Defined Pragmas}. | |
16810 | ||
16811 | ||
16812 | @itemize * | |
16813 | ||
16814 | @item | |
16815 | “The contents of the stream elements read and written by the Read and | |
16816 | Write attributes of elementary types. See 13.13.2(9).” | |
16817 | @end itemize | |
16818 | ||
16819 | The representation is the in-memory representation of the base type of | |
16820 | the type, using the number of bits corresponding to the | |
16821 | @code{type'Size} value, and the natural ordering of the machine. | |
16822 | ||
16823 | ||
16824 | @itemize * | |
16825 | ||
16826 | @item | |
16827 | “The names and characteristics of the numeric subtypes | |
16828 | declared in the visible part of package @code{Standard}. See A.1(3).” | |
16829 | @end itemize | |
16830 | ||
16831 | See items describing the integer and floating-point types supported. | |
16832 | ||
16833 | ||
16834 | @itemize * | |
16835 | ||
16836 | @item | |
16837 | “The values returned by Strings.Hash. See A.4.9(3).” | |
16838 | @end itemize | |
16839 | ||
16840 | This hash function has predictable collisions and is subject to | |
16841 | equivalent substring attacks. It is not suitable for construction of a | |
16842 | hash table keyed on possibly malicious user input. | |
16843 | ||
16844 | ||
16845 | @itemize * | |
16846 | ||
16847 | @item | |
16848 | “The value returned by a call to a Text_Buffer Get procedure if any | |
16849 | character in the returned sequence is not defined in Character. | |
16850 | See A.4.12(34).” | |
16851 | @end itemize | |
16852 | ||
16853 | The contents of a buffer is represented internally as a UTF_8 string. | |
16854 | The value return by Text_Buffer.Get is the result of passing that | |
16855 | UTF_8 string to UTF_Encoding.Strings.Decode. | |
16856 | ||
16857 | ||
16858 | @itemize * | |
16859 | ||
16860 | @item | |
16861 | “The value returned by a call to a Text_Buffer Wide_Get procedure if | |
16862 | any character in the returned sequence is not defined in Wide_Character. | |
16863 | See A.4.12(34).” | |
16864 | @end itemize | |
16865 | ||
16866 | The contents of a buffer is represented internally as a UTF_8 string. | |
16867 | The value return by Text_Buffer.Wide_Get is the result of passing that | |
16868 | UTF_8 string to UTF_Encoding.Wide_Strings.Decode. | |
16869 | ||
16870 | ||
16871 | @itemize * | |
16872 | ||
16873 | @item | |
16874 | “The accuracy actually achieved by the elementary | |
16875 | functions. See A.5.1(1).” | |
16876 | @end itemize | |
16877 | ||
16878 | The elementary functions correspond to the functions available in the C | |
16879 | library. Only fast math mode is implemented. | |
16880 | ||
16881 | ||
16882 | @itemize * | |
16883 | ||
16884 | @item | |
16885 | “The sign of a zero result from some of the operators or | |
16886 | functions in @code{Numerics.Generic_Elementary_Functions}, when | |
16887 | @code{Float_Type'Signed_Zeros} is @code{True}. See A.5.1(46).” | |
16888 | @end itemize | |
16889 | ||
16890 | The sign of zeroes follows the requirements of the IEEE 754 standard on | |
16891 | floating-point. | |
16892 | ||
16893 | ||
16894 | @itemize * | |
16895 | ||
16896 | @item | |
16897 | “The value of | |
16898 | @code{Numerics.Float_Random.Max_Image_Width}. See A.5.2(27).” | |
16899 | @end itemize | |
16900 | ||
16901 | Maximum image width is 6864, see library file @code{s-rannum.ads}. | |
16902 | ||
16903 | ||
16904 | @itemize * | |
16905 | ||
16906 | @item | |
16907 | “The value of | |
16908 | @code{Numerics.Discrete_Random.Max_Image_Width}. See A.5.2(27).” | |
16909 | @end itemize | |
16910 | ||
16911 | Maximum image width is 6864, see library file @code{s-rannum.ads}. | |
16912 | ||
16913 | ||
16914 | @itemize * | |
16915 | ||
16916 | @item | |
16917 | “The string representation of a random number generator’s | |
16918 | state. See A.5.2(38).” | |
16919 | @end itemize | |
16920 | ||
16921 | The value returned by the Image function is the concatenation of | |
16922 | the fixed-width decimal representations of the 624 32-bit integers | |
16923 | of the state vector. | |
16924 | ||
16925 | ||
16926 | @itemize * | |
16927 | ||
16928 | @item | |
16929 | “The values of the @code{Model_Mantissa}, | |
16930 | @code{Model_Emin}, @code{Model_Epsilon}, @code{Model}, | |
16931 | @code{Safe_First}, and @code{Safe_Last} attributes, if the Numerics | |
16932 | Annex is not supported. See A.5.3(72).” | |
16933 | @end itemize | |
16934 | ||
1acce141 | 16935 | Running the compiler with @emph{-gnatS} to produce a listing of package |
64d5610f ML |
16936 | @code{Standard} displays the values of these attributes. |
16937 | ||
16938 | ||
16939 | @itemize * | |
16940 | ||
16941 | @item | |
16942 | “The value of @code{Buffer_Size} in @code{Storage_IO}. See A.9(10).” | |
16943 | @end itemize | |
16944 | ||
16945 | All type representations are contiguous, and the @code{Buffer_Size} is | |
16946 | the value of @code{type'Size} rounded up to the next storage unit | |
16947 | boundary. | |
16948 | ||
16949 | ||
16950 | @itemize * | |
16951 | ||
16952 | @item | |
16953 | “External files for standard input, standard output, and | |
16954 | standard error See A.10(5).” | |
16955 | @end itemize | |
16956 | ||
16957 | These files are mapped onto the files provided by the C streams | |
16958 | libraries. See source file @code{i-cstrea.ads} for further details. | |
16959 | ||
16960 | ||
16961 | @itemize * | |
16962 | ||
16963 | @item | |
16964 | “The accuracy of the value produced by @code{Put}. See A.10.9(36).” | |
16965 | @end itemize | |
16966 | ||
16967 | If more digits are requested in the output than are represented by the | |
16968 | precision of the value, zeroes are output in the corresponding least | |
16969 | significant digit positions. | |
16970 | ||
16971 | ||
16972 | @itemize * | |
16973 | ||
16974 | @item | |
16975 | “Current size for a stream file for which positioning is not supported. | |
16976 | See A.12.1(1.1).” | |
16977 | @end itemize | |
16978 | ||
16979 | Positioning is supported. | |
16980 | ||
16981 | ||
16982 | @itemize * | |
16983 | ||
16984 | @item | |
16985 | “The meaning of @code{Argument_Count}, @code{Argument}, and | |
16986 | @code{Command_Name}. See A.15(1).” | |
16987 | @end itemize | |
16988 | ||
16989 | These are mapped onto the @code{argv} and @code{argc} parameters of the | |
16990 | main program in the natural manner. | |
16991 | ||
16992 | ||
16993 | @itemize * | |
16994 | ||
16995 | @item | |
16996 | “The interpretation of file names and directory names. See A.16(46).” | |
16997 | @end itemize | |
16998 | ||
16999 | These names are interpreted consistently with the underlying file system. | |
17000 | ||
17001 | ||
17002 | @itemize * | |
17003 | ||
17004 | @item | |
17005 | “The maxium value for a file size in Directories. See A.16(87).” | |
17006 | @end itemize | |
17007 | ||
17008 | Directories.File_Size’Last is equal to Long_Long_Integer’Last . | |
17009 | ||
17010 | ||
17011 | @itemize * | |
17012 | ||
17013 | @item | |
17014 | “The result for Directories.Size for a directory or special file. | |
17015 | See A.16(93).” | |
17016 | @end itemize | |
17017 | ||
17018 | Name_Error is raised. | |
17019 | ||
17020 | ||
17021 | @itemize * | |
17022 | ||
17023 | @item | |
17024 | “The result for Directories.Modification_Time for a directory or special file. | |
17025 | See A.16(93).” | |
17026 | @end itemize | |
17027 | ||
17028 | Name_Error is raised. | |
17029 | ||
17030 | ||
17031 | @itemize * | |
17032 | ||
17033 | @item | |
17034 | “The interpretation of a nonnull search pattern in Directories. | |
17035 | See A.16(104).” | |
17036 | @end itemize | |
17037 | ||
17038 | When the @code{Pattern} parameter is not the null string, it is interpreted | |
17039 | according to the syntax of regular expressions as defined in the | |
17040 | @code{GNAT.Regexp} package. | |
17041 | ||
9daee425 | 17042 | See @ref{268,,GNAT.Regexp (g-regexp.ads)}. |
64d5610f ML |
17043 | |
17044 | ||
17045 | @itemize * | |
17046 | ||
17047 | @item | |
17048 | “The results of a Directories search if the contents of the directory are | |
17049 | altered while a search is in progress. See A.16(110).” | |
17050 | @end itemize | |
17051 | ||
17052 | The effect of a call to Get_Next_Entry is determined by the current | |
17053 | state of the directory. | |
17054 | ||
17055 | ||
17056 | @itemize * | |
17057 | ||
17058 | @item | |
17059 | “The definition and meaning of an environment variable. See A.17(1).” | |
17060 | @end itemize | |
17061 | ||
17062 | This definition is determined by the underlying operating system. | |
17063 | ||
17064 | ||
17065 | @itemize * | |
17066 | ||
17067 | @item | |
17068 | “The circumstances where an environment variable cannot be defined. | |
17069 | See A.17(16).” | |
f571a201 | 17070 | @end itemize |
64d5610f ML |
17071 | |
17072 | There are no such implementation-defined circumstances. | |
17073 | ||
f571a201 RD |
17074 | |
17075 | @itemize * | |
17076 | ||
64d5610f ML |
17077 | @item |
17078 | “Environment names for which Set has the effect of Clear. See A.17(17).” | |
17079 | @end itemize | |
17080 | ||
17081 | There are no such names. | |
17082 | ||
17083 | ||
17084 | @itemize * | |
17085 | ||
17086 | @item | |
17087 | “The value of Containers.Hash_Type’Modulus. The value of | |
17088 | Containers.Count_Type’Last. See A.18.1(7).” | |
17089 | @end itemize | |
17090 | ||
17091 | Containers.Hash_Type’Modulus is 2**32. | |
17092 | Containers.Count_Type’Last is 2**31 - 1. | |
17093 | ||
17094 | ||
17095 | @itemize * | |
17096 | ||
17097 | @item | |
17098 | “Implementation-defined convention names. See B.1(11).” | |
17099 | @end itemize | |
17100 | ||
17101 | The following convention names are supported | |
17102 | ||
17103 | ||
17104 | @multitable {xxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} | |
17105 | @headitem | |
17106 | ||
17107 | Convention Name | |
17108 | ||
17109 | @tab | |
17110 | ||
17111 | Interpretation | |
17112 | ||
17113 | @item | |
17114 | ||
1acce141 | 17115 | @emph{Ada} |
64d5610f ML |
17116 | |
17117 | @tab | |
17118 | ||
17119 | Ada | |
17120 | ||
17121 | @item | |
17122 | ||
1acce141 | 17123 | @emph{Ada_Pass_By_Copy} |
64d5610f ML |
17124 | |
17125 | @tab | |
17126 | ||
17127 | Allowed for any types except by-reference types such as limited | |
17128 | records. Compatible with convention Ada, but causes any parameters | |
17129 | with this convention to be passed by copy. | |
17130 | ||
17131 | @item | |
17132 | ||
1acce141 | 17133 | @emph{Ada_Pass_By_Reference} |
64d5610f ML |
17134 | |
17135 | @tab | |
17136 | ||
17137 | Allowed for any types except by-copy types such as scalars. | |
17138 | Compatible with convention Ada, but causes any parameters | |
17139 | with this convention to be passed by reference. | |
17140 | ||
17141 | @item | |
17142 | ||
1acce141 | 17143 | @emph{Assembler} |
64d5610f ML |
17144 | |
17145 | @tab | |
17146 | ||
17147 | Assembly language | |
17148 | ||
17149 | @item | |
17150 | ||
1acce141 | 17151 | @emph{Asm} |
64d5610f ML |
17152 | |
17153 | @tab | |
17154 | ||
17155 | Synonym for Assembler | |
17156 | ||
17157 | @item | |
17158 | ||
1acce141 | 17159 | @emph{Assembly} |
64d5610f ML |
17160 | |
17161 | @tab | |
17162 | ||
17163 | Synonym for Assembler | |
17164 | ||
17165 | @item | |
17166 | ||
1acce141 | 17167 | @emph{C} |
64d5610f ML |
17168 | |
17169 | @tab | |
17170 | ||
17171 | C | |
17172 | ||
17173 | @item | |
17174 | ||
1acce141 | 17175 | @emph{C_Pass_By_Copy} |
64d5610f ML |
17176 | |
17177 | @tab | |
17178 | ||
17179 | Allowed only for record types, like C, but also notes that record | |
17180 | is to be passed by copy rather than reference. | |
17181 | ||
17182 | @item | |
17183 | ||
1acce141 | 17184 | @emph{COBOL} |
64d5610f ML |
17185 | |
17186 | @tab | |
17187 | ||
17188 | COBOL | |
17189 | ||
17190 | @item | |
17191 | ||
1acce141 | 17192 | @emph{C_Plus_Plus (or CPP)} |
64d5610f ML |
17193 | |
17194 | @tab | |
17195 | ||
17196 | C++ | |
17197 | ||
17198 | @item | |
17199 | ||
1acce141 | 17200 | @emph{Default} |
64d5610f ML |
17201 | |
17202 | @tab | |
17203 | ||
17204 | Treated the same as C | |
17205 | ||
17206 | @item | |
17207 | ||
1acce141 | 17208 | @emph{External} |
64d5610f ML |
17209 | |
17210 | @tab | |
17211 | ||
17212 | Treated the same as C | |
17213 | ||
17214 | @item | |
17215 | ||
1acce141 | 17216 | @emph{Fortran} |
64d5610f ML |
17217 | |
17218 | @tab | |
17219 | ||
17220 | Fortran | |
17221 | ||
17222 | @item | |
17223 | ||
1acce141 | 17224 | @emph{Intrinsic} |
64d5610f ML |
17225 | |
17226 | @tab | |
17227 | ||
17228 | For support of pragma @code{Import} with convention Intrinsic, see | |
17229 | separate section on Intrinsic Subprograms. | |
17230 | ||
17231 | @item | |
17232 | ||
1acce141 | 17233 | @emph{Stdcall} |
64d5610f ML |
17234 | |
17235 | @tab | |
17236 | ||
17237 | Stdcall (used for Windows implementations only). This convention correspond | |
17238 | to the WINAPI (previously called Pascal convention) C/C++ convention under | |
17239 | Windows. A routine with this convention cleans the stack before | |
17240 | exit. This pragma cannot be applied to a dispatching call. | |
17241 | ||
17242 | @item | |
17243 | ||
1acce141 | 17244 | @emph{DLL} |
64d5610f ML |
17245 | |
17246 | @tab | |
17247 | ||
17248 | Synonym for Stdcall | |
17249 | ||
17250 | @item | |
17251 | ||
1acce141 | 17252 | @emph{Win32} |
64d5610f ML |
17253 | |
17254 | @tab | |
17255 | ||
17256 | Synonym for Stdcall | |
17257 | ||
17258 | @item | |
17259 | ||
1acce141 | 17260 | @emph{Stubbed} |
64d5610f ML |
17261 | |
17262 | @tab | |
17263 | ||
17264 | Stubbed is a special convention used to indicate that the body of the | |
17265 | subprogram will be entirely ignored. Any call to the subprogram | |
17266 | is converted into a raise of the @code{Program_Error} exception. If a | |
17267 | pragma @code{Import} specifies convention @code{stubbed} then no body need | |
17268 | be present at all. This convention is useful during development for the | |
17269 | inclusion of subprograms whose body has not yet been written. | |
17270 | In addition, all otherwise unrecognized convention names are also | |
17271 | treated as being synonymous with convention C. In all implementations, | |
17272 | use of such other names results in a warning. | |
17273 | ||
17274 | @end multitable | |
17275 | ||
17276 | ||
17277 | ||
17278 | @itemize * | |
17279 | ||
17280 | @item | |
17281 | “The meaning of link names. See B.1(36).” | |
17282 | @end itemize | |
17283 | ||
17284 | Link names are the actual names used by the linker. | |
17285 | ||
17286 | ||
17287 | @itemize * | |
17288 | ||
17289 | @item | |
17290 | “The manner of choosing link names when neither the link name nor the | |
17291 | address of an imported or exported entity is specified. See B.1(36).” | |
17292 | @end itemize | |
17293 | ||
17294 | The default linker name is that which would be assigned by the relevant | |
17295 | external language, interpreting the Ada name as being in all lower case | |
17296 | letters. | |
17297 | ||
17298 | ||
17299 | @itemize * | |
17300 | ||
17301 | @item | |
17302 | “The effect of pragma @code{Linker_Options}. See B.1(37).” | |
17303 | @end itemize | |
17304 | ||
17305 | The string passed to @code{Linker_Options} is presented uninterpreted as | |
17306 | an argument to the link command, unless it contains ASCII.NUL characters. | |
17307 | NUL characters if they appear act as argument separators, so for example | |
17308 | ||
17309 | @example | |
17310 | pragma Linker_Options ("-labc" & ASCII.NUL & "-ldef"); | |
17311 | @end example | |
17312 | ||
17313 | causes two separate arguments @code{-labc} and @code{-ldef} to be passed to the | |
17314 | linker. The order of linker options is preserved for a given unit. The final | |
17315 | list of options passed to the linker is in reverse order of the elaboration | |
17316 | order. For example, linker options for a body always appear before the options | |
17317 | from the corresponding package spec. | |
17318 | ||
17319 | ||
17320 | @itemize * | |
17321 | ||
17322 | @item | |
17323 | “The contents of the visible part of package | |
17324 | @code{Interfaces} and its language-defined descendants. See B.2(1).” | |
17325 | @end itemize | |
17326 | ||
17327 | See files with prefix @code{i-} in the distributed library. | |
17328 | ||
17329 | ||
17330 | @itemize * | |
17331 | ||
17332 | @item | |
17333 | “Implementation-defined children of package | |
17334 | @code{Interfaces}. The contents of the visible part of package | |
17335 | @code{Interfaces}. See B.2(11).” | |
17336 | @end itemize | |
17337 | ||
17338 | See files with prefix @code{i-} in the distributed library. | |
17339 | ||
17340 | ||
17341 | @itemize * | |
17342 | ||
17343 | @item | |
17344 | “The definitions of certain types and constants in Interfaces.C. | |
17345 | See B.3(41).” | |
17346 | @end itemize | |
17347 | ||
17348 | See source file @code{i-c.ads}. | |
17349 | ||
17350 | ||
17351 | @itemize * | |
17352 | ||
17353 | @item | |
17354 | “The types @code{Floating}, @code{Long_Floating}, | |
17355 | @code{Binary}, @code{Long_Binary}, @code{Decimal_ Element}, and | |
17356 | @code{COBOL_Character}; and the initialization of the variables | |
17357 | @code{Ada_To_COBOL} and @code{COBOL_To_Ada}, in | |
17358 | @code{Interfaces.COBOL}. See B.4(50).” | |
17359 | @end itemize | |
17360 | ||
17361 | ||
17362 | @multitable {xxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} | |
17363 | @headitem | |
17364 | ||
17365 | COBOL | |
17366 | ||
17367 | @tab | |
17368 | ||
17369 | Ada | |
17370 | ||
17371 | @item | |
17372 | ||
1acce141 | 17373 | @emph{Floating} |
64d5610f ML |
17374 | |
17375 | @tab | |
17376 | ||
17377 | Float | |
17378 | ||
17379 | @item | |
17380 | ||
1acce141 | 17381 | @emph{Long_Floating} |
64d5610f ML |
17382 | |
17383 | @tab | |
17384 | ||
17385 | (Floating) Long_Float | |
17386 | ||
17387 | @item | |
17388 | ||
1acce141 | 17389 | @emph{Binary} |
64d5610f ML |
17390 | |
17391 | @tab | |
17392 | ||
17393 | Integer | |
17394 | ||
17395 | @item | |
17396 | ||
1acce141 | 17397 | @emph{Long_Binary} |
64d5610f ML |
17398 | |
17399 | @tab | |
17400 | ||
17401 | Long_Long_Integer | |
17402 | ||
17403 | @item | |
17404 | ||
1acce141 | 17405 | @emph{Decimal_Element} |
64d5610f ML |
17406 | |
17407 | @tab | |
17408 | ||
17409 | Character | |
17410 | ||
17411 | @item | |
17412 | ||
1acce141 | 17413 | @emph{COBOL_Character} |
64d5610f ML |
17414 | |
17415 | @tab | |
17416 | ||
17417 | Character | |
17418 | ||
17419 | @end multitable | |
17420 | ||
17421 | ||
17422 | For initialization, see the file @code{i-cobol.ads} in the distributed library. | |
17423 | ||
17424 | ||
17425 | @itemize * | |
17426 | ||
17427 | @item | |
17428 | “The types Fortran_Integer, Real, Double_Precision, and Character_Set | |
17429 | in Interfaces.Fortran. See B.5(17).” | |
17430 | @end itemize | |
17431 | ||
17432 | See source file @code{i-fortra.ads}. These types are derived, respectively, | |
17433 | from Integer, Float, Long_Float, and Character. | |
17434 | ||
17435 | ||
17436 | @itemize * | |
17437 | ||
17438 | @item | |
17439 | “Implementation-defined intrinsic subprograms. See C.1(1).” | |
17440 | @end itemize | |
17441 | ||
17442 | See separate section on Intrinsic Subprograms. | |
17443 | ||
17444 | ||
17445 | @itemize * | |
17446 | ||
17447 | @item | |
17448 | “Any restrictions on a protected procedure or its containing type when an | |
17449 | aspect Attach_handler or Interrupt_Handler is specified. See C.3.1(17).” | |
17450 | @end itemize | |
17451 | ||
17452 | There are no such restrictions. | |
17453 | ||
17454 | ||
17455 | @itemize * | |
17456 | ||
17457 | @item | |
17458 | “Any other forms of interrupt handler supported by the Attach_Handler and | |
17459 | Interrupt_Handler aspects. See C.3.1(19).” | |
17460 | @end itemize | |
17461 | ||
17462 | There are no such forms. | |
17463 | ||
17464 | ||
17465 | @itemize * | |
17466 | ||
17467 | @item | |
17468 | “The semantics of some attributes and functions of an entity for which | |
17469 | aspect Discard_Names is True. See C.5(7).” | |
17470 | @end itemize | |
17471 | ||
17472 | If Discard_Names is True for an enumeration type, the Image attribute | |
17473 | provides the image of the Pos of the literal, and Value accepts | |
17474 | Pos values. | |
17475 | ||
17476 | If both of the aspects`@w{`}Discard_Names`@w{`} and @code{No_Tagged_Streams} are true | |
17477 | for a tagged type, its Expanded_Name and External_Tag values are | |
17478 | empty strings. This is useful to avoid exposing entity names at binary | |
17479 | level. | |
17480 | ||
17481 | ||
17482 | @itemize * | |
17483 | ||
17484 | @item | |
17485 | “The modulus and size of Test_and_Set_Flag. See C.6.3(8).” | |
17486 | @end itemize | |
17487 | ||
17488 | The modulus is 2**8. The size is 8. | |
17489 | ||
17490 | ||
17491 | @itemize * | |
17492 | ||
17493 | @item | |
17494 | “The value used to represent the set value for Atomic_Test_and_Set. | |
17495 | See C.6.3(10).” | |
17496 | @end itemize | |
17497 | ||
17498 | The value is 1. | |
17499 | ||
17500 | ||
17501 | @itemize * | |
17502 | ||
17503 | @item | |
17504 | “The result of the @code{Task_Identification.Image} | |
17505 | attribute. See C.7.1(7).” | |
17506 | @end itemize | |
17507 | ||
17508 | The result of this attribute is a string that identifies | |
17509 | the object or component that denotes a given task. If a variable @code{Var} | |
1acce141 YM |
17510 | has a task type, the image for this task will have the form @code{Var_@emph{XXXXXXXX}}, |
17511 | where the suffix @emph{XXXXXXXX} | |
64d5610f ML |
17512 | is the hexadecimal representation of the virtual address of the corresponding |
17513 | task control block. If the variable is an array of tasks, the image of each | |
17514 | task will have the form of an indexed component indicating the position of a | |
1acce141 | 17515 | given task in the array, e.g., @code{Group(5)_@emph{XXXXXXX}}. If the task is a |
64d5610f ML |
17516 | component of a record, the image of the task will have the form of a selected |
17517 | component. These rules are fully recursive, so that the image of a task that | |
17518 | is a subcomponent of a composite object corresponds to the expression that | |
17519 | designates this task. | |
17520 | ||
17521 | If a task is created by an allocator, its image depends on the context. If the | |
17522 | allocator is part of an object declaration, the rules described above are used | |
17523 | to construct its image, and this image is not affected by subsequent | |
17524 | assignments. If the allocator appears within an expression, the image | |
17525 | includes only the name of the task type. | |
17526 | ||
17527 | If the configuration pragma Discard_Names is present, or if the restriction | |
17528 | No_Implicit_Heap_Allocation is in effect, the image reduces to | |
17529 | the numeric suffix, that is to say the hexadecimal representation of the | |
17530 | virtual address of the control block of the task. | |
17531 | ||
17532 | ||
17533 | @itemize * | |
17534 | ||
17535 | @item | |
17536 | “The value of @code{Current_Task} when in a protected entry | |
17537 | or interrupt handler. See C.7.1(17).” | |
17538 | @end itemize | |
17539 | ||
17540 | Protected entries or interrupt handlers can be executed by any | |
17541 | convenient thread, so the value of @code{Current_Task} is undefined. | |
17542 | ||
17543 | ||
17544 | @itemize * | |
17545 | ||
17546 | @item | |
17547 | “Granularity of locking for Task_Attributes. See C.7.2(16).” | |
17548 | @end itemize | |
17549 | ||
17550 | No locking is needed if the formal type Attribute has the size and | |
17551 | alignment of either Integer or System.Address and the bit representation | |
17552 | of Initial_Value is all zeroes. Otherwise, locking is performed. | |
17553 | ||
17554 | ||
17555 | @itemize * | |
17556 | ||
17557 | @item | |
17558 | “The declarations of @code{Any_Priority} and | |
17559 | @code{Priority}. See D.1(11).” | |
17560 | @end itemize | |
17561 | ||
17562 | See declarations in file @code{system.ads}. | |
17563 | ||
17564 | ||
17565 | @itemize * | |
17566 | ||
17567 | @item | |
17568 | “Implementation-defined execution resources. See D.1(15).” | |
17569 | @end itemize | |
17570 | ||
17571 | There are no implementation-defined execution resources. | |
17572 | ||
17573 | ||
17574 | @itemize * | |
17575 | ||
17576 | @item | |
17577 | “Whether, on a multiprocessor, a task that is waiting for | |
17578 | access to a protected object keeps its processor busy. See D.2.1(3).” | |
17579 | @end itemize | |
17580 | ||
17581 | On a multi-processor, a task that is waiting for access to a protected | |
17582 | object does not keep its processor busy. | |
17583 | ||
17584 | ||
17585 | @itemize * | |
17586 | ||
17587 | @item | |
17588 | “The affect of implementation defined execution resources | |
17589 | on task dispatching. See D.2.1(9).” | |
17590 | @end itemize | |
17591 | ||
17592 | Tasks map to threads in the threads package used by GNAT. Where possible | |
17593 | and appropriate, these threads correspond to native threads of the | |
17594 | underlying operating system. | |
17595 | ||
17596 | ||
17597 | @itemize * | |
17598 | ||
17599 | @item | |
17600 | “Implementation-defined task dispatching policies. See D.2.2(3).” | |
17601 | @end itemize | |
17602 | ||
17603 | There are no implementation-defined task dispatching policies. | |
17604 | ||
17605 | ||
17606 | @itemize * | |
17607 | ||
17608 | @item | |
17609 | “The value of Default_Quantum in Dispatching.Round_Robin. See D.2.5(4).” | |
17610 | @end itemize | |
17611 | ||
17612 | The value is 10 milliseconds. | |
17613 | ||
17614 | ||
17615 | @itemize * | |
17616 | ||
17617 | @item | |
1acce141 | 17618 | “Implementation-defined @emph{policy_identifiers} allowed |
64d5610f ML |
17619 | in a pragma @code{Locking_Policy}. See D.3(4).” |
17620 | @end itemize | |
17621 | ||
17622 | The two implementation defined policies permitted in GNAT are | |
17623 | @code{Inheritance_Locking} and @code{Concurrent_Readers_Locking}. On | |
17624 | targets that support the @code{Inheritance_Locking} policy, locking is | |
17625 | implemented by inheritance, i.e., the task owning the lock operates | |
17626 | at a priority equal to the highest priority of any task currently | |
17627 | requesting the lock. On targets that support the | |
17628 | @code{Concurrent_Readers_Locking} policy, locking is implemented with a | |
17629 | read/write lock allowing multiple protected object functions to enter | |
17630 | concurrently. | |
17631 | ||
17632 | ||
17633 | @itemize * | |
17634 | ||
17635 | @item | |
17636 | “Default ceiling priorities. See D.3(10).” | |
17637 | @end itemize | |
17638 | ||
17639 | The ceiling priority of protected objects of the type | |
17640 | @code{System.Interrupt_Priority'Last} as described in the Ada | |
17641 | Reference Manual D.3(10), | |
17642 | ||
17643 | ||
17644 | @itemize * | |
17645 | ||
17646 | @item | |
17647 | “The ceiling of any protected object used internally by | |
17648 | the implementation. See D.3(16).” | |
17649 | @end itemize | |
17650 | ||
17651 | The ceiling priority of internal protected objects is | |
17652 | @code{System.Priority'Last}. | |
17653 | ||
17654 | ||
17655 | @itemize * | |
17656 | ||
17657 | @item | |
17658 | “Implementation-defined queuing policies. See D.4(1).” | |
17659 | @end itemize | |
17660 | ||
17661 | There are no implementation-defined queuing policies. | |
17662 | ||
17663 | ||
17664 | @itemize * | |
17665 | ||
17666 | @item | |
17667 | “Implementation-defined admission policies. See D.4.1(1).” | |
17668 | @end itemize | |
17669 | ||
17670 | There are no implementation-defined admission policies. | |
17671 | ||
17672 | ||
17673 | @itemize * | |
17674 | ||
17675 | @item | |
17676 | “Any operations that implicitly require heap storage | |
17677 | allocation. See D.7(8).” | |
17678 | @end itemize | |
17679 | ||
17680 | The only operation that implicitly requires heap storage allocation is | |
17681 | task creation. | |
17682 | ||
17683 | ||
17684 | @itemize * | |
17685 | ||
17686 | @item | |
17687 | “When restriction No_Dynamic_CPU_Assignment applies to a partition, the | |
17688 | processor on which a task with a CPU value of a Not_A_Specific_CPU will | |
17689 | execute. See D.7(10).” | |
17690 | @end itemize | |
17691 | ||
17692 | Unknown. | |
17693 | ||
17694 | ||
17695 | @itemize * | |
17696 | ||
17697 | @item | |
17698 | “When restriction No_Task_Termination applies to a partition, what happens | |
17699 | when a task terminates. See D.7(15.1).” | |
17700 | @end itemize | |
17701 | ||
17702 | Execution is erroneous in that case. | |
17703 | ||
17704 | ||
17705 | @itemize * | |
17706 | ||
17707 | @item | |
17708 | “The behavior when restriction Max_Storage_At_Blocking is violated. | |
17709 | See D.7(17).” | |
17710 | @end itemize | |
17711 | ||
17712 | Execution is erroneous in that case. | |
17713 | ||
17714 | ||
17715 | @itemize * | |
17716 | ||
17717 | @item | |
17718 | “The behavior when restriction Max_Asynchronous_Select_Nesting is violated. | |
17719 | See D.7(18).” | |
17720 | @end itemize | |
17721 | ||
17722 | Execution is erroneous in that case. | |
17723 | ||
17724 | ||
17725 | @itemize * | |
17726 | ||
17727 | @item | |
17728 | “The behavior when restriction Max_Tasks is violated. See D.7(19).” | |
17729 | @end itemize | |
17730 | ||
17731 | Execution is erroneous in that case. | |
17732 | ||
17733 | ||
17734 | @itemize * | |
17735 | ||
17736 | @item | |
17737 | “Whether the use of pragma Restrictions results in a reduction in program | |
17738 | code or data size or execution time. See D.7(20).” | |
f571a201 | 17739 | @end itemize |
64d5610f ML |
17740 | |
17741 | Yes it can, but the precise circumstances and properties of such reductions | |
17742 | are difficult to characterize. | |
17743 | ||
f571a201 RD |
17744 | |
17745 | @itemize * | |
17746 | ||
64d5610f ML |
17747 | @item |
17748 | “The value of Barrier_Limit’Last in Synchronous_Barriers. See D.10.1(4).” | |
17749 | @end itemize | |
17750 | ||
17751 | Synchronous_Barriers.Barrier_Limit’Last is Integer’Last . | |
17752 | ||
17753 | ||
17754 | @itemize * | |
17755 | ||
17756 | @item | |
17757 | “When an aborted task that is waiting on a Synchronous_Barrier is aborted. | |
17758 | See D.10.1(13).” | |
17759 | @end itemize | |
17760 | ||
17761 | Difficult to characterize. | |
17762 | ||
17763 | ||
17764 | @itemize * | |
17765 | ||
17766 | @item | |
17767 | “The value of Min_Handler_Ceiling in Execution_Time.Group_Budgets. | |
17768 | See D.14.2(7).” | |
17769 | @end itemize | |
17770 | ||
17771 | See source file @code{a-etgrbu.ads}. | |
17772 | ||
17773 | ||
17774 | @itemize * | |
17775 | ||
17776 | @item | |
17777 | “The value of CPU_Range’Last in System.Multiprocessors. See D.16(4).” | |
17778 | @end itemize | |
17779 | ||
17780 | See source file @code{s-multip.ads}. | |
17781 | ||
17782 | ||
17783 | @itemize * | |
17784 | ||
17785 | @item | |
17786 | “The processor on which the environment task executes in the absence | |
17787 | of a value for the aspect CPU. See D.16(13).” | |
17788 | @end itemize | |
17789 | ||
17790 | Unknown. | |
17791 | ||
17792 | ||
17793 | @itemize * | |
17794 | ||
17795 | @item | |
17796 | “The means for creating and executing distributed | |
17797 | programs. See E(5).” | |
17798 | @end itemize | |
17799 | ||
17800 | The GLADE package provides a utility GNATDIST for creating and executing | |
17801 | distributed programs. See the GLADE reference manual for further details. | |
17802 | ||
17803 | ||
17804 | @itemize * | |
17805 | ||
17806 | @item | |
17807 | “Any events that can result in a partition becoming | |
17808 | inaccessible. See E.1(7).” | |
17809 | @end itemize | |
17810 | ||
17811 | See the GLADE reference manual for full details on such events. | |
17812 | ||
17813 | ||
17814 | @itemize * | |
17815 | ||
17816 | @item | |
17817 | “The scheduling policies, treatment of priorities, and management of | |
17818 | shared resources between partitions in certain cases. See E.1(11).” | |
17819 | @end itemize | |
17820 | ||
17821 | See the GLADE reference manual for full details on these aspects of | |
17822 | multi-partition execution. | |
17823 | ||
17824 | ||
17825 | @itemize * | |
17826 | ||
17827 | @item | |
17828 | “Whether the execution of the remote subprogram is | |
17829 | immediately aborted as a result of cancellation. See E.4(13).” | |
17830 | @end itemize | |
17831 | ||
17832 | See the GLADE reference manual for details on the effect of abort in | |
17833 | a distributed application. | |
17834 | ||
17835 | ||
17836 | @itemize * | |
17837 | ||
17838 | @item | |
17839 | “The range of type System.RPC.Partition_Id. See E.5(14).” | |
17840 | @end itemize | |
17841 | ||
17842 | System.RPC.Partition_ID’Last is Integer’Last. See source file @code{s-rpc.ads}. | |
17843 | ||
17844 | ||
17845 | @itemize * | |
17846 | ||
17847 | @item | |
17848 | “Implementation-defined interfaces in the PCS. See E.5(26).” | |
17849 | @end itemize | |
17850 | ||
17851 | See the GLADE reference manual for a full description of all | |
17852 | implementation defined interfaces. | |
17853 | ||
17854 | ||
17855 | @itemize * | |
17856 | ||
17857 | @item | |
17858 | “The values of named numbers in the package | |
17859 | @code{Decimal}. See F.2(7).” | |
17860 | @end itemize | |
17861 | ||
17862 | ||
17863 | @multitable {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxx} | |
17864 | @headitem | |
17865 | ||
17866 | Named Number | |
17867 | ||
17868 | @tab | |
17869 | ||
17870 | Value | |
17871 | ||
17872 | @item | |
17873 | ||
1acce141 | 17874 | @emph{Max_Scale} |
64d5610f ML |
17875 | |
17876 | @tab | |
17877 | ||
17878 | +18 | |
17879 | ||
17880 | @item | |
17881 | ||
1acce141 | 17882 | @emph{Min_Scale} |
64d5610f ML |
17883 | |
17884 | @tab | |
17885 | ||
17886 | -18 | |
17887 | ||
17888 | @item | |
17889 | ||
1acce141 | 17890 | @emph{Min_Delta} |
64d5610f ML |
17891 | |
17892 | @tab | |
17893 | ||
17894 | 1.0E-18 | |
17895 | ||
17896 | @item | |
17897 | ||
1acce141 | 17898 | @emph{Max_Delta} |
64d5610f ML |
17899 | |
17900 | @tab | |
17901 | ||
17902 | 1.0E+18 | |
17903 | ||
17904 | @item | |
17905 | ||
1acce141 | 17906 | @emph{Max_Decimal_Digits} |
64d5610f ML |
17907 | |
17908 | @tab | |
17909 | ||
17910 | 18 | |
17911 | ||
17912 | @end multitable | |
17913 | ||
17914 | ||
17915 | ||
17916 | @itemize * | |
17917 | ||
17918 | @item | |
17919 | “The value of @code{Max_Picture_Length} in the package | |
17920 | @code{Text_IO.Editing}. See F.3.3(16).” | |
17921 | ||
17922 | 64 | |
17923 | ||
17924 | @item | |
17925 | “The value of @code{Max_Picture_Length} in the package | |
17926 | @code{Wide_Text_IO.Editing}. See F.3.4(5).” | |
17927 | ||
17928 | 64 | |
17929 | ||
17930 | @item | |
17931 | “The accuracy actually achieved by the complex elementary | |
17932 | functions and by other complex arithmetic operations. See G.1(1).” | |
17933 | @end itemize | |
17934 | ||
17935 | Standard library functions are used for the complex arithmetic | |
17936 | operations. Only fast math mode is currently supported. | |
17937 | ||
17938 | ||
17939 | @itemize * | |
17940 | ||
17941 | @item | |
17942 | “The sign of a zero result (or a component thereof) from | |
17943 | any operator or function in @code{Numerics.Generic_Complex_Types}, when | |
17944 | @code{Real'Signed_Zeros} is True. See G.1.1(53).” | |
17945 | @end itemize | |
17946 | ||
17947 | The signs of zero values are as recommended by the relevant | |
17948 | implementation advice. | |
17949 | ||
17950 | ||
17951 | @itemize * | |
17952 | ||
17953 | @item | |
17954 | “The sign of a zero result (or a component thereof) from | |
17955 | any operator or function in | |
17956 | @code{Numerics.Generic_Complex_Elementary_Functions}, when | |
17957 | @code{Real'Signed_Zeros} is @code{True}. See G.1.2(45).” | |
17958 | @end itemize | |
17959 | ||
17960 | The signs of zero values are as recommended by the relevant | |
17961 | implementation advice. | |
17962 | ||
17963 | ||
17964 | @itemize * | |
17965 | ||
17966 | @item | |
17967 | “Whether the strict mode or the relaxed mode is the | |
17968 | default. See G.2(2).” | |
17969 | @end itemize | |
17970 | ||
17971 | The strict mode is the default. There is no separate relaxed mode. GNAT | |
17972 | provides a highly efficient implementation of strict mode. | |
17973 | ||
17974 | ||
17975 | @itemize * | |
17976 | ||
17977 | @item | |
17978 | “The result interval in certain cases of fixed-to-float | |
17979 | conversion. See G.2.1(10).” | |
17980 | @end itemize | |
17981 | ||
17982 | For cases where the result interval is implementation dependent, the | |
17983 | accuracy is that provided by performing all operations in 64-bit IEEE | |
17984 | floating-point format. | |
17985 | ||
17986 | ||
17987 | @itemize * | |
17988 | ||
17989 | @item | |
17990 | “The result of a floating point arithmetic operation in | |
17991 | overflow situations, when the @code{Machine_Overflows} attribute of the | |
17992 | result type is @code{False}. See G.2.1(13).” | |
17993 | @end itemize | |
17994 | ||
17995 | Infinite and NaN values are produced as dictated by the IEEE | |
17996 | floating-point standard. | |
17997 | Note that on machines that are not fully compliant with the IEEE | |
1acce141 | 17998 | floating-point standard, such as Alpha, the @emph{-mieee} compiler flag |
64d5610f ML |
17999 | must be used for achieving IEEE conforming behavior (although at the cost |
18000 | of a significant performance penalty), so infinite and NaN values are | |
18001 | properly generated. | |
18002 | ||
18003 | ||
18004 | @itemize * | |
18005 | ||
18006 | @item | |
18007 | “The result interval for division (or exponentiation by a | |
18008 | negative exponent), when the floating point hardware implements division | |
18009 | as multiplication by a reciprocal. See G.2.1(16).” | |
18010 | @end itemize | |
18011 | ||
18012 | Not relevant, division is IEEE exact. | |
18013 | ||
18014 | ||
18015 | @itemize * | |
18016 | ||
18017 | @item | |
18018 | “The definition of close result set, which determines the accuracy of | |
18019 | certain fixed point multiplications and divisions. See G.2.3(5).” | |
18020 | @end itemize | |
18021 | ||
18022 | Operations in the close result set are performed using IEEE long format | |
18023 | floating-point arithmetic. The input operands are converted to | |
18024 | floating-point, the operation is done in floating-point, and the result | |
18025 | is converted to the target type. | |
18026 | ||
18027 | ||
18028 | @itemize * | |
18029 | ||
18030 | @item | |
1acce141 | 18031 | “Conditions on a @emph{universal_real} operand of a fixed |
64d5610f ML |
18032 | point multiplication or division for which the result shall be in the |
18033 | perfect result set. See G.2.3(22).” | |
18034 | @end itemize | |
18035 | ||
18036 | The result is only defined to be in the perfect result set if the result | |
18037 | can be computed by a single scaling operation involving a scale factor | |
18038 | representable in 64 bits. | |
18039 | ||
18040 | ||
18041 | @itemize * | |
18042 | ||
18043 | @item | |
18044 | “The result of a fixed point arithmetic operation in | |
18045 | overflow situations, when the @code{Machine_Overflows} attribute of the | |
18046 | result type is @code{False}. See G.2.3(27).” | |
18047 | @end itemize | |
18048 | ||
18049 | Not relevant, @code{Machine_Overflows} is @code{True} for fixed-point | |
18050 | types. | |
18051 | ||
18052 | ||
18053 | @itemize * | |
18054 | ||
18055 | @item | |
18056 | “The result of an elementary function reference in | |
18057 | overflow situations, when the @code{Machine_Overflows} attribute of the | |
18058 | result type is @code{False}. See G.2.4(4).” | |
18059 | @end itemize | |
18060 | ||
18061 | IEEE infinite and Nan values are produced as appropriate. | |
18062 | ||
18063 | ||
18064 | @itemize * | |
18065 | ||
18066 | @item | |
18067 | “The value of the angle threshold, within which certain | |
18068 | elementary functions, complex arithmetic operations, and complex | |
18069 | elementary functions yield results conforming to a maximum relative | |
18070 | error bound. See G.2.4(10).” | |
18071 | @end itemize | |
18072 | ||
18073 | Information on this subject is not yet available. | |
18074 | ||
18075 | ||
18076 | @itemize * | |
18077 | ||
18078 | @item | |
18079 | “The accuracy of certain elementary functions for | |
18080 | parameters beyond the angle threshold. See G.2.4(10).” | |
18081 | @end itemize | |
18082 | ||
18083 | Information on this subject is not yet available. | |
18084 | ||
18085 | ||
18086 | @itemize * | |
18087 | ||
18088 | @item | |
18089 | “The result of a complex arithmetic operation or complex | |
18090 | elementary function reference in overflow situations, when the | |
18091 | @code{Machine_Overflows} attribute of the corresponding real type is | |
18092 | @code{False}. See G.2.6(5).” | |
18093 | @end itemize | |
18094 | ||
18095 | IEEE infinite and Nan values are produced as appropriate. | |
18096 | ||
18097 | ||
18098 | @itemize * | |
18099 | ||
18100 | @item | |
18101 | “The accuracy of certain complex arithmetic operations and | |
18102 | certain complex elementary functions for parameters (or components | |
18103 | thereof) beyond the angle threshold. See G.2.6(8).” | |
18104 | @end itemize | |
18105 | ||
18106 | Information on those subjects is not yet available. | |
18107 | ||
18108 | ||
18109 | @itemize * | |
18110 | ||
18111 | @item | |
18112 | “The accuracy requirements for the subprograms Solve, Inverse, | |
18113 | Determinant, Eigenvalues and Eigensystem for type Real_Matrix. | |
18114 | See G.3.1(81).” | |
18115 | @end itemize | |
18116 | ||
18117 | Information on those subjects is not yet available. | |
18118 | ||
18119 | ||
18120 | @itemize * | |
18121 | ||
18122 | @item | |
18123 | “The accuracy requirements for the subprograms Solve, Inverse, | |
18124 | Determinant, Eigenvalues and Eigensystem for type Complex_Matrix. | |
18125 | See G.3.2(149).” | |
18126 | @end itemize | |
18127 | ||
18128 | Information on those subjects is not yet available. | |
18129 | ||
18130 | ||
18131 | @itemize * | |
18132 | ||
18133 | @item | |
18134 | “The consequences of violating No_Hidden_Indirect_Globals. See H.4(23.9).” | |
18135 | @end itemize | |
18136 | ||
18137 | Execution is erroneous in that case. | |
18138 | ||
18139 | @node Intrinsic Subprograms,Representation Clauses and Pragmas,Implementation Defined Characteristics,Top | |
9daee425 | 18140 | @anchor{gnat_rm/intrinsic_subprograms doc}@anchor{269}@anchor{gnat_rm/intrinsic_subprograms id1}@anchor{26a}@anchor{gnat_rm/intrinsic_subprograms intrinsic-subprograms}@anchor{c} |
64d5610f ML |
18141 | @chapter Intrinsic Subprograms |
18142 | ||
18143 | ||
18144 | @geindex Intrinsic Subprograms | |
18145 | ||
18146 | GNAT allows a user application program to write the declaration: | |
18147 | ||
18148 | @example | |
18149 | pragma Import (Intrinsic, name); | |
18150 | @end example | |
18151 | ||
18152 | providing that the name corresponds to one of the implemented intrinsic | |
18153 | subprograms in GNAT, and that the parameter profile of the referenced | |
18154 | subprogram meets the requirements. This chapter describes the set of | |
18155 | implemented intrinsic subprograms, and the requirements on parameter profiles. | |
18156 | Note that no body is supplied; as with other uses of pragma Import, the | |
18157 | body is supplied elsewhere (in this case by the compiler itself). Note | |
18158 | that any use of this feature is potentially non-portable, since the | |
18159 | Ada standard does not require Ada compilers to implement this feature. | |
18160 | ||
18161 | @menu | |
18162 | * Intrinsic Operators:: | |
18163 | * Compilation_ISO_Date:: | |
18164 | * Compilation_Date:: | |
18165 | * Compilation_Time:: | |
18166 | * Enclosing_Entity:: | |
18167 | * Exception_Information:: | |
18168 | * Exception_Message:: | |
18169 | * Exception_Name:: | |
18170 | * File:: | |
18171 | * Line:: | |
18172 | * Shifts and Rotates:: | |
18173 | * Source_Location:: | |
18174 | ||
18175 | @end menu | |
18176 | ||
18177 | @node Intrinsic Operators,Compilation_ISO_Date,,Intrinsic Subprograms | |
9daee425 | 18178 | @anchor{gnat_rm/intrinsic_subprograms id2}@anchor{26b}@anchor{gnat_rm/intrinsic_subprograms intrinsic-operators}@anchor{26c} |
64d5610f ML |
18179 | @section Intrinsic Operators |
18180 | ||
18181 | ||
18182 | @geindex Intrinsic operator | |
18183 | ||
18184 | All the predefined numeric operators in package Standard | |
18185 | in @code{pragma Import (Intrinsic,..)} | |
18186 | declarations. In the binary operator case, the operands must have the same | |
18187 | size. The operand or operands must also be appropriate for | |
18188 | the operator. For example, for addition, the operands must | |
18189 | both be floating-point or both be fixed-point, and the | |
18190 | right operand for @code{"**"} must have a root type of | |
18191 | @code{Standard.Integer'Base}. | |
18192 | You can use an intrinsic operator declaration as in the following example: | |
18193 | ||
18194 | @example | |
18195 | type Int1 is new Integer; | |
18196 | type Int2 is new Integer; | |
18197 | ||
18198 | function "+" (X1 : Int1; X2 : Int2) return Int1; | |
18199 | function "+" (X1 : Int1; X2 : Int2) return Int2; | |
18200 | pragma Import (Intrinsic, "+"); | |
18201 | @end example | |
18202 | ||
18203 | This declaration would permit ‘mixed mode’ arithmetic on items | |
18204 | of the differing types @code{Int1} and @code{Int2}. | |
18205 | It is also possible to specify such operators for private types, if the | |
18206 | full views are appropriate arithmetic types. | |
18207 | ||
18208 | @node Compilation_ISO_Date,Compilation_Date,Intrinsic Operators,Intrinsic Subprograms | |
9daee425 | 18209 | @anchor{gnat_rm/intrinsic_subprograms compilation-iso-date}@anchor{26d}@anchor{gnat_rm/intrinsic_subprograms id3}@anchor{26e} |
64d5610f ML |
18210 | @section Compilation_ISO_Date |
18211 | ||
18212 | ||
18213 | @geindex Compilation_ISO_Date | |
18214 | ||
18215 | This intrinsic subprogram is used in the implementation of the | |
18216 | library package @code{GNAT.Source_Info}. The only useful use of the | |
18217 | intrinsic import in this case is the one in this unit, so an | |
18218 | application program should simply call the function | |
18219 | @code{GNAT.Source_Info.Compilation_ISO_Date} to obtain the date of | |
18220 | the current compilation (in local time format YYYY-MM-DD). | |
18221 | ||
18222 | @node Compilation_Date,Compilation_Time,Compilation_ISO_Date,Intrinsic Subprograms | |
9daee425 | 18223 | @anchor{gnat_rm/intrinsic_subprograms compilation-date}@anchor{26f}@anchor{gnat_rm/intrinsic_subprograms id4}@anchor{270} |
64d5610f ML |
18224 | @section Compilation_Date |
18225 | ||
18226 | ||
18227 | @geindex Compilation_Date | |
18228 | ||
18229 | Same as Compilation_ISO_Date, except the string is in the form | |
18230 | MMM DD YYYY. | |
18231 | ||
18232 | @node Compilation_Time,Enclosing_Entity,Compilation_Date,Intrinsic Subprograms | |
9daee425 | 18233 | @anchor{gnat_rm/intrinsic_subprograms compilation-time}@anchor{271}@anchor{gnat_rm/intrinsic_subprograms id5}@anchor{272} |
64d5610f ML |
18234 | @section Compilation_Time |
18235 | ||
18236 | ||
18237 | @geindex Compilation_Time | |
18238 | ||
18239 | This intrinsic subprogram is used in the implementation of the | |
18240 | library package @code{GNAT.Source_Info}. The only useful use of the | |
18241 | intrinsic import in this case is the one in this unit, so an | |
18242 | application program should simply call the function | |
18243 | @code{GNAT.Source_Info.Compilation_Time} to obtain the time of | |
18244 | the current compilation (in local time format HH:MM:SS). | |
18245 | ||
18246 | @node Enclosing_Entity,Exception_Information,Compilation_Time,Intrinsic Subprograms | |
9daee425 | 18247 | @anchor{gnat_rm/intrinsic_subprograms enclosing-entity}@anchor{273}@anchor{gnat_rm/intrinsic_subprograms id6}@anchor{274} |
64d5610f ML |
18248 | @section Enclosing_Entity |
18249 | ||
18250 | ||
18251 | @geindex Enclosing_Entity | |
18252 | ||
18253 | This intrinsic subprogram is used in the implementation of the | |
18254 | library package @code{GNAT.Source_Info}. The only useful use of the | |
18255 | intrinsic import in this case is the one in this unit, so an | |
18256 | application program should simply call the function | |
18257 | @code{GNAT.Source_Info.Enclosing_Entity} to obtain the name of | |
18258 | the current subprogram, package, task, entry, or protected subprogram. | |
18259 | ||
18260 | @node Exception_Information,Exception_Message,Enclosing_Entity,Intrinsic Subprograms | |
9daee425 | 18261 | @anchor{gnat_rm/intrinsic_subprograms exception-information}@anchor{275}@anchor{gnat_rm/intrinsic_subprograms id7}@anchor{276} |
64d5610f ML |
18262 | @section Exception_Information |
18263 | ||
18264 | ||
18265 | @geindex Exception_Information' | |
18266 | ||
18267 | This intrinsic subprogram is used in the implementation of the | |
18268 | library package @code{GNAT.Current_Exception}. The only useful | |
18269 | use of the intrinsic import in this case is the one in this unit, | |
18270 | so an application program should simply call the function | |
18271 | @code{GNAT.Current_Exception.Exception_Information} to obtain | |
18272 | the exception information associated with the current exception. | |
18273 | ||
18274 | @node Exception_Message,Exception_Name,Exception_Information,Intrinsic Subprograms | |
9daee425 | 18275 | @anchor{gnat_rm/intrinsic_subprograms exception-message}@anchor{277}@anchor{gnat_rm/intrinsic_subprograms id8}@anchor{278} |
64d5610f ML |
18276 | @section Exception_Message |
18277 | ||
18278 | ||
18279 | @geindex Exception_Message | |
18280 | ||
18281 | This intrinsic subprogram is used in the implementation of the | |
18282 | library package @code{GNAT.Current_Exception}. The only useful | |
18283 | use of the intrinsic import in this case is the one in this unit, | |
18284 | so an application program should simply call the function | |
18285 | @code{GNAT.Current_Exception.Exception_Message} to obtain | |
18286 | the message associated with the current exception. | |
18287 | ||
18288 | @node Exception_Name,File,Exception_Message,Intrinsic Subprograms | |
9daee425 | 18289 | @anchor{gnat_rm/intrinsic_subprograms exception-name}@anchor{279}@anchor{gnat_rm/intrinsic_subprograms id9}@anchor{27a} |
64d5610f ML |
18290 | @section Exception_Name |
18291 | ||
18292 | ||
18293 | @geindex Exception_Name | |
18294 | ||
18295 | This intrinsic subprogram is used in the implementation of the | |
18296 | library package @code{GNAT.Current_Exception}. The only useful | |
18297 | use of the intrinsic import in this case is the one in this unit, | |
18298 | so an application program should simply call the function | |
18299 | @code{GNAT.Current_Exception.Exception_Name} to obtain | |
18300 | the name of the current exception. | |
18301 | ||
18302 | @node File,Line,Exception_Name,Intrinsic Subprograms | |
9daee425 | 18303 | @anchor{gnat_rm/intrinsic_subprograms file}@anchor{27b}@anchor{gnat_rm/intrinsic_subprograms id10}@anchor{27c} |
64d5610f ML |
18304 | @section File |
18305 | ||
18306 | ||
18307 | @geindex File | |
18308 | ||
18309 | This intrinsic subprogram is used in the implementation of the | |
18310 | library package @code{GNAT.Source_Info}. The only useful use of the | |
18311 | intrinsic import in this case is the one in this unit, so an | |
18312 | application program should simply call the function | |
18313 | @code{GNAT.Source_Info.File} to obtain the name of the current | |
18314 | file. | |
18315 | ||
18316 | @node Line,Shifts and Rotates,File,Intrinsic Subprograms | |
9daee425 | 18317 | @anchor{gnat_rm/intrinsic_subprograms id11}@anchor{27d}@anchor{gnat_rm/intrinsic_subprograms line}@anchor{27e} |
64d5610f ML |
18318 | @section Line |
18319 | ||
18320 | ||
18321 | @geindex Line | |
18322 | ||
18323 | This intrinsic subprogram is used in the implementation of the | |
18324 | library package @code{GNAT.Source_Info}. The only useful use of the | |
18325 | intrinsic import in this case is the one in this unit, so an | |
18326 | application program should simply call the function | |
18327 | @code{GNAT.Source_Info.Line} to obtain the number of the current | |
18328 | source line. | |
18329 | ||
18330 | @node Shifts and Rotates,Source_Location,Line,Intrinsic Subprograms | |
9daee425 | 18331 | @anchor{gnat_rm/intrinsic_subprograms id12}@anchor{27f}@anchor{gnat_rm/intrinsic_subprograms shifts-and-rotates}@anchor{280} |
64d5610f ML |
18332 | @section Shifts and Rotates |
18333 | ||
18334 | ||
18335 | @geindex Shift_Left | |
18336 | ||
18337 | @geindex Shift_Right | |
18338 | ||
18339 | @geindex Shift_Right_Arithmetic | |
18340 | ||
18341 | @geindex Rotate_Left | |
18342 | ||
18343 | @geindex Rotate_Right | |
18344 | ||
18345 | In standard Ada, the shift and rotate functions are available only | |
18346 | for the predefined modular types in package @code{Interfaces}. However, in | |
18347 | GNAT it is possible to define these functions for any integer | |
18348 | type (signed or modular), as in this example: | |
18349 | ||
18350 | @example | |
18351 | function Shift_Left | |
18352 | (Value : T; | |
18353 | Amount : Natural) return T | |
18354 | with Import, Convention => Intrinsic; | |
18355 | @end example | |
18356 | ||
18357 | The function name must be one of | |
18358 | Shift_Left, Shift_Right, Shift_Right_Arithmetic, Rotate_Left, or | |
18359 | Rotate_Right. T must be an integer type. T’Size must be | |
18360 | 8, 16, 32 or 64 bits; if T is modular, the modulus | |
18361 | must be 2**8, 2**16, 2**32 or 2**64. | |
18362 | The result type must be the same as the type of @code{Value}. | |
18363 | The shift amount must be Natural. | |
18364 | The formal parameter names can be anything. | |
18365 | ||
18366 | A more convenient way of providing these shift operators is to use the | |
18367 | Provide_Shift_Operators pragma, which provides the function declarations and | |
18368 | corresponding pragma Import’s for all five shift functions. For signed types | |
18369 | the semantics of these operators is to interpret the bitwise result of the | |
18370 | corresponding operator for modular type. In particular, shifting a negative | |
18371 | number may change its sign bit to positive. | |
18372 | ||
18373 | @node Source_Location,,Shifts and Rotates,Intrinsic Subprograms | |
9daee425 | 18374 | @anchor{gnat_rm/intrinsic_subprograms id13}@anchor{281}@anchor{gnat_rm/intrinsic_subprograms source-location}@anchor{282} |
64d5610f ML |
18375 | @section Source_Location |
18376 | ||
18377 | ||
18378 | @geindex Source_Location | |
18379 | ||
18380 | This intrinsic subprogram is used in the implementation of the | |
18381 | library routine @code{GNAT.Source_Info}. The only useful use of the | |
18382 | intrinsic import in this case is the one in this unit, so an | |
18383 | application program should simply call the function | |
18384 | @code{GNAT.Source_Info.Source_Location} to obtain the current | |
18385 | source file location. | |
18386 | ||
18387 | @node Representation Clauses and Pragmas,Standard Library Routines,Intrinsic Subprograms,Top | |
9daee425 | 18388 | @anchor{gnat_rm/representation_clauses_and_pragmas doc}@anchor{283}@anchor{gnat_rm/representation_clauses_and_pragmas id1}@anchor{284}@anchor{gnat_rm/representation_clauses_and_pragmas representation-clauses-and-pragmas}@anchor{d} |
64d5610f ML |
18389 | @chapter Representation Clauses and Pragmas |
18390 | ||
18391 | ||
18392 | @geindex Representation Clauses | |
18393 | ||
18394 | @geindex Representation Clause | |
18395 | ||
18396 | @geindex Representation Pragma | |
18397 | ||
18398 | @geindex Pragma | |
18399 | @geindex representation | |
18400 | ||
18401 | This section describes the representation clauses accepted by GNAT, and | |
18402 | their effect on the representation of corresponding data objects. | |
18403 | ||
18404 | GNAT fully implements Annex C (Systems Programming). This means that all | |
18405 | the implementation advice sections in chapter 13 are fully implemented. | |
18406 | However, these sections only require a minimal level of support for | |
18407 | representation clauses. GNAT provides much more extensive capabilities, | |
18408 | and this section describes the additional capabilities provided. | |
18409 | ||
18410 | @menu | |
18411 | * Alignment Clauses:: | |
18412 | * Size Clauses:: | |
18413 | * Storage_Size Clauses:: | |
18414 | * Size of Variant Record Objects:: | |
18415 | * Biased Representation:: | |
18416 | * Value_Size and Object_Size Clauses:: | |
18417 | * Component_Size Clauses:: | |
18418 | * Bit_Order Clauses:: | |
18419 | * Effect of Bit_Order on Byte Ordering:: | |
18420 | * Pragma Pack for Arrays:: | |
18421 | * Pragma Pack for Records:: | |
18422 | * Record Representation Clauses:: | |
18423 | * Handling of Records with Holes:: | |
18424 | * Enumeration Clauses:: | |
18425 | * Address Clauses:: | |
18426 | * Use of Address Clauses for Memory-Mapped I/O:: | |
18427 | * Effect of Convention on Representation:: | |
18428 | * Conventions and Anonymous Access Types:: | |
18429 | * Determining the Representations chosen by GNAT:: | |
18430 | ||
18431 | @end menu | |
18432 | ||
18433 | @node Alignment Clauses,Size Clauses,,Representation Clauses and Pragmas | |
9daee425 | 18434 | @anchor{gnat_rm/representation_clauses_and_pragmas alignment-clauses}@anchor{285}@anchor{gnat_rm/representation_clauses_and_pragmas id2}@anchor{286} |
64d5610f ML |
18435 | @section Alignment Clauses |
18436 | ||
18437 | ||
18438 | @geindex Alignment Clause | |
18439 | ||
18440 | GNAT requires that all alignment clauses specify 0 or a power of 2, and | |
18441 | all default alignments are always a power of 2. Specifying 0 is the | |
18442 | same as specifying 1. | |
18443 | ||
18444 | The default alignment values are as follows: | |
18445 | ||
18446 | ||
18447 | @itemize * | |
18448 | ||
18449 | @item | |
1acce141 | 18450 | @emph{Elementary Types}. |
64d5610f ML |
18451 | |
18452 | For elementary types, the alignment is the minimum of the actual size of | |
18453 | objects of the type divided by @code{Storage_Unit}, | |
18454 | and the maximum alignment supported by the target. | |
18455 | (This maximum alignment is given by the GNAT-specific attribute | |
9daee425 | 18456 | @code{Standard'Maximum_Alignment}; see @ref{196,,Attribute Maximum_Alignment}.) |
64d5610f ML |
18457 | |
18458 | @geindex Maximum_Alignment attribute | |
18459 | ||
18460 | For example, for type @code{Long_Float}, the object size is 8 bytes, and the | |
18461 | default alignment will be 8 on any target that supports alignments | |
18462 | this large, but on some targets, the maximum alignment may be smaller | |
18463 | than 8, in which case objects of type @code{Long_Float} will be maximally | |
18464 | aligned. | |
18465 | ||
18466 | @item | |
1acce141 | 18467 | @emph{Arrays}. |
64d5610f ML |
18468 | |
18469 | For arrays, the alignment is equal to the alignment of the component type | |
18470 | for the normal case where no packing or component size is given. If the | |
18471 | array is packed, and the packing is effective (see separate section on | |
18472 | packed arrays), then the alignment will be either 4, 2, or 1 for long packed | |
18473 | arrays or arrays whose length is not known at compile time, depending on | |
18474 | whether the component size is divisible by 4, 2, or is odd. For short packed | |
18475 | arrays, which are handled internally as modular types, the alignment | |
18476 | will be as described for elementary types, e.g. a packed array of length | |
18477 | 31 bits will have an object size of four bytes, and an alignment of 4. | |
18478 | ||
18479 | @item | |
1acce141 | 18480 | @emph{Records}. |
64d5610f ML |
18481 | |
18482 | For the normal unpacked case, the alignment of a record is equal to | |
18483 | the maximum alignment of any of its components. For tagged records, this | |
18484 | includes the implicit access type used for the tag. If a pragma @code{Pack} | |
18485 | is used and all components are packable (see separate section on pragma | |
18486 | @code{Pack}), then the resulting alignment is 1, unless the layout of the | |
18487 | record makes it profitable to increase it. | |
18488 | ||
18489 | A special case is when: | |
18490 | ||
18491 | ||
18492 | @itemize * | |
18493 | ||
18494 | @item | |
18495 | the size of the record is given explicitly, or a | |
18496 | full record representation clause is given, and | |
18497 | ||
18498 | @item | |
18499 | the size of the record is 2, 4, or 8 bytes. | |
18500 | @end itemize | |
18501 | ||
18502 | In this case, an alignment is chosen to match the | |
18503 | size of the record. For example, if we have: | |
18504 | ||
18505 | @example | |
18506 | type Small is record | |
18507 | A, B : Character; | |
18508 | end record; | |
18509 | for Small'Size use 16; | |
18510 | @end example | |
18511 | ||
18512 | then the default alignment of the record type @code{Small} is 2, not 1. This | |
18513 | leads to more efficient code when the record is treated as a unit, and also | |
18514 | allows the type to specified as @code{Atomic} on architectures requiring | |
18515 | strict alignment. | |
18516 | @end itemize | |
18517 | ||
18518 | An alignment clause may specify a larger alignment than the default value | |
18519 | up to some maximum value dependent on the target (obtainable by using the | |
18520 | attribute reference @code{Standard'Maximum_Alignment}). It may also specify | |
18521 | a smaller alignment than the default value for enumeration, integer and | |
18522 | fixed point types, as well as for record types, for example | |
18523 | ||
18524 | @example | |
18525 | type V is record | |
18526 | A : Integer; | |
18527 | end record; | |
18528 | ||
18529 | for V'alignment use 1; | |
18530 | @end example | |
18531 | ||
18532 | @geindex Alignment | |
18533 | @geindex default | |
18534 | ||
18535 | The default alignment for the type @code{V} is 4, as a result of the | |
18536 | Integer field in the record, but it is permissible, as shown, to | |
18537 | override the default alignment of the record with a smaller value. | |
18538 | ||
18539 | @geindex Alignment | |
18540 | @geindex subtypes | |
18541 | ||
18542 | Note that according to the Ada standard, an alignment clause applies only | |
18543 | to the first named subtype. If additional subtypes are declared, then the | |
18544 | compiler is allowed to choose any alignment it likes, and there is no way | |
18545 | to control this choice. Consider: | |
18546 | ||
18547 | @example | |
18548 | type R is range 1 .. 10_000; | |
18549 | for R'Alignment use 1; | |
18550 | subtype RS is R range 1 .. 1000; | |
18551 | @end example | |
18552 | ||
18553 | The alignment clause specifies an alignment of 1 for the first named subtype | |
18554 | @code{R} but this does not necessarily apply to @code{RS}. When writing | |
18555 | portable Ada code, you should avoid writing code that explicitly or | |
18556 | implicitly relies on the alignment of such subtypes. | |
18557 | ||
18558 | For the GNAT compiler, if an explicit alignment clause is given, this | |
18559 | value is also used for any subsequent subtypes. So for GNAT, in the | |
18560 | above example, you can count on the alignment of @code{RS} being 1. But this | |
18561 | assumption is non-portable, and other compilers may choose different | |
18562 | alignments for the subtype @code{RS}. | |
18563 | ||
18564 | @node Size Clauses,Storage_Size Clauses,Alignment Clauses,Representation Clauses and Pragmas | |
9daee425 | 18565 | @anchor{gnat_rm/representation_clauses_and_pragmas id3}@anchor{287}@anchor{gnat_rm/representation_clauses_and_pragmas size-clauses}@anchor{288} |
64d5610f ML |
18566 | @section Size Clauses |
18567 | ||
18568 | ||
18569 | @geindex Size Clause | |
18570 | ||
18571 | The default size for a type @code{T} is obtainable through the | |
18572 | language-defined attribute @code{T'Size} and also through the | |
18573 | equivalent GNAT-defined attribute @code{T'Value_Size}. | |
18574 | For objects of type @code{T}, GNAT will generally increase the type size | |
18575 | so that the object size (obtainable through the GNAT-defined attribute | |
18576 | @code{T'Object_Size}) | |
18577 | is a multiple of @code{T'Alignment * Storage_Unit}. | |
18578 | ||
18579 | For example: | |
18580 | ||
18581 | @example | |
18582 | type Smallint is range 1 .. 6; | |
18583 | ||
18584 | type Rec is record | |
18585 | Y1 : integer; | |
18586 | Y2 : boolean; | |
18587 | end record; | |
18588 | @end example | |
18589 | ||
18590 | In this example, @code{Smallint'Size} = @code{Smallint'Value_Size} = 3, | |
18591 | as specified by the RM rules, | |
18592 | but objects of this type will have a size of 8 | |
18593 | (@code{Smallint'Object_Size} = 8), | |
18594 | since objects by default occupy an integral number | |
18595 | of storage units. On some targets, notably older | |
18596 | versions of the Digital Alpha, the size of stand | |
18597 | alone objects of this type may be 32, reflecting | |
18598 | the inability of the hardware to do byte load/stores. | |
18599 | ||
18600 | Similarly, the size of type @code{Rec} is 40 bits | |
18601 | (@code{Rec'Size} = @code{Rec'Value_Size} = 40), but | |
18602 | the alignment is 4, so objects of this type will have | |
18603 | their size increased to 64 bits so that it is a multiple | |
18604 | of the alignment (in bits). This decision is | |
18605 | in accordance with the specific Implementation Advice in RM 13.3(43): | |
18606 | ||
18607 | @quotation | |
18608 | ||
18609 | “A @code{Size} clause should be supported for an object if the specified | |
18610 | @code{Size} is at least as large as its subtype’s @code{Size}, and corresponds | |
18611 | to a size in storage elements that is a multiple of the object’s | |
18612 | @code{Alignment} (if the @code{Alignment} is nonzero).” | |
18613 | @end quotation | |
18614 | ||
18615 | An explicit size clause may be used to override the default size by | |
18616 | increasing it. For example, if we have: | |
18617 | ||
18618 | @example | |
18619 | type My_Boolean is new Boolean; | |
18620 | for My_Boolean'Size use 32; | |
18621 | @end example | |
18622 | ||
18623 | then values of this type will always be 32-bit long. In the case of discrete | |
18624 | types, the size can be increased up to 64 bits on 32-bit targets and 128 bits | |
18625 | on 64-bit targets, with the effect that the entire specified field is used to | |
18626 | hold the value, sign- or zero-extended as appropriate. If more than 64 bits | |
18627 | or 128 bits resp. is specified, then padding space is allocated after the | |
18628 | value, and a warning is issued that there are unused bits. | |
18629 | ||
18630 | Similarly the size of records and arrays may be increased, and the effect | |
18631 | is to add padding bits after the value. This also causes a warning message | |
18632 | to be generated. | |
18633 | ||
18634 | The largest Size value permitted in GNAT is 2**31-1. Since this is a | |
18635 | Size in bits, this corresponds to an object of size 256 megabytes (minus | |
18636 | one). This limitation is true on all targets. The reason for this | |
18637 | limitation is that it improves the quality of the code in many cases | |
18638 | if it is known that a Size value can be accommodated in an object of | |
18639 | type Integer. | |
18640 | ||
18641 | @node Storage_Size Clauses,Size of Variant Record Objects,Size Clauses,Representation Clauses and Pragmas | |
9daee425 | 18642 | @anchor{gnat_rm/representation_clauses_and_pragmas id4}@anchor{289}@anchor{gnat_rm/representation_clauses_and_pragmas storage-size-clauses}@anchor{28a} |
64d5610f ML |
18643 | @section Storage_Size Clauses |
18644 | ||
18645 | ||
18646 | @geindex Storage_Size Clause | |
18647 | ||
18648 | For tasks, the @code{Storage_Size} clause specifies the amount of space | |
18649 | to be allocated for the task stack. This cannot be extended, and if the | |
18650 | stack is exhausted, then @code{Storage_Error} will be raised (if stack | |
18651 | checking is enabled). Use a @code{Storage_Size} attribute definition clause, | |
18652 | or a @code{Storage_Size} pragma in the task definition to set the | |
18653 | appropriate required size. A useful technique is to include in every | |
18654 | task definition a pragma of the form: | |
18655 | ||
18656 | @example | |
18657 | pragma Storage_Size (Default_Stack_Size); | |
18658 | @end example | |
18659 | ||
18660 | Then @code{Default_Stack_Size} can be defined in a global package, and | |
18661 | modified as required. Any tasks requiring stack sizes different from the | |
18662 | default can have an appropriate alternative reference in the pragma. | |
18663 | ||
1acce141 | 18664 | You can also use the @emph{-d} binder switch to modify the default stack |
64d5610f ML |
18665 | size. |
18666 | ||
18667 | For access types, the @code{Storage_Size} clause specifies the maximum | |
18668 | space available for allocation of objects of the type. If this space is | |
18669 | exceeded then @code{Storage_Error} will be raised by an allocation attempt. | |
18670 | In the case where the access type is declared local to a subprogram, the | |
18671 | use of a @code{Storage_Size} clause triggers automatic use of a special | |
18672 | predefined storage pool (@code{System.Pool_Size}) that ensures that all | |
18673 | space for the pool is automatically reclaimed on exit from the scope in | |
18674 | which the type is declared. | |
18675 | ||
18676 | A special case recognized by the compiler is the specification of a | |
18677 | @code{Storage_Size} of zero for an access type. This means that no | |
18678 | items can be allocated from the pool, and this is recognized at compile | |
18679 | time, and all the overhead normally associated with maintaining a fixed | |
18680 | size storage pool is eliminated. Consider the following example: | |
18681 | ||
18682 | @example | |
18683 | procedure p is | |
18684 | type R is array (Natural) of Character; | |
18685 | type P is access all R; | |
18686 | for P'Storage_Size use 0; | |
18687 | -- Above access type intended only for interfacing purposes | |
18688 | ||
18689 | y : P; | |
18690 | ||
18691 | procedure g (m : P); | |
18692 | pragma Import (C, g); | |
18693 | ||
18694 | -- ... | |
18695 | ||
18696 | begin | |
18697 | -- ... | |
18698 | y := new R; | |
18699 | end; | |
18700 | @end example | |
18701 | ||
18702 | As indicated in this example, these dummy storage pools are often useful in | |
18703 | connection with interfacing where no object will ever be allocated. If you | |
18704 | compile the above example, you get the warning: | |
18705 | ||
18706 | @example | |
18707 | p.adb:16:09: warning: allocation from empty storage pool | |
18708 | p.adb:16:09: warning: Storage_Error will be raised at run time | |
18709 | @end example | |
18710 | ||
18711 | Of course in practice, there will not be any explicit allocators in the | |
18712 | case of such an access declaration. | |
18713 | ||
18714 | @node Size of Variant Record Objects,Biased Representation,Storage_Size Clauses,Representation Clauses and Pragmas | |
9daee425 | 18715 | @anchor{gnat_rm/representation_clauses_and_pragmas id5}@anchor{28b}@anchor{gnat_rm/representation_clauses_and_pragmas size-of-variant-record-objects}@anchor{28c} |
64d5610f ML |
18716 | @section Size of Variant Record Objects |
18717 | ||
18718 | ||
18719 | @geindex Size | |
18720 | @geindex variant record objects | |
18721 | ||
18722 | @geindex Variant record objects | |
18723 | @geindex size | |
18724 | ||
18725 | In the case of variant record objects, there is a question whether Size gives | |
18726 | information about a particular variant, or the maximum size required | |
18727 | for any variant. Consider the following program | |
18728 | ||
18729 | @example | |
18730 | with Text_IO; use Text_IO; | |
18731 | procedure q is | |
18732 | type R1 (A : Boolean := False) is record | |
18733 | case A is | |
18734 | when True => X : Character; | |
18735 | when False => null; | |
18736 | end case; | |
18737 | end record; | |
18738 | ||
18739 | V1 : R1 (False); | |
18740 | V2 : R1; | |
18741 | ||
18742 | begin | |
18743 | Put_Line (Integer'Image (V1'Size)); | |
18744 | Put_Line (Integer'Image (V2'Size)); | |
18745 | end q; | |
18746 | @end example | |
18747 | ||
18748 | Here we are dealing with a variant record, where the True variant | |
18749 | requires 16 bits, and the False variant requires 8 bits. | |
18750 | In the above example, both V1 and V2 contain the False variant, | |
18751 | which is only 8 bits long. However, the result of running the | |
18752 | program is: | |
18753 | ||
18754 | @example | |
18755 | 8 | |
18756 | 16 | |
18757 | @end example | |
18758 | ||
18759 | The reason for the difference here is that the discriminant value of | |
18760 | V1 is fixed, and will always be False. It is not possible to assign | |
18761 | a True variant value to V1, therefore 8 bits is sufficient. On the | |
18762 | other hand, in the case of V2, the initial discriminant value is | |
18763 | False (from the default), but it is possible to assign a True | |
18764 | variant value to V2, therefore 16 bits must be allocated for V2 | |
18765 | in the general case, even fewer bits may be needed at any particular | |
18766 | point during the program execution. | |
18767 | ||
18768 | As can be seen from the output of this program, the @code{'Size} | |
18769 | attribute applied to such an object in GNAT gives the actual allocated | |
18770 | size of the variable, which is the largest size of any of the variants. | |
18771 | The Ada Reference Manual is not completely clear on what choice should | |
18772 | be made here, but the GNAT behavior seems most consistent with the | |
18773 | language in the RM. | |
18774 | ||
18775 | In some cases, it may be desirable to obtain the size of the current | |
18776 | variant, rather than the size of the largest variant. This can be | |
18777 | achieved in GNAT by making use of the fact that in the case of a | |
18778 | subprogram parameter, GNAT does indeed return the size of the current | |
18779 | variant (because a subprogram has no way of knowing how much space | |
18780 | is actually allocated for the actual). | |
18781 | ||
18782 | Consider the following modified version of the above program: | |
18783 | ||
18784 | @example | |
18785 | with Text_IO; use Text_IO; | |
18786 | procedure q is | |
18787 | type R1 (A : Boolean := False) is record | |
18788 | case A is | |
18789 | when True => X : Character; | |
18790 | when False => null; | |
18791 | end case; | |
18792 | end record; | |
18793 | ||
18794 | V2 : R1; | |
18795 | ||
18796 | function Size (V : R1) return Integer is | |
18797 | begin | |
18798 | return V'Size; | |
18799 | end Size; | |
18800 | ||
18801 | begin | |
18802 | Put_Line (Integer'Image (V2'Size)); | |
18803 | Put_Line (Integer'Image (Size (V2))); | |
18804 | V2 := (True, 'x'); | |
18805 | Put_Line (Integer'Image (V2'Size)); | |
18806 | Put_Line (Integer'Image (Size (V2))); | |
18807 | end q; | |
18808 | @end example | |
18809 | ||
18810 | The output from this program is | |
18811 | ||
18812 | @example | |
18813 | 16 | |
18814 | 8 | |
18815 | 16 | |
18816 | 16 | |
18817 | @end example | |
18818 | ||
18819 | Here we see that while the @code{'Size} attribute always returns | |
18820 | the maximum size, regardless of the current variant value, the | |
18821 | @code{Size} function does indeed return the size of the current | |
18822 | variant value. | |
18823 | ||
18824 | @node Biased Representation,Value_Size and Object_Size Clauses,Size of Variant Record Objects,Representation Clauses and Pragmas | |
9daee425 | 18825 | @anchor{gnat_rm/representation_clauses_and_pragmas biased-representation}@anchor{28d}@anchor{gnat_rm/representation_clauses_and_pragmas id6}@anchor{28e} |
64d5610f ML |
18826 | @section Biased Representation |
18827 | ||
18828 | ||
18829 | @geindex Size for biased representation | |
18830 | ||
18831 | @geindex Biased representation | |
18832 | ||
18833 | In the case of scalars with a range starting at other than zero, it is | |
18834 | possible in some cases to specify a size smaller than the default minimum | |
18835 | value, and in such cases, GNAT uses an unsigned biased representation, | |
18836 | in which zero is used to represent the lower bound, and successive values | |
18837 | represent successive values of the type. | |
18838 | ||
18839 | For example, suppose we have the declaration: | |
18840 | ||
18841 | @example | |
18842 | type Small is range -7 .. -4; | |
18843 | for Small'Size use 2; | |
18844 | @end example | |
18845 | ||
18846 | Although the default size of type @code{Small} is 4, the @code{Size} | |
18847 | clause is accepted by GNAT and results in the following representation | |
18848 | scheme: | |
18849 | ||
18850 | @example | |
18851 | -7 is represented as 2#00# | |
18852 | -6 is represented as 2#01# | |
18853 | -5 is represented as 2#10# | |
18854 | -4 is represented as 2#11# | |
18855 | @end example | |
18856 | ||
18857 | Biased representation is only used if the specified @code{Size} clause | |
18858 | cannot be accepted in any other manner. These reduced sizes that force | |
18859 | biased representation can be used for all discrete types except for | |
18860 | enumeration types for which a representation clause is given. | |
18861 | ||
18862 | @node Value_Size and Object_Size Clauses,Component_Size Clauses,Biased Representation,Representation Clauses and Pragmas | |
9daee425 | 18863 | @anchor{gnat_rm/representation_clauses_and_pragmas id7}@anchor{28f}@anchor{gnat_rm/representation_clauses_and_pragmas value-size-and-object-size-clauses}@anchor{290} |
64d5610f ML |
18864 | @section Value_Size and Object_Size Clauses |
18865 | ||
18866 | ||
18867 | @geindex Value_Size | |
18868 | ||
18869 | @geindex Object_Size | |
18870 | ||
18871 | @geindex Size | |
18872 | @geindex of objects | |
18873 | ||
18874 | In Ada 95 and Ada 2005, @code{T'Size} for a type @code{T} is the minimum | |
18875 | number of bits required to hold values of type @code{T}. | |
18876 | Although this interpretation was allowed in Ada 83, it was not required, | |
18877 | and this requirement in practice can cause some significant difficulties. | |
18878 | For example, in most Ada 83 compilers, @code{Natural'Size} was 32. | |
18879 | However, in Ada 95 and Ada 2005, | |
18880 | @code{Natural'Size} is | |
18881 | typically 31. This means that code may change in behavior when moving | |
18882 | from Ada 83 to Ada 95 or Ada 2005. For example, consider: | |
18883 | ||
18884 | @example | |
18885 | type Rec is record | |
18886 | A : Natural; | |
18887 | B : Natural; | |
18888 | end record; | |
18889 | ||
18890 | for Rec use record | |
18891 | A at 0 range 0 .. Natural'Size - 1; | |
18892 | B at 0 range Natural'Size .. 2 * Natural'Size - 1; | |
18893 | end record; | |
18894 | @end example | |
18895 | ||
18896 | In the above code, since the typical size of @code{Natural} objects | |
18897 | is 32 bits and @code{Natural'Size} is 31, the above code can cause | |
18898 | unexpected inefficient packing in Ada 95 and Ada 2005, and in general | |
18899 | there are cases where the fact that the object size can exceed the | |
18900 | size of the type causes surprises. | |
18901 | ||
18902 | To help get around this problem GNAT provides two implementation | |
18903 | defined attributes, @code{Value_Size} and @code{Object_Size}. When | |
18904 | applied to a type, these attributes yield the size of the type | |
18905 | (corresponding to the RM defined size attribute), and the size of | |
18906 | objects of the type respectively. | |
18907 | ||
18908 | The @code{Object_Size} is used for determining the default size of | |
18909 | objects and components. This size value can be referred to using the | |
18910 | @code{Object_Size} attribute. The phrase ‘is used’ here means that it is | |
18911 | the basis of the determination of the size. The backend is free to | |
18912 | pad this up if necessary for efficiency, e.g., an 8-bit stand-alone | |
18913 | character might be stored in 32 bits on a machine with no efficient | |
18914 | byte access instructions such as the Alpha. | |
18915 | ||
18916 | The default rules for the value of @code{Object_Size} for | |
18917 | discrete types are as follows: | |
18918 | ||
18919 | ||
18920 | @itemize * | |
18921 | ||
18922 | @item | |
18923 | The @code{Object_Size} for base subtypes reflect the natural hardware | |
1acce141 | 18924 | size in bits (run the compiler with @emph{-gnatS} to find those values |
64d5610f ML |
18925 | for numeric types). Enumeration types and fixed-point base subtypes have |
18926 | 8, 16, 32, or 64 bits for this size, depending on the range of values | |
18927 | to be stored. | |
18928 | ||
18929 | @item | |
18930 | The @code{Object_Size} of a subtype is the same as the | |
18931 | @code{Object_Size} of | |
18932 | the type from which it is obtained. | |
18933 | ||
18934 | @item | |
18935 | The @code{Object_Size} of a derived base type is copied from the parent | |
18936 | base type, and the @code{Object_Size} of a derived first subtype is copied | |
18937 | from the parent first subtype. | |
18938 | @end itemize | |
18939 | ||
18940 | The @code{Value_Size} attribute | |
18941 | is the (minimum) number of bits required to store a value | |
18942 | of the type. | |
18943 | This value is used to determine how tightly to pack | |
18944 | records or arrays with components of this type, and also affects | |
18945 | the semantics of unchecked conversion (unchecked conversions where | |
18946 | the @code{Value_Size} values differ generate a warning, and are potentially | |
18947 | target dependent). | |
18948 | ||
18949 | The default rules for the value of @code{Value_Size} are as follows: | |
18950 | ||
18951 | ||
18952 | @itemize * | |
18953 | ||
18954 | @item | |
18955 | The @code{Value_Size} for a base subtype is the minimum number of bits | |
18956 | required to store all values of the type (including the sign bit | |
18957 | only if negative values are possible). | |
18958 | ||
18959 | @item | |
18960 | If a subtype statically matches the first subtype of a given type, then it has | |
18961 | by default the same @code{Value_Size} as the first subtype. (This is a | |
18962 | consequence of RM 13.1(14): “if two subtypes statically match, | |
18963 | then their subtype-specific aspects are the same”.) | |
18964 | ||
18965 | @item | |
18966 | All other subtypes have a @code{Value_Size} corresponding to the minimum | |
18967 | number of bits required to store all values of the subtype. For | |
18968 | dynamic bounds, it is assumed that the value can range down or up | |
18969 | to the corresponding bound of the ancestor | |
18970 | @end itemize | |
18971 | ||
18972 | The RM defined attribute @code{Size} corresponds to the | |
18973 | @code{Value_Size} attribute. | |
18974 | ||
18975 | The @code{Size} attribute may be defined for a first-named subtype. This sets | |
18976 | the @code{Value_Size} of | |
18977 | the first-named subtype to the given value, and the | |
18978 | @code{Object_Size} of this first-named subtype to the given value padded up | |
18979 | to an appropriate boundary. It is a consequence of the default rules | |
18980 | above that this @code{Object_Size} will apply to all further subtypes. On the | |
18981 | other hand, @code{Value_Size} is affected only for the first subtype, any | |
18982 | dynamic subtypes obtained from it directly, and any statically matching | |
18983 | subtypes. The @code{Value_Size} of any other static subtypes is not affected. | |
18984 | ||
18985 | @code{Value_Size} and | |
18986 | @code{Object_Size} may be explicitly set for any subtype using | |
18987 | an attribute definition clause. Note that the use of these attributes | |
18988 | can cause the RM 13.1(14) rule to be violated. If two access types | |
18989 | reference aliased objects whose subtypes have differing @code{Object_Size} | |
18990 | values as a result of explicit attribute definition clauses, then it | |
18991 | is illegal to convert from one access subtype to the other. For a more | |
18992 | complete description of this additional legality rule, see the | |
18993 | description of the @code{Object_Size} attribute. | |
18994 | ||
18995 | To get a feel for the difference, consider the following examples (note | |
18996 | that in each case the base is @code{Short_Short_Integer} with a size of 8): | |
18997 | ||
18998 | ||
18999 | @multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxx} | |
19000 | @headitem | |
19001 | ||
19002 | Type or subtype declaration | |
19003 | ||
19004 | @tab | |
19005 | ||
19006 | Object_Size | |
19007 | ||
19008 | @tab | |
19009 | ||
19010 | Value_Size | |
19011 | ||
19012 | @item | |
19013 | ||
19014 | @code{type x1 is range 0 .. 5;} | |
19015 | ||
19016 | @tab | |
19017 | ||
19018 | 8 | |
19019 | ||
19020 | @tab | |
19021 | ||
19022 | 3 | |
19023 | ||
19024 | @item | |
19025 | ||
19026 | @code{type x2 is range 0 .. 5;} | |
19027 | @code{for x2'size use 12;} | |
19028 | ||
19029 | @tab | |
19030 | ||
19031 | 16 | |
19032 | ||
19033 | @tab | |
19034 | ||
19035 | 12 | |
19036 | ||
19037 | @item | |
19038 | ||
19039 | @code{subtype x3 is x2 range 0 .. 3;} | |
19040 | ||
19041 | @tab | |
19042 | ||
19043 | 16 | |
19044 | ||
19045 | @tab | |
19046 | ||
19047 | 2 | |
19048 | ||
19049 | @item | |
19050 | ||
19051 | @code{subtype x4 is x2'base range 0 .. 10;} | |
19052 | ||
19053 | @tab | |
19054 | ||
19055 | 8 | |
19056 | ||
19057 | @tab | |
19058 | ||
19059 | 4 | |
19060 | ||
19061 | @item | |
19062 | ||
19063 | @code{dynamic : x2'Base range -64 .. +63;} | |
19064 | ||
19065 | @tab | |
19066 | ||
19067 | @tab | |
19068 | ||
19069 | @item | |
19070 | ||
19071 | @code{subtype x5 is x2 range 0 .. dynamic;} | |
19072 | ||
19073 | @tab | |
19074 | ||
19075 | 16 | |
19076 | ||
19077 | @tab | |
19078 | ||
19079 | 3* | |
19080 | ||
19081 | @item | |
19082 | ||
19083 | @code{subtype x6 is x2'base range 0 .. dynamic;} | |
19084 | ||
19085 | @tab | |
19086 | ||
19087 | 8 | |
19088 | ||
19089 | @tab | |
19090 | ||
19091 | 7* | |
19092 | ||
19093 | @end multitable | |
19094 | ||
19095 | ||
19096 | Note: the entries marked ‘*’ are not actually specified by the Ada | |
19097 | Reference Manual, which has nothing to say about size in the dynamic | |
19098 | case. What GNAT does is to allocate sufficient bits to accommodate any | |
19099 | possible dynamic values for the bounds at run-time. | |
19100 | ||
19101 | So far, so good, but GNAT has to obey the RM rules, so the question is | |
19102 | under what conditions must the RM @code{Size} be used. | |
19103 | The following is a list | |
19104 | of the occasions on which the RM @code{Size} must be used: | |
19105 | ||
19106 | ||
19107 | @itemize * | |
19108 | ||
19109 | @item | |
19110 | Component size for packed arrays or records | |
19111 | ||
19112 | @item | |
19113 | Value of the attribute @code{Size} for a type | |
19114 | ||
19115 | @item | |
19116 | Warning about sizes not matching for unchecked conversion | |
19117 | @end itemize | |
19118 | ||
19119 | For record types, the @code{Object_Size} is always a multiple of the | |
19120 | alignment of the type (this is true for all types). In some cases the | |
19121 | @code{Value_Size} can be smaller. Consider: | |
19122 | ||
19123 | @example | |
19124 | type R is record | |
19125 | X : Integer; | |
19126 | Y : Character; | |
19127 | end record; | |
19128 | @end example | |
19129 | ||
19130 | On a typical 32-bit architecture, the X component will occupy four bytes | |
19131 | and the Y component will occupy one byte, for a total of 5 bytes. As a | |
19132 | result @code{R'Value_Size} will be 40 (bits) since this is the minimum size | |
19133 | required to store a value of this type. For example, it is permissible | |
19134 | to have a component of type R in an array whose component size is | |
19135 | specified to be 40 bits. | |
19136 | ||
19137 | However, @code{R'Object_Size} will be 64 (bits). The difference is due to | |
19138 | the alignment requirement for objects of the record type. The X | |
19139 | component will require four-byte alignment because that is what type | |
19140 | Integer requires, whereas the Y component, a Character, will only | |
19141 | require 1-byte alignment. Since the alignment required for X is the | |
19142 | greatest of all the components’ alignments, that is the alignment | |
19143 | required for the enclosing record type, i.e., 4 bytes or 32 bits. As | |
19144 | indicated above, the actual object size must be rounded up so that it is | |
19145 | a multiple of the alignment value. Therefore, 40 bits rounded up to the | |
19146 | next multiple of 32 yields 64 bits. | |
19147 | ||
19148 | For all other types, the @code{Object_Size} | |
19149 | and @code{Value_Size} are the same (and equivalent to the RM attribute @code{Size}). | |
19150 | Only @code{Size} may be specified for such types. | |
19151 | ||
19152 | Note that @code{Value_Size} can be used to force biased representation | |
19153 | for a particular subtype. Consider this example: | |
19154 | ||
19155 | @example | |
19156 | type R is (A, B, C, D, E, F); | |
19157 | subtype RAB is R range A .. B; | |
19158 | subtype REF is R range E .. F; | |
19159 | @end example | |
19160 | ||
19161 | By default, @code{RAB} | |
19162 | has a size of 1 (sufficient to accommodate the representation | |
19163 | of @code{A} and @code{B}, 0 and 1), and @code{REF} | |
19164 | has a size of 3 (sufficient to accommodate the representation | |
19165 | of @code{E} and @code{F}, 4 and 5). But if we add the | |
19166 | following @code{Value_Size} attribute definition clause: | |
19167 | ||
19168 | @example | |
19169 | for REF'Value_Size use 1; | |
19170 | @end example | |
19171 | ||
19172 | then biased representation is forced for @code{REF}, | |
19173 | and 0 will represent @code{E} and 1 will represent @code{F}. | |
19174 | A warning is issued when a @code{Value_Size} attribute | |
19175 | definition clause forces biased representation. This | |
19176 | warning can be turned off using @code{-gnatw.B}. | |
19177 | ||
19178 | @node Component_Size Clauses,Bit_Order Clauses,Value_Size and Object_Size Clauses,Representation Clauses and Pragmas | |
9daee425 | 19179 | @anchor{gnat_rm/representation_clauses_and_pragmas component-size-clauses}@anchor{291}@anchor{gnat_rm/representation_clauses_and_pragmas id8}@anchor{292} |
64d5610f ML |
19180 | @section Component_Size Clauses |
19181 | ||
19182 | ||
19183 | @geindex Component_Size Clause | |
19184 | ||
19185 | Normally, the value specified in a component size clause must be consistent | |
19186 | with the subtype of the array component with regard to size and alignment. | |
19187 | In other words, the value specified must be at least equal to the size | |
19188 | of this subtype, and must be a multiple of the alignment value. | |
19189 | ||
19190 | In addition, component size clauses are allowed which cause the array | |
19191 | to be packed, by specifying a smaller value. A first case is for | |
19192 | component size values in the range 1 through 63 on 32-bit targets, | |
19193 | and 1 through 127 on 64-bit targets. The value specified may not | |
19194 | be smaller than the Size of the subtype. GNAT will accurately | |
19195 | honor all packing requests in this range. For example, if we have: | |
19196 | ||
19197 | @example | |
19198 | type r is array (1 .. 8) of Natural; | |
19199 | for r'Component_Size use 31; | |
19200 | @end example | |
19201 | ||
19202 | then the resulting array has a length of 31 bytes (248 bits = 8 * 31). | |
19203 | Of course access to the components of such an array is considerably | |
19204 | less efficient than if the natural component size of 32 is used. | |
19205 | A second case is when the subtype of the component is a record type | |
19206 | padded because of its default alignment. For example, if we have: | |
19207 | ||
19208 | @example | |
19209 | type r is record | |
19210 | i : Integer; | |
19211 | j : Integer; | |
19212 | b : Boolean; | |
19213 | end record; | |
19214 | ||
19215 | type a is array (1 .. 8) of r; | |
19216 | for a'Component_Size use 72; | |
19217 | @end example | |
19218 | ||
19219 | then the resulting array has a length of 72 bytes, instead of 96 bytes | |
19220 | if the alignment of the record (4) was obeyed. | |
19221 | ||
19222 | Note that there is no point in giving both a component size clause | |
19223 | and a pragma Pack for the same array type. if such duplicate | |
19224 | clauses are given, the pragma Pack will be ignored. | |
19225 | ||
19226 | @node Bit_Order Clauses,Effect of Bit_Order on Byte Ordering,Component_Size Clauses,Representation Clauses and Pragmas | |
9daee425 | 19227 | @anchor{gnat_rm/representation_clauses_and_pragmas bit-order-clauses}@anchor{293}@anchor{gnat_rm/representation_clauses_and_pragmas id9}@anchor{294} |
64d5610f ML |
19228 | @section Bit_Order Clauses |
19229 | ||
19230 | ||
19231 | @geindex Bit_Order Clause | |
19232 | ||
19233 | @geindex bit ordering | |
19234 | ||
19235 | @geindex ordering | |
19236 | @geindex of bits | |
19237 | ||
19238 | For record subtypes, GNAT permits the specification of the @code{Bit_Order} | |
19239 | attribute. The specification may either correspond to the default bit | |
19240 | order for the target, in which case the specification has no effect and | |
19241 | places no additional restrictions, or it may be for the non-standard | |
19242 | setting (that is the opposite of the default). | |
19243 | ||
19244 | In the case where the non-standard value is specified, the effect is | |
19245 | to renumber bits within each byte, but the ordering of bytes is not | |
19246 | affected. There are certain | |
19247 | restrictions placed on component clauses as follows: | |
19248 | ||
19249 | ||
19250 | @itemize * | |
19251 | ||
19252 | @item | |
19253 | Components fitting within a single storage unit. | |
19254 | ||
19255 | These are unrestricted, and the effect is merely to renumber bits. For | |
19256 | example if we are on a little-endian machine with @code{Low_Order_First} | |
19257 | being the default, then the following two declarations have exactly | |
19258 | the same effect: | |
19259 | ||
19260 | @example | |
19261 | type R1 is record | |
19262 | A : Boolean; | |
19263 | B : Integer range 1 .. 120; | |
19264 | end record; | |
19265 | ||
19266 | for R1 use record | |
19267 | A at 0 range 0 .. 0; | |
19268 | B at 0 range 1 .. 7; | |
19269 | end record; | |
19270 | ||
19271 | type R2 is record | |
19272 | A : Boolean; | |
19273 | B : Integer range 1 .. 120; | |
19274 | end record; | |
19275 | ||
19276 | for R2'Bit_Order use High_Order_First; | |
19277 | ||
19278 | for R2 use record | |
19279 | A at 0 range 7 .. 7; | |
19280 | B at 0 range 0 .. 6; | |
19281 | end record; | |
19282 | @end example | |
19283 | ||
19284 | The useful application here is to write the second declaration with the | |
19285 | @code{Bit_Order} attribute definition clause, and know that it will be treated | |
19286 | the same, regardless of whether the target is little-endian or big-endian. | |
19287 | ||
19288 | @item | |
19289 | Components occupying an integral number of bytes. | |
19290 | ||
19291 | These are components that exactly fit in two or more bytes. Such component | |
19292 | declarations are allowed, but have no effect, since it is important to realize | |
19293 | that the @code{Bit_Order} specification does not affect the ordering of bytes. | |
19294 | In particular, the following attempt at getting an endian-independent integer | |
19295 | does not work: | |
19296 | ||
19297 | @example | |
19298 | type R2 is record | |
19299 | A : Integer; | |
19300 | end record; | |
19301 | ||
19302 | for R2'Bit_Order use High_Order_First; | |
19303 | ||
19304 | for R2 use record | |
19305 | A at 0 range 0 .. 31; | |
19306 | end record; | |
19307 | @end example | |
19308 | ||
19309 | This declaration will result in a little-endian integer on a | |
19310 | little-endian machine, and a big-endian integer on a big-endian machine. | |
19311 | If byte flipping is required for interoperability between big- and | |
19312 | little-endian machines, this must be explicitly programmed. This capability | |
19313 | is not provided by @code{Bit_Order}. | |
19314 | ||
19315 | @item | |
19316 | Components that are positioned across byte boundaries. | |
19317 | ||
19318 | but do not occupy an integral number of bytes. Given that bytes are not | |
19319 | reordered, such fields would occupy a non-contiguous sequence of bits | |
19320 | in memory, requiring non-trivial code to reassemble. They are for this | |
19321 | reason not permitted, and any component clause specifying such a layout | |
19322 | will be flagged as illegal by GNAT. | |
19323 | @end itemize | |
19324 | ||
19325 | Since the misconception that Bit_Order automatically deals with all | |
19326 | endian-related incompatibilities is a common one, the specification of | |
19327 | a component field that is an integral number of bytes will always | |
19328 | generate a warning. This warning may be suppressed using @code{pragma Warnings (Off)} | |
19329 | if desired. The following section contains additional | |
19330 | details regarding the issue of byte ordering. | |
19331 | ||
19332 | @node Effect of Bit_Order on Byte Ordering,Pragma Pack for Arrays,Bit_Order Clauses,Representation Clauses and Pragmas | |
9daee425 | 19333 | @anchor{gnat_rm/representation_clauses_and_pragmas effect-of-bit-order-on-byte-ordering}@anchor{295}@anchor{gnat_rm/representation_clauses_and_pragmas id10}@anchor{296} |
64d5610f ML |
19334 | @section Effect of Bit_Order on Byte Ordering |
19335 | ||
19336 | ||
19337 | @geindex byte ordering | |
19338 | ||
19339 | @geindex ordering | |
19340 | @geindex of bytes | |
19341 | ||
19342 | In this section we will review the effect of the @code{Bit_Order} attribute | |
19343 | definition clause on byte ordering. Briefly, it has no effect at all, but | |
19344 | a detailed example will be helpful. Before giving this | |
19345 | example, let us review the precise | |
19346 | definition of the effect of defining @code{Bit_Order}. The effect of a | |
19347 | non-standard bit order is described in section 13.5.3 of the Ada | |
19348 | Reference Manual: | |
19349 | ||
19350 | @quotation | |
19351 | ||
19352 | “2 A bit ordering is a method of interpreting the meaning of | |
19353 | the storage place attributes.” | |
19354 | @end quotation | |
19355 | ||
19356 | To understand the precise definition of storage place attributes in | |
19357 | this context, we visit section 13.5.1 of the manual: | |
19358 | ||
19359 | @quotation | |
19360 | ||
19361 | “13 A record_representation_clause (without the mod_clause) | |
19362 | specifies the layout. The storage place attributes (see 13.5.2) | |
19363 | are taken from the values of the position, first_bit, and last_bit | |
19364 | expressions after normalizing those values so that first_bit is | |
19365 | less than Storage_Unit.” | |
19366 | @end quotation | |
19367 | ||
19368 | The critical point here is that storage places are taken from | |
19369 | the values after normalization, not before. So the @code{Bit_Order} | |
19370 | interpretation applies to normalized values. The interpretation | |
19371 | is described in the later part of the 13.5.3 paragraph: | |
19372 | ||
19373 | @quotation | |
19374 | ||
19375 | “2 A bit ordering is a method of interpreting the meaning of | |
19376 | the storage place attributes. High_Order_First (known in the | |
19377 | vernacular as ‘big endian’) means that the first bit of a | |
19378 | storage element (bit 0) is the most significant bit (interpreting | |
19379 | the sequence of bits that represent a component as an unsigned | |
19380 | integer value). Low_Order_First (known in the vernacular as | |
19381 | ‘little endian’) means the opposite: the first bit is the | |
19382 | least significant.” | |
19383 | @end quotation | |
19384 | ||
19385 | Note that the numbering is with respect to the bits of a storage | |
19386 | unit. In other words, the specification affects only the numbering | |
19387 | of bits within a single storage unit. | |
19388 | ||
19389 | We can make the effect clearer by giving an example. | |
19390 | ||
19391 | Suppose that we have an external device which presents two bytes, the first | |
19392 | byte presented, which is the first (low addressed byte) of the two byte | |
19393 | record is called Master, and the second byte is called Slave. | |
19394 | ||
19395 | The left most (most significant) bit is called Control for each byte, and | |
19396 | the remaining 7 bits are called V1, V2, … V7, where V7 is the rightmost | |
19397 | (least significant) bit. | |
19398 | ||
19399 | On a big-endian machine, we can write the following representation clause | |
19400 | ||
19401 | @example | |
19402 | type Data is record | |
19403 | Master_Control : Bit; | |
19404 | Master_V1 : Bit; | |
19405 | Master_V2 : Bit; | |
19406 | Master_V3 : Bit; | |
19407 | Master_V4 : Bit; | |
19408 | Master_V5 : Bit; | |
19409 | Master_V6 : Bit; | |
19410 | Master_V7 : Bit; | |
19411 | Slave_Control : Bit; | |
19412 | Slave_V1 : Bit; | |
19413 | Slave_V2 : Bit; | |
19414 | Slave_V3 : Bit; | |
19415 | Slave_V4 : Bit; | |
19416 | Slave_V5 : Bit; | |
19417 | Slave_V6 : Bit; | |
19418 | Slave_V7 : Bit; | |
19419 | end record; | |
19420 | ||
19421 | for Data use record | |
19422 | Master_Control at 0 range 0 .. 0; | |
19423 | Master_V1 at 0 range 1 .. 1; | |
19424 | Master_V2 at 0 range 2 .. 2; | |
19425 | Master_V3 at 0 range 3 .. 3; | |
19426 | Master_V4 at 0 range 4 .. 4; | |
19427 | Master_V5 at 0 range 5 .. 5; | |
19428 | Master_V6 at 0 range 6 .. 6; | |
19429 | Master_V7 at 0 range 7 .. 7; | |
19430 | Slave_Control at 1 range 0 .. 0; | |
19431 | Slave_V1 at 1 range 1 .. 1; | |
19432 | Slave_V2 at 1 range 2 .. 2; | |
19433 | Slave_V3 at 1 range 3 .. 3; | |
19434 | Slave_V4 at 1 range 4 .. 4; | |
19435 | Slave_V5 at 1 range 5 .. 5; | |
19436 | Slave_V6 at 1 range 6 .. 6; | |
19437 | Slave_V7 at 1 range 7 .. 7; | |
19438 | end record; | |
19439 | @end example | |
19440 | ||
19441 | Now if we move this to a little endian machine, then the bit ordering within | |
19442 | the byte is backwards, so we have to rewrite the record rep clause as: | |
19443 | ||
19444 | @example | |
19445 | for Data use record | |
19446 | Master_Control at 0 range 7 .. 7; | |
19447 | Master_V1 at 0 range 6 .. 6; | |
19448 | Master_V2 at 0 range 5 .. 5; | |
19449 | Master_V3 at 0 range 4 .. 4; | |
19450 | Master_V4 at 0 range 3 .. 3; | |
19451 | Master_V5 at 0 range 2 .. 2; | |
19452 | Master_V6 at 0 range 1 .. 1; | |
19453 | Master_V7 at 0 range 0 .. 0; | |
19454 | Slave_Control at 1 range 7 .. 7; | |
19455 | Slave_V1 at 1 range 6 .. 6; | |
19456 | Slave_V2 at 1 range 5 .. 5; | |
19457 | Slave_V3 at 1 range 4 .. 4; | |
19458 | Slave_V4 at 1 range 3 .. 3; | |
19459 | Slave_V5 at 1 range 2 .. 2; | |
19460 | Slave_V6 at 1 range 1 .. 1; | |
19461 | Slave_V7 at 1 range 0 .. 0; | |
19462 | end record; | |
19463 | @end example | |
19464 | ||
19465 | It is a nuisance to have to rewrite the clause, especially if | |
19466 | the code has to be maintained on both machines. However, | |
19467 | this is a case that we can handle with the | |
19468 | @code{Bit_Order} attribute if it is implemented. | |
19469 | Note that the implementation is not required on byte addressed | |
19470 | machines, but it is indeed implemented in GNAT. | |
19471 | This means that we can simply use the | |
19472 | first record clause, together with the declaration | |
19473 | ||
19474 | @example | |
19475 | for Data'Bit_Order use High_Order_First; | |
19476 | @end example | |
19477 | ||
19478 | and the effect is what is desired, namely the layout is exactly the same, | |
19479 | independent of whether the code is compiled on a big-endian or little-endian | |
19480 | machine. | |
19481 | ||
19482 | The important point to understand is that byte ordering is not affected. | |
19483 | A @code{Bit_Order} attribute definition never affects which byte a field | |
19484 | ends up in, only where it ends up in that byte. | |
19485 | To make this clear, let us rewrite the record rep clause of the previous | |
19486 | example as: | |
19487 | ||
19488 | @example | |
19489 | for Data'Bit_Order use High_Order_First; | |
19490 | for Data use record | |
19491 | Master_Control at 0 range 0 .. 0; | |
19492 | Master_V1 at 0 range 1 .. 1; | |
19493 | Master_V2 at 0 range 2 .. 2; | |
19494 | Master_V3 at 0 range 3 .. 3; | |
19495 | Master_V4 at 0 range 4 .. 4; | |
19496 | Master_V5 at 0 range 5 .. 5; | |
19497 | Master_V6 at 0 range 6 .. 6; | |
19498 | Master_V7 at 0 range 7 .. 7; | |
19499 | Slave_Control at 0 range 8 .. 8; | |
19500 | Slave_V1 at 0 range 9 .. 9; | |
19501 | Slave_V2 at 0 range 10 .. 10; | |
19502 | Slave_V3 at 0 range 11 .. 11; | |
19503 | Slave_V4 at 0 range 12 .. 12; | |
19504 | Slave_V5 at 0 range 13 .. 13; | |
19505 | Slave_V6 at 0 range 14 .. 14; | |
19506 | Slave_V7 at 0 range 15 .. 15; | |
19507 | end record; | |
19508 | @end example | |
19509 | ||
19510 | This is exactly equivalent to saying (a repeat of the first example): | |
19511 | ||
19512 | @example | |
19513 | for Data'Bit_Order use High_Order_First; | |
19514 | for Data use record | |
19515 | Master_Control at 0 range 0 .. 0; | |
19516 | Master_V1 at 0 range 1 .. 1; | |
19517 | Master_V2 at 0 range 2 .. 2; | |
19518 | Master_V3 at 0 range 3 .. 3; | |
19519 | Master_V4 at 0 range 4 .. 4; | |
19520 | Master_V5 at 0 range 5 .. 5; | |
19521 | Master_V6 at 0 range 6 .. 6; | |
19522 | Master_V7 at 0 range 7 .. 7; | |
19523 | Slave_Control at 1 range 0 .. 0; | |
19524 | Slave_V1 at 1 range 1 .. 1; | |
19525 | Slave_V2 at 1 range 2 .. 2; | |
19526 | Slave_V3 at 1 range 3 .. 3; | |
19527 | Slave_V4 at 1 range 4 .. 4; | |
19528 | Slave_V5 at 1 range 5 .. 5; | |
19529 | Slave_V6 at 1 range 6 .. 6; | |
19530 | Slave_V7 at 1 range 7 .. 7; | |
19531 | end record; | |
19532 | @end example | |
19533 | ||
19534 | Why are they equivalent? Well take a specific field, the @code{Slave_V2} | |
19535 | field. The storage place attributes are obtained by normalizing the | |
19536 | values given so that the @code{First_Bit} value is less than 8. After | |
19537 | normalizing the values (0,10,10) we get (1,2,2) which is exactly what | |
19538 | we specified in the other case. | |
19539 | ||
19540 | Now one might expect that the @code{Bit_Order} attribute might affect | |
19541 | bit numbering within the entire record component (two bytes in this | |
19542 | case, thus affecting which byte fields end up in), but that is not | |
19543 | the way this feature is defined, it only affects numbering of bits, | |
19544 | not which byte they end up in. | |
19545 | ||
19546 | Consequently it never makes sense to specify a starting bit number | |
19547 | greater than 7 (for a byte addressable field) if an attribute | |
19548 | definition for @code{Bit_Order} has been given, and indeed it | |
19549 | may be actively confusing to specify such a value, so the compiler | |
19550 | generates a warning for such usage. | |
19551 | ||
19552 | If you do need to control byte ordering then appropriate conditional | |
19553 | values must be used. If in our example, the slave byte came first on | |
19554 | some machines we might write: | |
19555 | ||
19556 | @example | |
19557 | Master_Byte_First constant Boolean := ...; | |
19558 | ||
19559 | Master_Byte : constant Natural := | |
19560 | 1 - Boolean'Pos (Master_Byte_First); | |
19561 | Slave_Byte : constant Natural := | |
19562 | Boolean'Pos (Master_Byte_First); | |
19563 | ||
19564 | for Data'Bit_Order use High_Order_First; | |
19565 | for Data use record | |
19566 | Master_Control at Master_Byte range 0 .. 0; | |
19567 | Master_V1 at Master_Byte range 1 .. 1; | |
19568 | Master_V2 at Master_Byte range 2 .. 2; | |
19569 | Master_V3 at Master_Byte range 3 .. 3; | |
19570 | Master_V4 at Master_Byte range 4 .. 4; | |
19571 | Master_V5 at Master_Byte range 5 .. 5; | |
19572 | Master_V6 at Master_Byte range 6 .. 6; | |
19573 | Master_V7 at Master_Byte range 7 .. 7; | |
19574 | Slave_Control at Slave_Byte range 0 .. 0; | |
19575 | Slave_V1 at Slave_Byte range 1 .. 1; | |
19576 | Slave_V2 at Slave_Byte range 2 .. 2; | |
19577 | Slave_V3 at Slave_Byte range 3 .. 3; | |
19578 | Slave_V4 at Slave_Byte range 4 .. 4; | |
19579 | Slave_V5 at Slave_Byte range 5 .. 5; | |
19580 | Slave_V6 at Slave_Byte range 6 .. 6; | |
19581 | Slave_V7 at Slave_Byte range 7 .. 7; | |
19582 | end record; | |
19583 | @end example | |
19584 | ||
19585 | Now to switch between machines, all that is necessary is | |
19586 | to set the boolean constant @code{Master_Byte_First} in | |
19587 | an appropriate manner. | |
19588 | ||
19589 | @node Pragma Pack for Arrays,Pragma Pack for Records,Effect of Bit_Order on Byte Ordering,Representation Clauses and Pragmas | |
9daee425 | 19590 | @anchor{gnat_rm/representation_clauses_and_pragmas id11}@anchor{297}@anchor{gnat_rm/representation_clauses_and_pragmas pragma-pack-for-arrays}@anchor{298} |
64d5610f ML |
19591 | @section Pragma Pack for Arrays |
19592 | ||
19593 | ||
19594 | @geindex Pragma Pack (for arrays) | |
19595 | ||
19596 | Pragma @code{Pack} applied to an array has an effect that depends upon whether the | |
1acce141 | 19597 | component type is @emph{packable}. For a component type to be @emph{packable}, it must |
64d5610f ML |
19598 | be one of the following cases: |
19599 | ||
19600 | ||
19601 | @itemize * | |
19602 | ||
19603 | @item | |
19604 | Any elementary type. | |
19605 | ||
19606 | @item | |
19607 | Any small packed array type with a static size. | |
19608 | ||
19609 | @item | |
19610 | Any small simple record type with a static size. | |
19611 | @end itemize | |
19612 | ||
19613 | For all these cases, if the component subtype size is in the range | |
19614 | 1 through 63 on 32-bit targets, and 1 through 127 on 64-bit targets, | |
19615 | then the effect of the pragma @code{Pack} is exactly as though a | |
19616 | component size were specified giving the component subtype size. | |
19617 | ||
19618 | All other types are non-packable, they occupy an integral number of storage | |
19619 | units and the only effect of pragma Pack is to remove alignment gaps. | |
19620 | ||
19621 | For example if we have: | |
19622 | ||
19623 | @example | |
19624 | type r is range 0 .. 17; | |
19625 | ||
19626 | type ar is array (1 .. 8) of r; | |
19627 | pragma Pack (ar); | |
19628 | @end example | |
19629 | ||
19630 | Then the component size of @code{ar} will be set to 5 (i.e., to @code{r'size}, | |
19631 | and the size of the array @code{ar} will be exactly 40 bits). | |
19632 | ||
19633 | Note that in some cases this rather fierce approach to packing can produce | |
19634 | unexpected effects. For example, in Ada 95 and Ada 2005, | |
19635 | subtype @code{Natural} typically has a size of 31, meaning that if you | |
19636 | pack an array of @code{Natural}, you get 31-bit | |
19637 | close packing, which saves a few bits, but results in far less efficient | |
19638 | access. Since many other Ada compilers will ignore such a packing request, | |
19639 | GNAT will generate a warning on some uses of pragma @code{Pack} that it guesses | |
19640 | might not be what is intended. You can easily remove this warning by | |
19641 | using an explicit @code{Component_Size} setting instead, which never generates | |
19642 | a warning, since the intention of the programmer is clear in this case. | |
19643 | ||
19644 | GNAT treats packed arrays in one of two ways. If the size of the array is | |
19645 | known at compile time and is at most 64 bits on 32-bit targets, and at most | |
19646 | 128 bits on 64-bit targets, then internally the array is represented as a | |
19647 | single modular type, of exactly the appropriate number of bits. If the | |
19648 | length is greater than 64 bits on 32-bit targets, and greater than 128 | |
19649 | bits on 64-bit targets, or is not known at compile time, then the packed | |
19650 | array is represented as an array of bytes, and its length is always a | |
19651 | multiple of 8 bits. | |
19652 | ||
19653 | Note that to represent a packed array as a modular type, the alignment must | |
19654 | be suitable for the modular type involved. For example, on typical machines | |
19655 | a 32-bit packed array will be represented by a 32-bit modular integer with | |
19656 | an alignment of four bytes. If you explicitly override the default alignment | |
19657 | with an alignment clause that is too small, the modular representation | |
19658 | cannot be used. For example, consider the following set of declarations: | |
19659 | ||
19660 | @example | |
19661 | type R is range 1 .. 3; | |
19662 | type S is array (1 .. 31) of R; | |
19663 | for S'Component_Size use 2; | |
19664 | for S'Size use 62; | |
19665 | for S'Alignment use 1; | |
19666 | @end example | |
19667 | ||
19668 | If the alignment clause were not present, then a 62-bit modular | |
19669 | representation would be chosen (typically with an alignment of 4 or 8 | |
19670 | bytes depending on the target). But the default alignment is overridden | |
19671 | with the explicit alignment clause. This means that the modular | |
19672 | representation cannot be used, and instead the array of bytes | |
19673 | representation must be used, meaning that the length must be a multiple | |
19674 | of 8. Thus the above set of declarations will result in a diagnostic | |
19675 | rejecting the size clause and noting that the minimum size allowed is 64. | |
19676 | ||
19677 | @geindex Pragma Pack (for type Natural) | |
19678 | ||
19679 | @geindex Pragma Pack warning | |
19680 | ||
19681 | One special case that is worth noting occurs when the base type of the | |
19682 | component size is 8/16/32 and the subtype is one bit less. Notably this | |
19683 | occurs with subtype @code{Natural}. Consider: | |
19684 | ||
19685 | @example | |
19686 | type Arr is array (1 .. 32) of Natural; | |
19687 | pragma Pack (Arr); | |
19688 | @end example | |
19689 | ||
19690 | In all commonly used Ada 83 compilers, this pragma Pack would be ignored, | |
19691 | since typically @code{Natural'Size} is 32 in Ada 83, and in any case most | |
19692 | Ada 83 compilers did not attempt 31 bit packing. | |
19693 | ||
19694 | In Ada 95 and Ada 2005, @code{Natural'Size} is required to be 31. Furthermore, | |
19695 | GNAT really does pack 31-bit subtype to 31 bits. This may result in a | |
19696 | substantial unintended performance penalty when porting legacy Ada 83 code. | |
19697 | To help prevent this, GNAT generates a warning in such cases. If you really | |
19698 | want 31 bit packing in a case like this, you can set the component size | |
19699 | explicitly: | |
19700 | ||
19701 | @example | |
19702 | type Arr is array (1 .. 32) of Natural; | |
19703 | for Arr'Component_Size use 31; | |
19704 | @end example | |
19705 | ||
19706 | Here 31-bit packing is achieved as required, and no warning is generated, | |
19707 | since in this case the programmer intention is clear. | |
19708 | ||
19709 | @node Pragma Pack for Records,Record Representation Clauses,Pragma Pack for Arrays,Representation Clauses and Pragmas | |
9daee425 | 19710 | @anchor{gnat_rm/representation_clauses_and_pragmas id12}@anchor{299}@anchor{gnat_rm/representation_clauses_and_pragmas pragma-pack-for-records}@anchor{29a} |
64d5610f ML |
19711 | @section Pragma Pack for Records |
19712 | ||
19713 | ||
19714 | @geindex Pragma Pack (for records) | |
19715 | ||
19716 | Pragma @code{Pack} applied to a record will pack the components to reduce | |
19717 | wasted space from alignment gaps and by reducing the amount of space | |
1acce141 YM |
19718 | taken by components. We distinguish between @emph{packable} components and |
19719 | @emph{non-packable} components. | |
64d5610f ML |
19720 | Components of the following types are considered packable: |
19721 | ||
19722 | ||
19723 | @itemize * | |
19724 | ||
19725 | @item | |
19726 | Components of an elementary type are packable unless they are aliased, | |
19727 | independent or atomic. | |
19728 | ||
19729 | @item | |
19730 | Small packed arrays, where the size is statically known, are represented | |
19731 | internally as modular integers, and so they are also packable. | |
19732 | ||
19733 | @item | |
19734 | Small simple records, where the size is statically known, are also packable. | |
19735 | @end itemize | |
19736 | ||
19737 | For all these cases, if the @code{'Size} value is in the range 1 through 64 on | |
19738 | 32-bit targets, and 1 through 128 on 64-bit targets, the components occupy | |
19739 | the exact number of bits corresponding to this value and are packed with no | |
19740 | padding bits, i.e. they can start on an arbitrary bit boundary. | |
19741 | ||
19742 | All other types are non-packable, they occupy an integral number of storage | |
19743 | units and the only effect of pragma @code{Pack} is to remove alignment gaps. | |
19744 | ||
19745 | For example, consider the record | |
19746 | ||
19747 | @example | |
19748 | type Rb1 is array (1 .. 13) of Boolean; | |
19749 | pragma Pack (Rb1); | |
19750 | ||
19751 | type Rb2 is array (1 .. 65) of Boolean; | |
19752 | pragma Pack (Rb2); | |
19753 | ||
19754 | type AF is new Float with Atomic; | |
19755 | ||
19756 | type X2 is record | |
19757 | L1 : Boolean; | |
19758 | L2 : Duration; | |
19759 | L3 : AF; | |
19760 | L4 : Boolean; | |
19761 | L5 : Rb1; | |
19762 | L6 : Rb2; | |
19763 | end record; | |
19764 | pragma Pack (X2); | |
19765 | @end example | |
19766 | ||
19767 | The representation for the record @code{X2} is as follows on 32-bit targets: | |
19768 | ||
19769 | @example | |
19770 | for X2'Size use 224; | |
19771 | for X2 use record | |
19772 | L1 at 0 range 0 .. 0; | |
19773 | L2 at 0 range 1 .. 64; | |
19774 | L3 at 12 range 0 .. 31; | |
19775 | L4 at 16 range 0 .. 0; | |
19776 | L5 at 16 range 1 .. 13; | |
19777 | L6 at 18 range 0 .. 71; | |
19778 | end record; | |
19779 | @end example | |
19780 | ||
19781 | Studying this example, we see that the packable fields @code{L1} | |
19782 | and @code{L2} are of length equal to their sizes, and placed at | |
19783 | specific bit boundaries (and not byte boundaries) to eliminate | |
19784 | padding. But @code{L3} is of a non-packable float type (because | |
19785 | it is aliased), so it is on the next appropriate alignment boundary. | |
19786 | ||
19787 | The next two fields are fully packable, so @code{L4} and @code{L5} are | |
19788 | minimally packed with no gaps. However, type @code{Rb2} is a packed | |
19789 | array that is longer than 64 bits, so it is itself non-packable on | |
19790 | 32-bit targets. Thus the @code{L6} field is aligned to the next byte | |
19791 | boundary, and takes an integral number of bytes, i.e., 72 bits. | |
19792 | ||
19793 | @node Record Representation Clauses,Handling of Records with Holes,Pragma Pack for Records,Representation Clauses and Pragmas | |
9daee425 | 19794 | @anchor{gnat_rm/representation_clauses_and_pragmas id13}@anchor{29b}@anchor{gnat_rm/representation_clauses_and_pragmas record-representation-clauses}@anchor{29c} |
64d5610f ML |
19795 | @section Record Representation Clauses |
19796 | ||
19797 | ||
19798 | @geindex Record Representation Clause | |
19799 | ||
19800 | Record representation clauses may be given for all record types, including | |
19801 | types obtained by record extension. Component clauses are allowed for any | |
19802 | static component. The restrictions on component clauses depend on the type | |
19803 | of the component. | |
19804 | ||
19805 | @geindex Component Clause | |
19806 | ||
19807 | For all components of an elementary type, the only restriction on component | |
19808 | clauses is that the size must be at least the @code{'Size} value of the type | |
19809 | (actually the Value_Size). There are no restrictions due to alignment, | |
19810 | and such components may freely cross storage boundaries. | |
19811 | ||
19812 | Packed arrays with a size up to and including 64 bits on 32-bit targets, | |
19813 | and up to and including 128 bits on 64-bit targets, are represented | |
19814 | internally using a modular type with the appropriate number of bits, and | |
19815 | thus the same lack of restriction applies. For example, if you declare: | |
19816 | ||
19817 | @example | |
19818 | type R is array (1 .. 49) of Boolean; | |
19819 | pragma Pack (R); | |
19820 | for R'Size use 49; | |
19821 | @end example | |
19822 | ||
19823 | then a component clause for a component of type @code{R} may start on any | |
19824 | specified bit boundary, and may specify a value of 49 bits or greater. | |
19825 | ||
19826 | For packed bit arrays that are longer than 64 bits on 32-bit targets, | |
19827 | and longer than 128 bits on 64-bit targets, there are two cases. If the | |
19828 | component size is a power of 2 (1,2,4,8,16,32,64 bits), including the | |
19829 | important case of single bits or boolean values, then there are no | |
19830 | limitations on placement of such components, and they may start and | |
19831 | end at arbitrary bit boundaries. | |
19832 | ||
19833 | If the component size is not a power of 2 (e.g., 3 or 5), then an array | |
19834 | of this type must always be placed on on a storage unit (byte) boundary | |
19835 | and occupy an integral number of storage units (bytes). Any component | |
19836 | clause that does not meet this requirement will be rejected. | |
19837 | ||
19838 | Any aliased component, or component of an aliased type, must have its | |
19839 | normal alignment and size. A component clause that does not meet this | |
19840 | requirement will be rejected. | |
19841 | ||
19842 | The tag field of a tagged type always occupies an address sized field at | |
19843 | the start of the record. No component clause may attempt to overlay this | |
19844 | tag. When a tagged type appears as a component, the tag field must have | |
19845 | proper alignment | |
19846 | ||
19847 | In the case of a record extension @code{T1}, of a type @code{T}, no component | |
19848 | clause applied to the type @code{T1} can specify a storage location that | |
19849 | would overlap the first @code{T'Object_Size} bits of the record. | |
19850 | ||
19851 | For all other component types, including non-bit-packed arrays, | |
19852 | the component can be placed at an arbitrary bit boundary, | |
19853 | so for example, the following is permitted: | |
19854 | ||
19855 | @example | |
19856 | type R is array (1 .. 10) of Boolean; | |
19857 | for R'Size use 80; | |
19858 | ||
19859 | type Q is record | |
19860 | G, H : Boolean; | |
19861 | L, M : R; | |
19862 | end record; | |
19863 | ||
19864 | for Q use record | |
19865 | G at 0 range 0 .. 0; | |
19866 | H at 0 range 1 .. 1; | |
19867 | L at 0 range 2 .. 81; | |
19868 | R at 0 range 82 .. 161; | |
19869 | end record; | |
19870 | @end example | |
19871 | ||
19872 | @node Handling of Records with Holes,Enumeration Clauses,Record Representation Clauses,Representation Clauses and Pragmas | |
9daee425 | 19873 | @anchor{gnat_rm/representation_clauses_and_pragmas handling-of-records-with-holes}@anchor{29d}@anchor{gnat_rm/representation_clauses_and_pragmas id14}@anchor{29e} |
64d5610f ML |
19874 | @section Handling of Records with Holes |
19875 | ||
19876 | ||
19877 | @geindex Handling of Records with Holes | |
19878 | ||
19879 | As a result of alignment considerations, records may contain “holes” | |
19880 | or gaps which do not correspond to the data bits of any of the components. | |
19881 | Record representation clauses can also result in holes in records. | |
19882 | ||
19883 | GNAT does not attempt to clear these holes, so in record objects, | |
19884 | they should be considered to hold undefined rubbish. The generated | |
19885 | equality routine just tests components so does not access these | |
19886 | undefined bits, and assignment and copy operations may or may not | |
19887 | preserve the contents of these holes (for assignments, the holes | |
19888 | in the target will in practice contain either the bits that are | |
19889 | present in the holes in the source, or the bits that were present | |
19890 | in the target before the assignment). | |
19891 | ||
19892 | If it is necessary to ensure that holes in records have all zero | |
19893 | bits, then record objects for which this initialization is desired | |
19894 | should be explicitly set to all zero values using Unchecked_Conversion | |
19895 | or address overlays. For example | |
19896 | ||
19897 | @example | |
19898 | type HRec is record | |
19899 | C : Character; | |
19900 | I : Integer; | |
19901 | end record; | |
19902 | @end example | |
19903 | ||
19904 | On typical machines, integers need to be aligned on a four-byte | |
19905 | boundary, resulting in three bytes of undefined rubbish following | |
19906 | the 8-bit field for C. To ensure that the hole in a variable of | |
19907 | type HRec is set to all zero bits, | |
19908 | you could for example do: | |
19909 | ||
19910 | @example | |
19911 | type Base is record | |
19912 | Dummy1, Dummy2 : Integer := 0; | |
19913 | end record; | |
19914 | ||
19915 | BaseVar : Base; | |
19916 | RealVar : Hrec; | |
19917 | for RealVar'Address use BaseVar'Address; | |
19918 | @end example | |
19919 | ||
19920 | Now the 8-bytes of the value of RealVar start out containing all zero | |
19921 | bits. A safer approach is to just define dummy fields, avoiding the | |
19922 | holes, as in: | |
19923 | ||
19924 | @example | |
19925 | type HRec is record | |
19926 | C : Character; | |
19927 | Dummy1 : Short_Short_Integer := 0; | |
19928 | Dummy2 : Short_Short_Integer := 0; | |
19929 | Dummy3 : Short_Short_Integer := 0; | |
19930 | I : Integer; | |
19931 | end record; | |
19932 | @end example | |
19933 | ||
19934 | And to make absolutely sure that the intent of this is followed, you | |
19935 | can use representation clauses: | |
19936 | ||
19937 | @example | |
19938 | for Hrec use record | |
19939 | C at 0 range 0 .. 7; | |
19940 | Dummy1 at 1 range 0 .. 7; | |
19941 | Dummy2 at 2 range 0 .. 7; | |
19942 | Dummy3 at 3 range 0 .. 7; | |
19943 | I at 4 range 0 .. 31; | |
19944 | end record; | |
19945 | for Hrec'Size use 64; | |
19946 | @end example | |
19947 | ||
19948 | @node Enumeration Clauses,Address Clauses,Handling of Records with Holes,Representation Clauses and Pragmas | |
9daee425 | 19949 | @anchor{gnat_rm/representation_clauses_and_pragmas enumeration-clauses}@anchor{29f}@anchor{gnat_rm/representation_clauses_and_pragmas id15}@anchor{2a0} |
64d5610f ML |
19950 | @section Enumeration Clauses |
19951 | ||
19952 | ||
19953 | The only restriction on enumeration clauses is that the range of values | |
19954 | must be representable. For the signed case, if one or more of the | |
19955 | representation values are negative, all values must be in the range: | |
19956 | ||
19957 | @example | |
19958 | System.Min_Int .. System.Max_Int | |
19959 | @end example | |
19960 | ||
19961 | For the unsigned case, where all values are nonnegative, the values must | |
19962 | be in the range: | |
19963 | ||
19964 | @example | |
19965 | 0 .. System.Max_Binary_Modulus; | |
19966 | @end example | |
19967 | ||
1acce141 | 19968 | A @emph{confirming} representation clause is one in which the values range |
64d5610f ML |
19969 | from 0 in sequence, i.e., a clause that confirms the default representation |
19970 | for an enumeration type. | |
19971 | Such a confirming representation | |
19972 | is permitted by these rules, and is specially recognized by the compiler so | |
19973 | that no extra overhead results from the use of such a clause. | |
19974 | ||
19975 | If an array has an index type which is an enumeration type to which an | |
19976 | enumeration clause has been applied, then the array is stored in a compact | |
19977 | manner. Consider the declarations: | |
19978 | ||
19979 | @example | |
19980 | type r is (A, B, C); | |
19981 | for r use (A => 1, B => 5, C => 10); | |
19982 | type t is array (r) of Character; | |
19983 | @end example | |
19984 | ||
19985 | The array type t corresponds to a vector with exactly three elements and | |
19986 | has a default size equal to @code{3*Character'Size}. This ensures efficient | |
19987 | use of space, but means that accesses to elements of the array will incur | |
19988 | the overhead of converting representation values to the corresponding | |
19989 | positional values, (i.e., the value delivered by the @code{Pos} attribute). | |
19990 | ||
19991 | @node Address Clauses,Use of Address Clauses for Memory-Mapped I/O,Enumeration Clauses,Representation Clauses and Pragmas | |
9daee425 | 19992 | @anchor{gnat_rm/representation_clauses_and_pragmas address-clauses}@anchor{2a1}@anchor{gnat_rm/representation_clauses_and_pragmas id16}@anchor{2a2} |
64d5610f ML |
19993 | @section Address Clauses |
19994 | ||
19995 | ||
19996 | @geindex Address Clause | |
19997 | ||
19998 | The reference manual allows a general restriction on representation clauses, | |
19999 | as found in RM 13.1(22): | |
20000 | ||
20001 | @quotation | |
20002 | ||
20003 | “An implementation need not support representation | |
20004 | items containing nonstatic expressions, except that | |
20005 | an implementation should support a representation item | |
20006 | for a given entity if each nonstatic expression in the | |
20007 | representation item is a name that statically denotes | |
20008 | a constant declared before the entity.” | |
20009 | @end quotation | |
20010 | ||
20011 | In practice this is applicable only to address clauses, since this is the | |
20012 | only case in which a nonstatic expression is permitted by the syntax. As | |
20013 | the AARM notes in sections 13.1 (22.a-22.h): | |
20014 | ||
20015 | @quotation | |
20016 | ||
20017 | 22.a Reason: This is to avoid the following sort of thing: | |
20018 | ||
20019 | 22.b X : Integer := F(…); | |
20020 | Y : Address := G(…); | |
20021 | for X’Address use Y; | |
20022 | ||
20023 | 22.c In the above, we have to evaluate the | |
20024 | initialization expression for X before we | |
20025 | know where to put the result. This seems | |
20026 | like an unreasonable implementation burden. | |
20027 | ||
20028 | 22.d The above code should instead be written | |
20029 | like this: | |
20030 | ||
20031 | 22.e Y : constant Address := G(…); | |
20032 | X : Integer := F(…); | |
20033 | for X’Address use Y; | |
20034 | ||
20035 | 22.f This allows the expression ‘Y’ to be safely | |
20036 | evaluated before X is created. | |
20037 | ||
20038 | 22.g The constant could be a formal parameter of mode in. | |
20039 | ||
20040 | 22.h An implementation can support other nonstatic | |
20041 | expressions if it wants to. Expressions of type | |
20042 | Address are hardly ever static, but their value | |
20043 | might be known at compile time anyway in many | |
20044 | cases. | |
20045 | @end quotation | |
20046 | ||
20047 | GNAT does indeed permit many additional cases of nonstatic expressions. In | |
20048 | particular, if the type involved is elementary there are no restrictions | |
20049 | (since in this case, holding a temporary copy of the initialization value, | |
20050 | if one is present, is inexpensive). In addition, if there is no implicit or | |
20051 | explicit initialization, then there are no restrictions. GNAT will reject | |
20052 | only the case where all three of these conditions hold: | |
20053 | ||
20054 | ||
20055 | @itemize * | |
20056 | ||
20057 | @item | |
20058 | The type of the item is non-elementary (e.g., a record or array). | |
20059 | ||
20060 | @item | |
20061 | There is explicit or implicit initialization required for the object. | |
20062 | Note that access values are always implicitly initialized. | |
20063 | ||
20064 | @item | |
20065 | The address value is nonstatic. Here GNAT is more permissive than the | |
20066 | RM, and allows the address value to be the address of a previously declared | |
20067 | stand-alone variable, as long as it does not itself have an address clause. | |
20068 | ||
20069 | @example | |
20070 | Anchor : Some_Initialized_Type; | |
20071 | Overlay : Some_Initialized_Type; | |
20072 | for Overlay'Address use Anchor'Address; | |
20073 | @end example | |
20074 | ||
20075 | However, the prefix of the address clause cannot be an array component, or | |
20076 | a component of a discriminated record. | |
20077 | @end itemize | |
20078 | ||
20079 | As noted above in section 22.h, address values are typically nonstatic. In | |
20080 | particular the To_Address function, even if applied to a literal value, is | |
20081 | a nonstatic function call. To avoid this minor annoyance, GNAT provides | |
20082 | the implementation defined attribute ‘To_Address. The following two | |
20083 | expressions have identical values: | |
20084 | ||
20085 | @geindex Attribute | |
20086 | ||
20087 | @geindex To_Address | |
20088 | ||
20089 | @example | |
20090 | To_Address (16#1234_0000#) | |
20091 | System'To_Address (16#1234_0000#); | |
20092 | @end example | |
20093 | ||
20094 | except that the second form is considered to be a static expression, and | |
20095 | thus when used as an address clause value is always permitted. | |
20096 | ||
20097 | Additionally, GNAT treats as static an address clause that is an | |
20098 | unchecked_conversion of a static integer value. This simplifies the porting | |
20099 | of legacy code, and provides a portable equivalent to the GNAT attribute | |
20100 | @code{To_Address}. | |
20101 | ||
20102 | Another issue with address clauses is the interaction with alignment | |
20103 | requirements. When an address clause is given for an object, the address | |
20104 | value must be consistent with the alignment of the object (which is usually | |
20105 | the same as the alignment of the type of the object). If an address clause | |
20106 | is given that specifies an inappropriately aligned address value, then the | |
20107 | program execution is erroneous. | |
20108 | ||
20109 | Since this source of erroneous behavior can have unfortunate effects on | |
20110 | machines with strict alignment requirements, GNAT | |
20111 | checks (at compile time if possible, generating a warning, or at execution | |
20112 | time with a run-time check) that the alignment is appropriate. If the | |
20113 | run-time check fails, then @code{Program_Error} is raised. This run-time | |
20114 | check is suppressed if range checks are suppressed, or if the special GNAT | |
20115 | check Alignment_Check is suppressed, or if | |
20116 | @code{pragma Restrictions (No_Elaboration_Code)} is in effect. It is also | |
20117 | suppressed by default on non-strict alignment machines (such as the x86). | |
20118 | ||
20119 | In some cases, GNAT does not support an address specification (using either | |
20120 | form of aspect specification syntax) for the declaration of an object that has | |
20121 | an indefinite nominal subtype. An object declaration has an indefinite | |
20122 | nominal subtype if it takes its bounds (for an array type), discriminant | |
20123 | values (for a discriminated type whose discriminants lack defaults), or tag | |
20124 | (for a class-wide type) from its initial value, as in | |
20125 | ||
20126 | @example | |
20127 | X : String := Some_Function_Call; | |
20128 | -- String has no constraint, so bounds for X come from function call | |
20129 | @end example | |
20130 | ||
20131 | This restriction does not apply if the size of the object’s initial value is | |
20132 | known at compile time and the type of the object is not class-wide. | |
20133 | ||
20134 | @geindex Export | |
20135 | ||
20136 | An address clause cannot be given for an exported object. More | |
20137 | understandably the real restriction is that objects with an address | |
20138 | clause cannot be exported. This is because such variables are not | |
20139 | defined by the Ada program, so there is no external object to export. | |
20140 | ||
20141 | @geindex Import | |
20142 | ||
20143 | It is permissible to give an address clause and a pragma Import for the | |
20144 | same object. In this case, the variable is not really defined by the | |
20145 | Ada program, so there is no external symbol to be linked. The link name | |
20146 | and the external name are ignored in this case. The reason that we allow this | |
20147 | combination is that it provides a useful idiom to avoid unwanted | |
20148 | initializations on objects with address clauses. | |
20149 | ||
20150 | When an address clause is given for an object that has implicit or | |
20151 | explicit initialization, then by default initialization takes place. This | |
20152 | means that the effect of the object declaration is to overwrite the | |
20153 | memory at the specified address. This is almost always not what the | |
20154 | programmer wants, so GNAT will output a warning: | |
20155 | ||
20156 | @example | |
20157 | with System; | |
20158 | package G is | |
20159 | type R is record | |
20160 | M : Integer := 0; | |
20161 | end record; | |
20162 | ||
20163 | Ext : R; | |
20164 | for Ext'Address use System'To_Address (16#1234_1234#); | |
20165 | | | |
20166 | >>> warning: implicit initialization of "Ext" may | |
20167 | modify overlaid storage | |
20168 | >>> warning: use pragma Import for "Ext" to suppress | |
20169 | initialization (RM B(24)) | |
20170 | ||
20171 | end G; | |
20172 | @end example | |
20173 | ||
20174 | As indicated by the warning message, the solution is to use a (dummy) pragma | |
20175 | Import to suppress this initialization. The pragma tell the compiler that the | |
20176 | object is declared and initialized elsewhere. The following package compiles | |
20177 | without warnings (and the initialization is suppressed): | |
20178 | ||
20179 | @example | |
20180 | with System; | |
20181 | package G is | |
20182 | type R is record | |
20183 | M : Integer := 0; | |
20184 | end record; | |
20185 | ||
20186 | Ext : R; | |
20187 | for Ext'Address use System'To_Address (16#1234_1234#); | |
20188 | pragma Import (Ada, Ext); | |
20189 | end G; | |
20190 | @end example | |
20191 | ||
20192 | A final issue with address clauses involves their use for overlaying | |
20193 | variables, as in the following example: | |
20194 | ||
20195 | @geindex Overlaying of objects | |
20196 | ||
20197 | @example | |
20198 | A : Integer; | |
20199 | B : Integer; | |
20200 | for B'Address use A'Address; | |
20201 | @end example | |
20202 | ||
20203 | or alternatively, using the form recommended by the RM: | |
20204 | ||
20205 | @example | |
20206 | A : Integer; | |
20207 | Addr : constant Address := A'Address; | |
20208 | B : Integer; | |
20209 | for B'Address use Addr; | |
20210 | @end example | |
20211 | ||
20212 | In both of these cases, @code{A} and @code{B} become aliased to one another | |
20213 | via the address clause. This use of address clauses to overlay | |
20214 | variables, achieving an effect similar to unchecked conversion | |
20215 | was erroneous in Ada 83, but in Ada 95 and Ada 2005 | |
20216 | the effect is implementation defined. Furthermore, the | |
20217 | Ada RM specifically recommends that in a situation | |
20218 | like this, @code{B} should be subject to the following | |
20219 | implementation advice (RM 13.3(19)): | |
20220 | ||
20221 | @quotation | |
20222 | ||
20223 | “19 If the Address of an object is specified, or it is imported | |
20224 | or exported, then the implementation should not perform | |
20225 | optimizations based on assumptions of no aliases.” | |
20226 | @end quotation | |
20227 | ||
20228 | GNAT follows this recommendation, and goes further by also applying | |
20229 | this recommendation to the overlaid variable (@code{A} in the above example) | |
20230 | in this case. This means that the overlay works “as expected”, in that | |
20231 | a modification to one of the variables will affect the value of the other. | |
20232 | ||
20233 | More generally, GNAT interprets this recommendation conservatively for | |
20234 | address clauses: in the cases other than overlays, it considers that the | |
20235 | object is effectively subject to pragma @code{Volatile} and implements the | |
20236 | associated semantics. | |
20237 | ||
20238 | Note that when address clause overlays are used in this way, there is an | |
20239 | issue of unintentional initialization, as shown by this example: | |
20240 | ||
20241 | @example | |
20242 | package Overwrite_Record is | |
20243 | type R is record | |
20244 | A : Character := 'C'; | |
20245 | B : Character := 'A'; | |
20246 | end record; | |
20247 | X : Short_Integer := 3; | |
20248 | Y : R; | |
20249 | for Y'Address use X'Address; | |
20250 | | | |
20251 | >>> warning: default initialization of "Y" may | |
20252 | modify "X", use pragma Import for "Y" to | |
20253 | suppress initialization (RM B.1(24)) | |
20254 | ||
20255 | end Overwrite_Record; | |
20256 | @end example | |
20257 | ||
20258 | Here the default initialization of @code{Y} will clobber the value | |
20259 | of @code{X}, which justifies the warning. The warning notes that | |
20260 | this effect can be eliminated by adding a @code{pragma Import} | |
20261 | which suppresses the initialization: | |
20262 | ||
20263 | @example | |
20264 | package Overwrite_Record is | |
20265 | type R is record | |
20266 | A : Character := 'C'; | |
20267 | B : Character := 'A'; | |
20268 | end record; | |
20269 | X : Short_Integer := 3; | |
20270 | Y : R; | |
20271 | for Y'Address use X'Address; | |
20272 | pragma Import (Ada, Y); | |
20273 | end Overwrite_Record; | |
20274 | @end example | |
20275 | ||
20276 | Note that the use of @code{pragma Initialize_Scalars} may cause variables to | |
20277 | be initialized when they would not otherwise have been in the absence | |
20278 | of the use of this pragma. This may cause an overlay to have this | |
20279 | unintended clobbering effect. The compiler avoids this for scalar | |
20280 | types, but not for composite objects (where in general the effect | |
20281 | of @code{Initialize_Scalars} is part of the initialization routine | |
20282 | for the composite object): | |
20283 | ||
20284 | @example | |
20285 | pragma Initialize_Scalars; | |
20286 | with Ada.Text_IO; use Ada.Text_IO; | |
20287 | procedure Overwrite_Array is | |
20288 | type Arr is array (1 .. 5) of Integer; | |
20289 | X : Arr := (others => 1); | |
20290 | A : Arr; | |
20291 | for A'Address use X'Address; | |
20292 | | | |
20293 | >>> warning: default initialization of "A" may | |
20294 | modify "X", use pragma Import for "A" to | |
20295 | suppress initialization (RM B.1(24)) | |
20296 | ||
20297 | begin | |
20298 | if X /= Arr'(others => 1) then | |
20299 | Put_Line ("X was clobbered"); | |
20300 | else | |
20301 | Put_Line ("X was not clobbered"); | |
20302 | end if; | |
20303 | end Overwrite_Array; | |
20304 | @end example | |
20305 | ||
20306 | The above program generates the warning as shown, and at execution | |
20307 | time, prints @code{X was clobbered}. If the @code{pragma Import} is | |
20308 | added as suggested: | |
20309 | ||
20310 | @example | |
20311 | pragma Initialize_Scalars; | |
20312 | with Ada.Text_IO; use Ada.Text_IO; | |
20313 | procedure Overwrite_Array is | |
20314 | type Arr is array (1 .. 5) of Integer; | |
20315 | X : Arr := (others => 1); | |
20316 | A : Arr; | |
20317 | for A'Address use X'Address; | |
20318 | pragma Import (Ada, A); | |
20319 | begin | |
20320 | if X /= Arr'(others => 1) then | |
20321 | Put_Line ("X was clobbered"); | |
20322 | else | |
20323 | Put_Line ("X was not clobbered"); | |
20324 | end if; | |
20325 | end Overwrite_Array; | |
20326 | @end example | |
20327 | ||
20328 | then the program compiles without the warning and when run will generate | |
20329 | the output @code{X was not clobbered}. | |
20330 | ||
20331 | @node Use of Address Clauses for Memory-Mapped I/O,Effect of Convention on Representation,Address Clauses,Representation Clauses and Pragmas | |
9daee425 | 20332 | @anchor{gnat_rm/representation_clauses_and_pragmas id17}@anchor{2a3}@anchor{gnat_rm/representation_clauses_and_pragmas use-of-address-clauses-for-memory-mapped-i-o}@anchor{2a4} |
64d5610f ML |
20333 | @section Use of Address Clauses for Memory-Mapped I/O |
20334 | ||
20335 | ||
20336 | @geindex Memory-mapped I/O | |
20337 | ||
20338 | A common pattern is to use an address clause to map an atomic variable to | |
20339 | a location in memory that corresponds to a memory-mapped I/O operation or | |
20340 | operations, for example: | |
20341 | ||
20342 | @example | |
20343 | type Mem_Word is record | |
20344 | A,B,C,D : Byte; | |
20345 | end record; | |
20346 | pragma Atomic (Mem_Word); | |
20347 | for Mem_Word_Size use 32; | |
20348 | ||
20349 | Mem : Mem_Word; | |
20350 | for Mem'Address use some-address; | |
20351 | ... | |
20352 | Temp := Mem; | |
20353 | Temp.A := 32; | |
20354 | Mem := Temp; | |
20355 | @end example | |
20356 | ||
20357 | For a full access (reference or modification) of the variable (Mem) in this | |
20358 | case, as in the above examples, GNAT guarantees that the entire atomic word | |
20359 | will be accessed, in accordance with the RM C.6(15) clause. | |
20360 | ||
20361 | A problem arises with a component access such as: | |
20362 | ||
20363 | @example | |
20364 | Mem.A := 32; | |
20365 | @end example | |
20366 | ||
20367 | Note that the component A is not declared as atomic. This means that it is | |
20368 | not clear what this assignment means. It could correspond to full word read | |
20369 | and write as given in the first example, or on architectures that supported | |
20370 | such an operation it might be a single byte store instruction. The RM does | |
20371 | not have anything to say in this situation, and GNAT does not make any | |
20372 | guarantee. The code generated may vary from target to target. GNAT will issue | |
20373 | a warning in such a case: | |
20374 | ||
20375 | @example | |
20376 | Mem.A := 32; | |
20377 | | | |
20378 | >>> warning: access to non-atomic component of atomic array, | |
20379 | may cause unexpected accesses to atomic object | |
20380 | @end example | |
20381 | ||
20382 | It is best to be explicit in this situation, by either declaring the | |
20383 | components to be atomic if you want the byte store, or explicitly writing | |
20384 | the full word access sequence if that is what the hardware requires. | |
20385 | Alternatively, if the full word access sequence is required, GNAT also | |
20386 | provides the pragma @code{Volatile_Full_Access} which can be used in lieu of | |
20387 | pragma @code{Atomic} and will give the additional guarantee. | |
20388 | ||
20389 | @node Effect of Convention on Representation,Conventions and Anonymous Access Types,Use of Address Clauses for Memory-Mapped I/O,Representation Clauses and Pragmas | |
9daee425 | 20390 | @anchor{gnat_rm/representation_clauses_and_pragmas effect-of-convention-on-representation}@anchor{2a5}@anchor{gnat_rm/representation_clauses_and_pragmas id18}@anchor{2a6} |
64d5610f ML |
20391 | @section Effect of Convention on Representation |
20392 | ||
20393 | ||
20394 | @geindex Convention | |
20395 | @geindex effect on representation | |
20396 | ||
20397 | Normally the specification of a foreign language convention for a type or | |
20398 | an object has no effect on the chosen representation. In particular, the | |
20399 | representation chosen for data in GNAT generally meets the standard system | |
20400 | conventions, and for example records are laid out in a manner that is | |
20401 | consistent with C. This means that specifying convention C (for example) | |
20402 | has no effect. | |
20403 | ||
20404 | There are four exceptions to this general rule: | |
20405 | ||
20406 | ||
20407 | @itemize * | |
20408 | ||
20409 | @item | |
1acce141 | 20410 | @emph{Convention Fortran and array subtypes}. |
64d5610f ML |
20411 | |
20412 | If pragma Convention Fortran is specified for an array subtype, then in | |
20413 | accordance with the implementation advice in section 3.6.2(11) of the | |
20414 | Ada Reference Manual, the array will be stored in a Fortran-compatible | |
20415 | column-major manner, instead of the normal default row-major order. | |
20416 | ||
20417 | @item | |
1acce141 | 20418 | @emph{Convention C and enumeration types} |
64d5610f ML |
20419 | |
20420 | GNAT normally stores enumeration types in 8, 16, or 32 bits as required | |
20421 | to accommodate all values of the type. For example, for the enumeration | |
20422 | type declared by: | |
20423 | ||
20424 | @example | |
20425 | type Color is (Red, Green, Blue); | |
20426 | @end example | |
20427 | ||
20428 | 8 bits is sufficient to store all values of the type, so by default, objects | |
20429 | of type @code{Color} will be represented using 8 bits. However, normal C | |
20430 | convention is to use 32 bits for all enum values in C, since enum values | |
20431 | are essentially of type int. If pragma @code{Convention C} is specified for an | |
20432 | Ada enumeration type, then the size is modified as necessary (usually to | |
20433 | 32 bits) to be consistent with the C convention for enum values. | |
20434 | ||
20435 | Note that this treatment applies only to types. If Convention C is given for | |
20436 | an enumeration object, where the enumeration type is not Convention C, then | |
20437 | Object_Size bits are allocated. For example, for a normal enumeration type, | |
20438 | with less than 256 elements, only 8 bits will be allocated for the object. | |
20439 | Since this may be a surprise in terms of what C expects, GNAT will issue a | |
20440 | warning in this situation. The warning can be suppressed by giving an explicit | |
20441 | size clause specifying the desired size. | |
20442 | ||
20443 | @item | |
1acce141 | 20444 | @emph{Convention C/Fortran and Boolean types} |
64d5610f ML |
20445 | |
20446 | In C, the usual convention for boolean values, that is values used for | |
20447 | conditions, is that zero represents false, and nonzero values represent | |
20448 | true. In Ada, the normal convention is that two specific values, typically | |
20449 | 0/1, are used to represent false/true respectively. | |
20450 | ||
20451 | Fortran has a similar convention for @code{LOGICAL} values (any nonzero | |
20452 | value represents true). | |
20453 | ||
20454 | To accommodate the Fortran and C conventions, if a pragma Convention specifies | |
20455 | C or Fortran convention for a derived Boolean, as in the following example: | |
20456 | ||
20457 | @example | |
20458 | type C_Switch is new Boolean; | |
20459 | pragma Convention (C, C_Switch); | |
20460 | @end example | |
20461 | ||
20462 | then the GNAT generated code will treat any nonzero value as true. For truth | |
20463 | values generated by GNAT, the conventional value 1 will be used for True, but | |
20464 | when one of these values is read, any nonzero value is treated as True. | |
20465 | @end itemize | |
20466 | ||
20467 | @node Conventions and Anonymous Access Types,Determining the Representations chosen by GNAT,Effect of Convention on Representation,Representation Clauses and Pragmas | |
9daee425 | 20468 | @anchor{gnat_rm/representation_clauses_and_pragmas conventions-and-anonymous-access-types}@anchor{2a7}@anchor{gnat_rm/representation_clauses_and_pragmas id19}@anchor{2a8} |
64d5610f ML |
20469 | @section Conventions and Anonymous Access Types |
20470 | ||
20471 | ||
20472 | @geindex Anonymous access types | |
20473 | ||
20474 | @geindex Convention for anonymous access types | |
20475 | ||
20476 | The RM is not entirely clear on convention handling in a number of cases, | |
20477 | and in particular, it is not clear on the convention to be given to | |
20478 | anonymous access types in general, and in particular what is to be | |
20479 | done for the case of anonymous access-to-subprogram. | |
20480 | ||
20481 | In GNAT, we decide that if an explicit Convention is applied | |
20482 | to an object or component, and its type is such an anonymous type, | |
20483 | then the convention will apply to this anonymous type as well. This | |
20484 | seems to make sense since it is anomolous in any case to have a | |
20485 | different convention for an object and its type, and there is clearly | |
20486 | no way to explicitly specify a convention for an anonymous type, since | |
20487 | it doesn’t have a name to specify! | |
20488 | ||
20489 | Furthermore, we decide that if a convention is applied to a record type, | |
20490 | then this convention is inherited by any of its components that are of an | |
20491 | anonymous access type which do not have an explicitly specified convention. | |
20492 | ||
20493 | The following program shows these conventions in action: | |
20494 | ||
20495 | @example | |
20496 | package ConvComp is | |
20497 | type Foo is range 1 .. 10; | |
20498 | type T1 is record | |
20499 | A : access function (X : Foo) return Integer; | |
20500 | B : Integer; | |
20501 | end record; | |
20502 | pragma Convention (C, T1); | |
20503 | ||
20504 | type T2 is record | |
20505 | A : access function (X : Foo) return Integer; | |
20506 | pragma Convention (C, A); | |
20507 | B : Integer; | |
20508 | end record; | |
20509 | pragma Convention (COBOL, T2); | |
20510 | ||
20511 | type T3 is record | |
20512 | A : access function (X : Foo) return Integer; | |
20513 | pragma Convention (COBOL, A); | |
20514 | B : Integer; | |
20515 | end record; | |
20516 | pragma Convention (C, T3); | |
20517 | ||
20518 | type T4 is record | |
20519 | A : access function (X : Foo) return Integer; | |
20520 | B : Integer; | |
20521 | end record; | |
20522 | pragma Convention (COBOL, T4); | |
20523 | ||
20524 | function F (X : Foo) return Integer; | |
20525 | pragma Convention (C, F); | |
20526 | ||
20527 | function F (X : Foo) return Integer is (13); | |
20528 | ||
20529 | TV1 : T1 := (F'Access, 12); -- OK | |
20530 | TV2 : T2 := (F'Access, 13); -- OK | |
20531 | ||
20532 | TV3 : T3 := (F'Access, 13); -- ERROR | |
20533 | | | |
20534 | >>> subprogram "F" has wrong convention | |
20535 | >>> does not match access to subprogram declared at line 17 | |
20536 | 38. TV4 : T4 := (F'Access, 13); -- ERROR | |
20537 | | | |
20538 | >>> subprogram "F" has wrong convention | |
20539 | >>> does not match access to subprogram declared at line 24 | |
20540 | 39. end ConvComp; | |
20541 | @end example | |
20542 | ||
20543 | @node Determining the Representations chosen by GNAT,,Conventions and Anonymous Access Types,Representation Clauses and Pragmas | |
9daee425 | 20544 | @anchor{gnat_rm/representation_clauses_and_pragmas determining-the-representations-chosen-by-gnat}@anchor{2a9}@anchor{gnat_rm/representation_clauses_and_pragmas id20}@anchor{2aa} |
64d5610f ML |
20545 | @section Determining the Representations chosen by GNAT |
20546 | ||
20547 | ||
20548 | @geindex Representation | |
20549 | @geindex determination of | |
20550 | ||
20551 | @geindex -gnatR (gcc) | |
20552 | ||
20553 | Although the descriptions in this section are intended to be complete, it is | |
20554 | often easier to simply experiment to see what GNAT accepts and what the | |
20555 | effect is on the layout of types and objects. | |
20556 | ||
20557 | As required by the Ada RM, if a representation clause is not accepted, then | |
20558 | it must be rejected as illegal by the compiler. However, when a | |
20559 | representation clause or pragma is accepted, there can still be questions | |
20560 | of what the compiler actually does. For example, if a partial record | |
20561 | representation clause specifies the location of some components and not | |
20562 | others, then where are the non-specified components placed? Or if pragma | |
20563 | @code{Pack} is used on a record, then exactly where are the resulting | |
20564 | fields placed? The section on pragma @code{Pack} in this chapter can be | |
20565 | used to answer the second question, but it is often easier to just see | |
20566 | what the compiler does. | |
20567 | ||
1acce141 | 20568 | For this purpose, GNAT provides the option @emph{-gnatR}. If you compile |
64d5610f ML |
20569 | with this option, then the compiler will output information on the actual |
20570 | representations chosen, in a format similar to source representation | |
20571 | clauses. For example, if we compile the package: | |
20572 | ||
20573 | @example | |
20574 | package q is | |
20575 | type r (x : boolean) is tagged record | |
20576 | case x is | |
20577 | when True => S : String (1 .. 100); | |
20578 | when False => null; | |
20579 | end case; | |
20580 | end record; | |
20581 | ||
20582 | type r2 is new r (false) with record | |
20583 | y2 : integer; | |
20584 | end record; | |
20585 | ||
20586 | for r2 use record | |
20587 | y2 at 16 range 0 .. 31; | |
20588 | end record; | |
20589 | ||
20590 | type x is record | |
20591 | y : character; | |
20592 | end record; | |
20593 | ||
20594 | type x1 is array (1 .. 10) of x; | |
20595 | for x1'component_size use 11; | |
20596 | ||
20597 | type ia is access integer; | |
20598 | ||
20599 | type Rb1 is array (1 .. 13) of Boolean; | |
20600 | pragma Pack (rb1); | |
20601 | ||
20602 | type Rb2 is array (1 .. 65) of Boolean; | |
20603 | pragma Pack (rb2); | |
20604 | ||
20605 | type x2 is record | |
20606 | l1 : Boolean; | |
20607 | l2 : Duration; | |
20608 | l3 : Float; | |
20609 | l4 : Boolean; | |
20610 | l5 : Rb1; | |
20611 | l6 : Rb2; | |
20612 | end record; | |
20613 | pragma Pack (x2); | |
20614 | end q; | |
20615 | @end example | |
20616 | ||
1acce141 | 20617 | using the switch @emph{-gnatR} we obtain the following output: |
64d5610f ML |
20618 | |
20619 | @example | |
20620 | Representation information for unit q | |
20621 | ------------------------------------- | |
20622 | ||
20623 | for r'Size use ??; | |
20624 | for r'Alignment use 4; | |
20625 | for r use record | |
20626 | x at 4 range 0 .. 7; | |
20627 | _tag at 0 range 0 .. 31; | |
20628 | s at 5 range 0 .. 799; | |
20629 | end record; | |
20630 | ||
20631 | for r2'Size use 160; | |
20632 | for r2'Alignment use 4; | |
20633 | for r2 use record | |
20634 | x at 4 range 0 .. 7; | |
20635 | _tag at 0 range 0 .. 31; | |
20636 | _parent at 0 range 0 .. 63; | |
20637 | y2 at 16 range 0 .. 31; | |
20638 | end record; | |
20639 | ||
20640 | for x'Size use 8; | |
20641 | for x'Alignment use 1; | |
20642 | for x use record | |
20643 | y at 0 range 0 .. 7; | |
20644 | end record; | |
20645 | ||
20646 | for x1'Size use 112; | |
20647 | for x1'Alignment use 1; | |
20648 | for x1'Component_Size use 11; | |
20649 | ||
20650 | for rb1'Size use 13; | |
20651 | for rb1'Alignment use 2; | |
20652 | for rb1'Component_Size use 1; | |
20653 | ||
20654 | for rb2'Size use 72; | |
20655 | for rb2'Alignment use 1; | |
20656 | for rb2'Component_Size use 1; | |
20657 | ||
20658 | for x2'Size use 224; | |
20659 | for x2'Alignment use 4; | |
20660 | for x2 use record | |
20661 | l1 at 0 range 0 .. 0; | |
20662 | l2 at 0 range 1 .. 64; | |
20663 | l3 at 12 range 0 .. 31; | |
20664 | l4 at 16 range 0 .. 0; | |
20665 | l5 at 16 range 1 .. 13; | |
20666 | l6 at 18 range 0 .. 71; | |
20667 | end record; | |
20668 | @end example | |
20669 | ||
20670 | The Size values are actually the Object_Size, i.e., the default size that | |
20671 | will be allocated for objects of the type. | |
20672 | The @code{??} size for type r indicates that we have a variant record, and the | |
20673 | actual size of objects will depend on the discriminant value. | |
20674 | ||
20675 | The Alignment values show the actual alignment chosen by the compiler | |
20676 | for each record or array type. | |
20677 | ||
20678 | The record representation clause for type r shows where all fields | |
20679 | are placed, including the compiler generated tag field (whose location | |
20680 | cannot be controlled by the programmer). | |
20681 | ||
20682 | The record representation clause for the type extension r2 shows all the | |
20683 | fields present, including the parent field, which is a copy of the fields | |
20684 | of the parent type of r2, i.e., r1. | |
20685 | ||
20686 | The component size and size clauses for types rb1 and rb2 show | |
20687 | the exact effect of pragma @code{Pack} on these arrays, and the record | |
20688 | representation clause for type x2 shows how pragma @cite{Pack} affects | |
20689 | this record type. | |
20690 | ||
20691 | In some cases, it may be useful to cut and paste the representation clauses | |
20692 | generated by the compiler into the original source to fix and guarantee | |
20693 | the actual representation to be used. | |
20694 | ||
20695 | @node Standard Library Routines,The Implementation of Standard I/O,Representation Clauses and Pragmas,Top | |
9daee425 | 20696 | @anchor{gnat_rm/standard_library_routines doc}@anchor{2ab}@anchor{gnat_rm/standard_library_routines id1}@anchor{2ac}@anchor{gnat_rm/standard_library_routines standard-library-routines}@anchor{e} |
64d5610f ML |
20697 | @chapter Standard Library Routines |
20698 | ||
20699 | ||
20700 | The Ada Reference Manual contains in Annex A a full description of an | |
20701 | extensive set of standard library routines that can be used in any Ada | |
20702 | program, and which must be provided by all Ada compilers. They are | |
20703 | analogous to the standard C library used by C programs. | |
20704 | ||
20705 | GNAT implements all of the facilities described in annex A, and for most | |
20706 | purposes the description in the Ada Reference Manual, or appropriate Ada | |
20707 | text book, will be sufficient for making use of these facilities. | |
20708 | ||
20709 | In the case of the input-output facilities, | |
20710 | @ref{f,,The Implementation of Standard I/O}, | |
20711 | gives details on exactly how GNAT interfaces to the | |
20712 | file system. For the remaining packages, the Ada Reference Manual | |
20713 | should be sufficient. The following is a list of the packages included, | |
20714 | together with a brief description of the functionality that is provided. | |
20715 | ||
20716 | For completeness, references are included to other predefined library | |
20717 | routines defined in other sections of the Ada Reference Manual (these are | |
20718 | cross-indexed from Annex A). For further details see the relevant | |
20719 | package declarations in the run-time library. In particular, a few units | |
20720 | are not implemented, as marked by the presence of pragma Unimplemented_Unit, | |
20721 | and in this case the package declaration contains comments explaining why | |
20722 | the unit is not implemented. | |
20723 | ||
20724 | ||
20725 | @table @asis | |
20726 | ||
1acce141 | 20727 | @item @code{Ada} @emph{(A.2)} |
64d5610f ML |
20728 | |
20729 | This is a parent package for all the standard library packages. It is | |
20730 | usually included implicitly in your program, and itself contains no | |
20731 | useful data or routines. | |
20732 | ||
1acce141 | 20733 | @item @code{Ada.Assertions} @emph{(11.4.2)} |
64d5610f ML |
20734 | |
20735 | @code{Assertions} provides the @code{Assert} subprograms, and also | |
20736 | the declaration of the @code{Assertion_Error} exception. | |
20737 | ||
1acce141 | 20738 | @item @code{Ada.Asynchronous_Task_Control} @emph{(D.11)} |
64d5610f ML |
20739 | |
20740 | @code{Asynchronous_Task_Control} provides low level facilities for task | |
20741 | synchronization. It is typically not implemented. See package spec for details. | |
20742 | ||
1acce141 | 20743 | @item @code{Ada.Calendar} @emph{(9.6)} |
64d5610f ML |
20744 | |
20745 | @code{Calendar} provides time of day access, and routines for | |
20746 | manipulating times and durations. | |
20747 | ||
1acce141 | 20748 | @item @code{Ada.Calendar.Arithmetic} @emph{(9.6.1)} |
64d5610f ML |
20749 | |
20750 | This package provides additional arithmetic | |
20751 | operations for @code{Calendar}. | |
20752 | ||
1acce141 | 20753 | @item @code{Ada.Calendar.Formatting} @emph{(9.6.1)} |
64d5610f ML |
20754 | |
20755 | This package provides formatting operations for @code{Calendar}. | |
20756 | ||
1acce141 | 20757 | @item @code{Ada.Calendar.Time_Zones} @emph{(9.6.1)} |
64d5610f ML |
20758 | |
20759 | This package provides additional @code{Calendar} facilities | |
20760 | for handling time zones. | |
20761 | ||
1acce141 | 20762 | @item @code{Ada.Characters} @emph{(A.3.1)} |
64d5610f ML |
20763 | |
20764 | This is a dummy parent package that contains no useful entities | |
20765 | ||
1acce141 | 20766 | @item @code{Ada.Characters.Conversions} @emph{(A.3.2)} |
64d5610f ML |
20767 | |
20768 | This package provides character conversion functions. | |
20769 | ||
1acce141 | 20770 | @item @code{Ada.Characters.Handling} @emph{(A.3.2)} |
64d5610f ML |
20771 | |
20772 | This package provides some basic character handling capabilities, | |
20773 | including classification functions for classes of characters (e.g., test | |
20774 | for letters, or digits). | |
20775 | ||
1acce141 | 20776 | @item @code{Ada.Characters.Latin_1} @emph{(A.3.3)} |
64d5610f ML |
20777 | |
20778 | This package includes a complete set of definitions of the characters | |
20779 | that appear in type CHARACTER. It is useful for writing programs that | |
20780 | will run in international environments. For example, if you want an | |
20781 | upper case E with an acute accent in a string, it is often better to use | |
20782 | the definition of @code{UC_E_Acute} in this package. Then your program | |
20783 | will print in an understandable manner even if your environment does not | |
20784 | support these extended characters. | |
20785 | ||
1acce141 | 20786 | @item @code{Ada.Command_Line} @emph{(A.15)} |
64d5610f ML |
20787 | |
20788 | This package provides access to the command line parameters and the name | |
20789 | of the current program (analogous to the use of @code{argc} and @code{argv} | |
20790 | in C), and also allows the exit status for the program to be set in a | |
20791 | system-independent manner. | |
20792 | ||
1acce141 | 20793 | @item @code{Ada.Complex_Text_IO} @emph{(G.1.3)} |
64d5610f ML |
20794 | |
20795 | This package provides text input and output of complex numbers. | |
20796 | ||
1acce141 | 20797 | @item @code{Ada.Containers} @emph{(A.18.1)} |
64d5610f ML |
20798 | |
20799 | A top level package providing a few basic definitions used by all the | |
20800 | following specific child packages that provide specific kinds of | |
20801 | containers. | |
20802 | @end table | |
20803 | ||
1acce141 | 20804 | @code{Ada.Containers.Bounded_Priority_Queues} @emph{(A.18.31)} |
64d5610f | 20805 | |
1acce141 | 20806 | @code{Ada.Containers.Bounded_Synchronized_Queues} @emph{(A.18.29)} |
64d5610f | 20807 | |
1acce141 | 20808 | @code{Ada.Containers.Doubly_Linked_Lists} @emph{(A.18.3)} |
64d5610f | 20809 | |
1acce141 | 20810 | @code{Ada.Containers.Generic_Array_Sort} @emph{(A.18.26)} |
64d5610f | 20811 | |
1acce141 | 20812 | @code{Ada.Containers.Generic_Constrained_Array_Sort} @emph{(A.18.26)} |
64d5610f | 20813 | |
1acce141 | 20814 | @code{Ada.Containers.Generic_Sort} @emph{(A.18.26)} |
64d5610f | 20815 | |
1acce141 | 20816 | @code{Ada.Containers.Hashed_Maps} @emph{(A.18.5)} |
64d5610f | 20817 | |
1acce141 | 20818 | @code{Ada.Containers.Hashed_Sets} @emph{(A.18.8)} |
64d5610f | 20819 | |
1acce141 | 20820 | @code{Ada.Containers.Indefinite_Doubly_Linked_Lists} @emph{(A.18.12)} |
64d5610f | 20821 | |
1acce141 | 20822 | @code{Ada.Containers.Indefinite_Hashed_Maps} @emph{(A.18.13)} |
64d5610f | 20823 | |
1acce141 | 20824 | @code{Ada.Containers.Indefinite_Hashed_Sets} @emph{(A.18.15)} |
64d5610f | 20825 | |
1acce141 | 20826 | @code{Ada.Containers.Indefinite_Holders} @emph{(A.18.18)} |
64d5610f | 20827 | |
1acce141 | 20828 | @code{Ada.Containers.Indefinite_Multiway_Trees} @emph{(A.18.17)} |
64d5610f | 20829 | |
1acce141 | 20830 | @code{Ada.Containers.Indefinite_Ordered_Maps} @emph{(A.18.14)} |
64d5610f | 20831 | |
1acce141 | 20832 | @code{Ada.Containers.Indefinite_Ordered_Sets} @emph{(A.18.16)} |
64d5610f | 20833 | |
1acce141 | 20834 | @code{Ada.Containers.Indefinite_Vectors} @emph{(A.18.11)} |
64d5610f | 20835 | |
1acce141 | 20836 | @code{Ada.Containers.Multiway_Trees} @emph{(A.18.10)} |
64d5610f | 20837 | |
1acce141 | 20838 | @code{Ada.Containers.Ordered_Maps} @emph{(A.18.6)} |
64d5610f | 20839 | |
1acce141 | 20840 | @code{Ada.Containers.Ordered_Sets} @emph{(A.18.9)} |
64d5610f | 20841 | |
1acce141 | 20842 | @code{Ada.Containers.Synchronized_Queue_Interfaces} @emph{(A.18.27)} |
64d5610f | 20843 | |
1acce141 | 20844 | @code{Ada.Containers.Unbounded_Priority_Queues} @emph{(A.18.30)} |
64d5610f | 20845 | |
1acce141 | 20846 | @code{Ada.Containers.Unbounded_Synchronized_Queues} @emph{(A.18.28)} |
64d5610f | 20847 | |
1acce141 | 20848 | @code{Ada.Containers.Vectors} @emph{(A.18.2)} |
64d5610f ML |
20849 | |
20850 | ||
20851 | @table @asis | |
20852 | ||
1acce141 | 20853 | @item @code{Ada.Directories} @emph{(A.16)} |
64d5610f ML |
20854 | |
20855 | This package provides operations on directories. | |
20856 | ||
1acce141 | 20857 | @item @code{Ada.Directories.Hierarchical_File_Names} @emph{(A.16.1)} |
64d5610f ML |
20858 | |
20859 | This package provides additional directory operations handling | |
20860 | hierarchical file names. | |
20861 | ||
1acce141 | 20862 | @item @code{Ada.Directories.Information} @emph{(A.16)} |
64d5610f ML |
20863 | |
20864 | This is an implementation defined package for additional directory | |
20865 | operations, which is not implemented in GNAT. | |
20866 | ||
1acce141 | 20867 | @item @code{Ada.Decimal} @emph{(F.2)} |
64d5610f ML |
20868 | |
20869 | This package provides constants describing the range of decimal numbers | |
20870 | implemented, and also a decimal divide routine (analogous to the COBOL | |
20871 | verb DIVIDE … GIVING … REMAINDER …) | |
20872 | ||
1acce141 | 20873 | @item @code{Ada.Direct_IO} @emph{(A.8.4)} |
64d5610f ML |
20874 | |
20875 | This package provides input-output using a model of a set of records of | |
20876 | fixed-length, containing an arbitrary definite Ada type, indexed by an | |
20877 | integer record number. | |
20878 | ||
1acce141 | 20879 | @item @code{Ada.Dispatching} @emph{(D.2.1)} |
64d5610f ML |
20880 | |
20881 | A parent package containing definitions for task dispatching operations. | |
20882 | ||
1acce141 | 20883 | @item @code{Ada.Dispatching.EDF} @emph{(D.2.6)} |
64d5610f ML |
20884 | |
20885 | Not implemented in GNAT. | |
20886 | ||
1acce141 | 20887 | @item @code{Ada.Dispatching.Non_Preemptive} @emph{(D.2.4)} |
64d5610f ML |
20888 | |
20889 | Not implemented in GNAT. | |
20890 | ||
1acce141 | 20891 | @item @code{Ada.Dispatching.Round_Robin} @emph{(D.2.5)} |
64d5610f ML |
20892 | |
20893 | Not implemented in GNAT. | |
20894 | ||
1acce141 | 20895 | @item @code{Ada.Dynamic_Priorities} @emph{(D.5)} |
64d5610f ML |
20896 | |
20897 | This package allows the priorities of a task to be adjusted dynamically | |
20898 | as the task is running. | |
20899 | ||
1acce141 | 20900 | @item @code{Ada.Environment_Variables} @emph{(A.17)} |
64d5610f ML |
20901 | |
20902 | This package provides facilities for accessing environment variables. | |
20903 | ||
1acce141 | 20904 | @item @code{Ada.Exceptions} @emph{(11.4.1)} |
64d5610f ML |
20905 | |
20906 | This package provides additional information on exceptions, and also | |
20907 | contains facilities for treating exceptions as data objects, and raising | |
20908 | exceptions with associated messages. | |
20909 | ||
1acce141 | 20910 | @item @code{Ada.Execution_Time} @emph{(D.14)} |
64d5610f ML |
20911 | |
20912 | This package provides CPU clock functionalities. It is not implemented on | |
20913 | all targets (see package spec for details). | |
20914 | ||
1acce141 | 20915 | @item @code{Ada.Execution_Time.Group_Budgets} @emph{(D.14.2)} |
64d5610f ML |
20916 | |
20917 | Not implemented in GNAT. | |
20918 | ||
1acce141 | 20919 | @item @code{Ada.Execution_Time.Timers} @emph{(D.14.1)’} |
64d5610f ML |
20920 | |
20921 | Not implemented in GNAT. | |
20922 | ||
1acce141 | 20923 | @item @code{Ada.Finalization} @emph{(7.6)} |
64d5610f ML |
20924 | |
20925 | This package contains the declarations and subprograms to support the | |
20926 | use of controlled types, providing for automatic initialization and | |
20927 | finalization (analogous to the constructors and destructors of C++). | |
20928 | ||
1acce141 | 20929 | @item @code{Ada.Float_Text_IO} @emph{(A.10.9)} |
64d5610f ML |
20930 | |
20931 | A library level instantiation of Text_IO.Float_IO for type Float. | |
20932 | ||
1acce141 | 20933 | @item @code{Ada.Float_Wide_Text_IO} @emph{(A.10.9)} |
64d5610f ML |
20934 | |
20935 | A library level instantiation of Wide_Text_IO.Float_IO for type Float. | |
20936 | ||
1acce141 | 20937 | @item @code{Ada.Float_Wide_Wide_Text_IO} @emph{(A.10.9)} |
64d5610f ML |
20938 | |
20939 | A library level instantiation of Wide_Wide_Text_IO.Float_IO for type Float. | |
20940 | ||
1acce141 | 20941 | @item @code{Ada.Integer_Text_IO} @emph{(A.10.9)} |
64d5610f ML |
20942 | |
20943 | A library level instantiation of Text_IO.Integer_IO for type Integer. | |
20944 | ||
1acce141 | 20945 | @item @code{Ada.Integer_Wide_Text_IO} @emph{(A.10.9)} |
64d5610f ML |
20946 | |
20947 | A library level instantiation of Wide_Text_IO.Integer_IO for type Integer. | |
20948 | ||
1acce141 | 20949 | @item @code{Ada.Integer_Wide_Wide_Text_IO} @emph{(A.10.9)} |
64d5610f ML |
20950 | |
20951 | A library level instantiation of Wide_Wide_Text_IO.Integer_IO for type Integer. | |
20952 | ||
1acce141 | 20953 | @item @code{Ada.Interrupts} @emph{(C.3.2)} |
64d5610f ML |
20954 | |
20955 | This package provides facilities for interfacing to interrupts, which | |
20956 | includes the set of signals or conditions that can be raised and | |
20957 | recognized as interrupts. | |
20958 | ||
1acce141 | 20959 | @item @code{Ada.Interrupts.Names} @emph{(C.3.2)} |
64d5610f ML |
20960 | |
20961 | This package provides the set of interrupt names (actually signal | |
20962 | or condition names) that can be handled by GNAT. | |
20963 | ||
1acce141 | 20964 | @item @code{Ada.IO_Exceptions} @emph{(A.13)} |
64d5610f ML |
20965 | |
20966 | This package defines the set of exceptions that can be raised by use of | |
20967 | the standard IO packages. | |
20968 | ||
1acce141 | 20969 | @item @code{Ada.Iterator_Interfaces} @emph{(5.5.1)} |
64d5610f ML |
20970 | |
20971 | This package provides a generic interface to generalized iterators. | |
20972 | ||
1acce141 | 20973 | @item @code{Ada.Locales} @emph{(A.19)} |
64d5610f ML |
20974 | |
20975 | This package provides declarations providing information (Language | |
20976 | and Country) about the current locale. | |
20977 | ||
20978 | @item @code{Ada.Numerics} | |
20979 | ||
20980 | This package contains some standard constants and exceptions used | |
20981 | throughout the numerics packages. Note that the constants pi and e are | |
20982 | defined here, and it is better to use these definitions than rolling | |
20983 | your own. | |
20984 | ||
1acce141 | 20985 | @item @code{Ada.Numerics.Complex_Arrays} @emph{(G.3.2)} |
64d5610f ML |
20986 | |
20987 | Provides operations on arrays of complex numbers. | |
20988 | ||
20989 | @item @code{Ada.Numerics.Complex_Elementary_Functions} | |
20990 | ||
20991 | Provides the implementation of standard elementary functions (such as | |
20992 | log and trigonometric functions) operating on complex numbers using the | |
20993 | standard @code{Float} and the @code{Complex} and @code{Imaginary} types | |
20994 | created by the package @code{Numerics.Complex_Types}. | |
20995 | ||
20996 | @item @code{Ada.Numerics.Complex_Types} | |
20997 | ||
20998 | This is a predefined instantiation of | |
20999 | @code{Numerics.Generic_Complex_Types} using @code{Standard.Float} to | |
21000 | build the type @code{Complex} and @code{Imaginary}. | |
21001 | ||
21002 | @item @code{Ada.Numerics.Discrete_Random} | |
21003 | ||
21004 | This generic package provides a random number generator suitable for generating | |
21005 | uniformly distributed values of a specified discrete subtype. | |
21006 | ||
21007 | @item @code{Ada.Numerics.Float_Random} | |
21008 | ||
21009 | This package provides a random number generator suitable for generating | |
21010 | uniformly distributed floating point values in the unit interval. | |
21011 | ||
21012 | @item @code{Ada.Numerics.Generic_Complex_Elementary_Functions} | |
21013 | ||
21014 | This is a generic version of the package that provides the | |
21015 | implementation of standard elementary functions (such as log and | |
21016 | trigonometric functions) for an arbitrary complex type. | |
21017 | ||
21018 | The following predefined instantiations of this package are provided: | |
21019 | ||
21020 | ||
21021 | @itemize * | |
21022 | ||
21023 | @item | |
21024 | @code{Short_Float} | |
21025 | ||
21026 | @code{Ada.Numerics.Short_Complex_Elementary_Functions} | |
21027 | ||
21028 | @item | |
21029 | @code{Float} | |
21030 | ||
21031 | @code{Ada.Numerics.Complex_Elementary_Functions} | |
21032 | ||
21033 | @item | |
21034 | @code{Long_Float} | |
21035 | ||
21036 | @code{Ada.Numerics.Long_Complex_Elementary_Functions} | |
21037 | @end itemize | |
21038 | ||
21039 | @item @code{Ada.Numerics.Generic_Complex_Types} | |
21040 | ||
21041 | This is a generic package that allows the creation of complex types, | |
21042 | with associated complex arithmetic operations. | |
21043 | ||
21044 | The following predefined instantiations of this package exist | |
21045 | ||
21046 | ||
21047 | @itemize * | |
21048 | ||
21049 | @item | |
21050 | @code{Short_Float} | |
21051 | ||
21052 | @code{Ada.Numerics.Short_Complex_Complex_Types} | |
21053 | ||
21054 | @item | |
21055 | @code{Float} | |
21056 | ||
21057 | @code{Ada.Numerics.Complex_Complex_Types} | |
21058 | ||
21059 | @item | |
21060 | @code{Long_Float} | |
21061 | ||
21062 | @code{Ada.Numerics.Long_Complex_Complex_Types} | |
21063 | @end itemize | |
21064 | ||
21065 | @item @code{Ada.Numerics.Generic_Elementary_Functions} | |
21066 | ||
21067 | This is a generic package that provides the implementation of standard | |
21068 | elementary functions (such as log an trigonometric functions) for an | |
21069 | arbitrary float type. | |
21070 | ||
21071 | The following predefined instantiations of this package exist | |
21072 | ||
21073 | ||
21074 | @itemize * | |
21075 | ||
21076 | @item | |
21077 | @code{Short_Float} | |
21078 | ||
21079 | @code{Ada.Numerics.Short_Elementary_Functions} | |
21080 | ||
21081 | @item | |
21082 | @code{Float} | |
21083 | ||
21084 | @code{Ada.Numerics.Elementary_Functions} | |
21085 | ||
21086 | @item | |
21087 | @code{Long_Float} | |
21088 | ||
21089 | @code{Ada.Numerics.Long_Elementary_Functions} | |
21090 | @end itemize | |
21091 | ||
1acce141 | 21092 | @item @code{Ada.Numerics.Generic_Real_Arrays} @emph{(G.3.1)} |
64d5610f ML |
21093 | |
21094 | Generic operations on arrays of reals | |
21095 | ||
1acce141 | 21096 | @item @code{Ada.Numerics.Real_Arrays} @emph{(G.3.1)} |
64d5610f ML |
21097 | |
21098 | Preinstantiation of Ada.Numerics.Generic_Real_Arrays (Float). | |
21099 | ||
1acce141 | 21100 | @item @code{Ada.Real_Time} @emph{(D.8)} |
64d5610f ML |
21101 | |
21102 | This package provides facilities similar to those of @code{Calendar}, but | |
21103 | operating with a finer clock suitable for real time control. Note that | |
21104 | annex D requires that there be no backward clock jumps, and GNAT generally | |
21105 | guarantees this behavior, but of course if the external clock on which | |
21106 | the GNAT runtime depends is deliberately reset by some external event, | |
21107 | then such a backward jump may occur. | |
21108 | ||
1acce141 | 21109 | @item @code{Ada.Real_Time.Timing_Events} @emph{(D.15)} |
64d5610f ML |
21110 | |
21111 | Not implemented in GNAT. | |
21112 | ||
1acce141 | 21113 | @item @code{Ada.Sequential_IO} @emph{(A.8.1)} |
64d5610f ML |
21114 | |
21115 | This package provides input-output facilities for sequential files, | |
21116 | which can contain a sequence of values of a single type, which can be | |
21117 | any Ada type, including indefinite (unconstrained) types. | |
21118 | ||
1acce141 | 21119 | @item @code{Ada.Storage_IO} @emph{(A.9)} |
64d5610f ML |
21120 | |
21121 | This package provides a facility for mapping arbitrary Ada types to and | |
21122 | from a storage buffer. It is primarily intended for the creation of new | |
21123 | IO packages. | |
21124 | ||
1acce141 | 21125 | @item @code{Ada.Streams} @emph{(13.13.1)} |
64d5610f ML |
21126 | |
21127 | This is a generic package that provides the basic support for the | |
21128 | concept of streams as used by the stream attributes (@code{Input}, | |
21129 | @code{Output}, @code{Read} and @code{Write}). | |
21130 | ||
1acce141 | 21131 | @item @code{Ada.Streams.Stream_IO} @emph{(A.12.1)} |
64d5610f ML |
21132 | |
21133 | This package is a specialization of the type @code{Streams} defined in | |
21134 | package @code{Streams} together with a set of operations providing | |
21135 | Stream_IO capability. The Stream_IO model permits both random and | |
21136 | sequential access to a file which can contain an arbitrary set of values | |
21137 | of one or more Ada types. | |
21138 | ||
1acce141 | 21139 | @item @code{Ada.Strings} @emph{(A.4.1)} |
64d5610f ML |
21140 | |
21141 | This package provides some basic constants used by the string handling | |
21142 | packages. | |
21143 | ||
1acce141 | 21144 | @item @code{Ada.Strings.Bounded} @emph{(A.4.4)} |
64d5610f ML |
21145 | |
21146 | This package provides facilities for handling variable length | |
21147 | strings. The bounded model requires a maximum length. It is thus | |
21148 | somewhat more limited than the unbounded model, but avoids the use of | |
21149 | dynamic allocation or finalization. | |
21150 | ||
1acce141 | 21151 | @item @code{Ada.Strings.Bounded.Equal_Case_Insensitive} @emph{(A.4.10)} |
64d5610f ML |
21152 | |
21153 | Provides case-insensitive comparisons of bounded strings | |
21154 | ||
1acce141 | 21155 | @item @code{Ada.Strings.Bounded.Hash} @emph{(A.4.9)} |
64d5610f ML |
21156 | |
21157 | This package provides a generic hash function for bounded strings | |
21158 | ||
1acce141 | 21159 | @item @code{Ada.Strings.Bounded.Hash_Case_Insensitive} @emph{(A.4.9)} |
64d5610f ML |
21160 | |
21161 | This package provides a generic hash function for bounded strings that | |
21162 | converts the string to be hashed to lower case. | |
21163 | ||
1acce141 | 21164 | @item @code{Ada.Strings.Bounded.Less_Case_Insensitive} @emph{(A.4.10)} |
64d5610f ML |
21165 | |
21166 | This package provides a comparison function for bounded strings that works | |
21167 | in a case insensitive manner by converting to lower case before the comparison. | |
21168 | ||
1acce141 | 21169 | @item @code{Ada.Strings.Fixed} @emph{(A.4.3)} |
64d5610f ML |
21170 | |
21171 | This package provides facilities for handling fixed length strings. | |
21172 | ||
1acce141 | 21173 | @item @code{Ada.Strings.Fixed.Equal_Case_Insensitive} @emph{(A.4.10)} |
64d5610f ML |
21174 | |
21175 | This package provides an equality function for fixed strings that compares | |
21176 | the strings after converting both to lower case. | |
21177 | ||
1acce141 | 21178 | @item @code{Ada.Strings.Fixed.Hash_Case_Insensitive} @emph{(A.4.9)} |
64d5610f ML |
21179 | |
21180 | This package provides a case insensitive hash function for fixed strings that | |
21181 | converts the string to lower case before computing the hash. | |
21182 | ||
1acce141 | 21183 | @item @code{Ada.Strings.Fixed.Less_Case_Insensitive} @emph{(A.4.10)} |
64d5610f ML |
21184 | |
21185 | This package provides a comparison function for fixed strings that works | |
21186 | in a case insensitive manner by converting to lower case before the comparison. | |
21187 | ||
1acce141 | 21188 | @item @code{Ada.Strings.Hash} @emph{(A.4.9)} |
64d5610f ML |
21189 | |
21190 | This package provides a hash function for strings. | |
21191 | ||
1acce141 | 21192 | @item @code{Ada.Strings.Hash_Case_Insensitive} @emph{(A.4.9)} |
64d5610f ML |
21193 | |
21194 | This package provides a hash function for strings that is case insensitive. | |
21195 | The string is converted to lower case before computing the hash. | |
21196 | ||
1acce141 | 21197 | @item @code{Ada.Strings.Less_Case_Insensitive} @emph{(A.4.10)} |
64d5610f ML |
21198 | |
21199 | This package provides a comparison function for\strings that works | |
21200 | in a case insensitive manner by converting to lower case before the comparison. | |
21201 | ||
1acce141 | 21202 | @item @code{Ada.Strings.Maps} @emph{(A.4.2)} |
64d5610f ML |
21203 | |
21204 | This package provides facilities for handling character mappings and | |
21205 | arbitrarily defined subsets of characters. For instance it is useful in | |
21206 | defining specialized translation tables. | |
21207 | ||
1acce141 | 21208 | @item @code{Ada.Strings.Maps.Constants} @emph{(A.4.6)} |
64d5610f ML |
21209 | |
21210 | This package provides a standard set of predefined mappings and | |
21211 | predefined character sets. For example, the standard upper to lower case | |
21212 | conversion table is found in this package. Note that upper to lower case | |
21213 | conversion is non-trivial if you want to take the entire set of | |
21214 | characters, including extended characters like E with an acute accent, | |
21215 | into account. You should use the mappings in this package (rather than | |
21216 | adding 32 yourself) to do case mappings. | |
21217 | ||
1acce141 | 21218 | @item @code{Ada.Strings.Unbounded} @emph{(A.4.5)} |
64d5610f ML |
21219 | |
21220 | This package provides facilities for handling variable length | |
21221 | strings. The unbounded model allows arbitrary length strings, but | |
21222 | requires the use of dynamic allocation and finalization. | |
21223 | ||
1acce141 | 21224 | @item @code{Ada.Strings.Unbounded.Equal_Case_Insensitive} @emph{(A.4.10)} |
64d5610f ML |
21225 | |
21226 | Provides case-insensitive comparisons of unbounded strings | |
21227 | ||
1acce141 | 21228 | @item @code{Ada.Strings.Unbounded.Hash} @emph{(A.4.9)} |
64d5610f ML |
21229 | |
21230 | This package provides a generic hash function for unbounded strings | |
21231 | ||
1acce141 | 21232 | @item @code{Ada.Strings.Unbounded.Hash_Case_Insensitive} @emph{(A.4.9)} |
64d5610f ML |
21233 | |
21234 | This package provides a generic hash function for unbounded strings that | |
21235 | converts the string to be hashed to lower case. | |
21236 | ||
1acce141 | 21237 | @item @code{Ada.Strings.Unbounded.Less_Case_Insensitive} @emph{(A.4.10)} |
64d5610f ML |
21238 | |
21239 | This package provides a comparison function for unbounded strings that works | |
21240 | in a case insensitive manner by converting to lower case before the comparison. | |
21241 | ||
1acce141 | 21242 | @item @code{Ada.Strings.UTF_Encoding} @emph{(A.4.11)} |
64d5610f ML |
21243 | |
21244 | This package provides basic definitions for dealing with UTF-encoded strings. | |
21245 | ||
1acce141 | 21246 | @item @code{Ada.Strings.UTF_Encoding.Conversions} @emph{(A.4.11)} |
64d5610f ML |
21247 | |
21248 | This package provides conversion functions for UTF-encoded strings. | |
21249 | @end table | |
21250 | ||
1acce141 | 21251 | @code{Ada.Strings.UTF_Encoding.Strings} @emph{(A.4.11)} |
64d5610f | 21252 | |
1acce141 | 21253 | @code{Ada.Strings.UTF_Encoding.Wide_Strings} @emph{(A.4.11)} |
64d5610f ML |
21254 | |
21255 | ||
21256 | @table @asis | |
21257 | ||
1acce141 | 21258 | @item @code{Ada.Strings.UTF_Encoding.Wide_Wide_Strings} @emph{(A.4.11)} |
64d5610f ML |
21259 | |
21260 | These packages provide facilities for handling UTF encodings for | |
21261 | Strings, Wide_Strings and Wide_Wide_Strings. | |
21262 | @end table | |
21263 | ||
1acce141 | 21264 | @code{Ada.Strings.Wide_Bounded} @emph{(A.4.7)} |
64d5610f | 21265 | |
1acce141 | 21266 | @code{Ada.Strings.Wide_Fixed} @emph{(A.4.7)} |
64d5610f | 21267 | |
1acce141 | 21268 | @code{Ada.Strings.Wide_Maps} @emph{(A.4.7)} |
64d5610f ML |
21269 | |
21270 | ||
21271 | @table @asis | |
21272 | ||
1acce141 | 21273 | @item @code{Ada.Strings.Wide_Unbounded} @emph{(A.4.7)} |
64d5610f ML |
21274 | |
21275 | These packages provide analogous capabilities to the corresponding | |
21276 | packages without @code{Wide_} in the name, but operate with the types | |
21277 | @code{Wide_String} and @code{Wide_Character} instead of @code{String} | |
21278 | and @code{Character}. Versions of all the child packages are available. | |
21279 | @end table | |
21280 | ||
1acce141 | 21281 | @code{Ada.Strings.Wide_Wide_Bounded} @emph{(A.4.7)} |
64d5610f | 21282 | |
1acce141 | 21283 | @code{Ada.Strings.Wide_Wide_Fixed} @emph{(A.4.7)} |
64d5610f | 21284 | |
1acce141 | 21285 | @code{Ada.Strings.Wide_Wide_Maps} @emph{(A.4.7)} |
64d5610f ML |
21286 | |
21287 | ||
21288 | @table @asis | |
21289 | ||
1acce141 | 21290 | @item @code{Ada.Strings.Wide_Wide_Unbounded} @emph{(A.4.7)} |
64d5610f ML |
21291 | |
21292 | These packages provide analogous capabilities to the corresponding | |
21293 | packages without @code{Wide_} in the name, but operate with the types | |
21294 | @code{Wide_Wide_String} and @code{Wide_Wide_Character} instead | |
21295 | of @code{String} and @code{Character}. | |
21296 | ||
1acce141 | 21297 | @item @code{Ada.Synchronous_Barriers} @emph{(D.10.1)} |
64d5610f ML |
21298 | |
21299 | This package provides facilities for synchronizing tasks at a low level | |
21300 | with barriers. | |
21301 | ||
1acce141 | 21302 | @item @code{Ada.Synchronous_Task_Control} @emph{(D.10)} |
64d5610f ML |
21303 | |
21304 | This package provides some standard facilities for controlling task | |
21305 | communication in a synchronous manner. | |
21306 | ||
1acce141 | 21307 | @item @code{Ada.Synchronous_Task_Control.EDF} @emph{(D.10)} |
64d5610f ML |
21308 | |
21309 | Not implemented in GNAT. | |
21310 | ||
21311 | @item @code{Ada.Tags} | |
21312 | ||
21313 | This package contains definitions for manipulation of the tags of tagged | |
21314 | values. | |
21315 | ||
1acce141 | 21316 | @item @code{Ada.Tags.Generic_Dispatching_Constructor} @emph{(3.9)} |
64d5610f ML |
21317 | |
21318 | This package provides a way of constructing tagged class-wide values given | |
21319 | only the tag value. | |
21320 | ||
1acce141 | 21321 | @item @code{Ada.Task_Attributes} @emph{(C.7.2)} |
64d5610f ML |
21322 | |
21323 | This package provides the capability of associating arbitrary | |
21324 | task-specific data with separate tasks. | |
21325 | ||
1acce141 | 21326 | @item @code{Ada.Task_Identification} @emph{(C.7.1)} |
64d5610f ML |
21327 | |
21328 | This package provides capabilities for task identification. | |
21329 | ||
1acce141 | 21330 | @item @code{Ada.Task_Termination} @emph{(C.7.3)} |
64d5610f ML |
21331 | |
21332 | This package provides control over task termination. | |
21333 | ||
21334 | @item @code{Ada.Text_IO} | |
21335 | ||
21336 | This package provides basic text input-output capabilities for | |
21337 | character, string and numeric data. The subpackages of this | |
21338 | package are listed next. Note that although these are defined | |
21339 | as subpackages in the RM, they are actually transparently | |
21340 | implemented as child packages in GNAT, meaning that they | |
21341 | are only loaded if needed. | |
21342 | ||
21343 | @item @code{Ada.Text_IO.Decimal_IO} | |
21344 | ||
21345 | Provides input-output facilities for decimal fixed-point types | |
21346 | ||
21347 | @item @code{Ada.Text_IO.Enumeration_IO} | |
21348 | ||
21349 | Provides input-output facilities for enumeration types. | |
21350 | ||
21351 | @item @code{Ada.Text_IO.Fixed_IO} | |
21352 | ||
21353 | Provides input-output facilities for ordinary fixed-point types. | |
21354 | ||
21355 | @item @code{Ada.Text_IO.Float_IO} | |
21356 | ||
21357 | Provides input-output facilities for float types. The following | |
21358 | predefined instantiations of this generic package are available: | |
21359 | ||
21360 | ||
21361 | @itemize * | |
21362 | ||
21363 | @item | |
21364 | @code{Short_Float} | |
21365 | ||
21366 | @code{Short_Float_Text_IO} | |
21367 | ||
21368 | @item | |
21369 | @code{Float} | |
21370 | ||
21371 | @code{Float_Text_IO} | |
21372 | ||
21373 | @item | |
21374 | @code{Long_Float} | |
21375 | ||
21376 | @code{Long_Float_Text_IO} | |
21377 | @end itemize | |
21378 | ||
21379 | @item @code{Ada.Text_IO.Integer_IO} | |
21380 | ||
21381 | Provides input-output facilities for integer types. The following | |
21382 | predefined instantiations of this generic package are available: | |
21383 | ||
21384 | ||
21385 | @itemize * | |
21386 | ||
21387 | @item | |
21388 | @code{Short_Short_Integer} | |
21389 | ||
21390 | @code{Ada.Short_Short_Integer_Text_IO} | |
21391 | ||
21392 | @item | |
21393 | @code{Short_Integer} | |
21394 | ||
21395 | @code{Ada.Short_Integer_Text_IO} | |
21396 | ||
21397 | @item | |
21398 | @code{Integer} | |
21399 | ||
21400 | @code{Ada.Integer_Text_IO} | |
21401 | ||
21402 | @item | |
21403 | @code{Long_Integer} | |
21404 | ||
21405 | @code{Ada.Long_Integer_Text_IO} | |
21406 | ||
21407 | @item | |
21408 | @code{Long_Long_Integer} | |
21409 | ||
21410 | @code{Ada.Long_Long_Integer_Text_IO} | |
21411 | @end itemize | |
21412 | ||
21413 | @item @code{Ada.Text_IO.Modular_IO} | |
21414 | ||
21415 | Provides input-output facilities for modular (unsigned) types. | |
21416 | ||
21417 | @item @code{Ada.Text_IO.Bounded_IO (A.10.11)} | |
21418 | ||
21419 | Provides input-output facilities for bounded strings. | |
21420 | ||
21421 | @item @code{Ada.Text_IO.Complex_IO (G.1.3)} | |
21422 | ||
21423 | This package provides basic text input-output capabilities for complex | |
21424 | data. | |
21425 | ||
21426 | @item @code{Ada.Text_IO.Editing (F.3.3)} | |
21427 | ||
21428 | This package contains routines for edited output, analogous to the use | |
21429 | of pictures in COBOL. The picture formats used by this package are a | |
21430 | close copy of the facility in COBOL. | |
21431 | ||
21432 | @item @code{Ada.Text_IO.Text_Streams (A.12.2)} | |
21433 | ||
21434 | This package provides a facility that allows Text_IO files to be treated | |
21435 | as streams, so that the stream attributes can be used for writing | |
21436 | arbitrary data, including binary data, to Text_IO files. | |
21437 | ||
21438 | @item @code{Ada.Text_IO.Unbounded_IO (A.10.12)} | |
21439 | ||
21440 | This package provides input-output facilities for unbounded strings. | |
21441 | ||
21442 | @item @code{Ada.Unchecked_Conversion (13.9)} | |
21443 | ||
21444 | This generic package allows arbitrary conversion from one type to | |
21445 | another of the same size, providing for breaking the type safety in | |
21446 | special circumstances. | |
21447 | ||
21448 | If the types have the same Size (more accurately the same Value_Size), | |
21449 | then the effect is simply to transfer the bits from the source to the | |
21450 | target type without any modification. This usage is well defined, and | |
21451 | for simple types whose representation is typically the same across | |
21452 | all implementations, gives a portable method of performing such | |
21453 | conversions. | |
21454 | ||
21455 | If the types do not have the same size, then the result is implementation | |
21456 | defined, and thus may be non-portable. The following describes how GNAT | |
21457 | handles such unchecked conversion cases. | |
21458 | ||
21459 | If the types are of different sizes, and are both discrete types, then | |
21460 | the effect is of a normal type conversion without any constraint checking. | |
21461 | In particular if the result type has a larger size, the result will be | |
21462 | zero or sign extended. If the result type has a smaller size, the result | |
21463 | will be truncated by ignoring high order bits. | |
21464 | ||
21465 | If the types are of different sizes, and are not both discrete types, | |
21466 | then the conversion works as though pointers were created to the source | |
21467 | and target, and the pointer value is converted. The effect is that bits | |
21468 | are copied from successive low order storage units and bits of the source | |
21469 | up to the length of the target type. | |
21470 | ||
21471 | A warning is issued if the lengths differ, since the effect in this | |
21472 | case is implementation dependent, and the above behavior may not match | |
21473 | that of some other compiler. | |
21474 | ||
21475 | A pointer to one type may be converted to a pointer to another type using | |
21476 | unchecked conversion. The only case in which the effect is undefined is | |
21477 | when one or both pointers are pointers to unconstrained array types. In | |
21478 | this case, the bounds information may get incorrectly transferred, and in | |
21479 | particular, GNAT uses double size pointers for such types, and it is | |
21480 | meaningless to convert between such pointer types. GNAT will issue a | |
21481 | warning if the alignment of the target designated type is more strict | |
21482 | than the alignment of the source designated type (since the result may | |
21483 | be unaligned in this case). | |
21484 | ||
21485 | A pointer other than a pointer to an unconstrained array type may be | |
21486 | converted to and from System.Address. Such usage is common in Ada 83 | |
21487 | programs, but note that Ada.Address_To_Access_Conversions is the | |
21488 | preferred method of performing such conversions in Ada 95 and Ada 2005. | |
21489 | Neither | |
21490 | unchecked conversion nor Ada.Address_To_Access_Conversions should be | |
21491 | used in conjunction with pointers to unconstrained objects, since | |
21492 | the bounds information cannot be handled correctly in this case. | |
21493 | ||
1acce141 | 21494 | @item @code{Ada.Unchecked_Deallocation} @emph{(13.11.2)} |
64d5610f ML |
21495 | |
21496 | This generic package allows explicit freeing of storage previously | |
21497 | allocated by use of an allocator. | |
21498 | ||
1acce141 | 21499 | @item @code{Ada.Wide_Text_IO} @emph{(A.11)} |
64d5610f ML |
21500 | |
21501 | This package is similar to @code{Ada.Text_IO}, except that the external | |
21502 | file supports wide character representations, and the internal types are | |
21503 | @code{Wide_Character} and @code{Wide_String} instead of @code{Character} | |
21504 | and @code{String}. The corresponding set of nested packages and child | |
21505 | packages are defined. | |
21506 | ||
1acce141 | 21507 | @item @code{Ada.Wide_Wide_Text_IO} @emph{(A.11)} |
64d5610f ML |
21508 | |
21509 | This package is similar to @code{Ada.Text_IO}, except that the external | |
21510 | file supports wide character representations, and the internal types are | |
21511 | @code{Wide_Character} and @code{Wide_String} instead of @code{Character} | |
21512 | and @code{String}. The corresponding set of nested packages and child | |
21513 | packages are defined. | |
21514 | @end table | |
21515 | ||
21516 | For packages in Interfaces and System, all the RM defined packages are | |
21517 | available in GNAT, see the Ada 2012 RM for full details. | |
21518 | ||
21519 | @node The Implementation of Standard I/O,The GNAT Library,Standard Library Routines,Top | |
9daee425 | 21520 | @anchor{gnat_rm/the_implementation_of_standard_i_o doc}@anchor{2ad}@anchor{gnat_rm/the_implementation_of_standard_i_o id1}@anchor{2ae}@anchor{gnat_rm/the_implementation_of_standard_i_o the-implementation-of-standard-i-o}@anchor{f} |
64d5610f ML |
21521 | @chapter The Implementation of Standard I/O |
21522 | ||
21523 | ||
21524 | GNAT implements all the required input-output facilities described in | |
21525 | A.6 through A.14. These sections of the Ada Reference Manual describe the | |
21526 | required behavior of these packages from the Ada point of view, and if | |
21527 | you are writing a portable Ada program that does not need to know the | |
21528 | exact manner in which Ada maps to the outside world when it comes to | |
21529 | reading or writing external files, then you do not need to read this | |
21530 | chapter. As long as your files are all regular files (not pipes or | |
21531 | devices), and as long as you write and read the files only from Ada, the | |
21532 | description in the Ada Reference Manual is sufficient. | |
21533 | ||
21534 | However, if you want to do input-output to pipes or other devices, such | |
21535 | as the keyboard or screen, or if the files you are dealing with are | |
21536 | either generated by some other language, or to be read by some other | |
21537 | language, then you need to know more about the details of how the GNAT | |
21538 | implementation of these input-output facilities behaves. | |
21539 | ||
21540 | In this chapter we give a detailed description of exactly how GNAT | |
21541 | interfaces to the file system. As always, the sources of the system are | |
21542 | available to you for answering questions at an even more detailed level, | |
21543 | but for most purposes the information in this chapter will suffice. | |
21544 | ||
21545 | Another reason that you may need to know more about how input-output is | |
21546 | implemented arises when you have a program written in mixed languages | |
21547 | where, for example, files are shared between the C and Ada sections of | |
21548 | the same program. GNAT provides some additional facilities, in the form | |
21549 | of additional child library packages, that facilitate this sharing, and | |
21550 | these additional facilities are also described in this chapter. | |
21551 | ||
21552 | @menu | |
21553 | * Standard I/O Packages:: | |
21554 | * FORM Strings:: | |
21555 | * Direct_IO:: | |
21556 | * Sequential_IO:: | |
21557 | * Text_IO:: | |
21558 | * Wide_Text_IO:: | |
21559 | * Wide_Wide_Text_IO:: | |
21560 | * Stream_IO:: | |
21561 | * Text Translation:: | |
21562 | * Shared Files:: | |
21563 | * Filenames encoding:: | |
21564 | * File content encoding:: | |
21565 | * Open Modes:: | |
21566 | * Operations on C Streams:: | |
21567 | * Interfacing to C Streams:: | |
21568 | ||
21569 | @end menu | |
21570 | ||
21571 | @node Standard I/O Packages,FORM Strings,,The Implementation of Standard I/O | |
9daee425 | 21572 | @anchor{gnat_rm/the_implementation_of_standard_i_o id2}@anchor{2af}@anchor{gnat_rm/the_implementation_of_standard_i_o standard-i-o-packages}@anchor{2b0} |
64d5610f ML |
21573 | @section Standard I/O Packages |
21574 | ||
21575 | ||
21576 | The Standard I/O packages described in Annex A for | |
21577 | ||
21578 | ||
21579 | @itemize * | |
21580 | ||
21581 | @item | |
21582 | Ada.Text_IO | |
21583 | ||
21584 | @item | |
21585 | Ada.Text_IO.Complex_IO | |
21586 | ||
21587 | @item | |
21588 | Ada.Text_IO.Text_Streams | |
21589 | ||
21590 | @item | |
21591 | Ada.Wide_Text_IO | |
21592 | ||
21593 | @item | |
21594 | Ada.Wide_Text_IO.Complex_IO | |
21595 | ||
21596 | @item | |
21597 | Ada.Wide_Text_IO.Text_Streams | |
21598 | ||
21599 | @item | |
21600 | Ada.Wide_Wide_Text_IO | |
21601 | ||
21602 | @item | |
21603 | Ada.Wide_Wide_Text_IO.Complex_IO | |
21604 | ||
21605 | @item | |
21606 | Ada.Wide_Wide_Text_IO.Text_Streams | |
21607 | ||
21608 | @item | |
21609 | Ada.Stream_IO | |
21610 | ||
21611 | @item | |
21612 | Ada.Sequential_IO | |
21613 | ||
21614 | @item | |
21615 | Ada.Direct_IO | |
21616 | @end itemize | |
21617 | ||
21618 | are implemented using the C | |
21619 | library streams facility; where | |
21620 | ||
21621 | ||
21622 | @itemize * | |
21623 | ||
21624 | @item | |
21625 | All files are opened using @code{fopen}. | |
21626 | ||
21627 | @item | |
19546867 | 21628 | All input/output operations use @code{fread}/@code{fwrite}. |
64d5610f ML |
21629 | @end itemize |
21630 | ||
21631 | There is no internal buffering of any kind at the Ada library level. The only | |
21632 | buffering is that provided at the system level in the implementation of the | |
21633 | library routines that support streams. This facilitates shared use of these | |
21634 | streams by mixed language programs. Note though that system level buffering is | |
21635 | explicitly enabled at elaboration of the standard I/O packages and that can | |
21636 | have an impact on mixed language programs, in particular those using I/O before | |
21637 | calling the Ada elaboration routine (e.g., adainit). It is recommended to call | |
21638 | the Ada elaboration routine before performing any I/O or when impractical, | |
21639 | flush the common I/O streams and in particular Standard_Output before | |
21640 | elaborating the Ada code. | |
21641 | ||
21642 | @node FORM Strings,Direct_IO,Standard I/O Packages,The Implementation of Standard I/O | |
9daee425 | 21643 | @anchor{gnat_rm/the_implementation_of_standard_i_o form-strings}@anchor{2b1}@anchor{gnat_rm/the_implementation_of_standard_i_o id3}@anchor{2b2} |
64d5610f ML |
21644 | @section FORM Strings |
21645 | ||
21646 | ||
21647 | The format of a FORM string in GNAT is: | |
21648 | ||
21649 | @example | |
21650 | "keyword=value,keyword=value,...,keyword=value" | |
21651 | @end example | |
21652 | ||
21653 | where letters may be in upper or lower case, and there are no spaces | |
21654 | between values. The order of the entries is not important. Currently | |
21655 | the following keywords defined. | |
21656 | ||
21657 | @example | |
21658 | TEXT_TRANSLATION=[YES|NO|TEXT|BINARY|U8TEXT|WTEXT|U16TEXT] | |
21659 | SHARED=[YES|NO] | |
21660 | WCEM=[n|h|u|s|e|8|b] | |
21661 | ENCODING=[UTF8|8BITS] | |
21662 | @end example | |
21663 | ||
21664 | The use of these parameters is described later in this section. If an | |
21665 | unrecognized keyword appears in a form string, it is silently ignored | |
21666 | and not considered invalid. | |
21667 | ||
21668 | @node Direct_IO,Sequential_IO,FORM Strings,The Implementation of Standard I/O | |
9daee425 | 21669 | @anchor{gnat_rm/the_implementation_of_standard_i_o direct-io}@anchor{2b3}@anchor{gnat_rm/the_implementation_of_standard_i_o id4}@anchor{2b4} |
64d5610f ML |
21670 | @section Direct_IO |
21671 | ||
21672 | ||
21673 | Direct_IO can only be instantiated for definite types. This is a | |
21674 | restriction of the Ada language, which means that the records are fixed | |
21675 | length (the length being determined by @code{type'Size}, rounded | |
21676 | up to the next storage unit boundary if necessary). | |
21677 | ||
21678 | The records of a Direct_IO file are simply written to the file in index | |
21679 | sequence, with the first record starting at offset zero, and subsequent | |
21680 | records following. There is no control information of any kind. For | |
21681 | example, if 32-bit integers are being written, each record takes | |
19546867 | 21682 | 4-bytes, so the record at index @code{K} starts at offset @code{(K-1)*4}. |
64d5610f ML |
21683 | |
21684 | There is no limit on the size of Direct_IO files, they are expanded as | |
21685 | necessary to accommodate whatever records are written to the file. | |
21686 | ||
21687 | @node Sequential_IO,Text_IO,Direct_IO,The Implementation of Standard I/O | |
9daee425 | 21688 | @anchor{gnat_rm/the_implementation_of_standard_i_o id5}@anchor{2b5}@anchor{gnat_rm/the_implementation_of_standard_i_o sequential-io}@anchor{2b6} |
64d5610f ML |
21689 | @section Sequential_IO |
21690 | ||
21691 | ||
21692 | Sequential_IO may be instantiated with either a definite (constrained) | |
21693 | or indefinite (unconstrained) type. | |
21694 | ||
21695 | For the definite type case, the elements written to the file are simply | |
21696 | the memory images of the data values with no control information of any | |
21697 | kind. The resulting file should be read using the same type, no validity | |
21698 | checking is performed on input. | |
21699 | ||
21700 | For the indefinite type case, the elements written consist of two | |
21701 | parts. First is the size of the data item, written as the memory image | |
21702 | of a @code{Interfaces.C.size_t} value, followed by the memory image of | |
21703 | the data value. The resulting file can only be read using the same | |
21704 | (unconstrained) type. Normal assignment checks are performed on these | |
21705 | read operations, and if these checks fail, @code{Data_Error} is | |
21706 | raised. In particular, in the array case, the lengths must match, and in | |
21707 | the variant record case, if the variable for a particular read operation | |
21708 | is constrained, the discriminants must match. | |
21709 | ||
21710 | Note that it is not possible to use Sequential_IO to write variable | |
21711 | length array items, and then read the data back into different length | |
21712 | arrays. For example, the following will raise @code{Data_Error}: | |
21713 | ||
21714 | @example | |
21715 | package IO is new Sequential_IO (String); | |
21716 | F : IO.File_Type; | |
21717 | S : String (1..4); | |
21718 | ... | |
21719 | IO.Create (F) | |
21720 | IO.Write (F, "hello!") | |
21721 | IO.Reset (F, Mode=>In_File); | |
21722 | IO.Read (F, S); | |
21723 | Put_Line (S); | |
21724 | @end example | |
21725 | ||
21726 | On some Ada implementations, this will print @code{hell}, but the program is | |
21727 | clearly incorrect, since there is only one element in the file, and that | |
21728 | element is the string @code{hello!}. | |
21729 | ||
21730 | In Ada 95 and Ada 2005, this kind of behavior can be legitimately achieved | |
21731 | using Stream_IO, and this is the preferred mechanism. In particular, the | |
21732 | above program fragment rewritten to use Stream_IO will work correctly. | |
21733 | ||
21734 | @node Text_IO,Wide_Text_IO,Sequential_IO,The Implementation of Standard I/O | |
9daee425 | 21735 | @anchor{gnat_rm/the_implementation_of_standard_i_o id6}@anchor{2b7}@anchor{gnat_rm/the_implementation_of_standard_i_o text-io}@anchor{2b8} |
64d5610f ML |
21736 | @section Text_IO |
21737 | ||
21738 | ||
21739 | Text_IO files consist of a stream of characters containing the following | |
21740 | special control characters: | |
21741 | ||
21742 | @example | |
21743 | LF (line feed, 16#0A#) Line Mark | |
21744 | FF (form feed, 16#0C#) Page Mark | |
21745 | @end example | |
21746 | ||
21747 | A canonical Text_IO file is defined as one in which the following | |
21748 | conditions are met: | |
21749 | ||
21750 | ||
21751 | @itemize * | |
21752 | ||
21753 | @item | |
21754 | The character @code{LF} is used only as a line mark, i.e., to mark the end | |
21755 | of the line. | |
21756 | ||
21757 | @item | |
21758 | The character @code{FF} is used only as a page mark, i.e., to mark the | |
21759 | end of a page and consequently can appear only immediately following a | |
21760 | @code{LF} (line mark) character. | |
21761 | ||
21762 | @item | |
21763 | The file ends with either @code{LF} (line mark) or @code{LF}-@cite{FF} | |
21764 | (line mark, page mark). In the former case, the page mark is implicitly | |
21765 | assumed to be present. | |
21766 | @end itemize | |
21767 | ||
21768 | A file written using Text_IO will be in canonical form provided that no | |
21769 | explicit @code{LF} or @code{FF} characters are written using @code{Put} | |
21770 | or @code{Put_Line}. There will be no @code{FF} character at the end of | |
21771 | the file unless an explicit @code{New_Page} operation was performed | |
21772 | before closing the file. | |
21773 | ||
21774 | A canonical Text_IO file that is a regular file (i.e., not a device or a | |
21775 | pipe) can be read using any of the routines in Text_IO. The | |
21776 | semantics in this case will be exactly as defined in the Ada Reference | |
21777 | Manual, and all the routines in Text_IO are fully implemented. | |
21778 | ||
21779 | A text file that does not meet the requirements for a canonical Text_IO | |
21780 | file has one of the following: | |
21781 | ||
21782 | ||
21783 | @itemize * | |
21784 | ||
21785 | @item | |
21786 | The file contains @code{FF} characters not immediately following a | |
21787 | @code{LF} character. | |
21788 | ||
21789 | @item | |
21790 | The file contains @code{LF} or @code{FF} characters written by | |
21791 | @code{Put} or @code{Put_Line}, which are not logically considered to be | |
21792 | line marks or page marks. | |
21793 | ||
21794 | @item | |
21795 | The file ends in a character other than @code{LF} or @code{FF}, | |
21796 | i.e., there is no explicit line mark or page mark at the end of the file. | |
21797 | @end itemize | |
21798 | ||
21799 | Text_IO can be used to read such non-standard text files but subprograms | |
21800 | to do with line or page numbers do not have defined meanings. In | |
21801 | particular, a @code{FF} character that does not follow a @code{LF} | |
21802 | character may or may not be treated as a page mark from the point of | |
21803 | view of page and line numbering. Every @code{LF} character is considered | |
21804 | to end a line, and there is an implied @code{LF} character at the end of | |
21805 | the file. | |
21806 | ||
21807 | @menu | |
21808 | * Stream Pointer Positioning:: | |
21809 | * Reading and Writing Non-Regular Files:: | |
21810 | * Get_Immediate:: | |
21811 | * Treating Text_IO Files as Streams:: | |
21812 | * Text_IO Extensions:: | |
21813 | * Text_IO Facilities for Unbounded Strings:: | |
21814 | ||
21815 | @end menu | |
21816 | ||
21817 | @node Stream Pointer Positioning,Reading and Writing Non-Regular Files,,Text_IO | |
9daee425 | 21818 | @anchor{gnat_rm/the_implementation_of_standard_i_o id7}@anchor{2b9}@anchor{gnat_rm/the_implementation_of_standard_i_o stream-pointer-positioning}@anchor{2ba} |
64d5610f ML |
21819 | @subsection Stream Pointer Positioning |
21820 | ||
21821 | ||
21822 | @code{Ada.Text_IO} has a definition of current position for a file that | |
21823 | is being read. No internal buffering occurs in Text_IO, and usually the | |
21824 | physical position in the stream used to implement the file corresponds | |
21825 | to this logical position defined by Text_IO. There are two exceptions: | |
21826 | ||
21827 | ||
21828 | @itemize * | |
21829 | ||
21830 | @item | |
21831 | After a call to @code{End_Of_Page} that returns @code{True}, the stream | |
21832 | is positioned past the @code{LF} (line mark) that precedes the page | |
21833 | mark. Text_IO maintains an internal flag so that subsequent read | |
21834 | operations properly handle the logical position which is unchanged by | |
21835 | the @code{End_Of_Page} call. | |
21836 | ||
21837 | @item | |
21838 | After a call to @code{End_Of_File} that returns @code{True}, if the | |
21839 | Text_IO file was positioned before the line mark at the end of file | |
21840 | before the call, then the logical position is unchanged, but the stream | |
21841 | is physically positioned right at the end of file (past the line mark, | |
21842 | and past a possible page mark following the line mark. Again Text_IO | |
21843 | maintains internal flags so that subsequent read operations properly | |
21844 | handle the logical position. | |
21845 | @end itemize | |
21846 | ||
21847 | These discrepancies have no effect on the observable behavior of | |
21848 | Text_IO, but if a single Ada stream is shared between a C program and | |
21849 | Ada program, or shared (using @code{shared=yes} in the form string) | |
21850 | between two Ada files, then the difference may be observable in some | |
21851 | situations. | |
21852 | ||
21853 | @node Reading and Writing Non-Regular Files,Get_Immediate,Stream Pointer Positioning,Text_IO | |
9daee425 | 21854 | @anchor{gnat_rm/the_implementation_of_standard_i_o id8}@anchor{2bb}@anchor{gnat_rm/the_implementation_of_standard_i_o reading-and-writing-non-regular-files}@anchor{2bc} |
64d5610f ML |
21855 | @subsection Reading and Writing Non-Regular Files |
21856 | ||
21857 | ||
21858 | A non-regular file is a device (such as a keyboard), or a pipe. Text_IO | |
21859 | can be used for reading and writing. Writing is not affected and the | |
21860 | sequence of characters output is identical to the normal file case, but | |
21861 | for reading, the behavior of Text_IO is modified to avoid undesirable | |
21862 | look-ahead as follows: | |
21863 | ||
21864 | An input file that is not a regular file is considered to have no page | |
21865 | marks. Any @code{Ascii.FF} characters (the character normally used for a | |
21866 | page mark) appearing in the file are considered to be data | |
21867 | characters. In particular: | |
21868 | ||
21869 | ||
21870 | @itemize * | |
21871 | ||
21872 | @item | |
21873 | @code{Get_Line} and @code{Skip_Line} do not test for a page mark | |
21874 | following a line mark. If a page mark appears, it will be treated as a | |
21875 | data character. | |
21876 | ||
21877 | @item | |
21878 | This avoids the need to wait for an extra character to be typed or | |
21879 | entered from the pipe to complete one of these operations. | |
21880 | ||
21881 | @item | |
21882 | @code{End_Of_Page} always returns @code{False} | |
21883 | ||
21884 | @item | |
21885 | @code{End_Of_File} will return @code{False} if there is a page mark at | |
21886 | the end of the file. | |
21887 | @end itemize | |
21888 | ||
21889 | Output to non-regular files is the same as for regular files. Page marks | |
21890 | may be written to non-regular files using @code{New_Page}, but as noted | |
21891 | above they will not be treated as page marks on input if the output is | |
21892 | piped to another Ada program. | |
21893 | ||
21894 | Another important discrepancy when reading non-regular files is that the end | |
21895 | of file indication is not ‘sticky’. If an end of file is entered, e.g., by | |
21896 | pressing the @code{EOT} key, | |
21897 | then end of file | |
21898 | is signaled once (i.e., the test @code{End_Of_File} | |
21899 | will yield @code{True}, or a read will | |
21900 | raise @code{End_Error}), but then reading can resume | |
21901 | to read data past that end of | |
21902 | file indication, until another end of file indication is entered. | |
21903 | ||
21904 | @node Get_Immediate,Treating Text_IO Files as Streams,Reading and Writing Non-Regular Files,Text_IO | |
9daee425 | 21905 | @anchor{gnat_rm/the_implementation_of_standard_i_o get-immediate}@anchor{2bd}@anchor{gnat_rm/the_implementation_of_standard_i_o id9}@anchor{2be} |
64d5610f ML |
21906 | @subsection Get_Immediate |
21907 | ||
21908 | ||
21909 | @geindex Get_Immediate | |
21910 | ||
21911 | Get_Immediate returns the next character (including control characters) | |
21912 | from the input file. In particular, Get_Immediate will return LF or FF | |
21913 | characters used as line marks or page marks. Such operations leave the | |
21914 | file positioned past the control character, and it is thus not treated | |
21915 | as having its normal function. This means that page, line and column | |
21916 | counts after this kind of Get_Immediate call are set as though the mark | |
21917 | did not occur. In the case where a Get_Immediate leaves the file | |
21918 | positioned between the line mark and page mark (which is not normally | |
21919 | possible), it is undefined whether the FF character will be treated as a | |
21920 | page mark. | |
21921 | ||
21922 | @node Treating Text_IO Files as Streams,Text_IO Extensions,Get_Immediate,Text_IO | |
9daee425 | 21923 | @anchor{gnat_rm/the_implementation_of_standard_i_o id10}@anchor{2bf}@anchor{gnat_rm/the_implementation_of_standard_i_o treating-text-io-files-as-streams}@anchor{2c0} |
64d5610f ML |
21924 | @subsection Treating Text_IO Files as Streams |
21925 | ||
21926 | ||
21927 | @geindex Stream files | |
21928 | ||
21929 | The package @code{Text_IO.Streams} allows a @code{Text_IO} file to be treated | |
21930 | as a stream. Data written to a @code{Text_IO} file in this stream mode is | |
21931 | binary data. If this binary data contains bytes 16#0A# (@code{LF}) or | |
21932 | 16#0C# (@code{FF}), the resulting file may have non-standard | |
21933 | format. Similarly if read operations are used to read from a Text_IO | |
21934 | file treated as a stream, then @code{LF} and @code{FF} characters may be | |
21935 | skipped and the effect is similar to that described above for | |
21936 | @code{Get_Immediate}. | |
21937 | ||
21938 | @node Text_IO Extensions,Text_IO Facilities for Unbounded Strings,Treating Text_IO Files as Streams,Text_IO | |
9daee425 | 21939 | @anchor{gnat_rm/the_implementation_of_standard_i_o id11}@anchor{2c1}@anchor{gnat_rm/the_implementation_of_standard_i_o text-io-extensions}@anchor{2c2} |
64d5610f ML |
21940 | @subsection Text_IO Extensions |
21941 | ||
21942 | ||
21943 | @geindex Text_IO extensions | |
21944 | ||
21945 | A package GNAT.IO_Aux in the GNAT library provides some useful extensions | |
21946 | to the standard @code{Text_IO} package: | |
21947 | ||
21948 | ||
21949 | @itemize * | |
21950 | ||
21951 | @item | |
21952 | function File_Exists (Name : String) return Boolean; | |
21953 | Determines if a file of the given name exists. | |
21954 | ||
21955 | @item | |
21956 | function Get_Line return String; | |
21957 | Reads a string from the standard input file. The value returned is exactly | |
21958 | the length of the line that was read. | |
21959 | ||
21960 | @item | |
21961 | function Get_Line (File : Ada.Text_IO.File_Type) return String; | |
21962 | Similar, except that the parameter File specifies the file from which | |
21963 | the string is to be read. | |
21964 | @end itemize | |
21965 | ||
21966 | @node Text_IO Facilities for Unbounded Strings,,Text_IO Extensions,Text_IO | |
9daee425 | 21967 | @anchor{gnat_rm/the_implementation_of_standard_i_o id12}@anchor{2c3}@anchor{gnat_rm/the_implementation_of_standard_i_o text-io-facilities-for-unbounded-strings}@anchor{2c4} |
64d5610f ML |
21968 | @subsection Text_IO Facilities for Unbounded Strings |
21969 | ||
21970 | ||
21971 | @geindex Text_IO for unbounded strings | |
21972 | ||
21973 | @geindex Unbounded_String | |
21974 | @geindex Text_IO operations | |
21975 | ||
21976 | The package @code{Ada.Strings.Unbounded.Text_IO} | |
21977 | in library files @code{a-suteio.ads/adb} contains some GNAT-specific | |
21978 | subprograms useful for Text_IO operations on unbounded strings: | |
21979 | ||
21980 | ||
21981 | @itemize * | |
21982 | ||
21983 | @item | |
21984 | function Get_Line (File : File_Type) return Unbounded_String; | |
21985 | Reads a line from the specified file | |
21986 | and returns the result as an unbounded string. | |
21987 | ||
21988 | @item | |
21989 | procedure Put (File : File_Type; U : Unbounded_String); | |
21990 | Writes the value of the given unbounded string to the specified file | |
21991 | Similar to the effect of | |
21992 | @code{Put (To_String (U))} except that an extra copy is avoided. | |
21993 | ||
21994 | @item | |
21995 | procedure Put_Line (File : File_Type; U : Unbounded_String); | |
21996 | Writes the value of the given unbounded string to the specified file, | |
21997 | followed by a @code{New_Line}. | |
21998 | Similar to the effect of @code{Put_Line (To_String (U))} except | |
21999 | that an extra copy is avoided. | |
22000 | @end itemize | |
22001 | ||
22002 | In the above procedures, @code{File} is of type @code{Ada.Text_IO.File_Type} | |
22003 | and is optional. If the parameter is omitted, then the standard input or | |
22004 | output file is referenced as appropriate. | |
22005 | ||
22006 | The package @code{Ada.Strings.Wide_Unbounded.Wide_Text_IO} in library | |
22007 | files @code{a-swuwti.ads} and @code{a-swuwti.adb} provides similar extended | |
22008 | @code{Wide_Text_IO} functionality for unbounded wide strings. | |
22009 | ||
22010 | The package @code{Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO} in library | |
22011 | files @code{a-szuzti.ads} and @code{a-szuzti.adb} provides similar extended | |
22012 | @code{Wide_Wide_Text_IO} functionality for unbounded wide wide strings. | |
22013 | ||
22014 | @node Wide_Text_IO,Wide_Wide_Text_IO,Text_IO,The Implementation of Standard I/O | |
9daee425 | 22015 | @anchor{gnat_rm/the_implementation_of_standard_i_o id13}@anchor{2c5}@anchor{gnat_rm/the_implementation_of_standard_i_o wide-text-io}@anchor{2c6} |
64d5610f ML |
22016 | @section Wide_Text_IO |
22017 | ||
22018 | ||
22019 | @code{Wide_Text_IO} is similar in most respects to Text_IO, except that | |
22020 | both input and output files may contain special sequences that represent | |
22021 | wide character values. The encoding scheme for a given file may be | |
22022 | specified using a FORM parameter: | |
22023 | ||
22024 | @example | |
22025 | WCEM=`x` | |
22026 | @end example | |
22027 | ||
22028 | as part of the FORM string (WCEM = wide character encoding method), | |
22029 | where @code{x} is one of the following characters | |
22030 | ||
22031 | ||
22032 | @multitable {xxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxx} | |
22033 | @headitem | |
22034 | ||
22035 | Character | |
22036 | ||
22037 | @tab | |
22038 | ||
22039 | Encoding | |
22040 | ||
22041 | @item | |
22042 | ||
1acce141 | 22043 | @emph{h} |
64d5610f ML |
22044 | |
22045 | @tab | |
22046 | ||
22047 | Hex ESC encoding | |
22048 | ||
22049 | @item | |
22050 | ||
1acce141 | 22051 | @emph{u} |
64d5610f ML |
22052 | |
22053 | @tab | |
22054 | ||
22055 | Upper half encoding | |
22056 | ||
22057 | @item | |
22058 | ||
1acce141 | 22059 | @emph{s} |
64d5610f ML |
22060 | |
22061 | @tab | |
22062 | ||
22063 | Shift-JIS encoding | |
22064 | ||
22065 | @item | |
22066 | ||
1acce141 | 22067 | @emph{e} |
64d5610f ML |
22068 | |
22069 | @tab | |
22070 | ||
22071 | EUC Encoding | |
22072 | ||
22073 | @item | |
22074 | ||
1acce141 | 22075 | @emph{8} |
64d5610f ML |
22076 | |
22077 | @tab | |
22078 | ||
22079 | UTF-8 encoding | |
22080 | ||
22081 | @item | |
22082 | ||
1acce141 | 22083 | @emph{b} |
64d5610f ML |
22084 | |
22085 | @tab | |
22086 | ||
22087 | Brackets encoding | |
22088 | ||
22089 | @end multitable | |
22090 | ||
22091 | ||
22092 | The encoding methods match those that | |
22093 | can be used in a source | |
22094 | program, but there is no requirement that the encoding method used for | |
22095 | the source program be the same as the encoding method used for files, | |
22096 | and different files may use different encoding methods. | |
22097 | ||
22098 | The default encoding method for the standard files, and for opened files | |
22099 | for which no WCEM parameter is given in the FORM string matches the | |
22100 | wide character encoding specified for the main program (the default | |
22101 | being brackets encoding if no coding method was specified with -gnatW). | |
22102 | ||
22103 | ||
22104 | @table @asis | |
22105 | ||
1acce141 | 22106 | @item @emph{Hex Coding} |
64d5610f ML |
22107 | |
22108 | In this encoding, a wide character is represented by a five character | |
22109 | sequence: | |
22110 | @end table | |
22111 | ||
22112 | @example | |
22113 | ESC a b c d | |
22114 | @end example | |
22115 | ||
22116 | ||
22117 | @quotation | |
22118 | ||
22119 | where @code{a}, @code{b}, @code{c}, @code{d} are the four hexadecimal | |
22120 | characters (using upper case letters) of the wide character code. For | |
22121 | example, ESC A345 is used to represent the wide character with code | |
22122 | 16#A345#. This scheme is compatible with use of the full | |
22123 | @code{Wide_Character} set. | |
22124 | @end quotation | |
22125 | ||
22126 | ||
22127 | @table @asis | |
22128 | ||
1acce141 | 22129 | @item @emph{Upper Half Coding} |
64d5610f ML |
22130 | |
22131 | The wide character with encoding 16#abcd#, where the upper bit is on | |
22132 | (i.e., a is in the range 8-F) is represented as two bytes 16#ab# and | |
22133 | 16#cd#. The second byte may never be a format control character, but is | |
22134 | not required to be in the upper half. This method can be also used for | |
22135 | shift-JIS or EUC where the internal coding matches the external coding. | |
22136 | ||
1acce141 | 22137 | @item @emph{Shift JIS Coding} |
64d5610f ML |
22138 | |
22139 | A wide character is represented by a two character sequence 16#ab# and | |
22140 | 16#cd#, with the restrictions described for upper half encoding as | |
22141 | described above. The internal character code is the corresponding JIS | |
22142 | character according to the standard algorithm for Shift-JIS | |
22143 | conversion. Only characters defined in the JIS code set table can be | |
22144 | used with this encoding method. | |
22145 | ||
1acce141 | 22146 | @item @emph{EUC Coding} |
64d5610f ML |
22147 | |
22148 | A wide character is represented by a two character sequence 16#ab# and | |
22149 | 16#cd#, with both characters being in the upper half. The internal | |
22150 | character code is the corresponding JIS character according to the EUC | |
22151 | encoding algorithm. Only characters defined in the JIS code set table | |
22152 | can be used with this encoding method. | |
22153 | ||
1acce141 | 22154 | @item @emph{UTF-8 Coding} |
64d5610f ML |
22155 | |
22156 | A wide character is represented using | |
22157 | UCS Transformation Format 8 (UTF-8) as defined in Annex R of ISO | |
22158 | 10646-1/Am.2. Depending on the character value, the representation | |
22159 | is a one, two, or three byte sequence: | |
22160 | @end table | |
22161 | ||
22162 | @example | |
22163 | 16#0000#-16#007f#: 2#0xxxxxxx# | |
22164 | 16#0080#-16#07ff#: 2#110xxxxx# 2#10xxxxxx# | |
22165 | 16#0800#-16#ffff#: 2#1110xxxx# 2#10xxxxxx# 2#10xxxxxx# | |
22166 | @end example | |
22167 | ||
22168 | ||
22169 | @quotation | |
22170 | ||
22171 | where the @code{xxx} bits correspond to the left-padded bits of the | |
22172 | 16-bit character value. Note that all lower half ASCII characters | |
22173 | are represented as ASCII bytes and all upper half characters and | |
22174 | other wide characters are represented as sequences of upper-half | |
22175 | (The full UTF-8 scheme allows for encoding 31-bit characters as | |
22176 | 6-byte sequences, but in this implementation, all UTF-8 sequences | |
22177 | of four or more bytes length will raise a Constraint_Error, as | |
22178 | will all invalid UTF-8 sequences.) | |
22179 | @end quotation | |
22180 | ||
22181 | ||
22182 | @table @asis | |
22183 | ||
1acce141 | 22184 | @item @emph{Brackets Coding} |
64d5610f ML |
22185 | |
22186 | In this encoding, a wide character is represented by the following eight | |
22187 | character sequence: | |
22188 | @end table | |
22189 | ||
22190 | @example | |
22191 | [ " a b c d " ] | |
22192 | @end example | |
22193 | ||
22194 | ||
22195 | @quotation | |
22196 | ||
22197 | where @code{a}, @code{b}, @code{c}, @code{d} are the four hexadecimal | |
22198 | characters (using uppercase letters) of the wide character code. For | |
22199 | example, @code{["A345"]} is used to represent the wide character with code | |
22200 | @code{16#A345#}. | |
22201 | This scheme is compatible with use of the full Wide_Character set. | |
22202 | On input, brackets coding can also be used for upper half characters, | |
22203 | e.g., @code{["C1"]} for lower case a. However, on output, brackets notation | |
22204 | is only used for wide characters with a code greater than @code{16#FF#}. | |
22205 | ||
22206 | Note that brackets coding is not normally used in the context of | |
22207 | Wide_Text_IO or Wide_Wide_Text_IO, since it is really just designed as | |
22208 | a portable way of encoding source files. In the context of Wide_Text_IO | |
22209 | or Wide_Wide_Text_IO, it can only be used if the file does not contain | |
22210 | any instance of the left bracket character other than to encode wide | |
22211 | character values using the brackets encoding method. In practice it is | |
22212 | expected that some standard wide character encoding method such | |
22213 | as UTF-8 will be used for text input output. | |
22214 | ||
22215 | If brackets notation is used, then any occurrence of a left bracket | |
22216 | in the input file which is not the start of a valid wide character | |
22217 | sequence will cause Constraint_Error to be raised. It is possible to | |
22218 | encode a left bracket as [“5B”] and Wide_Text_IO and Wide_Wide_Text_IO | |
22219 | input will interpret this as a left bracket. | |
22220 | ||
22221 | However, when a left bracket is output, it will be output as a left bracket | |
22222 | and not as [“5B”]. We make this decision because for normal use of | |
22223 | Wide_Text_IO for outputting messages, it is unpleasant to clobber left | |
22224 | brackets. For example, if we write: | |
22225 | ||
22226 | @example | |
22227 | Put_Line ("Start of output [first run]"); | |
22228 | @end example | |
22229 | ||
22230 | we really do not want to have the left bracket in this message clobbered so | |
22231 | that the output reads: | |
22232 | @end quotation | |
22233 | ||
22234 | @example | |
22235 | Start of output ["5B"]first run] | |
22236 | @end example | |
22237 | ||
22238 | ||
22239 | @quotation | |
22240 | ||
22241 | In practice brackets encoding is reasonably useful for normal Put_Line use | |
22242 | since we won’t get confused between left brackets and wide character | |
22243 | sequences in the output. But for input, or when files are written out | |
22244 | and read back in, it really makes better sense to use one of the standard | |
22245 | encoding methods such as UTF-8. | |
22246 | @end quotation | |
22247 | ||
22248 | For the coding schemes other than UTF-8, Hex, or Brackets encoding, | |
22249 | not all wide character | |
22250 | values can be represented. An attempt to output a character that cannot | |
22251 | be represented using the encoding scheme for the file causes | |
22252 | Constraint_Error to be raised. An invalid wide character sequence on | |
22253 | input also causes Constraint_Error to be raised. | |
22254 | ||
22255 | @menu | |
22256 | * Stream Pointer Positioning: Stream Pointer Positioning<2>. | |
22257 | * Reading and Writing Non-Regular Files: Reading and Writing Non-Regular Files<2>. | |
22258 | ||
22259 | @end menu | |
22260 | ||
22261 | @node Stream Pointer Positioning<2>,Reading and Writing Non-Regular Files<2>,,Wide_Text_IO | |
9daee425 | 22262 | @anchor{gnat_rm/the_implementation_of_standard_i_o id14}@anchor{2c7}@anchor{gnat_rm/the_implementation_of_standard_i_o stream-pointer-positioning-1}@anchor{2c8} |
64d5610f ML |
22263 | @subsection Stream Pointer Positioning |
22264 | ||
22265 | ||
22266 | @code{Ada.Wide_Text_IO} is similar to @code{Ada.Text_IO} in its handling | |
9daee425 | 22267 | of stream pointer positioning (@ref{2b8,,Text_IO}). There is one additional |
64d5610f ML |
22268 | case: |
22269 | ||
22270 | If @code{Ada.Wide_Text_IO.Look_Ahead} reads a character outside the | |
22271 | normal lower ASCII set, i.e. a character in the range: | |
22272 | ||
22273 | @example | |
22274 | Wide_Character'Val (16#0080#) .. Wide_Character'Val (16#FFFF#) | |
22275 | @end example | |
22276 | ||
22277 | then although the logical position of the file pointer is unchanged by | |
22278 | the @code{Look_Ahead} call, the stream is physically positioned past the | |
22279 | wide character sequence. Again this is to avoid the need for buffering | |
22280 | or backup, and all @code{Wide_Text_IO} routines check the internal | |
22281 | indication that this situation has occurred so that this is not visible | |
22282 | to a normal program using @code{Wide_Text_IO}. However, this discrepancy | |
22283 | can be observed if the wide text file shares a stream with another file. | |
22284 | ||
22285 | @node Reading and Writing Non-Regular Files<2>,,Stream Pointer Positioning<2>,Wide_Text_IO | |
9daee425 | 22286 | @anchor{gnat_rm/the_implementation_of_standard_i_o id15}@anchor{2c9}@anchor{gnat_rm/the_implementation_of_standard_i_o reading-and-writing-non-regular-files-1}@anchor{2ca} |
64d5610f ML |
22287 | @subsection Reading and Writing Non-Regular Files |
22288 | ||
22289 | ||
22290 | As in the case of Text_IO, when a non-regular file is read, it is | |
22291 | assumed that the file contains no page marks (any form characters are | |
22292 | treated as data characters), and @code{End_Of_Page} always returns | |
22293 | @code{False}. Similarly, the end of file indication is not sticky, so | |
22294 | it is possible to read beyond an end of file. | |
22295 | ||
22296 | @node Wide_Wide_Text_IO,Stream_IO,Wide_Text_IO,The Implementation of Standard I/O | |
9daee425 | 22297 | @anchor{gnat_rm/the_implementation_of_standard_i_o id16}@anchor{2cb}@anchor{gnat_rm/the_implementation_of_standard_i_o wide-wide-text-io}@anchor{2cc} |
64d5610f ML |
22298 | @section Wide_Wide_Text_IO |
22299 | ||
22300 | ||
22301 | @code{Wide_Wide_Text_IO} is similar in most respects to Text_IO, except that | |
22302 | both input and output files may contain special sequences that represent | |
22303 | wide wide character values. The encoding scheme for a given file may be | |
22304 | specified using a FORM parameter: | |
22305 | ||
22306 | @example | |
22307 | WCEM=`x` | |
22308 | @end example | |
22309 | ||
22310 | as part of the FORM string (WCEM = wide character encoding method), | |
22311 | where @code{x} is one of the following characters | |
22312 | ||
22313 | ||
22314 | @multitable {xxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxx} | |
22315 | @headitem | |
22316 | ||
22317 | Character | |
22318 | ||
22319 | @tab | |
22320 | ||
22321 | Encoding | |
22322 | ||
22323 | @item | |
22324 | ||
1acce141 | 22325 | @emph{h} |
64d5610f ML |
22326 | |
22327 | @tab | |
22328 | ||
22329 | Hex ESC encoding | |
22330 | ||
22331 | @item | |
22332 | ||
1acce141 | 22333 | @emph{u} |
64d5610f ML |
22334 | |
22335 | @tab | |
22336 | ||
22337 | Upper half encoding | |
22338 | ||
22339 | @item | |
22340 | ||
1acce141 | 22341 | @emph{s} |
64d5610f ML |
22342 | |
22343 | @tab | |
22344 | ||
22345 | Shift-JIS encoding | |
22346 | ||
22347 | @item | |
22348 | ||
1acce141 | 22349 | @emph{e} |
64d5610f ML |
22350 | |
22351 | @tab | |
22352 | ||
22353 | EUC Encoding | |
22354 | ||
22355 | @item | |
22356 | ||
1acce141 | 22357 | @emph{8} |
64d5610f ML |
22358 | |
22359 | @tab | |
22360 | ||
22361 | UTF-8 encoding | |
22362 | ||
22363 | @item | |
22364 | ||
1acce141 | 22365 | @emph{b} |
64d5610f ML |
22366 | |
22367 | @tab | |
22368 | ||
22369 | Brackets encoding | |
22370 | ||
22371 | @end multitable | |
22372 | ||
22373 | ||
22374 | The encoding methods match those that | |
22375 | can be used in a source | |
22376 | program, but there is no requirement that the encoding method used for | |
22377 | the source program be the same as the encoding method used for files, | |
22378 | and different files may use different encoding methods. | |
22379 | ||
22380 | The default encoding method for the standard files, and for opened files | |
22381 | for which no WCEM parameter is given in the FORM string matches the | |
22382 | wide character encoding specified for the main program (the default | |
22383 | being brackets encoding if no coding method was specified with -gnatW). | |
22384 | ||
22385 | ||
22386 | @table @asis | |
22387 | ||
1acce141 | 22388 | @item @emph{UTF-8 Coding} |
64d5610f ML |
22389 | |
22390 | A wide character is represented using | |
22391 | UCS Transformation Format 8 (UTF-8) as defined in Annex R of ISO | |
22392 | 10646-1/Am.2. Depending on the character value, the representation | |
22393 | is a one, two, three, or four byte sequence: | |
22394 | @end table | |
22395 | ||
22396 | @example | |
22397 | 16#000000#-16#00007f#: 2#0xxxxxxx# | |
22398 | 16#000080#-16#0007ff#: 2#110xxxxx# 2#10xxxxxx# | |
22399 | 16#000800#-16#00ffff#: 2#1110xxxx# 2#10xxxxxx# 2#10xxxxxx# | |
22400 | 16#010000#-16#10ffff#: 2#11110xxx# 2#10xxxxxx# 2#10xxxxxx# 2#10xxxxxx# | |
22401 | @end example | |
22402 | ||
22403 | ||
22404 | @quotation | |
22405 | ||
22406 | where the @code{xxx} bits correspond to the left-padded bits of the | |
22407 | 21-bit character value. Note that all lower half ASCII characters | |
22408 | are represented as ASCII bytes and all upper half characters and | |
22409 | other wide characters are represented as sequences of upper-half | |
22410 | characters. | |
22411 | @end quotation | |
22412 | ||
22413 | ||
22414 | @table @asis | |
22415 | ||
1acce141 | 22416 | @item @emph{Brackets Coding} |
64d5610f ML |
22417 | |
22418 | In this encoding, a wide wide character is represented by the following eight | |
22419 | character sequence if is in wide character range | |
22420 | @end table | |
22421 | ||
22422 | @example | |
22423 | [ " a b c d " ] | |
22424 | @end example | |
22425 | ||
22426 | ||
22427 | @quotation | |
22428 | ||
22429 | and by the following ten character sequence if not | |
22430 | @end quotation | |
22431 | ||
22432 | @example | |
22433 | [ " a b c d e f " ] | |
22434 | @end example | |
22435 | ||
22436 | ||
22437 | @quotation | |
22438 | ||
22439 | where @code{a}, @code{b}, @code{c}, @code{d}, @code{e}, and @code{f} | |
22440 | are the four or six hexadecimal | |
22441 | characters (using uppercase letters) of the wide wide character code. For | |
22442 | example, @code{["01A345"]} is used to represent the wide wide character | |
22443 | with code @code{16#01A345#}. | |
22444 | ||
22445 | This scheme is compatible with use of the full Wide_Wide_Character set. | |
22446 | On input, brackets coding can also be used for upper half characters, | |
22447 | e.g., @code{["C1"]} for lower case a. However, on output, brackets notation | |
22448 | is only used for wide characters with a code greater than @code{16#FF#}. | |
22449 | @end quotation | |
22450 | ||
22451 | If is also possible to use the other Wide_Character encoding methods, | |
22452 | such as Shift-JIS, but the other schemes cannot support the full range | |
22453 | of wide wide characters. | |
22454 | An attempt to output a character that cannot | |
22455 | be represented using the encoding scheme for the file causes | |
22456 | Constraint_Error to be raised. An invalid wide character sequence on | |
22457 | input also causes Constraint_Error to be raised. | |
22458 | ||
22459 | @menu | |
22460 | * Stream Pointer Positioning: Stream Pointer Positioning<3>. | |
22461 | * Reading and Writing Non-Regular Files: Reading and Writing Non-Regular Files<3>. | |
22462 | ||
22463 | @end menu | |
22464 | ||
22465 | @node Stream Pointer Positioning<3>,Reading and Writing Non-Regular Files<3>,,Wide_Wide_Text_IO | |
9daee425 | 22466 | @anchor{gnat_rm/the_implementation_of_standard_i_o id17}@anchor{2cd}@anchor{gnat_rm/the_implementation_of_standard_i_o stream-pointer-positioning-2}@anchor{2ce} |
64d5610f ML |
22467 | @subsection Stream Pointer Positioning |
22468 | ||
22469 | ||
22470 | @code{Ada.Wide_Wide_Text_IO} is similar to @code{Ada.Text_IO} in its handling | |
9daee425 | 22471 | of stream pointer positioning (@ref{2b8,,Text_IO}). There is one additional |
64d5610f ML |
22472 | case: |
22473 | ||
22474 | If @code{Ada.Wide_Wide_Text_IO.Look_Ahead} reads a character outside the | |
22475 | normal lower ASCII set, i.e. a character in the range: | |
22476 | ||
22477 | @example | |
22478 | Wide_Wide_Character'Val (16#0080#) .. Wide_Wide_Character'Val (16#10FFFF#) | |
22479 | @end example | |
22480 | ||
22481 | then although the logical position of the file pointer is unchanged by | |
22482 | the @code{Look_Ahead} call, the stream is physically positioned past the | |
22483 | wide character sequence. Again this is to avoid the need for buffering | |
22484 | or backup, and all @code{Wide_Wide_Text_IO} routines check the internal | |
22485 | indication that this situation has occurred so that this is not visible | |
22486 | to a normal program using @code{Wide_Wide_Text_IO}. However, this discrepancy | |
22487 | can be observed if the wide text file shares a stream with another file. | |
22488 | ||
22489 | @node Reading and Writing Non-Regular Files<3>,,Stream Pointer Positioning<3>,Wide_Wide_Text_IO | |
9daee425 | 22490 | @anchor{gnat_rm/the_implementation_of_standard_i_o id18}@anchor{2cf}@anchor{gnat_rm/the_implementation_of_standard_i_o reading-and-writing-non-regular-files-2}@anchor{2d0} |
64d5610f ML |
22491 | @subsection Reading and Writing Non-Regular Files |
22492 | ||
22493 | ||
22494 | As in the case of Text_IO, when a non-regular file is read, it is | |
22495 | assumed that the file contains no page marks (any form characters are | |
22496 | treated as data characters), and @code{End_Of_Page} always returns | |
22497 | @code{False}. Similarly, the end of file indication is not sticky, so | |
22498 | it is possible to read beyond an end of file. | |
22499 | ||
22500 | @node Stream_IO,Text Translation,Wide_Wide_Text_IO,The Implementation of Standard I/O | |
9daee425 | 22501 | @anchor{gnat_rm/the_implementation_of_standard_i_o id19}@anchor{2d1}@anchor{gnat_rm/the_implementation_of_standard_i_o stream-io}@anchor{2d2} |
64d5610f ML |
22502 | @section Stream_IO |
22503 | ||
22504 | ||
22505 | A stream file is a sequence of bytes, where individual elements are | |
22506 | written to the file as described in the Ada Reference Manual. The type | |
22507 | @code{Stream_Element} is simply a byte. There are two ways to read or | |
22508 | write a stream file. | |
22509 | ||
22510 | ||
22511 | @itemize * | |
22512 | ||
22513 | @item | |
22514 | The operations @code{Read} and @code{Write} directly read or write a | |
22515 | sequence of stream elements with no control information. | |
22516 | ||
22517 | @item | |
22518 | The stream attributes applied to a stream file transfer data in the | |
22519 | manner described for stream attributes. | |
22520 | @end itemize | |
22521 | ||
22522 | @node Text Translation,Shared Files,Stream_IO,The Implementation of Standard I/O | |
9daee425 | 22523 | @anchor{gnat_rm/the_implementation_of_standard_i_o id20}@anchor{2d3}@anchor{gnat_rm/the_implementation_of_standard_i_o text-translation}@anchor{2d4} |
64d5610f ML |
22524 | @section Text Translation |
22525 | ||
22526 | ||
22527 | @code{Text_Translation=xxx} may be used as the Form parameter | |
22528 | passed to Text_IO.Create and Text_IO.Open. @code{Text_Translation=xxx} | |
22529 | has no effect on Unix systems. Possible values are: | |
22530 | ||
22531 | ||
22532 | @itemize * | |
22533 | ||
22534 | @item | |
22535 | @code{Yes} or @code{Text} is the default, which means to | |
22536 | translate LF to/from CR/LF on Windows systems. | |
22537 | ||
22538 | @code{No} disables this translation; i.e. it | |
22539 | uses binary mode. For output files, @code{Text_Translation=No} | |
22540 | may be used to create Unix-style files on | |
22541 | Windows. | |
22542 | ||
22543 | @item | |
22544 | @code{wtext} translation enabled in Unicode mode. | |
22545 | (corresponds to _O_WTEXT). | |
22546 | ||
22547 | @item | |
22548 | @code{u8text} translation enabled in Unicode UTF-8 mode. | |
22549 | (corresponds to O_U8TEXT). | |
22550 | ||
22551 | @item | |
22552 | @code{u16text} translation enabled in Unicode UTF-16 | |
22553 | mode. (corresponds to_O_U16TEXT). | |
22554 | @end itemize | |
22555 | ||
22556 | @node Shared Files,Filenames encoding,Text Translation,The Implementation of Standard I/O | |
9daee425 | 22557 | @anchor{gnat_rm/the_implementation_of_standard_i_o id21}@anchor{2d5}@anchor{gnat_rm/the_implementation_of_standard_i_o shared-files}@anchor{2d6} |
64d5610f ML |
22558 | @section Shared Files |
22559 | ||
22560 | ||
22561 | Section A.14 of the Ada Reference Manual allows implementations to | |
22562 | provide a wide variety of behavior if an attempt is made to access the | |
22563 | same external file with two or more internal files. | |
22564 | ||
22565 | To provide a full range of functionality, while at the same time | |
22566 | minimizing the problems of portability caused by this implementation | |
22567 | dependence, GNAT handles file sharing as follows: | |
22568 | ||
22569 | ||
22570 | @itemize * | |
22571 | ||
22572 | @item | |
22573 | In the absence of a @code{shared=xxx} form parameter, an attempt | |
22574 | to open two or more files with the same full name is considered an error | |
22575 | and is not supported. The exception @code{Use_Error} will be | |
22576 | raised. Note that a file that is not explicitly closed by the program | |
22577 | remains open until the program terminates. | |
22578 | ||
22579 | @item | |
22580 | If the form parameter @code{shared=no} appears in the form string, the | |
22581 | file can be opened or created with its own separate stream identifier, | |
22582 | regardless of whether other files sharing the same external file are | |
22583 | opened. The exact effect depends on how the C stream routines handle | |
22584 | multiple accesses to the same external files using separate streams. | |
22585 | ||
22586 | @item | |
22587 | If the form parameter @code{shared=yes} appears in the form string for | |
22588 | each of two or more files opened using the same full name, the same | |
22589 | stream is shared between these files, and the semantics are as described | |
22590 | in Ada Reference Manual, Section A.14. | |
22591 | @end itemize | |
22592 | ||
22593 | When a program that opens multiple files with the same name is ported | |
22594 | from another Ada compiler to GNAT, the effect will be that | |
22595 | @code{Use_Error} is raised. | |
22596 | ||
22597 | The documentation of the original compiler and the documentation of the | |
22598 | program should then be examined to determine if file sharing was | |
22599 | expected, and @code{shared=xxx} parameters added to @code{Open} | |
22600 | and @code{Create} calls as required. | |
22601 | ||
22602 | When a program is ported from GNAT to some other Ada compiler, no | |
22603 | special attention is required unless the @code{shared=xxx} form | |
22604 | parameter is used in the program. In this case, you must examine the | |
22605 | documentation of the new compiler to see if it supports the required | |
22606 | file sharing semantics, and form strings modified appropriately. Of | |
22607 | course it may be the case that the program cannot be ported if the | |
22608 | target compiler does not support the required functionality. The best | |
22609 | approach in writing portable code is to avoid file sharing (and hence | |
22610 | the use of the @code{shared=xxx} parameter in the form string) | |
22611 | completely. | |
22612 | ||
22613 | One common use of file sharing in Ada 83 is the use of instantiations of | |
22614 | Sequential_IO on the same file with different types, to achieve | |
22615 | heterogeneous input-output. Although this approach will work in GNAT if | |
22616 | @code{shared=yes} is specified, it is preferable in Ada to use Stream_IO | |
22617 | for this purpose (using the stream attributes) | |
22618 | ||
22619 | @node Filenames encoding,File content encoding,Shared Files,The Implementation of Standard I/O | |
9daee425 | 22620 | @anchor{gnat_rm/the_implementation_of_standard_i_o filenames-encoding}@anchor{2d7}@anchor{gnat_rm/the_implementation_of_standard_i_o id22}@anchor{2d8} |
64d5610f ML |
22621 | @section Filenames encoding |
22622 | ||
22623 | ||
22624 | An encoding form parameter can be used to specify the filename | |
22625 | encoding @code{encoding=xxx}. | |
22626 | ||
22627 | ||
22628 | @itemize * | |
22629 | ||
22630 | @item | |
22631 | If the form parameter @code{encoding=utf8} appears in the form string, the | |
22632 | filename must be encoded in UTF-8. | |
22633 | ||
22634 | @item | |
22635 | If the form parameter @code{encoding=8bits} appears in the form | |
22636 | string, the filename must be a standard 8bits string. | |
22637 | @end itemize | |
22638 | ||
22639 | In the absence of a @code{encoding=xxx} form parameter, the | |
22640 | encoding is controlled by the @code{GNAT_CODE_PAGE} environment | |
22641 | variable. And if not set @code{utf8} is assumed. | |
22642 | ||
22643 | ||
22644 | @table @asis | |
22645 | ||
1acce141 | 22646 | @item @emph{CP_ACP} |
64d5610f ML |
22647 | |
22648 | The current system Windows ANSI code page. | |
22649 | ||
1acce141 | 22650 | @item @emph{CP_UTF8} |
64d5610f ML |
22651 | |
22652 | UTF-8 encoding | |
22653 | @end table | |
22654 | ||
22655 | This encoding form parameter is only supported on the Windows | |
22656 | platform. On the other Operating Systems the run-time is supporting | |
22657 | UTF-8 natively. | |
22658 | ||
22659 | @node File content encoding,Open Modes,Filenames encoding,The Implementation of Standard I/O | |
9daee425 | 22660 | @anchor{gnat_rm/the_implementation_of_standard_i_o file-content-encoding}@anchor{2d9}@anchor{gnat_rm/the_implementation_of_standard_i_o id23}@anchor{2da} |
64d5610f ML |
22661 | @section File content encoding |
22662 | ||
22663 | ||
22664 | For text files it is possible to specify the encoding to use. This is | |
22665 | controlled by the by the @code{GNAT_CCS_ENCODING} environment | |
22666 | variable. And if not set @code{TEXT} is assumed. | |
22667 | ||
22668 | The possible values are those supported on Windows: | |
22669 | ||
22670 | ||
22671 | @table @asis | |
22672 | ||
1acce141 | 22673 | @item @emph{TEXT} |
64d5610f ML |
22674 | |
22675 | Translated text mode | |
22676 | ||
1acce141 | 22677 | @item @emph{WTEXT} |
64d5610f ML |
22678 | |
22679 | Translated unicode encoding | |
22680 | ||
1acce141 | 22681 | @item @emph{U16TEXT} |
64d5610f ML |
22682 | |
22683 | Unicode 16-bit encoding | |
22684 | ||
1acce141 | 22685 | @item @emph{U8TEXT} |
64d5610f ML |
22686 | |
22687 | Unicode 8-bit encoding | |
22688 | @end table | |
22689 | ||
22690 | This encoding is only supported on the Windows platform. | |
22691 | ||
22692 | @node Open Modes,Operations on C Streams,File content encoding,The Implementation of Standard I/O | |
9daee425 | 22693 | @anchor{gnat_rm/the_implementation_of_standard_i_o id24}@anchor{2db}@anchor{gnat_rm/the_implementation_of_standard_i_o open-modes}@anchor{2dc} |
64d5610f ML |
22694 | @section Open Modes |
22695 | ||
22696 | ||
22697 | @code{Open} and @code{Create} calls result in a call to @code{fopen} | |
22698 | using the mode shown in the following table: | |
22699 | ||
22700 | ||
22701 | @multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxx} | |
22702 | @headitem | |
22703 | ||
22704 | @code{Open} and @code{Create} Call Modes | |
22705 | ||
22706 | @tab | |
22707 | ||
22708 | @tab | |
22709 | ||
22710 | @item | |
22711 | ||
22712 | @tab | |
22713 | ||
1acce141 | 22714 | @strong{OPEN} |
64d5610f ML |
22715 | |
22716 | @tab | |
22717 | ||
1acce141 | 22718 | @strong{CREATE} |
64d5610f ML |
22719 | |
22720 | @item | |
22721 | ||
22722 | Append_File | |
22723 | ||
22724 | @tab | |
22725 | ||
22726 | “r+” | |
22727 | ||
22728 | @tab | |
22729 | ||
22730 | “w+” | |
22731 | ||
22732 | @item | |
22733 | ||
22734 | In_File | |
22735 | ||
22736 | @tab | |
22737 | ||
22738 | “r” | |
22739 | ||
22740 | @tab | |
22741 | ||
22742 | “w+” | |
22743 | ||
22744 | @item | |
22745 | ||
22746 | Out_File (Direct_IO) | |
22747 | ||
22748 | @tab | |
22749 | ||
22750 | “r+” | |
22751 | ||
22752 | @tab | |
22753 | ||
22754 | “w” | |
22755 | ||
22756 | @item | |
22757 | ||
22758 | Out_File (all other cases) | |
22759 | ||
22760 | @tab | |
22761 | ||
22762 | “w” | |
22763 | ||
22764 | @tab | |
22765 | ||
22766 | “w” | |
22767 | ||
22768 | @item | |
22769 | ||
22770 | Inout_File | |
22771 | ||
22772 | @tab | |
22773 | ||
22774 | “r+” | |
22775 | ||
22776 | @tab | |
22777 | ||
22778 | “w+” | |
22779 | ||
22780 | @end multitable | |
22781 | ||
22782 | ||
22783 | If text file translation is required, then either @code{b} or @code{t} | |
22784 | is added to the mode, depending on the setting of Text. Text file | |
22785 | translation refers to the mapping of CR/LF sequences in an external file | |
22786 | to LF characters internally. This mapping only occurs in DOS and | |
22787 | DOS-like systems, and is not relevant to other systems. | |
22788 | ||
22789 | A special case occurs with Stream_IO. As shown in the above table, the | |
22790 | file is initially opened in @code{r} or @code{w} mode for the | |
22791 | @code{In_File} and @code{Out_File} cases. If a @code{Set_Mode} operation | |
22792 | subsequently requires switching from reading to writing or vice-versa, | |
22793 | then the file is reopened in @code{r+} mode to permit the required operation. | |
22794 | ||
22795 | @node Operations on C Streams,Interfacing to C Streams,Open Modes,The Implementation of Standard I/O | |
9daee425 | 22796 | @anchor{gnat_rm/the_implementation_of_standard_i_o id25}@anchor{2dd}@anchor{gnat_rm/the_implementation_of_standard_i_o operations-on-c-streams}@anchor{2de} |
64d5610f ML |
22797 | @section Operations on C Streams |
22798 | ||
22799 | ||
22800 | The package @code{Interfaces.C_Streams} provides an Ada program with direct | |
22801 | access to the C library functions for operations on C streams: | |
22802 | ||
22803 | @example | |
22804 | package Interfaces.C_Streams is | |
22805 | -- Note: the reason we do not use the types that are in | |
22806 | -- Interfaces.C is that we want to avoid dragging in the | |
22807 | -- code in this unit if possible. | |
22808 | subtype chars is System.Address; | |
22809 | -- Pointer to null-terminated array of characters | |
22810 | subtype FILEs is System.Address; | |
22811 | -- Corresponds to the C type FILE* | |
22812 | subtype voids is System.Address; | |
22813 | -- Corresponds to the C type void* | |
22814 | subtype int is Integer; | |
22815 | subtype long is Long_Integer; | |
22816 | -- Note: the above types are subtypes deliberately, and it | |
22817 | -- is part of this spec that the above correspondences are | |
22818 | -- guaranteed. This means that it is legitimate to, for | |
22819 | -- example, use Integer instead of int. We provide these | |
22820 | -- synonyms for clarity, but in some cases it may be | |
22821 | -- convenient to use the underlying types (for example to | |
22822 | -- avoid an unnecessary dependency of a spec on the spec | |
22823 | -- of this unit). | |
22824 | type size_t is mod 2 ** Standard'Address_Size; | |
22825 | NULL_Stream : constant FILEs; | |
22826 | -- Value returned (NULL in C) to indicate an | |
22827 | -- fdopen/fopen/tmpfile error | |
22828 | ---------------------------------- | |
22829 | -- Constants Defined in stdio.h -- | |
22830 | ---------------------------------- | |
22831 | EOF : constant int; | |
22832 | -- Used by a number of routines to indicate error or | |
22833 | -- end of file | |
22834 | IOFBF : constant int; | |
22835 | IOLBF : constant int; | |
22836 | IONBF : constant int; | |
22837 | -- Used to indicate buffering mode for setvbuf call | |
22838 | SEEK_CUR : constant int; | |
22839 | SEEK_END : constant int; | |
22840 | SEEK_SET : constant int; | |
22841 | -- Used to indicate origin for fseek call | |
22842 | function stdin return FILEs; | |
22843 | function stdout return FILEs; | |
22844 | function stderr return FILEs; | |
22845 | -- Streams associated with standard files | |
22846 | -------------------------- | |
22847 | -- Standard C functions -- | |
22848 | -------------------------- | |
22849 | -- The functions selected below are ones that are | |
22850 | -- available in UNIX (but not necessarily in ANSI C). | |
22851 | -- These are very thin interfaces | |
22852 | -- which copy exactly the C headers. For more | |
22853 | -- documentation on these functions, see the Microsoft C | |
22854 | -- "Run-Time Library Reference" (Microsoft Press, 1990, | |
22855 | -- ISBN 1-55615-225-6), which includes useful information | |
22856 | -- on system compatibility. | |
22857 | procedure clearerr (stream : FILEs); | |
22858 | function fclose (stream : FILEs) return int; | |
22859 | function fdopen (handle : int; mode : chars) return FILEs; | |
22860 | function feof (stream : FILEs) return int; | |
22861 | function ferror (stream : FILEs) return int; | |
22862 | function fflush (stream : FILEs) return int; | |
22863 | function fgetc (stream : FILEs) return int; | |
22864 | function fgets (strng : chars; n : int; stream : FILEs) | |
22865 | return chars; | |
22866 | function fileno (stream : FILEs) return int; | |
22867 | function fopen (filename : chars; Mode : chars) | |
22868 | return FILEs; | |
22869 | -- Note: to maintain target independence, use | |
22870 | -- text_translation_required, a boolean variable defined in | |
22871 | -- a-sysdep.c to deal with the target dependent text | |
22872 | -- translation requirement. If this variable is set, | |
22873 | -- then b/t should be appended to the standard mode | |
22874 | -- argument to set the text translation mode off or on | |
22875 | -- as required. | |
22876 | function fputc (C : int; stream : FILEs) return int; | |
22877 | function fputs (Strng : chars; Stream : FILEs) return int; | |
22878 | function fread | |
22879 | (buffer : voids; | |
22880 | size : size_t; | |
22881 | count : size_t; | |
22882 | stream : FILEs) | |
22883 | return size_t; | |
22884 | function freopen | |
22885 | (filename : chars; | |
22886 | mode : chars; | |
22887 | stream : FILEs) | |
22888 | return FILEs; | |
22889 | function fseek | |
22890 | (stream : FILEs; | |
22891 | offset : long; | |
22892 | origin : int) | |
22893 | return int; | |
22894 | function ftell (stream : FILEs) return long; | |
22895 | function fwrite | |
22896 | (buffer : voids; | |
22897 | size : size_t; | |
22898 | count : size_t; | |
22899 | stream : FILEs) | |
22900 | return size_t; | |
22901 | function isatty (handle : int) return int; | |
22902 | procedure mktemp (template : chars); | |
22903 | -- The return value (which is just a pointer to template) | |
22904 | -- is discarded | |
22905 | procedure rewind (stream : FILEs); | |
22906 | function rmtmp return int; | |
22907 | function setvbuf | |
22908 | (stream : FILEs; | |
22909 | buffer : chars; | |
22910 | mode : int; | |
22911 | size : size_t) | |
22912 | return int; | |
22913 | ||
22914 | function tmpfile return FILEs; | |
22915 | function ungetc (c : int; stream : FILEs) return int; | |
22916 | function unlink (filename : chars) return int; | |
22917 | --------------------- | |
22918 | -- Extra functions -- | |
22919 | --------------------- | |
22920 | -- These functions supply slightly thicker bindings than | |
22921 | -- those above. They are derived from functions in the | |
22922 | -- C Run-Time Library, but may do a bit more work than | |
22923 | -- just directly calling one of the Library functions. | |
22924 | function is_regular_file (handle : int) return int; | |
22925 | -- Tests if given handle is for a regular file (result 1) | |
22926 | -- or for a non-regular file (pipe or device, result 0). | |
22927 | --------------------------------- | |
22928 | -- Control of Text/Binary Mode -- | |
22929 | --------------------------------- | |
22930 | -- If text_translation_required is true, then the following | |
22931 | -- functions may be used to dynamically switch a file from | |
22932 | -- binary to text mode or vice versa. These functions have | |
22933 | -- no effect if text_translation_required is false (i.e., in | |
22934 | -- normal UNIX mode). Use fileno to get a stream handle. | |
22935 | procedure set_binary_mode (handle : int); | |
22936 | procedure set_text_mode (handle : int); | |
22937 | ---------------------------- | |
22938 | -- Full Path Name support -- | |
22939 | ---------------------------- | |
22940 | procedure full_name (nam : chars; buffer : chars); | |
22941 | -- Given a NUL terminated string representing a file | |
22942 | -- name, returns in buffer a NUL terminated string | |
22943 | -- representing the full path name for the file name. | |
22944 | -- On systems where it is relevant the drive is also | |
22945 | -- part of the full path name. It is the responsibility | |
22946 | -- of the caller to pass an actual parameter for buffer | |
22947 | -- that is big enough for any full path name. Use | |
22948 | -- max_path_len given below as the size of buffer. | |
22949 | max_path_len : integer; | |
22950 | -- Maximum length of an allowable full path name on the | |
22951 | -- system, including a terminating NUL character. | |
22952 | end Interfaces.C_Streams; | |
22953 | @end example | |
22954 | ||
22955 | @node Interfacing to C Streams,,Operations on C Streams,The Implementation of Standard I/O | |
9daee425 | 22956 | @anchor{gnat_rm/the_implementation_of_standard_i_o id26}@anchor{2df}@anchor{gnat_rm/the_implementation_of_standard_i_o interfacing-to-c-streams}@anchor{2e0} |
64d5610f ML |
22957 | @section Interfacing to C Streams |
22958 | ||
22959 | ||
22960 | The packages in this section permit interfacing Ada files to C Stream | |
22961 | operations. | |
22962 | ||
22963 | @example | |
22964 | with Interfaces.C_Streams; | |
22965 | package Ada.Sequential_IO.C_Streams is | |
22966 | function C_Stream (F : File_Type) | |
22967 | return Interfaces.C_Streams.FILEs; | |
22968 | procedure Open | |
22969 | (File : in out File_Type; | |
22970 | Mode : in File_Mode; | |
22971 | C_Stream : in Interfaces.C_Streams.FILEs; | |
22972 | Form : in String := ""); | |
22973 | end Ada.Sequential_IO.C_Streams; | |
22974 | ||
22975 | with Interfaces.C_Streams; | |
22976 | package Ada.Direct_IO.C_Streams is | |
22977 | function C_Stream (F : File_Type) | |
22978 | return Interfaces.C_Streams.FILEs; | |
22979 | procedure Open | |
22980 | (File : in out File_Type; | |
22981 | Mode : in File_Mode; | |
22982 | C_Stream : in Interfaces.C_Streams.FILEs; | |
22983 | Form : in String := ""); | |
22984 | end Ada.Direct_IO.C_Streams; | |
22985 | ||
22986 | with Interfaces.C_Streams; | |
22987 | package Ada.Text_IO.C_Streams is | |
22988 | function C_Stream (F : File_Type) | |
22989 | return Interfaces.C_Streams.FILEs; | |
22990 | procedure Open | |
22991 | (File : in out File_Type; | |
22992 | Mode : in File_Mode; | |
22993 | C_Stream : in Interfaces.C_Streams.FILEs; | |
22994 | Form : in String := ""); | |
22995 | end Ada.Text_IO.C_Streams; | |
22996 | ||
22997 | with Interfaces.C_Streams; | |
22998 | package Ada.Wide_Text_IO.C_Streams is | |
22999 | function C_Stream (F : File_Type) | |
23000 | return Interfaces.C_Streams.FILEs; | |
23001 | procedure Open | |
23002 | (File : in out File_Type; | |
23003 | Mode : in File_Mode; | |
23004 | C_Stream : in Interfaces.C_Streams.FILEs; | |
23005 | Form : in String := ""); | |
23006 | end Ada.Wide_Text_IO.C_Streams; | |
23007 | ||
23008 | with Interfaces.C_Streams; | |
23009 | package Ada.Wide_Wide_Text_IO.C_Streams is | |
23010 | function C_Stream (F : File_Type) | |
23011 | return Interfaces.C_Streams.FILEs; | |
23012 | procedure Open | |
23013 | (File : in out File_Type; | |
23014 | Mode : in File_Mode; | |
23015 | C_Stream : in Interfaces.C_Streams.FILEs; | |
23016 | Form : in String := ""); | |
23017 | end Ada.Wide_Wide_Text_IO.C_Streams; | |
23018 | ||
23019 | with Interfaces.C_Streams; | |
23020 | package Ada.Stream_IO.C_Streams is | |
23021 | function C_Stream (F : File_Type) | |
23022 | return Interfaces.C_Streams.FILEs; | |
23023 | procedure Open | |
23024 | (File : in out File_Type; | |
23025 | Mode : in File_Mode; | |
23026 | C_Stream : in Interfaces.C_Streams.FILEs; | |
23027 | Form : in String := ""); | |
23028 | end Ada.Stream_IO.C_Streams; | |
23029 | @end example | |
23030 | ||
23031 | In each of these six packages, the @code{C_Stream} function obtains the | |
23032 | @code{FILE} pointer from a currently opened Ada file. It is then | |
23033 | possible to use the @code{Interfaces.C_Streams} package to operate on | |
23034 | this stream, or the stream can be passed to a C program which can | |
23035 | operate on it directly. Of course the program is responsible for | |
23036 | ensuring that only appropriate sequences of operations are executed. | |
23037 | ||
23038 | One particular use of relevance to an Ada program is that the | |
23039 | @code{setvbuf} function can be used to control the buffering of the | |
23040 | stream used by an Ada file. In the absence of such a call the standard | |
23041 | default buffering is used. | |
23042 | ||
23043 | The @code{Open} procedures in these packages open a file giving an | |
23044 | existing C Stream instead of a file name. Typically this stream is | |
23045 | imported from a C program, allowing an Ada file to operate on an | |
23046 | existing C file. | |
23047 | ||
23048 | @node The GNAT Library,Interfacing to Other Languages,The Implementation of Standard I/O,Top | |
9daee425 | 23049 | @anchor{gnat_rm/the_gnat_library doc}@anchor{2e1}@anchor{gnat_rm/the_gnat_library id1}@anchor{2e2}@anchor{gnat_rm/the_gnat_library the-gnat-library}@anchor{10} |
64d5610f ML |
23050 | @chapter The GNAT Library |
23051 | ||
23052 | ||
23053 | The GNAT library contains a number of general and special purpose packages. | |
23054 | It represents functionality that the GNAT developers have found useful, and | |
23055 | which is made available to GNAT users. The packages described here are fully | |
23056 | supported, and upwards compatibility will be maintained in future releases, | |
23057 | so you can use these facilities with the confidence that the same functionality | |
23058 | will be available in future releases. | |
23059 | ||
23060 | The chapter here simply gives a brief summary of the facilities available. | |
23061 | The full documentation is found in the spec file for the package. The full | |
23062 | sources of these library packages, including both spec and body, are provided | |
23063 | with all GNAT releases. For example, to find out the full specifications of | |
23064 | the SPITBOL pattern matching capability, including a full tutorial and | |
23065 | extensive examples, look in the @code{g-spipat.ads} file in the library. | |
23066 | ||
23067 | For each entry here, the package name (as it would appear in a @code{with} | |
23068 | clause) is given, followed by the name of the corresponding spec file in | |
23069 | parentheses. The packages are children in four hierarchies, @code{Ada}, | |
23070 | @code{Interfaces}, @code{System}, and @code{GNAT}, the latter being a | |
23071 | GNAT-specific hierarchy. | |
23072 | ||
23073 | Note that an application program should only use packages in one of these | |
23074 | four hierarchies if the package is defined in the Ada Reference Manual, | |
23075 | or is listed in this section of the GNAT Programmers Reference Manual. | |
23076 | All other units should be considered internal implementation units and | |
23077 | should not be directly @code{with}ed by application code. The use of | |
23078 | a @code{with} clause that references one of these internal implementation | |
23079 | units makes an application potentially dependent on changes in versions | |
23080 | of GNAT, and will generate a warning message. | |
23081 | ||
23082 | @menu | |
23083 | * Ada.Characters.Latin_9 (a-chlat9.ads): Ada Characters Latin_9 a-chlat9 ads. | |
23084 | * Ada.Characters.Wide_Latin_1 (a-cwila1.ads): Ada Characters Wide_Latin_1 a-cwila1 ads. | |
eeba836b | 23085 | * Ada.Characters.Wide_Latin_9 (a-cwila9.ads): Ada Characters Wide_Latin_9 a-cwila9 ads. |
64d5610f ML |
23086 | * Ada.Characters.Wide_Wide_Latin_1 (a-chzla1.ads): Ada Characters Wide_Wide_Latin_1 a-chzla1 ads. |
23087 | * Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads): Ada Characters Wide_Wide_Latin_9 a-chzla9 ads. | |
23088 | * Ada.Containers.Bounded_Holders (a-coboho.ads): Ada Containers Bounded_Holders a-coboho ads. | |
23089 | * Ada.Command_Line.Environment (a-colien.ads): Ada Command_Line Environment a-colien ads. | |
23090 | * Ada.Command_Line.Remove (a-colire.ads): Ada Command_Line Remove a-colire ads. | |
23091 | * Ada.Command_Line.Response_File (a-clrefi.ads): Ada Command_Line Response_File a-clrefi ads. | |
23092 | * Ada.Direct_IO.C_Streams (a-diocst.ads): Ada Direct_IO C_Streams a-diocst ads. | |
23093 | * Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads): Ada Exceptions Is_Null_Occurrence a-einuoc ads. | |
23094 | * Ada.Exceptions.Last_Chance_Handler (a-elchha.ads): Ada Exceptions Last_Chance_Handler a-elchha ads. | |
23095 | * Ada.Exceptions.Traceback (a-exctra.ads): Ada Exceptions Traceback a-exctra ads. | |
23096 | * Ada.Sequential_IO.C_Streams (a-siocst.ads): Ada Sequential_IO C_Streams a-siocst ads. | |
23097 | * Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads): Ada Streams Stream_IO C_Streams a-ssicst ads. | |
23098 | * Ada.Strings.Unbounded.Text_IO (a-suteio.ads): Ada Strings Unbounded Text_IO a-suteio ads. | |
23099 | * Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads): Ada Strings Wide_Unbounded Wide_Text_IO a-swuwti ads. | |
23100 | * Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads): Ada Strings Wide_Wide_Unbounded Wide_Wide_Text_IO a-szuzti ads. | |
23101 | * Ada.Task_Initialization (a-tasini.ads): Ada Task_Initialization a-tasini ads. | |
23102 | * Ada.Text_IO.C_Streams (a-tiocst.ads): Ada Text_IO C_Streams a-tiocst ads. | |
23103 | * Ada.Text_IO.Reset_Standard_Files (a-tirsfi.ads): Ada Text_IO Reset_Standard_Files a-tirsfi ads. | |
23104 | * Ada.Wide_Characters.Unicode (a-wichun.ads): Ada Wide_Characters Unicode a-wichun ads. | |
23105 | * Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads): Ada Wide_Text_IO C_Streams a-wtcstr ads. | |
23106 | * Ada.Wide_Text_IO.Reset_Standard_Files (a-wrstfi.ads): Ada Wide_Text_IO Reset_Standard_Files a-wrstfi ads. | |
23107 | * Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads): Ada Wide_Wide_Characters Unicode a-zchuni ads. | |
23108 | * Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads): Ada Wide_Wide_Text_IO C_Streams a-ztcstr ads. | |
23109 | * Ada.Wide_Wide_Text_IO.Reset_Standard_Files (a-zrstfi.ads): Ada Wide_Wide_Text_IO Reset_Standard_Files a-zrstfi ads. | |
23110 | * GNAT.Altivec (g-altive.ads): GNAT Altivec g-altive ads. | |
23111 | * GNAT.Altivec.Conversions (g-altcon.ads): GNAT Altivec Conversions g-altcon ads. | |
23112 | * GNAT.Altivec.Vector_Operations (g-alveop.ads): GNAT Altivec Vector_Operations g-alveop ads. | |
23113 | * GNAT.Altivec.Vector_Types (g-alvety.ads): GNAT Altivec Vector_Types g-alvety ads. | |
23114 | * GNAT.Altivec.Vector_Views (g-alvevi.ads): GNAT Altivec Vector_Views g-alvevi ads. | |
23115 | * GNAT.Array_Split (g-arrspl.ads): GNAT Array_Split g-arrspl ads. | |
23116 | * GNAT.AWK (g-awk.ads): GNAT AWK g-awk ads. | |
23117 | * GNAT.Binary_Search (g-binsea.ads): GNAT Binary_Search g-binsea ads. | |
23118 | * GNAT.Bind_Environment (g-binenv.ads): GNAT Bind_Environment g-binenv ads. | |
23119 | * GNAT.Branch_Prediction (g-brapre.ads): GNAT Branch_Prediction g-brapre ads. | |
23120 | * GNAT.Bounded_Buffers (g-boubuf.ads): GNAT Bounded_Buffers g-boubuf ads. | |
23121 | * GNAT.Bounded_Mailboxes (g-boumai.ads): GNAT Bounded_Mailboxes g-boumai ads. | |
23122 | * GNAT.Bubble_Sort (g-bubsor.ads): GNAT Bubble_Sort g-bubsor ads. | |
23123 | * GNAT.Bubble_Sort_A (g-busora.ads): GNAT Bubble_Sort_A g-busora ads. | |
23124 | * GNAT.Bubble_Sort_G (g-busorg.ads): GNAT Bubble_Sort_G g-busorg ads. | |
23125 | * GNAT.Byte_Order_Mark (g-byorma.ads): GNAT Byte_Order_Mark g-byorma ads. | |
23126 | * GNAT.Byte_Swapping (g-bytswa.ads): GNAT Byte_Swapping g-bytswa ads. | |
23127 | * GNAT.Calendar (g-calend.ads): GNAT Calendar g-calend ads. | |
23128 | * GNAT.Calendar.Time_IO (g-catiio.ads): GNAT Calendar Time_IO g-catiio ads. | |
23129 | * GNAT.CRC32 (g-crc32.ads): GNAT CRC32 g-crc32 ads. | |
23130 | * GNAT.Case_Util (g-casuti.ads): GNAT Case_Util g-casuti ads. | |
23131 | * GNAT.CGI (g-cgi.ads): GNAT CGI g-cgi ads. | |
23132 | * GNAT.CGI.Cookie (g-cgicoo.ads): GNAT CGI Cookie g-cgicoo ads. | |
23133 | * GNAT.CGI.Debug (g-cgideb.ads): GNAT CGI Debug g-cgideb ads. | |
23134 | * GNAT.Command_Line (g-comlin.ads): GNAT Command_Line g-comlin ads. | |
23135 | * GNAT.Compiler_Version (g-comver.ads): GNAT Compiler_Version g-comver ads. | |
23136 | * GNAT.Ctrl_C (g-ctrl_c.ads): GNAT Ctrl_C g-ctrl_c ads. | |
23137 | * GNAT.Current_Exception (g-curexc.ads): GNAT Current_Exception g-curexc ads. | |
23138 | * GNAT.Debug_Pools (g-debpoo.ads): GNAT Debug_Pools g-debpoo ads. | |
23139 | * GNAT.Debug_Utilities (g-debuti.ads): GNAT Debug_Utilities g-debuti ads. | |
23140 | * GNAT.Decode_String (g-decstr.ads): GNAT Decode_String g-decstr ads. | |
23141 | * GNAT.Decode_UTF8_String (g-deutst.ads): GNAT Decode_UTF8_String g-deutst ads. | |
23142 | * GNAT.Directory_Operations (g-dirope.ads): GNAT Directory_Operations g-dirope ads. | |
23143 | * GNAT.Directory_Operations.Iteration (g-diopit.ads): GNAT Directory_Operations Iteration g-diopit ads. | |
23144 | * GNAT.Dynamic_HTables (g-dynhta.ads): GNAT Dynamic_HTables g-dynhta ads. | |
23145 | * GNAT.Dynamic_Tables (g-dyntab.ads): GNAT Dynamic_Tables g-dyntab ads. | |
23146 | * GNAT.Encode_String (g-encstr.ads): GNAT Encode_String g-encstr ads. | |
23147 | * GNAT.Encode_UTF8_String (g-enutst.ads): GNAT Encode_UTF8_String g-enutst ads. | |
23148 | * GNAT.Exception_Actions (g-excact.ads): GNAT Exception_Actions g-excact ads. | |
23149 | * GNAT.Exception_Traces (g-exctra.ads): GNAT Exception_Traces g-exctra ads. | |
23150 | * GNAT.Exceptions (g-except.ads): GNAT Exceptions g-except ads. | |
23151 | * GNAT.Expect (g-expect.ads): GNAT Expect g-expect ads. | |
23152 | * GNAT.Expect.TTY (g-exptty.ads): GNAT Expect TTY g-exptty ads. | |
23153 | * GNAT.Float_Control (g-flocon.ads): GNAT Float_Control g-flocon ads. | |
23154 | * GNAT.Formatted_String (g-forstr.ads): GNAT Formatted_String g-forstr ads. | |
23155 | * GNAT.Generic_Fast_Math_Functions (g-gfmafu.ads): GNAT Generic_Fast_Math_Functions g-gfmafu ads. | |
23156 | * GNAT.Heap_Sort (g-heasor.ads): GNAT Heap_Sort g-heasor ads. | |
23157 | * GNAT.Heap_Sort_A (g-hesora.ads): GNAT Heap_Sort_A g-hesora ads. | |
23158 | * GNAT.Heap_Sort_G (g-hesorg.ads): GNAT Heap_Sort_G g-hesorg ads. | |
23159 | * GNAT.HTable (g-htable.ads): GNAT HTable g-htable ads. | |
23160 | * GNAT.IO (g-io.ads): GNAT IO g-io ads. | |
23161 | * GNAT.IO_Aux (g-io_aux.ads): GNAT IO_Aux g-io_aux ads. | |
23162 | * GNAT.Lock_Files (g-locfil.ads): GNAT Lock_Files g-locfil ads. | |
23163 | * GNAT.MBBS_Discrete_Random (g-mbdira.ads): GNAT MBBS_Discrete_Random g-mbdira ads. | |
23164 | * GNAT.MBBS_Float_Random (g-mbflra.ads): GNAT MBBS_Float_Random g-mbflra ads. | |
23165 | * GNAT.MD5 (g-md5.ads): GNAT MD5 g-md5 ads. | |
23166 | * GNAT.Memory_Dump (g-memdum.ads): GNAT Memory_Dump g-memdum ads. | |
23167 | * GNAT.Most_Recent_Exception (g-moreex.ads): GNAT Most_Recent_Exception g-moreex ads. | |
23168 | * GNAT.OS_Lib (g-os_lib.ads): GNAT OS_Lib g-os_lib ads. | |
23169 | * GNAT.Perfect_Hash_Generators (g-pehage.ads): GNAT Perfect_Hash_Generators g-pehage ads. | |
23170 | * GNAT.Random_Numbers (g-rannum.ads): GNAT Random_Numbers g-rannum ads. | |
23171 | * GNAT.Regexp (g-regexp.ads): GNAT Regexp g-regexp ads. | |
23172 | * GNAT.Registry (g-regist.ads): GNAT Registry g-regist ads. | |
23173 | * GNAT.Regpat (g-regpat.ads): GNAT Regpat g-regpat ads. | |
23174 | * GNAT.Rewrite_Data (g-rewdat.ads): GNAT Rewrite_Data g-rewdat ads. | |
23175 | * GNAT.Secondary_Stack_Info (g-sestin.ads): GNAT Secondary_Stack_Info g-sestin ads. | |
23176 | * GNAT.Semaphores (g-semaph.ads): GNAT Semaphores g-semaph ads. | |
23177 | * GNAT.Serial_Communications (g-sercom.ads): GNAT Serial_Communications g-sercom ads. | |
23178 | * GNAT.SHA1 (g-sha1.ads): GNAT SHA1 g-sha1 ads. | |
23179 | * GNAT.SHA224 (g-sha224.ads): GNAT SHA224 g-sha224 ads. | |
23180 | * GNAT.SHA256 (g-sha256.ads): GNAT SHA256 g-sha256 ads. | |
23181 | * GNAT.SHA384 (g-sha384.ads): GNAT SHA384 g-sha384 ads. | |
23182 | * GNAT.SHA512 (g-sha512.ads): GNAT SHA512 g-sha512 ads. | |
23183 | * GNAT.Signals (g-signal.ads): GNAT Signals g-signal ads. | |
23184 | * GNAT.Sockets (g-socket.ads): GNAT Sockets g-socket ads. | |
23185 | * GNAT.Source_Info (g-souinf.ads): GNAT Source_Info g-souinf ads. | |
23186 | * GNAT.Spelling_Checker (g-speche.ads): GNAT Spelling_Checker g-speche ads. | |
23187 | * GNAT.Spelling_Checker_Generic (g-spchge.ads): GNAT Spelling_Checker_Generic g-spchge ads. | |
23188 | * GNAT.Spitbol.Patterns (g-spipat.ads): GNAT Spitbol Patterns g-spipat ads. | |
23189 | * GNAT.Spitbol (g-spitbo.ads): GNAT Spitbol g-spitbo ads. | |
23190 | * GNAT.Spitbol.Table_Boolean (g-sptabo.ads): GNAT Spitbol Table_Boolean g-sptabo ads. | |
23191 | * GNAT.Spitbol.Table_Integer (g-sptain.ads): GNAT Spitbol Table_Integer g-sptain ads. | |
23192 | * GNAT.Spitbol.Table_VString (g-sptavs.ads): GNAT Spitbol Table_VString g-sptavs ads. | |
23193 | * GNAT.SSE (g-sse.ads): GNAT SSE g-sse ads. | |
23194 | * GNAT.SSE.Vector_Types (g-ssvety.ads): GNAT SSE Vector_Types g-ssvety ads. | |
23195 | * GNAT.String_Hash (g-strhas.ads): GNAT String_Hash g-strhas ads. | |
23196 | * GNAT.Strings (g-string.ads): GNAT Strings g-string ads. | |
23197 | * GNAT.String_Split (g-strspl.ads): GNAT String_Split g-strspl ads. | |
23198 | * GNAT.Table (g-table.ads): GNAT Table g-table ads. | |
23199 | * GNAT.Task_Lock (g-tasloc.ads): GNAT Task_Lock g-tasloc ads. | |
23200 | * GNAT.Time_Stamp (g-timsta.ads): GNAT Time_Stamp g-timsta ads. | |
23201 | * GNAT.Threads (g-thread.ads): GNAT Threads g-thread ads. | |
23202 | * GNAT.Traceback (g-traceb.ads): GNAT Traceback g-traceb ads. | |
23203 | * GNAT.Traceback.Symbolic (g-trasym.ads): GNAT Traceback Symbolic g-trasym ads. | |
eeba836b RD |
23204 | * GNAT.UTF_32 (g-utf_32.ads): GNAT UTF_32 g-utf_32 ads. |
23205 | * GNAT.UTF_32_Spelling_Checker (g-u3spch.ads): GNAT UTF_32_Spelling_Checker g-u3spch ads. | |
64d5610f ML |
23206 | * GNAT.Wide_Spelling_Checker (g-wispch.ads): GNAT Wide_Spelling_Checker g-wispch ads. |
23207 | * GNAT.Wide_String_Split (g-wistsp.ads): GNAT Wide_String_Split g-wistsp ads. | |
23208 | * GNAT.Wide_Wide_Spelling_Checker (g-zspche.ads): GNAT Wide_Wide_Spelling_Checker g-zspche ads. | |
23209 | * GNAT.Wide_Wide_String_Split (g-zistsp.ads): GNAT Wide_Wide_String_Split g-zistsp ads. | |
23210 | * Interfaces.C.Extensions (i-cexten.ads): Interfaces C Extensions i-cexten ads. | |
23211 | * Interfaces.C.Streams (i-cstrea.ads): Interfaces C Streams i-cstrea ads. | |
23212 | * Interfaces.Packed_Decimal (i-pacdec.ads): Interfaces Packed_Decimal i-pacdec ads. | |
23213 | * Interfaces.VxWorks (i-vxwork.ads): Interfaces VxWorks i-vxwork ads. | |
23214 | * Interfaces.VxWorks.Int_Connection (i-vxinco.ads): Interfaces VxWorks Int_Connection i-vxinco ads. | |
23215 | * Interfaces.VxWorks.IO (i-vxwoio.ads): Interfaces VxWorks IO i-vxwoio ads. | |
23216 | * System.Address_Image (s-addima.ads): System Address_Image s-addima ads. | |
23217 | * System.Assertions (s-assert.ads): System Assertions s-assert ads. | |
23218 | * System.Atomic_Counters (s-atocou.ads): System Atomic_Counters s-atocou ads. | |
23219 | * System.Memory (s-memory.ads): System Memory s-memory ads. | |
23220 | * System.Multiprocessors (s-multip.ads): System Multiprocessors s-multip ads. | |
23221 | * System.Multiprocessors.Dispatching_Domains (s-mudido.ads): System Multiprocessors Dispatching_Domains s-mudido ads. | |
23222 | * System.Partition_Interface (s-parint.ads): System Partition_Interface s-parint ads. | |
23223 | * System.Pool_Global (s-pooglo.ads): System Pool_Global s-pooglo ads. | |
23224 | * System.Pool_Local (s-pooloc.ads): System Pool_Local s-pooloc ads. | |
23225 | * System.Restrictions (s-restri.ads): System Restrictions s-restri ads. | |
23226 | * System.Rident (s-rident.ads): System Rident s-rident ads. | |
23227 | * System.Strings.Stream_Ops (s-ststop.ads): System Strings Stream_Ops s-ststop ads. | |
23228 | * System.Unsigned_Types (s-unstyp.ads): System Unsigned_Types s-unstyp ads. | |
23229 | * System.Wch_Cnv (s-wchcnv.ads): System Wch_Cnv s-wchcnv ads. | |
23230 | * System.Wch_Con (s-wchcon.ads): System Wch_Con s-wchcon ads. | |
23231 | ||
23232 | @end menu | |
23233 | ||
23234 | @node Ada Characters Latin_9 a-chlat9 ads,Ada Characters Wide_Latin_1 a-cwila1 ads,,The GNAT Library | |
9daee425 | 23235 | @anchor{gnat_rm/the_gnat_library ada-characters-latin-9-a-chlat9-ads}@anchor{2e3}@anchor{gnat_rm/the_gnat_library id2}@anchor{2e4} |
64d5610f ML |
23236 | @section @code{Ada.Characters.Latin_9} (@code{a-chlat9.ads}) |
23237 | ||
23238 | ||
23239 | @geindex Ada.Characters.Latin_9 (a-chlat9.ads) | |
23240 | ||
23241 | @geindex Latin_9 constants for Character | |
23242 | ||
23243 | This child of @code{Ada.Characters} | |
23244 | provides a set of definitions corresponding to those in the | |
23245 | RM-defined package @code{Ada.Characters.Latin_1} but with the | |
eeba836b | 23246 | few modifications required for @code{Latin-9}. |
64d5610f ML |
23247 | The provision of such a package |
23248 | is specifically authorized by the Ada Reference Manual | |
23249 | (RM A.3.3(27)). | |
23250 | ||
eeba836b | 23251 | @node Ada Characters Wide_Latin_1 a-cwila1 ads,Ada Characters Wide_Latin_9 a-cwila9 ads,Ada Characters Latin_9 a-chlat9 ads,The GNAT Library |
9daee425 | 23252 | @anchor{gnat_rm/the_gnat_library ada-characters-wide-latin-1-a-cwila1-ads}@anchor{2e5}@anchor{gnat_rm/the_gnat_library id3}@anchor{2e6} |
64d5610f ML |
23253 | @section @code{Ada.Characters.Wide_Latin_1} (@code{a-cwila1.ads}) |
23254 | ||
23255 | ||
23256 | @geindex Ada.Characters.Wide_Latin_1 (a-cwila1.ads) | |
23257 | ||
23258 | @geindex Latin_1 constants for Wide_Character | |
23259 | ||
23260 | This child of @code{Ada.Characters} | |
23261 | provides a set of definitions corresponding to those in the | |
23262 | RM-defined package @code{Ada.Characters.Latin_1} but with the | |
23263 | types of the constants being @code{Wide_Character} | |
23264 | instead of @code{Character}. The provision of such a package | |
23265 | is specifically authorized by the Ada Reference Manual | |
23266 | (RM A.3.3(27)). | |
23267 | ||
eeba836b | 23268 | @node Ada Characters Wide_Latin_9 a-cwila9 ads,Ada Characters Wide_Wide_Latin_1 a-chzla1 ads,Ada Characters Wide_Latin_1 a-cwila1 ads,The GNAT Library |
9daee425 | 23269 | @anchor{gnat_rm/the_gnat_library ada-characters-wide-latin-9-a-cwila9-ads}@anchor{2e7}@anchor{gnat_rm/the_gnat_library id4}@anchor{2e8} |
eeba836b | 23270 | @section @code{Ada.Characters.Wide_Latin_9} (@code{a-cwila9.ads}) |
64d5610f ML |
23271 | |
23272 | ||
eeba836b | 23273 | @geindex Ada.Characters.Wide_Latin_9 (a-cwila9.ads) |
64d5610f ML |
23274 | |
23275 | @geindex Latin_9 constants for Wide_Character | |
23276 | ||
23277 | This child of @code{Ada.Characters} | |
23278 | provides a set of definitions corresponding to those in the | |
23279 | GNAT defined package @code{Ada.Characters.Latin_9} but with the | |
23280 | types of the constants being @code{Wide_Character} | |
23281 | instead of @code{Character}. The provision of such a package | |
23282 | is specifically authorized by the Ada Reference Manual | |
23283 | (RM A.3.3(27)). | |
23284 | ||
eeba836b | 23285 | @node Ada Characters Wide_Wide_Latin_1 a-chzla1 ads,Ada Characters Wide_Wide_Latin_9 a-chzla9 ads,Ada Characters Wide_Latin_9 a-cwila9 ads,The GNAT Library |
9daee425 | 23286 | @anchor{gnat_rm/the_gnat_library ada-characters-wide-wide-latin-1-a-chzla1-ads}@anchor{2e9}@anchor{gnat_rm/the_gnat_library id5}@anchor{2ea} |
64d5610f ML |
23287 | @section @code{Ada.Characters.Wide_Wide_Latin_1} (@code{a-chzla1.ads}) |
23288 | ||
23289 | ||
23290 | @geindex Ada.Characters.Wide_Wide_Latin_1 (a-chzla1.ads) | |
23291 | ||
23292 | @geindex Latin_1 constants for Wide_Wide_Character | |
23293 | ||
23294 | This child of @code{Ada.Characters} | |
23295 | provides a set of definitions corresponding to those in the | |
23296 | RM-defined package @code{Ada.Characters.Latin_1} but with the | |
23297 | types of the constants being @code{Wide_Wide_Character} | |
23298 | instead of @code{Character}. The provision of such a package | |
23299 | is specifically authorized by the Ada Reference Manual | |
23300 | (RM A.3.3(27)). | |
23301 | ||
23302 | @node Ada Characters Wide_Wide_Latin_9 a-chzla9 ads,Ada Containers Bounded_Holders a-coboho ads,Ada Characters Wide_Wide_Latin_1 a-chzla1 ads,The GNAT Library | |
9daee425 | 23303 | @anchor{gnat_rm/the_gnat_library ada-characters-wide-wide-latin-9-a-chzla9-ads}@anchor{2eb}@anchor{gnat_rm/the_gnat_library id6}@anchor{2ec} |
64d5610f ML |
23304 | @section @code{Ada.Characters.Wide_Wide_Latin_9} (@code{a-chzla9.ads}) |
23305 | ||
23306 | ||
23307 | @geindex Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads) | |
23308 | ||
23309 | @geindex Latin_9 constants for Wide_Wide_Character | |
23310 | ||
23311 | This child of @code{Ada.Characters} | |
23312 | provides a set of definitions corresponding to those in the | |
23313 | GNAT defined package @code{Ada.Characters.Latin_9} but with the | |
23314 | types of the constants being @code{Wide_Wide_Character} | |
23315 | instead of @code{Character}. The provision of such a package | |
23316 | is specifically authorized by the Ada Reference Manual | |
23317 | (RM A.3.3(27)). | |
23318 | ||
23319 | @node Ada Containers Bounded_Holders a-coboho ads,Ada Command_Line Environment a-colien ads,Ada Characters Wide_Wide_Latin_9 a-chzla9 ads,The GNAT Library | |
9daee425 | 23320 | @anchor{gnat_rm/the_gnat_library ada-containers-bounded-holders-a-coboho-ads}@anchor{2ed}@anchor{gnat_rm/the_gnat_library id7}@anchor{2ee} |
64d5610f ML |
23321 | @section @code{Ada.Containers.Bounded_Holders} (@code{a-coboho.ads}) |
23322 | ||
23323 | ||
23324 | @geindex Ada.Containers.Bounded_Holders (a-coboho.ads) | |
23325 | ||
23326 | @geindex Formal container for vectors | |
23327 | ||
23328 | This child of @code{Ada.Containers} defines a modified version of | |
23329 | Indefinite_Holders that avoids heap allocation. | |
23330 | ||
23331 | @node Ada Command_Line Environment a-colien ads,Ada Command_Line Remove a-colire ads,Ada Containers Bounded_Holders a-coboho ads,The GNAT Library | |
9daee425 | 23332 | @anchor{gnat_rm/the_gnat_library ada-command-line-environment-a-colien-ads}@anchor{2ef}@anchor{gnat_rm/the_gnat_library id8}@anchor{2f0} |
64d5610f ML |
23333 | @section @code{Ada.Command_Line.Environment} (@code{a-colien.ads}) |
23334 | ||
23335 | ||
23336 | @geindex Ada.Command_Line.Environment (a-colien.ads) | |
23337 | ||
23338 | @geindex Environment entries | |
23339 | ||
23340 | This child of @code{Ada.Command_Line} | |
23341 | provides a mechanism for obtaining environment values on systems | |
23342 | where this concept makes sense. | |
23343 | ||
23344 | @node Ada Command_Line Remove a-colire ads,Ada Command_Line Response_File a-clrefi ads,Ada Command_Line Environment a-colien ads,The GNAT Library | |
9daee425 | 23345 | @anchor{gnat_rm/the_gnat_library ada-command-line-remove-a-colire-ads}@anchor{2f1}@anchor{gnat_rm/the_gnat_library id9}@anchor{2f2} |
64d5610f ML |
23346 | @section @code{Ada.Command_Line.Remove} (@code{a-colire.ads}) |
23347 | ||
23348 | ||
23349 | @geindex Ada.Command_Line.Remove (a-colire.ads) | |
23350 | ||
23351 | @geindex Removing command line arguments | |
23352 | ||
23353 | @geindex Command line | |
23354 | @geindex argument removal | |
23355 | ||
23356 | This child of @code{Ada.Command_Line} | |
23357 | provides a mechanism for logically removing | |
23358 | arguments from the argument list. Once removed, an argument is not visible | |
eeba836b RD |
23359 | to further calls to the subprograms in @code{Ada.Command_Line}. These calls |
23360 | will not see the removed argument. | |
64d5610f ML |
23361 | |
23362 | @node Ada Command_Line Response_File a-clrefi ads,Ada Direct_IO C_Streams a-diocst ads,Ada Command_Line Remove a-colire ads,The GNAT Library | |
9daee425 | 23363 | @anchor{gnat_rm/the_gnat_library ada-command-line-response-file-a-clrefi-ads}@anchor{2f3}@anchor{gnat_rm/the_gnat_library id10}@anchor{2f4} |
64d5610f ML |
23364 | @section @code{Ada.Command_Line.Response_File} (@code{a-clrefi.ads}) |
23365 | ||
23366 | ||
23367 | @geindex Ada.Command_Line.Response_File (a-clrefi.ads) | |
23368 | ||
23369 | @geindex Response file for command line | |
23370 | ||
23371 | @geindex Command line | |
23372 | @geindex response file | |
23373 | ||
23374 | @geindex Command line | |
23375 | @geindex handling long command lines | |
23376 | ||
23377 | This child of @code{Ada.Command_Line} provides a mechanism facilities for | |
23378 | getting command line arguments from a text file, called a “response file”. | |
23379 | Using a response file allow passing a set of arguments to an executable longer | |
23380 | than the maximum allowed by the system on the command line. | |
23381 | ||
23382 | @node Ada Direct_IO C_Streams a-diocst ads,Ada Exceptions Is_Null_Occurrence a-einuoc ads,Ada Command_Line Response_File a-clrefi ads,The GNAT Library | |
9daee425 | 23383 | @anchor{gnat_rm/the_gnat_library ada-direct-io-c-streams-a-diocst-ads}@anchor{2f5}@anchor{gnat_rm/the_gnat_library id11}@anchor{2f6} |
64d5610f ML |
23384 | @section @code{Ada.Direct_IO.C_Streams} (@code{a-diocst.ads}) |
23385 | ||
23386 | ||
23387 | @geindex Ada.Direct_IO.C_Streams (a-diocst.ads) | |
23388 | ||
23389 | @geindex C Streams | |
23390 | @geindex Interfacing with Direct_IO | |
23391 | ||
23392 | This package provides subprograms that allow interfacing between | |
23393 | C streams and @code{Direct_IO}. The stream identifier can be | |
23394 | extracted from a file opened on the Ada side, and an Ada file | |
23395 | can be constructed from a stream opened on the C side. | |
23396 | ||
23397 | @node Ada Exceptions Is_Null_Occurrence a-einuoc ads,Ada Exceptions Last_Chance_Handler a-elchha ads,Ada Direct_IO C_Streams a-diocst ads,The GNAT Library | |
9daee425 | 23398 | @anchor{gnat_rm/the_gnat_library ada-exceptions-is-null-occurrence-a-einuoc-ads}@anchor{2f7}@anchor{gnat_rm/the_gnat_library id12}@anchor{2f8} |
64d5610f ML |
23399 | @section @code{Ada.Exceptions.Is_Null_Occurrence} (@code{a-einuoc.ads}) |
23400 | ||
23401 | ||
23402 | @geindex Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads) | |
23403 | ||
23404 | @geindex Null_Occurrence | |
23405 | @geindex testing for | |
23406 | ||
23407 | This child subprogram provides a way of testing for the null | |
23408 | exception occurrence (@code{Null_Occurrence}) without raising | |
23409 | an exception. | |
23410 | ||
23411 | @node Ada Exceptions Last_Chance_Handler a-elchha ads,Ada Exceptions Traceback a-exctra ads,Ada Exceptions Is_Null_Occurrence a-einuoc ads,The GNAT Library | |
9daee425 | 23412 | @anchor{gnat_rm/the_gnat_library ada-exceptions-last-chance-handler-a-elchha-ads}@anchor{2f9}@anchor{gnat_rm/the_gnat_library id13}@anchor{2fa} |
64d5610f ML |
23413 | @section @code{Ada.Exceptions.Last_Chance_Handler} (@code{a-elchha.ads}) |
23414 | ||
23415 | ||
23416 | @geindex Ada.Exceptions.Last_Chance_Handler (a-elchha.ads) | |
23417 | ||
23418 | @geindex Null_Occurrence | |
23419 | @geindex testing for | |
23420 | ||
23421 | This child subprogram is used for handling otherwise unhandled | |
23422 | exceptions (hence the name last chance), and perform clean ups before | |
23423 | terminating the program. Note that this subprogram never returns. | |
23424 | ||
23425 | @node Ada Exceptions Traceback a-exctra ads,Ada Sequential_IO C_Streams a-siocst ads,Ada Exceptions Last_Chance_Handler a-elchha ads,The GNAT Library | |
9daee425 | 23426 | @anchor{gnat_rm/the_gnat_library ada-exceptions-traceback-a-exctra-ads}@anchor{2fb}@anchor{gnat_rm/the_gnat_library id14}@anchor{2fc} |
64d5610f ML |
23427 | @section @code{Ada.Exceptions.Traceback} (@code{a-exctra.ads}) |
23428 | ||
23429 | ||
23430 | @geindex Ada.Exceptions.Traceback (a-exctra.ads) | |
23431 | ||
23432 | @geindex Traceback for Exception Occurrence | |
23433 | ||
23434 | This child package provides the subprogram (@code{Tracebacks}) to | |
23435 | give a traceback array of addresses based on an exception | |
23436 | occurrence. | |
23437 | ||
23438 | @node Ada Sequential_IO C_Streams a-siocst ads,Ada Streams Stream_IO C_Streams a-ssicst ads,Ada Exceptions Traceback a-exctra ads,The GNAT Library | |
9daee425 | 23439 | @anchor{gnat_rm/the_gnat_library ada-sequential-io-c-streams-a-siocst-ads}@anchor{2fd}@anchor{gnat_rm/the_gnat_library id15}@anchor{2fe} |
64d5610f ML |
23440 | @section @code{Ada.Sequential_IO.C_Streams} (@code{a-siocst.ads}) |
23441 | ||
23442 | ||
23443 | @geindex Ada.Sequential_IO.C_Streams (a-siocst.ads) | |
23444 | ||
23445 | @geindex C Streams | |
23446 | @geindex Interfacing with Sequential_IO | |
23447 | ||
23448 | This package provides subprograms that allow interfacing between | |
23449 | C streams and @code{Sequential_IO}. The stream identifier can be | |
23450 | extracted from a file opened on the Ada side, and an Ada file | |
23451 | can be constructed from a stream opened on the C side. | |
23452 | ||
23453 | @node Ada Streams Stream_IO C_Streams a-ssicst ads,Ada Strings Unbounded Text_IO a-suteio ads,Ada Sequential_IO C_Streams a-siocst ads,The GNAT Library | |
9daee425 | 23454 | @anchor{gnat_rm/the_gnat_library ada-streams-stream-io-c-streams-a-ssicst-ads}@anchor{2ff}@anchor{gnat_rm/the_gnat_library id16}@anchor{300} |
64d5610f ML |
23455 | @section @code{Ada.Streams.Stream_IO.C_Streams} (@code{a-ssicst.ads}) |
23456 | ||
23457 | ||
23458 | @geindex Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads) | |
23459 | ||
23460 | @geindex C Streams | |
23461 | @geindex Interfacing with Stream_IO | |
23462 | ||
23463 | This package provides subprograms that allow interfacing between | |
23464 | C streams and @code{Stream_IO}. The stream identifier can be | |
23465 | extracted from a file opened on the Ada side, and an Ada file | |
23466 | can be constructed from a stream opened on the C side. | |
23467 | ||
23468 | @node Ada Strings Unbounded Text_IO a-suteio ads,Ada Strings Wide_Unbounded Wide_Text_IO a-swuwti ads,Ada Streams Stream_IO C_Streams a-ssicst ads,The GNAT Library | |
9daee425 | 23469 | @anchor{gnat_rm/the_gnat_library ada-strings-unbounded-text-io-a-suteio-ads}@anchor{301}@anchor{gnat_rm/the_gnat_library id17}@anchor{302} |
64d5610f ML |
23470 | @section @code{Ada.Strings.Unbounded.Text_IO} (@code{a-suteio.ads}) |
23471 | ||
23472 | ||
23473 | @geindex Ada.Strings.Unbounded.Text_IO (a-suteio.ads) | |
23474 | ||
23475 | @geindex Unbounded_String | |
23476 | @geindex IO support | |
23477 | ||
23478 | @geindex Text_IO | |
23479 | @geindex extensions for unbounded strings | |
23480 | ||
23481 | This package provides subprograms for Text_IO for unbounded | |
23482 | strings, avoiding the necessity for an intermediate operation | |
23483 | with ordinary strings. | |
23484 | ||
23485 | @node Ada Strings Wide_Unbounded Wide_Text_IO a-swuwti ads,Ada Strings Wide_Wide_Unbounded Wide_Wide_Text_IO a-szuzti ads,Ada Strings Unbounded Text_IO a-suteio ads,The GNAT Library | |
9daee425 | 23486 | @anchor{gnat_rm/the_gnat_library ada-strings-wide-unbounded-wide-text-io-a-swuwti-ads}@anchor{303}@anchor{gnat_rm/the_gnat_library id18}@anchor{304} |
64d5610f ML |
23487 | @section @code{Ada.Strings.Wide_Unbounded.Wide_Text_IO} (@code{a-swuwti.ads}) |
23488 | ||
23489 | ||
23490 | @geindex Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads) | |
23491 | ||
23492 | @geindex Unbounded_Wide_String | |
23493 | @geindex IO support | |
23494 | ||
23495 | @geindex Text_IO | |
23496 | @geindex extensions for unbounded wide strings | |
23497 | ||
23498 | This package provides subprograms for Text_IO for unbounded | |
23499 | wide strings, avoiding the necessity for an intermediate operation | |
23500 | with ordinary wide strings. | |
23501 | ||
23502 | @node Ada Strings Wide_Wide_Unbounded Wide_Wide_Text_IO a-szuzti ads,Ada Task_Initialization a-tasini ads,Ada Strings Wide_Unbounded Wide_Text_IO a-swuwti ads,The GNAT Library | |
9daee425 | 23503 | @anchor{gnat_rm/the_gnat_library ada-strings-wide-wide-unbounded-wide-wide-text-io-a-szuzti-ads}@anchor{305}@anchor{gnat_rm/the_gnat_library id19}@anchor{306} |
64d5610f ML |
23504 | @section @code{Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO} (@code{a-szuzti.ads}) |
23505 | ||
23506 | ||
23507 | @geindex Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads) | |
23508 | ||
23509 | @geindex Unbounded_Wide_Wide_String | |
23510 | @geindex IO support | |
23511 | ||
23512 | @geindex Text_IO | |
23513 | @geindex extensions for unbounded wide wide strings | |
23514 | ||
23515 | This package provides subprograms for Text_IO for unbounded | |
23516 | wide wide strings, avoiding the necessity for an intermediate operation | |
23517 | with ordinary wide wide strings. | |
23518 | ||
23519 | @node Ada Task_Initialization a-tasini ads,Ada Text_IO C_Streams a-tiocst ads,Ada Strings Wide_Wide_Unbounded Wide_Wide_Text_IO a-szuzti ads,The GNAT Library | |
9daee425 | 23520 | @anchor{gnat_rm/the_gnat_library ada-task-initialization-a-tasini-ads}@anchor{307}@anchor{gnat_rm/the_gnat_library id20}@anchor{308} |
64d5610f ML |
23521 | @section @code{Ada.Task_Initialization} (@code{a-tasini.ads}) |
23522 | ||
23523 | ||
23524 | @geindex Ada.Task_Initialization (a-tasini.ads) | |
23525 | ||
23526 | This package provides a way to set a global initialization handler that | |
23527 | is automatically invoked whenever a task is activated. Handlers are | |
23528 | parameterless procedures. Note that such a handler is only invoked for | |
23529 | those tasks activated after the handler is set. | |
23530 | ||
23531 | @node Ada Text_IO C_Streams a-tiocst ads,Ada Text_IO Reset_Standard_Files a-tirsfi ads,Ada Task_Initialization a-tasini ads,The GNAT Library | |
9daee425 | 23532 | @anchor{gnat_rm/the_gnat_library ada-text-io-c-streams-a-tiocst-ads}@anchor{309}@anchor{gnat_rm/the_gnat_library id21}@anchor{30a} |
64d5610f ML |
23533 | @section @code{Ada.Text_IO.C_Streams} (@code{a-tiocst.ads}) |
23534 | ||
23535 | ||
23536 | @geindex Ada.Text_IO.C_Streams (a-tiocst.ads) | |
23537 | ||
23538 | @geindex C Streams | |
23539 | @geindex Interfacing with `@w{`}Text_IO`@w{`} | |
23540 | ||
23541 | This package provides subprograms that allow interfacing between | |
23542 | C streams and @code{Text_IO}. The stream identifier can be | |
23543 | extracted from a file opened on the Ada side, and an Ada file | |
23544 | can be constructed from a stream opened on the C side. | |
23545 | ||
23546 | @node Ada Text_IO Reset_Standard_Files a-tirsfi ads,Ada Wide_Characters Unicode a-wichun ads,Ada Text_IO C_Streams a-tiocst ads,The GNAT Library | |
9daee425 | 23547 | @anchor{gnat_rm/the_gnat_library ada-text-io-reset-standard-files-a-tirsfi-ads}@anchor{30b}@anchor{gnat_rm/the_gnat_library id22}@anchor{30c} |
64d5610f ML |
23548 | @section @code{Ada.Text_IO.Reset_Standard_Files} (@code{a-tirsfi.ads}) |
23549 | ||
23550 | ||
23551 | @geindex Ada.Text_IO.Reset_Standard_Files (a-tirsfi.ads) | |
23552 | ||
23553 | @geindex Text_IO resetting standard files | |
23554 | ||
23555 | This procedure is used to reset the status of the standard files used | |
23556 | by Ada.Text_IO. This is useful in a situation (such as a restart in an | |
23557 | embedded application) where the status of the files may change during | |
23558 | execution (for example a standard input file may be redefined to be | |
23559 | interactive). | |
23560 | ||
23561 | @node Ada Wide_Characters Unicode a-wichun ads,Ada Wide_Text_IO C_Streams a-wtcstr ads,Ada Text_IO Reset_Standard_Files a-tirsfi ads,The GNAT Library | |
9daee425 | 23562 | @anchor{gnat_rm/the_gnat_library ada-wide-characters-unicode-a-wichun-ads}@anchor{30d}@anchor{gnat_rm/the_gnat_library id23}@anchor{30e} |
64d5610f ML |
23563 | @section @code{Ada.Wide_Characters.Unicode} (@code{a-wichun.ads}) |
23564 | ||
23565 | ||
23566 | @geindex Ada.Wide_Characters.Unicode (a-wichun.ads) | |
23567 | ||
23568 | @geindex Unicode categorization | |
23569 | @geindex Wide_Character | |
23570 | ||
23571 | This package provides subprograms that allow categorization of | |
23572 | Wide_Character values according to Unicode categories. | |
23573 | ||
23574 | @node Ada Wide_Text_IO C_Streams a-wtcstr ads,Ada Wide_Text_IO Reset_Standard_Files a-wrstfi ads,Ada Wide_Characters Unicode a-wichun ads,The GNAT Library | |
9daee425 | 23575 | @anchor{gnat_rm/the_gnat_library ada-wide-text-io-c-streams-a-wtcstr-ads}@anchor{30f}@anchor{gnat_rm/the_gnat_library id24}@anchor{310} |
64d5610f ML |
23576 | @section @code{Ada.Wide_Text_IO.C_Streams} (@code{a-wtcstr.ads}) |
23577 | ||
23578 | ||
23579 | @geindex Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads) | |
23580 | ||
23581 | @geindex C Streams | |
23582 | @geindex Interfacing with `@w{`}Wide_Text_IO`@w{`} | |
23583 | ||
23584 | This package provides subprograms that allow interfacing between | |
23585 | C streams and @code{Wide_Text_IO}. The stream identifier can be | |
23586 | extracted from a file opened on the Ada side, and an Ada file | |
23587 | can be constructed from a stream opened on the C side. | |
23588 | ||
23589 | @node Ada Wide_Text_IO Reset_Standard_Files a-wrstfi ads,Ada Wide_Wide_Characters Unicode a-zchuni ads,Ada Wide_Text_IO C_Streams a-wtcstr ads,The GNAT Library | |
9daee425 | 23590 | @anchor{gnat_rm/the_gnat_library ada-wide-text-io-reset-standard-files-a-wrstfi-ads}@anchor{311}@anchor{gnat_rm/the_gnat_library id25}@anchor{312} |
64d5610f ML |
23591 | @section @code{Ada.Wide_Text_IO.Reset_Standard_Files} (@code{a-wrstfi.ads}) |
23592 | ||
23593 | ||
23594 | @geindex Ada.Wide_Text_IO.Reset_Standard_Files (a-wrstfi.ads) | |
23595 | ||
23596 | @geindex Wide_Text_IO resetting standard files | |
23597 | ||
23598 | This procedure is used to reset the status of the standard files used | |
23599 | by Ada.Wide_Text_IO. This is useful in a situation (such as a restart in an | |
23600 | embedded application) where the status of the files may change during | |
23601 | execution (for example a standard input file may be redefined to be | |
23602 | interactive). | |
23603 | ||
23604 | @node Ada Wide_Wide_Characters Unicode a-zchuni ads,Ada Wide_Wide_Text_IO C_Streams a-ztcstr ads,Ada Wide_Text_IO Reset_Standard_Files a-wrstfi ads,The GNAT Library | |
9daee425 | 23605 | @anchor{gnat_rm/the_gnat_library ada-wide-wide-characters-unicode-a-zchuni-ads}@anchor{313}@anchor{gnat_rm/the_gnat_library id26}@anchor{314} |
64d5610f ML |
23606 | @section @code{Ada.Wide_Wide_Characters.Unicode} (@code{a-zchuni.ads}) |
23607 | ||
23608 | ||
23609 | @geindex Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads) | |
23610 | ||
23611 | @geindex Unicode categorization | |
23612 | @geindex Wide_Wide_Character | |
23613 | ||
23614 | This package provides subprograms that allow categorization of | |
23615 | Wide_Wide_Character values according to Unicode categories. | |
23616 | ||
23617 | @node Ada Wide_Wide_Text_IO C_Streams a-ztcstr ads,Ada Wide_Wide_Text_IO Reset_Standard_Files a-zrstfi ads,Ada Wide_Wide_Characters Unicode a-zchuni ads,The GNAT Library | |
9daee425 | 23618 | @anchor{gnat_rm/the_gnat_library ada-wide-wide-text-io-c-streams-a-ztcstr-ads}@anchor{315}@anchor{gnat_rm/the_gnat_library id27}@anchor{316} |
64d5610f ML |
23619 | @section @code{Ada.Wide_Wide_Text_IO.C_Streams} (@code{a-ztcstr.ads}) |
23620 | ||
23621 | ||
23622 | @geindex Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads) | |
23623 | ||
23624 | @geindex C Streams | |
23625 | @geindex Interfacing with `@w{`}Wide_Wide_Text_IO`@w{`} | |
23626 | ||
23627 | This package provides subprograms that allow interfacing between | |
23628 | C streams and @code{Wide_Wide_Text_IO}. The stream identifier can be | |
23629 | extracted from a file opened on the Ada side, and an Ada file | |
23630 | can be constructed from a stream opened on the C side. | |
23631 | ||
23632 | @node Ada Wide_Wide_Text_IO Reset_Standard_Files a-zrstfi ads,GNAT Altivec g-altive ads,Ada Wide_Wide_Text_IO C_Streams a-ztcstr ads,The GNAT Library | |
9daee425 | 23633 | @anchor{gnat_rm/the_gnat_library ada-wide-wide-text-io-reset-standard-files-a-zrstfi-ads}@anchor{317}@anchor{gnat_rm/the_gnat_library id28}@anchor{318} |
64d5610f ML |
23634 | @section @code{Ada.Wide_Wide_Text_IO.Reset_Standard_Files} (@code{a-zrstfi.ads}) |
23635 | ||
23636 | ||
23637 | @geindex Ada.Wide_Wide_Text_IO.Reset_Standard_Files (a-zrstfi.ads) | |
23638 | ||
23639 | @geindex Wide_Wide_Text_IO resetting standard files | |
23640 | ||
23641 | This procedure is used to reset the status of the standard files used | |
23642 | by Ada.Wide_Wide_Text_IO. This is useful in a situation (such as a | |
23643 | restart in an embedded application) where the status of the files may | |
23644 | change during execution (for example a standard input file may be | |
23645 | redefined to be interactive). | |
23646 | ||
23647 | @node GNAT Altivec g-altive ads,GNAT Altivec Conversions g-altcon ads,Ada Wide_Wide_Text_IO Reset_Standard_Files a-zrstfi ads,The GNAT Library | |
9daee425 | 23648 | @anchor{gnat_rm/the_gnat_library gnat-altivec-g-altive-ads}@anchor{319}@anchor{gnat_rm/the_gnat_library id29}@anchor{31a} |
64d5610f ML |
23649 | @section @code{GNAT.Altivec} (@code{g-altive.ads}) |
23650 | ||
23651 | ||
23652 | @geindex GNAT.Altivec (g-altive.ads) | |
23653 | ||
23654 | @geindex AltiVec | |
23655 | ||
23656 | This is the root package of the GNAT AltiVec binding. It provides | |
23657 | definitions of constants and types common to all the versions of the | |
23658 | binding. | |
23659 | ||
23660 | @node GNAT Altivec Conversions g-altcon ads,GNAT Altivec Vector_Operations g-alveop ads,GNAT Altivec g-altive ads,The GNAT Library | |
9daee425 | 23661 | @anchor{gnat_rm/the_gnat_library gnat-altivec-conversions-g-altcon-ads}@anchor{31b}@anchor{gnat_rm/the_gnat_library id30}@anchor{31c} |
64d5610f ML |
23662 | @section @code{GNAT.Altivec.Conversions} (@code{g-altcon.ads}) |
23663 | ||
23664 | ||
23665 | @geindex GNAT.Altivec.Conversions (g-altcon.ads) | |
23666 | ||
23667 | @geindex AltiVec | |
23668 | ||
23669 | This package provides the Vector/View conversion routines. | |
23670 | ||
23671 | @node GNAT Altivec Vector_Operations g-alveop ads,GNAT Altivec Vector_Types g-alvety ads,GNAT Altivec Conversions g-altcon ads,The GNAT Library | |
9daee425 | 23672 | @anchor{gnat_rm/the_gnat_library gnat-altivec-vector-operations-g-alveop-ads}@anchor{31d}@anchor{gnat_rm/the_gnat_library id31}@anchor{31e} |
64d5610f ML |
23673 | @section @code{GNAT.Altivec.Vector_Operations} (@code{g-alveop.ads}) |
23674 | ||
23675 | ||
23676 | @geindex GNAT.Altivec.Vector_Operations (g-alveop.ads) | |
23677 | ||
23678 | @geindex AltiVec | |
23679 | ||
23680 | This package exposes the Ada interface to the AltiVec operations on | |
23681 | vector objects. A soft emulation is included by default in the GNAT | |
23682 | library. The hard binding is provided as a separate package. This unit | |
23683 | is common to both bindings. | |
23684 | ||
23685 | @node GNAT Altivec Vector_Types g-alvety ads,GNAT Altivec Vector_Views g-alvevi ads,GNAT Altivec Vector_Operations g-alveop ads,The GNAT Library | |
9daee425 | 23686 | @anchor{gnat_rm/the_gnat_library gnat-altivec-vector-types-g-alvety-ads}@anchor{31f}@anchor{gnat_rm/the_gnat_library id32}@anchor{320} |
64d5610f ML |
23687 | @section @code{GNAT.Altivec.Vector_Types} (@code{g-alvety.ads}) |
23688 | ||
23689 | ||
23690 | @geindex GNAT.Altivec.Vector_Types (g-alvety.ads) | |
23691 | ||
23692 | @geindex AltiVec | |
23693 | ||
23694 | This package exposes the various vector types part of the Ada binding | |
23695 | to AltiVec facilities. | |
23696 | ||
23697 | @node GNAT Altivec Vector_Views g-alvevi ads,GNAT Array_Split g-arrspl ads,GNAT Altivec Vector_Types g-alvety ads,The GNAT Library | |
9daee425 | 23698 | @anchor{gnat_rm/the_gnat_library gnat-altivec-vector-views-g-alvevi-ads}@anchor{321}@anchor{gnat_rm/the_gnat_library id33}@anchor{322} |
64d5610f ML |
23699 | @section @code{GNAT.Altivec.Vector_Views} (@code{g-alvevi.ads}) |
23700 | ||
23701 | ||
23702 | @geindex GNAT.Altivec.Vector_Views (g-alvevi.ads) | |
23703 | ||
23704 | @geindex AltiVec | |
23705 | ||
23706 | This package provides public ‘View’ data types from/to which private | |
23707 | vector representations can be converted via | |
23708 | GNAT.Altivec.Conversions. This allows convenient access to individual | |
23709 | vector elements and provides a simple way to initialize vector | |
23710 | objects. | |
23711 | ||
23712 | @node GNAT Array_Split g-arrspl ads,GNAT AWK g-awk ads,GNAT Altivec Vector_Views g-alvevi ads,The GNAT Library | |
9daee425 | 23713 | @anchor{gnat_rm/the_gnat_library gnat-array-split-g-arrspl-ads}@anchor{323}@anchor{gnat_rm/the_gnat_library id34}@anchor{324} |
64d5610f ML |
23714 | @section @code{GNAT.Array_Split} (@code{g-arrspl.ads}) |
23715 | ||
23716 | ||
23717 | @geindex GNAT.Array_Split (g-arrspl.ads) | |
23718 | ||
23719 | @geindex Array splitter | |
23720 | ||
23721 | Useful array-manipulation routines: given a set of separators, split | |
23722 | an array wherever the separators appear, and provide direct access | |
23723 | to the resulting slices. | |
23724 | ||
23725 | @node GNAT AWK g-awk ads,GNAT Binary_Search g-binsea ads,GNAT Array_Split g-arrspl ads,The GNAT Library | |
9daee425 | 23726 | @anchor{gnat_rm/the_gnat_library gnat-awk-g-awk-ads}@anchor{325}@anchor{gnat_rm/the_gnat_library id35}@anchor{326} |
64d5610f ML |
23727 | @section @code{GNAT.AWK} (@code{g-awk.ads}) |
23728 | ||
23729 | ||
23730 | @geindex GNAT.AWK (g-awk.ads) | |
23731 | ||
23732 | @geindex Parsing | |
23733 | ||
23734 | @geindex AWK | |
23735 | ||
23736 | Provides AWK-like parsing functions, with an easy interface for parsing one | |
23737 | or more files containing formatted data. The file is viewed as a database | |
23738 | where each record is a line and a field is a data element in this line. | |
23739 | ||
23740 | @node GNAT Binary_Search g-binsea ads,GNAT Bind_Environment g-binenv ads,GNAT AWK g-awk ads,The GNAT Library | |
9daee425 | 23741 | @anchor{gnat_rm/the_gnat_library gnat-binary-search-g-binsea-ads}@anchor{327}@anchor{gnat_rm/the_gnat_library id36}@anchor{328} |
64d5610f ML |
23742 | @section @code{GNAT.Binary_Search} (@code{g-binsea.ads}) |
23743 | ||
23744 | ||
23745 | @geindex GNAT.Binary_Search (g-binsea.ads) | |
23746 | ||
23747 | @geindex Binary search | |
23748 | ||
23749 | Allow binary search of a sorted array (or of an array-like container; | |
23750 | the generic does not reference the array directly). | |
23751 | ||
23752 | @node GNAT Bind_Environment g-binenv ads,GNAT Branch_Prediction g-brapre ads,GNAT Binary_Search g-binsea ads,The GNAT Library | |
9daee425 | 23753 | @anchor{gnat_rm/the_gnat_library gnat-bind-environment-g-binenv-ads}@anchor{329}@anchor{gnat_rm/the_gnat_library id37}@anchor{32a} |
64d5610f ML |
23754 | @section @code{GNAT.Bind_Environment} (@code{g-binenv.ads}) |
23755 | ||
23756 | ||
23757 | @geindex GNAT.Bind_Environment (g-binenv.ads) | |
23758 | ||
23759 | @geindex Bind environment | |
23760 | ||
23761 | Provides access to key=value associations captured at bind time. | |
23762 | These associations can be specified using the @code{-V} binder command | |
23763 | line switch. | |
23764 | ||
23765 | @node GNAT Branch_Prediction g-brapre ads,GNAT Bounded_Buffers g-boubuf ads,GNAT Bind_Environment g-binenv ads,The GNAT Library | |
9daee425 | 23766 | @anchor{gnat_rm/the_gnat_library gnat-branch-prediction-g-brapre-ads}@anchor{32b}@anchor{gnat_rm/the_gnat_library id38}@anchor{32c} |
64d5610f ML |
23767 | @section @code{GNAT.Branch_Prediction} (@code{g-brapre.ads}) |
23768 | ||
23769 | ||
23770 | @geindex GNAT.Branch_Prediction (g-brapre.ads) | |
23771 | ||
23772 | @geindex Branch Prediction | |
23773 | ||
23774 | Provides routines giving hints to the branch predictor of the code generator. | |
23775 | ||
23776 | @node GNAT Bounded_Buffers g-boubuf ads,GNAT Bounded_Mailboxes g-boumai ads,GNAT Branch_Prediction g-brapre ads,The GNAT Library | |
9daee425 | 23777 | @anchor{gnat_rm/the_gnat_library gnat-bounded-buffers-g-boubuf-ads}@anchor{32d}@anchor{gnat_rm/the_gnat_library id39}@anchor{32e} |
64d5610f ML |
23778 | @section @code{GNAT.Bounded_Buffers} (@code{g-boubuf.ads}) |
23779 | ||
23780 | ||
23781 | @geindex GNAT.Bounded_Buffers (g-boubuf.ads) | |
23782 | ||
23783 | @geindex Parsing | |
23784 | ||
23785 | @geindex Bounded Buffers | |
23786 | ||
23787 | Provides a concurrent generic bounded buffer abstraction. Instances are | |
23788 | useful directly or as parts of the implementations of other abstractions, | |
23789 | such as mailboxes. | |
23790 | ||
23791 | @node GNAT Bounded_Mailboxes g-boumai ads,GNAT Bubble_Sort g-bubsor ads,GNAT Bounded_Buffers g-boubuf ads,The GNAT Library | |
9daee425 | 23792 | @anchor{gnat_rm/the_gnat_library gnat-bounded-mailboxes-g-boumai-ads}@anchor{32f}@anchor{gnat_rm/the_gnat_library id40}@anchor{330} |
64d5610f ML |
23793 | @section @code{GNAT.Bounded_Mailboxes} (@code{g-boumai.ads}) |
23794 | ||
23795 | ||
23796 | @geindex GNAT.Bounded_Mailboxes (g-boumai.ads) | |
23797 | ||
23798 | @geindex Parsing | |
23799 | ||
23800 | @geindex Mailboxes | |
23801 | ||
23802 | Provides a thread-safe asynchronous intertask mailbox communication facility. | |
23803 | ||
23804 | @node GNAT Bubble_Sort g-bubsor ads,GNAT Bubble_Sort_A g-busora ads,GNAT Bounded_Mailboxes g-boumai ads,The GNAT Library | |
9daee425 | 23805 | @anchor{gnat_rm/the_gnat_library gnat-bubble-sort-g-bubsor-ads}@anchor{331}@anchor{gnat_rm/the_gnat_library id41}@anchor{332} |
64d5610f ML |
23806 | @section @code{GNAT.Bubble_Sort} (@code{g-bubsor.ads}) |
23807 | ||
23808 | ||
23809 | @geindex GNAT.Bubble_Sort (g-bubsor.ads) | |
23810 | ||
23811 | @geindex Sorting | |
23812 | ||
23813 | @geindex Bubble sort | |
23814 | ||
23815 | Provides a general implementation of bubble sort usable for sorting arbitrary | |
23816 | data items. Exchange and comparison procedures are provided by passing | |
23817 | access-to-procedure values. | |
23818 | ||
23819 | @node GNAT Bubble_Sort_A g-busora ads,GNAT Bubble_Sort_G g-busorg ads,GNAT Bubble_Sort g-bubsor ads,The GNAT Library | |
9daee425 | 23820 | @anchor{gnat_rm/the_gnat_library gnat-bubble-sort-a-g-busora-ads}@anchor{333}@anchor{gnat_rm/the_gnat_library id42}@anchor{334} |
64d5610f ML |
23821 | @section @code{GNAT.Bubble_Sort_A} (@code{g-busora.ads}) |
23822 | ||
23823 | ||
23824 | @geindex GNAT.Bubble_Sort_A (g-busora.ads) | |
23825 | ||
23826 | @geindex Sorting | |
23827 | ||
23828 | @geindex Bubble sort | |
23829 | ||
23830 | Provides a general implementation of bubble sort usable for sorting arbitrary | |
23831 | data items. Move and comparison procedures are provided by passing | |
23832 | access-to-procedure values. This is an older version, retained for | |
23833 | compatibility. Usually @code{GNAT.Bubble_Sort} will be preferable. | |
23834 | ||
23835 | @node GNAT Bubble_Sort_G g-busorg ads,GNAT Byte_Order_Mark g-byorma ads,GNAT Bubble_Sort_A g-busora ads,The GNAT Library | |
9daee425 | 23836 | @anchor{gnat_rm/the_gnat_library gnat-bubble-sort-g-g-busorg-ads}@anchor{335}@anchor{gnat_rm/the_gnat_library id43}@anchor{336} |
64d5610f ML |
23837 | @section @code{GNAT.Bubble_Sort_G} (@code{g-busorg.ads}) |
23838 | ||
23839 | ||
23840 | @geindex GNAT.Bubble_Sort_G (g-busorg.ads) | |
23841 | ||
23842 | @geindex Sorting | |
23843 | ||
23844 | @geindex Bubble sort | |
23845 | ||
23846 | Similar to @code{Bubble_Sort_A} except that the move and sorting procedures | |
23847 | are provided as generic parameters, this improves efficiency, especially | |
23848 | if the procedures can be inlined, at the expense of duplicating code for | |
23849 | multiple instantiations. | |
23850 | ||
23851 | @node GNAT Byte_Order_Mark g-byorma ads,GNAT Byte_Swapping g-bytswa ads,GNAT Bubble_Sort_G g-busorg ads,The GNAT Library | |
9daee425 | 23852 | @anchor{gnat_rm/the_gnat_library gnat-byte-order-mark-g-byorma-ads}@anchor{337}@anchor{gnat_rm/the_gnat_library id44}@anchor{338} |
64d5610f ML |
23853 | @section @code{GNAT.Byte_Order_Mark} (@code{g-byorma.ads}) |
23854 | ||
23855 | ||
23856 | @geindex GNAT.Byte_Order_Mark (g-byorma.ads) | |
23857 | ||
23858 | @geindex UTF-8 representation | |
23859 | ||
23860 | @geindex Wide characte representations | |
23861 | ||
23862 | Provides a routine which given a string, reads the start of the string to | |
23863 | see whether it is one of the standard byte order marks (BOM’s) which signal | |
23864 | the encoding of the string. The routine includes detection of special XML | |
23865 | sequences for various UCS input formats. | |
23866 | ||
23867 | @node GNAT Byte_Swapping g-bytswa ads,GNAT Calendar g-calend ads,GNAT Byte_Order_Mark g-byorma ads,The GNAT Library | |
9daee425 | 23868 | @anchor{gnat_rm/the_gnat_library gnat-byte-swapping-g-bytswa-ads}@anchor{339}@anchor{gnat_rm/the_gnat_library id45}@anchor{33a} |
64d5610f ML |
23869 | @section @code{GNAT.Byte_Swapping} (@code{g-bytswa.ads}) |
23870 | ||
23871 | ||
23872 | @geindex GNAT.Byte_Swapping (g-bytswa.ads) | |
23873 | ||
23874 | @geindex Byte swapping | |
23875 | ||
23876 | @geindex Endianness | |
23877 | ||
23878 | General routines for swapping the bytes in 2-, 4-, and 8-byte quantities. | |
23879 | Machine-specific implementations are available in some cases. | |
23880 | ||
23881 | @node GNAT Calendar g-calend ads,GNAT Calendar Time_IO g-catiio ads,GNAT Byte_Swapping g-bytswa ads,The GNAT Library | |
9daee425 | 23882 | @anchor{gnat_rm/the_gnat_library gnat-calendar-g-calend-ads}@anchor{33b}@anchor{gnat_rm/the_gnat_library id46}@anchor{33c} |
64d5610f ML |
23883 | @section @code{GNAT.Calendar} (@code{g-calend.ads}) |
23884 | ||
23885 | ||
23886 | @geindex GNAT.Calendar (g-calend.ads) | |
23887 | ||
23888 | @geindex Calendar | |
23889 | ||
23890 | Extends the facilities provided by @code{Ada.Calendar} to include handling | |
23891 | of days of the week, an extended @code{Split} and @code{Time_Of} capability. | |
23892 | Also provides conversion of @code{Ada.Calendar.Time} values to and from the | |
23893 | C @code{timeval} format. | |
23894 | ||
23895 | @node GNAT Calendar Time_IO g-catiio ads,GNAT CRC32 g-crc32 ads,GNAT Calendar g-calend ads,The GNAT Library | |
9daee425 | 23896 | @anchor{gnat_rm/the_gnat_library gnat-calendar-time-io-g-catiio-ads}@anchor{33d}@anchor{gnat_rm/the_gnat_library id47}@anchor{33e} |
64d5610f ML |
23897 | @section @code{GNAT.Calendar.Time_IO} (@code{g-catiio.ads}) |
23898 | ||
23899 | ||
23900 | @geindex Calendar | |
23901 | ||
23902 | @geindex Time | |
23903 | ||
23904 | @geindex GNAT.Calendar.Time_IO (g-catiio.ads) | |
23905 | ||
23906 | @node GNAT CRC32 g-crc32 ads,GNAT Case_Util g-casuti ads,GNAT Calendar Time_IO g-catiio ads,The GNAT Library | |
9daee425 | 23907 | @anchor{gnat_rm/the_gnat_library gnat-crc32-g-crc32-ads}@anchor{33f}@anchor{gnat_rm/the_gnat_library id48}@anchor{340} |
64d5610f ML |
23908 | @section @code{GNAT.CRC32} (@code{g-crc32.ads}) |
23909 | ||
23910 | ||
23911 | @geindex GNAT.CRC32 (g-crc32.ads) | |
23912 | ||
23913 | @geindex CRC32 | |
23914 | ||
23915 | @geindex Cyclic Redundancy Check | |
23916 | ||
23917 | This package implements the CRC-32 algorithm. For a full description | |
23918 | of this algorithm see | |
1acce141 | 23919 | @emph{Computation of Cyclic Redundancy Checks via Table Look-Up}, |
64d5610f ML |
23920 | @cite{Communications of the ACM}, Vol. 31 No. 8, pp. 1008-1013, |
23921 | Aug. 1988. Sarwate, D.V. | |
23922 | ||
23923 | @node GNAT Case_Util g-casuti ads,GNAT CGI g-cgi ads,GNAT CRC32 g-crc32 ads,The GNAT Library | |
9daee425 | 23924 | @anchor{gnat_rm/the_gnat_library gnat-case-util-g-casuti-ads}@anchor{341}@anchor{gnat_rm/the_gnat_library id49}@anchor{342} |
64d5610f ML |
23925 | @section @code{GNAT.Case_Util} (@code{g-casuti.ads}) |
23926 | ||
23927 | ||
23928 | @geindex GNAT.Case_Util (g-casuti.ads) | |
23929 | ||
23930 | @geindex Casing utilities | |
23931 | ||
23932 | @geindex Character handling (`@w{`}GNAT.Case_Util`@w{`}) | |
23933 | ||
23934 | A set of simple routines for handling upper and lower casing of strings | |
23935 | without the overhead of the full casing tables | |
23936 | in @code{Ada.Characters.Handling}. | |
23937 | ||
23938 | @node GNAT CGI g-cgi ads,GNAT CGI Cookie g-cgicoo ads,GNAT Case_Util g-casuti ads,The GNAT Library | |
9daee425 | 23939 | @anchor{gnat_rm/the_gnat_library gnat-cgi-g-cgi-ads}@anchor{343}@anchor{gnat_rm/the_gnat_library id50}@anchor{344} |
64d5610f ML |
23940 | @section @code{GNAT.CGI} (@code{g-cgi.ads}) |
23941 | ||
23942 | ||
23943 | @geindex GNAT.CGI (g-cgi.ads) | |
23944 | ||
23945 | @geindex CGI (Common Gateway Interface) | |
23946 | ||
23947 | This is a package for interfacing a GNAT program with a Web server via the | |
23948 | Common Gateway Interface (CGI). Basically this package parses the CGI | |
23949 | parameters, which are a set of key/value pairs sent by the Web server. It | |
23950 | builds a table whose index is the key and provides some services to deal | |
23951 | with this table. | |
23952 | ||
23953 | @node GNAT CGI Cookie g-cgicoo ads,GNAT CGI Debug g-cgideb ads,GNAT CGI g-cgi ads,The GNAT Library | |
9daee425 | 23954 | @anchor{gnat_rm/the_gnat_library gnat-cgi-cookie-g-cgicoo-ads}@anchor{345}@anchor{gnat_rm/the_gnat_library id51}@anchor{346} |
64d5610f ML |
23955 | @section @code{GNAT.CGI.Cookie} (@code{g-cgicoo.ads}) |
23956 | ||
23957 | ||
23958 | @geindex GNAT.CGI.Cookie (g-cgicoo.ads) | |
23959 | ||
23960 | @geindex CGI (Common Gateway Interface) cookie support | |
23961 | ||
23962 | @geindex Cookie support in CGI | |
23963 | ||
23964 | This is a package to interface a GNAT program with a Web server via the | |
23965 | Common Gateway Interface (CGI). It exports services to deal with Web | |
23966 | cookies (piece of information kept in the Web client software). | |
23967 | ||
23968 | @node GNAT CGI Debug g-cgideb ads,GNAT Command_Line g-comlin ads,GNAT CGI Cookie g-cgicoo ads,The GNAT Library | |
9daee425 | 23969 | @anchor{gnat_rm/the_gnat_library gnat-cgi-debug-g-cgideb-ads}@anchor{347}@anchor{gnat_rm/the_gnat_library id52}@anchor{348} |
64d5610f ML |
23970 | @section @code{GNAT.CGI.Debug} (@code{g-cgideb.ads}) |
23971 | ||
23972 | ||
23973 | @geindex GNAT.CGI.Debug (g-cgideb.ads) | |
23974 | ||
23975 | @geindex CGI (Common Gateway Interface) debugging | |
23976 | ||
23977 | This is a package to help debugging CGI (Common Gateway Interface) | |
23978 | programs written in Ada. | |
23979 | ||
23980 | @node GNAT Command_Line g-comlin ads,GNAT Compiler_Version g-comver ads,GNAT CGI Debug g-cgideb ads,The GNAT Library | |
9daee425 | 23981 | @anchor{gnat_rm/the_gnat_library gnat-command-line-g-comlin-ads}@anchor{349}@anchor{gnat_rm/the_gnat_library id53}@anchor{34a} |
64d5610f ML |
23982 | @section @code{GNAT.Command_Line} (@code{g-comlin.ads}) |
23983 | ||
23984 | ||
23985 | @geindex GNAT.Command_Line (g-comlin.ads) | |
23986 | ||
23987 | @geindex Command line | |
23988 | ||
23989 | Provides a high level interface to @code{Ada.Command_Line} facilities, | |
23990 | including the ability to scan for named switches with optional parameters | |
23991 | and expand file names using wildcard notations. | |
23992 | ||
23993 | @node GNAT Compiler_Version g-comver ads,GNAT Ctrl_C g-ctrl_c ads,GNAT Command_Line g-comlin ads,The GNAT Library | |
9daee425 | 23994 | @anchor{gnat_rm/the_gnat_library gnat-compiler-version-g-comver-ads}@anchor{34b}@anchor{gnat_rm/the_gnat_library id54}@anchor{34c} |
64d5610f ML |
23995 | @section @code{GNAT.Compiler_Version} (@code{g-comver.ads}) |
23996 | ||
23997 | ||
23998 | @geindex GNAT.Compiler_Version (g-comver.ads) | |
23999 | ||
24000 | @geindex Compiler Version | |
24001 | ||
24002 | @geindex Version | |
24003 | @geindex of compiler | |
24004 | ||
24005 | Provides a routine for obtaining the version of the compiler used to | |
24006 | compile the program. More accurately this is the version of the binder | |
24007 | used to bind the program (this will normally be the same as the version | |
24008 | of the compiler if a consistent tool set is used to compile all units | |
24009 | of a partition). | |
24010 | ||
24011 | @node GNAT Ctrl_C g-ctrl_c ads,GNAT Current_Exception g-curexc ads,GNAT Compiler_Version g-comver ads,The GNAT Library | |
9daee425 | 24012 | @anchor{gnat_rm/the_gnat_library gnat-ctrl-c-g-ctrl-c-ads}@anchor{34d}@anchor{gnat_rm/the_gnat_library id55}@anchor{34e} |
64d5610f ML |
24013 | @section @code{GNAT.Ctrl_C} (@code{g-ctrl_c.ads}) |
24014 | ||
24015 | ||
24016 | @geindex GNAT.Ctrl_C (g-ctrl_c.ads) | |
24017 | ||
24018 | @geindex Interrupt | |
24019 | ||
24020 | Provides a simple interface to handle Ctrl-C keyboard events. | |
24021 | ||
24022 | @node GNAT Current_Exception g-curexc ads,GNAT Debug_Pools g-debpoo ads,GNAT Ctrl_C g-ctrl_c ads,The GNAT Library | |
9daee425 | 24023 | @anchor{gnat_rm/the_gnat_library gnat-current-exception-g-curexc-ads}@anchor{34f}@anchor{gnat_rm/the_gnat_library id56}@anchor{350} |
64d5610f ML |
24024 | @section @code{GNAT.Current_Exception} (@code{g-curexc.ads}) |
24025 | ||
24026 | ||
24027 | @geindex GNAT.Current_Exception (g-curexc.ads) | |
24028 | ||
24029 | @geindex Current exception | |
24030 | ||
24031 | @geindex Exception retrieval | |
24032 | ||
24033 | Provides access to information on the current exception that has been raised | |
24034 | without the need for using the Ada 95 / Ada 2005 exception choice parameter | |
24035 | specification syntax. | |
24036 | This is particularly useful in simulating typical facilities for | |
24037 | obtaining information about exceptions provided by Ada 83 compilers. | |
24038 | ||
24039 | @node GNAT Debug_Pools g-debpoo ads,GNAT Debug_Utilities g-debuti ads,GNAT Current_Exception g-curexc ads,The GNAT Library | |
9daee425 | 24040 | @anchor{gnat_rm/the_gnat_library gnat-debug-pools-g-debpoo-ads}@anchor{351}@anchor{gnat_rm/the_gnat_library id57}@anchor{352} |
64d5610f ML |
24041 | @section @code{GNAT.Debug_Pools} (@code{g-debpoo.ads}) |
24042 | ||
24043 | ||
24044 | @geindex GNAT.Debug_Pools (g-debpoo.ads) | |
24045 | ||
24046 | @geindex Debugging | |
24047 | ||
24048 | @geindex Debug pools | |
24049 | ||
24050 | @geindex Memory corruption debugging | |
24051 | ||
eeba836b | 24052 | Provides a debugging storage pools that helps tracking memory corruption |
64d5610f ML |
24053 | problems. |
24054 | See @code{The GNAT Debug_Pool Facility} section in the @cite{GNAT User’s Guide}. | |
24055 | ||
24056 | @node GNAT Debug_Utilities g-debuti ads,GNAT Decode_String g-decstr ads,GNAT Debug_Pools g-debpoo ads,The GNAT Library | |
9daee425 | 24057 | @anchor{gnat_rm/the_gnat_library gnat-debug-utilities-g-debuti-ads}@anchor{353}@anchor{gnat_rm/the_gnat_library id58}@anchor{354} |
64d5610f ML |
24058 | @section @code{GNAT.Debug_Utilities} (@code{g-debuti.ads}) |
24059 | ||
24060 | ||
24061 | @geindex GNAT.Debug_Utilities (g-debuti.ads) | |
24062 | ||
24063 | @geindex Debugging | |
24064 | ||
24065 | Provides a few useful utilities for debugging purposes, including conversion | |
24066 | to and from string images of address values. Supports both C and Ada formats | |
24067 | for hexadecimal literals. | |
24068 | ||
24069 | @node GNAT Decode_String g-decstr ads,GNAT Decode_UTF8_String g-deutst ads,GNAT Debug_Utilities g-debuti ads,The GNAT Library | |
9daee425 | 24070 | @anchor{gnat_rm/the_gnat_library gnat-decode-string-g-decstr-ads}@anchor{355}@anchor{gnat_rm/the_gnat_library id59}@anchor{356} |
64d5610f ML |
24071 | @section @code{GNAT.Decode_String} (@code{g-decstr.ads}) |
24072 | ||
24073 | ||
24074 | @geindex GNAT.Decode_String (g-decstr.ads) | |
24075 | ||
24076 | @geindex Decoding strings | |
24077 | ||
24078 | @geindex String decoding | |
24079 | ||
24080 | @geindex Wide character encoding | |
24081 | ||
24082 | @geindex UTF-8 | |
24083 | ||
24084 | @geindex Unicode | |
24085 | ||
24086 | A generic package providing routines for decoding wide character and wide wide | |
24087 | character strings encoded as sequences of 8-bit characters using a specified | |
24088 | encoding method. Includes validation routines, and also routines for stepping | |
24089 | to next or previous encoded character in an encoded string. | |
24090 | Useful in conjunction with Unicode character coding. Note there is a | |
24091 | preinstantiation for UTF-8. See next entry. | |
24092 | ||
24093 | @node GNAT Decode_UTF8_String g-deutst ads,GNAT Directory_Operations g-dirope ads,GNAT Decode_String g-decstr ads,The GNAT Library | |
9daee425 | 24094 | @anchor{gnat_rm/the_gnat_library gnat-decode-utf8-string-g-deutst-ads}@anchor{357}@anchor{gnat_rm/the_gnat_library id60}@anchor{358} |
64d5610f ML |
24095 | @section @code{GNAT.Decode_UTF8_String} (@code{g-deutst.ads}) |
24096 | ||
24097 | ||
24098 | @geindex GNAT.Decode_UTF8_String (g-deutst.ads) | |
24099 | ||
24100 | @geindex Decoding strings | |
24101 | ||
24102 | @geindex Decoding UTF-8 strings | |
24103 | ||
24104 | @geindex UTF-8 string decoding | |
24105 | ||
24106 | @geindex Wide character decoding | |
24107 | ||
24108 | @geindex UTF-8 | |
24109 | ||
24110 | @geindex Unicode | |
24111 | ||
24112 | A preinstantiation of GNAT.Decode_Strings for UTF-8 encoding. | |
24113 | ||
24114 | @node GNAT Directory_Operations g-dirope ads,GNAT Directory_Operations Iteration g-diopit ads,GNAT Decode_UTF8_String g-deutst ads,The GNAT Library | |
9daee425 | 24115 | @anchor{gnat_rm/the_gnat_library gnat-directory-operations-g-dirope-ads}@anchor{359}@anchor{gnat_rm/the_gnat_library id61}@anchor{35a} |
64d5610f ML |
24116 | @section @code{GNAT.Directory_Operations} (@code{g-dirope.ads}) |
24117 | ||
24118 | ||
24119 | @geindex GNAT.Directory_Operations (g-dirope.ads) | |
24120 | ||
24121 | @geindex Directory operations | |
24122 | ||
24123 | Provides a set of routines for manipulating directories, including changing | |
24124 | the current directory, making new directories, and scanning the files in a | |
24125 | directory. | |
24126 | ||
24127 | @node GNAT Directory_Operations Iteration g-diopit ads,GNAT Dynamic_HTables g-dynhta ads,GNAT Directory_Operations g-dirope ads,The GNAT Library | |
9daee425 | 24128 | @anchor{gnat_rm/the_gnat_library gnat-directory-operations-iteration-g-diopit-ads}@anchor{35b}@anchor{gnat_rm/the_gnat_library id62}@anchor{35c} |
64d5610f ML |
24129 | @section @code{GNAT.Directory_Operations.Iteration} (@code{g-diopit.ads}) |
24130 | ||
24131 | ||
24132 | @geindex GNAT.Directory_Operations.Iteration (g-diopit.ads) | |
24133 | ||
24134 | @geindex Directory operations iteration | |
24135 | ||
24136 | A child unit of GNAT.Directory_Operations providing additional operations | |
24137 | for iterating through directories. | |
24138 | ||
24139 | @node GNAT Dynamic_HTables g-dynhta ads,GNAT Dynamic_Tables g-dyntab ads,GNAT Directory_Operations Iteration g-diopit ads,The GNAT Library | |
9daee425 | 24140 | @anchor{gnat_rm/the_gnat_library gnat-dynamic-htables-g-dynhta-ads}@anchor{35d}@anchor{gnat_rm/the_gnat_library id63}@anchor{35e} |
64d5610f ML |
24141 | @section @code{GNAT.Dynamic_HTables} (@code{g-dynhta.ads}) |
24142 | ||
24143 | ||
24144 | @geindex GNAT.Dynamic_HTables (g-dynhta.ads) | |
24145 | ||
24146 | @geindex Hash tables | |
24147 | ||
24148 | A generic implementation of hash tables that can be used to hash arbitrary | |
24149 | data. Provided in two forms, a simple form with built in hash functions, | |
24150 | and a more complex form in which the hash function is supplied. | |
24151 | ||
24152 | This package provides a facility similar to that of @code{GNAT.HTable}, | |
24153 | except that this package declares a type that can be used to define | |
24154 | dynamic instances of the hash table, while an instantiation of | |
24155 | @code{GNAT.HTable} creates a single instance of the hash table. | |
24156 | ||
24157 | @node GNAT Dynamic_Tables g-dyntab ads,GNAT Encode_String g-encstr ads,GNAT Dynamic_HTables g-dynhta ads,The GNAT Library | |
9daee425 | 24158 | @anchor{gnat_rm/the_gnat_library gnat-dynamic-tables-g-dyntab-ads}@anchor{35f}@anchor{gnat_rm/the_gnat_library id64}@anchor{360} |
64d5610f ML |
24159 | @section @code{GNAT.Dynamic_Tables} (@code{g-dyntab.ads}) |
24160 | ||
24161 | ||
24162 | @geindex GNAT.Dynamic_Tables (g-dyntab.ads) | |
24163 | ||
24164 | @geindex Table implementation | |
24165 | ||
24166 | @geindex Arrays | |
24167 | @geindex extendable | |
24168 | ||
24169 | A generic package providing a single dimension array abstraction where the | |
24170 | length of the array can be dynamically modified. | |
24171 | ||
24172 | This package provides a facility similar to that of @code{GNAT.Table}, | |
24173 | except that this package declares a type that can be used to define | |
24174 | dynamic instances of the table, while an instantiation of | |
24175 | @code{GNAT.Table} creates a single instance of the table type. | |
24176 | ||
24177 | @node GNAT Encode_String g-encstr ads,GNAT Encode_UTF8_String g-enutst ads,GNAT Dynamic_Tables g-dyntab ads,The GNAT Library | |
9daee425 | 24178 | @anchor{gnat_rm/the_gnat_library gnat-encode-string-g-encstr-ads}@anchor{361}@anchor{gnat_rm/the_gnat_library id65}@anchor{362} |
64d5610f ML |
24179 | @section @code{GNAT.Encode_String} (@code{g-encstr.ads}) |
24180 | ||
24181 | ||
24182 | @geindex GNAT.Encode_String (g-encstr.ads) | |
24183 | ||
24184 | @geindex Encoding strings | |
24185 | ||
24186 | @geindex String encoding | |
24187 | ||
24188 | @geindex Wide character encoding | |
24189 | ||
24190 | @geindex UTF-8 | |
24191 | ||
24192 | @geindex Unicode | |
24193 | ||
24194 | A generic package providing routines for encoding wide character and wide | |
24195 | wide character strings as sequences of 8-bit characters using a specified | |
24196 | encoding method. Useful in conjunction with Unicode character coding. | |
24197 | Note there is a preinstantiation for UTF-8. See next entry. | |
24198 | ||
24199 | @node GNAT Encode_UTF8_String g-enutst ads,GNAT Exception_Actions g-excact ads,GNAT Encode_String g-encstr ads,The GNAT Library | |
9daee425 | 24200 | @anchor{gnat_rm/the_gnat_library gnat-encode-utf8-string-g-enutst-ads}@anchor{363}@anchor{gnat_rm/the_gnat_library id66}@anchor{364} |
64d5610f ML |
24201 | @section @code{GNAT.Encode_UTF8_String} (@code{g-enutst.ads}) |
24202 | ||
24203 | ||
24204 | @geindex GNAT.Encode_UTF8_String (g-enutst.ads) | |
24205 | ||
24206 | @geindex Encoding strings | |
24207 | ||
24208 | @geindex Encoding UTF-8 strings | |
24209 | ||
24210 | @geindex UTF-8 string encoding | |
24211 | ||
24212 | @geindex Wide character encoding | |
24213 | ||
24214 | @geindex UTF-8 | |
24215 | ||
24216 | @geindex Unicode | |
24217 | ||
24218 | A preinstantiation of GNAT.Encode_Strings for UTF-8 encoding. | |
24219 | ||
24220 | @node GNAT Exception_Actions g-excact ads,GNAT Exception_Traces g-exctra ads,GNAT Encode_UTF8_String g-enutst ads,The GNAT Library | |
9daee425 | 24221 | @anchor{gnat_rm/the_gnat_library gnat-exception-actions-g-excact-ads}@anchor{365}@anchor{gnat_rm/the_gnat_library id67}@anchor{366} |
64d5610f ML |
24222 | @section @code{GNAT.Exception_Actions} (@code{g-excact.ads}) |
24223 | ||
24224 | ||
24225 | @geindex GNAT.Exception_Actions (g-excact.ads) | |
24226 | ||
24227 | @geindex Exception actions | |
24228 | ||
24229 | Provides callbacks when an exception is raised. Callbacks can be registered | |
24230 | for specific exceptions, or when any exception is raised. This | |
24231 | can be used for instance to force a core dump to ease debugging. | |
24232 | ||
24233 | @node GNAT Exception_Traces g-exctra ads,GNAT Exceptions g-except ads,GNAT Exception_Actions g-excact ads,The GNAT Library | |
9daee425 | 24234 | @anchor{gnat_rm/the_gnat_library gnat-exception-traces-g-exctra-ads}@anchor{367}@anchor{gnat_rm/the_gnat_library id68}@anchor{368} |
64d5610f ML |
24235 | @section @code{GNAT.Exception_Traces} (@code{g-exctra.ads}) |
24236 | ||
24237 | ||
24238 | @geindex GNAT.Exception_Traces (g-exctra.ads) | |
24239 | ||
24240 | @geindex Exception traces | |
24241 | ||
24242 | @geindex Debugging | |
24243 | ||
24244 | Provides an interface allowing to control automatic output upon exception | |
24245 | occurrences. | |
24246 | ||
24247 | @node GNAT Exceptions g-except ads,GNAT Expect g-expect ads,GNAT Exception_Traces g-exctra ads,The GNAT Library | |
9daee425 | 24248 | @anchor{gnat_rm/the_gnat_library gnat-exceptions-g-except-ads}@anchor{369}@anchor{gnat_rm/the_gnat_library id69}@anchor{36a} |
64d5610f ML |
24249 | @section @code{GNAT.Exceptions} (@code{g-except.ads}) |
24250 | ||
24251 | ||
24252 | @geindex GNAT.Exceptions (g-except.ads) | |
24253 | ||
24254 | @geindex Exceptions | |
24255 | @geindex Pure | |
24256 | ||
24257 | @geindex Pure packages | |
24258 | @geindex exceptions | |
24259 | ||
24260 | Normally it is not possible to raise an exception with | |
24261 | a message from a subprogram in a pure package, since the | |
24262 | necessary types and subprograms are in @code{Ada.Exceptions} | |
24263 | which is not a pure unit. @code{GNAT.Exceptions} provides a | |
24264 | facility for getting around this limitation for a few | |
eeba836b | 24265 | predefined exceptions, and for example allows raising |
64d5610f ML |
24266 | @code{Constraint_Error} with a message from a pure subprogram. |
24267 | ||
24268 | @node GNAT Expect g-expect ads,GNAT Expect TTY g-exptty ads,GNAT Exceptions g-except ads,The GNAT Library | |
9daee425 | 24269 | @anchor{gnat_rm/the_gnat_library gnat-expect-g-expect-ads}@anchor{36b}@anchor{gnat_rm/the_gnat_library id70}@anchor{36c} |
64d5610f ML |
24270 | @section @code{GNAT.Expect} (@code{g-expect.ads}) |
24271 | ||
24272 | ||
24273 | @geindex GNAT.Expect (g-expect.ads) | |
24274 | ||
24275 | Provides a set of subprograms similar to what is available | |
24276 | with the standard Tcl Expect tool. | |
24277 | It allows you to easily spawn and communicate with an external process. | |
24278 | You can send commands or inputs to the process, and compare the output | |
24279 | with some expected regular expression. Currently @code{GNAT.Expect} | |
24280 | is implemented on all native GNAT ports. | |
24281 | It is not implemented for cross ports, and in particular is not | |
24282 | implemented for VxWorks or LynxOS. | |
24283 | ||
24284 | @node GNAT Expect TTY g-exptty ads,GNAT Float_Control g-flocon ads,GNAT Expect g-expect ads,The GNAT Library | |
9daee425 | 24285 | @anchor{gnat_rm/the_gnat_library gnat-expect-tty-g-exptty-ads}@anchor{36d}@anchor{gnat_rm/the_gnat_library id71}@anchor{36e} |
64d5610f ML |
24286 | @section @code{GNAT.Expect.TTY} (@code{g-exptty.ads}) |
24287 | ||
24288 | ||
24289 | @geindex GNAT.Expect.TTY (g-exptty.ads) | |
24290 | ||
24291 | As GNAT.Expect but using pseudo-terminal. | |
24292 | Currently @code{GNAT.Expect.TTY} is implemented on all native GNAT | |
24293 | ports. It is not implemented for cross ports, and | |
24294 | in particular is not implemented for VxWorks or LynxOS. | |
24295 | ||
24296 | @node GNAT Float_Control g-flocon ads,GNAT Formatted_String g-forstr ads,GNAT Expect TTY g-exptty ads,The GNAT Library | |
9daee425 | 24297 | @anchor{gnat_rm/the_gnat_library gnat-float-control-g-flocon-ads}@anchor{36f}@anchor{gnat_rm/the_gnat_library id72}@anchor{370} |
64d5610f ML |
24298 | @section @code{GNAT.Float_Control} (@code{g-flocon.ads}) |
24299 | ||
24300 | ||
24301 | @geindex GNAT.Float_Control (g-flocon.ads) | |
24302 | ||
24303 | @geindex Floating-Point Processor | |
24304 | ||
24305 | Provides an interface for resetting the floating-point processor into the | |
24306 | mode required for correct semantic operation in Ada. Some third party | |
24307 | library calls may cause this mode to be modified, and the Reset procedure | |
24308 | in this package can be used to reestablish the required mode. | |
24309 | ||
24310 | @node GNAT Formatted_String g-forstr ads,GNAT Generic_Fast_Math_Functions g-gfmafu ads,GNAT Float_Control g-flocon ads,The GNAT Library | |
9daee425 | 24311 | @anchor{gnat_rm/the_gnat_library gnat-formatted-string-g-forstr-ads}@anchor{371}@anchor{gnat_rm/the_gnat_library id73}@anchor{372} |
64d5610f ML |
24312 | @section @code{GNAT.Formatted_String} (@code{g-forstr.ads}) |
24313 | ||
24314 | ||
24315 | @geindex GNAT.Formatted_String (g-forstr.ads) | |
24316 | ||
24317 | @geindex Formatted String | |
24318 | ||
24319 | Provides support for C/C++ printf() formatted strings. The format is | |
eeba836b | 24320 | copied from the printf() routine and should therefore give identical |
64d5610f ML |
24321 | output. Some generic routines are provided to be able to use types |
24322 | derived from Integer, Float or enumerations as values for the | |
24323 | formatted string. | |
24324 | ||
24325 | @node GNAT Generic_Fast_Math_Functions g-gfmafu ads,GNAT Heap_Sort g-heasor ads,GNAT Formatted_String g-forstr ads,The GNAT Library | |
9daee425 | 24326 | @anchor{gnat_rm/the_gnat_library gnat-generic-fast-math-functions-g-gfmafu-ads}@anchor{373}@anchor{gnat_rm/the_gnat_library id74}@anchor{374} |
64d5610f ML |
24327 | @section @code{GNAT.Generic_Fast_Math_Functions} (@code{g-gfmafu.ads}) |
24328 | ||
24329 | ||
24330 | @geindex GNAT.Generic_Fast_Math_Functions (g-gfmafu.ads) | |
24331 | ||
24332 | @geindex Mathematical functions | |
24333 | ||
24334 | Provides direct access to the underlying implementation of the common | |
24335 | mathematical functions, generally from the system mathematical library. | |
24336 | This differs from @code{Ada.Numerics.Generic_Elementary_Functions} in that | |
24337 | the implementation may deviate from the semantics specified for these | |
24338 | functions in the Reference Manual, for example @code{Numerics.Argument_Error} | |
24339 | is not raised. On selected platforms, some of these functions may also | |
24340 | have a vector implementation that can be automatically used by the | |
24341 | compiler when auto-vectorization is enabled. | |
24342 | ||
24343 | @node GNAT Heap_Sort g-heasor ads,GNAT Heap_Sort_A g-hesora ads,GNAT Generic_Fast_Math_Functions g-gfmafu ads,The GNAT Library | |
9daee425 | 24344 | @anchor{gnat_rm/the_gnat_library gnat-heap-sort-g-heasor-ads}@anchor{375}@anchor{gnat_rm/the_gnat_library id75}@anchor{376} |
64d5610f ML |
24345 | @section @code{GNAT.Heap_Sort} (@code{g-heasor.ads}) |
24346 | ||
24347 | ||
24348 | @geindex GNAT.Heap_Sort (g-heasor.ads) | |
24349 | ||
24350 | @geindex Sorting | |
24351 | ||
24352 | Provides a general implementation of heap sort usable for sorting arbitrary | |
24353 | data items. Exchange and comparison procedures are provided by passing | |
24354 | access-to-procedure values. The algorithm used is a modified heap sort | |
24355 | that performs approximately N*log(N) comparisons in the worst case. | |
24356 | ||
24357 | @node GNAT Heap_Sort_A g-hesora ads,GNAT Heap_Sort_G g-hesorg ads,GNAT Heap_Sort g-heasor ads,The GNAT Library | |
9daee425 | 24358 | @anchor{gnat_rm/the_gnat_library gnat-heap-sort-a-g-hesora-ads}@anchor{377}@anchor{gnat_rm/the_gnat_library id76}@anchor{378} |
64d5610f ML |
24359 | @section @code{GNAT.Heap_Sort_A} (@code{g-hesora.ads}) |
24360 | ||
24361 | ||
24362 | @geindex GNAT.Heap_Sort_A (g-hesora.ads) | |
24363 | ||
24364 | @geindex Sorting | |
24365 | ||
24366 | Provides a general implementation of heap sort usable for sorting arbitrary | |
24367 | data items. Move and comparison procedures are provided by passing | |
24368 | access-to-procedure values. The algorithm used is a modified heap sort | |
24369 | that performs approximately N*log(N) comparisons in the worst case. | |
24370 | This differs from @code{GNAT.Heap_Sort} in having a less convenient | |
24371 | interface, but may be slightly more efficient. | |
24372 | ||
24373 | @node GNAT Heap_Sort_G g-hesorg ads,GNAT HTable g-htable ads,GNAT Heap_Sort_A g-hesora ads,The GNAT Library | |
9daee425 | 24374 | @anchor{gnat_rm/the_gnat_library gnat-heap-sort-g-g-hesorg-ads}@anchor{379}@anchor{gnat_rm/the_gnat_library id77}@anchor{37a} |
64d5610f ML |
24375 | @section @code{GNAT.Heap_Sort_G} (@code{g-hesorg.ads}) |
24376 | ||
24377 | ||
24378 | @geindex GNAT.Heap_Sort_G (g-hesorg.ads) | |
24379 | ||
24380 | @geindex Sorting | |
24381 | ||
24382 | Similar to @code{Heap_Sort_A} except that the move and sorting procedures | |
24383 | are provided as generic parameters, this improves efficiency, especially | |
24384 | if the procedures can be inlined, at the expense of duplicating code for | |
24385 | multiple instantiations. | |
24386 | ||
24387 | @node GNAT HTable g-htable ads,GNAT IO g-io ads,GNAT Heap_Sort_G g-hesorg ads,The GNAT Library | |
9daee425 | 24388 | @anchor{gnat_rm/the_gnat_library gnat-htable-g-htable-ads}@anchor{37b}@anchor{gnat_rm/the_gnat_library id78}@anchor{37c} |
64d5610f ML |
24389 | @section @code{GNAT.HTable} (@code{g-htable.ads}) |
24390 | ||
24391 | ||
24392 | @geindex GNAT.HTable (g-htable.ads) | |
24393 | ||
24394 | @geindex Hash tables | |
24395 | ||
24396 | A generic implementation of hash tables that can be used to hash arbitrary | |
24397 | data. Provides two approaches, one a simple static approach, and the other | |
24398 | allowing arbitrary dynamic hash tables. | |
24399 | ||
24400 | @node GNAT IO g-io ads,GNAT IO_Aux g-io_aux ads,GNAT HTable g-htable ads,The GNAT Library | |
9daee425 | 24401 | @anchor{gnat_rm/the_gnat_library gnat-io-g-io-ads}@anchor{37d}@anchor{gnat_rm/the_gnat_library id79}@anchor{37e} |
64d5610f ML |
24402 | @section @code{GNAT.IO} (@code{g-io.ads}) |
24403 | ||
24404 | ||
24405 | @geindex GNAT.IO (g-io.ads) | |
24406 | ||
24407 | @geindex Simple I/O | |
24408 | ||
24409 | @geindex Input/Output facilities | |
24410 | ||
24411 | A simple preelaborable input-output package that provides a subset of | |
24412 | simple Text_IO functions for reading characters and strings from | |
24413 | Standard_Input, and writing characters, strings and integers to either | |
24414 | Standard_Output or Standard_Error. | |
24415 | ||
24416 | @node GNAT IO_Aux g-io_aux ads,GNAT Lock_Files g-locfil ads,GNAT IO g-io ads,The GNAT Library | |
9daee425 | 24417 | @anchor{gnat_rm/the_gnat_library gnat-io-aux-g-io-aux-ads}@anchor{37f}@anchor{gnat_rm/the_gnat_library id80}@anchor{380} |
64d5610f ML |
24418 | @section @code{GNAT.IO_Aux} (@code{g-io_aux.ads}) |
24419 | ||
24420 | ||
24421 | @geindex GNAT.IO_Aux (g-io_aux.ads) | |
24422 | ||
24423 | @geindex Text_IO | |
24424 | ||
24425 | @geindex Input/Output facilities | |
24426 | ||
24427 | Provides some auxiliary functions for use with Text_IO, including a test | |
24428 | for whether a file exists, and functions for reading a line of text. | |
24429 | ||
24430 | @node GNAT Lock_Files g-locfil ads,GNAT MBBS_Discrete_Random g-mbdira ads,GNAT IO_Aux g-io_aux ads,The GNAT Library | |
9daee425 | 24431 | @anchor{gnat_rm/the_gnat_library gnat-lock-files-g-locfil-ads}@anchor{381}@anchor{gnat_rm/the_gnat_library id81}@anchor{382} |
64d5610f ML |
24432 | @section @code{GNAT.Lock_Files} (@code{g-locfil.ads}) |
24433 | ||
24434 | ||
24435 | @geindex GNAT.Lock_Files (g-locfil.ads) | |
24436 | ||
24437 | @geindex File locking | |
24438 | ||
24439 | @geindex Locking using files | |
24440 | ||
24441 | Provides a general interface for using files as locks. Can be used for | |
24442 | providing program level synchronization. | |
24443 | ||
24444 | @node GNAT MBBS_Discrete_Random g-mbdira ads,GNAT MBBS_Float_Random g-mbflra ads,GNAT Lock_Files g-locfil ads,The GNAT Library | |
9daee425 | 24445 | @anchor{gnat_rm/the_gnat_library gnat-mbbs-discrete-random-g-mbdira-ads}@anchor{383}@anchor{gnat_rm/the_gnat_library id82}@anchor{384} |
64d5610f ML |
24446 | @section @code{GNAT.MBBS_Discrete_Random} (@code{g-mbdira.ads}) |
24447 | ||
24448 | ||
24449 | @geindex GNAT.MBBS_Discrete_Random (g-mbdira.ads) | |
24450 | ||
24451 | @geindex Random number generation | |
24452 | ||
24453 | The original implementation of @code{Ada.Numerics.Discrete_Random}. Uses | |
24454 | a modified version of the Blum-Blum-Shub generator. | |
24455 | ||
24456 | @node GNAT MBBS_Float_Random g-mbflra ads,GNAT MD5 g-md5 ads,GNAT MBBS_Discrete_Random g-mbdira ads,The GNAT Library | |
9daee425 | 24457 | @anchor{gnat_rm/the_gnat_library gnat-mbbs-float-random-g-mbflra-ads}@anchor{385}@anchor{gnat_rm/the_gnat_library id83}@anchor{386} |
64d5610f ML |
24458 | @section @code{GNAT.MBBS_Float_Random} (@code{g-mbflra.ads}) |
24459 | ||
24460 | ||
24461 | @geindex GNAT.MBBS_Float_Random (g-mbflra.ads) | |
24462 | ||
24463 | @geindex Random number generation | |
24464 | ||
24465 | The original implementation of @code{Ada.Numerics.Float_Random}. Uses | |
24466 | a modified version of the Blum-Blum-Shub generator. | |
24467 | ||
24468 | @node GNAT MD5 g-md5 ads,GNAT Memory_Dump g-memdum ads,GNAT MBBS_Float_Random g-mbflra ads,The GNAT Library | |
9daee425 | 24469 | @anchor{gnat_rm/the_gnat_library gnat-md5-g-md5-ads}@anchor{387}@anchor{gnat_rm/the_gnat_library id84}@anchor{388} |
64d5610f ML |
24470 | @section @code{GNAT.MD5} (@code{g-md5.ads}) |
24471 | ||
24472 | ||
24473 | @geindex GNAT.MD5 (g-md5.ads) | |
24474 | ||
24475 | @geindex Message Digest MD5 | |
24476 | ||
24477 | Implements the MD5 Message-Digest Algorithm as described in RFC 1321, and | |
24478 | the HMAC-MD5 message authentication function as described in RFC 2104 and | |
24479 | FIPS PUB 198. | |
24480 | ||
24481 | @node GNAT Memory_Dump g-memdum ads,GNAT Most_Recent_Exception g-moreex ads,GNAT MD5 g-md5 ads,The GNAT Library | |
9daee425 | 24482 | @anchor{gnat_rm/the_gnat_library gnat-memory-dump-g-memdum-ads}@anchor{389}@anchor{gnat_rm/the_gnat_library id85}@anchor{38a} |
64d5610f ML |
24483 | @section @code{GNAT.Memory_Dump} (@code{g-memdum.ads}) |
24484 | ||
24485 | ||
24486 | @geindex GNAT.Memory_Dump (g-memdum.ads) | |
24487 | ||
24488 | @geindex Dump Memory | |
24489 | ||
24490 | Provides a convenient routine for dumping raw memory to either the | |
24491 | standard output or standard error files. Uses GNAT.IO for actual | |
24492 | output. | |
24493 | ||
24494 | @node GNAT Most_Recent_Exception g-moreex ads,GNAT OS_Lib g-os_lib ads,GNAT Memory_Dump g-memdum ads,The GNAT Library | |
9daee425 | 24495 | @anchor{gnat_rm/the_gnat_library gnat-most-recent-exception-g-moreex-ads}@anchor{38b}@anchor{gnat_rm/the_gnat_library id86}@anchor{38c} |
64d5610f ML |
24496 | @section @code{GNAT.Most_Recent_Exception} (@code{g-moreex.ads}) |
24497 | ||
24498 | ||
24499 | @geindex GNAT.Most_Recent_Exception (g-moreex.ads) | |
24500 | ||
24501 | @geindex Exception | |
24502 | @geindex obtaining most recent | |
24503 | ||
24504 | Provides access to the most recently raised exception. Can be used for | |
24505 | various logging purposes, including duplicating functionality of some | |
24506 | Ada 83 implementation dependent extensions. | |
24507 | ||
24508 | @node GNAT OS_Lib g-os_lib ads,GNAT Perfect_Hash_Generators g-pehage ads,GNAT Most_Recent_Exception g-moreex ads,The GNAT Library | |
9daee425 | 24509 | @anchor{gnat_rm/the_gnat_library gnat-os-lib-g-os-lib-ads}@anchor{38d}@anchor{gnat_rm/the_gnat_library id87}@anchor{38e} |
64d5610f ML |
24510 | @section @code{GNAT.OS_Lib} (@code{g-os_lib.ads}) |
24511 | ||
24512 | ||
24513 | @geindex GNAT.OS_Lib (g-os_lib.ads) | |
24514 | ||
24515 | @geindex Operating System interface | |
24516 | ||
24517 | @geindex Spawn capability | |
24518 | ||
24519 | Provides a range of target independent operating system interface functions, | |
24520 | including time/date management, file operations, subprocess management, | |
24521 | including a portable spawn procedure, and access to environment variables | |
24522 | and error return codes. | |
24523 | ||
24524 | @node GNAT Perfect_Hash_Generators g-pehage ads,GNAT Random_Numbers g-rannum ads,GNAT OS_Lib g-os_lib ads,The GNAT Library | |
9daee425 | 24525 | @anchor{gnat_rm/the_gnat_library gnat-perfect-hash-generators-g-pehage-ads}@anchor{38f}@anchor{gnat_rm/the_gnat_library id88}@anchor{390} |
64d5610f ML |
24526 | @section @code{GNAT.Perfect_Hash_Generators} (@code{g-pehage.ads}) |
24527 | ||
24528 | ||
24529 | @geindex GNAT.Perfect_Hash_Generators (g-pehage.ads) | |
24530 | ||
24531 | @geindex Hash functions | |
24532 | ||
24533 | Provides a generator of static minimal perfect hash functions. No | |
24534 | collisions occur and each item can be retrieved from the table in one | |
24535 | probe (perfect property). The hash table size corresponds to the exact | |
24536 | size of the key set and no larger (minimal property). The key set has to | |
eeba836b | 24537 | be known in advance (static property). The hash functions are also order |
64d5610f ML |
24538 | preserving. If w2 is inserted after w1 in the generator, their |
24539 | hashcode are in the same order. These hashing functions are very | |
24540 | convenient for use with realtime applications. | |
24541 | ||
24542 | @node GNAT Random_Numbers g-rannum ads,GNAT Regexp g-regexp ads,GNAT Perfect_Hash_Generators g-pehage ads,The GNAT Library | |
9daee425 | 24543 | @anchor{gnat_rm/the_gnat_library gnat-random-numbers-g-rannum-ads}@anchor{391}@anchor{gnat_rm/the_gnat_library id89}@anchor{392} |
64d5610f ML |
24544 | @section @code{GNAT.Random_Numbers} (@code{g-rannum.ads}) |
24545 | ||
24546 | ||
24547 | @geindex GNAT.Random_Numbers (g-rannum.ads) | |
24548 | ||
24549 | @geindex Random number generation | |
24550 | ||
24551 | Provides random number capabilities which extend those available in the | |
24552 | standard Ada library and are more convenient to use. | |
24553 | ||
24554 | @node GNAT Regexp g-regexp ads,GNAT Registry g-regist ads,GNAT Random_Numbers g-rannum ads,The GNAT Library | |
9daee425 | 24555 | @anchor{gnat_rm/the_gnat_library gnat-regexp-g-regexp-ads}@anchor{268}@anchor{gnat_rm/the_gnat_library id90}@anchor{393} |
64d5610f ML |
24556 | @section @code{GNAT.Regexp} (@code{g-regexp.ads}) |
24557 | ||
24558 | ||
24559 | @geindex GNAT.Regexp (g-regexp.ads) | |
24560 | ||
24561 | @geindex Regular expressions | |
24562 | ||
24563 | @geindex Pattern matching | |
24564 | ||
24565 | A simple implementation of regular expressions, using a subset of regular | |
24566 | expression syntax copied from familiar Unix style utilities. This is the | |
24567 | simplest of the three pattern matching packages provided, and is particularly | |
24568 | suitable for ‘file globbing’ applications. | |
24569 | ||
24570 | @node GNAT Registry g-regist ads,GNAT Regpat g-regpat ads,GNAT Regexp g-regexp ads,The GNAT Library | |
9daee425 | 24571 | @anchor{gnat_rm/the_gnat_library gnat-registry-g-regist-ads}@anchor{394}@anchor{gnat_rm/the_gnat_library id91}@anchor{395} |
64d5610f ML |
24572 | @section @code{GNAT.Registry} (@code{g-regist.ads}) |
24573 | ||
24574 | ||
24575 | @geindex GNAT.Registry (g-regist.ads) | |
24576 | ||
24577 | @geindex Windows Registry | |
24578 | ||
24579 | This is a high level binding to the Windows registry. It is possible to | |
24580 | do simple things like reading a key value, creating a new key. For full | |
24581 | registry API, but at a lower level of abstraction, refer to the Win32.Winreg | |
24582 | package provided with the Win32Ada binding | |
24583 | ||
24584 | @node GNAT Regpat g-regpat ads,GNAT Rewrite_Data g-rewdat ads,GNAT Registry g-regist ads,The GNAT Library | |
9daee425 | 24585 | @anchor{gnat_rm/the_gnat_library gnat-regpat-g-regpat-ads}@anchor{396}@anchor{gnat_rm/the_gnat_library id92}@anchor{397} |
64d5610f ML |
24586 | @section @code{GNAT.Regpat} (@code{g-regpat.ads}) |
24587 | ||
24588 | ||
24589 | @geindex GNAT.Regpat (g-regpat.ads) | |
24590 | ||
24591 | @geindex Regular expressions | |
24592 | ||
24593 | @geindex Pattern matching | |
24594 | ||
24595 | A complete implementation of Unix-style regular expression matching, copied | |
24596 | from the original V7 style regular expression library written in C by | |
24597 | Henry Spencer (and binary compatible with this C library). | |
24598 | ||
24599 | @node GNAT Rewrite_Data g-rewdat ads,GNAT Secondary_Stack_Info g-sestin ads,GNAT Regpat g-regpat ads,The GNAT Library | |
9daee425 | 24600 | @anchor{gnat_rm/the_gnat_library gnat-rewrite-data-g-rewdat-ads}@anchor{398}@anchor{gnat_rm/the_gnat_library id93}@anchor{399} |
64d5610f ML |
24601 | @section @code{GNAT.Rewrite_Data} (@code{g-rewdat.ads}) |
24602 | ||
24603 | ||
24604 | @geindex GNAT.Rewrite_Data (g-rewdat.ads) | |
24605 | ||
24606 | @geindex Rewrite data | |
24607 | ||
24608 | A unit to rewrite on-the-fly string occurrences in a stream of | |
24609 | data. The implementation has a very minimal memory footprint as the | |
24610 | full content to be processed is not loaded into memory all at once. This makes | |
24611 | this interface usable for large files or socket streams. | |
24612 | ||
24613 | @node GNAT Secondary_Stack_Info g-sestin ads,GNAT Semaphores g-semaph ads,GNAT Rewrite_Data g-rewdat ads,The GNAT Library | |
9daee425 | 24614 | @anchor{gnat_rm/the_gnat_library gnat-secondary-stack-info-g-sestin-ads}@anchor{39a}@anchor{gnat_rm/the_gnat_library id94}@anchor{39b} |
64d5610f ML |
24615 | @section @code{GNAT.Secondary_Stack_Info} (@code{g-sestin.ads}) |
24616 | ||
24617 | ||
24618 | @geindex GNAT.Secondary_Stack_Info (g-sestin.ads) | |
24619 | ||
24620 | @geindex Secondary Stack Info | |
24621 | ||
eeba836b | 24622 | Provides the capability to query the high water mark of the current task’s |
64d5610f ML |
24623 | secondary stack. |
24624 | ||
24625 | @node GNAT Semaphores g-semaph ads,GNAT Serial_Communications g-sercom ads,GNAT Secondary_Stack_Info g-sestin ads,The GNAT Library | |
9daee425 | 24626 | @anchor{gnat_rm/the_gnat_library gnat-semaphores-g-semaph-ads}@anchor{39c}@anchor{gnat_rm/the_gnat_library id95}@anchor{39d} |
64d5610f ML |
24627 | @section @code{GNAT.Semaphores} (@code{g-semaph.ads}) |
24628 | ||
24629 | ||
24630 | @geindex GNAT.Semaphores (g-semaph.ads) | |
24631 | ||
24632 | @geindex Semaphores | |
24633 | ||
24634 | Provides classic counting and binary semaphores using protected types. | |
24635 | ||
24636 | @node GNAT Serial_Communications g-sercom ads,GNAT SHA1 g-sha1 ads,GNAT Semaphores g-semaph ads,The GNAT Library | |
9daee425 | 24637 | @anchor{gnat_rm/the_gnat_library gnat-serial-communications-g-sercom-ads}@anchor{39e}@anchor{gnat_rm/the_gnat_library id96}@anchor{39f} |
64d5610f ML |
24638 | @section @code{GNAT.Serial_Communications} (@code{g-sercom.ads}) |
24639 | ||
24640 | ||
24641 | @geindex GNAT.Serial_Communications (g-sercom.ads) | |
24642 | ||
24643 | @geindex Serial_Communications | |
24644 | ||
24645 | Provides a simple interface to send and receive data over a serial | |
24646 | port. This is only supported on GNU/Linux and Windows. | |
24647 | ||
24648 | @node GNAT SHA1 g-sha1 ads,GNAT SHA224 g-sha224 ads,GNAT Serial_Communications g-sercom ads,The GNAT Library | |
9daee425 | 24649 | @anchor{gnat_rm/the_gnat_library gnat-sha1-g-sha1-ads}@anchor{3a0}@anchor{gnat_rm/the_gnat_library id97}@anchor{3a1} |
64d5610f ML |
24650 | @section @code{GNAT.SHA1} (@code{g-sha1.ads}) |
24651 | ||
24652 | ||
24653 | @geindex GNAT.SHA1 (g-sha1.ads) | |
24654 | ||
24655 | @geindex Secure Hash Algorithm SHA-1 | |
24656 | ||
24657 | Implements the SHA-1 Secure Hash Algorithm as described in FIPS PUB 180-3 | |
24658 | and RFC 3174, and the HMAC-SHA1 message authentication function as described | |
24659 | in RFC 2104 and FIPS PUB 198. | |
24660 | ||
24661 | @node GNAT SHA224 g-sha224 ads,GNAT SHA256 g-sha256 ads,GNAT SHA1 g-sha1 ads,The GNAT Library | |
9daee425 | 24662 | @anchor{gnat_rm/the_gnat_library gnat-sha224-g-sha224-ads}@anchor{3a2}@anchor{gnat_rm/the_gnat_library id98}@anchor{3a3} |
64d5610f ML |
24663 | @section @code{GNAT.SHA224} (@code{g-sha224.ads}) |
24664 | ||
24665 | ||
24666 | @geindex GNAT.SHA224 (g-sha224.ads) | |
24667 | ||
24668 | @geindex Secure Hash Algorithm SHA-224 | |
24669 | ||
24670 | Implements the SHA-224 Secure Hash Algorithm as described in FIPS PUB 180-3, | |
24671 | and the HMAC-SHA224 message authentication function as described | |
24672 | in RFC 2104 and FIPS PUB 198. | |
24673 | ||
24674 | @node GNAT SHA256 g-sha256 ads,GNAT SHA384 g-sha384 ads,GNAT SHA224 g-sha224 ads,The GNAT Library | |
9daee425 | 24675 | @anchor{gnat_rm/the_gnat_library gnat-sha256-g-sha256-ads}@anchor{3a4}@anchor{gnat_rm/the_gnat_library id99}@anchor{3a5} |
64d5610f ML |
24676 | @section @code{GNAT.SHA256} (@code{g-sha256.ads}) |
24677 | ||
24678 | ||
24679 | @geindex GNAT.SHA256 (g-sha256.ads) | |
24680 | ||
24681 | @geindex Secure Hash Algorithm SHA-256 | |
24682 | ||
24683 | Implements the SHA-256 Secure Hash Algorithm as described in FIPS PUB 180-3, | |
24684 | and the HMAC-SHA256 message authentication function as described | |
24685 | in RFC 2104 and FIPS PUB 198. | |
24686 | ||
24687 | @node GNAT SHA384 g-sha384 ads,GNAT SHA512 g-sha512 ads,GNAT SHA256 g-sha256 ads,The GNAT Library | |
9daee425 | 24688 | @anchor{gnat_rm/the_gnat_library gnat-sha384-g-sha384-ads}@anchor{3a6}@anchor{gnat_rm/the_gnat_library id100}@anchor{3a7} |
64d5610f ML |
24689 | @section @code{GNAT.SHA384} (@code{g-sha384.ads}) |
24690 | ||
24691 | ||
24692 | @geindex GNAT.SHA384 (g-sha384.ads) | |
24693 | ||
24694 | @geindex Secure Hash Algorithm SHA-384 | |
24695 | ||
24696 | Implements the SHA-384 Secure Hash Algorithm as described in FIPS PUB 180-3, | |
24697 | and the HMAC-SHA384 message authentication function as described | |
24698 | in RFC 2104 and FIPS PUB 198. | |
24699 | ||
24700 | @node GNAT SHA512 g-sha512 ads,GNAT Signals g-signal ads,GNAT SHA384 g-sha384 ads,The GNAT Library | |
9daee425 | 24701 | @anchor{gnat_rm/the_gnat_library gnat-sha512-g-sha512-ads}@anchor{3a8}@anchor{gnat_rm/the_gnat_library id101}@anchor{3a9} |
64d5610f ML |
24702 | @section @code{GNAT.SHA512} (@code{g-sha512.ads}) |
24703 | ||
24704 | ||
24705 | @geindex GNAT.SHA512 (g-sha512.ads) | |
24706 | ||
24707 | @geindex Secure Hash Algorithm SHA-512 | |
24708 | ||
24709 | Implements the SHA-512 Secure Hash Algorithm as described in FIPS PUB 180-3, | |
24710 | and the HMAC-SHA512 message authentication function as described | |
24711 | in RFC 2104 and FIPS PUB 198. | |
24712 | ||
24713 | @node GNAT Signals g-signal ads,GNAT Sockets g-socket ads,GNAT SHA512 g-sha512 ads,The GNAT Library | |
9daee425 | 24714 | @anchor{gnat_rm/the_gnat_library gnat-signals-g-signal-ads}@anchor{3aa}@anchor{gnat_rm/the_gnat_library id102}@anchor{3ab} |
64d5610f ML |
24715 | @section @code{GNAT.Signals} (@code{g-signal.ads}) |
24716 | ||
24717 | ||
24718 | @geindex GNAT.Signals (g-signal.ads) | |
24719 | ||
24720 | @geindex Signals | |
24721 | ||
24722 | Provides the ability to manipulate the blocked status of signals on supported | |
24723 | targets. | |
24724 | ||
24725 | @node GNAT Sockets g-socket ads,GNAT Source_Info g-souinf ads,GNAT Signals g-signal ads,The GNAT Library | |
9daee425 | 24726 | @anchor{gnat_rm/the_gnat_library gnat-sockets-g-socket-ads}@anchor{3ac}@anchor{gnat_rm/the_gnat_library id103}@anchor{3ad} |
64d5610f ML |
24727 | @section @code{GNAT.Sockets} (@code{g-socket.ads}) |
24728 | ||
24729 | ||
24730 | @geindex GNAT.Sockets (g-socket.ads) | |
24731 | ||
24732 | @geindex Sockets | |
24733 | ||
24734 | A high level and portable interface to develop sockets based applications. | |
24735 | This package is based on the sockets thin binding found in | |
24736 | @code{GNAT.Sockets.Thin}. Currently @code{GNAT.Sockets} is implemented | |
eeba836b | 24737 | on all native GNAT ports and on VxWorks cross ports. It is not implemented for |
64d5610f ML |
24738 | the LynxOS cross port. |
24739 | ||
24740 | @node GNAT Source_Info g-souinf ads,GNAT Spelling_Checker g-speche ads,GNAT Sockets g-socket ads,The GNAT Library | |
9daee425 | 24741 | @anchor{gnat_rm/the_gnat_library gnat-source-info-g-souinf-ads}@anchor{3ae}@anchor{gnat_rm/the_gnat_library id104}@anchor{3af} |
64d5610f ML |
24742 | @section @code{GNAT.Source_Info} (@code{g-souinf.ads}) |
24743 | ||
24744 | ||
24745 | @geindex GNAT.Source_Info (g-souinf.ads) | |
24746 | ||
24747 | @geindex Source Information | |
24748 | ||
24749 | Provides subprograms that give access to source code information known at | |
24750 | compile time, such as the current file name and line number. Also provides | |
24751 | subprograms yielding the date and time of the current compilation (like the | |
24752 | C macros @code{__DATE__} and @code{__TIME__}) | |
24753 | ||
24754 | @node GNAT Spelling_Checker g-speche ads,GNAT Spelling_Checker_Generic g-spchge ads,GNAT Source_Info g-souinf ads,The GNAT Library | |
9daee425 | 24755 | @anchor{gnat_rm/the_gnat_library gnat-spelling-checker-g-speche-ads}@anchor{3b0}@anchor{gnat_rm/the_gnat_library id105}@anchor{3b1} |
64d5610f ML |
24756 | @section @code{GNAT.Spelling_Checker} (@code{g-speche.ads}) |
24757 | ||
24758 | ||
24759 | @geindex GNAT.Spelling_Checker (g-speche.ads) | |
24760 | ||
24761 | @geindex Spell checking | |
24762 | ||
24763 | Provides a function for determining whether one string is a plausible | |
24764 | near misspelling of another string. | |
24765 | ||
24766 | @node GNAT Spelling_Checker_Generic g-spchge ads,GNAT Spitbol Patterns g-spipat ads,GNAT Spelling_Checker g-speche ads,The GNAT Library | |
9daee425 | 24767 | @anchor{gnat_rm/the_gnat_library gnat-spelling-checker-generic-g-spchge-ads}@anchor{3b2}@anchor{gnat_rm/the_gnat_library id106}@anchor{3b3} |
64d5610f ML |
24768 | @section @code{GNAT.Spelling_Checker_Generic} (@code{g-spchge.ads}) |
24769 | ||
24770 | ||
24771 | @geindex GNAT.Spelling_Checker_Generic (g-spchge.ads) | |
24772 | ||
24773 | @geindex Spell checking | |
24774 | ||
24775 | Provides a generic function that can be instantiated with a string type for | |
24776 | determining whether one string is a plausible near misspelling of another | |
24777 | string. | |
24778 | ||
24779 | @node GNAT Spitbol Patterns g-spipat ads,GNAT Spitbol g-spitbo ads,GNAT Spelling_Checker_Generic g-spchge ads,The GNAT Library | |
9daee425 | 24780 | @anchor{gnat_rm/the_gnat_library gnat-spitbol-patterns-g-spipat-ads}@anchor{3b4}@anchor{gnat_rm/the_gnat_library id107}@anchor{3b5} |
64d5610f ML |
24781 | @section @code{GNAT.Spitbol.Patterns} (@code{g-spipat.ads}) |
24782 | ||
24783 | ||
24784 | @geindex GNAT.Spitbol.Patterns (g-spipat.ads) | |
24785 | ||
24786 | @geindex SPITBOL pattern matching | |
24787 | ||
24788 | @geindex Pattern matching | |
24789 | ||
24790 | A complete implementation of SNOBOL4 style pattern matching. This is the | |
24791 | most elaborate of the pattern matching packages provided. It fully duplicates | |
24792 | the SNOBOL4 dynamic pattern construction and matching capabilities, using the | |
24793 | efficient algorithm developed by Robert Dewar for the SPITBOL system. | |
24794 | ||
24795 | @node GNAT Spitbol g-spitbo ads,GNAT Spitbol Table_Boolean g-sptabo ads,GNAT Spitbol Patterns g-spipat ads,The GNAT Library | |
9daee425 | 24796 | @anchor{gnat_rm/the_gnat_library gnat-spitbol-g-spitbo-ads}@anchor{3b6}@anchor{gnat_rm/the_gnat_library id108}@anchor{3b7} |
64d5610f ML |
24797 | @section @code{GNAT.Spitbol} (@code{g-spitbo.ads}) |
24798 | ||
24799 | ||
24800 | @geindex GNAT.Spitbol (g-spitbo.ads) | |
24801 | ||
24802 | @geindex SPITBOL interface | |
24803 | ||
24804 | The top level package of the collection of SPITBOL-style functionality, this | |
24805 | package provides basic SNOBOL4 string manipulation functions, such as | |
24806 | Pad, Reverse, Trim, Substr capability, as well as a generic table function | |
24807 | useful for constructing arbitrary mappings from strings in the style of | |
24808 | the SNOBOL4 TABLE function. | |
24809 | ||
24810 | @node GNAT Spitbol Table_Boolean g-sptabo ads,GNAT Spitbol Table_Integer g-sptain ads,GNAT Spitbol g-spitbo ads,The GNAT Library | |
9daee425 | 24811 | @anchor{gnat_rm/the_gnat_library gnat-spitbol-table-boolean-g-sptabo-ads}@anchor{3b8}@anchor{gnat_rm/the_gnat_library id109}@anchor{3b9} |
64d5610f ML |
24812 | @section @code{GNAT.Spitbol.Table_Boolean} (@code{g-sptabo.ads}) |
24813 | ||
24814 | ||
24815 | @geindex GNAT.Spitbol.Table_Boolean (g-sptabo.ads) | |
24816 | ||
24817 | @geindex Sets of strings | |
24818 | ||
24819 | @geindex SPITBOL Tables | |
24820 | ||
24821 | A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table} | |
24822 | for type @code{Standard.Boolean}, giving an implementation of sets of | |
24823 | string values. | |
24824 | ||
24825 | @node GNAT Spitbol Table_Integer g-sptain ads,GNAT Spitbol Table_VString g-sptavs ads,GNAT Spitbol Table_Boolean g-sptabo ads,The GNAT Library | |
9daee425 | 24826 | @anchor{gnat_rm/the_gnat_library gnat-spitbol-table-integer-g-sptain-ads}@anchor{3ba}@anchor{gnat_rm/the_gnat_library id110}@anchor{3bb} |
64d5610f ML |
24827 | @section @code{GNAT.Spitbol.Table_Integer} (@code{g-sptain.ads}) |
24828 | ||
24829 | ||
24830 | @geindex GNAT.Spitbol.Table_Integer (g-sptain.ads) | |
24831 | ||
24832 | @geindex Integer maps | |
24833 | ||
24834 | @geindex Maps | |
24835 | ||
24836 | @geindex SPITBOL Tables | |
24837 | ||
24838 | A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table} | |
24839 | for type @code{Standard.Integer}, giving an implementation of maps | |
24840 | from string to integer values. | |
24841 | ||
24842 | @node GNAT Spitbol Table_VString g-sptavs ads,GNAT SSE g-sse ads,GNAT Spitbol Table_Integer g-sptain ads,The GNAT Library | |
9daee425 | 24843 | @anchor{gnat_rm/the_gnat_library gnat-spitbol-table-vstring-g-sptavs-ads}@anchor{3bc}@anchor{gnat_rm/the_gnat_library id111}@anchor{3bd} |
64d5610f ML |
24844 | @section @code{GNAT.Spitbol.Table_VString} (@code{g-sptavs.ads}) |
24845 | ||
24846 | ||
24847 | @geindex GNAT.Spitbol.Table_VString (g-sptavs.ads) | |
24848 | ||
24849 | @geindex String maps | |
24850 | ||
24851 | @geindex Maps | |
24852 | ||
24853 | @geindex SPITBOL Tables | |
24854 | ||
24855 | A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table} for | |
24856 | a variable length string type, giving an implementation of general | |
24857 | maps from strings to strings. | |
24858 | ||
24859 | @node GNAT SSE g-sse ads,GNAT SSE Vector_Types g-ssvety ads,GNAT Spitbol Table_VString g-sptavs ads,The GNAT Library | |
9daee425 | 24860 | @anchor{gnat_rm/the_gnat_library gnat-sse-g-sse-ads}@anchor{3be}@anchor{gnat_rm/the_gnat_library id112}@anchor{3bf} |
64d5610f ML |
24861 | @section @code{GNAT.SSE} (@code{g-sse.ads}) |
24862 | ||
24863 | ||
24864 | @geindex GNAT.SSE (g-sse.ads) | |
24865 | ||
24866 | Root of a set of units aimed at offering Ada bindings to a subset of | |
24867 | the Intel(r) Streaming SIMD Extensions with GNAT on the x86 family of | |
24868 | targets. It exposes vector component types together with a general | |
24869 | introduction to the binding contents and use. | |
24870 | ||
24871 | @node GNAT SSE Vector_Types g-ssvety ads,GNAT String_Hash g-strhas ads,GNAT SSE g-sse ads,The GNAT Library | |
9daee425 | 24872 | @anchor{gnat_rm/the_gnat_library gnat-sse-vector-types-g-ssvety-ads}@anchor{3c0}@anchor{gnat_rm/the_gnat_library id113}@anchor{3c1} |
64d5610f ML |
24873 | @section @code{GNAT.SSE.Vector_Types} (@code{g-ssvety.ads}) |
24874 | ||
24875 | ||
24876 | @geindex GNAT.SSE.Vector_Types (g-ssvety.ads) | |
24877 | ||
24878 | SSE vector types for use with SSE related intrinsics. | |
24879 | ||
24880 | @node GNAT String_Hash g-strhas ads,GNAT Strings g-string ads,GNAT SSE Vector_Types g-ssvety ads,The GNAT Library | |
9daee425 | 24881 | @anchor{gnat_rm/the_gnat_library gnat-string-hash-g-strhas-ads}@anchor{3c2}@anchor{gnat_rm/the_gnat_library id114}@anchor{3c3} |
64d5610f ML |
24882 | @section @code{GNAT.String_Hash} (@code{g-strhas.ads}) |
24883 | ||
24884 | ||
24885 | @geindex GNAT.String_Hash (g-strhas.ads) | |
24886 | ||
24887 | @geindex Hash functions | |
24888 | ||
24889 | Provides a generic hash function working on arrays of scalars. Both the scalar | |
24890 | type and the hash result type are parameters. | |
24891 | ||
24892 | @node GNAT Strings g-string ads,GNAT String_Split g-strspl ads,GNAT String_Hash g-strhas ads,The GNAT Library | |
9daee425 | 24893 | @anchor{gnat_rm/the_gnat_library gnat-strings-g-string-ads}@anchor{3c4}@anchor{gnat_rm/the_gnat_library id115}@anchor{3c5} |
64d5610f ML |
24894 | @section @code{GNAT.Strings} (@code{g-string.ads}) |
24895 | ||
24896 | ||
24897 | @geindex GNAT.Strings (g-string.ads) | |
24898 | ||
24899 | Common String access types and related subprograms. Basically it | |
24900 | defines a string access and an array of string access types. | |
24901 | ||
24902 | @node GNAT String_Split g-strspl ads,GNAT Table g-table ads,GNAT Strings g-string ads,The GNAT Library | |
9daee425 | 24903 | @anchor{gnat_rm/the_gnat_library gnat-string-split-g-strspl-ads}@anchor{3c6}@anchor{gnat_rm/the_gnat_library id116}@anchor{3c7} |
64d5610f ML |
24904 | @section @code{GNAT.String_Split} (@code{g-strspl.ads}) |
24905 | ||
24906 | ||
24907 | @geindex GNAT.String_Split (g-strspl.ads) | |
24908 | ||
24909 | @geindex String splitter | |
24910 | ||
24911 | Useful string manipulation routines: given a set of separators, split | |
24912 | a string wherever the separators appear, and provide direct access | |
24913 | to the resulting slices. This package is instantiated from | |
24914 | @code{GNAT.Array_Split}. | |
24915 | ||
24916 | @node GNAT Table g-table ads,GNAT Task_Lock g-tasloc ads,GNAT String_Split g-strspl ads,The GNAT Library | |
9daee425 | 24917 | @anchor{gnat_rm/the_gnat_library gnat-table-g-table-ads}@anchor{3c8}@anchor{gnat_rm/the_gnat_library id117}@anchor{3c9} |
64d5610f ML |
24918 | @section @code{GNAT.Table} (@code{g-table.ads}) |
24919 | ||
24920 | ||
24921 | @geindex GNAT.Table (g-table.ads) | |
24922 | ||
24923 | @geindex Table implementation | |
24924 | ||
24925 | @geindex Arrays | |
24926 | @geindex extendable | |
24927 | ||
24928 | A generic package providing a single dimension array abstraction where the | |
24929 | length of the array can be dynamically modified. | |
24930 | ||
24931 | This package provides a facility similar to that of @code{GNAT.Dynamic_Tables}, | |
24932 | except that this package declares a single instance of the table type, | |
24933 | while an instantiation of @code{GNAT.Dynamic_Tables} creates a type that can be | |
24934 | used to define dynamic instances of the table. | |
24935 | ||
24936 | @node GNAT Task_Lock g-tasloc ads,GNAT Time_Stamp g-timsta ads,GNAT Table g-table ads,The GNAT Library | |
9daee425 | 24937 | @anchor{gnat_rm/the_gnat_library gnat-task-lock-g-tasloc-ads}@anchor{3ca}@anchor{gnat_rm/the_gnat_library id118}@anchor{3cb} |
64d5610f ML |
24938 | @section @code{GNAT.Task_Lock} (@code{g-tasloc.ads}) |
24939 | ||
24940 | ||
24941 | @geindex GNAT.Task_Lock (g-tasloc.ads) | |
24942 | ||
24943 | @geindex Task synchronization | |
24944 | ||
24945 | @geindex Task locking | |
24946 | ||
24947 | @geindex Locking | |
24948 | ||
24949 | A very simple facility for locking and unlocking sections of code using a | |
24950 | single global task lock. Appropriate for use in situations where contention | |
24951 | between tasks is very rarely expected. | |
24952 | ||
24953 | @node GNAT Time_Stamp g-timsta ads,GNAT Threads g-thread ads,GNAT Task_Lock g-tasloc ads,The GNAT Library | |
9daee425 | 24954 | @anchor{gnat_rm/the_gnat_library gnat-time-stamp-g-timsta-ads}@anchor{3cc}@anchor{gnat_rm/the_gnat_library id119}@anchor{3cd} |
64d5610f ML |
24955 | @section @code{GNAT.Time_Stamp} (@code{g-timsta.ads}) |
24956 | ||
24957 | ||
24958 | @geindex GNAT.Time_Stamp (g-timsta.ads) | |
24959 | ||
24960 | @geindex Time stamp | |
24961 | ||
24962 | @geindex Current time | |
24963 | ||
24964 | Provides a simple function that returns a string YYYY-MM-DD HH:MM:SS.SS that | |
24965 | represents the current date and time in ISO 8601 format. This is a very simple | |
24966 | routine with minimal code and there are no dependencies on any other unit. | |
24967 | ||
24968 | @node GNAT Threads g-thread ads,GNAT Traceback g-traceb ads,GNAT Time_Stamp g-timsta ads,The GNAT Library | |
9daee425 | 24969 | @anchor{gnat_rm/the_gnat_library gnat-threads-g-thread-ads}@anchor{3ce}@anchor{gnat_rm/the_gnat_library id120}@anchor{3cf} |
64d5610f ML |
24970 | @section @code{GNAT.Threads} (@code{g-thread.ads}) |
24971 | ||
24972 | ||
24973 | @geindex GNAT.Threads (g-thread.ads) | |
24974 | ||
24975 | @geindex Foreign threads | |
24976 | ||
24977 | @geindex Threads | |
24978 | @geindex foreign | |
24979 | ||
24980 | Provides facilities for dealing with foreign threads which need to be known | |
24981 | by the GNAT run-time system. Consult the documentation of this package for | |
24982 | further details if your program has threads that are created by a non-Ada | |
24983 | environment which then accesses Ada code. | |
24984 | ||
24985 | @node GNAT Traceback g-traceb ads,GNAT Traceback Symbolic g-trasym ads,GNAT Threads g-thread ads,The GNAT Library | |
9daee425 | 24986 | @anchor{gnat_rm/the_gnat_library gnat-traceback-g-traceb-ads}@anchor{3d0}@anchor{gnat_rm/the_gnat_library id121}@anchor{3d1} |
64d5610f ML |
24987 | @section @code{GNAT.Traceback} (@code{g-traceb.ads}) |
24988 | ||
24989 | ||
24990 | @geindex GNAT.Traceback (g-traceb.ads) | |
24991 | ||
24992 | @geindex Trace back facilities | |
24993 | ||
24994 | Provides a facility for obtaining non-symbolic traceback information, useful | |
24995 | in various debugging situations. | |
24996 | ||
eeba836b | 24997 | @node GNAT Traceback Symbolic g-trasym ads,GNAT UTF_32 g-utf_32 ads,GNAT Traceback g-traceb ads,The GNAT Library |
9daee425 | 24998 | @anchor{gnat_rm/the_gnat_library gnat-traceback-symbolic-g-trasym-ads}@anchor{3d2}@anchor{gnat_rm/the_gnat_library id122}@anchor{3d3} |
64d5610f ML |
24999 | @section @code{GNAT.Traceback.Symbolic} (@code{g-trasym.ads}) |
25000 | ||
25001 | ||
25002 | @geindex GNAT.Traceback.Symbolic (g-trasym.ads) | |
25003 | ||
25004 | @geindex Trace back facilities | |
25005 | ||
eeba836b | 25006 | @node GNAT UTF_32 g-utf_32 ads,GNAT UTF_32_Spelling_Checker g-u3spch ads,GNAT Traceback Symbolic g-trasym ads,The GNAT Library |
9daee425 | 25007 | @anchor{gnat_rm/the_gnat_library gnat-utf-32-g-utf-32-ads}@anchor{3d4}@anchor{gnat_rm/the_gnat_library id123}@anchor{3d5} |
eeba836b | 25008 | @section @code{GNAT.UTF_32} (@code{g-utf_32.ads}) |
64d5610f ML |
25009 | |
25010 | ||
eeba836b | 25011 | @geindex GNAT.UTF_32 (g-utf_32.ads) |
64d5610f ML |
25012 | |
25013 | @geindex Wide character codes | |
25014 | ||
25015 | This is a package intended to be used in conjunction with the | |
25016 | @code{Wide_Character} type in Ada 95 and the | |
25017 | @code{Wide_Wide_Character} type in Ada 2005 (available | |
25018 | in @code{GNAT} in Ada 2005 mode). This package contains | |
25019 | Unicode categorization routines, as well as lexical | |
25020 | categorization routines corresponding to the Ada 2005 | |
25021 | lexical rules for identifiers and strings, and also a | |
25022 | lower case to upper case fold routine corresponding to | |
25023 | the Ada 2005 rules for identifier equivalence. | |
25024 | ||
eeba836b | 25025 | @node GNAT UTF_32_Spelling_Checker g-u3spch ads,GNAT Wide_Spelling_Checker g-wispch ads,GNAT UTF_32 g-utf_32 ads,The GNAT Library |
9daee425 | 25026 | @anchor{gnat_rm/the_gnat_library gnat-utf-32-spelling-checker-g-u3spch-ads}@anchor{3d6}@anchor{gnat_rm/the_gnat_library id124}@anchor{3d7} |
eeba836b | 25027 | @section @code{GNAT.UTF_32_Spelling_Checker} (@code{g-u3spch.ads}) |
64d5610f ML |
25028 | |
25029 | ||
eeba836b | 25030 | @geindex GNAT.UTF_32_Spelling_Checker (g-u3spch.ads) |
64d5610f ML |
25031 | |
25032 | @geindex Spell checking | |
25033 | ||
25034 | Provides a function for determining whether one wide wide string is a plausible | |
25035 | near misspelling of another wide wide string, where the strings are represented | |
25036 | using the UTF_32_String type defined in System.Wch_Cnv. | |
25037 | ||
eeba836b | 25038 | @node GNAT Wide_Spelling_Checker g-wispch ads,GNAT Wide_String_Split g-wistsp ads,GNAT UTF_32_Spelling_Checker g-u3spch ads,The GNAT Library |
9daee425 | 25039 | @anchor{gnat_rm/the_gnat_library gnat-wide-spelling-checker-g-wispch-ads}@anchor{3d8}@anchor{gnat_rm/the_gnat_library id125}@anchor{3d9} |
64d5610f ML |
25040 | @section @code{GNAT.Wide_Spelling_Checker} (@code{g-wispch.ads}) |
25041 | ||
25042 | ||
25043 | @geindex GNAT.Wide_Spelling_Checker (g-wispch.ads) | |
25044 | ||
25045 | @geindex Spell checking | |
25046 | ||
25047 | Provides a function for determining whether one wide string is a plausible | |
25048 | near misspelling of another wide string. | |
25049 | ||
25050 | @node GNAT Wide_String_Split g-wistsp ads,GNAT Wide_Wide_Spelling_Checker g-zspche ads,GNAT Wide_Spelling_Checker g-wispch ads,The GNAT Library | |
9daee425 | 25051 | @anchor{gnat_rm/the_gnat_library gnat-wide-string-split-g-wistsp-ads}@anchor{3da}@anchor{gnat_rm/the_gnat_library id126}@anchor{3db} |
64d5610f ML |
25052 | @section @code{GNAT.Wide_String_Split} (@code{g-wistsp.ads}) |
25053 | ||
25054 | ||
25055 | @geindex GNAT.Wide_String_Split (g-wistsp.ads) | |
25056 | ||
25057 | @geindex Wide_String splitter | |
25058 | ||
25059 | Useful wide string manipulation routines: given a set of separators, split | |
25060 | a wide string wherever the separators appear, and provide direct access | |
25061 | to the resulting slices. This package is instantiated from | |
25062 | @code{GNAT.Array_Split}. | |
25063 | ||
25064 | @node GNAT Wide_Wide_Spelling_Checker g-zspche ads,GNAT Wide_Wide_String_Split g-zistsp ads,GNAT Wide_String_Split g-wistsp ads,The GNAT Library | |
9daee425 | 25065 | @anchor{gnat_rm/the_gnat_library gnat-wide-wide-spelling-checker-g-zspche-ads}@anchor{3dc}@anchor{gnat_rm/the_gnat_library id127}@anchor{3dd} |
64d5610f ML |
25066 | @section @code{GNAT.Wide_Wide_Spelling_Checker} (@code{g-zspche.ads}) |
25067 | ||
25068 | ||
25069 | @geindex GNAT.Wide_Wide_Spelling_Checker (g-zspche.ads) | |
25070 | ||
25071 | @geindex Spell checking | |
25072 | ||
25073 | Provides a function for determining whether one wide wide string is a plausible | |
25074 | near misspelling of another wide wide string. | |
25075 | ||
25076 | @node GNAT Wide_Wide_String_Split g-zistsp ads,Interfaces C Extensions i-cexten ads,GNAT Wide_Wide_Spelling_Checker g-zspche ads,The GNAT Library | |
9daee425 | 25077 | @anchor{gnat_rm/the_gnat_library gnat-wide-wide-string-split-g-zistsp-ads}@anchor{3de}@anchor{gnat_rm/the_gnat_library id128}@anchor{3df} |
64d5610f ML |
25078 | @section @code{GNAT.Wide_Wide_String_Split} (@code{g-zistsp.ads}) |
25079 | ||
25080 | ||
25081 | @geindex GNAT.Wide_Wide_String_Split (g-zistsp.ads) | |
25082 | ||
25083 | @geindex Wide_Wide_String splitter | |
25084 | ||
25085 | Useful wide wide string manipulation routines: given a set of separators, split | |
25086 | a wide wide string wherever the separators appear, and provide direct access | |
25087 | to the resulting slices. This package is instantiated from | |
25088 | @code{GNAT.Array_Split}. | |
25089 | ||
25090 | @node Interfaces C Extensions i-cexten ads,Interfaces C Streams i-cstrea ads,GNAT Wide_Wide_String_Split g-zistsp ads,The GNAT Library | |
9daee425 | 25091 | @anchor{gnat_rm/the_gnat_library id129}@anchor{3e0}@anchor{gnat_rm/the_gnat_library interfaces-c-extensions-i-cexten-ads}@anchor{3e1} |
64d5610f ML |
25092 | @section @code{Interfaces.C.Extensions} (@code{i-cexten.ads}) |
25093 | ||
25094 | ||
25095 | @geindex Interfaces.C.Extensions (i-cexten.ads) | |
25096 | ||
25097 | This package contains additional C-related definitions, intended | |
25098 | for use with either manually or automatically generated bindings | |
25099 | to C libraries. | |
25100 | ||
25101 | @node Interfaces C Streams i-cstrea ads,Interfaces Packed_Decimal i-pacdec ads,Interfaces C Extensions i-cexten ads,The GNAT Library | |
9daee425 | 25102 | @anchor{gnat_rm/the_gnat_library id130}@anchor{3e2}@anchor{gnat_rm/the_gnat_library interfaces-c-streams-i-cstrea-ads}@anchor{3e3} |
64d5610f ML |
25103 | @section @code{Interfaces.C.Streams} (@code{i-cstrea.ads}) |
25104 | ||
25105 | ||
25106 | @geindex Interfaces.C.Streams (i-cstrea.ads) | |
25107 | ||
25108 | @geindex C streams | |
25109 | @geindex interfacing | |
25110 | ||
25111 | This package is a binding for the most commonly used operations | |
25112 | on C streams. | |
25113 | ||
25114 | @node Interfaces Packed_Decimal i-pacdec ads,Interfaces VxWorks i-vxwork ads,Interfaces C Streams i-cstrea ads,The GNAT Library | |
9daee425 | 25115 | @anchor{gnat_rm/the_gnat_library id131}@anchor{3e4}@anchor{gnat_rm/the_gnat_library interfaces-packed-decimal-i-pacdec-ads}@anchor{3e5} |
64d5610f ML |
25116 | @section @code{Interfaces.Packed_Decimal} (@code{i-pacdec.ads}) |
25117 | ||
25118 | ||
25119 | @geindex Interfaces.Packed_Decimal (i-pacdec.ads) | |
25120 | ||
25121 | @geindex IBM Packed Format | |
25122 | ||
25123 | @geindex Packed Decimal | |
25124 | ||
25125 | This package provides a set of routines for conversions to and | |
25126 | from a packed decimal format compatible with that used on IBM | |
25127 | mainframes. | |
25128 | ||
25129 | @node Interfaces VxWorks i-vxwork ads,Interfaces VxWorks Int_Connection i-vxinco ads,Interfaces Packed_Decimal i-pacdec ads,The GNAT Library | |
9daee425 | 25130 | @anchor{gnat_rm/the_gnat_library id132}@anchor{3e6}@anchor{gnat_rm/the_gnat_library interfaces-vxworks-i-vxwork-ads}@anchor{3e7} |
64d5610f ML |
25131 | @section @code{Interfaces.VxWorks} (@code{i-vxwork.ads}) |
25132 | ||
25133 | ||
25134 | @geindex Interfaces.VxWorks (i-vxwork.ads) | |
25135 | ||
25136 | @geindex Interfacing to VxWorks | |
25137 | ||
25138 | @geindex VxWorks | |
25139 | @geindex interfacing | |
25140 | ||
25141 | This package provides a limited binding to the VxWorks API. | |
25142 | In particular, it interfaces with the | |
25143 | VxWorks hardware interrupt facilities. | |
25144 | ||
25145 | @node Interfaces VxWorks Int_Connection i-vxinco ads,Interfaces VxWorks IO i-vxwoio ads,Interfaces VxWorks i-vxwork ads,The GNAT Library | |
9daee425 | 25146 | @anchor{gnat_rm/the_gnat_library id133}@anchor{3e8}@anchor{gnat_rm/the_gnat_library interfaces-vxworks-int-connection-i-vxinco-ads}@anchor{3e9} |
64d5610f ML |
25147 | @section @code{Interfaces.VxWorks.Int_Connection} (@code{i-vxinco.ads}) |
25148 | ||
25149 | ||
25150 | @geindex Interfaces.VxWorks.Int_Connection (i-vxinco.ads) | |
25151 | ||
25152 | @geindex Interfacing to VxWorks | |
25153 | ||
25154 | @geindex VxWorks | |
25155 | @geindex interfacing | |
25156 | ||
25157 | This package provides a way for users to replace the use of | |
25158 | intConnect() with a custom routine for installing interrupt | |
25159 | handlers. | |
25160 | ||
25161 | @node Interfaces VxWorks IO i-vxwoio ads,System Address_Image s-addima ads,Interfaces VxWorks Int_Connection i-vxinco ads,The GNAT Library | |
9daee425 | 25162 | @anchor{gnat_rm/the_gnat_library id134}@anchor{3ea}@anchor{gnat_rm/the_gnat_library interfaces-vxworks-io-i-vxwoio-ads}@anchor{3eb} |
64d5610f ML |
25163 | @section @code{Interfaces.VxWorks.IO} (@code{i-vxwoio.ads}) |
25164 | ||
25165 | ||
25166 | @geindex Interfaces.VxWorks.IO (i-vxwoio.ads) | |
25167 | ||
25168 | @geindex Interfacing to VxWorks' I/O | |
25169 | ||
25170 | @geindex VxWorks | |
25171 | @geindex I/O interfacing | |
25172 | ||
25173 | @geindex VxWorks | |
25174 | @geindex Get_Immediate | |
25175 | ||
25176 | @geindex Get_Immediate | |
25177 | @geindex VxWorks | |
25178 | ||
25179 | This package provides a binding to the ioctl (IO/Control) | |
25180 | function of VxWorks, defining a set of option values and | |
25181 | function codes. A particular use of this package is | |
25182 | to enable the use of Get_Immediate under VxWorks. | |
25183 | ||
25184 | @node System Address_Image s-addima ads,System Assertions s-assert ads,Interfaces VxWorks IO i-vxwoio ads,The GNAT Library | |
9daee425 | 25185 | @anchor{gnat_rm/the_gnat_library id135}@anchor{3ec}@anchor{gnat_rm/the_gnat_library system-address-image-s-addima-ads}@anchor{3ed} |
64d5610f ML |
25186 | @section @code{System.Address_Image} (@code{s-addima.ads}) |
25187 | ||
25188 | ||
25189 | @geindex System.Address_Image (s-addima.ads) | |
25190 | ||
25191 | @geindex Address image | |
25192 | ||
25193 | @geindex Image | |
25194 | @geindex of an address | |
25195 | ||
25196 | This function provides a useful debugging | |
25197 | function that gives an (implementation dependent) | |
25198 | string which identifies an address. | |
25199 | ||
25200 | @node System Assertions s-assert ads,System Atomic_Counters s-atocou ads,System Address_Image s-addima ads,The GNAT Library | |
9daee425 | 25201 | @anchor{gnat_rm/the_gnat_library id136}@anchor{3ee}@anchor{gnat_rm/the_gnat_library system-assertions-s-assert-ads}@anchor{3ef} |
64d5610f ML |
25202 | @section @code{System.Assertions} (@code{s-assert.ads}) |
25203 | ||
25204 | ||
25205 | @geindex System.Assertions (s-assert.ads) | |
25206 | ||
25207 | @geindex Assertions | |
25208 | ||
25209 | @geindex Assert_Failure | |
25210 | @geindex exception | |
25211 | ||
25212 | This package provides the declaration of the exception raised | |
25213 | by an run-time assertion failure, as well as the routine that | |
25214 | is used internally to raise this assertion. | |
25215 | ||
25216 | @node System Atomic_Counters s-atocou ads,System Memory s-memory ads,System Assertions s-assert ads,The GNAT Library | |
9daee425 | 25217 | @anchor{gnat_rm/the_gnat_library id137}@anchor{3f0}@anchor{gnat_rm/the_gnat_library system-atomic-counters-s-atocou-ads}@anchor{3f1} |
64d5610f ML |
25218 | @section @code{System.Atomic_Counters} (@code{s-atocou.ads}) |
25219 | ||
25220 | ||
25221 | @geindex System.Atomic_Counters (s-atocou.ads) | |
25222 | ||
25223 | This package provides the declaration of an atomic counter type, | |
25224 | together with efficient routines (using hardware | |
25225 | synchronization primitives) for incrementing, decrementing, | |
25226 | and testing of these counters. This package is implemented | |
25227 | on most targets, including all Alpha, AARCH64, ARM, ia64, PowerPC, SPARC V9, | |
25228 | x86, and x86_64 platforms. | |
25229 | ||
25230 | @node System Memory s-memory ads,System Multiprocessors s-multip ads,System Atomic_Counters s-atocou ads,The GNAT Library | |
9daee425 | 25231 | @anchor{gnat_rm/the_gnat_library id138}@anchor{3f2}@anchor{gnat_rm/the_gnat_library system-memory-s-memory-ads}@anchor{3f3} |
64d5610f ML |
25232 | @section @code{System.Memory} (@code{s-memory.ads}) |
25233 | ||
25234 | ||
25235 | @geindex System.Memory (s-memory.ads) | |
25236 | ||
25237 | @geindex Memory allocation | |
25238 | ||
25239 | This package provides the interface to the low level routines used | |
25240 | by the generated code for allocation and freeing storage for the | |
25241 | default storage pool (analogous to the C routines malloc and free). | |
25242 | It also provides a reallocation interface analogous to the C routine | |
25243 | realloc. The body of this unit may be modified to provide alternative | |
25244 | allocation mechanisms for the default pool, and in addition, direct | |
25245 | calls to this unit may be made for low level allocation uses (for | |
25246 | example see the body of @code{GNAT.Tables}). | |
25247 | ||
25248 | @node System Multiprocessors s-multip ads,System Multiprocessors Dispatching_Domains s-mudido ads,System Memory s-memory ads,The GNAT Library | |
9daee425 | 25249 | @anchor{gnat_rm/the_gnat_library id139}@anchor{3f4}@anchor{gnat_rm/the_gnat_library system-multiprocessors-s-multip-ads}@anchor{3f5} |
64d5610f ML |
25250 | @section @code{System.Multiprocessors} (@code{s-multip.ads}) |
25251 | ||
25252 | ||
25253 | @geindex System.Multiprocessors (s-multip.ads) | |
25254 | ||
25255 | @geindex Multiprocessor interface | |
25256 | ||
25257 | This is an Ada 2012 unit defined in the Ada 2012 Reference Manual, but | |
25258 | in GNAT we also make it available in Ada 95 and Ada 2005 (where it is | |
25259 | technically an implementation-defined addition). | |
25260 | ||
25261 | @node System Multiprocessors Dispatching_Domains s-mudido ads,System Partition_Interface s-parint ads,System Multiprocessors s-multip ads,The GNAT Library | |
9daee425 | 25262 | @anchor{gnat_rm/the_gnat_library id140}@anchor{3f6}@anchor{gnat_rm/the_gnat_library system-multiprocessors-dispatching-domains-s-mudido-ads}@anchor{3f7} |
64d5610f ML |
25263 | @section @code{System.Multiprocessors.Dispatching_Domains} (@code{s-mudido.ads}) |
25264 | ||
25265 | ||
25266 | @geindex System.Multiprocessors.Dispatching_Domains (s-mudido.ads) | |
25267 | ||
25268 | @geindex Multiprocessor interface | |
25269 | ||
25270 | This is an Ada 2012 unit defined in the Ada 2012 Reference Manual, but | |
25271 | in GNAT we also make it available in Ada 95 and Ada 2005 (where it is | |
25272 | technically an implementation-defined addition). | |
25273 | ||
25274 | @node System Partition_Interface s-parint ads,System Pool_Global s-pooglo ads,System Multiprocessors Dispatching_Domains s-mudido ads,The GNAT Library | |
9daee425 | 25275 | @anchor{gnat_rm/the_gnat_library id141}@anchor{3f8}@anchor{gnat_rm/the_gnat_library system-partition-interface-s-parint-ads}@anchor{3f9} |
64d5610f ML |
25276 | @section @code{System.Partition_Interface} (@code{s-parint.ads}) |
25277 | ||
25278 | ||
25279 | @geindex System.Partition_Interface (s-parint.ads) | |
25280 | ||
25281 | @geindex Partition interfacing functions | |
25282 | ||
25283 | This package provides facilities for partition interfacing. It | |
25284 | is used primarily in a distribution context when using Annex E | |
25285 | with @code{GLADE}. | |
25286 | ||
25287 | @node System Pool_Global s-pooglo ads,System Pool_Local s-pooloc ads,System Partition_Interface s-parint ads,The GNAT Library | |
9daee425 | 25288 | @anchor{gnat_rm/the_gnat_library id142}@anchor{3fa}@anchor{gnat_rm/the_gnat_library system-pool-global-s-pooglo-ads}@anchor{3fb} |
64d5610f ML |
25289 | @section @code{System.Pool_Global} (@code{s-pooglo.ads}) |
25290 | ||
25291 | ||
25292 | @geindex System.Pool_Global (s-pooglo.ads) | |
25293 | ||
25294 | @geindex Storage pool | |
25295 | @geindex global | |
25296 | ||
25297 | @geindex Global storage pool | |
25298 | ||
25299 | This package provides a storage pool that is equivalent to the default | |
25300 | storage pool used for access types for which no pool is specifically | |
25301 | declared. It uses malloc/free to allocate/free and does not attempt to | |
25302 | do any automatic reclamation. | |
25303 | ||
25304 | @node System Pool_Local s-pooloc ads,System Restrictions s-restri ads,System Pool_Global s-pooglo ads,The GNAT Library | |
9daee425 | 25305 | @anchor{gnat_rm/the_gnat_library id143}@anchor{3fc}@anchor{gnat_rm/the_gnat_library system-pool-local-s-pooloc-ads}@anchor{3fd} |
64d5610f ML |
25306 | @section @code{System.Pool_Local} (@code{s-pooloc.ads}) |
25307 | ||
25308 | ||
25309 | @geindex System.Pool_Local (s-pooloc.ads) | |
25310 | ||
25311 | @geindex Storage pool | |
25312 | @geindex local | |
25313 | ||
25314 | @geindex Local storage pool | |
25315 | ||
25316 | This package provides a storage pool that is intended for use with locally | |
25317 | defined access types. It uses malloc/free for allocate/free, and maintains | |
25318 | a list of allocated blocks, so that all storage allocated for the pool can | |
25319 | be freed automatically when the pool is finalized. | |
25320 | ||
25321 | @node System Restrictions s-restri ads,System Rident s-rident ads,System Pool_Local s-pooloc ads,The GNAT Library | |
9daee425 | 25322 | @anchor{gnat_rm/the_gnat_library id144}@anchor{3fe}@anchor{gnat_rm/the_gnat_library system-restrictions-s-restri-ads}@anchor{3ff} |
64d5610f ML |
25323 | @section @code{System.Restrictions} (@code{s-restri.ads}) |
25324 | ||
25325 | ||
25326 | @geindex System.Restrictions (s-restri.ads) | |
25327 | ||
25328 | @geindex Run-time restrictions access | |
25329 | ||
25330 | This package provides facilities for accessing at run time | |
25331 | the status of restrictions specified at compile time for | |
25332 | the partition. Information is available both with regard | |
25333 | to actual restrictions specified, and with regard to | |
25334 | compiler determined information on which restrictions | |
25335 | are violated by one or more packages in the partition. | |
25336 | ||
25337 | @node System Rident s-rident ads,System Strings Stream_Ops s-ststop ads,System Restrictions s-restri ads,The GNAT Library | |
9daee425 | 25338 | @anchor{gnat_rm/the_gnat_library id145}@anchor{400}@anchor{gnat_rm/the_gnat_library system-rident-s-rident-ads}@anchor{401} |
64d5610f ML |
25339 | @section @code{System.Rident} (@code{s-rident.ads}) |
25340 | ||
25341 | ||
25342 | @geindex System.Rident (s-rident.ads) | |
25343 | ||
25344 | @geindex Restrictions definitions | |
25345 | ||
25346 | This package provides definitions of the restrictions | |
25347 | identifiers supported by GNAT, and also the format of | |
25348 | the restrictions provided in package System.Restrictions. | |
25349 | It is not normally necessary to @code{with} this generic package | |
25350 | since the necessary instantiation is included in | |
25351 | package System.Restrictions. | |
25352 | ||
25353 | @node System Strings Stream_Ops s-ststop ads,System Unsigned_Types s-unstyp ads,System Rident s-rident ads,The GNAT Library | |
9daee425 | 25354 | @anchor{gnat_rm/the_gnat_library id146}@anchor{402}@anchor{gnat_rm/the_gnat_library system-strings-stream-ops-s-ststop-ads}@anchor{403} |
64d5610f ML |
25355 | @section @code{System.Strings.Stream_Ops} (@code{s-ststop.ads}) |
25356 | ||
25357 | ||
25358 | @geindex System.Strings.Stream_Ops (s-ststop.ads) | |
25359 | ||
25360 | @geindex Stream operations | |
25361 | ||
25362 | @geindex String stream operations | |
25363 | ||
25364 | This package provides a set of stream subprograms for standard string types. | |
25365 | It is intended primarily to support implicit use of such subprograms when | |
25366 | stream attributes are applied to string types, but the subprograms in this | |
25367 | package can be used directly by application programs. | |
25368 | ||
25369 | @node System Unsigned_Types s-unstyp ads,System Wch_Cnv s-wchcnv ads,System Strings Stream_Ops s-ststop ads,The GNAT Library | |
9daee425 | 25370 | @anchor{gnat_rm/the_gnat_library id147}@anchor{404}@anchor{gnat_rm/the_gnat_library system-unsigned-types-s-unstyp-ads}@anchor{405} |
64d5610f ML |
25371 | @section @code{System.Unsigned_Types} (@code{s-unstyp.ads}) |
25372 | ||
25373 | ||
25374 | @geindex System.Unsigned_Types (s-unstyp.ads) | |
25375 | ||
25376 | This package contains definitions of standard unsigned types that | |
25377 | correspond in size to the standard signed types declared in Standard, | |
25378 | and (unlike the types in Interfaces) have corresponding names. It | |
25379 | also contains some related definitions for other specialized types | |
25380 | used by the compiler in connection with packed array types. | |
25381 | ||
25382 | @node System Wch_Cnv s-wchcnv ads,System Wch_Con s-wchcon ads,System Unsigned_Types s-unstyp ads,The GNAT Library | |
9daee425 | 25383 | @anchor{gnat_rm/the_gnat_library id148}@anchor{406}@anchor{gnat_rm/the_gnat_library system-wch-cnv-s-wchcnv-ads}@anchor{407} |
64d5610f ML |
25384 | @section @code{System.Wch_Cnv} (@code{s-wchcnv.ads}) |
25385 | ||
25386 | ||
25387 | @geindex System.Wch_Cnv (s-wchcnv.ads) | |
25388 | ||
25389 | @geindex Wide Character | |
25390 | @geindex Representation | |
25391 | ||
25392 | @geindex Wide String | |
25393 | @geindex Conversion | |
25394 | ||
25395 | @geindex Representation of wide characters | |
25396 | ||
25397 | This package provides routines for converting between | |
25398 | wide and wide wide characters and a representation as a value of type | |
25399 | @code{Standard.String}, using a specified wide character | |
25400 | encoding method. It uses definitions in | |
25401 | package @code{System.Wch_Con}. | |
25402 | ||
25403 | @node System Wch_Con s-wchcon ads,,System Wch_Cnv s-wchcnv ads,The GNAT Library | |
9daee425 | 25404 | @anchor{gnat_rm/the_gnat_library id149}@anchor{408}@anchor{gnat_rm/the_gnat_library system-wch-con-s-wchcon-ads}@anchor{409} |
64d5610f ML |
25405 | @section @code{System.Wch_Con} (@code{s-wchcon.ads}) |
25406 | ||
25407 | ||
25408 | @geindex System.Wch_Con (s-wchcon.ads) | |
25409 | ||
25410 | This package provides definitions and descriptions of | |
25411 | the various methods used for encoding wide characters | |
25412 | in ordinary strings. These definitions are used by | |
25413 | the package @code{System.Wch_Cnv}. | |
25414 | ||
25415 | @node Interfacing to Other Languages,Specialized Needs Annexes,The GNAT Library,Top | |
9daee425 | 25416 | @anchor{gnat_rm/interfacing_to_other_languages doc}@anchor{40a}@anchor{gnat_rm/interfacing_to_other_languages id1}@anchor{40b}@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-other-languages}@anchor{11} |
64d5610f ML |
25417 | @chapter Interfacing to Other Languages |
25418 | ||
25419 | ||
25420 | The facilities in Annex B of the Ada Reference Manual are fully | |
25421 | implemented in GNAT, and in addition, a full interface to C++ is | |
25422 | provided. | |
25423 | ||
25424 | @menu | |
25425 | * Interfacing to C:: | |
25426 | * Interfacing to C++:: | |
25427 | * Interfacing to COBOL:: | |
25428 | * Interfacing to Fortran:: | |
25429 | * Interfacing to non-GNAT Ada code:: | |
25430 | ||
25431 | @end menu | |
25432 | ||
25433 | @node Interfacing to C,Interfacing to C++,,Interfacing to Other Languages | |
9daee425 | 25434 | @anchor{gnat_rm/interfacing_to_other_languages id2}@anchor{40c}@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-c}@anchor{40d} |
64d5610f ML |
25435 | @section Interfacing to C |
25436 | ||
25437 | ||
25438 | Interfacing to C with GNAT can use one of two approaches: | |
25439 | ||
25440 | ||
25441 | @itemize * | |
25442 | ||
25443 | @item | |
25444 | The types in the package @code{Interfaces.C} may be used. | |
25445 | ||
25446 | @item | |
25447 | Standard Ada types may be used directly. This may be less portable to | |
25448 | other compilers, but will work on all GNAT compilers, which guarantee | |
25449 | correspondence between the C and Ada types. | |
25450 | @end itemize | |
25451 | ||
25452 | Pragma @code{Convention C} may be applied to Ada types, but mostly has no | |
25453 | effect, since this is the default. The following table shows the | |
25454 | correspondence between Ada scalar types and the corresponding C types. | |
25455 | ||
25456 | ||
25457 | @multitable {xxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} | |
25458 | @headitem | |
25459 | ||
25460 | Ada Type | |
25461 | ||
25462 | @tab | |
25463 | ||
25464 | C Type | |
25465 | ||
25466 | @item | |
25467 | ||
25468 | @code{Integer} | |
25469 | ||
25470 | @tab | |
25471 | ||
25472 | @code{int} | |
25473 | ||
25474 | @item | |
25475 | ||
25476 | @code{Short_Integer} | |
25477 | ||
25478 | @tab | |
25479 | ||
25480 | @code{short} | |
25481 | ||
25482 | @item | |
25483 | ||
25484 | @code{Short_Short_Integer} | |
25485 | ||
25486 | @tab | |
25487 | ||
25488 | @code{signed char} | |
25489 | ||
25490 | @item | |
25491 | ||
25492 | @code{Long_Integer} | |
25493 | ||
25494 | @tab | |
25495 | ||
25496 | @code{long} | |
25497 | ||
25498 | @item | |
25499 | ||
25500 | @code{Long_Long_Integer} | |
25501 | ||
25502 | @tab | |
25503 | ||
25504 | @code{long long} | |
25505 | ||
25506 | @item | |
25507 | ||
25508 | @code{Short_Float} | |
25509 | ||
25510 | @tab | |
25511 | ||
25512 | @code{float} | |
25513 | ||
25514 | @item | |
25515 | ||
25516 | @code{Float} | |
25517 | ||
25518 | @tab | |
25519 | ||
25520 | @code{float} | |
25521 | ||
25522 | @item | |
25523 | ||
25524 | @code{Long_Float} | |
25525 | ||
25526 | @tab | |
25527 | ||
25528 | @code{double} | |
25529 | ||
25530 | @item | |
25531 | ||
25532 | @code{Long_Long_Float} | |
25533 | ||
25534 | @tab | |
25535 | ||
25536 | This is the longest floating-point type supported by the hardware. | |
25537 | ||
25538 | @end multitable | |
25539 | ||
25540 | ||
25541 | Additionally, there are the following general correspondences between Ada | |
25542 | and C types: | |
25543 | ||
25544 | ||
25545 | @itemize * | |
25546 | ||
25547 | @item | |
25548 | Ada enumeration types map to C enumeration types directly if pragma | |
25549 | @code{Convention C} is specified, which causes them to have a length of | |
25550 | 32 bits, except for boolean types which map to C99 @code{bool} and for | |
25551 | which the length is 8 bits. | |
25552 | Without pragma @code{Convention C}, Ada enumeration types map to | |
25553 | 8, 16, or 32 bits (i.e., C types @code{signed char}, @code{short}, | |
25554 | @code{int}, respectively) depending on the number of values passed. | |
25555 | This is the only case in which pragma @code{Convention C} affects the | |
25556 | representation of an Ada type. | |
25557 | ||
25558 | @item | |
25559 | Ada access types map to C pointers, except for the case of pointers to | |
25560 | unconstrained types in Ada, which have no direct C equivalent. | |
25561 | ||
25562 | @item | |
25563 | Ada arrays map directly to C arrays. | |
25564 | ||
25565 | @item | |
25566 | Ada records map directly to C structures. | |
25567 | ||
25568 | @item | |
25569 | Packed Ada records map to C structures where all members are bit fields | |
25570 | of the length corresponding to the @code{type'Size} value in Ada. | |
25571 | @end itemize | |
25572 | ||
25573 | @node Interfacing to C++,Interfacing to COBOL,Interfacing to C,Interfacing to Other Languages | |
9daee425 | 25574 | @anchor{gnat_rm/interfacing_to_other_languages id3}@anchor{47}@anchor{gnat_rm/interfacing_to_other_languages id4}@anchor{40e} |
64d5610f ML |
25575 | @section Interfacing to C++ |
25576 | ||
25577 | ||
25578 | The interface to C++ makes use of the following pragmas, which are | |
25579 | primarily intended to be constructed automatically using a binding generator | |
25580 | tool, although it is possible to construct them by hand. | |
25581 | ||
25582 | Using these pragmas it is possible to achieve complete | |
25583 | inter-operability between Ada tagged types and C++ class definitions. | |
25584 | See @ref{7,,Implementation Defined Pragmas}, for more details. | |
25585 | ||
25586 | ||
25587 | @table @asis | |
25588 | ||
1acce141 | 25589 | @item @code{pragma CPP_Class ([Entity =>] @emph{LOCAL_NAME})} |
64d5610f ML |
25590 | |
25591 | The argument denotes an entity in the current declarative region that is | |
25592 | declared as a tagged or untagged record type. It indicates that the type | |
25593 | corresponds to an externally declared C++ class type, and is to be laid | |
25594 | out the same way that C++ would lay out the type. | |
25595 | ||
25596 | Note: Pragma @code{CPP_Class} is currently obsolete. It is supported | |
25597 | for backward compatibility but its functionality is available | |
25598 | using pragma @code{Import} with @code{Convention} = @code{CPP}. | |
25599 | ||
1acce141 | 25600 | @item @code{pragma CPP_Constructor ([Entity =>] @emph{LOCAL_NAME})} |
64d5610f ML |
25601 | |
25602 | This pragma identifies an imported function (imported in the usual way | |
25603 | with pragma @code{Import}) as corresponding to a C++ constructor. | |
25604 | @end table | |
25605 | ||
25606 | A few restrictions are placed on the use of the @code{Access} attribute | |
25607 | in conjunction with subprograms subject to convention @code{CPP}: the | |
25608 | attribute may be used neither on primitive operations of a tagged | |
25609 | record type with convention @code{CPP}, imported or not, nor on | |
25610 | subprograms imported with pragma @code{CPP_Constructor}. | |
25611 | ||
25612 | In addition, C++ exceptions are propagated and can be handled in an | |
25613 | @code{others} choice of an exception handler. The corresponding Ada | |
25614 | occurrence has no message, and the simple name of the exception identity | |
25615 | contains @code{Foreign_Exception}. Finalization and awaiting dependent | |
25616 | tasks works properly when such foreign exceptions are propagated. | |
25617 | ||
25618 | It is also possible to import a C++ exception using the following syntax: | |
25619 | ||
25620 | @example | |
25621 | LOCAL_NAME : exception; | |
25622 | pragma Import (Cpp, | |
25623 | [Entity =>] LOCAL_NAME, | |
25624 | [External_Name =>] static_string_EXPRESSION); | |
25625 | @end example | |
25626 | ||
25627 | The @code{External_Name} is the name of the C++ RTTI symbol. You can then | |
25628 | cover a specific C++ exception in an exception handler. | |
25629 | ||
25630 | @node Interfacing to COBOL,Interfacing to Fortran,Interfacing to C++,Interfacing to Other Languages | |
9daee425 | 25631 | @anchor{gnat_rm/interfacing_to_other_languages id5}@anchor{40f}@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-cobol}@anchor{410} |
64d5610f ML |
25632 | @section Interfacing to COBOL |
25633 | ||
25634 | ||
25635 | Interfacing to COBOL is achieved as described in section B.4 of | |
25636 | the Ada Reference Manual. | |
25637 | ||
25638 | @node Interfacing to Fortran,Interfacing to non-GNAT Ada code,Interfacing to COBOL,Interfacing to Other Languages | |
9daee425 | 25639 | @anchor{gnat_rm/interfacing_to_other_languages id6}@anchor{411}@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-fortran}@anchor{412} |
64d5610f ML |
25640 | @section Interfacing to Fortran |
25641 | ||
25642 | ||
25643 | Interfacing to Fortran is achieved as described in section B.5 of the | |
25644 | Ada Reference Manual. The pragma @code{Convention Fortran}, applied to a | |
25645 | multi-dimensional array causes the array to be stored in column-major | |
25646 | order as required for convenient interface to Fortran. | |
25647 | ||
25648 | @node Interfacing to non-GNAT Ada code,,Interfacing to Fortran,Interfacing to Other Languages | |
9daee425 | 25649 | @anchor{gnat_rm/interfacing_to_other_languages id7}@anchor{413}@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-non-gnat-ada-code}@anchor{414} |
64d5610f ML |
25650 | @section Interfacing to non-GNAT Ada code |
25651 | ||
25652 | ||
25653 | It is possible to specify the convention @code{Ada} in a pragma | |
25654 | @code{Import} or pragma @code{Export}. However this refers to | |
25655 | the calling conventions used by GNAT, which may or may not be | |
25656 | similar enough to those used by some other Ada 83 / Ada 95 / Ada 2005 | |
25657 | compiler to allow interoperation. | |
25658 | ||
25659 | If arguments types are kept simple, and if the foreign compiler generally | |
25660 | follows system calling conventions, then it may be possible to integrate | |
25661 | files compiled by other Ada compilers, provided that the elaboration | |
25662 | issues are adequately addressed (for example by eliminating the | |
25663 | need for any load time elaboration). | |
25664 | ||
25665 | In particular, GNAT running on VMS is designed to | |
25666 | be highly compatible with the DEC Ada 83 compiler, so this is one | |
25667 | case in which it is possible to import foreign units of this type, | |
25668 | provided that the data items passed are restricted to simple scalar | |
25669 | values or simple record types without variants, or simple array | |
25670 | types with fixed bounds. | |
25671 | ||
25672 | @node Specialized Needs Annexes,Implementation of Specific Ada Features,Interfacing to Other Languages,Top | |
9daee425 | 25673 | @anchor{gnat_rm/specialized_needs_annexes doc}@anchor{415}@anchor{gnat_rm/specialized_needs_annexes id1}@anchor{416}@anchor{gnat_rm/specialized_needs_annexes specialized-needs-annexes}@anchor{12} |
64d5610f ML |
25674 | @chapter Specialized Needs Annexes |
25675 | ||
25676 | ||
25677 | Ada 95, Ada 2005, and Ada 2012 define a number of Specialized Needs Annexes, which are not | |
25678 | required in all implementations. However, as described in this chapter, | |
25679 | GNAT implements all of these annexes: | |
25680 | ||
25681 | ||
25682 | @table @asis | |
25683 | ||
1acce141 | 25684 | @item @emph{Systems Programming (Annex C)} |
64d5610f ML |
25685 | |
25686 | The Systems Programming Annex is fully implemented. | |
25687 | ||
1acce141 | 25688 | @item @emph{Real-Time Systems (Annex D)} |
64d5610f ML |
25689 | |
25690 | The Real-Time Systems Annex is fully implemented. | |
25691 | ||
1acce141 | 25692 | @item @emph{Distributed Systems (Annex E)} |
64d5610f ML |
25693 | |
25694 | Stub generation is fully implemented in the GNAT compiler. In addition, | |
25695 | a complete compatible PCS is available as part of the GLADE system, | |
25696 | a separate product. When the two | |
25697 | products are used in conjunction, this annex is fully implemented. | |
25698 | ||
1acce141 | 25699 | @item @emph{Information Systems (Annex F)} |
64d5610f ML |
25700 | |
25701 | The Information Systems annex is fully implemented. | |
25702 | ||
1acce141 | 25703 | @item @emph{Numerics (Annex G)} |
64d5610f ML |
25704 | |
25705 | The Numerics Annex is fully implemented. | |
25706 | ||
1acce141 | 25707 | @item @emph{Safety and Security / High-Integrity Systems (Annex H)} |
64d5610f ML |
25708 | |
25709 | The Safety and Security Annex (termed the High-Integrity Systems Annex | |
25710 | in Ada 2005) is fully implemented. | |
25711 | @end table | |
25712 | ||
25713 | @node Implementation of Specific Ada Features,Implementation of Ada 2012 Features,Specialized Needs Annexes,Top | |
9daee425 | 25714 | @anchor{gnat_rm/implementation_of_specific_ada_features doc}@anchor{417}@anchor{gnat_rm/implementation_of_specific_ada_features id1}@anchor{418}@anchor{gnat_rm/implementation_of_specific_ada_features implementation-of-specific-ada-features}@anchor{13} |
64d5610f ML |
25715 | @chapter Implementation of Specific Ada Features |
25716 | ||
25717 | ||
25718 | This chapter describes the GNAT implementation of several Ada language | |
25719 | facilities. | |
25720 | ||
25721 | @menu | |
25722 | * Machine Code Insertions:: | |
25723 | * GNAT Implementation of Tasking:: | |
25724 | * GNAT Implementation of Shared Passive Packages:: | |
25725 | * Code Generation for Array Aggregates:: | |
25726 | * The Size of Discriminated Records with Default Discriminants:: | |
25727 | * Image Values For Nonscalar Types:: | |
25728 | * Strict Conformance to the Ada Reference Manual:: | |
25729 | ||
25730 | @end menu | |
25731 | ||
25732 | @node Machine Code Insertions,GNAT Implementation of Tasking,,Implementation of Specific Ada Features | |
9daee425 | 25733 | @anchor{gnat_rm/implementation_of_specific_ada_features id2}@anchor{419}@anchor{gnat_rm/implementation_of_specific_ada_features machine-code-insertions}@anchor{170} |
64d5610f ML |
25734 | @section Machine Code Insertions |
25735 | ||
25736 | ||
25737 | @geindex Machine Code insertions | |
25738 | ||
25739 | Package @code{Machine_Code} provides machine code support as described | |
25740 | in the Ada Reference Manual in two separate forms: | |
25741 | ||
25742 | ||
25743 | @itemize * | |
25744 | ||
25745 | @item | |
25746 | Machine code statements, consisting of qualified expressions that | |
25747 | fit the requirements of RM section 13.8. | |
25748 | ||
25749 | @item | |
25750 | An intrinsic callable procedure, providing an alternative mechanism of | |
25751 | including machine instructions in a subprogram. | |
25752 | @end itemize | |
25753 | ||
25754 | The two features are similar, and both are closely related to the mechanism | |
25755 | provided by the asm instruction in the GNU C compiler. Full understanding | |
25756 | and use of the facilities in this package requires understanding the asm | |
25757 | instruction, see the section on Extended Asm in | |
25758 | @cite{Using_the_GNU_Compiler_Collection_(GCC)}. | |
25759 | ||
25760 | Calls to the function @code{Asm} and the procedure @code{Asm} have identical | |
25761 | semantic restrictions and effects as described below. Both are provided so | |
25762 | that the procedure call can be used as a statement, and the function call | |
25763 | can be used to form a code_statement. | |
25764 | ||
25765 | Consider this C @code{asm} instruction: | |
25766 | ||
25767 | @example | |
25768 | asm ("fsinx %1 %0" : "=f" (result) : "f" (angle)); | |
25769 | @end example | |
25770 | ||
25771 | The equivalent can be written for GNAT as: | |
25772 | ||
25773 | @example | |
25774 | Asm ("fsinx %1 %0", | |
25775 | My_Float'Asm_Output ("=f", result), | |
25776 | My_Float'Asm_Input ("f", angle)); | |
25777 | @end example | |
25778 | ||
25779 | The first argument to @code{Asm} is the assembler template, and is | |
25780 | identical to what is used in GNU C. This string must be a static | |
25781 | expression. The second argument is the output operand list. It is | |
25782 | either a single @code{Asm_Output} attribute reference, or a list of such | |
25783 | references enclosed in parentheses (technically an array aggregate of | |
25784 | such references). | |
25785 | ||
25786 | The @code{Asm_Output} attribute denotes a function that takes two | |
25787 | parameters. The first is a string, the second is the name of a variable | |
25788 | of the type designated by the attribute prefix. The first (string) | |
25789 | argument is required to be a static expression and designates the | |
25790 | constraint (see the section on Constraints in | |
25791 | @cite{Using_the_GNU_Compiler_Collection_(GCC)}) | |
25792 | for the parameter; e.g., what kind of register is required. The second | |
25793 | argument is the variable to be written or updated with the | |
25794 | result. The possible values for constraint are the same as those used in | |
25795 | the RTL, and are dependent on the configuration file used to build the | |
25796 | GCC back end. If there are no output operands, then this argument may | |
25797 | either be omitted, or explicitly given as @code{No_Output_Operands}. | |
25798 | No support is provided for GNU C’s symbolic names for output parameters. | |
25799 | ||
25800 | The second argument of @code{my_float'Asm_Output} functions as | |
25801 | though it were an @code{out} parameter, which is a little curious, but | |
25802 | all names have the form of expressions, so there is no syntactic | |
25803 | irregularity, even though normally functions would not be permitted | |
25804 | @code{out} parameters. The third argument is the list of input | |
25805 | operands. It is either a single @code{Asm_Input} attribute reference, or | |
25806 | a list of such references enclosed in parentheses (technically an array | |
25807 | aggregate of such references). | |
25808 | ||
25809 | The @code{Asm_Input} attribute denotes a function that takes two | |
25810 | parameters. The first is a string, the second is an expression of the | |
25811 | type designated by the prefix. The first (string) argument is required | |
25812 | to be a static expression, and is the constraint for the parameter, | |
25813 | (e.g., what kind of register is required). The second argument is the | |
25814 | value to be used as the input argument. The possible values for the | |
25815 | constraint are the same as those used in the RTL, and are dependent on | |
25816 | the configuration file used to built the GCC back end. | |
25817 | No support is provided for GNU C’s symbolic names for input parameters. | |
25818 | ||
25819 | If there are no input operands, this argument may either be omitted, or | |
25820 | explicitly given as @code{No_Input_Operands}. The fourth argument, not | |
25821 | present in the above example, is a list of register names, called the | |
1acce141 | 25822 | @emph{clobber} argument. This argument, if given, must be a static string |
64d5610f ML |
25823 | expression, and is a space or comma separated list of names of registers |
25824 | that must be considered destroyed as a result of the @code{Asm} call. If | |
25825 | this argument is the null string (the default value), then the code | |
25826 | generator assumes that no additional registers are destroyed. | |
25827 | In addition to registers, the special clobbers @code{memory} and | |
25828 | @code{cc} as described in the GNU C docs are both supported. | |
25829 | ||
25830 | The fifth argument, not present in the above example, called the | |
1acce141 | 25831 | @emph{volatile} argument, is by default @code{False}. It can be set to |
64d5610f ML |
25832 | the literal value @code{True} to indicate to the code generator that all |
25833 | optimizations with respect to the instruction specified should be | |
25834 | suppressed, and in particular an instruction that has outputs | |
25835 | will still be generated, even if none of the outputs are | |
25836 | used. See @cite{Using_the_GNU_Compiler_Collection_(GCC)} | |
25837 | for the full description. | |
25838 | Generally it is strongly advisable to use Volatile for any ASM statement | |
25839 | that is missing either input or output operands or to avoid unwanted | |
25840 | optimizations. A warning is generated if this advice is not followed. | |
25841 | ||
25842 | No support is provided for GNU C’s @code{asm goto} feature. | |
25843 | ||
25844 | The @code{Asm} subprograms may be used in two ways. First the procedure | |
25845 | forms can be used anywhere a procedure call would be valid, and | |
25846 | correspond to what the RM calls ‘intrinsic’ routines. Such calls can | |
25847 | be used to intersperse machine instructions with other Ada statements. | |
25848 | Second, the function forms, which return a dummy value of the limited | |
25849 | private type @code{Asm_Insn}, can be used in code statements, and indeed | |
25850 | this is the only context where such calls are allowed. Code statements | |
25851 | appear as aggregates of the form: | |
25852 | ||
b71d4b62 RA |
25853 | @example |
25854 | Asm_Insn'(Asm (...)); | |
25855 | Asm_Insn'(Asm_Volatile (...)); | |
25856 | @end example | |
25857 | ||
25858 | In accordance with RM rules, such code statements are allowed only | |
25859 | within subprograms whose entire body consists of such statements. It is | |
25860 | not permissible to intermix such statements with other Ada statements. | |
25861 | ||
25862 | Typically the form using intrinsic procedure calls is more convenient | |
25863 | and more flexible. The code statement form is provided to meet the RM | |
25864 | suggestion that such a facility should be made available. The following | |
25865 | is the exact syntax of the call to @code{Asm}. As usual, if named notation | |
25866 | is used, the arguments may be given in arbitrary order, following the | |
25867 | normal rules for use of positional and named arguments: | |
25868 | ||
25869 | @example | |
25870 | ASM_CALL ::= Asm ( | |
25871 | [Template =>] static_string_EXPRESSION | |
25872 | [,[Outputs =>] OUTPUT_OPERAND_LIST ] | |
25873 | [,[Inputs =>] INPUT_OPERAND_LIST ] | |
25874 | [,[Clobber =>] static_string_EXPRESSION ] | |
25875 | [,[Volatile =>] static_boolean_EXPRESSION] ) | |
25876 | ||
25877 | OUTPUT_OPERAND_LIST ::= | |
25878 | [PREFIX.]No_Output_Operands | |
25879 | | OUTPUT_OPERAND_ATTRIBUTE | |
25880 | | (OUTPUT_OPERAND_ATTRIBUTE @{,OUTPUT_OPERAND_ATTRIBUTE@}) | |
25881 | ||
25882 | OUTPUT_OPERAND_ATTRIBUTE ::= | |
25883 | SUBTYPE_MARK'Asm_Output (static_string_EXPRESSION, NAME) | |
25884 | ||
25885 | INPUT_OPERAND_LIST ::= | |
25886 | [PREFIX.]No_Input_Operands | |
25887 | | INPUT_OPERAND_ATTRIBUTE | |
25888 | | (INPUT_OPERAND_ATTRIBUTE @{,INPUT_OPERAND_ATTRIBUTE@}) | |
25889 | ||
25890 | INPUT_OPERAND_ATTRIBUTE ::= | |
25891 | SUBTYPE_MARK'Asm_Input (static_string_EXPRESSION, EXPRESSION) | |
25892 | @end example | |
25893 | ||
25894 | The identifiers @code{No_Input_Operands} and @code{No_Output_Operands} | |
25895 | are declared in the package @code{Machine_Code} and must be referenced | |
25896 | according to normal visibility rules. In particular if there is no | |
25897 | @code{use} clause for this package, then appropriate package name | |
25898 | qualification is required. | |
25899 | ||
25900 | @node GNAT Implementation of Tasking,GNAT Implementation of Shared Passive Packages,Machine Code Insertions,Implementation of Specific Ada Features | |
9daee425 | 25901 | @anchor{gnat_rm/implementation_of_specific_ada_features gnat-implementation-of-tasking}@anchor{41a}@anchor{gnat_rm/implementation_of_specific_ada_features id3}@anchor{41b} |
b71d4b62 RA |
25902 | @section GNAT Implementation of Tasking |
25903 | ||
25904 | ||
25905 | This chapter outlines the basic GNAT approach to tasking (in particular, | |
25906 | a multi-layered library for portability) and discusses issues related | |
25907 | to compliance with the Real-Time Systems Annex. | |
25908 | ||
25909 | @menu | |
25910 | * Mapping Ada Tasks onto the Underlying Kernel Threads:: | |
25911 | * Ensuring Compliance with the Real-Time Annex:: | |
25912 | * Support for Locking Policies:: | |
25913 | ||
25914 | @end menu | |
25915 | ||
25916 | @node Mapping Ada Tasks onto the Underlying Kernel Threads,Ensuring Compliance with the Real-Time Annex,,GNAT Implementation of Tasking | |
9daee425 | 25917 | @anchor{gnat_rm/implementation_of_specific_ada_features id4}@anchor{41c}@anchor{gnat_rm/implementation_of_specific_ada_features mapping-ada-tasks-onto-the-underlying-kernel-threads}@anchor{41d} |
b71d4b62 RA |
25918 | @subsection Mapping Ada Tasks onto the Underlying Kernel Threads |
25919 | ||
25920 | ||
25921 | GNAT’s run-time support comprises two layers: | |
25922 | ||
25923 | ||
25924 | @itemize * | |
25925 | ||
25926 | @item | |
25927 | GNARL (GNAT Run-time Layer) | |
25928 | ||
25929 | @item | |
25930 | GNULL (GNAT Low-level Library) | |
25931 | @end itemize | |
25932 | ||
25933 | In GNAT, Ada’s tasking services rely on a platform and OS independent | |
25934 | layer known as GNARL. This code is responsible for implementing the | |
25935 | correct semantics of Ada’s task creation, rendezvous, protected | |
25936 | operations etc. | |
25937 | ||
25938 | GNARL decomposes Ada’s tasking semantics into simpler lower level | |
25939 | operations such as create a thread, set the priority of a thread, | |
25940 | yield, create a lock, lock/unlock, etc. The spec for these low-level | |
25941 | operations constitutes GNULLI, the GNULL Interface. This interface is | |
25942 | directly inspired from the POSIX real-time API. | |
25943 | ||
25944 | If the underlying executive or OS implements the POSIX standard | |
25945 | faithfully, the GNULL Interface maps as is to the services offered by | |
25946 | the underlying kernel. Otherwise, some target dependent glue code maps | |
25947 | the services offered by the underlying kernel to the semantics expected | |
25948 | by GNARL. | |
25949 | ||
25950 | Whatever the underlying OS (VxWorks, UNIX, Windows, etc.) the | |
25951 | key point is that each Ada task is mapped on a thread in the underlying | |
25952 | kernel. For example, in the case of VxWorks, one Ada task = one VxWorks task. | |
25953 | ||
25954 | In addition Ada task priorities map onto the underlying thread priorities. | |
25955 | Mapping Ada tasks onto the underlying kernel threads has several advantages: | |
25956 | ||
25957 | ||
25958 | @itemize * | |
25959 | ||
25960 | @item | |
25961 | The underlying scheduler is used to schedule the Ada tasks. This | |
25962 | makes Ada tasks as efficient as kernel threads from a scheduling | |
25963 | standpoint. | |
25964 | ||
25965 | @item | |
25966 | Interaction with code written in C containing threads is eased | |
25967 | since at the lowest level Ada tasks and C threads map onto the same | |
25968 | underlying kernel concept. | |
25969 | ||
25970 | @item | |
25971 | When an Ada task is blocked during I/O the remaining Ada tasks are | |
25972 | able to proceed. | |
25973 | ||
25974 | @item | |
25975 | On multiprocessor systems Ada tasks can execute in parallel. | |
25976 | @end itemize | |
25977 | ||
25978 | Some threads libraries offer a mechanism to fork a new process, with the | |
25979 | child process duplicating the threads from the parent. | |
25980 | GNAT does not | |
25981 | support this functionality when the parent contains more than one task. | |
25982 | ||
25983 | @geindex Forking a new process | |
25984 | ||
25985 | @node Ensuring Compliance with the Real-Time Annex,Support for Locking Policies,Mapping Ada Tasks onto the Underlying Kernel Threads,GNAT Implementation of Tasking | |
9daee425 | 25986 | @anchor{gnat_rm/implementation_of_specific_ada_features ensuring-compliance-with-the-real-time-annex}@anchor{41e}@anchor{gnat_rm/implementation_of_specific_ada_features id5}@anchor{41f} |
b71d4b62 RA |
25987 | @subsection Ensuring Compliance with the Real-Time Annex |
25988 | ||
25989 | ||
25990 | @geindex Real-Time Systems Annex compliance | |
25991 | ||
25992 | Although mapping Ada tasks onto | |
25993 | the underlying threads has significant advantages, it does create some | |
25994 | complications when it comes to respecting the scheduling semantics | |
25995 | specified in the real-time annex (Annex D). | |
25996 | ||
25997 | For instance the Annex D requirement for the @code{FIFO_Within_Priorities} | |
25998 | scheduling policy states: | |
25999 | ||
26000 | @quotation | |
26001 | ||
1acce141 | 26002 | @emph{When the active priority of a ready task that is not running |
b71d4b62 RA |
26003 | changes, or the setting of its base priority takes effect, the |
26004 | task is removed from the ready queue for its old active priority | |
26005 | and is added at the tail of the ready queue for its new active | |
26006 | priority, except in the case where the active priority is lowered | |
26007 | due to the loss of inherited priority, in which case the task is | |
1acce141 | 26008 | added at the head of the ready queue for its new active priority.} |
b71d4b62 RA |
26009 | @end quotation |
26010 | ||
26011 | While most kernels do put tasks at the end of the priority queue when | |
26012 | a task changes its priority, (which respects the main | |
26013 | FIFO_Within_Priorities requirement), almost none keep a thread at the | |
26014 | beginning of its priority queue when its priority drops from the loss | |
26015 | of inherited priority. | |
26016 | ||
26017 | As a result most vendors have provided incomplete Annex D implementations. | |
26018 | ||
26019 | The GNAT run-time, has a nice cooperative solution to this problem | |
26020 | which ensures that accurate FIFO_Within_Priorities semantics are | |
26021 | respected. | |
26022 | ||
26023 | The principle is as follows. When an Ada task T is about to start | |
26024 | running, it checks whether some other Ada task R with the same | |
26025 | priority as T has been suspended due to the loss of priority | |
26026 | inheritance. If this is the case, T yields and is placed at the end of | |
26027 | its priority queue. When R arrives at the front of the queue it | |
26028 | executes. | |
26029 | ||
26030 | Note that this simple scheme preserves the relative order of the tasks | |
26031 | that were ready to execute in the priority queue where R has been | |
26032 | placed at the end. | |
26033 | ||
26034 | @c Support_for_Locking_Policies | |
26035 | ||
26036 | @node Support for Locking Policies,,Ensuring Compliance with the Real-Time Annex,GNAT Implementation of Tasking | |
9daee425 | 26037 | @anchor{gnat_rm/implementation_of_specific_ada_features support-for-locking-policies}@anchor{420} |
b71d4b62 RA |
26038 | @subsection Support for Locking Policies |
26039 | ||
26040 | ||
26041 | This section specifies which policies specified by pragma Locking_Policy | |
26042 | are supported on which platforms. | |
26043 | ||
26044 | GNAT supports the standard @code{Ceiling_Locking} policy, and the | |
26045 | implementation defined @code{Inheritance_Locking} and | |
26046 | @code{Concurrent_Readers_Locking} policies. | |
26047 | ||
26048 | @code{Ceiling_Locking} is supported on all platforms if the operating system | |
26049 | supports it. In particular, @code{Ceiling_Locking} is not supported on | |
26050 | VxWorks. | |
26051 | @code{Inheritance_Locking} is supported on | |
26052 | Linux, | |
26053 | Darwin (Mac OS X), | |
26054 | LynxOS 178, | |
26055 | and VxWorks. | |
26056 | @code{Concurrent_Readers_Locking} is supported on Linux. | |
26057 | ||
26058 | Notes about @code{Ceiling_Locking} on Linux: | |
26059 | If the process is running as ‘root’, ceiling locking is used. | |
26060 | If the capabilities facility is installed | |
26061 | (“sudo apt-get –assume-yes install libcap-dev” on Ubuntu, | |
26062 | for example), | |
26063 | and the program is linked against that library | |
26064 | (“-largs -lcap”), | |
26065 | and the executable file has the cap_sys_nice capability | |
26066 | (“sudo /sbin/setcap cap_sys_nice=ep executable_file_name”), | |
26067 | then ceiling locking is used. | |
26068 | Otherwise, the @code{Ceiling_Locking} policy is ignored. | |
26069 | ||
26070 | @node GNAT Implementation of Shared Passive Packages,Code Generation for Array Aggregates,GNAT Implementation of Tasking,Implementation of Specific Ada Features | |
9daee425 | 26071 | @anchor{gnat_rm/implementation_of_specific_ada_features gnat-implementation-of-shared-passive-packages}@anchor{421}@anchor{gnat_rm/implementation_of_specific_ada_features id6}@anchor{422} |
b71d4b62 RA |
26072 | @section GNAT Implementation of Shared Passive Packages |
26073 | ||
26074 | ||
26075 | @geindex Shared passive packages | |
26076 | ||
26077 | GNAT fully implements the | |
26078 | @geindex pragma Shared_Passive | |
26079 | pragma | |
26080 | @code{Shared_Passive} for | |
26081 | the purpose of designating shared passive packages. | |
26082 | This allows the use of passive partitions in the | |
26083 | context described in the Ada Reference Manual; i.e., for communication | |
26084 | between separate partitions of a distributed application using the | |
26085 | features in Annex E. | |
26086 | ||
26087 | @geindex Annex E | |
26088 | ||
26089 | @geindex Distribution Systems Annex | |
26090 | ||
26091 | However, the implementation approach used by GNAT provides for more | |
26092 | extensive usage as follows: | |
26093 | ||
26094 | ||
26095 | @table @asis | |
26096 | ||
1acce141 | 26097 | @item @emph{Communication between separate programs} |
b71d4b62 RA |
26098 | |
26099 | This allows separate programs to access the data in passive | |
26100 | partitions, using protected objects for synchronization where | |
26101 | needed. The only requirement is that the two programs have a | |
26102 | common shared file system. It is even possible for programs | |
26103 | running on different machines with different architectures | |
26104 | (e.g., different endianness) to communicate via the data in | |
26105 | a passive partition. | |
26106 | ||
1acce141 | 26107 | @item @emph{Persistence between program runs} |
b71d4b62 RA |
26108 | |
26109 | The data in a passive package can persist from one run of a | |
26110 | program to another, so that a later program sees the final | |
26111 | values stored by a previous run of the same program. | |
26112 | @end table | |
26113 | ||
26114 | The implementation approach used is to store the data in files. A | |
26115 | separate stream file is created for each object in the package, and | |
26116 | an access to an object causes the corresponding file to be read or | |
26117 | written. | |
26118 | ||
26119 | @geindex SHARED_MEMORY_DIRECTORY environment variable | |
26120 | ||
26121 | The environment variable @code{SHARED_MEMORY_DIRECTORY} should be | |
26122 | set to the directory to be used for these files. | |
26123 | The files in this directory | |
26124 | have names that correspond to their fully qualified names. For | |
26125 | example, if we have the package | |
26126 | ||
26127 | @example | |
26128 | package X is | |
26129 | pragma Shared_Passive (X); | |
26130 | Y : Integer; | |
26131 | Z : Float; | |
26132 | end X; | |
26133 | @end example | |
26134 | ||
26135 | and the environment variable is set to @code{/stemp/}, then the files created | |
26136 | will have the names: | |
26137 | ||
26138 | @example | |
26139 | /stemp/x.y | |
26140 | /stemp/x.z | |
26141 | @end example | |
26142 | ||
26143 | These files are created when a value is initially written to the object, and | |
26144 | the files are retained until manually deleted. This provides the persistence | |
26145 | semantics. If no file exists, it means that no partition has assigned a value | |
26146 | to the variable; in this case the initial value declared in the package | |
26147 | will be used. This model ensures that there are no issues in synchronizing | |
26148 | the elaboration process, since elaboration of passive packages elaborates the | |
26149 | initial values, but does not create the files. | |
26150 | ||
26151 | The files are written using normal @code{Stream_IO} access. | |
26152 | If you want to be able | |
26153 | to communicate between programs or partitions running on different | |
26154 | architectures, then you should use the XDR versions of the stream attribute | |
26155 | routines, since these are architecture independent. | |
26156 | ||
26157 | If active synchronization is required for access to the variables in the | |
26158 | shared passive package, then as described in the Ada Reference Manual, the | |
26159 | package may contain protected objects used for this purpose. In this case | |
26160 | a lock file (whose name is @code{___lock}, with three underscores) | |
26161 | is created in the shared memory directory. | |
26162 | ||
26163 | @geindex ___lock file (for shared passive packages) | |
26164 | ||
26165 | This is used to provide the required locking | |
26166 | semantics for proper protected object synchronization. | |
26167 | ||
26168 | @node Code Generation for Array Aggregates,The Size of Discriminated Records with Default Discriminants,GNAT Implementation of Shared Passive Packages,Implementation of Specific Ada Features | |
9daee425 | 26169 | @anchor{gnat_rm/implementation_of_specific_ada_features code-generation-for-array-aggregates}@anchor{423}@anchor{gnat_rm/implementation_of_specific_ada_features id7}@anchor{424} |
b71d4b62 RA |
26170 | @section Code Generation for Array Aggregates |
26171 | ||
26172 | ||
26173 | Aggregates have a rich syntax and allow the user to specify the values of | |
26174 | complex data structures by means of a single construct. As a result, the | |
26175 | code generated for aggregates can be quite complex and involve loops, case | |
26176 | statements and multiple assignments. In the simplest cases, however, the | |
26177 | compiler will recognize aggregates whose components and constraints are | |
26178 | fully static, and in those cases the compiler will generate little or no | |
26179 | executable code. The following is an outline of the code that GNAT generates | |
26180 | for various aggregate constructs. For further details, you will find it | |
26181 | useful to examine the output produced by the -gnatG flag to see the expanded | |
26182 | source that is input to the code generator. You may also want to examine | |
26183 | the assembly code generated at various levels of optimization. | |
26184 | ||
26185 | The code generated for aggregates depends on the context, the component values, | |
26186 | and the type. In the context of an object declaration the code generated is | |
26187 | generally simpler than in the case of an assignment. As a general rule, static | |
26188 | component values and static subtypes also lead to simpler code. | |
26189 | ||
26190 | @menu | |
26191 | * Static constant aggregates with static bounds:: | |
26192 | * Constant aggregates with unconstrained nominal types:: | |
26193 | * Aggregates with static bounds:: | |
26194 | * Aggregates with nonstatic bounds:: | |
26195 | * Aggregates in assignment statements:: | |
26196 | ||
26197 | @end menu | |
26198 | ||
26199 | @node Static constant aggregates with static bounds,Constant aggregates with unconstrained nominal types,,Code Generation for Array Aggregates | |
9daee425 | 26200 | @anchor{gnat_rm/implementation_of_specific_ada_features id8}@anchor{425}@anchor{gnat_rm/implementation_of_specific_ada_features static-constant-aggregates-with-static-bounds}@anchor{426} |
b71d4b62 RA |
26201 | @subsection Static constant aggregates with static bounds |
26202 | ||
26203 | ||
26204 | For the declarations: | |
26205 | ||
26206 | @example | |
26207 | type One_Dim is array (1..10) of integer; | |
26208 | ar0 : constant One_Dim := (1, 2, 3, 4, 5, 6, 7, 8, 9, 0); | |
26209 | @end example | |
26210 | ||
26211 | GNAT generates no executable code: the constant ar0 is placed in static memory. | |
26212 | The same is true for constant aggregates with named associations: | |
26213 | ||
26214 | @example | |
26215 | Cr1 : constant One_Dim := (4 => 16, 2 => 4, 3 => 9, 1 => 1, 5 .. 10 => 0); | |
26216 | Cr3 : constant One_Dim := (others => 7777); | |
26217 | @end example | |
26218 | ||
26219 | The same is true for multidimensional constant arrays such as: | |
26220 | ||
26221 | @example | |
26222 | type two_dim is array (1..3, 1..3) of integer; | |
26223 | Unit : constant two_dim := ( (1,0,0), (0,1,0), (0,0,1)); | |
26224 | @end example | |
26225 | ||
26226 | The same is true for arrays of one-dimensional arrays: the following are | |
26227 | static: | |
26228 | ||
26229 | @example | |
26230 | type ar1b is array (1..3) of boolean; | |
26231 | type ar_ar is array (1..3) of ar1b; | |
26232 | None : constant ar1b := (others => false); -- fully static | |
26233 | None2 : constant ar_ar := (1..3 => None); -- fully static | |
26234 | @end example | |
26235 | ||
26236 | However, for multidimensional aggregates with named associations, GNAT will | |
26237 | generate assignments and loops, even if all associations are static. The | |
26238 | following two declarations generate a loop for the first dimension, and | |
26239 | individual component assignments for the second dimension: | |
26240 | ||
26241 | @example | |
26242 | Zero1: constant two_dim := (1..3 => (1..3 => 0)); | |
26243 | Zero2: constant two_dim := (others => (others => 0)); | |
26244 | @end example | |
26245 | ||
26246 | @node Constant aggregates with unconstrained nominal types,Aggregates with static bounds,Static constant aggregates with static bounds,Code Generation for Array Aggregates | |
9daee425 | 26247 | @anchor{gnat_rm/implementation_of_specific_ada_features constant-aggregates-with-unconstrained-nominal-types}@anchor{427}@anchor{gnat_rm/implementation_of_specific_ada_features id9}@anchor{428} |
b71d4b62 RA |
26248 | @subsection Constant aggregates with unconstrained nominal types |
26249 | ||
26250 | ||
26251 | In such cases the aggregate itself establishes the subtype, so that | |
26252 | associations with @code{others} cannot be used. GNAT determines the | |
26253 | bounds for the actual subtype of the aggregate, and allocates the | |
26254 | aggregate statically as well. No code is generated for the following: | |
26255 | ||
26256 | @example | |
26257 | type One_Unc is array (natural range <>) of integer; | |
26258 | Cr_Unc : constant One_Unc := (12,24,36); | |
26259 | @end example | |
26260 | ||
26261 | @node Aggregates with static bounds,Aggregates with nonstatic bounds,Constant aggregates with unconstrained nominal types,Code Generation for Array Aggregates | |
9daee425 | 26262 | @anchor{gnat_rm/implementation_of_specific_ada_features aggregates-with-static-bounds}@anchor{429}@anchor{gnat_rm/implementation_of_specific_ada_features id10}@anchor{42a} |
b71d4b62 RA |
26263 | @subsection Aggregates with static bounds |
26264 | ||
26265 | ||
26266 | In all previous examples the aggregate was the initial (and immutable) value | |
26267 | of a constant. If the aggregate initializes a variable, then code is generated | |
26268 | for it as a combination of individual assignments and loops over the target | |
26269 | object. The declarations | |
26270 | ||
26271 | @example | |
26272 | Cr_Var1 : One_Dim := (2, 5, 7, 11, 0, 0, 0, 0, 0, 0); | |
26273 | Cr_Var2 : One_Dim := (others > -1); | |
26274 | @end example | |
26275 | ||
26276 | generate the equivalent of | |
26277 | ||
26278 | @example | |
26279 | Cr_Var1 (1) := 2; | |
26280 | Cr_Var1 (2) := 3; | |
26281 | Cr_Var1 (3) := 5; | |
26282 | Cr_Var1 (4) := 11; | |
26283 | ||
26284 | for I in Cr_Var2'range loop | |
26285 | Cr_Var2 (I) := -1; | |
26286 | end loop; | |
26287 | @end example | |
26288 | ||
26289 | @node Aggregates with nonstatic bounds,Aggregates in assignment statements,Aggregates with static bounds,Code Generation for Array Aggregates | |
9daee425 | 26290 | @anchor{gnat_rm/implementation_of_specific_ada_features aggregates-with-nonstatic-bounds}@anchor{42b}@anchor{gnat_rm/implementation_of_specific_ada_features id11}@anchor{42c} |
b71d4b62 RA |
26291 | @subsection Aggregates with nonstatic bounds |
26292 | ||
26293 | ||
26294 | If the bounds of the aggregate are not statically compatible with the bounds | |
26295 | of the nominal subtype of the target, then constraint checks have to be | |
26296 | generated on the bounds. For a multidimensional array, constraint checks may | |
26297 | have to be applied to sub-arrays individually, if they do not have statically | |
26298 | compatible subtypes. | |
26299 | ||
26300 | @node Aggregates in assignment statements,,Aggregates with nonstatic bounds,Code Generation for Array Aggregates | |
9daee425 | 26301 | @anchor{gnat_rm/implementation_of_specific_ada_features aggregates-in-assignment-statements}@anchor{42d}@anchor{gnat_rm/implementation_of_specific_ada_features id12}@anchor{42e} |
b71d4b62 RA |
26302 | @subsection Aggregates in assignment statements |
26303 | ||
26304 | ||
26305 | In general, aggregate assignment requires the construction of a temporary, | |
26306 | and a copy from the temporary to the target of the assignment. This is because | |
26307 | it is not always possible to convert the assignment into a series of individual | |
26308 | component assignments. For example, consider the simple case: | |
26309 | ||
26310 | @example | |
26311 | A := (A(2), A(1)); | |
26312 | @end example | |
26313 | ||
26314 | This cannot be converted into: | |
26315 | ||
26316 | @example | |
26317 | A(1) := A(2); | |
26318 | A(2) := A(1); | |
26319 | @end example | |
26320 | ||
26321 | So the aggregate has to be built first in a separate location, and then | |
26322 | copied into the target. GNAT recognizes simple cases where this intermediate | |
26323 | step is not required, and the assignments can be performed in place, directly | |
26324 | into the target. The following sufficient criteria are applied: | |
26325 | ||
26326 | ||
26327 | @itemize * | |
26328 | ||
26329 | @item | |
26330 | The bounds of the aggregate are static, and the associations are static. | |
26331 | ||
26332 | @item | |
26333 | The components of the aggregate are static constants, names of | |
26334 | simple variables that are not renamings, or expressions not involving | |
26335 | indexed components whose operands obey these rules. | |
26336 | @end itemize | |
26337 | ||
26338 | If any of these conditions are violated, the aggregate will be built in | |
26339 | a temporary (created either by the front-end or the code generator) and then | |
26340 | that temporary will be copied onto the target. | |
26341 | ||
26342 | @node The Size of Discriminated Records with Default Discriminants,Image Values For Nonscalar Types,Code Generation for Array Aggregates,Implementation of Specific Ada Features | |
9daee425 | 26343 | @anchor{gnat_rm/implementation_of_specific_ada_features id13}@anchor{42f}@anchor{gnat_rm/implementation_of_specific_ada_features the-size-of-discriminated-records-with-default-discriminants}@anchor{430} |
b71d4b62 RA |
26344 | @section The Size of Discriminated Records with Default Discriminants |
26345 | ||
26346 | ||
26347 | If a discriminated type @code{T} has discriminants with default values, it is | |
26348 | possible to declare an object of this type without providing an explicit | |
26349 | constraint: | |
26350 | ||
26351 | @example | |
26352 | type Size is range 1..100; | |
26353 | ||
26354 | type Rec (D : Size := 15) is record | |
26355 | Name : String (1..D); | |
26356 | end T; | |
26357 | ||
26358 | Word : Rec; | |
26359 | @end example | |
26360 | ||
1acce141 | 26361 | Such an object is said to be @emph{unconstrained}. |
b71d4b62 RA |
26362 | The discriminant of the object |
26363 | can be modified by a full assignment to the object, as long as it preserves the | |
26364 | relation between the value of the discriminant, and the value of the components | |
26365 | that depend on it: | |
26366 | ||
26367 | @example | |
26368 | Word := (3, "yes"); | |
26369 | ||
26370 | Word := (5, "maybe"); | |
26371 | ||
26372 | Word := (5, "no"); -- raises Constraint_Error | |
26373 | @end example | |
26374 | ||
26375 | In order to support this behavior efficiently, an unconstrained object is | |
26376 | given the maximum size that any value of the type requires. In the case | |
26377 | above, @code{Word} has storage for the discriminant and for | |
26378 | a @code{String} of length 100. | |
26379 | It is important to note that unconstrained objects do not require dynamic | |
26380 | allocation. It would be an improper implementation to place on the heap those | |
26381 | components whose size depends on discriminants. (This improper implementation | |
26382 | was used by some Ada83 compilers, where the @code{Name} component above | |
26383 | would have | |
26384 | been stored as a pointer to a dynamic string). Following the principle that | |
26385 | dynamic storage management should never be introduced implicitly, | |
26386 | an Ada compiler should reserve the full size for an unconstrained declared | |
26387 | object, and place it on the stack. | |
26388 | ||
26389 | This maximum size approach | |
26390 | has been a source of surprise to some users, who expect the default | |
26391 | values of the discriminants to determine the size reserved for an | |
26392 | unconstrained object: “If the default is 15, why should the object occupy | |
26393 | a larger size?” | |
26394 | The answer, of course, is that the discriminant may be later modified, | |
26395 | and its full range of values must be taken into account. This is why the | |
26396 | declaration: | |
26397 | ||
26398 | @example | |
26399 | type Rec (D : Positive := 15) is record | |
26400 | Name : String (1..D); | |
26401 | end record; | |
26402 | ||
26403 | Too_Large : Rec; | |
26404 | @end example | |
26405 | ||
26406 | is flagged by the compiler with a warning: | |
26407 | an attempt to create @code{Too_Large} will raise @code{Storage_Error}, | |
26408 | because the required size includes @code{Positive'Last} | |
26409 | bytes. As the first example indicates, the proper approach is to declare an | |
26410 | index type of ‘reasonable’ range so that unconstrained objects are not too | |
26411 | large. | |
26412 | ||
26413 | One final wrinkle: if the object is declared to be @code{aliased}, or if it is | |
1acce141 | 26414 | created in the heap by means of an allocator, then it is @emph{not} |
b71d4b62 RA |
26415 | unconstrained: |
26416 | it is constrained by the default values of the discriminants, and those values | |
26417 | cannot be modified by full assignment. This is because in the presence of | |
26418 | aliasing all views of the object (which may be manipulated by different tasks, | |
26419 | say) must be consistent, so it is imperative that the object, once created, | |
26420 | remain invariant. | |
26421 | ||
26422 | @node Image Values For Nonscalar Types,Strict Conformance to the Ada Reference Manual,The Size of Discriminated Records with Default Discriminants,Implementation of Specific Ada Features | |
9daee425 | 26423 | @anchor{gnat_rm/implementation_of_specific_ada_features id14}@anchor{431}@anchor{gnat_rm/implementation_of_specific_ada_features image-values-for-nonscalar-types}@anchor{432} |
b71d4b62 RA |
26424 | @section Image Values For Nonscalar Types |
26425 | ||
26426 | ||
26427 | Ada 2022 defines the Image, Wide_Image, and Wide_Wide image attributes | |
26428 | for nonscalar types; earlier Ada versions defined these attributes only | |
26429 | for scalar types. Ada RM 4.10 provides some general guidance regarding | |
26430 | the default implementation of these attributes and the GNAT compiler | |
26431 | follows that guidance. However, beyond that the precise details of the | |
26432 | image text generated in these cases are deliberately not documented and are | |
26433 | subject to change. In particular, users should not rely on formatting details | |
26434 | (such as spaces or line breaking), record field order, image values for access | |
26435 | types, image values for types that have ancestor or subcomponent types | |
26436 | declared in non-Ada2022 code, image values for predefined types, or the | |
26437 | compiler’s choices regarding the implementation permissions described in | |
26438 | Ada RM 4.10. This list is not intended to be exhaustive. If more precise | |
26439 | control of image text is required for some type T, then T’Put_Image should be | |
26440 | explicitly specified. | |
26441 | ||
26442 | @node Strict Conformance to the Ada Reference Manual,,Image Values For Nonscalar Types,Implementation of Specific Ada Features | |
9daee425 | 26443 | @anchor{gnat_rm/implementation_of_specific_ada_features id15}@anchor{433}@anchor{gnat_rm/implementation_of_specific_ada_features strict-conformance-to-the-ada-reference-manual}@anchor{434} |
b71d4b62 RA |
26444 | @section Strict Conformance to the Ada Reference Manual |
26445 | ||
26446 | ||
26447 | The dynamic semantics defined by the Ada Reference Manual impose a set of | |
26448 | run-time checks to be generated. By default, the GNAT compiler will insert many | |
26449 | run-time checks into the compiled code, including most of those required by the | |
26450 | Ada Reference Manual. However, there are two checks that are not enabled in | |
26451 | the default mode for efficiency reasons: checks for access before elaboration | |
26452 | on subprogram calls, and stack overflow checking (most operating systems do not | |
26453 | perform this check by default). | |
26454 | ||
26455 | Strict conformance to the Ada Reference Manual can be achieved by adding two | |
26456 | compiler options for dynamic checks for access-before-elaboration on subprogram | |
1acce141 YM |
26457 | calls and generic instantiations (@emph{-gnatE}), and stack overflow checking |
26458 | (@emph{-fstack-check}). | |
b71d4b62 RA |
26459 | |
26460 | Note that the result of a floating point arithmetic operation in overflow and | |
26461 | invalid situations, when the @code{Machine_Overflows} attribute of the result | |
26462 | type is @code{False}, is to generate IEEE NaN and infinite values. This is the | |
26463 | case for machines compliant with the IEEE floating-point standard, but on | |
26464 | machines that are not fully compliant with this standard, such as Alpha, the | |
1acce141 | 26465 | @emph{-mieee} compiler flag must be used for achieving IEEE confirming |
b71d4b62 RA |
26466 | behavior (although at the cost of a significant performance penalty), so |
26467 | infinite and NaN values are properly generated. | |
26468 | ||
26469 | @node Implementation of Ada 2012 Features,GNAT language extensions,Implementation of Specific Ada Features,Top | |
9daee425 | 26470 | @anchor{gnat_rm/implementation_of_ada_2012_features doc}@anchor{435}@anchor{gnat_rm/implementation_of_ada_2012_features id1}@anchor{436}@anchor{gnat_rm/implementation_of_ada_2012_features implementation-of-ada-2012-features}@anchor{14} |
b71d4b62 RA |
26471 | @chapter Implementation of Ada 2012 Features |
26472 | ||
26473 | ||
26474 | @geindex Ada 2012 implementation status | |
26475 | ||
26476 | @geindex -gnat12 option (gcc) | |
26477 | ||
26478 | @geindex pragma Ada_2012 | |
26479 | ||
26480 | @geindex configuration pragma Ada_2012 | |
26481 | ||
26482 | @geindex Ada_2012 configuration pragma | |
26483 | ||
26484 | This chapter contains a complete list of Ada 2012 features that have been | |
26485 | implemented. | |
26486 | Generally, these features are only | |
1acce141 | 26487 | available if the @emph{-gnat12} (Ada 2012 features enabled) option is set, |
b71d4b62 RA |
26488 | which is the default behavior, |
26489 | or if the configuration pragma @code{Ada_2012} is used. | |
26490 | ||
26491 | However, new pragmas, attributes, and restrictions are | |
26492 | unconditionally available, since the Ada 95 standard allows the addition of | |
26493 | new pragmas, attributes, and restrictions (there are exceptions, which are | |
26494 | documented in the individual descriptions), and also certain packages | |
26495 | were made available in earlier versions of Ada. | |
26496 | ||
26497 | An ISO date (YYYY-MM-DD) appears in parentheses on the description line. | |
26498 | This date shows the implementation date of the feature. Any wavefront | |
26499 | subsequent to this date will contain the indicated feature, as will any | |
26500 | subsequent releases. A date of 0000-00-00 means that GNAT has always | |
26501 | implemented the feature, or implemented it as soon as it appeared as a | |
26502 | binding interpretation. | |
26503 | ||
26504 | Each feature corresponds to an Ada Issue (‘AI’) approved by the Ada | |
26505 | standardization group (ISO/IEC JTC1/SC22/WG9) for inclusion in Ada 2012. | |
26506 | The features are ordered based on the relevant sections of the Ada | |
26507 | Reference Manual (“RM”). When a given AI relates to multiple points | |
26508 | in the RM, the earliest is used. | |
26509 | ||
26510 | A complete description of the AIs may be found in | |
26511 | @indicateurl{http://www.ada-auth.org/ai05-summary.html}. | |
26512 | ||
26513 | @geindex AI-0176 (Ada 2012 feature) | |
64d5610f | 26514 | |
64d5610f | 26515 | |
b71d4b62 | 26516 | @itemize * |
64d5610f | 26517 | |
b71d4b62 | 26518 | @item |
1acce141 | 26519 | @emph{AI-0176 Quantified expressions (2010-09-29)} |
64d5610f | 26520 | |
b71d4b62 RA |
26521 | Both universally and existentially quantified expressions are implemented. |
26522 | They use the new syntax for iterators proposed in AI05-139-2, as well as | |
26523 | the standard Ada loop syntax. | |
64d5610f | 26524 | |
b71d4b62 RA |
26525 | RM References: 1.01.04 (12) 2.09 (2/2) 4.04 (7) 4.05.09 (0) |
26526 | @end itemize | |
64d5610f | 26527 | |
b71d4b62 | 26528 | @geindex AI-0079 (Ada 2012 feature) |
64d5610f | 26529 | |
64d5610f | 26530 | |
b71d4b62 | 26531 | @itemize * |
64d5610f | 26532 | |
b71d4b62 | 26533 | @item |
1acce141 | 26534 | @emph{AI-0079 Allow other_format characters in source (2010-07-10)} |
64d5610f | 26535 | |
1acce141 | 26536 | Wide characters in the unicode category @emph{other_format} are now allowed in |
b71d4b62 | 26537 | source programs between tokens, but not within a token such as an identifier. |
64d5610f | 26538 | |
b71d4b62 RA |
26539 | RM References: 2.01 (4/2) 2.02 (7) |
26540 | @end itemize | |
64d5610f | 26541 | |
b71d4b62 | 26542 | @geindex AI-0091 (Ada 2012 feature) |
64d5610f | 26543 | |
64d5610f | 26544 | |
b71d4b62 RA |
26545 | @itemize * |
26546 | ||
26547 | @item | |
1acce141 | 26548 | @emph{AI-0091 Do not allow other_format in identifiers (0000-00-00)} |
64d5610f | 26549 | |
1acce141 | 26550 | Wide characters in the unicode category @emph{other_format} are not permitted |
b71d4b62 RA |
26551 | within an identifier, since this can be a security problem. The error |
26552 | message for this case has been improved to be more specific, but GNAT has | |
26553 | never allowed such characters to appear in identifiers. | |
64d5610f | 26554 | |
b71d4b62 RA |
26555 | RM References: 2.03 (3.1/2) 2.03 (4/2) 2.03 (5/2) 2.03 (5.1/2) 2.03 (5.2/2) 2.03 (5.3/2) 2.09 (2/2) |
26556 | @end itemize | |
26557 | ||
26558 | @geindex AI-0100 (Ada 2012 feature) | |
64d5610f ML |
26559 | |
26560 | ||
26561 | @itemize * | |
26562 | ||
26563 | @item | |
1acce141 | 26564 | @emph{AI-0100 Placement of pragmas (2010-07-01)} |
64d5610f | 26565 | |
b71d4b62 RA |
26566 | This AI is an earlier version of AI-163. It simplifies the rules |
26567 | for legal placement of pragmas. In the case of lists that allow pragmas, if | |
26568 | the list may have no elements, then the list may consist solely of pragmas. | |
26569 | ||
26570 | RM References: 2.08 (7) | |
64d5610f ML |
26571 | @end itemize |
26572 | ||
b71d4b62 | 26573 | @geindex AI-0163 (Ada 2012 feature) |
64d5610f | 26574 | |
64d5610f | 26575 | |
b71d4b62 | 26576 | @itemize * |
64d5610f | 26577 | |
b71d4b62 | 26578 | @item |
1acce141 | 26579 | @emph{AI-0163 Pragmas in place of null (2010-07-01)} |
64d5610f | 26580 | |
b71d4b62 RA |
26581 | A statement sequence may be composed entirely of pragmas. It is no longer |
26582 | necessary to add a dummy @code{null} statement to make the sequence legal. | |
26583 | ||
26584 | RM References: 2.08 (7) 2.08 (16) | |
26585 | @end itemize | |
26586 | ||
26587 | @geindex AI-0080 (Ada 2012 feature) | |
64d5610f ML |
26588 | |
26589 | ||
26590 | @itemize * | |
26591 | ||
26592 | @item | |
1acce141 | 26593 | @emph{AI-0080 ‘View of’ not needed if clear from context (0000-00-00)} |
64d5610f | 26594 | |
b71d4b62 | 26595 | This is an editorial change only, described as non-testable in the AI. |
64d5610f | 26596 | |
b71d4b62 RA |
26597 | RM References: 3.01 (7) |
26598 | @end itemize | |
26599 | ||
26600 | @geindex AI-0183 (Ada 2012 feature) | |
26601 | ||
26602 | ||
26603 | @itemize * | |
64d5610f ML |
26604 | |
26605 | @item | |
1acce141 | 26606 | @emph{AI-0183 Aspect specifications (2010-08-16)} |
b71d4b62 RA |
26607 | |
26608 | Aspect specifications have been fully implemented except for pre and post- | |
26609 | conditions, and type invariants, which have their own separate AI’s. All | |
26610 | forms of declarations listed in the AI are supported. The following is a | |
26611 | list of the aspects supported (with GNAT implementation aspects marked) | |
64d5610f ML |
26612 | @end itemize |
26613 | ||
64d5610f | 26614 | |
b71d4b62 RA |
26615 | @multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxx} |
26616 | @headitem | |
64d5610f | 26617 | |
b71d4b62 | 26618 | Supported Aspect |
64d5610f | 26619 | |
b71d4b62 | 26620 | @tab |
64d5610f | 26621 | |
b71d4b62 | 26622 | Source |
64d5610f | 26623 | |
b71d4b62 | 26624 | @item |
64d5610f | 26625 | |
b71d4b62 | 26626 | @code{Ada_2005} |
64d5610f | 26627 | |
b71d4b62 | 26628 | @tab |
64d5610f | 26629 | |
b71d4b62 | 26630 | – GNAT |
64d5610f | 26631 | |
b71d4b62 | 26632 | @item |
64d5610f | 26633 | |
b71d4b62 | 26634 | @code{Ada_2012} |
64d5610f | 26635 | |
b71d4b62 | 26636 | @tab |
64d5610f | 26637 | |
b71d4b62 | 26638 | – GNAT |
64d5610f | 26639 | |
b71d4b62 | 26640 | @item |
64d5610f | 26641 | |
b71d4b62 | 26642 | @code{Address} |
64d5610f | 26643 | |
b71d4b62 RA |
26644 | @tab |
26645 | ||
26646 | @item | |
26647 | ||
26648 | @code{Alignment} | |
26649 | ||
26650 | @tab | |
26651 | ||
26652 | @item | |
26653 | ||
26654 | @code{Atomic} | |
26655 | ||
26656 | @tab | |
26657 | ||
26658 | @item | |
26659 | ||
26660 | @code{Atomic_Components} | |
26661 | ||
26662 | @tab | |
26663 | ||
26664 | @item | |
26665 | ||
26666 | @code{Bit_Order} | |
26667 | ||
26668 | @tab | |
26669 | ||
26670 | @item | |
26671 | ||
26672 | @code{Component_Size} | |
26673 | ||
26674 | @tab | |
26675 | ||
26676 | @item | |
26677 | ||
26678 | @code{Contract_Cases} | |
26679 | ||
26680 | @tab | |
26681 | ||
26682 | – GNAT | |
26683 | ||
26684 | @item | |
26685 | ||
26686 | @code{Discard_Names} | |
26687 | ||
26688 | @tab | |
26689 | ||
26690 | @item | |
26691 | ||
26692 | @code{External_Tag} | |
64d5610f | 26693 | |
b71d4b62 | 26694 | @tab |
64d5610f | 26695 | |
b71d4b62 | 26696 | @item |
64d5610f | 26697 | |
b71d4b62 | 26698 | @code{Favor_Top_Level} |
64d5610f | 26699 | |
b71d4b62 | 26700 | @tab |
64d5610f | 26701 | |
b71d4b62 | 26702 | – GNAT |
64d5610f | 26703 | |
b71d4b62 | 26704 | @item |
64d5610f | 26705 | |
b71d4b62 | 26706 | @code{Inline} |
64d5610f | 26707 | |
b71d4b62 | 26708 | @tab |
64d5610f | 26709 | |
b71d4b62 | 26710 | @item |
64d5610f | 26711 | |
b71d4b62 | 26712 | @code{Inline_Always} |
64d5610f | 26713 | |
b71d4b62 | 26714 | @tab |
64d5610f | 26715 | |
b71d4b62 | 26716 | – GNAT |
64d5610f | 26717 | |
b71d4b62 | 26718 | @item |
64d5610f | 26719 | |
b71d4b62 | 26720 | @code{Invariant} |
64d5610f | 26721 | |
b71d4b62 | 26722 | @tab |
64d5610f | 26723 | |
b71d4b62 | 26724 | – GNAT |
64d5610f | 26725 | |
b71d4b62 | 26726 | @item |
64d5610f | 26727 | |
b71d4b62 | 26728 | @code{Machine_Radix} |
64d5610f | 26729 | |
b71d4b62 | 26730 | @tab |
64d5610f | 26731 | |
b71d4b62 | 26732 | @item |
64d5610f | 26733 | |
b71d4b62 | 26734 | @code{No_Return} |
64d5610f | 26735 | |
b71d4b62 | 26736 | @tab |
64d5610f | 26737 | |
b71d4b62 | 26738 | @item |
64d5610f | 26739 | |
b71d4b62 | 26740 | @code{Object_Size} |
64d5610f | 26741 | |
b71d4b62 | 26742 | @tab |
64d5610f | 26743 | |
b71d4b62 | 26744 | – GNAT |
64d5610f | 26745 | |
b71d4b62 | 26746 | @item |
64d5610f | 26747 | |
b71d4b62 | 26748 | @code{Pack} |
64d5610f | 26749 | |
b71d4b62 | 26750 | @tab |
64d5610f | 26751 | |
b71d4b62 | 26752 | @item |
64d5610f | 26753 | |
b71d4b62 | 26754 | @code{Persistent_BSS} |
64d5610f | 26755 | |
b71d4b62 | 26756 | @tab |
64d5610f | 26757 | |
b71d4b62 | 26758 | – GNAT |
64d5610f | 26759 | |
b71d4b62 | 26760 | @item |
64d5610f | 26761 | |
b71d4b62 | 26762 | @code{Post} |
64d5610f | 26763 | |
b71d4b62 | 26764 | @tab |
64d5610f | 26765 | |
b71d4b62 | 26766 | @item |
64d5610f | 26767 | |
b71d4b62 | 26768 | @code{Pre} |
64d5610f | 26769 | |
b71d4b62 | 26770 | @tab |
64d5610f | 26771 | |
b71d4b62 | 26772 | @item |
64d5610f | 26773 | |
b71d4b62 | 26774 | @code{Predicate} |
64d5610f | 26775 | |
b71d4b62 | 26776 | @tab |
64d5610f | 26777 | |
b71d4b62 | 26778 | @item |
64d5610f | 26779 | |
b71d4b62 | 26780 | @code{Preelaborable_Initialization} |
64d5610f | 26781 | |
b71d4b62 | 26782 | @tab |
64d5610f | 26783 | |
b71d4b62 | 26784 | @item |
64d5610f | 26785 | |
b71d4b62 | 26786 | @code{Pure_Function} |
64d5610f | 26787 | |
b71d4b62 | 26788 | @tab |
64d5610f | 26789 | |
b71d4b62 | 26790 | – GNAT |
64d5610f | 26791 | |
b71d4b62 | 26792 | @item |
64d5610f | 26793 | |
b71d4b62 | 26794 | @code{Remote_Access_Type} |
64d5610f | 26795 | |
b71d4b62 | 26796 | @tab |
64d5610f | 26797 | |
b71d4b62 | 26798 | – GNAT |
64d5610f | 26799 | |
b71d4b62 | 26800 | @item |
64d5610f | 26801 | |
b71d4b62 | 26802 | @code{Shared} |
64d5610f | 26803 | |
b71d4b62 | 26804 | @tab |
64d5610f | 26805 | |
b71d4b62 | 26806 | – GNAT |
64d5610f | 26807 | |
b71d4b62 | 26808 | @item |
64d5610f | 26809 | |
b71d4b62 RA |
26810 | @code{Size} |
26811 | ||
26812 | @tab | |
64d5610f | 26813 | |
b71d4b62 | 26814 | @item |
64d5610f | 26815 | |
b71d4b62 | 26816 | @code{Storage_Pool} |
64d5610f | 26817 | |
b71d4b62 | 26818 | @tab |
64d5610f | 26819 | |
b71d4b62 | 26820 | @item |
64d5610f | 26821 | |
b71d4b62 | 26822 | @code{Storage_Size} |
64d5610f | 26823 | |
b71d4b62 | 26824 | @tab |
64d5610f | 26825 | |
b71d4b62 | 26826 | @item |
64d5610f | 26827 | |
b71d4b62 | 26828 | @code{Stream_Size} |
64d5610f | 26829 | |
b71d4b62 | 26830 | @tab |
64d5610f | 26831 | |
b71d4b62 | 26832 | @item |
64d5610f | 26833 | |
b71d4b62 | 26834 | @code{Suppress} |
64d5610f | 26835 | |
b71d4b62 | 26836 | @tab |
64d5610f | 26837 | |
b71d4b62 | 26838 | @item |
64d5610f | 26839 | |
b71d4b62 | 26840 | @code{Suppress_Debug_Info} |
64d5610f | 26841 | |
b71d4b62 | 26842 | @tab |
64d5610f | 26843 | |
b71d4b62 | 26844 | – GNAT |
64d5610f | 26845 | |
b71d4b62 | 26846 | @item |
64d5610f | 26847 | |
b71d4b62 | 26848 | @code{Test_Case} |
64d5610f | 26849 | |
b71d4b62 | 26850 | @tab |
64d5610f | 26851 | |
b71d4b62 | 26852 | – GNAT |
64d5610f | 26853 | |
b71d4b62 | 26854 | @item |
64d5610f | 26855 | |
b71d4b62 | 26856 | @code{Thread_Local_Storage} |
64d5610f | 26857 | |
b71d4b62 | 26858 | @tab |
64d5610f | 26859 | |
b71d4b62 | 26860 | – GNAT |
64d5610f | 26861 | |
b71d4b62 | 26862 | @item |
64d5610f | 26863 | |
b71d4b62 | 26864 | @code{Type_Invariant} |
64d5610f | 26865 | |
b71d4b62 | 26866 | @tab |
64d5610f | 26867 | |
b71d4b62 | 26868 | @item |
64d5610f | 26869 | |
b71d4b62 | 26870 | @code{Unchecked_Union} |
64d5610f | 26871 | |
b71d4b62 | 26872 | @tab |
64d5610f | 26873 | |
b71d4b62 | 26874 | @item |
64d5610f | 26875 | |
b71d4b62 | 26876 | @code{Universal_Aliasing} |
64d5610f | 26877 | |
b71d4b62 | 26878 | @tab |
64d5610f | 26879 | |
b71d4b62 | 26880 | – GNAT |
64d5610f | 26881 | |
b71d4b62 | 26882 | @item |
64d5610f | 26883 | |
b71d4b62 | 26884 | @code{Unmodified} |
64d5610f | 26885 | |
b71d4b62 | 26886 | @tab |
64d5610f | 26887 | |
b71d4b62 | 26888 | – GNAT |
64d5610f | 26889 | |
b71d4b62 | 26890 | @item |
64d5610f | 26891 | |
b71d4b62 | 26892 | @code{Unreferenced} |
64d5610f | 26893 | |
b71d4b62 | 26894 | @tab |
64d5610f | 26895 | |
b71d4b62 | 26896 | – GNAT |
64d5610f | 26897 | |
b71d4b62 | 26898 | @item |
64d5610f | 26899 | |
b71d4b62 | 26900 | @code{Unreferenced_Objects} |
64d5610f | 26901 | |
b71d4b62 | 26902 | @tab |
64d5610f | 26903 | |
b71d4b62 | 26904 | – GNAT |
64d5610f | 26905 | |
b71d4b62 | 26906 | @item |
64d5610f | 26907 | |
b71d4b62 | 26908 | @code{Unsuppress} |
64d5610f | 26909 | |
b71d4b62 | 26910 | @tab |
64d5610f | 26911 | |
b71d4b62 | 26912 | @item |
64d5610f | 26913 | |
b71d4b62 | 26914 | @code{Value_Size} |
64d5610f | 26915 | |
b71d4b62 | 26916 | @tab |
64d5610f | 26917 | |
b71d4b62 | 26918 | – GNAT |
64d5610f | 26919 | |
b71d4b62 | 26920 | @item |
64d5610f | 26921 | |
b71d4b62 | 26922 | @code{Volatile} |
64d5610f | 26923 | |
b71d4b62 | 26924 | @tab |
64d5610f | 26925 | |
b71d4b62 | 26926 | @item |
64d5610f | 26927 | |
b71d4b62 | 26928 | @code{Volatile_Components} |
64d5610f | 26929 | |
b71d4b62 | 26930 | @tab |
64d5610f | 26931 | |
b71d4b62 | 26932 | @item |
64d5610f | 26933 | |
b71d4b62 | 26934 | @code{Warnings} |
64d5610f | 26935 | |
b71d4b62 | 26936 | @tab |
64d5610f | 26937 | |
b71d4b62 | 26938 | – GNAT |
64d5610f | 26939 | |
b71d4b62 | 26940 | @end multitable |
64d5610f | 26941 | |
64d5610f | 26942 | |
b71d4b62 | 26943 | @quotation |
64d5610f | 26944 | |
b71d4b62 RA |
26945 | Note that for aspects with an expression, e.g. @code{Size}, the expression is |
26946 | treated like a default expression (visibility is analyzed at the point of | |
26947 | occurrence of the aspect, but evaluation of the expression occurs at the | |
26948 | freeze point of the entity involved). | |
64d5610f | 26949 | |
b71d4b62 RA |
26950 | RM References: 3.02.01 (3) 3.02.02 (2) 3.03.01 (2/2) 3.08 (6) |
26951 | 3.09.03 (1.1/2) 6.01 (2/2) 6.07 (2/2) 9.05.02 (2/2) 7.01 (3) 7.03 | |
26952 | (2) 7.03 (3) 9.01 (2/2) 9.01 (3/2) 9.04 (2/2) 9.04 (3/2) | |
26953 | 9.05.02 (2/2) 11.01 (2) 12.01 (3) 12.03 (2/2) 12.04 (2/2) 12.05 (2) | |
26954 | 12.06 (2.1/2) 12.06 (2.2/2) 12.07 (2) 13.01 (0.1/2) 13.03 (5/1) | |
26955 | 13.03.01 (0) | |
26956 | @end quotation | |
64d5610f | 26957 | |
b71d4b62 | 26958 | @geindex AI-0128 (Ada 2012 feature) |
64d5610f ML |
26959 | |
26960 | ||
26961 | @itemize * | |
26962 | ||
26963 | @item | |
1acce141 | 26964 | @emph{AI-0128 Inequality is a primitive operation (0000-00-00)} |
64d5610f | 26965 | |
b71d4b62 RA |
26966 | If an equality operator (“=”) is declared for a type, then the implicitly |
26967 | declared inequality operator (“/=”) is a primitive operation of the type. | |
26968 | This is the only reasonable interpretation, and is the one always implemented | |
26969 | by GNAT, but the RM was not entirely clear in making this point. | |
64d5610f | 26970 | |
b71d4b62 | 26971 | RM References: 3.02.03 (6) 6.06 (6) |
64d5610f ML |
26972 | @end itemize |
26973 | ||
b71d4b62 | 26974 | @geindex AI-0003 (Ada 2012 feature) |
64d5610f ML |
26975 | |
26976 | ||
26977 | @itemize * | |
26978 | ||
26979 | @item | |
1acce141 | 26980 | @emph{AI-0003 Qualified expressions as names (2010-07-11)} |
64d5610f | 26981 | |
b71d4b62 RA |
26982 | In Ada 2012, a qualified expression is considered to be syntactically a name, |
26983 | meaning that constructs such as @code{A'(F(X)).B} are now legal. This is | |
26984 | useful in disambiguating some cases of overloading. | |
64d5610f | 26985 | |
b71d4b62 RA |
26986 | RM References: 3.03 (11) 3.03 (21) 4.01 (2) 4.04 (7) 4.07 (3) |
26987 | 5.04 (7) | |
64d5610f ML |
26988 | @end itemize |
26989 | ||
b71d4b62 | 26990 | @geindex AI-0120 (Ada 2012 feature) |
64d5610f ML |
26991 | |
26992 | ||
26993 | @itemize * | |
26994 | ||
26995 | @item | |
1acce141 | 26996 | @emph{AI-0120 Constant instance of protected object (0000-00-00)} |
64d5610f | 26997 | |
b71d4b62 RA |
26998 | This is an RM editorial change only. The section that lists objects that are |
26999 | constant failed to include the current instance of a protected object | |
27000 | within a protected function. This has always been treated as a constant | |
27001 | in GNAT. | |
64d5610f | 27002 | |
b71d4b62 | 27003 | RM References: 3.03 (21) |
64d5610f ML |
27004 | @end itemize |
27005 | ||
b71d4b62 | 27006 | @geindex AI-0008 (Ada 2012 feature) |
64d5610f ML |
27007 | |
27008 | ||
27009 | @itemize * | |
27010 | ||
27011 | @item | |
1acce141 | 27012 | @emph{AI-0008 General access to constrained objects (0000-00-00)} |
64d5610f | 27013 | |
b71d4b62 RA |
27014 | The wording in the RM implied that if you have a general access to a |
27015 | constrained object, it could be used to modify the discriminants. This was | |
27016 | obviously not intended. @code{Constraint_Error} should be raised, and GNAT | |
27017 | has always done so in this situation. | |
64d5610f | 27018 | |
b71d4b62 RA |
27019 | RM References: 3.03 (23) 3.10.02 (26/2) 4.01 (9) 6.04.01 (17) 8.05.01 (5/2) |
27020 | @end itemize | |
64d5610f | 27021 | |
b71d4b62 | 27022 | @geindex AI-0093 (Ada 2012 feature) |
64d5610f | 27023 | |
64d5610f | 27024 | |
b71d4b62 | 27025 | @itemize * |
64d5610f | 27026 | |
b71d4b62 | 27027 | @item |
1acce141 | 27028 | @emph{AI-0093 Additional rules use immutably limited (0000-00-00)} |
64d5610f | 27029 | |
b71d4b62 RA |
27030 | This is an editorial change only, to make more widespread use of the Ada 2012 |
27031 | ‘immutably limited’. | |
64d5610f | 27032 | |
b71d4b62 RA |
27033 | RM References: 3.03 (23.4/3) |
27034 | @end itemize | |
64d5610f | 27035 | |
b71d4b62 | 27036 | @geindex AI-0096 (Ada 2012 feature) |
64d5610f | 27037 | |
64d5610f | 27038 | |
b71d4b62 | 27039 | @itemize * |
64d5610f | 27040 | |
b71d4b62 | 27041 | @item |
1acce141 | 27042 | @emph{AI-0096 Deriving from formal private types (2010-07-20)} |
64d5610f | 27043 | |
b71d4b62 RA |
27044 | In general it is illegal for a type derived from a formal limited type to be |
27045 | nonlimited. This AI makes an exception to this rule: derivation is legal | |
27046 | if it appears in the private part of the generic, and the formal type is not | |
27047 | tagged. If the type is tagged, the legality check must be applied to the | |
27048 | private part of the package. | |
64d5610f | 27049 | |
b71d4b62 RA |
27050 | RM References: 3.04 (5.1/2) 6.02 (7) |
27051 | @end itemize | |
64d5610f | 27052 | |
b71d4b62 | 27053 | @geindex AI-0181 (Ada 2012 feature) |
64d5610f | 27054 | |
64d5610f | 27055 | |
b71d4b62 | 27056 | @itemize * |
64d5610f | 27057 | |
b71d4b62 | 27058 | @item |
1acce141 | 27059 | @emph{AI-0181 Soft hyphen is a non-graphic character (2010-07-23)} |
64d5610f | 27060 | |
b71d4b62 RA |
27061 | From Ada 2005 on, soft hyphen is considered a non-graphic character, which |
27062 | means that it has a special name (@code{SOFT_HYPHEN}) in conjunction with the | |
27063 | @code{Image} and @code{Value} attributes for the character types. Strictly | |
27064 | speaking this is an inconsistency with Ada 95, but in practice the use of | |
27065 | these attributes is so obscure that it will not cause problems. | |
64d5610f | 27066 | |
b71d4b62 RA |
27067 | RM References: 3.05.02 (2/2) A.01 (35/2) A.03.03 (21) |
27068 | @end itemize | |
64d5610f | 27069 | |
b71d4b62 | 27070 | @geindex AI-0182 (Ada 2012 feature) |
64d5610f | 27071 | |
64d5610f | 27072 | |
b71d4b62 | 27073 | @itemize * |
64d5610f | 27074 | |
b71d4b62 | 27075 | @item |
1acce141 | 27076 | @emph{AI-0182 Additional forms for} @code{Character'Value} @emph{(0000-00-00)} |
64d5610f | 27077 | |
b71d4b62 RA |
27078 | This AI allows @code{Character'Value} to accept the string @code{'?'} where |
27079 | @code{?} is any character including non-graphic control characters. GNAT has | |
27080 | always accepted such strings. It also allows strings such as | |
27081 | @code{HEX_00000041} to be accepted, but GNAT does not take advantage of this | |
27082 | permission and raises @code{Constraint_Error}, as is certainly still | |
27083 | permitted. | |
64d5610f | 27084 | |
b71d4b62 RA |
27085 | RM References: 3.05 (56/2) |
27086 | @end itemize | |
64d5610f | 27087 | |
b71d4b62 | 27088 | @geindex AI-0214 (Ada 2012 feature) |
64d5610f | 27089 | |
64d5610f | 27090 | |
b71d4b62 | 27091 | @itemize * |
64d5610f | 27092 | |
b71d4b62 | 27093 | @item |
1acce141 | 27094 | @emph{AI-0214 Defaulted discriminants for limited tagged (2010-10-01)} |
64d5610f | 27095 | |
b71d4b62 RA |
27096 | Ada 2012 relaxes the restriction that forbids discriminants of tagged types |
27097 | to have default expressions by allowing them when the type is limited. It | |
27098 | is often useful to define a default value for a discriminant even though | |
27099 | it can’t be changed by assignment. | |
64d5610f | 27100 | |
b71d4b62 RA |
27101 | RM References: 3.07 (9.1/2) 3.07.02 (3) |
27102 | @end itemize | |
64d5610f | 27103 | |
b71d4b62 | 27104 | @geindex AI-0102 (Ada 2012 feature) |
64d5610f | 27105 | |
64d5610f | 27106 | |
b71d4b62 | 27107 | @itemize * |
64d5610f | 27108 | |
b71d4b62 | 27109 | @item |
1acce141 | 27110 | @emph{AI-0102 Some implicit conversions are illegal (0000-00-00)} |
64d5610f | 27111 | |
b71d4b62 RA |
27112 | It is illegal to assign an anonymous access constant to an anonymous access |
27113 | variable. The RM did not have a clear rule to prevent this, but GNAT has | |
27114 | always generated an error for this usage. | |
64d5610f | 27115 | |
b71d4b62 RA |
27116 | RM References: 3.07 (16) 3.07.01 (9) 6.04.01 (6) 8.06 (27/2) |
27117 | @end itemize | |
64d5610f | 27118 | |
b71d4b62 | 27119 | @geindex AI-0158 (Ada 2012 feature) |
64d5610f | 27120 | |
64d5610f | 27121 | |
b71d4b62 | 27122 | @itemize * |
64d5610f | 27123 | |
b71d4b62 | 27124 | @item |
1acce141 | 27125 | @emph{AI-0158 Generalizing membership tests (2010-09-16)} |
64d5610f | 27126 | |
b71d4b62 RA |
27127 | This AI extends the syntax of membership tests to simplify complex conditions |
27128 | that can be expressed as membership in a subset of values of any type. It | |
27129 | introduces syntax for a list of expressions that may be used in loop contexts | |
27130 | as well. | |
64d5610f | 27131 | |
b71d4b62 RA |
27132 | RM References: 3.08.01 (5) 4.04 (3) 4.05.02 (3) 4.05.02 (5) 4.05.02 (27) |
27133 | @end itemize | |
64d5610f | 27134 | |
b71d4b62 | 27135 | @geindex AI-0173 (Ada 2012 feature) |
64d5610f | 27136 | |
64d5610f | 27137 | |
b71d4b62 | 27138 | @itemize * |
64d5610f | 27139 | |
b71d4b62 | 27140 | @item |
1acce141 | 27141 | @emph{AI-0173 Testing if tags represent abstract types (2010-07-03)} |
64d5610f | 27142 | |
b71d4b62 RA |
27143 | The function @code{Ada.Tags.Type_Is_Abstract} returns @code{True} if invoked |
27144 | with the tag of an abstract type, and @code{False} otherwise. | |
64d5610f | 27145 | |
b71d4b62 RA |
27146 | RM References: 3.09 (7.4/2) 3.09 (12.4/2) |
27147 | @end itemize | |
64d5610f | 27148 | |
b71d4b62 | 27149 | @geindex AI-0076 (Ada 2012 feature) |
64d5610f | 27150 | |
64d5610f | 27151 | |
b71d4b62 | 27152 | @itemize * |
64d5610f | 27153 | |
b71d4b62 | 27154 | @item |
1acce141 | 27155 | @emph{AI-0076 function with controlling result (0000-00-00)} |
64d5610f | 27156 | |
b71d4b62 RA |
27157 | This is an editorial change only. The RM defines calls with controlling |
27158 | results, but uses the term ‘function with controlling result’ without an | |
27159 | explicit definition. | |
64d5610f | 27160 | |
b71d4b62 RA |
27161 | RM References: 3.09.02 (2/2) |
27162 | @end itemize | |
64d5610f | 27163 | |
b71d4b62 | 27164 | @geindex AI-0126 (Ada 2012 feature) |
64d5610f | 27165 | |
64d5610f | 27166 | |
b71d4b62 | 27167 | @itemize * |
64d5610f | 27168 | |
b71d4b62 | 27169 | @item |
1acce141 | 27170 | @emph{AI-0126 Dispatching with no declared operation (0000-00-00)} |
64d5610f | 27171 | |
b71d4b62 RA |
27172 | This AI clarifies dispatching rules, and simply confirms that dispatching |
27173 | executes the operation of the parent type when there is no explicitly or | |
27174 | implicitly declared operation for the descendant type. This has always been | |
27175 | the case in all versions of GNAT. | |
64d5610f | 27176 | |
b71d4b62 RA |
27177 | RM References: 3.09.02 (20/2) 3.09.02 (20.1/2) 3.09.02 (20.2/2) |
27178 | @end itemize | |
64d5610f | 27179 | |
b71d4b62 | 27180 | @geindex AI-0097 (Ada 2012 feature) |
64d5610f | 27181 | |
64d5610f | 27182 | |
b71d4b62 | 27183 | @itemize * |
64d5610f | 27184 | |
b71d4b62 | 27185 | @item |
1acce141 | 27186 | @emph{AI-0097 Treatment of abstract null extension (2010-07-19)} |
64d5610f | 27187 | |
b71d4b62 RA |
27188 | The RM as written implied that in some cases it was possible to create an |
27189 | object of an abstract type, by having an abstract extension inherit a non- | |
27190 | abstract constructor from its parent type. This mistake has been corrected | |
27191 | in GNAT and in the RM, and this construct is now illegal. | |
64d5610f | 27192 | |
b71d4b62 RA |
27193 | RM References: 3.09.03 (4/2) |
27194 | @end itemize | |
64d5610f | 27195 | |
b71d4b62 | 27196 | @geindex AI-0203 (Ada 2012 feature) |
64d5610f | 27197 | |
64d5610f | 27198 | |
b71d4b62 | 27199 | @itemize * |
64d5610f | 27200 | |
b71d4b62 | 27201 | @item |
1acce141 | 27202 | @emph{AI-0203 Extended return cannot be abstract (0000-00-00)} |
64d5610f | 27203 | |
b71d4b62 RA |
27204 | A return_subtype_indication cannot denote an abstract subtype. GNAT has never |
27205 | permitted such usage. | |
64d5610f | 27206 | |
b71d4b62 RA |
27207 | RM References: 3.09.03 (8/3) |
27208 | @end itemize | |
64d5610f | 27209 | |
b71d4b62 | 27210 | @geindex AI-0198 (Ada 2012 feature) |
64d5610f | 27211 | |
64d5610f | 27212 | |
b71d4b62 | 27213 | @itemize * |
64d5610f | 27214 | |
b71d4b62 | 27215 | @item |
1acce141 | 27216 | @emph{AI-0198 Inheriting abstract operators (0000-00-00)} |
64d5610f | 27217 | |
b71d4b62 RA |
27218 | This AI resolves a conflict between two rules involving inherited abstract |
27219 | operations and predefined operators. If a derived numeric type inherits | |
27220 | an abstract operator, it overrides the predefined one. This interpretation | |
27221 | was always the one implemented in GNAT. | |
64d5610f | 27222 | |
b71d4b62 RA |
27223 | RM References: 3.09.03 (4/3) |
27224 | @end itemize | |
64d5610f | 27225 | |
b71d4b62 | 27226 | @geindex AI-0073 (Ada 2012 feature) |
64d5610f | 27227 | |
64d5610f | 27228 | |
b71d4b62 | 27229 | @itemize * |
64d5610f | 27230 | |
b71d4b62 | 27231 | @item |
1acce141 | 27232 | @emph{AI-0073 Functions returning abstract types (2010-07-10)} |
64d5610f | 27233 | |
b71d4b62 RA |
27234 | This AI covers a number of issues regarding returning abstract types. In |
27235 | particular generic functions cannot have abstract result types or access | |
27236 | result types designated an abstract type. There are some other cases which | |
27237 | are detailed in the AI. Note that this binding interpretation has not been | |
27238 | retrofitted to operate before Ada 2012 mode, since it caused a significant | |
27239 | number of regressions. | |
64d5610f | 27240 | |
b71d4b62 RA |
27241 | RM References: 3.09.03 (8) 3.09.03 (10) 6.05 (8/2) |
27242 | @end itemize | |
64d5610f | 27243 | |
b71d4b62 | 27244 | @geindex AI-0070 (Ada 2012 feature) |
64d5610f | 27245 | |
64d5610f | 27246 | |
b71d4b62 | 27247 | @itemize * |
64d5610f | 27248 | |
b71d4b62 | 27249 | @item |
1acce141 | 27250 | @emph{AI-0070 Elaboration of interface types (0000-00-00)} |
64d5610f | 27251 | |
b71d4b62 RA |
27252 | This is an editorial change only, there are no testable consequences short of |
27253 | checking for the absence of generated code for an interface declaration. | |
64d5610f | 27254 | |
b71d4b62 RA |
27255 | RM References: 3.09.04 (18/2) |
27256 | @end itemize | |
64d5610f | 27257 | |
b71d4b62 | 27258 | @geindex AI-0208 (Ada 2012 feature) |
64d5610f | 27259 | |
64d5610f | 27260 | |
b71d4b62 | 27261 | @itemize * |
64d5610f | 27262 | |
b71d4b62 | 27263 | @item |
1acce141 | 27264 | @emph{AI-0208 Characteristics of incomplete views (0000-00-00)} |
64d5610f | 27265 | |
b71d4b62 RA |
27266 | The wording in the Ada 2005 RM concerning characteristics of incomplete views |
27267 | was incorrect and implied that some programs intended to be legal were now | |
27268 | illegal. GNAT had never considered such programs illegal, so it has always | |
27269 | implemented the intent of this AI. | |
64d5610f | 27270 | |
b71d4b62 RA |
27271 | RM References: 3.10.01 (2.4/2) 3.10.01 (2.6/2) |
27272 | @end itemize | |
64d5610f | 27273 | |
b71d4b62 | 27274 | @geindex AI-0162 (Ada 2012 feature) |
64d5610f | 27275 | |
64d5610f | 27276 | |
b71d4b62 | 27277 | @itemize * |
64d5610f | 27278 | |
b71d4b62 | 27279 | @item |
1acce141 | 27280 | @emph{AI-0162 Incomplete type completed by partial view (2010-09-15)} |
64d5610f | 27281 | |
b71d4b62 RA |
27282 | Incomplete types are made more useful by allowing them to be completed by |
27283 | private types and private extensions. | |
64d5610f | 27284 | |
b71d4b62 RA |
27285 | RM References: 3.10.01 (2.5/2) 3.10.01 (2.6/2) 3.10.01 (3) 3.10.01 (4/2) |
27286 | @end itemize | |
64d5610f | 27287 | |
b71d4b62 | 27288 | @geindex AI-0098 (Ada 2012 feature) |
64d5610f | 27289 | |
64d5610f | 27290 | |
b71d4b62 | 27291 | @itemize * |
64d5610f | 27292 | |
b71d4b62 | 27293 | @item |
1acce141 | 27294 | @emph{AI-0098 Anonymous subprogram access restrictions (0000-00-00)} |
64d5610f | 27295 | |
b71d4b62 RA |
27296 | An unintentional omission in the RM implied some inconsistent restrictions on |
27297 | the use of anonymous access to subprogram values. These restrictions were not | |
27298 | intentional, and have never been enforced by GNAT. | |
64d5610f | 27299 | |
b71d4b62 RA |
27300 | RM References: 3.10.01 (6) 3.10.01 (9.2/2) |
27301 | @end itemize | |
64d5610f | 27302 | |
b71d4b62 | 27303 | @geindex AI-0199 (Ada 2012 feature) |
64d5610f | 27304 | |
64d5610f | 27305 | |
b71d4b62 | 27306 | @itemize * |
64d5610f | 27307 | |
b71d4b62 | 27308 | @item |
1acce141 | 27309 | @emph{AI-0199 Aggregate with anonymous access components (2010-07-14)} |
64d5610f | 27310 | |
b71d4b62 RA |
27311 | A choice list in a record aggregate can include several components of |
27312 | (distinct) anonymous access types as long as they have matching designated | |
27313 | subtypes. | |
64d5610f | 27314 | |
b71d4b62 RA |
27315 | RM References: 4.03.01 (16) |
27316 | @end itemize | |
64d5610f | 27317 | |
b71d4b62 | 27318 | @geindex AI-0220 (Ada 2012 feature) |
64d5610f | 27319 | |
64d5610f | 27320 | |
b71d4b62 | 27321 | @itemize * |
64d5610f | 27322 | |
b71d4b62 | 27323 | @item |
1acce141 | 27324 | @emph{AI-0220 Needed components for aggregates (0000-00-00)} |
64d5610f | 27325 | |
b71d4b62 RA |
27326 | This AI addresses a wording problem in the RM that appears to permit some |
27327 | complex cases of aggregates with nonstatic discriminants. GNAT has always | |
27328 | implemented the intended semantics. | |
64d5610f | 27329 | |
b71d4b62 RA |
27330 | RM References: 4.03.01 (17) |
27331 | @end itemize | |
64d5610f | 27332 | |
b71d4b62 | 27333 | @geindex AI-0147 (Ada 2012 feature) |
64d5610f | 27334 | |
64d5610f | 27335 | |
b71d4b62 | 27336 | @itemize * |
64d5610f | 27337 | |
b71d4b62 | 27338 | @item |
1acce141 | 27339 | @emph{AI-0147 Conditional expressions (2009-03-29)} |
64d5610f | 27340 | |
b71d4b62 | 27341 | Conditional expressions are permitted. The form of such an expression is: |
64d5610f | 27342 | |
b71d4b62 RA |
27343 | @example |
27344 | (if expr then expr @{elsif expr then expr@} [else expr]) | |
27345 | @end example | |
64d5610f | 27346 | |
b71d4b62 | 27347 | The parentheses can be omitted in contexts where parentheses are present |
1acce141 YM |
27348 | anyway, such as subprogram arguments and pragma arguments. If the @strong{else} |
27349 | clause is omitted, @strong{else} @emph{True} is assumed; | |
b71d4b62 | 27350 | thus @code{(if A then B)} is a way to conveniently represent |
1acce141 | 27351 | @emph{(A implies B)} in standard logic. |
64d5610f | 27352 | |
b71d4b62 RA |
27353 | RM References: 4.03.03 (15) 4.04 (1) 4.04 (7) 4.05.07 (0) 4.07 (2) |
27354 | 4.07 (3) 4.09 (12) 4.09 (33) 5.03 (3) 5.03 (4) 7.05 (2.1/2) | |
27355 | @end itemize | |
64d5610f | 27356 | |
b71d4b62 | 27357 | @geindex AI-0037 (Ada 2012 feature) |
64d5610f | 27358 | |
64d5610f | 27359 | |
b71d4b62 | 27360 | @itemize * |
64d5610f | 27361 | |
b71d4b62 | 27362 | @item |
1acce141 | 27363 | @emph{AI-0037 Out-of-range box associations in aggregate (0000-00-00)} |
64d5610f | 27364 | |
b71d4b62 RA |
27365 | This AI confirms that an association of the form @code{Indx => <>} in an |
27366 | array aggregate must raise @code{Constraint_Error} if @code{Indx} | |
27367 | is out of range. The RM specified a range check on other associations, but | |
27368 | not when the value of the association was defaulted. GNAT has always inserted | |
27369 | a constraint check on the index value. | |
64d5610f | 27370 | |
b71d4b62 RA |
27371 | RM References: 4.03.03 (29) |
27372 | @end itemize | |
64d5610f | 27373 | |
b71d4b62 | 27374 | @geindex AI-0123 (Ada 2012 feature) |
64d5610f | 27375 | |
64d5610f | 27376 | |
b71d4b62 | 27377 | @itemize * |
64d5610f | 27378 | |
b71d4b62 | 27379 | @item |
1acce141 | 27380 | @emph{AI-0123 Composability of equality (2010-04-13)} |
64d5610f | 27381 | |
b71d4b62 RA |
27382 | Equality of untagged record composes, so that the predefined equality for a |
27383 | composite type that includes a component of some untagged record type | |
27384 | @code{R} uses the equality operation of @code{R} (which may be user-defined | |
27385 | or predefined). This makes the behavior of untagged records identical to that | |
27386 | of tagged types in this respect. | |
64d5610f | 27387 | |
b71d4b62 RA |
27388 | This change is an incompatibility with previous versions of Ada, but it |
27389 | corrects a non-uniformity that was often a source of confusion. Analysis of | |
27390 | a large number of industrial programs indicates that in those rare cases | |
27391 | where a composite type had an untagged record component with a user-defined | |
27392 | equality, either there was no use of the composite equality, or else the code | |
27393 | expected the same composability as for tagged types, and thus had a bug that | |
27394 | would be fixed by this change. | |
64d5610f | 27395 | |
b71d4b62 RA |
27396 | RM References: 4.05.02 (9.7/2) 4.05.02 (14) 4.05.02 (15) 4.05.02 (24) |
27397 | 8.05.04 (8) | |
27398 | @end itemize | |
64d5610f | 27399 | |
b71d4b62 | 27400 | @geindex AI-0088 (Ada 2012 feature) |
64d5610f | 27401 | |
64d5610f | 27402 | |
b71d4b62 | 27403 | @itemize * |
64d5610f | 27404 | |
b71d4b62 | 27405 | @item |
1acce141 | 27406 | @emph{AI-0088 The value of exponentiation (0000-00-00)} |
64d5610f | 27407 | |
b71d4b62 RA |
27408 | This AI clarifies the equivalence rule given for the dynamic semantics of |
27409 | exponentiation: the value of the operation can be obtained by repeated | |
27410 | multiplication, but the operation can be implemented otherwise (for example | |
27411 | using the familiar divide-by-two-and-square algorithm, even if this is less | |
27412 | accurate), and does not imply repeated reads of a volatile base. | |
64d5610f | 27413 | |
b71d4b62 RA |
27414 | RM References: 4.05.06 (11) |
27415 | @end itemize | |
64d5610f | 27416 | |
b71d4b62 | 27417 | @geindex AI-0188 (Ada 2012 feature) |
64d5610f | 27418 | |
64d5610f | 27419 | |
b71d4b62 | 27420 | @itemize * |
64d5610f | 27421 | |
b71d4b62 | 27422 | @item |
1acce141 | 27423 | @emph{AI-0188 Case expressions (2010-01-09)} |
64d5610f | 27424 | |
b71d4b62 | 27425 | Case expressions are permitted. This allows use of constructs such as: |
64d5610f | 27426 | |
b71d4b62 RA |
27427 | @example |
27428 | X := (case Y is when 1 => 2, when 2 => 3, when others => 31) | |
27429 | @end example | |
64d5610f | 27430 | |
b71d4b62 RA |
27431 | RM References: 4.05.07 (0) 4.05.08 (0) 4.09 (12) 4.09 (33) |
27432 | @end itemize | |
64d5610f | 27433 | |
b71d4b62 | 27434 | @geindex AI-0104 (Ada 2012 feature) |
64d5610f ML |
27435 | |
27436 | ||
27437 | @itemize * | |
27438 | ||
27439 | @item | |
1acce141 | 27440 | @emph{AI-0104 Null exclusion and uninitialized allocator (2010-07-15)} |
64d5610f | 27441 | |
b71d4b62 RA |
27442 | The assignment @code{Ptr := new not null Some_Ptr;} will raise |
27443 | @code{Constraint_Error} because the default value of the allocated object is | |
1acce141 | 27444 | @strong{null}. This useless construct is illegal in Ada 2012. |
64d5610f | 27445 | |
b71d4b62 | 27446 | RM References: 4.08 (2) |
64d5610f ML |
27447 | @end itemize |
27448 | ||
b71d4b62 | 27449 | @geindex AI-0157 (Ada 2012 feature) |
64d5610f ML |
27450 | |
27451 | ||
27452 | @itemize * | |
27453 | ||
27454 | @item | |
1acce141 | 27455 | @emph{AI-0157 Allocation/Deallocation from empty pool (2010-07-11)} |
64d5610f | 27456 | |
b71d4b62 RA |
27457 | Allocation and Deallocation from an empty storage pool (i.e. allocation or |
27458 | deallocation of a pointer for which a static storage size clause of zero | |
27459 | has been given) is now illegal and is detected as such. GNAT | |
27460 | previously gave a warning but not an error. | |
64d5610f | 27461 | |
b71d4b62 | 27462 | RM References: 4.08 (5.3/2) 13.11.02 (4) 13.11.02 (17) |
64d5610f ML |
27463 | @end itemize |
27464 | ||
b71d4b62 | 27465 | @geindex AI-0179 (Ada 2012 feature) |
64d5610f ML |
27466 | |
27467 | ||
27468 | @itemize * | |
27469 | ||
27470 | @item | |
1acce141 | 27471 | @emph{AI-0179 Statement not required after label (2010-04-10)} |
64d5610f | 27472 | |
b71d4b62 RA |
27473 | It is not necessary to have a statement following a label, so a label |
27474 | can appear at the end of a statement sequence without the need for putting a | |
27475 | null statement afterwards, but it is not allowable to have only labels and | |
27476 | no real statements in a statement sequence. | |
64d5610f | 27477 | |
b71d4b62 | 27478 | RM References: 5.01 (2) |
64d5610f ML |
27479 | @end itemize |
27480 | ||
b71d4b62 | 27481 | @geindex AI-0139-2 (Ada 2012 feature) |
64d5610f ML |
27482 | |
27483 | ||
27484 | @itemize * | |
27485 | ||
27486 | @item | |
1acce141 | 27487 | @emph{AI-0139-2 Syntactic sugar for iterators (2010-09-29)} |
64d5610f | 27488 | |
b71d4b62 RA |
27489 | The new syntax for iterating over arrays and containers is now implemented. |
27490 | Iteration over containers is for now limited to read-only iterators. Only | |
27491 | default iterators are supported, with the syntax: @code{for Elem of C}. | |
64d5610f | 27492 | |
b71d4b62 | 27493 | RM References: 5.05 |
64d5610f ML |
27494 | @end itemize |
27495 | ||
b71d4b62 | 27496 | @geindex AI-0134 (Ada 2012 feature) |
64d5610f ML |
27497 | |
27498 | ||
27499 | @itemize * | |
27500 | ||
27501 | @item | |
1acce141 | 27502 | @emph{AI-0134 Profiles must match for full conformance (0000-00-00)} |
64d5610f | 27503 | |
b71d4b62 RA |
27504 | For full conformance, the profiles of anonymous-access-to-subprogram |
27505 | parameters must match. GNAT has always enforced this rule. | |
64d5610f | 27506 | |
b71d4b62 | 27507 | RM References: 6.03.01 (18) |
64d5610f ML |
27508 | @end itemize |
27509 | ||
b71d4b62 | 27510 | @geindex AI-0207 (Ada 2012 feature) |
64d5610f ML |
27511 | |
27512 | ||
27513 | @itemize * | |
27514 | ||
27515 | @item | |
1acce141 | 27516 | @emph{AI-0207 Mode conformance and access constant (0000-00-00)} |
64d5610f | 27517 | |
b71d4b62 RA |
27518 | This AI confirms that access_to_constant indication must match for mode |
27519 | conformance. This was implemented in GNAT when the qualifier was originally | |
27520 | introduced in Ada 2005. | |
64d5610f | 27521 | |
b71d4b62 | 27522 | RM References: 6.03.01 (16/2) |
64d5610f ML |
27523 | @end itemize |
27524 | ||
b71d4b62 | 27525 | @geindex AI-0046 (Ada 2012 feature) |
64d5610f ML |
27526 | |
27527 | ||
27528 | @itemize * | |
27529 | ||
27530 | @item | |
1acce141 | 27531 | @emph{AI-0046 Null exclusion match for full conformance (2010-07-17)} |
64d5610f | 27532 | |
b71d4b62 RA |
27533 | For full conformance, in the case of access parameters, the null exclusion |
27534 | must match (either both or neither must have @code{not null}). | |
64d5610f | 27535 | |
b71d4b62 | 27536 | RM References: 6.03.02 (18) |
64d5610f ML |
27537 | @end itemize |
27538 | ||
b71d4b62 | 27539 | @geindex AI-0118 (Ada 2012 feature) |
64d5610f ML |
27540 | |
27541 | ||
27542 | @itemize * | |
27543 | ||
27544 | @item | |
1acce141 | 27545 | @emph{AI-0118 The association of parameter associations (0000-00-00)} |
64d5610f | 27546 | |
b71d4b62 RA |
27547 | This AI clarifies the rules for named associations in subprogram calls and |
27548 | generic instantiations. The rules have been in place since Ada 83. | |
64d5610f | 27549 | |
b71d4b62 | 27550 | RM References: 6.04.01 (2) 12.03 (9) |
64d5610f ML |
27551 | @end itemize |
27552 | ||
b71d4b62 | 27553 | @geindex AI-0196 (Ada 2012 feature) |
64d5610f ML |
27554 | |
27555 | ||
27556 | @itemize * | |
27557 | ||
27558 | @item | |
1acce141 | 27559 | @emph{AI-0196 Null exclusion tests for out parameters (0000-00-00)} |
64d5610f | 27560 | |
b71d4b62 RA |
27561 | Null exclusion checks are not made for @code{out} parameters when |
27562 | evaluating the actual parameters. GNAT has never generated these checks. | |
64d5610f | 27563 | |
b71d4b62 | 27564 | RM References: 6.04.01 (13) |
64d5610f ML |
27565 | @end itemize |
27566 | ||
b71d4b62 | 27567 | @geindex AI-0015 (Ada 2012 feature) |
64d5610f ML |
27568 | |
27569 | ||
27570 | @itemize * | |
27571 | ||
27572 | @item | |
1acce141 | 27573 | @emph{AI-0015 Constant return objects (0000-00-00)} |
64d5610f | 27574 | |
1acce141 | 27575 | The return object declared in an @emph{extended_return_statement} may be |
b71d4b62 | 27576 | declared constant. This was always intended, and GNAT has always allowed it. |
64d5610f | 27577 | |
b71d4b62 RA |
27578 | RM References: 6.05 (2.1/2) 3.03 (10/2) 3.03 (21) 6.05 (5/2) |
27579 | 6.05 (5.7/2) | |
64d5610f ML |
27580 | @end itemize |
27581 | ||
b71d4b62 | 27582 | @geindex AI-0032 (Ada 2012 feature) |
64d5610f ML |
27583 | |
27584 | ||
27585 | @itemize * | |
27586 | ||
27587 | @item | |
1acce141 | 27588 | @emph{AI-0032 Extended return for class-wide functions (0000-00-00)} |
64d5610f | 27589 | |
b71d4b62 RA |
27590 | If a function returns a class-wide type, the object of an extended return |
27591 | statement can be declared with a specific type that is covered by the class- | |
27592 | wide type. This has been implemented in GNAT since the introduction of | |
27593 | extended returns. Note AI-0103 complements this AI by imposing matching | |
27594 | rules for constrained return types. | |
64d5610f | 27595 | |
b71d4b62 RA |
27596 | RM References: 6.05 (5.2/2) 6.05 (5.3/2) 6.05 (5.6/2) 6.05 (5.8/2) |
27597 | 6.05 (8/2) | |
64d5610f ML |
27598 | @end itemize |
27599 | ||
b71d4b62 | 27600 | @geindex AI-0103 (Ada 2012 feature) |
64d5610f ML |
27601 | |
27602 | ||
27603 | @itemize * | |
27604 | ||
27605 | @item | |
1acce141 | 27606 | @emph{AI-0103 Static matching for extended return (2010-07-23)} |
64d5610f | 27607 | |
b71d4b62 RA |
27608 | If the return subtype of a function is an elementary type or a constrained |
27609 | type, the subtype indication in an extended return statement must match | |
27610 | statically this return subtype. | |
64d5610f | 27611 | |
b71d4b62 | 27612 | RM References: 6.05 (5.2/2) |
64d5610f ML |
27613 | @end itemize |
27614 | ||
b71d4b62 | 27615 | @geindex AI-0058 (Ada 2012 feature) |
64d5610f ML |
27616 | |
27617 | ||
27618 | @itemize * | |
27619 | ||
27620 | @item | |
1acce141 | 27621 | @emph{AI-0058 Abnormal completion of an extended return (0000-00-00)} |
64d5610f | 27622 | |
b71d4b62 RA |
27623 | The RM had some incorrect wording implying wrong treatment of abnormal |
27624 | completion in an extended return. GNAT has always implemented the intended | |
27625 | correct semantics as described by this AI. | |
64d5610f | 27626 | |
b71d4b62 | 27627 | RM References: 6.05 (22/2) |
64d5610f ML |
27628 | @end itemize |
27629 | ||
b71d4b62 | 27630 | @geindex AI-0050 (Ada 2012 feature) |
64d5610f ML |
27631 | |
27632 | ||
27633 | @itemize * | |
27634 | ||
27635 | @item | |
1acce141 | 27636 | @emph{AI-0050 Raising Constraint_Error early for function call (0000-00-00)} |
64d5610f | 27637 | |
b71d4b62 RA |
27638 | The implementation permissions for raising @code{Constraint_Error} early on a function call |
27639 | when it was clear an exception would be raised were over-permissive and allowed | |
27640 | mishandling of discriminants in some cases. GNAT did | |
27641 | not take advantage of these incorrect permissions in any case. | |
64d5610f | 27642 | |
b71d4b62 | 27643 | RM References: 6.05 (24/2) |
64d5610f ML |
27644 | @end itemize |
27645 | ||
b71d4b62 | 27646 | @geindex AI-0125 (Ada 2012 feature) |
64d5610f ML |
27647 | |
27648 | ||
27649 | @itemize * | |
27650 | ||
27651 | @item | |
1acce141 | 27652 | @emph{AI-0125 Nonoverridable operations of an ancestor (2010-09-28)} |
64d5610f | 27653 | |
b71d4b62 RA |
27654 | In Ada 2012, the declaration of a primitive operation of a type extension |
27655 | or private extension can also override an inherited primitive that is not | |
27656 | visible at the point of this declaration. | |
64d5610f | 27657 | |
b71d4b62 | 27658 | RM References: 7.03.01 (6) 8.03 (23) 8.03.01 (5/2) 8.03.01 (6/2) |
64d5610f ML |
27659 | @end itemize |
27660 | ||
b71d4b62 | 27661 | @geindex AI-0062 (Ada 2012 feature) |
64d5610f ML |
27662 | |
27663 | ||
27664 | @itemize * | |
27665 | ||
27666 | @item | |
1acce141 | 27667 | @emph{AI-0062 Null exclusions and deferred constants (0000-00-00)} |
64d5610f | 27668 | |
b71d4b62 RA |
27669 | A full constant may have a null exclusion even if its associated deferred |
27670 | constant does not. GNAT has always allowed this. | |
64d5610f | 27671 | |
b71d4b62 | 27672 | RM References: 7.04 (6/2) 7.04 (7.1/2) |
64d5610f ML |
27673 | @end itemize |
27674 | ||
b71d4b62 | 27675 | @geindex AI-0178 (Ada 2012 feature) |
64d5610f ML |
27676 | |
27677 | ||
27678 | @itemize * | |
27679 | ||
27680 | @item | |
1acce141 | 27681 | @emph{AI-0178 Incomplete views are limited (0000-00-00)} |
64d5610f | 27682 | |
b71d4b62 RA |
27683 | This AI clarifies the role of incomplete views and plugs an omission in the |
27684 | RM. GNAT always correctly restricted the use of incomplete views and types. | |
64d5610f | 27685 | |
b71d4b62 | 27686 | RM References: 7.05 (3/2) 7.05 (6/2) |
64d5610f ML |
27687 | @end itemize |
27688 | ||
b71d4b62 | 27689 | @geindex AI-0087 (Ada 2012 feature) |
64d5610f ML |
27690 | |
27691 | ||
27692 | @itemize * | |
27693 | ||
27694 | @item | |
1acce141 | 27695 | @emph{AI-0087 Actual for formal nonlimited derived type (2010-07-15)} |
64d5610f | 27696 | |
b71d4b62 RA |
27697 | The actual for a formal nonlimited derived type cannot be limited. In |
27698 | particular, a formal derived type that extends a limited interface but which | |
27699 | is not explicitly limited cannot be instantiated with a limited type. | |
64d5610f | 27700 | |
b71d4b62 | 27701 | RM References: 7.05 (5/2) 12.05.01 (5.1/2) |
64d5610f ML |
27702 | @end itemize |
27703 | ||
b71d4b62 | 27704 | @geindex AI-0099 (Ada 2012 feature) |
64d5610f ML |
27705 | |
27706 | ||
27707 | @itemize * | |
27708 | ||
27709 | @item | |
1acce141 | 27710 | @emph{AI-0099 Tag determines whether finalization needed (0000-00-00)} |
64d5610f | 27711 | |
b71d4b62 RA |
27712 | This AI clarifies that ‘needs finalization’ is part of dynamic semantics, |
27713 | and therefore depends on the run-time characteristics of an object (i.e. its | |
27714 | tag) and not on its nominal type. As the AI indicates: “we do not expect | |
27715 | this to affect any implementation’’. | |
64d5610f | 27716 | |
b71d4b62 | 27717 | RM References: 7.06.01 (6) 7.06.01 (7) 7.06.01 (8) 7.06.01 (9/2) |
64d5610f ML |
27718 | @end itemize |
27719 | ||
b71d4b62 | 27720 | @geindex AI-0064 (Ada 2012 feature) |
64d5610f ML |
27721 | |
27722 | ||
27723 | @itemize * | |
27724 | ||
27725 | @item | |
1acce141 | 27726 | @emph{AI-0064 Redundant finalization rule (0000-00-00)} |
64d5610f | 27727 | |
b71d4b62 RA |
27728 | This is an editorial change only. The intended behavior is already checked |
27729 | by an existing ACATS test, which GNAT has always executed correctly. | |
64d5610f | 27730 | |
b71d4b62 | 27731 | RM References: 7.06.01 (17.1/1) |
64d5610f ML |
27732 | @end itemize |
27733 | ||
b71d4b62 | 27734 | @geindex AI-0026 (Ada 2012 feature) |
64d5610f ML |
27735 | |
27736 | ||
27737 | @itemize * | |
27738 | ||
27739 | @item | |
1acce141 | 27740 | @emph{AI-0026 Missing rules for Unchecked_Union (2010-07-07)} |
64d5610f | 27741 | |
b71d4b62 RA |
27742 | Record representation clauses concerning Unchecked_Union types cannot mention |
27743 | the discriminant of the type. The type of a component declared in the variant | |
27744 | part of an Unchecked_Union cannot be controlled, have controlled components, | |
27745 | nor have protected or task parts. If an Unchecked_Union type is declared | |
27746 | within the body of a generic unit or its descendants, then the type of a | |
27747 | component declared in the variant part cannot be a formal private type or a | |
27748 | formal private extension declared within the same generic unit. | |
64d5610f | 27749 | |
b71d4b62 | 27750 | RM References: 7.06 (9.4/2) B.03.03 (9/2) B.03.03 (10/2) |
64d5610f ML |
27751 | @end itemize |
27752 | ||
b71d4b62 | 27753 | @geindex AI-0205 (Ada 2012 feature) |
64d5610f ML |
27754 | |
27755 | ||
27756 | @itemize * | |
27757 | ||
27758 | @item | |
1acce141 | 27759 | @emph{AI-0205 Extended return declares visible name (0000-00-00)} |
64d5610f | 27760 | |
b71d4b62 RA |
27761 | This AI corrects a simple omission in the RM. Return objects have always |
27762 | been visible within an extended return statement. | |
64d5610f | 27763 | |
b71d4b62 | 27764 | RM References: 8.03 (17) |
64d5610f ML |
27765 | @end itemize |
27766 | ||
b71d4b62 | 27767 | @geindex AI-0042 (Ada 2012 feature) |
64d5610f ML |
27768 | |
27769 | ||
27770 | @itemize * | |
27771 | ||
27772 | @item | |
1acce141 | 27773 | @emph{AI-0042 Overriding versus implemented-by (0000-00-00)} |
64d5610f | 27774 | |
b71d4b62 RA |
27775 | This AI fixes a wording gap in the RM. An operation of a synchronized |
27776 | interface can be implemented by a protected or task entry, but the abstract | |
27777 | operation is not being overridden in the usual sense, and it must be stated | |
27778 | separately that this implementation is legal. This has always been the case | |
27779 | in GNAT. | |
64d5610f | 27780 | |
b71d4b62 | 27781 | RM References: 9.01 (9.2/2) 9.04 (11.1/2) |
64d5610f ML |
27782 | @end itemize |
27783 | ||
b71d4b62 | 27784 | @geindex AI-0030 (Ada 2012 feature) |
64d5610f ML |
27785 | |
27786 | ||
27787 | @itemize * | |
27788 | ||
27789 | @item | |
1acce141 | 27790 | @emph{AI-0030 Requeue on synchronized interfaces (2010-07-19)} |
64d5610f | 27791 | |
b71d4b62 RA |
27792 | Requeue is permitted to a protected, synchronized or task interface primitive |
27793 | providing it is known that the overriding operation is an entry. Otherwise | |
27794 | the requeue statement has the same effect as a procedure call. Use of pragma | |
27795 | @code{Implemented} provides a way to impose a static requirement on the | |
27796 | overriding operation by adhering to one of the implementation kinds: entry, | |
27797 | protected procedure or any of the above. | |
64d5610f | 27798 | |
b71d4b62 RA |
27799 | RM References: 9.05 (9) 9.05.04 (2) 9.05.04 (3) 9.05.04 (5) |
27800 | 9.05.04 (6) 9.05.04 (7) 9.05.04 (12) | |
64d5610f ML |
27801 | @end itemize |
27802 | ||
b71d4b62 | 27803 | @geindex AI-0201 (Ada 2012 feature) |
64d5610f ML |
27804 | |
27805 | ||
27806 | @itemize * | |
27807 | ||
27808 | @item | |
1acce141 | 27809 | @emph{AI-0201 Independence of atomic object components (2010-07-22)} |
64d5610f | 27810 | |
b71d4b62 RA |
27811 | If an Atomic object has a pragma @code{Pack} or a @code{Component_Size} |
27812 | attribute, then individual components may not be addressable by independent | |
27813 | tasks. However, if the representation clause has no effect (is confirming), | |
27814 | then independence is not compromised. Furthermore, in GNAT, specification of | |
27815 | other appropriately addressable component sizes (e.g. 16 for 8-bit | |
27816 | characters) also preserves independence. GNAT now gives very clear warnings | |
27817 | both for the declaration of such a type, and for any assignment to its components. | |
64d5610f | 27818 | |
b71d4b62 | 27819 | RM References: 9.10 (1/3) C.06 (22/2) C.06 (23/2) |
64d5610f ML |
27820 | @end itemize |
27821 | ||
b71d4b62 | 27822 | @geindex AI-0009 (Ada 2012 feature) |
64d5610f ML |
27823 | |
27824 | ||
27825 | @itemize * | |
27826 | ||
27827 | @item | |
1acce141 | 27828 | @emph{AI-0009 Pragma Independent[_Components] (2010-07-23)} |
64d5610f | 27829 | |
b71d4b62 RA |
27830 | This AI introduces the new pragmas @code{Independent} and |
27831 | @code{Independent_Components}, | |
27832 | which control guaranteeing independence of access to objects and components. | |
27833 | The AI also requires independence not unaffected by confirming rep clauses. | |
64d5610f | 27834 | |
b71d4b62 RA |
27835 | RM References: 9.10 (1) 13.01 (15/1) 13.02 (9) 13.03 (13) C.06 (2) |
27836 | C.06 (4) C.06 (6) C.06 (9) C.06 (13) C.06 (14) | |
64d5610f ML |
27837 | @end itemize |
27838 | ||
b71d4b62 | 27839 | @geindex AI-0072 (Ada 2012 feature) |
64d5610f ML |
27840 | |
27841 | ||
27842 | @itemize * | |
27843 | ||
27844 | @item | |
1acce141 | 27845 | @emph{AI-0072 Task signalling using ‘Terminated (0000-00-00)} |
64d5610f | 27846 | |
b71d4b62 RA |
27847 | This AI clarifies that task signalling for reading @code{'Terminated} only |
27848 | occurs if the result is True. GNAT semantics has always been consistent with | |
27849 | this notion of task signalling. | |
64d5610f | 27850 | |
b71d4b62 | 27851 | RM References: 9.10 (6.1/1) |
64d5610f ML |
27852 | @end itemize |
27853 | ||
b71d4b62 | 27854 | @geindex AI-0108 (Ada 2012 feature) |
64d5610f ML |
27855 | |
27856 | ||
27857 | @itemize * | |
27858 | ||
27859 | @item | |
1acce141 | 27860 | @emph{AI-0108 Limited incomplete view and discriminants (0000-00-00)} |
64d5610f | 27861 | |
b71d4b62 RA |
27862 | This AI confirms that an incomplete type from a limited view does not have |
27863 | discriminants. This has always been the case in GNAT. | |
64d5610f | 27864 | |
b71d4b62 | 27865 | RM References: 10.01.01 (12.3/2) |
64d5610f ML |
27866 | @end itemize |
27867 | ||
b71d4b62 | 27868 | @geindex AI-0129 (Ada 2012 feature) |
64d5610f ML |
27869 | |
27870 | ||
27871 | @itemize * | |
27872 | ||
27873 | @item | |
1acce141 | 27874 | @emph{AI-0129 Limited views and incomplete types (0000-00-00)} |
64d5610f | 27875 | |
b71d4b62 RA |
27876 | This AI clarifies the description of limited views: a limited view of a |
27877 | package includes only one view of a type that has an incomplete declaration | |
27878 | and a full declaration (there is no possible ambiguity in a client package). | |
27879 | This AI also fixes an omission: a nested package in the private part has no | |
27880 | limited view. GNAT always implemented this correctly. | |
64d5610f | 27881 | |
b71d4b62 | 27882 | RM References: 10.01.01 (12.2/2) 10.01.01 (12.3/2) |
64d5610f ML |
27883 | @end itemize |
27884 | ||
b71d4b62 | 27885 | @geindex AI-0077 (Ada 2012 feature) |
64d5610f ML |
27886 | |
27887 | ||
27888 | @itemize * | |
27889 | ||
27890 | @item | |
1acce141 | 27891 | @emph{AI-0077 Limited withs and scope of declarations (0000-00-00)} |
64d5610f | 27892 | |
b71d4b62 RA |
27893 | This AI clarifies that a declaration does not include a context clause, |
27894 | and confirms that it is illegal to have a context in which both a limited | |
27895 | and a nonlimited view of a package are accessible. Such double visibility | |
27896 | was always rejected by GNAT. | |
64d5610f | 27897 | |
b71d4b62 | 27898 | RM References: 10.01.02 (12/2) 10.01.02 (21/2) 10.01.02 (22/2) |
64d5610f ML |
27899 | @end itemize |
27900 | ||
b71d4b62 | 27901 | @geindex AI-0122 (Ada 2012 feature) |
64d5610f ML |
27902 | |
27903 | ||
27904 | @itemize * | |
27905 | ||
27906 | @item | |
1acce141 | 27907 | @emph{AI-0122 Private with and children of generics (0000-00-00)} |
64d5610f | 27908 | |
b71d4b62 RA |
27909 | This AI clarifies the visibility of private children of generic units within |
27910 | instantiations of a parent. GNAT has always handled this correctly. | |
64d5610f | 27911 | |
b71d4b62 | 27912 | RM References: 10.01.02 (12/2) |
64d5610f ML |
27913 | @end itemize |
27914 | ||
b71d4b62 | 27915 | @geindex AI-0040 (Ada 2012 feature) |
64d5610f ML |
27916 | |
27917 | ||
27918 | @itemize * | |
27919 | ||
27920 | @item | |
1acce141 | 27921 | @emph{AI-0040 Limited with clauses on descendant (0000-00-00)} |
64d5610f | 27922 | |
b71d4b62 RA |
27923 | This AI confirms that a limited with clause in a child unit cannot name |
27924 | an ancestor of the unit. This has always been checked in GNAT. | |
64d5610f | 27925 | |
b71d4b62 | 27926 | RM References: 10.01.02 (20/2) |
64d5610f ML |
27927 | @end itemize |
27928 | ||
b71d4b62 | 27929 | @geindex AI-0132 (Ada 2012 feature) |
64d5610f ML |
27930 | |
27931 | ||
27932 | @itemize * | |
27933 | ||
27934 | @item | |
1acce141 | 27935 | @emph{AI-0132 Placement of library unit pragmas (0000-00-00)} |
64d5610f | 27936 | |
b71d4b62 RA |
27937 | This AI fills a gap in the description of library unit pragmas. The pragma |
27938 | clearly must apply to a library unit, even if it does not carry the name | |
27939 | of the enclosing unit. GNAT has always enforced the required check. | |
64d5610f | 27940 | |
b71d4b62 | 27941 | RM References: 10.01.05 (7) |
64d5610f ML |
27942 | @end itemize |
27943 | ||
b71d4b62 | 27944 | @geindex AI-0034 (Ada 2012 feature) |
64d5610f ML |
27945 | |
27946 | ||
27947 | @itemize * | |
27948 | ||
27949 | @item | |
1acce141 | 27950 | @emph{AI-0034 Categorization of limited views (0000-00-00)} |
64d5610f | 27951 | |
b71d4b62 RA |
27952 | The RM makes certain limited with clauses illegal because of categorization |
27953 | considerations, when the corresponding normal with would be legal. This is | |
27954 | not intended, and GNAT has always implemented the recommended behavior. | |
64d5610f | 27955 | |
b71d4b62 | 27956 | RM References: 10.02.01 (11/1) 10.02.01 (17/2) |
64d5610f ML |
27957 | @end itemize |
27958 | ||
b71d4b62 | 27959 | @geindex AI-0035 (Ada 2012 feature) |
64d5610f ML |
27960 | |
27961 | ||
27962 | @itemize * | |
27963 | ||
27964 | @item | |
1acce141 | 27965 | @emph{AI-0035 Inconsistencies with Pure units (0000-00-00)} |
64d5610f | 27966 | |
b71d4b62 RA |
27967 | This AI remedies some inconsistencies in the legality rules for Pure units. |
27968 | Derived access types are legal in a pure unit (on the assumption that the | |
27969 | rule for a zero storage pool size has been enforced on the ancestor type). | |
27970 | The rules are enforced in generic instances and in subunits. GNAT has always | |
27971 | implemented the recommended behavior. | |
64d5610f | 27972 | |
b71d4b62 | 27973 | RM References: 10.02.01 (15.1/2) 10.02.01 (15.4/2) 10.02.01 (15.5/2) 10.02.01 (17/2) |
64d5610f ML |
27974 | @end itemize |
27975 | ||
b71d4b62 | 27976 | @geindex AI-0219 (Ada 2012 feature) |
64d5610f ML |
27977 | |
27978 | ||
27979 | @itemize * | |
27980 | ||
27981 | @item | |
1acce141 | 27982 | @emph{AI-0219 Pure permissions and limited parameters (2010-05-25)} |
64d5610f | 27983 | |
b71d4b62 RA |
27984 | This AI refines the rules for the cases with limited parameters which do not |
27985 | allow the implementations to omit ‘redundant’. GNAT now properly conforms | |
27986 | to the requirements of this binding interpretation. | |
64d5610f | 27987 | |
b71d4b62 | 27988 | RM References: 10.02.01 (18/2) |
64d5610f ML |
27989 | @end itemize |
27990 | ||
b71d4b62 | 27991 | @geindex AI-0043 (Ada 2012 feature) |
64d5610f ML |
27992 | |
27993 | ||
27994 | @itemize * | |
27995 | ||
27996 | @item | |
1acce141 | 27997 | @emph{AI-0043 Rules about raising exceptions (0000-00-00)} |
64d5610f | 27998 | |
b71d4b62 RA |
27999 | This AI covers various omissions in the RM regarding the raising of |
28000 | exceptions. GNAT has always implemented the intended semantics. | |
64d5610f | 28001 | |
b71d4b62 | 28002 | RM References: 11.04.01 (10.1/2) 11 (2) |
64d5610f ML |
28003 | @end itemize |
28004 | ||
b71d4b62 | 28005 | @geindex AI-0200 (Ada 2012 feature) |
64d5610f ML |
28006 | |
28007 | ||
28008 | @itemize * | |
28009 | ||
28010 | @item | |
1acce141 | 28011 | @emph{AI-0200 Mismatches in formal package declarations (0000-00-00)} |
64d5610f | 28012 | |
b71d4b62 RA |
28013 | This AI plugs a gap in the RM which appeared to allow some obviously intended |
28014 | illegal instantiations. GNAT has never allowed these instantiations. | |
64d5610f | 28015 | |
b71d4b62 | 28016 | RM References: 12.07 (16) |
64d5610f ML |
28017 | @end itemize |
28018 | ||
b71d4b62 | 28019 | @geindex AI-0112 (Ada 2012 feature) |
64d5610f ML |
28020 | |
28021 | ||
28022 | @itemize * | |
28023 | ||
28024 | @item | |
1acce141 | 28025 | @emph{AI-0112 Detection of duplicate pragmas (2010-07-24)} |
64d5610f | 28026 | |
b71d4b62 RA |
28027 | This AI concerns giving names to various representation aspects, but the |
28028 | practical effect is simply to make the use of duplicate | |
28029 | @code{Atomic[_Components]}, | |
28030 | @code{Volatile[_Components]}, and | |
28031 | @code{Independent[_Components]} pragmas illegal, and GNAT | |
28032 | now performs this required check. | |
64d5610f | 28033 | |
b71d4b62 | 28034 | RM References: 13.01 (8) |
64d5610f ML |
28035 | @end itemize |
28036 | ||
b71d4b62 | 28037 | @geindex AI-0106 (Ada 2012 feature) |
64d5610f ML |
28038 | |
28039 | ||
28040 | @itemize * | |
28041 | ||
28042 | @item | |
1acce141 | 28043 | @emph{AI-0106 No representation pragmas on generic formals (0000-00-00)} |
64d5610f | 28044 | |
b71d4b62 RA |
28045 | The RM appeared to allow representation pragmas on generic formal parameters, |
28046 | but this was not intended, and GNAT has never permitted this usage. | |
64d5610f | 28047 | |
b71d4b62 | 28048 | RM References: 13.01 (9.1/1) |
64d5610f ML |
28049 | @end itemize |
28050 | ||
b71d4b62 | 28051 | @geindex AI-0012 (Ada 2012 feature) |
64d5610f ML |
28052 | |
28053 | ||
28054 | @itemize * | |
28055 | ||
28056 | @item | |
1acce141 | 28057 | @emph{AI-0012 Pack/Component_Size for aliased/atomic (2010-07-15)} |
64d5610f | 28058 | |
b71d4b62 RA |
28059 | It is now illegal to give an inappropriate component size or a pragma |
28060 | @code{Pack} that attempts to change the component size in the case of atomic | |
28061 | or aliased components. Previously GNAT ignored such an attempt with a | |
28062 | warning. | |
64d5610f | 28063 | |
b71d4b62 | 28064 | RM References: 13.02 (6.1/2) 13.02 (7) C.06 (10) C.06 (11) C.06 (21) |
64d5610f ML |
28065 | @end itemize |
28066 | ||
b71d4b62 | 28067 | @geindex AI-0039 (Ada 2012 feature) |
64d5610f ML |
28068 | |
28069 | ||
28070 | @itemize * | |
28071 | ||
28072 | @item | |
1acce141 | 28073 | @emph{AI-0039 Stream attributes cannot be dynamic (0000-00-00)} |
64d5610f | 28074 | |
b71d4b62 RA |
28075 | The RM permitted the use of dynamic expressions (such as @code{ptr.all})` |
28076 | for stream attributes, but these were never useful and are now illegal. GNAT | |
28077 | has always regarded such expressions as illegal. | |
64d5610f | 28078 | |
b71d4b62 | 28079 | RM References: 13.03 (4) 13.03 (6) 13.13.02 (38/2) |
64d5610f ML |
28080 | @end itemize |
28081 | ||
b71d4b62 | 28082 | @geindex AI-0095 (Ada 2012 feature) |
64d5610f ML |
28083 | |
28084 | ||
28085 | @itemize * | |
28086 | ||
28087 | @item | |
1acce141 | 28088 | @emph{AI-0095 Address of intrinsic subprograms (0000-00-00)} |
64d5610f | 28089 | |
b71d4b62 RA |
28090 | The prefix of @code{'Address} cannot statically denote a subprogram with |
28091 | convention @code{Intrinsic}. The use of the @code{Address} attribute raises | |
28092 | @code{Program_Error} if the prefix denotes a subprogram with convention | |
28093 | @code{Intrinsic}. | |
64d5610f | 28094 | |
b71d4b62 | 28095 | RM References: 13.03 (11/1) |
64d5610f ML |
28096 | @end itemize |
28097 | ||
b71d4b62 | 28098 | @geindex AI-0116 (Ada 2012 feature) |
64d5610f ML |
28099 | |
28100 | ||
28101 | @itemize * | |
28102 | ||
28103 | @item | |
1acce141 | 28104 | @emph{AI-0116 Alignment of class-wide objects (0000-00-00)} |
64d5610f | 28105 | |
b71d4b62 RA |
28106 | This AI requires that the alignment of a class-wide object be no greater |
28107 | than the alignment of any type in the class. GNAT has always followed this | |
28108 | recommendation. | |
64d5610f | 28109 | |
b71d4b62 | 28110 | RM References: 13.03 (29) 13.11 (16) |
64d5610f ML |
28111 | @end itemize |
28112 | ||
b71d4b62 | 28113 | @geindex AI-0146 (Ada 2012 feature) |
64d5610f ML |
28114 | |
28115 | ||
28116 | @itemize * | |
28117 | ||
28118 | @item | |
1acce141 | 28119 | @emph{AI-0146 Type invariants (2009-09-21)} |
64d5610f | 28120 | |
b71d4b62 RA |
28121 | Type invariants may be specified for private types using the aspect notation. |
28122 | Aspect @code{Type_Invariant} may be specified for any private type, | |
28123 | @code{Type_Invariant'Class} can | |
28124 | only be specified for tagged types, and is inherited by any descendent of the | |
28125 | tagged types. The invariant is a boolean expression that is tested for being | |
28126 | true in the following situations: conversions to the private type, object | |
28127 | declarations for the private type that are default initialized, and | |
1acce141 | 28128 | [@strong{in}] @strong{out} |
b71d4b62 RA |
28129 | parameters and returned result on return from any primitive operation for |
28130 | the type that is visible to a client. | |
28131 | GNAT defines the synonyms @code{Invariant} for @code{Type_Invariant} and | |
28132 | @code{Invariant'Class} for @code{Type_Invariant'Class}. | |
64d5610f | 28133 | |
b71d4b62 | 28134 | RM References: 13.03.03 (00) |
64d5610f ML |
28135 | @end itemize |
28136 | ||
b71d4b62 | 28137 | @geindex AI-0078 (Ada 2012 feature) |
64d5610f ML |
28138 | |
28139 | ||
28140 | @itemize * | |
28141 | ||
28142 | @item | |
1acce141 | 28143 | @emph{AI-0078 Relax Unchecked_Conversion alignment rules (0000-00-00)} |
64d5610f | 28144 | |
b71d4b62 RA |
28145 | In Ada 2012, compilers are required to support unchecked conversion where the |
28146 | target alignment is a multiple of the source alignment. GNAT always supported | |
28147 | this case (and indeed all cases of differing alignments, doing copies where | |
28148 | required if the alignment was reduced). | |
64d5610f | 28149 | |
b71d4b62 | 28150 | RM References: 13.09 (7) |
64d5610f ML |
28151 | @end itemize |
28152 | ||
b71d4b62 | 28153 | @geindex AI-0195 (Ada 2012 feature) |
64d5610f ML |
28154 | |
28155 | ||
28156 | @itemize * | |
28157 | ||
28158 | @item | |
1acce141 | 28159 | @emph{AI-0195 Invalid value handling is implementation defined (2010-07-03)} |
64d5610f | 28160 | |
b71d4b62 RA |
28161 | The handling of invalid values is now designated to be implementation |
28162 | defined. This is a documentation change only, requiring Annex M in the GNAT | |
28163 | Reference Manual to document this handling. | |
28164 | In GNAT, checks for invalid values are made | |
28165 | only when necessary to avoid erroneous behavior. Operations like assignments | |
28166 | which cannot cause erroneous behavior ignore the possibility of invalid | |
28167 | values and do not do a check. The date given above applies only to the | |
28168 | documentation change, this behavior has always been implemented by GNAT. | |
64d5610f | 28169 | |
b71d4b62 | 28170 | RM References: 13.09.01 (10) |
64d5610f ML |
28171 | @end itemize |
28172 | ||
b71d4b62 | 28173 | @geindex AI-0193 (Ada 2012 feature) |
64d5610f ML |
28174 | |
28175 | ||
28176 | @itemize * | |
28177 | ||
28178 | @item | |
1acce141 | 28179 | @emph{AI-0193 Alignment of allocators (2010-09-16)} |
64d5610f | 28180 | |
b71d4b62 RA |
28181 | This AI introduces a new attribute @code{Max_Alignment_For_Allocation}, |
28182 | analogous to @code{Max_Size_In_Storage_Elements}, but for alignment instead | |
28183 | of size. | |
64d5610f | 28184 | |
b71d4b62 RA |
28185 | RM References: 13.11 (16) 13.11 (21) 13.11.01 (0) 13.11.01 (1) |
28186 | 13.11.01 (2) 13.11.01 (3) | |
64d5610f ML |
28187 | @end itemize |
28188 | ||
b71d4b62 | 28189 | @geindex AI-0177 (Ada 2012 feature) |
64d5610f ML |
28190 | |
28191 | ||
28192 | @itemize * | |
28193 | ||
28194 | @item | |
1acce141 | 28195 | @emph{AI-0177 Parameterized expressions (2010-07-10)} |
64d5610f | 28196 | |
b71d4b62 RA |
28197 | The new Ada 2012 notion of parameterized expressions is implemented. The form |
28198 | is: | |
64d5610f | 28199 | |
b71d4b62 RA |
28200 | @example |
28201 | function-specification is (expression) | |
28202 | @end example | |
28203 | ||
28204 | This is exactly equivalent to the | |
28205 | corresponding function body that returns the expression, but it can appear | |
28206 | in a package spec. Note that the expression must be parenthesized. | |
28207 | ||
28208 | RM References: 13.11.01 (3/2) | |
64d5610f ML |
28209 | @end itemize |
28210 | ||
b71d4b62 | 28211 | @geindex AI-0033 (Ada 2012 feature) |
64d5610f ML |
28212 | |
28213 | ||
28214 | @itemize * | |
28215 | ||
28216 | @item | |
1acce141 | 28217 | @emph{AI-0033 Attach/Interrupt_Handler in generic (2010-07-24)} |
64d5610f | 28218 | |
b71d4b62 RA |
28219 | Neither of these two pragmas may appear within a generic template, because |
28220 | the generic might be instantiated at other than the library level. | |
64d5610f | 28221 | |
b71d4b62 | 28222 | RM References: 13.11.02 (16) C.03.01 (7/2) C.03.01 (8/2) |
64d5610f ML |
28223 | @end itemize |
28224 | ||
b71d4b62 | 28225 | @geindex AI-0161 (Ada 2012 feature) |
64d5610f ML |
28226 | |
28227 | ||
28228 | @itemize * | |
28229 | ||
28230 | @item | |
1acce141 | 28231 | @emph{AI-0161 Restriction No_Default_Stream_Attributes (2010-09-11)} |
64d5610f | 28232 | |
b71d4b62 RA |
28233 | A new restriction @code{No_Default_Stream_Attributes} prevents the use of any |
28234 | of the default stream attributes for elementary types. If this restriction is | |
28235 | in force, then it is necessary to provide explicit subprograms for any | |
28236 | stream attributes used. | |
64d5610f | 28237 | |
b71d4b62 | 28238 | RM References: 13.12.01 (4/2) 13.13.02 (40/2) 13.13.02 (52/2) |
64d5610f ML |
28239 | @end itemize |
28240 | ||
b71d4b62 | 28241 | @geindex AI-0194 (Ada 2012 feature) |
64d5610f ML |
28242 | |
28243 | ||
28244 | @itemize * | |
28245 | ||
28246 | @item | |
1acce141 | 28247 | @emph{AI-0194 Value of Stream_Size attribute (0000-00-00)} |
64d5610f | 28248 | |
b71d4b62 RA |
28249 | The @code{Stream_Size} attribute returns the default number of bits in the |
28250 | stream representation of the given type. | |
28251 | This value is not affected by the presence | |
28252 | of stream subprogram attributes for the type. GNAT has always implemented | |
28253 | this interpretation. | |
64d5610f | 28254 | |
b71d4b62 | 28255 | RM References: 13.13.02 (1.2/2) |
64d5610f ML |
28256 | @end itemize |
28257 | ||
b71d4b62 | 28258 | @geindex AI-0109 (Ada 2012 feature) |
64d5610f ML |
28259 | |
28260 | ||
28261 | @itemize * | |
28262 | ||
28263 | @item | |
1acce141 | 28264 | @emph{AI-0109 Redundant check in S’Class’Input (0000-00-00)} |
64d5610f | 28265 | |
b71d4b62 RA |
28266 | This AI is an editorial change only. It removes the need for a tag check |
28267 | that can never fail. | |
64d5610f | 28268 | |
b71d4b62 | 28269 | RM References: 13.13.02 (34/2) |
64d5610f ML |
28270 | @end itemize |
28271 | ||
b71d4b62 | 28272 | @geindex AI-0007 (Ada 2012 feature) |
64d5610f ML |
28273 | |
28274 | ||
28275 | @itemize * | |
28276 | ||
28277 | @item | |
1acce141 | 28278 | @emph{AI-0007 Stream read and private scalar types (0000-00-00)} |
64d5610f | 28279 | |
b71d4b62 RA |
28280 | The RM as written appeared to limit the possibilities of declaring read |
28281 | attribute procedures for private scalar types. This limitation was not | |
28282 | intended, and has never been enforced by GNAT. | |
64d5610f | 28283 | |
b71d4b62 | 28284 | RM References: 13.13.02 (50/2) 13.13.02 (51/2) |
64d5610f ML |
28285 | @end itemize |
28286 | ||
b71d4b62 | 28287 | @geindex AI-0065 (Ada 2012 feature) |
64d5610f ML |
28288 | |
28289 | ||
28290 | @itemize * | |
28291 | ||
28292 | @item | |
1acce141 | 28293 | @emph{AI-0065 Remote access types and external streaming (0000-00-00)} |
64d5610f | 28294 | |
b71d4b62 RA |
28295 | This AI clarifies the fact that all remote access types support external |
28296 | streaming. This fixes an obvious oversight in the definition of the | |
28297 | language, and GNAT always implemented the intended correct rules. | |
64d5610f | 28298 | |
b71d4b62 | 28299 | RM References: 13.13.02 (52/2) |
64d5610f ML |
28300 | @end itemize |
28301 | ||
b71d4b62 | 28302 | @geindex AI-0019 (Ada 2012 feature) |
64d5610f ML |
28303 | |
28304 | ||
28305 | @itemize * | |
28306 | ||
28307 | @item | |
1acce141 | 28308 | @emph{AI-0019 Freezing of primitives for tagged types (0000-00-00)} |
64d5610f | 28309 | |
b71d4b62 RA |
28310 | The RM suggests that primitive subprograms of a specific tagged type are |
28311 | frozen when the tagged type is frozen. This would be an incompatible change | |
28312 | and is not intended. GNAT has never attempted this kind of freezing and its | |
28313 | behavior is consistent with the recommendation of this AI. | |
64d5610f | 28314 | |
b71d4b62 | 28315 | RM References: 13.14 (2) 13.14 (3/1) 13.14 (8.1/1) 13.14 (10) 13.14 (14) 13.14 (15.1/2) |
64d5610f ML |
28316 | @end itemize |
28317 | ||
b71d4b62 | 28318 | @geindex AI-0017 (Ada 2012 feature) |
64d5610f ML |
28319 | |
28320 | ||
28321 | @itemize * | |
28322 | ||
28323 | @item | |
1acce141 | 28324 | @emph{AI-0017 Freezing and incomplete types (0000-00-00)} |
64d5610f | 28325 | |
b71d4b62 RA |
28326 | So-called ‘Taft-amendment types’ (i.e., types that are completed in package |
28327 | bodies) are not frozen by the occurrence of bodies in the | |
28328 | enclosing declarative part. GNAT always implemented this properly. | |
64d5610f | 28329 | |
b71d4b62 | 28330 | RM References: 13.14 (3/1) |
64d5610f ML |
28331 | @end itemize |
28332 | ||
b71d4b62 | 28333 | @geindex AI-0060 (Ada 2012 feature) |
64d5610f ML |
28334 | |
28335 | ||
28336 | @itemize * | |
28337 | ||
28338 | @item | |
1acce141 | 28339 | @emph{AI-0060 Extended definition of remote access types (0000-00-00)} |
64d5610f | 28340 | |
b71d4b62 RA |
28341 | This AI extends the definition of remote access types to include access |
28342 | to limited, synchronized, protected or task class-wide interface types. | |
28343 | GNAT already implemented this extension. | |
64d5610f | 28344 | |
b71d4b62 | 28345 | RM References: A (4) E.02.02 (9/1) E.02.02 (9.2/1) E.02.02 (14/2) E.02.02 (18) |
64d5610f ML |
28346 | @end itemize |
28347 | ||
b71d4b62 | 28348 | @geindex AI-0114 (Ada 2012 feature) |
64d5610f ML |
28349 | |
28350 | ||
28351 | @itemize * | |
28352 | ||
28353 | @item | |
1acce141 | 28354 | @emph{AI-0114 Classification of letters (0000-00-00)} |
64d5610f | 28355 | |
b71d4b62 RA |
28356 | The code points 170 (@code{FEMININE ORDINAL INDICATOR}), |
28357 | 181 (@code{MICRO SIGN}), and | |
28358 | 186 (@code{MASCULINE ORDINAL INDICATOR}) are technically considered | |
28359 | lower case letters by Unicode. | |
28360 | However, they are not allowed in identifiers, and they | |
28361 | return @code{False} to @code{Ada.Characters.Handling.Is_Letter/Is_Lower}. | |
28362 | This behavior is consistent with that defined in Ada 95. | |
64d5610f | 28363 | |
b71d4b62 | 28364 | RM References: A.03.02 (59) A.04.06 (7) |
64d5610f ML |
28365 | @end itemize |
28366 | ||
b71d4b62 | 28367 | @geindex AI-0185 (Ada 2012 feature) |
64d5610f ML |
28368 | |
28369 | ||
28370 | @itemize * | |
28371 | ||
28372 | @item | |
1acce141 | 28373 | @emph{AI-0185 Ada.Wide_[Wide_]Characters.Handling (2010-07-06)} |
64d5610f | 28374 | |
b71d4b62 RA |
28375 | Two new packages @code{Ada.Wide_[Wide_]Characters.Handling} provide |
28376 | classification functions for @code{Wide_Character} and | |
28377 | @code{Wide_Wide_Character}, as well as providing | |
28378 | case folding routines for @code{Wide_[Wide_]Character} and | |
28379 | @code{Wide_[Wide_]String}. | |
64d5610f | 28380 | |
b71d4b62 | 28381 | RM References: A.03.05 (0) A.03.06 (0) |
64d5610f ML |
28382 | @end itemize |
28383 | ||
b71d4b62 | 28384 | @geindex AI-0031 (Ada 2012 feature) |
64d5610f ML |
28385 | |
28386 | ||
28387 | @itemize * | |
28388 | ||
28389 | @item | |
1acce141 | 28390 | @emph{AI-0031 Add From parameter to Find_Token (2010-07-25)} |
64d5610f | 28391 | |
b71d4b62 RA |
28392 | A new version of @code{Find_Token} is added to all relevant string packages, |
28393 | with an extra parameter @code{From}. Instead of starting at the first | |
28394 | character of the string, the search for a matching Token starts at the | |
28395 | character indexed by the value of @code{From}. | |
28396 | These procedures are available in all versions of Ada | |
28397 | but if used in versions earlier than Ada 2012 they will generate a warning | |
28398 | that an Ada 2012 subprogram is being used. | |
64d5610f | 28399 | |
b71d4b62 RA |
28400 | RM References: A.04.03 (16) A.04.03 (67) A.04.03 (68/1) A.04.04 (51) |
28401 | A.04.05 (46) | |
64d5610f ML |
28402 | @end itemize |
28403 | ||
b71d4b62 | 28404 | @geindex AI-0056 (Ada 2012 feature) |
64d5610f ML |
28405 | |
28406 | ||
28407 | @itemize * | |
28408 | ||
28409 | @item | |
1acce141 | 28410 | @emph{AI-0056 Index on null string returns zero (0000-00-00)} |
64d5610f | 28411 | |
b71d4b62 RA |
28412 | The wording in the Ada 2005 RM implied an incompatible handling of the |
28413 | @code{Index} functions, resulting in raising an exception instead of | |
28414 | returning zero in some situations. | |
28415 | This was not intended and has been corrected. | |
28416 | GNAT always returned zero, and is thus consistent with this AI. | |
64d5610f | 28417 | |
b71d4b62 | 28418 | RM References: A.04.03 (56.2/2) A.04.03 (58.5/2) |
64d5610f ML |
28419 | @end itemize |
28420 | ||
b71d4b62 | 28421 | @geindex AI-0137 (Ada 2012 feature) |
64d5610f ML |
28422 | |
28423 | ||
28424 | @itemize * | |
28425 | ||
28426 | @item | |
1acce141 | 28427 | @emph{AI-0137 String encoding package (2010-03-25)} |
64d5610f | 28428 | |
b71d4b62 RA |
28429 | The packages @code{Ada.Strings.UTF_Encoding}, together with its child |
28430 | packages, @code{Conversions}, @code{Strings}, @code{Wide_Strings}, | |
28431 | and @code{Wide_Wide_Strings} have been | |
28432 | implemented. These packages (whose documentation can be found in the spec | |
28433 | files @code{a-stuten.ads}, @code{a-suenco.ads}, @code{a-suenst.ads}, | |
28434 | @code{a-suewst.ads}, @code{a-suezst.ads}) allow encoding and decoding of | |
28435 | @code{String}, @code{Wide_String}, and @code{Wide_Wide_String} | |
28436 | values using UTF coding schemes (including UTF-8, UTF-16LE, UTF-16BE, and | |
28437 | UTF-16), as well as conversions between the different UTF encodings. With | |
28438 | the exception of @code{Wide_Wide_Strings}, these packages are available in | |
28439 | Ada 95 and Ada 2005 mode as well as Ada 2012 mode. | |
28440 | The @code{Wide_Wide_Strings} package | |
28441 | is available in Ada 2005 mode as well as Ada 2012 mode (but not in Ada 95 | |
28442 | mode since it uses @code{Wide_Wide_Character}). | |
64d5610f | 28443 | |
b71d4b62 | 28444 | RM References: A.04.11 |
64d5610f ML |
28445 | @end itemize |
28446 | ||
b71d4b62 | 28447 | @geindex AI-0038 (Ada 2012 feature) |
64d5610f ML |
28448 | |
28449 | ||
28450 | @itemize * | |
28451 | ||
28452 | @item | |
1acce141 | 28453 | @emph{AI-0038 Minor errors in Text_IO (0000-00-00)} |
64d5610f | 28454 | |
b71d4b62 RA |
28455 | These are minor errors in the description on three points. The intent on |
28456 | all these points has always been clear, and GNAT has always implemented the | |
28457 | correct intended semantics. | |
64d5610f | 28458 | |
b71d4b62 | 28459 | RM References: A.10.05 (37) A.10.07 (8/1) A.10.07 (10) A.10.07 (12) A.10.08 (10) A.10.08 (24) |
64d5610f ML |
28460 | @end itemize |
28461 | ||
b71d4b62 | 28462 | @geindex AI-0044 (Ada 2012 feature) |
64d5610f ML |
28463 | |
28464 | ||
28465 | @itemize * | |
28466 | ||
28467 | @item | |
1acce141 | 28468 | @emph{AI-0044 Restrictions on container instantiations (0000-00-00)} |
64d5610f | 28469 | |
b71d4b62 RA |
28470 | This AI places restrictions on allowed instantiations of generic containers. |
28471 | These restrictions are not checked by the compiler, so there is nothing to | |
28472 | change in the implementation. This affects only the RM documentation. | |
64d5610f | 28473 | |
b71d4b62 | 28474 | RM References: A.18 (4/2) A.18.02 (231/2) A.18.03 (145/2) A.18.06 (56/2) A.18.08 (66/2) A.18.09 (79/2) A.18.26 (5/2) A.18.26 (9/2) |
64d5610f ML |
28475 | @end itemize |
28476 | ||
b71d4b62 | 28477 | @geindex AI-0127 (Ada 2012 feature) |
64d5610f ML |
28478 | |
28479 | ||
28480 | @itemize * | |
28481 | ||
28482 | @item | |
1acce141 | 28483 | @emph{AI-0127 Adding Locale Capabilities (2010-09-29)} |
64d5610f | 28484 | |
b71d4b62 | 28485 | This package provides an interface for identifying the current locale. |
64d5610f | 28486 | |
b71d4b62 RA |
28487 | RM References: A.19 A.19.01 A.19.02 A.19.03 A.19.05 A.19.06 |
28488 | A.19.07 A.19.08 A.19.09 A.19.10 A.19.11 A.19.12 A.19.13 | |
64d5610f ML |
28489 | @end itemize |
28490 | ||
b71d4b62 | 28491 | @geindex AI-0002 (Ada 2012 feature) |
64d5610f ML |
28492 | |
28493 | ||
28494 | @itemize * | |
28495 | ||
28496 | @item | |
1acce141 | 28497 | @emph{AI-0002 Export C with unconstrained arrays (0000-00-00)} |
64d5610f | 28498 | |
b71d4b62 RA |
28499 | The compiler is not required to support exporting an Ada subprogram with |
28500 | convention C if there are parameters or a return type of an unconstrained | |
28501 | array type (such as @code{String}). GNAT allows such declarations but | |
28502 | generates warnings. It is possible, but complicated, to write the | |
28503 | corresponding C code and certainly such code would be specific to GNAT and | |
28504 | non-portable. | |
64d5610f | 28505 | |
b71d4b62 | 28506 | RM References: B.01 (17) B.03 (62) B.03 (71.1/2) |
64d5610f ML |
28507 | @end itemize |
28508 | ||
b71d4b62 | 28509 | @geindex AI05-0216 (Ada 2012 feature) |
64d5610f ML |
28510 | |
28511 | ||
28512 | @itemize * | |
28513 | ||
28514 | @item | |
1acce141 | 28515 | @emph{AI-0216 No_Task_Hierarchy forbids local tasks (0000-00-00)} |
64d5610f | 28516 | |
b71d4b62 RA |
28517 | It is clearly the intention that @code{No_Task_Hierarchy} is intended to |
28518 | forbid tasks declared locally within subprograms, or functions returning task | |
28519 | objects, and that is the implementation that GNAT has always provided. | |
28520 | However the language in the RM was not sufficiently clear on this point. | |
28521 | Thus this is a documentation change in the RM only. | |
64d5610f | 28522 | |
b71d4b62 | 28523 | RM References: D.07 (3/3) |
64d5610f ML |
28524 | @end itemize |
28525 | ||
b71d4b62 | 28526 | @geindex AI-0211 (Ada 2012 feature) |
64d5610f ML |
28527 | |
28528 | ||
28529 | @itemize * | |
28530 | ||
28531 | @item | |
1acce141 | 28532 | @emph{AI-0211 No_Relative_Delays forbids Set_Handler use (2010-07-09)} |
64d5610f | 28533 | |
b71d4b62 RA |
28534 | The restriction @code{No_Relative_Delays} forbids any calls to the subprogram |
28535 | @code{Ada.Real_Time.Timing_Events.Set_Handler}. | |
64d5610f | 28536 | |
b71d4b62 | 28537 | RM References: D.07 (5) D.07 (10/2) D.07 (10.4/2) D.07 (10.7/2) |
64d5610f ML |
28538 | @end itemize |
28539 | ||
b71d4b62 | 28540 | @geindex AI-0190 (Ada 2012 feature) |
64d5610f ML |
28541 | |
28542 | ||
28543 | @itemize * | |
28544 | ||
28545 | @item | |
1acce141 | 28546 | @emph{AI-0190 pragma Default_Storage_Pool (2010-09-15)} |
64d5610f | 28547 | |
b71d4b62 RA |
28548 | This AI introduces a new pragma @code{Default_Storage_Pool}, which can be |
28549 | used to control storage pools globally. | |
28550 | In particular, you can force every access | |
1acce141 | 28551 | type that is used for allocation (@strong{new}) to have an explicit storage pool, |
b71d4b62 RA |
28552 | or you can declare a pool globally to be used for all access types that lack |
28553 | an explicit one. | |
64d5610f | 28554 | |
b71d4b62 | 28555 | RM References: D.07 (8) |
64d5610f ML |
28556 | @end itemize |
28557 | ||
b71d4b62 | 28558 | @geindex AI-0189 (Ada 2012 feature) |
64d5610f ML |
28559 | |
28560 | ||
28561 | @itemize * | |
28562 | ||
28563 | @item | |
1acce141 | 28564 | @emph{AI-0189 No_Allocators_After_Elaboration (2010-01-23)} |
64d5610f | 28565 | |
b71d4b62 RA |
28566 | This AI introduces a new restriction @code{No_Allocators_After_Elaboration}, |
28567 | which says that no dynamic allocation will occur once elaboration is | |
28568 | completed. | |
28569 | In general this requires a run-time check, which is not required, and which | |
28570 | GNAT does not attempt. But the static cases of allocators in a task body or | |
28571 | in the body of the main program are detected and flagged at compile or bind | |
28572 | time. | |
64d5610f | 28573 | |
b71d4b62 | 28574 | RM References: D.07 (19.1/2) H.04 (23.3/2) |
64d5610f ML |
28575 | @end itemize |
28576 | ||
b71d4b62 | 28577 | @geindex AI-0171 (Ada 2012 feature) |
64d5610f ML |
28578 | |
28579 | ||
28580 | @itemize * | |
28581 | ||
28582 | @item | |
1acce141 | 28583 | @emph{AI-0171 Pragma CPU and Ravenscar Profile (2010-09-24)} |
64d5610f | 28584 | |
b71d4b62 RA |
28585 | A new package @code{System.Multiprocessors} is added, together with the |
28586 | definition of pragma @code{CPU} for controlling task affinity. A new no | |
28587 | dependence restriction, on @code{System.Multiprocessors.Dispatching_Domains}, | |
28588 | is added to the Ravenscar profile. | |
64d5610f | 28589 | |
b71d4b62 | 28590 | RM References: D.13.01 (4/2) D.16 |
64d5610f ML |
28591 | @end itemize |
28592 | ||
b71d4b62 | 28593 | @geindex AI-0210 (Ada 2012 feature) |
64d5610f ML |
28594 | |
28595 | ||
28596 | @itemize * | |
28597 | ||
28598 | @item | |
1acce141 | 28599 | @emph{AI-0210 Correct Timing_Events metric (0000-00-00)} |
64d5610f | 28600 | |
b71d4b62 RA |
28601 | This is a documentation only issue regarding wording of metric requirements, |
28602 | that does not affect the implementation of the compiler. | |
64d5610f | 28603 | |
b71d4b62 | 28604 | RM References: D.15 (24/2) |
64d5610f ML |
28605 | @end itemize |
28606 | ||
b71d4b62 | 28607 | @geindex AI-0206 (Ada 2012 feature) |
64d5610f ML |
28608 | |
28609 | ||
28610 | @itemize * | |
28611 | ||
28612 | @item | |
1acce141 | 28613 | @emph{AI-0206 Remote types packages and preelaborate (2010-07-24)} |
64d5610f | 28614 | |
b71d4b62 RA |
28615 | Remote types packages are now allowed to depend on preelaborated packages. |
28616 | This was formerly considered illegal. | |
64d5610f | 28617 | |
b71d4b62 | 28618 | RM References: E.02.02 (6) |
64d5610f ML |
28619 | @end itemize |
28620 | ||
b71d4b62 | 28621 | @geindex AI-0152 (Ada 2012 feature) |
64d5610f ML |
28622 | |
28623 | ||
28624 | @itemize * | |
28625 | ||
28626 | @item | |
1acce141 | 28627 | @emph{AI-0152 Restriction No_Anonymous_Allocators (2010-09-08)} |
64d5610f | 28628 | |
b71d4b62 RA |
28629 | Restriction @code{No_Anonymous_Allocators} prevents the use of allocators |
28630 | where the type of the returned value is an anonymous access type. | |
64d5610f | 28631 | |
b71d4b62 | 28632 | RM References: H.04 (8/1) |
64d5610f ML |
28633 | @end itemize |
28634 | ||
b71d4b62 | 28635 | @node GNAT language extensions,Security Hardening Features,Implementation of Ada 2012 Features,Top |
9daee425 | 28636 | @anchor{gnat_rm/gnat_language_extensions doc}@anchor{437}@anchor{gnat_rm/gnat_language_extensions gnat-language-extensions}@anchor{438}@anchor{gnat_rm/gnat_language_extensions id1}@anchor{439} |
b71d4b62 RA |
28637 | @chapter GNAT language extensions |
28638 | ||
28639 | ||
28640 | The GNAT compiler implements a certain number of language extensions on top of | |
28641 | the latest Ada standard, implementing its own extended superset of Ada. | |
28642 | ||
28643 | There are two sets of language extensions: | |
64d5610f ML |
28644 | |
28645 | ||
28646 | @itemize * | |
28647 | ||
28648 | @item | |
b71d4b62 RA |
28649 | The first is the curated set. The features in that set are features that we |
28650 | consider being worthy additions to the Ada language, and that we want to make | |
28651 | available to users early on. | |
64d5610f | 28652 | |
b71d4b62 RA |
28653 | @item |
28654 | The second is the experimental set. It includes the first, but also | |
28655 | experimental features, that are here because they’re still in an early | |
28656 | prototyping phase. | |
64d5610f ML |
28657 | @end itemize |
28658 | ||
b71d4b62 RA |
28659 | @menu |
28660 | * How to activate the extended GNAT Ada superset:: | |
28661 | * Curated Extensions:: | |
28662 | * Experimental Language Extensions:: | |
64d5610f | 28663 | |
b71d4b62 | 28664 | @end menu |
64d5610f | 28665 | |
b71d4b62 | 28666 | @node How to activate the extended GNAT Ada superset,Curated Extensions,,GNAT language extensions |
9daee425 | 28667 | @anchor{gnat_rm/gnat_language_extensions how-to-activate-the-extended-gnat-ada-superset}@anchor{43a} |
b71d4b62 | 28668 | @section How to activate the extended GNAT Ada superset |
64d5610f | 28669 | |
64d5610f | 28670 | |
b71d4b62 | 28671 | There are two ways to activate the extended GNAT Ada superset: |
64d5610f | 28672 | |
b71d4b62 RA |
28673 | |
28674 | @itemize * | |
28675 | ||
28676 | @item | |
28677 | The @ref{65,,Pragma Extensions_Allowed}. To activate | |
28678 | the curated set of extensions, you should use | |
64d5610f ML |
28679 | @end itemize |
28680 | ||
b71d4b62 RA |
28681 | @example |
28682 | pragma Extensions_Allowed (On) | |
28683 | @end example | |
28684 | ||
28685 | As a configuration pragma, you can either put it at the beginning of a source | |
28686 | file, or in a @code{.adc} file corresponding to your project. | |
64d5610f ML |
28687 | |
28688 | ||
28689 | @itemize * | |
28690 | ||
28691 | @item | |
b71d4b62 RA |
28692 | The @code{-gnatX} option, that you can pass to the compiler directly, will |
28693 | activate the curated subset of extensions. | |
28694 | @end itemize | |
64d5610f | 28695 | |
b71d4b62 RA |
28696 | @cartouche |
28697 | @quotation Attention | |
28698 | You can activate the extended set of extensions by using either | |
28699 | the @code{-gnatX0} command line flag, or the pragma @code{Extensions_Allowed} with | |
28700 | @code{All} as an argument. However, it is not recommended you use this subset | |
28701 | for serious projects, and is only means as a playground/technology preview. | |
28702 | @end quotation | |
28703 | @end cartouche | |
64d5610f | 28704 | |
b71d4b62 | 28705 | @node Curated Extensions,Experimental Language Extensions,How to activate the extended GNAT Ada superset,GNAT language extensions |
9daee425 | 28706 | @anchor{gnat_rm/gnat_language_extensions curated-extensions}@anchor{43b}@anchor{gnat_rm/gnat_language_extensions curated-language-extensions}@anchor{66} |
b71d4b62 | 28707 | @section Curated Extensions |
64d5610f | 28708 | |
64d5610f | 28709 | |
b71d4b62 | 28710 | @menu |
9105cd90 | 28711 | * Local Declarations Without Block:: |
b71d4b62 RA |
28712 | * Conditional when constructs:: |
28713 | * Case pattern matching:: | |
28714 | * Fixed lower bounds for array types and subtypes:: | |
28715 | * Prefixed-view notation for calls to primitive subprograms of untagged types:: | |
28716 | * Expression defaults for generic formal functions:: | |
28717 | * String interpolation:: | |
28718 | * Constrained attribute for generic objects:: | |
28719 | * Static aspect on intrinsic functions:: | |
64d5610f | 28720 | |
b71d4b62 | 28721 | @end menu |
64d5610f | 28722 | |
9105cd90 | 28723 | @node Local Declarations Without Block,Conditional when constructs,,Curated Extensions |
9daee425 | 28724 | @anchor{gnat_rm/gnat_language_extensions local-declarations-without-block}@anchor{43c} |
9105cd90 BD |
28725 | @subsection Local Declarations Without Block |
28726 | ||
28727 | ||
28728 | A basic_declarative_item may appear at the place of any statement. | |
28729 | This avoids the heavy syntax of block_statements just to declare | |
28730 | something locally. | |
28731 | ||
28732 | Link to the original RFC: | |
28733 | @indicateurl{https://github.com/AdaCore/ada-spark-rfcs/blob/master/prototyped/rfc-local-vars-without-block.md} | |
28734 | For example: | |
28735 | ||
28736 | @example | |
28737 | if X > 5 then | |
28738 | X := X + 1; | |
28739 | ||
28740 | Squared : constant Integer := X**2; | |
28741 | ||
28742 | X := X + Squared; | |
28743 | end if; | |
28744 | @end example | |
28745 | ||
28746 | @node Conditional when constructs,Case pattern matching,Local Declarations Without Block,Curated Extensions | |
9daee425 | 28747 | @anchor{gnat_rm/gnat_language_extensions conditional-when-constructs}@anchor{43d} |
b71d4b62 | 28748 | @subsection Conditional when constructs |
64d5610f | 28749 | |
64d5610f | 28750 | |
b71d4b62 RA |
28751 | This feature extends the use of @code{when} as a way to condition a control-flow |
28752 | related statement, to all control-flow related statements. | |
64d5610f | 28753 | |
b71d4b62 | 28754 | To do a conditional return in a procedure the following syntax should be used: |
64d5610f | 28755 | |
b71d4b62 RA |
28756 | @example |
28757 | procedure P (Condition : Boolean) is | |
28758 | begin | |
28759 | return when Condition; | |
28760 | end; | |
28761 | @end example | |
64d5610f | 28762 | |
b71d4b62 | 28763 | This will return from the procedure if @code{Condition} is true. |
64d5610f | 28764 | |
b71d4b62 | 28765 | When being used in a function the conditional part comes after the return value: |
64d5610f | 28766 | |
b71d4b62 RA |
28767 | @example |
28768 | function Is_Null (I : Integer) return Boolean is | |
28769 | begin | |
28770 | return True when I = 0; | |
28771 | return False; | |
28772 | end; | |
28773 | @end example | |
64d5610f | 28774 | |
b71d4b62 | 28775 | In a similar way to the @code{exit when} a @code{goto ... when} can be employed: |
64d5610f | 28776 | |
b71d4b62 RA |
28777 | @example |
28778 | procedure Low_Level_Optimized is | |
28779 | Flags : Bitmapping; | |
28780 | begin | |
28781 | Do_1 (Flags); | |
28782 | goto Cleanup when Flags (1); | |
64d5610f | 28783 | |
b71d4b62 RA |
28784 | Do_2 (Flags); |
28785 | goto Cleanup when Flags (32); | |
64d5610f | 28786 | |
b71d4b62 | 28787 | -- ... |
64d5610f | 28788 | |
b71d4b62 RA |
28789 | <<Cleanup>> |
28790 | -- ... | |
28791 | end; | |
28792 | @end example | |
64d5610f | 28793 | |
b71d4b62 | 28794 | @c code-block |
64d5610f | 28795 | |
b71d4b62 | 28796 | To use a conditional raise construct: |
64d5610f | 28797 | |
b71d4b62 RA |
28798 | @example |
28799 | procedure Foo is | |
28800 | begin | |
28801 | raise Error when Imported_C_Func /= 0; | |
28802 | end; | |
28803 | @end example | |
64d5610f | 28804 | |
b71d4b62 | 28805 | An exception message can also be added: |
64d5610f | 28806 | |
b71d4b62 RA |
28807 | @example |
28808 | procedure Foo is | |
28809 | begin | |
28810 | raise Error with "Unix Error" | |
28811 | when Imported_C_Func /= 0; | |
28812 | end; | |
28813 | @end example | |
64d5610f | 28814 | |
b71d4b62 RA |
28815 | Link to the original RFC: |
28816 | @indicateurl{https://github.com/AdaCore/ada-spark-rfcs/blob/master/prototyped/rfc-conditional-when-constructs.rst} | |
64d5610f | 28817 | |
b71d4b62 | 28818 | @node Case pattern matching,Fixed lower bounds for array types and subtypes,Conditional when constructs,Curated Extensions |
9daee425 | 28819 | @anchor{gnat_rm/gnat_language_extensions case-pattern-matching}@anchor{43e} |
b71d4b62 | 28820 | @subsection Case pattern matching |
64d5610f | 28821 | |
64d5610f | 28822 | |
b8a3e2ed | 28823 | The selector for a case statement (but not yet for a case expression) may be of a composite type, subject to |
b71d4b62 RA |
28824 | some restrictions (described below). Aggregate syntax is used for choices |
28825 | of such a case statement; however, in cases where a “normal” aggregate would | |
28826 | require a discrete value, a discrete subtype may be used instead; box | |
28827 | notation can also be used to match all values. | |
64d5610f | 28828 | |
b71d4b62 | 28829 | Consider this example: |
64d5610f | 28830 | |
b71d4b62 RA |
28831 | @example |
28832 | type Rec is record | |
28833 | F1, F2 : Integer; | |
28834 | end record; | |
64d5610f | 28835 | |
b71d4b62 RA |
28836 | procedure Caser_1 (X : Rec) is |
28837 | begin | |
28838 | case X is | |
28839 | when (F1 => Positive, F2 => Positive) => | |
28840 | Do_This; | |
28841 | when (F1 => Natural, F2 => <>) | (F1 => <>, F2 => Natural) => | |
28842 | Do_That; | |
28843 | when others => | |
28844 | Do_The_Other_Thing; | |
28845 | end case; | |
28846 | end Caser_1; | |
28847 | @end example | |
64d5610f | 28848 | |
b71d4b62 RA |
28849 | If @code{Caser_1} is called and both components of X are positive, then |
28850 | @code{Do_This} will be called; otherwise, if either component is nonnegative | |
28851 | then @code{Do_That} will be called; otherwise, @code{Do_The_Other_Thing} will be | |
28852 | called. | |
64d5610f | 28853 | |
b71d4b62 RA |
28854 | In addition, pattern bindings are supported. This is a mechanism |
28855 | for binding a name to a component of a matching value for use within | |
28856 | an alternative of a case statement. For a component association | |
28857 | that occurs within a case choice, the expression may be followed by | |
28858 | @code{is <identifier>}. In the special case of a “box” component association, | |
28859 | the identifier may instead be provided within the box. Either of these | |
28860 | indicates that the given identifier denotes (a constant view of) the matching | |
28861 | subcomponent of the case selector. | |
64d5610f | 28862 | |
b71d4b62 RA |
28863 | @cartouche |
28864 | @quotation Attention | |
28865 | Binding is not yet supported for arrays or subcomponents | |
28866 | thereof. | |
28867 | @end quotation | |
28868 | @end cartouche | |
64d5610f | 28869 | |
b71d4b62 | 28870 | Consider this example (which uses type @code{Rec} from the previous example): |
64d5610f | 28871 | |
b71d4b62 RA |
28872 | @example |
28873 | procedure Caser_2 (X : Rec) is | |
28874 | begin | |
28875 | case X is | |
28876 | when (F1 => Positive is Abc, F2 => Positive) => | |
28877 | Do_This (Abc) | |
28878 | when (F1 => Natural is N1, F2 => <N2>) | | |
28879 | (F1 => <N2>, F2 => Natural is N1) => | |
28880 | Do_That (Param_1 => N1, Param_2 => N2); | |
28881 | when others => | |
28882 | Do_The_Other_Thing; | |
28883 | end case; | |
28884 | end Caser_2; | |
28885 | @end example | |
64d5610f | 28886 | |
b71d4b62 RA |
28887 | This example is the same as the previous one with respect to determining |
28888 | whether @code{Do_This}, @code{Do_That}, or @code{Do_The_Other_Thing} will be called. But | |
28889 | for this version, @code{Do_This} takes a parameter and @code{Do_That} takes two | |
28890 | parameters. If @code{Do_This} is called, the actual parameter in the call will be | |
28891 | @code{X.F1}. | |
64d5610f | 28892 | |
b71d4b62 RA |
28893 | If @code{Do_That} is called, the situation is more complex because there are two |
28894 | choices for that alternative. If @code{Do_That} is called because the first choice | |
28895 | matched (i.e., because @code{X.F1} is nonnegative and either @code{X.F1} or @code{X.F2} | |
28896 | is zero or negative), then the actual parameters of the call will be (in order) | |
28897 | @code{X.F1} and @code{X.F2}. If @code{Do_That} is called because the second choice | |
28898 | matched (and the first one did not), then the actual parameters will be | |
28899 | reversed. | |
64d5610f | 28900 | |
b71d4b62 RA |
28901 | Within the choice list for single alternative, each choice must define the same |
28902 | set of bindings and the component subtypes for for a given identifer must all | |
28903 | statically match. Currently, the case of a binding for a nondiscrete component | |
28904 | is not implemented. | |
64d5610f | 28905 | |
b71d4b62 RA |
28906 | If the set of values that match the choice(s) of an earlier alternative |
28907 | overlaps the corresponding set of a later alternative, then the first set shall | |
28908 | be a proper subset of the second (and the later alternative will not be | |
28909 | executed if the earlier alternative “matches”). All possible values of the | |
28910 | composite type shall be covered. The composite type of the selector shall be an | |
28911 | array or record type that is neither limited nor class-wide. Currently, a “when | |
28912 | others =>” case choice is required; it is intended that this requirement will | |
28913 | be relaxed at some point. | |
64d5610f | 28914 | |
b71d4b62 RA |
28915 | If a subcomponent’s subtype does not meet certain restrictions, then the only |
28916 | value that can be specified for that subcomponent in a case choice expression | |
28917 | is a “box” component association (which matches all possible values for the | |
28918 | subcomponent). This restriction applies if: | |
64d5610f | 28919 | |
64d5610f | 28920 | |
b71d4b62 | 28921 | @itemize - |
64d5610f | 28922 | |
b71d4b62 RA |
28923 | @item |
28924 | the component subtype is not a record, array, or discrete type; or | |
64d5610f ML |
28925 | |
28926 | @item | |
b71d4b62 RA |
28927 | the component subtype is subject to a non-static constraint or has a |
28928 | predicate; or: | |
64d5610f | 28929 | |
b71d4b62 RA |
28930 | @item |
28931 | the component type is an enumeration type that is subject to an enumeration | |
28932 | representation clause; or | |
64d5610f | 28933 | |
b71d4b62 RA |
28934 | @item |
28935 | the component type is a multidimensional array type or an array type with a | |
28936 | nonstatic index subtype. | |
64d5610f ML |
28937 | @end itemize |
28938 | ||
b71d4b62 RA |
28939 | Support for casing on arrays (and on records that contain arrays) is |
28940 | currently subject to some restrictions. Non-positional | |
28941 | array aggregates are not supported as (or within) case choices. Likewise | |
28942 | for array type and subtype names. The current implementation exceeds | |
28943 | compile-time capacity limits in some annoyingly common scenarios; the | |
28944 | message generated in such cases is usually “Capacity exceeded in compiling | |
28945 | case statement with composite selector type”. | |
64d5610f | 28946 | |
b71d4b62 RA |
28947 | Link to the original RFC: |
28948 | @indicateurl{https://github.com/AdaCore/ada-spark-rfcs/blob/master/prototyped/rfc-pattern-matching.rst} | |
64d5610f | 28949 | |
b71d4b62 | 28950 | @node Fixed lower bounds for array types and subtypes,Prefixed-view notation for calls to primitive subprograms of untagged types,Case pattern matching,Curated Extensions |
9daee425 | 28951 | @anchor{gnat_rm/gnat_language_extensions fixed-lower-bounds-for-array-types-and-subtypes}@anchor{43f} |
b71d4b62 | 28952 | @subsection Fixed lower bounds for array types and subtypes |
64d5610f | 28953 | |
64d5610f | 28954 | |
b71d4b62 RA |
28955 | Unconstrained array types and subtypes can be specified with a lower bound that |
28956 | is fixed to a certain value, by writing an index range that uses the syntax | |
28957 | @code{<lower-bound-expression> .. <>}. This guarantees that all objects of the | |
28958 | type or subtype will have the specified lower bound. | |
64d5610f | 28959 | |
b71d4b62 RA |
28960 | For example, a matrix type with fixed lower bounds of zero for each dimension |
28961 | can be declared by the following: | |
64d5610f | 28962 | |
b71d4b62 RA |
28963 | @example |
28964 | type Matrix is | |
28965 | array (Natural range 0 .. <>, Natural range 0 .. <>) of Integer; | |
28966 | @end example | |
64d5610f | 28967 | |
b71d4b62 RA |
28968 | Objects of type @code{Matrix} declared with an index constraint must have index |
28969 | ranges starting at zero: | |
64d5610f | 28970 | |
b71d4b62 RA |
28971 | @example |
28972 | M1 : Matrix (0 .. 9, 0 .. 19); | |
28973 | M2 : Matrix (2 .. 11, 3 .. 22); -- Warning about bounds; will raise CE | |
28974 | @end example | |
64d5610f | 28975 | |
b71d4b62 RA |
28976 | Similarly, a subtype of @code{String} can be declared that specifies the lower |
28977 | bound of objects of that subtype to be @code{1}: | |
64d5610f | 28978 | |
b71d4b62 | 28979 | @quotation |
64d5610f | 28980 | |
b71d4b62 RA |
28981 | @example |
28982 | subtype String_1 is String (1 .. <>); | |
28983 | @end example | |
28984 | @end quotation | |
64d5610f | 28985 | |
b71d4b62 RA |
28986 | If a string slice is passed to a formal of subtype @code{String_1} in a call to a |
28987 | subprogram @code{S}, the slice’s bounds will “slide” so that the lower bound is | |
28988 | @code{1}. | |
64d5610f | 28989 | |
b71d4b62 RA |
28990 | Within @code{S}, the lower bound of the formal is known to be @code{1}, so, unlike a |
28991 | normal unconstrained @code{String} formal, there is no need to worry about | |
28992 | accounting for other possible lower-bound values. Sliding of bounds also occurs | |
28993 | in other contexts, such as for object declarations with an unconstrained | |
28994 | subtype with fixed lower bound, as well as in subtype conversions. | |
64d5610f | 28995 | |
b71d4b62 RA |
28996 | Use of this feature increases safety by simplifying code, and can also improve |
28997 | the efficiency of indexing operations, since the compiler statically knows the | |
28998 | lower bound of unconstrained array formals when the formal’s subtype has index | |
28999 | ranges with static fixed lower bounds. | |
64d5610f | 29000 | |
b71d4b62 RA |
29001 | Link to the original RFC: |
29002 | @indicateurl{https://github.com/AdaCore/ada-spark-rfcs/blob/master/prototyped/rfc-fixed-lower-bound.rst} | |
64d5610f | 29003 | |
b71d4b62 | 29004 | @node Prefixed-view notation for calls to primitive subprograms of untagged types,Expression defaults for generic formal functions,Fixed lower bounds for array types and subtypes,Curated Extensions |
9daee425 | 29005 | @anchor{gnat_rm/gnat_language_extensions prefixed-view-notation-for-calls-to-primitive-subprograms-of-untagged-types}@anchor{440} |
b71d4b62 RA |
29006 | @subsection Prefixed-view notation for calls to primitive subprograms of untagged types |
29007 | ||
29008 | ||
29009 | When operating on an untagged type, if it has any primitive operations, and the | |
29010 | first parameter of an operation is of the type (or is an access parameter with | |
29011 | an anonymous type that designates the type), you may invoke these operations | |
29012 | using an @code{object.op(...)} notation, where the parameter that would normally be | |
29013 | the first parameter is brought out front, and the remaining parameters (if any) | |
29014 | appear within parentheses after the name of the primitive operation. | |
29015 | ||
29016 | This same notation is already available for tagged types. This extension allows | |
29017 | for untagged types. It is allowed for all primitive operations of the type | |
29018 | independent of whether they were originally declared in a package spec or its | |
29019 | private part, or were inherited and/or overridden as part of a derived type | |
29020 | declaration occuring anywhere, so long as the first parameter is of the type, | |
29021 | or an access parameter designating the type. | |
29022 | ||
29023 | For example: | |
29024 | ||
29025 | @example | |
29026 | generic | |
29027 | type Elem_Type is private; | |
29028 | package Vectors is | |
29029 | type Vector is private; | |
29030 | procedure Add_Element (V : in out Vector; Elem : Elem_Type); | |
29031 | function Nth_Element (V : Vector; N : Positive) return Elem_Type; | |
29032 | function Length (V : Vector) return Natural; | |
29033 | private | |
29034 | function Capacity (V : Vector) return Natural; | |
29035 | -- Return number of elements that may be added without causing | |
29036 | -- any new allocation of space | |
29037 | ||
29038 | type Vector is ... | |
29039 | with Type_Invariant => Vector.Length <= Vector.Capacity; | |
29040 | ... | |
29041 | end Vectors; | |
29042 | ||
29043 | package Int_Vecs is new Vectors(Integer); | |
64d5610f | 29044 | |
b71d4b62 RA |
29045 | V : Int_Vecs.Vector; |
29046 | ... | |
29047 | V.Add_Element(42); | |
29048 | V.Add_Element(-33); | |
64d5610f | 29049 | |
b71d4b62 RA |
29050 | pragma Assert (V.Length = 2); |
29051 | pragma Assert (V.Nth_Element(1) = 42); | |
29052 | @end example | |
64d5610f | 29053 | |
b71d4b62 RA |
29054 | Link to the original RFC: |
29055 | @indicateurl{https://github.com/AdaCore/ada-spark-rfcs/blob/master/prototyped/rfc-prefixed-untagged.rst} | |
64d5610f | 29056 | |
b71d4b62 | 29057 | @node Expression defaults for generic formal functions,String interpolation,Prefixed-view notation for calls to primitive subprograms of untagged types,Curated Extensions |
9daee425 | 29058 | @anchor{gnat_rm/gnat_language_extensions expression-defaults-for-generic-formal-functions}@anchor{441} |
b71d4b62 | 29059 | @subsection Expression defaults for generic formal functions |
64d5610f | 29060 | |
64d5610f | 29061 | |
b71d4b62 RA |
29062 | The declaration of a generic formal function is allowed to specify |
29063 | an expression as a default, using the syntax of an expression function. | |
64d5610f | 29064 | |
b71d4b62 | 29065 | Here is an example of this feature: |
64d5610f | 29066 | |
b71d4b62 RA |
29067 | @example |
29068 | generic | |
29069 | type T is private; | |
29070 | with function Copy (Item : T) return T is (Item); -- Defaults to Item | |
29071 | package Stacks is | |
64d5610f | 29072 | |
b71d4b62 | 29073 | type Stack is limited private; |
64d5610f | 29074 | |
b71d4b62 RA |
29075 | procedure Push (S : in out Stack; X : T); -- Calls Copy on X |
29076 | function Pop (S : in out Stack) return T; -- Calls Copy to return item | |
64d5610f | 29077 | |
b71d4b62 RA |
29078 | private |
29079 | -- ... | |
29080 | end Stacks; | |
29081 | @end example | |
64d5610f | 29082 | |
b71d4b62 RA |
29083 | Link to the original RFC: |
29084 | @indicateurl{https://github.com/AdaCore/ada-spark-rfcs/blob/master/prototyped/rfc-expression-functions-as-default-for-generic-formal-function-parameters.rst} | |
64d5610f | 29085 | |
b71d4b62 | 29086 | @node String interpolation,Constrained attribute for generic objects,Expression defaults for generic formal functions,Curated Extensions |
9daee425 | 29087 | @anchor{gnat_rm/gnat_language_extensions string-interpolation}@anchor{442} |
b71d4b62 | 29088 | @subsection String interpolation |
64d5610f | 29089 | |
64d5610f | 29090 | |
b71d4b62 | 29091 | The syntax for string literals is extended to support string interpolation. |
64d5610f | 29092 | |
b71d4b62 RA |
29093 | Within an interpolated string literal, an arbitrary expression, when |
29094 | enclosed in @code{@{ ... @}}, is expanded at run time into the result of calling | |
29095 | @code{'Image} on the result of evaluating the expression enclosed by the brace | |
29096 | characters, unless it is already a string or a single character. | |
64d5610f | 29097 | |
b71d4b62 RA |
29098 | Here is an example of this feature where the expressions @code{Name} and @code{X + Y} |
29099 | will be evaluated and included in the string. | |
64d5610f | 29100 | |
b71d4b62 RA |
29101 | @example |
29102 | procedure Test_Interpolation is | |
29103 | X : Integer := 12; | |
29104 | Y : Integer := 15; | |
29105 | Name : String := "Leo"; | |
29106 | begin | |
29107 | Put_Line (f"The name is @{Name@} and the sum is @{X + Y@}."); | |
29108 | end Test_Interpolation; | |
29109 | @end example | |
64d5610f | 29110 | |
b71d4b62 RA |
29111 | In addition, an escape character (@code{\}) is provided for inserting certain |
29112 | standard control characters (such as @code{\t} for tabulation or @code{\n} for | |
29113 | newline) or to escape characters with special significance to the | |
29114 | interpolated string syntax, namely @code{"}, @code{@{}, @code{@}},and @code{\} itself. | |
64d5610f | 29115 | |
64d5610f | 29116 | |
b71d4b62 RA |
29117 | @multitable {xxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxx} |
29118 | @item | |
64d5610f | 29119 | |
b71d4b62 | 29120 | escaped_character |
64d5610f | 29121 | |
b71d4b62 | 29122 | @tab |
64d5610f | 29123 | |
b71d4b62 | 29124 | meaning |
64d5610f | 29125 | |
b71d4b62 | 29126 | @item |
64d5610f | 29127 | |
b71d4b62 | 29128 | @code{\a} |
64d5610f | 29129 | |
b71d4b62 | 29130 | @tab |
64d5610f | 29131 | |
b71d4b62 | 29132 | ALERT |
64d5610f | 29133 | |
b71d4b62 | 29134 | @item |
64d5610f | 29135 | |
b71d4b62 | 29136 | @code{\b} |
64d5610f | 29137 | |
b71d4b62 | 29138 | @tab |
64d5610f | 29139 | |
b71d4b62 | 29140 | BACKSPACE |
64d5610f | 29141 | |
b71d4b62 | 29142 | @item |
64d5610f | 29143 | |
b71d4b62 | 29144 | @code{\f} |
64d5610f | 29145 | |
b71d4b62 | 29146 | @tab |
64d5610f | 29147 | |
b71d4b62 | 29148 | FORM FEED |
64d5610f | 29149 | |
b71d4b62 | 29150 | @item |
64d5610f | 29151 | |
b71d4b62 | 29152 | @code{\n} |
64d5610f | 29153 | |
b71d4b62 | 29154 | @tab |
64d5610f | 29155 | |
b71d4b62 | 29156 | LINE FEED |
64d5610f | 29157 | |
b71d4b62 | 29158 | @item |
64d5610f | 29159 | |
b71d4b62 | 29160 | @code{\r} |
64d5610f | 29161 | |
b71d4b62 | 29162 | @tab |
64d5610f | 29163 | |
b71d4b62 | 29164 | CARRIAGE RETURN |
64d5610f | 29165 | |
b71d4b62 | 29166 | @item |
64d5610f | 29167 | |
b71d4b62 | 29168 | @code{\t} |
64d5610f | 29169 | |
b71d4b62 | 29170 | @tab |
64d5610f | 29171 | |
b71d4b62 | 29172 | CHARACTER TABULATION |
64d5610f | 29173 | |
b71d4b62 | 29174 | @item |
64d5610f | 29175 | |
b71d4b62 | 29176 | @code{\v} |
64d5610f | 29177 | |
b71d4b62 | 29178 | @tab |
64d5610f | 29179 | |
b71d4b62 | 29180 | LINE TABULATION |
64d5610f | 29181 | |
b71d4b62 | 29182 | @item |
64d5610f | 29183 | |
b71d4b62 | 29184 | @code{\0} |
64d5610f | 29185 | |
b71d4b62 | 29186 | @tab |
64d5610f | 29187 | |
b71d4b62 | 29188 | NUL |
64d5610f | 29189 | |
b71d4b62 | 29190 | @item |
64d5610f | 29191 | |
b71d4b62 | 29192 | @code{\\} |
64d5610f | 29193 | |
b71d4b62 | 29194 | @tab |
64d5610f | 29195 | |
b71d4b62 | 29196 | @code{\} |
64d5610f | 29197 | |
b71d4b62 | 29198 | @item |
64d5610f | 29199 | |
b71d4b62 | 29200 | @code{\"} |
64d5610f | 29201 | |
b71d4b62 | 29202 | @tab |
64d5610f | 29203 | |
b71d4b62 | 29204 | @code{"} |
64d5610f | 29205 | |
b71d4b62 | 29206 | @item |
64d5610f | 29207 | |
b71d4b62 | 29208 | @code{\@{} |
64d5610f | 29209 | |
b71d4b62 | 29210 | @tab |
64d5610f | 29211 | |
b71d4b62 | 29212 | @code{@{} |
64d5610f | 29213 | |
b71d4b62 | 29214 | @item |
64d5610f | 29215 | |
b71d4b62 | 29216 | @code{\@}} |
64d5610f | 29217 | |
b71d4b62 | 29218 | @tab |
64d5610f | 29219 | |
b71d4b62 | 29220 | @code{@}} |
64d5610f | 29221 | |
b71d4b62 | 29222 | @end multitable |
64d5610f | 29223 | |
64d5610f | 29224 | |
b71d4b62 RA |
29225 | Note that, unlike normal string literals, doubled characters have no |
29226 | special significance. So to include a double-quote or a brace character | |
29227 | in an interpolated string, they must be preceded by a @code{\}. | |
29228 | For example: | |
64d5610f | 29229 | |
b71d4b62 RA |
29230 | @example |
29231 | Put_Line | |
29232 | (f"X = @{X@} and Y = @{Y@} and X+Y = @{X+Y@};\n" & | |
29233 | f" a double quote is \" and" & | |
29234 | f" an open brace is \@{"); | |
29235 | @end example | |
64d5610f | 29236 | |
b71d4b62 RA |
29237 | Finally, a syntax is provided for creating multi-line string literals, |
29238 | without having to explicitly use an escape sequence such as @code{\n}. For | |
29239 | example: | |
64d5610f | 29240 | |
b71d4b62 RA |
29241 | @example |
29242 | Put_Line | |
29243 | (f"This is a multi-line" | |
29244 | "string literal" | |
29245 | "There is no ambiguity about how many" | |
29246 | "spaces are included in each line"); | |
29247 | @end example | |
64d5610f | 29248 | |
b71d4b62 RA |
29249 | Here is a link to the original RFC : |
29250 | @indicateurl{https://github.com/AdaCore/ada-spark-rfcs/blob/master/prototyped/rfc-string-interpolation.rst} | |
64d5610f | 29251 | |
b71d4b62 | 29252 | @node Constrained attribute for generic objects,Static aspect on intrinsic functions,String interpolation,Curated Extensions |
9daee425 | 29253 | @anchor{gnat_rm/gnat_language_extensions constrained-attribute-for-generic-objects}@anchor{443} |
b71d4b62 | 29254 | @subsection Constrained attribute for generic objects |
64d5610f ML |
29255 | |
29256 | ||
b71d4b62 RA |
29257 | The @code{Constrained} attribute is permitted for objects of generic types. The |
29258 | result indicates whether the corresponding actual is constrained. | |
64d5610f | 29259 | |
b71d4b62 | 29260 | @node Static aspect on intrinsic functions,,Constrained attribute for generic objects,Curated Extensions |
9daee425 | 29261 | @anchor{gnat_rm/gnat_language_extensions static-aspect-on-intrinsic-functions}@anchor{444} |
b71d4b62 | 29262 | @subsection @code{Static} aspect on intrinsic functions |
64d5610f | 29263 | |
64d5610f | 29264 | |
b71d4b62 RA |
29265 | The Ada 202x @code{Static} aspect can be specified on Intrinsic imported functions |
29266 | and the compiler will evaluate some of these intrinsics statically, in | |
29267 | particular the @code{Shift_Left} and @code{Shift_Right} intrinsics. | |
64d5610f | 29268 | |
b71d4b62 | 29269 | @node Experimental Language Extensions,,Curated Extensions,GNAT language extensions |
9daee425 | 29270 | @anchor{gnat_rm/gnat_language_extensions experimental-language-extensions}@anchor{67}@anchor{gnat_rm/gnat_language_extensions id2}@anchor{445} |
b71d4b62 | 29271 | @section Experimental Language Extensions |
64d5610f ML |
29272 | |
29273 | ||
b71d4b62 RA |
29274 | @menu |
29275 | * Pragma Storage_Model:: | |
29276 | * Simpler accessibility model:: | |
64d5610f | 29277 | |
b71d4b62 | 29278 | @end menu |
64d5610f | 29279 | |
b71d4b62 | 29280 | @node Pragma Storage_Model,Simpler accessibility model,,Experimental Language Extensions |
9daee425 | 29281 | @anchor{gnat_rm/gnat_language_extensions pragma-storage-model}@anchor{446} |
b71d4b62 | 29282 | @subsection Pragma Storage_Model |
64d5610f | 29283 | |
64d5610f | 29284 | |
b71d4b62 RA |
29285 | This feature proposes to redesign the concepts of Storage Pools into a more |
29286 | efficient model allowing higher performances and easier integration with low | |
29287 | footprint embedded run-times. | |
64d5610f | 29288 | |
b71d4b62 RA |
29289 | It also extends it to support distributed memory models, in particular to |
29290 | support interactions with GPU. | |
64d5610f | 29291 | |
b71d4b62 RA |
29292 | Here is a link to the full RFC: |
29293 | @indicateurl{https://github.com/AdaCore/ada-spark-rfcs/blob/master/prototyped/rfc-storage-model.rst} | |
64d5610f | 29294 | |
b71d4b62 | 29295 | @node Simpler accessibility model,,Pragma Storage_Model,Experimental Language Extensions |
9daee425 | 29296 | @anchor{gnat_rm/gnat_language_extensions simpler-accessibility-model}@anchor{447} |
b71d4b62 | 29297 | @subsection Simpler accessibility model |
64d5610f | 29298 | |
64d5610f | 29299 | |
b71d4b62 RA |
29300 | The goal of this feature is to restore a common understanding of accessibility |
29301 | rules for implementers and users alike. The new rules should both be effective | |
29302 | at preventing errors and feel natural and compatible in an Ada environment | |
29303 | while removing dynamic accessibility checking. | |
29304 | ||
29305 | Here is a link to the full RFC: | |
29306 | @indicateurl{https://github.com/AdaCore/ada-spark-rfcs/blob/master/prototyped/rfc-simpler-accessibility.md} | |
64d5610f | 29307 | |
b71d4b62 | 29308 | @node Security Hardening Features,Obsolescent Features,GNAT language extensions,Top |
9daee425 | 29309 | @anchor{gnat_rm/security_hardening_features doc}@anchor{448}@anchor{gnat_rm/security_hardening_features id1}@anchor{449}@anchor{gnat_rm/security_hardening_features security-hardening-features}@anchor{15} |
64d5610f ML |
29310 | @chapter Security Hardening Features |
29311 | ||
29312 | ||
29313 | This chapter describes Ada extensions aimed at security hardening that | |
29314 | are provided by GNAT. | |
29315 | ||
29316 | The features in this chapter are currently experimental and subject to | |
29317 | change. | |
29318 | ||
29319 | @c Register Scrubbing: | |
29320 | ||
29321 | @menu | |
29322 | * Register Scrubbing:: | |
29323 | * Stack Scrubbing:: | |
29324 | * Hardened Conditionals:: | |
29325 | * Hardened Booleans:: | |
29326 | * Control Flow Redundancy:: | |
29327 | ||
29328 | @end menu | |
29329 | ||
29330 | @node Register Scrubbing,Stack Scrubbing,,Security Hardening Features | |
9daee425 | 29331 | @anchor{gnat_rm/security_hardening_features register-scrubbing}@anchor{44a} |
64d5610f ML |
29332 | @section Register Scrubbing |
29333 | ||
29334 | ||
29335 | GNAT can generate code to zero-out hardware registers before returning | |
29336 | from a subprogram. | |
29337 | ||
1acce141 | 29338 | It can be enabled with the @code{-fzero-call-used-regs=@emph{choice}} |
64d5610f ML |
29339 | command-line option, to affect all subprograms in a compilation, and |
29340 | with a @code{Machine_Attribute} pragma, to affect only specific | |
29341 | subprograms. | |
29342 | ||
29343 | @example | |
29344 | procedure Foo; | |
29345 | pragma Machine_Attribute (Foo, "zero_call_used_regs", "used"); | |
29346 | -- Before returning, Foo scrubs only call-clobbered registers | |
29347 | -- that it uses itself. | |
29348 | ||
29349 | function Bar return Integer; | |
29350 | pragma Machine_Attribute (Bar, "zero_call_used_regs", "all"); | |
29351 | -- Before returning, Bar scrubs all call-clobbered registers. | |
92eeb32d AO |
29352 | |
29353 | function Baz return Integer; | |
29354 | pragma Machine_Attribute (Bar, "zero_call_used_regs", "leafy"); | |
29355 | -- Before returning, Bar scrubs call-clobbered registers, either | |
29356 | -- those it uses itself, if it can be identified as a leaf | |
29357 | -- function, or all of them otherwise. | |
64d5610f ML |
29358 | @end example |
29359 | ||
29360 | For usage and more details on the command-line option, on the | |
29361 | @code{zero_call_used_regs} attribute, and on their use with other | |
29362 | programming languages, see @cite{Using the GNU Compiler Collection (GCC)}. | |
29363 | ||
29364 | @c Stack Scrubbing: | |
29365 | ||
29366 | @node Stack Scrubbing,Hardened Conditionals,Register Scrubbing,Security Hardening Features | |
9daee425 | 29367 | @anchor{gnat_rm/security_hardening_features stack-scrubbing}@anchor{44b} |
64d5610f ML |
29368 | @section Stack Scrubbing |
29369 | ||
29370 | ||
29371 | GNAT can generate code to zero-out stack frames used by subprograms. | |
29372 | ||
29373 | It can be activated with the @code{Machine_Attribute} pragma, on | |
29374 | specific subprograms and variables, or their types. (This attribute | |
29375 | always applies to a type, even when it is associated with a subprogram | |
29376 | or a variable.) | |
29377 | ||
29378 | @example | |
29379 | function Foo returns Integer; | |
29380 | pragma Machine_Attribute (Foo, "strub"); | |
29381 | -- Foo and its callers are modified so as to scrub the stack | |
29382 | -- space used by Foo after it returns. Shorthand for: | |
29383 | -- pragma Machine_Attribute (Foo, "strub", "at-calls"); | |
29384 | ||
29385 | procedure Bar; | |
29386 | pragma Machine_Attribute (Bar, "strub", "internal"); | |
29387 | -- Bar is turned into a wrapper for its original body, | |
29388 | -- and they scrub the stack used by the original body. | |
29389 | ||
29390 | Var : Integer; | |
29391 | pragma Machine_Attribute (Var, "strub"); | |
29392 | -- Reading from Var in a subprogram enables stack scrubbing | |
29393 | -- of the stack space used by the subprogram. Furthermore, if | |
29394 | -- Var is declared within a subprogram, this also enables | |
29395 | -- scrubbing of the stack space used by that subprogram. | |
29396 | @end example | |
29397 | ||
29398 | Given these declarations, Foo has its type and body modified as | |
29399 | follows: | |
29400 | ||
29401 | @example | |
29402 | function Foo (<WaterMark> : in out System.Address) returns Integer | |
29403 | is | |
29404 | -- ... | |
29405 | begin | |
29406 | <__strub_update> (<WaterMark>); -- Updates the stack WaterMark. | |
29407 | -- ... | |
29408 | end; | |
29409 | @end example | |
29410 | ||
29411 | whereas its callers are modified from: | |
29412 | ||
29413 | @example | |
29414 | X := Foo; | |
29415 | @end example | |
29416 | ||
29417 | to: | |
29418 | ||
29419 | @example | |
29420 | declare | |
29421 | <WaterMark> : System.Address; | |
29422 | begin | |
29423 | <__strub_enter> (<WaterMark>); -- Initialize <WaterMark>. | |
29424 | X := Foo (<WaterMark>); | |
29425 | <__strub_leave> (<WaterMark>); -- Scrubs stack up to <WaterMark>. | |
29426 | end; | |
29427 | @end example | |
29428 | ||
29429 | As for Bar, because it is strubbed in internal mode, its callers are | |
29430 | not modified. Its definition is modified roughly as follows: | |
29431 | ||
29432 | @example | |
29433 | procedure Bar is | |
29434 | <WaterMark> : System.Address; | |
29435 | procedure Strubbed_Bar (<WaterMark> : in out System.Address) is | |
29436 | begin | |
29437 | <__strub_update> (<WaterMark>); -- Updates the stack WaterMark. | |
29438 | -- original Bar body. | |
29439 | end Strubbed_Bar; | |
29440 | begin | |
29441 | <__strub_enter> (<WaterMark>); -- Initialize <WaterMark>. | |
29442 | Strubbed_Bar (<WaterMark>); | |
29443 | <__strub_leave> (<WaterMark>); -- Scrubs stack up to <WaterMark>. | |
29444 | end Bar; | |
29445 | @end example | |
29446 | ||
1acce141 | 29447 | There are also @code{-fstrub=@emph{choice}} command-line options to |
64d5610f ML |
29448 | control default settings. For usage and more details on the |
29449 | command-line options, on the @code{strub} attribute, and their use with | |
29450 | other programming languages, see @cite{Using the GNU Compiler Collection (GCC)}. | |
29451 | ||
29452 | Note that Ada secondary stacks are not scrubbed. The restriction | |
29453 | @code{No_Secondary_Stack} avoids their use, and thus their accidental | |
29454 | preservation of data that should be scrubbed. | |
29455 | ||
29456 | Attributes @code{Access} and @code{Unconstrained_Access} of variables and | |
29457 | constants with @code{strub} enabled require types with @code{strub} enabled; | |
29458 | there is no way to express an access-to-strub type otherwise. | |
29459 | @code{Unchecked_Access} bypasses this constraint, but the resulting | |
29460 | access type designates a non-strub type. | |
29461 | ||
29462 | @example | |
29463 | VI : aliased Integer; | |
29464 | pragma Machine_Attribute (VI, "strub"); | |
29465 | XsVI : access Integer := VI'Access; -- Error. | |
29466 | UXsVI : access Integer := VI'Unchecked_Access; -- OK, | |
29467 | -- UXsVI does *not* enable strub in subprograms that | |
29468 | -- dereference it to obtain the UXsVI.all value. | |
29469 | ||
29470 | type Strub_Int is new Integer; | |
29471 | pragma Machine_Attribute (Strub_Int, "strub"); | |
29472 | VSI : aliased Strub_Int; | |
29473 | XsVSI : access Strub_Int := VSI'Access; -- OK, | |
29474 | -- VSI and XsVSI.all both enable strub in subprograms that | |
29475 | -- read their values. | |
29476 | @end example | |
29477 | ||
29478 | Every access-to-subprogram type, renaming, and overriding and | |
29479 | overridden dispatching operations that may refer to a subprogram with | |
29480 | an attribute-modified interface must be annotated with the same | |
29481 | interface-modifying attribute. Access-to-subprogram types can be | |
29482 | explicitly converted to different strub modes, as long as they are | |
29483 | interface-compatible (i.e., adding or removing @code{at-calls} is not | |
29484 | allowed). For example, a @code{strub}-@code{disabled} subprogram can be | |
29485 | turned @code{callable} through such an explicit conversion: | |
29486 | ||
29487 | @example | |
29488 | type TBar is access procedure; | |
29489 | ||
29490 | type TBar_Callable is access procedure; | |
29491 | pragma Machine_Attribute (TBar_Callable, "strub", "callable"); | |
29492 | -- The attribute modifies the procedure type, rather than the | |
29493 | -- access type, because of the extra argument after "strub", | |
29494 | -- only applicable to subprogram types. | |
29495 | ||
29496 | Bar_Callable_Ptr : constant TBar_Callable | |
29497 | := TBar_Callable (TBar'(Bar'Access)); | |
29498 | ||
29499 | procedure Bar_Callable renames Bar_Callable_Ptr.all; | |
29500 | pragma Machine_Attribute (Bar_Callable, "strub", "callable"); | |
29501 | @end example | |
29502 | ||
29503 | Note that the renaming declaration is expanded to a full subprogram | |
29504 | body, it won’t be just an alias. Only if it is inlined will it be as | |
29505 | efficient as a call by dereferencing the access-to-subprogram constant | |
29506 | Bar_Callable_Ptr. | |
29507 | ||
29508 | @c Hardened Conditionals: | |
29509 | ||
29510 | @node Hardened Conditionals,Hardened Booleans,Stack Scrubbing,Security Hardening Features | |
9daee425 | 29511 | @anchor{gnat_rm/security_hardening_features hardened-conditionals}@anchor{44c} |
64d5610f ML |
29512 | @section Hardened Conditionals |
29513 | ||
29514 | ||
29515 | GNAT can harden conditionals to protect against control-flow attacks. | |
29516 | ||
29517 | This is accomplished by two complementary transformations, each | |
29518 | activated by a separate command-line option. | |
29519 | ||
29520 | The option @code{-fharden-compares} enables hardening of compares | |
29521 | that compute results stored in variables, adding verification that the | |
29522 | reversed compare yields the opposite result, turning: | |
29523 | ||
29524 | @example | |
29525 | B := X = Y; | |
29526 | @end example | |
29527 | ||
29528 | into: | |
29529 | ||
29530 | @example | |
29531 | B := X = Y; | |
29532 | declare | |
29533 | NotB : Boolean := X /= Y; -- Computed independently of B. | |
29534 | begin | |
29535 | if B = NotB then | |
29536 | <__builtin_trap>; | |
29537 | end if; | |
29538 | end; | |
29539 | @end example | |
29540 | ||
29541 | The option @code{-fharden-conditional-branches} enables hardening | |
29542 | of compares that guard conditional branches, adding verification of | |
29543 | the reversed compare to both execution paths, turning: | |
29544 | ||
29545 | @example | |
29546 | if X = Y then | |
29547 | X := Z + 1; | |
29548 | else | |
29549 | Y := Z - 1; | |
29550 | end if; | |
29551 | @end example | |
29552 | ||
29553 | into: | |
29554 | ||
29555 | @example | |
29556 | if X = Y then | |
29557 | if X /= Y then -- Computed independently of X = Y. | |
29558 | <__builtin_trap>; | |
29559 | end if; | |
29560 | X := Z + 1; | |
29561 | else | |
29562 | if X /= Y then -- Computed independently of X = Y. | |
29563 | null; | |
29564 | else | |
29565 | <__builtin_trap>; | |
29566 | end if; | |
29567 | Y := Z - 1; | |
29568 | end if; | |
29569 | @end example | |
29570 | ||
29571 | These transformations are introduced late in the compilation pipeline, | |
29572 | long after boolean expressions are decomposed into separate compares, | |
29573 | each one turned into either a conditional branch or a compare whose | |
29574 | result is stored in a boolean variable or temporary. Compiler | |
29575 | optimizations, if enabled, may also turn conditional branches into | |
29576 | stored compares, and vice-versa, or into operations with implied | |
29577 | conditionals (e.g. MIN and MAX). Conditionals may also be optimized | |
29578 | out entirely, if their value can be determined at compile time, and | |
29579 | occasionally multiple compares can be combined into one. | |
29580 | ||
29581 | It is thus difficult to predict which of these two options will affect | |
29582 | a specific compare operation expressed in source code. Using both | |
29583 | options ensures that every compare that is neither optimized out nor | |
29584 | optimized into implied conditionals will be hardened. | |
29585 | ||
29586 | The addition of reversed compares can be observed by enabling the dump | |
29587 | files of the corresponding passes, through command-line options | |
29588 | @code{-fdump-tree-hardcmp} and @code{-fdump-tree-hardcbr}, | |
29589 | respectively. | |
29590 | ||
29591 | They are separate options, however, because of the significantly | |
29592 | different performance impact of the hardening transformations. | |
29593 | ||
29594 | For usage and more details on the command-line options, see | |
29595 | @cite{Using the GNU Compiler Collection (GCC)}. These options can | |
29596 | be used with other programming languages supported by GCC. | |
29597 | ||
29598 | @c Hardened Booleans: | |
29599 | ||
29600 | @node Hardened Booleans,Control Flow Redundancy,Hardened Conditionals,Security Hardening Features | |
9daee425 | 29601 | @anchor{gnat_rm/security_hardening_features hardened-booleans}@anchor{44d} |
64d5610f ML |
29602 | @section Hardened Booleans |
29603 | ||
29604 | ||
29605 | Ada has built-in support for introducing boolean types with | |
29606 | alternative representations, using representation clauses: | |
29607 | ||
29608 | @example | |
29609 | type HBool is new Boolean; | |
29610 | for HBool use (16#5a#, 16#a5#); | |
29611 | for HBool'Size use 8; | |
29612 | @end example | |
29613 | ||
29614 | When validity checking is enabled, the compiler will check that | |
29615 | variables of such types hold values corresponding to the selected | |
29616 | representations. | |
29617 | ||
29618 | There are multiple strategies for where to introduce validity checking | |
29619 | (see @code{-gnatV} options). Their goal is to guard against | |
29620 | various kinds of programming errors, and GNAT strives to omit checks | |
29621 | when program logic rules out an invalid value, and optimizers may | |
29622 | further remove checks found to be redundant. | |
29623 | ||
29624 | For additional hardening, the @code{hardbool} @code{Machine_Attribute} | |
29625 | pragma can be used to annotate boolean types with representation | |
29626 | clauses, so that expressions of such types used as conditions are | |
29627 | checked even when compiling with @code{-gnatVT}: | |
29628 | ||
29629 | @example | |
29630 | pragma Machine_Attribute (HBool, "hardbool"); | |
29631 | ||
29632 | function To_Boolean (X : HBool) returns Boolean is (Boolean (X)); | |
29633 | @end example | |
29634 | ||
29635 | is compiled roughly like: | |
29636 | ||
29637 | @example | |
29638 | function To_Boolean (X : HBool) returns Boolean is | |
29639 | begin | |
29640 | if X not in True | False then | |
29641 | raise Constraint_Error; | |
29642 | elsif X in True then | |
29643 | return True; | |
29644 | else | |
29645 | return False; | |
29646 | end if; | |
29647 | end To_Boolean; | |
29648 | @end example | |
29649 | ||
29650 | Note that @code{-gnatVn} will disable even @code{hardbool} testing. | |
29651 | ||
29652 | Analogous behavior is available as a GCC extension to the C and | |
29653 | Objective C programming languages, through the @code{hardbool} attribute, | |
29654 | with the difference that, instead of raising a Constraint_Error | |
29655 | exception, when a hardened boolean variable is found to hold a value | |
29656 | that stands for neither True nor False, the program traps. For usage | |
29657 | and more details on that attribute, see @cite{Using the GNU Compiler Collection (GCC)}. | |
29658 | ||
29659 | @c Control Flow Redundancy: | |
29660 | ||
29661 | @node Control Flow Redundancy,,Hardened Booleans,Security Hardening Features | |
9daee425 | 29662 | @anchor{gnat_rm/security_hardening_features control-flow-redundancy}@anchor{44e} |
64d5610f ML |
29663 | @section Control Flow Redundancy |
29664 | ||
29665 | ||
29666 | GNAT can guard against unexpected execution flows, such as branching | |
29667 | into the middle of subprograms, as in Return Oriented Programming | |
29668 | exploits. | |
29669 | ||
29670 | In units compiled with @code{-fharden-control-flow-redundancy}, | |
29671 | subprograms are instrumented so that, every time they are called, | |
29672 | basic blocks take note as control flows through them, and, before | |
29673 | returning, subprograms verify that the taken notes are consistent with | |
29674 | the control-flow graph. | |
29675 | ||
d4d6eda9 AO |
29676 | The performance impact of verification on leaf subprograms can be much |
29677 | higher, while the averted risks are much lower on them. | |
29678 | Instrumentation can be disabled for leaf subprograms with | |
29679 | @code{-fhardcfr-skip-leaf}. | |
29680 | ||
64d5610f ML |
29681 | Functions with too many basic blocks, or with multiple return points, |
29682 | call a run-time function to perform the verification. Other functions | |
29683 | perform the verification inline before returning. | |
29684 | ||
29685 | Optimizing the inlined verification can be quite time consuming, so | |
29686 | the default upper limit for the inline mode is set at 16 blocks. | |
29687 | Command-line option @code{--param hardcfr-max-inline-blocks=} can | |
29688 | override it. | |
29689 | ||
29690 | Even though typically sparse control-flow graphs exhibit run-time | |
29691 | verification time nearly proportional to the block count of a | |
29692 | subprogram, it may become very significant for generated subprograms | |
29693 | with thousands of blocks. Command-line option | |
29694 | @code{--param hardcfr-max-blocks=} can set an upper limit for | |
29695 | instrumentation. | |
29696 | ||
29697 | For each block that is marked as visited, the mechanism checks that at | |
29698 | least one of its predecessors, and at least one of its successors, are | |
29699 | also marked as visited. | |
29700 | ||
f3597ba6 AO |
29701 | Verification is performed just before a subprogram returns. The |
29702 | following fragment: | |
29703 | ||
29704 | @example | |
29705 | if X then | |
29706 | Y := F (Z); | |
29707 | return; | |
29708 | end if; | |
29709 | @end example | |
29710 | ||
29711 | gets turned into: | |
29712 | ||
29713 | @example | |
29714 | type Visited_Bitmap is array (1..N) of Boolean with Pack; | |
29715 | Visited : aliased Visited_Bitmap := (others => False); | |
29716 | -- Bitmap of visited blocks. N is the basic block count. | |
29717 | [...] | |
29718 | -- Basic block #I | |
29719 | Visited(I) := True; | |
29720 | if X then | |
29721 | -- Basic block #J | |
29722 | Visited(J) := True; | |
29723 | Y := F (Z); | |
29724 | CFR.Check (N, Visited'Access, CFG'Access); | |
29725 | -- CFR is a hypothetical package whose Check procedure calls | |
29726 | -- libgcc's __hardcfr_check, that traps if the Visited bitmap | |
29727 | -- does not hold a valid path in CFG, the run-time | |
29728 | -- representation of the control flow graph in the enclosing | |
29729 | -- subprogram. | |
29730 | return; | |
29731 | end if; | |
29732 | -- Basic block #K | |
29733 | Visited(K) := True; | |
29734 | @end example | |
29735 | ||
29736 | Verification would also be performed before tail calls, if any | |
29737 | front-ends marked them as mandatory or desirable, but none do. | |
29738 | Regular calls are optimized into tail calls too late for this | |
29739 | transformation to act on it. | |
29740 | ||
29741 | In order to avoid adding verification after potential tail calls, | |
29742 | which would prevent tail-call optimization, we recognize returning | |
29743 | calls, i.e., calls whose result, if any, is returned by the calling | |
29744 | subprogram to its caller immediately after the call returns. | |
29745 | Verification is performed before such calls, whether or not they are | |
29746 | ultimately optimized to tail calls. This behavior is enabled by | |
29747 | default whenever sibcall optimization is enabled (see | |
29748 | @code{-foptimize-sibling-calls}); it may be disabled with | |
29749 | @code{-fno-hardcfr-check-returning-calls}, or enabled with | |
29750 | @code{-fhardcfr-check-returning-calls}, regardless of the | |
29751 | optimization, but the lack of other optimizations may prevent calls | |
29752 | from being recognized as returning calls: | |
29753 | ||
29754 | @example | |
29755 | -- CFR.Check here, with -fhardcfr-check-returning-calls. | |
29756 | P (X); | |
29757 | -- CFR.Check here, with -fno-hardcfr-check-returning-calls. | |
29758 | return; | |
29759 | @end example | |
29760 | ||
29761 | or: | |
29762 | ||
29763 | @example | |
29764 | -- CFR.Check here, with -fhardcfr-check-returning-calls. | |
29765 | R := F (X); | |
29766 | -- CFR.Check here, with -fno-hardcfr-check-returning-calls. | |
29767 | return R; | |
29768 | @end example | |
29769 | ||
29770 | Any subprogram from which an exception may escape, i.e., that may | |
29771 | raise or propagate an exception that isn’t handled internally, is | |
29772 | conceptually enclosed by a cleanup handler that performs verification, | |
29773 | unless this is disabled with @code{-fno-hardcfr-check-exceptions}. | |
29774 | With this feature enabled, a subprogram body containing: | |
29775 | ||
29776 | @example | |
29777 | -- ... | |
29778 | Y := F (X); -- May raise exceptions. | |
29779 | -- ... | |
29780 | raise E; -- Not handled internally. | |
29781 | -- ... | |
29782 | @end example | |
29783 | ||
29784 | gets modified as follows: | |
29785 | ||
29786 | @example | |
29787 | begin | |
29788 | -- ... | |
29789 | Y := F (X); -- May raise exceptions. | |
29790 | -- ... | |
29791 | raise E; -- Not handled internally. | |
29792 | -- ... | |
29793 | exception | |
29794 | when others => | |
29795 | CFR.Check (N, Visited'Access, CFG'Access); | |
29796 | raise; | |
29797 | end; | |
29798 | @end example | |
29799 | ||
61736805 AO |
29800 | Verification may also be performed before No_Return calls, whether all |
29801 | of them, with @code{-fhardcfr-check-noreturn-calls=always}; all but | |
79cc2a75 AO |
29802 | internal subprograms involved in exception-raising or -reraising or |
29803 | subprograms explicitly marked with both @code{No_Return} and | |
29804 | @code{Machine_Attribute} @code{expected_throw} pragmas, with | |
61736805 AO |
29805 | @code{-fhardcfr-check-noreturn-calls=no-xthrow} (default); only |
29806 | nothrow ones, with @code{-fhardcfr-check-noreturn-calls=nothrow}; | |
29807 | or none, with @code{-fhardcfr-check-noreturn-calls=never}. | |
f3597ba6 AO |
29808 | |
29809 | When a No_Return call returns control to its caller through an | |
29810 | exception, verification may have already been performed before the | |
61736805 AO |
29811 | call, if @code{-fhardcfr-check-noreturn-calls=always} or |
29812 | @code{-fhardcfr-check-noreturn-calls=no-xthrow} is in effect. The | |
29813 | compiler arranges for already-checked No_Return calls without a | |
f3597ba6 AO |
29814 | preexisting handler to bypass the implicitly-added cleanup handler and |
29815 | thus the redundant check, but a local exception or cleanup handler, if | |
29816 | present, will modify the set of visited blocks, and checking will take | |
29817 | place again when the caller reaches the next verification point, | |
29818 | whether it is a return or reraise statement after the exception is | |
29819 | otherwise handled, or even another No_Return call. | |
64d5610f ML |
29820 | |
29821 | The instrumentation for hardening with control flow redundancy can be | |
29822 | observed in dump files generated by the command-line option | |
29823 | @code{-fdump-tree-hardcfr}. | |
29824 | ||
29825 | For more details on the control flow redundancy command-line options, | |
29826 | see @cite{Using the GNU Compiler Collection (GCC)}. These options | |
29827 | can be used with other programming languages supported by GCC. | |
29828 | ||
29829 | @node Obsolescent Features,Compatibility and Porting Guide,Security Hardening Features,Top | |
9daee425 | 29830 | @anchor{gnat_rm/obsolescent_features doc}@anchor{44f}@anchor{gnat_rm/obsolescent_features id1}@anchor{450}@anchor{gnat_rm/obsolescent_features obsolescent-features}@anchor{16} |
64d5610f ML |
29831 | @chapter Obsolescent Features |
29832 | ||
29833 | ||
29834 | This chapter describes features that are provided by GNAT, but are | |
29835 | considered obsolescent since there are preferred ways of achieving | |
29836 | the same effect. These features are provided solely for historical | |
29837 | compatibility purposes. | |
29838 | ||
29839 | @menu | |
29840 | * pragma No_Run_Time:: | |
29841 | * pragma Ravenscar:: | |
29842 | * pragma Restricted_Run_Time:: | |
29843 | * pragma Task_Info:: | |
29844 | * package System.Task_Info (s-tasinf.ads): package System Task_Info s-tasinf ads. | |
29845 | ||
29846 | @end menu | |
29847 | ||
29848 | @node pragma No_Run_Time,pragma Ravenscar,,Obsolescent Features | |
9daee425 | 29849 | @anchor{gnat_rm/obsolescent_features id2}@anchor{451}@anchor{gnat_rm/obsolescent_features pragma-no-run-time}@anchor{452} |
64d5610f ML |
29850 | @section pragma No_Run_Time |
29851 | ||
29852 | ||
29853 | The pragma @code{No_Run_Time} is used to achieve an affect similar | |
29854 | to the use of the “Zero Foot Print” configurable run time, but without | |
29855 | requiring a specially configured run time. The result of using this | |
29856 | pragma, which must be used for all units in a partition, is to restrict | |
29857 | the use of any language features requiring run-time support code. The | |
29858 | preferred usage is to use an appropriately configured run-time that | |
29859 | includes just those features that are to be made accessible. | |
29860 | ||
29861 | @node pragma Ravenscar,pragma Restricted_Run_Time,pragma No_Run_Time,Obsolescent Features | |
9daee425 | 29862 | @anchor{gnat_rm/obsolescent_features id3}@anchor{453}@anchor{gnat_rm/obsolescent_features pragma-ravenscar}@anchor{454} |
64d5610f ML |
29863 | @section pragma Ravenscar |
29864 | ||
29865 | ||
29866 | The pragma @code{Ravenscar} has exactly the same effect as pragma | |
29867 | @code{Profile (Ravenscar)}. The latter usage is preferred since it | |
29868 | is part of the new Ada 2005 standard. | |
29869 | ||
29870 | @node pragma Restricted_Run_Time,pragma Task_Info,pragma Ravenscar,Obsolescent Features | |
9daee425 | 29871 | @anchor{gnat_rm/obsolescent_features id4}@anchor{455}@anchor{gnat_rm/obsolescent_features pragma-restricted-run-time}@anchor{456} |
64d5610f ML |
29872 | @section pragma Restricted_Run_Time |
29873 | ||
29874 | ||
29875 | The pragma @code{Restricted_Run_Time} has exactly the same effect as | |
29876 | pragma @code{Profile (Restricted)}. The latter usage is | |
29877 | preferred since the Ada 2005 pragma @code{Profile} is intended for | |
29878 | this kind of implementation dependent addition. | |
29879 | ||
29880 | @node pragma Task_Info,package System Task_Info s-tasinf ads,pragma Restricted_Run_Time,Obsolescent Features | |
9daee425 | 29881 | @anchor{gnat_rm/obsolescent_features id5}@anchor{457}@anchor{gnat_rm/obsolescent_features pragma-task-info}@anchor{458} |
64d5610f ML |
29882 | @section pragma Task_Info |
29883 | ||
29884 | ||
29885 | The functionality provided by pragma @code{Task_Info} is now part of the | |
29886 | Ada language. The @code{CPU} aspect and the package | |
29887 | @code{System.Multiprocessors} offer a less system-dependent way to specify | |
29888 | task affinity or to query the number of processors. | |
29889 | ||
29890 | Syntax | |
29891 | ||
29892 | @example | |
29893 | pragma Task_Info (EXPRESSION); | |
29894 | @end example | |
29895 | ||
29896 | This pragma appears within a task definition (like pragma | |
29897 | @code{Priority}) and applies to the task in which it appears. The | |
29898 | argument must be of type @code{System.Task_Info.Task_Info_Type}. | |
29899 | The @code{Task_Info} pragma provides system dependent control over | |
29900 | aspects of tasking implementation, for example, the ability to map | |
29901 | tasks to specific processors. For details on the facilities available | |
29902 | for the version of GNAT that you are using, see the documentation | |
29903 | in the spec of package System.Task_Info in the runtime | |
29904 | library. | |
29905 | ||
29906 | @node package System Task_Info s-tasinf ads,,pragma Task_Info,Obsolescent Features | |
9daee425 | 29907 | @anchor{gnat_rm/obsolescent_features package-system-task-info}@anchor{459}@anchor{gnat_rm/obsolescent_features package-system-task-info-s-tasinf-ads}@anchor{45a} |
64d5610f ML |
29908 | @section package System.Task_Info (@code{s-tasinf.ads}) |
29909 | ||
29910 | ||
29911 | This package provides target dependent functionality that is used | |
29912 | to support the @code{Task_Info} pragma. The predefined Ada package | |
29913 | @code{System.Multiprocessors} and the @code{CPU} aspect now provide a | |
29914 | standard replacement for GNAT’s @code{Task_Info} functionality. | |
29915 | ||
29916 | @node Compatibility and Porting Guide,GNU Free Documentation License,Obsolescent Features,Top | |
9daee425 | 29917 | @anchor{gnat_rm/compatibility_and_porting_guide doc}@anchor{45b}@anchor{gnat_rm/compatibility_and_porting_guide compatibility-and-porting-guide}@anchor{17}@anchor{gnat_rm/compatibility_and_porting_guide id1}@anchor{45c} |
64d5610f ML |
29918 | @chapter Compatibility and Porting Guide |
29919 | ||
29920 | ||
29921 | This chapter presents some guidelines for developing portable Ada code, | |
29922 | describes the compatibility issues that may arise between | |
29923 | GNAT and other Ada compilation systems (including those for Ada 83), | |
29924 | and shows how GNAT can expedite porting | |
29925 | applications developed in other Ada environments. | |
29926 | ||
29927 | @menu | |
29928 | * Writing Portable Fixed-Point Declarations:: | |
29929 | * Compatibility with Ada 83:: | |
29930 | * Compatibility between Ada 95 and Ada 2005:: | |
29931 | * Implementation-dependent characteristics:: | |
29932 | * Compatibility with Other Ada Systems:: | |
29933 | * Representation Clauses:: | |
29934 | * Compatibility with HP Ada 83:: | |
29935 | ||
29936 | @end menu | |
29937 | ||
29938 | @node Writing Portable Fixed-Point Declarations,Compatibility with Ada 83,,Compatibility and Porting Guide | |
9daee425 | 29939 | @anchor{gnat_rm/compatibility_and_porting_guide id2}@anchor{45d}@anchor{gnat_rm/compatibility_and_porting_guide writing-portable-fixed-point-declarations}@anchor{45e} |
64d5610f ML |
29940 | @section Writing Portable Fixed-Point Declarations |
29941 | ||
29942 | ||
29943 | The Ada Reference Manual gives an implementation freedom to choose bounds | |
29944 | that are narrower by @code{Small} from the given bounds. | |
29945 | For example, if we write | |
29946 | ||
29947 | @example | |
29948 | type F1 is delta 1.0 range -128.0 .. +128.0; | |
29949 | @end example | |
29950 | ||
29951 | then the implementation is allowed to choose -128.0 .. +127.0 if it | |
29952 | likes, but is not required to do so. | |
29953 | ||
29954 | This leads to possible portability problems, so let’s have a closer | |
29955 | look at this, and figure out how to avoid these problems. | |
29956 | ||
29957 | First, why does this freedom exist, and why would an implementation | |
29958 | take advantage of it? To answer this, take a closer look at the type | |
29959 | declaration for @code{F1} above. If the compiler uses the given bounds, | |
29960 | it would need 9 bits to hold the largest positive value (and typically | |
29961 | that means 16 bits on all machines). But if the implementation chooses | |
29962 | the +127.0 bound then it can fit values of the type in 8 bits. | |
29963 | ||
29964 | Why not make the user write +127.0 if that’s what is wanted? | |
29965 | The rationale is that if you are thinking of fixed point | |
29966 | as a kind of ‘poor man’s floating-point’, then you don’t want | |
29967 | to be thinking about the scaled integers that are used in its | |
29968 | representation. Let’s take another example: | |
29969 | ||
29970 | @example | |
29971 | type F2 is delta 2.0**(-15) range -1.0 .. +1.0; | |
29972 | @end example | |
29973 | ||
29974 | Looking at this declaration, it seems casually as though | |
29975 | it should fit in 16 bits, but again that extra positive value | |
29976 | +1.0 has the scaled integer equivalent of 2**15 which is one too | |
29977 | big for signed 16 bits. The implementation can treat this as: | |
29978 | ||
29979 | @example | |
29980 | type F2 is delta 2.0**(-15) range -1.0 .. +1.0-(2.0**(-15)); | |
29981 | @end example | |
29982 | ||
29983 | and the Ada language design team felt that this was too annoying | |
29984 | to require. We don’t need to debate this decision at this point, | |
29985 | since it is well established (the rule about narrowing the ranges | |
29986 | dates to Ada 83). | |
29987 | ||
29988 | But the important point is that an implementation is not required | |
29989 | to do this narrowing, so we have a potential portability problem. | |
29990 | We could imagine three types of implementation: | |
29991 | ||
29992 | ||
29993 | @enumerate a | |
29994 | ||
29995 | @item | |
29996 | those that narrow the range automatically if they can figure | |
29997 | out that the narrower range will allow storage in a smaller machine unit, | |
29998 | ||
29999 | @item | |
30000 | those that will narrow only if forced to by a @code{'Size} clause, and | |
30001 | ||
30002 | @item | |
30003 | those that will never narrow. | |
30004 | @end enumerate | |
30005 | ||
30006 | Now if we are language theoreticians, we can imagine a fourth | |
30007 | approach: to narrow all the time, e.g. to treat | |
30008 | ||
30009 | @example | |
30010 | type F3 is delta 1.0 range -10.0 .. +23.0; | |
30011 | @end example | |
30012 | ||
30013 | as though it had been written: | |
30014 | ||
30015 | @example | |
30016 | type F3 is delta 1.0 range -9.0 .. +22.0; | |
30017 | @end example | |
30018 | ||
30019 | But although technically allowed, such a behavior would be hostile and silly, | |
30020 | and no real compiler would do this. All real compilers will fall into one of | |
30021 | the categories (a), (b) or (c) above. | |
30022 | ||
30023 | So, how do you get the compiler to do what you want? The answer is give the | |
30024 | actual bounds you want, and then use a @code{'Small} clause and a | |
30025 | @code{'Size} clause to absolutely pin down what the compiler does. | |
30026 | E.g., for @code{F2} above, we will write: | |
30027 | ||
30028 | @example | |
30029 | My_Small : constant := 2.0**(-15); | |
30030 | My_First : constant := -1.0; | |
30031 | My_Last : constant := +1.0 - My_Small; | |
30032 | ||
30033 | type F2 is delta My_Small range My_First .. My_Last; | |
30034 | @end example | |
30035 | ||
30036 | and then add | |
30037 | ||
30038 | @example | |
30039 | for F2'Small use my_Small; | |
30040 | for F2'Size use 16; | |
30041 | @end example | |
30042 | ||
30043 | In practice all compilers will do the same thing here and will give you | |
30044 | what you want, so the above declarations are fully portable. If you really | |
30045 | want to play language lawyer and guard against ludicrous behavior by the | |
30046 | compiler you could add | |
30047 | ||
30048 | @example | |
30049 | Test1 : constant := 1 / Boolean'Pos (F2'First = My_First); | |
30050 | Test2 : constant := 1 / Boolean'Pos (F2'Last = My_Last); | |
30051 | @end example | |
30052 | ||
30053 | One or other or both are allowed to be illegal if the compiler is | |
30054 | behaving in a silly manner, but at least the silly compiler will not | |
30055 | get away with silently messing with your (very clear) intentions. | |
30056 | ||
30057 | If you follow this scheme you will be guaranteed that your fixed-point | |
30058 | types will be portable. | |
30059 | ||
30060 | @node Compatibility with Ada 83,Compatibility between Ada 95 and Ada 2005,Writing Portable Fixed-Point Declarations,Compatibility and Porting Guide | |
9daee425 | 30061 | @anchor{gnat_rm/compatibility_and_porting_guide compatibility-with-ada-83}@anchor{45f}@anchor{gnat_rm/compatibility_and_porting_guide id3}@anchor{460} |
64d5610f ML |
30062 | @section Compatibility with Ada 83 |
30063 | ||
30064 | ||
30065 | @geindex Compatibility (between Ada 83 and Ada 95 / Ada 2005 / Ada 2012) | |
30066 | ||
30067 | Ada 95 and the subsequent revisions Ada 2005 and Ada 2012 | |
30068 | are highly upwards compatible with Ada 83. In | |
30069 | particular, the design intention was that the difficulties associated | |
30070 | with moving from Ada 83 to later versions of the standard should be no greater | |
30071 | than those that occur when moving from one Ada 83 system to another. | |
30072 | ||
30073 | However, there are a number of points at which there are minor | |
30074 | incompatibilities. The @cite{Ada 95 Annotated Reference Manual} contains | |
30075 | full details of these issues as they relate to Ada 95, | |
30076 | and should be consulted for a complete treatment. | |
30077 | In practice the | |
30078 | following subsections treat the most likely issues to be encountered. | |
30079 | ||
30080 | @menu | |
30081 | * Legal Ada 83 programs that are illegal in Ada 95:: | |
30082 | * More deterministic semantics:: | |
30083 | * Changed semantics:: | |
30084 | * Other language compatibility issues:: | |
30085 | ||
30086 | @end menu | |
30087 | ||
30088 | @node Legal Ada 83 programs that are illegal in Ada 95,More deterministic semantics,,Compatibility with Ada 83 | |
9daee425 | 30089 | @anchor{gnat_rm/compatibility_and_porting_guide id4}@anchor{461}@anchor{gnat_rm/compatibility_and_porting_guide legal-ada-83-programs-that-are-illegal-in-ada-95}@anchor{462} |
64d5610f ML |
30090 | @subsection Legal Ada 83 programs that are illegal in Ada 95 |
30091 | ||
30092 | ||
30093 | Some legal Ada 83 programs are illegal (i.e., they will fail to compile) in | |
30094 | Ada 95 and later versions of the standard: | |
30095 | ||
30096 | ||
30097 | @itemize * | |
30098 | ||
30099 | @item | |
1acce141 | 30100 | @emph{Character literals} |
64d5610f ML |
30101 | |
30102 | Some uses of character literals are ambiguous. Since Ada 95 has introduced | |
30103 | @code{Wide_Character} as a new predefined character type, some uses of | |
30104 | character literals that were legal in Ada 83 are illegal in Ada 95. | |
30105 | For example: | |
30106 | ||
30107 | @example | |
30108 | for Char in 'A' .. 'Z' loop ... end loop; | |
30109 | @end example | |
30110 | ||
30111 | The problem is that ‘A’ and ‘Z’ could be from either | |
30112 | @code{Character} or @code{Wide_Character}. The simplest correction | |
30113 | is to make the type explicit; e.g.: | |
30114 | ||
30115 | @example | |
30116 | for Char in Character range 'A' .. 'Z' loop ... end loop; | |
30117 | @end example | |
30118 | ||
30119 | @item | |
1acce141 | 30120 | @emph{New reserved words} |
64d5610f ML |
30121 | |
30122 | The identifiers @code{abstract}, @code{aliased}, @code{protected}, | |
30123 | @code{requeue}, @code{tagged}, and @code{until} are reserved in Ada 95. | |
30124 | Existing Ada 83 code using any of these identifiers must be edited to | |
30125 | use some alternative name. | |
30126 | ||
30127 | @item | |
1acce141 | 30128 | @emph{Freezing rules} |
64d5610f ML |
30129 | |
30130 | The rules in Ada 95 are slightly different with regard to the point at | |
30131 | which entities are frozen, and representation pragmas and clauses are | |
30132 | not permitted past the freeze point. This shows up most typically in | |
30133 | the form of an error message complaining that a representation item | |
30134 | appears too late, and the appropriate corrective action is to move | |
30135 | the item nearer to the declaration of the entity to which it refers. | |
30136 | ||
30137 | A particular case is that representation pragmas | |
30138 | cannot be applied to a subprogram body. If necessary, a separate subprogram | |
30139 | declaration must be introduced to which the pragma can be applied. | |
30140 | ||
30141 | @item | |
1acce141 | 30142 | @emph{Optional bodies for library packages} |
64d5610f ML |
30143 | |
30144 | In Ada 83, a package that did not require a package body was nevertheless | |
30145 | allowed to have one. This lead to certain surprises in compiling large | |
30146 | systems (situations in which the body could be unexpectedly ignored by the | |
30147 | binder). In Ada 95, if a package does not require a body then it is not | |
30148 | permitted to have a body. To fix this problem, simply remove a redundant | |
30149 | body if it is empty, or, if it is non-empty, introduce a dummy declaration | |
30150 | into the spec that makes the body required. One approach is to add a private | |
30151 | part to the package declaration (if necessary), and define a parameterless | |
30152 | procedure called @code{Requires_Body}, which must then be given a dummy | |
30153 | procedure body in the package body, which then becomes required. | |
30154 | Another approach (assuming that this does not introduce elaboration | |
30155 | circularities) is to add an @code{Elaborate_Body} pragma to the package spec, | |
30156 | since one effect of this pragma is to require the presence of a package body. | |
30157 | ||
30158 | @item | |
1acce141 | 30159 | @emph{Numeric_Error is the same exception as Constraint_Error} |
64d5610f ML |
30160 | |
30161 | In Ada 95, the exception @code{Numeric_Error} is a renaming of @code{Constraint_Error}. | |
30162 | This means that it is illegal to have separate exception handlers for | |
30163 | the two exceptions. The fix is simply to remove the handler for the | |
30164 | @code{Numeric_Error} case (since even in Ada 83, a compiler was free to raise | |
30165 | @code{Constraint_Error} in place of @code{Numeric_Error} in all cases). | |
30166 | ||
30167 | @item | |
1acce141 | 30168 | @emph{Indefinite subtypes in generics} |
64d5610f ML |
30169 | |
30170 | In Ada 83, it was permissible to pass an indefinite type (e.g, @code{String}) | |
30171 | as the actual for a generic formal private type, but then the instantiation | |
30172 | would be illegal if there were any instances of declarations of variables | |
30173 | of this type in the generic body. In Ada 95, to avoid this clear violation | |
30174 | of the methodological principle known as the ‘contract model’, | |
30175 | the generic declaration explicitly indicates whether | |
30176 | or not such instantiations are permitted. If a generic formal parameter | |
30177 | has explicit unknown discriminants, indicated by using @code{(<>)} after the | |
30178 | subtype name, then it can be instantiated with indefinite types, but no | |
30179 | stand-alone variables can be declared of this type. Any attempt to declare | |
30180 | such a variable will result in an illegality at the time the generic is | |
30181 | declared. If the @code{(<>)} notation is not used, then it is illegal | |
30182 | to instantiate the generic with an indefinite type. | |
30183 | This is the potential incompatibility issue when porting Ada 83 code to Ada 95. | |
30184 | It will show up as a compile time error, and | |
30185 | the fix is usually simply to add the @code{(<>)} to the generic declaration. | |
30186 | @end itemize | |
30187 | ||
30188 | @node More deterministic semantics,Changed semantics,Legal Ada 83 programs that are illegal in Ada 95,Compatibility with Ada 83 | |
9daee425 | 30189 | @anchor{gnat_rm/compatibility_and_porting_guide id5}@anchor{463}@anchor{gnat_rm/compatibility_and_porting_guide more-deterministic-semantics}@anchor{464} |
64d5610f ML |
30190 | @subsection More deterministic semantics |
30191 | ||
30192 | ||
30193 | ||
30194 | @itemize * | |
30195 | ||
30196 | @item | |
1acce141 | 30197 | @emph{Conversions} |
64d5610f ML |
30198 | |
30199 | Conversions from real types to integer types round away from 0. In Ada 83 | |
30200 | the conversion Integer(2.5) could deliver either 2 or 3 as its value. This | |
30201 | implementation freedom was intended to support unbiased rounding in | |
30202 | statistical applications, but in practice it interfered with portability. | |
30203 | In Ada 95 the conversion semantics are unambiguous, and rounding away from 0 | |
30204 | is required. Numeric code may be affected by this change in semantics. | |
30205 | Note, though, that this issue is no worse than already existed in Ada 83 | |
30206 | when porting code from one vendor to another. | |
30207 | ||
30208 | @item | |
1acce141 | 30209 | @emph{Tasking} |
64d5610f ML |
30210 | |
30211 | The Real-Time Annex introduces a set of policies that define the behavior of | |
30212 | features that were implementation dependent in Ada 83, such as the order in | |
30213 | which open select branches are executed. | |
30214 | @end itemize | |
30215 | ||
30216 | @node Changed semantics,Other language compatibility issues,More deterministic semantics,Compatibility with Ada 83 | |
9daee425 | 30217 | @anchor{gnat_rm/compatibility_and_porting_guide changed-semantics}@anchor{465}@anchor{gnat_rm/compatibility_and_porting_guide id6}@anchor{466} |
64d5610f ML |
30218 | @subsection Changed semantics |
30219 | ||
30220 | ||
30221 | The worst kind of incompatibility is one where a program that is legal in | |
30222 | Ada 83 is also legal in Ada 95 but can have an effect in Ada 95 that was not | |
30223 | possible in Ada 83. Fortunately this is extremely rare, but the one | |
30224 | situation that you should be alert to is the change in the predefined type | |
30225 | @code{Character} from 7-bit ASCII to 8-bit Latin-1. | |
30226 | ||
30227 | @quotation | |
30228 | ||
30229 | @geindex Latin-1 | |
30230 | @end quotation | |
30231 | ||
30232 | ||
30233 | @itemize * | |
30234 | ||
30235 | @item | |
1acce141 | 30236 | @emph{Range of type `@w{`}Character`@w{`}} |
64d5610f ML |
30237 | |
30238 | The range of @code{Standard.Character} is now the full 256 characters | |
30239 | of Latin-1, whereas in most Ada 83 implementations it was restricted | |
30240 | to 128 characters. Although some of the effects of | |
30241 | this change will be manifest in compile-time rejection of legal | |
30242 | Ada 83 programs it is possible for a working Ada 83 program to have | |
30243 | a different effect in Ada 95, one that was not permitted in Ada 83. | |
30244 | As an example, the expression | |
30245 | @code{Character'Pos(Character'Last)} returned @code{127} in Ada 83 and now | |
30246 | delivers @code{255} as its value. | |
30247 | In general, you should look at the logic of any | |
30248 | character-processing Ada 83 program and see whether it needs to be adapted | |
30249 | to work correctly with Latin-1. Note that the predefined Ada 95 API has a | |
30250 | character handling package that may be relevant if code needs to be adapted | |
30251 | to account for the additional Latin-1 elements. | |
30252 | The desirable fix is to | |
30253 | modify the program to accommodate the full character set, but in some cases | |
30254 | it may be convenient to define a subtype or derived type of Character that | |
30255 | covers only the restricted range. | |
30256 | @end itemize | |
30257 | ||
30258 | @node Other language compatibility issues,,Changed semantics,Compatibility with Ada 83 | |
9daee425 | 30259 | @anchor{gnat_rm/compatibility_and_porting_guide id7}@anchor{467}@anchor{gnat_rm/compatibility_and_porting_guide other-language-compatibility-issues}@anchor{468} |
64d5610f ML |
30260 | @subsection Other language compatibility issues |
30261 | ||
30262 | ||
30263 | ||
30264 | @itemize * | |
30265 | ||
30266 | @item | |
1acce141 | 30267 | @emph{-gnat83} switch |
64d5610f ML |
30268 | |
30269 | All implementations of GNAT provide a switch that causes GNAT to operate | |
30270 | in Ada 83 mode. In this mode, some but not all compatibility problems | |
30271 | of the type described above are handled automatically. For example, the | |
30272 | new reserved words introduced in Ada 95 and Ada 2005 are treated simply | |
30273 | as identifiers as in Ada 83. However, | |
30274 | in practice, it is usually advisable to make the necessary modifications | |
30275 | to the program to remove the need for using this switch. | |
30276 | See the @code{Compiling Different Versions of Ada} section in | |
30277 | the @cite{GNAT User’s Guide}. | |
30278 | ||
30279 | @item | |
30280 | Support for removed Ada 83 pragmas and attributes | |
30281 | ||
30282 | A number of pragmas and attributes from Ada 83 were removed from Ada 95, | |
30283 | generally because they were replaced by other mechanisms. Ada 95 and Ada 2005 | |
30284 | compilers are allowed, but not required, to implement these missing | |
30285 | elements. In contrast with some other compilers, GNAT implements all | |
30286 | such pragmas and attributes, eliminating this compatibility concern. These | |
30287 | include @code{pragma Interface} and the floating point type attributes | |
30288 | (@code{Emax}, @code{Mantissa}, etc.), among other items. | |
30289 | @end itemize | |
30290 | ||
30291 | @node Compatibility between Ada 95 and Ada 2005,Implementation-dependent characteristics,Compatibility with Ada 83,Compatibility and Porting Guide | |
9daee425 | 30292 | @anchor{gnat_rm/compatibility_and_porting_guide compatibility-between-ada-95-and-ada-2005}@anchor{469}@anchor{gnat_rm/compatibility_and_porting_guide id8}@anchor{46a} |
64d5610f ML |
30293 | @section Compatibility between Ada 95 and Ada 2005 |
30294 | ||
30295 | ||
30296 | @geindex Compatibility between Ada 95 and Ada 2005 | |
30297 | ||
30298 | Although Ada 2005 was designed to be upwards compatible with Ada 95, there are | |
30299 | a number of incompatibilities. Several are enumerated below; | |
30300 | for a complete description please see the | |
30301 | @cite{Annotated Ada 2005 Reference Manual}, or section 9.1.1 in | |
30302 | @cite{Rationale for Ada 2005}. | |
30303 | ||
30304 | ||
30305 | @itemize * | |
30306 | ||
30307 | @item | |
1acce141 | 30308 | @emph{New reserved words.} |
64d5610f ML |
30309 | |
30310 | The words @code{interface}, @code{overriding} and @code{synchronized} are | |
30311 | reserved in Ada 2005. | |
30312 | A pre-Ada 2005 program that uses any of these as an identifier will be | |
30313 | illegal. | |
30314 | ||
30315 | @item | |
1acce141 | 30316 | @emph{New declarations in predefined packages.} |
64d5610f ML |
30317 | |
30318 | A number of packages in the predefined environment contain new declarations: | |
30319 | @code{Ada.Exceptions}, @code{Ada.Real_Time}, @code{Ada.Strings}, | |
30320 | @code{Ada.Strings.Fixed}, @code{Ada.Strings.Bounded}, | |
30321 | @code{Ada.Strings.Unbounded}, @code{Ada.Strings.Wide_Fixed}, | |
30322 | @code{Ada.Strings.Wide_Bounded}, @code{Ada.Strings.Wide_Unbounded}, | |
30323 | @code{Ada.Tags}, @code{Ada.Text_IO}, and @code{Interfaces.C}. | |
30324 | If an Ada 95 program does a @code{with} and @code{use} of any of these | |
30325 | packages, the new declarations may cause name clashes. | |
30326 | ||
30327 | @item | |
1acce141 | 30328 | @emph{Access parameters.} |
64d5610f ML |
30329 | |
30330 | A nondispatching subprogram with an access parameter cannot be renamed | |
30331 | as a dispatching operation. This was permitted in Ada 95. | |
30332 | ||
30333 | @item | |
1acce141 | 30334 | @emph{Access types, discriminants, and constraints.} |
64d5610f ML |
30335 | |
30336 | Rule changes in this area have led to some incompatibilities; for example, | |
30337 | constrained subtypes of some access types are not permitted in Ada 2005. | |
30338 | ||
30339 | @item | |
1acce141 | 30340 | @emph{Aggregates for limited types.} |
64d5610f ML |
30341 | |
30342 | The allowance of aggregates for limited types in Ada 2005 raises the | |
30343 | possibility of ambiguities in legal Ada 95 programs, since additional types | |
30344 | now need to be considered in expression resolution. | |
30345 | ||
30346 | @item | |
1acce141 | 30347 | @emph{Fixed-point multiplication and division.} |
64d5610f ML |
30348 | |
30349 | Certain expressions involving ‘*’ or ‘/’ for a fixed-point type, which | |
30350 | were legal in Ada 95 and invoked the predefined versions of these operations, | |
30351 | are now ambiguous. | |
30352 | The ambiguity may be resolved either by applying a type conversion to the | |
30353 | expression, or by explicitly invoking the operation from package | |
30354 | @code{Standard}. | |
30355 | ||
30356 | @item | |
1acce141 | 30357 | @emph{Return-by-reference types.} |
64d5610f ML |
30358 | |
30359 | The Ada 95 return-by-reference mechanism has been removed. Instead, the user | |
30360 | can declare a function returning a value from an anonymous access type. | |
30361 | @end itemize | |
30362 | ||
30363 | @node Implementation-dependent characteristics,Compatibility with Other Ada Systems,Compatibility between Ada 95 and Ada 2005,Compatibility and Porting Guide | |
9daee425 | 30364 | @anchor{gnat_rm/compatibility_and_porting_guide id9}@anchor{46b}@anchor{gnat_rm/compatibility_and_porting_guide implementation-dependent-characteristics}@anchor{46c} |
64d5610f ML |
30365 | @section Implementation-dependent characteristics |
30366 | ||
30367 | ||
30368 | Although the Ada language defines the semantics of each construct as | |
30369 | precisely as practical, in some situations (for example for reasons of | |
30370 | efficiency, or where the effect is heavily dependent on the host or target | |
30371 | platform) the implementation is allowed some freedom. In porting Ada 83 | |
30372 | code to GNAT, you need to be aware of whether / how the existing code | |
30373 | exercised such implementation dependencies. Such characteristics fall into | |
30374 | several categories, and GNAT offers specific support in assisting the | |
30375 | transition from certain Ada 83 compilers. | |
30376 | ||
30377 | @menu | |
30378 | * Implementation-defined pragmas:: | |
30379 | * Implementation-defined attributes:: | |
30380 | * Libraries:: | |
30381 | * Elaboration order:: | |
30382 | * Target-specific aspects:: | |
30383 | ||
30384 | @end menu | |
30385 | ||
30386 | @node Implementation-defined pragmas,Implementation-defined attributes,,Implementation-dependent characteristics | |
9daee425 | 30387 | @anchor{gnat_rm/compatibility_and_porting_guide id10}@anchor{46d}@anchor{gnat_rm/compatibility_and_porting_guide implementation-defined-pragmas}@anchor{46e} |
64d5610f ML |
30388 | @subsection Implementation-defined pragmas |
30389 | ||
30390 | ||
30391 | Ada compilers are allowed to supplement the language-defined pragmas, and | |
30392 | these are a potential source of non-portability. All GNAT-defined pragmas | |
30393 | are described in @ref{7,,Implementation Defined Pragmas}, | |
30394 | and these include several that are specifically | |
30395 | intended to correspond to other vendors’ Ada 83 pragmas. | |
30396 | For migrating from VADS, the pragma @code{Use_VADS_Size} may be useful. | |
30397 | For compatibility with HP Ada 83, GNAT supplies the pragmas | |
30398 | @code{Extend_System}, @code{Ident}, @code{Inline_Generic}, | |
30399 | @code{Interface_Name}, @code{Passive}, @code{Suppress_All}, | |
30400 | and @code{Volatile}. | |
30401 | Other relevant pragmas include @code{External} and @code{Link_With}. | |
30402 | Some vendor-specific | |
30403 | Ada 83 pragmas (@code{Share_Generic}, @code{Subtitle}, and @code{Title}) are | |
30404 | recognized, thus | |
30405 | avoiding compiler rejection of units that contain such pragmas; they are not | |
30406 | relevant in a GNAT context and hence are not otherwise implemented. | |
30407 | ||
30408 | @node Implementation-defined attributes,Libraries,Implementation-defined pragmas,Implementation-dependent characteristics | |
9daee425 | 30409 | @anchor{gnat_rm/compatibility_and_porting_guide id11}@anchor{46f}@anchor{gnat_rm/compatibility_and_porting_guide implementation-defined-attributes}@anchor{470} |
64d5610f ML |
30410 | @subsection Implementation-defined attributes |
30411 | ||
30412 | ||
30413 | Analogous to pragmas, the set of attributes may be extended by an | |
30414 | implementation. All GNAT-defined attributes are described in | |
30415 | @ref{8,,Implementation Defined Attributes}, | |
30416 | and these include several that are specifically intended | |
30417 | to correspond to other vendors’ Ada 83 attributes. For migrating from VADS, | |
30418 | the attribute @code{VADS_Size} may be useful. For compatibility with HP | |
30419 | Ada 83, GNAT supplies the attributes @code{Bit}, @code{Machine_Size} and | |
30420 | @code{Type_Class}. | |
30421 | ||
30422 | @node Libraries,Elaboration order,Implementation-defined attributes,Implementation-dependent characteristics | |
9daee425 | 30423 | @anchor{gnat_rm/compatibility_and_porting_guide id12}@anchor{471}@anchor{gnat_rm/compatibility_and_porting_guide libraries}@anchor{472} |
64d5610f ML |
30424 | @subsection Libraries |
30425 | ||
30426 | ||
30427 | Vendors may supply libraries to supplement the standard Ada API. If Ada 83 | |
30428 | code uses vendor-specific libraries then there are several ways to manage | |
30429 | this in Ada 95 and later versions of the standard: | |
30430 | ||
30431 | ||
30432 | @itemize * | |
30433 | ||
30434 | @item | |
30435 | If the source code for the libraries (specs and bodies) are | |
30436 | available, then the libraries can be migrated in the same way as the | |
30437 | application. | |
30438 | ||
30439 | @item | |
30440 | If the source code for the specs but not the bodies are | |
30441 | available, then you can reimplement the bodies. | |
30442 | ||
30443 | @item | |
30444 | Some features introduced by Ada 95 obviate the need for library support. For | |
30445 | example most Ada 83 vendors supplied a package for unsigned integers. The | |
30446 | Ada 95 modular type feature is the preferred way to handle this need, so | |
30447 | instead of migrating or reimplementing the unsigned integer package it may | |
30448 | be preferable to retrofit the application using modular types. | |
30449 | @end itemize | |
30450 | ||
30451 | @node Elaboration order,Target-specific aspects,Libraries,Implementation-dependent characteristics | |
9daee425 | 30452 | @anchor{gnat_rm/compatibility_and_porting_guide elaboration-order}@anchor{473}@anchor{gnat_rm/compatibility_and_porting_guide id13}@anchor{474} |
64d5610f ML |
30453 | @subsection Elaboration order |
30454 | ||
30455 | ||
30456 | The implementation can choose any elaboration order consistent with the unit | |
30457 | dependency relationship. This freedom means that some orders can result in | |
30458 | Program_Error being raised due to an ‘Access Before Elaboration’: an attempt | |
30459 | to invoke a subprogram before its body has been elaborated, or to instantiate | |
30460 | a generic before the generic body has been elaborated. By default GNAT | |
30461 | attempts to choose a safe order (one that will not encounter access before | |
30462 | elaboration problems) by implicitly inserting @code{Elaborate} or | |
30463 | @code{Elaborate_All} pragmas where | |
30464 | needed. However, this can lead to the creation of elaboration circularities | |
30465 | and a resulting rejection of the program by gnatbind. This issue is | |
1acce141 | 30466 | thoroughly described in the @emph{Elaboration Order Handling in GNAT} appendix |
64d5610f ML |
30467 | in the @cite{GNAT User’s Guide}. |
30468 | In brief, there are several | |
30469 | ways to deal with this situation: | |
30470 | ||
30471 | ||
30472 | @itemize * | |
30473 | ||
30474 | @item | |
30475 | Modify the program to eliminate the circularities, e.g., by moving | |
30476 | elaboration-time code into explicitly-invoked procedures | |
30477 | ||
30478 | @item | |
30479 | Constrain the elaboration order by including explicit @code{Elaborate_Body} or | |
30480 | @code{Elaborate} pragmas, and then inhibit the generation of implicit | |
30481 | @code{Elaborate_All} | |
1acce141 | 30482 | pragmas either globally (as an effect of the @emph{-gnatE} switch) or locally |
64d5610f ML |
30483 | (by selectively suppressing elaboration checks via pragma |
30484 | @code{Suppress(Elaboration_Check)} when it is safe to do so). | |
30485 | @end itemize | |
30486 | ||
30487 | @node Target-specific aspects,,Elaboration order,Implementation-dependent characteristics | |
9daee425 | 30488 | @anchor{gnat_rm/compatibility_and_porting_guide id14}@anchor{475}@anchor{gnat_rm/compatibility_and_porting_guide target-specific-aspects}@anchor{476} |
64d5610f ML |
30489 | @subsection Target-specific aspects |
30490 | ||
30491 | ||
30492 | Low-level applications need to deal with machine addresses, data | |
30493 | representations, interfacing with assembler code, and similar issues. If | |
30494 | such an Ada 83 application is being ported to different target hardware (for | |
30495 | example where the byte endianness has changed) then you will need to | |
30496 | carefully examine the program logic; the porting effort will heavily depend | |
30497 | on the robustness of the original design. Moreover, Ada 95 (and thus | |
30498 | Ada 2005 and Ada 2012) are sometimes | |
30499 | incompatible with typical Ada 83 compiler practices regarding implicit | |
30500 | packing, the meaning of the Size attribute, and the size of access values. | |
9daee425 | 30501 | GNAT’s approach to these issues is described in @ref{477,,Representation Clauses}. |
64d5610f ML |
30502 | |
30503 | @node Compatibility with Other Ada Systems,Representation Clauses,Implementation-dependent characteristics,Compatibility and Porting Guide | |
9daee425 | 30504 | @anchor{gnat_rm/compatibility_and_porting_guide compatibility-with-other-ada-systems}@anchor{478}@anchor{gnat_rm/compatibility_and_porting_guide id15}@anchor{479} |
64d5610f ML |
30505 | @section Compatibility with Other Ada Systems |
30506 | ||
30507 | ||
30508 | If programs avoid the use of implementation dependent and | |
30509 | implementation defined features, as documented in the | |
30510 | @cite{Ada Reference Manual}, there should be a high degree of portability between | |
30511 | GNAT and other Ada systems. The following are specific items which | |
30512 | have proved troublesome in moving Ada 95 programs from GNAT to other Ada 95 | |
30513 | compilers, but do not affect porting code to GNAT. | |
30514 | (As of January 2007, GNAT is the only compiler available for Ada 2005; | |
30515 | the following issues may or may not arise for Ada 2005 programs | |
30516 | when other compilers appear.) | |
30517 | ||
30518 | ||
30519 | @itemize * | |
30520 | ||
30521 | @item | |
1acce141 | 30522 | @emph{Ada 83 Pragmas and Attributes} |
64d5610f ML |
30523 | |
30524 | Ada 95 compilers are allowed, but not required, to implement the missing | |
30525 | Ada 83 pragmas and attributes that are no longer defined in Ada 95. | |
30526 | GNAT implements all such pragmas and attributes, eliminating this as | |
30527 | a compatibility concern, but some other Ada 95 compilers reject these | |
30528 | pragmas and attributes. | |
30529 | ||
30530 | @item | |
1acce141 | 30531 | @emph{Specialized Needs Annexes} |
64d5610f ML |
30532 | |
30533 | GNAT implements the full set of special needs annexes. At the | |
30534 | current time, it is the only Ada 95 compiler to do so. This means that | |
30535 | programs making use of these features may not be portable to other Ada | |
30536 | 95 compilation systems. | |
30537 | ||
30538 | @item | |
1acce141 | 30539 | @emph{Representation Clauses} |
64d5610f ML |
30540 | |
30541 | Some other Ada 95 compilers implement only the minimal set of | |
30542 | representation clauses required by the Ada 95 reference manual. GNAT goes | |
30543 | far beyond this minimal set, as described in the next section. | |
30544 | @end itemize | |
30545 | ||
30546 | @node Representation Clauses,Compatibility with HP Ada 83,Compatibility with Other Ada Systems,Compatibility and Porting Guide | |
9daee425 | 30547 | @anchor{gnat_rm/compatibility_and_porting_guide id16}@anchor{47a}@anchor{gnat_rm/compatibility_and_porting_guide representation-clauses}@anchor{477} |
64d5610f ML |
30548 | @section Representation Clauses |
30549 | ||
30550 | ||
30551 | The Ada 83 reference manual was quite vague in describing both the minimal | |
30552 | required implementation of representation clauses, and also their precise | |
30553 | effects. Ada 95 (and thus also Ada 2005) are much more explicit, but the | |
30554 | minimal set of capabilities required is still quite limited. | |
30555 | ||
30556 | GNAT implements the full required set of capabilities in | |
30557 | Ada 95 and Ada 2005, but also goes much further, and in particular | |
30558 | an effort has been made to be compatible with existing Ada 83 usage to the | |
30559 | greatest extent possible. | |
30560 | ||
30561 | A few cases exist in which Ada 83 compiler behavior is incompatible with | |
30562 | the requirements in Ada 95 (and thus also Ada 2005). These are instances of | |
30563 | intentional or accidental dependence on specific implementation dependent | |
30564 | characteristics of these Ada 83 compilers. The following is a list of | |
30565 | the cases most likely to arise in existing Ada 83 code. | |
30566 | ||
30567 | ||
30568 | @itemize * | |
30569 | ||
30570 | @item | |
1acce141 | 30571 | @emph{Implicit Packing} |
64d5610f ML |
30572 | |
30573 | Some Ada 83 compilers allowed a Size specification to cause implicit | |
30574 | packing of an array or record. This could cause expensive implicit | |
30575 | conversions for change of representation in the presence of derived | |
30576 | types, and the Ada design intends to avoid this possibility. | |
30577 | Subsequent AI’s were issued to make it clear that such implicit | |
30578 | change of representation in response to a Size clause is inadvisable, | |
30579 | and this recommendation is represented explicitly in the Ada 95 (and Ada 2005) | |
30580 | Reference Manuals as implementation advice that is followed by GNAT. | |
30581 | The problem will show up as an error | |
30582 | message rejecting the size clause. The fix is simply to provide | |
30583 | the explicit pragma @code{Pack}, or for more fine tuned control, provide | |
30584 | a Component_Size clause. | |
30585 | ||
30586 | @item | |
1acce141 | 30587 | @emph{Meaning of Size Attribute} |
64d5610f ML |
30588 | |
30589 | The Size attribute in Ada 95 (and Ada 2005) for discrete types is defined as | |
30590 | the minimal number of bits required to hold values of the type. For example, | |
30591 | on a 32-bit machine, the size of @code{Natural} will typically be 31 and not | |
30592 | 32 (since no sign bit is required). Some Ada 83 compilers gave 31, and | |
30593 | some 32 in this situation. This problem will usually show up as a compile | |
30594 | time error, but not always. It is a good idea to check all uses of the | |
30595 | ‘Size attribute when porting Ada 83 code. The GNAT specific attribute | |
30596 | Object_Size can provide a useful way of duplicating the behavior of | |
30597 | some Ada 83 compiler systems. | |
30598 | ||
30599 | @item | |
1acce141 | 30600 | @emph{Size of Access Types} |
64d5610f ML |
30601 | |
30602 | A common assumption in Ada 83 code is that an access type is in fact a pointer, | |
30603 | and that therefore it will be the same size as a System.Address value. This | |
30604 | assumption is true for GNAT in most cases with one exception. For the case of | |
30605 | a pointer to an unconstrained array type (where the bounds may vary from one | |
30606 | value of the access type to another), the default is to use a ‘fat pointer’, | |
30607 | which is represented as two separate pointers, one to the bounds, and one to | |
30608 | the array. This representation has a number of advantages, including improved | |
30609 | efficiency. However, it may cause some difficulties in porting existing Ada 83 | |
30610 | code which makes the assumption that, for example, pointers fit in 32 bits on | |
30611 | a machine with 32-bit addressing. | |
30612 | ||
30613 | To get around this problem, GNAT also permits the use of ‘thin pointers’ for | |
30614 | access types in this case (where the designated type is an unconstrained array | |
30615 | type). These thin pointers are indeed the same size as a System.Address value. | |
30616 | To specify a thin pointer, use a size clause for the type, for example: | |
30617 | ||
30618 | @example | |
30619 | type X is access all String; | |
30620 | for X'Size use Standard'Address_Size; | |
30621 | @end example | |
30622 | ||
30623 | which will cause the type X to be represented using a single pointer. | |
30624 | When using this representation, the bounds are right behind the array. | |
30625 | This representation is slightly less efficient, and does not allow quite | |
30626 | such flexibility in the use of foreign pointers or in using the | |
30627 | Unrestricted_Access attribute to create pointers to non-aliased objects. | |
30628 | But for any standard portable use of the access type it will work in | |
30629 | a functionally correct manner and allow porting of existing code. | |
30630 | Note that another way of forcing a thin pointer representation | |
30631 | is to use a component size clause for the element size in an array, | |
30632 | or a record representation clause for an access field in a record. | |
30633 | ||
30634 | See the documentation of Unrestricted_Access in the GNAT RM for a | |
30635 | full discussion of possible problems using this attribute in conjunction | |
30636 | with thin pointers. | |
30637 | @end itemize | |
30638 | ||
30639 | @node Compatibility with HP Ada 83,,Representation Clauses,Compatibility and Porting Guide | |
9daee425 | 30640 | @anchor{gnat_rm/compatibility_and_porting_guide compatibility-with-hp-ada-83}@anchor{47b}@anchor{gnat_rm/compatibility_and_porting_guide id17}@anchor{47c} |
64d5610f ML |
30641 | @section Compatibility with HP Ada 83 |
30642 | ||
30643 | ||
30644 | All the HP Ada 83 pragmas and attributes are recognized, although only a subset | |
30645 | of them can sensibly be implemented. The description of pragmas in | |
30646 | @ref{7,,Implementation Defined Pragmas} indicates whether or not they are | |
30647 | applicable to GNAT. | |
30648 | ||
30649 | ||
30650 | @itemize * | |
30651 | ||
30652 | @item | |
1acce141 | 30653 | @emph{Default floating-point representation} |
64d5610f ML |
30654 | |
30655 | In GNAT, the default floating-point format is IEEE, whereas in HP Ada 83, | |
30656 | it is VMS format. | |
30657 | ||
30658 | @item | |
1acce141 | 30659 | @emph{System} |
64d5610f ML |
30660 | |
30661 | the package System in GNAT exactly corresponds to the definition in the | |
30662 | Ada 95 reference manual, which means that it excludes many of the | |
30663 | HP Ada 83 extensions. However, a separate package Aux_DEC is provided | |
30664 | that contains the additional definitions, and a special pragma, | |
30665 | Extend_System allows this package to be treated transparently as an | |
30666 | extension of package System. | |
30667 | @end itemize | |
30668 | ||
30669 | @node GNU Free Documentation License,Index,Compatibility and Porting Guide,Top | |
9daee425 | 30670 | @anchor{share/gnu_free_documentation_license doc}@anchor{47d}@anchor{share/gnu_free_documentation_license gnu-fdl}@anchor{1}@anchor{share/gnu_free_documentation_license gnu-free-documentation-license}@anchor{47e} |
64d5610f ML |
30671 | @chapter GNU Free Documentation License |
30672 | ||
30673 | ||
30674 | Version 1.3, 3 November 2008 | |
30675 | ||
30676 | Copyright 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc | |
30677 | @indicateurl{https://fsf.org/} | |
30678 | ||
30679 | Everyone is permitted to copy and distribute verbatim copies of this | |
30680 | license document, but changing it is not allowed. | |
30681 | ||
1acce141 | 30682 | @strong{Preamble} |
64d5610f ML |
30683 | |
30684 | The purpose of this License is to make a manual, textbook, or other | |
30685 | functional and useful document “free” in the sense of freedom: to | |
30686 | assure everyone the effective freedom to copy and redistribute it, | |
30687 | with or without modifying it, either commercially or noncommercially. | |
30688 | Secondarily, this License preserves for the author and publisher a way | |
30689 | to get credit for their work, while not being considered responsible | |
30690 | for modifications made by others. | |
30691 | ||
30692 | This License is a kind of “copyleft”, which means that derivative | |
30693 | works of the document must themselves be free in the same sense. It | |
30694 | complements the GNU General Public License, which is a copyleft | |
30695 | license designed for free software. | |
30696 | ||
30697 | We have designed this License in order to use it for manuals for free | |
30698 | software, because free software needs free documentation: a free | |
30699 | program should come with manuals providing the same freedoms that the | |
30700 | software does. But this License is not limited to software manuals; | |
30701 | it can be used for any textual work, regardless of subject matter or | |
30702 | whether it is published as a printed book. We recommend this License | |
30703 | principally for works whose purpose is instruction or reference. | |
30704 | ||
1acce141 | 30705 | @strong{1. APPLICABILITY AND DEFINITIONS} |
64d5610f ML |
30706 | |
30707 | This License applies to any manual or other work, in any medium, that | |
30708 | contains a notice placed by the copyright holder saying it can be | |
30709 | distributed under the terms of this License. Such a notice grants a | |
30710 | world-wide, royalty-free license, unlimited in duration, to use that | |
1acce141 | 30711 | work under the conditions stated herein. The @strong{Document}, below, |
64d5610f | 30712 | refers to any such manual or work. Any member of the public is a |
1acce141 | 30713 | licensee, and is addressed as “@strong{you}”. You accept the license if you |
64d5610f ML |
30714 | copy, modify or distribute the work in a way requiring permission |
30715 | under copyright law. | |
30716 | ||
1acce141 | 30717 | A “@strong{Modified Version}” of the Document means any work containing the |
64d5610f ML |
30718 | Document or a portion of it, either copied verbatim, or with |
30719 | modifications and/or translated into another language. | |
30720 | ||
1acce141 | 30721 | A “@strong{Secondary Section}” is a named appendix or a front-matter section of |
64d5610f ML |
30722 | the Document that deals exclusively with the relationship of the |
30723 | publishers or authors of the Document to the Document’s overall subject | |
30724 | (or to related matters) and contains nothing that could fall directly | |
30725 | within that overall subject. (Thus, if the Document is in part a | |
30726 | textbook of mathematics, a Secondary Section may not explain any | |
30727 | mathematics.) The relationship could be a matter of historical | |
30728 | connection with the subject or with related matters, or of legal, | |
30729 | commercial, philosophical, ethical or political position regarding | |
30730 | them. | |
30731 | ||
1acce141 | 30732 | The “@strong{Invariant Sections}” are certain Secondary Sections whose titles |
64d5610f ML |
30733 | are designated, as being those of Invariant Sections, in the notice |
30734 | that says that the Document is released under this License. If a | |
30735 | section does not fit the above definition of Secondary then it is not | |
30736 | allowed to be designated as Invariant. The Document may contain zero | |
30737 | Invariant Sections. If the Document does not identify any Invariant | |
30738 | Sections then there are none. | |
30739 | ||
1acce141 | 30740 | The “@strong{Cover Texts}” are certain short passages of text that are listed, |
64d5610f ML |
30741 | as Front-Cover Texts or Back-Cover Texts, in the notice that says that |
30742 | the Document is released under this License. A Front-Cover Text may | |
30743 | be at most 5 words, and a Back-Cover Text may be at most 25 words. | |
30744 | ||
1acce141 | 30745 | A “@strong{Transparent}” copy of the Document means a machine-readable copy, |
64d5610f ML |
30746 | represented in a format whose specification is available to the |
30747 | general public, that is suitable for revising the document | |
30748 | straightforwardly with generic text editors or (for images composed of | |
30749 | pixels) generic paint programs or (for drawings) some widely available | |
30750 | drawing editor, and that is suitable for input to text formatters or | |
30751 | for automatic translation to a variety of formats suitable for input | |
30752 | to text formatters. A copy made in an otherwise Transparent file | |
30753 | format whose markup, or absence of markup, has been arranged to thwart | |
30754 | or discourage subsequent modification by readers is not Transparent. | |
30755 | An image format is not Transparent if used for any substantial amount | |
1acce141 | 30756 | of text. A copy that is not “Transparent” is called @strong{Opaque}. |
64d5610f ML |
30757 | |
30758 | Examples of suitable formats for Transparent copies include plain | |
30759 | ASCII without markup, Texinfo input format, LaTeX input format, SGML | |
30760 | or XML using a publicly available DTD, and standard-conforming simple | |
30761 | HTML, PostScript or PDF designed for human modification. Examples of | |
30762 | transparent image formats include PNG, XCF and JPG. Opaque formats | |
30763 | include proprietary formats that can be read and edited only by | |
30764 | proprietary word processors, SGML or XML for which the DTD and/or | |
30765 | processing tools are not generally available, and the | |
30766 | machine-generated HTML, PostScript or PDF produced by some word | |
30767 | processors for output purposes only. | |
30768 | ||
1acce141 | 30769 | The “@strong{Title Page}” means, for a printed book, the title page itself, |
64d5610f ML |
30770 | plus such following pages as are needed to hold, legibly, the material |
30771 | this License requires to appear in the title page. For works in | |
30772 | formats which do not have any title page as such, “Title Page” means | |
30773 | the text near the most prominent appearance of the work’s title, | |
30774 | preceding the beginning of the body of the text. | |
30775 | ||
1acce141 | 30776 | The “@strong{publisher}” means any person or entity that distributes |
64d5610f ML |
30777 | copies of the Document to the public. |
30778 | ||
1acce141 | 30779 | A section “@strong{Entitled XYZ}” means a named subunit of the Document whose |
64d5610f ML |
30780 | title either is precisely XYZ or contains XYZ in parentheses following |
30781 | text that translates XYZ in another language. (Here XYZ stands for a | |
1acce141 YM |
30782 | specific section name mentioned below, such as “@strong{Acknowledgements}”, |
30783 | “@strong{Dedications}”, “@strong{Endorsements}”, or “@strong{History}”.) | |
30784 | To “@strong{Preserve the Title}” | |
64d5610f ML |
30785 | of such a section when you modify the Document means that it remains a |
30786 | section “Entitled XYZ” according to this definition. | |
30787 | ||
30788 | The Document may include Warranty Disclaimers next to the notice which | |
30789 | states that this License applies to the Document. These Warranty | |
30790 | Disclaimers are considered to be included by reference in this | |
30791 | License, but only as regards disclaiming warranties: any other | |
30792 | implication that these Warranty Disclaimers may have is void and has | |
30793 | no effect on the meaning of this License. | |
30794 | ||
1acce141 | 30795 | @strong{2. VERBATIM COPYING} |
64d5610f ML |
30796 | |
30797 | You may copy and distribute the Document in any medium, either | |
30798 | commercially or noncommercially, provided that this License, the | |
30799 | copyright notices, and the license notice saying this License applies | |
30800 | to the Document are reproduced in all copies, and that you add no other | |
30801 | conditions whatsoever to those of this License. You may not use | |
30802 | technical measures to obstruct or control the reading or further | |
30803 | copying of the copies you make or distribute. However, you may accept | |
30804 | compensation in exchange for copies. If you distribute a large enough | |
30805 | number of copies you must also follow the conditions in section 3. | |
30806 | ||
30807 | You may also lend copies, under the same conditions stated above, and | |
30808 | you may publicly display copies. | |
30809 | ||
1acce141 | 30810 | @strong{3. COPYING IN QUANTITY} |
64d5610f ML |
30811 | |
30812 | If you publish printed copies (or copies in media that commonly have | |
30813 | printed covers) of the Document, numbering more than 100, and the | |
30814 | Document’s license notice requires Cover Texts, you must enclose the | |
30815 | copies in covers that carry, clearly and legibly, all these Cover | |
30816 | Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on | |
30817 | the back cover. Both covers must also clearly and legibly identify | |
30818 | you as the publisher of these copies. The front cover must present | |
30819 | the full title with all words of the title equally prominent and | |
30820 | visible. You may add other material on the covers in addition. | |
30821 | Copying with changes limited to the covers, as long as they preserve | |
30822 | the title of the Document and satisfy these conditions, can be treated | |
30823 | as verbatim copying in other respects. | |
30824 | ||
30825 | If the required texts for either cover are too voluminous to fit | |
30826 | legibly, you should put the first ones listed (as many as fit | |
30827 | reasonably) on the actual cover, and continue the rest onto adjacent | |
30828 | pages. | |
30829 | ||
30830 | If you publish or distribute Opaque copies of the Document numbering | |
30831 | more than 100, you must either include a machine-readable Transparent | |
30832 | copy along with each Opaque copy, or state in or with each Opaque copy | |
30833 | a computer-network location from which the general network-using | |
30834 | public has access to download using public-standard network protocols | |
30835 | a complete Transparent copy of the Document, free of added material. | |
30836 | If you use the latter option, you must take reasonably prudent steps, | |
30837 | when you begin distribution of Opaque copies in quantity, to ensure | |
30838 | that this Transparent copy will remain thus accessible at the stated | |
30839 | location until at least one year after the last time you distribute an | |
30840 | Opaque copy (directly or through your agents or retailers) of that | |
30841 | edition to the public. | |
30842 | ||
30843 | It is requested, but not required, that you contact the authors of the | |
30844 | Document well before redistributing any large number of copies, to give | |
30845 | them a chance to provide you with an updated version of the Document. | |
30846 | ||
1acce141 | 30847 | @strong{4. MODIFICATIONS} |
64d5610f ML |
30848 | |
30849 | You may copy and distribute a Modified Version of the Document under | |
30850 | the conditions of sections 2 and 3 above, provided that you release | |
30851 | the Modified Version under precisely this License, with the Modified | |
30852 | Version filling the role of the Document, thus licensing distribution | |
30853 | and modification of the Modified Version to whoever possesses a copy | |
30854 | of it. In addition, you must do these things in the Modified Version: | |
30855 | ||
30856 | ||
30857 | @enumerate A | |
30858 | ||
30859 | @item | |
30860 | Use in the Title Page (and on the covers, if any) a title distinct | |
30861 | from that of the Document, and from those of previous versions | |
30862 | (which should, if there were any, be listed in the History section | |
30863 | of the Document). You may use the same title as a previous version | |
30864 | if the original publisher of that version gives permission. | |
30865 | ||
30866 | @item | |
30867 | List on the Title Page, as authors, one or more persons or entities | |
30868 | responsible for authorship of the modifications in the Modified | |
30869 | Version, together with at least five of the principal authors of the | |
30870 | Document (all of its principal authors, if it has fewer than five), | |
30871 | unless they release you from this requirement. | |
30872 | ||
30873 | @item | |
30874 | State on the Title page the name of the publisher of the | |
30875 | Modified Version, as the publisher. | |
30876 | ||
30877 | @item | |
30878 | Preserve all the copyright notices of the Document. | |
30879 | ||
30880 | @item | |
30881 | Add an appropriate copyright notice for your modifications | |
30882 | adjacent to the other copyright notices. | |
30883 | ||
30884 | @item | |
30885 | Include, immediately after the copyright notices, a license notice | |
30886 | giving the public permission to use the Modified Version under the | |
30887 | terms of this License, in the form shown in the Addendum below. | |
30888 | ||
30889 | @item | |
30890 | Preserve in that license notice the full lists of Invariant Sections | |
30891 | and required Cover Texts given in the Document’s license notice. | |
30892 | ||
30893 | @item | |
30894 | Include an unaltered copy of this License. | |
30895 | ||
30896 | @item | |
30897 | Preserve the section Entitled “History”, Preserve its Title, and add | |
30898 | to it an item stating at least the title, year, new authors, and | |
30899 | publisher of the Modified Version as given on the Title Page. If | |
30900 | there is no section Entitled “History” in the Document, create one | |
30901 | stating the title, year, authors, and publisher of the Document as | |
30902 | given on its Title Page, then add an item describing the Modified | |
30903 | Version as stated in the previous sentence. | |
30904 | ||
30905 | @item | |
30906 | Preserve the network location, if any, given in the Document for | |
30907 | public access to a Transparent copy of the Document, and likewise | |
30908 | the network locations given in the Document for previous versions | |
30909 | it was based on. These may be placed in the “History” section. | |
30910 | You may omit a network location for a work that was published at | |
30911 | least four years before the Document itself, or if the original | |
30912 | publisher of the version it refers to gives permission. | |
30913 | ||
30914 | @item | |
30915 | For any section Entitled “Acknowledgements” or “Dedications”, | |
30916 | Preserve the Title of the section, and preserve in the section all | |
30917 | the substance and tone of each of the contributor acknowledgements | |
30918 | and/or dedications given therein. | |
30919 | ||
30920 | @item | |
30921 | Preserve all the Invariant Sections of the Document, | |
30922 | unaltered in their text and in their titles. Section numbers | |
30923 | or the equivalent are not considered part of the section titles. | |
30924 | ||
30925 | @item | |
30926 | Delete any section Entitled “Endorsements”. Such a section | |
30927 | may not be included in the Modified Version. | |
30928 | ||
30929 | @item | |
30930 | Do not retitle any existing section to be Entitled “Endorsements” | |
30931 | or to conflict in title with any Invariant Section. | |
30932 | ||
30933 | @item | |
30934 | Preserve any Warranty Disclaimers. | |
30935 | @end enumerate | |
30936 | ||
30937 | If the Modified Version includes new front-matter sections or | |
30938 | appendices that qualify as Secondary Sections and contain no material | |
30939 | copied from the Document, you may at your option designate some or all | |
30940 | of these sections as invariant. To do this, add their titles to the | |
30941 | list of Invariant Sections in the Modified Version’s license notice. | |
30942 | These titles must be distinct from any other section titles. | |
30943 | ||
30944 | You may add a section Entitled “Endorsements”, provided it contains | |
30945 | nothing but endorsements of your Modified Version by various | |
30946 | parties—for example, statements of peer review or that the text has | |
30947 | been approved by an organization as the authoritative definition of a | |
30948 | standard. | |
30949 | ||
30950 | You may add a passage of up to five words as a Front-Cover Text, and a | |
30951 | passage of up to 25 words as a Back-Cover Text, to the end of the list | |
30952 | of Cover Texts in the Modified Version. Only one passage of | |
30953 | Front-Cover Text and one of Back-Cover Text may be added by (or | |
30954 | through arrangements made by) any one entity. If the Document already | |
30955 | includes a cover text for the same cover, previously added by you or | |
30956 | by arrangement made by the same entity you are acting on behalf of, | |
30957 | you may not add another; but you may replace the old one, on explicit | |
30958 | permission from the previous publisher that added the old one. | |
30959 | ||
30960 | The author(s) and publisher(s) of the Document do not by this License | |
30961 | give permission to use their names for publicity for or to assert or | |
30962 | imply endorsement of any Modified Version. | |
30963 | ||
1acce141 | 30964 | @strong{5. COMBINING DOCUMENTS} |
64d5610f ML |
30965 | |
30966 | You may combine the Document with other documents released under this | |
30967 | License, under the terms defined in section 4 above for modified | |
30968 | versions, provided that you include in the combination all of the | |
30969 | Invariant Sections of all of the original documents, unmodified, and | |
30970 | list them all as Invariant Sections of your combined work in its | |
30971 | license notice, and that you preserve all their Warranty Disclaimers. | |
30972 | ||
30973 | The combined work need only contain one copy of this License, and | |
30974 | multiple identical Invariant Sections may be replaced with a single | |
30975 | copy. If there are multiple Invariant Sections with the same name but | |
30976 | different contents, make the title of each such section unique by | |
30977 | adding at the end of it, in parentheses, the name of the original | |
30978 | author or publisher of that section if known, or else a unique number. | |
30979 | Make the same adjustment to the section titles in the list of | |
30980 | Invariant Sections in the license notice of the combined work. | |
30981 | ||
30982 | In the combination, you must combine any sections Entitled “History” | |
30983 | in the various original documents, forming one section Entitled | |
30984 | “History”; likewise combine any sections Entitled “Acknowledgements”, | |
30985 | and any sections Entitled “Dedications”. You must delete all sections | |
30986 | Entitled “Endorsements”. | |
30987 | ||
1acce141 | 30988 | @strong{6. COLLECTIONS OF DOCUMENTS} |
64d5610f ML |
30989 | |
30990 | You may make a collection consisting of the Document and other documents | |
30991 | released under this License, and replace the individual copies of this | |
30992 | License in the various documents with a single copy that is included in | |
30993 | the collection, provided that you follow the rules of this License for | |
30994 | verbatim copying of each of the documents in all other respects. | |
30995 | ||
30996 | You may extract a single document from such a collection, and distribute | |
30997 | it individually under this License, provided you insert a copy of this | |
30998 | License into the extracted document, and follow this License in all | |
30999 | other respects regarding verbatim copying of that document. | |
31000 | ||
1acce141 | 31001 | @strong{7. AGGREGATION WITH INDEPENDENT WORKS} |
64d5610f ML |
31002 | |
31003 | A compilation of the Document or its derivatives with other separate | |
31004 | and independent documents or works, in or on a volume of a storage or | |
31005 | distribution medium, is called an “aggregate” if the copyright | |
31006 | resulting from the compilation is not used to limit the legal rights | |
31007 | of the compilation’s users beyond what the individual works permit. | |
31008 | When the Document is included in an aggregate, this License does not | |
31009 | apply to the other works in the aggregate which are not themselves | |
31010 | derivative works of the Document. | |
31011 | ||
31012 | If the Cover Text requirement of section 3 is applicable to these | |
31013 | copies of the Document, then if the Document is less than one half of | |
31014 | the entire aggregate, the Document’s Cover Texts may be placed on | |
31015 | covers that bracket the Document within the aggregate, or the | |
31016 | electronic equivalent of covers if the Document is in electronic form. | |
31017 | Otherwise they must appear on printed covers that bracket the whole | |
31018 | aggregate. | |
31019 | ||
1acce141 | 31020 | @strong{8. TRANSLATION} |
64d5610f ML |
31021 | |
31022 | Translation is considered a kind of modification, so you may | |
31023 | distribute translations of the Document under the terms of section 4. | |
31024 | Replacing Invariant Sections with translations requires special | |
31025 | permission from their copyright holders, but you may include | |
31026 | translations of some or all Invariant Sections in addition to the | |
31027 | original versions of these Invariant Sections. You may include a | |
31028 | translation of this License, and all the license notices in the | |
31029 | Document, and any Warranty Disclaimers, provided that you also include | |
31030 | the original English version of this License and the original versions | |
31031 | of those notices and disclaimers. In case of a disagreement between | |
31032 | the translation and the original version of this License or a notice | |
31033 | or disclaimer, the original version will prevail. | |
31034 | ||
31035 | If a section in the Document is Entitled “Acknowledgements”, | |
31036 | “Dedications”, or “History”, the requirement (section 4) to Preserve | |
31037 | its Title (section 1) will typically require changing the actual | |
31038 | title. | |
31039 | ||
1acce141 | 31040 | @strong{9. TERMINATION} |
64d5610f ML |
31041 | |
31042 | You may not copy, modify, sublicense, or distribute the Document | |
31043 | except as expressly provided under this License. Any attempt | |
31044 | otherwise to copy, modify, sublicense, or distribute it is void, and | |
31045 | will automatically terminate your rights under this License. | |
31046 | ||
31047 | However, if you cease all violation of this License, then your license | |
31048 | from a particular copyright holder is reinstated (a) provisionally, | |
31049 | unless and until the copyright holder explicitly and finally | |
31050 | terminates your license, and (b) permanently, if the copyright holder | |
31051 | fails to notify you of the violation by some reasonable means prior to | |
31052 | 60 days after the cessation. | |
31053 | ||
31054 | Moreover, your license from a particular copyright holder is | |
31055 | reinstated permanently if the copyright holder notifies you of the | |
31056 | violation by some reasonable means, this is the first time you have | |
31057 | received notice of violation of this License (for any work) from that | |
31058 | copyright holder, and you cure the violation prior to 30 days after | |
31059 | your receipt of the notice. | |
31060 | ||
31061 | Termination of your rights under this section does not terminate the | |
31062 | licenses of parties who have received copies or rights from you under | |
31063 | this License. If your rights have been terminated and not permanently | |
31064 | reinstated, receipt of a copy of some or all of the same material does | |
31065 | not give you any rights to use it. | |
31066 | ||
1acce141 | 31067 | @strong{10. FUTURE REVISIONS OF THIS LICENSE} |
64d5610f ML |
31068 | |
31069 | The Free Software Foundation may publish new, revised versions | |
31070 | of the GNU Free Documentation License from time to time. Such new | |
31071 | versions will be similar in spirit to the present version, but may | |
31072 | differ in detail to address new problems or concerns. See | |
31073 | @indicateurl{https://www.gnu.org/copyleft/}. | |
31074 | ||
31075 | Each version of the License is given a distinguishing version number. | |
31076 | If the Document specifies that a particular numbered version of this | |
31077 | License “or any later version” applies to it, you have the option of | |
31078 | following the terms and conditions either of that specified version or | |
31079 | of any later version that has been published (not as a draft) by the | |
31080 | Free Software Foundation. If the Document does not specify a version | |
31081 | number of this License, you may choose any version ever published (not | |
31082 | as a draft) by the Free Software Foundation. If the Document | |
31083 | specifies that a proxy can decide which future versions of this | |
31084 | License can be used, that proxy’s public statement of acceptance of a | |
31085 | version permanently authorizes you to choose that version for the | |
31086 | Document. | |
31087 | ||
1acce141 | 31088 | @strong{11. RELICENSING} |
64d5610f ML |
31089 | |
31090 | “Massive Multiauthor Collaboration Site” (or “MMC Site”) means any | |
31091 | World Wide Web server that publishes copyrightable works and also | |
31092 | provides prominent facilities for anybody to edit those works. A | |
31093 | public wiki that anybody can edit is an example of such a server. A | |
31094 | “Massive Multiauthor Collaboration” (or “MMC”) contained in the | |
31095 | site means any set of copyrightable works thus published on the MMC | |
31096 | site. | |
31097 | ||
31098 | “CC-BY-SA” means the Creative Commons Attribution-Share Alike 3.0 | |
31099 | license published by Creative Commons Corporation, a not-for-profit | |
31100 | corporation with a principal place of business in San Francisco, | |
31101 | California, as well as future copyleft versions of that license | |
31102 | published by that same organization. | |
31103 | ||
31104 | “Incorporate” means to publish or republish a Document, in whole or | |
31105 | in part, as part of another Document. | |
31106 | ||
31107 | An MMC is “eligible for relicensing” if it is licensed under this | |
31108 | License, and if all works that were first published under this License | |
31109 | somewhere other than this MMC, and subsequently incorporated in whole | |
31110 | or in part into the MMC, (1) had no cover texts or invariant sections, | |
31111 | and (2) were thus incorporated prior to November 1, 2008. | |
31112 | ||
31113 | The operator of an MMC Site may republish an MMC contained in the site | |
31114 | under CC-BY-SA on the same site at any time before August 1, 2009, | |
31115 | provided the MMC is eligible for relicensing. | |
31116 | ||
1acce141 | 31117 | @strong{ADDENDUM: How to use this License for your documents} |
64d5610f ML |
31118 | |
31119 | To use this License in a document you have written, include a copy of | |
31120 | the License in the document and put the following copyright and | |
31121 | license notices just after the title page: | |
31122 | ||
31123 | @quotation | |
31124 | ||
31125 | Copyright © YEAR YOUR NAME. | |
31126 | Permission is granted to copy, distribute and/or modify this document | |
31127 | under the terms of the GNU Free Documentation License, Version 1.3 | |
31128 | or any later version published by the Free Software Foundation; | |
31129 | with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. | |
31130 | A copy of the license is included in the section entitled “GNU | |
31131 | Free Documentation License”. | |
31132 | @end quotation | |
31133 | ||
31134 | If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, | |
31135 | replace the “with … Texts.” line with this: | |
31136 | ||
31137 | @quotation | |
31138 | ||
31139 | with the Invariant Sections being LIST THEIR TITLES, with the | |
31140 | Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. | |
31141 | @end quotation | |
31142 | ||
31143 | If you have Invariant Sections without Cover Texts, or some other | |
31144 | combination of the three, merge those two alternatives to suit the | |
31145 | situation. | |
31146 | ||
31147 | If your document contains nontrivial examples of program code, we | |
31148 | recommend releasing these examples in parallel under your choice of | |
31149 | free software license, such as the GNU General Public License, | |
31150 | to permit their use in free software. | |
31151 | ||
31152 | @node Index,,GNU Free Documentation License,Top | |
31153 | @unnumbered Index | |
31154 | ||
31155 | ||
31156 | @printindex ge | |
31157 | ||
31158 | ||
31159 | @c %**end of body | |
31160 | @bye |