]>
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 | |
6 | @*Generated by Sphinx 5.2.3.@* | |
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 | ||
18 | @c %**end of header | |
19 | ||
20 | @copying | |
21 | @quotation | |
92eeb32d | 22 | GNAT Reference Manual , Jul 10, 2023 |
64d5610f ML |
23 | |
24 | AdaCore | |
25 | ||
74d5206f | 26 | Copyright @copyright{} 2008-2023, Free Software Foundation |
64d5610f ML |
27 | @end quotation |
28 | ||
29 | @end copying | |
30 | ||
31 | @titlepage | |
32 | @title GNAT Reference Manual | |
33 | @insertcopying | |
34 | @end titlepage | |
35 | @contents | |
36 | ||
37 | @c %** start of user preamble | |
38 | ||
39 | @c %** end of user preamble | |
40 | ||
41 | @ifnottex | |
42 | @node Top | |
43 | @top GNAT Reference Manual | |
44 | @insertcopying | |
45 | @end ifnottex | |
46 | ||
47 | @c %**start of body | |
48 | @anchor{gnat_rm doc}@anchor{0} | |
49 | `GNAT, The GNU Ada Development Environment' | |
50 | ||
51 | ||
52 | @include gcc-common.texi | |
53 | GCC version @value{version-GCC}@* | |
54 | AdaCore | |
55 | ||
56 | Permission is granted to copy, distribute and/or modify this document | |
57 | under the terms of the GNU Free Documentation License, Version 1.3 or | |
58 | any later version published by the Free Software Foundation; with no | |
59 | Invariant Sections, with the Front-Cover Texts being “GNAT Reference | |
60 | Manual”, and with no Back-Cover Texts. A copy of the license is | |
61 | included in the section entitled @ref{1,,GNU Free Documentation License}. | |
62 | ||
63 | @menu | |
64 | * About This Guide:: | |
65 | * Implementation Defined Pragmas:: | |
66 | * Implementation Defined Aspects:: | |
67 | * Implementation Defined Attributes:: | |
68 | * Standard and Implementation Defined Restrictions:: | |
69 | * Implementation Advice:: | |
70 | * Implementation Defined Characteristics:: | |
71 | * Intrinsic Subprograms:: | |
72 | * Representation Clauses and Pragmas:: | |
73 | * Standard Library Routines:: | |
74 | * The Implementation of Standard I/O:: | |
75 | * The GNAT Library:: | |
76 | * Interfacing to Other Languages:: | |
77 | * Specialized Needs Annexes:: | |
78 | * Implementation of Specific Ada Features:: | |
79 | * Implementation of Ada 2012 Features:: | |
b71d4b62 | 80 | * GNAT language extensions:: |
64d5610f ML |
81 | * Security Hardening Features:: |
82 | * Obsolescent Features:: | |
83 | * Compatibility and Porting Guide:: | |
84 | * GNU Free Documentation License:: | |
85 | * Index:: | |
86 | ||
87 | @detailmenu | |
88 | --- The Detailed Node Listing --- | |
89 | ||
90 | About This Guide | |
91 | ||
92 | * What This Reference Manual Contains:: | |
93 | * Conventions:: | |
94 | * Related Information:: | |
95 | ||
96 | Implementation Defined Pragmas | |
97 | ||
98 | * Pragma Abort_Defer:: | |
99 | * Pragma Abstract_State:: | |
100 | * Pragma Ada_83:: | |
101 | * Pragma Ada_95:: | |
102 | * Pragma Ada_05:: | |
103 | * Pragma Ada_2005:: | |
104 | * Pragma Ada_12:: | |
105 | * Pragma Ada_2012:: | |
106 | * Pragma Ada_2022:: | |
107 | * Pragma Aggregate_Individually_Assign:: | |
108 | * Pragma Allow_Integer_Address:: | |
109 | * Pragma Annotate:: | |
110 | * Pragma Assert:: | |
111 | * Pragma Assert_And_Cut:: | |
112 | * Pragma Assertion_Policy:: | |
113 | * Pragma Assume:: | |
114 | * Pragma Assume_No_Invalid_Values:: | |
115 | * Pragma Async_Readers:: | |
116 | * Pragma Async_Writers:: | |
117 | * Pragma Attribute_Definition:: | |
118 | * Pragma C_Pass_By_Copy:: | |
119 | * Pragma Check:: | |
120 | * Pragma Check_Float_Overflow:: | |
121 | * Pragma Check_Name:: | |
122 | * Pragma Check_Policy:: | |
123 | * Pragma Comment:: | |
124 | * Pragma Common_Object:: | |
125 | * Pragma Compile_Time_Error:: | |
126 | * Pragma Compile_Time_Warning:: | |
127 | * Pragma Complete_Representation:: | |
128 | * Pragma Complex_Representation:: | |
129 | * Pragma Component_Alignment:: | |
130 | * Pragma Constant_After_Elaboration:: | |
131 | * Pragma Contract_Cases:: | |
132 | * Pragma Convention_Identifier:: | |
133 | * Pragma CPP_Class:: | |
134 | * Pragma CPP_Constructor:: | |
135 | * Pragma CPP_Virtual:: | |
136 | * Pragma CPP_Vtable:: | |
137 | * Pragma CPU:: | |
138 | * Pragma Deadline_Floor:: | |
64d5610f ML |
139 | * Pragma Debug:: |
140 | * Pragma Debug_Policy:: | |
6f089469 | 141 | * Pragma Default_Initial_Condition:: |
64d5610f ML |
142 | * Pragma Default_Scalar_Storage_Order:: |
143 | * Pragma Default_Storage_Pool:: | |
144 | * Pragma Depends:: | |
145 | * Pragma Detect_Blocking:: | |
146 | * Pragma Disable_Atomic_Synchronization:: | |
147 | * Pragma Dispatching_Domain:: | |
148 | * Pragma Effective_Reads:: | |
149 | * Pragma Effective_Writes:: | |
150 | * Pragma Elaboration_Checks:: | |
151 | * Pragma Eliminate:: | |
152 | * Pragma Enable_Atomic_Synchronization:: | |
153 | * Pragma Export_Function:: | |
154 | * Pragma Export_Object:: | |
155 | * Pragma Export_Procedure:: | |
156 | * Pragma Export_Valued_Procedure:: | |
157 | * Pragma Extend_System:: | |
158 | * Pragma Extensions_Allowed:: | |
159 | * Pragma Extensions_Visible:: | |
160 | * Pragma External:: | |
161 | * Pragma External_Name_Casing:: | |
162 | * Pragma Fast_Math:: | |
163 | * Pragma Favor_Top_Level:: | |
164 | * Pragma Finalize_Storage_Only:: | |
165 | * Pragma Float_Representation:: | |
166 | * Pragma Ghost:: | |
167 | * Pragma Global:: | |
168 | * Pragma Ident:: | |
169 | * Pragma Ignore_Pragma:: | |
170 | * Pragma Implementation_Defined:: | |
171 | * Pragma Implemented:: | |
172 | * Pragma Implicit_Packing:: | |
173 | * Pragma Import_Function:: | |
174 | * Pragma Import_Object:: | |
175 | * Pragma Import_Procedure:: | |
176 | * Pragma Import_Valued_Procedure:: | |
177 | * Pragma Independent:: | |
178 | * Pragma Independent_Components:: | |
179 | * Pragma Initial_Condition:: | |
180 | * Pragma Initialize_Scalars:: | |
181 | * Pragma Initializes:: | |
182 | * Pragma Inline_Always:: | |
183 | * Pragma Inline_Generic:: | |
184 | * Pragma Interface:: | |
185 | * Pragma Interface_Name:: | |
186 | * Pragma Interrupt_Handler:: | |
187 | * Pragma Interrupt_State:: | |
188 | * Pragma Invariant:: | |
189 | * Pragma Keep_Names:: | |
190 | * Pragma License:: | |
191 | * Pragma Link_With:: | |
192 | * Pragma Linker_Alias:: | |
193 | * Pragma Linker_Constructor:: | |
194 | * Pragma Linker_Destructor:: | |
195 | * Pragma Linker_Section:: | |
196 | * Pragma Lock_Free:: | |
197 | * Pragma Loop_Invariant:: | |
198 | * Pragma Loop_Optimize:: | |
199 | * Pragma Loop_Variant:: | |
200 | * Pragma Machine_Attribute:: | |
201 | * Pragma Main:: | |
202 | * Pragma Main_Storage:: | |
203 | * Pragma Max_Queue_Length:: | |
204 | * Pragma No_Body:: | |
205 | * Pragma No_Caching:: | |
206 | * Pragma No_Component_Reordering:: | |
207 | * Pragma No_Elaboration_Code_All:: | |
208 | * Pragma No_Heap_Finalization:: | |
209 | * Pragma No_Inline:: | |
210 | * Pragma No_Return:: | |
211 | * Pragma No_Strict_Aliasing:: | |
212 | * Pragma No_Tagged_Streams:: | |
213 | * Pragma Normalize_Scalars:: | |
214 | * Pragma Obsolescent:: | |
215 | * Pragma Optimize_Alignment:: | |
216 | * Pragma Ordered:: | |
217 | * Pragma Overflow_Mode:: | |
218 | * Pragma Overriding_Renamings:: | |
64d5610f | 219 | * Pragma Part_Of:: |
6f089469 | 220 | * Pragma Partition_Elaboration_Policy:: |
64d5610f ML |
221 | * Pragma Passive:: |
222 | * Pragma Persistent_BSS:: | |
223 | * Pragma Post:: | |
224 | * Pragma Postcondition:: | |
225 | * Pragma Post_Class:: | |
226 | * Pragma Pre:: | |
227 | * Pragma Precondition:: | |
228 | * Pragma Predicate:: | |
229 | * Pragma Predicate_Failure:: | |
230 | * Pragma Preelaborable_Initialization:: | |
231 | * Pragma Prefix_Exception_Messages:: | |
232 | * Pragma Pre_Class:: | |
233 | * Pragma Priority_Specific_Dispatching:: | |
234 | * Pragma Profile:: | |
235 | * Pragma Profile_Warnings:: | |
236 | * Pragma Propagate_Exceptions:: | |
237 | * Pragma Provide_Shift_Operators:: | |
238 | * Pragma Psect_Object:: | |
239 | * Pragma Pure_Function:: | |
240 | * Pragma Rational:: | |
241 | * Pragma Ravenscar:: | |
242 | * Pragma Refined_Depends:: | |
243 | * Pragma Refined_Global:: | |
244 | * Pragma Refined_Post:: | |
245 | * Pragma Refined_State:: | |
246 | * Pragma Relative_Deadline:: | |
247 | * Pragma Remote_Access_Type:: | |
248 | * Pragma Rename_Pragma:: | |
249 | * Pragma Restricted_Run_Time:: | |
250 | * Pragma Restriction_Warnings:: | |
251 | * Pragma Reviewable:: | |
252 | * Pragma Secondary_Stack_Size:: | |
253 | * Pragma Share_Generic:: | |
254 | * Pragma Shared:: | |
255 | * Pragma Short_Circuit_And_Or:: | |
256 | * Pragma Short_Descriptors:: | |
257 | * Pragma Simple_Storage_Pool_Type:: | |
258 | * Pragma Source_File_Name:: | |
259 | * Pragma Source_File_Name_Project:: | |
260 | * Pragma Source_Reference:: | |
261 | * Pragma SPARK_Mode:: | |
262 | * Pragma Static_Elaboration_Desired:: | |
263 | * Pragma Stream_Convert:: | |
264 | * Pragma Style_Checks:: | |
265 | * Pragma Subtitle:: | |
266 | * Pragma Suppress:: | |
267 | * Pragma Suppress_All:: | |
268 | * Pragma Suppress_Debug_Info:: | |
269 | * Pragma Suppress_Exception_Locations:: | |
270 | * Pragma Suppress_Initialization:: | |
271 | * Pragma Task_Name:: | |
272 | * Pragma Task_Storage:: | |
273 | * Pragma Test_Case:: | |
274 | * Pragma Thread_Local_Storage:: | |
275 | * Pragma Time_Slice:: | |
276 | * Pragma Title:: | |
277 | * Pragma Type_Invariant:: | |
278 | * Pragma Type_Invariant_Class:: | |
279 | * Pragma Unchecked_Union:: | |
280 | * Pragma Unevaluated_Use_Of_Old:: | |
281 | * Pragma Unimplemented_Unit:: | |
282 | * Pragma Universal_Aliasing:: | |
283 | * Pragma Unmodified:: | |
284 | * Pragma Unreferenced:: | |
285 | * Pragma Unreferenced_Objects:: | |
286 | * Pragma Unreserve_All_Interrupts:: | |
287 | * Pragma Unsuppress:: | |
64d5610f | 288 | * Pragma Unused:: |
6f089469 | 289 | * Pragma Use_VADS_Size:: |
64d5610f ML |
290 | * Pragma Validity_Checks:: |
291 | * Pragma Volatile:: | |
292 | * Pragma Volatile_Full_Access:: | |
293 | * Pragma Volatile_Function:: | |
294 | * Pragma Warning_As_Error:: | |
295 | * Pragma Warnings:: | |
296 | * Pragma Weak_External:: | |
297 | * Pragma Wide_Character_Encoding:: | |
298 | ||
299 | Implementation Defined Aspects | |
300 | ||
301 | * Aspect Abstract_State:: | |
302 | * Aspect Annotate:: | |
303 | * Aspect Async_Readers:: | |
304 | * Aspect Async_Writers:: | |
305 | * Aspect Constant_After_Elaboration:: | |
306 | * Aspect Contract_Cases:: | |
307 | * Aspect Depends:: | |
308 | * Aspect Default_Initial_Condition:: | |
309 | * Aspect Dimension:: | |
310 | * Aspect Dimension_System:: | |
311 | * Aspect Disable_Controlled:: | |
312 | * Aspect Effective_Reads:: | |
313 | * Aspect Effective_Writes:: | |
314 | * Aspect Extensions_Visible:: | |
315 | * Aspect Favor_Top_Level:: | |
316 | * Aspect Ghost:: | |
067d80d8 | 317 | * Aspect Ghost_Predicate:: |
64d5610f ML |
318 | * Aspect Global:: |
319 | * Aspect Initial_Condition:: | |
320 | * Aspect Initializes:: | |
321 | * Aspect Inline_Always:: | |
322 | * Aspect Invariant:: | |
323 | * Aspect Invariant’Class:: | |
324 | * Aspect Iterable:: | |
325 | * Aspect Linker_Section:: | |
326 | * Aspect Lock_Free:: | |
327 | * Aspect Max_Queue_Length:: | |
328 | * Aspect No_Caching:: | |
329 | * Aspect No_Elaboration_Code_All:: | |
330 | * Aspect No_Inline:: | |
331 | * Aspect No_Tagged_Streams:: | |
332 | * Aspect No_Task_Parts:: | |
333 | * Aspect Object_Size:: | |
334 | * Aspect Obsolescent:: | |
335 | * Aspect Part_Of:: | |
336 | * Aspect Persistent_BSS:: | |
337 | * Aspect Predicate:: | |
338 | * Aspect Pure_Function:: | |
339 | * Aspect Refined_Depends:: | |
340 | * Aspect Refined_Global:: | |
341 | * Aspect Refined_Post:: | |
342 | * Aspect Refined_State:: | |
343 | * Aspect Relaxed_Initialization:: | |
344 | * Aspect Remote_Access_Type:: | |
345 | * Aspect Secondary_Stack_Size:: | |
346 | * Aspect Scalar_Storage_Order:: | |
347 | * Aspect Shared:: | |
348 | * Aspect Simple_Storage_Pool:: | |
349 | * Aspect Simple_Storage_Pool_Type:: | |
350 | * Aspect SPARK_Mode:: | |
351 | * Aspect Suppress_Debug_Info:: | |
352 | * Aspect Suppress_Initialization:: | |
353 | * Aspect Test_Case:: | |
354 | * Aspect Thread_Local_Storage:: | |
355 | * Aspect Universal_Aliasing:: | |
356 | * Aspect Unmodified:: | |
357 | * Aspect Unreferenced:: | |
358 | * Aspect Unreferenced_Objects:: | |
359 | * Aspect Value_Size:: | |
360 | * Aspect Volatile_Full_Access:: | |
361 | * Aspect Volatile_Function:: | |
362 | * Aspect Warnings:: | |
363 | ||
364 | Implementation Defined Attributes | |
365 | ||
366 | * Attribute Abort_Signal:: | |
367 | * Attribute Address_Size:: | |
368 | * Attribute Asm_Input:: | |
369 | * Attribute Asm_Output:: | |
370 | * Attribute Atomic_Always_Lock_Free:: | |
371 | * Attribute Bit:: | |
372 | * Attribute Bit_Position:: | |
373 | * Attribute Code_Address:: | |
374 | * Attribute Compiler_Version:: | |
375 | * Attribute Constrained:: | |
376 | * Attribute Default_Bit_Order:: | |
377 | * Attribute Default_Scalar_Storage_Order:: | |
378 | * Attribute Deref:: | |
379 | * Attribute Descriptor_Size:: | |
380 | * Attribute Elaborated:: | |
381 | * Attribute Elab_Body:: | |
382 | * Attribute Elab_Spec:: | |
383 | * Attribute Elab_Subp_Body:: | |
384 | * Attribute Emax:: | |
385 | * Attribute Enabled:: | |
386 | * Attribute Enum_Rep:: | |
387 | * Attribute Enum_Val:: | |
388 | * Attribute Epsilon:: | |
389 | * Attribute Fast_Math:: | |
390 | * Attribute Finalization_Size:: | |
391 | * Attribute Fixed_Value:: | |
392 | * Attribute From_Any:: | |
393 | * Attribute Has_Access_Values:: | |
394 | * Attribute Has_Discriminants:: | |
395 | * Attribute Has_Tagged_Values:: | |
396 | * Attribute Img:: | |
397 | * Attribute Initialized:: | |
398 | * Attribute Integer_Value:: | |
399 | * Attribute Invalid_Value:: | |
400 | * Attribute Iterable:: | |
401 | * Attribute Large:: | |
402 | * Attribute Library_Level:: | |
403 | * Attribute Loop_Entry:: | |
404 | * Attribute Machine_Size:: | |
405 | * Attribute Mantissa:: | |
406 | * Attribute Maximum_Alignment:: | |
407 | * Attribute Max_Integer_Size:: | |
408 | * Attribute Mechanism_Code:: | |
409 | * Attribute Null_Parameter:: | |
410 | * Attribute Object_Size:: | |
411 | * Attribute Old:: | |
412 | * Attribute Passed_By_Reference:: | |
413 | * Attribute Pool_Address:: | |
414 | * Attribute Range_Length:: | |
415 | * Attribute Restriction_Set:: | |
416 | * Attribute Result:: | |
417 | * Attribute Safe_Emax:: | |
418 | * Attribute Safe_Large:: | |
419 | * Attribute Safe_Small:: | |
420 | * Attribute Scalar_Storage_Order:: | |
421 | * Attribute Simple_Storage_Pool:: | |
422 | * Attribute Small:: | |
423 | * Attribute Small_Denominator:: | |
424 | * Attribute Small_Numerator:: | |
425 | * Attribute Storage_Unit:: | |
426 | * Attribute Stub_Type:: | |
427 | * Attribute System_Allocator_Alignment:: | |
428 | * Attribute Target_Name:: | |
429 | * Attribute To_Address:: | |
430 | * Attribute To_Any:: | |
431 | * Attribute Type_Class:: | |
432 | * Attribute Type_Key:: | |
433 | * Attribute TypeCode:: | |
434 | * Attribute Unconstrained_Array:: | |
435 | * Attribute Universal_Literal_String:: | |
436 | * Attribute Unrestricted_Access:: | |
437 | * Attribute Update:: | |
438 | * Attribute Valid_Value:: | |
439 | * Attribute Valid_Scalars:: | |
440 | * Attribute VADS_Size:: | |
441 | * Attribute Value_Size:: | |
442 | * Attribute Wchar_T_Size:: | |
443 | * Attribute Word_Size:: | |
444 | ||
445 | Standard and Implementation Defined Restrictions | |
446 | ||
447 | * Partition-Wide Restrictions:: | |
448 | * Program Unit Level Restrictions:: | |
449 | ||
450 | Partition-Wide Restrictions | |
451 | ||
452 | * Immediate_Reclamation:: | |
453 | * Max_Asynchronous_Select_Nesting:: | |
454 | * Max_Entry_Queue_Length:: | |
455 | * Max_Protected_Entries:: | |
456 | * Max_Select_Alternatives:: | |
457 | * Max_Storage_At_Blocking:: | |
458 | * Max_Task_Entries:: | |
459 | * Max_Tasks:: | |
460 | * No_Abort_Statements:: | |
461 | * No_Access_Parameter_Allocators:: | |
462 | * No_Access_Subprograms:: | |
463 | * No_Allocators:: | |
464 | * No_Anonymous_Allocators:: | |
465 | * No_Asynchronous_Control:: | |
466 | * No_Calendar:: | |
467 | * No_Coextensions:: | |
468 | * No_Default_Initialization:: | |
469 | * No_Delay:: | |
470 | * No_Dependence:: | |
471 | * No_Direct_Boolean_Operators:: | |
472 | * No_Dispatch:: | |
473 | * No_Dispatching_Calls:: | |
474 | * No_Dynamic_Attachment:: | |
475 | * No_Dynamic_Priorities:: | |
476 | * No_Entry_Calls_In_Elaboration_Code:: | |
477 | * No_Enumeration_Maps:: | |
478 | * No_Exception_Handlers:: | |
479 | * No_Exception_Propagation:: | |
480 | * No_Exception_Registration:: | |
481 | * No_Exceptions:: | |
482 | * No_Finalization:: | |
483 | * No_Fixed_Point:: | |
484 | * No_Floating_Point:: | |
485 | * No_Implicit_Conditionals:: | |
486 | * No_Implicit_Dynamic_Code:: | |
487 | * No_Implicit_Heap_Allocations:: | |
488 | * No_Implicit_Protected_Object_Allocations:: | |
489 | * No_Implicit_Task_Allocations:: | |
490 | * No_Initialize_Scalars:: | |
491 | * No_IO:: | |
492 | * No_Local_Allocators:: | |
493 | * No_Local_Protected_Objects:: | |
494 | * No_Local_Tagged_Types:: | |
495 | * No_Local_Timing_Events:: | |
496 | * No_Long_Long_Integers:: | |
497 | * No_Multiple_Elaboration:: | |
498 | * No_Nested_Finalization:: | |
499 | * No_Protected_Type_Allocators:: | |
500 | * No_Protected_Types:: | |
501 | * No_Recursion:: | |
502 | * No_Reentrancy:: | |
503 | * No_Relative_Delay:: | |
504 | * No_Requeue_Statements:: | |
505 | * No_Secondary_Stack:: | |
506 | * No_Select_Statements:: | |
507 | * No_Specific_Termination_Handlers:: | |
508 | * No_Specification_of_Aspect:: | |
509 | * No_Standard_Allocators_After_Elaboration:: | |
510 | * No_Standard_Storage_Pools:: | |
511 | * No_Stream_Optimizations:: | |
512 | * No_Streams:: | |
513 | * No_Tagged_Type_Registration:: | |
514 | * No_Task_Allocators:: | |
515 | * No_Task_At_Interrupt_Priority:: | |
516 | * No_Task_Attributes_Package:: | |
517 | * No_Task_Hierarchy:: | |
518 | * No_Task_Termination:: | |
519 | * No_Tasking:: | |
520 | * No_Terminate_Alternatives:: | |
521 | * No_Unchecked_Access:: | |
522 | * No_Unchecked_Conversion:: | |
523 | * No_Unchecked_Deallocation:: | |
73918baf | 524 | * No_Use_Of_Attribute:: |
64d5610f | 525 | * No_Use_Of_Entity:: |
73918baf | 526 | * No_Use_Of_Pragma:: |
64d5610f ML |
527 | * Pure_Barriers:: |
528 | * Simple_Barriers:: | |
529 | * Static_Priorities:: | |
530 | * Static_Storage_Size:: | |
531 | ||
532 | Program Unit Level Restrictions | |
533 | ||
534 | * No_Elaboration_Code:: | |
535 | * No_Dynamic_Accessibility_Checks:: | |
536 | * No_Dynamic_Sized_Objects:: | |
537 | * No_Entry_Queue:: | |
538 | * No_Implementation_Aspect_Specifications:: | |
539 | * No_Implementation_Attributes:: | |
540 | * No_Implementation_Identifiers:: | |
541 | * No_Implementation_Pragmas:: | |
542 | * No_Implementation_Restrictions:: | |
543 | * No_Implementation_Units:: | |
544 | * No_Implicit_Aliasing:: | |
545 | * No_Implicit_Loops:: | |
546 | * No_Obsolescent_Features:: | |
547 | * No_Wide_Characters:: | |
548 | * Static_Dispatch_Tables:: | |
549 | * SPARK_05:: | |
550 | ||
551 | Implementation Advice | |
552 | ||
553 | * RM 1.1.3(20); Error Detection: RM 1 1 3 20 Error Detection. | |
554 | * RM 1.1.3(31); Child Units: RM 1 1 3 31 Child Units. | |
555 | * RM 1.1.5(12); Bounded Errors: RM 1 1 5 12 Bounded Errors. | |
556 | * RM 2.8(16); Pragmas: RM 2 8 16 Pragmas. | |
557 | * RM 2.8(17-19); Pragmas: RM 2 8 17-19 Pragmas. | |
558 | * RM 3.5.2(5); Alternative Character Sets: RM 3 5 2 5 Alternative Character Sets. | |
559 | * RM 3.5.4(28); Integer Types: RM 3 5 4 28 Integer Types. | |
560 | * RM 3.5.4(29); Integer Types: RM 3 5 4 29 Integer Types. | |
561 | * RM 3.5.5(8); Enumeration Values: RM 3 5 5 8 Enumeration Values. | |
562 | * RM 3.5.7(17); Float Types: RM 3 5 7 17 Float Types. | |
563 | * RM 3.6.2(11); Multidimensional Arrays: RM 3 6 2 11 Multidimensional Arrays. | |
564 | * RM 9.6(30-31); Duration’Small: RM 9 6 30-31 Duration’Small. | |
565 | * RM 10.2.1(12); Consistent Representation: RM 10 2 1 12 Consistent Representation. | |
566 | * RM 11.4.1(19); Exception Information: RM 11 4 1 19 Exception Information. | |
567 | * RM 11.5(28); Suppression of Checks: RM 11 5 28 Suppression of Checks. | |
568 | * RM 13.1 (21-24); Representation Clauses: RM 13 1 21-24 Representation Clauses. | |
569 | * RM 13.2(6-8); Packed Types: RM 13 2 6-8 Packed Types. | |
570 | * RM 13.3(14-19); Address Clauses: RM 13 3 14-19 Address Clauses. | |
571 | * RM 13.3(29-35); Alignment Clauses: RM 13 3 29-35 Alignment Clauses. | |
572 | * RM 13.3(42-43); Size Clauses: RM 13 3 42-43 Size Clauses. | |
573 | * RM 13.3(50-56); Size Clauses: RM 13 3 50-56 Size Clauses. | |
574 | * RM 13.3(71-73); Component Size Clauses: RM 13 3 71-73 Component Size Clauses. | |
575 | * RM 13.4(9-10); Enumeration Representation Clauses: RM 13 4 9-10 Enumeration Representation Clauses. | |
576 | * RM 13.5.1(17-22); Record Representation Clauses: RM 13 5 1 17-22 Record Representation Clauses. | |
577 | * RM 13.5.2(5); Storage Place Attributes: RM 13 5 2 5 Storage Place Attributes. | |
578 | * RM 13.5.3(7-8); Bit Ordering: RM 13 5 3 7-8 Bit Ordering. | |
579 | * RM 13.7(37); Address as Private: RM 13 7 37 Address as Private. | |
580 | * RM 13.7.1(16); Address Operations: RM 13 7 1 16 Address Operations. | |
581 | * RM 13.9(14-17); Unchecked Conversion: RM 13 9 14-17 Unchecked Conversion. | |
582 | * RM 13.11(23-25); Implicit Heap Usage: RM 13 11 23-25 Implicit Heap Usage. | |
583 | * RM 13.11.2(17); Unchecked Deallocation: RM 13 11 2 17 Unchecked Deallocation. | |
584 | * RM 13.13.2(1.6); Stream Oriented Attributes: RM 13 13 2 1 6 Stream Oriented Attributes. | |
585 | * RM A.1(52); Names of Predefined Numeric Types: RM A 1 52 Names of Predefined Numeric Types. | |
586 | * RM A.3.2(49); Ada.Characters.Handling: RM A 3 2 49 Ada Characters Handling. | |
587 | * RM A.4.4(106); Bounded-Length String Handling: RM A 4 4 106 Bounded-Length String Handling. | |
588 | * RM A.5.2(46-47); Random Number Generation: RM A 5 2 46-47 Random Number Generation. | |
589 | * RM A.10.7(23); Get_Immediate: RM A 10 7 23 Get_Immediate. | |
590 | * RM A.18; Containers: RM A 18 Containers. | |
591 | * RM B.1(39-41); Pragma Export: RM B 1 39-41 Pragma Export. | |
592 | * RM B.2(12-13); Package Interfaces: RM B 2 12-13 Package Interfaces. | |
593 | * RM B.3(63-71); Interfacing with C: RM B 3 63-71 Interfacing with C. | |
594 | * RM B.4(95-98); Interfacing with COBOL: RM B 4 95-98 Interfacing with COBOL. | |
595 | * RM B.5(22-26); Interfacing with Fortran: RM B 5 22-26 Interfacing with Fortran. | |
596 | * RM C.1(3-5); Access to Machine Operations: RM C 1 3-5 Access to Machine Operations. | |
597 | * RM C.1(10-16); Access to Machine Operations: RM C 1 10-16 Access to Machine Operations. | |
598 | * RM C.3(28); Interrupt Support: RM C 3 28 Interrupt Support. | |
599 | * RM C.3.1(20-21); Protected Procedure Handlers: RM C 3 1 20-21 Protected Procedure Handlers. | |
600 | * RM C.3.2(25); Package Interrupts: RM C 3 2 25 Package Interrupts. | |
601 | * RM C.4(14); Pre-elaboration Requirements: RM C 4 14 Pre-elaboration Requirements. | |
602 | * RM C.5(8); Pragma Discard_Names: RM C 5 8 Pragma Discard_Names. | |
603 | * RM C.7.2(30); The Package Task_Attributes: RM C 7 2 30 The Package Task_Attributes. | |
604 | * RM D.3(17); Locking Policies: RM D 3 17 Locking Policies. | |
605 | * RM D.4(16); Entry Queuing Policies: RM D 4 16 Entry Queuing Policies. | |
606 | * RM D.6(9-10); Preemptive Abort: RM D 6 9-10 Preemptive Abort. | |
607 | * RM D.7(21); Tasking Restrictions: RM D 7 21 Tasking Restrictions. | |
608 | * RM D.8(47-49); Monotonic Time: RM D 8 47-49 Monotonic Time. | |
609 | * RM E.5(28-29); Partition Communication Subsystem: RM E 5 28-29 Partition Communication Subsystem. | |
610 | * RM F(7); COBOL Support: RM F 7 COBOL Support. | |
611 | * RM F.1(2); Decimal Radix Support: RM F 1 2 Decimal Radix Support. | |
612 | * RM G; Numerics: RM G Numerics. | |
613 | * RM G.1.1(56-58); Complex Types: RM G 1 1 56-58 Complex Types. | |
614 | * RM G.1.2(49); Complex Elementary Functions: RM G 1 2 49 Complex Elementary Functions. | |
615 | * RM G.2.4(19); Accuracy Requirements: RM G 2 4 19 Accuracy Requirements. | |
616 | * RM G.2.6(15); Complex Arithmetic Accuracy: RM G 2 6 15 Complex Arithmetic Accuracy. | |
617 | * RM H.6(15/2); Pragma Partition_Elaboration_Policy: RM H 6 15/2 Pragma Partition_Elaboration_Policy. | |
618 | ||
619 | Intrinsic Subprograms | |
620 | ||
621 | * Intrinsic Operators:: | |
622 | * Compilation_ISO_Date:: | |
623 | * Compilation_Date:: | |
624 | * Compilation_Time:: | |
625 | * Enclosing_Entity:: | |
626 | * Exception_Information:: | |
627 | * Exception_Message:: | |
628 | * Exception_Name:: | |
629 | * File:: | |
630 | * Line:: | |
631 | * Shifts and Rotates:: | |
632 | * Source_Location:: | |
633 | ||
634 | Representation Clauses and Pragmas | |
635 | ||
636 | * Alignment Clauses:: | |
637 | * Size Clauses:: | |
638 | * Storage_Size Clauses:: | |
639 | * Size of Variant Record Objects:: | |
640 | * Biased Representation:: | |
641 | * Value_Size and Object_Size Clauses:: | |
642 | * Component_Size Clauses:: | |
643 | * Bit_Order Clauses:: | |
644 | * Effect of Bit_Order on Byte Ordering:: | |
645 | * Pragma Pack for Arrays:: | |
646 | * Pragma Pack for Records:: | |
647 | * Record Representation Clauses:: | |
648 | * Handling of Records with Holes:: | |
649 | * Enumeration Clauses:: | |
650 | * Address Clauses:: | |
651 | * Use of Address Clauses for Memory-Mapped I/O:: | |
652 | * Effect of Convention on Representation:: | |
653 | * Conventions and Anonymous Access Types:: | |
654 | * Determining the Representations chosen by GNAT:: | |
655 | ||
656 | The Implementation of Standard I/O | |
657 | ||
658 | * Standard I/O Packages:: | |
659 | * FORM Strings:: | |
660 | * Direct_IO:: | |
661 | * Sequential_IO:: | |
662 | * Text_IO:: | |
663 | * Wide_Text_IO:: | |
664 | * Wide_Wide_Text_IO:: | |
665 | * Stream_IO:: | |
666 | * Text Translation:: | |
667 | * Shared Files:: | |
668 | * Filenames encoding:: | |
669 | * File content encoding:: | |
670 | * Open Modes:: | |
671 | * Operations on C Streams:: | |
672 | * Interfacing to C Streams:: | |
673 | ||
674 | Text_IO | |
675 | ||
676 | * Stream Pointer Positioning:: | |
677 | * Reading and Writing Non-Regular Files:: | |
678 | * Get_Immediate:: | |
679 | * Treating Text_IO Files as Streams:: | |
680 | * Text_IO Extensions:: | |
681 | * Text_IO Facilities for Unbounded Strings:: | |
682 | ||
683 | Wide_Text_IO | |
684 | ||
685 | * Stream Pointer Positioning: Stream Pointer Positioning<2>. | |
686 | * Reading and Writing Non-Regular Files: Reading and Writing Non-Regular Files<2>. | |
687 | ||
688 | Wide_Wide_Text_IO | |
689 | ||
690 | * Stream Pointer Positioning: Stream Pointer Positioning<3>. | |
691 | * Reading and Writing Non-Regular Files: Reading and Writing Non-Regular Files<3>. | |
692 | ||
693 | The GNAT Library | |
694 | ||
695 | * Ada.Characters.Latin_9 (a-chlat9.ads): Ada Characters Latin_9 a-chlat9 ads. | |
696 | * Ada.Characters.Wide_Latin_1 (a-cwila1.ads): Ada Characters Wide_Latin_1 a-cwila1 ads. | |
eeba836b | 697 | * Ada.Characters.Wide_Latin_9 (a-cwila9.ads): Ada Characters Wide_Latin_9 a-cwila9 ads. |
64d5610f ML |
698 | * Ada.Characters.Wide_Wide_Latin_1 (a-chzla1.ads): Ada Characters Wide_Wide_Latin_1 a-chzla1 ads. |
699 | * Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads): Ada Characters Wide_Wide_Latin_9 a-chzla9 ads. | |
700 | * Ada.Containers.Bounded_Holders (a-coboho.ads): Ada Containers Bounded_Holders a-coboho ads. | |
701 | * Ada.Command_Line.Environment (a-colien.ads): Ada Command_Line Environment a-colien ads. | |
702 | * Ada.Command_Line.Remove (a-colire.ads): Ada Command_Line Remove a-colire ads. | |
703 | * Ada.Command_Line.Response_File (a-clrefi.ads): Ada Command_Line Response_File a-clrefi ads. | |
704 | * Ada.Direct_IO.C_Streams (a-diocst.ads): Ada Direct_IO C_Streams a-diocst ads. | |
705 | * Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads): Ada Exceptions Is_Null_Occurrence a-einuoc ads. | |
706 | * Ada.Exceptions.Last_Chance_Handler (a-elchha.ads): Ada Exceptions Last_Chance_Handler a-elchha ads. | |
707 | * Ada.Exceptions.Traceback (a-exctra.ads): Ada Exceptions Traceback a-exctra ads. | |
708 | * Ada.Sequential_IO.C_Streams (a-siocst.ads): Ada Sequential_IO C_Streams a-siocst ads. | |
709 | * Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads): Ada Streams Stream_IO C_Streams a-ssicst ads. | |
710 | * Ada.Strings.Unbounded.Text_IO (a-suteio.ads): Ada Strings Unbounded Text_IO a-suteio ads. | |
711 | * Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads): Ada Strings Wide_Unbounded Wide_Text_IO a-swuwti ads. | |
712 | * Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads): Ada Strings Wide_Wide_Unbounded Wide_Wide_Text_IO a-szuzti ads. | |
713 | * Ada.Task_Initialization (a-tasini.ads): Ada Task_Initialization a-tasini ads. | |
714 | * Ada.Text_IO.C_Streams (a-tiocst.ads): Ada Text_IO C_Streams a-tiocst ads. | |
715 | * Ada.Text_IO.Reset_Standard_Files (a-tirsfi.ads): Ada Text_IO Reset_Standard_Files a-tirsfi ads. | |
716 | * Ada.Wide_Characters.Unicode (a-wichun.ads): Ada Wide_Characters Unicode a-wichun ads. | |
717 | * Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads): Ada Wide_Text_IO C_Streams a-wtcstr ads. | |
718 | * Ada.Wide_Text_IO.Reset_Standard_Files (a-wrstfi.ads): Ada Wide_Text_IO Reset_Standard_Files a-wrstfi ads. | |
719 | * Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads): Ada Wide_Wide_Characters Unicode a-zchuni ads. | |
720 | * Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads): Ada Wide_Wide_Text_IO C_Streams a-ztcstr ads. | |
721 | * Ada.Wide_Wide_Text_IO.Reset_Standard_Files (a-zrstfi.ads): Ada Wide_Wide_Text_IO Reset_Standard_Files a-zrstfi ads. | |
722 | * GNAT.Altivec (g-altive.ads): GNAT Altivec g-altive ads. | |
723 | * GNAT.Altivec.Conversions (g-altcon.ads): GNAT Altivec Conversions g-altcon ads. | |
724 | * GNAT.Altivec.Vector_Operations (g-alveop.ads): GNAT Altivec Vector_Operations g-alveop ads. | |
725 | * GNAT.Altivec.Vector_Types (g-alvety.ads): GNAT Altivec Vector_Types g-alvety ads. | |
726 | * GNAT.Altivec.Vector_Views (g-alvevi.ads): GNAT Altivec Vector_Views g-alvevi ads. | |
727 | * GNAT.Array_Split (g-arrspl.ads): GNAT Array_Split g-arrspl ads. | |
728 | * GNAT.AWK (g-awk.ads): GNAT AWK g-awk ads. | |
729 | * GNAT.Binary_Search (g-binsea.ads): GNAT Binary_Search g-binsea ads. | |
730 | * GNAT.Bind_Environment (g-binenv.ads): GNAT Bind_Environment g-binenv ads. | |
731 | * GNAT.Branch_Prediction (g-brapre.ads): GNAT Branch_Prediction g-brapre ads. | |
732 | * GNAT.Bounded_Buffers (g-boubuf.ads): GNAT Bounded_Buffers g-boubuf ads. | |
733 | * GNAT.Bounded_Mailboxes (g-boumai.ads): GNAT Bounded_Mailboxes g-boumai ads. | |
734 | * GNAT.Bubble_Sort (g-bubsor.ads): GNAT Bubble_Sort g-bubsor ads. | |
735 | * GNAT.Bubble_Sort_A (g-busora.ads): GNAT Bubble_Sort_A g-busora ads. | |
736 | * GNAT.Bubble_Sort_G (g-busorg.ads): GNAT Bubble_Sort_G g-busorg ads. | |
737 | * GNAT.Byte_Order_Mark (g-byorma.ads): GNAT Byte_Order_Mark g-byorma ads. | |
738 | * GNAT.Byte_Swapping (g-bytswa.ads): GNAT Byte_Swapping g-bytswa ads. | |
739 | * GNAT.Calendar (g-calend.ads): GNAT Calendar g-calend ads. | |
740 | * GNAT.Calendar.Time_IO (g-catiio.ads): GNAT Calendar Time_IO g-catiio ads. | |
741 | * GNAT.CRC32 (g-crc32.ads): GNAT CRC32 g-crc32 ads. | |
742 | * GNAT.Case_Util (g-casuti.ads): GNAT Case_Util g-casuti ads. | |
743 | * GNAT.CGI (g-cgi.ads): GNAT CGI g-cgi ads. | |
744 | * GNAT.CGI.Cookie (g-cgicoo.ads): GNAT CGI Cookie g-cgicoo ads. | |
745 | * GNAT.CGI.Debug (g-cgideb.ads): GNAT CGI Debug g-cgideb ads. | |
746 | * GNAT.Command_Line (g-comlin.ads): GNAT Command_Line g-comlin ads. | |
747 | * GNAT.Compiler_Version (g-comver.ads): GNAT Compiler_Version g-comver ads. | |
748 | * GNAT.Ctrl_C (g-ctrl_c.ads): GNAT Ctrl_C g-ctrl_c ads. | |
749 | * GNAT.Current_Exception (g-curexc.ads): GNAT Current_Exception g-curexc ads. | |
750 | * GNAT.Debug_Pools (g-debpoo.ads): GNAT Debug_Pools g-debpoo ads. | |
751 | * GNAT.Debug_Utilities (g-debuti.ads): GNAT Debug_Utilities g-debuti ads. | |
752 | * GNAT.Decode_String (g-decstr.ads): GNAT Decode_String g-decstr ads. | |
753 | * GNAT.Decode_UTF8_String (g-deutst.ads): GNAT Decode_UTF8_String g-deutst ads. | |
754 | * GNAT.Directory_Operations (g-dirope.ads): GNAT Directory_Operations g-dirope ads. | |
755 | * GNAT.Directory_Operations.Iteration (g-diopit.ads): GNAT Directory_Operations Iteration g-diopit ads. | |
756 | * GNAT.Dynamic_HTables (g-dynhta.ads): GNAT Dynamic_HTables g-dynhta ads. | |
757 | * GNAT.Dynamic_Tables (g-dyntab.ads): GNAT Dynamic_Tables g-dyntab ads. | |
758 | * GNAT.Encode_String (g-encstr.ads): GNAT Encode_String g-encstr ads. | |
759 | * GNAT.Encode_UTF8_String (g-enutst.ads): GNAT Encode_UTF8_String g-enutst ads. | |
760 | * GNAT.Exception_Actions (g-excact.ads): GNAT Exception_Actions g-excact ads. | |
761 | * GNAT.Exception_Traces (g-exctra.ads): GNAT Exception_Traces g-exctra ads. | |
762 | * GNAT.Exceptions (g-except.ads): GNAT Exceptions g-except ads. | |
763 | * GNAT.Expect (g-expect.ads): GNAT Expect g-expect ads. | |
764 | * GNAT.Expect.TTY (g-exptty.ads): GNAT Expect TTY g-exptty ads. | |
765 | * GNAT.Float_Control (g-flocon.ads): GNAT Float_Control g-flocon ads. | |
766 | * GNAT.Formatted_String (g-forstr.ads): GNAT Formatted_String g-forstr ads. | |
767 | * GNAT.Generic_Fast_Math_Functions (g-gfmafu.ads): GNAT Generic_Fast_Math_Functions g-gfmafu ads. | |
768 | * GNAT.Heap_Sort (g-heasor.ads): GNAT Heap_Sort g-heasor ads. | |
769 | * GNAT.Heap_Sort_A (g-hesora.ads): GNAT Heap_Sort_A g-hesora ads. | |
770 | * GNAT.Heap_Sort_G (g-hesorg.ads): GNAT Heap_Sort_G g-hesorg ads. | |
771 | * GNAT.HTable (g-htable.ads): GNAT HTable g-htable ads. | |
772 | * GNAT.IO (g-io.ads): GNAT IO g-io ads. | |
773 | * GNAT.IO_Aux (g-io_aux.ads): GNAT IO_Aux g-io_aux ads. | |
774 | * GNAT.Lock_Files (g-locfil.ads): GNAT Lock_Files g-locfil ads. | |
775 | * GNAT.MBBS_Discrete_Random (g-mbdira.ads): GNAT MBBS_Discrete_Random g-mbdira ads. | |
776 | * GNAT.MBBS_Float_Random (g-mbflra.ads): GNAT MBBS_Float_Random g-mbflra ads. | |
777 | * GNAT.MD5 (g-md5.ads): GNAT MD5 g-md5 ads. | |
778 | * GNAT.Memory_Dump (g-memdum.ads): GNAT Memory_Dump g-memdum ads. | |
779 | * GNAT.Most_Recent_Exception (g-moreex.ads): GNAT Most_Recent_Exception g-moreex ads. | |
780 | * GNAT.OS_Lib (g-os_lib.ads): GNAT OS_Lib g-os_lib ads. | |
781 | * GNAT.Perfect_Hash_Generators (g-pehage.ads): GNAT Perfect_Hash_Generators g-pehage ads. | |
782 | * GNAT.Random_Numbers (g-rannum.ads): GNAT Random_Numbers g-rannum ads. | |
783 | * GNAT.Regexp (g-regexp.ads): GNAT Regexp g-regexp ads. | |
784 | * GNAT.Registry (g-regist.ads): GNAT Registry g-regist ads. | |
785 | * GNAT.Regpat (g-regpat.ads): GNAT Regpat g-regpat ads. | |
786 | * GNAT.Rewrite_Data (g-rewdat.ads): GNAT Rewrite_Data g-rewdat ads. | |
787 | * GNAT.Secondary_Stack_Info (g-sestin.ads): GNAT Secondary_Stack_Info g-sestin ads. | |
788 | * GNAT.Semaphores (g-semaph.ads): GNAT Semaphores g-semaph ads. | |
789 | * GNAT.Serial_Communications (g-sercom.ads): GNAT Serial_Communications g-sercom ads. | |
790 | * GNAT.SHA1 (g-sha1.ads): GNAT SHA1 g-sha1 ads. | |
791 | * GNAT.SHA224 (g-sha224.ads): GNAT SHA224 g-sha224 ads. | |
792 | * GNAT.SHA256 (g-sha256.ads): GNAT SHA256 g-sha256 ads. | |
793 | * GNAT.SHA384 (g-sha384.ads): GNAT SHA384 g-sha384 ads. | |
794 | * GNAT.SHA512 (g-sha512.ads): GNAT SHA512 g-sha512 ads. | |
795 | * GNAT.Signals (g-signal.ads): GNAT Signals g-signal ads. | |
796 | * GNAT.Sockets (g-socket.ads): GNAT Sockets g-socket ads. | |
797 | * GNAT.Source_Info (g-souinf.ads): GNAT Source_Info g-souinf ads. | |
798 | * GNAT.Spelling_Checker (g-speche.ads): GNAT Spelling_Checker g-speche ads. | |
799 | * GNAT.Spelling_Checker_Generic (g-spchge.ads): GNAT Spelling_Checker_Generic g-spchge ads. | |
800 | * GNAT.Spitbol.Patterns (g-spipat.ads): GNAT Spitbol Patterns g-spipat ads. | |
801 | * GNAT.Spitbol (g-spitbo.ads): GNAT Spitbol g-spitbo ads. | |
802 | * GNAT.Spitbol.Table_Boolean (g-sptabo.ads): GNAT Spitbol Table_Boolean g-sptabo ads. | |
803 | * GNAT.Spitbol.Table_Integer (g-sptain.ads): GNAT Spitbol Table_Integer g-sptain ads. | |
804 | * GNAT.Spitbol.Table_VString (g-sptavs.ads): GNAT Spitbol Table_VString g-sptavs ads. | |
805 | * GNAT.SSE (g-sse.ads): GNAT SSE g-sse ads. | |
806 | * GNAT.SSE.Vector_Types (g-ssvety.ads): GNAT SSE Vector_Types g-ssvety ads. | |
807 | * GNAT.String_Hash (g-strhas.ads): GNAT String_Hash g-strhas ads. | |
808 | * GNAT.Strings (g-string.ads): GNAT Strings g-string ads. | |
809 | * GNAT.String_Split (g-strspl.ads): GNAT String_Split g-strspl ads. | |
810 | * GNAT.Table (g-table.ads): GNAT Table g-table ads. | |
811 | * GNAT.Task_Lock (g-tasloc.ads): GNAT Task_Lock g-tasloc ads. | |
812 | * GNAT.Time_Stamp (g-timsta.ads): GNAT Time_Stamp g-timsta ads. | |
813 | * GNAT.Threads (g-thread.ads): GNAT Threads g-thread ads. | |
814 | * GNAT.Traceback (g-traceb.ads): GNAT Traceback g-traceb ads. | |
815 | * GNAT.Traceback.Symbolic (g-trasym.ads): GNAT Traceback Symbolic g-trasym ads. | |
eeba836b RD |
816 | * GNAT.UTF_32 (g-utf_32.ads): GNAT UTF_32 g-utf_32 ads. |
817 | * GNAT.UTF_32_Spelling_Checker (g-u3spch.ads): GNAT UTF_32_Spelling_Checker g-u3spch ads. | |
64d5610f ML |
818 | * GNAT.Wide_Spelling_Checker (g-wispch.ads): GNAT Wide_Spelling_Checker g-wispch ads. |
819 | * GNAT.Wide_String_Split (g-wistsp.ads): GNAT Wide_String_Split g-wistsp ads. | |
820 | * GNAT.Wide_Wide_Spelling_Checker (g-zspche.ads): GNAT Wide_Wide_Spelling_Checker g-zspche ads. | |
821 | * GNAT.Wide_Wide_String_Split (g-zistsp.ads): GNAT Wide_Wide_String_Split g-zistsp ads. | |
822 | * Interfaces.C.Extensions (i-cexten.ads): Interfaces C Extensions i-cexten ads. | |
823 | * Interfaces.C.Streams (i-cstrea.ads): Interfaces C Streams i-cstrea ads. | |
824 | * Interfaces.Packed_Decimal (i-pacdec.ads): Interfaces Packed_Decimal i-pacdec ads. | |
825 | * Interfaces.VxWorks (i-vxwork.ads): Interfaces VxWorks i-vxwork ads. | |
826 | * Interfaces.VxWorks.Int_Connection (i-vxinco.ads): Interfaces VxWorks Int_Connection i-vxinco ads. | |
827 | * Interfaces.VxWorks.IO (i-vxwoio.ads): Interfaces VxWorks IO i-vxwoio ads. | |
828 | * System.Address_Image (s-addima.ads): System Address_Image s-addima ads. | |
829 | * System.Assertions (s-assert.ads): System Assertions s-assert ads. | |
830 | * System.Atomic_Counters (s-atocou.ads): System Atomic_Counters s-atocou ads. | |
831 | * System.Memory (s-memory.ads): System Memory s-memory ads. | |
832 | * System.Multiprocessors (s-multip.ads): System Multiprocessors s-multip ads. | |
833 | * System.Multiprocessors.Dispatching_Domains (s-mudido.ads): System Multiprocessors Dispatching_Domains s-mudido ads. | |
834 | * System.Partition_Interface (s-parint.ads): System Partition_Interface s-parint ads. | |
835 | * System.Pool_Global (s-pooglo.ads): System Pool_Global s-pooglo ads. | |
836 | * System.Pool_Local (s-pooloc.ads): System Pool_Local s-pooloc ads. | |
837 | * System.Restrictions (s-restri.ads): System Restrictions s-restri ads. | |
838 | * System.Rident (s-rident.ads): System Rident s-rident ads. | |
839 | * System.Strings.Stream_Ops (s-ststop.ads): System Strings Stream_Ops s-ststop ads. | |
840 | * System.Unsigned_Types (s-unstyp.ads): System Unsigned_Types s-unstyp ads. | |
841 | * System.Wch_Cnv (s-wchcnv.ads): System Wch_Cnv s-wchcnv ads. | |
842 | * System.Wch_Con (s-wchcon.ads): System Wch_Con s-wchcon ads. | |
843 | ||
844 | Interfacing to Other Languages | |
845 | ||
846 | * Interfacing to C:: | |
847 | * Interfacing to C++:: | |
848 | * Interfacing to COBOL:: | |
849 | * Interfacing to Fortran:: | |
850 | * Interfacing to non-GNAT Ada code:: | |
851 | ||
852 | Implementation of Specific Ada Features | |
853 | ||
854 | * Machine Code Insertions:: | |
855 | * GNAT Implementation of Tasking:: | |
856 | * GNAT Implementation of Shared Passive Packages:: | |
857 | * Code Generation for Array Aggregates:: | |
858 | * The Size of Discriminated Records with Default Discriminants:: | |
859 | * Image Values For Nonscalar Types:: | |
860 | * Strict Conformance to the Ada Reference Manual:: | |
861 | ||
862 | GNAT Implementation of Tasking | |
863 | ||
864 | * Mapping Ada Tasks onto the Underlying Kernel Threads:: | |
865 | * Ensuring Compliance with the Real-Time Annex:: | |
866 | * Support for Locking Policies:: | |
867 | ||
868 | Code Generation for Array Aggregates | |
869 | ||
870 | * Static constant aggregates with static bounds:: | |
871 | * Constant aggregates with unconstrained nominal types:: | |
872 | * Aggregates with static bounds:: | |
873 | * Aggregates with nonstatic bounds:: | |
874 | * Aggregates in assignment statements:: | |
875 | ||
b71d4b62 RA |
876 | GNAT language extensions |
877 | ||
878 | * How to activate the extended GNAT Ada superset:: | |
879 | * Curated Extensions:: | |
880 | * Experimental Language Extensions:: | |
881 | ||
882 | Curated Extensions | |
883 | ||
884 | * Conditional when constructs:: | |
885 | * Case pattern matching:: | |
886 | * Fixed lower bounds for array types and subtypes:: | |
887 | * Prefixed-view notation for calls to primitive subprograms of untagged types:: | |
888 | * Expression defaults for generic formal functions:: | |
889 | * String interpolation:: | |
890 | * Constrained attribute for generic objects:: | |
891 | * Static aspect on intrinsic functions:: | |
892 | ||
893 | Experimental Language Extensions | |
894 | ||
895 | * Pragma Storage_Model:: | |
896 | * Simpler accessibility model:: | |
897 | ||
64d5610f ML |
898 | Security Hardening Features |
899 | ||
900 | * Register Scrubbing:: | |
901 | * Stack Scrubbing:: | |
902 | * Hardened Conditionals:: | |
903 | * Hardened Booleans:: | |
904 | * Control Flow Redundancy:: | |
905 | ||
906 | Obsolescent Features | |
907 | ||
908 | * pragma No_Run_Time:: | |
909 | * pragma Ravenscar:: | |
910 | * pragma Restricted_Run_Time:: | |
911 | * pragma Task_Info:: | |
912 | * package System.Task_Info (s-tasinf.ads): package System Task_Info s-tasinf ads. | |
913 | ||
914 | Compatibility and Porting Guide | |
915 | ||
916 | * Writing Portable Fixed-Point Declarations:: | |
917 | * Compatibility with Ada 83:: | |
918 | * Compatibility between Ada 95 and Ada 2005:: | |
919 | * Implementation-dependent characteristics:: | |
920 | * Compatibility with Other Ada Systems:: | |
921 | * Representation Clauses:: | |
922 | * Compatibility with HP Ada 83:: | |
923 | ||
924 | Compatibility with Ada 83 | |
925 | ||
926 | * Legal Ada 83 programs that are illegal in Ada 95:: | |
927 | * More deterministic semantics:: | |
928 | * Changed semantics:: | |
929 | * Other language compatibility issues:: | |
930 | ||
931 | Implementation-dependent characteristics | |
932 | ||
933 | * Implementation-defined pragmas:: | |
934 | * Implementation-defined attributes:: | |
935 | * Libraries:: | |
936 | * Elaboration order:: | |
937 | * Target-specific aspects:: | |
938 | ||
939 | @end detailmenu | |
940 | @end menu | |
941 | ||
942 | @node About This Guide,Implementation Defined Pragmas,Top,Top | |
943 | @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} | |
944 | @chapter About This Guide | |
945 | ||
946 | ||
947 | ||
948 | This manual contains useful information in writing programs using the | |
949 | GNAT compiler. It includes information on implementation dependent | |
950 | characteristics of GNAT, including all the information required by | |
951 | Annex M of the Ada language standard. | |
952 | ||
953 | GNAT implements Ada 95, Ada 2005 and Ada 2012, and it may also be | |
954 | invoked in Ada 83 compatibility mode. | |
955 | By default, GNAT assumes Ada 2012, | |
956 | but you can override with a compiler switch | |
957 | to explicitly specify the language version. | |
958 | (Please refer to the `GNAT User’s Guide' for details on these switches.) | |
959 | Throughout this manual, references to ‘Ada’ without a year suffix | |
960 | apply to all the Ada versions of the language. | |
961 | ||
962 | Ada is designed to be highly portable. | |
963 | In general, a program will have the same effect even when compiled by | |
964 | different compilers on different platforms. | |
965 | However, since Ada is designed to be used in a | |
966 | wide variety of applications, it also contains a number of system | |
967 | dependent features to be used in interfacing to the external world. | |
968 | ||
969 | @geindex Implementation-dependent features | |
970 | ||
971 | @geindex Portability | |
972 | ||
973 | Note: Any program that makes use of implementation-dependent features | |
974 | may be non-portable. You should follow good programming practice and | |
975 | isolate and clearly document any sections of your program that make use | |
976 | of these features in a non-portable manner. | |
977 | ||
978 | @menu | |
979 | * What This Reference Manual Contains:: | |
980 | * Conventions:: | |
981 | * Related Information:: | |
982 | ||
983 | @end menu | |
984 | ||
985 | @node What This Reference Manual Contains,Conventions,,About This Guide | |
986 | @anchor{gnat_rm/about_this_guide what-this-reference-manual-contains}@anchor{6} | |
987 | @section What This Reference Manual Contains | |
988 | ||
989 | ||
990 | This reference manual contains the following chapters: | |
991 | ||
992 | ||
993 | @itemize * | |
994 | ||
995 | @item | |
996 | @ref{7,,Implementation Defined Pragmas}, lists GNAT implementation-dependent | |
997 | pragmas, which can be used to extend and enhance the functionality of the | |
998 | compiler. | |
999 | ||
1000 | @item | |
1001 | @ref{8,,Implementation Defined Attributes}, lists GNAT | |
1002 | implementation-dependent attributes, which can be used to extend and | |
1003 | enhance the functionality of the compiler. | |
1004 | ||
1005 | @item | |
1006 | @ref{9,,Standard and Implementation Defined Restrictions}, lists GNAT | |
1007 | implementation-dependent restrictions, which can be used to extend and | |
1008 | enhance the functionality of the compiler. | |
1009 | ||
1010 | @item | |
1011 | @ref{a,,Implementation Advice}, provides information on generally | |
1012 | desirable behavior which are not requirements that all compilers must | |
1013 | follow since it cannot be provided on all systems, or which may be | |
1014 | undesirable on some systems. | |
1015 | ||
1016 | @item | |
1017 | @ref{b,,Implementation Defined Characteristics}, provides a guide to | |
1018 | minimizing implementation dependent features. | |
1019 | ||
1020 | @item | |
1021 | @ref{c,,Intrinsic Subprograms}, describes the intrinsic subprograms | |
1022 | implemented by GNAT, and how they can be imported into user | |
1023 | application programs. | |
1024 | ||
1025 | @item | |
1026 | @ref{d,,Representation Clauses and Pragmas}, describes in detail the | |
1027 | way that GNAT represents data, and in particular the exact set | |
1028 | of representation clauses and pragmas that is accepted. | |
1029 | ||
1030 | @item | |
1031 | @ref{e,,Standard Library Routines}, provides a listing of packages and a | |
1032 | brief description of the functionality that is provided by Ada’s | |
1033 | extensive set of standard library routines as implemented by GNAT. | |
1034 | ||
1035 | @item | |
1036 | @ref{f,,The Implementation of Standard I/O}, details how the GNAT | |
1037 | implementation of the input-output facilities. | |
1038 | ||
1039 | @item | |
1040 | @ref{10,,The GNAT Library}, is a catalog of packages that complement | |
1041 | the Ada predefined library. | |
1042 | ||
1043 | @item | |
1044 | @ref{11,,Interfacing to Other Languages}, describes how programs | |
1045 | written in Ada using GNAT can be interfaced to other programming | |
1046 | languages. | |
1047 | ||
1048 | @item | |
1049 | @ref{12,,Specialized Needs Annexes}, describes the GNAT implementation of all | |
1050 | of the specialized needs annexes. | |
1051 | ||
1052 | @item | |
1053 | @ref{13,,Implementation of Specific Ada Features}, discusses issues related | |
1054 | to GNAT’s implementation of machine code insertions, tasking, and several | |
1055 | other features. | |
1056 | ||
1057 | @item | |
1058 | @ref{14,,Implementation of Ada 2012 Features}, describes the status of the | |
1059 | GNAT implementation of the Ada 2012 language standard. | |
1060 | ||
1061 | @item | |
1062 | @ref{15,,Security Hardening Features} documents GNAT extensions aimed | |
1063 | at security hardening. | |
1064 | ||
1065 | @item | |
1066 | @ref{16,,Obsolescent Features} documents implementation dependent features, | |
1067 | including pragmas and attributes, which are considered obsolescent, since | |
1068 | there are other preferred ways of achieving the same results. These | |
1069 | obsolescent forms are retained for backwards compatibility. | |
1070 | ||
1071 | @item | |
1072 | @ref{17,,Compatibility and Porting Guide} presents some guidelines for | |
1073 | developing portable Ada code, describes the compatibility issues that | |
1074 | may arise between GNAT and other Ada compilation systems (including those | |
1075 | for Ada 83), and shows how GNAT can expedite porting applications | |
1076 | developed in other Ada environments. | |
1077 | ||
1078 | @item | |
1079 | @ref{1,,GNU Free Documentation License} contains the license for this document. | |
1080 | @end itemize | |
1081 | ||
1082 | @geindex Ada 95 Language Reference Manual | |
1083 | ||
1084 | @geindex Ada 2005 Language Reference Manual | |
1085 | ||
1086 | This reference manual assumes a basic familiarity with the Ada 95 language, as | |
1087 | described in the | |
1088 | @cite{International Standard ANSI/ISO/IEC-8652:1995}. | |
1089 | It does not require knowledge of the new features introduced by Ada 2005 or | |
1090 | Ada 2012. | |
1091 | All three reference manuals are included in the GNAT documentation | |
1092 | package. | |
1093 | ||
1094 | @node Conventions,Related Information,What This Reference Manual Contains,About This Guide | |
1095 | @anchor{gnat_rm/about_this_guide conventions}@anchor{18} | |
1096 | @section Conventions | |
1097 | ||
1098 | ||
1099 | @geindex Conventions | |
1100 | @geindex typographical | |
1101 | ||
1102 | @geindex Typographical conventions | |
1103 | ||
1104 | Following are examples of the typographical and graphic conventions used | |
1105 | in this guide: | |
1106 | ||
1107 | ||
1108 | @itemize * | |
1109 | ||
1110 | @item | |
1111 | @code{Functions}, @code{utility program names}, @code{standard names}, | |
1112 | and @code{classes}. | |
1113 | ||
1114 | @item | |
1115 | @code{Option flags} | |
1116 | ||
1117 | @item | |
1118 | @code{File names} | |
1119 | ||
1120 | @item | |
1121 | @code{Variables} | |
1122 | ||
1123 | @item | |
1124 | `Emphasis' | |
1125 | ||
1126 | @item | |
1127 | [optional information or parameters] | |
1128 | ||
1129 | @item | |
1130 | Examples are described by text | |
1131 | ||
1132 | @example | |
1133 | and then shown this way. | |
1134 | @end example | |
1135 | ||
1136 | @item | |
1137 | Commands that are entered by the user are shown as preceded by a prompt string | |
1138 | comprising the @code{$} character followed by a space. | |
1139 | @end itemize | |
1140 | ||
1141 | @node Related Information,,Conventions,About This Guide | |
1142 | @anchor{gnat_rm/about_this_guide related-information}@anchor{19} | |
1143 | @section Related Information | |
1144 | ||
1145 | ||
1146 | See the following documents for further information on GNAT: | |
1147 | ||
1148 | ||
1149 | @itemize * | |
1150 | ||
1151 | @item | |
1152 | @cite{GNAT User’s Guide for Native Platforms}, | |
1153 | which provides information on how to use the | |
1154 | GNAT development environment. | |
1155 | ||
1156 | @item | |
1157 | @cite{Ada 95 Reference Manual}, the Ada 95 programming language standard. | |
1158 | ||
1159 | @item | |
1160 | @cite{Ada 95 Annotated Reference Manual}, which is an annotated version | |
1161 | of the Ada 95 standard. The annotations describe | |
1162 | detailed aspects of the design decision, and in particular contain useful | |
1163 | sections on Ada 83 compatibility. | |
1164 | ||
1165 | @item | |
1166 | @cite{Ada 2005 Reference Manual}, the Ada 2005 programming language standard. | |
1167 | ||
1168 | @item | |
1169 | @cite{Ada 2005 Annotated Reference Manual}, which is an annotated version | |
1170 | of the Ada 2005 standard. The annotations describe | |
1171 | detailed aspects of the design decision. | |
1172 | ||
1173 | @item | |
1174 | @cite{Ada 2012 Reference Manual}, the Ada 2012 programming language standard. | |
1175 | ||
1176 | @item | |
1177 | @cite{DEC Ada@comma{} Technical Overview and Comparison on DIGITAL Platforms}, | |
1178 | which contains specific information on compatibility between GNAT and | |
1179 | DEC Ada 83 systems. | |
1180 | ||
1181 | @item | |
1182 | @cite{DEC Ada@comma{} Language Reference Manual}, part number AA-PYZAB-TK, which | |
1183 | describes in detail the pragmas and attributes provided by the DEC Ada 83 | |
1184 | compiler system. | |
1185 | @end itemize | |
1186 | ||
1187 | @node Implementation Defined Pragmas,Implementation Defined Aspects,About This Guide,Top | |
1188 | @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} | |
1189 | @chapter Implementation Defined Pragmas | |
1190 | ||
1191 | ||
1192 | Ada defines a set of pragmas that can be used to supply additional | |
1193 | information to the compiler. These language defined pragmas are | |
1194 | implemented in GNAT and work as described in the Ada Reference Manual. | |
1195 | ||
1196 | In addition, Ada allows implementations to define additional pragmas | |
1197 | whose meaning is defined by the implementation. GNAT provides a number | |
1198 | of these implementation-defined pragmas, which can be used to extend | |
1199 | and enhance the functionality of the compiler. This section of the GNAT | |
1200 | Reference Manual describes these additional pragmas. | |
1201 | ||
1202 | Note that any program using these pragmas might not be portable to other | |
1203 | compilers (although GNAT implements this set of pragmas on all | |
1204 | platforms). Therefore if portability to other compilers is an important | |
1205 | consideration, the use of these pragmas should be minimized. | |
1206 | ||
1207 | @menu | |
1208 | * Pragma Abort_Defer:: | |
1209 | * Pragma Abstract_State:: | |
1210 | * Pragma Ada_83:: | |
1211 | * Pragma Ada_95:: | |
1212 | * Pragma Ada_05:: | |
1213 | * Pragma Ada_2005:: | |
1214 | * Pragma Ada_12:: | |
1215 | * Pragma Ada_2012:: | |
1216 | * Pragma Ada_2022:: | |
1217 | * Pragma Aggregate_Individually_Assign:: | |
1218 | * Pragma Allow_Integer_Address:: | |
1219 | * Pragma Annotate:: | |
1220 | * Pragma Assert:: | |
1221 | * Pragma Assert_And_Cut:: | |
1222 | * Pragma Assertion_Policy:: | |
1223 | * Pragma Assume:: | |
1224 | * Pragma Assume_No_Invalid_Values:: | |
1225 | * Pragma Async_Readers:: | |
1226 | * Pragma Async_Writers:: | |
1227 | * Pragma Attribute_Definition:: | |
1228 | * Pragma C_Pass_By_Copy:: | |
1229 | * Pragma Check:: | |
1230 | * Pragma Check_Float_Overflow:: | |
1231 | * Pragma Check_Name:: | |
1232 | * Pragma Check_Policy:: | |
1233 | * Pragma Comment:: | |
1234 | * Pragma Common_Object:: | |
1235 | * Pragma Compile_Time_Error:: | |
1236 | * Pragma Compile_Time_Warning:: | |
1237 | * Pragma Complete_Representation:: | |
1238 | * Pragma Complex_Representation:: | |
1239 | * Pragma Component_Alignment:: | |
1240 | * Pragma Constant_After_Elaboration:: | |
1241 | * Pragma Contract_Cases:: | |
1242 | * Pragma Convention_Identifier:: | |
1243 | * Pragma CPP_Class:: | |
1244 | * Pragma CPP_Constructor:: | |
1245 | * Pragma CPP_Virtual:: | |
1246 | * Pragma CPP_Vtable:: | |
1247 | * Pragma CPU:: | |
1248 | * Pragma Deadline_Floor:: | |
64d5610f ML |
1249 | * Pragma Debug:: |
1250 | * Pragma Debug_Policy:: | |
6f089469 | 1251 | * Pragma Default_Initial_Condition:: |
64d5610f ML |
1252 | * Pragma Default_Scalar_Storage_Order:: |
1253 | * Pragma Default_Storage_Pool:: | |
1254 | * Pragma Depends:: | |
1255 | * Pragma Detect_Blocking:: | |
1256 | * Pragma Disable_Atomic_Synchronization:: | |
1257 | * Pragma Dispatching_Domain:: | |
1258 | * Pragma Effective_Reads:: | |
1259 | * Pragma Effective_Writes:: | |
1260 | * Pragma Elaboration_Checks:: | |
1261 | * Pragma Eliminate:: | |
1262 | * Pragma Enable_Atomic_Synchronization:: | |
1263 | * Pragma Export_Function:: | |
1264 | * Pragma Export_Object:: | |
1265 | * Pragma Export_Procedure:: | |
1266 | * Pragma Export_Valued_Procedure:: | |
1267 | * Pragma Extend_System:: | |
1268 | * Pragma Extensions_Allowed:: | |
1269 | * Pragma Extensions_Visible:: | |
1270 | * Pragma External:: | |
1271 | * Pragma External_Name_Casing:: | |
1272 | * Pragma Fast_Math:: | |
1273 | * Pragma Favor_Top_Level:: | |
1274 | * Pragma Finalize_Storage_Only:: | |
1275 | * Pragma Float_Representation:: | |
1276 | * Pragma Ghost:: | |
1277 | * Pragma Global:: | |
1278 | * Pragma Ident:: | |
1279 | * Pragma Ignore_Pragma:: | |
1280 | * Pragma Implementation_Defined:: | |
1281 | * Pragma Implemented:: | |
1282 | * Pragma Implicit_Packing:: | |
1283 | * Pragma Import_Function:: | |
1284 | * Pragma Import_Object:: | |
1285 | * Pragma Import_Procedure:: | |
1286 | * Pragma Import_Valued_Procedure:: | |
1287 | * Pragma Independent:: | |
1288 | * Pragma Independent_Components:: | |
1289 | * Pragma Initial_Condition:: | |
1290 | * Pragma Initialize_Scalars:: | |
1291 | * Pragma Initializes:: | |
1292 | * Pragma Inline_Always:: | |
1293 | * Pragma Inline_Generic:: | |
1294 | * Pragma Interface:: | |
1295 | * Pragma Interface_Name:: | |
1296 | * Pragma Interrupt_Handler:: | |
1297 | * Pragma Interrupt_State:: | |
1298 | * Pragma Invariant:: | |
1299 | * Pragma Keep_Names:: | |
1300 | * Pragma License:: | |
1301 | * Pragma Link_With:: | |
1302 | * Pragma Linker_Alias:: | |
1303 | * Pragma Linker_Constructor:: | |
1304 | * Pragma Linker_Destructor:: | |
1305 | * Pragma Linker_Section:: | |
1306 | * Pragma Lock_Free:: | |
1307 | * Pragma Loop_Invariant:: | |
1308 | * Pragma Loop_Optimize:: | |
1309 | * Pragma Loop_Variant:: | |
1310 | * Pragma Machine_Attribute:: | |
1311 | * Pragma Main:: | |
1312 | * Pragma Main_Storage:: | |
1313 | * Pragma Max_Queue_Length:: | |
1314 | * Pragma No_Body:: | |
1315 | * Pragma No_Caching:: | |
1316 | * Pragma No_Component_Reordering:: | |
1317 | * Pragma No_Elaboration_Code_All:: | |
1318 | * Pragma No_Heap_Finalization:: | |
1319 | * Pragma No_Inline:: | |
1320 | * Pragma No_Return:: | |
1321 | * Pragma No_Strict_Aliasing:: | |
1322 | * Pragma No_Tagged_Streams:: | |
1323 | * Pragma Normalize_Scalars:: | |
1324 | * Pragma Obsolescent:: | |
1325 | * Pragma Optimize_Alignment:: | |
1326 | * Pragma Ordered:: | |
1327 | * Pragma Overflow_Mode:: | |
1328 | * Pragma Overriding_Renamings:: | |
64d5610f | 1329 | * Pragma Part_Of:: |
6f089469 | 1330 | * Pragma Partition_Elaboration_Policy:: |
64d5610f ML |
1331 | * Pragma Passive:: |
1332 | * Pragma Persistent_BSS:: | |
1333 | * Pragma Post:: | |
1334 | * Pragma Postcondition:: | |
1335 | * Pragma Post_Class:: | |
1336 | * Pragma Pre:: | |
1337 | * Pragma Precondition:: | |
1338 | * Pragma Predicate:: | |
1339 | * Pragma Predicate_Failure:: | |
1340 | * Pragma Preelaborable_Initialization:: | |
1341 | * Pragma Prefix_Exception_Messages:: | |
1342 | * Pragma Pre_Class:: | |
1343 | * Pragma Priority_Specific_Dispatching:: | |
1344 | * Pragma Profile:: | |
1345 | * Pragma Profile_Warnings:: | |
1346 | * Pragma Propagate_Exceptions:: | |
1347 | * Pragma Provide_Shift_Operators:: | |
1348 | * Pragma Psect_Object:: | |
1349 | * Pragma Pure_Function:: | |
1350 | * Pragma Rational:: | |
1351 | * Pragma Ravenscar:: | |
1352 | * Pragma Refined_Depends:: | |
1353 | * Pragma Refined_Global:: | |
1354 | * Pragma Refined_Post:: | |
1355 | * Pragma Refined_State:: | |
1356 | * Pragma Relative_Deadline:: | |
1357 | * Pragma Remote_Access_Type:: | |
1358 | * Pragma Rename_Pragma:: | |
1359 | * Pragma Restricted_Run_Time:: | |
1360 | * Pragma Restriction_Warnings:: | |
1361 | * Pragma Reviewable:: | |
1362 | * Pragma Secondary_Stack_Size:: | |
1363 | * Pragma Share_Generic:: | |
1364 | * Pragma Shared:: | |
1365 | * Pragma Short_Circuit_And_Or:: | |
1366 | * Pragma Short_Descriptors:: | |
1367 | * Pragma Simple_Storage_Pool_Type:: | |
1368 | * Pragma Source_File_Name:: | |
1369 | * Pragma Source_File_Name_Project:: | |
1370 | * Pragma Source_Reference:: | |
1371 | * Pragma SPARK_Mode:: | |
1372 | * Pragma Static_Elaboration_Desired:: | |
1373 | * Pragma Stream_Convert:: | |
1374 | * Pragma Style_Checks:: | |
1375 | * Pragma Subtitle:: | |
1376 | * Pragma Suppress:: | |
1377 | * Pragma Suppress_All:: | |
1378 | * Pragma Suppress_Debug_Info:: | |
1379 | * Pragma Suppress_Exception_Locations:: | |
1380 | * Pragma Suppress_Initialization:: | |
1381 | * Pragma Task_Name:: | |
1382 | * Pragma Task_Storage:: | |
1383 | * Pragma Test_Case:: | |
1384 | * Pragma Thread_Local_Storage:: | |
1385 | * Pragma Time_Slice:: | |
1386 | * Pragma Title:: | |
1387 | * Pragma Type_Invariant:: | |
1388 | * Pragma Type_Invariant_Class:: | |
1389 | * Pragma Unchecked_Union:: | |
1390 | * Pragma Unevaluated_Use_Of_Old:: | |
1391 | * Pragma Unimplemented_Unit:: | |
1392 | * Pragma Universal_Aliasing:: | |
1393 | * Pragma Unmodified:: | |
1394 | * Pragma Unreferenced:: | |
1395 | * Pragma Unreferenced_Objects:: | |
1396 | * Pragma Unreserve_All_Interrupts:: | |
1397 | * Pragma Unsuppress:: | |
64d5610f | 1398 | * Pragma Unused:: |
6f089469 | 1399 | * Pragma Use_VADS_Size:: |
64d5610f ML |
1400 | * Pragma Validity_Checks:: |
1401 | * Pragma Volatile:: | |
1402 | * Pragma Volatile_Full_Access:: | |
1403 | * Pragma Volatile_Function:: | |
1404 | * Pragma Warning_As_Error:: | |
1405 | * Pragma Warnings:: | |
1406 | * Pragma Weak_External:: | |
1407 | * Pragma Wide_Character_Encoding:: | |
1408 | ||
1409 | @end menu | |
1410 | ||
1411 | @node Pragma Abort_Defer,Pragma Abstract_State,,Implementation Defined Pragmas | |
1412 | @anchor{gnat_rm/implementation_defined_pragmas pragma-abort-defer}@anchor{1c} | |
1413 | @section Pragma Abort_Defer | |
1414 | ||
1415 | ||
1416 | @geindex Deferring aborts | |
1417 | ||
1418 | Syntax: | |
1419 | ||
1420 | @example | |
1421 | pragma Abort_Defer; | |
1422 | @end example | |
1423 | ||
1424 | This pragma must appear at the start of the statement sequence of a | |
1425 | handled sequence of statements (right after the @code{begin}). It has | |
1426 | the effect of deferring aborts for the sequence of statements (but not | |
1427 | for the declarations or handlers, if any, associated with this statement | |
1428 | sequence). This can also be useful for adding a polling point in Ada code, | |
1429 | where asynchronous abort of tasks is checked when leaving the statement | |
1430 | sequence, and is lighter than, for example, using @code{delay 0.0;}, since with | |
1431 | zero-cost exception handling, propagating exceptions (implicitly used to | |
1432 | implement task abort) cannot be done reliably in an asynchronous way. | |
1433 | ||
1434 | An example of usage would be: | |
1435 | ||
1436 | @example | |
1437 | -- Add a polling point to check for task aborts | |
1438 | ||
1439 | begin | |
1440 | pragma Abort_Defer; | |
1441 | end; | |
1442 | @end example | |
1443 | ||
1444 | @node Pragma Abstract_State,Pragma Ada_83,Pragma Abort_Defer,Implementation Defined Pragmas | |
1445 | @anchor{gnat_rm/implementation_defined_pragmas id2}@anchor{1d}@anchor{gnat_rm/implementation_defined_pragmas pragma-abstract-state}@anchor{1e} | |
1446 | @section Pragma Abstract_State | |
1447 | ||
1448 | ||
1449 | Syntax: | |
1450 | ||
1451 | @example | |
1452 | pragma Abstract_State (ABSTRACT_STATE_LIST); | |
1453 | ||
1454 | ABSTRACT_STATE_LIST ::= | |
1455 | null | |
1456 | | STATE_NAME_WITH_OPTIONS | |
1457 | | (STATE_NAME_WITH_OPTIONS @{, STATE_NAME_WITH_OPTIONS@} ) | |
1458 | ||
1459 | STATE_NAME_WITH_OPTIONS ::= | |
1460 | STATE_NAME | |
1461 | | (STATE_NAME with OPTION_LIST) | |
1462 | ||
1463 | OPTION_LIST ::= OPTION @{, OPTION@} | |
1464 | ||
1465 | OPTION ::= | |
1466 | SIMPLE_OPTION | |
1467 | | NAME_VALUE_OPTION | |
1468 | ||
1469 | SIMPLE_OPTION ::= Ghost | Synchronous | |
1470 | ||
1471 | NAME_VALUE_OPTION ::= | |
1472 | Part_Of => ABSTRACT_STATE | |
1473 | | External [=> EXTERNAL_PROPERTY_LIST] | |
1474 | ||
1475 | EXTERNAL_PROPERTY_LIST ::= | |
1476 | EXTERNAL_PROPERTY | |
1477 | | (EXTERNAL_PROPERTY @{, EXTERNAL_PROPERTY@} ) | |
1478 | ||
1479 | EXTERNAL_PROPERTY ::= | |
1480 | Async_Readers [=> static_boolean_EXPRESSION] | |
1481 | | Async_Writers [=> static_boolean_EXPRESSION] | |
1482 | | Effective_Reads [=> static_boolean_EXPRESSION] | |
1483 | | Effective_Writes [=> static_boolean_EXPRESSION] | |
1484 | others => static_boolean_EXPRESSION | |
1485 | ||
1486 | STATE_NAME ::= defining_identifier | |
1487 | ||
1488 | ABSTRACT_STATE ::= name | |
1489 | @end example | |
1490 | ||
1491 | For the semantics of this pragma, see the entry for aspect @code{Abstract_State} in | |
1492 | the SPARK 2014 Reference Manual, section 7.1.4. | |
1493 | ||
1494 | @node Pragma Ada_83,Pragma Ada_95,Pragma Abstract_State,Implementation Defined Pragmas | |
1495 | @anchor{gnat_rm/implementation_defined_pragmas pragma-ada-83}@anchor{1f} | |
1496 | @section Pragma Ada_83 | |
1497 | ||
1498 | ||
1499 | Syntax: | |
1500 | ||
1501 | @example | |
1502 | pragma Ada_83; | |
1503 | @end example | |
1504 | ||
1505 | A configuration pragma that establishes Ada 83 mode for the unit to | |
1506 | which it applies, regardless of the mode set by the command line | |
1507 | switches. In Ada 83 mode, GNAT attempts to be as compatible with | |
1508 | the syntax and semantics of Ada 83, as defined in the original Ada | |
1509 | 83 Reference Manual as possible. In particular, the keywords added by Ada 95 | |
1510 | and Ada 2005 are not recognized, optional package bodies are allowed, | |
1511 | and generics may name types with unknown discriminants without using | |
1512 | the @code{(<>)} notation. In addition, some but not all of the additional | |
1513 | restrictions of Ada 83 are enforced. | |
1514 | ||
1515 | Ada 83 mode is intended for two purposes. Firstly, it allows existing | |
1516 | Ada 83 code to be compiled and adapted to GNAT with less effort. | |
1517 | Secondly, it aids in keeping code backwards compatible with Ada 83. | |
1518 | However, there is no guarantee that code that is processed correctly | |
1519 | by GNAT in Ada 83 mode will in fact compile and execute with an Ada | |
1520 | 83 compiler, since GNAT does not enforce all the additional checks | |
1521 | required by Ada 83. | |
1522 | ||
1523 | @node Pragma Ada_95,Pragma Ada_05,Pragma Ada_83,Implementation Defined Pragmas | |
1524 | @anchor{gnat_rm/implementation_defined_pragmas pragma-ada-95}@anchor{20} | |
1525 | @section Pragma Ada_95 | |
1526 | ||
1527 | ||
1528 | Syntax: | |
1529 | ||
1530 | @example | |
1531 | pragma Ada_95; | |
1532 | @end example | |
1533 | ||
1534 | A configuration pragma that establishes Ada 95 mode for the unit to which | |
1535 | it applies, regardless of the mode set by the command line switches. | |
1536 | This mode is set automatically for the @code{Ada} and @code{System} | |
1537 | packages and their children, so you need not specify it in these | |
1538 | contexts. This pragma is useful when writing a reusable component that | |
1539 | itself uses Ada 95 features, but which is intended to be usable from | |
1540 | either Ada 83 or Ada 95 programs. | |
1541 | ||
1542 | @node Pragma Ada_05,Pragma Ada_2005,Pragma Ada_95,Implementation Defined Pragmas | |
1543 | @anchor{gnat_rm/implementation_defined_pragmas pragma-ada-05}@anchor{21} | |
1544 | @section Pragma Ada_05 | |
1545 | ||
1546 | ||
1547 | Syntax: | |
1548 | ||
1549 | @example | |
1550 | pragma Ada_05; | |
1551 | pragma Ada_05 (local_NAME); | |
1552 | @end example | |
1553 | ||
1554 | A configuration pragma that establishes Ada 2005 mode for the unit to which | |
1555 | it applies, regardless of the mode set by the command line switches. | |
1556 | This pragma is useful when writing a reusable component that | |
1557 | itself uses Ada 2005 features, but which is intended to be usable from | |
1558 | either Ada 83 or Ada 95 programs. | |
1559 | ||
1560 | The one argument form (which is not a configuration pragma) | |
1561 | is used for managing the transition from | |
1562 | Ada 95 to Ada 2005 in the run-time library. If an entity is marked | |
1563 | as Ada_2005 only, then referencing the entity in Ada_83 or Ada_95 | |
1564 | mode will generate a warning. In addition, in Ada_83 or Ada_95 | |
1565 | mode, a preference rule is established which does not choose | |
1566 | such an entity unless it is unambiguously specified. This avoids | |
1567 | extra subprograms marked this way from generating ambiguities in | |
1568 | otherwise legal pre-Ada_2005 programs. The one argument form is | |
1569 | intended for exclusive use in the GNAT run-time library. | |
1570 | ||
1571 | @node Pragma Ada_2005,Pragma Ada_12,Pragma Ada_05,Implementation Defined Pragmas | |
1572 | @anchor{gnat_rm/implementation_defined_pragmas pragma-ada-2005}@anchor{22} | |
1573 | @section Pragma Ada_2005 | |
1574 | ||
1575 | ||
1576 | Syntax: | |
1577 | ||
1578 | @example | |
1579 | pragma Ada_2005; | |
1580 | @end example | |
1581 | ||
1582 | This configuration pragma is a synonym for pragma Ada_05 and has the | |
1583 | same syntax and effect. | |
1584 | ||
1585 | @node Pragma Ada_12,Pragma Ada_2012,Pragma Ada_2005,Implementation Defined Pragmas | |
1586 | @anchor{gnat_rm/implementation_defined_pragmas pragma-ada-12}@anchor{23} | |
1587 | @section Pragma Ada_12 | |
1588 | ||
1589 | ||
1590 | Syntax: | |
1591 | ||
1592 | @example | |
1593 | pragma Ada_12; | |
1594 | pragma Ada_12 (local_NAME); | |
1595 | @end example | |
1596 | ||
1597 | A configuration pragma that establishes Ada 2012 mode for the unit to which | |
1598 | it applies, regardless of the mode set by the command line switches. | |
1599 | This mode is set automatically for the @code{Ada} and @code{System} | |
1600 | packages and their children, so you need not specify it in these | |
1601 | contexts. This pragma is useful when writing a reusable component that | |
1602 | itself uses Ada 2012 features, but which is intended to be usable from | |
1603 | Ada 83, Ada 95, or Ada 2005 programs. | |
1604 | ||
1605 | The one argument form, which is not a configuration pragma, | |
1606 | is used for managing the transition from Ada | |
1607 | 2005 to Ada 2012 in the run-time library. If an entity is marked | |
1608 | as Ada_2012 only, then referencing the entity in any pre-Ada_2012 | |
1609 | mode will generate a warning. In addition, in any pre-Ada_2012 | |
1610 | mode, a preference rule is established which does not choose | |
1611 | such an entity unless it is unambiguously specified. This avoids | |
1612 | extra subprograms marked this way from generating ambiguities in | |
1613 | otherwise legal pre-Ada_2012 programs. The one argument form is | |
1614 | intended for exclusive use in the GNAT run-time library. | |
1615 | ||
1616 | @node Pragma Ada_2012,Pragma Ada_2022,Pragma Ada_12,Implementation Defined Pragmas | |
1617 | @anchor{gnat_rm/implementation_defined_pragmas pragma-ada-2012}@anchor{24} | |
1618 | @section Pragma Ada_2012 | |
1619 | ||
1620 | ||
1621 | Syntax: | |
1622 | ||
1623 | @example | |
1624 | pragma Ada_2012; | |
1625 | @end example | |
1626 | ||
1627 | This configuration pragma is a synonym for pragma Ada_12 and has the | |
1628 | same syntax and effect. | |
1629 | ||
1630 | @node Pragma Ada_2022,Pragma Aggregate_Individually_Assign,Pragma Ada_2012,Implementation Defined Pragmas | |
1631 | @anchor{gnat_rm/implementation_defined_pragmas pragma-ada-2022}@anchor{25} | |
1632 | @section Pragma Ada_2022 | |
1633 | ||
1634 | ||
1635 | Syntax: | |
1636 | ||
1637 | @example | |
1638 | pragma Ada_2022; | |
1639 | pragma Ada_2022 (local_NAME); | |
1640 | @end example | |
1641 | ||
1642 | A configuration pragma that establishes Ada 2022 mode for the unit to which | |
1643 | it applies, regardless of the mode set by the command line switches. | |
1644 | This mode is set automatically for the @code{Ada} and @code{System} | |
1645 | packages and their children, so you need not specify it in these | |
1646 | contexts. This pragma is useful when writing a reusable component that | |
1647 | itself uses Ada 2022 features, but which is intended to be usable from | |
1648 | Ada 83, Ada 95, Ada 2005 or Ada 2012 programs. | |
1649 | ||
1650 | The one argument form, which is not a configuration pragma, | |
1651 | is used for managing the transition from Ada | |
1652 | 2012 to Ada 2022 in the run-time library. If an entity is marked | |
1653 | as Ada_2022 only, then referencing the entity in any pre-Ada_2022 | |
1654 | mode will generate a warning. In addition, in any pre-Ada_2012 | |
1655 | mode, a preference rule is established which does not choose | |
1656 | such an entity unless it is unambiguously specified. This avoids | |
1657 | extra subprograms marked this way from generating ambiguities in | |
1658 | otherwise legal pre-Ada_2022 programs. The one argument form is | |
1659 | intended for exclusive use in the GNAT run-time library. | |
1660 | ||
1661 | @node Pragma Aggregate_Individually_Assign,Pragma Allow_Integer_Address,Pragma Ada_2022,Implementation Defined Pragmas | |
1662 | @anchor{gnat_rm/implementation_defined_pragmas pragma-aggregate-individually-assign}@anchor{26} | |
1663 | @section Pragma Aggregate_Individually_Assign | |
1664 | ||
1665 | ||
1666 | Syntax: | |
1667 | ||
1668 | @example | |
1669 | pragma Aggregate_Individually_Assign; | |
1670 | @end example | |
1671 | ||
1672 | Where possible, GNAT will store the binary representation of a record aggregate | |
1673 | in memory for space and performance reasons. This configuration pragma changes | |
1674 | this behavior so that record aggregates are instead always converted into | |
1675 | individual assignment statements. | |
1676 | ||
1677 | @node Pragma Allow_Integer_Address,Pragma Annotate,Pragma Aggregate_Individually_Assign,Implementation Defined Pragmas | |
1678 | @anchor{gnat_rm/implementation_defined_pragmas pragma-allow-integer-address}@anchor{27} | |
1679 | @section Pragma Allow_Integer_Address | |
1680 | ||
1681 | ||
1682 | Syntax: | |
1683 | ||
1684 | @example | |
1685 | pragma Allow_Integer_Address; | |
1686 | @end example | |
1687 | ||
1688 | In almost all versions of GNAT, @code{System.Address} is a private | |
1689 | type in accordance with the implementation advice in the RM. This | |
1690 | means that integer values, | |
1691 | in particular integer literals, are not allowed as address values. | |
1692 | If the configuration pragma | |
1693 | @code{Allow_Integer_Address} is given, then integer expressions may | |
1694 | be used anywhere a value of type @code{System.Address} is required. | |
1695 | The effect is to introduce an implicit unchecked conversion from the | |
1696 | integer value to type @code{System.Address}. The reverse case of using | |
1697 | an address where an integer type is required is handled analogously. | |
1698 | The following example compiles without errors: | |
1699 | ||
1700 | @example | |
1701 | pragma Allow_Integer_Address; | |
1702 | with System; use System; | |
1703 | package AddrAsInt is | |
1704 | X : Integer; | |
1705 | Y : Integer; | |
1706 | for X'Address use 16#1240#; | |
1707 | for Y use at 16#3230#; | |
1708 | m : Address := 16#4000#; | |
1709 | n : constant Address := 4000; | |
1710 | p : constant Address := Address (X + Y); | |
1711 | v : Integer := y'Address; | |
1712 | w : constant Integer := Integer (Y'Address); | |
1713 | type R is new integer; | |
1714 | RR : R := 1000; | |
1715 | Z : Integer; | |
1716 | for Z'Address use RR; | |
1717 | end AddrAsInt; | |
1718 | @end example | |
1719 | ||
1720 | Note that pragma @code{Allow_Integer_Address} is ignored if @code{System.Address} | |
1721 | is not a private type. In implementations of @code{GNAT} where | |
1722 | System.Address is a visible integer type, | |
1723 | this pragma serves no purpose but is ignored | |
1724 | rather than rejected to allow common sets of sources to be used | |
1725 | in the two situations. | |
1726 | ||
1727 | @node Pragma Annotate,Pragma Assert,Pragma Allow_Integer_Address,Implementation Defined Pragmas | |
1728 | @anchor{gnat_rm/implementation_defined_pragmas id3}@anchor{28}@anchor{gnat_rm/implementation_defined_pragmas pragma-annotate}@anchor{29} | |
1729 | @section Pragma Annotate | |
1730 | ||
1731 | ||
1732 | Syntax: | |
1733 | ||
1734 | @example | |
1735 | pragma Annotate (IDENTIFIER [, IDENTIFIER @{, ARG@}] [, entity => local_NAME]); | |
1736 | ||
1737 | ARG ::= NAME | EXPRESSION | |
1738 | @end example | |
1739 | ||
1740 | This pragma is used to annotate programs. IDENTIFIER identifies | |
1741 | the type of annotation. GNAT verifies that it is an identifier, but does | |
1742 | not otherwise analyze it. The second optional identifier is also left | |
1743 | unanalyzed, and by convention is used to control the action of the tool to | |
1744 | which the annotation is addressed. The remaining ARG arguments | |
1745 | can be either string literals or more generally expressions. | |
1746 | String literals (and concatenations of string literals) are assumed to be | |
1747 | either of type | |
1748 | @code{Standard.String} or else @code{Wide_String} or @code{Wide_Wide_String} | |
1749 | depending on the character literals they contain. | |
1750 | All other kinds of arguments are analyzed as expressions, and must be | |
1751 | unambiguous. The last argument if present must have the identifier | |
1752 | @code{Entity} and GNAT verifies that a local name is given. | |
1753 | ||
1754 | The analyzed pragma is retained in the tree, but not otherwise processed | |
1755 | by any part of the GNAT compiler, except to generate corresponding note | |
1756 | lines in the generated ALI file. For the format of these note lines, see | |
1757 | the compiler source file lib-writ.ads. This pragma is intended for use by | |
1758 | external tools, including ASIS. The use of pragma Annotate does not | |
1759 | affect the compilation process in any way. This pragma may be used as | |
1760 | a configuration pragma. | |
1761 | ||
1762 | @node Pragma Assert,Pragma Assert_And_Cut,Pragma Annotate,Implementation Defined Pragmas | |
1763 | @anchor{gnat_rm/implementation_defined_pragmas pragma-assert}@anchor{2a} | |
1764 | @section Pragma Assert | |
1765 | ||
1766 | ||
1767 | Syntax: | |
1768 | ||
1769 | @example | |
1770 | pragma Assert ( | |
1771 | boolean_EXPRESSION | |
1772 | [, string_EXPRESSION]); | |
1773 | @end example | |
1774 | ||
1775 | The effect of this pragma depends on whether the corresponding command | |
1776 | line switch is set to activate assertions. The pragma expands into code | |
1777 | equivalent to the following: | |
1778 | ||
1779 | @example | |
1780 | if assertions-enabled then | |
1781 | if not boolean_EXPRESSION then | |
1782 | System.Assertions.Raise_Assert_Failure | |
1783 | (string_EXPRESSION); | |
1784 | end if; | |
1785 | end if; | |
1786 | @end example | |
1787 | ||
1788 | The string argument, if given, is the message that will be associated | |
1789 | with the exception occurrence if the exception is raised. If no second | |
1790 | argument is given, the default message is @code{file}:@code{nnn}, | |
1791 | where @code{file} is the name of the source file containing the assert, | |
1792 | and @code{nnn} is the line number of the assert. | |
1793 | ||
1794 | Note that, as with the @code{if} statement to which it is equivalent, the | |
1795 | type of the expression is either @code{Standard.Boolean}, or any type derived | |
1796 | from this standard type. | |
1797 | ||
1798 | Assert checks can be either checked or ignored. By default they are ignored. | |
1799 | They will be checked if either the command line switch `-gnata' is | |
1800 | used, or if an @code{Assertion_Policy} or @code{Check_Policy} pragma is used | |
1801 | to enable @code{Assert_Checks}. | |
1802 | ||
1803 | If assertions are ignored, then there | |
1804 | is no run-time effect (and in particular, any side effects from the | |
1805 | expression will not occur at run time). (The expression is still | |
1806 | analyzed at compile time, and may cause types to be frozen if they are | |
1807 | mentioned here for the first time). | |
1808 | ||
1809 | If assertions are checked, then the given expression is tested, and if | |
1810 | it is @code{False} then @code{System.Assertions.Raise_Assert_Failure} is called | |
1811 | which results in the raising of @code{Assert_Failure} with the given message. | |
1812 | ||
1813 | You should generally avoid side effects in the expression arguments of | |
1814 | this pragma, because these side effects will turn on and off with the | |
1815 | setting of the assertions mode, resulting in assertions that have an | |
1816 | effect on the program. However, the expressions are analyzed for | |
1817 | semantic correctness whether or not assertions are enabled, so turning | |
1818 | assertions on and off cannot affect the legality of a program. | |
1819 | ||
1820 | Note that the implementation defined policy @code{DISABLE}, given in a | |
1821 | pragma @code{Assertion_Policy}, can be used to suppress this semantic analysis. | |
1822 | ||
1823 | Note: this is a standard language-defined pragma in versions | |
1824 | of Ada from 2005 on. In GNAT, it is implemented in all versions | |
1825 | of Ada, and the DISABLE policy is an implementation-defined | |
1826 | addition. | |
1827 | ||
1828 | @node Pragma Assert_And_Cut,Pragma Assertion_Policy,Pragma Assert,Implementation Defined Pragmas | |
1829 | @anchor{gnat_rm/implementation_defined_pragmas pragma-assert-and-cut}@anchor{2b} | |
1830 | @section Pragma Assert_And_Cut | |
1831 | ||
1832 | ||
1833 | Syntax: | |
1834 | ||
1835 | @example | |
1836 | pragma Assert_And_Cut ( | |
1837 | boolean_EXPRESSION | |
1838 | [, string_EXPRESSION]); | |
1839 | @end example | |
1840 | ||
1841 | The effect of this pragma is identical to that of pragma @code{Assert}, | |
1842 | except that in an @code{Assertion_Policy} pragma, the identifier | |
1843 | @code{Assert_And_Cut} is used to control whether it is ignored or checked | |
1844 | (or disabled). | |
1845 | ||
1846 | The intention is that this be used within a subprogram when the | |
1847 | given test expresion sums up all the work done so far in the | |
1848 | subprogram, so that the rest of the subprogram can be verified | |
1849 | (informally or formally) using only the entry preconditions, | |
1850 | and the expression in this pragma. This allows dividing up | |
1851 | a subprogram into sections for the purposes of testing or | |
1852 | formal verification. The pragma also serves as useful | |
1853 | documentation. | |
1854 | ||
1855 | @node Pragma Assertion_Policy,Pragma Assume,Pragma Assert_And_Cut,Implementation Defined Pragmas | |
1856 | @anchor{gnat_rm/implementation_defined_pragmas pragma-assertion-policy}@anchor{2c} | |
1857 | @section Pragma Assertion_Policy | |
1858 | ||
1859 | ||
1860 | Syntax: | |
1861 | ||
1862 | @example | |
1863 | pragma Assertion_Policy (CHECK | DISABLE | IGNORE | SUPPRESSIBLE); | |
1864 | ||
1865 | pragma Assertion_Policy ( | |
1866 | ASSERTION_KIND => POLICY_IDENTIFIER | |
1867 | @{, ASSERTION_KIND => POLICY_IDENTIFIER@}); | |
1868 | ||
1869 | ASSERTION_KIND ::= RM_ASSERTION_KIND | ID_ASSERTION_KIND | |
1870 | ||
1871 | RM_ASSERTION_KIND ::= Assert | | |
1872 | Static_Predicate | | |
1873 | Dynamic_Predicate | | |
1874 | Pre | | |
1875 | Pre'Class | | |
1876 | Post | | |
1877 | Post'Class | | |
1878 | Type_Invariant | | |
1879 | Type_Invariant'Class | | |
1880 | Default_Initial_Condition | |
1881 | ||
1882 | ID_ASSERTION_KIND ::= Assertions | | |
1883 | Assert_And_Cut | | |
1884 | Assume | | |
1885 | Contract_Cases | | |
1886 | Debug | | |
1887 | Ghost | | |
1888 | Initial_Condition | | |
1889 | Invariant | | |
1890 | Invariant'Class | | |
1891 | Loop_Invariant | | |
1892 | Loop_Variant | | |
1893 | Postcondition | | |
1894 | Precondition | | |
1895 | Predicate | | |
1896 | Refined_Post | | |
1897 | Statement_Assertions | | |
1898 | Subprogram_Variant | |
1899 | ||
1900 | POLICY_IDENTIFIER ::= Check | Disable | Ignore | Suppressible | |
1901 | @end example | |
1902 | ||
1903 | This is a standard Ada 2012 pragma that is available as an | |
1904 | implementation-defined pragma in earlier versions of Ada. | |
1905 | The assertion kinds @code{RM_ASSERTION_KIND} are those defined in | |
1906 | the Ada standard. The assertion kinds @code{ID_ASSERTION_KIND} | |
1907 | are implementation defined additions recognized by the GNAT compiler. | |
1908 | ||
1909 | The pragma applies in both cases to pragmas and aspects with matching | |
1910 | names, e.g. @code{Pre} applies to the Pre aspect, and @code{Precondition} | |
1911 | applies to both the @code{Precondition} pragma | |
1912 | and the aspect @code{Precondition}. Note that the identifiers for | |
1913 | pragmas Pre_Class and Post_Class are Pre’Class and Post’Class (not | |
1914 | Pre_Class and Post_Class), since these pragmas are intended to be | |
1915 | identical to the corresponding aspects. | |
1916 | ||
1917 | If the policy is @code{CHECK}, then assertions are enabled, i.e. | |
1918 | the corresponding pragma or aspect is activated. | |
1919 | If the policy is @code{IGNORE}, then assertions are ignored, i.e. | |
1920 | the corresponding pragma or aspect is deactivated. | |
1921 | This pragma overrides the effect of the `-gnata' switch on the | |
1922 | command line. | |
1923 | If the policy is @code{SUPPRESSIBLE}, then assertions are enabled by default, | |
1924 | however, if the `-gnatp' switch is specified all assertions are ignored. | |
1925 | ||
1926 | The implementation defined policy @code{DISABLE} is like | |
1927 | @code{IGNORE} except that it completely disables semantic | |
1928 | checking of the corresponding pragma or aspect. This is | |
1929 | useful when the pragma or aspect argument references subprograms | |
1930 | in a with’ed package which is replaced by a dummy package | |
1931 | for the final build. | |
1932 | ||
1933 | The implementation defined assertion kind @code{Assertions} applies to all | |
1934 | assertion kinds. The form with no assertion kind given implies this | |
1935 | choice, so it applies to all assertion kinds (RM defined, and | |
1936 | implementation defined). | |
1937 | ||
1938 | The implementation defined assertion kind @code{Statement_Assertions} | |
1939 | applies to @code{Assert}, @code{Assert_And_Cut}, | |
1940 | @code{Assume}, @code{Loop_Invariant}, and @code{Loop_Variant}. | |
1941 | ||
1942 | @node Pragma Assume,Pragma Assume_No_Invalid_Values,Pragma Assertion_Policy,Implementation Defined Pragmas | |
1943 | @anchor{gnat_rm/implementation_defined_pragmas pragma-assume}@anchor{2d} | |
1944 | @section Pragma Assume | |
1945 | ||
1946 | ||
1947 | Syntax: | |
1948 | ||
1949 | @example | |
1950 | pragma Assume ( | |
1951 | boolean_EXPRESSION | |
1952 | [, string_EXPRESSION]); | |
1953 | @end example | |
1954 | ||
1955 | The effect of this pragma is identical to that of pragma @code{Assert}, | |
1956 | except that in an @code{Assertion_Policy} pragma, the identifier | |
1957 | @code{Assume} is used to control whether it is ignored or checked | |
1958 | (or disabled). | |
1959 | ||
1960 | The intention is that this be used for assumptions about the | |
1961 | external environment. So you cannot expect to verify formally | |
1962 | or informally that the condition is met, this must be | |
1963 | established by examining things outside the program itself. | |
1964 | For example, we may have code that depends on the size of | |
1965 | @code{Long_Long_Integer} being at least 64. So we could write: | |
1966 | ||
1967 | @example | |
1968 | pragma Assume (Long_Long_Integer'Size >= 64); | |
1969 | @end example | |
1970 | ||
1971 | This assumption cannot be proved from the program itself, | |
1972 | but it acts as a useful run-time check that the assumption | |
1973 | is met, and documents the need to ensure that it is met by | |
1974 | reference to information outside the program. | |
1975 | ||
1976 | @node Pragma Assume_No_Invalid_Values,Pragma Async_Readers,Pragma Assume,Implementation Defined Pragmas | |
1977 | @anchor{gnat_rm/implementation_defined_pragmas pragma-assume-no-invalid-values}@anchor{2e} | |
1978 | @section Pragma Assume_No_Invalid_Values | |
1979 | ||
1980 | ||
1981 | @geindex Invalid representations | |
1982 | ||
1983 | @geindex Invalid values | |
1984 | ||
1985 | Syntax: | |
1986 | ||
1987 | @example | |
1988 | pragma Assume_No_Invalid_Values (On | Off); | |
1989 | @end example | |
1990 | ||
1991 | This is a configuration pragma that controls the assumptions made by the | |
1992 | compiler about the occurrence of invalid representations (invalid values) | |
1993 | in the code. | |
1994 | ||
1995 | The default behavior (corresponding to an Off argument for this pragma), is | |
1996 | to assume that values may in general be invalid unless the compiler can | |
1997 | prove they are valid. Consider the following example: | |
1998 | ||
1999 | @example | |
2000 | V1 : Integer range 1 .. 10; | |
2001 | V2 : Integer range 11 .. 20; | |
2002 | ... | |
2003 | for J in V2 .. V1 loop | |
2004 | ... | |
2005 | end loop; | |
2006 | @end example | |
2007 | ||
2008 | if V1 and V2 have valid values, then the loop is known at compile | |
2009 | time not to execute since the lower bound must be greater than the | |
2010 | upper bound. However in default mode, no such assumption is made, | |
2011 | and the loop may execute. If @code{Assume_No_Invalid_Values (On)} | |
2012 | is given, the compiler will assume that any occurrence of a variable | |
2013 | other than in an explicit @code{'Valid} test always has a valid | |
2014 | value, and the loop above will be optimized away. | |
2015 | ||
2016 | The use of @code{Assume_No_Invalid_Values (On)} is appropriate if | |
2017 | you know your code is free of uninitialized variables and other | |
2018 | possible sources of invalid representations, and may result in | |
2019 | more efficient code. A program that accesses an invalid representation | |
2020 | with this pragma in effect is erroneous, so no guarantees can be made | |
2021 | about its behavior. | |
2022 | ||
2023 | It is peculiar though permissible to use this pragma in conjunction | |
2024 | with validity checking (-gnatVa). In such cases, accessing invalid | |
2025 | values will generally give an exception, though formally the program | |
2026 | is erroneous so there are no guarantees that this will always be the | |
2027 | case, and it is recommended that these two options not be used together. | |
2028 | ||
2029 | @node Pragma Async_Readers,Pragma Async_Writers,Pragma Assume_No_Invalid_Values,Implementation Defined Pragmas | |
2030 | @anchor{gnat_rm/implementation_defined_pragmas id4}@anchor{2f}@anchor{gnat_rm/implementation_defined_pragmas pragma-async-readers}@anchor{30} | |
2031 | @section Pragma Async_Readers | |
2032 | ||
2033 | ||
2034 | Syntax: | |
2035 | ||
2036 | @example | |
2037 | pragma Async_Readers [ (static_boolean_EXPRESSION) ]; | |
2038 | @end example | |
2039 | ||
2040 | For the semantics of this pragma, see the entry for aspect @code{Async_Readers} in | |
2041 | the SPARK 2014 Reference Manual, section 7.1.2. | |
2042 | ||
2043 | @node Pragma Async_Writers,Pragma Attribute_Definition,Pragma Async_Readers,Implementation Defined Pragmas | |
2044 | @anchor{gnat_rm/implementation_defined_pragmas id5}@anchor{31}@anchor{gnat_rm/implementation_defined_pragmas pragma-async-writers}@anchor{32} | |
2045 | @section Pragma Async_Writers | |
2046 | ||
2047 | ||
2048 | Syntax: | |
2049 | ||
2050 | @example | |
2051 | pragma Async_Writers [ (static_boolean_EXPRESSION) ]; | |
2052 | @end example | |
2053 | ||
2054 | For the semantics of this pragma, see the entry for aspect @code{Async_Writers} in | |
2055 | the SPARK 2014 Reference Manual, section 7.1.2. | |
2056 | ||
2057 | @node Pragma Attribute_Definition,Pragma C_Pass_By_Copy,Pragma Async_Writers,Implementation Defined Pragmas | |
2058 | @anchor{gnat_rm/implementation_defined_pragmas pragma-attribute-definition}@anchor{33} | |
2059 | @section Pragma Attribute_Definition | |
2060 | ||
2061 | ||
2062 | Syntax: | |
2063 | ||
2064 | @example | |
2065 | pragma Attribute_Definition | |
2066 | ([Attribute =>] ATTRIBUTE_DESIGNATOR, | |
2067 | [Entity =>] LOCAL_NAME, | |
2068 | [Expression =>] EXPRESSION | NAME); | |
2069 | @end example | |
2070 | ||
2071 | If @code{Attribute} is a known attribute name, this pragma is equivalent to | |
2072 | the attribute definition clause: | |
2073 | ||
2074 | @example | |
2075 | for Entity'Attribute use Expression; | |
2076 | @end example | |
2077 | ||
2078 | If @code{Attribute} is not a recognized attribute name, the pragma is | |
2079 | ignored, and a warning is emitted. This allows source | |
2080 | code to be written that takes advantage of some new attribute, while remaining | |
2081 | compilable with earlier compilers. | |
2082 | ||
2083 | @node Pragma C_Pass_By_Copy,Pragma Check,Pragma Attribute_Definition,Implementation Defined Pragmas | |
2084 | @anchor{gnat_rm/implementation_defined_pragmas pragma-c-pass-by-copy}@anchor{34} | |
2085 | @section Pragma C_Pass_By_Copy | |
2086 | ||
2087 | ||
2088 | @geindex Passing by copy | |
2089 | ||
2090 | Syntax: | |
2091 | ||
2092 | @example | |
2093 | pragma C_Pass_By_Copy | |
2094 | ([Max_Size =>] static_integer_EXPRESSION); | |
2095 | @end example | |
2096 | ||
2097 | Normally the default mechanism for passing C convention records to C | |
2098 | convention subprograms is to pass them by reference, as suggested by RM | |
2099 | B.3(69). Use the configuration pragma @code{C_Pass_By_Copy} to change | |
2100 | this default, by requiring that record formal parameters be passed by | |
2101 | copy if all of the following conditions are met: | |
2102 | ||
2103 | ||
2104 | @itemize * | |
2105 | ||
2106 | @item | |
2107 | The size of the record type does not exceed the value specified for | |
2108 | @code{Max_Size}. | |
2109 | ||
2110 | @item | |
2111 | The record type has @code{Convention C}. | |
2112 | ||
2113 | @item | |
2114 | The formal parameter has this record type, and the subprogram has a | |
2115 | foreign (non-Ada) convention. | |
2116 | @end itemize | |
2117 | ||
2118 | If these conditions are met the argument is passed by copy; i.e., in a | |
2119 | manner consistent with what C expects if the corresponding formal in the | |
2120 | C prototype is a struct (rather than a pointer to a struct). | |
2121 | ||
2122 | You can also pass records by copy by specifying the convention | |
2123 | @code{C_Pass_By_Copy} for the record type, or by using the extended | |
2124 | @code{Import} and @code{Export} pragmas, which allow specification of | |
2125 | passing mechanisms on a parameter by parameter basis. | |
2126 | ||
2127 | @node Pragma Check,Pragma Check_Float_Overflow,Pragma C_Pass_By_Copy,Implementation Defined Pragmas | |
2128 | @anchor{gnat_rm/implementation_defined_pragmas pragma-check}@anchor{35} | |
2129 | @section Pragma Check | |
2130 | ||
2131 | ||
2132 | @geindex Assertions | |
2133 | ||
2134 | @geindex Named assertions | |
2135 | ||
2136 | Syntax: | |
2137 | ||
2138 | @example | |
2139 | pragma Check ( | |
2140 | [Name =>] CHECK_KIND, | |
2141 | [Check =>] Boolean_EXPRESSION | |
2142 | [, [Message =>] string_EXPRESSION] ); | |
2143 | ||
2144 | CHECK_KIND ::= IDENTIFIER | | |
2145 | Pre'Class | | |
2146 | Post'Class | | |
2147 | Type_Invariant'Class | | |
2148 | Invariant'Class | |
2149 | @end example | |
2150 | ||
2151 | This pragma is similar to the predefined pragma @code{Assert} except that an | |
2152 | extra identifier argument is present. In conjunction with pragma | |
2153 | @code{Check_Policy}, this can be used to define groups of assertions that can | |
2154 | be independently controlled. The identifier @code{Assertion} is special, it | |
2155 | refers to the normal set of pragma @code{Assert} statements. | |
2156 | ||
2157 | Checks introduced by this pragma are normally deactivated by default. They can | |
2158 | be activated either by the command line option `-gnata', which turns on | |
2159 | all checks, or individually controlled using pragma @code{Check_Policy}. | |
2160 | ||
2161 | The identifiers @code{Assertions} and @code{Statement_Assertions} are not | |
2162 | permitted as check kinds, since this would cause confusion with the use | |
2163 | of these identifiers in @code{Assertion_Policy} and @code{Check_Policy} | |
2164 | pragmas, where they are used to refer to sets of assertions. | |
2165 | ||
2166 | @node Pragma Check_Float_Overflow,Pragma Check_Name,Pragma Check,Implementation Defined Pragmas | |
2167 | @anchor{gnat_rm/implementation_defined_pragmas pragma-check-float-overflow}@anchor{36} | |
2168 | @section Pragma Check_Float_Overflow | |
2169 | ||
2170 | ||
2171 | @geindex Floating-point overflow | |
2172 | ||
2173 | Syntax: | |
2174 | ||
2175 | @example | |
2176 | pragma Check_Float_Overflow; | |
2177 | @end example | |
2178 | ||
2179 | In Ada, the predefined floating-point types (@code{Short_Float}, | |
2180 | @code{Float}, @code{Long_Float}, @code{Long_Long_Float}) are | |
2181 | defined to be `unconstrained'. This means that even though each | |
2182 | has a well-defined base range, an operation that delivers a result | |
2183 | outside this base range is not required to raise an exception. | |
2184 | This implementation permission accommodates the notion | |
2185 | of infinities in IEEE floating-point, and corresponds to the | |
2186 | efficient execution mode on most machines. GNAT will not raise | |
2187 | overflow exceptions on these machines; instead it will generate | |
2188 | infinities and NaN’s as defined in the IEEE standard. | |
2189 | ||
2190 | Generating infinities, although efficient, is not always desirable. | |
2191 | Often the preferable approach is to check for overflow, even at the | |
2192 | (perhaps considerable) expense of run-time performance. | |
2193 | This can be accomplished by defining your own constrained floating-point subtypes – i.e., by supplying explicit | |
2194 | range constraints – and indeed such a subtype | |
2195 | can have the same base range as its base type. For example: | |
2196 | ||
2197 | @example | |
2198 | subtype My_Float is Float range Float'Range; | |
2199 | @end example | |
2200 | ||
2201 | Here @code{My_Float} has the same range as | |
2202 | @code{Float} but is constrained, so operations on | |
2203 | @code{My_Float} values will be checked for overflow | |
2204 | against this range. | |
2205 | ||
2206 | This style will achieve the desired goal, but | |
2207 | it is often more convenient to be able to simply use | |
2208 | the standard predefined floating-point types as long | |
2209 | as overflow checking could be guaranteed. | |
2210 | The @code{Check_Float_Overflow} | |
2211 | configuration pragma achieves this effect. If a unit is compiled | |
2212 | subject to this configuration pragma, then all operations | |
2213 | on predefined floating-point types including operations on | |
2214 | base types of these floating-point types will be treated as | |
2215 | though those types were constrained, and overflow checks | |
2216 | will be generated. The @code{Constraint_Error} | |
2217 | exception is raised if the result is out of range. | |
2218 | ||
2219 | This mode can also be set by use of the compiler | |
2220 | switch `-gnateF'. | |
2221 | ||
2222 | @node Pragma Check_Name,Pragma Check_Policy,Pragma Check_Float_Overflow,Implementation Defined Pragmas | |
2223 | @anchor{gnat_rm/implementation_defined_pragmas pragma-check-name}@anchor{37} | |
2224 | @section Pragma Check_Name | |
2225 | ||
2226 | ||
2227 | @geindex Defining check names | |
2228 | ||
2229 | @geindex Check names | |
2230 | @geindex defining | |
2231 | ||
2232 | Syntax: | |
2233 | ||
2234 | @example | |
2235 | pragma Check_Name (check_name_IDENTIFIER); | |
2236 | @end example | |
2237 | ||
2238 | This is a configuration pragma that defines a new implementation | |
2239 | defined check name (unless IDENTIFIER matches one of the predefined | |
2240 | check names, in which case the pragma has no effect). Check names | |
2241 | are global to a partition, so if two or more configuration pragmas | |
2242 | are present in a partition mentioning the same name, only one new | |
2243 | check name is introduced. | |
2244 | ||
2245 | An implementation defined check name introduced with this pragma may | |
2246 | be used in only three contexts: @code{pragma Suppress}, | |
2247 | @code{pragma Unsuppress}, | |
2248 | and as the prefix of a @code{Check_Name'Enabled} attribute reference. For | |
2249 | any of these three cases, the check name must be visible. A check | |
2250 | name is visible if it is in the configuration pragmas applying to | |
2251 | the current unit, or if it appears at the start of any unit that | |
2252 | is part of the dependency set of the current unit (e.g., units that | |
2253 | are mentioned in @code{with} clauses). | |
2254 | ||
2255 | Check names introduced by this pragma are subject to control by compiler | |
2256 | switches (in particular -gnatp) in the usual manner. | |
2257 | ||
2258 | @node Pragma Check_Policy,Pragma Comment,Pragma Check_Name,Implementation Defined Pragmas | |
2259 | @anchor{gnat_rm/implementation_defined_pragmas pragma-check-policy}@anchor{38} | |
2260 | @section Pragma Check_Policy | |
2261 | ||
2262 | ||
2263 | @geindex Controlling assertions | |
2264 | ||
2265 | @geindex Assertions | |
2266 | @geindex control | |
2267 | ||
2268 | @geindex Check pragma control | |
2269 | ||
2270 | @geindex Named assertions | |
2271 | ||
2272 | Syntax: | |
2273 | ||
2274 | @example | |
2275 | pragma Check_Policy | |
2276 | ([Name =>] CHECK_KIND, | |
2277 | [Policy =>] POLICY_IDENTIFIER); | |
2278 | ||
2279 | pragma Check_Policy ( | |
2280 | CHECK_KIND => POLICY_IDENTIFIER | |
2281 | @{, CHECK_KIND => POLICY_IDENTIFIER@}); | |
2282 | ||
2283 | ASSERTION_KIND ::= RM_ASSERTION_KIND | ID_ASSERTION_KIND | |
2284 | ||
2285 | CHECK_KIND ::= IDENTIFIER | | |
2286 | Pre'Class | | |
2287 | Post'Class | | |
2288 | Type_Invariant'Class | | |
2289 | Invariant'Class | |
2290 | ||
2291 | The identifiers Name and Policy are not allowed as CHECK_KIND values. This | |
2292 | avoids confusion between the two possible syntax forms for this pragma. | |
2293 | ||
2294 | POLICY_IDENTIFIER ::= ON | OFF | CHECK | DISABLE | IGNORE | |
2295 | @end example | |
2296 | ||
2297 | This pragma is used to set the checking policy for assertions (specified | |
2298 | by aspects or pragmas), the @code{Debug} pragma, or additional checks | |
2299 | to be checked using the @code{Check} pragma. It may appear either as | |
2300 | a configuration pragma, or within a declarative part of package. In the | |
2301 | latter case, it applies from the point where it appears to the end of | |
2302 | the declarative region (like pragma @code{Suppress}). | |
2303 | ||
2304 | The @code{Check_Policy} pragma is similar to the | |
2305 | predefined @code{Assertion_Policy} pragma, | |
2306 | and if the check kind corresponds to one of the assertion kinds that | |
2307 | are allowed by @code{Assertion_Policy}, then the effect is identical. | |
2308 | ||
2309 | If the first argument is Debug, then the policy applies to Debug pragmas, | |
2310 | disabling their effect if the policy is @code{OFF}, @code{DISABLE}, or | |
2311 | @code{IGNORE}, and allowing them to execute with normal semantics if | |
2312 | the policy is @code{ON} or @code{CHECK}. In addition if the policy is | |
2313 | @code{DISABLE}, then the procedure call in @code{Debug} pragmas will | |
2314 | be totally ignored and not analyzed semantically. | |
2315 | ||
2316 | Finally the first argument may be some other identifier than the above | |
2317 | possibilities, in which case it controls a set of named assertions | |
2318 | that can be checked using pragma @code{Check}. For example, if the pragma: | |
2319 | ||
2320 | @example | |
2321 | pragma Check_Policy (Critical_Error, OFF); | |
2322 | @end example | |
2323 | ||
2324 | is given, then subsequent @code{Check} pragmas whose first argument is also | |
2325 | @code{Critical_Error} will be disabled. | |
2326 | ||
2327 | The check policy is @code{OFF} to turn off corresponding checks, and @code{ON} | |
2328 | to turn on corresponding checks. The default for a set of checks for which no | |
2329 | @code{Check_Policy} is given is @code{OFF} unless the compiler switch | |
2330 | `-gnata' is given, which turns on all checks by default. | |
2331 | ||
2332 | The check policy settings @code{CHECK} and @code{IGNORE} are recognized | |
2333 | as synonyms for @code{ON} and @code{OFF}. These synonyms are provided for | |
2334 | compatibility with the standard @code{Assertion_Policy} pragma. The check | |
2335 | policy setting @code{DISABLE} causes the second argument of a corresponding | |
2336 | @code{Check} pragma to be completely ignored and not analyzed. | |
2337 | ||
2338 | @node Pragma Comment,Pragma Common_Object,Pragma Check_Policy,Implementation Defined Pragmas | |
2339 | @anchor{gnat_rm/implementation_defined_pragmas pragma-comment}@anchor{39} | |
2340 | @section Pragma Comment | |
2341 | ||
2342 | ||
2343 | Syntax: | |
2344 | ||
2345 | @example | |
2346 | pragma Comment (static_string_EXPRESSION); | |
2347 | @end example | |
2348 | ||
2349 | This is almost identical in effect to pragma @code{Ident}. It allows the | |
2350 | placement of a comment into the object file and hence into the | |
2351 | executable file if the operating system permits such usage. The | |
2352 | difference is that @code{Comment}, unlike @code{Ident}, has | |
2353 | no limitations on placement of the pragma (it can be placed | |
2354 | anywhere in the main source unit), and if more than one pragma | |
2355 | is used, all comments are retained. | |
2356 | ||
2357 | @node Pragma Common_Object,Pragma Compile_Time_Error,Pragma Comment,Implementation Defined Pragmas | |
2358 | @anchor{gnat_rm/implementation_defined_pragmas pragma-common-object}@anchor{3a} | |
2359 | @section Pragma Common_Object | |
2360 | ||
2361 | ||
2362 | Syntax: | |
2363 | ||
2364 | @example | |
2365 | pragma Common_Object ( | |
2366 | [Internal =>] LOCAL_NAME | |
2367 | [, [External =>] EXTERNAL_SYMBOL] | |
2368 | [, [Size =>] EXTERNAL_SYMBOL] ); | |
2369 | ||
2370 | EXTERNAL_SYMBOL ::= | |
2371 | IDENTIFIER | |
2372 | | static_string_EXPRESSION | |
2373 | @end example | |
2374 | ||
2375 | This pragma enables the shared use of variables stored in overlaid | |
2376 | linker areas corresponding to the use of @code{COMMON} | |
2377 | in Fortran. The single | |
2378 | object @code{LOCAL_NAME} is assigned to the area designated by | |
2379 | the @code{External} argument. | |
2380 | You may define a record to correspond to a series | |
2381 | of fields. The @code{Size} argument | |
2382 | is syntax checked in GNAT, but otherwise ignored. | |
2383 | ||
2384 | @code{Common_Object} is not supported on all platforms. If no | |
2385 | support is available, then the code generator will issue a message | |
2386 | indicating that the necessary attribute for implementation of this | |
2387 | pragma is not available. | |
2388 | ||
2389 | @node Pragma Compile_Time_Error,Pragma Compile_Time_Warning,Pragma Common_Object,Implementation Defined Pragmas | |
2390 | @anchor{gnat_rm/implementation_defined_pragmas compile-time-error}@anchor{3b}@anchor{gnat_rm/implementation_defined_pragmas pragma-compile-time-error}@anchor{3c} | |
2391 | @section Pragma Compile_Time_Error | |
2392 | ||
2393 | ||
2394 | Syntax: | |
2395 | ||
2396 | @example | |
2397 | pragma Compile_Time_Error | |
2398 | (boolean_EXPRESSION, static_string_EXPRESSION); | |
2399 | @end example | |
2400 | ||
2401 | This pragma can be used to generate additional compile time | |
2402 | error messages. It | |
2403 | is particularly useful in generics, where errors can be issued for | |
2404 | specific problematic instantiations. The first parameter is a boolean | |
2405 | expression. The pragma ensures that the value of an expression | |
2406 | is known at compile time, and has the value False. The set of expressions | |
2407 | whose values are known at compile time includes all static boolean | |
2408 | expressions, and also other values which the compiler can determine | |
2409 | at compile time (e.g., the size of a record type set by an explicit | |
2410 | size representation clause, or the value of a variable which was | |
2411 | initialized to a constant and is known not to have been modified). | |
2412 | If these conditions are not met, an error message is generated using | |
2413 | the value given as the second argument. This string value may contain | |
2414 | embedded ASCII.LF characters to break the message into multiple lines. | |
2415 | ||
2416 | @node Pragma Compile_Time_Warning,Pragma Complete_Representation,Pragma Compile_Time_Error,Implementation Defined Pragmas | |
2417 | @anchor{gnat_rm/implementation_defined_pragmas pragma-compile-time-warning}@anchor{3d} | |
2418 | @section Pragma Compile_Time_Warning | |
2419 | ||
2420 | ||
2421 | Syntax: | |
2422 | ||
2423 | @example | |
2424 | pragma Compile_Time_Warning | |
2425 | (boolean_EXPRESSION, static_string_EXPRESSION); | |
2426 | @end example | |
2427 | ||
2428 | Same as pragma Compile_Time_Error, except a warning is issued instead | |
2429 | of an error message. If switch `-gnatw_C' is used, a warning is only issued | |
2430 | if the value of the expression is known to be True at compile time, not when | |
2431 | the value of the expression is not known at compile time. | |
2432 | Note that if this pragma is used in a package that | |
2433 | is with’ed by a client, the client will get the warning even though it | |
2434 | is issued by a with’ed package (normally warnings in with’ed units are | |
2435 | suppressed, but this is a special exception to that rule). | |
2436 | ||
2437 | One typical use is within a generic where compile time known characteristics | |
2438 | of formal parameters are tested, and warnings given appropriately. Another use | |
2439 | with a first parameter of True is to warn a client about use of a package, | |
2440 | for example that it is not fully implemented. | |
2441 | ||
2442 | In previous versions of the compiler, combining `-gnatwe' with | |
2443 | Compile_Time_Warning resulted in a fatal error. Now the compiler always emits | |
2444 | a warning. You can use @ref{3b,,Pragma Compile_Time_Error} to force the generation of | |
2445 | an error. | |
2446 | ||
2447 | @node Pragma Complete_Representation,Pragma Complex_Representation,Pragma Compile_Time_Warning,Implementation Defined Pragmas | |
2448 | @anchor{gnat_rm/implementation_defined_pragmas pragma-complete-representation}@anchor{3e} | |
2449 | @section Pragma Complete_Representation | |
2450 | ||
2451 | ||
2452 | Syntax: | |
2453 | ||
2454 | @example | |
2455 | pragma Complete_Representation; | |
2456 | @end example | |
2457 | ||
2458 | This pragma must appear immediately within a record representation | |
2459 | clause. Typical placements are before the first component clause | |
2460 | or after the last component clause. The effect is to give an error | |
2461 | message if any component is missing a component clause. This pragma | |
2462 | may be used to ensure that a record representation clause is | |
2463 | complete, and that this invariant is maintained if fields are | |
2464 | added to the record in the future. | |
2465 | ||
2466 | @node Pragma Complex_Representation,Pragma Component_Alignment,Pragma Complete_Representation,Implementation Defined Pragmas | |
2467 | @anchor{gnat_rm/implementation_defined_pragmas pragma-complex-representation}@anchor{3f} | |
2468 | @section Pragma Complex_Representation | |
2469 | ||
2470 | ||
2471 | Syntax: | |
2472 | ||
2473 | @example | |
2474 | pragma Complex_Representation | |
2475 | ([Entity =>] LOCAL_NAME); | |
2476 | @end example | |
2477 | ||
2478 | The @code{Entity} argument must be the name of a record type which has | |
2479 | two fields of the same floating-point type. The effect of this pragma is | |
2480 | to force gcc to use the special internal complex representation form for | |
2481 | this record, which may be more efficient. Note that this may result in | |
2482 | the code for this type not conforming to standard ABI (application | |
2483 | binary interface) requirements for the handling of record types. For | |
2484 | example, in some environments, there is a requirement for passing | |
2485 | records by pointer, and the use of this pragma may result in passing | |
2486 | this type in floating-point registers. | |
2487 | ||
2488 | @node Pragma Component_Alignment,Pragma Constant_After_Elaboration,Pragma Complex_Representation,Implementation Defined Pragmas | |
2489 | @anchor{gnat_rm/implementation_defined_pragmas pragma-component-alignment}@anchor{40} | |
2490 | @section Pragma Component_Alignment | |
2491 | ||
2492 | ||
2493 | @geindex Alignments of components | |
2494 | ||
2495 | @geindex Pragma Component_Alignment | |
2496 | ||
2497 | Syntax: | |
2498 | ||
2499 | @example | |
2500 | pragma Component_Alignment ( | |
2501 | [Form =>] ALIGNMENT_CHOICE | |
2502 | [, [Name =>] type_LOCAL_NAME]); | |
2503 | ||
2504 | ALIGNMENT_CHOICE ::= | |
2505 | Component_Size | |
2506 | | Component_Size_4 | |
2507 | | Storage_Unit | |
2508 | | Default | |
2509 | @end example | |
2510 | ||
2511 | Specifies the alignment of components in array or record types. | |
2512 | The meaning of the @code{Form} argument is as follows: | |
2513 | ||
2514 | @quotation | |
2515 | ||
2516 | @geindex Component_Size (in pragma Component_Alignment) | |
2517 | @end quotation | |
2518 | ||
2519 | ||
2520 | @table @asis | |
2521 | ||
2522 | @item `Component_Size' | |
2523 | ||
2524 | Aligns scalar components and subcomponents of the array or record type | |
2525 | on boundaries appropriate to their inherent size (naturally | |
2526 | aligned). For example, 1-byte components are aligned on byte boundaries, | |
2527 | 2-byte integer components are aligned on 2-byte boundaries, 4-byte | |
2528 | integer components are aligned on 4-byte boundaries and so on. These | |
2529 | alignment rules correspond to the normal rules for C compilers on all | |
2530 | machines except the VAX. | |
2531 | ||
2532 | @geindex Component_Size_4 (in pragma Component_Alignment) | |
2533 | ||
2534 | @item `Component_Size_4' | |
2535 | ||
2536 | Naturally aligns components with a size of four or fewer | |
2537 | bytes. Components that are larger than 4 bytes are placed on the next | |
2538 | 4-byte boundary. | |
2539 | ||
2540 | @geindex Storage_Unit (in pragma Component_Alignment) | |
2541 | ||
2542 | @item `Storage_Unit' | |
2543 | ||
2544 | Specifies that array or record components are byte aligned, i.e., | |
2545 | aligned on boundaries determined by the value of the constant | |
2546 | @code{System.Storage_Unit}. | |
2547 | ||
2548 | @geindex Default (in pragma Component_Alignment) | |
2549 | ||
2550 | @item `Default' | |
2551 | ||
2552 | Specifies that array or record components are aligned on default | |
2553 | boundaries, appropriate to the underlying hardware or operating system or | |
2554 | both. The @code{Default} choice is the same as @code{Component_Size} (natural | |
2555 | alignment). | |
2556 | @end table | |
2557 | ||
2558 | If the @code{Name} parameter is present, @code{type_LOCAL_NAME} must | |
2559 | refer to a local record or array type, and the specified alignment | |
2560 | choice applies to the specified type. The use of | |
2561 | @code{Component_Alignment} together with a pragma @code{Pack} causes the | |
2562 | @code{Component_Alignment} pragma to be ignored. The use of | |
2563 | @code{Component_Alignment} together with a record representation clause | |
2564 | is only effective for fields not specified by the representation clause. | |
2565 | ||
2566 | If the @code{Name} parameter is absent, the pragma can be used as either | |
2567 | a configuration pragma, in which case it applies to one or more units in | |
2568 | accordance with the normal rules for configuration pragmas, or it can be | |
2569 | used within a declarative part, in which case it applies to types that | |
2570 | are declared within this declarative part, or within any nested scope | |
2571 | within this declarative part. In either case it specifies the alignment | |
2572 | to be applied to any record or array type which has otherwise standard | |
2573 | representation. | |
2574 | ||
2575 | If the alignment for a record or array type is not specified (using | |
2576 | pragma @code{Pack}, pragma @code{Component_Alignment}, or a record rep | |
2577 | clause), the GNAT uses the default alignment as described previously. | |
2578 | ||
2579 | @node Pragma Constant_After_Elaboration,Pragma Contract_Cases,Pragma Component_Alignment,Implementation Defined Pragmas | |
2580 | @anchor{gnat_rm/implementation_defined_pragmas id6}@anchor{41}@anchor{gnat_rm/implementation_defined_pragmas pragma-constant-after-elaboration}@anchor{42} | |
2581 | @section Pragma Constant_After_Elaboration | |
2582 | ||
2583 | ||
2584 | Syntax: | |
2585 | ||
2586 | @example | |
2587 | pragma Constant_After_Elaboration [ (static_boolean_EXPRESSION) ]; | |
2588 | @end example | |
2589 | ||
2590 | For the semantics of this pragma, see the entry for aspect | |
2591 | @code{Constant_After_Elaboration} in the SPARK 2014 Reference Manual, section 3.3.1. | |
2592 | ||
2593 | @node Pragma Contract_Cases,Pragma Convention_Identifier,Pragma Constant_After_Elaboration,Implementation Defined Pragmas | |
2594 | @anchor{gnat_rm/implementation_defined_pragmas id7}@anchor{43}@anchor{gnat_rm/implementation_defined_pragmas pragma-contract-cases}@anchor{44} | |
2595 | @section Pragma Contract_Cases | |
2596 | ||
2597 | ||
2598 | @geindex Contract cases | |
2599 | ||
2600 | Syntax: | |
2601 | ||
2602 | @example | |
2603 | pragma Contract_Cases (CONTRACT_CASE @{, CONTRACT_CASE@}); | |
2604 | ||
2605 | CONTRACT_CASE ::= CASE_GUARD => CONSEQUENCE | |
2606 | ||
2607 | CASE_GUARD ::= boolean_EXPRESSION | others | |
2608 | ||
2609 | CONSEQUENCE ::= boolean_EXPRESSION | |
2610 | @end example | |
2611 | ||
2612 | The @code{Contract_Cases} pragma allows defining fine-grain specifications | |
2613 | that can complement or replace the contract given by a precondition and a | |
2614 | postcondition. Additionally, the @code{Contract_Cases} pragma can be used | |
2615 | by testing and formal verification tools. The compiler checks its validity and, | |
2616 | depending on the assertion policy at the point of declaration of the pragma, | |
2617 | it may insert a check in the executable. For code generation, the contract | |
2618 | cases | |
2619 | ||
2620 | @example | |
2621 | pragma Contract_Cases ( | |
2622 | Cond1 => Pred1, | |
2623 | Cond2 => Pred2); | |
2624 | @end example | |
2625 | ||
2626 | are equivalent to | |
2627 | ||
2628 | @example | |
2629 | C1 : constant Boolean := Cond1; -- evaluated at subprogram entry | |
2630 | C2 : constant Boolean := Cond2; -- evaluated at subprogram entry | |
2631 | pragma Precondition ((C1 and not C2) or (C2 and not C1)); | |
2632 | pragma Postcondition (if C1 then Pred1); | |
2633 | pragma Postcondition (if C2 then Pred2); | |
2634 | @end example | |
2635 | ||
2636 | The precondition ensures that one and only one of the case guards is | |
2637 | satisfied on entry to the subprogram. | |
2638 | The postcondition ensures that for the case guard that was True on entry, | |
2639 | the corresponding consequence is True on exit. Other consequence expressions | |
2640 | are not evaluated. | |
2641 | ||
2642 | A precondition @code{P} and postcondition @code{Q} can also be | |
2643 | expressed as contract cases: | |
2644 | ||
2645 | @example | |
2646 | pragma Contract_Cases (P => Q); | |
2647 | @end example | |
2648 | ||
2649 | The placement and visibility rules for @code{Contract_Cases} pragmas are | |
2650 | identical to those described for preconditions and postconditions. | |
2651 | ||
2652 | The compiler checks that boolean expressions given in case guards and | |
2653 | consequences are valid, where the rules for case guards are the same as | |
2654 | the rule for an expression in @code{Precondition} and the rules for | |
2655 | consequences are the same as the rule for an expression in | |
2656 | @code{Postcondition}. In particular, attributes @code{'Old} and | |
2657 | @code{'Result} can only be used within consequence expressions. | |
2658 | The case guard for the last contract case may be @code{others}, to denote | |
2659 | any case not captured by the previous cases. The | |
2660 | following is an example of use within a package spec: | |
2661 | ||
2662 | @example | |
2663 | package Math_Functions is | |
2664 | ... | |
2665 | function Sqrt (Arg : Float) return Float; | |
2666 | pragma Contract_Cases (((Arg in 0.0 .. 99.0) => Sqrt'Result < 10.0, | |
2667 | Arg >= 100.0 => Sqrt'Result >= 10.0, | |
2668 | others => Sqrt'Result = 0.0)); | |
2669 | ... | |
2670 | end Math_Functions; | |
2671 | @end example | |
2672 | ||
2673 | The meaning of contract cases is that only one case should apply at each | |
2674 | call, as determined by the corresponding case guard evaluating to True, | |
2675 | and that the consequence for this case should hold when the subprogram | |
2676 | returns. | |
2677 | ||
2678 | @node Pragma Convention_Identifier,Pragma CPP_Class,Pragma Contract_Cases,Implementation Defined Pragmas | |
2679 | @anchor{gnat_rm/implementation_defined_pragmas pragma-convention-identifier}@anchor{45} | |
2680 | @section Pragma Convention_Identifier | |
2681 | ||
2682 | ||
2683 | @geindex Conventions | |
2684 | @geindex synonyms | |
2685 | ||
2686 | Syntax: | |
2687 | ||
2688 | @example | |
2689 | pragma Convention_Identifier ( | |
2690 | [Name =>] IDENTIFIER, | |
2691 | [Convention =>] convention_IDENTIFIER); | |
2692 | @end example | |
2693 | ||
2694 | This pragma provides a mechanism for supplying synonyms for existing | |
2695 | convention identifiers. The @code{Name} identifier can subsequently | |
2696 | be used as a synonym for the given convention in other pragmas (including | |
2697 | for example pragma @code{Import} or another @code{Convention_Identifier} | |
2698 | pragma). As an example of the use of this, suppose you had legacy code | |
2699 | which used Fortran77 as the identifier for Fortran. Then the pragma: | |
2700 | ||
2701 | @example | |
2702 | pragma Convention_Identifier (Fortran77, Fortran); | |
2703 | @end example | |
2704 | ||
2705 | would allow the use of the convention identifier @code{Fortran77} in | |
2706 | subsequent code, avoiding the need to modify the sources. As another | |
2707 | example, you could use this to parameterize convention requirements | |
2708 | according to systems. Suppose you needed to use @code{Stdcall} on | |
2709 | windows systems, and @code{C} on some other system, then you could | |
2710 | define a convention identifier @code{Library} and use a single | |
2711 | @code{Convention_Identifier} pragma to specify which convention | |
2712 | would be used system-wide. | |
2713 | ||
2714 | @node Pragma CPP_Class,Pragma CPP_Constructor,Pragma Convention_Identifier,Implementation Defined Pragmas | |
2715 | @anchor{gnat_rm/implementation_defined_pragmas pragma-cpp-class}@anchor{46} | |
2716 | @section Pragma CPP_Class | |
2717 | ||
2718 | ||
2719 | @geindex Interfacing with C++ | |
2720 | ||
2721 | Syntax: | |
2722 | ||
2723 | @example | |
2724 | pragma CPP_Class ([Entity =>] LOCAL_NAME); | |
2725 | @end example | |
2726 | ||
2727 | The argument denotes an entity in the current declarative region that is | |
2728 | declared as a record type. It indicates that the type corresponds to an | |
2729 | externally declared C++ class type, and is to be laid out the same way | |
2730 | that C++ would lay out the type. If the C++ class has virtual primitives | |
2731 | then the record must be declared as a tagged record type. | |
2732 | ||
2733 | Types for which @code{CPP_Class} is specified do not have assignment or | |
2734 | equality operators defined (such operations can be imported or declared | |
2735 | as subprograms as required). Initialization is allowed only by constructor | |
2736 | functions (see pragma @code{CPP_Constructor}). Such types are implicitly | |
2737 | limited if not explicitly declared as limited or derived from a limited | |
2738 | type, and an error is issued in that case. | |
2739 | ||
2740 | See @ref{47,,Interfacing to C++} for related information. | |
2741 | ||
2742 | Note: Pragma @code{CPP_Class} is currently obsolete. It is supported | |
2743 | for backward compatibility but its functionality is available | |
2744 | using pragma @code{Import} with @code{Convention} = @code{CPP}. | |
2745 | ||
2746 | @node Pragma CPP_Constructor,Pragma CPP_Virtual,Pragma CPP_Class,Implementation Defined Pragmas | |
2747 | @anchor{gnat_rm/implementation_defined_pragmas pragma-cpp-constructor}@anchor{48} | |
2748 | @section Pragma CPP_Constructor | |
2749 | ||
2750 | ||
2751 | @geindex Interfacing with C++ | |
2752 | ||
2753 | Syntax: | |
2754 | ||
2755 | @example | |
2756 | pragma CPP_Constructor ([Entity =>] LOCAL_NAME | |
2757 | [, [External_Name =>] static_string_EXPRESSION ] | |
2758 | [, [Link_Name =>] static_string_EXPRESSION ]); | |
2759 | @end example | |
2760 | ||
2761 | This pragma identifies an imported function (imported in the usual way | |
2762 | with pragma @code{Import}) as corresponding to a C++ constructor. If | |
2763 | @code{External_Name} and @code{Link_Name} are not specified then the | |
2764 | @code{Entity} argument is a name that must have been previously mentioned | |
2765 | in a pragma @code{Import} with @code{Convention} = @code{CPP}. Such name | |
2766 | must be of one of the following forms: | |
2767 | ||
2768 | ||
2769 | @itemize * | |
2770 | ||
2771 | @item | |
2772 | `function' @code{Fname} `return' T` | |
2773 | ||
2774 | @item | |
2775 | `function' @code{Fname} `return' T’Class | |
2776 | ||
2777 | @item | |
2778 | `function' @code{Fname} (…) `return' T` | |
2779 | ||
2780 | @item | |
2781 | `function' @code{Fname} (…) `return' T’Class | |
2782 | @end itemize | |
2783 | ||
2784 | where @code{T} is a limited record type imported from C++ with pragma | |
2785 | @code{Import} and @code{Convention} = @code{CPP}. | |
2786 | ||
2787 | The first two forms import the default constructor, used when an object | |
2788 | of type @code{T} is created on the Ada side with no explicit constructor. | |
2789 | The latter two forms cover all the non-default constructors of the type. | |
2790 | See the GNAT User’s Guide for details. | |
2791 | ||
2792 | If no constructors are imported, it is impossible to create any objects | |
2793 | on the Ada side and the type is implicitly declared abstract. | |
2794 | ||
2795 | Pragma @code{CPP_Constructor} is intended primarily for automatic generation | |
2796 | using an automatic binding generator tool (such as the @code{-fdump-ada-spec} | |
2797 | GCC switch). | |
2798 | See @ref{47,,Interfacing to C++} for more related information. | |
2799 | ||
2800 | Note: The use of functions returning class-wide types for constructors is | |
2801 | currently obsolete. They are supported for backward compatibility. The | |
2802 | use of functions returning the type T leave the Ada sources more clear | |
2803 | because the imported C++ constructors always return an object of type T; | |
2804 | that is, they never return an object whose type is a descendant of type T. | |
2805 | ||
2806 | @node Pragma CPP_Virtual,Pragma CPP_Vtable,Pragma CPP_Constructor,Implementation Defined Pragmas | |
2807 | @anchor{gnat_rm/implementation_defined_pragmas pragma-cpp-virtual}@anchor{49} | |
2808 | @section Pragma CPP_Virtual | |
2809 | ||
2810 | ||
2811 | @geindex Interfacing to C++ | |
2812 | ||
2813 | This pragma is now obsolete and, other than generating a warning if warnings | |
2814 | on obsolescent features are enabled, is completely ignored. | |
2815 | It is retained for compatibility | |
2816 | purposes. It used to be required to ensure compatibility with C++, but | |
2817 | is no longer required for that purpose because GNAT generates | |
2818 | the same object layout as the G++ compiler by default. | |
2819 | ||
2820 | See @ref{47,,Interfacing to C++} for related information. | |
2821 | ||
2822 | @node Pragma CPP_Vtable,Pragma CPU,Pragma CPP_Virtual,Implementation Defined Pragmas | |
2823 | @anchor{gnat_rm/implementation_defined_pragmas pragma-cpp-vtable}@anchor{4a} | |
2824 | @section Pragma CPP_Vtable | |
2825 | ||
2826 | ||
2827 | @geindex Interfacing with C++ | |
2828 | ||
2829 | This pragma is now obsolete and, other than generating a warning if warnings | |
2830 | on obsolescent features are enabled, is completely ignored. | |
2831 | It used to be required to ensure compatibility with C++, but | |
2832 | is no longer required for that purpose because GNAT generates | |
2833 | the same object layout as the G++ compiler by default. | |
2834 | ||
2835 | See @ref{47,,Interfacing to C++} for related information. | |
2836 | ||
2837 | @node Pragma CPU,Pragma Deadline_Floor,Pragma CPP_Vtable,Implementation Defined Pragmas | |
2838 | @anchor{gnat_rm/implementation_defined_pragmas pragma-cpu}@anchor{4b} | |
2839 | @section Pragma CPU | |
2840 | ||
2841 | ||
2842 | Syntax: | |
2843 | ||
2844 | @example | |
2845 | pragma CPU (EXPRESSION); | |
2846 | @end example | |
2847 | ||
2848 | This pragma is standard in Ada 2012, but is available in all earlier | |
2849 | versions of Ada as an implementation-defined pragma. | |
2850 | See Ada 2012 Reference Manual for details. | |
2851 | ||
6f089469 | 2852 | @node Pragma Deadline_Floor,Pragma Debug,Pragma CPU,Implementation Defined Pragmas |
64d5610f ML |
2853 | @anchor{gnat_rm/implementation_defined_pragmas pragma-deadline-floor}@anchor{4c} |
2854 | @section Pragma Deadline_Floor | |
2855 | ||
2856 | ||
2857 | Syntax: | |
2858 | ||
2859 | @example | |
2860 | pragma Deadline_Floor (time_span_EXPRESSION); | |
2861 | @end example | |
2862 | ||
2863 | This pragma applies only to protected types and specifies the floor | |
2864 | deadline inherited by a task when the task enters a protected object. | |
2865 | It is effective only when the EDF scheduling policy is used. | |
2866 | ||
6f089469 RD |
2867 | @node Pragma Debug,Pragma Debug_Policy,Pragma Deadline_Floor,Implementation Defined Pragmas |
2868 | @anchor{gnat_rm/implementation_defined_pragmas pragma-debug}@anchor{4d} | |
64d5610f ML |
2869 | @section Pragma Debug |
2870 | ||
2871 | ||
2872 | Syntax: | |
2873 | ||
2874 | @example | |
2875 | pragma Debug ([CONDITION, ]PROCEDURE_CALL_WITHOUT_SEMICOLON); | |
2876 | ||
2877 | PROCEDURE_CALL_WITHOUT_SEMICOLON ::= | |
2878 | PROCEDURE_NAME | |
2879 | | PROCEDURE_PREFIX ACTUAL_PARAMETER_PART | |
2880 | @end example | |
2881 | ||
2882 | The procedure call argument has the syntactic form of an expression, meeting | |
2883 | the syntactic requirements for pragmas. | |
2884 | ||
2885 | If debug pragmas are not enabled or if the condition is present and evaluates | |
2886 | to False, this pragma has no effect. If debug pragmas are enabled, the | |
2887 | semantics of the pragma is exactly equivalent to the procedure call statement | |
2888 | corresponding to the argument with a terminating semicolon. Pragmas are | |
2889 | permitted in sequences of declarations, so you can use pragma @code{Debug} to | |
2890 | intersperse calls to debug procedures in the middle of declarations. Debug | |
2891 | pragmas can be enabled either by use of the command line switch `-gnata' | |
2892 | or by use of the pragma @code{Check_Policy} with a first argument of | |
2893 | @code{Debug}. | |
2894 | ||
6f089469 RD |
2895 | @node Pragma Debug_Policy,Pragma Default_Initial_Condition,Pragma Debug,Implementation Defined Pragmas |
2896 | @anchor{gnat_rm/implementation_defined_pragmas pragma-debug-policy}@anchor{4e} | |
64d5610f ML |
2897 | @section Pragma Debug_Policy |
2898 | ||
2899 | ||
2900 | Syntax: | |
2901 | ||
2902 | @example | |
2903 | pragma Debug_Policy (CHECK | DISABLE | IGNORE | ON | OFF); | |
2904 | @end example | |
2905 | ||
2906 | This pragma is equivalent to a corresponding @code{Check_Policy} pragma | |
2907 | with a first argument of @code{Debug}. It is retained for historical | |
2908 | compatibility reasons. | |
2909 | ||
6f089469 RD |
2910 | @node Pragma Default_Initial_Condition,Pragma Default_Scalar_Storage_Order,Pragma Debug_Policy,Implementation Defined Pragmas |
2911 | @anchor{gnat_rm/implementation_defined_pragmas id8}@anchor{4f}@anchor{gnat_rm/implementation_defined_pragmas pragma-default-initial-condition}@anchor{50} | |
2912 | @section Pragma Default_Initial_Condition | |
2913 | ||
2914 | ||
2915 | Syntax: | |
2916 | ||
2917 | @example | |
2918 | pragma Default_Initial_Condition [ (null | boolean_EXPRESSION) ]; | |
2919 | @end example | |
2920 | ||
2921 | For the semantics of this pragma, see the entry for aspect | |
2922 | @code{Default_Initial_Condition} in the SPARK 2014 Reference Manual, section 7.3.3. | |
2923 | ||
2924 | @node Pragma Default_Scalar_Storage_Order,Pragma Default_Storage_Pool,Pragma Default_Initial_Condition,Implementation Defined Pragmas | |
64d5610f ML |
2925 | @anchor{gnat_rm/implementation_defined_pragmas pragma-default-scalar-storage-order}@anchor{51} |
2926 | @section Pragma Default_Scalar_Storage_Order | |
2927 | ||
2928 | ||
2929 | @geindex Default_Scalar_Storage_Order | |
2930 | ||
2931 | @geindex Scalar_Storage_Order | |
2932 | ||
2933 | Syntax: | |
2934 | ||
2935 | @example | |
2936 | pragma Default_Scalar_Storage_Order (High_Order_First | Low_Order_First); | |
2937 | @end example | |
2938 | ||
2939 | Normally if no explicit @code{Scalar_Storage_Order} is given for a record | |
2940 | type or array type, then the scalar storage order defaults to the ordinary | |
2941 | default for the target. But this default may be overridden using this pragma. | |
2942 | The pragma may appear as a configuration pragma, or locally within a package | |
2943 | spec or declarative part. In the latter case, it applies to all subsequent | |
2944 | types declared within that package spec or declarative part. | |
2945 | ||
2946 | The following example shows the use of this pragma: | |
2947 | ||
2948 | @example | |
2949 | pragma Default_Scalar_Storage_Order (High_Order_First); | |
2950 | with System; use System; | |
2951 | package DSSO1 is | |
2952 | type H1 is record | |
2953 | a : Integer; | |
2954 | end record; | |
2955 | ||
2956 | type L2 is record | |
2957 | a : Integer; | |
2958 | end record; | |
2959 | for L2'Scalar_Storage_Order use Low_Order_First; | |
2960 | ||
2961 | type L2a is new L2; | |
2962 | ||
2963 | package Inner is | |
2964 | type H3 is record | |
2965 | a : Integer; | |
2966 | end record; | |
2967 | ||
2968 | pragma Default_Scalar_Storage_Order (Low_Order_First); | |
2969 | ||
2970 | type L4 is record | |
2971 | a : Integer; | |
2972 | end record; | |
2973 | end Inner; | |
2974 | ||
2975 | type H4a is new Inner.L4; | |
2976 | ||
2977 | type H5 is record | |
2978 | a : Integer; | |
2979 | end record; | |
2980 | end DSSO1; | |
2981 | @end example | |
2982 | ||
2983 | In this example record types with names starting with `L' have @cite{Low_Order_First} scalar | |
2984 | storage order, and record types with names starting with `H' have @code{High_Order_First}. | |
2985 | Note that in the case of @code{H4a}, the order is not inherited | |
2986 | from the parent type. Only an explicitly set @code{Scalar_Storage_Order} | |
2987 | gets inherited on type derivation. | |
2988 | ||
2989 | If this pragma is used as a configuration pragma which appears within a | |
2990 | configuration pragma file (as opposed to appearing explicitly at the start | |
2991 | of a single unit), then the binder will require that all units in a partition | |
2992 | be compiled in a similar manner, other than run-time units, which are not | |
2993 | affected by this pragma. Note that the use of this form is discouraged because | |
2994 | it may significantly degrade the run-time performance of the software, instead | |
2995 | the default scalar storage order ought to be changed only on a local basis. | |
2996 | ||
2997 | @node Pragma Default_Storage_Pool,Pragma Depends,Pragma Default_Scalar_Storage_Order,Implementation Defined Pragmas | |
2998 | @anchor{gnat_rm/implementation_defined_pragmas pragma-default-storage-pool}@anchor{52} | |
2999 | @section Pragma Default_Storage_Pool | |
3000 | ||
3001 | ||
3002 | @geindex Default_Storage_Pool | |
3003 | ||
3004 | Syntax: | |
3005 | ||
3006 | @example | |
3007 | pragma Default_Storage_Pool (storage_pool_NAME | null); | |
3008 | @end example | |
3009 | ||
3010 | This pragma is standard in Ada 2012, but is available in all earlier | |
3011 | versions of Ada as an implementation-defined pragma. | |
3012 | See Ada 2012 Reference Manual for details. | |
3013 | ||
3014 | @node Pragma Depends,Pragma Detect_Blocking,Pragma Default_Storage_Pool,Implementation Defined Pragmas | |
3015 | @anchor{gnat_rm/implementation_defined_pragmas id9}@anchor{53}@anchor{gnat_rm/implementation_defined_pragmas pragma-depends}@anchor{54} | |
3016 | @section Pragma Depends | |
3017 | ||
3018 | ||
3019 | Syntax: | |
3020 | ||
3021 | @example | |
3022 | pragma Depends (DEPENDENCY_RELATION); | |
3023 | ||
3024 | DEPENDENCY_RELATION ::= | |
3025 | null | |
3026 | | (DEPENDENCY_CLAUSE @{, DEPENDENCY_CLAUSE@}) | |
3027 | ||
3028 | DEPENDENCY_CLAUSE ::= | |
3029 | OUTPUT_LIST =>[+] INPUT_LIST | |
3030 | | NULL_DEPENDENCY_CLAUSE | |
3031 | ||
3032 | NULL_DEPENDENCY_CLAUSE ::= null => INPUT_LIST | |
3033 | ||
3034 | OUTPUT_LIST ::= OUTPUT | (OUTPUT @{, OUTPUT@}) | |
3035 | ||
3036 | INPUT_LIST ::= null | INPUT | (INPUT @{, INPUT@}) | |
3037 | ||
3038 | OUTPUT ::= NAME | FUNCTION_RESULT | |
3039 | INPUT ::= NAME | |
3040 | ||
3041 | where FUNCTION_RESULT is a function Result attribute_reference | |
3042 | @end example | |
3043 | ||
3044 | For the semantics of this pragma, see the entry for aspect @code{Depends} in the | |
3045 | SPARK 2014 Reference Manual, section 6.1.5. | |
3046 | ||
3047 | @node Pragma Detect_Blocking,Pragma Disable_Atomic_Synchronization,Pragma Depends,Implementation Defined Pragmas | |
3048 | @anchor{gnat_rm/implementation_defined_pragmas pragma-detect-blocking}@anchor{55} | |
3049 | @section Pragma Detect_Blocking | |
3050 | ||
3051 | ||
3052 | Syntax: | |
3053 | ||
3054 | @example | |
3055 | pragma Detect_Blocking; | |
3056 | @end example | |
3057 | ||
3058 | This is a standard pragma in Ada 2005, that is available in all earlier | |
3059 | versions of Ada as an implementation-defined pragma. | |
3060 | ||
3061 | This is a configuration pragma that forces the detection of potentially | |
3062 | blocking operations within a protected operation, and to raise Program_Error | |
3063 | if that happens. | |
3064 | ||
3065 | @node Pragma Disable_Atomic_Synchronization,Pragma Dispatching_Domain,Pragma Detect_Blocking,Implementation Defined Pragmas | |
3066 | @anchor{gnat_rm/implementation_defined_pragmas pragma-disable-atomic-synchronization}@anchor{56} | |
3067 | @section Pragma Disable_Atomic_Synchronization | |
3068 | ||
3069 | ||
3070 | @geindex Atomic Synchronization | |
3071 | ||
3072 | Syntax: | |
3073 | ||
3074 | @example | |
3075 | pragma Disable_Atomic_Synchronization [(Entity)]; | |
3076 | @end example | |
3077 | ||
3078 | Ada requires that accesses (reads or writes) of an atomic variable be | |
3079 | regarded as synchronization points in the case of multiple tasks. | |
3080 | Particularly in the case of multi-processors this may require special | |
3081 | handling, e.g. the generation of memory barriers. This capability may | |
3082 | be turned off using this pragma in cases where it is known not to be | |
3083 | required. | |
3084 | ||
3085 | The placement and scope rules for this pragma are the same as those | |
3086 | for @code{pragma Suppress}. In particular it can be used as a | |
3087 | configuration pragma, or in a declaration sequence where it applies | |
3088 | till the end of the scope. If an @code{Entity} argument is present, | |
3089 | the action applies only to that entity. | |
3090 | ||
3091 | @node Pragma Dispatching_Domain,Pragma Effective_Reads,Pragma Disable_Atomic_Synchronization,Implementation Defined Pragmas | |
3092 | @anchor{gnat_rm/implementation_defined_pragmas pragma-dispatching-domain}@anchor{57} | |
3093 | @section Pragma Dispatching_Domain | |
3094 | ||
3095 | ||
3096 | Syntax: | |
3097 | ||
3098 | @example | |
3099 | pragma Dispatching_Domain (EXPRESSION); | |
3100 | @end example | |
3101 | ||
3102 | This pragma is standard in Ada 2012, but is available in all earlier | |
3103 | versions of Ada as an implementation-defined pragma. | |
3104 | See Ada 2012 Reference Manual for details. | |
3105 | ||
3106 | @node Pragma Effective_Reads,Pragma Effective_Writes,Pragma Dispatching_Domain,Implementation Defined Pragmas | |
3107 | @anchor{gnat_rm/implementation_defined_pragmas id10}@anchor{58}@anchor{gnat_rm/implementation_defined_pragmas pragma-effective-reads}@anchor{59} | |
3108 | @section Pragma Effective_Reads | |
3109 | ||
3110 | ||
3111 | Syntax: | |
3112 | ||
3113 | @example | |
3114 | pragma Effective_Reads [ (static_boolean_EXPRESSION) ]; | |
3115 | @end example | |
3116 | ||
3117 | For the semantics of this pragma, see the entry for aspect @code{Effective_Reads} in | |
3118 | the SPARK 2014 Reference Manual, section 7.1.2. | |
3119 | ||
3120 | @node Pragma Effective_Writes,Pragma Elaboration_Checks,Pragma Effective_Reads,Implementation Defined Pragmas | |
3121 | @anchor{gnat_rm/implementation_defined_pragmas id11}@anchor{5a}@anchor{gnat_rm/implementation_defined_pragmas pragma-effective-writes}@anchor{5b} | |
3122 | @section Pragma Effective_Writes | |
3123 | ||
3124 | ||
3125 | Syntax: | |
3126 | ||
3127 | @example | |
3128 | pragma Effective_Writes [ (static_boolean_EXPRESSION) ]; | |
3129 | @end example | |
3130 | ||
3131 | For the semantics of this pragma, see the entry for aspect @code{Effective_Writes} | |
3132 | in the SPARK 2014 Reference Manual, section 7.1.2. | |
3133 | ||
3134 | @node Pragma Elaboration_Checks,Pragma Eliminate,Pragma Effective_Writes,Implementation Defined Pragmas | |
3135 | @anchor{gnat_rm/implementation_defined_pragmas pragma-elaboration-checks}@anchor{5c} | |
3136 | @section Pragma Elaboration_Checks | |
3137 | ||
3138 | ||
3139 | @geindex Elaboration control | |
3140 | ||
3141 | Syntax: | |
3142 | ||
3143 | @example | |
3144 | pragma Elaboration_Checks (Dynamic | Static); | |
3145 | @end example | |
3146 | ||
3147 | This is a configuration pragma which specifies the elaboration model to be | |
3148 | used during compilation. For more information on the elaboration models of | |
3149 | GNAT, consult the chapter on elaboration order handling in the `GNAT User’s | |
3150 | Guide'. | |
3151 | ||
3152 | The pragma may appear in the following contexts: | |
3153 | ||
3154 | ||
3155 | @itemize * | |
3156 | ||
3157 | @item | |
3158 | Configuration pragmas file | |
3159 | ||
3160 | @item | |
3161 | Prior to the context clauses of a compilation unit’s initial declaration | |
3162 | @end itemize | |
3163 | ||
3164 | Any other placement of the pragma will result in a warning and the effects of | |
3165 | the offending pragma will be ignored. | |
3166 | ||
3167 | If the pragma argument is @code{Dynamic}, then the dynamic elaboration model is in | |
3168 | effect. If the pragma argument is @code{Static}, then the static elaboration model | |
3169 | is in effect. | |
3170 | ||
3171 | @node Pragma Eliminate,Pragma Enable_Atomic_Synchronization,Pragma Elaboration_Checks,Implementation Defined Pragmas | |
3172 | @anchor{gnat_rm/implementation_defined_pragmas pragma-eliminate}@anchor{5d} | |
3173 | @section Pragma Eliminate | |
3174 | ||
3175 | ||
3176 | @geindex Elimination of unused subprograms | |
3177 | ||
3178 | Syntax: | |
3179 | ||
3180 | @example | |
3181 | pragma Eliminate ( | |
3182 | [ Unit_Name => ] IDENTIFIER | SELECTED_COMPONENT , | |
3183 | [ Entity => ] IDENTIFIER | | |
3184 | SELECTED_COMPONENT | | |
3185 | STRING_LITERAL | |
3186 | [, Source_Location => SOURCE_TRACE ] ); | |
3187 | ||
3188 | SOURCE_TRACE ::= STRING_LITERAL | |
3189 | @end example | |
3190 | ||
3191 | This pragma indicates that the given entity is not used in the program to be | |
3192 | compiled and built, thus allowing the compiler to | |
3193 | eliminate the code or data associated with the named entity. Any reference to | |
3194 | an eliminated entity causes a compile-time or link-time error. | |
3195 | ||
3196 | The pragma has the following semantics, where @code{U} is the unit specified by | |
3197 | the @code{Unit_Name} argument and @code{E} is the entity specified by the @code{Entity} | |
3198 | argument: | |
3199 | ||
3200 | ||
3201 | @itemize * | |
3202 | ||
3203 | @item | |
3204 | @code{E} must be a subprogram that is explicitly declared either: | |
3205 | ||
3206 | ||
3207 | @itemize * | |
3208 | ||
3209 | @item | |
3210 | Within @code{U}, or | |
3211 | ||
3212 | @item | |
3213 | Within a generic package that is instantiated in @code{U}, or | |
3214 | ||
3215 | @item | |
3216 | As an instance of generic subprogram instantiated in @code{U}. | |
3217 | @end itemize | |
3218 | ||
3219 | Otherwise the pragma is ignored. | |
3220 | ||
3221 | @item | |
3222 | If @code{E} is overloaded within @code{U} then, in the absence of a | |
3223 | @code{Source_Location} argument, all overloadings are eliminated. | |
3224 | ||
3225 | @item | |
3226 | If @code{E} is overloaded within @code{U} and only some overloadings | |
3227 | are to be eliminated, then each overloading to be eliminated | |
3228 | must be specified in a corresponding pragma @code{Eliminate} | |
3229 | with a @code{Source_Location} argument identifying the line where the | |
3230 | declaration appears, as described below. | |
3231 | ||
3232 | @item | |
3233 | If @code{E} is declared as the result of a generic instantiation, then | |
3234 | a @code{Source_Location} argument is needed, as described below. | |
3235 | @end itemize | |
3236 | ||
3237 | Pragma @code{Eliminate} allows a program to be compiled in a system-independent | |
3238 | manner, so that unused entities are eliminated but without | |
3239 | needing to modify the source text. Normally the required set of | |
3240 | @code{Eliminate} pragmas is constructed automatically using the @code{gnatelim} tool. | |
3241 | ||
3242 | Any source file change that removes, splits, or | |
3243 | adds lines may make the set of @code{Eliminate} pragmas invalid because their | |
3244 | @code{Source_Location} argument values may get out of date. | |
3245 | ||
3246 | Pragma @code{Eliminate} may be used where the referenced entity is a dispatching | |
3247 | operation. In this case all the subprograms to which the given operation can | |
3248 | dispatch are considered to be unused (are never called as a result of a direct | |
3249 | or a dispatching call). | |
3250 | ||
3251 | The string literal given for the source location specifies the line number | |
3252 | of the declaration of the entity, using the following syntax for @code{SOURCE_TRACE}: | |
3253 | ||
3254 | @example | |
3255 | SOURCE_TRACE ::= SOURCE_REFERENCE [ LBRACKET SOURCE_TRACE RBRACKET ] | |
3256 | ||
3257 | LBRACKET ::= '[' | |
3258 | RBRACKET ::= ']' | |
3259 | ||
3260 | SOURCE_REFERENCE ::= FILE_NAME : LINE_NUMBER | |
3261 | ||
3262 | LINE_NUMBER ::= DIGIT @{DIGIT@} | |
3263 | @end example | |
3264 | ||
3265 | Spaces around the colon in a @code{SOURCE_REFERENCE} are optional. | |
3266 | ||
3267 | The source trace that is given as the @code{Source_Location} must obey the | |
3268 | following rules (or else the pragma is ignored), where @code{U} is | |
3269 | the unit @code{U} specified by the @code{Unit_Name} argument and @code{E} is the | |
3270 | subprogram specified by the @code{Entity} argument: | |
3271 | ||
3272 | ||
3273 | @itemize * | |
3274 | ||
3275 | @item | |
3276 | @code{FILE_NAME} is the short name (with no directory | |
3277 | information) of the Ada source file for @code{U}, using the required syntax | |
3278 | for the underlying file system (e.g. case is significant if the underlying | |
3279 | operating system is case sensitive). | |
3280 | If @code{U} is a package and @code{E} is a subprogram declared in the package | |
3281 | specification and its full declaration appears in the package body, | |
3282 | then the relevant source file is the one for the package specification; | |
3283 | analogously if @code{U} is a generic package. | |
3284 | ||
3285 | @item | |
3286 | If @code{E} is not declared in a generic instantiation (this includes | |
3287 | generic subprogram instances), the source trace includes only one source | |
3288 | line reference. @code{LINE_NUMBER} gives the line number of the occurrence | |
3289 | of the declaration of @code{E} within the source file (as a decimal literal | |
3290 | without an exponent or point). | |
3291 | ||
3292 | @item | |
3293 | If @code{E} is declared by a generic instantiation, its source trace | |
3294 | (from left to right) starts with the source location of the | |
3295 | declaration of @code{E} in the generic unit and ends with the source | |
3296 | location of the instantiation, given in square brackets. This approach is | |
3297 | applied recursively with nested instantiations: the rightmost (nested | |
3298 | most deeply in square brackets) element of the source trace is the location | |
3299 | of the outermost instantiation, and the leftmost element (that is, outside | |
3300 | of any square brackets) is the location of the declaration of @code{E} in | |
3301 | the generic unit. | |
3302 | @end itemize | |
3303 | ||
3304 | Examples: | |
3305 | ||
3306 | @quotation | |
3307 | ||
3308 | @example | |
3309 | pragma Eliminate (Pkg0, Proc); | |
3310 | -- Eliminate (all overloadings of) Proc in Pkg0 | |
3311 | ||
3312 | pragma Eliminate (Pkg1, Proc, | |
3313 | Source_Location => "pkg1.ads:8"); | |
3314 | -- Eliminate overloading of Proc at line 8 in pkg1.ads | |
3315 | ||
3316 | -- Assume the following file contents: | |
3317 | -- gen_pkg.ads | |
3318 | -- 1: generic | |
3319 | -- 2: type T is private; | |
3320 | -- 3: package Gen_Pkg is | |
3321 | -- 4: procedure Proc(N : T); | |
3322 | -- ... ... | |
3323 | -- ... end Gen_Pkg; | |
3324 | -- | |
3325 | -- q.adb | |
3326 | -- 1: with Gen_Pkg; | |
3327 | -- 2: procedure Q is | |
3328 | -- 3: package Inst_Pkg is new Gen_Pkg(Integer); | |
3329 | -- ... -- No calls on Inst_Pkg.Proc | |
3330 | -- ... end Q; | |
3331 | ||
3332 | -- The following pragma eliminates Inst_Pkg.Proc from Q | |
3333 | pragma Eliminate (Q, Proc, | |
3334 | Source_Location => "gen_pkg.ads:4[q.adb:3]"); | |
3335 | @end example | |
3336 | @end quotation | |
3337 | ||
3338 | @node Pragma Enable_Atomic_Synchronization,Pragma Export_Function,Pragma Eliminate,Implementation Defined Pragmas | |
3339 | @anchor{gnat_rm/implementation_defined_pragmas pragma-enable-atomic-synchronization}@anchor{5e} | |
3340 | @section Pragma Enable_Atomic_Synchronization | |
3341 | ||
3342 | ||
3343 | @geindex Atomic Synchronization | |
3344 | ||
3345 | Syntax: | |
3346 | ||
3347 | @example | |
3348 | pragma Enable_Atomic_Synchronization [(Entity)]; | |
3349 | @end example | |
3350 | ||
3351 | Ada requires that accesses (reads or writes) of an atomic variable be | |
3352 | regarded as synchronization points in the case of multiple tasks. | |
3353 | Particularly in the case of multi-processors this may require special | |
3354 | handling, e.g. the generation of memory barriers. This synchronization | |
3355 | is performed by default, but can be turned off using | |
3356 | @code{pragma Disable_Atomic_Synchronization}. The | |
3357 | @code{Enable_Atomic_Synchronization} pragma can be used to turn | |
3358 | it back on. | |
3359 | ||
3360 | The placement and scope rules for this pragma are the same as those | |
3361 | for @code{pragma Unsuppress}. In particular it can be used as a | |
3362 | configuration pragma, or in a declaration sequence where it applies | |
3363 | till the end of the scope. If an @code{Entity} argument is present, | |
3364 | the action applies only to that entity. | |
3365 | ||
3366 | @node Pragma Export_Function,Pragma Export_Object,Pragma Enable_Atomic_Synchronization,Implementation Defined Pragmas | |
3367 | @anchor{gnat_rm/implementation_defined_pragmas pragma-export-function}@anchor{5f} | |
3368 | @section Pragma Export_Function | |
3369 | ||
3370 | ||
3371 | @geindex Argument passing mechanisms | |
3372 | ||
3373 | Syntax: | |
3374 | ||
3375 | @example | |
3376 | pragma Export_Function ( | |
3377 | [Internal =>] LOCAL_NAME | |
3378 | [, [External =>] EXTERNAL_SYMBOL] | |
3379 | [, [Parameter_Types =>] PARAMETER_TYPES] | |
3380 | [, [Result_Type =>] result_SUBTYPE_MARK] | |
3381 | [, [Mechanism =>] MECHANISM] | |
3382 | [, [Result_Mechanism =>] MECHANISM_NAME]); | |
3383 | ||
3384 | EXTERNAL_SYMBOL ::= | |
3385 | IDENTIFIER | |
3386 | | static_string_EXPRESSION | |
3387 | | "" | |
3388 | ||
3389 | PARAMETER_TYPES ::= | |
3390 | null | |
3391 | | TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} | |
3392 | ||
3393 | TYPE_DESIGNATOR ::= | |
3394 | subtype_NAME | |
3395 | | subtype_Name ' Access | |
3396 | ||
3397 | MECHANISM ::= | |
3398 | MECHANISM_NAME | |
3399 | | (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) | |
3400 | ||
3401 | MECHANISM_ASSOCIATION ::= | |
3402 | [formal_parameter_NAME =>] MECHANISM_NAME | |
3403 | ||
3404 | MECHANISM_NAME ::= Value | Reference | |
3405 | @end example | |
3406 | ||
3407 | Use this pragma to make a function externally callable and optionally | |
3408 | provide information on mechanisms to be used for passing parameter and | |
3409 | result values. We recommend, for the purposes of improving portability, | |
3410 | this pragma always be used in conjunction with a separate pragma | |
3411 | @code{Export}, which must precede the pragma @code{Export_Function}. | |
3412 | GNAT does not require a separate pragma @code{Export}, but if none is | |
3413 | present, @code{Convention Ada} is assumed, which is usually | |
3414 | not what is wanted, so it is usually appropriate to use this | |
3415 | pragma in conjunction with a @code{Export} or @code{Convention} | |
3416 | pragma that specifies the desired foreign convention. | |
3417 | Pragma @code{Export_Function} | |
3418 | (and @code{Export}, if present) must appear in the same declarative | |
3419 | region as the function to which they apply. | |
3420 | ||
3421 | The @code{internal_name} must uniquely designate the function to which the | |
3422 | pragma applies. If more than one function name exists of this name in | |
3423 | the declarative part you must use the @code{Parameter_Types} and | |
3424 | @code{Result_Type} parameters to achieve the required | |
3425 | unique designation. The @cite{subtype_mark}s in these parameters must | |
3426 | exactly match the subtypes in the corresponding function specification, | |
3427 | using positional notation to match parameters with subtype marks. | |
3428 | The form with an @code{'Access} attribute can be used to match an | |
3429 | anonymous access parameter. | |
3430 | ||
3431 | @geindex Suppressing external name | |
3432 | ||
3433 | Special treatment is given if the EXTERNAL is an explicit null | |
3434 | string or a static string expressions that evaluates to the null | |
3435 | string. In this case, no external name is generated. This form | |
3436 | still allows the specification of parameter mechanisms. | |
3437 | ||
3438 | @node Pragma Export_Object,Pragma Export_Procedure,Pragma Export_Function,Implementation Defined Pragmas | |
3439 | @anchor{gnat_rm/implementation_defined_pragmas pragma-export-object}@anchor{60} | |
3440 | @section Pragma Export_Object | |
3441 | ||
3442 | ||
3443 | Syntax: | |
3444 | ||
3445 | @example | |
3446 | pragma Export_Object ( | |
3447 | [Internal =>] LOCAL_NAME | |
3448 | [, [External =>] EXTERNAL_SYMBOL] | |
3449 | [, [Size =>] EXTERNAL_SYMBOL]); | |
3450 | ||
3451 | EXTERNAL_SYMBOL ::= | |
3452 | IDENTIFIER | |
3453 | | static_string_EXPRESSION | |
3454 | @end example | |
3455 | ||
3456 | This pragma designates an object as exported, and apart from the | |
3457 | extended rules for external symbols, is identical in effect to the use of | |
3458 | the normal @code{Export} pragma applied to an object. You may use a | |
3459 | separate Export pragma (and you probably should from the point of view | |
3460 | of portability), but it is not required. @code{Size} is syntax checked, | |
3461 | but otherwise ignored by GNAT. | |
3462 | ||
3463 | @node Pragma Export_Procedure,Pragma Export_Valued_Procedure,Pragma Export_Object,Implementation Defined Pragmas | |
3464 | @anchor{gnat_rm/implementation_defined_pragmas pragma-export-procedure}@anchor{61} | |
3465 | @section Pragma Export_Procedure | |
3466 | ||
3467 | ||
3468 | Syntax: | |
3469 | ||
3470 | @example | |
3471 | pragma Export_Procedure ( | |
3472 | [Internal =>] LOCAL_NAME | |
3473 | [, [External =>] EXTERNAL_SYMBOL] | |
3474 | [, [Parameter_Types =>] PARAMETER_TYPES] | |
3475 | [, [Mechanism =>] MECHANISM]); | |
3476 | ||
3477 | EXTERNAL_SYMBOL ::= | |
3478 | IDENTIFIER | |
3479 | | static_string_EXPRESSION | |
3480 | | "" | |
3481 | ||
3482 | PARAMETER_TYPES ::= | |
3483 | null | |
3484 | | TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} | |
3485 | ||
3486 | TYPE_DESIGNATOR ::= | |
3487 | subtype_NAME | |
3488 | | subtype_Name ' Access | |
3489 | ||
3490 | MECHANISM ::= | |
3491 | MECHANISM_NAME | |
3492 | | (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) | |
3493 | ||
3494 | MECHANISM_ASSOCIATION ::= | |
3495 | [formal_parameter_NAME =>] MECHANISM_NAME | |
3496 | ||
3497 | MECHANISM_NAME ::= Value | Reference | |
3498 | @end example | |
3499 | ||
3500 | This pragma is identical to @code{Export_Function} except that it | |
3501 | applies to a procedure rather than a function and the parameters | |
3502 | @code{Result_Type} and @code{Result_Mechanism} are not permitted. | |
3503 | GNAT does not require a separate pragma @code{Export}, but if none is | |
3504 | present, @code{Convention Ada} is assumed, which is usually | |
3505 | not what is wanted, so it is usually appropriate to use this | |
3506 | pragma in conjunction with a @code{Export} or @code{Convention} | |
3507 | pragma that specifies the desired foreign convention. | |
3508 | ||
3509 | @geindex Suppressing external name | |
3510 | ||
3511 | Special treatment is given if the EXTERNAL is an explicit null | |
3512 | string or a static string expressions that evaluates to the null | |
3513 | string. In this case, no external name is generated. This form | |
3514 | still allows the specification of parameter mechanisms. | |
3515 | ||
3516 | @node Pragma Export_Valued_Procedure,Pragma Extend_System,Pragma Export_Procedure,Implementation Defined Pragmas | |
3517 | @anchor{gnat_rm/implementation_defined_pragmas pragma-export-valued-procedure}@anchor{62} | |
3518 | @section Pragma Export_Valued_Procedure | |
3519 | ||
3520 | ||
3521 | Syntax: | |
3522 | ||
3523 | @example | |
3524 | pragma Export_Valued_Procedure ( | |
3525 | [Internal =>] LOCAL_NAME | |
3526 | [, [External =>] EXTERNAL_SYMBOL] | |
3527 | [, [Parameter_Types =>] PARAMETER_TYPES] | |
3528 | [, [Mechanism =>] MECHANISM]); | |
3529 | ||
3530 | EXTERNAL_SYMBOL ::= | |
3531 | IDENTIFIER | |
3532 | | static_string_EXPRESSION | |
3533 | | "" | |
3534 | ||
3535 | PARAMETER_TYPES ::= | |
3536 | null | |
3537 | | TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} | |
3538 | ||
3539 | TYPE_DESIGNATOR ::= | |
3540 | subtype_NAME | |
3541 | | subtype_Name ' Access | |
3542 | ||
3543 | MECHANISM ::= | |
3544 | MECHANISM_NAME | |
3545 | | (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) | |
3546 | ||
3547 | MECHANISM_ASSOCIATION ::= | |
3548 | [formal_parameter_NAME =>] MECHANISM_NAME | |
3549 | ||
3550 | MECHANISM_NAME ::= Value | Reference | |
3551 | @end example | |
3552 | ||
3553 | This pragma is identical to @code{Export_Procedure} except that the | |
3554 | first parameter of @code{LOCAL_NAME}, which must be present, must be of | |
3555 | mode @code{out}, and externally the subprogram is treated as a function | |
3556 | with this parameter as the result of the function. GNAT provides for | |
3557 | this capability to allow the use of @code{out} and @code{in out} | |
3558 | parameters in interfacing to external functions (which are not permitted | |
3559 | in Ada functions). | |
3560 | GNAT does not require a separate pragma @code{Export}, but if none is | |
3561 | present, @code{Convention Ada} is assumed, which is almost certainly | |
3562 | not what is wanted since the whole point of this pragma is to interface | |
3563 | with foreign language functions, so it is usually appropriate to use this | |
3564 | pragma in conjunction with a @code{Export} or @code{Convention} | |
3565 | pragma that specifies the desired foreign convention. | |
3566 | ||
3567 | @geindex Suppressing external name | |
3568 | ||
3569 | Special treatment is given if the EXTERNAL is an explicit null | |
3570 | string or a static string expressions that evaluates to the null | |
3571 | string. In this case, no external name is generated. This form | |
3572 | still allows the specification of parameter mechanisms. | |
3573 | ||
3574 | @node Pragma Extend_System,Pragma Extensions_Allowed,Pragma Export_Valued_Procedure,Implementation Defined Pragmas | |
3575 | @anchor{gnat_rm/implementation_defined_pragmas pragma-extend-system}@anchor{63} | |
3576 | @section Pragma Extend_System | |
3577 | ||
3578 | ||
3579 | @geindex System | |
3580 | @geindex extending | |
3581 | ||
3582 | @geindex DEC Ada 83 | |
3583 | ||
3584 | Syntax: | |
3585 | ||
3586 | @example | |
3587 | pragma Extend_System ([Name =>] IDENTIFIER); | |
3588 | @end example | |
3589 | ||
3590 | This pragma is used to provide backwards compatibility with other | |
3591 | implementations that extend the facilities of package @code{System}. In | |
3592 | GNAT, @code{System} contains only the definitions that are present in | |
3593 | the Ada RM. However, other implementations, notably the DEC Ada 83 | |
3594 | implementation, provide many extensions to package @code{System}. | |
3595 | ||
3596 | For each such implementation accommodated by this pragma, GNAT provides a | |
3597 | package @code{Aux_@var{xxx}}, e.g., @code{Aux_DEC} for the DEC Ada 83 | |
3598 | implementation, which provides the required additional definitions. You | |
3599 | can use this package in two ways. You can @code{with} it in the normal | |
3600 | way and access entities either by selection or using a @code{use} | |
3601 | clause. In this case no special processing is required. | |
3602 | ||
3603 | However, if existing code contains references such as | |
3604 | @code{System.@var{xxx}} where `xxx' is an entity in the extended | |
3605 | definitions provided in package @code{System}, you may use this pragma | |
3606 | to extend visibility in @code{System} in a non-standard way that | |
3607 | provides greater compatibility with the existing code. Pragma | |
3608 | @code{Extend_System} is a configuration pragma whose single argument is | |
3609 | the name of the package containing the extended definition | |
3610 | (e.g., @code{Aux_DEC} for the DEC Ada case). A unit compiled under | |
3611 | control of this pragma will be processed using special visibility | |
3612 | processing that looks in package @code{System.Aux_@var{xxx}} where | |
3613 | @code{Aux_@var{xxx}} is the pragma argument for any entity referenced in | |
3614 | package @code{System}, but not found in package @code{System}. | |
3615 | ||
3616 | You can use this pragma either to access a predefined @code{System} | |
3617 | extension supplied with the compiler, for example @code{Aux_DEC} or | |
3618 | you can construct your own extension unit following the above | |
3619 | definition. Note that such a package is a child of @code{System} | |
3620 | and thus is considered part of the implementation. | |
3621 | To compile it you will have to use the `-gnatg' switch | |
3622 | for compiling System units, as explained in the | |
3623 | GNAT User’s Guide. | |
3624 | ||
3625 | @node Pragma Extensions_Allowed,Pragma Extensions_Visible,Pragma Extend_System,Implementation Defined Pragmas | |
b71d4b62 | 3626 | @anchor{gnat_rm/implementation_defined_pragmas id12}@anchor{64}@anchor{gnat_rm/implementation_defined_pragmas pragma-extensions-allowed}@anchor{65} |
64d5610f ML |
3627 | @section Pragma Extensions_Allowed |
3628 | ||
3629 | ||
3630 | @geindex Ada Extensions | |
3631 | ||
3632 | @geindex GNAT Extensions | |
3633 | ||
3634 | Syntax: | |
3635 | ||
3636 | @example | |
3637 | pragma Extensions_Allowed (On | Off | All); | |
3638 | @end example | |
3639 | ||
3640 | This configuration pragma enables (via the “On” or “All” argument) or disables | |
3641 | (via the “Off” argument) the implementation extension mode; the pragma takes | |
b71d4b62 | 3642 | precedence over the @code{-gnatX} and @code{-gnatX0} command switches. |
64d5610f | 3643 | |
b71d4b62 RA |
3644 | If an argument of @code{"On"} is specified, the latest version of the Ada language |
3645 | is implemented (currently Ada 2022) and, in addition, a curated set of GNAT | |
3646 | specific extensions are recognized. (See the list here | |
3647 | @ref{66,,here}) | |
64d5610f | 3648 | |
b71d4b62 RA |
3649 | An argument of @code{"All"} has the same effect except that some extra |
3650 | experimental extensions are enabled (See the list here | |
3651 | @ref{67,,here}) | |
64d5610f | 3652 | |
b71d4b62 RA |
3653 | @node Pragma Extensions_Visible,Pragma External,Pragma Extensions_Allowed,Implementation Defined Pragmas |
3654 | @anchor{gnat_rm/implementation_defined_pragmas id13}@anchor{68}@anchor{gnat_rm/implementation_defined_pragmas pragma-extensions-visible}@anchor{69} | |
3655 | @section Pragma Extensions_Visible | |
64d5610f | 3656 | |
64d5610f | 3657 | |
b71d4b62 | 3658 | Syntax: |
64d5610f | 3659 | |
b71d4b62 RA |
3660 | @example |
3661 | pragma Extensions_Visible [ (static_boolean_EXPRESSION) ]; | |
3662 | @end example | |
64d5610f | 3663 | |
b71d4b62 RA |
3664 | For the semantics of this pragma, see the entry for aspect @code{Extensions_Visible} |
3665 | in the SPARK 2014 Reference Manual, section 6.1.7. | |
64d5610f | 3666 | |
b71d4b62 RA |
3667 | @node Pragma External,Pragma External_Name_Casing,Pragma Extensions_Visible,Implementation Defined Pragmas |
3668 | @anchor{gnat_rm/implementation_defined_pragmas pragma-external}@anchor{6a} | |
3669 | @section Pragma External | |
64d5610f | 3670 | |
64d5610f | 3671 | |
b71d4b62 | 3672 | Syntax: |
64d5610f ML |
3673 | |
3674 | @example | |
b71d4b62 RA |
3675 | pragma External ( |
3676 | [ Convention =>] convention_IDENTIFIER, | |
3677 | [ Entity =>] LOCAL_NAME | |
3678 | [, [External_Name =>] static_string_EXPRESSION ] | |
3679 | [, [Link_Name =>] static_string_EXPRESSION ]); | |
64d5610f ML |
3680 | @end example |
3681 | ||
b71d4b62 RA |
3682 | This pragma is identical in syntax and semantics to pragma |
3683 | @code{Export} as defined in the Ada Reference Manual. It is | |
3684 | provided for compatibility with some Ada 83 compilers that | |
3685 | used this pragma for exactly the same purposes as pragma | |
3686 | @code{Export} before the latter was standardized. | |
64d5610f | 3687 | |
b71d4b62 RA |
3688 | @node Pragma External_Name_Casing,Pragma Fast_Math,Pragma External,Implementation Defined Pragmas |
3689 | @anchor{gnat_rm/implementation_defined_pragmas pragma-external-name-casing}@anchor{6b} | |
3690 | @section Pragma External_Name_Casing | |
64d5610f | 3691 | |
64d5610f | 3692 | |
b71d4b62 | 3693 | @geindex Dec Ada 83 casing compatibility |
64d5610f | 3694 | |
b71d4b62 RA |
3695 | @geindex External Names |
3696 | @geindex casing | |
64d5610f | 3697 | |
b71d4b62 | 3698 | @geindex Casing of External names |
64d5610f | 3699 | |
b71d4b62 | 3700 | Syntax: |
64d5610f | 3701 | |
b71d4b62 RA |
3702 | @example |
3703 | pragma External_Name_Casing ( | |
3704 | Uppercase | Lowercase | |
3705 | [, Uppercase | Lowercase | As_Is]); | |
3706 | @end example | |
64d5610f | 3707 | |
b71d4b62 RA |
3708 | This pragma provides control over the casing of external names associated |
3709 | with Import and Export pragmas. There are two cases to consider: | |
64d5610f | 3710 | |
64d5610f | 3711 | |
b71d4b62 | 3712 | @itemize * |
64d5610f ML |
3713 | |
3714 | @item | |
b71d4b62 | 3715 | Implicit external names |
64d5610f | 3716 | |
b71d4b62 RA |
3717 | Implicit external names are derived from identifiers. The most common case |
3718 | arises when a standard Ada Import or Export pragma is used with only two | |
3719 | arguments, as in: | |
64d5610f ML |
3720 | |
3721 | @example | |
b71d4b62 | 3722 | pragma Import (C, C_Routine); |
64d5610f ML |
3723 | @end example |
3724 | ||
b71d4b62 RA |
3725 | Since Ada is a case-insensitive language, the spelling of the identifier in |
3726 | the Ada source program does not provide any information on the desired | |
3727 | casing of the external name, and so a convention is needed. In GNAT the | |
3728 | default treatment is that such names are converted to all lower case | |
3729 | letters. This corresponds to the normal C style in many environments. | |
3730 | The first argument of pragma @code{External_Name_Casing} can be used to | |
3731 | control this treatment. If @code{Uppercase} is specified, then the name | |
3732 | will be forced to all uppercase letters. If @code{Lowercase} is specified, | |
3733 | then the normal default of all lower case letters will be used. | |
64d5610f | 3734 | |
b71d4b62 RA |
3735 | This same implicit treatment is also used in the case of extended DEC Ada 83 |
3736 | compatible Import and Export pragmas where an external name is explicitly | |
3737 | specified using an identifier rather than a string. | |
64d5610f ML |
3738 | |
3739 | @item | |
b71d4b62 | 3740 | Explicit external names |
64d5610f | 3741 | |
b71d4b62 RA |
3742 | Explicit external names are given as string literals. The most common case |
3743 | arises when a standard Ada Import or Export pragma is used with three | |
3744 | arguments, as in: | |
64d5610f ML |
3745 | |
3746 | @example | |
b71d4b62 | 3747 | pragma Import (C, C_Routine, "C_routine"); |
64d5610f ML |
3748 | @end example |
3749 | ||
b71d4b62 RA |
3750 | In this case, the string literal normally provides the exact casing required |
3751 | for the external name. The second argument of pragma | |
3752 | @code{External_Name_Casing} may be used to modify this behavior. | |
3753 | If @code{Uppercase} is specified, then the name | |
3754 | will be forced to all uppercase letters. If @code{Lowercase} is specified, | |
3755 | then the name will be forced to all lowercase letters. A specification of | |
3756 | @code{As_Is} provides the normal default behavior in which the casing is | |
3757 | taken from the string provided. | |
3758 | @end itemize | |
64d5610f | 3759 | |
b71d4b62 RA |
3760 | This pragma may appear anywhere that a pragma is valid. In particular, it |
3761 | can be used as a configuration pragma in the @code{gnat.adc} file, in which | |
3762 | case it applies to all subsequent compilations, or it can be used as a program | |
3763 | unit pragma, in which case it only applies to the current unit, or it can | |
3764 | be used more locally to control individual Import/Export pragmas. | |
64d5610f | 3765 | |
b71d4b62 RA |
3766 | It was primarily intended for use with OpenVMS systems, where many |
3767 | compilers convert all symbols to upper case by default. For interfacing to | |
3768 | such compilers (e.g., the DEC C compiler), it may be convenient to use | |
3769 | the pragma: | |
64d5610f ML |
3770 | |
3771 | @example | |
b71d4b62 | 3772 | pragma External_Name_Casing (Uppercase, Uppercase); |
64d5610f | 3773 | @end example |
64d5610f | 3774 | |
b71d4b62 | 3775 | to enforce the upper casing of all external symbols. |
64d5610f | 3776 | |
b71d4b62 RA |
3777 | @node Pragma Fast_Math,Pragma Favor_Top_Level,Pragma External_Name_Casing,Implementation Defined Pragmas |
3778 | @anchor{gnat_rm/implementation_defined_pragmas pragma-fast-math}@anchor{6c} | |
3779 | @section Pragma Fast_Math | |
64d5610f | 3780 | |
64d5610f | 3781 | |
b71d4b62 | 3782 | Syntax: |
64d5610f | 3783 | |
b71d4b62 RA |
3784 | @example |
3785 | pragma Fast_Math; | |
3786 | @end example | |
64d5610f | 3787 | |
b71d4b62 RA |
3788 | This is a configuration pragma which activates a mode in which speed is |
3789 | considered more important for floating-point operations than absolutely | |
3790 | accurate adherence to the requirements of the standard. Currently the | |
3791 | following operations are affected: | |
64d5610f | 3792 | |
64d5610f | 3793 | |
b71d4b62 | 3794 | @table @asis |
64d5610f | 3795 | |
b71d4b62 | 3796 | @item `Complex Multiplication' |
64d5610f | 3797 | |
b71d4b62 RA |
3798 | The normal simple formula for complex multiplication can result in intermediate |
3799 | overflows for numbers near the end of the range. The Ada standard requires that | |
3800 | this situation be detected and corrected by scaling, but in Fast_Math mode such | |
3801 | cases will simply result in overflow. Note that to take advantage of this you | |
3802 | must instantiate your own version of @code{Ada.Numerics.Generic_Complex_Types} | |
3803 | under control of the pragma, rather than use the preinstantiated versions. | |
3804 | @end table | |
64d5610f | 3805 | |
b71d4b62 RA |
3806 | @node Pragma Favor_Top_Level,Pragma Finalize_Storage_Only,Pragma Fast_Math,Implementation Defined Pragmas |
3807 | @anchor{gnat_rm/implementation_defined_pragmas id14}@anchor{6d}@anchor{gnat_rm/implementation_defined_pragmas pragma-favor-top-level}@anchor{6e} | |
3808 | @section Pragma Favor_Top_Level | |
64d5610f | 3809 | |
64d5610f | 3810 | |
b71d4b62 | 3811 | Syntax: |
64d5610f | 3812 | |
b71d4b62 RA |
3813 | @example |
3814 | pragma Favor_Top_Level (type_NAME); | |
64d5610f | 3815 | @end example |
b7d26cb1 | 3816 | |
b71d4b62 RA |
3817 | The argument of pragma @code{Favor_Top_Level} must be a named access-to-subprogram |
3818 | type. This pragma is an efficiency hint to the compiler, regarding the use of | |
3819 | @code{'Access} or @code{'Unrestricted_Access} on nested (non-library-level) subprograms. | |
3820 | The pragma means that nested subprograms are not used with this type, or are | |
3821 | rare, so that the generated code should be efficient in the top-level case. | |
3822 | When this pragma is used, dynamically generated trampolines may be used on some | |
3823 | targets for nested subprograms. See restriction @code{No_Implicit_Dynamic_Code}. | |
b7d26cb1 | 3824 | |
b71d4b62 RA |
3825 | @node Pragma Finalize_Storage_Only,Pragma Float_Representation,Pragma Favor_Top_Level,Implementation Defined Pragmas |
3826 | @anchor{gnat_rm/implementation_defined_pragmas pragma-finalize-storage-only}@anchor{6f} | |
3827 | @section Pragma Finalize_Storage_Only | |
b7d26cb1 | 3828 | |
b7d26cb1 | 3829 | |
b71d4b62 | 3830 | Syntax: |
b7d26cb1 JM |
3831 | |
3832 | @example | |
b71d4b62 | 3833 | pragma Finalize_Storage_Only (first_subtype_LOCAL_NAME); |
b7d26cb1 JM |
3834 | @end example |
3835 | ||
b71d4b62 RA |
3836 | The argument of pragma @code{Finalize_Storage_Only} must denote a local type which |
3837 | is derived from @code{Ada.Finalization.Controlled} or @code{Limited_Controlled}. The | |
3838 | pragma suppresses the call to @code{Finalize} for declared library-level objects | |
3839 | of the argument type. This is mostly useful for types where finalization is | |
3840 | only used to deal with storage reclamation since in most environments it is | |
3841 | not necessary to reclaim memory just before terminating execution, hence the | |
3842 | name. Note that this pragma does not suppress Finalize calls for library-level | |
3843 | heap-allocated objects (see pragma @code{No_Heap_Finalization}). | |
b7d26cb1 | 3844 | |
b71d4b62 RA |
3845 | @node Pragma Float_Representation,Pragma Ghost,Pragma Finalize_Storage_Only,Implementation Defined Pragmas |
3846 | @anchor{gnat_rm/implementation_defined_pragmas pragma-float-representation}@anchor{70} | |
3847 | @section Pragma Float_Representation | |
b7d26cb1 | 3848 | |
b7d26cb1 | 3849 | |
b71d4b62 | 3850 | Syntax: |
b7d26cb1 | 3851 | |
b71d4b62 RA |
3852 | @example |
3853 | pragma Float_Representation (FLOAT_REP[, float_type_LOCAL_NAME]); | |
b7d26cb1 | 3854 | |
b71d4b62 RA |
3855 | FLOAT_REP ::= VAX_Float | IEEE_Float |
3856 | @end example | |
b7d26cb1 | 3857 | |
b71d4b62 RA |
3858 | In the one argument form, this pragma is a configuration pragma which |
3859 | allows control over the internal representation chosen for the predefined | |
3860 | floating point types declared in the packages @code{Standard} and | |
3861 | @code{System}. This pragma is only provided for compatibility and has no effect. | |
b7d26cb1 | 3862 | |
b71d4b62 RA |
3863 | The two argument form specifies the representation to be used for |
3864 | the specified floating-point type. The argument must | |
3865 | be @code{IEEE_Float} to specify the use of IEEE format, as follows: | |
b7d26cb1 | 3866 | |
b7d26cb1 | 3867 | |
b71d4b62 | 3868 | @itemize * |
b7d26cb1 | 3869 | |
b71d4b62 RA |
3870 | @item |
3871 | For a digits value of 6, 32-bit IEEE short format will be used. | |
b7d26cb1 | 3872 | |
b71d4b62 RA |
3873 | @item |
3874 | For a digits value of 15, 64-bit IEEE long format will be used. | |
b7d26cb1 | 3875 | |
b71d4b62 RA |
3876 | @item |
3877 | No other value of digits is permitted. | |
3878 | @end itemize | |
b7d26cb1 | 3879 | |
b71d4b62 RA |
3880 | @node Pragma Ghost,Pragma Global,Pragma Float_Representation,Implementation Defined Pragmas |
3881 | @anchor{gnat_rm/implementation_defined_pragmas id15}@anchor{71}@anchor{gnat_rm/implementation_defined_pragmas pragma-ghost}@anchor{72} | |
3882 | @section Pragma Ghost | |
b7d26cb1 | 3883 | |
b7d26cb1 | 3884 | |
b71d4b62 | 3885 | Syntax: |
b7d26cb1 | 3886 | |
b71d4b62 RA |
3887 | @example |
3888 | pragma Ghost [ (static_boolean_EXPRESSION) ]; | |
3889 | @end example | |
b7d26cb1 | 3890 | |
b71d4b62 RA |
3891 | For the semantics of this pragma, see the entry for aspect @code{Ghost} in the SPARK |
3892 | 2014 Reference Manual, section 6.9. | |
b7d26cb1 | 3893 | |
b71d4b62 RA |
3894 | @node Pragma Global,Pragma Ident,Pragma Ghost,Implementation Defined Pragmas |
3895 | @anchor{gnat_rm/implementation_defined_pragmas id16}@anchor{73}@anchor{gnat_rm/implementation_defined_pragmas pragma-global}@anchor{74} | |
3896 | @section Pragma Global | |
b7d26cb1 | 3897 | |
b7d26cb1 | 3898 | |
b71d4b62 | 3899 | Syntax: |
b7d26cb1 | 3900 | |
b71d4b62 RA |
3901 | @example |
3902 | pragma Global (GLOBAL_SPECIFICATION); | |
b7d26cb1 | 3903 | |
b71d4b62 RA |
3904 | GLOBAL_SPECIFICATION ::= |
3905 | null | |
3906 | | (GLOBAL_LIST) | |
3907 | | (MODED_GLOBAL_LIST @{, MODED_GLOBAL_LIST@}) | |
b7d26cb1 | 3908 | |
b71d4b62 | 3909 | MODED_GLOBAL_LIST ::= MODE_SELECTOR => GLOBAL_LIST |
b7d26cb1 | 3910 | |
b71d4b62 RA |
3911 | MODE_SELECTOR ::= In_Out | Input | Output | Proof_In |
3912 | GLOBAL_LIST ::= GLOBAL_ITEM | (GLOBAL_ITEM @{, GLOBAL_ITEM@}) | |
3913 | GLOBAL_ITEM ::= NAME | |
3914 | @end example | |
b7d26cb1 | 3915 | |
b71d4b62 RA |
3916 | For the semantics of this pragma, see the entry for aspect @code{Global} in the |
3917 | SPARK 2014 Reference Manual, section 6.1.4. | |
b7d26cb1 | 3918 | |
b71d4b62 RA |
3919 | @node Pragma Ident,Pragma Ignore_Pragma,Pragma Global,Implementation Defined Pragmas |
3920 | @anchor{gnat_rm/implementation_defined_pragmas pragma-ident}@anchor{75} | |
3921 | @section Pragma Ident | |
b7d26cb1 | 3922 | |
b7d26cb1 | 3923 | |
b71d4b62 | 3924 | Syntax: |
b7d26cb1 | 3925 | |
b71d4b62 RA |
3926 | @example |
3927 | pragma Ident (static_string_EXPRESSION); | |
3928 | @end example | |
b7d26cb1 | 3929 | |
b71d4b62 RA |
3930 | This pragma is identical in effect to pragma @code{Comment}. It is provided |
3931 | for compatibility with other Ada compilers providing this pragma. | |
b7d26cb1 | 3932 | |
b71d4b62 RA |
3933 | @node Pragma Ignore_Pragma,Pragma Implementation_Defined,Pragma Ident,Implementation Defined Pragmas |
3934 | @anchor{gnat_rm/implementation_defined_pragmas pragma-ignore-pragma}@anchor{76} | |
3935 | @section Pragma Ignore_Pragma | |
b7d26cb1 | 3936 | |
b7d26cb1 | 3937 | |
b71d4b62 | 3938 | Syntax: |
b7d26cb1 | 3939 | |
b71d4b62 RA |
3940 | @example |
3941 | pragma Ignore_Pragma (pragma_IDENTIFIER); | |
3942 | @end example | |
b7d26cb1 | 3943 | |
b71d4b62 RA |
3944 | This is a configuration pragma |
3945 | that takes a single argument that is a simple identifier. Any subsequent | |
3946 | use of a pragma whose pragma identifier matches this argument will be | |
3947 | silently ignored. This may be useful when legacy code or code intended | |
3948 | for compilation with some other compiler contains pragmas that match the | |
3949 | name, but not the exact implementation, of a GNAT pragma. The use of this | |
3950 | pragma allows such pragmas to be ignored, which may be useful in CodePeer | |
3951 | mode, or during porting of legacy code. | |
b7d26cb1 | 3952 | |
b71d4b62 RA |
3953 | @node Pragma Implementation_Defined,Pragma Implemented,Pragma Ignore_Pragma,Implementation Defined Pragmas |
3954 | @anchor{gnat_rm/implementation_defined_pragmas pragma-implementation-defined}@anchor{77} | |
3955 | @section Pragma Implementation_Defined | |
b7d26cb1 | 3956 | |
b7d26cb1 | 3957 | |
b71d4b62 | 3958 | Syntax: |
b7d26cb1 | 3959 | |
b71d4b62 RA |
3960 | @example |
3961 | pragma Implementation_Defined (local_NAME); | |
3962 | @end example | |
b7d26cb1 | 3963 | |
b71d4b62 RA |
3964 | This pragma marks a previously declared entity as implementation-defined. |
3965 | For an overloaded entity, applies to the most recent homonym. | |
b7d26cb1 | 3966 | |
b71d4b62 RA |
3967 | @example |
3968 | pragma Implementation_Defined; | |
3969 | @end example | |
b7d26cb1 | 3970 | |
b71d4b62 RA |
3971 | The form with no arguments appears anywhere within a scope, most |
3972 | typically a package spec, and indicates that all entities that are | |
3973 | defined within the package spec are Implementation_Defined. | |
b7d26cb1 | 3974 | |
b71d4b62 RA |
3975 | This pragma is used within the GNAT runtime library to identify |
3976 | implementation-defined entities introduced in language-defined units, | |
3977 | for the purpose of implementing the No_Implementation_Identifiers | |
3978 | restriction. | |
b7d26cb1 | 3979 | |
b71d4b62 RA |
3980 | @node Pragma Implemented,Pragma Implicit_Packing,Pragma Implementation_Defined,Implementation Defined Pragmas |
3981 | @anchor{gnat_rm/implementation_defined_pragmas pragma-implemented}@anchor{78} | |
3982 | @section Pragma Implemented | |
b7d26cb1 | 3983 | |
b7d26cb1 | 3984 | |
b71d4b62 | 3985 | Syntax: |
b7d26cb1 | 3986 | |
b71d4b62 RA |
3987 | @example |
3988 | pragma Implemented (procedure_LOCAL_NAME, implementation_kind); | |
b7d26cb1 | 3989 | |
b71d4b62 RA |
3990 | implementation_kind ::= By_Entry | By_Protected_Procedure | By_Any |
3991 | @end example | |
b7d26cb1 | 3992 | |
b71d4b62 RA |
3993 | This is an Ada 2012 representation pragma which applies to protected, task |
3994 | and synchronized interface primitives. The use of pragma Implemented provides | |
3995 | a way to impose a static requirement on the overriding operation by adhering | |
3996 | to one of the three implementation kinds: entry, protected procedure or any of | |
3997 | the above. This pragma is available in all earlier versions of Ada as an | |
3998 | implementation-defined pragma. | |
b7d26cb1 | 3999 | |
b71d4b62 RA |
4000 | @example |
4001 | type Synch_Iface is synchronized interface; | |
4002 | procedure Prim_Op (Obj : in out Iface) is abstract; | |
4003 | pragma Implemented (Prim_Op, By_Protected_Procedure); | |
b7d26cb1 | 4004 | |
b71d4b62 RA |
4005 | protected type Prot_1 is new Synch_Iface with |
4006 | procedure Prim_Op; -- Legal | |
4007 | end Prot_1; | |
b7d26cb1 | 4008 | |
b71d4b62 RA |
4009 | protected type Prot_2 is new Synch_Iface with |
4010 | entry Prim_Op; -- Illegal | |
4011 | end Prot_2; | |
b7d26cb1 | 4012 | |
b71d4b62 RA |
4013 | task type Task_Typ is new Synch_Iface with |
4014 | entry Prim_Op; -- Illegal | |
4015 | end Task_Typ; | |
4016 | @end example | |
b7d26cb1 | 4017 | |
b71d4b62 RA |
4018 | When applied to the procedure_or_entry_NAME of a requeue statement, pragma |
4019 | Implemented determines the runtime behavior of the requeue. Implementation kind | |
4020 | By_Entry guarantees that the action of requeueing will proceed from an entry to | |
4021 | another entry. Implementation kind By_Protected_Procedure transforms the | |
4022 | requeue into a dispatching call, thus eliminating the chance of blocking. Kind | |
4023 | By_Any shares the behavior of By_Entry and By_Protected_Procedure depending on | |
4024 | the target’s overriding subprogram kind. | |
b7d26cb1 | 4025 | |
b71d4b62 RA |
4026 | @node Pragma Implicit_Packing,Pragma Import_Function,Pragma Implemented,Implementation Defined Pragmas |
4027 | @anchor{gnat_rm/implementation_defined_pragmas pragma-implicit-packing}@anchor{79} | |
4028 | @section Pragma Implicit_Packing | |
b7d26cb1 | 4029 | |
b7d26cb1 | 4030 | |
b71d4b62 | 4031 | @geindex Rational Profile |
b7d26cb1 | 4032 | |
b71d4b62 | 4033 | Syntax: |
b7d26cb1 JM |
4034 | |
4035 | @example | |
b71d4b62 | 4036 | pragma Implicit_Packing; |
b7d26cb1 | 4037 | @end example |
64d5610f | 4038 | |
b71d4b62 RA |
4039 | This is a configuration pragma that requests implicit packing for packed |
4040 | arrays for which a size clause is given but no explicit pragma Pack or | |
4041 | specification of Component_Size is present. It also applies to records | |
4042 | where no record representation clause is present. Consider this example: | |
64d5610f ML |
4043 | |
4044 | @example | |
b71d4b62 RA |
4045 | type R is array (0 .. 7) of Boolean; |
4046 | for R'Size use 8; | |
64d5610f ML |
4047 | @end example |
4048 | ||
b71d4b62 RA |
4049 | In accordance with the recommendation in the RM (RM 13.3(53)), a Size clause |
4050 | does not change the layout of a composite object. So the Size clause in the | |
4051 | above example is normally rejected, since the default layout of the array uses | |
4052 | 8-bit components, and thus the array requires a minimum of 64 bits. | |
64d5610f | 4053 | |
b71d4b62 RA |
4054 | If this declaration is compiled in a region of code covered by an occurrence |
4055 | of the configuration pragma Implicit_Packing, then the Size clause in this | |
4056 | and similar examples will cause implicit packing and thus be accepted. For | |
4057 | this implicit packing to occur, the type in question must be an array of small | |
4058 | components whose size is known at compile time, and the Size clause must | |
4059 | specify the exact size that corresponds to the number of elements in the array | |
4060 | multiplied by the size in bits of the component type (both single and | |
4061 | multi-dimensioned arrays can be controlled with this pragma). | |
64d5610f | 4062 | |
b71d4b62 | 4063 | @geindex Array packing |
64d5610f | 4064 | |
b71d4b62 | 4065 | Similarly, the following example shows the use in the record case |
64d5610f ML |
4066 | |
4067 | @example | |
b71d4b62 RA |
4068 | type r is record |
4069 | a, b, c, d, e, f, g, h : boolean; | |
4070 | chr : character; | |
4071 | end record; | |
4072 | for r'size use 16; | |
64d5610f ML |
4073 | @end example |
4074 | ||
b71d4b62 RA |
4075 | Without a pragma Pack, each Boolean field requires 8 bits, so the |
4076 | minimum size is 72 bits, but with a pragma Pack, 16 bits would be | |
4077 | sufficient. The use of pragma Implicit_Packing allows this record | |
4078 | declaration to compile without an explicit pragma Pack. | |
64d5610f | 4079 | |
b71d4b62 RA |
4080 | @node Pragma Import_Function,Pragma Import_Object,Pragma Implicit_Packing,Implementation Defined Pragmas |
4081 | @anchor{gnat_rm/implementation_defined_pragmas pragma-import-function}@anchor{7a} | |
4082 | @section Pragma Import_Function | |
64d5610f | 4083 | |
64d5610f ML |
4084 | |
4085 | Syntax: | |
4086 | ||
4087 | @example | |
b71d4b62 RA |
4088 | pragma Import_Function ( |
4089 | [Internal =>] LOCAL_NAME, | |
4090 | [, [External =>] EXTERNAL_SYMBOL] | |
4091 | [, [Parameter_Types =>] PARAMETER_TYPES] | |
4092 | [, [Result_Type =>] SUBTYPE_MARK] | |
4093 | [, [Mechanism =>] MECHANISM] | |
4094 | [, [Result_Mechanism =>] MECHANISM_NAME]); | |
64d5610f | 4095 | |
b71d4b62 RA |
4096 | EXTERNAL_SYMBOL ::= |
4097 | IDENTIFIER | |
4098 | | static_string_EXPRESSION | |
64d5610f | 4099 | |
b71d4b62 RA |
4100 | PARAMETER_TYPES ::= |
4101 | null | |
4102 | | TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} | |
64d5610f | 4103 | |
b71d4b62 RA |
4104 | TYPE_DESIGNATOR ::= |
4105 | subtype_NAME | |
4106 | | subtype_Name ' Access | |
64d5610f | 4107 | |
b71d4b62 RA |
4108 | MECHANISM ::= |
4109 | MECHANISM_NAME | |
4110 | | (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) | |
64d5610f | 4111 | |
b71d4b62 RA |
4112 | MECHANISM_ASSOCIATION ::= |
4113 | [formal_parameter_NAME =>] MECHANISM_NAME | |
64d5610f | 4114 | |
b71d4b62 RA |
4115 | MECHANISM_NAME ::= |
4116 | Value | |
4117 | | Reference | |
64d5610f ML |
4118 | @end example |
4119 | ||
b71d4b62 RA |
4120 | This pragma is used in conjunction with a pragma @code{Import} to |
4121 | specify additional information for an imported function. The pragma | |
4122 | @code{Import} (or equivalent pragma @code{Interface}) must precede the | |
4123 | @code{Import_Function} pragma and both must appear in the same | |
4124 | declarative part as the function specification. | |
64d5610f | 4125 | |
b71d4b62 RA |
4126 | The @code{Internal} argument must uniquely designate |
4127 | the function to which the | |
4128 | pragma applies. If more than one function name exists of this name in | |
4129 | the declarative part you must use the @code{Parameter_Types} and | |
4130 | @code{Result_Type} parameters to achieve the required unique | |
4131 | designation. Subtype marks in these parameters must exactly match the | |
4132 | subtypes in the corresponding function specification, using positional | |
4133 | notation to match parameters with subtype marks. | |
4134 | The form with an @code{'Access} attribute can be used to match an | |
4135 | anonymous access parameter. | |
64d5610f | 4136 | |
b71d4b62 RA |
4137 | You may optionally use the @code{Mechanism} and @code{Result_Mechanism} |
4138 | parameters to specify passing mechanisms for the | |
4139 | parameters and result. If you specify a single mechanism name, it | |
4140 | applies to all parameters. Otherwise you may specify a mechanism on a | |
4141 | parameter by parameter basis using either positional or named | |
4142 | notation. If the mechanism is not specified, the default mechanism | |
4143 | is used. | |
64d5610f | 4144 | |
b71d4b62 RA |
4145 | @node Pragma Import_Object,Pragma Import_Procedure,Pragma Import_Function,Implementation Defined Pragmas |
4146 | @anchor{gnat_rm/implementation_defined_pragmas pragma-import-object}@anchor{7b} | |
4147 | @section Pragma Import_Object | |
64d5610f | 4148 | |
64d5610f | 4149 | |
b71d4b62 | 4150 | Syntax: |
64d5610f ML |
4151 | |
4152 | @example | |
b71d4b62 RA |
4153 | pragma Import_Object ( |
4154 | [Internal =>] LOCAL_NAME | |
4155 | [, [External =>] EXTERNAL_SYMBOL] | |
4156 | [, [Size =>] EXTERNAL_SYMBOL]); | |
4157 | ||
4158 | EXTERNAL_SYMBOL ::= | |
4159 | IDENTIFIER | |
4160 | | static_string_EXPRESSION | |
64d5610f ML |
4161 | @end example |
4162 | ||
b71d4b62 RA |
4163 | This pragma designates an object as imported, and apart from the |
4164 | extended rules for external symbols, is identical in effect to the use of | |
4165 | the normal @code{Import} pragma applied to an object. Unlike the | |
4166 | subprogram case, you need not use a separate @code{Import} pragma, | |
4167 | although you may do so (and probably should do so from a portability | |
4168 | point of view). @code{size} is syntax checked, but otherwise ignored by | |
4169 | GNAT. | |
64d5610f | 4170 | |
b71d4b62 RA |
4171 | @node Pragma Import_Procedure,Pragma Import_Valued_Procedure,Pragma Import_Object,Implementation Defined Pragmas |
4172 | @anchor{gnat_rm/implementation_defined_pragmas pragma-import-procedure}@anchor{7c} | |
4173 | @section Pragma Import_Procedure | |
64d5610f ML |
4174 | |
4175 | ||
4176 | Syntax: | |
4177 | ||
4178 | @example | |
b71d4b62 RA |
4179 | pragma Import_Procedure ( |
4180 | [Internal =>] LOCAL_NAME | |
4181 | [, [External =>] EXTERNAL_SYMBOL] | |
4182 | [, [Parameter_Types =>] PARAMETER_TYPES] | |
4183 | [, [Mechanism =>] MECHANISM]); | |
64d5610f | 4184 | |
b71d4b62 RA |
4185 | EXTERNAL_SYMBOL ::= |
4186 | IDENTIFIER | |
4187 | | static_string_EXPRESSION | |
64d5610f | 4188 | |
b71d4b62 RA |
4189 | PARAMETER_TYPES ::= |
4190 | null | |
4191 | | TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} | |
64d5610f | 4192 | |
b71d4b62 RA |
4193 | TYPE_DESIGNATOR ::= |
4194 | subtype_NAME | |
4195 | | subtype_Name ' Access | |
64d5610f | 4196 | |
b71d4b62 RA |
4197 | MECHANISM ::= |
4198 | MECHANISM_NAME | |
4199 | | (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) | |
64d5610f | 4200 | |
b71d4b62 RA |
4201 | MECHANISM_ASSOCIATION ::= |
4202 | [formal_parameter_NAME =>] MECHANISM_NAME | |
64d5610f | 4203 | |
b71d4b62 RA |
4204 | MECHANISM_NAME ::= Value | Reference |
4205 | @end example | |
4206 | ||
4207 | This pragma is identical to @code{Import_Function} except that it | |
4208 | applies to a procedure rather than a function and the parameters | |
4209 | @code{Result_Type} and @code{Result_Mechanism} are not permitted. | |
4210 | ||
4211 | @node Pragma Import_Valued_Procedure,Pragma Independent,Pragma Import_Procedure,Implementation Defined Pragmas | |
4212 | @anchor{gnat_rm/implementation_defined_pragmas pragma-import-valued-procedure}@anchor{7d} | |
4213 | @section Pragma Import_Valued_Procedure | |
64d5610f ML |
4214 | |
4215 | ||
4216 | Syntax: | |
4217 | ||
4218 | @example | |
b71d4b62 RA |
4219 | pragma Import_Valued_Procedure ( |
4220 | [Internal =>] LOCAL_NAME | |
4221 | [, [External =>] EXTERNAL_SYMBOL] | |
4222 | [, [Parameter_Types =>] PARAMETER_TYPES] | |
4223 | [, [Mechanism =>] MECHANISM]); | |
64d5610f | 4224 | |
b71d4b62 RA |
4225 | EXTERNAL_SYMBOL ::= |
4226 | IDENTIFIER | |
4227 | | static_string_EXPRESSION | |
64d5610f | 4228 | |
b71d4b62 RA |
4229 | PARAMETER_TYPES ::= |
4230 | null | |
4231 | | TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} | |
64d5610f | 4232 | |
b71d4b62 RA |
4233 | TYPE_DESIGNATOR ::= |
4234 | subtype_NAME | |
4235 | | subtype_Name ' Access | |
64d5610f | 4236 | |
b71d4b62 RA |
4237 | MECHANISM ::= |
4238 | MECHANISM_NAME | |
4239 | | (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) | |
64d5610f | 4240 | |
b71d4b62 RA |
4241 | MECHANISM_ASSOCIATION ::= |
4242 | [formal_parameter_NAME =>] MECHANISM_NAME | |
4243 | ||
4244 | MECHANISM_NAME ::= Value | Reference | |
64d5610f ML |
4245 | @end example |
4246 | ||
b71d4b62 RA |
4247 | This pragma is identical to @code{Import_Procedure} except that the |
4248 | first parameter of @code{LOCAL_NAME}, which must be present, must be of | |
4249 | mode @code{out}, and externally the subprogram is treated as a function | |
4250 | with this parameter as the result of the function. The purpose of this | |
4251 | capability is to allow the use of @code{out} and @code{in out} | |
4252 | parameters in interfacing to external functions (which are not permitted | |
4253 | in Ada functions). You may optionally use the @code{Mechanism} | |
4254 | parameters to specify passing mechanisms for the parameters. | |
4255 | If you specify a single mechanism name, it applies to all parameters. | |
4256 | Otherwise you may specify a mechanism on a parameter by parameter | |
4257 | basis using either positional or named notation. If the mechanism is not | |
4258 | specified, the default mechanism is used. | |
64d5610f | 4259 | |
b71d4b62 RA |
4260 | Note that it is important to use this pragma in conjunction with a separate |
4261 | pragma Import that specifies the desired convention, since otherwise the | |
4262 | default convention is Ada, which is almost certainly not what is required. | |
4263 | ||
4264 | @node Pragma Independent,Pragma Independent_Components,Pragma Import_Valued_Procedure,Implementation Defined Pragmas | |
4265 | @anchor{gnat_rm/implementation_defined_pragmas pragma-independent}@anchor{7e} | |
4266 | @section Pragma Independent | |
64d5610f ML |
4267 | |
4268 | ||
4269 | Syntax: | |
4270 | ||
4271 | @example | |
b71d4b62 | 4272 | pragma Independent (Local_NAME); |
64d5610f ML |
4273 | @end example |
4274 | ||
b71d4b62 RA |
4275 | This pragma is standard in Ada 2012 mode (which also provides an aspect |
4276 | of the same name). It is also available as an implementation-defined | |
4277 | pragma in all earlier versions. It specifies that the | |
4278 | designated object or all objects of the designated type must be | |
4279 | independently addressable. This means that separate tasks can safely | |
4280 | manipulate such objects. For example, if two components of a record are | |
4281 | independent, then two separate tasks may access these two components. | |
4282 | This may place | |
4283 | constraints on the representation of the object (for instance prohibiting | |
4284 | tight packing). | |
64d5610f | 4285 | |
b71d4b62 RA |
4286 | @node Pragma Independent_Components,Pragma Initial_Condition,Pragma Independent,Implementation Defined Pragmas |
4287 | @anchor{gnat_rm/implementation_defined_pragmas pragma-independent-components}@anchor{7f} | |
4288 | @section Pragma Independent_Components | |
64d5610f | 4289 | |
64d5610f | 4290 | |
b71d4b62 | 4291 | Syntax: |
64d5610f | 4292 | |
b71d4b62 RA |
4293 | @example |
4294 | pragma Independent_Components (Local_NAME); | |
4295 | @end example | |
64d5610f | 4296 | |
b71d4b62 RA |
4297 | This pragma is standard in Ada 2012 mode (which also provides an aspect |
4298 | of the same name). It is also available as an implementation-defined | |
4299 | pragma in all earlier versions. It specifies that the components of the | |
4300 | designated object, or the components of each object of the designated | |
4301 | type, must be | |
4302 | independently addressable. This means that separate tasks can safely | |
4303 | manipulate separate components in the composite object. This may place | |
4304 | constraints on the representation of the object (for instance prohibiting | |
4305 | tight packing). | |
64d5610f | 4306 | |
b71d4b62 RA |
4307 | @node Pragma Initial_Condition,Pragma Initialize_Scalars,Pragma Independent_Components,Implementation Defined Pragmas |
4308 | @anchor{gnat_rm/implementation_defined_pragmas id17}@anchor{80}@anchor{gnat_rm/implementation_defined_pragmas pragma-initial-condition}@anchor{81} | |
4309 | @section Pragma Initial_Condition | |
64d5610f ML |
4310 | |
4311 | ||
4312 | Syntax: | |
4313 | ||
4314 | @example | |
b71d4b62 | 4315 | pragma Initial_Condition (boolean_EXPRESSION); |
64d5610f ML |
4316 | @end example |
4317 | ||
b71d4b62 RA |
4318 | For the semantics of this pragma, see the entry for aspect @code{Initial_Condition} |
4319 | in the SPARK 2014 Reference Manual, section 7.1.6. | |
4320 | ||
4321 | @node Pragma Initialize_Scalars,Pragma Initializes,Pragma Initial_Condition,Implementation Defined Pragmas | |
4322 | @anchor{gnat_rm/implementation_defined_pragmas pragma-initialize-scalars}@anchor{82} | |
4323 | @section Pragma Initialize_Scalars | |
64d5610f | 4324 | |
64d5610f | 4325 | |
b71d4b62 | 4326 | @geindex debugging with Initialize_Scalars |
64d5610f ML |
4327 | |
4328 | Syntax: | |
4329 | ||
4330 | @example | |
b71d4b62 RA |
4331 | pragma Initialize_Scalars |
4332 | [ ( TYPE_VALUE_PAIR @{, TYPE_VALUE_PAIR@} ) ]; | |
64d5610f | 4333 | |
b71d4b62 RA |
4334 | TYPE_VALUE_PAIR ::= |
4335 | SCALAR_TYPE => static_EXPRESSION | |
64d5610f | 4336 | |
b71d4b62 RA |
4337 | SCALAR_TYPE := |
4338 | Short_Float | |
4339 | | Float | |
4340 | | Long_Float | |
4341 | | Long_Long_Flat | |
4342 | | Signed_8 | |
4343 | | Signed_16 | |
4344 | | Signed_32 | |
4345 | | Signed_64 | |
4346 | | Unsigned_8 | |
4347 | | Unsigned_16 | |
4348 | | Unsigned_32 | |
4349 | | Unsigned_64 | |
64d5610f ML |
4350 | @end example |
4351 | ||
b71d4b62 RA |
4352 | This pragma is similar to @code{Normalize_Scalars} conceptually but has two |
4353 | important differences. | |
64d5610f | 4354 | |
b71d4b62 RA |
4355 | First, there is no requirement for the pragma to be used uniformly in all units |
4356 | of a partition. In particular, it is fine to use this just for some or all of | |
4357 | the application units of a partition, without needing to recompile the run-time | |
4358 | library. In the case where some units are compiled with the pragma, and some | |
4359 | without, then a declaration of a variable where the type is defined in package | |
4360 | Standard or is locally declared will always be subject to initialization, as | |
4361 | will any declaration of a scalar variable. For composite variables, whether the | |
4362 | variable is initialized may also depend on whether the package in which the | |
4363 | type of the variable is declared is compiled with the pragma. | |
64d5610f | 4364 | |
b71d4b62 RA |
4365 | The other important difference is that the programmer can control the value |
4366 | used for initializing scalar objects. This effect can be achieved in several | |
4367 | different ways: | |
64d5610f | 4368 | |
64d5610f | 4369 | |
b71d4b62 | 4370 | @itemize * |
64d5610f | 4371 | |
b71d4b62 RA |
4372 | @item |
4373 | At compile time, the programmer can specify the invalid value for a | |
4374 | particular family of scalar types using the optional arguments of the pragma. | |
64d5610f | 4375 | |
b71d4b62 RA |
4376 | The compile-time approach is intended to optimize the generated code for the |
4377 | pragma, by possibly using fast operations such as @code{memset}. Note that such | |
4378 | optimizations require using values where the bytes all have the same binary | |
4379 | representation. | |
64d5610f | 4380 | |
b71d4b62 RA |
4381 | @item |
4382 | At bind time, the programmer has several options: | |
64d5610f | 4383 | |
64d5610f | 4384 | |
b71d4b62 | 4385 | @itemize * |
64d5610f | 4386 | |
b71d4b62 RA |
4387 | @item |
4388 | Initialization with invalid values (similar to Normalize_Scalars, though | |
4389 | for Initialize_Scalars it is not always possible to determine the invalid | |
4390 | values in complex cases like signed component fields with nonstandard | |
4391 | sizes). | |
64d5610f | 4392 | |
b71d4b62 RA |
4393 | @item |
4394 | Initialization with high values. | |
64d5610f | 4395 | |
b71d4b62 RA |
4396 | @item |
4397 | Initialization with low values. | |
64d5610f | 4398 | |
b71d4b62 RA |
4399 | @item |
4400 | Initialization with a specific bit pattern. | |
4401 | @end itemize | |
64d5610f | 4402 | |
b71d4b62 | 4403 | See the GNAT User’s Guide for binder options for specifying these cases. |
64d5610f | 4404 | |
b71d4b62 RA |
4405 | The bind-time approach is intended to provide fast turnaround for testing |
4406 | with different values, without having to recompile the program. | |
64d5610f | 4407 | |
b71d4b62 RA |
4408 | @item |
4409 | At execution time, the programmer can specify the invalid values using an | |
4410 | environment variable. See the GNAT User’s Guide for details. | |
64d5610f | 4411 | |
b71d4b62 RA |
4412 | The execution-time approach is intended to provide fast turnaround for |
4413 | testing with different values, without having to recompile and rebind the | |
4414 | program. | |
4415 | @end itemize | |
64d5610f | 4416 | |
b71d4b62 RA |
4417 | Note that pragma @code{Initialize_Scalars} is particularly useful in conjunction |
4418 | with the enhanced validity checking that is now provided in GNAT, which checks | |
4419 | for invalid values under more conditions. Using this feature (see description | |
4420 | of the `-gnatV' flag in the GNAT User’s Guide) in conjunction with pragma | |
4421 | @code{Initialize_Scalars} provides a powerful new tool to assist in the detection | |
4422 | of problems caused by uninitialized variables. | |
64d5610f | 4423 | |
b71d4b62 RA |
4424 | Note: the use of @code{Initialize_Scalars} has a fairly extensive effect on the |
4425 | generated code. This may cause your code to be substantially larger. It may | |
4426 | also cause an increase in the amount of stack required, so it is probably a | |
4427 | good idea to turn on stack checking (see description of stack checking in the | |
4428 | GNAT User’s Guide) when using this pragma. | |
4429 | ||
4430 | @node Pragma Initializes,Pragma Inline_Always,Pragma Initialize_Scalars,Implementation Defined Pragmas | |
4431 | @anchor{gnat_rm/implementation_defined_pragmas id18}@anchor{83}@anchor{gnat_rm/implementation_defined_pragmas pragma-initializes}@anchor{84} | |
4432 | @section Pragma Initializes | |
64d5610f ML |
4433 | |
4434 | ||
4435 | Syntax: | |
4436 | ||
4437 | @example | |
b71d4b62 | 4438 | pragma Initializes (INITIALIZATION_LIST); |
64d5610f | 4439 | |
b71d4b62 RA |
4440 | INITIALIZATION_LIST ::= |
4441 | null | |
4442 | | (INITIALIZATION_ITEM @{, INITIALIZATION_ITEM@}) | |
64d5610f | 4443 | |
b71d4b62 | 4444 | INITIALIZATION_ITEM ::= name [=> INPUT_LIST] |
64d5610f | 4445 | |
b71d4b62 RA |
4446 | INPUT_LIST ::= |
4447 | null | |
4448 | | INPUT | |
4449 | | (INPUT @{, INPUT@}) | |
64d5610f | 4450 | |
b71d4b62 | 4451 | INPUT ::= name |
64d5610f ML |
4452 | @end example |
4453 | ||
b71d4b62 RA |
4454 | For the semantics of this pragma, see the entry for aspect @code{Initializes} in the |
4455 | SPARK 2014 Reference Manual, section 7.1.5. | |
64d5610f | 4456 | |
b71d4b62 RA |
4457 | @node Pragma Inline_Always,Pragma Inline_Generic,Pragma Initializes,Implementation Defined Pragmas |
4458 | @anchor{gnat_rm/implementation_defined_pragmas id19}@anchor{85}@anchor{gnat_rm/implementation_defined_pragmas pragma-inline-always}@anchor{86} | |
4459 | @section Pragma Inline_Always | |
64d5610f | 4460 | |
64d5610f ML |
4461 | |
4462 | Syntax: | |
4463 | ||
4464 | @example | |
b71d4b62 | 4465 | pragma Inline_Always (NAME [, NAME]); |
64d5610f ML |
4466 | @end example |
4467 | ||
b71d4b62 RA |
4468 | Similar to pragma @code{Inline} except that inlining is unconditional. |
4469 | Inline_Always instructs the compiler to inline every direct call to the | |
4470 | subprogram or else to emit a compilation error, independently of any | |
4471 | option, in particular `-gnatn' or `-gnatN' or the optimization level. | |
4472 | It is an error to take the address or access of @code{NAME}. It is also an error to | |
4473 | apply this pragma to a primitive operation of a tagged type. Thanks to such | |
4474 | restrictions, the compiler is allowed to remove the out-of-line body of @code{NAME}. | |
4475 | ||
4476 | @node Pragma Inline_Generic,Pragma Interface,Pragma Inline_Always,Implementation Defined Pragmas | |
4477 | @anchor{gnat_rm/implementation_defined_pragmas pragma-inline-generic}@anchor{87} | |
4478 | @section Pragma Inline_Generic | |
4479 | ||
4480 | ||
4481 | Syntax: | |
64d5610f ML |
4482 | |
4483 | @example | |
b71d4b62 RA |
4484 | pragma Inline_Generic (GNAME @{, GNAME@}); |
4485 | ||
4486 | GNAME ::= generic_unit_NAME | generic_instance_NAME | |
64d5610f ML |
4487 | @end example |
4488 | ||
b71d4b62 RA |
4489 | This pragma is provided for compatibility with Dec Ada 83. It has |
4490 | no effect in GNAT (which always inlines generics), other | |
4491 | than to check that the given names are all names of generic units or | |
4492 | generic instances. | |
64d5610f | 4493 | |
b71d4b62 RA |
4494 | @node Pragma Interface,Pragma Interface_Name,Pragma Inline_Generic,Implementation Defined Pragmas |
4495 | @anchor{gnat_rm/implementation_defined_pragmas pragma-interface}@anchor{88} | |
4496 | @section Pragma Interface | |
64d5610f | 4497 | |
64d5610f | 4498 | |
b71d4b62 | 4499 | Syntax: |
64d5610f ML |
4500 | |
4501 | @example | |
b71d4b62 RA |
4502 | pragma Interface ( |
4503 | [Convention =>] convention_identifier, | |
4504 | [Entity =>] local_NAME | |
4505 | [, [External_Name =>] static_string_expression] | |
4506 | [, [Link_Name =>] static_string_expression]); | |
64d5610f ML |
4507 | @end example |
4508 | ||
b71d4b62 RA |
4509 | This pragma is identical in syntax and semantics to |
4510 | the standard Ada pragma @code{Import}. It is provided for compatibility | |
4511 | with Ada 83. The definition is upwards compatible both with pragma | |
4512 | @code{Interface} as defined in the Ada 83 Reference Manual, and also | |
4513 | with some extended implementations of this pragma in certain Ada 83 | |
4514 | implementations. The only difference between pragma @code{Interface} | |
4515 | and pragma @code{Import} is that there is special circuitry to allow | |
4516 | both pragmas to appear for the same subprogram entity (normally it | |
4517 | is illegal to have multiple @code{Import} pragmas). This is useful in | |
4518 | maintaining Ada 83/Ada 95 compatibility and is compatible with other | |
4519 | Ada 83 compilers. | |
64d5610f | 4520 | |
b71d4b62 RA |
4521 | @node Pragma Interface_Name,Pragma Interrupt_Handler,Pragma Interface,Implementation Defined Pragmas |
4522 | @anchor{gnat_rm/implementation_defined_pragmas pragma-interface-name}@anchor{89} | |
4523 | @section Pragma Interface_Name | |
64d5610f ML |
4524 | |
4525 | ||
4526 | Syntax: | |
4527 | ||
4528 | @example | |
b71d4b62 RA |
4529 | pragma Interface_Name ( |
4530 | [Entity =>] LOCAL_NAME | |
4531 | [, [External_Name =>] static_string_EXPRESSION] | |
4532 | [, [Link_Name =>] static_string_EXPRESSION]); | |
4533 | @end example | |
64d5610f | 4534 | |
b71d4b62 RA |
4535 | This pragma provides an alternative way of specifying the interface name |
4536 | for an interfaced subprogram, and is provided for compatibility with Ada | |
4537 | 83 compilers that use the pragma for this purpose. You must provide at | |
4538 | least one of @code{External_Name} or @code{Link_Name}. | |
64d5610f | 4539 | |
b71d4b62 RA |
4540 | @node Pragma Interrupt_Handler,Pragma Interrupt_State,Pragma Interface_Name,Implementation Defined Pragmas |
4541 | @anchor{gnat_rm/implementation_defined_pragmas pragma-interrupt-handler}@anchor{8a} | |
4542 | @section Pragma Interrupt_Handler | |
64d5610f | 4543 | |
64d5610f | 4544 | |
b71d4b62 | 4545 | Syntax: |
64d5610f | 4546 | |
b71d4b62 RA |
4547 | @example |
4548 | pragma Interrupt_Handler (procedure_LOCAL_NAME); | |
64d5610f ML |
4549 | @end example |
4550 | ||
b71d4b62 RA |
4551 | This program unit pragma is supported for parameterless protected procedures |
4552 | as described in Annex C of the Ada Reference Manual. | |
64d5610f | 4553 | |
b71d4b62 RA |
4554 | @node Pragma Interrupt_State,Pragma Invariant,Pragma Interrupt_Handler,Implementation Defined Pragmas |
4555 | @anchor{gnat_rm/implementation_defined_pragmas pragma-interrupt-state}@anchor{8b} | |
4556 | @section Pragma Interrupt_State | |
64d5610f ML |
4557 | |
4558 | ||
4559 | Syntax: | |
4560 | ||
4561 | @example | |
b71d4b62 RA |
4562 | pragma Interrupt_State |
4563 | ([Name =>] value, | |
4564 | [State =>] SYSTEM | RUNTIME | USER); | |
64d5610f ML |
4565 | @end example |
4566 | ||
b71d4b62 RA |
4567 | Normally certain interrupts are reserved to the implementation. Any attempt |
4568 | to attach an interrupt causes Program_Error to be raised, as described in | |
4569 | RM C.3.2(22). A typical example is the @code{SIGINT} interrupt used in | |
4570 | many systems for an @code{Ctrl-C} interrupt. Normally this interrupt is | |
4571 | reserved to the implementation, so that @code{Ctrl-C} can be used to | |
4572 | interrupt execution. Additionally, signals such as @code{SIGSEGV}, | |
4573 | @code{SIGABRT}, @code{SIGFPE} and @code{SIGILL} are often mapped to specific | |
4574 | Ada exceptions, or used to implement run-time functions such as the | |
4575 | @code{abort} statement and stack overflow checking. | |
64d5610f | 4576 | |
b71d4b62 RA |
4577 | Pragma @code{Interrupt_State} provides a general mechanism for overriding |
4578 | such uses of interrupts. It subsumes the functionality of pragma | |
4579 | @code{Unreserve_All_Interrupts}. Pragma @code{Interrupt_State} is not | |
4580 | available on Windows. On all other platforms than VxWorks, | |
4581 | it applies to signals; on VxWorks, it applies to vectored hardware interrupts | |
4582 | and may be used to mark interrupts required by the board support package | |
4583 | as reserved. | |
64d5610f | 4584 | |
b71d4b62 | 4585 | Interrupts can be in one of three states: |
64d5610f | 4586 | |
64d5610f | 4587 | |
b71d4b62 | 4588 | @itemize * |
64d5610f | 4589 | |
b71d4b62 RA |
4590 | @item |
4591 | System | |
64d5610f | 4592 | |
b71d4b62 RA |
4593 | The interrupt is reserved (no Ada handler can be installed), and the |
4594 | Ada run-time may not install a handler. As a result you are guaranteed | |
4595 | standard system default action if this interrupt is raised. This also allows | |
4596 | installing a low level handler via C APIs such as sigaction(), outside | |
4597 | of Ada control. | |
64d5610f | 4598 | |
b71d4b62 RA |
4599 | @item |
4600 | Runtime | |
64d5610f | 4601 | |
b71d4b62 RA |
4602 | The interrupt is reserved (no Ada handler can be installed). The run time |
4603 | is allowed to install a handler for internal control purposes, but is | |
4604 | not required to do so. | |
64d5610f | 4605 | |
b71d4b62 RA |
4606 | @item |
4607 | User | |
64d5610f | 4608 | |
b71d4b62 RA |
4609 | The interrupt is unreserved. The user may install an Ada handler via |
4610 | Ada.Interrupts and pragma Interrupt_Handler or Attach_Handler to provide | |
4611 | some other action. | |
4612 | @end itemize | |
64d5610f | 4613 | |
b71d4b62 RA |
4614 | These states are the allowed values of the @code{State} parameter of the |
4615 | pragma. The @code{Name} parameter is a value of the type | |
4616 | @code{Ada.Interrupts.Interrupt_ID}. Typically, it is a name declared in | |
4617 | @code{Ada.Interrupts.Names}. | |
64d5610f | 4618 | |
b71d4b62 RA |
4619 | This is a configuration pragma, and the binder will check that there |
4620 | are no inconsistencies between different units in a partition in how a | |
4621 | given interrupt is specified. It may appear anywhere a pragma is legal. | |
64d5610f | 4622 | |
b71d4b62 | 4623 | The effect is to move the interrupt to the specified state. |
64d5610f | 4624 | |
b71d4b62 RA |
4625 | By declaring interrupts to be SYSTEM, you guarantee the standard system |
4626 | action, such as a core dump. | |
64d5610f | 4627 | |
b71d4b62 RA |
4628 | By declaring interrupts to be USER, you guarantee that you can install |
4629 | a handler. | |
64d5610f | 4630 | |
b71d4b62 RA |
4631 | Note that certain signals on many operating systems cannot be caught and |
4632 | handled by applications. In such cases, the pragma is ignored. See the | |
4633 | operating system documentation, or the value of the array @code{Reserved} | |
4634 | declared in the spec of package @code{System.OS_Interface}. | |
64d5610f | 4635 | |
b71d4b62 RA |
4636 | Overriding the default state of signals used by the Ada runtime may interfere |
4637 | with an application’s runtime behavior in the cases of the synchronous signals, | |
4638 | and in the case of the signal used to implement the @code{abort} statement. | |
64d5610f | 4639 | |
b71d4b62 RA |
4640 | @node Pragma Invariant,Pragma Keep_Names,Pragma Interrupt_State,Implementation Defined Pragmas |
4641 | @anchor{gnat_rm/implementation_defined_pragmas id20}@anchor{8c}@anchor{gnat_rm/implementation_defined_pragmas pragma-invariant}@anchor{8d} | |
4642 | @section Pragma Invariant | |
64d5610f | 4643 | |
64d5610f | 4644 | |
b71d4b62 | 4645 | Syntax: |
64d5610f | 4646 | |
b71d4b62 RA |
4647 | @example |
4648 | pragma Invariant | |
4649 | ([Entity =>] private_type_LOCAL_NAME, | |
4650 | [Check =>] EXPRESSION | |
4651 | [,[Message =>] String_Expression]); | |
64d5610f ML |
4652 | @end example |
4653 | ||
b71d4b62 RA |
4654 | This pragma provides exactly the same capabilities as the Type_Invariant aspect |
4655 | defined in AI05-0146-1, and in the Ada 2012 Reference Manual. The | |
4656 | Type_Invariant aspect is fully implemented in Ada 2012 mode, but since it | |
4657 | requires the use of the aspect syntax, which is not available except in 2012 | |
4658 | mode, it is not possible to use the Type_Invariant aspect in earlier versions | |
4659 | of Ada. However the Invariant pragma may be used in any version of Ada. Also | |
4660 | note that the aspect Invariant is a synonym in GNAT for the aspect | |
4661 | Type_Invariant, but there is no pragma Type_Invariant. | |
64d5610f | 4662 | |
b71d4b62 RA |
4663 | The pragma must appear within the visible part of the package specification, |
4664 | after the type to which its Entity argument appears. As with the Invariant | |
4665 | aspect, the Check expression is not analyzed until the end of the visible | |
4666 | part of the package, so it may contain forward references. The Message | |
4667 | argument, if present, provides the exception message used if the invariant | |
4668 | is violated. If no Message parameter is provided, a default message that | |
4669 | identifies the line on which the pragma appears is used. | |
64d5610f | 4670 | |
b71d4b62 RA |
4671 | It is permissible to have multiple Invariants for the same type entity, in |
4672 | which case they are and’ed together. It is permissible to use this pragma | |
4673 | in Ada 2012 mode, but you cannot have both an invariant aspect and an | |
4674 | invariant pragma for the same entity. | |
4675 | ||
4676 | For further details on the use of this pragma, see the Ada 2012 documentation | |
4677 | of the Type_Invariant aspect. | |
4678 | ||
4679 | @node Pragma Keep_Names,Pragma License,Pragma Invariant,Implementation Defined Pragmas | |
4680 | @anchor{gnat_rm/implementation_defined_pragmas pragma-keep-names}@anchor{8e} | |
4681 | @section Pragma Keep_Names | |
64d5610f ML |
4682 | |
4683 | ||
4684 | Syntax: | |
4685 | ||
4686 | @example | |
b71d4b62 | 4687 | pragma Keep_Names ([On =>] enumeration_first_subtype_LOCAL_NAME); |
64d5610f ML |
4688 | @end example |
4689 | ||
b71d4b62 RA |
4690 | The @code{LOCAL_NAME} argument |
4691 | must refer to an enumeration first subtype | |
4692 | in the current declarative part. The effect is to retain the enumeration | |
4693 | literal names for use by @code{Image} and @code{Value} even if a global | |
4694 | @code{Discard_Names} pragma applies. This is useful when you want to | |
4695 | generally suppress enumeration literal names and for example you therefore | |
4696 | use a @code{Discard_Names} pragma in the @code{gnat.adc} file, but you | |
4697 | want to retain the names for specific enumeration types. | |
64d5610f | 4698 | |
b71d4b62 RA |
4699 | @node Pragma License,Pragma Link_With,Pragma Keep_Names,Implementation Defined Pragmas |
4700 | @anchor{gnat_rm/implementation_defined_pragmas pragma-license}@anchor{8f} | |
4701 | @section Pragma License | |
64d5610f ML |
4702 | |
4703 | ||
b71d4b62 | 4704 | @geindex License checking |
64d5610f ML |
4705 | |
4706 | Syntax: | |
4707 | ||
4708 | @example | |
b71d4b62 | 4709 | pragma License (Unrestricted | GPL | Modified_GPL | Restricted); |
64d5610f ML |
4710 | @end example |
4711 | ||
b71d4b62 RA |
4712 | This pragma is provided to allow automated checking for appropriate license |
4713 | conditions with respect to the standard and modified GPL. A pragma | |
4714 | @code{License}, which is a configuration pragma that typically appears at | |
4715 | the start of a source file or in a separate @code{gnat.adc} file, specifies | |
4716 | the licensing conditions of a unit as follows: | |
64d5610f ML |
4717 | |
4718 | ||
4719 | @itemize * | |
4720 | ||
4721 | @item | |
b71d4b62 RA |
4722 | Unrestricted |
4723 | This is used for a unit that can be freely used with no license restrictions. | |
4724 | Examples of such units are public domain units, and units from the Ada | |
4725 | Reference Manual. | |
64d5610f ML |
4726 | |
4727 | @item | |
b71d4b62 RA |
4728 | GPL |
4729 | This is used for a unit that is licensed under the unmodified GPL, and which | |
4730 | therefore cannot be @code{with}ed by a restricted unit. | |
64d5610f ML |
4731 | |
4732 | @item | |
b71d4b62 RA |
4733 | Modified_GPL |
4734 | This is used for a unit licensed under the GNAT modified GPL that includes | |
4735 | a special exception paragraph that specifically permits the inclusion of | |
4736 | the unit in programs without requiring the entire program to be released | |
4737 | under the GPL. | |
64d5610f ML |
4738 | |
4739 | @item | |
b71d4b62 RA |
4740 | Restricted |
4741 | This is used for a unit that is restricted in that it is not permitted to | |
4742 | depend on units that are licensed under the GPL. Typical examples are | |
4743 | proprietary code that is to be released under more restrictive license | |
4744 | conditions. Note that restricted units are permitted to @code{with} units | |
4745 | which are licensed under the modified GPL (this is the whole point of the | |
4746 | modified GPL). | |
64d5610f ML |
4747 | @end itemize |
4748 | ||
b71d4b62 RA |
4749 | Normally a unit with no @code{License} pragma is considered to have an |
4750 | unknown license, and no checking is done. However, standard GNAT headers | |
4751 | are recognized, and license information is derived from them as follows. | |
64d5610f | 4752 | |
b71d4b62 RA |
4753 | A GNAT license header starts with a line containing 78 hyphens. The following |
4754 | comment text is searched for the appearance of any of the following strings. | |
64d5610f | 4755 | |
b71d4b62 RA |
4756 | If the string ‘GNU General Public License’ is found, then the unit is assumed |
4757 | to have GPL license, unless the string ‘As a special exception’ follows, in | |
4758 | which case the license is assumed to be modified GPL. | |
64d5610f | 4759 | |
b71d4b62 RA |
4760 | If one of the strings |
4761 | ‘This specification is adapted from the Ada Semantic Interface’ or | |
4762 | ‘This specification is derived from the Ada Reference Manual’ is found | |
4763 | then the unit is assumed to be unrestricted. | |
64d5610f | 4764 | |
b71d4b62 RA |
4765 | These default actions means that a program with a restricted license pragma |
4766 | will automatically get warnings if a GPL unit is inappropriately | |
4767 | @code{with}ed. For example, the program: | |
64d5610f ML |
4768 | |
4769 | @example | |
b71d4b62 RA |
4770 | with Sem_Ch3; |
4771 | with GNAT.Sockets; | |
4772 | procedure Secret_Stuff is | |
4773 | ... | |
4774 | end Secret_Stuff | |
4775 | @end example | |
64d5610f | 4776 | |
b71d4b62 RA |
4777 | if compiled with pragma @code{License} (@code{Restricted}) in a |
4778 | @code{gnat.adc} file will generate the warning: | |
64d5610f | 4779 | |
b71d4b62 RA |
4780 | @example |
4781 | 1. with Sem_Ch3; | |
4782 | | | |
4783 | >>> license of withed unit "Sem_Ch3" is incompatible | |
64d5610f | 4784 | |
b71d4b62 RA |
4785 | 2. with GNAT.Sockets; |
4786 | 3. procedure Secret_Stuff is | |
64d5610f ML |
4787 | @end example |
4788 | ||
b71d4b62 RA |
4789 | Here we get a warning on @code{Sem_Ch3} since it is part of the GNAT |
4790 | compiler and is licensed under the | |
4791 | GPL, but no warning for @code{GNAT.Sockets} which is part of the GNAT | |
4792 | run time, and is therefore licensed under the modified GPL. | |
64d5610f | 4793 | |
b71d4b62 RA |
4794 | @node Pragma Link_With,Pragma Linker_Alias,Pragma License,Implementation Defined Pragmas |
4795 | @anchor{gnat_rm/implementation_defined_pragmas pragma-link-with}@anchor{90} | |
4796 | @section Pragma Link_With | |
64d5610f ML |
4797 | |
4798 | ||
4799 | Syntax: | |
4800 | ||
4801 | @example | |
b71d4b62 | 4802 | pragma Link_With (static_string_EXPRESSION @{,static_string_EXPRESSION@}); |
64d5610f ML |
4803 | @end example |
4804 | ||
b71d4b62 RA |
4805 | This pragma is provided for compatibility with certain Ada 83 compilers. |
4806 | It has exactly the same effect as pragma @code{Linker_Options} except | |
4807 | that spaces occurring within one of the string expressions are treated | |
4808 | as separators. For example, in the following case: | |
64d5610f ML |
4809 | |
4810 | @example | |
b71d4b62 | 4811 | pragma Link_With ("-labc -ldef"); |
64d5610f ML |
4812 | @end example |
4813 | ||
b71d4b62 RA |
4814 | results in passing the strings @code{-labc} and @code{-ldef} as two |
4815 | separate arguments to the linker. In addition pragma Link_With allows | |
4816 | multiple arguments, with the same effect as successive pragmas. | |
64d5610f | 4817 | |
b71d4b62 RA |
4818 | @node Pragma Linker_Alias,Pragma Linker_Constructor,Pragma Link_With,Implementation Defined Pragmas |
4819 | @anchor{gnat_rm/implementation_defined_pragmas pragma-linker-alias}@anchor{91} | |
4820 | @section Pragma Linker_Alias | |
64d5610f ML |
4821 | |
4822 | ||
4823 | Syntax: | |
4824 | ||
4825 | @example | |
b71d4b62 RA |
4826 | pragma Linker_Alias ( |
4827 | [Entity =>] LOCAL_NAME, | |
4828 | [Target =>] static_string_EXPRESSION); | |
64d5610f ML |
4829 | @end example |
4830 | ||
b71d4b62 RA |
4831 | @code{LOCAL_NAME} must refer to an object that is declared at the library |
4832 | level. This pragma establishes the given entity as a linker alias for the | |
4833 | given target. It is equivalent to @code{__attribute__((alias))} in GNU C | |
4834 | and causes @code{LOCAL_NAME} to be emitted as an alias for the symbol | |
4835 | @code{static_string_EXPRESSION} in the object file, that is to say no space | |
4836 | is reserved for @code{LOCAL_NAME} by the assembler and it will be resolved | |
4837 | to the same address as @code{static_string_EXPRESSION} by the linker. | |
64d5610f | 4838 | |
b71d4b62 RA |
4839 | The actual linker name for the target must be used (e.g., the fully |
4840 | encoded name with qualification in Ada, or the mangled name in C++), | |
4841 | or it must be declared using the C convention with @code{pragma Import} | |
4842 | or @code{pragma Export}. | |
64d5610f | 4843 | |
b71d4b62 RA |
4844 | Not all target machines support this pragma. On some of them it is accepted |
4845 | only if @code{pragma Weak_External} has been applied to @code{LOCAL_NAME}. | |
64d5610f ML |
4846 | |
4847 | @example | |
b71d4b62 | 4848 | -- Example of the use of pragma Linker_Alias |
64d5610f | 4849 | |
b71d4b62 RA |
4850 | package p is |
4851 | i : Integer := 1; | |
4852 | pragma Export (C, i); | |
64d5610f | 4853 | |
b71d4b62 RA |
4854 | new_name_for_i : Integer; |
4855 | pragma Linker_Alias (new_name_for_i, "i"); | |
4856 | end p; | |
4857 | @end example | |
4858 | ||
4859 | @node Pragma Linker_Constructor,Pragma Linker_Destructor,Pragma Linker_Alias,Implementation Defined Pragmas | |
4860 | @anchor{gnat_rm/implementation_defined_pragmas pragma-linker-constructor}@anchor{92} | |
4861 | @section Pragma Linker_Constructor | |
64d5610f ML |
4862 | |
4863 | ||
4864 | Syntax: | |
4865 | ||
4866 | @example | |
b71d4b62 | 4867 | pragma Linker_Constructor (procedure_LOCAL_NAME); |
64d5610f ML |
4868 | @end example |
4869 | ||
b71d4b62 RA |
4870 | @code{procedure_LOCAL_NAME} must refer to a parameterless procedure that |
4871 | is declared at the library level. A procedure to which this pragma is | |
4872 | applied will be treated as an initialization routine by the linker. | |
4873 | It is equivalent to @code{__attribute__((constructor))} in GNU C and | |
4874 | causes @code{procedure_LOCAL_NAME} to be invoked before the entry point | |
4875 | of the executable is called (or immediately after the shared library is | |
4876 | loaded if the procedure is linked in a shared library), in particular | |
4877 | before the Ada run-time environment is set up. | |
64d5610f | 4878 | |
b71d4b62 RA |
4879 | Because of these specific contexts, the set of operations such a procedure |
4880 | can perform is very limited and the type of objects it can manipulate is | |
4881 | essentially restricted to the elementary types. In particular, it must only | |
4882 | contain code to which pragma Restrictions (No_Elaboration_Code) applies. | |
4883 | ||
4884 | This pragma is used by GNAT to implement auto-initialization of shared Stand | |
4885 | Alone Libraries, which provides a related capability without the restrictions | |
4886 | listed above. Where possible, the use of Stand Alone Libraries is preferable | |
4887 | to the use of this pragma. | |
4888 | ||
4889 | @node Pragma Linker_Destructor,Pragma Linker_Section,Pragma Linker_Constructor,Implementation Defined Pragmas | |
4890 | @anchor{gnat_rm/implementation_defined_pragmas pragma-linker-destructor}@anchor{93} | |
4891 | @section Pragma Linker_Destructor | |
64d5610f ML |
4892 | |
4893 | ||
4894 | Syntax: | |
4895 | ||
4896 | @example | |
b71d4b62 | 4897 | pragma Linker_Destructor (procedure_LOCAL_NAME); |
64d5610f ML |
4898 | @end example |
4899 | ||
b71d4b62 RA |
4900 | @code{procedure_LOCAL_NAME} must refer to a parameterless procedure that |
4901 | is declared at the library level. A procedure to which this pragma is | |
4902 | applied will be treated as a finalization routine by the linker. | |
4903 | It is equivalent to @code{__attribute__((destructor))} in GNU C and | |
4904 | causes @code{procedure_LOCAL_NAME} to be invoked after the entry point | |
4905 | of the executable has exited (or immediately before the shared library | |
4906 | is unloaded if the procedure is linked in a shared library), in particular | |
4907 | after the Ada run-time environment is shut down. | |
64d5610f | 4908 | |
b71d4b62 RA |
4909 | See @code{pragma Linker_Constructor} for the set of restrictions that apply |
4910 | because of these specific contexts. | |
64d5610f | 4911 | |
b71d4b62 RA |
4912 | @node Pragma Linker_Section,Pragma Lock_Free,Pragma Linker_Destructor,Implementation Defined Pragmas |
4913 | @anchor{gnat_rm/implementation_defined_pragmas id21}@anchor{94}@anchor{gnat_rm/implementation_defined_pragmas pragma-linker-section}@anchor{95} | |
4914 | @section Pragma Linker_Section | |
64d5610f ML |
4915 | |
4916 | ||
b71d4b62 | 4917 | Syntax: |
64d5610f | 4918 | |
b71d4b62 RA |
4919 | @example |
4920 | pragma Linker_Section ( | |
4921 | [Entity =>] LOCAL_NAME, | |
4922 | [Section =>] static_string_EXPRESSION); | |
4923 | @end example | |
64d5610f | 4924 | |
b71d4b62 RA |
4925 | @code{LOCAL_NAME} must refer to an object, type, or subprogram that is |
4926 | declared at the library level. This pragma specifies the name of the | |
4927 | linker section for the given entity. It is equivalent to | |
4928 | @code{__attribute__((section))} in GNU C and causes @code{LOCAL_NAME} to | |
4929 | be placed in the @code{static_string_EXPRESSION} section of the | |
4930 | executable (assuming the linker doesn’t rename the section). | |
4931 | GNAT also provides an implementation defined aspect of the same name. | |
64d5610f | 4932 | |
b71d4b62 RA |
4933 | In the case of specifying this aspect for a type, the effect is to |
4934 | specify the corresponding section for all library-level objects of | |
4935 | the type that do not have an explicit linker section set. Note that | |
4936 | this only applies to whole objects, not to components of composite objects. | |
64d5610f | 4937 | |
b71d4b62 RA |
4938 | In the case of a subprogram, the linker section applies to all previously |
4939 | declared matching overloaded subprograms in the current declarative part | |
4940 | which do not already have a linker section assigned. The linker section | |
4941 | aspect is useful in this case for specifying different linker sections | |
4942 | for different elements of such an overloaded set. | |
64d5610f | 4943 | |
b71d4b62 RA |
4944 | Note that an empty string specifies that no linker section is specified. |
4945 | This is not quite the same as omitting the pragma or aspect, since it | |
4946 | can be used to specify that one element of an overloaded set of subprograms | |
4947 | has the default linker section, or that one object of a type for which a | |
4948 | linker section is specified should has the default linker section. | |
64d5610f | 4949 | |
b71d4b62 RA |
4950 | The compiler normally places library-level entities in standard sections |
4951 | depending on the class: procedures and functions generally go in the | |
4952 | @code{.text} section, initialized variables in the @code{.data} section | |
4953 | and uninitialized variables in the @code{.bss} section. | |
64d5610f | 4954 | |
b71d4b62 RA |
4955 | Other, special sections may exist on given target machines to map special |
4956 | hardware, for example I/O ports or flash memory. This pragma is a means to | |
4957 | defer the final layout of the executable to the linker, thus fully working | |
4958 | at the symbolic level with the compiler. | |
64d5610f | 4959 | |
b71d4b62 RA |
4960 | Some file formats do not support arbitrary sections so not all target |
4961 | machines support this pragma. The use of this pragma may cause a program | |
4962 | execution to be erroneous if it is used to place an entity into an | |
4963 | inappropriate section (e.g., a modified variable into the @code{.text} | |
4964 | section). See also @code{pragma Persistent_BSS}. | |
64d5610f | 4965 | |
b71d4b62 RA |
4966 | @example |
4967 | -- Example of the use of pragma Linker_Section | |
64d5610f | 4968 | |
b71d4b62 RA |
4969 | package IO_Card is |
4970 | Port_A : Integer; | |
4971 | pragma Volatile (Port_A); | |
4972 | pragma Linker_Section (Port_A, ".bss.port_a"); | |
64d5610f | 4973 | |
b71d4b62 RA |
4974 | Port_B : Integer; |
4975 | pragma Volatile (Port_B); | |
4976 | pragma Linker_Section (Port_B, ".bss.port_b"); | |
64d5610f | 4977 | |
b71d4b62 RA |
4978 | type Port_Type is new Integer with Linker_Section => ".bss"; |
4979 | PA : Port_Type with Linker_Section => ".bss.PA"; | |
4980 | PB : Port_Type; -- ends up in linker section ".bss" | |
64d5610f | 4981 | |
b71d4b62 RA |
4982 | procedure Q with Linker_Section => "Qsection"; |
4983 | end IO_Card; | |
4984 | @end example | |
64d5610f | 4985 | |
b71d4b62 RA |
4986 | @node Pragma Lock_Free,Pragma Loop_Invariant,Pragma Linker_Section,Implementation Defined Pragmas |
4987 | @anchor{gnat_rm/implementation_defined_pragmas id22}@anchor{96}@anchor{gnat_rm/implementation_defined_pragmas pragma-lock-free}@anchor{97} | |
4988 | @section Pragma Lock_Free | |
64d5610f ML |
4989 | |
4990 | ||
4991 | Syntax: | |
b71d4b62 RA |
4992 | This pragma may be specified for protected types or objects. It specifies that |
4993 | the implementation of protected operations must be implemented without locks. | |
4994 | Compilation fails if the compiler cannot generate lock-free code for the | |
4995 | operations. | |
64d5610f | 4996 | |
b71d4b62 | 4997 | The current conditions required to support this pragma are: |
64d5610f | 4998 | |
64d5610f | 4999 | |
b71d4b62 | 5000 | @itemize * |
64d5610f | 5001 | |
b71d4b62 RA |
5002 | @item |
5003 | Protected type declarations may not contain entries | |
64d5610f | 5004 | |
b71d4b62 RA |
5005 | @item |
5006 | Protected subprogram declarations may not have nonelementary parameters | |
5007 | @end itemize | |
64d5610f | 5008 | |
b71d4b62 | 5009 | In addition, each protected subprogram body must satisfy: |
64d5610f ML |
5010 | |
5011 | ||
b71d4b62 | 5012 | @itemize * |
64d5610f | 5013 | |
b71d4b62 RA |
5014 | @item |
5015 | May reference only one protected component | |
64d5610f | 5016 | |
b71d4b62 RA |
5017 | @item |
5018 | May not reference nonconstant entities outside the protected subprogram | |
5019 | scope | |
64d5610f | 5020 | |
b71d4b62 RA |
5021 | @item |
5022 | May not contain address representation items, allocators, or quantified | |
5023 | expressions | |
64d5610f ML |
5024 | |
5025 | @item | |
b71d4b62 | 5026 | May not contain delay, goto, loop, or procedure-call statements |
64d5610f ML |
5027 | |
5028 | @item | |
b71d4b62 | 5029 | May not contain exported and imported entities |
64d5610f ML |
5030 | |
5031 | @item | |
b71d4b62 | 5032 | May not dereferenced access values |
64d5610f ML |
5033 | |
5034 | @item | |
b71d4b62 | 5035 | Function calls and attribute references must be static |
64d5610f ML |
5036 | @end itemize |
5037 | ||
b71d4b62 RA |
5038 | If the Lock_Free aspect is specified to be True for a protected unit |
5039 | and the Ceiling_Locking locking policy is in effect, then the run-time | |
5040 | actions associated with the Ceiling_Locking locking policy (described in | |
5041 | Ada RM D.3) are not performed when a protected operation of the protected | |
5042 | unit is executed. | |
64d5610f | 5043 | |
b71d4b62 RA |
5044 | @node Pragma Loop_Invariant,Pragma Loop_Optimize,Pragma Lock_Free,Implementation Defined Pragmas |
5045 | @anchor{gnat_rm/implementation_defined_pragmas pragma-loop-invariant}@anchor{98} | |
5046 | @section Pragma Loop_Invariant | |
64d5610f | 5047 | |
64d5610f | 5048 | |
b71d4b62 | 5049 | Syntax: |
64d5610f ML |
5050 | |
5051 | @example | |
b71d4b62 | 5052 | pragma Loop_Invariant ( boolean_EXPRESSION ); |
64d5610f ML |
5053 | @end example |
5054 | ||
b71d4b62 RA |
5055 | The effect of this pragma is similar to that of pragma @code{Assert}, |
5056 | except that in an @code{Assertion_Policy} pragma, the identifier | |
5057 | @code{Loop_Invariant} is used to control whether it is ignored or checked | |
5058 | (or disabled). | |
64d5610f | 5059 | |
b71d4b62 RA |
5060 | @code{Loop_Invariant} can only appear as one of the items in the sequence |
5061 | of statements of a loop body, or nested inside block statements that | |
5062 | appear in the sequence of statements of a loop body. | |
5063 | The intention is that it be used to | |
5064 | represent a “loop invariant” assertion, i.e. something that is true each | |
5065 | time through the loop, and which can be used to show that the loop is | |
5066 | achieving its purpose. | |
64d5610f | 5067 | |
b71d4b62 RA |
5068 | Multiple @code{Loop_Invariant} and @code{Loop_Variant} pragmas that |
5069 | apply to the same loop should be grouped in the same sequence of | |
5070 | statements. | |
64d5610f | 5071 | |
b71d4b62 RA |
5072 | To aid in writing such invariants, the special attribute @code{Loop_Entry} |
5073 | may be used to refer to the value of an expression on entry to the loop. This | |
5074 | attribute can only be used within the expression of a @code{Loop_Invariant} | |
5075 | pragma. For full details, see documentation of attribute @code{Loop_Entry}. | |
64d5610f | 5076 | |
b71d4b62 RA |
5077 | @node Pragma Loop_Optimize,Pragma Loop_Variant,Pragma Loop_Invariant,Implementation Defined Pragmas |
5078 | @anchor{gnat_rm/implementation_defined_pragmas pragma-loop-optimize}@anchor{99} | |
5079 | @section Pragma Loop_Optimize | |
64d5610f ML |
5080 | |
5081 | ||
5082 | Syntax: | |
5083 | ||
5084 | @example | |
b71d4b62 RA |
5085 | pragma Loop_Optimize (OPTIMIZATION_HINT @{, OPTIMIZATION_HINT@}); |
5086 | ||
5087 | OPTIMIZATION_HINT ::= Ivdep | No_Unroll | Unroll | No_Vector | Vector | |
64d5610f ML |
5088 | @end example |
5089 | ||
b71d4b62 RA |
5090 | This pragma must appear immediately within a loop statement. It allows the |
5091 | programmer to specify optimization hints for the enclosing loop. The hints | |
5092 | are not mutually exclusive and can be freely mixed, but not all combinations | |
5093 | will yield a sensible outcome. | |
64d5610f | 5094 | |
b71d4b62 | 5095 | There are five supported optimization hints for a loop: |
64d5610f | 5096 | |
64d5610f | 5097 | |
b71d4b62 | 5098 | @itemize * |
64d5610f | 5099 | |
b71d4b62 RA |
5100 | @item |
5101 | Ivdep | |
64d5610f | 5102 | |
b71d4b62 RA |
5103 | The programmer asserts that there are no loop-carried dependencies |
5104 | which would prevent consecutive iterations of the loop from being | |
5105 | executed simultaneously. | |
64d5610f | 5106 | |
b71d4b62 RA |
5107 | @item |
5108 | No_Unroll | |
64d5610f | 5109 | |
b71d4b62 RA |
5110 | The loop must not be unrolled. This is a strong hint: the compiler will not |
5111 | unroll a loop marked with this hint. | |
64d5610f | 5112 | |
b71d4b62 RA |
5113 | @item |
5114 | Unroll | |
64d5610f | 5115 | |
b71d4b62 RA |
5116 | The loop should be unrolled. This is a weak hint: the compiler will try to |
5117 | apply unrolling to this loop preferably to other optimizations, notably | |
5118 | vectorization, but there is no guarantee that the loop will be unrolled. | |
64d5610f | 5119 | |
b71d4b62 RA |
5120 | @item |
5121 | No_Vector | |
64d5610f | 5122 | |
b71d4b62 RA |
5123 | The loop must not be vectorized. This is a strong hint: the compiler will not |
5124 | vectorize a loop marked with this hint. | |
64d5610f | 5125 | |
b71d4b62 RA |
5126 | @item |
5127 | Vector | |
64d5610f | 5128 | |
b71d4b62 RA |
5129 | The loop should be vectorized. This is a weak hint: the compiler will try to |
5130 | apply vectorization to this loop preferably to other optimizations, notably | |
5131 | unrolling, but there is no guarantee that the loop will be vectorized. | |
5132 | @end itemize | |
5133 | ||
5134 | These hints do not remove the need to pass the appropriate switches to the | |
5135 | compiler in order to enable the relevant optimizations, that is to say | |
5136 | `-funroll-loops' for unrolling and `-ftree-vectorize' for | |
5137 | vectorization. | |
5138 | ||
5139 | @node Pragma Loop_Variant,Pragma Machine_Attribute,Pragma Loop_Optimize,Implementation Defined Pragmas | |
5140 | @anchor{gnat_rm/implementation_defined_pragmas pragma-loop-variant}@anchor{9a} | |
5141 | @section Pragma Loop_Variant | |
64d5610f ML |
5142 | |
5143 | ||
5144 | Syntax: | |
5145 | ||
5146 | @example | |
b71d4b62 RA |
5147 | pragma Loop_Variant ( LOOP_VARIANT_ITEM @{, LOOP_VARIANT_ITEM @} ); |
5148 | LOOP_VARIANT_ITEM ::= CHANGE_DIRECTION => discrete_EXPRESSION | |
5149 | CHANGE_DIRECTION ::= Increases | Decreases | |
64d5610f ML |
5150 | @end example |
5151 | ||
b71d4b62 RA |
5152 | @code{Loop_Variant} can only appear as one of the items in the sequence |
5153 | of statements of a loop body, or nested inside block statements that | |
5154 | appear in the sequence of statements of a loop body. | |
5155 | It allows the specification of quantities which must always | |
5156 | decrease or increase in successive iterations of the loop. In its simplest | |
5157 | form, just one expression is specified, whose value must increase or decrease | |
5158 | on each iteration of the loop. | |
64d5610f | 5159 | |
b71d4b62 RA |
5160 | In a more complex form, multiple arguments can be given which are interpreted |
5161 | in a nesting lexicographic manner. For example: | |
64d5610f | 5162 | |
b71d4b62 RA |
5163 | @example |
5164 | pragma Loop_Variant (Increases => X, Decreases => Y); | |
5165 | @end example | |
64d5610f | 5166 | |
b71d4b62 RA |
5167 | specifies that each time through the loop either X increases, or X stays |
5168 | the same and Y decreases. A @code{Loop_Variant} pragma ensures that the | |
5169 | loop is making progress. It can be useful in helping to show informally | |
5170 | or prove formally that the loop always terminates. | |
5171 | ||
5172 | @code{Loop_Variant} is an assertion whose effect can be controlled using | |
5173 | an @code{Assertion_Policy} with a check name of @code{Loop_Variant}. The | |
5174 | policy can be @code{Check} to enable the loop variant check, @code{Ignore} | |
5175 | to ignore the check (in which case the pragma has no effect on the program), | |
5176 | or @code{Disable} in which case the pragma is not even checked for correct | |
5177 | syntax. | |
5178 | ||
5179 | Multiple @code{Loop_Invariant} and @code{Loop_Variant} pragmas that | |
5180 | apply to the same loop should be grouped in the same sequence of | |
5181 | statements. | |
5182 | ||
5183 | The @code{Loop_Entry} attribute may be used within the expressions of the | |
5184 | @code{Loop_Variant} pragma to refer to values on entry to the loop. | |
5185 | ||
5186 | @node Pragma Machine_Attribute,Pragma Main,Pragma Loop_Variant,Implementation Defined Pragmas | |
5187 | @anchor{gnat_rm/implementation_defined_pragmas pragma-machine-attribute}@anchor{9b} | |
5188 | @section Pragma Machine_Attribute | |
64d5610f ML |
5189 | |
5190 | ||
5191 | Syntax: | |
5192 | ||
5193 | @example | |
b71d4b62 RA |
5194 | pragma Machine_Attribute ( |
5195 | [Entity =>] LOCAL_NAME, | |
5196 | [Attribute_Name =>] static_string_EXPRESSION | |
5197 | [, [Info =>] static_EXPRESSION @{, static_EXPRESSION@}] ); | |
64d5610f ML |
5198 | @end example |
5199 | ||
b71d4b62 RA |
5200 | Machine-dependent attributes can be specified for types and/or |
5201 | declarations. This pragma is semantically equivalent to | |
5202 | @code{__attribute__((@var{attribute_name}))} (if @code{info} is not | |
5203 | specified) or @code{__attribute__((@var{attribute_name(info})))} | |
5204 | or @code{__attribute__((@var{attribute_name(info,...})))} in GNU C, | |
5205 | where `attribute_name' is recognized by the compiler middle-end | |
5206 | or the @code{TARGET_ATTRIBUTE_TABLE} machine specific macro. Note | |
5207 | that a string literal for the optional parameter @code{info} or the | |
5208 | following ones is transformed by default into an identifier, | |
5209 | which may make this pragma unusable for some attributes. | |
5210 | For further information see @cite{GNU Compiler Collection (GCC) Internals}. | |
64d5610f | 5211 | |
b71d4b62 RA |
5212 | @node Pragma Main,Pragma Main_Storage,Pragma Machine_Attribute,Implementation Defined Pragmas |
5213 | @anchor{gnat_rm/implementation_defined_pragmas pragma-main}@anchor{9c} | |
5214 | @section Pragma Main | |
64d5610f ML |
5215 | |
5216 | ||
5217 | Syntax: | |
5218 | ||
5219 | @example | |
b71d4b62 RA |
5220 | pragma Main |
5221 | (MAIN_OPTION [, MAIN_OPTION]); | |
64d5610f | 5222 | |
b71d4b62 RA |
5223 | MAIN_OPTION ::= |
5224 | [Stack_Size =>] static_integer_EXPRESSION | |
5225 | | [Task_Stack_Size_Default =>] static_integer_EXPRESSION | |
5226 | | [Time_Slicing_Enabled =>] static_boolean_EXPRESSION | |
5227 | @end example | |
64d5610f | 5228 | |
b71d4b62 RA |
5229 | This pragma is provided for compatibility with OpenVMS VAX Systems. It has |
5230 | no effect in GNAT, other than being syntax checked. | |
64d5610f | 5231 | |
b71d4b62 RA |
5232 | @node Pragma Main_Storage,Pragma Max_Queue_Length,Pragma Main,Implementation Defined Pragmas |
5233 | @anchor{gnat_rm/implementation_defined_pragmas pragma-main-storage}@anchor{9d} | |
5234 | @section Pragma Main_Storage | |
64d5610f | 5235 | |
64d5610f | 5236 | |
b71d4b62 | 5237 | Syntax: |
64d5610f | 5238 | |
b71d4b62 RA |
5239 | @example |
5240 | pragma Main_Storage | |
5241 | (MAIN_STORAGE_OPTION [, MAIN_STORAGE_OPTION]); | |
64d5610f | 5242 | |
b71d4b62 RA |
5243 | MAIN_STORAGE_OPTION ::= |
5244 | [WORKING_STORAGE =>] static_SIMPLE_EXPRESSION | |
5245 | | [TOP_GUARD =>] static_SIMPLE_EXPRESSION | |
5246 | @end example | |
64d5610f | 5247 | |
b71d4b62 RA |
5248 | This pragma is provided for compatibility with OpenVMS VAX Systems. It has |
5249 | no effect in GNAT, other than being syntax checked. | |
64d5610f | 5250 | |
b71d4b62 RA |
5251 | @node Pragma Max_Queue_Length,Pragma No_Body,Pragma Main_Storage,Implementation Defined Pragmas |
5252 | @anchor{gnat_rm/implementation_defined_pragmas id23}@anchor{9e}@anchor{gnat_rm/implementation_defined_pragmas pragma-max-queue-length}@anchor{9f} | |
5253 | @section Pragma Max_Queue_Length | |
64d5610f | 5254 | |
64d5610f | 5255 | |
b71d4b62 | 5256 | Syntax: |
64d5610f | 5257 | |
b71d4b62 RA |
5258 | @example |
5259 | pragma Max_Entry_Queue (static_integer_EXPRESSION); | |
64d5610f ML |
5260 | @end example |
5261 | ||
b71d4b62 RA |
5262 | This pragma is used to specify the maximum callers per entry queue for |
5263 | individual protected entries and entry families. It accepts a single | |
5264 | integer (-1 or more) as a parameter and must appear after the declaration of an | |
5265 | entry. | |
64d5610f | 5266 | |
b71d4b62 | 5267 | A value of -1 represents no additional restriction on queue length. |
64d5610f | 5268 | |
b71d4b62 RA |
5269 | @node Pragma No_Body,Pragma No_Caching,Pragma Max_Queue_Length,Implementation Defined Pragmas |
5270 | @anchor{gnat_rm/implementation_defined_pragmas pragma-no-body}@anchor{a0} | |
5271 | @section Pragma No_Body | |
64d5610f ML |
5272 | |
5273 | ||
b71d4b62 | 5274 | Syntax: |
64d5610f | 5275 | |
b71d4b62 RA |
5276 | @example |
5277 | pragma No_Body; | |
5278 | @end example | |
64d5610f | 5279 | |
b71d4b62 RA |
5280 | There are a number of cases in which a package spec does not require a body, |
5281 | and in fact a body is not permitted. GNAT will not permit the spec to be | |
5282 | compiled if there is a body around. The pragma No_Body allows you to provide | |
5283 | a body file, even in a case where no body is allowed. The body file must | |
5284 | contain only comments and a single No_Body pragma. This is recognized by | |
5285 | the compiler as indicating that no body is logically present. | |
64d5610f | 5286 | |
b71d4b62 RA |
5287 | This is particularly useful during maintenance when a package is modified in |
5288 | such a way that a body needed before is no longer needed. The provision of a | |
5289 | dummy body with a No_Body pragma ensures that there is no interference from | |
5290 | earlier versions of the package body. | |
64d5610f | 5291 | |
b71d4b62 RA |
5292 | @node Pragma No_Caching,Pragma No_Component_Reordering,Pragma No_Body,Implementation Defined Pragmas |
5293 | @anchor{gnat_rm/implementation_defined_pragmas id24}@anchor{a1}@anchor{gnat_rm/implementation_defined_pragmas pragma-no-caching}@anchor{a2} | |
5294 | @section Pragma No_Caching | |
64d5610f | 5295 | |
64d5610f | 5296 | |
b71d4b62 | 5297 | Syntax: |
64d5610f | 5298 | |
b71d4b62 RA |
5299 | @example |
5300 | pragma No_Caching [ (static_boolean_EXPRESSION) ]; | |
5301 | @end example | |
64d5610f | 5302 | |
b71d4b62 RA |
5303 | For the semantics of this pragma, see the entry for aspect @code{No_Caching} in |
5304 | the SPARK 2014 Reference Manual, section 7.1.2. | |
64d5610f | 5305 | |
b71d4b62 RA |
5306 | @node Pragma No_Component_Reordering,Pragma No_Elaboration_Code_All,Pragma No_Caching,Implementation Defined Pragmas |
5307 | @anchor{gnat_rm/implementation_defined_pragmas pragma-no-component-reordering}@anchor{a3} | |
5308 | @section Pragma No_Component_Reordering | |
64d5610f | 5309 | |
64d5610f | 5310 | |
b71d4b62 | 5311 | Syntax: |
64d5610f | 5312 | |
b71d4b62 RA |
5313 | @example |
5314 | pragma No_Component_Reordering [([Entity =>] type_LOCAL_NAME)]; | |
5315 | @end example | |
64d5610f | 5316 | |
b71d4b62 RA |
5317 | @code{type_LOCAL_NAME} must refer to a record type declaration in the current |
5318 | declarative part. The effect is to preclude any reordering of components | |
5319 | for the layout of the record, i.e. the record is laid out by the compiler | |
5320 | in the order in which the components are declared textually. The form with | |
5321 | no argument is a configuration pragma which applies to all record types | |
5322 | declared in units to which the pragma applies and there is a requirement | |
5323 | that this pragma be used consistently within a partition. | |
64d5610f | 5324 | |
b71d4b62 RA |
5325 | @node Pragma No_Elaboration_Code_All,Pragma No_Heap_Finalization,Pragma No_Component_Reordering,Implementation Defined Pragmas |
5326 | @anchor{gnat_rm/implementation_defined_pragmas id25}@anchor{a4}@anchor{gnat_rm/implementation_defined_pragmas pragma-no-elaboration-code-all}@anchor{a5} | |
5327 | @section Pragma No_Elaboration_Code_All | |
64d5610f ML |
5328 | |
5329 | ||
5330 | Syntax: | |
5331 | ||
5332 | @example | |
b71d4b62 | 5333 | pragma No_Elaboration_Code_All [(program_unit_NAME)]; |
64d5610f ML |
5334 | @end example |
5335 | ||
b71d4b62 RA |
5336 | This is a program unit pragma (there is also an equivalent aspect of the |
5337 | same name) that establishes the restriction @code{No_Elaboration_Code} for | |
5338 | the current unit and any extended main source units (body and subunits). | |
5339 | It also has the effect of enforcing a transitive application of this | |
5340 | aspect, so that if any unit is implicitly or explicitly with’ed by the | |
5341 | current unit, it must also have the No_Elaboration_Code_All aspect set. | |
5342 | It may be applied to package or subprogram specs or their generic versions. | |
64d5610f | 5343 | |
b71d4b62 RA |
5344 | @node Pragma No_Heap_Finalization,Pragma No_Inline,Pragma No_Elaboration_Code_All,Implementation Defined Pragmas |
5345 | @anchor{gnat_rm/implementation_defined_pragmas pragma-no-heap-finalization}@anchor{a6} | |
5346 | @section Pragma No_Heap_Finalization | |
64d5610f ML |
5347 | |
5348 | ||
5349 | Syntax: | |
5350 | ||
5351 | @example | |
b71d4b62 | 5352 | pragma No_Heap_Finalization [ (first_subtype_LOCAL_NAME) ]; |
64d5610f ML |
5353 | @end example |
5354 | ||
b71d4b62 RA |
5355 | Pragma @code{No_Heap_Finalization} may be used as a configuration pragma or as a |
5356 | type-specific pragma. | |
64d5610f | 5357 | |
b71d4b62 RA |
5358 | In its configuration form, the pragma must appear within a configuration file |
5359 | such as gnat.adc, without an argument. The pragma suppresses the call to | |
5360 | @code{Finalize} for heap-allocated objects created through library-level named | |
5361 | access-to-object types in cases where the designated type requires finalization | |
5362 | actions. | |
64d5610f | 5363 | |
b71d4b62 RA |
5364 | In its type-specific form, the argument of the pragma must denote a |
5365 | library-level named access-to-object type. The pragma suppresses the call to | |
5366 | @code{Finalize} for heap-allocated objects created through the specific access type | |
5367 | in cases where the designated type requires finalization actions. | |
64d5610f | 5368 | |
b71d4b62 RA |
5369 | It is still possible to finalize such heap-allocated objects by explicitly |
5370 | deallocating them. | |
64d5610f | 5371 | |
b71d4b62 RA |
5372 | A library-level named access-to-object type declared within a generic unit will |
5373 | lose its @code{No_Heap_Finalization} pragma when the corresponding instance does not | |
5374 | appear at the library level. | |
64d5610f | 5375 | |
b71d4b62 RA |
5376 | @node Pragma No_Inline,Pragma No_Return,Pragma No_Heap_Finalization,Implementation Defined Pragmas |
5377 | @anchor{gnat_rm/implementation_defined_pragmas id26}@anchor{a7}@anchor{gnat_rm/implementation_defined_pragmas pragma-no-inline}@anchor{a8} | |
5378 | @section Pragma No_Inline | |
64d5610f ML |
5379 | |
5380 | ||
5381 | Syntax: | |
5382 | ||
5383 | @example | |
b71d4b62 | 5384 | pragma No_Inline (NAME @{, NAME@}); |
64d5610f ML |
5385 | @end example |
5386 | ||
b71d4b62 RA |
5387 | This pragma suppresses inlining for the callable entity or the instances of |
5388 | the generic subprogram designated by @code{NAME}, including inlining that | |
5389 | results from the use of pragma @code{Inline}. This pragma is always active, | |
5390 | in particular it is not subject to the use of option `-gnatn' or | |
5391 | `-gnatN'. It is illegal to specify both pragma @code{No_Inline} and | |
5392 | pragma @code{Inline_Always} for the same @code{NAME}. | |
5393 | ||
5394 | @node Pragma No_Return,Pragma No_Strict_Aliasing,Pragma No_Inline,Implementation Defined Pragmas | |
5395 | @anchor{gnat_rm/implementation_defined_pragmas pragma-no-return}@anchor{a9} | |
5396 | @section Pragma No_Return | |
64d5610f | 5397 | |
b71d4b62 RA |
5398 | |
5399 | Syntax: | |
64d5610f ML |
5400 | |
5401 | @example | |
b71d4b62 | 5402 | pragma No_Return (procedure_LOCAL_NAME @{, procedure_LOCAL_NAME@}); |
64d5610f ML |
5403 | @end example |
5404 | ||
b71d4b62 RA |
5405 | Each @code{procedure_LOCAL_NAME} argument must refer to one or more procedure |
5406 | declarations in the current declarative part. A procedure to which this | |
5407 | pragma is applied may not contain any explicit @code{return} statements. | |
5408 | In addition, if the procedure contains any implicit returns from falling | |
5409 | off the end of a statement sequence, then execution of that implicit | |
5410 | return will cause Program_Error to be raised. | |
64d5610f | 5411 | |
b71d4b62 RA |
5412 | One use of this pragma is to identify procedures whose only purpose is to raise |
5413 | an exception. Another use of this pragma is to suppress incorrect warnings | |
5414 | about missing returns in functions, where the last statement of a function | |
5415 | statement sequence is a call to such a procedure. | |
64d5610f | 5416 | |
b71d4b62 RA |
5417 | Note that in Ada 2005 mode, this pragma is part of the language. It is |
5418 | available in all earlier versions of Ada as an implementation-defined | |
5419 | pragma. | |
64d5610f | 5420 | |
b71d4b62 RA |
5421 | @node Pragma No_Strict_Aliasing,Pragma No_Tagged_Streams,Pragma No_Return,Implementation Defined Pragmas |
5422 | @anchor{gnat_rm/implementation_defined_pragmas pragma-no-strict-aliasing}@anchor{aa} | |
5423 | @section Pragma No_Strict_Aliasing | |
64d5610f ML |
5424 | |
5425 | ||
5426 | Syntax: | |
5427 | ||
5428 | @example | |
b71d4b62 | 5429 | pragma No_Strict_Aliasing [([Entity =>] type_LOCAL_NAME)]; |
64d5610f ML |
5430 | @end example |
5431 | ||
b71d4b62 RA |
5432 | @code{type_LOCAL_NAME} must refer to an access type |
5433 | declaration in the current declarative part. The effect is to inhibit | |
5434 | strict aliasing optimization for the given type. The form with no | |
5435 | arguments is a configuration pragma which applies to all access types | |
5436 | declared in units to which the pragma applies. For a detailed | |
5437 | description of the strict aliasing optimization, and the situations | |
5438 | in which it must be suppressed, see the section on Optimization and Strict Aliasing | |
5439 | in the @cite{GNAT User’s Guide}. | |
64d5610f | 5440 | |
b71d4b62 RA |
5441 | This pragma currently has no effects on access to unconstrained array types. |
5442 | ||
5443 | @node Pragma No_Tagged_Streams,Pragma Normalize_Scalars,Pragma No_Strict_Aliasing,Implementation Defined Pragmas | |
5444 | @anchor{gnat_rm/implementation_defined_pragmas id27}@anchor{ab}@anchor{gnat_rm/implementation_defined_pragmas pragma-no-tagged-streams}@anchor{ac} | |
5445 | @section Pragma No_Tagged_Streams | |
64d5610f ML |
5446 | |
5447 | ||
5448 | Syntax: | |
5449 | ||
5450 | @example | |
b71d4b62 | 5451 | pragma No_Tagged_Streams [([Entity =>] tagged_type_LOCAL_NAME)]; |
64d5610f ML |
5452 | @end example |
5453 | ||
b71d4b62 RA |
5454 | Normally when a tagged type is introduced using a full type declaration, |
5455 | part of the processing includes generating stream access routines to be | |
5456 | used by stream attributes referencing the type (or one of its subtypes | |
5457 | or derived types). This can involve the generation of significant amounts | |
5458 | of code which is wasted space if stream routines are not needed for the | |
5459 | type in question. | |
64d5610f | 5460 | |
b71d4b62 RA |
5461 | The @code{No_Tagged_Streams} pragma causes the generation of these stream |
5462 | routines to be skipped, and any attempt to use stream operations on | |
5463 | types subject to this pragma will be statically rejected as illegal. | |
64d5610f | 5464 | |
b71d4b62 RA |
5465 | There are two forms of the pragma. The form with no arguments must appear |
5466 | in a declarative sequence or in the declarations of a package spec. This | |
5467 | pragma affects all subsequent root tagged types declared in the declaration | |
5468 | sequence, and specifies that no stream routines be generated. The form with | |
5469 | an argument (for which there is also a corresponding aspect) specifies a | |
5470 | single root tagged type for which stream routines are not to be generated. | |
64d5610f | 5471 | |
b71d4b62 RA |
5472 | Once the pragma has been given for a particular root tagged type, all subtypes |
5473 | and derived types of this type inherit the pragma automatically, so the effect | |
5474 | applies to a complete hierarchy (this is necessary to deal with the class-wide | |
5475 | dispatching versions of the stream routines). | |
64d5610f | 5476 | |
b71d4b62 RA |
5477 | When pragmas @code{Discard_Names} and @code{No_Tagged_Streams} are simultaneously |
5478 | applied to a tagged type its Expanded_Name and External_Tag are initialized | |
5479 | with empty strings. This is useful to avoid exposing entity names at binary | |
5480 | level but has a negative impact on the debuggability of tagged types. | |
64d5610f | 5481 | |
b71d4b62 RA |
5482 | @node Pragma Normalize_Scalars,Pragma Obsolescent,Pragma No_Tagged_Streams,Implementation Defined Pragmas |
5483 | @anchor{gnat_rm/implementation_defined_pragmas pragma-normalize-scalars}@anchor{ad} | |
5484 | @section Pragma Normalize_Scalars | |
64d5610f ML |
5485 | |
5486 | ||
5487 | Syntax: | |
5488 | ||
5489 | @example | |
b71d4b62 | 5490 | pragma Normalize_Scalars; |
64d5610f ML |
5491 | @end example |
5492 | ||
b71d4b62 RA |
5493 | This is a language defined pragma which is fully implemented in GNAT. The |
5494 | effect is to cause all scalar objects that are not otherwise initialized | |
5495 | to be initialized. The initial values are implementation dependent and | |
5496 | are as follows: | |
64d5610f | 5497 | |
64d5610f | 5498 | |
b71d4b62 | 5499 | @table @asis |
64d5610f | 5500 | |
b71d4b62 | 5501 | @item `Standard.Character' |
64d5610f | 5502 | |
b71d4b62 RA |
5503 | Objects whose root type is Standard.Character are initialized to |
5504 | Character’Last unless the subtype range excludes NUL (in which case | |
5505 | NUL is used). This choice will always generate an invalid value if | |
5506 | one exists. | |
64d5610f | 5507 | |
b71d4b62 | 5508 | @item `Standard.Wide_Character' |
64d5610f | 5509 | |
b71d4b62 RA |
5510 | Objects whose root type is Standard.Wide_Character are initialized to |
5511 | Wide_Character’Last unless the subtype range excludes NUL (in which case | |
5512 | NUL is used). This choice will always generate an invalid value if | |
5513 | one exists. | |
64d5610f | 5514 | |
b71d4b62 | 5515 | @item `Standard.Wide_Wide_Character' |
64d5610f | 5516 | |
b71d4b62 RA |
5517 | Objects whose root type is Standard.Wide_Wide_Character are initialized to |
5518 | the invalid value 16#FFFF_FFFF# unless the subtype range excludes NUL (in | |
5519 | which case NUL is used). This choice will always generate an invalid value if | |
5520 | one exists. | |
64d5610f | 5521 | |
b71d4b62 | 5522 | @item `Integer types' |
64d5610f | 5523 | |
b71d4b62 RA |
5524 | Objects of an integer type are treated differently depending on whether |
5525 | negative values are present in the subtype. If no negative values are | |
5526 | present, then all one bits is used as the initial value except in the | |
5527 | special case where zero is excluded from the subtype, in which case | |
5528 | all zero bits are used. This choice will always generate an invalid | |
5529 | value if one exists. | |
64d5610f | 5530 | |
b71d4b62 RA |
5531 | For subtypes with negative values present, the largest negative number |
5532 | is used, except in the unusual case where this largest negative number | |
5533 | is in the subtype, and the largest positive number is not, in which case | |
5534 | the largest positive value is used. This choice will always generate | |
5535 | an invalid value if one exists. | |
64d5610f | 5536 | |
b71d4b62 | 5537 | @item `Floating-Point Types' |
64d5610f | 5538 | |
b71d4b62 RA |
5539 | Objects of all floating-point types are initialized to all 1-bits. For |
5540 | standard IEEE format, this corresponds to a NaN (not a number) which is | |
5541 | indeed an invalid value. | |
64d5610f | 5542 | |
b71d4b62 | 5543 | @item `Fixed-Point Types' |
64d5610f | 5544 | |
b71d4b62 RA |
5545 | Objects of all fixed-point types are treated as described above for integers, |
5546 | with the rules applying to the underlying integer value used to represent | |
5547 | the fixed-point value. | |
64d5610f | 5548 | |
b71d4b62 | 5549 | @item `Modular types' |
64d5610f ML |
5550 | |
5551 | Objects of a modular type are initialized to all one bits, except in | |
5552 | the special case where zero is excluded from the subtype, in which | |
5553 | case all zero bits are used. This choice will always generate an | |
5554 | invalid value if one exists. | |
5555 | ||
5556 | @item `Enumeration types' | |
5557 | ||
5558 | Objects of an enumeration type are initialized to all one-bits, i.e., to | |
5559 | the value @code{2 ** typ'Size - 1} unless the subtype excludes the literal | |
5560 | whose Pos value is zero, in which case a code of zero is used. This choice | |
5561 | will always generate an invalid value if one exists. | |
5562 | @end table | |
5563 | ||
5564 | @node Pragma Obsolescent,Pragma Optimize_Alignment,Pragma Normalize_Scalars,Implementation Defined Pragmas | |
b71d4b62 | 5565 | @anchor{gnat_rm/implementation_defined_pragmas id28}@anchor{ae}@anchor{gnat_rm/implementation_defined_pragmas pragma-obsolescent}@anchor{af} |
64d5610f ML |
5566 | @section Pragma Obsolescent |
5567 | ||
5568 | ||
5569 | Syntax: | |
5570 | ||
5571 | @example | |
5572 | pragma Obsolescent; | |
5573 | ||
5574 | pragma Obsolescent ( | |
5575 | [Message =>] static_string_EXPRESSION | |
5576 | [,[Version =>] Ada_05]); | |
5577 | ||
5578 | pragma Obsolescent ( | |
5579 | [Entity =>] NAME | |
5580 | [,[Message =>] static_string_EXPRESSION | |
5581 | [,[Version =>] Ada_05]]); | |
5582 | @end example | |
5583 | ||
5584 | This pragma can occur immediately following a declaration of an entity, | |
5585 | including the case of a record component. If no Entity argument is present, | |
5586 | then this declaration is the one to which the pragma applies. If an Entity | |
5587 | parameter is present, it must either match the name of the entity in this | |
5588 | declaration, or alternatively, the pragma can immediately follow an enumeration | |
5589 | type declaration, where the Entity argument names one of the enumeration | |
5590 | literals. | |
5591 | ||
5592 | This pragma is used to indicate that the named entity | |
5593 | is considered obsolescent and should not be used. Typically this is | |
5594 | used when an API must be modified by eventually removing or modifying | |
5595 | existing subprograms or other entities. The pragma can be used at an | |
5596 | intermediate stage when the entity is still present, but will be | |
5597 | removed later. | |
5598 | ||
5599 | The effect of this pragma is to output a warning message on a reference to | |
5600 | an entity thus marked that the subprogram is obsolescent if the appropriate | |
5601 | warning option in the compiler is activated. If the @code{Message} parameter is | |
5602 | present, then a second warning message is given containing this text. In | |
5603 | addition, a reference to the entity is considered to be a violation of pragma | |
5604 | @code{Restrictions (No_Obsolescent_Features)}. | |
5605 | ||
5606 | This pragma can also be used as a program unit pragma for a package, | |
5607 | in which case the entity name is the name of the package, and the | |
5608 | pragma indicates that the entire package is considered | |
5609 | obsolescent. In this case a client @code{with}ing such a package | |
5610 | violates the restriction, and the @code{with} clause is | |
5611 | flagged with warnings if the warning option is set. | |
5612 | ||
5613 | If the @code{Version} parameter is present (which must be exactly | |
5614 | the identifier @code{Ada_05}, no other argument is allowed), then the | |
5615 | indication of obsolescence applies only when compiling in Ada 2005 | |
5616 | mode. This is primarily intended for dealing with the situations | |
5617 | in the predefined library where subprograms or packages | |
5618 | have become defined as obsolescent in Ada 2005 | |
5619 | (e.g., in @code{Ada.Characters.Handling}), but may be used anywhere. | |
5620 | ||
5621 | The following examples show typical uses of this pragma: | |
5622 | ||
5623 | @example | |
5624 | package p is | |
5625 | pragma Obsolescent (p, Message => "use pp instead of p"); | |
5626 | end p; | |
5627 | ||
5628 | package q is | |
5629 | procedure q2; | |
5630 | pragma Obsolescent ("use q2new instead"); | |
5631 | ||
5632 | type R is new integer; | |
5633 | pragma Obsolescent | |
5634 | (Entity => R, | |
5635 | Message => "use RR in Ada 2005", | |
5636 | Version => Ada_05); | |
5637 | ||
5638 | type M is record | |
5639 | F1 : Integer; | |
5640 | F2 : Integer; | |
5641 | pragma Obsolescent; | |
5642 | F3 : Integer; | |
5643 | end record; | |
5644 | ||
5645 | type E is (a, bc, 'd', quack); | |
5646 | pragma Obsolescent (Entity => bc) | |
5647 | pragma Obsolescent (Entity => 'd') | |
5648 | ||
5649 | function "+" | |
5650 | (a, b : character) return character; | |
5651 | pragma Obsolescent (Entity => "+"); | |
5652 | end; | |
5653 | @end example | |
5654 | ||
5655 | Note that, as for all pragmas, if you use a pragma argument identifier, | |
5656 | then all subsequent parameters must also use a pragma argument identifier. | |
5657 | So if you specify @code{Entity =>} for the @code{Entity} argument, and a @code{Message} | |
5658 | argument is present, it must be preceded by @code{Message =>}. | |
5659 | ||
5660 | @node Pragma Optimize_Alignment,Pragma Ordered,Pragma Obsolescent,Implementation Defined Pragmas | |
b71d4b62 | 5661 | @anchor{gnat_rm/implementation_defined_pragmas pragma-optimize-alignment}@anchor{b0} |
64d5610f ML |
5662 | @section Pragma Optimize_Alignment |
5663 | ||
5664 | ||
5665 | @geindex Alignment | |
5666 | @geindex default settings | |
5667 | ||
5668 | Syntax: | |
5669 | ||
5670 | @example | |
5671 | pragma Optimize_Alignment (TIME | SPACE | OFF); | |
5672 | @end example | |
5673 | ||
5674 | This is a configuration pragma which affects the choice of default alignments | |
5675 | for types and objects where no alignment is explicitly specified. There is a | |
5676 | time/space trade-off in the selection of these values. Large alignments result | |
5677 | in more efficient code, at the expense of larger data space, since sizes have | |
5678 | to be increased to match these alignments. Smaller alignments save space, but | |
5679 | the access code is slower. The normal choice of default alignments for types | |
5680 | and individual alignment promotions for objects (which is what you get if you | |
5681 | do not use this pragma, or if you use an argument of OFF), tries to balance | |
5682 | these two requirements. | |
5683 | ||
5684 | Specifying SPACE causes smaller default alignments to be chosen in two cases. | |
5685 | First any packed record is given an alignment of 1. Second, if a size is given | |
5686 | for the type, then the alignment is chosen to avoid increasing this size. For | |
5687 | example, consider: | |
5688 | ||
5689 | @example | |
5690 | type R is record | |
5691 | X : Integer; | |
5692 | Y : Character; | |
5693 | end record; | |
5694 | ||
5695 | for R'Size use 5*8; | |
5696 | @end example | |
5697 | ||
5698 | In the default mode, this type gets an alignment of 4, so that access to the | |
5699 | Integer field X are efficient. But this means that objects of the type end up | |
5700 | with a size of 8 bytes. This is a valid choice, since sizes of objects are | |
5701 | allowed to be bigger than the size of the type, but it can waste space if for | |
5702 | example fields of type R appear in an enclosing record. If the above type is | |
5703 | compiled in @code{Optimize_Alignment (Space)} mode, the alignment is set to 1. | |
5704 | ||
5705 | However, there is one case in which SPACE is ignored. If a variable length | |
5706 | record (that is a discriminated record with a component which is an array | |
5707 | whose length depends on a discriminant), has a pragma Pack, then it is not | |
5708 | in general possible to set the alignment of such a record to one, so the | |
5709 | pragma is ignored in this case (with a warning). | |
5710 | ||
5711 | Specifying SPACE also disables alignment promotions for standalone objects, | |
5712 | which occur when the compiler increases the alignment of a specific object | |
5713 | without changing the alignment of its type. | |
5714 | ||
5715 | Specifying SPACE also disables component reordering in unpacked record types, | |
5716 | which can result in larger sizes in order to meet alignment requirements. | |
5717 | ||
5718 | Specifying TIME causes larger default alignments to be chosen in the case of | |
5719 | small types with sizes that are not a power of 2. For example, consider: | |
5720 | ||
5721 | @example | |
5722 | type R is record | |
5723 | A : Character; | |
5724 | B : Character; | |
5725 | C : Boolean; | |
5726 | end record; | |
5727 | ||
5728 | pragma Pack (R); | |
5729 | for R'Size use 17; | |
5730 | @end example | |
5731 | ||
5732 | The default alignment for this record is normally 1, but if this type is | |
5733 | compiled in @code{Optimize_Alignment (Time)} mode, then the alignment is set | |
5734 | to 4, which wastes space for objects of the type, since they are now 4 bytes | |
5735 | long, but results in more efficient access when the whole record is referenced. | |
5736 | ||
5737 | As noted above, this is a configuration pragma, and there is a requirement | |
5738 | that all units in a partition be compiled with a consistent setting of the | |
5739 | optimization setting. This would normally be achieved by use of a configuration | |
5740 | pragma file containing the appropriate setting. The exception to this rule is | |
5741 | that units with an explicit configuration pragma in the same file as the source | |
5742 | unit are excluded from the consistency check, as are all predefined units. The | |
5743 | latter are compiled by default in pragma Optimize_Alignment (Off) mode if no | |
5744 | pragma appears at the start of the file. | |
5745 | ||
5746 | @node Pragma Ordered,Pragma Overflow_Mode,Pragma Optimize_Alignment,Implementation Defined Pragmas | |
b71d4b62 | 5747 | @anchor{gnat_rm/implementation_defined_pragmas pragma-ordered}@anchor{b1} |
64d5610f ML |
5748 | @section Pragma Ordered |
5749 | ||
5750 | ||
5751 | Syntax: | |
5752 | ||
5753 | @example | |
5754 | pragma Ordered (enumeration_first_subtype_LOCAL_NAME); | |
5755 | @end example | |
5756 | ||
5757 | Most enumeration types are from a conceptual point of view unordered. | |
5758 | For example, consider: | |
5759 | ||
5760 | @example | |
5761 | type Color is (Red, Blue, Green, Yellow); | |
5762 | @end example | |
5763 | ||
5764 | By Ada semantics @code{Blue > Red} and @code{Green > Blue}, | |
5765 | but really these relations make no sense; the enumeration type merely | |
5766 | specifies a set of possible colors, and the order is unimportant. | |
5767 | ||
5768 | For unordered enumeration types, it is generally a good idea if | |
5769 | clients avoid comparisons (other than equality or inequality) and | |
5770 | explicit ranges. (A `client' is a unit where the type is referenced, | |
5771 | other than the unit where the type is declared, its body, and its subunits.) | |
5772 | For example, if code buried in some client says: | |
5773 | ||
5774 | @example | |
5775 | if Current_Color < Yellow then ... | |
5776 | if Current_Color in Blue .. Green then ... | |
5777 | @end example | |
5778 | ||
5779 | then the client code is relying on the order, which is undesirable. | |
5780 | It makes the code hard to read and creates maintenance difficulties if | |
5781 | entries have to be added to the enumeration type. Instead, | |
5782 | the code in the client should list the possibilities, or an | |
5783 | appropriate subtype should be declared in the unit that declares | |
5784 | the original enumeration type. E.g., the following subtype could | |
5785 | be declared along with the type @code{Color}: | |
5786 | ||
5787 | @example | |
5788 | subtype RBG is Color range Red .. Green; | |
5789 | @end example | |
5790 | ||
5791 | and then the client could write: | |
5792 | ||
5793 | @example | |
5794 | if Current_Color in RBG then ... | |
5795 | if Current_Color = Blue or Current_Color = Green then ... | |
5796 | @end example | |
5797 | ||
5798 | However, some enumeration types are legitimately ordered from a conceptual | |
5799 | point of view. For example, if you declare: | |
5800 | ||
5801 | @example | |
5802 | type Day is (Mon, Tue, Wed, Thu, Fri, Sat, Sun); | |
5803 | @end example | |
5804 | ||
5805 | then the ordering imposed by the language is reasonable, and | |
5806 | clients can depend on it, writing for example: | |
5807 | ||
5808 | @example | |
5809 | if D in Mon .. Fri then ... | |
5810 | if D < Wed then ... | |
5811 | @end example | |
5812 | ||
5813 | The pragma `Ordered' is provided to mark enumeration types that | |
5814 | are conceptually ordered, alerting the reader that clients may depend | |
5815 | on the ordering. GNAT provides a pragma to mark enumerations as ordered | |
5816 | rather than one to mark them as unordered, since in our experience, | |
5817 | the great majority of enumeration types are conceptually unordered. | |
5818 | ||
5819 | The types @code{Boolean}, @code{Character}, @code{Wide_Character}, | |
5820 | and @code{Wide_Wide_Character} | |
5821 | are considered to be ordered types, so each is declared with a | |
5822 | pragma @code{Ordered} in package @code{Standard}. | |
5823 | ||
5824 | Normally pragma @code{Ordered} serves only as documentation and a guide for | |
5825 | coding standards, but GNAT provides a warning switch `-gnatw.u' that | |
5826 | requests warnings for inappropriate uses (comparisons and explicit | |
5827 | subranges) for unordered types. If this switch is used, then any | |
5828 | enumeration type not marked with pragma @code{Ordered} will be considered | |
5829 | as unordered, and will generate warnings for inappropriate uses. | |
5830 | ||
5831 | Note that generic types are not considered ordered or unordered (since the | |
5832 | template can be instantiated for both cases), so we never generate warnings | |
5833 | for the case of generic enumerated types. | |
5834 | ||
5835 | For additional information please refer to the description of the | |
5836 | `-gnatw.u' switch in the GNAT User’s Guide. | |
5837 | ||
5838 | @node Pragma Overflow_Mode,Pragma Overriding_Renamings,Pragma Ordered,Implementation Defined Pragmas | |
b71d4b62 | 5839 | @anchor{gnat_rm/implementation_defined_pragmas pragma-overflow-mode}@anchor{b2} |
64d5610f ML |
5840 | @section Pragma Overflow_Mode |
5841 | ||
5842 | ||
5843 | Syntax: | |
5844 | ||
5845 | @example | |
5846 | pragma Overflow_Mode | |
5847 | ( [General =>] MODE | |
5848 | [,[Assertions =>] MODE]); | |
5849 | ||
5850 | MODE ::= STRICT | MINIMIZED | ELIMINATED | |
5851 | @end example | |
5852 | ||
5853 | This pragma sets the current overflow mode to the given setting. For details | |
5854 | of the meaning of these modes, please refer to the | |
5855 | ‘Overflow Check Handling in GNAT’ appendix in the | |
5856 | GNAT User’s Guide. If only the @code{General} parameter is present, | |
5857 | the given mode applies to all expressions. If both parameters are present, | |
5858 | the @code{General} mode applies to expressions outside assertions, and | |
5859 | the @code{Eliminated} mode applies to expressions within assertions. | |
5860 | ||
5861 | The case of the @code{MODE} parameter is ignored, | |
5862 | so @code{MINIMIZED}, @code{Minimized} and | |
5863 | @code{minimized} all have the same effect. | |
5864 | ||
5865 | The @code{Overflow_Mode} pragma has the same scoping and placement | |
5866 | rules as pragma @code{Suppress}, so it can occur either as a | |
5867 | configuration pragma, specifying a default for the whole | |
5868 | program, or in a declarative scope, where it applies to the | |
5869 | remaining declarations and statements in that scope. | |
5870 | ||
5871 | The pragma @code{Suppress (Overflow_Check)} suppresses | |
5872 | overflow checking, but does not affect the overflow mode. | |
5873 | ||
5874 | The pragma @code{Unsuppress (Overflow_Check)} unsuppresses (enables) | |
5875 | overflow checking, but does not affect the overflow mode. | |
5876 | ||
6f089469 | 5877 | @node Pragma Overriding_Renamings,Pragma Part_Of,Pragma Overflow_Mode,Implementation Defined Pragmas |
b71d4b62 | 5878 | @anchor{gnat_rm/implementation_defined_pragmas pragma-overriding-renamings}@anchor{b3} |
64d5610f ML |
5879 | @section Pragma Overriding_Renamings |
5880 | ||
5881 | ||
5882 | @geindex Rational profile | |
5883 | ||
5884 | @geindex Rational compatibility | |
5885 | ||
5886 | Syntax: | |
5887 | ||
5888 | @example | |
5889 | pragma Overriding_Renamings; | |
5890 | @end example | |
5891 | ||
5892 | This is a GNAT configuration pragma to simplify porting | |
5893 | legacy code accepted by the Rational | |
5894 | Ada compiler. In the presence of this pragma, a renaming declaration that | |
5895 | renames an inherited operation declared in the same scope is legal if selected | |
5896 | notation is used as in: | |
5897 | ||
5898 | @example | |
5899 | pragma Overriding_Renamings; | |
5900 | ... | |
5901 | package R is | |
5902 | function F (..); | |
5903 | ... | |
5904 | function F (..) renames R.F; | |
5905 | end R; | |
5906 | @end example | |
5907 | ||
5908 | even though | |
5909 | RM 8.3 (15) stipulates that an overridden operation is not visible within the | |
5910 | declaration of the overriding operation. | |
5911 | ||
6f089469 | 5912 | @node Pragma Part_Of,Pragma Partition_Elaboration_Policy,Pragma Overriding_Renamings,Implementation Defined Pragmas |
b71d4b62 | 5913 | @anchor{gnat_rm/implementation_defined_pragmas id29}@anchor{b4}@anchor{gnat_rm/implementation_defined_pragmas pragma-part-of}@anchor{b5} |
6f089469 | 5914 | @section Pragma Part_Of |
64d5610f ML |
5915 | |
5916 | ||
5917 | Syntax: | |
5918 | ||
5919 | @example | |
6f089469 | 5920 | pragma Part_Of (ABSTRACT_STATE); |
64d5610f | 5921 | |
6f089469 | 5922 | ABSTRACT_STATE ::= NAME |
64d5610f ML |
5923 | @end example |
5924 | ||
6f089469 RD |
5925 | For the semantics of this pragma, see the entry for aspect @code{Part_Of} in the |
5926 | SPARK 2014 Reference Manual, section 7.2.6. | |
64d5610f | 5927 | |
6f089469 | 5928 | @node Pragma Partition_Elaboration_Policy,Pragma Passive,Pragma Part_Of,Implementation Defined Pragmas |
b71d4b62 | 5929 | @anchor{gnat_rm/implementation_defined_pragmas pragma-partition-elaboration-policy}@anchor{b6} |
6f089469 | 5930 | @section Pragma Partition_Elaboration_Policy |
64d5610f ML |
5931 | |
5932 | ||
5933 | Syntax: | |
5934 | ||
5935 | @example | |
6f089469 | 5936 | pragma Partition_Elaboration_Policy (POLICY_IDENTIFIER); |
64d5610f | 5937 | |
6f089469 | 5938 | POLICY_IDENTIFIER ::= Concurrent | Sequential |
64d5610f ML |
5939 | @end example |
5940 | ||
6f089469 RD |
5941 | This pragma is standard in Ada 2005, but is available in all earlier |
5942 | versions of Ada as an implementation-defined pragma. | |
5943 | See Ada 2012 Reference Manual for details. | |
64d5610f | 5944 | |
6f089469 | 5945 | @node Pragma Passive,Pragma Persistent_BSS,Pragma Partition_Elaboration_Policy,Implementation Defined Pragmas |
b71d4b62 | 5946 | @anchor{gnat_rm/implementation_defined_pragmas pragma-passive}@anchor{b7} |
64d5610f ML |
5947 | @section Pragma Passive |
5948 | ||
5949 | ||
5950 | Syntax: | |
5951 | ||
5952 | @example | |
5953 | pragma Passive [(Semaphore | No)]; | |
5954 | @end example | |
5955 | ||
5956 | Syntax checked, but otherwise ignored by GNAT. This is recognized for | |
5957 | compatibility with DEC Ada 83 implementations, where it is used within a | |
5958 | task definition to request that a task be made passive. If the argument | |
5959 | @code{Semaphore} is present, or the argument is omitted, then DEC Ada 83 | |
5960 | treats the pragma as an assertion that the containing task is passive | |
5961 | and that optimization of context switch with this task is permitted and | |
5962 | desired. If the argument @code{No} is present, the task must not be | |
5963 | optimized. GNAT does not attempt to optimize any tasks in this manner | |
5964 | (since protected objects are available in place of passive tasks). | |
5965 | ||
5966 | For more information on the subject of passive tasks, see the section | |
5967 | ‘Passive Task Optimization’ in the GNAT Users Guide. | |
5968 | ||
5969 | @node Pragma Persistent_BSS,Pragma Post,Pragma Passive,Implementation Defined Pragmas | |
b71d4b62 | 5970 | @anchor{gnat_rm/implementation_defined_pragmas id30}@anchor{b8}@anchor{gnat_rm/implementation_defined_pragmas pragma-persistent-bss}@anchor{b9} |
64d5610f ML |
5971 | @section Pragma Persistent_BSS |
5972 | ||
5973 | ||
5974 | Syntax: | |
5975 | ||
5976 | @example | |
5977 | pragma Persistent_BSS [(LOCAL_NAME)] | |
5978 | @end example | |
5979 | ||
5980 | This pragma allows selected objects to be placed in the @code{.persistent_bss} | |
5981 | section. On some targets the linker and loader provide for special | |
5982 | treatment of this section, allowing a program to be reloaded without | |
5983 | affecting the contents of this data (hence the name persistent). | |
5984 | ||
5985 | There are two forms of usage. If an argument is given, it must be the | |
5986 | local name of a library-level object, with no explicit initialization | |
5987 | and whose type is potentially persistent. If no argument is given, then | |
5988 | the pragma is a configuration pragma, and applies to all library-level | |
5989 | objects with no explicit initialization of potentially persistent types. | |
5990 | ||
5991 | A potentially persistent type is a scalar type, or an untagged, | |
5992 | non-discriminated record, all of whose components have no explicit | |
5993 | initialization and are themselves of a potentially persistent type, | |
5994 | or an array, all of whose constraints are static, and whose component | |
5995 | type is potentially persistent. | |
5996 | ||
5997 | If this pragma is used on a target where this feature is not supported, | |
5998 | then the pragma will be ignored. See also @code{pragma Linker_Section}. | |
5999 | ||
6000 | @node Pragma Post,Pragma Postcondition,Pragma Persistent_BSS,Implementation Defined Pragmas | |
b71d4b62 | 6001 | @anchor{gnat_rm/implementation_defined_pragmas pragma-post}@anchor{ba} |
64d5610f ML |
6002 | @section Pragma Post |
6003 | ||
6004 | ||
6005 | @geindex Post | |
6006 | ||
6007 | @geindex Checks | |
6008 | @geindex postconditions | |
6009 | ||
6010 | Syntax: | |
6011 | ||
6012 | @example | |
6013 | pragma Post (Boolean_Expression); | |
6014 | @end example | |
6015 | ||
6016 | The @code{Post} pragma is intended to be an exact replacement for | |
6017 | the language-defined | |
6018 | @code{Post} aspect, and shares its restrictions and semantics. | |
6019 | It must appear either immediately following the corresponding | |
6020 | subprogram declaration (only other pragmas may intervene), or | |
6021 | if there is no separate subprogram declaration, then it can | |
6022 | appear at the start of the declarations in a subprogram body | |
6023 | (preceded only by other pragmas). | |
6024 | ||
6025 | @node Pragma Postcondition,Pragma Post_Class,Pragma Post,Implementation Defined Pragmas | |
b71d4b62 | 6026 | @anchor{gnat_rm/implementation_defined_pragmas pragma-postcondition}@anchor{bb} |
64d5610f ML |
6027 | @section Pragma Postcondition |
6028 | ||
6029 | ||
6030 | @geindex Postcondition | |
6031 | ||
6032 | @geindex Checks | |
6033 | @geindex postconditions | |
6034 | ||
6035 | Syntax: | |
6036 | ||
6037 | @example | |
6038 | pragma Postcondition ( | |
6039 | [Check =>] Boolean_Expression | |
6040 | [,[Message =>] String_Expression]); | |
6041 | @end example | |
6042 | ||
6043 | The @code{Postcondition} pragma allows specification of automatic | |
6044 | postcondition checks for subprograms. These checks are similar to | |
6045 | assertions, but are automatically inserted just prior to the return | |
6046 | statements of the subprogram with which they are associated (including | |
6047 | implicit returns at the end of procedure bodies and associated | |
6048 | exception handlers). | |
6049 | ||
6050 | In addition, the boolean expression which is the condition which | |
6051 | must be true may contain references to function’Result in the case | |
6052 | of a function to refer to the returned value. | |
6053 | ||
6054 | @code{Postcondition} pragmas may appear either immediately following the | |
6055 | (separate) declaration of a subprogram, or at the start of the | |
6056 | declarations of a subprogram body. Only other pragmas may intervene | |
6057 | (that is appear between the subprogram declaration and its | |
6058 | postconditions, or appear before the postcondition in the | |
6059 | declaration sequence in a subprogram body). In the case of a | |
6060 | postcondition appearing after a subprogram declaration, the | |
6061 | formal arguments of the subprogram are visible, and can be | |
6062 | referenced in the postcondition expressions. | |
6063 | ||
6064 | The postconditions are collected and automatically tested just | |
6065 | before any return (implicit or explicit) in the subprogram body. | |
6066 | A postcondition is only recognized if postconditions are active | |
6067 | at the time the pragma is encountered. The compiler switch `gnata' | |
6068 | turns on all postconditions by default, and pragma @code{Check_Policy} | |
6069 | with an identifier of @code{Postcondition} can also be used to | |
6070 | control whether postconditions are active. | |
6071 | ||
6072 | The general approach is that postconditions are placed in the spec | |
6073 | if they represent functional aspects which make sense to the client. | |
6074 | For example we might have: | |
6075 | ||
6076 | @example | |
6077 | function Direction return Integer; | |
6078 | pragma Postcondition | |
6079 | (Direction'Result = +1 | |
6080 | or else | |
6081 | Direction'Result = -1); | |
6082 | @end example | |
6083 | ||
6084 | which serves to document that the result must be +1 or -1, and | |
6085 | will test that this is the case at run time if postcondition | |
6086 | checking is active. | |
6087 | ||
6088 | Postconditions within the subprogram body can be used to | |
6089 | check that some internal aspect of the implementation, | |
6090 | not visible to the client, is operating as expected. | |
6091 | For instance if a square root routine keeps an internal | |
6092 | counter of the number of times it is called, then we | |
6093 | might have the following postcondition: | |
6094 | ||
6095 | @example | |
6096 | Sqrt_Calls : Natural := 0; | |
6097 | ||
6098 | function Sqrt (Arg : Float) return Float is | |
6099 | pragma Postcondition | |
6100 | (Sqrt_Calls = Sqrt_Calls'Old + 1); | |
6101 | ... | |
6102 | end Sqrt | |
6103 | @end example | |
6104 | ||
6105 | As this example, shows, the use of the @code{Old} attribute | |
6106 | is often useful in postconditions to refer to the state on | |
6107 | entry to the subprogram. | |
6108 | ||
6109 | Note that postconditions are only checked on normal returns | |
6110 | from the subprogram. If an abnormal return results from | |
6111 | raising an exception, then the postconditions are not checked. | |
6112 | ||
6113 | If a postcondition fails, then the exception | |
6114 | @code{System.Assertions.Assert_Failure} is raised. If | |
6115 | a message argument was supplied, then the given string | |
6116 | will be used as the exception message. If no message | |
6117 | argument was supplied, then the default message has | |
6118 | the form “Postcondition failed at file_name:line”. The | |
6119 | exception is raised in the context of the subprogram | |
6120 | body, so it is possible to catch postcondition failures | |
6121 | within the subprogram body itself. | |
6122 | ||
6123 | Within a package spec, normal visibility rules | |
6124 | in Ada would prevent forward references within a | |
6125 | postcondition pragma to functions defined later in | |
6126 | the same package. This would introduce undesirable | |
6127 | ordering constraints. To avoid this problem, all | |
6128 | postcondition pragmas are analyzed at the end of | |
6129 | the package spec, allowing forward references. | |
6130 | ||
6131 | The following example shows that this even allows | |
6132 | mutually recursive postconditions as in: | |
6133 | ||
6134 | @example | |
6135 | package Parity_Functions is | |
6136 | function Odd (X : Natural) return Boolean; | |
6137 | pragma Postcondition | |
6138 | (Odd'Result = | |
6139 | (x = 1 | |
6140 | or else | |
6141 | (x /= 0 and then Even (X - 1)))); | |
6142 | ||
6143 | function Even (X : Natural) return Boolean; | |
6144 | pragma Postcondition | |
6145 | (Even'Result = | |
6146 | (x = 0 | |
6147 | or else | |
6148 | (x /= 1 and then Odd (X - 1)))); | |
6149 | ||
6150 | end Parity_Functions; | |
6151 | @end example | |
6152 | ||
6153 | There are no restrictions on the complexity or form of | |
6154 | conditions used within @code{Postcondition} pragmas. | |
6155 | The following example shows that it is even possible | |
6156 | to verify performance behavior. | |
6157 | ||
6158 | @example | |
6159 | package Sort is | |
6160 | ||
6161 | Performance : constant Float; | |
6162 | -- Performance constant set by implementation | |
6163 | -- to match target architecture behavior. | |
6164 | ||
6165 | procedure Treesort (Arg : String); | |
6166 | -- Sorts characters of argument using N*logN sort | |
6167 | pragma Postcondition | |
6168 | (Float (Clock - Clock'Old) <= | |
6169 | Float (Arg'Length) * | |
6170 | log (Float (Arg'Length)) * | |
6171 | Performance); | |
6172 | end Sort; | |
6173 | @end example | |
6174 | ||
6175 | Note: postcondition pragmas associated with subprograms that are | |
6176 | marked as Inline_Always, or those marked as Inline with front-end | |
6177 | inlining (-gnatN option set) are accepted and legality-checked | |
6178 | by the compiler, but are ignored at run-time even if postcondition | |
6179 | checking is enabled. | |
6180 | ||
6181 | Note that pragma @code{Postcondition} differs from the language-defined | |
6182 | @code{Post} aspect (and corresponding @code{Post} pragma) in allowing | |
6183 | multiple occurrences, allowing occurences in the body even if there | |
6184 | is a separate spec, and allowing a second string parameter, and the | |
6185 | use of the pragma identifier @code{Check}. Historically, pragma | |
6186 | @code{Postcondition} was implemented prior to the development of | |
6187 | Ada 2012, and has been retained in its original form for | |
6188 | compatibility purposes. | |
6189 | ||
6190 | @node Pragma Post_Class,Pragma Pre,Pragma Postcondition,Implementation Defined Pragmas | |
b71d4b62 | 6191 | @anchor{gnat_rm/implementation_defined_pragmas pragma-post-class}@anchor{bc} |
64d5610f ML |
6192 | @section Pragma Post_Class |
6193 | ||
6194 | ||
6195 | @geindex Post | |
6196 | ||
6197 | @geindex Checks | |
6198 | @geindex postconditions | |
6199 | ||
6200 | Syntax: | |
6201 | ||
6202 | @example | |
6203 | pragma Post_Class (Boolean_Expression); | |
6204 | @end example | |
6205 | ||
6206 | The @code{Post_Class} pragma is intended to be an exact replacement for | |
6207 | the language-defined | |
6208 | @code{Post'Class} aspect, and shares its restrictions and semantics. | |
6209 | It must appear either immediately following the corresponding | |
6210 | subprogram declaration (only other pragmas may intervene), or | |
6211 | if there is no separate subprogram declaration, then it can | |
6212 | appear at the start of the declarations in a subprogram body | |
6213 | (preceded only by other pragmas). | |
6214 | ||
6215 | Note: This pragma is called @code{Post_Class} rather than | |
6216 | @code{Post'Class} because the latter would not be strictly | |
6217 | conforming to the allowed syntax for pragmas. The motivation | |
6218 | for providing pragmas equivalent to the aspects is to allow a program | |
6219 | to be written using the pragmas, and then compiled if necessary | |
6220 | using an Ada compiler that does not recognize the pragmas or | |
6221 | aspects, but is prepared to ignore the pragmas. The assertion | |
6222 | policy that controls this pragma is @code{Post'Class}, not | |
6223 | @code{Post_Class}. | |
6224 | ||
6225 | @node Pragma Pre,Pragma Precondition,Pragma Post_Class,Implementation Defined Pragmas | |
b71d4b62 | 6226 | @anchor{gnat_rm/implementation_defined_pragmas pragma-pre}@anchor{bd} |
64d5610f ML |
6227 | @section Pragma Pre |
6228 | ||
6229 | ||
6230 | @geindex Pre | |
6231 | ||
6232 | @geindex Checks | |
6233 | @geindex preconditions | |
6234 | ||
6235 | Syntax: | |
6236 | ||
6237 | @example | |
6238 | pragma Pre (Boolean_Expression); | |
6239 | @end example | |
6240 | ||
6241 | The @code{Pre} pragma is intended to be an exact replacement for | |
6242 | the language-defined | |
6243 | @code{Pre} aspect, and shares its restrictions and semantics. | |
6244 | It must appear either immediately following the corresponding | |
6245 | subprogram declaration (only other pragmas may intervene), or | |
6246 | if there is no separate subprogram declaration, then it can | |
6247 | appear at the start of the declarations in a subprogram body | |
6248 | (preceded only by other pragmas). | |
6249 | ||
6250 | @node Pragma Precondition,Pragma Predicate,Pragma Pre,Implementation Defined Pragmas | |
b71d4b62 | 6251 | @anchor{gnat_rm/implementation_defined_pragmas pragma-precondition}@anchor{be} |
64d5610f ML |
6252 | @section Pragma Precondition |
6253 | ||
6254 | ||
6255 | @geindex Preconditions | |
6256 | ||
6257 | @geindex Checks | |
6258 | @geindex preconditions | |
6259 | ||
6260 | Syntax: | |
6261 | ||
6262 | @example | |
6263 | pragma Precondition ( | |
6264 | [Check =>] Boolean_Expression | |
6265 | [,[Message =>] String_Expression]); | |
6266 | @end example | |
6267 | ||
6268 | The @code{Precondition} pragma is similar to @code{Postcondition} | |
6269 | except that the corresponding checks take place immediately upon | |
6270 | entry to the subprogram, and if a precondition fails, the exception | |
6271 | is raised in the context of the caller, and the attribute ‘Result | |
6272 | cannot be used within the precondition expression. | |
6273 | ||
6274 | Otherwise, the placement and visibility rules are identical to those | |
6275 | described for postconditions. The following is an example of use | |
6276 | within a package spec: | |
6277 | ||
6278 | @example | |
6279 | package Math_Functions is | |
6280 | ... | |
6281 | function Sqrt (Arg : Float) return Float; | |
6282 | pragma Precondition (Arg >= 0.0) | |
6283 | ... | |
6284 | end Math_Functions; | |
6285 | @end example | |
6286 | ||
6287 | @code{Precondition} pragmas may appear either immediately following the | |
6288 | (separate) declaration of a subprogram, or at the start of the | |
6289 | declarations of a subprogram body. Only other pragmas may intervene | |
6290 | (that is appear between the subprogram declaration and its | |
6291 | postconditions, or appear before the postcondition in the | |
6292 | declaration sequence in a subprogram body). | |
6293 | ||
6294 | Note: precondition pragmas associated with subprograms that are | |
6295 | marked as Inline_Always, or those marked as Inline with front-end | |
6296 | inlining (-gnatN option set) are accepted and legality-checked | |
6297 | by the compiler, but are ignored at run-time even if precondition | |
6298 | checking is enabled. | |
6299 | ||
6300 | Note that pragma @code{Precondition} differs from the language-defined | |
6301 | @code{Pre} aspect (and corresponding @code{Pre} pragma) in allowing | |
6302 | multiple occurrences, allowing occurences in the body even if there | |
6303 | is a separate spec, and allowing a second string parameter, and the | |
6304 | use of the pragma identifier @code{Check}. Historically, pragma | |
6305 | @code{Precondition} was implemented prior to the development of | |
6306 | Ada 2012, and has been retained in its original form for | |
6307 | compatibility purposes. | |
6308 | ||
6309 | @node Pragma Predicate,Pragma Predicate_Failure,Pragma Precondition,Implementation Defined Pragmas | |
b71d4b62 | 6310 | @anchor{gnat_rm/implementation_defined_pragmas id31}@anchor{bf}@anchor{gnat_rm/implementation_defined_pragmas pragma-predicate}@anchor{c0} |
64d5610f ML |
6311 | @section Pragma Predicate |
6312 | ||
6313 | ||
6314 | Syntax: | |
6315 | ||
6316 | @example | |
6317 | pragma Predicate | |
6318 | ([Entity =>] type_LOCAL_NAME, | |
6319 | [Check =>] EXPRESSION); | |
6320 | @end example | |
6321 | ||
6322 | This pragma (available in all versions of Ada in GNAT) encompasses both | |
6323 | the @code{Static_Predicate} and @code{Dynamic_Predicate} aspects in | |
6324 | Ada 2012. A predicate is regarded as static if it has an allowed form | |
6325 | for @code{Static_Predicate} and is otherwise treated as a | |
6326 | @code{Dynamic_Predicate}. Otherwise, predicates specified by this | |
6327 | pragma behave exactly as described in the Ada 2012 reference manual. | |
6328 | For example, if we have | |
6329 | ||
6330 | @example | |
6331 | type R is range 1 .. 10; | |
6332 | subtype S is R; | |
6333 | pragma Predicate (Entity => S, Check => S not in 4 .. 6); | |
6334 | subtype Q is R | |
6335 | pragma Predicate (Entity => Q, Check => F(Q) or G(Q)); | |
6336 | @end example | |
6337 | ||
6338 | the effect is identical to the following Ada 2012 code: | |
6339 | ||
6340 | @example | |
6341 | type R is range 1 .. 10; | |
6342 | subtype S is R with | |
6343 | Static_Predicate => S not in 4 .. 6; | |
6344 | subtype Q is R with | |
6345 | Dynamic_Predicate => F(Q) or G(Q); | |
6346 | @end example | |
6347 | ||
6348 | Note that there are no pragmas @code{Dynamic_Predicate} | |
6349 | or @code{Static_Predicate}. That is | |
6350 | because these pragmas would affect legality and semantics of | |
6351 | the program and thus do not have a neutral effect if ignored. | |
6352 | The motivation behind providing pragmas equivalent to | |
6353 | corresponding aspects is to allow a program to be written | |
6354 | using the pragmas, and then compiled with a compiler that | |
6355 | will ignore the pragmas. That doesn’t work in the case of | |
6356 | static and dynamic predicates, since if the corresponding | |
6357 | pragmas are ignored, then the behavior of the program is | |
6358 | fundamentally changed (for example a membership test | |
6359 | @code{A in B} would not take into account a predicate | |
6360 | defined for subtype B). When following this approach, the | |
6361 | use of predicates should be avoided. | |
6362 | ||
6363 | @node Pragma Predicate_Failure,Pragma Preelaborable_Initialization,Pragma Predicate,Implementation Defined Pragmas | |
b71d4b62 | 6364 | @anchor{gnat_rm/implementation_defined_pragmas pragma-predicate-failure}@anchor{c1} |
64d5610f ML |
6365 | @section Pragma Predicate_Failure |
6366 | ||
6367 | ||
6368 | Syntax: | |
6369 | ||
6370 | @example | |
6371 | pragma Predicate_Failure | |
6372 | ([Entity =>] type_LOCAL_NAME, | |
6373 | [Message =>] String_Expression); | |
6374 | @end example | |
6375 | ||
6376 | The @code{Predicate_Failure} pragma is intended to be an exact replacement for | |
6377 | the language-defined | |
6378 | @code{Predicate_Failure} aspect, and shares its restrictions and semantics. | |
6379 | ||
6380 | @node Pragma Preelaborable_Initialization,Pragma Prefix_Exception_Messages,Pragma Predicate_Failure,Implementation Defined Pragmas | |
b71d4b62 | 6381 | @anchor{gnat_rm/implementation_defined_pragmas pragma-preelaborable-initialization}@anchor{c2} |
64d5610f ML |
6382 | @section Pragma Preelaborable_Initialization |
6383 | ||
6384 | ||
6385 | Syntax: | |
6386 | ||
6387 | @example | |
6388 | pragma Preelaborable_Initialization (DIRECT_NAME); | |
6389 | @end example | |
6390 | ||
6391 | This pragma is standard in Ada 2005, but is available in all earlier | |
6392 | versions of Ada as an implementation-defined pragma. | |
6393 | See Ada 2012 Reference Manual for details. | |
6394 | ||
6395 | @node Pragma Prefix_Exception_Messages,Pragma Pre_Class,Pragma Preelaborable_Initialization,Implementation Defined Pragmas | |
b71d4b62 | 6396 | @anchor{gnat_rm/implementation_defined_pragmas pragma-prefix-exception-messages}@anchor{c3} |
64d5610f ML |
6397 | @section Pragma Prefix_Exception_Messages |
6398 | ||
6399 | ||
6400 | @geindex Prefix_Exception_Messages | |
6401 | ||
6402 | @geindex exception | |
6403 | ||
6404 | @geindex Exception_Message | |
6405 | ||
6406 | Syntax: | |
6407 | ||
6408 | @example | |
6409 | pragma Prefix_Exception_Messages; | |
6410 | @end example | |
6411 | ||
6412 | This is an implementation-defined configuration pragma that affects the | |
6413 | behavior of raise statements with a message given as a static string | |
6414 | constant (typically a string literal). In such cases, the string will | |
6415 | be automatically prefixed by the name of the enclosing entity (giving | |
6416 | the package and subprogram containing the raise statement). This helps | |
6417 | to identify where messages are coming from, and this mode is automatic | |
6418 | for the run-time library. | |
6419 | ||
6420 | The pragma has no effect if the message is computed with an expression other | |
6421 | than a static string constant, since the assumption in this case is that | |
6422 | the program computes exactly the string it wants. If you still want the | |
6423 | prefixing in this case, you can always call | |
6424 | @code{GNAT.Source_Info.Enclosing_Entity} and prepend the string manually. | |
6425 | ||
6426 | @node Pragma Pre_Class,Pragma Priority_Specific_Dispatching,Pragma Prefix_Exception_Messages,Implementation Defined Pragmas | |
b71d4b62 | 6427 | @anchor{gnat_rm/implementation_defined_pragmas pragma-pre-class}@anchor{c4} |
64d5610f ML |
6428 | @section Pragma Pre_Class |
6429 | ||
6430 | ||
6431 | @geindex Pre_Class | |
6432 | ||
6433 | @geindex Checks | |
6434 | @geindex preconditions | |
6435 | ||
6436 | Syntax: | |
6437 | ||
6438 | @example | |
6439 | pragma Pre_Class (Boolean_Expression); | |
6440 | @end example | |
6441 | ||
6442 | The @code{Pre_Class} pragma is intended to be an exact replacement for | |
6443 | the language-defined | |
6444 | @code{Pre'Class} aspect, and shares its restrictions and semantics. | |
6445 | It must appear either immediately following the corresponding | |
6446 | subprogram declaration (only other pragmas may intervene), or | |
6447 | if there is no separate subprogram declaration, then it can | |
6448 | appear at the start of the declarations in a subprogram body | |
6449 | (preceded only by other pragmas). | |
6450 | ||
6451 | Note: This pragma is called @code{Pre_Class} rather than | |
6452 | @code{Pre'Class} because the latter would not be strictly | |
6453 | conforming to the allowed syntax for pragmas. The motivation | |
6454 | for providing pragmas equivalent to the aspects is to allow a program | |
6455 | to be written using the pragmas, and then compiled if necessary | |
6456 | using an Ada compiler that does not recognize the pragmas or | |
6457 | aspects, but is prepared to ignore the pragmas. The assertion | |
6458 | policy that controls this pragma is @code{Pre'Class}, not | |
6459 | @code{Pre_Class}. | |
6460 | ||
6461 | @node Pragma Priority_Specific_Dispatching,Pragma Profile,Pragma Pre_Class,Implementation Defined Pragmas | |
b71d4b62 | 6462 | @anchor{gnat_rm/implementation_defined_pragmas pragma-priority-specific-dispatching}@anchor{c5} |
64d5610f ML |
6463 | @section Pragma Priority_Specific_Dispatching |
6464 | ||
6465 | ||
6466 | Syntax: | |
6467 | ||
6468 | @example | |
6469 | pragma Priority_Specific_Dispatching ( | |
6470 | POLICY_IDENTIFIER, | |
6471 | first_priority_EXPRESSION, | |
6472 | last_priority_EXPRESSION) | |
6473 | ||
6474 | POLICY_IDENTIFIER ::= | |
6475 | EDF_Across_Priorities | | |
6476 | FIFO_Within_Priorities | | |
6477 | Non_Preemptive_Within_Priorities | | |
6478 | Round_Robin_Within_Priorities | |
6479 | @end example | |
6480 | ||
6481 | This pragma is standard in Ada 2005, but is available in all earlier | |
6482 | versions of Ada as an implementation-defined pragma. | |
6483 | See Ada 2012 Reference Manual for details. | |
6484 | ||
6485 | @node Pragma Profile,Pragma Profile_Warnings,Pragma Priority_Specific_Dispatching,Implementation Defined Pragmas | |
b71d4b62 | 6486 | @anchor{gnat_rm/implementation_defined_pragmas pragma-profile}@anchor{c6} |
64d5610f ML |
6487 | @section Pragma Profile |
6488 | ||
6489 | ||
6490 | Syntax: | |
6491 | ||
6492 | @example | |
6493 | pragma Profile (Ravenscar | Restricted | Rational | Jorvik | | |
6494 | GNAT_Extended_Ravenscar | GNAT_Ravenscar_EDF ); | |
6495 | @end example | |
6496 | ||
6497 | This pragma is standard in Ada 2005, but is available in all earlier | |
6498 | versions of Ada as an implementation-defined pragma. This is a | |
6499 | configuration pragma that establishes a set of configuration pragmas | |
6500 | that depend on the argument. @code{Ravenscar} is standard in Ada 2005. | |
6501 | @code{Jorvik} is standard in Ada 202x. | |
6502 | The other possibilities (@code{Restricted}, @code{Rational}, | |
6503 | @code{GNAT_Extended_Ravenscar}, @code{GNAT_Ravenscar_EDF}) | |
6504 | are implementation-defined. @code{GNAT_Extended_Ravenscar} is an alias for @code{Jorvik}. | |
6505 | ||
6506 | The set of configuration pragmas is defined in the following sections. | |
6507 | ||
6508 | ||
6509 | @itemize * | |
6510 | ||
6511 | @item | |
6512 | Pragma Profile (Ravenscar) | |
6513 | ||
6514 | The @code{Ravenscar} profile is standard in Ada 2005, | |
6515 | but is available in all earlier | |
6516 | versions of Ada as an implementation-defined pragma. This profile | |
6517 | establishes the following set of configuration pragmas: | |
6518 | ||
6519 | ||
6520 | @itemize * | |
6521 | ||
6522 | @item | |
6523 | @code{Task_Dispatching_Policy (FIFO_Within_Priorities)} | |
6524 | ||
6525 | [RM D.2.2] Tasks are dispatched following a preemptive | |
6526 | priority-ordered scheduling policy. | |
6527 | ||
6528 | @item | |
6529 | @code{Locking_Policy (Ceiling_Locking)} | |
6530 | ||
6531 | [RM D.3] While tasks and interrupts execute a protected action, they inherit | |
6532 | the ceiling priority of the corresponding protected object. | |
6533 | ||
6534 | @item | |
6535 | @code{Detect_Blocking} | |
6536 | ||
6537 | This pragma forces the detection of potentially blocking operations within a | |
6538 | protected operation, and to raise Program_Error if that happens. | |
6539 | @end itemize | |
6540 | ||
6541 | plus the following set of restrictions: | |
6542 | ||
6543 | ||
6544 | @itemize * | |
6545 | ||
6546 | @item | |
6547 | @code{Max_Entry_Queue_Length => 1} | |
6548 | ||
6549 | No task can be queued on a protected entry. | |
6550 | ||
6551 | @item | |
6552 | @code{Max_Protected_Entries => 1} | |
6553 | ||
6554 | @item | |
6555 | @code{Max_Task_Entries => 0} | |
6556 | ||
6557 | No rendezvous statements are allowed. | |
6558 | ||
6559 | @item | |
6560 | @code{No_Abort_Statements} | |
6561 | ||
6562 | @item | |
6563 | @code{No_Dynamic_Attachment} | |
6564 | ||
6565 | @item | |
6566 | @code{No_Dynamic_Priorities} | |
6567 | ||
6568 | @item | |
6569 | @code{No_Implicit_Heap_Allocations} | |
6570 | ||
6571 | @item | |
6572 | @code{No_Local_Protected_Objects} | |
6573 | ||
6574 | @item | |
6575 | @code{No_Local_Timing_Events} | |
6576 | ||
6577 | @item | |
6578 | @code{No_Protected_Type_Allocators} | |
6579 | ||
6580 | @item | |
6581 | @code{No_Relative_Delay} | |
6582 | ||
6583 | @item | |
6584 | @code{No_Requeue_Statements} | |
6585 | ||
6586 | @item | |
6587 | @code{No_Select_Statements} | |
6588 | ||
6589 | @item | |
6590 | @code{No_Specific_Termination_Handlers} | |
6591 | ||
6592 | @item | |
6593 | @code{No_Task_Allocators} | |
6594 | ||
6595 | @item | |
6596 | @code{No_Task_Hierarchy} | |
6597 | ||
6598 | @item | |
6599 | @code{No_Task_Termination} | |
6600 | ||
6601 | @item | |
6602 | @code{Simple_Barriers} | |
6603 | @end itemize | |
6604 | ||
6605 | The Ravenscar profile also includes the following restrictions that specify | |
6606 | that there are no semantic dependencies on the corresponding predefined | |
6607 | packages: | |
6608 | ||
6609 | ||
6610 | @itemize * | |
6611 | ||
6612 | @item | |
6613 | @code{No_Dependence => Ada.Asynchronous_Task_Control} | |
6614 | ||
6615 | @item | |
6616 | @code{No_Dependence => Ada.Calendar} | |
6617 | ||
6618 | @item | |
6619 | @code{No_Dependence => Ada.Execution_Time.Group_Budget} | |
6620 | ||
6621 | @item | |
6622 | @code{No_Dependence => Ada.Execution_Time.Timers} | |
6623 | ||
6624 | @item | |
6625 | @code{No_Dependence => Ada.Task_Attributes} | |
6626 | ||
6627 | @item | |
6628 | @code{No_Dependence => System.Multiprocessors.Dispatching_Domains} | |
6629 | @end itemize | |
6630 | ||
6631 | This set of configuration pragmas and restrictions correspond to the | |
6632 | definition of the ‘Ravenscar Profile’ for limited tasking, devised and | |
6633 | published by the @cite{International Real-Time Ada Workshop@comma{} 1997}. | |
6634 | A description is also available at | |
6635 | @indicateurl{http://www-users.cs.york.ac.uk/~burns/ravenscar.ps}. | |
6636 | ||
6637 | The original definition of the profile was revised at subsequent IRTAW | |
6638 | meetings. It has been included in the ISO | |
6639 | @cite{Guide for the Use of the Ada Programming Language in High Integrity Systems}, | |
6640 | and was made part of the Ada 2005 standard. | |
6641 | The formal definition given by | |
6642 | the Ada Rapporteur Group (ARG) can be found in two Ada Issues (AI-249 and | |
6643 | AI-305) available at | |
6644 | @indicateurl{http://www.ada-auth.org/cgi-bin/cvsweb.cgi/ais/ai-00249.txt} and | |
6645 | @indicateurl{http://www.ada-auth.org/cgi-bin/cvsweb.cgi/ais/ai-00305.txt}. | |
6646 | ||
6647 | The above set is a superset of the restrictions provided by pragma | |
6648 | @code{Profile (Restricted)}, it includes six additional restrictions | |
6649 | (@code{Simple_Barriers}, @code{No_Select_Statements}, | |
6650 | @code{No_Calendar}, @code{No_Implicit_Heap_Allocations}, | |
6651 | @code{No_Relative_Delay} and @code{No_Task_Termination}). This means | |
6652 | that pragma @code{Profile (Ravenscar)}, like the pragma | |
6653 | @code{Profile (Restricted)}, | |
6654 | automatically causes the use of a simplified, | |
6655 | more efficient version of the tasking run-time library. | |
6656 | ||
6657 | @item | |
6658 | Pragma Profile (Jorvik) | |
6659 | ||
6660 | @code{Jorvik} is the new profile added to the Ada 202x draft standard, | |
6661 | previously implemented under the name @code{GNAT_Extended_Ravenscar}. | |
6662 | ||
6663 | The @code{No_Implicit_Heap_Allocations} restriction has been replaced | |
6664 | by @code{No_Implicit_Task_Allocations} and | |
6665 | @code{No_Implicit_Protected_Object_Allocations}. | |
6666 | ||
6667 | The @code{Simple_Barriers} restriction has been replaced by | |
6668 | @code{Pure_Barriers}. | |
6669 | ||
6670 | The @code{Max_Protected_Entries}, @code{Max_Entry_Queue_Length}, and | |
6671 | @code{No_Relative_Delay} restrictions have been removed. | |
6672 | ||
6673 | Details on the rationale for @code{Jorvik} and implications for use may be | |
6674 | found in @cite{A New Ravenscar-Based Profile} by P. Rogers, J. Ruiz, | |
6675 | T. Gingold and P. Bernardi, in @cite{Reliable Software Technologies – Ada Europe 2017}, Springer-Verlag Lecture Notes in Computer Science, | |
6676 | Number 10300. | |
6677 | ||
6678 | @item | |
6679 | Pragma Profile (GNAT_Ravenscar_EDF) | |
6680 | ||
6681 | This profile corresponds to the Ravenscar profile but using | |
6682 | EDF_Across_Priority as the Task_Scheduling_Policy. | |
6683 | ||
6684 | @item | |
6685 | Pragma Profile (Restricted) | |
6686 | ||
6687 | This profile corresponds to the GNAT restricted run time. It | |
6688 | establishes the following set of restrictions: | |
6689 | ||
6690 | ||
6691 | @itemize * | |
6692 | ||
6693 | @item | |
6694 | @code{No_Abort_Statements} | |
6695 | ||
6696 | @item | |
6697 | @code{No_Entry_Queue} | |
6698 | ||
6699 | @item | |
6700 | @code{No_Task_Hierarchy} | |
6701 | ||
6702 | @item | |
6703 | @code{No_Task_Allocators} | |
6704 | ||
6705 | @item | |
6706 | @code{No_Dynamic_Priorities} | |
6707 | ||
6708 | @item | |
6709 | @code{No_Terminate_Alternatives} | |
6710 | ||
6711 | @item | |
6712 | @code{No_Dynamic_Attachment} | |
6713 | ||
6714 | @item | |
6715 | @code{No_Protected_Type_Allocators} | |
6716 | ||
6717 | @item | |
6718 | @code{No_Local_Protected_Objects} | |
6719 | ||
6720 | @item | |
6721 | @code{No_Requeue_Statements} | |
6722 | ||
6723 | @item | |
6724 | @code{No_Task_Attributes_Package} | |
6725 | ||
6726 | @item | |
6727 | @code{Max_Asynchronous_Select_Nesting = 0} | |
6728 | ||
6729 | @item | |
6730 | @code{Max_Task_Entries = 0} | |
6731 | ||
6732 | @item | |
6733 | @code{Max_Protected_Entries = 1} | |
6734 | ||
6735 | @item | |
6736 | @code{Max_Select_Alternatives = 0} | |
6737 | @end itemize | |
6738 | ||
6739 | This set of restrictions causes the automatic selection of a simplified | |
6740 | version of the run time that provides improved performance for the | |
6741 | limited set of tasking functionality permitted by this set of restrictions. | |
6742 | ||
6743 | @item | |
6744 | Pragma Profile (Rational) | |
6745 | ||
6746 | The Rational profile is intended to facilitate porting legacy code that | |
6747 | compiles with the Rational APEX compiler, even when the code includes non- | |
6748 | conforming Ada constructs. The profile enables the following three pragmas: | |
6749 | ||
6750 | ||
6751 | @itemize * | |
6752 | ||
6753 | @item | |
6754 | @code{pragma Implicit_Packing} | |
6755 | ||
6756 | @item | |
6757 | @code{pragma Overriding_Renamings} | |
6758 | ||
6759 | @item | |
6760 | @code{pragma Use_VADS_Size} | |
6761 | @end itemize | |
6762 | @end itemize | |
6763 | ||
6764 | @node Pragma Profile_Warnings,Pragma Propagate_Exceptions,Pragma Profile,Implementation Defined Pragmas | |
b71d4b62 | 6765 | @anchor{gnat_rm/implementation_defined_pragmas pragma-profile-warnings}@anchor{c7} |
64d5610f ML |
6766 | @section Pragma Profile_Warnings |
6767 | ||
6768 | ||
6769 | Syntax: | |
6770 | ||
6771 | @example | |
6772 | pragma Profile_Warnings (Ravenscar | Restricted | Rational); | |
6773 | @end example | |
6774 | ||
6775 | This is an implementation-defined pragma that is similar in | |
6776 | effect to @code{pragma Profile} except that instead of | |
6777 | generating @code{Restrictions} pragmas, it generates | |
6778 | @code{Restriction_Warnings} pragmas. The result is that | |
6779 | violations of the profile generate warning messages instead | |
6780 | of error messages. | |
6781 | ||
6782 | @node Pragma Propagate_Exceptions,Pragma Provide_Shift_Operators,Pragma Profile_Warnings,Implementation Defined Pragmas | |
b71d4b62 | 6783 | @anchor{gnat_rm/implementation_defined_pragmas pragma-propagate-exceptions}@anchor{c8} |
64d5610f ML |
6784 | @section Pragma Propagate_Exceptions |
6785 | ||
6786 | ||
6787 | @geindex Interfacing to C++ | |
6788 | ||
6789 | Syntax: | |
6790 | ||
6791 | @example | |
6792 | pragma Propagate_Exceptions; | |
6793 | @end example | |
6794 | ||
6795 | This pragma is now obsolete and, other than generating a warning if warnings | |
6796 | on obsolescent features are enabled, is ignored. | |
6797 | It is retained for compatibility | |
6798 | purposes. It used to be used in connection with optimization of | |
6799 | a now-obsolete mechanism for implementation of exceptions. | |
6800 | ||
6801 | @node Pragma Provide_Shift_Operators,Pragma Psect_Object,Pragma Propagate_Exceptions,Implementation Defined Pragmas | |
b71d4b62 | 6802 | @anchor{gnat_rm/implementation_defined_pragmas pragma-provide-shift-operators}@anchor{c9} |
64d5610f ML |
6803 | @section Pragma Provide_Shift_Operators |
6804 | ||
6805 | ||
6806 | @geindex Shift operators | |
6807 | ||
6808 | Syntax: | |
6809 | ||
6810 | @example | |
6811 | pragma Provide_Shift_Operators (integer_first_subtype_LOCAL_NAME); | |
6812 | @end example | |
6813 | ||
6814 | This pragma can be applied to a first subtype local name that specifies | |
6815 | either an unsigned or signed type. It has the effect of providing the | |
6816 | five shift operators (Shift_Left, Shift_Right, Shift_Right_Arithmetic, | |
6817 | Rotate_Left and Rotate_Right) for the given type. It is similar to | |
6818 | including the function declarations for these five operators, together | |
6819 | with the pragma Import (Intrinsic, …) statements. | |
6820 | ||
6821 | @node Pragma Psect_Object,Pragma Pure_Function,Pragma Provide_Shift_Operators,Implementation Defined Pragmas | |
b71d4b62 | 6822 | @anchor{gnat_rm/implementation_defined_pragmas pragma-psect-object}@anchor{ca} |
64d5610f ML |
6823 | @section Pragma Psect_Object |
6824 | ||
6825 | ||
6826 | Syntax: | |
6827 | ||
6828 | @example | |
6829 | pragma Psect_Object ( | |
6830 | [Internal =>] LOCAL_NAME, | |
6831 | [, [External =>] EXTERNAL_SYMBOL] | |
6832 | [, [Size =>] EXTERNAL_SYMBOL]); | |
6833 | ||
6834 | EXTERNAL_SYMBOL ::= | |
6835 | IDENTIFIER | |
6836 | | static_string_EXPRESSION | |
6837 | @end example | |
6838 | ||
6839 | This pragma is identical in effect to pragma @code{Common_Object}. | |
6840 | ||
6841 | @node Pragma Pure_Function,Pragma Rational,Pragma Psect_Object,Implementation Defined Pragmas | |
b71d4b62 | 6842 | @anchor{gnat_rm/implementation_defined_pragmas id32}@anchor{cb}@anchor{gnat_rm/implementation_defined_pragmas pragma-pure-function}@anchor{cc} |
64d5610f ML |
6843 | @section Pragma Pure_Function |
6844 | ||
6845 | ||
6846 | Syntax: | |
6847 | ||
6848 | @example | |
6849 | pragma Pure_Function ([Entity =>] function_LOCAL_NAME); | |
6850 | @end example | |
6851 | ||
6852 | This pragma appears in the same declarative part as a function | |
6853 | declaration (or a set of function declarations if more than one | |
6854 | overloaded declaration exists, in which case the pragma applies | |
6855 | to all entities). It specifies that the function @code{Entity} is | |
6856 | to be considered pure for the purposes of code generation. This means | |
6857 | that the compiler can assume that there are no side effects, and | |
6858 | in particular that two identical calls produce the same result in | |
6859 | the same context. It also means that the function can be used in | |
6860 | an address clause. | |
6861 | ||
6862 | Note that, quite deliberately, there are no static checks to try | |
6863 | to ensure that this promise is met, so @code{Pure_Function} can be used | |
6864 | with functions that are conceptually pure, even if they do modify | |
6865 | global variables. For example, a square root function that is | |
6866 | instrumented to count the number of times it is called is still | |
6867 | conceptually pure, and can still be optimized, even though it | |
6868 | modifies a global variable (the count). Memo functions are another | |
6869 | example (where a table of previous calls is kept and consulted to | |
6870 | avoid re-computation). | |
6871 | ||
6872 | Note also that the normal rules excluding optimization of subprograms | |
6873 | in pure units (when parameter types are descended from System.Address, | |
6874 | or when the full view of a parameter type is limited), do not apply | |
6875 | for the Pure_Function case. If you explicitly specify Pure_Function, | |
6876 | the compiler may optimize away calls with identical arguments, and | |
6877 | if that results in unexpected behavior, the proper action is not to | |
6878 | use the pragma for subprograms that are not (conceptually) pure. | |
6879 | ||
6880 | Note: Most functions in a @code{Pure} package are automatically pure, and | |
6881 | there is no need to use pragma @code{Pure_Function} for such functions. One | |
6882 | exception is any function that has at least one formal of type | |
6883 | @code{System.Address} or a type derived from it. Such functions are not | |
6884 | considered pure by default, since the compiler assumes that the | |
6885 | @code{Address} parameter may be functioning as a pointer and that the | |
6886 | referenced data may change even if the address value does not. | |
6887 | Similarly, imported functions are not considered to be pure by default, | |
6888 | since there is no way of checking that they are in fact pure. The use | |
6889 | of pragma @code{Pure_Function} for such a function will override these default | |
6890 | assumption, and cause the compiler to treat a designated subprogram as pure | |
6891 | in these cases. | |
6892 | ||
6893 | Note: If pragma @code{Pure_Function} is applied to a renamed function, it | |
6894 | applies to the underlying renamed function. This can be used to | |
6895 | disambiguate cases of overloading where some but not all functions | |
6896 | in a set of overloaded functions are to be designated as pure. | |
6897 | ||
6898 | If pragma @code{Pure_Function} is applied to a library-level function, the | |
6899 | function is also considered pure from an optimization point of view, but the | |
6900 | unit is not a Pure unit in the categorization sense. So for example, a function | |
6901 | thus marked is free to @code{with} non-pure units. | |
6902 | ||
6903 | @node Pragma Rational,Pragma Ravenscar,Pragma Pure_Function,Implementation Defined Pragmas | |
b71d4b62 | 6904 | @anchor{gnat_rm/implementation_defined_pragmas pragma-rational}@anchor{cd} |
64d5610f ML |
6905 | @section Pragma Rational |
6906 | ||
6907 | ||
6908 | Syntax: | |
6909 | ||
6910 | @example | |
6911 | pragma Rational; | |
6912 | @end example | |
6913 | ||
6914 | This pragma is considered obsolescent, but is retained for | |
6915 | compatibility purposes. It is equivalent to: | |
6916 | ||
6917 | @example | |
6918 | pragma Profile (Rational); | |
6919 | @end example | |
6920 | ||
6921 | @node Pragma Ravenscar,Pragma Refined_Depends,Pragma Rational,Implementation Defined Pragmas | |
b71d4b62 | 6922 | @anchor{gnat_rm/implementation_defined_pragmas pragma-ravenscar}@anchor{ce} |
64d5610f ML |
6923 | @section Pragma Ravenscar |
6924 | ||
6925 | ||
6926 | Syntax: | |
6927 | ||
6928 | @example | |
6929 | pragma Ravenscar; | |
6930 | @end example | |
6931 | ||
6932 | This pragma is considered obsolescent, but is retained for | |
6933 | compatibility purposes. It is equivalent to: | |
6934 | ||
6935 | @example | |
6936 | pragma Profile (Ravenscar); | |
6937 | @end example | |
6938 | ||
6939 | which is the preferred method of setting the @code{Ravenscar} profile. | |
6940 | ||
6941 | @node Pragma Refined_Depends,Pragma Refined_Global,Pragma Ravenscar,Implementation Defined Pragmas | |
b71d4b62 | 6942 | @anchor{gnat_rm/implementation_defined_pragmas id33}@anchor{cf}@anchor{gnat_rm/implementation_defined_pragmas pragma-refined-depends}@anchor{d0} |
64d5610f ML |
6943 | @section Pragma Refined_Depends |
6944 | ||
6945 | ||
6946 | Syntax: | |
6947 | ||
6948 | @example | |
6949 | pragma Refined_Depends (DEPENDENCY_RELATION); | |
6950 | ||
6951 | DEPENDENCY_RELATION ::= | |
6952 | null | |
6953 | | (DEPENDENCY_CLAUSE @{, DEPENDENCY_CLAUSE@}) | |
6954 | ||
6955 | DEPENDENCY_CLAUSE ::= | |
6956 | OUTPUT_LIST =>[+] INPUT_LIST | |
6957 | | NULL_DEPENDENCY_CLAUSE | |
6958 | ||
6959 | NULL_DEPENDENCY_CLAUSE ::= null => INPUT_LIST | |
6960 | ||
6961 | OUTPUT_LIST ::= OUTPUT | (OUTPUT @{, OUTPUT@}) | |
6962 | ||
6963 | INPUT_LIST ::= null | INPUT | (INPUT @{, INPUT@}) | |
6964 | ||
6965 | OUTPUT ::= NAME | FUNCTION_RESULT | |
6966 | INPUT ::= NAME | |
6967 | ||
6968 | where FUNCTION_RESULT is a function Result attribute_reference | |
6969 | @end example | |
6970 | ||
6971 | For the semantics of this pragma, see the entry for aspect @code{Refined_Depends} in | |
6972 | the SPARK 2014 Reference Manual, section 6.1.5. | |
6973 | ||
6974 | @node Pragma Refined_Global,Pragma Refined_Post,Pragma Refined_Depends,Implementation Defined Pragmas | |
b71d4b62 | 6975 | @anchor{gnat_rm/implementation_defined_pragmas id34}@anchor{d1}@anchor{gnat_rm/implementation_defined_pragmas pragma-refined-global}@anchor{d2} |
64d5610f ML |
6976 | @section Pragma Refined_Global |
6977 | ||
6978 | ||
6979 | Syntax: | |
6980 | ||
6981 | @example | |
6982 | pragma Refined_Global (GLOBAL_SPECIFICATION); | |
6983 | ||
6984 | GLOBAL_SPECIFICATION ::= | |
6985 | null | |
6986 | | (GLOBAL_LIST) | |
6987 | | (MODED_GLOBAL_LIST @{, MODED_GLOBAL_LIST@}) | |
6988 | ||
6989 | MODED_GLOBAL_LIST ::= MODE_SELECTOR => GLOBAL_LIST | |
6990 | ||
6991 | MODE_SELECTOR ::= In_Out | Input | Output | Proof_In | |
6992 | GLOBAL_LIST ::= GLOBAL_ITEM | (GLOBAL_ITEM @{, GLOBAL_ITEM@}) | |
6993 | GLOBAL_ITEM ::= NAME | |
6994 | @end example | |
6995 | ||
6996 | For the semantics of this pragma, see the entry for aspect @code{Refined_Global} in | |
6997 | the SPARK 2014 Reference Manual, section 6.1.4. | |
6998 | ||
6999 | @node Pragma Refined_Post,Pragma Refined_State,Pragma Refined_Global,Implementation Defined Pragmas | |
b71d4b62 | 7000 | @anchor{gnat_rm/implementation_defined_pragmas id35}@anchor{d3}@anchor{gnat_rm/implementation_defined_pragmas pragma-refined-post}@anchor{d4} |
64d5610f ML |
7001 | @section Pragma Refined_Post |
7002 | ||
7003 | ||
7004 | Syntax: | |
7005 | ||
7006 | @example | |
7007 | pragma Refined_Post (boolean_EXPRESSION); | |
7008 | @end example | |
7009 | ||
7010 | For the semantics of this pragma, see the entry for aspect @code{Refined_Post} in | |
7011 | the SPARK 2014 Reference Manual, section 7.2.7. | |
7012 | ||
7013 | @node Pragma Refined_State,Pragma Relative_Deadline,Pragma Refined_Post,Implementation Defined Pragmas | |
b71d4b62 | 7014 | @anchor{gnat_rm/implementation_defined_pragmas id36}@anchor{d5}@anchor{gnat_rm/implementation_defined_pragmas pragma-refined-state}@anchor{d6} |
64d5610f ML |
7015 | @section Pragma Refined_State |
7016 | ||
7017 | ||
7018 | Syntax: | |
7019 | ||
7020 | @example | |
7021 | pragma Refined_State (REFINEMENT_LIST); | |
7022 | ||
7023 | REFINEMENT_LIST ::= | |
7024 | (REFINEMENT_CLAUSE @{, REFINEMENT_CLAUSE@}) | |
7025 | ||
7026 | REFINEMENT_CLAUSE ::= state_NAME => CONSTITUENT_LIST | |
7027 | ||
7028 | CONSTITUENT_LIST ::= | |
7029 | null | |
7030 | | CONSTITUENT | |
7031 | | (CONSTITUENT @{, CONSTITUENT@}) | |
7032 | ||
7033 | CONSTITUENT ::= object_NAME | state_NAME | |
7034 | @end example | |
7035 | ||
7036 | For the semantics of this pragma, see the entry for aspect @code{Refined_State} in | |
7037 | the SPARK 2014 Reference Manual, section 7.2.2. | |
7038 | ||
7039 | @node Pragma Relative_Deadline,Pragma Remote_Access_Type,Pragma Refined_State,Implementation Defined Pragmas | |
b71d4b62 | 7040 | @anchor{gnat_rm/implementation_defined_pragmas pragma-relative-deadline}@anchor{d7} |
64d5610f ML |
7041 | @section Pragma Relative_Deadline |
7042 | ||
7043 | ||
7044 | Syntax: | |
7045 | ||
7046 | @example | |
7047 | pragma Relative_Deadline (time_span_EXPRESSION); | |
7048 | @end example | |
7049 | ||
7050 | This pragma is standard in Ada 2005, but is available in all earlier | |
7051 | versions of Ada as an implementation-defined pragma. | |
7052 | See Ada 2012 Reference Manual for details. | |
7053 | ||
7054 | @node Pragma Remote_Access_Type,Pragma Rename_Pragma,Pragma Relative_Deadline,Implementation Defined Pragmas | |
b71d4b62 | 7055 | @anchor{gnat_rm/implementation_defined_pragmas id37}@anchor{d8}@anchor{gnat_rm/implementation_defined_pragmas pragma-remote-access-type}@anchor{d9} |
64d5610f ML |
7056 | @section Pragma Remote_Access_Type |
7057 | ||
7058 | ||
7059 | Syntax: | |
7060 | ||
7061 | @example | |
7062 | pragma Remote_Access_Type ([Entity =>] formal_access_type_LOCAL_NAME); | |
7063 | @end example | |
7064 | ||
7065 | This pragma appears in the formal part of a generic declaration. | |
7066 | It specifies an exception to the RM rule from E.2.2(17/2), which forbids | |
7067 | the use of a remote access to class-wide type as actual for a formal | |
7068 | access type. | |
7069 | ||
7070 | When this pragma applies to a formal access type @code{Entity}, that | |
7071 | type is treated as a remote access to class-wide type in the generic. | |
7072 | It must be a formal general access type, and its designated type must | |
7073 | be the class-wide type of a formal tagged limited private type from the | |
7074 | same generic declaration. | |
7075 | ||
7076 | In the generic unit, the formal type is subject to all restrictions | |
7077 | pertaining to remote access to class-wide types. At instantiation, the | |
7078 | actual type must be a remote access to class-wide type. | |
7079 | ||
7080 | @node Pragma Rename_Pragma,Pragma Restricted_Run_Time,Pragma Remote_Access_Type,Implementation Defined Pragmas | |
b71d4b62 | 7081 | @anchor{gnat_rm/implementation_defined_pragmas pragma-rename-pragma}@anchor{da} |
64d5610f ML |
7082 | @section Pragma Rename_Pragma |
7083 | ||
7084 | ||
7085 | @geindex Pragmas | |
7086 | @geindex synonyms | |
7087 | ||
7088 | Syntax: | |
7089 | ||
7090 | @example | |
7091 | pragma Rename_Pragma ( | |
7092 | [New_Name =>] IDENTIFIER, | |
7093 | [Renamed =>] pragma_IDENTIFIER); | |
7094 | @end example | |
7095 | ||
7096 | This pragma provides a mechanism for supplying new names for existing | |
7097 | pragmas. The @code{New_Name} identifier can subsequently be used as a synonym for | |
7098 | the Renamed pragma. For example, suppose you have code that was originally | |
7099 | developed on a compiler that supports Inline_Only as an implementation defined | |
7100 | pragma. And suppose the semantics of pragma Inline_Only are identical to (or at | |
7101 | least very similar to) the GNAT implementation defined pragma | |
7102 | Inline_Always. You could globally replace Inline_Only with Inline_Always. | |
7103 | ||
7104 | However, to avoid that source modification, you could instead add a | |
7105 | configuration pragma: | |
7106 | ||
7107 | @example | |
7108 | pragma Rename_Pragma ( | |
7109 | New_Name => Inline_Only, | |
7110 | Renamed => Inline_Always); | |
7111 | @end example | |
7112 | ||
7113 | Then GNAT will treat “pragma Inline_Only …” as if you had written | |
7114 | “pragma Inline_Always …”. | |
7115 | ||
7116 | Pragma Inline_Only will not necessarily mean the same thing as the other Ada | |
7117 | compiler; it’s up to you to make sure the semantics are close enough. | |
7118 | ||
7119 | @node Pragma Restricted_Run_Time,Pragma Restriction_Warnings,Pragma Rename_Pragma,Implementation Defined Pragmas | |
b71d4b62 | 7120 | @anchor{gnat_rm/implementation_defined_pragmas pragma-restricted-run-time}@anchor{db} |
64d5610f ML |
7121 | @section Pragma Restricted_Run_Time |
7122 | ||
7123 | ||
7124 | Syntax: | |
7125 | ||
7126 | @example | |
7127 | pragma Restricted_Run_Time; | |
7128 | @end example | |
7129 | ||
7130 | This pragma is considered obsolescent, but is retained for | |
7131 | compatibility purposes. It is equivalent to: | |
7132 | ||
7133 | @example | |
7134 | pragma Profile (Restricted); | |
7135 | @end example | |
7136 | ||
7137 | which is the preferred method of setting the restricted run time | |
7138 | profile. | |
7139 | ||
7140 | @node Pragma Restriction_Warnings,Pragma Reviewable,Pragma Restricted_Run_Time,Implementation Defined Pragmas | |
b71d4b62 | 7141 | @anchor{gnat_rm/implementation_defined_pragmas pragma-restriction-warnings}@anchor{dc} |
64d5610f ML |
7142 | @section Pragma Restriction_Warnings |
7143 | ||
7144 | ||
7145 | Syntax: | |
7146 | ||
7147 | @example | |
7148 | pragma Restriction_Warnings | |
7149 | (restriction_IDENTIFIER @{, restriction_IDENTIFIER@}); | |
7150 | @end example | |
7151 | ||
7152 | This pragma allows a series of restriction identifiers to be | |
7153 | specified (the list of allowed identifiers is the same as for | |
7154 | pragma @code{Restrictions}). For each of these identifiers | |
7155 | the compiler checks for violations of the restriction, but | |
7156 | generates a warning message rather than an error message | |
7157 | if the restriction is violated. | |
7158 | ||
7159 | One use of this is in situations where you want to know | |
7160 | about violations of a restriction, but you want to ignore some of | |
7161 | these violations. Consider this example, where you want to set | |
7162 | Ada_95 mode and enable style checks, but you want to know about | |
7163 | any other use of implementation pragmas: | |
7164 | ||
7165 | @example | |
7166 | pragma Restriction_Warnings (No_Implementation_Pragmas); | |
7167 | pragma Warnings (Off, "violation of No_Implementation_Pragmas"); | |
7168 | pragma Ada_95; | |
7169 | pragma Style_Checks ("2bfhkM160"); | |
7170 | pragma Warnings (On, "violation of No_Implementation_Pragmas"); | |
7171 | @end example | |
7172 | ||
7173 | By including the above lines in a configuration pragmas file, | |
7174 | the Ada_95 and Style_Checks pragmas are accepted without | |
7175 | generating a warning, but any other use of implementation | |
7176 | defined pragmas will cause a warning to be generated. | |
7177 | ||
7178 | @node Pragma Reviewable,Pragma Secondary_Stack_Size,Pragma Restriction_Warnings,Implementation Defined Pragmas | |
b71d4b62 | 7179 | @anchor{gnat_rm/implementation_defined_pragmas pragma-reviewable}@anchor{dd} |
64d5610f ML |
7180 | @section Pragma Reviewable |
7181 | ||
7182 | ||
7183 | Syntax: | |
7184 | ||
7185 | @example | |
7186 | pragma Reviewable; | |
7187 | @end example | |
7188 | ||
7189 | This pragma is an RM-defined standard pragma, but has no effect on the | |
7190 | program being compiled, or on the code generated for the program. | |
7191 | ||
7192 | To obtain the required output specified in RM H.3.1, the compiler must be | |
7193 | run with various special switches as follows: | |
7194 | ||
7195 | ||
7196 | @itemize * | |
7197 | ||
7198 | @item | |
7199 | `Where compiler-generated run-time checks remain' | |
7200 | ||
7201 | The switch `-gnatGL' | |
7202 | may be used to list the expanded code in pseudo-Ada form. | |
7203 | Runtime checks show up in the listing either as explicit | |
7204 | checks or operators marked with @{@} to indicate a check is present. | |
7205 | ||
7206 | @item | |
7207 | `An identification of known exceptions at compile time' | |
7208 | ||
7209 | If the program is compiled with `-gnatwa', | |
7210 | the compiler warning messages will indicate all cases where the compiler | |
7211 | detects that an exception is certain to occur at run time. | |
7212 | ||
7213 | @item | |
7214 | `Possible reads of uninitialized variables' | |
7215 | ||
7216 | The compiler warns of many such cases, but its output is incomplete. | |
7217 | @end itemize | |
7218 | ||
7219 | ||
7220 | A supplemental static analysis tool | |
7221 | may be used to obtain a comprehensive list of all | |
7222 | possible points at which uninitialized data may be read. | |
7223 | ||
7224 | ||
7225 | @itemize * | |
7226 | ||
7227 | @item | |
7228 | `Where run-time support routines are implicitly invoked' | |
7229 | ||
7230 | In the output from `-gnatGL', | |
7231 | run-time calls are explicitly listed as calls to the relevant | |
7232 | run-time routine. | |
7233 | ||
7234 | @item | |
7235 | `Object code listing' | |
7236 | ||
7237 | This may be obtained either by using the `-S' switch, | |
7238 | or the objdump utility. | |
7239 | ||
7240 | @item | |
7241 | `Constructs known to be erroneous at compile time' | |
7242 | ||
7243 | These are identified by warnings issued by the compiler (use `-gnatwa'). | |
7244 | ||
7245 | @item | |
7246 | `Stack usage information' | |
7247 | ||
7248 | Static stack usage data (maximum per-subprogram) can be obtained via the | |
7249 | `-fstack-usage' switch to the compiler. | |
7250 | Dynamic stack usage data (per task) can be obtained via the `-u' switch | |
7251 | to gnatbind | |
7252 | @end itemize | |
7253 | ||
7254 | ||
7255 | ||
7256 | @itemize * | |
7257 | ||
7258 | @item | |
7259 | `Object code listing of entire partition' | |
7260 | ||
7261 | This can be obtained by compiling the partition with `-S', | |
7262 | or by applying objdump | |
7263 | to all the object files that are part of the partition. | |
7264 | ||
7265 | @item | |
7266 | `A description of the run-time model' | |
7267 | ||
7268 | The full sources of the run-time are available, and the documentation of | |
7269 | these routines describes how these run-time routines interface to the | |
7270 | underlying operating system facilities. | |
7271 | ||
7272 | @item | |
7273 | `Control and data-flow information' | |
7274 | @end itemize | |
7275 | ||
7276 | ||
7277 | A supplemental static analysis tool | |
7278 | may be used to obtain complete control and data-flow information, as well as | |
7279 | comprehensive messages identifying possible problems based on this | |
7280 | information. | |
7281 | ||
7282 | @node Pragma Secondary_Stack_Size,Pragma Share_Generic,Pragma Reviewable,Implementation Defined Pragmas | |
b71d4b62 | 7283 | @anchor{gnat_rm/implementation_defined_pragmas id38}@anchor{de}@anchor{gnat_rm/implementation_defined_pragmas pragma-secondary-stack-size}@anchor{df} |
64d5610f ML |
7284 | @section Pragma Secondary_Stack_Size |
7285 | ||
7286 | ||
7287 | Syntax: | |
7288 | ||
7289 | @example | |
7290 | pragma Secondary_Stack_Size (integer_EXPRESSION); | |
7291 | @end example | |
7292 | ||
7293 | This pragma appears within the task definition of a single task declaration | |
7294 | or a task type declaration (like pragma @code{Storage_Size}) and applies to all | |
7295 | task objects of that type. The argument specifies the size of the secondary | |
7296 | stack to be used by these task objects, and must be of an integer type. The | |
7297 | secondary stack is used to handle functions that return a variable-sized | |
7298 | result, for example a function returning an unconstrained String. | |
7299 | ||
7300 | Note this pragma only applies to targets using fixed secondary stacks, like | |
7301 | VxWorks 653 and bare board targets, where a fixed block for the | |
7302 | secondary stack is allocated from the primary stack of the task. By default, | |
7303 | these targets assign a percentage of the primary stack for the secondary stack, | |
7304 | as defined by @code{System.Parameter.Sec_Stack_Percentage}. With this pragma, | |
7305 | an @code{integer_EXPRESSION} of bytes is assigned from the primary stack instead. | |
7306 | ||
7307 | For most targets, the pragma does not apply as the secondary stack grows on | |
7308 | demand: allocated as a chain of blocks in the heap. The default size of these | |
7309 | blocks can be modified via the @code{-D} binder option as described in | |
7310 | @cite{GNAT User’s Guide}. | |
7311 | ||
7312 | Note that no check is made to see if the secondary stack can fit inside the | |
7313 | primary stack. | |
7314 | ||
7315 | Note the pragma cannot appear when the restriction @code{No_Secondary_Stack} | |
7316 | is in effect. | |
7317 | ||
7318 | @node Pragma Share_Generic,Pragma Shared,Pragma Secondary_Stack_Size,Implementation Defined Pragmas | |
b71d4b62 | 7319 | @anchor{gnat_rm/implementation_defined_pragmas pragma-share-generic}@anchor{e0} |
64d5610f ML |
7320 | @section Pragma Share_Generic |
7321 | ||
7322 | ||
7323 | Syntax: | |
7324 | ||
7325 | @example | |
7326 | pragma Share_Generic (GNAME @{, GNAME@}); | |
7327 | ||
7328 | GNAME ::= generic_unit_NAME | generic_instance_NAME | |
7329 | @end example | |
7330 | ||
7331 | This pragma is provided for compatibility with Dec Ada 83. It has | |
7332 | no effect in GNAT (which does not implement shared generics), other | |
7333 | than to check that the given names are all names of generic units or | |
7334 | generic instances. | |
7335 | ||
7336 | @node Pragma Shared,Pragma Short_Circuit_And_Or,Pragma Share_Generic,Implementation Defined Pragmas | |
b71d4b62 | 7337 | @anchor{gnat_rm/implementation_defined_pragmas id39}@anchor{e1}@anchor{gnat_rm/implementation_defined_pragmas pragma-shared}@anchor{e2} |
64d5610f ML |
7338 | @section Pragma Shared |
7339 | ||
7340 | ||
7341 | This pragma is provided for compatibility with Ada 83. The syntax and | |
7342 | semantics are identical to pragma Atomic. | |
7343 | ||
7344 | @node Pragma Short_Circuit_And_Or,Pragma Short_Descriptors,Pragma Shared,Implementation Defined Pragmas | |
b71d4b62 | 7345 | @anchor{gnat_rm/implementation_defined_pragmas pragma-short-circuit-and-or}@anchor{e3} |
64d5610f ML |
7346 | @section Pragma Short_Circuit_And_Or |
7347 | ||
7348 | ||
7349 | Syntax: | |
7350 | ||
7351 | @example | |
7352 | pragma Short_Circuit_And_Or; | |
7353 | @end example | |
7354 | ||
7355 | This configuration pragma causes any occurrence of the AND operator applied to | |
7356 | operands of type Standard.Boolean to be short-circuited (i.e. the AND operator | |
7357 | is treated as if it were AND THEN). Or is similarly treated as OR ELSE. This | |
7358 | may be useful in the context of certification protocols requiring the use of | |
7359 | short-circuited logical operators. If this configuration pragma occurs locally | |
7360 | within the file being compiled, it applies only to the file being compiled. | |
7361 | There is no requirement that all units in a partition use this option. | |
7362 | ||
7363 | @node Pragma Short_Descriptors,Pragma Simple_Storage_Pool_Type,Pragma Short_Circuit_And_Or,Implementation Defined Pragmas | |
b71d4b62 | 7364 | @anchor{gnat_rm/implementation_defined_pragmas pragma-short-descriptors}@anchor{e4} |
64d5610f ML |
7365 | @section Pragma Short_Descriptors |
7366 | ||
7367 | ||
7368 | Syntax: | |
7369 | ||
7370 | @example | |
7371 | pragma Short_Descriptors; | |
7372 | @end example | |
7373 | ||
7374 | This pragma is provided for compatibility with other Ada implementations. It | |
7375 | is recognized but ignored by all current versions of GNAT. | |
7376 | ||
7377 | @node Pragma Simple_Storage_Pool_Type,Pragma Source_File_Name,Pragma Short_Descriptors,Implementation Defined Pragmas | |
b71d4b62 | 7378 | @anchor{gnat_rm/implementation_defined_pragmas id40}@anchor{e5}@anchor{gnat_rm/implementation_defined_pragmas pragma-simple-storage-pool-type}@anchor{e6} |
64d5610f ML |
7379 | @section Pragma Simple_Storage_Pool_Type |
7380 | ||
7381 | ||
7382 | @geindex Storage pool | |
7383 | @geindex simple | |
7384 | ||
7385 | @geindex Simple storage pool | |
7386 | ||
7387 | Syntax: | |
7388 | ||
7389 | @example | |
7390 | pragma Simple_Storage_Pool_Type (type_LOCAL_NAME); | |
7391 | @end example | |
7392 | ||
7393 | A type can be established as a ‘simple storage pool type’ by applying | |
7394 | the representation pragma @code{Simple_Storage_Pool_Type} to the type. | |
7395 | A type named in the pragma must be a library-level immutably limited record | |
7396 | type or limited tagged type declared immediately within a package declaration. | |
7397 | The type can also be a limited private type whose full type is allowed as | |
7398 | a simple storage pool type. | |
7399 | ||
7400 | For a simple storage pool type @code{SSP}, nonabstract primitive subprograms | |
7401 | @code{Allocate}, @code{Deallocate}, and @code{Storage_Size} can be declared that | |
7402 | are subtype conformant with the following subprogram declarations: | |
7403 | ||
7404 | @example | |
7405 | procedure Allocate | |
7406 | (Pool : in out SSP; | |
7407 | Storage_Address : out System.Address; | |
7408 | Size_In_Storage_Elements : System.Storage_Elements.Storage_Count; | |
7409 | Alignment : System.Storage_Elements.Storage_Count); | |
7410 | ||
7411 | procedure Deallocate | |
7412 | (Pool : in out SSP; | |
7413 | Storage_Address : System.Address; | |
7414 | Size_In_Storage_Elements : System.Storage_Elements.Storage_Count; | |
7415 | Alignment : System.Storage_Elements.Storage_Count); | |
7416 | ||
7417 | function Storage_Size (Pool : SSP) | |
7418 | return System.Storage_Elements.Storage_Count; | |
7419 | @end example | |
7420 | ||
7421 | Procedure @code{Allocate} must be declared, whereas @code{Deallocate} and | |
7422 | @code{Storage_Size} are optional. If @code{Deallocate} is not declared, then | |
7423 | applying an unchecked deallocation has no effect other than to set its actual | |
7424 | parameter to null. If @code{Storage_Size} is not declared, then the | |
7425 | @code{Storage_Size} attribute applied to an access type associated with | |
7426 | a pool object of type SSP returns zero. Additional operations can be declared | |
7427 | for a simple storage pool type (such as for supporting a mark/release | |
7428 | storage-management discipline). | |
7429 | ||
7430 | An object of a simple storage pool type can be associated with an access | |
7431 | type by specifying the attribute | |
b71d4b62 | 7432 | @ref{e7,,Simple_Storage_Pool}. For example: |
64d5610f ML |
7433 | |
7434 | @example | |
7435 | My_Pool : My_Simple_Storage_Pool_Type; | |
7436 | ||
7437 | type Acc is access My_Data_Type; | |
7438 | ||
7439 | for Acc'Simple_Storage_Pool use My_Pool; | |
7440 | @end example | |
7441 | ||
b71d4b62 | 7442 | See attribute @ref{e7,,Simple_Storage_Pool} |
64d5610f ML |
7443 | for further details. |
7444 | ||
7445 | @node Pragma Source_File_Name,Pragma Source_File_Name_Project,Pragma Simple_Storage_Pool_Type,Implementation Defined Pragmas | |
b71d4b62 | 7446 | @anchor{gnat_rm/implementation_defined_pragmas id41}@anchor{e8}@anchor{gnat_rm/implementation_defined_pragmas pragma-source-file-name}@anchor{e9} |
64d5610f ML |
7447 | @section Pragma Source_File_Name |
7448 | ||
7449 | ||
7450 | Syntax: | |
7451 | ||
7452 | @example | |
7453 | pragma Source_File_Name ( | |
7454 | [Unit_Name =>] unit_NAME, | |
7455 | Spec_File_Name => STRING_LITERAL, | |
7456 | [Index => INTEGER_LITERAL]); | |
7457 | ||
7458 | pragma Source_File_Name ( | |
7459 | [Unit_Name =>] unit_NAME, | |
7460 | Body_File_Name => STRING_LITERAL, | |
7461 | [Index => INTEGER_LITERAL]); | |
7462 | @end example | |
7463 | ||
7464 | Use this to override the normal naming convention. It is a configuration | |
7465 | pragma, and so has the usual applicability of configuration pragmas | |
7466 | (i.e., it applies to either an entire partition, or to all units in a | |
7467 | compilation, or to a single unit, depending on how it is used). | |
7468 | @code{unit_name} is mapped to @code{file_name_literal}. The identifier for | |
7469 | the second argument is required, and indicates whether this is the file | |
7470 | name for the spec or for the body. | |
7471 | ||
7472 | The optional Index argument should be used when a file contains multiple | |
7473 | units, and when you do not want to use @code{gnatchop} to separate then | |
7474 | into multiple files (which is the recommended procedure to limit the | |
7475 | number of recompilations that are needed when some sources change). | |
7476 | For instance, if the source file @code{source.ada} contains | |
7477 | ||
7478 | @example | |
7479 | package B is | |
7480 | ... | |
7481 | end B; | |
7482 | ||
7483 | with B; | |
7484 | procedure A is | |
7485 | begin | |
7486 | .. | |
7487 | end A; | |
7488 | @end example | |
7489 | ||
7490 | you could use the following configuration pragmas: | |
7491 | ||
7492 | @example | |
7493 | pragma Source_File_Name | |
7494 | (B, Spec_File_Name => "source.ada", Index => 1); | |
7495 | pragma Source_File_Name | |
7496 | (A, Body_File_Name => "source.ada", Index => 2); | |
7497 | @end example | |
7498 | ||
7499 | Note that the @code{gnatname} utility can also be used to generate those | |
7500 | configuration pragmas. | |
7501 | ||
7502 | Another form of the @code{Source_File_Name} pragma allows | |
7503 | the specification of patterns defining alternative file naming schemes | |
7504 | to apply to all files. | |
7505 | ||
7506 | @example | |
7507 | pragma Source_File_Name | |
7508 | ( [Spec_File_Name =>] STRING_LITERAL | |
7509 | [,[Casing =>] CASING_SPEC] | |
7510 | [,[Dot_Replacement =>] STRING_LITERAL]); | |
7511 | ||
7512 | pragma Source_File_Name | |
7513 | ( [Body_File_Name =>] STRING_LITERAL | |
7514 | [,[Casing =>] CASING_SPEC] | |
7515 | [,[Dot_Replacement =>] STRING_LITERAL]); | |
7516 | ||
7517 | pragma Source_File_Name | |
7518 | ( [Subunit_File_Name =>] STRING_LITERAL | |
7519 | [,[Casing =>] CASING_SPEC] | |
7520 | [,[Dot_Replacement =>] STRING_LITERAL]); | |
7521 | ||
7522 | CASING_SPEC ::= Lowercase | Uppercase | Mixedcase | |
7523 | @end example | |
7524 | ||
7525 | The first argument is a pattern that contains a single asterisk indicating | |
7526 | the point at which the unit name is to be inserted in the pattern string | |
7527 | to form the file name. The second argument is optional. If present it | |
7528 | specifies the casing of the unit name in the resulting file name string. | |
7529 | The default is lower case. Finally the third argument allows for systematic | |
7530 | replacement of any dots in the unit name by the specified string literal. | |
7531 | ||
7532 | Note that Source_File_Name pragmas should not be used if you are using | |
7533 | project files. The reason for this rule is that the project manager is not | |
7534 | aware of these pragmas, and so other tools that use the project file would not | |
7535 | be aware of the intended naming conventions. If you are using project files, | |
7536 | file naming is controlled by Source_File_Name_Project pragmas, which are | |
7537 | usually supplied automatically by the project manager. A pragma | |
b71d4b62 | 7538 | Source_File_Name cannot appear after a @ref{ea,,Pragma Source_File_Name_Project}. |
64d5610f ML |
7539 | |
7540 | For more details on the use of the @code{Source_File_Name} pragma, see the | |
7541 | sections on @cite{Using Other File Names} and @cite{Alternative File Naming Schemes} | |
7542 | in the @cite{GNAT User’s Guide}. | |
7543 | ||
7544 | @node Pragma Source_File_Name_Project,Pragma Source_Reference,Pragma Source_File_Name,Implementation Defined Pragmas | |
b71d4b62 | 7545 | @anchor{gnat_rm/implementation_defined_pragmas id42}@anchor{eb}@anchor{gnat_rm/implementation_defined_pragmas pragma-source-file-name-project}@anchor{ea} |
64d5610f ML |
7546 | @section Pragma Source_File_Name_Project |
7547 | ||
7548 | ||
7549 | This pragma has the same syntax and semantics as pragma Source_File_Name. | |
7550 | It is only allowed as a stand-alone configuration pragma. | |
b71d4b62 | 7551 | It cannot appear after a @ref{e9,,Pragma Source_File_Name}, and |
64d5610f ML |
7552 | most importantly, once pragma Source_File_Name_Project appears, |
7553 | no further Source_File_Name pragmas are allowed. | |
7554 | ||
7555 | The intention is that Source_File_Name_Project pragmas are always | |
7556 | generated by the Project Manager in a manner consistent with the naming | |
7557 | specified in a project file, and when naming is controlled in this manner, | |
7558 | it is not permissible to attempt to modify this naming scheme using | |
7559 | Source_File_Name or Source_File_Name_Project pragmas (which would not be | |
7560 | known to the project manager). | |
7561 | ||
7562 | @node Pragma Source_Reference,Pragma SPARK_Mode,Pragma Source_File_Name_Project,Implementation Defined Pragmas | |
b71d4b62 | 7563 | @anchor{gnat_rm/implementation_defined_pragmas pragma-source-reference}@anchor{ec} |
64d5610f ML |
7564 | @section Pragma Source_Reference |
7565 | ||
7566 | ||
7567 | Syntax: | |
7568 | ||
7569 | @example | |
7570 | pragma Source_Reference (INTEGER_LITERAL, STRING_LITERAL); | |
7571 | @end example | |
7572 | ||
7573 | This pragma must appear as the first line of a source file. | |
7574 | @code{integer_literal} is the logical line number of the line following | |
7575 | the pragma line (for use in error messages and debugging | |
7576 | information). @code{string_literal} is a static string constant that | |
7577 | specifies the file name to be used in error messages and debugging | |
7578 | information. This is most notably used for the output of @code{gnatchop} | |
7579 | with the `-r' switch, to make sure that the original unchopped | |
7580 | source file is the one referred to. | |
7581 | ||
7582 | The second argument must be a string literal, it cannot be a static | |
7583 | string expression other than a string literal. This is because its value | |
7584 | is needed for error messages issued by all phases of the compiler. | |
7585 | ||
7586 | @node Pragma SPARK_Mode,Pragma Static_Elaboration_Desired,Pragma Source_Reference,Implementation Defined Pragmas | |
b71d4b62 | 7587 | @anchor{gnat_rm/implementation_defined_pragmas id43}@anchor{ed}@anchor{gnat_rm/implementation_defined_pragmas pragma-spark-mode}@anchor{ee} |
64d5610f ML |
7588 | @section Pragma SPARK_Mode |
7589 | ||
7590 | ||
7591 | Syntax: | |
7592 | ||
7593 | @example | |
7594 | pragma SPARK_Mode [(On | Off)] ; | |
7595 | @end example | |
7596 | ||
7597 | In general a program can have some parts that are in SPARK 2014 (and | |
7598 | follow all the rules in the SPARK Reference Manual), and some parts | |
7599 | that are full Ada 2012. | |
7600 | ||
7601 | The SPARK_Mode pragma is used to identify which parts are in SPARK | |
7602 | 2014 (by default programs are in full Ada). The SPARK_Mode pragma can | |
7603 | be used in the following places: | |
7604 | ||
7605 | ||
7606 | @itemize * | |
7607 | ||
7608 | @item | |
7609 | As a configuration pragma, in which case it sets the default mode for | |
7610 | all units compiled with this pragma. | |
7611 | ||
7612 | @item | |
7613 | Immediately following a library-level subprogram spec | |
7614 | ||
7615 | @item | |
7616 | Immediately within a library-level package body | |
7617 | ||
7618 | @item | |
7619 | Immediately following the @code{private} keyword of a library-level | |
7620 | package spec | |
7621 | ||
7622 | @item | |
7623 | Immediately following the @code{begin} keyword of a library-level | |
7624 | package body | |
7625 | ||
7626 | @item | |
7627 | Immediately within a library-level subprogram body | |
7628 | @end itemize | |
7629 | ||
7630 | Normally a subprogram or package spec/body inherits the current mode | |
7631 | that is active at the point it is declared. But this can be overridden | |
7632 | by pragma within the spec or body as above. | |
7633 | ||
7634 | The basic consistency rule is that you can’t turn SPARK_Mode back | |
7635 | @code{On}, once you have explicitly (with a pragma) turned if | |
7636 | @code{Off}. So the following rules apply: | |
7637 | ||
7638 | If a subprogram spec has SPARK_Mode @code{Off}, then the body must | |
7639 | also have SPARK_Mode @code{Off}. | |
7640 | ||
7641 | For a package, we have four parts: | |
7642 | ||
7643 | ||
7644 | @itemize * | |
7645 | ||
7646 | @item | |
7647 | the package public declarations | |
7648 | ||
7649 | @item | |
7650 | the package private part | |
7651 | ||
7652 | @item | |
7653 | the body of the package | |
7654 | ||
7655 | @item | |
7656 | the elaboration code after @code{begin} | |
7657 | @end itemize | |
7658 | ||
7659 | For a package, the rule is that if you explicitly turn SPARK_Mode | |
7660 | @code{Off} for any part, then all the following parts must have | |
7661 | SPARK_Mode @code{Off}. Note that this may require repeating a pragma | |
7662 | SPARK_Mode (@code{Off}) in the body. For example, if we have a | |
7663 | configuration pragma SPARK_Mode (@code{On}) that turns the mode on by | |
7664 | default everywhere, and one particular package spec has pragma | |
7665 | SPARK_Mode (@code{Off}), then that pragma will need to be repeated in | |
7666 | the package body. | |
7667 | ||
7668 | @node Pragma Static_Elaboration_Desired,Pragma Stream_Convert,Pragma SPARK_Mode,Implementation Defined Pragmas | |
b71d4b62 | 7669 | @anchor{gnat_rm/implementation_defined_pragmas pragma-static-elaboration-desired}@anchor{ef} |
64d5610f ML |
7670 | @section Pragma Static_Elaboration_Desired |
7671 | ||
7672 | ||
7673 | Syntax: | |
7674 | ||
7675 | @example | |
7676 | pragma Static_Elaboration_Desired; | |
7677 | @end example | |
7678 | ||
7679 | This pragma is used to indicate that the compiler should attempt to initialize | |
7680 | statically the objects declared in the library unit to which the pragma applies, | |
7681 | when these objects are initialized (explicitly or implicitly) by an aggregate. | |
7682 | In the absence of this pragma, aggregates in object declarations are expanded | |
7683 | into assignments and loops, even when the aggregate components are static | |
7684 | constants. When the aggregate is present the compiler builds a static expression | |
7685 | that requires no run-time code, so that the initialized object can be placed in | |
7686 | read-only data space. If the components are not static, or the aggregate has | |
7687 | more that 100 components, the compiler emits a warning that the pragma cannot | |
7688 | be obeyed. (See also the restriction No_Implicit_Loops, which supports static | |
7689 | construction of larger aggregates with static components that include an others | |
7690 | choice.) | |
7691 | ||
7692 | @node Pragma Stream_Convert,Pragma Style_Checks,Pragma Static_Elaboration_Desired,Implementation Defined Pragmas | |
b71d4b62 | 7693 | @anchor{gnat_rm/implementation_defined_pragmas pragma-stream-convert}@anchor{f0} |
64d5610f ML |
7694 | @section Pragma Stream_Convert |
7695 | ||
7696 | ||
7697 | Syntax: | |
7698 | ||
7699 | @example | |
7700 | pragma Stream_Convert ( | |
7701 | [Entity =>] type_LOCAL_NAME, | |
7702 | [Read =>] function_NAME, | |
7703 | [Write =>] function_NAME); | |
7704 | @end example | |
7705 | ||
7706 | This pragma provides an efficient way of providing user-defined stream | |
7707 | attributes. Not only is it simpler to use than specifying the attributes | |
7708 | directly, but more importantly, it allows the specification to be made in such | |
7709 | a way that the predefined unit Ada.Streams is not loaded unless it is actually | |
7710 | needed (i.e. unless the stream attributes are actually used); the use of | |
7711 | the Stream_Convert pragma adds no overhead at all, unless the stream | |
7712 | attributes are actually used on the designated type. | |
7713 | ||
7714 | The first argument specifies the type for which stream functions are | |
7715 | provided. The second parameter provides a function used to read values | |
7716 | of this type. It must name a function whose argument type may be any | |
7717 | subtype, and whose returned type must be the type given as the first | |
7718 | argument to the pragma. | |
7719 | ||
7720 | The meaning of the @code{Read} parameter is that if a stream attribute directly | |
7721 | or indirectly specifies reading of the type given as the first parameter, | |
7722 | then a value of the type given as the argument to the Read function is | |
7723 | read from the stream, and then the Read function is used to convert this | |
7724 | to the required target type. | |
7725 | ||
7726 | Similarly the @code{Write} parameter specifies how to treat write attributes | |
7727 | that directly or indirectly apply to the type given as the first parameter. | |
7728 | It must have an input parameter of the type specified by the first parameter, | |
7729 | and the return type must be the same as the input type of the Read function. | |
7730 | The effect is to first call the Write function to convert to the given stream | |
7731 | type, and then write the result type to the stream. | |
7732 | ||
7733 | The Read and Write functions must not be overloaded subprograms. If necessary | |
7734 | renamings can be supplied to meet this requirement. | |
7735 | The usage of this attribute is best illustrated by a simple example, taken | |
7736 | from the GNAT implementation of package Ada.Strings.Unbounded: | |
7737 | ||
7738 | @example | |
7739 | function To_Unbounded (S : String) return Unbounded_String | |
7740 | renames To_Unbounded_String; | |
7741 | ||
7742 | pragma Stream_Convert | |
7743 | (Unbounded_String, To_Unbounded, To_String); | |
7744 | @end example | |
7745 | ||
7746 | The specifications of the referenced functions, as given in the Ada | |
7747 | Reference Manual are: | |
7748 | ||
7749 | @example | |
7750 | function To_Unbounded_String (Source : String) | |
7751 | return Unbounded_String; | |
7752 | ||
7753 | function To_String (Source : Unbounded_String) | |
7754 | return String; | |
7755 | @end example | |
7756 | ||
7757 | The effect is that if the value of an unbounded string is written to a stream, | |
7758 | then the representation of the item in the stream is in the same format that | |
7759 | would be used for @code{Standard.String'Output}, and this same representation | |
7760 | is expected when a value of this type is read from the stream. Note that the | |
7761 | value written always includes the bounds, even for Unbounded_String’Write, | |
7762 | since Unbounded_String is not an array type. | |
7763 | ||
7764 | Note that the @code{Stream_Convert} pragma is not effective in the case of | |
7765 | a derived type of a non-limited tagged type. If such a type is specified then | |
7766 | the pragma is silently ignored, and the default implementation of the stream | |
7767 | attributes is used instead. | |
7768 | ||
7769 | @node Pragma Style_Checks,Pragma Subtitle,Pragma Stream_Convert,Implementation Defined Pragmas | |
b71d4b62 | 7770 | @anchor{gnat_rm/implementation_defined_pragmas pragma-style-checks}@anchor{f1} |
64d5610f ML |
7771 | @section Pragma Style_Checks |
7772 | ||
7773 | ||
7774 | Syntax: | |
7775 | ||
7776 | @example | |
7777 | pragma Style_Checks (string_LITERAL | ALL_CHECKS | | |
7778 | On | Off [, LOCAL_NAME]); | |
7779 | @end example | |
7780 | ||
7781 | This pragma is used in conjunction with compiler switches to control the | |
7782 | built in style checking provided by GNAT. The compiler switches, if set, | |
7783 | provide an initial setting for the switches, and this pragma may be used | |
7784 | to modify these settings, or the settings may be provided entirely by | |
7785 | the use of the pragma. This pragma can be used anywhere that a pragma | |
7786 | is legal, including use as a configuration pragma (including use in | |
7787 | the @code{gnat.adc} file). | |
7788 | ||
7789 | The form with a string literal specifies which style options are to be | |
7790 | activated. These are additive, so they apply in addition to any previously | |
7791 | set style check options. The codes for the options are the same as those | |
7792 | used in the `-gnaty' switch to `gcc' or `gnatmake'. | |
7793 | For example the following two methods can be used to enable | |
7794 | layout checking: | |
7795 | ||
7796 | ||
7797 | @itemize * | |
7798 | ||
7799 | @item | |
7800 | @example | |
7801 | pragma Style_Checks ("l"); | |
7802 | @end example | |
7803 | ||
7804 | @item | |
7805 | @example | |
7806 | gcc -c -gnatyl ... | |
7807 | @end example | |
7808 | @end itemize | |
7809 | ||
7810 | The form @code{ALL_CHECKS} activates all standard checks (its use is equivalent | |
7811 | to the use of the @code{gnaty} switch with no options. | |
7812 | See the @cite{GNAT User’s Guide} for details.) | |
7813 | ||
7814 | Note: the behavior is slightly different in GNAT mode (@code{-gnatg} used). | |
7815 | In this case, @code{ALL_CHECKS} implies the standard set of GNAT mode style check | |
7816 | options (i.e. equivalent to @code{-gnatyg}). | |
7817 | ||
7818 | The forms with @code{Off} and @code{On} | |
7819 | can be used to temporarily disable style checks | |
7820 | as shown in the following example: | |
7821 | ||
7822 | @example | |
7823 | pragma Style_Checks ("k"); -- requires keywords in lower case | |
7824 | pragma Style_Checks (Off); -- turn off style checks | |
7825 | NULL; -- this will not generate an error message | |
7826 | pragma Style_Checks (On); -- turn style checks back on | |
7827 | NULL; -- this will generate an error message | |
7828 | @end example | |
7829 | ||
7830 | Finally the two argument form is allowed only if the first argument is | |
7831 | @code{On} or @code{Off}. The effect is to turn of semantic style checks | |
7832 | for the specified entity, as shown in the following example: | |
7833 | ||
7834 | @example | |
7835 | pragma Style_Checks ("r"); -- require consistency of identifier casing | |
7836 | Arg : Integer; | |
7837 | Rf1 : Integer := ARG; -- incorrect, wrong case | |
7838 | pragma Style_Checks (Off, Arg); | |
7839 | Rf2 : Integer := ARG; -- OK, no error | |
7840 | @end example | |
7841 | ||
7842 | @node Pragma Subtitle,Pragma Suppress,Pragma Style_Checks,Implementation Defined Pragmas | |
b71d4b62 | 7843 | @anchor{gnat_rm/implementation_defined_pragmas pragma-subtitle}@anchor{f2} |
64d5610f ML |
7844 | @section Pragma Subtitle |
7845 | ||
7846 | ||
7847 | Syntax: | |
7848 | ||
7849 | @example | |
7850 | pragma Subtitle ([Subtitle =>] STRING_LITERAL); | |
7851 | @end example | |
7852 | ||
7853 | This pragma is recognized for compatibility with other Ada compilers | |
7854 | but is ignored by GNAT. | |
7855 | ||
7856 | @node Pragma Suppress,Pragma Suppress_All,Pragma Subtitle,Implementation Defined Pragmas | |
b71d4b62 | 7857 | @anchor{gnat_rm/implementation_defined_pragmas pragma-suppress}@anchor{f3} |
64d5610f ML |
7858 | @section Pragma Suppress |
7859 | ||
7860 | ||
7861 | Syntax: | |
7862 | ||
7863 | @example | |
7864 | pragma Suppress (Identifier [, [On =>] Name]); | |
7865 | @end example | |
7866 | ||
7867 | This is a standard pragma, and supports all the check names required in | |
7868 | the RM. It is included here because GNAT recognizes some additional check | |
7869 | names that are implementation defined (as permitted by the RM): | |
7870 | ||
7871 | ||
7872 | @itemize * | |
7873 | ||
7874 | @item | |
7875 | @code{Alignment_Check} can be used to suppress alignment checks | |
7876 | on addresses used in address clauses. Such checks can also be suppressed | |
7877 | by suppressing range checks, but the specific use of @code{Alignment_Check} | |
7878 | allows suppression of alignment checks without suppressing other range checks. | |
7879 | Note that @code{Alignment_Check} is suppressed by default on machines (such as | |
7880 | the x86) with non-strict alignment. | |
7881 | ||
7882 | @item | |
7883 | @code{Atomic_Synchronization} can be used to suppress the special memory | |
7884 | synchronization instructions that are normally generated for access to | |
7885 | @code{Atomic} variables to ensure correct synchronization between tasks | |
7886 | that use such variables for synchronization purposes. | |
7887 | ||
7888 | @item | |
7889 | @code{Duplicated_Tag_Check} Can be used to suppress the check that is generated | |
7890 | for a duplicated tag value when a tagged type is declared. | |
7891 | ||
7892 | @item | |
7893 | @code{Container_Checks} Can be used to suppress all checks within Ada.Containers | |
7894 | and instances of its children, including Tampering_Check. | |
7895 | ||
7896 | @item | |
7897 | @code{Tampering_Check} Can be used to suppress tampering check in the containers. | |
7898 | ||
7899 | @item | |
7900 | @code{Predicate_Check} can be used to control whether predicate checks are | |
7901 | active. It is applicable only to predicates for which the policy is | |
7902 | @code{Check}. Unlike @code{Assertion_Policy}, which determines if a given | |
7903 | predicate is ignored or checked for the whole program, the use of | |
7904 | @code{Suppress} and @code{Unsuppress} with this check name allows a given | |
7905 | predicate to be turned on and off at specific points in the program. | |
7906 | ||
7907 | @item | |
7908 | @code{Validity_Check} can be used specifically to control validity checks. | |
7909 | If @code{Suppress} is used to suppress validity checks, then no validity | |
7910 | checks are performed, including those specified by the appropriate compiler | |
7911 | switch or the @code{Validity_Checks} pragma. | |
7912 | ||
7913 | @item | |
7914 | Additional check names previously introduced by use of the @code{Check_Name} | |
7915 | pragma are also allowed. | |
7916 | @end itemize | |
7917 | ||
7918 | Note that pragma Suppress gives the compiler permission to omit | |
7919 | checks, but does not require the compiler to omit checks. The compiler | |
7920 | will generate checks if they are essentially free, even when they are | |
7921 | suppressed. In particular, if the compiler can prove that a certain | |
7922 | check will necessarily fail, it will generate code to do an | |
7923 | unconditional ‘raise’, even if checks are suppressed. The compiler | |
7924 | warns in this case. | |
7925 | ||
7926 | Of course, run-time checks are omitted whenever the compiler can prove | |
7927 | that they will not fail, whether or not checks are suppressed. | |
7928 | ||
7929 | @node Pragma Suppress_All,Pragma Suppress_Debug_Info,Pragma Suppress,Implementation Defined Pragmas | |
b71d4b62 | 7930 | @anchor{gnat_rm/implementation_defined_pragmas pragma-suppress-all}@anchor{f4} |
64d5610f ML |
7931 | @section Pragma Suppress_All |
7932 | ||
7933 | ||
7934 | Syntax: | |
7935 | ||
7936 | @example | |
7937 | pragma Suppress_All; | |
7938 | @end example | |
7939 | ||
7940 | This pragma can appear anywhere within a unit. | |
7941 | The effect is to apply @code{Suppress (All_Checks)} to the unit | |
7942 | in which it appears. This pragma is implemented for compatibility with DEC | |
7943 | Ada 83 usage where it appears at the end of a unit, and for compatibility | |
7944 | with Rational Ada, where it appears as a program unit pragma. | |
7945 | The use of the standard Ada pragma @code{Suppress (All_Checks)} | |
7946 | as a normal configuration pragma is the preferred usage in GNAT. | |
7947 | ||
7948 | @node Pragma Suppress_Debug_Info,Pragma Suppress_Exception_Locations,Pragma Suppress_All,Implementation Defined Pragmas | |
b71d4b62 | 7949 | @anchor{gnat_rm/implementation_defined_pragmas id44}@anchor{f5}@anchor{gnat_rm/implementation_defined_pragmas pragma-suppress-debug-info}@anchor{f6} |
64d5610f ML |
7950 | @section Pragma Suppress_Debug_Info |
7951 | ||
7952 | ||
7953 | Syntax: | |
7954 | ||
7955 | @example | |
7956 | pragma Suppress_Debug_Info ([Entity =>] LOCAL_NAME); | |
7957 | @end example | |
7958 | ||
7959 | This pragma can be used to suppress generation of debug information | |
7960 | for the specified entity. It is intended primarily for use in debugging | |
7961 | the debugger, and navigating around debugger problems. | |
7962 | ||
7963 | @node Pragma Suppress_Exception_Locations,Pragma Suppress_Initialization,Pragma Suppress_Debug_Info,Implementation Defined Pragmas | |
b71d4b62 | 7964 | @anchor{gnat_rm/implementation_defined_pragmas pragma-suppress-exception-locations}@anchor{f7} |
64d5610f ML |
7965 | @section Pragma Suppress_Exception_Locations |
7966 | ||
7967 | ||
7968 | Syntax: | |
7969 | ||
7970 | @example | |
7971 | pragma Suppress_Exception_Locations; | |
7972 | @end example | |
7973 | ||
7974 | In normal mode, a raise statement for an exception by default generates | |
7975 | an exception message giving the file name and line number for the location | |
7976 | of the raise. This is useful for debugging and logging purposes, but this | |
7977 | entails extra space for the strings for the messages. The configuration | |
7978 | pragma @code{Suppress_Exception_Locations} can be used to suppress the | |
7979 | generation of these strings, with the result that space is saved, but the | |
7980 | exception message for such raises is null. This configuration pragma may | |
7981 | appear in a global configuration pragma file, or in a specific unit as | |
7982 | usual. It is not required that this pragma be used consistently within | |
7983 | a partition, so it is fine to have some units within a partition compiled | |
7984 | with this pragma and others compiled in normal mode without it. | |
7985 | ||
7986 | @node Pragma Suppress_Initialization,Pragma Task_Name,Pragma Suppress_Exception_Locations,Implementation Defined Pragmas | |
b71d4b62 | 7987 | @anchor{gnat_rm/implementation_defined_pragmas id45}@anchor{f8}@anchor{gnat_rm/implementation_defined_pragmas pragma-suppress-initialization}@anchor{f9} |
64d5610f ML |
7988 | @section Pragma Suppress_Initialization |
7989 | ||
7990 | ||
7991 | @geindex Suppressing initialization | |
7992 | ||
7993 | @geindex Initialization | |
7994 | @geindex suppression of | |
7995 | ||
7996 | Syntax: | |
7997 | ||
7998 | @example | |
7999 | pragma Suppress_Initialization ([Entity =>] variable_or_subtype_Name); | |
8000 | @end example | |
8001 | ||
8002 | Here variable_or_subtype_Name is the name introduced by a type declaration | |
8003 | or subtype declaration or the name of a variable introduced by an | |
8004 | object declaration. | |
8005 | ||
8006 | In the case of a type or subtype | |
8007 | this pragma suppresses any implicit or explicit initialization | |
8008 | for all variables of the given type or subtype, | |
8009 | including initialization resulting from the use of pragmas | |
8010 | Normalize_Scalars or Initialize_Scalars. | |
8011 | ||
8012 | This is considered a representation item, so it cannot be given after | |
8013 | the type is frozen. It applies to all subsequent object declarations, | |
8014 | and also any allocator that creates objects of the type. | |
8015 | ||
8016 | If the pragma is given for the first subtype, then it is considered | |
8017 | to apply to the base type and all its subtypes. If the pragma is given | |
8018 | for other than a first subtype, then it applies only to the given subtype. | |
8019 | The pragma may not be given after the type is frozen. | |
8020 | ||
8021 | Note that this includes eliminating initialization of discriminants | |
8022 | for discriminated types, and tags for tagged types. In these cases, | |
8023 | you will have to use some non-portable mechanism (e.g. address | |
8024 | overlays or unchecked conversion) to achieve required initialization | |
8025 | of these fields before accessing any object of the corresponding type. | |
8026 | ||
8027 | For the variable case, implicit initialization for the named variable | |
8028 | is suppressed, just as though its subtype had been given in a pragma | |
8029 | Suppress_Initialization, as described above. | |
8030 | ||
8031 | @node Pragma Task_Name,Pragma Task_Storage,Pragma Suppress_Initialization,Implementation Defined Pragmas | |
b71d4b62 | 8032 | @anchor{gnat_rm/implementation_defined_pragmas pragma-task-name}@anchor{fa} |
64d5610f ML |
8033 | @section Pragma Task_Name |
8034 | ||
8035 | ||
8036 | Syntax | |
8037 | ||
8038 | @example | |
8039 | pragma Task_Name (string_EXPRESSION); | |
8040 | @end example | |
8041 | ||
8042 | This pragma appears within a task definition (like pragma | |
8043 | @code{Priority}) and applies to the task in which it appears. The | |
8044 | argument must be of type String, and provides a name to be used for | |
8045 | the task instance when the task is created. Note that this expression | |
8046 | is not required to be static, and in particular, it can contain | |
8047 | references to task discriminants. This facility can be used to | |
8048 | provide different names for different tasks as they are created, | |
8049 | as illustrated in the example below. | |
8050 | ||
8051 | The task name is recorded internally in the run-time structures | |
8052 | and is accessible to tools like the debugger. In addition the | |
8053 | routine @code{Ada.Task_Identification.Image} will return this | |
8054 | string, with a unique task address appended. | |
8055 | ||
8056 | @example | |
8057 | -- Example of the use of pragma Task_Name | |
8058 | ||
8059 | with Ada.Task_Identification; | |
8060 | use Ada.Task_Identification; | |
8061 | with Text_IO; use Text_IO; | |
8062 | procedure t3 is | |
8063 | ||
8064 | type Astring is access String; | |
8065 | ||
8066 | task type Task_Typ (Name : access String) is | |
8067 | pragma Task_Name (Name.all); | |
8068 | end Task_Typ; | |
8069 | ||
8070 | task body Task_Typ is | |
8071 | Nam : constant String := Image (Current_Task); | |
8072 | begin | |
8073 | Put_Line ("-->" & Nam (1 .. 14) & "<--"); | |
8074 | end Task_Typ; | |
8075 | ||
8076 | type Ptr_Task is access Task_Typ; | |
8077 | Task_Var : Ptr_Task; | |
8078 | ||
8079 | begin | |
8080 | Task_Var := | |
8081 | new Task_Typ (new String'("This is task 1")); | |
8082 | Task_Var := | |
8083 | new Task_Typ (new String'("This is task 2")); | |
8084 | end; | |
8085 | @end example | |
8086 | ||
8087 | @node Pragma Task_Storage,Pragma Test_Case,Pragma Task_Name,Implementation Defined Pragmas | |
b71d4b62 | 8088 | @anchor{gnat_rm/implementation_defined_pragmas pragma-task-storage}@anchor{fb} |
64d5610f ML |
8089 | @section Pragma Task_Storage |
8090 | ||
8091 | ||
8092 | Syntax: | |
8093 | ||
8094 | @example | |
8095 | pragma Task_Storage ( | |
8096 | [Task_Type =>] LOCAL_NAME, | |
8097 | [Top_Guard =>] static_integer_EXPRESSION); | |
8098 | @end example | |
8099 | ||
8100 | This pragma specifies the length of the guard area for tasks. The guard | |
8101 | area is an additional storage area allocated to a task. A value of zero | |
8102 | means that either no guard area is created or a minimal guard area is | |
8103 | created, depending on the target. This pragma can appear anywhere a | |
8104 | @code{Storage_Size} attribute definition clause is allowed for a task | |
8105 | type. | |
8106 | ||
8107 | @node Pragma Test_Case,Pragma Thread_Local_Storage,Pragma Task_Storage,Implementation Defined Pragmas | |
b71d4b62 | 8108 | @anchor{gnat_rm/implementation_defined_pragmas id46}@anchor{fc}@anchor{gnat_rm/implementation_defined_pragmas pragma-test-case}@anchor{fd} |
64d5610f ML |
8109 | @section Pragma Test_Case |
8110 | ||
8111 | ||
8112 | @geindex Test cases | |
8113 | ||
8114 | Syntax: | |
8115 | ||
8116 | @example | |
8117 | pragma Test_Case ( | |
8118 | [Name =>] static_string_Expression | |
8119 | ,[Mode =>] (Nominal | Robustness) | |
8120 | [, Requires => Boolean_Expression] | |
8121 | [, Ensures => Boolean_Expression]); | |
8122 | @end example | |
8123 | ||
8124 | The @code{Test_Case} pragma allows defining fine-grain specifications | |
8125 | for use by testing tools. | |
8126 | The compiler checks the validity of the @code{Test_Case} pragma, but its | |
8127 | presence does not lead to any modification of the code generated by the | |
8128 | compiler. | |
8129 | ||
8130 | @code{Test_Case} pragmas may only appear immediately following the | |
8131 | (separate) declaration of a subprogram in a package declaration, inside | |
8132 | a package spec unit. Only other pragmas may intervene (that is appear | |
8133 | between the subprogram declaration and a test case). | |
8134 | ||
8135 | The compiler checks that boolean expressions given in @code{Requires} and | |
8136 | @code{Ensures} are valid, where the rules for @code{Requires} are the | |
8137 | same as the rule for an expression in @code{Precondition} and the rules | |
8138 | for @code{Ensures} are the same as the rule for an expression in | |
8139 | @code{Postcondition}. In particular, attributes @code{'Old} and | |
8140 | @code{'Result} can only be used within the @code{Ensures} | |
8141 | expression. The following is an example of use within a package spec: | |
8142 | ||
8143 | @example | |
8144 | package Math_Functions is | |
8145 | ... | |
8146 | function Sqrt (Arg : Float) return Float; | |
8147 | pragma Test_Case (Name => "Test 1", | |
8148 | Mode => Nominal, | |
8149 | Requires => Arg < 10000.0, | |
8150 | Ensures => Sqrt'Result < 10.0); | |
8151 | ... | |
8152 | end Math_Functions; | |
8153 | @end example | |
8154 | ||
8155 | The meaning of a test case is that there is at least one context where | |
8156 | @code{Requires} holds such that, if the associated subprogram is executed in | |
8157 | that context, then @code{Ensures} holds when the subprogram returns. | |
8158 | Mode @code{Nominal} indicates that the input context should also satisfy the | |
8159 | precondition of the subprogram, and the output context should also satisfy its | |
8160 | postcondition. Mode @code{Robustness} indicates that the precondition and | |
8161 | postcondition of the subprogram should be ignored for this test case. | |
8162 | ||
8163 | @node Pragma Thread_Local_Storage,Pragma Time_Slice,Pragma Test_Case,Implementation Defined Pragmas | |
b71d4b62 | 8164 | @anchor{gnat_rm/implementation_defined_pragmas id47}@anchor{fe}@anchor{gnat_rm/implementation_defined_pragmas pragma-thread-local-storage}@anchor{ff} |
64d5610f ML |
8165 | @section Pragma Thread_Local_Storage |
8166 | ||
8167 | ||
8168 | @geindex Task specific storage | |
8169 | ||
8170 | @geindex TLS (Thread Local Storage) | |
8171 | ||
8172 | @geindex Task_Attributes | |
8173 | ||
8174 | Syntax: | |
8175 | ||
8176 | @example | |
8177 | pragma Thread_Local_Storage ([Entity =>] LOCAL_NAME); | |
8178 | @end example | |
8179 | ||
8180 | This pragma specifies that the specified entity, which must be | |
8181 | a variable declared in a library-level package, is to be marked as | |
8182 | “Thread Local Storage” (@code{TLS}). On systems supporting this (which | |
8183 | include Windows, Solaris, GNU/Linux, and VxWorks), this causes each | |
8184 | thread (and hence each Ada task) to see a distinct copy of the variable. | |
8185 | ||
8186 | The variable must not have default initialization, and if there is | |
8187 | an explicit initialization, it must be either @code{null} for an | |
8188 | access variable, a static expression for a scalar variable, or a fully | |
8189 | static aggregate for a composite type, that is to say, an aggregate all | |
8190 | of whose components are static, and which does not include packed or | |
8191 | discriminated components. | |
8192 | ||
8193 | This provides a low-level mechanism similar to that provided by | |
8194 | the @code{Ada.Task_Attributes} package, but much more efficient | |
8195 | and is also useful in writing interface code that will interact | |
8196 | with foreign threads. | |
8197 | ||
8198 | If this pragma is used on a system where @code{TLS} is not supported, | |
8199 | then an error message will be generated and the program will be rejected. | |
8200 | ||
8201 | @node Pragma Time_Slice,Pragma Title,Pragma Thread_Local_Storage,Implementation Defined Pragmas | |
b71d4b62 | 8202 | @anchor{gnat_rm/implementation_defined_pragmas pragma-time-slice}@anchor{100} |
64d5610f ML |
8203 | @section Pragma Time_Slice |
8204 | ||
8205 | ||
8206 | Syntax: | |
8207 | ||
8208 | @example | |
8209 | pragma Time_Slice (static_duration_EXPRESSION); | |
8210 | @end example | |
8211 | ||
8212 | For implementations of GNAT on operating systems where it is possible | |
8213 | to supply a time slice value, this pragma may be used for this purpose. | |
8214 | It is ignored if it is used in a system that does not allow this control, | |
8215 | or if it appears in other than the main program unit. | |
8216 | ||
8217 | @node Pragma Title,Pragma Type_Invariant,Pragma Time_Slice,Implementation Defined Pragmas | |
b71d4b62 | 8218 | @anchor{gnat_rm/implementation_defined_pragmas pragma-title}@anchor{101} |
64d5610f ML |
8219 | @section Pragma Title |
8220 | ||
8221 | ||
8222 | Syntax: | |
8223 | ||
8224 | @example | |
8225 | pragma Title (TITLING_OPTION [, TITLING OPTION]); | |
8226 | ||
8227 | TITLING_OPTION ::= | |
8228 | [Title =>] STRING_LITERAL, | |
8229 | | [Subtitle =>] STRING_LITERAL | |
8230 | @end example | |
8231 | ||
8232 | Syntax checked but otherwise ignored by GNAT. This is a listing control | |
8233 | pragma used in DEC Ada 83 implementations to provide a title and/or | |
8234 | subtitle for the program listing. The program listing generated by GNAT | |
8235 | does not have titles or subtitles. | |
8236 | ||
8237 | Unlike other pragmas, the full flexibility of named notation is allowed | |
8238 | for this pragma, i.e., the parameters may be given in any order if named | |
8239 | notation is used, and named and positional notation can be mixed | |
8240 | following the normal rules for procedure calls in Ada. | |
8241 | ||
8242 | @node Pragma Type_Invariant,Pragma Type_Invariant_Class,Pragma Title,Implementation Defined Pragmas | |
b71d4b62 | 8243 | @anchor{gnat_rm/implementation_defined_pragmas pragma-type-invariant}@anchor{102} |
64d5610f ML |
8244 | @section Pragma Type_Invariant |
8245 | ||
8246 | ||
8247 | Syntax: | |
8248 | ||
8249 | @example | |
8250 | pragma Type_Invariant | |
8251 | ([Entity =>] type_LOCAL_NAME, | |
8252 | [Check =>] EXPRESSION); | |
8253 | @end example | |
8254 | ||
8255 | The @code{Type_Invariant} pragma is intended to be an exact | |
8256 | replacement for the language-defined @code{Type_Invariant} | |
8257 | aspect, and shares its restrictions and semantics. It differs | |
8258 | from the language defined @code{Invariant} pragma in that it | |
8259 | does not permit a string parameter, and it is | |
8260 | controlled by the assertion identifier @code{Type_Invariant} | |
8261 | rather than @code{Invariant}. | |
8262 | ||
8263 | @node Pragma Type_Invariant_Class,Pragma Unchecked_Union,Pragma Type_Invariant,Implementation Defined Pragmas | |
b71d4b62 | 8264 | @anchor{gnat_rm/implementation_defined_pragmas id48}@anchor{103}@anchor{gnat_rm/implementation_defined_pragmas pragma-type-invariant-class}@anchor{104} |
64d5610f ML |
8265 | @section Pragma Type_Invariant_Class |
8266 | ||
8267 | ||
8268 | Syntax: | |
8269 | ||
8270 | @example | |
8271 | pragma Type_Invariant_Class | |
8272 | ([Entity =>] type_LOCAL_NAME, | |
8273 | [Check =>] EXPRESSION); | |
8274 | @end example | |
8275 | ||
8276 | The @code{Type_Invariant_Class} pragma is intended to be an exact | |
8277 | replacement for the language-defined @code{Type_Invariant'Class} | |
8278 | aspect, and shares its restrictions and semantics. | |
8279 | ||
8280 | Note: This pragma is called @code{Type_Invariant_Class} rather than | |
8281 | @code{Type_Invariant'Class} because the latter would not be strictly | |
8282 | conforming to the allowed syntax for pragmas. The motivation | |
8283 | for providing pragmas equivalent to the aspects is to allow a program | |
8284 | to be written using the pragmas, and then compiled if necessary | |
8285 | using an Ada compiler that does not recognize the pragmas or | |
8286 | aspects, but is prepared to ignore the pragmas. The assertion | |
8287 | policy that controls this pragma is @code{Type_Invariant'Class}, | |
8288 | not @code{Type_Invariant_Class}. | |
8289 | ||
8290 | @node Pragma Unchecked_Union,Pragma Unevaluated_Use_Of_Old,Pragma Type_Invariant_Class,Implementation Defined Pragmas | |
b71d4b62 | 8291 | @anchor{gnat_rm/implementation_defined_pragmas pragma-unchecked-union}@anchor{105} |
64d5610f ML |
8292 | @section Pragma Unchecked_Union |
8293 | ||
8294 | ||
8295 | @geindex Unions in C | |
8296 | ||
8297 | Syntax: | |
8298 | ||
8299 | @example | |
8300 | pragma Unchecked_Union (first_subtype_LOCAL_NAME); | |
8301 | @end example | |
8302 | ||
8303 | This pragma is used to specify a representation of a record type that is | |
8304 | equivalent to a C union. It was introduced as a GNAT implementation defined | |
8305 | pragma in the GNAT Ada 95 mode. Ada 2005 includes an extended version of this | |
8306 | pragma, making it language defined, and GNAT fully implements this extended | |
8307 | version in all language modes (Ada 83, Ada 95, and Ada 2005). For full | |
8308 | details, consult the Ada 2012 Reference Manual, section B.3.3. | |
8309 | ||
8310 | @node Pragma Unevaluated_Use_Of_Old,Pragma Unimplemented_Unit,Pragma Unchecked_Union,Implementation Defined Pragmas | |
b71d4b62 | 8311 | @anchor{gnat_rm/implementation_defined_pragmas pragma-unevaluated-use-of-old}@anchor{106} |
64d5610f ML |
8312 | @section Pragma Unevaluated_Use_Of_Old |
8313 | ||
8314 | ||
8315 | @geindex Attribute Old | |
8316 | ||
8317 | @geindex Attribute Loop_Entry | |
8318 | ||
8319 | @geindex Unevaluated_Use_Of_Old | |
8320 | ||
8321 | Syntax: | |
8322 | ||
8323 | @example | |
8324 | pragma Unevaluated_Use_Of_Old (Error | Warn | Allow); | |
8325 | @end example | |
8326 | ||
8327 | This pragma controls the processing of attributes Old and Loop_Entry. | |
8328 | If either of these attributes is used in a potentially unevaluated | |
8329 | expression (e.g. the then or else parts of an if expression), then | |
8330 | normally this usage is considered illegal if the prefix of the attribute | |
8331 | is other than an entity name. The language requires this | |
8332 | behavior for Old, and GNAT copies the same rule for Loop_Entry. | |
8333 | ||
8334 | The reason for this rule is that otherwise, we can have a situation | |
8335 | where we save the Old value, and this results in an exception, even | |
8336 | though we might not evaluate the attribute. Consider this example: | |
8337 | ||
8338 | @example | |
8339 | package UnevalOld is | |
8340 | K : Character; | |
8341 | procedure U (A : String; C : Boolean) -- ERROR | |
8342 | with Post => (if C then A(1)'Old = K else True); | |
8343 | end; | |
8344 | @end example | |
8345 | ||
8346 | If procedure U is called with a string with a lower bound of 2, and | |
8347 | C false, then an exception would be raised trying to evaluate A(1) | |
8348 | on entry even though the value would not be actually used. | |
8349 | ||
8350 | Although the rule guarantees against this possibility, it is sometimes | |
8351 | too restrictive. For example if we know that the string has a lower | |
8352 | bound of 1, then we will never raise an exception. | |
8353 | The pragma @code{Unevaluated_Use_Of_Old} can be | |
8354 | used to modify this behavior. If the argument is @code{Error} then an | |
8355 | error is given (this is the default RM behavior). If the argument is | |
8356 | @code{Warn} then the usage is allowed as legal but with a warning | |
8357 | that an exception might be raised. If the argument is @code{Allow} | |
8358 | then the usage is allowed as legal without generating a warning. | |
8359 | ||
8360 | This pragma may appear as a configuration pragma, or in a declarative | |
8361 | part or package specification. In the latter case it applies to | |
8362 | uses up to the end of the corresponding statement sequence or | |
8363 | sequence of package declarations. | |
8364 | ||
8365 | @node Pragma Unimplemented_Unit,Pragma Universal_Aliasing,Pragma Unevaluated_Use_Of_Old,Implementation Defined Pragmas | |
b71d4b62 | 8366 | @anchor{gnat_rm/implementation_defined_pragmas pragma-unimplemented-unit}@anchor{107} |
64d5610f ML |
8367 | @section Pragma Unimplemented_Unit |
8368 | ||
8369 | ||
8370 | Syntax: | |
8371 | ||
8372 | @example | |
8373 | pragma Unimplemented_Unit; | |
8374 | @end example | |
8375 | ||
8376 | If this pragma occurs in a unit that is processed by the compiler, GNAT | |
8377 | aborts with the message @code{xxx not implemented}, where | |
8378 | @code{xxx} is the name of the current compilation unit. This pragma is | |
8379 | intended to allow the compiler to handle unimplemented library units in | |
8380 | a clean manner. | |
8381 | ||
8382 | The abort only happens if code is being generated. Thus you can use | |
8383 | specs of unimplemented packages in syntax or semantic checking mode. | |
8384 | ||
8385 | @node Pragma Universal_Aliasing,Pragma Unmodified,Pragma Unimplemented_Unit,Implementation Defined Pragmas | |
b71d4b62 | 8386 | @anchor{gnat_rm/implementation_defined_pragmas id49}@anchor{108}@anchor{gnat_rm/implementation_defined_pragmas pragma-universal-aliasing}@anchor{109} |
64d5610f ML |
8387 | @section Pragma Universal_Aliasing |
8388 | ||
8389 | ||
8390 | Syntax: | |
8391 | ||
8392 | @example | |
8393 | pragma Universal_Aliasing [([Entity =>] type_LOCAL_NAME)]; | |
8394 | @end example | |
8395 | ||
8396 | @code{type_LOCAL_NAME} must refer to a type declaration in the current | |
8397 | declarative part. The effect is to inhibit strict type-based aliasing | |
8398 | optimization for the given type. In other words, the effect is as though | |
8399 | access types designating this type were subject to pragma No_Strict_Aliasing. | |
8400 | For a detailed description of the strict aliasing optimization, and the | |
8401 | situations in which it must be suppressed, see the section on | |
8402 | @code{Optimization and Strict Aliasing} in the @cite{GNAT User’s Guide}. | |
8403 | ||
8404 | @node Pragma Unmodified,Pragma Unreferenced,Pragma Universal_Aliasing,Implementation Defined Pragmas | |
b71d4b62 | 8405 | @anchor{gnat_rm/implementation_defined_pragmas id50}@anchor{10a}@anchor{gnat_rm/implementation_defined_pragmas pragma-unmodified}@anchor{10b} |
64d5610f ML |
8406 | @section Pragma Unmodified |
8407 | ||
8408 | ||
8409 | @geindex Warnings | |
8410 | @geindex unmodified | |
8411 | ||
8412 | Syntax: | |
8413 | ||
8414 | @example | |
8415 | pragma Unmodified (LOCAL_NAME @{, LOCAL_NAME@}); | |
8416 | @end example | |
8417 | ||
8418 | This pragma signals that the assignable entities (variables, | |
8419 | @code{out} parameters, @code{in out} parameters) whose names are listed are | |
8420 | deliberately not assigned in the current source unit. This | |
8421 | suppresses warnings about the | |
8422 | entities being referenced but not assigned, and in addition a warning will be | |
8423 | generated if one of these entities is in fact assigned in the | |
8424 | same unit as the pragma (or in the corresponding body, or one | |
8425 | of its subunits). | |
8426 | ||
8427 | This is particularly useful for clearly signaling that a particular | |
8428 | parameter is not modified, even though the spec suggests that it might | |
8429 | be. | |
8430 | ||
8431 | For the variable case, warnings are never given for unreferenced variables | |
8432 | whose name contains one of the substrings | |
8433 | @code{DISCARD, DUMMY, IGNORE, JUNK, UNUSE, TMP, TEMP} in any casing. Such names | |
8434 | are typically to be used in cases where such warnings are expected. | |
8435 | Thus it is never necessary to use @code{pragma Unmodified} for such | |
8436 | variables, though it is harmless to do so. | |
8437 | ||
8438 | @node Pragma Unreferenced,Pragma Unreferenced_Objects,Pragma Unmodified,Implementation Defined Pragmas | |
b71d4b62 | 8439 | @anchor{gnat_rm/implementation_defined_pragmas id51}@anchor{10c}@anchor{gnat_rm/implementation_defined_pragmas pragma-unreferenced}@anchor{10d} |
64d5610f ML |
8440 | @section Pragma Unreferenced |
8441 | ||
8442 | ||
8443 | @geindex Warnings | |
8444 | @geindex unreferenced | |
8445 | ||
8446 | Syntax: | |
8447 | ||
8448 | @example | |
8449 | pragma Unreferenced (LOCAL_NAME @{, LOCAL_NAME@}); | |
8450 | pragma Unreferenced (library_unit_NAME @{, library_unit_NAME@}); | |
8451 | @end example | |
8452 | ||
8453 | This pragma signals that the entities whose names are listed are | |
8454 | deliberately not referenced in the current source unit after the | |
8455 | occurrence of the pragma. This | |
8456 | suppresses warnings about the | |
8457 | entities being unreferenced, and in addition a warning will be | |
8458 | generated if one of these entities is in fact subsequently referenced in the | |
8459 | same unit as the pragma (or in the corresponding body, or one | |
8460 | of its subunits). | |
8461 | ||
8462 | This is particularly useful for clearly signaling that a particular | |
8463 | parameter is not referenced in some particular subprogram implementation | |
8464 | and that this is deliberate. It can also be useful in the case of | |
8465 | objects declared only for their initialization or finalization side | |
8466 | effects. | |
8467 | ||
8468 | If @code{LOCAL_NAME} identifies more than one matching homonym in the | |
8469 | current scope, then the entity most recently declared is the one to which | |
8470 | the pragma applies. Note that in the case of accept formals, the pragma | |
8471 | Unreferenced may appear immediately after the keyword @code{do} which | |
8472 | allows the indication of whether or not accept formals are referenced | |
8473 | or not to be given individually for each accept statement. | |
8474 | ||
8475 | The left hand side of an assignment does not count as a reference for the | |
8476 | purpose of this pragma. Thus it is fine to assign to an entity for which | |
8477 | pragma Unreferenced is given. However, use of an entity as an actual for | |
8478 | an out parameter does count as a reference unless warnings for unread output | |
8479 | parameters are enabled via @code{-gnatw.o}. | |
8480 | ||
8481 | Note that if a warning is desired for all calls to a given subprogram, | |
8482 | regardless of whether they occur in the same unit as the subprogram | |
8483 | declaration, then this pragma should not be used (calls from another | |
8484 | unit would not be flagged); pragma Obsolescent can be used instead | |
b71d4b62 | 8485 | for this purpose, see @ref{af,,Pragma Obsolescent}. |
64d5610f ML |
8486 | |
8487 | The second form of pragma @code{Unreferenced} is used within a context | |
8488 | clause. In this case the arguments must be unit names of units previously | |
8489 | mentioned in @code{with} clauses (similar to the usage of pragma | |
8490 | @code{Elaborate_All}). The effect is to suppress warnings about unreferenced | |
8491 | units and unreferenced entities within these units. | |
8492 | ||
8493 | For the variable case, warnings are never given for unreferenced variables | |
8494 | whose name contains one of the substrings | |
8495 | @code{DISCARD, DUMMY, IGNORE, JUNK, UNUSED} in any casing. Such names | |
8496 | are typically to be used in cases where such warnings are expected. | |
8497 | Thus it is never necessary to use @code{pragma Unreferenced} for such | |
8498 | variables, though it is harmless to do so. | |
8499 | ||
8500 | @node Pragma Unreferenced_Objects,Pragma Unreserve_All_Interrupts,Pragma Unreferenced,Implementation Defined Pragmas | |
b71d4b62 | 8501 | @anchor{gnat_rm/implementation_defined_pragmas id52}@anchor{10e}@anchor{gnat_rm/implementation_defined_pragmas pragma-unreferenced-objects}@anchor{10f} |
64d5610f ML |
8502 | @section Pragma Unreferenced_Objects |
8503 | ||
8504 | ||
8505 | @geindex Warnings | |
8506 | @geindex unreferenced | |
8507 | ||
8508 | Syntax: | |
8509 | ||
8510 | @example | |
8511 | pragma Unreferenced_Objects (local_subtype_NAME @{, local_subtype_NAME@}); | |
8512 | @end example | |
8513 | ||
8514 | This pragma signals that for the types or subtypes whose names are | |
8515 | listed, objects which are declared with one of these types or subtypes may | |
8516 | not be referenced, and if no references appear, no warnings are given. | |
8517 | ||
8518 | This is particularly useful for objects which are declared solely for their | |
8519 | initialization and finalization effect. Such variables are sometimes referred | |
8520 | to as RAII variables (Resource Acquisition Is Initialization). Using this | |
8521 | pragma on the relevant type (most typically a limited controlled type), the | |
8522 | compiler will automatically suppress unwanted warnings about these variables | |
8523 | not being referenced. | |
8524 | ||
8525 | @node Pragma Unreserve_All_Interrupts,Pragma Unsuppress,Pragma Unreferenced_Objects,Implementation Defined Pragmas | |
b71d4b62 | 8526 | @anchor{gnat_rm/implementation_defined_pragmas pragma-unreserve-all-interrupts}@anchor{110} |
64d5610f ML |
8527 | @section Pragma Unreserve_All_Interrupts |
8528 | ||
8529 | ||
8530 | Syntax: | |
8531 | ||
8532 | @example | |
8533 | pragma Unreserve_All_Interrupts; | |
8534 | @end example | |
8535 | ||
8536 | Normally certain interrupts are reserved to the implementation. Any attempt | |
8537 | to attach an interrupt causes Program_Error to be raised, as described in | |
8538 | RM C.3.2(22). A typical example is the @code{SIGINT} interrupt used in | |
8539 | many systems for a @code{Ctrl-C} interrupt. Normally this interrupt is | |
8540 | reserved to the implementation, so that @code{Ctrl-C} can be used to | |
8541 | interrupt execution. | |
8542 | ||
8543 | If the pragma @code{Unreserve_All_Interrupts} appears anywhere in any unit in | |
8544 | a program, then all such interrupts are unreserved. This allows the | |
8545 | program to handle these interrupts, but disables their standard | |
8546 | functions. For example, if this pragma is used, then pressing | |
8547 | @code{Ctrl-C} will not automatically interrupt execution. However, | |
8548 | a program can then handle the @code{SIGINT} interrupt as it chooses. | |
8549 | ||
8550 | For a full list of the interrupts handled in a specific implementation, | |
8551 | see the source code for the spec of @code{Ada.Interrupts.Names} in | |
8552 | file @code{a-intnam.ads}. This is a target dependent file that contains the | |
8553 | list of interrupts recognized for a given target. The documentation in | |
8554 | this file also specifies what interrupts are affected by the use of | |
8555 | the @code{Unreserve_All_Interrupts} pragma. | |
8556 | ||
8557 | For a more general facility for controlling what interrupts can be | |
8558 | handled, see pragma @code{Interrupt_State}, which subsumes the functionality | |
8559 | of the @code{Unreserve_All_Interrupts} pragma. | |
8560 | ||
6f089469 | 8561 | @node Pragma Unsuppress,Pragma Unused,Pragma Unreserve_All_Interrupts,Implementation Defined Pragmas |
b71d4b62 | 8562 | @anchor{gnat_rm/implementation_defined_pragmas pragma-unsuppress}@anchor{111} |
64d5610f ML |
8563 | @section Pragma Unsuppress |
8564 | ||
8565 | ||
8566 | Syntax: | |
8567 | ||
8568 | @example | |
8569 | pragma Unsuppress (IDENTIFIER [, [On =>] NAME]); | |
8570 | @end example | |
8571 | ||
8572 | This pragma undoes the effect of a previous pragma @code{Suppress}. If | |
8573 | there is no corresponding pragma @code{Suppress} in effect, it has no | |
8574 | effect. The range of the effect is the same as for pragma | |
8575 | @code{Suppress}. The meaning of the arguments is identical to that used | |
8576 | in pragma @code{Suppress}. | |
8577 | ||
8578 | One important application is to ensure that checks are on in cases where | |
8579 | code depends on the checks for its correct functioning, so that the code | |
8580 | will compile correctly even if the compiler switches are set to suppress | |
8581 | checks. For example, in a program that depends on external names of tagged | |
8582 | types and wants to ensure that the duplicated tag check occurs even if all | |
8583 | run-time checks are suppressed by a compiler switch, the following | |
8584 | configuration pragma will ensure this test is not suppressed: | |
8585 | ||
8586 | @example | |
8587 | pragma Unsuppress (Duplicated_Tag_Check); | |
8588 | @end example | |
8589 | ||
8590 | This pragma is standard in Ada 2005. It is available in all earlier versions | |
8591 | of Ada as an implementation-defined pragma. | |
8592 | ||
8593 | Note that in addition to the checks defined in the Ada RM, GNAT recognizes a | |
8594 | number of implementation-defined check names. See the description of pragma | |
8595 | @code{Suppress} for full details. | |
8596 | ||
6f089469 | 8597 | @node Pragma Unused,Pragma Use_VADS_Size,Pragma Unsuppress,Implementation Defined Pragmas |
b71d4b62 | 8598 | @anchor{gnat_rm/implementation_defined_pragmas id53}@anchor{112}@anchor{gnat_rm/implementation_defined_pragmas pragma-unused}@anchor{113} |
64d5610f ML |
8599 | @section Pragma Unused |
8600 | ||
8601 | ||
8602 | @geindex Warnings | |
8603 | @geindex unused | |
8604 | ||
8605 | Syntax: | |
8606 | ||
8607 | @example | |
8608 | pragma Unused (LOCAL_NAME @{, LOCAL_NAME@}); | |
8609 | @end example | |
8610 | ||
8611 | This pragma signals that the assignable entities (variables, | |
8612 | @code{out} parameters, and @code{in out} parameters) whose names are listed | |
8613 | deliberately do not get assigned or referenced in the current source unit | |
8614 | after the occurrence of the pragma in the current source unit. This | |
8615 | suppresses warnings about the entities that are unreferenced and/or not | |
8616 | assigned, and, in addition, a warning will be generated if one of these | |
8617 | entities gets assigned or subsequently referenced in the same unit as the | |
8618 | pragma (in the corresponding body or one of its subunits). | |
8619 | ||
8620 | This is particularly useful for clearly signaling that a particular | |
8621 | parameter is not modified or referenced, even though the spec suggests | |
8622 | that it might be. | |
8623 | ||
8624 | For the variable case, warnings are never given for unreferenced | |
8625 | variables whose name contains one of the substrings | |
8626 | @code{DISCARD, DUMMY, IGNORE, JUNK, UNUSED} in any casing. Such names | |
8627 | are typically to be used in cases where such warnings are expected. | |
8628 | Thus it is never necessary to use @code{pragma Unused} for such | |
8629 | variables, though it is harmless to do so. | |
8630 | ||
6f089469 | 8631 | @node Pragma Use_VADS_Size,Pragma Validity_Checks,Pragma Unused,Implementation Defined Pragmas |
b71d4b62 | 8632 | @anchor{gnat_rm/implementation_defined_pragmas pragma-use-vads-size}@anchor{114} |
6f089469 RD |
8633 | @section Pragma Use_VADS_Size |
8634 | ||
8635 | ||
8636 | @geindex Size | |
8637 | @geindex VADS compatibility | |
8638 | ||
8639 | @geindex Rational profile | |
8640 | ||
8641 | Syntax: | |
8642 | ||
8643 | @example | |
8644 | pragma Use_VADS_Size; | |
8645 | @end example | |
8646 | ||
8647 | This is a configuration pragma. In a unit to which it applies, any use | |
8648 | of the ‘Size attribute is automatically interpreted as a use of the | |
8649 | ‘VADS_Size attribute. Note that this may result in incorrect semantic | |
8650 | processing of valid Ada 95 or Ada 2005 programs. This is intended to aid in | |
8651 | the handling of existing code which depends on the interpretation of Size | |
8652 | as implemented in the VADS compiler. See description of the VADS_Size | |
8653 | attribute for further details. | |
8654 | ||
8655 | @node Pragma Validity_Checks,Pragma Volatile,Pragma Use_VADS_Size,Implementation Defined Pragmas | |
b71d4b62 | 8656 | @anchor{gnat_rm/implementation_defined_pragmas pragma-validity-checks}@anchor{115} |
64d5610f ML |
8657 | @section Pragma Validity_Checks |
8658 | ||
8659 | ||
8660 | Syntax: | |
8661 | ||
8662 | @example | |
8663 | pragma Validity_Checks (string_LITERAL | ALL_CHECKS | On | Off); | |
8664 | @end example | |
8665 | ||
8666 | This pragma is used in conjunction with compiler switches to control the | |
8667 | built-in validity checking provided by GNAT. The compiler switches, if set | |
8668 | provide an initial setting for the switches, and this pragma may be used | |
8669 | to modify these settings, or the settings may be provided entirely by | |
8670 | the use of the pragma. This pragma can be used anywhere that a pragma | |
8671 | is legal, including use as a configuration pragma (including use in | |
8672 | the @code{gnat.adc} file). | |
8673 | ||
8674 | The form with a string literal specifies which validity options are to be | |
8675 | activated. The validity checks are first set to include only the default | |
8676 | reference manual settings, and then a string of letters in the string | |
8677 | specifies the exact set of options required. The form of this string | |
8678 | is exactly as described for the `-gnatVx' compiler switch (see the | |
8679 | GNAT User’s Guide for details). For example the following two | |
8680 | methods can be used to enable validity checking for mode @code{in} and | |
8681 | @code{in out} subprogram parameters: | |
8682 | ||
8683 | ||
8684 | @itemize * | |
8685 | ||
8686 | @item | |
8687 | @example | |
8688 | pragma Validity_Checks ("im"); | |
8689 | @end example | |
8690 | ||
8691 | @item | |
8692 | @example | |
8693 | $ gcc -c -gnatVim ... | |
8694 | @end example | |
8695 | @end itemize | |
8696 | ||
8697 | The form ALL_CHECKS activates all standard checks (its use is equivalent | |
8698 | to the use of the @code{gnatVa} switch). | |
8699 | ||
8700 | The forms with @code{Off} and @code{On} can be used to temporarily disable | |
8701 | validity checks as shown in the following example: | |
8702 | ||
8703 | @example | |
8704 | pragma Validity_Checks ("c"); -- validity checks for copies | |
8705 | pragma Validity_Checks (Off); -- turn off validity checks | |
8706 | A := B; -- B will not be validity checked | |
8707 | pragma Validity_Checks (On); -- turn validity checks back on | |
8708 | A := C; -- C will be validity checked | |
8709 | @end example | |
8710 | ||
8711 | @node Pragma Volatile,Pragma Volatile_Full_Access,Pragma Validity_Checks,Implementation Defined Pragmas | |
b71d4b62 | 8712 | @anchor{gnat_rm/implementation_defined_pragmas id54}@anchor{116}@anchor{gnat_rm/implementation_defined_pragmas pragma-volatile}@anchor{117} |
64d5610f ML |
8713 | @section Pragma Volatile |
8714 | ||
8715 | ||
8716 | Syntax: | |
8717 | ||
8718 | @example | |
8719 | pragma Volatile (LOCAL_NAME); | |
8720 | @end example | |
8721 | ||
8722 | This pragma is defined by the Ada Reference Manual, and the GNAT | |
8723 | implementation is fully conformant with this definition. The reason it | |
8724 | is mentioned in this section is that a pragma of the same name was supplied | |
8725 | in some Ada 83 compilers, including DEC Ada 83. The Ada 95 / Ada 2005 | |
8726 | implementation of pragma Volatile is upwards compatible with the | |
8727 | implementation in DEC Ada 83. | |
8728 | ||
8729 | @node Pragma Volatile_Full_Access,Pragma Volatile_Function,Pragma Volatile,Implementation Defined Pragmas | |
b71d4b62 | 8730 | @anchor{gnat_rm/implementation_defined_pragmas id55}@anchor{118}@anchor{gnat_rm/implementation_defined_pragmas pragma-volatile-full-access}@anchor{119} |
64d5610f ML |
8731 | @section Pragma Volatile_Full_Access |
8732 | ||
8733 | ||
8734 | Syntax: | |
8735 | ||
8736 | @example | |
8737 | pragma Volatile_Full_Access (LOCAL_NAME); | |
8738 | @end example | |
8739 | ||
8740 | This is similar in effect to pragma Volatile, except that any reference to the | |
8741 | object is guaranteed to be done only with instructions that read or write all | |
8742 | the bits of the object. Furthermore, if the object is of a composite type, | |
8743 | then any reference to a subcomponent of the object is guaranteed to read | |
8744 | and/or write all the bits of the object. | |
8745 | ||
8746 | The intention is that this be suitable for use with memory-mapped I/O devices | |
8747 | on some machines. Note that there are two important respects in which this is | |
8748 | different from @code{pragma Atomic}. First a reference to a @code{Volatile_Full_Access} | |
8749 | object is not a sequential action in the RM 9.10 sense and, therefore, does | |
8750 | not create a synchronization point. Second, in the case of @code{pragma Atomic}, | |
8751 | there is no guarantee that all the bits will be accessed if the reference | |
8752 | is not to the whole object; the compiler is allowed (and generally will) | |
8753 | access only part of the object in this case. | |
8754 | ||
8755 | @node Pragma Volatile_Function,Pragma Warning_As_Error,Pragma Volatile_Full_Access,Implementation Defined Pragmas | |
b71d4b62 | 8756 | @anchor{gnat_rm/implementation_defined_pragmas id56}@anchor{11a}@anchor{gnat_rm/implementation_defined_pragmas pragma-volatile-function}@anchor{11b} |
64d5610f ML |
8757 | @section Pragma Volatile_Function |
8758 | ||
8759 | ||
8760 | Syntax: | |
8761 | ||
8762 | @example | |
8763 | pragma Volatile_Function [ (static_boolean_EXPRESSION) ]; | |
8764 | @end example | |
8765 | ||
8766 | For the semantics of this pragma, see the entry for aspect @code{Volatile_Function} | |
8767 | in the SPARK 2014 Reference Manual, section 7.1.2. | |
8768 | ||
8769 | @node Pragma Warning_As_Error,Pragma Warnings,Pragma Volatile_Function,Implementation Defined Pragmas | |
b71d4b62 | 8770 | @anchor{gnat_rm/implementation_defined_pragmas pragma-warning-as-error}@anchor{11c} |
64d5610f ML |
8771 | @section Pragma Warning_As_Error |
8772 | ||
8773 | ||
8774 | Syntax: | |
8775 | ||
8776 | @example | |
8777 | pragma Warning_As_Error (static_string_EXPRESSION); | |
8778 | @end example | |
8779 | ||
8780 | This configuration pragma allows the programmer to specify a set | |
8781 | of warnings that will be treated as errors. Any warning that | |
8782 | matches the pattern given by the pragma argument will be treated | |
8783 | as an error. This gives more precise control than -gnatwe, | |
8784 | which treats warnings as errors. | |
8785 | ||
8786 | This pragma can apply to regular warnings (messages enabled by -gnatw) | |
8787 | and to style warnings (messages that start with “(style)”, | |
8788 | enabled by -gnaty). | |
8789 | ||
8790 | The pattern may contain asterisks, which match zero or more characters | |
8791 | in the message. For example, you can use @code{pragma Warning_As_Error | |
8792 | ("bits of*unused")} to treat the warning message @code{warning: 960 bits of | |
8793 | "a" unused} as an error. All characters other than asterisk are treated | |
8794 | as literal characters in the match. The match is case insensitive; for | |
8795 | example XYZ matches xyz. | |
8796 | ||
8797 | Note that the pattern matches if it occurs anywhere within the warning | |
8798 | message string (it is not necessary to put an asterisk at the start and | |
8799 | the end of the message, since this is implied). | |
8800 | ||
8801 | Another possibility for the static_string_EXPRESSION which works whether | |
8802 | or not error tags are enabled (`-gnatw.d') is to use a single | |
8803 | `-gnatw' tag string, enclosed in brackets, | |
8804 | as shown in the example below, to treat one category of warnings as errors. | |
8805 | Note that if you want to treat multiple categories of warnings as errors, | |
8806 | you can use multiple pragma Warning_As_Error. | |
8807 | ||
8808 | The above use of patterns to match the message applies only to warning | |
8809 | messages generated by the front end. This pragma can also be applied to | |
b71d4b62 | 8810 | warnings provided by the back end and mentioned in @ref{11d,,Pragma Warnings}. |
64d5610f ML |
8811 | By using a single full `-Wxxx' switch in the pragma, such warnings |
8812 | can also be treated as errors. | |
8813 | ||
8814 | The pragma can appear either in a global configuration pragma file | |
8815 | (e.g. @code{gnat.adc}), or at the start of a file. Given a global | |
8816 | configuration pragma file containing: | |
8817 | ||
8818 | @example | |
8819 | pragma Warning_As_Error ("[-gnatwj]"); | |
8820 | @end example | |
8821 | ||
8822 | which will treat all obsolescent feature warnings as errors, the | |
8823 | following program compiles as shown (compile options here are | |
8824 | `-gnatwa.d -gnatl -gnatj55'). | |
8825 | ||
8826 | @example | |
8827 | 1. pragma Warning_As_Error ("*never assigned*"); | |
8828 | 2. function Warnerr return String is | |
8829 | 3. X : Integer; | |
8830 | | | |
8831 | >>> error: variable "X" is never read and | |
8832 | never assigned [-gnatwv] [warning-as-error] | |
8833 | ||
8834 | 4. Y : Integer; | |
8835 | | | |
8836 | >>> warning: variable "Y" is assigned but | |
8837 | never read [-gnatwu] | |
8838 | ||
8839 | 5. begin | |
8840 | 6. Y := 0; | |
8841 | 7. return %ABC%; | |
8842 | | | |
8843 | >>> error: use of "%" is an obsolescent | |
8844 | feature (RM J.2(4)), use """ instead | |
8845 | [-gnatwj] [warning-as-error] | |
8846 | ||
8847 | 8. end; | |
8848 | ||
8849 | 8 lines: No errors, 3 warnings (2 treated as errors) | |
8850 | @end example | |
8851 | ||
8852 | Note that this pragma does not affect the set of warnings issued in | |
8853 | any way, it merely changes the effect of a matching warning if one | |
8854 | is produced as a result of other warnings options. As shown in this | |
8855 | example, if the pragma results in a warning being treated as an error, | |
8856 | the tag is changed from “warning:” to “error:” and the string | |
8857 | “[warning-as-error]” is appended to the end of the message. | |
8858 | ||
8859 | @node Pragma Warnings,Pragma Weak_External,Pragma Warning_As_Error,Implementation Defined Pragmas | |
b71d4b62 | 8860 | @anchor{gnat_rm/implementation_defined_pragmas id57}@anchor{11e}@anchor{gnat_rm/implementation_defined_pragmas pragma-warnings}@anchor{11d} |
64d5610f ML |
8861 | @section Pragma Warnings |
8862 | ||
8863 | ||
8864 | Syntax: | |
8865 | ||
8866 | @example | |
8867 | pragma Warnings ([TOOL_NAME,] DETAILS [, REASON]); | |
8868 | ||
8869 | DETAILS ::= On | Off | |
8870 | DETAILS ::= On | Off, local_NAME | |
8871 | DETAILS ::= static_string_EXPRESSION | |
8872 | DETAILS ::= On | Off, static_string_EXPRESSION | |
8873 | ||
8874 | TOOL_NAME ::= GNAT | GNATprove | |
8875 | ||
8876 | REASON ::= Reason => STRING_LITERAL @{& STRING_LITERAL@} | |
8877 | @end example | |
8878 | ||
8879 | Note: in Ada 83 mode, a string literal may be used in place of a static string | |
8880 | expression (which does not exist in Ada 83). | |
8881 | ||
8882 | Note if the second argument of @code{DETAILS} is a @code{local_NAME} then the | |
8883 | second form is always understood. If the intention is to use | |
8884 | the fourth form, then you can write @code{NAME & ""} to force the | |
8885 | interpretation as a `static_string_EXPRESSION'. | |
8886 | ||
8887 | Note: if the first argument is a valid @code{TOOL_NAME}, it will be interpreted | |
8888 | that way. The use of the @code{TOOL_NAME} argument is relevant only to users | |
8889 | of SPARK and GNATprove, see last part of this section for details. | |
8890 | ||
8891 | Normally warnings are enabled, with the output being controlled by | |
8892 | the command line switch. Warnings (@code{Off}) turns off generation of | |
8893 | warnings until a Warnings (@code{On}) is encountered or the end of the | |
8894 | current unit. If generation of warnings is turned off using this | |
8895 | pragma, then some or all of the warning messages are suppressed, | |
8896 | regardless of the setting of the command line switches. | |
8897 | ||
8898 | The @code{Reason} parameter may optionally appear as the last argument | |
8899 | in any of the forms of this pragma. It is intended purely for the | |
8900 | purposes of documenting the reason for the @code{Warnings} pragma. | |
8901 | The compiler will check that the argument is a static string but | |
8902 | otherwise ignore this argument. Other tools may provide specialized | |
8903 | processing for this string. | |
8904 | ||
8905 | The form with a single argument (or two arguments if Reason present), | |
8906 | where the first argument is @code{ON} or @code{OFF} | |
8907 | may be used as a configuration pragma. | |
8908 | ||
8909 | If the @code{LOCAL_NAME} parameter is present, warnings are suppressed for | |
8910 | the specified entity. This suppression is effective from the point where | |
8911 | it occurs till the end of the extended scope of the variable (similar to | |
8912 | the scope of @code{Suppress}). This form cannot be used as a configuration | |
8913 | pragma. | |
8914 | ||
8915 | In the case where the first argument is other than @code{ON} or | |
8916 | @code{OFF}, | |
8917 | the third form with a single static_string_EXPRESSION argument (and possible | |
8918 | reason) provides more precise | |
8919 | control over which warnings are active. The string is a list of letters | |
8920 | specifying which warnings are to be activated and which deactivated. The | |
8921 | code for these letters is the same as the string used in the command | |
8922 | line switch controlling warnings. For a brief summary, use the gnatmake | |
8923 | command with no arguments, which will generate usage information containing | |
8924 | the list of warnings switches supported. For | |
8925 | full details see the section on @code{Warning Message Control} in the | |
8926 | @cite{GNAT User’s Guide}. | |
8927 | This form can also be used as a configuration pragma. | |
8928 | ||
8929 | The warnings controlled by the @code{-gnatw} switch are generated by the | |
8930 | front end of the compiler. The GCC back end can provide additional warnings | |
8931 | and they are controlled by the @code{-W} switch. Such warnings can be | |
8932 | identified by the appearance of a string of the form @code{[-W@{xxx@}]} in the | |
8933 | message which designates the @code{-W`xxx'} switch that controls the message. | |
8934 | The form with a single `static_string_EXPRESSION' argument also works for these | |
8935 | warnings, but the string must be a single full @code{-W`xxx'} switch in this | |
8936 | case. The above reference lists a few examples of these additional warnings. | |
8937 | ||
8938 | The specified warnings will be in effect until the end of the program | |
8939 | or another pragma @code{Warnings} is encountered. The effect of the pragma is | |
8940 | cumulative. Initially the set of warnings is the standard default set | |
8941 | as possibly modified by compiler switches. Then each pragma Warning | |
8942 | modifies this set of warnings as specified. This form of the pragma may | |
8943 | also be used as a configuration pragma. | |
8944 | ||
8945 | The fourth form, with an @code{On|Off} parameter and a string, is used to | |
8946 | control individual messages, based on their text. The string argument | |
8947 | is a pattern that is used to match against the text of individual | |
eeba836b | 8948 | warning messages (not including the initial “warning: ” tag). |
64d5610f ML |
8949 | |
8950 | The pattern may contain asterisks, which match zero or more characters in | |
8951 | the message. For example, you can use | |
8952 | @code{pragma Warnings (Off, "bits of*unused")} to suppress the warning | |
8953 | message @code{warning: 960 bits of "a" unused}. No other regular | |
8954 | expression notations are permitted. All characters other than asterisk in | |
8955 | these three specific cases are treated as literal characters in the match. | |
8956 | The match is case insensitive, for example XYZ matches xyz. | |
8957 | ||
8958 | Note that the pattern matches if it occurs anywhere within the warning | |
8959 | message string (it is not necessary to put an asterisk at the start and | |
8960 | the end of the message, since this is implied). | |
8961 | ||
8962 | The above use of patterns to match the message applies only to warning | |
8963 | messages generated by the front end. This form of the pragma with a string | |
8964 | argument can also be used to control warnings provided by the back end and | |
8965 | mentioned above. By using a single full @code{-W`xxx'} switch in the pragma, | |
8966 | such warnings can be turned on and off. | |
8967 | ||
8968 | There are two ways to use the pragma in this form. The OFF form can be used | |
8969 | as a configuration pragma. The effect is to suppress all warnings (if any) | |
8970 | that match the pattern string throughout the compilation (or match the | |
8971 | -W switch in the back end case). | |
8972 | ||
8973 | The second usage is to suppress a warning locally, and in this case, two | |
8974 | pragmas must appear in sequence: | |
8975 | ||
8976 | @example | |
8977 | pragma Warnings (Off, Pattern); | |
8978 | ... code where given warning is to be suppressed | |
8979 | pragma Warnings (On, Pattern); | |
8980 | @end example | |
8981 | ||
8982 | In this usage, the pattern string must match in the Off and On | |
8983 | pragmas, and (if `-gnatw.w' is given) at least one matching | |
8984 | warning must be suppressed. | |
8985 | ||
8986 | Note: if the ON form is not found, then the effect of the OFF form extends | |
8987 | until the end of the file (pragma Warnings is purely textual, so its effect | |
8988 | does not stop at the end of the enclosing scope). | |
8989 | ||
8990 | Note: to write a string that will match any warning, use the string | |
8991 | @code{"***"}. It will not work to use a single asterisk or two | |
8992 | asterisks since this looks like an operator name. This form with three | |
8993 | asterisks is similar in effect to specifying @code{pragma Warnings (Off)} except (if @code{-gnatw.w} is given) that a matching | |
8994 | @code{pragma Warnings (On, "***")} will be required. This can be | |
8995 | helpful in avoiding forgetting to turn warnings back on. | |
8996 | ||
8997 | Note: the debug flag @code{-gnatd.i} can be | |
8998 | used to cause the compiler to entirely ignore all WARNINGS pragmas. This can | |
8999 | be useful in checking whether obsolete pragmas in existing programs are hiding | |
9000 | real problems. | |
9001 | ||
9002 | Note: pragma Warnings does not affect the processing of style messages. See | |
9003 | separate entry for pragma Style_Checks for control of style messages. | |
9004 | ||
9005 | Users of the formal verification tool GNATprove for the SPARK subset of Ada may | |
9006 | use the version of the pragma with a @code{TOOL_NAME} parameter. | |
9007 | ||
9008 | If present, @code{TOOL_NAME} is the name of a tool, currently either @code{GNAT} for the | |
9009 | compiler or @code{GNATprove} for the formal verification tool. A given tool only | |
9010 | takes into account pragma Warnings that do not specify a tool name, or that | |
9011 | specify the matching tool name. This makes it possible to disable warnings | |
9012 | selectively for each tool, and as a consequence to detect useless pragma | |
9013 | Warnings with switch @code{-gnatw.w}. | |
9014 | ||
9015 | @node Pragma Weak_External,Pragma Wide_Character_Encoding,Pragma Warnings,Implementation Defined Pragmas | |
b71d4b62 | 9016 | @anchor{gnat_rm/implementation_defined_pragmas pragma-weak-external}@anchor{11f} |
64d5610f ML |
9017 | @section Pragma Weak_External |
9018 | ||
9019 | ||
9020 | Syntax: | |
9021 | ||
9022 | @example | |
9023 | pragma Weak_External ([Entity =>] LOCAL_NAME); | |
9024 | @end example | |
9025 | ||
9026 | @code{LOCAL_NAME} must refer to an object that is declared at the library | |
9027 | level. This pragma specifies that the given entity should be marked as a | |
9028 | weak symbol for the linker. It is equivalent to @code{__attribute__((weak))} | |
9029 | in GNU C and causes @code{LOCAL_NAME} to be emitted as a weak symbol instead | |
9030 | of a regular symbol, that is to say a symbol that does not have to be | |
9031 | resolved by the linker if used in conjunction with a pragma Import. | |
9032 | ||
9033 | When a weak symbol is not resolved by the linker, its address is set to | |
9034 | zero. This is useful in writing interfaces to external modules that may | |
9035 | or may not be linked in the final executable, for example depending on | |
9036 | configuration settings. | |
9037 | ||
9038 | If a program references at run time an entity to which this pragma has been | |
9039 | applied, and the corresponding symbol was not resolved at link time, then | |
9040 | the execution of the program is erroneous. It is not erroneous to take the | |
9041 | Address of such an entity, for example to guard potential references, | |
9042 | as shown in the example below. | |
9043 | ||
9044 | Some file formats do not support weak symbols so not all target machines | |
9045 | support this pragma. | |
9046 | ||
9047 | @example | |
9048 | -- Example of the use of pragma Weak_External | |
9049 | ||
9050 | package External_Module is | |
9051 | key : Integer; | |
9052 | pragma Import (C, key); | |
9053 | pragma Weak_External (key); | |
9054 | function Present return boolean; | |
9055 | end External_Module; | |
9056 | ||
9057 | with System; use System; | |
9058 | package body External_Module is | |
9059 | function Present return boolean is | |
9060 | begin | |
9061 | return key'Address /= System.Null_Address; | |
9062 | end Present; | |
9063 | end External_Module; | |
9064 | @end example | |
9065 | ||
9066 | @node Pragma Wide_Character_Encoding,,Pragma Weak_External,Implementation Defined Pragmas | |
b71d4b62 | 9067 | @anchor{gnat_rm/implementation_defined_pragmas pragma-wide-character-encoding}@anchor{120} |
64d5610f ML |
9068 | @section Pragma Wide_Character_Encoding |
9069 | ||
9070 | ||
9071 | Syntax: | |
9072 | ||
9073 | @example | |
9074 | pragma Wide_Character_Encoding (IDENTIFIER | CHARACTER_LITERAL); | |
9075 | @end example | |
9076 | ||
9077 | This pragma specifies the wide character encoding to be used in program | |
9078 | source text appearing subsequently. It is a configuration pragma, but may | |
9079 | also be used at any point that a pragma is allowed, and it is permissible | |
9080 | to have more than one such pragma in a file, allowing multiple encodings | |
9081 | to appear within the same file. | |
9082 | ||
9083 | However, note that the pragma cannot immediately precede the relevant | |
9084 | wide character, because then the previous encoding will still be in | |
9085 | effect, causing “illegal character” errors. | |
9086 | ||
9087 | The argument can be an identifier or a character literal. In the identifier | |
9088 | case, it is one of @code{HEX}, @code{UPPER}, @code{SHIFT_JIS}, | |
9089 | @code{EUC}, @code{UTF8}, or @code{BRACKETS}. In the character literal | |
9090 | case it is correspondingly one of the characters @code{h}, @code{u}, | |
9091 | @code{s}, @code{e}, @code{8}, or @code{b}. | |
9092 | ||
9093 | Note that when the pragma is used within a file, it affects only the | |
9094 | encoding within that file, and does not affect withed units, specs, | |
9095 | or subunits. | |
9096 | ||
9097 | @node Implementation Defined Aspects,Implementation Defined Attributes,Implementation Defined Pragmas,Top | |
b71d4b62 | 9098 | @anchor{gnat_rm/implementation_defined_aspects doc}@anchor{121}@anchor{gnat_rm/implementation_defined_aspects id1}@anchor{122}@anchor{gnat_rm/implementation_defined_aspects implementation-defined-aspects}@anchor{123} |
64d5610f ML |
9099 | @chapter Implementation Defined Aspects |
9100 | ||
9101 | ||
9102 | Ada defines (throughout the Ada 2012 reference manual, summarized | |
9103 | in Annex K) a set of aspects that can be specified for certain entities. | |
9104 | These language defined aspects are implemented in GNAT in Ada 2012 mode | |
9105 | and work as described in the Ada 2012 Reference Manual. | |
9106 | ||
9107 | In addition, Ada 2012 allows implementations to define additional aspects | |
9108 | whose meaning is defined by the implementation. GNAT provides | |
9109 | a number of these implementation-defined aspects which can be used | |
9110 | to extend and enhance the functionality of the compiler. This section of | |
9111 | the GNAT reference manual describes these additional aspects. | |
9112 | ||
9113 | Note that any program using these aspects may not be portable to | |
9114 | other compilers (although GNAT implements this set of aspects on all | |
9115 | platforms). Therefore if portability to other compilers is an important | |
9116 | consideration, you should minimize the use of these aspects. | |
9117 | ||
9118 | Note that for many of these aspects, the effect is essentially similar | |
9119 | to the use of a pragma or attribute specification with the same name | |
9120 | applied to the entity. For example, if we write: | |
9121 | ||
9122 | @example | |
9123 | type R is range 1 .. 100 | |
9124 | with Value_Size => 10; | |
9125 | @end example | |
9126 | ||
9127 | then the effect is the same as: | |
9128 | ||
9129 | @example | |
9130 | type R is range 1 .. 100; | |
9131 | for R'Value_Size use 10; | |
9132 | @end example | |
9133 | ||
9134 | and if we write: | |
9135 | ||
9136 | @example | |
9137 | type R is new Integer | |
9138 | with Shared => True; | |
9139 | @end example | |
9140 | ||
9141 | then the effect is the same as: | |
9142 | ||
9143 | @example | |
9144 | type R is new Integer; | |
9145 | pragma Shared (R); | |
9146 | @end example | |
9147 | ||
9148 | In the documentation below, such cases are simply marked | |
9149 | as being boolean aspects equivalent to the corresponding pragma | |
9150 | or attribute definition clause. | |
9151 | ||
9152 | @menu | |
9153 | * Aspect Abstract_State:: | |
9154 | * Aspect Annotate:: | |
9155 | * Aspect Async_Readers:: | |
9156 | * Aspect Async_Writers:: | |
9157 | * Aspect Constant_After_Elaboration:: | |
9158 | * Aspect Contract_Cases:: | |
9159 | * Aspect Depends:: | |
9160 | * Aspect Default_Initial_Condition:: | |
9161 | * Aspect Dimension:: | |
9162 | * Aspect Dimension_System:: | |
9163 | * Aspect Disable_Controlled:: | |
9164 | * Aspect Effective_Reads:: | |
9165 | * Aspect Effective_Writes:: | |
9166 | * Aspect Extensions_Visible:: | |
9167 | * Aspect Favor_Top_Level:: | |
9168 | * Aspect Ghost:: | |
067d80d8 | 9169 | * Aspect Ghost_Predicate:: |
64d5610f ML |
9170 | * Aspect Global:: |
9171 | * Aspect Initial_Condition:: | |
9172 | * Aspect Initializes:: | |
9173 | * Aspect Inline_Always:: | |
9174 | * Aspect Invariant:: | |
9175 | * Aspect Invariant’Class:: | |
9176 | * Aspect Iterable:: | |
9177 | * Aspect Linker_Section:: | |
9178 | * Aspect Lock_Free:: | |
9179 | * Aspect Max_Queue_Length:: | |
9180 | * Aspect No_Caching:: | |
9181 | * Aspect No_Elaboration_Code_All:: | |
9182 | * Aspect No_Inline:: | |
9183 | * Aspect No_Tagged_Streams:: | |
9184 | * Aspect No_Task_Parts:: | |
9185 | * Aspect Object_Size:: | |
9186 | * Aspect Obsolescent:: | |
9187 | * Aspect Part_Of:: | |
9188 | * Aspect Persistent_BSS:: | |
9189 | * Aspect Predicate:: | |
9190 | * Aspect Pure_Function:: | |
9191 | * Aspect Refined_Depends:: | |
9192 | * Aspect Refined_Global:: | |
9193 | * Aspect Refined_Post:: | |
9194 | * Aspect Refined_State:: | |
9195 | * Aspect Relaxed_Initialization:: | |
9196 | * Aspect Remote_Access_Type:: | |
9197 | * Aspect Secondary_Stack_Size:: | |
9198 | * Aspect Scalar_Storage_Order:: | |
9199 | * Aspect Shared:: | |
9200 | * Aspect Simple_Storage_Pool:: | |
9201 | * Aspect Simple_Storage_Pool_Type:: | |
9202 | * Aspect SPARK_Mode:: | |
9203 | * Aspect Suppress_Debug_Info:: | |
9204 | * Aspect Suppress_Initialization:: | |
9205 | * Aspect Test_Case:: | |
9206 | * Aspect Thread_Local_Storage:: | |
9207 | * Aspect Universal_Aliasing:: | |
9208 | * Aspect Unmodified:: | |
9209 | * Aspect Unreferenced:: | |
9210 | * Aspect Unreferenced_Objects:: | |
9211 | * Aspect Value_Size:: | |
9212 | * Aspect Volatile_Full_Access:: | |
9213 | * Aspect Volatile_Function:: | |
9214 | * Aspect Warnings:: | |
9215 | ||
9216 | @end menu | |
9217 | ||
9218 | @node Aspect Abstract_State,Aspect Annotate,,Implementation Defined Aspects | |
b71d4b62 | 9219 | @anchor{gnat_rm/implementation_defined_aspects aspect-abstract-state}@anchor{124} |
64d5610f ML |
9220 | @section Aspect Abstract_State |
9221 | ||
9222 | ||
9223 | @geindex Abstract_State | |
9224 | ||
9225 | This aspect is equivalent to @ref{1e,,pragma Abstract_State}. | |
9226 | ||
9227 | @node Aspect Annotate,Aspect Async_Readers,Aspect Abstract_State,Implementation Defined Aspects | |
b71d4b62 | 9228 | @anchor{gnat_rm/implementation_defined_aspects aspect-annotate}@anchor{125} |
64d5610f ML |
9229 | @section Aspect Annotate |
9230 | ||
9231 | ||
9232 | @geindex Annotate | |
9233 | ||
9234 | There are three forms of this aspect (where ID is an identifier, | |
9235 | and ARG is a general expression), | |
9236 | corresponding to @ref{29,,pragma Annotate}. | |
9237 | ||
9238 | ||
9239 | @table @asis | |
9240 | ||
9241 | @item `Annotate => ID' | |
9242 | ||
9243 | Equivalent to @code{pragma Annotate (ID, Entity => Name);} | |
9244 | ||
9245 | @item `Annotate => (ID)' | |
9246 | ||
9247 | Equivalent to @code{pragma Annotate (ID, Entity => Name);} | |
9248 | ||
9249 | @item `Annotate => (ID ,ID @{, ARG@})' | |
9250 | ||
9251 | Equivalent to @code{pragma Annotate (ID, ID @{, ARG@}, Entity => Name);} | |
9252 | @end table | |
9253 | ||
9254 | @node Aspect Async_Readers,Aspect Async_Writers,Aspect Annotate,Implementation Defined Aspects | |
b71d4b62 | 9255 | @anchor{gnat_rm/implementation_defined_aspects aspect-async-readers}@anchor{126} |
64d5610f ML |
9256 | @section Aspect Async_Readers |
9257 | ||
9258 | ||
9259 | @geindex Async_Readers | |
9260 | ||
9261 | This boolean aspect is equivalent to @ref{30,,pragma Async_Readers}. | |
9262 | ||
9263 | @node Aspect Async_Writers,Aspect Constant_After_Elaboration,Aspect Async_Readers,Implementation Defined Aspects | |
b71d4b62 | 9264 | @anchor{gnat_rm/implementation_defined_aspects aspect-async-writers}@anchor{127} |
64d5610f ML |
9265 | @section Aspect Async_Writers |
9266 | ||
9267 | ||
9268 | @geindex Async_Writers | |
9269 | ||
9270 | This boolean aspect is equivalent to @ref{32,,pragma Async_Writers}. | |
9271 | ||
9272 | @node Aspect Constant_After_Elaboration,Aspect Contract_Cases,Aspect Async_Writers,Implementation Defined Aspects | |
b71d4b62 | 9273 | @anchor{gnat_rm/implementation_defined_aspects aspect-constant-after-elaboration}@anchor{128} |
64d5610f ML |
9274 | @section Aspect Constant_After_Elaboration |
9275 | ||
9276 | ||
9277 | @geindex Constant_After_Elaboration | |
9278 | ||
9279 | This aspect is equivalent to @ref{42,,pragma Constant_After_Elaboration}. | |
9280 | ||
9281 | @node Aspect Contract_Cases,Aspect Depends,Aspect Constant_After_Elaboration,Implementation Defined Aspects | |
b71d4b62 | 9282 | @anchor{gnat_rm/implementation_defined_aspects aspect-contract-cases}@anchor{129} |
64d5610f ML |
9283 | @section Aspect Contract_Cases |
9284 | ||
9285 | ||
9286 | @geindex Contract_Cases | |
9287 | ||
9288 | This aspect is equivalent to @ref{44,,pragma Contract_Cases}, the sequence | |
9289 | of clauses being enclosed in parentheses so that syntactically it is an | |
9290 | aggregate. | |
9291 | ||
9292 | @node Aspect Depends,Aspect Default_Initial_Condition,Aspect Contract_Cases,Implementation Defined Aspects | |
b71d4b62 | 9293 | @anchor{gnat_rm/implementation_defined_aspects aspect-depends}@anchor{12a} |
64d5610f ML |
9294 | @section Aspect Depends |
9295 | ||
9296 | ||
9297 | @geindex Depends | |
9298 | ||
9299 | This aspect is equivalent to @ref{54,,pragma Depends}. | |
9300 | ||
9301 | @node Aspect Default_Initial_Condition,Aspect Dimension,Aspect Depends,Implementation Defined Aspects | |
b71d4b62 | 9302 | @anchor{gnat_rm/implementation_defined_aspects aspect-default-initial-condition}@anchor{12b} |
64d5610f ML |
9303 | @section Aspect Default_Initial_Condition |
9304 | ||
9305 | ||
9306 | @geindex Default_Initial_Condition | |
9307 | ||
6f089469 | 9308 | This aspect is equivalent to @ref{50,,pragma Default_Initial_Condition}. |
64d5610f ML |
9309 | |
9310 | @node Aspect Dimension,Aspect Dimension_System,Aspect Default_Initial_Condition,Implementation Defined Aspects | |
b71d4b62 | 9311 | @anchor{gnat_rm/implementation_defined_aspects aspect-dimension}@anchor{12c} |
64d5610f ML |
9312 | @section Aspect Dimension |
9313 | ||
9314 | ||
9315 | @geindex Dimension | |
9316 | ||
9317 | The @code{Dimension} aspect is used to specify the dimensions of a given | |
9318 | subtype of a dimensioned numeric type. The aspect also specifies a symbol | |
9319 | used when doing formatted output of dimensioned quantities. The syntax is: | |
9320 | ||
9321 | @example | |
9322 | with Dimension => | |
9323 | ([Symbol =>] SYMBOL, DIMENSION_VALUE @{, DIMENSION_Value@}) | |
9324 | ||
9325 | SYMBOL ::= STRING_LITERAL | CHARACTER_LITERAL | |
9326 | ||
9327 | DIMENSION_VALUE ::= | |
9328 | RATIONAL | |
9329 | | others => RATIONAL | |
9330 | | DISCRETE_CHOICE_LIST => RATIONAL | |
9331 | ||
9332 | RATIONAL ::= [-] NUMERIC_LITERAL [/ NUMERIC_LITERAL] | |
9333 | @end example | |
9334 | ||
9335 | This aspect can only be applied to a subtype whose parent type has | |
9336 | a @code{Dimension_System} aspect. The aspect must specify values for | |
9337 | all dimensions of the system. The rational values are the powers of the | |
9338 | corresponding dimensions that are used by the compiler to verify that | |
9339 | physical (numeric) computations are dimensionally consistent. For example, | |
9340 | the computation of a force must result in dimensions (L => 1, M => 1, T => -2). | |
9341 | For further examples of the usage | |
9342 | of this aspect, see package @code{System.Dim.Mks}. | |
9343 | Note that when the dimensioned type is an integer type, then any | |
9344 | dimension value must be an integer literal. | |
9345 | ||
9346 | @node Aspect Dimension_System,Aspect Disable_Controlled,Aspect Dimension,Implementation Defined Aspects | |
b71d4b62 | 9347 | @anchor{gnat_rm/implementation_defined_aspects aspect-dimension-system}@anchor{12d} |
64d5610f ML |
9348 | @section Aspect Dimension_System |
9349 | ||
9350 | ||
9351 | @geindex Dimension_System | |
9352 | ||
9353 | The @code{Dimension_System} aspect is used to define a system of | |
9354 | dimensions that will be used in subsequent subtype declarations with | |
9355 | @code{Dimension} aspects that reference this system. The syntax is: | |
9356 | ||
9357 | @example | |
9358 | with Dimension_System => (DIMENSION @{, DIMENSION@}); | |
9359 | ||
9360 | DIMENSION ::= ([Unit_Name =>] IDENTIFIER, | |
9361 | [Unit_Symbol =>] SYMBOL, | |
9362 | [Dim_Symbol =>] SYMBOL) | |
9363 | ||
9364 | SYMBOL ::= CHARACTER_LITERAL | STRING_LITERAL | |
9365 | @end example | |
9366 | ||
9367 | This aspect is applied to a type, which must be a numeric derived type | |
9368 | (typically a floating-point type), that | |
9369 | will represent values within the dimension system. Each @code{DIMENSION} | |
9370 | corresponds to one particular dimension. A maximum of 7 dimensions may | |
9371 | be specified. @code{Unit_Name} is the name of the dimension (for example | |
9372 | @code{Meter}). @code{Unit_Symbol} is the shorthand used for quantities | |
9373 | of this dimension (for example @code{m} for @code{Meter}). | |
9374 | @code{Dim_Symbol} gives | |
9375 | the identification within the dimension system (typically this is a | |
9376 | single letter, e.g. @code{L} standing for length for unit name @code{Meter}). | |
9377 | The @code{Unit_Symbol} is used in formatted output of dimensioned quantities. | |
9378 | The @code{Dim_Symbol} is used in error messages when numeric operations have | |
9379 | inconsistent dimensions. | |
9380 | ||
9381 | GNAT provides the standard definition of the International MKS system in | |
9382 | the run-time package @code{System.Dim.Mks}. You can easily define | |
9383 | similar packages for cgs units or British units, and define conversion factors | |
9384 | between values in different systems. The MKS system is characterized by the | |
9385 | following aspect: | |
9386 | ||
9387 | @example | |
9388 | type Mks_Type is new Long_Long_Float with | |
9389 | Dimension_System => ( | |
9390 | (Unit_Name => Meter, Unit_Symbol => 'm', Dim_Symbol => 'L'), | |
9391 | (Unit_Name => Kilogram, Unit_Symbol => "kg", Dim_Symbol => 'M'), | |
9392 | (Unit_Name => Second, Unit_Symbol => 's', Dim_Symbol => 'T'), | |
9393 | (Unit_Name => Ampere, Unit_Symbol => 'A', Dim_Symbol => 'I'), | |
9394 | (Unit_Name => Kelvin, Unit_Symbol => 'K', Dim_Symbol => '@@'), | |
9395 | (Unit_Name => Mole, Unit_Symbol => "mol", Dim_Symbol => 'N'), | |
9396 | (Unit_Name => Candela, Unit_Symbol => "cd", Dim_Symbol => 'J')); | |
9397 | @end example | |
9398 | ||
9399 | Note that in the above type definition, we use the @code{at} symbol (@code{@@}) to | |
9400 | represent a theta character (avoiding the use of extended Latin-1 | |
9401 | characters in this context). | |
9402 | ||
9403 | See section ‘Performing Dimensionality Analysis in GNAT’ in the GNAT Users | |
9404 | Guide for detailed examples of use of the dimension system. | |
9405 | ||
9406 | @node Aspect Disable_Controlled,Aspect Effective_Reads,Aspect Dimension_System,Implementation Defined Aspects | |
b71d4b62 | 9407 | @anchor{gnat_rm/implementation_defined_aspects aspect-disable-controlled}@anchor{12e} |
64d5610f ML |
9408 | @section Aspect Disable_Controlled |
9409 | ||
9410 | ||
9411 | @geindex Disable_Controlled | |
9412 | ||
9413 | The aspect @code{Disable_Controlled} is defined for controlled record types. If | |
9414 | active, this aspect causes suppression of all related calls to @code{Initialize}, | |
9415 | @code{Adjust}, and @code{Finalize}. The intended use is for conditional compilation, | |
9416 | where for example you might want a record to be controlled or not depending on | |
9417 | whether some run-time check is enabled or suppressed. | |
9418 | ||
9419 | @node Aspect Effective_Reads,Aspect Effective_Writes,Aspect Disable_Controlled,Implementation Defined Aspects | |
b71d4b62 | 9420 | @anchor{gnat_rm/implementation_defined_aspects aspect-effective-reads}@anchor{12f} |
64d5610f ML |
9421 | @section Aspect Effective_Reads |
9422 | ||
9423 | ||
9424 | @geindex Effective_Reads | |
9425 | ||
9426 | This aspect is equivalent to @ref{59,,pragma Effective_Reads}. | |
9427 | ||
9428 | @node Aspect Effective_Writes,Aspect Extensions_Visible,Aspect Effective_Reads,Implementation Defined Aspects | |
b71d4b62 | 9429 | @anchor{gnat_rm/implementation_defined_aspects aspect-effective-writes}@anchor{130} |
64d5610f ML |
9430 | @section Aspect Effective_Writes |
9431 | ||
9432 | ||
9433 | @geindex Effective_Writes | |
9434 | ||
9435 | This aspect is equivalent to @ref{5b,,pragma Effective_Writes}. | |
9436 | ||
9437 | @node Aspect Extensions_Visible,Aspect Favor_Top_Level,Aspect Effective_Writes,Implementation Defined Aspects | |
b71d4b62 | 9438 | @anchor{gnat_rm/implementation_defined_aspects aspect-extensions-visible}@anchor{131} |
64d5610f ML |
9439 | @section Aspect Extensions_Visible |
9440 | ||
9441 | ||
9442 | @geindex Extensions_Visible | |
9443 | ||
b71d4b62 | 9444 | This aspect is equivalent to @ref{69,,pragma Extensions_Visible}. |
64d5610f ML |
9445 | |
9446 | @node Aspect Favor_Top_Level,Aspect Ghost,Aspect Extensions_Visible,Implementation Defined Aspects | |
b71d4b62 | 9447 | @anchor{gnat_rm/implementation_defined_aspects aspect-favor-top-level}@anchor{132} |
64d5610f ML |
9448 | @section Aspect Favor_Top_Level |
9449 | ||
9450 | ||
9451 | @geindex Favor_Top_Level | |
9452 | ||
b71d4b62 | 9453 | This boolean aspect is equivalent to @ref{6e,,pragma Favor_Top_Level}. |
64d5610f | 9454 | |
067d80d8 | 9455 | @node Aspect Ghost,Aspect Ghost_Predicate,Aspect Favor_Top_Level,Implementation Defined Aspects |
b71d4b62 | 9456 | @anchor{gnat_rm/implementation_defined_aspects aspect-ghost}@anchor{133} |
64d5610f ML |
9457 | @section Aspect Ghost |
9458 | ||
9459 | ||
9460 | @geindex Ghost | |
9461 | ||
b71d4b62 | 9462 | This aspect is equivalent to @ref{72,,pragma Ghost}. |
64d5610f | 9463 | |
067d80d8 YM |
9464 | @node Aspect Ghost_Predicate,Aspect Global,Aspect Ghost,Implementation Defined Aspects |
9465 | @anchor{gnat_rm/implementation_defined_aspects aspect-ghost-predicate}@anchor{134} | |
9466 | @section Aspect Ghost_Predicate | |
9467 | ||
9468 | ||
9469 | @geindex Ghost_Predicate | |
9470 | ||
9471 | This aspect introduces a subtype predicate that can reference ghost | |
9472 | entities. The subtype cannot appear as a subtype_mark in a membership test. | |
9473 | ||
9474 | For the detailed semantics of this aspect, see the entry for subtype predicates | |
9475 | in the SPARK Reference Manual, section 3.2.4. | |
9476 | ||
9477 | @node Aspect Global,Aspect Initial_Condition,Aspect Ghost_Predicate,Implementation Defined Aspects | |
9478 | @anchor{gnat_rm/implementation_defined_aspects aspect-global}@anchor{135} | |
64d5610f ML |
9479 | @section Aspect Global |
9480 | ||
9481 | ||
9482 | @geindex Global | |
9483 | ||
b71d4b62 | 9484 | This aspect is equivalent to @ref{74,,pragma Global}. |
64d5610f ML |
9485 | |
9486 | @node Aspect Initial_Condition,Aspect Initializes,Aspect Global,Implementation Defined Aspects | |
067d80d8 | 9487 | @anchor{gnat_rm/implementation_defined_aspects aspect-initial-condition}@anchor{136} |
64d5610f ML |
9488 | @section Aspect Initial_Condition |
9489 | ||
9490 | ||
9491 | @geindex Initial_Condition | |
9492 | ||
b71d4b62 | 9493 | This aspect is equivalent to @ref{81,,pragma Initial_Condition}. |
64d5610f ML |
9494 | |
9495 | @node Aspect Initializes,Aspect Inline_Always,Aspect Initial_Condition,Implementation Defined Aspects | |
067d80d8 | 9496 | @anchor{gnat_rm/implementation_defined_aspects aspect-initializes}@anchor{137} |
64d5610f ML |
9497 | @section Aspect Initializes |
9498 | ||
9499 | ||
9500 | @geindex Initializes | |
9501 | ||
b71d4b62 | 9502 | This aspect is equivalent to @ref{84,,pragma Initializes}. |
64d5610f ML |
9503 | |
9504 | @node Aspect Inline_Always,Aspect Invariant,Aspect Initializes,Implementation Defined Aspects | |
067d80d8 | 9505 | @anchor{gnat_rm/implementation_defined_aspects aspect-inline-always}@anchor{138} |
64d5610f ML |
9506 | @section Aspect Inline_Always |
9507 | ||
9508 | ||
9509 | @geindex Inline_Always | |
9510 | ||
b71d4b62 | 9511 | This boolean aspect is equivalent to @ref{86,,pragma Inline_Always}. |
64d5610f ML |
9512 | |
9513 | @node Aspect Invariant,Aspect Invariant’Class,Aspect Inline_Always,Implementation Defined Aspects | |
067d80d8 | 9514 | @anchor{gnat_rm/implementation_defined_aspects aspect-invariant}@anchor{139} |
64d5610f ML |
9515 | @section Aspect Invariant |
9516 | ||
9517 | ||
9518 | @geindex Invariant | |
9519 | ||
b71d4b62 | 9520 | This aspect is equivalent to @ref{8d,,pragma Invariant}. It is a |
64d5610f ML |
9521 | synonym for the language defined aspect @code{Type_Invariant} except |
9522 | that it is separately controllable using pragma @code{Assertion_Policy}. | |
9523 | ||
9524 | @node Aspect Invariant’Class,Aspect Iterable,Aspect Invariant,Implementation Defined Aspects | |
067d80d8 | 9525 | @anchor{gnat_rm/implementation_defined_aspects aspect-invariant-class}@anchor{13a} |
64d5610f ML |
9526 | @section Aspect Invariant’Class |
9527 | ||
9528 | ||
9529 | @geindex Invariant'Class | |
9530 | ||
b71d4b62 | 9531 | This aspect is equivalent to @ref{104,,pragma Type_Invariant_Class}. It is a |
64d5610f ML |
9532 | synonym for the language defined aspect @code{Type_Invariant'Class} except |
9533 | that it is separately controllable using pragma @code{Assertion_Policy}. | |
9534 | ||
9535 | @node Aspect Iterable,Aspect Linker_Section,Aspect Invariant’Class,Implementation Defined Aspects | |
067d80d8 | 9536 | @anchor{gnat_rm/implementation_defined_aspects aspect-iterable}@anchor{13b} |
64d5610f ML |
9537 | @section Aspect Iterable |
9538 | ||
9539 | ||
9540 | @geindex Iterable | |
9541 | ||
9542 | This aspect provides a light-weight mechanism for loops and quantified | |
9543 | expressions over container types, without the overhead imposed by the tampering | |
9544 | checks of standard Ada 2012 iterators. The value of the aspect is an aggregate | |
9545 | with six named components, of which the last three are optional: @code{First}, | |
9546 | @code{Next}, @code{Has_Element}, @code{Element}, @code{Last}, and @code{Previous}. | |
9547 | When only the first three components are specified, only the | |
9548 | @code{for .. in} form of iteration over cursors is available. When @code{Element} | |
9549 | is specified, both this form and the @code{for .. of} form of iteration over | |
9550 | elements are available. If the last two components are specified, reverse | |
9551 | iterations over the container can be specified (analogous to what can be done | |
9552 | over predefined containers that support the @code{Reverse_Iterator} interface). | |
9553 | The following is a typical example of use: | |
9554 | ||
9555 | @example | |
9556 | type List is private with | |
9557 | Iterable => (First => First_Cursor, | |
9558 | Next => Advance, | |
9559 | Has_Element => Cursor_Has_Element | |
9560 | [,Element => Get_Element] | |
9561 | [,Last => Last_Cursor] | |
9562 | [,Previous => Retreat]); | |
9563 | @end example | |
9564 | ||
9565 | ||
9566 | @itemize * | |
9567 | ||
9568 | @item | |
9569 | The values of @code{First} and @code{Last} are primitive operations of the | |
9570 | container type that return a @code{Cursor}, which must be a type declared in | |
9571 | the container package or visible from it. For example: | |
9572 | @end itemize | |
9573 | ||
9574 | @example | |
9575 | function First_Cursor (Cont : Container) return Cursor; | |
9576 | function Last_Cursor (Cont : Container) return Cursor; | |
9577 | @end example | |
9578 | ||
9579 | ||
9580 | @itemize * | |
9581 | ||
9582 | @item | |
9583 | The values of @code{Next} and @code{Previous} are primitive operations of the container type that take | |
9584 | both a container and a cursor and yield a cursor. For example: | |
9585 | @end itemize | |
9586 | ||
9587 | @example | |
9588 | function Advance (Cont : Container; Position : Cursor) return Cursor; | |
9589 | function Retreat (Cont : Container; Position : Cursor) return Cursor; | |
9590 | @end example | |
9591 | ||
9592 | ||
9593 | @itemize * | |
9594 | ||
9595 | @item | |
9596 | The value of @code{Has_Element} is a primitive operation of the container type | |
9597 | that takes both a container and a cursor and yields a boolean. For example: | |
9598 | @end itemize | |
9599 | ||
9600 | @example | |
9601 | function Cursor_Has_Element (Cont : Container; Position : Cursor) return Boolean; | |
9602 | @end example | |
9603 | ||
9604 | ||
9605 | @itemize * | |
9606 | ||
9607 | @item | |
9608 | The value of @code{Element} is a primitive operation of the container type that | |
9609 | takes both a container and a cursor and yields an @code{Element_Type}, which must | |
9610 | be a type declared in the container package or visible from it. For example: | |
9611 | @end itemize | |
9612 | ||
9613 | @example | |
9614 | function Get_Element (Cont : Container; Position : Cursor) return Element_Type; | |
9615 | @end example | |
9616 | ||
9617 | This aspect is used in the GNAT-defined formal container packages. | |
9618 | ||
9619 | @node Aspect Linker_Section,Aspect Lock_Free,Aspect Iterable,Implementation Defined Aspects | |
067d80d8 | 9620 | @anchor{gnat_rm/implementation_defined_aspects aspect-linker-section}@anchor{13c} |
64d5610f ML |
9621 | @section Aspect Linker_Section |
9622 | ||
9623 | ||
9624 | @geindex Linker_Section | |
9625 | ||
b71d4b62 | 9626 | This aspect is equivalent to @ref{95,,pragma Linker_Section}. |
64d5610f ML |
9627 | |
9628 | @node Aspect Lock_Free,Aspect Max_Queue_Length,Aspect Linker_Section,Implementation Defined Aspects | |
067d80d8 | 9629 | @anchor{gnat_rm/implementation_defined_aspects aspect-lock-free}@anchor{13d} |
64d5610f ML |
9630 | @section Aspect Lock_Free |
9631 | ||
9632 | ||
9633 | @geindex Lock_Free | |
9634 | ||
b71d4b62 | 9635 | This boolean aspect is equivalent to @ref{97,,pragma Lock_Free}. |
64d5610f ML |
9636 | |
9637 | @node Aspect Max_Queue_Length,Aspect No_Caching,Aspect Lock_Free,Implementation Defined Aspects | |
067d80d8 | 9638 | @anchor{gnat_rm/implementation_defined_aspects aspect-max-queue-length}@anchor{13e} |
64d5610f ML |
9639 | @section Aspect Max_Queue_Length |
9640 | ||
9641 | ||
9642 | @geindex Max_Queue_Length | |
9643 | ||
b71d4b62 | 9644 | This aspect is equivalent to @ref{9f,,pragma Max_Queue_Length}. |
64d5610f ML |
9645 | |
9646 | @node Aspect No_Caching,Aspect No_Elaboration_Code_All,Aspect Max_Queue_Length,Implementation Defined Aspects | |
067d80d8 | 9647 | @anchor{gnat_rm/implementation_defined_aspects aspect-no-caching}@anchor{13f} |
64d5610f ML |
9648 | @section Aspect No_Caching |
9649 | ||
9650 | ||
9651 | @geindex No_Caching | |
9652 | ||
b71d4b62 | 9653 | This boolean aspect is equivalent to @ref{a2,,pragma No_Caching}. |
64d5610f ML |
9654 | |
9655 | @node Aspect No_Elaboration_Code_All,Aspect No_Inline,Aspect No_Caching,Implementation Defined Aspects | |
067d80d8 | 9656 | @anchor{gnat_rm/implementation_defined_aspects aspect-no-elaboration-code-all}@anchor{140} |
64d5610f ML |
9657 | @section Aspect No_Elaboration_Code_All |
9658 | ||
9659 | ||
9660 | @geindex No_Elaboration_Code_All | |
9661 | ||
b71d4b62 | 9662 | This aspect is equivalent to @ref{a5,,pragma No_Elaboration_Code_All} |
64d5610f ML |
9663 | for a program unit. |
9664 | ||
9665 | @node Aspect No_Inline,Aspect No_Tagged_Streams,Aspect No_Elaboration_Code_All,Implementation Defined Aspects | |
067d80d8 | 9666 | @anchor{gnat_rm/implementation_defined_aspects aspect-no-inline}@anchor{141} |
64d5610f ML |
9667 | @section Aspect No_Inline |
9668 | ||
9669 | ||
9670 | @geindex No_Inline | |
9671 | ||
b71d4b62 | 9672 | This boolean aspect is equivalent to @ref{a8,,pragma No_Inline}. |
64d5610f ML |
9673 | |
9674 | @node Aspect No_Tagged_Streams,Aspect No_Task_Parts,Aspect No_Inline,Implementation Defined Aspects | |
067d80d8 | 9675 | @anchor{gnat_rm/implementation_defined_aspects aspect-no-tagged-streams}@anchor{142} |
64d5610f ML |
9676 | @section Aspect No_Tagged_Streams |
9677 | ||
9678 | ||
9679 | @geindex No_Tagged_Streams | |
9680 | ||
b71d4b62 | 9681 | This aspect is equivalent to @ref{ac,,pragma No_Tagged_Streams} with an |
64d5610f ML |
9682 | argument specifying a root tagged type (thus this aspect can only be |
9683 | applied to such a type). | |
9684 | ||
9685 | @node Aspect No_Task_Parts,Aspect Object_Size,Aspect No_Tagged_Streams,Implementation Defined Aspects | |
067d80d8 | 9686 | @anchor{gnat_rm/implementation_defined_aspects aspect-no-task-parts}@anchor{143} |
64d5610f ML |
9687 | @section Aspect No_Task_Parts |
9688 | ||
9689 | ||
9690 | @geindex No_Task_Parts | |
9691 | ||
9692 | Applies to a type. If True, requires that the type and any descendants | |
9693 | do not have any task parts. The rules for this aspect are the same as | |
9694 | for the language-defined No_Controlled_Parts aspect (see RM-H.4.1), | |
9695 | replacing “controlled” with “task”. | |
9696 | ||
9697 | If No_Task_Parts is True for a type T, then the compiler can optimize | |
9698 | away certain tasking-related code that would otherwise be needed | |
9699 | for T’Class, because descendants of T might contain tasks. | |
9700 | ||
9701 | @node Aspect Object_Size,Aspect Obsolescent,Aspect No_Task_Parts,Implementation Defined Aspects | |
067d80d8 | 9702 | @anchor{gnat_rm/implementation_defined_aspects aspect-object-size}@anchor{144} |
64d5610f ML |
9703 | @section Aspect Object_Size |
9704 | ||
9705 | ||
9706 | @geindex Object_Size | |
9707 | ||
067d80d8 | 9708 | This aspect is equivalent to @ref{145,,attribute Object_Size}. |
64d5610f ML |
9709 | |
9710 | @node Aspect Obsolescent,Aspect Part_Of,Aspect Object_Size,Implementation Defined Aspects | |
067d80d8 | 9711 | @anchor{gnat_rm/implementation_defined_aspects aspect-obsolescent}@anchor{146} |
64d5610f ML |
9712 | @section Aspect Obsolescent |
9713 | ||
9714 | ||
9715 | @geindex Obsolescent | |
9716 | ||
b71d4b62 | 9717 | This aspect is equivalent to @ref{af,,pragma Obsolescent}. Note that the |
64d5610f ML |
9718 | evaluation of this aspect happens at the point of occurrence, it is not |
9719 | delayed until the freeze point. | |
9720 | ||
9721 | @node Aspect Part_Of,Aspect Persistent_BSS,Aspect Obsolescent,Implementation Defined Aspects | |
067d80d8 | 9722 | @anchor{gnat_rm/implementation_defined_aspects aspect-part-of}@anchor{147} |
64d5610f ML |
9723 | @section Aspect Part_Of |
9724 | ||
9725 | ||
9726 | @geindex Part_Of | |
9727 | ||
b71d4b62 | 9728 | This aspect is equivalent to @ref{b5,,pragma Part_Of}. |
64d5610f ML |
9729 | |
9730 | @node Aspect Persistent_BSS,Aspect Predicate,Aspect Part_Of,Implementation Defined Aspects | |
067d80d8 | 9731 | @anchor{gnat_rm/implementation_defined_aspects aspect-persistent-bss}@anchor{148} |
64d5610f ML |
9732 | @section Aspect Persistent_BSS |
9733 | ||
9734 | ||
9735 | @geindex Persistent_BSS | |
9736 | ||
b71d4b62 | 9737 | This boolean aspect is equivalent to @ref{b9,,pragma Persistent_BSS}. |
64d5610f ML |
9738 | |
9739 | @node Aspect Predicate,Aspect Pure_Function,Aspect Persistent_BSS,Implementation Defined Aspects | |
067d80d8 | 9740 | @anchor{gnat_rm/implementation_defined_aspects aspect-predicate}@anchor{149} |
64d5610f ML |
9741 | @section Aspect Predicate |
9742 | ||
9743 | ||
9744 | @geindex Predicate | |
9745 | ||
b71d4b62 | 9746 | This aspect is equivalent to @ref{c0,,pragma Predicate}. It is thus |
64d5610f ML |
9747 | similar to the language defined aspects @code{Dynamic_Predicate} |
9748 | and @code{Static_Predicate} except that whether the resulting | |
9749 | predicate is static or dynamic is controlled by the form of the | |
9750 | expression. It is also separately controllable using pragma | |
9751 | @code{Assertion_Policy}. | |
9752 | ||
9753 | @node Aspect Pure_Function,Aspect Refined_Depends,Aspect Predicate,Implementation Defined Aspects | |
067d80d8 | 9754 | @anchor{gnat_rm/implementation_defined_aspects aspect-pure-function}@anchor{14a} |
64d5610f ML |
9755 | @section Aspect Pure_Function |
9756 | ||
9757 | ||
9758 | @geindex Pure_Function | |
9759 | ||
b71d4b62 | 9760 | This boolean aspect is equivalent to @ref{cc,,pragma Pure_Function}. |
64d5610f ML |
9761 | |
9762 | @node Aspect Refined_Depends,Aspect Refined_Global,Aspect Pure_Function,Implementation Defined Aspects | |
067d80d8 | 9763 | @anchor{gnat_rm/implementation_defined_aspects aspect-refined-depends}@anchor{14b} |
64d5610f ML |
9764 | @section Aspect Refined_Depends |
9765 | ||
9766 | ||
9767 | @geindex Refined_Depends | |
9768 | ||
b71d4b62 | 9769 | This aspect is equivalent to @ref{d0,,pragma Refined_Depends}. |
64d5610f ML |
9770 | |
9771 | @node Aspect Refined_Global,Aspect Refined_Post,Aspect Refined_Depends,Implementation Defined Aspects | |
067d80d8 | 9772 | @anchor{gnat_rm/implementation_defined_aspects aspect-refined-global}@anchor{14c} |
64d5610f ML |
9773 | @section Aspect Refined_Global |
9774 | ||
9775 | ||
9776 | @geindex Refined_Global | |
9777 | ||
b71d4b62 | 9778 | This aspect is equivalent to @ref{d2,,pragma Refined_Global}. |
64d5610f ML |
9779 | |
9780 | @node Aspect Refined_Post,Aspect Refined_State,Aspect Refined_Global,Implementation Defined Aspects | |
067d80d8 | 9781 | @anchor{gnat_rm/implementation_defined_aspects aspect-refined-post}@anchor{14d} |
64d5610f ML |
9782 | @section Aspect Refined_Post |
9783 | ||
9784 | ||
9785 | @geindex Refined_Post | |
9786 | ||
b71d4b62 | 9787 | This aspect is equivalent to @ref{d4,,pragma Refined_Post}. |
64d5610f ML |
9788 | |
9789 | @node Aspect Refined_State,Aspect Relaxed_Initialization,Aspect Refined_Post,Implementation Defined Aspects | |
067d80d8 | 9790 | @anchor{gnat_rm/implementation_defined_aspects aspect-refined-state}@anchor{14e} |
64d5610f ML |
9791 | @section Aspect Refined_State |
9792 | ||
9793 | ||
9794 | @geindex Refined_State | |
9795 | ||
b71d4b62 | 9796 | This aspect is equivalent to @ref{d6,,pragma Refined_State}. |
64d5610f ML |
9797 | |
9798 | @node Aspect Relaxed_Initialization,Aspect Remote_Access_Type,Aspect Refined_State,Implementation Defined Aspects | |
067d80d8 | 9799 | @anchor{gnat_rm/implementation_defined_aspects aspect-relaxed-initialization}@anchor{14f} |
64d5610f ML |
9800 | @section Aspect Relaxed_Initialization |
9801 | ||
9802 | ||
9803 | @geindex Refined_Initialization | |
9804 | ||
9805 | For the syntax and semantics of this aspect, see the SPARK 2014 Reference | |
9806 | Manual, section 6.10. | |
9807 | ||
9808 | @node Aspect Remote_Access_Type,Aspect Secondary_Stack_Size,Aspect Relaxed_Initialization,Implementation Defined Aspects | |
067d80d8 | 9809 | @anchor{gnat_rm/implementation_defined_aspects aspect-remote-access-type}@anchor{150} |
64d5610f ML |
9810 | @section Aspect Remote_Access_Type |
9811 | ||
9812 | ||
9813 | @geindex Remote_Access_Type | |
9814 | ||
b71d4b62 | 9815 | This aspect is equivalent to @ref{d9,,pragma Remote_Access_Type}. |
64d5610f ML |
9816 | |
9817 | @node Aspect Secondary_Stack_Size,Aspect Scalar_Storage_Order,Aspect Remote_Access_Type,Implementation Defined Aspects | |
067d80d8 | 9818 | @anchor{gnat_rm/implementation_defined_aspects aspect-secondary-stack-size}@anchor{151} |
64d5610f ML |
9819 | @section Aspect Secondary_Stack_Size |
9820 | ||
9821 | ||
9822 | @geindex Secondary_Stack_Size | |
9823 | ||
b71d4b62 | 9824 | This aspect is equivalent to @ref{df,,pragma Secondary_Stack_Size}. |
64d5610f ML |
9825 | |
9826 | @node Aspect Scalar_Storage_Order,Aspect Shared,Aspect Secondary_Stack_Size,Implementation Defined Aspects | |
067d80d8 | 9827 | @anchor{gnat_rm/implementation_defined_aspects aspect-scalar-storage-order}@anchor{152} |
64d5610f ML |
9828 | @section Aspect Scalar_Storage_Order |
9829 | ||
9830 | ||
9831 | @geindex Scalar_Storage_Order | |
9832 | ||
067d80d8 | 9833 | This aspect is equivalent to a @ref{153,,attribute Scalar_Storage_Order}. |
64d5610f ML |
9834 | |
9835 | @node Aspect Shared,Aspect Simple_Storage_Pool,Aspect Scalar_Storage_Order,Implementation Defined Aspects | |
067d80d8 | 9836 | @anchor{gnat_rm/implementation_defined_aspects aspect-shared}@anchor{154} |
64d5610f ML |
9837 | @section Aspect Shared |
9838 | ||
9839 | ||
9840 | @geindex Shared | |
9841 | ||
b71d4b62 | 9842 | This boolean aspect is equivalent to @ref{e2,,pragma Shared} |
64d5610f ML |
9843 | and is thus a synonym for aspect @code{Atomic}. |
9844 | ||
9845 | @node Aspect Simple_Storage_Pool,Aspect Simple_Storage_Pool_Type,Aspect Shared,Implementation Defined Aspects | |
067d80d8 | 9846 | @anchor{gnat_rm/implementation_defined_aspects aspect-simple-storage-pool}@anchor{155} |
64d5610f ML |
9847 | @section Aspect Simple_Storage_Pool |
9848 | ||
9849 | ||
9850 | @geindex Simple_Storage_Pool | |
9851 | ||
b71d4b62 | 9852 | This aspect is equivalent to @ref{e7,,attribute Simple_Storage_Pool}. |
64d5610f ML |
9853 | |
9854 | @node Aspect Simple_Storage_Pool_Type,Aspect SPARK_Mode,Aspect Simple_Storage_Pool,Implementation Defined Aspects | |
067d80d8 | 9855 | @anchor{gnat_rm/implementation_defined_aspects aspect-simple-storage-pool-type}@anchor{156} |
64d5610f ML |
9856 | @section Aspect Simple_Storage_Pool_Type |
9857 | ||
9858 | ||
9859 | @geindex Simple_Storage_Pool_Type | |
9860 | ||
b71d4b62 | 9861 | This boolean aspect is equivalent to @ref{e6,,pragma Simple_Storage_Pool_Type}. |
64d5610f ML |
9862 | |
9863 | @node Aspect SPARK_Mode,Aspect Suppress_Debug_Info,Aspect Simple_Storage_Pool_Type,Implementation Defined Aspects | |
067d80d8 | 9864 | @anchor{gnat_rm/implementation_defined_aspects aspect-spark-mode}@anchor{157} |
64d5610f ML |
9865 | @section Aspect SPARK_Mode |
9866 | ||
9867 | ||
9868 | @geindex SPARK_Mode | |
9869 | ||
b71d4b62 | 9870 | This aspect is equivalent to @ref{ee,,pragma SPARK_Mode} and |
64d5610f ML |
9871 | may be specified for either or both of the specification and body |
9872 | of a subprogram or package. | |
9873 | ||
9874 | @node Aspect Suppress_Debug_Info,Aspect Suppress_Initialization,Aspect SPARK_Mode,Implementation Defined Aspects | |
067d80d8 | 9875 | @anchor{gnat_rm/implementation_defined_aspects aspect-suppress-debug-info}@anchor{158} |
64d5610f ML |
9876 | @section Aspect Suppress_Debug_Info |
9877 | ||
9878 | ||
9879 | @geindex Suppress_Debug_Info | |
9880 | ||
b71d4b62 | 9881 | This boolean aspect is equivalent to @ref{f6,,pragma Suppress_Debug_Info}. |
64d5610f ML |
9882 | |
9883 | @node Aspect Suppress_Initialization,Aspect Test_Case,Aspect Suppress_Debug_Info,Implementation Defined Aspects | |
067d80d8 | 9884 | @anchor{gnat_rm/implementation_defined_aspects aspect-suppress-initialization}@anchor{159} |
64d5610f ML |
9885 | @section Aspect Suppress_Initialization |
9886 | ||
9887 | ||
9888 | @geindex Suppress_Initialization | |
9889 | ||
b71d4b62 | 9890 | This boolean aspect is equivalent to @ref{f9,,pragma Suppress_Initialization}. |
64d5610f ML |
9891 | |
9892 | @node Aspect Test_Case,Aspect Thread_Local_Storage,Aspect Suppress_Initialization,Implementation Defined Aspects | |
067d80d8 | 9893 | @anchor{gnat_rm/implementation_defined_aspects aspect-test-case}@anchor{15a} |
64d5610f ML |
9894 | @section Aspect Test_Case |
9895 | ||
9896 | ||
9897 | @geindex Test_Case | |
9898 | ||
b71d4b62 | 9899 | This aspect is equivalent to @ref{fd,,pragma Test_Case}. |
64d5610f ML |
9900 | |
9901 | @node Aspect Thread_Local_Storage,Aspect Universal_Aliasing,Aspect Test_Case,Implementation Defined Aspects | |
067d80d8 | 9902 | @anchor{gnat_rm/implementation_defined_aspects aspect-thread-local-storage}@anchor{15b} |
64d5610f ML |
9903 | @section Aspect Thread_Local_Storage |
9904 | ||
9905 | ||
9906 | @geindex Thread_Local_Storage | |
9907 | ||
b71d4b62 | 9908 | This boolean aspect is equivalent to @ref{ff,,pragma Thread_Local_Storage}. |
64d5610f ML |
9909 | |
9910 | @node Aspect Universal_Aliasing,Aspect Unmodified,Aspect Thread_Local_Storage,Implementation Defined Aspects | |
067d80d8 | 9911 | @anchor{gnat_rm/implementation_defined_aspects aspect-universal-aliasing}@anchor{15c} |
64d5610f ML |
9912 | @section Aspect Universal_Aliasing |
9913 | ||
9914 | ||
9915 | @geindex Universal_Aliasing | |
9916 | ||
b71d4b62 | 9917 | This boolean aspect is equivalent to @ref{109,,pragma Universal_Aliasing}. |
64d5610f ML |
9918 | |
9919 | @node Aspect Unmodified,Aspect Unreferenced,Aspect Universal_Aliasing,Implementation Defined Aspects | |
067d80d8 | 9920 | @anchor{gnat_rm/implementation_defined_aspects aspect-unmodified}@anchor{15d} |
64d5610f ML |
9921 | @section Aspect Unmodified |
9922 | ||
9923 | ||
9924 | @geindex Unmodified | |
9925 | ||
b71d4b62 | 9926 | This boolean aspect is equivalent to @ref{10b,,pragma Unmodified}. |
64d5610f ML |
9927 | |
9928 | @node Aspect Unreferenced,Aspect Unreferenced_Objects,Aspect Unmodified,Implementation Defined Aspects | |
067d80d8 | 9929 | @anchor{gnat_rm/implementation_defined_aspects aspect-unreferenced}@anchor{15e} |
64d5610f ML |
9930 | @section Aspect Unreferenced |
9931 | ||
9932 | ||
9933 | @geindex Unreferenced | |
9934 | ||
b71d4b62 | 9935 | This boolean aspect is equivalent to @ref{10d,,pragma Unreferenced}. |
64d5610f ML |
9936 | |
9937 | When using the @code{-gnat2022} switch, this aspect is also supported on formal | |
9938 | parameters, which is in particular the only form possible for expression | |
9939 | functions. | |
9940 | ||
9941 | @node Aspect Unreferenced_Objects,Aspect Value_Size,Aspect Unreferenced,Implementation Defined Aspects | |
067d80d8 | 9942 | @anchor{gnat_rm/implementation_defined_aspects aspect-unreferenced-objects}@anchor{15f} |
64d5610f ML |
9943 | @section Aspect Unreferenced_Objects |
9944 | ||
9945 | ||
9946 | @geindex Unreferenced_Objects | |
9947 | ||
b71d4b62 | 9948 | This boolean aspect is equivalent to @ref{10f,,pragma Unreferenced_Objects}. |
64d5610f ML |
9949 | |
9950 | @node Aspect Value_Size,Aspect Volatile_Full_Access,Aspect Unreferenced_Objects,Implementation Defined Aspects | |
067d80d8 | 9951 | @anchor{gnat_rm/implementation_defined_aspects aspect-value-size}@anchor{160} |
64d5610f ML |
9952 | @section Aspect Value_Size |
9953 | ||
9954 | ||
9955 | @geindex Value_Size | |
9956 | ||
067d80d8 | 9957 | This aspect is equivalent to @ref{161,,attribute Value_Size}. |
64d5610f ML |
9958 | |
9959 | @node Aspect Volatile_Full_Access,Aspect Volatile_Function,Aspect Value_Size,Implementation Defined Aspects | |
067d80d8 | 9960 | @anchor{gnat_rm/implementation_defined_aspects aspect-volatile-full-access}@anchor{162} |
64d5610f ML |
9961 | @section Aspect Volatile_Full_Access |
9962 | ||
9963 | ||
9964 | @geindex Volatile_Full_Access | |
9965 | ||
b71d4b62 | 9966 | This boolean aspect is equivalent to @ref{119,,pragma Volatile_Full_Access}. |
64d5610f ML |
9967 | |
9968 | @node Aspect Volatile_Function,Aspect Warnings,Aspect Volatile_Full_Access,Implementation Defined Aspects | |
067d80d8 | 9969 | @anchor{gnat_rm/implementation_defined_aspects aspect-volatile-function}@anchor{163} |
64d5610f ML |
9970 | @section Aspect Volatile_Function |
9971 | ||
9972 | ||
9973 | @geindex Volatile_Function | |
9974 | ||
b71d4b62 | 9975 | This boolean aspect is equivalent to @ref{11b,,pragma Volatile_Function}. |
64d5610f ML |
9976 | |
9977 | @node Aspect Warnings,,Aspect Volatile_Function,Implementation Defined Aspects | |
067d80d8 | 9978 | @anchor{gnat_rm/implementation_defined_aspects aspect-warnings}@anchor{164} |
64d5610f ML |
9979 | @section Aspect Warnings |
9980 | ||
9981 | ||
9982 | @geindex Warnings | |
9983 | ||
b71d4b62 | 9984 | This aspect is equivalent to the two argument form of @ref{11d,,pragma Warnings}, |
64d5610f ML |
9985 | where the first argument is @code{ON} or @code{OFF} and the second argument |
9986 | is the entity. | |
9987 | ||
9988 | @node Implementation Defined Attributes,Standard and Implementation Defined Restrictions,Implementation Defined Aspects,Top | |
067d80d8 | 9989 | @anchor{gnat_rm/implementation_defined_attributes doc}@anchor{165}@anchor{gnat_rm/implementation_defined_attributes id1}@anchor{166}@anchor{gnat_rm/implementation_defined_attributes implementation-defined-attributes}@anchor{8} |
64d5610f ML |
9990 | @chapter Implementation Defined Attributes |
9991 | ||
9992 | ||
9993 | Ada defines (throughout the Ada reference manual, | |
9994 | summarized in Annex K), | |
9995 | a set of attributes that provide useful additional functionality in all | |
9996 | areas of the language. These language defined attributes are implemented | |
9997 | in GNAT and work as described in the Ada Reference Manual. | |
9998 | ||
9999 | In addition, Ada allows implementations to define additional | |
10000 | attributes whose meaning is defined by the implementation. GNAT provides | |
10001 | a number of these implementation-dependent attributes which can be used | |
10002 | to extend and enhance the functionality of the compiler. This section of | |
10003 | the GNAT reference manual describes these additional attributes. It also | |
10004 | describes additional implementation-dependent features of standard | |
10005 | language-defined attributes. | |
10006 | ||
10007 | Note that any program using these attributes may not be portable to | |
10008 | other compilers (although GNAT implements this set of attributes on all | |
10009 | platforms). Therefore if portability to other compilers is an important | |
10010 | consideration, you should minimize the use of these attributes. | |
10011 | ||
10012 | @menu | |
10013 | * Attribute Abort_Signal:: | |
10014 | * Attribute Address_Size:: | |
10015 | * Attribute Asm_Input:: | |
10016 | * Attribute Asm_Output:: | |
10017 | * Attribute Atomic_Always_Lock_Free:: | |
10018 | * Attribute Bit:: | |
10019 | * Attribute Bit_Position:: | |
10020 | * Attribute Code_Address:: | |
10021 | * Attribute Compiler_Version:: | |
10022 | * Attribute Constrained:: | |
10023 | * Attribute Default_Bit_Order:: | |
10024 | * Attribute Default_Scalar_Storage_Order:: | |
10025 | * Attribute Deref:: | |
10026 | * Attribute Descriptor_Size:: | |
10027 | * Attribute Elaborated:: | |
10028 | * Attribute Elab_Body:: | |
10029 | * Attribute Elab_Spec:: | |
10030 | * Attribute Elab_Subp_Body:: | |
10031 | * Attribute Emax:: | |
10032 | * Attribute Enabled:: | |
10033 | * Attribute Enum_Rep:: | |
10034 | * Attribute Enum_Val:: | |
10035 | * Attribute Epsilon:: | |
10036 | * Attribute Fast_Math:: | |
10037 | * Attribute Finalization_Size:: | |
10038 | * Attribute Fixed_Value:: | |
10039 | * Attribute From_Any:: | |
10040 | * Attribute Has_Access_Values:: | |
10041 | * Attribute Has_Discriminants:: | |
10042 | * Attribute Has_Tagged_Values:: | |
10043 | * Attribute Img:: | |
10044 | * Attribute Initialized:: | |
10045 | * Attribute Integer_Value:: | |
10046 | * Attribute Invalid_Value:: | |
10047 | * Attribute Iterable:: | |
10048 | * Attribute Large:: | |
10049 | * Attribute Library_Level:: | |
10050 | * Attribute Loop_Entry:: | |
10051 | * Attribute Machine_Size:: | |
10052 | * Attribute Mantissa:: | |
10053 | * Attribute Maximum_Alignment:: | |
10054 | * Attribute Max_Integer_Size:: | |
10055 | * Attribute Mechanism_Code:: | |
10056 | * Attribute Null_Parameter:: | |
10057 | * Attribute Object_Size:: | |
10058 | * Attribute Old:: | |
10059 | * Attribute Passed_By_Reference:: | |
10060 | * Attribute Pool_Address:: | |
10061 | * Attribute Range_Length:: | |
10062 | * Attribute Restriction_Set:: | |
10063 | * Attribute Result:: | |
10064 | * Attribute Safe_Emax:: | |
10065 | * Attribute Safe_Large:: | |
10066 | * Attribute Safe_Small:: | |
10067 | * Attribute Scalar_Storage_Order:: | |
10068 | * Attribute Simple_Storage_Pool:: | |
10069 | * Attribute Small:: | |
10070 | * Attribute Small_Denominator:: | |
10071 | * Attribute Small_Numerator:: | |
10072 | * Attribute Storage_Unit:: | |
10073 | * Attribute Stub_Type:: | |
10074 | * Attribute System_Allocator_Alignment:: | |
10075 | * Attribute Target_Name:: | |
10076 | * Attribute To_Address:: | |
10077 | * Attribute To_Any:: | |
10078 | * Attribute Type_Class:: | |
10079 | * Attribute Type_Key:: | |
10080 | * Attribute TypeCode:: | |
10081 | * Attribute Unconstrained_Array:: | |
10082 | * Attribute Universal_Literal_String:: | |
10083 | * Attribute Unrestricted_Access:: | |
10084 | * Attribute Update:: | |
10085 | * Attribute Valid_Value:: | |
10086 | * Attribute Valid_Scalars:: | |
10087 | * Attribute VADS_Size:: | |
10088 | * Attribute Value_Size:: | |
10089 | * Attribute Wchar_T_Size:: | |
10090 | * Attribute Word_Size:: | |
10091 | ||
10092 | @end menu | |
10093 | ||
10094 | @node Attribute Abort_Signal,Attribute Address_Size,,Implementation Defined Attributes | |
067d80d8 | 10095 | @anchor{gnat_rm/implementation_defined_attributes attribute-abort-signal}@anchor{167} |
64d5610f ML |
10096 | @section Attribute Abort_Signal |
10097 | ||
10098 | ||
10099 | @geindex Abort_Signal | |
10100 | ||
10101 | @code{Standard'Abort_Signal} (@code{Standard} is the only allowed | |
10102 | prefix) provides the entity for the special exception used to signal | |
10103 | task abort or asynchronous transfer of control. Normally this attribute | |
10104 | should only be used in the tasking runtime (it is highly peculiar, and | |
10105 | completely outside the normal semantics of Ada, for a user program to | |
10106 | intercept the abort exception). | |
10107 | ||
10108 | @node Attribute Address_Size,Attribute Asm_Input,Attribute Abort_Signal,Implementation Defined Attributes | |
067d80d8 | 10109 | @anchor{gnat_rm/implementation_defined_attributes attribute-address-size}@anchor{168} |
64d5610f ML |
10110 | @section Attribute Address_Size |
10111 | ||
10112 | ||
10113 | @geindex Size of `@w{`}Address`@w{`} | |
10114 | ||
10115 | @geindex Address_Size | |
10116 | ||
10117 | @code{Standard'Address_Size} (@code{Standard} is the only allowed | |
10118 | prefix) is a static constant giving the number of bits in an | |
10119 | @code{Address}. It is the same value as System.Address’Size, | |
10120 | but has the advantage of being static, while a direct | |
10121 | reference to System.Address’Size is nonstatic because Address | |
10122 | is a private type. | |
10123 | ||
10124 | @node Attribute Asm_Input,Attribute Asm_Output,Attribute Address_Size,Implementation Defined Attributes | |
067d80d8 | 10125 | @anchor{gnat_rm/implementation_defined_attributes attribute-asm-input}@anchor{169} |
64d5610f ML |
10126 | @section Attribute Asm_Input |
10127 | ||
10128 | ||
10129 | @geindex Asm_Input | |
10130 | ||
10131 | The @code{Asm_Input} attribute denotes a function that takes two | |
10132 | parameters. The first is a string, the second is an expression of the | |
10133 | type designated by the prefix. The first (string) argument is required | |
10134 | to be a static expression, and is the constraint for the parameter, | |
10135 | (e.g., what kind of register is required). The second argument is the | |
10136 | value to be used as the input argument. The possible values for the | |
10137 | constant are the same as those used in the RTL, and are dependent on | |
10138 | the configuration file used to built the GCC back end. | |
067d80d8 | 10139 | @ref{16a,,Machine Code Insertions} |
64d5610f ML |
10140 | |
10141 | @node Attribute Asm_Output,Attribute Atomic_Always_Lock_Free,Attribute Asm_Input,Implementation Defined Attributes | |
067d80d8 | 10142 | @anchor{gnat_rm/implementation_defined_attributes attribute-asm-output}@anchor{16b} |
64d5610f ML |
10143 | @section Attribute Asm_Output |
10144 | ||
10145 | ||
10146 | @geindex Asm_Output | |
10147 | ||
10148 | The @code{Asm_Output} attribute denotes a function that takes two | |
10149 | parameters. The first is a string, the second is the name of a variable | |
10150 | of the type designated by the attribute prefix. The first (string) | |
10151 | argument is required to be a static expression and designates the | |
10152 | constraint for the parameter (e.g., what kind of register is | |
10153 | required). The second argument is the variable to be updated with the | |
10154 | result. The possible values for constraint are the same as those used in | |
10155 | the RTL, and are dependent on the configuration file used to build the | |
10156 | GCC back end. If there are no output operands, then this argument may | |
10157 | either be omitted, or explicitly given as @code{No_Output_Operands}. | |
067d80d8 | 10158 | @ref{16a,,Machine Code Insertions} |
64d5610f ML |
10159 | |
10160 | @node Attribute Atomic_Always_Lock_Free,Attribute Bit,Attribute Asm_Output,Implementation Defined Attributes | |
067d80d8 | 10161 | @anchor{gnat_rm/implementation_defined_attributes attribute-atomic-always-lock-free}@anchor{16c} |
64d5610f ML |
10162 | @section Attribute Atomic_Always_Lock_Free |
10163 | ||
10164 | ||
10165 | @geindex Atomic_Always_Lock_Free | |
10166 | ||
10167 | The prefix of the @code{Atomic_Always_Lock_Free} attribute is a type. | |
10168 | The result is a Boolean value which is True if the type has discriminants, | |
10169 | and False otherwise. The result indicate whether atomic operations are | |
10170 | supported by the target for the given type. | |
10171 | ||
10172 | @node Attribute Bit,Attribute Bit_Position,Attribute Atomic_Always_Lock_Free,Implementation Defined Attributes | |
067d80d8 | 10173 | @anchor{gnat_rm/implementation_defined_attributes attribute-bit}@anchor{16d} |
64d5610f ML |
10174 | @section Attribute Bit |
10175 | ||
10176 | ||
10177 | @geindex Bit | |
10178 | ||
10179 | @code{obj'Bit}, where @code{obj} is any object, yields the bit | |
10180 | offset within the storage unit (byte) that contains the first bit of | |
10181 | storage allocated for the object. The value of this attribute is of the | |
10182 | type `universal_integer' and is always a nonnegative number smaller | |
10183 | than @code{System.Storage_Unit}. | |
10184 | ||
10185 | For an object that is a variable or a constant allocated in a register, | |
10186 | the value is zero. (The use of this attribute does not force the | |
10187 | allocation of a variable to memory). | |
10188 | ||
10189 | For an object that is a formal parameter, this attribute applies | |
10190 | to either the matching actual parameter or to a copy of the | |
10191 | matching actual parameter. | |
10192 | ||
10193 | For an access object the value is zero. Note that | |
10194 | @code{obj.all'Bit} is subject to an @code{Access_Check} for the | |
10195 | designated object. Similarly for a record component | |
10196 | @code{X.C'Bit} is subject to a discriminant check and | |
10197 | @code{X(I).Bit} and @code{X(I1..I2)'Bit} | |
10198 | are subject to index checks. | |
10199 | ||
10200 | This attribute is designed to be compatible with the DEC Ada 83 definition | |
10201 | and implementation of the @code{Bit} attribute. | |
10202 | ||
10203 | @node Attribute Bit_Position,Attribute Code_Address,Attribute Bit,Implementation Defined Attributes | |
067d80d8 | 10204 | @anchor{gnat_rm/implementation_defined_attributes attribute-bit-position}@anchor{16e} |
64d5610f ML |
10205 | @section Attribute Bit_Position |
10206 | ||
10207 | ||
10208 | @geindex Bit_Position | |
10209 | ||
10210 | @code{R.C'Bit_Position}, where @code{R} is a record object and @code{C} is one | |
10211 | of the fields of the record type, yields the bit | |
10212 | offset within the record contains the first bit of | |
10213 | storage allocated for the object. The value of this attribute is of the | |
10214 | type `universal_integer'. The value depends only on the field | |
10215 | @code{C} and is independent of the alignment of | |
10216 | the containing record @code{R}. | |
10217 | ||
10218 | @node Attribute Code_Address,Attribute Compiler_Version,Attribute Bit_Position,Implementation Defined Attributes | |
067d80d8 | 10219 | @anchor{gnat_rm/implementation_defined_attributes attribute-code-address}@anchor{16f} |
64d5610f ML |
10220 | @section Attribute Code_Address |
10221 | ||
10222 | ||
10223 | @geindex Code_Address | |
10224 | ||
10225 | @geindex Subprogram address | |
10226 | ||
10227 | @geindex Address of subprogram code | |
10228 | ||
10229 | The @code{'Address} | |
10230 | attribute may be applied to subprograms in Ada 95 and Ada 2005, but the | |
10231 | intended effect seems to be to provide | |
10232 | an address value which can be used to call the subprogram by means of | |
10233 | an address clause as in the following example: | |
10234 | ||
10235 | @example | |
10236 | procedure K is ... | |
10237 | ||
10238 | procedure L; | |
10239 | for L'Address use K'Address; | |
10240 | pragma Import (Ada, L); | |
10241 | @end example | |
10242 | ||
10243 | A call to @code{L} is then expected to result in a call to @code{K}. | |
10244 | In Ada 83, where there were no access-to-subprogram values, this was | |
10245 | a common work-around for getting the effect of an indirect call. | |
10246 | GNAT implements the above use of @code{Address} and the technique | |
10247 | illustrated by the example code works correctly. | |
10248 | ||
10249 | However, for some purposes, it is useful to have the address of the start | |
10250 | of the generated code for the subprogram. On some architectures, this is | |
10251 | not necessarily the same as the @code{Address} value described above. | |
10252 | For example, the @code{Address} value may reference a subprogram | |
10253 | descriptor rather than the subprogram itself. | |
10254 | ||
10255 | The @code{'Code_Address} attribute, which can only be applied to | |
10256 | subprogram entities, always returns the address of the start of the | |
10257 | generated code of the specified subprogram, which may or may not be | |
10258 | the same value as is returned by the corresponding @code{'Address} | |
10259 | attribute. | |
10260 | ||
10261 | @node Attribute Compiler_Version,Attribute Constrained,Attribute Code_Address,Implementation Defined Attributes | |
067d80d8 | 10262 | @anchor{gnat_rm/implementation_defined_attributes attribute-compiler-version}@anchor{170} |
64d5610f ML |
10263 | @section Attribute Compiler_Version |
10264 | ||
10265 | ||
10266 | @geindex Compiler_Version | |
10267 | ||
10268 | @code{Standard'Compiler_Version} (@code{Standard} is the only allowed | |
10269 | prefix) yields a static string identifying the version of the compiler | |
10270 | being used to compile the unit containing the attribute reference. | |
10271 | ||
10272 | @node Attribute Constrained,Attribute Default_Bit_Order,Attribute Compiler_Version,Implementation Defined Attributes | |
067d80d8 | 10273 | @anchor{gnat_rm/implementation_defined_attributes attribute-constrained}@anchor{171} |
64d5610f ML |
10274 | @section Attribute Constrained |
10275 | ||
10276 | ||
10277 | @geindex Constrained | |
10278 | ||
10279 | In addition to the usage of this attribute in the Ada RM, GNAT | |
10280 | also permits the use of the @code{'Constrained} attribute | |
10281 | in a generic template | |
10282 | for any type, including types without discriminants. The value of this | |
10283 | attribute in the generic instance when applied to a scalar type or a | |
10284 | record type without discriminants is always @code{True}. This usage is | |
10285 | compatible with older Ada compilers, including notably DEC Ada. | |
10286 | ||
10287 | @node Attribute Default_Bit_Order,Attribute Default_Scalar_Storage_Order,Attribute Constrained,Implementation Defined Attributes | |
067d80d8 | 10288 | @anchor{gnat_rm/implementation_defined_attributes attribute-default-bit-order}@anchor{172} |
64d5610f ML |
10289 | @section Attribute Default_Bit_Order |
10290 | ||
10291 | ||
10292 | @geindex Big endian | |
10293 | ||
10294 | @geindex Little endian | |
10295 | ||
10296 | @geindex Default_Bit_Order | |
10297 | ||
10298 | @code{Standard'Default_Bit_Order} (@code{Standard} is the only | |
10299 | allowed prefix), provides the value @code{System.Default_Bit_Order} | |
10300 | as a @code{Pos} value (0 for @code{High_Order_First}, 1 for | |
10301 | @code{Low_Order_First}). This is used to construct the definition of | |
10302 | @code{Default_Bit_Order} in package @code{System}. | |
10303 | ||
10304 | @node Attribute Default_Scalar_Storage_Order,Attribute Deref,Attribute Default_Bit_Order,Implementation Defined Attributes | |
067d80d8 | 10305 | @anchor{gnat_rm/implementation_defined_attributes attribute-default-scalar-storage-order}@anchor{173} |
64d5610f ML |
10306 | @section Attribute Default_Scalar_Storage_Order |
10307 | ||
10308 | ||
10309 | @geindex Big endian | |
10310 | ||
10311 | @geindex Little endian | |
10312 | ||
10313 | @geindex Default_Scalar_Storage_Order | |
10314 | ||
10315 | @code{Standard'Default_Scalar_Storage_Order} (@code{Standard} is the only | |
10316 | allowed prefix), provides the current value of the default scalar storage | |
10317 | order (as specified using pragma @code{Default_Scalar_Storage_Order}, or | |
10318 | equal to @code{Default_Bit_Order} if unspecified) as a | |
10319 | @code{System.Bit_Order} value. This is a static attribute. | |
10320 | ||
10321 | @node Attribute Deref,Attribute Descriptor_Size,Attribute Default_Scalar_Storage_Order,Implementation Defined Attributes | |
067d80d8 | 10322 | @anchor{gnat_rm/implementation_defined_attributes attribute-deref}@anchor{174} |
64d5610f ML |
10323 | @section Attribute Deref |
10324 | ||
10325 | ||
10326 | @geindex Deref | |
10327 | ||
10328 | The attribute @code{typ'Deref(expr)} where @code{expr} is of type @code{System.Address} yields | |
10329 | the variable of type @code{typ} that is located at the given address. It is similar | |
10330 | to @code{(totyp (expr).all)}, where @code{totyp} is an unchecked conversion from address to | |
10331 | a named access-to-@cite{typ} type, except that it yields a variable, so it can be | |
10332 | used on the left side of an assignment. | |
10333 | ||
10334 | @node Attribute Descriptor_Size,Attribute Elaborated,Attribute Deref,Implementation Defined Attributes | |
067d80d8 | 10335 | @anchor{gnat_rm/implementation_defined_attributes attribute-descriptor-size}@anchor{175} |
64d5610f ML |
10336 | @section Attribute Descriptor_Size |
10337 | ||
10338 | ||
10339 | @geindex Descriptor | |
10340 | ||
10341 | @geindex Dope vector | |
10342 | ||
10343 | @geindex Descriptor_Size | |
10344 | ||
10345 | Nonstatic attribute @code{Descriptor_Size} returns the size in bits of the | |
10346 | descriptor allocated for a type. The result is non-zero only for unconstrained | |
10347 | array types and the returned value is of type universal integer. In GNAT, an | |
10348 | array descriptor contains bounds information and is located immediately before | |
10349 | the first element of the array. | |
10350 | ||
10351 | @example | |
10352 | type Unconstr_Array is array (Short_Short_Integer range <>) of Positive; | |
10353 | Put_Line ("Descriptor size = " & Unconstr_Array'Descriptor_Size'Img); | |
10354 | @end example | |
10355 | ||
10356 | The attribute takes into account any padding due to the alignment of the | |
10357 | component type. In the example above, the descriptor contains two values | |
10358 | of type @code{Short_Short_Integer} representing the low and high bound. But, | |
10359 | since @code{Positive} has an alignment of 4, the size of the descriptor is | |
10360 | @code{2 * Short_Short_Integer'Size} rounded up to the next multiple of 32, | |
10361 | which yields a size of 32 bits, i.e. including 16 bits of padding. | |
10362 | ||
10363 | @node Attribute Elaborated,Attribute Elab_Body,Attribute Descriptor_Size,Implementation Defined Attributes | |
067d80d8 | 10364 | @anchor{gnat_rm/implementation_defined_attributes attribute-elaborated}@anchor{176} |
64d5610f ML |
10365 | @section Attribute Elaborated |
10366 | ||
10367 | ||
10368 | @geindex Elaborated | |
10369 | ||
10370 | The prefix of the @code{'Elaborated} attribute must be a unit name. The | |
10371 | value is a Boolean which indicates whether or not the given unit has been | |
10372 | elaborated. This attribute is primarily intended for internal use by the | |
10373 | generated code for dynamic elaboration checking, but it can also be used | |
10374 | in user programs. The value will always be True once elaboration of all | |
10375 | units has been completed. An exception is for units which need no | |
10376 | elaboration, the value is always False for such units. | |
10377 | ||
10378 | @node Attribute Elab_Body,Attribute Elab_Spec,Attribute Elaborated,Implementation Defined Attributes | |
067d80d8 | 10379 | @anchor{gnat_rm/implementation_defined_attributes attribute-elab-body}@anchor{177} |
64d5610f ML |
10380 | @section Attribute Elab_Body |
10381 | ||
10382 | ||
10383 | @geindex Elab_Body | |
10384 | ||
10385 | This attribute can only be applied to a program unit name. It returns | |
10386 | the entity for the corresponding elaboration procedure for elaborating | |
10387 | the body of the referenced unit. This is used in the main generated | |
10388 | elaboration procedure by the binder and is not normally used in any | |
10389 | other context. However, there may be specialized situations in which it | |
10390 | is useful to be able to call this elaboration procedure from Ada code, | |
10391 | e.g., if it is necessary to do selective re-elaboration to fix some | |
10392 | error. | |
10393 | ||
10394 | @node Attribute Elab_Spec,Attribute Elab_Subp_Body,Attribute Elab_Body,Implementation Defined Attributes | |
067d80d8 | 10395 | @anchor{gnat_rm/implementation_defined_attributes attribute-elab-spec}@anchor{178} |
64d5610f ML |
10396 | @section Attribute Elab_Spec |
10397 | ||
10398 | ||
10399 | @geindex Elab_Spec | |
10400 | ||
10401 | This attribute can only be applied to a program unit name. It returns | |
10402 | the entity for the corresponding elaboration procedure for elaborating | |
10403 | the spec of the referenced unit. This is used in the main | |
10404 | generated elaboration procedure by the binder and is not normally used | |
10405 | in any other context. However, there may be specialized situations in | |
10406 | which it is useful to be able to call this elaboration procedure from | |
10407 | Ada code, e.g., if it is necessary to do selective re-elaboration to fix | |
10408 | some error. | |
10409 | ||
10410 | @node Attribute Elab_Subp_Body,Attribute Emax,Attribute Elab_Spec,Implementation Defined Attributes | |
067d80d8 | 10411 | @anchor{gnat_rm/implementation_defined_attributes attribute-elab-subp-body}@anchor{179} |
64d5610f ML |
10412 | @section Attribute Elab_Subp_Body |
10413 | ||
10414 | ||
10415 | @geindex Elab_Subp_Body | |
10416 | ||
10417 | This attribute can only be applied to a library level subprogram | |
10418 | name and is only allowed in CodePeer mode. It returns the entity | |
10419 | for the corresponding elaboration procedure for elaborating the body | |
10420 | of the referenced subprogram unit. This is used in the main generated | |
10421 | elaboration procedure by the binder in CodePeer mode only and is unrecognized | |
10422 | otherwise. | |
10423 | ||
10424 | @node Attribute Emax,Attribute Enabled,Attribute Elab_Subp_Body,Implementation Defined Attributes | |
067d80d8 | 10425 | @anchor{gnat_rm/implementation_defined_attributes attribute-emax}@anchor{17a} |
64d5610f ML |
10426 | @section Attribute Emax |
10427 | ||
10428 | ||
10429 | @geindex Ada 83 attributes | |
10430 | ||
10431 | @geindex Emax | |
10432 | ||
10433 | The @code{Emax} attribute is provided for compatibility with Ada 83. See | |
10434 | the Ada 83 reference manual for an exact description of the semantics of | |
10435 | this attribute. | |
10436 | ||
10437 | @node Attribute Enabled,Attribute Enum_Rep,Attribute Emax,Implementation Defined Attributes | |
067d80d8 | 10438 | @anchor{gnat_rm/implementation_defined_attributes attribute-enabled}@anchor{17b} |
64d5610f ML |
10439 | @section Attribute Enabled |
10440 | ||
10441 | ||
10442 | @geindex Enabled | |
10443 | ||
10444 | The @code{Enabled} attribute allows an application program to check at compile | |
10445 | time to see if the designated check is currently enabled. The prefix is a | |
10446 | simple identifier, referencing any predefined check name (other than | |
10447 | @code{All_Checks}) or a check name introduced by pragma Check_Name. If | |
10448 | no argument is given for the attribute, the check is for the general state | |
10449 | of the check, if an argument is given, then it is an entity name, and the | |
10450 | check indicates whether an @code{Suppress} or @code{Unsuppress} has been | |
10451 | given naming the entity (if not, then the argument is ignored). | |
10452 | ||
10453 | Note that instantiations inherit the check status at the point of the | |
10454 | instantiation, so a useful idiom is to have a library package that | |
10455 | introduces a check name with @code{pragma Check_Name}, and then contains | |
10456 | generic packages or subprograms which use the @code{Enabled} attribute | |
10457 | to see if the check is enabled. A user of this package can then issue | |
10458 | a @code{pragma Suppress} or @code{pragma Unsuppress} before instantiating | |
10459 | the package or subprogram, controlling whether the check will be present. | |
10460 | ||
10461 | @node Attribute Enum_Rep,Attribute Enum_Val,Attribute Enabled,Implementation Defined Attributes | |
067d80d8 | 10462 | @anchor{gnat_rm/implementation_defined_attributes attribute-enum-rep}@anchor{17c} |
64d5610f ML |
10463 | @section Attribute Enum_Rep |
10464 | ||
10465 | ||
10466 | @geindex Representation of enums | |
10467 | ||
10468 | @geindex Enum_Rep | |
10469 | ||
10470 | Note that this attribute is now standard in Ada 202x and is available | |
10471 | as an implementation defined attribute for earlier Ada versions. | |
10472 | ||
10473 | For every enumeration subtype @code{S}, @code{S'Enum_Rep} denotes a | |
10474 | function with the following spec: | |
10475 | ||
10476 | @example | |
10477 | function S'Enum_Rep (Arg : S'Base) return <Universal_Integer>; | |
10478 | @end example | |
10479 | ||
10480 | It is also allowable to apply @code{Enum_Rep} directly to an object of an | |
10481 | enumeration type or to a non-overloaded enumeration | |
10482 | literal. In this case @code{S'Enum_Rep} is equivalent to | |
10483 | @code{typ'Enum_Rep(S)} where @code{typ} is the type of the | |
10484 | enumeration literal or object. | |
10485 | ||
10486 | The function returns the representation value for the given enumeration | |
10487 | value. This will be equal to value of the @code{Pos} attribute in the | |
10488 | absence of an enumeration representation clause. This is a static | |
10489 | attribute (i.e., the result is static if the argument is static). | |
10490 | ||
10491 | @code{S'Enum_Rep} can also be used with integer types and objects, | |
10492 | in which case it simply returns the integer value. The reason for this | |
10493 | is to allow it to be used for @code{(<>)} discrete formal arguments in | |
10494 | a generic unit that can be instantiated with either enumeration types | |
10495 | or integer types. Note that if @code{Enum_Rep} is used on a modular | |
10496 | type whose upper bound exceeds the upper bound of the largest signed | |
10497 | integer type, and the argument is a variable, so that the universal | |
10498 | integer calculation is done at run time, then the call to @code{Enum_Rep} | |
10499 | may raise @code{Constraint_Error}. | |
10500 | ||
10501 | @node Attribute Enum_Val,Attribute Epsilon,Attribute Enum_Rep,Implementation Defined Attributes | |
067d80d8 | 10502 | @anchor{gnat_rm/implementation_defined_attributes attribute-enum-val}@anchor{17d} |
64d5610f ML |
10503 | @section Attribute Enum_Val |
10504 | ||
10505 | ||
10506 | @geindex Representation of enums | |
10507 | ||
10508 | @geindex Enum_Val | |
10509 | ||
10510 | Note that this attribute is now standard in Ada 202x and is available | |
10511 | as an implementation defined attribute for earlier Ada versions. | |
10512 | ||
10513 | For every enumeration subtype @code{S}, @code{S'Enum_Val} denotes a | |
10514 | function with the following spec: | |
10515 | ||
10516 | @example | |
10517 | function S'Enum_Val (Arg : <Universal_Integer>) return S'Base; | |
10518 | @end example | |
10519 | ||
10520 | The function returns the enumeration value whose representation matches the | |
10521 | argument, or raises Constraint_Error if no enumeration literal of the type | |
10522 | has the matching value. | |
10523 | This will be equal to value of the @code{Val} attribute in the | |
10524 | absence of an enumeration representation clause. This is a static | |
10525 | attribute (i.e., the result is static if the argument is static). | |
10526 | ||
10527 | @node Attribute Epsilon,Attribute Fast_Math,Attribute Enum_Val,Implementation Defined Attributes | |
067d80d8 | 10528 | @anchor{gnat_rm/implementation_defined_attributes attribute-epsilon}@anchor{17e} |
64d5610f ML |
10529 | @section Attribute Epsilon |
10530 | ||
10531 | ||
10532 | @geindex Ada 83 attributes | |
10533 | ||
10534 | @geindex Epsilon | |
10535 | ||
10536 | The @code{Epsilon} attribute is provided for compatibility with Ada 83. See | |
10537 | the Ada 83 reference manual for an exact description of the semantics of | |
10538 | this attribute. | |
10539 | ||
10540 | @node Attribute Fast_Math,Attribute Finalization_Size,Attribute Epsilon,Implementation Defined Attributes | |
067d80d8 | 10541 | @anchor{gnat_rm/implementation_defined_attributes attribute-fast-math}@anchor{17f} |
64d5610f ML |
10542 | @section Attribute Fast_Math |
10543 | ||
10544 | ||
10545 | @geindex Fast_Math | |
10546 | ||
10547 | @code{Standard'Fast_Math} (@code{Standard} is the only allowed | |
10548 | prefix) yields a static Boolean value that is True if pragma | |
10549 | @code{Fast_Math} is active, and False otherwise. | |
10550 | ||
10551 | @node Attribute Finalization_Size,Attribute Fixed_Value,Attribute Fast_Math,Implementation Defined Attributes | |
067d80d8 | 10552 | @anchor{gnat_rm/implementation_defined_attributes attribute-finalization-size}@anchor{180} |
64d5610f ML |
10553 | @section Attribute Finalization_Size |
10554 | ||
10555 | ||
10556 | @geindex Finalization_Size | |
10557 | ||
10558 | The prefix of attribute @code{Finalization_Size} must be an object or | |
10559 | a non-class-wide type. This attribute returns the size of any hidden data | |
10560 | reserved by the compiler to handle finalization-related actions. The type of | |
10561 | the attribute is `universal_integer'. | |
10562 | ||
10563 | @code{Finalization_Size} yields a value of zero for a type with no controlled | |
10564 | parts, an object whose type has no controlled parts, or an object of a | |
10565 | class-wide type whose tag denotes a type with no controlled parts. | |
10566 | ||
10567 | Note that only heap-allocated objects contain finalization data. | |
10568 | ||
10569 | @node Attribute Fixed_Value,Attribute From_Any,Attribute Finalization_Size,Implementation Defined Attributes | |
067d80d8 | 10570 | @anchor{gnat_rm/implementation_defined_attributes attribute-fixed-value}@anchor{181} |
64d5610f ML |
10571 | @section Attribute Fixed_Value |
10572 | ||
10573 | ||
10574 | @geindex Fixed_Value | |
10575 | ||
10576 | For every fixed-point type @code{S}, @code{S'Fixed_Value} denotes a | |
10577 | function with the following specification: | |
10578 | ||
10579 | @example | |
10580 | function S'Fixed_Value (Arg : <Universal_Integer>) return S; | |
10581 | @end example | |
10582 | ||
10583 | The value returned is the fixed-point value @code{V} such that: | |
10584 | ||
10585 | @example | |
10586 | V = Arg * S'Small | |
10587 | @end example | |
10588 | ||
10589 | The effect is thus similar to first converting the argument to the | |
10590 | integer type used to represent @code{S}, and then doing an unchecked | |
10591 | conversion to the fixed-point type. The difference is | |
10592 | that there are full range checks, to ensure that the result is in range. | |
10593 | This attribute is primarily intended for use in implementation of the | |
10594 | input-output functions for fixed-point values. | |
10595 | ||
10596 | @node Attribute From_Any,Attribute Has_Access_Values,Attribute Fixed_Value,Implementation Defined Attributes | |
067d80d8 | 10597 | @anchor{gnat_rm/implementation_defined_attributes attribute-from-any}@anchor{182} |
64d5610f ML |
10598 | @section Attribute From_Any |
10599 | ||
10600 | ||
10601 | @geindex From_Any | |
10602 | ||
10603 | This internal attribute is used for the generation of remote subprogram | |
10604 | stubs in the context of the Distributed Systems Annex. | |
10605 | ||
10606 | @node Attribute Has_Access_Values,Attribute Has_Discriminants,Attribute From_Any,Implementation Defined Attributes | |
067d80d8 | 10607 | @anchor{gnat_rm/implementation_defined_attributes attribute-has-access-values}@anchor{183} |
64d5610f ML |
10608 | @section Attribute Has_Access_Values |
10609 | ||
10610 | ||
10611 | @geindex Access values | |
10612 | @geindex testing for | |
10613 | ||
10614 | @geindex Has_Access_Values | |
10615 | ||
10616 | The prefix of the @code{Has_Access_Values} attribute is a type. The result | |
10617 | is a Boolean value which is True if the is an access type, or is a composite | |
10618 | type with a component (at any nesting depth) that is an access type, and is | |
10619 | False otherwise. | |
10620 | The intended use of this attribute is in conjunction with generic | |
10621 | definitions. If the attribute is applied to a generic private type, it | |
10622 | indicates whether or not the corresponding actual type has access values. | |
10623 | ||
10624 | @node Attribute Has_Discriminants,Attribute Has_Tagged_Values,Attribute Has_Access_Values,Implementation Defined Attributes | |
067d80d8 | 10625 | @anchor{gnat_rm/implementation_defined_attributes attribute-has-discriminants}@anchor{184} |
64d5610f ML |
10626 | @section Attribute Has_Discriminants |
10627 | ||
10628 | ||
10629 | @geindex Discriminants | |
10630 | @geindex testing for | |
10631 | ||
10632 | @geindex Has_Discriminants | |
10633 | ||
10634 | The prefix of the @code{Has_Discriminants} attribute is a type. The result | |
10635 | is a Boolean value which is True if the type has discriminants, and False | |
10636 | otherwise. The intended use of this attribute is in conjunction with generic | |
10637 | definitions. If the attribute is applied to a generic private type, it | |
10638 | indicates whether or not the corresponding actual type has discriminants. | |
10639 | ||
10640 | @node Attribute Has_Tagged_Values,Attribute Img,Attribute Has_Discriminants,Implementation Defined Attributes | |
067d80d8 | 10641 | @anchor{gnat_rm/implementation_defined_attributes attribute-has-tagged-values}@anchor{185} |
64d5610f ML |
10642 | @section Attribute Has_Tagged_Values |
10643 | ||
10644 | ||
10645 | @geindex Tagged values | |
10646 | @geindex testing for | |
10647 | ||
10648 | @geindex Has_Tagged_Values | |
10649 | ||
10650 | The prefix of the @code{Has_Tagged_Values} attribute is a type. The result is a | |
10651 | Boolean value which is True if the type is a composite type (array or record) | |
10652 | that is either a tagged type or has a subcomponent that is tagged, and is False | |
10653 | otherwise. The intended use of this attribute is in conjunction with generic | |
10654 | definitions. If the attribute is applied to a generic private type, it | |
10655 | indicates whether or not the corresponding actual type has access values. | |
10656 | ||
10657 | @node Attribute Img,Attribute Initialized,Attribute Has_Tagged_Values,Implementation Defined Attributes | |
067d80d8 | 10658 | @anchor{gnat_rm/implementation_defined_attributes attribute-img}@anchor{186} |
64d5610f ML |
10659 | @section Attribute Img |
10660 | ||
10661 | ||
10662 | @geindex Img | |
10663 | ||
10664 | The @code{Img} attribute differs from @code{Image} in that, while both can be | |
10665 | applied directly to an object, @code{Img} cannot be applied to types. | |
10666 | ||
10667 | Example usage of the attribute: | |
10668 | ||
10669 | @example | |
10670 | Put_Line ("X = " & X'Img); | |
10671 | @end example | |
10672 | ||
10673 | which has the same meaning as the more verbose: | |
10674 | ||
10675 | @example | |
10676 | Put_Line ("X = " & T'Image (X)); | |
10677 | @end example | |
10678 | ||
10679 | where @code{T} is the (sub)type of the object @code{X}. | |
10680 | ||
10681 | Note that technically, in analogy to @code{Image}, | |
10682 | @code{X'Img} returns a parameterless function | |
10683 | that returns the appropriate string when called. This means that | |
10684 | @code{X'Img} can be renamed as a function-returning-string, or used | |
10685 | in an instantiation as a function parameter. | |
10686 | ||
10687 | @node Attribute Initialized,Attribute Integer_Value,Attribute Img,Implementation Defined Attributes | |
067d80d8 | 10688 | @anchor{gnat_rm/implementation_defined_attributes attribute-initialized}@anchor{187} |
64d5610f ML |
10689 | @section Attribute Initialized |
10690 | ||
10691 | ||
10692 | @geindex Initialized | |
10693 | ||
10694 | For the syntax and semantics of this attribute, see the SPARK 2014 Reference | |
10695 | Manual, section 6.10. | |
10696 | ||
10697 | @node Attribute Integer_Value,Attribute Invalid_Value,Attribute Initialized,Implementation Defined Attributes | |
067d80d8 | 10698 | @anchor{gnat_rm/implementation_defined_attributes attribute-integer-value}@anchor{188} |
64d5610f ML |
10699 | @section Attribute Integer_Value |
10700 | ||
10701 | ||
10702 | @geindex Integer_Value | |
10703 | ||
10704 | For every integer type @code{S}, @code{S'Integer_Value} denotes a | |
10705 | function with the following spec: | |
10706 | ||
10707 | @example | |
10708 | function S'Integer_Value (Arg : <Universal_Fixed>) return S; | |
10709 | @end example | |
10710 | ||
10711 | The value returned is the integer value @code{V}, such that: | |
10712 | ||
10713 | @example | |
10714 | Arg = V * T'Small | |
10715 | @end example | |
10716 | ||
10717 | where @code{T} is the type of @code{Arg}. | |
10718 | The effect is thus similar to first doing an unchecked conversion from | |
10719 | the fixed-point type to its corresponding implementation type, and then | |
10720 | converting the result to the target integer type. The difference is | |
10721 | that there are full range checks, to ensure that the result is in range. | |
10722 | This attribute is primarily intended for use in implementation of the | |
10723 | standard input-output functions for fixed-point values. | |
10724 | ||
10725 | @node Attribute Invalid_Value,Attribute Iterable,Attribute Integer_Value,Implementation Defined Attributes | |
067d80d8 | 10726 | @anchor{gnat_rm/implementation_defined_attributes attribute-invalid-value}@anchor{189} |
64d5610f ML |
10727 | @section Attribute Invalid_Value |
10728 | ||
10729 | ||
10730 | @geindex Invalid_Value | |
10731 | ||
10732 | For every scalar type S, S’Invalid_Value returns an undefined value of the | |
10733 | type. If possible this value is an invalid representation for the type. The | |
10734 | value returned is identical to the value used to initialize an otherwise | |
10735 | uninitialized value of the type if pragma Initialize_Scalars is used, | |
10736 | including the ability to modify the value with the binder -Sxx flag and | |
10737 | relevant environment variables at run time. | |
10738 | ||
10739 | @node Attribute Iterable,Attribute Large,Attribute Invalid_Value,Implementation Defined Attributes | |
067d80d8 | 10740 | @anchor{gnat_rm/implementation_defined_attributes attribute-iterable}@anchor{18a} |
64d5610f ML |
10741 | @section Attribute Iterable |
10742 | ||
10743 | ||
10744 | @geindex Iterable | |
10745 | ||
10746 | Equivalent to Aspect Iterable. | |
10747 | ||
10748 | @node Attribute Large,Attribute Library_Level,Attribute Iterable,Implementation Defined Attributes | |
067d80d8 | 10749 | @anchor{gnat_rm/implementation_defined_attributes attribute-large}@anchor{18b} |
64d5610f ML |
10750 | @section Attribute Large |
10751 | ||
10752 | ||
10753 | @geindex Ada 83 attributes | |
10754 | ||
10755 | @geindex Large | |
10756 | ||
10757 | The @code{Large} attribute is provided for compatibility with Ada 83. See | |
10758 | the Ada 83 reference manual for an exact description of the semantics of | |
10759 | this attribute. | |
10760 | ||
10761 | @node Attribute Library_Level,Attribute Loop_Entry,Attribute Large,Implementation Defined Attributes | |
067d80d8 | 10762 | @anchor{gnat_rm/implementation_defined_attributes attribute-library-level}@anchor{18c} |
64d5610f ML |
10763 | @section Attribute Library_Level |
10764 | ||
10765 | ||
10766 | @geindex Library_Level | |
10767 | ||
10768 | @code{P'Library_Level}, where P is an entity name, | |
10769 | returns a Boolean value which is True if the entity is declared | |
10770 | at the library level, and False otherwise. Note that within a | |
10771 | generic instantiation, the name of the generic unit denotes the | |
10772 | instance, which means that this attribute can be used to test | |
10773 | if a generic is instantiated at the library level, as shown | |
10774 | in this example: | |
10775 | ||
10776 | @example | |
10777 | generic | |
10778 | ... | |
10779 | package Gen is | |
10780 | pragma Compile_Time_Error | |
10781 | (not Gen'Library_Level, | |
10782 | "Gen can only be instantiated at library level"); | |
10783 | ... | |
10784 | end Gen; | |
10785 | @end example | |
10786 | ||
10787 | @node Attribute Loop_Entry,Attribute Machine_Size,Attribute Library_Level,Implementation Defined Attributes | |
067d80d8 | 10788 | @anchor{gnat_rm/implementation_defined_attributes attribute-loop-entry}@anchor{18d} |
64d5610f ML |
10789 | @section Attribute Loop_Entry |
10790 | ||
10791 | ||
10792 | @geindex Loop_Entry | |
10793 | ||
10794 | Syntax: | |
10795 | ||
10796 | @example | |
10797 | X'Loop_Entry [(loop_name)] | |
10798 | @end example | |
10799 | ||
10800 | The @code{Loop_Entry} attribute is used to refer to the value that an | |
10801 | expression had upon entry to a given loop in much the same way that the | |
10802 | @code{Old} attribute in a subprogram postcondition can be used to refer | |
10803 | to the value an expression had upon entry to the subprogram. The | |
10804 | relevant loop is either identified by the given loop name, or it is the | |
10805 | innermost enclosing loop when no loop name is given. | |
10806 | ||
10807 | A @code{Loop_Entry} attribute can only occur within an @code{Assert}, | |
10808 | @code{Assert_And_Cut}, @code{Assume}, @code{Loop_Variant} or @code{Loop_Invariant} pragma. | |
10809 | In addition, such a pragma must be one of the items in the sequence | |
10810 | of statements of a loop body, or nested inside block statements that | |
10811 | appear in the sequence of statements of a loop body. | |
10812 | A common use of @code{Loop_Entry} is to compare the current value of objects with | |
10813 | their initial value at loop entry, in a @code{Loop_Invariant} pragma. | |
10814 | ||
10815 | The effect of using @code{X'Loop_Entry} is the same as declaring | |
10816 | a constant initialized with the initial value of @code{X} at loop | |
10817 | entry. This copy is not performed if the loop is not entered, or if the | |
10818 | corresponding pragmas are ignored or disabled. | |
10819 | ||
10820 | @node Attribute Machine_Size,Attribute Mantissa,Attribute Loop_Entry,Implementation Defined Attributes | |
067d80d8 | 10821 | @anchor{gnat_rm/implementation_defined_attributes attribute-machine-size}@anchor{18e} |
64d5610f ML |
10822 | @section Attribute Machine_Size |
10823 | ||
10824 | ||
10825 | @geindex Machine_Size | |
10826 | ||
10827 | This attribute is identical to the @code{Object_Size} attribute. It is | |
10828 | provided for compatibility with the DEC Ada 83 attribute of this name. | |
10829 | ||
10830 | @node Attribute Mantissa,Attribute Maximum_Alignment,Attribute Machine_Size,Implementation Defined Attributes | |
067d80d8 | 10831 | @anchor{gnat_rm/implementation_defined_attributes attribute-mantissa}@anchor{18f} |
64d5610f ML |
10832 | @section Attribute Mantissa |
10833 | ||
10834 | ||
10835 | @geindex Ada 83 attributes | |
10836 | ||
10837 | @geindex Mantissa | |
10838 | ||
10839 | The @code{Mantissa} attribute is provided for compatibility with Ada 83. See | |
10840 | the Ada 83 reference manual for an exact description of the semantics of | |
10841 | this attribute. | |
10842 | ||
10843 | @node Attribute Maximum_Alignment,Attribute Max_Integer_Size,Attribute Mantissa,Implementation Defined Attributes | |
067d80d8 | 10844 | @anchor{gnat_rm/implementation_defined_attributes attribute-maximum-alignment}@anchor{190}@anchor{gnat_rm/implementation_defined_attributes id2}@anchor{191} |
64d5610f ML |
10845 | @section Attribute Maximum_Alignment |
10846 | ||
10847 | ||
10848 | @geindex Alignment | |
10849 | @geindex maximum | |
10850 | ||
10851 | @geindex Maximum_Alignment | |
10852 | ||
10853 | @code{Standard'Maximum_Alignment} (@code{Standard} is the only | |
10854 | allowed prefix) provides the maximum useful alignment value for the | |
10855 | target. This is a static value that can be used to specify the alignment | |
10856 | for an object, guaranteeing that it is properly aligned in all | |
10857 | cases. | |
10858 | ||
10859 | @node Attribute Max_Integer_Size,Attribute Mechanism_Code,Attribute Maximum_Alignment,Implementation Defined Attributes | |
067d80d8 | 10860 | @anchor{gnat_rm/implementation_defined_attributes attribute-max-integer-size}@anchor{192} |
64d5610f ML |
10861 | @section Attribute Max_Integer_Size |
10862 | ||
10863 | ||
10864 | @geindex Max_Integer_Size | |
10865 | ||
10866 | @code{Standard'Max_Integer_Size} (@code{Standard} is the only allowed | |
10867 | prefix) provides the size of the largest supported integer type for | |
10868 | the target. The result is a static constant. | |
10869 | ||
10870 | @node Attribute Mechanism_Code,Attribute Null_Parameter,Attribute Max_Integer_Size,Implementation Defined Attributes | |
067d80d8 | 10871 | @anchor{gnat_rm/implementation_defined_attributes attribute-mechanism-code}@anchor{193} |
64d5610f ML |
10872 | @section Attribute Mechanism_Code |
10873 | ||
10874 | ||
10875 | @geindex Return values | |
10876 | @geindex passing mechanism | |
10877 | ||
10878 | @geindex Parameters | |
10879 | @geindex passing mechanism | |
10880 | ||
10881 | @geindex Mechanism_Code | |
10882 | ||
10883 | @code{func'Mechanism_Code} yields an integer code for the | |
10884 | mechanism used for the result of function @code{func}, and | |
10885 | @code{subprog'Mechanism_Code (n)} yields the mechanism | |
10886 | used for formal parameter number `n' (a static integer value, with 1 | |
10887 | meaning the first parameter) of subprogram @code{subprog}. The code returned is: | |
10888 | ||
10889 | ||
10890 | @table @asis | |
10891 | ||
10892 | @item `1' | |
10893 | ||
10894 | by copy (value) | |
10895 | ||
10896 | @item `2' | |
10897 | ||
10898 | by reference | |
10899 | @end table | |
10900 | ||
10901 | @node Attribute Null_Parameter,Attribute Object_Size,Attribute Mechanism_Code,Implementation Defined Attributes | |
067d80d8 | 10902 | @anchor{gnat_rm/implementation_defined_attributes attribute-null-parameter}@anchor{194} |
64d5610f ML |
10903 | @section Attribute Null_Parameter |
10904 | ||
10905 | ||
10906 | @geindex Zero address | |
10907 | @geindex passing | |
10908 | ||
10909 | @geindex Null_Parameter | |
10910 | ||
10911 | A reference @code{T'Null_Parameter} denotes an imaginary object of | |
10912 | type or subtype @code{T} allocated at machine address zero. The attribute | |
10913 | is allowed only as the default expression of a formal parameter, or as | |
10914 | an actual expression of a subprogram call. In either case, the | |
10915 | subprogram must be imported. | |
10916 | ||
10917 | The identity of the object is represented by the address zero in the | |
10918 | argument list, independent of the passing mechanism (explicit or | |
10919 | default). | |
10920 | ||
10921 | This capability is needed to specify that a zero address should be | |
10922 | passed for a record or other composite object passed by reference. | |
10923 | There is no way of indicating this without the @code{Null_Parameter} | |
10924 | attribute. | |
10925 | ||
10926 | @node Attribute Object_Size,Attribute Old,Attribute Null_Parameter,Implementation Defined Attributes | |
067d80d8 | 10927 | @anchor{gnat_rm/implementation_defined_attributes attribute-object-size}@anchor{145}@anchor{gnat_rm/implementation_defined_attributes id3}@anchor{195} |
64d5610f ML |
10928 | @section Attribute Object_Size |
10929 | ||
10930 | ||
10931 | @geindex Size | |
10932 | @geindex used for objects | |
10933 | ||
10934 | @geindex Object_Size | |
10935 | ||
10936 | The size of an object is not necessarily the same as the size of the type | |
10937 | of an object. This is because by default object sizes are increased to be | |
10938 | a multiple of the alignment of the object. For example, | |
10939 | @code{Natural'Size} is | |
10940 | 31, but by default objects of type @code{Natural} will have a size of 32 bits. | |
10941 | Similarly, a record containing an integer and a character: | |
10942 | ||
10943 | @example | |
10944 | type Rec is record | |
10945 | I : Integer; | |
10946 | C : Character; | |
10947 | end record; | |
10948 | @end example | |
10949 | ||
10950 | will have a size of 40 (that is @code{Rec'Size} will be 40). The | |
10951 | alignment will be 4, because of the | |
10952 | integer field, and so the default size of record objects for this type | |
10953 | will be 64 (8 bytes). | |
10954 | ||
10955 | If the alignment of the above record is specified to be 1, then the | |
10956 | object size will be 40 (5 bytes). This is true by default, and also | |
10957 | an object size of 40 can be explicitly specified in this case. | |
10958 | ||
10959 | A consequence of this capability is that different object sizes can be | |
10960 | given to subtypes that would otherwise be considered in Ada to be | |
10961 | statically matching. But it makes no sense to consider such subtypes | |
10962 | as statically matching. Consequently, GNAT adds a rule | |
10963 | to the static matching rules that requires object sizes to match. | |
10964 | Consider this example: | |
10965 | ||
10966 | @example | |
10967 | 1. procedure BadAVConvert is | |
10968 | 2. type R is new Integer; | |
10969 | 3. subtype R1 is R range 1 .. 10; | |
10970 | 4. subtype R2 is R range 1 .. 10; | |
10971 | 5. for R1'Object_Size use 8; | |
10972 | 6. for R2'Object_Size use 16; | |
10973 | 7. type R1P is access all R1; | |
10974 | 8. type R2P is access all R2; | |
10975 | 9. R1PV : R1P := new R1'(4); | |
10976 | 10. R2PV : R2P; | |
10977 | 11. begin | |
10978 | 12. R2PV := R2P (R1PV); | |
10979 | | | |
10980 | >>> target designated subtype not compatible with | |
10981 | type "R1" defined at line 3 | |
10982 | ||
10983 | 13. end; | |
10984 | @end example | |
10985 | ||
10986 | In the absence of lines 5 and 6, | |
10987 | types @code{R1} and @code{R2} statically match and | |
10988 | hence the conversion on line 12 is legal. But since lines 5 and 6 | |
10989 | cause the object sizes to differ, GNAT considers that types | |
10990 | @code{R1} and @code{R2} are not statically matching, and line 12 | |
10991 | generates the diagnostic shown above. | |
10992 | ||
10993 | Similar additional checks are performed in other contexts requiring | |
10994 | statically matching subtypes. | |
10995 | ||
10996 | @node Attribute Old,Attribute Passed_By_Reference,Attribute Object_Size,Implementation Defined Attributes | |
067d80d8 | 10997 | @anchor{gnat_rm/implementation_defined_attributes attribute-old}@anchor{196} |
64d5610f ML |
10998 | @section Attribute Old |
10999 | ||
11000 | ||
11001 | @geindex Old | |
11002 | ||
11003 | In addition to the usage of @code{Old} defined in the Ada 2012 RM (usage | |
11004 | within @code{Post} aspect), GNAT also permits the use of this attribute | |
11005 | in implementation defined pragmas @code{Postcondition}, | |
11006 | @code{Contract_Cases} and @code{Test_Case}. Also usages of | |
11007 | @code{Old} which would be illegal according to the Ada 2012 RM | |
11008 | definition are allowed under control of | |
11009 | implementation defined pragma @code{Unevaluated_Use_Of_Old}. | |
11010 | ||
11011 | @node Attribute Passed_By_Reference,Attribute Pool_Address,Attribute Old,Implementation Defined Attributes | |
067d80d8 | 11012 | @anchor{gnat_rm/implementation_defined_attributes attribute-passed-by-reference}@anchor{197} |
64d5610f ML |
11013 | @section Attribute Passed_By_Reference |
11014 | ||
11015 | ||
11016 | @geindex Parameters | |
11017 | @geindex when passed by reference | |
11018 | ||
11019 | @geindex Passed_By_Reference | |
11020 | ||
11021 | @code{typ'Passed_By_Reference} for any subtype @cite{typ} returns | |
11022 | a value of type @code{Boolean} value that is @code{True} if the type is | |
11023 | normally passed by reference and @code{False} if the type is normally | |
11024 | passed by copy in calls. For scalar types, the result is always @code{False} | |
11025 | and is static. For non-scalar types, the result is nonstatic. | |
11026 | ||
11027 | @node Attribute Pool_Address,Attribute Range_Length,Attribute Passed_By_Reference,Implementation Defined Attributes | |
067d80d8 | 11028 | @anchor{gnat_rm/implementation_defined_attributes attribute-pool-address}@anchor{198} |
64d5610f ML |
11029 | @section Attribute Pool_Address |
11030 | ||
11031 | ||
11032 | @geindex Pool_Address | |
11033 | ||
11034 | @code{X'Pool_Address} for any object @code{X} returns the address | |
11035 | of X within its storage pool. This is the same as | |
11036 | @code{X'Address}, except that for an unconstrained array whose | |
11037 | bounds are allocated just before the first component, | |
11038 | @code{X'Pool_Address} returns the address of those bounds, | |
11039 | whereas @code{X'Address} returns the address of the first | |
11040 | component. | |
11041 | ||
11042 | Here, we are interpreting ‘storage pool’ broadly to mean | |
11043 | @code{wherever the object is allocated}, which could be a | |
11044 | user-defined storage pool, | |
11045 | the global heap, on the stack, or in a static memory area. | |
11046 | For an object created by @code{new}, @code{Ptr.all'Pool_Address} is | |
11047 | what is passed to @code{Allocate} and returned from @code{Deallocate}. | |
11048 | ||
11049 | @node Attribute Range_Length,Attribute Restriction_Set,Attribute Pool_Address,Implementation Defined Attributes | |
067d80d8 | 11050 | @anchor{gnat_rm/implementation_defined_attributes attribute-range-length}@anchor{199} |
64d5610f ML |
11051 | @section Attribute Range_Length |
11052 | ||
11053 | ||
11054 | @geindex Range_Length | |
11055 | ||
11056 | @code{typ'Range_Length} for any discrete type @cite{typ} yields | |
11057 | the number of values represented by the subtype (zero for a null | |
11058 | range). The result is static for static subtypes. @code{Range_Length} | |
11059 | applied to the index subtype of a one dimensional array always gives the | |
11060 | same result as @code{Length} applied to the array itself. | |
11061 | ||
11062 | @node Attribute Restriction_Set,Attribute Result,Attribute Range_Length,Implementation Defined Attributes | |
067d80d8 | 11063 | @anchor{gnat_rm/implementation_defined_attributes attribute-restriction-set}@anchor{19a} |
64d5610f ML |
11064 | @section Attribute Restriction_Set |
11065 | ||
11066 | ||
11067 | @geindex Restriction_Set | |
11068 | ||
11069 | @geindex Restrictions | |
11070 | ||
11071 | This attribute allows compile time testing of restrictions that | |
11072 | are currently in effect. It is primarily intended for specializing | |
11073 | code in the run-time based on restrictions that are active (e.g. | |
11074 | don’t need to save fpt registers if restriction No_Floating_Point | |
11075 | is known to be in effect), but can be used anywhere. | |
11076 | ||
11077 | There are two forms: | |
11078 | ||
11079 | @example | |
11080 | System'Restriction_Set (partition_boolean_restriction_NAME) | |
11081 | System'Restriction_Set (No_Dependence => library_unit_NAME); | |
11082 | @end example | |
11083 | ||
11084 | In the case of the first form, the only restriction names | |
11085 | allowed are parameterless restrictions that are checked | |
11086 | for consistency at bind time. For a complete list see the | |
11087 | subtype @code{System.Rident.Partition_Boolean_Restrictions}. | |
11088 | ||
11089 | The result returned is True if the restriction is known to | |
11090 | be in effect, and False if the restriction is known not to | |
11091 | be in effect. An important guarantee is that the value of | |
11092 | a Restriction_Set attribute is known to be consistent throughout | |
11093 | all the code of a partition. | |
11094 | ||
11095 | This is trivially achieved if the entire partition is compiled | |
11096 | with a consistent set of restriction pragmas. However, the | |
11097 | compilation model does not require this. It is possible to | |
11098 | compile one set of units with one set of pragmas, and another | |
11099 | set of units with another set of pragmas. It is even possible | |
11100 | to compile a spec with one set of pragmas, and then WITH the | |
11101 | same spec with a different set of pragmas. Inconsistencies | |
11102 | in the actual use of the restriction are checked at bind time. | |
11103 | ||
11104 | In order to achieve the guarantee of consistency for the | |
11105 | Restriction_Set pragma, we consider that a use of the pragma | |
11106 | that yields False is equivalent to a violation of the | |
11107 | restriction. | |
11108 | ||
11109 | So for example if you write | |
11110 | ||
11111 | @example | |
11112 | if System'Restriction_Set (No_Floating_Point) then | |
11113 | ... | |
11114 | else | |
11115 | ... | |
11116 | end if; | |
11117 | @end example | |
11118 | ||
11119 | And the result is False, so that the else branch is executed, | |
11120 | you can assume that this restriction is not set for any unit | |
11121 | in the partition. This is checked by considering this use of | |
11122 | the restriction pragma to be a violation of the restriction | |
11123 | No_Floating_Point. This means that no other unit can attempt | |
11124 | to set this restriction (if some unit does attempt to set it, | |
11125 | the binder will refuse to bind the partition). | |
11126 | ||
11127 | Technical note: The restriction name and the unit name are | |
11128 | intepreted entirely syntactically, as in the corresponding | |
11129 | Restrictions pragma, they are not analyzed semantically, | |
11130 | so they do not have a type. | |
11131 | ||
11132 | @node Attribute Result,Attribute Safe_Emax,Attribute Restriction_Set,Implementation Defined Attributes | |
067d80d8 | 11133 | @anchor{gnat_rm/implementation_defined_attributes attribute-result}@anchor{19b} |
64d5610f ML |
11134 | @section Attribute Result |
11135 | ||
11136 | ||
11137 | @geindex Result | |
11138 | ||
11139 | @code{function'Result} can only be used with in a Postcondition pragma | |
11140 | for a function. The prefix must be the name of the corresponding function. This | |
11141 | is used to refer to the result of the function in the postcondition expression. | |
11142 | For a further discussion of the use of this attribute and examples of its use, | |
11143 | see the description of pragma Postcondition. | |
11144 | ||
11145 | @node Attribute Safe_Emax,Attribute Safe_Large,Attribute Result,Implementation Defined Attributes | |
067d80d8 | 11146 | @anchor{gnat_rm/implementation_defined_attributes attribute-safe-emax}@anchor{19c} |
64d5610f ML |
11147 | @section Attribute Safe_Emax |
11148 | ||
11149 | ||
11150 | @geindex Ada 83 attributes | |
11151 | ||
11152 | @geindex Safe_Emax | |
11153 | ||
11154 | The @code{Safe_Emax} attribute is provided for compatibility with Ada 83. See | |
11155 | the Ada 83 reference manual for an exact description of the semantics of | |
11156 | this attribute. | |
11157 | ||
11158 | @node Attribute Safe_Large,Attribute Safe_Small,Attribute Safe_Emax,Implementation Defined Attributes | |
067d80d8 | 11159 | @anchor{gnat_rm/implementation_defined_attributes attribute-safe-large}@anchor{19d} |
64d5610f ML |
11160 | @section Attribute Safe_Large |
11161 | ||
11162 | ||
11163 | @geindex Ada 83 attributes | |
11164 | ||
11165 | @geindex Safe_Large | |
11166 | ||
11167 | The @code{Safe_Large} attribute is provided for compatibility with Ada 83. See | |
11168 | the Ada 83 reference manual for an exact description of the semantics of | |
11169 | this attribute. | |
11170 | ||
11171 | @node Attribute Safe_Small,Attribute Scalar_Storage_Order,Attribute Safe_Large,Implementation Defined Attributes | |
067d80d8 | 11172 | @anchor{gnat_rm/implementation_defined_attributes attribute-safe-small}@anchor{19e} |
64d5610f ML |
11173 | @section Attribute Safe_Small |
11174 | ||
11175 | ||
11176 | @geindex Ada 83 attributes | |
11177 | ||
11178 | @geindex Safe_Small | |
11179 | ||
11180 | The @code{Safe_Small} attribute is provided for compatibility with Ada 83. See | |
11181 | the Ada 83 reference manual for an exact description of the semantics of | |
11182 | this attribute. | |
11183 | ||
11184 | @node Attribute Scalar_Storage_Order,Attribute Simple_Storage_Pool,Attribute Safe_Small,Implementation Defined Attributes | |
067d80d8 | 11185 | @anchor{gnat_rm/implementation_defined_attributes attribute-scalar-storage-order}@anchor{153}@anchor{gnat_rm/implementation_defined_attributes id4}@anchor{19f} |
64d5610f ML |
11186 | @section Attribute Scalar_Storage_Order |
11187 | ||
11188 | ||
11189 | @geindex Endianness | |
11190 | ||
11191 | @geindex Scalar storage order | |
11192 | ||
11193 | @geindex Scalar_Storage_Order | |
11194 | ||
11195 | For every array or record type @code{S}, the representation attribute | |
11196 | @code{Scalar_Storage_Order} denotes the order in which storage elements | |
11197 | that make up scalar components are ordered within S. The value given must | |
11198 | be a static expression of type System.Bit_Order. The following is an example | |
11199 | of the use of this feature: | |
11200 | ||
11201 | @example | |
11202 | -- Component type definitions | |
11203 | ||
11204 | subtype Yr_Type is Natural range 0 .. 127; | |
11205 | subtype Mo_Type is Natural range 1 .. 12; | |
11206 | subtype Da_Type is Natural range 1 .. 31; | |
11207 | ||
11208 | -- Record declaration | |
11209 | ||
11210 | type Date is record | |
11211 | Years_Since_1980 : Yr_Type; | |
11212 | Month : Mo_Type; | |
11213 | Day_Of_Month : Da_Type; | |
11214 | end record; | |
11215 | ||
11216 | -- Record representation clause | |
11217 | ||
11218 | for Date use record | |
11219 | Years_Since_1980 at 0 range 0 .. 6; | |
11220 | Month at 0 range 7 .. 10; | |
11221 | Day_Of_Month at 0 range 11 .. 15; | |
11222 | end record; | |
11223 | ||
11224 | -- Attribute definition clauses | |
11225 | ||
11226 | for Date'Bit_Order use System.High_Order_First; | |
11227 | for Date'Scalar_Storage_Order use System.High_Order_First; | |
11228 | -- If Scalar_Storage_Order is specified, it must be consistent with | |
11229 | -- Bit_Order, so it's best to always define the latter explicitly if | |
11230 | -- the former is used. | |
11231 | @end example | |
11232 | ||
11233 | Other properties are as for the standard representation attribute @code{Bit_Order} | |
11234 | defined by Ada RM 13.5.3(4). The default is @code{System.Default_Bit_Order}. | |
11235 | ||
11236 | For a record type @code{T}, if @code{T'Scalar_Storage_Order} is | |
11237 | specified explicitly, it shall be equal to @code{T'Bit_Order}. Note: | |
11238 | this means that if a @code{Scalar_Storage_Order} attribute definition | |
11239 | clause is not confirming, then the type’s @code{Bit_Order} shall be | |
11240 | specified explicitly and set to the same value. | |
11241 | ||
11242 | Derived types inherit an explicitly set scalar storage order from their parent | |
11243 | types. This may be overridden for the derived type by giving an explicit scalar | |
11244 | storage order for it. However, for a record extension, the derived type must | |
11245 | have the same scalar storage order as the parent type. | |
11246 | ||
11247 | A component of a record type that is itself a record or an array and that does | |
11248 | not start and end on a byte boundary must have have the same scalar storage | |
11249 | order as the record type. A component of a bit-packed array type that is itself | |
11250 | a record or an array must have the same scalar storage order as the array type. | |
11251 | ||
11252 | No component of a type that has an explicit @code{Scalar_Storage_Order} | |
11253 | attribute definition may be aliased. | |
11254 | ||
11255 | A confirming @code{Scalar_Storage_Order} attribute definition clause (i.e. | |
11256 | with a value equal to @code{System.Default_Bit_Order}) has no effect. | |
11257 | ||
11258 | If the opposite storage order is specified, then whenever the value of | |
11259 | a scalar component of an object of type @code{S} is read, the storage | |
11260 | elements of the enclosing machine scalar are first reversed (before | |
11261 | retrieving the component value, possibly applying some shift and mask | |
11262 | operatings on the enclosing machine scalar), and the opposite operation | |
11263 | is done for writes. | |
11264 | ||
11265 | In that case, the restrictions set forth in 13.5.1(10.3/2) for scalar components | |
11266 | are relaxed. Instead, the following rules apply: | |
11267 | ||
11268 | ||
11269 | @itemize * | |
11270 | ||
11271 | @item | |
11272 | the underlying storage elements are those at positions | |
11273 | @code{(position + first_bit / storage_element_size) .. (position + (last_bit + storage_element_size - 1) / storage_element_size)} | |
11274 | ||
11275 | @item | |
11276 | the sequence of underlying storage elements shall have | |
11277 | a size no greater than the largest machine scalar | |
11278 | ||
11279 | @item | |
11280 | the enclosing machine scalar is defined as the smallest machine | |
11281 | scalar starting at a position no greater than | |
11282 | @code{position + first_bit / storage_element_size} and covering | |
11283 | storage elements at least up to @code{position + (last_bit + storage_element_size - 1) / storage_element_size} | |
11284 | ||
11285 | @item | |
11286 | the position of the component is interpreted relative to that machine | |
11287 | scalar. | |
11288 | @end itemize | |
11289 | ||
11290 | If no scalar storage order is specified for a type (either directly, or by | |
11291 | inheritance in the case of a derived type), then the default is normally | |
11292 | the native ordering of the target, but this default can be overridden using | |
11293 | pragma @code{Default_Scalar_Storage_Order}. | |
11294 | ||
11295 | If a component of @code{T} is itself of a record or array type, the specfied | |
11296 | @code{Scalar_Storage_Order} does `not' apply to that nested type: an explicit | |
11297 | attribute definition clause must be provided for the component type as well | |
11298 | if desired. | |
11299 | ||
11300 | Representation changes that explicitly or implicitly toggle the scalar storage | |
11301 | order are not supported and may result in erroneous execution of the program, | |
11302 | except when performed by means of an instance of @code{Ada.Unchecked_Conversion}. | |
11303 | ||
11304 | In particular, overlays are not supported and a warning is given for them: | |
11305 | ||
11306 | @example | |
11307 | type Rec_LE is record | |
11308 | I : Integer; | |
11309 | end record; | |
11310 | ||
11311 | for Rec_LE use record | |
11312 | I at 0 range 0 .. 31; | |
11313 | end record; | |
11314 | ||
11315 | for Rec_LE'Bit_Order use System.Low_Order_First; | |
11316 | for Rec_LE'Scalar_Storage_Order use System.Low_Order_First; | |
11317 | ||
11318 | type Rec_BE is record | |
11319 | I : Integer; | |
11320 | end record; | |
11321 | ||
11322 | for Rec_BE use record | |
11323 | I at 0 range 0 .. 31; | |
11324 | end record; | |
11325 | ||
11326 | for Rec_BE'Bit_Order use System.High_Order_First; | |
11327 | for Rec_BE'Scalar_Storage_Order use System.High_Order_First; | |
11328 | ||
11329 | R_LE : Rec_LE; | |
11330 | ||
11331 | R_BE : Rec_BE; | |
11332 | for R_BE'Address use R_LE'Address; | |
11333 | @end example | |
11334 | ||
11335 | @code{warning: overlay changes scalar storage order [enabled by default]} | |
11336 | ||
11337 | In most cases, such representation changes ought to be replaced by an | |
11338 | instantiation of a function or procedure provided by @code{GNAT.Byte_Swapping}. | |
11339 | ||
11340 | Note that the scalar storage order only affects the in-memory data | |
11341 | representation. It has no effect on the representation used by stream | |
11342 | attributes. | |
11343 | ||
11344 | Note that debuggers may be unable to display the correct value of scalar | |
11345 | components of a type for which the opposite storage order is specified. | |
11346 | ||
11347 | @node Attribute Simple_Storage_Pool,Attribute Small,Attribute Scalar_Storage_Order,Implementation Defined Attributes | |
067d80d8 | 11348 | @anchor{gnat_rm/implementation_defined_attributes attribute-simple-storage-pool}@anchor{e7}@anchor{gnat_rm/implementation_defined_attributes id5}@anchor{1a0} |
64d5610f ML |
11349 | @section Attribute Simple_Storage_Pool |
11350 | ||
11351 | ||
11352 | @geindex Storage pool | |
11353 | @geindex simple | |
11354 | ||
11355 | @geindex Simple storage pool | |
11356 | ||
11357 | @geindex Simple_Storage_Pool | |
11358 | ||
11359 | For every nonformal, nonderived access-to-object type @code{Acc}, the | |
11360 | representation attribute @code{Simple_Storage_Pool} may be specified | |
11361 | via an attribute_definition_clause (or by specifying the equivalent aspect): | |
11362 | ||
11363 | @example | |
11364 | My_Pool : My_Simple_Storage_Pool_Type; | |
11365 | ||
11366 | type Acc is access My_Data_Type; | |
11367 | ||
11368 | for Acc'Simple_Storage_Pool use My_Pool; | |
11369 | @end example | |
11370 | ||
11371 | The name given in an attribute_definition_clause for the | |
11372 | @code{Simple_Storage_Pool} attribute shall denote a variable of | |
11373 | a ‘simple storage pool type’ (see pragma @cite{Simple_Storage_Pool_Type}). | |
11374 | ||
11375 | The use of this attribute is only allowed for a prefix denoting a type | |
11376 | for which it has been specified. The type of the attribute is the type | |
11377 | of the variable specified as the simple storage pool of the access type, | |
11378 | and the attribute denotes that variable. | |
11379 | ||
11380 | It is illegal to specify both @code{Storage_Pool} and @code{Simple_Storage_Pool} | |
11381 | for the same access type. | |
11382 | ||
11383 | If the @code{Simple_Storage_Pool} attribute has been specified for an access | |
11384 | type, then applying the @code{Storage_Pool} attribute to the type is flagged | |
11385 | with a warning and its evaluation raises the exception @code{Program_Error}. | |
11386 | ||
11387 | If the Simple_Storage_Pool attribute has been specified for an access | |
11388 | type @code{S}, then the evaluation of the attribute @code{S'Storage_Size} | |
11389 | returns the result of calling @code{Storage_Size (S'Simple_Storage_Pool)}, | |
11390 | which is intended to indicate the number of storage elements reserved for | |
11391 | the simple storage pool. If the Storage_Size function has not been defined | |
11392 | for the simple storage pool type, then this attribute returns zero. | |
11393 | ||
11394 | If an access type @code{S} has a specified simple storage pool of type | |
11395 | @code{SSP}, then the evaluation of an allocator for that access type calls | |
11396 | the primitive @code{Allocate} procedure for type @code{SSP}, passing | |
11397 | @code{S'Simple_Storage_Pool} as the pool parameter. The detailed | |
11398 | semantics of such allocators is the same as those defined for allocators | |
11399 | in section 13.11 of the @cite{Ada Reference Manual}, with the term | |
11400 | `simple storage pool' substituted for `storage pool'. | |
11401 | ||
11402 | If an access type @code{S} has a specified simple storage pool of type | |
11403 | @code{SSP}, then a call to an instance of the @code{Ada.Unchecked_Deallocation} | |
11404 | for that access type invokes the primitive @code{Deallocate} procedure | |
11405 | for type @code{SSP}, passing @code{S'Simple_Storage_Pool} as the pool | |
11406 | parameter. The detailed semantics of such unchecked deallocations is the same | |
11407 | as defined in section 13.11.2 of the Ada Reference Manual, except that the | |
11408 | term `simple storage pool' is substituted for `storage pool'. | |
11409 | ||
11410 | @node Attribute Small,Attribute Small_Denominator,Attribute Simple_Storage_Pool,Implementation Defined Attributes | |
067d80d8 | 11411 | @anchor{gnat_rm/implementation_defined_attributes attribute-small}@anchor{1a1} |
64d5610f ML |
11412 | @section Attribute Small |
11413 | ||
11414 | ||
11415 | @geindex Ada 83 attributes | |
11416 | ||
11417 | @geindex Small | |
11418 | ||
11419 | The @code{Small} attribute is defined in Ada 95 (and Ada 2005) only for | |
11420 | fixed-point types. | |
11421 | GNAT also allows this attribute to be applied to floating-point types | |
11422 | for compatibility with Ada 83. See | |
11423 | the Ada 83 reference manual for an exact description of the semantics of | |
11424 | this attribute when applied to floating-point types. | |
11425 | ||
11426 | @node Attribute Small_Denominator,Attribute Small_Numerator,Attribute Small,Implementation Defined Attributes | |
067d80d8 | 11427 | @anchor{gnat_rm/implementation_defined_attributes attribute-small-denominator}@anchor{1a2} |
64d5610f ML |
11428 | @section Attribute Small_Denominator |
11429 | ||
11430 | ||
11431 | @geindex Small | |
11432 | ||
11433 | @geindex Small_Denominator | |
11434 | ||
11435 | @code{typ'Small_Denominator} for any fixed-point subtype @cite{typ} yields the | |
11436 | denominator in the representation of @code{typ'Small} as a rational number | |
11437 | with coprime factors (i.e. as an irreducible fraction). | |
11438 | ||
11439 | @node Attribute Small_Numerator,Attribute Storage_Unit,Attribute Small_Denominator,Implementation Defined Attributes | |
067d80d8 | 11440 | @anchor{gnat_rm/implementation_defined_attributes attribute-small-numerator}@anchor{1a3} |
64d5610f ML |
11441 | @section Attribute Small_Numerator |
11442 | ||
11443 | ||
11444 | @geindex Small | |
11445 | ||
11446 | @geindex Small_Numerator | |
11447 | ||
11448 | @code{typ'Small_Numerator} for any fixed-point subtype @cite{typ} yields the | |
11449 | numerator in the representation of @code{typ'Small} as a rational number | |
11450 | with coprime factors (i.e. as an irreducible fraction). | |
11451 | ||
11452 | @node Attribute Storage_Unit,Attribute Stub_Type,Attribute Small_Numerator,Implementation Defined Attributes | |
067d80d8 | 11453 | @anchor{gnat_rm/implementation_defined_attributes attribute-storage-unit}@anchor{1a4} |
64d5610f ML |
11454 | @section Attribute Storage_Unit |
11455 | ||
11456 | ||
11457 | @geindex Storage_Unit | |
11458 | ||
11459 | @code{Standard'Storage_Unit} (@code{Standard} is the only allowed | |
11460 | prefix) provides the same value as @code{System.Storage_Unit}. | |
11461 | ||
11462 | @node Attribute Stub_Type,Attribute System_Allocator_Alignment,Attribute Storage_Unit,Implementation Defined Attributes | |
067d80d8 | 11463 | @anchor{gnat_rm/implementation_defined_attributes attribute-stub-type}@anchor{1a5} |
64d5610f ML |
11464 | @section Attribute Stub_Type |
11465 | ||
11466 | ||
11467 | @geindex Stub_Type | |
11468 | ||
11469 | The GNAT implementation of remote access-to-classwide types is | |
11470 | organized as described in AARM section E.4 (20.t): a value of an RACW type | |
11471 | (designating a remote object) is represented as a normal access | |
11472 | value, pointing to a “stub” object which in turn contains the | |
11473 | necessary information to contact the designated remote object. A | |
11474 | call on any dispatching operation of such a stub object does the | |
11475 | remote call, if necessary, using the information in the stub object | |
11476 | to locate the target partition, etc. | |
11477 | ||
11478 | For a prefix @code{T} that denotes a remote access-to-classwide type, | |
11479 | @code{T'Stub_Type} denotes the type of the corresponding stub objects. | |
11480 | ||
11481 | By construction, the layout of @code{T'Stub_Type} is identical to that of | |
11482 | type @code{RACW_Stub_Type} declared in the internal implementation-defined | |
11483 | unit @code{System.Partition_Interface}. Use of this attribute will create | |
11484 | an implicit dependency on this unit. | |
11485 | ||
11486 | @node Attribute System_Allocator_Alignment,Attribute Target_Name,Attribute Stub_Type,Implementation Defined Attributes | |
067d80d8 | 11487 | @anchor{gnat_rm/implementation_defined_attributes attribute-system-allocator-alignment}@anchor{1a6} |
64d5610f ML |
11488 | @section Attribute System_Allocator_Alignment |
11489 | ||
11490 | ||
11491 | @geindex Alignment | |
11492 | @geindex allocator | |
11493 | ||
11494 | @geindex System_Allocator_Alignment | |
11495 | ||
11496 | @code{Standard'System_Allocator_Alignment} (@code{Standard} is the only | |
11497 | allowed prefix) provides the observable guaranteed to be honored by | |
11498 | the system allocator (malloc). This is a static value that can be used | |
11499 | in user storage pools based on malloc either to reject allocation | |
11500 | with alignment too large or to enable a realignment circuitry if the | |
11501 | alignment request is larger than this value. | |
11502 | ||
11503 | @node Attribute Target_Name,Attribute To_Address,Attribute System_Allocator_Alignment,Implementation Defined Attributes | |
067d80d8 | 11504 | @anchor{gnat_rm/implementation_defined_attributes attribute-target-name}@anchor{1a7} |
64d5610f ML |
11505 | @section Attribute Target_Name |
11506 | ||
11507 | ||
11508 | @geindex Target_Name | |
11509 | ||
11510 | @code{Standard'Target_Name} (@code{Standard} is the only allowed | |
11511 | prefix) provides a static string value that identifies the target | |
11512 | for the current compilation. For GCC implementations, this is the | |
11513 | standard gcc target name without the terminating slash (for | |
11514 | example, GNAT 5.0 on windows yields “i586-pc-mingw32msv”). | |
11515 | ||
11516 | @node Attribute To_Address,Attribute To_Any,Attribute Target_Name,Implementation Defined Attributes | |
067d80d8 | 11517 | @anchor{gnat_rm/implementation_defined_attributes attribute-to-address}@anchor{1a8} |
64d5610f ML |
11518 | @section Attribute To_Address |
11519 | ||
11520 | ||
11521 | @geindex To_Address | |
11522 | ||
11523 | The @code{System'To_Address} | |
11524 | (@code{System} is the only allowed prefix) | |
11525 | denotes a function identical to | |
11526 | @code{System.Storage_Elements.To_Address} except that | |
11527 | it is a static attribute. This means that if its argument is | |
11528 | a static expression, then the result of the attribute is a | |
11529 | static expression. This means that such an expression can be | |
11530 | used in contexts (e.g., preelaborable packages) which require a | |
11531 | static expression and where the function call could not be used | |
11532 | (since the function call is always nonstatic, even if its | |
11533 | argument is static). The argument must be in the range | |
11534 | -(2**(m-1)) .. 2**m-1, where m is the memory size | |
11535 | (typically 32 or 64). Negative values are intepreted in a | |
11536 | modular manner (e.g., -1 means the same as 16#FFFF_FFFF# on | |
11537 | a 32 bits machine). | |
11538 | ||
11539 | @node Attribute To_Any,Attribute Type_Class,Attribute To_Address,Implementation Defined Attributes | |
067d80d8 | 11540 | @anchor{gnat_rm/implementation_defined_attributes attribute-to-any}@anchor{1a9} |
64d5610f ML |
11541 | @section Attribute To_Any |
11542 | ||
11543 | ||
11544 | @geindex To_Any | |
11545 | ||
11546 | This internal attribute is used for the generation of remote subprogram | |
11547 | stubs in the context of the Distributed Systems Annex. | |
11548 | ||
11549 | @node Attribute Type_Class,Attribute Type_Key,Attribute To_Any,Implementation Defined Attributes | |
067d80d8 | 11550 | @anchor{gnat_rm/implementation_defined_attributes attribute-type-class}@anchor{1aa} |
64d5610f ML |
11551 | @section Attribute Type_Class |
11552 | ||
11553 | ||
11554 | @geindex Type_Class | |
11555 | ||
11556 | @code{typ'Type_Class} for any type or subtype @cite{typ} yields | |
11557 | the value of the type class for the full type of @cite{typ}. If | |
11558 | @cite{typ} is a generic formal type, the value is the value for the | |
11559 | corresponding actual subtype. The value of this attribute is of type | |
11560 | @code{System.Aux_DEC.Type_Class}, which has the following definition: | |
11561 | ||
11562 | @example | |
11563 | type Type_Class is | |
11564 | (Type_Class_Enumeration, | |
11565 | Type_Class_Integer, | |
11566 | Type_Class_Fixed_Point, | |
11567 | Type_Class_Floating_Point, | |
11568 | Type_Class_Array, | |
11569 | Type_Class_Record, | |
11570 | Type_Class_Access, | |
11571 | Type_Class_Task, | |
11572 | Type_Class_Address); | |
11573 | @end example | |
11574 | ||
11575 | Protected types yield the value @code{Type_Class_Task}, which thus | |
11576 | applies to all concurrent types. This attribute is designed to | |
11577 | be compatible with the DEC Ada 83 attribute of the same name. | |
11578 | ||
11579 | @node Attribute Type_Key,Attribute TypeCode,Attribute Type_Class,Implementation Defined Attributes | |
067d80d8 | 11580 | @anchor{gnat_rm/implementation_defined_attributes attribute-type-key}@anchor{1ab} |
64d5610f ML |
11581 | @section Attribute Type_Key |
11582 | ||
11583 | ||
11584 | @geindex Type_Key | |
11585 | ||
11586 | The @code{Type_Key} attribute is applicable to a type or subtype and | |
11587 | yields a value of type Standard.String containing encoded information | |
11588 | about the type or subtype. This provides improved compatibility with | |
11589 | other implementations that support this attribute. | |
11590 | ||
11591 | @node Attribute TypeCode,Attribute Unconstrained_Array,Attribute Type_Key,Implementation Defined Attributes | |
067d80d8 | 11592 | @anchor{gnat_rm/implementation_defined_attributes attribute-typecode}@anchor{1ac} |
64d5610f ML |
11593 | @section Attribute TypeCode |
11594 | ||
11595 | ||
11596 | @geindex TypeCode | |
11597 | ||
11598 | This internal attribute is used for the generation of remote subprogram | |
11599 | stubs in the context of the Distributed Systems Annex. | |
11600 | ||
11601 | @node Attribute Unconstrained_Array,Attribute Universal_Literal_String,Attribute TypeCode,Implementation Defined Attributes | |
067d80d8 | 11602 | @anchor{gnat_rm/implementation_defined_attributes attribute-unconstrained-array}@anchor{1ad} |
64d5610f ML |
11603 | @section Attribute Unconstrained_Array |
11604 | ||
11605 | ||
11606 | @geindex Unconstrained_Array | |
11607 | ||
11608 | The @code{Unconstrained_Array} attribute can be used with a prefix that | |
11609 | denotes any type or subtype. It is a static attribute that yields | |
11610 | @code{True} if the prefix designates an unconstrained array, | |
11611 | and @code{False} otherwise. In a generic instance, the result is | |
11612 | still static, and yields the result of applying this test to the | |
11613 | generic actual. | |
11614 | ||
11615 | @node Attribute Universal_Literal_String,Attribute Unrestricted_Access,Attribute Unconstrained_Array,Implementation Defined Attributes | |
067d80d8 | 11616 | @anchor{gnat_rm/implementation_defined_attributes attribute-universal-literal-string}@anchor{1ae} |
64d5610f ML |
11617 | @section Attribute Universal_Literal_String |
11618 | ||
11619 | ||
11620 | @geindex Named numbers | |
11621 | @geindex representation of | |
11622 | ||
11623 | @geindex Universal_Literal_String | |
11624 | ||
11625 | The prefix of @code{Universal_Literal_String} must be a named | |
11626 | number. The static result is the string consisting of the characters of | |
11627 | the number as defined in the original source. This allows the user | |
11628 | program to access the actual text of named numbers without intermediate | |
11629 | conversions and without the need to enclose the strings in quotes (which | |
11630 | would preclude their use as numbers). | |
11631 | ||
11632 | For example, the following program prints the first 50 digits of pi: | |
11633 | ||
11634 | @example | |
11635 | with Text_IO; use Text_IO; | |
11636 | with Ada.Numerics; | |
11637 | procedure Pi is | |
11638 | begin | |
11639 | Put (Ada.Numerics.Pi'Universal_Literal_String); | |
11640 | end; | |
11641 | @end example | |
11642 | ||
11643 | @node Attribute Unrestricted_Access,Attribute Update,Attribute Universal_Literal_String,Implementation Defined Attributes | |
067d80d8 | 11644 | @anchor{gnat_rm/implementation_defined_attributes attribute-unrestricted-access}@anchor{1af} |
64d5610f ML |
11645 | @section Attribute Unrestricted_Access |
11646 | ||
11647 | ||
11648 | @geindex Access | |
11649 | @geindex unrestricted | |
11650 | ||
11651 | @geindex Unrestricted_Access | |
11652 | ||
11653 | The @code{Unrestricted_Access} attribute is similar to @code{Access} | |
11654 | except that all accessibility and aliased view checks are omitted. This | |
11655 | is a user-beware attribute. | |
11656 | ||
11657 | For objects, it is similar to @code{Address}, for which it is a | |
11658 | desirable replacement where the value desired is an access type. | |
11659 | In other words, its effect is similar to first applying the | |
11660 | @code{Address} attribute and then doing an unchecked conversion to a | |
11661 | desired access type. | |
11662 | ||
11663 | For subprograms, @code{P'Unrestricted_Access} may be used where | |
11664 | @code{P'Access} would be illegal, to construct a value of a | |
11665 | less-nested named access type that designates a more-nested | |
11666 | subprogram. This value may be used in indirect calls, so long as the | |
11667 | more-nested subprogram still exists; once the subprogram containing it | |
11668 | has returned, such calls are erroneous. For example: | |
11669 | ||
11670 | @example | |
11671 | package body P is | |
11672 | ||
11673 | type Less_Nested is not null access procedure; | |
11674 | Global : Less_Nested; | |
11675 | ||
11676 | procedure P1 is | |
11677 | begin | |
11678 | Global.all; | |
11679 | end P1; | |
11680 | ||
11681 | procedure P2 is | |
11682 | Local_Var : Integer; | |
11683 | ||
11684 | procedure More_Nested is | |
11685 | begin | |
11686 | ... Local_Var ... | |
11687 | end More_Nested; | |
11688 | begin | |
11689 | Global := More_Nested'Unrestricted_Access; | |
11690 | P1; | |
11691 | end P2; | |
11692 | ||
11693 | end P; | |
11694 | @end example | |
11695 | ||
11696 | When P1 is called from P2, the call via Global is OK, but if P1 were | |
11697 | called after P2 returns, it would be an erroneous use of a dangling | |
11698 | pointer. | |
11699 | ||
11700 | For objects, it is possible to use @code{Unrestricted_Access} for any | |
11701 | type. However, if the result is of an access-to-unconstrained array | |
11702 | subtype, then the resulting pointer has the same scope as the context | |
11703 | of the attribute, and must not be returned to some enclosing scope. | |
11704 | For instance, if a function uses @code{Unrestricted_Access} to create | |
11705 | an access-to-unconstrained-array and returns that value to the caller, | |
11706 | the result will involve dangling pointers. In addition, it is only | |
11707 | valid to create pointers to unconstrained arrays using this attribute | |
11708 | if the pointer has the normal default ‘fat’ representation where a | |
11709 | pointer has two components, one points to the array and one points to | |
11710 | the bounds. If a size clause is used to force ‘thin’ representation | |
11711 | for a pointer to unconstrained where there is only space for a single | |
11712 | pointer, then the resulting pointer is not usable. | |
11713 | ||
11714 | In the simple case where a direct use of Unrestricted_Access attempts | |
11715 | to make a thin pointer for a non-aliased object, the compiler will | |
11716 | reject the use as illegal, as shown in the following example: | |
11717 | ||
11718 | @example | |
11719 | with System; use System; | |
11720 | procedure SliceUA2 is | |
11721 | type A is access all String; | |
11722 | for A'Size use Standard'Address_Size; | |
11723 | ||
11724 | procedure P (Arg : A) is | |
11725 | begin | |
11726 | null; | |
11727 | end P; | |
11728 | ||
11729 | X : String := "hello world!"; | |
11730 | X2 : aliased String := "hello world!"; | |
11731 | ||
11732 | AV : A := X'Unrestricted_Access; -- ERROR | |
11733 | | | |
11734 | >>> illegal use of Unrestricted_Access attribute | |
11735 | >>> attempt to generate thin pointer to unaliased object | |
11736 | ||
11737 | begin | |
11738 | P (X'Unrestricted_Access); -- ERROR | |
11739 | | | |
11740 | >>> illegal use of Unrestricted_Access attribute | |
11741 | >>> attempt to generate thin pointer to unaliased object | |
11742 | ||
11743 | P (X(7 .. 12)'Unrestricted_Access); -- ERROR | |
11744 | | | |
11745 | >>> illegal use of Unrestricted_Access attribute | |
11746 | >>> attempt to generate thin pointer to unaliased object | |
11747 | ||
11748 | P (X2'Unrestricted_Access); -- OK | |
11749 | end; | |
11750 | @end example | |
11751 | ||
11752 | but other cases cannot be detected by the compiler, and are | |
11753 | considered to be erroneous. Consider the following example: | |
11754 | ||
11755 | @example | |
11756 | with System; use System; | |
11757 | with System; use System; | |
11758 | procedure SliceUA is | |
11759 | type AF is access all String; | |
11760 | ||
11761 | type A is access all String; | |
11762 | for A'Size use Standard'Address_Size; | |
11763 | ||
11764 | procedure P (Arg : A) is | |
11765 | begin | |
11766 | if Arg'Length /= 6 then | |
11767 | raise Program_Error; | |
11768 | end if; | |
11769 | end P; | |
11770 | ||
11771 | X : String := "hello world!"; | |
11772 | Y : AF := X (7 .. 12)'Unrestricted_Access; | |
11773 | ||
11774 | begin | |
11775 | P (A (Y)); | |
11776 | end; | |
11777 | @end example | |
11778 | ||
11779 | A normal unconstrained array value | |
11780 | or a constrained array object marked as aliased has the bounds in memory | |
11781 | just before the array, so a thin pointer can retrieve both the data and | |
11782 | the bounds. But in this case, the non-aliased object @code{X} does not have the | |
11783 | bounds before the string. If the size clause for type @code{A} | |
11784 | were not present, then the pointer | |
11785 | would be a fat pointer, where one component is a pointer to the bounds, | |
11786 | and all would be well. But with the size clause present, the conversion from | |
11787 | fat pointer to thin pointer in the call loses the bounds, and so this | |
11788 | is erroneous, and the program likely raises a @code{Program_Error} exception. | |
11789 | ||
11790 | In general, it is advisable to completely | |
11791 | avoid mixing the use of thin pointers and the use of | |
11792 | @code{Unrestricted_Access} where the designated type is an | |
11793 | unconstrained array. The use of thin pointers should be restricted to | |
11794 | cases of porting legacy code that implicitly assumes the size of pointers, | |
11795 | and such code should not in any case be using this attribute. | |
11796 | ||
11797 | Another erroneous situation arises if the attribute is | |
11798 | applied to a constant. The resulting pointer can be used to access the | |
11799 | constant, but the effect of trying to modify a constant in this manner | |
11800 | is not well-defined. Consider this example: | |
11801 | ||
11802 | @example | |
11803 | P : constant Integer := 4; | |
11804 | type R is access all Integer; | |
11805 | RV : R := P'Unrestricted_Access; | |
11806 | .. | |
11807 | RV.all := 3; | |
11808 | @end example | |
11809 | ||
11810 | Here we attempt to modify the constant P from 4 to 3, but the compiler may | |
11811 | or may not notice this attempt, and subsequent references to P may yield | |
11812 | either the value 3 or the value 4 or the assignment may blow up if the | |
11813 | compiler decides to put P in read-only memory. One particular case where | |
11814 | @code{Unrestricted_Access} can be used in this way is to modify the | |
11815 | value of an @code{in} parameter: | |
11816 | ||
11817 | @example | |
11818 | procedure K (S : in String) is | |
11819 | type R is access all Character; | |
11820 | RV : R := S (3)'Unrestricted_Access; | |
11821 | begin | |
11822 | RV.all := 'a'; | |
11823 | end; | |
11824 | @end example | |
11825 | ||
11826 | In general this is a risky approach. It may appear to “work” but such uses of | |
11827 | @code{Unrestricted_Access} are potentially non-portable, even from one version | |
11828 | of GNAT to another, so are best avoided if possible. | |
11829 | ||
11830 | @node Attribute Update,Attribute Valid_Value,Attribute Unrestricted_Access,Implementation Defined Attributes | |
067d80d8 | 11831 | @anchor{gnat_rm/implementation_defined_attributes attribute-update}@anchor{1b0} |
64d5610f ML |
11832 | @section Attribute Update |
11833 | ||
11834 | ||
11835 | @geindex Update | |
11836 | ||
11837 | The @code{Update} attribute creates a copy of an array or record value | |
11838 | with one or more modified components. The syntax is: | |
11839 | ||
11840 | @example | |
11841 | PREFIX'Update ( RECORD_COMPONENT_ASSOCIATION_LIST ) | |
11842 | PREFIX'Update ( ARRAY_COMPONENT_ASSOCIATION @{, ARRAY_COMPONENT_ASSOCIATION @} ) | |
11843 | PREFIX'Update ( MULTIDIMENSIONAL_ARRAY_COMPONENT_ASSOCIATION | |
11844 | @{, MULTIDIMENSIONAL_ARRAY_COMPONENT_ASSOCIATION @} ) | |
11845 | ||
11846 | MULTIDIMENSIONAL_ARRAY_COMPONENT_ASSOCIATION ::= INDEX_EXPRESSION_LIST_LIST => EXPRESSION | |
11847 | INDEX_EXPRESSION_LIST_LIST ::= INDEX_EXPRESSION_LIST @{| INDEX_EXPRESSION_LIST @} | |
11848 | INDEX_EXPRESSION_LIST ::= ( EXPRESSION @{, EXPRESSION @} ) | |
11849 | @end example | |
11850 | ||
11851 | where @code{PREFIX} is the name of an array or record object, the | |
11852 | association list in parentheses does not contain an @code{others} | |
11853 | choice and the box symbol @code{<>} may not appear in any | |
11854 | expression. The effect is to yield a copy of the array or record value | |
11855 | which is unchanged apart from the components mentioned in the | |
11856 | association list, which are changed to the indicated value. The | |
11857 | original value of the array or record value is not affected. For | |
11858 | example: | |
11859 | ||
11860 | @example | |
11861 | type Arr is Array (1 .. 5) of Integer; | |
11862 | ... | |
11863 | Avar1 : Arr := (1,2,3,4,5); | |
11864 | Avar2 : Arr := Avar1'Update (2 => 10, 3 .. 4 => 20); | |
11865 | @end example | |
11866 | ||
11867 | yields a value for @code{Avar2} of 1,10,20,20,5 with @code{Avar1} | |
11868 | begin unmodified. Similarly: | |
11869 | ||
11870 | @example | |
11871 | type Rec is A, B, C : Integer; | |
11872 | ... | |
11873 | Rvar1 : Rec := (A => 1, B => 2, C => 3); | |
11874 | Rvar2 : Rec := Rvar1'Update (B => 20); | |
11875 | @end example | |
11876 | ||
11877 | yields a value for @code{Rvar2} of (A => 1, B => 20, C => 3), | |
11878 | with @code{Rvar1} being unmodifed. | |
11879 | Note that the value of the attribute reference is computed | |
11880 | completely before it is used. This means that if you write: | |
11881 | ||
11882 | @example | |
11883 | Avar1 := Avar1'Update (1 => 10, 2 => Function_Call); | |
11884 | @end example | |
11885 | ||
11886 | then the value of @code{Avar1} is not modified if @code{Function_Call} | |
11887 | raises an exception, unlike the effect of a series of direct assignments | |
11888 | to elements of @code{Avar1}. In general this requires that | |
11889 | two extra complete copies of the object are required, which should be | |
11890 | kept in mind when considering efficiency. | |
11891 | ||
11892 | The @code{Update} attribute cannot be applied to prefixes of a limited | |
11893 | type, and cannot reference discriminants in the case of a record type. | |
11894 | The accessibility level of an Update attribute result object is defined | |
11895 | as for an aggregate. | |
11896 | ||
11897 | In the record case, no component can be mentioned more than once. In | |
11898 | the array case, two overlapping ranges can appear in the association list, | |
11899 | in which case the modifications are processed left to right. | |
11900 | ||
11901 | Multi-dimensional arrays can be modified, as shown by this example: | |
11902 | ||
11903 | @example | |
11904 | A : array (1 .. 10, 1 .. 10) of Integer; | |
11905 | .. | |
11906 | A := A'Update ((1, 2) => 20, (3, 4) => 30); | |
11907 | @end example | |
11908 | ||
11909 | which changes element (1,2) to 20 and (3,4) to 30. | |
11910 | ||
11911 | @node Attribute Valid_Value,Attribute Valid_Scalars,Attribute Update,Implementation Defined Attributes | |
067d80d8 | 11912 | @anchor{gnat_rm/implementation_defined_attributes attribute-valid-value}@anchor{1b1} |
64d5610f ML |
11913 | @section Attribute Valid_Value |
11914 | ||
11915 | ||
11916 | @geindex Valid_Value | |
11917 | ||
11918 | The @code{'Valid_Value} attribute is defined for enumeration types other than | |
11919 | those in package Standard. This attribute is a function that takes | |
11920 | a String, and returns Boolean. @code{T'Valid_Value (S)} returns True | |
11921 | if and only if @code{T'Value (S)} would not raise Constraint_Error. | |
11922 | ||
11923 | @node Attribute Valid_Scalars,Attribute VADS_Size,Attribute Valid_Value,Implementation Defined Attributes | |
067d80d8 | 11924 | @anchor{gnat_rm/implementation_defined_attributes attribute-valid-scalars}@anchor{1b2} |
64d5610f ML |
11925 | @section Attribute Valid_Scalars |
11926 | ||
11927 | ||
11928 | @geindex Valid_Scalars | |
11929 | ||
11930 | The @code{'Valid_Scalars} attribute is intended to make it easier to check the | |
11931 | validity of scalar subcomponents of composite objects. The attribute is defined | |
11932 | for any prefix @code{P} which denotes an object. Prefix @code{P} can be any type | |
11933 | except for tagged private or @code{Unchecked_Union} types. The value of the | |
11934 | attribute is of type @code{Boolean}. | |
11935 | ||
11936 | @code{P'Valid_Scalars} yields @code{True} if and only if the evaluation of | |
11937 | @code{C'Valid} yields @code{True} for every scalar subcomponent @code{C} of @code{P}, or if | |
11938 | @code{P} has no scalar subcomponents. Attribute @code{'Valid_Scalars} is equivalent | |
11939 | to attribute @code{'Valid} for scalar types. | |
11940 | ||
11941 | It is not specified in what order the subcomponents are checked, nor whether | |
11942 | any more are checked after any one of them is determined to be invalid. If the | |
11943 | prefix @code{P} is of a class-wide type @code{T'Class} (where @code{T} is the associated | |
11944 | specific type), or if the prefix @code{P} is of a specific tagged type @code{T}, then | |
11945 | only the subcomponents of @code{T} are checked; in other words, components of | |
11946 | extensions of @code{T} are not checked even if @code{T'Class (P)'Tag /= T'Tag}. | |
11947 | ||
11948 | The compiler will issue a warning if it can be determined at compile time that | |
11949 | the prefix of the attribute has no scalar subcomponents. | |
11950 | ||
11951 | Note: @code{Valid_Scalars} can generate a lot of code, especially in the case of | |
11952 | a large variant record. If the attribute is called in many places in the same | |
11953 | program applied to objects of the same type, it can reduce program size to | |
11954 | write a function with a single use of the attribute, and then call that | |
11955 | function from multiple places. | |
11956 | ||
11957 | @node Attribute VADS_Size,Attribute Value_Size,Attribute Valid_Scalars,Implementation Defined Attributes | |
067d80d8 | 11958 | @anchor{gnat_rm/implementation_defined_attributes attribute-vads-size}@anchor{1b3} |
64d5610f ML |
11959 | @section Attribute VADS_Size |
11960 | ||
11961 | ||
11962 | @geindex Size | |
11963 | @geindex VADS compatibility | |
11964 | ||
11965 | @geindex VADS_Size | |
11966 | ||
11967 | The @code{'VADS_Size} attribute is intended to make it easier to port | |
11968 | legacy code which relies on the semantics of @code{'Size} as implemented | |
11969 | by the VADS Ada 83 compiler. GNAT makes a best effort at duplicating the | |
11970 | same semantic interpretation. In particular, @code{'VADS_Size} applied | |
11971 | to a predefined or other primitive type with no Size clause yields the | |
11972 | Object_Size (for example, @code{Natural'Size} is 32 rather than 31 on | |
11973 | typical machines). In addition @code{'VADS_Size} applied to an object | |
11974 | gives the result that would be obtained by applying the attribute to | |
11975 | the corresponding type. | |
11976 | ||
11977 | @node Attribute Value_Size,Attribute Wchar_T_Size,Attribute VADS_Size,Implementation Defined Attributes | |
067d80d8 | 11978 | @anchor{gnat_rm/implementation_defined_attributes attribute-value-size}@anchor{161}@anchor{gnat_rm/implementation_defined_attributes id6}@anchor{1b4} |
64d5610f ML |
11979 | @section Attribute Value_Size |
11980 | ||
11981 | ||
11982 | @geindex Size | |
11983 | @geindex setting for not-first subtype | |
11984 | ||
11985 | @geindex Value_Size | |
11986 | ||
11987 | @code{type'Value_Size} is the number of bits required to represent | |
11988 | a value of the given subtype. It is the same as @code{type'Size}, | |
11989 | but, unlike @code{Size}, may be set for non-first subtypes. | |
11990 | ||
11991 | @node Attribute Wchar_T_Size,Attribute Word_Size,Attribute Value_Size,Implementation Defined Attributes | |
067d80d8 | 11992 | @anchor{gnat_rm/implementation_defined_attributes attribute-wchar-t-size}@anchor{1b5} |
64d5610f ML |
11993 | @section Attribute Wchar_T_Size |
11994 | ||
11995 | ||
11996 | @geindex Wchar_T_Size | |
11997 | ||
11998 | @code{Standard'Wchar_T_Size} (@code{Standard} is the only allowed | |
11999 | prefix) provides the size in bits of the C @code{wchar_t} type | |
12000 | primarily for constructing the definition of this type in | |
12001 | package @code{Interfaces.C}. The result is a static constant. | |
12002 | ||
12003 | @node Attribute Word_Size,,Attribute Wchar_T_Size,Implementation Defined Attributes | |
067d80d8 | 12004 | @anchor{gnat_rm/implementation_defined_attributes attribute-word-size}@anchor{1b6} |
64d5610f ML |
12005 | @section Attribute Word_Size |
12006 | ||
12007 | ||
12008 | @geindex Word_Size | |
12009 | ||
12010 | @code{Standard'Word_Size} (@code{Standard} is the only allowed | |
12011 | prefix) provides the value @code{System.Word_Size}. The result is | |
12012 | a static constant. | |
12013 | ||
12014 | @node Standard and Implementation Defined Restrictions,Implementation Advice,Implementation Defined Attributes,Top | |
067d80d8 | 12015 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions doc}@anchor{1b7}@anchor{gnat_rm/standard_and_implementation_defined_restrictions id1}@anchor{1b8}@anchor{gnat_rm/standard_and_implementation_defined_restrictions standard-and-implementation-defined-restrictions}@anchor{9} |
64d5610f ML |
12016 | @chapter Standard and Implementation Defined Restrictions |
12017 | ||
12018 | ||
12019 | All Ada Reference Manual-defined Restriction identifiers are implemented: | |
12020 | ||
12021 | ||
12022 | @itemize * | |
12023 | ||
12024 | @item | |
12025 | language-defined restrictions (see 13.12.1) | |
12026 | ||
12027 | @item | |
12028 | tasking restrictions (see D.7) | |
12029 | ||
12030 | @item | |
12031 | high integrity restrictions (see H.4) | |
12032 | @end itemize | |
12033 | ||
12034 | GNAT implements additional restriction identifiers. All restrictions, whether | |
12035 | language defined or GNAT-specific, are listed in the following. | |
12036 | ||
12037 | @menu | |
12038 | * Partition-Wide Restrictions:: | |
12039 | * Program Unit Level Restrictions:: | |
12040 | ||
12041 | @end menu | |
12042 | ||
12043 | @node Partition-Wide Restrictions,Program Unit Level Restrictions,,Standard and Implementation Defined Restrictions | |
067d80d8 | 12044 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions id2}@anchor{1b9}@anchor{gnat_rm/standard_and_implementation_defined_restrictions partition-wide-restrictions}@anchor{1ba} |
64d5610f ML |
12045 | @section Partition-Wide Restrictions |
12046 | ||
12047 | ||
12048 | There are two separate lists of restriction identifiers. The first | |
12049 | set requires consistency throughout a partition (in other words, if the | |
12050 | restriction identifier is used for any compilation unit in the partition, | |
12051 | then all compilation units in the partition must obey the restriction). | |
12052 | ||
12053 | @menu | |
12054 | * Immediate_Reclamation:: | |
12055 | * Max_Asynchronous_Select_Nesting:: | |
12056 | * Max_Entry_Queue_Length:: | |
12057 | * Max_Protected_Entries:: | |
12058 | * Max_Select_Alternatives:: | |
12059 | * Max_Storage_At_Blocking:: | |
12060 | * Max_Task_Entries:: | |
12061 | * Max_Tasks:: | |
12062 | * No_Abort_Statements:: | |
12063 | * No_Access_Parameter_Allocators:: | |
12064 | * No_Access_Subprograms:: | |
12065 | * No_Allocators:: | |
12066 | * No_Anonymous_Allocators:: | |
12067 | * No_Asynchronous_Control:: | |
12068 | * No_Calendar:: | |
12069 | * No_Coextensions:: | |
12070 | * No_Default_Initialization:: | |
12071 | * No_Delay:: | |
12072 | * No_Dependence:: | |
12073 | * No_Direct_Boolean_Operators:: | |
12074 | * No_Dispatch:: | |
12075 | * No_Dispatching_Calls:: | |
12076 | * No_Dynamic_Attachment:: | |
12077 | * No_Dynamic_Priorities:: | |
12078 | * No_Entry_Calls_In_Elaboration_Code:: | |
12079 | * No_Enumeration_Maps:: | |
12080 | * No_Exception_Handlers:: | |
12081 | * No_Exception_Propagation:: | |
12082 | * No_Exception_Registration:: | |
12083 | * No_Exceptions:: | |
12084 | * No_Finalization:: | |
12085 | * No_Fixed_Point:: | |
12086 | * No_Floating_Point:: | |
12087 | * No_Implicit_Conditionals:: | |
12088 | * No_Implicit_Dynamic_Code:: | |
12089 | * No_Implicit_Heap_Allocations:: | |
12090 | * No_Implicit_Protected_Object_Allocations:: | |
12091 | * No_Implicit_Task_Allocations:: | |
12092 | * No_Initialize_Scalars:: | |
12093 | * No_IO:: | |
12094 | * No_Local_Allocators:: | |
12095 | * No_Local_Protected_Objects:: | |
12096 | * No_Local_Tagged_Types:: | |
12097 | * No_Local_Timing_Events:: | |
12098 | * No_Long_Long_Integers:: | |
12099 | * No_Multiple_Elaboration:: | |
12100 | * No_Nested_Finalization:: | |
12101 | * No_Protected_Type_Allocators:: | |
12102 | * No_Protected_Types:: | |
12103 | * No_Recursion:: | |
12104 | * No_Reentrancy:: | |
12105 | * No_Relative_Delay:: | |
12106 | * No_Requeue_Statements:: | |
12107 | * No_Secondary_Stack:: | |
12108 | * No_Select_Statements:: | |
12109 | * No_Specific_Termination_Handlers:: | |
12110 | * No_Specification_of_Aspect:: | |
12111 | * No_Standard_Allocators_After_Elaboration:: | |
12112 | * No_Standard_Storage_Pools:: | |
12113 | * No_Stream_Optimizations:: | |
12114 | * No_Streams:: | |
12115 | * No_Tagged_Type_Registration:: | |
12116 | * No_Task_Allocators:: | |
12117 | * No_Task_At_Interrupt_Priority:: | |
12118 | * No_Task_Attributes_Package:: | |
12119 | * No_Task_Hierarchy:: | |
12120 | * No_Task_Termination:: | |
12121 | * No_Tasking:: | |
12122 | * No_Terminate_Alternatives:: | |
12123 | * No_Unchecked_Access:: | |
12124 | * No_Unchecked_Conversion:: | |
12125 | * No_Unchecked_Deallocation:: | |
73918baf | 12126 | * No_Use_Of_Attribute:: |
64d5610f | 12127 | * No_Use_Of_Entity:: |
73918baf | 12128 | * No_Use_Of_Pragma:: |
64d5610f ML |
12129 | * Pure_Barriers:: |
12130 | * Simple_Barriers:: | |
12131 | * Static_Priorities:: | |
12132 | * Static_Storage_Size:: | |
12133 | ||
12134 | @end menu | |
12135 | ||
12136 | @node Immediate_Reclamation,Max_Asynchronous_Select_Nesting,,Partition-Wide Restrictions | |
067d80d8 | 12137 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions immediate-reclamation}@anchor{1bb} |
64d5610f ML |
12138 | @subsection Immediate_Reclamation |
12139 | ||
12140 | ||
12141 | @geindex Immediate_Reclamation | |
12142 | ||
12143 | [RM H.4] This restriction ensures that, except for storage occupied by | |
12144 | objects created by allocators and not deallocated via unchecked | |
12145 | deallocation, any storage reserved at run time for an object is | |
12146 | immediately reclaimed when the object no longer exists. | |
12147 | ||
12148 | @node Max_Asynchronous_Select_Nesting,Max_Entry_Queue_Length,Immediate_Reclamation,Partition-Wide Restrictions | |
067d80d8 | 12149 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions max-asynchronous-select-nesting}@anchor{1bc} |
64d5610f ML |
12150 | @subsection Max_Asynchronous_Select_Nesting |
12151 | ||
12152 | ||
12153 | @geindex Max_Asynchronous_Select_Nesting | |
12154 | ||
12155 | [RM D.7] Specifies the maximum dynamic nesting level of asynchronous | |
12156 | selects. Violations of this restriction with a value of zero are | |
12157 | detected at compile time. Violations of this restriction with values | |
12158 | other than zero cause Storage_Error to be raised. | |
12159 | ||
12160 | @node Max_Entry_Queue_Length,Max_Protected_Entries,Max_Asynchronous_Select_Nesting,Partition-Wide Restrictions | |
067d80d8 | 12161 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions max-entry-queue-length}@anchor{1bd} |
64d5610f ML |
12162 | @subsection Max_Entry_Queue_Length |
12163 | ||
12164 | ||
12165 | @geindex Max_Entry_Queue_Length | |
12166 | ||
12167 | [RM D.7] This restriction is a declaration that any protected entry compiled in | |
12168 | the scope of the restriction has at most the specified number of | |
12169 | tasks waiting on the entry at any one time, and so no queue is required. | |
12170 | Note that this restriction is checked at run time. Violation of this | |
12171 | restriction results in the raising of Program_Error exception at the point of | |
12172 | the call. | |
12173 | ||
12174 | @geindex Max_Entry_Queue_Depth | |
12175 | ||
12176 | The restriction @code{Max_Entry_Queue_Depth} is recognized as a | |
12177 | synonym for @code{Max_Entry_Queue_Length}. This is retained for historical | |
12178 | compatibility purposes (and a warning will be generated for its use if | |
12179 | warnings on obsolescent features are activated). | |
12180 | ||
12181 | @node Max_Protected_Entries,Max_Select_Alternatives,Max_Entry_Queue_Length,Partition-Wide Restrictions | |
067d80d8 | 12182 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions max-protected-entries}@anchor{1be} |
64d5610f ML |
12183 | @subsection Max_Protected_Entries |
12184 | ||
12185 | ||
12186 | @geindex Max_Protected_Entries | |
12187 | ||
12188 | [RM D.7] Specifies the maximum number of entries per protected type. The | |
12189 | bounds of every entry family of a protected unit shall be static, or shall be | |
12190 | defined by a discriminant of a subtype whose corresponding bound is static. | |
12191 | ||
12192 | @node Max_Select_Alternatives,Max_Storage_At_Blocking,Max_Protected_Entries,Partition-Wide Restrictions | |
067d80d8 | 12193 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions max-select-alternatives}@anchor{1bf} |
64d5610f ML |
12194 | @subsection Max_Select_Alternatives |
12195 | ||
12196 | ||
12197 | @geindex Max_Select_Alternatives | |
12198 | ||
12199 | [RM D.7] Specifies the maximum number of alternatives in a selective accept. | |
12200 | ||
12201 | @node Max_Storage_At_Blocking,Max_Task_Entries,Max_Select_Alternatives,Partition-Wide Restrictions | |
067d80d8 | 12202 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions max-storage-at-blocking}@anchor{1c0} |
64d5610f ML |
12203 | @subsection Max_Storage_At_Blocking |
12204 | ||
12205 | ||
12206 | @geindex Max_Storage_At_Blocking | |
12207 | ||
12208 | [RM D.7] Specifies the maximum portion (in storage elements) of a task’s | |
12209 | Storage_Size that can be retained by a blocked task. A violation of this | |
12210 | restriction causes Storage_Error to be raised. | |
12211 | ||
12212 | @node Max_Task_Entries,Max_Tasks,Max_Storage_At_Blocking,Partition-Wide Restrictions | |
067d80d8 | 12213 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions max-task-entries}@anchor{1c1} |
64d5610f ML |
12214 | @subsection Max_Task_Entries |
12215 | ||
12216 | ||
12217 | @geindex Max_Task_Entries | |
12218 | ||
12219 | [RM D.7] Specifies the maximum number of entries | |
12220 | per task. The bounds of every entry family | |
12221 | of a task unit shall be static, or shall be | |
12222 | defined by a discriminant of a subtype whose | |
12223 | corresponding bound is static. | |
12224 | ||
12225 | @node Max_Tasks,No_Abort_Statements,Max_Task_Entries,Partition-Wide Restrictions | |
067d80d8 | 12226 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions max-tasks}@anchor{1c2} |
64d5610f ML |
12227 | @subsection Max_Tasks |
12228 | ||
12229 | ||
12230 | @geindex Max_Tasks | |
12231 | ||
12232 | [RM D.7] Specifies the maximum number of task that may be created, not | |
12233 | counting the creation of the environment task. Violations of this | |
12234 | restriction with a value of zero are detected at compile | |
12235 | time. Violations of this restriction with values other than zero cause | |
12236 | Storage_Error to be raised. | |
12237 | ||
12238 | @node No_Abort_Statements,No_Access_Parameter_Allocators,Max_Tasks,Partition-Wide Restrictions | |
067d80d8 | 12239 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-abort-statements}@anchor{1c3} |
64d5610f ML |
12240 | @subsection No_Abort_Statements |
12241 | ||
12242 | ||
12243 | @geindex No_Abort_Statements | |
12244 | ||
12245 | [RM D.7] There are no abort_statements, and there are | |
12246 | no calls to Task_Identification.Abort_Task. | |
12247 | ||
12248 | @node No_Access_Parameter_Allocators,No_Access_Subprograms,No_Abort_Statements,Partition-Wide Restrictions | |
067d80d8 | 12249 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-access-parameter-allocators}@anchor{1c4} |
64d5610f ML |
12250 | @subsection No_Access_Parameter_Allocators |
12251 | ||
12252 | ||
12253 | @geindex No_Access_Parameter_Allocators | |
12254 | ||
12255 | [RM H.4] This restriction ensures at compile time that there are no | |
12256 | occurrences of an allocator as the actual parameter to an access | |
12257 | parameter. | |
12258 | ||
12259 | @node No_Access_Subprograms,No_Allocators,No_Access_Parameter_Allocators,Partition-Wide Restrictions | |
067d80d8 | 12260 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-access-subprograms}@anchor{1c5} |
64d5610f ML |
12261 | @subsection No_Access_Subprograms |
12262 | ||
12263 | ||
12264 | @geindex No_Access_Subprograms | |
12265 | ||
12266 | [RM H.4] This restriction ensures at compile time that there are no | |
12267 | declarations of access-to-subprogram types. | |
12268 | ||
12269 | @node No_Allocators,No_Anonymous_Allocators,No_Access_Subprograms,Partition-Wide Restrictions | |
067d80d8 | 12270 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-allocators}@anchor{1c6} |
64d5610f ML |
12271 | @subsection No_Allocators |
12272 | ||
12273 | ||
12274 | @geindex No_Allocators | |
12275 | ||
12276 | [RM H.4] This restriction ensures at compile time that there are no | |
12277 | occurrences of an allocator. | |
12278 | ||
12279 | @node No_Anonymous_Allocators,No_Asynchronous_Control,No_Allocators,Partition-Wide Restrictions | |
067d80d8 | 12280 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-anonymous-allocators}@anchor{1c7} |
64d5610f ML |
12281 | @subsection No_Anonymous_Allocators |
12282 | ||
12283 | ||
12284 | @geindex No_Anonymous_Allocators | |
12285 | ||
12286 | [RM H.4] This restriction ensures at compile time that there are no | |
12287 | occurrences of an allocator of anonymous access type. | |
12288 | ||
12289 | @node No_Asynchronous_Control,No_Calendar,No_Anonymous_Allocators,Partition-Wide Restrictions | |
067d80d8 | 12290 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-asynchronous-control}@anchor{1c8} |
64d5610f ML |
12291 | @subsection No_Asynchronous_Control |
12292 | ||
12293 | ||
12294 | @geindex No_Asynchronous_Control | |
12295 | ||
12296 | [RM J.13] This restriction ensures at compile time that there are no semantic | |
12297 | dependences on the predefined package Asynchronous_Task_Control. | |
12298 | ||
12299 | @node No_Calendar,No_Coextensions,No_Asynchronous_Control,Partition-Wide Restrictions | |
067d80d8 | 12300 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-calendar}@anchor{1c9} |
64d5610f ML |
12301 | @subsection No_Calendar |
12302 | ||
12303 | ||
12304 | @geindex No_Calendar | |
12305 | ||
12306 | [GNAT] This restriction ensures at compile time that there are no semantic | |
12307 | dependences on package Calendar. | |
12308 | ||
12309 | @node No_Coextensions,No_Default_Initialization,No_Calendar,Partition-Wide Restrictions | |
067d80d8 | 12310 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-coextensions}@anchor{1ca} |
64d5610f ML |
12311 | @subsection No_Coextensions |
12312 | ||
12313 | ||
12314 | @geindex No_Coextensions | |
12315 | ||
12316 | [RM H.4] This restriction ensures at compile time that there are no | |
12317 | coextensions. See 3.10.2. | |
12318 | ||
12319 | @node No_Default_Initialization,No_Delay,No_Coextensions,Partition-Wide Restrictions | |
067d80d8 | 12320 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-default-initialization}@anchor{1cb} |
64d5610f ML |
12321 | @subsection No_Default_Initialization |
12322 | ||
12323 | ||
12324 | @geindex No_Default_Initialization | |
12325 | ||
12326 | [GNAT] This restriction prohibits any instance of default initialization | |
12327 | of variables. The binder implements a consistency rule which prevents | |
12328 | any unit compiled without the restriction from with’ing a unit with the | |
12329 | restriction (this allows the generation of initialization procedures to | |
12330 | be skipped, since you can be sure that no call is ever generated to an | |
12331 | initialization procedure in a unit with the restriction active). If used | |
12332 | in conjunction with Initialize_Scalars or Normalize_Scalars, the effect | |
12333 | is to prohibit all cases of variables declared without a specific | |
12334 | initializer (including the case of OUT scalar parameters). | |
12335 | ||
12336 | @node No_Delay,No_Dependence,No_Default_Initialization,Partition-Wide Restrictions | |
067d80d8 | 12337 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-delay}@anchor{1cc} |
64d5610f ML |
12338 | @subsection No_Delay |
12339 | ||
12340 | ||
12341 | @geindex No_Delay | |
12342 | ||
12343 | [RM H.4] This restriction ensures at compile time that there are no | |
12344 | delay statements and no semantic dependences on package Calendar. | |
12345 | ||
12346 | @node No_Dependence,No_Direct_Boolean_Operators,No_Delay,Partition-Wide Restrictions | |
067d80d8 | 12347 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dependence}@anchor{1cd} |
64d5610f ML |
12348 | @subsection No_Dependence |
12349 | ||
12350 | ||
12351 | @geindex No_Dependence | |
12352 | ||
12353 | [RM 13.12.1] This restriction ensures at compile time that there are no | |
12354 | dependences on a library unit. For GNAT, this includes implicit implementation | |
12355 | dependences on units of the runtime library that are created by the compiler | |
5c6e2616 EB |
12356 | to support specific constructs of the language. Here are some examples: |
12357 | ||
12358 | ||
12359 | @itemize * | |
12360 | ||
12361 | @item | |
12362 | @code{System.Arith_64}: 64-bit arithmetics for 32-bit platforms, | |
12363 | ||
12364 | @item | |
12365 | @code{System.Arith_128}: 128-bit arithmetics for 64-bit platforms, | |
12366 | ||
12367 | @item | |
12368 | @code{System.Memory}: heap memory allocation routines, | |
12369 | ||
12370 | @item | |
12371 | @code{System.Memory_Compare}: memory comparison routine (aka @code{memcmp} for C), | |
12372 | ||
12373 | @item | |
12374 | @code{System.Memory_Copy}: memory copy routine (aka @code{memcpy} for C), | |
12375 | ||
12376 | @item | |
12377 | @code{System.Memory_Move}: memoy move routine (aka @code{memmove} for C), | |
12378 | ||
12379 | @item | |
12380 | @code{System.Memory_Set}: memory set routine (aka @code{memset} for C), | |
12381 | ||
12382 | @item | |
12383 | @code{System.Stack_Checking[.Operations]}: stack checking without MMU, | |
12384 | ||
12385 | @item | |
12386 | @code{System.GCC}: support routines from the GCC library. | |
12387 | @end itemize | |
64d5610f ML |
12388 | |
12389 | @node No_Direct_Boolean_Operators,No_Dispatch,No_Dependence,Partition-Wide Restrictions | |
067d80d8 | 12390 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-direct-boolean-operators}@anchor{1ce} |
64d5610f ML |
12391 | @subsection No_Direct_Boolean_Operators |
12392 | ||
12393 | ||
12394 | @geindex No_Direct_Boolean_Operators | |
12395 | ||
12396 | [GNAT] This restriction ensures that no logical operators (and/or/xor) | |
12397 | are used on operands of type Boolean (or any type derived from Boolean). | |
12398 | This is intended for use in safety critical programs where the certification | |
12399 | protocol requires the use of short-circuit (and then, or else) forms for all | |
12400 | composite boolean operations. | |
12401 | ||
12402 | @node No_Dispatch,No_Dispatching_Calls,No_Direct_Boolean_Operators,Partition-Wide Restrictions | |
067d80d8 | 12403 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dispatch}@anchor{1cf} |
64d5610f ML |
12404 | @subsection No_Dispatch |
12405 | ||
12406 | ||
12407 | @geindex No_Dispatch | |
12408 | ||
12409 | [RM H.4] This restriction ensures at compile time that there are no | |
12410 | occurrences of @code{T'Class}, for any (tagged) subtype @code{T}. | |
12411 | ||
12412 | @node No_Dispatching_Calls,No_Dynamic_Attachment,No_Dispatch,Partition-Wide Restrictions | |
067d80d8 | 12413 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dispatching-calls}@anchor{1d0} |
64d5610f ML |
12414 | @subsection No_Dispatching_Calls |
12415 | ||
12416 | ||
12417 | @geindex No_Dispatching_Calls | |
12418 | ||
12419 | [GNAT] This restriction ensures at compile time that the code generated by the | |
12420 | compiler involves no dispatching calls. The use of this restriction allows the | |
12421 | safe use of record extensions, classwide membership tests and other classwide | |
12422 | features not involving implicit dispatching. This restriction ensures that | |
12423 | the code contains no indirect calls through a dispatching mechanism. Note that | |
12424 | this includes internally-generated calls created by the compiler, for example | |
12425 | in the implementation of class-wide objects assignments. The | |
12426 | membership test is allowed in the presence of this restriction, because its | |
12427 | implementation requires no dispatching. | |
12428 | This restriction is comparable to the official Ada restriction | |
12429 | @code{No_Dispatch} except that it is a bit less restrictive in that it allows | |
12430 | all classwide constructs that do not imply dispatching. | |
12431 | The following example indicates constructs that violate this restriction. | |
12432 | ||
12433 | @example | |
12434 | package Pkg is | |
12435 | type T is tagged record | |
12436 | Data : Natural; | |
12437 | end record; | |
12438 | procedure P (X : T); | |
12439 | ||
12440 | type DT is new T with record | |
12441 | More_Data : Natural; | |
12442 | end record; | |
12443 | procedure Q (X : DT); | |
12444 | end Pkg; | |
12445 | ||
12446 | with Pkg; use Pkg; | |
12447 | procedure Example is | |
12448 | procedure Test (O : T'Class) is | |
12449 | N : Natural := O'Size; -- Error: Dispatching call | |
12450 | C : T'Class := O; -- Error: implicit Dispatching Call | |
12451 | begin | |
12452 | if O in DT'Class then -- OK : Membership test | |
12453 | Q (DT (O)); -- OK : Type conversion plus direct call | |
12454 | else | |
12455 | P (O); -- Error: Dispatching call | |
12456 | end if; | |
12457 | end Test; | |
12458 | ||
12459 | Obj : DT; | |
12460 | begin | |
12461 | P (Obj); -- OK : Direct call | |
12462 | P (T (Obj)); -- OK : Type conversion plus direct call | |
12463 | P (T'Class (Obj)); -- Error: Dispatching call | |
12464 | ||
12465 | Test (Obj); -- OK : Type conversion | |
12466 | ||
12467 | if Obj in T'Class then -- OK : Membership test | |
12468 | null; | |
12469 | end if; | |
12470 | end Example; | |
12471 | @end example | |
12472 | ||
12473 | @node No_Dynamic_Attachment,No_Dynamic_Priorities,No_Dispatching_Calls,Partition-Wide Restrictions | |
067d80d8 | 12474 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dynamic-attachment}@anchor{1d1} |
64d5610f ML |
12475 | @subsection No_Dynamic_Attachment |
12476 | ||
12477 | ||
12478 | @geindex No_Dynamic_Attachment | |
12479 | ||
12480 | [RM D.7] This restriction ensures that there is no call to any of the | |
12481 | operations defined in package Ada.Interrupts | |
12482 | (Is_Reserved, Is_Attached, Current_Handler, Attach_Handler, Exchange_Handler, | |
12483 | Detach_Handler, and Reference). | |
12484 | ||
12485 | @geindex No_Dynamic_Interrupts | |
12486 | ||
12487 | The restriction @code{No_Dynamic_Interrupts} is recognized as a | |
12488 | synonym for @code{No_Dynamic_Attachment}. This is retained for historical | |
12489 | compatibility purposes (and a warning will be generated for its use if | |
12490 | warnings on obsolescent features are activated). | |
12491 | ||
12492 | @node No_Dynamic_Priorities,No_Entry_Calls_In_Elaboration_Code,No_Dynamic_Attachment,Partition-Wide Restrictions | |
067d80d8 | 12493 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dynamic-priorities}@anchor{1d2} |
64d5610f ML |
12494 | @subsection No_Dynamic_Priorities |
12495 | ||
12496 | ||
12497 | @geindex No_Dynamic_Priorities | |
12498 | ||
12499 | [RM D.7] There are no semantic dependencies on the package Dynamic_Priorities. | |
12500 | ||
12501 | @node No_Entry_Calls_In_Elaboration_Code,No_Enumeration_Maps,No_Dynamic_Priorities,Partition-Wide Restrictions | |
067d80d8 | 12502 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-entry-calls-in-elaboration-code}@anchor{1d3} |
64d5610f ML |
12503 | @subsection No_Entry_Calls_In_Elaboration_Code |
12504 | ||
12505 | ||
12506 | @geindex No_Entry_Calls_In_Elaboration_Code | |
12507 | ||
12508 | [GNAT] This restriction ensures at compile time that no task or protected entry | |
12509 | calls are made during elaboration code. As a result of the use of this | |
12510 | restriction, the compiler can assume that no code past an accept statement | |
12511 | in a task can be executed at elaboration time. | |
12512 | ||
12513 | @node No_Enumeration_Maps,No_Exception_Handlers,No_Entry_Calls_In_Elaboration_Code,Partition-Wide Restrictions | |
067d80d8 | 12514 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-enumeration-maps}@anchor{1d4} |
64d5610f ML |
12515 | @subsection No_Enumeration_Maps |
12516 | ||
12517 | ||
12518 | @geindex No_Enumeration_Maps | |
12519 | ||
12520 | [GNAT] This restriction ensures at compile time that no operations requiring | |
12521 | enumeration maps are used (that is Image and Value attributes applied | |
12522 | to enumeration types). | |
12523 | ||
12524 | @node No_Exception_Handlers,No_Exception_Propagation,No_Enumeration_Maps,Partition-Wide Restrictions | |
067d80d8 | 12525 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-exception-handlers}@anchor{1d5} |
64d5610f ML |
12526 | @subsection No_Exception_Handlers |
12527 | ||
12528 | ||
12529 | @geindex No_Exception_Handlers | |
12530 | ||
12531 | [GNAT] This restriction ensures at compile time that there are no explicit | |
12532 | exception handlers. It also indicates that no exception propagation will | |
12533 | be provided. In this mode, exceptions may be raised but will result in | |
12534 | an immediate call to the last chance handler, a routine that the user | |
12535 | must define with the following profile: | |
12536 | ||
12537 | @example | |
12538 | procedure Last_Chance_Handler | |
12539 | (Source_Location : System.Address; Line : Integer); | |
12540 | pragma Export (C, Last_Chance_Handler, | |
12541 | "__gnat_last_chance_handler"); | |
12542 | @end example | |
12543 | ||
12544 | The parameter is a C null-terminated string representing a message to be | |
12545 | associated with the exception (typically the source location of the raise | |
12546 | statement generated by the compiler). The Line parameter when nonzero | |
12547 | represents the line number in the source program where the raise occurs. | |
12548 | ||
12549 | @node No_Exception_Propagation,No_Exception_Registration,No_Exception_Handlers,Partition-Wide Restrictions | |
067d80d8 | 12550 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-exception-propagation}@anchor{1d6} |
64d5610f ML |
12551 | @subsection No_Exception_Propagation |
12552 | ||
12553 | ||
12554 | @geindex No_Exception_Propagation | |
12555 | ||
12556 | [GNAT] This restriction guarantees that exceptions are never propagated | |
12557 | to an outer subprogram scope. The only case in which an exception may | |
12558 | be raised is when the handler is statically in the same subprogram, so | |
12559 | that the effect of a raise is essentially like a goto statement. Any | |
12560 | other raise statement (implicit or explicit) will be considered | |
12561 | unhandled. Exception handlers are allowed, but may not contain an | |
12562 | exception occurrence identifier (exception choice). In addition, use of | |
12563 | the package GNAT.Current_Exception is not permitted, and reraise | |
12564 | statements (raise with no operand) are not permitted. | |
12565 | ||
12566 | @node No_Exception_Registration,No_Exceptions,No_Exception_Propagation,Partition-Wide Restrictions | |
067d80d8 | 12567 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-exception-registration}@anchor{1d7} |
64d5610f ML |
12568 | @subsection No_Exception_Registration |
12569 | ||
12570 | ||
12571 | @geindex No_Exception_Registration | |
12572 | ||
12573 | [GNAT] This restriction ensures at compile time that no stream operations for | |
12574 | types Exception_Id or Exception_Occurrence are used. This also makes it | |
12575 | impossible to pass exceptions to or from a partition with this restriction | |
12576 | in a distributed environment. If this restriction is active, the generated | |
12577 | code is simplified by omitting the otherwise-required global registration | |
12578 | of exceptions when they are declared. | |
12579 | ||
12580 | @node No_Exceptions,No_Finalization,No_Exception_Registration,Partition-Wide Restrictions | |
067d80d8 | 12581 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-exceptions}@anchor{1d8} |
64d5610f ML |
12582 | @subsection No_Exceptions |
12583 | ||
12584 | ||
12585 | @geindex No_Exceptions | |
12586 | ||
12587 | [RM H.4] This restriction ensures at compile time that there are no | |
12588 | raise statements and no exception handlers and also suppresses the | |
12589 | generation of language-defined run-time checks. | |
12590 | ||
12591 | @node No_Finalization,No_Fixed_Point,No_Exceptions,Partition-Wide Restrictions | |
067d80d8 | 12592 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-finalization}@anchor{1d9} |
64d5610f ML |
12593 | @subsection No_Finalization |
12594 | ||
12595 | ||
12596 | @geindex No_Finalization | |
12597 | ||
12598 | [GNAT] This restriction disables the language features described in | |
12599 | chapter 7.6 of the Ada 2005 RM as well as all form of code generation | |
12600 | performed by the compiler to support these features. The following types | |
12601 | are no longer considered controlled when this restriction is in effect: | |
12602 | ||
12603 | ||
12604 | @itemize * | |
12605 | ||
12606 | @item | |
12607 | @code{Ada.Finalization.Controlled} | |
12608 | ||
12609 | @item | |
12610 | @code{Ada.Finalization.Limited_Controlled} | |
12611 | ||
12612 | @item | |
12613 | Derivations from @code{Controlled} or @code{Limited_Controlled} | |
12614 | ||
12615 | @item | |
12616 | Class-wide types | |
12617 | ||
12618 | @item | |
12619 | Protected types | |
12620 | ||
12621 | @item | |
12622 | Task types | |
12623 | ||
12624 | @item | |
12625 | Array and record types with controlled components | |
12626 | @end itemize | |
12627 | ||
12628 | The compiler no longer generates code to initialize, finalize or adjust an | |
12629 | object or a nested component, either declared on the stack or on the heap. The | |
12630 | deallocation of a controlled object no longer finalizes its contents. | |
12631 | ||
12632 | @node No_Fixed_Point,No_Floating_Point,No_Finalization,Partition-Wide Restrictions | |
067d80d8 | 12633 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-fixed-point}@anchor{1da} |
64d5610f ML |
12634 | @subsection No_Fixed_Point |
12635 | ||
12636 | ||
12637 | @geindex No_Fixed_Point | |
12638 | ||
12639 | [RM H.4] This restriction ensures at compile time that there are no | |
12640 | occurrences of fixed point types and operations. | |
12641 | ||
12642 | @node No_Floating_Point,No_Implicit_Conditionals,No_Fixed_Point,Partition-Wide Restrictions | |
067d80d8 | 12643 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-floating-point}@anchor{1db} |
64d5610f ML |
12644 | @subsection No_Floating_Point |
12645 | ||
12646 | ||
12647 | @geindex No_Floating_Point | |
12648 | ||
12649 | [RM H.4] This restriction ensures at compile time that there are no | |
12650 | occurrences of floating point types and operations. | |
12651 | ||
12652 | @node No_Implicit_Conditionals,No_Implicit_Dynamic_Code,No_Floating_Point,Partition-Wide Restrictions | |
067d80d8 | 12653 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-conditionals}@anchor{1dc} |
64d5610f ML |
12654 | @subsection No_Implicit_Conditionals |
12655 | ||
12656 | ||
12657 | @geindex No_Implicit_Conditionals | |
12658 | ||
12659 | [GNAT] This restriction ensures that the generated code does not contain any | |
12660 | implicit conditionals, either by modifying the generated code where possible, | |
12661 | or by rejecting any construct that would otherwise generate an implicit | |
12662 | conditional. Note that this check does not include run time constraint | |
12663 | checks, which on some targets may generate implicit conditionals as | |
12664 | well. To control the latter, constraint checks can be suppressed in the | |
12665 | normal manner. Constructs generating implicit conditionals include comparisons | |
12666 | of composite objects and the Max/Min attributes. | |
12667 | ||
12668 | @node No_Implicit_Dynamic_Code,No_Implicit_Heap_Allocations,No_Implicit_Conditionals,Partition-Wide Restrictions | |
067d80d8 | 12669 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-dynamic-code}@anchor{1dd} |
64d5610f ML |
12670 | @subsection No_Implicit_Dynamic_Code |
12671 | ||
12672 | ||
12673 | @geindex No_Implicit_Dynamic_Code | |
12674 | ||
12675 | @geindex trampoline | |
12676 | ||
12677 | [GNAT] This restriction prevents the compiler from building ‘trampolines’. | |
12678 | This is a structure that is built on the stack and contains dynamic | |
12679 | code to be executed at run time. On some targets, a trampoline is | |
12680 | built for the following features: @code{Access}, | |
12681 | @code{Unrestricted_Access}, or @code{Address} of a nested subprogram; | |
12682 | nested task bodies; primitive operations of nested tagged types. | |
12683 | Trampolines do not work on machines that prevent execution of stack | |
12684 | data. For example, on windows systems, enabling DEP (data execution | |
12685 | protection) will cause trampolines to raise an exception. | |
12686 | Trampolines are also quite slow at run time. | |
12687 | ||
12688 | On many targets, trampolines have been largely eliminated. Look at the | |
12689 | version of system.ads for your target — if it has | |
12690 | Always_Compatible_Rep equal to False, then trampolines are largely | |
12691 | eliminated. In particular, a trampoline is built for the following | |
12692 | features: @code{Address} of a nested subprogram; | |
12693 | @code{Access} or @code{Unrestricted_Access} of a nested subprogram, | |
12694 | but only if pragma Favor_Top_Level applies, or the access type has a | |
12695 | foreign-language convention; primitive operations of nested tagged | |
12696 | types. | |
12697 | ||
12698 | @node No_Implicit_Heap_Allocations,No_Implicit_Protected_Object_Allocations,No_Implicit_Dynamic_Code,Partition-Wide Restrictions | |
067d80d8 | 12699 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-heap-allocations}@anchor{1de} |
64d5610f ML |
12700 | @subsection No_Implicit_Heap_Allocations |
12701 | ||
12702 | ||
12703 | @geindex No_Implicit_Heap_Allocations | |
12704 | ||
12705 | [RM D.7] No constructs are allowed to cause implicit heap allocation. | |
12706 | ||
12707 | @node No_Implicit_Protected_Object_Allocations,No_Implicit_Task_Allocations,No_Implicit_Heap_Allocations,Partition-Wide Restrictions | |
067d80d8 | 12708 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-protected-object-allocations}@anchor{1df} |
64d5610f ML |
12709 | @subsection No_Implicit_Protected_Object_Allocations |
12710 | ||
12711 | ||
12712 | @geindex No_Implicit_Protected_Object_Allocations | |
12713 | ||
12714 | [GNAT] No constructs are allowed to cause implicit heap allocation of a | |
12715 | protected object. | |
12716 | ||
12717 | @node No_Implicit_Task_Allocations,No_Initialize_Scalars,No_Implicit_Protected_Object_Allocations,Partition-Wide Restrictions | |
067d80d8 | 12718 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-task-allocations}@anchor{1e0} |
64d5610f ML |
12719 | @subsection No_Implicit_Task_Allocations |
12720 | ||
12721 | ||
12722 | @geindex No_Implicit_Task_Allocations | |
12723 | ||
12724 | [GNAT] No constructs are allowed to cause implicit heap allocation of a task. | |
12725 | ||
12726 | @node No_Initialize_Scalars,No_IO,No_Implicit_Task_Allocations,Partition-Wide Restrictions | |
067d80d8 | 12727 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-initialize-scalars}@anchor{1e1} |
64d5610f ML |
12728 | @subsection No_Initialize_Scalars |
12729 | ||
12730 | ||
12731 | @geindex No_Initialize_Scalars | |
12732 | ||
12733 | [GNAT] This restriction ensures that no unit in the partition is compiled with | |
12734 | pragma Initialize_Scalars. This allows the generation of more efficient | |
12735 | code, and in particular eliminates dummy null initialization routines that | |
12736 | are otherwise generated for some record and array types. | |
12737 | ||
12738 | @node No_IO,No_Local_Allocators,No_Initialize_Scalars,Partition-Wide Restrictions | |
067d80d8 | 12739 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-io}@anchor{1e2} |
64d5610f ML |
12740 | @subsection No_IO |
12741 | ||
12742 | ||
12743 | @geindex No_IO | |
12744 | ||
12745 | [RM H.4] This restriction ensures at compile time that there are no | |
12746 | dependences on any of the library units Sequential_IO, Direct_IO, | |
12747 | Text_IO, Wide_Text_IO, Wide_Wide_Text_IO, or Stream_IO. | |
12748 | ||
12749 | @node No_Local_Allocators,No_Local_Protected_Objects,No_IO,Partition-Wide Restrictions | |
067d80d8 | 12750 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-local-allocators}@anchor{1e3} |
64d5610f ML |
12751 | @subsection No_Local_Allocators |
12752 | ||
12753 | ||
12754 | @geindex No_Local_Allocators | |
12755 | ||
12756 | [RM H.4] This restriction ensures at compile time that there are no | |
12757 | occurrences of an allocator in subprograms, generic subprograms, tasks, | |
12758 | and entry bodies. | |
12759 | ||
12760 | @node No_Local_Protected_Objects,No_Local_Tagged_Types,No_Local_Allocators,Partition-Wide Restrictions | |
067d80d8 | 12761 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-local-protected-objects}@anchor{1e4} |
64d5610f ML |
12762 | @subsection No_Local_Protected_Objects |
12763 | ||
12764 | ||
12765 | @geindex No_Local_Protected_Objects | |
12766 | ||
12767 | [RM D.7] This restriction ensures at compile time that protected objects are | |
12768 | only declared at the library level. | |
12769 | ||
12770 | @node No_Local_Tagged_Types,No_Local_Timing_Events,No_Local_Protected_Objects,Partition-Wide Restrictions | |
067d80d8 | 12771 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-local-tagged-types}@anchor{1e5} |
64d5610f ML |
12772 | @subsection No_Local_Tagged_Types |
12773 | ||
12774 | ||
12775 | @geindex No_Local_Tagged_Types | |
12776 | ||
12777 | [GNAT] This restriction ensures at compile time that tagged types are only | |
12778 | declared at the library level. | |
12779 | ||
12780 | @node No_Local_Timing_Events,No_Long_Long_Integers,No_Local_Tagged_Types,Partition-Wide Restrictions | |
067d80d8 | 12781 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-local-timing-events}@anchor{1e6} |
64d5610f ML |
12782 | @subsection No_Local_Timing_Events |
12783 | ||
12784 | ||
12785 | @geindex No_Local_Timing_Events | |
12786 | ||
12787 | [RM D.7] All objects of type Ada.Real_Time.Timing_Events.Timing_Event are | |
12788 | declared at the library level. | |
12789 | ||
12790 | @node No_Long_Long_Integers,No_Multiple_Elaboration,No_Local_Timing_Events,Partition-Wide Restrictions | |
067d80d8 | 12791 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-long-long-integers}@anchor{1e7} |
64d5610f ML |
12792 | @subsection No_Long_Long_Integers |
12793 | ||
12794 | ||
12795 | @geindex No_Long_Long_Integers | |
12796 | ||
12797 | [GNAT] This partition-wide restriction forbids any explicit reference to | |
12798 | type Standard.Long_Long_Integer, and also forbids declaring range types whose | |
12799 | implicit base type is Long_Long_Integer, and modular types whose size exceeds | |
12800 | Long_Integer’Size. | |
12801 | ||
12802 | @node No_Multiple_Elaboration,No_Nested_Finalization,No_Long_Long_Integers,Partition-Wide Restrictions | |
067d80d8 | 12803 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-multiple-elaboration}@anchor{1e8} |
64d5610f ML |
12804 | @subsection No_Multiple_Elaboration |
12805 | ||
12806 | ||
12807 | @geindex No_Multiple_Elaboration | |
12808 | ||
12809 | [GNAT] When this restriction is active and the static elaboration model is | |
12810 | used, and -fpreserve-control-flow is not used, the compiler is allowed to | |
12811 | suppress the elaboration counter normally associated with the unit, even if | |
12812 | the unit has elaboration code. This counter is typically used to check for | |
12813 | access before elaboration and to control multiple elaboration attempts. If the | |
12814 | restriction is used, then the situations in which multiple elaboration is | |
12815 | possible, including non-Ada main programs and Stand Alone libraries, are not | |
12816 | permitted and will be diagnosed by the binder. | |
12817 | ||
12818 | @node No_Nested_Finalization,No_Protected_Type_Allocators,No_Multiple_Elaboration,Partition-Wide Restrictions | |
067d80d8 | 12819 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-nested-finalization}@anchor{1e9} |
64d5610f ML |
12820 | @subsection No_Nested_Finalization |
12821 | ||
12822 | ||
12823 | @geindex No_Nested_Finalization | |
12824 | ||
12825 | [RM D.7] All objects requiring finalization are declared at the library level. | |
12826 | ||
12827 | @node No_Protected_Type_Allocators,No_Protected_Types,No_Nested_Finalization,Partition-Wide Restrictions | |
067d80d8 | 12828 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-protected-type-allocators}@anchor{1ea} |
64d5610f ML |
12829 | @subsection No_Protected_Type_Allocators |
12830 | ||
12831 | ||
12832 | @geindex No_Protected_Type_Allocators | |
12833 | ||
12834 | [RM D.7] This restriction ensures at compile time that there are no allocator | |
12835 | expressions that attempt to allocate protected objects. | |
12836 | ||
12837 | @node No_Protected_Types,No_Recursion,No_Protected_Type_Allocators,Partition-Wide Restrictions | |
067d80d8 | 12838 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-protected-types}@anchor{1eb} |
64d5610f ML |
12839 | @subsection No_Protected_Types |
12840 | ||
12841 | ||
12842 | @geindex No_Protected_Types | |
12843 | ||
12844 | [RM H.4] This restriction ensures at compile time that there are no | |
12845 | declarations of protected types or protected objects. | |
12846 | ||
12847 | @node No_Recursion,No_Reentrancy,No_Protected_Types,Partition-Wide Restrictions | |
067d80d8 | 12848 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-recursion}@anchor{1ec} |
64d5610f ML |
12849 | @subsection No_Recursion |
12850 | ||
12851 | ||
12852 | @geindex No_Recursion | |
12853 | ||
12854 | [RM H.4] A program execution is erroneous if a subprogram is invoked as | |
12855 | part of its execution. | |
12856 | ||
12857 | @node No_Reentrancy,No_Relative_Delay,No_Recursion,Partition-Wide Restrictions | |
067d80d8 | 12858 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-reentrancy}@anchor{1ed} |
64d5610f ML |
12859 | @subsection No_Reentrancy |
12860 | ||
12861 | ||
12862 | @geindex No_Reentrancy | |
12863 | ||
12864 | [RM H.4] A program execution is erroneous if a subprogram is executed by | |
12865 | two tasks at the same time. | |
12866 | ||
12867 | @node No_Relative_Delay,No_Requeue_Statements,No_Reentrancy,Partition-Wide Restrictions | |
067d80d8 | 12868 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-relative-delay}@anchor{1ee} |
64d5610f ML |
12869 | @subsection No_Relative_Delay |
12870 | ||
12871 | ||
12872 | @geindex No_Relative_Delay | |
12873 | ||
12874 | [RM D.7] This restriction ensures at compile time that there are no delay | |
12875 | relative statements and prevents expressions such as @code{delay 1.23;} from | |
12876 | appearing in source code. | |
12877 | ||
12878 | @node No_Requeue_Statements,No_Secondary_Stack,No_Relative_Delay,Partition-Wide Restrictions | |
067d80d8 | 12879 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-requeue-statements}@anchor{1ef} |
64d5610f ML |
12880 | @subsection No_Requeue_Statements |
12881 | ||
12882 | ||
12883 | @geindex No_Requeue_Statements | |
12884 | ||
12885 | [RM D.7] This restriction ensures at compile time that no requeue statements | |
12886 | are permitted and prevents keyword @code{requeue} from being used in source | |
12887 | code. | |
12888 | ||
12889 | @geindex No_Requeue | |
12890 | ||
12891 | The restriction @code{No_Requeue} is recognized as a | |
12892 | synonym for @code{No_Requeue_Statements}. This is retained for historical | |
12893 | compatibility purposes (and a warning will be generated for its use if | |
12894 | warnings on oNobsolescent features are activated). | |
12895 | ||
12896 | @node No_Secondary_Stack,No_Select_Statements,No_Requeue_Statements,Partition-Wide Restrictions | |
067d80d8 | 12897 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-secondary-stack}@anchor{1f0} |
64d5610f ML |
12898 | @subsection No_Secondary_Stack |
12899 | ||
12900 | ||
12901 | @geindex No_Secondary_Stack | |
12902 | ||
12903 | [GNAT] This restriction ensures at compile time that the generated code | |
12904 | does not contain any reference to the secondary stack. The secondary | |
12905 | stack is used to implement functions returning unconstrained objects | |
12906 | (arrays or records) on some targets. Suppresses the allocation of | |
12907 | secondary stacks for tasks (excluding the environment task) at run time. | |
12908 | ||
12909 | @node No_Select_Statements,No_Specific_Termination_Handlers,No_Secondary_Stack,Partition-Wide Restrictions | |
067d80d8 | 12910 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-select-statements}@anchor{1f1} |
64d5610f ML |
12911 | @subsection No_Select_Statements |
12912 | ||
12913 | ||
12914 | @geindex No_Select_Statements | |
12915 | ||
12916 | [RM D.7] This restriction ensures at compile time no select statements of any | |
12917 | kind are permitted, that is the keyword @code{select} may not appear. | |
12918 | ||
12919 | @node No_Specific_Termination_Handlers,No_Specification_of_Aspect,No_Select_Statements,Partition-Wide Restrictions | |
067d80d8 | 12920 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-specific-termination-handlers}@anchor{1f2} |
64d5610f ML |
12921 | @subsection No_Specific_Termination_Handlers |
12922 | ||
12923 | ||
12924 | @geindex No_Specific_Termination_Handlers | |
12925 | ||
12926 | [RM D.7] There are no calls to Ada.Task_Termination.Set_Specific_Handler | |
12927 | or to Ada.Task_Termination.Specific_Handler. | |
12928 | ||
12929 | @node No_Specification_of_Aspect,No_Standard_Allocators_After_Elaboration,No_Specific_Termination_Handlers,Partition-Wide Restrictions | |
067d80d8 | 12930 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-specification-of-aspect}@anchor{1f3} |
64d5610f ML |
12931 | @subsection No_Specification_of_Aspect |
12932 | ||
12933 | ||
12934 | @geindex No_Specification_of_Aspect | |
12935 | ||
12936 | [RM 13.12.1] This restriction checks at compile time that no aspect | |
12937 | specification, attribute definition clause, or pragma is given for a | |
12938 | given aspect. | |
12939 | ||
12940 | @node No_Standard_Allocators_After_Elaboration,No_Standard_Storage_Pools,No_Specification_of_Aspect,Partition-Wide Restrictions | |
067d80d8 | 12941 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-standard-allocators-after-elaboration}@anchor{1f4} |
64d5610f ML |
12942 | @subsection No_Standard_Allocators_After_Elaboration |
12943 | ||
12944 | ||
12945 | @geindex No_Standard_Allocators_After_Elaboration | |
12946 | ||
12947 | [RM D.7] Specifies that an allocator using a standard storage pool | |
12948 | should never be evaluated at run time after the elaboration of the | |
12949 | library items of the partition has completed. Otherwise, Storage_Error | |
12950 | is raised. | |
12951 | ||
12952 | @node No_Standard_Storage_Pools,No_Stream_Optimizations,No_Standard_Allocators_After_Elaboration,Partition-Wide Restrictions | |
067d80d8 | 12953 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-standard-storage-pools}@anchor{1f5} |
64d5610f ML |
12954 | @subsection No_Standard_Storage_Pools |
12955 | ||
12956 | ||
12957 | @geindex No_Standard_Storage_Pools | |
12958 | ||
12959 | [GNAT] This restriction ensures at compile time that no access types | |
12960 | use the standard default storage pool. Any access type declared must | |
12961 | have an explicit Storage_Pool attribute defined specifying a | |
12962 | user-defined storage pool. | |
12963 | ||
12964 | @node No_Stream_Optimizations,No_Streams,No_Standard_Storage_Pools,Partition-Wide Restrictions | |
067d80d8 | 12965 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-stream-optimizations}@anchor{1f6} |
64d5610f ML |
12966 | @subsection No_Stream_Optimizations |
12967 | ||
12968 | ||
12969 | @geindex No_Stream_Optimizations | |
12970 | ||
12971 | [GNAT] This restriction affects the performance of stream operations on types | |
12972 | @code{String}, @code{Wide_String} and @code{Wide_Wide_String}. By default, the | |
12973 | compiler uses block reads and writes when manipulating @code{String} objects | |
12974 | due to their superior performance. When this restriction is in effect, the | |
12975 | compiler performs all IO operations on a per-character basis. | |
12976 | ||
12977 | @node No_Streams,No_Tagged_Type_Registration,No_Stream_Optimizations,Partition-Wide Restrictions | |
067d80d8 | 12978 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-streams}@anchor{1f7} |
64d5610f ML |
12979 | @subsection No_Streams |
12980 | ||
12981 | ||
12982 | @geindex No_Streams | |
12983 | ||
12984 | [GNAT] This restriction ensures at compile/bind time that there are no | |
12985 | stream objects created and no use of stream attributes. | |
12986 | This restriction does not forbid dependences on the package | |
12987 | @code{Ada.Streams}. So it is permissible to with | |
12988 | @code{Ada.Streams} (or another package that does so itself) | |
12989 | as long as no actual stream objects are created and no | |
12990 | stream attributes are used. | |
12991 | ||
12992 | Note that the use of restriction allows optimization of tagged types, | |
12993 | since they do not need to worry about dispatching stream operations. | |
12994 | To take maximum advantage of this space-saving optimization, any | |
12995 | unit declaring a tagged type should be compiled with the restriction, | |
12996 | though this is not required. | |
12997 | ||
12998 | @node No_Tagged_Type_Registration,No_Task_Allocators,No_Streams,Partition-Wide Restrictions | |
067d80d8 | 12999 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-tagged-type-registration}@anchor{1f8} |
64d5610f ML |
13000 | @subsection No_Tagged_Type_Registration |
13001 | ||
13002 | ||
13003 | @geindex No_Tagged_Type_Registration | |
13004 | ||
13005 | [GNAT] If this restriction is active, then class-wide streaming | |
13006 | attributes are not supported. In addition, the subprograms in | |
13007 | Ada.Tags are not supported. | |
13008 | If this restriction is active, the generated code is simplified by | |
13009 | omitting the otherwise-required global registration of tagged types when they | |
13010 | are declared. This restriction may be necessary in order to also apply | |
13011 | the No_Elaboration_Code restriction. | |
13012 | ||
13013 | @node No_Task_Allocators,No_Task_At_Interrupt_Priority,No_Tagged_Type_Registration,Partition-Wide Restrictions | |
067d80d8 | 13014 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-allocators}@anchor{1f9} |
64d5610f ML |
13015 | @subsection No_Task_Allocators |
13016 | ||
13017 | ||
13018 | @geindex No_Task_Allocators | |
13019 | ||
13020 | [RM D.7] There are no allocators for task types | |
13021 | or types containing task subcomponents. | |
13022 | ||
13023 | @node No_Task_At_Interrupt_Priority,No_Task_Attributes_Package,No_Task_Allocators,Partition-Wide Restrictions | |
067d80d8 | 13024 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-at-interrupt-priority}@anchor{1fa} |
64d5610f ML |
13025 | @subsection No_Task_At_Interrupt_Priority |
13026 | ||
13027 | ||
13028 | @geindex No_Task_At_Interrupt_Priority | |
13029 | ||
13030 | [GNAT] This restriction ensures at compile time that there is no | |
13031 | Interrupt_Priority aspect or pragma for a task or a task type. As | |
13032 | a consequence, the tasks are always created with a priority below | |
13033 | that an interrupt priority. | |
13034 | ||
13035 | @node No_Task_Attributes_Package,No_Task_Hierarchy,No_Task_At_Interrupt_Priority,Partition-Wide Restrictions | |
067d80d8 | 13036 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-attributes-package}@anchor{1fb} |
64d5610f ML |
13037 | @subsection No_Task_Attributes_Package |
13038 | ||
13039 | ||
13040 | @geindex No_Task_Attributes_Package | |
13041 | ||
13042 | [GNAT] This restriction ensures at compile time that there are no implicit or | |
13043 | explicit dependencies on the package @code{Ada.Task_Attributes}. | |
13044 | ||
13045 | @geindex No_Task_Attributes | |
13046 | ||
13047 | The restriction @code{No_Task_Attributes} is recognized as a synonym | |
13048 | for @code{No_Task_Attributes_Package}. This is retained for historical | |
13049 | compatibility purposes (and a warning will be generated for its use if | |
13050 | warnings on obsolescent features are activated). | |
13051 | ||
13052 | @node No_Task_Hierarchy,No_Task_Termination,No_Task_Attributes_Package,Partition-Wide Restrictions | |
067d80d8 | 13053 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-hierarchy}@anchor{1fc} |
64d5610f ML |
13054 | @subsection No_Task_Hierarchy |
13055 | ||
13056 | ||
13057 | @geindex No_Task_Hierarchy | |
13058 | ||
13059 | [RM D.7] All (non-environment) tasks depend | |
13060 | directly on the environment task of the partition. | |
13061 | ||
13062 | @node No_Task_Termination,No_Tasking,No_Task_Hierarchy,Partition-Wide Restrictions | |
067d80d8 | 13063 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-termination}@anchor{1fd} |
64d5610f ML |
13064 | @subsection No_Task_Termination |
13065 | ||
13066 | ||
13067 | @geindex No_Task_Termination | |
13068 | ||
13069 | [RM D.7] Tasks that terminate are erroneous. | |
13070 | ||
13071 | @node No_Tasking,No_Terminate_Alternatives,No_Task_Termination,Partition-Wide Restrictions | |
067d80d8 | 13072 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-tasking}@anchor{1fe} |
64d5610f ML |
13073 | @subsection No_Tasking |
13074 | ||
13075 | ||
13076 | @geindex No_Tasking | |
13077 | ||
13078 | [GNAT] This restriction prevents the declaration of tasks or task types | |
13079 | throughout the partition. It is similar in effect to the use of | |
13080 | @code{Max_Tasks => 0} except that violations are caught at compile time | |
13081 | and cause an error message to be output either by the compiler or | |
13082 | binder. | |
13083 | ||
13084 | @node No_Terminate_Alternatives,No_Unchecked_Access,No_Tasking,Partition-Wide Restrictions | |
067d80d8 | 13085 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-terminate-alternatives}@anchor{1ff} |
64d5610f ML |
13086 | @subsection No_Terminate_Alternatives |
13087 | ||
13088 | ||
13089 | @geindex No_Terminate_Alternatives | |
13090 | ||
13091 | [RM D.7] There are no selective accepts with terminate alternatives. | |
13092 | ||
13093 | @node No_Unchecked_Access,No_Unchecked_Conversion,No_Terminate_Alternatives,Partition-Wide Restrictions | |
067d80d8 | 13094 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-unchecked-access}@anchor{200} |
64d5610f ML |
13095 | @subsection No_Unchecked_Access |
13096 | ||
13097 | ||
13098 | @geindex No_Unchecked_Access | |
13099 | ||
13100 | [RM H.4] This restriction ensures at compile time that there are no | |
13101 | occurrences of the Unchecked_Access attribute. | |
13102 | ||
13103 | @node No_Unchecked_Conversion,No_Unchecked_Deallocation,No_Unchecked_Access,Partition-Wide Restrictions | |
067d80d8 | 13104 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-unchecked-conversion}@anchor{201} |
64d5610f ML |
13105 | @subsection No_Unchecked_Conversion |
13106 | ||
13107 | ||
13108 | @geindex No_Unchecked_Conversion | |
13109 | ||
13110 | [RM J.13] This restriction ensures at compile time that there are no semantic | |
13111 | dependences on the predefined generic function Unchecked_Conversion. | |
13112 | ||
73918baf | 13113 | @node No_Unchecked_Deallocation,No_Use_Of_Attribute,No_Unchecked_Conversion,Partition-Wide Restrictions |
067d80d8 | 13114 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-unchecked-deallocation}@anchor{202} |
64d5610f ML |
13115 | @subsection No_Unchecked_Deallocation |
13116 | ||
13117 | ||
13118 | @geindex No_Unchecked_Deallocation | |
13119 | ||
13120 | [RM J.13] This restriction ensures at compile time that there are no semantic | |
13121 | dependences on the predefined generic procedure Unchecked_Deallocation. | |
13122 | ||
73918baf VI |
13123 | @node No_Use_Of_Attribute,No_Use_Of_Entity,No_Unchecked_Deallocation,Partition-Wide Restrictions |
13124 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-use-of-attribute}@anchor{203} | |
13125 | @subsection No_Use_Of_Attribute | |
13126 | ||
13127 | ||
13128 | @geindex No_Use_Of_Attribute | |
13129 | ||
13130 | [RM 13.12.1] This is a standard Ada 2012 restriction that is GNAT defined in | |
13131 | earlier versions of Ada. | |
13132 | ||
13133 | @node No_Use_Of_Entity,No_Use_Of_Pragma,No_Use_Of_Attribute,Partition-Wide Restrictions | |
13134 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-use-of-entity}@anchor{204} | |
64d5610f ML |
13135 | @subsection No_Use_Of_Entity |
13136 | ||
13137 | ||
13138 | @geindex No_Use_Of_Entity | |
13139 | ||
13140 | [GNAT] This restriction ensures at compile time that there are no references | |
13141 | to the entity given in the form | |
13142 | ||
13143 | @example | |
13144 | No_Use_Of_Entity => Name | |
13145 | @end example | |
13146 | ||
13147 | where @code{Name} is the fully qualified entity, for example | |
13148 | ||
13149 | @example | |
13150 | No_Use_Of_Entity => Ada.Text_IO.Put_Line | |
13151 | @end example | |
13152 | ||
73918baf VI |
13153 | @node No_Use_Of_Pragma,Pure_Barriers,No_Use_Of_Entity,Partition-Wide Restrictions |
13154 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-use-of-pragma}@anchor{205} | |
13155 | @subsection No_Use_Of_Pragma | |
13156 | ||
13157 | ||
13158 | @geindex No_Use_Of_Pragma | |
13159 | ||
13160 | [RM 13.12.1] This is a standard Ada 2012 restriction that is GNAT defined in | |
13161 | earlier versions of Ada. | |
13162 | ||
13163 | @node Pure_Barriers,Simple_Barriers,No_Use_Of_Pragma,Partition-Wide Restrictions | |
13164 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions pure-barriers}@anchor{206} | |
64d5610f ML |
13165 | @subsection Pure_Barriers |
13166 | ||
13167 | ||
13168 | @geindex Pure_Barriers | |
13169 | ||
13170 | [GNAT] This restriction ensures at compile time that protected entry | |
13171 | barriers are restricted to: | |
13172 | ||
13173 | ||
13174 | @itemize * | |
13175 | ||
13176 | @item | |
13177 | components of the protected object (excluding selection from dereferences), | |
13178 | ||
13179 | @item | |
13180 | constant declarations, | |
13181 | ||
13182 | @item | |
13183 | named numbers, | |
13184 | ||
13185 | @item | |
13186 | enumeration literals, | |
13187 | ||
13188 | @item | |
13189 | integer literals, | |
13190 | ||
13191 | @item | |
13192 | real literals, | |
13193 | ||
13194 | @item | |
13195 | character literals, | |
13196 | ||
13197 | @item | |
13198 | implicitly defined comparison operators, | |
13199 | ||
13200 | @item | |
13201 | uses of the Standard.”not” operator, | |
13202 | ||
13203 | @item | |
13204 | short-circuit operator, | |
13205 | ||
13206 | @item | |
13207 | the Count attribute | |
13208 | @end itemize | |
13209 | ||
13210 | This restriction is a relaxation of the Simple_Barriers restriction, | |
13211 | but still ensures absence of side effects, exceptions, and recursion | |
13212 | during the evaluation of the barriers. | |
13213 | ||
13214 | @node Simple_Barriers,Static_Priorities,Pure_Barriers,Partition-Wide Restrictions | |
73918baf | 13215 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions simple-barriers}@anchor{207} |
64d5610f ML |
13216 | @subsection Simple_Barriers |
13217 | ||
13218 | ||
13219 | @geindex Simple_Barriers | |
13220 | ||
13221 | [RM D.7] This restriction ensures at compile time that barriers in entry | |
13222 | declarations for protected types are restricted to either static boolean | |
13223 | expressions or references to simple boolean variables defined in the private | |
13224 | part of the protected type. No other form of entry barriers is permitted. | |
13225 | ||
13226 | @geindex Boolean_Entry_Barriers | |
13227 | ||
13228 | The restriction @code{Boolean_Entry_Barriers} is recognized as a | |
13229 | synonym for @code{Simple_Barriers}. This is retained for historical | |
13230 | compatibility purposes (and a warning will be generated for its use if | |
13231 | warnings on obsolescent features are activated). | |
13232 | ||
13233 | @node Static_Priorities,Static_Storage_Size,Simple_Barriers,Partition-Wide Restrictions | |
73918baf | 13234 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions static-priorities}@anchor{208} |
64d5610f ML |
13235 | @subsection Static_Priorities |
13236 | ||
13237 | ||
13238 | @geindex Static_Priorities | |
13239 | ||
13240 | [GNAT] This restriction ensures at compile time that all priority expressions | |
13241 | are static, and that there are no dependences on the package | |
13242 | @code{Ada.Dynamic_Priorities}. | |
13243 | ||
13244 | @node Static_Storage_Size,,Static_Priorities,Partition-Wide Restrictions | |
73918baf | 13245 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions static-storage-size}@anchor{209} |
64d5610f ML |
13246 | @subsection Static_Storage_Size |
13247 | ||
13248 | ||
13249 | @geindex Static_Storage_Size | |
13250 | ||
13251 | [GNAT] This restriction ensures at compile time that any expression appearing | |
13252 | in a Storage_Size pragma or attribute definition clause is static. | |
13253 | ||
13254 | @node Program Unit Level Restrictions,,Partition-Wide Restrictions,Standard and Implementation Defined Restrictions | |
73918baf | 13255 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions id3}@anchor{20a}@anchor{gnat_rm/standard_and_implementation_defined_restrictions program-unit-level-restrictions}@anchor{20b} |
64d5610f ML |
13256 | @section Program Unit Level Restrictions |
13257 | ||
13258 | ||
13259 | The second set of restriction identifiers | |
13260 | does not require partition-wide consistency. | |
13261 | The restriction may be enforced for a single | |
13262 | compilation unit without any effect on any of the | |
13263 | other compilation units in the partition. | |
13264 | ||
13265 | @menu | |
13266 | * No_Elaboration_Code:: | |
13267 | * No_Dynamic_Accessibility_Checks:: | |
13268 | * No_Dynamic_Sized_Objects:: | |
13269 | * No_Entry_Queue:: | |
13270 | * No_Implementation_Aspect_Specifications:: | |
13271 | * No_Implementation_Attributes:: | |
13272 | * No_Implementation_Identifiers:: | |
13273 | * No_Implementation_Pragmas:: | |
13274 | * No_Implementation_Restrictions:: | |
13275 | * No_Implementation_Units:: | |
13276 | * No_Implicit_Aliasing:: | |
13277 | * No_Implicit_Loops:: | |
13278 | * No_Obsolescent_Features:: | |
13279 | * No_Wide_Characters:: | |
13280 | * Static_Dispatch_Tables:: | |
13281 | * SPARK_05:: | |
13282 | ||
13283 | @end menu | |
13284 | ||
13285 | @node No_Elaboration_Code,No_Dynamic_Accessibility_Checks,,Program Unit Level Restrictions | |
73918baf | 13286 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-elaboration-code}@anchor{20c} |
64d5610f ML |
13287 | @subsection No_Elaboration_Code |
13288 | ||
13289 | ||
13290 | @geindex No_Elaboration_Code | |
13291 | ||
13292 | [GNAT] This restriction ensures at compile time that no elaboration code is | |
13293 | generated. Note that this is not the same condition as is enforced | |
13294 | by pragma @code{Preelaborate}. There are cases in which pragma | |
13295 | @code{Preelaborate} still permits code to be generated (e.g., code | |
13296 | to initialize a large array to all zeroes), and there are cases of units | |
13297 | which do not meet the requirements for pragma @code{Preelaborate}, | |
13298 | but for which no elaboration code is generated. Generally, it is | |
13299 | the case that preelaborable units will meet the restrictions, with | |
13300 | the exception of large aggregates initialized with an others_clause, | |
13301 | and exception declarations (which generate calls to a run-time | |
13302 | registry procedure). This restriction is enforced on | |
13303 | a unit by unit basis, it need not be obeyed consistently | |
13304 | throughout a partition. | |
13305 | ||
13306 | In the case of aggregates with others, if the aggregate has a dynamic | |
13307 | size, there is no way to eliminate the elaboration code (such dynamic | |
13308 | bounds would be incompatible with @code{Preelaborate} in any case). If | |
13309 | the bounds are static, then use of this restriction actually modifies | |
13310 | the code choice of the compiler to avoid generating a loop, and instead | |
13311 | generate the aggregate statically if possible, no matter how many times | |
13312 | the data for the others clause must be repeatedly generated. | |
13313 | ||
13314 | It is not possible to precisely document | |
13315 | the constructs which are compatible with this restriction, since, | |
13316 | unlike most other restrictions, this is not a restriction on the | |
13317 | source code, but a restriction on the generated object code. For | |
13318 | example, if the source contains a declaration: | |
13319 | ||
13320 | @example | |
13321 | Val : constant Integer := X; | |
13322 | @end example | |
13323 | ||
13324 | where X is not a static constant, it may be possible, depending | |
13325 | on complex optimization circuitry, for the compiler to figure | |
13326 | out the value of X at compile time, in which case this initialization | |
13327 | can be done by the loader, and requires no initialization code. It | |
13328 | is not possible to document the precise conditions under which the | |
13329 | optimizer can figure this out. | |
13330 | ||
13331 | Note that this the implementation of this restriction requires full | |
13332 | code generation. If it is used in conjunction with “semantics only” | |
13333 | checking, then some cases of violations may be missed. | |
13334 | ||
13335 | When this restriction is active, we are not requesting control-flow | |
13336 | preservation with -fpreserve-control-flow, and the static elaboration model is | |
13337 | used, the compiler is allowed to suppress the elaboration counter normally | |
13338 | associated with the unit. This counter is typically used to check for access | |
13339 | before elaboration and to control multiple elaboration attempts. | |
13340 | ||
13341 | @node No_Dynamic_Accessibility_Checks,No_Dynamic_Sized_Objects,No_Elaboration_Code,Program Unit Level Restrictions | |
73918baf | 13342 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dynamic-accessibility-checks}@anchor{20d} |
64d5610f ML |
13343 | @subsection No_Dynamic_Accessibility_Checks |
13344 | ||
13345 | ||
13346 | @geindex No_Dynamic_Accessibility_Checks | |
13347 | ||
13348 | [GNAT] No dynamic accessibility checks are generated when this restriction is | |
13349 | in effect. Instead, dangling references are prevented via more conservative | |
13350 | compile-time checking. More specifically, existing compile-time checks are | |
13351 | enforced but with more conservative assumptions about the accessibility levels | |
13352 | of the relevant entities. These conservative assumptions eliminate the need for | |
13353 | dynamic accessibility checks. | |
13354 | ||
13355 | These new rules for computing (at compile-time) the accessibility level of an | |
13356 | anonymous access type T are as follows: | |
13357 | ||
13358 | ||
13359 | @itemize * | |
13360 | ||
13361 | @item | |
13362 | If T is a function result type then, from the caller’s perspective, its level | |
13363 | is that of the innermost master enclosing the function call. From the callee’s | |
13364 | perspective, the level of parameters and local variables of the callee is | |
13365 | statically deeper than the level of T. | |
13366 | ||
13367 | For any other accessibility level L such that the level of parameters and local | |
13368 | variables of the callee is statically deeper than L, the level of T (from the | |
13369 | callee’s perspective) is also statically deeper than L. | |
13370 | ||
13371 | @item | |
13372 | If T is the type of a formal parameter then, from the caller’s perspective, | |
13373 | its level is at least as deep as that of the type of the corresponding actual | |
13374 | parameter (whatever that actual parameter might be). From the callee’s | |
13375 | perspective, the level of parameters and local variables of the callee is | |
13376 | statically deeper than the level of T. | |
13377 | ||
13378 | @item | |
13379 | If T is the type of a discriminant then its level is that of the discriminated | |
13380 | type. | |
13381 | ||
13382 | @item | |
13383 | If T is the type of a stand-alone object then its level is the level of the | |
13384 | object. | |
13385 | ||
13386 | @item | |
13387 | In all other cases, the level of T is as defined by the existing rules of Ada. | |
13388 | @end itemize | |
13389 | ||
13390 | @node No_Dynamic_Sized_Objects,No_Entry_Queue,No_Dynamic_Accessibility_Checks,Program Unit Level Restrictions | |
73918baf | 13391 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dynamic-sized-objects}@anchor{20e} |
64d5610f ML |
13392 | @subsection No_Dynamic_Sized_Objects |
13393 | ||
13394 | ||
13395 | @geindex No_Dynamic_Sized_Objects | |
13396 | ||
13397 | [GNAT] This restriction disallows certain constructs that might lead to the | |
13398 | creation of dynamic-sized composite objects (or array or discriminated type). | |
13399 | An array subtype indication is illegal if the bounds are not static | |
13400 | or references to discriminants of an enclosing type. | |
13401 | A discriminated subtype indication is illegal if the type has | |
13402 | discriminant-dependent array components or a variant part, and the | |
13403 | discriminants are not static. In addition, array and record aggregates are | |
13404 | illegal in corresponding cases. Note that this restriction does not forbid | |
13405 | access discriminants. It is often a good idea to combine this restriction | |
13406 | with No_Secondary_Stack. | |
13407 | ||
13408 | @node No_Entry_Queue,No_Implementation_Aspect_Specifications,No_Dynamic_Sized_Objects,Program Unit Level Restrictions | |
73918baf | 13409 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-entry-queue}@anchor{20f} |
64d5610f ML |
13410 | @subsection No_Entry_Queue |
13411 | ||
13412 | ||
13413 | @geindex No_Entry_Queue | |
13414 | ||
13415 | [GNAT] This restriction is a declaration that any protected entry compiled in | |
13416 | the scope of the restriction has at most one task waiting on the entry | |
13417 | at any one time, and so no queue is required. This restriction is not | |
13418 | checked at compile time. A program execution is erroneous if an attempt | |
13419 | is made to queue a second task on such an entry. | |
13420 | ||
13421 | @node No_Implementation_Aspect_Specifications,No_Implementation_Attributes,No_Entry_Queue,Program Unit Level Restrictions | |
73918baf | 13422 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-aspect-specifications}@anchor{210} |
64d5610f ML |
13423 | @subsection No_Implementation_Aspect_Specifications |
13424 | ||
13425 | ||
13426 | @geindex No_Implementation_Aspect_Specifications | |
13427 | ||
13428 | [RM 13.12.1] This restriction checks at compile time that no | |
13429 | GNAT-defined aspects are present. With this restriction, the only | |
13430 | aspects that can be used are those defined in the Ada Reference Manual. | |
13431 | ||
13432 | @node No_Implementation_Attributes,No_Implementation_Identifiers,No_Implementation_Aspect_Specifications,Program Unit Level Restrictions | |
73918baf | 13433 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-attributes}@anchor{211} |
64d5610f ML |
13434 | @subsection No_Implementation_Attributes |
13435 | ||
13436 | ||
13437 | @geindex No_Implementation_Attributes | |
13438 | ||
13439 | [RM 13.12.1] This restriction checks at compile time that no | |
13440 | GNAT-defined attributes are present. With this restriction, the only | |
13441 | attributes that can be used are those defined in the Ada Reference | |
13442 | Manual. | |
13443 | ||
13444 | @node No_Implementation_Identifiers,No_Implementation_Pragmas,No_Implementation_Attributes,Program Unit Level Restrictions | |
73918baf | 13445 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-identifiers}@anchor{212} |
64d5610f ML |
13446 | @subsection No_Implementation_Identifiers |
13447 | ||
13448 | ||
13449 | @geindex No_Implementation_Identifiers | |
13450 | ||
13451 | [RM 13.12.1] This restriction checks at compile time that no | |
13452 | implementation-defined identifiers (marked with pragma Implementation_Defined) | |
13453 | occur within language-defined packages. | |
13454 | ||
13455 | @node No_Implementation_Pragmas,No_Implementation_Restrictions,No_Implementation_Identifiers,Program Unit Level Restrictions | |
73918baf | 13456 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-pragmas}@anchor{213} |
64d5610f ML |
13457 | @subsection No_Implementation_Pragmas |
13458 | ||
13459 | ||
13460 | @geindex No_Implementation_Pragmas | |
13461 | ||
13462 | [RM 13.12.1] This restriction checks at compile time that no | |
13463 | GNAT-defined pragmas are present. With this restriction, the only | |
13464 | pragmas that can be used are those defined in the Ada Reference Manual. | |
13465 | ||
13466 | @node No_Implementation_Restrictions,No_Implementation_Units,No_Implementation_Pragmas,Program Unit Level Restrictions | |
73918baf | 13467 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-restrictions}@anchor{214} |
64d5610f ML |
13468 | @subsection No_Implementation_Restrictions |
13469 | ||
13470 | ||
13471 | @geindex No_Implementation_Restrictions | |
13472 | ||
13473 | [GNAT] This restriction checks at compile time that no GNAT-defined restriction | |
13474 | identifiers (other than @code{No_Implementation_Restrictions} itself) | |
13475 | are present. With this restriction, the only other restriction identifiers | |
13476 | that can be used are those defined in the Ada Reference Manual. | |
13477 | ||
13478 | @node No_Implementation_Units,No_Implicit_Aliasing,No_Implementation_Restrictions,Program Unit Level Restrictions | |
73918baf | 13479 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-units}@anchor{215} |
64d5610f ML |
13480 | @subsection No_Implementation_Units |
13481 | ||
13482 | ||
13483 | @geindex No_Implementation_Units | |
13484 | ||
13485 | [RM 13.12.1] This restriction checks at compile time that there is no | |
13486 | mention in the context clause of any implementation-defined descendants | |
13487 | of packages Ada, Interfaces, or System. | |
13488 | ||
13489 | @node No_Implicit_Aliasing,No_Implicit_Loops,No_Implementation_Units,Program Unit Level Restrictions | |
73918baf | 13490 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-aliasing}@anchor{216} |
64d5610f ML |
13491 | @subsection No_Implicit_Aliasing |
13492 | ||
13493 | ||
13494 | @geindex No_Implicit_Aliasing | |
13495 | ||
13496 | [GNAT] This restriction, which is not required to be partition-wide consistent, | |
13497 | requires an explicit aliased keyword for an object to which ‘Access, | |
13498 | ‘Unchecked_Access, or ‘Address is applied, and forbids entirely the use of | |
13499 | the ‘Unrestricted_Access attribute for objects. Note: the reason that | |
13500 | Unrestricted_Access is forbidden is that it would require the prefix | |
13501 | to be aliased, and in such cases, it can always be replaced by | |
13502 | the standard attribute Unchecked_Access which is preferable. | |
13503 | ||
13504 | @node No_Implicit_Loops,No_Obsolescent_Features,No_Implicit_Aliasing,Program Unit Level Restrictions | |
73918baf | 13505 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-loops}@anchor{217} |
64d5610f ML |
13506 | @subsection No_Implicit_Loops |
13507 | ||
13508 | ||
13509 | @geindex No_Implicit_Loops | |
13510 | ||
13511 | [GNAT] This restriction ensures that the generated code of the unit marked | |
13512 | with this restriction does not contain any implicit @code{for} loops, either by | |
13513 | modifying the generated code where possible, or by rejecting any construct | |
13514 | that would otherwise generate an implicit @code{for} loop. If this restriction is | |
13515 | active, it is possible to build large array aggregates with all static | |
13516 | components without generating an intermediate temporary, and without generating | |
13517 | a loop to initialize individual components. Otherwise, a loop is created for | |
13518 | arrays larger than about 5000 scalar components. Note that if this restriction | |
13519 | is set in the spec of a package, it will not apply to its body. | |
13520 | ||
13521 | @node No_Obsolescent_Features,No_Wide_Characters,No_Implicit_Loops,Program Unit Level Restrictions | |
73918baf | 13522 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-obsolescent-features}@anchor{218} |
64d5610f ML |
13523 | @subsection No_Obsolescent_Features |
13524 | ||
13525 | ||
13526 | @geindex No_Obsolescent_Features | |
13527 | ||
13528 | [RM 13.12.1] This restriction checks at compile time that no obsolescent | |
13529 | features are used, as defined in Annex J of the Ada Reference Manual. | |
13530 | ||
13531 | @node No_Wide_Characters,Static_Dispatch_Tables,No_Obsolescent_Features,Program Unit Level Restrictions | |
73918baf | 13532 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-wide-characters}@anchor{219} |
64d5610f ML |
13533 | @subsection No_Wide_Characters |
13534 | ||
13535 | ||
13536 | @geindex No_Wide_Characters | |
13537 | ||
13538 | [GNAT] This restriction ensures at compile time that no uses of the types | |
13539 | @code{Wide_Character} or @code{Wide_String} or corresponding wide | |
13540 | wide types | |
13541 | appear, and that no wide or wide wide string or character literals | |
13542 | appear in the program (that is literals representing characters not in | |
13543 | type @code{Character}). | |
13544 | ||
13545 | @node Static_Dispatch_Tables,SPARK_05,No_Wide_Characters,Program Unit Level Restrictions | |
73918baf | 13546 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions static-dispatch-tables}@anchor{21a} |
64d5610f ML |
13547 | @subsection Static_Dispatch_Tables |
13548 | ||
13549 | ||
13550 | @geindex Static_Dispatch_Tables | |
13551 | ||
13552 | [GNAT] This restriction checks at compile time that all the artifacts | |
13553 | associated with dispatch tables can be placed in read-only memory. | |
13554 | ||
13555 | @node SPARK_05,,Static_Dispatch_Tables,Program Unit Level Restrictions | |
73918baf | 13556 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions spark-05}@anchor{21b} |
64d5610f ML |
13557 | @subsection SPARK_05 |
13558 | ||
13559 | ||
13560 | @geindex SPARK_05 | |
13561 | ||
13562 | [GNAT] This restriction no longer has any effect and is superseded by | |
13563 | SPARK 2014, whose restrictions are checked by the tool GNATprove. To check that | |
13564 | a codebase respects SPARK 2014 restrictions, mark the code with pragma or | |
13565 | aspect @code{SPARK_Mode}, and run the tool GNATprove at Stone assurance level, as | |
13566 | follows: | |
13567 | ||
13568 | @example | |
13569 | gnatprove -P project.gpr --mode=stone | |
13570 | @end example | |
13571 | ||
13572 | or equivalently: | |
13573 | ||
13574 | @example | |
13575 | gnatprove -P project.gpr --mode=check_all | |
13576 | @end example | |
13577 | ||
13578 | @node Implementation Advice,Implementation Defined Characteristics,Standard and Implementation Defined Restrictions,Top | |
73918baf | 13579 | @anchor{gnat_rm/implementation_advice doc}@anchor{21c}@anchor{gnat_rm/implementation_advice id1}@anchor{21d}@anchor{gnat_rm/implementation_advice implementation-advice}@anchor{a} |
64d5610f ML |
13580 | @chapter Implementation Advice |
13581 | ||
13582 | ||
13583 | The main text of the Ada Reference Manual describes the required | |
13584 | behavior of all Ada compilers, and the GNAT compiler conforms to | |
13585 | these requirements. | |
13586 | ||
13587 | In addition, there are sections throughout the Ada Reference Manual headed | |
13588 | by the phrase ‘Implementation advice’. These sections are not normative, | |
13589 | i.e., they do not specify requirements that all compilers must | |
13590 | follow. Rather they provide advice on generally desirable behavior. | |
13591 | They are not requirements, because they describe behavior that cannot | |
13592 | be provided on all systems, or may be undesirable on some systems. | |
13593 | ||
13594 | As far as practical, GNAT follows the implementation advice in | |
13595 | the Ada Reference Manual. Each such RM section corresponds to a section | |
13596 | in this chapter whose title specifies the | |
13597 | RM section number and paragraph number and the subject of | |
13598 | the advice. The contents of each section consists of the RM text within | |
13599 | quotation marks, | |
13600 | followed by the GNAT interpretation of the advice. Most often, this simply says | |
13601 | ‘followed’, which means that GNAT follows the advice. However, in a | |
13602 | number of cases, GNAT deliberately deviates from this advice, in which | |
13603 | case the text describes what GNAT does and why. | |
13604 | ||
13605 | @geindex Error detection | |
13606 | ||
13607 | @menu | |
13608 | * RM 1.1.3(20); Error Detection: RM 1 1 3 20 Error Detection. | |
13609 | * RM 1.1.3(31); Child Units: RM 1 1 3 31 Child Units. | |
13610 | * RM 1.1.5(12); Bounded Errors: RM 1 1 5 12 Bounded Errors. | |
13611 | * RM 2.8(16); Pragmas: RM 2 8 16 Pragmas. | |
13612 | * RM 2.8(17-19); Pragmas: RM 2 8 17-19 Pragmas. | |
13613 | * RM 3.5.2(5); Alternative Character Sets: RM 3 5 2 5 Alternative Character Sets. | |
13614 | * RM 3.5.4(28); Integer Types: RM 3 5 4 28 Integer Types. | |
13615 | * RM 3.5.4(29); Integer Types: RM 3 5 4 29 Integer Types. | |
13616 | * RM 3.5.5(8); Enumeration Values: RM 3 5 5 8 Enumeration Values. | |
13617 | * RM 3.5.7(17); Float Types: RM 3 5 7 17 Float Types. | |
13618 | * RM 3.6.2(11); Multidimensional Arrays: RM 3 6 2 11 Multidimensional Arrays. | |
13619 | * RM 9.6(30-31); Duration’Small: RM 9 6 30-31 Duration’Small. | |
13620 | * RM 10.2.1(12); Consistent Representation: RM 10 2 1 12 Consistent Representation. | |
13621 | * RM 11.4.1(19); Exception Information: RM 11 4 1 19 Exception Information. | |
13622 | * RM 11.5(28); Suppression of Checks: RM 11 5 28 Suppression of Checks. | |
13623 | * RM 13.1 (21-24); Representation Clauses: RM 13 1 21-24 Representation Clauses. | |
13624 | * RM 13.2(6-8); Packed Types: RM 13 2 6-8 Packed Types. | |
13625 | * RM 13.3(14-19); Address Clauses: RM 13 3 14-19 Address Clauses. | |
13626 | * RM 13.3(29-35); Alignment Clauses: RM 13 3 29-35 Alignment Clauses. | |
13627 | * RM 13.3(42-43); Size Clauses: RM 13 3 42-43 Size Clauses. | |
13628 | * RM 13.3(50-56); Size Clauses: RM 13 3 50-56 Size Clauses. | |
13629 | * RM 13.3(71-73); Component Size Clauses: RM 13 3 71-73 Component Size Clauses. | |
13630 | * RM 13.4(9-10); Enumeration Representation Clauses: RM 13 4 9-10 Enumeration Representation Clauses. | |
13631 | * RM 13.5.1(17-22); Record Representation Clauses: RM 13 5 1 17-22 Record Representation Clauses. | |
13632 | * RM 13.5.2(5); Storage Place Attributes: RM 13 5 2 5 Storage Place Attributes. | |
13633 | * RM 13.5.3(7-8); Bit Ordering: RM 13 5 3 7-8 Bit Ordering. | |
13634 | * RM 13.7(37); Address as Private: RM 13 7 37 Address as Private. | |
13635 | * RM 13.7.1(16); Address Operations: RM 13 7 1 16 Address Operations. | |
13636 | * RM 13.9(14-17); Unchecked Conversion: RM 13 9 14-17 Unchecked Conversion. | |
13637 | * RM 13.11(23-25); Implicit Heap Usage: RM 13 11 23-25 Implicit Heap Usage. | |
13638 | * RM 13.11.2(17); Unchecked Deallocation: RM 13 11 2 17 Unchecked Deallocation. | |
13639 | * RM 13.13.2(1.6); Stream Oriented Attributes: RM 13 13 2 1 6 Stream Oriented Attributes. | |
13640 | * RM A.1(52); Names of Predefined Numeric Types: RM A 1 52 Names of Predefined Numeric Types. | |
13641 | * RM A.3.2(49); Ada.Characters.Handling: RM A 3 2 49 Ada Characters Handling. | |
13642 | * RM A.4.4(106); Bounded-Length String Handling: RM A 4 4 106 Bounded-Length String Handling. | |
13643 | * RM A.5.2(46-47); Random Number Generation: RM A 5 2 46-47 Random Number Generation. | |
13644 | * RM A.10.7(23); Get_Immediate: RM A 10 7 23 Get_Immediate. | |
13645 | * RM A.18; Containers: RM A 18 Containers. | |
13646 | * RM B.1(39-41); Pragma Export: RM B 1 39-41 Pragma Export. | |
13647 | * RM B.2(12-13); Package Interfaces: RM B 2 12-13 Package Interfaces. | |
13648 | * RM B.3(63-71); Interfacing with C: RM B 3 63-71 Interfacing with C. | |
13649 | * RM B.4(95-98); Interfacing with COBOL: RM B 4 95-98 Interfacing with COBOL. | |
13650 | * RM B.5(22-26); Interfacing with Fortran: RM B 5 22-26 Interfacing with Fortran. | |
13651 | * RM C.1(3-5); Access to Machine Operations: RM C 1 3-5 Access to Machine Operations. | |
13652 | * RM C.1(10-16); Access to Machine Operations: RM C 1 10-16 Access to Machine Operations. | |
13653 | * RM C.3(28); Interrupt Support: RM C 3 28 Interrupt Support. | |
13654 | * RM C.3.1(20-21); Protected Procedure Handlers: RM C 3 1 20-21 Protected Procedure Handlers. | |
13655 | * RM C.3.2(25); Package Interrupts: RM C 3 2 25 Package Interrupts. | |
13656 | * RM C.4(14); Pre-elaboration Requirements: RM C 4 14 Pre-elaboration Requirements. | |
13657 | * RM C.5(8); Pragma Discard_Names: RM C 5 8 Pragma Discard_Names. | |
13658 | * RM C.7.2(30); The Package Task_Attributes: RM C 7 2 30 The Package Task_Attributes. | |
13659 | * RM D.3(17); Locking Policies: RM D 3 17 Locking Policies. | |
13660 | * RM D.4(16); Entry Queuing Policies: RM D 4 16 Entry Queuing Policies. | |
13661 | * RM D.6(9-10); Preemptive Abort: RM D 6 9-10 Preemptive Abort. | |
13662 | * RM D.7(21); Tasking Restrictions: RM D 7 21 Tasking Restrictions. | |
13663 | * RM D.8(47-49); Monotonic Time: RM D 8 47-49 Monotonic Time. | |
13664 | * RM E.5(28-29); Partition Communication Subsystem: RM E 5 28-29 Partition Communication Subsystem. | |
13665 | * RM F(7); COBOL Support: RM F 7 COBOL Support. | |
13666 | * RM F.1(2); Decimal Radix Support: RM F 1 2 Decimal Radix Support. | |
13667 | * RM G; Numerics: RM G Numerics. | |
13668 | * RM G.1.1(56-58); Complex Types: RM G 1 1 56-58 Complex Types. | |
13669 | * RM G.1.2(49); Complex Elementary Functions: RM G 1 2 49 Complex Elementary Functions. | |
13670 | * RM G.2.4(19); Accuracy Requirements: RM G 2 4 19 Accuracy Requirements. | |
13671 | * RM G.2.6(15); Complex Arithmetic Accuracy: RM G 2 6 15 Complex Arithmetic Accuracy. | |
13672 | * RM H.6(15/2); Pragma Partition_Elaboration_Policy: RM H 6 15/2 Pragma Partition_Elaboration_Policy. | |
13673 | ||
13674 | @end menu | |
13675 | ||
13676 | @node RM 1 1 3 20 Error Detection,RM 1 1 3 31 Child Units,,Implementation Advice | |
73918baf | 13677 | @anchor{gnat_rm/implementation_advice rm-1-1-3-20-error-detection}@anchor{21e} |
64d5610f ML |
13678 | @section RM 1.1.3(20): Error Detection |
13679 | ||
13680 | ||
13681 | @quotation | |
13682 | ||
13683 | “If an implementation detects the use of an unsupported Specialized Needs | |
13684 | Annex feature at run time, it should raise @code{Program_Error} if | |
13685 | feasible.” | |
13686 | @end quotation | |
13687 | ||
13688 | Not relevant. All specialized needs annex features are either supported, | |
13689 | or diagnosed at compile time. | |
13690 | ||
13691 | @geindex Child Units | |
13692 | ||
13693 | @node RM 1 1 3 31 Child Units,RM 1 1 5 12 Bounded Errors,RM 1 1 3 20 Error Detection,Implementation Advice | |
73918baf | 13694 | @anchor{gnat_rm/implementation_advice rm-1-1-3-31-child-units}@anchor{21f} |
64d5610f ML |
13695 | @section RM 1.1.3(31): Child Units |
13696 | ||
13697 | ||
13698 | @quotation | |
13699 | ||
13700 | “If an implementation wishes to provide implementation-defined | |
13701 | extensions to the functionality of a language-defined library unit, it | |
13702 | should normally do so by adding children to the library unit.” | |
13703 | @end quotation | |
13704 | ||
13705 | Followed. | |
13706 | ||
13707 | @geindex Bounded errors | |
13708 | ||
13709 | @node RM 1 1 5 12 Bounded Errors,RM 2 8 16 Pragmas,RM 1 1 3 31 Child Units,Implementation Advice | |
73918baf | 13710 | @anchor{gnat_rm/implementation_advice rm-1-1-5-12-bounded-errors}@anchor{220} |
64d5610f ML |
13711 | @section RM 1.1.5(12): Bounded Errors |
13712 | ||
13713 | ||
13714 | @quotation | |
13715 | ||
13716 | “If an implementation detects a bounded error or erroneous | |
13717 | execution, it should raise @code{Program_Error}.” | |
13718 | @end quotation | |
13719 | ||
13720 | Followed in all cases in which the implementation detects a bounded | |
13721 | error or erroneous execution. Not all such situations are detected at | |
13722 | runtime. | |
13723 | ||
13724 | @geindex Pragmas | |
13725 | ||
13726 | @node RM 2 8 16 Pragmas,RM 2 8 17-19 Pragmas,RM 1 1 5 12 Bounded Errors,Implementation Advice | |
73918baf | 13727 | @anchor{gnat_rm/implementation_advice id2}@anchor{221}@anchor{gnat_rm/implementation_advice rm-2-8-16-pragmas}@anchor{222} |
64d5610f ML |
13728 | @section RM 2.8(16): Pragmas |
13729 | ||
13730 | ||
13731 | @quotation | |
13732 | ||
13733 | “Normally, implementation-defined pragmas should have no semantic effect | |
13734 | for error-free programs; that is, if the implementation-defined pragmas | |
13735 | are removed from a working program, the program should still be legal, | |
13736 | and should still have the same semantics.” | |
13737 | @end quotation | |
13738 | ||
13739 | The following implementation defined pragmas are exceptions to this | |
13740 | rule: | |
13741 | ||
13742 | ||
13743 | @multitable {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxx} | |
13744 | @headitem | |
13745 | ||
13746 | Pragma | |
13747 | ||
13748 | @tab | |
13749 | ||
13750 | Explanation | |
13751 | ||
13752 | @item | |
13753 | ||
13754 | `Abort_Defer' | |
13755 | ||
13756 | @tab | |
13757 | ||
13758 | Affects semantics | |
13759 | ||
13760 | @item | |
13761 | ||
13762 | `Ada_83' | |
13763 | ||
13764 | @tab | |
13765 | ||
13766 | Affects legality | |
13767 | ||
13768 | @item | |
13769 | ||
13770 | `Assert' | |
13771 | ||
13772 | @tab | |
13773 | ||
13774 | Affects semantics | |
13775 | ||
13776 | @item | |
13777 | ||
13778 | `CPP_Class' | |
13779 | ||
13780 | @tab | |
13781 | ||
13782 | Affects semantics | |
13783 | ||
13784 | @item | |
13785 | ||
13786 | `CPP_Constructor' | |
13787 | ||
13788 | @tab | |
13789 | ||
13790 | Affects semantics | |
13791 | ||
13792 | @item | |
13793 | ||
13794 | `Debug' | |
13795 | ||
13796 | @tab | |
13797 | ||
13798 | Affects semantics | |
13799 | ||
13800 | @item | |
13801 | ||
13802 | `Interface_Name' | |
13803 | ||
13804 | @tab | |
13805 | ||
13806 | Affects semantics | |
13807 | ||
13808 | @item | |
13809 | ||
13810 | `Machine_Attribute' | |
13811 | ||
13812 | @tab | |
13813 | ||
13814 | Affects semantics | |
13815 | ||
13816 | @item | |
13817 | ||
13818 | `Unimplemented_Unit' | |
13819 | ||
13820 | @tab | |
13821 | ||
13822 | Affects legality | |
13823 | ||
13824 | @item | |
13825 | ||
13826 | `Unchecked_Union' | |
13827 | ||
13828 | @tab | |
13829 | ||
13830 | Affects semantics | |
13831 | ||
13832 | @end multitable | |
13833 | ||
13834 | ||
13835 | In each of the above cases, it is essential to the purpose of the pragma | |
13836 | that this advice not be followed. For details see | |
13837 | @ref{7,,Implementation Defined Pragmas}. | |
13838 | ||
13839 | @node RM 2 8 17-19 Pragmas,RM 3 5 2 5 Alternative Character Sets,RM 2 8 16 Pragmas,Implementation Advice | |
73918baf | 13840 | @anchor{gnat_rm/implementation_advice rm-2-8-17-19-pragmas}@anchor{223} |
64d5610f ML |
13841 | @section RM 2.8(17-19): Pragmas |
13842 | ||
13843 | ||
13844 | @quotation | |
13845 | ||
13846 | “Normally, an implementation should not define pragmas that can | |
13847 | make an illegal program legal, except as follows: | |
13848 | ||
13849 | ||
13850 | @itemize * | |
13851 | ||
13852 | @item | |
13853 | A pragma used to complete a declaration, such as a pragma @code{Import}; | |
13854 | ||
13855 | @item | |
13856 | A pragma used to configure the environment by adding, removing, or | |
13857 | replacing @code{library_items}.” | |
13858 | @end itemize | |
13859 | @end quotation | |
13860 | ||
73918baf | 13861 | See @ref{222,,RM 2.8(16); Pragmas}. |
64d5610f ML |
13862 | |
13863 | @geindex Character Sets | |
13864 | ||
13865 | @geindex Alternative Character Sets | |
13866 | ||
13867 | @node RM 3 5 2 5 Alternative Character Sets,RM 3 5 4 28 Integer Types,RM 2 8 17-19 Pragmas,Implementation Advice | |
73918baf | 13868 | @anchor{gnat_rm/implementation_advice rm-3-5-2-5-alternative-character-sets}@anchor{224} |
64d5610f ML |
13869 | @section RM 3.5.2(5): Alternative Character Sets |
13870 | ||
13871 | ||
13872 | @quotation | |
13873 | ||
13874 | “If an implementation supports a mode with alternative interpretations | |
13875 | for @code{Character} and @code{Wide_Character}, the set of graphic | |
13876 | characters of @code{Character} should nevertheless remain a proper | |
13877 | subset of the set of graphic characters of @code{Wide_Character}. Any | |
13878 | character set ‘localizations’ should be reflected in the results of | |
13879 | the subprograms defined in the language-defined package | |
13880 | @code{Characters.Handling} (see A.3) available in such a mode. In a mode with | |
13881 | an alternative interpretation of @code{Character}, the implementation should | |
13882 | also support a corresponding change in what is a legal | |
13883 | @code{identifier_letter}.” | |
13884 | @end quotation | |
13885 | ||
13886 | Not all wide character modes follow this advice, in particular the JIS | |
13887 | and IEC modes reflect standard usage in Japan, and in these encoding, | |
13888 | the upper half of the Latin-1 set is not part of the wide-character | |
13889 | subset, since the most significant bit is used for wide character | |
13890 | encoding. However, this only applies to the external forms. Internally | |
13891 | there is no such restriction. | |
13892 | ||
13893 | @geindex Integer types | |
13894 | ||
13895 | @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 | |
73918baf | 13896 | @anchor{gnat_rm/implementation_advice rm-3-5-4-28-integer-types}@anchor{225} |
64d5610f ML |
13897 | @section RM 3.5.4(28): Integer Types |
13898 | ||
13899 | ||
13900 | @quotation | |
13901 | ||
13902 | “An implementation should support @code{Long_Integer} in addition to | |
13903 | @code{Integer} if the target machine supports 32-bit (or longer) | |
13904 | arithmetic. No other named integer subtypes are recommended for package | |
13905 | @code{Standard}. Instead, appropriate named integer subtypes should be | |
13906 | provided in the library package @code{Interfaces} (see B.2).” | |
13907 | @end quotation | |
13908 | ||
13909 | @code{Long_Integer} is supported. Other standard integer types are supported | |
13910 | so this advice is not fully followed. These types | |
13911 | are supported for convenient interface to C, and so that all hardware | |
13912 | types of the machine are easily available. | |
13913 | ||
13914 | @node RM 3 5 4 29 Integer Types,RM 3 5 5 8 Enumeration Values,RM 3 5 4 28 Integer Types,Implementation Advice | |
73918baf | 13915 | @anchor{gnat_rm/implementation_advice rm-3-5-4-29-integer-types}@anchor{226} |
64d5610f ML |
13916 | @section RM 3.5.4(29): Integer Types |
13917 | ||
13918 | ||
13919 | @quotation | |
13920 | ||
13921 | “An implementation for a two’s complement machine should support | |
13922 | modular types with a binary modulus up to @code{System.Max_Int*2+2}. An | |
13923 | implementation should support a non-binary modules up to @code{Integer'Last}.” | |
13924 | @end quotation | |
13925 | ||
13926 | Followed. | |
13927 | ||
13928 | @geindex Enumeration values | |
13929 | ||
13930 | @node RM 3 5 5 8 Enumeration Values,RM 3 5 7 17 Float Types,RM 3 5 4 29 Integer Types,Implementation Advice | |
73918baf | 13931 | @anchor{gnat_rm/implementation_advice rm-3-5-5-8-enumeration-values}@anchor{227} |
64d5610f ML |
13932 | @section RM 3.5.5(8): Enumeration Values |
13933 | ||
13934 | ||
13935 | @quotation | |
13936 | ||
13937 | “For the evaluation of a call on @code{S'Pos} for an enumeration | |
13938 | subtype, if the value of the operand does not correspond to the internal | |
13939 | code for any enumeration literal of its type (perhaps due to an | |
13940 | un-initialized variable), then the implementation should raise | |
13941 | @code{Program_Error}. This is particularly important for enumeration | |
13942 | types with noncontiguous internal codes specified by an | |
13943 | enumeration_representation_clause.” | |
13944 | @end quotation | |
13945 | ||
13946 | Followed. | |
13947 | ||
13948 | @geindex Float types | |
13949 | ||
13950 | @node RM 3 5 7 17 Float Types,RM 3 6 2 11 Multidimensional Arrays,RM 3 5 5 8 Enumeration Values,Implementation Advice | |
73918baf | 13951 | @anchor{gnat_rm/implementation_advice rm-3-5-7-17-float-types}@anchor{228} |
64d5610f ML |
13952 | @section RM 3.5.7(17): Float Types |
13953 | ||
13954 | ||
13955 | @quotation | |
13956 | ||
13957 | “An implementation should support @code{Long_Float} in addition to | |
13958 | @code{Float} if the target machine supports 11 or more digits of | |
13959 | precision. No other named floating point subtypes are recommended for | |
13960 | package @code{Standard}. Instead, appropriate named floating point subtypes | |
13961 | should be provided in the library package @code{Interfaces} (see B.2).” | |
13962 | @end quotation | |
13963 | ||
13964 | @code{Short_Float} and @code{Long_Long_Float} are also provided. The | |
13965 | former provides improved compatibility with other implementations | |
13966 | supporting this type. The latter corresponds to the highest precision | |
13967 | floating-point type supported by the hardware. On most machines, this | |
13968 | will be the same as @code{Long_Float}, but on some machines, it will | |
13969 | correspond to the IEEE extended form. The notable case is all x86 | |
13970 | implementations, where @code{Long_Long_Float} corresponds to the 80-bit | |
13971 | extended precision format supported in hardware on this processor. | |
13972 | Note that the 128-bit format on SPARC is not supported, since this | |
13973 | is a software rather than a hardware format. | |
13974 | ||
13975 | @geindex Multidimensional arrays | |
13976 | ||
13977 | @geindex Arrays | |
13978 | @geindex multidimensional | |
13979 | ||
13980 | @node RM 3 6 2 11 Multidimensional Arrays,RM 9 6 30-31 Duration’Small,RM 3 5 7 17 Float Types,Implementation Advice | |
73918baf | 13981 | @anchor{gnat_rm/implementation_advice rm-3-6-2-11-multidimensional-arrays}@anchor{229} |
64d5610f ML |
13982 | @section RM 3.6.2(11): Multidimensional Arrays |
13983 | ||
13984 | ||
13985 | @quotation | |
13986 | ||
13987 | “An implementation should normally represent multidimensional arrays in | |
13988 | row-major order, consistent with the notation used for multidimensional | |
13989 | array aggregates (see 4.3.3). However, if a pragma @code{Convention} | |
13990 | (@code{Fortran}, …) applies to a multidimensional array type, then | |
13991 | column-major order should be used instead (see B.5, `Interfacing with Fortran').” | |
13992 | @end quotation | |
13993 | ||
13994 | Followed. | |
13995 | ||
13996 | @geindex Duration'Small | |
13997 | ||
13998 | @node RM 9 6 30-31 Duration’Small,RM 10 2 1 12 Consistent Representation,RM 3 6 2 11 Multidimensional Arrays,Implementation Advice | |
73918baf | 13999 | @anchor{gnat_rm/implementation_advice rm-9-6-30-31-duration-small}@anchor{22a} |
64d5610f ML |
14000 | @section RM 9.6(30-31): Duration’Small |
14001 | ||
14002 | ||
14003 | @quotation | |
14004 | ||
14005 | “Whenever possible in an implementation, the value of @code{Duration'Small} | |
14006 | should be no greater than 100 microseconds.” | |
14007 | @end quotation | |
14008 | ||
14009 | Followed. (@code{Duration'Small} = 10**(-9)). | |
14010 | ||
14011 | @quotation | |
14012 | ||
14013 | “The time base for @code{delay_relative_statements} should be monotonic; | |
14014 | it need not be the same time base as used for @code{Calendar.Clock}.” | |
14015 | @end quotation | |
14016 | ||
14017 | Followed. | |
14018 | ||
14019 | @node RM 10 2 1 12 Consistent Representation,RM 11 4 1 19 Exception Information,RM 9 6 30-31 Duration’Small,Implementation Advice | |
73918baf | 14020 | @anchor{gnat_rm/implementation_advice rm-10-2-1-12-consistent-representation}@anchor{22b} |
64d5610f ML |
14021 | @section RM 10.2.1(12): Consistent Representation |
14022 | ||
14023 | ||
14024 | @quotation | |
14025 | ||
14026 | “In an implementation, a type declared in a pre-elaborated package should | |
14027 | have the same representation in every elaboration of a given version of | |
14028 | the package, whether the elaborations occur in distinct executions of | |
14029 | the same program, or in executions of distinct programs or partitions | |
14030 | that include the given version.” | |
14031 | @end quotation | |
14032 | ||
14033 | Followed, except in the case of tagged types. Tagged types involve | |
14034 | implicit pointers to a local copy of a dispatch table, and these pointers | |
14035 | have representations which thus depend on a particular elaboration of the | |
14036 | package. It is not easy to see how it would be possible to follow this | |
14037 | advice without severely impacting efficiency of execution. | |
14038 | ||
14039 | @geindex Exception information | |
14040 | ||
14041 | @node RM 11 4 1 19 Exception Information,RM 11 5 28 Suppression of Checks,RM 10 2 1 12 Consistent Representation,Implementation Advice | |
73918baf | 14042 | @anchor{gnat_rm/implementation_advice rm-11-4-1-19-exception-information}@anchor{22c} |
64d5610f ML |
14043 | @section RM 11.4.1(19): Exception Information |
14044 | ||
14045 | ||
14046 | @quotation | |
14047 | ||
14048 | “@code{Exception_Message} by default and @code{Exception_Information} | |
14049 | should produce information useful for | |
14050 | debugging. @code{Exception_Message} should be short, about one | |
14051 | line. @code{Exception_Information} can be long. @code{Exception_Message} | |
14052 | should not include the | |
14053 | @code{Exception_Name}. @code{Exception_Information} should include both | |
14054 | the @code{Exception_Name} and the @code{Exception_Message}.” | |
14055 | @end quotation | |
14056 | ||
14057 | Followed. For each exception that doesn’t have a specified | |
14058 | @code{Exception_Message}, the compiler generates one containing the location | |
14059 | of the raise statement. This location has the form ‘file_name:line’, where | |
14060 | file_name is the short file name (without path information) and line is the line | |
14061 | number in the file. Note that in the case of the Zero Cost Exception | |
14062 | mechanism, these messages become redundant with the Exception_Information that | |
14063 | contains a full backtrace of the calling sequence, so they are disabled. | |
14064 | To disable explicitly the generation of the source location message, use the | |
14065 | Pragma @code{Discard_Names}. | |
14066 | ||
14067 | @geindex Suppression of checks | |
14068 | ||
14069 | @geindex Checks | |
14070 | @geindex suppression of | |
14071 | ||
14072 | @node RM 11 5 28 Suppression of Checks,RM 13 1 21-24 Representation Clauses,RM 11 4 1 19 Exception Information,Implementation Advice | |
73918baf | 14073 | @anchor{gnat_rm/implementation_advice rm-11-5-28-suppression-of-checks}@anchor{22d} |
64d5610f ML |
14074 | @section RM 11.5(28): Suppression of Checks |
14075 | ||
14076 | ||
14077 | @quotation | |
14078 | ||
14079 | “The implementation should minimize the code executed for checks that | |
14080 | have been suppressed.” | |
14081 | @end quotation | |
14082 | ||
14083 | Followed. | |
14084 | ||
14085 | @geindex Representation clauses | |
14086 | ||
14087 | @node RM 13 1 21-24 Representation Clauses,RM 13 2 6-8 Packed Types,RM 11 5 28 Suppression of Checks,Implementation Advice | |
73918baf | 14088 | @anchor{gnat_rm/implementation_advice rm-13-1-21-24-representation-clauses}@anchor{22e} |
64d5610f ML |
14089 | @section RM 13.1 (21-24): Representation Clauses |
14090 | ||
14091 | ||
14092 | @quotation | |
14093 | ||
14094 | “The recommended level of support for all representation items is | |
14095 | qualified as follows: | |
14096 | ||
14097 | An implementation need not support representation items containing | |
14098 | nonstatic expressions, except that an implementation should support a | |
14099 | representation item for a given entity if each nonstatic expression in | |
14100 | the representation item is a name that statically denotes a constant | |
14101 | declared before the entity.” | |
14102 | @end quotation | |
14103 | ||
14104 | Followed. In fact, GNAT goes beyond the recommended level of support | |
14105 | by allowing nonstatic expressions in some representation clauses even | |
14106 | without the need to declare constants initialized with the values of | |
14107 | such expressions. | |
14108 | For example: | |
14109 | ||
14110 | @example | |
14111 | X : Integer; | |
14112 | Y : Float; | |
14113 | for Y'Address use X'Address;>> | |
14114 | ||
14115 | ||
14116 | "An implementation need not support a specification for the `@w{`}Size`@w{`} | |
14117 | for a given composite subtype, nor the size or storage place for an | |
14118 | object (including a component) of a given composite subtype, unless the | |
14119 | constraints on the subtype and its composite subcomponents (if any) are | |
14120 | all static constraints." | |
14121 | @end example | |
14122 | ||
14123 | Followed. Size Clauses are not permitted on nonstatic components, as | |
14124 | described above. | |
14125 | ||
14126 | @quotation | |
14127 | ||
14128 | “An aliased component, or a component whose type is by-reference, should | |
14129 | always be allocated at an addressable location.” | |
14130 | @end quotation | |
14131 | ||
14132 | Followed. | |
14133 | ||
14134 | @geindex Packed types | |
14135 | ||
14136 | @node RM 13 2 6-8 Packed Types,RM 13 3 14-19 Address Clauses,RM 13 1 21-24 Representation Clauses,Implementation Advice | |
73918baf | 14137 | @anchor{gnat_rm/implementation_advice rm-13-2-6-8-packed-types}@anchor{22f} |
64d5610f ML |
14138 | @section RM 13.2(6-8): Packed Types |
14139 | ||
14140 | ||
14141 | @quotation | |
14142 | ||
14143 | “If a type is packed, then the implementation should try to minimize | |
14144 | storage allocated to objects of the type, possibly at the expense of | |
14145 | speed of accessing components, subject to reasonable complexity in | |
14146 | addressing calculations. | |
14147 | ||
14148 | The recommended level of support pragma @code{Pack} is: | |
14149 | ||
14150 | For a packed record type, the components should be packed as tightly as | |
14151 | possible subject to the Sizes of the component subtypes, and subject to | |
14152 | any `record_representation_clause' that applies to the type; the | |
14153 | implementation may, but need not, reorder components or cross aligned | |
14154 | word boundaries to improve the packing. A component whose @code{Size} is | |
14155 | greater than the word size may be allocated an integral number of words.” | |
14156 | @end quotation | |
14157 | ||
14158 | Followed. Tight packing of arrays is supported for all component sizes | |
14159 | up to 64-bits. If the array component size is 1 (that is to say, if | |
14160 | the component is a boolean type or an enumeration type with two values) | |
14161 | then values of the type are implicitly initialized to zero. This | |
14162 | happens both for objects of the packed type, and for objects that have a | |
14163 | subcomponent of the packed type. | |
14164 | ||
14165 | @geindex Address clauses | |
14166 | ||
14167 | @node RM 13 3 14-19 Address Clauses,RM 13 3 29-35 Alignment Clauses,RM 13 2 6-8 Packed Types,Implementation Advice | |
73918baf | 14168 | @anchor{gnat_rm/implementation_advice rm-13-3-14-19-address-clauses}@anchor{230} |
64d5610f ML |
14169 | @section RM 13.3(14-19): Address Clauses |
14170 | ||
14171 | ||
14172 | @quotation | |
14173 | ||
14174 | “For an array @code{X}, @code{X'Address} should point at the first | |
14175 | component of the array, and not at the array bounds.” | |
14176 | @end quotation | |
14177 | ||
14178 | Followed. | |
14179 | ||
14180 | @quotation | |
14181 | ||
14182 | “The recommended level of support for the @code{Address} attribute is: | |
14183 | ||
14184 | @code{X'Address} should produce a useful result if @code{X} is an | |
14185 | object that is aliased or of a by-reference type, or is an entity whose | |
14186 | @code{Address} has been specified.” | |
14187 | @end quotation | |
14188 | ||
14189 | Followed. A valid address will be produced even if none of those | |
14190 | conditions have been met. If necessary, the object is forced into | |
14191 | memory to ensure the address is valid. | |
14192 | ||
14193 | @quotation | |
14194 | ||
14195 | “An implementation should support @code{Address} clauses for imported | |
14196 | subprograms.” | |
14197 | @end quotation | |
14198 | ||
14199 | Followed. | |
14200 | ||
14201 | @quotation | |
14202 | ||
14203 | “Objects (including subcomponents) that are aliased or of a by-reference | |
14204 | type should be allocated on storage element boundaries.” | |
14205 | @end quotation | |
14206 | ||
14207 | Followed. | |
14208 | ||
14209 | @quotation | |
14210 | ||
14211 | “If the @code{Address} of an object is specified, or it is imported or exported, | |
14212 | then the implementation should not perform optimizations based on | |
14213 | assumptions of no aliases.” | |
14214 | @end quotation | |
14215 | ||
14216 | Followed. | |
14217 | ||
14218 | @geindex Alignment clauses | |
14219 | ||
14220 | @node RM 13 3 29-35 Alignment Clauses,RM 13 3 42-43 Size Clauses,RM 13 3 14-19 Address Clauses,Implementation Advice | |
73918baf | 14221 | @anchor{gnat_rm/implementation_advice rm-13-3-29-35-alignment-clauses}@anchor{231} |
64d5610f ML |
14222 | @section RM 13.3(29-35): Alignment Clauses |
14223 | ||
14224 | ||
14225 | @quotation | |
14226 | ||
14227 | “The recommended level of support for the @code{Alignment} attribute for | |
14228 | subtypes is: | |
14229 | ||
14230 | An implementation should support specified Alignments that are factors | |
14231 | and multiples of the number of storage elements per word, subject to the | |
14232 | following:” | |
14233 | @end quotation | |
14234 | ||
14235 | Followed. | |
14236 | ||
14237 | @quotation | |
14238 | ||
14239 | “An implementation need not support specified Alignments for | |
14240 | combinations of Sizes and Alignments that cannot be easily | |
14241 | loaded and stored by available machine instructions.” | |
14242 | @end quotation | |
14243 | ||
14244 | Followed. | |
14245 | ||
14246 | @quotation | |
14247 | ||
14248 | “An implementation need not support specified Alignments that are | |
14249 | greater than the maximum @code{Alignment} the implementation ever returns by | |
14250 | default.” | |
14251 | @end quotation | |
14252 | ||
14253 | Followed. | |
14254 | ||
14255 | @quotation | |
14256 | ||
14257 | “The recommended level of support for the @code{Alignment} attribute for | |
14258 | objects is: | |
14259 | ||
14260 | Same as above, for subtypes, but in addition:” | |
14261 | @end quotation | |
14262 | ||
14263 | Followed. | |
14264 | ||
14265 | @quotation | |
14266 | ||
14267 | “For stand-alone library-level objects of statically constrained | |
14268 | subtypes, the implementation should support all alignments | |
14269 | supported by the target linker. For example, page alignment is likely to | |
14270 | be supported for such objects, but not for subtypes.” | |
14271 | @end quotation | |
14272 | ||
14273 | Followed. | |
14274 | ||
14275 | @geindex Size clauses | |
14276 | ||
14277 | @node RM 13 3 42-43 Size Clauses,RM 13 3 50-56 Size Clauses,RM 13 3 29-35 Alignment Clauses,Implementation Advice | |
73918baf | 14278 | @anchor{gnat_rm/implementation_advice rm-13-3-42-43-size-clauses}@anchor{232} |
64d5610f ML |
14279 | @section RM 13.3(42-43): Size Clauses |
14280 | ||
14281 | ||
14282 | @quotation | |
14283 | ||
14284 | “The recommended level of support for the @code{Size} attribute of | |
14285 | objects is: | |
14286 | ||
14287 | A @code{Size} clause should be supported for an object if the specified | |
14288 | @code{Size} is at least as large as its subtype’s @code{Size}, and | |
14289 | corresponds to a size in storage elements that is a multiple of the | |
14290 | object’s @code{Alignment} (if the @code{Alignment} is nonzero).” | |
14291 | @end quotation | |
14292 | ||
14293 | Followed. | |
14294 | ||
14295 | @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 | |
73918baf | 14296 | @anchor{gnat_rm/implementation_advice rm-13-3-50-56-size-clauses}@anchor{233} |
64d5610f ML |
14297 | @section RM 13.3(50-56): Size Clauses |
14298 | ||
14299 | ||
14300 | @quotation | |
14301 | ||
14302 | “If the @code{Size} of a subtype is specified, and allows for efficient | |
14303 | independent addressability (see 9.10) on the target architecture, then | |
14304 | the @code{Size} of the following objects of the subtype should equal the | |
14305 | @code{Size} of the subtype: | |
14306 | ||
14307 | Aliased objects (including components).” | |
14308 | @end quotation | |
14309 | ||
14310 | Followed. | |
14311 | ||
14312 | @quotation | |
14313 | ||
14314 | “@cite{Size} clause on a composite subtype should not affect the | |
14315 | internal layout of components.” | |
14316 | @end quotation | |
14317 | ||
14318 | Followed. But note that this can be overridden by use of the implementation | |
14319 | pragma Implicit_Packing in the case of packed arrays. | |
14320 | ||
14321 | @quotation | |
14322 | ||
14323 | “The recommended level of support for the @code{Size} attribute of subtypes is: | |
14324 | ||
14325 | The @code{Size} (if not specified) of a static discrete or fixed point | |
14326 | subtype should be the number of bits needed to represent each value | |
14327 | belonging to the subtype using an unbiased representation, leaving space | |
14328 | for a sign bit only if the subtype contains negative values. If such a | |
14329 | subtype is a first subtype, then an implementation should support a | |
14330 | specified @code{Size} for it that reflects this representation.” | |
14331 | @end quotation | |
14332 | ||
14333 | Followed. | |
14334 | ||
14335 | @quotation | |
14336 | ||
14337 | “For a subtype implemented with levels of indirection, the @code{Size} | |
14338 | should include the size of the pointers, but not the size of what they | |
14339 | point at.” | |
14340 | @end quotation | |
14341 | ||
14342 | Followed. | |
14343 | ||
14344 | @geindex Component_Size clauses | |
14345 | ||
14346 | @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 | |
73918baf | 14347 | @anchor{gnat_rm/implementation_advice rm-13-3-71-73-component-size-clauses}@anchor{234} |
64d5610f ML |
14348 | @section RM 13.3(71-73): Component Size Clauses |
14349 | ||
14350 | ||
14351 | @quotation | |
14352 | ||
14353 | “The recommended level of support for the @code{Component_Size} | |
14354 | attribute is: | |
14355 | ||
14356 | An implementation need not support specified @code{Component_Sizes} that are | |
14357 | less than the @code{Size} of the component subtype.” | |
14358 | @end quotation | |
14359 | ||
14360 | Followed. | |
14361 | ||
14362 | @quotation | |
14363 | ||
14364 | “An implementation should support specified Component_Sizes that | |
14365 | are factors and multiples of the word size. For such | |
14366 | Component_Sizes, the array should contain no gaps between | |
14367 | components. For other Component_Sizes (if supported), the array | |
14368 | should contain no gaps between components when packing is also | |
14369 | specified; the implementation should forbid this combination in cases | |
14370 | where it cannot support a no-gaps representation.” | |
14371 | @end quotation | |
14372 | ||
14373 | Followed. | |
14374 | ||
14375 | @geindex Enumeration representation clauses | |
14376 | ||
14377 | @geindex Representation clauses | |
14378 | @geindex enumeration | |
14379 | ||
14380 | @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 | |
73918baf | 14381 | @anchor{gnat_rm/implementation_advice rm-13-4-9-10-enumeration-representation-clauses}@anchor{235} |
64d5610f ML |
14382 | @section RM 13.4(9-10): Enumeration Representation Clauses |
14383 | ||
14384 | ||
14385 | @quotation | |
14386 | ||
14387 | “The recommended level of support for enumeration representation clauses | |
14388 | is: | |
14389 | ||
14390 | An implementation need not support enumeration representation clauses | |
14391 | for boolean types, but should at minimum support the internal codes in | |
14392 | the range @code{System.Min_Int .. System.Max_Int}.” | |
14393 | @end quotation | |
14394 | ||
14395 | Followed. | |
14396 | ||
14397 | @geindex Record representation clauses | |
14398 | ||
14399 | @geindex Representation clauses | |
14400 | @geindex records | |
14401 | ||
14402 | @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 | |
73918baf | 14403 | @anchor{gnat_rm/implementation_advice rm-13-5-1-17-22-record-representation-clauses}@anchor{236} |
64d5610f ML |
14404 | @section RM 13.5.1(17-22): Record Representation Clauses |
14405 | ||
14406 | ||
14407 | @quotation | |
14408 | ||
14409 | “The recommended level of support for | |
14410 | `record_representation_clause's is: | |
14411 | ||
14412 | An implementation should support storage places that can be extracted | |
14413 | with a load, mask, shift sequence of machine code, and set with a load, | |
14414 | shift, mask, store sequence, given the available machine instructions | |
14415 | and run-time model.” | |
14416 | @end quotation | |
14417 | ||
14418 | Followed. | |
14419 | ||
14420 | @quotation | |
14421 | ||
14422 | “A storage place should be supported if its size is equal to the | |
14423 | @code{Size} of the component subtype, and it starts and ends on a | |
14424 | boundary that obeys the @code{Alignment} of the component subtype.” | |
14425 | @end quotation | |
14426 | ||
14427 | Followed. | |
14428 | ||
14429 | @quotation | |
14430 | ||
14431 | “If the default bit ordering applies to the declaration of a given type, | |
14432 | then for a component whose subtype’s @code{Size} is less than the word | |
14433 | size, any storage place that does not cross an aligned word boundary | |
14434 | should be supported.” | |
14435 | @end quotation | |
14436 | ||
14437 | Followed. | |
14438 | ||
14439 | @quotation | |
14440 | ||
14441 | “An implementation may reserve a storage place for the tag field of a | |
14442 | tagged type, and disallow other components from overlapping that place.” | |
14443 | @end quotation | |
14444 | ||
14445 | Followed. The storage place for the tag field is the beginning of the tagged | |
14446 | record, and its size is Address’Size. GNAT will reject an explicit component | |
14447 | clause for the tag field. | |
14448 | ||
14449 | @quotation | |
14450 | ||
14451 | “An implementation need not support a `component_clause' for a | |
14452 | component of an extension part if the storage place is not after the | |
14453 | storage places of all components of the parent type, whether or not | |
14454 | those storage places had been specified.” | |
14455 | @end quotation | |
14456 | ||
14457 | Followed. The above advice on record representation clauses is followed, | |
14458 | and all mentioned features are implemented. | |
14459 | ||
14460 | @geindex Storage place attributes | |
14461 | ||
14462 | @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 | |
73918baf | 14463 | @anchor{gnat_rm/implementation_advice rm-13-5-2-5-storage-place-attributes}@anchor{237} |
64d5610f ML |
14464 | @section RM 13.5.2(5): Storage Place Attributes |
14465 | ||
14466 | ||
14467 | @quotation | |
14468 | ||
14469 | “If a component is represented using some form of pointer (such as an | |
14470 | offset) to the actual data of the component, and this data is contiguous | |
14471 | with the rest of the object, then the storage place attributes should | |
14472 | reflect the place of the actual data, not the pointer. If a component is | |
14473 | allocated discontinuously from the rest of the object, then a warning | |
14474 | should be generated upon reference to one of its storage place | |
14475 | attributes.” | |
14476 | @end quotation | |
14477 | ||
14478 | Followed. There are no such components in GNAT. | |
14479 | ||
14480 | @geindex Bit ordering | |
14481 | ||
14482 | @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 | |
73918baf | 14483 | @anchor{gnat_rm/implementation_advice rm-13-5-3-7-8-bit-ordering}@anchor{238} |
64d5610f ML |
14484 | @section RM 13.5.3(7-8): Bit Ordering |
14485 | ||
14486 | ||
14487 | @quotation | |
14488 | ||
14489 | “The recommended level of support for the non-default bit ordering is: | |
14490 | ||
14491 | If @code{Word_Size} = @code{Storage_Unit}, then the implementation | |
14492 | should support the non-default bit ordering in addition to the default | |
14493 | bit ordering.” | |
14494 | @end quotation | |
14495 | ||
14496 | Followed. Word size does not equal storage size in this implementation. | |
14497 | Thus non-default bit ordering is not supported. | |
14498 | ||
14499 | @geindex Address | |
14500 | @geindex as private type | |
14501 | ||
14502 | @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 | |
73918baf | 14503 | @anchor{gnat_rm/implementation_advice rm-13-7-37-address-as-private}@anchor{239} |
64d5610f ML |
14504 | @section RM 13.7(37): Address as Private |
14505 | ||
14506 | ||
14507 | @quotation | |
14508 | ||
14509 | “@cite{Address} should be of a private type.” | |
14510 | @end quotation | |
14511 | ||
14512 | Followed. | |
14513 | ||
14514 | @geindex Operations | |
14515 | @geindex on `@w{`}Address`@w{`} | |
14516 | ||
14517 | @geindex Address | |
14518 | @geindex operations of | |
14519 | ||
14520 | @node RM 13 7 1 16 Address Operations,RM 13 9 14-17 Unchecked Conversion,RM 13 7 37 Address as Private,Implementation Advice | |
73918baf | 14521 | @anchor{gnat_rm/implementation_advice rm-13-7-1-16-address-operations}@anchor{23a} |
64d5610f ML |
14522 | @section RM 13.7.1(16): Address Operations |
14523 | ||
14524 | ||
14525 | @quotation | |
14526 | ||
14527 | “Operations in @code{System} and its children should reflect the target | |
14528 | environment semantics as closely as is reasonable. For example, on most | |
14529 | machines, it makes sense for address arithmetic to ‘wrap around’. | |
14530 | Operations that do not make sense should raise @code{Program_Error}.” | |
14531 | @end quotation | |
14532 | ||
14533 | Followed. Address arithmetic is modular arithmetic that wraps around. No | |
14534 | operation raises @code{Program_Error}, since all operations make sense. | |
14535 | ||
14536 | @geindex Unchecked conversion | |
14537 | ||
14538 | @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 | |
73918baf | 14539 | @anchor{gnat_rm/implementation_advice rm-13-9-14-17-unchecked-conversion}@anchor{23b} |
64d5610f ML |
14540 | @section RM 13.9(14-17): Unchecked Conversion |
14541 | ||
14542 | ||
14543 | @quotation | |
14544 | ||
14545 | “The @code{Size} of an array object should not include its bounds; hence, | |
14546 | the bounds should not be part of the converted data.” | |
14547 | @end quotation | |
14548 | ||
14549 | Followed. | |
14550 | ||
14551 | @quotation | |
14552 | ||
14553 | “The implementation should not generate unnecessary run-time checks to | |
14554 | ensure that the representation of @code{S} is a representation of the | |
14555 | target type. It should take advantage of the permission to return by | |
14556 | reference when possible. Restrictions on unchecked conversions should be | |
14557 | avoided unless required by the target environment.” | |
14558 | @end quotation | |
14559 | ||
14560 | Followed. There are no restrictions on unchecked conversion. A warning is | |
14561 | generated if the source and target types do not have the same size since | |
14562 | the semantics in this case may be target dependent. | |
14563 | ||
14564 | @quotation | |
14565 | ||
14566 | “The recommended level of support for unchecked conversions is: | |
14567 | ||
14568 | Unchecked conversions should be supported and should be reversible in | |
14569 | the cases where this clause defines the result. To enable meaningful use | |
14570 | of unchecked conversion, a contiguous representation should be used for | |
14571 | elementary subtypes, for statically constrained array subtypes whose | |
14572 | component subtype is one of the subtypes described in this paragraph, | |
14573 | and for record subtypes without discriminants whose component subtypes | |
14574 | are described in this paragraph.” | |
14575 | @end quotation | |
14576 | ||
14577 | Followed. | |
14578 | ||
14579 | @geindex Heap usage | |
14580 | @geindex implicit | |
14581 | ||
14582 | @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 | |
73918baf | 14583 | @anchor{gnat_rm/implementation_advice rm-13-11-23-25-implicit-heap-usage}@anchor{23c} |
64d5610f ML |
14584 | @section RM 13.11(23-25): Implicit Heap Usage |
14585 | ||
14586 | ||
14587 | @quotation | |
14588 | ||
14589 | “An implementation should document any cases in which it dynamically | |
14590 | allocates heap storage for a purpose other than the evaluation of an | |
14591 | allocator.” | |
14592 | @end quotation | |
14593 | ||
14594 | Followed, the only other points at which heap storage is dynamically | |
14595 | allocated are as follows: | |
14596 | ||
14597 | ||
14598 | @itemize * | |
14599 | ||
14600 | @item | |
14601 | At initial elaboration time, to allocate dynamically sized global | |
14602 | objects. | |
14603 | ||
14604 | @item | |
14605 | To allocate space for a task when a task is created. | |
14606 | ||
14607 | @item | |
14608 | To extend the secondary stack dynamically when needed. The secondary | |
14609 | stack is used for returning variable length results. | |
14610 | @end itemize | |
14611 | ||
14612 | ||
14613 | @quotation | |
14614 | ||
14615 | “A default (implementation-provided) storage pool for an | |
14616 | access-to-constant type should not have overhead to support deallocation of | |
14617 | individual objects.” | |
14618 | @end quotation | |
14619 | ||
14620 | Followed. | |
14621 | ||
14622 | @quotation | |
14623 | ||
14624 | “A storage pool for an anonymous access type should be created at the | |
14625 | point of an allocator for the type, and be reclaimed when the designated | |
14626 | object becomes inaccessible.” | |
14627 | @end quotation | |
14628 | ||
14629 | Followed. | |
14630 | ||
14631 | @geindex Unchecked deallocation | |
14632 | ||
14633 | @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 | |
73918baf | 14634 | @anchor{gnat_rm/implementation_advice rm-13-11-2-17-unchecked-deallocation}@anchor{23d} |
64d5610f ML |
14635 | @section RM 13.11.2(17): Unchecked Deallocation |
14636 | ||
14637 | ||
14638 | @quotation | |
14639 | ||
14640 | “For a standard storage pool, @code{Free} should actually reclaim the | |
14641 | storage.” | |
14642 | @end quotation | |
14643 | ||
14644 | Followed. | |
14645 | ||
14646 | @geindex Stream oriented attributes | |
14647 | ||
14648 | @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 | |
73918baf | 14649 | @anchor{gnat_rm/implementation_advice rm-13-13-2-1-6-stream-oriented-attributes}@anchor{23e} |
64d5610f ML |
14650 | @section RM 13.13.2(1.6): Stream Oriented Attributes |
14651 | ||
14652 | ||
14653 | @quotation | |
14654 | ||
14655 | “If not specified, the value of Stream_Size for an elementary type | |
14656 | should be the number of bits that corresponds to the minimum number of | |
14657 | stream elements required by the first subtype of the type, rounded up | |
14658 | to the nearest factor or multiple of the word size that is also a | |
14659 | multiple of the stream element size.” | |
14660 | @end quotation | |
14661 | ||
14662 | Followed, except that the number of stream elements is 1, 2, 3, 4 or 8. | |
14663 | The Stream_Size may be used to override the default choice. | |
14664 | ||
14665 | The default implementation is based on direct binary representations and is | |
14666 | therefore target- and endianness-dependent. To address this issue, GNAT also | |
14667 | supplies an alternate implementation of the stream attributes @code{Read} and | |
14668 | @code{Write}, which uses the target-independent XDR standard representation for | |
14669 | scalar types. This XDR alternative can be enabled via the binder switch -xdr. | |
14670 | ||
14671 | @geindex XDR representation | |
14672 | ||
14673 | @geindex Read attribute | |
14674 | ||
14675 | @geindex Write attribute | |
14676 | ||
14677 | @geindex Stream oriented attributes | |
14678 | ||
14679 | @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 | |
73918baf | 14680 | @anchor{gnat_rm/implementation_advice rm-a-1-52-names-of-predefined-numeric-types}@anchor{23f} |
64d5610f ML |
14681 | @section RM A.1(52): Names of Predefined Numeric Types |
14682 | ||
14683 | ||
14684 | @quotation | |
14685 | ||
14686 | “If an implementation provides additional named predefined integer types, | |
14687 | then the names should end with @code{Integer} as in | |
14688 | @code{Long_Integer}. If an implementation provides additional named | |
14689 | predefined floating point types, then the names should end with | |
14690 | @code{Float} as in @code{Long_Float}.” | |
14691 | @end quotation | |
14692 | ||
14693 | Followed. | |
14694 | ||
14695 | @geindex Ada.Characters.Handling | |
14696 | ||
14697 | @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 | |
73918baf | 14698 | @anchor{gnat_rm/implementation_advice rm-a-3-2-49-ada-characters-handling}@anchor{240} |
64d5610f ML |
14699 | @section RM A.3.2(49): @code{Ada.Characters.Handling} |
14700 | ||
14701 | ||
14702 | @quotation | |
14703 | ||
14704 | “If an implementation provides a localized definition of @code{Character} | |
14705 | or @code{Wide_Character}, then the effects of the subprograms in | |
14706 | @code{Characters.Handling} should reflect the localizations. | |
14707 | See also 3.5.2.” | |
14708 | @end quotation | |
14709 | ||
14710 | Followed. GNAT provides no such localized definitions. | |
14711 | ||
14712 | @geindex Bounded-length strings | |
14713 | ||
14714 | @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 | |
73918baf | 14715 | @anchor{gnat_rm/implementation_advice rm-a-4-4-106-bounded-length-string-handling}@anchor{241} |
64d5610f ML |
14716 | @section RM A.4.4(106): Bounded-Length String Handling |
14717 | ||
14718 | ||
14719 | @quotation | |
14720 | ||
14721 | “Bounded string objects should not be implemented by implicit pointers | |
14722 | and dynamic allocation.” | |
14723 | @end quotation | |
14724 | ||
14725 | Followed. No implicit pointers or dynamic allocation are used. | |
14726 | ||
14727 | @geindex Random number generation | |
14728 | ||
14729 | @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 | |
73918baf | 14730 | @anchor{gnat_rm/implementation_advice rm-a-5-2-46-47-random-number-generation}@anchor{242} |
64d5610f ML |
14731 | @section RM A.5.2(46-47): Random Number Generation |
14732 | ||
14733 | ||
14734 | @quotation | |
14735 | ||
14736 | “Any storage associated with an object of type @code{Generator} should be | |
14737 | reclaimed on exit from the scope of the object.” | |
14738 | @end quotation | |
14739 | ||
14740 | Followed. | |
14741 | ||
14742 | @quotation | |
14743 | ||
14744 | “If the generator period is sufficiently long in relation to the number | |
14745 | of distinct initiator values, then each possible value of | |
14746 | @code{Initiator} passed to @code{Reset} should initiate a sequence of | |
14747 | random numbers that does not, in a practical sense, overlap the sequence | |
14748 | initiated by any other value. If this is not possible, then the mapping | |
14749 | between initiator values and generator states should be a rapidly | |
14750 | varying function of the initiator value.” | |
14751 | @end quotation | |
14752 | ||
14753 | Followed. The generator period is sufficiently long for the first | |
14754 | condition here to hold true. | |
14755 | ||
14756 | @geindex Get_Immediate | |
14757 | ||
14758 | @node RM A 10 7 23 Get_Immediate,RM A 18 Containers,RM A 5 2 46-47 Random Number Generation,Implementation Advice | |
73918baf | 14759 | @anchor{gnat_rm/implementation_advice rm-a-10-7-23-get-immediate}@anchor{243} |
64d5610f ML |
14760 | @section RM A.10.7(23): @code{Get_Immediate} |
14761 | ||
14762 | ||
14763 | @quotation | |
14764 | ||
14765 | “The @code{Get_Immediate} procedures should be implemented with | |
14766 | unbuffered input. For a device such as a keyboard, input should be | |
14767 | available if a key has already been typed, whereas for a disk | |
14768 | file, input should always be available except at end of file. For a file | |
14769 | associated with a keyboard-like device, any line-editing features of the | |
14770 | underlying operating system should be disabled during the execution of | |
14771 | @code{Get_Immediate}.” | |
14772 | @end quotation | |
14773 | ||
14774 | Followed on all targets except VxWorks. For VxWorks, there is no way to | |
14775 | provide this functionality that does not result in the input buffer being | |
14776 | flushed before the @code{Get_Immediate} call. A special unit | |
14777 | @code{Interfaces.Vxworks.IO} is provided that contains routines to enable | |
14778 | this functionality. | |
14779 | ||
14780 | @geindex Containers | |
14781 | ||
14782 | @node RM A 18 Containers,RM B 1 39-41 Pragma Export,RM A 10 7 23 Get_Immediate,Implementation Advice | |
73918baf | 14783 | @anchor{gnat_rm/implementation_advice rm-a-18-containers}@anchor{244} |
64d5610f ML |
14784 | @section RM A.18: @code{Containers} |
14785 | ||
14786 | ||
14787 | All implementation advice pertaining to Ada.Containers and its | |
14788 | child units (that is, all implementation advice occurring within | |
14789 | section A.18 and its subsections) is followed except for A.18.24(17): | |
14790 | ||
14791 | @quotation | |
14792 | ||
14793 | “Bounded ordered set objects should be implemented without implicit pointers or dynamic allocation. “ | |
14794 | @end quotation | |
14795 | ||
14796 | The implementations of the two Reference_Preserving_Key functions of | |
14797 | the generic package Ada.Containers.Bounded_Ordered_Sets each currently make | |
14798 | use of dynamic allocation; other operations on bounded ordered set objects | |
14799 | follow the implementation advice. | |
14800 | ||
14801 | @geindex Export | |
14802 | ||
14803 | @node RM B 1 39-41 Pragma Export,RM B 2 12-13 Package Interfaces,RM A 18 Containers,Implementation Advice | |
73918baf | 14804 | @anchor{gnat_rm/implementation_advice rm-b-1-39-41-pragma-export}@anchor{245} |
64d5610f ML |
14805 | @section RM B.1(39-41): Pragma @code{Export} |
14806 | ||
14807 | ||
14808 | @quotation | |
14809 | ||
14810 | “If an implementation supports pragma @code{Export} to a given language, | |
14811 | then it should also allow the main subprogram to be written in that | |
14812 | language. It should support some mechanism for invoking the elaboration | |
14813 | of the Ada library units included in the system, and for invoking the | |
14814 | finalization of the environment task. On typical systems, the | |
14815 | recommended mechanism is to provide two subprograms whose link names are | |
14816 | @code{adainit} and @code{adafinal}. @code{adainit} should contain the | |
14817 | elaboration code for library units. @code{adafinal} should contain the | |
14818 | finalization code. These subprograms should have no effect the second | |
14819 | and subsequent time they are called.” | |
14820 | @end quotation | |
14821 | ||
14822 | Followed. | |
14823 | ||
14824 | @quotation | |
14825 | ||
14826 | “Automatic elaboration of pre-elaborated packages should be | |
14827 | provided when pragma @code{Export} is supported.” | |
14828 | @end quotation | |
14829 | ||
14830 | Followed when the main program is in Ada. If the main program is in a | |
14831 | foreign language, then | |
14832 | @code{adainit} must be called to elaborate pre-elaborated | |
14833 | packages. | |
14834 | ||
14835 | @quotation | |
14836 | ||
14837 | “For each supported convention `L' other than @code{Intrinsic}, an | |
14838 | implementation should support @code{Import} and @code{Export} pragmas | |
14839 | for objects of `L'-compatible types and for subprograms, and pragma | |
14840 | @cite{Convention} for `L'-eligible types and for subprograms, | |
14841 | presuming the other language has corresponding features. Pragma | |
14842 | @code{Convention} need not be supported for scalar types.” | |
14843 | @end quotation | |
14844 | ||
14845 | Followed. | |
14846 | ||
14847 | @geindex Package Interfaces | |
14848 | ||
14849 | @geindex Interfaces | |
14850 | ||
14851 | @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 | |
73918baf | 14852 | @anchor{gnat_rm/implementation_advice rm-b-2-12-13-package-interfaces}@anchor{246} |
64d5610f ML |
14853 | @section RM B.2(12-13): Package @code{Interfaces} |
14854 | ||
14855 | ||
14856 | @quotation | |
14857 | ||
14858 | “For each implementation-defined convention identifier, there should be a | |
14859 | child package of package Interfaces with the corresponding name. This | |
14860 | package should contain any declarations that would be useful for | |
14861 | interfacing to the language (implementation) represented by the | |
14862 | convention. Any declarations useful for interfacing to any language on | |
14863 | the given hardware architecture should be provided directly in | |
14864 | @code{Interfaces}.” | |
14865 | @end quotation | |
14866 | ||
14867 | Followed. | |
14868 | ||
14869 | @quotation | |
14870 | ||
14871 | “An implementation supporting an interface to C, COBOL, or Fortran should | |
14872 | provide the corresponding package or packages described in the following | |
14873 | clauses.” | |
14874 | @end quotation | |
14875 | ||
14876 | Followed. GNAT provides all the packages described in this section. | |
14877 | ||
14878 | @geindex C | |
14879 | @geindex interfacing with | |
14880 | ||
14881 | @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 | |
73918baf | 14882 | @anchor{gnat_rm/implementation_advice rm-b-3-63-71-interfacing-with-c}@anchor{247} |
64d5610f ML |
14883 | @section RM B.3(63-71): Interfacing with C |
14884 | ||
14885 | ||
14886 | @quotation | |
14887 | ||
14888 | “An implementation should support the following interface correspondences | |
14889 | between Ada and C.” | |
14890 | @end quotation | |
14891 | ||
14892 | Followed. | |
14893 | ||
14894 | @quotation | |
14895 | ||
14896 | “An Ada procedure corresponds to a void-returning C function.” | |
14897 | @end quotation | |
14898 | ||
14899 | Followed. | |
14900 | ||
14901 | @quotation | |
14902 | ||
14903 | “An Ada function corresponds to a non-void C function.” | |
14904 | @end quotation | |
14905 | ||
14906 | Followed. | |
14907 | ||
14908 | @quotation | |
14909 | ||
14910 | “An Ada @code{in} scalar parameter is passed as a scalar argument to a C | |
14911 | function.” | |
14912 | @end quotation | |
14913 | ||
14914 | Followed. | |
14915 | ||
14916 | @quotation | |
14917 | ||
14918 | “An Ada @code{in} parameter of an access-to-object type with designated | |
14919 | type @code{T} is passed as a @code{t*} argument to a C function, | |
14920 | where @code{t} is the C type corresponding to the Ada type @code{T}.” | |
14921 | @end quotation | |
14922 | ||
14923 | Followed. | |
14924 | ||
14925 | @quotation | |
14926 | ||
14927 | “An Ada access @code{T} parameter, or an Ada @code{out} or @code{in out} | |
14928 | parameter of an elementary type @code{T}, is passed as a @code{t*} | |
14929 | argument to a C function, where @code{t} is the C type corresponding to | |
14930 | the Ada type @code{T}. In the case of an elementary @code{out} or | |
14931 | @code{in out} parameter, a pointer to a temporary copy is used to | |
14932 | preserve by-copy semantics.” | |
14933 | @end quotation | |
14934 | ||
14935 | Followed. | |
14936 | ||
14937 | @quotation | |
14938 | ||
14939 | “An Ada parameter of a record type @code{T}, of any mode, is passed as a | |
14940 | @code{t*} argument to a C function, where @code{t} is the C | |
14941 | structure corresponding to the Ada type @code{T}.” | |
14942 | @end quotation | |
14943 | ||
14944 | Followed. This convention may be overridden by the use of the C_Pass_By_Copy | |
14945 | pragma, or Convention, or by explicitly specifying the mechanism for a given | |
14946 | call using an extended import or export pragma. | |
14947 | ||
14948 | @quotation | |
14949 | ||
14950 | “An Ada parameter of an array type with component type @code{T}, of any | |
14951 | mode, is passed as a @code{t*} argument to a C function, where | |
14952 | @code{t} is the C type corresponding to the Ada type @code{T}.” | |
14953 | @end quotation | |
14954 | ||
14955 | Followed. | |
14956 | ||
14957 | @quotation | |
14958 | ||
14959 | “An Ada parameter of an access-to-subprogram type is passed as a pointer | |
14960 | to a C function whose prototype corresponds to the designated | |
14961 | subprogram’s specification.” | |
14962 | @end quotation | |
14963 | ||
14964 | Followed. | |
14965 | ||
14966 | @geindex COBOL | |
14967 | @geindex interfacing with | |
14968 | ||
14969 | @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 | |
73918baf | 14970 | @anchor{gnat_rm/implementation_advice rm-b-4-95-98-interfacing-with-cobol}@anchor{248} |
64d5610f ML |
14971 | @section RM B.4(95-98): Interfacing with COBOL |
14972 | ||
14973 | ||
14974 | @quotation | |
14975 | ||
14976 | “An Ada implementation should support the following interface | |
14977 | correspondences between Ada and COBOL.” | |
14978 | @end quotation | |
14979 | ||
14980 | Followed. | |
14981 | ||
14982 | @quotation | |
14983 | ||
14984 | “An Ada access @code{T} parameter is passed as a @code{BY REFERENCE} data item of | |
14985 | the COBOL type corresponding to @code{T}.” | |
14986 | @end quotation | |
14987 | ||
14988 | Followed. | |
14989 | ||
14990 | @quotation | |
14991 | ||
14992 | “An Ada in scalar parameter is passed as a @code{BY CONTENT} data item of | |
14993 | the corresponding COBOL type.” | |
14994 | @end quotation | |
14995 | ||
14996 | Followed. | |
14997 | ||
14998 | @quotation | |
14999 | ||
15000 | “Any other Ada parameter is passed as a @code{BY REFERENCE} data item of the | |
15001 | COBOL type corresponding to the Ada parameter type; for scalars, a local | |
15002 | copy is used if necessary to ensure by-copy semantics.” | |
15003 | @end quotation | |
15004 | ||
15005 | Followed. | |
15006 | ||
15007 | @geindex Fortran | |
15008 | @geindex interfacing with | |
15009 | ||
15010 | @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 | |
73918baf | 15011 | @anchor{gnat_rm/implementation_advice rm-b-5-22-26-interfacing-with-fortran}@anchor{249} |
64d5610f ML |
15012 | @section RM B.5(22-26): Interfacing with Fortran |
15013 | ||
15014 | ||
15015 | @quotation | |
15016 | ||
15017 | “An Ada implementation should support the following interface | |
15018 | correspondences between Ada and Fortran:” | |
15019 | @end quotation | |
15020 | ||
15021 | Followed. | |
15022 | ||
15023 | @quotation | |
15024 | ||
15025 | “An Ada procedure corresponds to a Fortran subroutine.” | |
15026 | @end quotation | |
15027 | ||
15028 | Followed. | |
15029 | ||
15030 | @quotation | |
15031 | ||
15032 | “An Ada function corresponds to a Fortran function.” | |
15033 | @end quotation | |
15034 | ||
15035 | Followed. | |
15036 | ||
15037 | @quotation | |
15038 | ||
15039 | “An Ada parameter of an elementary, array, or record type @code{T} is | |
15040 | passed as a @code{T} argument to a Fortran procedure, where @code{T} is | |
15041 | the Fortran type corresponding to the Ada type @code{T}, and where the | |
15042 | INTENT attribute of the corresponding dummy argument matches the Ada | |
15043 | formal parameter mode; the Fortran implementation’s parameter passing | |
15044 | conventions are used. For elementary types, a local copy is used if | |
15045 | necessary to ensure by-copy semantics.” | |
15046 | @end quotation | |
15047 | ||
15048 | Followed. | |
15049 | ||
15050 | @quotation | |
15051 | ||
15052 | “An Ada parameter of an access-to-subprogram type is passed as a | |
15053 | reference to a Fortran procedure whose interface corresponds to the | |
15054 | designated subprogram’s specification.” | |
15055 | @end quotation | |
15056 | ||
15057 | Followed. | |
15058 | ||
15059 | @geindex Machine operations | |
15060 | ||
15061 | @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 | |
73918baf | 15062 | @anchor{gnat_rm/implementation_advice rm-c-1-3-5-access-to-machine-operations}@anchor{24a} |
64d5610f ML |
15063 | @section RM C.1(3-5): Access to Machine Operations |
15064 | ||
15065 | ||
15066 | @quotation | |
15067 | ||
15068 | “The machine code or intrinsic support should allow access to all | |
15069 | operations normally available to assembly language programmers for the | |
15070 | target environment, including privileged instructions, if any.” | |
15071 | @end quotation | |
15072 | ||
15073 | Followed. | |
15074 | ||
15075 | @quotation | |
15076 | ||
15077 | “The interfacing pragmas (see Annex B) should support interface to | |
15078 | assembler; the default assembler should be associated with the | |
15079 | convention identifier @code{Assembler}.” | |
15080 | @end quotation | |
15081 | ||
15082 | Followed. | |
15083 | ||
15084 | @quotation | |
15085 | ||
15086 | “If an entity is exported to assembly language, then the implementation | |
15087 | should allocate it at an addressable location, and should ensure that it | |
15088 | is retained by the linking process, even if not otherwise referenced | |
15089 | from the Ada code. The implementation should assume that any call to a | |
15090 | machine code or assembler subprogram is allowed to read or update every | |
15091 | object that is specified as exported.” | |
15092 | @end quotation | |
15093 | ||
15094 | Followed. | |
15095 | ||
15096 | @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 | |
73918baf | 15097 | @anchor{gnat_rm/implementation_advice rm-c-1-10-16-access-to-machine-operations}@anchor{24b} |
64d5610f ML |
15098 | @section RM C.1(10-16): Access to Machine Operations |
15099 | ||
15100 | ||
15101 | @quotation | |
15102 | ||
15103 | “The implementation should ensure that little or no overhead is | |
15104 | associated with calling intrinsic and machine-code subprograms.” | |
15105 | @end quotation | |
15106 | ||
15107 | Followed for both intrinsics and machine-code subprograms. | |
15108 | ||
15109 | @quotation | |
15110 | ||
15111 | “It is recommended that intrinsic subprograms be provided for convenient | |
15112 | access to any machine operations that provide special capabilities or | |
15113 | efficiency and that are not otherwise available through the language | |
15114 | constructs.” | |
15115 | @end quotation | |
15116 | ||
15117 | Followed. A full set of machine operation intrinsic subprograms is provided. | |
15118 | ||
15119 | @quotation | |
15120 | ||
15121 | “Atomic read-modify-write operations—e.g., test and set, compare and | |
15122 | swap, decrement and test, enqueue/dequeue.” | |
15123 | @end quotation | |
15124 | ||
15125 | Followed on any target supporting such operations. | |
15126 | ||
15127 | @quotation | |
15128 | ||
15129 | “Standard numeric functions—e.g.:, sin, log.” | |
15130 | @end quotation | |
15131 | ||
15132 | Followed on any target supporting such operations. | |
15133 | ||
15134 | @quotation | |
15135 | ||
15136 | “String manipulation operations—e.g.:, translate and test.” | |
15137 | @end quotation | |
15138 | ||
15139 | Followed on any target supporting such operations. | |
15140 | ||
15141 | @quotation | |
15142 | ||
15143 | “Vector operations—e.g.:, compare vector against thresholds.” | |
15144 | @end quotation | |
15145 | ||
15146 | Followed on any target supporting such operations. | |
15147 | ||
15148 | @quotation | |
15149 | ||
15150 | “Direct operations on I/O ports.” | |
15151 | @end quotation | |
15152 | ||
15153 | Followed on any target supporting such operations. | |
15154 | ||
15155 | @geindex Interrupt support | |
15156 | ||
15157 | @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 | |
73918baf | 15158 | @anchor{gnat_rm/implementation_advice rm-c-3-28-interrupt-support}@anchor{24c} |
64d5610f ML |
15159 | @section RM C.3(28): Interrupt Support |
15160 | ||
15161 | ||
15162 | @quotation | |
15163 | ||
15164 | “If the @code{Ceiling_Locking} policy is not in effect, the | |
15165 | implementation should provide means for the application to specify which | |
15166 | interrupts are to be blocked during protected actions, if the underlying | |
15167 | system allows for a finer-grain control of interrupt blocking.” | |
15168 | @end quotation | |
15169 | ||
15170 | Followed. The underlying system does not allow for finer-grain control | |
15171 | of interrupt blocking. | |
15172 | ||
15173 | @geindex Protected procedure handlers | |
15174 | ||
15175 | @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 | |
73918baf | 15176 | @anchor{gnat_rm/implementation_advice rm-c-3-1-20-21-protected-procedure-handlers}@anchor{24d} |
64d5610f ML |
15177 | @section RM C.3.1(20-21): Protected Procedure Handlers |
15178 | ||
15179 | ||
15180 | @quotation | |
15181 | ||
15182 | “Whenever possible, the implementation should allow interrupt handlers to | |
15183 | be called directly by the hardware.” | |
15184 | @end quotation | |
15185 | ||
15186 | Followed on any target where the underlying operating system permits | |
15187 | such direct calls. | |
15188 | ||
15189 | @quotation | |
15190 | ||
15191 | “Whenever practical, violations of any | |
15192 | implementation-defined restrictions should be detected before run time.” | |
15193 | @end quotation | |
15194 | ||
15195 | Followed. Compile time warnings are given when possible. | |
15196 | ||
15197 | @geindex Package `@w{`}Interrupts`@w{`} | |
15198 | ||
15199 | @geindex Interrupts | |
15200 | ||
15201 | @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 | |
73918baf | 15202 | @anchor{gnat_rm/implementation_advice rm-c-3-2-25-package-interrupts}@anchor{24e} |
64d5610f ML |
15203 | @section RM C.3.2(25): Package @code{Interrupts} |
15204 | ||
15205 | ||
15206 | @quotation | |
15207 | ||
15208 | “If implementation-defined forms of interrupt handler procedures are | |
15209 | supported, such as protected procedures with parameters, then for each | |
15210 | such form of a handler, a type analogous to @code{Parameterless_Handler} | |
15211 | should be specified in a child package of @code{Interrupts}, with the | |
15212 | same operations as in the predefined package Interrupts.” | |
15213 | @end quotation | |
15214 | ||
15215 | Followed. | |
15216 | ||
15217 | @geindex Pre-elaboration requirements | |
15218 | ||
15219 | @node RM C 4 14 Pre-elaboration Requirements,RM C 5 8 Pragma Discard_Names,RM C 3 2 25 Package Interrupts,Implementation Advice | |
73918baf | 15220 | @anchor{gnat_rm/implementation_advice rm-c-4-14-pre-elaboration-requirements}@anchor{24f} |
64d5610f ML |
15221 | @section RM C.4(14): Pre-elaboration Requirements |
15222 | ||
15223 | ||
15224 | @quotation | |
15225 | ||
15226 | “It is recommended that pre-elaborated packages be implemented in such a | |
15227 | way that there should be little or no code executed at run time for the | |
15228 | elaboration of entities not already covered by the Implementation | |
15229 | Requirements.” | |
15230 | @end quotation | |
15231 | ||
15232 | Followed. Executable code is generated in some cases, e.g., loops | |
15233 | to initialize large arrays. | |
15234 | ||
15235 | @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 | |
73918baf | 15236 | @anchor{gnat_rm/implementation_advice rm-c-5-8-pragma-discard-names}@anchor{250} |
64d5610f ML |
15237 | @section RM C.5(8): Pragma @code{Discard_Names} |
15238 | ||
15239 | ||
15240 | @quotation | |
15241 | ||
15242 | “If the pragma applies to an entity, then the implementation should | |
15243 | reduce the amount of storage used for storing names associated with that | |
15244 | entity.” | |
15245 | @end quotation | |
15246 | ||
15247 | Followed. | |
15248 | ||
15249 | @geindex Package Task_Attributes | |
15250 | ||
15251 | @geindex Task_Attributes | |
15252 | ||
15253 | @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 | |
73918baf | 15254 | @anchor{gnat_rm/implementation_advice rm-c-7-2-30-the-package-task-attributes}@anchor{251} |
64d5610f ML |
15255 | @section RM C.7.2(30): The Package Task_Attributes |
15256 | ||
15257 | ||
15258 | @quotation | |
15259 | ||
15260 | “Some implementations are targeted to domains in which memory use at run | |
15261 | time must be completely deterministic. For such implementations, it is | |
15262 | recommended that the storage for task attributes will be pre-allocated | |
15263 | statically and not from the heap. This can be accomplished by either | |
15264 | placing restrictions on the number and the size of the task’s | |
15265 | attributes, or by using the pre-allocated storage for the first @code{N} | |
15266 | attribute objects, and the heap for the others. In the latter case, | |
15267 | @code{N} should be documented.” | |
15268 | @end quotation | |
15269 | ||
15270 | Not followed. This implementation is not targeted to such a domain. | |
15271 | ||
15272 | @geindex Locking Policies | |
15273 | ||
15274 | @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 | |
73918baf | 15275 | @anchor{gnat_rm/implementation_advice rm-d-3-17-locking-policies}@anchor{252} |
64d5610f ML |
15276 | @section RM D.3(17): Locking Policies |
15277 | ||
15278 | ||
15279 | @quotation | |
15280 | ||
15281 | “The implementation should use names that end with @code{_Locking} for | |
15282 | locking policies defined by the implementation.” | |
15283 | @end quotation | |
15284 | ||
15285 | Followed. Two implementation-defined locking policies are defined, | |
15286 | whose names (@code{Inheritance_Locking} and | |
15287 | @code{Concurrent_Readers_Locking}) follow this suggestion. | |
15288 | ||
15289 | @geindex Entry queuing policies | |
15290 | ||
15291 | @node RM D 4 16 Entry Queuing Policies,RM D 6 9-10 Preemptive Abort,RM D 3 17 Locking Policies,Implementation Advice | |
73918baf | 15292 | @anchor{gnat_rm/implementation_advice rm-d-4-16-entry-queuing-policies}@anchor{253} |
64d5610f ML |
15293 | @section RM D.4(16): Entry Queuing Policies |
15294 | ||
15295 | ||
15296 | @quotation | |
15297 | ||
15298 | “Names that end with @code{_Queuing} should be used | |
15299 | for all implementation-defined queuing policies.” | |
15300 | @end quotation | |
15301 | ||
15302 | Followed. No such implementation-defined queuing policies exist. | |
15303 | ||
15304 | @geindex Preemptive abort | |
15305 | ||
15306 | @node RM D 6 9-10 Preemptive Abort,RM D 7 21 Tasking Restrictions,RM D 4 16 Entry Queuing Policies,Implementation Advice | |
73918baf | 15307 | @anchor{gnat_rm/implementation_advice rm-d-6-9-10-preemptive-abort}@anchor{254} |
64d5610f ML |
15308 | @section RM D.6(9-10): Preemptive Abort |
15309 | ||
15310 | ||
15311 | @quotation | |
15312 | ||
15313 | “Even though the `abort_statement' is included in the list of | |
15314 | potentially blocking operations (see 9.5.1), it is recommended that this | |
15315 | statement be implemented in a way that never requires the task executing | |
15316 | the `abort_statement' to block.” | |
15317 | @end quotation | |
15318 | ||
15319 | Followed. | |
15320 | ||
15321 | @quotation | |
15322 | ||
15323 | “On a multi-processor, the delay associated with aborting a task on | |
15324 | another processor should be bounded; the implementation should use | |
15325 | periodic polling, if necessary, to achieve this.” | |
15326 | @end quotation | |
15327 | ||
15328 | Followed. | |
15329 | ||
15330 | @geindex Tasking restrictions | |
15331 | ||
15332 | @node RM D 7 21 Tasking Restrictions,RM D 8 47-49 Monotonic Time,RM D 6 9-10 Preemptive Abort,Implementation Advice | |
73918baf | 15333 | @anchor{gnat_rm/implementation_advice rm-d-7-21-tasking-restrictions}@anchor{255} |
64d5610f ML |
15334 | @section RM D.7(21): Tasking Restrictions |
15335 | ||
15336 | ||
15337 | @quotation | |
15338 | ||
15339 | “When feasible, the implementation should take advantage of the specified | |
15340 | restrictions to produce a more efficient implementation.” | |
15341 | @end quotation | |
15342 | ||
15343 | GNAT currently takes advantage of these restrictions by providing an optimized | |
15344 | run time when the Ravenscar profile and the GNAT restricted run time set | |
15345 | of restrictions are specified. See pragma @code{Profile (Ravenscar)} and | |
15346 | pragma @code{Profile (Restricted)} for more details. | |
15347 | ||
15348 | @geindex Time | |
15349 | @geindex monotonic | |
15350 | ||
15351 | @node RM D 8 47-49 Monotonic Time,RM E 5 28-29 Partition Communication Subsystem,RM D 7 21 Tasking Restrictions,Implementation Advice | |
73918baf | 15352 | @anchor{gnat_rm/implementation_advice rm-d-8-47-49-monotonic-time}@anchor{256} |
64d5610f ML |
15353 | @section RM D.8(47-49): Monotonic Time |
15354 | ||
15355 | ||
15356 | @quotation | |
15357 | ||
15358 | “When appropriate, implementations should provide configuration | |
15359 | mechanisms to change the value of @code{Tick}.” | |
15360 | @end quotation | |
15361 | ||
15362 | Such configuration mechanisms are not appropriate to this implementation | |
15363 | and are thus not supported. | |
15364 | ||
15365 | @quotation | |
15366 | ||
15367 | “It is recommended that @code{Calendar.Clock} and @code{Real_Time.Clock} | |
15368 | be implemented as transformations of the same time base.” | |
15369 | @end quotation | |
15370 | ||
15371 | Followed. | |
15372 | ||
15373 | @quotation | |
15374 | ||
15375 | “It is recommended that the best time base which exists in | |
15376 | the underlying system be available to the application through | |
15377 | @code{Clock}. @cite{Best} may mean highest accuracy or largest range.” | |
15378 | @end quotation | |
15379 | ||
15380 | Followed. | |
15381 | ||
15382 | @geindex Partition communication subsystem | |
15383 | ||
15384 | @geindex PCS | |
15385 | ||
15386 | @node RM E 5 28-29 Partition Communication Subsystem,RM F 7 COBOL Support,RM D 8 47-49 Monotonic Time,Implementation Advice | |
73918baf | 15387 | @anchor{gnat_rm/implementation_advice rm-e-5-28-29-partition-communication-subsystem}@anchor{257} |
64d5610f ML |
15388 | @section RM E.5(28-29): Partition Communication Subsystem |
15389 | ||
15390 | ||
15391 | @quotation | |
15392 | ||
15393 | “Whenever possible, the PCS on the called partition should allow for | |
15394 | multiple tasks to call the RPC-receiver with different messages and | |
15395 | should allow them to block until the corresponding subprogram body | |
15396 | returns.” | |
15397 | @end quotation | |
15398 | ||
15399 | Followed by GLADE, a separately supplied PCS that can be used with | |
15400 | GNAT. | |
15401 | ||
15402 | @quotation | |
15403 | ||
15404 | “The @code{Write} operation on a stream of type @code{Params_Stream_Type} | |
15405 | should raise @code{Storage_Error} if it runs out of space trying to | |
15406 | write the @code{Item} into the stream.” | |
15407 | @end quotation | |
15408 | ||
15409 | Followed by GLADE, a separately supplied PCS that can be used with | |
15410 | GNAT. | |
15411 | ||
15412 | @geindex COBOL support | |
15413 | ||
15414 | @node RM F 7 COBOL Support,RM F 1 2 Decimal Radix Support,RM E 5 28-29 Partition Communication Subsystem,Implementation Advice | |
73918baf | 15415 | @anchor{gnat_rm/implementation_advice rm-f-7-cobol-support}@anchor{258} |
64d5610f ML |
15416 | @section RM F(7): COBOL Support |
15417 | ||
15418 | ||
15419 | @quotation | |
15420 | ||
15421 | “If COBOL (respectively, C) is widely supported in the target | |
15422 | environment, implementations supporting the Information Systems Annex | |
15423 | should provide the child package @code{Interfaces.COBOL} (respectively, | |
15424 | @code{Interfaces.C}) specified in Annex B and should support a | |
15425 | @code{convention_identifier} of COBOL (respectively, C) in the interfacing | |
15426 | pragmas (see Annex B), thus allowing Ada programs to interface with | |
15427 | programs written in that language.” | |
15428 | @end quotation | |
15429 | ||
15430 | Followed. | |
15431 | ||
15432 | @geindex Decimal radix support | |
15433 | ||
15434 | @node RM F 1 2 Decimal Radix Support,RM G Numerics,RM F 7 COBOL Support,Implementation Advice | |
73918baf | 15435 | @anchor{gnat_rm/implementation_advice rm-f-1-2-decimal-radix-support}@anchor{259} |
64d5610f ML |
15436 | @section RM F.1(2): Decimal Radix Support |
15437 | ||
15438 | ||
15439 | @quotation | |
15440 | ||
15441 | “Packed decimal should be used as the internal representation for objects | |
15442 | of subtype @code{S} when @code{S}’Machine_Radix = 10.” | |
15443 | @end quotation | |
15444 | ||
15445 | Not followed. GNAT ignores @code{S}’Machine_Radix and always uses binary | |
15446 | representations. | |
15447 | ||
15448 | @geindex Numerics | |
15449 | ||
15450 | @node RM G Numerics,RM G 1 1 56-58 Complex Types,RM F 1 2 Decimal Radix Support,Implementation Advice | |
73918baf | 15451 | @anchor{gnat_rm/implementation_advice rm-g-numerics}@anchor{25a} |
64d5610f ML |
15452 | @section RM G: Numerics |
15453 | ||
15454 | ||
15455 | @quotation | |
15456 | ||
15457 | “If Fortran (respectively, C) is widely supported in the target | |
15458 | environment, implementations supporting the Numerics Annex | |
15459 | should provide the child package @code{Interfaces.Fortran} (respectively, | |
15460 | @code{Interfaces.C}) specified in Annex B and should support a | |
15461 | @code{convention_identifier} of Fortran (respectively, C) in the interfacing | |
15462 | pragmas (see Annex B), thus allowing Ada programs to interface with | |
15463 | programs written in that language.” | |
15464 | @end quotation | |
15465 | ||
15466 | Followed. | |
15467 | ||
15468 | @geindex Complex types | |
15469 | ||
15470 | @node RM G 1 1 56-58 Complex Types,RM G 1 2 49 Complex Elementary Functions,RM G Numerics,Implementation Advice | |
73918baf | 15471 | @anchor{gnat_rm/implementation_advice rm-g-1-1-56-58-complex-types}@anchor{25b} |
64d5610f ML |
15472 | @section RM G.1.1(56-58): Complex Types |
15473 | ||
15474 | ||
15475 | @quotation | |
15476 | ||
15477 | “Because the usual mathematical meaning of multiplication of a complex | |
15478 | operand and a real operand is that of the scaling of both components of | |
15479 | the former by the latter, an implementation should not perform this | |
15480 | operation by first promoting the real operand to complex type and then | |
15481 | performing a full complex multiplication. In systems that, in the | |
15482 | future, support an Ada binding to IEC 559:1989, the latter technique | |
15483 | will not generate the required result when one of the components of the | |
15484 | complex operand is infinite. (Explicit multiplication of the infinite | |
15485 | component by the zero component obtained during promotion yields a NaN | |
15486 | that propagates into the final result.) Analogous advice applies in the | |
15487 | case of multiplication of a complex operand and a pure-imaginary | |
15488 | operand, and in the case of division of a complex operand by a real or | |
15489 | pure-imaginary operand.” | |
15490 | @end quotation | |
15491 | ||
15492 | Not followed. | |
15493 | ||
15494 | @quotation | |
15495 | ||
15496 | “Similarly, because the usual mathematical meaning of addition of a | |
15497 | complex operand and a real operand is that the imaginary operand remains | |
15498 | unchanged, an implementation should not perform this operation by first | |
15499 | promoting the real operand to complex type and then performing a full | |
15500 | complex addition. In implementations in which the @code{Signed_Zeros} | |
15501 | attribute of the component type is @code{True} (and which therefore | |
15502 | conform to IEC 559:1989 in regard to the handling of the sign of zero in | |
15503 | predefined arithmetic operations), the latter technique will not | |
15504 | generate the required result when the imaginary component of the complex | |
15505 | operand is a negatively signed zero. (Explicit addition of the negative | |
15506 | zero to the zero obtained during promotion yields a positive zero.) | |
15507 | Analogous advice applies in the case of addition of a complex operand | |
15508 | and a pure-imaginary operand, and in the case of subtraction of a | |
15509 | complex operand and a real or pure-imaginary operand.” | |
15510 | @end quotation | |
15511 | ||
15512 | Not followed. | |
15513 | ||
15514 | @quotation | |
15515 | ||
15516 | “Implementations in which @code{Real'Signed_Zeros} is @code{True} should | |
15517 | attempt to provide a rational treatment of the signs of zero results and | |
15518 | result components. As one example, the result of the @code{Argument} | |
15519 | function should have the sign of the imaginary component of the | |
15520 | parameter @code{X} when the point represented by that parameter lies on | |
15521 | the positive real axis; as another, the sign of the imaginary component | |
15522 | of the @code{Compose_From_Polar} function should be the same as | |
15523 | (respectively, the opposite of) that of the @code{Argument} parameter when that | |
15524 | parameter has a value of zero and the @code{Modulus} parameter has a | |
15525 | nonnegative (respectively, negative) value.” | |
15526 | @end quotation | |
15527 | ||
15528 | Followed. | |
15529 | ||
15530 | @geindex Complex elementary functions | |
15531 | ||
15532 | @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 | |
73918baf | 15533 | @anchor{gnat_rm/implementation_advice rm-g-1-2-49-complex-elementary-functions}@anchor{25c} |
64d5610f ML |
15534 | @section RM G.1.2(49): Complex Elementary Functions |
15535 | ||
15536 | ||
15537 | @quotation | |
15538 | ||
15539 | “Implementations in which @code{Complex_Types.Real'Signed_Zeros} is | |
15540 | @code{True} should attempt to provide a rational treatment of the signs | |
15541 | of zero results and result components. For example, many of the complex | |
15542 | elementary functions have components that are odd functions of one of | |
15543 | the parameter components; in these cases, the result component should | |
15544 | have the sign of the parameter component at the origin. Other complex | |
15545 | elementary functions have zero components whose sign is opposite that of | |
15546 | a parameter component at the origin, or is always positive or always | |
15547 | negative.” | |
15548 | @end quotation | |
15549 | ||
15550 | Followed. | |
15551 | ||
15552 | @geindex Accuracy requirements | |
15553 | ||
15554 | @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 | |
73918baf | 15555 | @anchor{gnat_rm/implementation_advice rm-g-2-4-19-accuracy-requirements}@anchor{25d} |
64d5610f ML |
15556 | @section RM G.2.4(19): Accuracy Requirements |
15557 | ||
15558 | ||
15559 | @quotation | |
15560 | ||
15561 | “The versions of the forward trigonometric functions without a | |
15562 | @code{Cycle} parameter should not be implemented by calling the | |
15563 | corresponding version with a @code{Cycle} parameter of | |
15564 | @code{2.0*Numerics.Pi}, since this will not provide the required | |
15565 | accuracy in some portions of the domain. For the same reason, the | |
15566 | version of @code{Log} without a @code{Base} parameter should not be | |
15567 | implemented by calling the corresponding version with a @code{Base} | |
15568 | parameter of @code{Numerics.e}.” | |
15569 | @end quotation | |
15570 | ||
15571 | Followed. | |
15572 | ||
15573 | @geindex Complex arithmetic accuracy | |
15574 | ||
15575 | @geindex Accuracy | |
15576 | @geindex complex arithmetic | |
15577 | ||
15578 | @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 | |
73918baf | 15579 | @anchor{gnat_rm/implementation_advice rm-g-2-6-15-complex-arithmetic-accuracy}@anchor{25e} |
64d5610f ML |
15580 | @section RM G.2.6(15): Complex Arithmetic Accuracy |
15581 | ||
15582 | ||
15583 | @quotation | |
15584 | ||
15585 | “The version of the @code{Compose_From_Polar} function without a | |
15586 | @code{Cycle} parameter should not be implemented by calling the | |
15587 | corresponding version with a @code{Cycle} parameter of | |
15588 | @code{2.0*Numerics.Pi}, since this will not provide the required | |
15589 | accuracy in some portions of the domain.” | |
15590 | @end quotation | |
15591 | ||
15592 | Followed. | |
15593 | ||
15594 | @geindex Sequential elaboration policy | |
15595 | ||
15596 | @node RM H 6 15/2 Pragma Partition_Elaboration_Policy,,RM G 2 6 15 Complex Arithmetic Accuracy,Implementation Advice | |
73918baf | 15597 | @anchor{gnat_rm/implementation_advice rm-h-6-15-2-pragma-partition-elaboration-policy}@anchor{25f} |
64d5610f ML |
15598 | @section RM H.6(15/2): Pragma Partition_Elaboration_Policy |
15599 | ||
15600 | ||
15601 | @quotation | |
15602 | ||
15603 | “If the partition elaboration policy is @code{Sequential} and the | |
15604 | Environment task becomes permanently blocked during elaboration then the | |
15605 | partition is deadlocked and it is recommended that the partition be | |
15606 | immediately terminated.” | |
15607 | @end quotation | |
15608 | ||
15609 | Not followed. | |
15610 | ||
15611 | @node Implementation Defined Characteristics,Intrinsic Subprograms,Implementation Advice,Top | |
73918baf | 15612 | @anchor{gnat_rm/implementation_defined_characteristics doc}@anchor{260}@anchor{gnat_rm/implementation_defined_characteristics id1}@anchor{261}@anchor{gnat_rm/implementation_defined_characteristics implementation-defined-characteristics}@anchor{b} |
64d5610f ML |
15613 | @chapter Implementation Defined Characteristics |
15614 | ||
15615 | ||
15616 | In addition to the implementation dependent pragmas and attributes, and the | |
15617 | implementation advice, there are a number of other Ada features that are | |
15618 | potentially implementation dependent and are designated as | |
15619 | implementation-defined. These are mentioned throughout the Ada Reference | |
15620 | Manual, and are summarized in Annex M. | |
15621 | ||
15622 | A requirement for conforming Ada compilers is that they provide | |
15623 | documentation describing how the implementation deals with each of these | |
15624 | issues. In this chapter you will find each point in Annex M listed, | |
15625 | followed by a description of how GNAT handles the implementation dependence. | |
15626 | ||
15627 | You can use this chapter as a guide to minimizing implementation | |
15628 | dependent features in your programs if portability to other compilers | |
15629 | and other operating systems is an important consideration. The numbers | |
15630 | in each entry below correspond to the paragraph numbers in the Ada | |
15631 | Reference Manual. | |
15632 | ||
15633 | ||
15634 | @itemize * | |
15635 | ||
15636 | @item | |
15637 | “Whether or not each recommendation given in Implementation | |
15638 | Advice is followed. See 1.1.2(37).” | |
15639 | @end itemize | |
15640 | ||
15641 | See @ref{a,,Implementation Advice}. | |
15642 | ||
15643 | ||
15644 | @itemize * | |
15645 | ||
15646 | @item | |
15647 | “Capacity limitations of the implementation. See 1.1.3(3).” | |
15648 | @end itemize | |
15649 | ||
15650 | The complexity of programs that can be processed is limited only by the | |
15651 | total amount of available virtual memory, and disk space for the | |
15652 | generated object files. | |
15653 | ||
15654 | ||
15655 | @itemize * | |
15656 | ||
15657 | @item | |
15658 | “Variations from the standard that are impractical to avoid | |
15659 | given the implementation’s execution environment. See 1.1.3(6).” | |
15660 | @end itemize | |
15661 | ||
15662 | There are no variations from the standard. | |
15663 | ||
15664 | ||
15665 | @itemize * | |
15666 | ||
15667 | @item | |
15668 | “Which code_statements cause external | |
15669 | interactions. See 1.1.3(10).” | |
15670 | @end itemize | |
15671 | ||
15672 | Any `code_statement' can potentially cause external interactions. | |
15673 | ||
15674 | ||
15675 | @itemize * | |
15676 | ||
15677 | @item | |
15678 | “The coded representation for the text of an Ada | |
15679 | program. See 2.1(4).” | |
15680 | @end itemize | |
15681 | ||
15682 | See separate section on source representation. | |
15683 | ||
15684 | ||
15685 | @itemize * | |
15686 | ||
15687 | @item | |
15688 | “The semantics of an Ada program whose text is not in | |
15689 | Normalization Form C. See 2.1(4).” | |
15690 | @end itemize | |
15691 | ||
15692 | See separate section on source representation. | |
15693 | ||
15694 | ||
15695 | @itemize * | |
15696 | ||
15697 | @item | |
15698 | “The representation for an end of line. See 2.2(2).” | |
15699 | @end itemize | |
15700 | ||
15701 | See separate section on source representation. | |
15702 | ||
15703 | ||
15704 | @itemize * | |
15705 | ||
15706 | @item | |
15707 | “Maximum supported line length and lexical element | |
15708 | length. See 2.2(15).” | |
15709 | @end itemize | |
15710 | ||
15711 | The maximum line length is 255 characters and the maximum length of | |
15712 | a lexical element is also 255 characters. This is the default setting | |
15713 | if not overridden by the use of compiler switch `-gnaty' (which | |
15714 | sets the maximum to 79) or `-gnatyMnn' which allows the maximum | |
15715 | line length to be specified to be any value up to 32767. The maximum | |
15716 | length of a lexical element is the same as the maximum line length. | |
15717 | ||
15718 | ||
15719 | @itemize * | |
15720 | ||
15721 | @item | |
15722 | “Implementation defined pragmas. See 2.8(14).” | |
15723 | @end itemize | |
15724 | ||
15725 | See @ref{7,,Implementation Defined Pragmas}. | |
15726 | ||
15727 | ||
15728 | @itemize * | |
15729 | ||
15730 | @item | |
15731 | “Effect of pragma @code{Optimize}. See 2.8(27).” | |
15732 | @end itemize | |
15733 | ||
15734 | Pragma @code{Optimize}, if given with a @code{Time} or @code{Space} | |
15735 | parameter, checks that the optimization flag is set, and aborts if it is | |
15736 | not. | |
15737 | ||
15738 | ||
15739 | @itemize * | |
15740 | ||
15741 | @item | |
15742 | “The message string associated with the Assertion_Error exception raised | |
15743 | by the failure of a predicate check if there is no applicable | |
15744 | Predicate_Failure aspect. See 3.2.4(31).” | |
15745 | @end itemize | |
15746 | ||
15747 | In the case of a Dynamic_Predicate aspect, the string is | |
15748 | “Dynamic_Predicate failed at <source position>”, where | |
15749 | “<source position>” might be something like “foo.adb:123”. | |
15750 | The Static_Predicate case is handled analogously. | |
15751 | ||
15752 | ||
15753 | @itemize * | |
15754 | ||
15755 | @item | |
15756 | “The predefined integer types declared in | |
15757 | @code{Standard}. See 3.5.4(25).” | |
15758 | @end itemize | |
15759 | ||
15760 | ||
15761 | @multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} | |
15762 | @headitem | |
15763 | ||
15764 | Type | |
15765 | ||
15766 | @tab | |
15767 | ||
15768 | Representation | |
15769 | ||
15770 | @item | |
15771 | ||
15772 | `Short_Short_Integer' | |
15773 | ||
15774 | @tab | |
15775 | ||
15776 | 8-bit signed | |
15777 | ||
15778 | @item | |
15779 | ||
15780 | `Short_Integer' | |
15781 | ||
15782 | @tab | |
15783 | ||
15784 | 16-bit signed | |
15785 | ||
15786 | @item | |
15787 | ||
15788 | `Integer' | |
15789 | ||
15790 | @tab | |
15791 | ||
15792 | 32-bit signed | |
15793 | ||
15794 | @item | |
15795 | ||
15796 | `Long_Integer' | |
15797 | ||
15798 | @tab | |
15799 | ||
15800 | 64-bit signed (on most 64-bit targets, | |
15801 | depending on the C definition of long) | |
15802 | 32-bit signed (on all other targets) | |
15803 | ||
15804 | @item | |
15805 | ||
15806 | `Long_Long_Integer' | |
15807 | ||
15808 | @tab | |
15809 | ||
15810 | 64-bit signed | |
15811 | ||
15812 | @item | |
15813 | ||
15814 | `Long_Long_Long_Integer' | |
15815 | ||
15816 | @tab | |
15817 | ||
15818 | 128-bit signed (on 64-bit targets) | |
15819 | 64-bit signed (on 32-bit targets) | |
15820 | ||
15821 | @end multitable | |
15822 | ||
15823 | ||
15824 | ||
15825 | @itemize * | |
15826 | ||
15827 | @item | |
15828 | “Any nonstandard integer types and the operators defined | |
15829 | for them. See 3.5.4(26).” | |
15830 | @end itemize | |
15831 | ||
15832 | There are no nonstandard integer types. | |
15833 | ||
15834 | ||
15835 | @itemize * | |
15836 | ||
15837 | @item | |
15838 | “Any nonstandard real types and the operators defined for | |
15839 | them. See 3.5.6(8).” | |
15840 | @end itemize | |
15841 | ||
15842 | There are no nonstandard real types. | |
15843 | ||
15844 | ||
15845 | @itemize * | |
15846 | ||
15847 | @item | |
15848 | “What combinations of requested decimal precision and range | |
15849 | are supported for floating point types. See 3.5.7(7).” | |
15850 | @end itemize | |
15851 | ||
15852 | The precision and range are defined by the IEEE Standard for Floating-Point | |
15853 | Arithmetic (IEEE 754-2019). | |
15854 | ||
15855 | ||
15856 | @itemize * | |
15857 | ||
15858 | @item | |
15859 | “The predefined floating point types declared in | |
15860 | @code{Standard}. See 3.5.7(16).” | |
15861 | @end itemize | |
15862 | ||
15863 | ||
15864 | @multitable {xxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} | |
15865 | @headitem | |
15866 | ||
15867 | Type | |
15868 | ||
15869 | @tab | |
15870 | ||
15871 | Representation | |
15872 | ||
15873 | @item | |
15874 | ||
15875 | `Short_Float' | |
15876 | ||
15877 | @tab | |
15878 | ||
15879 | IEEE Binary32 (Single) | |
15880 | ||
15881 | @item | |
15882 | ||
15883 | `Float' | |
15884 | ||
15885 | @tab | |
15886 | ||
15887 | IEEE Binary32 (Single) | |
15888 | ||
15889 | @item | |
15890 | ||
15891 | `Long_Float' | |
15892 | ||
15893 | @tab | |
15894 | ||
15895 | IEEE Binary64 (Double) | |
15896 | ||
15897 | @item | |
15898 | ||
15899 | `Long_Long_Float' | |
15900 | ||
15901 | @tab | |
15902 | ||
15903 | IEEE Binary64 (Double) on non-x86 architectures | |
15904 | IEEE 80-bit Extended on x86 architecture | |
15905 | ||
15906 | @end multitable | |
15907 | ||
15908 | ||
15909 | The default rounding mode specified by the IEEE 754 Standard is assumed both | |
15910 | for static and dynamic computations (that is, round to nearest, ties to even). | |
15911 | The input routines yield correctly rounded values for Short_Float, Float, and | |
15912 | Long_Float at least. The output routines can compute up to twice as many exact | |
15913 | digits as the value of @code{T'Digits} for any type, for example 30 digits for | |
15914 | Long_Float; if more digits are requested, zeros are printed. | |
15915 | ||
15916 | ||
15917 | @itemize * | |
15918 | ||
15919 | @item | |
15920 | “The small of an ordinary fixed point type. See 3.5.9(8).” | |
15921 | @end itemize | |
15922 | ||
15923 | The small is the largest power of two that does not exceed the delta. | |
15924 | ||
15925 | ||
15926 | @itemize * | |
15927 | ||
15928 | @item | |
15929 | “What combinations of small, range, and digits are | |
15930 | supported for fixed point types. See 3.5.9(10).” | |
15931 | @end itemize | |
15932 | ||
15933 | For an ordinary fixed point type, on 32-bit platforms, the small must lie in | |
15934 | 2.0**(-80) .. 2.0**80 and the range in -9.0E+36 .. 9.0E+36; any combination | |
15935 | is permitted that does not result in a mantissa larger than 63 bits. | |
15936 | ||
15937 | On 64-bit platforms, the small must lie in 2.0**(-127) .. 2.0**127 and the | |
15938 | range in -1.0E+76 .. 1.0E+76; any combination is permitted that does not | |
15939 | result in a mantissa larger than 63 bits, and any combination is permitted | |
15940 | that results in a mantissa between 64 and 127 bits if the small is the | |
15941 | ratio of two integers that lie in 1 .. 2.0**127. | |
15942 | ||
15943 | If the small is the ratio of two integers with 64-bit magnitude on 32-bit | |
15944 | platforms and 128-bit magnitude on 64-bit platforms, which is the case if | |
15945 | no @code{small} clause is provided, then the operations of the fixed point | |
15946 | type are entirely implemented by means of integer instructions. In the | |
15947 | other cases, some operations, in particular input and output, may be | |
15948 | implemented by means of floating-point instructions and may be affected | |
15949 | by accuracy issues on architectures other than x86. | |
15950 | ||
15951 | For a decimal fixed point type, on 32-bit platforms, the small must lie in | |
15952 | 1.0E-18 .. 1.0E+18 and the digits in 1 .. 18. On 64-bit platforms, the | |
15953 | small must lie in 1.0E-38 .. 1.0E+38 and the digits in 1 .. 38. | |
15954 | ||
15955 | ||
15956 | @itemize * | |
15957 | ||
15958 | @item | |
15959 | “The result of @code{Tags.Expanded_Name} for types declared | |
15960 | within an unnamed `block_statement'. See 3.9(10).” | |
15961 | @end itemize | |
15962 | ||
15963 | Block numbers of the form @code{B@var{nnn}}, where `nnn' is a | |
15964 | decimal integer are allocated. | |
15965 | ||
15966 | ||
15967 | @itemize * | |
15968 | ||
15969 | @item | |
15970 | “The sequence of characters of the value returned by Tags.Expanded_Name | |
15971 | (respectively, Tags.Wide_Expanded_Name) when some of the graphic | |
15972 | characters of Tags.Wide_Wide_Expanded_Name are not defined in Character | |
15973 | (respectively, Wide_Character). See 3.9(10.1).” | |
15974 | @end itemize | |
15975 | ||
15976 | This is handled in the same way as the implementation-defined behavior | |
15977 | referenced in A.4.12(34). | |
15978 | ||
15979 | ||
15980 | @itemize * | |
15981 | ||
15982 | @item | |
15983 | “Implementation-defined attributes. See 4.1.4(12).” | |
15984 | @end itemize | |
15985 | ||
15986 | See @ref{8,,Implementation Defined Attributes}. | |
15987 | ||
15988 | ||
15989 | @itemize * | |
15990 | ||
15991 | @item | |
15992 | “The value of the parameter to Empty for some container aggregates. | |
15993 | See 4.3.5(40).” | |
15994 | @end itemize | |
15995 | ||
15996 | As per the suggestion given in the Annotated Ada RM, the default value | |
15997 | of the formal parameter is used if one exists and zero is used otherwise. | |
15998 | ||
15999 | ||
16000 | @itemize * | |
16001 | ||
16002 | @item | |
16003 | “The maximum number of chunks for a parallel reduction expression without | |
16004 | a chunk_specification. See 4.5.10(21).” | |
16005 | @end itemize | |
16006 | ||
16007 | Feature unimplemented. | |
16008 | ||
16009 | ||
16010 | @itemize * | |
16011 | ||
16012 | @item | |
16013 | “Rounding of real static expressions which are exactly half-way between | |
16014 | two machine numbers. See 4.9(38).” | |
16015 | @end itemize | |
16016 | ||
16017 | Round to even is used in all such cases. | |
16018 | ||
16019 | ||
16020 | @itemize * | |
16021 | ||
16022 | @item | |
16023 | “The maximum number of chunks for a parallel generalized iterator without | |
16024 | a chunk_specification. See 5.5.2(10).” | |
16025 | @end itemize | |
16026 | ||
16027 | Feature unimplemented. | |
16028 | ||
16029 | ||
16030 | @itemize * | |
16031 | ||
16032 | @item | |
16033 | “The number of chunks for an array component iterator. See 5.5.2(11).” | |
16034 | @end itemize | |
16035 | ||
16036 | Feature unimplemented. | |
16037 | ||
16038 | ||
16039 | @itemize * | |
16040 | ||
16041 | @item | |
16042 | “Any extensions of the Global aspect. See 6.1.2(43).” | |
16043 | @end itemize | |
16044 | ||
16045 | Feature unimplemented. | |
16046 | ||
16047 | ||
16048 | @itemize * | |
16049 | ||
16050 | @item | |
16051 | “The circumstances the implementation passes in the null value for a view | |
16052 | conversion of an access type used as an out parameter. See 6.4.1(19).” | |
16053 | @end itemize | |
16054 | ||
16055 | Difficult to characterize. | |
16056 | ||
16057 | ||
16058 | @itemize * | |
16059 | ||
16060 | @item | |
16061 | “Any extensions of the Default_Initial_Condition aspect. See 7.3.3(11).” | |
16062 | @end itemize | |
16063 | ||
16064 | SPARK allows specifying `null' as the Default_Initial_Condition | |
16065 | aspect of a type. See the SPARK reference manual for further details. | |
16066 | ||
16067 | ||
16068 | @itemize * | |
16069 | ||
16070 | @item | |
16071 | “Any implementation-defined time types. See 9.6(6).” | |
16072 | @end itemize | |
16073 | ||
16074 | There are no implementation-defined time types. | |
16075 | ||
16076 | ||
16077 | @itemize * | |
16078 | ||
16079 | @item | |
16080 | “The time base associated with relative delays. See 9.6(20).” | |
16081 | @end itemize | |
16082 | ||
16083 | See 9.6(20). The time base used is that provided by the C library | |
16084 | function @code{gettimeofday}. | |
16085 | ||
16086 | ||
16087 | @itemize * | |
16088 | ||
16089 | @item | |
16090 | “The time base of the type @code{Calendar.Time}. See 9.6(23).” | |
16091 | @end itemize | |
16092 | ||
16093 | The time base used is that provided by the C library function | |
16094 | @code{gettimeofday}. | |
16095 | ||
16096 | ||
16097 | @itemize * | |
16098 | ||
16099 | @item | |
16100 | “The time zone used for package @code{Calendar} | |
16101 | operations. See 9.6(24).” | |
16102 | @end itemize | |
16103 | ||
16104 | The time zone used by package @code{Calendar} is the current system time zone | |
16105 | setting for local time, as accessed by the C library function | |
16106 | @code{localtime}. | |
16107 | ||
16108 | ||
16109 | @itemize * | |
16110 | ||
16111 | @item | |
16112 | “Any limit on `delay_until_statements' of | |
16113 | `select_statements'. See 9.6(29).” | |
16114 | @end itemize | |
16115 | ||
16116 | There are no such limits. | |
16117 | ||
16118 | ||
16119 | @itemize * | |
16120 | ||
16121 | @item | |
16122 | “The result of Calendar.Formatting.Image if its argument represents more | |
16123 | than 100 hours. See 9.6.1(86).” | |
16124 | @end itemize | |
16125 | ||
16126 | Calendar.Time_Error is raised. | |
16127 | ||
16128 | ||
16129 | @itemize * | |
16130 | ||
16131 | @item | |
16132 | “Implementation-defined conflict check policies. See 9.10.1(5).” | |
16133 | @end itemize | |
16134 | ||
16135 | There are no implementation-defined conflict check policies. | |
16136 | ||
16137 | ||
16138 | @itemize * | |
16139 | ||
16140 | @item | |
16141 | “The representation for a compilation. See 10.1(2).” | |
16142 | @end itemize | |
16143 | ||
16144 | A compilation is represented by a sequence of files presented to the | |
16145 | compiler in a single invocation of the `gcc' command. | |
16146 | ||
16147 | ||
16148 | @itemize * | |
16149 | ||
16150 | @item | |
16151 | “Any restrictions on compilations that contain multiple | |
16152 | compilation_units. See 10.1(4).” | |
16153 | @end itemize | |
16154 | ||
16155 | No single file can contain more than one compilation unit, but any | |
16156 | sequence of files can be presented to the compiler as a single | |
16157 | compilation. | |
16158 | ||
16159 | ||
16160 | @itemize * | |
16161 | ||
16162 | @item | |
16163 | “The mechanisms for creating an environment and for adding | |
16164 | and replacing compilation units. See 10.1.4(3).” | |
16165 | @end itemize | |
16166 | ||
16167 | See separate section on compilation model. | |
16168 | ||
16169 | ||
16170 | @itemize * | |
16171 | ||
16172 | @item | |
16173 | “The manner of explicitly assigning library units to a | |
16174 | partition. See 10.2(2).” | |
16175 | @end itemize | |
16176 | ||
16177 | If a unit contains an Ada main program, then the Ada units for the partition | |
16178 | are determined by recursive application of the rules in the Ada Reference | |
16179 | Manual section 10.2(2-6). In other words, the Ada units will be those that | |
16180 | are needed by the main program, and then this definition of need is applied | |
16181 | recursively to those units, and the partition contains the transitive | |
16182 | closure determined by this relationship. In short, all the necessary units | |
16183 | are included, with no need to explicitly specify the list. If additional | |
16184 | units are required, e.g., by foreign language units, then all units must be | |
16185 | mentioned in the context clause of one of the needed Ada units. | |
16186 | ||
16187 | If the partition contains no main program, or if the main program is in | |
16188 | a language other than Ada, then GNAT | |
16189 | provides the binder options `-z' and `-n' respectively, and in | |
16190 | this case a list of units can be explicitly supplied to the binder for | |
16191 | inclusion in the partition (all units needed by these units will also | |
16192 | be included automatically). For full details on the use of these | |
16193 | options, refer to `GNAT Make Program gnatmake' in the | |
16194 | @cite{GNAT User’s Guide}. | |
16195 | ||
16196 | ||
16197 | @itemize * | |
16198 | ||
16199 | @item | |
16200 | “The implementation-defined means, if any, of specifying which compilation | |
16201 | units are needed by a given compilation unit. See 10.2(2).” | |
16202 | @end itemize | |
16203 | ||
16204 | The units needed by a given compilation unit are as defined in | |
16205 | the Ada Reference Manual section 10.2(2-6). There are no | |
16206 | implementation-defined pragmas or other implementation-defined | |
16207 | means for specifying needed units. | |
16208 | ||
16209 | ||
16210 | @itemize * | |
16211 | ||
16212 | @item | |
16213 | “The manner of designating the main subprogram of a | |
16214 | partition. See 10.2(7).” | |
16215 | @end itemize | |
16216 | ||
16217 | The main program is designated by providing the name of the | |
16218 | corresponding @code{ALI} file as the input parameter to the binder. | |
16219 | ||
16220 | ||
16221 | @itemize * | |
16222 | ||
16223 | @item | |
16224 | “The order of elaboration of `library_items'. See 10.2(18).” | |
16225 | @end itemize | |
16226 | ||
16227 | The first constraint on ordering is that it meets the requirements of | |
16228 | Chapter 10 of the Ada Reference Manual. This still leaves some | |
16229 | implementation-dependent choices, which are resolved by analyzing | |
16230 | the elaboration code of each unit and identifying implicit | |
16231 | elaboration-order dependencies. | |
16232 | ||
16233 | ||
16234 | @itemize * | |
16235 | ||
16236 | @item | |
16237 | “Parameter passing and function return for the main | |
16238 | subprogram. See 10.2(21).” | |
16239 | @end itemize | |
16240 | ||
16241 | The main program has no parameters. It may be a procedure, or a function | |
16242 | returning an integer type. In the latter case, the returned integer | |
16243 | value is the return code of the program (overriding any value that | |
16244 | may have been set by a call to @code{Ada.Command_Line.Set_Exit_Status}). | |
16245 | ||
16246 | ||
16247 | @itemize * | |
16248 | ||
16249 | @item | |
16250 | “The mechanisms for building and running partitions. See 10.2(24).” | |
16251 | @end itemize | |
16252 | ||
16253 | GNAT itself supports programs with only a single partition. The GNATDIST | |
16254 | tool provided with the GLADE package (which also includes an implementation | |
16255 | of the PCS) provides a completely flexible method for building and running | |
16256 | programs consisting of multiple partitions. See the separate GLADE manual | |
16257 | for details. | |
16258 | ||
16259 | ||
16260 | @itemize * | |
16261 | ||
16262 | @item | |
16263 | “The details of program execution, including program | |
16264 | termination. See 10.2(25).” | |
16265 | @end itemize | |
16266 | ||
16267 | See separate section on compilation model. | |
16268 | ||
16269 | ||
16270 | @itemize * | |
16271 | ||
16272 | @item | |
16273 | “The semantics of any non-active partitions supported by the | |
16274 | implementation. See 10.2(28).” | |
16275 | @end itemize | |
16276 | ||
16277 | Passive partitions are supported on targets where shared memory is | |
16278 | provided by the operating system. See the GLADE reference manual for | |
16279 | further details. | |
16280 | ||
16281 | ||
16282 | @itemize * | |
16283 | ||
16284 | @item | |
16285 | “The information returned by @code{Exception_Message}. See 11.4.1(10).” | |
16286 | @end itemize | |
16287 | ||
16288 | Exception message returns the null string unless a specific message has | |
16289 | been passed by the program. | |
16290 | ||
16291 | ||
16292 | @itemize * | |
16293 | ||
16294 | @item | |
16295 | “The result of @code{Exceptions.Exception_Name} for types | |
16296 | declared within an unnamed `block_statement'. See 11.4.1(12).” | |
16297 | @end itemize | |
16298 | ||
16299 | Blocks have implementation defined names of the form @code{B@var{nnn}} | |
16300 | where `nnn' is an integer. | |
16301 | ||
16302 | ||
16303 | @itemize * | |
16304 | ||
16305 | @item | |
16306 | “The information returned by | |
16307 | @code{Exception_Information}. See 11.4.1(13).” | |
16308 | @end itemize | |
16309 | ||
16310 | @code{Exception_Information} returns a string in the following format: | |
16311 | ||
16312 | @example | |
16313 | *Exception_Name:* nnnnn | |
16314 | *Message:* mmmmm | |
16315 | *PID:* ppp | |
16316 | *Load address:* 0xhhhh | |
16317 | *Call stack traceback locations:* | |
16318 | 0xhhhh 0xhhhh 0xhhhh ... 0xhhh | |
16319 | @end example | |
16320 | ||
16321 | where | |
16322 | ||
16323 | @quotation | |
16324 | ||
16325 | ||
16326 | @itemize * | |
16327 | ||
16328 | @item | |
16329 | @code{nnnn} is the fully qualified name of the exception in all upper | |
16330 | case letters. This line is always present. | |
16331 | ||
16332 | @item | |
16333 | @code{mmmm} is the message (this line present only if message is non-null) | |
16334 | ||
16335 | @item | |
16336 | @code{ppp} is the Process Id value as a decimal integer (this line is | |
16337 | present only if the Process Id is nonzero). Currently we are | |
16338 | not making use of this field. | |
16339 | ||
16340 | @item | |
16341 | The Load address line, the Call stack traceback locations line and the | |
16342 | following values are present only if at least one traceback location was | |
16343 | recorded. The Load address indicates the address at which the main executable | |
16344 | was loaded; this line may not be present if operating system hasn’t relocated | |
16345 | the main executable. The values are given in C style format, with lower case | |
16346 | letters for a-f, and only as many digits present as are necessary. | |
16347 | The line terminator sequence at the end of each line, including | |
16348 | the last line is a single @code{LF} character (@code{16#0A#}). | |
16349 | @end itemize | |
16350 | @end quotation | |
16351 | ||
16352 | ||
16353 | @itemize * | |
16354 | ||
16355 | @item | |
16356 | “The sequence of characters of the value returned by | |
16357 | Exceptions.Exception_Name (respectively, Exceptions.Wide_Exception_Name) | |
16358 | when some of the graphic characters of Exceptions.Wide_Wide_Exception_Name | |
16359 | are not defined in Character (respectively, Wide_Character). | |
16360 | See 11.4.1(12.1).” | |
16361 | @end itemize | |
16362 | ||
16363 | This is handled in the same way as the implementation-defined behavior | |
16364 | referenced in A.4.12(34). | |
16365 | ||
16366 | ||
16367 | @itemize * | |
16368 | ||
16369 | @item | |
16370 | “The information returned by Exception_Information. See 11.4.1(13).” | |
16371 | @end itemize | |
16372 | ||
16373 | The exception name and the source location at which the exception was | |
16374 | raised are included. | |
16375 | ||
16376 | ||
16377 | @itemize * | |
16378 | ||
16379 | @item | |
16380 | “Implementation-defined policy_identifiers and assertion_aspect_marks | |
16381 | allowed in a pragma Assertion_Policy. See 11.4.2(9).” | |
16382 | @end itemize | |
16383 | ||
16384 | Implementation-defined assertion_aspect_marks include Assert_And_Cut, | |
16385 | Assume, Contract_Cases, Debug, Ghost, Initial_Condition, Loop_Invariant, | |
16386 | Loop_Variant, Postcondition, Precondition, Predicate, Refined_Post, | |
16387 | Statement_Assertions, and Subprogram_Variant. Implementation-defined | |
16388 | policy_identifiers include Ignore and Suppressible. | |
16389 | ||
16390 | ||
16391 | @itemize * | |
16392 | ||
16393 | @item | |
16394 | “The default assertion policy. See 11.4.2(10).” | |
16395 | @end itemize | |
16396 | ||
16397 | The default assertion policy is Ignore, although this can be overridden | |
16398 | via compiler switches such as “-gnata”. | |
16399 | ||
16400 | ||
16401 | @itemize * | |
16402 | ||
16403 | @item | |
16404 | “Implementation-defined check names. See 11.5(27).” | |
16405 | @end itemize | |
16406 | ||
16407 | The implementation defined check names include Alignment_Check, | |
16408 | Atomic_Synchronization, Duplicated_Tag_Check, Container_Checks, | |
16409 | Tampering_Check, Predicate_Check, and Validity_Check. In addition, a user | |
16410 | program can add implementation-defined check names by means of the pragma | |
16411 | Check_Name. See the description of pragma @code{Suppress} for full details. | |
16412 | ||
16413 | ||
16414 | @itemize * | |
16415 | ||
16416 | @item | |
16417 | “Existence and meaning of second parameter of pragma Unsuppress. | |
16418 | See 11.5(27.1).” | |
16419 | @end itemize | |
16420 | ||
16421 | The legality rules for and semantics of the second parameter of pragma | |
16422 | Unsuppress match those for the second argument of pragma Suppress. | |
16423 | ||
16424 | ||
16425 | @itemize * | |
16426 | ||
16427 | @item | |
16428 | “The cases that cause conflicts between the representation of the | |
16429 | ancestors of a type_declaration. See 13.1(13.1).” | |
16430 | @end itemize | |
16431 | ||
16432 | No such cases exist. | |
16433 | ||
16434 | ||
16435 | @itemize * | |
16436 | ||
16437 | @item | |
16438 | “The interpretation of each representation aspect. See 13.1(20).” | |
16439 | @end itemize | |
16440 | ||
16441 | See separate section on data representations. | |
16442 | ||
16443 | ||
16444 | @itemize * | |
16445 | ||
16446 | @item | |
16447 | “Any restrictions placed upon the specification of representation aspects. | |
16448 | See 13.1(20).” | |
16449 | @end itemize | |
16450 | ||
16451 | See separate section on data representations. | |
16452 | ||
16453 | ||
16454 | @itemize * | |
16455 | ||
16456 | @item | |
16457 | “Implementation-defined aspects, including the syntax for specifying | |
16458 | such aspects and the legality rules for such aspects. See 13.1.1(38).” | |
16459 | @end itemize | |
16460 | ||
b71d4b62 | 16461 | See @ref{123,,Implementation Defined Aspects}. |
64d5610f ML |
16462 | |
16463 | ||
16464 | @itemize * | |
16465 | ||
16466 | @item | |
16467 | “The set of machine scalars. See 13.3(8.1).” | |
16468 | @end itemize | |
16469 | ||
16470 | See separate section on data representations. | |
16471 | ||
16472 | ||
16473 | @itemize * | |
16474 | ||
16475 | @item | |
16476 | “The meaning of @code{Size} for indefinite subtypes. See 13.3(48).” | |
16477 | @end itemize | |
16478 | ||
16479 | The Size attribute of an indefinite subtype is not less than the Size | |
16480 | attribute of any object of that type. | |
16481 | ||
16482 | ||
16483 | @itemize * | |
16484 | ||
16485 | @item | |
16486 | “The meaning of Object_Size for indefinite subtypes. See 13.3(58).” | |
16487 | @end itemize | |
16488 | ||
16489 | The Object_Size attribute of an indefinite subtype is not less than the | |
16490 | Object_Size attribute of any object of that type. | |
16491 | ||
16492 | ||
16493 | @itemize * | |
16494 | ||
16495 | @item | |
16496 | “The default external representation for a type tag. See 13.3(75).” | |
16497 | @end itemize | |
16498 | ||
16499 | The default external representation for a type tag is the fully expanded | |
16500 | name of the type in upper case letters. | |
16501 | ||
16502 | ||
16503 | @itemize * | |
16504 | ||
16505 | @item | |
16506 | “What determines whether a compilation unit is the same in | |
16507 | two different partitions. See 13.3(76).” | |
16508 | @end itemize | |
16509 | ||
16510 | A compilation unit is the same in two different partitions if and only | |
16511 | if it derives from the same source file. | |
16512 | ||
16513 | ||
16514 | @itemize * | |
16515 | ||
16516 | @item | |
16517 | “Implementation-defined components. See 13.5.1(15).” | |
16518 | @end itemize | |
16519 | ||
16520 | The only implementation defined component is the tag for a tagged type, | |
16521 | which contains a pointer to the dispatching table. | |
16522 | ||
16523 | ||
16524 | @itemize * | |
16525 | ||
16526 | @item | |
16527 | “If @code{Word_Size} = @code{Storage_Unit}, the default bit | |
16528 | ordering. See 13.5.3(5).” | |
16529 | @end itemize | |
16530 | ||
16531 | @code{Word_Size} (32) is not the same as @code{Storage_Unit} (8) for this | |
16532 | implementation, so no non-default bit ordering is supported. The default | |
16533 | bit ordering corresponds to the natural endianness of the target architecture. | |
16534 | ||
16535 | ||
16536 | @itemize * | |
16537 | ||
16538 | @item | |
16539 | “The contents of the visible part of package @code{System}. See 13.7(2).” | |
16540 | @end itemize | |
16541 | ||
16542 | See the definition of package System in @code{system.ads}. | |
16543 | Note that two declarations are added to package System. | |
16544 | ||
16545 | @example | |
16546 | Max_Priority : constant Positive := Priority'Last; | |
16547 | Max_Interrupt_Priority : constant Positive := Interrupt_Priority'Last; | |
16548 | @end example | |
16549 | ||
16550 | ||
16551 | @itemize * | |
16552 | ||
16553 | @item | |
16554 | “The range of Storage_Elements.Storage_Offset, the modulus of | |
16555 | Storage_Elements.Storage_Element, and the declaration of | |
16556 | Storage_Elements.Integer_Address. See 13.7.1(11).” | |
16557 | @end itemize | |
16558 | ||
16559 | See the definition of package System.Storage_Elements in @code{s-stoele.ads}. | |
16560 | ||
16561 | ||
16562 | @itemize * | |
16563 | ||
16564 | @item | |
16565 | “The contents of the visible part of package @code{System.Machine_Code}, | |
16566 | and the meaning of `code_statements'. See 13.8(7).” | |
16567 | @end itemize | |
16568 | ||
16569 | See the definition and documentation in file @code{s-maccod.ads}. | |
16570 | ||
16571 | ||
16572 | @itemize * | |
16573 | ||
16574 | @item | |
16575 | “The result of unchecked conversion for instances with scalar result | |
16576 | types whose result is not defined by the language. See 13.9(11).” | |
16577 | @end itemize | |
16578 | ||
16579 | Unchecked conversion between types of the same size | |
16580 | results in an uninterpreted transmission of the bits from one type | |
16581 | to the other. If the types are of unequal sizes, then in the case of | |
16582 | discrete types, a shorter source is first zero or sign extended as | |
16583 | necessary, and a shorter target is simply truncated on the left. | |
16584 | For all non-discrete types, the source is first copied if necessary | |
16585 | to ensure that the alignment requirements of the target are met, then | |
16586 | a pointer is constructed to the source value, and the result is obtained | |
16587 | by dereferencing this pointer after converting it to be a pointer to the | |
16588 | target type. Unchecked conversions where the target subtype is an | |
16589 | unconstrained array are not permitted. If the target alignment is | |
16590 | greater than the source alignment, then a copy of the result is | |
16591 | made with appropriate alignment | |
16592 | ||
16593 | ||
16594 | @itemize * | |
16595 | ||
16596 | @item | |
16597 | “The result of unchecked conversion for instances with nonscalar result | |
16598 | types whose result is not defined by the language. See 13.9(11).” | |
16599 | @end itemize | |
16600 | ||
16601 | See preceding definition for the scalar result case. | |
16602 | ||
16603 | ||
16604 | @itemize * | |
16605 | ||
16606 | @item | |
16607 | “Whether or not the implementation provides user-accessible | |
16608 | names for the standard pool type(s). See 13.11(17).” | |
16609 | @end itemize | |
16610 | ||
16611 | There are 3 different standard pools used by the compiler when | |
16612 | @code{Storage_Pool} is not specified depending whether the type is local | |
16613 | to a subprogram or defined at the library level and whether | |
16614 | @code{Storage_Size`@w{`}is specified or not. See documentation in the runtime | |
16615 | library units `@w{`}System.Pool_Global}, @code{System.Pool_Size} and | |
16616 | @code{System.Pool_Local} in files @code{s-poosiz.ads}, | |
16617 | @code{s-pooglo.ads} and @code{s-pooloc.ads} for full details on the | |
16618 | default pools used. All these pools are accessible by means of @cite{with}ing | |
16619 | these units. | |
16620 | ||
16621 | ||
16622 | @itemize * | |
16623 | ||
16624 | @item | |
16625 | “The meaning of @code{Storage_Size} when neither the Storage_Size nor the | |
16626 | Storage_Pool is specified for an access type. See 13.11(18).” | |
16627 | @end itemize | |
16628 | ||
16629 | @code{Storage_Size} is measured in storage units, and refers to the | |
16630 | total space available for an access type collection, or to the primary | |
16631 | stack space for a task. | |
16632 | ||
16633 | ||
16634 | @itemize * | |
16635 | ||
16636 | @item | |
16637 | “The effect of specifying aspect Default_Storage_Pool on an instance | |
16638 | of a language-defined generic unit. See 13.11.3(5).” | |
16639 | @end itemize | |
16640 | ||
16641 | Instances of language-defined generic units are treated the same as other | |
16642 | instances with respect to the Default_Storage_Pool aspect. | |
16643 | ||
16644 | ||
16645 | @itemize * | |
16646 | ||
16647 | @item | |
16648 | “Implementation-defined restrictions allowed in a pragma | |
16649 | @code{Restrictions}. See 13.12(8.7).” | |
16650 | @end itemize | |
16651 | ||
16652 | See @ref{9,,Standard and Implementation Defined Restrictions}. | |
16653 | ||
16654 | ||
16655 | @itemize * | |
16656 | ||
16657 | @item | |
16658 | “The consequences of violating limitations on | |
16659 | @code{Restrictions} pragmas. See 13.12(9).” | |
16660 | @end itemize | |
16661 | ||
16662 | Restrictions that can be checked at compile time are enforced at | |
16663 | compile time; violations are illegal. For other restrictions, any | |
16664 | violation during program execution results in erroneous execution. | |
16665 | ||
16666 | ||
16667 | @itemize * | |
16668 | ||
16669 | @item | |
16670 | “Implementation-defined usage profiles allowed in a pragma Profile. | |
16671 | See 13.12(15).” | |
16672 | @end itemize | |
16673 | ||
16674 | See @ref{7,,Implementation Defined Pragmas}. | |
16675 | ||
16676 | ||
16677 | @itemize * | |
16678 | ||
16679 | @item | |
16680 | “The contents of the stream elements read and written by the Read and | |
16681 | Write attributes of elementary types. See 13.13.2(9).” | |
16682 | @end itemize | |
16683 | ||
16684 | The representation is the in-memory representation of the base type of | |
16685 | the type, using the number of bits corresponding to the | |
16686 | @code{type'Size} value, and the natural ordering of the machine. | |
16687 | ||
16688 | ||
16689 | @itemize * | |
16690 | ||
16691 | @item | |
16692 | “The names and characteristics of the numeric subtypes | |
16693 | declared in the visible part of package @code{Standard}. See A.1(3).” | |
16694 | @end itemize | |
16695 | ||
16696 | See items describing the integer and floating-point types supported. | |
16697 | ||
16698 | ||
16699 | @itemize * | |
16700 | ||
16701 | @item | |
16702 | “The values returned by Strings.Hash. See A.4.9(3).” | |
16703 | @end itemize | |
16704 | ||
16705 | This hash function has predictable collisions and is subject to | |
16706 | equivalent substring attacks. It is not suitable for construction of a | |
16707 | hash table keyed on possibly malicious user input. | |
16708 | ||
16709 | ||
16710 | @itemize * | |
16711 | ||
16712 | @item | |
16713 | “The value returned by a call to a Text_Buffer Get procedure if any | |
16714 | character in the returned sequence is not defined in Character. | |
16715 | See A.4.12(34).” | |
16716 | @end itemize | |
16717 | ||
16718 | The contents of a buffer is represented internally as a UTF_8 string. | |
16719 | The value return by Text_Buffer.Get is the result of passing that | |
16720 | UTF_8 string to UTF_Encoding.Strings.Decode. | |
16721 | ||
16722 | ||
16723 | @itemize * | |
16724 | ||
16725 | @item | |
16726 | “The value returned by a call to a Text_Buffer Wide_Get procedure if | |
16727 | any character in the returned sequence is not defined in Wide_Character. | |
16728 | See A.4.12(34).” | |
16729 | @end itemize | |
16730 | ||
16731 | The contents of a buffer is represented internally as a UTF_8 string. | |
16732 | The value return by Text_Buffer.Wide_Get is the result of passing that | |
16733 | UTF_8 string to UTF_Encoding.Wide_Strings.Decode. | |
16734 | ||
16735 | ||
16736 | @itemize * | |
16737 | ||
16738 | @item | |
16739 | “The accuracy actually achieved by the elementary | |
16740 | functions. See A.5.1(1).” | |
16741 | @end itemize | |
16742 | ||
16743 | The elementary functions correspond to the functions available in the C | |
16744 | library. Only fast math mode is implemented. | |
16745 | ||
16746 | ||
16747 | @itemize * | |
16748 | ||
16749 | @item | |
16750 | “The sign of a zero result from some of the operators or | |
16751 | functions in @code{Numerics.Generic_Elementary_Functions}, when | |
16752 | @code{Float_Type'Signed_Zeros} is @code{True}. See A.5.1(46).” | |
16753 | @end itemize | |
16754 | ||
16755 | The sign of zeroes follows the requirements of the IEEE 754 standard on | |
16756 | floating-point. | |
16757 | ||
16758 | ||
16759 | @itemize * | |
16760 | ||
16761 | @item | |
16762 | “The value of | |
16763 | @code{Numerics.Float_Random.Max_Image_Width}. See A.5.2(27).” | |
16764 | @end itemize | |
16765 | ||
16766 | Maximum image width is 6864, see library file @code{s-rannum.ads}. | |
16767 | ||
16768 | ||
16769 | @itemize * | |
16770 | ||
16771 | @item | |
16772 | “The value of | |
16773 | @code{Numerics.Discrete_Random.Max_Image_Width}. See A.5.2(27).” | |
16774 | @end itemize | |
16775 | ||
16776 | Maximum image width is 6864, see library file @code{s-rannum.ads}. | |
16777 | ||
16778 | ||
16779 | @itemize * | |
16780 | ||
16781 | @item | |
16782 | “The string representation of a random number generator’s | |
16783 | state. See A.5.2(38).” | |
16784 | @end itemize | |
16785 | ||
16786 | The value returned by the Image function is the concatenation of | |
16787 | the fixed-width decimal representations of the 624 32-bit integers | |
16788 | of the state vector. | |
16789 | ||
16790 | ||
16791 | @itemize * | |
16792 | ||
16793 | @item | |
16794 | “The values of the @code{Model_Mantissa}, | |
16795 | @code{Model_Emin}, @code{Model_Epsilon}, @code{Model}, | |
16796 | @code{Safe_First}, and @code{Safe_Last} attributes, if the Numerics | |
16797 | Annex is not supported. See A.5.3(72).” | |
16798 | @end itemize | |
16799 | ||
16800 | Running the compiler with `-gnatS' to produce a listing of package | |
16801 | @code{Standard} displays the values of these attributes. | |
16802 | ||
16803 | ||
16804 | @itemize * | |
16805 | ||
16806 | @item | |
16807 | “The value of @code{Buffer_Size} in @code{Storage_IO}. See A.9(10).” | |
16808 | @end itemize | |
16809 | ||
16810 | All type representations are contiguous, and the @code{Buffer_Size} is | |
16811 | the value of @code{type'Size} rounded up to the next storage unit | |
16812 | boundary. | |
16813 | ||
16814 | ||
16815 | @itemize * | |
16816 | ||
16817 | @item | |
16818 | “External files for standard input, standard output, and | |
16819 | standard error See A.10(5).” | |
16820 | @end itemize | |
16821 | ||
16822 | These files are mapped onto the files provided by the C streams | |
16823 | libraries. See source file @code{i-cstrea.ads} for further details. | |
16824 | ||
16825 | ||
16826 | @itemize * | |
16827 | ||
16828 | @item | |
16829 | “The accuracy of the value produced by @code{Put}. See A.10.9(36).” | |
16830 | @end itemize | |
16831 | ||
16832 | If more digits are requested in the output than are represented by the | |
16833 | precision of the value, zeroes are output in the corresponding least | |
16834 | significant digit positions. | |
16835 | ||
16836 | ||
16837 | @itemize * | |
16838 | ||
16839 | @item | |
16840 | “Current size for a stream file for which positioning is not supported. | |
16841 | See A.12.1(1.1).” | |
16842 | @end itemize | |
16843 | ||
16844 | Positioning is supported. | |
16845 | ||
16846 | ||
16847 | @itemize * | |
16848 | ||
16849 | @item | |
16850 | “The meaning of @code{Argument_Count}, @code{Argument}, and | |
16851 | @code{Command_Name}. See A.15(1).” | |
16852 | @end itemize | |
16853 | ||
16854 | These are mapped onto the @code{argv} and @code{argc} parameters of the | |
16855 | main program in the natural manner. | |
16856 | ||
16857 | ||
16858 | @itemize * | |
16859 | ||
16860 | @item | |
16861 | “The interpretation of file names and directory names. See A.16(46).” | |
16862 | @end itemize | |
16863 | ||
16864 | These names are interpreted consistently with the underlying file system. | |
16865 | ||
16866 | ||
16867 | @itemize * | |
16868 | ||
16869 | @item | |
16870 | “The maxium value for a file size in Directories. See A.16(87).” | |
16871 | @end itemize | |
16872 | ||
16873 | Directories.File_Size’Last is equal to Long_Long_Integer’Last . | |
16874 | ||
16875 | ||
16876 | @itemize * | |
16877 | ||
16878 | @item | |
16879 | “The result for Directories.Size for a directory or special file. | |
16880 | See A.16(93).” | |
16881 | @end itemize | |
16882 | ||
16883 | Name_Error is raised. | |
16884 | ||
16885 | ||
16886 | @itemize * | |
16887 | ||
16888 | @item | |
16889 | “The result for Directories.Modification_Time for a directory or special file. | |
16890 | See A.16(93).” | |
16891 | @end itemize | |
16892 | ||
16893 | Name_Error is raised. | |
16894 | ||
16895 | ||
16896 | @itemize * | |
16897 | ||
16898 | @item | |
16899 | “The interpretation of a nonnull search pattern in Directories. | |
16900 | See A.16(104).” | |
16901 | @end itemize | |
16902 | ||
16903 | When the @code{Pattern} parameter is not the null string, it is interpreted | |
16904 | according to the syntax of regular expressions as defined in the | |
16905 | @code{GNAT.Regexp} package. | |
16906 | ||
73918baf | 16907 | See @ref{262,,GNAT.Regexp (g-regexp.ads)}. |
64d5610f ML |
16908 | |
16909 | ||
16910 | @itemize * | |
16911 | ||
16912 | @item | |
16913 | “The results of a Directories search if the contents of the directory are | |
16914 | altered while a search is in progress. See A.16(110).” | |
16915 | @end itemize | |
16916 | ||
16917 | The effect of a call to Get_Next_Entry is determined by the current | |
16918 | state of the directory. | |
16919 | ||
16920 | ||
16921 | @itemize * | |
16922 | ||
16923 | @item | |
16924 | “The definition and meaning of an environment variable. See A.17(1).” | |
16925 | @end itemize | |
16926 | ||
16927 | This definition is determined by the underlying operating system. | |
16928 | ||
16929 | ||
16930 | @itemize * | |
16931 | ||
16932 | @item | |
16933 | “The circumstances where an environment variable cannot be defined. | |
16934 | See A.17(16).” | |
f571a201 | 16935 | @end itemize |
64d5610f ML |
16936 | |
16937 | There are no such implementation-defined circumstances. | |
16938 | ||
f571a201 RD |
16939 | |
16940 | @itemize * | |
16941 | ||
64d5610f ML |
16942 | @item |
16943 | “Environment names for which Set has the effect of Clear. See A.17(17).” | |
16944 | @end itemize | |
16945 | ||
16946 | There are no such names. | |
16947 | ||
16948 | ||
16949 | @itemize * | |
16950 | ||
16951 | @item | |
16952 | “The value of Containers.Hash_Type’Modulus. The value of | |
16953 | Containers.Count_Type’Last. See A.18.1(7).” | |
16954 | @end itemize | |
16955 | ||
16956 | Containers.Hash_Type’Modulus is 2**32. | |
16957 | Containers.Count_Type’Last is 2**31 - 1. | |
16958 | ||
16959 | ||
16960 | @itemize * | |
16961 | ||
16962 | @item | |
16963 | “Implementation-defined convention names. See B.1(11).” | |
16964 | @end itemize | |
16965 | ||
16966 | The following convention names are supported | |
16967 | ||
16968 | ||
16969 | @multitable {xxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} | |
16970 | @headitem | |
16971 | ||
16972 | Convention Name | |
16973 | ||
16974 | @tab | |
16975 | ||
16976 | Interpretation | |
16977 | ||
16978 | @item | |
16979 | ||
16980 | `Ada' | |
16981 | ||
16982 | @tab | |
16983 | ||
16984 | Ada | |
16985 | ||
16986 | @item | |
16987 | ||
16988 | `Ada_Pass_By_Copy' | |
16989 | ||
16990 | @tab | |
16991 | ||
16992 | Allowed for any types except by-reference types such as limited | |
16993 | records. Compatible with convention Ada, but causes any parameters | |
16994 | with this convention to be passed by copy. | |
16995 | ||
16996 | @item | |
16997 | ||
16998 | `Ada_Pass_By_Reference' | |
16999 | ||
17000 | @tab | |
17001 | ||
17002 | Allowed for any types except by-copy types such as scalars. | |
17003 | Compatible with convention Ada, but causes any parameters | |
17004 | with this convention to be passed by reference. | |
17005 | ||
17006 | @item | |
17007 | ||
17008 | `Assembler' | |
17009 | ||
17010 | @tab | |
17011 | ||
17012 | Assembly language | |
17013 | ||
17014 | @item | |
17015 | ||
17016 | `Asm' | |
17017 | ||
17018 | @tab | |
17019 | ||
17020 | Synonym for Assembler | |
17021 | ||
17022 | @item | |
17023 | ||
17024 | `Assembly' | |
17025 | ||
17026 | @tab | |
17027 | ||
17028 | Synonym for Assembler | |
17029 | ||
17030 | @item | |
17031 | ||
17032 | `C' | |
17033 | ||
17034 | @tab | |
17035 | ||
17036 | C | |
17037 | ||
17038 | @item | |
17039 | ||
17040 | `C_Pass_By_Copy' | |
17041 | ||
17042 | @tab | |
17043 | ||
17044 | Allowed only for record types, like C, but also notes that record | |
17045 | is to be passed by copy rather than reference. | |
17046 | ||
17047 | @item | |
17048 | ||
17049 | `COBOL' | |
17050 | ||
17051 | @tab | |
17052 | ||
17053 | COBOL | |
17054 | ||
17055 | @item | |
17056 | ||
17057 | `C_Plus_Plus (or CPP)' | |
17058 | ||
17059 | @tab | |
17060 | ||
17061 | C++ | |
17062 | ||
17063 | @item | |
17064 | ||
17065 | `Default' | |
17066 | ||
17067 | @tab | |
17068 | ||
17069 | Treated the same as C | |
17070 | ||
17071 | @item | |
17072 | ||
17073 | `External' | |
17074 | ||
17075 | @tab | |
17076 | ||
17077 | Treated the same as C | |
17078 | ||
17079 | @item | |
17080 | ||
17081 | `Fortran' | |
17082 | ||
17083 | @tab | |
17084 | ||
17085 | Fortran | |
17086 | ||
17087 | @item | |
17088 | ||
17089 | `Intrinsic' | |
17090 | ||
17091 | @tab | |
17092 | ||
17093 | For support of pragma @code{Import} with convention Intrinsic, see | |
17094 | separate section on Intrinsic Subprograms. | |
17095 | ||
17096 | @item | |
17097 | ||
17098 | `Stdcall' | |
17099 | ||
17100 | @tab | |
17101 | ||
17102 | Stdcall (used for Windows implementations only). This convention correspond | |
17103 | to the WINAPI (previously called Pascal convention) C/C++ convention under | |
17104 | Windows. A routine with this convention cleans the stack before | |
17105 | exit. This pragma cannot be applied to a dispatching call. | |
17106 | ||
17107 | @item | |
17108 | ||
17109 | `DLL' | |
17110 | ||
17111 | @tab | |
17112 | ||
17113 | Synonym for Stdcall | |
17114 | ||
17115 | @item | |
17116 | ||
17117 | `Win32' | |
17118 | ||
17119 | @tab | |
17120 | ||
17121 | Synonym for Stdcall | |
17122 | ||
17123 | @item | |
17124 | ||
17125 | `Stubbed' | |
17126 | ||
17127 | @tab | |
17128 | ||
17129 | Stubbed is a special convention used to indicate that the body of the | |
17130 | subprogram will be entirely ignored. Any call to the subprogram | |
17131 | is converted into a raise of the @code{Program_Error} exception. If a | |
17132 | pragma @code{Import} specifies convention @code{stubbed} then no body need | |
17133 | be present at all. This convention is useful during development for the | |
17134 | inclusion of subprograms whose body has not yet been written. | |
17135 | In addition, all otherwise unrecognized convention names are also | |
17136 | treated as being synonymous with convention C. In all implementations, | |
17137 | use of such other names results in a warning. | |
17138 | ||
17139 | @end multitable | |
17140 | ||
17141 | ||
17142 | ||
17143 | @itemize * | |
17144 | ||
17145 | @item | |
17146 | “The meaning of link names. See B.1(36).” | |
17147 | @end itemize | |
17148 | ||
17149 | Link names are the actual names used by the linker. | |
17150 | ||
17151 | ||
17152 | @itemize * | |
17153 | ||
17154 | @item | |
17155 | “The manner of choosing link names when neither the link name nor the | |
17156 | address of an imported or exported entity is specified. See B.1(36).” | |
17157 | @end itemize | |
17158 | ||
17159 | The default linker name is that which would be assigned by the relevant | |
17160 | external language, interpreting the Ada name as being in all lower case | |
17161 | letters. | |
17162 | ||
17163 | ||
17164 | @itemize * | |
17165 | ||
17166 | @item | |
17167 | “The effect of pragma @code{Linker_Options}. See B.1(37).” | |
17168 | @end itemize | |
17169 | ||
17170 | The string passed to @code{Linker_Options} is presented uninterpreted as | |
17171 | an argument to the link command, unless it contains ASCII.NUL characters. | |
17172 | NUL characters if they appear act as argument separators, so for example | |
17173 | ||
17174 | @example | |
17175 | pragma Linker_Options ("-labc" & ASCII.NUL & "-ldef"); | |
17176 | @end example | |
17177 | ||
17178 | causes two separate arguments @code{-labc} and @code{-ldef} to be passed to the | |
17179 | linker. The order of linker options is preserved for a given unit. The final | |
17180 | list of options passed to the linker is in reverse order of the elaboration | |
17181 | order. For example, linker options for a body always appear before the options | |
17182 | from the corresponding package spec. | |
17183 | ||
17184 | ||
17185 | @itemize * | |
17186 | ||
17187 | @item | |
17188 | “The contents of the visible part of package | |
17189 | @code{Interfaces} and its language-defined descendants. See B.2(1).” | |
17190 | @end itemize | |
17191 | ||
17192 | See files with prefix @code{i-} in the distributed library. | |
17193 | ||
17194 | ||
17195 | @itemize * | |
17196 | ||
17197 | @item | |
17198 | “Implementation-defined children of package | |
17199 | @code{Interfaces}. The contents of the visible part of package | |
17200 | @code{Interfaces}. See B.2(11).” | |
17201 | @end itemize | |
17202 | ||
17203 | See files with prefix @code{i-} in the distributed library. | |
17204 | ||
17205 | ||
17206 | @itemize * | |
17207 | ||
17208 | @item | |
17209 | “The definitions of certain types and constants in Interfaces.C. | |
17210 | See B.3(41).” | |
17211 | @end itemize | |
17212 | ||
17213 | See source file @code{i-c.ads}. | |
17214 | ||
17215 | ||
17216 | @itemize * | |
17217 | ||
17218 | @item | |
17219 | “The types @code{Floating}, @code{Long_Floating}, | |
17220 | @code{Binary}, @code{Long_Binary}, @code{Decimal_ Element}, and | |
17221 | @code{COBOL_Character}; and the initialization of the variables | |
17222 | @code{Ada_To_COBOL} and @code{COBOL_To_Ada}, in | |
17223 | @code{Interfaces.COBOL}. See B.4(50).” | |
17224 | @end itemize | |
17225 | ||
17226 | ||
17227 | @multitable {xxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} | |
17228 | @headitem | |
17229 | ||
17230 | COBOL | |
17231 | ||
17232 | @tab | |
17233 | ||
17234 | Ada | |
17235 | ||
17236 | @item | |
17237 | ||
17238 | `Floating' | |
17239 | ||
17240 | @tab | |
17241 | ||
17242 | Float | |
17243 | ||
17244 | @item | |
17245 | ||
17246 | `Long_Floating' | |
17247 | ||
17248 | @tab | |
17249 | ||
17250 | (Floating) Long_Float | |
17251 | ||
17252 | @item | |
17253 | ||
17254 | `Binary' | |
17255 | ||
17256 | @tab | |
17257 | ||
17258 | Integer | |
17259 | ||
17260 | @item | |
17261 | ||
17262 | `Long_Binary' | |
17263 | ||
17264 | @tab | |
17265 | ||
17266 | Long_Long_Integer | |
17267 | ||
17268 | @item | |
17269 | ||
17270 | `Decimal_Element' | |
17271 | ||
17272 | @tab | |
17273 | ||
17274 | Character | |
17275 | ||
17276 | @item | |
17277 | ||
17278 | `COBOL_Character' | |
17279 | ||
17280 | @tab | |
17281 | ||
17282 | Character | |
17283 | ||
17284 | @end multitable | |
17285 | ||
17286 | ||
17287 | For initialization, see the file @code{i-cobol.ads} in the distributed library. | |
17288 | ||
17289 | ||
17290 | @itemize * | |
17291 | ||
17292 | @item | |
17293 | “The types Fortran_Integer, Real, Double_Precision, and Character_Set | |
17294 | in Interfaces.Fortran. See B.5(17).” | |
17295 | @end itemize | |
17296 | ||
17297 | See source file @code{i-fortra.ads}. These types are derived, respectively, | |
17298 | from Integer, Float, Long_Float, and Character. | |
17299 | ||
17300 | ||
17301 | @itemize * | |
17302 | ||
17303 | @item | |
17304 | “Implementation-defined intrinsic subprograms. See C.1(1).” | |
17305 | @end itemize | |
17306 | ||
17307 | See separate section on Intrinsic Subprograms. | |
17308 | ||
17309 | ||
17310 | @itemize * | |
17311 | ||
17312 | @item | |
17313 | “Any restrictions on a protected procedure or its containing type when an | |
17314 | aspect Attach_handler or Interrupt_Handler is specified. See C.3.1(17).” | |
17315 | @end itemize | |
17316 | ||
17317 | There are no such restrictions. | |
17318 | ||
17319 | ||
17320 | @itemize * | |
17321 | ||
17322 | @item | |
17323 | “Any other forms of interrupt handler supported by the Attach_Handler and | |
17324 | Interrupt_Handler aspects. See C.3.1(19).” | |
17325 | @end itemize | |
17326 | ||
17327 | There are no such forms. | |
17328 | ||
17329 | ||
17330 | @itemize * | |
17331 | ||
17332 | @item | |
17333 | “The semantics of some attributes and functions of an entity for which | |
17334 | aspect Discard_Names is True. See C.5(7).” | |
17335 | @end itemize | |
17336 | ||
17337 | If Discard_Names is True for an enumeration type, the Image attribute | |
17338 | provides the image of the Pos of the literal, and Value accepts | |
17339 | Pos values. | |
17340 | ||
17341 | If both of the aspects`@w{`}Discard_Names`@w{`} and @code{No_Tagged_Streams} are true | |
17342 | for a tagged type, its Expanded_Name and External_Tag values are | |
17343 | empty strings. This is useful to avoid exposing entity names at binary | |
17344 | level. | |
17345 | ||
17346 | ||
17347 | @itemize * | |
17348 | ||
17349 | @item | |
17350 | “The modulus and size of Test_and_Set_Flag. See C.6.3(8).” | |
17351 | @end itemize | |
17352 | ||
17353 | The modulus is 2**8. The size is 8. | |
17354 | ||
17355 | ||
17356 | @itemize * | |
17357 | ||
17358 | @item | |
17359 | “The value used to represent the set value for Atomic_Test_and_Set. | |
17360 | See C.6.3(10).” | |
17361 | @end itemize | |
17362 | ||
17363 | The value is 1. | |
17364 | ||
17365 | ||
17366 | @itemize * | |
17367 | ||
17368 | @item | |
17369 | “The result of the @code{Task_Identification.Image} | |
17370 | attribute. See C.7.1(7).” | |
17371 | @end itemize | |
17372 | ||
17373 | The result of this attribute is a string that identifies | |
17374 | the object or component that denotes a given task. If a variable @code{Var} | |
17375 | has a task type, the image for this task will have the form @code{Var_@var{XXXXXXXX}}, | |
17376 | where the suffix `XXXXXXXX' | |
17377 | is the hexadecimal representation of the virtual address of the corresponding | |
17378 | task control block. If the variable is an array of tasks, the image of each | |
17379 | task will have the form of an indexed component indicating the position of a | |
17380 | given task in the array, e.g., @code{Group(5)_@var{XXXXXXX}}. If the task is a | |
17381 | component of a record, the image of the task will have the form of a selected | |
17382 | component. These rules are fully recursive, so that the image of a task that | |
17383 | is a subcomponent of a composite object corresponds to the expression that | |
17384 | designates this task. | |
17385 | ||
17386 | If a task is created by an allocator, its image depends on the context. If the | |
17387 | allocator is part of an object declaration, the rules described above are used | |
17388 | to construct its image, and this image is not affected by subsequent | |
17389 | assignments. If the allocator appears within an expression, the image | |
17390 | includes only the name of the task type. | |
17391 | ||
17392 | If the configuration pragma Discard_Names is present, or if the restriction | |
17393 | No_Implicit_Heap_Allocation is in effect, the image reduces to | |
17394 | the numeric suffix, that is to say the hexadecimal representation of the | |
17395 | virtual address of the control block of the task. | |
17396 | ||
17397 | ||
17398 | @itemize * | |
17399 | ||
17400 | @item | |
17401 | “The value of @code{Current_Task} when in a protected entry | |
17402 | or interrupt handler. See C.7.1(17).” | |
17403 | @end itemize | |
17404 | ||
17405 | Protected entries or interrupt handlers can be executed by any | |
17406 | convenient thread, so the value of @code{Current_Task} is undefined. | |
17407 | ||
17408 | ||
17409 | @itemize * | |
17410 | ||
17411 | @item | |
17412 | “Granularity of locking for Task_Attributes. See C.7.2(16).” | |
17413 | @end itemize | |
17414 | ||
17415 | No locking is needed if the formal type Attribute has the size and | |
17416 | alignment of either Integer or System.Address and the bit representation | |
17417 | of Initial_Value is all zeroes. Otherwise, locking is performed. | |
17418 | ||
17419 | ||
17420 | @itemize * | |
17421 | ||
17422 | @item | |
17423 | “The declarations of @code{Any_Priority} and | |
17424 | @code{Priority}. See D.1(11).” | |
17425 | @end itemize | |
17426 | ||
17427 | See declarations in file @code{system.ads}. | |
17428 | ||
17429 | ||
17430 | @itemize * | |
17431 | ||
17432 | @item | |
17433 | “Implementation-defined execution resources. See D.1(15).” | |
17434 | @end itemize | |
17435 | ||
17436 | There are no implementation-defined execution resources. | |
17437 | ||
17438 | ||
17439 | @itemize * | |
17440 | ||
17441 | @item | |
17442 | “Whether, on a multiprocessor, a task that is waiting for | |
17443 | access to a protected object keeps its processor busy. See D.2.1(3).” | |
17444 | @end itemize | |
17445 | ||
17446 | On a multi-processor, a task that is waiting for access to a protected | |
17447 | object does not keep its processor busy. | |
17448 | ||
17449 | ||
17450 | @itemize * | |
17451 | ||
17452 | @item | |
17453 | “The affect of implementation defined execution resources | |
17454 | on task dispatching. See D.2.1(9).” | |
17455 | @end itemize | |
17456 | ||
17457 | Tasks map to threads in the threads package used by GNAT. Where possible | |
17458 | and appropriate, these threads correspond to native threads of the | |
17459 | underlying operating system. | |
17460 | ||
17461 | ||
17462 | @itemize * | |
17463 | ||
17464 | @item | |
17465 | “Implementation-defined task dispatching policies. See D.2.2(3).” | |
17466 | @end itemize | |
17467 | ||
17468 | There are no implementation-defined task dispatching policies. | |
17469 | ||
17470 | ||
17471 | @itemize * | |
17472 | ||
17473 | @item | |
17474 | “The value of Default_Quantum in Dispatching.Round_Robin. See D.2.5(4).” | |
17475 | @end itemize | |
17476 | ||
17477 | The value is 10 milliseconds. | |
17478 | ||
17479 | ||
17480 | @itemize * | |
17481 | ||
17482 | @item | |
17483 | “Implementation-defined `policy_identifiers' allowed | |
17484 | in a pragma @code{Locking_Policy}. See D.3(4).” | |
17485 | @end itemize | |
17486 | ||
17487 | The two implementation defined policies permitted in GNAT are | |
17488 | @code{Inheritance_Locking} and @code{Concurrent_Readers_Locking}. On | |
17489 | targets that support the @code{Inheritance_Locking} policy, locking is | |
17490 | implemented by inheritance, i.e., the task owning the lock operates | |
17491 | at a priority equal to the highest priority of any task currently | |
17492 | requesting the lock. On targets that support the | |
17493 | @code{Concurrent_Readers_Locking} policy, locking is implemented with a | |
17494 | read/write lock allowing multiple protected object functions to enter | |
17495 | concurrently. | |
17496 | ||
17497 | ||
17498 | @itemize * | |
17499 | ||
17500 | @item | |
17501 | “Default ceiling priorities. See D.3(10).” | |
17502 | @end itemize | |
17503 | ||
17504 | The ceiling priority of protected objects of the type | |
17505 | @code{System.Interrupt_Priority'Last} as described in the Ada | |
17506 | Reference Manual D.3(10), | |
17507 | ||
17508 | ||
17509 | @itemize * | |
17510 | ||
17511 | @item | |
17512 | “The ceiling of any protected object used internally by | |
17513 | the implementation. See D.3(16).” | |
17514 | @end itemize | |
17515 | ||
17516 | The ceiling priority of internal protected objects is | |
17517 | @code{System.Priority'Last}. | |
17518 | ||
17519 | ||
17520 | @itemize * | |
17521 | ||
17522 | @item | |
17523 | “Implementation-defined queuing policies. See D.4(1).” | |
17524 | @end itemize | |
17525 | ||
17526 | There are no implementation-defined queuing policies. | |
17527 | ||
17528 | ||
17529 | @itemize * | |
17530 | ||
17531 | @item | |
17532 | “Implementation-defined admission policies. See D.4.1(1).” | |
17533 | @end itemize | |
17534 | ||
17535 | There are no implementation-defined admission policies. | |
17536 | ||
17537 | ||
17538 | @itemize * | |
17539 | ||
17540 | @item | |
17541 | “Any operations that implicitly require heap storage | |
17542 | allocation. See D.7(8).” | |
17543 | @end itemize | |
17544 | ||
17545 | The only operation that implicitly requires heap storage allocation is | |
17546 | task creation. | |
17547 | ||
17548 | ||
17549 | @itemize * | |
17550 | ||
17551 | @item | |
17552 | “When restriction No_Dynamic_CPU_Assignment applies to a partition, the | |
17553 | processor on which a task with a CPU value of a Not_A_Specific_CPU will | |
17554 | execute. See D.7(10).” | |
17555 | @end itemize | |
17556 | ||
17557 | Unknown. | |
17558 | ||
17559 | ||
17560 | @itemize * | |
17561 | ||
17562 | @item | |
17563 | “When restriction No_Task_Termination applies to a partition, what happens | |
17564 | when a task terminates. See D.7(15.1).” | |
17565 | @end itemize | |
17566 | ||
17567 | Execution is erroneous in that case. | |
17568 | ||
17569 | ||
17570 | @itemize * | |
17571 | ||
17572 | @item | |
17573 | “The behavior when restriction Max_Storage_At_Blocking is violated. | |
17574 | See D.7(17).” | |
17575 | @end itemize | |
17576 | ||
17577 | Execution is erroneous in that case. | |
17578 | ||
17579 | ||
17580 | @itemize * | |
17581 | ||
17582 | @item | |
17583 | “The behavior when restriction Max_Asynchronous_Select_Nesting is violated. | |
17584 | See D.7(18).” | |
17585 | @end itemize | |
17586 | ||
17587 | Execution is erroneous in that case. | |
17588 | ||
17589 | ||
17590 | @itemize * | |
17591 | ||
17592 | @item | |
17593 | “The behavior when restriction Max_Tasks is violated. See D.7(19).” | |
17594 | @end itemize | |
17595 | ||
17596 | Execution is erroneous in that case. | |
17597 | ||
17598 | ||
17599 | @itemize * | |
17600 | ||
17601 | @item | |
17602 | “Whether the use of pragma Restrictions results in a reduction in program | |
17603 | code or data size or execution time. See D.7(20).” | |
f571a201 | 17604 | @end itemize |
64d5610f ML |
17605 | |
17606 | Yes it can, but the precise circumstances and properties of such reductions | |
17607 | are difficult to characterize. | |
17608 | ||
f571a201 RD |
17609 | |
17610 | @itemize * | |
17611 | ||
64d5610f ML |
17612 | @item |
17613 | “The value of Barrier_Limit’Last in Synchronous_Barriers. See D.10.1(4).” | |
17614 | @end itemize | |
17615 | ||
17616 | Synchronous_Barriers.Barrier_Limit’Last is Integer’Last . | |
17617 | ||
17618 | ||
17619 | @itemize * | |
17620 | ||
17621 | @item | |
17622 | “When an aborted task that is waiting on a Synchronous_Barrier is aborted. | |
17623 | See D.10.1(13).” | |
17624 | @end itemize | |
17625 | ||
17626 | Difficult to characterize. | |
17627 | ||
17628 | ||
17629 | @itemize * | |
17630 | ||
17631 | @item | |
17632 | “The value of Min_Handler_Ceiling in Execution_Time.Group_Budgets. | |
17633 | See D.14.2(7).” | |
17634 | @end itemize | |
17635 | ||
17636 | See source file @code{a-etgrbu.ads}. | |
17637 | ||
17638 | ||
17639 | @itemize * | |
17640 | ||
17641 | @item | |
17642 | “The value of CPU_Range’Last in System.Multiprocessors. See D.16(4).” | |
17643 | @end itemize | |
17644 | ||
17645 | See source file @code{s-multip.ads}. | |
17646 | ||
17647 | ||
17648 | @itemize * | |
17649 | ||
17650 | @item | |
17651 | “The processor on which the environment task executes in the absence | |
17652 | of a value for the aspect CPU. See D.16(13).” | |
17653 | @end itemize | |
17654 | ||
17655 | Unknown. | |
17656 | ||
17657 | ||
17658 | @itemize * | |
17659 | ||
17660 | @item | |
17661 | “The means for creating and executing distributed | |
17662 | programs. See E(5).” | |
17663 | @end itemize | |
17664 | ||
17665 | The GLADE package provides a utility GNATDIST for creating and executing | |
17666 | distributed programs. See the GLADE reference manual for further details. | |
17667 | ||
17668 | ||
17669 | @itemize * | |
17670 | ||
17671 | @item | |
17672 | “Any events that can result in a partition becoming | |
17673 | inaccessible. See E.1(7).” | |
17674 | @end itemize | |
17675 | ||
17676 | See the GLADE reference manual for full details on such events. | |
17677 | ||
17678 | ||
17679 | @itemize * | |
17680 | ||
17681 | @item | |
17682 | “The scheduling policies, treatment of priorities, and management of | |
17683 | shared resources between partitions in certain cases. See E.1(11).” | |
17684 | @end itemize | |
17685 | ||
17686 | See the GLADE reference manual for full details on these aspects of | |
17687 | multi-partition execution. | |
17688 | ||
17689 | ||
17690 | @itemize * | |
17691 | ||
17692 | @item | |
17693 | “Whether the execution of the remote subprogram is | |
17694 | immediately aborted as a result of cancellation. See E.4(13).” | |
17695 | @end itemize | |
17696 | ||
17697 | See the GLADE reference manual for details on the effect of abort in | |
17698 | a distributed application. | |
17699 | ||
17700 | ||
17701 | @itemize * | |
17702 | ||
17703 | @item | |
17704 | “The range of type System.RPC.Partition_Id. See E.5(14).” | |
17705 | @end itemize | |
17706 | ||
17707 | System.RPC.Partition_ID’Last is Integer’Last. See source file @code{s-rpc.ads}. | |
17708 | ||
17709 | ||
17710 | @itemize * | |
17711 | ||
17712 | @item | |
17713 | “Implementation-defined interfaces in the PCS. See E.5(26).” | |
17714 | @end itemize | |
17715 | ||
17716 | See the GLADE reference manual for a full description of all | |
17717 | implementation defined interfaces. | |
17718 | ||
17719 | ||
17720 | @itemize * | |
17721 | ||
17722 | @item | |
17723 | “The values of named numbers in the package | |
17724 | @code{Decimal}. See F.2(7).” | |
17725 | @end itemize | |
17726 | ||
17727 | ||
17728 | @multitable {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxx} | |
17729 | @headitem | |
17730 | ||
17731 | Named Number | |
17732 | ||
17733 | @tab | |
17734 | ||
17735 | Value | |
17736 | ||
17737 | @item | |
17738 | ||
17739 | `Max_Scale' | |
17740 | ||
17741 | @tab | |
17742 | ||
17743 | +18 | |
17744 | ||
17745 | @item | |
17746 | ||
17747 | `Min_Scale' | |
17748 | ||
17749 | @tab | |
17750 | ||
17751 | -18 | |
17752 | ||
17753 | @item | |
17754 | ||
17755 | `Min_Delta' | |
17756 | ||
17757 | @tab | |
17758 | ||
17759 | 1.0E-18 | |
17760 | ||
17761 | @item | |
17762 | ||
17763 | `Max_Delta' | |
17764 | ||
17765 | @tab | |
17766 | ||
17767 | 1.0E+18 | |
17768 | ||
17769 | @item | |
17770 | ||
17771 | `Max_Decimal_Digits' | |
17772 | ||
17773 | @tab | |
17774 | ||
17775 | 18 | |
17776 | ||
17777 | @end multitable | |
17778 | ||
17779 | ||
17780 | ||
17781 | @itemize * | |
17782 | ||
17783 | @item | |
17784 | “The value of @code{Max_Picture_Length} in the package | |
17785 | @code{Text_IO.Editing}. See F.3.3(16).” | |
17786 | ||
17787 | 64 | |
17788 | ||
17789 | @item | |
17790 | “The value of @code{Max_Picture_Length} in the package | |
17791 | @code{Wide_Text_IO.Editing}. See F.3.4(5).” | |
17792 | ||
17793 | 64 | |
17794 | ||
17795 | @item | |
17796 | “The accuracy actually achieved by the complex elementary | |
17797 | functions and by other complex arithmetic operations. See G.1(1).” | |
17798 | @end itemize | |
17799 | ||
17800 | Standard library functions are used for the complex arithmetic | |
17801 | operations. Only fast math mode is currently supported. | |
17802 | ||
17803 | ||
17804 | @itemize * | |
17805 | ||
17806 | @item | |
17807 | “The sign of a zero result (or a component thereof) from | |
17808 | any operator or function in @code{Numerics.Generic_Complex_Types}, when | |
17809 | @code{Real'Signed_Zeros} is True. See G.1.1(53).” | |
17810 | @end itemize | |
17811 | ||
17812 | The signs of zero values are as recommended by the relevant | |
17813 | implementation advice. | |
17814 | ||
17815 | ||
17816 | @itemize * | |
17817 | ||
17818 | @item | |
17819 | “The sign of a zero result (or a component thereof) from | |
17820 | any operator or function in | |
17821 | @code{Numerics.Generic_Complex_Elementary_Functions}, when | |
17822 | @code{Real'Signed_Zeros} is @code{True}. See G.1.2(45).” | |
17823 | @end itemize | |
17824 | ||
17825 | The signs of zero values are as recommended by the relevant | |
17826 | implementation advice. | |
17827 | ||
17828 | ||
17829 | @itemize * | |
17830 | ||
17831 | @item | |
17832 | “Whether the strict mode or the relaxed mode is the | |
17833 | default. See G.2(2).” | |
17834 | @end itemize | |
17835 | ||
17836 | The strict mode is the default. There is no separate relaxed mode. GNAT | |
17837 | provides a highly efficient implementation of strict mode. | |
17838 | ||
17839 | ||
17840 | @itemize * | |
17841 | ||
17842 | @item | |
17843 | “The result interval in certain cases of fixed-to-float | |
17844 | conversion. See G.2.1(10).” | |
17845 | @end itemize | |
17846 | ||
17847 | For cases where the result interval is implementation dependent, the | |
17848 | accuracy is that provided by performing all operations in 64-bit IEEE | |
17849 | floating-point format. | |
17850 | ||
17851 | ||
17852 | @itemize * | |
17853 | ||
17854 | @item | |
17855 | “The result of a floating point arithmetic operation in | |
17856 | overflow situations, when the @code{Machine_Overflows} attribute of the | |
17857 | result type is @code{False}. See G.2.1(13).” | |
17858 | @end itemize | |
17859 | ||
17860 | Infinite and NaN values are produced as dictated by the IEEE | |
17861 | floating-point standard. | |
17862 | Note that on machines that are not fully compliant with the IEEE | |
17863 | floating-point standard, such as Alpha, the `-mieee' compiler flag | |
17864 | must be used for achieving IEEE conforming behavior (although at the cost | |
17865 | of a significant performance penalty), so infinite and NaN values are | |
17866 | properly generated. | |
17867 | ||
17868 | ||
17869 | @itemize * | |
17870 | ||
17871 | @item | |
17872 | “The result interval for division (or exponentiation by a | |
17873 | negative exponent), when the floating point hardware implements division | |
17874 | as multiplication by a reciprocal. See G.2.1(16).” | |
17875 | @end itemize | |
17876 | ||
17877 | Not relevant, division is IEEE exact. | |
17878 | ||
17879 | ||
17880 | @itemize * | |
17881 | ||
17882 | @item | |
17883 | “The definition of close result set, which determines the accuracy of | |
17884 | certain fixed point multiplications and divisions. See G.2.3(5).” | |
17885 | @end itemize | |
17886 | ||
17887 | Operations in the close result set are performed using IEEE long format | |
17888 | floating-point arithmetic. The input operands are converted to | |
17889 | floating-point, the operation is done in floating-point, and the result | |
17890 | is converted to the target type. | |
17891 | ||
17892 | ||
17893 | @itemize * | |
17894 | ||
17895 | @item | |
17896 | “Conditions on a `universal_real' operand of a fixed | |
17897 | point multiplication or division for which the result shall be in the | |
17898 | perfect result set. See G.2.3(22).” | |
17899 | @end itemize | |
17900 | ||
17901 | The result is only defined to be in the perfect result set if the result | |
17902 | can be computed by a single scaling operation involving a scale factor | |
17903 | representable in 64 bits. | |
17904 | ||
17905 | ||
17906 | @itemize * | |
17907 | ||
17908 | @item | |
17909 | “The result of a fixed point arithmetic operation in | |
17910 | overflow situations, when the @code{Machine_Overflows} attribute of the | |
17911 | result type is @code{False}. See G.2.3(27).” | |
17912 | @end itemize | |
17913 | ||
17914 | Not relevant, @code{Machine_Overflows} is @code{True} for fixed-point | |
17915 | types. | |
17916 | ||
17917 | ||
17918 | @itemize * | |
17919 | ||
17920 | @item | |
17921 | “The result of an elementary function reference in | |
17922 | overflow situations, when the @code{Machine_Overflows} attribute of the | |
17923 | result type is @code{False}. See G.2.4(4).” | |
17924 | @end itemize | |
17925 | ||
17926 | IEEE infinite and Nan values are produced as appropriate. | |
17927 | ||
17928 | ||
17929 | @itemize * | |
17930 | ||
17931 | @item | |
17932 | “The value of the angle threshold, within which certain | |
17933 | elementary functions, complex arithmetic operations, and complex | |
17934 | elementary functions yield results conforming to a maximum relative | |
17935 | error bound. See G.2.4(10).” | |
17936 | @end itemize | |
17937 | ||
17938 | Information on this subject is not yet available. | |
17939 | ||
17940 | ||
17941 | @itemize * | |
17942 | ||
17943 | @item | |
17944 | “The accuracy of certain elementary functions for | |
17945 | parameters beyond the angle threshold. See G.2.4(10).” | |
17946 | @end itemize | |
17947 | ||
17948 | Information on this subject is not yet available. | |
17949 | ||
17950 | ||
17951 | @itemize * | |
17952 | ||
17953 | @item | |
17954 | “The result of a complex arithmetic operation or complex | |
17955 | elementary function reference in overflow situations, when the | |
17956 | @code{Machine_Overflows} attribute of the corresponding real type is | |
17957 | @code{False}. See G.2.6(5).” | |
17958 | @end itemize | |
17959 | ||
17960 | IEEE infinite and Nan values are produced as appropriate. | |
17961 | ||
17962 | ||
17963 | @itemize * | |
17964 | ||
17965 | @item | |
17966 | “The accuracy of certain complex arithmetic operations and | |
17967 | certain complex elementary functions for parameters (or components | |
17968 | thereof) beyond the angle threshold. See G.2.6(8).” | |
17969 | @end itemize | |
17970 | ||
17971 | Information on those subjects is not yet available. | |
17972 | ||
17973 | ||
17974 | @itemize * | |
17975 | ||
17976 | @item | |
17977 | “The accuracy requirements for the subprograms Solve, Inverse, | |
17978 | Determinant, Eigenvalues and Eigensystem for type Real_Matrix. | |
17979 | See G.3.1(81).” | |
17980 | @end itemize | |
17981 | ||
17982 | Information on those subjects is not yet available. | |
17983 | ||
17984 | ||
17985 | @itemize * | |
17986 | ||
17987 | @item | |
17988 | “The accuracy requirements for the subprograms Solve, Inverse, | |
17989 | Determinant, Eigenvalues and Eigensystem for type Complex_Matrix. | |
17990 | See G.3.2(149).” | |
17991 | @end itemize | |
17992 | ||
17993 | Information on those subjects is not yet available. | |
17994 | ||
17995 | ||
17996 | @itemize * | |
17997 | ||
17998 | @item | |
17999 | “The consequences of violating No_Hidden_Indirect_Globals. See H.4(23.9).” | |
18000 | @end itemize | |
18001 | ||
18002 | Execution is erroneous in that case. | |
18003 | ||
18004 | @node Intrinsic Subprograms,Representation Clauses and Pragmas,Implementation Defined Characteristics,Top | |
73918baf | 18005 | @anchor{gnat_rm/intrinsic_subprograms doc}@anchor{263}@anchor{gnat_rm/intrinsic_subprograms id1}@anchor{264}@anchor{gnat_rm/intrinsic_subprograms intrinsic-subprograms}@anchor{c} |
64d5610f ML |
18006 | @chapter Intrinsic Subprograms |
18007 | ||
18008 | ||
18009 | @geindex Intrinsic Subprograms | |
18010 | ||
18011 | GNAT allows a user application program to write the declaration: | |
18012 | ||
18013 | @example | |
18014 | pragma Import (Intrinsic, name); | |
18015 | @end example | |
18016 | ||
18017 | providing that the name corresponds to one of the implemented intrinsic | |
18018 | subprograms in GNAT, and that the parameter profile of the referenced | |
18019 | subprogram meets the requirements. This chapter describes the set of | |
18020 | implemented intrinsic subprograms, and the requirements on parameter profiles. | |
18021 | Note that no body is supplied; as with other uses of pragma Import, the | |
18022 | body is supplied elsewhere (in this case by the compiler itself). Note | |
18023 | that any use of this feature is potentially non-portable, since the | |
18024 | Ada standard does not require Ada compilers to implement this feature. | |
18025 | ||
18026 | @menu | |
18027 | * Intrinsic Operators:: | |
18028 | * Compilation_ISO_Date:: | |
18029 | * Compilation_Date:: | |
18030 | * Compilation_Time:: | |
18031 | * Enclosing_Entity:: | |
18032 | * Exception_Information:: | |
18033 | * Exception_Message:: | |
18034 | * Exception_Name:: | |
18035 | * File:: | |
18036 | * Line:: | |
18037 | * Shifts and Rotates:: | |
18038 | * Source_Location:: | |
18039 | ||
18040 | @end menu | |
18041 | ||
18042 | @node Intrinsic Operators,Compilation_ISO_Date,,Intrinsic Subprograms | |
73918baf | 18043 | @anchor{gnat_rm/intrinsic_subprograms id2}@anchor{265}@anchor{gnat_rm/intrinsic_subprograms intrinsic-operators}@anchor{266} |
64d5610f ML |
18044 | @section Intrinsic Operators |
18045 | ||
18046 | ||
18047 | @geindex Intrinsic operator | |
18048 | ||
18049 | All the predefined numeric operators in package Standard | |
18050 | in @code{pragma Import (Intrinsic,..)} | |
18051 | declarations. In the binary operator case, the operands must have the same | |
18052 | size. The operand or operands must also be appropriate for | |
18053 | the operator. For example, for addition, the operands must | |
18054 | both be floating-point or both be fixed-point, and the | |
18055 | right operand for @code{"**"} must have a root type of | |
18056 | @code{Standard.Integer'Base}. | |
18057 | You can use an intrinsic operator declaration as in the following example: | |
18058 | ||
18059 | @example | |
18060 | type Int1 is new Integer; | |
18061 | type Int2 is new Integer; | |
18062 | ||
18063 | function "+" (X1 : Int1; X2 : Int2) return Int1; | |
18064 | function "+" (X1 : Int1; X2 : Int2) return Int2; | |
18065 | pragma Import (Intrinsic, "+"); | |
18066 | @end example | |
18067 | ||
18068 | This declaration would permit ‘mixed mode’ arithmetic on items | |
18069 | of the differing types @code{Int1} and @code{Int2}. | |
18070 | It is also possible to specify such operators for private types, if the | |
18071 | full views are appropriate arithmetic types. | |
18072 | ||
18073 | @node Compilation_ISO_Date,Compilation_Date,Intrinsic Operators,Intrinsic Subprograms | |
73918baf | 18074 | @anchor{gnat_rm/intrinsic_subprograms compilation-iso-date}@anchor{267}@anchor{gnat_rm/intrinsic_subprograms id3}@anchor{268} |
64d5610f ML |
18075 | @section Compilation_ISO_Date |
18076 | ||
18077 | ||
18078 | @geindex Compilation_ISO_Date | |
18079 | ||
18080 | This intrinsic subprogram is used in the implementation of the | |
18081 | library package @code{GNAT.Source_Info}. The only useful use of the | |
18082 | intrinsic import in this case is the one in this unit, so an | |
18083 | application program should simply call the function | |
18084 | @code{GNAT.Source_Info.Compilation_ISO_Date} to obtain the date of | |
18085 | the current compilation (in local time format YYYY-MM-DD). | |
18086 | ||
18087 | @node Compilation_Date,Compilation_Time,Compilation_ISO_Date,Intrinsic Subprograms | |
73918baf | 18088 | @anchor{gnat_rm/intrinsic_subprograms compilation-date}@anchor{269}@anchor{gnat_rm/intrinsic_subprograms id4}@anchor{26a} |
64d5610f ML |
18089 | @section Compilation_Date |
18090 | ||
18091 | ||
18092 | @geindex Compilation_Date | |
18093 | ||
18094 | Same as Compilation_ISO_Date, except the string is in the form | |
18095 | MMM DD YYYY. | |
18096 | ||
18097 | @node Compilation_Time,Enclosing_Entity,Compilation_Date,Intrinsic Subprograms | |
73918baf | 18098 | @anchor{gnat_rm/intrinsic_subprograms compilation-time}@anchor{26b}@anchor{gnat_rm/intrinsic_subprograms id5}@anchor{26c} |
64d5610f ML |
18099 | @section Compilation_Time |
18100 | ||
18101 | ||
18102 | @geindex Compilation_Time | |
18103 | ||
18104 | This intrinsic subprogram is used in the implementation of the | |
18105 | library package @code{GNAT.Source_Info}. The only useful use of the | |
18106 | intrinsic import in this case is the one in this unit, so an | |
18107 | application program should simply call the function | |
18108 | @code{GNAT.Source_Info.Compilation_Time} to obtain the time of | |
18109 | the current compilation (in local time format HH:MM:SS). | |
18110 | ||
18111 | @node Enclosing_Entity,Exception_Information,Compilation_Time,Intrinsic Subprograms | |
73918baf | 18112 | @anchor{gnat_rm/intrinsic_subprograms enclosing-entity}@anchor{26d}@anchor{gnat_rm/intrinsic_subprograms id6}@anchor{26e} |
64d5610f ML |
18113 | @section Enclosing_Entity |
18114 | ||
18115 | ||
18116 | @geindex Enclosing_Entity | |
18117 | ||
18118 | This intrinsic subprogram is used in the implementation of the | |
18119 | library package @code{GNAT.Source_Info}. The only useful use of the | |
18120 | intrinsic import in this case is the one in this unit, so an | |
18121 | application program should simply call the function | |
18122 | @code{GNAT.Source_Info.Enclosing_Entity} to obtain the name of | |
18123 | the current subprogram, package, task, entry, or protected subprogram. | |
18124 | ||
18125 | @node Exception_Information,Exception_Message,Enclosing_Entity,Intrinsic Subprograms | |
73918baf | 18126 | @anchor{gnat_rm/intrinsic_subprograms exception-information}@anchor{26f}@anchor{gnat_rm/intrinsic_subprograms id7}@anchor{270} |
64d5610f ML |
18127 | @section Exception_Information |
18128 | ||
18129 | ||
18130 | @geindex Exception_Information' | |
18131 | ||
18132 | This intrinsic subprogram is used in the implementation of the | |
18133 | library package @code{GNAT.Current_Exception}. The only useful | |
18134 | use of the intrinsic import in this case is the one in this unit, | |
18135 | so an application program should simply call the function | |
18136 | @code{GNAT.Current_Exception.Exception_Information} to obtain | |
18137 | the exception information associated with the current exception. | |
18138 | ||
18139 | @node Exception_Message,Exception_Name,Exception_Information,Intrinsic Subprograms | |
73918baf | 18140 | @anchor{gnat_rm/intrinsic_subprograms exception-message}@anchor{271}@anchor{gnat_rm/intrinsic_subprograms id8}@anchor{272} |
64d5610f ML |
18141 | @section Exception_Message |
18142 | ||
18143 | ||
18144 | @geindex Exception_Message | |
18145 | ||
18146 | This intrinsic subprogram is used in the implementation of the | |
18147 | library package @code{GNAT.Current_Exception}. The only useful | |
18148 | use of the intrinsic import in this case is the one in this unit, | |
18149 | so an application program should simply call the function | |
18150 | @code{GNAT.Current_Exception.Exception_Message} to obtain | |
18151 | the message associated with the current exception. | |
18152 | ||
18153 | @node Exception_Name,File,Exception_Message,Intrinsic Subprograms | |
73918baf | 18154 | @anchor{gnat_rm/intrinsic_subprograms exception-name}@anchor{273}@anchor{gnat_rm/intrinsic_subprograms id9}@anchor{274} |
64d5610f ML |
18155 | @section Exception_Name |
18156 | ||
18157 | ||
18158 | @geindex Exception_Name | |
18159 | ||
18160 | This intrinsic subprogram is used in the implementation of the | |
18161 | library package @code{GNAT.Current_Exception}. The only useful | |
18162 | use of the intrinsic import in this case is the one in this unit, | |
18163 | so an application program should simply call the function | |
18164 | @code{GNAT.Current_Exception.Exception_Name} to obtain | |
18165 | the name of the current exception. | |
18166 | ||
18167 | @node File,Line,Exception_Name,Intrinsic Subprograms | |
73918baf | 18168 | @anchor{gnat_rm/intrinsic_subprograms file}@anchor{275}@anchor{gnat_rm/intrinsic_subprograms id10}@anchor{276} |
64d5610f ML |
18169 | @section File |
18170 | ||
18171 | ||
18172 | @geindex File | |
18173 | ||
18174 | This intrinsic subprogram is used in the implementation of the | |
18175 | library package @code{GNAT.Source_Info}. The only useful use of the | |
18176 | intrinsic import in this case is the one in this unit, so an | |
18177 | application program should simply call the function | |
18178 | @code{GNAT.Source_Info.File} to obtain the name of the current | |
18179 | file. | |
18180 | ||
18181 | @node Line,Shifts and Rotates,File,Intrinsic Subprograms | |
73918baf | 18182 | @anchor{gnat_rm/intrinsic_subprograms id11}@anchor{277}@anchor{gnat_rm/intrinsic_subprograms line}@anchor{278} |
64d5610f ML |
18183 | @section Line |
18184 | ||
18185 | ||
18186 | @geindex Line | |
18187 | ||
18188 | This intrinsic subprogram is used in the implementation of the | |
18189 | library package @code{GNAT.Source_Info}. The only useful use of the | |
18190 | intrinsic import in this case is the one in this unit, so an | |
18191 | application program should simply call the function | |
18192 | @code{GNAT.Source_Info.Line} to obtain the number of the current | |
18193 | source line. | |
18194 | ||
18195 | @node Shifts and Rotates,Source_Location,Line,Intrinsic Subprograms | |
73918baf | 18196 | @anchor{gnat_rm/intrinsic_subprograms id12}@anchor{279}@anchor{gnat_rm/intrinsic_subprograms shifts-and-rotates}@anchor{27a} |
64d5610f ML |
18197 | @section Shifts and Rotates |
18198 | ||
18199 | ||
18200 | @geindex Shift_Left | |
18201 | ||
18202 | @geindex Shift_Right | |
18203 | ||
18204 | @geindex Shift_Right_Arithmetic | |
18205 | ||
18206 | @geindex Rotate_Left | |
18207 | ||
18208 | @geindex Rotate_Right | |
18209 | ||
18210 | In standard Ada, the shift and rotate functions are available only | |
18211 | for the predefined modular types in package @code{Interfaces}. However, in | |
18212 | GNAT it is possible to define these functions for any integer | |
18213 | type (signed or modular), as in this example: | |
18214 | ||
18215 | @example | |
18216 | function Shift_Left | |
18217 | (Value : T; | |
18218 | Amount : Natural) return T | |
18219 | with Import, Convention => Intrinsic; | |
18220 | @end example | |
18221 | ||
18222 | The function name must be one of | |
18223 | Shift_Left, Shift_Right, Shift_Right_Arithmetic, Rotate_Left, or | |
18224 | Rotate_Right. T must be an integer type. T’Size must be | |
18225 | 8, 16, 32 or 64 bits; if T is modular, the modulus | |
18226 | must be 2**8, 2**16, 2**32 or 2**64. | |
18227 | The result type must be the same as the type of @code{Value}. | |
18228 | The shift amount must be Natural. | |
18229 | The formal parameter names can be anything. | |
18230 | ||
18231 | A more convenient way of providing these shift operators is to use the | |
18232 | Provide_Shift_Operators pragma, which provides the function declarations and | |
18233 | corresponding pragma Import’s for all five shift functions. For signed types | |
18234 | the semantics of these operators is to interpret the bitwise result of the | |
18235 | corresponding operator for modular type. In particular, shifting a negative | |
18236 | number may change its sign bit to positive. | |
18237 | ||
18238 | @node Source_Location,,Shifts and Rotates,Intrinsic Subprograms | |
73918baf | 18239 | @anchor{gnat_rm/intrinsic_subprograms id13}@anchor{27b}@anchor{gnat_rm/intrinsic_subprograms source-location}@anchor{27c} |
64d5610f ML |
18240 | @section Source_Location |
18241 | ||
18242 | ||
18243 | @geindex Source_Location | |
18244 | ||
18245 | This intrinsic subprogram is used in the implementation of the | |
18246 | library routine @code{GNAT.Source_Info}. The only useful use of the | |
18247 | intrinsic import in this case is the one in this unit, so an | |
18248 | application program should simply call the function | |
18249 | @code{GNAT.Source_Info.Source_Location} to obtain the current | |
18250 | source file location. | |
18251 | ||
18252 | @node Representation Clauses and Pragmas,Standard Library Routines,Intrinsic Subprograms,Top | |
73918baf | 18253 | @anchor{gnat_rm/representation_clauses_and_pragmas doc}@anchor{27d}@anchor{gnat_rm/representation_clauses_and_pragmas id1}@anchor{27e}@anchor{gnat_rm/representation_clauses_and_pragmas representation-clauses-and-pragmas}@anchor{d} |
64d5610f ML |
18254 | @chapter Representation Clauses and Pragmas |
18255 | ||
18256 | ||
18257 | @geindex Representation Clauses | |
18258 | ||
18259 | @geindex Representation Clause | |
18260 | ||
18261 | @geindex Representation Pragma | |
18262 | ||
18263 | @geindex Pragma | |
18264 | @geindex representation | |
18265 | ||
18266 | This section describes the representation clauses accepted by GNAT, and | |
18267 | their effect on the representation of corresponding data objects. | |
18268 | ||
18269 | GNAT fully implements Annex C (Systems Programming). This means that all | |
18270 | the implementation advice sections in chapter 13 are fully implemented. | |
18271 | However, these sections only require a minimal level of support for | |
18272 | representation clauses. GNAT provides much more extensive capabilities, | |
18273 | and this section describes the additional capabilities provided. | |
18274 | ||
18275 | @menu | |
18276 | * Alignment Clauses:: | |
18277 | * Size Clauses:: | |
18278 | * Storage_Size Clauses:: | |
18279 | * Size of Variant Record Objects:: | |
18280 | * Biased Representation:: | |
18281 | * Value_Size and Object_Size Clauses:: | |
18282 | * Component_Size Clauses:: | |
18283 | * Bit_Order Clauses:: | |
18284 | * Effect of Bit_Order on Byte Ordering:: | |
18285 | * Pragma Pack for Arrays:: | |
18286 | * Pragma Pack for Records:: | |
18287 | * Record Representation Clauses:: | |
18288 | * Handling of Records with Holes:: | |
18289 | * Enumeration Clauses:: | |
18290 | * Address Clauses:: | |
18291 | * Use of Address Clauses for Memory-Mapped I/O:: | |
18292 | * Effect of Convention on Representation:: | |
18293 | * Conventions and Anonymous Access Types:: | |
18294 | * Determining the Representations chosen by GNAT:: | |
18295 | ||
18296 | @end menu | |
18297 | ||
18298 | @node Alignment Clauses,Size Clauses,,Representation Clauses and Pragmas | |
73918baf | 18299 | @anchor{gnat_rm/representation_clauses_and_pragmas alignment-clauses}@anchor{27f}@anchor{gnat_rm/representation_clauses_and_pragmas id2}@anchor{280} |
64d5610f ML |
18300 | @section Alignment Clauses |
18301 | ||
18302 | ||
18303 | @geindex Alignment Clause | |
18304 | ||
18305 | GNAT requires that all alignment clauses specify 0 or a power of 2, and | |
18306 | all default alignments are always a power of 2. Specifying 0 is the | |
18307 | same as specifying 1. | |
18308 | ||
18309 | The default alignment values are as follows: | |
18310 | ||
18311 | ||
18312 | @itemize * | |
18313 | ||
18314 | @item | |
18315 | `Elementary Types'. | |
18316 | ||
18317 | For elementary types, the alignment is the minimum of the actual size of | |
18318 | objects of the type divided by @code{Storage_Unit}, | |
18319 | and the maximum alignment supported by the target. | |
18320 | (This maximum alignment is given by the GNAT-specific attribute | |
067d80d8 | 18321 | @code{Standard'Maximum_Alignment}; see @ref{190,,Attribute Maximum_Alignment}.) |
64d5610f ML |
18322 | |
18323 | @geindex Maximum_Alignment attribute | |
18324 | ||
18325 | For example, for type @code{Long_Float}, the object size is 8 bytes, and the | |
18326 | default alignment will be 8 on any target that supports alignments | |
18327 | this large, but on some targets, the maximum alignment may be smaller | |
18328 | than 8, in which case objects of type @code{Long_Float} will be maximally | |
18329 | aligned. | |
18330 | ||
18331 | @item | |
18332 | `Arrays'. | |
18333 | ||
18334 | For arrays, the alignment is equal to the alignment of the component type | |
18335 | for the normal case where no packing or component size is given. If the | |
18336 | array is packed, and the packing is effective (see separate section on | |
18337 | packed arrays), then the alignment will be either 4, 2, or 1 for long packed | |
18338 | arrays or arrays whose length is not known at compile time, depending on | |
18339 | whether the component size is divisible by 4, 2, or is odd. For short packed | |
18340 | arrays, which are handled internally as modular types, the alignment | |
18341 | will be as described for elementary types, e.g. a packed array of length | |
18342 | 31 bits will have an object size of four bytes, and an alignment of 4. | |
18343 | ||
18344 | @item | |
18345 | `Records'. | |
18346 | ||
18347 | For the normal unpacked case, the alignment of a record is equal to | |
18348 | the maximum alignment of any of its components. For tagged records, this | |
18349 | includes the implicit access type used for the tag. If a pragma @code{Pack} | |
18350 | is used and all components are packable (see separate section on pragma | |
18351 | @code{Pack}), then the resulting alignment is 1, unless the layout of the | |
18352 | record makes it profitable to increase it. | |
18353 | ||
18354 | A special case is when: | |
18355 | ||
18356 | ||
18357 | @itemize * | |
18358 | ||
18359 | @item | |
18360 | the size of the record is given explicitly, or a | |
18361 | full record representation clause is given, and | |
18362 | ||
18363 | @item | |
18364 | the size of the record is 2, 4, or 8 bytes. | |
18365 | @end itemize | |
18366 | ||
18367 | In this case, an alignment is chosen to match the | |
18368 | size of the record. For example, if we have: | |
18369 | ||
18370 | @example | |
18371 | type Small is record | |
18372 | A, B : Character; | |
18373 | end record; | |
18374 | for Small'Size use 16; | |
18375 | @end example | |
18376 | ||
18377 | then the default alignment of the record type @code{Small} is 2, not 1. This | |
18378 | leads to more efficient code when the record is treated as a unit, and also | |
18379 | allows the type to specified as @code{Atomic} on architectures requiring | |
18380 | strict alignment. | |
18381 | @end itemize | |
18382 | ||
18383 | An alignment clause may specify a larger alignment than the default value | |
18384 | up to some maximum value dependent on the target (obtainable by using the | |
18385 | attribute reference @code{Standard'Maximum_Alignment}). It may also specify | |
18386 | a smaller alignment than the default value for enumeration, integer and | |
18387 | fixed point types, as well as for record types, for example | |
18388 | ||
18389 | @example | |
18390 | type V is record | |
18391 | A : Integer; | |
18392 | end record; | |
18393 | ||
18394 | for V'alignment use 1; | |
18395 | @end example | |
18396 | ||
18397 | @geindex Alignment | |
18398 | @geindex default | |
18399 | ||
18400 | The default alignment for the type @code{V} is 4, as a result of the | |
18401 | Integer field in the record, but it is permissible, as shown, to | |
18402 | override the default alignment of the record with a smaller value. | |
18403 | ||
18404 | @geindex Alignment | |
18405 | @geindex subtypes | |
18406 | ||
18407 | Note that according to the Ada standard, an alignment clause applies only | |
18408 | to the first named subtype. If additional subtypes are declared, then the | |
18409 | compiler is allowed to choose any alignment it likes, and there is no way | |
18410 | to control this choice. Consider: | |
18411 | ||
18412 | @example | |
18413 | type R is range 1 .. 10_000; | |
18414 | for R'Alignment use 1; | |
18415 | subtype RS is R range 1 .. 1000; | |
18416 | @end example | |
18417 | ||
18418 | The alignment clause specifies an alignment of 1 for the first named subtype | |
18419 | @code{R} but this does not necessarily apply to @code{RS}. When writing | |
18420 | portable Ada code, you should avoid writing code that explicitly or | |
18421 | implicitly relies on the alignment of such subtypes. | |
18422 | ||
18423 | For the GNAT compiler, if an explicit alignment clause is given, this | |
18424 | value is also used for any subsequent subtypes. So for GNAT, in the | |
18425 | above example, you can count on the alignment of @code{RS} being 1. But this | |
18426 | assumption is non-portable, and other compilers may choose different | |
18427 | alignments for the subtype @code{RS}. | |
18428 | ||
18429 | @node Size Clauses,Storage_Size Clauses,Alignment Clauses,Representation Clauses and Pragmas | |
73918baf | 18430 | @anchor{gnat_rm/representation_clauses_and_pragmas id3}@anchor{281}@anchor{gnat_rm/representation_clauses_and_pragmas size-clauses}@anchor{282} |
64d5610f ML |
18431 | @section Size Clauses |
18432 | ||
18433 | ||
18434 | @geindex Size Clause | |
18435 | ||
18436 | The default size for a type @code{T} is obtainable through the | |
18437 | language-defined attribute @code{T'Size} and also through the | |
18438 | equivalent GNAT-defined attribute @code{T'Value_Size}. | |
18439 | For objects of type @code{T}, GNAT will generally increase the type size | |
18440 | so that the object size (obtainable through the GNAT-defined attribute | |
18441 | @code{T'Object_Size}) | |
18442 | is a multiple of @code{T'Alignment * Storage_Unit}. | |
18443 | ||
18444 | For example: | |
18445 | ||
18446 | @example | |
18447 | type Smallint is range 1 .. 6; | |
18448 | ||
18449 | type Rec is record | |
18450 | Y1 : integer; | |
18451 | Y2 : boolean; | |
18452 | end record; | |
18453 | @end example | |
18454 | ||
18455 | In this example, @code{Smallint'Size} = @code{Smallint'Value_Size} = 3, | |
18456 | as specified by the RM rules, | |
18457 | but objects of this type will have a size of 8 | |
18458 | (@code{Smallint'Object_Size} = 8), | |
18459 | since objects by default occupy an integral number | |
18460 | of storage units. On some targets, notably older | |
18461 | versions of the Digital Alpha, the size of stand | |
18462 | alone objects of this type may be 32, reflecting | |
18463 | the inability of the hardware to do byte load/stores. | |
18464 | ||
18465 | Similarly, the size of type @code{Rec} is 40 bits | |
18466 | (@code{Rec'Size} = @code{Rec'Value_Size} = 40), but | |
18467 | the alignment is 4, so objects of this type will have | |
18468 | their size increased to 64 bits so that it is a multiple | |
18469 | of the alignment (in bits). This decision is | |
18470 | in accordance with the specific Implementation Advice in RM 13.3(43): | |
18471 | ||
18472 | @quotation | |
18473 | ||
18474 | “A @code{Size} clause should be supported for an object if the specified | |
18475 | @code{Size} is at least as large as its subtype’s @code{Size}, and corresponds | |
18476 | to a size in storage elements that is a multiple of the object’s | |
18477 | @code{Alignment} (if the @code{Alignment} is nonzero).” | |
18478 | @end quotation | |
18479 | ||
18480 | An explicit size clause may be used to override the default size by | |
18481 | increasing it. For example, if we have: | |
18482 | ||
18483 | @example | |
18484 | type My_Boolean is new Boolean; | |
18485 | for My_Boolean'Size use 32; | |
18486 | @end example | |
18487 | ||
18488 | then values of this type will always be 32-bit long. In the case of discrete | |
18489 | types, the size can be increased up to 64 bits on 32-bit targets and 128 bits | |
18490 | on 64-bit targets, with the effect that the entire specified field is used to | |
18491 | hold the value, sign- or zero-extended as appropriate. If more than 64 bits | |
18492 | or 128 bits resp. is specified, then padding space is allocated after the | |
18493 | value, and a warning is issued that there are unused bits. | |
18494 | ||
18495 | Similarly the size of records and arrays may be increased, and the effect | |
18496 | is to add padding bits after the value. This also causes a warning message | |
18497 | to be generated. | |
18498 | ||
18499 | The largest Size value permitted in GNAT is 2**31-1. Since this is a | |
18500 | Size in bits, this corresponds to an object of size 256 megabytes (minus | |
18501 | one). This limitation is true on all targets. The reason for this | |
18502 | limitation is that it improves the quality of the code in many cases | |
18503 | if it is known that a Size value can be accommodated in an object of | |
18504 | type Integer. | |
18505 | ||
18506 | @node Storage_Size Clauses,Size of Variant Record Objects,Size Clauses,Representation Clauses and Pragmas | |
73918baf | 18507 | @anchor{gnat_rm/representation_clauses_and_pragmas id4}@anchor{283}@anchor{gnat_rm/representation_clauses_and_pragmas storage-size-clauses}@anchor{284} |
64d5610f ML |
18508 | @section Storage_Size Clauses |
18509 | ||
18510 | ||
18511 | @geindex Storage_Size Clause | |
18512 | ||
18513 | For tasks, the @code{Storage_Size} clause specifies the amount of space | |
18514 | to be allocated for the task stack. This cannot be extended, and if the | |
18515 | stack is exhausted, then @code{Storage_Error} will be raised (if stack | |
18516 | checking is enabled). Use a @code{Storage_Size} attribute definition clause, | |
18517 | or a @code{Storage_Size} pragma in the task definition to set the | |
18518 | appropriate required size. A useful technique is to include in every | |
18519 | task definition a pragma of the form: | |
18520 | ||
18521 | @example | |
18522 | pragma Storage_Size (Default_Stack_Size); | |
18523 | @end example | |
18524 | ||
18525 | Then @code{Default_Stack_Size} can be defined in a global package, and | |
18526 | modified as required. Any tasks requiring stack sizes different from the | |
18527 | default can have an appropriate alternative reference in the pragma. | |
18528 | ||
18529 | You can also use the `-d' binder switch to modify the default stack | |
18530 | size. | |
18531 | ||
18532 | For access types, the @code{Storage_Size} clause specifies the maximum | |
18533 | space available for allocation of objects of the type. If this space is | |
18534 | exceeded then @code{Storage_Error} will be raised by an allocation attempt. | |
18535 | In the case where the access type is declared local to a subprogram, the | |
18536 | use of a @code{Storage_Size} clause triggers automatic use of a special | |
18537 | predefined storage pool (@code{System.Pool_Size}) that ensures that all | |
18538 | space for the pool is automatically reclaimed on exit from the scope in | |
18539 | which the type is declared. | |
18540 | ||
18541 | A special case recognized by the compiler is the specification of a | |
18542 | @code{Storage_Size} of zero for an access type. This means that no | |
18543 | items can be allocated from the pool, and this is recognized at compile | |
18544 | time, and all the overhead normally associated with maintaining a fixed | |
18545 | size storage pool is eliminated. Consider the following example: | |
18546 | ||
18547 | @example | |
18548 | procedure p is | |
18549 | type R is array (Natural) of Character; | |
18550 | type P is access all R; | |
18551 | for P'Storage_Size use 0; | |
18552 | -- Above access type intended only for interfacing purposes | |
18553 | ||
18554 | y : P; | |
18555 | ||
18556 | procedure g (m : P); | |
18557 | pragma Import (C, g); | |
18558 | ||
18559 | -- ... | |
18560 | ||
18561 | begin | |
18562 | -- ... | |
18563 | y := new R; | |
18564 | end; | |
18565 | @end example | |
18566 | ||
18567 | As indicated in this example, these dummy storage pools are often useful in | |
18568 | connection with interfacing where no object will ever be allocated. If you | |
18569 | compile the above example, you get the warning: | |
18570 | ||
18571 | @example | |
18572 | p.adb:16:09: warning: allocation from empty storage pool | |
18573 | p.adb:16:09: warning: Storage_Error will be raised at run time | |
18574 | @end example | |
18575 | ||
18576 | Of course in practice, there will not be any explicit allocators in the | |
18577 | case of such an access declaration. | |
18578 | ||
18579 | @node Size of Variant Record Objects,Biased Representation,Storage_Size Clauses,Representation Clauses and Pragmas | |
73918baf | 18580 | @anchor{gnat_rm/representation_clauses_and_pragmas id5}@anchor{285}@anchor{gnat_rm/representation_clauses_and_pragmas size-of-variant-record-objects}@anchor{286} |
64d5610f ML |
18581 | @section Size of Variant Record Objects |
18582 | ||
18583 | ||
18584 | @geindex Size | |
18585 | @geindex variant record objects | |
18586 | ||
18587 | @geindex Variant record objects | |
18588 | @geindex size | |
18589 | ||
18590 | In the case of variant record objects, there is a question whether Size gives | |
18591 | information about a particular variant, or the maximum size required | |
18592 | for any variant. Consider the following program | |
18593 | ||
18594 | @example | |
18595 | with Text_IO; use Text_IO; | |
18596 | procedure q is | |
18597 | type R1 (A : Boolean := False) is record | |
18598 | case A is | |
18599 | when True => X : Character; | |
18600 | when False => null; | |
18601 | end case; | |
18602 | end record; | |
18603 | ||
18604 | V1 : R1 (False); | |
18605 | V2 : R1; | |
18606 | ||
18607 | begin | |
18608 | Put_Line (Integer'Image (V1'Size)); | |
18609 | Put_Line (Integer'Image (V2'Size)); | |
18610 | end q; | |
18611 | @end example | |
18612 | ||
18613 | Here we are dealing with a variant record, where the True variant | |
18614 | requires 16 bits, and the False variant requires 8 bits. | |
18615 | In the above example, both V1 and V2 contain the False variant, | |
18616 | which is only 8 bits long. However, the result of running the | |
18617 | program is: | |
18618 | ||
18619 | @example | |
18620 | 8 | |
18621 | 16 | |
18622 | @end example | |
18623 | ||
18624 | The reason for the difference here is that the discriminant value of | |
18625 | V1 is fixed, and will always be False. It is not possible to assign | |
18626 | a True variant value to V1, therefore 8 bits is sufficient. On the | |
18627 | other hand, in the case of V2, the initial discriminant value is | |
18628 | False (from the default), but it is possible to assign a True | |
18629 | variant value to V2, therefore 16 bits must be allocated for V2 | |
18630 | in the general case, even fewer bits may be needed at any particular | |
18631 | point during the program execution. | |
18632 | ||
18633 | As can be seen from the output of this program, the @code{'Size} | |
18634 | attribute applied to such an object in GNAT gives the actual allocated | |
18635 | size of the variable, which is the largest size of any of the variants. | |
18636 | The Ada Reference Manual is not completely clear on what choice should | |
18637 | be made here, but the GNAT behavior seems most consistent with the | |
18638 | language in the RM. | |
18639 | ||
18640 | In some cases, it may be desirable to obtain the size of the current | |
18641 | variant, rather than the size of the largest variant. This can be | |
18642 | achieved in GNAT by making use of the fact that in the case of a | |
18643 | subprogram parameter, GNAT does indeed return the size of the current | |
18644 | variant (because a subprogram has no way of knowing how much space | |
18645 | is actually allocated for the actual). | |
18646 | ||
18647 | Consider the following modified version of the above program: | |
18648 | ||
18649 | @example | |
18650 | with Text_IO; use Text_IO; | |
18651 | procedure q is | |
18652 | type R1 (A : Boolean := False) is record | |
18653 | case A is | |
18654 | when True => X : Character; | |
18655 | when False => null; | |
18656 | end case; | |
18657 | end record; | |
18658 | ||
18659 | V2 : R1; | |
18660 | ||
18661 | function Size (V : R1) return Integer is | |
18662 | begin | |
18663 | return V'Size; | |
18664 | end Size; | |
18665 | ||
18666 | begin | |
18667 | Put_Line (Integer'Image (V2'Size)); | |
18668 | Put_Line (Integer'Image (Size (V2))); | |
18669 | V2 := (True, 'x'); | |
18670 | Put_Line (Integer'Image (V2'Size)); | |
18671 | Put_Line (Integer'Image (Size (V2))); | |
18672 | end q; | |
18673 | @end example | |
18674 | ||
18675 | The output from this program is | |
18676 | ||
18677 | @example | |
18678 | 16 | |
18679 | 8 | |
18680 | 16 | |
18681 | 16 | |
18682 | @end example | |
18683 | ||
18684 | Here we see that while the @code{'Size} attribute always returns | |
18685 | the maximum size, regardless of the current variant value, the | |
18686 | @code{Size} function does indeed return the size of the current | |
18687 | variant value. | |
18688 | ||
18689 | @node Biased Representation,Value_Size and Object_Size Clauses,Size of Variant Record Objects,Representation Clauses and Pragmas | |
73918baf | 18690 | @anchor{gnat_rm/representation_clauses_and_pragmas biased-representation}@anchor{287}@anchor{gnat_rm/representation_clauses_and_pragmas id6}@anchor{288} |
64d5610f ML |
18691 | @section Biased Representation |
18692 | ||
18693 | ||
18694 | @geindex Size for biased representation | |
18695 | ||
18696 | @geindex Biased representation | |
18697 | ||
18698 | In the case of scalars with a range starting at other than zero, it is | |
18699 | possible in some cases to specify a size smaller than the default minimum | |
18700 | value, and in such cases, GNAT uses an unsigned biased representation, | |
18701 | in which zero is used to represent the lower bound, and successive values | |
18702 | represent successive values of the type. | |
18703 | ||
18704 | For example, suppose we have the declaration: | |
18705 | ||
18706 | @example | |
18707 | type Small is range -7 .. -4; | |
18708 | for Small'Size use 2; | |
18709 | @end example | |
18710 | ||
18711 | Although the default size of type @code{Small} is 4, the @code{Size} | |
18712 | clause is accepted by GNAT and results in the following representation | |
18713 | scheme: | |
18714 | ||
18715 | @example | |
18716 | -7 is represented as 2#00# | |
18717 | -6 is represented as 2#01# | |
18718 | -5 is represented as 2#10# | |
18719 | -4 is represented as 2#11# | |
18720 | @end example | |
18721 | ||
18722 | Biased representation is only used if the specified @code{Size} clause | |
18723 | cannot be accepted in any other manner. These reduced sizes that force | |
18724 | biased representation can be used for all discrete types except for | |
18725 | enumeration types for which a representation clause is given. | |
18726 | ||
18727 | @node Value_Size and Object_Size Clauses,Component_Size Clauses,Biased Representation,Representation Clauses and Pragmas | |
73918baf | 18728 | @anchor{gnat_rm/representation_clauses_and_pragmas id7}@anchor{289}@anchor{gnat_rm/representation_clauses_and_pragmas value-size-and-object-size-clauses}@anchor{28a} |
64d5610f ML |
18729 | @section Value_Size and Object_Size Clauses |
18730 | ||
18731 | ||
18732 | @geindex Value_Size | |
18733 | ||
18734 | @geindex Object_Size | |
18735 | ||
18736 | @geindex Size | |
18737 | @geindex of objects | |
18738 | ||
18739 | In Ada 95 and Ada 2005, @code{T'Size} for a type @code{T} is the minimum | |
18740 | number of bits required to hold values of type @code{T}. | |
18741 | Although this interpretation was allowed in Ada 83, it was not required, | |
18742 | and this requirement in practice can cause some significant difficulties. | |
18743 | For example, in most Ada 83 compilers, @code{Natural'Size} was 32. | |
18744 | However, in Ada 95 and Ada 2005, | |
18745 | @code{Natural'Size} is | |
18746 | typically 31. This means that code may change in behavior when moving | |
18747 | from Ada 83 to Ada 95 or Ada 2005. For example, consider: | |
18748 | ||
18749 | @example | |
18750 | type Rec is record | |
18751 | A : Natural; | |
18752 | B : Natural; | |
18753 | end record; | |
18754 | ||
18755 | for Rec use record | |
18756 | A at 0 range 0 .. Natural'Size - 1; | |
18757 | B at 0 range Natural'Size .. 2 * Natural'Size - 1; | |
18758 | end record; | |
18759 | @end example | |
18760 | ||
18761 | In the above code, since the typical size of @code{Natural} objects | |
18762 | is 32 bits and @code{Natural'Size} is 31, the above code can cause | |
18763 | unexpected inefficient packing in Ada 95 and Ada 2005, and in general | |
18764 | there are cases where the fact that the object size can exceed the | |
18765 | size of the type causes surprises. | |
18766 | ||
18767 | To help get around this problem GNAT provides two implementation | |
18768 | defined attributes, @code{Value_Size} and @code{Object_Size}. When | |
18769 | applied to a type, these attributes yield the size of the type | |
18770 | (corresponding to the RM defined size attribute), and the size of | |
18771 | objects of the type respectively. | |
18772 | ||
18773 | The @code{Object_Size} is used for determining the default size of | |
18774 | objects and components. This size value can be referred to using the | |
18775 | @code{Object_Size} attribute. The phrase ‘is used’ here means that it is | |
18776 | the basis of the determination of the size. The backend is free to | |
18777 | pad this up if necessary for efficiency, e.g., an 8-bit stand-alone | |
18778 | character might be stored in 32 bits on a machine with no efficient | |
18779 | byte access instructions such as the Alpha. | |
18780 | ||
18781 | The default rules for the value of @code{Object_Size} for | |
18782 | discrete types are as follows: | |
18783 | ||
18784 | ||
18785 | @itemize * | |
18786 | ||
18787 | @item | |
18788 | The @code{Object_Size} for base subtypes reflect the natural hardware | |
18789 | size in bits (run the compiler with `-gnatS' to find those values | |
18790 | for numeric types). Enumeration types and fixed-point base subtypes have | |
18791 | 8, 16, 32, or 64 bits for this size, depending on the range of values | |
18792 | to be stored. | |
18793 | ||
18794 | @item | |
18795 | The @code{Object_Size} of a subtype is the same as the | |
18796 | @code{Object_Size} of | |
18797 | the type from which it is obtained. | |
18798 | ||
18799 | @item | |
18800 | The @code{Object_Size} of a derived base type is copied from the parent | |
18801 | base type, and the @code{Object_Size} of a derived first subtype is copied | |
18802 | from the parent first subtype. | |
18803 | @end itemize | |
18804 | ||
18805 | The @code{Value_Size} attribute | |
18806 | is the (minimum) number of bits required to store a value | |
18807 | of the type. | |
18808 | This value is used to determine how tightly to pack | |
18809 | records or arrays with components of this type, and also affects | |
18810 | the semantics of unchecked conversion (unchecked conversions where | |
18811 | the @code{Value_Size} values differ generate a warning, and are potentially | |
18812 | target dependent). | |
18813 | ||
18814 | The default rules for the value of @code{Value_Size} are as follows: | |
18815 | ||
18816 | ||
18817 | @itemize * | |
18818 | ||
18819 | @item | |
18820 | The @code{Value_Size} for a base subtype is the minimum number of bits | |
18821 | required to store all values of the type (including the sign bit | |
18822 | only if negative values are possible). | |
18823 | ||
18824 | @item | |
18825 | If a subtype statically matches the first subtype of a given type, then it has | |
18826 | by default the same @code{Value_Size} as the first subtype. (This is a | |
18827 | consequence of RM 13.1(14): “if two subtypes statically match, | |
18828 | then their subtype-specific aspects are the same”.) | |
18829 | ||
18830 | @item | |
18831 | All other subtypes have a @code{Value_Size} corresponding to the minimum | |
18832 | number of bits required to store all values of the subtype. For | |
18833 | dynamic bounds, it is assumed that the value can range down or up | |
18834 | to the corresponding bound of the ancestor | |
18835 | @end itemize | |
18836 | ||
18837 | The RM defined attribute @code{Size} corresponds to the | |
18838 | @code{Value_Size} attribute. | |
18839 | ||
18840 | The @code{Size} attribute may be defined for a first-named subtype. This sets | |
18841 | the @code{Value_Size} of | |
18842 | the first-named subtype to the given value, and the | |
18843 | @code{Object_Size} of this first-named subtype to the given value padded up | |
18844 | to an appropriate boundary. It is a consequence of the default rules | |
18845 | above that this @code{Object_Size} will apply to all further subtypes. On the | |
18846 | other hand, @code{Value_Size} is affected only for the first subtype, any | |
18847 | dynamic subtypes obtained from it directly, and any statically matching | |
18848 | subtypes. The @code{Value_Size} of any other static subtypes is not affected. | |
18849 | ||
18850 | @code{Value_Size} and | |
18851 | @code{Object_Size} may be explicitly set for any subtype using | |
18852 | an attribute definition clause. Note that the use of these attributes | |
18853 | can cause the RM 13.1(14) rule to be violated. If two access types | |
18854 | reference aliased objects whose subtypes have differing @code{Object_Size} | |
18855 | values as a result of explicit attribute definition clauses, then it | |
18856 | is illegal to convert from one access subtype to the other. For a more | |
18857 | complete description of this additional legality rule, see the | |
18858 | description of the @code{Object_Size} attribute. | |
18859 | ||
18860 | To get a feel for the difference, consider the following examples (note | |
18861 | that in each case the base is @code{Short_Short_Integer} with a size of 8): | |
18862 | ||
18863 | ||
18864 | @multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxx} | |
18865 | @headitem | |
18866 | ||
18867 | Type or subtype declaration | |
18868 | ||
18869 | @tab | |
18870 | ||
18871 | Object_Size | |
18872 | ||
18873 | @tab | |
18874 | ||
18875 | Value_Size | |
18876 | ||
18877 | @item | |
18878 | ||
18879 | @code{type x1 is range 0 .. 5;} | |
18880 | ||
18881 | @tab | |
18882 | ||
18883 | 8 | |
18884 | ||
18885 | @tab | |
18886 | ||
18887 | 3 | |
18888 | ||
18889 | @item | |
18890 | ||
18891 | @code{type x2 is range 0 .. 5;} | |
18892 | @code{for x2'size use 12;} | |
18893 | ||
18894 | @tab | |
18895 | ||
18896 | 16 | |
18897 | ||
18898 | @tab | |
18899 | ||
18900 | 12 | |
18901 | ||
18902 | @item | |
18903 | ||
18904 | @code{subtype x3 is x2 range 0 .. 3;} | |
18905 | ||
18906 | @tab | |
18907 | ||
18908 | 16 | |
18909 | ||
18910 | @tab | |
18911 | ||
18912 | 2 | |
18913 | ||
18914 | @item | |
18915 | ||
18916 | @code{subtype x4 is x2'base range 0 .. 10;} | |
18917 | ||
18918 | @tab | |
18919 | ||
18920 | 8 | |
18921 | ||
18922 | @tab | |
18923 | ||
18924 | 4 | |
18925 | ||
18926 | @item | |
18927 | ||
18928 | @code{dynamic : x2'Base range -64 .. +63;} | |
18929 | ||
18930 | @tab | |
18931 | ||
18932 | @tab | |
18933 | ||
18934 | @item | |
18935 | ||
18936 | @code{subtype x5 is x2 range 0 .. dynamic;} | |
18937 | ||
18938 | @tab | |
18939 | ||
18940 | 16 | |
18941 | ||
18942 | @tab | |
18943 | ||
18944 | 3* | |
18945 | ||
18946 | @item | |
18947 | ||
18948 | @code{subtype x6 is x2'base range 0 .. dynamic;} | |
18949 | ||
18950 | @tab | |
18951 | ||
18952 | 8 | |
18953 | ||
18954 | @tab | |
18955 | ||
18956 | 7* | |
18957 | ||
18958 | @end multitable | |
18959 | ||
18960 | ||
18961 | Note: the entries marked ‘*’ are not actually specified by the Ada | |
18962 | Reference Manual, which has nothing to say about size in the dynamic | |
18963 | case. What GNAT does is to allocate sufficient bits to accommodate any | |
18964 | possible dynamic values for the bounds at run-time. | |
18965 | ||
18966 | So far, so good, but GNAT has to obey the RM rules, so the question is | |
18967 | under what conditions must the RM @code{Size} be used. | |
18968 | The following is a list | |
18969 | of the occasions on which the RM @code{Size} must be used: | |
18970 | ||
18971 | ||
18972 | @itemize * | |
18973 | ||
18974 | @item | |
18975 | Component size for packed arrays or records | |
18976 | ||
18977 | @item | |
18978 | Value of the attribute @code{Size} for a type | |
18979 | ||
18980 | @item | |
18981 | Warning about sizes not matching for unchecked conversion | |
18982 | @end itemize | |
18983 | ||
18984 | For record types, the @code{Object_Size} is always a multiple of the | |
18985 | alignment of the type (this is true for all types). In some cases the | |
18986 | @code{Value_Size} can be smaller. Consider: | |
18987 | ||
18988 | @example | |
18989 | type R is record | |
18990 | X : Integer; | |
18991 | Y : Character; | |
18992 | end record; | |
18993 | @end example | |
18994 | ||
18995 | On a typical 32-bit architecture, the X component will occupy four bytes | |
18996 | and the Y component will occupy one byte, for a total of 5 bytes. As a | |
18997 | result @code{R'Value_Size} will be 40 (bits) since this is the minimum size | |
18998 | required to store a value of this type. For example, it is permissible | |
18999 | to have a component of type R in an array whose component size is | |
19000 | specified to be 40 bits. | |
19001 | ||
19002 | However, @code{R'Object_Size} will be 64 (bits). The difference is due to | |
19003 | the alignment requirement for objects of the record type. The X | |
19004 | component will require four-byte alignment because that is what type | |
19005 | Integer requires, whereas the Y component, a Character, will only | |
19006 | require 1-byte alignment. Since the alignment required for X is the | |
19007 | greatest of all the components’ alignments, that is the alignment | |
19008 | required for the enclosing record type, i.e., 4 bytes or 32 bits. As | |
19009 | indicated above, the actual object size must be rounded up so that it is | |
19010 | a multiple of the alignment value. Therefore, 40 bits rounded up to the | |
19011 | next multiple of 32 yields 64 bits. | |
19012 | ||
19013 | For all other types, the @code{Object_Size} | |
19014 | and @code{Value_Size} are the same (and equivalent to the RM attribute @code{Size}). | |
19015 | Only @code{Size} may be specified for such types. | |
19016 | ||
19017 | Note that @code{Value_Size} can be used to force biased representation | |
19018 | for a particular subtype. Consider this example: | |
19019 | ||
19020 | @example | |
19021 | type R is (A, B, C, D, E, F); | |
19022 | subtype RAB is R range A .. B; | |
19023 | subtype REF is R range E .. F; | |
19024 | @end example | |
19025 | ||
19026 | By default, @code{RAB} | |
19027 | has a size of 1 (sufficient to accommodate the representation | |
19028 | of @code{A} and @code{B}, 0 and 1), and @code{REF} | |
19029 | has a size of 3 (sufficient to accommodate the representation | |
19030 | of @code{E} and @code{F}, 4 and 5). But if we add the | |
19031 | following @code{Value_Size} attribute definition clause: | |
19032 | ||
19033 | @example | |
19034 | for REF'Value_Size use 1; | |
19035 | @end example | |
19036 | ||
19037 | then biased representation is forced for @code{REF}, | |
19038 | and 0 will represent @code{E} and 1 will represent @code{F}. | |
19039 | A warning is issued when a @code{Value_Size} attribute | |
19040 | definition clause forces biased representation. This | |
19041 | warning can be turned off using @code{-gnatw.B}. | |
19042 | ||
19043 | @node Component_Size Clauses,Bit_Order Clauses,Value_Size and Object_Size Clauses,Representation Clauses and Pragmas | |
73918baf | 19044 | @anchor{gnat_rm/representation_clauses_and_pragmas component-size-clauses}@anchor{28b}@anchor{gnat_rm/representation_clauses_and_pragmas id8}@anchor{28c} |
64d5610f ML |
19045 | @section Component_Size Clauses |
19046 | ||
19047 | ||
19048 | @geindex Component_Size Clause | |
19049 | ||
19050 | Normally, the value specified in a component size clause must be consistent | |
19051 | with the subtype of the array component with regard to size and alignment. | |
19052 | In other words, the value specified must be at least equal to the size | |
19053 | of this subtype, and must be a multiple of the alignment value. | |
19054 | ||
19055 | In addition, component size clauses are allowed which cause the array | |
19056 | to be packed, by specifying a smaller value. A first case is for | |
19057 | component size values in the range 1 through 63 on 32-bit targets, | |
19058 | and 1 through 127 on 64-bit targets. The value specified may not | |
19059 | be smaller than the Size of the subtype. GNAT will accurately | |
19060 | honor all packing requests in this range. For example, if we have: | |
19061 | ||
19062 | @example | |
19063 | type r is array (1 .. 8) of Natural; | |
19064 | for r'Component_Size use 31; | |
19065 | @end example | |
19066 | ||
19067 | then the resulting array has a length of 31 bytes (248 bits = 8 * 31). | |
19068 | Of course access to the components of such an array is considerably | |
19069 | less efficient than if the natural component size of 32 is used. | |
19070 | A second case is when the subtype of the component is a record type | |
19071 | padded because of its default alignment. For example, if we have: | |
19072 | ||
19073 | @example | |
19074 | type r is record | |
19075 | i : Integer; | |
19076 | j : Integer; | |
19077 | b : Boolean; | |
19078 | end record; | |
19079 | ||
19080 | type a is array (1 .. 8) of r; | |
19081 | for a'Component_Size use 72; | |
19082 | @end example | |
19083 | ||
19084 | then the resulting array has a length of 72 bytes, instead of 96 bytes | |
19085 | if the alignment of the record (4) was obeyed. | |
19086 | ||
19087 | Note that there is no point in giving both a component size clause | |
19088 | and a pragma Pack for the same array type. if such duplicate | |
19089 | clauses are given, the pragma Pack will be ignored. | |
19090 | ||
19091 | @node Bit_Order Clauses,Effect of Bit_Order on Byte Ordering,Component_Size Clauses,Representation Clauses and Pragmas | |
73918baf | 19092 | @anchor{gnat_rm/representation_clauses_and_pragmas bit-order-clauses}@anchor{28d}@anchor{gnat_rm/representation_clauses_and_pragmas id9}@anchor{28e} |
64d5610f ML |
19093 | @section Bit_Order Clauses |
19094 | ||
19095 | ||
19096 | @geindex Bit_Order Clause | |
19097 | ||
19098 | @geindex bit ordering | |
19099 | ||
19100 | @geindex ordering | |
19101 | @geindex of bits | |
19102 | ||
19103 | For record subtypes, GNAT permits the specification of the @code{Bit_Order} | |
19104 | attribute. The specification may either correspond to the default bit | |
19105 | order for the target, in which case the specification has no effect and | |
19106 | places no additional restrictions, or it may be for the non-standard | |
19107 | setting (that is the opposite of the default). | |
19108 | ||
19109 | In the case where the non-standard value is specified, the effect is | |
19110 | to renumber bits within each byte, but the ordering of bytes is not | |
19111 | affected. There are certain | |
19112 | restrictions placed on component clauses as follows: | |
19113 | ||
19114 | ||
19115 | @itemize * | |
19116 | ||
19117 | @item | |
19118 | Components fitting within a single storage unit. | |
19119 | ||
19120 | These are unrestricted, and the effect is merely to renumber bits. For | |
19121 | example if we are on a little-endian machine with @code{Low_Order_First} | |
19122 | being the default, then the following two declarations have exactly | |
19123 | the same effect: | |
19124 | ||
19125 | @example | |
19126 | type R1 is record | |
19127 | A : Boolean; | |
19128 | B : Integer range 1 .. 120; | |
19129 | end record; | |
19130 | ||
19131 | for R1 use record | |
19132 | A at 0 range 0 .. 0; | |
19133 | B at 0 range 1 .. 7; | |
19134 | end record; | |
19135 | ||
19136 | type R2 is record | |
19137 | A : Boolean; | |
19138 | B : Integer range 1 .. 120; | |
19139 | end record; | |
19140 | ||
19141 | for R2'Bit_Order use High_Order_First; | |
19142 | ||
19143 | for R2 use record | |
19144 | A at 0 range 7 .. 7; | |
19145 | B at 0 range 0 .. 6; | |
19146 | end record; | |
19147 | @end example | |
19148 | ||
19149 | The useful application here is to write the second declaration with the | |
19150 | @code{Bit_Order} attribute definition clause, and know that it will be treated | |
19151 | the same, regardless of whether the target is little-endian or big-endian. | |
19152 | ||
19153 | @item | |
19154 | Components occupying an integral number of bytes. | |
19155 | ||
19156 | These are components that exactly fit in two or more bytes. Such component | |
19157 | declarations are allowed, but have no effect, since it is important to realize | |
19158 | that the @code{Bit_Order} specification does not affect the ordering of bytes. | |
19159 | In particular, the following attempt at getting an endian-independent integer | |
19160 | does not work: | |
19161 | ||
19162 | @example | |
19163 | type R2 is record | |
19164 | A : Integer; | |
19165 | end record; | |
19166 | ||
19167 | for R2'Bit_Order use High_Order_First; | |
19168 | ||
19169 | for R2 use record | |
19170 | A at 0 range 0 .. 31; | |
19171 | end record; | |
19172 | @end example | |
19173 | ||
19174 | This declaration will result in a little-endian integer on a | |
19175 | little-endian machine, and a big-endian integer on a big-endian machine. | |
19176 | If byte flipping is required for interoperability between big- and | |
19177 | little-endian machines, this must be explicitly programmed. This capability | |
19178 | is not provided by @code{Bit_Order}. | |
19179 | ||
19180 | @item | |
19181 | Components that are positioned across byte boundaries. | |
19182 | ||
19183 | but do not occupy an integral number of bytes. Given that bytes are not | |
19184 | reordered, such fields would occupy a non-contiguous sequence of bits | |
19185 | in memory, requiring non-trivial code to reassemble. They are for this | |
19186 | reason not permitted, and any component clause specifying such a layout | |
19187 | will be flagged as illegal by GNAT. | |
19188 | @end itemize | |
19189 | ||
19190 | Since the misconception that Bit_Order automatically deals with all | |
19191 | endian-related incompatibilities is a common one, the specification of | |
19192 | a component field that is an integral number of bytes will always | |
19193 | generate a warning. This warning may be suppressed using @code{pragma Warnings (Off)} | |
19194 | if desired. The following section contains additional | |
19195 | details regarding the issue of byte ordering. | |
19196 | ||
19197 | @node Effect of Bit_Order on Byte Ordering,Pragma Pack for Arrays,Bit_Order Clauses,Representation Clauses and Pragmas | |
73918baf | 19198 | @anchor{gnat_rm/representation_clauses_and_pragmas effect-of-bit-order-on-byte-ordering}@anchor{28f}@anchor{gnat_rm/representation_clauses_and_pragmas id10}@anchor{290} |
64d5610f ML |
19199 | @section Effect of Bit_Order on Byte Ordering |
19200 | ||
19201 | ||
19202 | @geindex byte ordering | |
19203 | ||
19204 | @geindex ordering | |
19205 | @geindex of bytes | |
19206 | ||
19207 | In this section we will review the effect of the @code{Bit_Order} attribute | |
19208 | definition clause on byte ordering. Briefly, it has no effect at all, but | |
19209 | a detailed example will be helpful. Before giving this | |
19210 | example, let us review the precise | |
19211 | definition of the effect of defining @code{Bit_Order}. The effect of a | |
19212 | non-standard bit order is described in section 13.5.3 of the Ada | |
19213 | Reference Manual: | |
19214 | ||
19215 | @quotation | |
19216 | ||
19217 | “2 A bit ordering is a method of interpreting the meaning of | |
19218 | the storage place attributes.” | |
19219 | @end quotation | |
19220 | ||
19221 | To understand the precise definition of storage place attributes in | |
19222 | this context, we visit section 13.5.1 of the manual: | |
19223 | ||
19224 | @quotation | |
19225 | ||
19226 | “13 A record_representation_clause (without the mod_clause) | |
19227 | specifies the layout. The storage place attributes (see 13.5.2) | |
19228 | are taken from the values of the position, first_bit, and last_bit | |
19229 | expressions after normalizing those values so that first_bit is | |
19230 | less than Storage_Unit.” | |
19231 | @end quotation | |
19232 | ||
19233 | The critical point here is that storage places are taken from | |
19234 | the values after normalization, not before. So the @code{Bit_Order} | |
19235 | interpretation applies to normalized values. The interpretation | |
19236 | is described in the later part of the 13.5.3 paragraph: | |
19237 | ||
19238 | @quotation | |
19239 | ||
19240 | “2 A bit ordering is a method of interpreting the meaning of | |
19241 | the storage place attributes. High_Order_First (known in the | |
19242 | vernacular as ‘big endian’) means that the first bit of a | |
19243 | storage element (bit 0) is the most significant bit (interpreting | |
19244 | the sequence of bits that represent a component as an unsigned | |
19245 | integer value). Low_Order_First (known in the vernacular as | |
19246 | ‘little endian’) means the opposite: the first bit is the | |
19247 | least significant.” | |
19248 | @end quotation | |
19249 | ||
19250 | Note that the numbering is with respect to the bits of a storage | |
19251 | unit. In other words, the specification affects only the numbering | |
19252 | of bits within a single storage unit. | |
19253 | ||
19254 | We can make the effect clearer by giving an example. | |
19255 | ||
19256 | Suppose that we have an external device which presents two bytes, the first | |
19257 | byte presented, which is the first (low addressed byte) of the two byte | |
19258 | record is called Master, and the second byte is called Slave. | |
19259 | ||
19260 | The left most (most significant) bit is called Control for each byte, and | |
19261 | the remaining 7 bits are called V1, V2, … V7, where V7 is the rightmost | |
19262 | (least significant) bit. | |
19263 | ||
19264 | On a big-endian machine, we can write the following representation clause | |
19265 | ||
19266 | @example | |
19267 | type Data is record | |
19268 | Master_Control : Bit; | |
19269 | Master_V1 : Bit; | |
19270 | Master_V2 : Bit; | |
19271 | Master_V3 : Bit; | |
19272 | Master_V4 : Bit; | |
19273 | Master_V5 : Bit; | |
19274 | Master_V6 : Bit; | |
19275 | Master_V7 : Bit; | |
19276 | Slave_Control : Bit; | |
19277 | Slave_V1 : Bit; | |
19278 | Slave_V2 : Bit; | |
19279 | Slave_V3 : Bit; | |
19280 | Slave_V4 : Bit; | |
19281 | Slave_V5 : Bit; | |
19282 | Slave_V6 : Bit; | |
19283 | Slave_V7 : Bit; | |
19284 | end record; | |
19285 | ||
19286 | for Data use record | |
19287 | Master_Control at 0 range 0 .. 0; | |
19288 | Master_V1 at 0 range 1 .. 1; | |
19289 | Master_V2 at 0 range 2 .. 2; | |
19290 | Master_V3 at 0 range 3 .. 3; | |
19291 | Master_V4 at 0 range 4 .. 4; | |
19292 | Master_V5 at 0 range 5 .. 5; | |
19293 | Master_V6 at 0 range 6 .. 6; | |
19294 | Master_V7 at 0 range 7 .. 7; | |
19295 | Slave_Control at 1 range 0 .. 0; | |
19296 | Slave_V1 at 1 range 1 .. 1; | |
19297 | Slave_V2 at 1 range 2 .. 2; | |
19298 | Slave_V3 at 1 range 3 .. 3; | |
19299 | Slave_V4 at 1 range 4 .. 4; | |
19300 | Slave_V5 at 1 range 5 .. 5; | |
19301 | Slave_V6 at 1 range 6 .. 6; | |
19302 | Slave_V7 at 1 range 7 .. 7; | |
19303 | end record; | |
19304 | @end example | |
19305 | ||
19306 | Now if we move this to a little endian machine, then the bit ordering within | |
19307 | the byte is backwards, so we have to rewrite the record rep clause as: | |
19308 | ||
19309 | @example | |
19310 | for Data use record | |
19311 | Master_Control at 0 range 7 .. 7; | |
19312 | Master_V1 at 0 range 6 .. 6; | |
19313 | Master_V2 at 0 range 5 .. 5; | |
19314 | Master_V3 at 0 range 4 .. 4; | |
19315 | Master_V4 at 0 range 3 .. 3; | |
19316 | Master_V5 at 0 range 2 .. 2; | |
19317 | Master_V6 at 0 range 1 .. 1; | |
19318 | Master_V7 at 0 range 0 .. 0; | |
19319 | Slave_Control at 1 range 7 .. 7; | |
19320 | Slave_V1 at 1 range 6 .. 6; | |
19321 | Slave_V2 at 1 range 5 .. 5; | |
19322 | Slave_V3 at 1 range 4 .. 4; | |
19323 | Slave_V4 at 1 range 3 .. 3; | |
19324 | Slave_V5 at 1 range 2 .. 2; | |
19325 | Slave_V6 at 1 range 1 .. 1; | |
19326 | Slave_V7 at 1 range 0 .. 0; | |
19327 | end record; | |
19328 | @end example | |
19329 | ||
19330 | It is a nuisance to have to rewrite the clause, especially if | |
19331 | the code has to be maintained on both machines. However, | |
19332 | this is a case that we can handle with the | |
19333 | @code{Bit_Order} attribute if it is implemented. | |
19334 | Note that the implementation is not required on byte addressed | |
19335 | machines, but it is indeed implemented in GNAT. | |
19336 | This means that we can simply use the | |
19337 | first record clause, together with the declaration | |
19338 | ||
19339 | @example | |
19340 | for Data'Bit_Order use High_Order_First; | |
19341 | @end example | |
19342 | ||
19343 | and the effect is what is desired, namely the layout is exactly the same, | |
19344 | independent of whether the code is compiled on a big-endian or little-endian | |
19345 | machine. | |
19346 | ||
19347 | The important point to understand is that byte ordering is not affected. | |
19348 | A @code{Bit_Order} attribute definition never affects which byte a field | |
19349 | ends up in, only where it ends up in that byte. | |
19350 | To make this clear, let us rewrite the record rep clause of the previous | |
19351 | example as: | |
19352 | ||
19353 | @example | |
19354 | for Data'Bit_Order use High_Order_First; | |
19355 | for Data use record | |
19356 | Master_Control at 0 range 0 .. 0; | |
19357 | Master_V1 at 0 range 1 .. 1; | |
19358 | Master_V2 at 0 range 2 .. 2; | |
19359 | Master_V3 at 0 range 3 .. 3; | |
19360 | Master_V4 at 0 range 4 .. 4; | |
19361 | Master_V5 at 0 range 5 .. 5; | |
19362 | Master_V6 at 0 range 6 .. 6; | |
19363 | Master_V7 at 0 range 7 .. 7; | |
19364 | Slave_Control at 0 range 8 .. 8; | |
19365 | Slave_V1 at 0 range 9 .. 9; | |
19366 | Slave_V2 at 0 range 10 .. 10; | |
19367 | Slave_V3 at 0 range 11 .. 11; | |
19368 | Slave_V4 at 0 range 12 .. 12; | |
19369 | Slave_V5 at 0 range 13 .. 13; | |
19370 | Slave_V6 at 0 range 14 .. 14; | |
19371 | Slave_V7 at 0 range 15 .. 15; | |
19372 | end record; | |
19373 | @end example | |
19374 | ||
19375 | This is exactly equivalent to saying (a repeat of the first example): | |
19376 | ||
19377 | @example | |
19378 | for Data'Bit_Order use High_Order_First; | |
19379 | for Data use record | |
19380 | Master_Control at 0 range 0 .. 0; | |
19381 | Master_V1 at 0 range 1 .. 1; | |
19382 | Master_V2 at 0 range 2 .. 2; | |
19383 | Master_V3 at 0 range 3 .. 3; | |
19384 | Master_V4 at 0 range 4 .. 4; | |
19385 | Master_V5 at 0 range 5 .. 5; | |
19386 | Master_V6 at 0 range 6 .. 6; | |
19387 | Master_V7 at 0 range 7 .. 7; | |
19388 | Slave_Control at 1 range 0 .. 0; | |
19389 | Slave_V1 at 1 range 1 .. 1; | |
19390 | Slave_V2 at 1 range 2 .. 2; | |
19391 | Slave_V3 at 1 range 3 .. 3; | |
19392 | Slave_V4 at 1 range 4 .. 4; | |
19393 | Slave_V5 at 1 range 5 .. 5; | |
19394 | Slave_V6 at 1 range 6 .. 6; | |
19395 | Slave_V7 at 1 range 7 .. 7; | |
19396 | end record; | |
19397 | @end example | |
19398 | ||
19399 | Why are they equivalent? Well take a specific field, the @code{Slave_V2} | |
19400 | field. The storage place attributes are obtained by normalizing the | |
19401 | values given so that the @code{First_Bit} value is less than 8. After | |
19402 | normalizing the values (0,10,10) we get (1,2,2) which is exactly what | |
19403 | we specified in the other case. | |
19404 | ||
19405 | Now one might expect that the @code{Bit_Order} attribute might affect | |
19406 | bit numbering within the entire record component (two bytes in this | |
19407 | case, thus affecting which byte fields end up in), but that is not | |
19408 | the way this feature is defined, it only affects numbering of bits, | |
19409 | not which byte they end up in. | |
19410 | ||
19411 | Consequently it never makes sense to specify a starting bit number | |
19412 | greater than 7 (for a byte addressable field) if an attribute | |
19413 | definition for @code{Bit_Order} has been given, and indeed it | |
19414 | may be actively confusing to specify such a value, so the compiler | |
19415 | generates a warning for such usage. | |
19416 | ||
19417 | If you do need to control byte ordering then appropriate conditional | |
19418 | values must be used. If in our example, the slave byte came first on | |
19419 | some machines we might write: | |
19420 | ||
19421 | @example | |
19422 | Master_Byte_First constant Boolean := ...; | |
19423 | ||
19424 | Master_Byte : constant Natural := | |
19425 | 1 - Boolean'Pos (Master_Byte_First); | |
19426 | Slave_Byte : constant Natural := | |
19427 | Boolean'Pos (Master_Byte_First); | |
19428 | ||
19429 | for Data'Bit_Order use High_Order_First; | |
19430 | for Data use record | |
19431 | Master_Control at Master_Byte range 0 .. 0; | |
19432 | Master_V1 at Master_Byte range 1 .. 1; | |
19433 | Master_V2 at Master_Byte range 2 .. 2; | |
19434 | Master_V3 at Master_Byte range 3 .. 3; | |
19435 | Master_V4 at Master_Byte range 4 .. 4; | |
19436 | Master_V5 at Master_Byte range 5 .. 5; | |
19437 | Master_V6 at Master_Byte range 6 .. 6; | |
19438 | Master_V7 at Master_Byte range 7 .. 7; | |
19439 | Slave_Control at Slave_Byte range 0 .. 0; | |
19440 | Slave_V1 at Slave_Byte range 1 .. 1; | |
19441 | Slave_V2 at Slave_Byte range 2 .. 2; | |
19442 | Slave_V3 at Slave_Byte range 3 .. 3; | |
19443 | Slave_V4 at Slave_Byte range 4 .. 4; | |
19444 | Slave_V5 at Slave_Byte range 5 .. 5; | |
19445 | Slave_V6 at Slave_Byte range 6 .. 6; | |
19446 | Slave_V7 at Slave_Byte range 7 .. 7; | |
19447 | end record; | |
19448 | @end example | |
19449 | ||
19450 | Now to switch between machines, all that is necessary is | |
19451 | to set the boolean constant @code{Master_Byte_First} in | |
19452 | an appropriate manner. | |
19453 | ||
19454 | @node Pragma Pack for Arrays,Pragma Pack for Records,Effect of Bit_Order on Byte Ordering,Representation Clauses and Pragmas | |
73918baf | 19455 | @anchor{gnat_rm/representation_clauses_and_pragmas id11}@anchor{291}@anchor{gnat_rm/representation_clauses_and_pragmas pragma-pack-for-arrays}@anchor{292} |
64d5610f ML |
19456 | @section Pragma Pack for Arrays |
19457 | ||
19458 | ||
19459 | @geindex Pragma Pack (for arrays) | |
19460 | ||
19461 | Pragma @code{Pack} applied to an array has an effect that depends upon whether the | |
19462 | component type is `packable'. For a component type to be `packable', it must | |
19463 | be one of the following cases: | |
19464 | ||
19465 | ||
19466 | @itemize * | |
19467 | ||
19468 | @item | |
19469 | Any elementary type. | |
19470 | ||
19471 | @item | |
19472 | Any small packed array type with a static size. | |
19473 | ||
19474 | @item | |
19475 | Any small simple record type with a static size. | |
19476 | @end itemize | |
19477 | ||
19478 | For all these cases, if the component subtype size is in the range | |
19479 | 1 through 63 on 32-bit targets, and 1 through 127 on 64-bit targets, | |
19480 | then the effect of the pragma @code{Pack} is exactly as though a | |
19481 | component size were specified giving the component subtype size. | |
19482 | ||
19483 | All other types are non-packable, they occupy an integral number of storage | |
19484 | units and the only effect of pragma Pack is to remove alignment gaps. | |
19485 | ||
19486 | For example if we have: | |
19487 | ||
19488 | @example | |
19489 | type r is range 0 .. 17; | |
19490 | ||
19491 | type ar is array (1 .. 8) of r; | |
19492 | pragma Pack (ar); | |
19493 | @end example | |
19494 | ||
19495 | Then the component size of @code{ar} will be set to 5 (i.e., to @code{r'size}, | |
19496 | and the size of the array @code{ar} will be exactly 40 bits). | |
19497 | ||
19498 | Note that in some cases this rather fierce approach to packing can produce | |
19499 | unexpected effects. For example, in Ada 95 and Ada 2005, | |
19500 | subtype @code{Natural} typically has a size of 31, meaning that if you | |
19501 | pack an array of @code{Natural}, you get 31-bit | |
19502 | close packing, which saves a few bits, but results in far less efficient | |
19503 | access. Since many other Ada compilers will ignore such a packing request, | |
19504 | GNAT will generate a warning on some uses of pragma @code{Pack} that it guesses | |
19505 | might not be what is intended. You can easily remove this warning by | |
19506 | using an explicit @code{Component_Size} setting instead, which never generates | |
19507 | a warning, since the intention of the programmer is clear in this case. | |
19508 | ||
19509 | GNAT treats packed arrays in one of two ways. If the size of the array is | |
19510 | known at compile time and is at most 64 bits on 32-bit targets, and at most | |
19511 | 128 bits on 64-bit targets, then internally the array is represented as a | |
19512 | single modular type, of exactly the appropriate number of bits. If the | |
19513 | length is greater than 64 bits on 32-bit targets, and greater than 128 | |
19514 | bits on 64-bit targets, or is not known at compile time, then the packed | |
19515 | array is represented as an array of bytes, and its length is always a | |
19516 | multiple of 8 bits. | |
19517 | ||
19518 | Note that to represent a packed array as a modular type, the alignment must | |
19519 | be suitable for the modular type involved. For example, on typical machines | |
19520 | a 32-bit packed array will be represented by a 32-bit modular integer with | |
19521 | an alignment of four bytes. If you explicitly override the default alignment | |
19522 | with an alignment clause that is too small, the modular representation | |
19523 | cannot be used. For example, consider the following set of declarations: | |
19524 | ||
19525 | @example | |
19526 | type R is range 1 .. 3; | |
19527 | type S is array (1 .. 31) of R; | |
19528 | for S'Component_Size use 2; | |
19529 | for S'Size use 62; | |
19530 | for S'Alignment use 1; | |
19531 | @end example | |
19532 | ||
19533 | If the alignment clause were not present, then a 62-bit modular | |
19534 | representation would be chosen (typically with an alignment of 4 or 8 | |
19535 | bytes depending on the target). But the default alignment is overridden | |
19536 | with the explicit alignment clause. This means that the modular | |
19537 | representation cannot be used, and instead the array of bytes | |
19538 | representation must be used, meaning that the length must be a multiple | |
19539 | of 8. Thus the above set of declarations will result in a diagnostic | |
19540 | rejecting the size clause and noting that the minimum size allowed is 64. | |
19541 | ||
19542 | @geindex Pragma Pack (for type Natural) | |
19543 | ||
19544 | @geindex Pragma Pack warning | |
19545 | ||
19546 | One special case that is worth noting occurs when the base type of the | |
19547 | component size is 8/16/32 and the subtype is one bit less. Notably this | |
19548 | occurs with subtype @code{Natural}. Consider: | |
19549 | ||
19550 | @example | |
19551 | type Arr is array (1 .. 32) of Natural; | |
19552 | pragma Pack (Arr); | |
19553 | @end example | |
19554 | ||
19555 | In all commonly used Ada 83 compilers, this pragma Pack would be ignored, | |
19556 | since typically @code{Natural'Size} is 32 in Ada 83, and in any case most | |
19557 | Ada 83 compilers did not attempt 31 bit packing. | |
19558 | ||
19559 | In Ada 95 and Ada 2005, @code{Natural'Size} is required to be 31. Furthermore, | |
19560 | GNAT really does pack 31-bit subtype to 31 bits. This may result in a | |
19561 | substantial unintended performance penalty when porting legacy Ada 83 code. | |
19562 | To help prevent this, GNAT generates a warning in such cases. If you really | |
19563 | want 31 bit packing in a case like this, you can set the component size | |
19564 | explicitly: | |
19565 | ||
19566 | @example | |
19567 | type Arr is array (1 .. 32) of Natural; | |
19568 | for Arr'Component_Size use 31; | |
19569 | @end example | |
19570 | ||
19571 | Here 31-bit packing is achieved as required, and no warning is generated, | |
19572 | since in this case the programmer intention is clear. | |
19573 | ||
19574 | @node Pragma Pack for Records,Record Representation Clauses,Pragma Pack for Arrays,Representation Clauses and Pragmas | |
73918baf | 19575 | @anchor{gnat_rm/representation_clauses_and_pragmas id12}@anchor{293}@anchor{gnat_rm/representation_clauses_and_pragmas pragma-pack-for-records}@anchor{294} |
64d5610f ML |
19576 | @section Pragma Pack for Records |
19577 | ||
19578 | ||
19579 | @geindex Pragma Pack (for records) | |
19580 | ||
19581 | Pragma @code{Pack} applied to a record will pack the components to reduce | |
19582 | wasted space from alignment gaps and by reducing the amount of space | |
19583 | taken by components. We distinguish between `packable' components and | |
19584 | `non-packable' components. | |
19585 | Components of the following types are considered packable: | |
19586 | ||
19587 | ||
19588 | @itemize * | |
19589 | ||
19590 | @item | |
19591 | Components of an elementary type are packable unless they are aliased, | |
19592 | independent or atomic. | |
19593 | ||
19594 | @item | |
19595 | Small packed arrays, where the size is statically known, are represented | |
19596 | internally as modular integers, and so they are also packable. | |
19597 | ||
19598 | @item | |
19599 | Small simple records, where the size is statically known, are also packable. | |
19600 | @end itemize | |
19601 | ||
19602 | For all these cases, if the @code{'Size} value is in the range 1 through 64 on | |
19603 | 32-bit targets, and 1 through 128 on 64-bit targets, the components occupy | |
19604 | the exact number of bits corresponding to this value and are packed with no | |
19605 | padding bits, i.e. they can start on an arbitrary bit boundary. | |
19606 | ||
19607 | All other types are non-packable, they occupy an integral number of storage | |
19608 | units and the only effect of pragma @code{Pack} is to remove alignment gaps. | |
19609 | ||
19610 | For example, consider the record | |
19611 | ||
19612 | @example | |
19613 | type Rb1 is array (1 .. 13) of Boolean; | |
19614 | pragma Pack (Rb1); | |
19615 | ||
19616 | type Rb2 is array (1 .. 65) of Boolean; | |
19617 | pragma Pack (Rb2); | |
19618 | ||
19619 | type AF is new Float with Atomic; | |
19620 | ||
19621 | type X2 is record | |
19622 | L1 : Boolean; | |
19623 | L2 : Duration; | |
19624 | L3 : AF; | |
19625 | L4 : Boolean; | |
19626 | L5 : Rb1; | |
19627 | L6 : Rb2; | |
19628 | end record; | |
19629 | pragma Pack (X2); | |
19630 | @end example | |
19631 | ||
19632 | The representation for the record @code{X2} is as follows on 32-bit targets: | |
19633 | ||
19634 | @example | |
19635 | for X2'Size use 224; | |
19636 | for X2 use record | |
19637 | L1 at 0 range 0 .. 0; | |
19638 | L2 at 0 range 1 .. 64; | |
19639 | L3 at 12 range 0 .. 31; | |
19640 | L4 at 16 range 0 .. 0; | |
19641 | L5 at 16 range 1 .. 13; | |
19642 | L6 at 18 range 0 .. 71; | |
19643 | end record; | |
19644 | @end example | |
19645 | ||
19646 | Studying this example, we see that the packable fields @code{L1} | |
19647 | and @code{L2} are of length equal to their sizes, and placed at | |
19648 | specific bit boundaries (and not byte boundaries) to eliminate | |
19649 | padding. But @code{L3} is of a non-packable float type (because | |
19650 | it is aliased), so it is on the next appropriate alignment boundary. | |
19651 | ||
19652 | The next two fields are fully packable, so @code{L4} and @code{L5} are | |
19653 | minimally packed with no gaps. However, type @code{Rb2} is a packed | |
19654 | array that is longer than 64 bits, so it is itself non-packable on | |
19655 | 32-bit targets. Thus the @code{L6} field is aligned to the next byte | |
19656 | boundary, and takes an integral number of bytes, i.e., 72 bits. | |
19657 | ||
19658 | @node Record Representation Clauses,Handling of Records with Holes,Pragma Pack for Records,Representation Clauses and Pragmas | |
73918baf | 19659 | @anchor{gnat_rm/representation_clauses_and_pragmas id13}@anchor{295}@anchor{gnat_rm/representation_clauses_and_pragmas record-representation-clauses}@anchor{296} |
64d5610f ML |
19660 | @section Record Representation Clauses |
19661 | ||
19662 | ||
19663 | @geindex Record Representation Clause | |
19664 | ||
19665 | Record representation clauses may be given for all record types, including | |
19666 | types obtained by record extension. Component clauses are allowed for any | |
19667 | static component. The restrictions on component clauses depend on the type | |
19668 | of the component. | |
19669 | ||
19670 | @geindex Component Clause | |
19671 | ||
19672 | For all components of an elementary type, the only restriction on component | |
19673 | clauses is that the size must be at least the @code{'Size} value of the type | |
19674 | (actually the Value_Size). There are no restrictions due to alignment, | |
19675 | and such components may freely cross storage boundaries. | |
19676 | ||
19677 | Packed arrays with a size up to and including 64 bits on 32-bit targets, | |
19678 | and up to and including 128 bits on 64-bit targets, are represented | |
19679 | internally using a modular type with the appropriate number of bits, and | |
19680 | thus the same lack of restriction applies. For example, if you declare: | |
19681 | ||
19682 | @example | |
19683 | type R is array (1 .. 49) of Boolean; | |
19684 | pragma Pack (R); | |
19685 | for R'Size use 49; | |
19686 | @end example | |
19687 | ||
19688 | then a component clause for a component of type @code{R} may start on any | |
19689 | specified bit boundary, and may specify a value of 49 bits or greater. | |
19690 | ||
19691 | For packed bit arrays that are longer than 64 bits on 32-bit targets, | |
19692 | and longer than 128 bits on 64-bit targets, there are two cases. If the | |
19693 | component size is a power of 2 (1,2,4,8,16,32,64 bits), including the | |
19694 | important case of single bits or boolean values, then there are no | |
19695 | limitations on placement of such components, and they may start and | |
19696 | end at arbitrary bit boundaries. | |
19697 | ||
19698 | If the component size is not a power of 2 (e.g., 3 or 5), then an array | |
19699 | of this type must always be placed on on a storage unit (byte) boundary | |
19700 | and occupy an integral number of storage units (bytes). Any component | |
19701 | clause that does not meet this requirement will be rejected. | |
19702 | ||
19703 | Any aliased component, or component of an aliased type, must have its | |
19704 | normal alignment and size. A component clause that does not meet this | |
19705 | requirement will be rejected. | |
19706 | ||
19707 | The tag field of a tagged type always occupies an address sized field at | |
19708 | the start of the record. No component clause may attempt to overlay this | |
19709 | tag. When a tagged type appears as a component, the tag field must have | |
19710 | proper alignment | |
19711 | ||
19712 | In the case of a record extension @code{T1}, of a type @code{T}, no component | |
19713 | clause applied to the type @code{T1} can specify a storage location that | |
19714 | would overlap the first @code{T'Object_Size} bits of the record. | |
19715 | ||
19716 | For all other component types, including non-bit-packed arrays, | |
19717 | the component can be placed at an arbitrary bit boundary, | |
19718 | so for example, the following is permitted: | |
19719 | ||
19720 | @example | |
19721 | type R is array (1 .. 10) of Boolean; | |
19722 | for R'Size use 80; | |
19723 | ||
19724 | type Q is record | |
19725 | G, H : Boolean; | |
19726 | L, M : R; | |
19727 | end record; | |
19728 | ||
19729 | for Q use record | |
19730 | G at 0 range 0 .. 0; | |
19731 | H at 0 range 1 .. 1; | |
19732 | L at 0 range 2 .. 81; | |
19733 | R at 0 range 82 .. 161; | |
19734 | end record; | |
19735 | @end example | |
19736 | ||
19737 | @node Handling of Records with Holes,Enumeration Clauses,Record Representation Clauses,Representation Clauses and Pragmas | |
73918baf | 19738 | @anchor{gnat_rm/representation_clauses_and_pragmas handling-of-records-with-holes}@anchor{297}@anchor{gnat_rm/representation_clauses_and_pragmas id14}@anchor{298} |
64d5610f ML |
19739 | @section Handling of Records with Holes |
19740 | ||
19741 | ||
19742 | @geindex Handling of Records with Holes | |
19743 | ||
19744 | As a result of alignment considerations, records may contain “holes” | |
19745 | or gaps which do not correspond to the data bits of any of the components. | |
19746 | Record representation clauses can also result in holes in records. | |
19747 | ||
19748 | GNAT does not attempt to clear these holes, so in record objects, | |
19749 | they should be considered to hold undefined rubbish. The generated | |
19750 | equality routine just tests components so does not access these | |
19751 | undefined bits, and assignment and copy operations may or may not | |
19752 | preserve the contents of these holes (for assignments, the holes | |
19753 | in the target will in practice contain either the bits that are | |
19754 | present in the holes in the source, or the bits that were present | |
19755 | in the target before the assignment). | |
19756 | ||
19757 | If it is necessary to ensure that holes in records have all zero | |
19758 | bits, then record objects for which this initialization is desired | |
19759 | should be explicitly set to all zero values using Unchecked_Conversion | |
19760 | or address overlays. For example | |
19761 | ||
19762 | @example | |
19763 | type HRec is record | |
19764 | C : Character; | |
19765 | I : Integer; | |
19766 | end record; | |
19767 | @end example | |
19768 | ||
19769 | On typical machines, integers need to be aligned on a four-byte | |
19770 | boundary, resulting in three bytes of undefined rubbish following | |
19771 | the 8-bit field for C. To ensure that the hole in a variable of | |
19772 | type HRec is set to all zero bits, | |
19773 | you could for example do: | |
19774 | ||
19775 | @example | |
19776 | type Base is record | |
19777 | Dummy1, Dummy2 : Integer := 0; | |
19778 | end record; | |
19779 | ||
19780 | BaseVar : Base; | |
19781 | RealVar : Hrec; | |
19782 | for RealVar'Address use BaseVar'Address; | |
19783 | @end example | |
19784 | ||
19785 | Now the 8-bytes of the value of RealVar start out containing all zero | |
19786 | bits. A safer approach is to just define dummy fields, avoiding the | |
19787 | holes, as in: | |
19788 | ||
19789 | @example | |
19790 | type HRec is record | |
19791 | C : Character; | |
19792 | Dummy1 : Short_Short_Integer := 0; | |
19793 | Dummy2 : Short_Short_Integer := 0; | |
19794 | Dummy3 : Short_Short_Integer := 0; | |
19795 | I : Integer; | |
19796 | end record; | |
19797 | @end example | |
19798 | ||
19799 | And to make absolutely sure that the intent of this is followed, you | |
19800 | can use representation clauses: | |
19801 | ||
19802 | @example | |
19803 | for Hrec use record | |
19804 | C at 0 range 0 .. 7; | |
19805 | Dummy1 at 1 range 0 .. 7; | |
19806 | Dummy2 at 2 range 0 .. 7; | |
19807 | Dummy3 at 3 range 0 .. 7; | |
19808 | I at 4 range 0 .. 31; | |
19809 | end record; | |
19810 | for Hrec'Size use 64; | |
19811 | @end example | |
19812 | ||
19813 | @node Enumeration Clauses,Address Clauses,Handling of Records with Holes,Representation Clauses and Pragmas | |
73918baf | 19814 | @anchor{gnat_rm/representation_clauses_and_pragmas enumeration-clauses}@anchor{299}@anchor{gnat_rm/representation_clauses_and_pragmas id15}@anchor{29a} |
64d5610f ML |
19815 | @section Enumeration Clauses |
19816 | ||
19817 | ||
19818 | The only restriction on enumeration clauses is that the range of values | |
19819 | must be representable. For the signed case, if one or more of the | |
19820 | representation values are negative, all values must be in the range: | |
19821 | ||
19822 | @example | |
19823 | System.Min_Int .. System.Max_Int | |
19824 | @end example | |
19825 | ||
19826 | For the unsigned case, where all values are nonnegative, the values must | |
19827 | be in the range: | |
19828 | ||
19829 | @example | |
19830 | 0 .. System.Max_Binary_Modulus; | |
19831 | @end example | |
19832 | ||
19833 | A `confirming' representation clause is one in which the values range | |
19834 | from 0 in sequence, i.e., a clause that confirms the default representation | |
19835 | for an enumeration type. | |
19836 | Such a confirming representation | |
19837 | is permitted by these rules, and is specially recognized by the compiler so | |
19838 | that no extra overhead results from the use of such a clause. | |
19839 | ||
19840 | If an array has an index type which is an enumeration type to which an | |
19841 | enumeration clause has been applied, then the array is stored in a compact | |
19842 | manner. Consider the declarations: | |
19843 | ||
19844 | @example | |
19845 | type r is (A, B, C); | |
19846 | for r use (A => 1, B => 5, C => 10); | |
19847 | type t is array (r) of Character; | |
19848 | @end example | |
19849 | ||
19850 | The array type t corresponds to a vector with exactly three elements and | |
19851 | has a default size equal to @code{3*Character'Size}. This ensures efficient | |
19852 | use of space, but means that accesses to elements of the array will incur | |
19853 | the overhead of converting representation values to the corresponding | |
19854 | positional values, (i.e., the value delivered by the @code{Pos} attribute). | |
19855 | ||
19856 | @node Address Clauses,Use of Address Clauses for Memory-Mapped I/O,Enumeration Clauses,Representation Clauses and Pragmas | |
73918baf | 19857 | @anchor{gnat_rm/representation_clauses_and_pragmas address-clauses}@anchor{29b}@anchor{gnat_rm/representation_clauses_and_pragmas id16}@anchor{29c} |
64d5610f ML |
19858 | @section Address Clauses |
19859 | ||
19860 | ||
19861 | @geindex Address Clause | |
19862 | ||
19863 | The reference manual allows a general restriction on representation clauses, | |
19864 | as found in RM 13.1(22): | |
19865 | ||
19866 | @quotation | |
19867 | ||
19868 | “An implementation need not support representation | |
19869 | items containing nonstatic expressions, except that | |
19870 | an implementation should support a representation item | |
19871 | for a given entity if each nonstatic expression in the | |
19872 | representation item is a name that statically denotes | |
19873 | a constant declared before the entity.” | |
19874 | @end quotation | |
19875 | ||
19876 | In practice this is applicable only to address clauses, since this is the | |
19877 | only case in which a nonstatic expression is permitted by the syntax. As | |
19878 | the AARM notes in sections 13.1 (22.a-22.h): | |
19879 | ||
19880 | @quotation | |
19881 | ||
19882 | 22.a Reason: This is to avoid the following sort of thing: | |
19883 | ||
19884 | 22.b X : Integer := F(…); | |
19885 | Y : Address := G(…); | |
19886 | for X’Address use Y; | |
19887 | ||
19888 | 22.c In the above, we have to evaluate the | |
19889 | initialization expression for X before we | |
19890 | know where to put the result. This seems | |
19891 | like an unreasonable implementation burden. | |
19892 | ||
19893 | 22.d The above code should instead be written | |
19894 | like this: | |
19895 | ||
19896 | 22.e Y : constant Address := G(…); | |
19897 | X : Integer := F(…); | |
19898 | for X’Address use Y; | |
19899 | ||
19900 | 22.f This allows the expression ‘Y’ to be safely | |
19901 | evaluated before X is created. | |
19902 | ||
19903 | 22.g The constant could be a formal parameter of mode in. | |
19904 | ||
19905 | 22.h An implementation can support other nonstatic | |
19906 | expressions if it wants to. Expressions of type | |
19907 | Address are hardly ever static, but their value | |
19908 | might be known at compile time anyway in many | |
19909 | cases. | |
19910 | @end quotation | |
19911 | ||
19912 | GNAT does indeed permit many additional cases of nonstatic expressions. In | |
19913 | particular, if the type involved is elementary there are no restrictions | |
19914 | (since in this case, holding a temporary copy of the initialization value, | |
19915 | if one is present, is inexpensive). In addition, if there is no implicit or | |
19916 | explicit initialization, then there are no restrictions. GNAT will reject | |
19917 | only the case where all three of these conditions hold: | |
19918 | ||
19919 | ||
19920 | @itemize * | |
19921 | ||
19922 | @item | |
19923 | The type of the item is non-elementary (e.g., a record or array). | |
19924 | ||
19925 | @item | |
19926 | There is explicit or implicit initialization required for the object. | |
19927 | Note that access values are always implicitly initialized. | |
19928 | ||
19929 | @item | |
19930 | The address value is nonstatic. Here GNAT is more permissive than the | |
19931 | RM, and allows the address value to be the address of a previously declared | |
19932 | stand-alone variable, as long as it does not itself have an address clause. | |
19933 | ||
19934 | @example | |
19935 | Anchor : Some_Initialized_Type; | |
19936 | Overlay : Some_Initialized_Type; | |
19937 | for Overlay'Address use Anchor'Address; | |
19938 | @end example | |
19939 | ||
19940 | However, the prefix of the address clause cannot be an array component, or | |
19941 | a component of a discriminated record. | |
19942 | @end itemize | |
19943 | ||
19944 | As noted above in section 22.h, address values are typically nonstatic. In | |
19945 | particular the To_Address function, even if applied to a literal value, is | |
19946 | a nonstatic function call. To avoid this minor annoyance, GNAT provides | |
19947 | the implementation defined attribute ‘To_Address. The following two | |
19948 | expressions have identical values: | |
19949 | ||
19950 | @geindex Attribute | |
19951 | ||
19952 | @geindex To_Address | |
19953 | ||
19954 | @example | |
19955 | To_Address (16#1234_0000#) | |
19956 | System'To_Address (16#1234_0000#); | |
19957 | @end example | |
19958 | ||
19959 | except that the second form is considered to be a static expression, and | |
19960 | thus when used as an address clause value is always permitted. | |
19961 | ||
19962 | Additionally, GNAT treats as static an address clause that is an | |
19963 | unchecked_conversion of a static integer value. This simplifies the porting | |
19964 | of legacy code, and provides a portable equivalent to the GNAT attribute | |
19965 | @code{To_Address}. | |
19966 | ||
19967 | Another issue with address clauses is the interaction with alignment | |
19968 | requirements. When an address clause is given for an object, the address | |
19969 | value must be consistent with the alignment of the object (which is usually | |
19970 | the same as the alignment of the type of the object). If an address clause | |
19971 | is given that specifies an inappropriately aligned address value, then the | |
19972 | program execution is erroneous. | |
19973 | ||
19974 | Since this source of erroneous behavior can have unfortunate effects on | |
19975 | machines with strict alignment requirements, GNAT | |
19976 | checks (at compile time if possible, generating a warning, or at execution | |
19977 | time with a run-time check) that the alignment is appropriate. If the | |
19978 | run-time check fails, then @code{Program_Error} is raised. This run-time | |
19979 | check is suppressed if range checks are suppressed, or if the special GNAT | |
19980 | check Alignment_Check is suppressed, or if | |
19981 | @code{pragma Restrictions (No_Elaboration_Code)} is in effect. It is also | |
19982 | suppressed by default on non-strict alignment machines (such as the x86). | |
19983 | ||
19984 | In some cases, GNAT does not support an address specification (using either | |
19985 | form of aspect specification syntax) for the declaration of an object that has | |
19986 | an indefinite nominal subtype. An object declaration has an indefinite | |
19987 | nominal subtype if it takes its bounds (for an array type), discriminant | |
19988 | values (for a discriminated type whose discriminants lack defaults), or tag | |
19989 | (for a class-wide type) from its initial value, as in | |
19990 | ||
19991 | @example | |
19992 | X : String := Some_Function_Call; | |
19993 | -- String has no constraint, so bounds for X come from function call | |
19994 | @end example | |
19995 | ||
19996 | This restriction does not apply if the size of the object’s initial value is | |
19997 | known at compile time and the type of the object is not class-wide. | |
19998 | ||
19999 | @geindex Export | |
20000 | ||
20001 | An address clause cannot be given for an exported object. More | |
20002 | understandably the real restriction is that objects with an address | |
20003 | clause cannot be exported. This is because such variables are not | |
20004 | defined by the Ada program, so there is no external object to export. | |
20005 | ||
20006 | @geindex Import | |
20007 | ||
20008 | It is permissible to give an address clause and a pragma Import for the | |
20009 | same object. In this case, the variable is not really defined by the | |
20010 | Ada program, so there is no external symbol to be linked. The link name | |
20011 | and the external name are ignored in this case. The reason that we allow this | |
20012 | combination is that it provides a useful idiom to avoid unwanted | |
20013 | initializations on objects with address clauses. | |
20014 | ||
20015 | When an address clause is given for an object that has implicit or | |
20016 | explicit initialization, then by default initialization takes place. This | |
20017 | means that the effect of the object declaration is to overwrite the | |
20018 | memory at the specified address. This is almost always not what the | |
20019 | programmer wants, so GNAT will output a warning: | |
20020 | ||
20021 | @example | |
20022 | with System; | |
20023 | package G is | |
20024 | type R is record | |
20025 | M : Integer := 0; | |
20026 | end record; | |
20027 | ||
20028 | Ext : R; | |
20029 | for Ext'Address use System'To_Address (16#1234_1234#); | |
20030 | | | |
20031 | >>> warning: implicit initialization of "Ext" may | |
20032 | modify overlaid storage | |
20033 | >>> warning: use pragma Import for "Ext" to suppress | |
20034 | initialization (RM B(24)) | |
20035 | ||
20036 | end G; | |
20037 | @end example | |
20038 | ||
20039 | As indicated by the warning message, the solution is to use a (dummy) pragma | |
20040 | Import to suppress this initialization. The pragma tell the compiler that the | |
20041 | object is declared and initialized elsewhere. The following package compiles | |
20042 | without warnings (and the initialization is suppressed): | |
20043 | ||
20044 | @example | |
20045 | with System; | |
20046 | package G is | |
20047 | type R is record | |
20048 | M : Integer := 0; | |
20049 | end record; | |
20050 | ||
20051 | Ext : R; | |
20052 | for Ext'Address use System'To_Address (16#1234_1234#); | |
20053 | pragma Import (Ada, Ext); | |
20054 | end G; | |
20055 | @end example | |
20056 | ||
20057 | A final issue with address clauses involves their use for overlaying | |
20058 | variables, as in the following example: | |
20059 | ||
20060 | @geindex Overlaying of objects | |
20061 | ||
20062 | @example | |
20063 | A : Integer; | |
20064 | B : Integer; | |
20065 | for B'Address use A'Address; | |
20066 | @end example | |
20067 | ||
20068 | or alternatively, using the form recommended by the RM: | |
20069 | ||
20070 | @example | |
20071 | A : Integer; | |
20072 | Addr : constant Address := A'Address; | |
20073 | B : Integer; | |
20074 | for B'Address use Addr; | |
20075 | @end example | |
20076 | ||
20077 | In both of these cases, @code{A} and @code{B} become aliased to one another | |
20078 | via the address clause. This use of address clauses to overlay | |
20079 | variables, achieving an effect similar to unchecked conversion | |
20080 | was erroneous in Ada 83, but in Ada 95 and Ada 2005 | |
20081 | the effect is implementation defined. Furthermore, the | |
20082 | Ada RM specifically recommends that in a situation | |
20083 | like this, @code{B} should be subject to the following | |
20084 | implementation advice (RM 13.3(19)): | |
20085 | ||
20086 | @quotation | |
20087 | ||
20088 | “19 If the Address of an object is specified, or it is imported | |
20089 | or exported, then the implementation should not perform | |
20090 | optimizations based on assumptions of no aliases.” | |
20091 | @end quotation | |
20092 | ||
20093 | GNAT follows this recommendation, and goes further by also applying | |
20094 | this recommendation to the overlaid variable (@code{A} in the above example) | |
20095 | in this case. This means that the overlay works “as expected”, in that | |
20096 | a modification to one of the variables will affect the value of the other. | |
20097 | ||
20098 | More generally, GNAT interprets this recommendation conservatively for | |
20099 | address clauses: in the cases other than overlays, it considers that the | |
20100 | object is effectively subject to pragma @code{Volatile} and implements the | |
20101 | associated semantics. | |
20102 | ||
20103 | Note that when address clause overlays are used in this way, there is an | |
20104 | issue of unintentional initialization, as shown by this example: | |
20105 | ||
20106 | @example | |
20107 | package Overwrite_Record is | |
20108 | type R is record | |
20109 | A : Character := 'C'; | |
20110 | B : Character := 'A'; | |
20111 | end record; | |
20112 | X : Short_Integer := 3; | |
20113 | Y : R; | |
20114 | for Y'Address use X'Address; | |
20115 | | | |
20116 | >>> warning: default initialization of "Y" may | |
20117 | modify "X", use pragma Import for "Y" to | |
20118 | suppress initialization (RM B.1(24)) | |
20119 | ||
20120 | end Overwrite_Record; | |
20121 | @end example | |
20122 | ||
20123 | Here the default initialization of @code{Y} will clobber the value | |
20124 | of @code{X}, which justifies the warning. The warning notes that | |
20125 | this effect can be eliminated by adding a @code{pragma Import} | |
20126 | which suppresses the initialization: | |
20127 | ||
20128 | @example | |
20129 | package Overwrite_Record is | |
20130 | type R is record | |
20131 | A : Character := 'C'; | |
20132 | B : Character := 'A'; | |
20133 | end record; | |
20134 | X : Short_Integer := 3; | |
20135 | Y : R; | |
20136 | for Y'Address use X'Address; | |
20137 | pragma Import (Ada, Y); | |
20138 | end Overwrite_Record; | |
20139 | @end example | |
20140 | ||
20141 | Note that the use of @code{pragma Initialize_Scalars} may cause variables to | |
20142 | be initialized when they would not otherwise have been in the absence | |
20143 | of the use of this pragma. This may cause an overlay to have this | |
20144 | unintended clobbering effect. The compiler avoids this for scalar | |
20145 | types, but not for composite objects (where in general the effect | |
20146 | of @code{Initialize_Scalars} is part of the initialization routine | |
20147 | for the composite object): | |
20148 | ||
20149 | @example | |
20150 | pragma Initialize_Scalars; | |
20151 | with Ada.Text_IO; use Ada.Text_IO; | |
20152 | procedure Overwrite_Array is | |
20153 | type Arr is array (1 .. 5) of Integer; | |
20154 | X : Arr := (others => 1); | |
20155 | A : Arr; | |
20156 | for A'Address use X'Address; | |
20157 | | | |
20158 | >>> warning: default initialization of "A" may | |
20159 | modify "X", use pragma Import for "A" to | |
20160 | suppress initialization (RM B.1(24)) | |
20161 | ||
20162 | begin | |
20163 | if X /= Arr'(others => 1) then | |
20164 | Put_Line ("X was clobbered"); | |
20165 | else | |
20166 | Put_Line ("X was not clobbered"); | |
20167 | end if; | |
20168 | end Overwrite_Array; | |
20169 | @end example | |
20170 | ||
20171 | The above program generates the warning as shown, and at execution | |
20172 | time, prints @code{X was clobbered}. If the @code{pragma Import} is | |
20173 | added as suggested: | |
20174 | ||
20175 | @example | |
20176 | pragma Initialize_Scalars; | |
20177 | with Ada.Text_IO; use Ada.Text_IO; | |
20178 | procedure Overwrite_Array is | |
20179 | type Arr is array (1 .. 5) of Integer; | |
20180 | X : Arr := (others => 1); | |
20181 | A : Arr; | |
20182 | for A'Address use X'Address; | |
20183 | pragma Import (Ada, A); | |
20184 | begin | |
20185 | if X /= Arr'(others => 1) then | |
20186 | Put_Line ("X was clobbered"); | |
20187 | else | |
20188 | Put_Line ("X was not clobbered"); | |
20189 | end if; | |
20190 | end Overwrite_Array; | |
20191 | @end example | |
20192 | ||
20193 | then the program compiles without the warning and when run will generate | |
20194 | the output @code{X was not clobbered}. | |
20195 | ||
20196 | @node Use of Address Clauses for Memory-Mapped I/O,Effect of Convention on Representation,Address Clauses,Representation Clauses and Pragmas | |
73918baf | 20197 | @anchor{gnat_rm/representation_clauses_and_pragmas id17}@anchor{29d}@anchor{gnat_rm/representation_clauses_and_pragmas use-of-address-clauses-for-memory-mapped-i-o}@anchor{29e} |
64d5610f ML |
20198 | @section Use of Address Clauses for Memory-Mapped I/O |
20199 | ||
20200 | ||
20201 | @geindex Memory-mapped I/O | |
20202 | ||
20203 | A common pattern is to use an address clause to map an atomic variable to | |
20204 | a location in memory that corresponds to a memory-mapped I/O operation or | |
20205 | operations, for example: | |
20206 | ||
20207 | @example | |
20208 | type Mem_Word is record | |
20209 | A,B,C,D : Byte; | |
20210 | end record; | |
20211 | pragma Atomic (Mem_Word); | |
20212 | for Mem_Word_Size use 32; | |
20213 | ||
20214 | Mem : Mem_Word; | |
20215 | for Mem'Address use some-address; | |
20216 | ... | |
20217 | Temp := Mem; | |
20218 | Temp.A := 32; | |
20219 | Mem := Temp; | |
20220 | @end example | |
20221 | ||
20222 | For a full access (reference or modification) of the variable (Mem) in this | |
20223 | case, as in the above examples, GNAT guarantees that the entire atomic word | |
20224 | will be accessed, in accordance with the RM C.6(15) clause. | |
20225 | ||
20226 | A problem arises with a component access such as: | |
20227 | ||
20228 | @example | |
20229 | Mem.A := 32; | |
20230 | @end example | |
20231 | ||
20232 | Note that the component A is not declared as atomic. This means that it is | |
20233 | not clear what this assignment means. It could correspond to full word read | |
20234 | and write as given in the first example, or on architectures that supported | |
20235 | such an operation it might be a single byte store instruction. The RM does | |
20236 | not have anything to say in this situation, and GNAT does not make any | |
20237 | guarantee. The code generated may vary from target to target. GNAT will issue | |
20238 | a warning in such a case: | |
20239 | ||
20240 | @example | |
20241 | Mem.A := 32; | |
20242 | | | |
20243 | >>> warning: access to non-atomic component of atomic array, | |
20244 | may cause unexpected accesses to atomic object | |
20245 | @end example | |
20246 | ||
20247 | It is best to be explicit in this situation, by either declaring the | |
20248 | components to be atomic if you want the byte store, or explicitly writing | |
20249 | the full word access sequence if that is what the hardware requires. | |
20250 | Alternatively, if the full word access sequence is required, GNAT also | |
20251 | provides the pragma @code{Volatile_Full_Access} which can be used in lieu of | |
20252 | pragma @code{Atomic} and will give the additional guarantee. | |
20253 | ||
20254 | @node Effect of Convention on Representation,Conventions and Anonymous Access Types,Use of Address Clauses for Memory-Mapped I/O,Representation Clauses and Pragmas | |
73918baf | 20255 | @anchor{gnat_rm/representation_clauses_and_pragmas effect-of-convention-on-representation}@anchor{29f}@anchor{gnat_rm/representation_clauses_and_pragmas id18}@anchor{2a0} |
64d5610f ML |
20256 | @section Effect of Convention on Representation |
20257 | ||
20258 | ||
20259 | @geindex Convention | |
20260 | @geindex effect on representation | |
20261 | ||
20262 | Normally the specification of a foreign language convention for a type or | |
20263 | an object has no effect on the chosen representation. In particular, the | |
20264 | representation chosen for data in GNAT generally meets the standard system | |
20265 | conventions, and for example records are laid out in a manner that is | |
20266 | consistent with C. This means that specifying convention C (for example) | |
20267 | has no effect. | |
20268 | ||
20269 | There are four exceptions to this general rule: | |
20270 | ||
20271 | ||
20272 | @itemize * | |
20273 | ||
20274 | @item | |
20275 | `Convention Fortran and array subtypes'. | |
20276 | ||
20277 | If pragma Convention Fortran is specified for an array subtype, then in | |
20278 | accordance with the implementation advice in section 3.6.2(11) of the | |
20279 | Ada Reference Manual, the array will be stored in a Fortran-compatible | |
20280 | column-major manner, instead of the normal default row-major order. | |
20281 | ||
20282 | @item | |
20283 | `Convention C and enumeration types' | |
20284 | ||
20285 | GNAT normally stores enumeration types in 8, 16, or 32 bits as required | |
20286 | to accommodate all values of the type. For example, for the enumeration | |
20287 | type declared by: | |
20288 | ||
20289 | @example | |
20290 | type Color is (Red, Green, Blue); | |
20291 | @end example | |
20292 | ||
20293 | 8 bits is sufficient to store all values of the type, so by default, objects | |
20294 | of type @code{Color} will be represented using 8 bits. However, normal C | |
20295 | convention is to use 32 bits for all enum values in C, since enum values | |
20296 | are essentially of type int. If pragma @code{Convention C} is specified for an | |
20297 | Ada enumeration type, then the size is modified as necessary (usually to | |
20298 | 32 bits) to be consistent with the C convention for enum values. | |
20299 | ||
20300 | Note that this treatment applies only to types. If Convention C is given for | |
20301 | an enumeration object, where the enumeration type is not Convention C, then | |
20302 | Object_Size bits are allocated. For example, for a normal enumeration type, | |
20303 | with less than 256 elements, only 8 bits will be allocated for the object. | |
20304 | Since this may be a surprise in terms of what C expects, GNAT will issue a | |
20305 | warning in this situation. The warning can be suppressed by giving an explicit | |
20306 | size clause specifying the desired size. | |
20307 | ||
20308 | @item | |
20309 | `Convention C/Fortran and Boolean types' | |
20310 | ||
20311 | In C, the usual convention for boolean values, that is values used for | |
20312 | conditions, is that zero represents false, and nonzero values represent | |
20313 | true. In Ada, the normal convention is that two specific values, typically | |
20314 | 0/1, are used to represent false/true respectively. | |
20315 | ||
20316 | Fortran has a similar convention for @code{LOGICAL} values (any nonzero | |
20317 | value represents true). | |
20318 | ||
20319 | To accommodate the Fortran and C conventions, if a pragma Convention specifies | |
20320 | C or Fortran convention for a derived Boolean, as in the following example: | |
20321 | ||
20322 | @example | |
20323 | type C_Switch is new Boolean; | |
20324 | pragma Convention (C, C_Switch); | |
20325 | @end example | |
20326 | ||
20327 | then the GNAT generated code will treat any nonzero value as true. For truth | |
20328 | values generated by GNAT, the conventional value 1 will be used for True, but | |
20329 | when one of these values is read, any nonzero value is treated as True. | |
20330 | @end itemize | |
20331 | ||
20332 | @node Conventions and Anonymous Access Types,Determining the Representations chosen by GNAT,Effect of Convention on Representation,Representation Clauses and Pragmas | |
73918baf | 20333 | @anchor{gnat_rm/representation_clauses_and_pragmas conventions-and-anonymous-access-types}@anchor{2a1}@anchor{gnat_rm/representation_clauses_and_pragmas id19}@anchor{2a2} |
64d5610f ML |
20334 | @section Conventions and Anonymous Access Types |
20335 | ||
20336 | ||
20337 | @geindex Anonymous access types | |
20338 | ||
20339 | @geindex Convention for anonymous access types | |
20340 | ||
20341 | The RM is not entirely clear on convention handling in a number of cases, | |
20342 | and in particular, it is not clear on the convention to be given to | |
20343 | anonymous access types in general, and in particular what is to be | |
20344 | done for the case of anonymous access-to-subprogram. | |
20345 | ||
20346 | In GNAT, we decide that if an explicit Convention is applied | |
20347 | to an object or component, and its type is such an anonymous type, | |
20348 | then the convention will apply to this anonymous type as well. This | |
20349 | seems to make sense since it is anomolous in any case to have a | |
20350 | different convention for an object and its type, and there is clearly | |
20351 | no way to explicitly specify a convention for an anonymous type, since | |
20352 | it doesn’t have a name to specify! | |
20353 | ||
20354 | Furthermore, we decide that if a convention is applied to a record type, | |
20355 | then this convention is inherited by any of its components that are of an | |
20356 | anonymous access type which do not have an explicitly specified convention. | |
20357 | ||
20358 | The following program shows these conventions in action: | |
20359 | ||
20360 | @example | |
20361 | package ConvComp is | |
20362 | type Foo is range 1 .. 10; | |
20363 | type T1 is record | |
20364 | A : access function (X : Foo) return Integer; | |
20365 | B : Integer; | |
20366 | end record; | |
20367 | pragma Convention (C, T1); | |
20368 | ||
20369 | type T2 is record | |
20370 | A : access function (X : Foo) return Integer; | |
20371 | pragma Convention (C, A); | |
20372 | B : Integer; | |
20373 | end record; | |
20374 | pragma Convention (COBOL, T2); | |
20375 | ||
20376 | type T3 is record | |
20377 | A : access function (X : Foo) return Integer; | |
20378 | pragma Convention (COBOL, A); | |
20379 | B : Integer; | |
20380 | end record; | |
20381 | pragma Convention (C, T3); | |
20382 | ||
20383 | type T4 is record | |
20384 | A : access function (X : Foo) return Integer; | |
20385 | B : Integer; | |
20386 | end record; | |
20387 | pragma Convention (COBOL, T4); | |
20388 | ||
20389 | function F (X : Foo) return Integer; | |
20390 | pragma Convention (C, F); | |
20391 | ||
20392 | function F (X : Foo) return Integer is (13); | |
20393 | ||
20394 | TV1 : T1 := (F'Access, 12); -- OK | |
20395 | TV2 : T2 := (F'Access, 13); -- OK | |
20396 | ||
20397 | TV3 : T3 := (F'Access, 13); -- ERROR | |
20398 | | | |
20399 | >>> subprogram "F" has wrong convention | |
20400 | >>> does not match access to subprogram declared at line 17 | |
20401 | 38. TV4 : T4 := (F'Access, 13); -- ERROR | |
20402 | | | |
20403 | >>> subprogram "F" has wrong convention | |
20404 | >>> does not match access to subprogram declared at line 24 | |
20405 | 39. end ConvComp; | |
20406 | @end example | |
20407 | ||
20408 | @node Determining the Representations chosen by GNAT,,Conventions and Anonymous Access Types,Representation Clauses and Pragmas | |
73918baf | 20409 | @anchor{gnat_rm/representation_clauses_and_pragmas determining-the-representations-chosen-by-gnat}@anchor{2a3}@anchor{gnat_rm/representation_clauses_and_pragmas id20}@anchor{2a4} |
64d5610f ML |
20410 | @section Determining the Representations chosen by GNAT |
20411 | ||
20412 | ||
20413 | @geindex Representation | |
20414 | @geindex determination of | |
20415 | ||
20416 | @geindex -gnatR (gcc) | |
20417 | ||
20418 | Although the descriptions in this section are intended to be complete, it is | |
20419 | often easier to simply experiment to see what GNAT accepts and what the | |
20420 | effect is on the layout of types and objects. | |
20421 | ||
20422 | As required by the Ada RM, if a representation clause is not accepted, then | |
20423 | it must be rejected as illegal by the compiler. However, when a | |
20424 | representation clause or pragma is accepted, there can still be questions | |
20425 | of what the compiler actually does. For example, if a partial record | |
20426 | representation clause specifies the location of some components and not | |
20427 | others, then where are the non-specified components placed? Or if pragma | |
20428 | @code{Pack} is used on a record, then exactly where are the resulting | |
20429 | fields placed? The section on pragma @code{Pack} in this chapter can be | |
20430 | used to answer the second question, but it is often easier to just see | |
20431 | what the compiler does. | |
20432 | ||
20433 | For this purpose, GNAT provides the option `-gnatR'. If you compile | |
20434 | with this option, then the compiler will output information on the actual | |
20435 | representations chosen, in a format similar to source representation | |
20436 | clauses. For example, if we compile the package: | |
20437 | ||
20438 | @example | |
20439 | package q is | |
20440 | type r (x : boolean) is tagged record | |
20441 | case x is | |
20442 | when True => S : String (1 .. 100); | |
20443 | when False => null; | |
20444 | end case; | |
20445 | end record; | |
20446 | ||
20447 | type r2 is new r (false) with record | |
20448 | y2 : integer; | |
20449 | end record; | |
20450 | ||
20451 | for r2 use record | |
20452 | y2 at 16 range 0 .. 31; | |
20453 | end record; | |
20454 | ||
20455 | type x is record | |
20456 | y : character; | |
20457 | end record; | |
20458 | ||
20459 | type x1 is array (1 .. 10) of x; | |
20460 | for x1'component_size use 11; | |
20461 | ||
20462 | type ia is access integer; | |
20463 | ||
20464 | type Rb1 is array (1 .. 13) of Boolean; | |
20465 | pragma Pack (rb1); | |
20466 | ||
20467 | type Rb2 is array (1 .. 65) of Boolean; | |
20468 | pragma Pack (rb2); | |
20469 | ||
20470 | type x2 is record | |
20471 | l1 : Boolean; | |
20472 | l2 : Duration; | |
20473 | l3 : Float; | |
20474 | l4 : Boolean; | |
20475 | l5 : Rb1; | |
20476 | l6 : Rb2; | |
20477 | end record; | |
20478 | pragma Pack (x2); | |
20479 | end q; | |
20480 | @end example | |
20481 | ||
20482 | using the switch `-gnatR' we obtain the following output: | |
20483 | ||
20484 | @example | |
20485 | Representation information for unit q | |
20486 | ------------------------------------- | |
20487 | ||
20488 | for r'Size use ??; | |
20489 | for r'Alignment use 4; | |
20490 | for r use record | |
20491 | x at 4 range 0 .. 7; | |
20492 | _tag at 0 range 0 .. 31; | |
20493 | s at 5 range 0 .. 799; | |
20494 | end record; | |
20495 | ||
20496 | for r2'Size use 160; | |
20497 | for r2'Alignment use 4; | |
20498 | for r2 use record | |
20499 | x at 4 range 0 .. 7; | |
20500 | _tag at 0 range 0 .. 31; | |
20501 | _parent at 0 range 0 .. 63; | |
20502 | y2 at 16 range 0 .. 31; | |
20503 | end record; | |
20504 | ||
20505 | for x'Size use 8; | |
20506 | for x'Alignment use 1; | |
20507 | for x use record | |
20508 | y at 0 range 0 .. 7; | |
20509 | end record; | |
20510 | ||
20511 | for x1'Size use 112; | |
20512 | for x1'Alignment use 1; | |
20513 | for x1'Component_Size use 11; | |
20514 | ||
20515 | for rb1'Size use 13; | |
20516 | for rb1'Alignment use 2; | |
20517 | for rb1'Component_Size use 1; | |
20518 | ||
20519 | for rb2'Size use 72; | |
20520 | for rb2'Alignment use 1; | |
20521 | for rb2'Component_Size use 1; | |
20522 | ||
20523 | for x2'Size use 224; | |
20524 | for x2'Alignment use 4; | |
20525 | for x2 use record | |
20526 | l1 at 0 range 0 .. 0; | |
20527 | l2 at 0 range 1 .. 64; | |
20528 | l3 at 12 range 0 .. 31; | |
20529 | l4 at 16 range 0 .. 0; | |
20530 | l5 at 16 range 1 .. 13; | |
20531 | l6 at 18 range 0 .. 71; | |
20532 | end record; | |
20533 | @end example | |
20534 | ||
20535 | The Size values are actually the Object_Size, i.e., the default size that | |
20536 | will be allocated for objects of the type. | |
20537 | The @code{??} size for type r indicates that we have a variant record, and the | |
20538 | actual size of objects will depend on the discriminant value. | |
20539 | ||
20540 | The Alignment values show the actual alignment chosen by the compiler | |
20541 | for each record or array type. | |
20542 | ||
20543 | The record representation clause for type r shows where all fields | |
20544 | are placed, including the compiler generated tag field (whose location | |
20545 | cannot be controlled by the programmer). | |
20546 | ||
20547 | The record representation clause for the type extension r2 shows all the | |
20548 | fields present, including the parent field, which is a copy of the fields | |
20549 | of the parent type of r2, i.e., r1. | |
20550 | ||
20551 | The component size and size clauses for types rb1 and rb2 show | |
20552 | the exact effect of pragma @code{Pack} on these arrays, and the record | |
20553 | representation clause for type x2 shows how pragma @cite{Pack} affects | |
20554 | this record type. | |
20555 | ||
20556 | In some cases, it may be useful to cut and paste the representation clauses | |
20557 | generated by the compiler into the original source to fix and guarantee | |
20558 | the actual representation to be used. | |
20559 | ||
20560 | @node Standard Library Routines,The Implementation of Standard I/O,Representation Clauses and Pragmas,Top | |
73918baf | 20561 | @anchor{gnat_rm/standard_library_routines doc}@anchor{2a5}@anchor{gnat_rm/standard_library_routines id1}@anchor{2a6}@anchor{gnat_rm/standard_library_routines standard-library-routines}@anchor{e} |
64d5610f ML |
20562 | @chapter Standard Library Routines |
20563 | ||
20564 | ||
20565 | The Ada Reference Manual contains in Annex A a full description of an | |
20566 | extensive set of standard library routines that can be used in any Ada | |
20567 | program, and which must be provided by all Ada compilers. They are | |
20568 | analogous to the standard C library used by C programs. | |
20569 | ||
20570 | GNAT implements all of the facilities described in annex A, and for most | |
20571 | purposes the description in the Ada Reference Manual, or appropriate Ada | |
20572 | text book, will be sufficient for making use of these facilities. | |
20573 | ||
20574 | In the case of the input-output facilities, | |
20575 | @ref{f,,The Implementation of Standard I/O}, | |
20576 | gives details on exactly how GNAT interfaces to the | |
20577 | file system. For the remaining packages, the Ada Reference Manual | |
20578 | should be sufficient. The following is a list of the packages included, | |
20579 | together with a brief description of the functionality that is provided. | |
20580 | ||
20581 | For completeness, references are included to other predefined library | |
20582 | routines defined in other sections of the Ada Reference Manual (these are | |
20583 | cross-indexed from Annex A). For further details see the relevant | |
20584 | package declarations in the run-time library. In particular, a few units | |
20585 | are not implemented, as marked by the presence of pragma Unimplemented_Unit, | |
20586 | and in this case the package declaration contains comments explaining why | |
20587 | the unit is not implemented. | |
20588 | ||
20589 | ||
20590 | @table @asis | |
20591 | ||
20592 | @item @code{Ada} `(A.2)' | |
20593 | ||
20594 | This is a parent package for all the standard library packages. It is | |
20595 | usually included implicitly in your program, and itself contains no | |
20596 | useful data or routines. | |
20597 | ||
20598 | @item @code{Ada.Assertions} `(11.4.2)' | |
20599 | ||
20600 | @code{Assertions} provides the @code{Assert} subprograms, and also | |
20601 | the declaration of the @code{Assertion_Error} exception. | |
20602 | ||
20603 | @item @code{Ada.Asynchronous_Task_Control} `(D.11)' | |
20604 | ||
20605 | @code{Asynchronous_Task_Control} provides low level facilities for task | |
20606 | synchronization. It is typically not implemented. See package spec for details. | |
20607 | ||
20608 | @item @code{Ada.Calendar} `(9.6)' | |
20609 | ||
20610 | @code{Calendar} provides time of day access, and routines for | |
20611 | manipulating times and durations. | |
20612 | ||
20613 | @item @code{Ada.Calendar.Arithmetic} `(9.6.1)' | |
20614 | ||
20615 | This package provides additional arithmetic | |
20616 | operations for @code{Calendar}. | |
20617 | ||
20618 | @item @code{Ada.Calendar.Formatting} `(9.6.1)' | |
20619 | ||
20620 | This package provides formatting operations for @code{Calendar}. | |
20621 | ||
20622 | @item @code{Ada.Calendar.Time_Zones} `(9.6.1)' | |
20623 | ||
20624 | This package provides additional @code{Calendar} facilities | |
20625 | for handling time zones. | |
20626 | ||
20627 | @item @code{Ada.Characters} `(A.3.1)' | |
20628 | ||
20629 | This is a dummy parent package that contains no useful entities | |
20630 | ||
20631 | @item @code{Ada.Characters.Conversions} `(A.3.2)' | |
20632 | ||
20633 | This package provides character conversion functions. | |
20634 | ||
20635 | @item @code{Ada.Characters.Handling} `(A.3.2)' | |
20636 | ||
20637 | This package provides some basic character handling capabilities, | |
20638 | including classification functions for classes of characters (e.g., test | |
20639 | for letters, or digits). | |
20640 | ||
20641 | @item @code{Ada.Characters.Latin_1} `(A.3.3)' | |
20642 | ||
20643 | This package includes a complete set of definitions of the characters | |
20644 | that appear in type CHARACTER. It is useful for writing programs that | |
20645 | will run in international environments. For example, if you want an | |
20646 | upper case E with an acute accent in a string, it is often better to use | |
20647 | the definition of @code{UC_E_Acute} in this package. Then your program | |
20648 | will print in an understandable manner even if your environment does not | |
20649 | support these extended characters. | |
20650 | ||
20651 | @item @code{Ada.Command_Line} `(A.15)' | |
20652 | ||
20653 | This package provides access to the command line parameters and the name | |
20654 | of the current program (analogous to the use of @code{argc} and @code{argv} | |
20655 | in C), and also allows the exit status for the program to be set in a | |
20656 | system-independent manner. | |
20657 | ||
20658 | @item @code{Ada.Complex_Text_IO} `(G.1.3)' | |
20659 | ||
20660 | This package provides text input and output of complex numbers. | |
20661 | ||
20662 | @item @code{Ada.Containers} `(A.18.1)' | |
20663 | ||
20664 | A top level package providing a few basic definitions used by all the | |
20665 | following specific child packages that provide specific kinds of | |
20666 | containers. | |
20667 | @end table | |
20668 | ||
20669 | @code{Ada.Containers.Bounded_Priority_Queues} `(A.18.31)' | |
20670 | ||
20671 | @code{Ada.Containers.Bounded_Synchronized_Queues} `(A.18.29)' | |
20672 | ||
20673 | @code{Ada.Containers.Doubly_Linked_Lists} `(A.18.3)' | |
20674 | ||
20675 | @code{Ada.Containers.Generic_Array_Sort} `(A.18.26)' | |
20676 | ||
20677 | @code{Ada.Containers.Generic_Constrained_Array_Sort} `(A.18.26)' | |
20678 | ||
20679 | @code{Ada.Containers.Generic_Sort} `(A.18.26)' | |
20680 | ||
20681 | @code{Ada.Containers.Hashed_Maps} `(A.18.5)' | |
20682 | ||
20683 | @code{Ada.Containers.Hashed_Sets} `(A.18.8)' | |
20684 | ||
20685 | @code{Ada.Containers.Indefinite_Doubly_Linked_Lists} `(A.18.12)' | |
20686 | ||
20687 | @code{Ada.Containers.Indefinite_Hashed_Maps} `(A.18.13)' | |
20688 | ||
20689 | @code{Ada.Containers.Indefinite_Hashed_Sets} `(A.18.15)' | |
20690 | ||
20691 | @code{Ada.Containers.Indefinite_Holders} `(A.18.18)' | |
20692 | ||
20693 | @code{Ada.Containers.Indefinite_Multiway_Trees} `(A.18.17)' | |
20694 | ||
20695 | @code{Ada.Containers.Indefinite_Ordered_Maps} `(A.18.14)' | |
20696 | ||
20697 | @code{Ada.Containers.Indefinite_Ordered_Sets} `(A.18.16)' | |
20698 | ||
20699 | @code{Ada.Containers.Indefinite_Vectors} `(A.18.11)' | |
20700 | ||
20701 | @code{Ada.Containers.Multiway_Trees} `(A.18.10)' | |
20702 | ||
20703 | @code{Ada.Containers.Ordered_Maps} `(A.18.6)' | |
20704 | ||
20705 | @code{Ada.Containers.Ordered_Sets} `(A.18.9)' | |
20706 | ||
20707 | @code{Ada.Containers.Synchronized_Queue_Interfaces} `(A.18.27)' | |
20708 | ||
20709 | @code{Ada.Containers.Unbounded_Priority_Queues} `(A.18.30)' | |
20710 | ||
20711 | @code{Ada.Containers.Unbounded_Synchronized_Queues} `(A.18.28)' | |
20712 | ||
20713 | @code{Ada.Containers.Vectors} `(A.18.2)' | |
20714 | ||
20715 | ||
20716 | @table @asis | |
20717 | ||
20718 | @item @code{Ada.Directories} `(A.16)' | |
20719 | ||
20720 | This package provides operations on directories. | |
20721 | ||
20722 | @item @code{Ada.Directories.Hierarchical_File_Names} `(A.16.1)' | |
20723 | ||
20724 | This package provides additional directory operations handling | |
20725 | hierarchical file names. | |
20726 | ||
20727 | @item @code{Ada.Directories.Information} `(A.16)' | |
20728 | ||
20729 | This is an implementation defined package for additional directory | |
20730 | operations, which is not implemented in GNAT. | |
20731 | ||
20732 | @item @code{Ada.Decimal} `(F.2)' | |
20733 | ||
20734 | This package provides constants describing the range of decimal numbers | |
20735 | implemented, and also a decimal divide routine (analogous to the COBOL | |
20736 | verb DIVIDE … GIVING … REMAINDER …) | |
20737 | ||
20738 | @item @code{Ada.Direct_IO} `(A.8.4)' | |
20739 | ||
20740 | This package provides input-output using a model of a set of records of | |
20741 | fixed-length, containing an arbitrary definite Ada type, indexed by an | |
20742 | integer record number. | |
20743 | ||
20744 | @item @code{Ada.Dispatching} `(D.2.1)' | |
20745 | ||
20746 | A parent package containing definitions for task dispatching operations. | |
20747 | ||
20748 | @item @code{Ada.Dispatching.EDF} `(D.2.6)' | |
20749 | ||
20750 | Not implemented in GNAT. | |
20751 | ||
20752 | @item @code{Ada.Dispatching.Non_Preemptive} `(D.2.4)' | |
20753 | ||
20754 | Not implemented in GNAT. | |
20755 | ||
20756 | @item @code{Ada.Dispatching.Round_Robin} `(D.2.5)' | |
20757 | ||
20758 | Not implemented in GNAT. | |
20759 | ||
20760 | @item @code{Ada.Dynamic_Priorities} `(D.5)' | |
20761 | ||
20762 | This package allows the priorities of a task to be adjusted dynamically | |
20763 | as the task is running. | |
20764 | ||
20765 | @item @code{Ada.Environment_Variables} `(A.17)' | |
20766 | ||
20767 | This package provides facilities for accessing environment variables. | |
20768 | ||
20769 | @item @code{Ada.Exceptions} `(11.4.1)' | |
20770 | ||
20771 | This package provides additional information on exceptions, and also | |
20772 | contains facilities for treating exceptions as data objects, and raising | |
20773 | exceptions with associated messages. | |
20774 | ||
20775 | @item @code{Ada.Execution_Time} `(D.14)' | |
20776 | ||
20777 | This package provides CPU clock functionalities. It is not implemented on | |
20778 | all targets (see package spec for details). | |
20779 | ||
20780 | @item @code{Ada.Execution_Time.Group_Budgets} `(D.14.2)' | |
20781 | ||
20782 | Not implemented in GNAT. | |
20783 | ||
20784 | @item @code{Ada.Execution_Time.Timers} `(D.14.1)’' | |
20785 | ||
20786 | Not implemented in GNAT. | |
20787 | ||
20788 | @item @code{Ada.Finalization} `(7.6)' | |
20789 | ||
20790 | This package contains the declarations and subprograms to support the | |
20791 | use of controlled types, providing for automatic initialization and | |
20792 | finalization (analogous to the constructors and destructors of C++). | |
20793 | ||
20794 | @item @code{Ada.Float_Text_IO} `(A.10.9)' | |
20795 | ||
20796 | A library level instantiation of Text_IO.Float_IO for type Float. | |
20797 | ||
20798 | @item @code{Ada.Float_Wide_Text_IO} `(A.10.9)' | |
20799 | ||
20800 | A library level instantiation of Wide_Text_IO.Float_IO for type Float. | |
20801 | ||
20802 | @item @code{Ada.Float_Wide_Wide_Text_IO} `(A.10.9)' | |
20803 | ||
20804 | A library level instantiation of Wide_Wide_Text_IO.Float_IO for type Float. | |
20805 | ||
20806 | @item @code{Ada.Integer_Text_IO} `(A.10.9)' | |
20807 | ||
20808 | A library level instantiation of Text_IO.Integer_IO for type Integer. | |
20809 | ||
20810 | @item @code{Ada.Integer_Wide_Text_IO} `(A.10.9)' | |
20811 | ||
20812 | A library level instantiation of Wide_Text_IO.Integer_IO for type Integer. | |
20813 | ||
20814 | @item @code{Ada.Integer_Wide_Wide_Text_IO} `(A.10.9)' | |
20815 | ||
20816 | A library level instantiation of Wide_Wide_Text_IO.Integer_IO for type Integer. | |
20817 | ||
20818 | @item @code{Ada.Interrupts} `(C.3.2)' | |
20819 | ||
20820 | This package provides facilities for interfacing to interrupts, which | |
20821 | includes the set of signals or conditions that can be raised and | |
20822 | recognized as interrupts. | |
20823 | ||
20824 | @item @code{Ada.Interrupts.Names} `(C.3.2)' | |
20825 | ||
20826 | This package provides the set of interrupt names (actually signal | |
20827 | or condition names) that can be handled by GNAT. | |
20828 | ||
20829 | @item @code{Ada.IO_Exceptions} `(A.13)' | |
20830 | ||
20831 | This package defines the set of exceptions that can be raised by use of | |
20832 | the standard IO packages. | |
20833 | ||
20834 | @item @code{Ada.Iterator_Interfaces} `(5.5.1)' | |
20835 | ||
20836 | This package provides a generic interface to generalized iterators. | |
20837 | ||
20838 | @item @code{Ada.Locales} `(A.19)' | |
20839 | ||
20840 | This package provides declarations providing information (Language | |
20841 | and Country) about the current locale. | |
20842 | ||
20843 | @item @code{Ada.Numerics} | |
20844 | ||
20845 | This package contains some standard constants and exceptions used | |
20846 | throughout the numerics packages. Note that the constants pi and e are | |
20847 | defined here, and it is better to use these definitions than rolling | |
20848 | your own. | |
20849 | ||
20850 | @item @code{Ada.Numerics.Complex_Arrays} `(G.3.2)' | |
20851 | ||
20852 | Provides operations on arrays of complex numbers. | |
20853 | ||
20854 | @item @code{Ada.Numerics.Complex_Elementary_Functions} | |
20855 | ||
20856 | Provides the implementation of standard elementary functions (such as | |
20857 | log and trigonometric functions) operating on complex numbers using the | |
20858 | standard @code{Float} and the @code{Complex} and @code{Imaginary} types | |
20859 | created by the package @code{Numerics.Complex_Types}. | |
20860 | ||
20861 | @item @code{Ada.Numerics.Complex_Types} | |
20862 | ||
20863 | This is a predefined instantiation of | |
20864 | @code{Numerics.Generic_Complex_Types} using @code{Standard.Float} to | |
20865 | build the type @code{Complex} and @code{Imaginary}. | |
20866 | ||
20867 | @item @code{Ada.Numerics.Discrete_Random} | |
20868 | ||
20869 | This generic package provides a random number generator suitable for generating | |
20870 | uniformly distributed values of a specified discrete subtype. | |
20871 | ||
20872 | @item @code{Ada.Numerics.Float_Random} | |
20873 | ||
20874 | This package provides a random number generator suitable for generating | |
20875 | uniformly distributed floating point values in the unit interval. | |
20876 | ||
20877 | @item @code{Ada.Numerics.Generic_Complex_Elementary_Functions} | |
20878 | ||
20879 | This is a generic version of the package that provides the | |
20880 | implementation of standard elementary functions (such as log and | |
20881 | trigonometric functions) for an arbitrary complex type. | |
20882 | ||
20883 | The following predefined instantiations of this package are provided: | |
20884 | ||
20885 | ||
20886 | @itemize * | |
20887 | ||
20888 | @item | |
20889 | @code{Short_Float} | |
20890 | ||
20891 | @code{Ada.Numerics.Short_Complex_Elementary_Functions} | |
20892 | ||
20893 | @item | |
20894 | @code{Float} | |
20895 | ||
20896 | @code{Ada.Numerics.Complex_Elementary_Functions} | |
20897 | ||
20898 | @item | |
20899 | @code{Long_Float} | |
20900 | ||
20901 | @code{Ada.Numerics.Long_Complex_Elementary_Functions} | |
20902 | @end itemize | |
20903 | ||
20904 | @item @code{Ada.Numerics.Generic_Complex_Types} | |
20905 | ||
20906 | This is a generic package that allows the creation of complex types, | |
20907 | with associated complex arithmetic operations. | |
20908 | ||
20909 | The following predefined instantiations of this package exist | |
20910 | ||
20911 | ||
20912 | @itemize * | |
20913 | ||
20914 | @item | |
20915 | @code{Short_Float} | |
20916 | ||
20917 | @code{Ada.Numerics.Short_Complex_Complex_Types} | |
20918 | ||
20919 | @item | |
20920 | @code{Float} | |
20921 | ||
20922 | @code{Ada.Numerics.Complex_Complex_Types} | |
20923 | ||
20924 | @item | |
20925 | @code{Long_Float} | |
20926 | ||
20927 | @code{Ada.Numerics.Long_Complex_Complex_Types} | |
20928 | @end itemize | |
20929 | ||
20930 | @item @code{Ada.Numerics.Generic_Elementary_Functions} | |
20931 | ||
20932 | This is a generic package that provides the implementation of standard | |
20933 | elementary functions (such as log an trigonometric functions) for an | |
20934 | arbitrary float type. | |
20935 | ||
20936 | The following predefined instantiations of this package exist | |
20937 | ||
20938 | ||
20939 | @itemize * | |
20940 | ||
20941 | @item | |
20942 | @code{Short_Float} | |
20943 | ||
20944 | @code{Ada.Numerics.Short_Elementary_Functions} | |
20945 | ||
20946 | @item | |
20947 | @code{Float} | |
20948 | ||
20949 | @code{Ada.Numerics.Elementary_Functions} | |
20950 | ||
20951 | @item | |
20952 | @code{Long_Float} | |
20953 | ||
20954 | @code{Ada.Numerics.Long_Elementary_Functions} | |
20955 | @end itemize | |
20956 | ||
20957 | @item @code{Ada.Numerics.Generic_Real_Arrays} `(G.3.1)' | |
20958 | ||
20959 | Generic operations on arrays of reals | |
20960 | ||
20961 | @item @code{Ada.Numerics.Real_Arrays} `(G.3.1)' | |
20962 | ||
20963 | Preinstantiation of Ada.Numerics.Generic_Real_Arrays (Float). | |
20964 | ||
20965 | @item @code{Ada.Real_Time} `(D.8)' | |
20966 | ||
20967 | This package provides facilities similar to those of @code{Calendar}, but | |
20968 | operating with a finer clock suitable for real time control. Note that | |
20969 | annex D requires that there be no backward clock jumps, and GNAT generally | |
20970 | guarantees this behavior, but of course if the external clock on which | |
20971 | the GNAT runtime depends is deliberately reset by some external event, | |
20972 | then such a backward jump may occur. | |
20973 | ||
20974 | @item @code{Ada.Real_Time.Timing_Events} `(D.15)' | |
20975 | ||
20976 | Not implemented in GNAT. | |
20977 | ||
20978 | @item @code{Ada.Sequential_IO} `(A.8.1)' | |
20979 | ||
20980 | This package provides input-output facilities for sequential files, | |
20981 | which can contain a sequence of values of a single type, which can be | |
20982 | any Ada type, including indefinite (unconstrained) types. | |
20983 | ||
20984 | @item @code{Ada.Storage_IO} `(A.9)' | |
20985 | ||
20986 | This package provides a facility for mapping arbitrary Ada types to and | |
20987 | from a storage buffer. It is primarily intended for the creation of new | |
20988 | IO packages. | |
20989 | ||
20990 | @item @code{Ada.Streams} `(13.13.1)' | |
20991 | ||
20992 | This is a generic package that provides the basic support for the | |
20993 | concept of streams as used by the stream attributes (@code{Input}, | |
20994 | @code{Output}, @code{Read} and @code{Write}). | |
20995 | ||
20996 | @item @code{Ada.Streams.Stream_IO} `(A.12.1)' | |
20997 | ||
20998 | This package is a specialization of the type @code{Streams} defined in | |
20999 | package @code{Streams} together with a set of operations providing | |
21000 | Stream_IO capability. The Stream_IO model permits both random and | |
21001 | sequential access to a file which can contain an arbitrary set of values | |
21002 | of one or more Ada types. | |
21003 | ||
21004 | @item @code{Ada.Strings} `(A.4.1)' | |
21005 | ||
21006 | This package provides some basic constants used by the string handling | |
21007 | packages. | |
21008 | ||
21009 | @item @code{Ada.Strings.Bounded} `(A.4.4)' | |
21010 | ||
21011 | This package provides facilities for handling variable length | |
21012 | strings. The bounded model requires a maximum length. It is thus | |
21013 | somewhat more limited than the unbounded model, but avoids the use of | |
21014 | dynamic allocation or finalization. | |
21015 | ||
21016 | @item @code{Ada.Strings.Bounded.Equal_Case_Insensitive} `(A.4.10)' | |
21017 | ||
21018 | Provides case-insensitive comparisons of bounded strings | |
21019 | ||
21020 | @item @code{Ada.Strings.Bounded.Hash} `(A.4.9)' | |
21021 | ||
21022 | This package provides a generic hash function for bounded strings | |
21023 | ||
21024 | @item @code{Ada.Strings.Bounded.Hash_Case_Insensitive} `(A.4.9)' | |
21025 | ||
21026 | This package provides a generic hash function for bounded strings that | |
21027 | converts the string to be hashed to lower case. | |
21028 | ||
21029 | @item @code{Ada.Strings.Bounded.Less_Case_Insensitive} `(A.4.10)' | |
21030 | ||
21031 | This package provides a comparison function for bounded strings that works | |
21032 | in a case insensitive manner by converting to lower case before the comparison. | |
21033 | ||
21034 | @item @code{Ada.Strings.Fixed} `(A.4.3)' | |
21035 | ||
21036 | This package provides facilities for handling fixed length strings. | |
21037 | ||
21038 | @item @code{Ada.Strings.Fixed.Equal_Case_Insensitive} `(A.4.10)' | |
21039 | ||
21040 | This package provides an equality function for fixed strings that compares | |
21041 | the strings after converting both to lower case. | |
21042 | ||
21043 | @item @code{Ada.Strings.Fixed.Hash_Case_Insensitive} `(A.4.9)' | |
21044 | ||
21045 | This package provides a case insensitive hash function for fixed strings that | |
21046 | converts the string to lower case before computing the hash. | |
21047 | ||
21048 | @item @code{Ada.Strings.Fixed.Less_Case_Insensitive} `(A.4.10)' | |
21049 | ||
21050 | This package provides a comparison function for fixed strings that works | |
21051 | in a case insensitive manner by converting to lower case before the comparison. | |
21052 | ||
21053 | @item @code{Ada.Strings.Hash} `(A.4.9)' | |
21054 | ||
21055 | This package provides a hash function for strings. | |
21056 | ||
21057 | @item @code{Ada.Strings.Hash_Case_Insensitive} `(A.4.9)' | |
21058 | ||
21059 | This package provides a hash function for strings that is case insensitive. | |
21060 | The string is converted to lower case before computing the hash. | |
21061 | ||
21062 | @item @code{Ada.Strings.Less_Case_Insensitive} `(A.4.10)' | |
21063 | ||
21064 | This package provides a comparison function for\strings that works | |
21065 | in a case insensitive manner by converting to lower case before the comparison. | |
21066 | ||
21067 | @item @code{Ada.Strings.Maps} `(A.4.2)' | |
21068 | ||
21069 | This package provides facilities for handling character mappings and | |
21070 | arbitrarily defined subsets of characters. For instance it is useful in | |
21071 | defining specialized translation tables. | |
21072 | ||
21073 | @item @code{Ada.Strings.Maps.Constants} `(A.4.6)' | |
21074 | ||
21075 | This package provides a standard set of predefined mappings and | |
21076 | predefined character sets. For example, the standard upper to lower case | |
21077 | conversion table is found in this package. Note that upper to lower case | |
21078 | conversion is non-trivial if you want to take the entire set of | |
21079 | characters, including extended characters like E with an acute accent, | |
21080 | into account. You should use the mappings in this package (rather than | |
21081 | adding 32 yourself) to do case mappings. | |
21082 | ||
21083 | @item @code{Ada.Strings.Unbounded} `(A.4.5)' | |
21084 | ||
21085 | This package provides facilities for handling variable length | |
21086 | strings. The unbounded model allows arbitrary length strings, but | |
21087 | requires the use of dynamic allocation and finalization. | |
21088 | ||
21089 | @item @code{Ada.Strings.Unbounded.Equal_Case_Insensitive} `(A.4.10)' | |
21090 | ||
21091 | Provides case-insensitive comparisons of unbounded strings | |
21092 | ||
21093 | @item @code{Ada.Strings.Unbounded.Hash} `(A.4.9)' | |
21094 | ||
21095 | This package provides a generic hash function for unbounded strings | |
21096 | ||
21097 | @item @code{Ada.Strings.Unbounded.Hash_Case_Insensitive} `(A.4.9)' | |
21098 | ||
21099 | This package provides a generic hash function for unbounded strings that | |
21100 | converts the string to be hashed to lower case. | |
21101 | ||
21102 | @item @code{Ada.Strings.Unbounded.Less_Case_Insensitive} `(A.4.10)' | |
21103 | ||
21104 | This package provides a comparison function for unbounded strings that works | |
21105 | in a case insensitive manner by converting to lower case before the comparison. | |
21106 | ||
21107 | @item @code{Ada.Strings.UTF_Encoding} `(A.4.11)' | |
21108 | ||
21109 | This package provides basic definitions for dealing with UTF-encoded strings. | |
21110 | ||
21111 | @item @code{Ada.Strings.UTF_Encoding.Conversions} `(A.4.11)' | |
21112 | ||
21113 | This package provides conversion functions for UTF-encoded strings. | |
21114 | @end table | |
21115 | ||
21116 | @code{Ada.Strings.UTF_Encoding.Strings} `(A.4.11)' | |
21117 | ||
21118 | @code{Ada.Strings.UTF_Encoding.Wide_Strings} `(A.4.11)' | |
21119 | ||
21120 | ||
21121 | @table @asis | |
21122 | ||
21123 | @item @code{Ada.Strings.UTF_Encoding.Wide_Wide_Strings} `(A.4.11)' | |
21124 | ||
21125 | These packages provide facilities for handling UTF encodings for | |
21126 | Strings, Wide_Strings and Wide_Wide_Strings. | |
21127 | @end table | |
21128 | ||
21129 | @code{Ada.Strings.Wide_Bounded} `(A.4.7)' | |
21130 | ||
21131 | @code{Ada.Strings.Wide_Fixed} `(A.4.7)' | |
21132 | ||
21133 | @code{Ada.Strings.Wide_Maps} `(A.4.7)' | |
21134 | ||
21135 | ||
21136 | @table @asis | |
21137 | ||
21138 | @item @code{Ada.Strings.Wide_Unbounded} `(A.4.7)' | |
21139 | ||
21140 | These packages provide analogous capabilities to the corresponding | |
21141 | packages without @code{Wide_} in the name, but operate with the types | |
21142 | @code{Wide_String} and @code{Wide_Character} instead of @code{String} | |
21143 | and @code{Character}. Versions of all the child packages are available. | |
21144 | @end table | |
21145 | ||
21146 | @code{Ada.Strings.Wide_Wide_Bounded} `(A.4.7)' | |
21147 | ||
21148 | @code{Ada.Strings.Wide_Wide_Fixed} `(A.4.7)' | |
21149 | ||
21150 | @code{Ada.Strings.Wide_Wide_Maps} `(A.4.7)' | |
21151 | ||
21152 | ||
21153 | @table @asis | |
21154 | ||
21155 | @item @code{Ada.Strings.Wide_Wide_Unbounded} `(A.4.7)' | |
21156 | ||
21157 | These packages provide analogous capabilities to the corresponding | |
21158 | packages without @code{Wide_} in the name, but operate with the types | |
21159 | @code{Wide_Wide_String} and @code{Wide_Wide_Character} instead | |
21160 | of @code{String} and @code{Character}. | |
21161 | ||
21162 | @item @code{Ada.Synchronous_Barriers} `(D.10.1)' | |
21163 | ||
21164 | This package provides facilities for synchronizing tasks at a low level | |
21165 | with barriers. | |
21166 | ||
21167 | @item @code{Ada.Synchronous_Task_Control} `(D.10)' | |
21168 | ||
21169 | This package provides some standard facilities for controlling task | |
21170 | communication in a synchronous manner. | |
21171 | ||
21172 | @item @code{Ada.Synchronous_Task_Control.EDF} `(D.10)' | |
21173 | ||
21174 | Not implemented in GNAT. | |
21175 | ||
21176 | @item @code{Ada.Tags} | |
21177 | ||
21178 | This package contains definitions for manipulation of the tags of tagged | |
21179 | values. | |
21180 | ||
21181 | @item @code{Ada.Tags.Generic_Dispatching_Constructor} `(3.9)' | |
21182 | ||
21183 | This package provides a way of constructing tagged class-wide values given | |
21184 | only the tag value. | |
21185 | ||
21186 | @item @code{Ada.Task_Attributes} `(C.7.2)' | |
21187 | ||
21188 | This package provides the capability of associating arbitrary | |
21189 | task-specific data with separate tasks. | |
21190 | ||
21191 | @item @code{Ada.Task_Identification} `(C.7.1)' | |
21192 | ||
21193 | This package provides capabilities for task identification. | |
21194 | ||
21195 | @item @code{Ada.Task_Termination} `(C.7.3)' | |
21196 | ||
21197 | This package provides control over task termination. | |
21198 | ||
21199 | @item @code{Ada.Text_IO} | |
21200 | ||
21201 | This package provides basic text input-output capabilities for | |
21202 | character, string and numeric data. The subpackages of this | |
21203 | package are listed next. Note that although these are defined | |
21204 | as subpackages in the RM, they are actually transparently | |
21205 | implemented as child packages in GNAT, meaning that they | |
21206 | are only loaded if needed. | |
21207 | ||
21208 | @item @code{Ada.Text_IO.Decimal_IO} | |
21209 | ||
21210 | Provides input-output facilities for decimal fixed-point types | |
21211 | ||
21212 | @item @code{Ada.Text_IO.Enumeration_IO} | |
21213 | ||
21214 | Provides input-output facilities for enumeration types. | |
21215 | ||
21216 | @item @code{Ada.Text_IO.Fixed_IO} | |
21217 | ||
21218 | Provides input-output facilities for ordinary fixed-point types. | |
21219 | ||
21220 | @item @code{Ada.Text_IO.Float_IO} | |
21221 | ||
21222 | Provides input-output facilities for float types. The following | |
21223 | predefined instantiations of this generic package are available: | |
21224 | ||
21225 | ||
21226 | @itemize * | |
21227 | ||
21228 | @item | |
21229 | @code{Short_Float} | |
21230 | ||
21231 | @code{Short_Float_Text_IO} | |
21232 | ||
21233 | @item | |
21234 | @code{Float} | |
21235 | ||
21236 | @code{Float_Text_IO} | |
21237 | ||
21238 | @item | |
21239 | @code{Long_Float} | |
21240 | ||
21241 | @code{Long_Float_Text_IO} | |
21242 | @end itemize | |
21243 | ||
21244 | @item @code{Ada.Text_IO.Integer_IO} | |
21245 | ||
21246 | Provides input-output facilities for integer types. The following | |
21247 | predefined instantiations of this generic package are available: | |
21248 | ||
21249 | ||
21250 | @itemize * | |
21251 | ||
21252 | @item | |
21253 | @code{Short_Short_Integer} | |
21254 | ||
21255 | @code{Ada.Short_Short_Integer_Text_IO} | |
21256 | ||
21257 | @item | |
21258 | @code{Short_Integer} | |
21259 | ||
21260 | @code{Ada.Short_Integer_Text_IO} | |
21261 | ||
21262 | @item | |
21263 | @code{Integer} | |
21264 | ||
21265 | @code{Ada.Integer_Text_IO} | |
21266 | ||
21267 | @item | |
21268 | @code{Long_Integer} | |
21269 | ||
21270 | @code{Ada.Long_Integer_Text_IO} | |
21271 | ||
21272 | @item | |
21273 | @code{Long_Long_Integer} | |
21274 | ||
21275 | @code{Ada.Long_Long_Integer_Text_IO} | |
21276 | @end itemize | |
21277 | ||
21278 | @item @code{Ada.Text_IO.Modular_IO} | |
21279 | ||
21280 | Provides input-output facilities for modular (unsigned) types. | |
21281 | ||
21282 | @item @code{Ada.Text_IO.Bounded_IO (A.10.11)} | |
21283 | ||
21284 | Provides input-output facilities for bounded strings. | |
21285 | ||
21286 | @item @code{Ada.Text_IO.Complex_IO (G.1.3)} | |
21287 | ||
21288 | This package provides basic text input-output capabilities for complex | |
21289 | data. | |
21290 | ||
21291 | @item @code{Ada.Text_IO.Editing (F.3.3)} | |
21292 | ||
21293 | This package contains routines for edited output, analogous to the use | |
21294 | of pictures in COBOL. The picture formats used by this package are a | |
21295 | close copy of the facility in COBOL. | |
21296 | ||
21297 | @item @code{Ada.Text_IO.Text_Streams (A.12.2)} | |
21298 | ||
21299 | This package provides a facility that allows Text_IO files to be treated | |
21300 | as streams, so that the stream attributes can be used for writing | |
21301 | arbitrary data, including binary data, to Text_IO files. | |
21302 | ||
21303 | @item @code{Ada.Text_IO.Unbounded_IO (A.10.12)} | |
21304 | ||
21305 | This package provides input-output facilities for unbounded strings. | |
21306 | ||
21307 | @item @code{Ada.Unchecked_Conversion (13.9)} | |
21308 | ||
21309 | This generic package allows arbitrary conversion from one type to | |
21310 | another of the same size, providing for breaking the type safety in | |
21311 | special circumstances. | |
21312 | ||
21313 | If the types have the same Size (more accurately the same Value_Size), | |
21314 | then the effect is simply to transfer the bits from the source to the | |
21315 | target type without any modification. This usage is well defined, and | |
21316 | for simple types whose representation is typically the same across | |
21317 | all implementations, gives a portable method of performing such | |
21318 | conversions. | |
21319 | ||
21320 | If the types do not have the same size, then the result is implementation | |
21321 | defined, and thus may be non-portable. The following describes how GNAT | |
21322 | handles such unchecked conversion cases. | |
21323 | ||
21324 | If the types are of different sizes, and are both discrete types, then | |
21325 | the effect is of a normal type conversion without any constraint checking. | |
21326 | In particular if the result type has a larger size, the result will be | |
21327 | zero or sign extended. If the result type has a smaller size, the result | |
21328 | will be truncated by ignoring high order bits. | |
21329 | ||
21330 | If the types are of different sizes, and are not both discrete types, | |
21331 | then the conversion works as though pointers were created to the source | |
21332 | and target, and the pointer value is converted. The effect is that bits | |
21333 | are copied from successive low order storage units and bits of the source | |
21334 | up to the length of the target type. | |
21335 | ||
21336 | A warning is issued if the lengths differ, since the effect in this | |
21337 | case is implementation dependent, and the above behavior may not match | |
21338 | that of some other compiler. | |
21339 | ||
21340 | A pointer to one type may be converted to a pointer to another type using | |
21341 | unchecked conversion. The only case in which the effect is undefined is | |
21342 | when one or both pointers are pointers to unconstrained array types. In | |
21343 | this case, the bounds information may get incorrectly transferred, and in | |
21344 | particular, GNAT uses double size pointers for such types, and it is | |
21345 | meaningless to convert between such pointer types. GNAT will issue a | |
21346 | warning if the alignment of the target designated type is more strict | |
21347 | than the alignment of the source designated type (since the result may | |
21348 | be unaligned in this case). | |
21349 | ||
21350 | A pointer other than a pointer to an unconstrained array type may be | |
21351 | converted to and from System.Address. Such usage is common in Ada 83 | |
21352 | programs, but note that Ada.Address_To_Access_Conversions is the | |
21353 | preferred method of performing such conversions in Ada 95 and Ada 2005. | |
21354 | Neither | |
21355 | unchecked conversion nor Ada.Address_To_Access_Conversions should be | |
21356 | used in conjunction with pointers to unconstrained objects, since | |
21357 | the bounds information cannot be handled correctly in this case. | |
21358 | ||
21359 | @item @code{Ada.Unchecked_Deallocation} `(13.11.2)' | |
21360 | ||
21361 | This generic package allows explicit freeing of storage previously | |
21362 | allocated by use of an allocator. | |
21363 | ||
21364 | @item @code{Ada.Wide_Text_IO} `(A.11)' | |
21365 | ||
21366 | This package is similar to @code{Ada.Text_IO}, except that the external | |
21367 | file supports wide character representations, and the internal types are | |
21368 | @code{Wide_Character} and @code{Wide_String} instead of @code{Character} | |
21369 | and @code{String}. The corresponding set of nested packages and child | |
21370 | packages are defined. | |
21371 | ||
21372 | @item @code{Ada.Wide_Wide_Text_IO} `(A.11)' | |
21373 | ||
21374 | This package is similar to @code{Ada.Text_IO}, except that the external | |
21375 | file supports wide character representations, and the internal types are | |
21376 | @code{Wide_Character} and @code{Wide_String} instead of @code{Character} | |
21377 | and @code{String}. The corresponding set of nested packages and child | |
21378 | packages are defined. | |
21379 | @end table | |
21380 | ||
21381 | For packages in Interfaces and System, all the RM defined packages are | |
21382 | available in GNAT, see the Ada 2012 RM for full details. | |
21383 | ||
21384 | @node The Implementation of Standard I/O,The GNAT Library,Standard Library Routines,Top | |
73918baf | 21385 | @anchor{gnat_rm/the_implementation_of_standard_i_o doc}@anchor{2a7}@anchor{gnat_rm/the_implementation_of_standard_i_o id1}@anchor{2a8}@anchor{gnat_rm/the_implementation_of_standard_i_o the-implementation-of-standard-i-o}@anchor{f} |
64d5610f ML |
21386 | @chapter The Implementation of Standard I/O |
21387 | ||
21388 | ||
21389 | GNAT implements all the required input-output facilities described in | |
21390 | A.6 through A.14. These sections of the Ada Reference Manual describe the | |
21391 | required behavior of these packages from the Ada point of view, and if | |
21392 | you are writing a portable Ada program that does not need to know the | |
21393 | exact manner in which Ada maps to the outside world when it comes to | |
21394 | reading or writing external files, then you do not need to read this | |
21395 | chapter. As long as your files are all regular files (not pipes or | |
21396 | devices), and as long as you write and read the files only from Ada, the | |
21397 | description in the Ada Reference Manual is sufficient. | |
21398 | ||
21399 | However, if you want to do input-output to pipes or other devices, such | |
21400 | as the keyboard or screen, or if the files you are dealing with are | |
21401 | either generated by some other language, or to be read by some other | |
21402 | language, then you need to know more about the details of how the GNAT | |
21403 | implementation of these input-output facilities behaves. | |
21404 | ||
21405 | In this chapter we give a detailed description of exactly how GNAT | |
21406 | interfaces to the file system. As always, the sources of the system are | |
21407 | available to you for answering questions at an even more detailed level, | |
21408 | but for most purposes the information in this chapter will suffice. | |
21409 | ||
21410 | Another reason that you may need to know more about how input-output is | |
21411 | implemented arises when you have a program written in mixed languages | |
21412 | where, for example, files are shared between the C and Ada sections of | |
21413 | the same program. GNAT provides some additional facilities, in the form | |
21414 | of additional child library packages, that facilitate this sharing, and | |
21415 | these additional facilities are also described in this chapter. | |
21416 | ||
21417 | @menu | |
21418 | * Standard I/O Packages:: | |
21419 | * FORM Strings:: | |
21420 | * Direct_IO:: | |
21421 | * Sequential_IO:: | |
21422 | * Text_IO:: | |
21423 | * Wide_Text_IO:: | |
21424 | * Wide_Wide_Text_IO:: | |
21425 | * Stream_IO:: | |
21426 | * Text Translation:: | |
21427 | * Shared Files:: | |
21428 | * Filenames encoding:: | |
21429 | * File content encoding:: | |
21430 | * Open Modes:: | |
21431 | * Operations on C Streams:: | |
21432 | * Interfacing to C Streams:: | |
21433 | ||
21434 | @end menu | |
21435 | ||
21436 | @node Standard I/O Packages,FORM Strings,,The Implementation of Standard I/O | |
73918baf | 21437 | @anchor{gnat_rm/the_implementation_of_standard_i_o id2}@anchor{2a9}@anchor{gnat_rm/the_implementation_of_standard_i_o standard-i-o-packages}@anchor{2aa} |
64d5610f ML |
21438 | @section Standard I/O Packages |
21439 | ||
21440 | ||
21441 | The Standard I/O packages described in Annex A for | |
21442 | ||
21443 | ||
21444 | @itemize * | |
21445 | ||
21446 | @item | |
21447 | Ada.Text_IO | |
21448 | ||
21449 | @item | |
21450 | Ada.Text_IO.Complex_IO | |
21451 | ||
21452 | @item | |
21453 | Ada.Text_IO.Text_Streams | |
21454 | ||
21455 | @item | |
21456 | Ada.Wide_Text_IO | |
21457 | ||
21458 | @item | |
21459 | Ada.Wide_Text_IO.Complex_IO | |
21460 | ||
21461 | @item | |
21462 | Ada.Wide_Text_IO.Text_Streams | |
21463 | ||
21464 | @item | |
21465 | Ada.Wide_Wide_Text_IO | |
21466 | ||
21467 | @item | |
21468 | Ada.Wide_Wide_Text_IO.Complex_IO | |
21469 | ||
21470 | @item | |
21471 | Ada.Wide_Wide_Text_IO.Text_Streams | |
21472 | ||
21473 | @item | |
21474 | Ada.Stream_IO | |
21475 | ||
21476 | @item | |
21477 | Ada.Sequential_IO | |
21478 | ||
21479 | @item | |
21480 | Ada.Direct_IO | |
21481 | @end itemize | |
21482 | ||
21483 | are implemented using the C | |
21484 | library streams facility; where | |
21485 | ||
21486 | ||
21487 | @itemize * | |
21488 | ||
21489 | @item | |
21490 | All files are opened using @code{fopen}. | |
21491 | ||
21492 | @item | |
21493 | All input/output operations use @code{fread}/@cite{fwrite}. | |
21494 | @end itemize | |
21495 | ||
21496 | There is no internal buffering of any kind at the Ada library level. The only | |
21497 | buffering is that provided at the system level in the implementation of the | |
21498 | library routines that support streams. This facilitates shared use of these | |
21499 | streams by mixed language programs. Note though that system level buffering is | |
21500 | explicitly enabled at elaboration of the standard I/O packages and that can | |
21501 | have an impact on mixed language programs, in particular those using I/O before | |
21502 | calling the Ada elaboration routine (e.g., adainit). It is recommended to call | |
21503 | the Ada elaboration routine before performing any I/O or when impractical, | |
21504 | flush the common I/O streams and in particular Standard_Output before | |
21505 | elaborating the Ada code. | |
21506 | ||
21507 | @node FORM Strings,Direct_IO,Standard I/O Packages,The Implementation of Standard I/O | |
73918baf | 21508 | @anchor{gnat_rm/the_implementation_of_standard_i_o form-strings}@anchor{2ab}@anchor{gnat_rm/the_implementation_of_standard_i_o id3}@anchor{2ac} |
64d5610f ML |
21509 | @section FORM Strings |
21510 | ||
21511 | ||
21512 | The format of a FORM string in GNAT is: | |
21513 | ||
21514 | @example | |
21515 | "keyword=value,keyword=value,...,keyword=value" | |
21516 | @end example | |
21517 | ||
21518 | where letters may be in upper or lower case, and there are no spaces | |
21519 | between values. The order of the entries is not important. Currently | |
21520 | the following keywords defined. | |
21521 | ||
21522 | @example | |
21523 | TEXT_TRANSLATION=[YES|NO|TEXT|BINARY|U8TEXT|WTEXT|U16TEXT] | |
21524 | SHARED=[YES|NO] | |
21525 | WCEM=[n|h|u|s|e|8|b] | |
21526 | ENCODING=[UTF8|8BITS] | |
21527 | @end example | |
21528 | ||
21529 | The use of these parameters is described later in this section. If an | |
21530 | unrecognized keyword appears in a form string, it is silently ignored | |
21531 | and not considered invalid. | |
21532 | ||
21533 | @node Direct_IO,Sequential_IO,FORM Strings,The Implementation of Standard I/O | |
73918baf | 21534 | @anchor{gnat_rm/the_implementation_of_standard_i_o direct-io}@anchor{2ad}@anchor{gnat_rm/the_implementation_of_standard_i_o id4}@anchor{2ae} |
64d5610f ML |
21535 | @section Direct_IO |
21536 | ||
21537 | ||
21538 | Direct_IO can only be instantiated for definite types. This is a | |
21539 | restriction of the Ada language, which means that the records are fixed | |
21540 | length (the length being determined by @code{type'Size}, rounded | |
21541 | up to the next storage unit boundary if necessary). | |
21542 | ||
21543 | The records of a Direct_IO file are simply written to the file in index | |
21544 | sequence, with the first record starting at offset zero, and subsequent | |
21545 | records following. There is no control information of any kind. For | |
21546 | example, if 32-bit integers are being written, each record takes | |
21547 | 4-bytes, so the record at index @code{K} starts at offset | |
21548 | (@code{K}-1)*4. | |
21549 | ||
21550 | There is no limit on the size of Direct_IO files, they are expanded as | |
21551 | necessary to accommodate whatever records are written to the file. | |
21552 | ||
21553 | @node Sequential_IO,Text_IO,Direct_IO,The Implementation of Standard I/O | |
73918baf | 21554 | @anchor{gnat_rm/the_implementation_of_standard_i_o id5}@anchor{2af}@anchor{gnat_rm/the_implementation_of_standard_i_o sequential-io}@anchor{2b0} |
64d5610f ML |
21555 | @section Sequential_IO |
21556 | ||
21557 | ||
21558 | Sequential_IO may be instantiated with either a definite (constrained) | |
21559 | or indefinite (unconstrained) type. | |
21560 | ||
21561 | For the definite type case, the elements written to the file are simply | |
21562 | the memory images of the data values with no control information of any | |
21563 | kind. The resulting file should be read using the same type, no validity | |
21564 | checking is performed on input. | |
21565 | ||
21566 | For the indefinite type case, the elements written consist of two | |
21567 | parts. First is the size of the data item, written as the memory image | |
21568 | of a @code{Interfaces.C.size_t} value, followed by the memory image of | |
21569 | the data value. The resulting file can only be read using the same | |
21570 | (unconstrained) type. Normal assignment checks are performed on these | |
21571 | read operations, and if these checks fail, @code{Data_Error} is | |
21572 | raised. In particular, in the array case, the lengths must match, and in | |
21573 | the variant record case, if the variable for a particular read operation | |
21574 | is constrained, the discriminants must match. | |
21575 | ||
21576 | Note that it is not possible to use Sequential_IO to write variable | |
21577 | length array items, and then read the data back into different length | |
21578 | arrays. For example, the following will raise @code{Data_Error}: | |
21579 | ||
21580 | @example | |
21581 | package IO is new Sequential_IO (String); | |
21582 | F : IO.File_Type; | |
21583 | S : String (1..4); | |
21584 | ... | |
21585 | IO.Create (F) | |
21586 | IO.Write (F, "hello!") | |
21587 | IO.Reset (F, Mode=>In_File); | |
21588 | IO.Read (F, S); | |
21589 | Put_Line (S); | |
21590 | @end example | |
21591 | ||
21592 | On some Ada implementations, this will print @code{hell}, but the program is | |
21593 | clearly incorrect, since there is only one element in the file, and that | |
21594 | element is the string @code{hello!}. | |
21595 | ||
21596 | In Ada 95 and Ada 2005, this kind of behavior can be legitimately achieved | |
21597 | using Stream_IO, and this is the preferred mechanism. In particular, the | |
21598 | above program fragment rewritten to use Stream_IO will work correctly. | |
21599 | ||
21600 | @node Text_IO,Wide_Text_IO,Sequential_IO,The Implementation of Standard I/O | |
73918baf | 21601 | @anchor{gnat_rm/the_implementation_of_standard_i_o id6}@anchor{2b1}@anchor{gnat_rm/the_implementation_of_standard_i_o text-io}@anchor{2b2} |
64d5610f ML |
21602 | @section Text_IO |
21603 | ||
21604 | ||
21605 | Text_IO files consist of a stream of characters containing the following | |
21606 | special control characters: | |
21607 | ||
21608 | @example | |
21609 | LF (line feed, 16#0A#) Line Mark | |
21610 | FF (form feed, 16#0C#) Page Mark | |
21611 | @end example | |
21612 | ||
21613 | A canonical Text_IO file is defined as one in which the following | |
21614 | conditions are met: | |
21615 | ||
21616 | ||
21617 | @itemize * | |
21618 | ||
21619 | @item | |
21620 | The character @code{LF} is used only as a line mark, i.e., to mark the end | |
21621 | of the line. | |
21622 | ||
21623 | @item | |
21624 | The character @code{FF} is used only as a page mark, i.e., to mark the | |
21625 | end of a page and consequently can appear only immediately following a | |
21626 | @code{LF} (line mark) character. | |
21627 | ||
21628 | @item | |
21629 | The file ends with either @code{LF} (line mark) or @code{LF}-@cite{FF} | |
21630 | (line mark, page mark). In the former case, the page mark is implicitly | |
21631 | assumed to be present. | |
21632 | @end itemize | |
21633 | ||
21634 | A file written using Text_IO will be in canonical form provided that no | |
21635 | explicit @code{LF} or @code{FF} characters are written using @code{Put} | |
21636 | or @code{Put_Line}. There will be no @code{FF} character at the end of | |
21637 | the file unless an explicit @code{New_Page} operation was performed | |
21638 | before closing the file. | |
21639 | ||
21640 | A canonical Text_IO file that is a regular file (i.e., not a device or a | |
21641 | pipe) can be read using any of the routines in Text_IO. The | |
21642 | semantics in this case will be exactly as defined in the Ada Reference | |
21643 | Manual, and all the routines in Text_IO are fully implemented. | |
21644 | ||
21645 | A text file that does not meet the requirements for a canonical Text_IO | |
21646 | file has one of the following: | |
21647 | ||
21648 | ||
21649 | @itemize * | |
21650 | ||
21651 | @item | |
21652 | The file contains @code{FF} characters not immediately following a | |
21653 | @code{LF} character. | |
21654 | ||
21655 | @item | |
21656 | The file contains @code{LF} or @code{FF} characters written by | |
21657 | @code{Put} or @code{Put_Line}, which are not logically considered to be | |
21658 | line marks or page marks. | |
21659 | ||
21660 | @item | |
21661 | The file ends in a character other than @code{LF} or @code{FF}, | |
21662 | i.e., there is no explicit line mark or page mark at the end of the file. | |
21663 | @end itemize | |
21664 | ||
21665 | Text_IO can be used to read such non-standard text files but subprograms | |
21666 | to do with line or page numbers do not have defined meanings. In | |
21667 | particular, a @code{FF} character that does not follow a @code{LF} | |
21668 | character may or may not be treated as a page mark from the point of | |
21669 | view of page and line numbering. Every @code{LF} character is considered | |
21670 | to end a line, and there is an implied @code{LF} character at the end of | |
21671 | the file. | |
21672 | ||
21673 | @menu | |
21674 | * Stream Pointer Positioning:: | |
21675 | * Reading and Writing Non-Regular Files:: | |
21676 | * Get_Immediate:: | |
21677 | * Treating Text_IO Files as Streams:: | |
21678 | * Text_IO Extensions:: | |
21679 | * Text_IO Facilities for Unbounded Strings:: | |
21680 | ||
21681 | @end menu | |
21682 | ||
21683 | @node Stream Pointer Positioning,Reading and Writing Non-Regular Files,,Text_IO | |
73918baf | 21684 | @anchor{gnat_rm/the_implementation_of_standard_i_o id7}@anchor{2b3}@anchor{gnat_rm/the_implementation_of_standard_i_o stream-pointer-positioning}@anchor{2b4} |
64d5610f ML |
21685 | @subsection Stream Pointer Positioning |
21686 | ||
21687 | ||
21688 | @code{Ada.Text_IO} has a definition of current position for a file that | |
21689 | is being read. No internal buffering occurs in Text_IO, and usually the | |
21690 | physical position in the stream used to implement the file corresponds | |
21691 | to this logical position defined by Text_IO. There are two exceptions: | |
21692 | ||
21693 | ||
21694 | @itemize * | |
21695 | ||
21696 | @item | |
21697 | After a call to @code{End_Of_Page} that returns @code{True}, the stream | |
21698 | is positioned past the @code{LF} (line mark) that precedes the page | |
21699 | mark. Text_IO maintains an internal flag so that subsequent read | |
21700 | operations properly handle the logical position which is unchanged by | |
21701 | the @code{End_Of_Page} call. | |
21702 | ||
21703 | @item | |
21704 | After a call to @code{End_Of_File} that returns @code{True}, if the | |
21705 | Text_IO file was positioned before the line mark at the end of file | |
21706 | before the call, then the logical position is unchanged, but the stream | |
21707 | is physically positioned right at the end of file (past the line mark, | |
21708 | and past a possible page mark following the line mark. Again Text_IO | |
21709 | maintains internal flags so that subsequent read operations properly | |
21710 | handle the logical position. | |
21711 | @end itemize | |
21712 | ||
21713 | These discrepancies have no effect on the observable behavior of | |
21714 | Text_IO, but if a single Ada stream is shared between a C program and | |
21715 | Ada program, or shared (using @code{shared=yes} in the form string) | |
21716 | between two Ada files, then the difference may be observable in some | |
21717 | situations. | |
21718 | ||
21719 | @node Reading and Writing Non-Regular Files,Get_Immediate,Stream Pointer Positioning,Text_IO | |
73918baf | 21720 | @anchor{gnat_rm/the_implementation_of_standard_i_o id8}@anchor{2b5}@anchor{gnat_rm/the_implementation_of_standard_i_o reading-and-writing-non-regular-files}@anchor{2b6} |
64d5610f ML |
21721 | @subsection Reading and Writing Non-Regular Files |
21722 | ||
21723 | ||
21724 | A non-regular file is a device (such as a keyboard), or a pipe. Text_IO | |
21725 | can be used for reading and writing. Writing is not affected and the | |
21726 | sequence of characters output is identical to the normal file case, but | |
21727 | for reading, the behavior of Text_IO is modified to avoid undesirable | |
21728 | look-ahead as follows: | |
21729 | ||
21730 | An input file that is not a regular file is considered to have no page | |
21731 | marks. Any @code{Ascii.FF} characters (the character normally used for a | |
21732 | page mark) appearing in the file are considered to be data | |
21733 | characters. In particular: | |
21734 | ||
21735 | ||
21736 | @itemize * | |
21737 | ||
21738 | @item | |
21739 | @code{Get_Line} and @code{Skip_Line} do not test for a page mark | |
21740 | following a line mark. If a page mark appears, it will be treated as a | |
21741 | data character. | |
21742 | ||
21743 | @item | |
21744 | This avoids the need to wait for an extra character to be typed or | |
21745 | entered from the pipe to complete one of these operations. | |
21746 | ||
21747 | @item | |
21748 | @code{End_Of_Page} always returns @code{False} | |
21749 | ||
21750 | @item | |
21751 | @code{End_Of_File} will return @code{False} if there is a page mark at | |
21752 | the end of the file. | |
21753 | @end itemize | |
21754 | ||
21755 | Output to non-regular files is the same as for regular files. Page marks | |
21756 | may be written to non-regular files using @code{New_Page}, but as noted | |
21757 | above they will not be treated as page marks on input if the output is | |
21758 | piped to another Ada program. | |
21759 | ||
21760 | Another important discrepancy when reading non-regular files is that the end | |
21761 | of file indication is not ‘sticky’. If an end of file is entered, e.g., by | |
21762 | pressing the @code{EOT} key, | |
21763 | then end of file | |
21764 | is signaled once (i.e., the test @code{End_Of_File} | |
21765 | will yield @code{True}, or a read will | |
21766 | raise @code{End_Error}), but then reading can resume | |
21767 | to read data past that end of | |
21768 | file indication, until another end of file indication is entered. | |
21769 | ||
21770 | @node Get_Immediate,Treating Text_IO Files as Streams,Reading and Writing Non-Regular Files,Text_IO | |
73918baf | 21771 | @anchor{gnat_rm/the_implementation_of_standard_i_o get-immediate}@anchor{2b7}@anchor{gnat_rm/the_implementation_of_standard_i_o id9}@anchor{2b8} |
64d5610f ML |
21772 | @subsection Get_Immediate |
21773 | ||
21774 | ||
21775 | @geindex Get_Immediate | |
21776 | ||
21777 | Get_Immediate returns the next character (including control characters) | |
21778 | from the input file. In particular, Get_Immediate will return LF or FF | |
21779 | characters used as line marks or page marks. Such operations leave the | |
21780 | file positioned past the control character, and it is thus not treated | |
21781 | as having its normal function. This means that page, line and column | |
21782 | counts after this kind of Get_Immediate call are set as though the mark | |
21783 | did not occur. In the case where a Get_Immediate leaves the file | |
21784 | positioned between the line mark and page mark (which is not normally | |
21785 | possible), it is undefined whether the FF character will be treated as a | |
21786 | page mark. | |
21787 | ||
21788 | @node Treating Text_IO Files as Streams,Text_IO Extensions,Get_Immediate,Text_IO | |
73918baf | 21789 | @anchor{gnat_rm/the_implementation_of_standard_i_o id10}@anchor{2b9}@anchor{gnat_rm/the_implementation_of_standard_i_o treating-text-io-files-as-streams}@anchor{2ba} |
64d5610f ML |
21790 | @subsection Treating Text_IO Files as Streams |
21791 | ||
21792 | ||
21793 | @geindex Stream files | |
21794 | ||
21795 | The package @code{Text_IO.Streams} allows a @code{Text_IO} file to be treated | |
21796 | as a stream. Data written to a @code{Text_IO} file in this stream mode is | |
21797 | binary data. If this binary data contains bytes 16#0A# (@code{LF}) or | |
21798 | 16#0C# (@code{FF}), the resulting file may have non-standard | |
21799 | format. Similarly if read operations are used to read from a Text_IO | |
21800 | file treated as a stream, then @code{LF} and @code{FF} characters may be | |
21801 | skipped and the effect is similar to that described above for | |
21802 | @code{Get_Immediate}. | |
21803 | ||
21804 | @node Text_IO Extensions,Text_IO Facilities for Unbounded Strings,Treating Text_IO Files as Streams,Text_IO | |
73918baf | 21805 | @anchor{gnat_rm/the_implementation_of_standard_i_o id11}@anchor{2bb}@anchor{gnat_rm/the_implementation_of_standard_i_o text-io-extensions}@anchor{2bc} |
64d5610f ML |
21806 | @subsection Text_IO Extensions |
21807 | ||
21808 | ||
21809 | @geindex Text_IO extensions | |
21810 | ||
21811 | A package GNAT.IO_Aux in the GNAT library provides some useful extensions | |
21812 | to the standard @code{Text_IO} package: | |
21813 | ||
21814 | ||
21815 | @itemize * | |
21816 | ||
21817 | @item | |
21818 | function File_Exists (Name : String) return Boolean; | |
21819 | Determines if a file of the given name exists. | |
21820 | ||
21821 | @item | |
21822 | function Get_Line return String; | |
21823 | Reads a string from the standard input file. The value returned is exactly | |
21824 | the length of the line that was read. | |
21825 | ||
21826 | @item | |
21827 | function Get_Line (File : Ada.Text_IO.File_Type) return String; | |
21828 | Similar, except that the parameter File specifies the file from which | |
21829 | the string is to be read. | |
21830 | @end itemize | |
21831 | ||
21832 | @node Text_IO Facilities for Unbounded Strings,,Text_IO Extensions,Text_IO | |
73918baf | 21833 | @anchor{gnat_rm/the_implementation_of_standard_i_o id12}@anchor{2bd}@anchor{gnat_rm/the_implementation_of_standard_i_o text-io-facilities-for-unbounded-strings}@anchor{2be} |
64d5610f ML |
21834 | @subsection Text_IO Facilities for Unbounded Strings |
21835 | ||
21836 | ||
21837 | @geindex Text_IO for unbounded strings | |
21838 | ||
21839 | @geindex Unbounded_String | |
21840 | @geindex Text_IO operations | |
21841 | ||
21842 | The package @code{Ada.Strings.Unbounded.Text_IO} | |
21843 | in library files @code{a-suteio.ads/adb} contains some GNAT-specific | |
21844 | subprograms useful for Text_IO operations on unbounded strings: | |
21845 | ||
21846 | ||
21847 | @itemize * | |
21848 | ||
21849 | @item | |
21850 | function Get_Line (File : File_Type) return Unbounded_String; | |
21851 | Reads a line from the specified file | |
21852 | and returns the result as an unbounded string. | |
21853 | ||
21854 | @item | |
21855 | procedure Put (File : File_Type; U : Unbounded_String); | |
21856 | Writes the value of the given unbounded string to the specified file | |
21857 | Similar to the effect of | |
21858 | @code{Put (To_String (U))} except that an extra copy is avoided. | |
21859 | ||
21860 | @item | |
21861 | procedure Put_Line (File : File_Type; U : Unbounded_String); | |
21862 | Writes the value of the given unbounded string to the specified file, | |
21863 | followed by a @code{New_Line}. | |
21864 | Similar to the effect of @code{Put_Line (To_String (U))} except | |
21865 | that an extra copy is avoided. | |
21866 | @end itemize | |
21867 | ||
21868 | In the above procedures, @code{File} is of type @code{Ada.Text_IO.File_Type} | |
21869 | and is optional. If the parameter is omitted, then the standard input or | |
21870 | output file is referenced as appropriate. | |
21871 | ||
21872 | The package @code{Ada.Strings.Wide_Unbounded.Wide_Text_IO} in library | |
21873 | files @code{a-swuwti.ads} and @code{a-swuwti.adb} provides similar extended | |
21874 | @code{Wide_Text_IO} functionality for unbounded wide strings. | |
21875 | ||
21876 | The package @code{Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO} in library | |
21877 | files @code{a-szuzti.ads} and @code{a-szuzti.adb} provides similar extended | |
21878 | @code{Wide_Wide_Text_IO} functionality for unbounded wide wide strings. | |
21879 | ||
21880 | @node Wide_Text_IO,Wide_Wide_Text_IO,Text_IO,The Implementation of Standard I/O | |
73918baf | 21881 | @anchor{gnat_rm/the_implementation_of_standard_i_o id13}@anchor{2bf}@anchor{gnat_rm/the_implementation_of_standard_i_o wide-text-io}@anchor{2c0} |
64d5610f ML |
21882 | @section Wide_Text_IO |
21883 | ||
21884 | ||
21885 | @code{Wide_Text_IO} is similar in most respects to Text_IO, except that | |
21886 | both input and output files may contain special sequences that represent | |
21887 | wide character values. The encoding scheme for a given file may be | |
21888 | specified using a FORM parameter: | |
21889 | ||
21890 | @example | |
21891 | WCEM=`x` | |
21892 | @end example | |
21893 | ||
21894 | as part of the FORM string (WCEM = wide character encoding method), | |
21895 | where @code{x} is one of the following characters | |
21896 | ||
21897 | ||
21898 | @multitable {xxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxx} | |
21899 | @headitem | |
21900 | ||
21901 | Character | |
21902 | ||
21903 | @tab | |
21904 | ||
21905 | Encoding | |
21906 | ||
21907 | @item | |
21908 | ||
21909 | `h' | |
21910 | ||
21911 | @tab | |
21912 | ||
21913 | Hex ESC encoding | |
21914 | ||
21915 | @item | |
21916 | ||
21917 | `u' | |
21918 | ||
21919 | @tab | |
21920 | ||
21921 | Upper half encoding | |
21922 | ||
21923 | @item | |
21924 | ||
21925 | `s' | |
21926 | ||
21927 | @tab | |
21928 | ||
21929 | Shift-JIS encoding | |
21930 | ||
21931 | @item | |
21932 | ||
21933 | `e' | |
21934 | ||
21935 | @tab | |
21936 | ||
21937 | EUC Encoding | |
21938 | ||
21939 | @item | |
21940 | ||
21941 | `8' | |
21942 | ||
21943 | @tab | |
21944 | ||
21945 | UTF-8 encoding | |
21946 | ||
21947 | @item | |
21948 | ||
21949 | `b' | |
21950 | ||
21951 | @tab | |
21952 | ||
21953 | Brackets encoding | |
21954 | ||
21955 | @end multitable | |
21956 | ||
21957 | ||
21958 | The encoding methods match those that | |
21959 | can be used in a source | |
21960 | program, but there is no requirement that the encoding method used for | |
21961 | the source program be the same as the encoding method used for files, | |
21962 | and different files may use different encoding methods. | |
21963 | ||
21964 | The default encoding method for the standard files, and for opened files | |
21965 | for which no WCEM parameter is given in the FORM string matches the | |
21966 | wide character encoding specified for the main program (the default | |
21967 | being brackets encoding if no coding method was specified with -gnatW). | |
21968 | ||
21969 | ||
21970 | @table @asis | |
21971 | ||
21972 | @item `Hex Coding' | |
21973 | ||
21974 | In this encoding, a wide character is represented by a five character | |
21975 | sequence: | |
21976 | @end table | |
21977 | ||
21978 | @example | |
21979 | ESC a b c d | |
21980 | @end example | |
21981 | ||
21982 | ||
21983 | @quotation | |
21984 | ||
21985 | where @code{a}, @code{b}, @code{c}, @code{d} are the four hexadecimal | |
21986 | characters (using upper case letters) of the wide character code. For | |
21987 | example, ESC A345 is used to represent the wide character with code | |
21988 | 16#A345#. This scheme is compatible with use of the full | |
21989 | @code{Wide_Character} set. | |
21990 | @end quotation | |
21991 | ||
21992 | ||
21993 | @table @asis | |
21994 | ||
21995 | @item `Upper Half Coding' | |
21996 | ||
21997 | The wide character with encoding 16#abcd#, where the upper bit is on | |
21998 | (i.e., a is in the range 8-F) is represented as two bytes 16#ab# and | |
21999 | 16#cd#. The second byte may never be a format control character, but is | |
22000 | not required to be in the upper half. This method can be also used for | |
22001 | shift-JIS or EUC where the internal coding matches the external coding. | |
22002 | ||
22003 | @item `Shift JIS Coding' | |
22004 | ||
22005 | A wide character is represented by a two character sequence 16#ab# and | |
22006 | 16#cd#, with the restrictions described for upper half encoding as | |
22007 | described above. The internal character code is the corresponding JIS | |
22008 | character according to the standard algorithm for Shift-JIS | |
22009 | conversion. Only characters defined in the JIS code set table can be | |
22010 | used with this encoding method. | |
22011 | ||
22012 | @item `EUC Coding' | |
22013 | ||
22014 | A wide character is represented by a two character sequence 16#ab# and | |
22015 | 16#cd#, with both characters being in the upper half. The internal | |
22016 | character code is the corresponding JIS character according to the EUC | |
22017 | encoding algorithm. Only characters defined in the JIS code set table | |
22018 | can be used with this encoding method. | |
22019 | ||
22020 | @item `UTF-8 Coding' | |
22021 | ||
22022 | A wide character is represented using | |
22023 | UCS Transformation Format 8 (UTF-8) as defined in Annex R of ISO | |
22024 | 10646-1/Am.2. Depending on the character value, the representation | |
22025 | is a one, two, or three byte sequence: | |
22026 | @end table | |
22027 | ||
22028 | @example | |
22029 | 16#0000#-16#007f#: 2#0xxxxxxx# | |
22030 | 16#0080#-16#07ff#: 2#110xxxxx# 2#10xxxxxx# | |
22031 | 16#0800#-16#ffff#: 2#1110xxxx# 2#10xxxxxx# 2#10xxxxxx# | |
22032 | @end example | |
22033 | ||
22034 | ||
22035 | @quotation | |
22036 | ||
22037 | where the @code{xxx} bits correspond to the left-padded bits of the | |
22038 | 16-bit character value. Note that all lower half ASCII characters | |
22039 | are represented as ASCII bytes and all upper half characters and | |
22040 | other wide characters are represented as sequences of upper-half | |
22041 | (The full UTF-8 scheme allows for encoding 31-bit characters as | |
22042 | 6-byte sequences, but in this implementation, all UTF-8 sequences | |
22043 | of four or more bytes length will raise a Constraint_Error, as | |
22044 | will all invalid UTF-8 sequences.) | |
22045 | @end quotation | |
22046 | ||
22047 | ||
22048 | @table @asis | |
22049 | ||
22050 | @item `Brackets Coding' | |
22051 | ||
22052 | In this encoding, a wide character is represented by the following eight | |
22053 | character sequence: | |
22054 | @end table | |
22055 | ||
22056 | @example | |
22057 | [ " a b c d " ] | |
22058 | @end example | |
22059 | ||
22060 | ||
22061 | @quotation | |
22062 | ||
22063 | where @code{a}, @code{b}, @code{c}, @code{d} are the four hexadecimal | |
22064 | characters (using uppercase letters) of the wide character code. For | |
22065 | example, @code{["A345"]} is used to represent the wide character with code | |
22066 | @code{16#A345#}. | |
22067 | This scheme is compatible with use of the full Wide_Character set. | |
22068 | On input, brackets coding can also be used for upper half characters, | |
22069 | e.g., @code{["C1"]} for lower case a. However, on output, brackets notation | |
22070 | is only used for wide characters with a code greater than @code{16#FF#}. | |
22071 | ||
22072 | Note that brackets coding is not normally used in the context of | |
22073 | Wide_Text_IO or Wide_Wide_Text_IO, since it is really just designed as | |
22074 | a portable way of encoding source files. In the context of Wide_Text_IO | |
22075 | or Wide_Wide_Text_IO, it can only be used if the file does not contain | |
22076 | any instance of the left bracket character other than to encode wide | |
22077 | character values using the brackets encoding method. In practice it is | |
22078 | expected that some standard wide character encoding method such | |
22079 | as UTF-8 will be used for text input output. | |
22080 | ||
22081 | If brackets notation is used, then any occurrence of a left bracket | |
22082 | in the input file which is not the start of a valid wide character | |
22083 | sequence will cause Constraint_Error to be raised. It is possible to | |
22084 | encode a left bracket as [“5B”] and Wide_Text_IO and Wide_Wide_Text_IO | |
22085 | input will interpret this as a left bracket. | |
22086 | ||
22087 | However, when a left bracket is output, it will be output as a left bracket | |
22088 | and not as [“5B”]. We make this decision because for normal use of | |
22089 | Wide_Text_IO for outputting messages, it is unpleasant to clobber left | |
22090 | brackets. For example, if we write: | |
22091 | ||
22092 | @example | |
22093 | Put_Line ("Start of output [first run]"); | |
22094 | @end example | |
22095 | ||
22096 | we really do not want to have the left bracket in this message clobbered so | |
22097 | that the output reads: | |
22098 | @end quotation | |
22099 | ||
22100 | @example | |
22101 | Start of output ["5B"]first run] | |
22102 | @end example | |
22103 | ||
22104 | ||
22105 | @quotation | |
22106 | ||
22107 | In practice brackets encoding is reasonably useful for normal Put_Line use | |
22108 | since we won’t get confused between left brackets and wide character | |
22109 | sequences in the output. But for input, or when files are written out | |
22110 | and read back in, it really makes better sense to use one of the standard | |
22111 | encoding methods such as UTF-8. | |
22112 | @end quotation | |
22113 | ||
22114 | For the coding schemes other than UTF-8, Hex, or Brackets encoding, | |
22115 | not all wide character | |
22116 | values can be represented. An attempt to output a character that cannot | |
22117 | be represented using the encoding scheme for the file causes | |
22118 | Constraint_Error to be raised. An invalid wide character sequence on | |
22119 | input also causes Constraint_Error to be raised. | |
22120 | ||
22121 | @menu | |
22122 | * Stream Pointer Positioning: Stream Pointer Positioning<2>. | |
22123 | * Reading and Writing Non-Regular Files: Reading and Writing Non-Regular Files<2>. | |
22124 | ||
22125 | @end menu | |
22126 | ||
22127 | @node Stream Pointer Positioning<2>,Reading and Writing Non-Regular Files<2>,,Wide_Text_IO | |
73918baf | 22128 | @anchor{gnat_rm/the_implementation_of_standard_i_o id14}@anchor{2c1}@anchor{gnat_rm/the_implementation_of_standard_i_o stream-pointer-positioning-1}@anchor{2c2} |
64d5610f ML |
22129 | @subsection Stream Pointer Positioning |
22130 | ||
22131 | ||
22132 | @code{Ada.Wide_Text_IO} is similar to @code{Ada.Text_IO} in its handling | |
73918baf | 22133 | of stream pointer positioning (@ref{2b2,,Text_IO}). There is one additional |
64d5610f ML |
22134 | case: |
22135 | ||
22136 | If @code{Ada.Wide_Text_IO.Look_Ahead} reads a character outside the | |
22137 | normal lower ASCII set, i.e. a character in the range: | |
22138 | ||
22139 | @example | |
22140 | Wide_Character'Val (16#0080#) .. Wide_Character'Val (16#FFFF#) | |
22141 | @end example | |
22142 | ||
22143 | then although the logical position of the file pointer is unchanged by | |
22144 | the @code{Look_Ahead} call, the stream is physically positioned past the | |
22145 | wide character sequence. Again this is to avoid the need for buffering | |
22146 | or backup, and all @code{Wide_Text_IO} routines check the internal | |
22147 | indication that this situation has occurred so that this is not visible | |
22148 | to a normal program using @code{Wide_Text_IO}. However, this discrepancy | |
22149 | can be observed if the wide text file shares a stream with another file. | |
22150 | ||
22151 | @node Reading and Writing Non-Regular Files<2>,,Stream Pointer Positioning<2>,Wide_Text_IO | |
73918baf | 22152 | @anchor{gnat_rm/the_implementation_of_standard_i_o id15}@anchor{2c3}@anchor{gnat_rm/the_implementation_of_standard_i_o reading-and-writing-non-regular-files-1}@anchor{2c4} |
64d5610f ML |
22153 | @subsection Reading and Writing Non-Regular Files |
22154 | ||
22155 | ||
22156 | As in the case of Text_IO, when a non-regular file is read, it is | |
22157 | assumed that the file contains no page marks (any form characters are | |
22158 | treated as data characters), and @code{End_Of_Page} always returns | |
22159 | @code{False}. Similarly, the end of file indication is not sticky, so | |
22160 | it is possible to read beyond an end of file. | |
22161 | ||
22162 | @node Wide_Wide_Text_IO,Stream_IO,Wide_Text_IO,The Implementation of Standard I/O | |
73918baf | 22163 | @anchor{gnat_rm/the_implementation_of_standard_i_o id16}@anchor{2c5}@anchor{gnat_rm/the_implementation_of_standard_i_o wide-wide-text-io}@anchor{2c6} |
64d5610f ML |
22164 | @section Wide_Wide_Text_IO |
22165 | ||
22166 | ||
22167 | @code{Wide_Wide_Text_IO} is similar in most respects to Text_IO, except that | |
22168 | both input and output files may contain special sequences that represent | |
22169 | wide wide character values. The encoding scheme for a given file may be | |
22170 | specified using a FORM parameter: | |
22171 | ||
22172 | @example | |
22173 | WCEM=`x` | |
22174 | @end example | |
22175 | ||
22176 | as part of the FORM string (WCEM = wide character encoding method), | |
22177 | where @code{x} is one of the following characters | |
22178 | ||
22179 | ||
22180 | @multitable {xxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxx} | |
22181 | @headitem | |
22182 | ||
22183 | Character | |
22184 | ||
22185 | @tab | |
22186 | ||
22187 | Encoding | |
22188 | ||
22189 | @item | |
22190 | ||
22191 | `h' | |
22192 | ||
22193 | @tab | |
22194 | ||
22195 | Hex ESC encoding | |
22196 | ||
22197 | @item | |
22198 | ||
22199 | `u' | |
22200 | ||
22201 | @tab | |
22202 | ||
22203 | Upper half encoding | |
22204 | ||
22205 | @item | |
22206 | ||
22207 | `s' | |
22208 | ||
22209 | @tab | |
22210 | ||
22211 | Shift-JIS encoding | |
22212 | ||
22213 | @item | |
22214 | ||
22215 | `e' | |
22216 | ||
22217 | @tab | |
22218 | ||
22219 | EUC Encoding | |
22220 | ||
22221 | @item | |
22222 | ||
22223 | `8' | |
22224 | ||
22225 | @tab | |
22226 | ||
22227 | UTF-8 encoding | |
22228 | ||
22229 | @item | |
22230 | ||
22231 | `b' | |
22232 | ||
22233 | @tab | |
22234 | ||
22235 | Brackets encoding | |
22236 | ||
22237 | @end multitable | |
22238 | ||
22239 | ||
22240 | The encoding methods match those that | |
22241 | can be used in a source | |
22242 | program, but there is no requirement that the encoding method used for | |
22243 | the source program be the same as the encoding method used for files, | |
22244 | and different files may use different encoding methods. | |
22245 | ||
22246 | The default encoding method for the standard files, and for opened files | |
22247 | for which no WCEM parameter is given in the FORM string matches the | |
22248 | wide character encoding specified for the main program (the default | |
22249 | being brackets encoding if no coding method was specified with -gnatW). | |
22250 | ||
22251 | ||
22252 | @table @asis | |
22253 | ||
22254 | @item `UTF-8 Coding' | |
22255 | ||
22256 | A wide character is represented using | |
22257 | UCS Transformation Format 8 (UTF-8) as defined in Annex R of ISO | |
22258 | 10646-1/Am.2. Depending on the character value, the representation | |
22259 | is a one, two, three, or four byte sequence: | |
22260 | @end table | |
22261 | ||
22262 | @example | |
22263 | 16#000000#-16#00007f#: 2#0xxxxxxx# | |
22264 | 16#000080#-16#0007ff#: 2#110xxxxx# 2#10xxxxxx# | |
22265 | 16#000800#-16#00ffff#: 2#1110xxxx# 2#10xxxxxx# 2#10xxxxxx# | |
22266 | 16#010000#-16#10ffff#: 2#11110xxx# 2#10xxxxxx# 2#10xxxxxx# 2#10xxxxxx# | |
22267 | @end example | |
22268 | ||
22269 | ||
22270 | @quotation | |
22271 | ||
22272 | where the @code{xxx} bits correspond to the left-padded bits of the | |
22273 | 21-bit character value. Note that all lower half ASCII characters | |
22274 | are represented as ASCII bytes and all upper half characters and | |
22275 | other wide characters are represented as sequences of upper-half | |
22276 | characters. | |
22277 | @end quotation | |
22278 | ||
22279 | ||
22280 | @table @asis | |
22281 | ||
22282 | @item `Brackets Coding' | |
22283 | ||
22284 | In this encoding, a wide wide character is represented by the following eight | |
22285 | character sequence if is in wide character range | |
22286 | @end table | |
22287 | ||
22288 | @example | |
22289 | [ " a b c d " ] | |
22290 | @end example | |
22291 | ||
22292 | ||
22293 | @quotation | |
22294 | ||
22295 | and by the following ten character sequence if not | |
22296 | @end quotation | |
22297 | ||
22298 | @example | |
22299 | [ " a b c d e f " ] | |
22300 | @end example | |
22301 | ||
22302 | ||
22303 | @quotation | |
22304 | ||
22305 | where @code{a}, @code{b}, @code{c}, @code{d}, @code{e}, and @code{f} | |
22306 | are the four or six hexadecimal | |
22307 | characters (using uppercase letters) of the wide wide character code. For | |
22308 | example, @code{["01A345"]} is used to represent the wide wide character | |
22309 | with code @code{16#01A345#}. | |
22310 | ||
22311 | This scheme is compatible with use of the full Wide_Wide_Character set. | |
22312 | On input, brackets coding can also be used for upper half characters, | |
22313 | e.g., @code{["C1"]} for lower case a. However, on output, brackets notation | |
22314 | is only used for wide characters with a code greater than @code{16#FF#}. | |
22315 | @end quotation | |
22316 | ||
22317 | If is also possible to use the other Wide_Character encoding methods, | |
22318 | such as Shift-JIS, but the other schemes cannot support the full range | |
22319 | of wide wide characters. | |
22320 | An attempt to output a character that cannot | |
22321 | be represented using the encoding scheme for the file causes | |
22322 | Constraint_Error to be raised. An invalid wide character sequence on | |
22323 | input also causes Constraint_Error to be raised. | |
22324 | ||
22325 | @menu | |
22326 | * Stream Pointer Positioning: Stream Pointer Positioning<3>. | |
22327 | * Reading and Writing Non-Regular Files: Reading and Writing Non-Regular Files<3>. | |
22328 | ||
22329 | @end menu | |
22330 | ||
22331 | @node Stream Pointer Positioning<3>,Reading and Writing Non-Regular Files<3>,,Wide_Wide_Text_IO | |
73918baf | 22332 | @anchor{gnat_rm/the_implementation_of_standard_i_o id17}@anchor{2c7}@anchor{gnat_rm/the_implementation_of_standard_i_o stream-pointer-positioning-2}@anchor{2c8} |
64d5610f ML |
22333 | @subsection Stream Pointer Positioning |
22334 | ||
22335 | ||
22336 | @code{Ada.Wide_Wide_Text_IO} is similar to @code{Ada.Text_IO} in its handling | |
73918baf | 22337 | of stream pointer positioning (@ref{2b2,,Text_IO}). There is one additional |
64d5610f ML |
22338 | case: |
22339 | ||
22340 | If @code{Ada.Wide_Wide_Text_IO.Look_Ahead} reads a character outside the | |
22341 | normal lower ASCII set, i.e. a character in the range: | |
22342 | ||
22343 | @example | |
22344 | Wide_Wide_Character'Val (16#0080#) .. Wide_Wide_Character'Val (16#10FFFF#) | |
22345 | @end example | |
22346 | ||
22347 | then although the logical position of the file pointer is unchanged by | |
22348 | the @code{Look_Ahead} call, the stream is physically positioned past the | |
22349 | wide character sequence. Again this is to avoid the need for buffering | |
22350 | or backup, and all @code{Wide_Wide_Text_IO} routines check the internal | |
22351 | indication that this situation has occurred so that this is not visible | |
22352 | to a normal program using @code{Wide_Wide_Text_IO}. However, this discrepancy | |
22353 | can be observed if the wide text file shares a stream with another file. | |
22354 | ||
22355 | @node Reading and Writing Non-Regular Files<3>,,Stream Pointer Positioning<3>,Wide_Wide_Text_IO | |
73918baf | 22356 | @anchor{gnat_rm/the_implementation_of_standard_i_o id18}@anchor{2c9}@anchor{gnat_rm/the_implementation_of_standard_i_o reading-and-writing-non-regular-files-2}@anchor{2ca} |
64d5610f ML |
22357 | @subsection Reading and Writing Non-Regular Files |
22358 | ||
22359 | ||
22360 | As in the case of Text_IO, when a non-regular file is read, it is | |
22361 | assumed that the file contains no page marks (any form characters are | |
22362 | treated as data characters), and @code{End_Of_Page} always returns | |
22363 | @code{False}. Similarly, the end of file indication is not sticky, so | |
22364 | it is possible to read beyond an end of file. | |
22365 | ||
22366 | @node Stream_IO,Text Translation,Wide_Wide_Text_IO,The Implementation of Standard I/O | |
73918baf | 22367 | @anchor{gnat_rm/the_implementation_of_standard_i_o id19}@anchor{2cb}@anchor{gnat_rm/the_implementation_of_standard_i_o stream-io}@anchor{2cc} |
64d5610f ML |
22368 | @section Stream_IO |
22369 | ||
22370 | ||
22371 | A stream file is a sequence of bytes, where individual elements are | |
22372 | written to the file as described in the Ada Reference Manual. The type | |
22373 | @code{Stream_Element} is simply a byte. There are two ways to read or | |
22374 | write a stream file. | |
22375 | ||
22376 | ||
22377 | @itemize * | |
22378 | ||
22379 | @item | |
22380 | The operations @code{Read} and @code{Write} directly read or write a | |
22381 | sequence of stream elements with no control information. | |
22382 | ||
22383 | @item | |
22384 | The stream attributes applied to a stream file transfer data in the | |
22385 | manner described for stream attributes. | |
22386 | @end itemize | |
22387 | ||
22388 | @node Text Translation,Shared Files,Stream_IO,The Implementation of Standard I/O | |
73918baf | 22389 | @anchor{gnat_rm/the_implementation_of_standard_i_o id20}@anchor{2cd}@anchor{gnat_rm/the_implementation_of_standard_i_o text-translation}@anchor{2ce} |
64d5610f ML |
22390 | @section Text Translation |
22391 | ||
22392 | ||
22393 | @code{Text_Translation=xxx} may be used as the Form parameter | |
22394 | passed to Text_IO.Create and Text_IO.Open. @code{Text_Translation=xxx} | |
22395 | has no effect on Unix systems. Possible values are: | |
22396 | ||
22397 | ||
22398 | @itemize * | |
22399 | ||
22400 | @item | |
22401 | @code{Yes} or @code{Text} is the default, which means to | |
22402 | translate LF to/from CR/LF on Windows systems. | |
22403 | ||
22404 | @code{No} disables this translation; i.e. it | |
22405 | uses binary mode. For output files, @code{Text_Translation=No} | |
22406 | may be used to create Unix-style files on | |
22407 | Windows. | |
22408 | ||
22409 | @item | |
22410 | @code{wtext} translation enabled in Unicode mode. | |
22411 | (corresponds to _O_WTEXT). | |
22412 | ||
22413 | @item | |
22414 | @code{u8text} translation enabled in Unicode UTF-8 mode. | |
22415 | (corresponds to O_U8TEXT). | |
22416 | ||
22417 | @item | |
22418 | @code{u16text} translation enabled in Unicode UTF-16 | |
22419 | mode. (corresponds to_O_U16TEXT). | |
22420 | @end itemize | |
22421 | ||
22422 | @node Shared Files,Filenames encoding,Text Translation,The Implementation of Standard I/O | |
73918baf | 22423 | @anchor{gnat_rm/the_implementation_of_standard_i_o id21}@anchor{2cf}@anchor{gnat_rm/the_implementation_of_standard_i_o shared-files}@anchor{2d0} |
64d5610f ML |
22424 | @section Shared Files |
22425 | ||
22426 | ||
22427 | Section A.14 of the Ada Reference Manual allows implementations to | |
22428 | provide a wide variety of behavior if an attempt is made to access the | |
22429 | same external file with two or more internal files. | |
22430 | ||
22431 | To provide a full range of functionality, while at the same time | |
22432 | minimizing the problems of portability caused by this implementation | |
22433 | dependence, GNAT handles file sharing as follows: | |
22434 | ||
22435 | ||
22436 | @itemize * | |
22437 | ||
22438 | @item | |
22439 | In the absence of a @code{shared=xxx} form parameter, an attempt | |
22440 | to open two or more files with the same full name is considered an error | |
22441 | and is not supported. The exception @code{Use_Error} will be | |
22442 | raised. Note that a file that is not explicitly closed by the program | |
22443 | remains open until the program terminates. | |
22444 | ||
22445 | @item | |
22446 | If the form parameter @code{shared=no} appears in the form string, the | |
22447 | file can be opened or created with its own separate stream identifier, | |
22448 | regardless of whether other files sharing the same external file are | |
22449 | opened. The exact effect depends on how the C stream routines handle | |
22450 | multiple accesses to the same external files using separate streams. | |
22451 | ||
22452 | @item | |
22453 | If the form parameter @code{shared=yes} appears in the form string for | |
22454 | each of two or more files opened using the same full name, the same | |
22455 | stream is shared between these files, and the semantics are as described | |
22456 | in Ada Reference Manual, Section A.14. | |
22457 | @end itemize | |
22458 | ||
22459 | When a program that opens multiple files with the same name is ported | |
22460 | from another Ada compiler to GNAT, the effect will be that | |
22461 | @code{Use_Error} is raised. | |
22462 | ||
22463 | The documentation of the original compiler and the documentation of the | |
22464 | program should then be examined to determine if file sharing was | |
22465 | expected, and @code{shared=xxx} parameters added to @code{Open} | |
22466 | and @code{Create} calls as required. | |
22467 | ||
22468 | When a program is ported from GNAT to some other Ada compiler, no | |
22469 | special attention is required unless the @code{shared=xxx} form | |
22470 | parameter is used in the program. In this case, you must examine the | |
22471 | documentation of the new compiler to see if it supports the required | |
22472 | file sharing semantics, and form strings modified appropriately. Of | |
22473 | course it may be the case that the program cannot be ported if the | |
22474 | target compiler does not support the required functionality. The best | |
22475 | approach in writing portable code is to avoid file sharing (and hence | |
22476 | the use of the @code{shared=xxx} parameter in the form string) | |
22477 | completely. | |
22478 | ||
22479 | One common use of file sharing in Ada 83 is the use of instantiations of | |
22480 | Sequential_IO on the same file with different types, to achieve | |
22481 | heterogeneous input-output. Although this approach will work in GNAT if | |
22482 | @code{shared=yes} is specified, it is preferable in Ada to use Stream_IO | |
22483 | for this purpose (using the stream attributes) | |
22484 | ||
22485 | @node Filenames encoding,File content encoding,Shared Files,The Implementation of Standard I/O | |
73918baf | 22486 | @anchor{gnat_rm/the_implementation_of_standard_i_o filenames-encoding}@anchor{2d1}@anchor{gnat_rm/the_implementation_of_standard_i_o id22}@anchor{2d2} |
64d5610f ML |
22487 | @section Filenames encoding |
22488 | ||
22489 | ||
22490 | An encoding form parameter can be used to specify the filename | |
22491 | encoding @code{encoding=xxx}. | |
22492 | ||
22493 | ||
22494 | @itemize * | |
22495 | ||
22496 | @item | |
22497 | If the form parameter @code{encoding=utf8} appears in the form string, the | |
22498 | filename must be encoded in UTF-8. | |
22499 | ||
22500 | @item | |
22501 | If the form parameter @code{encoding=8bits} appears in the form | |
22502 | string, the filename must be a standard 8bits string. | |
22503 | @end itemize | |
22504 | ||
22505 | In the absence of a @code{encoding=xxx} form parameter, the | |
22506 | encoding is controlled by the @code{GNAT_CODE_PAGE} environment | |
22507 | variable. And if not set @code{utf8} is assumed. | |
22508 | ||
22509 | ||
22510 | @table @asis | |
22511 | ||
22512 | @item `CP_ACP' | |
22513 | ||
22514 | The current system Windows ANSI code page. | |
22515 | ||
22516 | @item `CP_UTF8' | |
22517 | ||
22518 | UTF-8 encoding | |
22519 | @end table | |
22520 | ||
22521 | This encoding form parameter is only supported on the Windows | |
22522 | platform. On the other Operating Systems the run-time is supporting | |
22523 | UTF-8 natively. | |
22524 | ||
22525 | @node File content encoding,Open Modes,Filenames encoding,The Implementation of Standard I/O | |
73918baf | 22526 | @anchor{gnat_rm/the_implementation_of_standard_i_o file-content-encoding}@anchor{2d3}@anchor{gnat_rm/the_implementation_of_standard_i_o id23}@anchor{2d4} |
64d5610f ML |
22527 | @section File content encoding |
22528 | ||
22529 | ||
22530 | For text files it is possible to specify the encoding to use. This is | |
22531 | controlled by the by the @code{GNAT_CCS_ENCODING} environment | |
22532 | variable. And if not set @code{TEXT} is assumed. | |
22533 | ||
22534 | The possible values are those supported on Windows: | |
22535 | ||
22536 | ||
22537 | @table @asis | |
22538 | ||
22539 | @item `TEXT' | |
22540 | ||
22541 | Translated text mode | |
22542 | ||
22543 | @item `WTEXT' | |
22544 | ||
22545 | Translated unicode encoding | |
22546 | ||
22547 | @item `U16TEXT' | |
22548 | ||
22549 | Unicode 16-bit encoding | |
22550 | ||
22551 | @item `U8TEXT' | |
22552 | ||
22553 | Unicode 8-bit encoding | |
22554 | @end table | |
22555 | ||
22556 | This encoding is only supported on the Windows platform. | |
22557 | ||
22558 | @node Open Modes,Operations on C Streams,File content encoding,The Implementation of Standard I/O | |
73918baf | 22559 | @anchor{gnat_rm/the_implementation_of_standard_i_o id24}@anchor{2d5}@anchor{gnat_rm/the_implementation_of_standard_i_o open-modes}@anchor{2d6} |
64d5610f ML |
22560 | @section Open Modes |
22561 | ||
22562 | ||
22563 | @code{Open} and @code{Create} calls result in a call to @code{fopen} | |
22564 | using the mode shown in the following table: | |
22565 | ||
22566 | ||
22567 | @multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxx} | |
22568 | @headitem | |
22569 | ||
22570 | @code{Open} and @code{Create} Call Modes | |
22571 | ||
22572 | @tab | |
22573 | ||
22574 | @tab | |
22575 | ||
22576 | @item | |
22577 | ||
22578 | @tab | |
22579 | ||
22580 | `OPEN' | |
22581 | ||
22582 | @tab | |
22583 | ||
22584 | `CREATE' | |
22585 | ||
22586 | @item | |
22587 | ||
22588 | Append_File | |
22589 | ||
22590 | @tab | |
22591 | ||
22592 | “r+” | |
22593 | ||
22594 | @tab | |
22595 | ||
22596 | “w+” | |
22597 | ||
22598 | @item | |
22599 | ||
22600 | In_File | |
22601 | ||
22602 | @tab | |
22603 | ||
22604 | “r” | |
22605 | ||
22606 | @tab | |
22607 | ||
22608 | “w+” | |
22609 | ||
22610 | @item | |
22611 | ||
22612 | Out_File (Direct_IO) | |
22613 | ||
22614 | @tab | |
22615 | ||
22616 | “r+” | |
22617 | ||
22618 | @tab | |
22619 | ||
22620 | “w” | |
22621 | ||
22622 | @item | |
22623 | ||
22624 | Out_File (all other cases) | |
22625 | ||
22626 | @tab | |
22627 | ||
22628 | “w” | |
22629 | ||
22630 | @tab | |
22631 | ||
22632 | “w” | |
22633 | ||
22634 | @item | |
22635 | ||
22636 | Inout_File | |
22637 | ||
22638 | @tab | |
22639 | ||
22640 | “r+” | |
22641 | ||
22642 | @tab | |
22643 | ||
22644 | “w+” | |
22645 | ||
22646 | @end multitable | |
22647 | ||
22648 | ||
22649 | If text file translation is required, then either @code{b} or @code{t} | |
22650 | is added to the mode, depending on the setting of Text. Text file | |
22651 | translation refers to the mapping of CR/LF sequences in an external file | |
22652 | to LF characters internally. This mapping only occurs in DOS and | |
22653 | DOS-like systems, and is not relevant to other systems. | |
22654 | ||
22655 | A special case occurs with Stream_IO. As shown in the above table, the | |
22656 | file is initially opened in @code{r} or @code{w} mode for the | |
22657 | @code{In_File} and @code{Out_File} cases. If a @code{Set_Mode} operation | |
22658 | subsequently requires switching from reading to writing or vice-versa, | |
22659 | then the file is reopened in @code{r+} mode to permit the required operation. | |
22660 | ||
22661 | @node Operations on C Streams,Interfacing to C Streams,Open Modes,The Implementation of Standard I/O | |
73918baf | 22662 | @anchor{gnat_rm/the_implementation_of_standard_i_o id25}@anchor{2d7}@anchor{gnat_rm/the_implementation_of_standard_i_o operations-on-c-streams}@anchor{2d8} |
64d5610f ML |
22663 | @section Operations on C Streams |
22664 | ||
22665 | ||
22666 | The package @code{Interfaces.C_Streams} provides an Ada program with direct | |
22667 | access to the C library functions for operations on C streams: | |
22668 | ||
22669 | @example | |
22670 | package Interfaces.C_Streams is | |
22671 | -- Note: the reason we do not use the types that are in | |
22672 | -- Interfaces.C is that we want to avoid dragging in the | |
22673 | -- code in this unit if possible. | |
22674 | subtype chars is System.Address; | |
22675 | -- Pointer to null-terminated array of characters | |
22676 | subtype FILEs is System.Address; | |
22677 | -- Corresponds to the C type FILE* | |
22678 | subtype voids is System.Address; | |
22679 | -- Corresponds to the C type void* | |
22680 | subtype int is Integer; | |
22681 | subtype long is Long_Integer; | |
22682 | -- Note: the above types are subtypes deliberately, and it | |
22683 | -- is part of this spec that the above correspondences are | |
22684 | -- guaranteed. This means that it is legitimate to, for | |
22685 | -- example, use Integer instead of int. We provide these | |
22686 | -- synonyms for clarity, but in some cases it may be | |
22687 | -- convenient to use the underlying types (for example to | |
22688 | -- avoid an unnecessary dependency of a spec on the spec | |
22689 | -- of this unit). | |
22690 | type size_t is mod 2 ** Standard'Address_Size; | |
22691 | NULL_Stream : constant FILEs; | |
22692 | -- Value returned (NULL in C) to indicate an | |
22693 | -- fdopen/fopen/tmpfile error | |
22694 | ---------------------------------- | |
22695 | -- Constants Defined in stdio.h -- | |
22696 | ---------------------------------- | |
22697 | EOF : constant int; | |
22698 | -- Used by a number of routines to indicate error or | |
22699 | -- end of file | |
22700 | IOFBF : constant int; | |
22701 | IOLBF : constant int; | |
22702 | IONBF : constant int; | |
22703 | -- Used to indicate buffering mode for setvbuf call | |
22704 | SEEK_CUR : constant int; | |
22705 | SEEK_END : constant int; | |
22706 | SEEK_SET : constant int; | |
22707 | -- Used to indicate origin for fseek call | |
22708 | function stdin return FILEs; | |
22709 | function stdout return FILEs; | |
22710 | function stderr return FILEs; | |
22711 | -- Streams associated with standard files | |
22712 | -------------------------- | |
22713 | -- Standard C functions -- | |
22714 | -------------------------- | |
22715 | -- The functions selected below are ones that are | |
22716 | -- available in UNIX (but not necessarily in ANSI C). | |
22717 | -- These are very thin interfaces | |
22718 | -- which copy exactly the C headers. For more | |
22719 | -- documentation on these functions, see the Microsoft C | |
22720 | -- "Run-Time Library Reference" (Microsoft Press, 1990, | |
22721 | -- ISBN 1-55615-225-6), which includes useful information | |
22722 | -- on system compatibility. | |
22723 | procedure clearerr (stream : FILEs); | |
22724 | function fclose (stream : FILEs) return int; | |
22725 | function fdopen (handle : int; mode : chars) return FILEs; | |
22726 | function feof (stream : FILEs) return int; | |
22727 | function ferror (stream : FILEs) return int; | |
22728 | function fflush (stream : FILEs) return int; | |
22729 | function fgetc (stream : FILEs) return int; | |
22730 | function fgets (strng : chars; n : int; stream : FILEs) | |
22731 | return chars; | |
22732 | function fileno (stream : FILEs) return int; | |
22733 | function fopen (filename : chars; Mode : chars) | |
22734 | return FILEs; | |
22735 | -- Note: to maintain target independence, use | |
22736 | -- text_translation_required, a boolean variable defined in | |
22737 | -- a-sysdep.c to deal with the target dependent text | |
22738 | -- translation requirement. If this variable is set, | |
22739 | -- then b/t should be appended to the standard mode | |
22740 | -- argument to set the text translation mode off or on | |
22741 | -- as required. | |
22742 | function fputc (C : int; stream : FILEs) return int; | |
22743 | function fputs (Strng : chars; Stream : FILEs) return int; | |
22744 | function fread | |
22745 | (buffer : voids; | |
22746 | size : size_t; | |
22747 | count : size_t; | |
22748 | stream : FILEs) | |
22749 | return size_t; | |
22750 | function freopen | |
22751 | (filename : chars; | |
22752 | mode : chars; | |
22753 | stream : FILEs) | |
22754 | return FILEs; | |
22755 | function fseek | |
22756 | (stream : FILEs; | |
22757 | offset : long; | |
22758 | origin : int) | |
22759 | return int; | |
22760 | function ftell (stream : FILEs) return long; | |
22761 | function fwrite | |
22762 | (buffer : voids; | |
22763 | size : size_t; | |
22764 | count : size_t; | |
22765 | stream : FILEs) | |
22766 | return size_t; | |
22767 | function isatty (handle : int) return int; | |
22768 | procedure mktemp (template : chars); | |
22769 | -- The return value (which is just a pointer to template) | |
22770 | -- is discarded | |
22771 | procedure rewind (stream : FILEs); | |
22772 | function rmtmp return int; | |
22773 | function setvbuf | |
22774 | (stream : FILEs; | |
22775 | buffer : chars; | |
22776 | mode : int; | |
22777 | size : size_t) | |
22778 | return int; | |
22779 | ||
22780 | function tmpfile return FILEs; | |
22781 | function ungetc (c : int; stream : FILEs) return int; | |
22782 | function unlink (filename : chars) return int; | |
22783 | --------------------- | |
22784 | -- Extra functions -- | |
22785 | --------------------- | |
22786 | -- These functions supply slightly thicker bindings than | |
22787 | -- those above. They are derived from functions in the | |
22788 | -- C Run-Time Library, but may do a bit more work than | |
22789 | -- just directly calling one of the Library functions. | |
22790 | function is_regular_file (handle : int) return int; | |
22791 | -- Tests if given handle is for a regular file (result 1) | |
22792 | -- or for a non-regular file (pipe or device, result 0). | |
22793 | --------------------------------- | |
22794 | -- Control of Text/Binary Mode -- | |
22795 | --------------------------------- | |
22796 | -- If text_translation_required is true, then the following | |
22797 | -- functions may be used to dynamically switch a file from | |
22798 | -- binary to text mode or vice versa. These functions have | |
22799 | -- no effect if text_translation_required is false (i.e., in | |
22800 | -- normal UNIX mode). Use fileno to get a stream handle. | |
22801 | procedure set_binary_mode (handle : int); | |
22802 | procedure set_text_mode (handle : int); | |
22803 | ---------------------------- | |
22804 | -- Full Path Name support -- | |
22805 | ---------------------------- | |
22806 | procedure full_name (nam : chars; buffer : chars); | |
22807 | -- Given a NUL terminated string representing a file | |
22808 | -- name, returns in buffer a NUL terminated string | |
22809 | -- representing the full path name for the file name. | |
22810 | -- On systems where it is relevant the drive is also | |
22811 | -- part of the full path name. It is the responsibility | |
22812 | -- of the caller to pass an actual parameter for buffer | |
22813 | -- that is big enough for any full path name. Use | |
22814 | -- max_path_len given below as the size of buffer. | |
22815 | max_path_len : integer; | |
22816 | -- Maximum length of an allowable full path name on the | |
22817 | -- system, including a terminating NUL character. | |
22818 | end Interfaces.C_Streams; | |
22819 | @end example | |
22820 | ||
22821 | @node Interfacing to C Streams,,Operations on C Streams,The Implementation of Standard I/O | |
73918baf | 22822 | @anchor{gnat_rm/the_implementation_of_standard_i_o id26}@anchor{2d9}@anchor{gnat_rm/the_implementation_of_standard_i_o interfacing-to-c-streams}@anchor{2da} |
64d5610f ML |
22823 | @section Interfacing to C Streams |
22824 | ||
22825 | ||
22826 | The packages in this section permit interfacing Ada files to C Stream | |
22827 | operations. | |
22828 | ||
22829 | @example | |
22830 | with Interfaces.C_Streams; | |
22831 | package Ada.Sequential_IO.C_Streams is | |
22832 | function C_Stream (F : File_Type) | |
22833 | return Interfaces.C_Streams.FILEs; | |
22834 | procedure Open | |
22835 | (File : in out File_Type; | |
22836 | Mode : in File_Mode; | |
22837 | C_Stream : in Interfaces.C_Streams.FILEs; | |
22838 | Form : in String := ""); | |
22839 | end Ada.Sequential_IO.C_Streams; | |
22840 | ||
22841 | with Interfaces.C_Streams; | |
22842 | package Ada.Direct_IO.C_Streams is | |
22843 | function C_Stream (F : File_Type) | |
22844 | return Interfaces.C_Streams.FILEs; | |
22845 | procedure Open | |
22846 | (File : in out File_Type; | |
22847 | Mode : in File_Mode; | |
22848 | C_Stream : in Interfaces.C_Streams.FILEs; | |
22849 | Form : in String := ""); | |
22850 | end Ada.Direct_IO.C_Streams; | |
22851 | ||
22852 | with Interfaces.C_Streams; | |
22853 | package Ada.Text_IO.C_Streams is | |
22854 | function C_Stream (F : File_Type) | |
22855 | return Interfaces.C_Streams.FILEs; | |
22856 | procedure Open | |
22857 | (File : in out File_Type; | |
22858 | Mode : in File_Mode; | |
22859 | C_Stream : in Interfaces.C_Streams.FILEs; | |
22860 | Form : in String := ""); | |
22861 | end Ada.Text_IO.C_Streams; | |
22862 | ||
22863 | with Interfaces.C_Streams; | |
22864 | package Ada.Wide_Text_IO.C_Streams is | |
22865 | function C_Stream (F : File_Type) | |
22866 | return Interfaces.C_Streams.FILEs; | |
22867 | procedure Open | |
22868 | (File : in out File_Type; | |
22869 | Mode : in File_Mode; | |
22870 | C_Stream : in Interfaces.C_Streams.FILEs; | |
22871 | Form : in String := ""); | |
22872 | end Ada.Wide_Text_IO.C_Streams; | |
22873 | ||
22874 | with Interfaces.C_Streams; | |
22875 | package Ada.Wide_Wide_Text_IO.C_Streams is | |
22876 | function C_Stream (F : File_Type) | |
22877 | return Interfaces.C_Streams.FILEs; | |
22878 | procedure Open | |
22879 | (File : in out File_Type; | |
22880 | Mode : in File_Mode; | |
22881 | C_Stream : in Interfaces.C_Streams.FILEs; | |
22882 | Form : in String := ""); | |
22883 | end Ada.Wide_Wide_Text_IO.C_Streams; | |
22884 | ||
22885 | with Interfaces.C_Streams; | |
22886 | package Ada.Stream_IO.C_Streams is | |
22887 | function C_Stream (F : File_Type) | |
22888 | return Interfaces.C_Streams.FILEs; | |
22889 | procedure Open | |
22890 | (File : in out File_Type; | |
22891 | Mode : in File_Mode; | |
22892 | C_Stream : in Interfaces.C_Streams.FILEs; | |
22893 | Form : in String := ""); | |
22894 | end Ada.Stream_IO.C_Streams; | |
22895 | @end example | |
22896 | ||
22897 | In each of these six packages, the @code{C_Stream} function obtains the | |
22898 | @code{FILE} pointer from a currently opened Ada file. It is then | |
22899 | possible to use the @code{Interfaces.C_Streams} package to operate on | |
22900 | this stream, or the stream can be passed to a C program which can | |
22901 | operate on it directly. Of course the program is responsible for | |
22902 | ensuring that only appropriate sequences of operations are executed. | |
22903 | ||
22904 | One particular use of relevance to an Ada program is that the | |
22905 | @code{setvbuf} function can be used to control the buffering of the | |
22906 | stream used by an Ada file. In the absence of such a call the standard | |
22907 | default buffering is used. | |
22908 | ||
22909 | The @code{Open} procedures in these packages open a file giving an | |
22910 | existing C Stream instead of a file name. Typically this stream is | |
22911 | imported from a C program, allowing an Ada file to operate on an | |
22912 | existing C file. | |
22913 | ||
22914 | @node The GNAT Library,Interfacing to Other Languages,The Implementation of Standard I/O,Top | |
73918baf | 22915 | @anchor{gnat_rm/the_gnat_library doc}@anchor{2db}@anchor{gnat_rm/the_gnat_library id1}@anchor{2dc}@anchor{gnat_rm/the_gnat_library the-gnat-library}@anchor{10} |
64d5610f ML |
22916 | @chapter The GNAT Library |
22917 | ||
22918 | ||
22919 | The GNAT library contains a number of general and special purpose packages. | |
22920 | It represents functionality that the GNAT developers have found useful, and | |
22921 | which is made available to GNAT users. The packages described here are fully | |
22922 | supported, and upwards compatibility will be maintained in future releases, | |
22923 | so you can use these facilities with the confidence that the same functionality | |
22924 | will be available in future releases. | |
22925 | ||
22926 | The chapter here simply gives a brief summary of the facilities available. | |
22927 | The full documentation is found in the spec file for the package. The full | |
22928 | sources of these library packages, including both spec and body, are provided | |
22929 | with all GNAT releases. For example, to find out the full specifications of | |
22930 | the SPITBOL pattern matching capability, including a full tutorial and | |
22931 | extensive examples, look in the @code{g-spipat.ads} file in the library. | |
22932 | ||
22933 | For each entry here, the package name (as it would appear in a @code{with} | |
22934 | clause) is given, followed by the name of the corresponding spec file in | |
22935 | parentheses. The packages are children in four hierarchies, @code{Ada}, | |
22936 | @code{Interfaces}, @code{System}, and @code{GNAT}, the latter being a | |
22937 | GNAT-specific hierarchy. | |
22938 | ||
22939 | Note that an application program should only use packages in one of these | |
22940 | four hierarchies if the package is defined in the Ada Reference Manual, | |
22941 | or is listed in this section of the GNAT Programmers Reference Manual. | |
22942 | All other units should be considered internal implementation units and | |
22943 | should not be directly @code{with}ed by application code. The use of | |
22944 | a @code{with} clause that references one of these internal implementation | |
22945 | units makes an application potentially dependent on changes in versions | |
22946 | of GNAT, and will generate a warning message. | |
22947 | ||
22948 | @menu | |
22949 | * Ada.Characters.Latin_9 (a-chlat9.ads): Ada Characters Latin_9 a-chlat9 ads. | |
22950 | * Ada.Characters.Wide_Latin_1 (a-cwila1.ads): Ada Characters Wide_Latin_1 a-cwila1 ads. | |
eeba836b | 22951 | * Ada.Characters.Wide_Latin_9 (a-cwila9.ads): Ada Characters Wide_Latin_9 a-cwila9 ads. |
64d5610f ML |
22952 | * Ada.Characters.Wide_Wide_Latin_1 (a-chzla1.ads): Ada Characters Wide_Wide_Latin_1 a-chzla1 ads. |
22953 | * Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads): Ada Characters Wide_Wide_Latin_9 a-chzla9 ads. | |
22954 | * Ada.Containers.Bounded_Holders (a-coboho.ads): Ada Containers Bounded_Holders a-coboho ads. | |
22955 | * Ada.Command_Line.Environment (a-colien.ads): Ada Command_Line Environment a-colien ads. | |
22956 | * Ada.Command_Line.Remove (a-colire.ads): Ada Command_Line Remove a-colire ads. | |
22957 | * Ada.Command_Line.Response_File (a-clrefi.ads): Ada Command_Line Response_File a-clrefi ads. | |
22958 | * Ada.Direct_IO.C_Streams (a-diocst.ads): Ada Direct_IO C_Streams a-diocst ads. | |
22959 | * Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads): Ada Exceptions Is_Null_Occurrence a-einuoc ads. | |
22960 | * Ada.Exceptions.Last_Chance_Handler (a-elchha.ads): Ada Exceptions Last_Chance_Handler a-elchha ads. | |
22961 | * Ada.Exceptions.Traceback (a-exctra.ads): Ada Exceptions Traceback a-exctra ads. | |
22962 | * Ada.Sequential_IO.C_Streams (a-siocst.ads): Ada Sequential_IO C_Streams a-siocst ads. | |
22963 | * Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads): Ada Streams Stream_IO C_Streams a-ssicst ads. | |
22964 | * Ada.Strings.Unbounded.Text_IO (a-suteio.ads): Ada Strings Unbounded Text_IO a-suteio ads. | |
22965 | * Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads): Ada Strings Wide_Unbounded Wide_Text_IO a-swuwti ads. | |
22966 | * Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads): Ada Strings Wide_Wide_Unbounded Wide_Wide_Text_IO a-szuzti ads. | |
22967 | * Ada.Task_Initialization (a-tasini.ads): Ada Task_Initialization a-tasini ads. | |
22968 | * Ada.Text_IO.C_Streams (a-tiocst.ads): Ada Text_IO C_Streams a-tiocst ads. | |
22969 | * Ada.Text_IO.Reset_Standard_Files (a-tirsfi.ads): Ada Text_IO Reset_Standard_Files a-tirsfi ads. | |
22970 | * Ada.Wide_Characters.Unicode (a-wichun.ads): Ada Wide_Characters Unicode a-wichun ads. | |
22971 | * Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads): Ada Wide_Text_IO C_Streams a-wtcstr ads. | |
22972 | * Ada.Wide_Text_IO.Reset_Standard_Files (a-wrstfi.ads): Ada Wide_Text_IO Reset_Standard_Files a-wrstfi ads. | |
22973 | * Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads): Ada Wide_Wide_Characters Unicode a-zchuni ads. | |
22974 | * Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads): Ada Wide_Wide_Text_IO C_Streams a-ztcstr ads. | |
22975 | * Ada.Wide_Wide_Text_IO.Reset_Standard_Files (a-zrstfi.ads): Ada Wide_Wide_Text_IO Reset_Standard_Files a-zrstfi ads. | |
22976 | * GNAT.Altivec (g-altive.ads): GNAT Altivec g-altive ads. | |
22977 | * GNAT.Altivec.Conversions (g-altcon.ads): GNAT Altivec Conversions g-altcon ads. | |
22978 | * GNAT.Altivec.Vector_Operations (g-alveop.ads): GNAT Altivec Vector_Operations g-alveop ads. | |
22979 | * GNAT.Altivec.Vector_Types (g-alvety.ads): GNAT Altivec Vector_Types g-alvety ads. | |
22980 | * GNAT.Altivec.Vector_Views (g-alvevi.ads): GNAT Altivec Vector_Views g-alvevi ads. | |
22981 | * GNAT.Array_Split (g-arrspl.ads): GNAT Array_Split g-arrspl ads. | |
22982 | * GNAT.AWK (g-awk.ads): GNAT AWK g-awk ads. | |
22983 | * GNAT.Binary_Search (g-binsea.ads): GNAT Binary_Search g-binsea ads. | |
22984 | * GNAT.Bind_Environment (g-binenv.ads): GNAT Bind_Environment g-binenv ads. | |
22985 | * GNAT.Branch_Prediction (g-brapre.ads): GNAT Branch_Prediction g-brapre ads. | |
22986 | * GNAT.Bounded_Buffers (g-boubuf.ads): GNAT Bounded_Buffers g-boubuf ads. | |
22987 | * GNAT.Bounded_Mailboxes (g-boumai.ads): GNAT Bounded_Mailboxes g-boumai ads. | |
22988 | * GNAT.Bubble_Sort (g-bubsor.ads): GNAT Bubble_Sort g-bubsor ads. | |
22989 | * GNAT.Bubble_Sort_A (g-busora.ads): GNAT Bubble_Sort_A g-busora ads. | |
22990 | * GNAT.Bubble_Sort_G (g-busorg.ads): GNAT Bubble_Sort_G g-busorg ads. | |
22991 | * GNAT.Byte_Order_Mark (g-byorma.ads): GNAT Byte_Order_Mark g-byorma ads. | |
22992 | * GNAT.Byte_Swapping (g-bytswa.ads): GNAT Byte_Swapping g-bytswa ads. | |
22993 | * GNAT.Calendar (g-calend.ads): GNAT Calendar g-calend ads. | |
22994 | * GNAT.Calendar.Time_IO (g-catiio.ads): GNAT Calendar Time_IO g-catiio ads. | |
22995 | * GNAT.CRC32 (g-crc32.ads): GNAT CRC32 g-crc32 ads. | |
22996 | * GNAT.Case_Util (g-casuti.ads): GNAT Case_Util g-casuti ads. | |
22997 | * GNAT.CGI (g-cgi.ads): GNAT CGI g-cgi ads. | |
22998 | * GNAT.CGI.Cookie (g-cgicoo.ads): GNAT CGI Cookie g-cgicoo ads. | |
22999 | * GNAT.CGI.Debug (g-cgideb.ads): GNAT CGI Debug g-cgideb ads. | |
23000 | * GNAT.Command_Line (g-comlin.ads): GNAT Command_Line g-comlin ads. | |
23001 | * GNAT.Compiler_Version (g-comver.ads): GNAT Compiler_Version g-comver ads. | |
23002 | * GNAT.Ctrl_C (g-ctrl_c.ads): GNAT Ctrl_C g-ctrl_c ads. | |
23003 | * GNAT.Current_Exception (g-curexc.ads): GNAT Current_Exception g-curexc ads. | |
23004 | * GNAT.Debug_Pools (g-debpoo.ads): GNAT Debug_Pools g-debpoo ads. | |
23005 | * GNAT.Debug_Utilities (g-debuti.ads): GNAT Debug_Utilities g-debuti ads. | |
23006 | * GNAT.Decode_String (g-decstr.ads): GNAT Decode_String g-decstr ads. | |
23007 | * GNAT.Decode_UTF8_String (g-deutst.ads): GNAT Decode_UTF8_String g-deutst ads. | |
23008 | * GNAT.Directory_Operations (g-dirope.ads): GNAT Directory_Operations g-dirope ads. | |
23009 | * GNAT.Directory_Operations.Iteration (g-diopit.ads): GNAT Directory_Operations Iteration g-diopit ads. | |
23010 | * GNAT.Dynamic_HTables (g-dynhta.ads): GNAT Dynamic_HTables g-dynhta ads. | |
23011 | * GNAT.Dynamic_Tables (g-dyntab.ads): GNAT Dynamic_Tables g-dyntab ads. | |
23012 | * GNAT.Encode_String (g-encstr.ads): GNAT Encode_String g-encstr ads. | |
23013 | * GNAT.Encode_UTF8_String (g-enutst.ads): GNAT Encode_UTF8_String g-enutst ads. | |
23014 | * GNAT.Exception_Actions (g-excact.ads): GNAT Exception_Actions g-excact ads. | |
23015 | * GNAT.Exception_Traces (g-exctra.ads): GNAT Exception_Traces g-exctra ads. | |
23016 | * GNAT.Exceptions (g-except.ads): GNAT Exceptions g-except ads. | |
23017 | * GNAT.Expect (g-expect.ads): GNAT Expect g-expect ads. | |
23018 | * GNAT.Expect.TTY (g-exptty.ads): GNAT Expect TTY g-exptty ads. | |
23019 | * GNAT.Float_Control (g-flocon.ads): GNAT Float_Control g-flocon ads. | |
23020 | * GNAT.Formatted_String (g-forstr.ads): GNAT Formatted_String g-forstr ads. | |
23021 | * GNAT.Generic_Fast_Math_Functions (g-gfmafu.ads): GNAT Generic_Fast_Math_Functions g-gfmafu ads. | |
23022 | * GNAT.Heap_Sort (g-heasor.ads): GNAT Heap_Sort g-heasor ads. | |
23023 | * GNAT.Heap_Sort_A (g-hesora.ads): GNAT Heap_Sort_A g-hesora ads. | |
23024 | * GNAT.Heap_Sort_G (g-hesorg.ads): GNAT Heap_Sort_G g-hesorg ads. | |
23025 | * GNAT.HTable (g-htable.ads): GNAT HTable g-htable ads. | |
23026 | * GNAT.IO (g-io.ads): GNAT IO g-io ads. | |
23027 | * GNAT.IO_Aux (g-io_aux.ads): GNAT IO_Aux g-io_aux ads. | |
23028 | * GNAT.Lock_Files (g-locfil.ads): GNAT Lock_Files g-locfil ads. | |
23029 | * GNAT.MBBS_Discrete_Random (g-mbdira.ads): GNAT MBBS_Discrete_Random g-mbdira ads. | |
23030 | * GNAT.MBBS_Float_Random (g-mbflra.ads): GNAT MBBS_Float_Random g-mbflra ads. | |
23031 | * GNAT.MD5 (g-md5.ads): GNAT MD5 g-md5 ads. | |
23032 | * GNAT.Memory_Dump (g-memdum.ads): GNAT Memory_Dump g-memdum ads. | |
23033 | * GNAT.Most_Recent_Exception (g-moreex.ads): GNAT Most_Recent_Exception g-moreex ads. | |
23034 | * GNAT.OS_Lib (g-os_lib.ads): GNAT OS_Lib g-os_lib ads. | |
23035 | * GNAT.Perfect_Hash_Generators (g-pehage.ads): GNAT Perfect_Hash_Generators g-pehage ads. | |
23036 | * GNAT.Random_Numbers (g-rannum.ads): GNAT Random_Numbers g-rannum ads. | |
23037 | * GNAT.Regexp (g-regexp.ads): GNAT Regexp g-regexp ads. | |
23038 | * GNAT.Registry (g-regist.ads): GNAT Registry g-regist ads. | |
23039 | * GNAT.Regpat (g-regpat.ads): GNAT Regpat g-regpat ads. | |
23040 | * GNAT.Rewrite_Data (g-rewdat.ads): GNAT Rewrite_Data g-rewdat ads. | |
23041 | * GNAT.Secondary_Stack_Info (g-sestin.ads): GNAT Secondary_Stack_Info g-sestin ads. | |
23042 | * GNAT.Semaphores (g-semaph.ads): GNAT Semaphores g-semaph ads. | |
23043 | * GNAT.Serial_Communications (g-sercom.ads): GNAT Serial_Communications g-sercom ads. | |
23044 | * GNAT.SHA1 (g-sha1.ads): GNAT SHA1 g-sha1 ads. | |
23045 | * GNAT.SHA224 (g-sha224.ads): GNAT SHA224 g-sha224 ads. | |
23046 | * GNAT.SHA256 (g-sha256.ads): GNAT SHA256 g-sha256 ads. | |
23047 | * GNAT.SHA384 (g-sha384.ads): GNAT SHA384 g-sha384 ads. | |
23048 | * GNAT.SHA512 (g-sha512.ads): GNAT SHA512 g-sha512 ads. | |
23049 | * GNAT.Signals (g-signal.ads): GNAT Signals g-signal ads. | |
23050 | * GNAT.Sockets (g-socket.ads): GNAT Sockets g-socket ads. | |
23051 | * GNAT.Source_Info (g-souinf.ads): GNAT Source_Info g-souinf ads. | |
23052 | * GNAT.Spelling_Checker (g-speche.ads): GNAT Spelling_Checker g-speche ads. | |
23053 | * GNAT.Spelling_Checker_Generic (g-spchge.ads): GNAT Spelling_Checker_Generic g-spchge ads. | |
23054 | * GNAT.Spitbol.Patterns (g-spipat.ads): GNAT Spitbol Patterns g-spipat ads. | |
23055 | * GNAT.Spitbol (g-spitbo.ads): GNAT Spitbol g-spitbo ads. | |
23056 | * GNAT.Spitbol.Table_Boolean (g-sptabo.ads): GNAT Spitbol Table_Boolean g-sptabo ads. | |
23057 | * GNAT.Spitbol.Table_Integer (g-sptain.ads): GNAT Spitbol Table_Integer g-sptain ads. | |
23058 | * GNAT.Spitbol.Table_VString (g-sptavs.ads): GNAT Spitbol Table_VString g-sptavs ads. | |
23059 | * GNAT.SSE (g-sse.ads): GNAT SSE g-sse ads. | |
23060 | * GNAT.SSE.Vector_Types (g-ssvety.ads): GNAT SSE Vector_Types g-ssvety ads. | |
23061 | * GNAT.String_Hash (g-strhas.ads): GNAT String_Hash g-strhas ads. | |
23062 | * GNAT.Strings (g-string.ads): GNAT Strings g-string ads. | |
23063 | * GNAT.String_Split (g-strspl.ads): GNAT String_Split g-strspl ads. | |
23064 | * GNAT.Table (g-table.ads): GNAT Table g-table ads. | |
23065 | * GNAT.Task_Lock (g-tasloc.ads): GNAT Task_Lock g-tasloc ads. | |
23066 | * GNAT.Time_Stamp (g-timsta.ads): GNAT Time_Stamp g-timsta ads. | |
23067 | * GNAT.Threads (g-thread.ads): GNAT Threads g-thread ads. | |
23068 | * GNAT.Traceback (g-traceb.ads): GNAT Traceback g-traceb ads. | |
23069 | * GNAT.Traceback.Symbolic (g-trasym.ads): GNAT Traceback Symbolic g-trasym ads. | |
eeba836b RD |
23070 | * GNAT.UTF_32 (g-utf_32.ads): GNAT UTF_32 g-utf_32 ads. |
23071 | * GNAT.UTF_32_Spelling_Checker (g-u3spch.ads): GNAT UTF_32_Spelling_Checker g-u3spch ads. | |
64d5610f ML |
23072 | * GNAT.Wide_Spelling_Checker (g-wispch.ads): GNAT Wide_Spelling_Checker g-wispch ads. |
23073 | * GNAT.Wide_String_Split (g-wistsp.ads): GNAT Wide_String_Split g-wistsp ads. | |
23074 | * GNAT.Wide_Wide_Spelling_Checker (g-zspche.ads): GNAT Wide_Wide_Spelling_Checker g-zspche ads. | |
23075 | * GNAT.Wide_Wide_String_Split (g-zistsp.ads): GNAT Wide_Wide_String_Split g-zistsp ads. | |
23076 | * Interfaces.C.Extensions (i-cexten.ads): Interfaces C Extensions i-cexten ads. | |
23077 | * Interfaces.C.Streams (i-cstrea.ads): Interfaces C Streams i-cstrea ads. | |
23078 | * Interfaces.Packed_Decimal (i-pacdec.ads): Interfaces Packed_Decimal i-pacdec ads. | |
23079 | * Interfaces.VxWorks (i-vxwork.ads): Interfaces VxWorks i-vxwork ads. | |
23080 | * Interfaces.VxWorks.Int_Connection (i-vxinco.ads): Interfaces VxWorks Int_Connection i-vxinco ads. | |
23081 | * Interfaces.VxWorks.IO (i-vxwoio.ads): Interfaces VxWorks IO i-vxwoio ads. | |
23082 | * System.Address_Image (s-addima.ads): System Address_Image s-addima ads. | |
23083 | * System.Assertions (s-assert.ads): System Assertions s-assert ads. | |
23084 | * System.Atomic_Counters (s-atocou.ads): System Atomic_Counters s-atocou ads. | |
23085 | * System.Memory (s-memory.ads): System Memory s-memory ads. | |
23086 | * System.Multiprocessors (s-multip.ads): System Multiprocessors s-multip ads. | |
23087 | * System.Multiprocessors.Dispatching_Domains (s-mudido.ads): System Multiprocessors Dispatching_Domains s-mudido ads. | |
23088 | * System.Partition_Interface (s-parint.ads): System Partition_Interface s-parint ads. | |
23089 | * System.Pool_Global (s-pooglo.ads): System Pool_Global s-pooglo ads. | |
23090 | * System.Pool_Local (s-pooloc.ads): System Pool_Local s-pooloc ads. | |
23091 | * System.Restrictions (s-restri.ads): System Restrictions s-restri ads. | |
23092 | * System.Rident (s-rident.ads): System Rident s-rident ads. | |
23093 | * System.Strings.Stream_Ops (s-ststop.ads): System Strings Stream_Ops s-ststop ads. | |
23094 | * System.Unsigned_Types (s-unstyp.ads): System Unsigned_Types s-unstyp ads. | |
23095 | * System.Wch_Cnv (s-wchcnv.ads): System Wch_Cnv s-wchcnv ads. | |
23096 | * System.Wch_Con (s-wchcon.ads): System Wch_Con s-wchcon ads. | |
23097 | ||
23098 | @end menu | |
23099 | ||
23100 | @node Ada Characters Latin_9 a-chlat9 ads,Ada Characters Wide_Latin_1 a-cwila1 ads,,The GNAT Library | |
73918baf | 23101 | @anchor{gnat_rm/the_gnat_library ada-characters-latin-9-a-chlat9-ads}@anchor{2dd}@anchor{gnat_rm/the_gnat_library id2}@anchor{2de} |
64d5610f ML |
23102 | @section @code{Ada.Characters.Latin_9} (@code{a-chlat9.ads}) |
23103 | ||
23104 | ||
23105 | @geindex Ada.Characters.Latin_9 (a-chlat9.ads) | |
23106 | ||
23107 | @geindex Latin_9 constants for Character | |
23108 | ||
23109 | This child of @code{Ada.Characters} | |
23110 | provides a set of definitions corresponding to those in the | |
23111 | RM-defined package @code{Ada.Characters.Latin_1} but with the | |
eeba836b | 23112 | few modifications required for @code{Latin-9}. |
64d5610f ML |
23113 | The provision of such a package |
23114 | is specifically authorized by the Ada Reference Manual | |
23115 | (RM A.3.3(27)). | |
23116 | ||
eeba836b | 23117 | @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 |
73918baf | 23118 | @anchor{gnat_rm/the_gnat_library ada-characters-wide-latin-1-a-cwila1-ads}@anchor{2df}@anchor{gnat_rm/the_gnat_library id3}@anchor{2e0} |
64d5610f ML |
23119 | @section @code{Ada.Characters.Wide_Latin_1} (@code{a-cwila1.ads}) |
23120 | ||
23121 | ||
23122 | @geindex Ada.Characters.Wide_Latin_1 (a-cwila1.ads) | |
23123 | ||
23124 | @geindex Latin_1 constants for Wide_Character | |
23125 | ||
23126 | This child of @code{Ada.Characters} | |
23127 | provides a set of definitions corresponding to those in the | |
23128 | RM-defined package @code{Ada.Characters.Latin_1} but with the | |
23129 | types of the constants being @code{Wide_Character} | |
23130 | instead of @code{Character}. The provision of such a package | |
23131 | is specifically authorized by the Ada Reference Manual | |
23132 | (RM A.3.3(27)). | |
23133 | ||
eeba836b | 23134 | @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 |
73918baf | 23135 | @anchor{gnat_rm/the_gnat_library ada-characters-wide-latin-9-a-cwila9-ads}@anchor{2e1}@anchor{gnat_rm/the_gnat_library id4}@anchor{2e2} |
eeba836b | 23136 | @section @code{Ada.Characters.Wide_Latin_9} (@code{a-cwila9.ads}) |
64d5610f ML |
23137 | |
23138 | ||
eeba836b | 23139 | @geindex Ada.Characters.Wide_Latin_9 (a-cwila9.ads) |
64d5610f ML |
23140 | |
23141 | @geindex Latin_9 constants for Wide_Character | |
23142 | ||
23143 | This child of @code{Ada.Characters} | |
23144 | provides a set of definitions corresponding to those in the | |
23145 | GNAT defined package @code{Ada.Characters.Latin_9} but with the | |
23146 | types of the constants being @code{Wide_Character} | |
23147 | instead of @code{Character}. The provision of such a package | |
23148 | is specifically authorized by the Ada Reference Manual | |
23149 | (RM A.3.3(27)). | |
23150 | ||
eeba836b | 23151 | @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 |
73918baf | 23152 | @anchor{gnat_rm/the_gnat_library ada-characters-wide-wide-latin-1-a-chzla1-ads}@anchor{2e3}@anchor{gnat_rm/the_gnat_library id5}@anchor{2e4} |
64d5610f ML |
23153 | @section @code{Ada.Characters.Wide_Wide_Latin_1} (@code{a-chzla1.ads}) |
23154 | ||
23155 | ||
23156 | @geindex Ada.Characters.Wide_Wide_Latin_1 (a-chzla1.ads) | |
23157 | ||
23158 | @geindex Latin_1 constants for Wide_Wide_Character | |
23159 | ||
23160 | This child of @code{Ada.Characters} | |
23161 | provides a set of definitions corresponding to those in the | |
23162 | RM-defined package @code{Ada.Characters.Latin_1} but with the | |
23163 | types of the constants being @code{Wide_Wide_Character} | |
23164 | instead of @code{Character}. The provision of such a package | |
23165 | is specifically authorized by the Ada Reference Manual | |
23166 | (RM A.3.3(27)). | |
23167 | ||
23168 | @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 | |
73918baf | 23169 | @anchor{gnat_rm/the_gnat_library ada-characters-wide-wide-latin-9-a-chzla9-ads}@anchor{2e5}@anchor{gnat_rm/the_gnat_library id6}@anchor{2e6} |
64d5610f ML |
23170 | @section @code{Ada.Characters.Wide_Wide_Latin_9} (@code{a-chzla9.ads}) |
23171 | ||
23172 | ||
23173 | @geindex Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads) | |
23174 | ||
23175 | @geindex Latin_9 constants for Wide_Wide_Character | |
23176 | ||
23177 | This child of @code{Ada.Characters} | |
23178 | provides a set of definitions corresponding to those in the | |
23179 | GNAT defined package @code{Ada.Characters.Latin_9} but with the | |
23180 | types of the constants being @code{Wide_Wide_Character} | |
23181 | instead of @code{Character}. The provision of such a package | |
23182 | is specifically authorized by the Ada Reference Manual | |
23183 | (RM A.3.3(27)). | |
23184 | ||
23185 | @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 | |
73918baf | 23186 | @anchor{gnat_rm/the_gnat_library ada-containers-bounded-holders-a-coboho-ads}@anchor{2e7}@anchor{gnat_rm/the_gnat_library id7}@anchor{2e8} |
64d5610f ML |
23187 | @section @code{Ada.Containers.Bounded_Holders} (@code{a-coboho.ads}) |
23188 | ||
23189 | ||
23190 | @geindex Ada.Containers.Bounded_Holders (a-coboho.ads) | |
23191 | ||
23192 | @geindex Formal container for vectors | |
23193 | ||
23194 | This child of @code{Ada.Containers} defines a modified version of | |
23195 | Indefinite_Holders that avoids heap allocation. | |
23196 | ||
23197 | @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 | |
73918baf | 23198 | @anchor{gnat_rm/the_gnat_library ada-command-line-environment-a-colien-ads}@anchor{2e9}@anchor{gnat_rm/the_gnat_library id8}@anchor{2ea} |
64d5610f ML |
23199 | @section @code{Ada.Command_Line.Environment} (@code{a-colien.ads}) |
23200 | ||
23201 | ||
23202 | @geindex Ada.Command_Line.Environment (a-colien.ads) | |
23203 | ||
23204 | @geindex Environment entries | |
23205 | ||
23206 | This child of @code{Ada.Command_Line} | |
23207 | provides a mechanism for obtaining environment values on systems | |
23208 | where this concept makes sense. | |
23209 | ||
23210 | @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 | |
73918baf | 23211 | @anchor{gnat_rm/the_gnat_library ada-command-line-remove-a-colire-ads}@anchor{2eb}@anchor{gnat_rm/the_gnat_library id9}@anchor{2ec} |
64d5610f ML |
23212 | @section @code{Ada.Command_Line.Remove} (@code{a-colire.ads}) |
23213 | ||
23214 | ||
23215 | @geindex Ada.Command_Line.Remove (a-colire.ads) | |
23216 | ||
23217 | @geindex Removing command line arguments | |
23218 | ||
23219 | @geindex Command line | |
23220 | @geindex argument removal | |
23221 | ||
23222 | This child of @code{Ada.Command_Line} | |
23223 | provides a mechanism for logically removing | |
23224 | arguments from the argument list. Once removed, an argument is not visible | |
eeba836b RD |
23225 | to further calls to the subprograms in @code{Ada.Command_Line}. These calls |
23226 | will not see the removed argument. | |
64d5610f ML |
23227 | |
23228 | @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 | |
73918baf | 23229 | @anchor{gnat_rm/the_gnat_library ada-command-line-response-file-a-clrefi-ads}@anchor{2ed}@anchor{gnat_rm/the_gnat_library id10}@anchor{2ee} |
64d5610f ML |
23230 | @section @code{Ada.Command_Line.Response_File} (@code{a-clrefi.ads}) |
23231 | ||
23232 | ||
23233 | @geindex Ada.Command_Line.Response_File (a-clrefi.ads) | |
23234 | ||
23235 | @geindex Response file for command line | |
23236 | ||
23237 | @geindex Command line | |
23238 | @geindex response file | |
23239 | ||
23240 | @geindex Command line | |
23241 | @geindex handling long command lines | |
23242 | ||
23243 | This child of @code{Ada.Command_Line} provides a mechanism facilities for | |
23244 | getting command line arguments from a text file, called a “response file”. | |
23245 | Using a response file allow passing a set of arguments to an executable longer | |
23246 | than the maximum allowed by the system on the command line. | |
23247 | ||
23248 | @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 | |
73918baf | 23249 | @anchor{gnat_rm/the_gnat_library ada-direct-io-c-streams-a-diocst-ads}@anchor{2ef}@anchor{gnat_rm/the_gnat_library id11}@anchor{2f0} |
64d5610f ML |
23250 | @section @code{Ada.Direct_IO.C_Streams} (@code{a-diocst.ads}) |
23251 | ||
23252 | ||
23253 | @geindex Ada.Direct_IO.C_Streams (a-diocst.ads) | |
23254 | ||
23255 | @geindex C Streams | |
23256 | @geindex Interfacing with Direct_IO | |
23257 | ||
23258 | This package provides subprograms that allow interfacing between | |
23259 | C streams and @code{Direct_IO}. The stream identifier can be | |
23260 | extracted from a file opened on the Ada side, and an Ada file | |
23261 | can be constructed from a stream opened on the C side. | |
23262 | ||
23263 | @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 | |
73918baf | 23264 | @anchor{gnat_rm/the_gnat_library ada-exceptions-is-null-occurrence-a-einuoc-ads}@anchor{2f1}@anchor{gnat_rm/the_gnat_library id12}@anchor{2f2} |
64d5610f ML |
23265 | @section @code{Ada.Exceptions.Is_Null_Occurrence} (@code{a-einuoc.ads}) |
23266 | ||
23267 | ||
23268 | @geindex Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads) | |
23269 | ||
23270 | @geindex Null_Occurrence | |
23271 | @geindex testing for | |
23272 | ||
23273 | This child subprogram provides a way of testing for the null | |
23274 | exception occurrence (@code{Null_Occurrence}) without raising | |
23275 | an exception. | |
23276 | ||
23277 | @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 | |
73918baf | 23278 | @anchor{gnat_rm/the_gnat_library ada-exceptions-last-chance-handler-a-elchha-ads}@anchor{2f3}@anchor{gnat_rm/the_gnat_library id13}@anchor{2f4} |
64d5610f ML |
23279 | @section @code{Ada.Exceptions.Last_Chance_Handler} (@code{a-elchha.ads}) |
23280 | ||
23281 | ||
23282 | @geindex Ada.Exceptions.Last_Chance_Handler (a-elchha.ads) | |
23283 | ||
23284 | @geindex Null_Occurrence | |
23285 | @geindex testing for | |
23286 | ||
23287 | This child subprogram is used for handling otherwise unhandled | |
23288 | exceptions (hence the name last chance), and perform clean ups before | |
23289 | terminating the program. Note that this subprogram never returns. | |
23290 | ||
23291 | @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 | |
73918baf | 23292 | @anchor{gnat_rm/the_gnat_library ada-exceptions-traceback-a-exctra-ads}@anchor{2f5}@anchor{gnat_rm/the_gnat_library id14}@anchor{2f6} |
64d5610f ML |
23293 | @section @code{Ada.Exceptions.Traceback} (@code{a-exctra.ads}) |
23294 | ||
23295 | ||
23296 | @geindex Ada.Exceptions.Traceback (a-exctra.ads) | |
23297 | ||
23298 | @geindex Traceback for Exception Occurrence | |
23299 | ||
23300 | This child package provides the subprogram (@code{Tracebacks}) to | |
23301 | give a traceback array of addresses based on an exception | |
23302 | occurrence. | |
23303 | ||
23304 | @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 | |
73918baf | 23305 | @anchor{gnat_rm/the_gnat_library ada-sequential-io-c-streams-a-siocst-ads}@anchor{2f7}@anchor{gnat_rm/the_gnat_library id15}@anchor{2f8} |
64d5610f ML |
23306 | @section @code{Ada.Sequential_IO.C_Streams} (@code{a-siocst.ads}) |
23307 | ||
23308 | ||
23309 | @geindex Ada.Sequential_IO.C_Streams (a-siocst.ads) | |
23310 | ||
23311 | @geindex C Streams | |
23312 | @geindex Interfacing with Sequential_IO | |
23313 | ||
23314 | This package provides subprograms that allow interfacing between | |
23315 | C streams and @code{Sequential_IO}. The stream identifier can be | |
23316 | extracted from a file opened on the Ada side, and an Ada file | |
23317 | can be constructed from a stream opened on the C side. | |
23318 | ||
23319 | @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 | |
73918baf | 23320 | @anchor{gnat_rm/the_gnat_library ada-streams-stream-io-c-streams-a-ssicst-ads}@anchor{2f9}@anchor{gnat_rm/the_gnat_library id16}@anchor{2fa} |
64d5610f ML |
23321 | @section @code{Ada.Streams.Stream_IO.C_Streams} (@code{a-ssicst.ads}) |
23322 | ||
23323 | ||
23324 | @geindex Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads) | |
23325 | ||
23326 | @geindex C Streams | |
23327 | @geindex Interfacing with Stream_IO | |
23328 | ||
23329 | This package provides subprograms that allow interfacing between | |
23330 | C streams and @code{Stream_IO}. The stream identifier can be | |
23331 | extracted from a file opened on the Ada side, and an Ada file | |
23332 | can be constructed from a stream opened on the C side. | |
23333 | ||
23334 | @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 | |
73918baf | 23335 | @anchor{gnat_rm/the_gnat_library ada-strings-unbounded-text-io-a-suteio-ads}@anchor{2fb}@anchor{gnat_rm/the_gnat_library id17}@anchor{2fc} |
64d5610f ML |
23336 | @section @code{Ada.Strings.Unbounded.Text_IO} (@code{a-suteio.ads}) |
23337 | ||
23338 | ||
23339 | @geindex Ada.Strings.Unbounded.Text_IO (a-suteio.ads) | |
23340 | ||
23341 | @geindex Unbounded_String | |
23342 | @geindex IO support | |
23343 | ||
23344 | @geindex Text_IO | |
23345 | @geindex extensions for unbounded strings | |
23346 | ||
23347 | This package provides subprograms for Text_IO for unbounded | |
23348 | strings, avoiding the necessity for an intermediate operation | |
23349 | with ordinary strings. | |
23350 | ||
23351 | @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 | |
73918baf | 23352 | @anchor{gnat_rm/the_gnat_library ada-strings-wide-unbounded-wide-text-io-a-swuwti-ads}@anchor{2fd}@anchor{gnat_rm/the_gnat_library id18}@anchor{2fe} |
64d5610f ML |
23353 | @section @code{Ada.Strings.Wide_Unbounded.Wide_Text_IO} (@code{a-swuwti.ads}) |
23354 | ||
23355 | ||
23356 | @geindex Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads) | |
23357 | ||
23358 | @geindex Unbounded_Wide_String | |
23359 | @geindex IO support | |
23360 | ||
23361 | @geindex Text_IO | |
23362 | @geindex extensions for unbounded wide strings | |
23363 | ||
23364 | This package provides subprograms for Text_IO for unbounded | |
23365 | wide strings, avoiding the necessity for an intermediate operation | |
23366 | with ordinary wide strings. | |
23367 | ||
23368 | @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 | |
73918baf | 23369 | @anchor{gnat_rm/the_gnat_library ada-strings-wide-wide-unbounded-wide-wide-text-io-a-szuzti-ads}@anchor{2ff}@anchor{gnat_rm/the_gnat_library id19}@anchor{300} |
64d5610f ML |
23370 | @section @code{Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO} (@code{a-szuzti.ads}) |
23371 | ||
23372 | ||
23373 | @geindex Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads) | |
23374 | ||
23375 | @geindex Unbounded_Wide_Wide_String | |
23376 | @geindex IO support | |
23377 | ||
23378 | @geindex Text_IO | |
23379 | @geindex extensions for unbounded wide wide strings | |
23380 | ||
23381 | This package provides subprograms for Text_IO for unbounded | |
23382 | wide wide strings, avoiding the necessity for an intermediate operation | |
23383 | with ordinary wide wide strings. | |
23384 | ||
23385 | @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 | |
73918baf | 23386 | @anchor{gnat_rm/the_gnat_library ada-task-initialization-a-tasini-ads}@anchor{301}@anchor{gnat_rm/the_gnat_library id20}@anchor{302} |
64d5610f ML |
23387 | @section @code{Ada.Task_Initialization} (@code{a-tasini.ads}) |
23388 | ||
23389 | ||
23390 | @geindex Ada.Task_Initialization (a-tasini.ads) | |
23391 | ||
23392 | This package provides a way to set a global initialization handler that | |
23393 | is automatically invoked whenever a task is activated. Handlers are | |
23394 | parameterless procedures. Note that such a handler is only invoked for | |
23395 | those tasks activated after the handler is set. | |
23396 | ||
23397 | @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 | |
73918baf | 23398 | @anchor{gnat_rm/the_gnat_library ada-text-io-c-streams-a-tiocst-ads}@anchor{303}@anchor{gnat_rm/the_gnat_library id21}@anchor{304} |
64d5610f ML |
23399 | @section @code{Ada.Text_IO.C_Streams} (@code{a-tiocst.ads}) |
23400 | ||
23401 | ||
23402 | @geindex Ada.Text_IO.C_Streams (a-tiocst.ads) | |
23403 | ||
23404 | @geindex C Streams | |
23405 | @geindex Interfacing with `@w{`}Text_IO`@w{`} | |
23406 | ||
23407 | This package provides subprograms that allow interfacing between | |
23408 | C streams and @code{Text_IO}. The stream identifier can be | |
23409 | extracted from a file opened on the Ada side, and an Ada file | |
23410 | can be constructed from a stream opened on the C side. | |
23411 | ||
23412 | @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 | |
73918baf | 23413 | @anchor{gnat_rm/the_gnat_library ada-text-io-reset-standard-files-a-tirsfi-ads}@anchor{305}@anchor{gnat_rm/the_gnat_library id22}@anchor{306} |
64d5610f ML |
23414 | @section @code{Ada.Text_IO.Reset_Standard_Files} (@code{a-tirsfi.ads}) |
23415 | ||
23416 | ||
23417 | @geindex Ada.Text_IO.Reset_Standard_Files (a-tirsfi.ads) | |
23418 | ||
23419 | @geindex Text_IO resetting standard files | |
23420 | ||
23421 | This procedure is used to reset the status of the standard files used | |
23422 | by Ada.Text_IO. This is useful in a situation (such as a restart in an | |
23423 | embedded application) where the status of the files may change during | |
23424 | execution (for example a standard input file may be redefined to be | |
23425 | interactive). | |
23426 | ||
23427 | @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 | |
73918baf | 23428 | @anchor{gnat_rm/the_gnat_library ada-wide-characters-unicode-a-wichun-ads}@anchor{307}@anchor{gnat_rm/the_gnat_library id23}@anchor{308} |
64d5610f ML |
23429 | @section @code{Ada.Wide_Characters.Unicode} (@code{a-wichun.ads}) |
23430 | ||
23431 | ||
23432 | @geindex Ada.Wide_Characters.Unicode (a-wichun.ads) | |
23433 | ||
23434 | @geindex Unicode categorization | |
23435 | @geindex Wide_Character | |
23436 | ||
23437 | This package provides subprograms that allow categorization of | |
23438 | Wide_Character values according to Unicode categories. | |
23439 | ||
23440 | @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 | |
73918baf | 23441 | @anchor{gnat_rm/the_gnat_library ada-wide-text-io-c-streams-a-wtcstr-ads}@anchor{309}@anchor{gnat_rm/the_gnat_library id24}@anchor{30a} |
64d5610f ML |
23442 | @section @code{Ada.Wide_Text_IO.C_Streams} (@code{a-wtcstr.ads}) |
23443 | ||
23444 | ||
23445 | @geindex Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads) | |
23446 | ||
23447 | @geindex C Streams | |
23448 | @geindex Interfacing with `@w{`}Wide_Text_IO`@w{`} | |
23449 | ||
23450 | This package provides subprograms that allow interfacing between | |
23451 | C streams and @code{Wide_Text_IO}. The stream identifier can be | |
23452 | extracted from a file opened on the Ada side, and an Ada file | |
23453 | can be constructed from a stream opened on the C side. | |
23454 | ||
23455 | @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 | |
73918baf | 23456 | @anchor{gnat_rm/the_gnat_library ada-wide-text-io-reset-standard-files-a-wrstfi-ads}@anchor{30b}@anchor{gnat_rm/the_gnat_library id25}@anchor{30c} |
64d5610f ML |
23457 | @section @code{Ada.Wide_Text_IO.Reset_Standard_Files} (@code{a-wrstfi.ads}) |
23458 | ||
23459 | ||
23460 | @geindex Ada.Wide_Text_IO.Reset_Standard_Files (a-wrstfi.ads) | |
23461 | ||
23462 | @geindex Wide_Text_IO resetting standard files | |
23463 | ||
23464 | This procedure is used to reset the status of the standard files used | |
23465 | by Ada.Wide_Text_IO. This is useful in a situation (such as a restart in an | |
23466 | embedded application) where the status of the files may change during | |
23467 | execution (for example a standard input file may be redefined to be | |
23468 | interactive). | |
23469 | ||
23470 | @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 | |
73918baf | 23471 | @anchor{gnat_rm/the_gnat_library ada-wide-wide-characters-unicode-a-zchuni-ads}@anchor{30d}@anchor{gnat_rm/the_gnat_library id26}@anchor{30e} |
64d5610f ML |
23472 | @section @code{Ada.Wide_Wide_Characters.Unicode} (@code{a-zchuni.ads}) |
23473 | ||
23474 | ||
23475 | @geindex Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads) | |
23476 | ||
23477 | @geindex Unicode categorization | |
23478 | @geindex Wide_Wide_Character | |
23479 | ||
23480 | This package provides subprograms that allow categorization of | |
23481 | Wide_Wide_Character values according to Unicode categories. | |
23482 | ||
23483 | @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 | |
73918baf | 23484 | @anchor{gnat_rm/the_gnat_library ada-wide-wide-text-io-c-streams-a-ztcstr-ads}@anchor{30f}@anchor{gnat_rm/the_gnat_library id27}@anchor{310} |
64d5610f ML |
23485 | @section @code{Ada.Wide_Wide_Text_IO.C_Streams} (@code{a-ztcstr.ads}) |
23486 | ||
23487 | ||
23488 | @geindex Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads) | |
23489 | ||
23490 | @geindex C Streams | |
23491 | @geindex Interfacing with `@w{`}Wide_Wide_Text_IO`@w{`} | |
23492 | ||
23493 | This package provides subprograms that allow interfacing between | |
23494 | C streams and @code{Wide_Wide_Text_IO}. The stream identifier can be | |
23495 | extracted from a file opened on the Ada side, and an Ada file | |
23496 | can be constructed from a stream opened on the C side. | |
23497 | ||
23498 | @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 | |
73918baf | 23499 | @anchor{gnat_rm/the_gnat_library ada-wide-wide-text-io-reset-standard-files-a-zrstfi-ads}@anchor{311}@anchor{gnat_rm/the_gnat_library id28}@anchor{312} |
64d5610f ML |
23500 | @section @code{Ada.Wide_Wide_Text_IO.Reset_Standard_Files} (@code{a-zrstfi.ads}) |
23501 | ||
23502 | ||
23503 | @geindex Ada.Wide_Wide_Text_IO.Reset_Standard_Files (a-zrstfi.ads) | |
23504 | ||
23505 | @geindex Wide_Wide_Text_IO resetting standard files | |
23506 | ||
23507 | This procedure is used to reset the status of the standard files used | |
23508 | by Ada.Wide_Wide_Text_IO. This is useful in a situation (such as a | |
23509 | restart in an embedded application) where the status of the files may | |
23510 | change during execution (for example a standard input file may be | |
23511 | redefined to be interactive). | |
23512 | ||
23513 | @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 | |
73918baf | 23514 | @anchor{gnat_rm/the_gnat_library gnat-altivec-g-altive-ads}@anchor{313}@anchor{gnat_rm/the_gnat_library id29}@anchor{314} |
64d5610f ML |
23515 | @section @code{GNAT.Altivec} (@code{g-altive.ads}) |
23516 | ||
23517 | ||
23518 | @geindex GNAT.Altivec (g-altive.ads) | |
23519 | ||
23520 | @geindex AltiVec | |
23521 | ||
23522 | This is the root package of the GNAT AltiVec binding. It provides | |
23523 | definitions of constants and types common to all the versions of the | |
23524 | binding. | |
23525 | ||
23526 | @node GNAT Altivec Conversions g-altcon ads,GNAT Altivec Vector_Operations g-alveop ads,GNAT Altivec g-altive ads,The GNAT Library | |
73918baf | 23527 | @anchor{gnat_rm/the_gnat_library gnat-altivec-conversions-g-altcon-ads}@anchor{315}@anchor{gnat_rm/the_gnat_library id30}@anchor{316} |
64d5610f ML |
23528 | @section @code{GNAT.Altivec.Conversions} (@code{g-altcon.ads}) |
23529 | ||
23530 | ||
23531 | @geindex GNAT.Altivec.Conversions (g-altcon.ads) | |
23532 | ||
23533 | @geindex AltiVec | |
23534 | ||
23535 | This package provides the Vector/View conversion routines. | |
23536 | ||
23537 | @node GNAT Altivec Vector_Operations g-alveop ads,GNAT Altivec Vector_Types g-alvety ads,GNAT Altivec Conversions g-altcon ads,The GNAT Library | |
73918baf | 23538 | @anchor{gnat_rm/the_gnat_library gnat-altivec-vector-operations-g-alveop-ads}@anchor{317}@anchor{gnat_rm/the_gnat_library id31}@anchor{318} |
64d5610f ML |
23539 | @section @code{GNAT.Altivec.Vector_Operations} (@code{g-alveop.ads}) |
23540 | ||
23541 | ||
23542 | @geindex GNAT.Altivec.Vector_Operations (g-alveop.ads) | |
23543 | ||
23544 | @geindex AltiVec | |
23545 | ||
23546 | This package exposes the Ada interface to the AltiVec operations on | |
23547 | vector objects. A soft emulation is included by default in the GNAT | |
23548 | library. The hard binding is provided as a separate package. This unit | |
23549 | is common to both bindings. | |
23550 | ||
23551 | @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 | |
73918baf | 23552 | @anchor{gnat_rm/the_gnat_library gnat-altivec-vector-types-g-alvety-ads}@anchor{319}@anchor{gnat_rm/the_gnat_library id32}@anchor{31a} |
64d5610f ML |
23553 | @section @code{GNAT.Altivec.Vector_Types} (@code{g-alvety.ads}) |
23554 | ||
23555 | ||
23556 | @geindex GNAT.Altivec.Vector_Types (g-alvety.ads) | |
23557 | ||
23558 | @geindex AltiVec | |
23559 | ||
23560 | This package exposes the various vector types part of the Ada binding | |
23561 | to AltiVec facilities. | |
23562 | ||
23563 | @node GNAT Altivec Vector_Views g-alvevi ads,GNAT Array_Split g-arrspl ads,GNAT Altivec Vector_Types g-alvety ads,The GNAT Library | |
73918baf | 23564 | @anchor{gnat_rm/the_gnat_library gnat-altivec-vector-views-g-alvevi-ads}@anchor{31b}@anchor{gnat_rm/the_gnat_library id33}@anchor{31c} |
64d5610f ML |
23565 | @section @code{GNAT.Altivec.Vector_Views} (@code{g-alvevi.ads}) |
23566 | ||
23567 | ||
23568 | @geindex GNAT.Altivec.Vector_Views (g-alvevi.ads) | |
23569 | ||
23570 | @geindex AltiVec | |
23571 | ||
23572 | This package provides public ‘View’ data types from/to which private | |
23573 | vector representations can be converted via | |
23574 | GNAT.Altivec.Conversions. This allows convenient access to individual | |
23575 | vector elements and provides a simple way to initialize vector | |
23576 | objects. | |
23577 | ||
23578 | @node GNAT Array_Split g-arrspl ads,GNAT AWK g-awk ads,GNAT Altivec Vector_Views g-alvevi ads,The GNAT Library | |
73918baf | 23579 | @anchor{gnat_rm/the_gnat_library gnat-array-split-g-arrspl-ads}@anchor{31d}@anchor{gnat_rm/the_gnat_library id34}@anchor{31e} |
64d5610f ML |
23580 | @section @code{GNAT.Array_Split} (@code{g-arrspl.ads}) |
23581 | ||
23582 | ||
23583 | @geindex GNAT.Array_Split (g-arrspl.ads) | |
23584 | ||
23585 | @geindex Array splitter | |
23586 | ||
23587 | Useful array-manipulation routines: given a set of separators, split | |
23588 | an array wherever the separators appear, and provide direct access | |
23589 | to the resulting slices. | |
23590 | ||
23591 | @node GNAT AWK g-awk ads,GNAT Binary_Search g-binsea ads,GNAT Array_Split g-arrspl ads,The GNAT Library | |
73918baf | 23592 | @anchor{gnat_rm/the_gnat_library gnat-awk-g-awk-ads}@anchor{31f}@anchor{gnat_rm/the_gnat_library id35}@anchor{320} |
64d5610f ML |
23593 | @section @code{GNAT.AWK} (@code{g-awk.ads}) |
23594 | ||
23595 | ||
23596 | @geindex GNAT.AWK (g-awk.ads) | |
23597 | ||
23598 | @geindex Parsing | |
23599 | ||
23600 | @geindex AWK | |
23601 | ||
23602 | Provides AWK-like parsing functions, with an easy interface for parsing one | |
23603 | or more files containing formatted data. The file is viewed as a database | |
23604 | where each record is a line and a field is a data element in this line. | |
23605 | ||
23606 | @node GNAT Binary_Search g-binsea ads,GNAT Bind_Environment g-binenv ads,GNAT AWK g-awk ads,The GNAT Library | |
73918baf | 23607 | @anchor{gnat_rm/the_gnat_library gnat-binary-search-g-binsea-ads}@anchor{321}@anchor{gnat_rm/the_gnat_library id36}@anchor{322} |
64d5610f ML |
23608 | @section @code{GNAT.Binary_Search} (@code{g-binsea.ads}) |
23609 | ||
23610 | ||
23611 | @geindex GNAT.Binary_Search (g-binsea.ads) | |
23612 | ||
23613 | @geindex Binary search | |
23614 | ||
23615 | Allow binary search of a sorted array (or of an array-like container; | |
23616 | the generic does not reference the array directly). | |
23617 | ||
23618 | @node GNAT Bind_Environment g-binenv ads,GNAT Branch_Prediction g-brapre ads,GNAT Binary_Search g-binsea ads,The GNAT Library | |
73918baf | 23619 | @anchor{gnat_rm/the_gnat_library gnat-bind-environment-g-binenv-ads}@anchor{323}@anchor{gnat_rm/the_gnat_library id37}@anchor{324} |
64d5610f ML |
23620 | @section @code{GNAT.Bind_Environment} (@code{g-binenv.ads}) |
23621 | ||
23622 | ||
23623 | @geindex GNAT.Bind_Environment (g-binenv.ads) | |
23624 | ||
23625 | @geindex Bind environment | |
23626 | ||
23627 | Provides access to key=value associations captured at bind time. | |
23628 | These associations can be specified using the @code{-V} binder command | |
23629 | line switch. | |
23630 | ||
23631 | @node GNAT Branch_Prediction g-brapre ads,GNAT Bounded_Buffers g-boubuf ads,GNAT Bind_Environment g-binenv ads,The GNAT Library | |
73918baf | 23632 | @anchor{gnat_rm/the_gnat_library gnat-branch-prediction-g-brapre-ads}@anchor{325}@anchor{gnat_rm/the_gnat_library id38}@anchor{326} |
64d5610f ML |
23633 | @section @code{GNAT.Branch_Prediction} (@code{g-brapre.ads}) |
23634 | ||
23635 | ||
23636 | @geindex GNAT.Branch_Prediction (g-brapre.ads) | |
23637 | ||
23638 | @geindex Branch Prediction | |
23639 | ||
23640 | Provides routines giving hints to the branch predictor of the code generator. | |
23641 | ||
23642 | @node GNAT Bounded_Buffers g-boubuf ads,GNAT Bounded_Mailboxes g-boumai ads,GNAT Branch_Prediction g-brapre ads,The GNAT Library | |
73918baf | 23643 | @anchor{gnat_rm/the_gnat_library gnat-bounded-buffers-g-boubuf-ads}@anchor{327}@anchor{gnat_rm/the_gnat_library id39}@anchor{328} |
64d5610f ML |
23644 | @section @code{GNAT.Bounded_Buffers} (@code{g-boubuf.ads}) |
23645 | ||
23646 | ||
23647 | @geindex GNAT.Bounded_Buffers (g-boubuf.ads) | |
23648 | ||
23649 | @geindex Parsing | |
23650 | ||
23651 | @geindex Bounded Buffers | |
23652 | ||
23653 | Provides a concurrent generic bounded buffer abstraction. Instances are | |
23654 | useful directly or as parts of the implementations of other abstractions, | |
23655 | such as mailboxes. | |
23656 | ||
23657 | @node GNAT Bounded_Mailboxes g-boumai ads,GNAT Bubble_Sort g-bubsor ads,GNAT Bounded_Buffers g-boubuf ads,The GNAT Library | |
73918baf | 23658 | @anchor{gnat_rm/the_gnat_library gnat-bounded-mailboxes-g-boumai-ads}@anchor{329}@anchor{gnat_rm/the_gnat_library id40}@anchor{32a} |
64d5610f ML |
23659 | @section @code{GNAT.Bounded_Mailboxes} (@code{g-boumai.ads}) |
23660 | ||
23661 | ||
23662 | @geindex GNAT.Bounded_Mailboxes (g-boumai.ads) | |
23663 | ||
23664 | @geindex Parsing | |
23665 | ||
23666 | @geindex Mailboxes | |
23667 | ||
23668 | Provides a thread-safe asynchronous intertask mailbox communication facility. | |
23669 | ||
23670 | @node GNAT Bubble_Sort g-bubsor ads,GNAT Bubble_Sort_A g-busora ads,GNAT Bounded_Mailboxes g-boumai ads,The GNAT Library | |
73918baf | 23671 | @anchor{gnat_rm/the_gnat_library gnat-bubble-sort-g-bubsor-ads}@anchor{32b}@anchor{gnat_rm/the_gnat_library id41}@anchor{32c} |
64d5610f ML |
23672 | @section @code{GNAT.Bubble_Sort} (@code{g-bubsor.ads}) |
23673 | ||
23674 | ||
23675 | @geindex GNAT.Bubble_Sort (g-bubsor.ads) | |
23676 | ||
23677 | @geindex Sorting | |
23678 | ||
23679 | @geindex Bubble sort | |
23680 | ||
23681 | Provides a general implementation of bubble sort usable for sorting arbitrary | |
23682 | data items. Exchange and comparison procedures are provided by passing | |
23683 | access-to-procedure values. | |
23684 | ||
23685 | @node GNAT Bubble_Sort_A g-busora ads,GNAT Bubble_Sort_G g-busorg ads,GNAT Bubble_Sort g-bubsor ads,The GNAT Library | |
73918baf | 23686 | @anchor{gnat_rm/the_gnat_library gnat-bubble-sort-a-g-busora-ads}@anchor{32d}@anchor{gnat_rm/the_gnat_library id42}@anchor{32e} |
64d5610f ML |
23687 | @section @code{GNAT.Bubble_Sort_A} (@code{g-busora.ads}) |
23688 | ||
23689 | ||
23690 | @geindex GNAT.Bubble_Sort_A (g-busora.ads) | |
23691 | ||
23692 | @geindex Sorting | |
23693 | ||
23694 | @geindex Bubble sort | |
23695 | ||
23696 | Provides a general implementation of bubble sort usable for sorting arbitrary | |
23697 | data items. Move and comparison procedures are provided by passing | |
23698 | access-to-procedure values. This is an older version, retained for | |
23699 | compatibility. Usually @code{GNAT.Bubble_Sort} will be preferable. | |
23700 | ||
23701 | @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 | |
73918baf | 23702 | @anchor{gnat_rm/the_gnat_library gnat-bubble-sort-g-g-busorg-ads}@anchor{32f}@anchor{gnat_rm/the_gnat_library id43}@anchor{330} |
64d5610f ML |
23703 | @section @code{GNAT.Bubble_Sort_G} (@code{g-busorg.ads}) |
23704 | ||
23705 | ||
23706 | @geindex GNAT.Bubble_Sort_G (g-busorg.ads) | |
23707 | ||
23708 | @geindex Sorting | |
23709 | ||
23710 | @geindex Bubble sort | |
23711 | ||
23712 | Similar to @code{Bubble_Sort_A} except that the move and sorting procedures | |
23713 | are provided as generic parameters, this improves efficiency, especially | |
23714 | if the procedures can be inlined, at the expense of duplicating code for | |
23715 | multiple instantiations. | |
23716 | ||
23717 | @node GNAT Byte_Order_Mark g-byorma ads,GNAT Byte_Swapping g-bytswa ads,GNAT Bubble_Sort_G g-busorg ads,The GNAT Library | |
73918baf | 23718 | @anchor{gnat_rm/the_gnat_library gnat-byte-order-mark-g-byorma-ads}@anchor{331}@anchor{gnat_rm/the_gnat_library id44}@anchor{332} |
64d5610f ML |
23719 | @section @code{GNAT.Byte_Order_Mark} (@code{g-byorma.ads}) |
23720 | ||
23721 | ||
23722 | @geindex GNAT.Byte_Order_Mark (g-byorma.ads) | |
23723 | ||
23724 | @geindex UTF-8 representation | |
23725 | ||
23726 | @geindex Wide characte representations | |
23727 | ||
23728 | Provides a routine which given a string, reads the start of the string to | |
23729 | see whether it is one of the standard byte order marks (BOM’s) which signal | |
23730 | the encoding of the string. The routine includes detection of special XML | |
23731 | sequences for various UCS input formats. | |
23732 | ||
23733 | @node GNAT Byte_Swapping g-bytswa ads,GNAT Calendar g-calend ads,GNAT Byte_Order_Mark g-byorma ads,The GNAT Library | |
73918baf | 23734 | @anchor{gnat_rm/the_gnat_library gnat-byte-swapping-g-bytswa-ads}@anchor{333}@anchor{gnat_rm/the_gnat_library id45}@anchor{334} |
64d5610f ML |
23735 | @section @code{GNAT.Byte_Swapping} (@code{g-bytswa.ads}) |
23736 | ||
23737 | ||
23738 | @geindex GNAT.Byte_Swapping (g-bytswa.ads) | |
23739 | ||
23740 | @geindex Byte swapping | |
23741 | ||
23742 | @geindex Endianness | |
23743 | ||
23744 | General routines for swapping the bytes in 2-, 4-, and 8-byte quantities. | |
23745 | Machine-specific implementations are available in some cases. | |
23746 | ||
23747 | @node GNAT Calendar g-calend ads,GNAT Calendar Time_IO g-catiio ads,GNAT Byte_Swapping g-bytswa ads,The GNAT Library | |
73918baf | 23748 | @anchor{gnat_rm/the_gnat_library gnat-calendar-g-calend-ads}@anchor{335}@anchor{gnat_rm/the_gnat_library id46}@anchor{336} |
64d5610f ML |
23749 | @section @code{GNAT.Calendar} (@code{g-calend.ads}) |
23750 | ||
23751 | ||
23752 | @geindex GNAT.Calendar (g-calend.ads) | |
23753 | ||
23754 | @geindex Calendar | |
23755 | ||
23756 | Extends the facilities provided by @code{Ada.Calendar} to include handling | |
23757 | of days of the week, an extended @code{Split} and @code{Time_Of} capability. | |
23758 | Also provides conversion of @code{Ada.Calendar.Time} values to and from the | |
23759 | C @code{timeval} format. | |
23760 | ||
23761 | @node GNAT Calendar Time_IO g-catiio ads,GNAT CRC32 g-crc32 ads,GNAT Calendar g-calend ads,The GNAT Library | |
73918baf | 23762 | @anchor{gnat_rm/the_gnat_library gnat-calendar-time-io-g-catiio-ads}@anchor{337}@anchor{gnat_rm/the_gnat_library id47}@anchor{338} |
64d5610f ML |
23763 | @section @code{GNAT.Calendar.Time_IO} (@code{g-catiio.ads}) |
23764 | ||
23765 | ||
23766 | @geindex Calendar | |
23767 | ||
23768 | @geindex Time | |
23769 | ||
23770 | @geindex GNAT.Calendar.Time_IO (g-catiio.ads) | |
23771 | ||
23772 | @node GNAT CRC32 g-crc32 ads,GNAT Case_Util g-casuti ads,GNAT Calendar Time_IO g-catiio ads,The GNAT Library | |
73918baf | 23773 | @anchor{gnat_rm/the_gnat_library gnat-crc32-g-crc32-ads}@anchor{339}@anchor{gnat_rm/the_gnat_library id48}@anchor{33a} |
64d5610f ML |
23774 | @section @code{GNAT.CRC32} (@code{g-crc32.ads}) |
23775 | ||
23776 | ||
23777 | @geindex GNAT.CRC32 (g-crc32.ads) | |
23778 | ||
23779 | @geindex CRC32 | |
23780 | ||
23781 | @geindex Cyclic Redundancy Check | |
23782 | ||
23783 | This package implements the CRC-32 algorithm. For a full description | |
23784 | of this algorithm see | |
23785 | `Computation of Cyclic Redundancy Checks via Table Look-Up', | |
23786 | @cite{Communications of the ACM}, Vol. 31 No. 8, pp. 1008-1013, | |
23787 | Aug. 1988. Sarwate, D.V. | |
23788 | ||
23789 | @node GNAT Case_Util g-casuti ads,GNAT CGI g-cgi ads,GNAT CRC32 g-crc32 ads,The GNAT Library | |
73918baf | 23790 | @anchor{gnat_rm/the_gnat_library gnat-case-util-g-casuti-ads}@anchor{33b}@anchor{gnat_rm/the_gnat_library id49}@anchor{33c} |
64d5610f ML |
23791 | @section @code{GNAT.Case_Util} (@code{g-casuti.ads}) |
23792 | ||
23793 | ||
23794 | @geindex GNAT.Case_Util (g-casuti.ads) | |
23795 | ||
23796 | @geindex Casing utilities | |
23797 | ||
23798 | @geindex Character handling (`@w{`}GNAT.Case_Util`@w{`}) | |
23799 | ||
23800 | A set of simple routines for handling upper and lower casing of strings | |
23801 | without the overhead of the full casing tables | |
23802 | in @code{Ada.Characters.Handling}. | |
23803 | ||
23804 | @node GNAT CGI g-cgi ads,GNAT CGI Cookie g-cgicoo ads,GNAT Case_Util g-casuti ads,The GNAT Library | |
73918baf | 23805 | @anchor{gnat_rm/the_gnat_library gnat-cgi-g-cgi-ads}@anchor{33d}@anchor{gnat_rm/the_gnat_library id50}@anchor{33e} |
64d5610f ML |
23806 | @section @code{GNAT.CGI} (@code{g-cgi.ads}) |
23807 | ||
23808 | ||
23809 | @geindex GNAT.CGI (g-cgi.ads) | |
23810 | ||
23811 | @geindex CGI (Common Gateway Interface) | |
23812 | ||
23813 | This is a package for interfacing a GNAT program with a Web server via the | |
23814 | Common Gateway Interface (CGI). Basically this package parses the CGI | |
23815 | parameters, which are a set of key/value pairs sent by the Web server. It | |
23816 | builds a table whose index is the key and provides some services to deal | |
23817 | with this table. | |
23818 | ||
23819 | @node GNAT CGI Cookie g-cgicoo ads,GNAT CGI Debug g-cgideb ads,GNAT CGI g-cgi ads,The GNAT Library | |
73918baf | 23820 | @anchor{gnat_rm/the_gnat_library gnat-cgi-cookie-g-cgicoo-ads}@anchor{33f}@anchor{gnat_rm/the_gnat_library id51}@anchor{340} |
64d5610f ML |
23821 | @section @code{GNAT.CGI.Cookie} (@code{g-cgicoo.ads}) |
23822 | ||
23823 | ||
23824 | @geindex GNAT.CGI.Cookie (g-cgicoo.ads) | |
23825 | ||
23826 | @geindex CGI (Common Gateway Interface) cookie support | |
23827 | ||
23828 | @geindex Cookie support in CGI | |
23829 | ||
23830 | This is a package to interface a GNAT program with a Web server via the | |
23831 | Common Gateway Interface (CGI). It exports services to deal with Web | |
23832 | cookies (piece of information kept in the Web client software). | |
23833 | ||
23834 | @node GNAT CGI Debug g-cgideb ads,GNAT Command_Line g-comlin ads,GNAT CGI Cookie g-cgicoo ads,The GNAT Library | |
73918baf | 23835 | @anchor{gnat_rm/the_gnat_library gnat-cgi-debug-g-cgideb-ads}@anchor{341}@anchor{gnat_rm/the_gnat_library id52}@anchor{342} |
64d5610f ML |
23836 | @section @code{GNAT.CGI.Debug} (@code{g-cgideb.ads}) |
23837 | ||
23838 | ||
23839 | @geindex GNAT.CGI.Debug (g-cgideb.ads) | |
23840 | ||
23841 | @geindex CGI (Common Gateway Interface) debugging | |
23842 | ||
23843 | This is a package to help debugging CGI (Common Gateway Interface) | |
23844 | programs written in Ada. | |
23845 | ||
23846 | @node GNAT Command_Line g-comlin ads,GNAT Compiler_Version g-comver ads,GNAT CGI Debug g-cgideb ads,The GNAT Library | |
73918baf | 23847 | @anchor{gnat_rm/the_gnat_library gnat-command-line-g-comlin-ads}@anchor{343}@anchor{gnat_rm/the_gnat_library id53}@anchor{344} |
64d5610f ML |
23848 | @section @code{GNAT.Command_Line} (@code{g-comlin.ads}) |
23849 | ||
23850 | ||
23851 | @geindex GNAT.Command_Line (g-comlin.ads) | |
23852 | ||
23853 | @geindex Command line | |
23854 | ||
23855 | Provides a high level interface to @code{Ada.Command_Line} facilities, | |
23856 | including the ability to scan for named switches with optional parameters | |
23857 | and expand file names using wildcard notations. | |
23858 | ||
23859 | @node GNAT Compiler_Version g-comver ads,GNAT Ctrl_C g-ctrl_c ads,GNAT Command_Line g-comlin ads,The GNAT Library | |
73918baf | 23860 | @anchor{gnat_rm/the_gnat_library gnat-compiler-version-g-comver-ads}@anchor{345}@anchor{gnat_rm/the_gnat_library id54}@anchor{346} |
64d5610f ML |
23861 | @section @code{GNAT.Compiler_Version} (@code{g-comver.ads}) |
23862 | ||
23863 | ||
23864 | @geindex GNAT.Compiler_Version (g-comver.ads) | |
23865 | ||
23866 | @geindex Compiler Version | |
23867 | ||
23868 | @geindex Version | |
23869 | @geindex of compiler | |
23870 | ||
23871 | Provides a routine for obtaining the version of the compiler used to | |
23872 | compile the program. More accurately this is the version of the binder | |
23873 | used to bind the program (this will normally be the same as the version | |
23874 | of the compiler if a consistent tool set is used to compile all units | |
23875 | of a partition). | |
23876 | ||
23877 | @node GNAT Ctrl_C g-ctrl_c ads,GNAT Current_Exception g-curexc ads,GNAT Compiler_Version g-comver ads,The GNAT Library | |
73918baf | 23878 | @anchor{gnat_rm/the_gnat_library gnat-ctrl-c-g-ctrl-c-ads}@anchor{347}@anchor{gnat_rm/the_gnat_library id55}@anchor{348} |
64d5610f ML |
23879 | @section @code{GNAT.Ctrl_C} (@code{g-ctrl_c.ads}) |
23880 | ||
23881 | ||
23882 | @geindex GNAT.Ctrl_C (g-ctrl_c.ads) | |
23883 | ||
23884 | @geindex Interrupt | |
23885 | ||
23886 | Provides a simple interface to handle Ctrl-C keyboard events. | |
23887 | ||
23888 | @node GNAT Current_Exception g-curexc ads,GNAT Debug_Pools g-debpoo ads,GNAT Ctrl_C g-ctrl_c ads,The GNAT Library | |
73918baf | 23889 | @anchor{gnat_rm/the_gnat_library gnat-current-exception-g-curexc-ads}@anchor{349}@anchor{gnat_rm/the_gnat_library id56}@anchor{34a} |
64d5610f ML |
23890 | @section @code{GNAT.Current_Exception} (@code{g-curexc.ads}) |
23891 | ||
23892 | ||
23893 | @geindex GNAT.Current_Exception (g-curexc.ads) | |
23894 | ||
23895 | @geindex Current exception | |
23896 | ||
23897 | @geindex Exception retrieval | |
23898 | ||
23899 | Provides access to information on the current exception that has been raised | |
23900 | without the need for using the Ada 95 / Ada 2005 exception choice parameter | |
23901 | specification syntax. | |
23902 | This is particularly useful in simulating typical facilities for | |
23903 | obtaining information about exceptions provided by Ada 83 compilers. | |
23904 | ||
23905 | @node GNAT Debug_Pools g-debpoo ads,GNAT Debug_Utilities g-debuti ads,GNAT Current_Exception g-curexc ads,The GNAT Library | |
73918baf | 23906 | @anchor{gnat_rm/the_gnat_library gnat-debug-pools-g-debpoo-ads}@anchor{34b}@anchor{gnat_rm/the_gnat_library id57}@anchor{34c} |
64d5610f ML |
23907 | @section @code{GNAT.Debug_Pools} (@code{g-debpoo.ads}) |
23908 | ||
23909 | ||
23910 | @geindex GNAT.Debug_Pools (g-debpoo.ads) | |
23911 | ||
23912 | @geindex Debugging | |
23913 | ||
23914 | @geindex Debug pools | |
23915 | ||
23916 | @geindex Memory corruption debugging | |
23917 | ||
eeba836b | 23918 | Provides a debugging storage pools that helps tracking memory corruption |
64d5610f ML |
23919 | problems. |
23920 | See @code{The GNAT Debug_Pool Facility} section in the @cite{GNAT User’s Guide}. | |
23921 | ||
23922 | @node GNAT Debug_Utilities g-debuti ads,GNAT Decode_String g-decstr ads,GNAT Debug_Pools g-debpoo ads,The GNAT Library | |
73918baf | 23923 | @anchor{gnat_rm/the_gnat_library gnat-debug-utilities-g-debuti-ads}@anchor{34d}@anchor{gnat_rm/the_gnat_library id58}@anchor{34e} |
64d5610f ML |
23924 | @section @code{GNAT.Debug_Utilities} (@code{g-debuti.ads}) |
23925 | ||
23926 | ||
23927 | @geindex GNAT.Debug_Utilities (g-debuti.ads) | |
23928 | ||
23929 | @geindex Debugging | |
23930 | ||
23931 | Provides a few useful utilities for debugging purposes, including conversion | |
23932 | to and from string images of address values. Supports both C and Ada formats | |
23933 | for hexadecimal literals. | |
23934 | ||
23935 | @node GNAT Decode_String g-decstr ads,GNAT Decode_UTF8_String g-deutst ads,GNAT Debug_Utilities g-debuti ads,The GNAT Library | |
73918baf | 23936 | @anchor{gnat_rm/the_gnat_library gnat-decode-string-g-decstr-ads}@anchor{34f}@anchor{gnat_rm/the_gnat_library id59}@anchor{350} |
64d5610f ML |
23937 | @section @code{GNAT.Decode_String} (@code{g-decstr.ads}) |
23938 | ||
23939 | ||
23940 | @geindex GNAT.Decode_String (g-decstr.ads) | |
23941 | ||
23942 | @geindex Decoding strings | |
23943 | ||
23944 | @geindex String decoding | |
23945 | ||
23946 | @geindex Wide character encoding | |
23947 | ||
23948 | @geindex UTF-8 | |
23949 | ||
23950 | @geindex Unicode | |
23951 | ||
23952 | A generic package providing routines for decoding wide character and wide wide | |
23953 | character strings encoded as sequences of 8-bit characters using a specified | |
23954 | encoding method. Includes validation routines, and also routines for stepping | |
23955 | to next or previous encoded character in an encoded string. | |
23956 | Useful in conjunction with Unicode character coding. Note there is a | |
23957 | preinstantiation for UTF-8. See next entry. | |
23958 | ||
23959 | @node GNAT Decode_UTF8_String g-deutst ads,GNAT Directory_Operations g-dirope ads,GNAT Decode_String g-decstr ads,The GNAT Library | |
73918baf | 23960 | @anchor{gnat_rm/the_gnat_library gnat-decode-utf8-string-g-deutst-ads}@anchor{351}@anchor{gnat_rm/the_gnat_library id60}@anchor{352} |
64d5610f ML |
23961 | @section @code{GNAT.Decode_UTF8_String} (@code{g-deutst.ads}) |
23962 | ||
23963 | ||
23964 | @geindex GNAT.Decode_UTF8_String (g-deutst.ads) | |
23965 | ||
23966 | @geindex Decoding strings | |
23967 | ||
23968 | @geindex Decoding UTF-8 strings | |
23969 | ||
23970 | @geindex UTF-8 string decoding | |
23971 | ||
23972 | @geindex Wide character decoding | |
23973 | ||
23974 | @geindex UTF-8 | |
23975 | ||
23976 | @geindex Unicode | |
23977 | ||
23978 | A preinstantiation of GNAT.Decode_Strings for UTF-8 encoding. | |
23979 | ||
23980 | @node GNAT Directory_Operations g-dirope ads,GNAT Directory_Operations Iteration g-diopit ads,GNAT Decode_UTF8_String g-deutst ads,The GNAT Library | |
73918baf | 23981 | @anchor{gnat_rm/the_gnat_library gnat-directory-operations-g-dirope-ads}@anchor{353}@anchor{gnat_rm/the_gnat_library id61}@anchor{354} |
64d5610f ML |
23982 | @section @code{GNAT.Directory_Operations} (@code{g-dirope.ads}) |
23983 | ||
23984 | ||
23985 | @geindex GNAT.Directory_Operations (g-dirope.ads) | |
23986 | ||
23987 | @geindex Directory operations | |
23988 | ||
23989 | Provides a set of routines for manipulating directories, including changing | |
23990 | the current directory, making new directories, and scanning the files in a | |
23991 | directory. | |
23992 | ||
23993 | @node GNAT Directory_Operations Iteration g-diopit ads,GNAT Dynamic_HTables g-dynhta ads,GNAT Directory_Operations g-dirope ads,The GNAT Library | |
73918baf | 23994 | @anchor{gnat_rm/the_gnat_library gnat-directory-operations-iteration-g-diopit-ads}@anchor{355}@anchor{gnat_rm/the_gnat_library id62}@anchor{356} |
64d5610f ML |
23995 | @section @code{GNAT.Directory_Operations.Iteration} (@code{g-diopit.ads}) |
23996 | ||
23997 | ||
23998 | @geindex GNAT.Directory_Operations.Iteration (g-diopit.ads) | |
23999 | ||
24000 | @geindex Directory operations iteration | |
24001 | ||
24002 | A child unit of GNAT.Directory_Operations providing additional operations | |
24003 | for iterating through directories. | |
24004 | ||
24005 | @node GNAT Dynamic_HTables g-dynhta ads,GNAT Dynamic_Tables g-dyntab ads,GNAT Directory_Operations Iteration g-diopit ads,The GNAT Library | |
73918baf | 24006 | @anchor{gnat_rm/the_gnat_library gnat-dynamic-htables-g-dynhta-ads}@anchor{357}@anchor{gnat_rm/the_gnat_library id63}@anchor{358} |
64d5610f ML |
24007 | @section @code{GNAT.Dynamic_HTables} (@code{g-dynhta.ads}) |
24008 | ||
24009 | ||
24010 | @geindex GNAT.Dynamic_HTables (g-dynhta.ads) | |
24011 | ||
24012 | @geindex Hash tables | |
24013 | ||
24014 | A generic implementation of hash tables that can be used to hash arbitrary | |
24015 | data. Provided in two forms, a simple form with built in hash functions, | |
24016 | and a more complex form in which the hash function is supplied. | |
24017 | ||
24018 | This package provides a facility similar to that of @code{GNAT.HTable}, | |
24019 | except that this package declares a type that can be used to define | |
24020 | dynamic instances of the hash table, while an instantiation of | |
24021 | @code{GNAT.HTable} creates a single instance of the hash table. | |
24022 | ||
24023 | @node GNAT Dynamic_Tables g-dyntab ads,GNAT Encode_String g-encstr ads,GNAT Dynamic_HTables g-dynhta ads,The GNAT Library | |
73918baf | 24024 | @anchor{gnat_rm/the_gnat_library gnat-dynamic-tables-g-dyntab-ads}@anchor{359}@anchor{gnat_rm/the_gnat_library id64}@anchor{35a} |
64d5610f ML |
24025 | @section @code{GNAT.Dynamic_Tables} (@code{g-dyntab.ads}) |
24026 | ||
24027 | ||
24028 | @geindex GNAT.Dynamic_Tables (g-dyntab.ads) | |
24029 | ||
24030 | @geindex Table implementation | |
24031 | ||
24032 | @geindex Arrays | |
24033 | @geindex extendable | |
24034 | ||
24035 | A generic package providing a single dimension array abstraction where the | |
24036 | length of the array can be dynamically modified. | |
24037 | ||
24038 | This package provides a facility similar to that of @code{GNAT.Table}, | |
24039 | except that this package declares a type that can be used to define | |
24040 | dynamic instances of the table, while an instantiation of | |
24041 | @code{GNAT.Table} creates a single instance of the table type. | |
24042 | ||
24043 | @node GNAT Encode_String g-encstr ads,GNAT Encode_UTF8_String g-enutst ads,GNAT Dynamic_Tables g-dyntab ads,The GNAT Library | |
73918baf | 24044 | @anchor{gnat_rm/the_gnat_library gnat-encode-string-g-encstr-ads}@anchor{35b}@anchor{gnat_rm/the_gnat_library id65}@anchor{35c} |
64d5610f ML |
24045 | @section @code{GNAT.Encode_String} (@code{g-encstr.ads}) |
24046 | ||
24047 | ||
24048 | @geindex GNAT.Encode_String (g-encstr.ads) | |
24049 | ||
24050 | @geindex Encoding strings | |
24051 | ||
24052 | @geindex String encoding | |
24053 | ||
24054 | @geindex Wide character encoding | |
24055 | ||
24056 | @geindex UTF-8 | |
24057 | ||
24058 | @geindex Unicode | |
24059 | ||
24060 | A generic package providing routines for encoding wide character and wide | |
24061 | wide character strings as sequences of 8-bit characters using a specified | |
24062 | encoding method. Useful in conjunction with Unicode character coding. | |
24063 | Note there is a preinstantiation for UTF-8. See next entry. | |
24064 | ||
24065 | @node GNAT Encode_UTF8_String g-enutst ads,GNAT Exception_Actions g-excact ads,GNAT Encode_String g-encstr ads,The GNAT Library | |
73918baf | 24066 | @anchor{gnat_rm/the_gnat_library gnat-encode-utf8-string-g-enutst-ads}@anchor{35d}@anchor{gnat_rm/the_gnat_library id66}@anchor{35e} |
64d5610f ML |
24067 | @section @code{GNAT.Encode_UTF8_String} (@code{g-enutst.ads}) |
24068 | ||
24069 | ||
24070 | @geindex GNAT.Encode_UTF8_String (g-enutst.ads) | |
24071 | ||
24072 | @geindex Encoding strings | |
24073 | ||
24074 | @geindex Encoding UTF-8 strings | |
24075 | ||
24076 | @geindex UTF-8 string encoding | |
24077 | ||
24078 | @geindex Wide character encoding | |
24079 | ||
24080 | @geindex UTF-8 | |
24081 | ||
24082 | @geindex Unicode | |
24083 | ||
24084 | A preinstantiation of GNAT.Encode_Strings for UTF-8 encoding. | |
24085 | ||
24086 | @node GNAT Exception_Actions g-excact ads,GNAT Exception_Traces g-exctra ads,GNAT Encode_UTF8_String g-enutst ads,The GNAT Library | |
73918baf | 24087 | @anchor{gnat_rm/the_gnat_library gnat-exception-actions-g-excact-ads}@anchor{35f}@anchor{gnat_rm/the_gnat_library id67}@anchor{360} |
64d5610f ML |
24088 | @section @code{GNAT.Exception_Actions} (@code{g-excact.ads}) |
24089 | ||
24090 | ||
24091 | @geindex GNAT.Exception_Actions (g-excact.ads) | |
24092 | ||
24093 | @geindex Exception actions | |
24094 | ||
24095 | Provides callbacks when an exception is raised. Callbacks can be registered | |
24096 | for specific exceptions, or when any exception is raised. This | |
24097 | can be used for instance to force a core dump to ease debugging. | |
24098 | ||
24099 | @node GNAT Exception_Traces g-exctra ads,GNAT Exceptions g-except ads,GNAT Exception_Actions g-excact ads,The GNAT Library | |
73918baf | 24100 | @anchor{gnat_rm/the_gnat_library gnat-exception-traces-g-exctra-ads}@anchor{361}@anchor{gnat_rm/the_gnat_library id68}@anchor{362} |
64d5610f ML |
24101 | @section @code{GNAT.Exception_Traces} (@code{g-exctra.ads}) |
24102 | ||
24103 | ||
24104 | @geindex GNAT.Exception_Traces (g-exctra.ads) | |
24105 | ||
24106 | @geindex Exception traces | |
24107 | ||
24108 | @geindex Debugging | |
24109 | ||
24110 | Provides an interface allowing to control automatic output upon exception | |
24111 | occurrences. | |
24112 | ||
24113 | @node GNAT Exceptions g-except ads,GNAT Expect g-expect ads,GNAT Exception_Traces g-exctra ads,The GNAT Library | |
73918baf | 24114 | @anchor{gnat_rm/the_gnat_library gnat-exceptions-g-except-ads}@anchor{363}@anchor{gnat_rm/the_gnat_library id69}@anchor{364} |
64d5610f ML |
24115 | @section @code{GNAT.Exceptions} (@code{g-except.ads}) |
24116 | ||
24117 | ||
24118 | @geindex GNAT.Exceptions (g-except.ads) | |
24119 | ||
24120 | @geindex Exceptions | |
24121 | @geindex Pure | |
24122 | ||
24123 | @geindex Pure packages | |
24124 | @geindex exceptions | |
24125 | ||
24126 | Normally it is not possible to raise an exception with | |
24127 | a message from a subprogram in a pure package, since the | |
24128 | necessary types and subprograms are in @code{Ada.Exceptions} | |
24129 | which is not a pure unit. @code{GNAT.Exceptions} provides a | |
24130 | facility for getting around this limitation for a few | |
eeba836b | 24131 | predefined exceptions, and for example allows raising |
64d5610f ML |
24132 | @code{Constraint_Error} with a message from a pure subprogram. |
24133 | ||
24134 | @node GNAT Expect g-expect ads,GNAT Expect TTY g-exptty ads,GNAT Exceptions g-except ads,The GNAT Library | |
73918baf | 24135 | @anchor{gnat_rm/the_gnat_library gnat-expect-g-expect-ads}@anchor{365}@anchor{gnat_rm/the_gnat_library id70}@anchor{366} |
64d5610f ML |
24136 | @section @code{GNAT.Expect} (@code{g-expect.ads}) |
24137 | ||
24138 | ||
24139 | @geindex GNAT.Expect (g-expect.ads) | |
24140 | ||
24141 | Provides a set of subprograms similar to what is available | |
24142 | with the standard Tcl Expect tool. | |
24143 | It allows you to easily spawn and communicate with an external process. | |
24144 | You can send commands or inputs to the process, and compare the output | |
24145 | with some expected regular expression. Currently @code{GNAT.Expect} | |
24146 | is implemented on all native GNAT ports. | |
24147 | It is not implemented for cross ports, and in particular is not | |
24148 | implemented for VxWorks or LynxOS. | |
24149 | ||
24150 | @node GNAT Expect TTY g-exptty ads,GNAT Float_Control g-flocon ads,GNAT Expect g-expect ads,The GNAT Library | |
73918baf | 24151 | @anchor{gnat_rm/the_gnat_library gnat-expect-tty-g-exptty-ads}@anchor{367}@anchor{gnat_rm/the_gnat_library id71}@anchor{368} |
64d5610f ML |
24152 | @section @code{GNAT.Expect.TTY} (@code{g-exptty.ads}) |
24153 | ||
24154 | ||
24155 | @geindex GNAT.Expect.TTY (g-exptty.ads) | |
24156 | ||
24157 | As GNAT.Expect but using pseudo-terminal. | |
24158 | Currently @code{GNAT.Expect.TTY} is implemented on all native GNAT | |
24159 | ports. It is not implemented for cross ports, and | |
24160 | in particular is not implemented for VxWorks or LynxOS. | |
24161 | ||
24162 | @node GNAT Float_Control g-flocon ads,GNAT Formatted_String g-forstr ads,GNAT Expect TTY g-exptty ads,The GNAT Library | |
73918baf | 24163 | @anchor{gnat_rm/the_gnat_library gnat-float-control-g-flocon-ads}@anchor{369}@anchor{gnat_rm/the_gnat_library id72}@anchor{36a} |
64d5610f ML |
24164 | @section @code{GNAT.Float_Control} (@code{g-flocon.ads}) |
24165 | ||
24166 | ||
24167 | @geindex GNAT.Float_Control (g-flocon.ads) | |
24168 | ||
24169 | @geindex Floating-Point Processor | |
24170 | ||
24171 | Provides an interface for resetting the floating-point processor into the | |
24172 | mode required for correct semantic operation in Ada. Some third party | |
24173 | library calls may cause this mode to be modified, and the Reset procedure | |
24174 | in this package can be used to reestablish the required mode. | |
24175 | ||
24176 | @node GNAT Formatted_String g-forstr ads,GNAT Generic_Fast_Math_Functions g-gfmafu ads,GNAT Float_Control g-flocon ads,The GNAT Library | |
73918baf | 24177 | @anchor{gnat_rm/the_gnat_library gnat-formatted-string-g-forstr-ads}@anchor{36b}@anchor{gnat_rm/the_gnat_library id73}@anchor{36c} |
64d5610f ML |
24178 | @section @code{GNAT.Formatted_String} (@code{g-forstr.ads}) |
24179 | ||
24180 | ||
24181 | @geindex GNAT.Formatted_String (g-forstr.ads) | |
24182 | ||
24183 | @geindex Formatted String | |
24184 | ||
24185 | Provides support for C/C++ printf() formatted strings. The format is | |
eeba836b | 24186 | copied from the printf() routine and should therefore give identical |
64d5610f ML |
24187 | output. Some generic routines are provided to be able to use types |
24188 | derived from Integer, Float or enumerations as values for the | |
24189 | formatted string. | |
24190 | ||
24191 | @node GNAT Generic_Fast_Math_Functions g-gfmafu ads,GNAT Heap_Sort g-heasor ads,GNAT Formatted_String g-forstr ads,The GNAT Library | |
73918baf | 24192 | @anchor{gnat_rm/the_gnat_library gnat-generic-fast-math-functions-g-gfmafu-ads}@anchor{36d}@anchor{gnat_rm/the_gnat_library id74}@anchor{36e} |
64d5610f ML |
24193 | @section @code{GNAT.Generic_Fast_Math_Functions} (@code{g-gfmafu.ads}) |
24194 | ||
24195 | ||
24196 | @geindex GNAT.Generic_Fast_Math_Functions (g-gfmafu.ads) | |
24197 | ||
24198 | @geindex Mathematical functions | |
24199 | ||
24200 | Provides direct access to the underlying implementation of the common | |
24201 | mathematical functions, generally from the system mathematical library. | |
24202 | This differs from @code{Ada.Numerics.Generic_Elementary_Functions} in that | |
24203 | the implementation may deviate from the semantics specified for these | |
24204 | functions in the Reference Manual, for example @code{Numerics.Argument_Error} | |
24205 | is not raised. On selected platforms, some of these functions may also | |
24206 | have a vector implementation that can be automatically used by the | |
24207 | compiler when auto-vectorization is enabled. | |
24208 | ||
24209 | @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 | |
73918baf | 24210 | @anchor{gnat_rm/the_gnat_library gnat-heap-sort-g-heasor-ads}@anchor{36f}@anchor{gnat_rm/the_gnat_library id75}@anchor{370} |
64d5610f ML |
24211 | @section @code{GNAT.Heap_Sort} (@code{g-heasor.ads}) |
24212 | ||
24213 | ||
24214 | @geindex GNAT.Heap_Sort (g-heasor.ads) | |
24215 | ||
24216 | @geindex Sorting | |
24217 | ||
24218 | Provides a general implementation of heap sort usable for sorting arbitrary | |
24219 | data items. Exchange and comparison procedures are provided by passing | |
24220 | access-to-procedure values. The algorithm used is a modified heap sort | |
24221 | that performs approximately N*log(N) comparisons in the worst case. | |
24222 | ||
24223 | @node GNAT Heap_Sort_A g-hesora ads,GNAT Heap_Sort_G g-hesorg ads,GNAT Heap_Sort g-heasor ads,The GNAT Library | |
73918baf | 24224 | @anchor{gnat_rm/the_gnat_library gnat-heap-sort-a-g-hesora-ads}@anchor{371}@anchor{gnat_rm/the_gnat_library id76}@anchor{372} |
64d5610f ML |
24225 | @section @code{GNAT.Heap_Sort_A} (@code{g-hesora.ads}) |
24226 | ||
24227 | ||
24228 | @geindex GNAT.Heap_Sort_A (g-hesora.ads) | |
24229 | ||
24230 | @geindex Sorting | |
24231 | ||
24232 | Provides a general implementation of heap sort usable for sorting arbitrary | |
24233 | data items. Move and comparison procedures are provided by passing | |
24234 | access-to-procedure values. The algorithm used is a modified heap sort | |
24235 | that performs approximately N*log(N) comparisons in the worst case. | |
24236 | This differs from @code{GNAT.Heap_Sort} in having a less convenient | |
24237 | interface, but may be slightly more efficient. | |
24238 | ||
24239 | @node GNAT Heap_Sort_G g-hesorg ads,GNAT HTable g-htable ads,GNAT Heap_Sort_A g-hesora ads,The GNAT Library | |
73918baf | 24240 | @anchor{gnat_rm/the_gnat_library gnat-heap-sort-g-g-hesorg-ads}@anchor{373}@anchor{gnat_rm/the_gnat_library id77}@anchor{374} |
64d5610f ML |
24241 | @section @code{GNAT.Heap_Sort_G} (@code{g-hesorg.ads}) |
24242 | ||
24243 | ||
24244 | @geindex GNAT.Heap_Sort_G (g-hesorg.ads) | |
24245 | ||
24246 | @geindex Sorting | |
24247 | ||
24248 | Similar to @code{Heap_Sort_A} except that the move and sorting procedures | |
24249 | are provided as generic parameters, this improves efficiency, especially | |
24250 | if the procedures can be inlined, at the expense of duplicating code for | |
24251 | multiple instantiations. | |
24252 | ||
24253 | @node GNAT HTable g-htable ads,GNAT IO g-io ads,GNAT Heap_Sort_G g-hesorg ads,The GNAT Library | |
73918baf | 24254 | @anchor{gnat_rm/the_gnat_library gnat-htable-g-htable-ads}@anchor{375}@anchor{gnat_rm/the_gnat_library id78}@anchor{376} |
64d5610f ML |
24255 | @section @code{GNAT.HTable} (@code{g-htable.ads}) |
24256 | ||
24257 | ||
24258 | @geindex GNAT.HTable (g-htable.ads) | |
24259 | ||
24260 | @geindex Hash tables | |
24261 | ||
24262 | A generic implementation of hash tables that can be used to hash arbitrary | |
24263 | data. Provides two approaches, one a simple static approach, and the other | |
24264 | allowing arbitrary dynamic hash tables. | |
24265 | ||
24266 | @node GNAT IO g-io ads,GNAT IO_Aux g-io_aux ads,GNAT HTable g-htable ads,The GNAT Library | |
73918baf | 24267 | @anchor{gnat_rm/the_gnat_library gnat-io-g-io-ads}@anchor{377}@anchor{gnat_rm/the_gnat_library id79}@anchor{378} |
64d5610f ML |
24268 | @section @code{GNAT.IO} (@code{g-io.ads}) |
24269 | ||
24270 | ||
24271 | @geindex GNAT.IO (g-io.ads) | |
24272 | ||
24273 | @geindex Simple I/O | |
24274 | ||
24275 | @geindex Input/Output facilities | |
24276 | ||
24277 | A simple preelaborable input-output package that provides a subset of | |
24278 | simple Text_IO functions for reading characters and strings from | |
24279 | Standard_Input, and writing characters, strings and integers to either | |
24280 | Standard_Output or Standard_Error. | |
24281 | ||
24282 | @node GNAT IO_Aux g-io_aux ads,GNAT Lock_Files g-locfil ads,GNAT IO g-io ads,The GNAT Library | |
73918baf | 24283 | @anchor{gnat_rm/the_gnat_library gnat-io-aux-g-io-aux-ads}@anchor{379}@anchor{gnat_rm/the_gnat_library id80}@anchor{37a} |
64d5610f ML |
24284 | @section @code{GNAT.IO_Aux} (@code{g-io_aux.ads}) |
24285 | ||
24286 | ||
24287 | @geindex GNAT.IO_Aux (g-io_aux.ads) | |
24288 | ||
24289 | @geindex Text_IO | |
24290 | ||
24291 | @geindex Input/Output facilities | |
24292 | ||
24293 | Provides some auxiliary functions for use with Text_IO, including a test | |
24294 | for whether a file exists, and functions for reading a line of text. | |
24295 | ||
24296 | @node GNAT Lock_Files g-locfil ads,GNAT MBBS_Discrete_Random g-mbdira ads,GNAT IO_Aux g-io_aux ads,The GNAT Library | |
73918baf | 24297 | @anchor{gnat_rm/the_gnat_library gnat-lock-files-g-locfil-ads}@anchor{37b}@anchor{gnat_rm/the_gnat_library id81}@anchor{37c} |
64d5610f ML |
24298 | @section @code{GNAT.Lock_Files} (@code{g-locfil.ads}) |
24299 | ||
24300 | ||
24301 | @geindex GNAT.Lock_Files (g-locfil.ads) | |
24302 | ||
24303 | @geindex File locking | |
24304 | ||
24305 | @geindex Locking using files | |
24306 | ||
24307 | Provides a general interface for using files as locks. Can be used for | |
24308 | providing program level synchronization. | |
24309 | ||
24310 | @node GNAT MBBS_Discrete_Random g-mbdira ads,GNAT MBBS_Float_Random g-mbflra ads,GNAT Lock_Files g-locfil ads,The GNAT Library | |
73918baf | 24311 | @anchor{gnat_rm/the_gnat_library gnat-mbbs-discrete-random-g-mbdira-ads}@anchor{37d}@anchor{gnat_rm/the_gnat_library id82}@anchor{37e} |
64d5610f ML |
24312 | @section @code{GNAT.MBBS_Discrete_Random} (@code{g-mbdira.ads}) |
24313 | ||
24314 | ||
24315 | @geindex GNAT.MBBS_Discrete_Random (g-mbdira.ads) | |
24316 | ||
24317 | @geindex Random number generation | |
24318 | ||
24319 | The original implementation of @code{Ada.Numerics.Discrete_Random}. Uses | |
24320 | a modified version of the Blum-Blum-Shub generator. | |
24321 | ||
24322 | @node GNAT MBBS_Float_Random g-mbflra ads,GNAT MD5 g-md5 ads,GNAT MBBS_Discrete_Random g-mbdira ads,The GNAT Library | |
73918baf | 24323 | @anchor{gnat_rm/the_gnat_library gnat-mbbs-float-random-g-mbflra-ads}@anchor{37f}@anchor{gnat_rm/the_gnat_library id83}@anchor{380} |
64d5610f ML |
24324 | @section @code{GNAT.MBBS_Float_Random} (@code{g-mbflra.ads}) |
24325 | ||
24326 | ||
24327 | @geindex GNAT.MBBS_Float_Random (g-mbflra.ads) | |
24328 | ||
24329 | @geindex Random number generation | |
24330 | ||
24331 | The original implementation of @code{Ada.Numerics.Float_Random}. Uses | |
24332 | a modified version of the Blum-Blum-Shub generator. | |
24333 | ||
24334 | @node GNAT MD5 g-md5 ads,GNAT Memory_Dump g-memdum ads,GNAT MBBS_Float_Random g-mbflra ads,The GNAT Library | |
73918baf | 24335 | @anchor{gnat_rm/the_gnat_library gnat-md5-g-md5-ads}@anchor{381}@anchor{gnat_rm/the_gnat_library id84}@anchor{382} |
64d5610f ML |
24336 | @section @code{GNAT.MD5} (@code{g-md5.ads}) |
24337 | ||
24338 | ||
24339 | @geindex GNAT.MD5 (g-md5.ads) | |
24340 | ||
24341 | @geindex Message Digest MD5 | |
24342 | ||
24343 | Implements the MD5 Message-Digest Algorithm as described in RFC 1321, and | |
24344 | the HMAC-MD5 message authentication function as described in RFC 2104 and | |
24345 | FIPS PUB 198. | |
24346 | ||
24347 | @node GNAT Memory_Dump g-memdum ads,GNAT Most_Recent_Exception g-moreex ads,GNAT MD5 g-md5 ads,The GNAT Library | |
73918baf | 24348 | @anchor{gnat_rm/the_gnat_library gnat-memory-dump-g-memdum-ads}@anchor{383}@anchor{gnat_rm/the_gnat_library id85}@anchor{384} |
64d5610f ML |
24349 | @section @code{GNAT.Memory_Dump} (@code{g-memdum.ads}) |
24350 | ||
24351 | ||
24352 | @geindex GNAT.Memory_Dump (g-memdum.ads) | |
24353 | ||
24354 | @geindex Dump Memory | |
24355 | ||
24356 | Provides a convenient routine for dumping raw memory to either the | |
24357 | standard output or standard error files. Uses GNAT.IO for actual | |
24358 | output. | |
24359 | ||
24360 | @node GNAT Most_Recent_Exception g-moreex ads,GNAT OS_Lib g-os_lib ads,GNAT Memory_Dump g-memdum ads,The GNAT Library | |
73918baf | 24361 | @anchor{gnat_rm/the_gnat_library gnat-most-recent-exception-g-moreex-ads}@anchor{385}@anchor{gnat_rm/the_gnat_library id86}@anchor{386} |
64d5610f ML |
24362 | @section @code{GNAT.Most_Recent_Exception} (@code{g-moreex.ads}) |
24363 | ||
24364 | ||
24365 | @geindex GNAT.Most_Recent_Exception (g-moreex.ads) | |
24366 | ||
24367 | @geindex Exception | |
24368 | @geindex obtaining most recent | |
24369 | ||
24370 | Provides access to the most recently raised exception. Can be used for | |
24371 | various logging purposes, including duplicating functionality of some | |
24372 | Ada 83 implementation dependent extensions. | |
24373 | ||
24374 | @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 | |
73918baf | 24375 | @anchor{gnat_rm/the_gnat_library gnat-os-lib-g-os-lib-ads}@anchor{387}@anchor{gnat_rm/the_gnat_library id87}@anchor{388} |
64d5610f ML |
24376 | @section @code{GNAT.OS_Lib} (@code{g-os_lib.ads}) |
24377 | ||
24378 | ||
24379 | @geindex GNAT.OS_Lib (g-os_lib.ads) | |
24380 | ||
24381 | @geindex Operating System interface | |
24382 | ||
24383 | @geindex Spawn capability | |
24384 | ||
24385 | Provides a range of target independent operating system interface functions, | |
24386 | including time/date management, file operations, subprocess management, | |
24387 | including a portable spawn procedure, and access to environment variables | |
24388 | and error return codes. | |
24389 | ||
24390 | @node GNAT Perfect_Hash_Generators g-pehage ads,GNAT Random_Numbers g-rannum ads,GNAT OS_Lib g-os_lib ads,The GNAT Library | |
73918baf | 24391 | @anchor{gnat_rm/the_gnat_library gnat-perfect-hash-generators-g-pehage-ads}@anchor{389}@anchor{gnat_rm/the_gnat_library id88}@anchor{38a} |
64d5610f ML |
24392 | @section @code{GNAT.Perfect_Hash_Generators} (@code{g-pehage.ads}) |
24393 | ||
24394 | ||
24395 | @geindex GNAT.Perfect_Hash_Generators (g-pehage.ads) | |
24396 | ||
24397 | @geindex Hash functions | |
24398 | ||
24399 | Provides a generator of static minimal perfect hash functions. No | |
24400 | collisions occur and each item can be retrieved from the table in one | |
24401 | probe (perfect property). The hash table size corresponds to the exact | |
24402 | size of the key set and no larger (minimal property). The key set has to | |
eeba836b | 24403 | be known in advance (static property). The hash functions are also order |
64d5610f ML |
24404 | preserving. If w2 is inserted after w1 in the generator, their |
24405 | hashcode are in the same order. These hashing functions are very | |
24406 | convenient for use with realtime applications. | |
24407 | ||
24408 | @node GNAT Random_Numbers g-rannum ads,GNAT Regexp g-regexp ads,GNAT Perfect_Hash_Generators g-pehage ads,The GNAT Library | |
73918baf | 24409 | @anchor{gnat_rm/the_gnat_library gnat-random-numbers-g-rannum-ads}@anchor{38b}@anchor{gnat_rm/the_gnat_library id89}@anchor{38c} |
64d5610f ML |
24410 | @section @code{GNAT.Random_Numbers} (@code{g-rannum.ads}) |
24411 | ||
24412 | ||
24413 | @geindex GNAT.Random_Numbers (g-rannum.ads) | |
24414 | ||
24415 | @geindex Random number generation | |
24416 | ||
24417 | Provides random number capabilities which extend those available in the | |
24418 | standard Ada library and are more convenient to use. | |
24419 | ||
24420 | @node GNAT Regexp g-regexp ads,GNAT Registry g-regist ads,GNAT Random_Numbers g-rannum ads,The GNAT Library | |
73918baf | 24421 | @anchor{gnat_rm/the_gnat_library gnat-regexp-g-regexp-ads}@anchor{262}@anchor{gnat_rm/the_gnat_library id90}@anchor{38d} |
64d5610f ML |
24422 | @section @code{GNAT.Regexp} (@code{g-regexp.ads}) |
24423 | ||
24424 | ||
24425 | @geindex GNAT.Regexp (g-regexp.ads) | |
24426 | ||
24427 | @geindex Regular expressions | |
24428 | ||
24429 | @geindex Pattern matching | |
24430 | ||
24431 | A simple implementation of regular expressions, using a subset of regular | |
24432 | expression syntax copied from familiar Unix style utilities. This is the | |
24433 | simplest of the three pattern matching packages provided, and is particularly | |
24434 | suitable for ‘file globbing’ applications. | |
24435 | ||
24436 | @node GNAT Registry g-regist ads,GNAT Regpat g-regpat ads,GNAT Regexp g-regexp ads,The GNAT Library | |
73918baf | 24437 | @anchor{gnat_rm/the_gnat_library gnat-registry-g-regist-ads}@anchor{38e}@anchor{gnat_rm/the_gnat_library id91}@anchor{38f} |
64d5610f ML |
24438 | @section @code{GNAT.Registry} (@code{g-regist.ads}) |
24439 | ||
24440 | ||
24441 | @geindex GNAT.Registry (g-regist.ads) | |
24442 | ||
24443 | @geindex Windows Registry | |
24444 | ||
24445 | This is a high level binding to the Windows registry. It is possible to | |
24446 | do simple things like reading a key value, creating a new key. For full | |
24447 | registry API, but at a lower level of abstraction, refer to the Win32.Winreg | |
24448 | package provided with the Win32Ada binding | |
24449 | ||
24450 | @node GNAT Regpat g-regpat ads,GNAT Rewrite_Data g-rewdat ads,GNAT Registry g-regist ads,The GNAT Library | |
73918baf | 24451 | @anchor{gnat_rm/the_gnat_library gnat-regpat-g-regpat-ads}@anchor{390}@anchor{gnat_rm/the_gnat_library id92}@anchor{391} |
64d5610f ML |
24452 | @section @code{GNAT.Regpat} (@code{g-regpat.ads}) |
24453 | ||
24454 | ||
24455 | @geindex GNAT.Regpat (g-regpat.ads) | |
24456 | ||
24457 | @geindex Regular expressions | |
24458 | ||
24459 | @geindex Pattern matching | |
24460 | ||
24461 | A complete implementation of Unix-style regular expression matching, copied | |
24462 | from the original V7 style regular expression library written in C by | |
24463 | Henry Spencer (and binary compatible with this C library). | |
24464 | ||
24465 | @node GNAT Rewrite_Data g-rewdat ads,GNAT Secondary_Stack_Info g-sestin ads,GNAT Regpat g-regpat ads,The GNAT Library | |
73918baf | 24466 | @anchor{gnat_rm/the_gnat_library gnat-rewrite-data-g-rewdat-ads}@anchor{392}@anchor{gnat_rm/the_gnat_library id93}@anchor{393} |
64d5610f ML |
24467 | @section @code{GNAT.Rewrite_Data} (@code{g-rewdat.ads}) |
24468 | ||
24469 | ||
24470 | @geindex GNAT.Rewrite_Data (g-rewdat.ads) | |
24471 | ||
24472 | @geindex Rewrite data | |
24473 | ||
24474 | A unit to rewrite on-the-fly string occurrences in a stream of | |
24475 | data. The implementation has a very minimal memory footprint as the | |
24476 | full content to be processed is not loaded into memory all at once. This makes | |
24477 | this interface usable for large files or socket streams. | |
24478 | ||
24479 | @node GNAT Secondary_Stack_Info g-sestin ads,GNAT Semaphores g-semaph ads,GNAT Rewrite_Data g-rewdat ads,The GNAT Library | |
73918baf | 24480 | @anchor{gnat_rm/the_gnat_library gnat-secondary-stack-info-g-sestin-ads}@anchor{394}@anchor{gnat_rm/the_gnat_library id94}@anchor{395} |
64d5610f ML |
24481 | @section @code{GNAT.Secondary_Stack_Info} (@code{g-sestin.ads}) |
24482 | ||
24483 | ||
24484 | @geindex GNAT.Secondary_Stack_Info (g-sestin.ads) | |
24485 | ||
24486 | @geindex Secondary Stack Info | |
24487 | ||
eeba836b | 24488 | Provides the capability to query the high water mark of the current task’s |
64d5610f ML |
24489 | secondary stack. |
24490 | ||
24491 | @node GNAT Semaphores g-semaph ads,GNAT Serial_Communications g-sercom ads,GNAT Secondary_Stack_Info g-sestin ads,The GNAT Library | |
73918baf | 24492 | @anchor{gnat_rm/the_gnat_library gnat-semaphores-g-semaph-ads}@anchor{396}@anchor{gnat_rm/the_gnat_library id95}@anchor{397} |
64d5610f ML |
24493 | @section @code{GNAT.Semaphores} (@code{g-semaph.ads}) |
24494 | ||
24495 | ||
24496 | @geindex GNAT.Semaphores (g-semaph.ads) | |
24497 | ||
24498 | @geindex Semaphores | |
24499 | ||
24500 | Provides classic counting and binary semaphores using protected types. | |
24501 | ||
24502 | @node GNAT Serial_Communications g-sercom ads,GNAT SHA1 g-sha1 ads,GNAT Semaphores g-semaph ads,The GNAT Library | |
73918baf | 24503 | @anchor{gnat_rm/the_gnat_library gnat-serial-communications-g-sercom-ads}@anchor{398}@anchor{gnat_rm/the_gnat_library id96}@anchor{399} |
64d5610f ML |
24504 | @section @code{GNAT.Serial_Communications} (@code{g-sercom.ads}) |
24505 | ||
24506 | ||
24507 | @geindex GNAT.Serial_Communications (g-sercom.ads) | |
24508 | ||
24509 | @geindex Serial_Communications | |
24510 | ||
24511 | Provides a simple interface to send and receive data over a serial | |
24512 | port. This is only supported on GNU/Linux and Windows. | |
24513 | ||
24514 | @node GNAT SHA1 g-sha1 ads,GNAT SHA224 g-sha224 ads,GNAT Serial_Communications g-sercom ads,The GNAT Library | |
73918baf | 24515 | @anchor{gnat_rm/the_gnat_library gnat-sha1-g-sha1-ads}@anchor{39a}@anchor{gnat_rm/the_gnat_library id97}@anchor{39b} |
64d5610f ML |
24516 | @section @code{GNAT.SHA1} (@code{g-sha1.ads}) |
24517 | ||
24518 | ||
24519 | @geindex GNAT.SHA1 (g-sha1.ads) | |
24520 | ||
24521 | @geindex Secure Hash Algorithm SHA-1 | |
24522 | ||
24523 | Implements the SHA-1 Secure Hash Algorithm as described in FIPS PUB 180-3 | |
24524 | and RFC 3174, and the HMAC-SHA1 message authentication function as described | |
24525 | in RFC 2104 and FIPS PUB 198. | |
24526 | ||
24527 | @node GNAT SHA224 g-sha224 ads,GNAT SHA256 g-sha256 ads,GNAT SHA1 g-sha1 ads,The GNAT Library | |
73918baf | 24528 | @anchor{gnat_rm/the_gnat_library gnat-sha224-g-sha224-ads}@anchor{39c}@anchor{gnat_rm/the_gnat_library id98}@anchor{39d} |
64d5610f ML |
24529 | @section @code{GNAT.SHA224} (@code{g-sha224.ads}) |
24530 | ||
24531 | ||
24532 | @geindex GNAT.SHA224 (g-sha224.ads) | |
24533 | ||
24534 | @geindex Secure Hash Algorithm SHA-224 | |
24535 | ||
24536 | Implements the SHA-224 Secure Hash Algorithm as described in FIPS PUB 180-3, | |
24537 | and the HMAC-SHA224 message authentication function as described | |
24538 | in RFC 2104 and FIPS PUB 198. | |
24539 | ||
24540 | @node GNAT SHA256 g-sha256 ads,GNAT SHA384 g-sha384 ads,GNAT SHA224 g-sha224 ads,The GNAT Library | |
73918baf | 24541 | @anchor{gnat_rm/the_gnat_library gnat-sha256-g-sha256-ads}@anchor{39e}@anchor{gnat_rm/the_gnat_library id99}@anchor{39f} |
64d5610f ML |
24542 | @section @code{GNAT.SHA256} (@code{g-sha256.ads}) |
24543 | ||
24544 | ||
24545 | @geindex GNAT.SHA256 (g-sha256.ads) | |
24546 | ||
24547 | @geindex Secure Hash Algorithm SHA-256 | |
24548 | ||
24549 | Implements the SHA-256 Secure Hash Algorithm as described in FIPS PUB 180-3, | |
24550 | and the HMAC-SHA256 message authentication function as described | |
24551 | in RFC 2104 and FIPS PUB 198. | |
24552 | ||
24553 | @node GNAT SHA384 g-sha384 ads,GNAT SHA512 g-sha512 ads,GNAT SHA256 g-sha256 ads,The GNAT Library | |
73918baf | 24554 | @anchor{gnat_rm/the_gnat_library gnat-sha384-g-sha384-ads}@anchor{3a0}@anchor{gnat_rm/the_gnat_library id100}@anchor{3a1} |
64d5610f ML |
24555 | @section @code{GNAT.SHA384} (@code{g-sha384.ads}) |
24556 | ||
24557 | ||
24558 | @geindex GNAT.SHA384 (g-sha384.ads) | |
24559 | ||
24560 | @geindex Secure Hash Algorithm SHA-384 | |
24561 | ||
24562 | Implements the SHA-384 Secure Hash Algorithm as described in FIPS PUB 180-3, | |
24563 | and the HMAC-SHA384 message authentication function as described | |
24564 | in RFC 2104 and FIPS PUB 198. | |
24565 | ||
24566 | @node GNAT SHA512 g-sha512 ads,GNAT Signals g-signal ads,GNAT SHA384 g-sha384 ads,The GNAT Library | |
73918baf | 24567 | @anchor{gnat_rm/the_gnat_library gnat-sha512-g-sha512-ads}@anchor{3a2}@anchor{gnat_rm/the_gnat_library id101}@anchor{3a3} |
64d5610f ML |
24568 | @section @code{GNAT.SHA512} (@code{g-sha512.ads}) |
24569 | ||
24570 | ||
24571 | @geindex GNAT.SHA512 (g-sha512.ads) | |
24572 | ||
24573 | @geindex Secure Hash Algorithm SHA-512 | |
24574 | ||
24575 | Implements the SHA-512 Secure Hash Algorithm as described in FIPS PUB 180-3, | |
24576 | and the HMAC-SHA512 message authentication function as described | |
24577 | in RFC 2104 and FIPS PUB 198. | |
24578 | ||
24579 | @node GNAT Signals g-signal ads,GNAT Sockets g-socket ads,GNAT SHA512 g-sha512 ads,The GNAT Library | |
73918baf | 24580 | @anchor{gnat_rm/the_gnat_library gnat-signals-g-signal-ads}@anchor{3a4}@anchor{gnat_rm/the_gnat_library id102}@anchor{3a5} |
64d5610f ML |
24581 | @section @code{GNAT.Signals} (@code{g-signal.ads}) |
24582 | ||
24583 | ||
24584 | @geindex GNAT.Signals (g-signal.ads) | |
24585 | ||
24586 | @geindex Signals | |
24587 | ||
24588 | Provides the ability to manipulate the blocked status of signals on supported | |
24589 | targets. | |
24590 | ||
24591 | @node GNAT Sockets g-socket ads,GNAT Source_Info g-souinf ads,GNAT Signals g-signal ads,The GNAT Library | |
73918baf | 24592 | @anchor{gnat_rm/the_gnat_library gnat-sockets-g-socket-ads}@anchor{3a6}@anchor{gnat_rm/the_gnat_library id103}@anchor{3a7} |
64d5610f ML |
24593 | @section @code{GNAT.Sockets} (@code{g-socket.ads}) |
24594 | ||
24595 | ||
24596 | @geindex GNAT.Sockets (g-socket.ads) | |
24597 | ||
24598 | @geindex Sockets | |
24599 | ||
24600 | A high level and portable interface to develop sockets based applications. | |
24601 | This package is based on the sockets thin binding found in | |
24602 | @code{GNAT.Sockets.Thin}. Currently @code{GNAT.Sockets} is implemented | |
eeba836b | 24603 | on all native GNAT ports and on VxWorks cross ports. It is not implemented for |
64d5610f ML |
24604 | the LynxOS cross port. |
24605 | ||
24606 | @node GNAT Source_Info g-souinf ads,GNAT Spelling_Checker g-speche ads,GNAT Sockets g-socket ads,The GNAT Library | |
73918baf | 24607 | @anchor{gnat_rm/the_gnat_library gnat-source-info-g-souinf-ads}@anchor{3a8}@anchor{gnat_rm/the_gnat_library id104}@anchor{3a9} |
64d5610f ML |
24608 | @section @code{GNAT.Source_Info} (@code{g-souinf.ads}) |
24609 | ||
24610 | ||
24611 | @geindex GNAT.Source_Info (g-souinf.ads) | |
24612 | ||
24613 | @geindex Source Information | |
24614 | ||
24615 | Provides subprograms that give access to source code information known at | |
24616 | compile time, such as the current file name and line number. Also provides | |
24617 | subprograms yielding the date and time of the current compilation (like the | |
24618 | C macros @code{__DATE__} and @code{__TIME__}) | |
24619 | ||
24620 | @node GNAT Spelling_Checker g-speche ads,GNAT Spelling_Checker_Generic g-spchge ads,GNAT Source_Info g-souinf ads,The GNAT Library | |
73918baf | 24621 | @anchor{gnat_rm/the_gnat_library gnat-spelling-checker-g-speche-ads}@anchor{3aa}@anchor{gnat_rm/the_gnat_library id105}@anchor{3ab} |
64d5610f ML |
24622 | @section @code{GNAT.Spelling_Checker} (@code{g-speche.ads}) |
24623 | ||
24624 | ||
24625 | @geindex GNAT.Spelling_Checker (g-speche.ads) | |
24626 | ||
24627 | @geindex Spell checking | |
24628 | ||
24629 | Provides a function for determining whether one string is a plausible | |
24630 | near misspelling of another string. | |
24631 | ||
24632 | @node GNAT Spelling_Checker_Generic g-spchge ads,GNAT Spitbol Patterns g-spipat ads,GNAT Spelling_Checker g-speche ads,The GNAT Library | |
73918baf | 24633 | @anchor{gnat_rm/the_gnat_library gnat-spelling-checker-generic-g-spchge-ads}@anchor{3ac}@anchor{gnat_rm/the_gnat_library id106}@anchor{3ad} |
64d5610f ML |
24634 | @section @code{GNAT.Spelling_Checker_Generic} (@code{g-spchge.ads}) |
24635 | ||
24636 | ||
24637 | @geindex GNAT.Spelling_Checker_Generic (g-spchge.ads) | |
24638 | ||
24639 | @geindex Spell checking | |
24640 | ||
24641 | Provides a generic function that can be instantiated with a string type for | |
24642 | determining whether one string is a plausible near misspelling of another | |
24643 | string. | |
24644 | ||
24645 | @node GNAT Spitbol Patterns g-spipat ads,GNAT Spitbol g-spitbo ads,GNAT Spelling_Checker_Generic g-spchge ads,The GNAT Library | |
73918baf | 24646 | @anchor{gnat_rm/the_gnat_library gnat-spitbol-patterns-g-spipat-ads}@anchor{3ae}@anchor{gnat_rm/the_gnat_library id107}@anchor{3af} |
64d5610f ML |
24647 | @section @code{GNAT.Spitbol.Patterns} (@code{g-spipat.ads}) |
24648 | ||
24649 | ||
24650 | @geindex GNAT.Spitbol.Patterns (g-spipat.ads) | |
24651 | ||
24652 | @geindex SPITBOL pattern matching | |
24653 | ||
24654 | @geindex Pattern matching | |
24655 | ||
24656 | A complete implementation of SNOBOL4 style pattern matching. This is the | |
24657 | most elaborate of the pattern matching packages provided. It fully duplicates | |
24658 | the SNOBOL4 dynamic pattern construction and matching capabilities, using the | |
24659 | efficient algorithm developed by Robert Dewar for the SPITBOL system. | |
24660 | ||
24661 | @node GNAT Spitbol g-spitbo ads,GNAT Spitbol Table_Boolean g-sptabo ads,GNAT Spitbol Patterns g-spipat ads,The GNAT Library | |
73918baf | 24662 | @anchor{gnat_rm/the_gnat_library gnat-spitbol-g-spitbo-ads}@anchor{3b0}@anchor{gnat_rm/the_gnat_library id108}@anchor{3b1} |
64d5610f ML |
24663 | @section @code{GNAT.Spitbol} (@code{g-spitbo.ads}) |
24664 | ||
24665 | ||
24666 | @geindex GNAT.Spitbol (g-spitbo.ads) | |
24667 | ||
24668 | @geindex SPITBOL interface | |
24669 | ||
24670 | The top level package of the collection of SPITBOL-style functionality, this | |
24671 | package provides basic SNOBOL4 string manipulation functions, such as | |
24672 | Pad, Reverse, Trim, Substr capability, as well as a generic table function | |
24673 | useful for constructing arbitrary mappings from strings in the style of | |
24674 | the SNOBOL4 TABLE function. | |
24675 | ||
24676 | @node GNAT Spitbol Table_Boolean g-sptabo ads,GNAT Spitbol Table_Integer g-sptain ads,GNAT Spitbol g-spitbo ads,The GNAT Library | |
73918baf | 24677 | @anchor{gnat_rm/the_gnat_library gnat-spitbol-table-boolean-g-sptabo-ads}@anchor{3b2}@anchor{gnat_rm/the_gnat_library id109}@anchor{3b3} |
64d5610f ML |
24678 | @section @code{GNAT.Spitbol.Table_Boolean} (@code{g-sptabo.ads}) |
24679 | ||
24680 | ||
24681 | @geindex GNAT.Spitbol.Table_Boolean (g-sptabo.ads) | |
24682 | ||
24683 | @geindex Sets of strings | |
24684 | ||
24685 | @geindex SPITBOL Tables | |
24686 | ||
24687 | A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table} | |
24688 | for type @code{Standard.Boolean}, giving an implementation of sets of | |
24689 | string values. | |
24690 | ||
24691 | @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 | |
73918baf | 24692 | @anchor{gnat_rm/the_gnat_library gnat-spitbol-table-integer-g-sptain-ads}@anchor{3b4}@anchor{gnat_rm/the_gnat_library id110}@anchor{3b5} |
64d5610f ML |
24693 | @section @code{GNAT.Spitbol.Table_Integer} (@code{g-sptain.ads}) |
24694 | ||
24695 | ||
24696 | @geindex GNAT.Spitbol.Table_Integer (g-sptain.ads) | |
24697 | ||
24698 | @geindex Integer maps | |
24699 | ||
24700 | @geindex Maps | |
24701 | ||
24702 | @geindex SPITBOL Tables | |
24703 | ||
24704 | A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table} | |
24705 | for type @code{Standard.Integer}, giving an implementation of maps | |
24706 | from string to integer values. | |
24707 | ||
24708 | @node GNAT Spitbol Table_VString g-sptavs ads,GNAT SSE g-sse ads,GNAT Spitbol Table_Integer g-sptain ads,The GNAT Library | |
73918baf | 24709 | @anchor{gnat_rm/the_gnat_library gnat-spitbol-table-vstring-g-sptavs-ads}@anchor{3b6}@anchor{gnat_rm/the_gnat_library id111}@anchor{3b7} |
64d5610f ML |
24710 | @section @code{GNAT.Spitbol.Table_VString} (@code{g-sptavs.ads}) |
24711 | ||
24712 | ||
24713 | @geindex GNAT.Spitbol.Table_VString (g-sptavs.ads) | |
24714 | ||
24715 | @geindex String maps | |
24716 | ||
24717 | @geindex Maps | |
24718 | ||
24719 | @geindex SPITBOL Tables | |
24720 | ||
24721 | A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table} for | |
24722 | a variable length string type, giving an implementation of general | |
24723 | maps from strings to strings. | |
24724 | ||
24725 | @node GNAT SSE g-sse ads,GNAT SSE Vector_Types g-ssvety ads,GNAT Spitbol Table_VString g-sptavs ads,The GNAT Library | |
73918baf | 24726 | @anchor{gnat_rm/the_gnat_library gnat-sse-g-sse-ads}@anchor{3b8}@anchor{gnat_rm/the_gnat_library id112}@anchor{3b9} |
64d5610f ML |
24727 | @section @code{GNAT.SSE} (@code{g-sse.ads}) |
24728 | ||
24729 | ||
24730 | @geindex GNAT.SSE (g-sse.ads) | |
24731 | ||
24732 | Root of a set of units aimed at offering Ada bindings to a subset of | |
24733 | the Intel(r) Streaming SIMD Extensions with GNAT on the x86 family of | |
24734 | targets. It exposes vector component types together with a general | |
24735 | introduction to the binding contents and use. | |
24736 | ||
24737 | @node GNAT SSE Vector_Types g-ssvety ads,GNAT String_Hash g-strhas ads,GNAT SSE g-sse ads,The GNAT Library | |
73918baf | 24738 | @anchor{gnat_rm/the_gnat_library gnat-sse-vector-types-g-ssvety-ads}@anchor{3ba}@anchor{gnat_rm/the_gnat_library id113}@anchor{3bb} |
64d5610f ML |
24739 | @section @code{GNAT.SSE.Vector_Types} (@code{g-ssvety.ads}) |
24740 | ||
24741 | ||
24742 | @geindex GNAT.SSE.Vector_Types (g-ssvety.ads) | |
24743 | ||
24744 | SSE vector types for use with SSE related intrinsics. | |
24745 | ||
24746 | @node GNAT String_Hash g-strhas ads,GNAT Strings g-string ads,GNAT SSE Vector_Types g-ssvety ads,The GNAT Library | |
73918baf | 24747 | @anchor{gnat_rm/the_gnat_library gnat-string-hash-g-strhas-ads}@anchor{3bc}@anchor{gnat_rm/the_gnat_library id114}@anchor{3bd} |
64d5610f ML |
24748 | @section @code{GNAT.String_Hash} (@code{g-strhas.ads}) |
24749 | ||
24750 | ||
24751 | @geindex GNAT.String_Hash (g-strhas.ads) | |
24752 | ||
24753 | @geindex Hash functions | |
24754 | ||
24755 | Provides a generic hash function working on arrays of scalars. Both the scalar | |
24756 | type and the hash result type are parameters. | |
24757 | ||
24758 | @node GNAT Strings g-string ads,GNAT String_Split g-strspl ads,GNAT String_Hash g-strhas ads,The GNAT Library | |
73918baf | 24759 | @anchor{gnat_rm/the_gnat_library gnat-strings-g-string-ads}@anchor{3be}@anchor{gnat_rm/the_gnat_library id115}@anchor{3bf} |
64d5610f ML |
24760 | @section @code{GNAT.Strings} (@code{g-string.ads}) |
24761 | ||
24762 | ||
24763 | @geindex GNAT.Strings (g-string.ads) | |
24764 | ||
24765 | Common String access types and related subprograms. Basically it | |
24766 | defines a string access and an array of string access types. | |
24767 | ||
24768 | @node GNAT String_Split g-strspl ads,GNAT Table g-table ads,GNAT Strings g-string ads,The GNAT Library | |
73918baf | 24769 | @anchor{gnat_rm/the_gnat_library gnat-string-split-g-strspl-ads}@anchor{3c0}@anchor{gnat_rm/the_gnat_library id116}@anchor{3c1} |
64d5610f ML |
24770 | @section @code{GNAT.String_Split} (@code{g-strspl.ads}) |
24771 | ||
24772 | ||
24773 | @geindex GNAT.String_Split (g-strspl.ads) | |
24774 | ||
24775 | @geindex String splitter | |
24776 | ||
24777 | Useful string manipulation routines: given a set of separators, split | |
24778 | a string wherever the separators appear, and provide direct access | |
24779 | to the resulting slices. This package is instantiated from | |
24780 | @code{GNAT.Array_Split}. | |
24781 | ||
24782 | @node GNAT Table g-table ads,GNAT Task_Lock g-tasloc ads,GNAT String_Split g-strspl ads,The GNAT Library | |
73918baf | 24783 | @anchor{gnat_rm/the_gnat_library gnat-table-g-table-ads}@anchor{3c2}@anchor{gnat_rm/the_gnat_library id117}@anchor{3c3} |
64d5610f ML |
24784 | @section @code{GNAT.Table} (@code{g-table.ads}) |
24785 | ||
24786 | ||
24787 | @geindex GNAT.Table (g-table.ads) | |
24788 | ||
24789 | @geindex Table implementation | |
24790 | ||
24791 | @geindex Arrays | |
24792 | @geindex extendable | |
24793 | ||
24794 | A generic package providing a single dimension array abstraction where the | |
24795 | length of the array can be dynamically modified. | |
24796 | ||
24797 | This package provides a facility similar to that of @code{GNAT.Dynamic_Tables}, | |
24798 | except that this package declares a single instance of the table type, | |
24799 | while an instantiation of @code{GNAT.Dynamic_Tables} creates a type that can be | |
24800 | used to define dynamic instances of the table. | |
24801 | ||
24802 | @node GNAT Task_Lock g-tasloc ads,GNAT Time_Stamp g-timsta ads,GNAT Table g-table ads,The GNAT Library | |
73918baf | 24803 | @anchor{gnat_rm/the_gnat_library gnat-task-lock-g-tasloc-ads}@anchor{3c4}@anchor{gnat_rm/the_gnat_library id118}@anchor{3c5} |
64d5610f ML |
24804 | @section @code{GNAT.Task_Lock} (@code{g-tasloc.ads}) |
24805 | ||
24806 | ||
24807 | @geindex GNAT.Task_Lock (g-tasloc.ads) | |
24808 | ||
24809 | @geindex Task synchronization | |
24810 | ||
24811 | @geindex Task locking | |
24812 | ||
24813 | @geindex Locking | |
24814 | ||
24815 | A very simple facility for locking and unlocking sections of code using a | |
24816 | single global task lock. Appropriate for use in situations where contention | |
24817 | between tasks is very rarely expected. | |
24818 | ||
24819 | @node GNAT Time_Stamp g-timsta ads,GNAT Threads g-thread ads,GNAT Task_Lock g-tasloc ads,The GNAT Library | |
73918baf | 24820 | @anchor{gnat_rm/the_gnat_library gnat-time-stamp-g-timsta-ads}@anchor{3c6}@anchor{gnat_rm/the_gnat_library id119}@anchor{3c7} |
64d5610f ML |
24821 | @section @code{GNAT.Time_Stamp} (@code{g-timsta.ads}) |
24822 | ||
24823 | ||
24824 | @geindex GNAT.Time_Stamp (g-timsta.ads) | |
24825 | ||
24826 | @geindex Time stamp | |
24827 | ||
24828 | @geindex Current time | |
24829 | ||
24830 | Provides a simple function that returns a string YYYY-MM-DD HH:MM:SS.SS that | |
24831 | represents the current date and time in ISO 8601 format. This is a very simple | |
24832 | routine with minimal code and there are no dependencies on any other unit. | |
24833 | ||
24834 | @node GNAT Threads g-thread ads,GNAT Traceback g-traceb ads,GNAT Time_Stamp g-timsta ads,The GNAT Library | |
73918baf | 24835 | @anchor{gnat_rm/the_gnat_library gnat-threads-g-thread-ads}@anchor{3c8}@anchor{gnat_rm/the_gnat_library id120}@anchor{3c9} |
64d5610f ML |
24836 | @section @code{GNAT.Threads} (@code{g-thread.ads}) |
24837 | ||
24838 | ||
24839 | @geindex GNAT.Threads (g-thread.ads) | |
24840 | ||
24841 | @geindex Foreign threads | |
24842 | ||
24843 | @geindex Threads | |
24844 | @geindex foreign | |
24845 | ||
24846 | Provides facilities for dealing with foreign threads which need to be known | |
24847 | by the GNAT run-time system. Consult the documentation of this package for | |
24848 | further details if your program has threads that are created by a non-Ada | |
24849 | environment which then accesses Ada code. | |
24850 | ||
24851 | @node GNAT Traceback g-traceb ads,GNAT Traceback Symbolic g-trasym ads,GNAT Threads g-thread ads,The GNAT Library | |
73918baf | 24852 | @anchor{gnat_rm/the_gnat_library gnat-traceback-g-traceb-ads}@anchor{3ca}@anchor{gnat_rm/the_gnat_library id121}@anchor{3cb} |
64d5610f ML |
24853 | @section @code{GNAT.Traceback} (@code{g-traceb.ads}) |
24854 | ||
24855 | ||
24856 | @geindex GNAT.Traceback (g-traceb.ads) | |
24857 | ||
24858 | @geindex Trace back facilities | |
24859 | ||
24860 | Provides a facility for obtaining non-symbolic traceback information, useful | |
24861 | in various debugging situations. | |
24862 | ||
eeba836b | 24863 | @node GNAT Traceback Symbolic g-trasym ads,GNAT UTF_32 g-utf_32 ads,GNAT Traceback g-traceb ads,The GNAT Library |
73918baf | 24864 | @anchor{gnat_rm/the_gnat_library gnat-traceback-symbolic-g-trasym-ads}@anchor{3cc}@anchor{gnat_rm/the_gnat_library id122}@anchor{3cd} |
64d5610f ML |
24865 | @section @code{GNAT.Traceback.Symbolic} (@code{g-trasym.ads}) |
24866 | ||
24867 | ||
24868 | @geindex GNAT.Traceback.Symbolic (g-trasym.ads) | |
24869 | ||
24870 | @geindex Trace back facilities | |
24871 | ||
eeba836b | 24872 | @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 |
73918baf | 24873 | @anchor{gnat_rm/the_gnat_library gnat-utf-32-g-utf-32-ads}@anchor{3ce}@anchor{gnat_rm/the_gnat_library id123}@anchor{3cf} |
eeba836b | 24874 | @section @code{GNAT.UTF_32} (@code{g-utf_32.ads}) |
64d5610f ML |
24875 | |
24876 | ||
eeba836b | 24877 | @geindex GNAT.UTF_32 (g-utf_32.ads) |
64d5610f ML |
24878 | |
24879 | @geindex Wide character codes | |
24880 | ||
24881 | This is a package intended to be used in conjunction with the | |
24882 | @code{Wide_Character} type in Ada 95 and the | |
24883 | @code{Wide_Wide_Character} type in Ada 2005 (available | |
24884 | in @code{GNAT} in Ada 2005 mode). This package contains | |
24885 | Unicode categorization routines, as well as lexical | |
24886 | categorization routines corresponding to the Ada 2005 | |
24887 | lexical rules for identifiers and strings, and also a | |
24888 | lower case to upper case fold routine corresponding to | |
24889 | the Ada 2005 rules for identifier equivalence. | |
24890 | ||
eeba836b | 24891 | @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 |
73918baf | 24892 | @anchor{gnat_rm/the_gnat_library gnat-utf-32-spelling-checker-g-u3spch-ads}@anchor{3d0}@anchor{gnat_rm/the_gnat_library id124}@anchor{3d1} |
eeba836b | 24893 | @section @code{GNAT.UTF_32_Spelling_Checker} (@code{g-u3spch.ads}) |
64d5610f ML |
24894 | |
24895 | ||
eeba836b | 24896 | @geindex GNAT.UTF_32_Spelling_Checker (g-u3spch.ads) |
64d5610f ML |
24897 | |
24898 | @geindex Spell checking | |
24899 | ||
24900 | Provides a function for determining whether one wide wide string is a plausible | |
24901 | near misspelling of another wide wide string, where the strings are represented | |
24902 | using the UTF_32_String type defined in System.Wch_Cnv. | |
24903 | ||
eeba836b | 24904 | @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 |
73918baf | 24905 | @anchor{gnat_rm/the_gnat_library gnat-wide-spelling-checker-g-wispch-ads}@anchor{3d2}@anchor{gnat_rm/the_gnat_library id125}@anchor{3d3} |
64d5610f ML |
24906 | @section @code{GNAT.Wide_Spelling_Checker} (@code{g-wispch.ads}) |
24907 | ||
24908 | ||
24909 | @geindex GNAT.Wide_Spelling_Checker (g-wispch.ads) | |
24910 | ||
24911 | @geindex Spell checking | |
24912 | ||
24913 | Provides a function for determining whether one wide string is a plausible | |
24914 | near misspelling of another wide string. | |
24915 | ||
24916 | @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 | |
73918baf | 24917 | @anchor{gnat_rm/the_gnat_library gnat-wide-string-split-g-wistsp-ads}@anchor{3d4}@anchor{gnat_rm/the_gnat_library id126}@anchor{3d5} |
64d5610f ML |
24918 | @section @code{GNAT.Wide_String_Split} (@code{g-wistsp.ads}) |
24919 | ||
24920 | ||
24921 | @geindex GNAT.Wide_String_Split (g-wistsp.ads) | |
24922 | ||
24923 | @geindex Wide_String splitter | |
24924 | ||
24925 | Useful wide string manipulation routines: given a set of separators, split | |
24926 | a wide string wherever the separators appear, and provide direct access | |
24927 | to the resulting slices. This package is instantiated from | |
24928 | @code{GNAT.Array_Split}. | |
24929 | ||
24930 | @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 | |
73918baf | 24931 | @anchor{gnat_rm/the_gnat_library gnat-wide-wide-spelling-checker-g-zspche-ads}@anchor{3d6}@anchor{gnat_rm/the_gnat_library id127}@anchor{3d7} |
64d5610f ML |
24932 | @section @code{GNAT.Wide_Wide_Spelling_Checker} (@code{g-zspche.ads}) |
24933 | ||
24934 | ||
24935 | @geindex GNAT.Wide_Wide_Spelling_Checker (g-zspche.ads) | |
24936 | ||
24937 | @geindex Spell checking | |
24938 | ||
24939 | Provides a function for determining whether one wide wide string is a plausible | |
24940 | near misspelling of another wide wide string. | |
24941 | ||
24942 | @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 | |
73918baf | 24943 | @anchor{gnat_rm/the_gnat_library gnat-wide-wide-string-split-g-zistsp-ads}@anchor{3d8}@anchor{gnat_rm/the_gnat_library id128}@anchor{3d9} |
64d5610f ML |
24944 | @section @code{GNAT.Wide_Wide_String_Split} (@code{g-zistsp.ads}) |
24945 | ||
24946 | ||
24947 | @geindex GNAT.Wide_Wide_String_Split (g-zistsp.ads) | |
24948 | ||
24949 | @geindex Wide_Wide_String splitter | |
24950 | ||
24951 | Useful wide wide string manipulation routines: given a set of separators, split | |
24952 | a wide wide string wherever the separators appear, and provide direct access | |
24953 | to the resulting slices. This package is instantiated from | |
24954 | @code{GNAT.Array_Split}. | |
24955 | ||
24956 | @node Interfaces C Extensions i-cexten ads,Interfaces C Streams i-cstrea ads,GNAT Wide_Wide_String_Split g-zistsp ads,The GNAT Library | |
73918baf | 24957 | @anchor{gnat_rm/the_gnat_library id129}@anchor{3da}@anchor{gnat_rm/the_gnat_library interfaces-c-extensions-i-cexten-ads}@anchor{3db} |
64d5610f ML |
24958 | @section @code{Interfaces.C.Extensions} (@code{i-cexten.ads}) |
24959 | ||
24960 | ||
24961 | @geindex Interfaces.C.Extensions (i-cexten.ads) | |
24962 | ||
24963 | This package contains additional C-related definitions, intended | |
24964 | for use with either manually or automatically generated bindings | |
24965 | to C libraries. | |
24966 | ||
24967 | @node Interfaces C Streams i-cstrea ads,Interfaces Packed_Decimal i-pacdec ads,Interfaces C Extensions i-cexten ads,The GNAT Library | |
73918baf | 24968 | @anchor{gnat_rm/the_gnat_library id130}@anchor{3dc}@anchor{gnat_rm/the_gnat_library interfaces-c-streams-i-cstrea-ads}@anchor{3dd} |
64d5610f ML |
24969 | @section @code{Interfaces.C.Streams} (@code{i-cstrea.ads}) |
24970 | ||
24971 | ||
24972 | @geindex Interfaces.C.Streams (i-cstrea.ads) | |
24973 | ||
24974 | @geindex C streams | |
24975 | @geindex interfacing | |
24976 | ||
24977 | This package is a binding for the most commonly used operations | |
24978 | on C streams. | |
24979 | ||
24980 | @node Interfaces Packed_Decimal i-pacdec ads,Interfaces VxWorks i-vxwork ads,Interfaces C Streams i-cstrea ads,The GNAT Library | |
73918baf | 24981 | @anchor{gnat_rm/the_gnat_library id131}@anchor{3de}@anchor{gnat_rm/the_gnat_library interfaces-packed-decimal-i-pacdec-ads}@anchor{3df} |
64d5610f ML |
24982 | @section @code{Interfaces.Packed_Decimal} (@code{i-pacdec.ads}) |
24983 | ||
24984 | ||
24985 | @geindex Interfaces.Packed_Decimal (i-pacdec.ads) | |
24986 | ||
24987 | @geindex IBM Packed Format | |
24988 | ||
24989 | @geindex Packed Decimal | |
24990 | ||
24991 | This package provides a set of routines for conversions to and | |
24992 | from a packed decimal format compatible with that used on IBM | |
24993 | mainframes. | |
24994 | ||
24995 | @node Interfaces VxWorks i-vxwork ads,Interfaces VxWorks Int_Connection i-vxinco ads,Interfaces Packed_Decimal i-pacdec ads,The GNAT Library | |
73918baf | 24996 | @anchor{gnat_rm/the_gnat_library id132}@anchor{3e0}@anchor{gnat_rm/the_gnat_library interfaces-vxworks-i-vxwork-ads}@anchor{3e1} |
64d5610f ML |
24997 | @section @code{Interfaces.VxWorks} (@code{i-vxwork.ads}) |
24998 | ||
24999 | ||
25000 | @geindex Interfaces.VxWorks (i-vxwork.ads) | |
25001 | ||
25002 | @geindex Interfacing to VxWorks | |
25003 | ||
25004 | @geindex VxWorks | |
25005 | @geindex interfacing | |
25006 | ||
25007 | This package provides a limited binding to the VxWorks API. | |
25008 | In particular, it interfaces with the | |
25009 | VxWorks hardware interrupt facilities. | |
25010 | ||
25011 | @node Interfaces VxWorks Int_Connection i-vxinco ads,Interfaces VxWorks IO i-vxwoio ads,Interfaces VxWorks i-vxwork ads,The GNAT Library | |
73918baf | 25012 | @anchor{gnat_rm/the_gnat_library id133}@anchor{3e2}@anchor{gnat_rm/the_gnat_library interfaces-vxworks-int-connection-i-vxinco-ads}@anchor{3e3} |
64d5610f ML |
25013 | @section @code{Interfaces.VxWorks.Int_Connection} (@code{i-vxinco.ads}) |
25014 | ||
25015 | ||
25016 | @geindex Interfaces.VxWorks.Int_Connection (i-vxinco.ads) | |
25017 | ||
25018 | @geindex Interfacing to VxWorks | |
25019 | ||
25020 | @geindex VxWorks | |
25021 | @geindex interfacing | |
25022 | ||
25023 | This package provides a way for users to replace the use of | |
25024 | intConnect() with a custom routine for installing interrupt | |
25025 | handlers. | |
25026 | ||
25027 | @node Interfaces VxWorks IO i-vxwoio ads,System Address_Image s-addima ads,Interfaces VxWorks Int_Connection i-vxinco ads,The GNAT Library | |
73918baf | 25028 | @anchor{gnat_rm/the_gnat_library id134}@anchor{3e4}@anchor{gnat_rm/the_gnat_library interfaces-vxworks-io-i-vxwoio-ads}@anchor{3e5} |
64d5610f ML |
25029 | @section @code{Interfaces.VxWorks.IO} (@code{i-vxwoio.ads}) |
25030 | ||
25031 | ||
25032 | @geindex Interfaces.VxWorks.IO (i-vxwoio.ads) | |
25033 | ||
25034 | @geindex Interfacing to VxWorks' I/O | |
25035 | ||
25036 | @geindex VxWorks | |
25037 | @geindex I/O interfacing | |
25038 | ||
25039 | @geindex VxWorks | |
25040 | @geindex Get_Immediate | |
25041 | ||
25042 | @geindex Get_Immediate | |
25043 | @geindex VxWorks | |
25044 | ||
25045 | This package provides a binding to the ioctl (IO/Control) | |
25046 | function of VxWorks, defining a set of option values and | |
25047 | function codes. A particular use of this package is | |
25048 | to enable the use of Get_Immediate under VxWorks. | |
25049 | ||
25050 | @node System Address_Image s-addima ads,System Assertions s-assert ads,Interfaces VxWorks IO i-vxwoio ads,The GNAT Library | |
73918baf | 25051 | @anchor{gnat_rm/the_gnat_library id135}@anchor{3e6}@anchor{gnat_rm/the_gnat_library system-address-image-s-addima-ads}@anchor{3e7} |
64d5610f ML |
25052 | @section @code{System.Address_Image} (@code{s-addima.ads}) |
25053 | ||
25054 | ||
25055 | @geindex System.Address_Image (s-addima.ads) | |
25056 | ||
25057 | @geindex Address image | |
25058 | ||
25059 | @geindex Image | |
25060 | @geindex of an address | |
25061 | ||
25062 | This function provides a useful debugging | |
25063 | function that gives an (implementation dependent) | |
25064 | string which identifies an address. | |
25065 | ||
25066 | @node System Assertions s-assert ads,System Atomic_Counters s-atocou ads,System Address_Image s-addima ads,The GNAT Library | |
73918baf | 25067 | @anchor{gnat_rm/the_gnat_library id136}@anchor{3e8}@anchor{gnat_rm/the_gnat_library system-assertions-s-assert-ads}@anchor{3e9} |
64d5610f ML |
25068 | @section @code{System.Assertions} (@code{s-assert.ads}) |
25069 | ||
25070 | ||
25071 | @geindex System.Assertions (s-assert.ads) | |
25072 | ||
25073 | @geindex Assertions | |
25074 | ||
25075 | @geindex Assert_Failure | |
25076 | @geindex exception | |
25077 | ||
25078 | This package provides the declaration of the exception raised | |
25079 | by an run-time assertion failure, as well as the routine that | |
25080 | is used internally to raise this assertion. | |
25081 | ||
25082 | @node System Atomic_Counters s-atocou ads,System Memory s-memory ads,System Assertions s-assert ads,The GNAT Library | |
73918baf | 25083 | @anchor{gnat_rm/the_gnat_library id137}@anchor{3ea}@anchor{gnat_rm/the_gnat_library system-atomic-counters-s-atocou-ads}@anchor{3eb} |
64d5610f ML |
25084 | @section @code{System.Atomic_Counters} (@code{s-atocou.ads}) |
25085 | ||
25086 | ||
25087 | @geindex System.Atomic_Counters (s-atocou.ads) | |
25088 | ||
25089 | This package provides the declaration of an atomic counter type, | |
25090 | together with efficient routines (using hardware | |
25091 | synchronization primitives) for incrementing, decrementing, | |
25092 | and testing of these counters. This package is implemented | |
25093 | on most targets, including all Alpha, AARCH64, ARM, ia64, PowerPC, SPARC V9, | |
25094 | x86, and x86_64 platforms. | |
25095 | ||
25096 | @node System Memory s-memory ads,System Multiprocessors s-multip ads,System Atomic_Counters s-atocou ads,The GNAT Library | |
73918baf | 25097 | @anchor{gnat_rm/the_gnat_library id138}@anchor{3ec}@anchor{gnat_rm/the_gnat_library system-memory-s-memory-ads}@anchor{3ed} |
64d5610f ML |
25098 | @section @code{System.Memory} (@code{s-memory.ads}) |
25099 | ||
25100 | ||
25101 | @geindex System.Memory (s-memory.ads) | |
25102 | ||
25103 | @geindex Memory allocation | |
25104 | ||
25105 | This package provides the interface to the low level routines used | |
25106 | by the generated code for allocation and freeing storage for the | |
25107 | default storage pool (analogous to the C routines malloc and free). | |
25108 | It also provides a reallocation interface analogous to the C routine | |
25109 | realloc. The body of this unit may be modified to provide alternative | |
25110 | allocation mechanisms for the default pool, and in addition, direct | |
25111 | calls to this unit may be made for low level allocation uses (for | |
25112 | example see the body of @code{GNAT.Tables}). | |
25113 | ||
25114 | @node System Multiprocessors s-multip ads,System Multiprocessors Dispatching_Domains s-mudido ads,System Memory s-memory ads,The GNAT Library | |
73918baf | 25115 | @anchor{gnat_rm/the_gnat_library id139}@anchor{3ee}@anchor{gnat_rm/the_gnat_library system-multiprocessors-s-multip-ads}@anchor{3ef} |
64d5610f ML |
25116 | @section @code{System.Multiprocessors} (@code{s-multip.ads}) |
25117 | ||
25118 | ||
25119 | @geindex System.Multiprocessors (s-multip.ads) | |
25120 | ||
25121 | @geindex Multiprocessor interface | |
25122 | ||
25123 | This is an Ada 2012 unit defined in the Ada 2012 Reference Manual, but | |
25124 | in GNAT we also make it available in Ada 95 and Ada 2005 (where it is | |
25125 | technically an implementation-defined addition). | |
25126 | ||
25127 | @node System Multiprocessors Dispatching_Domains s-mudido ads,System Partition_Interface s-parint ads,System Multiprocessors s-multip ads,The GNAT Library | |
73918baf | 25128 | @anchor{gnat_rm/the_gnat_library id140}@anchor{3f0}@anchor{gnat_rm/the_gnat_library system-multiprocessors-dispatching-domains-s-mudido-ads}@anchor{3f1} |
64d5610f ML |
25129 | @section @code{System.Multiprocessors.Dispatching_Domains} (@code{s-mudido.ads}) |
25130 | ||
25131 | ||
25132 | @geindex System.Multiprocessors.Dispatching_Domains (s-mudido.ads) | |
25133 | ||
25134 | @geindex Multiprocessor interface | |
25135 | ||
25136 | This is an Ada 2012 unit defined in the Ada 2012 Reference Manual, but | |
25137 | in GNAT we also make it available in Ada 95 and Ada 2005 (where it is | |
25138 | technically an implementation-defined addition). | |
25139 | ||
25140 | @node System Partition_Interface s-parint ads,System Pool_Global s-pooglo ads,System Multiprocessors Dispatching_Domains s-mudido ads,The GNAT Library | |
73918baf | 25141 | @anchor{gnat_rm/the_gnat_library id141}@anchor{3f2}@anchor{gnat_rm/the_gnat_library system-partition-interface-s-parint-ads}@anchor{3f3} |
64d5610f ML |
25142 | @section @code{System.Partition_Interface} (@code{s-parint.ads}) |
25143 | ||
25144 | ||
25145 | @geindex System.Partition_Interface (s-parint.ads) | |
25146 | ||
25147 | @geindex Partition interfacing functions | |
25148 | ||
25149 | This package provides facilities for partition interfacing. It | |
25150 | is used primarily in a distribution context when using Annex E | |
25151 | with @code{GLADE}. | |
25152 | ||
25153 | @node System Pool_Global s-pooglo ads,System Pool_Local s-pooloc ads,System Partition_Interface s-parint ads,The GNAT Library | |
73918baf | 25154 | @anchor{gnat_rm/the_gnat_library id142}@anchor{3f4}@anchor{gnat_rm/the_gnat_library system-pool-global-s-pooglo-ads}@anchor{3f5} |
64d5610f ML |
25155 | @section @code{System.Pool_Global} (@code{s-pooglo.ads}) |
25156 | ||
25157 | ||
25158 | @geindex System.Pool_Global (s-pooglo.ads) | |
25159 | ||
25160 | @geindex Storage pool | |
25161 | @geindex global | |
25162 | ||
25163 | @geindex Global storage pool | |
25164 | ||
25165 | This package provides a storage pool that is equivalent to the default | |
25166 | storage pool used for access types for which no pool is specifically | |
25167 | declared. It uses malloc/free to allocate/free and does not attempt to | |
25168 | do any automatic reclamation. | |
25169 | ||
25170 | @node System Pool_Local s-pooloc ads,System Restrictions s-restri ads,System Pool_Global s-pooglo ads,The GNAT Library | |
73918baf | 25171 | @anchor{gnat_rm/the_gnat_library id143}@anchor{3f6}@anchor{gnat_rm/the_gnat_library system-pool-local-s-pooloc-ads}@anchor{3f7} |
64d5610f ML |
25172 | @section @code{System.Pool_Local} (@code{s-pooloc.ads}) |
25173 | ||
25174 | ||
25175 | @geindex System.Pool_Local (s-pooloc.ads) | |
25176 | ||
25177 | @geindex Storage pool | |
25178 | @geindex local | |
25179 | ||
25180 | @geindex Local storage pool | |
25181 | ||
25182 | This package provides a storage pool that is intended for use with locally | |
25183 | defined access types. It uses malloc/free for allocate/free, and maintains | |
25184 | a list of allocated blocks, so that all storage allocated for the pool can | |
25185 | be freed automatically when the pool is finalized. | |
25186 | ||
25187 | @node System Restrictions s-restri ads,System Rident s-rident ads,System Pool_Local s-pooloc ads,The GNAT Library | |
73918baf | 25188 | @anchor{gnat_rm/the_gnat_library id144}@anchor{3f8}@anchor{gnat_rm/the_gnat_library system-restrictions-s-restri-ads}@anchor{3f9} |
64d5610f ML |
25189 | @section @code{System.Restrictions} (@code{s-restri.ads}) |
25190 | ||
25191 | ||
25192 | @geindex System.Restrictions (s-restri.ads) | |
25193 | ||
25194 | @geindex Run-time restrictions access | |
25195 | ||
25196 | This package provides facilities for accessing at run time | |
25197 | the status of restrictions specified at compile time for | |
25198 | the partition. Information is available both with regard | |
25199 | to actual restrictions specified, and with regard to | |
25200 | compiler determined information on which restrictions | |
25201 | are violated by one or more packages in the partition. | |
25202 | ||
25203 | @node System Rident s-rident ads,System Strings Stream_Ops s-ststop ads,System Restrictions s-restri ads,The GNAT Library | |
73918baf | 25204 | @anchor{gnat_rm/the_gnat_library id145}@anchor{3fa}@anchor{gnat_rm/the_gnat_library system-rident-s-rident-ads}@anchor{3fb} |
64d5610f ML |
25205 | @section @code{System.Rident} (@code{s-rident.ads}) |
25206 | ||
25207 | ||
25208 | @geindex System.Rident (s-rident.ads) | |
25209 | ||
25210 | @geindex Restrictions definitions | |
25211 | ||
25212 | This package provides definitions of the restrictions | |
25213 | identifiers supported by GNAT, and also the format of | |
25214 | the restrictions provided in package System.Restrictions. | |
25215 | It is not normally necessary to @code{with} this generic package | |
25216 | since the necessary instantiation is included in | |
25217 | package System.Restrictions. | |
25218 | ||
25219 | @node System Strings Stream_Ops s-ststop ads,System Unsigned_Types s-unstyp ads,System Rident s-rident ads,The GNAT Library | |
73918baf | 25220 | @anchor{gnat_rm/the_gnat_library id146}@anchor{3fc}@anchor{gnat_rm/the_gnat_library system-strings-stream-ops-s-ststop-ads}@anchor{3fd} |
64d5610f ML |
25221 | @section @code{System.Strings.Stream_Ops} (@code{s-ststop.ads}) |
25222 | ||
25223 | ||
25224 | @geindex System.Strings.Stream_Ops (s-ststop.ads) | |
25225 | ||
25226 | @geindex Stream operations | |
25227 | ||
25228 | @geindex String stream operations | |
25229 | ||
25230 | This package provides a set of stream subprograms for standard string types. | |
25231 | It is intended primarily to support implicit use of such subprograms when | |
25232 | stream attributes are applied to string types, but the subprograms in this | |
25233 | package can be used directly by application programs. | |
25234 | ||
25235 | @node System Unsigned_Types s-unstyp ads,System Wch_Cnv s-wchcnv ads,System Strings Stream_Ops s-ststop ads,The GNAT Library | |
73918baf | 25236 | @anchor{gnat_rm/the_gnat_library id147}@anchor{3fe}@anchor{gnat_rm/the_gnat_library system-unsigned-types-s-unstyp-ads}@anchor{3ff} |
64d5610f ML |
25237 | @section @code{System.Unsigned_Types} (@code{s-unstyp.ads}) |
25238 | ||
25239 | ||
25240 | @geindex System.Unsigned_Types (s-unstyp.ads) | |
25241 | ||
25242 | This package contains definitions of standard unsigned types that | |
25243 | correspond in size to the standard signed types declared in Standard, | |
25244 | and (unlike the types in Interfaces) have corresponding names. It | |
25245 | also contains some related definitions for other specialized types | |
25246 | used by the compiler in connection with packed array types. | |
25247 | ||
25248 | @node System Wch_Cnv s-wchcnv ads,System Wch_Con s-wchcon ads,System Unsigned_Types s-unstyp ads,The GNAT Library | |
73918baf | 25249 | @anchor{gnat_rm/the_gnat_library id148}@anchor{400}@anchor{gnat_rm/the_gnat_library system-wch-cnv-s-wchcnv-ads}@anchor{401} |
64d5610f ML |
25250 | @section @code{System.Wch_Cnv} (@code{s-wchcnv.ads}) |
25251 | ||
25252 | ||
25253 | @geindex System.Wch_Cnv (s-wchcnv.ads) | |
25254 | ||
25255 | @geindex Wide Character | |
25256 | @geindex Representation | |
25257 | ||
25258 | @geindex Wide String | |
25259 | @geindex Conversion | |
25260 | ||
25261 | @geindex Representation of wide characters | |
25262 | ||
25263 | This package provides routines for converting between | |
25264 | wide and wide wide characters and a representation as a value of type | |
25265 | @code{Standard.String}, using a specified wide character | |
25266 | encoding method. It uses definitions in | |
25267 | package @code{System.Wch_Con}. | |
25268 | ||
25269 | @node System Wch_Con s-wchcon ads,,System Wch_Cnv s-wchcnv ads,The GNAT Library | |
73918baf | 25270 | @anchor{gnat_rm/the_gnat_library id149}@anchor{402}@anchor{gnat_rm/the_gnat_library system-wch-con-s-wchcon-ads}@anchor{403} |
64d5610f ML |
25271 | @section @code{System.Wch_Con} (@code{s-wchcon.ads}) |
25272 | ||
25273 | ||
25274 | @geindex System.Wch_Con (s-wchcon.ads) | |
25275 | ||
25276 | This package provides definitions and descriptions of | |
25277 | the various methods used for encoding wide characters | |
25278 | in ordinary strings. These definitions are used by | |
25279 | the package @code{System.Wch_Cnv}. | |
25280 | ||
25281 | @node Interfacing to Other Languages,Specialized Needs Annexes,The GNAT Library,Top | |
73918baf | 25282 | @anchor{gnat_rm/interfacing_to_other_languages doc}@anchor{404}@anchor{gnat_rm/interfacing_to_other_languages id1}@anchor{405}@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-other-languages}@anchor{11} |
64d5610f ML |
25283 | @chapter Interfacing to Other Languages |
25284 | ||
25285 | ||
25286 | The facilities in Annex B of the Ada Reference Manual are fully | |
25287 | implemented in GNAT, and in addition, a full interface to C++ is | |
25288 | provided. | |
25289 | ||
25290 | @menu | |
25291 | * Interfacing to C:: | |
25292 | * Interfacing to C++:: | |
25293 | * Interfacing to COBOL:: | |
25294 | * Interfacing to Fortran:: | |
25295 | * Interfacing to non-GNAT Ada code:: | |
25296 | ||
25297 | @end menu | |
25298 | ||
25299 | @node Interfacing to C,Interfacing to C++,,Interfacing to Other Languages | |
73918baf | 25300 | @anchor{gnat_rm/interfacing_to_other_languages id2}@anchor{406}@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-c}@anchor{407} |
64d5610f ML |
25301 | @section Interfacing to C |
25302 | ||
25303 | ||
25304 | Interfacing to C with GNAT can use one of two approaches: | |
25305 | ||
25306 | ||
25307 | @itemize * | |
25308 | ||
25309 | @item | |
25310 | The types in the package @code{Interfaces.C} may be used. | |
25311 | ||
25312 | @item | |
25313 | Standard Ada types may be used directly. This may be less portable to | |
25314 | other compilers, but will work on all GNAT compilers, which guarantee | |
25315 | correspondence between the C and Ada types. | |
25316 | @end itemize | |
25317 | ||
25318 | Pragma @code{Convention C} may be applied to Ada types, but mostly has no | |
25319 | effect, since this is the default. The following table shows the | |
25320 | correspondence between Ada scalar types and the corresponding C types. | |
25321 | ||
25322 | ||
25323 | @multitable {xxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} | |
25324 | @headitem | |
25325 | ||
25326 | Ada Type | |
25327 | ||
25328 | @tab | |
25329 | ||
25330 | C Type | |
25331 | ||
25332 | @item | |
25333 | ||
25334 | @code{Integer} | |
25335 | ||
25336 | @tab | |
25337 | ||
25338 | @code{int} | |
25339 | ||
25340 | @item | |
25341 | ||
25342 | @code{Short_Integer} | |
25343 | ||
25344 | @tab | |
25345 | ||
25346 | @code{short} | |
25347 | ||
25348 | @item | |
25349 | ||
25350 | @code{Short_Short_Integer} | |
25351 | ||
25352 | @tab | |
25353 | ||
25354 | @code{signed char} | |
25355 | ||
25356 | @item | |
25357 | ||
25358 | @code{Long_Integer} | |
25359 | ||
25360 | @tab | |
25361 | ||
25362 | @code{long} | |
25363 | ||
25364 | @item | |
25365 | ||
25366 | @code{Long_Long_Integer} | |
25367 | ||
25368 | @tab | |
25369 | ||
25370 | @code{long long} | |
25371 | ||
25372 | @item | |
25373 | ||
25374 | @code{Short_Float} | |
25375 | ||
25376 | @tab | |
25377 | ||
25378 | @code{float} | |
25379 | ||
25380 | @item | |
25381 | ||
25382 | @code{Float} | |
25383 | ||
25384 | @tab | |
25385 | ||
25386 | @code{float} | |
25387 | ||
25388 | @item | |
25389 | ||
25390 | @code{Long_Float} | |
25391 | ||
25392 | @tab | |
25393 | ||
25394 | @code{double} | |
25395 | ||
25396 | @item | |
25397 | ||
25398 | @code{Long_Long_Float} | |
25399 | ||
25400 | @tab | |
25401 | ||
25402 | This is the longest floating-point type supported by the hardware. | |
25403 | ||
25404 | @end multitable | |
25405 | ||
25406 | ||
25407 | Additionally, there are the following general correspondences between Ada | |
25408 | and C types: | |
25409 | ||
25410 | ||
25411 | @itemize * | |
25412 | ||
25413 | @item | |
25414 | Ada enumeration types map to C enumeration types directly if pragma | |
25415 | @code{Convention C} is specified, which causes them to have a length of | |
25416 | 32 bits, except for boolean types which map to C99 @code{bool} and for | |
25417 | which the length is 8 bits. | |
25418 | Without pragma @code{Convention C}, Ada enumeration types map to | |
25419 | 8, 16, or 32 bits (i.e., C types @code{signed char}, @code{short}, | |
25420 | @code{int}, respectively) depending on the number of values passed. | |
25421 | This is the only case in which pragma @code{Convention C} affects the | |
25422 | representation of an Ada type. | |
25423 | ||
25424 | @item | |
25425 | Ada access types map to C pointers, except for the case of pointers to | |
25426 | unconstrained types in Ada, which have no direct C equivalent. | |
25427 | ||
25428 | @item | |
25429 | Ada arrays map directly to C arrays. | |
25430 | ||
25431 | @item | |
25432 | Ada records map directly to C structures. | |
25433 | ||
25434 | @item | |
25435 | Packed Ada records map to C structures where all members are bit fields | |
25436 | of the length corresponding to the @code{type'Size} value in Ada. | |
25437 | @end itemize | |
25438 | ||
25439 | @node Interfacing to C++,Interfacing to COBOL,Interfacing to C,Interfacing to Other Languages | |
73918baf | 25440 | @anchor{gnat_rm/interfacing_to_other_languages id3}@anchor{47}@anchor{gnat_rm/interfacing_to_other_languages id4}@anchor{408} |
64d5610f ML |
25441 | @section Interfacing to C++ |
25442 | ||
25443 | ||
25444 | The interface to C++ makes use of the following pragmas, which are | |
25445 | primarily intended to be constructed automatically using a binding generator | |
25446 | tool, although it is possible to construct them by hand. | |
25447 | ||
25448 | Using these pragmas it is possible to achieve complete | |
25449 | inter-operability between Ada tagged types and C++ class definitions. | |
25450 | See @ref{7,,Implementation Defined Pragmas}, for more details. | |
25451 | ||
25452 | ||
25453 | @table @asis | |
25454 | ||
25455 | @item @code{pragma CPP_Class ([Entity =>] @var{LOCAL_NAME})} | |
25456 | ||
25457 | The argument denotes an entity in the current declarative region that is | |
25458 | declared as a tagged or untagged record type. It indicates that the type | |
25459 | corresponds to an externally declared C++ class type, and is to be laid | |
25460 | out the same way that C++ would lay out the type. | |
25461 | ||
25462 | Note: Pragma @code{CPP_Class} is currently obsolete. It is supported | |
25463 | for backward compatibility but its functionality is available | |
25464 | using pragma @code{Import} with @code{Convention} = @code{CPP}. | |
25465 | ||
25466 | @item @code{pragma CPP_Constructor ([Entity =>] @var{LOCAL_NAME})} | |
25467 | ||
25468 | This pragma identifies an imported function (imported in the usual way | |
25469 | with pragma @code{Import}) as corresponding to a C++ constructor. | |
25470 | @end table | |
25471 | ||
25472 | A few restrictions are placed on the use of the @code{Access} attribute | |
25473 | in conjunction with subprograms subject to convention @code{CPP}: the | |
25474 | attribute may be used neither on primitive operations of a tagged | |
25475 | record type with convention @code{CPP}, imported or not, nor on | |
25476 | subprograms imported with pragma @code{CPP_Constructor}. | |
25477 | ||
25478 | In addition, C++ exceptions are propagated and can be handled in an | |
25479 | @code{others} choice of an exception handler. The corresponding Ada | |
25480 | occurrence has no message, and the simple name of the exception identity | |
25481 | contains @code{Foreign_Exception}. Finalization and awaiting dependent | |
25482 | tasks works properly when such foreign exceptions are propagated. | |
25483 | ||
25484 | It is also possible to import a C++ exception using the following syntax: | |
25485 | ||
25486 | @example | |
25487 | LOCAL_NAME : exception; | |
25488 | pragma Import (Cpp, | |
25489 | [Entity =>] LOCAL_NAME, | |
25490 | [External_Name =>] static_string_EXPRESSION); | |
25491 | @end example | |
25492 | ||
25493 | The @code{External_Name} is the name of the C++ RTTI symbol. You can then | |
25494 | cover a specific C++ exception in an exception handler. | |
25495 | ||
25496 | @node Interfacing to COBOL,Interfacing to Fortran,Interfacing to C++,Interfacing to Other Languages | |
73918baf | 25497 | @anchor{gnat_rm/interfacing_to_other_languages id5}@anchor{409}@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-cobol}@anchor{40a} |
64d5610f ML |
25498 | @section Interfacing to COBOL |
25499 | ||
25500 | ||
25501 | Interfacing to COBOL is achieved as described in section B.4 of | |
25502 | the Ada Reference Manual. | |
25503 | ||
25504 | @node Interfacing to Fortran,Interfacing to non-GNAT Ada code,Interfacing to COBOL,Interfacing to Other Languages | |
73918baf | 25505 | @anchor{gnat_rm/interfacing_to_other_languages id6}@anchor{40b}@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-fortran}@anchor{40c} |
64d5610f ML |
25506 | @section Interfacing to Fortran |
25507 | ||
25508 | ||
25509 | Interfacing to Fortran is achieved as described in section B.5 of the | |
25510 | Ada Reference Manual. The pragma @code{Convention Fortran}, applied to a | |
25511 | multi-dimensional array causes the array to be stored in column-major | |
25512 | order as required for convenient interface to Fortran. | |
25513 | ||
25514 | @node Interfacing to non-GNAT Ada code,,Interfacing to Fortran,Interfacing to Other Languages | |
73918baf | 25515 | @anchor{gnat_rm/interfacing_to_other_languages id7}@anchor{40d}@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-non-gnat-ada-code}@anchor{40e} |
64d5610f ML |
25516 | @section Interfacing to non-GNAT Ada code |
25517 | ||
25518 | ||
25519 | It is possible to specify the convention @code{Ada} in a pragma | |
25520 | @code{Import} or pragma @code{Export}. However this refers to | |
25521 | the calling conventions used by GNAT, which may or may not be | |
25522 | similar enough to those used by some other Ada 83 / Ada 95 / Ada 2005 | |
25523 | compiler to allow interoperation. | |
25524 | ||
25525 | If arguments types are kept simple, and if the foreign compiler generally | |
25526 | follows system calling conventions, then it may be possible to integrate | |
25527 | files compiled by other Ada compilers, provided that the elaboration | |
25528 | issues are adequately addressed (for example by eliminating the | |
25529 | need for any load time elaboration). | |
25530 | ||
25531 | In particular, GNAT running on VMS is designed to | |
25532 | be highly compatible with the DEC Ada 83 compiler, so this is one | |
25533 | case in which it is possible to import foreign units of this type, | |
25534 | provided that the data items passed are restricted to simple scalar | |
25535 | values or simple record types without variants, or simple array | |
25536 | types with fixed bounds. | |
25537 | ||
25538 | @node Specialized Needs Annexes,Implementation of Specific Ada Features,Interfacing to Other Languages,Top | |
73918baf | 25539 | @anchor{gnat_rm/specialized_needs_annexes doc}@anchor{40f}@anchor{gnat_rm/specialized_needs_annexes id1}@anchor{410}@anchor{gnat_rm/specialized_needs_annexes specialized-needs-annexes}@anchor{12} |
64d5610f ML |
25540 | @chapter Specialized Needs Annexes |
25541 | ||
25542 | ||
25543 | Ada 95, Ada 2005, and Ada 2012 define a number of Specialized Needs Annexes, which are not | |
25544 | required in all implementations. However, as described in this chapter, | |
25545 | GNAT implements all of these annexes: | |
25546 | ||
25547 | ||
25548 | @table @asis | |
25549 | ||
25550 | @item `Systems Programming (Annex C)' | |
25551 | ||
25552 | The Systems Programming Annex is fully implemented. | |
25553 | ||
25554 | @item `Real-Time Systems (Annex D)' | |
25555 | ||
25556 | The Real-Time Systems Annex is fully implemented. | |
25557 | ||
25558 | @item `Distributed Systems (Annex E)' | |
25559 | ||
25560 | Stub generation is fully implemented in the GNAT compiler. In addition, | |
25561 | a complete compatible PCS is available as part of the GLADE system, | |
25562 | a separate product. When the two | |
25563 | products are used in conjunction, this annex is fully implemented. | |
25564 | ||
25565 | @item `Information Systems (Annex F)' | |
25566 | ||
25567 | The Information Systems annex is fully implemented. | |
25568 | ||
25569 | @item `Numerics (Annex G)' | |
25570 | ||
25571 | The Numerics Annex is fully implemented. | |
25572 | ||
25573 | @item `Safety and Security / High-Integrity Systems (Annex H)' | |
25574 | ||
25575 | The Safety and Security Annex (termed the High-Integrity Systems Annex | |
25576 | in Ada 2005) is fully implemented. | |
25577 | @end table | |
25578 | ||
25579 | @node Implementation of Specific Ada Features,Implementation of Ada 2012 Features,Specialized Needs Annexes,Top | |
73918baf | 25580 | @anchor{gnat_rm/implementation_of_specific_ada_features doc}@anchor{411}@anchor{gnat_rm/implementation_of_specific_ada_features id1}@anchor{412}@anchor{gnat_rm/implementation_of_specific_ada_features implementation-of-specific-ada-features}@anchor{13} |
64d5610f ML |
25581 | @chapter Implementation of Specific Ada Features |
25582 | ||
25583 | ||
25584 | This chapter describes the GNAT implementation of several Ada language | |
25585 | facilities. | |
25586 | ||
25587 | @menu | |
25588 | * Machine Code Insertions:: | |
25589 | * GNAT Implementation of Tasking:: | |
25590 | * GNAT Implementation of Shared Passive Packages:: | |
25591 | * Code Generation for Array Aggregates:: | |
25592 | * The Size of Discriminated Records with Default Discriminants:: | |
25593 | * Image Values For Nonscalar Types:: | |
25594 | * Strict Conformance to the Ada Reference Manual:: | |
25595 | ||
25596 | @end menu | |
25597 | ||
25598 | @node Machine Code Insertions,GNAT Implementation of Tasking,,Implementation of Specific Ada Features | |
73918baf | 25599 | @anchor{gnat_rm/implementation_of_specific_ada_features id2}@anchor{413}@anchor{gnat_rm/implementation_of_specific_ada_features machine-code-insertions}@anchor{16a} |
64d5610f ML |
25600 | @section Machine Code Insertions |
25601 | ||
25602 | ||
25603 | @geindex Machine Code insertions | |
25604 | ||
25605 | Package @code{Machine_Code} provides machine code support as described | |
25606 | in the Ada Reference Manual in two separate forms: | |
25607 | ||
25608 | ||
25609 | @itemize * | |
25610 | ||
25611 | @item | |
25612 | Machine code statements, consisting of qualified expressions that | |
25613 | fit the requirements of RM section 13.8. | |
25614 | ||
25615 | @item | |
25616 | An intrinsic callable procedure, providing an alternative mechanism of | |
25617 | including machine instructions in a subprogram. | |
25618 | @end itemize | |
25619 | ||
25620 | The two features are similar, and both are closely related to the mechanism | |
25621 | provided by the asm instruction in the GNU C compiler. Full understanding | |
25622 | and use of the facilities in this package requires understanding the asm | |
25623 | instruction, see the section on Extended Asm in | |
25624 | @cite{Using_the_GNU_Compiler_Collection_(GCC)}. | |
25625 | ||
25626 | Calls to the function @code{Asm} and the procedure @code{Asm} have identical | |
25627 | semantic restrictions and effects as described below. Both are provided so | |
25628 | that the procedure call can be used as a statement, and the function call | |
25629 | can be used to form a code_statement. | |
25630 | ||
25631 | Consider this C @code{asm} instruction: | |
25632 | ||
25633 | @example | |
25634 | asm ("fsinx %1 %0" : "=f" (result) : "f" (angle)); | |
25635 | @end example | |
25636 | ||
25637 | The equivalent can be written for GNAT as: | |
25638 | ||
25639 | @example | |
25640 | Asm ("fsinx %1 %0", | |
25641 | My_Float'Asm_Output ("=f", result), | |
25642 | My_Float'Asm_Input ("f", angle)); | |
25643 | @end example | |
25644 | ||
25645 | The first argument to @code{Asm} is the assembler template, and is | |
25646 | identical to what is used in GNU C. This string must be a static | |
25647 | expression. The second argument is the output operand list. It is | |
25648 | either a single @code{Asm_Output} attribute reference, or a list of such | |
25649 | references enclosed in parentheses (technically an array aggregate of | |
25650 | such references). | |
25651 | ||
25652 | The @code{Asm_Output} attribute denotes a function that takes two | |
25653 | parameters. The first is a string, the second is the name of a variable | |
25654 | of the type designated by the attribute prefix. The first (string) | |
25655 | argument is required to be a static expression and designates the | |
25656 | constraint (see the section on Constraints in | |
25657 | @cite{Using_the_GNU_Compiler_Collection_(GCC)}) | |
25658 | for the parameter; e.g., what kind of register is required. The second | |
25659 | argument is the variable to be written or updated with the | |
25660 | result. The possible values for constraint are the same as those used in | |
25661 | the RTL, and are dependent on the configuration file used to build the | |
25662 | GCC back end. If there are no output operands, then this argument may | |
25663 | either be omitted, or explicitly given as @code{No_Output_Operands}. | |
25664 | No support is provided for GNU C’s symbolic names for output parameters. | |
25665 | ||
25666 | The second argument of @code{my_float'Asm_Output} functions as | |
25667 | though it were an @code{out} parameter, which is a little curious, but | |
25668 | all names have the form of expressions, so there is no syntactic | |
25669 | irregularity, even though normally functions would not be permitted | |
25670 | @code{out} parameters. The third argument is the list of input | |
25671 | operands. It is either a single @code{Asm_Input} attribute reference, or | |
25672 | a list of such references enclosed in parentheses (technically an array | |
25673 | aggregate of such references). | |
25674 | ||
25675 | The @code{Asm_Input} attribute denotes a function that takes two | |
25676 | parameters. The first is a string, the second is an expression of the | |
25677 | type designated by the prefix. The first (string) argument is required | |
25678 | to be a static expression, and is the constraint for the parameter, | |
25679 | (e.g., what kind of register is required). The second argument is the | |
25680 | value to be used as the input argument. The possible values for the | |
25681 | constraint are the same as those used in the RTL, and are dependent on | |
25682 | the configuration file used to built the GCC back end. | |
25683 | No support is provided for GNU C’s symbolic names for input parameters. | |
25684 | ||
25685 | If there are no input operands, this argument may either be omitted, or | |
25686 | explicitly given as @code{No_Input_Operands}. The fourth argument, not | |
25687 | present in the above example, is a list of register names, called the | |
25688 | `clobber' argument. This argument, if given, must be a static string | |
25689 | expression, and is a space or comma separated list of names of registers | |
25690 | that must be considered destroyed as a result of the @code{Asm} call. If | |
25691 | this argument is the null string (the default value), then the code | |
25692 | generator assumes that no additional registers are destroyed. | |
25693 | In addition to registers, the special clobbers @code{memory} and | |
25694 | @code{cc} as described in the GNU C docs are both supported. | |
25695 | ||
25696 | The fifth argument, not present in the above example, called the | |
25697 | `volatile' argument, is by default @code{False}. It can be set to | |
25698 | the literal value @code{True} to indicate to the code generator that all | |
25699 | optimizations with respect to the instruction specified should be | |
25700 | suppressed, and in particular an instruction that has outputs | |
25701 | will still be generated, even if none of the outputs are | |
25702 | used. See @cite{Using_the_GNU_Compiler_Collection_(GCC)} | |
25703 | for the full description. | |
25704 | Generally it is strongly advisable to use Volatile for any ASM statement | |
25705 | that is missing either input or output operands or to avoid unwanted | |
25706 | optimizations. A warning is generated if this advice is not followed. | |
25707 | ||
25708 | No support is provided for GNU C’s @code{asm goto} feature. | |
25709 | ||
25710 | The @code{Asm} subprograms may be used in two ways. First the procedure | |
25711 | forms can be used anywhere a procedure call would be valid, and | |
25712 | correspond to what the RM calls ‘intrinsic’ routines. Such calls can | |
25713 | be used to intersperse machine instructions with other Ada statements. | |
25714 | Second, the function forms, which return a dummy value of the limited | |
25715 | private type @code{Asm_Insn}, can be used in code statements, and indeed | |
25716 | this is the only context where such calls are allowed. Code statements | |
25717 | appear as aggregates of the form: | |
25718 | ||
b71d4b62 RA |
25719 | @example |
25720 | Asm_Insn'(Asm (...)); | |
25721 | Asm_Insn'(Asm_Volatile (...)); | |
25722 | @end example | |
25723 | ||
25724 | In accordance with RM rules, such code statements are allowed only | |
25725 | within subprograms whose entire body consists of such statements. It is | |
25726 | not permissible to intermix such statements with other Ada statements. | |
25727 | ||
25728 | Typically the form using intrinsic procedure calls is more convenient | |
25729 | and more flexible. The code statement form is provided to meet the RM | |
25730 | suggestion that such a facility should be made available. The following | |
25731 | is the exact syntax of the call to @code{Asm}. As usual, if named notation | |
25732 | is used, the arguments may be given in arbitrary order, following the | |
25733 | normal rules for use of positional and named arguments: | |
25734 | ||
25735 | @example | |
25736 | ASM_CALL ::= Asm ( | |
25737 | [Template =>] static_string_EXPRESSION | |
25738 | [,[Outputs =>] OUTPUT_OPERAND_LIST ] | |
25739 | [,[Inputs =>] INPUT_OPERAND_LIST ] | |
25740 | [,[Clobber =>] static_string_EXPRESSION ] | |
25741 | [,[Volatile =>] static_boolean_EXPRESSION] ) | |
25742 | ||
25743 | OUTPUT_OPERAND_LIST ::= | |
25744 | [PREFIX.]No_Output_Operands | |
25745 | | OUTPUT_OPERAND_ATTRIBUTE | |
25746 | | (OUTPUT_OPERAND_ATTRIBUTE @{,OUTPUT_OPERAND_ATTRIBUTE@}) | |
25747 | ||
25748 | OUTPUT_OPERAND_ATTRIBUTE ::= | |
25749 | SUBTYPE_MARK'Asm_Output (static_string_EXPRESSION, NAME) | |
25750 | ||
25751 | INPUT_OPERAND_LIST ::= | |
25752 | [PREFIX.]No_Input_Operands | |
25753 | | INPUT_OPERAND_ATTRIBUTE | |
25754 | | (INPUT_OPERAND_ATTRIBUTE @{,INPUT_OPERAND_ATTRIBUTE@}) | |
25755 | ||
25756 | INPUT_OPERAND_ATTRIBUTE ::= | |
25757 | SUBTYPE_MARK'Asm_Input (static_string_EXPRESSION, EXPRESSION) | |
25758 | @end example | |
25759 | ||
25760 | The identifiers @code{No_Input_Operands} and @code{No_Output_Operands} | |
25761 | are declared in the package @code{Machine_Code} and must be referenced | |
25762 | according to normal visibility rules. In particular if there is no | |
25763 | @code{use} clause for this package, then appropriate package name | |
25764 | qualification is required. | |
25765 | ||
25766 | @node GNAT Implementation of Tasking,GNAT Implementation of Shared Passive Packages,Machine Code Insertions,Implementation of Specific Ada Features | |
73918baf | 25767 | @anchor{gnat_rm/implementation_of_specific_ada_features gnat-implementation-of-tasking}@anchor{414}@anchor{gnat_rm/implementation_of_specific_ada_features id3}@anchor{415} |
b71d4b62 RA |
25768 | @section GNAT Implementation of Tasking |
25769 | ||
25770 | ||
25771 | This chapter outlines the basic GNAT approach to tasking (in particular, | |
25772 | a multi-layered library for portability) and discusses issues related | |
25773 | to compliance with the Real-Time Systems Annex. | |
25774 | ||
25775 | @menu | |
25776 | * Mapping Ada Tasks onto the Underlying Kernel Threads:: | |
25777 | * Ensuring Compliance with the Real-Time Annex:: | |
25778 | * Support for Locking Policies:: | |
25779 | ||
25780 | @end menu | |
25781 | ||
25782 | @node Mapping Ada Tasks onto the Underlying Kernel Threads,Ensuring Compliance with the Real-Time Annex,,GNAT Implementation of Tasking | |
73918baf | 25783 | @anchor{gnat_rm/implementation_of_specific_ada_features id4}@anchor{416}@anchor{gnat_rm/implementation_of_specific_ada_features mapping-ada-tasks-onto-the-underlying-kernel-threads}@anchor{417} |
b71d4b62 RA |
25784 | @subsection Mapping Ada Tasks onto the Underlying Kernel Threads |
25785 | ||
25786 | ||
25787 | GNAT’s run-time support comprises two layers: | |
25788 | ||
25789 | ||
25790 | @itemize * | |
25791 | ||
25792 | @item | |
25793 | GNARL (GNAT Run-time Layer) | |
25794 | ||
25795 | @item | |
25796 | GNULL (GNAT Low-level Library) | |
25797 | @end itemize | |
25798 | ||
25799 | In GNAT, Ada’s tasking services rely on a platform and OS independent | |
25800 | layer known as GNARL. This code is responsible for implementing the | |
25801 | correct semantics of Ada’s task creation, rendezvous, protected | |
25802 | operations etc. | |
25803 | ||
25804 | GNARL decomposes Ada’s tasking semantics into simpler lower level | |
25805 | operations such as create a thread, set the priority of a thread, | |
25806 | yield, create a lock, lock/unlock, etc. The spec for these low-level | |
25807 | operations constitutes GNULLI, the GNULL Interface. This interface is | |
25808 | directly inspired from the POSIX real-time API. | |
25809 | ||
25810 | If the underlying executive or OS implements the POSIX standard | |
25811 | faithfully, the GNULL Interface maps as is to the services offered by | |
25812 | the underlying kernel. Otherwise, some target dependent glue code maps | |
25813 | the services offered by the underlying kernel to the semantics expected | |
25814 | by GNARL. | |
25815 | ||
25816 | Whatever the underlying OS (VxWorks, UNIX, Windows, etc.) the | |
25817 | key point is that each Ada task is mapped on a thread in the underlying | |
25818 | kernel. For example, in the case of VxWorks, one Ada task = one VxWorks task. | |
25819 | ||
25820 | In addition Ada task priorities map onto the underlying thread priorities. | |
25821 | Mapping Ada tasks onto the underlying kernel threads has several advantages: | |
25822 | ||
25823 | ||
25824 | @itemize * | |
25825 | ||
25826 | @item | |
25827 | The underlying scheduler is used to schedule the Ada tasks. This | |
25828 | makes Ada tasks as efficient as kernel threads from a scheduling | |
25829 | standpoint. | |
25830 | ||
25831 | @item | |
25832 | Interaction with code written in C containing threads is eased | |
25833 | since at the lowest level Ada tasks and C threads map onto the same | |
25834 | underlying kernel concept. | |
25835 | ||
25836 | @item | |
25837 | When an Ada task is blocked during I/O the remaining Ada tasks are | |
25838 | able to proceed. | |
25839 | ||
25840 | @item | |
25841 | On multiprocessor systems Ada tasks can execute in parallel. | |
25842 | @end itemize | |
25843 | ||
25844 | Some threads libraries offer a mechanism to fork a new process, with the | |
25845 | child process duplicating the threads from the parent. | |
25846 | GNAT does not | |
25847 | support this functionality when the parent contains more than one task. | |
25848 | ||
25849 | @geindex Forking a new process | |
25850 | ||
25851 | @node Ensuring Compliance with the Real-Time Annex,Support for Locking Policies,Mapping Ada Tasks onto the Underlying Kernel Threads,GNAT Implementation of Tasking | |
73918baf | 25852 | @anchor{gnat_rm/implementation_of_specific_ada_features ensuring-compliance-with-the-real-time-annex}@anchor{418}@anchor{gnat_rm/implementation_of_specific_ada_features id5}@anchor{419} |
b71d4b62 RA |
25853 | @subsection Ensuring Compliance with the Real-Time Annex |
25854 | ||
25855 | ||
25856 | @geindex Real-Time Systems Annex compliance | |
25857 | ||
25858 | Although mapping Ada tasks onto | |
25859 | the underlying threads has significant advantages, it does create some | |
25860 | complications when it comes to respecting the scheduling semantics | |
25861 | specified in the real-time annex (Annex D). | |
25862 | ||
25863 | For instance the Annex D requirement for the @code{FIFO_Within_Priorities} | |
25864 | scheduling policy states: | |
25865 | ||
25866 | @quotation | |
25867 | ||
25868 | `When the active priority of a ready task that is not running | |
25869 | changes, or the setting of its base priority takes effect, the | |
25870 | task is removed from the ready queue for its old active priority | |
25871 | and is added at the tail of the ready queue for its new active | |
25872 | priority, except in the case where the active priority is lowered | |
25873 | due to the loss of inherited priority, in which case the task is | |
25874 | added at the head of the ready queue for its new active priority.' | |
25875 | @end quotation | |
25876 | ||
25877 | While most kernels do put tasks at the end of the priority queue when | |
25878 | a task changes its priority, (which respects the main | |
25879 | FIFO_Within_Priorities requirement), almost none keep a thread at the | |
25880 | beginning of its priority queue when its priority drops from the loss | |
25881 | of inherited priority. | |
25882 | ||
25883 | As a result most vendors have provided incomplete Annex D implementations. | |
25884 | ||
25885 | The GNAT run-time, has a nice cooperative solution to this problem | |
25886 | which ensures that accurate FIFO_Within_Priorities semantics are | |
25887 | respected. | |
25888 | ||
25889 | The principle is as follows. When an Ada task T is about to start | |
25890 | running, it checks whether some other Ada task R with the same | |
25891 | priority as T has been suspended due to the loss of priority | |
25892 | inheritance. If this is the case, T yields and is placed at the end of | |
25893 | its priority queue. When R arrives at the front of the queue it | |
25894 | executes. | |
25895 | ||
25896 | Note that this simple scheme preserves the relative order of the tasks | |
25897 | that were ready to execute in the priority queue where R has been | |
25898 | placed at the end. | |
25899 | ||
25900 | @c Support_for_Locking_Policies | |
25901 | ||
25902 | @node Support for Locking Policies,,Ensuring Compliance with the Real-Time Annex,GNAT Implementation of Tasking | |
73918baf | 25903 | @anchor{gnat_rm/implementation_of_specific_ada_features support-for-locking-policies}@anchor{41a} |
b71d4b62 RA |
25904 | @subsection Support for Locking Policies |
25905 | ||
25906 | ||
25907 | This section specifies which policies specified by pragma Locking_Policy | |
25908 | are supported on which platforms. | |
25909 | ||
25910 | GNAT supports the standard @code{Ceiling_Locking} policy, and the | |
25911 | implementation defined @code{Inheritance_Locking} and | |
25912 | @code{Concurrent_Readers_Locking} policies. | |
25913 | ||
25914 | @code{Ceiling_Locking} is supported on all platforms if the operating system | |
25915 | supports it. In particular, @code{Ceiling_Locking} is not supported on | |
25916 | VxWorks. | |
25917 | @code{Inheritance_Locking} is supported on | |
25918 | Linux, | |
25919 | Darwin (Mac OS X), | |
25920 | LynxOS 178, | |
25921 | and VxWorks. | |
25922 | @code{Concurrent_Readers_Locking} is supported on Linux. | |
25923 | ||
25924 | Notes about @code{Ceiling_Locking} on Linux: | |
25925 | If the process is running as ‘root’, ceiling locking is used. | |
25926 | If the capabilities facility is installed | |
25927 | (“sudo apt-get –assume-yes install libcap-dev” on Ubuntu, | |
25928 | for example), | |
25929 | and the program is linked against that library | |
25930 | (“-largs -lcap”), | |
25931 | and the executable file has the cap_sys_nice capability | |
25932 | (“sudo /sbin/setcap cap_sys_nice=ep executable_file_name”), | |
25933 | then ceiling locking is used. | |
25934 | Otherwise, the @code{Ceiling_Locking} policy is ignored. | |
25935 | ||
25936 | @node GNAT Implementation of Shared Passive Packages,Code Generation for Array Aggregates,GNAT Implementation of Tasking,Implementation of Specific Ada Features | |
73918baf | 25937 | @anchor{gnat_rm/implementation_of_specific_ada_features gnat-implementation-of-shared-passive-packages}@anchor{41b}@anchor{gnat_rm/implementation_of_specific_ada_features id6}@anchor{41c} |
b71d4b62 RA |
25938 | @section GNAT Implementation of Shared Passive Packages |
25939 | ||
25940 | ||
25941 | @geindex Shared passive packages | |
25942 | ||
25943 | GNAT fully implements the | |
25944 | @geindex pragma Shared_Passive | |
25945 | pragma | |
25946 | @code{Shared_Passive} for | |
25947 | the purpose of designating shared passive packages. | |
25948 | This allows the use of passive partitions in the | |
25949 | context described in the Ada Reference Manual; i.e., for communication | |
25950 | between separate partitions of a distributed application using the | |
25951 | features in Annex E. | |
25952 | ||
25953 | @geindex Annex E | |
25954 | ||
25955 | @geindex Distribution Systems Annex | |
25956 | ||
25957 | However, the implementation approach used by GNAT provides for more | |
25958 | extensive usage as follows: | |
25959 | ||
25960 | ||
25961 | @table @asis | |
25962 | ||
25963 | @item `Communication between separate programs' | |
25964 | ||
25965 | This allows separate programs to access the data in passive | |
25966 | partitions, using protected objects for synchronization where | |
25967 | needed. The only requirement is that the two programs have a | |
25968 | common shared file system. It is even possible for programs | |
25969 | running on different machines with different architectures | |
25970 | (e.g., different endianness) to communicate via the data in | |
25971 | a passive partition. | |
25972 | ||
25973 | @item `Persistence between program runs' | |
25974 | ||
25975 | The data in a passive package can persist from one run of a | |
25976 | program to another, so that a later program sees the final | |
25977 | values stored by a previous run of the same program. | |
25978 | @end table | |
25979 | ||
25980 | The implementation approach used is to store the data in files. A | |
25981 | separate stream file is created for each object in the package, and | |
25982 | an access to an object causes the corresponding file to be read or | |
25983 | written. | |
25984 | ||
25985 | @geindex SHARED_MEMORY_DIRECTORY environment variable | |
25986 | ||
25987 | The environment variable @code{SHARED_MEMORY_DIRECTORY} should be | |
25988 | set to the directory to be used for these files. | |
25989 | The files in this directory | |
25990 | have names that correspond to their fully qualified names. For | |
25991 | example, if we have the package | |
25992 | ||
25993 | @example | |
25994 | package X is | |
25995 | pragma Shared_Passive (X); | |
25996 | Y : Integer; | |
25997 | Z : Float; | |
25998 | end X; | |
25999 | @end example | |
26000 | ||
26001 | and the environment variable is set to @code{/stemp/}, then the files created | |
26002 | will have the names: | |
26003 | ||
26004 | @example | |
26005 | /stemp/x.y | |
26006 | /stemp/x.z | |
26007 | @end example | |
26008 | ||
26009 | These files are created when a value is initially written to the object, and | |
26010 | the files are retained until manually deleted. This provides the persistence | |
26011 | semantics. If no file exists, it means that no partition has assigned a value | |
26012 | to the variable; in this case the initial value declared in the package | |
26013 | will be used. This model ensures that there are no issues in synchronizing | |
26014 | the elaboration process, since elaboration of passive packages elaborates the | |
26015 | initial values, but does not create the files. | |
26016 | ||
26017 | The files are written using normal @code{Stream_IO} access. | |
26018 | If you want to be able | |
26019 | to communicate between programs or partitions running on different | |
26020 | architectures, then you should use the XDR versions of the stream attribute | |
26021 | routines, since these are architecture independent. | |
26022 | ||
26023 | If active synchronization is required for access to the variables in the | |
26024 | shared passive package, then as described in the Ada Reference Manual, the | |
26025 | package may contain protected objects used for this purpose. In this case | |
26026 | a lock file (whose name is @code{___lock}, with three underscores) | |
26027 | is created in the shared memory directory. | |
26028 | ||
26029 | @geindex ___lock file (for shared passive packages) | |
26030 | ||
26031 | This is used to provide the required locking | |
26032 | semantics for proper protected object synchronization. | |
26033 | ||
26034 | @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 | |
73918baf | 26035 | @anchor{gnat_rm/implementation_of_specific_ada_features code-generation-for-array-aggregates}@anchor{41d}@anchor{gnat_rm/implementation_of_specific_ada_features id7}@anchor{41e} |
b71d4b62 RA |
26036 | @section Code Generation for Array Aggregates |
26037 | ||
26038 | ||
26039 | Aggregates have a rich syntax and allow the user to specify the values of | |
26040 | complex data structures by means of a single construct. As a result, the | |
26041 | code generated for aggregates can be quite complex and involve loops, case | |
26042 | statements and multiple assignments. In the simplest cases, however, the | |
26043 | compiler will recognize aggregates whose components and constraints are | |
26044 | fully static, and in those cases the compiler will generate little or no | |
26045 | executable code. The following is an outline of the code that GNAT generates | |
26046 | for various aggregate constructs. For further details, you will find it | |
26047 | useful to examine the output produced by the -gnatG flag to see the expanded | |
26048 | source that is input to the code generator. You may also want to examine | |
26049 | the assembly code generated at various levels of optimization. | |
26050 | ||
26051 | The code generated for aggregates depends on the context, the component values, | |
26052 | and the type. In the context of an object declaration the code generated is | |
26053 | generally simpler than in the case of an assignment. As a general rule, static | |
26054 | component values and static subtypes also lead to simpler code. | |
26055 | ||
26056 | @menu | |
26057 | * Static constant aggregates with static bounds:: | |
26058 | * Constant aggregates with unconstrained nominal types:: | |
26059 | * Aggregates with static bounds:: | |
26060 | * Aggregates with nonstatic bounds:: | |
26061 | * Aggregates in assignment statements:: | |
26062 | ||
26063 | @end menu | |
26064 | ||
26065 | @node Static constant aggregates with static bounds,Constant aggregates with unconstrained nominal types,,Code Generation for Array Aggregates | |
73918baf | 26066 | @anchor{gnat_rm/implementation_of_specific_ada_features id8}@anchor{41f}@anchor{gnat_rm/implementation_of_specific_ada_features static-constant-aggregates-with-static-bounds}@anchor{420} |
b71d4b62 RA |
26067 | @subsection Static constant aggregates with static bounds |
26068 | ||
26069 | ||
26070 | For the declarations: | |
26071 | ||
26072 | @example | |
26073 | type One_Dim is array (1..10) of integer; | |
26074 | ar0 : constant One_Dim := (1, 2, 3, 4, 5, 6, 7, 8, 9, 0); | |
26075 | @end example | |
26076 | ||
26077 | GNAT generates no executable code: the constant ar0 is placed in static memory. | |
26078 | The same is true for constant aggregates with named associations: | |
26079 | ||
26080 | @example | |
26081 | Cr1 : constant One_Dim := (4 => 16, 2 => 4, 3 => 9, 1 => 1, 5 .. 10 => 0); | |
26082 | Cr3 : constant One_Dim := (others => 7777); | |
26083 | @end example | |
26084 | ||
26085 | The same is true for multidimensional constant arrays such as: | |
26086 | ||
26087 | @example | |
26088 | type two_dim is array (1..3, 1..3) of integer; | |
26089 | Unit : constant two_dim := ( (1,0,0), (0,1,0), (0,0,1)); | |
26090 | @end example | |
26091 | ||
26092 | The same is true for arrays of one-dimensional arrays: the following are | |
26093 | static: | |
26094 | ||
26095 | @example | |
26096 | type ar1b is array (1..3) of boolean; | |
26097 | type ar_ar is array (1..3) of ar1b; | |
26098 | None : constant ar1b := (others => false); -- fully static | |
26099 | None2 : constant ar_ar := (1..3 => None); -- fully static | |
26100 | @end example | |
26101 | ||
26102 | However, for multidimensional aggregates with named associations, GNAT will | |
26103 | generate assignments and loops, even if all associations are static. The | |
26104 | following two declarations generate a loop for the first dimension, and | |
26105 | individual component assignments for the second dimension: | |
26106 | ||
26107 | @example | |
26108 | Zero1: constant two_dim := (1..3 => (1..3 => 0)); | |
26109 | Zero2: constant two_dim := (others => (others => 0)); | |
26110 | @end example | |
26111 | ||
26112 | @node Constant aggregates with unconstrained nominal types,Aggregates with static bounds,Static constant aggregates with static bounds,Code Generation for Array Aggregates | |
73918baf | 26113 | @anchor{gnat_rm/implementation_of_specific_ada_features constant-aggregates-with-unconstrained-nominal-types}@anchor{421}@anchor{gnat_rm/implementation_of_specific_ada_features id9}@anchor{422} |
b71d4b62 RA |
26114 | @subsection Constant aggregates with unconstrained nominal types |
26115 | ||
26116 | ||
26117 | In such cases the aggregate itself establishes the subtype, so that | |
26118 | associations with @code{others} cannot be used. GNAT determines the | |
26119 | bounds for the actual subtype of the aggregate, and allocates the | |
26120 | aggregate statically as well. No code is generated for the following: | |
26121 | ||
26122 | @example | |
26123 | type One_Unc is array (natural range <>) of integer; | |
26124 | Cr_Unc : constant One_Unc := (12,24,36); | |
26125 | @end example | |
26126 | ||
26127 | @node Aggregates with static bounds,Aggregates with nonstatic bounds,Constant aggregates with unconstrained nominal types,Code Generation for Array Aggregates | |
73918baf | 26128 | @anchor{gnat_rm/implementation_of_specific_ada_features aggregates-with-static-bounds}@anchor{423}@anchor{gnat_rm/implementation_of_specific_ada_features id10}@anchor{424} |
b71d4b62 RA |
26129 | @subsection Aggregates with static bounds |
26130 | ||
26131 | ||
26132 | In all previous examples the aggregate was the initial (and immutable) value | |
26133 | of a constant. If the aggregate initializes a variable, then code is generated | |
26134 | for it as a combination of individual assignments and loops over the target | |
26135 | object. The declarations | |
26136 | ||
26137 | @example | |
26138 | Cr_Var1 : One_Dim := (2, 5, 7, 11, 0, 0, 0, 0, 0, 0); | |
26139 | Cr_Var2 : One_Dim := (others > -1); | |
26140 | @end example | |
26141 | ||
26142 | generate the equivalent of | |
26143 | ||
26144 | @example | |
26145 | Cr_Var1 (1) := 2; | |
26146 | Cr_Var1 (2) := 3; | |
26147 | Cr_Var1 (3) := 5; | |
26148 | Cr_Var1 (4) := 11; | |
26149 | ||
26150 | for I in Cr_Var2'range loop | |
26151 | Cr_Var2 (I) := -1; | |
26152 | end loop; | |
26153 | @end example | |
26154 | ||
26155 | @node Aggregates with nonstatic bounds,Aggregates in assignment statements,Aggregates with static bounds,Code Generation for Array Aggregates | |
73918baf | 26156 | @anchor{gnat_rm/implementation_of_specific_ada_features aggregates-with-nonstatic-bounds}@anchor{425}@anchor{gnat_rm/implementation_of_specific_ada_features id11}@anchor{426} |
b71d4b62 RA |
26157 | @subsection Aggregates with nonstatic bounds |
26158 | ||
26159 | ||
26160 | If the bounds of the aggregate are not statically compatible with the bounds | |
26161 | of the nominal subtype of the target, then constraint checks have to be | |
26162 | generated on the bounds. For a multidimensional array, constraint checks may | |
26163 | have to be applied to sub-arrays individually, if they do not have statically | |
26164 | compatible subtypes. | |
26165 | ||
26166 | @node Aggregates in assignment statements,,Aggregates with nonstatic bounds,Code Generation for Array Aggregates | |
73918baf | 26167 | @anchor{gnat_rm/implementation_of_specific_ada_features aggregates-in-assignment-statements}@anchor{427}@anchor{gnat_rm/implementation_of_specific_ada_features id12}@anchor{428} |
b71d4b62 RA |
26168 | @subsection Aggregates in assignment statements |
26169 | ||
26170 | ||
26171 | In general, aggregate assignment requires the construction of a temporary, | |
26172 | and a copy from the temporary to the target of the assignment. This is because | |
26173 | it is not always possible to convert the assignment into a series of individual | |
26174 | component assignments. For example, consider the simple case: | |
26175 | ||
26176 | @example | |
26177 | A := (A(2), A(1)); | |
26178 | @end example | |
26179 | ||
26180 | This cannot be converted into: | |
26181 | ||
26182 | @example | |
26183 | A(1) := A(2); | |
26184 | A(2) := A(1); | |
26185 | @end example | |
26186 | ||
26187 | So the aggregate has to be built first in a separate location, and then | |
26188 | copied into the target. GNAT recognizes simple cases where this intermediate | |
26189 | step is not required, and the assignments can be performed in place, directly | |
26190 | into the target. The following sufficient criteria are applied: | |
26191 | ||
26192 | ||
26193 | @itemize * | |
26194 | ||
26195 | @item | |
26196 | The bounds of the aggregate are static, and the associations are static. | |
26197 | ||
26198 | @item | |
26199 | The components of the aggregate are static constants, names of | |
26200 | simple variables that are not renamings, or expressions not involving | |
26201 | indexed components whose operands obey these rules. | |
26202 | @end itemize | |
26203 | ||
26204 | If any of these conditions are violated, the aggregate will be built in | |
26205 | a temporary (created either by the front-end or the code generator) and then | |
26206 | that temporary will be copied onto the target. | |
26207 | ||
26208 | @node The Size of Discriminated Records with Default Discriminants,Image Values For Nonscalar Types,Code Generation for Array Aggregates,Implementation of Specific Ada Features | |
73918baf | 26209 | @anchor{gnat_rm/implementation_of_specific_ada_features id13}@anchor{429}@anchor{gnat_rm/implementation_of_specific_ada_features the-size-of-discriminated-records-with-default-discriminants}@anchor{42a} |
b71d4b62 RA |
26210 | @section The Size of Discriminated Records with Default Discriminants |
26211 | ||
26212 | ||
26213 | If a discriminated type @code{T} has discriminants with default values, it is | |
26214 | possible to declare an object of this type without providing an explicit | |
26215 | constraint: | |
26216 | ||
26217 | @example | |
26218 | type Size is range 1..100; | |
26219 | ||
26220 | type Rec (D : Size := 15) is record | |
26221 | Name : String (1..D); | |
26222 | end T; | |
26223 | ||
26224 | Word : Rec; | |
26225 | @end example | |
26226 | ||
26227 | Such an object is said to be `unconstrained'. | |
26228 | The discriminant of the object | |
26229 | can be modified by a full assignment to the object, as long as it preserves the | |
26230 | relation between the value of the discriminant, and the value of the components | |
26231 | that depend on it: | |
26232 | ||
26233 | @example | |
26234 | Word := (3, "yes"); | |
26235 | ||
26236 | Word := (5, "maybe"); | |
26237 | ||
26238 | Word := (5, "no"); -- raises Constraint_Error | |
26239 | @end example | |
26240 | ||
26241 | In order to support this behavior efficiently, an unconstrained object is | |
26242 | given the maximum size that any value of the type requires. In the case | |
26243 | above, @code{Word} has storage for the discriminant and for | |
26244 | a @code{String} of length 100. | |
26245 | It is important to note that unconstrained objects do not require dynamic | |
26246 | allocation. It would be an improper implementation to place on the heap those | |
26247 | components whose size depends on discriminants. (This improper implementation | |
26248 | was used by some Ada83 compilers, where the @code{Name} component above | |
26249 | would have | |
26250 | been stored as a pointer to a dynamic string). Following the principle that | |
26251 | dynamic storage management should never be introduced implicitly, | |
26252 | an Ada compiler should reserve the full size for an unconstrained declared | |
26253 | object, and place it on the stack. | |
26254 | ||
26255 | This maximum size approach | |
26256 | has been a source of surprise to some users, who expect the default | |
26257 | values of the discriminants to determine the size reserved for an | |
26258 | unconstrained object: “If the default is 15, why should the object occupy | |
26259 | a larger size?” | |
26260 | The answer, of course, is that the discriminant may be later modified, | |
26261 | and its full range of values must be taken into account. This is why the | |
26262 | declaration: | |
26263 | ||
26264 | @example | |
26265 | type Rec (D : Positive := 15) is record | |
26266 | Name : String (1..D); | |
26267 | end record; | |
26268 | ||
26269 | Too_Large : Rec; | |
26270 | @end example | |
26271 | ||
26272 | is flagged by the compiler with a warning: | |
26273 | an attempt to create @code{Too_Large} will raise @code{Storage_Error}, | |
26274 | because the required size includes @code{Positive'Last} | |
26275 | bytes. As the first example indicates, the proper approach is to declare an | |
26276 | index type of ‘reasonable’ range so that unconstrained objects are not too | |
26277 | large. | |
26278 | ||
26279 | One final wrinkle: if the object is declared to be @code{aliased}, or if it is | |
26280 | created in the heap by means of an allocator, then it is `not' | |
26281 | unconstrained: | |
26282 | it is constrained by the default values of the discriminants, and those values | |
26283 | cannot be modified by full assignment. This is because in the presence of | |
26284 | aliasing all views of the object (which may be manipulated by different tasks, | |
26285 | say) must be consistent, so it is imperative that the object, once created, | |
26286 | remain invariant. | |
26287 | ||
26288 | @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 | |
73918baf | 26289 | @anchor{gnat_rm/implementation_of_specific_ada_features id14}@anchor{42b}@anchor{gnat_rm/implementation_of_specific_ada_features image-values-for-nonscalar-types}@anchor{42c} |
b71d4b62 RA |
26290 | @section Image Values For Nonscalar Types |
26291 | ||
26292 | ||
26293 | Ada 2022 defines the Image, Wide_Image, and Wide_Wide image attributes | |
26294 | for nonscalar types; earlier Ada versions defined these attributes only | |
26295 | for scalar types. Ada RM 4.10 provides some general guidance regarding | |
26296 | the default implementation of these attributes and the GNAT compiler | |
26297 | follows that guidance. However, beyond that the precise details of the | |
26298 | image text generated in these cases are deliberately not documented and are | |
26299 | subject to change. In particular, users should not rely on formatting details | |
26300 | (such as spaces or line breaking), record field order, image values for access | |
26301 | types, image values for types that have ancestor or subcomponent types | |
26302 | declared in non-Ada2022 code, image values for predefined types, or the | |
26303 | compiler’s choices regarding the implementation permissions described in | |
26304 | Ada RM 4.10. This list is not intended to be exhaustive. If more precise | |
26305 | control of image text is required for some type T, then T’Put_Image should be | |
26306 | explicitly specified. | |
26307 | ||
26308 | @node Strict Conformance to the Ada Reference Manual,,Image Values For Nonscalar Types,Implementation of Specific Ada Features | |
73918baf | 26309 | @anchor{gnat_rm/implementation_of_specific_ada_features id15}@anchor{42d}@anchor{gnat_rm/implementation_of_specific_ada_features strict-conformance-to-the-ada-reference-manual}@anchor{42e} |
b71d4b62 RA |
26310 | @section Strict Conformance to the Ada Reference Manual |
26311 | ||
26312 | ||
26313 | The dynamic semantics defined by the Ada Reference Manual impose a set of | |
26314 | run-time checks to be generated. By default, the GNAT compiler will insert many | |
26315 | run-time checks into the compiled code, including most of those required by the | |
26316 | Ada Reference Manual. However, there are two checks that are not enabled in | |
26317 | the default mode for efficiency reasons: checks for access before elaboration | |
26318 | on subprogram calls, and stack overflow checking (most operating systems do not | |
26319 | perform this check by default). | |
26320 | ||
26321 | Strict conformance to the Ada Reference Manual can be achieved by adding two | |
26322 | compiler options for dynamic checks for access-before-elaboration on subprogram | |
26323 | calls and generic instantiations (`-gnatE'), and stack overflow checking | |
26324 | (`-fstack-check'). | |
26325 | ||
26326 | Note that the result of a floating point arithmetic operation in overflow and | |
26327 | invalid situations, when the @code{Machine_Overflows} attribute of the result | |
26328 | type is @code{False}, is to generate IEEE NaN and infinite values. This is the | |
26329 | case for machines compliant with the IEEE floating-point standard, but on | |
26330 | machines that are not fully compliant with this standard, such as Alpha, the | |
26331 | `-mieee' compiler flag must be used for achieving IEEE confirming | |
26332 | behavior (although at the cost of a significant performance penalty), so | |
26333 | infinite and NaN values are properly generated. | |
26334 | ||
26335 | @node Implementation of Ada 2012 Features,GNAT language extensions,Implementation of Specific Ada Features,Top | |
73918baf | 26336 | @anchor{gnat_rm/implementation_of_ada_2012_features doc}@anchor{42f}@anchor{gnat_rm/implementation_of_ada_2012_features id1}@anchor{430}@anchor{gnat_rm/implementation_of_ada_2012_features implementation-of-ada-2012-features}@anchor{14} |
b71d4b62 RA |
26337 | @chapter Implementation of Ada 2012 Features |
26338 | ||
26339 | ||
26340 | @geindex Ada 2012 implementation status | |
26341 | ||
26342 | @geindex -gnat12 option (gcc) | |
26343 | ||
26344 | @geindex pragma Ada_2012 | |
26345 | ||
26346 | @geindex configuration pragma Ada_2012 | |
26347 | ||
26348 | @geindex Ada_2012 configuration pragma | |
26349 | ||
26350 | This chapter contains a complete list of Ada 2012 features that have been | |
26351 | implemented. | |
26352 | Generally, these features are only | |
26353 | available if the `-gnat12' (Ada 2012 features enabled) option is set, | |
26354 | which is the default behavior, | |
26355 | or if the configuration pragma @code{Ada_2012} is used. | |
26356 | ||
26357 | However, new pragmas, attributes, and restrictions are | |
26358 | unconditionally available, since the Ada 95 standard allows the addition of | |
26359 | new pragmas, attributes, and restrictions (there are exceptions, which are | |
26360 | documented in the individual descriptions), and also certain packages | |
26361 | were made available in earlier versions of Ada. | |
26362 | ||
26363 | An ISO date (YYYY-MM-DD) appears in parentheses on the description line. | |
26364 | This date shows the implementation date of the feature. Any wavefront | |
26365 | subsequent to this date will contain the indicated feature, as will any | |
26366 | subsequent releases. A date of 0000-00-00 means that GNAT has always | |
26367 | implemented the feature, or implemented it as soon as it appeared as a | |
26368 | binding interpretation. | |
26369 | ||
26370 | Each feature corresponds to an Ada Issue (‘AI’) approved by the Ada | |
26371 | standardization group (ISO/IEC JTC1/SC22/WG9) for inclusion in Ada 2012. | |
26372 | The features are ordered based on the relevant sections of the Ada | |
26373 | Reference Manual (“RM”). When a given AI relates to multiple points | |
26374 | in the RM, the earliest is used. | |
26375 | ||
26376 | A complete description of the AIs may be found in | |
26377 | @indicateurl{http://www.ada-auth.org/ai05-summary.html}. | |
26378 | ||
26379 | @geindex AI-0176 (Ada 2012 feature) | |
64d5610f | 26380 | |
64d5610f | 26381 | |
b71d4b62 | 26382 | @itemize * |
64d5610f | 26383 | |
b71d4b62 RA |
26384 | @item |
26385 | `AI-0176 Quantified expressions (2010-09-29)' | |
64d5610f | 26386 | |
b71d4b62 RA |
26387 | Both universally and existentially quantified expressions are implemented. |
26388 | They use the new syntax for iterators proposed in AI05-139-2, as well as | |
26389 | the standard Ada loop syntax. | |
64d5610f | 26390 | |
b71d4b62 RA |
26391 | RM References: 1.01.04 (12) 2.09 (2/2) 4.04 (7) 4.05.09 (0) |
26392 | @end itemize | |
64d5610f | 26393 | |
b71d4b62 | 26394 | @geindex AI-0079 (Ada 2012 feature) |
64d5610f | 26395 | |
64d5610f | 26396 | |
b71d4b62 | 26397 | @itemize * |
64d5610f | 26398 | |
b71d4b62 RA |
26399 | @item |
26400 | `AI-0079 Allow other_format characters in source (2010-07-10)' | |
64d5610f | 26401 | |
b71d4b62 RA |
26402 | Wide characters in the unicode category `other_format' are now allowed in |
26403 | source programs between tokens, but not within a token such as an identifier. | |
64d5610f | 26404 | |
b71d4b62 RA |
26405 | RM References: 2.01 (4/2) 2.02 (7) |
26406 | @end itemize | |
64d5610f | 26407 | |
b71d4b62 | 26408 | @geindex AI-0091 (Ada 2012 feature) |
64d5610f | 26409 | |
64d5610f | 26410 | |
b71d4b62 RA |
26411 | @itemize * |
26412 | ||
26413 | @item | |
26414 | `AI-0091 Do not allow other_format in identifiers (0000-00-00)' | |
64d5610f | 26415 | |
b71d4b62 RA |
26416 | Wide characters in the unicode category `other_format' are not permitted |
26417 | within an identifier, since this can be a security problem. The error | |
26418 | message for this case has been improved to be more specific, but GNAT has | |
26419 | never allowed such characters to appear in identifiers. | |
64d5610f | 26420 | |
b71d4b62 RA |
26421 | 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) |
26422 | @end itemize | |
26423 | ||
26424 | @geindex AI-0100 (Ada 2012 feature) | |
64d5610f ML |
26425 | |
26426 | ||
26427 | @itemize * | |
26428 | ||
26429 | @item | |
b71d4b62 | 26430 | `AI-0100 Placement of pragmas (2010-07-01)' |
64d5610f | 26431 | |
b71d4b62 RA |
26432 | This AI is an earlier version of AI-163. It simplifies the rules |
26433 | for legal placement of pragmas. In the case of lists that allow pragmas, if | |
26434 | the list may have no elements, then the list may consist solely of pragmas. | |
26435 | ||
26436 | RM References: 2.08 (7) | |
64d5610f ML |
26437 | @end itemize |
26438 | ||
b71d4b62 | 26439 | @geindex AI-0163 (Ada 2012 feature) |
64d5610f | 26440 | |
64d5610f | 26441 | |
b71d4b62 | 26442 | @itemize * |
64d5610f | 26443 | |
b71d4b62 RA |
26444 | @item |
26445 | `AI-0163 Pragmas in place of null (2010-07-01)' | |
64d5610f | 26446 | |
b71d4b62 RA |
26447 | A statement sequence may be composed entirely of pragmas. It is no longer |
26448 | necessary to add a dummy @code{null} statement to make the sequence legal. | |
26449 | ||
26450 | RM References: 2.08 (7) 2.08 (16) | |
26451 | @end itemize | |
26452 | ||
26453 | @geindex AI-0080 (Ada 2012 feature) | |
64d5610f ML |
26454 | |
26455 | ||
26456 | @itemize * | |
26457 | ||
26458 | @item | |
b71d4b62 | 26459 | `AI-0080 ‘View of’ not needed if clear from context (0000-00-00)' |
64d5610f | 26460 | |
b71d4b62 | 26461 | This is an editorial change only, described as non-testable in the AI. |
64d5610f | 26462 | |
b71d4b62 RA |
26463 | RM References: 3.01 (7) |
26464 | @end itemize | |
26465 | ||
26466 | @geindex AI-0183 (Ada 2012 feature) | |
26467 | ||
26468 | ||
26469 | @itemize * | |
64d5610f ML |
26470 | |
26471 | @item | |
b71d4b62 RA |
26472 | `AI-0183 Aspect specifications (2010-08-16)' |
26473 | ||
26474 | Aspect specifications have been fully implemented except for pre and post- | |
26475 | conditions, and type invariants, which have their own separate AI’s. All | |
26476 | forms of declarations listed in the AI are supported. The following is a | |
26477 | list of the aspects supported (with GNAT implementation aspects marked) | |
64d5610f ML |
26478 | @end itemize |
26479 | ||
64d5610f | 26480 | |
b71d4b62 RA |
26481 | @multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxx} |
26482 | @headitem | |
64d5610f | 26483 | |
b71d4b62 | 26484 | Supported Aspect |
64d5610f | 26485 | |
b71d4b62 | 26486 | @tab |
64d5610f | 26487 | |
b71d4b62 | 26488 | Source |
64d5610f | 26489 | |
b71d4b62 | 26490 | @item |
64d5610f | 26491 | |
b71d4b62 | 26492 | @code{Ada_2005} |
64d5610f | 26493 | |
b71d4b62 | 26494 | @tab |
64d5610f | 26495 | |
b71d4b62 | 26496 | – GNAT |
64d5610f | 26497 | |
b71d4b62 | 26498 | @item |
64d5610f | 26499 | |
b71d4b62 | 26500 | @code{Ada_2012} |
64d5610f | 26501 | |
b71d4b62 | 26502 | @tab |
64d5610f | 26503 | |
b71d4b62 | 26504 | – GNAT |
64d5610f | 26505 | |
b71d4b62 | 26506 | @item |
64d5610f | 26507 | |
b71d4b62 | 26508 | @code{Address} |
64d5610f | 26509 | |
b71d4b62 RA |
26510 | @tab |
26511 | ||
26512 | @item | |
26513 | ||
26514 | @code{Alignment} | |
26515 | ||
26516 | @tab | |
26517 | ||
26518 | @item | |
26519 | ||
26520 | @code{Atomic} | |
26521 | ||
26522 | @tab | |
26523 | ||
26524 | @item | |
26525 | ||
26526 | @code{Atomic_Components} | |
26527 | ||
26528 | @tab | |
26529 | ||
26530 | @item | |
26531 | ||
26532 | @code{Bit_Order} | |
26533 | ||
26534 | @tab | |
26535 | ||
26536 | @item | |
26537 | ||
26538 | @code{Component_Size} | |
26539 | ||
26540 | @tab | |
26541 | ||
26542 | @item | |
26543 | ||
26544 | @code{Contract_Cases} | |
26545 | ||
26546 | @tab | |
26547 | ||
26548 | – GNAT | |
26549 | ||
26550 | @item | |
26551 | ||
26552 | @code{Discard_Names} | |
26553 | ||
26554 | @tab | |
26555 | ||
26556 | @item | |
26557 | ||
26558 | @code{External_Tag} | |
64d5610f | 26559 | |
b71d4b62 | 26560 | @tab |
64d5610f | 26561 | |
b71d4b62 | 26562 | @item |
64d5610f | 26563 | |
b71d4b62 | 26564 | @code{Favor_Top_Level} |
64d5610f | 26565 | |
b71d4b62 | 26566 | @tab |
64d5610f | 26567 | |
b71d4b62 | 26568 | – GNAT |
64d5610f | 26569 | |
b71d4b62 | 26570 | @item |
64d5610f | 26571 | |
b71d4b62 | 26572 | @code{Inline} |
64d5610f | 26573 | |
b71d4b62 | 26574 | @tab |
64d5610f | 26575 | |
b71d4b62 | 26576 | @item |
64d5610f | 26577 | |
b71d4b62 | 26578 | @code{Inline_Always} |
64d5610f | 26579 | |
b71d4b62 | 26580 | @tab |
64d5610f | 26581 | |
b71d4b62 | 26582 | – GNAT |
64d5610f | 26583 | |
b71d4b62 | 26584 | @item |
64d5610f | 26585 | |
b71d4b62 | 26586 | @code{Invariant} |
64d5610f | 26587 | |
b71d4b62 | 26588 | @tab |
64d5610f | 26589 | |
b71d4b62 | 26590 | – GNAT |
64d5610f | 26591 | |
b71d4b62 | 26592 | @item |
64d5610f | 26593 | |
b71d4b62 | 26594 | @code{Machine_Radix} |
64d5610f | 26595 | |
b71d4b62 | 26596 | @tab |
64d5610f | 26597 | |
b71d4b62 | 26598 | @item |
64d5610f | 26599 | |
b71d4b62 | 26600 | @code{No_Return} |
64d5610f | 26601 | |
b71d4b62 | 26602 | @tab |
64d5610f | 26603 | |
b71d4b62 | 26604 | @item |
64d5610f | 26605 | |
b71d4b62 | 26606 | @code{Object_Size} |
64d5610f | 26607 | |
b71d4b62 | 26608 | @tab |
64d5610f | 26609 | |
b71d4b62 | 26610 | – GNAT |
64d5610f | 26611 | |
b71d4b62 | 26612 | @item |
64d5610f | 26613 | |
b71d4b62 | 26614 | @code{Pack} |
64d5610f | 26615 | |
b71d4b62 | 26616 | @tab |
64d5610f | 26617 | |
b71d4b62 | 26618 | @item |
64d5610f | 26619 | |
b71d4b62 | 26620 | @code{Persistent_BSS} |
64d5610f | 26621 | |
b71d4b62 | 26622 | @tab |
64d5610f | 26623 | |
b71d4b62 | 26624 | – GNAT |
64d5610f | 26625 | |
b71d4b62 | 26626 | @item |
64d5610f | 26627 | |
b71d4b62 | 26628 | @code{Post} |
64d5610f | 26629 | |
b71d4b62 | 26630 | @tab |
64d5610f | 26631 | |
b71d4b62 | 26632 | @item |
64d5610f | 26633 | |
b71d4b62 | 26634 | @code{Pre} |
64d5610f | 26635 | |
b71d4b62 | 26636 | @tab |
64d5610f | 26637 | |
b71d4b62 | 26638 | @item |
64d5610f | 26639 | |
b71d4b62 | 26640 | @code{Predicate} |
64d5610f | 26641 | |
b71d4b62 | 26642 | @tab |
64d5610f | 26643 | |
b71d4b62 | 26644 | @item |
64d5610f | 26645 | |
b71d4b62 | 26646 | @code{Preelaborable_Initialization} |
64d5610f | 26647 | |
b71d4b62 | 26648 | @tab |
64d5610f | 26649 | |
b71d4b62 | 26650 | @item |
64d5610f | 26651 | |
b71d4b62 | 26652 | @code{Pure_Function} |
64d5610f | 26653 | |
b71d4b62 | 26654 | @tab |
64d5610f | 26655 | |
b71d4b62 | 26656 | – GNAT |
64d5610f | 26657 | |
b71d4b62 | 26658 | @item |
64d5610f | 26659 | |
b71d4b62 | 26660 | @code{Remote_Access_Type} |
64d5610f | 26661 | |
b71d4b62 | 26662 | @tab |
64d5610f | 26663 | |
b71d4b62 | 26664 | – GNAT |
64d5610f | 26665 | |
b71d4b62 | 26666 | @item |
64d5610f | 26667 | |
b71d4b62 | 26668 | @code{Shared} |
64d5610f | 26669 | |
b71d4b62 | 26670 | @tab |
64d5610f | 26671 | |
b71d4b62 | 26672 | – GNAT |
64d5610f | 26673 | |
b71d4b62 | 26674 | @item |
64d5610f | 26675 | |
b71d4b62 RA |
26676 | @code{Size} |
26677 | ||
26678 | @tab | |
64d5610f | 26679 | |
b71d4b62 | 26680 | @item |
64d5610f | 26681 | |
b71d4b62 | 26682 | @code{Storage_Pool} |
64d5610f | 26683 | |
b71d4b62 | 26684 | @tab |
64d5610f | 26685 | |
b71d4b62 | 26686 | @item |
64d5610f | 26687 | |
b71d4b62 | 26688 | @code{Storage_Size} |
64d5610f | 26689 | |
b71d4b62 | 26690 | @tab |
64d5610f | 26691 | |
b71d4b62 | 26692 | @item |
64d5610f | 26693 | |
b71d4b62 | 26694 | @code{Stream_Size} |
64d5610f | 26695 | |
b71d4b62 | 26696 | @tab |
64d5610f | 26697 | |
b71d4b62 | 26698 | @item |
64d5610f | 26699 | |
b71d4b62 | 26700 | @code{Suppress} |
64d5610f | 26701 | |
b71d4b62 | 26702 | @tab |
64d5610f | 26703 | |
b71d4b62 | 26704 | @item |
64d5610f | 26705 | |
b71d4b62 | 26706 | @code{Suppress_Debug_Info} |
64d5610f | 26707 | |
b71d4b62 | 26708 | @tab |
64d5610f | 26709 | |
b71d4b62 | 26710 | – GNAT |
64d5610f | 26711 | |
b71d4b62 | 26712 | @item |
64d5610f | 26713 | |
b71d4b62 | 26714 | @code{Test_Case} |
64d5610f | 26715 | |
b71d4b62 | 26716 | @tab |
64d5610f | 26717 | |
b71d4b62 | 26718 | – GNAT |
64d5610f | 26719 | |
b71d4b62 | 26720 | @item |
64d5610f | 26721 | |
b71d4b62 | 26722 | @code{Thread_Local_Storage} |
64d5610f | 26723 | |
b71d4b62 | 26724 | @tab |
64d5610f | 26725 | |
b71d4b62 | 26726 | – GNAT |
64d5610f | 26727 | |
b71d4b62 | 26728 | @item |
64d5610f | 26729 | |
b71d4b62 | 26730 | @code{Type_Invariant} |
64d5610f | 26731 | |
b71d4b62 | 26732 | @tab |
64d5610f | 26733 | |
b71d4b62 | 26734 | @item |
64d5610f | 26735 | |
b71d4b62 | 26736 | @code{Unchecked_Union} |
64d5610f | 26737 | |
b71d4b62 | 26738 | @tab |
64d5610f | 26739 | |
b71d4b62 | 26740 | @item |
64d5610f | 26741 | |
b71d4b62 | 26742 | @code{Universal_Aliasing} |
64d5610f | 26743 | |
b71d4b62 | 26744 | @tab |
64d5610f | 26745 | |
b71d4b62 | 26746 | – GNAT |
64d5610f | 26747 | |
b71d4b62 | 26748 | @item |
64d5610f | 26749 | |
b71d4b62 | 26750 | @code{Unmodified} |
64d5610f | 26751 | |
b71d4b62 | 26752 | @tab |
64d5610f | 26753 | |
b71d4b62 | 26754 | – GNAT |
64d5610f | 26755 | |
b71d4b62 | 26756 | @item |
64d5610f | 26757 | |
b71d4b62 | 26758 | @code{Unreferenced} |
64d5610f | 26759 | |
b71d4b62 | 26760 | @tab |
64d5610f | 26761 | |
b71d4b62 | 26762 | – GNAT |
64d5610f | 26763 | |
b71d4b62 | 26764 | @item |
64d5610f | 26765 | |
b71d4b62 | 26766 | @code{Unreferenced_Objects} |
64d5610f | 26767 | |
b71d4b62 | 26768 | @tab |
64d5610f | 26769 | |
b71d4b62 | 26770 | – GNAT |
64d5610f | 26771 | |
b71d4b62 | 26772 | @item |
64d5610f | 26773 | |
b71d4b62 | 26774 | @code{Unsuppress} |
64d5610f | 26775 | |
b71d4b62 | 26776 | @tab |
64d5610f | 26777 | |
b71d4b62 | 26778 | @item |
64d5610f | 26779 | |
b71d4b62 | 26780 | @code{Value_Size} |
64d5610f | 26781 | |
b71d4b62 | 26782 | @tab |
64d5610f | 26783 | |
b71d4b62 | 26784 | – GNAT |
64d5610f | 26785 | |
b71d4b62 | 26786 | @item |
64d5610f | 26787 | |
b71d4b62 | 26788 | @code{Volatile} |
64d5610f | 26789 | |
b71d4b62 | 26790 | @tab |
64d5610f | 26791 | |
b71d4b62 | 26792 | @item |
64d5610f | 26793 | |
b71d4b62 | 26794 | @code{Volatile_Components} |
64d5610f | 26795 | |
b71d4b62 | 26796 | @tab |
64d5610f | 26797 | |
b71d4b62 | 26798 | @item |
64d5610f | 26799 | |
b71d4b62 | 26800 | @code{Warnings} |
64d5610f | 26801 | |
b71d4b62 | 26802 | @tab |
64d5610f | 26803 | |
b71d4b62 | 26804 | – GNAT |
64d5610f | 26805 | |
b71d4b62 | 26806 | @end multitable |
64d5610f | 26807 | |
64d5610f | 26808 | |
b71d4b62 | 26809 | @quotation |
64d5610f | 26810 | |
b71d4b62 RA |
26811 | Note that for aspects with an expression, e.g. @code{Size}, the expression is |
26812 | treated like a default expression (visibility is analyzed at the point of | |
26813 | occurrence of the aspect, but evaluation of the expression occurs at the | |
26814 | freeze point of the entity involved). | |
64d5610f | 26815 | |
b71d4b62 RA |
26816 | RM References: 3.02.01 (3) 3.02.02 (2) 3.03.01 (2/2) 3.08 (6) |
26817 | 3.09.03 (1.1/2) 6.01 (2/2) 6.07 (2/2) 9.05.02 (2/2) 7.01 (3) 7.03 | |
26818 | (2) 7.03 (3) 9.01 (2/2) 9.01 (3/2) 9.04 (2/2) 9.04 (3/2) | |
26819 | 9.05.02 (2/2) 11.01 (2) 12.01 (3) 12.03 (2/2) 12.04 (2/2) 12.05 (2) | |
26820 | 12.06 (2.1/2) 12.06 (2.2/2) 12.07 (2) 13.01 (0.1/2) 13.03 (5/1) | |
26821 | 13.03.01 (0) | |
26822 | @end quotation | |
64d5610f | 26823 | |
b71d4b62 | 26824 | @geindex AI-0128 (Ada 2012 feature) |
64d5610f ML |
26825 | |
26826 | ||
26827 | @itemize * | |
26828 | ||
26829 | @item | |
b71d4b62 | 26830 | `AI-0128 Inequality is a primitive operation (0000-00-00)' |
64d5610f | 26831 | |
b71d4b62 RA |
26832 | If an equality operator (“=”) is declared for a type, then the implicitly |
26833 | declared inequality operator (“/=”) is a primitive operation of the type. | |
26834 | This is the only reasonable interpretation, and is the one always implemented | |
26835 | by GNAT, but the RM was not entirely clear in making this point. | |
64d5610f | 26836 | |
b71d4b62 | 26837 | RM References: 3.02.03 (6) 6.06 (6) |
64d5610f ML |
26838 | @end itemize |
26839 | ||
b71d4b62 | 26840 | @geindex AI-0003 (Ada 2012 feature) |
64d5610f ML |
26841 | |
26842 | ||
26843 | @itemize * | |
26844 | ||
26845 | @item | |
b71d4b62 | 26846 | `AI-0003 Qualified expressions as names (2010-07-11)' |
64d5610f | 26847 | |
b71d4b62 RA |
26848 | In Ada 2012, a qualified expression is considered to be syntactically a name, |
26849 | meaning that constructs such as @code{A'(F(X)).B} are now legal. This is | |
26850 | useful in disambiguating some cases of overloading. | |
64d5610f | 26851 | |
b71d4b62 RA |
26852 | RM References: 3.03 (11) 3.03 (21) 4.01 (2) 4.04 (7) 4.07 (3) |
26853 | 5.04 (7) | |
64d5610f ML |
26854 | @end itemize |
26855 | ||
b71d4b62 | 26856 | @geindex AI-0120 (Ada 2012 feature) |
64d5610f ML |
26857 | |
26858 | ||
26859 | @itemize * | |
26860 | ||
26861 | @item | |
b71d4b62 | 26862 | `AI-0120 Constant instance of protected object (0000-00-00)' |
64d5610f | 26863 | |
b71d4b62 RA |
26864 | This is an RM editorial change only. The section that lists objects that are |
26865 | constant failed to include the current instance of a protected object | |
26866 | within a protected function. This has always been treated as a constant | |
26867 | in GNAT. | |
64d5610f | 26868 | |
b71d4b62 | 26869 | RM References: 3.03 (21) |
64d5610f ML |
26870 | @end itemize |
26871 | ||
b71d4b62 | 26872 | @geindex AI-0008 (Ada 2012 feature) |
64d5610f ML |
26873 | |
26874 | ||
26875 | @itemize * | |
26876 | ||
26877 | @item | |
b71d4b62 | 26878 | `AI-0008 General access to constrained objects (0000-00-00)' |
64d5610f | 26879 | |
b71d4b62 RA |
26880 | The wording in the RM implied that if you have a general access to a |
26881 | constrained object, it could be used to modify the discriminants. This was | |
26882 | obviously not intended. @code{Constraint_Error} should be raised, and GNAT | |
26883 | has always done so in this situation. | |
64d5610f | 26884 | |
b71d4b62 RA |
26885 | RM References: 3.03 (23) 3.10.02 (26/2) 4.01 (9) 6.04.01 (17) 8.05.01 (5/2) |
26886 | @end itemize | |
64d5610f | 26887 | |
b71d4b62 | 26888 | @geindex AI-0093 (Ada 2012 feature) |
64d5610f | 26889 | |
64d5610f | 26890 | |
b71d4b62 | 26891 | @itemize * |
64d5610f | 26892 | |
b71d4b62 RA |
26893 | @item |
26894 | `AI-0093 Additional rules use immutably limited (0000-00-00)' | |
64d5610f | 26895 | |
b71d4b62 RA |
26896 | This is an editorial change only, to make more widespread use of the Ada 2012 |
26897 | ‘immutably limited’. | |
64d5610f | 26898 | |
b71d4b62 RA |
26899 | RM References: 3.03 (23.4/3) |
26900 | @end itemize | |
64d5610f | 26901 | |
b71d4b62 | 26902 | @geindex AI-0096 (Ada 2012 feature) |
64d5610f | 26903 | |
64d5610f | 26904 | |
b71d4b62 | 26905 | @itemize * |
64d5610f | 26906 | |
b71d4b62 RA |
26907 | @item |
26908 | `AI-0096 Deriving from formal private types (2010-07-20)' | |
64d5610f | 26909 | |
b71d4b62 RA |
26910 | In general it is illegal for a type derived from a formal limited type to be |
26911 | nonlimited. This AI makes an exception to this rule: derivation is legal | |
26912 | if it appears in the private part of the generic, and the formal type is not | |
26913 | tagged. If the type is tagged, the legality check must be applied to the | |
26914 | private part of the package. | |
64d5610f | 26915 | |
b71d4b62 RA |
26916 | RM References: 3.04 (5.1/2) 6.02 (7) |
26917 | @end itemize | |
64d5610f | 26918 | |
b71d4b62 | 26919 | @geindex AI-0181 (Ada 2012 feature) |
64d5610f | 26920 | |
64d5610f | 26921 | |
b71d4b62 | 26922 | @itemize * |
64d5610f | 26923 | |
b71d4b62 RA |
26924 | @item |
26925 | `AI-0181 Soft hyphen is a non-graphic character (2010-07-23)' | |
64d5610f | 26926 | |
b71d4b62 RA |
26927 | From Ada 2005 on, soft hyphen is considered a non-graphic character, which |
26928 | means that it has a special name (@code{SOFT_HYPHEN}) in conjunction with the | |
26929 | @code{Image} and @code{Value} attributes for the character types. Strictly | |
26930 | speaking this is an inconsistency with Ada 95, but in practice the use of | |
26931 | these attributes is so obscure that it will not cause problems. | |
64d5610f | 26932 | |
b71d4b62 RA |
26933 | RM References: 3.05.02 (2/2) A.01 (35/2) A.03.03 (21) |
26934 | @end itemize | |
64d5610f | 26935 | |
b71d4b62 | 26936 | @geindex AI-0182 (Ada 2012 feature) |
64d5610f | 26937 | |
64d5610f | 26938 | |
b71d4b62 | 26939 | @itemize * |
64d5610f | 26940 | |
b71d4b62 RA |
26941 | @item |
26942 | `AI-0182 Additional forms for' @code{Character'Value} `(0000-00-00)' | |
64d5610f | 26943 | |
b71d4b62 RA |
26944 | This AI allows @code{Character'Value} to accept the string @code{'?'} where |
26945 | @code{?} is any character including non-graphic control characters. GNAT has | |
26946 | always accepted such strings. It also allows strings such as | |
26947 | @code{HEX_00000041} to be accepted, but GNAT does not take advantage of this | |
26948 | permission and raises @code{Constraint_Error}, as is certainly still | |
26949 | permitted. | |
64d5610f | 26950 | |
b71d4b62 RA |
26951 | RM References: 3.05 (56/2) |
26952 | @end itemize | |
64d5610f | 26953 | |
b71d4b62 | 26954 | @geindex AI-0214 (Ada 2012 feature) |
64d5610f | 26955 | |
64d5610f | 26956 | |
b71d4b62 | 26957 | @itemize * |
64d5610f | 26958 | |
b71d4b62 RA |
26959 | @item |
26960 | `AI-0214 Defaulted discriminants for limited tagged (2010-10-01)' | |
64d5610f | 26961 | |
b71d4b62 RA |
26962 | Ada 2012 relaxes the restriction that forbids discriminants of tagged types |
26963 | to have default expressions by allowing them when the type is limited. It | |
26964 | is often useful to define a default value for a discriminant even though | |
26965 | it can’t be changed by assignment. | |
64d5610f | 26966 | |
b71d4b62 RA |
26967 | RM References: 3.07 (9.1/2) 3.07.02 (3) |
26968 | @end itemize | |
64d5610f | 26969 | |
b71d4b62 | 26970 | @geindex AI-0102 (Ada 2012 feature) |
64d5610f | 26971 | |
64d5610f | 26972 | |
b71d4b62 | 26973 | @itemize * |
64d5610f | 26974 | |
b71d4b62 RA |
26975 | @item |
26976 | `AI-0102 Some implicit conversions are illegal (0000-00-00)' | |
64d5610f | 26977 | |
b71d4b62 RA |
26978 | It is illegal to assign an anonymous access constant to an anonymous access |
26979 | variable. The RM did not have a clear rule to prevent this, but GNAT has | |
26980 | always generated an error for this usage. | |
64d5610f | 26981 | |
b71d4b62 RA |
26982 | RM References: 3.07 (16) 3.07.01 (9) 6.04.01 (6) 8.06 (27/2) |
26983 | @end itemize | |
64d5610f | 26984 | |
b71d4b62 | 26985 | @geindex AI-0158 (Ada 2012 feature) |
64d5610f | 26986 | |
64d5610f | 26987 | |
b71d4b62 | 26988 | @itemize * |
64d5610f | 26989 | |
b71d4b62 RA |
26990 | @item |
26991 | `AI-0158 Generalizing membership tests (2010-09-16)' | |
64d5610f | 26992 | |
b71d4b62 RA |
26993 | This AI extends the syntax of membership tests to simplify complex conditions |
26994 | that can be expressed as membership in a subset of values of any type. It | |
26995 | introduces syntax for a list of expressions that may be used in loop contexts | |
26996 | as well. | |
64d5610f | 26997 | |
b71d4b62 RA |
26998 | RM References: 3.08.01 (5) 4.04 (3) 4.05.02 (3) 4.05.02 (5) 4.05.02 (27) |
26999 | @end itemize | |
64d5610f | 27000 | |
b71d4b62 | 27001 | @geindex AI-0173 (Ada 2012 feature) |
64d5610f | 27002 | |
64d5610f | 27003 | |
b71d4b62 | 27004 | @itemize * |
64d5610f | 27005 | |
b71d4b62 RA |
27006 | @item |
27007 | `AI-0173 Testing if tags represent abstract types (2010-07-03)' | |
64d5610f | 27008 | |
b71d4b62 RA |
27009 | The function @code{Ada.Tags.Type_Is_Abstract} returns @code{True} if invoked |
27010 | with the tag of an abstract type, and @code{False} otherwise. | |
64d5610f | 27011 | |
b71d4b62 RA |
27012 | RM References: 3.09 (7.4/2) 3.09 (12.4/2) |
27013 | @end itemize | |
64d5610f | 27014 | |
b71d4b62 | 27015 | @geindex AI-0076 (Ada 2012 feature) |
64d5610f | 27016 | |
64d5610f | 27017 | |
b71d4b62 | 27018 | @itemize * |
64d5610f | 27019 | |
b71d4b62 RA |
27020 | @item |
27021 | `AI-0076 function with controlling result (0000-00-00)' | |
64d5610f | 27022 | |
b71d4b62 RA |
27023 | This is an editorial change only. The RM defines calls with controlling |
27024 | results, but uses the term ‘function with controlling result’ without an | |
27025 | explicit definition. | |
64d5610f | 27026 | |
b71d4b62 RA |
27027 | RM References: 3.09.02 (2/2) |
27028 | @end itemize | |
64d5610f | 27029 | |
b71d4b62 | 27030 | @geindex AI-0126 (Ada 2012 feature) |
64d5610f | 27031 | |
64d5610f | 27032 | |
b71d4b62 | 27033 | @itemize * |
64d5610f | 27034 | |
b71d4b62 RA |
27035 | @item |
27036 | `AI-0126 Dispatching with no declared operation (0000-00-00)' | |
64d5610f | 27037 | |
b71d4b62 RA |
27038 | This AI clarifies dispatching rules, and simply confirms that dispatching |
27039 | executes the operation of the parent type when there is no explicitly or | |
27040 | implicitly declared operation for the descendant type. This has always been | |
27041 | the case in all versions of GNAT. | |
64d5610f | 27042 | |
b71d4b62 RA |
27043 | RM References: 3.09.02 (20/2) 3.09.02 (20.1/2) 3.09.02 (20.2/2) |
27044 | @end itemize | |
64d5610f | 27045 | |
b71d4b62 | 27046 | @geindex AI-0097 (Ada 2012 feature) |
64d5610f | 27047 | |
64d5610f | 27048 | |
b71d4b62 | 27049 | @itemize * |
64d5610f | 27050 | |
b71d4b62 RA |
27051 | @item |
27052 | `AI-0097 Treatment of abstract null extension (2010-07-19)' | |
64d5610f | 27053 | |
b71d4b62 RA |
27054 | The RM as written implied that in some cases it was possible to create an |
27055 | object of an abstract type, by having an abstract extension inherit a non- | |
27056 | abstract constructor from its parent type. This mistake has been corrected | |
27057 | in GNAT and in the RM, and this construct is now illegal. | |
64d5610f | 27058 | |
b71d4b62 RA |
27059 | RM References: 3.09.03 (4/2) |
27060 | @end itemize | |
64d5610f | 27061 | |
b71d4b62 | 27062 | @geindex AI-0203 (Ada 2012 feature) |
64d5610f | 27063 | |
64d5610f | 27064 | |
b71d4b62 | 27065 | @itemize * |
64d5610f | 27066 | |
b71d4b62 RA |
27067 | @item |
27068 | `AI-0203 Extended return cannot be abstract (0000-00-00)' | |
64d5610f | 27069 | |
b71d4b62 RA |
27070 | A return_subtype_indication cannot denote an abstract subtype. GNAT has never |
27071 | permitted such usage. | |
64d5610f | 27072 | |
b71d4b62 RA |
27073 | RM References: 3.09.03 (8/3) |
27074 | @end itemize | |
64d5610f | 27075 | |
b71d4b62 | 27076 | @geindex AI-0198 (Ada 2012 feature) |
64d5610f | 27077 | |
64d5610f | 27078 | |
b71d4b62 | 27079 | @itemize * |
64d5610f | 27080 | |
b71d4b62 RA |
27081 | @item |
27082 | `AI-0198 Inheriting abstract operators (0000-00-00)' | |
64d5610f | 27083 | |
b71d4b62 RA |
27084 | This AI resolves a conflict between two rules involving inherited abstract |
27085 | operations and predefined operators. If a derived numeric type inherits | |
27086 | an abstract operator, it overrides the predefined one. This interpretation | |
27087 | was always the one implemented in GNAT. | |
64d5610f | 27088 | |
b71d4b62 RA |
27089 | RM References: 3.09.03 (4/3) |
27090 | @end itemize | |
64d5610f | 27091 | |
b71d4b62 | 27092 | @geindex AI-0073 (Ada 2012 feature) |
64d5610f | 27093 | |
64d5610f | 27094 | |
b71d4b62 | 27095 | @itemize * |
64d5610f | 27096 | |
b71d4b62 RA |
27097 | @item |
27098 | `AI-0073 Functions returning abstract types (2010-07-10)' | |
64d5610f | 27099 | |
b71d4b62 RA |
27100 | This AI covers a number of issues regarding returning abstract types. In |
27101 | particular generic functions cannot have abstract result types or access | |
27102 | result types designated an abstract type. There are some other cases which | |
27103 | are detailed in the AI. Note that this binding interpretation has not been | |
27104 | retrofitted to operate before Ada 2012 mode, since it caused a significant | |
27105 | number of regressions. | |
64d5610f | 27106 | |
b71d4b62 RA |
27107 | RM References: 3.09.03 (8) 3.09.03 (10) 6.05 (8/2) |
27108 | @end itemize | |
64d5610f | 27109 | |
b71d4b62 | 27110 | @geindex AI-0070 (Ada 2012 feature) |
64d5610f | 27111 | |
64d5610f | 27112 | |
b71d4b62 | 27113 | @itemize * |
64d5610f | 27114 | |
b71d4b62 RA |
27115 | @item |
27116 | `AI-0070 Elaboration of interface types (0000-00-00)' | |
64d5610f | 27117 | |
b71d4b62 RA |
27118 | This is an editorial change only, there are no testable consequences short of |
27119 | checking for the absence of generated code for an interface declaration. | |
64d5610f | 27120 | |
b71d4b62 RA |
27121 | RM References: 3.09.04 (18/2) |
27122 | @end itemize | |
64d5610f | 27123 | |
b71d4b62 | 27124 | @geindex AI-0208 (Ada 2012 feature) |
64d5610f | 27125 | |
64d5610f | 27126 | |
b71d4b62 | 27127 | @itemize * |
64d5610f | 27128 | |
b71d4b62 RA |
27129 | @item |
27130 | `AI-0208 Characteristics of incomplete views (0000-00-00)' | |
64d5610f | 27131 | |
b71d4b62 RA |
27132 | The wording in the Ada 2005 RM concerning characteristics of incomplete views |
27133 | was incorrect and implied that some programs intended to be legal were now | |
27134 | illegal. GNAT had never considered such programs illegal, so it has always | |
27135 | implemented the intent of this AI. | |
64d5610f | 27136 | |
b71d4b62 RA |
27137 | RM References: 3.10.01 (2.4/2) 3.10.01 (2.6/2) |
27138 | @end itemize | |
64d5610f | 27139 | |
b71d4b62 | 27140 | @geindex AI-0162 (Ada 2012 feature) |
64d5610f | 27141 | |
64d5610f | 27142 | |
b71d4b62 | 27143 | @itemize * |
64d5610f | 27144 | |
b71d4b62 RA |
27145 | @item |
27146 | `AI-0162 Incomplete type completed by partial view (2010-09-15)' | |
64d5610f | 27147 | |
b71d4b62 RA |
27148 | Incomplete types are made more useful by allowing them to be completed by |
27149 | private types and private extensions. | |
64d5610f | 27150 | |
b71d4b62 RA |
27151 | RM References: 3.10.01 (2.5/2) 3.10.01 (2.6/2) 3.10.01 (3) 3.10.01 (4/2) |
27152 | @end itemize | |
64d5610f | 27153 | |
b71d4b62 | 27154 | @geindex AI-0098 (Ada 2012 feature) |
64d5610f | 27155 | |
64d5610f | 27156 | |
b71d4b62 | 27157 | @itemize * |
64d5610f | 27158 | |
b71d4b62 RA |
27159 | @item |
27160 | `AI-0098 Anonymous subprogram access restrictions (0000-00-00)' | |
64d5610f | 27161 | |
b71d4b62 RA |
27162 | An unintentional omission in the RM implied some inconsistent restrictions on |
27163 | the use of anonymous access to subprogram values. These restrictions were not | |
27164 | intentional, and have never been enforced by GNAT. | |
64d5610f | 27165 | |
b71d4b62 RA |
27166 | RM References: 3.10.01 (6) 3.10.01 (9.2/2) |
27167 | @end itemize | |
64d5610f | 27168 | |
b71d4b62 | 27169 | @geindex AI-0199 (Ada 2012 feature) |
64d5610f | 27170 | |
64d5610f | 27171 | |
b71d4b62 | 27172 | @itemize * |
64d5610f | 27173 | |
b71d4b62 RA |
27174 | @item |
27175 | `AI-0199 Aggregate with anonymous access components (2010-07-14)' | |
64d5610f | 27176 | |
b71d4b62 RA |
27177 | A choice list in a record aggregate can include several components of |
27178 | (distinct) anonymous access types as long as they have matching designated | |
27179 | subtypes. | |
64d5610f | 27180 | |
b71d4b62 RA |
27181 | RM References: 4.03.01 (16) |
27182 | @end itemize | |
64d5610f | 27183 | |
b71d4b62 | 27184 | @geindex AI-0220 (Ada 2012 feature) |
64d5610f | 27185 | |
64d5610f | 27186 | |
b71d4b62 | 27187 | @itemize * |
64d5610f | 27188 | |
b71d4b62 RA |
27189 | @item |
27190 | `AI-0220 Needed components for aggregates (0000-00-00)' | |
64d5610f | 27191 | |
b71d4b62 RA |
27192 | This AI addresses a wording problem in the RM that appears to permit some |
27193 | complex cases of aggregates with nonstatic discriminants. GNAT has always | |
27194 | implemented the intended semantics. | |
64d5610f | 27195 | |
b71d4b62 RA |
27196 | RM References: 4.03.01 (17) |
27197 | @end itemize | |
64d5610f | 27198 | |
b71d4b62 | 27199 | @geindex AI-0147 (Ada 2012 feature) |
64d5610f | 27200 | |
64d5610f | 27201 | |
b71d4b62 | 27202 | @itemize * |
64d5610f | 27203 | |
b71d4b62 RA |
27204 | @item |
27205 | `AI-0147 Conditional expressions (2009-03-29)' | |
64d5610f | 27206 | |
b71d4b62 | 27207 | Conditional expressions are permitted. The form of such an expression is: |
64d5610f | 27208 | |
b71d4b62 RA |
27209 | @example |
27210 | (if expr then expr @{elsif expr then expr@} [else expr]) | |
27211 | @end example | |
64d5610f | 27212 | |
b71d4b62 RA |
27213 | The parentheses can be omitted in contexts where parentheses are present |
27214 | anyway, such as subprogram arguments and pragma arguments. If the `else' | |
27215 | clause is omitted, `else' `True' is assumed; | |
27216 | thus @code{(if A then B)} is a way to conveniently represent | |
27217 | `(A implies B)' in standard logic. | |
64d5610f | 27218 | |
b71d4b62 RA |
27219 | RM References: 4.03.03 (15) 4.04 (1) 4.04 (7) 4.05.07 (0) 4.07 (2) |
27220 | 4.07 (3) 4.09 (12) 4.09 (33) 5.03 (3) 5.03 (4) 7.05 (2.1/2) | |
27221 | @end itemize | |
64d5610f | 27222 | |
b71d4b62 | 27223 | @geindex AI-0037 (Ada 2012 feature) |
64d5610f | 27224 | |
64d5610f | 27225 | |
b71d4b62 | 27226 | @itemize * |
64d5610f | 27227 | |
b71d4b62 RA |
27228 | @item |
27229 | `AI-0037 Out-of-range box associations in aggregate (0000-00-00)' | |
64d5610f | 27230 | |
b71d4b62 RA |
27231 | This AI confirms that an association of the form @code{Indx => <>} in an |
27232 | array aggregate must raise @code{Constraint_Error} if @code{Indx} | |
27233 | is out of range. The RM specified a range check on other associations, but | |
27234 | not when the value of the association was defaulted. GNAT has always inserted | |
27235 | a constraint check on the index value. | |
64d5610f | 27236 | |
b71d4b62 RA |
27237 | RM References: 4.03.03 (29) |
27238 | @end itemize | |
64d5610f | 27239 | |
b71d4b62 | 27240 | @geindex AI-0123 (Ada 2012 feature) |
64d5610f | 27241 | |
64d5610f | 27242 | |
b71d4b62 | 27243 | @itemize * |
64d5610f | 27244 | |
b71d4b62 RA |
27245 | @item |
27246 | `AI-0123 Composability of equality (2010-04-13)' | |
64d5610f | 27247 | |
b71d4b62 RA |
27248 | Equality of untagged record composes, so that the predefined equality for a |
27249 | composite type that includes a component of some untagged record type | |
27250 | @code{R} uses the equality operation of @code{R} (which may be user-defined | |
27251 | or predefined). This makes the behavior of untagged records identical to that | |
27252 | of tagged types in this respect. | |
64d5610f | 27253 | |
b71d4b62 RA |
27254 | This change is an incompatibility with previous versions of Ada, but it |
27255 | corrects a non-uniformity that was often a source of confusion. Analysis of | |
27256 | a large number of industrial programs indicates that in those rare cases | |
27257 | where a composite type had an untagged record component with a user-defined | |
27258 | equality, either there was no use of the composite equality, or else the code | |
27259 | expected the same composability as for tagged types, and thus had a bug that | |
27260 | would be fixed by this change. | |
64d5610f | 27261 | |
b71d4b62 RA |
27262 | RM References: 4.05.02 (9.7/2) 4.05.02 (14) 4.05.02 (15) 4.05.02 (24) |
27263 | 8.05.04 (8) | |
27264 | @end itemize | |
64d5610f | 27265 | |
b71d4b62 | 27266 | @geindex AI-0088 (Ada 2012 feature) |
64d5610f | 27267 | |
64d5610f | 27268 | |
b71d4b62 | 27269 | @itemize * |
64d5610f | 27270 | |
b71d4b62 RA |
27271 | @item |
27272 | `AI-0088 The value of exponentiation (0000-00-00)' | |
64d5610f | 27273 | |
b71d4b62 RA |
27274 | This AI clarifies the equivalence rule given for the dynamic semantics of |
27275 | exponentiation: the value of the operation can be obtained by repeated | |
27276 | multiplication, but the operation can be implemented otherwise (for example | |
27277 | using the familiar divide-by-two-and-square algorithm, even if this is less | |
27278 | accurate), and does not imply repeated reads of a volatile base. | |
64d5610f | 27279 | |
b71d4b62 RA |
27280 | RM References: 4.05.06 (11) |
27281 | @end itemize | |
64d5610f | 27282 | |
b71d4b62 | 27283 | @geindex AI-0188 (Ada 2012 feature) |
64d5610f | 27284 | |
64d5610f | 27285 | |
b71d4b62 | 27286 | @itemize * |
64d5610f | 27287 | |
b71d4b62 RA |
27288 | @item |
27289 | `AI-0188 Case expressions (2010-01-09)' | |
64d5610f | 27290 | |
b71d4b62 | 27291 | Case expressions are permitted. This allows use of constructs such as: |
64d5610f | 27292 | |
b71d4b62 RA |
27293 | @example |
27294 | X := (case Y is when 1 => 2, when 2 => 3, when others => 31) | |
27295 | @end example | |
64d5610f | 27296 | |
b71d4b62 RA |
27297 | RM References: 4.05.07 (0) 4.05.08 (0) 4.09 (12) 4.09 (33) |
27298 | @end itemize | |
64d5610f | 27299 | |
b71d4b62 | 27300 | @geindex AI-0104 (Ada 2012 feature) |
64d5610f ML |
27301 | |
27302 | ||
27303 | @itemize * | |
27304 | ||
27305 | @item | |
b71d4b62 | 27306 | `AI-0104 Null exclusion and uninitialized allocator (2010-07-15)' |
64d5610f | 27307 | |
b71d4b62 RA |
27308 | The assignment @code{Ptr := new not null Some_Ptr;} will raise |
27309 | @code{Constraint_Error} because the default value of the allocated object is | |
27310 | `null'. This useless construct is illegal in Ada 2012. | |
64d5610f | 27311 | |
b71d4b62 | 27312 | RM References: 4.08 (2) |
64d5610f ML |
27313 | @end itemize |
27314 | ||
b71d4b62 | 27315 | @geindex AI-0157 (Ada 2012 feature) |
64d5610f ML |
27316 | |
27317 | ||
27318 | @itemize * | |
27319 | ||
27320 | @item | |
b71d4b62 | 27321 | `AI-0157 Allocation/Deallocation from empty pool (2010-07-11)' |
64d5610f | 27322 | |
b71d4b62 RA |
27323 | Allocation and Deallocation from an empty storage pool (i.e. allocation or |
27324 | deallocation of a pointer for which a static storage size clause of zero | |
27325 | has been given) is now illegal and is detected as such. GNAT | |
27326 | previously gave a warning but not an error. | |
64d5610f | 27327 | |
b71d4b62 | 27328 | RM References: 4.08 (5.3/2) 13.11.02 (4) 13.11.02 (17) |
64d5610f ML |
27329 | @end itemize |
27330 | ||
b71d4b62 | 27331 | @geindex AI-0179 (Ada 2012 feature) |
64d5610f ML |
27332 | |
27333 | ||
27334 | @itemize * | |
27335 | ||
27336 | @item | |
b71d4b62 | 27337 | `AI-0179 Statement not required after label (2010-04-10)' |
64d5610f | 27338 | |
b71d4b62 RA |
27339 | It is not necessary to have a statement following a label, so a label |
27340 | can appear at the end of a statement sequence without the need for putting a | |
27341 | null statement afterwards, but it is not allowable to have only labels and | |
27342 | no real statements in a statement sequence. | |
64d5610f | 27343 | |
b71d4b62 | 27344 | RM References: 5.01 (2) |
64d5610f ML |
27345 | @end itemize |
27346 | ||
b71d4b62 | 27347 | @geindex AI-0139-2 (Ada 2012 feature) |
64d5610f ML |
27348 | |
27349 | ||
27350 | @itemize * | |
27351 | ||
27352 | @item | |
b71d4b62 | 27353 | `AI-0139-2 Syntactic sugar for iterators (2010-09-29)' |
64d5610f | 27354 | |
b71d4b62 RA |
27355 | The new syntax for iterating over arrays and containers is now implemented. |
27356 | Iteration over containers is for now limited to read-only iterators. Only | |
27357 | default iterators are supported, with the syntax: @code{for Elem of C}. | |
64d5610f | 27358 | |
b71d4b62 | 27359 | RM References: 5.05 |
64d5610f ML |
27360 | @end itemize |
27361 | ||
b71d4b62 | 27362 | @geindex AI-0134 (Ada 2012 feature) |
64d5610f ML |
27363 | |
27364 | ||
27365 | @itemize * | |
27366 | ||
27367 | @item | |
b71d4b62 | 27368 | `AI-0134 Profiles must match for full conformance (0000-00-00)' |
64d5610f | 27369 | |
b71d4b62 RA |
27370 | For full conformance, the profiles of anonymous-access-to-subprogram |
27371 | parameters must match. GNAT has always enforced this rule. | |
64d5610f | 27372 | |
b71d4b62 | 27373 | RM References: 6.03.01 (18) |
64d5610f ML |
27374 | @end itemize |
27375 | ||
b71d4b62 | 27376 | @geindex AI-0207 (Ada 2012 feature) |
64d5610f ML |
27377 | |
27378 | ||
27379 | @itemize * | |
27380 | ||
27381 | @item | |
b71d4b62 | 27382 | `AI-0207 Mode conformance and access constant (0000-00-00)' |
64d5610f | 27383 | |
b71d4b62 RA |
27384 | This AI confirms that access_to_constant indication must match for mode |
27385 | conformance. This was implemented in GNAT when the qualifier was originally | |
27386 | introduced in Ada 2005. | |
64d5610f | 27387 | |
b71d4b62 | 27388 | RM References: 6.03.01 (16/2) |
64d5610f ML |
27389 | @end itemize |
27390 | ||
b71d4b62 | 27391 | @geindex AI-0046 (Ada 2012 feature) |
64d5610f ML |
27392 | |
27393 | ||
27394 | @itemize * | |
27395 | ||
27396 | @item | |
b71d4b62 | 27397 | `AI-0046 Null exclusion match for full conformance (2010-07-17)' |
64d5610f | 27398 | |
b71d4b62 RA |
27399 | For full conformance, in the case of access parameters, the null exclusion |
27400 | must match (either both or neither must have @code{not null}). | |
64d5610f | 27401 | |
b71d4b62 | 27402 | RM References: 6.03.02 (18) |
64d5610f ML |
27403 | @end itemize |
27404 | ||
b71d4b62 | 27405 | @geindex AI-0118 (Ada 2012 feature) |
64d5610f ML |
27406 | |
27407 | ||
27408 | @itemize * | |
27409 | ||
27410 | @item | |
b71d4b62 | 27411 | `AI-0118 The association of parameter associations (0000-00-00)' |
64d5610f | 27412 | |
b71d4b62 RA |
27413 | This AI clarifies the rules for named associations in subprogram calls and |
27414 | generic instantiations. The rules have been in place since Ada 83. | |
64d5610f | 27415 | |
b71d4b62 | 27416 | RM References: 6.04.01 (2) 12.03 (9) |
64d5610f ML |
27417 | @end itemize |
27418 | ||
b71d4b62 | 27419 | @geindex AI-0196 (Ada 2012 feature) |
64d5610f ML |
27420 | |
27421 | ||
27422 | @itemize * | |
27423 | ||
27424 | @item | |
b71d4b62 | 27425 | `AI-0196 Null exclusion tests for out parameters (0000-00-00)' |
64d5610f | 27426 | |
b71d4b62 RA |
27427 | Null exclusion checks are not made for @code{out} parameters when |
27428 | evaluating the actual parameters. GNAT has never generated these checks. | |
64d5610f | 27429 | |
b71d4b62 | 27430 | RM References: 6.04.01 (13) |
64d5610f ML |
27431 | @end itemize |
27432 | ||
b71d4b62 | 27433 | @geindex AI-0015 (Ada 2012 feature) |
64d5610f ML |
27434 | |
27435 | ||
27436 | @itemize * | |
27437 | ||
27438 | @item | |
b71d4b62 | 27439 | `AI-0015 Constant return objects (0000-00-00)' |
64d5610f | 27440 | |
b71d4b62 RA |
27441 | The return object declared in an `extended_return_statement' may be |
27442 | declared constant. This was always intended, and GNAT has always allowed it. | |
64d5610f | 27443 | |
b71d4b62 RA |
27444 | RM References: 6.05 (2.1/2) 3.03 (10/2) 3.03 (21) 6.05 (5/2) |
27445 | 6.05 (5.7/2) | |
64d5610f ML |
27446 | @end itemize |
27447 | ||
b71d4b62 | 27448 | @geindex AI-0032 (Ada 2012 feature) |
64d5610f ML |
27449 | |
27450 | ||
27451 | @itemize * | |
27452 | ||
27453 | @item | |
b71d4b62 | 27454 | `AI-0032 Extended return for class-wide functions (0000-00-00)' |
64d5610f | 27455 | |
b71d4b62 RA |
27456 | If a function returns a class-wide type, the object of an extended return |
27457 | statement can be declared with a specific type that is covered by the class- | |
27458 | wide type. This has been implemented in GNAT since the introduction of | |
27459 | extended returns. Note AI-0103 complements this AI by imposing matching | |
27460 | rules for constrained return types. | |
64d5610f | 27461 | |
b71d4b62 RA |
27462 | RM References: 6.05 (5.2/2) 6.05 (5.3/2) 6.05 (5.6/2) 6.05 (5.8/2) |
27463 | 6.05 (8/2) | |
64d5610f ML |
27464 | @end itemize |
27465 | ||
b71d4b62 | 27466 | @geindex AI-0103 (Ada 2012 feature) |
64d5610f ML |
27467 | |
27468 | ||
27469 | @itemize * | |
27470 | ||
27471 | @item | |
b71d4b62 | 27472 | `AI-0103 Static matching for extended return (2010-07-23)' |
64d5610f | 27473 | |
b71d4b62 RA |
27474 | If the return subtype of a function is an elementary type or a constrained |
27475 | type, the subtype indication in an extended return statement must match | |
27476 | statically this return subtype. | |
64d5610f | 27477 | |
b71d4b62 | 27478 | RM References: 6.05 (5.2/2) |
64d5610f ML |
27479 | @end itemize |
27480 | ||
b71d4b62 | 27481 | @geindex AI-0058 (Ada 2012 feature) |
64d5610f ML |
27482 | |
27483 | ||
27484 | @itemize * | |
27485 | ||
27486 | @item | |
b71d4b62 | 27487 | `AI-0058 Abnormal completion of an extended return (0000-00-00)' |
64d5610f | 27488 | |
b71d4b62 RA |
27489 | The RM had some incorrect wording implying wrong treatment of abnormal |
27490 | completion in an extended return. GNAT has always implemented the intended | |
27491 | correct semantics as described by this AI. | |
64d5610f | 27492 | |
b71d4b62 | 27493 | RM References: 6.05 (22/2) |
64d5610f ML |
27494 | @end itemize |
27495 | ||
b71d4b62 | 27496 | @geindex AI-0050 (Ada 2012 feature) |
64d5610f ML |
27497 | |
27498 | ||
27499 | @itemize * | |
27500 | ||
27501 | @item | |
b71d4b62 | 27502 | `AI-0050 Raising Constraint_Error early for function call (0000-00-00)' |
64d5610f | 27503 | |
b71d4b62 RA |
27504 | The implementation permissions for raising @code{Constraint_Error} early on a function call |
27505 | when it was clear an exception would be raised were over-permissive and allowed | |
27506 | mishandling of discriminants in some cases. GNAT did | |
27507 | not take advantage of these incorrect permissions in any case. | |
64d5610f | 27508 | |
b71d4b62 | 27509 | RM References: 6.05 (24/2) |
64d5610f ML |
27510 | @end itemize |
27511 | ||
b71d4b62 | 27512 | @geindex AI-0125 (Ada 2012 feature) |
64d5610f ML |
27513 | |
27514 | ||
27515 | @itemize * | |
27516 | ||
27517 | @item | |
b71d4b62 | 27518 | `AI-0125 Nonoverridable operations of an ancestor (2010-09-28)' |
64d5610f | 27519 | |
b71d4b62 RA |
27520 | In Ada 2012, the declaration of a primitive operation of a type extension |
27521 | or private extension can also override an inherited primitive that is not | |
27522 | visible at the point of this declaration. | |
64d5610f | 27523 | |
b71d4b62 | 27524 | RM References: 7.03.01 (6) 8.03 (23) 8.03.01 (5/2) 8.03.01 (6/2) |
64d5610f ML |
27525 | @end itemize |
27526 | ||
b71d4b62 | 27527 | @geindex AI-0062 (Ada 2012 feature) |
64d5610f ML |
27528 | |
27529 | ||
27530 | @itemize * | |
27531 | ||
27532 | @item | |
b71d4b62 | 27533 | `AI-0062 Null exclusions and deferred constants (0000-00-00)' |
64d5610f | 27534 | |
b71d4b62 RA |
27535 | A full constant may have a null exclusion even if its associated deferred |
27536 | constant does not. GNAT has always allowed this. | |
64d5610f | 27537 | |
b71d4b62 | 27538 | RM References: 7.04 (6/2) 7.04 (7.1/2) |
64d5610f ML |
27539 | @end itemize |
27540 | ||
b71d4b62 | 27541 | @geindex AI-0178 (Ada 2012 feature) |
64d5610f ML |
27542 | |
27543 | ||
27544 | @itemize * | |
27545 | ||
27546 | @item | |
b71d4b62 | 27547 | `AI-0178 Incomplete views are limited (0000-00-00)' |
64d5610f | 27548 | |
b71d4b62 RA |
27549 | This AI clarifies the role of incomplete views and plugs an omission in the |
27550 | RM. GNAT always correctly restricted the use of incomplete views and types. | |
64d5610f | 27551 | |
b71d4b62 | 27552 | RM References: 7.05 (3/2) 7.05 (6/2) |
64d5610f ML |
27553 | @end itemize |
27554 | ||
b71d4b62 | 27555 | @geindex AI-0087 (Ada 2012 feature) |
64d5610f ML |
27556 | |
27557 | ||
27558 | @itemize * | |
27559 | ||
27560 | @item | |
b71d4b62 | 27561 | `AI-0087 Actual for formal nonlimited derived type (2010-07-15)' |
64d5610f | 27562 | |
b71d4b62 RA |
27563 | The actual for a formal nonlimited derived type cannot be limited. In |
27564 | particular, a formal derived type that extends a limited interface but which | |
27565 | is not explicitly limited cannot be instantiated with a limited type. | |
64d5610f | 27566 | |
b71d4b62 | 27567 | RM References: 7.05 (5/2) 12.05.01 (5.1/2) |
64d5610f ML |
27568 | @end itemize |
27569 | ||
b71d4b62 | 27570 | @geindex AI-0099 (Ada 2012 feature) |
64d5610f ML |
27571 | |
27572 | ||
27573 | @itemize * | |
27574 | ||
27575 | @item | |
b71d4b62 | 27576 | `AI-0099 Tag determines whether finalization needed (0000-00-00)' |
64d5610f | 27577 | |
b71d4b62 RA |
27578 | This AI clarifies that ‘needs finalization’ is part of dynamic semantics, |
27579 | and therefore depends on the run-time characteristics of an object (i.e. its | |
27580 | tag) and not on its nominal type. As the AI indicates: “we do not expect | |
27581 | this to affect any implementation’’. | |
64d5610f | 27582 | |
b71d4b62 | 27583 | RM References: 7.06.01 (6) 7.06.01 (7) 7.06.01 (8) 7.06.01 (9/2) |
64d5610f ML |
27584 | @end itemize |
27585 | ||
b71d4b62 | 27586 | @geindex AI-0064 (Ada 2012 feature) |
64d5610f ML |
27587 | |
27588 | ||
27589 | @itemize * | |
27590 | ||
27591 | @item | |
b71d4b62 | 27592 | `AI-0064 Redundant finalization rule (0000-00-00)' |
64d5610f | 27593 | |
b71d4b62 RA |
27594 | This is an editorial change only. The intended behavior is already checked |
27595 | by an existing ACATS test, which GNAT has always executed correctly. | |
64d5610f | 27596 | |
b71d4b62 | 27597 | RM References: 7.06.01 (17.1/1) |
64d5610f ML |
27598 | @end itemize |
27599 | ||
b71d4b62 | 27600 | @geindex AI-0026 (Ada 2012 feature) |
64d5610f ML |
27601 | |
27602 | ||
27603 | @itemize * | |
27604 | ||
27605 | @item | |
b71d4b62 | 27606 | `AI-0026 Missing rules for Unchecked_Union (2010-07-07)' |
64d5610f | 27607 | |
b71d4b62 RA |
27608 | Record representation clauses concerning Unchecked_Union types cannot mention |
27609 | the discriminant of the type. The type of a component declared in the variant | |
27610 | part of an Unchecked_Union cannot be controlled, have controlled components, | |
27611 | nor have protected or task parts. If an Unchecked_Union type is declared | |
27612 | within the body of a generic unit or its descendants, then the type of a | |
27613 | component declared in the variant part cannot be a formal private type or a | |
27614 | formal private extension declared within the same generic unit. | |
64d5610f | 27615 | |
b71d4b62 | 27616 | RM References: 7.06 (9.4/2) B.03.03 (9/2) B.03.03 (10/2) |
64d5610f ML |
27617 | @end itemize |
27618 | ||
b71d4b62 | 27619 | @geindex AI-0205 (Ada 2012 feature) |
64d5610f ML |
27620 | |
27621 | ||
27622 | @itemize * | |
27623 | ||
27624 | @item | |
b71d4b62 | 27625 | `AI-0205 Extended return declares visible name (0000-00-00)' |
64d5610f | 27626 | |
b71d4b62 RA |
27627 | This AI corrects a simple omission in the RM. Return objects have always |
27628 | been visible within an extended return statement. | |
64d5610f | 27629 | |
b71d4b62 | 27630 | RM References: 8.03 (17) |
64d5610f ML |
27631 | @end itemize |
27632 | ||
b71d4b62 | 27633 | @geindex AI-0042 (Ada 2012 feature) |
64d5610f ML |
27634 | |
27635 | ||
27636 | @itemize * | |
27637 | ||
27638 | @item | |
b71d4b62 | 27639 | `AI-0042 Overriding versus implemented-by (0000-00-00)' |
64d5610f | 27640 | |
b71d4b62 RA |
27641 | This AI fixes a wording gap in the RM. An operation of a synchronized |
27642 | interface can be implemented by a protected or task entry, but the abstract | |
27643 | operation is not being overridden in the usual sense, and it must be stated | |
27644 | separately that this implementation is legal. This has always been the case | |
27645 | in GNAT. | |
64d5610f | 27646 | |
b71d4b62 | 27647 | RM References: 9.01 (9.2/2) 9.04 (11.1/2) |
64d5610f ML |
27648 | @end itemize |
27649 | ||
b71d4b62 | 27650 | @geindex AI-0030 (Ada 2012 feature) |
64d5610f ML |
27651 | |
27652 | ||
27653 | @itemize * | |
27654 | ||
27655 | @item | |
b71d4b62 | 27656 | `AI-0030 Requeue on synchronized interfaces (2010-07-19)' |
64d5610f | 27657 | |
b71d4b62 RA |
27658 | Requeue is permitted to a protected, synchronized or task interface primitive |
27659 | providing it is known that the overriding operation is an entry. Otherwise | |
27660 | the requeue statement has the same effect as a procedure call. Use of pragma | |
27661 | @code{Implemented} provides a way to impose a static requirement on the | |
27662 | overriding operation by adhering to one of the implementation kinds: entry, | |
27663 | protected procedure or any of the above. | |
64d5610f | 27664 | |
b71d4b62 RA |
27665 | RM References: 9.05 (9) 9.05.04 (2) 9.05.04 (3) 9.05.04 (5) |
27666 | 9.05.04 (6) 9.05.04 (7) 9.05.04 (12) | |
64d5610f ML |
27667 | @end itemize |
27668 | ||
b71d4b62 | 27669 | @geindex AI-0201 (Ada 2012 feature) |
64d5610f ML |
27670 | |
27671 | ||
27672 | @itemize * | |
27673 | ||
27674 | @item | |
b71d4b62 | 27675 | `AI-0201 Independence of atomic object components (2010-07-22)' |
64d5610f | 27676 | |
b71d4b62 RA |
27677 | If an Atomic object has a pragma @code{Pack} or a @code{Component_Size} |
27678 | attribute, then individual components may not be addressable by independent | |
27679 | tasks. However, if the representation clause has no effect (is confirming), | |
27680 | then independence is not compromised. Furthermore, in GNAT, specification of | |
27681 | other appropriately addressable component sizes (e.g. 16 for 8-bit | |
27682 | characters) also preserves independence. GNAT now gives very clear warnings | |
27683 | both for the declaration of such a type, and for any assignment to its components. | |
64d5610f | 27684 | |
b71d4b62 | 27685 | RM References: 9.10 (1/3) C.06 (22/2) C.06 (23/2) |
64d5610f ML |
27686 | @end itemize |
27687 | ||
b71d4b62 | 27688 | @geindex AI-0009 (Ada 2012 feature) |
64d5610f ML |
27689 | |
27690 | ||
27691 | @itemize * | |
27692 | ||
27693 | @item | |
b71d4b62 | 27694 | `AI-0009 Pragma Independent[_Components] (2010-07-23)' |
64d5610f | 27695 | |
b71d4b62 RA |
27696 | This AI introduces the new pragmas @code{Independent} and |
27697 | @code{Independent_Components}, | |
27698 | which control guaranteeing independence of access to objects and components. | |
27699 | The AI also requires independence not unaffected by confirming rep clauses. | |
64d5610f | 27700 | |
b71d4b62 RA |
27701 | RM References: 9.10 (1) 13.01 (15/1) 13.02 (9) 13.03 (13) C.06 (2) |
27702 | C.06 (4) C.06 (6) C.06 (9) C.06 (13) C.06 (14) | |
64d5610f ML |
27703 | @end itemize |
27704 | ||
b71d4b62 | 27705 | @geindex AI-0072 (Ada 2012 feature) |
64d5610f ML |
27706 | |
27707 | ||
27708 | @itemize * | |
27709 | ||
27710 | @item | |
b71d4b62 | 27711 | `AI-0072 Task signalling using ‘Terminated (0000-00-00)' |
64d5610f | 27712 | |
b71d4b62 RA |
27713 | This AI clarifies that task signalling for reading @code{'Terminated} only |
27714 | occurs if the result is True. GNAT semantics has always been consistent with | |
27715 | this notion of task signalling. | |
64d5610f | 27716 | |
b71d4b62 | 27717 | RM References: 9.10 (6.1/1) |
64d5610f ML |
27718 | @end itemize |
27719 | ||
b71d4b62 | 27720 | @geindex AI-0108 (Ada 2012 feature) |
64d5610f ML |
27721 | |
27722 | ||
27723 | @itemize * | |
27724 | ||
27725 | @item | |
b71d4b62 | 27726 | `AI-0108 Limited incomplete view and discriminants (0000-00-00)' |
64d5610f | 27727 | |
b71d4b62 RA |
27728 | This AI confirms that an incomplete type from a limited view does not have |
27729 | discriminants. This has always been the case in GNAT. | |
64d5610f | 27730 | |
b71d4b62 | 27731 | RM References: 10.01.01 (12.3/2) |
64d5610f ML |
27732 | @end itemize |
27733 | ||
b71d4b62 | 27734 | @geindex AI-0129 (Ada 2012 feature) |
64d5610f ML |
27735 | |
27736 | ||
27737 | @itemize * | |
27738 | ||
27739 | @item | |
b71d4b62 | 27740 | `AI-0129 Limited views and incomplete types (0000-00-00)' |
64d5610f | 27741 | |
b71d4b62 RA |
27742 | This AI clarifies the description of limited views: a limited view of a |
27743 | package includes only one view of a type that has an incomplete declaration | |
27744 | and a full declaration (there is no possible ambiguity in a client package). | |
27745 | This AI also fixes an omission: a nested package in the private part has no | |
27746 | limited view. GNAT always implemented this correctly. | |
64d5610f | 27747 | |
b71d4b62 | 27748 | RM References: 10.01.01 (12.2/2) 10.01.01 (12.3/2) |
64d5610f ML |
27749 | @end itemize |
27750 | ||
b71d4b62 | 27751 | @geindex AI-0077 (Ada 2012 feature) |
64d5610f ML |
27752 | |
27753 | ||
27754 | @itemize * | |
27755 | ||
27756 | @item | |
b71d4b62 | 27757 | `AI-0077 Limited withs and scope of declarations (0000-00-00)' |
64d5610f | 27758 | |
b71d4b62 RA |
27759 | This AI clarifies that a declaration does not include a context clause, |
27760 | and confirms that it is illegal to have a context in which both a limited | |
27761 | and a nonlimited view of a package are accessible. Such double visibility | |
27762 | was always rejected by GNAT. | |
64d5610f | 27763 | |
b71d4b62 | 27764 | RM References: 10.01.02 (12/2) 10.01.02 (21/2) 10.01.02 (22/2) |
64d5610f ML |
27765 | @end itemize |
27766 | ||
b71d4b62 | 27767 | @geindex AI-0122 (Ada 2012 feature) |
64d5610f ML |
27768 | |
27769 | ||
27770 | @itemize * | |
27771 | ||
27772 | @item | |
b71d4b62 | 27773 | `AI-0122 Private with and children of generics (0000-00-00)' |
64d5610f | 27774 | |
b71d4b62 RA |
27775 | This AI clarifies the visibility of private children of generic units within |
27776 | instantiations of a parent. GNAT has always handled this correctly. | |
64d5610f | 27777 | |
b71d4b62 | 27778 | RM References: 10.01.02 (12/2) |
64d5610f ML |
27779 | @end itemize |
27780 | ||
b71d4b62 | 27781 | @geindex AI-0040 (Ada 2012 feature) |
64d5610f ML |
27782 | |
27783 | ||
27784 | @itemize * | |
27785 | ||
27786 | @item | |
b71d4b62 | 27787 | `AI-0040 Limited with clauses on descendant (0000-00-00)' |
64d5610f | 27788 | |
b71d4b62 RA |
27789 | This AI confirms that a limited with clause in a child unit cannot name |
27790 | an ancestor of the unit. This has always been checked in GNAT. | |
64d5610f | 27791 | |
b71d4b62 | 27792 | RM References: 10.01.02 (20/2) |
64d5610f ML |
27793 | @end itemize |
27794 | ||
b71d4b62 | 27795 | @geindex AI-0132 (Ada 2012 feature) |
64d5610f ML |
27796 | |
27797 | ||
27798 | @itemize * | |
27799 | ||
27800 | @item | |
b71d4b62 | 27801 | `AI-0132 Placement of library unit pragmas (0000-00-00)' |
64d5610f | 27802 | |
b71d4b62 RA |
27803 | This AI fills a gap in the description of library unit pragmas. The pragma |
27804 | clearly must apply to a library unit, even if it does not carry the name | |
27805 | of the enclosing unit. GNAT has always enforced the required check. | |
64d5610f | 27806 | |
b71d4b62 | 27807 | RM References: 10.01.05 (7) |
64d5610f ML |
27808 | @end itemize |
27809 | ||
b71d4b62 | 27810 | @geindex AI-0034 (Ada 2012 feature) |
64d5610f ML |
27811 | |
27812 | ||
27813 | @itemize * | |
27814 | ||
27815 | @item | |
b71d4b62 | 27816 | `AI-0034 Categorization of limited views (0000-00-00)' |
64d5610f | 27817 | |
b71d4b62 RA |
27818 | The RM makes certain limited with clauses illegal because of categorization |
27819 | considerations, when the corresponding normal with would be legal. This is | |
27820 | not intended, and GNAT has always implemented the recommended behavior. | |
64d5610f | 27821 | |
b71d4b62 | 27822 | RM References: 10.02.01 (11/1) 10.02.01 (17/2) |
64d5610f ML |
27823 | @end itemize |
27824 | ||
b71d4b62 | 27825 | @geindex AI-0035 (Ada 2012 feature) |
64d5610f ML |
27826 | |
27827 | ||
27828 | @itemize * | |
27829 | ||
27830 | @item | |
b71d4b62 | 27831 | `AI-0035 Inconsistencies with Pure units (0000-00-00)' |
64d5610f | 27832 | |
b71d4b62 RA |
27833 | This AI remedies some inconsistencies in the legality rules for Pure units. |
27834 | Derived access types are legal in a pure unit (on the assumption that the | |
27835 | rule for a zero storage pool size has been enforced on the ancestor type). | |
27836 | The rules are enforced in generic instances and in subunits. GNAT has always | |
27837 | implemented the recommended behavior. | |
64d5610f | 27838 | |
b71d4b62 | 27839 | 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 |
27840 | @end itemize |
27841 | ||
b71d4b62 | 27842 | @geindex AI-0219 (Ada 2012 feature) |
64d5610f ML |
27843 | |
27844 | ||
27845 | @itemize * | |
27846 | ||
27847 | @item | |
b71d4b62 | 27848 | `AI-0219 Pure permissions and limited parameters (2010-05-25)' |
64d5610f | 27849 | |
b71d4b62 RA |
27850 | This AI refines the rules for the cases with limited parameters which do not |
27851 | allow the implementations to omit ‘redundant’. GNAT now properly conforms | |
27852 | to the requirements of this binding interpretation. | |
64d5610f | 27853 | |
b71d4b62 | 27854 | RM References: 10.02.01 (18/2) |
64d5610f ML |
27855 | @end itemize |
27856 | ||
b71d4b62 | 27857 | @geindex AI-0043 (Ada 2012 feature) |
64d5610f ML |
27858 | |
27859 | ||
27860 | @itemize * | |
27861 | ||
27862 | @item | |
b71d4b62 | 27863 | `AI-0043 Rules about raising exceptions (0000-00-00)' |
64d5610f | 27864 | |
b71d4b62 RA |
27865 | This AI covers various omissions in the RM regarding the raising of |
27866 | exceptions. GNAT has always implemented the intended semantics. | |
64d5610f | 27867 | |
b71d4b62 | 27868 | RM References: 11.04.01 (10.1/2) 11 (2) |
64d5610f ML |
27869 | @end itemize |
27870 | ||
b71d4b62 | 27871 | @geindex AI-0200 (Ada 2012 feature) |
64d5610f ML |
27872 | |
27873 | ||
27874 | @itemize * | |
27875 | ||
27876 | @item | |
b71d4b62 | 27877 | `AI-0200 Mismatches in formal package declarations (0000-00-00)' |
64d5610f | 27878 | |
b71d4b62 RA |
27879 | This AI plugs a gap in the RM which appeared to allow some obviously intended |
27880 | illegal instantiations. GNAT has never allowed these instantiations. | |
64d5610f | 27881 | |
b71d4b62 | 27882 | RM References: 12.07 (16) |
64d5610f ML |
27883 | @end itemize |
27884 | ||
b71d4b62 | 27885 | @geindex AI-0112 (Ada 2012 feature) |
64d5610f ML |
27886 | |
27887 | ||
27888 | @itemize * | |
27889 | ||
27890 | @item | |
b71d4b62 | 27891 | `AI-0112 Detection of duplicate pragmas (2010-07-24)' |
64d5610f | 27892 | |
b71d4b62 RA |
27893 | This AI concerns giving names to various representation aspects, but the |
27894 | practical effect is simply to make the use of duplicate | |
27895 | @code{Atomic[_Components]}, | |
27896 | @code{Volatile[_Components]}, and | |
27897 | @code{Independent[_Components]} pragmas illegal, and GNAT | |
27898 | now performs this required check. | |
64d5610f | 27899 | |
b71d4b62 | 27900 | RM References: 13.01 (8) |
64d5610f ML |
27901 | @end itemize |
27902 | ||
b71d4b62 | 27903 | @geindex AI-0106 (Ada 2012 feature) |
64d5610f ML |
27904 | |
27905 | ||
27906 | @itemize * | |
27907 | ||
27908 | @item | |
b71d4b62 | 27909 | `AI-0106 No representation pragmas on generic formals (0000-00-00)' |
64d5610f | 27910 | |
b71d4b62 RA |
27911 | The RM appeared to allow representation pragmas on generic formal parameters, |
27912 | but this was not intended, and GNAT has never permitted this usage. | |
64d5610f | 27913 | |
b71d4b62 | 27914 | RM References: 13.01 (9.1/1) |
64d5610f ML |
27915 | @end itemize |
27916 | ||
b71d4b62 | 27917 | @geindex AI-0012 (Ada 2012 feature) |
64d5610f ML |
27918 | |
27919 | ||
27920 | @itemize * | |
27921 | ||
27922 | @item | |
b71d4b62 | 27923 | `AI-0012 Pack/Component_Size for aliased/atomic (2010-07-15)' |
64d5610f | 27924 | |
b71d4b62 RA |
27925 | It is now illegal to give an inappropriate component size or a pragma |
27926 | @code{Pack} that attempts to change the component size in the case of atomic | |
27927 | or aliased components. Previously GNAT ignored such an attempt with a | |
27928 | warning. | |
64d5610f | 27929 | |
b71d4b62 | 27930 | RM References: 13.02 (6.1/2) 13.02 (7) C.06 (10) C.06 (11) C.06 (21) |
64d5610f ML |
27931 | @end itemize |
27932 | ||
b71d4b62 | 27933 | @geindex AI-0039 (Ada 2012 feature) |
64d5610f ML |
27934 | |
27935 | ||
27936 | @itemize * | |
27937 | ||
27938 | @item | |
b71d4b62 | 27939 | `AI-0039 Stream attributes cannot be dynamic (0000-00-00)' |
64d5610f | 27940 | |
b71d4b62 RA |
27941 | The RM permitted the use of dynamic expressions (such as @code{ptr.all})` |
27942 | for stream attributes, but these were never useful and are now illegal. GNAT | |
27943 | has always regarded such expressions as illegal. | |
64d5610f | 27944 | |
b71d4b62 | 27945 | RM References: 13.03 (4) 13.03 (6) 13.13.02 (38/2) |
64d5610f ML |
27946 | @end itemize |
27947 | ||
b71d4b62 | 27948 | @geindex AI-0095 (Ada 2012 feature) |
64d5610f ML |
27949 | |
27950 | ||
27951 | @itemize * | |
27952 | ||
27953 | @item | |
b71d4b62 | 27954 | `AI-0095 Address of intrinsic subprograms (0000-00-00)' |
64d5610f | 27955 | |
b71d4b62 RA |
27956 | The prefix of @code{'Address} cannot statically denote a subprogram with |
27957 | convention @code{Intrinsic}. The use of the @code{Address} attribute raises | |
27958 | @code{Program_Error} if the prefix denotes a subprogram with convention | |
27959 | @code{Intrinsic}. | |
64d5610f | 27960 | |
b71d4b62 | 27961 | RM References: 13.03 (11/1) |
64d5610f ML |
27962 | @end itemize |
27963 | ||
b71d4b62 | 27964 | @geindex AI-0116 (Ada 2012 feature) |
64d5610f ML |
27965 | |
27966 | ||
27967 | @itemize * | |
27968 | ||
27969 | @item | |
b71d4b62 | 27970 | `AI-0116 Alignment of class-wide objects (0000-00-00)' |
64d5610f | 27971 | |
b71d4b62 RA |
27972 | This AI requires that the alignment of a class-wide object be no greater |
27973 | than the alignment of any type in the class. GNAT has always followed this | |
27974 | recommendation. | |
64d5610f | 27975 | |
b71d4b62 | 27976 | RM References: 13.03 (29) 13.11 (16) |
64d5610f ML |
27977 | @end itemize |
27978 | ||
b71d4b62 | 27979 | @geindex AI-0146 (Ada 2012 feature) |
64d5610f ML |
27980 | |
27981 | ||
27982 | @itemize * | |
27983 | ||
27984 | @item | |
b71d4b62 | 27985 | `AI-0146 Type invariants (2009-09-21)' |
64d5610f | 27986 | |
b71d4b62 RA |
27987 | Type invariants may be specified for private types using the aspect notation. |
27988 | Aspect @code{Type_Invariant} may be specified for any private type, | |
27989 | @code{Type_Invariant'Class} can | |
27990 | only be specified for tagged types, and is inherited by any descendent of the | |
27991 | tagged types. The invariant is a boolean expression that is tested for being | |
27992 | true in the following situations: conversions to the private type, object | |
27993 | declarations for the private type that are default initialized, and | |
27994 | [`in'] `out' | |
27995 | parameters and returned result on return from any primitive operation for | |
27996 | the type that is visible to a client. | |
27997 | GNAT defines the synonyms @code{Invariant} for @code{Type_Invariant} and | |
27998 | @code{Invariant'Class} for @code{Type_Invariant'Class}. | |
64d5610f | 27999 | |
b71d4b62 | 28000 | RM References: 13.03.03 (00) |
64d5610f ML |
28001 | @end itemize |
28002 | ||
b71d4b62 | 28003 | @geindex AI-0078 (Ada 2012 feature) |
64d5610f ML |
28004 | |
28005 | ||
28006 | @itemize * | |
28007 | ||
28008 | @item | |
b71d4b62 | 28009 | `AI-0078 Relax Unchecked_Conversion alignment rules (0000-00-00)' |
64d5610f | 28010 | |
b71d4b62 RA |
28011 | In Ada 2012, compilers are required to support unchecked conversion where the |
28012 | target alignment is a multiple of the source alignment. GNAT always supported | |
28013 | this case (and indeed all cases of differing alignments, doing copies where | |
28014 | required if the alignment was reduced). | |
64d5610f | 28015 | |
b71d4b62 | 28016 | RM References: 13.09 (7) |
64d5610f ML |
28017 | @end itemize |
28018 | ||
b71d4b62 | 28019 | @geindex AI-0195 (Ada 2012 feature) |
64d5610f ML |
28020 | |
28021 | ||
28022 | @itemize * | |
28023 | ||
28024 | @item | |
b71d4b62 | 28025 | `AI-0195 Invalid value handling is implementation defined (2010-07-03)' |
64d5610f | 28026 | |
b71d4b62 RA |
28027 | The handling of invalid values is now designated to be implementation |
28028 | defined. This is a documentation change only, requiring Annex M in the GNAT | |
28029 | Reference Manual to document this handling. | |
28030 | In GNAT, checks for invalid values are made | |
28031 | only when necessary to avoid erroneous behavior. Operations like assignments | |
28032 | which cannot cause erroneous behavior ignore the possibility of invalid | |
28033 | values and do not do a check. The date given above applies only to the | |
28034 | documentation change, this behavior has always been implemented by GNAT. | |
64d5610f | 28035 | |
b71d4b62 | 28036 | RM References: 13.09.01 (10) |
64d5610f ML |
28037 | @end itemize |
28038 | ||
b71d4b62 | 28039 | @geindex AI-0193 (Ada 2012 feature) |
64d5610f ML |
28040 | |
28041 | ||
28042 | @itemize * | |
28043 | ||
28044 | @item | |
b71d4b62 | 28045 | `AI-0193 Alignment of allocators (2010-09-16)' |
64d5610f | 28046 | |
b71d4b62 RA |
28047 | This AI introduces a new attribute @code{Max_Alignment_For_Allocation}, |
28048 | analogous to @code{Max_Size_In_Storage_Elements}, but for alignment instead | |
28049 | of size. | |
64d5610f | 28050 | |
b71d4b62 RA |
28051 | RM References: 13.11 (16) 13.11 (21) 13.11.01 (0) 13.11.01 (1) |
28052 | 13.11.01 (2) 13.11.01 (3) | |
64d5610f ML |
28053 | @end itemize |
28054 | ||
b71d4b62 | 28055 | @geindex AI-0177 (Ada 2012 feature) |
64d5610f ML |
28056 | |
28057 | ||
28058 | @itemize * | |
28059 | ||
28060 | @item | |
b71d4b62 | 28061 | `AI-0177 Parameterized expressions (2010-07-10)' |
64d5610f | 28062 | |
b71d4b62 RA |
28063 | The new Ada 2012 notion of parameterized expressions is implemented. The form |
28064 | is: | |
64d5610f | 28065 | |
b71d4b62 RA |
28066 | @example |
28067 | function-specification is (expression) | |
28068 | @end example | |
28069 | ||
28070 | This is exactly equivalent to the | |
28071 | corresponding function body that returns the expression, but it can appear | |
28072 | in a package spec. Note that the expression must be parenthesized. | |
28073 | ||
28074 | RM References: 13.11.01 (3/2) | |
64d5610f ML |
28075 | @end itemize |
28076 | ||
b71d4b62 | 28077 | @geindex AI-0033 (Ada 2012 feature) |
64d5610f ML |
28078 | |
28079 | ||
28080 | @itemize * | |
28081 | ||
28082 | @item | |
b71d4b62 | 28083 | `AI-0033 Attach/Interrupt_Handler in generic (2010-07-24)' |
64d5610f | 28084 | |
b71d4b62 RA |
28085 | Neither of these two pragmas may appear within a generic template, because |
28086 | the generic might be instantiated at other than the library level. | |
64d5610f | 28087 | |
b71d4b62 | 28088 | RM References: 13.11.02 (16) C.03.01 (7/2) C.03.01 (8/2) |
64d5610f ML |
28089 | @end itemize |
28090 | ||
b71d4b62 | 28091 | @geindex AI-0161 (Ada 2012 feature) |
64d5610f ML |
28092 | |
28093 | ||
28094 | @itemize * | |
28095 | ||
28096 | @item | |
b71d4b62 | 28097 | `AI-0161 Restriction No_Default_Stream_Attributes (2010-09-11)' |
64d5610f | 28098 | |
b71d4b62 RA |
28099 | A new restriction @code{No_Default_Stream_Attributes} prevents the use of any |
28100 | of the default stream attributes for elementary types. If this restriction is | |
28101 | in force, then it is necessary to provide explicit subprograms for any | |
28102 | stream attributes used. | |
64d5610f | 28103 | |
b71d4b62 | 28104 | RM References: 13.12.01 (4/2) 13.13.02 (40/2) 13.13.02 (52/2) |
64d5610f ML |
28105 | @end itemize |
28106 | ||
b71d4b62 | 28107 | @geindex AI-0194 (Ada 2012 feature) |
64d5610f ML |
28108 | |
28109 | ||
28110 | @itemize * | |
28111 | ||
28112 | @item | |
b71d4b62 | 28113 | `AI-0194 Value of Stream_Size attribute (0000-00-00)' |
64d5610f | 28114 | |
b71d4b62 RA |
28115 | The @code{Stream_Size} attribute returns the default number of bits in the |
28116 | stream representation of the given type. | |
28117 | This value is not affected by the presence | |
28118 | of stream subprogram attributes for the type. GNAT has always implemented | |
28119 | this interpretation. | |
64d5610f | 28120 | |
b71d4b62 | 28121 | RM References: 13.13.02 (1.2/2) |
64d5610f ML |
28122 | @end itemize |
28123 | ||
b71d4b62 | 28124 | @geindex AI-0109 (Ada 2012 feature) |
64d5610f ML |
28125 | |
28126 | ||
28127 | @itemize * | |
28128 | ||
28129 | @item | |
b71d4b62 | 28130 | `AI-0109 Redundant check in S’Class’Input (0000-00-00)' |
64d5610f | 28131 | |
b71d4b62 RA |
28132 | This AI is an editorial change only. It removes the need for a tag check |
28133 | that can never fail. | |
64d5610f | 28134 | |
b71d4b62 | 28135 | RM References: 13.13.02 (34/2) |
64d5610f ML |
28136 | @end itemize |
28137 | ||
b71d4b62 | 28138 | @geindex AI-0007 (Ada 2012 feature) |
64d5610f ML |
28139 | |
28140 | ||
28141 | @itemize * | |
28142 | ||
28143 | @item | |
b71d4b62 | 28144 | `AI-0007 Stream read and private scalar types (0000-00-00)' |
64d5610f | 28145 | |
b71d4b62 RA |
28146 | The RM as written appeared to limit the possibilities of declaring read |
28147 | attribute procedures for private scalar types. This limitation was not | |
28148 | intended, and has never been enforced by GNAT. | |
64d5610f | 28149 | |
b71d4b62 | 28150 | RM References: 13.13.02 (50/2) 13.13.02 (51/2) |
64d5610f ML |
28151 | @end itemize |
28152 | ||
b71d4b62 | 28153 | @geindex AI-0065 (Ada 2012 feature) |
64d5610f ML |
28154 | |
28155 | ||
28156 | @itemize * | |
28157 | ||
28158 | @item | |
b71d4b62 | 28159 | `AI-0065 Remote access types and external streaming (0000-00-00)' |
64d5610f | 28160 | |
b71d4b62 RA |
28161 | This AI clarifies the fact that all remote access types support external |
28162 | streaming. This fixes an obvious oversight in the definition of the | |
28163 | language, and GNAT always implemented the intended correct rules. | |
64d5610f | 28164 | |
b71d4b62 | 28165 | RM References: 13.13.02 (52/2) |
64d5610f ML |
28166 | @end itemize |
28167 | ||
b71d4b62 | 28168 | @geindex AI-0019 (Ada 2012 feature) |
64d5610f ML |
28169 | |
28170 | ||
28171 | @itemize * | |
28172 | ||
28173 | @item | |
b71d4b62 | 28174 | `AI-0019 Freezing of primitives for tagged types (0000-00-00)' |
64d5610f | 28175 | |
b71d4b62 RA |
28176 | The RM suggests that primitive subprograms of a specific tagged type are |
28177 | frozen when the tagged type is frozen. This would be an incompatible change | |
28178 | and is not intended. GNAT has never attempted this kind of freezing and its | |
28179 | behavior is consistent with the recommendation of this AI. | |
64d5610f | 28180 | |
b71d4b62 | 28181 | 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 |
28182 | @end itemize |
28183 | ||
b71d4b62 | 28184 | @geindex AI-0017 (Ada 2012 feature) |
64d5610f ML |
28185 | |
28186 | ||
28187 | @itemize * | |
28188 | ||
28189 | @item | |
b71d4b62 | 28190 | `AI-0017 Freezing and incomplete types (0000-00-00)' |
64d5610f | 28191 | |
b71d4b62 RA |
28192 | So-called ‘Taft-amendment types’ (i.e., types that are completed in package |
28193 | bodies) are not frozen by the occurrence of bodies in the | |
28194 | enclosing declarative part. GNAT always implemented this properly. | |
64d5610f | 28195 | |
b71d4b62 | 28196 | RM References: 13.14 (3/1) |
64d5610f ML |
28197 | @end itemize |
28198 | ||
b71d4b62 | 28199 | @geindex AI-0060 (Ada 2012 feature) |
64d5610f ML |
28200 | |
28201 | ||
28202 | @itemize * | |
28203 | ||
28204 | @item | |
b71d4b62 | 28205 | `AI-0060 Extended definition of remote access types (0000-00-00)' |
64d5610f | 28206 | |
b71d4b62 RA |
28207 | This AI extends the definition of remote access types to include access |
28208 | to limited, synchronized, protected or task class-wide interface types. | |
28209 | GNAT already implemented this extension. | |
64d5610f | 28210 | |
b71d4b62 | 28211 | 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 |
28212 | @end itemize |
28213 | ||
b71d4b62 | 28214 | @geindex AI-0114 (Ada 2012 feature) |
64d5610f ML |
28215 | |
28216 | ||
28217 | @itemize * | |
28218 | ||
28219 | @item | |
b71d4b62 | 28220 | `AI-0114 Classification of letters (0000-00-00)' |
64d5610f | 28221 | |
b71d4b62 RA |
28222 | The code points 170 (@code{FEMININE ORDINAL INDICATOR}), |
28223 | 181 (@code{MICRO SIGN}), and | |
28224 | 186 (@code{MASCULINE ORDINAL INDICATOR}) are technically considered | |
28225 | lower case letters by Unicode. | |
28226 | However, they are not allowed in identifiers, and they | |
28227 | return @code{False} to @code{Ada.Characters.Handling.Is_Letter/Is_Lower}. | |
28228 | This behavior is consistent with that defined in Ada 95. | |
64d5610f | 28229 | |
b71d4b62 | 28230 | RM References: A.03.02 (59) A.04.06 (7) |
64d5610f ML |
28231 | @end itemize |
28232 | ||
b71d4b62 | 28233 | @geindex AI-0185 (Ada 2012 feature) |
64d5610f ML |
28234 | |
28235 | ||
28236 | @itemize * | |
28237 | ||
28238 | @item | |
b71d4b62 | 28239 | `AI-0185 Ada.Wide_[Wide_]Characters.Handling (2010-07-06)' |
64d5610f | 28240 | |
b71d4b62 RA |
28241 | Two new packages @code{Ada.Wide_[Wide_]Characters.Handling} provide |
28242 | classification functions for @code{Wide_Character} and | |
28243 | @code{Wide_Wide_Character}, as well as providing | |
28244 | case folding routines for @code{Wide_[Wide_]Character} and | |
28245 | @code{Wide_[Wide_]String}. | |
64d5610f | 28246 | |
b71d4b62 | 28247 | RM References: A.03.05 (0) A.03.06 (0) |
64d5610f ML |
28248 | @end itemize |
28249 | ||
b71d4b62 | 28250 | @geindex AI-0031 (Ada 2012 feature) |
64d5610f ML |
28251 | |
28252 | ||
28253 | @itemize * | |
28254 | ||
28255 | @item | |
b71d4b62 | 28256 | `AI-0031 Add From parameter to Find_Token (2010-07-25)' |
64d5610f | 28257 | |
b71d4b62 RA |
28258 | A new version of @code{Find_Token} is added to all relevant string packages, |
28259 | with an extra parameter @code{From}. Instead of starting at the first | |
28260 | character of the string, the search for a matching Token starts at the | |
28261 | character indexed by the value of @code{From}. | |
28262 | These procedures are available in all versions of Ada | |
28263 | but if used in versions earlier than Ada 2012 they will generate a warning | |
28264 | that an Ada 2012 subprogram is being used. | |
64d5610f | 28265 | |
b71d4b62 RA |
28266 | RM References: A.04.03 (16) A.04.03 (67) A.04.03 (68/1) A.04.04 (51) |
28267 | A.04.05 (46) | |
64d5610f ML |
28268 | @end itemize |
28269 | ||
b71d4b62 | 28270 | @geindex AI-0056 (Ada 2012 feature) |
64d5610f ML |
28271 | |
28272 | ||
28273 | @itemize * | |
28274 | ||
28275 | @item | |
b71d4b62 | 28276 | `AI-0056 Index on null string returns zero (0000-00-00)' |
64d5610f | 28277 | |
b71d4b62 RA |
28278 | The wording in the Ada 2005 RM implied an incompatible handling of the |
28279 | @code{Index} functions, resulting in raising an exception instead of | |
28280 | returning zero in some situations. | |
28281 | This was not intended and has been corrected. | |
28282 | GNAT always returned zero, and is thus consistent with this AI. | |
64d5610f | 28283 | |
b71d4b62 | 28284 | RM References: A.04.03 (56.2/2) A.04.03 (58.5/2) |
64d5610f ML |
28285 | @end itemize |
28286 | ||
b71d4b62 | 28287 | @geindex AI-0137 (Ada 2012 feature) |
64d5610f ML |
28288 | |
28289 | ||
28290 | @itemize * | |
28291 | ||
28292 | @item | |
b71d4b62 | 28293 | `AI-0137 String encoding package (2010-03-25)' |
64d5610f | 28294 | |
b71d4b62 RA |
28295 | The packages @code{Ada.Strings.UTF_Encoding}, together with its child |
28296 | packages, @code{Conversions}, @code{Strings}, @code{Wide_Strings}, | |
28297 | and @code{Wide_Wide_Strings} have been | |
28298 | implemented. These packages (whose documentation can be found in the spec | |
28299 | files @code{a-stuten.ads}, @code{a-suenco.ads}, @code{a-suenst.ads}, | |
28300 | @code{a-suewst.ads}, @code{a-suezst.ads}) allow encoding and decoding of | |
28301 | @code{String}, @code{Wide_String}, and @code{Wide_Wide_String} | |
28302 | values using UTF coding schemes (including UTF-8, UTF-16LE, UTF-16BE, and | |
28303 | UTF-16), as well as conversions between the different UTF encodings. With | |
28304 | the exception of @code{Wide_Wide_Strings}, these packages are available in | |
28305 | Ada 95 and Ada 2005 mode as well as Ada 2012 mode. | |
28306 | The @code{Wide_Wide_Strings} package | |
28307 | is available in Ada 2005 mode as well as Ada 2012 mode (but not in Ada 95 | |
28308 | mode since it uses @code{Wide_Wide_Character}). | |
64d5610f | 28309 | |
b71d4b62 | 28310 | RM References: A.04.11 |
64d5610f ML |
28311 | @end itemize |
28312 | ||
b71d4b62 | 28313 | @geindex AI-0038 (Ada 2012 feature) |
64d5610f ML |
28314 | |
28315 | ||
28316 | @itemize * | |
28317 | ||
28318 | @item | |
b71d4b62 | 28319 | `AI-0038 Minor errors in Text_IO (0000-00-00)' |
64d5610f | 28320 | |
b71d4b62 RA |
28321 | These are minor errors in the description on three points. The intent on |
28322 | all these points has always been clear, and GNAT has always implemented the | |
28323 | correct intended semantics. | |
64d5610f | 28324 | |
b71d4b62 | 28325 | 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 |
28326 | @end itemize |
28327 | ||
b71d4b62 | 28328 | @geindex AI-0044 (Ada 2012 feature) |
64d5610f ML |
28329 | |
28330 | ||
28331 | @itemize * | |
28332 | ||
28333 | @item | |
b71d4b62 | 28334 | `AI-0044 Restrictions on container instantiations (0000-00-00)' |
64d5610f | 28335 | |
b71d4b62 RA |
28336 | This AI places restrictions on allowed instantiations of generic containers. |
28337 | These restrictions are not checked by the compiler, so there is nothing to | |
28338 | change in the implementation. This affects only the RM documentation. | |
64d5610f | 28339 | |
b71d4b62 | 28340 | 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 |
28341 | @end itemize |
28342 | ||
b71d4b62 | 28343 | @geindex AI-0127 (Ada 2012 feature) |
64d5610f ML |
28344 | |
28345 | ||
28346 | @itemize * | |
28347 | ||
28348 | @item | |
b71d4b62 | 28349 | `AI-0127 Adding Locale Capabilities (2010-09-29)' |
64d5610f | 28350 | |
b71d4b62 | 28351 | This package provides an interface for identifying the current locale. |
64d5610f | 28352 | |
b71d4b62 RA |
28353 | RM References: A.19 A.19.01 A.19.02 A.19.03 A.19.05 A.19.06 |
28354 | A.19.07 A.19.08 A.19.09 A.19.10 A.19.11 A.19.12 A.19.13 | |
64d5610f ML |
28355 | @end itemize |
28356 | ||
b71d4b62 | 28357 | @geindex AI-0002 (Ada 2012 feature) |
64d5610f ML |
28358 | |
28359 | ||
28360 | @itemize * | |
28361 | ||
28362 | @item | |
b71d4b62 | 28363 | `AI-0002 Export C with unconstrained arrays (0000-00-00)' |
64d5610f | 28364 | |
b71d4b62 RA |
28365 | The compiler is not required to support exporting an Ada subprogram with |
28366 | convention C if there are parameters or a return type of an unconstrained | |
28367 | array type (such as @code{String}). GNAT allows such declarations but | |
28368 | generates warnings. It is possible, but complicated, to write the | |
28369 | corresponding C code and certainly such code would be specific to GNAT and | |
28370 | non-portable. | |
64d5610f | 28371 | |
b71d4b62 | 28372 | RM References: B.01 (17) B.03 (62) B.03 (71.1/2) |
64d5610f ML |
28373 | @end itemize |
28374 | ||
b71d4b62 | 28375 | @geindex AI05-0216 (Ada 2012 feature) |
64d5610f ML |
28376 | |
28377 | ||
28378 | @itemize * | |
28379 | ||
28380 | @item | |
b71d4b62 | 28381 | `AI-0216 No_Task_Hierarchy forbids local tasks (0000-00-00)' |
64d5610f | 28382 | |
b71d4b62 RA |
28383 | It is clearly the intention that @code{No_Task_Hierarchy} is intended to |
28384 | forbid tasks declared locally within subprograms, or functions returning task | |
28385 | objects, and that is the implementation that GNAT has always provided. | |
28386 | However the language in the RM was not sufficiently clear on this point. | |
28387 | Thus this is a documentation change in the RM only. | |
64d5610f | 28388 | |
b71d4b62 | 28389 | RM References: D.07 (3/3) |
64d5610f ML |
28390 | @end itemize |
28391 | ||
b71d4b62 | 28392 | @geindex AI-0211 (Ada 2012 feature) |
64d5610f ML |
28393 | |
28394 | ||
28395 | @itemize * | |
28396 | ||
28397 | @item | |
b71d4b62 | 28398 | `AI-0211 No_Relative_Delays forbids Set_Handler use (2010-07-09)' |
64d5610f | 28399 | |
b71d4b62 RA |
28400 | The restriction @code{No_Relative_Delays} forbids any calls to the subprogram |
28401 | @code{Ada.Real_Time.Timing_Events.Set_Handler}. | |
64d5610f | 28402 | |
b71d4b62 | 28403 | RM References: D.07 (5) D.07 (10/2) D.07 (10.4/2) D.07 (10.7/2) |
64d5610f ML |
28404 | @end itemize |
28405 | ||
b71d4b62 | 28406 | @geindex AI-0190 (Ada 2012 feature) |
64d5610f ML |
28407 | |
28408 | ||
28409 | @itemize * | |
28410 | ||
28411 | @item | |
b71d4b62 | 28412 | `AI-0190 pragma Default_Storage_Pool (2010-09-15)' |
64d5610f | 28413 | |
b71d4b62 RA |
28414 | This AI introduces a new pragma @code{Default_Storage_Pool}, which can be |
28415 | used to control storage pools globally. | |
28416 | In particular, you can force every access | |
28417 | type that is used for allocation (`new') to have an explicit storage pool, | |
28418 | or you can declare a pool globally to be used for all access types that lack | |
28419 | an explicit one. | |
64d5610f | 28420 | |
b71d4b62 | 28421 | RM References: D.07 (8) |
64d5610f ML |
28422 | @end itemize |
28423 | ||
b71d4b62 | 28424 | @geindex AI-0189 (Ada 2012 feature) |
64d5610f ML |
28425 | |
28426 | ||
28427 | @itemize * | |
28428 | ||
28429 | @item | |
b71d4b62 | 28430 | `AI-0189 No_Allocators_After_Elaboration (2010-01-23)' |
64d5610f | 28431 | |
b71d4b62 RA |
28432 | This AI introduces a new restriction @code{No_Allocators_After_Elaboration}, |
28433 | which says that no dynamic allocation will occur once elaboration is | |
28434 | completed. | |
28435 | In general this requires a run-time check, which is not required, and which | |
28436 | GNAT does not attempt. But the static cases of allocators in a task body or | |
28437 | in the body of the main program are detected and flagged at compile or bind | |
28438 | time. | |
64d5610f | 28439 | |
b71d4b62 | 28440 | RM References: D.07 (19.1/2) H.04 (23.3/2) |
64d5610f ML |
28441 | @end itemize |
28442 | ||
b71d4b62 | 28443 | @geindex AI-0171 (Ada 2012 feature) |
64d5610f ML |
28444 | |
28445 | ||
28446 | @itemize * | |
28447 | ||
28448 | @item | |
b71d4b62 | 28449 | `AI-0171 Pragma CPU and Ravenscar Profile (2010-09-24)' |
64d5610f | 28450 | |
b71d4b62 RA |
28451 | A new package @code{System.Multiprocessors} is added, together with the |
28452 | definition of pragma @code{CPU} for controlling task affinity. A new no | |
28453 | dependence restriction, on @code{System.Multiprocessors.Dispatching_Domains}, | |
28454 | is added to the Ravenscar profile. | |
64d5610f | 28455 | |
b71d4b62 | 28456 | RM References: D.13.01 (4/2) D.16 |
64d5610f ML |
28457 | @end itemize |
28458 | ||
b71d4b62 | 28459 | @geindex AI-0210 (Ada 2012 feature) |
64d5610f ML |
28460 | |
28461 | ||
28462 | @itemize * | |
28463 | ||
28464 | @item | |
b71d4b62 | 28465 | `AI-0210 Correct Timing_Events metric (0000-00-00)' |
64d5610f | 28466 | |
b71d4b62 RA |
28467 | This is a documentation only issue regarding wording of metric requirements, |
28468 | that does not affect the implementation of the compiler. | |
64d5610f | 28469 | |
b71d4b62 | 28470 | RM References: D.15 (24/2) |
64d5610f ML |
28471 | @end itemize |
28472 | ||
b71d4b62 | 28473 | @geindex AI-0206 (Ada 2012 feature) |
64d5610f ML |
28474 | |
28475 | ||
28476 | @itemize * | |
28477 | ||
28478 | @item | |
b71d4b62 | 28479 | `AI-0206 Remote types packages and preelaborate (2010-07-24)' |
64d5610f | 28480 | |
b71d4b62 RA |
28481 | Remote types packages are now allowed to depend on preelaborated packages. |
28482 | This was formerly considered illegal. | |
64d5610f | 28483 | |
b71d4b62 | 28484 | RM References: E.02.02 (6) |
64d5610f ML |
28485 | @end itemize |
28486 | ||
b71d4b62 | 28487 | @geindex AI-0152 (Ada 2012 feature) |
64d5610f ML |
28488 | |
28489 | ||
28490 | @itemize * | |
28491 | ||
28492 | @item | |
b71d4b62 | 28493 | `AI-0152 Restriction No_Anonymous_Allocators (2010-09-08)' |
64d5610f | 28494 | |
b71d4b62 RA |
28495 | Restriction @code{No_Anonymous_Allocators} prevents the use of allocators |
28496 | where the type of the returned value is an anonymous access type. | |
64d5610f | 28497 | |
b71d4b62 | 28498 | RM References: H.04 (8/1) |
64d5610f ML |
28499 | @end itemize |
28500 | ||
b71d4b62 | 28501 | @node GNAT language extensions,Security Hardening Features,Implementation of Ada 2012 Features,Top |
73918baf | 28502 | @anchor{gnat_rm/gnat_language_extensions doc}@anchor{431}@anchor{gnat_rm/gnat_language_extensions gnat-language-extensions}@anchor{432}@anchor{gnat_rm/gnat_language_extensions id1}@anchor{433} |
b71d4b62 RA |
28503 | @chapter GNAT language extensions |
28504 | ||
28505 | ||
28506 | The GNAT compiler implements a certain number of language extensions on top of | |
28507 | the latest Ada standard, implementing its own extended superset of Ada. | |
28508 | ||
28509 | There are two sets of language extensions: | |
64d5610f ML |
28510 | |
28511 | ||
28512 | @itemize * | |
28513 | ||
28514 | @item | |
b71d4b62 RA |
28515 | The first is the curated set. The features in that set are features that we |
28516 | consider being worthy additions to the Ada language, and that we want to make | |
28517 | available to users early on. | |
64d5610f | 28518 | |
b71d4b62 RA |
28519 | @item |
28520 | The second is the experimental set. It includes the first, but also | |
28521 | experimental features, that are here because they’re still in an early | |
28522 | prototyping phase. | |
64d5610f ML |
28523 | @end itemize |
28524 | ||
b71d4b62 RA |
28525 | @menu |
28526 | * How to activate the extended GNAT Ada superset:: | |
28527 | * Curated Extensions:: | |
28528 | * Experimental Language Extensions:: | |
64d5610f | 28529 | |
b71d4b62 | 28530 | @end menu |
64d5610f | 28531 | |
b71d4b62 | 28532 | @node How to activate the extended GNAT Ada superset,Curated Extensions,,GNAT language extensions |
73918baf | 28533 | @anchor{gnat_rm/gnat_language_extensions how-to-activate-the-extended-gnat-ada-superset}@anchor{434} |
b71d4b62 | 28534 | @section How to activate the extended GNAT Ada superset |
64d5610f | 28535 | |
64d5610f | 28536 | |
b71d4b62 | 28537 | There are two ways to activate the extended GNAT Ada superset: |
64d5610f | 28538 | |
b71d4b62 RA |
28539 | |
28540 | @itemize * | |
28541 | ||
28542 | @item | |
28543 | The @ref{65,,Pragma Extensions_Allowed}. To activate | |
28544 | the curated set of extensions, you should use | |
64d5610f ML |
28545 | @end itemize |
28546 | ||
b71d4b62 RA |
28547 | @example |
28548 | pragma Extensions_Allowed (On) | |
28549 | @end example | |
28550 | ||
28551 | As a configuration pragma, you can either put it at the beginning of a source | |
28552 | file, or in a @code{.adc} file corresponding to your project. | |
64d5610f ML |
28553 | |
28554 | ||
28555 | @itemize * | |
28556 | ||
28557 | @item | |
b71d4b62 RA |
28558 | The @code{-gnatX} option, that you can pass to the compiler directly, will |
28559 | activate the curated subset of extensions. | |
28560 | @end itemize | |
64d5610f | 28561 | |
b71d4b62 RA |
28562 | @cartouche |
28563 | @quotation Attention | |
28564 | You can activate the extended set of extensions by using either | |
28565 | the @code{-gnatX0} command line flag, or the pragma @code{Extensions_Allowed} with | |
28566 | @code{All} as an argument. However, it is not recommended you use this subset | |
28567 | for serious projects, and is only means as a playground/technology preview. | |
28568 | @end quotation | |
28569 | @end cartouche | |
64d5610f | 28570 | |
b71d4b62 | 28571 | @node Curated Extensions,Experimental Language Extensions,How to activate the extended GNAT Ada superset,GNAT language extensions |
73918baf | 28572 | @anchor{gnat_rm/gnat_language_extensions curated-extensions}@anchor{435}@anchor{gnat_rm/gnat_language_extensions curated-language-extensions}@anchor{66} |
b71d4b62 | 28573 | @section Curated Extensions |
64d5610f | 28574 | |
64d5610f | 28575 | |
b71d4b62 RA |
28576 | @menu |
28577 | * Conditional when constructs:: | |
28578 | * Case pattern matching:: | |
28579 | * Fixed lower bounds for array types and subtypes:: | |
28580 | * Prefixed-view notation for calls to primitive subprograms of untagged types:: | |
28581 | * Expression defaults for generic formal functions:: | |
28582 | * String interpolation:: | |
28583 | * Constrained attribute for generic objects:: | |
28584 | * Static aspect on intrinsic functions:: | |
64d5610f | 28585 | |
b71d4b62 | 28586 | @end menu |
64d5610f | 28587 | |
b71d4b62 | 28588 | @node Conditional when constructs,Case pattern matching,,Curated Extensions |
73918baf | 28589 | @anchor{gnat_rm/gnat_language_extensions conditional-when-constructs}@anchor{436} |
b71d4b62 | 28590 | @subsection Conditional when constructs |
64d5610f | 28591 | |
64d5610f | 28592 | |
b71d4b62 RA |
28593 | This feature extends the use of @code{when} as a way to condition a control-flow |
28594 | related statement, to all control-flow related statements. | |
64d5610f | 28595 | |
b71d4b62 | 28596 | To do a conditional return in a procedure the following syntax should be used: |
64d5610f | 28597 | |
b71d4b62 RA |
28598 | @example |
28599 | procedure P (Condition : Boolean) is | |
28600 | begin | |
28601 | return when Condition; | |
28602 | end; | |
28603 | @end example | |
64d5610f | 28604 | |
b71d4b62 | 28605 | This will return from the procedure if @code{Condition} is true. |
64d5610f | 28606 | |
b71d4b62 | 28607 | When being used in a function the conditional part comes after the return value: |
64d5610f | 28608 | |
b71d4b62 RA |
28609 | @example |
28610 | function Is_Null (I : Integer) return Boolean is | |
28611 | begin | |
28612 | return True when I = 0; | |
28613 | return False; | |
28614 | end; | |
28615 | @end example | |
64d5610f | 28616 | |
b71d4b62 | 28617 | In a similar way to the @code{exit when} a @code{goto ... when} can be employed: |
64d5610f | 28618 | |
b71d4b62 RA |
28619 | @example |
28620 | procedure Low_Level_Optimized is | |
28621 | Flags : Bitmapping; | |
28622 | begin | |
28623 | Do_1 (Flags); | |
28624 | goto Cleanup when Flags (1); | |
64d5610f | 28625 | |
b71d4b62 RA |
28626 | Do_2 (Flags); |
28627 | goto Cleanup when Flags (32); | |
64d5610f | 28628 | |
b71d4b62 | 28629 | -- ... |
64d5610f | 28630 | |
b71d4b62 RA |
28631 | <<Cleanup>> |
28632 | -- ... | |
28633 | end; | |
28634 | @end example | |
64d5610f | 28635 | |
b71d4b62 | 28636 | @c code-block |
64d5610f | 28637 | |
b71d4b62 | 28638 | To use a conditional raise construct: |
64d5610f | 28639 | |
b71d4b62 RA |
28640 | @example |
28641 | procedure Foo is | |
28642 | begin | |
28643 | raise Error when Imported_C_Func /= 0; | |
28644 | end; | |
28645 | @end example | |
64d5610f | 28646 | |
b71d4b62 | 28647 | An exception message can also be added: |
64d5610f | 28648 | |
b71d4b62 RA |
28649 | @example |
28650 | procedure Foo is | |
28651 | begin | |
28652 | raise Error with "Unix Error" | |
28653 | when Imported_C_Func /= 0; | |
28654 | end; | |
28655 | @end example | |
64d5610f | 28656 | |
b71d4b62 RA |
28657 | Link to the original RFC: |
28658 | @indicateurl{https://github.com/AdaCore/ada-spark-rfcs/blob/master/prototyped/rfc-conditional-when-constructs.rst} | |
64d5610f | 28659 | |
b71d4b62 | 28660 | @node Case pattern matching,Fixed lower bounds for array types and subtypes,Conditional when constructs,Curated Extensions |
73918baf | 28661 | @anchor{gnat_rm/gnat_language_extensions case-pattern-matching}@anchor{437} |
b71d4b62 | 28662 | @subsection Case pattern matching |
64d5610f | 28663 | |
64d5610f | 28664 | |
b8a3e2ed | 28665 | The selector for a case statement (but not yet for a case expression) may be of a composite type, subject to |
b71d4b62 RA |
28666 | some restrictions (described below). Aggregate syntax is used for choices |
28667 | of such a case statement; however, in cases where a “normal” aggregate would | |
28668 | require a discrete value, a discrete subtype may be used instead; box | |
28669 | notation can also be used to match all values. | |
64d5610f | 28670 | |
b71d4b62 | 28671 | Consider this example: |
64d5610f | 28672 | |
b71d4b62 RA |
28673 | @example |
28674 | type Rec is record | |
28675 | F1, F2 : Integer; | |
28676 | end record; | |
64d5610f | 28677 | |
b71d4b62 RA |
28678 | procedure Caser_1 (X : Rec) is |
28679 | begin | |
28680 | case X is | |
28681 | when (F1 => Positive, F2 => Positive) => | |
28682 | Do_This; | |
28683 | when (F1 => Natural, F2 => <>) | (F1 => <>, F2 => Natural) => | |
28684 | Do_That; | |
28685 | when others => | |
28686 | Do_The_Other_Thing; | |
28687 | end case; | |
28688 | end Caser_1; | |
28689 | @end example | |
64d5610f | 28690 | |
b71d4b62 RA |
28691 | If @code{Caser_1} is called and both components of X are positive, then |
28692 | @code{Do_This} will be called; otherwise, if either component is nonnegative | |
28693 | then @code{Do_That} will be called; otherwise, @code{Do_The_Other_Thing} will be | |
28694 | called. | |
64d5610f | 28695 | |
b71d4b62 RA |
28696 | In addition, pattern bindings are supported. This is a mechanism |
28697 | for binding a name to a component of a matching value for use within | |
28698 | an alternative of a case statement. For a component association | |
28699 | that occurs within a case choice, the expression may be followed by | |
28700 | @code{is <identifier>}. In the special case of a “box” component association, | |
28701 | the identifier may instead be provided within the box. Either of these | |
28702 | indicates that the given identifier denotes (a constant view of) the matching | |
28703 | subcomponent of the case selector. | |
64d5610f | 28704 | |
b71d4b62 RA |
28705 | @cartouche |
28706 | @quotation Attention | |
28707 | Binding is not yet supported for arrays or subcomponents | |
28708 | thereof. | |
28709 | @end quotation | |
28710 | @end cartouche | |
64d5610f | 28711 | |
b71d4b62 | 28712 | Consider this example (which uses type @code{Rec} from the previous example): |
64d5610f | 28713 | |
b71d4b62 RA |
28714 | @example |
28715 | procedure Caser_2 (X : Rec) is | |
28716 | begin | |
28717 | case X is | |
28718 | when (F1 => Positive is Abc, F2 => Positive) => | |
28719 | Do_This (Abc) | |
28720 | when (F1 => Natural is N1, F2 => <N2>) | | |
28721 | (F1 => <N2>, F2 => Natural is N1) => | |
28722 | Do_That (Param_1 => N1, Param_2 => N2); | |
28723 | when others => | |
28724 | Do_The_Other_Thing; | |
28725 | end case; | |
28726 | end Caser_2; | |
28727 | @end example | |
64d5610f | 28728 | |
b71d4b62 RA |
28729 | This example is the same as the previous one with respect to determining |
28730 | whether @code{Do_This}, @code{Do_That}, or @code{Do_The_Other_Thing} will be called. But | |
28731 | for this version, @code{Do_This} takes a parameter and @code{Do_That} takes two | |
28732 | parameters. If @code{Do_This} is called, the actual parameter in the call will be | |
28733 | @code{X.F1}. | |
64d5610f | 28734 | |
b71d4b62 RA |
28735 | If @code{Do_That} is called, the situation is more complex because there are two |
28736 | choices for that alternative. If @code{Do_That} is called because the first choice | |
28737 | matched (i.e., because @code{X.F1} is nonnegative and either @code{X.F1} or @code{X.F2} | |
28738 | is zero or negative), then the actual parameters of the call will be (in order) | |
28739 | @code{X.F1} and @code{X.F2}. If @code{Do_That} is called because the second choice | |
28740 | matched (and the first one did not), then the actual parameters will be | |
28741 | reversed. | |
64d5610f | 28742 | |
b71d4b62 RA |
28743 | Within the choice list for single alternative, each choice must define the same |
28744 | set of bindings and the component subtypes for for a given identifer must all | |
28745 | statically match. Currently, the case of a binding for a nondiscrete component | |
28746 | is not implemented. | |
64d5610f | 28747 | |
b71d4b62 RA |
28748 | If the set of values that match the choice(s) of an earlier alternative |
28749 | overlaps the corresponding set of a later alternative, then the first set shall | |
28750 | be a proper subset of the second (and the later alternative will not be | |
28751 | executed if the earlier alternative “matches”). All possible values of the | |
28752 | composite type shall be covered. The composite type of the selector shall be an | |
28753 | array or record type that is neither limited nor class-wide. Currently, a “when | |
28754 | others =>” case choice is required; it is intended that this requirement will | |
28755 | be relaxed at some point. | |
64d5610f | 28756 | |
b71d4b62 RA |
28757 | If a subcomponent’s subtype does not meet certain restrictions, then the only |
28758 | value that can be specified for that subcomponent in a case choice expression | |
28759 | is a “box” component association (which matches all possible values for the | |
28760 | subcomponent). This restriction applies if: | |
64d5610f | 28761 | |
64d5610f | 28762 | |
b71d4b62 | 28763 | @itemize - |
64d5610f | 28764 | |
b71d4b62 RA |
28765 | @item |
28766 | the component subtype is not a record, array, or discrete type; or | |
64d5610f ML |
28767 | |
28768 | @item | |
b71d4b62 RA |
28769 | the component subtype is subject to a non-static constraint or has a |
28770 | predicate; or: | |
64d5610f | 28771 | |
b71d4b62 RA |
28772 | @item |
28773 | the component type is an enumeration type that is subject to an enumeration | |
28774 | representation clause; or | |
64d5610f | 28775 | |
b71d4b62 RA |
28776 | @item |
28777 | the component type is a multidimensional array type or an array type with a | |
28778 | nonstatic index subtype. | |
64d5610f ML |
28779 | @end itemize |
28780 | ||
b71d4b62 RA |
28781 | Support for casing on arrays (and on records that contain arrays) is |
28782 | currently subject to some restrictions. Non-positional | |
28783 | array aggregates are not supported as (or within) case choices. Likewise | |
28784 | for array type and subtype names. The current implementation exceeds | |
28785 | compile-time capacity limits in some annoyingly common scenarios; the | |
28786 | message generated in such cases is usually “Capacity exceeded in compiling | |
28787 | case statement with composite selector type”. | |
64d5610f | 28788 | |
b71d4b62 RA |
28789 | Link to the original RFC: |
28790 | @indicateurl{https://github.com/AdaCore/ada-spark-rfcs/blob/master/prototyped/rfc-pattern-matching.rst} | |
64d5610f | 28791 | |
b71d4b62 | 28792 | @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 |
73918baf | 28793 | @anchor{gnat_rm/gnat_language_extensions fixed-lower-bounds-for-array-types-and-subtypes}@anchor{438} |
b71d4b62 | 28794 | @subsection Fixed lower bounds for array types and subtypes |
64d5610f | 28795 | |
64d5610f | 28796 | |
b71d4b62 RA |
28797 | Unconstrained array types and subtypes can be specified with a lower bound that |
28798 | is fixed to a certain value, by writing an index range that uses the syntax | |
28799 | @code{<lower-bound-expression> .. <>}. This guarantees that all objects of the | |
28800 | type or subtype will have the specified lower bound. | |
64d5610f | 28801 | |
b71d4b62 RA |
28802 | For example, a matrix type with fixed lower bounds of zero for each dimension |
28803 | can be declared by the following: | |
64d5610f | 28804 | |
b71d4b62 RA |
28805 | @example |
28806 | type Matrix is | |
28807 | array (Natural range 0 .. <>, Natural range 0 .. <>) of Integer; | |
28808 | @end example | |
64d5610f | 28809 | |
b71d4b62 RA |
28810 | Objects of type @code{Matrix} declared with an index constraint must have index |
28811 | ranges starting at zero: | |
64d5610f | 28812 | |
b71d4b62 RA |
28813 | @example |
28814 | M1 : Matrix (0 .. 9, 0 .. 19); | |
28815 | M2 : Matrix (2 .. 11, 3 .. 22); -- Warning about bounds; will raise CE | |
28816 | @end example | |
64d5610f | 28817 | |
b71d4b62 RA |
28818 | Similarly, a subtype of @code{String} can be declared that specifies the lower |
28819 | bound of objects of that subtype to be @code{1}: | |
64d5610f | 28820 | |
b71d4b62 | 28821 | @quotation |
64d5610f | 28822 | |
b71d4b62 RA |
28823 | @example |
28824 | subtype String_1 is String (1 .. <>); | |
28825 | @end example | |
28826 | @end quotation | |
64d5610f | 28827 | |
b71d4b62 RA |
28828 | If a string slice is passed to a formal of subtype @code{String_1} in a call to a |
28829 | subprogram @code{S}, the slice’s bounds will “slide” so that the lower bound is | |
28830 | @code{1}. | |
64d5610f | 28831 | |
b71d4b62 RA |
28832 | Within @code{S}, the lower bound of the formal is known to be @code{1}, so, unlike a |
28833 | normal unconstrained @code{String} formal, there is no need to worry about | |
28834 | accounting for other possible lower-bound values. Sliding of bounds also occurs | |
28835 | in other contexts, such as for object declarations with an unconstrained | |
28836 | subtype with fixed lower bound, as well as in subtype conversions. | |
64d5610f | 28837 | |
b71d4b62 RA |
28838 | Use of this feature increases safety by simplifying code, and can also improve |
28839 | the efficiency of indexing operations, since the compiler statically knows the | |
28840 | lower bound of unconstrained array formals when the formal’s subtype has index | |
28841 | ranges with static fixed lower bounds. | |
64d5610f | 28842 | |
b71d4b62 RA |
28843 | Link to the original RFC: |
28844 | @indicateurl{https://github.com/AdaCore/ada-spark-rfcs/blob/master/prototyped/rfc-fixed-lower-bound.rst} | |
64d5610f | 28845 | |
b71d4b62 | 28846 | @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 |
73918baf | 28847 | @anchor{gnat_rm/gnat_language_extensions prefixed-view-notation-for-calls-to-primitive-subprograms-of-untagged-types}@anchor{439} |
b71d4b62 RA |
28848 | @subsection Prefixed-view notation for calls to primitive subprograms of untagged types |
28849 | ||
28850 | ||
28851 | When operating on an untagged type, if it has any primitive operations, and the | |
28852 | first parameter of an operation is of the type (or is an access parameter with | |
28853 | an anonymous type that designates the type), you may invoke these operations | |
28854 | using an @code{object.op(...)} notation, where the parameter that would normally be | |
28855 | the first parameter is brought out front, and the remaining parameters (if any) | |
28856 | appear within parentheses after the name of the primitive operation. | |
28857 | ||
28858 | This same notation is already available for tagged types. This extension allows | |
28859 | for untagged types. It is allowed for all primitive operations of the type | |
28860 | independent of whether they were originally declared in a package spec or its | |
28861 | private part, or were inherited and/or overridden as part of a derived type | |
28862 | declaration occuring anywhere, so long as the first parameter is of the type, | |
28863 | or an access parameter designating the type. | |
28864 | ||
28865 | For example: | |
28866 | ||
28867 | @example | |
28868 | generic | |
28869 | type Elem_Type is private; | |
28870 | package Vectors is | |
28871 | type Vector is private; | |
28872 | procedure Add_Element (V : in out Vector; Elem : Elem_Type); | |
28873 | function Nth_Element (V : Vector; N : Positive) return Elem_Type; | |
28874 | function Length (V : Vector) return Natural; | |
28875 | private | |
28876 | function Capacity (V : Vector) return Natural; | |
28877 | -- Return number of elements that may be added without causing | |
28878 | -- any new allocation of space | |
28879 | ||
28880 | type Vector is ... | |
28881 | with Type_Invariant => Vector.Length <= Vector.Capacity; | |
28882 | ... | |
28883 | end Vectors; | |
28884 | ||
28885 | package Int_Vecs is new Vectors(Integer); | |
64d5610f | 28886 | |
b71d4b62 RA |
28887 | V : Int_Vecs.Vector; |
28888 | ... | |
28889 | V.Add_Element(42); | |
28890 | V.Add_Element(-33); | |
64d5610f | 28891 | |
b71d4b62 RA |
28892 | pragma Assert (V.Length = 2); |
28893 | pragma Assert (V.Nth_Element(1) = 42); | |
28894 | @end example | |
64d5610f | 28895 | |
b71d4b62 RA |
28896 | Link to the original RFC: |
28897 | @indicateurl{https://github.com/AdaCore/ada-spark-rfcs/blob/master/prototyped/rfc-prefixed-untagged.rst} | |
64d5610f | 28898 | |
b71d4b62 | 28899 | @node Expression defaults for generic formal functions,String interpolation,Prefixed-view notation for calls to primitive subprograms of untagged types,Curated Extensions |
73918baf | 28900 | @anchor{gnat_rm/gnat_language_extensions expression-defaults-for-generic-formal-functions}@anchor{43a} |
b71d4b62 | 28901 | @subsection Expression defaults for generic formal functions |
64d5610f | 28902 | |
64d5610f | 28903 | |
b71d4b62 RA |
28904 | The declaration of a generic formal function is allowed to specify |
28905 | an expression as a default, using the syntax of an expression function. | |
64d5610f | 28906 | |
b71d4b62 | 28907 | Here is an example of this feature: |
64d5610f | 28908 | |
b71d4b62 RA |
28909 | @example |
28910 | generic | |
28911 | type T is private; | |
28912 | with function Copy (Item : T) return T is (Item); -- Defaults to Item | |
28913 | package Stacks is | |
64d5610f | 28914 | |
b71d4b62 | 28915 | type Stack is limited private; |
64d5610f | 28916 | |
b71d4b62 RA |
28917 | procedure Push (S : in out Stack; X : T); -- Calls Copy on X |
28918 | function Pop (S : in out Stack) return T; -- Calls Copy to return item | |
64d5610f | 28919 | |
b71d4b62 RA |
28920 | private |
28921 | -- ... | |
28922 | end Stacks; | |
28923 | @end example | |
64d5610f | 28924 | |
b71d4b62 RA |
28925 | Link to the original RFC: |
28926 | @indicateurl{https://github.com/AdaCore/ada-spark-rfcs/blob/master/prototyped/rfc-expression-functions-as-default-for-generic-formal-function-parameters.rst} | |
64d5610f | 28927 | |
b71d4b62 | 28928 | @node String interpolation,Constrained attribute for generic objects,Expression defaults for generic formal functions,Curated Extensions |
73918baf | 28929 | @anchor{gnat_rm/gnat_language_extensions string-interpolation}@anchor{43b} |
b71d4b62 | 28930 | @subsection String interpolation |
64d5610f | 28931 | |
64d5610f | 28932 | |
b71d4b62 | 28933 | The syntax for string literals is extended to support string interpolation. |
64d5610f | 28934 | |
b71d4b62 RA |
28935 | Within an interpolated string literal, an arbitrary expression, when |
28936 | enclosed in @code{@{ ... @}}, is expanded at run time into the result of calling | |
28937 | @code{'Image} on the result of evaluating the expression enclosed by the brace | |
28938 | characters, unless it is already a string or a single character. | |
64d5610f | 28939 | |
b71d4b62 RA |
28940 | Here is an example of this feature where the expressions @code{Name} and @code{X + Y} |
28941 | will be evaluated and included in the string. | |
64d5610f | 28942 | |
b71d4b62 RA |
28943 | @example |
28944 | procedure Test_Interpolation is | |
28945 | X : Integer := 12; | |
28946 | Y : Integer := 15; | |
28947 | Name : String := "Leo"; | |
28948 | begin | |
28949 | Put_Line (f"The name is @{Name@} and the sum is @{X + Y@}."); | |
28950 | end Test_Interpolation; | |
28951 | @end example | |
64d5610f | 28952 | |
b71d4b62 RA |
28953 | In addition, an escape character (@code{\}) is provided for inserting certain |
28954 | standard control characters (such as @code{\t} for tabulation or @code{\n} for | |
28955 | newline) or to escape characters with special significance to the | |
28956 | interpolated string syntax, namely @code{"}, @code{@{}, @code{@}},and @code{\} itself. | |
64d5610f | 28957 | |
64d5610f | 28958 | |
b71d4b62 RA |
28959 | @multitable {xxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxx} |
28960 | @item | |
64d5610f | 28961 | |
b71d4b62 | 28962 | escaped_character |
64d5610f | 28963 | |
b71d4b62 | 28964 | @tab |
64d5610f | 28965 | |
b71d4b62 | 28966 | meaning |
64d5610f | 28967 | |
b71d4b62 | 28968 | @item |
64d5610f | 28969 | |
b71d4b62 | 28970 | @code{\a} |
64d5610f | 28971 | |
b71d4b62 | 28972 | @tab |
64d5610f | 28973 | |
b71d4b62 | 28974 | ALERT |
64d5610f | 28975 | |
b71d4b62 | 28976 | @item |
64d5610f | 28977 | |
b71d4b62 | 28978 | @code{\b} |
64d5610f | 28979 | |
b71d4b62 | 28980 | @tab |
64d5610f | 28981 | |
b71d4b62 | 28982 | BACKSPACE |
64d5610f | 28983 | |
b71d4b62 | 28984 | @item |
64d5610f | 28985 | |
b71d4b62 | 28986 | @code{\f} |
64d5610f | 28987 | |
b71d4b62 | 28988 | @tab |
64d5610f | 28989 | |
b71d4b62 | 28990 | FORM FEED |
64d5610f | 28991 | |
b71d4b62 | 28992 | @item |
64d5610f | 28993 | |
b71d4b62 | 28994 | @code{\n} |
64d5610f | 28995 | |
b71d4b62 | 28996 | @tab |
64d5610f | 28997 | |
b71d4b62 | 28998 | LINE FEED |
64d5610f | 28999 | |
b71d4b62 | 29000 | @item |
64d5610f | 29001 | |
b71d4b62 | 29002 | @code{\r} |
64d5610f | 29003 | |
b71d4b62 | 29004 | @tab |
64d5610f | 29005 | |
b71d4b62 | 29006 | CARRIAGE RETURN |
64d5610f | 29007 | |
b71d4b62 | 29008 | @item |
64d5610f | 29009 | |
b71d4b62 | 29010 | @code{\t} |
64d5610f | 29011 | |
b71d4b62 | 29012 | @tab |
64d5610f | 29013 | |
b71d4b62 | 29014 | CHARACTER TABULATION |
64d5610f | 29015 | |
b71d4b62 | 29016 | @item |
64d5610f | 29017 | |
b71d4b62 | 29018 | @code{\v} |
64d5610f | 29019 | |
b71d4b62 | 29020 | @tab |
64d5610f | 29021 | |
b71d4b62 | 29022 | LINE TABULATION |
64d5610f | 29023 | |
b71d4b62 | 29024 | @item |
64d5610f | 29025 | |
b71d4b62 | 29026 | @code{\0} |
64d5610f | 29027 | |
b71d4b62 | 29028 | @tab |
64d5610f | 29029 | |
b71d4b62 | 29030 | NUL |
64d5610f | 29031 | |
b71d4b62 | 29032 | @item |
64d5610f | 29033 | |
b71d4b62 | 29034 | @code{\\} |
64d5610f | 29035 | |
b71d4b62 | 29036 | @tab |
64d5610f | 29037 | |
b71d4b62 | 29038 | @code{\} |
64d5610f | 29039 | |
b71d4b62 | 29040 | @item |
64d5610f | 29041 | |
b71d4b62 | 29042 | @code{\"} |
64d5610f | 29043 | |
b71d4b62 | 29044 | @tab |
64d5610f | 29045 | |
b71d4b62 | 29046 | @code{"} |
64d5610f | 29047 | |
b71d4b62 | 29048 | @item |
64d5610f | 29049 | |
b71d4b62 | 29050 | @code{\@{} |
64d5610f | 29051 | |
b71d4b62 | 29052 | @tab |
64d5610f | 29053 | |
b71d4b62 | 29054 | @code{@{} |
64d5610f | 29055 | |
b71d4b62 | 29056 | @item |
64d5610f | 29057 | |
b71d4b62 | 29058 | @code{\@}} |
64d5610f | 29059 | |
b71d4b62 | 29060 | @tab |
64d5610f | 29061 | |
b71d4b62 | 29062 | @code{@}} |
64d5610f | 29063 | |
b71d4b62 | 29064 | @end multitable |
64d5610f | 29065 | |
64d5610f | 29066 | |
b71d4b62 RA |
29067 | Note that, unlike normal string literals, doubled characters have no |
29068 | special significance. So to include a double-quote or a brace character | |
29069 | in an interpolated string, they must be preceded by a @code{\}. | |
29070 | For example: | |
64d5610f | 29071 | |
b71d4b62 RA |
29072 | @example |
29073 | Put_Line | |
29074 | (f"X = @{X@} and Y = @{Y@} and X+Y = @{X+Y@};\n" & | |
29075 | f" a double quote is \" and" & | |
29076 | f" an open brace is \@{"); | |
29077 | @end example | |
64d5610f | 29078 | |
b71d4b62 RA |
29079 | Finally, a syntax is provided for creating multi-line string literals, |
29080 | without having to explicitly use an escape sequence such as @code{\n}. For | |
29081 | example: | |
64d5610f | 29082 | |
b71d4b62 RA |
29083 | @example |
29084 | Put_Line | |
29085 | (f"This is a multi-line" | |
29086 | "string literal" | |
29087 | "There is no ambiguity about how many" | |
29088 | "spaces are included in each line"); | |
29089 | @end example | |
64d5610f | 29090 | |
b71d4b62 RA |
29091 | Here is a link to the original RFC : |
29092 | @indicateurl{https://github.com/AdaCore/ada-spark-rfcs/blob/master/prototyped/rfc-string-interpolation.rst} | |
64d5610f | 29093 | |
b71d4b62 | 29094 | @node Constrained attribute for generic objects,Static aspect on intrinsic functions,String interpolation,Curated Extensions |
73918baf | 29095 | @anchor{gnat_rm/gnat_language_extensions constrained-attribute-for-generic-objects}@anchor{43c} |
b71d4b62 | 29096 | @subsection Constrained attribute for generic objects |
64d5610f ML |
29097 | |
29098 | ||
b71d4b62 RA |
29099 | The @code{Constrained} attribute is permitted for objects of generic types. The |
29100 | result indicates whether the corresponding actual is constrained. | |
64d5610f | 29101 | |
b71d4b62 | 29102 | @node Static aspect on intrinsic functions,,Constrained attribute for generic objects,Curated Extensions |
73918baf | 29103 | @anchor{gnat_rm/gnat_language_extensions static-aspect-on-intrinsic-functions}@anchor{43d} |
b71d4b62 | 29104 | @subsection @code{Static} aspect on intrinsic functions |
64d5610f | 29105 | |
64d5610f | 29106 | |
b71d4b62 RA |
29107 | The Ada 202x @code{Static} aspect can be specified on Intrinsic imported functions |
29108 | and the compiler will evaluate some of these intrinsics statically, in | |
29109 | particular the @code{Shift_Left} and @code{Shift_Right} intrinsics. | |
64d5610f | 29110 | |
b71d4b62 | 29111 | @node Experimental Language Extensions,,Curated Extensions,GNAT language extensions |
73918baf | 29112 | @anchor{gnat_rm/gnat_language_extensions experimental-language-extensions}@anchor{67}@anchor{gnat_rm/gnat_language_extensions id2}@anchor{43e} |
b71d4b62 | 29113 | @section Experimental Language Extensions |
64d5610f ML |
29114 | |
29115 | ||
b71d4b62 RA |
29116 | @menu |
29117 | * Pragma Storage_Model:: | |
29118 | * Simpler accessibility model:: | |
64d5610f | 29119 | |
b71d4b62 | 29120 | @end menu |
64d5610f | 29121 | |
b71d4b62 | 29122 | @node Pragma Storage_Model,Simpler accessibility model,,Experimental Language Extensions |
73918baf | 29123 | @anchor{gnat_rm/gnat_language_extensions pragma-storage-model}@anchor{43f} |
b71d4b62 | 29124 | @subsection Pragma Storage_Model |
64d5610f | 29125 | |
64d5610f | 29126 | |
b71d4b62 RA |
29127 | This feature proposes to redesign the concepts of Storage Pools into a more |
29128 | efficient model allowing higher performances and easier integration with low | |
29129 | footprint embedded run-times. | |
64d5610f | 29130 | |
b71d4b62 RA |
29131 | It also extends it to support distributed memory models, in particular to |
29132 | support interactions with GPU. | |
64d5610f | 29133 | |
b71d4b62 RA |
29134 | Here is a link to the full RFC: |
29135 | @indicateurl{https://github.com/AdaCore/ada-spark-rfcs/blob/master/prototyped/rfc-storage-model.rst} | |
64d5610f | 29136 | |
b71d4b62 | 29137 | @node Simpler accessibility model,,Pragma Storage_Model,Experimental Language Extensions |
73918baf | 29138 | @anchor{gnat_rm/gnat_language_extensions simpler-accessibility-model}@anchor{440} |
b71d4b62 | 29139 | @subsection Simpler accessibility model |
64d5610f | 29140 | |
64d5610f | 29141 | |
b71d4b62 RA |
29142 | The goal of this feature is to restore a common understanding of accessibility |
29143 | rules for implementers and users alike. The new rules should both be effective | |
29144 | at preventing errors and feel natural and compatible in an Ada environment | |
29145 | while removing dynamic accessibility checking. | |
29146 | ||
29147 | Here is a link to the full RFC: | |
29148 | @indicateurl{https://github.com/AdaCore/ada-spark-rfcs/blob/master/prototyped/rfc-simpler-accessibility.md} | |
64d5610f | 29149 | |
b71d4b62 | 29150 | @node Security Hardening Features,Obsolescent Features,GNAT language extensions,Top |
73918baf | 29151 | @anchor{gnat_rm/security_hardening_features doc}@anchor{441}@anchor{gnat_rm/security_hardening_features id1}@anchor{442}@anchor{gnat_rm/security_hardening_features security-hardening-features}@anchor{15} |
64d5610f ML |
29152 | @chapter Security Hardening Features |
29153 | ||
29154 | ||
29155 | This chapter describes Ada extensions aimed at security hardening that | |
29156 | are provided by GNAT. | |
29157 | ||
29158 | The features in this chapter are currently experimental and subject to | |
29159 | change. | |
29160 | ||
29161 | @c Register Scrubbing: | |
29162 | ||
29163 | @menu | |
29164 | * Register Scrubbing:: | |
29165 | * Stack Scrubbing:: | |
29166 | * Hardened Conditionals:: | |
29167 | * Hardened Booleans:: | |
29168 | * Control Flow Redundancy:: | |
29169 | ||
29170 | @end menu | |
29171 | ||
29172 | @node Register Scrubbing,Stack Scrubbing,,Security Hardening Features | |
73918baf | 29173 | @anchor{gnat_rm/security_hardening_features register-scrubbing}@anchor{443} |
64d5610f ML |
29174 | @section Register Scrubbing |
29175 | ||
29176 | ||
29177 | GNAT can generate code to zero-out hardware registers before returning | |
29178 | from a subprogram. | |
29179 | ||
29180 | It can be enabled with the @code{-fzero-call-used-regs=`choice'} | |
29181 | command-line option, to affect all subprograms in a compilation, and | |
29182 | with a @code{Machine_Attribute} pragma, to affect only specific | |
29183 | subprograms. | |
29184 | ||
29185 | @example | |
29186 | procedure Foo; | |
29187 | pragma Machine_Attribute (Foo, "zero_call_used_regs", "used"); | |
29188 | -- Before returning, Foo scrubs only call-clobbered registers | |
29189 | -- that it uses itself. | |
29190 | ||
29191 | function Bar return Integer; | |
29192 | pragma Machine_Attribute (Bar, "zero_call_used_regs", "all"); | |
29193 | -- Before returning, Bar scrubs all call-clobbered registers. | |
92eeb32d AO |
29194 | |
29195 | function Baz return Integer; | |
29196 | pragma Machine_Attribute (Bar, "zero_call_used_regs", "leafy"); | |
29197 | -- Before returning, Bar scrubs call-clobbered registers, either | |
29198 | -- those it uses itself, if it can be identified as a leaf | |
29199 | -- function, or all of them otherwise. | |
64d5610f ML |
29200 | @end example |
29201 | ||
29202 | For usage and more details on the command-line option, on the | |
29203 | @code{zero_call_used_regs} attribute, and on their use with other | |
29204 | programming languages, see @cite{Using the GNU Compiler Collection (GCC)}. | |
29205 | ||
29206 | @c Stack Scrubbing: | |
29207 | ||
29208 | @node Stack Scrubbing,Hardened Conditionals,Register Scrubbing,Security Hardening Features | |
73918baf | 29209 | @anchor{gnat_rm/security_hardening_features stack-scrubbing}@anchor{444} |
64d5610f ML |
29210 | @section Stack Scrubbing |
29211 | ||
29212 | ||
29213 | GNAT can generate code to zero-out stack frames used by subprograms. | |
29214 | ||
29215 | It can be activated with the @code{Machine_Attribute} pragma, on | |
29216 | specific subprograms and variables, or their types. (This attribute | |
29217 | always applies to a type, even when it is associated with a subprogram | |
29218 | or a variable.) | |
29219 | ||
29220 | @example | |
29221 | function Foo returns Integer; | |
29222 | pragma Machine_Attribute (Foo, "strub"); | |
29223 | -- Foo and its callers are modified so as to scrub the stack | |
29224 | -- space used by Foo after it returns. Shorthand for: | |
29225 | -- pragma Machine_Attribute (Foo, "strub", "at-calls"); | |
29226 | ||
29227 | procedure Bar; | |
29228 | pragma Machine_Attribute (Bar, "strub", "internal"); | |
29229 | -- Bar is turned into a wrapper for its original body, | |
29230 | -- and they scrub the stack used by the original body. | |
29231 | ||
29232 | Var : Integer; | |
29233 | pragma Machine_Attribute (Var, "strub"); | |
29234 | -- Reading from Var in a subprogram enables stack scrubbing | |
29235 | -- of the stack space used by the subprogram. Furthermore, if | |
29236 | -- Var is declared within a subprogram, this also enables | |
29237 | -- scrubbing of the stack space used by that subprogram. | |
29238 | @end example | |
29239 | ||
29240 | Given these declarations, Foo has its type and body modified as | |
29241 | follows: | |
29242 | ||
29243 | @example | |
29244 | function Foo (<WaterMark> : in out System.Address) returns Integer | |
29245 | is | |
29246 | -- ... | |
29247 | begin | |
29248 | <__strub_update> (<WaterMark>); -- Updates the stack WaterMark. | |
29249 | -- ... | |
29250 | end; | |
29251 | @end example | |
29252 | ||
29253 | whereas its callers are modified from: | |
29254 | ||
29255 | @example | |
29256 | X := Foo; | |
29257 | @end example | |
29258 | ||
29259 | to: | |
29260 | ||
29261 | @example | |
29262 | declare | |
29263 | <WaterMark> : System.Address; | |
29264 | begin | |
29265 | <__strub_enter> (<WaterMark>); -- Initialize <WaterMark>. | |
29266 | X := Foo (<WaterMark>); | |
29267 | <__strub_leave> (<WaterMark>); -- Scrubs stack up to <WaterMark>. | |
29268 | end; | |
29269 | @end example | |
29270 | ||
29271 | As for Bar, because it is strubbed in internal mode, its callers are | |
29272 | not modified. Its definition is modified roughly as follows: | |
29273 | ||
29274 | @example | |
29275 | procedure Bar is | |
29276 | <WaterMark> : System.Address; | |
29277 | procedure Strubbed_Bar (<WaterMark> : in out System.Address) is | |
29278 | begin | |
29279 | <__strub_update> (<WaterMark>); -- Updates the stack WaterMark. | |
29280 | -- original Bar body. | |
29281 | end Strubbed_Bar; | |
29282 | begin | |
29283 | <__strub_enter> (<WaterMark>); -- Initialize <WaterMark>. | |
29284 | Strubbed_Bar (<WaterMark>); | |
29285 | <__strub_leave> (<WaterMark>); -- Scrubs stack up to <WaterMark>. | |
29286 | end Bar; | |
29287 | @end example | |
29288 | ||
29289 | There are also @code{-fstrub=`choice'} command-line options to | |
29290 | control default settings. For usage and more details on the | |
29291 | command-line options, on the @code{strub} attribute, and their use with | |
29292 | other programming languages, see @cite{Using the GNU Compiler Collection (GCC)}. | |
29293 | ||
29294 | Note that Ada secondary stacks are not scrubbed. The restriction | |
29295 | @code{No_Secondary_Stack} avoids their use, and thus their accidental | |
29296 | preservation of data that should be scrubbed. | |
29297 | ||
29298 | Attributes @code{Access} and @code{Unconstrained_Access} of variables and | |
29299 | constants with @code{strub} enabled require types with @code{strub} enabled; | |
29300 | there is no way to express an access-to-strub type otherwise. | |
29301 | @code{Unchecked_Access} bypasses this constraint, but the resulting | |
29302 | access type designates a non-strub type. | |
29303 | ||
29304 | @example | |
29305 | VI : aliased Integer; | |
29306 | pragma Machine_Attribute (VI, "strub"); | |
29307 | XsVI : access Integer := VI'Access; -- Error. | |
29308 | UXsVI : access Integer := VI'Unchecked_Access; -- OK, | |
29309 | -- UXsVI does *not* enable strub in subprograms that | |
29310 | -- dereference it to obtain the UXsVI.all value. | |
29311 | ||
29312 | type Strub_Int is new Integer; | |
29313 | pragma Machine_Attribute (Strub_Int, "strub"); | |
29314 | VSI : aliased Strub_Int; | |
29315 | XsVSI : access Strub_Int := VSI'Access; -- OK, | |
29316 | -- VSI and XsVSI.all both enable strub in subprograms that | |
29317 | -- read their values. | |
29318 | @end example | |
29319 | ||
29320 | Every access-to-subprogram type, renaming, and overriding and | |
29321 | overridden dispatching operations that may refer to a subprogram with | |
29322 | an attribute-modified interface must be annotated with the same | |
29323 | interface-modifying attribute. Access-to-subprogram types can be | |
29324 | explicitly converted to different strub modes, as long as they are | |
29325 | interface-compatible (i.e., adding or removing @code{at-calls} is not | |
29326 | allowed). For example, a @code{strub}-@code{disabled} subprogram can be | |
29327 | turned @code{callable} through such an explicit conversion: | |
29328 | ||
29329 | @example | |
29330 | type TBar is access procedure; | |
29331 | ||
29332 | type TBar_Callable is access procedure; | |
29333 | pragma Machine_Attribute (TBar_Callable, "strub", "callable"); | |
29334 | -- The attribute modifies the procedure type, rather than the | |
29335 | -- access type, because of the extra argument after "strub", | |
29336 | -- only applicable to subprogram types. | |
29337 | ||
29338 | Bar_Callable_Ptr : constant TBar_Callable | |
29339 | := TBar_Callable (TBar'(Bar'Access)); | |
29340 | ||
29341 | procedure Bar_Callable renames Bar_Callable_Ptr.all; | |
29342 | pragma Machine_Attribute (Bar_Callable, "strub", "callable"); | |
29343 | @end example | |
29344 | ||
29345 | Note that the renaming declaration is expanded to a full subprogram | |
29346 | body, it won’t be just an alias. Only if it is inlined will it be as | |
29347 | efficient as a call by dereferencing the access-to-subprogram constant | |
29348 | Bar_Callable_Ptr. | |
29349 | ||
29350 | @c Hardened Conditionals: | |
29351 | ||
29352 | @node Hardened Conditionals,Hardened Booleans,Stack Scrubbing,Security Hardening Features | |
73918baf | 29353 | @anchor{gnat_rm/security_hardening_features hardened-conditionals}@anchor{445} |
64d5610f ML |
29354 | @section Hardened Conditionals |
29355 | ||
29356 | ||
29357 | GNAT can harden conditionals to protect against control-flow attacks. | |
29358 | ||
29359 | This is accomplished by two complementary transformations, each | |
29360 | activated by a separate command-line option. | |
29361 | ||
29362 | The option @code{-fharden-compares} enables hardening of compares | |
29363 | that compute results stored in variables, adding verification that the | |
29364 | reversed compare yields the opposite result, turning: | |
29365 | ||
29366 | @example | |
29367 | B := X = Y; | |
29368 | @end example | |
29369 | ||
29370 | into: | |
29371 | ||
29372 | @example | |
29373 | B := X = Y; | |
29374 | declare | |
29375 | NotB : Boolean := X /= Y; -- Computed independently of B. | |
29376 | begin | |
29377 | if B = NotB then | |
29378 | <__builtin_trap>; | |
29379 | end if; | |
29380 | end; | |
29381 | @end example | |
29382 | ||
29383 | The option @code{-fharden-conditional-branches} enables hardening | |
29384 | of compares that guard conditional branches, adding verification of | |
29385 | the reversed compare to both execution paths, turning: | |
29386 | ||
29387 | @example | |
29388 | if X = Y then | |
29389 | X := Z + 1; | |
29390 | else | |
29391 | Y := Z - 1; | |
29392 | end if; | |
29393 | @end example | |
29394 | ||
29395 | into: | |
29396 | ||
29397 | @example | |
29398 | if X = Y then | |
29399 | if X /= Y then -- Computed independently of X = Y. | |
29400 | <__builtin_trap>; | |
29401 | end if; | |
29402 | X := Z + 1; | |
29403 | else | |
29404 | if X /= Y then -- Computed independently of X = Y. | |
29405 | null; | |
29406 | else | |
29407 | <__builtin_trap>; | |
29408 | end if; | |
29409 | Y := Z - 1; | |
29410 | end if; | |
29411 | @end example | |
29412 | ||
29413 | These transformations are introduced late in the compilation pipeline, | |
29414 | long after boolean expressions are decomposed into separate compares, | |
29415 | each one turned into either a conditional branch or a compare whose | |
29416 | result is stored in a boolean variable or temporary. Compiler | |
29417 | optimizations, if enabled, may also turn conditional branches into | |
29418 | stored compares, and vice-versa, or into operations with implied | |
29419 | conditionals (e.g. MIN and MAX). Conditionals may also be optimized | |
29420 | out entirely, if their value can be determined at compile time, and | |
29421 | occasionally multiple compares can be combined into one. | |
29422 | ||
29423 | It is thus difficult to predict which of these two options will affect | |
29424 | a specific compare operation expressed in source code. Using both | |
29425 | options ensures that every compare that is neither optimized out nor | |
29426 | optimized into implied conditionals will be hardened. | |
29427 | ||
29428 | The addition of reversed compares can be observed by enabling the dump | |
29429 | files of the corresponding passes, through command-line options | |
29430 | @code{-fdump-tree-hardcmp} and @code{-fdump-tree-hardcbr}, | |
29431 | respectively. | |
29432 | ||
29433 | They are separate options, however, because of the significantly | |
29434 | different performance impact of the hardening transformations. | |
29435 | ||
29436 | For usage and more details on the command-line options, see | |
29437 | @cite{Using the GNU Compiler Collection (GCC)}. These options can | |
29438 | be used with other programming languages supported by GCC. | |
29439 | ||
29440 | @c Hardened Booleans: | |
29441 | ||
29442 | @node Hardened Booleans,Control Flow Redundancy,Hardened Conditionals,Security Hardening Features | |
73918baf | 29443 | @anchor{gnat_rm/security_hardening_features hardened-booleans}@anchor{446} |
64d5610f ML |
29444 | @section Hardened Booleans |
29445 | ||
29446 | ||
29447 | Ada has built-in support for introducing boolean types with | |
29448 | alternative representations, using representation clauses: | |
29449 | ||
29450 | @example | |
29451 | type HBool is new Boolean; | |
29452 | for HBool use (16#5a#, 16#a5#); | |
29453 | for HBool'Size use 8; | |
29454 | @end example | |
29455 | ||
29456 | When validity checking is enabled, the compiler will check that | |
29457 | variables of such types hold values corresponding to the selected | |
29458 | representations. | |
29459 | ||
29460 | There are multiple strategies for where to introduce validity checking | |
29461 | (see @code{-gnatV} options). Their goal is to guard against | |
29462 | various kinds of programming errors, and GNAT strives to omit checks | |
29463 | when program logic rules out an invalid value, and optimizers may | |
29464 | further remove checks found to be redundant. | |
29465 | ||
29466 | For additional hardening, the @code{hardbool} @code{Machine_Attribute} | |
29467 | pragma can be used to annotate boolean types with representation | |
29468 | clauses, so that expressions of such types used as conditions are | |
29469 | checked even when compiling with @code{-gnatVT}: | |
29470 | ||
29471 | @example | |
29472 | pragma Machine_Attribute (HBool, "hardbool"); | |
29473 | ||
29474 | function To_Boolean (X : HBool) returns Boolean is (Boolean (X)); | |
29475 | @end example | |
29476 | ||
29477 | is compiled roughly like: | |
29478 | ||
29479 | @example | |
29480 | function To_Boolean (X : HBool) returns Boolean is | |
29481 | begin | |
29482 | if X not in True | False then | |
29483 | raise Constraint_Error; | |
29484 | elsif X in True then | |
29485 | return True; | |
29486 | else | |
29487 | return False; | |
29488 | end if; | |
29489 | end To_Boolean; | |
29490 | @end example | |
29491 | ||
29492 | Note that @code{-gnatVn} will disable even @code{hardbool} testing. | |
29493 | ||
29494 | Analogous behavior is available as a GCC extension to the C and | |
29495 | Objective C programming languages, through the @code{hardbool} attribute, | |
29496 | with the difference that, instead of raising a Constraint_Error | |
29497 | exception, when a hardened boolean variable is found to hold a value | |
29498 | that stands for neither True nor False, the program traps. For usage | |
29499 | and more details on that attribute, see @cite{Using the GNU Compiler Collection (GCC)}. | |
29500 | ||
29501 | @c Control Flow Redundancy: | |
29502 | ||
29503 | @node Control Flow Redundancy,,Hardened Booleans,Security Hardening Features | |
73918baf | 29504 | @anchor{gnat_rm/security_hardening_features control-flow-redundancy}@anchor{447} |
64d5610f ML |
29505 | @section Control Flow Redundancy |
29506 | ||
29507 | ||
29508 | GNAT can guard against unexpected execution flows, such as branching | |
29509 | into the middle of subprograms, as in Return Oriented Programming | |
29510 | exploits. | |
29511 | ||
29512 | In units compiled with @code{-fharden-control-flow-redundancy}, | |
29513 | subprograms are instrumented so that, every time they are called, | |
29514 | basic blocks take note as control flows through them, and, before | |
29515 | returning, subprograms verify that the taken notes are consistent with | |
29516 | the control-flow graph. | |
29517 | ||
29518 | Functions with too many basic blocks, or with multiple return points, | |
29519 | call a run-time function to perform the verification. Other functions | |
29520 | perform the verification inline before returning. | |
29521 | ||
29522 | Optimizing the inlined verification can be quite time consuming, so | |
29523 | the default upper limit for the inline mode is set at 16 blocks. | |
29524 | Command-line option @code{--param hardcfr-max-inline-blocks=} can | |
29525 | override it. | |
29526 | ||
29527 | Even though typically sparse control-flow graphs exhibit run-time | |
29528 | verification time nearly proportional to the block count of a | |
29529 | subprogram, it may become very significant for generated subprograms | |
29530 | with thousands of blocks. Command-line option | |
29531 | @code{--param hardcfr-max-blocks=} can set an upper limit for | |
29532 | instrumentation. | |
29533 | ||
29534 | For each block that is marked as visited, the mechanism checks that at | |
29535 | least one of its predecessors, and at least one of its successors, are | |
29536 | also marked as visited. | |
29537 | ||
f3597ba6 AO |
29538 | Verification is performed just before a subprogram returns. The |
29539 | following fragment: | |
29540 | ||
29541 | @example | |
29542 | if X then | |
29543 | Y := F (Z); | |
29544 | return; | |
29545 | end if; | |
29546 | @end example | |
29547 | ||
29548 | gets turned into: | |
29549 | ||
29550 | @example | |
29551 | type Visited_Bitmap is array (1..N) of Boolean with Pack; | |
29552 | Visited : aliased Visited_Bitmap := (others => False); | |
29553 | -- Bitmap of visited blocks. N is the basic block count. | |
29554 | [...] | |
29555 | -- Basic block #I | |
29556 | Visited(I) := True; | |
29557 | if X then | |
29558 | -- Basic block #J | |
29559 | Visited(J) := True; | |
29560 | Y := F (Z); | |
29561 | CFR.Check (N, Visited'Access, CFG'Access); | |
29562 | -- CFR is a hypothetical package whose Check procedure calls | |
29563 | -- libgcc's __hardcfr_check, that traps if the Visited bitmap | |
29564 | -- does not hold a valid path in CFG, the run-time | |
29565 | -- representation of the control flow graph in the enclosing | |
29566 | -- subprogram. | |
29567 | return; | |
29568 | end if; | |
29569 | -- Basic block #K | |
29570 | Visited(K) := True; | |
29571 | @end example | |
29572 | ||
29573 | Verification would also be performed before tail calls, if any | |
29574 | front-ends marked them as mandatory or desirable, but none do. | |
29575 | Regular calls are optimized into tail calls too late for this | |
29576 | transformation to act on it. | |
29577 | ||
29578 | In order to avoid adding verification after potential tail calls, | |
29579 | which would prevent tail-call optimization, we recognize returning | |
29580 | calls, i.e., calls whose result, if any, is returned by the calling | |
29581 | subprogram to its caller immediately after the call returns. | |
29582 | Verification is performed before such calls, whether or not they are | |
29583 | ultimately optimized to tail calls. This behavior is enabled by | |
29584 | default whenever sibcall optimization is enabled (see | |
29585 | @code{-foptimize-sibling-calls}); it may be disabled with | |
29586 | @code{-fno-hardcfr-check-returning-calls}, or enabled with | |
29587 | @code{-fhardcfr-check-returning-calls}, regardless of the | |
29588 | optimization, but the lack of other optimizations may prevent calls | |
29589 | from being recognized as returning calls: | |
29590 | ||
29591 | @example | |
29592 | -- CFR.Check here, with -fhardcfr-check-returning-calls. | |
29593 | P (X); | |
29594 | -- CFR.Check here, with -fno-hardcfr-check-returning-calls. | |
29595 | return; | |
29596 | @end example | |
29597 | ||
29598 | or: | |
29599 | ||
29600 | @example | |
29601 | -- CFR.Check here, with -fhardcfr-check-returning-calls. | |
29602 | R := F (X); | |
29603 | -- CFR.Check here, with -fno-hardcfr-check-returning-calls. | |
29604 | return R; | |
29605 | @end example | |
29606 | ||
29607 | Any subprogram from which an exception may escape, i.e., that may | |
29608 | raise or propagate an exception that isn’t handled internally, is | |
29609 | conceptually enclosed by a cleanup handler that performs verification, | |
29610 | unless this is disabled with @code{-fno-hardcfr-check-exceptions}. | |
29611 | With this feature enabled, a subprogram body containing: | |
29612 | ||
29613 | @example | |
29614 | -- ... | |
29615 | Y := F (X); -- May raise exceptions. | |
29616 | -- ... | |
29617 | raise E; -- Not handled internally. | |
29618 | -- ... | |
29619 | @end example | |
29620 | ||
29621 | gets modified as follows: | |
29622 | ||
29623 | @example | |
29624 | begin | |
29625 | -- ... | |
29626 | Y := F (X); -- May raise exceptions. | |
29627 | -- ... | |
29628 | raise E; -- Not handled internally. | |
29629 | -- ... | |
29630 | exception | |
29631 | when others => | |
29632 | CFR.Check (N, Visited'Access, CFG'Access); | |
29633 | raise; | |
29634 | end; | |
29635 | @end example | |
29636 | ||
29637 | Verification may also be performed before No_Return calls, whether | |
29638 | only nothrow ones, with | |
29639 | @code{-fhardcfr-check-noreturn-calls=nothrow}, or all of them, with | |
29640 | @code{-fhardcfr-check-noreturn-calls=always}. The default is | |
29641 | @code{-fhardcfr-check-noreturn-calls=never} for this feature, that | |
29642 | disables checking before No_Return calls. | |
29643 | ||
29644 | When a No_Return call returns control to its caller through an | |
29645 | exception, verification may have already been performed before the | |
29646 | call, if @code{-fhardcfr-check-noreturn-calls=always} is in effect. | |
29647 | The compiler arranges for already-checked No_Return calls without a | |
29648 | preexisting handler to bypass the implicitly-added cleanup handler and | |
29649 | thus the redundant check, but a local exception or cleanup handler, if | |
29650 | present, will modify the set of visited blocks, and checking will take | |
29651 | place again when the caller reaches the next verification point, | |
29652 | whether it is a return or reraise statement after the exception is | |
29653 | otherwise handled, or even another No_Return call. | |
64d5610f ML |
29654 | |
29655 | The instrumentation for hardening with control flow redundancy can be | |
29656 | observed in dump files generated by the command-line option | |
29657 | @code{-fdump-tree-hardcfr}. | |
29658 | ||
29659 | For more details on the control flow redundancy command-line options, | |
29660 | see @cite{Using the GNU Compiler Collection (GCC)}. These options | |
29661 | can be used with other programming languages supported by GCC. | |
29662 | ||
29663 | @node Obsolescent Features,Compatibility and Porting Guide,Security Hardening Features,Top | |
73918baf | 29664 | @anchor{gnat_rm/obsolescent_features doc}@anchor{448}@anchor{gnat_rm/obsolescent_features id1}@anchor{449}@anchor{gnat_rm/obsolescent_features obsolescent-features}@anchor{16} |
64d5610f ML |
29665 | @chapter Obsolescent Features |
29666 | ||
29667 | ||
29668 | This chapter describes features that are provided by GNAT, but are | |
29669 | considered obsolescent since there are preferred ways of achieving | |
29670 | the same effect. These features are provided solely for historical | |
29671 | compatibility purposes. | |
29672 | ||
29673 | @menu | |
29674 | * pragma No_Run_Time:: | |
29675 | * pragma Ravenscar:: | |
29676 | * pragma Restricted_Run_Time:: | |
29677 | * pragma Task_Info:: | |
29678 | * package System.Task_Info (s-tasinf.ads): package System Task_Info s-tasinf ads. | |
29679 | ||
29680 | @end menu | |
29681 | ||
29682 | @node pragma No_Run_Time,pragma Ravenscar,,Obsolescent Features | |
73918baf | 29683 | @anchor{gnat_rm/obsolescent_features id2}@anchor{44a}@anchor{gnat_rm/obsolescent_features pragma-no-run-time}@anchor{44b} |
64d5610f ML |
29684 | @section pragma No_Run_Time |
29685 | ||
29686 | ||
29687 | The pragma @code{No_Run_Time} is used to achieve an affect similar | |
29688 | to the use of the “Zero Foot Print” configurable run time, but without | |
29689 | requiring a specially configured run time. The result of using this | |
29690 | pragma, which must be used for all units in a partition, is to restrict | |
29691 | the use of any language features requiring run-time support code. The | |
29692 | preferred usage is to use an appropriately configured run-time that | |
29693 | includes just those features that are to be made accessible. | |
29694 | ||
29695 | @node pragma Ravenscar,pragma Restricted_Run_Time,pragma No_Run_Time,Obsolescent Features | |
73918baf | 29696 | @anchor{gnat_rm/obsolescent_features id3}@anchor{44c}@anchor{gnat_rm/obsolescent_features pragma-ravenscar}@anchor{44d} |
64d5610f ML |
29697 | @section pragma Ravenscar |
29698 | ||
29699 | ||
29700 | The pragma @code{Ravenscar} has exactly the same effect as pragma | |
29701 | @code{Profile (Ravenscar)}. The latter usage is preferred since it | |
29702 | is part of the new Ada 2005 standard. | |
29703 | ||
29704 | @node pragma Restricted_Run_Time,pragma Task_Info,pragma Ravenscar,Obsolescent Features | |
73918baf | 29705 | @anchor{gnat_rm/obsolescent_features id4}@anchor{44e}@anchor{gnat_rm/obsolescent_features pragma-restricted-run-time}@anchor{44f} |
64d5610f ML |
29706 | @section pragma Restricted_Run_Time |
29707 | ||
29708 | ||
29709 | The pragma @code{Restricted_Run_Time} has exactly the same effect as | |
29710 | pragma @code{Profile (Restricted)}. The latter usage is | |
29711 | preferred since the Ada 2005 pragma @code{Profile} is intended for | |
29712 | this kind of implementation dependent addition. | |
29713 | ||
29714 | @node pragma Task_Info,package System Task_Info s-tasinf ads,pragma Restricted_Run_Time,Obsolescent Features | |
73918baf | 29715 | @anchor{gnat_rm/obsolescent_features id5}@anchor{450}@anchor{gnat_rm/obsolescent_features pragma-task-info}@anchor{451} |
64d5610f ML |
29716 | @section pragma Task_Info |
29717 | ||
29718 | ||
29719 | The functionality provided by pragma @code{Task_Info} is now part of the | |
29720 | Ada language. The @code{CPU} aspect and the package | |
29721 | @code{System.Multiprocessors} offer a less system-dependent way to specify | |
29722 | task affinity or to query the number of processors. | |
29723 | ||
29724 | Syntax | |
29725 | ||
29726 | @example | |
29727 | pragma Task_Info (EXPRESSION); | |
29728 | @end example | |
29729 | ||
29730 | This pragma appears within a task definition (like pragma | |
29731 | @code{Priority}) and applies to the task in which it appears. The | |
29732 | argument must be of type @code{System.Task_Info.Task_Info_Type}. | |
29733 | The @code{Task_Info} pragma provides system dependent control over | |
29734 | aspects of tasking implementation, for example, the ability to map | |
29735 | tasks to specific processors. For details on the facilities available | |
29736 | for the version of GNAT that you are using, see the documentation | |
29737 | in the spec of package System.Task_Info in the runtime | |
29738 | library. | |
29739 | ||
29740 | @node package System Task_Info s-tasinf ads,,pragma Task_Info,Obsolescent Features | |
73918baf | 29741 | @anchor{gnat_rm/obsolescent_features package-system-task-info}@anchor{452}@anchor{gnat_rm/obsolescent_features package-system-task-info-s-tasinf-ads}@anchor{453} |
64d5610f ML |
29742 | @section package System.Task_Info (@code{s-tasinf.ads}) |
29743 | ||
29744 | ||
29745 | This package provides target dependent functionality that is used | |
29746 | to support the @code{Task_Info} pragma. The predefined Ada package | |
29747 | @code{System.Multiprocessors} and the @code{CPU} aspect now provide a | |
29748 | standard replacement for GNAT’s @code{Task_Info} functionality. | |
29749 | ||
29750 | @node Compatibility and Porting Guide,GNU Free Documentation License,Obsolescent Features,Top | |
73918baf | 29751 | @anchor{gnat_rm/compatibility_and_porting_guide doc}@anchor{454}@anchor{gnat_rm/compatibility_and_porting_guide compatibility-and-porting-guide}@anchor{17}@anchor{gnat_rm/compatibility_and_porting_guide id1}@anchor{455} |
64d5610f ML |
29752 | @chapter Compatibility and Porting Guide |
29753 | ||
29754 | ||
29755 | This chapter presents some guidelines for developing portable Ada code, | |
29756 | describes the compatibility issues that may arise between | |
29757 | GNAT and other Ada compilation systems (including those for Ada 83), | |
29758 | and shows how GNAT can expedite porting | |
29759 | applications developed in other Ada environments. | |
29760 | ||
29761 | @menu | |
29762 | * Writing Portable Fixed-Point Declarations:: | |
29763 | * Compatibility with Ada 83:: | |
29764 | * Compatibility between Ada 95 and Ada 2005:: | |
29765 | * Implementation-dependent characteristics:: | |
29766 | * Compatibility with Other Ada Systems:: | |
29767 | * Representation Clauses:: | |
29768 | * Compatibility with HP Ada 83:: | |
29769 | ||
29770 | @end menu | |
29771 | ||
29772 | @node Writing Portable Fixed-Point Declarations,Compatibility with Ada 83,,Compatibility and Porting Guide | |
73918baf | 29773 | @anchor{gnat_rm/compatibility_and_porting_guide id2}@anchor{456}@anchor{gnat_rm/compatibility_and_porting_guide writing-portable-fixed-point-declarations}@anchor{457} |
64d5610f ML |
29774 | @section Writing Portable Fixed-Point Declarations |
29775 | ||
29776 | ||
29777 | The Ada Reference Manual gives an implementation freedom to choose bounds | |
29778 | that are narrower by @code{Small} from the given bounds. | |
29779 | For example, if we write | |
29780 | ||
29781 | @example | |
29782 | type F1 is delta 1.0 range -128.0 .. +128.0; | |
29783 | @end example | |
29784 | ||
29785 | then the implementation is allowed to choose -128.0 .. +127.0 if it | |
29786 | likes, but is not required to do so. | |
29787 | ||
29788 | This leads to possible portability problems, so let’s have a closer | |
29789 | look at this, and figure out how to avoid these problems. | |
29790 | ||
29791 | First, why does this freedom exist, and why would an implementation | |
29792 | take advantage of it? To answer this, take a closer look at the type | |
29793 | declaration for @code{F1} above. If the compiler uses the given bounds, | |
29794 | it would need 9 bits to hold the largest positive value (and typically | |
29795 | that means 16 bits on all machines). But if the implementation chooses | |
29796 | the +127.0 bound then it can fit values of the type in 8 bits. | |
29797 | ||
29798 | Why not make the user write +127.0 if that’s what is wanted? | |
29799 | The rationale is that if you are thinking of fixed point | |
29800 | as a kind of ‘poor man’s floating-point’, then you don’t want | |
29801 | to be thinking about the scaled integers that are used in its | |
29802 | representation. Let’s take another example: | |
29803 | ||
29804 | @example | |
29805 | type F2 is delta 2.0**(-15) range -1.0 .. +1.0; | |
29806 | @end example | |
29807 | ||
29808 | Looking at this declaration, it seems casually as though | |
29809 | it should fit in 16 bits, but again that extra positive value | |
29810 | +1.0 has the scaled integer equivalent of 2**15 which is one too | |
29811 | big for signed 16 bits. The implementation can treat this as: | |
29812 | ||
29813 | @example | |
29814 | type F2 is delta 2.0**(-15) range -1.0 .. +1.0-(2.0**(-15)); | |
29815 | @end example | |
29816 | ||
29817 | and the Ada language design team felt that this was too annoying | |
29818 | to require. We don’t need to debate this decision at this point, | |
29819 | since it is well established (the rule about narrowing the ranges | |
29820 | dates to Ada 83). | |
29821 | ||
29822 | But the important point is that an implementation is not required | |
29823 | to do this narrowing, so we have a potential portability problem. | |
29824 | We could imagine three types of implementation: | |
29825 | ||
29826 | ||
29827 | @enumerate a | |
29828 | ||
29829 | @item | |
29830 | those that narrow the range automatically if they can figure | |
29831 | out that the narrower range will allow storage in a smaller machine unit, | |
29832 | ||
29833 | @item | |
29834 | those that will narrow only if forced to by a @code{'Size} clause, and | |
29835 | ||
29836 | @item | |
29837 | those that will never narrow. | |
29838 | @end enumerate | |
29839 | ||
29840 | Now if we are language theoreticians, we can imagine a fourth | |
29841 | approach: to narrow all the time, e.g. to treat | |
29842 | ||
29843 | @example | |
29844 | type F3 is delta 1.0 range -10.0 .. +23.0; | |
29845 | @end example | |
29846 | ||
29847 | as though it had been written: | |
29848 | ||
29849 | @example | |
29850 | type F3 is delta 1.0 range -9.0 .. +22.0; | |
29851 | @end example | |
29852 | ||
29853 | But although technically allowed, such a behavior would be hostile and silly, | |
29854 | and no real compiler would do this. All real compilers will fall into one of | |
29855 | the categories (a), (b) or (c) above. | |
29856 | ||
29857 | So, how do you get the compiler to do what you want? The answer is give the | |
29858 | actual bounds you want, and then use a @code{'Small} clause and a | |
29859 | @code{'Size} clause to absolutely pin down what the compiler does. | |
29860 | E.g., for @code{F2} above, we will write: | |
29861 | ||
29862 | @example | |
29863 | My_Small : constant := 2.0**(-15); | |
29864 | My_First : constant := -1.0; | |
29865 | My_Last : constant := +1.0 - My_Small; | |
29866 | ||
29867 | type F2 is delta My_Small range My_First .. My_Last; | |
29868 | @end example | |
29869 | ||
29870 | and then add | |
29871 | ||
29872 | @example | |
29873 | for F2'Small use my_Small; | |
29874 | for F2'Size use 16; | |
29875 | @end example | |
29876 | ||
29877 | In practice all compilers will do the same thing here and will give you | |
29878 | what you want, so the above declarations are fully portable. If you really | |
29879 | want to play language lawyer and guard against ludicrous behavior by the | |
29880 | compiler you could add | |
29881 | ||
29882 | @example | |
29883 | Test1 : constant := 1 / Boolean'Pos (F2'First = My_First); | |
29884 | Test2 : constant := 1 / Boolean'Pos (F2'Last = My_Last); | |
29885 | @end example | |
29886 | ||
29887 | One or other or both are allowed to be illegal if the compiler is | |
29888 | behaving in a silly manner, but at least the silly compiler will not | |
29889 | get away with silently messing with your (very clear) intentions. | |
29890 | ||
29891 | If you follow this scheme you will be guaranteed that your fixed-point | |
29892 | types will be portable. | |
29893 | ||
29894 | @node Compatibility with Ada 83,Compatibility between Ada 95 and Ada 2005,Writing Portable Fixed-Point Declarations,Compatibility and Porting Guide | |
73918baf | 29895 | @anchor{gnat_rm/compatibility_and_porting_guide compatibility-with-ada-83}@anchor{458}@anchor{gnat_rm/compatibility_and_porting_guide id3}@anchor{459} |
64d5610f ML |
29896 | @section Compatibility with Ada 83 |
29897 | ||
29898 | ||
29899 | @geindex Compatibility (between Ada 83 and Ada 95 / Ada 2005 / Ada 2012) | |
29900 | ||
29901 | Ada 95 and the subsequent revisions Ada 2005 and Ada 2012 | |
29902 | are highly upwards compatible with Ada 83. In | |
29903 | particular, the design intention was that the difficulties associated | |
29904 | with moving from Ada 83 to later versions of the standard should be no greater | |
29905 | than those that occur when moving from one Ada 83 system to another. | |
29906 | ||
29907 | However, there are a number of points at which there are minor | |
29908 | incompatibilities. The @cite{Ada 95 Annotated Reference Manual} contains | |
29909 | full details of these issues as they relate to Ada 95, | |
29910 | and should be consulted for a complete treatment. | |
29911 | In practice the | |
29912 | following subsections treat the most likely issues to be encountered. | |
29913 | ||
29914 | @menu | |
29915 | * Legal Ada 83 programs that are illegal in Ada 95:: | |
29916 | * More deterministic semantics:: | |
29917 | * Changed semantics:: | |
29918 | * Other language compatibility issues:: | |
29919 | ||
29920 | @end menu | |
29921 | ||
29922 | @node Legal Ada 83 programs that are illegal in Ada 95,More deterministic semantics,,Compatibility with Ada 83 | |
73918baf | 29923 | @anchor{gnat_rm/compatibility_and_porting_guide id4}@anchor{45a}@anchor{gnat_rm/compatibility_and_porting_guide legal-ada-83-programs-that-are-illegal-in-ada-95}@anchor{45b} |
64d5610f ML |
29924 | @subsection Legal Ada 83 programs that are illegal in Ada 95 |
29925 | ||
29926 | ||
29927 | Some legal Ada 83 programs are illegal (i.e., they will fail to compile) in | |
29928 | Ada 95 and later versions of the standard: | |
29929 | ||
29930 | ||
29931 | @itemize * | |
29932 | ||
29933 | @item | |
29934 | `Character literals' | |
29935 | ||
29936 | Some uses of character literals are ambiguous. Since Ada 95 has introduced | |
29937 | @code{Wide_Character} as a new predefined character type, some uses of | |
29938 | character literals that were legal in Ada 83 are illegal in Ada 95. | |
29939 | For example: | |
29940 | ||
29941 | @example | |
29942 | for Char in 'A' .. 'Z' loop ... end loop; | |
29943 | @end example | |
29944 | ||
29945 | The problem is that ‘A’ and ‘Z’ could be from either | |
29946 | @code{Character} or @code{Wide_Character}. The simplest correction | |
29947 | is to make the type explicit; e.g.: | |
29948 | ||
29949 | @example | |
29950 | for Char in Character range 'A' .. 'Z' loop ... end loop; | |
29951 | @end example | |
29952 | ||
29953 | @item | |
29954 | `New reserved words' | |
29955 | ||
29956 | The identifiers @code{abstract}, @code{aliased}, @code{protected}, | |
29957 | @code{requeue}, @code{tagged}, and @code{until} are reserved in Ada 95. | |
29958 | Existing Ada 83 code using any of these identifiers must be edited to | |
29959 | use some alternative name. | |
29960 | ||
29961 | @item | |
29962 | `Freezing rules' | |
29963 | ||
29964 | The rules in Ada 95 are slightly different with regard to the point at | |
29965 | which entities are frozen, and representation pragmas and clauses are | |
29966 | not permitted past the freeze point. This shows up most typically in | |
29967 | the form of an error message complaining that a representation item | |
29968 | appears too late, and the appropriate corrective action is to move | |
29969 | the item nearer to the declaration of the entity to which it refers. | |
29970 | ||
29971 | A particular case is that representation pragmas | |
29972 | cannot be applied to a subprogram body. If necessary, a separate subprogram | |
29973 | declaration must be introduced to which the pragma can be applied. | |
29974 | ||
29975 | @item | |
29976 | `Optional bodies for library packages' | |
29977 | ||
29978 | In Ada 83, a package that did not require a package body was nevertheless | |
29979 | allowed to have one. This lead to certain surprises in compiling large | |
29980 | systems (situations in which the body could be unexpectedly ignored by the | |
29981 | binder). In Ada 95, if a package does not require a body then it is not | |
29982 | permitted to have a body. To fix this problem, simply remove a redundant | |
29983 | body if it is empty, or, if it is non-empty, introduce a dummy declaration | |
29984 | into the spec that makes the body required. One approach is to add a private | |
29985 | part to the package declaration (if necessary), and define a parameterless | |
29986 | procedure called @code{Requires_Body}, which must then be given a dummy | |
29987 | procedure body in the package body, which then becomes required. | |
29988 | Another approach (assuming that this does not introduce elaboration | |
29989 | circularities) is to add an @code{Elaborate_Body} pragma to the package spec, | |
29990 | since one effect of this pragma is to require the presence of a package body. | |
29991 | ||
29992 | @item | |
29993 | `Numeric_Error is the same exception as Constraint_Error' | |
29994 | ||
29995 | In Ada 95, the exception @code{Numeric_Error} is a renaming of @code{Constraint_Error}. | |
29996 | This means that it is illegal to have separate exception handlers for | |
29997 | the two exceptions. The fix is simply to remove the handler for the | |
29998 | @code{Numeric_Error} case (since even in Ada 83, a compiler was free to raise | |
29999 | @code{Constraint_Error} in place of @code{Numeric_Error} in all cases). | |
30000 | ||
30001 | @item | |
30002 | `Indefinite subtypes in generics' | |
30003 | ||
30004 | In Ada 83, it was permissible to pass an indefinite type (e.g, @code{String}) | |
30005 | as the actual for a generic formal private type, but then the instantiation | |
30006 | would be illegal if there were any instances of declarations of variables | |
30007 | of this type in the generic body. In Ada 95, to avoid this clear violation | |
30008 | of the methodological principle known as the ‘contract model’, | |
30009 | the generic declaration explicitly indicates whether | |
30010 | or not such instantiations are permitted. If a generic formal parameter | |
30011 | has explicit unknown discriminants, indicated by using @code{(<>)} after the | |
30012 | subtype name, then it can be instantiated with indefinite types, but no | |
30013 | stand-alone variables can be declared of this type. Any attempt to declare | |
30014 | such a variable will result in an illegality at the time the generic is | |
30015 | declared. If the @code{(<>)} notation is not used, then it is illegal | |
30016 | to instantiate the generic with an indefinite type. | |
30017 | This is the potential incompatibility issue when porting Ada 83 code to Ada 95. | |
30018 | It will show up as a compile time error, and | |
30019 | the fix is usually simply to add the @code{(<>)} to the generic declaration. | |
30020 | @end itemize | |
30021 | ||
30022 | @node More deterministic semantics,Changed semantics,Legal Ada 83 programs that are illegal in Ada 95,Compatibility with Ada 83 | |
73918baf | 30023 | @anchor{gnat_rm/compatibility_and_porting_guide id5}@anchor{45c}@anchor{gnat_rm/compatibility_and_porting_guide more-deterministic-semantics}@anchor{45d} |
64d5610f ML |
30024 | @subsection More deterministic semantics |
30025 | ||
30026 | ||
30027 | ||
30028 | @itemize * | |
30029 | ||
30030 | @item | |
30031 | `Conversions' | |
30032 | ||
30033 | Conversions from real types to integer types round away from 0. In Ada 83 | |
30034 | the conversion Integer(2.5) could deliver either 2 or 3 as its value. This | |
30035 | implementation freedom was intended to support unbiased rounding in | |
30036 | statistical applications, but in practice it interfered with portability. | |
30037 | In Ada 95 the conversion semantics are unambiguous, and rounding away from 0 | |
30038 | is required. Numeric code may be affected by this change in semantics. | |
30039 | Note, though, that this issue is no worse than already existed in Ada 83 | |
30040 | when porting code from one vendor to another. | |
30041 | ||
30042 | @item | |
30043 | `Tasking' | |
30044 | ||
30045 | The Real-Time Annex introduces a set of policies that define the behavior of | |
30046 | features that were implementation dependent in Ada 83, such as the order in | |
30047 | which open select branches are executed. | |
30048 | @end itemize | |
30049 | ||
30050 | @node Changed semantics,Other language compatibility issues,More deterministic semantics,Compatibility with Ada 83 | |
73918baf | 30051 | @anchor{gnat_rm/compatibility_and_porting_guide changed-semantics}@anchor{45e}@anchor{gnat_rm/compatibility_and_porting_guide id6}@anchor{45f} |
64d5610f ML |
30052 | @subsection Changed semantics |
30053 | ||
30054 | ||
30055 | The worst kind of incompatibility is one where a program that is legal in | |
30056 | Ada 83 is also legal in Ada 95 but can have an effect in Ada 95 that was not | |
30057 | possible in Ada 83. Fortunately this is extremely rare, but the one | |
30058 | situation that you should be alert to is the change in the predefined type | |
30059 | @code{Character} from 7-bit ASCII to 8-bit Latin-1. | |
30060 | ||
30061 | @quotation | |
30062 | ||
30063 | @geindex Latin-1 | |
30064 | @end quotation | |
30065 | ||
30066 | ||
30067 | @itemize * | |
30068 | ||
30069 | @item | |
30070 | `Range of type `@w{`}Character`@w{`}' | |
30071 | ||
30072 | The range of @code{Standard.Character} is now the full 256 characters | |
30073 | of Latin-1, whereas in most Ada 83 implementations it was restricted | |
30074 | to 128 characters. Although some of the effects of | |
30075 | this change will be manifest in compile-time rejection of legal | |
30076 | Ada 83 programs it is possible for a working Ada 83 program to have | |
30077 | a different effect in Ada 95, one that was not permitted in Ada 83. | |
30078 | As an example, the expression | |
30079 | @code{Character'Pos(Character'Last)} returned @code{127} in Ada 83 and now | |
30080 | delivers @code{255} as its value. | |
30081 | In general, you should look at the logic of any | |
30082 | character-processing Ada 83 program and see whether it needs to be adapted | |
30083 | to work correctly with Latin-1. Note that the predefined Ada 95 API has a | |
30084 | character handling package that may be relevant if code needs to be adapted | |
30085 | to account for the additional Latin-1 elements. | |
30086 | The desirable fix is to | |
30087 | modify the program to accommodate the full character set, but in some cases | |
30088 | it may be convenient to define a subtype or derived type of Character that | |
30089 | covers only the restricted range. | |
30090 | @end itemize | |
30091 | ||
30092 | @node Other language compatibility issues,,Changed semantics,Compatibility with Ada 83 | |
73918baf | 30093 | @anchor{gnat_rm/compatibility_and_porting_guide id7}@anchor{460}@anchor{gnat_rm/compatibility_and_porting_guide other-language-compatibility-issues}@anchor{461} |
64d5610f ML |
30094 | @subsection Other language compatibility issues |
30095 | ||
30096 | ||
30097 | ||
30098 | @itemize * | |
30099 | ||
30100 | @item | |
30101 | `-gnat83' switch | |
30102 | ||
30103 | All implementations of GNAT provide a switch that causes GNAT to operate | |
30104 | in Ada 83 mode. In this mode, some but not all compatibility problems | |
30105 | of the type described above are handled automatically. For example, the | |
30106 | new reserved words introduced in Ada 95 and Ada 2005 are treated simply | |
30107 | as identifiers as in Ada 83. However, | |
30108 | in practice, it is usually advisable to make the necessary modifications | |
30109 | to the program to remove the need for using this switch. | |
30110 | See the @code{Compiling Different Versions of Ada} section in | |
30111 | the @cite{GNAT User’s Guide}. | |
30112 | ||
30113 | @item | |
30114 | Support for removed Ada 83 pragmas and attributes | |
30115 | ||
30116 | A number of pragmas and attributes from Ada 83 were removed from Ada 95, | |
30117 | generally because they were replaced by other mechanisms. Ada 95 and Ada 2005 | |
30118 | compilers are allowed, but not required, to implement these missing | |
30119 | elements. In contrast with some other compilers, GNAT implements all | |
30120 | such pragmas and attributes, eliminating this compatibility concern. These | |
30121 | include @code{pragma Interface} and the floating point type attributes | |
30122 | (@code{Emax}, @code{Mantissa}, etc.), among other items. | |
30123 | @end itemize | |
30124 | ||
30125 | @node Compatibility between Ada 95 and Ada 2005,Implementation-dependent characteristics,Compatibility with Ada 83,Compatibility and Porting Guide | |
73918baf | 30126 | @anchor{gnat_rm/compatibility_and_porting_guide compatibility-between-ada-95-and-ada-2005}@anchor{462}@anchor{gnat_rm/compatibility_and_porting_guide id8}@anchor{463} |
64d5610f ML |
30127 | @section Compatibility between Ada 95 and Ada 2005 |
30128 | ||
30129 | ||
30130 | @geindex Compatibility between Ada 95 and Ada 2005 | |
30131 | ||
30132 | Although Ada 2005 was designed to be upwards compatible with Ada 95, there are | |
30133 | a number of incompatibilities. Several are enumerated below; | |
30134 | for a complete description please see the | |
30135 | @cite{Annotated Ada 2005 Reference Manual}, or section 9.1.1 in | |
30136 | @cite{Rationale for Ada 2005}. | |
30137 | ||
30138 | ||
30139 | @itemize * | |
30140 | ||
30141 | @item | |
30142 | `New reserved words.' | |
30143 | ||
30144 | The words @code{interface}, @code{overriding} and @code{synchronized} are | |
30145 | reserved in Ada 2005. | |
30146 | A pre-Ada 2005 program that uses any of these as an identifier will be | |
30147 | illegal. | |
30148 | ||
30149 | @item | |
30150 | `New declarations in predefined packages.' | |
30151 | ||
30152 | A number of packages in the predefined environment contain new declarations: | |
30153 | @code{Ada.Exceptions}, @code{Ada.Real_Time}, @code{Ada.Strings}, | |
30154 | @code{Ada.Strings.Fixed}, @code{Ada.Strings.Bounded}, | |
30155 | @code{Ada.Strings.Unbounded}, @code{Ada.Strings.Wide_Fixed}, | |
30156 | @code{Ada.Strings.Wide_Bounded}, @code{Ada.Strings.Wide_Unbounded}, | |
30157 | @code{Ada.Tags}, @code{Ada.Text_IO}, and @code{Interfaces.C}. | |
30158 | If an Ada 95 program does a @code{with} and @code{use} of any of these | |
30159 | packages, the new declarations may cause name clashes. | |
30160 | ||
30161 | @item | |
30162 | `Access parameters.' | |
30163 | ||
30164 | A nondispatching subprogram with an access parameter cannot be renamed | |
30165 | as a dispatching operation. This was permitted in Ada 95. | |
30166 | ||
30167 | @item | |
30168 | `Access types, discriminants, and constraints.' | |
30169 | ||
30170 | Rule changes in this area have led to some incompatibilities; for example, | |
30171 | constrained subtypes of some access types are not permitted in Ada 2005. | |
30172 | ||
30173 | @item | |
30174 | `Aggregates for limited types.' | |
30175 | ||
30176 | The allowance of aggregates for limited types in Ada 2005 raises the | |
30177 | possibility of ambiguities in legal Ada 95 programs, since additional types | |
30178 | now need to be considered in expression resolution. | |
30179 | ||
30180 | @item | |
30181 | `Fixed-point multiplication and division.' | |
30182 | ||
30183 | Certain expressions involving ‘*’ or ‘/’ for a fixed-point type, which | |
30184 | were legal in Ada 95 and invoked the predefined versions of these operations, | |
30185 | are now ambiguous. | |
30186 | The ambiguity may be resolved either by applying a type conversion to the | |
30187 | expression, or by explicitly invoking the operation from package | |
30188 | @code{Standard}. | |
30189 | ||
30190 | @item | |
30191 | `Return-by-reference types.' | |
30192 | ||
30193 | The Ada 95 return-by-reference mechanism has been removed. Instead, the user | |
30194 | can declare a function returning a value from an anonymous access type. | |
30195 | @end itemize | |
30196 | ||
30197 | @node Implementation-dependent characteristics,Compatibility with Other Ada Systems,Compatibility between Ada 95 and Ada 2005,Compatibility and Porting Guide | |
73918baf | 30198 | @anchor{gnat_rm/compatibility_and_porting_guide id9}@anchor{464}@anchor{gnat_rm/compatibility_and_porting_guide implementation-dependent-characteristics}@anchor{465} |
64d5610f ML |
30199 | @section Implementation-dependent characteristics |
30200 | ||
30201 | ||
30202 | Although the Ada language defines the semantics of each construct as | |
30203 | precisely as practical, in some situations (for example for reasons of | |
30204 | efficiency, or where the effect is heavily dependent on the host or target | |
30205 | platform) the implementation is allowed some freedom. In porting Ada 83 | |
30206 | code to GNAT, you need to be aware of whether / how the existing code | |
30207 | exercised such implementation dependencies. Such characteristics fall into | |
30208 | several categories, and GNAT offers specific support in assisting the | |
30209 | transition from certain Ada 83 compilers. | |
30210 | ||
30211 | @menu | |
30212 | * Implementation-defined pragmas:: | |
30213 | * Implementation-defined attributes:: | |
30214 | * Libraries:: | |
30215 | * Elaboration order:: | |
30216 | * Target-specific aspects:: | |
30217 | ||
30218 | @end menu | |
30219 | ||
30220 | @node Implementation-defined pragmas,Implementation-defined attributes,,Implementation-dependent characteristics | |
73918baf | 30221 | @anchor{gnat_rm/compatibility_and_porting_guide id10}@anchor{466}@anchor{gnat_rm/compatibility_and_porting_guide implementation-defined-pragmas}@anchor{467} |
64d5610f ML |
30222 | @subsection Implementation-defined pragmas |
30223 | ||
30224 | ||
30225 | Ada compilers are allowed to supplement the language-defined pragmas, and | |
30226 | these are a potential source of non-portability. All GNAT-defined pragmas | |
30227 | are described in @ref{7,,Implementation Defined Pragmas}, | |
30228 | and these include several that are specifically | |
30229 | intended to correspond to other vendors’ Ada 83 pragmas. | |
30230 | For migrating from VADS, the pragma @code{Use_VADS_Size} may be useful. | |
30231 | For compatibility with HP Ada 83, GNAT supplies the pragmas | |
30232 | @code{Extend_System}, @code{Ident}, @code{Inline_Generic}, | |
30233 | @code{Interface_Name}, @code{Passive}, @code{Suppress_All}, | |
30234 | and @code{Volatile}. | |
30235 | Other relevant pragmas include @code{External} and @code{Link_With}. | |
30236 | Some vendor-specific | |
30237 | Ada 83 pragmas (@code{Share_Generic}, @code{Subtitle}, and @code{Title}) are | |
30238 | recognized, thus | |
30239 | avoiding compiler rejection of units that contain such pragmas; they are not | |
30240 | relevant in a GNAT context and hence are not otherwise implemented. | |
30241 | ||
30242 | @node Implementation-defined attributes,Libraries,Implementation-defined pragmas,Implementation-dependent characteristics | |
73918baf | 30243 | @anchor{gnat_rm/compatibility_and_porting_guide id11}@anchor{468}@anchor{gnat_rm/compatibility_and_porting_guide implementation-defined-attributes}@anchor{469} |
64d5610f ML |
30244 | @subsection Implementation-defined attributes |
30245 | ||
30246 | ||
30247 | Analogous to pragmas, the set of attributes may be extended by an | |
30248 | implementation. All GNAT-defined attributes are described in | |
30249 | @ref{8,,Implementation Defined Attributes}, | |
30250 | and these include several that are specifically intended | |
30251 | to correspond to other vendors’ Ada 83 attributes. For migrating from VADS, | |
30252 | the attribute @code{VADS_Size} may be useful. For compatibility with HP | |
30253 | Ada 83, GNAT supplies the attributes @code{Bit}, @code{Machine_Size} and | |
30254 | @code{Type_Class}. | |
30255 | ||
30256 | @node Libraries,Elaboration order,Implementation-defined attributes,Implementation-dependent characteristics | |
73918baf | 30257 | @anchor{gnat_rm/compatibility_and_porting_guide id12}@anchor{46a}@anchor{gnat_rm/compatibility_and_porting_guide libraries}@anchor{46b} |
64d5610f ML |
30258 | @subsection Libraries |
30259 | ||
30260 | ||
30261 | Vendors may supply libraries to supplement the standard Ada API. If Ada 83 | |
30262 | code uses vendor-specific libraries then there are several ways to manage | |
30263 | this in Ada 95 and later versions of the standard: | |
30264 | ||
30265 | ||
30266 | @itemize * | |
30267 | ||
30268 | @item | |
30269 | If the source code for the libraries (specs and bodies) are | |
30270 | available, then the libraries can be migrated in the same way as the | |
30271 | application. | |
30272 | ||
30273 | @item | |
30274 | If the source code for the specs but not the bodies are | |
30275 | available, then you can reimplement the bodies. | |
30276 | ||
30277 | @item | |
30278 | Some features introduced by Ada 95 obviate the need for library support. For | |
30279 | example most Ada 83 vendors supplied a package for unsigned integers. The | |
30280 | Ada 95 modular type feature is the preferred way to handle this need, so | |
30281 | instead of migrating or reimplementing the unsigned integer package it may | |
30282 | be preferable to retrofit the application using modular types. | |
30283 | @end itemize | |
30284 | ||
30285 | @node Elaboration order,Target-specific aspects,Libraries,Implementation-dependent characteristics | |
73918baf | 30286 | @anchor{gnat_rm/compatibility_and_porting_guide elaboration-order}@anchor{46c}@anchor{gnat_rm/compatibility_and_porting_guide id13}@anchor{46d} |
64d5610f ML |
30287 | @subsection Elaboration order |
30288 | ||
30289 | ||
30290 | The implementation can choose any elaboration order consistent with the unit | |
30291 | dependency relationship. This freedom means that some orders can result in | |
30292 | Program_Error being raised due to an ‘Access Before Elaboration’: an attempt | |
30293 | to invoke a subprogram before its body has been elaborated, or to instantiate | |
30294 | a generic before the generic body has been elaborated. By default GNAT | |
30295 | attempts to choose a safe order (one that will not encounter access before | |
30296 | elaboration problems) by implicitly inserting @code{Elaborate} or | |
30297 | @code{Elaborate_All} pragmas where | |
30298 | needed. However, this can lead to the creation of elaboration circularities | |
30299 | and a resulting rejection of the program by gnatbind. This issue is | |
30300 | thoroughly described in the `Elaboration Order Handling in GNAT' appendix | |
30301 | in the @cite{GNAT User’s Guide}. | |
30302 | In brief, there are several | |
30303 | ways to deal with this situation: | |
30304 | ||
30305 | ||
30306 | @itemize * | |
30307 | ||
30308 | @item | |
30309 | Modify the program to eliminate the circularities, e.g., by moving | |
30310 | elaboration-time code into explicitly-invoked procedures | |
30311 | ||
30312 | @item | |
30313 | Constrain the elaboration order by including explicit @code{Elaborate_Body} or | |
30314 | @code{Elaborate} pragmas, and then inhibit the generation of implicit | |
30315 | @code{Elaborate_All} | |
30316 | pragmas either globally (as an effect of the `-gnatE' switch) or locally | |
30317 | (by selectively suppressing elaboration checks via pragma | |
30318 | @code{Suppress(Elaboration_Check)} when it is safe to do so). | |
30319 | @end itemize | |
30320 | ||
30321 | @node Target-specific aspects,,Elaboration order,Implementation-dependent characteristics | |
73918baf | 30322 | @anchor{gnat_rm/compatibility_and_porting_guide id14}@anchor{46e}@anchor{gnat_rm/compatibility_and_porting_guide target-specific-aspects}@anchor{46f} |
64d5610f ML |
30323 | @subsection Target-specific aspects |
30324 | ||
30325 | ||
30326 | Low-level applications need to deal with machine addresses, data | |
30327 | representations, interfacing with assembler code, and similar issues. If | |
30328 | such an Ada 83 application is being ported to different target hardware (for | |
30329 | example where the byte endianness has changed) then you will need to | |
30330 | carefully examine the program logic; the porting effort will heavily depend | |
30331 | on the robustness of the original design. Moreover, Ada 95 (and thus | |
30332 | Ada 2005 and Ada 2012) are sometimes | |
30333 | incompatible with typical Ada 83 compiler practices regarding implicit | |
30334 | packing, the meaning of the Size attribute, and the size of access values. | |
73918baf | 30335 | GNAT’s approach to these issues is described in @ref{470,,Representation Clauses}. |
64d5610f ML |
30336 | |
30337 | @node Compatibility with Other Ada Systems,Representation Clauses,Implementation-dependent characteristics,Compatibility and Porting Guide | |
73918baf | 30338 | @anchor{gnat_rm/compatibility_and_porting_guide compatibility-with-other-ada-systems}@anchor{471}@anchor{gnat_rm/compatibility_and_porting_guide id15}@anchor{472} |
64d5610f ML |
30339 | @section Compatibility with Other Ada Systems |
30340 | ||
30341 | ||
30342 | If programs avoid the use of implementation dependent and | |
30343 | implementation defined features, as documented in the | |
30344 | @cite{Ada Reference Manual}, there should be a high degree of portability between | |
30345 | GNAT and other Ada systems. The following are specific items which | |
30346 | have proved troublesome in moving Ada 95 programs from GNAT to other Ada 95 | |
30347 | compilers, but do not affect porting code to GNAT. | |
30348 | (As of January 2007, GNAT is the only compiler available for Ada 2005; | |
30349 | the following issues may or may not arise for Ada 2005 programs | |
30350 | when other compilers appear.) | |
30351 | ||
30352 | ||
30353 | @itemize * | |
30354 | ||
30355 | @item | |
30356 | `Ada 83 Pragmas and Attributes' | |
30357 | ||
30358 | Ada 95 compilers are allowed, but not required, to implement the missing | |
30359 | Ada 83 pragmas and attributes that are no longer defined in Ada 95. | |
30360 | GNAT implements all such pragmas and attributes, eliminating this as | |
30361 | a compatibility concern, but some other Ada 95 compilers reject these | |
30362 | pragmas and attributes. | |
30363 | ||
30364 | @item | |
30365 | `Specialized Needs Annexes' | |
30366 | ||
30367 | GNAT implements the full set of special needs annexes. At the | |
30368 | current time, it is the only Ada 95 compiler to do so. This means that | |
30369 | programs making use of these features may not be portable to other Ada | |
30370 | 95 compilation systems. | |
30371 | ||
30372 | @item | |
30373 | `Representation Clauses' | |
30374 | ||
30375 | Some other Ada 95 compilers implement only the minimal set of | |
30376 | representation clauses required by the Ada 95 reference manual. GNAT goes | |
30377 | far beyond this minimal set, as described in the next section. | |
30378 | @end itemize | |
30379 | ||
30380 | @node Representation Clauses,Compatibility with HP Ada 83,Compatibility with Other Ada Systems,Compatibility and Porting Guide | |
73918baf | 30381 | @anchor{gnat_rm/compatibility_and_porting_guide id16}@anchor{473}@anchor{gnat_rm/compatibility_and_porting_guide representation-clauses}@anchor{470} |
64d5610f ML |
30382 | @section Representation Clauses |
30383 | ||
30384 | ||
30385 | The Ada 83 reference manual was quite vague in describing both the minimal | |
30386 | required implementation of representation clauses, and also their precise | |
30387 | effects. Ada 95 (and thus also Ada 2005) are much more explicit, but the | |
30388 | minimal set of capabilities required is still quite limited. | |
30389 | ||
30390 | GNAT implements the full required set of capabilities in | |
30391 | Ada 95 and Ada 2005, but also goes much further, and in particular | |
30392 | an effort has been made to be compatible with existing Ada 83 usage to the | |
30393 | greatest extent possible. | |
30394 | ||
30395 | A few cases exist in which Ada 83 compiler behavior is incompatible with | |
30396 | the requirements in Ada 95 (and thus also Ada 2005). These are instances of | |
30397 | intentional or accidental dependence on specific implementation dependent | |
30398 | characteristics of these Ada 83 compilers. The following is a list of | |
30399 | the cases most likely to arise in existing Ada 83 code. | |
30400 | ||
30401 | ||
30402 | @itemize * | |
30403 | ||
30404 | @item | |
30405 | `Implicit Packing' | |
30406 | ||
30407 | Some Ada 83 compilers allowed a Size specification to cause implicit | |
30408 | packing of an array or record. This could cause expensive implicit | |
30409 | conversions for change of representation in the presence of derived | |
30410 | types, and the Ada design intends to avoid this possibility. | |
30411 | Subsequent AI’s were issued to make it clear that such implicit | |
30412 | change of representation in response to a Size clause is inadvisable, | |
30413 | and this recommendation is represented explicitly in the Ada 95 (and Ada 2005) | |
30414 | Reference Manuals as implementation advice that is followed by GNAT. | |
30415 | The problem will show up as an error | |
30416 | message rejecting the size clause. The fix is simply to provide | |
30417 | the explicit pragma @code{Pack}, or for more fine tuned control, provide | |
30418 | a Component_Size clause. | |
30419 | ||
30420 | @item | |
30421 | `Meaning of Size Attribute' | |
30422 | ||
30423 | The Size attribute in Ada 95 (and Ada 2005) for discrete types is defined as | |
30424 | the minimal number of bits required to hold values of the type. For example, | |
30425 | on a 32-bit machine, the size of @code{Natural} will typically be 31 and not | |
30426 | 32 (since no sign bit is required). Some Ada 83 compilers gave 31, and | |
30427 | some 32 in this situation. This problem will usually show up as a compile | |
30428 | time error, but not always. It is a good idea to check all uses of the | |
30429 | ‘Size attribute when porting Ada 83 code. The GNAT specific attribute | |
30430 | Object_Size can provide a useful way of duplicating the behavior of | |
30431 | some Ada 83 compiler systems. | |
30432 | ||
30433 | @item | |
30434 | `Size of Access Types' | |
30435 | ||
30436 | A common assumption in Ada 83 code is that an access type is in fact a pointer, | |
30437 | and that therefore it will be the same size as a System.Address value. This | |
30438 | assumption is true for GNAT in most cases with one exception. For the case of | |
30439 | a pointer to an unconstrained array type (where the bounds may vary from one | |
30440 | value of the access type to another), the default is to use a ‘fat pointer’, | |
30441 | which is represented as two separate pointers, one to the bounds, and one to | |
30442 | the array. This representation has a number of advantages, including improved | |
30443 | efficiency. However, it may cause some difficulties in porting existing Ada 83 | |
30444 | code which makes the assumption that, for example, pointers fit in 32 bits on | |
30445 | a machine with 32-bit addressing. | |
30446 | ||
30447 | To get around this problem, GNAT also permits the use of ‘thin pointers’ for | |
30448 | access types in this case (where the designated type is an unconstrained array | |
30449 | type). These thin pointers are indeed the same size as a System.Address value. | |
30450 | To specify a thin pointer, use a size clause for the type, for example: | |
30451 | ||
30452 | @example | |
30453 | type X is access all String; | |
30454 | for X'Size use Standard'Address_Size; | |
30455 | @end example | |
30456 | ||
30457 | which will cause the type X to be represented using a single pointer. | |
30458 | When using this representation, the bounds are right behind the array. | |
30459 | This representation is slightly less efficient, and does not allow quite | |
30460 | such flexibility in the use of foreign pointers or in using the | |
30461 | Unrestricted_Access attribute to create pointers to non-aliased objects. | |
30462 | But for any standard portable use of the access type it will work in | |
30463 | a functionally correct manner and allow porting of existing code. | |
30464 | Note that another way of forcing a thin pointer representation | |
30465 | is to use a component size clause for the element size in an array, | |
30466 | or a record representation clause for an access field in a record. | |
30467 | ||
30468 | See the documentation of Unrestricted_Access in the GNAT RM for a | |
30469 | full discussion of possible problems using this attribute in conjunction | |
30470 | with thin pointers. | |
30471 | @end itemize | |
30472 | ||
30473 | @node Compatibility with HP Ada 83,,Representation Clauses,Compatibility and Porting Guide | |
73918baf | 30474 | @anchor{gnat_rm/compatibility_and_porting_guide compatibility-with-hp-ada-83}@anchor{474}@anchor{gnat_rm/compatibility_and_porting_guide id17}@anchor{475} |
64d5610f ML |
30475 | @section Compatibility with HP Ada 83 |
30476 | ||
30477 | ||
30478 | All the HP Ada 83 pragmas and attributes are recognized, although only a subset | |
30479 | of them can sensibly be implemented. The description of pragmas in | |
30480 | @ref{7,,Implementation Defined Pragmas} indicates whether or not they are | |
30481 | applicable to GNAT. | |
30482 | ||
30483 | ||
30484 | @itemize * | |
30485 | ||
30486 | @item | |
30487 | `Default floating-point representation' | |
30488 | ||
30489 | In GNAT, the default floating-point format is IEEE, whereas in HP Ada 83, | |
30490 | it is VMS format. | |
30491 | ||
30492 | @item | |
30493 | `System' | |
30494 | ||
30495 | the package System in GNAT exactly corresponds to the definition in the | |
30496 | Ada 95 reference manual, which means that it excludes many of the | |
30497 | HP Ada 83 extensions. However, a separate package Aux_DEC is provided | |
30498 | that contains the additional definitions, and a special pragma, | |
30499 | Extend_System allows this package to be treated transparently as an | |
30500 | extension of package System. | |
30501 | @end itemize | |
30502 | ||
30503 | @node GNU Free Documentation License,Index,Compatibility and Porting Guide,Top | |
73918baf | 30504 | @anchor{share/gnu_free_documentation_license doc}@anchor{476}@anchor{share/gnu_free_documentation_license gnu-fdl}@anchor{1}@anchor{share/gnu_free_documentation_license gnu-free-documentation-license}@anchor{477} |
64d5610f ML |
30505 | @chapter GNU Free Documentation License |
30506 | ||
30507 | ||
30508 | Version 1.3, 3 November 2008 | |
30509 | ||
30510 | Copyright 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc | |
30511 | @indicateurl{https://fsf.org/} | |
30512 | ||
30513 | Everyone is permitted to copy and distribute verbatim copies of this | |
30514 | license document, but changing it is not allowed. | |
30515 | ||
30516 | `Preamble' | |
30517 | ||
30518 | The purpose of this License is to make a manual, textbook, or other | |
30519 | functional and useful document “free” in the sense of freedom: to | |
30520 | assure everyone the effective freedom to copy and redistribute it, | |
30521 | with or without modifying it, either commercially or noncommercially. | |
30522 | Secondarily, this License preserves for the author and publisher a way | |
30523 | to get credit for their work, while not being considered responsible | |
30524 | for modifications made by others. | |
30525 | ||
30526 | This License is a kind of “copyleft”, which means that derivative | |
30527 | works of the document must themselves be free in the same sense. It | |
30528 | complements the GNU General Public License, which is a copyleft | |
30529 | license designed for free software. | |
30530 | ||
30531 | We have designed this License in order to use it for manuals for free | |
30532 | software, because free software needs free documentation: a free | |
30533 | program should come with manuals providing the same freedoms that the | |
30534 | software does. But this License is not limited to software manuals; | |
30535 | it can be used for any textual work, regardless of subject matter or | |
30536 | whether it is published as a printed book. We recommend this License | |
30537 | principally for works whose purpose is instruction or reference. | |
30538 | ||
30539 | `1. APPLICABILITY AND DEFINITIONS' | |
30540 | ||
30541 | This License applies to any manual or other work, in any medium, that | |
30542 | contains a notice placed by the copyright holder saying it can be | |
30543 | distributed under the terms of this License. Such a notice grants a | |
30544 | world-wide, royalty-free license, unlimited in duration, to use that | |
30545 | work under the conditions stated herein. The `Document', below, | |
30546 | refers to any such manual or work. Any member of the public is a | |
30547 | licensee, and is addressed as “`you'”. You accept the license if you | |
30548 | copy, modify or distribute the work in a way requiring permission | |
30549 | under copyright law. | |
30550 | ||
30551 | A “`Modified Version'” of the Document means any work containing the | |
30552 | Document or a portion of it, either copied verbatim, or with | |
30553 | modifications and/or translated into another language. | |
30554 | ||
30555 | A “`Secondary Section'” is a named appendix or a front-matter section of | |
30556 | the Document that deals exclusively with the relationship of the | |
30557 | publishers or authors of the Document to the Document’s overall subject | |
30558 | (or to related matters) and contains nothing that could fall directly | |
30559 | within that overall subject. (Thus, if the Document is in part a | |
30560 | textbook of mathematics, a Secondary Section may not explain any | |
30561 | mathematics.) The relationship could be a matter of historical | |
30562 | connection with the subject or with related matters, or of legal, | |
30563 | commercial, philosophical, ethical or political position regarding | |
30564 | them. | |
30565 | ||
30566 | The “`Invariant Sections'” are certain Secondary Sections whose titles | |
30567 | are designated, as being those of Invariant Sections, in the notice | |
30568 | that says that the Document is released under this License. If a | |
30569 | section does not fit the above definition of Secondary then it is not | |
30570 | allowed to be designated as Invariant. The Document may contain zero | |
30571 | Invariant Sections. If the Document does not identify any Invariant | |
30572 | Sections then there are none. | |
30573 | ||
30574 | The “`Cover Texts'” are certain short passages of text that are listed, | |
30575 | as Front-Cover Texts or Back-Cover Texts, in the notice that says that | |
30576 | the Document is released under this License. A Front-Cover Text may | |
30577 | be at most 5 words, and a Back-Cover Text may be at most 25 words. | |
30578 | ||
30579 | A “`Transparent'” copy of the Document means a machine-readable copy, | |
30580 | represented in a format whose specification is available to the | |
30581 | general public, that is suitable for revising the document | |
30582 | straightforwardly with generic text editors or (for images composed of | |
30583 | pixels) generic paint programs or (for drawings) some widely available | |
30584 | drawing editor, and that is suitable for input to text formatters or | |
30585 | for automatic translation to a variety of formats suitable for input | |
30586 | to text formatters. A copy made in an otherwise Transparent file | |
30587 | format whose markup, or absence of markup, has been arranged to thwart | |
30588 | or discourage subsequent modification by readers is not Transparent. | |
30589 | An image format is not Transparent if used for any substantial amount | |
30590 | of text. A copy that is not “Transparent” is called `Opaque'. | |
30591 | ||
30592 | Examples of suitable formats for Transparent copies include plain | |
30593 | ASCII without markup, Texinfo input format, LaTeX input format, SGML | |
30594 | or XML using a publicly available DTD, and standard-conforming simple | |
30595 | HTML, PostScript or PDF designed for human modification. Examples of | |
30596 | transparent image formats include PNG, XCF and JPG. Opaque formats | |
30597 | include proprietary formats that can be read and edited only by | |
30598 | proprietary word processors, SGML or XML for which the DTD and/or | |
30599 | processing tools are not generally available, and the | |
30600 | machine-generated HTML, PostScript or PDF produced by some word | |
30601 | processors for output purposes only. | |
30602 | ||
30603 | The “`Title Page'” means, for a printed book, the title page itself, | |
30604 | plus such following pages as are needed to hold, legibly, the material | |
30605 | this License requires to appear in the title page. For works in | |
30606 | formats which do not have any title page as such, “Title Page” means | |
30607 | the text near the most prominent appearance of the work’s title, | |
30608 | preceding the beginning of the body of the text. | |
30609 | ||
30610 | The “`publisher'” means any person or entity that distributes | |
30611 | copies of the Document to the public. | |
30612 | ||
30613 | A section “`Entitled XYZ'” means a named subunit of the Document whose | |
30614 | title either is precisely XYZ or contains XYZ in parentheses following | |
30615 | text that translates XYZ in another language. (Here XYZ stands for a | |
30616 | specific section name mentioned below, such as “`Acknowledgements'”, | |
30617 | “`Dedications'”, “`Endorsements'”, or “`History'”.) | |
30618 | To “`Preserve the Title'” | |
30619 | of such a section when you modify the Document means that it remains a | |
30620 | section “Entitled XYZ” according to this definition. | |
30621 | ||
30622 | The Document may include Warranty Disclaimers next to the notice which | |
30623 | states that this License applies to the Document. These Warranty | |
30624 | Disclaimers are considered to be included by reference in this | |
30625 | License, but only as regards disclaiming warranties: any other | |
30626 | implication that these Warranty Disclaimers may have is void and has | |
30627 | no effect on the meaning of this License. | |
30628 | ||
30629 | `2. VERBATIM COPYING' | |
30630 | ||
30631 | You may copy and distribute the Document in any medium, either | |
30632 | commercially or noncommercially, provided that this License, the | |
30633 | copyright notices, and the license notice saying this License applies | |
30634 | to the Document are reproduced in all copies, and that you add no other | |
30635 | conditions whatsoever to those of this License. You may not use | |
30636 | technical measures to obstruct or control the reading or further | |
30637 | copying of the copies you make or distribute. However, you may accept | |
30638 | compensation in exchange for copies. If you distribute a large enough | |
30639 | number of copies you must also follow the conditions in section 3. | |
30640 | ||
30641 | You may also lend copies, under the same conditions stated above, and | |
30642 | you may publicly display copies. | |
30643 | ||
30644 | `3. COPYING IN QUANTITY' | |
30645 | ||
30646 | If you publish printed copies (or copies in media that commonly have | |
30647 | printed covers) of the Document, numbering more than 100, and the | |
30648 | Document’s license notice requires Cover Texts, you must enclose the | |
30649 | copies in covers that carry, clearly and legibly, all these Cover | |
30650 | Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on | |
30651 | the back cover. Both covers must also clearly and legibly identify | |
30652 | you as the publisher of these copies. The front cover must present | |
30653 | the full title with all words of the title equally prominent and | |
30654 | visible. You may add other material on the covers in addition. | |
30655 | Copying with changes limited to the covers, as long as they preserve | |
30656 | the title of the Document and satisfy these conditions, can be treated | |
30657 | as verbatim copying in other respects. | |
30658 | ||
30659 | If the required texts for either cover are too voluminous to fit | |
30660 | legibly, you should put the first ones listed (as many as fit | |
30661 | reasonably) on the actual cover, and continue the rest onto adjacent | |
30662 | pages. | |
30663 | ||
30664 | If you publish or distribute Opaque copies of the Document numbering | |
30665 | more than 100, you must either include a machine-readable Transparent | |
30666 | copy along with each Opaque copy, or state in or with each Opaque copy | |
30667 | a computer-network location from which the general network-using | |
30668 | public has access to download using public-standard network protocols | |
30669 | a complete Transparent copy of the Document, free of added material. | |
30670 | If you use the latter option, you must take reasonably prudent steps, | |
30671 | when you begin distribution of Opaque copies in quantity, to ensure | |
30672 | that this Transparent copy will remain thus accessible at the stated | |
30673 | location until at least one year after the last time you distribute an | |
30674 | Opaque copy (directly or through your agents or retailers) of that | |
30675 | edition to the public. | |
30676 | ||
30677 | It is requested, but not required, that you contact the authors of the | |
30678 | Document well before redistributing any large number of copies, to give | |
30679 | them a chance to provide you with an updated version of the Document. | |
30680 | ||
30681 | `4. MODIFICATIONS' | |
30682 | ||
30683 | You may copy and distribute a Modified Version of the Document under | |
30684 | the conditions of sections 2 and 3 above, provided that you release | |
30685 | the Modified Version under precisely this License, with the Modified | |
30686 | Version filling the role of the Document, thus licensing distribution | |
30687 | and modification of the Modified Version to whoever possesses a copy | |
30688 | of it. In addition, you must do these things in the Modified Version: | |
30689 | ||
30690 | ||
30691 | @enumerate A | |
30692 | ||
30693 | @item | |
30694 | Use in the Title Page (and on the covers, if any) a title distinct | |
30695 | from that of the Document, and from those of previous versions | |
30696 | (which should, if there were any, be listed in the History section | |
30697 | of the Document). You may use the same title as a previous version | |
30698 | if the original publisher of that version gives permission. | |
30699 | ||
30700 | @item | |
30701 | List on the Title Page, as authors, one or more persons or entities | |
30702 | responsible for authorship of the modifications in the Modified | |
30703 | Version, together with at least five of the principal authors of the | |
30704 | Document (all of its principal authors, if it has fewer than five), | |
30705 | unless they release you from this requirement. | |
30706 | ||
30707 | @item | |
30708 | State on the Title page the name of the publisher of the | |
30709 | Modified Version, as the publisher. | |
30710 | ||
30711 | @item | |
30712 | Preserve all the copyright notices of the Document. | |
30713 | ||
30714 | @item | |
30715 | Add an appropriate copyright notice for your modifications | |
30716 | adjacent to the other copyright notices. | |
30717 | ||
30718 | @item | |
30719 | Include, immediately after the copyright notices, a license notice | |
30720 | giving the public permission to use the Modified Version under the | |
30721 | terms of this License, in the form shown in the Addendum below. | |
30722 | ||
30723 | @item | |
30724 | Preserve in that license notice the full lists of Invariant Sections | |
30725 | and required Cover Texts given in the Document’s license notice. | |
30726 | ||
30727 | @item | |
30728 | Include an unaltered copy of this License. | |
30729 | ||
30730 | @item | |
30731 | Preserve the section Entitled “History”, Preserve its Title, and add | |
30732 | to it an item stating at least the title, year, new authors, and | |
30733 | publisher of the Modified Version as given on the Title Page. If | |
30734 | there is no section Entitled “History” in the Document, create one | |
30735 | stating the title, year, authors, and publisher of the Document as | |
30736 | given on its Title Page, then add an item describing the Modified | |
30737 | Version as stated in the previous sentence. | |
30738 | ||
30739 | @item | |
30740 | Preserve the network location, if any, given in the Document for | |
30741 | public access to a Transparent copy of the Document, and likewise | |
30742 | the network locations given in the Document for previous versions | |
30743 | it was based on. These may be placed in the “History” section. | |
30744 | You may omit a network location for a work that was published at | |
30745 | least four years before the Document itself, or if the original | |
30746 | publisher of the version it refers to gives permission. | |
30747 | ||
30748 | @item | |
30749 | For any section Entitled “Acknowledgements” or “Dedications”, | |
30750 | Preserve the Title of the section, and preserve in the section all | |
30751 | the substance and tone of each of the contributor acknowledgements | |
30752 | and/or dedications given therein. | |
30753 | ||
30754 | @item | |
30755 | Preserve all the Invariant Sections of the Document, | |
30756 | unaltered in their text and in their titles. Section numbers | |
30757 | or the equivalent are not considered part of the section titles. | |
30758 | ||
30759 | @item | |
30760 | Delete any section Entitled “Endorsements”. Such a section | |
30761 | may not be included in the Modified Version. | |
30762 | ||
30763 | @item | |
30764 | Do not retitle any existing section to be Entitled “Endorsements” | |
30765 | or to conflict in title with any Invariant Section. | |
30766 | ||
30767 | @item | |
30768 | Preserve any Warranty Disclaimers. | |
30769 | @end enumerate | |
30770 | ||
30771 | If the Modified Version includes new front-matter sections or | |
30772 | appendices that qualify as Secondary Sections and contain no material | |
30773 | copied from the Document, you may at your option designate some or all | |
30774 | of these sections as invariant. To do this, add their titles to the | |
30775 | list of Invariant Sections in the Modified Version’s license notice. | |
30776 | These titles must be distinct from any other section titles. | |
30777 | ||
30778 | You may add a section Entitled “Endorsements”, provided it contains | |
30779 | nothing but endorsements of your Modified Version by various | |
30780 | parties—for example, statements of peer review or that the text has | |
30781 | been approved by an organization as the authoritative definition of a | |
30782 | standard. | |
30783 | ||
30784 | You may add a passage of up to five words as a Front-Cover Text, and a | |
30785 | passage of up to 25 words as a Back-Cover Text, to the end of the list | |
30786 | of Cover Texts in the Modified Version. Only one passage of | |
30787 | Front-Cover Text and one of Back-Cover Text may be added by (or | |
30788 | through arrangements made by) any one entity. If the Document already | |
30789 | includes a cover text for the same cover, previously added by you or | |
30790 | by arrangement made by the same entity you are acting on behalf of, | |
30791 | you may not add another; but you may replace the old one, on explicit | |
30792 | permission from the previous publisher that added the old one. | |
30793 | ||
30794 | The author(s) and publisher(s) of the Document do not by this License | |
30795 | give permission to use their names for publicity for or to assert or | |
30796 | imply endorsement of any Modified Version. | |
30797 | ||
30798 | `5. COMBINING DOCUMENTS' | |
30799 | ||
30800 | You may combine the Document with other documents released under this | |
30801 | License, under the terms defined in section 4 above for modified | |
30802 | versions, provided that you include in the combination all of the | |
30803 | Invariant Sections of all of the original documents, unmodified, and | |
30804 | list them all as Invariant Sections of your combined work in its | |
30805 | license notice, and that you preserve all their Warranty Disclaimers. | |
30806 | ||
30807 | The combined work need only contain one copy of this License, and | |
30808 | multiple identical Invariant Sections may be replaced with a single | |
30809 | copy. If there are multiple Invariant Sections with the same name but | |
30810 | different contents, make the title of each such section unique by | |
30811 | adding at the end of it, in parentheses, the name of the original | |
30812 | author or publisher of that section if known, or else a unique number. | |
30813 | Make the same adjustment to the section titles in the list of | |
30814 | Invariant Sections in the license notice of the combined work. | |
30815 | ||
30816 | In the combination, you must combine any sections Entitled “History” | |
30817 | in the various original documents, forming one section Entitled | |
30818 | “History”; likewise combine any sections Entitled “Acknowledgements”, | |
30819 | and any sections Entitled “Dedications”. You must delete all sections | |
30820 | Entitled “Endorsements”. | |
30821 | ||
30822 | `6. COLLECTIONS OF DOCUMENTS' | |
30823 | ||
30824 | You may make a collection consisting of the Document and other documents | |
30825 | released under this License, and replace the individual copies of this | |
30826 | License in the various documents with a single copy that is included in | |
30827 | the collection, provided that you follow the rules of this License for | |
30828 | verbatim copying of each of the documents in all other respects. | |
30829 | ||
30830 | You may extract a single document from such a collection, and distribute | |
30831 | it individually under this License, provided you insert a copy of this | |
30832 | License into the extracted document, and follow this License in all | |
30833 | other respects regarding verbatim copying of that document. | |
30834 | ||
30835 | `7. AGGREGATION WITH INDEPENDENT WORKS' | |
30836 | ||
30837 | A compilation of the Document or its derivatives with other separate | |
30838 | and independent documents or works, in or on a volume of a storage or | |
30839 | distribution medium, is called an “aggregate” if the copyright | |
30840 | resulting from the compilation is not used to limit the legal rights | |
30841 | of the compilation’s users beyond what the individual works permit. | |
30842 | When the Document is included in an aggregate, this License does not | |
30843 | apply to the other works in the aggregate which are not themselves | |
30844 | derivative works of the Document. | |
30845 | ||
30846 | If the Cover Text requirement of section 3 is applicable to these | |
30847 | copies of the Document, then if the Document is less than one half of | |
30848 | the entire aggregate, the Document’s Cover Texts may be placed on | |
30849 | covers that bracket the Document within the aggregate, or the | |
30850 | electronic equivalent of covers if the Document is in electronic form. | |
30851 | Otherwise they must appear on printed covers that bracket the whole | |
30852 | aggregate. | |
30853 | ||
30854 | `8. TRANSLATION' | |
30855 | ||
30856 | Translation is considered a kind of modification, so you may | |
30857 | distribute translations of the Document under the terms of section 4. | |
30858 | Replacing Invariant Sections with translations requires special | |
30859 | permission from their copyright holders, but you may include | |
30860 | translations of some or all Invariant Sections in addition to the | |
30861 | original versions of these Invariant Sections. You may include a | |
30862 | translation of this License, and all the license notices in the | |
30863 | Document, and any Warranty Disclaimers, provided that you also include | |
30864 | the original English version of this License and the original versions | |
30865 | of those notices and disclaimers. In case of a disagreement between | |
30866 | the translation and the original version of this License or a notice | |
30867 | or disclaimer, the original version will prevail. | |
30868 | ||
30869 | If a section in the Document is Entitled “Acknowledgements”, | |
30870 | “Dedications”, or “History”, the requirement (section 4) to Preserve | |
30871 | its Title (section 1) will typically require changing the actual | |
30872 | title. | |
30873 | ||
30874 | `9. TERMINATION' | |
30875 | ||
30876 | You may not copy, modify, sublicense, or distribute the Document | |
30877 | except as expressly provided under this License. Any attempt | |
30878 | otherwise to copy, modify, sublicense, or distribute it is void, and | |
30879 | will automatically terminate your rights under this License. | |
30880 | ||
30881 | However, if you cease all violation of this License, then your license | |
30882 | from a particular copyright holder is reinstated (a) provisionally, | |
30883 | unless and until the copyright holder explicitly and finally | |
30884 | terminates your license, and (b) permanently, if the copyright holder | |
30885 | fails to notify you of the violation by some reasonable means prior to | |
30886 | 60 days after the cessation. | |
30887 | ||
30888 | Moreover, your license from a particular copyright holder is | |
30889 | reinstated permanently if the copyright holder notifies you of the | |
30890 | violation by some reasonable means, this is the first time you have | |
30891 | received notice of violation of this License (for any work) from that | |
30892 | copyright holder, and you cure the violation prior to 30 days after | |
30893 | your receipt of the notice. | |
30894 | ||
30895 | Termination of your rights under this section does not terminate the | |
30896 | licenses of parties who have received copies or rights from you under | |
30897 | this License. If your rights have been terminated and not permanently | |
30898 | reinstated, receipt of a copy of some or all of the same material does | |
30899 | not give you any rights to use it. | |
30900 | ||
30901 | `10. FUTURE REVISIONS OF THIS LICENSE' | |
30902 | ||
30903 | The Free Software Foundation may publish new, revised versions | |
30904 | of the GNU Free Documentation License from time to time. Such new | |
30905 | versions will be similar in spirit to the present version, but may | |
30906 | differ in detail to address new problems or concerns. See | |
30907 | @indicateurl{https://www.gnu.org/copyleft/}. | |
30908 | ||
30909 | Each version of the License is given a distinguishing version number. | |
30910 | If the Document specifies that a particular numbered version of this | |
30911 | License “or any later version” applies to it, you have the option of | |
30912 | following the terms and conditions either of that specified version or | |
30913 | of any later version that has been published (not as a draft) by the | |
30914 | Free Software Foundation. If the Document does not specify a version | |
30915 | number of this License, you may choose any version ever published (not | |
30916 | as a draft) by the Free Software Foundation. If the Document | |
30917 | specifies that a proxy can decide which future versions of this | |
30918 | License can be used, that proxy’s public statement of acceptance of a | |
30919 | version permanently authorizes you to choose that version for the | |
30920 | Document. | |
30921 | ||
30922 | `11. RELICENSING' | |
30923 | ||
30924 | “Massive Multiauthor Collaboration Site” (or “MMC Site”) means any | |
30925 | World Wide Web server that publishes copyrightable works and also | |
30926 | provides prominent facilities for anybody to edit those works. A | |
30927 | public wiki that anybody can edit is an example of such a server. A | |
30928 | “Massive Multiauthor Collaboration” (or “MMC”) contained in the | |
30929 | site means any set of copyrightable works thus published on the MMC | |
30930 | site. | |
30931 | ||
30932 | “CC-BY-SA” means the Creative Commons Attribution-Share Alike 3.0 | |
30933 | license published by Creative Commons Corporation, a not-for-profit | |
30934 | corporation with a principal place of business in San Francisco, | |
30935 | California, as well as future copyleft versions of that license | |
30936 | published by that same organization. | |
30937 | ||
30938 | “Incorporate” means to publish or republish a Document, in whole or | |
30939 | in part, as part of another Document. | |
30940 | ||
30941 | An MMC is “eligible for relicensing” if it is licensed under this | |
30942 | License, and if all works that were first published under this License | |
30943 | somewhere other than this MMC, and subsequently incorporated in whole | |
30944 | or in part into the MMC, (1) had no cover texts or invariant sections, | |
30945 | and (2) were thus incorporated prior to November 1, 2008. | |
30946 | ||
30947 | The operator of an MMC Site may republish an MMC contained in the site | |
30948 | under CC-BY-SA on the same site at any time before August 1, 2009, | |
30949 | provided the MMC is eligible for relicensing. | |
30950 | ||
30951 | `ADDENDUM: How to use this License for your documents' | |
30952 | ||
30953 | To use this License in a document you have written, include a copy of | |
30954 | the License in the document and put the following copyright and | |
30955 | license notices just after the title page: | |
30956 | ||
30957 | @quotation | |
30958 | ||
30959 | Copyright © YEAR YOUR NAME. | |
30960 | Permission is granted to copy, distribute and/or modify this document | |
30961 | under the terms of the GNU Free Documentation License, Version 1.3 | |
30962 | or any later version published by the Free Software Foundation; | |
30963 | with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. | |
30964 | A copy of the license is included in the section entitled “GNU | |
30965 | Free Documentation License”. | |
30966 | @end quotation | |
30967 | ||
30968 | If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, | |
30969 | replace the “with … Texts.” line with this: | |
30970 | ||
30971 | @quotation | |
30972 | ||
30973 | with the Invariant Sections being LIST THEIR TITLES, with the | |
30974 | Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. | |
30975 | @end quotation | |
30976 | ||
30977 | If you have Invariant Sections without Cover Texts, or some other | |
30978 | combination of the three, merge those two alternatives to suit the | |
30979 | situation. | |
30980 | ||
30981 | If your document contains nontrivial examples of program code, we | |
30982 | recommend releasing these examples in parallel under your choice of | |
30983 | free software license, such as the GNU General Public License, | |
30984 | to permit their use in free software. | |
30985 | ||
30986 | @node Index,,GNU Free Documentation License,Top | |
30987 | @unnumbered Index | |
30988 | ||
30989 | ||
30990 | @printindex ge | |
30991 | ||
30992 | ||
30993 | @c %**end of body | |
30994 | @bye |