]>
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 | |
1555d181 | 6 | @*Generated by Sphinx 7.2.6.@* |
64d5610f ML |
7 | @end ifinfo |
8 | @settitle GNAT Reference Manual | |
9 | @defindex ge | |
10 | @paragraphindent 0 | |
11 | @exampleindent 4 | |
12 | @finalout | |
13 | @dircategory GNU Ada Tools | |
14 | @direntry | |
15 | * gnat_rm: (gnat_rm.info). gnat_rm | |
16 | @end direntry | |
17 | ||
18 | @c %**end of header | |
19 | ||
20 | @copying | |
21 | @quotation | |
1555d181 | 22 | GNAT Reference Manual , Oct 16, 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:: | |
04d6c745 | 257 | * Pragma Side_Effects:: |
64d5610f ML |
258 | * Pragma Simple_Storage_Pool_Type:: |
259 | * Pragma Source_File_Name:: | |
260 | * Pragma Source_File_Name_Project:: | |
261 | * Pragma Source_Reference:: | |
262 | * Pragma SPARK_Mode:: | |
263 | * Pragma Static_Elaboration_Desired:: | |
264 | * Pragma Stream_Convert:: | |
265 | * Pragma Style_Checks:: | |
266 | * Pragma Subtitle:: | |
267 | * Pragma Suppress:: | |
268 | * Pragma Suppress_All:: | |
269 | * Pragma Suppress_Debug_Info:: | |
270 | * Pragma Suppress_Exception_Locations:: | |
271 | * Pragma Suppress_Initialization:: | |
272 | * Pragma Task_Name:: | |
273 | * Pragma Task_Storage:: | |
274 | * Pragma Test_Case:: | |
275 | * Pragma Thread_Local_Storage:: | |
276 | * Pragma Time_Slice:: | |
277 | * Pragma Title:: | |
278 | * Pragma Type_Invariant:: | |
279 | * Pragma Type_Invariant_Class:: | |
280 | * Pragma Unchecked_Union:: | |
281 | * Pragma Unevaluated_Use_Of_Old:: | |
282 | * Pragma Unimplemented_Unit:: | |
283 | * Pragma Universal_Aliasing:: | |
284 | * Pragma Unmodified:: | |
285 | * Pragma Unreferenced:: | |
286 | * Pragma Unreferenced_Objects:: | |
287 | * Pragma Unreserve_All_Interrupts:: | |
288 | * Pragma Unsuppress:: | |
64d5610f | 289 | * Pragma Unused:: |
6f089469 | 290 | * Pragma Use_VADS_Size:: |
64d5610f ML |
291 | * Pragma Validity_Checks:: |
292 | * Pragma Volatile:: | |
293 | * Pragma Volatile_Full_Access:: | |
294 | * Pragma Volatile_Function:: | |
295 | * Pragma Warning_As_Error:: | |
296 | * Pragma Warnings:: | |
297 | * Pragma Weak_External:: | |
298 | * Pragma Wide_Character_Encoding:: | |
299 | ||
300 | Implementation Defined Aspects | |
301 | ||
302 | * Aspect Abstract_State:: | |
303 | * Aspect Annotate:: | |
304 | * Aspect Async_Readers:: | |
305 | * Aspect Async_Writers:: | |
306 | * Aspect Constant_After_Elaboration:: | |
307 | * Aspect Contract_Cases:: | |
308 | * Aspect Depends:: | |
309 | * Aspect Default_Initial_Condition:: | |
310 | * Aspect Dimension:: | |
311 | * Aspect Dimension_System:: | |
312 | * Aspect Disable_Controlled:: | |
313 | * Aspect Effective_Reads:: | |
314 | * Aspect Effective_Writes:: | |
315 | * Aspect Extensions_Visible:: | |
316 | * Aspect Favor_Top_Level:: | |
317 | * Aspect Ghost:: | |
067d80d8 | 318 | * Aspect Ghost_Predicate:: |
64d5610f ML |
319 | * Aspect Global:: |
320 | * Aspect Initial_Condition:: | |
321 | * Aspect Initializes:: | |
322 | * Aspect Inline_Always:: | |
323 | * Aspect Invariant:: | |
324 | * Aspect Invariant’Class:: | |
325 | * Aspect Iterable:: | |
326 | * Aspect Linker_Section:: | |
327 | * Aspect Lock_Free:: | |
328 | * Aspect Max_Queue_Length:: | |
329 | * Aspect No_Caching:: | |
330 | * Aspect No_Elaboration_Code_All:: | |
331 | * Aspect No_Inline:: | |
332 | * Aspect No_Tagged_Streams:: | |
333 | * Aspect No_Task_Parts:: | |
334 | * Aspect Object_Size:: | |
335 | * Aspect Obsolescent:: | |
336 | * Aspect Part_Of:: | |
337 | * Aspect Persistent_BSS:: | |
338 | * Aspect Predicate:: | |
339 | * Aspect Pure_Function:: | |
340 | * Aspect Refined_Depends:: | |
341 | * Aspect Refined_Global:: | |
342 | * Aspect Refined_Post:: | |
343 | * Aspect Refined_State:: | |
344 | * Aspect Relaxed_Initialization:: | |
345 | * Aspect Remote_Access_Type:: | |
346 | * Aspect Secondary_Stack_Size:: | |
347 | * Aspect Scalar_Storage_Order:: | |
348 | * Aspect Shared:: | |
04d6c745 | 349 | * Aspect Side_Effects:: |
64d5610f ML |
350 | * Aspect Simple_Storage_Pool:: |
351 | * Aspect Simple_Storage_Pool_Type:: | |
352 | * Aspect SPARK_Mode:: | |
353 | * Aspect Suppress_Debug_Info:: | |
354 | * Aspect Suppress_Initialization:: | |
355 | * Aspect Test_Case:: | |
356 | * Aspect Thread_Local_Storage:: | |
357 | * Aspect Universal_Aliasing:: | |
358 | * Aspect Unmodified:: | |
359 | * Aspect Unreferenced:: | |
360 | * Aspect Unreferenced_Objects:: | |
361 | * Aspect Value_Size:: | |
362 | * Aspect Volatile_Full_Access:: | |
363 | * Aspect Volatile_Function:: | |
364 | * Aspect Warnings:: | |
365 | ||
366 | Implementation Defined Attributes | |
367 | ||
368 | * Attribute Abort_Signal:: | |
369 | * Attribute Address_Size:: | |
370 | * Attribute Asm_Input:: | |
371 | * Attribute Asm_Output:: | |
372 | * Attribute Atomic_Always_Lock_Free:: | |
373 | * Attribute Bit:: | |
374 | * Attribute Bit_Position:: | |
375 | * Attribute Code_Address:: | |
376 | * Attribute Compiler_Version:: | |
377 | * Attribute Constrained:: | |
378 | * Attribute Default_Bit_Order:: | |
379 | * Attribute Default_Scalar_Storage_Order:: | |
380 | * Attribute Deref:: | |
381 | * Attribute Descriptor_Size:: | |
382 | * Attribute Elaborated:: | |
383 | * Attribute Elab_Body:: | |
384 | * Attribute Elab_Spec:: | |
385 | * Attribute Elab_Subp_Body:: | |
386 | * Attribute Emax:: | |
387 | * Attribute Enabled:: | |
388 | * Attribute Enum_Rep:: | |
389 | * Attribute Enum_Val:: | |
390 | * Attribute Epsilon:: | |
391 | * Attribute Fast_Math:: | |
392 | * Attribute Finalization_Size:: | |
393 | * Attribute Fixed_Value:: | |
394 | * Attribute From_Any:: | |
395 | * Attribute Has_Access_Values:: | |
396 | * Attribute Has_Discriminants:: | |
397 | * Attribute Has_Tagged_Values:: | |
398 | * Attribute Img:: | |
399 | * Attribute Initialized:: | |
400 | * Attribute Integer_Value:: | |
401 | * Attribute Invalid_Value:: | |
402 | * Attribute Iterable:: | |
403 | * Attribute Large:: | |
404 | * Attribute Library_Level:: | |
405 | * Attribute Loop_Entry:: | |
406 | * Attribute Machine_Size:: | |
407 | * Attribute Mantissa:: | |
408 | * Attribute Maximum_Alignment:: | |
409 | * Attribute Max_Integer_Size:: | |
410 | * Attribute Mechanism_Code:: | |
411 | * Attribute Null_Parameter:: | |
412 | * Attribute Object_Size:: | |
413 | * Attribute Old:: | |
414 | * Attribute Passed_By_Reference:: | |
415 | * Attribute Pool_Address:: | |
416 | * Attribute Range_Length:: | |
417 | * Attribute Restriction_Set:: | |
418 | * Attribute Result:: | |
419 | * Attribute Safe_Emax:: | |
420 | * Attribute Safe_Large:: | |
421 | * Attribute Safe_Small:: | |
422 | * Attribute Scalar_Storage_Order:: | |
423 | * Attribute Simple_Storage_Pool:: | |
424 | * Attribute Small:: | |
425 | * Attribute Small_Denominator:: | |
426 | * Attribute Small_Numerator:: | |
427 | * Attribute Storage_Unit:: | |
428 | * Attribute Stub_Type:: | |
429 | * Attribute System_Allocator_Alignment:: | |
430 | * Attribute Target_Name:: | |
431 | * Attribute To_Address:: | |
432 | * Attribute To_Any:: | |
433 | * Attribute Type_Class:: | |
434 | * Attribute Type_Key:: | |
435 | * Attribute TypeCode:: | |
436 | * Attribute Unconstrained_Array:: | |
437 | * Attribute Universal_Literal_String:: | |
438 | * Attribute Unrestricted_Access:: | |
439 | * Attribute Update:: | |
440 | * Attribute Valid_Value:: | |
441 | * Attribute Valid_Scalars:: | |
442 | * Attribute VADS_Size:: | |
443 | * Attribute Value_Size:: | |
444 | * Attribute Wchar_T_Size:: | |
445 | * Attribute Word_Size:: | |
446 | ||
447 | Standard and Implementation Defined Restrictions | |
448 | ||
449 | * Partition-Wide Restrictions:: | |
450 | * Program Unit Level Restrictions:: | |
451 | ||
452 | Partition-Wide Restrictions | |
453 | ||
454 | * Immediate_Reclamation:: | |
455 | * Max_Asynchronous_Select_Nesting:: | |
456 | * Max_Entry_Queue_Length:: | |
457 | * Max_Protected_Entries:: | |
458 | * Max_Select_Alternatives:: | |
459 | * Max_Storage_At_Blocking:: | |
460 | * Max_Task_Entries:: | |
461 | * Max_Tasks:: | |
462 | * No_Abort_Statements:: | |
463 | * No_Access_Parameter_Allocators:: | |
464 | * No_Access_Subprograms:: | |
465 | * No_Allocators:: | |
466 | * No_Anonymous_Allocators:: | |
467 | * No_Asynchronous_Control:: | |
468 | * No_Calendar:: | |
469 | * No_Coextensions:: | |
470 | * No_Default_Initialization:: | |
471 | * No_Delay:: | |
472 | * No_Dependence:: | |
473 | * No_Direct_Boolean_Operators:: | |
474 | * No_Dispatch:: | |
475 | * No_Dispatching_Calls:: | |
476 | * No_Dynamic_Attachment:: | |
477 | * No_Dynamic_Priorities:: | |
478 | * No_Entry_Calls_In_Elaboration_Code:: | |
479 | * No_Enumeration_Maps:: | |
480 | * No_Exception_Handlers:: | |
481 | * No_Exception_Propagation:: | |
482 | * No_Exception_Registration:: | |
483 | * No_Exceptions:: | |
484 | * No_Finalization:: | |
485 | * No_Fixed_Point:: | |
486 | * No_Floating_Point:: | |
487 | * No_Implicit_Conditionals:: | |
488 | * No_Implicit_Dynamic_Code:: | |
489 | * No_Implicit_Heap_Allocations:: | |
490 | * No_Implicit_Protected_Object_Allocations:: | |
491 | * No_Implicit_Task_Allocations:: | |
492 | * No_Initialize_Scalars:: | |
493 | * No_IO:: | |
494 | * No_Local_Allocators:: | |
495 | * No_Local_Protected_Objects:: | |
496 | * No_Local_Tagged_Types:: | |
497 | * No_Local_Timing_Events:: | |
498 | * No_Long_Long_Integers:: | |
499 | * No_Multiple_Elaboration:: | |
500 | * No_Nested_Finalization:: | |
501 | * No_Protected_Type_Allocators:: | |
502 | * No_Protected_Types:: | |
503 | * No_Recursion:: | |
504 | * No_Reentrancy:: | |
505 | * No_Relative_Delay:: | |
506 | * No_Requeue_Statements:: | |
507 | * No_Secondary_Stack:: | |
508 | * No_Select_Statements:: | |
509 | * No_Specific_Termination_Handlers:: | |
510 | * No_Specification_of_Aspect:: | |
511 | * No_Standard_Allocators_After_Elaboration:: | |
512 | * No_Standard_Storage_Pools:: | |
513 | * No_Stream_Optimizations:: | |
514 | * No_Streams:: | |
515 | * No_Tagged_Type_Registration:: | |
516 | * No_Task_Allocators:: | |
517 | * No_Task_At_Interrupt_Priority:: | |
518 | * No_Task_Attributes_Package:: | |
519 | * No_Task_Hierarchy:: | |
520 | * No_Task_Termination:: | |
521 | * No_Tasking:: | |
522 | * No_Terminate_Alternatives:: | |
523 | * No_Unchecked_Access:: | |
524 | * No_Unchecked_Conversion:: | |
525 | * No_Unchecked_Deallocation:: | |
73918baf | 526 | * No_Use_Of_Attribute:: |
64d5610f | 527 | * No_Use_Of_Entity:: |
73918baf | 528 | * No_Use_Of_Pragma:: |
64d5610f ML |
529 | * Pure_Barriers:: |
530 | * Simple_Barriers:: | |
531 | * Static_Priorities:: | |
532 | * Static_Storage_Size:: | |
533 | ||
534 | Program Unit Level Restrictions | |
535 | ||
536 | * No_Elaboration_Code:: | |
537 | * No_Dynamic_Accessibility_Checks:: | |
538 | * No_Dynamic_Sized_Objects:: | |
539 | * No_Entry_Queue:: | |
540 | * No_Implementation_Aspect_Specifications:: | |
541 | * No_Implementation_Attributes:: | |
542 | * No_Implementation_Identifiers:: | |
543 | * No_Implementation_Pragmas:: | |
544 | * No_Implementation_Restrictions:: | |
545 | * No_Implementation_Units:: | |
546 | * No_Implicit_Aliasing:: | |
547 | * No_Implicit_Loops:: | |
548 | * No_Obsolescent_Features:: | |
549 | * No_Wide_Characters:: | |
550 | * Static_Dispatch_Tables:: | |
551 | * SPARK_05:: | |
552 | ||
553 | Implementation Advice | |
554 | ||
555 | * RM 1.1.3(20); Error Detection: RM 1 1 3 20 Error Detection. | |
556 | * RM 1.1.3(31); Child Units: RM 1 1 3 31 Child Units. | |
557 | * RM 1.1.5(12); Bounded Errors: RM 1 1 5 12 Bounded Errors. | |
558 | * RM 2.8(16); Pragmas: RM 2 8 16 Pragmas. | |
559 | * RM 2.8(17-19); Pragmas: RM 2 8 17-19 Pragmas. | |
560 | * RM 3.5.2(5); Alternative Character Sets: RM 3 5 2 5 Alternative Character Sets. | |
561 | * RM 3.5.4(28); Integer Types: RM 3 5 4 28 Integer Types. | |
562 | * RM 3.5.4(29); Integer Types: RM 3 5 4 29 Integer Types. | |
563 | * RM 3.5.5(8); Enumeration Values: RM 3 5 5 8 Enumeration Values. | |
564 | * RM 3.5.7(17); Float Types: RM 3 5 7 17 Float Types. | |
565 | * RM 3.6.2(11); Multidimensional Arrays: RM 3 6 2 11 Multidimensional Arrays. | |
566 | * RM 9.6(30-31); Duration’Small: RM 9 6 30-31 Duration’Small. | |
567 | * RM 10.2.1(12); Consistent Representation: RM 10 2 1 12 Consistent Representation. | |
568 | * RM 11.4.1(19); Exception Information: RM 11 4 1 19 Exception Information. | |
569 | * RM 11.5(28); Suppression of Checks: RM 11 5 28 Suppression of Checks. | |
570 | * RM 13.1 (21-24); Representation Clauses: RM 13 1 21-24 Representation Clauses. | |
571 | * RM 13.2(6-8); Packed Types: RM 13 2 6-8 Packed Types. | |
572 | * RM 13.3(14-19); Address Clauses: RM 13 3 14-19 Address Clauses. | |
573 | * RM 13.3(29-35); Alignment Clauses: RM 13 3 29-35 Alignment Clauses. | |
574 | * RM 13.3(42-43); Size Clauses: RM 13 3 42-43 Size Clauses. | |
575 | * RM 13.3(50-56); Size Clauses: RM 13 3 50-56 Size Clauses. | |
576 | * RM 13.3(71-73); Component Size Clauses: RM 13 3 71-73 Component Size Clauses. | |
577 | * RM 13.4(9-10); Enumeration Representation Clauses: RM 13 4 9-10 Enumeration Representation Clauses. | |
578 | * RM 13.5.1(17-22); Record Representation Clauses: RM 13 5 1 17-22 Record Representation Clauses. | |
579 | * RM 13.5.2(5); Storage Place Attributes: RM 13 5 2 5 Storage Place Attributes. | |
580 | * RM 13.5.3(7-8); Bit Ordering: RM 13 5 3 7-8 Bit Ordering. | |
581 | * RM 13.7(37); Address as Private: RM 13 7 37 Address as Private. | |
582 | * RM 13.7.1(16); Address Operations: RM 13 7 1 16 Address Operations. | |
583 | * RM 13.9(14-17); Unchecked Conversion: RM 13 9 14-17 Unchecked Conversion. | |
584 | * RM 13.11(23-25); Implicit Heap Usage: RM 13 11 23-25 Implicit Heap Usage. | |
585 | * RM 13.11.2(17); Unchecked Deallocation: RM 13 11 2 17 Unchecked Deallocation. | |
586 | * RM 13.13.2(1.6); Stream Oriented Attributes: RM 13 13 2 1 6 Stream Oriented Attributes. | |
587 | * RM A.1(52); Names of Predefined Numeric Types: RM A 1 52 Names of Predefined Numeric Types. | |
588 | * RM A.3.2(49); Ada.Characters.Handling: RM A 3 2 49 Ada Characters Handling. | |
589 | * RM A.4.4(106); Bounded-Length String Handling: RM A 4 4 106 Bounded-Length String Handling. | |
590 | * RM A.5.2(46-47); Random Number Generation: RM A 5 2 46-47 Random Number Generation. | |
591 | * RM A.10.7(23); Get_Immediate: RM A 10 7 23 Get_Immediate. | |
592 | * RM A.18; Containers: RM A 18 Containers. | |
593 | * RM B.1(39-41); Pragma Export: RM B 1 39-41 Pragma Export. | |
594 | * RM B.2(12-13); Package Interfaces: RM B 2 12-13 Package Interfaces. | |
595 | * RM B.3(63-71); Interfacing with C: RM B 3 63-71 Interfacing with C. | |
596 | * RM B.4(95-98); Interfacing with COBOL: RM B 4 95-98 Interfacing with COBOL. | |
597 | * RM B.5(22-26); Interfacing with Fortran: RM B 5 22-26 Interfacing with Fortran. | |
598 | * RM C.1(3-5); Access to Machine Operations: RM C 1 3-5 Access to Machine Operations. | |
599 | * RM C.1(10-16); Access to Machine Operations: RM C 1 10-16 Access to Machine Operations. | |
600 | * RM C.3(28); Interrupt Support: RM C 3 28 Interrupt Support. | |
601 | * RM C.3.1(20-21); Protected Procedure Handlers: RM C 3 1 20-21 Protected Procedure Handlers. | |
602 | * RM C.3.2(25); Package Interrupts: RM C 3 2 25 Package Interrupts. | |
603 | * RM C.4(14); Pre-elaboration Requirements: RM C 4 14 Pre-elaboration Requirements. | |
604 | * RM C.5(8); Pragma Discard_Names: RM C 5 8 Pragma Discard_Names. | |
605 | * RM C.7.2(30); The Package Task_Attributes: RM C 7 2 30 The Package Task_Attributes. | |
606 | * RM D.3(17); Locking Policies: RM D 3 17 Locking Policies. | |
607 | * RM D.4(16); Entry Queuing Policies: RM D 4 16 Entry Queuing Policies. | |
608 | * RM D.6(9-10); Preemptive Abort: RM D 6 9-10 Preemptive Abort. | |
609 | * RM D.7(21); Tasking Restrictions: RM D 7 21 Tasking Restrictions. | |
610 | * RM D.8(47-49); Monotonic Time: RM D 8 47-49 Monotonic Time. | |
611 | * RM E.5(28-29); Partition Communication Subsystem: RM E 5 28-29 Partition Communication Subsystem. | |
612 | * RM F(7); COBOL Support: RM F 7 COBOL Support. | |
613 | * RM F.1(2); Decimal Radix Support: RM F 1 2 Decimal Radix Support. | |
614 | * RM G; Numerics: RM G Numerics. | |
615 | * RM G.1.1(56-58); Complex Types: RM G 1 1 56-58 Complex Types. | |
616 | * RM G.1.2(49); Complex Elementary Functions: RM G 1 2 49 Complex Elementary Functions. | |
617 | * RM G.2.4(19); Accuracy Requirements: RM G 2 4 19 Accuracy Requirements. | |
618 | * RM G.2.6(15); Complex Arithmetic Accuracy: RM G 2 6 15 Complex Arithmetic Accuracy. | |
619 | * RM H.6(15/2); Pragma Partition_Elaboration_Policy: RM H 6 15/2 Pragma Partition_Elaboration_Policy. | |
620 | ||
621 | Intrinsic Subprograms | |
622 | ||
623 | * Intrinsic Operators:: | |
624 | * Compilation_ISO_Date:: | |
625 | * Compilation_Date:: | |
626 | * Compilation_Time:: | |
627 | * Enclosing_Entity:: | |
628 | * Exception_Information:: | |
629 | * Exception_Message:: | |
630 | * Exception_Name:: | |
631 | * File:: | |
632 | * Line:: | |
633 | * Shifts and Rotates:: | |
634 | * Source_Location:: | |
635 | ||
636 | Representation Clauses and Pragmas | |
637 | ||
638 | * Alignment Clauses:: | |
639 | * Size Clauses:: | |
640 | * Storage_Size Clauses:: | |
641 | * Size of Variant Record Objects:: | |
642 | * Biased Representation:: | |
643 | * Value_Size and Object_Size Clauses:: | |
644 | * Component_Size Clauses:: | |
645 | * Bit_Order Clauses:: | |
646 | * Effect of Bit_Order on Byte Ordering:: | |
647 | * Pragma Pack for Arrays:: | |
648 | * Pragma Pack for Records:: | |
649 | * Record Representation Clauses:: | |
650 | * Handling of Records with Holes:: | |
651 | * Enumeration Clauses:: | |
652 | * Address Clauses:: | |
653 | * Use of Address Clauses for Memory-Mapped I/O:: | |
654 | * Effect of Convention on Representation:: | |
655 | * Conventions and Anonymous Access Types:: | |
656 | * Determining the Representations chosen by GNAT:: | |
657 | ||
658 | The Implementation of Standard I/O | |
659 | ||
660 | * Standard I/O Packages:: | |
661 | * FORM Strings:: | |
662 | * Direct_IO:: | |
663 | * Sequential_IO:: | |
664 | * Text_IO:: | |
665 | * Wide_Text_IO:: | |
666 | * Wide_Wide_Text_IO:: | |
667 | * Stream_IO:: | |
668 | * Text Translation:: | |
669 | * Shared Files:: | |
670 | * Filenames encoding:: | |
671 | * File content encoding:: | |
672 | * Open Modes:: | |
673 | * Operations on C Streams:: | |
674 | * Interfacing to C Streams:: | |
675 | ||
676 | Text_IO | |
677 | ||
678 | * Stream Pointer Positioning:: | |
679 | * Reading and Writing Non-Regular Files:: | |
680 | * Get_Immediate:: | |
681 | * Treating Text_IO Files as Streams:: | |
682 | * Text_IO Extensions:: | |
683 | * Text_IO Facilities for Unbounded Strings:: | |
684 | ||
685 | Wide_Text_IO | |
686 | ||
687 | * Stream Pointer Positioning: Stream Pointer Positioning<2>. | |
688 | * Reading and Writing Non-Regular Files: Reading and Writing Non-Regular Files<2>. | |
689 | ||
690 | Wide_Wide_Text_IO | |
691 | ||
692 | * Stream Pointer Positioning: Stream Pointer Positioning<3>. | |
693 | * Reading and Writing Non-Regular Files: Reading and Writing Non-Regular Files<3>. | |
694 | ||
695 | The GNAT Library | |
696 | ||
697 | * Ada.Characters.Latin_9 (a-chlat9.ads): Ada Characters Latin_9 a-chlat9 ads. | |
698 | * Ada.Characters.Wide_Latin_1 (a-cwila1.ads): Ada Characters Wide_Latin_1 a-cwila1 ads. | |
eeba836b | 699 | * Ada.Characters.Wide_Latin_9 (a-cwila9.ads): Ada Characters Wide_Latin_9 a-cwila9 ads. |
64d5610f ML |
700 | * Ada.Characters.Wide_Wide_Latin_1 (a-chzla1.ads): Ada Characters Wide_Wide_Latin_1 a-chzla1 ads. |
701 | * Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads): Ada Characters Wide_Wide_Latin_9 a-chzla9 ads. | |
702 | * Ada.Containers.Bounded_Holders (a-coboho.ads): Ada Containers Bounded_Holders a-coboho ads. | |
703 | * Ada.Command_Line.Environment (a-colien.ads): Ada Command_Line Environment a-colien ads. | |
704 | * Ada.Command_Line.Remove (a-colire.ads): Ada Command_Line Remove a-colire ads. | |
705 | * Ada.Command_Line.Response_File (a-clrefi.ads): Ada Command_Line Response_File a-clrefi ads. | |
706 | * Ada.Direct_IO.C_Streams (a-diocst.ads): Ada Direct_IO C_Streams a-diocst ads. | |
707 | * Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads): Ada Exceptions Is_Null_Occurrence a-einuoc ads. | |
708 | * Ada.Exceptions.Last_Chance_Handler (a-elchha.ads): Ada Exceptions Last_Chance_Handler a-elchha ads. | |
709 | * Ada.Exceptions.Traceback (a-exctra.ads): Ada Exceptions Traceback a-exctra ads. | |
710 | * Ada.Sequential_IO.C_Streams (a-siocst.ads): Ada Sequential_IO C_Streams a-siocst ads. | |
711 | * Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads): Ada Streams Stream_IO C_Streams a-ssicst ads. | |
712 | * Ada.Strings.Unbounded.Text_IO (a-suteio.ads): Ada Strings Unbounded Text_IO a-suteio ads. | |
713 | * Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads): Ada Strings Wide_Unbounded Wide_Text_IO a-swuwti ads. | |
714 | * Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads): Ada Strings Wide_Wide_Unbounded Wide_Wide_Text_IO a-szuzti ads. | |
715 | * Ada.Task_Initialization (a-tasini.ads): Ada Task_Initialization a-tasini ads. | |
716 | * Ada.Text_IO.C_Streams (a-tiocst.ads): Ada Text_IO C_Streams a-tiocst ads. | |
717 | * Ada.Text_IO.Reset_Standard_Files (a-tirsfi.ads): Ada Text_IO Reset_Standard_Files a-tirsfi ads. | |
718 | * Ada.Wide_Characters.Unicode (a-wichun.ads): Ada Wide_Characters Unicode a-wichun ads. | |
719 | * Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads): Ada Wide_Text_IO C_Streams a-wtcstr ads. | |
720 | * Ada.Wide_Text_IO.Reset_Standard_Files (a-wrstfi.ads): Ada Wide_Text_IO Reset_Standard_Files a-wrstfi ads. | |
721 | * Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads): Ada Wide_Wide_Characters Unicode a-zchuni ads. | |
722 | * Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads): Ada Wide_Wide_Text_IO C_Streams a-ztcstr ads. | |
723 | * Ada.Wide_Wide_Text_IO.Reset_Standard_Files (a-zrstfi.ads): Ada Wide_Wide_Text_IO Reset_Standard_Files a-zrstfi ads. | |
724 | * GNAT.Altivec (g-altive.ads): GNAT Altivec g-altive ads. | |
725 | * GNAT.Altivec.Conversions (g-altcon.ads): GNAT Altivec Conversions g-altcon ads. | |
726 | * GNAT.Altivec.Vector_Operations (g-alveop.ads): GNAT Altivec Vector_Operations g-alveop ads. | |
727 | * GNAT.Altivec.Vector_Types (g-alvety.ads): GNAT Altivec Vector_Types g-alvety ads. | |
728 | * GNAT.Altivec.Vector_Views (g-alvevi.ads): GNAT Altivec Vector_Views g-alvevi ads. | |
729 | * GNAT.Array_Split (g-arrspl.ads): GNAT Array_Split g-arrspl ads. | |
730 | * GNAT.AWK (g-awk.ads): GNAT AWK g-awk ads. | |
731 | * GNAT.Binary_Search (g-binsea.ads): GNAT Binary_Search g-binsea ads. | |
732 | * GNAT.Bind_Environment (g-binenv.ads): GNAT Bind_Environment g-binenv ads. | |
733 | * GNAT.Branch_Prediction (g-brapre.ads): GNAT Branch_Prediction g-brapre ads. | |
734 | * GNAT.Bounded_Buffers (g-boubuf.ads): GNAT Bounded_Buffers g-boubuf ads. | |
735 | * GNAT.Bounded_Mailboxes (g-boumai.ads): GNAT Bounded_Mailboxes g-boumai ads. | |
736 | * GNAT.Bubble_Sort (g-bubsor.ads): GNAT Bubble_Sort g-bubsor ads. | |
737 | * GNAT.Bubble_Sort_A (g-busora.ads): GNAT Bubble_Sort_A g-busora ads. | |
738 | * GNAT.Bubble_Sort_G (g-busorg.ads): GNAT Bubble_Sort_G g-busorg ads. | |
739 | * GNAT.Byte_Order_Mark (g-byorma.ads): GNAT Byte_Order_Mark g-byorma ads. | |
740 | * GNAT.Byte_Swapping (g-bytswa.ads): GNAT Byte_Swapping g-bytswa ads. | |
741 | * GNAT.Calendar (g-calend.ads): GNAT Calendar g-calend ads. | |
742 | * GNAT.Calendar.Time_IO (g-catiio.ads): GNAT Calendar Time_IO g-catiio ads. | |
743 | * GNAT.CRC32 (g-crc32.ads): GNAT CRC32 g-crc32 ads. | |
744 | * GNAT.Case_Util (g-casuti.ads): GNAT Case_Util g-casuti ads. | |
745 | * GNAT.CGI (g-cgi.ads): GNAT CGI g-cgi ads. | |
746 | * GNAT.CGI.Cookie (g-cgicoo.ads): GNAT CGI Cookie g-cgicoo ads. | |
747 | * GNAT.CGI.Debug (g-cgideb.ads): GNAT CGI Debug g-cgideb ads. | |
748 | * GNAT.Command_Line (g-comlin.ads): GNAT Command_Line g-comlin ads. | |
749 | * GNAT.Compiler_Version (g-comver.ads): GNAT Compiler_Version g-comver ads. | |
750 | * GNAT.Ctrl_C (g-ctrl_c.ads): GNAT Ctrl_C g-ctrl_c ads. | |
751 | * GNAT.Current_Exception (g-curexc.ads): GNAT Current_Exception g-curexc ads. | |
752 | * GNAT.Debug_Pools (g-debpoo.ads): GNAT Debug_Pools g-debpoo ads. | |
753 | * GNAT.Debug_Utilities (g-debuti.ads): GNAT Debug_Utilities g-debuti ads. | |
754 | * GNAT.Decode_String (g-decstr.ads): GNAT Decode_String g-decstr ads. | |
755 | * GNAT.Decode_UTF8_String (g-deutst.ads): GNAT Decode_UTF8_String g-deutst ads. | |
756 | * GNAT.Directory_Operations (g-dirope.ads): GNAT Directory_Operations g-dirope ads. | |
757 | * GNAT.Directory_Operations.Iteration (g-diopit.ads): GNAT Directory_Operations Iteration g-diopit ads. | |
758 | * GNAT.Dynamic_HTables (g-dynhta.ads): GNAT Dynamic_HTables g-dynhta ads. | |
759 | * GNAT.Dynamic_Tables (g-dyntab.ads): GNAT Dynamic_Tables g-dyntab ads. | |
760 | * GNAT.Encode_String (g-encstr.ads): GNAT Encode_String g-encstr ads. | |
761 | * GNAT.Encode_UTF8_String (g-enutst.ads): GNAT Encode_UTF8_String g-enutst ads. | |
762 | * GNAT.Exception_Actions (g-excact.ads): GNAT Exception_Actions g-excact ads. | |
763 | * GNAT.Exception_Traces (g-exctra.ads): GNAT Exception_Traces g-exctra ads. | |
764 | * GNAT.Exceptions (g-except.ads): GNAT Exceptions g-except ads. | |
765 | * GNAT.Expect (g-expect.ads): GNAT Expect g-expect ads. | |
766 | * GNAT.Expect.TTY (g-exptty.ads): GNAT Expect TTY g-exptty ads. | |
767 | * GNAT.Float_Control (g-flocon.ads): GNAT Float_Control g-flocon ads. | |
768 | * GNAT.Formatted_String (g-forstr.ads): GNAT Formatted_String g-forstr ads. | |
769 | * GNAT.Generic_Fast_Math_Functions (g-gfmafu.ads): GNAT Generic_Fast_Math_Functions g-gfmafu ads. | |
770 | * GNAT.Heap_Sort (g-heasor.ads): GNAT Heap_Sort g-heasor ads. | |
771 | * GNAT.Heap_Sort_A (g-hesora.ads): GNAT Heap_Sort_A g-hesora ads. | |
772 | * GNAT.Heap_Sort_G (g-hesorg.ads): GNAT Heap_Sort_G g-hesorg ads. | |
773 | * GNAT.HTable (g-htable.ads): GNAT HTable g-htable ads. | |
774 | * GNAT.IO (g-io.ads): GNAT IO g-io ads. | |
775 | * GNAT.IO_Aux (g-io_aux.ads): GNAT IO_Aux g-io_aux ads. | |
776 | * GNAT.Lock_Files (g-locfil.ads): GNAT Lock_Files g-locfil ads. | |
777 | * GNAT.MBBS_Discrete_Random (g-mbdira.ads): GNAT MBBS_Discrete_Random g-mbdira ads. | |
778 | * GNAT.MBBS_Float_Random (g-mbflra.ads): GNAT MBBS_Float_Random g-mbflra ads. | |
779 | * GNAT.MD5 (g-md5.ads): GNAT MD5 g-md5 ads. | |
780 | * GNAT.Memory_Dump (g-memdum.ads): GNAT Memory_Dump g-memdum ads. | |
781 | * GNAT.Most_Recent_Exception (g-moreex.ads): GNAT Most_Recent_Exception g-moreex ads. | |
782 | * GNAT.OS_Lib (g-os_lib.ads): GNAT OS_Lib g-os_lib ads. | |
783 | * GNAT.Perfect_Hash_Generators (g-pehage.ads): GNAT Perfect_Hash_Generators g-pehage ads. | |
784 | * GNAT.Random_Numbers (g-rannum.ads): GNAT Random_Numbers g-rannum ads. | |
785 | * GNAT.Regexp (g-regexp.ads): GNAT Regexp g-regexp ads. | |
786 | * GNAT.Registry (g-regist.ads): GNAT Registry g-regist ads. | |
787 | * GNAT.Regpat (g-regpat.ads): GNAT Regpat g-regpat ads. | |
788 | * GNAT.Rewrite_Data (g-rewdat.ads): GNAT Rewrite_Data g-rewdat ads. | |
789 | * GNAT.Secondary_Stack_Info (g-sestin.ads): GNAT Secondary_Stack_Info g-sestin ads. | |
790 | * GNAT.Semaphores (g-semaph.ads): GNAT Semaphores g-semaph ads. | |
791 | * GNAT.Serial_Communications (g-sercom.ads): GNAT Serial_Communications g-sercom ads. | |
792 | * GNAT.SHA1 (g-sha1.ads): GNAT SHA1 g-sha1 ads. | |
793 | * GNAT.SHA224 (g-sha224.ads): GNAT SHA224 g-sha224 ads. | |
794 | * GNAT.SHA256 (g-sha256.ads): GNAT SHA256 g-sha256 ads. | |
795 | * GNAT.SHA384 (g-sha384.ads): GNAT SHA384 g-sha384 ads. | |
796 | * GNAT.SHA512 (g-sha512.ads): GNAT SHA512 g-sha512 ads. | |
797 | * GNAT.Signals (g-signal.ads): GNAT Signals g-signal ads. | |
798 | * GNAT.Sockets (g-socket.ads): GNAT Sockets g-socket ads. | |
799 | * GNAT.Source_Info (g-souinf.ads): GNAT Source_Info g-souinf ads. | |
800 | * GNAT.Spelling_Checker (g-speche.ads): GNAT Spelling_Checker g-speche ads. | |
801 | * GNAT.Spelling_Checker_Generic (g-spchge.ads): GNAT Spelling_Checker_Generic g-spchge ads. | |
802 | * GNAT.Spitbol.Patterns (g-spipat.ads): GNAT Spitbol Patterns g-spipat ads. | |
803 | * GNAT.Spitbol (g-spitbo.ads): GNAT Spitbol g-spitbo ads. | |
804 | * GNAT.Spitbol.Table_Boolean (g-sptabo.ads): GNAT Spitbol Table_Boolean g-sptabo ads. | |
805 | * GNAT.Spitbol.Table_Integer (g-sptain.ads): GNAT Spitbol Table_Integer g-sptain ads. | |
806 | * GNAT.Spitbol.Table_VString (g-sptavs.ads): GNAT Spitbol Table_VString g-sptavs ads. | |
807 | * GNAT.SSE (g-sse.ads): GNAT SSE g-sse ads. | |
808 | * GNAT.SSE.Vector_Types (g-ssvety.ads): GNAT SSE Vector_Types g-ssvety ads. | |
809 | * GNAT.String_Hash (g-strhas.ads): GNAT String_Hash g-strhas ads. | |
810 | * GNAT.Strings (g-string.ads): GNAT Strings g-string ads. | |
811 | * GNAT.String_Split (g-strspl.ads): GNAT String_Split g-strspl ads. | |
812 | * GNAT.Table (g-table.ads): GNAT Table g-table ads. | |
813 | * GNAT.Task_Lock (g-tasloc.ads): GNAT Task_Lock g-tasloc ads. | |
814 | * GNAT.Time_Stamp (g-timsta.ads): GNAT Time_Stamp g-timsta ads. | |
815 | * GNAT.Threads (g-thread.ads): GNAT Threads g-thread ads. | |
816 | * GNAT.Traceback (g-traceb.ads): GNAT Traceback g-traceb ads. | |
817 | * GNAT.Traceback.Symbolic (g-trasym.ads): GNAT Traceback Symbolic g-trasym ads. | |
eeba836b RD |
818 | * GNAT.UTF_32 (g-utf_32.ads): GNAT UTF_32 g-utf_32 ads. |
819 | * GNAT.UTF_32_Spelling_Checker (g-u3spch.ads): GNAT UTF_32_Spelling_Checker g-u3spch ads. | |
64d5610f ML |
820 | * GNAT.Wide_Spelling_Checker (g-wispch.ads): GNAT Wide_Spelling_Checker g-wispch ads. |
821 | * GNAT.Wide_String_Split (g-wistsp.ads): GNAT Wide_String_Split g-wistsp ads. | |
822 | * GNAT.Wide_Wide_Spelling_Checker (g-zspche.ads): GNAT Wide_Wide_Spelling_Checker g-zspche ads. | |
823 | * GNAT.Wide_Wide_String_Split (g-zistsp.ads): GNAT Wide_Wide_String_Split g-zistsp ads. | |
824 | * Interfaces.C.Extensions (i-cexten.ads): Interfaces C Extensions i-cexten ads. | |
825 | * Interfaces.C.Streams (i-cstrea.ads): Interfaces C Streams i-cstrea ads. | |
826 | * Interfaces.Packed_Decimal (i-pacdec.ads): Interfaces Packed_Decimal i-pacdec ads. | |
827 | * Interfaces.VxWorks (i-vxwork.ads): Interfaces VxWorks i-vxwork ads. | |
828 | * Interfaces.VxWorks.Int_Connection (i-vxinco.ads): Interfaces VxWorks Int_Connection i-vxinco ads. | |
829 | * Interfaces.VxWorks.IO (i-vxwoio.ads): Interfaces VxWorks IO i-vxwoio ads. | |
830 | * System.Address_Image (s-addima.ads): System Address_Image s-addima ads. | |
831 | * System.Assertions (s-assert.ads): System Assertions s-assert ads. | |
832 | * System.Atomic_Counters (s-atocou.ads): System Atomic_Counters s-atocou ads. | |
833 | * System.Memory (s-memory.ads): System Memory s-memory ads. | |
834 | * System.Multiprocessors (s-multip.ads): System Multiprocessors s-multip ads. | |
835 | * System.Multiprocessors.Dispatching_Domains (s-mudido.ads): System Multiprocessors Dispatching_Domains s-mudido ads. | |
836 | * System.Partition_Interface (s-parint.ads): System Partition_Interface s-parint ads. | |
837 | * System.Pool_Global (s-pooglo.ads): System Pool_Global s-pooglo ads. | |
838 | * System.Pool_Local (s-pooloc.ads): System Pool_Local s-pooloc ads. | |
839 | * System.Restrictions (s-restri.ads): System Restrictions s-restri ads. | |
840 | * System.Rident (s-rident.ads): System Rident s-rident ads. | |
841 | * System.Strings.Stream_Ops (s-ststop.ads): System Strings Stream_Ops s-ststop ads. | |
842 | * System.Unsigned_Types (s-unstyp.ads): System Unsigned_Types s-unstyp ads. | |
843 | * System.Wch_Cnv (s-wchcnv.ads): System Wch_Cnv s-wchcnv ads. | |
844 | * System.Wch_Con (s-wchcon.ads): System Wch_Con s-wchcon ads. | |
845 | ||
846 | Interfacing to Other Languages | |
847 | ||
848 | * Interfacing to C:: | |
849 | * Interfacing to C++:: | |
850 | * Interfacing to COBOL:: | |
851 | * Interfacing to Fortran:: | |
852 | * Interfacing to non-GNAT Ada code:: | |
853 | ||
854 | Implementation of Specific Ada Features | |
855 | ||
856 | * Machine Code Insertions:: | |
857 | * GNAT Implementation of Tasking:: | |
858 | * GNAT Implementation of Shared Passive Packages:: | |
859 | * Code Generation for Array Aggregates:: | |
860 | * The Size of Discriminated Records with Default Discriminants:: | |
861 | * Image Values For Nonscalar Types:: | |
862 | * Strict Conformance to the Ada Reference Manual:: | |
863 | ||
864 | GNAT Implementation of Tasking | |
865 | ||
866 | * Mapping Ada Tasks onto the Underlying Kernel Threads:: | |
867 | * Ensuring Compliance with the Real-Time Annex:: | |
868 | * Support for Locking Policies:: | |
869 | ||
870 | Code Generation for Array Aggregates | |
871 | ||
872 | * Static constant aggregates with static bounds:: | |
873 | * Constant aggregates with unconstrained nominal types:: | |
874 | * Aggregates with static bounds:: | |
875 | * Aggregates with nonstatic bounds:: | |
876 | * Aggregates in assignment statements:: | |
877 | ||
b71d4b62 RA |
878 | GNAT language extensions |
879 | ||
880 | * How to activate the extended GNAT Ada superset:: | |
881 | * Curated Extensions:: | |
882 | * Experimental Language Extensions:: | |
883 | ||
884 | Curated Extensions | |
885 | ||
9105cd90 | 886 | * Local Declarations Without Block:: |
b71d4b62 RA |
887 | * Conditional when constructs:: |
888 | * Case pattern matching:: | |
889 | * Fixed lower bounds for array types and subtypes:: | |
890 | * Prefixed-view notation for calls to primitive subprograms of untagged types:: | |
891 | * Expression defaults for generic formal functions:: | |
892 | * String interpolation:: | |
893 | * Constrained attribute for generic objects:: | |
894 | * Static aspect on intrinsic functions:: | |
895 | ||
896 | Experimental Language Extensions | |
897 | ||
898 | * Pragma Storage_Model:: | |
899 | * Simpler accessibility model:: | |
900 | ||
64d5610f ML |
901 | Security Hardening Features |
902 | ||
903 | * Register Scrubbing:: | |
904 | * Stack Scrubbing:: | |
905 | * Hardened Conditionals:: | |
906 | * Hardened Booleans:: | |
907 | * Control Flow Redundancy:: | |
908 | ||
909 | Obsolescent Features | |
910 | ||
911 | * pragma No_Run_Time:: | |
912 | * pragma Ravenscar:: | |
913 | * pragma Restricted_Run_Time:: | |
914 | * pragma Task_Info:: | |
915 | * package System.Task_Info (s-tasinf.ads): package System Task_Info s-tasinf ads. | |
916 | ||
917 | Compatibility and Porting Guide | |
918 | ||
919 | * Writing Portable Fixed-Point Declarations:: | |
920 | * Compatibility with Ada 83:: | |
921 | * Compatibility between Ada 95 and Ada 2005:: | |
922 | * Implementation-dependent characteristics:: | |
923 | * Compatibility with Other Ada Systems:: | |
924 | * Representation Clauses:: | |
925 | * Compatibility with HP Ada 83:: | |
926 | ||
927 | Compatibility with Ada 83 | |
928 | ||
929 | * Legal Ada 83 programs that are illegal in Ada 95:: | |
930 | * More deterministic semantics:: | |
931 | * Changed semantics:: | |
932 | * Other language compatibility issues:: | |
933 | ||
934 | Implementation-dependent characteristics | |
935 | ||
936 | * Implementation-defined pragmas:: | |
937 | * Implementation-defined attributes:: | |
938 | * Libraries:: | |
939 | * Elaboration order:: | |
940 | * Target-specific aspects:: | |
941 | ||
942 | @end detailmenu | |
943 | @end menu | |
944 | ||
945 | @node About This Guide,Implementation Defined Pragmas,Top,Top | |
946 | @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} | |
947 | @chapter About This Guide | |
948 | ||
949 | ||
950 | ||
951 | This manual contains useful information in writing programs using the | |
952 | GNAT compiler. It includes information on implementation dependent | |
953 | characteristics of GNAT, including all the information required by | |
954 | Annex M of the Ada language standard. | |
955 | ||
956 | GNAT implements Ada 95, Ada 2005 and Ada 2012, and it may also be | |
957 | invoked in Ada 83 compatibility mode. | |
958 | By default, GNAT assumes Ada 2012, | |
959 | but you can override with a compiler switch | |
960 | to explicitly specify the language version. | |
961 | (Please refer to the `GNAT User’s Guide' for details on these switches.) | |
962 | Throughout this manual, references to ‘Ada’ without a year suffix | |
963 | apply to all the Ada versions of the language. | |
964 | ||
965 | Ada is designed to be highly portable. | |
966 | In general, a program will have the same effect even when compiled by | |
967 | different compilers on different platforms. | |
968 | However, since Ada is designed to be used in a | |
969 | wide variety of applications, it also contains a number of system | |
970 | dependent features to be used in interfacing to the external world. | |
971 | ||
972 | @geindex Implementation-dependent features | |
973 | ||
974 | @geindex Portability | |
975 | ||
976 | Note: Any program that makes use of implementation-dependent features | |
977 | may be non-portable. You should follow good programming practice and | |
978 | isolate and clearly document any sections of your program that make use | |
979 | of these features in a non-portable manner. | |
980 | ||
981 | @menu | |
982 | * What This Reference Manual Contains:: | |
983 | * Conventions:: | |
984 | * Related Information:: | |
985 | ||
986 | @end menu | |
987 | ||
988 | @node What This Reference Manual Contains,Conventions,,About This Guide | |
989 | @anchor{gnat_rm/about_this_guide what-this-reference-manual-contains}@anchor{6} | |
990 | @section What This Reference Manual Contains | |
991 | ||
992 | ||
993 | This reference manual contains the following chapters: | |
994 | ||
995 | ||
996 | @itemize * | |
997 | ||
998 | @item | |
999 | @ref{7,,Implementation Defined Pragmas}, lists GNAT implementation-dependent | |
1000 | pragmas, which can be used to extend and enhance the functionality of the | |
1001 | compiler. | |
1002 | ||
1003 | @item | |
1004 | @ref{8,,Implementation Defined Attributes}, lists GNAT | |
1005 | implementation-dependent attributes, which can be used to extend and | |
1006 | enhance the functionality of the compiler. | |
1007 | ||
1008 | @item | |
1009 | @ref{9,,Standard and Implementation Defined Restrictions}, lists GNAT | |
1010 | implementation-dependent restrictions, which can be used to extend and | |
1011 | enhance the functionality of the compiler. | |
1012 | ||
1013 | @item | |
1014 | @ref{a,,Implementation Advice}, provides information on generally | |
1015 | desirable behavior which are not requirements that all compilers must | |
1016 | follow since it cannot be provided on all systems, or which may be | |
1017 | undesirable on some systems. | |
1018 | ||
1019 | @item | |
1020 | @ref{b,,Implementation Defined Characteristics}, provides a guide to | |
1021 | minimizing implementation dependent features. | |
1022 | ||
1023 | @item | |
1024 | @ref{c,,Intrinsic Subprograms}, describes the intrinsic subprograms | |
1025 | implemented by GNAT, and how they can be imported into user | |
1026 | application programs. | |
1027 | ||
1028 | @item | |
1029 | @ref{d,,Representation Clauses and Pragmas}, describes in detail the | |
1030 | way that GNAT represents data, and in particular the exact set | |
1031 | of representation clauses and pragmas that is accepted. | |
1032 | ||
1033 | @item | |
1034 | @ref{e,,Standard Library Routines}, provides a listing of packages and a | |
1035 | brief description of the functionality that is provided by Ada’s | |
1036 | extensive set of standard library routines as implemented by GNAT. | |
1037 | ||
1038 | @item | |
1039 | @ref{f,,The Implementation of Standard I/O}, details how the GNAT | |
1040 | implementation of the input-output facilities. | |
1041 | ||
1042 | @item | |
1043 | @ref{10,,The GNAT Library}, is a catalog of packages that complement | |
1044 | the Ada predefined library. | |
1045 | ||
1046 | @item | |
1047 | @ref{11,,Interfacing to Other Languages}, describes how programs | |
1048 | written in Ada using GNAT can be interfaced to other programming | |
1049 | languages. | |
1050 | ||
1051 | @item | |
1052 | @ref{12,,Specialized Needs Annexes}, describes the GNAT implementation of all | |
1053 | of the specialized needs annexes. | |
1054 | ||
1055 | @item | |
1056 | @ref{13,,Implementation of Specific Ada Features}, discusses issues related | |
1057 | to GNAT’s implementation of machine code insertions, tasking, and several | |
1058 | other features. | |
1059 | ||
1060 | @item | |
1061 | @ref{14,,Implementation of Ada 2012 Features}, describes the status of the | |
1062 | GNAT implementation of the Ada 2012 language standard. | |
1063 | ||
1064 | @item | |
1065 | @ref{15,,Security Hardening Features} documents GNAT extensions aimed | |
1066 | at security hardening. | |
1067 | ||
1068 | @item | |
1069 | @ref{16,,Obsolescent Features} documents implementation dependent features, | |
1070 | including pragmas and attributes, which are considered obsolescent, since | |
1071 | there are other preferred ways of achieving the same results. These | |
1072 | obsolescent forms are retained for backwards compatibility. | |
1073 | ||
1074 | @item | |
1075 | @ref{17,,Compatibility and Porting Guide} presents some guidelines for | |
1076 | developing portable Ada code, describes the compatibility issues that | |
1077 | may arise between GNAT and other Ada compilation systems (including those | |
1078 | for Ada 83), and shows how GNAT can expedite porting applications | |
1079 | developed in other Ada environments. | |
1080 | ||
1081 | @item | |
1082 | @ref{1,,GNU Free Documentation License} contains the license for this document. | |
1083 | @end itemize | |
1084 | ||
1085 | @geindex Ada 95 Language Reference Manual | |
1086 | ||
1087 | @geindex Ada 2005 Language Reference Manual | |
1088 | ||
1089 | This reference manual assumes a basic familiarity with the Ada 95 language, as | |
1090 | described in the | |
1091 | @cite{International Standard ANSI/ISO/IEC-8652:1995}. | |
1092 | It does not require knowledge of the new features introduced by Ada 2005 or | |
1093 | Ada 2012. | |
1094 | All three reference manuals are included in the GNAT documentation | |
1095 | package. | |
1096 | ||
1097 | @node Conventions,Related Information,What This Reference Manual Contains,About This Guide | |
1098 | @anchor{gnat_rm/about_this_guide conventions}@anchor{18} | |
1099 | @section Conventions | |
1100 | ||
1101 | ||
1102 | @geindex Conventions | |
1103 | @geindex typographical | |
1104 | ||
1105 | @geindex Typographical conventions | |
1106 | ||
1107 | Following are examples of the typographical and graphic conventions used | |
1108 | in this guide: | |
1109 | ||
1110 | ||
1111 | @itemize * | |
1112 | ||
1113 | @item | |
1114 | @code{Functions}, @code{utility program names}, @code{standard names}, | |
1115 | and @code{classes}. | |
1116 | ||
1117 | @item | |
1118 | @code{Option flags} | |
1119 | ||
1120 | @item | |
1121 | @code{File names} | |
1122 | ||
1123 | @item | |
1124 | @code{Variables} | |
1125 | ||
1126 | @item | |
1127 | `Emphasis' | |
1128 | ||
1129 | @item | |
1130 | [optional information or parameters] | |
1131 | ||
1132 | @item | |
1133 | Examples are described by text | |
1134 | ||
1135 | @example | |
1136 | and then shown this way. | |
1137 | @end example | |
1138 | ||
1139 | @item | |
1140 | Commands that are entered by the user are shown as preceded by a prompt string | |
1141 | comprising the @code{$} character followed by a space. | |
1142 | @end itemize | |
1143 | ||
1144 | @node Related Information,,Conventions,About This Guide | |
1145 | @anchor{gnat_rm/about_this_guide related-information}@anchor{19} | |
1146 | @section Related Information | |
1147 | ||
1148 | ||
1149 | See the following documents for further information on GNAT: | |
1150 | ||
1151 | ||
1152 | @itemize * | |
1153 | ||
1154 | @item | |
1155 | @cite{GNAT User’s Guide for Native Platforms}, | |
1156 | which provides information on how to use the | |
1157 | GNAT development environment. | |
1158 | ||
1159 | @item | |
1160 | @cite{Ada 95 Reference Manual}, the Ada 95 programming language standard. | |
1161 | ||
1162 | @item | |
1163 | @cite{Ada 95 Annotated Reference Manual}, which is an annotated version | |
1164 | of the Ada 95 standard. The annotations describe | |
1165 | detailed aspects of the design decision, and in particular contain useful | |
1166 | sections on Ada 83 compatibility. | |
1167 | ||
1168 | @item | |
1169 | @cite{Ada 2005 Reference Manual}, the Ada 2005 programming language standard. | |
1170 | ||
1171 | @item | |
1172 | @cite{Ada 2005 Annotated Reference Manual}, which is an annotated version | |
1173 | of the Ada 2005 standard. The annotations describe | |
1174 | detailed aspects of the design decision. | |
1175 | ||
1176 | @item | |
1177 | @cite{Ada 2012 Reference Manual}, the Ada 2012 programming language standard. | |
1178 | ||
1179 | @item | |
1180 | @cite{DEC Ada@comma{} Technical Overview and Comparison on DIGITAL Platforms}, | |
1181 | which contains specific information on compatibility between GNAT and | |
1182 | DEC Ada 83 systems. | |
1183 | ||
1184 | @item | |
1185 | @cite{DEC Ada@comma{} Language Reference Manual}, part number AA-PYZAB-TK, which | |
1186 | describes in detail the pragmas and attributes provided by the DEC Ada 83 | |
1187 | compiler system. | |
1188 | @end itemize | |
1189 | ||
1190 | @node Implementation Defined Pragmas,Implementation Defined Aspects,About This Guide,Top | |
1191 | @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} | |
1192 | @chapter Implementation Defined Pragmas | |
1193 | ||
1194 | ||
1195 | Ada defines a set of pragmas that can be used to supply additional | |
1196 | information to the compiler. These language defined pragmas are | |
1197 | implemented in GNAT and work as described in the Ada Reference Manual. | |
1198 | ||
1199 | In addition, Ada allows implementations to define additional pragmas | |
1200 | whose meaning is defined by the implementation. GNAT provides a number | |
1201 | of these implementation-defined pragmas, which can be used to extend | |
1202 | and enhance the functionality of the compiler. This section of the GNAT | |
1203 | Reference Manual describes these additional pragmas. | |
1204 | ||
1205 | Note that any program using these pragmas might not be portable to other | |
1206 | compilers (although GNAT implements this set of pragmas on all | |
1207 | platforms). Therefore if portability to other compilers is an important | |
1208 | consideration, the use of these pragmas should be minimized. | |
1209 | ||
1210 | @menu | |
1211 | * Pragma Abort_Defer:: | |
1212 | * Pragma Abstract_State:: | |
1213 | * Pragma Ada_83:: | |
1214 | * Pragma Ada_95:: | |
1215 | * Pragma Ada_05:: | |
1216 | * Pragma Ada_2005:: | |
1217 | * Pragma Ada_12:: | |
1218 | * Pragma Ada_2012:: | |
1219 | * Pragma Ada_2022:: | |
1220 | * Pragma Aggregate_Individually_Assign:: | |
1221 | * Pragma Allow_Integer_Address:: | |
1222 | * Pragma Annotate:: | |
1223 | * Pragma Assert:: | |
1224 | * Pragma Assert_And_Cut:: | |
1225 | * Pragma Assertion_Policy:: | |
1226 | * Pragma Assume:: | |
1227 | * Pragma Assume_No_Invalid_Values:: | |
1228 | * Pragma Async_Readers:: | |
1229 | * Pragma Async_Writers:: | |
1230 | * Pragma Attribute_Definition:: | |
1231 | * Pragma C_Pass_By_Copy:: | |
1232 | * Pragma Check:: | |
1233 | * Pragma Check_Float_Overflow:: | |
1234 | * Pragma Check_Name:: | |
1235 | * Pragma Check_Policy:: | |
1236 | * Pragma Comment:: | |
1237 | * Pragma Common_Object:: | |
1238 | * Pragma Compile_Time_Error:: | |
1239 | * Pragma Compile_Time_Warning:: | |
1240 | * Pragma Complete_Representation:: | |
1241 | * Pragma Complex_Representation:: | |
1242 | * Pragma Component_Alignment:: | |
1243 | * Pragma Constant_After_Elaboration:: | |
1244 | * Pragma Contract_Cases:: | |
1245 | * Pragma Convention_Identifier:: | |
1246 | * Pragma CPP_Class:: | |
1247 | * Pragma CPP_Constructor:: | |
1248 | * Pragma CPP_Virtual:: | |
1249 | * Pragma CPP_Vtable:: | |
1250 | * Pragma CPU:: | |
1251 | * Pragma Deadline_Floor:: | |
64d5610f ML |
1252 | * Pragma Debug:: |
1253 | * Pragma Debug_Policy:: | |
6f089469 | 1254 | * Pragma Default_Initial_Condition:: |
64d5610f ML |
1255 | * Pragma Default_Scalar_Storage_Order:: |
1256 | * Pragma Default_Storage_Pool:: | |
1257 | * Pragma Depends:: | |
1258 | * Pragma Detect_Blocking:: | |
1259 | * Pragma Disable_Atomic_Synchronization:: | |
1260 | * Pragma Dispatching_Domain:: | |
1261 | * Pragma Effective_Reads:: | |
1262 | * Pragma Effective_Writes:: | |
1263 | * Pragma Elaboration_Checks:: | |
1264 | * Pragma Eliminate:: | |
1265 | * Pragma Enable_Atomic_Synchronization:: | |
1266 | * Pragma Export_Function:: | |
1267 | * Pragma Export_Object:: | |
1268 | * Pragma Export_Procedure:: | |
1269 | * Pragma Export_Valued_Procedure:: | |
1270 | * Pragma Extend_System:: | |
1271 | * Pragma Extensions_Allowed:: | |
1272 | * Pragma Extensions_Visible:: | |
1273 | * Pragma External:: | |
1274 | * Pragma External_Name_Casing:: | |
1275 | * Pragma Fast_Math:: | |
1276 | * Pragma Favor_Top_Level:: | |
1277 | * Pragma Finalize_Storage_Only:: | |
1278 | * Pragma Float_Representation:: | |
1279 | * Pragma Ghost:: | |
1280 | * Pragma Global:: | |
1281 | * Pragma Ident:: | |
1282 | * Pragma Ignore_Pragma:: | |
1283 | * Pragma Implementation_Defined:: | |
1284 | * Pragma Implemented:: | |
1285 | * Pragma Implicit_Packing:: | |
1286 | * Pragma Import_Function:: | |
1287 | * Pragma Import_Object:: | |
1288 | * Pragma Import_Procedure:: | |
1289 | * Pragma Import_Valued_Procedure:: | |
1290 | * Pragma Independent:: | |
1291 | * Pragma Independent_Components:: | |
1292 | * Pragma Initial_Condition:: | |
1293 | * Pragma Initialize_Scalars:: | |
1294 | * Pragma Initializes:: | |
1295 | * Pragma Inline_Always:: | |
1296 | * Pragma Inline_Generic:: | |
1297 | * Pragma Interface:: | |
1298 | * Pragma Interface_Name:: | |
1299 | * Pragma Interrupt_Handler:: | |
1300 | * Pragma Interrupt_State:: | |
1301 | * Pragma Invariant:: | |
1302 | * Pragma Keep_Names:: | |
1303 | * Pragma License:: | |
1304 | * Pragma Link_With:: | |
1305 | * Pragma Linker_Alias:: | |
1306 | * Pragma Linker_Constructor:: | |
1307 | * Pragma Linker_Destructor:: | |
1308 | * Pragma Linker_Section:: | |
1309 | * Pragma Lock_Free:: | |
1310 | * Pragma Loop_Invariant:: | |
1311 | * Pragma Loop_Optimize:: | |
1312 | * Pragma Loop_Variant:: | |
1313 | * Pragma Machine_Attribute:: | |
1314 | * Pragma Main:: | |
1315 | * Pragma Main_Storage:: | |
1316 | * Pragma Max_Queue_Length:: | |
1317 | * Pragma No_Body:: | |
1318 | * Pragma No_Caching:: | |
1319 | * Pragma No_Component_Reordering:: | |
1320 | * Pragma No_Elaboration_Code_All:: | |
1321 | * Pragma No_Heap_Finalization:: | |
1322 | * Pragma No_Inline:: | |
1323 | * Pragma No_Return:: | |
1324 | * Pragma No_Strict_Aliasing:: | |
1325 | * Pragma No_Tagged_Streams:: | |
1326 | * Pragma Normalize_Scalars:: | |
1327 | * Pragma Obsolescent:: | |
1328 | * Pragma Optimize_Alignment:: | |
1329 | * Pragma Ordered:: | |
1330 | * Pragma Overflow_Mode:: | |
1331 | * Pragma Overriding_Renamings:: | |
64d5610f | 1332 | * Pragma Part_Of:: |
6f089469 | 1333 | * Pragma Partition_Elaboration_Policy:: |
64d5610f ML |
1334 | * Pragma Passive:: |
1335 | * Pragma Persistent_BSS:: | |
1336 | * Pragma Post:: | |
1337 | * Pragma Postcondition:: | |
1338 | * Pragma Post_Class:: | |
1339 | * Pragma Pre:: | |
1340 | * Pragma Precondition:: | |
1341 | * Pragma Predicate:: | |
1342 | * Pragma Predicate_Failure:: | |
1343 | * Pragma Preelaborable_Initialization:: | |
1344 | * Pragma Prefix_Exception_Messages:: | |
1345 | * Pragma Pre_Class:: | |
1346 | * Pragma Priority_Specific_Dispatching:: | |
1347 | * Pragma Profile:: | |
1348 | * Pragma Profile_Warnings:: | |
1349 | * Pragma Propagate_Exceptions:: | |
1350 | * Pragma Provide_Shift_Operators:: | |
1351 | * Pragma Psect_Object:: | |
1352 | * Pragma Pure_Function:: | |
1353 | * Pragma Rational:: | |
1354 | * Pragma Ravenscar:: | |
1355 | * Pragma Refined_Depends:: | |
1356 | * Pragma Refined_Global:: | |
1357 | * Pragma Refined_Post:: | |
1358 | * Pragma Refined_State:: | |
1359 | * Pragma Relative_Deadline:: | |
1360 | * Pragma Remote_Access_Type:: | |
1361 | * Pragma Rename_Pragma:: | |
1362 | * Pragma Restricted_Run_Time:: | |
1363 | * Pragma Restriction_Warnings:: | |
1364 | * Pragma Reviewable:: | |
1365 | * Pragma Secondary_Stack_Size:: | |
1366 | * Pragma Share_Generic:: | |
1367 | * Pragma Shared:: | |
1368 | * Pragma Short_Circuit_And_Or:: | |
1369 | * Pragma Short_Descriptors:: | |
04d6c745 | 1370 | * Pragma Side_Effects:: |
64d5610f ML |
1371 | * Pragma Simple_Storage_Pool_Type:: |
1372 | * Pragma Source_File_Name:: | |
1373 | * Pragma Source_File_Name_Project:: | |
1374 | * Pragma Source_Reference:: | |
1375 | * Pragma SPARK_Mode:: | |
1376 | * Pragma Static_Elaboration_Desired:: | |
1377 | * Pragma Stream_Convert:: | |
1378 | * Pragma Style_Checks:: | |
1379 | * Pragma Subtitle:: | |
1380 | * Pragma Suppress:: | |
1381 | * Pragma Suppress_All:: | |
1382 | * Pragma Suppress_Debug_Info:: | |
1383 | * Pragma Suppress_Exception_Locations:: | |
1384 | * Pragma Suppress_Initialization:: | |
1385 | * Pragma Task_Name:: | |
1386 | * Pragma Task_Storage:: | |
1387 | * Pragma Test_Case:: | |
1388 | * Pragma Thread_Local_Storage:: | |
1389 | * Pragma Time_Slice:: | |
1390 | * Pragma Title:: | |
1391 | * Pragma Type_Invariant:: | |
1392 | * Pragma Type_Invariant_Class:: | |
1393 | * Pragma Unchecked_Union:: | |
1394 | * Pragma Unevaluated_Use_Of_Old:: | |
1395 | * Pragma Unimplemented_Unit:: | |
1396 | * Pragma Universal_Aliasing:: | |
1397 | * Pragma Unmodified:: | |
1398 | * Pragma Unreferenced:: | |
1399 | * Pragma Unreferenced_Objects:: | |
1400 | * Pragma Unreserve_All_Interrupts:: | |
1401 | * Pragma Unsuppress:: | |
64d5610f | 1402 | * Pragma Unused:: |
6f089469 | 1403 | * Pragma Use_VADS_Size:: |
64d5610f ML |
1404 | * Pragma Validity_Checks:: |
1405 | * Pragma Volatile:: | |
1406 | * Pragma Volatile_Full_Access:: | |
1407 | * Pragma Volatile_Function:: | |
1408 | * Pragma Warning_As_Error:: | |
1409 | * Pragma Warnings:: | |
1410 | * Pragma Weak_External:: | |
1411 | * Pragma Wide_Character_Encoding:: | |
1412 | ||
1413 | @end menu | |
1414 | ||
1415 | @node Pragma Abort_Defer,Pragma Abstract_State,,Implementation Defined Pragmas | |
1416 | @anchor{gnat_rm/implementation_defined_pragmas pragma-abort-defer}@anchor{1c} | |
1417 | @section Pragma Abort_Defer | |
1418 | ||
1419 | ||
1420 | @geindex Deferring aborts | |
1421 | ||
1422 | Syntax: | |
1423 | ||
1424 | @example | |
1425 | pragma Abort_Defer; | |
1426 | @end example | |
1427 | ||
1428 | This pragma must appear at the start of the statement sequence of a | |
1429 | handled sequence of statements (right after the @code{begin}). It has | |
1430 | the effect of deferring aborts for the sequence of statements (but not | |
1431 | for the declarations or handlers, if any, associated with this statement | |
1432 | sequence). This can also be useful for adding a polling point in Ada code, | |
1433 | where asynchronous abort of tasks is checked when leaving the statement | |
1434 | sequence, and is lighter than, for example, using @code{delay 0.0;}, since with | |
1435 | zero-cost exception handling, propagating exceptions (implicitly used to | |
1436 | implement task abort) cannot be done reliably in an asynchronous way. | |
1437 | ||
1438 | An example of usage would be: | |
1439 | ||
1440 | @example | |
1441 | -- Add a polling point to check for task aborts | |
1442 | ||
1443 | begin | |
1444 | pragma Abort_Defer; | |
1445 | end; | |
1446 | @end example | |
1447 | ||
1448 | @node Pragma Abstract_State,Pragma Ada_83,Pragma Abort_Defer,Implementation Defined Pragmas | |
1449 | @anchor{gnat_rm/implementation_defined_pragmas id2}@anchor{1d}@anchor{gnat_rm/implementation_defined_pragmas pragma-abstract-state}@anchor{1e} | |
1450 | @section Pragma Abstract_State | |
1451 | ||
1452 | ||
1453 | Syntax: | |
1454 | ||
1455 | @example | |
1456 | pragma Abstract_State (ABSTRACT_STATE_LIST); | |
1457 | ||
1458 | ABSTRACT_STATE_LIST ::= | |
1459 | null | |
1460 | | STATE_NAME_WITH_OPTIONS | |
1461 | | (STATE_NAME_WITH_OPTIONS @{, STATE_NAME_WITH_OPTIONS@} ) | |
1462 | ||
1463 | STATE_NAME_WITH_OPTIONS ::= | |
1464 | STATE_NAME | |
1465 | | (STATE_NAME with OPTION_LIST) | |
1466 | ||
1467 | OPTION_LIST ::= OPTION @{, OPTION@} | |
1468 | ||
1469 | OPTION ::= | |
1470 | SIMPLE_OPTION | |
1471 | | NAME_VALUE_OPTION | |
1472 | ||
1473 | SIMPLE_OPTION ::= Ghost | Synchronous | |
1474 | ||
1475 | NAME_VALUE_OPTION ::= | |
1476 | Part_Of => ABSTRACT_STATE | |
1477 | | External [=> EXTERNAL_PROPERTY_LIST] | |
1478 | ||
1479 | EXTERNAL_PROPERTY_LIST ::= | |
1480 | EXTERNAL_PROPERTY | |
1481 | | (EXTERNAL_PROPERTY @{, EXTERNAL_PROPERTY@} ) | |
1482 | ||
1483 | EXTERNAL_PROPERTY ::= | |
1484 | Async_Readers [=> static_boolean_EXPRESSION] | |
1485 | | Async_Writers [=> static_boolean_EXPRESSION] | |
1486 | | Effective_Reads [=> static_boolean_EXPRESSION] | |
1487 | | Effective_Writes [=> static_boolean_EXPRESSION] | |
1488 | others => static_boolean_EXPRESSION | |
1489 | ||
1490 | STATE_NAME ::= defining_identifier | |
1491 | ||
1492 | ABSTRACT_STATE ::= name | |
1493 | @end example | |
1494 | ||
1495 | For the semantics of this pragma, see the entry for aspect @code{Abstract_State} in | |
1496 | the SPARK 2014 Reference Manual, section 7.1.4. | |
1497 | ||
1498 | @node Pragma Ada_83,Pragma Ada_95,Pragma Abstract_State,Implementation Defined Pragmas | |
1499 | @anchor{gnat_rm/implementation_defined_pragmas pragma-ada-83}@anchor{1f} | |
1500 | @section Pragma Ada_83 | |
1501 | ||
1502 | ||
1503 | Syntax: | |
1504 | ||
1505 | @example | |
1506 | pragma Ada_83; | |
1507 | @end example | |
1508 | ||
1509 | A configuration pragma that establishes Ada 83 mode for the unit to | |
1510 | which it applies, regardless of the mode set by the command line | |
1511 | switches. In Ada 83 mode, GNAT attempts to be as compatible with | |
1512 | the syntax and semantics of Ada 83, as defined in the original Ada | |
1513 | 83 Reference Manual as possible. In particular, the keywords added by Ada 95 | |
1514 | and Ada 2005 are not recognized, optional package bodies are allowed, | |
1515 | and generics may name types with unknown discriminants without using | |
1516 | the @code{(<>)} notation. In addition, some but not all of the additional | |
1517 | restrictions of Ada 83 are enforced. | |
1518 | ||
1519 | Ada 83 mode is intended for two purposes. Firstly, it allows existing | |
1520 | Ada 83 code to be compiled and adapted to GNAT with less effort. | |
1521 | Secondly, it aids in keeping code backwards compatible with Ada 83. | |
1522 | However, there is no guarantee that code that is processed correctly | |
1523 | by GNAT in Ada 83 mode will in fact compile and execute with an Ada | |
1524 | 83 compiler, since GNAT does not enforce all the additional checks | |
1525 | required by Ada 83. | |
1526 | ||
1527 | @node Pragma Ada_95,Pragma Ada_05,Pragma Ada_83,Implementation Defined Pragmas | |
1528 | @anchor{gnat_rm/implementation_defined_pragmas pragma-ada-95}@anchor{20} | |
1529 | @section Pragma Ada_95 | |
1530 | ||
1531 | ||
1532 | Syntax: | |
1533 | ||
1534 | @example | |
1535 | pragma Ada_95; | |
1536 | @end example | |
1537 | ||
1538 | A configuration pragma that establishes Ada 95 mode for the unit to which | |
1539 | it applies, regardless of the mode set by the command line switches. | |
1540 | This mode is set automatically for the @code{Ada} and @code{System} | |
1541 | packages and their children, so you need not specify it in these | |
1542 | contexts. This pragma is useful when writing a reusable component that | |
1543 | itself uses Ada 95 features, but which is intended to be usable from | |
1544 | either Ada 83 or Ada 95 programs. | |
1545 | ||
1546 | @node Pragma Ada_05,Pragma Ada_2005,Pragma Ada_95,Implementation Defined Pragmas | |
1547 | @anchor{gnat_rm/implementation_defined_pragmas pragma-ada-05}@anchor{21} | |
1548 | @section Pragma Ada_05 | |
1549 | ||
1550 | ||
1551 | Syntax: | |
1552 | ||
1553 | @example | |
1554 | pragma Ada_05; | |
1555 | pragma Ada_05 (local_NAME); | |
1556 | @end example | |
1557 | ||
1558 | A configuration pragma that establishes Ada 2005 mode for the unit to which | |
1559 | it applies, regardless of the mode set by the command line switches. | |
1560 | This pragma is useful when writing a reusable component that | |
1561 | itself uses Ada 2005 features, but which is intended to be usable from | |
1562 | either Ada 83 or Ada 95 programs. | |
1563 | ||
1564 | The one argument form (which is not a configuration pragma) | |
1565 | is used for managing the transition from | |
1566 | Ada 95 to Ada 2005 in the run-time library. If an entity is marked | |
1567 | as Ada_2005 only, then referencing the entity in Ada_83 or Ada_95 | |
1568 | mode will generate a warning. In addition, in Ada_83 or Ada_95 | |
1569 | mode, a preference rule is established which does not choose | |
1570 | such an entity unless it is unambiguously specified. This avoids | |
1571 | extra subprograms marked this way from generating ambiguities in | |
1572 | otherwise legal pre-Ada_2005 programs. The one argument form is | |
1573 | intended for exclusive use in the GNAT run-time library. | |
1574 | ||
1575 | @node Pragma Ada_2005,Pragma Ada_12,Pragma Ada_05,Implementation Defined Pragmas | |
1576 | @anchor{gnat_rm/implementation_defined_pragmas pragma-ada-2005}@anchor{22} | |
1577 | @section Pragma Ada_2005 | |
1578 | ||
1579 | ||
1580 | Syntax: | |
1581 | ||
1582 | @example | |
1583 | pragma Ada_2005; | |
1584 | @end example | |
1585 | ||
1586 | This configuration pragma is a synonym for pragma Ada_05 and has the | |
1587 | same syntax and effect. | |
1588 | ||
1589 | @node Pragma Ada_12,Pragma Ada_2012,Pragma Ada_2005,Implementation Defined Pragmas | |
1590 | @anchor{gnat_rm/implementation_defined_pragmas pragma-ada-12}@anchor{23} | |
1591 | @section Pragma Ada_12 | |
1592 | ||
1593 | ||
1594 | Syntax: | |
1595 | ||
1596 | @example | |
1597 | pragma Ada_12; | |
1598 | pragma Ada_12 (local_NAME); | |
1599 | @end example | |
1600 | ||
1601 | A configuration pragma that establishes Ada 2012 mode for the unit to which | |
1602 | it applies, regardless of the mode set by the command line switches. | |
1603 | This mode is set automatically for the @code{Ada} and @code{System} | |
1604 | packages and their children, so you need not specify it in these | |
1605 | contexts. This pragma is useful when writing a reusable component that | |
1606 | itself uses Ada 2012 features, but which is intended to be usable from | |
1607 | Ada 83, Ada 95, or Ada 2005 programs. | |
1608 | ||
1609 | The one argument form, which is not a configuration pragma, | |
1610 | is used for managing the transition from Ada | |
1611 | 2005 to Ada 2012 in the run-time library. If an entity is marked | |
1612 | as Ada_2012 only, then referencing the entity in any pre-Ada_2012 | |
1613 | mode will generate a warning. In addition, in any pre-Ada_2012 | |
1614 | mode, a preference rule is established which does not choose | |
1615 | such an entity unless it is unambiguously specified. This avoids | |
1616 | extra subprograms marked this way from generating ambiguities in | |
1617 | otherwise legal pre-Ada_2012 programs. The one argument form is | |
1618 | intended for exclusive use in the GNAT run-time library. | |
1619 | ||
1620 | @node Pragma Ada_2012,Pragma Ada_2022,Pragma Ada_12,Implementation Defined Pragmas | |
1621 | @anchor{gnat_rm/implementation_defined_pragmas pragma-ada-2012}@anchor{24} | |
1622 | @section Pragma Ada_2012 | |
1623 | ||
1624 | ||
1625 | Syntax: | |
1626 | ||
1627 | @example | |
1628 | pragma Ada_2012; | |
1629 | @end example | |
1630 | ||
1631 | This configuration pragma is a synonym for pragma Ada_12 and has the | |
1632 | same syntax and effect. | |
1633 | ||
1634 | @node Pragma Ada_2022,Pragma Aggregate_Individually_Assign,Pragma Ada_2012,Implementation Defined Pragmas | |
1635 | @anchor{gnat_rm/implementation_defined_pragmas pragma-ada-2022}@anchor{25} | |
1636 | @section Pragma Ada_2022 | |
1637 | ||
1638 | ||
1639 | Syntax: | |
1640 | ||
1641 | @example | |
1642 | pragma Ada_2022; | |
1643 | pragma Ada_2022 (local_NAME); | |
1644 | @end example | |
1645 | ||
1646 | A configuration pragma that establishes Ada 2022 mode for the unit to which | |
1647 | it applies, regardless of the mode set by the command line switches. | |
1648 | This mode is set automatically for the @code{Ada} and @code{System} | |
1649 | packages and their children, so you need not specify it in these | |
1650 | contexts. This pragma is useful when writing a reusable component that | |
1651 | itself uses Ada 2022 features, but which is intended to be usable from | |
1652 | Ada 83, Ada 95, Ada 2005 or Ada 2012 programs. | |
1653 | ||
1654 | The one argument form, which is not a configuration pragma, | |
1655 | is used for managing the transition from Ada | |
1656 | 2012 to Ada 2022 in the run-time library. If an entity is marked | |
1657 | as Ada_2022 only, then referencing the entity in any pre-Ada_2022 | |
1658 | mode will generate a warning. In addition, in any pre-Ada_2012 | |
1659 | mode, a preference rule is established which does not choose | |
1660 | such an entity unless it is unambiguously specified. This avoids | |
1661 | extra subprograms marked this way from generating ambiguities in | |
1662 | otherwise legal pre-Ada_2022 programs. The one argument form is | |
1663 | intended for exclusive use in the GNAT run-time library. | |
1664 | ||
1665 | @node Pragma Aggregate_Individually_Assign,Pragma Allow_Integer_Address,Pragma Ada_2022,Implementation Defined Pragmas | |
1666 | @anchor{gnat_rm/implementation_defined_pragmas pragma-aggregate-individually-assign}@anchor{26} | |
1667 | @section Pragma Aggregate_Individually_Assign | |
1668 | ||
1669 | ||
1670 | Syntax: | |
1671 | ||
1672 | @example | |
1673 | pragma Aggregate_Individually_Assign; | |
1674 | @end example | |
1675 | ||
1676 | Where possible, GNAT will store the binary representation of a record aggregate | |
1677 | in memory for space and performance reasons. This configuration pragma changes | |
1678 | this behavior so that record aggregates are instead always converted into | |
1679 | individual assignment statements. | |
1680 | ||
1681 | @node Pragma Allow_Integer_Address,Pragma Annotate,Pragma Aggregate_Individually_Assign,Implementation Defined Pragmas | |
1682 | @anchor{gnat_rm/implementation_defined_pragmas pragma-allow-integer-address}@anchor{27} | |
1683 | @section Pragma Allow_Integer_Address | |
1684 | ||
1685 | ||
1686 | Syntax: | |
1687 | ||
1688 | @example | |
1689 | pragma Allow_Integer_Address; | |
1690 | @end example | |
1691 | ||
1692 | In almost all versions of GNAT, @code{System.Address} is a private | |
1693 | type in accordance with the implementation advice in the RM. This | |
1694 | means that integer values, | |
1695 | in particular integer literals, are not allowed as address values. | |
1696 | If the configuration pragma | |
1697 | @code{Allow_Integer_Address} is given, then integer expressions may | |
1698 | be used anywhere a value of type @code{System.Address} is required. | |
1699 | The effect is to introduce an implicit unchecked conversion from the | |
1700 | integer value to type @code{System.Address}. The reverse case of using | |
1701 | an address where an integer type is required is handled analogously. | |
1702 | The following example compiles without errors: | |
1703 | ||
1704 | @example | |
1705 | pragma Allow_Integer_Address; | |
1706 | with System; use System; | |
1707 | package AddrAsInt is | |
1708 | X : Integer; | |
1709 | Y : Integer; | |
1710 | for X'Address use 16#1240#; | |
1711 | for Y use at 16#3230#; | |
1712 | m : Address := 16#4000#; | |
1713 | n : constant Address := 4000; | |
1714 | p : constant Address := Address (X + Y); | |
1715 | v : Integer := y'Address; | |
1716 | w : constant Integer := Integer (Y'Address); | |
1717 | type R is new integer; | |
1718 | RR : R := 1000; | |
1719 | Z : Integer; | |
1720 | for Z'Address use RR; | |
1721 | end AddrAsInt; | |
1722 | @end example | |
1723 | ||
1724 | Note that pragma @code{Allow_Integer_Address} is ignored if @code{System.Address} | |
1725 | is not a private type. In implementations of @code{GNAT} where | |
1726 | System.Address is a visible integer type, | |
1727 | this pragma serves no purpose but is ignored | |
1728 | rather than rejected to allow common sets of sources to be used | |
1729 | in the two situations. | |
1730 | ||
1731 | @node Pragma Annotate,Pragma Assert,Pragma Allow_Integer_Address,Implementation Defined Pragmas | |
1732 | @anchor{gnat_rm/implementation_defined_pragmas id3}@anchor{28}@anchor{gnat_rm/implementation_defined_pragmas pragma-annotate}@anchor{29} | |
1733 | @section Pragma Annotate | |
1734 | ||
1735 | ||
1736 | Syntax: | |
1737 | ||
1738 | @example | |
1739 | pragma Annotate (IDENTIFIER [, IDENTIFIER @{, ARG@}] [, entity => local_NAME]); | |
1740 | ||
1741 | ARG ::= NAME | EXPRESSION | |
1742 | @end example | |
1743 | ||
1744 | This pragma is used to annotate programs. IDENTIFIER identifies | |
1745 | the type of annotation. GNAT verifies that it is an identifier, but does | |
1746 | not otherwise analyze it. The second optional identifier is also left | |
1747 | unanalyzed, and by convention is used to control the action of the tool to | |
1748 | which the annotation is addressed. The remaining ARG arguments | |
1749 | can be either string literals or more generally expressions. | |
1750 | String literals (and concatenations of string literals) are assumed to be | |
1751 | either of type | |
1752 | @code{Standard.String} or else @code{Wide_String} or @code{Wide_Wide_String} | |
1753 | depending on the character literals they contain. | |
1754 | All other kinds of arguments are analyzed as expressions, and must be | |
1755 | unambiguous. The last argument if present must have the identifier | |
1756 | @code{Entity} and GNAT verifies that a local name is given. | |
1757 | ||
1758 | The analyzed pragma is retained in the tree, but not otherwise processed | |
1759 | by any part of the GNAT compiler, except to generate corresponding note | |
1760 | lines in the generated ALI file. For the format of these note lines, see | |
1761 | the compiler source file lib-writ.ads. This pragma is intended for use by | |
1762 | external tools, including ASIS. The use of pragma Annotate does not | |
1763 | affect the compilation process in any way. This pragma may be used as | |
1764 | a configuration pragma. | |
1765 | ||
1766 | @node Pragma Assert,Pragma Assert_And_Cut,Pragma Annotate,Implementation Defined Pragmas | |
1767 | @anchor{gnat_rm/implementation_defined_pragmas pragma-assert}@anchor{2a} | |
1768 | @section Pragma Assert | |
1769 | ||
1770 | ||
1771 | Syntax: | |
1772 | ||
1773 | @example | |
1774 | pragma Assert ( | |
1775 | boolean_EXPRESSION | |
1776 | [, string_EXPRESSION]); | |
1777 | @end example | |
1778 | ||
1779 | The effect of this pragma depends on whether the corresponding command | |
1780 | line switch is set to activate assertions. The pragma expands into code | |
1781 | equivalent to the following: | |
1782 | ||
1783 | @example | |
1784 | if assertions-enabled then | |
1785 | if not boolean_EXPRESSION then | |
1786 | System.Assertions.Raise_Assert_Failure | |
1787 | (string_EXPRESSION); | |
1788 | end if; | |
1789 | end if; | |
1790 | @end example | |
1791 | ||
1792 | The string argument, if given, is the message that will be associated | |
1793 | with the exception occurrence if the exception is raised. If no second | |
1794 | argument is given, the default message is @code{file}:@code{nnn}, | |
1795 | where @code{file} is the name of the source file containing the assert, | |
1796 | and @code{nnn} is the line number of the assert. | |
1797 | ||
1798 | Note that, as with the @code{if} statement to which it is equivalent, the | |
1799 | type of the expression is either @code{Standard.Boolean}, or any type derived | |
1800 | from this standard type. | |
1801 | ||
1802 | Assert checks can be either checked or ignored. By default they are ignored. | |
1803 | They will be checked if either the command line switch `-gnata' is | |
1804 | used, or if an @code{Assertion_Policy} or @code{Check_Policy} pragma is used | |
1805 | to enable @code{Assert_Checks}. | |
1806 | ||
1807 | If assertions are ignored, then there | |
1808 | is no run-time effect (and in particular, any side effects from the | |
1809 | expression will not occur at run time). (The expression is still | |
1810 | analyzed at compile time, and may cause types to be frozen if they are | |
1811 | mentioned here for the first time). | |
1812 | ||
1813 | If assertions are checked, then the given expression is tested, and if | |
1814 | it is @code{False} then @code{System.Assertions.Raise_Assert_Failure} is called | |
1815 | which results in the raising of @code{Assert_Failure} with the given message. | |
1816 | ||
1817 | You should generally avoid side effects in the expression arguments of | |
1818 | this pragma, because these side effects will turn on and off with the | |
1819 | setting of the assertions mode, resulting in assertions that have an | |
1820 | effect on the program. However, the expressions are analyzed for | |
1821 | semantic correctness whether or not assertions are enabled, so turning | |
1822 | assertions on and off cannot affect the legality of a program. | |
1823 | ||
1824 | Note that the implementation defined policy @code{DISABLE}, given in a | |
1825 | pragma @code{Assertion_Policy}, can be used to suppress this semantic analysis. | |
1826 | ||
1827 | Note: this is a standard language-defined pragma in versions | |
1828 | of Ada from 2005 on. In GNAT, it is implemented in all versions | |
1829 | of Ada, and the DISABLE policy is an implementation-defined | |
1830 | addition. | |
1831 | ||
1832 | @node Pragma Assert_And_Cut,Pragma Assertion_Policy,Pragma Assert,Implementation Defined Pragmas | |
1833 | @anchor{gnat_rm/implementation_defined_pragmas pragma-assert-and-cut}@anchor{2b} | |
1834 | @section Pragma Assert_And_Cut | |
1835 | ||
1836 | ||
1837 | Syntax: | |
1838 | ||
1839 | @example | |
1840 | pragma Assert_And_Cut ( | |
1841 | boolean_EXPRESSION | |
1842 | [, string_EXPRESSION]); | |
1843 | @end example | |
1844 | ||
1845 | The effect of this pragma is identical to that of pragma @code{Assert}, | |
1846 | except that in an @code{Assertion_Policy} pragma, the identifier | |
1847 | @code{Assert_And_Cut} is used to control whether it is ignored or checked | |
1848 | (or disabled). | |
1849 | ||
1850 | The intention is that this be used within a subprogram when the | |
1851 | given test expresion sums up all the work done so far in the | |
1852 | subprogram, so that the rest of the subprogram can be verified | |
1853 | (informally or formally) using only the entry preconditions, | |
1854 | and the expression in this pragma. This allows dividing up | |
1855 | a subprogram into sections for the purposes of testing or | |
1856 | formal verification. The pragma also serves as useful | |
1857 | documentation. | |
1858 | ||
1859 | @node Pragma Assertion_Policy,Pragma Assume,Pragma Assert_And_Cut,Implementation Defined Pragmas | |
1860 | @anchor{gnat_rm/implementation_defined_pragmas pragma-assertion-policy}@anchor{2c} | |
1861 | @section Pragma Assertion_Policy | |
1862 | ||
1863 | ||
1864 | Syntax: | |
1865 | ||
1866 | @example | |
1867 | pragma Assertion_Policy (CHECK | DISABLE | IGNORE | SUPPRESSIBLE); | |
1868 | ||
1869 | pragma Assertion_Policy ( | |
1870 | ASSERTION_KIND => POLICY_IDENTIFIER | |
1871 | @{, ASSERTION_KIND => POLICY_IDENTIFIER@}); | |
1872 | ||
1873 | ASSERTION_KIND ::= RM_ASSERTION_KIND | ID_ASSERTION_KIND | |
1874 | ||
1875 | RM_ASSERTION_KIND ::= Assert | | |
1876 | Static_Predicate | | |
1877 | Dynamic_Predicate | | |
1878 | Pre | | |
1879 | Pre'Class | | |
1880 | Post | | |
1881 | Post'Class | | |
1882 | Type_Invariant | | |
1883 | Type_Invariant'Class | | |
1884 | Default_Initial_Condition | |
1885 | ||
1886 | ID_ASSERTION_KIND ::= Assertions | | |
1887 | Assert_And_Cut | | |
1888 | Assume | | |
1889 | Contract_Cases | | |
1890 | Debug | | |
1891 | Ghost | | |
1892 | Initial_Condition | | |
1893 | Invariant | | |
1894 | Invariant'Class | | |
1895 | Loop_Invariant | | |
1896 | Loop_Variant | | |
1897 | Postcondition | | |
1898 | Precondition | | |
1899 | Predicate | | |
1900 | Refined_Post | | |
1901 | Statement_Assertions | | |
1902 | Subprogram_Variant | |
1903 | ||
1904 | POLICY_IDENTIFIER ::= Check | Disable | Ignore | Suppressible | |
1905 | @end example | |
1906 | ||
1907 | This is a standard Ada 2012 pragma that is available as an | |
1908 | implementation-defined pragma in earlier versions of Ada. | |
1909 | The assertion kinds @code{RM_ASSERTION_KIND} are those defined in | |
1910 | the Ada standard. The assertion kinds @code{ID_ASSERTION_KIND} | |
1911 | are implementation defined additions recognized by the GNAT compiler. | |
1912 | ||
1913 | The pragma applies in both cases to pragmas and aspects with matching | |
1914 | names, e.g. @code{Pre} applies to the Pre aspect, and @code{Precondition} | |
1915 | applies to both the @code{Precondition} pragma | |
1916 | and the aspect @code{Precondition}. Note that the identifiers for | |
1917 | pragmas Pre_Class and Post_Class are Pre’Class and Post’Class (not | |
1918 | Pre_Class and Post_Class), since these pragmas are intended to be | |
1919 | identical to the corresponding aspects. | |
1920 | ||
1921 | If the policy is @code{CHECK}, then assertions are enabled, i.e. | |
1922 | the corresponding pragma or aspect is activated. | |
1923 | If the policy is @code{IGNORE}, then assertions are ignored, i.e. | |
1924 | the corresponding pragma or aspect is deactivated. | |
1925 | This pragma overrides the effect of the `-gnata' switch on the | |
1926 | command line. | |
1927 | If the policy is @code{SUPPRESSIBLE}, then assertions are enabled by default, | |
1928 | however, if the `-gnatp' switch is specified all assertions are ignored. | |
1929 | ||
1930 | The implementation defined policy @code{DISABLE} is like | |
1931 | @code{IGNORE} except that it completely disables semantic | |
1932 | checking of the corresponding pragma or aspect. This is | |
1933 | useful when the pragma or aspect argument references subprograms | |
1934 | in a with’ed package which is replaced by a dummy package | |
1935 | for the final build. | |
1936 | ||
1937 | The implementation defined assertion kind @code{Assertions} applies to all | |
1938 | assertion kinds. The form with no assertion kind given implies this | |
1939 | choice, so it applies to all assertion kinds (RM defined, and | |
1940 | implementation defined). | |
1941 | ||
1942 | The implementation defined assertion kind @code{Statement_Assertions} | |
1943 | applies to @code{Assert}, @code{Assert_And_Cut}, | |
1944 | @code{Assume}, @code{Loop_Invariant}, and @code{Loop_Variant}. | |
1945 | ||
1946 | @node Pragma Assume,Pragma Assume_No_Invalid_Values,Pragma Assertion_Policy,Implementation Defined Pragmas | |
1947 | @anchor{gnat_rm/implementation_defined_pragmas pragma-assume}@anchor{2d} | |
1948 | @section Pragma Assume | |
1949 | ||
1950 | ||
1951 | Syntax: | |
1952 | ||
1953 | @example | |
1954 | pragma Assume ( | |
1955 | boolean_EXPRESSION | |
1956 | [, string_EXPRESSION]); | |
1957 | @end example | |
1958 | ||
1959 | The effect of this pragma is identical to that of pragma @code{Assert}, | |
1960 | except that in an @code{Assertion_Policy} pragma, the identifier | |
1961 | @code{Assume} is used to control whether it is ignored or checked | |
1962 | (or disabled). | |
1963 | ||
1964 | The intention is that this be used for assumptions about the | |
1965 | external environment. So you cannot expect to verify formally | |
1966 | or informally that the condition is met, this must be | |
1967 | established by examining things outside the program itself. | |
1968 | For example, we may have code that depends on the size of | |
1969 | @code{Long_Long_Integer} being at least 64. So we could write: | |
1970 | ||
1971 | @example | |
1972 | pragma Assume (Long_Long_Integer'Size >= 64); | |
1973 | @end example | |
1974 | ||
1975 | This assumption cannot be proved from the program itself, | |
1976 | but it acts as a useful run-time check that the assumption | |
1977 | is met, and documents the need to ensure that it is met by | |
1978 | reference to information outside the program. | |
1979 | ||
1980 | @node Pragma Assume_No_Invalid_Values,Pragma Async_Readers,Pragma Assume,Implementation Defined Pragmas | |
1981 | @anchor{gnat_rm/implementation_defined_pragmas pragma-assume-no-invalid-values}@anchor{2e} | |
1982 | @section Pragma Assume_No_Invalid_Values | |
1983 | ||
1984 | ||
1985 | @geindex Invalid representations | |
1986 | ||
1987 | @geindex Invalid values | |
1988 | ||
1989 | Syntax: | |
1990 | ||
1991 | @example | |
1992 | pragma Assume_No_Invalid_Values (On | Off); | |
1993 | @end example | |
1994 | ||
1995 | This is a configuration pragma that controls the assumptions made by the | |
1996 | compiler about the occurrence of invalid representations (invalid values) | |
1997 | in the code. | |
1998 | ||
1999 | The default behavior (corresponding to an Off argument for this pragma), is | |
2000 | to assume that values may in general be invalid unless the compiler can | |
2001 | prove they are valid. Consider the following example: | |
2002 | ||
2003 | @example | |
2004 | V1 : Integer range 1 .. 10; | |
2005 | V2 : Integer range 11 .. 20; | |
2006 | ... | |
2007 | for J in V2 .. V1 loop | |
2008 | ... | |
2009 | end loop; | |
2010 | @end example | |
2011 | ||
2012 | if V1 and V2 have valid values, then the loop is known at compile | |
2013 | time not to execute since the lower bound must be greater than the | |
2014 | upper bound. However in default mode, no such assumption is made, | |
2015 | and the loop may execute. If @code{Assume_No_Invalid_Values (On)} | |
2016 | is given, the compiler will assume that any occurrence of a variable | |
2017 | other than in an explicit @code{'Valid} test always has a valid | |
2018 | value, and the loop above will be optimized away. | |
2019 | ||
2020 | The use of @code{Assume_No_Invalid_Values (On)} is appropriate if | |
2021 | you know your code is free of uninitialized variables and other | |
2022 | possible sources of invalid representations, and may result in | |
2023 | more efficient code. A program that accesses an invalid representation | |
2024 | with this pragma in effect is erroneous, so no guarantees can be made | |
2025 | about its behavior. | |
2026 | ||
2027 | It is peculiar though permissible to use this pragma in conjunction | |
2028 | with validity checking (-gnatVa). In such cases, accessing invalid | |
2029 | values will generally give an exception, though formally the program | |
2030 | is erroneous so there are no guarantees that this will always be the | |
2031 | case, and it is recommended that these two options not be used together. | |
2032 | ||
2033 | @node Pragma Async_Readers,Pragma Async_Writers,Pragma Assume_No_Invalid_Values,Implementation Defined Pragmas | |
2034 | @anchor{gnat_rm/implementation_defined_pragmas id4}@anchor{2f}@anchor{gnat_rm/implementation_defined_pragmas pragma-async-readers}@anchor{30} | |
2035 | @section Pragma Async_Readers | |
2036 | ||
2037 | ||
2038 | Syntax: | |
2039 | ||
2040 | @example | |
2041 | pragma Async_Readers [ (static_boolean_EXPRESSION) ]; | |
2042 | @end example | |
2043 | ||
2044 | For the semantics of this pragma, see the entry for aspect @code{Async_Readers} in | |
2045 | the SPARK 2014 Reference Manual, section 7.1.2. | |
2046 | ||
2047 | @node Pragma Async_Writers,Pragma Attribute_Definition,Pragma Async_Readers,Implementation Defined Pragmas | |
2048 | @anchor{gnat_rm/implementation_defined_pragmas id5}@anchor{31}@anchor{gnat_rm/implementation_defined_pragmas pragma-async-writers}@anchor{32} | |
2049 | @section Pragma Async_Writers | |
2050 | ||
2051 | ||
2052 | Syntax: | |
2053 | ||
2054 | @example | |
2055 | pragma Async_Writers [ (static_boolean_EXPRESSION) ]; | |
2056 | @end example | |
2057 | ||
2058 | For the semantics of this pragma, see the entry for aspect @code{Async_Writers} in | |
2059 | the SPARK 2014 Reference Manual, section 7.1.2. | |
2060 | ||
2061 | @node Pragma Attribute_Definition,Pragma C_Pass_By_Copy,Pragma Async_Writers,Implementation Defined Pragmas | |
2062 | @anchor{gnat_rm/implementation_defined_pragmas pragma-attribute-definition}@anchor{33} | |
2063 | @section Pragma Attribute_Definition | |
2064 | ||
2065 | ||
2066 | Syntax: | |
2067 | ||
2068 | @example | |
2069 | pragma Attribute_Definition | |
2070 | ([Attribute =>] ATTRIBUTE_DESIGNATOR, | |
2071 | [Entity =>] LOCAL_NAME, | |
2072 | [Expression =>] EXPRESSION | NAME); | |
2073 | @end example | |
2074 | ||
2075 | If @code{Attribute} is a known attribute name, this pragma is equivalent to | |
2076 | the attribute definition clause: | |
2077 | ||
2078 | @example | |
2079 | for Entity'Attribute use Expression; | |
2080 | @end example | |
2081 | ||
2082 | If @code{Attribute} is not a recognized attribute name, the pragma is | |
2083 | ignored, and a warning is emitted. This allows source | |
2084 | code to be written that takes advantage of some new attribute, while remaining | |
2085 | compilable with earlier compilers. | |
2086 | ||
2087 | @node Pragma C_Pass_By_Copy,Pragma Check,Pragma Attribute_Definition,Implementation Defined Pragmas | |
2088 | @anchor{gnat_rm/implementation_defined_pragmas pragma-c-pass-by-copy}@anchor{34} | |
2089 | @section Pragma C_Pass_By_Copy | |
2090 | ||
2091 | ||
2092 | @geindex Passing by copy | |
2093 | ||
2094 | Syntax: | |
2095 | ||
2096 | @example | |
2097 | pragma C_Pass_By_Copy | |
2098 | ([Max_Size =>] static_integer_EXPRESSION); | |
2099 | @end example | |
2100 | ||
2101 | Normally the default mechanism for passing C convention records to C | |
2102 | convention subprograms is to pass them by reference, as suggested by RM | |
2103 | B.3(69). Use the configuration pragma @code{C_Pass_By_Copy} to change | |
2104 | this default, by requiring that record formal parameters be passed by | |
2105 | copy if all of the following conditions are met: | |
2106 | ||
2107 | ||
2108 | @itemize * | |
2109 | ||
2110 | @item | |
2111 | The size of the record type does not exceed the value specified for | |
2112 | @code{Max_Size}. | |
2113 | ||
2114 | @item | |
2115 | The record type has @code{Convention C}. | |
2116 | ||
2117 | @item | |
2118 | The formal parameter has this record type, and the subprogram has a | |
2119 | foreign (non-Ada) convention. | |
2120 | @end itemize | |
2121 | ||
2122 | If these conditions are met the argument is passed by copy; i.e., in a | |
2123 | manner consistent with what C expects if the corresponding formal in the | |
2124 | C prototype is a struct (rather than a pointer to a struct). | |
2125 | ||
2126 | You can also pass records by copy by specifying the convention | |
2127 | @code{C_Pass_By_Copy} for the record type, or by using the extended | |
2128 | @code{Import} and @code{Export} pragmas, which allow specification of | |
2129 | passing mechanisms on a parameter by parameter basis. | |
2130 | ||
2131 | @node Pragma Check,Pragma Check_Float_Overflow,Pragma C_Pass_By_Copy,Implementation Defined Pragmas | |
2132 | @anchor{gnat_rm/implementation_defined_pragmas pragma-check}@anchor{35} | |
2133 | @section Pragma Check | |
2134 | ||
2135 | ||
2136 | @geindex Assertions | |
2137 | ||
2138 | @geindex Named assertions | |
2139 | ||
2140 | Syntax: | |
2141 | ||
2142 | @example | |
2143 | pragma Check ( | |
2144 | [Name =>] CHECK_KIND, | |
2145 | [Check =>] Boolean_EXPRESSION | |
2146 | [, [Message =>] string_EXPRESSION] ); | |
2147 | ||
2148 | CHECK_KIND ::= IDENTIFIER | | |
2149 | Pre'Class | | |
2150 | Post'Class | | |
2151 | Type_Invariant'Class | | |
2152 | Invariant'Class | |
2153 | @end example | |
2154 | ||
2155 | This pragma is similar to the predefined pragma @code{Assert} except that an | |
2156 | extra identifier argument is present. In conjunction with pragma | |
2157 | @code{Check_Policy}, this can be used to define groups of assertions that can | |
2158 | be independently controlled. The identifier @code{Assertion} is special, it | |
2159 | refers to the normal set of pragma @code{Assert} statements. | |
2160 | ||
2161 | Checks introduced by this pragma are normally deactivated by default. They can | |
2162 | be activated either by the command line option `-gnata', which turns on | |
2163 | all checks, or individually controlled using pragma @code{Check_Policy}. | |
2164 | ||
2165 | The identifiers @code{Assertions} and @code{Statement_Assertions} are not | |
2166 | permitted as check kinds, since this would cause confusion with the use | |
2167 | of these identifiers in @code{Assertion_Policy} and @code{Check_Policy} | |
2168 | pragmas, where they are used to refer to sets of assertions. | |
2169 | ||
2170 | @node Pragma Check_Float_Overflow,Pragma Check_Name,Pragma Check,Implementation Defined Pragmas | |
2171 | @anchor{gnat_rm/implementation_defined_pragmas pragma-check-float-overflow}@anchor{36} | |
2172 | @section Pragma Check_Float_Overflow | |
2173 | ||
2174 | ||
2175 | @geindex Floating-point overflow | |
2176 | ||
2177 | Syntax: | |
2178 | ||
2179 | @example | |
2180 | pragma Check_Float_Overflow; | |
2181 | @end example | |
2182 | ||
2183 | In Ada, the predefined floating-point types (@code{Short_Float}, | |
2184 | @code{Float}, @code{Long_Float}, @code{Long_Long_Float}) are | |
2185 | defined to be `unconstrained'. This means that even though each | |
2186 | has a well-defined base range, an operation that delivers a result | |
2187 | outside this base range is not required to raise an exception. | |
2188 | This implementation permission accommodates the notion | |
2189 | of infinities in IEEE floating-point, and corresponds to the | |
2190 | efficient execution mode on most machines. GNAT will not raise | |
2191 | overflow exceptions on these machines; instead it will generate | |
2192 | infinities and NaN’s as defined in the IEEE standard. | |
2193 | ||
2194 | Generating infinities, although efficient, is not always desirable. | |
2195 | Often the preferable approach is to check for overflow, even at the | |
2196 | (perhaps considerable) expense of run-time performance. | |
2197 | This can be accomplished by defining your own constrained floating-point subtypes – i.e., by supplying explicit | |
2198 | range constraints – and indeed such a subtype | |
2199 | can have the same base range as its base type. For example: | |
2200 | ||
2201 | @example | |
2202 | subtype My_Float is Float range Float'Range; | |
2203 | @end example | |
2204 | ||
2205 | Here @code{My_Float} has the same range as | |
2206 | @code{Float} but is constrained, so operations on | |
2207 | @code{My_Float} values will be checked for overflow | |
2208 | against this range. | |
2209 | ||
2210 | This style will achieve the desired goal, but | |
2211 | it is often more convenient to be able to simply use | |
2212 | the standard predefined floating-point types as long | |
2213 | as overflow checking could be guaranteed. | |
2214 | The @code{Check_Float_Overflow} | |
2215 | configuration pragma achieves this effect. If a unit is compiled | |
2216 | subject to this configuration pragma, then all operations | |
2217 | on predefined floating-point types including operations on | |
2218 | base types of these floating-point types will be treated as | |
2219 | though those types were constrained, and overflow checks | |
2220 | will be generated. The @code{Constraint_Error} | |
2221 | exception is raised if the result is out of range. | |
2222 | ||
2223 | This mode can also be set by use of the compiler | |
2224 | switch `-gnateF'. | |
2225 | ||
2226 | @node Pragma Check_Name,Pragma Check_Policy,Pragma Check_Float_Overflow,Implementation Defined Pragmas | |
2227 | @anchor{gnat_rm/implementation_defined_pragmas pragma-check-name}@anchor{37} | |
2228 | @section Pragma Check_Name | |
2229 | ||
2230 | ||
2231 | @geindex Defining check names | |
2232 | ||
2233 | @geindex Check names | |
2234 | @geindex defining | |
2235 | ||
2236 | Syntax: | |
2237 | ||
2238 | @example | |
2239 | pragma Check_Name (check_name_IDENTIFIER); | |
2240 | @end example | |
2241 | ||
2242 | This is a configuration pragma that defines a new implementation | |
2243 | defined check name (unless IDENTIFIER matches one of the predefined | |
2244 | check names, in which case the pragma has no effect). Check names | |
2245 | are global to a partition, so if two or more configuration pragmas | |
2246 | are present in a partition mentioning the same name, only one new | |
2247 | check name is introduced. | |
2248 | ||
2249 | An implementation defined check name introduced with this pragma may | |
2250 | be used in only three contexts: @code{pragma Suppress}, | |
2251 | @code{pragma Unsuppress}, | |
2252 | and as the prefix of a @code{Check_Name'Enabled} attribute reference. For | |
2253 | any of these three cases, the check name must be visible. A check | |
2254 | name is visible if it is in the configuration pragmas applying to | |
2255 | the current unit, or if it appears at the start of any unit that | |
2256 | is part of the dependency set of the current unit (e.g., units that | |
2257 | are mentioned in @code{with} clauses). | |
2258 | ||
2259 | Check names introduced by this pragma are subject to control by compiler | |
2260 | switches (in particular -gnatp) in the usual manner. | |
2261 | ||
2262 | @node Pragma Check_Policy,Pragma Comment,Pragma Check_Name,Implementation Defined Pragmas | |
2263 | @anchor{gnat_rm/implementation_defined_pragmas pragma-check-policy}@anchor{38} | |
2264 | @section Pragma Check_Policy | |
2265 | ||
2266 | ||
2267 | @geindex Controlling assertions | |
2268 | ||
2269 | @geindex Assertions | |
2270 | @geindex control | |
2271 | ||
2272 | @geindex Check pragma control | |
2273 | ||
2274 | @geindex Named assertions | |
2275 | ||
2276 | Syntax: | |
2277 | ||
2278 | @example | |
2279 | pragma Check_Policy | |
2280 | ([Name =>] CHECK_KIND, | |
2281 | [Policy =>] POLICY_IDENTIFIER); | |
2282 | ||
2283 | pragma Check_Policy ( | |
2284 | CHECK_KIND => POLICY_IDENTIFIER | |
2285 | @{, CHECK_KIND => POLICY_IDENTIFIER@}); | |
2286 | ||
2287 | ASSERTION_KIND ::= RM_ASSERTION_KIND | ID_ASSERTION_KIND | |
2288 | ||
2289 | CHECK_KIND ::= IDENTIFIER | | |
2290 | Pre'Class | | |
2291 | Post'Class | | |
2292 | Type_Invariant'Class | | |
2293 | Invariant'Class | |
2294 | ||
2295 | The identifiers Name and Policy are not allowed as CHECK_KIND values. This | |
2296 | avoids confusion between the two possible syntax forms for this pragma. | |
2297 | ||
2298 | POLICY_IDENTIFIER ::= ON | OFF | CHECK | DISABLE | IGNORE | |
2299 | @end example | |
2300 | ||
2301 | This pragma is used to set the checking policy for assertions (specified | |
2302 | by aspects or pragmas), the @code{Debug} pragma, or additional checks | |
2303 | to be checked using the @code{Check} pragma. It may appear either as | |
2304 | a configuration pragma, or within a declarative part of package. In the | |
2305 | latter case, it applies from the point where it appears to the end of | |
2306 | the declarative region (like pragma @code{Suppress}). | |
2307 | ||
2308 | The @code{Check_Policy} pragma is similar to the | |
2309 | predefined @code{Assertion_Policy} pragma, | |
2310 | and if the check kind corresponds to one of the assertion kinds that | |
2311 | are allowed by @code{Assertion_Policy}, then the effect is identical. | |
2312 | ||
2313 | If the first argument is Debug, then the policy applies to Debug pragmas, | |
2314 | disabling their effect if the policy is @code{OFF}, @code{DISABLE}, or | |
2315 | @code{IGNORE}, and allowing them to execute with normal semantics if | |
2316 | the policy is @code{ON} or @code{CHECK}. In addition if the policy is | |
2317 | @code{DISABLE}, then the procedure call in @code{Debug} pragmas will | |
2318 | be totally ignored and not analyzed semantically. | |
2319 | ||
2320 | Finally the first argument may be some other identifier than the above | |
2321 | possibilities, in which case it controls a set of named assertions | |
2322 | that can be checked using pragma @code{Check}. For example, if the pragma: | |
2323 | ||
2324 | @example | |
2325 | pragma Check_Policy (Critical_Error, OFF); | |
2326 | @end example | |
2327 | ||
2328 | is given, then subsequent @code{Check} pragmas whose first argument is also | |
2329 | @code{Critical_Error} will be disabled. | |
2330 | ||
2331 | The check policy is @code{OFF} to turn off corresponding checks, and @code{ON} | |
2332 | to turn on corresponding checks. The default for a set of checks for which no | |
2333 | @code{Check_Policy} is given is @code{OFF} unless the compiler switch | |
2334 | `-gnata' is given, which turns on all checks by default. | |
2335 | ||
2336 | The check policy settings @code{CHECK} and @code{IGNORE} are recognized | |
2337 | as synonyms for @code{ON} and @code{OFF}. These synonyms are provided for | |
2338 | compatibility with the standard @code{Assertion_Policy} pragma. The check | |
2339 | policy setting @code{DISABLE} causes the second argument of a corresponding | |
2340 | @code{Check} pragma to be completely ignored and not analyzed. | |
2341 | ||
2342 | @node Pragma Comment,Pragma Common_Object,Pragma Check_Policy,Implementation Defined Pragmas | |
2343 | @anchor{gnat_rm/implementation_defined_pragmas pragma-comment}@anchor{39} | |
2344 | @section Pragma Comment | |
2345 | ||
2346 | ||
2347 | Syntax: | |
2348 | ||
2349 | @example | |
2350 | pragma Comment (static_string_EXPRESSION); | |
2351 | @end example | |
2352 | ||
2353 | This is almost identical in effect to pragma @code{Ident}. It allows the | |
2354 | placement of a comment into the object file and hence into the | |
2355 | executable file if the operating system permits such usage. The | |
2356 | difference is that @code{Comment}, unlike @code{Ident}, has | |
2357 | no limitations on placement of the pragma (it can be placed | |
2358 | anywhere in the main source unit), and if more than one pragma | |
2359 | is used, all comments are retained. | |
2360 | ||
2361 | @node Pragma Common_Object,Pragma Compile_Time_Error,Pragma Comment,Implementation Defined Pragmas | |
2362 | @anchor{gnat_rm/implementation_defined_pragmas pragma-common-object}@anchor{3a} | |
2363 | @section Pragma Common_Object | |
2364 | ||
2365 | ||
2366 | Syntax: | |
2367 | ||
2368 | @example | |
2369 | pragma Common_Object ( | |
2370 | [Internal =>] LOCAL_NAME | |
2371 | [, [External =>] EXTERNAL_SYMBOL] | |
2372 | [, [Size =>] EXTERNAL_SYMBOL] ); | |
2373 | ||
2374 | EXTERNAL_SYMBOL ::= | |
2375 | IDENTIFIER | |
2376 | | static_string_EXPRESSION | |
2377 | @end example | |
2378 | ||
2379 | This pragma enables the shared use of variables stored in overlaid | |
2380 | linker areas corresponding to the use of @code{COMMON} | |
2381 | in Fortran. The single | |
2382 | object @code{LOCAL_NAME} is assigned to the area designated by | |
2383 | the @code{External} argument. | |
2384 | You may define a record to correspond to a series | |
2385 | of fields. The @code{Size} argument | |
2386 | is syntax checked in GNAT, but otherwise ignored. | |
2387 | ||
2388 | @code{Common_Object} is not supported on all platforms. If no | |
2389 | support is available, then the code generator will issue a message | |
2390 | indicating that the necessary attribute for implementation of this | |
2391 | pragma is not available. | |
2392 | ||
2393 | @node Pragma Compile_Time_Error,Pragma Compile_Time_Warning,Pragma Common_Object,Implementation Defined Pragmas | |
2394 | @anchor{gnat_rm/implementation_defined_pragmas compile-time-error}@anchor{3b}@anchor{gnat_rm/implementation_defined_pragmas pragma-compile-time-error}@anchor{3c} | |
2395 | @section Pragma Compile_Time_Error | |
2396 | ||
2397 | ||
2398 | Syntax: | |
2399 | ||
2400 | @example | |
2401 | pragma Compile_Time_Error | |
2402 | (boolean_EXPRESSION, static_string_EXPRESSION); | |
2403 | @end example | |
2404 | ||
2405 | This pragma can be used to generate additional compile time | |
2406 | error messages. It | |
2407 | is particularly useful in generics, where errors can be issued for | |
2408 | specific problematic instantiations. The first parameter is a boolean | |
2409 | expression. The pragma ensures that the value of an expression | |
2410 | is known at compile time, and has the value False. The set of expressions | |
2411 | whose values are known at compile time includes all static boolean | |
2412 | expressions, and also other values which the compiler can determine | |
2413 | at compile time (e.g., the size of a record type set by an explicit | |
2414 | size representation clause, or the value of a variable which was | |
2415 | initialized to a constant and is known not to have been modified). | |
2416 | If these conditions are not met, an error message is generated using | |
2417 | the value given as the second argument. This string value may contain | |
2418 | embedded ASCII.LF characters to break the message into multiple lines. | |
2419 | ||
2420 | @node Pragma Compile_Time_Warning,Pragma Complete_Representation,Pragma Compile_Time_Error,Implementation Defined Pragmas | |
2421 | @anchor{gnat_rm/implementation_defined_pragmas pragma-compile-time-warning}@anchor{3d} | |
2422 | @section Pragma Compile_Time_Warning | |
2423 | ||
2424 | ||
2425 | Syntax: | |
2426 | ||
2427 | @example | |
2428 | pragma Compile_Time_Warning | |
2429 | (boolean_EXPRESSION, static_string_EXPRESSION); | |
2430 | @end example | |
2431 | ||
2432 | Same as pragma Compile_Time_Error, except a warning is issued instead | |
2433 | of an error message. If switch `-gnatw_C' is used, a warning is only issued | |
2434 | if the value of the expression is known to be True at compile time, not when | |
2435 | the value of the expression is not known at compile time. | |
2436 | Note that if this pragma is used in a package that | |
2437 | is with’ed by a client, the client will get the warning even though it | |
2438 | is issued by a with’ed package (normally warnings in with’ed units are | |
2439 | suppressed, but this is a special exception to that rule). | |
2440 | ||
2441 | One typical use is within a generic where compile time known characteristics | |
2442 | of formal parameters are tested, and warnings given appropriately. Another use | |
2443 | with a first parameter of True is to warn a client about use of a package, | |
2444 | for example that it is not fully implemented. | |
2445 | ||
2446 | In previous versions of the compiler, combining `-gnatwe' with | |
2447 | Compile_Time_Warning resulted in a fatal error. Now the compiler always emits | |
2448 | a warning. You can use @ref{3b,,Pragma Compile_Time_Error} to force the generation of | |
2449 | an error. | |
2450 | ||
2451 | @node Pragma Complete_Representation,Pragma Complex_Representation,Pragma Compile_Time_Warning,Implementation Defined Pragmas | |
2452 | @anchor{gnat_rm/implementation_defined_pragmas pragma-complete-representation}@anchor{3e} | |
2453 | @section Pragma Complete_Representation | |
2454 | ||
2455 | ||
2456 | Syntax: | |
2457 | ||
2458 | @example | |
2459 | pragma Complete_Representation; | |
2460 | @end example | |
2461 | ||
2462 | This pragma must appear immediately within a record representation | |
2463 | clause. Typical placements are before the first component clause | |
2464 | or after the last component clause. The effect is to give an error | |
2465 | message if any component is missing a component clause. This pragma | |
2466 | may be used to ensure that a record representation clause is | |
2467 | complete, and that this invariant is maintained if fields are | |
2468 | added to the record in the future. | |
2469 | ||
2470 | @node Pragma Complex_Representation,Pragma Component_Alignment,Pragma Complete_Representation,Implementation Defined Pragmas | |
2471 | @anchor{gnat_rm/implementation_defined_pragmas pragma-complex-representation}@anchor{3f} | |
2472 | @section Pragma Complex_Representation | |
2473 | ||
2474 | ||
2475 | Syntax: | |
2476 | ||
2477 | @example | |
2478 | pragma Complex_Representation | |
2479 | ([Entity =>] LOCAL_NAME); | |
2480 | @end example | |
2481 | ||
2482 | The @code{Entity} argument must be the name of a record type which has | |
2483 | two fields of the same floating-point type. The effect of this pragma is | |
2484 | to force gcc to use the special internal complex representation form for | |
2485 | this record, which may be more efficient. Note that this may result in | |
2486 | the code for this type not conforming to standard ABI (application | |
2487 | binary interface) requirements for the handling of record types. For | |
2488 | example, in some environments, there is a requirement for passing | |
2489 | records by pointer, and the use of this pragma may result in passing | |
2490 | this type in floating-point registers. | |
2491 | ||
2492 | @node Pragma Component_Alignment,Pragma Constant_After_Elaboration,Pragma Complex_Representation,Implementation Defined Pragmas | |
2493 | @anchor{gnat_rm/implementation_defined_pragmas pragma-component-alignment}@anchor{40} | |
2494 | @section Pragma Component_Alignment | |
2495 | ||
2496 | ||
2497 | @geindex Alignments of components | |
2498 | ||
2499 | @geindex Pragma Component_Alignment | |
2500 | ||
2501 | Syntax: | |
2502 | ||
2503 | @example | |
2504 | pragma Component_Alignment ( | |
2505 | [Form =>] ALIGNMENT_CHOICE | |
2506 | [, [Name =>] type_LOCAL_NAME]); | |
2507 | ||
2508 | ALIGNMENT_CHOICE ::= | |
2509 | Component_Size | |
2510 | | Component_Size_4 | |
2511 | | Storage_Unit | |
2512 | | Default | |
2513 | @end example | |
2514 | ||
2515 | Specifies the alignment of components in array or record types. | |
2516 | The meaning of the @code{Form} argument is as follows: | |
2517 | ||
2518 | @quotation | |
2519 | ||
2520 | @geindex Component_Size (in pragma Component_Alignment) | |
2521 | @end quotation | |
2522 | ||
2523 | ||
2524 | @table @asis | |
2525 | ||
2526 | @item `Component_Size' | |
2527 | ||
2528 | Aligns scalar components and subcomponents of the array or record type | |
2529 | on boundaries appropriate to their inherent size (naturally | |
2530 | aligned). For example, 1-byte components are aligned on byte boundaries, | |
2531 | 2-byte integer components are aligned on 2-byte boundaries, 4-byte | |
2532 | integer components are aligned on 4-byte boundaries and so on. These | |
2533 | alignment rules correspond to the normal rules for C compilers on all | |
2534 | machines except the VAX. | |
2535 | ||
2536 | @geindex Component_Size_4 (in pragma Component_Alignment) | |
2537 | ||
2538 | @item `Component_Size_4' | |
2539 | ||
2540 | Naturally aligns components with a size of four or fewer | |
2541 | bytes. Components that are larger than 4 bytes are placed on the next | |
2542 | 4-byte boundary. | |
2543 | ||
2544 | @geindex Storage_Unit (in pragma Component_Alignment) | |
2545 | ||
2546 | @item `Storage_Unit' | |
2547 | ||
2548 | Specifies that array or record components are byte aligned, i.e., | |
2549 | aligned on boundaries determined by the value of the constant | |
2550 | @code{System.Storage_Unit}. | |
2551 | ||
2552 | @geindex Default (in pragma Component_Alignment) | |
2553 | ||
2554 | @item `Default' | |
2555 | ||
2556 | Specifies that array or record components are aligned on default | |
2557 | boundaries, appropriate to the underlying hardware or operating system or | |
2558 | both. The @code{Default} choice is the same as @code{Component_Size} (natural | |
2559 | alignment). | |
2560 | @end table | |
2561 | ||
2562 | If the @code{Name} parameter is present, @code{type_LOCAL_NAME} must | |
2563 | refer to a local record or array type, and the specified alignment | |
2564 | choice applies to the specified type. The use of | |
2565 | @code{Component_Alignment} together with a pragma @code{Pack} causes the | |
2566 | @code{Component_Alignment} pragma to be ignored. The use of | |
2567 | @code{Component_Alignment} together with a record representation clause | |
2568 | is only effective for fields not specified by the representation clause. | |
2569 | ||
2570 | If the @code{Name} parameter is absent, the pragma can be used as either | |
2571 | a configuration pragma, in which case it applies to one or more units in | |
2572 | accordance with the normal rules for configuration pragmas, or it can be | |
2573 | used within a declarative part, in which case it applies to types that | |
2574 | are declared within this declarative part, or within any nested scope | |
2575 | within this declarative part. In either case it specifies the alignment | |
2576 | to be applied to any record or array type which has otherwise standard | |
2577 | representation. | |
2578 | ||
2579 | If the alignment for a record or array type is not specified (using | |
2580 | pragma @code{Pack}, pragma @code{Component_Alignment}, or a record rep | |
2581 | clause), the GNAT uses the default alignment as described previously. | |
2582 | ||
2583 | @node Pragma Constant_After_Elaboration,Pragma Contract_Cases,Pragma Component_Alignment,Implementation Defined Pragmas | |
2584 | @anchor{gnat_rm/implementation_defined_pragmas id6}@anchor{41}@anchor{gnat_rm/implementation_defined_pragmas pragma-constant-after-elaboration}@anchor{42} | |
2585 | @section Pragma Constant_After_Elaboration | |
2586 | ||
2587 | ||
2588 | Syntax: | |
2589 | ||
2590 | @example | |
2591 | pragma Constant_After_Elaboration [ (static_boolean_EXPRESSION) ]; | |
2592 | @end example | |
2593 | ||
2594 | For the semantics of this pragma, see the entry for aspect | |
2595 | @code{Constant_After_Elaboration} in the SPARK 2014 Reference Manual, section 3.3.1. | |
2596 | ||
2597 | @node Pragma Contract_Cases,Pragma Convention_Identifier,Pragma Constant_After_Elaboration,Implementation Defined Pragmas | |
2598 | @anchor{gnat_rm/implementation_defined_pragmas id7}@anchor{43}@anchor{gnat_rm/implementation_defined_pragmas pragma-contract-cases}@anchor{44} | |
2599 | @section Pragma Contract_Cases | |
2600 | ||
2601 | ||
2602 | @geindex Contract cases | |
2603 | ||
2604 | Syntax: | |
2605 | ||
2606 | @example | |
2607 | pragma Contract_Cases (CONTRACT_CASE @{, CONTRACT_CASE@}); | |
2608 | ||
2609 | CONTRACT_CASE ::= CASE_GUARD => CONSEQUENCE | |
2610 | ||
2611 | CASE_GUARD ::= boolean_EXPRESSION | others | |
2612 | ||
2613 | CONSEQUENCE ::= boolean_EXPRESSION | |
2614 | @end example | |
2615 | ||
2616 | The @code{Contract_Cases} pragma allows defining fine-grain specifications | |
2617 | that can complement or replace the contract given by a precondition and a | |
2618 | postcondition. Additionally, the @code{Contract_Cases} pragma can be used | |
2619 | by testing and formal verification tools. The compiler checks its validity and, | |
2620 | depending on the assertion policy at the point of declaration of the pragma, | |
2621 | it may insert a check in the executable. For code generation, the contract | |
2622 | cases | |
2623 | ||
2624 | @example | |
2625 | pragma Contract_Cases ( | |
2626 | Cond1 => Pred1, | |
2627 | Cond2 => Pred2); | |
2628 | @end example | |
2629 | ||
2630 | are equivalent to | |
2631 | ||
2632 | @example | |
2633 | C1 : constant Boolean := Cond1; -- evaluated at subprogram entry | |
2634 | C2 : constant Boolean := Cond2; -- evaluated at subprogram entry | |
2635 | pragma Precondition ((C1 and not C2) or (C2 and not C1)); | |
2636 | pragma Postcondition (if C1 then Pred1); | |
2637 | pragma Postcondition (if C2 then Pred2); | |
2638 | @end example | |
2639 | ||
2640 | The precondition ensures that one and only one of the case guards is | |
2641 | satisfied on entry to the subprogram. | |
2642 | The postcondition ensures that for the case guard that was True on entry, | |
2643 | the corresponding consequence is True on exit. Other consequence expressions | |
2644 | are not evaluated. | |
2645 | ||
2646 | A precondition @code{P} and postcondition @code{Q} can also be | |
2647 | expressed as contract cases: | |
2648 | ||
2649 | @example | |
2650 | pragma Contract_Cases (P => Q); | |
2651 | @end example | |
2652 | ||
2653 | The placement and visibility rules for @code{Contract_Cases} pragmas are | |
2654 | identical to those described for preconditions and postconditions. | |
2655 | ||
2656 | The compiler checks that boolean expressions given in case guards and | |
2657 | consequences are valid, where the rules for case guards are the same as | |
2658 | the rule for an expression in @code{Precondition} and the rules for | |
2659 | consequences are the same as the rule for an expression in | |
2660 | @code{Postcondition}. In particular, attributes @code{'Old} and | |
2661 | @code{'Result} can only be used within consequence expressions. | |
2662 | The case guard for the last contract case may be @code{others}, to denote | |
2663 | any case not captured by the previous cases. The | |
2664 | following is an example of use within a package spec: | |
2665 | ||
2666 | @example | |
2667 | package Math_Functions is | |
2668 | ... | |
2669 | function Sqrt (Arg : Float) return Float; | |
2670 | pragma Contract_Cases (((Arg in 0.0 .. 99.0) => Sqrt'Result < 10.0, | |
2671 | Arg >= 100.0 => Sqrt'Result >= 10.0, | |
2672 | others => Sqrt'Result = 0.0)); | |
2673 | ... | |
2674 | end Math_Functions; | |
2675 | @end example | |
2676 | ||
2677 | The meaning of contract cases is that only one case should apply at each | |
2678 | call, as determined by the corresponding case guard evaluating to True, | |
2679 | and that the consequence for this case should hold when the subprogram | |
2680 | returns. | |
2681 | ||
2682 | @node Pragma Convention_Identifier,Pragma CPP_Class,Pragma Contract_Cases,Implementation Defined Pragmas | |
2683 | @anchor{gnat_rm/implementation_defined_pragmas pragma-convention-identifier}@anchor{45} | |
2684 | @section Pragma Convention_Identifier | |
2685 | ||
2686 | ||
2687 | @geindex Conventions | |
2688 | @geindex synonyms | |
2689 | ||
2690 | Syntax: | |
2691 | ||
2692 | @example | |
2693 | pragma Convention_Identifier ( | |
2694 | [Name =>] IDENTIFIER, | |
2695 | [Convention =>] convention_IDENTIFIER); | |
2696 | @end example | |
2697 | ||
2698 | This pragma provides a mechanism for supplying synonyms for existing | |
2699 | convention identifiers. The @code{Name} identifier can subsequently | |
2700 | be used as a synonym for the given convention in other pragmas (including | |
2701 | for example pragma @code{Import} or another @code{Convention_Identifier} | |
2702 | pragma). As an example of the use of this, suppose you had legacy code | |
2703 | which used Fortran77 as the identifier for Fortran. Then the pragma: | |
2704 | ||
2705 | @example | |
2706 | pragma Convention_Identifier (Fortran77, Fortran); | |
2707 | @end example | |
2708 | ||
2709 | would allow the use of the convention identifier @code{Fortran77} in | |
2710 | subsequent code, avoiding the need to modify the sources. As another | |
2711 | example, you could use this to parameterize convention requirements | |
2712 | according to systems. Suppose you needed to use @code{Stdcall} on | |
2713 | windows systems, and @code{C} on some other system, then you could | |
2714 | define a convention identifier @code{Library} and use a single | |
2715 | @code{Convention_Identifier} pragma to specify which convention | |
2716 | would be used system-wide. | |
2717 | ||
2718 | @node Pragma CPP_Class,Pragma CPP_Constructor,Pragma Convention_Identifier,Implementation Defined Pragmas | |
2719 | @anchor{gnat_rm/implementation_defined_pragmas pragma-cpp-class}@anchor{46} | |
2720 | @section Pragma CPP_Class | |
2721 | ||
2722 | ||
2723 | @geindex Interfacing with C++ | |
2724 | ||
2725 | Syntax: | |
2726 | ||
2727 | @example | |
2728 | pragma CPP_Class ([Entity =>] LOCAL_NAME); | |
2729 | @end example | |
2730 | ||
2731 | The argument denotes an entity in the current declarative region that is | |
2732 | declared as a record type. It indicates that the type corresponds to an | |
2733 | externally declared C++ class type, and is to be laid out the same way | |
2734 | that C++ would lay out the type. If the C++ class has virtual primitives | |
2735 | then the record must be declared as a tagged record type. | |
2736 | ||
2737 | Types for which @code{CPP_Class} is specified do not have assignment or | |
2738 | equality operators defined (such operations can be imported or declared | |
2739 | as subprograms as required). Initialization is allowed only by constructor | |
2740 | functions (see pragma @code{CPP_Constructor}). Such types are implicitly | |
2741 | limited if not explicitly declared as limited or derived from a limited | |
2742 | type, and an error is issued in that case. | |
2743 | ||
2744 | See @ref{47,,Interfacing to C++} for related information. | |
2745 | ||
2746 | Note: Pragma @code{CPP_Class} is currently obsolete. It is supported | |
2747 | for backward compatibility but its functionality is available | |
2748 | using pragma @code{Import} with @code{Convention} = @code{CPP}. | |
2749 | ||
2750 | @node Pragma CPP_Constructor,Pragma CPP_Virtual,Pragma CPP_Class,Implementation Defined Pragmas | |
2751 | @anchor{gnat_rm/implementation_defined_pragmas pragma-cpp-constructor}@anchor{48} | |
2752 | @section Pragma CPP_Constructor | |
2753 | ||
2754 | ||
2755 | @geindex Interfacing with C++ | |
2756 | ||
2757 | Syntax: | |
2758 | ||
2759 | @example | |
2760 | pragma CPP_Constructor ([Entity =>] LOCAL_NAME | |
2761 | [, [External_Name =>] static_string_EXPRESSION ] | |
2762 | [, [Link_Name =>] static_string_EXPRESSION ]); | |
2763 | @end example | |
2764 | ||
2765 | This pragma identifies an imported function (imported in the usual way | |
2766 | with pragma @code{Import}) as corresponding to a C++ constructor. If | |
2767 | @code{External_Name} and @code{Link_Name} are not specified then the | |
2768 | @code{Entity} argument is a name that must have been previously mentioned | |
2769 | in a pragma @code{Import} with @code{Convention} = @code{CPP}. Such name | |
2770 | must be of one of the following forms: | |
2771 | ||
2772 | ||
2773 | @itemize * | |
2774 | ||
2775 | @item | |
2776 | `function' @code{Fname} `return' T` | |
2777 | ||
2778 | @item | |
2779 | `function' @code{Fname} `return' T’Class | |
2780 | ||
2781 | @item | |
2782 | `function' @code{Fname} (…) `return' T` | |
2783 | ||
2784 | @item | |
2785 | `function' @code{Fname} (…) `return' T’Class | |
2786 | @end itemize | |
2787 | ||
2788 | where @code{T} is a limited record type imported from C++ with pragma | |
2789 | @code{Import} and @code{Convention} = @code{CPP}. | |
2790 | ||
2791 | The first two forms import the default constructor, used when an object | |
2792 | of type @code{T} is created on the Ada side with no explicit constructor. | |
2793 | The latter two forms cover all the non-default constructors of the type. | |
2794 | See the GNAT User’s Guide for details. | |
2795 | ||
2796 | If no constructors are imported, it is impossible to create any objects | |
2797 | on the Ada side and the type is implicitly declared abstract. | |
2798 | ||
2799 | Pragma @code{CPP_Constructor} is intended primarily for automatic generation | |
2800 | using an automatic binding generator tool (such as the @code{-fdump-ada-spec} | |
2801 | GCC switch). | |
2802 | See @ref{47,,Interfacing to C++} for more related information. | |
2803 | ||
2804 | Note: The use of functions returning class-wide types for constructors is | |
2805 | currently obsolete. They are supported for backward compatibility. The | |
2806 | use of functions returning the type T leave the Ada sources more clear | |
2807 | because the imported C++ constructors always return an object of type T; | |
2808 | that is, they never return an object whose type is a descendant of type T. | |
2809 | ||
2810 | @node Pragma CPP_Virtual,Pragma CPP_Vtable,Pragma CPP_Constructor,Implementation Defined Pragmas | |
2811 | @anchor{gnat_rm/implementation_defined_pragmas pragma-cpp-virtual}@anchor{49} | |
2812 | @section Pragma CPP_Virtual | |
2813 | ||
2814 | ||
2815 | @geindex Interfacing to C++ | |
2816 | ||
2817 | This pragma is now obsolete and, other than generating a warning if warnings | |
2818 | on obsolescent features are enabled, is completely ignored. | |
2819 | It is retained for compatibility | |
2820 | purposes. It used to be required to ensure compatibility with C++, but | |
2821 | is no longer required for that purpose because GNAT generates | |
2822 | the same object layout as the G++ compiler by default. | |
2823 | ||
2824 | See @ref{47,,Interfacing to C++} for related information. | |
2825 | ||
2826 | @node Pragma CPP_Vtable,Pragma CPU,Pragma CPP_Virtual,Implementation Defined Pragmas | |
2827 | @anchor{gnat_rm/implementation_defined_pragmas pragma-cpp-vtable}@anchor{4a} | |
2828 | @section Pragma CPP_Vtable | |
2829 | ||
2830 | ||
2831 | @geindex Interfacing with C++ | |
2832 | ||
2833 | This pragma is now obsolete and, other than generating a warning if warnings | |
2834 | on obsolescent features are enabled, is completely ignored. | |
2835 | It used to be required to ensure compatibility with C++, but | |
2836 | is no longer required for that purpose because GNAT generates | |
2837 | the same object layout as the G++ compiler by default. | |
2838 | ||
2839 | See @ref{47,,Interfacing to C++} for related information. | |
2840 | ||
2841 | @node Pragma CPU,Pragma Deadline_Floor,Pragma CPP_Vtable,Implementation Defined Pragmas | |
2842 | @anchor{gnat_rm/implementation_defined_pragmas pragma-cpu}@anchor{4b} | |
2843 | @section Pragma CPU | |
2844 | ||
2845 | ||
2846 | Syntax: | |
2847 | ||
2848 | @example | |
2849 | pragma CPU (EXPRESSION); | |
2850 | @end example | |
2851 | ||
2852 | This pragma is standard in Ada 2012, but is available in all earlier | |
2853 | versions of Ada as an implementation-defined pragma. | |
2854 | See Ada 2012 Reference Manual for details. | |
2855 | ||
6f089469 | 2856 | @node Pragma Deadline_Floor,Pragma Debug,Pragma CPU,Implementation Defined Pragmas |
64d5610f ML |
2857 | @anchor{gnat_rm/implementation_defined_pragmas pragma-deadline-floor}@anchor{4c} |
2858 | @section Pragma Deadline_Floor | |
2859 | ||
2860 | ||
2861 | Syntax: | |
2862 | ||
2863 | @example | |
2864 | pragma Deadline_Floor (time_span_EXPRESSION); | |
2865 | @end example | |
2866 | ||
2867 | This pragma applies only to protected types and specifies the floor | |
2868 | deadline inherited by a task when the task enters a protected object. | |
2869 | It is effective only when the EDF scheduling policy is used. | |
2870 | ||
6f089469 RD |
2871 | @node Pragma Debug,Pragma Debug_Policy,Pragma Deadline_Floor,Implementation Defined Pragmas |
2872 | @anchor{gnat_rm/implementation_defined_pragmas pragma-debug}@anchor{4d} | |
64d5610f ML |
2873 | @section Pragma Debug |
2874 | ||
2875 | ||
2876 | Syntax: | |
2877 | ||
2878 | @example | |
2879 | pragma Debug ([CONDITION, ]PROCEDURE_CALL_WITHOUT_SEMICOLON); | |
2880 | ||
2881 | PROCEDURE_CALL_WITHOUT_SEMICOLON ::= | |
2882 | PROCEDURE_NAME | |
2883 | | PROCEDURE_PREFIX ACTUAL_PARAMETER_PART | |
2884 | @end example | |
2885 | ||
2886 | The procedure call argument has the syntactic form of an expression, meeting | |
2887 | the syntactic requirements for pragmas. | |
2888 | ||
2889 | If debug pragmas are not enabled or if the condition is present and evaluates | |
2890 | to False, this pragma has no effect. If debug pragmas are enabled, the | |
2891 | semantics of the pragma is exactly equivalent to the procedure call statement | |
2892 | corresponding to the argument with a terminating semicolon. Pragmas are | |
2893 | permitted in sequences of declarations, so you can use pragma @code{Debug} to | |
2894 | intersperse calls to debug procedures in the middle of declarations. Debug | |
2895 | pragmas can be enabled either by use of the command line switch `-gnata' | |
2896 | or by use of the pragma @code{Check_Policy} with a first argument of | |
2897 | @code{Debug}. | |
2898 | ||
6f089469 RD |
2899 | @node Pragma Debug_Policy,Pragma Default_Initial_Condition,Pragma Debug,Implementation Defined Pragmas |
2900 | @anchor{gnat_rm/implementation_defined_pragmas pragma-debug-policy}@anchor{4e} | |
64d5610f ML |
2901 | @section Pragma Debug_Policy |
2902 | ||
2903 | ||
2904 | Syntax: | |
2905 | ||
2906 | @example | |
2907 | pragma Debug_Policy (CHECK | DISABLE | IGNORE | ON | OFF); | |
2908 | @end example | |
2909 | ||
2910 | This pragma is equivalent to a corresponding @code{Check_Policy} pragma | |
2911 | with a first argument of @code{Debug}. It is retained for historical | |
2912 | compatibility reasons. | |
2913 | ||
6f089469 RD |
2914 | @node Pragma Default_Initial_Condition,Pragma Default_Scalar_Storage_Order,Pragma Debug_Policy,Implementation Defined Pragmas |
2915 | @anchor{gnat_rm/implementation_defined_pragmas id8}@anchor{4f}@anchor{gnat_rm/implementation_defined_pragmas pragma-default-initial-condition}@anchor{50} | |
2916 | @section Pragma Default_Initial_Condition | |
2917 | ||
2918 | ||
2919 | Syntax: | |
2920 | ||
2921 | @example | |
2922 | pragma Default_Initial_Condition [ (null | boolean_EXPRESSION) ]; | |
2923 | @end example | |
2924 | ||
2925 | For the semantics of this pragma, see the entry for aspect | |
2926 | @code{Default_Initial_Condition} in the SPARK 2014 Reference Manual, section 7.3.3. | |
2927 | ||
2928 | @node Pragma Default_Scalar_Storage_Order,Pragma Default_Storage_Pool,Pragma Default_Initial_Condition,Implementation Defined Pragmas | |
64d5610f ML |
2929 | @anchor{gnat_rm/implementation_defined_pragmas pragma-default-scalar-storage-order}@anchor{51} |
2930 | @section Pragma Default_Scalar_Storage_Order | |
2931 | ||
2932 | ||
2933 | @geindex Default_Scalar_Storage_Order | |
2934 | ||
2935 | @geindex Scalar_Storage_Order | |
2936 | ||
2937 | Syntax: | |
2938 | ||
2939 | @example | |
2940 | pragma Default_Scalar_Storage_Order (High_Order_First | Low_Order_First); | |
2941 | @end example | |
2942 | ||
2943 | Normally if no explicit @code{Scalar_Storage_Order} is given for a record | |
2944 | type or array type, then the scalar storage order defaults to the ordinary | |
2945 | default for the target. But this default may be overridden using this pragma. | |
2946 | The pragma may appear as a configuration pragma, or locally within a package | |
2947 | spec or declarative part. In the latter case, it applies to all subsequent | |
2948 | types declared within that package spec or declarative part. | |
2949 | ||
2950 | The following example shows the use of this pragma: | |
2951 | ||
2952 | @example | |
2953 | pragma Default_Scalar_Storage_Order (High_Order_First); | |
2954 | with System; use System; | |
2955 | package DSSO1 is | |
2956 | type H1 is record | |
2957 | a : Integer; | |
2958 | end record; | |
2959 | ||
2960 | type L2 is record | |
2961 | a : Integer; | |
2962 | end record; | |
2963 | for L2'Scalar_Storage_Order use Low_Order_First; | |
2964 | ||
2965 | type L2a is new L2; | |
2966 | ||
2967 | package Inner is | |
2968 | type H3 is record | |
2969 | a : Integer; | |
2970 | end record; | |
2971 | ||
2972 | pragma Default_Scalar_Storage_Order (Low_Order_First); | |
2973 | ||
2974 | type L4 is record | |
2975 | a : Integer; | |
2976 | end record; | |
2977 | end Inner; | |
2978 | ||
2979 | type H4a is new Inner.L4; | |
2980 | ||
2981 | type H5 is record | |
2982 | a : Integer; | |
2983 | end record; | |
2984 | end DSSO1; | |
2985 | @end example | |
2986 | ||
2987 | In this example record types with names starting with `L' have @cite{Low_Order_First} scalar | |
2988 | storage order, and record types with names starting with `H' have @code{High_Order_First}. | |
2989 | Note that in the case of @code{H4a}, the order is not inherited | |
2990 | from the parent type. Only an explicitly set @code{Scalar_Storage_Order} | |
2991 | gets inherited on type derivation. | |
2992 | ||
2993 | If this pragma is used as a configuration pragma which appears within a | |
2994 | configuration pragma file (as opposed to appearing explicitly at the start | |
2995 | of a single unit), then the binder will require that all units in a partition | |
2996 | be compiled in a similar manner, other than run-time units, which are not | |
2997 | affected by this pragma. Note that the use of this form is discouraged because | |
2998 | it may significantly degrade the run-time performance of the software, instead | |
2999 | the default scalar storage order ought to be changed only on a local basis. | |
3000 | ||
3001 | @node Pragma Default_Storage_Pool,Pragma Depends,Pragma Default_Scalar_Storage_Order,Implementation Defined Pragmas | |
3002 | @anchor{gnat_rm/implementation_defined_pragmas pragma-default-storage-pool}@anchor{52} | |
3003 | @section Pragma Default_Storage_Pool | |
3004 | ||
3005 | ||
3006 | @geindex Default_Storage_Pool | |
3007 | ||
3008 | Syntax: | |
3009 | ||
3010 | @example | |
3011 | pragma Default_Storage_Pool (storage_pool_NAME | null); | |
3012 | @end example | |
3013 | ||
3014 | This pragma is standard in Ada 2012, but is available in all earlier | |
3015 | versions of Ada as an implementation-defined pragma. | |
3016 | See Ada 2012 Reference Manual for details. | |
3017 | ||
3018 | @node Pragma Depends,Pragma Detect_Blocking,Pragma Default_Storage_Pool,Implementation Defined Pragmas | |
3019 | @anchor{gnat_rm/implementation_defined_pragmas id9}@anchor{53}@anchor{gnat_rm/implementation_defined_pragmas pragma-depends}@anchor{54} | |
3020 | @section Pragma Depends | |
3021 | ||
3022 | ||
3023 | Syntax: | |
3024 | ||
3025 | @example | |
3026 | pragma Depends (DEPENDENCY_RELATION); | |
3027 | ||
3028 | DEPENDENCY_RELATION ::= | |
3029 | null | |
3030 | | (DEPENDENCY_CLAUSE @{, DEPENDENCY_CLAUSE@}) | |
3031 | ||
3032 | DEPENDENCY_CLAUSE ::= | |
3033 | OUTPUT_LIST =>[+] INPUT_LIST | |
3034 | | NULL_DEPENDENCY_CLAUSE | |
3035 | ||
3036 | NULL_DEPENDENCY_CLAUSE ::= null => INPUT_LIST | |
3037 | ||
3038 | OUTPUT_LIST ::= OUTPUT | (OUTPUT @{, OUTPUT@}) | |
3039 | ||
3040 | INPUT_LIST ::= null | INPUT | (INPUT @{, INPUT@}) | |
3041 | ||
3042 | OUTPUT ::= NAME | FUNCTION_RESULT | |
3043 | INPUT ::= NAME | |
3044 | ||
3045 | where FUNCTION_RESULT is a function Result attribute_reference | |
3046 | @end example | |
3047 | ||
3048 | For the semantics of this pragma, see the entry for aspect @code{Depends} in the | |
3049 | SPARK 2014 Reference Manual, section 6.1.5. | |
3050 | ||
3051 | @node Pragma Detect_Blocking,Pragma Disable_Atomic_Synchronization,Pragma Depends,Implementation Defined Pragmas | |
3052 | @anchor{gnat_rm/implementation_defined_pragmas pragma-detect-blocking}@anchor{55} | |
3053 | @section Pragma Detect_Blocking | |
3054 | ||
3055 | ||
3056 | Syntax: | |
3057 | ||
3058 | @example | |
3059 | pragma Detect_Blocking; | |
3060 | @end example | |
3061 | ||
3062 | This is a standard pragma in Ada 2005, that is available in all earlier | |
3063 | versions of Ada as an implementation-defined pragma. | |
3064 | ||
3065 | This is a configuration pragma that forces the detection of potentially | |
3066 | blocking operations within a protected operation, and to raise Program_Error | |
3067 | if that happens. | |
3068 | ||
3069 | @node Pragma Disable_Atomic_Synchronization,Pragma Dispatching_Domain,Pragma Detect_Blocking,Implementation Defined Pragmas | |
3070 | @anchor{gnat_rm/implementation_defined_pragmas pragma-disable-atomic-synchronization}@anchor{56} | |
3071 | @section Pragma Disable_Atomic_Synchronization | |
3072 | ||
3073 | ||
3074 | @geindex Atomic Synchronization | |
3075 | ||
3076 | Syntax: | |
3077 | ||
3078 | @example | |
3079 | pragma Disable_Atomic_Synchronization [(Entity)]; | |
3080 | @end example | |
3081 | ||
3082 | Ada requires that accesses (reads or writes) of an atomic variable be | |
3083 | regarded as synchronization points in the case of multiple tasks. | |
3084 | Particularly in the case of multi-processors this may require special | |
3085 | handling, e.g. the generation of memory barriers. This capability may | |
3086 | be turned off using this pragma in cases where it is known not to be | |
3087 | required. | |
3088 | ||
3089 | The placement and scope rules for this pragma are the same as those | |
3090 | for @code{pragma Suppress}. In particular it can be used as a | |
3091 | configuration pragma, or in a declaration sequence where it applies | |
3092 | till the end of the scope. If an @code{Entity} argument is present, | |
3093 | the action applies only to that entity. | |
3094 | ||
3095 | @node Pragma Dispatching_Domain,Pragma Effective_Reads,Pragma Disable_Atomic_Synchronization,Implementation Defined Pragmas | |
3096 | @anchor{gnat_rm/implementation_defined_pragmas pragma-dispatching-domain}@anchor{57} | |
3097 | @section Pragma Dispatching_Domain | |
3098 | ||
3099 | ||
3100 | Syntax: | |
3101 | ||
3102 | @example | |
3103 | pragma Dispatching_Domain (EXPRESSION); | |
3104 | @end example | |
3105 | ||
3106 | This pragma is standard in Ada 2012, but is available in all earlier | |
3107 | versions of Ada as an implementation-defined pragma. | |
3108 | See Ada 2012 Reference Manual for details. | |
3109 | ||
3110 | @node Pragma Effective_Reads,Pragma Effective_Writes,Pragma Dispatching_Domain,Implementation Defined Pragmas | |
3111 | @anchor{gnat_rm/implementation_defined_pragmas id10}@anchor{58}@anchor{gnat_rm/implementation_defined_pragmas pragma-effective-reads}@anchor{59} | |
3112 | @section Pragma Effective_Reads | |
3113 | ||
3114 | ||
3115 | Syntax: | |
3116 | ||
3117 | @example | |
3118 | pragma Effective_Reads [ (static_boolean_EXPRESSION) ]; | |
3119 | @end example | |
3120 | ||
3121 | For the semantics of this pragma, see the entry for aspect @code{Effective_Reads} in | |
3122 | the SPARK 2014 Reference Manual, section 7.1.2. | |
3123 | ||
3124 | @node Pragma Effective_Writes,Pragma Elaboration_Checks,Pragma Effective_Reads,Implementation Defined Pragmas | |
3125 | @anchor{gnat_rm/implementation_defined_pragmas id11}@anchor{5a}@anchor{gnat_rm/implementation_defined_pragmas pragma-effective-writes}@anchor{5b} | |
3126 | @section Pragma Effective_Writes | |
3127 | ||
3128 | ||
3129 | Syntax: | |
3130 | ||
3131 | @example | |
3132 | pragma Effective_Writes [ (static_boolean_EXPRESSION) ]; | |
3133 | @end example | |
3134 | ||
3135 | For the semantics of this pragma, see the entry for aspect @code{Effective_Writes} | |
3136 | in the SPARK 2014 Reference Manual, section 7.1.2. | |
3137 | ||
3138 | @node Pragma Elaboration_Checks,Pragma Eliminate,Pragma Effective_Writes,Implementation Defined Pragmas | |
3139 | @anchor{gnat_rm/implementation_defined_pragmas pragma-elaboration-checks}@anchor{5c} | |
3140 | @section Pragma Elaboration_Checks | |
3141 | ||
3142 | ||
3143 | @geindex Elaboration control | |
3144 | ||
3145 | Syntax: | |
3146 | ||
3147 | @example | |
3148 | pragma Elaboration_Checks (Dynamic | Static); | |
3149 | @end example | |
3150 | ||
3151 | This is a configuration pragma which specifies the elaboration model to be | |
3152 | used during compilation. For more information on the elaboration models of | |
3153 | GNAT, consult the chapter on elaboration order handling in the `GNAT User’s | |
3154 | Guide'. | |
3155 | ||
3156 | The pragma may appear in the following contexts: | |
3157 | ||
3158 | ||
3159 | @itemize * | |
3160 | ||
3161 | @item | |
3162 | Configuration pragmas file | |
3163 | ||
3164 | @item | |
3165 | Prior to the context clauses of a compilation unit’s initial declaration | |
3166 | @end itemize | |
3167 | ||
3168 | Any other placement of the pragma will result in a warning and the effects of | |
3169 | the offending pragma will be ignored. | |
3170 | ||
3171 | If the pragma argument is @code{Dynamic}, then the dynamic elaboration model is in | |
3172 | effect. If the pragma argument is @code{Static}, then the static elaboration model | |
3173 | is in effect. | |
3174 | ||
3175 | @node Pragma Eliminate,Pragma Enable_Atomic_Synchronization,Pragma Elaboration_Checks,Implementation Defined Pragmas | |
3176 | @anchor{gnat_rm/implementation_defined_pragmas pragma-eliminate}@anchor{5d} | |
3177 | @section Pragma Eliminate | |
3178 | ||
3179 | ||
3180 | @geindex Elimination of unused subprograms | |
3181 | ||
3182 | Syntax: | |
3183 | ||
3184 | @example | |
3185 | pragma Eliminate ( | |
3186 | [ Unit_Name => ] IDENTIFIER | SELECTED_COMPONENT , | |
3187 | [ Entity => ] IDENTIFIER | | |
3188 | SELECTED_COMPONENT | | |
3189 | STRING_LITERAL | |
3190 | [, Source_Location => SOURCE_TRACE ] ); | |
3191 | ||
3192 | SOURCE_TRACE ::= STRING_LITERAL | |
3193 | @end example | |
3194 | ||
3195 | This pragma indicates that the given entity is not used in the program to be | |
3196 | compiled and built, thus allowing the compiler to | |
3197 | eliminate the code or data associated with the named entity. Any reference to | |
3198 | an eliminated entity causes a compile-time or link-time error. | |
3199 | ||
3200 | The pragma has the following semantics, where @code{U} is the unit specified by | |
3201 | the @code{Unit_Name} argument and @code{E} is the entity specified by the @code{Entity} | |
3202 | argument: | |
3203 | ||
3204 | ||
3205 | @itemize * | |
3206 | ||
3207 | @item | |
3208 | @code{E} must be a subprogram that is explicitly declared either: | |
3209 | ||
3210 | ||
3211 | @itemize * | |
3212 | ||
3213 | @item | |
3214 | Within @code{U}, or | |
3215 | ||
3216 | @item | |
3217 | Within a generic package that is instantiated in @code{U}, or | |
3218 | ||
3219 | @item | |
3220 | As an instance of generic subprogram instantiated in @code{U}. | |
3221 | @end itemize | |
3222 | ||
3223 | Otherwise the pragma is ignored. | |
3224 | ||
3225 | @item | |
3226 | If @code{E} is overloaded within @code{U} then, in the absence of a | |
3227 | @code{Source_Location} argument, all overloadings are eliminated. | |
3228 | ||
3229 | @item | |
3230 | If @code{E} is overloaded within @code{U} and only some overloadings | |
3231 | are to be eliminated, then each overloading to be eliminated | |
3232 | must be specified in a corresponding pragma @code{Eliminate} | |
3233 | with a @code{Source_Location} argument identifying the line where the | |
3234 | declaration appears, as described below. | |
3235 | ||
3236 | @item | |
3237 | If @code{E} is declared as the result of a generic instantiation, then | |
3238 | a @code{Source_Location} argument is needed, as described below. | |
3239 | @end itemize | |
3240 | ||
3241 | Pragma @code{Eliminate} allows a program to be compiled in a system-independent | |
3242 | manner, so that unused entities are eliminated but without | |
3243 | needing to modify the source text. Normally the required set of | |
3244 | @code{Eliminate} pragmas is constructed automatically using the @code{gnatelim} tool. | |
3245 | ||
3246 | Any source file change that removes, splits, or | |
3247 | adds lines may make the set of @code{Eliminate} pragmas invalid because their | |
3248 | @code{Source_Location} argument values may get out of date. | |
3249 | ||
3250 | Pragma @code{Eliminate} may be used where the referenced entity is a dispatching | |
3251 | operation. In this case all the subprograms to which the given operation can | |
3252 | dispatch are considered to be unused (are never called as a result of a direct | |
3253 | or a dispatching call). | |
3254 | ||
3255 | The string literal given for the source location specifies the line number | |
3256 | of the declaration of the entity, using the following syntax for @code{SOURCE_TRACE}: | |
3257 | ||
3258 | @example | |
3259 | SOURCE_TRACE ::= SOURCE_REFERENCE [ LBRACKET SOURCE_TRACE RBRACKET ] | |
3260 | ||
3261 | LBRACKET ::= '[' | |
3262 | RBRACKET ::= ']' | |
3263 | ||
3264 | SOURCE_REFERENCE ::= FILE_NAME : LINE_NUMBER | |
3265 | ||
3266 | LINE_NUMBER ::= DIGIT @{DIGIT@} | |
3267 | @end example | |
3268 | ||
3269 | Spaces around the colon in a @code{SOURCE_REFERENCE} are optional. | |
3270 | ||
3271 | The source trace that is given as the @code{Source_Location} must obey the | |
3272 | following rules (or else the pragma is ignored), where @code{U} is | |
3273 | the unit @code{U} specified by the @code{Unit_Name} argument and @code{E} is the | |
3274 | subprogram specified by the @code{Entity} argument: | |
3275 | ||
3276 | ||
3277 | @itemize * | |
3278 | ||
3279 | @item | |
3280 | @code{FILE_NAME} is the short name (with no directory | |
3281 | information) of the Ada source file for @code{U}, using the required syntax | |
3282 | for the underlying file system (e.g. case is significant if the underlying | |
3283 | operating system is case sensitive). | |
3284 | If @code{U} is a package and @code{E} is a subprogram declared in the package | |
3285 | specification and its full declaration appears in the package body, | |
3286 | then the relevant source file is the one for the package specification; | |
3287 | analogously if @code{U} is a generic package. | |
3288 | ||
3289 | @item | |
3290 | If @code{E} is not declared in a generic instantiation (this includes | |
3291 | generic subprogram instances), the source trace includes only one source | |
3292 | line reference. @code{LINE_NUMBER} gives the line number of the occurrence | |
3293 | of the declaration of @code{E} within the source file (as a decimal literal | |
3294 | without an exponent or point). | |
3295 | ||
3296 | @item | |
3297 | If @code{E} is declared by a generic instantiation, its source trace | |
3298 | (from left to right) starts with the source location of the | |
3299 | declaration of @code{E} in the generic unit and ends with the source | |
3300 | location of the instantiation, given in square brackets. This approach is | |
3301 | applied recursively with nested instantiations: the rightmost (nested | |
3302 | most deeply in square brackets) element of the source trace is the location | |
3303 | of the outermost instantiation, and the leftmost element (that is, outside | |
3304 | of any square brackets) is the location of the declaration of @code{E} in | |
3305 | the generic unit. | |
3306 | @end itemize | |
3307 | ||
3308 | Examples: | |
3309 | ||
3310 | @quotation | |
3311 | ||
3312 | @example | |
3313 | pragma Eliminate (Pkg0, Proc); | |
3314 | -- Eliminate (all overloadings of) Proc in Pkg0 | |
3315 | ||
3316 | pragma Eliminate (Pkg1, Proc, | |
3317 | Source_Location => "pkg1.ads:8"); | |
3318 | -- Eliminate overloading of Proc at line 8 in pkg1.ads | |
3319 | ||
3320 | -- Assume the following file contents: | |
3321 | -- gen_pkg.ads | |
3322 | -- 1: generic | |
3323 | -- 2: type T is private; | |
3324 | -- 3: package Gen_Pkg is | |
3325 | -- 4: procedure Proc(N : T); | |
3326 | -- ... ... | |
3327 | -- ... end Gen_Pkg; | |
3328 | -- | |
3329 | -- q.adb | |
3330 | -- 1: with Gen_Pkg; | |
3331 | -- 2: procedure Q is | |
3332 | -- 3: package Inst_Pkg is new Gen_Pkg(Integer); | |
3333 | -- ... -- No calls on Inst_Pkg.Proc | |
3334 | -- ... end Q; | |
3335 | ||
3336 | -- The following pragma eliminates Inst_Pkg.Proc from Q | |
3337 | pragma Eliminate (Q, Proc, | |
3338 | Source_Location => "gen_pkg.ads:4[q.adb:3]"); | |
3339 | @end example | |
3340 | @end quotation | |
3341 | ||
3342 | @node Pragma Enable_Atomic_Synchronization,Pragma Export_Function,Pragma Eliminate,Implementation Defined Pragmas | |
3343 | @anchor{gnat_rm/implementation_defined_pragmas pragma-enable-atomic-synchronization}@anchor{5e} | |
3344 | @section Pragma Enable_Atomic_Synchronization | |
3345 | ||
3346 | ||
3347 | @geindex Atomic Synchronization | |
3348 | ||
3349 | Syntax: | |
3350 | ||
3351 | @example | |
3352 | pragma Enable_Atomic_Synchronization [(Entity)]; | |
3353 | @end example | |
3354 | ||
3355 | Ada requires that accesses (reads or writes) of an atomic variable be | |
3356 | regarded as synchronization points in the case of multiple tasks. | |
3357 | Particularly in the case of multi-processors this may require special | |
3358 | handling, e.g. the generation of memory barriers. This synchronization | |
3359 | is performed by default, but can be turned off using | |
3360 | @code{pragma Disable_Atomic_Synchronization}. The | |
3361 | @code{Enable_Atomic_Synchronization} pragma can be used to turn | |
3362 | it back on. | |
3363 | ||
3364 | The placement and scope rules for this pragma are the same as those | |
3365 | for @code{pragma Unsuppress}. In particular it can be used as a | |
3366 | configuration pragma, or in a declaration sequence where it applies | |
3367 | till the end of the scope. If an @code{Entity} argument is present, | |
3368 | the action applies only to that entity. | |
3369 | ||
3370 | @node Pragma Export_Function,Pragma Export_Object,Pragma Enable_Atomic_Synchronization,Implementation Defined Pragmas | |
3371 | @anchor{gnat_rm/implementation_defined_pragmas pragma-export-function}@anchor{5f} | |
3372 | @section Pragma Export_Function | |
3373 | ||
3374 | ||
3375 | @geindex Argument passing mechanisms | |
3376 | ||
3377 | Syntax: | |
3378 | ||
3379 | @example | |
3380 | pragma Export_Function ( | |
3381 | [Internal =>] LOCAL_NAME | |
3382 | [, [External =>] EXTERNAL_SYMBOL] | |
3383 | [, [Parameter_Types =>] PARAMETER_TYPES] | |
3384 | [, [Result_Type =>] result_SUBTYPE_MARK] | |
3385 | [, [Mechanism =>] MECHANISM] | |
3386 | [, [Result_Mechanism =>] MECHANISM_NAME]); | |
3387 | ||
3388 | EXTERNAL_SYMBOL ::= | |
3389 | IDENTIFIER | |
3390 | | static_string_EXPRESSION | |
3391 | | "" | |
3392 | ||
3393 | PARAMETER_TYPES ::= | |
3394 | null | |
3395 | | TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} | |
3396 | ||
3397 | TYPE_DESIGNATOR ::= | |
3398 | subtype_NAME | |
3399 | | subtype_Name ' Access | |
3400 | ||
3401 | MECHANISM ::= | |
3402 | MECHANISM_NAME | |
3403 | | (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) | |
3404 | ||
3405 | MECHANISM_ASSOCIATION ::= | |
3406 | [formal_parameter_NAME =>] MECHANISM_NAME | |
3407 | ||
3408 | MECHANISM_NAME ::= Value | Reference | |
3409 | @end example | |
3410 | ||
3411 | Use this pragma to make a function externally callable and optionally | |
3412 | provide information on mechanisms to be used for passing parameter and | |
3413 | result values. We recommend, for the purposes of improving portability, | |
3414 | this pragma always be used in conjunction with a separate pragma | |
3415 | @code{Export}, which must precede the pragma @code{Export_Function}. | |
3416 | GNAT does not require a separate pragma @code{Export}, but if none is | |
3417 | present, @code{Convention Ada} is assumed, which is usually | |
3418 | not what is wanted, so it is usually appropriate to use this | |
3419 | pragma in conjunction with a @code{Export} or @code{Convention} | |
3420 | pragma that specifies the desired foreign convention. | |
3421 | Pragma @code{Export_Function} | |
3422 | (and @code{Export}, if present) must appear in the same declarative | |
3423 | region as the function to which they apply. | |
3424 | ||
3425 | The @code{internal_name} must uniquely designate the function to which the | |
3426 | pragma applies. If more than one function name exists of this name in | |
3427 | the declarative part you must use the @code{Parameter_Types} and | |
3428 | @code{Result_Type} parameters to achieve the required | |
3429 | unique designation. The @cite{subtype_mark}s in these parameters must | |
3430 | exactly match the subtypes in the corresponding function specification, | |
3431 | using positional notation to match parameters with subtype marks. | |
3432 | The form with an @code{'Access} attribute can be used to match an | |
3433 | anonymous access parameter. | |
3434 | ||
3435 | @geindex Suppressing external name | |
3436 | ||
3437 | Special treatment is given if the EXTERNAL is an explicit null | |
3438 | string or a static string expressions that evaluates to the null | |
3439 | string. In this case, no external name is generated. This form | |
3440 | still allows the specification of parameter mechanisms. | |
3441 | ||
3442 | @node Pragma Export_Object,Pragma Export_Procedure,Pragma Export_Function,Implementation Defined Pragmas | |
3443 | @anchor{gnat_rm/implementation_defined_pragmas pragma-export-object}@anchor{60} | |
3444 | @section Pragma Export_Object | |
3445 | ||
3446 | ||
3447 | Syntax: | |
3448 | ||
3449 | @example | |
3450 | pragma Export_Object ( | |
3451 | [Internal =>] LOCAL_NAME | |
3452 | [, [External =>] EXTERNAL_SYMBOL] | |
3453 | [, [Size =>] EXTERNAL_SYMBOL]); | |
3454 | ||
3455 | EXTERNAL_SYMBOL ::= | |
3456 | IDENTIFIER | |
3457 | | static_string_EXPRESSION | |
3458 | @end example | |
3459 | ||
3460 | This pragma designates an object as exported, and apart from the | |
3461 | extended rules for external symbols, is identical in effect to the use of | |
3462 | the normal @code{Export} pragma applied to an object. You may use a | |
3463 | separate Export pragma (and you probably should from the point of view | |
3464 | of portability), but it is not required. @code{Size} is syntax checked, | |
3465 | but otherwise ignored by GNAT. | |
3466 | ||
3467 | @node Pragma Export_Procedure,Pragma Export_Valued_Procedure,Pragma Export_Object,Implementation Defined Pragmas | |
3468 | @anchor{gnat_rm/implementation_defined_pragmas pragma-export-procedure}@anchor{61} | |
3469 | @section Pragma Export_Procedure | |
3470 | ||
3471 | ||
3472 | Syntax: | |
3473 | ||
3474 | @example | |
3475 | pragma Export_Procedure ( | |
3476 | [Internal =>] LOCAL_NAME | |
3477 | [, [External =>] EXTERNAL_SYMBOL] | |
3478 | [, [Parameter_Types =>] PARAMETER_TYPES] | |
3479 | [, [Mechanism =>] MECHANISM]); | |
3480 | ||
3481 | EXTERNAL_SYMBOL ::= | |
3482 | IDENTIFIER | |
3483 | | static_string_EXPRESSION | |
3484 | | "" | |
3485 | ||
3486 | PARAMETER_TYPES ::= | |
3487 | null | |
3488 | | TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} | |
3489 | ||
3490 | TYPE_DESIGNATOR ::= | |
3491 | subtype_NAME | |
3492 | | subtype_Name ' Access | |
3493 | ||
3494 | MECHANISM ::= | |
3495 | MECHANISM_NAME | |
3496 | | (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) | |
3497 | ||
3498 | MECHANISM_ASSOCIATION ::= | |
3499 | [formal_parameter_NAME =>] MECHANISM_NAME | |
3500 | ||
3501 | MECHANISM_NAME ::= Value | Reference | |
3502 | @end example | |
3503 | ||
3504 | This pragma is identical to @code{Export_Function} except that it | |
3505 | applies to a procedure rather than a function and the parameters | |
3506 | @code{Result_Type} and @code{Result_Mechanism} are not permitted. | |
3507 | GNAT does not require a separate pragma @code{Export}, but if none is | |
3508 | present, @code{Convention Ada} is assumed, which is usually | |
3509 | not what is wanted, so it is usually appropriate to use this | |
3510 | pragma in conjunction with a @code{Export} or @code{Convention} | |
3511 | pragma that specifies the desired foreign convention. | |
3512 | ||
3513 | @geindex Suppressing external name | |
3514 | ||
3515 | Special treatment is given if the EXTERNAL is an explicit null | |
3516 | string or a static string expressions that evaluates to the null | |
3517 | string. In this case, no external name is generated. This form | |
3518 | still allows the specification of parameter mechanisms. | |
3519 | ||
3520 | @node Pragma Export_Valued_Procedure,Pragma Extend_System,Pragma Export_Procedure,Implementation Defined Pragmas | |
3521 | @anchor{gnat_rm/implementation_defined_pragmas pragma-export-valued-procedure}@anchor{62} | |
3522 | @section Pragma Export_Valued_Procedure | |
3523 | ||
3524 | ||
3525 | Syntax: | |
3526 | ||
3527 | @example | |
3528 | pragma Export_Valued_Procedure ( | |
3529 | [Internal =>] LOCAL_NAME | |
3530 | [, [External =>] EXTERNAL_SYMBOL] | |
3531 | [, [Parameter_Types =>] PARAMETER_TYPES] | |
3532 | [, [Mechanism =>] MECHANISM]); | |
3533 | ||
3534 | EXTERNAL_SYMBOL ::= | |
3535 | IDENTIFIER | |
3536 | | static_string_EXPRESSION | |
3537 | | "" | |
3538 | ||
3539 | PARAMETER_TYPES ::= | |
3540 | null | |
3541 | | TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} | |
3542 | ||
3543 | TYPE_DESIGNATOR ::= | |
3544 | subtype_NAME | |
3545 | | subtype_Name ' Access | |
3546 | ||
3547 | MECHANISM ::= | |
3548 | MECHANISM_NAME | |
3549 | | (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) | |
3550 | ||
3551 | MECHANISM_ASSOCIATION ::= | |
3552 | [formal_parameter_NAME =>] MECHANISM_NAME | |
3553 | ||
3554 | MECHANISM_NAME ::= Value | Reference | |
3555 | @end example | |
3556 | ||
3557 | This pragma is identical to @code{Export_Procedure} except that the | |
3558 | first parameter of @code{LOCAL_NAME}, which must be present, must be of | |
3559 | mode @code{out}, and externally the subprogram is treated as a function | |
3560 | with this parameter as the result of the function. GNAT provides for | |
3561 | this capability to allow the use of @code{out} and @code{in out} | |
3562 | parameters in interfacing to external functions (which are not permitted | |
3563 | in Ada functions). | |
3564 | GNAT does not require a separate pragma @code{Export}, but if none is | |
3565 | present, @code{Convention Ada} is assumed, which is almost certainly | |
3566 | not what is wanted since the whole point of this pragma is to interface | |
3567 | with foreign language functions, so it is usually appropriate to use this | |
3568 | pragma in conjunction with a @code{Export} or @code{Convention} | |
3569 | pragma that specifies the desired foreign convention. | |
3570 | ||
3571 | @geindex Suppressing external name | |
3572 | ||
3573 | Special treatment is given if the EXTERNAL is an explicit null | |
3574 | string or a static string expressions that evaluates to the null | |
3575 | string. In this case, no external name is generated. This form | |
3576 | still allows the specification of parameter mechanisms. | |
3577 | ||
3578 | @node Pragma Extend_System,Pragma Extensions_Allowed,Pragma Export_Valued_Procedure,Implementation Defined Pragmas | |
3579 | @anchor{gnat_rm/implementation_defined_pragmas pragma-extend-system}@anchor{63} | |
3580 | @section Pragma Extend_System | |
3581 | ||
3582 | ||
3583 | @geindex System | |
3584 | @geindex extending | |
3585 | ||
3586 | @geindex DEC Ada 83 | |
3587 | ||
3588 | Syntax: | |
3589 | ||
3590 | @example | |
3591 | pragma Extend_System ([Name =>] IDENTIFIER); | |
3592 | @end example | |
3593 | ||
3594 | This pragma is used to provide backwards compatibility with other | |
3595 | implementations that extend the facilities of package @code{System}. In | |
3596 | GNAT, @code{System} contains only the definitions that are present in | |
3597 | the Ada RM. However, other implementations, notably the DEC Ada 83 | |
3598 | implementation, provide many extensions to package @code{System}. | |
3599 | ||
3600 | For each such implementation accommodated by this pragma, GNAT provides a | |
3601 | package @code{Aux_@var{xxx}}, e.g., @code{Aux_DEC} for the DEC Ada 83 | |
3602 | implementation, which provides the required additional definitions. You | |
3603 | can use this package in two ways. You can @code{with} it in the normal | |
3604 | way and access entities either by selection or using a @code{use} | |
3605 | clause. In this case no special processing is required. | |
3606 | ||
3607 | However, if existing code contains references such as | |
3608 | @code{System.@var{xxx}} where `xxx' is an entity in the extended | |
3609 | definitions provided in package @code{System}, you may use this pragma | |
3610 | to extend visibility in @code{System} in a non-standard way that | |
3611 | provides greater compatibility with the existing code. Pragma | |
3612 | @code{Extend_System} is a configuration pragma whose single argument is | |
3613 | the name of the package containing the extended definition | |
3614 | (e.g., @code{Aux_DEC} for the DEC Ada case). A unit compiled under | |
3615 | control of this pragma will be processed using special visibility | |
3616 | processing that looks in package @code{System.Aux_@var{xxx}} where | |
3617 | @code{Aux_@var{xxx}} is the pragma argument for any entity referenced in | |
3618 | package @code{System}, but not found in package @code{System}. | |
3619 | ||
3620 | You can use this pragma either to access a predefined @code{System} | |
3621 | extension supplied with the compiler, for example @code{Aux_DEC} or | |
3622 | you can construct your own extension unit following the above | |
3623 | definition. Note that such a package is a child of @code{System} | |
3624 | and thus is considered part of the implementation. | |
3625 | To compile it you will have to use the `-gnatg' switch | |
3626 | for compiling System units, as explained in the | |
3627 | GNAT User’s Guide. | |
3628 | ||
3629 | @node Pragma Extensions_Allowed,Pragma Extensions_Visible,Pragma Extend_System,Implementation Defined Pragmas | |
b71d4b62 | 3630 | @anchor{gnat_rm/implementation_defined_pragmas id12}@anchor{64}@anchor{gnat_rm/implementation_defined_pragmas pragma-extensions-allowed}@anchor{65} |
64d5610f ML |
3631 | @section Pragma Extensions_Allowed |
3632 | ||
3633 | ||
3634 | @geindex Ada Extensions | |
3635 | ||
3636 | @geindex GNAT Extensions | |
3637 | ||
3638 | Syntax: | |
3639 | ||
3640 | @example | |
3641 | pragma Extensions_Allowed (On | Off | All); | |
3642 | @end example | |
3643 | ||
3644 | This configuration pragma enables (via the “On” or “All” argument) or disables | |
3645 | (via the “Off” argument) the implementation extension mode; the pragma takes | |
b71d4b62 | 3646 | precedence over the @code{-gnatX} and @code{-gnatX0} command switches. |
64d5610f | 3647 | |
b71d4b62 RA |
3648 | If an argument of @code{"On"} is specified, the latest version of the Ada language |
3649 | is implemented (currently Ada 2022) and, in addition, a curated set of GNAT | |
3650 | specific extensions are recognized. (See the list here | |
3651 | @ref{66,,here}) | |
64d5610f | 3652 | |
b71d4b62 RA |
3653 | An argument of @code{"All"} has the same effect except that some extra |
3654 | experimental extensions are enabled (See the list here | |
3655 | @ref{67,,here}) | |
64d5610f | 3656 | |
b71d4b62 RA |
3657 | @node Pragma Extensions_Visible,Pragma External,Pragma Extensions_Allowed,Implementation Defined Pragmas |
3658 | @anchor{gnat_rm/implementation_defined_pragmas id13}@anchor{68}@anchor{gnat_rm/implementation_defined_pragmas pragma-extensions-visible}@anchor{69} | |
3659 | @section Pragma Extensions_Visible | |
64d5610f | 3660 | |
64d5610f | 3661 | |
b71d4b62 | 3662 | Syntax: |
64d5610f | 3663 | |
b71d4b62 RA |
3664 | @example |
3665 | pragma Extensions_Visible [ (static_boolean_EXPRESSION) ]; | |
3666 | @end example | |
64d5610f | 3667 | |
b71d4b62 RA |
3668 | For the semantics of this pragma, see the entry for aspect @code{Extensions_Visible} |
3669 | in the SPARK 2014 Reference Manual, section 6.1.7. | |
64d5610f | 3670 | |
b71d4b62 RA |
3671 | @node Pragma External,Pragma External_Name_Casing,Pragma Extensions_Visible,Implementation Defined Pragmas |
3672 | @anchor{gnat_rm/implementation_defined_pragmas pragma-external}@anchor{6a} | |
3673 | @section Pragma External | |
64d5610f | 3674 | |
64d5610f | 3675 | |
b71d4b62 | 3676 | Syntax: |
64d5610f ML |
3677 | |
3678 | @example | |
b71d4b62 RA |
3679 | pragma External ( |
3680 | [ Convention =>] convention_IDENTIFIER, | |
3681 | [ Entity =>] LOCAL_NAME | |
3682 | [, [External_Name =>] static_string_EXPRESSION ] | |
3683 | [, [Link_Name =>] static_string_EXPRESSION ]); | |
64d5610f ML |
3684 | @end example |
3685 | ||
b71d4b62 RA |
3686 | This pragma is identical in syntax and semantics to pragma |
3687 | @code{Export} as defined in the Ada Reference Manual. It is | |
3688 | provided for compatibility with some Ada 83 compilers that | |
3689 | used this pragma for exactly the same purposes as pragma | |
3690 | @code{Export} before the latter was standardized. | |
64d5610f | 3691 | |
b71d4b62 RA |
3692 | @node Pragma External_Name_Casing,Pragma Fast_Math,Pragma External,Implementation Defined Pragmas |
3693 | @anchor{gnat_rm/implementation_defined_pragmas pragma-external-name-casing}@anchor{6b} | |
3694 | @section Pragma External_Name_Casing | |
64d5610f | 3695 | |
64d5610f | 3696 | |
b71d4b62 | 3697 | @geindex Dec Ada 83 casing compatibility |
64d5610f | 3698 | |
b71d4b62 RA |
3699 | @geindex External Names |
3700 | @geindex casing | |
64d5610f | 3701 | |
b71d4b62 | 3702 | @geindex Casing of External names |
64d5610f | 3703 | |
b71d4b62 | 3704 | Syntax: |
64d5610f | 3705 | |
b71d4b62 RA |
3706 | @example |
3707 | pragma External_Name_Casing ( | |
3708 | Uppercase | Lowercase | |
3709 | [, Uppercase | Lowercase | As_Is]); | |
3710 | @end example | |
64d5610f | 3711 | |
b71d4b62 RA |
3712 | This pragma provides control over the casing of external names associated |
3713 | with Import and Export pragmas. There are two cases to consider: | |
64d5610f | 3714 | |
64d5610f | 3715 | |
b71d4b62 | 3716 | @itemize * |
64d5610f ML |
3717 | |
3718 | @item | |
b71d4b62 | 3719 | Implicit external names |
64d5610f | 3720 | |
b71d4b62 RA |
3721 | Implicit external names are derived from identifiers. The most common case |
3722 | arises when a standard Ada Import or Export pragma is used with only two | |
3723 | arguments, as in: | |
64d5610f ML |
3724 | |
3725 | @example | |
b71d4b62 | 3726 | pragma Import (C, C_Routine); |
64d5610f ML |
3727 | @end example |
3728 | ||
b71d4b62 RA |
3729 | Since Ada is a case-insensitive language, the spelling of the identifier in |
3730 | the Ada source program does not provide any information on the desired | |
3731 | casing of the external name, and so a convention is needed. In GNAT the | |
3732 | default treatment is that such names are converted to all lower case | |
3733 | letters. This corresponds to the normal C style in many environments. | |
3734 | The first argument of pragma @code{External_Name_Casing} can be used to | |
3735 | control this treatment. If @code{Uppercase} is specified, then the name | |
3736 | will be forced to all uppercase letters. If @code{Lowercase} is specified, | |
3737 | then the normal default of all lower case letters will be used. | |
64d5610f | 3738 | |
b71d4b62 RA |
3739 | This same implicit treatment is also used in the case of extended DEC Ada 83 |
3740 | compatible Import and Export pragmas where an external name is explicitly | |
3741 | specified using an identifier rather than a string. | |
64d5610f ML |
3742 | |
3743 | @item | |
b71d4b62 | 3744 | Explicit external names |
64d5610f | 3745 | |
b71d4b62 RA |
3746 | Explicit external names are given as string literals. The most common case |
3747 | arises when a standard Ada Import or Export pragma is used with three | |
3748 | arguments, as in: | |
64d5610f ML |
3749 | |
3750 | @example | |
b71d4b62 | 3751 | pragma Import (C, C_Routine, "C_routine"); |
64d5610f ML |
3752 | @end example |
3753 | ||
b71d4b62 RA |
3754 | In this case, the string literal normally provides the exact casing required |
3755 | for the external name. The second argument of pragma | |
3756 | @code{External_Name_Casing} may be used to modify this behavior. | |
3757 | If @code{Uppercase} is specified, then the name | |
3758 | will be forced to all uppercase letters. If @code{Lowercase} is specified, | |
3759 | then the name will be forced to all lowercase letters. A specification of | |
3760 | @code{As_Is} provides the normal default behavior in which the casing is | |
3761 | taken from the string provided. | |
3762 | @end itemize | |
64d5610f | 3763 | |
b71d4b62 RA |
3764 | This pragma may appear anywhere that a pragma is valid. In particular, it |
3765 | can be used as a configuration pragma in the @code{gnat.adc} file, in which | |
3766 | case it applies to all subsequent compilations, or it can be used as a program | |
3767 | unit pragma, in which case it only applies to the current unit, or it can | |
3768 | be used more locally to control individual Import/Export pragmas. | |
64d5610f | 3769 | |
b71d4b62 RA |
3770 | It was primarily intended for use with OpenVMS systems, where many |
3771 | compilers convert all symbols to upper case by default. For interfacing to | |
3772 | such compilers (e.g., the DEC C compiler), it may be convenient to use | |
3773 | the pragma: | |
64d5610f ML |
3774 | |
3775 | @example | |
b71d4b62 | 3776 | pragma External_Name_Casing (Uppercase, Uppercase); |
64d5610f | 3777 | @end example |
64d5610f | 3778 | |
b71d4b62 | 3779 | to enforce the upper casing of all external symbols. |
64d5610f | 3780 | |
b71d4b62 RA |
3781 | @node Pragma Fast_Math,Pragma Favor_Top_Level,Pragma External_Name_Casing,Implementation Defined Pragmas |
3782 | @anchor{gnat_rm/implementation_defined_pragmas pragma-fast-math}@anchor{6c} | |
3783 | @section Pragma Fast_Math | |
64d5610f | 3784 | |
64d5610f | 3785 | |
b71d4b62 | 3786 | Syntax: |
64d5610f | 3787 | |
b71d4b62 RA |
3788 | @example |
3789 | pragma Fast_Math; | |
3790 | @end example | |
64d5610f | 3791 | |
b71d4b62 RA |
3792 | This is a configuration pragma which activates a mode in which speed is |
3793 | considered more important for floating-point operations than absolutely | |
3794 | accurate adherence to the requirements of the standard. Currently the | |
3795 | following operations are affected: | |
64d5610f | 3796 | |
64d5610f | 3797 | |
b71d4b62 | 3798 | @table @asis |
64d5610f | 3799 | |
b71d4b62 | 3800 | @item `Complex Multiplication' |
64d5610f | 3801 | |
b71d4b62 RA |
3802 | The normal simple formula for complex multiplication can result in intermediate |
3803 | overflows for numbers near the end of the range. The Ada standard requires that | |
3804 | this situation be detected and corrected by scaling, but in Fast_Math mode such | |
3805 | cases will simply result in overflow. Note that to take advantage of this you | |
3806 | must instantiate your own version of @code{Ada.Numerics.Generic_Complex_Types} | |
3807 | under control of the pragma, rather than use the preinstantiated versions. | |
3808 | @end table | |
64d5610f | 3809 | |
b71d4b62 RA |
3810 | @node Pragma Favor_Top_Level,Pragma Finalize_Storage_Only,Pragma Fast_Math,Implementation Defined Pragmas |
3811 | @anchor{gnat_rm/implementation_defined_pragmas id14}@anchor{6d}@anchor{gnat_rm/implementation_defined_pragmas pragma-favor-top-level}@anchor{6e} | |
3812 | @section Pragma Favor_Top_Level | |
64d5610f | 3813 | |
64d5610f | 3814 | |
b71d4b62 | 3815 | Syntax: |
64d5610f | 3816 | |
b71d4b62 RA |
3817 | @example |
3818 | pragma Favor_Top_Level (type_NAME); | |
64d5610f | 3819 | @end example |
b7d26cb1 | 3820 | |
b71d4b62 RA |
3821 | The argument of pragma @code{Favor_Top_Level} must be a named access-to-subprogram |
3822 | type. This pragma is an efficiency hint to the compiler, regarding the use of | |
3823 | @code{'Access} or @code{'Unrestricted_Access} on nested (non-library-level) subprograms. | |
3824 | The pragma means that nested subprograms are not used with this type, or are | |
3825 | rare, so that the generated code should be efficient in the top-level case. | |
3826 | When this pragma is used, dynamically generated trampolines may be used on some | |
3827 | targets for nested subprograms. See restriction @code{No_Implicit_Dynamic_Code}. | |
b7d26cb1 | 3828 | |
b71d4b62 RA |
3829 | @node Pragma Finalize_Storage_Only,Pragma Float_Representation,Pragma Favor_Top_Level,Implementation Defined Pragmas |
3830 | @anchor{gnat_rm/implementation_defined_pragmas pragma-finalize-storage-only}@anchor{6f} | |
3831 | @section Pragma Finalize_Storage_Only | |
b7d26cb1 | 3832 | |
b7d26cb1 | 3833 | |
b71d4b62 | 3834 | Syntax: |
b7d26cb1 JM |
3835 | |
3836 | @example | |
b71d4b62 | 3837 | pragma Finalize_Storage_Only (first_subtype_LOCAL_NAME); |
b7d26cb1 JM |
3838 | @end example |
3839 | ||
b71d4b62 RA |
3840 | The argument of pragma @code{Finalize_Storage_Only} must denote a local type which |
3841 | is derived from @code{Ada.Finalization.Controlled} or @code{Limited_Controlled}. The | |
3842 | pragma suppresses the call to @code{Finalize} for declared library-level objects | |
3843 | of the argument type. This is mostly useful for types where finalization is | |
3844 | only used to deal with storage reclamation since in most environments it is | |
3845 | not necessary to reclaim memory just before terminating execution, hence the | |
3846 | name. Note that this pragma does not suppress Finalize calls for library-level | |
3847 | heap-allocated objects (see pragma @code{No_Heap_Finalization}). | |
b7d26cb1 | 3848 | |
b71d4b62 RA |
3849 | @node Pragma Float_Representation,Pragma Ghost,Pragma Finalize_Storage_Only,Implementation Defined Pragmas |
3850 | @anchor{gnat_rm/implementation_defined_pragmas pragma-float-representation}@anchor{70} | |
3851 | @section Pragma Float_Representation | |
b7d26cb1 | 3852 | |
b7d26cb1 | 3853 | |
b71d4b62 | 3854 | Syntax: |
b7d26cb1 | 3855 | |
b71d4b62 RA |
3856 | @example |
3857 | pragma Float_Representation (FLOAT_REP[, float_type_LOCAL_NAME]); | |
b7d26cb1 | 3858 | |
b71d4b62 RA |
3859 | FLOAT_REP ::= VAX_Float | IEEE_Float |
3860 | @end example | |
b7d26cb1 | 3861 | |
b71d4b62 RA |
3862 | In the one argument form, this pragma is a configuration pragma which |
3863 | allows control over the internal representation chosen for the predefined | |
3864 | floating point types declared in the packages @code{Standard} and | |
3865 | @code{System}. This pragma is only provided for compatibility and has no effect. | |
b7d26cb1 | 3866 | |
b71d4b62 RA |
3867 | The two argument form specifies the representation to be used for |
3868 | the specified floating-point type. The argument must | |
3869 | be @code{IEEE_Float} to specify the use of IEEE format, as follows: | |
b7d26cb1 | 3870 | |
b7d26cb1 | 3871 | |
b71d4b62 | 3872 | @itemize * |
b7d26cb1 | 3873 | |
b71d4b62 RA |
3874 | @item |
3875 | For a digits value of 6, 32-bit IEEE short format will be used. | |
b7d26cb1 | 3876 | |
b71d4b62 RA |
3877 | @item |
3878 | For a digits value of 15, 64-bit IEEE long format will be used. | |
b7d26cb1 | 3879 | |
b71d4b62 RA |
3880 | @item |
3881 | No other value of digits is permitted. | |
3882 | @end itemize | |
b7d26cb1 | 3883 | |
b71d4b62 RA |
3884 | @node Pragma Ghost,Pragma Global,Pragma Float_Representation,Implementation Defined Pragmas |
3885 | @anchor{gnat_rm/implementation_defined_pragmas id15}@anchor{71}@anchor{gnat_rm/implementation_defined_pragmas pragma-ghost}@anchor{72} | |
3886 | @section Pragma Ghost | |
b7d26cb1 | 3887 | |
b7d26cb1 | 3888 | |
b71d4b62 | 3889 | Syntax: |
b7d26cb1 | 3890 | |
b71d4b62 RA |
3891 | @example |
3892 | pragma Ghost [ (static_boolean_EXPRESSION) ]; | |
3893 | @end example | |
b7d26cb1 | 3894 | |
b71d4b62 RA |
3895 | For the semantics of this pragma, see the entry for aspect @code{Ghost} in the SPARK |
3896 | 2014 Reference Manual, section 6.9. | |
b7d26cb1 | 3897 | |
b71d4b62 RA |
3898 | @node Pragma Global,Pragma Ident,Pragma Ghost,Implementation Defined Pragmas |
3899 | @anchor{gnat_rm/implementation_defined_pragmas id16}@anchor{73}@anchor{gnat_rm/implementation_defined_pragmas pragma-global}@anchor{74} | |
3900 | @section Pragma Global | |
b7d26cb1 | 3901 | |
b7d26cb1 | 3902 | |
b71d4b62 | 3903 | Syntax: |
b7d26cb1 | 3904 | |
b71d4b62 RA |
3905 | @example |
3906 | pragma Global (GLOBAL_SPECIFICATION); | |
b7d26cb1 | 3907 | |
b71d4b62 RA |
3908 | GLOBAL_SPECIFICATION ::= |
3909 | null | |
3910 | | (GLOBAL_LIST) | |
3911 | | (MODED_GLOBAL_LIST @{, MODED_GLOBAL_LIST@}) | |
b7d26cb1 | 3912 | |
b71d4b62 | 3913 | MODED_GLOBAL_LIST ::= MODE_SELECTOR => GLOBAL_LIST |
b7d26cb1 | 3914 | |
b71d4b62 RA |
3915 | MODE_SELECTOR ::= In_Out | Input | Output | Proof_In |
3916 | GLOBAL_LIST ::= GLOBAL_ITEM | (GLOBAL_ITEM @{, GLOBAL_ITEM@}) | |
3917 | GLOBAL_ITEM ::= NAME | |
3918 | @end example | |
b7d26cb1 | 3919 | |
b71d4b62 RA |
3920 | For the semantics of this pragma, see the entry for aspect @code{Global} in the |
3921 | SPARK 2014 Reference Manual, section 6.1.4. | |
b7d26cb1 | 3922 | |
b71d4b62 RA |
3923 | @node Pragma Ident,Pragma Ignore_Pragma,Pragma Global,Implementation Defined Pragmas |
3924 | @anchor{gnat_rm/implementation_defined_pragmas pragma-ident}@anchor{75} | |
3925 | @section Pragma Ident | |
b7d26cb1 | 3926 | |
b7d26cb1 | 3927 | |
b71d4b62 | 3928 | Syntax: |
b7d26cb1 | 3929 | |
b71d4b62 RA |
3930 | @example |
3931 | pragma Ident (static_string_EXPRESSION); | |
3932 | @end example | |
b7d26cb1 | 3933 | |
b71d4b62 RA |
3934 | This pragma is identical in effect to pragma @code{Comment}. It is provided |
3935 | for compatibility with other Ada compilers providing this pragma. | |
b7d26cb1 | 3936 | |
b71d4b62 RA |
3937 | @node Pragma Ignore_Pragma,Pragma Implementation_Defined,Pragma Ident,Implementation Defined Pragmas |
3938 | @anchor{gnat_rm/implementation_defined_pragmas pragma-ignore-pragma}@anchor{76} | |
3939 | @section Pragma Ignore_Pragma | |
b7d26cb1 | 3940 | |
b7d26cb1 | 3941 | |
b71d4b62 | 3942 | Syntax: |
b7d26cb1 | 3943 | |
b71d4b62 RA |
3944 | @example |
3945 | pragma Ignore_Pragma (pragma_IDENTIFIER); | |
3946 | @end example | |
b7d26cb1 | 3947 | |
b71d4b62 RA |
3948 | This is a configuration pragma |
3949 | that takes a single argument that is a simple identifier. Any subsequent | |
3950 | use of a pragma whose pragma identifier matches this argument will be | |
3951 | silently ignored. This may be useful when legacy code or code intended | |
3952 | for compilation with some other compiler contains pragmas that match the | |
3953 | name, but not the exact implementation, of a GNAT pragma. The use of this | |
3954 | pragma allows such pragmas to be ignored, which may be useful in CodePeer | |
3955 | mode, or during porting of legacy code. | |
b7d26cb1 | 3956 | |
b71d4b62 RA |
3957 | @node Pragma Implementation_Defined,Pragma Implemented,Pragma Ignore_Pragma,Implementation Defined Pragmas |
3958 | @anchor{gnat_rm/implementation_defined_pragmas pragma-implementation-defined}@anchor{77} | |
3959 | @section Pragma Implementation_Defined | |
b7d26cb1 | 3960 | |
b7d26cb1 | 3961 | |
b71d4b62 | 3962 | Syntax: |
b7d26cb1 | 3963 | |
b71d4b62 RA |
3964 | @example |
3965 | pragma Implementation_Defined (local_NAME); | |
3966 | @end example | |
b7d26cb1 | 3967 | |
b71d4b62 RA |
3968 | This pragma marks a previously declared entity as implementation-defined. |
3969 | For an overloaded entity, applies to the most recent homonym. | |
b7d26cb1 | 3970 | |
b71d4b62 RA |
3971 | @example |
3972 | pragma Implementation_Defined; | |
3973 | @end example | |
b7d26cb1 | 3974 | |
b71d4b62 RA |
3975 | The form with no arguments appears anywhere within a scope, most |
3976 | typically a package spec, and indicates that all entities that are | |
3977 | defined within the package spec are Implementation_Defined. | |
b7d26cb1 | 3978 | |
b71d4b62 RA |
3979 | This pragma is used within the GNAT runtime library to identify |
3980 | implementation-defined entities introduced in language-defined units, | |
3981 | for the purpose of implementing the No_Implementation_Identifiers | |
3982 | restriction. | |
b7d26cb1 | 3983 | |
b71d4b62 RA |
3984 | @node Pragma Implemented,Pragma Implicit_Packing,Pragma Implementation_Defined,Implementation Defined Pragmas |
3985 | @anchor{gnat_rm/implementation_defined_pragmas pragma-implemented}@anchor{78} | |
3986 | @section Pragma Implemented | |
b7d26cb1 | 3987 | |
b7d26cb1 | 3988 | |
b71d4b62 | 3989 | Syntax: |
b7d26cb1 | 3990 | |
b71d4b62 RA |
3991 | @example |
3992 | pragma Implemented (procedure_LOCAL_NAME, implementation_kind); | |
b7d26cb1 | 3993 | |
b71d4b62 RA |
3994 | implementation_kind ::= By_Entry | By_Protected_Procedure | By_Any |
3995 | @end example | |
b7d26cb1 | 3996 | |
b71d4b62 RA |
3997 | This is an Ada 2012 representation pragma which applies to protected, task |
3998 | and synchronized interface primitives. The use of pragma Implemented provides | |
3999 | a way to impose a static requirement on the overriding operation by adhering | |
4000 | to one of the three implementation kinds: entry, protected procedure or any of | |
4001 | the above. This pragma is available in all earlier versions of Ada as an | |
4002 | implementation-defined pragma. | |
b7d26cb1 | 4003 | |
b71d4b62 RA |
4004 | @example |
4005 | type Synch_Iface is synchronized interface; | |
4006 | procedure Prim_Op (Obj : in out Iface) is abstract; | |
4007 | pragma Implemented (Prim_Op, By_Protected_Procedure); | |
b7d26cb1 | 4008 | |
b71d4b62 RA |
4009 | protected type Prot_1 is new Synch_Iface with |
4010 | procedure Prim_Op; -- Legal | |
4011 | end Prot_1; | |
b7d26cb1 | 4012 | |
b71d4b62 RA |
4013 | protected type Prot_2 is new Synch_Iface with |
4014 | entry Prim_Op; -- Illegal | |
4015 | end Prot_2; | |
b7d26cb1 | 4016 | |
b71d4b62 RA |
4017 | task type Task_Typ is new Synch_Iface with |
4018 | entry Prim_Op; -- Illegal | |
4019 | end Task_Typ; | |
4020 | @end example | |
b7d26cb1 | 4021 | |
b71d4b62 RA |
4022 | When applied to the procedure_or_entry_NAME of a requeue statement, pragma |
4023 | Implemented determines the runtime behavior of the requeue. Implementation kind | |
4024 | By_Entry guarantees that the action of requeueing will proceed from an entry to | |
4025 | another entry. Implementation kind By_Protected_Procedure transforms the | |
4026 | requeue into a dispatching call, thus eliminating the chance of blocking. Kind | |
4027 | By_Any shares the behavior of By_Entry and By_Protected_Procedure depending on | |
4028 | the target’s overriding subprogram kind. | |
b7d26cb1 | 4029 | |
b71d4b62 RA |
4030 | @node Pragma Implicit_Packing,Pragma Import_Function,Pragma Implemented,Implementation Defined Pragmas |
4031 | @anchor{gnat_rm/implementation_defined_pragmas pragma-implicit-packing}@anchor{79} | |
4032 | @section Pragma Implicit_Packing | |
b7d26cb1 | 4033 | |
b7d26cb1 | 4034 | |
b71d4b62 | 4035 | @geindex Rational Profile |
b7d26cb1 | 4036 | |
b71d4b62 | 4037 | Syntax: |
b7d26cb1 JM |
4038 | |
4039 | @example | |
b71d4b62 | 4040 | pragma Implicit_Packing; |
b7d26cb1 | 4041 | @end example |
64d5610f | 4042 | |
b71d4b62 RA |
4043 | This is a configuration pragma that requests implicit packing for packed |
4044 | arrays for which a size clause is given but no explicit pragma Pack or | |
4045 | specification of Component_Size is present. It also applies to records | |
4046 | where no record representation clause is present. Consider this example: | |
64d5610f ML |
4047 | |
4048 | @example | |
b71d4b62 RA |
4049 | type R is array (0 .. 7) of Boolean; |
4050 | for R'Size use 8; | |
64d5610f ML |
4051 | @end example |
4052 | ||
b71d4b62 RA |
4053 | In accordance with the recommendation in the RM (RM 13.3(53)), a Size clause |
4054 | does not change the layout of a composite object. So the Size clause in the | |
4055 | above example is normally rejected, since the default layout of the array uses | |
4056 | 8-bit components, and thus the array requires a minimum of 64 bits. | |
64d5610f | 4057 | |
b71d4b62 RA |
4058 | If this declaration is compiled in a region of code covered by an occurrence |
4059 | of the configuration pragma Implicit_Packing, then the Size clause in this | |
4060 | and similar examples will cause implicit packing and thus be accepted. For | |
4061 | this implicit packing to occur, the type in question must be an array of small | |
4062 | components whose size is known at compile time, and the Size clause must | |
4063 | specify the exact size that corresponds to the number of elements in the array | |
4064 | multiplied by the size in bits of the component type (both single and | |
4065 | multi-dimensioned arrays can be controlled with this pragma). | |
64d5610f | 4066 | |
b71d4b62 | 4067 | @geindex Array packing |
64d5610f | 4068 | |
b71d4b62 | 4069 | Similarly, the following example shows the use in the record case |
64d5610f ML |
4070 | |
4071 | @example | |
b71d4b62 RA |
4072 | type r is record |
4073 | a, b, c, d, e, f, g, h : boolean; | |
4074 | chr : character; | |
4075 | end record; | |
4076 | for r'size use 16; | |
64d5610f ML |
4077 | @end example |
4078 | ||
b71d4b62 RA |
4079 | Without a pragma Pack, each Boolean field requires 8 bits, so the |
4080 | minimum size is 72 bits, but with a pragma Pack, 16 bits would be | |
4081 | sufficient. The use of pragma Implicit_Packing allows this record | |
4082 | declaration to compile without an explicit pragma Pack. | |
64d5610f | 4083 | |
b71d4b62 RA |
4084 | @node Pragma Import_Function,Pragma Import_Object,Pragma Implicit_Packing,Implementation Defined Pragmas |
4085 | @anchor{gnat_rm/implementation_defined_pragmas pragma-import-function}@anchor{7a} | |
4086 | @section Pragma Import_Function | |
64d5610f | 4087 | |
64d5610f ML |
4088 | |
4089 | Syntax: | |
4090 | ||
4091 | @example | |
b71d4b62 RA |
4092 | pragma Import_Function ( |
4093 | [Internal =>] LOCAL_NAME, | |
4094 | [, [External =>] EXTERNAL_SYMBOL] | |
4095 | [, [Parameter_Types =>] PARAMETER_TYPES] | |
4096 | [, [Result_Type =>] SUBTYPE_MARK] | |
4097 | [, [Mechanism =>] MECHANISM] | |
4098 | [, [Result_Mechanism =>] MECHANISM_NAME]); | |
64d5610f | 4099 | |
b71d4b62 RA |
4100 | EXTERNAL_SYMBOL ::= |
4101 | IDENTIFIER | |
4102 | | static_string_EXPRESSION | |
64d5610f | 4103 | |
b71d4b62 RA |
4104 | PARAMETER_TYPES ::= |
4105 | null | |
4106 | | TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} | |
64d5610f | 4107 | |
b71d4b62 RA |
4108 | TYPE_DESIGNATOR ::= |
4109 | subtype_NAME | |
4110 | | subtype_Name ' Access | |
64d5610f | 4111 | |
b71d4b62 RA |
4112 | MECHANISM ::= |
4113 | MECHANISM_NAME | |
4114 | | (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) | |
64d5610f | 4115 | |
b71d4b62 RA |
4116 | MECHANISM_ASSOCIATION ::= |
4117 | [formal_parameter_NAME =>] MECHANISM_NAME | |
64d5610f | 4118 | |
b71d4b62 RA |
4119 | MECHANISM_NAME ::= |
4120 | Value | |
4121 | | Reference | |
64d5610f ML |
4122 | @end example |
4123 | ||
b71d4b62 RA |
4124 | This pragma is used in conjunction with a pragma @code{Import} to |
4125 | specify additional information for an imported function. The pragma | |
4126 | @code{Import} (or equivalent pragma @code{Interface}) must precede the | |
4127 | @code{Import_Function} pragma and both must appear in the same | |
4128 | declarative part as the function specification. | |
64d5610f | 4129 | |
b71d4b62 RA |
4130 | The @code{Internal} argument must uniquely designate |
4131 | the function to which the | |
4132 | pragma applies. If more than one function name exists of this name in | |
4133 | the declarative part you must use the @code{Parameter_Types} and | |
4134 | @code{Result_Type} parameters to achieve the required unique | |
4135 | designation. Subtype marks in these parameters must exactly match the | |
4136 | subtypes in the corresponding function specification, using positional | |
4137 | notation to match parameters with subtype marks. | |
4138 | The form with an @code{'Access} attribute can be used to match an | |
4139 | anonymous access parameter. | |
64d5610f | 4140 | |
b71d4b62 RA |
4141 | You may optionally use the @code{Mechanism} and @code{Result_Mechanism} |
4142 | parameters to specify passing mechanisms for the | |
4143 | parameters and result. If you specify a single mechanism name, it | |
4144 | applies to all parameters. Otherwise you may specify a mechanism on a | |
4145 | parameter by parameter basis using either positional or named | |
4146 | notation. If the mechanism is not specified, the default mechanism | |
4147 | is used. | |
64d5610f | 4148 | |
b71d4b62 RA |
4149 | @node Pragma Import_Object,Pragma Import_Procedure,Pragma Import_Function,Implementation Defined Pragmas |
4150 | @anchor{gnat_rm/implementation_defined_pragmas pragma-import-object}@anchor{7b} | |
4151 | @section Pragma Import_Object | |
64d5610f | 4152 | |
64d5610f | 4153 | |
b71d4b62 | 4154 | Syntax: |
64d5610f ML |
4155 | |
4156 | @example | |
b71d4b62 RA |
4157 | pragma Import_Object ( |
4158 | [Internal =>] LOCAL_NAME | |
4159 | [, [External =>] EXTERNAL_SYMBOL] | |
4160 | [, [Size =>] EXTERNAL_SYMBOL]); | |
4161 | ||
4162 | EXTERNAL_SYMBOL ::= | |
4163 | IDENTIFIER | |
4164 | | static_string_EXPRESSION | |
64d5610f ML |
4165 | @end example |
4166 | ||
b71d4b62 RA |
4167 | This pragma designates an object as imported, and apart from the |
4168 | extended rules for external symbols, is identical in effect to the use of | |
4169 | the normal @code{Import} pragma applied to an object. Unlike the | |
4170 | subprogram case, you need not use a separate @code{Import} pragma, | |
4171 | although you may do so (and probably should do so from a portability | |
4172 | point of view). @code{size} is syntax checked, but otherwise ignored by | |
4173 | GNAT. | |
64d5610f | 4174 | |
b71d4b62 RA |
4175 | @node Pragma Import_Procedure,Pragma Import_Valued_Procedure,Pragma Import_Object,Implementation Defined Pragmas |
4176 | @anchor{gnat_rm/implementation_defined_pragmas pragma-import-procedure}@anchor{7c} | |
4177 | @section Pragma Import_Procedure | |
64d5610f ML |
4178 | |
4179 | ||
4180 | Syntax: | |
4181 | ||
4182 | @example | |
b71d4b62 RA |
4183 | pragma Import_Procedure ( |
4184 | [Internal =>] LOCAL_NAME | |
4185 | [, [External =>] EXTERNAL_SYMBOL] | |
4186 | [, [Parameter_Types =>] PARAMETER_TYPES] | |
4187 | [, [Mechanism =>] MECHANISM]); | |
64d5610f | 4188 | |
b71d4b62 RA |
4189 | EXTERNAL_SYMBOL ::= |
4190 | IDENTIFIER | |
4191 | | static_string_EXPRESSION | |
64d5610f | 4192 | |
b71d4b62 RA |
4193 | PARAMETER_TYPES ::= |
4194 | null | |
4195 | | TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} | |
64d5610f | 4196 | |
b71d4b62 RA |
4197 | TYPE_DESIGNATOR ::= |
4198 | subtype_NAME | |
4199 | | subtype_Name ' Access | |
64d5610f | 4200 | |
b71d4b62 RA |
4201 | MECHANISM ::= |
4202 | MECHANISM_NAME | |
4203 | | (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) | |
64d5610f | 4204 | |
b71d4b62 RA |
4205 | MECHANISM_ASSOCIATION ::= |
4206 | [formal_parameter_NAME =>] MECHANISM_NAME | |
64d5610f | 4207 | |
b71d4b62 RA |
4208 | MECHANISM_NAME ::= Value | Reference |
4209 | @end example | |
4210 | ||
4211 | This pragma is identical to @code{Import_Function} except that it | |
4212 | applies to a procedure rather than a function and the parameters | |
4213 | @code{Result_Type} and @code{Result_Mechanism} are not permitted. | |
4214 | ||
4215 | @node Pragma Import_Valued_Procedure,Pragma Independent,Pragma Import_Procedure,Implementation Defined Pragmas | |
4216 | @anchor{gnat_rm/implementation_defined_pragmas pragma-import-valued-procedure}@anchor{7d} | |
4217 | @section Pragma Import_Valued_Procedure | |
64d5610f ML |
4218 | |
4219 | ||
4220 | Syntax: | |
4221 | ||
4222 | @example | |
b71d4b62 RA |
4223 | pragma Import_Valued_Procedure ( |
4224 | [Internal =>] LOCAL_NAME | |
4225 | [, [External =>] EXTERNAL_SYMBOL] | |
4226 | [, [Parameter_Types =>] PARAMETER_TYPES] | |
4227 | [, [Mechanism =>] MECHANISM]); | |
64d5610f | 4228 | |
b71d4b62 RA |
4229 | EXTERNAL_SYMBOL ::= |
4230 | IDENTIFIER | |
4231 | | static_string_EXPRESSION | |
64d5610f | 4232 | |
b71d4b62 RA |
4233 | PARAMETER_TYPES ::= |
4234 | null | |
4235 | | TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@} | |
64d5610f | 4236 | |
b71d4b62 RA |
4237 | TYPE_DESIGNATOR ::= |
4238 | subtype_NAME | |
4239 | | subtype_Name ' Access | |
64d5610f | 4240 | |
b71d4b62 RA |
4241 | MECHANISM ::= |
4242 | MECHANISM_NAME | |
4243 | | (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@}) | |
64d5610f | 4244 | |
b71d4b62 RA |
4245 | MECHANISM_ASSOCIATION ::= |
4246 | [formal_parameter_NAME =>] MECHANISM_NAME | |
4247 | ||
4248 | MECHANISM_NAME ::= Value | Reference | |
64d5610f ML |
4249 | @end example |
4250 | ||
b71d4b62 RA |
4251 | This pragma is identical to @code{Import_Procedure} except that the |
4252 | first parameter of @code{LOCAL_NAME}, which must be present, must be of | |
4253 | mode @code{out}, and externally the subprogram is treated as a function | |
4254 | with this parameter as the result of the function. The purpose of this | |
4255 | capability is to allow the use of @code{out} and @code{in out} | |
4256 | parameters in interfacing to external functions (which are not permitted | |
4257 | in Ada functions). You may optionally use the @code{Mechanism} | |
4258 | parameters to specify passing mechanisms for the parameters. | |
4259 | If you specify a single mechanism name, it applies to all parameters. | |
4260 | Otherwise you may specify a mechanism on a parameter by parameter | |
4261 | basis using either positional or named notation. If the mechanism is not | |
4262 | specified, the default mechanism is used. | |
64d5610f | 4263 | |
b71d4b62 RA |
4264 | Note that it is important to use this pragma in conjunction with a separate |
4265 | pragma Import that specifies the desired convention, since otherwise the | |
4266 | default convention is Ada, which is almost certainly not what is required. | |
4267 | ||
4268 | @node Pragma Independent,Pragma Independent_Components,Pragma Import_Valued_Procedure,Implementation Defined Pragmas | |
4269 | @anchor{gnat_rm/implementation_defined_pragmas pragma-independent}@anchor{7e} | |
4270 | @section Pragma Independent | |
64d5610f ML |
4271 | |
4272 | ||
4273 | Syntax: | |
4274 | ||
4275 | @example | |
b71d4b62 | 4276 | pragma Independent (Local_NAME); |
64d5610f ML |
4277 | @end example |
4278 | ||
b71d4b62 RA |
4279 | This pragma is standard in Ada 2012 mode (which also provides an aspect |
4280 | of the same name). It is also available as an implementation-defined | |
4281 | pragma in all earlier versions. It specifies that the | |
4282 | designated object or all objects of the designated type must be | |
4283 | independently addressable. This means that separate tasks can safely | |
4284 | manipulate such objects. For example, if two components of a record are | |
4285 | independent, then two separate tasks may access these two components. | |
4286 | This may place | |
4287 | constraints on the representation of the object (for instance prohibiting | |
4288 | tight packing). | |
64d5610f | 4289 | |
b71d4b62 RA |
4290 | @node Pragma Independent_Components,Pragma Initial_Condition,Pragma Independent,Implementation Defined Pragmas |
4291 | @anchor{gnat_rm/implementation_defined_pragmas pragma-independent-components}@anchor{7f} | |
4292 | @section Pragma Independent_Components | |
64d5610f | 4293 | |
64d5610f | 4294 | |
b71d4b62 | 4295 | Syntax: |
64d5610f | 4296 | |
b71d4b62 RA |
4297 | @example |
4298 | pragma Independent_Components (Local_NAME); | |
4299 | @end example | |
64d5610f | 4300 | |
b71d4b62 RA |
4301 | This pragma is standard in Ada 2012 mode (which also provides an aspect |
4302 | of the same name). It is also available as an implementation-defined | |
4303 | pragma in all earlier versions. It specifies that the components of the | |
4304 | designated object, or the components of each object of the designated | |
4305 | type, must be | |
4306 | independently addressable. This means that separate tasks can safely | |
4307 | manipulate separate components in the composite object. This may place | |
4308 | constraints on the representation of the object (for instance prohibiting | |
4309 | tight packing). | |
64d5610f | 4310 | |
b71d4b62 RA |
4311 | @node Pragma Initial_Condition,Pragma Initialize_Scalars,Pragma Independent_Components,Implementation Defined Pragmas |
4312 | @anchor{gnat_rm/implementation_defined_pragmas id17}@anchor{80}@anchor{gnat_rm/implementation_defined_pragmas pragma-initial-condition}@anchor{81} | |
4313 | @section Pragma Initial_Condition | |
64d5610f ML |
4314 | |
4315 | ||
4316 | Syntax: | |
4317 | ||
4318 | @example | |
b71d4b62 | 4319 | pragma Initial_Condition (boolean_EXPRESSION); |
64d5610f ML |
4320 | @end example |
4321 | ||
b71d4b62 RA |
4322 | For the semantics of this pragma, see the entry for aspect @code{Initial_Condition} |
4323 | in the SPARK 2014 Reference Manual, section 7.1.6. | |
4324 | ||
4325 | @node Pragma Initialize_Scalars,Pragma Initializes,Pragma Initial_Condition,Implementation Defined Pragmas | |
4326 | @anchor{gnat_rm/implementation_defined_pragmas pragma-initialize-scalars}@anchor{82} | |
4327 | @section Pragma Initialize_Scalars | |
64d5610f | 4328 | |
64d5610f | 4329 | |
b71d4b62 | 4330 | @geindex debugging with Initialize_Scalars |
64d5610f ML |
4331 | |
4332 | Syntax: | |
4333 | ||
4334 | @example | |
b71d4b62 RA |
4335 | pragma Initialize_Scalars |
4336 | [ ( TYPE_VALUE_PAIR @{, TYPE_VALUE_PAIR@} ) ]; | |
64d5610f | 4337 | |
b71d4b62 RA |
4338 | TYPE_VALUE_PAIR ::= |
4339 | SCALAR_TYPE => static_EXPRESSION | |
64d5610f | 4340 | |
b71d4b62 RA |
4341 | SCALAR_TYPE := |
4342 | Short_Float | |
4343 | | Float | |
4344 | | Long_Float | |
4345 | | Long_Long_Flat | |
4346 | | Signed_8 | |
4347 | | Signed_16 | |
4348 | | Signed_32 | |
4349 | | Signed_64 | |
4350 | | Unsigned_8 | |
4351 | | Unsigned_16 | |
4352 | | Unsigned_32 | |
4353 | | Unsigned_64 | |
64d5610f ML |
4354 | @end example |
4355 | ||
b71d4b62 RA |
4356 | This pragma is similar to @code{Normalize_Scalars} conceptually but has two |
4357 | important differences. | |
64d5610f | 4358 | |
b71d4b62 RA |
4359 | First, there is no requirement for the pragma to be used uniformly in all units |
4360 | of a partition. In particular, it is fine to use this just for some or all of | |
4361 | the application units of a partition, without needing to recompile the run-time | |
4362 | library. In the case where some units are compiled with the pragma, and some | |
4363 | without, then a declaration of a variable where the type is defined in package | |
4364 | Standard or is locally declared will always be subject to initialization, as | |
4365 | will any declaration of a scalar variable. For composite variables, whether the | |
4366 | variable is initialized may also depend on whether the package in which the | |
4367 | type of the variable is declared is compiled with the pragma. | |
64d5610f | 4368 | |
b71d4b62 RA |
4369 | The other important difference is that the programmer can control the value |
4370 | used for initializing scalar objects. This effect can be achieved in several | |
4371 | different ways: | |
64d5610f | 4372 | |
64d5610f | 4373 | |
b71d4b62 | 4374 | @itemize * |
64d5610f | 4375 | |
b71d4b62 RA |
4376 | @item |
4377 | At compile time, the programmer can specify the invalid value for a | |
4378 | particular family of scalar types using the optional arguments of the pragma. | |
64d5610f | 4379 | |
b71d4b62 RA |
4380 | The compile-time approach is intended to optimize the generated code for the |
4381 | pragma, by possibly using fast operations such as @code{memset}. Note that such | |
4382 | optimizations require using values where the bytes all have the same binary | |
4383 | representation. | |
64d5610f | 4384 | |
b71d4b62 RA |
4385 | @item |
4386 | At bind time, the programmer has several options: | |
64d5610f | 4387 | |
64d5610f | 4388 | |
b71d4b62 | 4389 | @itemize * |
64d5610f | 4390 | |
b71d4b62 RA |
4391 | @item |
4392 | Initialization with invalid values (similar to Normalize_Scalars, though | |
4393 | for Initialize_Scalars it is not always possible to determine the invalid | |
4394 | values in complex cases like signed component fields with nonstandard | |
4395 | sizes). | |
64d5610f | 4396 | |
b71d4b62 RA |
4397 | @item |
4398 | Initialization with high values. | |
64d5610f | 4399 | |
b71d4b62 RA |
4400 | @item |
4401 | Initialization with low values. | |
64d5610f | 4402 | |
b71d4b62 RA |
4403 | @item |
4404 | Initialization with a specific bit pattern. | |
4405 | @end itemize | |
64d5610f | 4406 | |
b71d4b62 | 4407 | See the GNAT User’s Guide for binder options for specifying these cases. |
64d5610f | 4408 | |
b71d4b62 RA |
4409 | The bind-time approach is intended to provide fast turnaround for testing |
4410 | with different values, without having to recompile the program. | |
64d5610f | 4411 | |
b71d4b62 RA |
4412 | @item |
4413 | At execution time, the programmer can specify the invalid values using an | |
4414 | environment variable. See the GNAT User’s Guide for details. | |
64d5610f | 4415 | |
b71d4b62 RA |
4416 | The execution-time approach is intended to provide fast turnaround for |
4417 | testing with different values, without having to recompile and rebind the | |
4418 | program. | |
4419 | @end itemize | |
64d5610f | 4420 | |
b71d4b62 RA |
4421 | Note that pragma @code{Initialize_Scalars} is particularly useful in conjunction |
4422 | with the enhanced validity checking that is now provided in GNAT, which checks | |
4423 | for invalid values under more conditions. Using this feature (see description | |
4424 | of the `-gnatV' flag in the GNAT User’s Guide) in conjunction with pragma | |
4425 | @code{Initialize_Scalars} provides a powerful new tool to assist in the detection | |
4426 | of problems caused by uninitialized variables. | |
64d5610f | 4427 | |
b71d4b62 RA |
4428 | Note: the use of @code{Initialize_Scalars} has a fairly extensive effect on the |
4429 | generated code. This may cause your code to be substantially larger. It may | |
4430 | also cause an increase in the amount of stack required, so it is probably a | |
4431 | good idea to turn on stack checking (see description of stack checking in the | |
4432 | GNAT User’s Guide) when using this pragma. | |
4433 | ||
4434 | @node Pragma Initializes,Pragma Inline_Always,Pragma Initialize_Scalars,Implementation Defined Pragmas | |
4435 | @anchor{gnat_rm/implementation_defined_pragmas id18}@anchor{83}@anchor{gnat_rm/implementation_defined_pragmas pragma-initializes}@anchor{84} | |
4436 | @section Pragma Initializes | |
64d5610f ML |
4437 | |
4438 | ||
4439 | Syntax: | |
4440 | ||
4441 | @example | |
b71d4b62 | 4442 | pragma Initializes (INITIALIZATION_LIST); |
64d5610f | 4443 | |
b71d4b62 RA |
4444 | INITIALIZATION_LIST ::= |
4445 | null | |
4446 | | (INITIALIZATION_ITEM @{, INITIALIZATION_ITEM@}) | |
64d5610f | 4447 | |
b71d4b62 | 4448 | INITIALIZATION_ITEM ::= name [=> INPUT_LIST] |
64d5610f | 4449 | |
b71d4b62 RA |
4450 | INPUT_LIST ::= |
4451 | null | |
4452 | | INPUT | |
4453 | | (INPUT @{, INPUT@}) | |
64d5610f | 4454 | |
b71d4b62 | 4455 | INPUT ::= name |
64d5610f ML |
4456 | @end example |
4457 | ||
b71d4b62 RA |
4458 | For the semantics of this pragma, see the entry for aspect @code{Initializes} in the |
4459 | SPARK 2014 Reference Manual, section 7.1.5. | |
64d5610f | 4460 | |
b71d4b62 RA |
4461 | @node Pragma Inline_Always,Pragma Inline_Generic,Pragma Initializes,Implementation Defined Pragmas |
4462 | @anchor{gnat_rm/implementation_defined_pragmas id19}@anchor{85}@anchor{gnat_rm/implementation_defined_pragmas pragma-inline-always}@anchor{86} | |
4463 | @section Pragma Inline_Always | |
64d5610f | 4464 | |
64d5610f ML |
4465 | |
4466 | Syntax: | |
4467 | ||
4468 | @example | |
b71d4b62 | 4469 | pragma Inline_Always (NAME [, NAME]); |
64d5610f ML |
4470 | @end example |
4471 | ||
b71d4b62 RA |
4472 | Similar to pragma @code{Inline} except that inlining is unconditional. |
4473 | Inline_Always instructs the compiler to inline every direct call to the | |
4474 | subprogram or else to emit a compilation error, independently of any | |
4475 | option, in particular `-gnatn' or `-gnatN' or the optimization level. | |
4476 | It is an error to take the address or access of @code{NAME}. It is also an error to | |
4477 | apply this pragma to a primitive operation of a tagged type. Thanks to such | |
4478 | restrictions, the compiler is allowed to remove the out-of-line body of @code{NAME}. | |
4479 | ||
4480 | @node Pragma Inline_Generic,Pragma Interface,Pragma Inline_Always,Implementation Defined Pragmas | |
4481 | @anchor{gnat_rm/implementation_defined_pragmas pragma-inline-generic}@anchor{87} | |
4482 | @section Pragma Inline_Generic | |
4483 | ||
4484 | ||
4485 | Syntax: | |
64d5610f ML |
4486 | |
4487 | @example | |
b71d4b62 RA |
4488 | pragma Inline_Generic (GNAME @{, GNAME@}); |
4489 | ||
4490 | GNAME ::= generic_unit_NAME | generic_instance_NAME | |
64d5610f ML |
4491 | @end example |
4492 | ||
b71d4b62 RA |
4493 | This pragma is provided for compatibility with Dec Ada 83. It has |
4494 | no effect in GNAT (which always inlines generics), other | |
4495 | than to check that the given names are all names of generic units or | |
4496 | generic instances. | |
64d5610f | 4497 | |
b71d4b62 RA |
4498 | @node Pragma Interface,Pragma Interface_Name,Pragma Inline_Generic,Implementation Defined Pragmas |
4499 | @anchor{gnat_rm/implementation_defined_pragmas pragma-interface}@anchor{88} | |
4500 | @section Pragma Interface | |
64d5610f | 4501 | |
64d5610f | 4502 | |
b71d4b62 | 4503 | Syntax: |
64d5610f ML |
4504 | |
4505 | @example | |
b71d4b62 RA |
4506 | pragma Interface ( |
4507 | [Convention =>] convention_identifier, | |
4508 | [Entity =>] local_NAME | |
4509 | [, [External_Name =>] static_string_expression] | |
4510 | [, [Link_Name =>] static_string_expression]); | |
64d5610f ML |
4511 | @end example |
4512 | ||
b71d4b62 RA |
4513 | This pragma is identical in syntax and semantics to |
4514 | the standard Ada pragma @code{Import}. It is provided for compatibility | |
4515 | with Ada 83. The definition is upwards compatible both with pragma | |
4516 | @code{Interface} as defined in the Ada 83 Reference Manual, and also | |
4517 | with some extended implementations of this pragma in certain Ada 83 | |
4518 | implementations. The only difference between pragma @code{Interface} | |
4519 | and pragma @code{Import} is that there is special circuitry to allow | |
4520 | both pragmas to appear for the same subprogram entity (normally it | |
4521 | is illegal to have multiple @code{Import} pragmas). This is useful in | |
4522 | maintaining Ada 83/Ada 95 compatibility and is compatible with other | |
4523 | Ada 83 compilers. | |
64d5610f | 4524 | |
b71d4b62 RA |
4525 | @node Pragma Interface_Name,Pragma Interrupt_Handler,Pragma Interface,Implementation Defined Pragmas |
4526 | @anchor{gnat_rm/implementation_defined_pragmas pragma-interface-name}@anchor{89} | |
4527 | @section Pragma Interface_Name | |
64d5610f ML |
4528 | |
4529 | ||
4530 | Syntax: | |
4531 | ||
4532 | @example | |
b71d4b62 RA |
4533 | pragma Interface_Name ( |
4534 | [Entity =>] LOCAL_NAME | |
4535 | [, [External_Name =>] static_string_EXPRESSION] | |
4536 | [, [Link_Name =>] static_string_EXPRESSION]); | |
4537 | @end example | |
64d5610f | 4538 | |
b71d4b62 RA |
4539 | This pragma provides an alternative way of specifying the interface name |
4540 | for an interfaced subprogram, and is provided for compatibility with Ada | |
4541 | 83 compilers that use the pragma for this purpose. You must provide at | |
4542 | least one of @code{External_Name} or @code{Link_Name}. | |
64d5610f | 4543 | |
b71d4b62 RA |
4544 | @node Pragma Interrupt_Handler,Pragma Interrupt_State,Pragma Interface_Name,Implementation Defined Pragmas |
4545 | @anchor{gnat_rm/implementation_defined_pragmas pragma-interrupt-handler}@anchor{8a} | |
4546 | @section Pragma Interrupt_Handler | |
64d5610f | 4547 | |
64d5610f | 4548 | |
b71d4b62 | 4549 | Syntax: |
64d5610f | 4550 | |
b71d4b62 RA |
4551 | @example |
4552 | pragma Interrupt_Handler (procedure_LOCAL_NAME); | |
64d5610f ML |
4553 | @end example |
4554 | ||
b71d4b62 RA |
4555 | This program unit pragma is supported for parameterless protected procedures |
4556 | as described in Annex C of the Ada Reference Manual. | |
64d5610f | 4557 | |
b71d4b62 RA |
4558 | @node Pragma Interrupt_State,Pragma Invariant,Pragma Interrupt_Handler,Implementation Defined Pragmas |
4559 | @anchor{gnat_rm/implementation_defined_pragmas pragma-interrupt-state}@anchor{8b} | |
4560 | @section Pragma Interrupt_State | |
64d5610f ML |
4561 | |
4562 | ||
4563 | Syntax: | |
4564 | ||
4565 | @example | |
b71d4b62 RA |
4566 | pragma Interrupt_State |
4567 | ([Name =>] value, | |
4568 | [State =>] SYSTEM | RUNTIME | USER); | |
64d5610f ML |
4569 | @end example |
4570 | ||
b71d4b62 RA |
4571 | Normally certain interrupts are reserved to the implementation. Any attempt |
4572 | to attach an interrupt causes Program_Error to be raised, as described in | |
4573 | RM C.3.2(22). A typical example is the @code{SIGINT} interrupt used in | |
4574 | many systems for an @code{Ctrl-C} interrupt. Normally this interrupt is | |
4575 | reserved to the implementation, so that @code{Ctrl-C} can be used to | |
4576 | interrupt execution. Additionally, signals such as @code{SIGSEGV}, | |
4577 | @code{SIGABRT}, @code{SIGFPE} and @code{SIGILL} are often mapped to specific | |
4578 | Ada exceptions, or used to implement run-time functions such as the | |
4579 | @code{abort} statement and stack overflow checking. | |
64d5610f | 4580 | |
b71d4b62 RA |
4581 | Pragma @code{Interrupt_State} provides a general mechanism for overriding |
4582 | such uses of interrupts. It subsumes the functionality of pragma | |
4583 | @code{Unreserve_All_Interrupts}. Pragma @code{Interrupt_State} is not | |
4584 | available on Windows. On all other platforms than VxWorks, | |
4585 | it applies to signals; on VxWorks, it applies to vectored hardware interrupts | |
4586 | and may be used to mark interrupts required by the board support package | |
4587 | as reserved. | |
64d5610f | 4588 | |
b71d4b62 | 4589 | Interrupts can be in one of three states: |
64d5610f | 4590 | |
64d5610f | 4591 | |
b71d4b62 | 4592 | @itemize * |
64d5610f | 4593 | |
b71d4b62 RA |
4594 | @item |
4595 | System | |
64d5610f | 4596 | |
b71d4b62 RA |
4597 | The interrupt is reserved (no Ada handler can be installed), and the |
4598 | Ada run-time may not install a handler. As a result you are guaranteed | |
4599 | standard system default action if this interrupt is raised. This also allows | |
4600 | installing a low level handler via C APIs such as sigaction(), outside | |
4601 | of Ada control. | |
64d5610f | 4602 | |
b71d4b62 RA |
4603 | @item |
4604 | Runtime | |
64d5610f | 4605 | |
b71d4b62 RA |
4606 | The interrupt is reserved (no Ada handler can be installed). The run time |
4607 | is allowed to install a handler for internal control purposes, but is | |
4608 | not required to do so. | |
64d5610f | 4609 | |
b71d4b62 RA |
4610 | @item |
4611 | User | |
64d5610f | 4612 | |
b71d4b62 RA |
4613 | The interrupt is unreserved. The user may install an Ada handler via |
4614 | Ada.Interrupts and pragma Interrupt_Handler or Attach_Handler to provide | |
4615 | some other action. | |
4616 | @end itemize | |
64d5610f | 4617 | |
b71d4b62 RA |
4618 | These states are the allowed values of the @code{State} parameter of the |
4619 | pragma. The @code{Name} parameter is a value of the type | |
4620 | @code{Ada.Interrupts.Interrupt_ID}. Typically, it is a name declared in | |
4621 | @code{Ada.Interrupts.Names}. | |
64d5610f | 4622 | |
b71d4b62 RA |
4623 | This is a configuration pragma, and the binder will check that there |
4624 | are no inconsistencies between different units in a partition in how a | |
4625 | given interrupt is specified. It may appear anywhere a pragma is legal. | |
64d5610f | 4626 | |
b71d4b62 | 4627 | The effect is to move the interrupt to the specified state. |
64d5610f | 4628 | |
b71d4b62 RA |
4629 | By declaring interrupts to be SYSTEM, you guarantee the standard system |
4630 | action, such as a core dump. | |
64d5610f | 4631 | |
b71d4b62 RA |
4632 | By declaring interrupts to be USER, you guarantee that you can install |
4633 | a handler. | |
64d5610f | 4634 | |
b71d4b62 RA |
4635 | Note that certain signals on many operating systems cannot be caught and |
4636 | handled by applications. In such cases, the pragma is ignored. See the | |
4637 | operating system documentation, or the value of the array @code{Reserved} | |
4638 | declared in the spec of package @code{System.OS_Interface}. | |
64d5610f | 4639 | |
b71d4b62 RA |
4640 | Overriding the default state of signals used by the Ada runtime may interfere |
4641 | with an application’s runtime behavior in the cases of the synchronous signals, | |
4642 | and in the case of the signal used to implement the @code{abort} statement. | |
64d5610f | 4643 | |
b71d4b62 RA |
4644 | @node Pragma Invariant,Pragma Keep_Names,Pragma Interrupt_State,Implementation Defined Pragmas |
4645 | @anchor{gnat_rm/implementation_defined_pragmas id20}@anchor{8c}@anchor{gnat_rm/implementation_defined_pragmas pragma-invariant}@anchor{8d} | |
4646 | @section Pragma Invariant | |
64d5610f | 4647 | |
64d5610f | 4648 | |
b71d4b62 | 4649 | Syntax: |
64d5610f | 4650 | |
b71d4b62 RA |
4651 | @example |
4652 | pragma Invariant | |
4653 | ([Entity =>] private_type_LOCAL_NAME, | |
4654 | [Check =>] EXPRESSION | |
4655 | [,[Message =>] String_Expression]); | |
64d5610f ML |
4656 | @end example |
4657 | ||
b71d4b62 RA |
4658 | This pragma provides exactly the same capabilities as the Type_Invariant aspect |
4659 | defined in AI05-0146-1, and in the Ada 2012 Reference Manual. The | |
4660 | Type_Invariant aspect is fully implemented in Ada 2012 mode, but since it | |
4661 | requires the use of the aspect syntax, which is not available except in 2012 | |
4662 | mode, it is not possible to use the Type_Invariant aspect in earlier versions | |
4663 | of Ada. However the Invariant pragma may be used in any version of Ada. Also | |
4664 | note that the aspect Invariant is a synonym in GNAT for the aspect | |
4665 | Type_Invariant, but there is no pragma Type_Invariant. | |
64d5610f | 4666 | |
b71d4b62 RA |
4667 | The pragma must appear within the visible part of the package specification, |
4668 | after the type to which its Entity argument appears. As with the Invariant | |
4669 | aspect, the Check expression is not analyzed until the end of the visible | |
4670 | part of the package, so it may contain forward references. The Message | |
4671 | argument, if present, provides the exception message used if the invariant | |
4672 | is violated. If no Message parameter is provided, a default message that | |
4673 | identifies the line on which the pragma appears is used. | |
64d5610f | 4674 | |
b71d4b62 RA |
4675 | It is permissible to have multiple Invariants for the same type entity, in |
4676 | which case they are and’ed together. It is permissible to use this pragma | |
4677 | in Ada 2012 mode, but you cannot have both an invariant aspect and an | |
4678 | invariant pragma for the same entity. | |
4679 | ||
4680 | For further details on the use of this pragma, see the Ada 2012 documentation | |
4681 | of the Type_Invariant aspect. | |
4682 | ||
4683 | @node Pragma Keep_Names,Pragma License,Pragma Invariant,Implementation Defined Pragmas | |
4684 | @anchor{gnat_rm/implementation_defined_pragmas pragma-keep-names}@anchor{8e} | |
4685 | @section Pragma Keep_Names | |
64d5610f ML |
4686 | |
4687 | ||
4688 | Syntax: | |
4689 | ||
4690 | @example | |
b71d4b62 | 4691 | pragma Keep_Names ([On =>] enumeration_first_subtype_LOCAL_NAME); |
64d5610f ML |
4692 | @end example |
4693 | ||
b71d4b62 RA |
4694 | The @code{LOCAL_NAME} argument |
4695 | must refer to an enumeration first subtype | |
4696 | in the current declarative part. The effect is to retain the enumeration | |
4697 | literal names for use by @code{Image} and @code{Value} even if a global | |
4698 | @code{Discard_Names} pragma applies. This is useful when you want to | |
4699 | generally suppress enumeration literal names and for example you therefore | |
4700 | use a @code{Discard_Names} pragma in the @code{gnat.adc} file, but you | |
4701 | want to retain the names for specific enumeration types. | |
64d5610f | 4702 | |
b71d4b62 RA |
4703 | @node Pragma License,Pragma Link_With,Pragma Keep_Names,Implementation Defined Pragmas |
4704 | @anchor{gnat_rm/implementation_defined_pragmas pragma-license}@anchor{8f} | |
4705 | @section Pragma License | |
64d5610f ML |
4706 | |
4707 | ||
b71d4b62 | 4708 | @geindex License checking |
64d5610f ML |
4709 | |
4710 | Syntax: | |
4711 | ||
4712 | @example | |
b71d4b62 | 4713 | pragma License (Unrestricted | GPL | Modified_GPL | Restricted); |
64d5610f ML |
4714 | @end example |
4715 | ||
b71d4b62 RA |
4716 | This pragma is provided to allow automated checking for appropriate license |
4717 | conditions with respect to the standard and modified GPL. A pragma | |
4718 | @code{License}, which is a configuration pragma that typically appears at | |
4719 | the start of a source file or in a separate @code{gnat.adc} file, specifies | |
4720 | the licensing conditions of a unit as follows: | |
64d5610f ML |
4721 | |
4722 | ||
4723 | @itemize * | |
4724 | ||
4725 | @item | |
b71d4b62 RA |
4726 | Unrestricted |
4727 | This is used for a unit that can be freely used with no license restrictions. | |
4728 | Examples of such units are public domain units, and units from the Ada | |
4729 | Reference Manual. | |
64d5610f ML |
4730 | |
4731 | @item | |
b71d4b62 RA |
4732 | GPL |
4733 | This is used for a unit that is licensed under the unmodified GPL, and which | |
4734 | therefore cannot be @code{with}ed by a restricted unit. | |
64d5610f ML |
4735 | |
4736 | @item | |
b71d4b62 RA |
4737 | Modified_GPL |
4738 | This is used for a unit licensed under the GNAT modified GPL that includes | |
4739 | a special exception paragraph that specifically permits the inclusion of | |
4740 | the unit in programs without requiring the entire program to be released | |
4741 | under the GPL. | |
64d5610f ML |
4742 | |
4743 | @item | |
b71d4b62 RA |
4744 | Restricted |
4745 | This is used for a unit that is restricted in that it is not permitted to | |
4746 | depend on units that are licensed under the GPL. Typical examples are | |
4747 | proprietary code that is to be released under more restrictive license | |
4748 | conditions. Note that restricted units are permitted to @code{with} units | |
4749 | which are licensed under the modified GPL (this is the whole point of the | |
4750 | modified GPL). | |
64d5610f ML |
4751 | @end itemize |
4752 | ||
b71d4b62 RA |
4753 | Normally a unit with no @code{License} pragma is considered to have an |
4754 | unknown license, and no checking is done. However, standard GNAT headers | |
4755 | are recognized, and license information is derived from them as follows. | |
64d5610f | 4756 | |
b71d4b62 RA |
4757 | A GNAT license header starts with a line containing 78 hyphens. The following |
4758 | comment text is searched for the appearance of any of the following strings. | |
64d5610f | 4759 | |
b71d4b62 RA |
4760 | If the string ‘GNU General Public License’ is found, then the unit is assumed |
4761 | to have GPL license, unless the string ‘As a special exception’ follows, in | |
4762 | which case the license is assumed to be modified GPL. | |
64d5610f | 4763 | |
b71d4b62 RA |
4764 | If one of the strings |
4765 | ‘This specification is adapted from the Ada Semantic Interface’ or | |
4766 | ‘This specification is derived from the Ada Reference Manual’ is found | |
4767 | then the unit is assumed to be unrestricted. | |
64d5610f | 4768 | |
b71d4b62 RA |
4769 | These default actions means that a program with a restricted license pragma |
4770 | will automatically get warnings if a GPL unit is inappropriately | |
4771 | @code{with}ed. For example, the program: | |
64d5610f ML |
4772 | |
4773 | @example | |
b71d4b62 RA |
4774 | with Sem_Ch3; |
4775 | with GNAT.Sockets; | |
4776 | procedure Secret_Stuff is | |
4777 | ... | |
4778 | end Secret_Stuff | |
4779 | @end example | |
64d5610f | 4780 | |
b71d4b62 RA |
4781 | if compiled with pragma @code{License} (@code{Restricted}) in a |
4782 | @code{gnat.adc} file will generate the warning: | |
64d5610f | 4783 | |
b71d4b62 RA |
4784 | @example |
4785 | 1. with Sem_Ch3; | |
4786 | | | |
4787 | >>> license of withed unit "Sem_Ch3" is incompatible | |
64d5610f | 4788 | |
b71d4b62 RA |
4789 | 2. with GNAT.Sockets; |
4790 | 3. procedure Secret_Stuff is | |
64d5610f ML |
4791 | @end example |
4792 | ||
b71d4b62 RA |
4793 | Here we get a warning on @code{Sem_Ch3} since it is part of the GNAT |
4794 | compiler and is licensed under the | |
4795 | GPL, but no warning for @code{GNAT.Sockets} which is part of the GNAT | |
4796 | run time, and is therefore licensed under the modified GPL. | |
64d5610f | 4797 | |
b71d4b62 RA |
4798 | @node Pragma Link_With,Pragma Linker_Alias,Pragma License,Implementation Defined Pragmas |
4799 | @anchor{gnat_rm/implementation_defined_pragmas pragma-link-with}@anchor{90} | |
4800 | @section Pragma Link_With | |
64d5610f ML |
4801 | |
4802 | ||
4803 | Syntax: | |
4804 | ||
4805 | @example | |
b71d4b62 | 4806 | pragma Link_With (static_string_EXPRESSION @{,static_string_EXPRESSION@}); |
64d5610f ML |
4807 | @end example |
4808 | ||
b71d4b62 RA |
4809 | This pragma is provided for compatibility with certain Ada 83 compilers. |
4810 | It has exactly the same effect as pragma @code{Linker_Options} except | |
4811 | that spaces occurring within one of the string expressions are treated | |
4812 | as separators. For example, in the following case: | |
64d5610f ML |
4813 | |
4814 | @example | |
b71d4b62 | 4815 | pragma Link_With ("-labc -ldef"); |
64d5610f ML |
4816 | @end example |
4817 | ||
b71d4b62 RA |
4818 | results in passing the strings @code{-labc} and @code{-ldef} as two |
4819 | separate arguments to the linker. In addition pragma Link_With allows | |
4820 | multiple arguments, with the same effect as successive pragmas. | |
64d5610f | 4821 | |
b71d4b62 RA |
4822 | @node Pragma Linker_Alias,Pragma Linker_Constructor,Pragma Link_With,Implementation Defined Pragmas |
4823 | @anchor{gnat_rm/implementation_defined_pragmas pragma-linker-alias}@anchor{91} | |
4824 | @section Pragma Linker_Alias | |
64d5610f ML |
4825 | |
4826 | ||
4827 | Syntax: | |
4828 | ||
4829 | @example | |
b71d4b62 RA |
4830 | pragma Linker_Alias ( |
4831 | [Entity =>] LOCAL_NAME, | |
4832 | [Target =>] static_string_EXPRESSION); | |
64d5610f ML |
4833 | @end example |
4834 | ||
b71d4b62 RA |
4835 | @code{LOCAL_NAME} must refer to an object that is declared at the library |
4836 | level. This pragma establishes the given entity as a linker alias for the | |
4837 | given target. It is equivalent to @code{__attribute__((alias))} in GNU C | |
4838 | and causes @code{LOCAL_NAME} to be emitted as an alias for the symbol | |
4839 | @code{static_string_EXPRESSION} in the object file, that is to say no space | |
4840 | is reserved for @code{LOCAL_NAME} by the assembler and it will be resolved | |
4841 | to the same address as @code{static_string_EXPRESSION} by the linker. | |
64d5610f | 4842 | |
b71d4b62 RA |
4843 | The actual linker name for the target must be used (e.g., the fully |
4844 | encoded name with qualification in Ada, or the mangled name in C++), | |
4845 | or it must be declared using the C convention with @code{pragma Import} | |
4846 | or @code{pragma Export}. | |
64d5610f | 4847 | |
b71d4b62 RA |
4848 | Not all target machines support this pragma. On some of them it is accepted |
4849 | only if @code{pragma Weak_External} has been applied to @code{LOCAL_NAME}. | |
64d5610f ML |
4850 | |
4851 | @example | |
b71d4b62 | 4852 | -- Example of the use of pragma Linker_Alias |
64d5610f | 4853 | |
b71d4b62 RA |
4854 | package p is |
4855 | i : Integer := 1; | |
4856 | pragma Export (C, i); | |
64d5610f | 4857 | |
b71d4b62 RA |
4858 | new_name_for_i : Integer; |
4859 | pragma Linker_Alias (new_name_for_i, "i"); | |
4860 | end p; | |
4861 | @end example | |
4862 | ||
4863 | @node Pragma Linker_Constructor,Pragma Linker_Destructor,Pragma Linker_Alias,Implementation Defined Pragmas | |
4864 | @anchor{gnat_rm/implementation_defined_pragmas pragma-linker-constructor}@anchor{92} | |
4865 | @section Pragma Linker_Constructor | |
64d5610f ML |
4866 | |
4867 | ||
4868 | Syntax: | |
4869 | ||
4870 | @example | |
b71d4b62 | 4871 | pragma Linker_Constructor (procedure_LOCAL_NAME); |
64d5610f ML |
4872 | @end example |
4873 | ||
b71d4b62 RA |
4874 | @code{procedure_LOCAL_NAME} must refer to a parameterless procedure that |
4875 | is declared at the library level. A procedure to which this pragma is | |
4876 | applied will be treated as an initialization routine by the linker. | |
4877 | It is equivalent to @code{__attribute__((constructor))} in GNU C and | |
4878 | causes @code{procedure_LOCAL_NAME} to be invoked before the entry point | |
4879 | of the executable is called (or immediately after the shared library is | |
4880 | loaded if the procedure is linked in a shared library), in particular | |
4881 | before the Ada run-time environment is set up. | |
64d5610f | 4882 | |
b71d4b62 RA |
4883 | Because of these specific contexts, the set of operations such a procedure |
4884 | can perform is very limited and the type of objects it can manipulate is | |
4885 | essentially restricted to the elementary types. In particular, it must only | |
4886 | contain code to which pragma Restrictions (No_Elaboration_Code) applies. | |
4887 | ||
4888 | This pragma is used by GNAT to implement auto-initialization of shared Stand | |
4889 | Alone Libraries, which provides a related capability without the restrictions | |
4890 | listed above. Where possible, the use of Stand Alone Libraries is preferable | |
4891 | to the use of this pragma. | |
4892 | ||
4893 | @node Pragma Linker_Destructor,Pragma Linker_Section,Pragma Linker_Constructor,Implementation Defined Pragmas | |
4894 | @anchor{gnat_rm/implementation_defined_pragmas pragma-linker-destructor}@anchor{93} | |
4895 | @section Pragma Linker_Destructor | |
64d5610f ML |
4896 | |
4897 | ||
4898 | Syntax: | |
4899 | ||
4900 | @example | |
b71d4b62 | 4901 | pragma Linker_Destructor (procedure_LOCAL_NAME); |
64d5610f ML |
4902 | @end example |
4903 | ||
b71d4b62 RA |
4904 | @code{procedure_LOCAL_NAME} must refer to a parameterless procedure that |
4905 | is declared at the library level. A procedure to which this pragma is | |
4906 | applied will be treated as a finalization routine by the linker. | |
4907 | It is equivalent to @code{__attribute__((destructor))} in GNU C and | |
4908 | causes @code{procedure_LOCAL_NAME} to be invoked after the entry point | |
4909 | of the executable has exited (or immediately before the shared library | |
4910 | is unloaded if the procedure is linked in a shared library), in particular | |
4911 | after the Ada run-time environment is shut down. | |
64d5610f | 4912 | |
b71d4b62 RA |
4913 | See @code{pragma Linker_Constructor} for the set of restrictions that apply |
4914 | because of these specific contexts. | |
64d5610f | 4915 | |
b71d4b62 RA |
4916 | @node Pragma Linker_Section,Pragma Lock_Free,Pragma Linker_Destructor,Implementation Defined Pragmas |
4917 | @anchor{gnat_rm/implementation_defined_pragmas id21}@anchor{94}@anchor{gnat_rm/implementation_defined_pragmas pragma-linker-section}@anchor{95} | |
4918 | @section Pragma Linker_Section | |
64d5610f ML |
4919 | |
4920 | ||
b71d4b62 | 4921 | Syntax: |
64d5610f | 4922 | |
b71d4b62 RA |
4923 | @example |
4924 | pragma Linker_Section ( | |
4925 | [Entity =>] LOCAL_NAME, | |
4926 | [Section =>] static_string_EXPRESSION); | |
4927 | @end example | |
64d5610f | 4928 | |
b71d4b62 RA |
4929 | @code{LOCAL_NAME} must refer to an object, type, or subprogram that is |
4930 | declared at the library level. This pragma specifies the name of the | |
4931 | linker section for the given entity. It is equivalent to | |
4932 | @code{__attribute__((section))} in GNU C and causes @code{LOCAL_NAME} to | |
4933 | be placed in the @code{static_string_EXPRESSION} section of the | |
4934 | executable (assuming the linker doesn’t rename the section). | |
4935 | GNAT also provides an implementation defined aspect of the same name. | |
64d5610f | 4936 | |
b71d4b62 RA |
4937 | In the case of specifying this aspect for a type, the effect is to |
4938 | specify the corresponding section for all library-level objects of | |
4939 | the type that do not have an explicit linker section set. Note that | |
4940 | this only applies to whole objects, not to components of composite objects. | |
64d5610f | 4941 | |
b71d4b62 RA |
4942 | In the case of a subprogram, the linker section applies to all previously |
4943 | declared matching overloaded subprograms in the current declarative part | |
4944 | which do not already have a linker section assigned. The linker section | |
4945 | aspect is useful in this case for specifying different linker sections | |
4946 | for different elements of such an overloaded set. | |
64d5610f | 4947 | |
b71d4b62 RA |
4948 | Note that an empty string specifies that no linker section is specified. |
4949 | This is not quite the same as omitting the pragma or aspect, since it | |
4950 | can be used to specify that one element of an overloaded set of subprograms | |
4951 | has the default linker section, or that one object of a type for which a | |
4952 | linker section is specified should has the default linker section. | |
64d5610f | 4953 | |
b71d4b62 RA |
4954 | The compiler normally places library-level entities in standard sections |
4955 | depending on the class: procedures and functions generally go in the | |
4956 | @code{.text} section, initialized variables in the @code{.data} section | |
4957 | and uninitialized variables in the @code{.bss} section. | |
64d5610f | 4958 | |
b71d4b62 RA |
4959 | Other, special sections may exist on given target machines to map special |
4960 | hardware, for example I/O ports or flash memory. This pragma is a means to | |
4961 | defer the final layout of the executable to the linker, thus fully working | |
4962 | at the symbolic level with the compiler. | |
64d5610f | 4963 | |
b71d4b62 RA |
4964 | Some file formats do not support arbitrary sections so not all target |
4965 | machines support this pragma. The use of this pragma may cause a program | |
4966 | execution to be erroneous if it is used to place an entity into an | |
4967 | inappropriate section (e.g., a modified variable into the @code{.text} | |
4968 | section). See also @code{pragma Persistent_BSS}. | |
64d5610f | 4969 | |
b71d4b62 RA |
4970 | @example |
4971 | -- Example of the use of pragma Linker_Section | |
64d5610f | 4972 | |
b71d4b62 RA |
4973 | package IO_Card is |
4974 | Port_A : Integer; | |
4975 | pragma Volatile (Port_A); | |
4976 | pragma Linker_Section (Port_A, ".bss.port_a"); | |
64d5610f | 4977 | |
b71d4b62 RA |
4978 | Port_B : Integer; |
4979 | pragma Volatile (Port_B); | |
4980 | pragma Linker_Section (Port_B, ".bss.port_b"); | |
64d5610f | 4981 | |
b71d4b62 RA |
4982 | type Port_Type is new Integer with Linker_Section => ".bss"; |
4983 | PA : Port_Type with Linker_Section => ".bss.PA"; | |
4984 | PB : Port_Type; -- ends up in linker section ".bss" | |
64d5610f | 4985 | |
b71d4b62 RA |
4986 | procedure Q with Linker_Section => "Qsection"; |
4987 | end IO_Card; | |
4988 | @end example | |
64d5610f | 4989 | |
b71d4b62 RA |
4990 | @node Pragma Lock_Free,Pragma Loop_Invariant,Pragma Linker_Section,Implementation Defined Pragmas |
4991 | @anchor{gnat_rm/implementation_defined_pragmas id22}@anchor{96}@anchor{gnat_rm/implementation_defined_pragmas pragma-lock-free}@anchor{97} | |
4992 | @section Pragma Lock_Free | |
64d5610f ML |
4993 | |
4994 | ||
4995 | Syntax: | |
b71d4b62 RA |
4996 | This pragma may be specified for protected types or objects. It specifies that |
4997 | the implementation of protected operations must be implemented without locks. | |
4998 | Compilation fails if the compiler cannot generate lock-free code for the | |
4999 | operations. | |
64d5610f | 5000 | |
b71d4b62 | 5001 | The current conditions required to support this pragma are: |
64d5610f | 5002 | |
64d5610f | 5003 | |
b71d4b62 | 5004 | @itemize * |
64d5610f | 5005 | |
b71d4b62 RA |
5006 | @item |
5007 | Protected type declarations may not contain entries | |
64d5610f | 5008 | |
b71d4b62 RA |
5009 | @item |
5010 | Protected subprogram declarations may not have nonelementary parameters | |
5011 | @end itemize | |
64d5610f | 5012 | |
b71d4b62 | 5013 | In addition, each protected subprogram body must satisfy: |
64d5610f ML |
5014 | |
5015 | ||
b71d4b62 | 5016 | @itemize * |
64d5610f | 5017 | |
b71d4b62 RA |
5018 | @item |
5019 | May reference only one protected component | |
64d5610f | 5020 | |
b71d4b62 RA |
5021 | @item |
5022 | May not reference nonconstant entities outside the protected subprogram | |
5023 | scope | |
64d5610f | 5024 | |
b71d4b62 RA |
5025 | @item |
5026 | May not contain address representation items, allocators, or quantified | |
5027 | expressions | |
64d5610f ML |
5028 | |
5029 | @item | |
b71d4b62 | 5030 | May not contain delay, goto, loop, or procedure-call statements |
64d5610f ML |
5031 | |
5032 | @item | |
b71d4b62 | 5033 | May not contain exported and imported entities |
64d5610f ML |
5034 | |
5035 | @item | |
b71d4b62 | 5036 | May not dereferenced access values |
64d5610f ML |
5037 | |
5038 | @item | |
b71d4b62 | 5039 | Function calls and attribute references must be static |
64d5610f ML |
5040 | @end itemize |
5041 | ||
b71d4b62 RA |
5042 | If the Lock_Free aspect is specified to be True for a protected unit |
5043 | and the Ceiling_Locking locking policy is in effect, then the run-time | |
5044 | actions associated with the Ceiling_Locking locking policy (described in | |
5045 | Ada RM D.3) are not performed when a protected operation of the protected | |
5046 | unit is executed. | |
64d5610f | 5047 | |
b71d4b62 RA |
5048 | @node Pragma Loop_Invariant,Pragma Loop_Optimize,Pragma Lock_Free,Implementation Defined Pragmas |
5049 | @anchor{gnat_rm/implementation_defined_pragmas pragma-loop-invariant}@anchor{98} | |
5050 | @section Pragma Loop_Invariant | |
64d5610f | 5051 | |
64d5610f | 5052 | |
b71d4b62 | 5053 | Syntax: |
64d5610f ML |
5054 | |
5055 | @example | |
b71d4b62 | 5056 | pragma Loop_Invariant ( boolean_EXPRESSION ); |
64d5610f ML |
5057 | @end example |
5058 | ||
b71d4b62 RA |
5059 | The effect of this pragma is similar to that of pragma @code{Assert}, |
5060 | except that in an @code{Assertion_Policy} pragma, the identifier | |
5061 | @code{Loop_Invariant} is used to control whether it is ignored or checked | |
5062 | (or disabled). | |
64d5610f | 5063 | |
b71d4b62 RA |
5064 | @code{Loop_Invariant} can only appear as one of the items in the sequence |
5065 | of statements of a loop body, or nested inside block statements that | |
5066 | appear in the sequence of statements of a loop body. | |
5067 | The intention is that it be used to | |
5068 | represent a “loop invariant” assertion, i.e. something that is true each | |
5069 | time through the loop, and which can be used to show that the loop is | |
5070 | achieving its purpose. | |
64d5610f | 5071 | |
b71d4b62 RA |
5072 | Multiple @code{Loop_Invariant} and @code{Loop_Variant} pragmas that |
5073 | apply to the same loop should be grouped in the same sequence of | |
5074 | statements. | |
64d5610f | 5075 | |
b71d4b62 RA |
5076 | To aid in writing such invariants, the special attribute @code{Loop_Entry} |
5077 | may be used to refer to the value of an expression on entry to the loop. This | |
5078 | attribute can only be used within the expression of a @code{Loop_Invariant} | |
5079 | pragma. For full details, see documentation of attribute @code{Loop_Entry}. | |
64d5610f | 5080 | |
b71d4b62 RA |
5081 | @node Pragma Loop_Optimize,Pragma Loop_Variant,Pragma Loop_Invariant,Implementation Defined Pragmas |
5082 | @anchor{gnat_rm/implementation_defined_pragmas pragma-loop-optimize}@anchor{99} | |
5083 | @section Pragma Loop_Optimize | |
64d5610f ML |
5084 | |
5085 | ||
5086 | Syntax: | |
5087 | ||
5088 | @example | |
b71d4b62 RA |
5089 | pragma Loop_Optimize (OPTIMIZATION_HINT @{, OPTIMIZATION_HINT@}); |
5090 | ||
5091 | OPTIMIZATION_HINT ::= Ivdep | No_Unroll | Unroll | No_Vector | Vector | |
64d5610f ML |
5092 | @end example |
5093 | ||
b71d4b62 RA |
5094 | This pragma must appear immediately within a loop statement. It allows the |
5095 | programmer to specify optimization hints for the enclosing loop. The hints | |
5096 | are not mutually exclusive and can be freely mixed, but not all combinations | |
5097 | will yield a sensible outcome. | |
64d5610f | 5098 | |
b71d4b62 | 5099 | There are five supported optimization hints for a loop: |
64d5610f | 5100 | |
64d5610f | 5101 | |
b71d4b62 | 5102 | @itemize * |
64d5610f | 5103 | |
b71d4b62 RA |
5104 | @item |
5105 | Ivdep | |
64d5610f | 5106 | |
b71d4b62 RA |
5107 | The programmer asserts that there are no loop-carried dependencies |
5108 | which would prevent consecutive iterations of the loop from being | |
5109 | executed simultaneously. | |
64d5610f | 5110 | |
b71d4b62 RA |
5111 | @item |
5112 | No_Unroll | |
64d5610f | 5113 | |
b71d4b62 RA |
5114 | The loop must not be unrolled. This is a strong hint: the compiler will not |
5115 | unroll a loop marked with this hint. | |
64d5610f | 5116 | |
b71d4b62 RA |
5117 | @item |
5118 | Unroll | |
64d5610f | 5119 | |
b71d4b62 RA |
5120 | The loop should be unrolled. This is a weak hint: the compiler will try to |
5121 | apply unrolling to this loop preferably to other optimizations, notably | |
5122 | vectorization, but there is no guarantee that the loop will be unrolled. | |
64d5610f | 5123 | |
b71d4b62 RA |
5124 | @item |
5125 | No_Vector | |
64d5610f | 5126 | |
b71d4b62 RA |
5127 | The loop must not be vectorized. This is a strong hint: the compiler will not |
5128 | vectorize a loop marked with this hint. | |
64d5610f | 5129 | |
b71d4b62 RA |
5130 | @item |
5131 | Vector | |
64d5610f | 5132 | |
b71d4b62 RA |
5133 | The loop should be vectorized. This is a weak hint: the compiler will try to |
5134 | apply vectorization to this loop preferably to other optimizations, notably | |
5135 | unrolling, but there is no guarantee that the loop will be vectorized. | |
5136 | @end itemize | |
5137 | ||
5138 | These hints do not remove the need to pass the appropriate switches to the | |
5139 | compiler in order to enable the relevant optimizations, that is to say | |
5140 | `-funroll-loops' for unrolling and `-ftree-vectorize' for | |
5141 | vectorization. | |
5142 | ||
5143 | @node Pragma Loop_Variant,Pragma Machine_Attribute,Pragma Loop_Optimize,Implementation Defined Pragmas | |
5144 | @anchor{gnat_rm/implementation_defined_pragmas pragma-loop-variant}@anchor{9a} | |
5145 | @section Pragma Loop_Variant | |
64d5610f ML |
5146 | |
5147 | ||
5148 | Syntax: | |
5149 | ||
5150 | @example | |
b71d4b62 RA |
5151 | pragma Loop_Variant ( LOOP_VARIANT_ITEM @{, LOOP_VARIANT_ITEM @} ); |
5152 | LOOP_VARIANT_ITEM ::= CHANGE_DIRECTION => discrete_EXPRESSION | |
5153 | CHANGE_DIRECTION ::= Increases | Decreases | |
64d5610f ML |
5154 | @end example |
5155 | ||
b71d4b62 RA |
5156 | @code{Loop_Variant} can only appear as one of the items in the sequence |
5157 | of statements of a loop body, or nested inside block statements that | |
5158 | appear in the sequence of statements of a loop body. | |
5159 | It allows the specification of quantities which must always | |
5160 | decrease or increase in successive iterations of the loop. In its simplest | |
5161 | form, just one expression is specified, whose value must increase or decrease | |
5162 | on each iteration of the loop. | |
64d5610f | 5163 | |
b71d4b62 RA |
5164 | In a more complex form, multiple arguments can be given which are interpreted |
5165 | in a nesting lexicographic manner. For example: | |
64d5610f | 5166 | |
b71d4b62 RA |
5167 | @example |
5168 | pragma Loop_Variant (Increases => X, Decreases => Y); | |
5169 | @end example | |
64d5610f | 5170 | |
b71d4b62 RA |
5171 | specifies that each time through the loop either X increases, or X stays |
5172 | the same and Y decreases. A @code{Loop_Variant} pragma ensures that the | |
5173 | loop is making progress. It can be useful in helping to show informally | |
5174 | or prove formally that the loop always terminates. | |
5175 | ||
5176 | @code{Loop_Variant} is an assertion whose effect can be controlled using | |
5177 | an @code{Assertion_Policy} with a check name of @code{Loop_Variant}. The | |
5178 | policy can be @code{Check} to enable the loop variant check, @code{Ignore} | |
5179 | to ignore the check (in which case the pragma has no effect on the program), | |
5180 | or @code{Disable} in which case the pragma is not even checked for correct | |
5181 | syntax. | |
5182 | ||
5183 | Multiple @code{Loop_Invariant} and @code{Loop_Variant} pragmas that | |
5184 | apply to the same loop should be grouped in the same sequence of | |
5185 | statements. | |
5186 | ||
5187 | The @code{Loop_Entry} attribute may be used within the expressions of the | |
5188 | @code{Loop_Variant} pragma to refer to values on entry to the loop. | |
5189 | ||
5190 | @node Pragma Machine_Attribute,Pragma Main,Pragma Loop_Variant,Implementation Defined Pragmas | |
5191 | @anchor{gnat_rm/implementation_defined_pragmas pragma-machine-attribute}@anchor{9b} | |
5192 | @section Pragma Machine_Attribute | |
64d5610f ML |
5193 | |
5194 | ||
5195 | Syntax: | |
5196 | ||
5197 | @example | |
b71d4b62 RA |
5198 | pragma Machine_Attribute ( |
5199 | [Entity =>] LOCAL_NAME, | |
5200 | [Attribute_Name =>] static_string_EXPRESSION | |
5201 | [, [Info =>] static_EXPRESSION @{, static_EXPRESSION@}] ); | |
64d5610f ML |
5202 | @end example |
5203 | ||
b71d4b62 RA |
5204 | Machine-dependent attributes can be specified for types and/or |
5205 | declarations. This pragma is semantically equivalent to | |
5206 | @code{__attribute__((@var{attribute_name}))} (if @code{info} is not | |
5207 | specified) or @code{__attribute__((@var{attribute_name(info})))} | |
5208 | or @code{__attribute__((@var{attribute_name(info,...})))} in GNU C, | |
5209 | where `attribute_name' is recognized by the compiler middle-end | |
5210 | or the @code{TARGET_ATTRIBUTE_TABLE} machine specific macro. Note | |
5211 | that a string literal for the optional parameter @code{info} or the | |
5212 | following ones is transformed by default into an identifier, | |
5213 | which may make this pragma unusable for some attributes. | |
5214 | For further information see @cite{GNU Compiler Collection (GCC) Internals}. | |
64d5610f | 5215 | |
b71d4b62 RA |
5216 | @node Pragma Main,Pragma Main_Storage,Pragma Machine_Attribute,Implementation Defined Pragmas |
5217 | @anchor{gnat_rm/implementation_defined_pragmas pragma-main}@anchor{9c} | |
5218 | @section Pragma Main | |
64d5610f ML |
5219 | |
5220 | ||
5221 | Syntax: | |
5222 | ||
5223 | @example | |
b71d4b62 RA |
5224 | pragma Main |
5225 | (MAIN_OPTION [, MAIN_OPTION]); | |
64d5610f | 5226 | |
b71d4b62 RA |
5227 | MAIN_OPTION ::= |
5228 | [Stack_Size =>] static_integer_EXPRESSION | |
5229 | | [Task_Stack_Size_Default =>] static_integer_EXPRESSION | |
5230 | | [Time_Slicing_Enabled =>] static_boolean_EXPRESSION | |
5231 | @end example | |
64d5610f | 5232 | |
b71d4b62 RA |
5233 | This pragma is provided for compatibility with OpenVMS VAX Systems. It has |
5234 | no effect in GNAT, other than being syntax checked. | |
64d5610f | 5235 | |
b71d4b62 RA |
5236 | @node Pragma Main_Storage,Pragma Max_Queue_Length,Pragma Main,Implementation Defined Pragmas |
5237 | @anchor{gnat_rm/implementation_defined_pragmas pragma-main-storage}@anchor{9d} | |
5238 | @section Pragma Main_Storage | |
64d5610f | 5239 | |
64d5610f | 5240 | |
b71d4b62 | 5241 | Syntax: |
64d5610f | 5242 | |
b71d4b62 RA |
5243 | @example |
5244 | pragma Main_Storage | |
5245 | (MAIN_STORAGE_OPTION [, MAIN_STORAGE_OPTION]); | |
64d5610f | 5246 | |
b71d4b62 RA |
5247 | MAIN_STORAGE_OPTION ::= |
5248 | [WORKING_STORAGE =>] static_SIMPLE_EXPRESSION | |
5249 | | [TOP_GUARD =>] static_SIMPLE_EXPRESSION | |
5250 | @end example | |
64d5610f | 5251 | |
b71d4b62 RA |
5252 | This pragma is provided for compatibility with OpenVMS VAX Systems. It has |
5253 | no effect in GNAT, other than being syntax checked. | |
64d5610f | 5254 | |
b71d4b62 RA |
5255 | @node Pragma Max_Queue_Length,Pragma No_Body,Pragma Main_Storage,Implementation Defined Pragmas |
5256 | @anchor{gnat_rm/implementation_defined_pragmas id23}@anchor{9e}@anchor{gnat_rm/implementation_defined_pragmas pragma-max-queue-length}@anchor{9f} | |
5257 | @section Pragma Max_Queue_Length | |
64d5610f | 5258 | |
64d5610f | 5259 | |
b71d4b62 | 5260 | Syntax: |
64d5610f | 5261 | |
b71d4b62 RA |
5262 | @example |
5263 | pragma Max_Entry_Queue (static_integer_EXPRESSION); | |
64d5610f ML |
5264 | @end example |
5265 | ||
b71d4b62 RA |
5266 | This pragma is used to specify the maximum callers per entry queue for |
5267 | individual protected entries and entry families. It accepts a single | |
5268 | integer (-1 or more) as a parameter and must appear after the declaration of an | |
5269 | entry. | |
64d5610f | 5270 | |
b71d4b62 | 5271 | A value of -1 represents no additional restriction on queue length. |
64d5610f | 5272 | |
b71d4b62 RA |
5273 | @node Pragma No_Body,Pragma No_Caching,Pragma Max_Queue_Length,Implementation Defined Pragmas |
5274 | @anchor{gnat_rm/implementation_defined_pragmas pragma-no-body}@anchor{a0} | |
5275 | @section Pragma No_Body | |
64d5610f ML |
5276 | |
5277 | ||
b71d4b62 | 5278 | Syntax: |
64d5610f | 5279 | |
b71d4b62 RA |
5280 | @example |
5281 | pragma No_Body; | |
5282 | @end example | |
64d5610f | 5283 | |
b71d4b62 RA |
5284 | There are a number of cases in which a package spec does not require a body, |
5285 | and in fact a body is not permitted. GNAT will not permit the spec to be | |
5286 | compiled if there is a body around. The pragma No_Body allows you to provide | |
5287 | a body file, even in a case where no body is allowed. The body file must | |
5288 | contain only comments and a single No_Body pragma. This is recognized by | |
5289 | the compiler as indicating that no body is logically present. | |
64d5610f | 5290 | |
b71d4b62 RA |
5291 | This is particularly useful during maintenance when a package is modified in |
5292 | such a way that a body needed before is no longer needed. The provision of a | |
5293 | dummy body with a No_Body pragma ensures that there is no interference from | |
5294 | earlier versions of the package body. | |
64d5610f | 5295 | |
b71d4b62 RA |
5296 | @node Pragma No_Caching,Pragma No_Component_Reordering,Pragma No_Body,Implementation Defined Pragmas |
5297 | @anchor{gnat_rm/implementation_defined_pragmas id24}@anchor{a1}@anchor{gnat_rm/implementation_defined_pragmas pragma-no-caching}@anchor{a2} | |
5298 | @section Pragma No_Caching | |
64d5610f | 5299 | |
64d5610f | 5300 | |
b71d4b62 | 5301 | Syntax: |
64d5610f | 5302 | |
b71d4b62 RA |
5303 | @example |
5304 | pragma No_Caching [ (static_boolean_EXPRESSION) ]; | |
5305 | @end example | |
64d5610f | 5306 | |
b71d4b62 RA |
5307 | For the semantics of this pragma, see the entry for aspect @code{No_Caching} in |
5308 | the SPARK 2014 Reference Manual, section 7.1.2. | |
64d5610f | 5309 | |
b71d4b62 RA |
5310 | @node Pragma No_Component_Reordering,Pragma No_Elaboration_Code_All,Pragma No_Caching,Implementation Defined Pragmas |
5311 | @anchor{gnat_rm/implementation_defined_pragmas pragma-no-component-reordering}@anchor{a3} | |
5312 | @section Pragma No_Component_Reordering | |
64d5610f | 5313 | |
64d5610f | 5314 | |
b71d4b62 | 5315 | Syntax: |
64d5610f | 5316 | |
b71d4b62 RA |
5317 | @example |
5318 | pragma No_Component_Reordering [([Entity =>] type_LOCAL_NAME)]; | |
5319 | @end example | |
64d5610f | 5320 | |
b71d4b62 RA |
5321 | @code{type_LOCAL_NAME} must refer to a record type declaration in the current |
5322 | declarative part. The effect is to preclude any reordering of components | |
5323 | for the layout of the record, i.e. the record is laid out by the compiler | |
5324 | in the order in which the components are declared textually. The form with | |
5325 | no argument is a configuration pragma which applies to all record types | |
5326 | declared in units to which the pragma applies and there is a requirement | |
5327 | that this pragma be used consistently within a partition. | |
64d5610f | 5328 | |
b71d4b62 RA |
5329 | @node Pragma No_Elaboration_Code_All,Pragma No_Heap_Finalization,Pragma No_Component_Reordering,Implementation Defined Pragmas |
5330 | @anchor{gnat_rm/implementation_defined_pragmas id25}@anchor{a4}@anchor{gnat_rm/implementation_defined_pragmas pragma-no-elaboration-code-all}@anchor{a5} | |
5331 | @section Pragma No_Elaboration_Code_All | |
64d5610f ML |
5332 | |
5333 | ||
5334 | Syntax: | |
5335 | ||
5336 | @example | |
b71d4b62 | 5337 | pragma No_Elaboration_Code_All [(program_unit_NAME)]; |
64d5610f ML |
5338 | @end example |
5339 | ||
b71d4b62 RA |
5340 | This is a program unit pragma (there is also an equivalent aspect of the |
5341 | same name) that establishes the restriction @code{No_Elaboration_Code} for | |
5342 | the current unit and any extended main source units (body and subunits). | |
5343 | It also has the effect of enforcing a transitive application of this | |
5344 | aspect, so that if any unit is implicitly or explicitly with’ed by the | |
5345 | current unit, it must also have the No_Elaboration_Code_All aspect set. | |
5346 | It may be applied to package or subprogram specs or their generic versions. | |
64d5610f | 5347 | |
b71d4b62 RA |
5348 | @node Pragma No_Heap_Finalization,Pragma No_Inline,Pragma No_Elaboration_Code_All,Implementation Defined Pragmas |
5349 | @anchor{gnat_rm/implementation_defined_pragmas pragma-no-heap-finalization}@anchor{a6} | |
5350 | @section Pragma No_Heap_Finalization | |
64d5610f ML |
5351 | |
5352 | ||
5353 | Syntax: | |
5354 | ||
5355 | @example | |
b71d4b62 | 5356 | pragma No_Heap_Finalization [ (first_subtype_LOCAL_NAME) ]; |
64d5610f ML |
5357 | @end example |
5358 | ||
b71d4b62 RA |
5359 | Pragma @code{No_Heap_Finalization} may be used as a configuration pragma or as a |
5360 | type-specific pragma. | |
64d5610f | 5361 | |
b71d4b62 RA |
5362 | In its configuration form, the pragma must appear within a configuration file |
5363 | such as gnat.adc, without an argument. The pragma suppresses the call to | |
5364 | @code{Finalize} for heap-allocated objects created through library-level named | |
5365 | access-to-object types in cases where the designated type requires finalization | |
5366 | actions. | |
64d5610f | 5367 | |
b71d4b62 RA |
5368 | In its type-specific form, the argument of the pragma must denote a |
5369 | library-level named access-to-object type. The pragma suppresses the call to | |
5370 | @code{Finalize} for heap-allocated objects created through the specific access type | |
5371 | in cases where the designated type requires finalization actions. | |
64d5610f | 5372 | |
b71d4b62 RA |
5373 | It is still possible to finalize such heap-allocated objects by explicitly |
5374 | deallocating them. | |
64d5610f | 5375 | |
b71d4b62 RA |
5376 | A library-level named access-to-object type declared within a generic unit will |
5377 | lose its @code{No_Heap_Finalization} pragma when the corresponding instance does not | |
5378 | appear at the library level. | |
64d5610f | 5379 | |
b71d4b62 RA |
5380 | @node Pragma No_Inline,Pragma No_Return,Pragma No_Heap_Finalization,Implementation Defined Pragmas |
5381 | @anchor{gnat_rm/implementation_defined_pragmas id26}@anchor{a7}@anchor{gnat_rm/implementation_defined_pragmas pragma-no-inline}@anchor{a8} | |
5382 | @section Pragma No_Inline | |
64d5610f ML |
5383 | |
5384 | ||
5385 | Syntax: | |
5386 | ||
5387 | @example | |
b71d4b62 | 5388 | pragma No_Inline (NAME @{, NAME@}); |
64d5610f ML |
5389 | @end example |
5390 | ||
b71d4b62 RA |
5391 | This pragma suppresses inlining for the callable entity or the instances of |
5392 | the generic subprogram designated by @code{NAME}, including inlining that | |
5393 | results from the use of pragma @code{Inline}. This pragma is always active, | |
5394 | in particular it is not subject to the use of option `-gnatn' or | |
5395 | `-gnatN'. It is illegal to specify both pragma @code{No_Inline} and | |
5396 | pragma @code{Inline_Always} for the same @code{NAME}. | |
5397 | ||
5398 | @node Pragma No_Return,Pragma No_Strict_Aliasing,Pragma No_Inline,Implementation Defined Pragmas | |
5399 | @anchor{gnat_rm/implementation_defined_pragmas pragma-no-return}@anchor{a9} | |
5400 | @section Pragma No_Return | |
64d5610f | 5401 | |
b71d4b62 RA |
5402 | |
5403 | Syntax: | |
64d5610f ML |
5404 | |
5405 | @example | |
b71d4b62 | 5406 | pragma No_Return (procedure_LOCAL_NAME @{, procedure_LOCAL_NAME@}); |
64d5610f ML |
5407 | @end example |
5408 | ||
b71d4b62 RA |
5409 | Each @code{procedure_LOCAL_NAME} argument must refer to one or more procedure |
5410 | declarations in the current declarative part. A procedure to which this | |
5411 | pragma is applied may not contain any explicit @code{return} statements. | |
5412 | In addition, if the procedure contains any implicit returns from falling | |
5413 | off the end of a statement sequence, then execution of that implicit | |
5414 | return will cause Program_Error to be raised. | |
64d5610f | 5415 | |
b71d4b62 RA |
5416 | One use of this pragma is to identify procedures whose only purpose is to raise |
5417 | an exception. Another use of this pragma is to suppress incorrect warnings | |
5418 | about missing returns in functions, where the last statement of a function | |
5419 | statement sequence is a call to such a procedure. | |
64d5610f | 5420 | |
b71d4b62 RA |
5421 | Note that in Ada 2005 mode, this pragma is part of the language. It is |
5422 | available in all earlier versions of Ada as an implementation-defined | |
5423 | pragma. | |
64d5610f | 5424 | |
b71d4b62 RA |
5425 | @node Pragma No_Strict_Aliasing,Pragma No_Tagged_Streams,Pragma No_Return,Implementation Defined Pragmas |
5426 | @anchor{gnat_rm/implementation_defined_pragmas pragma-no-strict-aliasing}@anchor{aa} | |
5427 | @section Pragma No_Strict_Aliasing | |
64d5610f ML |
5428 | |
5429 | ||
5430 | Syntax: | |
5431 | ||
5432 | @example | |
b71d4b62 | 5433 | pragma No_Strict_Aliasing [([Entity =>] type_LOCAL_NAME)]; |
64d5610f ML |
5434 | @end example |
5435 | ||
b71d4b62 RA |
5436 | @code{type_LOCAL_NAME} must refer to an access type |
5437 | declaration in the current declarative part. The effect is to inhibit | |
5438 | strict aliasing optimization for the given type. The form with no | |
5439 | arguments is a configuration pragma which applies to all access types | |
5440 | declared in units to which the pragma applies. For a detailed | |
5441 | description of the strict aliasing optimization, and the situations | |
5442 | in which it must be suppressed, see the section on Optimization and Strict Aliasing | |
5443 | in the @cite{GNAT User’s Guide}. | |
64d5610f | 5444 | |
b71d4b62 RA |
5445 | This pragma currently has no effects on access to unconstrained array types. |
5446 | ||
5447 | @node Pragma No_Tagged_Streams,Pragma Normalize_Scalars,Pragma No_Strict_Aliasing,Implementation Defined Pragmas | |
5448 | @anchor{gnat_rm/implementation_defined_pragmas id27}@anchor{ab}@anchor{gnat_rm/implementation_defined_pragmas pragma-no-tagged-streams}@anchor{ac} | |
5449 | @section Pragma No_Tagged_Streams | |
64d5610f ML |
5450 | |
5451 | ||
5452 | Syntax: | |
5453 | ||
5454 | @example | |
b71d4b62 | 5455 | pragma No_Tagged_Streams [([Entity =>] tagged_type_LOCAL_NAME)]; |
64d5610f ML |
5456 | @end example |
5457 | ||
b71d4b62 RA |
5458 | Normally when a tagged type is introduced using a full type declaration, |
5459 | part of the processing includes generating stream access routines to be | |
5460 | used by stream attributes referencing the type (or one of its subtypes | |
5461 | or derived types). This can involve the generation of significant amounts | |
5462 | of code which is wasted space if stream routines are not needed for the | |
5463 | type in question. | |
64d5610f | 5464 | |
b71d4b62 RA |
5465 | The @code{No_Tagged_Streams} pragma causes the generation of these stream |
5466 | routines to be skipped, and any attempt to use stream operations on | |
5467 | types subject to this pragma will be statically rejected as illegal. | |
64d5610f | 5468 | |
b71d4b62 RA |
5469 | There are two forms of the pragma. The form with no arguments must appear |
5470 | in a declarative sequence or in the declarations of a package spec. This | |
5471 | pragma affects all subsequent root tagged types declared in the declaration | |
5472 | sequence, and specifies that no stream routines be generated. The form with | |
5473 | an argument (for which there is also a corresponding aspect) specifies a | |
5474 | single root tagged type for which stream routines are not to be generated. | |
64d5610f | 5475 | |
b71d4b62 RA |
5476 | Once the pragma has been given for a particular root tagged type, all subtypes |
5477 | and derived types of this type inherit the pragma automatically, so the effect | |
5478 | applies to a complete hierarchy (this is necessary to deal with the class-wide | |
5479 | dispatching versions of the stream routines). | |
64d5610f | 5480 | |
b71d4b62 RA |
5481 | When pragmas @code{Discard_Names} and @code{No_Tagged_Streams} are simultaneously |
5482 | applied to a tagged type its Expanded_Name and External_Tag are initialized | |
5483 | with empty strings. This is useful to avoid exposing entity names at binary | |
5484 | level but has a negative impact on the debuggability of tagged types. | |
64d5610f | 5485 | |
b71d4b62 RA |
5486 | @node Pragma Normalize_Scalars,Pragma Obsolescent,Pragma No_Tagged_Streams,Implementation Defined Pragmas |
5487 | @anchor{gnat_rm/implementation_defined_pragmas pragma-normalize-scalars}@anchor{ad} | |
5488 | @section Pragma Normalize_Scalars | |
64d5610f ML |
5489 | |
5490 | ||
5491 | Syntax: | |
5492 | ||
5493 | @example | |
b71d4b62 | 5494 | pragma Normalize_Scalars; |
64d5610f ML |
5495 | @end example |
5496 | ||
b71d4b62 RA |
5497 | This is a language defined pragma which is fully implemented in GNAT. The |
5498 | effect is to cause all scalar objects that are not otherwise initialized | |
5499 | to be initialized. The initial values are implementation dependent and | |
5500 | are as follows: | |
64d5610f | 5501 | |
64d5610f | 5502 | |
b71d4b62 | 5503 | @table @asis |
64d5610f | 5504 | |
b71d4b62 | 5505 | @item `Standard.Character' |
64d5610f | 5506 | |
b71d4b62 RA |
5507 | Objects whose root type is Standard.Character are initialized to |
5508 | Character’Last unless the subtype range excludes NUL (in which case | |
5509 | NUL is used). This choice will always generate an invalid value if | |
5510 | one exists. | |
64d5610f | 5511 | |
b71d4b62 | 5512 | @item `Standard.Wide_Character' |
64d5610f | 5513 | |
b71d4b62 RA |
5514 | Objects whose root type is Standard.Wide_Character are initialized to |
5515 | Wide_Character’Last unless the subtype range excludes NUL (in which case | |
5516 | NUL is used). This choice will always generate an invalid value if | |
5517 | one exists. | |
64d5610f | 5518 | |
b71d4b62 | 5519 | @item `Standard.Wide_Wide_Character' |
64d5610f | 5520 | |
b71d4b62 RA |
5521 | Objects whose root type is Standard.Wide_Wide_Character are initialized to |
5522 | the invalid value 16#FFFF_FFFF# unless the subtype range excludes NUL (in | |
5523 | which case NUL is used). This choice will always generate an invalid value if | |
5524 | one exists. | |
64d5610f | 5525 | |
b71d4b62 | 5526 | @item `Integer types' |
64d5610f | 5527 | |
b71d4b62 RA |
5528 | Objects of an integer type are treated differently depending on whether |
5529 | negative values are present in the subtype. If no negative values are | |
5530 | present, then all one bits is used as the initial value except in the | |
5531 | special case where zero is excluded from the subtype, in which case | |
5532 | all zero bits are used. This choice will always generate an invalid | |
5533 | value if one exists. | |
64d5610f | 5534 | |
b71d4b62 RA |
5535 | For subtypes with negative values present, the largest negative number |
5536 | is used, except in the unusual case where this largest negative number | |
5537 | is in the subtype, and the largest positive number is not, in which case | |
5538 | the largest positive value is used. This choice will always generate | |
5539 | an invalid value if one exists. | |
64d5610f | 5540 | |
b71d4b62 | 5541 | @item `Floating-Point Types' |
64d5610f | 5542 | |
b71d4b62 RA |
5543 | Objects of all floating-point types are initialized to all 1-bits. For |
5544 | standard IEEE format, this corresponds to a NaN (not a number) which is | |
5545 | indeed an invalid value. | |
64d5610f | 5546 | |
b71d4b62 | 5547 | @item `Fixed-Point Types' |
64d5610f | 5548 | |
b71d4b62 RA |
5549 | Objects of all fixed-point types are treated as described above for integers, |
5550 | with the rules applying to the underlying integer value used to represent | |
5551 | the fixed-point value. | |
64d5610f | 5552 | |
b71d4b62 | 5553 | @item `Modular types' |
64d5610f ML |
5554 | |
5555 | Objects of a modular type are initialized to all one bits, except in | |
5556 | the special case where zero is excluded from the subtype, in which | |
5557 | case all zero bits are used. This choice will always generate an | |
5558 | invalid value if one exists. | |
5559 | ||
5560 | @item `Enumeration types' | |
5561 | ||
5562 | Objects of an enumeration type are initialized to all one-bits, i.e., to | |
5563 | the value @code{2 ** typ'Size - 1} unless the subtype excludes the literal | |
5564 | whose Pos value is zero, in which case a code of zero is used. This choice | |
5565 | will always generate an invalid value if one exists. | |
5566 | @end table | |
5567 | ||
5568 | @node Pragma Obsolescent,Pragma Optimize_Alignment,Pragma Normalize_Scalars,Implementation Defined Pragmas | |
b71d4b62 | 5569 | @anchor{gnat_rm/implementation_defined_pragmas id28}@anchor{ae}@anchor{gnat_rm/implementation_defined_pragmas pragma-obsolescent}@anchor{af} |
64d5610f ML |
5570 | @section Pragma Obsolescent |
5571 | ||
5572 | ||
5573 | Syntax: | |
5574 | ||
5575 | @example | |
5576 | pragma Obsolescent; | |
5577 | ||
5578 | pragma Obsolescent ( | |
5579 | [Message =>] static_string_EXPRESSION | |
5580 | [,[Version =>] Ada_05]); | |
5581 | ||
5582 | pragma Obsolescent ( | |
5583 | [Entity =>] NAME | |
5584 | [,[Message =>] static_string_EXPRESSION | |
5585 | [,[Version =>] Ada_05]]); | |
5586 | @end example | |
5587 | ||
5588 | This pragma can occur immediately following a declaration of an entity, | |
5589 | including the case of a record component. If no Entity argument is present, | |
5590 | then this declaration is the one to which the pragma applies. If an Entity | |
5591 | parameter is present, it must either match the name of the entity in this | |
5592 | declaration, or alternatively, the pragma can immediately follow an enumeration | |
5593 | type declaration, where the Entity argument names one of the enumeration | |
5594 | literals. | |
5595 | ||
5596 | This pragma is used to indicate that the named entity | |
5597 | is considered obsolescent and should not be used. Typically this is | |
5598 | used when an API must be modified by eventually removing or modifying | |
5599 | existing subprograms or other entities. The pragma can be used at an | |
5600 | intermediate stage when the entity is still present, but will be | |
5601 | removed later. | |
5602 | ||
5603 | The effect of this pragma is to output a warning message on a reference to | |
5604 | an entity thus marked that the subprogram is obsolescent if the appropriate | |
5605 | warning option in the compiler is activated. If the @code{Message} parameter is | |
5606 | present, then a second warning message is given containing this text. In | |
5607 | addition, a reference to the entity is considered to be a violation of pragma | |
5608 | @code{Restrictions (No_Obsolescent_Features)}. | |
5609 | ||
5610 | This pragma can also be used as a program unit pragma for a package, | |
5611 | in which case the entity name is the name of the package, and the | |
5612 | pragma indicates that the entire package is considered | |
5613 | obsolescent. In this case a client @code{with}ing such a package | |
5614 | violates the restriction, and the @code{with} clause is | |
5615 | flagged with warnings if the warning option is set. | |
5616 | ||
5617 | If the @code{Version} parameter is present (which must be exactly | |
5618 | the identifier @code{Ada_05}, no other argument is allowed), then the | |
5619 | indication of obsolescence applies only when compiling in Ada 2005 | |
5620 | mode. This is primarily intended for dealing with the situations | |
5621 | in the predefined library where subprograms or packages | |
5622 | have become defined as obsolescent in Ada 2005 | |
5623 | (e.g., in @code{Ada.Characters.Handling}), but may be used anywhere. | |
5624 | ||
5625 | The following examples show typical uses of this pragma: | |
5626 | ||
5627 | @example | |
5628 | package p is | |
5629 | pragma Obsolescent (p, Message => "use pp instead of p"); | |
5630 | end p; | |
5631 | ||
5632 | package q is | |
5633 | procedure q2; | |
5634 | pragma Obsolescent ("use q2new instead"); | |
5635 | ||
5636 | type R is new integer; | |
5637 | pragma Obsolescent | |
5638 | (Entity => R, | |
5639 | Message => "use RR in Ada 2005", | |
5640 | Version => Ada_05); | |
5641 | ||
5642 | type M is record | |
5643 | F1 : Integer; | |
5644 | F2 : Integer; | |
5645 | pragma Obsolescent; | |
5646 | F3 : Integer; | |
5647 | end record; | |
5648 | ||
5649 | type E is (a, bc, 'd', quack); | |
5650 | pragma Obsolescent (Entity => bc) | |
5651 | pragma Obsolescent (Entity => 'd') | |
5652 | ||
5653 | function "+" | |
5654 | (a, b : character) return character; | |
5655 | pragma Obsolescent (Entity => "+"); | |
5656 | end; | |
5657 | @end example | |
5658 | ||
5659 | Note that, as for all pragmas, if you use a pragma argument identifier, | |
5660 | then all subsequent parameters must also use a pragma argument identifier. | |
5661 | So if you specify @code{Entity =>} for the @code{Entity} argument, and a @code{Message} | |
5662 | argument is present, it must be preceded by @code{Message =>}. | |
5663 | ||
5664 | @node Pragma Optimize_Alignment,Pragma Ordered,Pragma Obsolescent,Implementation Defined Pragmas | |
b71d4b62 | 5665 | @anchor{gnat_rm/implementation_defined_pragmas pragma-optimize-alignment}@anchor{b0} |
64d5610f ML |
5666 | @section Pragma Optimize_Alignment |
5667 | ||
5668 | ||
5669 | @geindex Alignment | |
5670 | @geindex default settings | |
5671 | ||
5672 | Syntax: | |
5673 | ||
5674 | @example | |
5675 | pragma Optimize_Alignment (TIME | SPACE | OFF); | |
5676 | @end example | |
5677 | ||
5678 | This is a configuration pragma which affects the choice of default alignments | |
5679 | for types and objects where no alignment is explicitly specified. There is a | |
5680 | time/space trade-off in the selection of these values. Large alignments result | |
5681 | in more efficient code, at the expense of larger data space, since sizes have | |
5682 | to be increased to match these alignments. Smaller alignments save space, but | |
5683 | the access code is slower. The normal choice of default alignments for types | |
5684 | and individual alignment promotions for objects (which is what you get if you | |
5685 | do not use this pragma, or if you use an argument of OFF), tries to balance | |
5686 | these two requirements. | |
5687 | ||
5688 | Specifying SPACE causes smaller default alignments to be chosen in two cases. | |
5689 | First any packed record is given an alignment of 1. Second, if a size is given | |
5690 | for the type, then the alignment is chosen to avoid increasing this size. For | |
5691 | example, consider: | |
5692 | ||
5693 | @example | |
5694 | type R is record | |
5695 | X : Integer; | |
5696 | Y : Character; | |
5697 | end record; | |
5698 | ||
5699 | for R'Size use 5*8; | |
5700 | @end example | |
5701 | ||
5702 | In the default mode, this type gets an alignment of 4, so that access to the | |
5703 | Integer field X are efficient. But this means that objects of the type end up | |
5704 | with a size of 8 bytes. This is a valid choice, since sizes of objects are | |
5705 | allowed to be bigger than the size of the type, but it can waste space if for | |
5706 | example fields of type R appear in an enclosing record. If the above type is | |
5707 | compiled in @code{Optimize_Alignment (Space)} mode, the alignment is set to 1. | |
5708 | ||
5709 | However, there is one case in which SPACE is ignored. If a variable length | |
5710 | record (that is a discriminated record with a component which is an array | |
5711 | whose length depends on a discriminant), has a pragma Pack, then it is not | |
5712 | in general possible to set the alignment of such a record to one, so the | |
5713 | pragma is ignored in this case (with a warning). | |
5714 | ||
5715 | Specifying SPACE also disables alignment promotions for standalone objects, | |
5716 | which occur when the compiler increases the alignment of a specific object | |
5717 | without changing the alignment of its type. | |
5718 | ||
5719 | Specifying SPACE also disables component reordering in unpacked record types, | |
5720 | which can result in larger sizes in order to meet alignment requirements. | |
5721 | ||
5722 | Specifying TIME causes larger default alignments to be chosen in the case of | |
5723 | small types with sizes that are not a power of 2. For example, consider: | |
5724 | ||
5725 | @example | |
5726 | type R is record | |
5727 | A : Character; | |
5728 | B : Character; | |
5729 | C : Boolean; | |
5730 | end record; | |
5731 | ||
5732 | pragma Pack (R); | |
5733 | for R'Size use 17; | |
5734 | @end example | |
5735 | ||
5736 | The default alignment for this record is normally 1, but if this type is | |
5737 | compiled in @code{Optimize_Alignment (Time)} mode, then the alignment is set | |
5738 | to 4, which wastes space for objects of the type, since they are now 4 bytes | |
5739 | long, but results in more efficient access when the whole record is referenced. | |
5740 | ||
5741 | As noted above, this is a configuration pragma, and there is a requirement | |
5742 | that all units in a partition be compiled with a consistent setting of the | |
5743 | optimization setting. This would normally be achieved by use of a configuration | |
5744 | pragma file containing the appropriate setting. The exception to this rule is | |
5745 | that units with an explicit configuration pragma in the same file as the source | |
5746 | unit are excluded from the consistency check, as are all predefined units. The | |
5747 | latter are compiled by default in pragma Optimize_Alignment (Off) mode if no | |
5748 | pragma appears at the start of the file. | |
5749 | ||
5750 | @node Pragma Ordered,Pragma Overflow_Mode,Pragma Optimize_Alignment,Implementation Defined Pragmas | |
b71d4b62 | 5751 | @anchor{gnat_rm/implementation_defined_pragmas pragma-ordered}@anchor{b1} |
64d5610f ML |
5752 | @section Pragma Ordered |
5753 | ||
5754 | ||
5755 | Syntax: | |
5756 | ||
5757 | @example | |
5758 | pragma Ordered (enumeration_first_subtype_LOCAL_NAME); | |
5759 | @end example | |
5760 | ||
5761 | Most enumeration types are from a conceptual point of view unordered. | |
5762 | For example, consider: | |
5763 | ||
5764 | @example | |
5765 | type Color is (Red, Blue, Green, Yellow); | |
5766 | @end example | |
5767 | ||
5768 | By Ada semantics @code{Blue > Red} and @code{Green > Blue}, | |
5769 | but really these relations make no sense; the enumeration type merely | |
5770 | specifies a set of possible colors, and the order is unimportant. | |
5771 | ||
5772 | For unordered enumeration types, it is generally a good idea if | |
5773 | clients avoid comparisons (other than equality or inequality) and | |
5774 | explicit ranges. (A `client' is a unit where the type is referenced, | |
5775 | other than the unit where the type is declared, its body, and its subunits.) | |
5776 | For example, if code buried in some client says: | |
5777 | ||
5778 | @example | |
5779 | if Current_Color < Yellow then ... | |
5780 | if Current_Color in Blue .. Green then ... | |
5781 | @end example | |
5782 | ||
5783 | then the client code is relying on the order, which is undesirable. | |
5784 | It makes the code hard to read and creates maintenance difficulties if | |
5785 | entries have to be added to the enumeration type. Instead, | |
5786 | the code in the client should list the possibilities, or an | |
5787 | appropriate subtype should be declared in the unit that declares | |
5788 | the original enumeration type. E.g., the following subtype could | |
5789 | be declared along with the type @code{Color}: | |
5790 | ||
5791 | @example | |
5792 | subtype RBG is Color range Red .. Green; | |
5793 | @end example | |
5794 | ||
5795 | and then the client could write: | |
5796 | ||
5797 | @example | |
5798 | if Current_Color in RBG then ... | |
5799 | if Current_Color = Blue or Current_Color = Green then ... | |
5800 | @end example | |
5801 | ||
5802 | However, some enumeration types are legitimately ordered from a conceptual | |
5803 | point of view. For example, if you declare: | |
5804 | ||
5805 | @example | |
5806 | type Day is (Mon, Tue, Wed, Thu, Fri, Sat, Sun); | |
5807 | @end example | |
5808 | ||
5809 | then the ordering imposed by the language is reasonable, and | |
5810 | clients can depend on it, writing for example: | |
5811 | ||
5812 | @example | |
5813 | if D in Mon .. Fri then ... | |
5814 | if D < Wed then ... | |
5815 | @end example | |
5816 | ||
5817 | The pragma `Ordered' is provided to mark enumeration types that | |
5818 | are conceptually ordered, alerting the reader that clients may depend | |
5819 | on the ordering. GNAT provides a pragma to mark enumerations as ordered | |
5820 | rather than one to mark them as unordered, since in our experience, | |
5821 | the great majority of enumeration types are conceptually unordered. | |
5822 | ||
5823 | The types @code{Boolean}, @code{Character}, @code{Wide_Character}, | |
5824 | and @code{Wide_Wide_Character} | |
5825 | are considered to be ordered types, so each is declared with a | |
5826 | pragma @code{Ordered} in package @code{Standard}. | |
5827 | ||
5828 | Normally pragma @code{Ordered} serves only as documentation and a guide for | |
5829 | coding standards, but GNAT provides a warning switch `-gnatw.u' that | |
5830 | requests warnings for inappropriate uses (comparisons and explicit | |
5831 | subranges) for unordered types. If this switch is used, then any | |
5832 | enumeration type not marked with pragma @code{Ordered} will be considered | |
5833 | as unordered, and will generate warnings for inappropriate uses. | |
5834 | ||
5835 | Note that generic types are not considered ordered or unordered (since the | |
5836 | template can be instantiated for both cases), so we never generate warnings | |
5837 | for the case of generic enumerated types. | |
5838 | ||
5839 | For additional information please refer to the description of the | |
5840 | `-gnatw.u' switch in the GNAT User’s Guide. | |
5841 | ||
5842 | @node Pragma Overflow_Mode,Pragma Overriding_Renamings,Pragma Ordered,Implementation Defined Pragmas | |
b71d4b62 | 5843 | @anchor{gnat_rm/implementation_defined_pragmas pragma-overflow-mode}@anchor{b2} |
64d5610f ML |
5844 | @section Pragma Overflow_Mode |
5845 | ||
5846 | ||
5847 | Syntax: | |
5848 | ||
5849 | @example | |
5850 | pragma Overflow_Mode | |
5851 | ( [General =>] MODE | |
5852 | [,[Assertions =>] MODE]); | |
5853 | ||
5854 | MODE ::= STRICT | MINIMIZED | ELIMINATED | |
5855 | @end example | |
5856 | ||
5857 | This pragma sets the current overflow mode to the given setting. For details | |
5858 | of the meaning of these modes, please refer to the | |
5859 | ‘Overflow Check Handling in GNAT’ appendix in the | |
5860 | GNAT User’s Guide. If only the @code{General} parameter is present, | |
5861 | the given mode applies to all expressions. If both parameters are present, | |
5862 | the @code{General} mode applies to expressions outside assertions, and | |
5863 | the @code{Eliminated} mode applies to expressions within assertions. | |
5864 | ||
5865 | The case of the @code{MODE} parameter is ignored, | |
5866 | so @code{MINIMIZED}, @code{Minimized} and | |
5867 | @code{minimized} all have the same effect. | |
5868 | ||
5869 | The @code{Overflow_Mode} pragma has the same scoping and placement | |
5870 | rules as pragma @code{Suppress}, so it can occur either as a | |
5871 | configuration pragma, specifying a default for the whole | |
5872 | program, or in a declarative scope, where it applies to the | |
5873 | remaining declarations and statements in that scope. | |
5874 | ||
5875 | The pragma @code{Suppress (Overflow_Check)} suppresses | |
5876 | overflow checking, but does not affect the overflow mode. | |
5877 | ||
5878 | The pragma @code{Unsuppress (Overflow_Check)} unsuppresses (enables) | |
5879 | overflow checking, but does not affect the overflow mode. | |
5880 | ||
6f089469 | 5881 | @node Pragma Overriding_Renamings,Pragma Part_Of,Pragma Overflow_Mode,Implementation Defined Pragmas |
b71d4b62 | 5882 | @anchor{gnat_rm/implementation_defined_pragmas pragma-overriding-renamings}@anchor{b3} |
64d5610f ML |
5883 | @section Pragma Overriding_Renamings |
5884 | ||
5885 | ||
5886 | @geindex Rational profile | |
5887 | ||
5888 | @geindex Rational compatibility | |
5889 | ||
5890 | Syntax: | |
5891 | ||
5892 | @example | |
5893 | pragma Overriding_Renamings; | |
5894 | @end example | |
5895 | ||
5896 | This is a GNAT configuration pragma to simplify porting | |
5897 | legacy code accepted by the Rational | |
5898 | Ada compiler. In the presence of this pragma, a renaming declaration that | |
5899 | renames an inherited operation declared in the same scope is legal if selected | |
5900 | notation is used as in: | |
5901 | ||
5902 | @example | |
5903 | pragma Overriding_Renamings; | |
5904 | ... | |
5905 | package R is | |
5906 | function F (..); | |
5907 | ... | |
5908 | function F (..) renames R.F; | |
5909 | end R; | |
5910 | @end example | |
5911 | ||
5912 | even though | |
5913 | RM 8.3 (15) stipulates that an overridden operation is not visible within the | |
5914 | declaration of the overriding operation. | |
5915 | ||
6f089469 | 5916 | @node Pragma Part_Of,Pragma Partition_Elaboration_Policy,Pragma Overriding_Renamings,Implementation Defined Pragmas |
b71d4b62 | 5917 | @anchor{gnat_rm/implementation_defined_pragmas id29}@anchor{b4}@anchor{gnat_rm/implementation_defined_pragmas pragma-part-of}@anchor{b5} |
6f089469 | 5918 | @section Pragma Part_Of |
64d5610f ML |
5919 | |
5920 | ||
5921 | Syntax: | |
5922 | ||
5923 | @example | |
6f089469 | 5924 | pragma Part_Of (ABSTRACT_STATE); |
64d5610f | 5925 | |
6f089469 | 5926 | ABSTRACT_STATE ::= NAME |
64d5610f ML |
5927 | @end example |
5928 | ||
6f089469 RD |
5929 | For the semantics of this pragma, see the entry for aspect @code{Part_Of} in the |
5930 | SPARK 2014 Reference Manual, section 7.2.6. | |
64d5610f | 5931 | |
6f089469 | 5932 | @node Pragma Partition_Elaboration_Policy,Pragma Passive,Pragma Part_Of,Implementation Defined Pragmas |
b71d4b62 | 5933 | @anchor{gnat_rm/implementation_defined_pragmas pragma-partition-elaboration-policy}@anchor{b6} |
6f089469 | 5934 | @section Pragma Partition_Elaboration_Policy |
64d5610f ML |
5935 | |
5936 | ||
5937 | Syntax: | |
5938 | ||
5939 | @example | |
6f089469 | 5940 | pragma Partition_Elaboration_Policy (POLICY_IDENTIFIER); |
64d5610f | 5941 | |
6f089469 | 5942 | POLICY_IDENTIFIER ::= Concurrent | Sequential |
64d5610f ML |
5943 | @end example |
5944 | ||
6f089469 RD |
5945 | This pragma is standard in Ada 2005, but is available in all earlier |
5946 | versions of Ada as an implementation-defined pragma. | |
5947 | See Ada 2012 Reference Manual for details. | |
64d5610f | 5948 | |
6f089469 | 5949 | @node Pragma Passive,Pragma Persistent_BSS,Pragma Partition_Elaboration_Policy,Implementation Defined Pragmas |
b71d4b62 | 5950 | @anchor{gnat_rm/implementation_defined_pragmas pragma-passive}@anchor{b7} |
64d5610f ML |
5951 | @section Pragma Passive |
5952 | ||
5953 | ||
5954 | Syntax: | |
5955 | ||
5956 | @example | |
5957 | pragma Passive [(Semaphore | No)]; | |
5958 | @end example | |
5959 | ||
5960 | Syntax checked, but otherwise ignored by GNAT. This is recognized for | |
5961 | compatibility with DEC Ada 83 implementations, where it is used within a | |
5962 | task definition to request that a task be made passive. If the argument | |
5963 | @code{Semaphore} is present, or the argument is omitted, then DEC Ada 83 | |
5964 | treats the pragma as an assertion that the containing task is passive | |
5965 | and that optimization of context switch with this task is permitted and | |
5966 | desired. If the argument @code{No} is present, the task must not be | |
5967 | optimized. GNAT does not attempt to optimize any tasks in this manner | |
5968 | (since protected objects are available in place of passive tasks). | |
5969 | ||
5970 | For more information on the subject of passive tasks, see the section | |
5971 | ‘Passive Task Optimization’ in the GNAT Users Guide. | |
5972 | ||
5973 | @node Pragma Persistent_BSS,Pragma Post,Pragma Passive,Implementation Defined Pragmas | |
b71d4b62 | 5974 | @anchor{gnat_rm/implementation_defined_pragmas id30}@anchor{b8}@anchor{gnat_rm/implementation_defined_pragmas pragma-persistent-bss}@anchor{b9} |
64d5610f ML |
5975 | @section Pragma Persistent_BSS |
5976 | ||
5977 | ||
5978 | Syntax: | |
5979 | ||
5980 | @example | |
5981 | pragma Persistent_BSS [(LOCAL_NAME)] | |
5982 | @end example | |
5983 | ||
5984 | This pragma allows selected objects to be placed in the @code{.persistent_bss} | |
5985 | section. On some targets the linker and loader provide for special | |
5986 | treatment of this section, allowing a program to be reloaded without | |
5987 | affecting the contents of this data (hence the name persistent). | |
5988 | ||
5989 | There are two forms of usage. If an argument is given, it must be the | |
5990 | local name of a library-level object, with no explicit initialization | |
5991 | and whose type is potentially persistent. If no argument is given, then | |
5992 | the pragma is a configuration pragma, and applies to all library-level | |
5993 | objects with no explicit initialization of potentially persistent types. | |
5994 | ||
5995 | A potentially persistent type is a scalar type, or an untagged, | |
5996 | non-discriminated record, all of whose components have no explicit | |
5997 | initialization and are themselves of a potentially persistent type, | |
5998 | or an array, all of whose constraints are static, and whose component | |
5999 | type is potentially persistent. | |
6000 | ||
6001 | If this pragma is used on a target where this feature is not supported, | |
6002 | then the pragma will be ignored. See also @code{pragma Linker_Section}. | |
6003 | ||
6004 | @node Pragma Post,Pragma Postcondition,Pragma Persistent_BSS,Implementation Defined Pragmas | |
b71d4b62 | 6005 | @anchor{gnat_rm/implementation_defined_pragmas pragma-post}@anchor{ba} |
64d5610f ML |
6006 | @section Pragma Post |
6007 | ||
6008 | ||
6009 | @geindex Post | |
6010 | ||
6011 | @geindex Checks | |
6012 | @geindex postconditions | |
6013 | ||
6014 | Syntax: | |
6015 | ||
6016 | @example | |
6017 | pragma Post (Boolean_Expression); | |
6018 | @end example | |
6019 | ||
6020 | The @code{Post} pragma is intended to be an exact replacement for | |
6021 | the language-defined | |
6022 | @code{Post} aspect, and shares its restrictions and semantics. | |
6023 | It must appear either immediately following the corresponding | |
6024 | subprogram declaration (only other pragmas may intervene), or | |
6025 | if there is no separate subprogram declaration, then it can | |
6026 | appear at the start of the declarations in a subprogram body | |
6027 | (preceded only by other pragmas). | |
6028 | ||
6029 | @node Pragma Postcondition,Pragma Post_Class,Pragma Post,Implementation Defined Pragmas | |
b71d4b62 | 6030 | @anchor{gnat_rm/implementation_defined_pragmas pragma-postcondition}@anchor{bb} |
64d5610f ML |
6031 | @section Pragma Postcondition |
6032 | ||
6033 | ||
6034 | @geindex Postcondition | |
6035 | ||
6036 | @geindex Checks | |
6037 | @geindex postconditions | |
6038 | ||
6039 | Syntax: | |
6040 | ||
6041 | @example | |
6042 | pragma Postcondition ( | |
6043 | [Check =>] Boolean_Expression | |
6044 | [,[Message =>] String_Expression]); | |
6045 | @end example | |
6046 | ||
6047 | The @code{Postcondition} pragma allows specification of automatic | |
6048 | postcondition checks for subprograms. These checks are similar to | |
6049 | assertions, but are automatically inserted just prior to the return | |
6050 | statements of the subprogram with which they are associated (including | |
6051 | implicit returns at the end of procedure bodies and associated | |
6052 | exception handlers). | |
6053 | ||
6054 | In addition, the boolean expression which is the condition which | |
6055 | must be true may contain references to function’Result in the case | |
6056 | of a function to refer to the returned value. | |
6057 | ||
6058 | @code{Postcondition} pragmas may appear either immediately following the | |
6059 | (separate) declaration of a subprogram, or at the start of the | |
6060 | declarations of a subprogram body. Only other pragmas may intervene | |
6061 | (that is appear between the subprogram declaration and its | |
6062 | postconditions, or appear before the postcondition in the | |
6063 | declaration sequence in a subprogram body). In the case of a | |
6064 | postcondition appearing after a subprogram declaration, the | |
6065 | formal arguments of the subprogram are visible, and can be | |
6066 | referenced in the postcondition expressions. | |
6067 | ||
6068 | The postconditions are collected and automatically tested just | |
6069 | before any return (implicit or explicit) in the subprogram body. | |
6070 | A postcondition is only recognized if postconditions are active | |
6071 | at the time the pragma is encountered. The compiler switch `gnata' | |
6072 | turns on all postconditions by default, and pragma @code{Check_Policy} | |
6073 | with an identifier of @code{Postcondition} can also be used to | |
6074 | control whether postconditions are active. | |
6075 | ||
6076 | The general approach is that postconditions are placed in the spec | |
6077 | if they represent functional aspects which make sense to the client. | |
6078 | For example we might have: | |
6079 | ||
6080 | @example | |
6081 | function Direction return Integer; | |
6082 | pragma Postcondition | |
6083 | (Direction'Result = +1 | |
6084 | or else | |
6085 | Direction'Result = -1); | |
6086 | @end example | |
6087 | ||
6088 | which serves to document that the result must be +1 or -1, and | |
6089 | will test that this is the case at run time if postcondition | |
6090 | checking is active. | |
6091 | ||
6092 | Postconditions within the subprogram body can be used to | |
6093 | check that some internal aspect of the implementation, | |
6094 | not visible to the client, is operating as expected. | |
6095 | For instance if a square root routine keeps an internal | |
6096 | counter of the number of times it is called, then we | |
6097 | might have the following postcondition: | |
6098 | ||
6099 | @example | |
6100 | Sqrt_Calls : Natural := 0; | |
6101 | ||
6102 | function Sqrt (Arg : Float) return Float is | |
6103 | pragma Postcondition | |
6104 | (Sqrt_Calls = Sqrt_Calls'Old + 1); | |
6105 | ... | |
6106 | end Sqrt | |
6107 | @end example | |
6108 | ||
6109 | As this example, shows, the use of the @code{Old} attribute | |
6110 | is often useful in postconditions to refer to the state on | |
6111 | entry to the subprogram. | |
6112 | ||
6113 | Note that postconditions are only checked on normal returns | |
6114 | from the subprogram. If an abnormal return results from | |
6115 | raising an exception, then the postconditions are not checked. | |
6116 | ||
6117 | If a postcondition fails, then the exception | |
6118 | @code{System.Assertions.Assert_Failure} is raised. If | |
6119 | a message argument was supplied, then the given string | |
6120 | will be used as the exception message. If no message | |
6121 | argument was supplied, then the default message has | |
6122 | the form “Postcondition failed at file_name:line”. The | |
6123 | exception is raised in the context of the subprogram | |
6124 | body, so it is possible to catch postcondition failures | |
6125 | within the subprogram body itself. | |
6126 | ||
6127 | Within a package spec, normal visibility rules | |
6128 | in Ada would prevent forward references within a | |
6129 | postcondition pragma to functions defined later in | |
6130 | the same package. This would introduce undesirable | |
6131 | ordering constraints. To avoid this problem, all | |
6132 | postcondition pragmas are analyzed at the end of | |
6133 | the package spec, allowing forward references. | |
6134 | ||
6135 | The following example shows that this even allows | |
6136 | mutually recursive postconditions as in: | |
6137 | ||
6138 | @example | |
6139 | package Parity_Functions is | |
6140 | function Odd (X : Natural) return Boolean; | |
6141 | pragma Postcondition | |
6142 | (Odd'Result = | |
6143 | (x = 1 | |
6144 | or else | |
6145 | (x /= 0 and then Even (X - 1)))); | |
6146 | ||
6147 | function Even (X : Natural) return Boolean; | |
6148 | pragma Postcondition | |
6149 | (Even'Result = | |
6150 | (x = 0 | |
6151 | or else | |
6152 | (x /= 1 and then Odd (X - 1)))); | |
6153 | ||
6154 | end Parity_Functions; | |
6155 | @end example | |
6156 | ||
6157 | There are no restrictions on the complexity or form of | |
6158 | conditions used within @code{Postcondition} pragmas. | |
6159 | The following example shows that it is even possible | |
6160 | to verify performance behavior. | |
6161 | ||
6162 | @example | |
6163 | package Sort is | |
6164 | ||
6165 | Performance : constant Float; | |
6166 | -- Performance constant set by implementation | |
6167 | -- to match target architecture behavior. | |
6168 | ||
6169 | procedure Treesort (Arg : String); | |
6170 | -- Sorts characters of argument using N*logN sort | |
6171 | pragma Postcondition | |
6172 | (Float (Clock - Clock'Old) <= | |
6173 | Float (Arg'Length) * | |
6174 | log (Float (Arg'Length)) * | |
6175 | Performance); | |
6176 | end Sort; | |
6177 | @end example | |
6178 | ||
6179 | Note: postcondition pragmas associated with subprograms that are | |
6180 | marked as Inline_Always, or those marked as Inline with front-end | |
6181 | inlining (-gnatN option set) are accepted and legality-checked | |
6182 | by the compiler, but are ignored at run-time even if postcondition | |
6183 | checking is enabled. | |
6184 | ||
6185 | Note that pragma @code{Postcondition} differs from the language-defined | |
6186 | @code{Post} aspect (and corresponding @code{Post} pragma) in allowing | |
6187 | multiple occurrences, allowing occurences in the body even if there | |
6188 | is a separate spec, and allowing a second string parameter, and the | |
6189 | use of the pragma identifier @code{Check}. Historically, pragma | |
6190 | @code{Postcondition} was implemented prior to the development of | |
6191 | Ada 2012, and has been retained in its original form for | |
6192 | compatibility purposes. | |
6193 | ||
6194 | @node Pragma Post_Class,Pragma Pre,Pragma Postcondition,Implementation Defined Pragmas | |
b71d4b62 | 6195 | @anchor{gnat_rm/implementation_defined_pragmas pragma-post-class}@anchor{bc} |
64d5610f ML |
6196 | @section Pragma Post_Class |
6197 | ||
6198 | ||
6199 | @geindex Post | |
6200 | ||
6201 | @geindex Checks | |
6202 | @geindex postconditions | |
6203 | ||
6204 | Syntax: | |
6205 | ||
6206 | @example | |
6207 | pragma Post_Class (Boolean_Expression); | |
6208 | @end example | |
6209 | ||
6210 | The @code{Post_Class} pragma is intended to be an exact replacement for | |
6211 | the language-defined | |
6212 | @code{Post'Class} aspect, and shares its restrictions and semantics. | |
6213 | It must appear either immediately following the corresponding | |
6214 | subprogram declaration (only other pragmas may intervene), or | |
6215 | if there is no separate subprogram declaration, then it can | |
6216 | appear at the start of the declarations in a subprogram body | |
6217 | (preceded only by other pragmas). | |
6218 | ||
6219 | Note: This pragma is called @code{Post_Class} rather than | |
6220 | @code{Post'Class} because the latter would not be strictly | |
6221 | conforming to the allowed syntax for pragmas. The motivation | |
6222 | for providing pragmas equivalent to the aspects is to allow a program | |
6223 | to be written using the pragmas, and then compiled if necessary | |
6224 | using an Ada compiler that does not recognize the pragmas or | |
6225 | aspects, but is prepared to ignore the pragmas. The assertion | |
6226 | policy that controls this pragma is @code{Post'Class}, not | |
6227 | @code{Post_Class}. | |
6228 | ||
6229 | @node Pragma Pre,Pragma Precondition,Pragma Post_Class,Implementation Defined Pragmas | |
b71d4b62 | 6230 | @anchor{gnat_rm/implementation_defined_pragmas pragma-pre}@anchor{bd} |
64d5610f ML |
6231 | @section Pragma Pre |
6232 | ||
6233 | ||
6234 | @geindex Pre | |
6235 | ||
6236 | @geindex Checks | |
6237 | @geindex preconditions | |
6238 | ||
6239 | Syntax: | |
6240 | ||
6241 | @example | |
6242 | pragma Pre (Boolean_Expression); | |
6243 | @end example | |
6244 | ||
6245 | The @code{Pre} pragma is intended to be an exact replacement for | |
6246 | the language-defined | |
6247 | @code{Pre} aspect, and shares its restrictions and semantics. | |
6248 | It must appear either immediately following the corresponding | |
6249 | subprogram declaration (only other pragmas may intervene), or | |
6250 | if there is no separate subprogram declaration, then it can | |
6251 | appear at the start of the declarations in a subprogram body | |
6252 | (preceded only by other pragmas). | |
6253 | ||
6254 | @node Pragma Precondition,Pragma Predicate,Pragma Pre,Implementation Defined Pragmas | |
b71d4b62 | 6255 | @anchor{gnat_rm/implementation_defined_pragmas pragma-precondition}@anchor{be} |
64d5610f ML |
6256 | @section Pragma Precondition |
6257 | ||
6258 | ||
6259 | @geindex Preconditions | |
6260 | ||
6261 | @geindex Checks | |
6262 | @geindex preconditions | |
6263 | ||
6264 | Syntax: | |
6265 | ||
6266 | @example | |
6267 | pragma Precondition ( | |
6268 | [Check =>] Boolean_Expression | |
6269 | [,[Message =>] String_Expression]); | |
6270 | @end example | |
6271 | ||
6272 | The @code{Precondition} pragma is similar to @code{Postcondition} | |
6273 | except that the corresponding checks take place immediately upon | |
6274 | entry to the subprogram, and if a precondition fails, the exception | |
6275 | is raised in the context of the caller, and the attribute ‘Result | |
6276 | cannot be used within the precondition expression. | |
6277 | ||
6278 | Otherwise, the placement and visibility rules are identical to those | |
6279 | described for postconditions. The following is an example of use | |
6280 | within a package spec: | |
6281 | ||
6282 | @example | |
6283 | package Math_Functions is | |
6284 | ... | |
6285 | function Sqrt (Arg : Float) return Float; | |
6286 | pragma Precondition (Arg >= 0.0) | |
6287 | ... | |
6288 | end Math_Functions; | |
6289 | @end example | |
6290 | ||
6291 | @code{Precondition} pragmas may appear either immediately following the | |
6292 | (separate) declaration of a subprogram, or at the start of the | |
6293 | declarations of a subprogram body. Only other pragmas may intervene | |
6294 | (that is appear between the subprogram declaration and its | |
6295 | postconditions, or appear before the postcondition in the | |
6296 | declaration sequence in a subprogram body). | |
6297 | ||
6298 | Note: precondition pragmas associated with subprograms that are | |
6299 | marked as Inline_Always, or those marked as Inline with front-end | |
6300 | inlining (-gnatN option set) are accepted and legality-checked | |
6301 | by the compiler, but are ignored at run-time even if precondition | |
6302 | checking is enabled. | |
6303 | ||
6304 | Note that pragma @code{Precondition} differs from the language-defined | |
6305 | @code{Pre} aspect (and corresponding @code{Pre} pragma) in allowing | |
6306 | multiple occurrences, allowing occurences in the body even if there | |
6307 | is a separate spec, and allowing a second string parameter, and the | |
6308 | use of the pragma identifier @code{Check}. Historically, pragma | |
6309 | @code{Precondition} was implemented prior to the development of | |
6310 | Ada 2012, and has been retained in its original form for | |
6311 | compatibility purposes. | |
6312 | ||
6313 | @node Pragma Predicate,Pragma Predicate_Failure,Pragma Precondition,Implementation Defined Pragmas | |
b71d4b62 | 6314 | @anchor{gnat_rm/implementation_defined_pragmas id31}@anchor{bf}@anchor{gnat_rm/implementation_defined_pragmas pragma-predicate}@anchor{c0} |
64d5610f ML |
6315 | @section Pragma Predicate |
6316 | ||
6317 | ||
6318 | Syntax: | |
6319 | ||
6320 | @example | |
6321 | pragma Predicate | |
6322 | ([Entity =>] type_LOCAL_NAME, | |
6323 | [Check =>] EXPRESSION); | |
6324 | @end example | |
6325 | ||
6326 | This pragma (available in all versions of Ada in GNAT) encompasses both | |
6327 | the @code{Static_Predicate} and @code{Dynamic_Predicate} aspects in | |
6328 | Ada 2012. A predicate is regarded as static if it has an allowed form | |
6329 | for @code{Static_Predicate} and is otherwise treated as a | |
6330 | @code{Dynamic_Predicate}. Otherwise, predicates specified by this | |
6331 | pragma behave exactly as described in the Ada 2012 reference manual. | |
6332 | For example, if we have | |
6333 | ||
6334 | @example | |
6335 | type R is range 1 .. 10; | |
6336 | subtype S is R; | |
6337 | pragma Predicate (Entity => S, Check => S not in 4 .. 6); | |
6338 | subtype Q is R | |
6339 | pragma Predicate (Entity => Q, Check => F(Q) or G(Q)); | |
6340 | @end example | |
6341 | ||
6342 | the effect is identical to the following Ada 2012 code: | |
6343 | ||
6344 | @example | |
6345 | type R is range 1 .. 10; | |
6346 | subtype S is R with | |
6347 | Static_Predicate => S not in 4 .. 6; | |
6348 | subtype Q is R with | |
6349 | Dynamic_Predicate => F(Q) or G(Q); | |
6350 | @end example | |
6351 | ||
6352 | Note that there are no pragmas @code{Dynamic_Predicate} | |
6353 | or @code{Static_Predicate}. That is | |
6354 | because these pragmas would affect legality and semantics of | |
6355 | the program and thus do not have a neutral effect if ignored. | |
6356 | The motivation behind providing pragmas equivalent to | |
6357 | corresponding aspects is to allow a program to be written | |
6358 | using the pragmas, and then compiled with a compiler that | |
6359 | will ignore the pragmas. That doesn’t work in the case of | |
6360 | static and dynamic predicates, since if the corresponding | |
6361 | pragmas are ignored, then the behavior of the program is | |
6362 | fundamentally changed (for example a membership test | |
6363 | @code{A in B} would not take into account a predicate | |
6364 | defined for subtype B). When following this approach, the | |
6365 | use of predicates should be avoided. | |
6366 | ||
6367 | @node Pragma Predicate_Failure,Pragma Preelaborable_Initialization,Pragma Predicate,Implementation Defined Pragmas | |
b71d4b62 | 6368 | @anchor{gnat_rm/implementation_defined_pragmas pragma-predicate-failure}@anchor{c1} |
64d5610f ML |
6369 | @section Pragma Predicate_Failure |
6370 | ||
6371 | ||
6372 | Syntax: | |
6373 | ||
6374 | @example | |
6375 | pragma Predicate_Failure | |
6376 | ([Entity =>] type_LOCAL_NAME, | |
6377 | [Message =>] String_Expression); | |
6378 | @end example | |
6379 | ||
6380 | The @code{Predicate_Failure} pragma is intended to be an exact replacement for | |
6381 | the language-defined | |
6382 | @code{Predicate_Failure} aspect, and shares its restrictions and semantics. | |
6383 | ||
6384 | @node Pragma Preelaborable_Initialization,Pragma Prefix_Exception_Messages,Pragma Predicate_Failure,Implementation Defined Pragmas | |
b71d4b62 | 6385 | @anchor{gnat_rm/implementation_defined_pragmas pragma-preelaborable-initialization}@anchor{c2} |
64d5610f ML |
6386 | @section Pragma Preelaborable_Initialization |
6387 | ||
6388 | ||
6389 | Syntax: | |
6390 | ||
6391 | @example | |
6392 | pragma Preelaborable_Initialization (DIRECT_NAME); | |
6393 | @end example | |
6394 | ||
6395 | This pragma is standard in Ada 2005, but is available in all earlier | |
6396 | versions of Ada as an implementation-defined pragma. | |
6397 | See Ada 2012 Reference Manual for details. | |
6398 | ||
6399 | @node Pragma Prefix_Exception_Messages,Pragma Pre_Class,Pragma Preelaborable_Initialization,Implementation Defined Pragmas | |
b71d4b62 | 6400 | @anchor{gnat_rm/implementation_defined_pragmas pragma-prefix-exception-messages}@anchor{c3} |
64d5610f ML |
6401 | @section Pragma Prefix_Exception_Messages |
6402 | ||
6403 | ||
6404 | @geindex Prefix_Exception_Messages | |
6405 | ||
6406 | @geindex exception | |
6407 | ||
6408 | @geindex Exception_Message | |
6409 | ||
6410 | Syntax: | |
6411 | ||
6412 | @example | |
6413 | pragma Prefix_Exception_Messages; | |
6414 | @end example | |
6415 | ||
6416 | This is an implementation-defined configuration pragma that affects the | |
6417 | behavior of raise statements with a message given as a static string | |
6418 | constant (typically a string literal). In such cases, the string will | |
6419 | be automatically prefixed by the name of the enclosing entity (giving | |
6420 | the package and subprogram containing the raise statement). This helps | |
6421 | to identify where messages are coming from, and this mode is automatic | |
6422 | for the run-time library. | |
6423 | ||
6424 | The pragma has no effect if the message is computed with an expression other | |
6425 | than a static string constant, since the assumption in this case is that | |
6426 | the program computes exactly the string it wants. If you still want the | |
6427 | prefixing in this case, you can always call | |
6428 | @code{GNAT.Source_Info.Enclosing_Entity} and prepend the string manually. | |
6429 | ||
6430 | @node Pragma Pre_Class,Pragma Priority_Specific_Dispatching,Pragma Prefix_Exception_Messages,Implementation Defined Pragmas | |
b71d4b62 | 6431 | @anchor{gnat_rm/implementation_defined_pragmas pragma-pre-class}@anchor{c4} |
64d5610f ML |
6432 | @section Pragma Pre_Class |
6433 | ||
6434 | ||
6435 | @geindex Pre_Class | |
6436 | ||
6437 | @geindex Checks | |
6438 | @geindex preconditions | |
6439 | ||
6440 | Syntax: | |
6441 | ||
6442 | @example | |
6443 | pragma Pre_Class (Boolean_Expression); | |
6444 | @end example | |
6445 | ||
6446 | The @code{Pre_Class} pragma is intended to be an exact replacement for | |
6447 | the language-defined | |
6448 | @code{Pre'Class} aspect, and shares its restrictions and semantics. | |
6449 | It must appear either immediately following the corresponding | |
6450 | subprogram declaration (only other pragmas may intervene), or | |
6451 | if there is no separate subprogram declaration, then it can | |
6452 | appear at the start of the declarations in a subprogram body | |
6453 | (preceded only by other pragmas). | |
6454 | ||
6455 | Note: This pragma is called @code{Pre_Class} rather than | |
6456 | @code{Pre'Class} because the latter would not be strictly | |
6457 | conforming to the allowed syntax for pragmas. The motivation | |
6458 | for providing pragmas equivalent to the aspects is to allow a program | |
6459 | to be written using the pragmas, and then compiled if necessary | |
6460 | using an Ada compiler that does not recognize the pragmas or | |
6461 | aspects, but is prepared to ignore the pragmas. The assertion | |
6462 | policy that controls this pragma is @code{Pre'Class}, not | |
6463 | @code{Pre_Class}. | |
6464 | ||
6465 | @node Pragma Priority_Specific_Dispatching,Pragma Profile,Pragma Pre_Class,Implementation Defined Pragmas | |
b71d4b62 | 6466 | @anchor{gnat_rm/implementation_defined_pragmas pragma-priority-specific-dispatching}@anchor{c5} |
64d5610f ML |
6467 | @section Pragma Priority_Specific_Dispatching |
6468 | ||
6469 | ||
6470 | Syntax: | |
6471 | ||
6472 | @example | |
6473 | pragma Priority_Specific_Dispatching ( | |
6474 | POLICY_IDENTIFIER, | |
6475 | first_priority_EXPRESSION, | |
6476 | last_priority_EXPRESSION) | |
6477 | ||
6478 | POLICY_IDENTIFIER ::= | |
6479 | EDF_Across_Priorities | | |
6480 | FIFO_Within_Priorities | | |
6481 | Non_Preemptive_Within_Priorities | | |
6482 | Round_Robin_Within_Priorities | |
6483 | @end example | |
6484 | ||
6485 | This pragma is standard in Ada 2005, but is available in all earlier | |
6486 | versions of Ada as an implementation-defined pragma. | |
6487 | See Ada 2012 Reference Manual for details. | |
6488 | ||
6489 | @node Pragma Profile,Pragma Profile_Warnings,Pragma Priority_Specific_Dispatching,Implementation Defined Pragmas | |
b71d4b62 | 6490 | @anchor{gnat_rm/implementation_defined_pragmas pragma-profile}@anchor{c6} |
64d5610f ML |
6491 | @section Pragma Profile |
6492 | ||
6493 | ||
6494 | Syntax: | |
6495 | ||
6496 | @example | |
6497 | pragma Profile (Ravenscar | Restricted | Rational | Jorvik | | |
6498 | GNAT_Extended_Ravenscar | GNAT_Ravenscar_EDF ); | |
6499 | @end example | |
6500 | ||
6501 | This pragma is standard in Ada 2005, but is available in all earlier | |
6502 | versions of Ada as an implementation-defined pragma. This is a | |
6503 | configuration pragma that establishes a set of configuration pragmas | |
6504 | that depend on the argument. @code{Ravenscar} is standard in Ada 2005. | |
6505 | @code{Jorvik} is standard in Ada 202x. | |
6506 | The other possibilities (@code{Restricted}, @code{Rational}, | |
6507 | @code{GNAT_Extended_Ravenscar}, @code{GNAT_Ravenscar_EDF}) | |
6508 | are implementation-defined. @code{GNAT_Extended_Ravenscar} is an alias for @code{Jorvik}. | |
6509 | ||
6510 | The set of configuration pragmas is defined in the following sections. | |
6511 | ||
6512 | ||
6513 | @itemize * | |
6514 | ||
6515 | @item | |
6516 | Pragma Profile (Ravenscar) | |
6517 | ||
6518 | The @code{Ravenscar} profile is standard in Ada 2005, | |
6519 | but is available in all earlier | |
6520 | versions of Ada as an implementation-defined pragma. This profile | |
6521 | establishes the following set of configuration pragmas: | |
6522 | ||
6523 | ||
6524 | @itemize * | |
6525 | ||
6526 | @item | |
6527 | @code{Task_Dispatching_Policy (FIFO_Within_Priorities)} | |
6528 | ||
6529 | [RM D.2.2] Tasks are dispatched following a preemptive | |
6530 | priority-ordered scheduling policy. | |
6531 | ||
6532 | @item | |
6533 | @code{Locking_Policy (Ceiling_Locking)} | |
6534 | ||
6535 | [RM D.3] While tasks and interrupts execute a protected action, they inherit | |
6536 | the ceiling priority of the corresponding protected object. | |
6537 | ||
6538 | @item | |
6539 | @code{Detect_Blocking} | |
6540 | ||
6541 | This pragma forces the detection of potentially blocking operations within a | |
6542 | protected operation, and to raise Program_Error if that happens. | |
6543 | @end itemize | |
6544 | ||
6545 | plus the following set of restrictions: | |
6546 | ||
6547 | ||
6548 | @itemize * | |
6549 | ||
6550 | @item | |
6551 | @code{Max_Entry_Queue_Length => 1} | |
6552 | ||
6553 | No task can be queued on a protected entry. | |
6554 | ||
6555 | @item | |
6556 | @code{Max_Protected_Entries => 1} | |
6557 | ||
6558 | @item | |
6559 | @code{Max_Task_Entries => 0} | |
6560 | ||
6561 | No rendezvous statements are allowed. | |
6562 | ||
6563 | @item | |
6564 | @code{No_Abort_Statements} | |
6565 | ||
6566 | @item | |
6567 | @code{No_Dynamic_Attachment} | |
6568 | ||
6569 | @item | |
6570 | @code{No_Dynamic_Priorities} | |
6571 | ||
6572 | @item | |
6573 | @code{No_Implicit_Heap_Allocations} | |
6574 | ||
6575 | @item | |
6576 | @code{No_Local_Protected_Objects} | |
6577 | ||
6578 | @item | |
6579 | @code{No_Local_Timing_Events} | |
6580 | ||
6581 | @item | |
6582 | @code{No_Protected_Type_Allocators} | |
6583 | ||
6584 | @item | |
6585 | @code{No_Relative_Delay} | |
6586 | ||
6587 | @item | |
6588 | @code{No_Requeue_Statements} | |
6589 | ||
6590 | @item | |
6591 | @code{No_Select_Statements} | |
6592 | ||
6593 | @item | |
6594 | @code{No_Specific_Termination_Handlers} | |
6595 | ||
6596 | @item | |
6597 | @code{No_Task_Allocators} | |
6598 | ||
6599 | @item | |
6600 | @code{No_Task_Hierarchy} | |
6601 | ||
6602 | @item | |
6603 | @code{No_Task_Termination} | |
6604 | ||
6605 | @item | |
6606 | @code{Simple_Barriers} | |
6607 | @end itemize | |
6608 | ||
6609 | The Ravenscar profile also includes the following restrictions that specify | |
6610 | that there are no semantic dependencies on the corresponding predefined | |
6611 | packages: | |
6612 | ||
6613 | ||
6614 | @itemize * | |
6615 | ||
6616 | @item | |
6617 | @code{No_Dependence => Ada.Asynchronous_Task_Control} | |
6618 | ||
6619 | @item | |
6620 | @code{No_Dependence => Ada.Calendar} | |
6621 | ||
6622 | @item | |
6623 | @code{No_Dependence => Ada.Execution_Time.Group_Budget} | |
6624 | ||
6625 | @item | |
6626 | @code{No_Dependence => Ada.Execution_Time.Timers} | |
6627 | ||
6628 | @item | |
6629 | @code{No_Dependence => Ada.Task_Attributes} | |
6630 | ||
6631 | @item | |
6632 | @code{No_Dependence => System.Multiprocessors.Dispatching_Domains} | |
6633 | @end itemize | |
6634 | ||
6635 | This set of configuration pragmas and restrictions correspond to the | |
6636 | definition of the ‘Ravenscar Profile’ for limited tasking, devised and | |
6637 | published by the @cite{International Real-Time Ada Workshop@comma{} 1997}. | |
6638 | A description is also available at | |
6639 | @indicateurl{http://www-users.cs.york.ac.uk/~burns/ravenscar.ps}. | |
6640 | ||
6641 | The original definition of the profile was revised at subsequent IRTAW | |
6642 | meetings. It has been included in the ISO | |
6643 | @cite{Guide for the Use of the Ada Programming Language in High Integrity Systems}, | |
6644 | and was made part of the Ada 2005 standard. | |
6645 | The formal definition given by | |
6646 | the Ada Rapporteur Group (ARG) can be found in two Ada Issues (AI-249 and | |
6647 | AI-305) available at | |
6648 | @indicateurl{http://www.ada-auth.org/cgi-bin/cvsweb.cgi/ais/ai-00249.txt} and | |
6649 | @indicateurl{http://www.ada-auth.org/cgi-bin/cvsweb.cgi/ais/ai-00305.txt}. | |
6650 | ||
6651 | The above set is a superset of the restrictions provided by pragma | |
6652 | @code{Profile (Restricted)}, it includes six additional restrictions | |
6653 | (@code{Simple_Barriers}, @code{No_Select_Statements}, | |
6654 | @code{No_Calendar}, @code{No_Implicit_Heap_Allocations}, | |
6655 | @code{No_Relative_Delay} and @code{No_Task_Termination}). This means | |
6656 | that pragma @code{Profile (Ravenscar)}, like the pragma | |
6657 | @code{Profile (Restricted)}, | |
6658 | automatically causes the use of a simplified, | |
6659 | more efficient version of the tasking run-time library. | |
6660 | ||
6661 | @item | |
6662 | Pragma Profile (Jorvik) | |
6663 | ||
6664 | @code{Jorvik} is the new profile added to the Ada 202x draft standard, | |
6665 | previously implemented under the name @code{GNAT_Extended_Ravenscar}. | |
6666 | ||
6667 | The @code{No_Implicit_Heap_Allocations} restriction has been replaced | |
6668 | by @code{No_Implicit_Task_Allocations} and | |
6669 | @code{No_Implicit_Protected_Object_Allocations}. | |
6670 | ||
6671 | The @code{Simple_Barriers} restriction has been replaced by | |
6672 | @code{Pure_Barriers}. | |
6673 | ||
6674 | The @code{Max_Protected_Entries}, @code{Max_Entry_Queue_Length}, and | |
6675 | @code{No_Relative_Delay} restrictions have been removed. | |
6676 | ||
6677 | Details on the rationale for @code{Jorvik} and implications for use may be | |
6678 | found in @cite{A New Ravenscar-Based Profile} by P. Rogers, J. Ruiz, | |
6679 | T. Gingold and P. Bernardi, in @cite{Reliable Software Technologies – Ada Europe 2017}, Springer-Verlag Lecture Notes in Computer Science, | |
6680 | Number 10300. | |
6681 | ||
6682 | @item | |
6683 | Pragma Profile (GNAT_Ravenscar_EDF) | |
6684 | ||
6685 | This profile corresponds to the Ravenscar profile but using | |
6686 | EDF_Across_Priority as the Task_Scheduling_Policy. | |
6687 | ||
6688 | @item | |
6689 | Pragma Profile (Restricted) | |
6690 | ||
6691 | This profile corresponds to the GNAT restricted run time. It | |
6692 | establishes the following set of restrictions: | |
6693 | ||
6694 | ||
6695 | @itemize * | |
6696 | ||
6697 | @item | |
6698 | @code{No_Abort_Statements} | |
6699 | ||
6700 | @item | |
6701 | @code{No_Entry_Queue} | |
6702 | ||
6703 | @item | |
6704 | @code{No_Task_Hierarchy} | |
6705 | ||
6706 | @item | |
6707 | @code{No_Task_Allocators} | |
6708 | ||
6709 | @item | |
6710 | @code{No_Dynamic_Priorities} | |
6711 | ||
6712 | @item | |
6713 | @code{No_Terminate_Alternatives} | |
6714 | ||
6715 | @item | |
6716 | @code{No_Dynamic_Attachment} | |
6717 | ||
6718 | @item | |
6719 | @code{No_Protected_Type_Allocators} | |
6720 | ||
6721 | @item | |
6722 | @code{No_Local_Protected_Objects} | |
6723 | ||
6724 | @item | |
6725 | @code{No_Requeue_Statements} | |
6726 | ||
6727 | @item | |
6728 | @code{No_Task_Attributes_Package} | |
6729 | ||
6730 | @item | |
6731 | @code{Max_Asynchronous_Select_Nesting = 0} | |
6732 | ||
6733 | @item | |
6734 | @code{Max_Task_Entries = 0} | |
6735 | ||
6736 | @item | |
6737 | @code{Max_Protected_Entries = 1} | |
6738 | ||
6739 | @item | |
6740 | @code{Max_Select_Alternatives = 0} | |
6741 | @end itemize | |
6742 | ||
6743 | This set of restrictions causes the automatic selection of a simplified | |
6744 | version of the run time that provides improved performance for the | |
6745 | limited set of tasking functionality permitted by this set of restrictions. | |
6746 | ||
6747 | @item | |
6748 | Pragma Profile (Rational) | |
6749 | ||
6750 | The Rational profile is intended to facilitate porting legacy code that | |
6751 | compiles with the Rational APEX compiler, even when the code includes non- | |
6752 | conforming Ada constructs. The profile enables the following three pragmas: | |
6753 | ||
6754 | ||
6755 | @itemize * | |
6756 | ||
6757 | @item | |
6758 | @code{pragma Implicit_Packing} | |
6759 | ||
6760 | @item | |
6761 | @code{pragma Overriding_Renamings} | |
6762 | ||
6763 | @item | |
6764 | @code{pragma Use_VADS_Size} | |
6765 | @end itemize | |
6766 | @end itemize | |
6767 | ||
6768 | @node Pragma Profile_Warnings,Pragma Propagate_Exceptions,Pragma Profile,Implementation Defined Pragmas | |
b71d4b62 | 6769 | @anchor{gnat_rm/implementation_defined_pragmas pragma-profile-warnings}@anchor{c7} |
64d5610f ML |
6770 | @section Pragma Profile_Warnings |
6771 | ||
6772 | ||
6773 | Syntax: | |
6774 | ||
6775 | @example | |
6776 | pragma Profile_Warnings (Ravenscar | Restricted | Rational); | |
6777 | @end example | |
6778 | ||
6779 | This is an implementation-defined pragma that is similar in | |
6780 | effect to @code{pragma Profile} except that instead of | |
6781 | generating @code{Restrictions} pragmas, it generates | |
6782 | @code{Restriction_Warnings} pragmas. The result is that | |
6783 | violations of the profile generate warning messages instead | |
6784 | of error messages. | |
6785 | ||
6786 | @node Pragma Propagate_Exceptions,Pragma Provide_Shift_Operators,Pragma Profile_Warnings,Implementation Defined Pragmas | |
b71d4b62 | 6787 | @anchor{gnat_rm/implementation_defined_pragmas pragma-propagate-exceptions}@anchor{c8} |
64d5610f ML |
6788 | @section Pragma Propagate_Exceptions |
6789 | ||
6790 | ||
6791 | @geindex Interfacing to C++ | |
6792 | ||
6793 | Syntax: | |
6794 | ||
6795 | @example | |
6796 | pragma Propagate_Exceptions; | |
6797 | @end example | |
6798 | ||
6799 | This pragma is now obsolete and, other than generating a warning if warnings | |
6800 | on obsolescent features are enabled, is ignored. | |
6801 | It is retained for compatibility | |
6802 | purposes. It used to be used in connection with optimization of | |
6803 | a now-obsolete mechanism for implementation of exceptions. | |
6804 | ||
6805 | @node Pragma Provide_Shift_Operators,Pragma Psect_Object,Pragma Propagate_Exceptions,Implementation Defined Pragmas | |
b71d4b62 | 6806 | @anchor{gnat_rm/implementation_defined_pragmas pragma-provide-shift-operators}@anchor{c9} |
64d5610f ML |
6807 | @section Pragma Provide_Shift_Operators |
6808 | ||
6809 | ||
6810 | @geindex Shift operators | |
6811 | ||
6812 | Syntax: | |
6813 | ||
6814 | @example | |
6815 | pragma Provide_Shift_Operators (integer_first_subtype_LOCAL_NAME); | |
6816 | @end example | |
6817 | ||
6818 | This pragma can be applied to a first subtype local name that specifies | |
6819 | either an unsigned or signed type. It has the effect of providing the | |
6820 | five shift operators (Shift_Left, Shift_Right, Shift_Right_Arithmetic, | |
6821 | Rotate_Left and Rotate_Right) for the given type. It is similar to | |
6822 | including the function declarations for these five operators, together | |
6823 | with the pragma Import (Intrinsic, …) statements. | |
6824 | ||
6825 | @node Pragma Psect_Object,Pragma Pure_Function,Pragma Provide_Shift_Operators,Implementation Defined Pragmas | |
b71d4b62 | 6826 | @anchor{gnat_rm/implementation_defined_pragmas pragma-psect-object}@anchor{ca} |
64d5610f ML |
6827 | @section Pragma Psect_Object |
6828 | ||
6829 | ||
6830 | Syntax: | |
6831 | ||
6832 | @example | |
6833 | pragma Psect_Object ( | |
6834 | [Internal =>] LOCAL_NAME, | |
6835 | [, [External =>] EXTERNAL_SYMBOL] | |
6836 | [, [Size =>] EXTERNAL_SYMBOL]); | |
6837 | ||
6838 | EXTERNAL_SYMBOL ::= | |
6839 | IDENTIFIER | |
6840 | | static_string_EXPRESSION | |
6841 | @end example | |
6842 | ||
6843 | This pragma is identical in effect to pragma @code{Common_Object}. | |
6844 | ||
6845 | @node Pragma Pure_Function,Pragma Rational,Pragma Psect_Object,Implementation Defined Pragmas | |
b71d4b62 | 6846 | @anchor{gnat_rm/implementation_defined_pragmas id32}@anchor{cb}@anchor{gnat_rm/implementation_defined_pragmas pragma-pure-function}@anchor{cc} |
64d5610f ML |
6847 | @section Pragma Pure_Function |
6848 | ||
6849 | ||
6850 | Syntax: | |
6851 | ||
6852 | @example | |
6853 | pragma Pure_Function ([Entity =>] function_LOCAL_NAME); | |
6854 | @end example | |
6855 | ||
6856 | This pragma appears in the same declarative part as a function | |
6857 | declaration (or a set of function declarations if more than one | |
6858 | overloaded declaration exists, in which case the pragma applies | |
6859 | to all entities). It specifies that the function @code{Entity} is | |
6860 | to be considered pure for the purposes of code generation. This means | |
6861 | that the compiler can assume that there are no side effects, and | |
6862 | in particular that two identical calls produce the same result in | |
6863 | the same context. It also means that the function can be used in | |
6864 | an address clause. | |
6865 | ||
6866 | Note that, quite deliberately, there are no static checks to try | |
6867 | to ensure that this promise is met, so @code{Pure_Function} can be used | |
6868 | with functions that are conceptually pure, even if they do modify | |
6869 | global variables. For example, a square root function that is | |
6870 | instrumented to count the number of times it is called is still | |
6871 | conceptually pure, and can still be optimized, even though it | |
6872 | modifies a global variable (the count). Memo functions are another | |
6873 | example (where a table of previous calls is kept and consulted to | |
6874 | avoid re-computation). | |
6875 | ||
6876 | Note also that the normal rules excluding optimization of subprograms | |
6877 | in pure units (when parameter types are descended from System.Address, | |
6878 | or when the full view of a parameter type is limited), do not apply | |
6879 | for the Pure_Function case. If you explicitly specify Pure_Function, | |
6880 | the compiler may optimize away calls with identical arguments, and | |
6881 | if that results in unexpected behavior, the proper action is not to | |
6882 | use the pragma for subprograms that are not (conceptually) pure. | |
6883 | ||
6884 | Note: Most functions in a @code{Pure} package are automatically pure, and | |
6885 | there is no need to use pragma @code{Pure_Function} for such functions. One | |
6886 | exception is any function that has at least one formal of type | |
6887 | @code{System.Address} or a type derived from it. Such functions are not | |
6888 | considered pure by default, since the compiler assumes that the | |
6889 | @code{Address} parameter may be functioning as a pointer and that the | |
6890 | referenced data may change even if the address value does not. | |
6891 | Similarly, imported functions are not considered to be pure by default, | |
6892 | since there is no way of checking that they are in fact pure. The use | |
6893 | of pragma @code{Pure_Function} for such a function will override these default | |
6894 | assumption, and cause the compiler to treat a designated subprogram as pure | |
6895 | in these cases. | |
6896 | ||
6897 | Note: If pragma @code{Pure_Function} is applied to a renamed function, it | |
6898 | applies to the underlying renamed function. This can be used to | |
6899 | disambiguate cases of overloading where some but not all functions | |
6900 | in a set of overloaded functions are to be designated as pure. | |
6901 | ||
6902 | If pragma @code{Pure_Function} is applied to a library-level function, the | |
6903 | function is also considered pure from an optimization point of view, but the | |
6904 | unit is not a Pure unit in the categorization sense. So for example, a function | |
6905 | thus marked is free to @code{with} non-pure units. | |
6906 | ||
6907 | @node Pragma Rational,Pragma Ravenscar,Pragma Pure_Function,Implementation Defined Pragmas | |
b71d4b62 | 6908 | @anchor{gnat_rm/implementation_defined_pragmas pragma-rational}@anchor{cd} |
64d5610f ML |
6909 | @section Pragma Rational |
6910 | ||
6911 | ||
6912 | Syntax: | |
6913 | ||
6914 | @example | |
6915 | pragma Rational; | |
6916 | @end example | |
6917 | ||
6918 | This pragma is considered obsolescent, but is retained for | |
6919 | compatibility purposes. It is equivalent to: | |
6920 | ||
6921 | @example | |
6922 | pragma Profile (Rational); | |
6923 | @end example | |
6924 | ||
6925 | @node Pragma Ravenscar,Pragma Refined_Depends,Pragma Rational,Implementation Defined Pragmas | |
b71d4b62 | 6926 | @anchor{gnat_rm/implementation_defined_pragmas pragma-ravenscar}@anchor{ce} |
64d5610f ML |
6927 | @section Pragma Ravenscar |
6928 | ||
6929 | ||
6930 | Syntax: | |
6931 | ||
6932 | @example | |
6933 | pragma Ravenscar; | |
6934 | @end example | |
6935 | ||
6936 | This pragma is considered obsolescent, but is retained for | |
6937 | compatibility purposes. It is equivalent to: | |
6938 | ||
6939 | @example | |
6940 | pragma Profile (Ravenscar); | |
6941 | @end example | |
6942 | ||
6943 | which is the preferred method of setting the @code{Ravenscar} profile. | |
6944 | ||
6945 | @node Pragma Refined_Depends,Pragma Refined_Global,Pragma Ravenscar,Implementation Defined Pragmas | |
b71d4b62 | 6946 | @anchor{gnat_rm/implementation_defined_pragmas id33}@anchor{cf}@anchor{gnat_rm/implementation_defined_pragmas pragma-refined-depends}@anchor{d0} |
64d5610f ML |
6947 | @section Pragma Refined_Depends |
6948 | ||
6949 | ||
6950 | Syntax: | |
6951 | ||
6952 | @example | |
6953 | pragma Refined_Depends (DEPENDENCY_RELATION); | |
6954 | ||
6955 | DEPENDENCY_RELATION ::= | |
6956 | null | |
6957 | | (DEPENDENCY_CLAUSE @{, DEPENDENCY_CLAUSE@}) | |
6958 | ||
6959 | DEPENDENCY_CLAUSE ::= | |
6960 | OUTPUT_LIST =>[+] INPUT_LIST | |
6961 | | NULL_DEPENDENCY_CLAUSE | |
6962 | ||
6963 | NULL_DEPENDENCY_CLAUSE ::= null => INPUT_LIST | |
6964 | ||
6965 | OUTPUT_LIST ::= OUTPUT | (OUTPUT @{, OUTPUT@}) | |
6966 | ||
6967 | INPUT_LIST ::= null | INPUT | (INPUT @{, INPUT@}) | |
6968 | ||
6969 | OUTPUT ::= NAME | FUNCTION_RESULT | |
6970 | INPUT ::= NAME | |
6971 | ||
6972 | where FUNCTION_RESULT is a function Result attribute_reference | |
6973 | @end example | |
6974 | ||
6975 | For the semantics of this pragma, see the entry for aspect @code{Refined_Depends} in | |
6976 | the SPARK 2014 Reference Manual, section 6.1.5. | |
6977 | ||
6978 | @node Pragma Refined_Global,Pragma Refined_Post,Pragma Refined_Depends,Implementation Defined Pragmas | |
b71d4b62 | 6979 | @anchor{gnat_rm/implementation_defined_pragmas id34}@anchor{d1}@anchor{gnat_rm/implementation_defined_pragmas pragma-refined-global}@anchor{d2} |
64d5610f ML |
6980 | @section Pragma Refined_Global |
6981 | ||
6982 | ||
6983 | Syntax: | |
6984 | ||
6985 | @example | |
6986 | pragma Refined_Global (GLOBAL_SPECIFICATION); | |
6987 | ||
6988 | GLOBAL_SPECIFICATION ::= | |
6989 | null | |
6990 | | (GLOBAL_LIST) | |
6991 | | (MODED_GLOBAL_LIST @{, MODED_GLOBAL_LIST@}) | |
6992 | ||
6993 | MODED_GLOBAL_LIST ::= MODE_SELECTOR => GLOBAL_LIST | |
6994 | ||
6995 | MODE_SELECTOR ::= In_Out | Input | Output | Proof_In | |
6996 | GLOBAL_LIST ::= GLOBAL_ITEM | (GLOBAL_ITEM @{, GLOBAL_ITEM@}) | |
6997 | GLOBAL_ITEM ::= NAME | |
6998 | @end example | |
6999 | ||
7000 | For the semantics of this pragma, see the entry for aspect @code{Refined_Global} in | |
7001 | the SPARK 2014 Reference Manual, section 6.1.4. | |
7002 | ||
7003 | @node Pragma Refined_Post,Pragma Refined_State,Pragma Refined_Global,Implementation Defined Pragmas | |
b71d4b62 | 7004 | @anchor{gnat_rm/implementation_defined_pragmas id35}@anchor{d3}@anchor{gnat_rm/implementation_defined_pragmas pragma-refined-post}@anchor{d4} |
64d5610f ML |
7005 | @section Pragma Refined_Post |
7006 | ||
7007 | ||
7008 | Syntax: | |
7009 | ||
7010 | @example | |
7011 | pragma Refined_Post (boolean_EXPRESSION); | |
7012 | @end example | |
7013 | ||
7014 | For the semantics of this pragma, see the entry for aspect @code{Refined_Post} in | |
7015 | the SPARK 2014 Reference Manual, section 7.2.7. | |
7016 | ||
7017 | @node Pragma Refined_State,Pragma Relative_Deadline,Pragma Refined_Post,Implementation Defined Pragmas | |
b71d4b62 | 7018 | @anchor{gnat_rm/implementation_defined_pragmas id36}@anchor{d5}@anchor{gnat_rm/implementation_defined_pragmas pragma-refined-state}@anchor{d6} |
64d5610f ML |
7019 | @section Pragma Refined_State |
7020 | ||
7021 | ||
7022 | Syntax: | |
7023 | ||
7024 | @example | |
7025 | pragma Refined_State (REFINEMENT_LIST); | |
7026 | ||
7027 | REFINEMENT_LIST ::= | |
7028 | (REFINEMENT_CLAUSE @{, REFINEMENT_CLAUSE@}) | |
7029 | ||
7030 | REFINEMENT_CLAUSE ::= state_NAME => CONSTITUENT_LIST | |
7031 | ||
7032 | CONSTITUENT_LIST ::= | |
7033 | null | |
7034 | | CONSTITUENT | |
7035 | | (CONSTITUENT @{, CONSTITUENT@}) | |
7036 | ||
7037 | CONSTITUENT ::= object_NAME | state_NAME | |
7038 | @end example | |
7039 | ||
7040 | For the semantics of this pragma, see the entry for aspect @code{Refined_State} in | |
7041 | the SPARK 2014 Reference Manual, section 7.2.2. | |
7042 | ||
7043 | @node Pragma Relative_Deadline,Pragma Remote_Access_Type,Pragma Refined_State,Implementation Defined Pragmas | |
b71d4b62 | 7044 | @anchor{gnat_rm/implementation_defined_pragmas pragma-relative-deadline}@anchor{d7} |
64d5610f ML |
7045 | @section Pragma Relative_Deadline |
7046 | ||
7047 | ||
7048 | Syntax: | |
7049 | ||
7050 | @example | |
7051 | pragma Relative_Deadline (time_span_EXPRESSION); | |
7052 | @end example | |
7053 | ||
7054 | This pragma is standard in Ada 2005, but is available in all earlier | |
7055 | versions of Ada as an implementation-defined pragma. | |
7056 | See Ada 2012 Reference Manual for details. | |
7057 | ||
7058 | @node Pragma Remote_Access_Type,Pragma Rename_Pragma,Pragma Relative_Deadline,Implementation Defined Pragmas | |
b71d4b62 | 7059 | @anchor{gnat_rm/implementation_defined_pragmas id37}@anchor{d8}@anchor{gnat_rm/implementation_defined_pragmas pragma-remote-access-type}@anchor{d9} |
64d5610f ML |
7060 | @section Pragma Remote_Access_Type |
7061 | ||
7062 | ||
7063 | Syntax: | |
7064 | ||
7065 | @example | |
7066 | pragma Remote_Access_Type ([Entity =>] formal_access_type_LOCAL_NAME); | |
7067 | @end example | |
7068 | ||
7069 | This pragma appears in the formal part of a generic declaration. | |
7070 | It specifies an exception to the RM rule from E.2.2(17/2), which forbids | |
7071 | the use of a remote access to class-wide type as actual for a formal | |
7072 | access type. | |
7073 | ||
7074 | When this pragma applies to a formal access type @code{Entity}, that | |
7075 | type is treated as a remote access to class-wide type in the generic. | |
7076 | It must be a formal general access type, and its designated type must | |
7077 | be the class-wide type of a formal tagged limited private type from the | |
7078 | same generic declaration. | |
7079 | ||
7080 | In the generic unit, the formal type is subject to all restrictions | |
7081 | pertaining to remote access to class-wide types. At instantiation, the | |
7082 | actual type must be a remote access to class-wide type. | |
7083 | ||
7084 | @node Pragma Rename_Pragma,Pragma Restricted_Run_Time,Pragma Remote_Access_Type,Implementation Defined Pragmas | |
b71d4b62 | 7085 | @anchor{gnat_rm/implementation_defined_pragmas pragma-rename-pragma}@anchor{da} |
64d5610f ML |
7086 | @section Pragma Rename_Pragma |
7087 | ||
7088 | ||
7089 | @geindex Pragmas | |
7090 | @geindex synonyms | |
7091 | ||
7092 | Syntax: | |
7093 | ||
7094 | @example | |
7095 | pragma Rename_Pragma ( | |
7096 | [New_Name =>] IDENTIFIER, | |
7097 | [Renamed =>] pragma_IDENTIFIER); | |
7098 | @end example | |
7099 | ||
7100 | This pragma provides a mechanism for supplying new names for existing | |
7101 | pragmas. The @code{New_Name} identifier can subsequently be used as a synonym for | |
7102 | the Renamed pragma. For example, suppose you have code that was originally | |
7103 | developed on a compiler that supports Inline_Only as an implementation defined | |
7104 | pragma. And suppose the semantics of pragma Inline_Only are identical to (or at | |
7105 | least very similar to) the GNAT implementation defined pragma | |
7106 | Inline_Always. You could globally replace Inline_Only with Inline_Always. | |
7107 | ||
7108 | However, to avoid that source modification, you could instead add a | |
7109 | configuration pragma: | |
7110 | ||
7111 | @example | |
7112 | pragma Rename_Pragma ( | |
7113 | New_Name => Inline_Only, | |
7114 | Renamed => Inline_Always); | |
7115 | @end example | |
7116 | ||
7117 | Then GNAT will treat “pragma Inline_Only …” as if you had written | |
7118 | “pragma Inline_Always …”. | |
7119 | ||
7120 | Pragma Inline_Only will not necessarily mean the same thing as the other Ada | |
7121 | compiler; it’s up to you to make sure the semantics are close enough. | |
7122 | ||
7123 | @node Pragma Restricted_Run_Time,Pragma Restriction_Warnings,Pragma Rename_Pragma,Implementation Defined Pragmas | |
b71d4b62 | 7124 | @anchor{gnat_rm/implementation_defined_pragmas pragma-restricted-run-time}@anchor{db} |
64d5610f ML |
7125 | @section Pragma Restricted_Run_Time |
7126 | ||
7127 | ||
7128 | Syntax: | |
7129 | ||
7130 | @example | |
7131 | pragma Restricted_Run_Time; | |
7132 | @end example | |
7133 | ||
7134 | This pragma is considered obsolescent, but is retained for | |
7135 | compatibility purposes. It is equivalent to: | |
7136 | ||
7137 | @example | |
7138 | pragma Profile (Restricted); | |
7139 | @end example | |
7140 | ||
7141 | which is the preferred method of setting the restricted run time | |
7142 | profile. | |
7143 | ||
7144 | @node Pragma Restriction_Warnings,Pragma Reviewable,Pragma Restricted_Run_Time,Implementation Defined Pragmas | |
b71d4b62 | 7145 | @anchor{gnat_rm/implementation_defined_pragmas pragma-restriction-warnings}@anchor{dc} |
64d5610f ML |
7146 | @section Pragma Restriction_Warnings |
7147 | ||
7148 | ||
7149 | Syntax: | |
7150 | ||
7151 | @example | |
7152 | pragma Restriction_Warnings | |
7153 | (restriction_IDENTIFIER @{, restriction_IDENTIFIER@}); | |
7154 | @end example | |
7155 | ||
7156 | This pragma allows a series of restriction identifiers to be | |
7157 | specified (the list of allowed identifiers is the same as for | |
7158 | pragma @code{Restrictions}). For each of these identifiers | |
7159 | the compiler checks for violations of the restriction, but | |
7160 | generates a warning message rather than an error message | |
7161 | if the restriction is violated. | |
7162 | ||
7163 | One use of this is in situations where you want to know | |
7164 | about violations of a restriction, but you want to ignore some of | |
7165 | these violations. Consider this example, where you want to set | |
7166 | Ada_95 mode and enable style checks, but you want to know about | |
7167 | any other use of implementation pragmas: | |
7168 | ||
7169 | @example | |
7170 | pragma Restriction_Warnings (No_Implementation_Pragmas); | |
7171 | pragma Warnings (Off, "violation of No_Implementation_Pragmas"); | |
7172 | pragma Ada_95; | |
7173 | pragma Style_Checks ("2bfhkM160"); | |
7174 | pragma Warnings (On, "violation of No_Implementation_Pragmas"); | |
7175 | @end example | |
7176 | ||
7177 | By including the above lines in a configuration pragmas file, | |
7178 | the Ada_95 and Style_Checks pragmas are accepted without | |
7179 | generating a warning, but any other use of implementation | |
7180 | defined pragmas will cause a warning to be generated. | |
7181 | ||
7182 | @node Pragma Reviewable,Pragma Secondary_Stack_Size,Pragma Restriction_Warnings,Implementation Defined Pragmas | |
b71d4b62 | 7183 | @anchor{gnat_rm/implementation_defined_pragmas pragma-reviewable}@anchor{dd} |
64d5610f ML |
7184 | @section Pragma Reviewable |
7185 | ||
7186 | ||
7187 | Syntax: | |
7188 | ||
7189 | @example | |
7190 | pragma Reviewable; | |
7191 | @end example | |
7192 | ||
7193 | This pragma is an RM-defined standard pragma, but has no effect on the | |
7194 | program being compiled, or on the code generated for the program. | |
7195 | ||
7196 | To obtain the required output specified in RM H.3.1, the compiler must be | |
7197 | run with various special switches as follows: | |
7198 | ||
7199 | ||
7200 | @itemize * | |
7201 | ||
7202 | @item | |
7203 | `Where compiler-generated run-time checks remain' | |
7204 | ||
7205 | The switch `-gnatGL' | |
7206 | may be used to list the expanded code in pseudo-Ada form. | |
7207 | Runtime checks show up in the listing either as explicit | |
7208 | checks or operators marked with @{@} to indicate a check is present. | |
7209 | ||
7210 | @item | |
7211 | `An identification of known exceptions at compile time' | |
7212 | ||
7213 | If the program is compiled with `-gnatwa', | |
7214 | the compiler warning messages will indicate all cases where the compiler | |
7215 | detects that an exception is certain to occur at run time. | |
7216 | ||
7217 | @item | |
7218 | `Possible reads of uninitialized variables' | |
7219 | ||
7220 | The compiler warns of many such cases, but its output is incomplete. | |
7221 | @end itemize | |
7222 | ||
7223 | ||
7224 | A supplemental static analysis tool | |
7225 | may be used to obtain a comprehensive list of all | |
7226 | possible points at which uninitialized data may be read. | |
7227 | ||
7228 | ||
7229 | @itemize * | |
7230 | ||
7231 | @item | |
7232 | `Where run-time support routines are implicitly invoked' | |
7233 | ||
7234 | In the output from `-gnatGL', | |
7235 | run-time calls are explicitly listed as calls to the relevant | |
7236 | run-time routine. | |
7237 | ||
7238 | @item | |
7239 | `Object code listing' | |
7240 | ||
7241 | This may be obtained either by using the `-S' switch, | |
7242 | or the objdump utility. | |
7243 | ||
7244 | @item | |
7245 | `Constructs known to be erroneous at compile time' | |
7246 | ||
7247 | These are identified by warnings issued by the compiler (use `-gnatwa'). | |
7248 | ||
7249 | @item | |
7250 | `Stack usage information' | |
7251 | ||
7252 | Static stack usage data (maximum per-subprogram) can be obtained via the | |
7253 | `-fstack-usage' switch to the compiler. | |
7254 | Dynamic stack usage data (per task) can be obtained via the `-u' switch | |
7255 | to gnatbind | |
7256 | @end itemize | |
7257 | ||
7258 | ||
7259 | ||
7260 | @itemize * | |
7261 | ||
7262 | @item | |
7263 | `Object code listing of entire partition' | |
7264 | ||
7265 | This can be obtained by compiling the partition with `-S', | |
7266 | or by applying objdump | |
7267 | to all the object files that are part of the partition. | |
7268 | ||
7269 | @item | |
7270 | `A description of the run-time model' | |
7271 | ||
7272 | The full sources of the run-time are available, and the documentation of | |
7273 | these routines describes how these run-time routines interface to the | |
7274 | underlying operating system facilities. | |
7275 | ||
7276 | @item | |
7277 | `Control and data-flow information' | |
7278 | @end itemize | |
7279 | ||
7280 | ||
7281 | A supplemental static analysis tool | |
7282 | may be used to obtain complete control and data-flow information, as well as | |
7283 | comprehensive messages identifying possible problems based on this | |
7284 | information. | |
7285 | ||
7286 | @node Pragma Secondary_Stack_Size,Pragma Share_Generic,Pragma Reviewable,Implementation Defined Pragmas | |
b71d4b62 | 7287 | @anchor{gnat_rm/implementation_defined_pragmas id38}@anchor{de}@anchor{gnat_rm/implementation_defined_pragmas pragma-secondary-stack-size}@anchor{df} |
64d5610f ML |
7288 | @section Pragma Secondary_Stack_Size |
7289 | ||
7290 | ||
7291 | Syntax: | |
7292 | ||
7293 | @example | |
7294 | pragma Secondary_Stack_Size (integer_EXPRESSION); | |
7295 | @end example | |
7296 | ||
7297 | This pragma appears within the task definition of a single task declaration | |
7298 | or a task type declaration (like pragma @code{Storage_Size}) and applies to all | |
7299 | task objects of that type. The argument specifies the size of the secondary | |
7300 | stack to be used by these task objects, and must be of an integer type. The | |
7301 | secondary stack is used to handle functions that return a variable-sized | |
7302 | result, for example a function returning an unconstrained String. | |
7303 | ||
7304 | Note this pragma only applies to targets using fixed secondary stacks, like | |
7305 | VxWorks 653 and bare board targets, where a fixed block for the | |
7306 | secondary stack is allocated from the primary stack of the task. By default, | |
7307 | these targets assign a percentage of the primary stack for the secondary stack, | |
7308 | as defined by @code{System.Parameter.Sec_Stack_Percentage}. With this pragma, | |
7309 | an @code{integer_EXPRESSION} of bytes is assigned from the primary stack instead. | |
7310 | ||
7311 | For most targets, the pragma does not apply as the secondary stack grows on | |
7312 | demand: allocated as a chain of blocks in the heap. The default size of these | |
7313 | blocks can be modified via the @code{-D} binder option as described in | |
7314 | @cite{GNAT User’s Guide}. | |
7315 | ||
7316 | Note that no check is made to see if the secondary stack can fit inside the | |
7317 | primary stack. | |
7318 | ||
7319 | Note the pragma cannot appear when the restriction @code{No_Secondary_Stack} | |
7320 | is in effect. | |
7321 | ||
7322 | @node Pragma Share_Generic,Pragma Shared,Pragma Secondary_Stack_Size,Implementation Defined Pragmas | |
b71d4b62 | 7323 | @anchor{gnat_rm/implementation_defined_pragmas pragma-share-generic}@anchor{e0} |
64d5610f ML |
7324 | @section Pragma Share_Generic |
7325 | ||
7326 | ||
7327 | Syntax: | |
7328 | ||
7329 | @example | |
7330 | pragma Share_Generic (GNAME @{, GNAME@}); | |
7331 | ||
7332 | GNAME ::= generic_unit_NAME | generic_instance_NAME | |
7333 | @end example | |
7334 | ||
7335 | This pragma is provided for compatibility with Dec Ada 83. It has | |
7336 | no effect in GNAT (which does not implement shared generics), other | |
7337 | than to check that the given names are all names of generic units or | |
7338 | generic instances. | |
7339 | ||
7340 | @node Pragma Shared,Pragma Short_Circuit_And_Or,Pragma Share_Generic,Implementation Defined Pragmas | |
b71d4b62 | 7341 | @anchor{gnat_rm/implementation_defined_pragmas id39}@anchor{e1}@anchor{gnat_rm/implementation_defined_pragmas pragma-shared}@anchor{e2} |
64d5610f ML |
7342 | @section Pragma Shared |
7343 | ||
7344 | ||
7345 | This pragma is provided for compatibility with Ada 83. The syntax and | |
7346 | semantics are identical to pragma Atomic. | |
7347 | ||
7348 | @node Pragma Short_Circuit_And_Or,Pragma Short_Descriptors,Pragma Shared,Implementation Defined Pragmas | |
b71d4b62 | 7349 | @anchor{gnat_rm/implementation_defined_pragmas pragma-short-circuit-and-or}@anchor{e3} |
64d5610f ML |
7350 | @section Pragma Short_Circuit_And_Or |
7351 | ||
7352 | ||
7353 | Syntax: | |
7354 | ||
7355 | @example | |
7356 | pragma Short_Circuit_And_Or; | |
7357 | @end example | |
7358 | ||
7359 | This configuration pragma causes any occurrence of the AND operator applied to | |
7360 | operands of type Standard.Boolean to be short-circuited (i.e. the AND operator | |
7361 | is treated as if it were AND THEN). Or is similarly treated as OR ELSE. This | |
7362 | may be useful in the context of certification protocols requiring the use of | |
7363 | short-circuited logical operators. If this configuration pragma occurs locally | |
7364 | within the file being compiled, it applies only to the file being compiled. | |
7365 | There is no requirement that all units in a partition use this option. | |
7366 | ||
04d6c745 | 7367 | @node Pragma Short_Descriptors,Pragma Side_Effects,Pragma Short_Circuit_And_Or,Implementation Defined Pragmas |
b71d4b62 | 7368 | @anchor{gnat_rm/implementation_defined_pragmas pragma-short-descriptors}@anchor{e4} |
64d5610f ML |
7369 | @section Pragma Short_Descriptors |
7370 | ||
7371 | ||
7372 | Syntax: | |
7373 | ||
7374 | @example | |
7375 | pragma Short_Descriptors; | |
7376 | @end example | |
7377 | ||
7378 | This pragma is provided for compatibility with other Ada implementations. It | |
7379 | is recognized but ignored by all current versions of GNAT. | |
7380 | ||
04d6c745 YM |
7381 | @node Pragma Side_Effects,Pragma Simple_Storage_Pool_Type,Pragma Short_Descriptors,Implementation Defined Pragmas |
7382 | @anchor{gnat_rm/implementation_defined_pragmas id40}@anchor{e5}@anchor{gnat_rm/implementation_defined_pragmas pragma-side-effects}@anchor{e6} | |
7383 | @section Pragma Side_Effects | |
7384 | ||
7385 | ||
7386 | Syntax: | |
7387 | ||
7388 | @example | |
7389 | pragma Side_Effects [ (static_boolean_EXPRESSION) ]; | |
7390 | @end example | |
7391 | ||
7392 | For the semantics of this pragma, see the entry for aspect | |
7393 | @code{Side_Effects} in the SPARK Reference Manual, section 6.1.11. | |
7394 | ||
7395 | @node Pragma Simple_Storage_Pool_Type,Pragma Source_File_Name,Pragma Side_Effects,Implementation Defined Pragmas | |
7396 | @anchor{gnat_rm/implementation_defined_pragmas id41}@anchor{e7}@anchor{gnat_rm/implementation_defined_pragmas pragma-simple-storage-pool-type}@anchor{e8} | |
64d5610f ML |
7397 | @section Pragma Simple_Storage_Pool_Type |
7398 | ||
7399 | ||
7400 | @geindex Storage pool | |
7401 | @geindex simple | |
7402 | ||
7403 | @geindex Simple storage pool | |
7404 | ||
7405 | Syntax: | |
7406 | ||
7407 | @example | |
7408 | pragma Simple_Storage_Pool_Type (type_LOCAL_NAME); | |
7409 | @end example | |
7410 | ||
7411 | A type can be established as a ‘simple storage pool type’ by applying | |
7412 | the representation pragma @code{Simple_Storage_Pool_Type} to the type. | |
7413 | A type named in the pragma must be a library-level immutably limited record | |
7414 | type or limited tagged type declared immediately within a package declaration. | |
7415 | The type can also be a limited private type whose full type is allowed as | |
7416 | a simple storage pool type. | |
7417 | ||
7418 | For a simple storage pool type @code{SSP}, nonabstract primitive subprograms | |
7419 | @code{Allocate}, @code{Deallocate}, and @code{Storage_Size} can be declared that | |
7420 | are subtype conformant with the following subprogram declarations: | |
7421 | ||
7422 | @example | |
7423 | procedure Allocate | |
7424 | (Pool : in out SSP; | |
7425 | Storage_Address : out System.Address; | |
7426 | Size_In_Storage_Elements : System.Storage_Elements.Storage_Count; | |
7427 | Alignment : System.Storage_Elements.Storage_Count); | |
7428 | ||
7429 | procedure Deallocate | |
7430 | (Pool : in out SSP; | |
7431 | Storage_Address : System.Address; | |
7432 | Size_In_Storage_Elements : System.Storage_Elements.Storage_Count; | |
7433 | Alignment : System.Storage_Elements.Storage_Count); | |
7434 | ||
7435 | function Storage_Size (Pool : SSP) | |
7436 | return System.Storage_Elements.Storage_Count; | |
7437 | @end example | |
7438 | ||
7439 | Procedure @code{Allocate} must be declared, whereas @code{Deallocate} and | |
7440 | @code{Storage_Size} are optional. If @code{Deallocate} is not declared, then | |
7441 | applying an unchecked deallocation has no effect other than to set its actual | |
7442 | parameter to null. If @code{Storage_Size} is not declared, then the | |
7443 | @code{Storage_Size} attribute applied to an access type associated with | |
7444 | a pool object of type SSP returns zero. Additional operations can be declared | |
7445 | for a simple storage pool type (such as for supporting a mark/release | |
7446 | storage-management discipline). | |
7447 | ||
7448 | An object of a simple storage pool type can be associated with an access | |
7449 | type by specifying the attribute | |
04d6c745 | 7450 | @ref{e9,,Simple_Storage_Pool}. For example: |
64d5610f ML |
7451 | |
7452 | @example | |
7453 | My_Pool : My_Simple_Storage_Pool_Type; | |
7454 | ||
7455 | type Acc is access My_Data_Type; | |
7456 | ||
7457 | for Acc'Simple_Storage_Pool use My_Pool; | |
7458 | @end example | |
7459 | ||
04d6c745 | 7460 | See attribute @ref{e9,,Simple_Storage_Pool} |
64d5610f ML |
7461 | for further details. |
7462 | ||
7463 | @node Pragma Source_File_Name,Pragma Source_File_Name_Project,Pragma Simple_Storage_Pool_Type,Implementation Defined Pragmas | |
04d6c745 | 7464 | @anchor{gnat_rm/implementation_defined_pragmas id42}@anchor{ea}@anchor{gnat_rm/implementation_defined_pragmas pragma-source-file-name}@anchor{eb} |
64d5610f ML |
7465 | @section Pragma Source_File_Name |
7466 | ||
7467 | ||
7468 | Syntax: | |
7469 | ||
7470 | @example | |
7471 | pragma Source_File_Name ( | |
7472 | [Unit_Name =>] unit_NAME, | |
7473 | Spec_File_Name => STRING_LITERAL, | |
7474 | [Index => INTEGER_LITERAL]); | |
7475 | ||
7476 | pragma Source_File_Name ( | |
7477 | [Unit_Name =>] unit_NAME, | |
7478 | Body_File_Name => STRING_LITERAL, | |
7479 | [Index => INTEGER_LITERAL]); | |
7480 | @end example | |
7481 | ||
7482 | Use this to override the normal naming convention. It is a configuration | |
7483 | pragma, and so has the usual applicability of configuration pragmas | |
7484 | (i.e., it applies to either an entire partition, or to all units in a | |
7485 | compilation, or to a single unit, depending on how it is used). | |
7486 | @code{unit_name} is mapped to @code{file_name_literal}. The identifier for | |
7487 | the second argument is required, and indicates whether this is the file | |
7488 | name for the spec or for the body. | |
7489 | ||
7490 | The optional Index argument should be used when a file contains multiple | |
7491 | units, and when you do not want to use @code{gnatchop} to separate then | |
7492 | into multiple files (which is the recommended procedure to limit the | |
7493 | number of recompilations that are needed when some sources change). | |
7494 | For instance, if the source file @code{source.ada} contains | |
7495 | ||
7496 | @example | |
7497 | package B is | |
7498 | ... | |
7499 | end B; | |
7500 | ||
7501 | with B; | |
7502 | procedure A is | |
7503 | begin | |
7504 | .. | |
7505 | end A; | |
7506 | @end example | |
7507 | ||
7508 | you could use the following configuration pragmas: | |
7509 | ||
7510 | @example | |
7511 | pragma Source_File_Name | |
7512 | (B, Spec_File_Name => "source.ada", Index => 1); | |
7513 | pragma Source_File_Name | |
7514 | (A, Body_File_Name => "source.ada", Index => 2); | |
7515 | @end example | |
7516 | ||
7517 | Note that the @code{gnatname} utility can also be used to generate those | |
7518 | configuration pragmas. | |
7519 | ||
7520 | Another form of the @code{Source_File_Name} pragma allows | |
7521 | the specification of patterns defining alternative file naming schemes | |
7522 | to apply to all files. | |
7523 | ||
7524 | @example | |
7525 | pragma Source_File_Name | |
7526 | ( [Spec_File_Name =>] STRING_LITERAL | |
7527 | [,[Casing =>] CASING_SPEC] | |
7528 | [,[Dot_Replacement =>] STRING_LITERAL]); | |
7529 | ||
7530 | pragma Source_File_Name | |
7531 | ( [Body_File_Name =>] STRING_LITERAL | |
7532 | [,[Casing =>] CASING_SPEC] | |
7533 | [,[Dot_Replacement =>] STRING_LITERAL]); | |
7534 | ||
7535 | pragma Source_File_Name | |
7536 | ( [Subunit_File_Name =>] STRING_LITERAL | |
7537 | [,[Casing =>] CASING_SPEC] | |
7538 | [,[Dot_Replacement =>] STRING_LITERAL]); | |
7539 | ||
7540 | CASING_SPEC ::= Lowercase | Uppercase | Mixedcase | |
7541 | @end example | |
7542 | ||
7543 | The first argument is a pattern that contains a single asterisk indicating | |
7544 | the point at which the unit name is to be inserted in the pattern string | |
7545 | to form the file name. The second argument is optional. If present it | |
7546 | specifies the casing of the unit name in the resulting file name string. | |
7547 | The default is lower case. Finally the third argument allows for systematic | |
7548 | replacement of any dots in the unit name by the specified string literal. | |
7549 | ||
7550 | Note that Source_File_Name pragmas should not be used if you are using | |
7551 | project files. The reason for this rule is that the project manager is not | |
7552 | aware of these pragmas, and so other tools that use the project file would not | |
7553 | be aware of the intended naming conventions. If you are using project files, | |
7554 | file naming is controlled by Source_File_Name_Project pragmas, which are | |
7555 | usually supplied automatically by the project manager. A pragma | |
04d6c745 | 7556 | Source_File_Name cannot appear after a @ref{ec,,Pragma Source_File_Name_Project}. |
64d5610f ML |
7557 | |
7558 | For more details on the use of the @code{Source_File_Name} pragma, see the | |
7559 | sections on @cite{Using Other File Names} and @cite{Alternative File Naming Schemes} | |
7560 | in the @cite{GNAT User’s Guide}. | |
7561 | ||
7562 | @node Pragma Source_File_Name_Project,Pragma Source_Reference,Pragma Source_File_Name,Implementation Defined Pragmas | |
04d6c745 | 7563 | @anchor{gnat_rm/implementation_defined_pragmas id43}@anchor{ed}@anchor{gnat_rm/implementation_defined_pragmas pragma-source-file-name-project}@anchor{ec} |
64d5610f ML |
7564 | @section Pragma Source_File_Name_Project |
7565 | ||
7566 | ||
7567 | This pragma has the same syntax and semantics as pragma Source_File_Name. | |
7568 | It is only allowed as a stand-alone configuration pragma. | |
04d6c745 | 7569 | It cannot appear after a @ref{eb,,Pragma Source_File_Name}, and |
64d5610f ML |
7570 | most importantly, once pragma Source_File_Name_Project appears, |
7571 | no further Source_File_Name pragmas are allowed. | |
7572 | ||
7573 | The intention is that Source_File_Name_Project pragmas are always | |
7574 | generated by the Project Manager in a manner consistent with the naming | |
7575 | specified in a project file, and when naming is controlled in this manner, | |
7576 | it is not permissible to attempt to modify this naming scheme using | |
7577 | Source_File_Name or Source_File_Name_Project pragmas (which would not be | |
7578 | known to the project manager). | |
7579 | ||
7580 | @node Pragma Source_Reference,Pragma SPARK_Mode,Pragma Source_File_Name_Project,Implementation Defined Pragmas | |
04d6c745 | 7581 | @anchor{gnat_rm/implementation_defined_pragmas pragma-source-reference}@anchor{ee} |
64d5610f ML |
7582 | @section Pragma Source_Reference |
7583 | ||
7584 | ||
7585 | Syntax: | |
7586 | ||
7587 | @example | |
7588 | pragma Source_Reference (INTEGER_LITERAL, STRING_LITERAL); | |
7589 | @end example | |
7590 | ||
7591 | This pragma must appear as the first line of a source file. | |
7592 | @code{integer_literal} is the logical line number of the line following | |
7593 | the pragma line (for use in error messages and debugging | |
7594 | information). @code{string_literal} is a static string constant that | |
7595 | specifies the file name to be used in error messages and debugging | |
7596 | information. This is most notably used for the output of @code{gnatchop} | |
7597 | with the `-r' switch, to make sure that the original unchopped | |
7598 | source file is the one referred to. | |
7599 | ||
7600 | The second argument must be a string literal, it cannot be a static | |
7601 | string expression other than a string literal. This is because its value | |
7602 | is needed for error messages issued by all phases of the compiler. | |
7603 | ||
7604 | @node Pragma SPARK_Mode,Pragma Static_Elaboration_Desired,Pragma Source_Reference,Implementation Defined Pragmas | |
04d6c745 | 7605 | @anchor{gnat_rm/implementation_defined_pragmas id44}@anchor{ef}@anchor{gnat_rm/implementation_defined_pragmas pragma-spark-mode}@anchor{f0} |
64d5610f ML |
7606 | @section Pragma SPARK_Mode |
7607 | ||
7608 | ||
7609 | Syntax: | |
7610 | ||
7611 | @example | |
7612 | pragma SPARK_Mode [(On | Off)] ; | |
7613 | @end example | |
7614 | ||
7615 | In general a program can have some parts that are in SPARK 2014 (and | |
7616 | follow all the rules in the SPARK Reference Manual), and some parts | |
7617 | that are full Ada 2012. | |
7618 | ||
7619 | The SPARK_Mode pragma is used to identify which parts are in SPARK | |
7620 | 2014 (by default programs are in full Ada). The SPARK_Mode pragma can | |
7621 | be used in the following places: | |
7622 | ||
7623 | ||
7624 | @itemize * | |
7625 | ||
7626 | @item | |
7627 | As a configuration pragma, in which case it sets the default mode for | |
7628 | all units compiled with this pragma. | |
7629 | ||
7630 | @item | |
7631 | Immediately following a library-level subprogram spec | |
7632 | ||
7633 | @item | |
7634 | Immediately within a library-level package body | |
7635 | ||
7636 | @item | |
7637 | Immediately following the @code{private} keyword of a library-level | |
7638 | package spec | |
7639 | ||
7640 | @item | |
7641 | Immediately following the @code{begin} keyword of a library-level | |
7642 | package body | |
7643 | ||
7644 | @item | |
7645 | Immediately within a library-level subprogram body | |
7646 | @end itemize | |
7647 | ||
7648 | Normally a subprogram or package spec/body inherits the current mode | |
7649 | that is active at the point it is declared. But this can be overridden | |
7650 | by pragma within the spec or body as above. | |
7651 | ||
7652 | The basic consistency rule is that you can’t turn SPARK_Mode back | |
7653 | @code{On}, once you have explicitly (with a pragma) turned if | |
7654 | @code{Off}. So the following rules apply: | |
7655 | ||
7656 | If a subprogram spec has SPARK_Mode @code{Off}, then the body must | |
7657 | also have SPARK_Mode @code{Off}. | |
7658 | ||
7659 | For a package, we have four parts: | |
7660 | ||
7661 | ||
7662 | @itemize * | |
7663 | ||
7664 | @item | |
7665 | the package public declarations | |
7666 | ||
7667 | @item | |
7668 | the package private part | |
7669 | ||
7670 | @item | |
7671 | the body of the package | |
7672 | ||
7673 | @item | |
7674 | the elaboration code after @code{begin} | |
7675 | @end itemize | |
7676 | ||
7677 | For a package, the rule is that if you explicitly turn SPARK_Mode | |
7678 | @code{Off} for any part, then all the following parts must have | |
7679 | SPARK_Mode @code{Off}. Note that this may require repeating a pragma | |
7680 | SPARK_Mode (@code{Off}) in the body. For example, if we have a | |
7681 | configuration pragma SPARK_Mode (@code{On}) that turns the mode on by | |
7682 | default everywhere, and one particular package spec has pragma | |
7683 | SPARK_Mode (@code{Off}), then that pragma will need to be repeated in | |
7684 | the package body. | |
7685 | ||
7686 | @node Pragma Static_Elaboration_Desired,Pragma Stream_Convert,Pragma SPARK_Mode,Implementation Defined Pragmas | |
04d6c745 | 7687 | @anchor{gnat_rm/implementation_defined_pragmas pragma-static-elaboration-desired}@anchor{f1} |
64d5610f ML |
7688 | @section Pragma Static_Elaboration_Desired |
7689 | ||
7690 | ||
7691 | Syntax: | |
7692 | ||
7693 | @example | |
7694 | pragma Static_Elaboration_Desired; | |
7695 | @end example | |
7696 | ||
7697 | This pragma is used to indicate that the compiler should attempt to initialize | |
7698 | statically the objects declared in the library unit to which the pragma applies, | |
7699 | when these objects are initialized (explicitly or implicitly) by an aggregate. | |
7700 | In the absence of this pragma, aggregates in object declarations are expanded | |
7701 | into assignments and loops, even when the aggregate components are static | |
7702 | constants. When the aggregate is present the compiler builds a static expression | |
7703 | that requires no run-time code, so that the initialized object can be placed in | |
7704 | read-only data space. If the components are not static, or the aggregate has | |
7705 | more that 100 components, the compiler emits a warning that the pragma cannot | |
7706 | be obeyed. (See also the restriction No_Implicit_Loops, which supports static | |
7707 | construction of larger aggregates with static components that include an others | |
7708 | choice.) | |
7709 | ||
7710 | @node Pragma Stream_Convert,Pragma Style_Checks,Pragma Static_Elaboration_Desired,Implementation Defined Pragmas | |
04d6c745 | 7711 | @anchor{gnat_rm/implementation_defined_pragmas pragma-stream-convert}@anchor{f2} |
64d5610f ML |
7712 | @section Pragma Stream_Convert |
7713 | ||
7714 | ||
7715 | Syntax: | |
7716 | ||
7717 | @example | |
7718 | pragma Stream_Convert ( | |
7719 | [Entity =>] type_LOCAL_NAME, | |
7720 | [Read =>] function_NAME, | |
7721 | [Write =>] function_NAME); | |
7722 | @end example | |
7723 | ||
7724 | This pragma provides an efficient way of providing user-defined stream | |
7725 | attributes. Not only is it simpler to use than specifying the attributes | |
7726 | directly, but more importantly, it allows the specification to be made in such | |
7727 | a way that the predefined unit Ada.Streams is not loaded unless it is actually | |
7728 | needed (i.e. unless the stream attributes are actually used); the use of | |
7729 | the Stream_Convert pragma adds no overhead at all, unless the stream | |
7730 | attributes are actually used on the designated type. | |
7731 | ||
7732 | The first argument specifies the type for which stream functions are | |
7733 | provided. The second parameter provides a function used to read values | |
7734 | of this type. It must name a function whose argument type may be any | |
7735 | subtype, and whose returned type must be the type given as the first | |
7736 | argument to the pragma. | |
7737 | ||
7738 | The meaning of the @code{Read} parameter is that if a stream attribute directly | |
7739 | or indirectly specifies reading of the type given as the first parameter, | |
7740 | then a value of the type given as the argument to the Read function is | |
7741 | read from the stream, and then the Read function is used to convert this | |
7742 | to the required target type. | |
7743 | ||
7744 | Similarly the @code{Write} parameter specifies how to treat write attributes | |
7745 | that directly or indirectly apply to the type given as the first parameter. | |
7746 | It must have an input parameter of the type specified by the first parameter, | |
7747 | and the return type must be the same as the input type of the Read function. | |
7748 | The effect is to first call the Write function to convert to the given stream | |
7749 | type, and then write the result type to the stream. | |
7750 | ||
7751 | The Read and Write functions must not be overloaded subprograms. If necessary | |
7752 | renamings can be supplied to meet this requirement. | |
7753 | The usage of this attribute is best illustrated by a simple example, taken | |
7754 | from the GNAT implementation of package Ada.Strings.Unbounded: | |
7755 | ||
7756 | @example | |
7757 | function To_Unbounded (S : String) return Unbounded_String | |
7758 | renames To_Unbounded_String; | |
7759 | ||
7760 | pragma Stream_Convert | |
7761 | (Unbounded_String, To_Unbounded, To_String); | |
7762 | @end example | |
7763 | ||
7764 | The specifications of the referenced functions, as given in the Ada | |
7765 | Reference Manual are: | |
7766 | ||
7767 | @example | |
7768 | function To_Unbounded_String (Source : String) | |
7769 | return Unbounded_String; | |
7770 | ||
7771 | function To_String (Source : Unbounded_String) | |
7772 | return String; | |
7773 | @end example | |
7774 | ||
7775 | The effect is that if the value of an unbounded string is written to a stream, | |
7776 | then the representation of the item in the stream is in the same format that | |
7777 | would be used for @code{Standard.String'Output}, and this same representation | |
7778 | is expected when a value of this type is read from the stream. Note that the | |
7779 | value written always includes the bounds, even for Unbounded_String’Write, | |
7780 | since Unbounded_String is not an array type. | |
7781 | ||
7782 | Note that the @code{Stream_Convert} pragma is not effective in the case of | |
7783 | a derived type of a non-limited tagged type. If such a type is specified then | |
7784 | the pragma is silently ignored, and the default implementation of the stream | |
7785 | attributes is used instead. | |
7786 | ||
7787 | @node Pragma Style_Checks,Pragma Subtitle,Pragma Stream_Convert,Implementation Defined Pragmas | |
04d6c745 | 7788 | @anchor{gnat_rm/implementation_defined_pragmas pragma-style-checks}@anchor{f3} |
64d5610f ML |
7789 | @section Pragma Style_Checks |
7790 | ||
7791 | ||
7792 | Syntax: | |
7793 | ||
7794 | @example | |
7795 | pragma Style_Checks (string_LITERAL | ALL_CHECKS | | |
7796 | On | Off [, LOCAL_NAME]); | |
7797 | @end example | |
7798 | ||
7799 | This pragma is used in conjunction with compiler switches to control the | |
7800 | built in style checking provided by GNAT. The compiler switches, if set, | |
7801 | provide an initial setting for the switches, and this pragma may be used | |
7802 | to modify these settings, or the settings may be provided entirely by | |
7803 | the use of the pragma. This pragma can be used anywhere that a pragma | |
7804 | is legal, including use as a configuration pragma (including use in | |
7805 | the @code{gnat.adc} file). | |
7806 | ||
7807 | The form with a string literal specifies which style options are to be | |
7808 | activated. These are additive, so they apply in addition to any previously | |
7809 | set style check options. The codes for the options are the same as those | |
7810 | used in the `-gnaty' switch to `gcc' or `gnatmake'. | |
7811 | For example the following two methods can be used to enable | |
7812 | layout checking: | |
7813 | ||
7814 | ||
7815 | @itemize * | |
7816 | ||
7817 | @item | |
7818 | @example | |
7819 | pragma Style_Checks ("l"); | |
7820 | @end example | |
7821 | ||
7822 | @item | |
7823 | @example | |
7824 | gcc -c -gnatyl ... | |
7825 | @end example | |
7826 | @end itemize | |
7827 | ||
7828 | The form @code{ALL_CHECKS} activates all standard checks (its use is equivalent | |
7829 | to the use of the @code{gnaty} switch with no options. | |
7830 | See the @cite{GNAT User’s Guide} for details.) | |
7831 | ||
7832 | Note: the behavior is slightly different in GNAT mode (@code{-gnatg} used). | |
7833 | In this case, @code{ALL_CHECKS} implies the standard set of GNAT mode style check | |
7834 | options (i.e. equivalent to @code{-gnatyg}). | |
7835 | ||
7836 | The forms with @code{Off} and @code{On} | |
7837 | can be used to temporarily disable style checks | |
7838 | as shown in the following example: | |
7839 | ||
7840 | @example | |
7841 | pragma Style_Checks ("k"); -- requires keywords in lower case | |
7842 | pragma Style_Checks (Off); -- turn off style checks | |
7843 | NULL; -- this will not generate an error message | |
7844 | pragma Style_Checks (On); -- turn style checks back on | |
7845 | NULL; -- this will generate an error message | |
7846 | @end example | |
7847 | ||
7848 | Finally the two argument form is allowed only if the first argument is | |
7849 | @code{On} or @code{Off}. The effect is to turn of semantic style checks | |
7850 | for the specified entity, as shown in the following example: | |
7851 | ||
7852 | @example | |
7853 | pragma Style_Checks ("r"); -- require consistency of identifier casing | |
7854 | Arg : Integer; | |
7855 | Rf1 : Integer := ARG; -- incorrect, wrong case | |
7856 | pragma Style_Checks (Off, Arg); | |
7857 | Rf2 : Integer := ARG; -- OK, no error | |
7858 | @end example | |
7859 | ||
7860 | @node Pragma Subtitle,Pragma Suppress,Pragma Style_Checks,Implementation Defined Pragmas | |
04d6c745 | 7861 | @anchor{gnat_rm/implementation_defined_pragmas pragma-subtitle}@anchor{f4} |
64d5610f ML |
7862 | @section Pragma Subtitle |
7863 | ||
7864 | ||
7865 | Syntax: | |
7866 | ||
7867 | @example | |
7868 | pragma Subtitle ([Subtitle =>] STRING_LITERAL); | |
7869 | @end example | |
7870 | ||
7871 | This pragma is recognized for compatibility with other Ada compilers | |
7872 | but is ignored by GNAT. | |
7873 | ||
7874 | @node Pragma Suppress,Pragma Suppress_All,Pragma Subtitle,Implementation Defined Pragmas | |
04d6c745 | 7875 | @anchor{gnat_rm/implementation_defined_pragmas pragma-suppress}@anchor{f5} |
64d5610f ML |
7876 | @section Pragma Suppress |
7877 | ||
7878 | ||
7879 | Syntax: | |
7880 | ||
7881 | @example | |
7882 | pragma Suppress (Identifier [, [On =>] Name]); | |
7883 | @end example | |
7884 | ||
7885 | This is a standard pragma, and supports all the check names required in | |
7886 | the RM. It is included here because GNAT recognizes some additional check | |
7887 | names that are implementation defined (as permitted by the RM): | |
7888 | ||
7889 | ||
7890 | @itemize * | |
7891 | ||
7892 | @item | |
7893 | @code{Alignment_Check} can be used to suppress alignment checks | |
7894 | on addresses used in address clauses. Such checks can also be suppressed | |
7895 | by suppressing range checks, but the specific use of @code{Alignment_Check} | |
7896 | allows suppression of alignment checks without suppressing other range checks. | |
7897 | Note that @code{Alignment_Check} is suppressed by default on machines (such as | |
7898 | the x86) with non-strict alignment. | |
7899 | ||
7900 | @item | |
7901 | @code{Atomic_Synchronization} can be used to suppress the special memory | |
7902 | synchronization instructions that are normally generated for access to | |
7903 | @code{Atomic} variables to ensure correct synchronization between tasks | |
7904 | that use such variables for synchronization purposes. | |
7905 | ||
7906 | @item | |
7907 | @code{Duplicated_Tag_Check} Can be used to suppress the check that is generated | |
7908 | for a duplicated tag value when a tagged type is declared. | |
7909 | ||
7910 | @item | |
7911 | @code{Container_Checks} Can be used to suppress all checks within Ada.Containers | |
7912 | and instances of its children, including Tampering_Check. | |
7913 | ||
7914 | @item | |
7915 | @code{Tampering_Check} Can be used to suppress tampering check in the containers. | |
7916 | ||
7917 | @item | |
7918 | @code{Predicate_Check} can be used to control whether predicate checks are | |
7919 | active. It is applicable only to predicates for which the policy is | |
7920 | @code{Check}. Unlike @code{Assertion_Policy}, which determines if a given | |
7921 | predicate is ignored or checked for the whole program, the use of | |
7922 | @code{Suppress} and @code{Unsuppress} with this check name allows a given | |
7923 | predicate to be turned on and off at specific points in the program. | |
7924 | ||
7925 | @item | |
7926 | @code{Validity_Check} can be used specifically to control validity checks. | |
7927 | If @code{Suppress} is used to suppress validity checks, then no validity | |
7928 | checks are performed, including those specified by the appropriate compiler | |
7929 | switch or the @code{Validity_Checks} pragma. | |
7930 | ||
7931 | @item | |
7932 | Additional check names previously introduced by use of the @code{Check_Name} | |
7933 | pragma are also allowed. | |
7934 | @end itemize | |
7935 | ||
7936 | Note that pragma Suppress gives the compiler permission to omit | |
7937 | checks, but does not require the compiler to omit checks. The compiler | |
7938 | will generate checks if they are essentially free, even when they are | |
7939 | suppressed. In particular, if the compiler can prove that a certain | |
7940 | check will necessarily fail, it will generate code to do an | |
7941 | unconditional ‘raise’, even if checks are suppressed. The compiler | |
7942 | warns in this case. | |
7943 | ||
7944 | Of course, run-time checks are omitted whenever the compiler can prove | |
7945 | that they will not fail, whether or not checks are suppressed. | |
7946 | ||
7947 | @node Pragma Suppress_All,Pragma Suppress_Debug_Info,Pragma Suppress,Implementation Defined Pragmas | |
04d6c745 | 7948 | @anchor{gnat_rm/implementation_defined_pragmas pragma-suppress-all}@anchor{f6} |
64d5610f ML |
7949 | @section Pragma Suppress_All |
7950 | ||
7951 | ||
7952 | Syntax: | |
7953 | ||
7954 | @example | |
7955 | pragma Suppress_All; | |
7956 | @end example | |
7957 | ||
7958 | This pragma can appear anywhere within a unit. | |
7959 | The effect is to apply @code{Suppress (All_Checks)} to the unit | |
7960 | in which it appears. This pragma is implemented for compatibility with DEC | |
7961 | Ada 83 usage where it appears at the end of a unit, and for compatibility | |
7962 | with Rational Ada, where it appears as a program unit pragma. | |
7963 | The use of the standard Ada pragma @code{Suppress (All_Checks)} | |
7964 | as a normal configuration pragma is the preferred usage in GNAT. | |
7965 | ||
7966 | @node Pragma Suppress_Debug_Info,Pragma Suppress_Exception_Locations,Pragma Suppress_All,Implementation Defined Pragmas | |
04d6c745 | 7967 | @anchor{gnat_rm/implementation_defined_pragmas id45}@anchor{f7}@anchor{gnat_rm/implementation_defined_pragmas pragma-suppress-debug-info}@anchor{f8} |
64d5610f ML |
7968 | @section Pragma Suppress_Debug_Info |
7969 | ||
7970 | ||
7971 | Syntax: | |
7972 | ||
7973 | @example | |
7974 | pragma Suppress_Debug_Info ([Entity =>] LOCAL_NAME); | |
7975 | @end example | |
7976 | ||
7977 | This pragma can be used to suppress generation of debug information | |
7978 | for the specified entity. It is intended primarily for use in debugging | |
7979 | the debugger, and navigating around debugger problems. | |
7980 | ||
7981 | @node Pragma Suppress_Exception_Locations,Pragma Suppress_Initialization,Pragma Suppress_Debug_Info,Implementation Defined Pragmas | |
04d6c745 | 7982 | @anchor{gnat_rm/implementation_defined_pragmas pragma-suppress-exception-locations}@anchor{f9} |
64d5610f ML |
7983 | @section Pragma Suppress_Exception_Locations |
7984 | ||
7985 | ||
7986 | Syntax: | |
7987 | ||
7988 | @example | |
7989 | pragma Suppress_Exception_Locations; | |
7990 | @end example | |
7991 | ||
7992 | In normal mode, a raise statement for an exception by default generates | |
7993 | an exception message giving the file name and line number for the location | |
7994 | of the raise. This is useful for debugging and logging purposes, but this | |
7995 | entails extra space for the strings for the messages. The configuration | |
7996 | pragma @code{Suppress_Exception_Locations} can be used to suppress the | |
7997 | generation of these strings, with the result that space is saved, but the | |
7998 | exception message for such raises is null. This configuration pragma may | |
7999 | appear in a global configuration pragma file, or in a specific unit as | |
8000 | usual. It is not required that this pragma be used consistently within | |
8001 | a partition, so it is fine to have some units within a partition compiled | |
8002 | with this pragma and others compiled in normal mode without it. | |
8003 | ||
8004 | @node Pragma Suppress_Initialization,Pragma Task_Name,Pragma Suppress_Exception_Locations,Implementation Defined Pragmas | |
04d6c745 | 8005 | @anchor{gnat_rm/implementation_defined_pragmas id46}@anchor{fa}@anchor{gnat_rm/implementation_defined_pragmas pragma-suppress-initialization}@anchor{fb} |
64d5610f ML |
8006 | @section Pragma Suppress_Initialization |
8007 | ||
8008 | ||
8009 | @geindex Suppressing initialization | |
8010 | ||
8011 | @geindex Initialization | |
8012 | @geindex suppression of | |
8013 | ||
8014 | Syntax: | |
8015 | ||
8016 | @example | |
8017 | pragma Suppress_Initialization ([Entity =>] variable_or_subtype_Name); | |
8018 | @end example | |
8019 | ||
8020 | Here variable_or_subtype_Name is the name introduced by a type declaration | |
8021 | or subtype declaration or the name of a variable introduced by an | |
8022 | object declaration. | |
8023 | ||
8024 | In the case of a type or subtype | |
8025 | this pragma suppresses any implicit or explicit initialization | |
8026 | for all variables of the given type or subtype, | |
8027 | including initialization resulting from the use of pragmas | |
8028 | Normalize_Scalars or Initialize_Scalars. | |
8029 | ||
8030 | This is considered a representation item, so it cannot be given after | |
8031 | the type is frozen. It applies to all subsequent object declarations, | |
8032 | and also any allocator that creates objects of the type. | |
8033 | ||
8034 | If the pragma is given for the first subtype, then it is considered | |
8035 | to apply to the base type and all its subtypes. If the pragma is given | |
8036 | for other than a first subtype, then it applies only to the given subtype. | |
8037 | The pragma may not be given after the type is frozen. | |
8038 | ||
8039 | Note that this includes eliminating initialization of discriminants | |
8040 | for discriminated types, and tags for tagged types. In these cases, | |
8041 | you will have to use some non-portable mechanism (e.g. address | |
8042 | overlays or unchecked conversion) to achieve required initialization | |
8043 | of these fields before accessing any object of the corresponding type. | |
8044 | ||
8045 | For the variable case, implicit initialization for the named variable | |
8046 | is suppressed, just as though its subtype had been given in a pragma | |
8047 | Suppress_Initialization, as described above. | |
8048 | ||
8049 | @node Pragma Task_Name,Pragma Task_Storage,Pragma Suppress_Initialization,Implementation Defined Pragmas | |
04d6c745 | 8050 | @anchor{gnat_rm/implementation_defined_pragmas pragma-task-name}@anchor{fc} |
64d5610f ML |
8051 | @section Pragma Task_Name |
8052 | ||
8053 | ||
8054 | Syntax | |
8055 | ||
8056 | @example | |
8057 | pragma Task_Name (string_EXPRESSION); | |
8058 | @end example | |
8059 | ||
8060 | This pragma appears within a task definition (like pragma | |
8061 | @code{Priority}) and applies to the task in which it appears. The | |
8062 | argument must be of type String, and provides a name to be used for | |
8063 | the task instance when the task is created. Note that this expression | |
8064 | is not required to be static, and in particular, it can contain | |
8065 | references to task discriminants. This facility can be used to | |
8066 | provide different names for different tasks as they are created, | |
8067 | as illustrated in the example below. | |
8068 | ||
8069 | The task name is recorded internally in the run-time structures | |
8070 | and is accessible to tools like the debugger. In addition the | |
8071 | routine @code{Ada.Task_Identification.Image} will return this | |
8072 | string, with a unique task address appended. | |
8073 | ||
8074 | @example | |
8075 | -- Example of the use of pragma Task_Name | |
8076 | ||
8077 | with Ada.Task_Identification; | |
8078 | use Ada.Task_Identification; | |
8079 | with Text_IO; use Text_IO; | |
8080 | procedure t3 is | |
8081 | ||
8082 | type Astring is access String; | |
8083 | ||
8084 | task type Task_Typ (Name : access String) is | |
8085 | pragma Task_Name (Name.all); | |
8086 | end Task_Typ; | |
8087 | ||
8088 | task body Task_Typ is | |
8089 | Nam : constant String := Image (Current_Task); | |
8090 | begin | |
8091 | Put_Line ("-->" & Nam (1 .. 14) & "<--"); | |
8092 | end Task_Typ; | |
8093 | ||
8094 | type Ptr_Task is access Task_Typ; | |
8095 | Task_Var : Ptr_Task; | |
8096 | ||
8097 | begin | |
8098 | Task_Var := | |
8099 | new Task_Typ (new String'("This is task 1")); | |
8100 | Task_Var := | |
8101 | new Task_Typ (new String'("This is task 2")); | |
8102 | end; | |
8103 | @end example | |
8104 | ||
8105 | @node Pragma Task_Storage,Pragma Test_Case,Pragma Task_Name,Implementation Defined Pragmas | |
04d6c745 | 8106 | @anchor{gnat_rm/implementation_defined_pragmas pragma-task-storage}@anchor{fd} |
64d5610f ML |
8107 | @section Pragma Task_Storage |
8108 | ||
8109 | ||
8110 | Syntax: | |
8111 | ||
8112 | @example | |
8113 | pragma Task_Storage ( | |
8114 | [Task_Type =>] LOCAL_NAME, | |
8115 | [Top_Guard =>] static_integer_EXPRESSION); | |
8116 | @end example | |
8117 | ||
8118 | This pragma specifies the length of the guard area for tasks. The guard | |
8119 | area is an additional storage area allocated to a task. A value of zero | |
8120 | means that either no guard area is created or a minimal guard area is | |
8121 | created, depending on the target. This pragma can appear anywhere a | |
8122 | @code{Storage_Size} attribute definition clause is allowed for a task | |
8123 | type. | |
8124 | ||
8125 | @node Pragma Test_Case,Pragma Thread_Local_Storage,Pragma Task_Storage,Implementation Defined Pragmas | |
04d6c745 | 8126 | @anchor{gnat_rm/implementation_defined_pragmas id47}@anchor{fe}@anchor{gnat_rm/implementation_defined_pragmas pragma-test-case}@anchor{ff} |
64d5610f ML |
8127 | @section Pragma Test_Case |
8128 | ||
8129 | ||
8130 | @geindex Test cases | |
8131 | ||
8132 | Syntax: | |
8133 | ||
8134 | @example | |
8135 | pragma Test_Case ( | |
8136 | [Name =>] static_string_Expression | |
8137 | ,[Mode =>] (Nominal | Robustness) | |
8138 | [, Requires => Boolean_Expression] | |
8139 | [, Ensures => Boolean_Expression]); | |
8140 | @end example | |
8141 | ||
8142 | The @code{Test_Case} pragma allows defining fine-grain specifications | |
8143 | for use by testing tools. | |
8144 | The compiler checks the validity of the @code{Test_Case} pragma, but its | |
8145 | presence does not lead to any modification of the code generated by the | |
8146 | compiler. | |
8147 | ||
8148 | @code{Test_Case} pragmas may only appear immediately following the | |
8149 | (separate) declaration of a subprogram in a package declaration, inside | |
8150 | a package spec unit. Only other pragmas may intervene (that is appear | |
8151 | between the subprogram declaration and a test case). | |
8152 | ||
8153 | The compiler checks that boolean expressions given in @code{Requires} and | |
8154 | @code{Ensures} are valid, where the rules for @code{Requires} are the | |
8155 | same as the rule for an expression in @code{Precondition} and the rules | |
8156 | for @code{Ensures} are the same as the rule for an expression in | |
8157 | @code{Postcondition}. In particular, attributes @code{'Old} and | |
8158 | @code{'Result} can only be used within the @code{Ensures} | |
8159 | expression. The following is an example of use within a package spec: | |
8160 | ||
8161 | @example | |
8162 | package Math_Functions is | |
8163 | ... | |
8164 | function Sqrt (Arg : Float) return Float; | |
8165 | pragma Test_Case (Name => "Test 1", | |
8166 | Mode => Nominal, | |
8167 | Requires => Arg < 10000.0, | |
8168 | Ensures => Sqrt'Result < 10.0); | |
8169 | ... | |
8170 | end Math_Functions; | |
8171 | @end example | |
8172 | ||
8173 | The meaning of a test case is that there is at least one context where | |
8174 | @code{Requires} holds such that, if the associated subprogram is executed in | |
8175 | that context, then @code{Ensures} holds when the subprogram returns. | |
8176 | Mode @code{Nominal} indicates that the input context should also satisfy the | |
8177 | precondition of the subprogram, and the output context should also satisfy its | |
8178 | postcondition. Mode @code{Robustness} indicates that the precondition and | |
8179 | postcondition of the subprogram should be ignored for this test case. | |
8180 | ||
8181 | @node Pragma Thread_Local_Storage,Pragma Time_Slice,Pragma Test_Case,Implementation Defined Pragmas | |
04d6c745 | 8182 | @anchor{gnat_rm/implementation_defined_pragmas id48}@anchor{100}@anchor{gnat_rm/implementation_defined_pragmas pragma-thread-local-storage}@anchor{101} |
64d5610f ML |
8183 | @section Pragma Thread_Local_Storage |
8184 | ||
8185 | ||
8186 | @geindex Task specific storage | |
8187 | ||
8188 | @geindex TLS (Thread Local Storage) | |
8189 | ||
8190 | @geindex Task_Attributes | |
8191 | ||
8192 | Syntax: | |
8193 | ||
8194 | @example | |
8195 | pragma Thread_Local_Storage ([Entity =>] LOCAL_NAME); | |
8196 | @end example | |
8197 | ||
8198 | This pragma specifies that the specified entity, which must be | |
8199 | a variable declared in a library-level package, is to be marked as | |
8200 | “Thread Local Storage” (@code{TLS}). On systems supporting this (which | |
8201 | include Windows, Solaris, GNU/Linux, and VxWorks), this causes each | |
8202 | thread (and hence each Ada task) to see a distinct copy of the variable. | |
8203 | ||
8204 | The variable must not have default initialization, and if there is | |
8205 | an explicit initialization, it must be either @code{null} for an | |
8206 | access variable, a static expression for a scalar variable, or a fully | |
8207 | static aggregate for a composite type, that is to say, an aggregate all | |
8208 | of whose components are static, and which does not include packed or | |
8209 | discriminated components. | |
8210 | ||
8211 | This provides a low-level mechanism similar to that provided by | |
8212 | the @code{Ada.Task_Attributes} package, but much more efficient | |
8213 | and is also useful in writing interface code that will interact | |
8214 | with foreign threads. | |
8215 | ||
8216 | If this pragma is used on a system where @code{TLS} is not supported, | |
8217 | then an error message will be generated and the program will be rejected. | |
8218 | ||
8219 | @node Pragma Time_Slice,Pragma Title,Pragma Thread_Local_Storage,Implementation Defined Pragmas | |
04d6c745 | 8220 | @anchor{gnat_rm/implementation_defined_pragmas pragma-time-slice}@anchor{102} |
64d5610f ML |
8221 | @section Pragma Time_Slice |
8222 | ||
8223 | ||
8224 | Syntax: | |
8225 | ||
8226 | @example | |
8227 | pragma Time_Slice (static_duration_EXPRESSION); | |
8228 | @end example | |
8229 | ||
8230 | For implementations of GNAT on operating systems where it is possible | |
8231 | to supply a time slice value, this pragma may be used for this purpose. | |
8232 | It is ignored if it is used in a system that does not allow this control, | |
8233 | or if it appears in other than the main program unit. | |
8234 | ||
8235 | @node Pragma Title,Pragma Type_Invariant,Pragma Time_Slice,Implementation Defined Pragmas | |
04d6c745 | 8236 | @anchor{gnat_rm/implementation_defined_pragmas pragma-title}@anchor{103} |
64d5610f ML |
8237 | @section Pragma Title |
8238 | ||
8239 | ||
8240 | Syntax: | |
8241 | ||
8242 | @example | |
8243 | pragma Title (TITLING_OPTION [, TITLING OPTION]); | |
8244 | ||
8245 | TITLING_OPTION ::= | |
8246 | [Title =>] STRING_LITERAL, | |
8247 | | [Subtitle =>] STRING_LITERAL | |
8248 | @end example | |
8249 | ||
8250 | Syntax checked but otherwise ignored by GNAT. This is a listing control | |
8251 | pragma used in DEC Ada 83 implementations to provide a title and/or | |
8252 | subtitle for the program listing. The program listing generated by GNAT | |
8253 | does not have titles or subtitles. | |
8254 | ||
8255 | Unlike other pragmas, the full flexibility of named notation is allowed | |
8256 | for this pragma, i.e., the parameters may be given in any order if named | |
8257 | notation is used, and named and positional notation can be mixed | |
8258 | following the normal rules for procedure calls in Ada. | |
8259 | ||
8260 | @node Pragma Type_Invariant,Pragma Type_Invariant_Class,Pragma Title,Implementation Defined Pragmas | |
04d6c745 | 8261 | @anchor{gnat_rm/implementation_defined_pragmas pragma-type-invariant}@anchor{104} |
64d5610f ML |
8262 | @section Pragma Type_Invariant |
8263 | ||
8264 | ||
8265 | Syntax: | |
8266 | ||
8267 | @example | |
8268 | pragma Type_Invariant | |
8269 | ([Entity =>] type_LOCAL_NAME, | |
8270 | [Check =>] EXPRESSION); | |
8271 | @end example | |
8272 | ||
8273 | The @code{Type_Invariant} pragma is intended to be an exact | |
8274 | replacement for the language-defined @code{Type_Invariant} | |
8275 | aspect, and shares its restrictions and semantics. It differs | |
8276 | from the language defined @code{Invariant} pragma in that it | |
8277 | does not permit a string parameter, and it is | |
8278 | controlled by the assertion identifier @code{Type_Invariant} | |
8279 | rather than @code{Invariant}. | |
8280 | ||
8281 | @node Pragma Type_Invariant_Class,Pragma Unchecked_Union,Pragma Type_Invariant,Implementation Defined Pragmas | |
04d6c745 | 8282 | @anchor{gnat_rm/implementation_defined_pragmas id49}@anchor{105}@anchor{gnat_rm/implementation_defined_pragmas pragma-type-invariant-class}@anchor{106} |
64d5610f ML |
8283 | @section Pragma Type_Invariant_Class |
8284 | ||
8285 | ||
8286 | Syntax: | |
8287 | ||
8288 | @example | |
8289 | pragma Type_Invariant_Class | |
8290 | ([Entity =>] type_LOCAL_NAME, | |
8291 | [Check =>] EXPRESSION); | |
8292 | @end example | |
8293 | ||
8294 | The @code{Type_Invariant_Class} pragma is intended to be an exact | |
8295 | replacement for the language-defined @code{Type_Invariant'Class} | |
8296 | aspect, and shares its restrictions and semantics. | |
8297 | ||
8298 | Note: This pragma is called @code{Type_Invariant_Class} rather than | |
8299 | @code{Type_Invariant'Class} because the latter would not be strictly | |
8300 | conforming to the allowed syntax for pragmas. The motivation | |
8301 | for providing pragmas equivalent to the aspects is to allow a program | |
8302 | to be written using the pragmas, and then compiled if necessary | |
8303 | using an Ada compiler that does not recognize the pragmas or | |
8304 | aspects, but is prepared to ignore the pragmas. The assertion | |
8305 | policy that controls this pragma is @code{Type_Invariant'Class}, | |
8306 | not @code{Type_Invariant_Class}. | |
8307 | ||
8308 | @node Pragma Unchecked_Union,Pragma Unevaluated_Use_Of_Old,Pragma Type_Invariant_Class,Implementation Defined Pragmas | |
04d6c745 | 8309 | @anchor{gnat_rm/implementation_defined_pragmas pragma-unchecked-union}@anchor{107} |
64d5610f ML |
8310 | @section Pragma Unchecked_Union |
8311 | ||
8312 | ||
8313 | @geindex Unions in C | |
8314 | ||
8315 | Syntax: | |
8316 | ||
8317 | @example | |
8318 | pragma Unchecked_Union (first_subtype_LOCAL_NAME); | |
8319 | @end example | |
8320 | ||
8321 | This pragma is used to specify a representation of a record type that is | |
8322 | equivalent to a C union. It was introduced as a GNAT implementation defined | |
8323 | pragma in the GNAT Ada 95 mode. Ada 2005 includes an extended version of this | |
8324 | pragma, making it language defined, and GNAT fully implements this extended | |
8325 | version in all language modes (Ada 83, Ada 95, and Ada 2005). For full | |
8326 | details, consult the Ada 2012 Reference Manual, section B.3.3. | |
8327 | ||
8328 | @node Pragma Unevaluated_Use_Of_Old,Pragma Unimplemented_Unit,Pragma Unchecked_Union,Implementation Defined Pragmas | |
04d6c745 | 8329 | @anchor{gnat_rm/implementation_defined_pragmas pragma-unevaluated-use-of-old}@anchor{108} |
64d5610f ML |
8330 | @section Pragma Unevaluated_Use_Of_Old |
8331 | ||
8332 | ||
8333 | @geindex Attribute Old | |
8334 | ||
8335 | @geindex Attribute Loop_Entry | |
8336 | ||
8337 | @geindex Unevaluated_Use_Of_Old | |
8338 | ||
8339 | Syntax: | |
8340 | ||
8341 | @example | |
8342 | pragma Unevaluated_Use_Of_Old (Error | Warn | Allow); | |
8343 | @end example | |
8344 | ||
8345 | This pragma controls the processing of attributes Old and Loop_Entry. | |
8346 | If either of these attributes is used in a potentially unevaluated | |
8347 | expression (e.g. the then or else parts of an if expression), then | |
8348 | normally this usage is considered illegal if the prefix of the attribute | |
8349 | is other than an entity name. The language requires this | |
8350 | behavior for Old, and GNAT copies the same rule for Loop_Entry. | |
8351 | ||
8352 | The reason for this rule is that otherwise, we can have a situation | |
8353 | where we save the Old value, and this results in an exception, even | |
8354 | though we might not evaluate the attribute. Consider this example: | |
8355 | ||
8356 | @example | |
8357 | package UnevalOld is | |
8358 | K : Character; | |
8359 | procedure U (A : String; C : Boolean) -- ERROR | |
8360 | with Post => (if C then A(1)'Old = K else True); | |
8361 | end; | |
8362 | @end example | |
8363 | ||
8364 | If procedure U is called with a string with a lower bound of 2, and | |
8365 | C false, then an exception would be raised trying to evaluate A(1) | |
8366 | on entry even though the value would not be actually used. | |
8367 | ||
8368 | Although the rule guarantees against this possibility, it is sometimes | |
8369 | too restrictive. For example if we know that the string has a lower | |
8370 | bound of 1, then we will never raise an exception. | |
8371 | The pragma @code{Unevaluated_Use_Of_Old} can be | |
8372 | used to modify this behavior. If the argument is @code{Error} then an | |
8373 | error is given (this is the default RM behavior). If the argument is | |
8374 | @code{Warn} then the usage is allowed as legal but with a warning | |
8375 | that an exception might be raised. If the argument is @code{Allow} | |
8376 | then the usage is allowed as legal without generating a warning. | |
8377 | ||
8378 | This pragma may appear as a configuration pragma, or in a declarative | |
8379 | part or package specification. In the latter case it applies to | |
8380 | uses up to the end of the corresponding statement sequence or | |
8381 | sequence of package declarations. | |
8382 | ||
8383 | @node Pragma Unimplemented_Unit,Pragma Universal_Aliasing,Pragma Unevaluated_Use_Of_Old,Implementation Defined Pragmas | |
04d6c745 | 8384 | @anchor{gnat_rm/implementation_defined_pragmas pragma-unimplemented-unit}@anchor{109} |
64d5610f ML |
8385 | @section Pragma Unimplemented_Unit |
8386 | ||
8387 | ||
8388 | Syntax: | |
8389 | ||
8390 | @example | |
8391 | pragma Unimplemented_Unit; | |
8392 | @end example | |
8393 | ||
8394 | If this pragma occurs in a unit that is processed by the compiler, GNAT | |
8395 | aborts with the message @code{xxx not implemented}, where | |
8396 | @code{xxx} is the name of the current compilation unit. This pragma is | |
8397 | intended to allow the compiler to handle unimplemented library units in | |
8398 | a clean manner. | |
8399 | ||
8400 | The abort only happens if code is being generated. Thus you can use | |
8401 | specs of unimplemented packages in syntax or semantic checking mode. | |
8402 | ||
8403 | @node Pragma Universal_Aliasing,Pragma Unmodified,Pragma Unimplemented_Unit,Implementation Defined Pragmas | |
04d6c745 | 8404 | @anchor{gnat_rm/implementation_defined_pragmas id50}@anchor{10a}@anchor{gnat_rm/implementation_defined_pragmas pragma-universal-aliasing}@anchor{10b} |
64d5610f ML |
8405 | @section Pragma Universal_Aliasing |
8406 | ||
8407 | ||
8408 | Syntax: | |
8409 | ||
8410 | @example | |
8411 | pragma Universal_Aliasing [([Entity =>] type_LOCAL_NAME)]; | |
8412 | @end example | |
8413 | ||
8414 | @code{type_LOCAL_NAME} must refer to a type declaration in the current | |
8415 | declarative part. The effect is to inhibit strict type-based aliasing | |
8416 | optimization for the given type. In other words, the effect is as though | |
8417 | access types designating this type were subject to pragma No_Strict_Aliasing. | |
8418 | For a detailed description of the strict aliasing optimization, and the | |
8419 | situations in which it must be suppressed, see the section on | |
8420 | @code{Optimization and Strict Aliasing} in the @cite{GNAT User’s Guide}. | |
8421 | ||
8422 | @node Pragma Unmodified,Pragma Unreferenced,Pragma Universal_Aliasing,Implementation Defined Pragmas | |
04d6c745 | 8423 | @anchor{gnat_rm/implementation_defined_pragmas id51}@anchor{10c}@anchor{gnat_rm/implementation_defined_pragmas pragma-unmodified}@anchor{10d} |
64d5610f ML |
8424 | @section Pragma Unmodified |
8425 | ||
8426 | ||
8427 | @geindex Warnings | |
8428 | @geindex unmodified | |
8429 | ||
8430 | Syntax: | |
8431 | ||
8432 | @example | |
8433 | pragma Unmodified (LOCAL_NAME @{, LOCAL_NAME@}); | |
8434 | @end example | |
8435 | ||
8436 | This pragma signals that the assignable entities (variables, | |
8437 | @code{out} parameters, @code{in out} parameters) whose names are listed are | |
8438 | deliberately not assigned in the current source unit. This | |
8439 | suppresses warnings about the | |
8440 | entities being referenced but not assigned, and in addition a warning will be | |
8441 | generated if one of these entities is in fact assigned in the | |
8442 | same unit as the pragma (or in the corresponding body, or one | |
8443 | of its subunits). | |
8444 | ||
8445 | This is particularly useful for clearly signaling that a particular | |
8446 | parameter is not modified, even though the spec suggests that it might | |
8447 | be. | |
8448 | ||
8449 | For the variable case, warnings are never given for unreferenced variables | |
8450 | whose name contains one of the substrings | |
8451 | @code{DISCARD, DUMMY, IGNORE, JUNK, UNUSE, TMP, TEMP} in any casing. Such names | |
8452 | are typically to be used in cases where such warnings are expected. | |
8453 | Thus it is never necessary to use @code{pragma Unmodified} for such | |
8454 | variables, though it is harmless to do so. | |
8455 | ||
8456 | @node Pragma Unreferenced,Pragma Unreferenced_Objects,Pragma Unmodified,Implementation Defined Pragmas | |
04d6c745 | 8457 | @anchor{gnat_rm/implementation_defined_pragmas id52}@anchor{10e}@anchor{gnat_rm/implementation_defined_pragmas pragma-unreferenced}@anchor{10f} |
64d5610f ML |
8458 | @section Pragma Unreferenced |
8459 | ||
8460 | ||
8461 | @geindex Warnings | |
8462 | @geindex unreferenced | |
8463 | ||
8464 | Syntax: | |
8465 | ||
8466 | @example | |
8467 | pragma Unreferenced (LOCAL_NAME @{, LOCAL_NAME@}); | |
8468 | pragma Unreferenced (library_unit_NAME @{, library_unit_NAME@}); | |
8469 | @end example | |
8470 | ||
8471 | This pragma signals that the entities whose names are listed are | |
8472 | deliberately not referenced in the current source unit after the | |
8473 | occurrence of the pragma. This | |
8474 | suppresses warnings about the | |
8475 | entities being unreferenced, and in addition a warning will be | |
8476 | generated if one of these entities is in fact subsequently referenced in the | |
8477 | same unit as the pragma (or in the corresponding body, or one | |
8478 | of its subunits). | |
8479 | ||
8480 | This is particularly useful for clearly signaling that a particular | |
8481 | parameter is not referenced in some particular subprogram implementation | |
8482 | and that this is deliberate. It can also be useful in the case of | |
8483 | objects declared only for their initialization or finalization side | |
8484 | effects. | |
8485 | ||
8486 | If @code{LOCAL_NAME} identifies more than one matching homonym in the | |
8487 | current scope, then the entity most recently declared is the one to which | |
8488 | the pragma applies. Note that in the case of accept formals, the pragma | |
8489 | Unreferenced may appear immediately after the keyword @code{do} which | |
8490 | allows the indication of whether or not accept formals are referenced | |
8491 | or not to be given individually for each accept statement. | |
8492 | ||
8493 | The left hand side of an assignment does not count as a reference for the | |
8494 | purpose of this pragma. Thus it is fine to assign to an entity for which | |
8495 | pragma Unreferenced is given. However, use of an entity as an actual for | |
8496 | an out parameter does count as a reference unless warnings for unread output | |
8497 | parameters are enabled via @code{-gnatw.o}. | |
8498 | ||
8499 | Note that if a warning is desired for all calls to a given subprogram, | |
8500 | regardless of whether they occur in the same unit as the subprogram | |
8501 | declaration, then this pragma should not be used (calls from another | |
8502 | unit would not be flagged); pragma Obsolescent can be used instead | |
b71d4b62 | 8503 | for this purpose, see @ref{af,,Pragma Obsolescent}. |
64d5610f ML |
8504 | |
8505 | The second form of pragma @code{Unreferenced} is used within a context | |
8506 | clause. In this case the arguments must be unit names of units previously | |
8507 | mentioned in @code{with} clauses (similar to the usage of pragma | |
8508 | @code{Elaborate_All}). The effect is to suppress warnings about unreferenced | |
8509 | units and unreferenced entities within these units. | |
8510 | ||
8511 | For the variable case, warnings are never given for unreferenced variables | |
8512 | whose name contains one of the substrings | |
8513 | @code{DISCARD, DUMMY, IGNORE, JUNK, UNUSED} in any casing. Such names | |
8514 | are typically to be used in cases where such warnings are expected. | |
8515 | Thus it is never necessary to use @code{pragma Unreferenced} for such | |
8516 | variables, though it is harmless to do so. | |
8517 | ||
8518 | @node Pragma Unreferenced_Objects,Pragma Unreserve_All_Interrupts,Pragma Unreferenced,Implementation Defined Pragmas | |
04d6c745 | 8519 | @anchor{gnat_rm/implementation_defined_pragmas id53}@anchor{110}@anchor{gnat_rm/implementation_defined_pragmas pragma-unreferenced-objects}@anchor{111} |
64d5610f ML |
8520 | @section Pragma Unreferenced_Objects |
8521 | ||
8522 | ||
8523 | @geindex Warnings | |
8524 | @geindex unreferenced | |
8525 | ||
8526 | Syntax: | |
8527 | ||
8528 | @example | |
8529 | pragma Unreferenced_Objects (local_subtype_NAME @{, local_subtype_NAME@}); | |
8530 | @end example | |
8531 | ||
8532 | This pragma signals that for the types or subtypes whose names are | |
8533 | listed, objects which are declared with one of these types or subtypes may | |
8534 | not be referenced, and if no references appear, no warnings are given. | |
8535 | ||
8536 | This is particularly useful for objects which are declared solely for their | |
8537 | initialization and finalization effect. Such variables are sometimes referred | |
8538 | to as RAII variables (Resource Acquisition Is Initialization). Using this | |
8539 | pragma on the relevant type (most typically a limited controlled type), the | |
8540 | compiler will automatically suppress unwanted warnings about these variables | |
8541 | not being referenced. | |
8542 | ||
8543 | @node Pragma Unreserve_All_Interrupts,Pragma Unsuppress,Pragma Unreferenced_Objects,Implementation Defined Pragmas | |
04d6c745 | 8544 | @anchor{gnat_rm/implementation_defined_pragmas pragma-unreserve-all-interrupts}@anchor{112} |
64d5610f ML |
8545 | @section Pragma Unreserve_All_Interrupts |
8546 | ||
8547 | ||
8548 | Syntax: | |
8549 | ||
8550 | @example | |
8551 | pragma Unreserve_All_Interrupts; | |
8552 | @end example | |
8553 | ||
8554 | Normally certain interrupts are reserved to the implementation. Any attempt | |
8555 | to attach an interrupt causes Program_Error to be raised, as described in | |
8556 | RM C.3.2(22). A typical example is the @code{SIGINT} interrupt used in | |
8557 | many systems for a @code{Ctrl-C} interrupt. Normally this interrupt is | |
8558 | reserved to the implementation, so that @code{Ctrl-C} can be used to | |
8559 | interrupt execution. | |
8560 | ||
8561 | If the pragma @code{Unreserve_All_Interrupts} appears anywhere in any unit in | |
8562 | a program, then all such interrupts are unreserved. This allows the | |
8563 | program to handle these interrupts, but disables their standard | |
8564 | functions. For example, if this pragma is used, then pressing | |
8565 | @code{Ctrl-C} will not automatically interrupt execution. However, | |
8566 | a program can then handle the @code{SIGINT} interrupt as it chooses. | |
8567 | ||
8568 | For a full list of the interrupts handled in a specific implementation, | |
8569 | see the source code for the spec of @code{Ada.Interrupts.Names} in | |
8570 | file @code{a-intnam.ads}. This is a target dependent file that contains the | |
8571 | list of interrupts recognized for a given target. The documentation in | |
8572 | this file also specifies what interrupts are affected by the use of | |
8573 | the @code{Unreserve_All_Interrupts} pragma. | |
8574 | ||
8575 | For a more general facility for controlling what interrupts can be | |
8576 | handled, see pragma @code{Interrupt_State}, which subsumes the functionality | |
8577 | of the @code{Unreserve_All_Interrupts} pragma. | |
8578 | ||
6f089469 | 8579 | @node Pragma Unsuppress,Pragma Unused,Pragma Unreserve_All_Interrupts,Implementation Defined Pragmas |
04d6c745 | 8580 | @anchor{gnat_rm/implementation_defined_pragmas pragma-unsuppress}@anchor{113} |
64d5610f ML |
8581 | @section Pragma Unsuppress |
8582 | ||
8583 | ||
8584 | Syntax: | |
8585 | ||
8586 | @example | |
8587 | pragma Unsuppress (IDENTIFIER [, [On =>] NAME]); | |
8588 | @end example | |
8589 | ||
8590 | This pragma undoes the effect of a previous pragma @code{Suppress}. If | |
8591 | there is no corresponding pragma @code{Suppress} in effect, it has no | |
8592 | effect. The range of the effect is the same as for pragma | |
8593 | @code{Suppress}. The meaning of the arguments is identical to that used | |
8594 | in pragma @code{Suppress}. | |
8595 | ||
8596 | One important application is to ensure that checks are on in cases where | |
8597 | code depends on the checks for its correct functioning, so that the code | |
8598 | will compile correctly even if the compiler switches are set to suppress | |
8599 | checks. For example, in a program that depends on external names of tagged | |
8600 | types and wants to ensure that the duplicated tag check occurs even if all | |
8601 | run-time checks are suppressed by a compiler switch, the following | |
8602 | configuration pragma will ensure this test is not suppressed: | |
8603 | ||
8604 | @example | |
8605 | pragma Unsuppress (Duplicated_Tag_Check); | |
8606 | @end example | |
8607 | ||
8608 | This pragma is standard in Ada 2005. It is available in all earlier versions | |
8609 | of Ada as an implementation-defined pragma. | |
8610 | ||
8611 | Note that in addition to the checks defined in the Ada RM, GNAT recognizes a | |
8612 | number of implementation-defined check names. See the description of pragma | |
8613 | @code{Suppress} for full details. | |
8614 | ||
6f089469 | 8615 | @node Pragma Unused,Pragma Use_VADS_Size,Pragma Unsuppress,Implementation Defined Pragmas |
04d6c745 | 8616 | @anchor{gnat_rm/implementation_defined_pragmas id54}@anchor{114}@anchor{gnat_rm/implementation_defined_pragmas pragma-unused}@anchor{115} |
64d5610f ML |
8617 | @section Pragma Unused |
8618 | ||
8619 | ||
8620 | @geindex Warnings | |
8621 | @geindex unused | |
8622 | ||
8623 | Syntax: | |
8624 | ||
8625 | @example | |
8626 | pragma Unused (LOCAL_NAME @{, LOCAL_NAME@}); | |
8627 | @end example | |
8628 | ||
8629 | This pragma signals that the assignable entities (variables, | |
8630 | @code{out} parameters, and @code{in out} parameters) whose names are listed | |
8631 | deliberately do not get assigned or referenced in the current source unit | |
8632 | after the occurrence of the pragma in the current source unit. This | |
8633 | suppresses warnings about the entities that are unreferenced and/or not | |
8634 | assigned, and, in addition, a warning will be generated if one of these | |
8635 | entities gets assigned or subsequently referenced in the same unit as the | |
8636 | pragma (in the corresponding body or one of its subunits). | |
8637 | ||
8638 | This is particularly useful for clearly signaling that a particular | |
8639 | parameter is not modified or referenced, even though the spec suggests | |
8640 | that it might be. | |
8641 | ||
8642 | For the variable case, warnings are never given for unreferenced | |
8643 | variables whose name contains one of the substrings | |
8644 | @code{DISCARD, DUMMY, IGNORE, JUNK, UNUSED} in any casing. Such names | |
8645 | are typically to be used in cases where such warnings are expected. | |
8646 | Thus it is never necessary to use @code{pragma Unused} for such | |
8647 | variables, though it is harmless to do so. | |
8648 | ||
6f089469 | 8649 | @node Pragma Use_VADS_Size,Pragma Validity_Checks,Pragma Unused,Implementation Defined Pragmas |
04d6c745 | 8650 | @anchor{gnat_rm/implementation_defined_pragmas pragma-use-vads-size}@anchor{116} |
6f089469 RD |
8651 | @section Pragma Use_VADS_Size |
8652 | ||
8653 | ||
8654 | @geindex Size | |
8655 | @geindex VADS compatibility | |
8656 | ||
8657 | @geindex Rational profile | |
8658 | ||
8659 | Syntax: | |
8660 | ||
8661 | @example | |
8662 | pragma Use_VADS_Size; | |
8663 | @end example | |
8664 | ||
8665 | This is a configuration pragma. In a unit to which it applies, any use | |
8666 | of the ‘Size attribute is automatically interpreted as a use of the | |
8667 | ‘VADS_Size attribute. Note that this may result in incorrect semantic | |
8668 | processing of valid Ada 95 or Ada 2005 programs. This is intended to aid in | |
8669 | the handling of existing code which depends on the interpretation of Size | |
8670 | as implemented in the VADS compiler. See description of the VADS_Size | |
8671 | attribute for further details. | |
8672 | ||
8673 | @node Pragma Validity_Checks,Pragma Volatile,Pragma Use_VADS_Size,Implementation Defined Pragmas | |
04d6c745 | 8674 | @anchor{gnat_rm/implementation_defined_pragmas pragma-validity-checks}@anchor{117} |
64d5610f ML |
8675 | @section Pragma Validity_Checks |
8676 | ||
8677 | ||
8678 | Syntax: | |
8679 | ||
8680 | @example | |
8681 | pragma Validity_Checks (string_LITERAL | ALL_CHECKS | On | Off); | |
8682 | @end example | |
8683 | ||
8684 | This pragma is used in conjunction with compiler switches to control the | |
8685 | built-in validity checking provided by GNAT. The compiler switches, if set | |
8686 | provide an initial setting for the switches, and this pragma may be used | |
8687 | to modify these settings, or the settings may be provided entirely by | |
8688 | the use of the pragma. This pragma can be used anywhere that a pragma | |
8689 | is legal, including use as a configuration pragma (including use in | |
8690 | the @code{gnat.adc} file). | |
8691 | ||
8692 | The form with a string literal specifies which validity options are to be | |
8693 | activated. The validity checks are first set to include only the default | |
8694 | reference manual settings, and then a string of letters in the string | |
8695 | specifies the exact set of options required. The form of this string | |
8696 | is exactly as described for the `-gnatVx' compiler switch (see the | |
8697 | GNAT User’s Guide for details). For example the following two | |
8698 | methods can be used to enable validity checking for mode @code{in} and | |
8699 | @code{in out} subprogram parameters: | |
8700 | ||
8701 | ||
8702 | @itemize * | |
8703 | ||
8704 | @item | |
8705 | @example | |
8706 | pragma Validity_Checks ("im"); | |
8707 | @end example | |
8708 | ||
8709 | @item | |
8710 | @example | |
8711 | $ gcc -c -gnatVim ... | |
8712 | @end example | |
8713 | @end itemize | |
8714 | ||
8715 | The form ALL_CHECKS activates all standard checks (its use is equivalent | |
8716 | to the use of the @code{gnatVa} switch). | |
8717 | ||
8718 | The forms with @code{Off} and @code{On} can be used to temporarily disable | |
8719 | validity checks as shown in the following example: | |
8720 | ||
8721 | @example | |
8722 | pragma Validity_Checks ("c"); -- validity checks for copies | |
8723 | pragma Validity_Checks (Off); -- turn off validity checks | |
8724 | A := B; -- B will not be validity checked | |
8725 | pragma Validity_Checks (On); -- turn validity checks back on | |
8726 | A := C; -- C will be validity checked | |
8727 | @end example | |
8728 | ||
8729 | @node Pragma Volatile,Pragma Volatile_Full_Access,Pragma Validity_Checks,Implementation Defined Pragmas | |
04d6c745 | 8730 | @anchor{gnat_rm/implementation_defined_pragmas id55}@anchor{118}@anchor{gnat_rm/implementation_defined_pragmas pragma-volatile}@anchor{119} |
64d5610f ML |
8731 | @section Pragma Volatile |
8732 | ||
8733 | ||
8734 | Syntax: | |
8735 | ||
8736 | @example | |
8737 | pragma Volatile (LOCAL_NAME); | |
8738 | @end example | |
8739 | ||
8740 | This pragma is defined by the Ada Reference Manual, and the GNAT | |
8741 | implementation is fully conformant with this definition. The reason it | |
8742 | is mentioned in this section is that a pragma of the same name was supplied | |
8743 | in some Ada 83 compilers, including DEC Ada 83. The Ada 95 / Ada 2005 | |
8744 | implementation of pragma Volatile is upwards compatible with the | |
8745 | implementation in DEC Ada 83. | |
8746 | ||
8747 | @node Pragma Volatile_Full_Access,Pragma Volatile_Function,Pragma Volatile,Implementation Defined Pragmas | |
04d6c745 | 8748 | @anchor{gnat_rm/implementation_defined_pragmas id56}@anchor{11a}@anchor{gnat_rm/implementation_defined_pragmas pragma-volatile-full-access}@anchor{11b} |
64d5610f ML |
8749 | @section Pragma Volatile_Full_Access |
8750 | ||
8751 | ||
8752 | Syntax: | |
8753 | ||
8754 | @example | |
8755 | pragma Volatile_Full_Access (LOCAL_NAME); | |
8756 | @end example | |
8757 | ||
8758 | This is similar in effect to pragma Volatile, except that any reference to the | |
8759 | object is guaranteed to be done only with instructions that read or write all | |
8760 | the bits of the object. Furthermore, if the object is of a composite type, | |
8761 | then any reference to a subcomponent of the object is guaranteed to read | |
8762 | and/or write all the bits of the object. | |
8763 | ||
8764 | The intention is that this be suitable for use with memory-mapped I/O devices | |
8765 | on some machines. Note that there are two important respects in which this is | |
8766 | different from @code{pragma Atomic}. First a reference to a @code{Volatile_Full_Access} | |
8767 | object is not a sequential action in the RM 9.10 sense and, therefore, does | |
8768 | not create a synchronization point. Second, in the case of @code{pragma Atomic}, | |
8769 | there is no guarantee that all the bits will be accessed if the reference | |
8770 | is not to the whole object; the compiler is allowed (and generally will) | |
8771 | access only part of the object in this case. | |
8772 | ||
8773 | @node Pragma Volatile_Function,Pragma Warning_As_Error,Pragma Volatile_Full_Access,Implementation Defined Pragmas | |
04d6c745 | 8774 | @anchor{gnat_rm/implementation_defined_pragmas id57}@anchor{11c}@anchor{gnat_rm/implementation_defined_pragmas pragma-volatile-function}@anchor{11d} |
64d5610f ML |
8775 | @section Pragma Volatile_Function |
8776 | ||
8777 | ||
8778 | Syntax: | |
8779 | ||
8780 | @example | |
8781 | pragma Volatile_Function [ (static_boolean_EXPRESSION) ]; | |
8782 | @end example | |
8783 | ||
8784 | For the semantics of this pragma, see the entry for aspect @code{Volatile_Function} | |
8785 | in the SPARK 2014 Reference Manual, section 7.1.2. | |
8786 | ||
8787 | @node Pragma Warning_As_Error,Pragma Warnings,Pragma Volatile_Function,Implementation Defined Pragmas | |
04d6c745 | 8788 | @anchor{gnat_rm/implementation_defined_pragmas pragma-warning-as-error}@anchor{11e} |
64d5610f ML |
8789 | @section Pragma Warning_As_Error |
8790 | ||
8791 | ||
8792 | Syntax: | |
8793 | ||
8794 | @example | |
8795 | pragma Warning_As_Error (static_string_EXPRESSION); | |
8796 | @end example | |
8797 | ||
8798 | This configuration pragma allows the programmer to specify a set | |
8799 | of warnings that will be treated as errors. Any warning that | |
8800 | matches the pattern given by the pragma argument will be treated | |
8801 | as an error. This gives more precise control than -gnatwe, | |
8802 | which treats warnings as errors. | |
8803 | ||
8804 | This pragma can apply to regular warnings (messages enabled by -gnatw) | |
8805 | and to style warnings (messages that start with “(style)”, | |
8806 | enabled by -gnaty). | |
8807 | ||
8808 | The pattern may contain asterisks, which match zero or more characters | |
8809 | in the message. For example, you can use @code{pragma Warning_As_Error | |
8810 | ("bits of*unused")} to treat the warning message @code{warning: 960 bits of | |
8811 | "a" unused} as an error. All characters other than asterisk are treated | |
8812 | as literal characters in the match. The match is case insensitive; for | |
8813 | example XYZ matches xyz. | |
8814 | ||
8815 | Note that the pattern matches if it occurs anywhere within the warning | |
8816 | message string (it is not necessary to put an asterisk at the start and | |
8817 | the end of the message, since this is implied). | |
8818 | ||
8819 | Another possibility for the static_string_EXPRESSION which works whether | |
8820 | or not error tags are enabled (`-gnatw.d') is to use a single | |
8821 | `-gnatw' tag string, enclosed in brackets, | |
8822 | as shown in the example below, to treat one category of warnings as errors. | |
8823 | Note that if you want to treat multiple categories of warnings as errors, | |
8824 | you can use multiple pragma Warning_As_Error. | |
8825 | ||
8826 | The above use of patterns to match the message applies only to warning | |
8827 | messages generated by the front end. This pragma can also be applied to | |
04d6c745 | 8828 | warnings provided by the back end and mentioned in @ref{11f,,Pragma Warnings}. |
64d5610f ML |
8829 | By using a single full `-Wxxx' switch in the pragma, such warnings |
8830 | can also be treated as errors. | |
8831 | ||
8832 | The pragma can appear either in a global configuration pragma file | |
8833 | (e.g. @code{gnat.adc}), or at the start of a file. Given a global | |
8834 | configuration pragma file containing: | |
8835 | ||
8836 | @example | |
8837 | pragma Warning_As_Error ("[-gnatwj]"); | |
8838 | @end example | |
8839 | ||
8840 | which will treat all obsolescent feature warnings as errors, the | |
8841 | following program compiles as shown (compile options here are | |
8842 | `-gnatwa.d -gnatl -gnatj55'). | |
8843 | ||
8844 | @example | |
8845 | 1. pragma Warning_As_Error ("*never assigned*"); | |
8846 | 2. function Warnerr return String is | |
8847 | 3. X : Integer; | |
8848 | | | |
8849 | >>> error: variable "X" is never read and | |
8850 | never assigned [-gnatwv] [warning-as-error] | |
8851 | ||
8852 | 4. Y : Integer; | |
8853 | | | |
8854 | >>> warning: variable "Y" is assigned but | |
8855 | never read [-gnatwu] | |
8856 | ||
8857 | 5. begin | |
8858 | 6. Y := 0; | |
8859 | 7. return %ABC%; | |
8860 | | | |
8861 | >>> error: use of "%" is an obsolescent | |
8862 | feature (RM J.2(4)), use """ instead | |
8863 | [-gnatwj] [warning-as-error] | |
8864 | ||
8865 | 8. end; | |
8866 | ||
8867 | 8 lines: No errors, 3 warnings (2 treated as errors) | |
8868 | @end example | |
8869 | ||
8870 | Note that this pragma does not affect the set of warnings issued in | |
8871 | any way, it merely changes the effect of a matching warning if one | |
8872 | is produced as a result of other warnings options. As shown in this | |
8873 | example, if the pragma results in a warning being treated as an error, | |
8874 | the tag is changed from “warning:” to “error:” and the string | |
8875 | “[warning-as-error]” is appended to the end of the message. | |
8876 | ||
8877 | @node Pragma Warnings,Pragma Weak_External,Pragma Warning_As_Error,Implementation Defined Pragmas | |
04d6c745 | 8878 | @anchor{gnat_rm/implementation_defined_pragmas id58}@anchor{120}@anchor{gnat_rm/implementation_defined_pragmas pragma-warnings}@anchor{11f} |
64d5610f ML |
8879 | @section Pragma Warnings |
8880 | ||
8881 | ||
8882 | Syntax: | |
8883 | ||
8884 | @example | |
8885 | pragma Warnings ([TOOL_NAME,] DETAILS [, REASON]); | |
8886 | ||
8887 | DETAILS ::= On | Off | |
8888 | DETAILS ::= On | Off, local_NAME | |
8889 | DETAILS ::= static_string_EXPRESSION | |
8890 | DETAILS ::= On | Off, static_string_EXPRESSION | |
8891 | ||
8892 | TOOL_NAME ::= GNAT | GNATprove | |
8893 | ||
8894 | REASON ::= Reason => STRING_LITERAL @{& STRING_LITERAL@} | |
8895 | @end example | |
8896 | ||
8897 | Note: in Ada 83 mode, a string literal may be used in place of a static string | |
8898 | expression (which does not exist in Ada 83). | |
8899 | ||
8900 | Note if the second argument of @code{DETAILS} is a @code{local_NAME} then the | |
8901 | second form is always understood. If the intention is to use | |
8902 | the fourth form, then you can write @code{NAME & ""} to force the | |
8903 | interpretation as a `static_string_EXPRESSION'. | |
8904 | ||
8905 | Note: if the first argument is a valid @code{TOOL_NAME}, it will be interpreted | |
8906 | that way. The use of the @code{TOOL_NAME} argument is relevant only to users | |
8907 | of SPARK and GNATprove, see last part of this section for details. | |
8908 | ||
8909 | Normally warnings are enabled, with the output being controlled by | |
8910 | the command line switch. Warnings (@code{Off}) turns off generation of | |
8911 | warnings until a Warnings (@code{On}) is encountered or the end of the | |
8912 | current unit. If generation of warnings is turned off using this | |
8913 | pragma, then some or all of the warning messages are suppressed, | |
8914 | regardless of the setting of the command line switches. | |
8915 | ||
8916 | The @code{Reason} parameter may optionally appear as the last argument | |
8917 | in any of the forms of this pragma. It is intended purely for the | |
8918 | purposes of documenting the reason for the @code{Warnings} pragma. | |
8919 | The compiler will check that the argument is a static string but | |
8920 | otherwise ignore this argument. Other tools may provide specialized | |
8921 | processing for this string. | |
8922 | ||
8923 | The form with a single argument (or two arguments if Reason present), | |
8924 | where the first argument is @code{ON} or @code{OFF} | |
8925 | may be used as a configuration pragma. | |
8926 | ||
8927 | If the @code{LOCAL_NAME} parameter is present, warnings are suppressed for | |
8928 | the specified entity. This suppression is effective from the point where | |
8929 | it occurs till the end of the extended scope of the variable (similar to | |
8930 | the scope of @code{Suppress}). This form cannot be used as a configuration | |
8931 | pragma. | |
8932 | ||
8933 | In the case where the first argument is other than @code{ON} or | |
8934 | @code{OFF}, | |
8935 | the third form with a single static_string_EXPRESSION argument (and possible | |
8936 | reason) provides more precise | |
8937 | control over which warnings are active. The string is a list of letters | |
8938 | specifying which warnings are to be activated and which deactivated. The | |
8939 | code for these letters is the same as the string used in the command | |
8940 | line switch controlling warnings. For a brief summary, use the gnatmake | |
8941 | command with no arguments, which will generate usage information containing | |
8942 | the list of warnings switches supported. For | |
8943 | full details see the section on @code{Warning Message Control} in the | |
8944 | @cite{GNAT User’s Guide}. | |
8945 | This form can also be used as a configuration pragma. | |
8946 | ||
8947 | The warnings controlled by the @code{-gnatw} switch are generated by the | |
8948 | front end of the compiler. The GCC back end can provide additional warnings | |
8949 | and they are controlled by the @code{-W} switch. Such warnings can be | |
8950 | identified by the appearance of a string of the form @code{[-W@{xxx@}]} in the | |
8951 | message which designates the @code{-W`xxx'} switch that controls the message. | |
8952 | The form with a single `static_string_EXPRESSION' argument also works for these | |
8953 | warnings, but the string must be a single full @code{-W`xxx'} switch in this | |
8954 | case. The above reference lists a few examples of these additional warnings. | |
8955 | ||
8956 | The specified warnings will be in effect until the end of the program | |
8957 | or another pragma @code{Warnings} is encountered. The effect of the pragma is | |
8958 | cumulative. Initially the set of warnings is the standard default set | |
8959 | as possibly modified by compiler switches. Then each pragma Warning | |
8960 | modifies this set of warnings as specified. This form of the pragma may | |
8961 | also be used as a configuration pragma. | |
8962 | ||
8963 | The fourth form, with an @code{On|Off} parameter and a string, is used to | |
8964 | control individual messages, based on their text. The string argument | |
8965 | is a pattern that is used to match against the text of individual | |
eeba836b | 8966 | warning messages (not including the initial “warning: ” tag). |
64d5610f ML |
8967 | |
8968 | The pattern may contain asterisks, which match zero or more characters in | |
8969 | the message. For example, you can use | |
8970 | @code{pragma Warnings (Off, "bits of*unused")} to suppress the warning | |
8971 | message @code{warning: 960 bits of "a" unused}. No other regular | |
8972 | expression notations are permitted. All characters other than asterisk in | |
8973 | these three specific cases are treated as literal characters in the match. | |
8974 | The match is case insensitive, for example XYZ matches xyz. | |
8975 | ||
8976 | Note that the pattern matches if it occurs anywhere within the warning | |
8977 | message string (it is not necessary to put an asterisk at the start and | |
8978 | the end of the message, since this is implied). | |
8979 | ||
8980 | The above use of patterns to match the message applies only to warning | |
8981 | messages generated by the front end. This form of the pragma with a string | |
8982 | argument can also be used to control warnings provided by the back end and | |
8983 | mentioned above. By using a single full @code{-W`xxx'} switch in the pragma, | |
8984 | such warnings can be turned on and off. | |
8985 | ||
8986 | There are two ways to use the pragma in this form. The OFF form can be used | |
8987 | as a configuration pragma. The effect is to suppress all warnings (if any) | |
8988 | that match the pattern string throughout the compilation (or match the | |
8989 | -W switch in the back end case). | |
8990 | ||
8991 | The second usage is to suppress a warning locally, and in this case, two | |
8992 | pragmas must appear in sequence: | |
8993 | ||
8994 | @example | |
8995 | pragma Warnings (Off, Pattern); | |
8996 | ... code where given warning is to be suppressed | |
8997 | pragma Warnings (On, Pattern); | |
8998 | @end example | |
8999 | ||
9000 | In this usage, the pattern string must match in the Off and On | |
9001 | pragmas, and (if `-gnatw.w' is given) at least one matching | |
9002 | warning must be suppressed. | |
9003 | ||
9004 | Note: if the ON form is not found, then the effect of the OFF form extends | |
9005 | until the end of the file (pragma Warnings is purely textual, so its effect | |
9006 | does not stop at the end of the enclosing scope). | |
9007 | ||
9008 | Note: to write a string that will match any warning, use the string | |
9009 | @code{"***"}. It will not work to use a single asterisk or two | |
9010 | asterisks since this looks like an operator name. This form with three | |
9011 | asterisks is similar in effect to specifying @code{pragma Warnings (Off)} except (if @code{-gnatw.w} is given) that a matching | |
9012 | @code{pragma Warnings (On, "***")} will be required. This can be | |
9013 | helpful in avoiding forgetting to turn warnings back on. | |
9014 | ||
9015 | Note: the debug flag @code{-gnatd.i} can be | |
9016 | used to cause the compiler to entirely ignore all WARNINGS pragmas. This can | |
9017 | be useful in checking whether obsolete pragmas in existing programs are hiding | |
9018 | real problems. | |
9019 | ||
9020 | Note: pragma Warnings does not affect the processing of style messages. See | |
9021 | separate entry for pragma Style_Checks for control of style messages. | |
9022 | ||
9023 | Users of the formal verification tool GNATprove for the SPARK subset of Ada may | |
9024 | use the version of the pragma with a @code{TOOL_NAME} parameter. | |
9025 | ||
9026 | If present, @code{TOOL_NAME} is the name of a tool, currently either @code{GNAT} for the | |
9027 | compiler or @code{GNATprove} for the formal verification tool. A given tool only | |
9028 | takes into account pragma Warnings that do not specify a tool name, or that | |
9029 | specify the matching tool name. This makes it possible to disable warnings | |
9030 | selectively for each tool, and as a consequence to detect useless pragma | |
9031 | Warnings with switch @code{-gnatw.w}. | |
9032 | ||
9033 | @node Pragma Weak_External,Pragma Wide_Character_Encoding,Pragma Warnings,Implementation Defined Pragmas | |
04d6c745 | 9034 | @anchor{gnat_rm/implementation_defined_pragmas pragma-weak-external}@anchor{121} |
64d5610f ML |
9035 | @section Pragma Weak_External |
9036 | ||
9037 | ||
9038 | Syntax: | |
9039 | ||
9040 | @example | |
9041 | pragma Weak_External ([Entity =>] LOCAL_NAME); | |
9042 | @end example | |
9043 | ||
9044 | @code{LOCAL_NAME} must refer to an object that is declared at the library | |
9045 | level. This pragma specifies that the given entity should be marked as a | |
9046 | weak symbol for the linker. It is equivalent to @code{__attribute__((weak))} | |
9047 | in GNU C and causes @code{LOCAL_NAME} to be emitted as a weak symbol instead | |
9048 | of a regular symbol, that is to say a symbol that does not have to be | |
9049 | resolved by the linker if used in conjunction with a pragma Import. | |
9050 | ||
9051 | When a weak symbol is not resolved by the linker, its address is set to | |
9052 | zero. This is useful in writing interfaces to external modules that may | |
9053 | or may not be linked in the final executable, for example depending on | |
9054 | configuration settings. | |
9055 | ||
9056 | If a program references at run time an entity to which this pragma has been | |
9057 | applied, and the corresponding symbol was not resolved at link time, then | |
9058 | the execution of the program is erroneous. It is not erroneous to take the | |
9059 | Address of such an entity, for example to guard potential references, | |
9060 | as shown in the example below. | |
9061 | ||
9062 | Some file formats do not support weak symbols so not all target machines | |
9063 | support this pragma. | |
9064 | ||
9065 | @example | |
9066 | -- Example of the use of pragma Weak_External | |
9067 | ||
9068 | package External_Module is | |
9069 | key : Integer; | |
9070 | pragma Import (C, key); | |
9071 | pragma Weak_External (key); | |
9072 | function Present return boolean; | |
9073 | end External_Module; | |
9074 | ||
9075 | with System; use System; | |
9076 | package body External_Module is | |
9077 | function Present return boolean is | |
9078 | begin | |
9079 | return key'Address /= System.Null_Address; | |
9080 | end Present; | |
9081 | end External_Module; | |
9082 | @end example | |
9083 | ||
9084 | @node Pragma Wide_Character_Encoding,,Pragma Weak_External,Implementation Defined Pragmas | |
04d6c745 | 9085 | @anchor{gnat_rm/implementation_defined_pragmas pragma-wide-character-encoding}@anchor{122} |
64d5610f ML |
9086 | @section Pragma Wide_Character_Encoding |
9087 | ||
9088 | ||
9089 | Syntax: | |
9090 | ||
9091 | @example | |
9092 | pragma Wide_Character_Encoding (IDENTIFIER | CHARACTER_LITERAL); | |
9093 | @end example | |
9094 | ||
9095 | This pragma specifies the wide character encoding to be used in program | |
9096 | source text appearing subsequently. It is a configuration pragma, but may | |
9097 | also be used at any point that a pragma is allowed, and it is permissible | |
9098 | to have more than one such pragma in a file, allowing multiple encodings | |
9099 | to appear within the same file. | |
9100 | ||
9101 | However, note that the pragma cannot immediately precede the relevant | |
9102 | wide character, because then the previous encoding will still be in | |
9103 | effect, causing “illegal character” errors. | |
9104 | ||
9105 | The argument can be an identifier or a character literal. In the identifier | |
9106 | case, it is one of @code{HEX}, @code{UPPER}, @code{SHIFT_JIS}, | |
9107 | @code{EUC}, @code{UTF8}, or @code{BRACKETS}. In the character literal | |
9108 | case it is correspondingly one of the characters @code{h}, @code{u}, | |
9109 | @code{s}, @code{e}, @code{8}, or @code{b}. | |
9110 | ||
9111 | Note that when the pragma is used within a file, it affects only the | |
9112 | encoding within that file, and does not affect withed units, specs, | |
9113 | or subunits. | |
9114 | ||
9115 | @node Implementation Defined Aspects,Implementation Defined Attributes,Implementation Defined Pragmas,Top | |
04d6c745 | 9116 | @anchor{gnat_rm/implementation_defined_aspects doc}@anchor{123}@anchor{gnat_rm/implementation_defined_aspects id1}@anchor{124}@anchor{gnat_rm/implementation_defined_aspects implementation-defined-aspects}@anchor{125} |
64d5610f ML |
9117 | @chapter Implementation Defined Aspects |
9118 | ||
9119 | ||
9120 | Ada defines (throughout the Ada 2012 reference manual, summarized | |
9121 | in Annex K) a set of aspects that can be specified for certain entities. | |
9122 | These language defined aspects are implemented in GNAT in Ada 2012 mode | |
9123 | and work as described in the Ada 2012 Reference Manual. | |
9124 | ||
9125 | In addition, Ada 2012 allows implementations to define additional aspects | |
9126 | whose meaning is defined by the implementation. GNAT provides | |
9127 | a number of these implementation-defined aspects which can be used | |
9128 | to extend and enhance the functionality of the compiler. This section of | |
9129 | the GNAT reference manual describes these additional aspects. | |
9130 | ||
9131 | Note that any program using these aspects may not be portable to | |
9132 | other compilers (although GNAT implements this set of aspects on all | |
9133 | platforms). Therefore if portability to other compilers is an important | |
9134 | consideration, you should minimize the use of these aspects. | |
9135 | ||
9136 | Note that for many of these aspects, the effect is essentially similar | |
9137 | to the use of a pragma or attribute specification with the same name | |
9138 | applied to the entity. For example, if we write: | |
9139 | ||
9140 | @example | |
9141 | type R is range 1 .. 100 | |
9142 | with Value_Size => 10; | |
9143 | @end example | |
9144 | ||
9145 | then the effect is the same as: | |
9146 | ||
9147 | @example | |
9148 | type R is range 1 .. 100; | |
9149 | for R'Value_Size use 10; | |
9150 | @end example | |
9151 | ||
9152 | and if we write: | |
9153 | ||
9154 | @example | |
9155 | type R is new Integer | |
9156 | with Shared => True; | |
9157 | @end example | |
9158 | ||
9159 | then the effect is the same as: | |
9160 | ||
9161 | @example | |
9162 | type R is new Integer; | |
9163 | pragma Shared (R); | |
9164 | @end example | |
9165 | ||
9166 | In the documentation below, such cases are simply marked | |
9167 | as being boolean aspects equivalent to the corresponding pragma | |
9168 | or attribute definition clause. | |
9169 | ||
9170 | @menu | |
9171 | * Aspect Abstract_State:: | |
9172 | * Aspect Annotate:: | |
9173 | * Aspect Async_Readers:: | |
9174 | * Aspect Async_Writers:: | |
9175 | * Aspect Constant_After_Elaboration:: | |
9176 | * Aspect Contract_Cases:: | |
9177 | * Aspect Depends:: | |
9178 | * Aspect Default_Initial_Condition:: | |
9179 | * Aspect Dimension:: | |
9180 | * Aspect Dimension_System:: | |
9181 | * Aspect Disable_Controlled:: | |
9182 | * Aspect Effective_Reads:: | |
9183 | * Aspect Effective_Writes:: | |
9184 | * Aspect Extensions_Visible:: | |
9185 | * Aspect Favor_Top_Level:: | |
9186 | * Aspect Ghost:: | |
067d80d8 | 9187 | * Aspect Ghost_Predicate:: |
64d5610f ML |
9188 | * Aspect Global:: |
9189 | * Aspect Initial_Condition:: | |
9190 | * Aspect Initializes:: | |
9191 | * Aspect Inline_Always:: | |
9192 | * Aspect Invariant:: | |
9193 | * Aspect Invariant’Class:: | |
9194 | * Aspect Iterable:: | |
9195 | * Aspect Linker_Section:: | |
9196 | * Aspect Lock_Free:: | |
9197 | * Aspect Max_Queue_Length:: | |
9198 | * Aspect No_Caching:: | |
9199 | * Aspect No_Elaboration_Code_All:: | |
9200 | * Aspect No_Inline:: | |
9201 | * Aspect No_Tagged_Streams:: | |
9202 | * Aspect No_Task_Parts:: | |
9203 | * Aspect Object_Size:: | |
9204 | * Aspect Obsolescent:: | |
9205 | * Aspect Part_Of:: | |
9206 | * Aspect Persistent_BSS:: | |
9207 | * Aspect Predicate:: | |
9208 | * Aspect Pure_Function:: | |
9209 | * Aspect Refined_Depends:: | |
9210 | * Aspect Refined_Global:: | |
9211 | * Aspect Refined_Post:: | |
9212 | * Aspect Refined_State:: | |
9213 | * Aspect Relaxed_Initialization:: | |
9214 | * Aspect Remote_Access_Type:: | |
9215 | * Aspect Secondary_Stack_Size:: | |
9216 | * Aspect Scalar_Storage_Order:: | |
9217 | * Aspect Shared:: | |
04d6c745 | 9218 | * Aspect Side_Effects:: |
64d5610f ML |
9219 | * Aspect Simple_Storage_Pool:: |
9220 | * Aspect Simple_Storage_Pool_Type:: | |
9221 | * Aspect SPARK_Mode:: | |
9222 | * Aspect Suppress_Debug_Info:: | |
9223 | * Aspect Suppress_Initialization:: | |
9224 | * Aspect Test_Case:: | |
9225 | * Aspect Thread_Local_Storage:: | |
9226 | * Aspect Universal_Aliasing:: | |
9227 | * Aspect Unmodified:: | |
9228 | * Aspect Unreferenced:: | |
9229 | * Aspect Unreferenced_Objects:: | |
9230 | * Aspect Value_Size:: | |
9231 | * Aspect Volatile_Full_Access:: | |
9232 | * Aspect Volatile_Function:: | |
9233 | * Aspect Warnings:: | |
9234 | ||
9235 | @end menu | |
9236 | ||
9237 | @node Aspect Abstract_State,Aspect Annotate,,Implementation Defined Aspects | |
04d6c745 | 9238 | @anchor{gnat_rm/implementation_defined_aspects aspect-abstract-state}@anchor{126} |
64d5610f ML |
9239 | @section Aspect Abstract_State |
9240 | ||
9241 | ||
9242 | @geindex Abstract_State | |
9243 | ||
9244 | This aspect is equivalent to @ref{1e,,pragma Abstract_State}. | |
9245 | ||
9246 | @node Aspect Annotate,Aspect Async_Readers,Aspect Abstract_State,Implementation Defined Aspects | |
04d6c745 | 9247 | @anchor{gnat_rm/implementation_defined_aspects aspect-annotate}@anchor{127} |
64d5610f ML |
9248 | @section Aspect Annotate |
9249 | ||
9250 | ||
9251 | @geindex Annotate | |
9252 | ||
9253 | There are three forms of this aspect (where ID is an identifier, | |
9254 | and ARG is a general expression), | |
9255 | corresponding to @ref{29,,pragma Annotate}. | |
9256 | ||
9257 | ||
9258 | @table @asis | |
9259 | ||
9260 | @item `Annotate => ID' | |
9261 | ||
9262 | Equivalent to @code{pragma Annotate (ID, Entity => Name);} | |
9263 | ||
9264 | @item `Annotate => (ID)' | |
9265 | ||
9266 | Equivalent to @code{pragma Annotate (ID, Entity => Name);} | |
9267 | ||
9268 | @item `Annotate => (ID ,ID @{, ARG@})' | |
9269 | ||
9270 | Equivalent to @code{pragma Annotate (ID, ID @{, ARG@}, Entity => Name);} | |
9271 | @end table | |
9272 | ||
9273 | @node Aspect Async_Readers,Aspect Async_Writers,Aspect Annotate,Implementation Defined Aspects | |
04d6c745 | 9274 | @anchor{gnat_rm/implementation_defined_aspects aspect-async-readers}@anchor{128} |
64d5610f ML |
9275 | @section Aspect Async_Readers |
9276 | ||
9277 | ||
9278 | @geindex Async_Readers | |
9279 | ||
9280 | This boolean aspect is equivalent to @ref{30,,pragma Async_Readers}. | |
9281 | ||
9282 | @node Aspect Async_Writers,Aspect Constant_After_Elaboration,Aspect Async_Readers,Implementation Defined Aspects | |
04d6c745 | 9283 | @anchor{gnat_rm/implementation_defined_aspects aspect-async-writers}@anchor{129} |
64d5610f ML |
9284 | @section Aspect Async_Writers |
9285 | ||
9286 | ||
9287 | @geindex Async_Writers | |
9288 | ||
9289 | This boolean aspect is equivalent to @ref{32,,pragma Async_Writers}. | |
9290 | ||
9291 | @node Aspect Constant_After_Elaboration,Aspect Contract_Cases,Aspect Async_Writers,Implementation Defined Aspects | |
04d6c745 | 9292 | @anchor{gnat_rm/implementation_defined_aspects aspect-constant-after-elaboration}@anchor{12a} |
64d5610f ML |
9293 | @section Aspect Constant_After_Elaboration |
9294 | ||
9295 | ||
9296 | @geindex Constant_After_Elaboration | |
9297 | ||
9298 | This aspect is equivalent to @ref{42,,pragma Constant_After_Elaboration}. | |
9299 | ||
9300 | @node Aspect Contract_Cases,Aspect Depends,Aspect Constant_After_Elaboration,Implementation Defined Aspects | |
04d6c745 | 9301 | @anchor{gnat_rm/implementation_defined_aspects aspect-contract-cases}@anchor{12b} |
64d5610f ML |
9302 | @section Aspect Contract_Cases |
9303 | ||
9304 | ||
9305 | @geindex Contract_Cases | |
9306 | ||
9307 | This aspect is equivalent to @ref{44,,pragma Contract_Cases}, the sequence | |
9308 | of clauses being enclosed in parentheses so that syntactically it is an | |
9309 | aggregate. | |
9310 | ||
9311 | @node Aspect Depends,Aspect Default_Initial_Condition,Aspect Contract_Cases,Implementation Defined Aspects | |
04d6c745 | 9312 | @anchor{gnat_rm/implementation_defined_aspects aspect-depends}@anchor{12c} |
64d5610f ML |
9313 | @section Aspect Depends |
9314 | ||
9315 | ||
9316 | @geindex Depends | |
9317 | ||
9318 | This aspect is equivalent to @ref{54,,pragma Depends}. | |
9319 | ||
9320 | @node Aspect Default_Initial_Condition,Aspect Dimension,Aspect Depends,Implementation Defined Aspects | |
04d6c745 | 9321 | @anchor{gnat_rm/implementation_defined_aspects aspect-default-initial-condition}@anchor{12d} |
64d5610f ML |
9322 | @section Aspect Default_Initial_Condition |
9323 | ||
9324 | ||
9325 | @geindex Default_Initial_Condition | |
9326 | ||
6f089469 | 9327 | This aspect is equivalent to @ref{50,,pragma Default_Initial_Condition}. |
64d5610f ML |
9328 | |
9329 | @node Aspect Dimension,Aspect Dimension_System,Aspect Default_Initial_Condition,Implementation Defined Aspects | |
04d6c745 | 9330 | @anchor{gnat_rm/implementation_defined_aspects aspect-dimension}@anchor{12e} |
64d5610f ML |
9331 | @section Aspect Dimension |
9332 | ||
9333 | ||
9334 | @geindex Dimension | |
9335 | ||
9336 | The @code{Dimension} aspect is used to specify the dimensions of a given | |
9337 | subtype of a dimensioned numeric type. The aspect also specifies a symbol | |
9338 | used when doing formatted output of dimensioned quantities. The syntax is: | |
9339 | ||
9340 | @example | |
9341 | with Dimension => | |
9342 | ([Symbol =>] SYMBOL, DIMENSION_VALUE @{, DIMENSION_Value@}) | |
9343 | ||
9344 | SYMBOL ::= STRING_LITERAL | CHARACTER_LITERAL | |
9345 | ||
9346 | DIMENSION_VALUE ::= | |
9347 | RATIONAL | |
9348 | | others => RATIONAL | |
9349 | | DISCRETE_CHOICE_LIST => RATIONAL | |
9350 | ||
9351 | RATIONAL ::= [-] NUMERIC_LITERAL [/ NUMERIC_LITERAL] | |
9352 | @end example | |
9353 | ||
9354 | This aspect can only be applied to a subtype whose parent type has | |
9355 | a @code{Dimension_System} aspect. The aspect must specify values for | |
9356 | all dimensions of the system. The rational values are the powers of the | |
9357 | corresponding dimensions that are used by the compiler to verify that | |
9358 | physical (numeric) computations are dimensionally consistent. For example, | |
9359 | the computation of a force must result in dimensions (L => 1, M => 1, T => -2). | |
9360 | For further examples of the usage | |
9361 | of this aspect, see package @code{System.Dim.Mks}. | |
9362 | Note that when the dimensioned type is an integer type, then any | |
9363 | dimension value must be an integer literal. | |
9364 | ||
9365 | @node Aspect Dimension_System,Aspect Disable_Controlled,Aspect Dimension,Implementation Defined Aspects | |
04d6c745 | 9366 | @anchor{gnat_rm/implementation_defined_aspects aspect-dimension-system}@anchor{12f} |
64d5610f ML |
9367 | @section Aspect Dimension_System |
9368 | ||
9369 | ||
9370 | @geindex Dimension_System | |
9371 | ||
9372 | The @code{Dimension_System} aspect is used to define a system of | |
9373 | dimensions that will be used in subsequent subtype declarations with | |
9374 | @code{Dimension} aspects that reference this system. The syntax is: | |
9375 | ||
9376 | @example | |
9377 | with Dimension_System => (DIMENSION @{, DIMENSION@}); | |
9378 | ||
9379 | DIMENSION ::= ([Unit_Name =>] IDENTIFIER, | |
9380 | [Unit_Symbol =>] SYMBOL, | |
9381 | [Dim_Symbol =>] SYMBOL) | |
9382 | ||
9383 | SYMBOL ::= CHARACTER_LITERAL | STRING_LITERAL | |
9384 | @end example | |
9385 | ||
9386 | This aspect is applied to a type, which must be a numeric derived type | |
9387 | (typically a floating-point type), that | |
9388 | will represent values within the dimension system. Each @code{DIMENSION} | |
9389 | corresponds to one particular dimension. A maximum of 7 dimensions may | |
9390 | be specified. @code{Unit_Name} is the name of the dimension (for example | |
9391 | @code{Meter}). @code{Unit_Symbol} is the shorthand used for quantities | |
9392 | of this dimension (for example @code{m} for @code{Meter}). | |
9393 | @code{Dim_Symbol} gives | |
9394 | the identification within the dimension system (typically this is a | |
9395 | single letter, e.g. @code{L} standing for length for unit name @code{Meter}). | |
9396 | The @code{Unit_Symbol} is used in formatted output of dimensioned quantities. | |
9397 | The @code{Dim_Symbol} is used in error messages when numeric operations have | |
9398 | inconsistent dimensions. | |
9399 | ||
9400 | GNAT provides the standard definition of the International MKS system in | |
9401 | the run-time package @code{System.Dim.Mks}. You can easily define | |
9402 | similar packages for cgs units or British units, and define conversion factors | |
9403 | between values in different systems. The MKS system is characterized by the | |
9404 | following aspect: | |
9405 | ||
9406 | @example | |
9407 | type Mks_Type is new Long_Long_Float with | |
9408 | Dimension_System => ( | |
9409 | (Unit_Name => Meter, Unit_Symbol => 'm', Dim_Symbol => 'L'), | |
9410 | (Unit_Name => Kilogram, Unit_Symbol => "kg", Dim_Symbol => 'M'), | |
9411 | (Unit_Name => Second, Unit_Symbol => 's', Dim_Symbol => 'T'), | |
9412 | (Unit_Name => Ampere, Unit_Symbol => 'A', Dim_Symbol => 'I'), | |
9413 | (Unit_Name => Kelvin, Unit_Symbol => 'K', Dim_Symbol => '@@'), | |
9414 | (Unit_Name => Mole, Unit_Symbol => "mol", Dim_Symbol => 'N'), | |
9415 | (Unit_Name => Candela, Unit_Symbol => "cd", Dim_Symbol => 'J')); | |
9416 | @end example | |
9417 | ||
9418 | Note that in the above type definition, we use the @code{at} symbol (@code{@@}) to | |
9419 | represent a theta character (avoiding the use of extended Latin-1 | |
9420 | characters in this context). | |
9421 | ||
9422 | See section ‘Performing Dimensionality Analysis in GNAT’ in the GNAT Users | |
9423 | Guide for detailed examples of use of the dimension system. | |
9424 | ||
9425 | @node Aspect Disable_Controlled,Aspect Effective_Reads,Aspect Dimension_System,Implementation Defined Aspects | |
04d6c745 | 9426 | @anchor{gnat_rm/implementation_defined_aspects aspect-disable-controlled}@anchor{130} |
64d5610f ML |
9427 | @section Aspect Disable_Controlled |
9428 | ||
9429 | ||
9430 | @geindex Disable_Controlled | |
9431 | ||
9432 | The aspect @code{Disable_Controlled} is defined for controlled record types. If | |
9433 | active, this aspect causes suppression of all related calls to @code{Initialize}, | |
9434 | @code{Adjust}, and @code{Finalize}. The intended use is for conditional compilation, | |
9435 | where for example you might want a record to be controlled or not depending on | |
9436 | whether some run-time check is enabled or suppressed. | |
9437 | ||
9438 | @node Aspect Effective_Reads,Aspect Effective_Writes,Aspect Disable_Controlled,Implementation Defined Aspects | |
04d6c745 | 9439 | @anchor{gnat_rm/implementation_defined_aspects aspect-effective-reads}@anchor{131} |
64d5610f ML |
9440 | @section Aspect Effective_Reads |
9441 | ||
9442 | ||
9443 | @geindex Effective_Reads | |
9444 | ||
9445 | This aspect is equivalent to @ref{59,,pragma Effective_Reads}. | |
9446 | ||
9447 | @node Aspect Effective_Writes,Aspect Extensions_Visible,Aspect Effective_Reads,Implementation Defined Aspects | |
04d6c745 | 9448 | @anchor{gnat_rm/implementation_defined_aspects aspect-effective-writes}@anchor{132} |
64d5610f ML |
9449 | @section Aspect Effective_Writes |
9450 | ||
9451 | ||
9452 | @geindex Effective_Writes | |
9453 | ||
9454 | This aspect is equivalent to @ref{5b,,pragma Effective_Writes}. | |
9455 | ||
9456 | @node Aspect Extensions_Visible,Aspect Favor_Top_Level,Aspect Effective_Writes,Implementation Defined Aspects | |
04d6c745 | 9457 | @anchor{gnat_rm/implementation_defined_aspects aspect-extensions-visible}@anchor{133} |
64d5610f ML |
9458 | @section Aspect Extensions_Visible |
9459 | ||
9460 | ||
9461 | @geindex Extensions_Visible | |
9462 | ||
b71d4b62 | 9463 | This aspect is equivalent to @ref{69,,pragma Extensions_Visible}. |
64d5610f ML |
9464 | |
9465 | @node Aspect Favor_Top_Level,Aspect Ghost,Aspect Extensions_Visible,Implementation Defined Aspects | |
04d6c745 | 9466 | @anchor{gnat_rm/implementation_defined_aspects aspect-favor-top-level}@anchor{134} |
64d5610f ML |
9467 | @section Aspect Favor_Top_Level |
9468 | ||
9469 | ||
9470 | @geindex Favor_Top_Level | |
9471 | ||
b71d4b62 | 9472 | This boolean aspect is equivalent to @ref{6e,,pragma Favor_Top_Level}. |
64d5610f | 9473 | |
067d80d8 | 9474 | @node Aspect Ghost,Aspect Ghost_Predicate,Aspect Favor_Top_Level,Implementation Defined Aspects |
04d6c745 | 9475 | @anchor{gnat_rm/implementation_defined_aspects aspect-ghost}@anchor{135} |
64d5610f ML |
9476 | @section Aspect Ghost |
9477 | ||
9478 | ||
9479 | @geindex Ghost | |
9480 | ||
b71d4b62 | 9481 | This aspect is equivalent to @ref{72,,pragma Ghost}. |
64d5610f | 9482 | |
067d80d8 | 9483 | @node Aspect Ghost_Predicate,Aspect Global,Aspect Ghost,Implementation Defined Aspects |
04d6c745 | 9484 | @anchor{gnat_rm/implementation_defined_aspects aspect-ghost-predicate}@anchor{136} |
067d80d8 YM |
9485 | @section Aspect Ghost_Predicate |
9486 | ||
9487 | ||
9488 | @geindex Ghost_Predicate | |
9489 | ||
9490 | This aspect introduces a subtype predicate that can reference ghost | |
9491 | entities. The subtype cannot appear as a subtype_mark in a membership test. | |
9492 | ||
9493 | For the detailed semantics of this aspect, see the entry for subtype predicates | |
9494 | in the SPARK Reference Manual, section 3.2.4. | |
9495 | ||
9496 | @node Aspect Global,Aspect Initial_Condition,Aspect Ghost_Predicate,Implementation Defined Aspects | |
04d6c745 | 9497 | @anchor{gnat_rm/implementation_defined_aspects aspect-global}@anchor{137} |
64d5610f ML |
9498 | @section Aspect Global |
9499 | ||
9500 | ||
9501 | @geindex Global | |
9502 | ||
b71d4b62 | 9503 | This aspect is equivalent to @ref{74,,pragma Global}. |
64d5610f ML |
9504 | |
9505 | @node Aspect Initial_Condition,Aspect Initializes,Aspect Global,Implementation Defined Aspects | |
04d6c745 | 9506 | @anchor{gnat_rm/implementation_defined_aspects aspect-initial-condition}@anchor{138} |
64d5610f ML |
9507 | @section Aspect Initial_Condition |
9508 | ||
9509 | ||
9510 | @geindex Initial_Condition | |
9511 | ||
b71d4b62 | 9512 | This aspect is equivalent to @ref{81,,pragma Initial_Condition}. |
64d5610f ML |
9513 | |
9514 | @node Aspect Initializes,Aspect Inline_Always,Aspect Initial_Condition,Implementation Defined Aspects | |
04d6c745 | 9515 | @anchor{gnat_rm/implementation_defined_aspects aspect-initializes}@anchor{139} |
64d5610f ML |
9516 | @section Aspect Initializes |
9517 | ||
9518 | ||
9519 | @geindex Initializes | |
9520 | ||
b71d4b62 | 9521 | This aspect is equivalent to @ref{84,,pragma Initializes}. |
64d5610f ML |
9522 | |
9523 | @node Aspect Inline_Always,Aspect Invariant,Aspect Initializes,Implementation Defined Aspects | |
04d6c745 | 9524 | @anchor{gnat_rm/implementation_defined_aspects aspect-inline-always}@anchor{13a} |
64d5610f ML |
9525 | @section Aspect Inline_Always |
9526 | ||
9527 | ||
9528 | @geindex Inline_Always | |
9529 | ||
b71d4b62 | 9530 | This boolean aspect is equivalent to @ref{86,,pragma Inline_Always}. |
64d5610f ML |
9531 | |
9532 | @node Aspect Invariant,Aspect Invariant’Class,Aspect Inline_Always,Implementation Defined Aspects | |
04d6c745 | 9533 | @anchor{gnat_rm/implementation_defined_aspects aspect-invariant}@anchor{13b} |
64d5610f ML |
9534 | @section Aspect Invariant |
9535 | ||
9536 | ||
9537 | @geindex Invariant | |
9538 | ||
b71d4b62 | 9539 | This aspect is equivalent to @ref{8d,,pragma Invariant}. It is a |
64d5610f ML |
9540 | synonym for the language defined aspect @code{Type_Invariant} except |
9541 | that it is separately controllable using pragma @code{Assertion_Policy}. | |
9542 | ||
9543 | @node Aspect Invariant’Class,Aspect Iterable,Aspect Invariant,Implementation Defined Aspects | |
04d6c745 | 9544 | @anchor{gnat_rm/implementation_defined_aspects aspect-invariant-class}@anchor{13c} |
64d5610f ML |
9545 | @section Aspect Invariant’Class |
9546 | ||
9547 | ||
9548 | @geindex Invariant'Class | |
9549 | ||
04d6c745 | 9550 | This aspect is equivalent to @ref{106,,pragma Type_Invariant_Class}. It is a |
64d5610f ML |
9551 | synonym for the language defined aspect @code{Type_Invariant'Class} except |
9552 | that it is separately controllable using pragma @code{Assertion_Policy}. | |
9553 | ||
9554 | @node Aspect Iterable,Aspect Linker_Section,Aspect Invariant’Class,Implementation Defined Aspects | |
04d6c745 | 9555 | @anchor{gnat_rm/implementation_defined_aspects aspect-iterable}@anchor{13d} |
64d5610f ML |
9556 | @section Aspect Iterable |
9557 | ||
9558 | ||
9559 | @geindex Iterable | |
9560 | ||
9561 | This aspect provides a light-weight mechanism for loops and quantified | |
9562 | expressions over container types, without the overhead imposed by the tampering | |
9563 | checks of standard Ada 2012 iterators. The value of the aspect is an aggregate | |
9564 | with six named components, of which the last three are optional: @code{First}, | |
9565 | @code{Next}, @code{Has_Element}, @code{Element}, @code{Last}, and @code{Previous}. | |
9566 | When only the first three components are specified, only the | |
9567 | @code{for .. in} form of iteration over cursors is available. When @code{Element} | |
9568 | is specified, both this form and the @code{for .. of} form of iteration over | |
9569 | elements are available. If the last two components are specified, reverse | |
9570 | iterations over the container can be specified (analogous to what can be done | |
9571 | over predefined containers that support the @code{Reverse_Iterator} interface). | |
9572 | The following is a typical example of use: | |
9573 | ||
9574 | @example | |
9575 | type List is private with | |
9576 | Iterable => (First => First_Cursor, | |
9577 | Next => Advance, | |
9578 | Has_Element => Cursor_Has_Element | |
9579 | [,Element => Get_Element] | |
9580 | [,Last => Last_Cursor] | |
9581 | [,Previous => Retreat]); | |
9582 | @end example | |
9583 | ||
9584 | ||
9585 | @itemize * | |
9586 | ||
9587 | @item | |
9588 | The values of @code{First} and @code{Last} are primitive operations of the | |
9589 | container type that return a @code{Cursor}, which must be a type declared in | |
9590 | the container package or visible from it. For example: | |
9591 | @end itemize | |
9592 | ||
9593 | @example | |
9594 | function First_Cursor (Cont : Container) return Cursor; | |
9595 | function Last_Cursor (Cont : Container) return Cursor; | |
9596 | @end example | |
9597 | ||
9598 | ||
9599 | @itemize * | |
9600 | ||
9601 | @item | |
9602 | The values of @code{Next} and @code{Previous} are primitive operations of the container type that take | |
9603 | both a container and a cursor and yield a cursor. For example: | |
9604 | @end itemize | |
9605 | ||
9606 | @example | |
9607 | function Advance (Cont : Container; Position : Cursor) return Cursor; | |
9608 | function Retreat (Cont : Container; Position : Cursor) return Cursor; | |
9609 | @end example | |
9610 | ||
9611 | ||
9612 | @itemize * | |
9613 | ||
9614 | @item | |
9615 | The value of @code{Has_Element} is a primitive operation of the container type | |
9616 | that takes both a container and a cursor and yields a boolean. For example: | |
9617 | @end itemize | |
9618 | ||
9619 | @example | |
9620 | function Cursor_Has_Element (Cont : Container; Position : Cursor) return Boolean; | |
9621 | @end example | |
9622 | ||
9623 | ||
9624 | @itemize * | |
9625 | ||
9626 | @item | |
9627 | The value of @code{Element} is a primitive operation of the container type that | |
9628 | takes both a container and a cursor and yields an @code{Element_Type}, which must | |
9629 | be a type declared in the container package or visible from it. For example: | |
9630 | @end itemize | |
9631 | ||
9632 | @example | |
9633 | function Get_Element (Cont : Container; Position : Cursor) return Element_Type; | |
9634 | @end example | |
9635 | ||
9636 | This aspect is used in the GNAT-defined formal container packages. | |
9637 | ||
9638 | @node Aspect Linker_Section,Aspect Lock_Free,Aspect Iterable,Implementation Defined Aspects | |
04d6c745 | 9639 | @anchor{gnat_rm/implementation_defined_aspects aspect-linker-section}@anchor{13e} |
64d5610f ML |
9640 | @section Aspect Linker_Section |
9641 | ||
9642 | ||
9643 | @geindex Linker_Section | |
9644 | ||
b71d4b62 | 9645 | This aspect is equivalent to @ref{95,,pragma Linker_Section}. |
64d5610f ML |
9646 | |
9647 | @node Aspect Lock_Free,Aspect Max_Queue_Length,Aspect Linker_Section,Implementation Defined Aspects | |
04d6c745 | 9648 | @anchor{gnat_rm/implementation_defined_aspects aspect-lock-free}@anchor{13f} |
64d5610f ML |
9649 | @section Aspect Lock_Free |
9650 | ||
9651 | ||
9652 | @geindex Lock_Free | |
9653 | ||
b71d4b62 | 9654 | This boolean aspect is equivalent to @ref{97,,pragma Lock_Free}. |
64d5610f ML |
9655 | |
9656 | @node Aspect Max_Queue_Length,Aspect No_Caching,Aspect Lock_Free,Implementation Defined Aspects | |
04d6c745 | 9657 | @anchor{gnat_rm/implementation_defined_aspects aspect-max-queue-length}@anchor{140} |
64d5610f ML |
9658 | @section Aspect Max_Queue_Length |
9659 | ||
9660 | ||
9661 | @geindex Max_Queue_Length | |
9662 | ||
b71d4b62 | 9663 | This aspect is equivalent to @ref{9f,,pragma Max_Queue_Length}. |
64d5610f ML |
9664 | |
9665 | @node Aspect No_Caching,Aspect No_Elaboration_Code_All,Aspect Max_Queue_Length,Implementation Defined Aspects | |
04d6c745 | 9666 | @anchor{gnat_rm/implementation_defined_aspects aspect-no-caching}@anchor{141} |
64d5610f ML |
9667 | @section Aspect No_Caching |
9668 | ||
9669 | ||
9670 | @geindex No_Caching | |
9671 | ||
b71d4b62 | 9672 | This boolean aspect is equivalent to @ref{a2,,pragma No_Caching}. |
64d5610f ML |
9673 | |
9674 | @node Aspect No_Elaboration_Code_All,Aspect No_Inline,Aspect No_Caching,Implementation Defined Aspects | |
04d6c745 | 9675 | @anchor{gnat_rm/implementation_defined_aspects aspect-no-elaboration-code-all}@anchor{142} |
64d5610f ML |
9676 | @section Aspect No_Elaboration_Code_All |
9677 | ||
9678 | ||
9679 | @geindex No_Elaboration_Code_All | |
9680 | ||
b71d4b62 | 9681 | This aspect is equivalent to @ref{a5,,pragma No_Elaboration_Code_All} |
64d5610f ML |
9682 | for a program unit. |
9683 | ||
9684 | @node Aspect No_Inline,Aspect No_Tagged_Streams,Aspect No_Elaboration_Code_All,Implementation Defined Aspects | |
04d6c745 | 9685 | @anchor{gnat_rm/implementation_defined_aspects aspect-no-inline}@anchor{143} |
64d5610f ML |
9686 | @section Aspect No_Inline |
9687 | ||
9688 | ||
9689 | @geindex No_Inline | |
9690 | ||
b71d4b62 | 9691 | This boolean aspect is equivalent to @ref{a8,,pragma No_Inline}. |
64d5610f ML |
9692 | |
9693 | @node Aspect No_Tagged_Streams,Aspect No_Task_Parts,Aspect No_Inline,Implementation Defined Aspects | |
04d6c745 | 9694 | @anchor{gnat_rm/implementation_defined_aspects aspect-no-tagged-streams}@anchor{144} |
64d5610f ML |
9695 | @section Aspect No_Tagged_Streams |
9696 | ||
9697 | ||
9698 | @geindex No_Tagged_Streams | |
9699 | ||
b71d4b62 | 9700 | This aspect is equivalent to @ref{ac,,pragma No_Tagged_Streams} with an |
64d5610f ML |
9701 | argument specifying a root tagged type (thus this aspect can only be |
9702 | applied to such a type). | |
9703 | ||
9704 | @node Aspect No_Task_Parts,Aspect Object_Size,Aspect No_Tagged_Streams,Implementation Defined Aspects | |
04d6c745 | 9705 | @anchor{gnat_rm/implementation_defined_aspects aspect-no-task-parts}@anchor{145} |
64d5610f ML |
9706 | @section Aspect No_Task_Parts |
9707 | ||
9708 | ||
9709 | @geindex No_Task_Parts | |
9710 | ||
9711 | Applies to a type. If True, requires that the type and any descendants | |
9712 | do not have any task parts. The rules for this aspect are the same as | |
9713 | for the language-defined No_Controlled_Parts aspect (see RM-H.4.1), | |
9714 | replacing “controlled” with “task”. | |
9715 | ||
9716 | If No_Task_Parts is True for a type T, then the compiler can optimize | |
9717 | away certain tasking-related code that would otherwise be needed | |
9718 | for T’Class, because descendants of T might contain tasks. | |
9719 | ||
9720 | @node Aspect Object_Size,Aspect Obsolescent,Aspect No_Task_Parts,Implementation Defined Aspects | |
04d6c745 | 9721 | @anchor{gnat_rm/implementation_defined_aspects aspect-object-size}@anchor{146} |
64d5610f ML |
9722 | @section Aspect Object_Size |
9723 | ||
9724 | ||
9725 | @geindex Object_Size | |
9726 | ||
04d6c745 | 9727 | This aspect is equivalent to @ref{147,,attribute Object_Size}. |
64d5610f ML |
9728 | |
9729 | @node Aspect Obsolescent,Aspect Part_Of,Aspect Object_Size,Implementation Defined Aspects | |
04d6c745 | 9730 | @anchor{gnat_rm/implementation_defined_aspects aspect-obsolescent}@anchor{148} |
64d5610f ML |
9731 | @section Aspect Obsolescent |
9732 | ||
9733 | ||
9734 | @geindex Obsolescent | |
9735 | ||
b71d4b62 | 9736 | This aspect is equivalent to @ref{af,,pragma Obsolescent}. Note that the |
64d5610f ML |
9737 | evaluation of this aspect happens at the point of occurrence, it is not |
9738 | delayed until the freeze point. | |
9739 | ||
9740 | @node Aspect Part_Of,Aspect Persistent_BSS,Aspect Obsolescent,Implementation Defined Aspects | |
04d6c745 | 9741 | @anchor{gnat_rm/implementation_defined_aspects aspect-part-of}@anchor{149} |
64d5610f ML |
9742 | @section Aspect Part_Of |
9743 | ||
9744 | ||
9745 | @geindex Part_Of | |
9746 | ||
b71d4b62 | 9747 | This aspect is equivalent to @ref{b5,,pragma Part_Of}. |
64d5610f ML |
9748 | |
9749 | @node Aspect Persistent_BSS,Aspect Predicate,Aspect Part_Of,Implementation Defined Aspects | |
04d6c745 | 9750 | @anchor{gnat_rm/implementation_defined_aspects aspect-persistent-bss}@anchor{14a} |
64d5610f ML |
9751 | @section Aspect Persistent_BSS |
9752 | ||
9753 | ||
9754 | @geindex Persistent_BSS | |
9755 | ||
b71d4b62 | 9756 | This boolean aspect is equivalent to @ref{b9,,pragma Persistent_BSS}. |
64d5610f ML |
9757 | |
9758 | @node Aspect Predicate,Aspect Pure_Function,Aspect Persistent_BSS,Implementation Defined Aspects | |
04d6c745 | 9759 | @anchor{gnat_rm/implementation_defined_aspects aspect-predicate}@anchor{14b} |
64d5610f ML |
9760 | @section Aspect Predicate |
9761 | ||
9762 | ||
9763 | @geindex Predicate | |
9764 | ||
b71d4b62 | 9765 | This aspect is equivalent to @ref{c0,,pragma Predicate}. It is thus |
64d5610f ML |
9766 | similar to the language defined aspects @code{Dynamic_Predicate} |
9767 | and @code{Static_Predicate} except that whether the resulting | |
9768 | predicate is static or dynamic is controlled by the form of the | |
9769 | expression. It is also separately controllable using pragma | |
9770 | @code{Assertion_Policy}. | |
9771 | ||
9772 | @node Aspect Pure_Function,Aspect Refined_Depends,Aspect Predicate,Implementation Defined Aspects | |
04d6c745 | 9773 | @anchor{gnat_rm/implementation_defined_aspects aspect-pure-function}@anchor{14c} |
64d5610f ML |
9774 | @section Aspect Pure_Function |
9775 | ||
9776 | ||
9777 | @geindex Pure_Function | |
9778 | ||
b71d4b62 | 9779 | This boolean aspect is equivalent to @ref{cc,,pragma Pure_Function}. |
64d5610f ML |
9780 | |
9781 | @node Aspect Refined_Depends,Aspect Refined_Global,Aspect Pure_Function,Implementation Defined Aspects | |
04d6c745 | 9782 | @anchor{gnat_rm/implementation_defined_aspects aspect-refined-depends}@anchor{14d} |
64d5610f ML |
9783 | @section Aspect Refined_Depends |
9784 | ||
9785 | ||
9786 | @geindex Refined_Depends | |
9787 | ||
b71d4b62 | 9788 | This aspect is equivalent to @ref{d0,,pragma Refined_Depends}. |
64d5610f ML |
9789 | |
9790 | @node Aspect Refined_Global,Aspect Refined_Post,Aspect Refined_Depends,Implementation Defined Aspects | |
04d6c745 | 9791 | @anchor{gnat_rm/implementation_defined_aspects aspect-refined-global}@anchor{14e} |
64d5610f ML |
9792 | @section Aspect Refined_Global |
9793 | ||
9794 | ||
9795 | @geindex Refined_Global | |
9796 | ||
b71d4b62 | 9797 | This aspect is equivalent to @ref{d2,,pragma Refined_Global}. |
64d5610f ML |
9798 | |
9799 | @node Aspect Refined_Post,Aspect Refined_State,Aspect Refined_Global,Implementation Defined Aspects | |
04d6c745 | 9800 | @anchor{gnat_rm/implementation_defined_aspects aspect-refined-post}@anchor{14f} |
64d5610f ML |
9801 | @section Aspect Refined_Post |
9802 | ||
9803 | ||
9804 | @geindex Refined_Post | |
9805 | ||
b71d4b62 | 9806 | This aspect is equivalent to @ref{d4,,pragma Refined_Post}. |
64d5610f ML |
9807 | |
9808 | @node Aspect Refined_State,Aspect Relaxed_Initialization,Aspect Refined_Post,Implementation Defined Aspects | |
04d6c745 | 9809 | @anchor{gnat_rm/implementation_defined_aspects aspect-refined-state}@anchor{150} |
64d5610f ML |
9810 | @section Aspect Refined_State |
9811 | ||
9812 | ||
9813 | @geindex Refined_State | |
9814 | ||
b71d4b62 | 9815 | This aspect is equivalent to @ref{d6,,pragma Refined_State}. |
64d5610f ML |
9816 | |
9817 | @node Aspect Relaxed_Initialization,Aspect Remote_Access_Type,Aspect Refined_State,Implementation Defined Aspects | |
04d6c745 | 9818 | @anchor{gnat_rm/implementation_defined_aspects aspect-relaxed-initialization}@anchor{151} |
64d5610f ML |
9819 | @section Aspect Relaxed_Initialization |
9820 | ||
9821 | ||
9822 | @geindex Refined_Initialization | |
9823 | ||
9824 | For the syntax and semantics of this aspect, see the SPARK 2014 Reference | |
9825 | Manual, section 6.10. | |
9826 | ||
9827 | @node Aspect Remote_Access_Type,Aspect Secondary_Stack_Size,Aspect Relaxed_Initialization,Implementation Defined Aspects | |
04d6c745 | 9828 | @anchor{gnat_rm/implementation_defined_aspects aspect-remote-access-type}@anchor{152} |
64d5610f ML |
9829 | @section Aspect Remote_Access_Type |
9830 | ||
9831 | ||
9832 | @geindex Remote_Access_Type | |
9833 | ||
b71d4b62 | 9834 | This aspect is equivalent to @ref{d9,,pragma Remote_Access_Type}. |
64d5610f ML |
9835 | |
9836 | @node Aspect Secondary_Stack_Size,Aspect Scalar_Storage_Order,Aspect Remote_Access_Type,Implementation Defined Aspects | |
04d6c745 | 9837 | @anchor{gnat_rm/implementation_defined_aspects aspect-secondary-stack-size}@anchor{153} |
64d5610f ML |
9838 | @section Aspect Secondary_Stack_Size |
9839 | ||
9840 | ||
9841 | @geindex Secondary_Stack_Size | |
9842 | ||
b71d4b62 | 9843 | This aspect is equivalent to @ref{df,,pragma Secondary_Stack_Size}. |
64d5610f ML |
9844 | |
9845 | @node Aspect Scalar_Storage_Order,Aspect Shared,Aspect Secondary_Stack_Size,Implementation Defined Aspects | |
04d6c745 | 9846 | @anchor{gnat_rm/implementation_defined_aspects aspect-scalar-storage-order}@anchor{154} |
64d5610f ML |
9847 | @section Aspect Scalar_Storage_Order |
9848 | ||
9849 | ||
9850 | @geindex Scalar_Storage_Order | |
9851 | ||
04d6c745 | 9852 | This aspect is equivalent to a @ref{155,,attribute Scalar_Storage_Order}. |
64d5610f | 9853 | |
04d6c745 YM |
9854 | @node Aspect Shared,Aspect Side_Effects,Aspect Scalar_Storage_Order,Implementation Defined Aspects |
9855 | @anchor{gnat_rm/implementation_defined_aspects aspect-shared}@anchor{156} | |
64d5610f ML |
9856 | @section Aspect Shared |
9857 | ||
9858 | ||
9859 | @geindex Shared | |
9860 | ||
b71d4b62 | 9861 | This boolean aspect is equivalent to @ref{e2,,pragma Shared} |
64d5610f ML |
9862 | and is thus a synonym for aspect @code{Atomic}. |
9863 | ||
04d6c745 YM |
9864 | @node Aspect Side_Effects,Aspect Simple_Storage_Pool,Aspect Shared,Implementation Defined Aspects |
9865 | @anchor{gnat_rm/implementation_defined_aspects aspect-side-effects}@anchor{157} | |
9866 | @section Aspect Side_Effects | |
9867 | ||
9868 | ||
9869 | @geindex Side_Effects | |
9870 | ||
9871 | This aspect is equivalent to @ref{e6,,pragma Side_Effects}. | |
9872 | ||
9873 | @node Aspect Simple_Storage_Pool,Aspect Simple_Storage_Pool_Type,Aspect Side_Effects,Implementation Defined Aspects | |
9874 | @anchor{gnat_rm/implementation_defined_aspects aspect-simple-storage-pool}@anchor{158} | |
64d5610f ML |
9875 | @section Aspect Simple_Storage_Pool |
9876 | ||
9877 | ||
9878 | @geindex Simple_Storage_Pool | |
9879 | ||
04d6c745 | 9880 | This aspect is equivalent to @ref{e9,,attribute Simple_Storage_Pool}. |
64d5610f ML |
9881 | |
9882 | @node Aspect Simple_Storage_Pool_Type,Aspect SPARK_Mode,Aspect Simple_Storage_Pool,Implementation Defined Aspects | |
04d6c745 | 9883 | @anchor{gnat_rm/implementation_defined_aspects aspect-simple-storage-pool-type}@anchor{159} |
64d5610f ML |
9884 | @section Aspect Simple_Storage_Pool_Type |
9885 | ||
9886 | ||
9887 | @geindex Simple_Storage_Pool_Type | |
9888 | ||
04d6c745 | 9889 | This boolean aspect is equivalent to @ref{e8,,pragma Simple_Storage_Pool_Type}. |
64d5610f ML |
9890 | |
9891 | @node Aspect SPARK_Mode,Aspect Suppress_Debug_Info,Aspect Simple_Storage_Pool_Type,Implementation Defined Aspects | |
04d6c745 | 9892 | @anchor{gnat_rm/implementation_defined_aspects aspect-spark-mode}@anchor{15a} |
64d5610f ML |
9893 | @section Aspect SPARK_Mode |
9894 | ||
9895 | ||
9896 | @geindex SPARK_Mode | |
9897 | ||
04d6c745 | 9898 | This aspect is equivalent to @ref{f0,,pragma SPARK_Mode} and |
64d5610f ML |
9899 | may be specified for either or both of the specification and body |
9900 | of a subprogram or package. | |
9901 | ||
9902 | @node Aspect Suppress_Debug_Info,Aspect Suppress_Initialization,Aspect SPARK_Mode,Implementation Defined Aspects | |
04d6c745 | 9903 | @anchor{gnat_rm/implementation_defined_aspects aspect-suppress-debug-info}@anchor{15b} |
64d5610f ML |
9904 | @section Aspect Suppress_Debug_Info |
9905 | ||
9906 | ||
9907 | @geindex Suppress_Debug_Info | |
9908 | ||
04d6c745 | 9909 | This boolean aspect is equivalent to @ref{f8,,pragma Suppress_Debug_Info}. |
64d5610f ML |
9910 | |
9911 | @node Aspect Suppress_Initialization,Aspect Test_Case,Aspect Suppress_Debug_Info,Implementation Defined Aspects | |
04d6c745 | 9912 | @anchor{gnat_rm/implementation_defined_aspects aspect-suppress-initialization}@anchor{15c} |
64d5610f ML |
9913 | @section Aspect Suppress_Initialization |
9914 | ||
9915 | ||
9916 | @geindex Suppress_Initialization | |
9917 | ||
04d6c745 | 9918 | This boolean aspect is equivalent to @ref{fb,,pragma Suppress_Initialization}. |
64d5610f ML |
9919 | |
9920 | @node Aspect Test_Case,Aspect Thread_Local_Storage,Aspect Suppress_Initialization,Implementation Defined Aspects | |
04d6c745 | 9921 | @anchor{gnat_rm/implementation_defined_aspects aspect-test-case}@anchor{15d} |
64d5610f ML |
9922 | @section Aspect Test_Case |
9923 | ||
9924 | ||
9925 | @geindex Test_Case | |
9926 | ||
04d6c745 | 9927 | This aspect is equivalent to @ref{ff,,pragma Test_Case}. |
64d5610f ML |
9928 | |
9929 | @node Aspect Thread_Local_Storage,Aspect Universal_Aliasing,Aspect Test_Case,Implementation Defined Aspects | |
04d6c745 | 9930 | @anchor{gnat_rm/implementation_defined_aspects aspect-thread-local-storage}@anchor{15e} |
64d5610f ML |
9931 | @section Aspect Thread_Local_Storage |
9932 | ||
9933 | ||
9934 | @geindex Thread_Local_Storage | |
9935 | ||
04d6c745 | 9936 | This boolean aspect is equivalent to @ref{101,,pragma Thread_Local_Storage}. |
64d5610f ML |
9937 | |
9938 | @node Aspect Universal_Aliasing,Aspect Unmodified,Aspect Thread_Local_Storage,Implementation Defined Aspects | |
04d6c745 | 9939 | @anchor{gnat_rm/implementation_defined_aspects aspect-universal-aliasing}@anchor{15f} |
64d5610f ML |
9940 | @section Aspect Universal_Aliasing |
9941 | ||
9942 | ||
9943 | @geindex Universal_Aliasing | |
9944 | ||
04d6c745 | 9945 | This boolean aspect is equivalent to @ref{10b,,pragma Universal_Aliasing}. |
64d5610f ML |
9946 | |
9947 | @node Aspect Unmodified,Aspect Unreferenced,Aspect Universal_Aliasing,Implementation Defined Aspects | |
04d6c745 | 9948 | @anchor{gnat_rm/implementation_defined_aspects aspect-unmodified}@anchor{160} |
64d5610f ML |
9949 | @section Aspect Unmodified |
9950 | ||
9951 | ||
9952 | @geindex Unmodified | |
9953 | ||
04d6c745 | 9954 | This boolean aspect is equivalent to @ref{10d,,pragma Unmodified}. |
64d5610f ML |
9955 | |
9956 | @node Aspect Unreferenced,Aspect Unreferenced_Objects,Aspect Unmodified,Implementation Defined Aspects | |
04d6c745 | 9957 | @anchor{gnat_rm/implementation_defined_aspects aspect-unreferenced}@anchor{161} |
64d5610f ML |
9958 | @section Aspect Unreferenced |
9959 | ||
9960 | ||
9961 | @geindex Unreferenced | |
9962 | ||
04d6c745 | 9963 | This boolean aspect is equivalent to @ref{10f,,pragma Unreferenced}. |
64d5610f ML |
9964 | |
9965 | When using the @code{-gnat2022} switch, this aspect is also supported on formal | |
9966 | parameters, which is in particular the only form possible for expression | |
9967 | functions. | |
9968 | ||
9969 | @node Aspect Unreferenced_Objects,Aspect Value_Size,Aspect Unreferenced,Implementation Defined Aspects | |
04d6c745 | 9970 | @anchor{gnat_rm/implementation_defined_aspects aspect-unreferenced-objects}@anchor{162} |
64d5610f ML |
9971 | @section Aspect Unreferenced_Objects |
9972 | ||
9973 | ||
9974 | @geindex Unreferenced_Objects | |
9975 | ||
04d6c745 | 9976 | This boolean aspect is equivalent to @ref{111,,pragma Unreferenced_Objects}. |
64d5610f ML |
9977 | |
9978 | @node Aspect Value_Size,Aspect Volatile_Full_Access,Aspect Unreferenced_Objects,Implementation Defined Aspects | |
04d6c745 | 9979 | @anchor{gnat_rm/implementation_defined_aspects aspect-value-size}@anchor{163} |
64d5610f ML |
9980 | @section Aspect Value_Size |
9981 | ||
9982 | ||
9983 | @geindex Value_Size | |
9984 | ||
04d6c745 | 9985 | This aspect is equivalent to @ref{164,,attribute Value_Size}. |
64d5610f ML |
9986 | |
9987 | @node Aspect Volatile_Full_Access,Aspect Volatile_Function,Aspect Value_Size,Implementation Defined Aspects | |
04d6c745 | 9988 | @anchor{gnat_rm/implementation_defined_aspects aspect-volatile-full-access}@anchor{165} |
64d5610f ML |
9989 | @section Aspect Volatile_Full_Access |
9990 | ||
9991 | ||
9992 | @geindex Volatile_Full_Access | |
9993 | ||
04d6c745 | 9994 | This boolean aspect is equivalent to @ref{11b,,pragma Volatile_Full_Access}. |
64d5610f ML |
9995 | |
9996 | @node Aspect Volatile_Function,Aspect Warnings,Aspect Volatile_Full_Access,Implementation Defined Aspects | |
04d6c745 | 9997 | @anchor{gnat_rm/implementation_defined_aspects aspect-volatile-function}@anchor{166} |
64d5610f ML |
9998 | @section Aspect Volatile_Function |
9999 | ||
10000 | ||
10001 | @geindex Volatile_Function | |
10002 | ||
04d6c745 | 10003 | This boolean aspect is equivalent to @ref{11d,,pragma Volatile_Function}. |
64d5610f ML |
10004 | |
10005 | @node Aspect Warnings,,Aspect Volatile_Function,Implementation Defined Aspects | |
04d6c745 | 10006 | @anchor{gnat_rm/implementation_defined_aspects aspect-warnings}@anchor{167} |
64d5610f ML |
10007 | @section Aspect Warnings |
10008 | ||
10009 | ||
10010 | @geindex Warnings | |
10011 | ||
04d6c745 | 10012 | This aspect is equivalent to the two argument form of @ref{11f,,pragma Warnings}, |
64d5610f ML |
10013 | where the first argument is @code{ON} or @code{OFF} and the second argument |
10014 | is the entity. | |
10015 | ||
10016 | @node Implementation Defined Attributes,Standard and Implementation Defined Restrictions,Implementation Defined Aspects,Top | |
04d6c745 | 10017 | @anchor{gnat_rm/implementation_defined_attributes doc}@anchor{168}@anchor{gnat_rm/implementation_defined_attributes id1}@anchor{169}@anchor{gnat_rm/implementation_defined_attributes implementation-defined-attributes}@anchor{8} |
64d5610f ML |
10018 | @chapter Implementation Defined Attributes |
10019 | ||
10020 | ||
10021 | Ada defines (throughout the Ada reference manual, | |
10022 | summarized in Annex K), | |
10023 | a set of attributes that provide useful additional functionality in all | |
10024 | areas of the language. These language defined attributes are implemented | |
10025 | in GNAT and work as described in the Ada Reference Manual. | |
10026 | ||
10027 | In addition, Ada allows implementations to define additional | |
10028 | attributes whose meaning is defined by the implementation. GNAT provides | |
10029 | a number of these implementation-dependent attributes which can be used | |
10030 | to extend and enhance the functionality of the compiler. This section of | |
10031 | the GNAT reference manual describes these additional attributes. It also | |
10032 | describes additional implementation-dependent features of standard | |
10033 | language-defined attributes. | |
10034 | ||
10035 | Note that any program using these attributes may not be portable to | |
10036 | other compilers (although GNAT implements this set of attributes on all | |
10037 | platforms). Therefore if portability to other compilers is an important | |
10038 | consideration, you should minimize the use of these attributes. | |
10039 | ||
10040 | @menu | |
10041 | * Attribute Abort_Signal:: | |
10042 | * Attribute Address_Size:: | |
10043 | * Attribute Asm_Input:: | |
10044 | * Attribute Asm_Output:: | |
10045 | * Attribute Atomic_Always_Lock_Free:: | |
10046 | * Attribute Bit:: | |
10047 | * Attribute Bit_Position:: | |
10048 | * Attribute Code_Address:: | |
10049 | * Attribute Compiler_Version:: | |
10050 | * Attribute Constrained:: | |
10051 | * Attribute Default_Bit_Order:: | |
10052 | * Attribute Default_Scalar_Storage_Order:: | |
10053 | * Attribute Deref:: | |
10054 | * Attribute Descriptor_Size:: | |
10055 | * Attribute Elaborated:: | |
10056 | * Attribute Elab_Body:: | |
10057 | * Attribute Elab_Spec:: | |
10058 | * Attribute Elab_Subp_Body:: | |
10059 | * Attribute Emax:: | |
10060 | * Attribute Enabled:: | |
10061 | * Attribute Enum_Rep:: | |
10062 | * Attribute Enum_Val:: | |
10063 | * Attribute Epsilon:: | |
10064 | * Attribute Fast_Math:: | |
10065 | * Attribute Finalization_Size:: | |
10066 | * Attribute Fixed_Value:: | |
10067 | * Attribute From_Any:: | |
10068 | * Attribute Has_Access_Values:: | |
10069 | * Attribute Has_Discriminants:: | |
10070 | * Attribute Has_Tagged_Values:: | |
10071 | * Attribute Img:: | |
10072 | * Attribute Initialized:: | |
10073 | * Attribute Integer_Value:: | |
10074 | * Attribute Invalid_Value:: | |
10075 | * Attribute Iterable:: | |
10076 | * Attribute Large:: | |
10077 | * Attribute Library_Level:: | |
10078 | * Attribute Loop_Entry:: | |
10079 | * Attribute Machine_Size:: | |
10080 | * Attribute Mantissa:: | |
10081 | * Attribute Maximum_Alignment:: | |
10082 | * Attribute Max_Integer_Size:: | |
10083 | * Attribute Mechanism_Code:: | |
10084 | * Attribute Null_Parameter:: | |
10085 | * Attribute Object_Size:: | |
10086 | * Attribute Old:: | |
10087 | * Attribute Passed_By_Reference:: | |
10088 | * Attribute Pool_Address:: | |
10089 | * Attribute Range_Length:: | |
10090 | * Attribute Restriction_Set:: | |
10091 | * Attribute Result:: | |
10092 | * Attribute Safe_Emax:: | |
10093 | * Attribute Safe_Large:: | |
10094 | * Attribute Safe_Small:: | |
10095 | * Attribute Scalar_Storage_Order:: | |
10096 | * Attribute Simple_Storage_Pool:: | |
10097 | * Attribute Small:: | |
10098 | * Attribute Small_Denominator:: | |
10099 | * Attribute Small_Numerator:: | |
10100 | * Attribute Storage_Unit:: | |
10101 | * Attribute Stub_Type:: | |
10102 | * Attribute System_Allocator_Alignment:: | |
10103 | * Attribute Target_Name:: | |
10104 | * Attribute To_Address:: | |
10105 | * Attribute To_Any:: | |
10106 | * Attribute Type_Class:: | |
10107 | * Attribute Type_Key:: | |
10108 | * Attribute TypeCode:: | |
10109 | * Attribute Unconstrained_Array:: | |
10110 | * Attribute Universal_Literal_String:: | |
10111 | * Attribute Unrestricted_Access:: | |
10112 | * Attribute Update:: | |
10113 | * Attribute Valid_Value:: | |
10114 | * Attribute Valid_Scalars:: | |
10115 | * Attribute VADS_Size:: | |
10116 | * Attribute Value_Size:: | |
10117 | * Attribute Wchar_T_Size:: | |
10118 | * Attribute Word_Size:: | |
10119 | ||
10120 | @end menu | |
10121 | ||
10122 | @node Attribute Abort_Signal,Attribute Address_Size,,Implementation Defined Attributes | |
04d6c745 | 10123 | @anchor{gnat_rm/implementation_defined_attributes attribute-abort-signal}@anchor{16a} |
64d5610f ML |
10124 | @section Attribute Abort_Signal |
10125 | ||
10126 | ||
10127 | @geindex Abort_Signal | |
10128 | ||
10129 | @code{Standard'Abort_Signal} (@code{Standard} is the only allowed | |
10130 | prefix) provides the entity for the special exception used to signal | |
10131 | task abort or asynchronous transfer of control. Normally this attribute | |
10132 | should only be used in the tasking runtime (it is highly peculiar, and | |
10133 | completely outside the normal semantics of Ada, for a user program to | |
10134 | intercept the abort exception). | |
10135 | ||
10136 | @node Attribute Address_Size,Attribute Asm_Input,Attribute Abort_Signal,Implementation Defined Attributes | |
04d6c745 | 10137 | @anchor{gnat_rm/implementation_defined_attributes attribute-address-size}@anchor{16b} |
64d5610f ML |
10138 | @section Attribute Address_Size |
10139 | ||
10140 | ||
10141 | @geindex Size of `@w{`}Address`@w{`} | |
10142 | ||
10143 | @geindex Address_Size | |
10144 | ||
10145 | @code{Standard'Address_Size} (@code{Standard} is the only allowed | |
10146 | prefix) is a static constant giving the number of bits in an | |
10147 | @code{Address}. It is the same value as System.Address’Size, | |
10148 | but has the advantage of being static, while a direct | |
10149 | reference to System.Address’Size is nonstatic because Address | |
10150 | is a private type. | |
10151 | ||
10152 | @node Attribute Asm_Input,Attribute Asm_Output,Attribute Address_Size,Implementation Defined Attributes | |
04d6c745 | 10153 | @anchor{gnat_rm/implementation_defined_attributes attribute-asm-input}@anchor{16c} |
64d5610f ML |
10154 | @section Attribute Asm_Input |
10155 | ||
10156 | ||
10157 | @geindex Asm_Input | |
10158 | ||
10159 | The @code{Asm_Input} attribute denotes a function that takes two | |
10160 | parameters. The first is a string, the second is an expression of the | |
10161 | type designated by the prefix. The first (string) argument is required | |
10162 | to be a static expression, and is the constraint for the parameter, | |
10163 | (e.g., what kind of register is required). The second argument is the | |
10164 | value to be used as the input argument. The possible values for the | |
10165 | constant are the same as those used in the RTL, and are dependent on | |
10166 | the configuration file used to built the GCC back end. | |
04d6c745 | 10167 | @ref{16d,,Machine Code Insertions} |
64d5610f ML |
10168 | |
10169 | @node Attribute Asm_Output,Attribute Atomic_Always_Lock_Free,Attribute Asm_Input,Implementation Defined Attributes | |
04d6c745 | 10170 | @anchor{gnat_rm/implementation_defined_attributes attribute-asm-output}@anchor{16e} |
64d5610f ML |
10171 | @section Attribute Asm_Output |
10172 | ||
10173 | ||
10174 | @geindex Asm_Output | |
10175 | ||
10176 | The @code{Asm_Output} attribute denotes a function that takes two | |
10177 | parameters. The first is a string, the second is the name of a variable | |
10178 | of the type designated by the attribute prefix. The first (string) | |
10179 | argument is required to be a static expression and designates the | |
10180 | constraint for the parameter (e.g., what kind of register is | |
10181 | required). The second argument is the variable to be updated with the | |
10182 | result. The possible values for constraint are the same as those used in | |
10183 | the RTL, and are dependent on the configuration file used to build the | |
10184 | GCC back end. If there are no output operands, then this argument may | |
10185 | either be omitted, or explicitly given as @code{No_Output_Operands}. | |
04d6c745 | 10186 | @ref{16d,,Machine Code Insertions} |
64d5610f ML |
10187 | |
10188 | @node Attribute Atomic_Always_Lock_Free,Attribute Bit,Attribute Asm_Output,Implementation Defined Attributes | |
04d6c745 | 10189 | @anchor{gnat_rm/implementation_defined_attributes attribute-atomic-always-lock-free}@anchor{16f} |
64d5610f ML |
10190 | @section Attribute Atomic_Always_Lock_Free |
10191 | ||
10192 | ||
10193 | @geindex Atomic_Always_Lock_Free | |
10194 | ||
10195 | The prefix of the @code{Atomic_Always_Lock_Free} attribute is a type. | |
10196 | The result is a Boolean value which is True if the type has discriminants, | |
10197 | and False otherwise. The result indicate whether atomic operations are | |
10198 | supported by the target for the given type. | |
10199 | ||
10200 | @node Attribute Bit,Attribute Bit_Position,Attribute Atomic_Always_Lock_Free,Implementation Defined Attributes | |
04d6c745 | 10201 | @anchor{gnat_rm/implementation_defined_attributes attribute-bit}@anchor{170} |
64d5610f ML |
10202 | @section Attribute Bit |
10203 | ||
10204 | ||
10205 | @geindex Bit | |
10206 | ||
10207 | @code{obj'Bit}, where @code{obj} is any object, yields the bit | |
10208 | offset within the storage unit (byte) that contains the first bit of | |
10209 | storage allocated for the object. The value of this attribute is of the | |
10210 | type `universal_integer' and is always a nonnegative number smaller | |
10211 | than @code{System.Storage_Unit}. | |
10212 | ||
10213 | For an object that is a variable or a constant allocated in a register, | |
10214 | the value is zero. (The use of this attribute does not force the | |
10215 | allocation of a variable to memory). | |
10216 | ||
10217 | For an object that is a formal parameter, this attribute applies | |
10218 | to either the matching actual parameter or to a copy of the | |
10219 | matching actual parameter. | |
10220 | ||
10221 | For an access object the value is zero. Note that | |
10222 | @code{obj.all'Bit} is subject to an @code{Access_Check} for the | |
10223 | designated object. Similarly for a record component | |
10224 | @code{X.C'Bit} is subject to a discriminant check and | |
10225 | @code{X(I).Bit} and @code{X(I1..I2)'Bit} | |
10226 | are subject to index checks. | |
10227 | ||
10228 | This attribute is designed to be compatible with the DEC Ada 83 definition | |
10229 | and implementation of the @code{Bit} attribute. | |
10230 | ||
10231 | @node Attribute Bit_Position,Attribute Code_Address,Attribute Bit,Implementation Defined Attributes | |
04d6c745 | 10232 | @anchor{gnat_rm/implementation_defined_attributes attribute-bit-position}@anchor{171} |
64d5610f ML |
10233 | @section Attribute Bit_Position |
10234 | ||
10235 | ||
10236 | @geindex Bit_Position | |
10237 | ||
10238 | @code{R.C'Bit_Position}, where @code{R} is a record object and @code{C} is one | |
10239 | of the fields of the record type, yields the bit | |
10240 | offset within the record contains the first bit of | |
10241 | storage allocated for the object. The value of this attribute is of the | |
10242 | type `universal_integer'. The value depends only on the field | |
10243 | @code{C} and is independent of the alignment of | |
10244 | the containing record @code{R}. | |
10245 | ||
10246 | @node Attribute Code_Address,Attribute Compiler_Version,Attribute Bit_Position,Implementation Defined Attributes | |
04d6c745 | 10247 | @anchor{gnat_rm/implementation_defined_attributes attribute-code-address}@anchor{172} |
64d5610f ML |
10248 | @section Attribute Code_Address |
10249 | ||
10250 | ||
10251 | @geindex Code_Address | |
10252 | ||
10253 | @geindex Subprogram address | |
10254 | ||
10255 | @geindex Address of subprogram code | |
10256 | ||
10257 | The @code{'Address} | |
10258 | attribute may be applied to subprograms in Ada 95 and Ada 2005, but the | |
10259 | intended effect seems to be to provide | |
10260 | an address value which can be used to call the subprogram by means of | |
10261 | an address clause as in the following example: | |
10262 | ||
10263 | @example | |
10264 | procedure K is ... | |
10265 | ||
10266 | procedure L; | |
10267 | for L'Address use K'Address; | |
10268 | pragma Import (Ada, L); | |
10269 | @end example | |
10270 | ||
10271 | A call to @code{L} is then expected to result in a call to @code{K}. | |
10272 | In Ada 83, where there were no access-to-subprogram values, this was | |
10273 | a common work-around for getting the effect of an indirect call. | |
10274 | GNAT implements the above use of @code{Address} and the technique | |
10275 | illustrated by the example code works correctly. | |
10276 | ||
10277 | However, for some purposes, it is useful to have the address of the start | |
10278 | of the generated code for the subprogram. On some architectures, this is | |
10279 | not necessarily the same as the @code{Address} value described above. | |
10280 | For example, the @code{Address} value may reference a subprogram | |
10281 | descriptor rather than the subprogram itself. | |
10282 | ||
10283 | The @code{'Code_Address} attribute, which can only be applied to | |
10284 | subprogram entities, always returns the address of the start of the | |
10285 | generated code of the specified subprogram, which may or may not be | |
10286 | the same value as is returned by the corresponding @code{'Address} | |
10287 | attribute. | |
10288 | ||
10289 | @node Attribute Compiler_Version,Attribute Constrained,Attribute Code_Address,Implementation Defined Attributes | |
04d6c745 | 10290 | @anchor{gnat_rm/implementation_defined_attributes attribute-compiler-version}@anchor{173} |
64d5610f ML |
10291 | @section Attribute Compiler_Version |
10292 | ||
10293 | ||
10294 | @geindex Compiler_Version | |
10295 | ||
10296 | @code{Standard'Compiler_Version} (@code{Standard} is the only allowed | |
10297 | prefix) yields a static string identifying the version of the compiler | |
10298 | being used to compile the unit containing the attribute reference. | |
10299 | ||
10300 | @node Attribute Constrained,Attribute Default_Bit_Order,Attribute Compiler_Version,Implementation Defined Attributes | |
04d6c745 | 10301 | @anchor{gnat_rm/implementation_defined_attributes attribute-constrained}@anchor{174} |
64d5610f ML |
10302 | @section Attribute Constrained |
10303 | ||
10304 | ||
10305 | @geindex Constrained | |
10306 | ||
10307 | In addition to the usage of this attribute in the Ada RM, GNAT | |
10308 | also permits the use of the @code{'Constrained} attribute | |
10309 | in a generic template | |
10310 | for any type, including types without discriminants. The value of this | |
10311 | attribute in the generic instance when applied to a scalar type or a | |
10312 | record type without discriminants is always @code{True}. This usage is | |
10313 | compatible with older Ada compilers, including notably DEC Ada. | |
10314 | ||
10315 | @node Attribute Default_Bit_Order,Attribute Default_Scalar_Storage_Order,Attribute Constrained,Implementation Defined Attributes | |
04d6c745 | 10316 | @anchor{gnat_rm/implementation_defined_attributes attribute-default-bit-order}@anchor{175} |
64d5610f ML |
10317 | @section Attribute Default_Bit_Order |
10318 | ||
10319 | ||
10320 | @geindex Big endian | |
10321 | ||
10322 | @geindex Little endian | |
10323 | ||
10324 | @geindex Default_Bit_Order | |
10325 | ||
10326 | @code{Standard'Default_Bit_Order} (@code{Standard} is the only | |
10327 | allowed prefix), provides the value @code{System.Default_Bit_Order} | |
10328 | as a @code{Pos} value (0 for @code{High_Order_First}, 1 for | |
10329 | @code{Low_Order_First}). This is used to construct the definition of | |
10330 | @code{Default_Bit_Order} in package @code{System}. | |
10331 | ||
10332 | @node Attribute Default_Scalar_Storage_Order,Attribute Deref,Attribute Default_Bit_Order,Implementation Defined Attributes | |
04d6c745 | 10333 | @anchor{gnat_rm/implementation_defined_attributes attribute-default-scalar-storage-order}@anchor{176} |
64d5610f ML |
10334 | @section Attribute Default_Scalar_Storage_Order |
10335 | ||
10336 | ||
10337 | @geindex Big endian | |
10338 | ||
10339 | @geindex Little endian | |
10340 | ||
10341 | @geindex Default_Scalar_Storage_Order | |
10342 | ||
10343 | @code{Standard'Default_Scalar_Storage_Order} (@code{Standard} is the only | |
10344 | allowed prefix), provides the current value of the default scalar storage | |
10345 | order (as specified using pragma @code{Default_Scalar_Storage_Order}, or | |
10346 | equal to @code{Default_Bit_Order} if unspecified) as a | |
10347 | @code{System.Bit_Order} value. This is a static attribute. | |
10348 | ||
10349 | @node Attribute Deref,Attribute Descriptor_Size,Attribute Default_Scalar_Storage_Order,Implementation Defined Attributes | |
04d6c745 | 10350 | @anchor{gnat_rm/implementation_defined_attributes attribute-deref}@anchor{177} |
64d5610f ML |
10351 | @section Attribute Deref |
10352 | ||
10353 | ||
10354 | @geindex Deref | |
10355 | ||
10356 | The attribute @code{typ'Deref(expr)} where @code{expr} is of type @code{System.Address} yields | |
10357 | the variable of type @code{typ} that is located at the given address. It is similar | |
10358 | to @code{(totyp (expr).all)}, where @code{totyp} is an unchecked conversion from address to | |
10359 | a named access-to-@cite{typ} type, except that it yields a variable, so it can be | |
10360 | used on the left side of an assignment. | |
10361 | ||
10362 | @node Attribute Descriptor_Size,Attribute Elaborated,Attribute Deref,Implementation Defined Attributes | |
04d6c745 | 10363 | @anchor{gnat_rm/implementation_defined_attributes attribute-descriptor-size}@anchor{178} |
64d5610f ML |
10364 | @section Attribute Descriptor_Size |
10365 | ||
10366 | ||
10367 | @geindex Descriptor | |
10368 | ||
10369 | @geindex Dope vector | |
10370 | ||
10371 | @geindex Descriptor_Size | |
10372 | ||
10373 | Nonstatic attribute @code{Descriptor_Size} returns the size in bits of the | |
10374 | descriptor allocated for a type. The result is non-zero only for unconstrained | |
10375 | array types and the returned value is of type universal integer. In GNAT, an | |
10376 | array descriptor contains bounds information and is located immediately before | |
10377 | the first element of the array. | |
10378 | ||
10379 | @example | |
10380 | type Unconstr_Array is array (Short_Short_Integer range <>) of Positive; | |
10381 | Put_Line ("Descriptor size = " & Unconstr_Array'Descriptor_Size'Img); | |
10382 | @end example | |
10383 | ||
10384 | The attribute takes into account any padding due to the alignment of the | |
10385 | component type. In the example above, the descriptor contains two values | |
10386 | of type @code{Short_Short_Integer} representing the low and high bound. But, | |
10387 | since @code{Positive} has an alignment of 4, the size of the descriptor is | |
10388 | @code{2 * Short_Short_Integer'Size} rounded up to the next multiple of 32, | |
10389 | which yields a size of 32 bits, i.e. including 16 bits of padding. | |
10390 | ||
10391 | @node Attribute Elaborated,Attribute Elab_Body,Attribute Descriptor_Size,Implementation Defined Attributes | |
04d6c745 | 10392 | @anchor{gnat_rm/implementation_defined_attributes attribute-elaborated}@anchor{179} |
64d5610f ML |
10393 | @section Attribute Elaborated |
10394 | ||
10395 | ||
10396 | @geindex Elaborated | |
10397 | ||
10398 | The prefix of the @code{'Elaborated} attribute must be a unit name. The | |
10399 | value is a Boolean which indicates whether or not the given unit has been | |
10400 | elaborated. This attribute is primarily intended for internal use by the | |
10401 | generated code for dynamic elaboration checking, but it can also be used | |
10402 | in user programs. The value will always be True once elaboration of all | |
10403 | units has been completed. An exception is for units which need no | |
10404 | elaboration, the value is always False for such units. | |
10405 | ||
10406 | @node Attribute Elab_Body,Attribute Elab_Spec,Attribute Elaborated,Implementation Defined Attributes | |
04d6c745 | 10407 | @anchor{gnat_rm/implementation_defined_attributes attribute-elab-body}@anchor{17a} |
64d5610f ML |
10408 | @section Attribute Elab_Body |
10409 | ||
10410 | ||
10411 | @geindex Elab_Body | |
10412 | ||
10413 | This attribute can only be applied to a program unit name. It returns | |
10414 | the entity for the corresponding elaboration procedure for elaborating | |
10415 | the body of the referenced unit. This is used in the main generated | |
10416 | elaboration procedure by the binder and is not normally used in any | |
10417 | other context. However, there may be specialized situations in which it | |
10418 | is useful to be able to call this elaboration procedure from Ada code, | |
10419 | e.g., if it is necessary to do selective re-elaboration to fix some | |
10420 | error. | |
10421 | ||
10422 | @node Attribute Elab_Spec,Attribute Elab_Subp_Body,Attribute Elab_Body,Implementation Defined Attributes | |
04d6c745 | 10423 | @anchor{gnat_rm/implementation_defined_attributes attribute-elab-spec}@anchor{17b} |
64d5610f ML |
10424 | @section Attribute Elab_Spec |
10425 | ||
10426 | ||
10427 | @geindex Elab_Spec | |
10428 | ||
10429 | This attribute can only be applied to a program unit name. It returns | |
10430 | the entity for the corresponding elaboration procedure for elaborating | |
10431 | the spec of the referenced unit. This is used in the main | |
10432 | generated elaboration procedure by the binder and is not normally used | |
10433 | in any other context. However, there may be specialized situations in | |
10434 | which it is useful to be able to call this elaboration procedure from | |
10435 | Ada code, e.g., if it is necessary to do selective re-elaboration to fix | |
10436 | some error. | |
10437 | ||
10438 | @node Attribute Elab_Subp_Body,Attribute Emax,Attribute Elab_Spec,Implementation Defined Attributes | |
04d6c745 | 10439 | @anchor{gnat_rm/implementation_defined_attributes attribute-elab-subp-body}@anchor{17c} |
64d5610f ML |
10440 | @section Attribute Elab_Subp_Body |
10441 | ||
10442 | ||
10443 | @geindex Elab_Subp_Body | |
10444 | ||
10445 | This attribute can only be applied to a library level subprogram | |
10446 | name and is only allowed in CodePeer mode. It returns the entity | |
10447 | for the corresponding elaboration procedure for elaborating the body | |
10448 | of the referenced subprogram unit. This is used in the main generated | |
10449 | elaboration procedure by the binder in CodePeer mode only and is unrecognized | |
10450 | otherwise. | |
10451 | ||
10452 | @node Attribute Emax,Attribute Enabled,Attribute Elab_Subp_Body,Implementation Defined Attributes | |
04d6c745 | 10453 | @anchor{gnat_rm/implementation_defined_attributes attribute-emax}@anchor{17d} |
64d5610f ML |
10454 | @section Attribute Emax |
10455 | ||
10456 | ||
10457 | @geindex Ada 83 attributes | |
10458 | ||
10459 | @geindex Emax | |
10460 | ||
10461 | The @code{Emax} attribute is provided for compatibility with Ada 83. See | |
10462 | the Ada 83 reference manual for an exact description of the semantics of | |
10463 | this attribute. | |
10464 | ||
10465 | @node Attribute Enabled,Attribute Enum_Rep,Attribute Emax,Implementation Defined Attributes | |
04d6c745 | 10466 | @anchor{gnat_rm/implementation_defined_attributes attribute-enabled}@anchor{17e} |
64d5610f ML |
10467 | @section Attribute Enabled |
10468 | ||
10469 | ||
10470 | @geindex Enabled | |
10471 | ||
10472 | The @code{Enabled} attribute allows an application program to check at compile | |
10473 | time to see if the designated check is currently enabled. The prefix is a | |
10474 | simple identifier, referencing any predefined check name (other than | |
10475 | @code{All_Checks}) or a check name introduced by pragma Check_Name. If | |
10476 | no argument is given for the attribute, the check is for the general state | |
10477 | of the check, if an argument is given, then it is an entity name, and the | |
10478 | check indicates whether an @code{Suppress} or @code{Unsuppress} has been | |
10479 | given naming the entity (if not, then the argument is ignored). | |
10480 | ||
10481 | Note that instantiations inherit the check status at the point of the | |
10482 | instantiation, so a useful idiom is to have a library package that | |
10483 | introduces a check name with @code{pragma Check_Name}, and then contains | |
10484 | generic packages or subprograms which use the @code{Enabled} attribute | |
10485 | to see if the check is enabled. A user of this package can then issue | |
10486 | a @code{pragma Suppress} or @code{pragma Unsuppress} before instantiating | |
10487 | the package or subprogram, controlling whether the check will be present. | |
10488 | ||
10489 | @node Attribute Enum_Rep,Attribute Enum_Val,Attribute Enabled,Implementation Defined Attributes | |
04d6c745 | 10490 | @anchor{gnat_rm/implementation_defined_attributes attribute-enum-rep}@anchor{17f} |
64d5610f ML |
10491 | @section Attribute Enum_Rep |
10492 | ||
10493 | ||
10494 | @geindex Representation of enums | |
10495 | ||
10496 | @geindex Enum_Rep | |
10497 | ||
10498 | Note that this attribute is now standard in Ada 202x and is available | |
10499 | as an implementation defined attribute for earlier Ada versions. | |
10500 | ||
10501 | For every enumeration subtype @code{S}, @code{S'Enum_Rep} denotes a | |
10502 | function with the following spec: | |
10503 | ||
10504 | @example | |
10505 | function S'Enum_Rep (Arg : S'Base) return <Universal_Integer>; | |
10506 | @end example | |
10507 | ||
10508 | It is also allowable to apply @code{Enum_Rep} directly to an object of an | |
10509 | enumeration type or to a non-overloaded enumeration | |
10510 | literal. In this case @code{S'Enum_Rep} is equivalent to | |
10511 | @code{typ'Enum_Rep(S)} where @code{typ} is the type of the | |
10512 | enumeration literal or object. | |
10513 | ||
10514 | The function returns the representation value for the given enumeration | |
10515 | value. This will be equal to value of the @code{Pos} attribute in the | |
10516 | absence of an enumeration representation clause. This is a static | |
10517 | attribute (i.e., the result is static if the argument is static). | |
10518 | ||
10519 | @code{S'Enum_Rep} can also be used with integer types and objects, | |
10520 | in which case it simply returns the integer value. The reason for this | |
10521 | is to allow it to be used for @code{(<>)} discrete formal arguments in | |
10522 | a generic unit that can be instantiated with either enumeration types | |
10523 | or integer types. Note that if @code{Enum_Rep} is used on a modular | |
10524 | type whose upper bound exceeds the upper bound of the largest signed | |
10525 | integer type, and the argument is a variable, so that the universal | |
10526 | integer calculation is done at run time, then the call to @code{Enum_Rep} | |
10527 | may raise @code{Constraint_Error}. | |
10528 | ||
10529 | @node Attribute Enum_Val,Attribute Epsilon,Attribute Enum_Rep,Implementation Defined Attributes | |
04d6c745 | 10530 | @anchor{gnat_rm/implementation_defined_attributes attribute-enum-val}@anchor{180} |
64d5610f ML |
10531 | @section Attribute Enum_Val |
10532 | ||
10533 | ||
10534 | @geindex Representation of enums | |
10535 | ||
10536 | @geindex Enum_Val | |
10537 | ||
10538 | Note that this attribute is now standard in Ada 202x and is available | |
10539 | as an implementation defined attribute for earlier Ada versions. | |
10540 | ||
10541 | For every enumeration subtype @code{S}, @code{S'Enum_Val} denotes a | |
10542 | function with the following spec: | |
10543 | ||
10544 | @example | |
10545 | function S'Enum_Val (Arg : <Universal_Integer>) return S'Base; | |
10546 | @end example | |
10547 | ||
10548 | The function returns the enumeration value whose representation matches the | |
10549 | argument, or raises Constraint_Error if no enumeration literal of the type | |
10550 | has the matching value. | |
10551 | This will be equal to value of the @code{Val} attribute in the | |
10552 | absence of an enumeration representation clause. This is a static | |
10553 | attribute (i.e., the result is static if the argument is static). | |
10554 | ||
10555 | @node Attribute Epsilon,Attribute Fast_Math,Attribute Enum_Val,Implementation Defined Attributes | |
04d6c745 | 10556 | @anchor{gnat_rm/implementation_defined_attributes attribute-epsilon}@anchor{181} |
64d5610f ML |
10557 | @section Attribute Epsilon |
10558 | ||
10559 | ||
10560 | @geindex Ada 83 attributes | |
10561 | ||
10562 | @geindex Epsilon | |
10563 | ||
10564 | The @code{Epsilon} attribute is provided for compatibility with Ada 83. See | |
10565 | the Ada 83 reference manual for an exact description of the semantics of | |
10566 | this attribute. | |
10567 | ||
10568 | @node Attribute Fast_Math,Attribute Finalization_Size,Attribute Epsilon,Implementation Defined Attributes | |
04d6c745 | 10569 | @anchor{gnat_rm/implementation_defined_attributes attribute-fast-math}@anchor{182} |
64d5610f ML |
10570 | @section Attribute Fast_Math |
10571 | ||
10572 | ||
10573 | @geindex Fast_Math | |
10574 | ||
10575 | @code{Standard'Fast_Math} (@code{Standard} is the only allowed | |
10576 | prefix) yields a static Boolean value that is True if pragma | |
10577 | @code{Fast_Math} is active, and False otherwise. | |
10578 | ||
10579 | @node Attribute Finalization_Size,Attribute Fixed_Value,Attribute Fast_Math,Implementation Defined Attributes | |
04d6c745 | 10580 | @anchor{gnat_rm/implementation_defined_attributes attribute-finalization-size}@anchor{183} |
64d5610f ML |
10581 | @section Attribute Finalization_Size |
10582 | ||
10583 | ||
10584 | @geindex Finalization_Size | |
10585 | ||
10586 | The prefix of attribute @code{Finalization_Size} must be an object or | |
10587 | a non-class-wide type. This attribute returns the size of any hidden data | |
10588 | reserved by the compiler to handle finalization-related actions. The type of | |
10589 | the attribute is `universal_integer'. | |
10590 | ||
10591 | @code{Finalization_Size} yields a value of zero for a type with no controlled | |
10592 | parts, an object whose type has no controlled parts, or an object of a | |
10593 | class-wide type whose tag denotes a type with no controlled parts. | |
10594 | ||
10595 | Note that only heap-allocated objects contain finalization data. | |
10596 | ||
10597 | @node Attribute Fixed_Value,Attribute From_Any,Attribute Finalization_Size,Implementation Defined Attributes | |
04d6c745 | 10598 | @anchor{gnat_rm/implementation_defined_attributes attribute-fixed-value}@anchor{184} |
64d5610f ML |
10599 | @section Attribute Fixed_Value |
10600 | ||
10601 | ||
10602 | @geindex Fixed_Value | |
10603 | ||
10604 | For every fixed-point type @code{S}, @code{S'Fixed_Value} denotes a | |
10605 | function with the following specification: | |
10606 | ||
10607 | @example | |
10608 | function S'Fixed_Value (Arg : <Universal_Integer>) return S; | |
10609 | @end example | |
10610 | ||
10611 | The value returned is the fixed-point value @code{V} such that: | |
10612 | ||
10613 | @example | |
10614 | V = Arg * S'Small | |
10615 | @end example | |
10616 | ||
10617 | The effect is thus similar to first converting the argument to the | |
10618 | integer type used to represent @code{S}, and then doing an unchecked | |
10619 | conversion to the fixed-point type. The difference is | |
10620 | that there are full range checks, to ensure that the result is in range. | |
10621 | This attribute is primarily intended for use in implementation of the | |
10622 | input-output functions for fixed-point values. | |
10623 | ||
10624 | @node Attribute From_Any,Attribute Has_Access_Values,Attribute Fixed_Value,Implementation Defined Attributes | |
04d6c745 | 10625 | @anchor{gnat_rm/implementation_defined_attributes attribute-from-any}@anchor{185} |
64d5610f ML |
10626 | @section Attribute From_Any |
10627 | ||
10628 | ||
10629 | @geindex From_Any | |
10630 | ||
10631 | This internal attribute is used for the generation of remote subprogram | |
10632 | stubs in the context of the Distributed Systems Annex. | |
10633 | ||
10634 | @node Attribute Has_Access_Values,Attribute Has_Discriminants,Attribute From_Any,Implementation Defined Attributes | |
04d6c745 | 10635 | @anchor{gnat_rm/implementation_defined_attributes attribute-has-access-values}@anchor{186} |
64d5610f ML |
10636 | @section Attribute Has_Access_Values |
10637 | ||
10638 | ||
10639 | @geindex Access values | |
10640 | @geindex testing for | |
10641 | ||
10642 | @geindex Has_Access_Values | |
10643 | ||
10644 | The prefix of the @code{Has_Access_Values} attribute is a type. The result | |
10645 | is a Boolean value which is True if the is an access type, or is a composite | |
10646 | type with a component (at any nesting depth) that is an access type, and is | |
10647 | False otherwise. | |
10648 | The intended use of this attribute is in conjunction with generic | |
10649 | definitions. If the attribute is applied to a generic private type, it | |
10650 | indicates whether or not the corresponding actual type has access values. | |
10651 | ||
10652 | @node Attribute Has_Discriminants,Attribute Has_Tagged_Values,Attribute Has_Access_Values,Implementation Defined Attributes | |
04d6c745 | 10653 | @anchor{gnat_rm/implementation_defined_attributes attribute-has-discriminants}@anchor{187} |
64d5610f ML |
10654 | @section Attribute Has_Discriminants |
10655 | ||
10656 | ||
10657 | @geindex Discriminants | |
10658 | @geindex testing for | |
10659 | ||
10660 | @geindex Has_Discriminants | |
10661 | ||
10662 | The prefix of the @code{Has_Discriminants} attribute is a type. The result | |
10663 | is a Boolean value which is True if the type has discriminants, and False | |
10664 | otherwise. The intended use of this attribute is in conjunction with generic | |
10665 | definitions. If the attribute is applied to a generic private type, it | |
10666 | indicates whether or not the corresponding actual type has discriminants. | |
10667 | ||
10668 | @node Attribute Has_Tagged_Values,Attribute Img,Attribute Has_Discriminants,Implementation Defined Attributes | |
04d6c745 | 10669 | @anchor{gnat_rm/implementation_defined_attributes attribute-has-tagged-values}@anchor{188} |
64d5610f ML |
10670 | @section Attribute Has_Tagged_Values |
10671 | ||
10672 | ||
10673 | @geindex Tagged values | |
10674 | @geindex testing for | |
10675 | ||
10676 | @geindex Has_Tagged_Values | |
10677 | ||
10678 | The prefix of the @code{Has_Tagged_Values} attribute is a type. The result is a | |
10679 | Boolean value which is True if the type is a composite type (array or record) | |
10680 | that is either a tagged type or has a subcomponent that is tagged, and is False | |
10681 | otherwise. The intended use of this attribute is in conjunction with generic | |
10682 | definitions. If the attribute is applied to a generic private type, it | |
10683 | indicates whether or not the corresponding actual type has access values. | |
10684 | ||
10685 | @node Attribute Img,Attribute Initialized,Attribute Has_Tagged_Values,Implementation Defined Attributes | |
04d6c745 | 10686 | @anchor{gnat_rm/implementation_defined_attributes attribute-img}@anchor{189} |
64d5610f ML |
10687 | @section Attribute Img |
10688 | ||
10689 | ||
10690 | @geindex Img | |
10691 | ||
10692 | The @code{Img} attribute differs from @code{Image} in that, while both can be | |
10693 | applied directly to an object, @code{Img} cannot be applied to types. | |
10694 | ||
10695 | Example usage of the attribute: | |
10696 | ||
10697 | @example | |
10698 | Put_Line ("X = " & X'Img); | |
10699 | @end example | |
10700 | ||
10701 | which has the same meaning as the more verbose: | |
10702 | ||
10703 | @example | |
10704 | Put_Line ("X = " & T'Image (X)); | |
10705 | @end example | |
10706 | ||
10707 | where @code{T} is the (sub)type of the object @code{X}. | |
10708 | ||
10709 | Note that technically, in analogy to @code{Image}, | |
10710 | @code{X'Img} returns a parameterless function | |
10711 | that returns the appropriate string when called. This means that | |
10712 | @code{X'Img} can be renamed as a function-returning-string, or used | |
10713 | in an instantiation as a function parameter. | |
10714 | ||
10715 | @node Attribute Initialized,Attribute Integer_Value,Attribute Img,Implementation Defined Attributes | |
04d6c745 | 10716 | @anchor{gnat_rm/implementation_defined_attributes attribute-initialized}@anchor{18a} |
64d5610f ML |
10717 | @section Attribute Initialized |
10718 | ||
10719 | ||
10720 | @geindex Initialized | |
10721 | ||
10722 | For the syntax and semantics of this attribute, see the SPARK 2014 Reference | |
10723 | Manual, section 6.10. | |
10724 | ||
10725 | @node Attribute Integer_Value,Attribute Invalid_Value,Attribute Initialized,Implementation Defined Attributes | |
04d6c745 | 10726 | @anchor{gnat_rm/implementation_defined_attributes attribute-integer-value}@anchor{18b} |
64d5610f ML |
10727 | @section Attribute Integer_Value |
10728 | ||
10729 | ||
10730 | @geindex Integer_Value | |
10731 | ||
10732 | For every integer type @code{S}, @code{S'Integer_Value} denotes a | |
10733 | function with the following spec: | |
10734 | ||
10735 | @example | |
10736 | function S'Integer_Value (Arg : <Universal_Fixed>) return S; | |
10737 | @end example | |
10738 | ||
10739 | The value returned is the integer value @code{V}, such that: | |
10740 | ||
10741 | @example | |
10742 | Arg = V * T'Small | |
10743 | @end example | |
10744 | ||
10745 | where @code{T} is the type of @code{Arg}. | |
10746 | The effect is thus similar to first doing an unchecked conversion from | |
10747 | the fixed-point type to its corresponding implementation type, and then | |
10748 | converting the result to the target integer type. The difference is | |
10749 | that there are full range checks, to ensure that the result is in range. | |
10750 | This attribute is primarily intended for use in implementation of the | |
10751 | standard input-output functions for fixed-point values. | |
10752 | ||
10753 | @node Attribute Invalid_Value,Attribute Iterable,Attribute Integer_Value,Implementation Defined Attributes | |
04d6c745 | 10754 | @anchor{gnat_rm/implementation_defined_attributes attribute-invalid-value}@anchor{18c} |
64d5610f ML |
10755 | @section Attribute Invalid_Value |
10756 | ||
10757 | ||
10758 | @geindex Invalid_Value | |
10759 | ||
10760 | For every scalar type S, S’Invalid_Value returns an undefined value of the | |
10761 | type. If possible this value is an invalid representation for the type. The | |
10762 | value returned is identical to the value used to initialize an otherwise | |
10763 | uninitialized value of the type if pragma Initialize_Scalars is used, | |
10764 | including the ability to modify the value with the binder -Sxx flag and | |
10765 | relevant environment variables at run time. | |
10766 | ||
10767 | @node Attribute Iterable,Attribute Large,Attribute Invalid_Value,Implementation Defined Attributes | |
04d6c745 | 10768 | @anchor{gnat_rm/implementation_defined_attributes attribute-iterable}@anchor{18d} |
64d5610f ML |
10769 | @section Attribute Iterable |
10770 | ||
10771 | ||
10772 | @geindex Iterable | |
10773 | ||
10774 | Equivalent to Aspect Iterable. | |
10775 | ||
10776 | @node Attribute Large,Attribute Library_Level,Attribute Iterable,Implementation Defined Attributes | |
04d6c745 | 10777 | @anchor{gnat_rm/implementation_defined_attributes attribute-large}@anchor{18e} |
64d5610f ML |
10778 | @section Attribute Large |
10779 | ||
10780 | ||
10781 | @geindex Ada 83 attributes | |
10782 | ||
10783 | @geindex Large | |
10784 | ||
10785 | The @code{Large} attribute is provided for compatibility with Ada 83. See | |
10786 | the Ada 83 reference manual for an exact description of the semantics of | |
10787 | this attribute. | |
10788 | ||
10789 | @node Attribute Library_Level,Attribute Loop_Entry,Attribute Large,Implementation Defined Attributes | |
04d6c745 | 10790 | @anchor{gnat_rm/implementation_defined_attributes attribute-library-level}@anchor{18f} |
64d5610f ML |
10791 | @section Attribute Library_Level |
10792 | ||
10793 | ||
10794 | @geindex Library_Level | |
10795 | ||
10796 | @code{P'Library_Level}, where P is an entity name, | |
10797 | returns a Boolean value which is True if the entity is declared | |
10798 | at the library level, and False otherwise. Note that within a | |
10799 | generic instantiation, the name of the generic unit denotes the | |
10800 | instance, which means that this attribute can be used to test | |
10801 | if a generic is instantiated at the library level, as shown | |
10802 | in this example: | |
10803 | ||
10804 | @example | |
10805 | generic | |
10806 | ... | |
10807 | package Gen is | |
10808 | pragma Compile_Time_Error | |
10809 | (not Gen'Library_Level, | |
10810 | "Gen can only be instantiated at library level"); | |
10811 | ... | |
10812 | end Gen; | |
10813 | @end example | |
10814 | ||
10815 | @node Attribute Loop_Entry,Attribute Machine_Size,Attribute Library_Level,Implementation Defined Attributes | |
04d6c745 | 10816 | @anchor{gnat_rm/implementation_defined_attributes attribute-loop-entry}@anchor{190} |
64d5610f ML |
10817 | @section Attribute Loop_Entry |
10818 | ||
10819 | ||
10820 | @geindex Loop_Entry | |
10821 | ||
10822 | Syntax: | |
10823 | ||
10824 | @example | |
10825 | X'Loop_Entry [(loop_name)] | |
10826 | @end example | |
10827 | ||
10828 | The @code{Loop_Entry} attribute is used to refer to the value that an | |
10829 | expression had upon entry to a given loop in much the same way that the | |
10830 | @code{Old} attribute in a subprogram postcondition can be used to refer | |
10831 | to the value an expression had upon entry to the subprogram. The | |
10832 | relevant loop is either identified by the given loop name, or it is the | |
10833 | innermost enclosing loop when no loop name is given. | |
10834 | ||
10835 | A @code{Loop_Entry} attribute can only occur within an @code{Assert}, | |
10836 | @code{Assert_And_Cut}, @code{Assume}, @code{Loop_Variant} or @code{Loop_Invariant} pragma. | |
10837 | In addition, such a pragma must be one of the items in the sequence | |
10838 | of statements of a loop body, or nested inside block statements that | |
10839 | appear in the sequence of statements of a loop body. | |
10840 | A common use of @code{Loop_Entry} is to compare the current value of objects with | |
10841 | their initial value at loop entry, in a @code{Loop_Invariant} pragma. | |
10842 | ||
10843 | The effect of using @code{X'Loop_Entry} is the same as declaring | |
10844 | a constant initialized with the initial value of @code{X} at loop | |
10845 | entry. This copy is not performed if the loop is not entered, or if the | |
10846 | corresponding pragmas are ignored or disabled. | |
10847 | ||
10848 | @node Attribute Machine_Size,Attribute Mantissa,Attribute Loop_Entry,Implementation Defined Attributes | |
04d6c745 | 10849 | @anchor{gnat_rm/implementation_defined_attributes attribute-machine-size}@anchor{191} |
64d5610f ML |
10850 | @section Attribute Machine_Size |
10851 | ||
10852 | ||
10853 | @geindex Machine_Size | |
10854 | ||
10855 | This attribute is identical to the @code{Object_Size} attribute. It is | |
10856 | provided for compatibility with the DEC Ada 83 attribute of this name. | |
10857 | ||
10858 | @node Attribute Mantissa,Attribute Maximum_Alignment,Attribute Machine_Size,Implementation Defined Attributes | |
04d6c745 | 10859 | @anchor{gnat_rm/implementation_defined_attributes attribute-mantissa}@anchor{192} |
64d5610f ML |
10860 | @section Attribute Mantissa |
10861 | ||
10862 | ||
10863 | @geindex Ada 83 attributes | |
10864 | ||
10865 | @geindex Mantissa | |
10866 | ||
10867 | The @code{Mantissa} attribute is provided for compatibility with Ada 83. See | |
10868 | the Ada 83 reference manual for an exact description of the semantics of | |
10869 | this attribute. | |
10870 | ||
10871 | @node Attribute Maximum_Alignment,Attribute Max_Integer_Size,Attribute Mantissa,Implementation Defined Attributes | |
04d6c745 | 10872 | @anchor{gnat_rm/implementation_defined_attributes attribute-maximum-alignment}@anchor{193}@anchor{gnat_rm/implementation_defined_attributes id2}@anchor{194} |
64d5610f ML |
10873 | @section Attribute Maximum_Alignment |
10874 | ||
10875 | ||
10876 | @geindex Alignment | |
10877 | @geindex maximum | |
10878 | ||
10879 | @geindex Maximum_Alignment | |
10880 | ||
10881 | @code{Standard'Maximum_Alignment} (@code{Standard} is the only | |
10882 | allowed prefix) provides the maximum useful alignment value for the | |
10883 | target. This is a static value that can be used to specify the alignment | |
10884 | for an object, guaranteeing that it is properly aligned in all | |
10885 | cases. | |
10886 | ||
10887 | @node Attribute Max_Integer_Size,Attribute Mechanism_Code,Attribute Maximum_Alignment,Implementation Defined Attributes | |
04d6c745 | 10888 | @anchor{gnat_rm/implementation_defined_attributes attribute-max-integer-size}@anchor{195} |
64d5610f ML |
10889 | @section Attribute Max_Integer_Size |
10890 | ||
10891 | ||
10892 | @geindex Max_Integer_Size | |
10893 | ||
10894 | @code{Standard'Max_Integer_Size} (@code{Standard} is the only allowed | |
10895 | prefix) provides the size of the largest supported integer type for | |
10896 | the target. The result is a static constant. | |
10897 | ||
10898 | @node Attribute Mechanism_Code,Attribute Null_Parameter,Attribute Max_Integer_Size,Implementation Defined Attributes | |
04d6c745 | 10899 | @anchor{gnat_rm/implementation_defined_attributes attribute-mechanism-code}@anchor{196} |
64d5610f ML |
10900 | @section Attribute Mechanism_Code |
10901 | ||
10902 | ||
10903 | @geindex Return values | |
10904 | @geindex passing mechanism | |
10905 | ||
10906 | @geindex Parameters | |
10907 | @geindex passing mechanism | |
10908 | ||
10909 | @geindex Mechanism_Code | |
10910 | ||
10911 | @code{func'Mechanism_Code} yields an integer code for the | |
10912 | mechanism used for the result of function @code{func}, and | |
10913 | @code{subprog'Mechanism_Code (n)} yields the mechanism | |
10914 | used for formal parameter number `n' (a static integer value, with 1 | |
10915 | meaning the first parameter) of subprogram @code{subprog}. The code returned is: | |
10916 | ||
10917 | ||
10918 | @table @asis | |
10919 | ||
10920 | @item `1' | |
10921 | ||
10922 | by copy (value) | |
10923 | ||
10924 | @item `2' | |
10925 | ||
10926 | by reference | |
10927 | @end table | |
10928 | ||
10929 | @node Attribute Null_Parameter,Attribute Object_Size,Attribute Mechanism_Code,Implementation Defined Attributes | |
04d6c745 | 10930 | @anchor{gnat_rm/implementation_defined_attributes attribute-null-parameter}@anchor{197} |
64d5610f ML |
10931 | @section Attribute Null_Parameter |
10932 | ||
10933 | ||
10934 | @geindex Zero address | |
10935 | @geindex passing | |
10936 | ||
10937 | @geindex Null_Parameter | |
10938 | ||
10939 | A reference @code{T'Null_Parameter} denotes an imaginary object of | |
10940 | type or subtype @code{T} allocated at machine address zero. The attribute | |
10941 | is allowed only as the default expression of a formal parameter, or as | |
10942 | an actual expression of a subprogram call. In either case, the | |
10943 | subprogram must be imported. | |
10944 | ||
10945 | The identity of the object is represented by the address zero in the | |
10946 | argument list, independent of the passing mechanism (explicit or | |
10947 | default). | |
10948 | ||
10949 | This capability is needed to specify that a zero address should be | |
10950 | passed for a record or other composite object passed by reference. | |
10951 | There is no way of indicating this without the @code{Null_Parameter} | |
10952 | attribute. | |
10953 | ||
10954 | @node Attribute Object_Size,Attribute Old,Attribute Null_Parameter,Implementation Defined Attributes | |
04d6c745 | 10955 | @anchor{gnat_rm/implementation_defined_attributes attribute-object-size}@anchor{147}@anchor{gnat_rm/implementation_defined_attributes id3}@anchor{198} |
64d5610f ML |
10956 | @section Attribute Object_Size |
10957 | ||
10958 | ||
10959 | @geindex Size | |
10960 | @geindex used for objects | |
10961 | ||
10962 | @geindex Object_Size | |
10963 | ||
10964 | The size of an object is not necessarily the same as the size of the type | |
10965 | of an object. This is because by default object sizes are increased to be | |
10966 | a multiple of the alignment of the object. For example, | |
10967 | @code{Natural'Size} is | |
10968 | 31, but by default objects of type @code{Natural} will have a size of 32 bits. | |
10969 | Similarly, a record containing an integer and a character: | |
10970 | ||
10971 | @example | |
10972 | type Rec is record | |
10973 | I : Integer; | |
10974 | C : Character; | |
10975 | end record; | |
10976 | @end example | |
10977 | ||
10978 | will have a size of 40 (that is @code{Rec'Size} will be 40). The | |
10979 | alignment will be 4, because of the | |
10980 | integer field, and so the default size of record objects for this type | |
10981 | will be 64 (8 bytes). | |
10982 | ||
10983 | If the alignment of the above record is specified to be 1, then the | |
10984 | object size will be 40 (5 bytes). This is true by default, and also | |
10985 | an object size of 40 can be explicitly specified in this case. | |
10986 | ||
10987 | A consequence of this capability is that different object sizes can be | |
10988 | given to subtypes that would otherwise be considered in Ada to be | |
10989 | statically matching. But it makes no sense to consider such subtypes | |
10990 | as statically matching. Consequently, GNAT adds a rule | |
10991 | to the static matching rules that requires object sizes to match. | |
10992 | Consider this example: | |
10993 | ||
10994 | @example | |
10995 | 1. procedure BadAVConvert is | |
10996 | 2. type R is new Integer; | |
10997 | 3. subtype R1 is R range 1 .. 10; | |
10998 | 4. subtype R2 is R range 1 .. 10; | |
10999 | 5. for R1'Object_Size use 8; | |
11000 | 6. for R2'Object_Size use 16; | |
11001 | 7. type R1P is access all R1; | |
11002 | 8. type R2P is access all R2; | |
11003 | 9. R1PV : R1P := new R1'(4); | |
11004 | 10. R2PV : R2P; | |
11005 | 11. begin | |
11006 | 12. R2PV := R2P (R1PV); | |
11007 | | | |
11008 | >>> target designated subtype not compatible with | |
11009 | type "R1" defined at line 3 | |
11010 | ||
11011 | 13. end; | |
11012 | @end example | |
11013 | ||
11014 | In the absence of lines 5 and 6, | |
11015 | types @code{R1} and @code{R2} statically match and | |
11016 | hence the conversion on line 12 is legal. But since lines 5 and 6 | |
11017 | cause the object sizes to differ, GNAT considers that types | |
11018 | @code{R1} and @code{R2} are not statically matching, and line 12 | |
11019 | generates the diagnostic shown above. | |
11020 | ||
11021 | Similar additional checks are performed in other contexts requiring | |
11022 | statically matching subtypes. | |
11023 | ||
11024 | @node Attribute Old,Attribute Passed_By_Reference,Attribute Object_Size,Implementation Defined Attributes | |
04d6c745 | 11025 | @anchor{gnat_rm/implementation_defined_attributes attribute-old}@anchor{199} |
64d5610f ML |
11026 | @section Attribute Old |
11027 | ||
11028 | ||
11029 | @geindex Old | |
11030 | ||
11031 | In addition to the usage of @code{Old} defined in the Ada 2012 RM (usage | |
11032 | within @code{Post} aspect), GNAT also permits the use of this attribute | |
11033 | in implementation defined pragmas @code{Postcondition}, | |
11034 | @code{Contract_Cases} and @code{Test_Case}. Also usages of | |
11035 | @code{Old} which would be illegal according to the Ada 2012 RM | |
11036 | definition are allowed under control of | |
11037 | implementation defined pragma @code{Unevaluated_Use_Of_Old}. | |
11038 | ||
11039 | @node Attribute Passed_By_Reference,Attribute Pool_Address,Attribute Old,Implementation Defined Attributes | |
04d6c745 | 11040 | @anchor{gnat_rm/implementation_defined_attributes attribute-passed-by-reference}@anchor{19a} |
64d5610f ML |
11041 | @section Attribute Passed_By_Reference |
11042 | ||
11043 | ||
11044 | @geindex Parameters | |
11045 | @geindex when passed by reference | |
11046 | ||
11047 | @geindex Passed_By_Reference | |
11048 | ||
11049 | @code{typ'Passed_By_Reference} for any subtype @cite{typ} returns | |
11050 | a value of type @code{Boolean} value that is @code{True} if the type is | |
11051 | normally passed by reference and @code{False} if the type is normally | |
11052 | passed by copy in calls. For scalar types, the result is always @code{False} | |
11053 | and is static. For non-scalar types, the result is nonstatic. | |
11054 | ||
11055 | @node Attribute Pool_Address,Attribute Range_Length,Attribute Passed_By_Reference,Implementation Defined Attributes | |
04d6c745 | 11056 | @anchor{gnat_rm/implementation_defined_attributes attribute-pool-address}@anchor{19b} |
64d5610f ML |
11057 | @section Attribute Pool_Address |
11058 | ||
11059 | ||
11060 | @geindex Pool_Address | |
11061 | ||
11062 | @code{X'Pool_Address} for any object @code{X} returns the address | |
11063 | of X within its storage pool. This is the same as | |
11064 | @code{X'Address}, except that for an unconstrained array whose | |
11065 | bounds are allocated just before the first component, | |
11066 | @code{X'Pool_Address} returns the address of those bounds, | |
11067 | whereas @code{X'Address} returns the address of the first | |
11068 | component. | |
11069 | ||
11070 | Here, we are interpreting ‘storage pool’ broadly to mean | |
11071 | @code{wherever the object is allocated}, which could be a | |
11072 | user-defined storage pool, | |
11073 | the global heap, on the stack, or in a static memory area. | |
11074 | For an object created by @code{new}, @code{Ptr.all'Pool_Address} is | |
11075 | what is passed to @code{Allocate} and returned from @code{Deallocate}. | |
11076 | ||
11077 | @node Attribute Range_Length,Attribute Restriction_Set,Attribute Pool_Address,Implementation Defined Attributes | |
04d6c745 | 11078 | @anchor{gnat_rm/implementation_defined_attributes attribute-range-length}@anchor{19c} |
64d5610f ML |
11079 | @section Attribute Range_Length |
11080 | ||
11081 | ||
11082 | @geindex Range_Length | |
11083 | ||
11084 | @code{typ'Range_Length} for any discrete type @cite{typ} yields | |
11085 | the number of values represented by the subtype (zero for a null | |
11086 | range). The result is static for static subtypes. @code{Range_Length} | |
11087 | applied to the index subtype of a one dimensional array always gives the | |
11088 | same result as @code{Length} applied to the array itself. | |
11089 | ||
11090 | @node Attribute Restriction_Set,Attribute Result,Attribute Range_Length,Implementation Defined Attributes | |
04d6c745 | 11091 | @anchor{gnat_rm/implementation_defined_attributes attribute-restriction-set}@anchor{19d} |
64d5610f ML |
11092 | @section Attribute Restriction_Set |
11093 | ||
11094 | ||
11095 | @geindex Restriction_Set | |
11096 | ||
11097 | @geindex Restrictions | |
11098 | ||
11099 | This attribute allows compile time testing of restrictions that | |
11100 | are currently in effect. It is primarily intended for specializing | |
11101 | code in the run-time based on restrictions that are active (e.g. | |
11102 | don’t need to save fpt registers if restriction No_Floating_Point | |
11103 | is known to be in effect), but can be used anywhere. | |
11104 | ||
11105 | There are two forms: | |
11106 | ||
11107 | @example | |
11108 | System'Restriction_Set (partition_boolean_restriction_NAME) | |
11109 | System'Restriction_Set (No_Dependence => library_unit_NAME); | |
11110 | @end example | |
11111 | ||
11112 | In the case of the first form, the only restriction names | |
11113 | allowed are parameterless restrictions that are checked | |
11114 | for consistency at bind time. For a complete list see the | |
11115 | subtype @code{System.Rident.Partition_Boolean_Restrictions}. | |
11116 | ||
11117 | The result returned is True if the restriction is known to | |
11118 | be in effect, and False if the restriction is known not to | |
11119 | be in effect. An important guarantee is that the value of | |
11120 | a Restriction_Set attribute is known to be consistent throughout | |
11121 | all the code of a partition. | |
11122 | ||
11123 | This is trivially achieved if the entire partition is compiled | |
11124 | with a consistent set of restriction pragmas. However, the | |
11125 | compilation model does not require this. It is possible to | |
11126 | compile one set of units with one set of pragmas, and another | |
11127 | set of units with another set of pragmas. It is even possible | |
11128 | to compile a spec with one set of pragmas, and then WITH the | |
11129 | same spec with a different set of pragmas. Inconsistencies | |
11130 | in the actual use of the restriction are checked at bind time. | |
11131 | ||
11132 | In order to achieve the guarantee of consistency for the | |
11133 | Restriction_Set pragma, we consider that a use of the pragma | |
11134 | that yields False is equivalent to a violation of the | |
11135 | restriction. | |
11136 | ||
11137 | So for example if you write | |
11138 | ||
11139 | @example | |
11140 | if System'Restriction_Set (No_Floating_Point) then | |
11141 | ... | |
11142 | else | |
11143 | ... | |
11144 | end if; | |
11145 | @end example | |
11146 | ||
11147 | And the result is False, so that the else branch is executed, | |
11148 | you can assume that this restriction is not set for any unit | |
11149 | in the partition. This is checked by considering this use of | |
11150 | the restriction pragma to be a violation of the restriction | |
11151 | No_Floating_Point. This means that no other unit can attempt | |
11152 | to set this restriction (if some unit does attempt to set it, | |
11153 | the binder will refuse to bind the partition). | |
11154 | ||
11155 | Technical note: The restriction name and the unit name are | |
11156 | intepreted entirely syntactically, as in the corresponding | |
11157 | Restrictions pragma, they are not analyzed semantically, | |
11158 | so they do not have a type. | |
11159 | ||
11160 | @node Attribute Result,Attribute Safe_Emax,Attribute Restriction_Set,Implementation Defined Attributes | |
04d6c745 | 11161 | @anchor{gnat_rm/implementation_defined_attributes attribute-result}@anchor{19e} |
64d5610f ML |
11162 | @section Attribute Result |
11163 | ||
11164 | ||
11165 | @geindex Result | |
11166 | ||
11167 | @code{function'Result} can only be used with in a Postcondition pragma | |
11168 | for a function. The prefix must be the name of the corresponding function. This | |
11169 | is used to refer to the result of the function in the postcondition expression. | |
11170 | For a further discussion of the use of this attribute and examples of its use, | |
11171 | see the description of pragma Postcondition. | |
11172 | ||
11173 | @node Attribute Safe_Emax,Attribute Safe_Large,Attribute Result,Implementation Defined Attributes | |
04d6c745 | 11174 | @anchor{gnat_rm/implementation_defined_attributes attribute-safe-emax}@anchor{19f} |
64d5610f ML |
11175 | @section Attribute Safe_Emax |
11176 | ||
11177 | ||
11178 | @geindex Ada 83 attributes | |
11179 | ||
11180 | @geindex Safe_Emax | |
11181 | ||
11182 | The @code{Safe_Emax} attribute is provided for compatibility with Ada 83. See | |
11183 | the Ada 83 reference manual for an exact description of the semantics of | |
11184 | this attribute. | |
11185 | ||
11186 | @node Attribute Safe_Large,Attribute Safe_Small,Attribute Safe_Emax,Implementation Defined Attributes | |
04d6c745 | 11187 | @anchor{gnat_rm/implementation_defined_attributes attribute-safe-large}@anchor{1a0} |
64d5610f ML |
11188 | @section Attribute Safe_Large |
11189 | ||
11190 | ||
11191 | @geindex Ada 83 attributes | |
11192 | ||
11193 | @geindex Safe_Large | |
11194 | ||
11195 | The @code{Safe_Large} attribute is provided for compatibility with Ada 83. See | |
11196 | the Ada 83 reference manual for an exact description of the semantics of | |
11197 | this attribute. | |
11198 | ||
11199 | @node Attribute Safe_Small,Attribute Scalar_Storage_Order,Attribute Safe_Large,Implementation Defined Attributes | |
04d6c745 | 11200 | @anchor{gnat_rm/implementation_defined_attributes attribute-safe-small}@anchor{1a1} |
64d5610f ML |
11201 | @section Attribute Safe_Small |
11202 | ||
11203 | ||
11204 | @geindex Ada 83 attributes | |
11205 | ||
11206 | @geindex Safe_Small | |
11207 | ||
11208 | The @code{Safe_Small} attribute is provided for compatibility with Ada 83. See | |
11209 | the Ada 83 reference manual for an exact description of the semantics of | |
11210 | this attribute. | |
11211 | ||
11212 | @node Attribute Scalar_Storage_Order,Attribute Simple_Storage_Pool,Attribute Safe_Small,Implementation Defined Attributes | |
04d6c745 | 11213 | @anchor{gnat_rm/implementation_defined_attributes attribute-scalar-storage-order}@anchor{155}@anchor{gnat_rm/implementation_defined_attributes id4}@anchor{1a2} |
64d5610f ML |
11214 | @section Attribute Scalar_Storage_Order |
11215 | ||
11216 | ||
11217 | @geindex Endianness | |
11218 | ||
11219 | @geindex Scalar storage order | |
11220 | ||
11221 | @geindex Scalar_Storage_Order | |
11222 | ||
11223 | For every array or record type @code{S}, the representation attribute | |
11224 | @code{Scalar_Storage_Order} denotes the order in which storage elements | |
11225 | that make up scalar components are ordered within S. The value given must | |
11226 | be a static expression of type System.Bit_Order. The following is an example | |
11227 | of the use of this feature: | |
11228 | ||
11229 | @example | |
11230 | -- Component type definitions | |
11231 | ||
11232 | subtype Yr_Type is Natural range 0 .. 127; | |
11233 | subtype Mo_Type is Natural range 1 .. 12; | |
11234 | subtype Da_Type is Natural range 1 .. 31; | |
11235 | ||
11236 | -- Record declaration | |
11237 | ||
11238 | type Date is record | |
11239 | Years_Since_1980 : Yr_Type; | |
11240 | Month : Mo_Type; | |
11241 | Day_Of_Month : Da_Type; | |
11242 | end record; | |
11243 | ||
11244 | -- Record representation clause | |
11245 | ||
11246 | for Date use record | |
11247 | Years_Since_1980 at 0 range 0 .. 6; | |
11248 | Month at 0 range 7 .. 10; | |
11249 | Day_Of_Month at 0 range 11 .. 15; | |
11250 | end record; | |
11251 | ||
11252 | -- Attribute definition clauses | |
11253 | ||
11254 | for Date'Bit_Order use System.High_Order_First; | |
11255 | for Date'Scalar_Storage_Order use System.High_Order_First; | |
11256 | -- If Scalar_Storage_Order is specified, it must be consistent with | |
11257 | -- Bit_Order, so it's best to always define the latter explicitly if | |
11258 | -- the former is used. | |
11259 | @end example | |
11260 | ||
11261 | Other properties are as for the standard representation attribute @code{Bit_Order} | |
11262 | defined by Ada RM 13.5.3(4). The default is @code{System.Default_Bit_Order}. | |
11263 | ||
11264 | For a record type @code{T}, if @code{T'Scalar_Storage_Order} is | |
11265 | specified explicitly, it shall be equal to @code{T'Bit_Order}. Note: | |
11266 | this means that if a @code{Scalar_Storage_Order} attribute definition | |
11267 | clause is not confirming, then the type’s @code{Bit_Order} shall be | |
11268 | specified explicitly and set to the same value. | |
11269 | ||
11270 | Derived types inherit an explicitly set scalar storage order from their parent | |
11271 | types. This may be overridden for the derived type by giving an explicit scalar | |
11272 | storage order for it. However, for a record extension, the derived type must | |
11273 | have the same scalar storage order as the parent type. | |
11274 | ||
11275 | A component of a record type that is itself a record or an array and that does | |
11276 | not start and end on a byte boundary must have have the same scalar storage | |
11277 | order as the record type. A component of a bit-packed array type that is itself | |
11278 | a record or an array must have the same scalar storage order as the array type. | |
11279 | ||
11280 | No component of a type that has an explicit @code{Scalar_Storage_Order} | |
11281 | attribute definition may be aliased. | |
11282 | ||
11283 | A confirming @code{Scalar_Storage_Order} attribute definition clause (i.e. | |
11284 | with a value equal to @code{System.Default_Bit_Order}) has no effect. | |
11285 | ||
11286 | If the opposite storage order is specified, then whenever the value of | |
11287 | a scalar component of an object of type @code{S} is read, the storage | |
11288 | elements of the enclosing machine scalar are first reversed (before | |
11289 | retrieving the component value, possibly applying some shift and mask | |
11290 | operatings on the enclosing machine scalar), and the opposite operation | |
11291 | is done for writes. | |
11292 | ||
11293 | In that case, the restrictions set forth in 13.5.1(10.3/2) for scalar components | |
11294 | are relaxed. Instead, the following rules apply: | |
11295 | ||
11296 | ||
11297 | @itemize * | |
11298 | ||
11299 | @item | |
11300 | the underlying storage elements are those at positions | |
11301 | @code{(position + first_bit / storage_element_size) .. (position + (last_bit + storage_element_size - 1) / storage_element_size)} | |
11302 | ||
11303 | @item | |
11304 | the sequence of underlying storage elements shall have | |
11305 | a size no greater than the largest machine scalar | |
11306 | ||
11307 | @item | |
11308 | the enclosing machine scalar is defined as the smallest machine | |
11309 | scalar starting at a position no greater than | |
11310 | @code{position + first_bit / storage_element_size} and covering | |
11311 | storage elements at least up to @code{position + (last_bit + storage_element_size - 1) / storage_element_size} | |
11312 | ||
11313 | @item | |
11314 | the position of the component is interpreted relative to that machine | |
11315 | scalar. | |
11316 | @end itemize | |
11317 | ||
11318 | If no scalar storage order is specified for a type (either directly, or by | |
11319 | inheritance in the case of a derived type), then the default is normally | |
11320 | the native ordering of the target, but this default can be overridden using | |
11321 | pragma @code{Default_Scalar_Storage_Order}. | |
11322 | ||
11323 | If a component of @code{T} is itself of a record or array type, the specfied | |
11324 | @code{Scalar_Storage_Order} does `not' apply to that nested type: an explicit | |
11325 | attribute definition clause must be provided for the component type as well | |
11326 | if desired. | |
11327 | ||
11328 | Representation changes that explicitly or implicitly toggle the scalar storage | |
11329 | order are not supported and may result in erroneous execution of the program, | |
11330 | except when performed by means of an instance of @code{Ada.Unchecked_Conversion}. | |
11331 | ||
11332 | In particular, overlays are not supported and a warning is given for them: | |
11333 | ||
11334 | @example | |
11335 | type Rec_LE is record | |
11336 | I : Integer; | |
11337 | end record; | |
11338 | ||
11339 | for Rec_LE use record | |
11340 | I at 0 range 0 .. 31; | |
11341 | end record; | |
11342 | ||
11343 | for Rec_LE'Bit_Order use System.Low_Order_First; | |
11344 | for Rec_LE'Scalar_Storage_Order use System.Low_Order_First; | |
11345 | ||
11346 | type Rec_BE is record | |
11347 | I : Integer; | |
11348 | end record; | |
11349 | ||
11350 | for Rec_BE use record | |
11351 | I at 0 range 0 .. 31; | |
11352 | end record; | |
11353 | ||
11354 | for Rec_BE'Bit_Order use System.High_Order_First; | |
11355 | for Rec_BE'Scalar_Storage_Order use System.High_Order_First; | |
11356 | ||
11357 | R_LE : Rec_LE; | |
11358 | ||
11359 | R_BE : Rec_BE; | |
11360 | for R_BE'Address use R_LE'Address; | |
11361 | @end example | |
11362 | ||
11363 | @code{warning: overlay changes scalar storage order [enabled by default]} | |
11364 | ||
11365 | In most cases, such representation changes ought to be replaced by an | |
11366 | instantiation of a function or procedure provided by @code{GNAT.Byte_Swapping}. | |
11367 | ||
11368 | Note that the scalar storage order only affects the in-memory data | |
11369 | representation. It has no effect on the representation used by stream | |
11370 | attributes. | |
11371 | ||
11372 | Note that debuggers may be unable to display the correct value of scalar | |
11373 | components of a type for which the opposite storage order is specified. | |
11374 | ||
11375 | @node Attribute Simple_Storage_Pool,Attribute Small,Attribute Scalar_Storage_Order,Implementation Defined Attributes | |
04d6c745 | 11376 | @anchor{gnat_rm/implementation_defined_attributes attribute-simple-storage-pool}@anchor{e9}@anchor{gnat_rm/implementation_defined_attributes id5}@anchor{1a3} |
64d5610f ML |
11377 | @section Attribute Simple_Storage_Pool |
11378 | ||
11379 | ||
11380 | @geindex Storage pool | |
11381 | @geindex simple | |
11382 | ||
11383 | @geindex Simple storage pool | |
11384 | ||
11385 | @geindex Simple_Storage_Pool | |
11386 | ||
11387 | For every nonformal, nonderived access-to-object type @code{Acc}, the | |
11388 | representation attribute @code{Simple_Storage_Pool} may be specified | |
11389 | via an attribute_definition_clause (or by specifying the equivalent aspect): | |
11390 | ||
11391 | @example | |
11392 | My_Pool : My_Simple_Storage_Pool_Type; | |
11393 | ||
11394 | type Acc is access My_Data_Type; | |
11395 | ||
11396 | for Acc'Simple_Storage_Pool use My_Pool; | |
11397 | @end example | |
11398 | ||
11399 | The name given in an attribute_definition_clause for the | |
11400 | @code{Simple_Storage_Pool} attribute shall denote a variable of | |
11401 | a ‘simple storage pool type’ (see pragma @cite{Simple_Storage_Pool_Type}). | |
11402 | ||
11403 | The use of this attribute is only allowed for a prefix denoting a type | |
11404 | for which it has been specified. The type of the attribute is the type | |
11405 | of the variable specified as the simple storage pool of the access type, | |
11406 | and the attribute denotes that variable. | |
11407 | ||
11408 | It is illegal to specify both @code{Storage_Pool} and @code{Simple_Storage_Pool} | |
11409 | for the same access type. | |
11410 | ||
11411 | If the @code{Simple_Storage_Pool} attribute has been specified for an access | |
11412 | type, then applying the @code{Storage_Pool} attribute to the type is flagged | |
11413 | with a warning and its evaluation raises the exception @code{Program_Error}. | |
11414 | ||
11415 | If the Simple_Storage_Pool attribute has been specified for an access | |
11416 | type @code{S}, then the evaluation of the attribute @code{S'Storage_Size} | |
11417 | returns the result of calling @code{Storage_Size (S'Simple_Storage_Pool)}, | |
11418 | which is intended to indicate the number of storage elements reserved for | |
11419 | the simple storage pool. If the Storage_Size function has not been defined | |
11420 | for the simple storage pool type, then this attribute returns zero. | |
11421 | ||
11422 | If an access type @code{S} has a specified simple storage pool of type | |
11423 | @code{SSP}, then the evaluation of an allocator for that access type calls | |
11424 | the primitive @code{Allocate} procedure for type @code{SSP}, passing | |
11425 | @code{S'Simple_Storage_Pool} as the pool parameter. The detailed | |
11426 | semantics of such allocators is the same as those defined for allocators | |
11427 | in section 13.11 of the @cite{Ada Reference Manual}, with the term | |
11428 | `simple storage pool' substituted for `storage pool'. | |
11429 | ||
11430 | If an access type @code{S} has a specified simple storage pool of type | |
11431 | @code{SSP}, then a call to an instance of the @code{Ada.Unchecked_Deallocation} | |
11432 | for that access type invokes the primitive @code{Deallocate} procedure | |
11433 | for type @code{SSP}, passing @code{S'Simple_Storage_Pool} as the pool | |
11434 | parameter. The detailed semantics of such unchecked deallocations is the same | |
11435 | as defined in section 13.11.2 of the Ada Reference Manual, except that the | |
11436 | term `simple storage pool' is substituted for `storage pool'. | |
11437 | ||
11438 | @node Attribute Small,Attribute Small_Denominator,Attribute Simple_Storage_Pool,Implementation Defined Attributes | |
04d6c745 | 11439 | @anchor{gnat_rm/implementation_defined_attributes attribute-small}@anchor{1a4} |
64d5610f ML |
11440 | @section Attribute Small |
11441 | ||
11442 | ||
11443 | @geindex Ada 83 attributes | |
11444 | ||
11445 | @geindex Small | |
11446 | ||
11447 | The @code{Small} attribute is defined in Ada 95 (and Ada 2005) only for | |
11448 | fixed-point types. | |
11449 | GNAT also allows this attribute to be applied to floating-point types | |
11450 | for compatibility with Ada 83. See | |
11451 | the Ada 83 reference manual for an exact description of the semantics of | |
11452 | this attribute when applied to floating-point types. | |
11453 | ||
11454 | @node Attribute Small_Denominator,Attribute Small_Numerator,Attribute Small,Implementation Defined Attributes | |
04d6c745 | 11455 | @anchor{gnat_rm/implementation_defined_attributes attribute-small-denominator}@anchor{1a5} |
64d5610f ML |
11456 | @section Attribute Small_Denominator |
11457 | ||
11458 | ||
11459 | @geindex Small | |
11460 | ||
11461 | @geindex Small_Denominator | |
11462 | ||
11463 | @code{typ'Small_Denominator} for any fixed-point subtype @cite{typ} yields the | |
11464 | denominator in the representation of @code{typ'Small} as a rational number | |
11465 | with coprime factors (i.e. as an irreducible fraction). | |
11466 | ||
11467 | @node Attribute Small_Numerator,Attribute Storage_Unit,Attribute Small_Denominator,Implementation Defined Attributes | |
04d6c745 | 11468 | @anchor{gnat_rm/implementation_defined_attributes attribute-small-numerator}@anchor{1a6} |
64d5610f ML |
11469 | @section Attribute Small_Numerator |
11470 | ||
11471 | ||
11472 | @geindex Small | |
11473 | ||
11474 | @geindex Small_Numerator | |
11475 | ||
11476 | @code{typ'Small_Numerator} for any fixed-point subtype @cite{typ} yields the | |
11477 | numerator in the representation of @code{typ'Small} as a rational number | |
11478 | with coprime factors (i.e. as an irreducible fraction). | |
11479 | ||
11480 | @node Attribute Storage_Unit,Attribute Stub_Type,Attribute Small_Numerator,Implementation Defined Attributes | |
04d6c745 | 11481 | @anchor{gnat_rm/implementation_defined_attributes attribute-storage-unit}@anchor{1a7} |
64d5610f ML |
11482 | @section Attribute Storage_Unit |
11483 | ||
11484 | ||
11485 | @geindex Storage_Unit | |
11486 | ||
11487 | @code{Standard'Storage_Unit} (@code{Standard} is the only allowed | |
11488 | prefix) provides the same value as @code{System.Storage_Unit}. | |
11489 | ||
11490 | @node Attribute Stub_Type,Attribute System_Allocator_Alignment,Attribute Storage_Unit,Implementation Defined Attributes | |
04d6c745 | 11491 | @anchor{gnat_rm/implementation_defined_attributes attribute-stub-type}@anchor{1a8} |
64d5610f ML |
11492 | @section Attribute Stub_Type |
11493 | ||
11494 | ||
11495 | @geindex Stub_Type | |
11496 | ||
11497 | The GNAT implementation of remote access-to-classwide types is | |
11498 | organized as described in AARM section E.4 (20.t): a value of an RACW type | |
11499 | (designating a remote object) is represented as a normal access | |
11500 | value, pointing to a “stub” object which in turn contains the | |
11501 | necessary information to contact the designated remote object. A | |
11502 | call on any dispatching operation of such a stub object does the | |
11503 | remote call, if necessary, using the information in the stub object | |
11504 | to locate the target partition, etc. | |
11505 | ||
11506 | For a prefix @code{T} that denotes a remote access-to-classwide type, | |
11507 | @code{T'Stub_Type} denotes the type of the corresponding stub objects. | |
11508 | ||
11509 | By construction, the layout of @code{T'Stub_Type} is identical to that of | |
11510 | type @code{RACW_Stub_Type} declared in the internal implementation-defined | |
11511 | unit @code{System.Partition_Interface}. Use of this attribute will create | |
11512 | an implicit dependency on this unit. | |
11513 | ||
11514 | @node Attribute System_Allocator_Alignment,Attribute Target_Name,Attribute Stub_Type,Implementation Defined Attributes | |
04d6c745 | 11515 | @anchor{gnat_rm/implementation_defined_attributes attribute-system-allocator-alignment}@anchor{1a9} |
64d5610f ML |
11516 | @section Attribute System_Allocator_Alignment |
11517 | ||
11518 | ||
11519 | @geindex Alignment | |
11520 | @geindex allocator | |
11521 | ||
11522 | @geindex System_Allocator_Alignment | |
11523 | ||
11524 | @code{Standard'System_Allocator_Alignment} (@code{Standard} is the only | |
11525 | allowed prefix) provides the observable guaranteed to be honored by | |
11526 | the system allocator (malloc). This is a static value that can be used | |
11527 | in user storage pools based on malloc either to reject allocation | |
11528 | with alignment too large or to enable a realignment circuitry if the | |
11529 | alignment request is larger than this value. | |
11530 | ||
11531 | @node Attribute Target_Name,Attribute To_Address,Attribute System_Allocator_Alignment,Implementation Defined Attributes | |
04d6c745 | 11532 | @anchor{gnat_rm/implementation_defined_attributes attribute-target-name}@anchor{1aa} |
64d5610f ML |
11533 | @section Attribute Target_Name |
11534 | ||
11535 | ||
11536 | @geindex Target_Name | |
11537 | ||
11538 | @code{Standard'Target_Name} (@code{Standard} is the only allowed | |
11539 | prefix) provides a static string value that identifies the target | |
11540 | for the current compilation. For GCC implementations, this is the | |
11541 | standard gcc target name without the terminating slash (for | |
11542 | example, GNAT 5.0 on windows yields “i586-pc-mingw32msv”). | |
11543 | ||
11544 | @node Attribute To_Address,Attribute To_Any,Attribute Target_Name,Implementation Defined Attributes | |
04d6c745 | 11545 | @anchor{gnat_rm/implementation_defined_attributes attribute-to-address}@anchor{1ab} |
64d5610f ML |
11546 | @section Attribute To_Address |
11547 | ||
11548 | ||
11549 | @geindex To_Address | |
11550 | ||
11551 | The @code{System'To_Address} | |
11552 | (@code{System} is the only allowed prefix) | |
11553 | denotes a function identical to | |
11554 | @code{System.Storage_Elements.To_Address} except that | |
11555 | it is a static attribute. This means that if its argument is | |
11556 | a static expression, then the result of the attribute is a | |
11557 | static expression. This means that such an expression can be | |
11558 | used in contexts (e.g., preelaborable packages) which require a | |
11559 | static expression and where the function call could not be used | |
11560 | (since the function call is always nonstatic, even if its | |
11561 | argument is static). The argument must be in the range | |
11562 | -(2**(m-1)) .. 2**m-1, where m is the memory size | |
11563 | (typically 32 or 64). Negative values are intepreted in a | |
11564 | modular manner (e.g., -1 means the same as 16#FFFF_FFFF# on | |
11565 | a 32 bits machine). | |
11566 | ||
11567 | @node Attribute To_Any,Attribute Type_Class,Attribute To_Address,Implementation Defined Attributes | |
04d6c745 | 11568 | @anchor{gnat_rm/implementation_defined_attributes attribute-to-any}@anchor{1ac} |
64d5610f ML |
11569 | @section Attribute To_Any |
11570 | ||
11571 | ||
11572 | @geindex To_Any | |
11573 | ||
11574 | This internal attribute is used for the generation of remote subprogram | |
11575 | stubs in the context of the Distributed Systems Annex. | |
11576 | ||
11577 | @node Attribute Type_Class,Attribute Type_Key,Attribute To_Any,Implementation Defined Attributes | |
04d6c745 | 11578 | @anchor{gnat_rm/implementation_defined_attributes attribute-type-class}@anchor{1ad} |
64d5610f ML |
11579 | @section Attribute Type_Class |
11580 | ||
11581 | ||
11582 | @geindex Type_Class | |
11583 | ||
11584 | @code{typ'Type_Class} for any type or subtype @cite{typ} yields | |
11585 | the value of the type class for the full type of @cite{typ}. If | |
11586 | @cite{typ} is a generic formal type, the value is the value for the | |
11587 | corresponding actual subtype. The value of this attribute is of type | |
11588 | @code{System.Aux_DEC.Type_Class}, which has the following definition: | |
11589 | ||
11590 | @example | |
11591 | type Type_Class is | |
11592 | (Type_Class_Enumeration, | |
11593 | Type_Class_Integer, | |
11594 | Type_Class_Fixed_Point, | |
11595 | Type_Class_Floating_Point, | |
11596 | Type_Class_Array, | |
11597 | Type_Class_Record, | |
11598 | Type_Class_Access, | |
11599 | Type_Class_Task, | |
11600 | Type_Class_Address); | |
11601 | @end example | |
11602 | ||
11603 | Protected types yield the value @code{Type_Class_Task}, which thus | |
11604 | applies to all concurrent types. This attribute is designed to | |
11605 | be compatible with the DEC Ada 83 attribute of the same name. | |
11606 | ||
11607 | @node Attribute Type_Key,Attribute TypeCode,Attribute Type_Class,Implementation Defined Attributes | |
04d6c745 | 11608 | @anchor{gnat_rm/implementation_defined_attributes attribute-type-key}@anchor{1ae} |
64d5610f ML |
11609 | @section Attribute Type_Key |
11610 | ||
11611 | ||
11612 | @geindex Type_Key | |
11613 | ||
11614 | The @code{Type_Key} attribute is applicable to a type or subtype and | |
11615 | yields a value of type Standard.String containing encoded information | |
11616 | about the type or subtype. This provides improved compatibility with | |
11617 | other implementations that support this attribute. | |
11618 | ||
11619 | @node Attribute TypeCode,Attribute Unconstrained_Array,Attribute Type_Key,Implementation Defined Attributes | |
04d6c745 | 11620 | @anchor{gnat_rm/implementation_defined_attributes attribute-typecode}@anchor{1af} |
64d5610f ML |
11621 | @section Attribute TypeCode |
11622 | ||
11623 | ||
11624 | @geindex TypeCode | |
11625 | ||
11626 | This internal attribute is used for the generation of remote subprogram | |
11627 | stubs in the context of the Distributed Systems Annex. | |
11628 | ||
11629 | @node Attribute Unconstrained_Array,Attribute Universal_Literal_String,Attribute TypeCode,Implementation Defined Attributes | |
04d6c745 | 11630 | @anchor{gnat_rm/implementation_defined_attributes attribute-unconstrained-array}@anchor{1b0} |
64d5610f ML |
11631 | @section Attribute Unconstrained_Array |
11632 | ||
11633 | ||
11634 | @geindex Unconstrained_Array | |
11635 | ||
11636 | The @code{Unconstrained_Array} attribute can be used with a prefix that | |
11637 | denotes any type or subtype. It is a static attribute that yields | |
11638 | @code{True} if the prefix designates an unconstrained array, | |
11639 | and @code{False} otherwise. In a generic instance, the result is | |
11640 | still static, and yields the result of applying this test to the | |
11641 | generic actual. | |
11642 | ||
11643 | @node Attribute Universal_Literal_String,Attribute Unrestricted_Access,Attribute Unconstrained_Array,Implementation Defined Attributes | |
04d6c745 | 11644 | @anchor{gnat_rm/implementation_defined_attributes attribute-universal-literal-string}@anchor{1b1} |
64d5610f ML |
11645 | @section Attribute Universal_Literal_String |
11646 | ||
11647 | ||
11648 | @geindex Named numbers | |
11649 | @geindex representation of | |
11650 | ||
11651 | @geindex Universal_Literal_String | |
11652 | ||
11653 | The prefix of @code{Universal_Literal_String} must be a named | |
11654 | number. The static result is the string consisting of the characters of | |
11655 | the number as defined in the original source. This allows the user | |
11656 | program to access the actual text of named numbers without intermediate | |
11657 | conversions and without the need to enclose the strings in quotes (which | |
11658 | would preclude their use as numbers). | |
11659 | ||
11660 | For example, the following program prints the first 50 digits of pi: | |
11661 | ||
11662 | @example | |
11663 | with Text_IO; use Text_IO; | |
11664 | with Ada.Numerics; | |
11665 | procedure Pi is | |
11666 | begin | |
11667 | Put (Ada.Numerics.Pi'Universal_Literal_String); | |
11668 | end; | |
11669 | @end example | |
11670 | ||
11671 | @node Attribute Unrestricted_Access,Attribute Update,Attribute Universal_Literal_String,Implementation Defined Attributes | |
04d6c745 | 11672 | @anchor{gnat_rm/implementation_defined_attributes attribute-unrestricted-access}@anchor{1b2} |
64d5610f ML |
11673 | @section Attribute Unrestricted_Access |
11674 | ||
11675 | ||
11676 | @geindex Access | |
11677 | @geindex unrestricted | |
11678 | ||
11679 | @geindex Unrestricted_Access | |
11680 | ||
11681 | The @code{Unrestricted_Access} attribute is similar to @code{Access} | |
11682 | except that all accessibility and aliased view checks are omitted. This | |
11683 | is a user-beware attribute. | |
11684 | ||
11685 | For objects, it is similar to @code{Address}, for which it is a | |
11686 | desirable replacement where the value desired is an access type. | |
11687 | In other words, its effect is similar to first applying the | |
11688 | @code{Address} attribute and then doing an unchecked conversion to a | |
11689 | desired access type. | |
11690 | ||
11691 | For subprograms, @code{P'Unrestricted_Access} may be used where | |
11692 | @code{P'Access} would be illegal, to construct a value of a | |
11693 | less-nested named access type that designates a more-nested | |
11694 | subprogram. This value may be used in indirect calls, so long as the | |
11695 | more-nested subprogram still exists; once the subprogram containing it | |
11696 | has returned, such calls are erroneous. For example: | |
11697 | ||
11698 | @example | |
11699 | package body P is | |
11700 | ||
11701 | type Less_Nested is not null access procedure; | |
11702 | Global : Less_Nested; | |
11703 | ||
11704 | procedure P1 is | |
11705 | begin | |
11706 | Global.all; | |
11707 | end P1; | |
11708 | ||
11709 | procedure P2 is | |
11710 | Local_Var : Integer; | |
11711 | ||
11712 | procedure More_Nested is | |
11713 | begin | |
11714 | ... Local_Var ... | |
11715 | end More_Nested; | |
11716 | begin | |
11717 | Global := More_Nested'Unrestricted_Access; | |
11718 | P1; | |
11719 | end P2; | |
11720 | ||
11721 | end P; | |
11722 | @end example | |
11723 | ||
11724 | When P1 is called from P2, the call via Global is OK, but if P1 were | |
11725 | called after P2 returns, it would be an erroneous use of a dangling | |
11726 | pointer. | |
11727 | ||
11728 | For objects, it is possible to use @code{Unrestricted_Access} for any | |
11729 | type. However, if the result is of an access-to-unconstrained array | |
11730 | subtype, then the resulting pointer has the same scope as the context | |
11731 | of the attribute, and must not be returned to some enclosing scope. | |
11732 | For instance, if a function uses @code{Unrestricted_Access} to create | |
11733 | an access-to-unconstrained-array and returns that value to the caller, | |
11734 | the result will involve dangling pointers. In addition, it is only | |
11735 | valid to create pointers to unconstrained arrays using this attribute | |
11736 | if the pointer has the normal default ‘fat’ representation where a | |
11737 | pointer has two components, one points to the array and one points to | |
11738 | the bounds. If a size clause is used to force ‘thin’ representation | |
11739 | for a pointer to unconstrained where there is only space for a single | |
11740 | pointer, then the resulting pointer is not usable. | |
11741 | ||
11742 | In the simple case where a direct use of Unrestricted_Access attempts | |
11743 | to make a thin pointer for a non-aliased object, the compiler will | |
11744 | reject the use as illegal, as shown in the following example: | |
11745 | ||
11746 | @example | |
11747 | with System; use System; | |
11748 | procedure SliceUA2 is | |
11749 | type A is access all String; | |
11750 | for A'Size use Standard'Address_Size; | |
11751 | ||
11752 | procedure P (Arg : A) is | |
11753 | begin | |
11754 | null; | |
11755 | end P; | |
11756 | ||
11757 | X : String := "hello world!"; | |
11758 | X2 : aliased String := "hello world!"; | |
11759 | ||
11760 | AV : A := X'Unrestricted_Access; -- ERROR | |
11761 | | | |
11762 | >>> illegal use of Unrestricted_Access attribute | |
11763 | >>> attempt to generate thin pointer to unaliased object | |
11764 | ||
11765 | begin | |
11766 | P (X'Unrestricted_Access); -- ERROR | |
11767 | | | |
11768 | >>> illegal use of Unrestricted_Access attribute | |
11769 | >>> attempt to generate thin pointer to unaliased object | |
11770 | ||
11771 | P (X(7 .. 12)'Unrestricted_Access); -- ERROR | |
11772 | | | |
11773 | >>> illegal use of Unrestricted_Access attribute | |
11774 | >>> attempt to generate thin pointer to unaliased object | |
11775 | ||
11776 | P (X2'Unrestricted_Access); -- OK | |
11777 | end; | |
11778 | @end example | |
11779 | ||
11780 | but other cases cannot be detected by the compiler, and are | |
11781 | considered to be erroneous. Consider the following example: | |
11782 | ||
11783 | @example | |
11784 | with System; use System; | |
11785 | with System; use System; | |
11786 | procedure SliceUA is | |
11787 | type AF is access all String; | |
11788 | ||
11789 | type A is access all String; | |
11790 | for A'Size use Standard'Address_Size; | |
11791 | ||
11792 | procedure P (Arg : A) is | |
11793 | begin | |
11794 | if Arg'Length /= 6 then | |
11795 | raise Program_Error; | |
11796 | end if; | |
11797 | end P; | |
11798 | ||
11799 | X : String := "hello world!"; | |
11800 | Y : AF := X (7 .. 12)'Unrestricted_Access; | |
11801 | ||
11802 | begin | |
11803 | P (A (Y)); | |
11804 | end; | |
11805 | @end example | |
11806 | ||
11807 | A normal unconstrained array value | |
11808 | or a constrained array object marked as aliased has the bounds in memory | |
11809 | just before the array, so a thin pointer can retrieve both the data and | |
11810 | the bounds. But in this case, the non-aliased object @code{X} does not have the | |
11811 | bounds before the string. If the size clause for type @code{A} | |
11812 | were not present, then the pointer | |
11813 | would be a fat pointer, where one component is a pointer to the bounds, | |
11814 | and all would be well. But with the size clause present, the conversion from | |
11815 | fat pointer to thin pointer in the call loses the bounds, and so this | |
11816 | is erroneous, and the program likely raises a @code{Program_Error} exception. | |
11817 | ||
11818 | In general, it is advisable to completely | |
11819 | avoid mixing the use of thin pointers and the use of | |
11820 | @code{Unrestricted_Access} where the designated type is an | |
11821 | unconstrained array. The use of thin pointers should be restricted to | |
11822 | cases of porting legacy code that implicitly assumes the size of pointers, | |
11823 | and such code should not in any case be using this attribute. | |
11824 | ||
11825 | Another erroneous situation arises if the attribute is | |
11826 | applied to a constant. The resulting pointer can be used to access the | |
11827 | constant, but the effect of trying to modify a constant in this manner | |
11828 | is not well-defined. Consider this example: | |
11829 | ||
11830 | @example | |
11831 | P : constant Integer := 4; | |
11832 | type R is access all Integer; | |
11833 | RV : R := P'Unrestricted_Access; | |
11834 | .. | |
11835 | RV.all := 3; | |
11836 | @end example | |
11837 | ||
11838 | Here we attempt to modify the constant P from 4 to 3, but the compiler may | |
11839 | or may not notice this attempt, and subsequent references to P may yield | |
11840 | either the value 3 or the value 4 or the assignment may blow up if the | |
11841 | compiler decides to put P in read-only memory. One particular case where | |
11842 | @code{Unrestricted_Access} can be used in this way is to modify the | |
11843 | value of an @code{in} parameter: | |
11844 | ||
11845 | @example | |
11846 | procedure K (S : in String) is | |
11847 | type R is access all Character; | |
11848 | RV : R := S (3)'Unrestricted_Access; | |
11849 | begin | |
11850 | RV.all := 'a'; | |
11851 | end; | |
11852 | @end example | |
11853 | ||
11854 | In general this is a risky approach. It may appear to “work” but such uses of | |
11855 | @code{Unrestricted_Access} are potentially non-portable, even from one version | |
11856 | of GNAT to another, so are best avoided if possible. | |
11857 | ||
11858 | @node Attribute Update,Attribute Valid_Value,Attribute Unrestricted_Access,Implementation Defined Attributes | |
04d6c745 | 11859 | @anchor{gnat_rm/implementation_defined_attributes attribute-update}@anchor{1b3} |
64d5610f ML |
11860 | @section Attribute Update |
11861 | ||
11862 | ||
11863 | @geindex Update | |
11864 | ||
11865 | The @code{Update} attribute creates a copy of an array or record value | |
11866 | with one or more modified components. The syntax is: | |
11867 | ||
11868 | @example | |
11869 | PREFIX'Update ( RECORD_COMPONENT_ASSOCIATION_LIST ) | |
11870 | PREFIX'Update ( ARRAY_COMPONENT_ASSOCIATION @{, ARRAY_COMPONENT_ASSOCIATION @} ) | |
11871 | PREFIX'Update ( MULTIDIMENSIONAL_ARRAY_COMPONENT_ASSOCIATION | |
11872 | @{, MULTIDIMENSIONAL_ARRAY_COMPONENT_ASSOCIATION @} ) | |
11873 | ||
11874 | MULTIDIMENSIONAL_ARRAY_COMPONENT_ASSOCIATION ::= INDEX_EXPRESSION_LIST_LIST => EXPRESSION | |
11875 | INDEX_EXPRESSION_LIST_LIST ::= INDEX_EXPRESSION_LIST @{| INDEX_EXPRESSION_LIST @} | |
11876 | INDEX_EXPRESSION_LIST ::= ( EXPRESSION @{, EXPRESSION @} ) | |
11877 | @end example | |
11878 | ||
11879 | where @code{PREFIX} is the name of an array or record object, the | |
11880 | association list in parentheses does not contain an @code{others} | |
11881 | choice and the box symbol @code{<>} may not appear in any | |
11882 | expression. The effect is to yield a copy of the array or record value | |
11883 | which is unchanged apart from the components mentioned in the | |
11884 | association list, which are changed to the indicated value. The | |
11885 | original value of the array or record value is not affected. For | |
11886 | example: | |
11887 | ||
11888 | @example | |
11889 | type Arr is Array (1 .. 5) of Integer; | |
11890 | ... | |
11891 | Avar1 : Arr := (1,2,3,4,5); | |
11892 | Avar2 : Arr := Avar1'Update (2 => 10, 3 .. 4 => 20); | |
11893 | @end example | |
11894 | ||
11895 | yields a value for @code{Avar2} of 1,10,20,20,5 with @code{Avar1} | |
11896 | begin unmodified. Similarly: | |
11897 | ||
11898 | @example | |
11899 | type Rec is A, B, C : Integer; | |
11900 | ... | |
11901 | Rvar1 : Rec := (A => 1, B => 2, C => 3); | |
11902 | Rvar2 : Rec := Rvar1'Update (B => 20); | |
11903 | @end example | |
11904 | ||
11905 | yields a value for @code{Rvar2} of (A => 1, B => 20, C => 3), | |
11906 | with @code{Rvar1} being unmodifed. | |
11907 | Note that the value of the attribute reference is computed | |
11908 | completely before it is used. This means that if you write: | |
11909 | ||
11910 | @example | |
11911 | Avar1 := Avar1'Update (1 => 10, 2 => Function_Call); | |
11912 | @end example | |
11913 | ||
11914 | then the value of @code{Avar1} is not modified if @code{Function_Call} | |
11915 | raises an exception, unlike the effect of a series of direct assignments | |
11916 | to elements of @code{Avar1}. In general this requires that | |
11917 | two extra complete copies of the object are required, which should be | |
11918 | kept in mind when considering efficiency. | |
11919 | ||
11920 | The @code{Update} attribute cannot be applied to prefixes of a limited | |
11921 | type, and cannot reference discriminants in the case of a record type. | |
11922 | The accessibility level of an Update attribute result object is defined | |
11923 | as for an aggregate. | |
11924 | ||
11925 | In the record case, no component can be mentioned more than once. In | |
11926 | the array case, two overlapping ranges can appear in the association list, | |
11927 | in which case the modifications are processed left to right. | |
11928 | ||
11929 | Multi-dimensional arrays can be modified, as shown by this example: | |
11930 | ||
11931 | @example | |
11932 | A : array (1 .. 10, 1 .. 10) of Integer; | |
11933 | .. | |
11934 | A := A'Update ((1, 2) => 20, (3, 4) => 30); | |
11935 | @end example | |
11936 | ||
11937 | which changes element (1,2) to 20 and (3,4) to 30. | |
11938 | ||
11939 | @node Attribute Valid_Value,Attribute Valid_Scalars,Attribute Update,Implementation Defined Attributes | |
04d6c745 | 11940 | @anchor{gnat_rm/implementation_defined_attributes attribute-valid-value}@anchor{1b4} |
64d5610f ML |
11941 | @section Attribute Valid_Value |
11942 | ||
11943 | ||
11944 | @geindex Valid_Value | |
11945 | ||
11946 | The @code{'Valid_Value} attribute is defined for enumeration types other than | |
11947 | those in package Standard. This attribute is a function that takes | |
11948 | a String, and returns Boolean. @code{T'Valid_Value (S)} returns True | |
11949 | if and only if @code{T'Value (S)} would not raise Constraint_Error. | |
11950 | ||
11951 | @node Attribute Valid_Scalars,Attribute VADS_Size,Attribute Valid_Value,Implementation Defined Attributes | |
04d6c745 | 11952 | @anchor{gnat_rm/implementation_defined_attributes attribute-valid-scalars}@anchor{1b5} |
64d5610f ML |
11953 | @section Attribute Valid_Scalars |
11954 | ||
11955 | ||
11956 | @geindex Valid_Scalars | |
11957 | ||
11958 | The @code{'Valid_Scalars} attribute is intended to make it easier to check the | |
11959 | validity of scalar subcomponents of composite objects. The attribute is defined | |
11960 | for any prefix @code{P} which denotes an object. Prefix @code{P} can be any type | |
11961 | except for tagged private or @code{Unchecked_Union} types. The value of the | |
11962 | attribute is of type @code{Boolean}. | |
11963 | ||
11964 | @code{P'Valid_Scalars} yields @code{True} if and only if the evaluation of | |
11965 | @code{C'Valid} yields @code{True} for every scalar subcomponent @code{C} of @code{P}, or if | |
11966 | @code{P} has no scalar subcomponents. Attribute @code{'Valid_Scalars} is equivalent | |
11967 | to attribute @code{'Valid} for scalar types. | |
11968 | ||
11969 | It is not specified in what order the subcomponents are checked, nor whether | |
11970 | any more are checked after any one of them is determined to be invalid. If the | |
11971 | prefix @code{P} is of a class-wide type @code{T'Class} (where @code{T} is the associated | |
11972 | specific type), or if the prefix @code{P} is of a specific tagged type @code{T}, then | |
11973 | only the subcomponents of @code{T} are checked; in other words, components of | |
11974 | extensions of @code{T} are not checked even if @code{T'Class (P)'Tag /= T'Tag}. | |
11975 | ||
11976 | The compiler will issue a warning if it can be determined at compile time that | |
11977 | the prefix of the attribute has no scalar subcomponents. | |
11978 | ||
11979 | Note: @code{Valid_Scalars} can generate a lot of code, especially in the case of | |
11980 | a large variant record. If the attribute is called in many places in the same | |
11981 | program applied to objects of the same type, it can reduce program size to | |
11982 | write a function with a single use of the attribute, and then call that | |
11983 | function from multiple places. | |
11984 | ||
11985 | @node Attribute VADS_Size,Attribute Value_Size,Attribute Valid_Scalars,Implementation Defined Attributes | |
04d6c745 | 11986 | @anchor{gnat_rm/implementation_defined_attributes attribute-vads-size}@anchor{1b6} |
64d5610f ML |
11987 | @section Attribute VADS_Size |
11988 | ||
11989 | ||
11990 | @geindex Size | |
11991 | @geindex VADS compatibility | |
11992 | ||
11993 | @geindex VADS_Size | |
11994 | ||
11995 | The @code{'VADS_Size} attribute is intended to make it easier to port | |
11996 | legacy code which relies on the semantics of @code{'Size} as implemented | |
11997 | by the VADS Ada 83 compiler. GNAT makes a best effort at duplicating the | |
11998 | same semantic interpretation. In particular, @code{'VADS_Size} applied | |
11999 | to a predefined or other primitive type with no Size clause yields the | |
12000 | Object_Size (for example, @code{Natural'Size} is 32 rather than 31 on | |
12001 | typical machines). In addition @code{'VADS_Size} applied to an object | |
12002 | gives the result that would be obtained by applying the attribute to | |
12003 | the corresponding type. | |
12004 | ||
12005 | @node Attribute Value_Size,Attribute Wchar_T_Size,Attribute VADS_Size,Implementation Defined Attributes | |
04d6c745 | 12006 | @anchor{gnat_rm/implementation_defined_attributes attribute-value-size}@anchor{164}@anchor{gnat_rm/implementation_defined_attributes id6}@anchor{1b7} |
64d5610f ML |
12007 | @section Attribute Value_Size |
12008 | ||
12009 | ||
12010 | @geindex Size | |
12011 | @geindex setting for not-first subtype | |
12012 | ||
12013 | @geindex Value_Size | |
12014 | ||
12015 | @code{type'Value_Size} is the number of bits required to represent | |
12016 | a value of the given subtype. It is the same as @code{type'Size}, | |
12017 | but, unlike @code{Size}, may be set for non-first subtypes. | |
12018 | ||
12019 | @node Attribute Wchar_T_Size,Attribute Word_Size,Attribute Value_Size,Implementation Defined Attributes | |
04d6c745 | 12020 | @anchor{gnat_rm/implementation_defined_attributes attribute-wchar-t-size}@anchor{1b8} |
64d5610f ML |
12021 | @section Attribute Wchar_T_Size |
12022 | ||
12023 | ||
12024 | @geindex Wchar_T_Size | |
12025 | ||
12026 | @code{Standard'Wchar_T_Size} (@code{Standard} is the only allowed | |
12027 | prefix) provides the size in bits of the C @code{wchar_t} type | |
12028 | primarily for constructing the definition of this type in | |
12029 | package @code{Interfaces.C}. The result is a static constant. | |
12030 | ||
12031 | @node Attribute Word_Size,,Attribute Wchar_T_Size,Implementation Defined Attributes | |
04d6c745 | 12032 | @anchor{gnat_rm/implementation_defined_attributes attribute-word-size}@anchor{1b9} |
64d5610f ML |
12033 | @section Attribute Word_Size |
12034 | ||
12035 | ||
12036 | @geindex Word_Size | |
12037 | ||
12038 | @code{Standard'Word_Size} (@code{Standard} is the only allowed | |
12039 | prefix) provides the value @code{System.Word_Size}. The result is | |
12040 | a static constant. | |
12041 | ||
12042 | @node Standard and Implementation Defined Restrictions,Implementation Advice,Implementation Defined Attributes,Top | |
04d6c745 | 12043 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions doc}@anchor{1ba}@anchor{gnat_rm/standard_and_implementation_defined_restrictions id1}@anchor{1bb}@anchor{gnat_rm/standard_and_implementation_defined_restrictions standard-and-implementation-defined-restrictions}@anchor{9} |
64d5610f ML |
12044 | @chapter Standard and Implementation Defined Restrictions |
12045 | ||
12046 | ||
12047 | All Ada Reference Manual-defined Restriction identifiers are implemented: | |
12048 | ||
12049 | ||
12050 | @itemize * | |
12051 | ||
12052 | @item | |
12053 | language-defined restrictions (see 13.12.1) | |
12054 | ||
12055 | @item | |
12056 | tasking restrictions (see D.7) | |
12057 | ||
12058 | @item | |
12059 | high integrity restrictions (see H.4) | |
12060 | @end itemize | |
12061 | ||
12062 | GNAT implements additional restriction identifiers. All restrictions, whether | |
12063 | language defined or GNAT-specific, are listed in the following. | |
12064 | ||
12065 | @menu | |
12066 | * Partition-Wide Restrictions:: | |
12067 | * Program Unit Level Restrictions:: | |
12068 | ||
12069 | @end menu | |
12070 | ||
12071 | @node Partition-Wide Restrictions,Program Unit Level Restrictions,,Standard and Implementation Defined Restrictions | |
04d6c745 | 12072 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions id2}@anchor{1bc}@anchor{gnat_rm/standard_and_implementation_defined_restrictions partition-wide-restrictions}@anchor{1bd} |
64d5610f ML |
12073 | @section Partition-Wide Restrictions |
12074 | ||
12075 | ||
12076 | There are two separate lists of restriction identifiers. The first | |
12077 | set requires consistency throughout a partition (in other words, if the | |
12078 | restriction identifier is used for any compilation unit in the partition, | |
12079 | then all compilation units in the partition must obey the restriction). | |
12080 | ||
12081 | @menu | |
12082 | * Immediate_Reclamation:: | |
12083 | * Max_Asynchronous_Select_Nesting:: | |
12084 | * Max_Entry_Queue_Length:: | |
12085 | * Max_Protected_Entries:: | |
12086 | * Max_Select_Alternatives:: | |
12087 | * Max_Storage_At_Blocking:: | |
12088 | * Max_Task_Entries:: | |
12089 | * Max_Tasks:: | |
12090 | * No_Abort_Statements:: | |
12091 | * No_Access_Parameter_Allocators:: | |
12092 | * No_Access_Subprograms:: | |
12093 | * No_Allocators:: | |
12094 | * No_Anonymous_Allocators:: | |
12095 | * No_Asynchronous_Control:: | |
12096 | * No_Calendar:: | |
12097 | * No_Coextensions:: | |
12098 | * No_Default_Initialization:: | |
12099 | * No_Delay:: | |
12100 | * No_Dependence:: | |
12101 | * No_Direct_Boolean_Operators:: | |
12102 | * No_Dispatch:: | |
12103 | * No_Dispatching_Calls:: | |
12104 | * No_Dynamic_Attachment:: | |
12105 | * No_Dynamic_Priorities:: | |
12106 | * No_Entry_Calls_In_Elaboration_Code:: | |
12107 | * No_Enumeration_Maps:: | |
12108 | * No_Exception_Handlers:: | |
12109 | * No_Exception_Propagation:: | |
12110 | * No_Exception_Registration:: | |
12111 | * No_Exceptions:: | |
12112 | * No_Finalization:: | |
12113 | * No_Fixed_Point:: | |
12114 | * No_Floating_Point:: | |
12115 | * No_Implicit_Conditionals:: | |
12116 | * No_Implicit_Dynamic_Code:: | |
12117 | * No_Implicit_Heap_Allocations:: | |
12118 | * No_Implicit_Protected_Object_Allocations:: | |
12119 | * No_Implicit_Task_Allocations:: | |
12120 | * No_Initialize_Scalars:: | |
12121 | * No_IO:: | |
12122 | * No_Local_Allocators:: | |
12123 | * No_Local_Protected_Objects:: | |
12124 | * No_Local_Tagged_Types:: | |
12125 | * No_Local_Timing_Events:: | |
12126 | * No_Long_Long_Integers:: | |
12127 | * No_Multiple_Elaboration:: | |
12128 | * No_Nested_Finalization:: | |
12129 | * No_Protected_Type_Allocators:: | |
12130 | * No_Protected_Types:: | |
12131 | * No_Recursion:: | |
12132 | * No_Reentrancy:: | |
12133 | * No_Relative_Delay:: | |
12134 | * No_Requeue_Statements:: | |
12135 | * No_Secondary_Stack:: | |
12136 | * No_Select_Statements:: | |
12137 | * No_Specific_Termination_Handlers:: | |
12138 | * No_Specification_of_Aspect:: | |
12139 | * No_Standard_Allocators_After_Elaboration:: | |
12140 | * No_Standard_Storage_Pools:: | |
12141 | * No_Stream_Optimizations:: | |
12142 | * No_Streams:: | |
12143 | * No_Tagged_Type_Registration:: | |
12144 | * No_Task_Allocators:: | |
12145 | * No_Task_At_Interrupt_Priority:: | |
12146 | * No_Task_Attributes_Package:: | |
12147 | * No_Task_Hierarchy:: | |
12148 | * No_Task_Termination:: | |
12149 | * No_Tasking:: | |
12150 | * No_Terminate_Alternatives:: | |
12151 | * No_Unchecked_Access:: | |
12152 | * No_Unchecked_Conversion:: | |
12153 | * No_Unchecked_Deallocation:: | |
73918baf | 12154 | * No_Use_Of_Attribute:: |
64d5610f | 12155 | * No_Use_Of_Entity:: |
73918baf | 12156 | * No_Use_Of_Pragma:: |
64d5610f ML |
12157 | * Pure_Barriers:: |
12158 | * Simple_Barriers:: | |
12159 | * Static_Priorities:: | |
12160 | * Static_Storage_Size:: | |
12161 | ||
12162 | @end menu | |
12163 | ||
12164 | @node Immediate_Reclamation,Max_Asynchronous_Select_Nesting,,Partition-Wide Restrictions | |
04d6c745 | 12165 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions immediate-reclamation}@anchor{1be} |
64d5610f ML |
12166 | @subsection Immediate_Reclamation |
12167 | ||
12168 | ||
12169 | @geindex Immediate_Reclamation | |
12170 | ||
12171 | [RM H.4] This restriction ensures that, except for storage occupied by | |
12172 | objects created by allocators and not deallocated via unchecked | |
12173 | deallocation, any storage reserved at run time for an object is | |
12174 | immediately reclaimed when the object no longer exists. | |
12175 | ||
12176 | @node Max_Asynchronous_Select_Nesting,Max_Entry_Queue_Length,Immediate_Reclamation,Partition-Wide Restrictions | |
04d6c745 | 12177 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions max-asynchronous-select-nesting}@anchor{1bf} |
64d5610f ML |
12178 | @subsection Max_Asynchronous_Select_Nesting |
12179 | ||
12180 | ||
12181 | @geindex Max_Asynchronous_Select_Nesting | |
12182 | ||
12183 | [RM D.7] Specifies the maximum dynamic nesting level of asynchronous | |
12184 | selects. Violations of this restriction with a value of zero are | |
12185 | detected at compile time. Violations of this restriction with values | |
12186 | other than zero cause Storage_Error to be raised. | |
12187 | ||
12188 | @node Max_Entry_Queue_Length,Max_Protected_Entries,Max_Asynchronous_Select_Nesting,Partition-Wide Restrictions | |
04d6c745 | 12189 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions max-entry-queue-length}@anchor{1c0} |
64d5610f ML |
12190 | @subsection Max_Entry_Queue_Length |
12191 | ||
12192 | ||
12193 | @geindex Max_Entry_Queue_Length | |
12194 | ||
12195 | [RM D.7] This restriction is a declaration that any protected entry compiled in | |
12196 | the scope of the restriction has at most the specified number of | |
12197 | tasks waiting on the entry at any one time, and so no queue is required. | |
12198 | Note that this restriction is checked at run time. Violation of this | |
12199 | restriction results in the raising of Program_Error exception at the point of | |
12200 | the call. | |
12201 | ||
12202 | @geindex Max_Entry_Queue_Depth | |
12203 | ||
12204 | The restriction @code{Max_Entry_Queue_Depth} is recognized as a | |
12205 | synonym for @code{Max_Entry_Queue_Length}. This is retained for historical | |
12206 | compatibility purposes (and a warning will be generated for its use if | |
12207 | warnings on obsolescent features are activated). | |
12208 | ||
12209 | @node Max_Protected_Entries,Max_Select_Alternatives,Max_Entry_Queue_Length,Partition-Wide Restrictions | |
04d6c745 | 12210 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions max-protected-entries}@anchor{1c1} |
64d5610f ML |
12211 | @subsection Max_Protected_Entries |
12212 | ||
12213 | ||
12214 | @geindex Max_Protected_Entries | |
12215 | ||
12216 | [RM D.7] Specifies the maximum number of entries per protected type. The | |
12217 | bounds of every entry family of a protected unit shall be static, or shall be | |
12218 | defined by a discriminant of a subtype whose corresponding bound is static. | |
12219 | ||
12220 | @node Max_Select_Alternatives,Max_Storage_At_Blocking,Max_Protected_Entries,Partition-Wide Restrictions | |
04d6c745 | 12221 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions max-select-alternatives}@anchor{1c2} |
64d5610f ML |
12222 | @subsection Max_Select_Alternatives |
12223 | ||
12224 | ||
12225 | @geindex Max_Select_Alternatives | |
12226 | ||
12227 | [RM D.7] Specifies the maximum number of alternatives in a selective accept. | |
12228 | ||
12229 | @node Max_Storage_At_Blocking,Max_Task_Entries,Max_Select_Alternatives,Partition-Wide Restrictions | |
04d6c745 | 12230 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions max-storage-at-blocking}@anchor{1c3} |
64d5610f ML |
12231 | @subsection Max_Storage_At_Blocking |
12232 | ||
12233 | ||
12234 | @geindex Max_Storage_At_Blocking | |
12235 | ||
12236 | [RM D.7] Specifies the maximum portion (in storage elements) of a task’s | |
12237 | Storage_Size that can be retained by a blocked task. A violation of this | |
12238 | restriction causes Storage_Error to be raised. | |
12239 | ||
12240 | @node Max_Task_Entries,Max_Tasks,Max_Storage_At_Blocking,Partition-Wide Restrictions | |
04d6c745 | 12241 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions max-task-entries}@anchor{1c4} |
64d5610f ML |
12242 | @subsection Max_Task_Entries |
12243 | ||
12244 | ||
12245 | @geindex Max_Task_Entries | |
12246 | ||
12247 | [RM D.7] Specifies the maximum number of entries | |
12248 | per task. The bounds of every entry family | |
12249 | of a task unit shall be static, or shall be | |
12250 | defined by a discriminant of a subtype whose | |
12251 | corresponding bound is static. | |
12252 | ||
12253 | @node Max_Tasks,No_Abort_Statements,Max_Task_Entries,Partition-Wide Restrictions | |
04d6c745 | 12254 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions max-tasks}@anchor{1c5} |
64d5610f ML |
12255 | @subsection Max_Tasks |
12256 | ||
12257 | ||
12258 | @geindex Max_Tasks | |
12259 | ||
12260 | [RM D.7] Specifies the maximum number of task that may be created, not | |
12261 | counting the creation of the environment task. Violations of this | |
12262 | restriction with a value of zero are detected at compile | |
12263 | time. Violations of this restriction with values other than zero cause | |
12264 | Storage_Error to be raised. | |
12265 | ||
12266 | @node No_Abort_Statements,No_Access_Parameter_Allocators,Max_Tasks,Partition-Wide Restrictions | |
04d6c745 | 12267 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-abort-statements}@anchor{1c6} |
64d5610f ML |
12268 | @subsection No_Abort_Statements |
12269 | ||
12270 | ||
12271 | @geindex No_Abort_Statements | |
12272 | ||
12273 | [RM D.7] There are no abort_statements, and there are | |
12274 | no calls to Task_Identification.Abort_Task. | |
12275 | ||
12276 | @node No_Access_Parameter_Allocators,No_Access_Subprograms,No_Abort_Statements,Partition-Wide Restrictions | |
04d6c745 | 12277 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-access-parameter-allocators}@anchor{1c7} |
64d5610f ML |
12278 | @subsection No_Access_Parameter_Allocators |
12279 | ||
12280 | ||
12281 | @geindex No_Access_Parameter_Allocators | |
12282 | ||
12283 | [RM H.4] This restriction ensures at compile time that there are no | |
12284 | occurrences of an allocator as the actual parameter to an access | |
12285 | parameter. | |
12286 | ||
12287 | @node No_Access_Subprograms,No_Allocators,No_Access_Parameter_Allocators,Partition-Wide Restrictions | |
04d6c745 | 12288 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-access-subprograms}@anchor{1c8} |
64d5610f ML |
12289 | @subsection No_Access_Subprograms |
12290 | ||
12291 | ||
12292 | @geindex No_Access_Subprograms | |
12293 | ||
12294 | [RM H.4] This restriction ensures at compile time that there are no | |
12295 | declarations of access-to-subprogram types. | |
12296 | ||
12297 | @node No_Allocators,No_Anonymous_Allocators,No_Access_Subprograms,Partition-Wide Restrictions | |
04d6c745 | 12298 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-allocators}@anchor{1c9} |
64d5610f ML |
12299 | @subsection No_Allocators |
12300 | ||
12301 | ||
12302 | @geindex No_Allocators | |
12303 | ||
12304 | [RM H.4] This restriction ensures at compile time that there are no | |
12305 | occurrences of an allocator. | |
12306 | ||
12307 | @node No_Anonymous_Allocators,No_Asynchronous_Control,No_Allocators,Partition-Wide Restrictions | |
04d6c745 | 12308 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-anonymous-allocators}@anchor{1ca} |
64d5610f ML |
12309 | @subsection No_Anonymous_Allocators |
12310 | ||
12311 | ||
12312 | @geindex No_Anonymous_Allocators | |
12313 | ||
12314 | [RM H.4] This restriction ensures at compile time that there are no | |
12315 | occurrences of an allocator of anonymous access type. | |
12316 | ||
12317 | @node No_Asynchronous_Control,No_Calendar,No_Anonymous_Allocators,Partition-Wide Restrictions | |
04d6c745 | 12318 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-asynchronous-control}@anchor{1cb} |
64d5610f ML |
12319 | @subsection No_Asynchronous_Control |
12320 | ||
12321 | ||
12322 | @geindex No_Asynchronous_Control | |
12323 | ||
12324 | [RM J.13] This restriction ensures at compile time that there are no semantic | |
12325 | dependences on the predefined package Asynchronous_Task_Control. | |
12326 | ||
12327 | @node No_Calendar,No_Coextensions,No_Asynchronous_Control,Partition-Wide Restrictions | |
04d6c745 | 12328 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-calendar}@anchor{1cc} |
64d5610f ML |
12329 | @subsection No_Calendar |
12330 | ||
12331 | ||
12332 | @geindex No_Calendar | |
12333 | ||
12334 | [GNAT] This restriction ensures at compile time that there are no semantic | |
12335 | dependences on package Calendar. | |
12336 | ||
12337 | @node No_Coextensions,No_Default_Initialization,No_Calendar,Partition-Wide Restrictions | |
04d6c745 | 12338 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-coextensions}@anchor{1cd} |
64d5610f ML |
12339 | @subsection No_Coextensions |
12340 | ||
12341 | ||
12342 | @geindex No_Coextensions | |
12343 | ||
12344 | [RM H.4] This restriction ensures at compile time that there are no | |
12345 | coextensions. See 3.10.2. | |
12346 | ||
12347 | @node No_Default_Initialization,No_Delay,No_Coextensions,Partition-Wide Restrictions | |
04d6c745 | 12348 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-default-initialization}@anchor{1ce} |
64d5610f ML |
12349 | @subsection No_Default_Initialization |
12350 | ||
12351 | ||
12352 | @geindex No_Default_Initialization | |
12353 | ||
12354 | [GNAT] This restriction prohibits any instance of default initialization | |
12355 | of variables. The binder implements a consistency rule which prevents | |
12356 | any unit compiled without the restriction from with’ing a unit with the | |
12357 | restriction (this allows the generation of initialization procedures to | |
12358 | be skipped, since you can be sure that no call is ever generated to an | |
12359 | initialization procedure in a unit with the restriction active). If used | |
12360 | in conjunction with Initialize_Scalars or Normalize_Scalars, the effect | |
12361 | is to prohibit all cases of variables declared without a specific | |
12362 | initializer (including the case of OUT scalar parameters). | |
12363 | ||
12364 | @node No_Delay,No_Dependence,No_Default_Initialization,Partition-Wide Restrictions | |
04d6c745 | 12365 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-delay}@anchor{1cf} |
64d5610f ML |
12366 | @subsection No_Delay |
12367 | ||
12368 | ||
12369 | @geindex No_Delay | |
12370 | ||
12371 | [RM H.4] This restriction ensures at compile time that there are no | |
12372 | delay statements and no semantic dependences on package Calendar. | |
12373 | ||
12374 | @node No_Dependence,No_Direct_Boolean_Operators,No_Delay,Partition-Wide Restrictions | |
04d6c745 | 12375 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dependence}@anchor{1d0} |
64d5610f ML |
12376 | @subsection No_Dependence |
12377 | ||
12378 | ||
12379 | @geindex No_Dependence | |
12380 | ||
12381 | [RM 13.12.1] This restriction ensures at compile time that there are no | |
12382 | dependences on a library unit. For GNAT, this includes implicit implementation | |
12383 | dependences on units of the runtime library that are created by the compiler | |
5c6e2616 EB |
12384 | to support specific constructs of the language. Here are some examples: |
12385 | ||
12386 | ||
12387 | @itemize * | |
12388 | ||
12389 | @item | |
12390 | @code{System.Arith_64}: 64-bit arithmetics for 32-bit platforms, | |
12391 | ||
12392 | @item | |
12393 | @code{System.Arith_128}: 128-bit arithmetics for 64-bit platforms, | |
12394 | ||
12395 | @item | |
12396 | @code{System.Memory}: heap memory allocation routines, | |
12397 | ||
12398 | @item | |
12399 | @code{System.Memory_Compare}: memory comparison routine (aka @code{memcmp} for C), | |
12400 | ||
12401 | @item | |
12402 | @code{System.Memory_Copy}: memory copy routine (aka @code{memcpy} for C), | |
12403 | ||
12404 | @item | |
12405 | @code{System.Memory_Move}: memoy move routine (aka @code{memmove} for C), | |
12406 | ||
12407 | @item | |
12408 | @code{System.Memory_Set}: memory set routine (aka @code{memset} for C), | |
12409 | ||
12410 | @item | |
12411 | @code{System.Stack_Checking[.Operations]}: stack checking without MMU, | |
12412 | ||
12413 | @item | |
12414 | @code{System.GCC}: support routines from the GCC library. | |
12415 | @end itemize | |
64d5610f ML |
12416 | |
12417 | @node No_Direct_Boolean_Operators,No_Dispatch,No_Dependence,Partition-Wide Restrictions | |
04d6c745 | 12418 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-direct-boolean-operators}@anchor{1d1} |
64d5610f ML |
12419 | @subsection No_Direct_Boolean_Operators |
12420 | ||
12421 | ||
12422 | @geindex No_Direct_Boolean_Operators | |
12423 | ||
12424 | [GNAT] This restriction ensures that no logical operators (and/or/xor) | |
12425 | are used on operands of type Boolean (or any type derived from Boolean). | |
12426 | This is intended for use in safety critical programs where the certification | |
12427 | protocol requires the use of short-circuit (and then, or else) forms for all | |
12428 | composite boolean operations. | |
12429 | ||
12430 | @node No_Dispatch,No_Dispatching_Calls,No_Direct_Boolean_Operators,Partition-Wide Restrictions | |
04d6c745 | 12431 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dispatch}@anchor{1d2} |
64d5610f ML |
12432 | @subsection No_Dispatch |
12433 | ||
12434 | ||
12435 | @geindex No_Dispatch | |
12436 | ||
12437 | [RM H.4] This restriction ensures at compile time that there are no | |
12438 | occurrences of @code{T'Class}, for any (tagged) subtype @code{T}. | |
12439 | ||
12440 | @node No_Dispatching_Calls,No_Dynamic_Attachment,No_Dispatch,Partition-Wide Restrictions | |
04d6c745 | 12441 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dispatching-calls}@anchor{1d3} |
64d5610f ML |
12442 | @subsection No_Dispatching_Calls |
12443 | ||
12444 | ||
12445 | @geindex No_Dispatching_Calls | |
12446 | ||
12447 | [GNAT] This restriction ensures at compile time that the code generated by the | |
12448 | compiler involves no dispatching calls. The use of this restriction allows the | |
12449 | safe use of record extensions, classwide membership tests and other classwide | |
12450 | features not involving implicit dispatching. This restriction ensures that | |
12451 | the code contains no indirect calls through a dispatching mechanism. Note that | |
12452 | this includes internally-generated calls created by the compiler, for example | |
12453 | in the implementation of class-wide objects assignments. The | |
12454 | membership test is allowed in the presence of this restriction, because its | |
12455 | implementation requires no dispatching. | |
12456 | This restriction is comparable to the official Ada restriction | |
12457 | @code{No_Dispatch} except that it is a bit less restrictive in that it allows | |
12458 | all classwide constructs that do not imply dispatching. | |
12459 | The following example indicates constructs that violate this restriction. | |
12460 | ||
12461 | @example | |
12462 | package Pkg is | |
12463 | type T is tagged record | |
12464 | Data : Natural; | |
12465 | end record; | |
12466 | procedure P (X : T); | |
12467 | ||
12468 | type DT is new T with record | |
12469 | More_Data : Natural; | |
12470 | end record; | |
12471 | procedure Q (X : DT); | |
12472 | end Pkg; | |
12473 | ||
12474 | with Pkg; use Pkg; | |
12475 | procedure Example is | |
12476 | procedure Test (O : T'Class) is | |
12477 | N : Natural := O'Size; -- Error: Dispatching call | |
12478 | C : T'Class := O; -- Error: implicit Dispatching Call | |
12479 | begin | |
12480 | if O in DT'Class then -- OK : Membership test | |
12481 | Q (DT (O)); -- OK : Type conversion plus direct call | |
12482 | else | |
12483 | P (O); -- Error: Dispatching call | |
12484 | end if; | |
12485 | end Test; | |
12486 | ||
12487 | Obj : DT; | |
12488 | begin | |
12489 | P (Obj); -- OK : Direct call | |
12490 | P (T (Obj)); -- OK : Type conversion plus direct call | |
12491 | P (T'Class (Obj)); -- Error: Dispatching call | |
12492 | ||
12493 | Test (Obj); -- OK : Type conversion | |
12494 | ||
12495 | if Obj in T'Class then -- OK : Membership test | |
12496 | null; | |
12497 | end if; | |
12498 | end Example; | |
12499 | @end example | |
12500 | ||
12501 | @node No_Dynamic_Attachment,No_Dynamic_Priorities,No_Dispatching_Calls,Partition-Wide Restrictions | |
04d6c745 | 12502 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dynamic-attachment}@anchor{1d4} |
64d5610f ML |
12503 | @subsection No_Dynamic_Attachment |
12504 | ||
12505 | ||
12506 | @geindex No_Dynamic_Attachment | |
12507 | ||
12508 | [RM D.7] This restriction ensures that there is no call to any of the | |
12509 | operations defined in package Ada.Interrupts | |
12510 | (Is_Reserved, Is_Attached, Current_Handler, Attach_Handler, Exchange_Handler, | |
12511 | Detach_Handler, and Reference). | |
12512 | ||
12513 | @geindex No_Dynamic_Interrupts | |
12514 | ||
12515 | The restriction @code{No_Dynamic_Interrupts} is recognized as a | |
12516 | synonym for @code{No_Dynamic_Attachment}. This is retained for historical | |
12517 | compatibility purposes (and a warning will be generated for its use if | |
12518 | warnings on obsolescent features are activated). | |
12519 | ||
12520 | @node No_Dynamic_Priorities,No_Entry_Calls_In_Elaboration_Code,No_Dynamic_Attachment,Partition-Wide Restrictions | |
04d6c745 | 12521 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dynamic-priorities}@anchor{1d5} |
64d5610f ML |
12522 | @subsection No_Dynamic_Priorities |
12523 | ||
12524 | ||
12525 | @geindex No_Dynamic_Priorities | |
12526 | ||
12527 | [RM D.7] There are no semantic dependencies on the package Dynamic_Priorities. | |
12528 | ||
12529 | @node No_Entry_Calls_In_Elaboration_Code,No_Enumeration_Maps,No_Dynamic_Priorities,Partition-Wide Restrictions | |
04d6c745 | 12530 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-entry-calls-in-elaboration-code}@anchor{1d6} |
64d5610f ML |
12531 | @subsection No_Entry_Calls_In_Elaboration_Code |
12532 | ||
12533 | ||
12534 | @geindex No_Entry_Calls_In_Elaboration_Code | |
12535 | ||
12536 | [GNAT] This restriction ensures at compile time that no task or protected entry | |
12537 | calls are made during elaboration code. As a result of the use of this | |
12538 | restriction, the compiler can assume that no code past an accept statement | |
12539 | in a task can be executed at elaboration time. | |
12540 | ||
12541 | @node No_Enumeration_Maps,No_Exception_Handlers,No_Entry_Calls_In_Elaboration_Code,Partition-Wide Restrictions | |
04d6c745 | 12542 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-enumeration-maps}@anchor{1d7} |
64d5610f ML |
12543 | @subsection No_Enumeration_Maps |
12544 | ||
12545 | ||
12546 | @geindex No_Enumeration_Maps | |
12547 | ||
12548 | [GNAT] This restriction ensures at compile time that no operations requiring | |
12549 | enumeration maps are used (that is Image and Value attributes applied | |
12550 | to enumeration types). | |
12551 | ||
12552 | @node No_Exception_Handlers,No_Exception_Propagation,No_Enumeration_Maps,Partition-Wide Restrictions | |
04d6c745 | 12553 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-exception-handlers}@anchor{1d8} |
64d5610f ML |
12554 | @subsection No_Exception_Handlers |
12555 | ||
12556 | ||
12557 | @geindex No_Exception_Handlers | |
12558 | ||
12559 | [GNAT] This restriction ensures at compile time that there are no explicit | |
12560 | exception handlers. It also indicates that no exception propagation will | |
12561 | be provided. In this mode, exceptions may be raised but will result in | |
12562 | an immediate call to the last chance handler, a routine that the user | |
12563 | must define with the following profile: | |
12564 | ||
12565 | @example | |
12566 | procedure Last_Chance_Handler | |
12567 | (Source_Location : System.Address; Line : Integer); | |
12568 | pragma Export (C, Last_Chance_Handler, | |
12569 | "__gnat_last_chance_handler"); | |
12570 | @end example | |
12571 | ||
12572 | The parameter is a C null-terminated string representing a message to be | |
12573 | associated with the exception (typically the source location of the raise | |
12574 | statement generated by the compiler). The Line parameter when nonzero | |
12575 | represents the line number in the source program where the raise occurs. | |
12576 | ||
12577 | @node No_Exception_Propagation,No_Exception_Registration,No_Exception_Handlers,Partition-Wide Restrictions | |
04d6c745 | 12578 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-exception-propagation}@anchor{1d9} |
64d5610f ML |
12579 | @subsection No_Exception_Propagation |
12580 | ||
12581 | ||
12582 | @geindex No_Exception_Propagation | |
12583 | ||
12584 | [GNAT] This restriction guarantees that exceptions are never propagated | |
12585 | to an outer subprogram scope. The only case in which an exception may | |
12586 | be raised is when the handler is statically in the same subprogram, so | |
12587 | that the effect of a raise is essentially like a goto statement. Any | |
12588 | other raise statement (implicit or explicit) will be considered | |
12589 | unhandled. Exception handlers are allowed, but may not contain an | |
12590 | exception occurrence identifier (exception choice). In addition, use of | |
12591 | the package GNAT.Current_Exception is not permitted, and reraise | |
12592 | statements (raise with no operand) are not permitted. | |
12593 | ||
12594 | @node No_Exception_Registration,No_Exceptions,No_Exception_Propagation,Partition-Wide Restrictions | |
04d6c745 | 12595 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-exception-registration}@anchor{1da} |
64d5610f ML |
12596 | @subsection No_Exception_Registration |
12597 | ||
12598 | ||
12599 | @geindex No_Exception_Registration | |
12600 | ||
12601 | [GNAT] This restriction ensures at compile time that no stream operations for | |
12602 | types Exception_Id or Exception_Occurrence are used. This also makes it | |
12603 | impossible to pass exceptions to or from a partition with this restriction | |
12604 | in a distributed environment. If this restriction is active, the generated | |
12605 | code is simplified by omitting the otherwise-required global registration | |
12606 | of exceptions when they are declared. | |
12607 | ||
12608 | @node No_Exceptions,No_Finalization,No_Exception_Registration,Partition-Wide Restrictions | |
04d6c745 | 12609 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-exceptions}@anchor{1db} |
64d5610f ML |
12610 | @subsection No_Exceptions |
12611 | ||
12612 | ||
12613 | @geindex No_Exceptions | |
12614 | ||
12615 | [RM H.4] This restriction ensures at compile time that there are no | |
12616 | raise statements and no exception handlers and also suppresses the | |
12617 | generation of language-defined run-time checks. | |
12618 | ||
12619 | @node No_Finalization,No_Fixed_Point,No_Exceptions,Partition-Wide Restrictions | |
04d6c745 | 12620 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-finalization}@anchor{1dc} |
64d5610f ML |
12621 | @subsection No_Finalization |
12622 | ||
12623 | ||
12624 | @geindex No_Finalization | |
12625 | ||
12626 | [GNAT] This restriction disables the language features described in | |
12627 | chapter 7.6 of the Ada 2005 RM as well as all form of code generation | |
12628 | performed by the compiler to support these features. The following types | |
12629 | are no longer considered controlled when this restriction is in effect: | |
12630 | ||
12631 | ||
12632 | @itemize * | |
12633 | ||
12634 | @item | |
12635 | @code{Ada.Finalization.Controlled} | |
12636 | ||
12637 | @item | |
12638 | @code{Ada.Finalization.Limited_Controlled} | |
12639 | ||
12640 | @item | |
12641 | Derivations from @code{Controlled} or @code{Limited_Controlled} | |
12642 | ||
12643 | @item | |
12644 | Class-wide types | |
12645 | ||
12646 | @item | |
12647 | Protected types | |
12648 | ||
12649 | @item | |
12650 | Task types | |
12651 | ||
12652 | @item | |
12653 | Array and record types with controlled components | |
12654 | @end itemize | |
12655 | ||
12656 | The compiler no longer generates code to initialize, finalize or adjust an | |
12657 | object or a nested component, either declared on the stack or on the heap. The | |
12658 | deallocation of a controlled object no longer finalizes its contents. | |
12659 | ||
12660 | @node No_Fixed_Point,No_Floating_Point,No_Finalization,Partition-Wide Restrictions | |
04d6c745 | 12661 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-fixed-point}@anchor{1dd} |
64d5610f ML |
12662 | @subsection No_Fixed_Point |
12663 | ||
12664 | ||
12665 | @geindex No_Fixed_Point | |
12666 | ||
12667 | [RM H.4] This restriction ensures at compile time that there are no | |
12668 | occurrences of fixed point types and operations. | |
12669 | ||
12670 | @node No_Floating_Point,No_Implicit_Conditionals,No_Fixed_Point,Partition-Wide Restrictions | |
04d6c745 | 12671 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-floating-point}@anchor{1de} |
64d5610f ML |
12672 | @subsection No_Floating_Point |
12673 | ||
12674 | ||
12675 | @geindex No_Floating_Point | |
12676 | ||
12677 | [RM H.4] This restriction ensures at compile time that there are no | |
12678 | occurrences of floating point types and operations. | |
12679 | ||
12680 | @node No_Implicit_Conditionals,No_Implicit_Dynamic_Code,No_Floating_Point,Partition-Wide Restrictions | |
04d6c745 | 12681 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-conditionals}@anchor{1df} |
64d5610f ML |
12682 | @subsection No_Implicit_Conditionals |
12683 | ||
12684 | ||
12685 | @geindex No_Implicit_Conditionals | |
12686 | ||
12687 | [GNAT] This restriction ensures that the generated code does not contain any | |
12688 | implicit conditionals, either by modifying the generated code where possible, | |
12689 | or by rejecting any construct that would otherwise generate an implicit | |
12690 | conditional. Note that this check does not include run time constraint | |
12691 | checks, which on some targets may generate implicit conditionals as | |
12692 | well. To control the latter, constraint checks can be suppressed in the | |
12693 | normal manner. Constructs generating implicit conditionals include comparisons | |
12694 | of composite objects and the Max/Min attributes. | |
12695 | ||
12696 | @node No_Implicit_Dynamic_Code,No_Implicit_Heap_Allocations,No_Implicit_Conditionals,Partition-Wide Restrictions | |
04d6c745 | 12697 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-dynamic-code}@anchor{1e0} |
64d5610f ML |
12698 | @subsection No_Implicit_Dynamic_Code |
12699 | ||
12700 | ||
12701 | @geindex No_Implicit_Dynamic_Code | |
12702 | ||
12703 | @geindex trampoline | |
12704 | ||
12705 | [GNAT] This restriction prevents the compiler from building ‘trampolines’. | |
12706 | This is a structure that is built on the stack and contains dynamic | |
12707 | code to be executed at run time. On some targets, a trampoline is | |
12708 | built for the following features: @code{Access}, | |
12709 | @code{Unrestricted_Access}, or @code{Address} of a nested subprogram; | |
12710 | nested task bodies; primitive operations of nested tagged types. | |
12711 | Trampolines do not work on machines that prevent execution of stack | |
12712 | data. For example, on windows systems, enabling DEP (data execution | |
12713 | protection) will cause trampolines to raise an exception. | |
12714 | Trampolines are also quite slow at run time. | |
12715 | ||
12716 | On many targets, trampolines have been largely eliminated. Look at the | |
12717 | version of system.ads for your target — if it has | |
12718 | Always_Compatible_Rep equal to False, then trampolines are largely | |
12719 | eliminated. In particular, a trampoline is built for the following | |
12720 | features: @code{Address} of a nested subprogram; | |
12721 | @code{Access} or @code{Unrestricted_Access} of a nested subprogram, | |
12722 | but only if pragma Favor_Top_Level applies, or the access type has a | |
12723 | foreign-language convention; primitive operations of nested tagged | |
12724 | types. | |
12725 | ||
12726 | @node No_Implicit_Heap_Allocations,No_Implicit_Protected_Object_Allocations,No_Implicit_Dynamic_Code,Partition-Wide Restrictions | |
04d6c745 | 12727 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-heap-allocations}@anchor{1e1} |
64d5610f ML |
12728 | @subsection No_Implicit_Heap_Allocations |
12729 | ||
12730 | ||
12731 | @geindex No_Implicit_Heap_Allocations | |
12732 | ||
12733 | [RM D.7] No constructs are allowed to cause implicit heap allocation. | |
12734 | ||
12735 | @node No_Implicit_Protected_Object_Allocations,No_Implicit_Task_Allocations,No_Implicit_Heap_Allocations,Partition-Wide Restrictions | |
04d6c745 | 12736 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-protected-object-allocations}@anchor{1e2} |
64d5610f ML |
12737 | @subsection No_Implicit_Protected_Object_Allocations |
12738 | ||
12739 | ||
12740 | @geindex No_Implicit_Protected_Object_Allocations | |
12741 | ||
12742 | [GNAT] No constructs are allowed to cause implicit heap allocation of a | |
12743 | protected object. | |
12744 | ||
12745 | @node No_Implicit_Task_Allocations,No_Initialize_Scalars,No_Implicit_Protected_Object_Allocations,Partition-Wide Restrictions | |
04d6c745 | 12746 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-task-allocations}@anchor{1e3} |
64d5610f ML |
12747 | @subsection No_Implicit_Task_Allocations |
12748 | ||
12749 | ||
12750 | @geindex No_Implicit_Task_Allocations | |
12751 | ||
12752 | [GNAT] No constructs are allowed to cause implicit heap allocation of a task. | |
12753 | ||
12754 | @node No_Initialize_Scalars,No_IO,No_Implicit_Task_Allocations,Partition-Wide Restrictions | |
04d6c745 | 12755 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-initialize-scalars}@anchor{1e4} |
64d5610f ML |
12756 | @subsection No_Initialize_Scalars |
12757 | ||
12758 | ||
12759 | @geindex No_Initialize_Scalars | |
12760 | ||
12761 | [GNAT] This restriction ensures that no unit in the partition is compiled with | |
12762 | pragma Initialize_Scalars. This allows the generation of more efficient | |
12763 | code, and in particular eliminates dummy null initialization routines that | |
12764 | are otherwise generated for some record and array types. | |
12765 | ||
12766 | @node No_IO,No_Local_Allocators,No_Initialize_Scalars,Partition-Wide Restrictions | |
04d6c745 | 12767 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-io}@anchor{1e5} |
64d5610f ML |
12768 | @subsection No_IO |
12769 | ||
12770 | ||
12771 | @geindex No_IO | |
12772 | ||
12773 | [RM H.4] This restriction ensures at compile time that there are no | |
12774 | dependences on any of the library units Sequential_IO, Direct_IO, | |
12775 | Text_IO, Wide_Text_IO, Wide_Wide_Text_IO, or Stream_IO. | |
12776 | ||
12777 | @node No_Local_Allocators,No_Local_Protected_Objects,No_IO,Partition-Wide Restrictions | |
04d6c745 | 12778 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-local-allocators}@anchor{1e6} |
64d5610f ML |
12779 | @subsection No_Local_Allocators |
12780 | ||
12781 | ||
12782 | @geindex No_Local_Allocators | |
12783 | ||
12784 | [RM H.4] This restriction ensures at compile time that there are no | |
12785 | occurrences of an allocator in subprograms, generic subprograms, tasks, | |
12786 | and entry bodies. | |
12787 | ||
12788 | @node No_Local_Protected_Objects,No_Local_Tagged_Types,No_Local_Allocators,Partition-Wide Restrictions | |
04d6c745 | 12789 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-local-protected-objects}@anchor{1e7} |
64d5610f ML |
12790 | @subsection No_Local_Protected_Objects |
12791 | ||
12792 | ||
12793 | @geindex No_Local_Protected_Objects | |
12794 | ||
12795 | [RM D.7] This restriction ensures at compile time that protected objects are | |
12796 | only declared at the library level. | |
12797 | ||
12798 | @node No_Local_Tagged_Types,No_Local_Timing_Events,No_Local_Protected_Objects,Partition-Wide Restrictions | |
04d6c745 | 12799 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-local-tagged-types}@anchor{1e8} |
64d5610f ML |
12800 | @subsection No_Local_Tagged_Types |
12801 | ||
12802 | ||
12803 | @geindex No_Local_Tagged_Types | |
12804 | ||
12805 | [GNAT] This restriction ensures at compile time that tagged types are only | |
12806 | declared at the library level. | |
12807 | ||
12808 | @node No_Local_Timing_Events,No_Long_Long_Integers,No_Local_Tagged_Types,Partition-Wide Restrictions | |
04d6c745 | 12809 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-local-timing-events}@anchor{1e9} |
64d5610f ML |
12810 | @subsection No_Local_Timing_Events |
12811 | ||
12812 | ||
12813 | @geindex No_Local_Timing_Events | |
12814 | ||
12815 | [RM D.7] All objects of type Ada.Real_Time.Timing_Events.Timing_Event are | |
12816 | declared at the library level. | |
12817 | ||
12818 | @node No_Long_Long_Integers,No_Multiple_Elaboration,No_Local_Timing_Events,Partition-Wide Restrictions | |
04d6c745 | 12819 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-long-long-integers}@anchor{1ea} |
64d5610f ML |
12820 | @subsection No_Long_Long_Integers |
12821 | ||
12822 | ||
12823 | @geindex No_Long_Long_Integers | |
12824 | ||
12825 | [GNAT] This partition-wide restriction forbids any explicit reference to | |
12826 | type Standard.Long_Long_Integer, and also forbids declaring range types whose | |
12827 | implicit base type is Long_Long_Integer, and modular types whose size exceeds | |
12828 | Long_Integer’Size. | |
12829 | ||
12830 | @node No_Multiple_Elaboration,No_Nested_Finalization,No_Long_Long_Integers,Partition-Wide Restrictions | |
04d6c745 | 12831 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-multiple-elaboration}@anchor{1eb} |
64d5610f ML |
12832 | @subsection No_Multiple_Elaboration |
12833 | ||
12834 | ||
12835 | @geindex No_Multiple_Elaboration | |
12836 | ||
12837 | [GNAT] When this restriction is active and the static elaboration model is | |
12838 | used, and -fpreserve-control-flow is not used, the compiler is allowed to | |
12839 | suppress the elaboration counter normally associated with the unit, even if | |
12840 | the unit has elaboration code. This counter is typically used to check for | |
12841 | access before elaboration and to control multiple elaboration attempts. If the | |
12842 | restriction is used, then the situations in which multiple elaboration is | |
12843 | possible, including non-Ada main programs and Stand Alone libraries, are not | |
12844 | permitted and will be diagnosed by the binder. | |
12845 | ||
12846 | @node No_Nested_Finalization,No_Protected_Type_Allocators,No_Multiple_Elaboration,Partition-Wide Restrictions | |
04d6c745 | 12847 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-nested-finalization}@anchor{1ec} |
64d5610f ML |
12848 | @subsection No_Nested_Finalization |
12849 | ||
12850 | ||
12851 | @geindex No_Nested_Finalization | |
12852 | ||
12853 | [RM D.7] All objects requiring finalization are declared at the library level. | |
12854 | ||
12855 | @node No_Protected_Type_Allocators,No_Protected_Types,No_Nested_Finalization,Partition-Wide Restrictions | |
04d6c745 | 12856 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-protected-type-allocators}@anchor{1ed} |
64d5610f ML |
12857 | @subsection No_Protected_Type_Allocators |
12858 | ||
12859 | ||
12860 | @geindex No_Protected_Type_Allocators | |
12861 | ||
12862 | [RM D.7] This restriction ensures at compile time that there are no allocator | |
12863 | expressions that attempt to allocate protected objects. | |
12864 | ||
12865 | @node No_Protected_Types,No_Recursion,No_Protected_Type_Allocators,Partition-Wide Restrictions | |
04d6c745 | 12866 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-protected-types}@anchor{1ee} |
64d5610f ML |
12867 | @subsection No_Protected_Types |
12868 | ||
12869 | ||
12870 | @geindex No_Protected_Types | |
12871 | ||
12872 | [RM H.4] This restriction ensures at compile time that there are no | |
12873 | declarations of protected types or protected objects. | |
12874 | ||
12875 | @node No_Recursion,No_Reentrancy,No_Protected_Types,Partition-Wide Restrictions | |
04d6c745 | 12876 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-recursion}@anchor{1ef} |
64d5610f ML |
12877 | @subsection No_Recursion |
12878 | ||
12879 | ||
12880 | @geindex No_Recursion | |
12881 | ||
12882 | [RM H.4] A program execution is erroneous if a subprogram is invoked as | |
12883 | part of its execution. | |
12884 | ||
12885 | @node No_Reentrancy,No_Relative_Delay,No_Recursion,Partition-Wide Restrictions | |
04d6c745 | 12886 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-reentrancy}@anchor{1f0} |
64d5610f ML |
12887 | @subsection No_Reentrancy |
12888 | ||
12889 | ||
12890 | @geindex No_Reentrancy | |
12891 | ||
12892 | [RM H.4] A program execution is erroneous if a subprogram is executed by | |
12893 | two tasks at the same time. | |
12894 | ||
12895 | @node No_Relative_Delay,No_Requeue_Statements,No_Reentrancy,Partition-Wide Restrictions | |
04d6c745 | 12896 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-relative-delay}@anchor{1f1} |
64d5610f ML |
12897 | @subsection No_Relative_Delay |
12898 | ||
12899 | ||
12900 | @geindex No_Relative_Delay | |
12901 | ||
12902 | [RM D.7] This restriction ensures at compile time that there are no delay | |
12903 | relative statements and prevents expressions such as @code{delay 1.23;} from | |
12904 | appearing in source code. | |
12905 | ||
12906 | @node No_Requeue_Statements,No_Secondary_Stack,No_Relative_Delay,Partition-Wide Restrictions | |
04d6c745 | 12907 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-requeue-statements}@anchor{1f2} |
64d5610f ML |
12908 | @subsection No_Requeue_Statements |
12909 | ||
12910 | ||
12911 | @geindex No_Requeue_Statements | |
12912 | ||
12913 | [RM D.7] This restriction ensures at compile time that no requeue statements | |
12914 | are permitted and prevents keyword @code{requeue} from being used in source | |
12915 | code. | |
12916 | ||
12917 | @geindex No_Requeue | |
12918 | ||
12919 | The restriction @code{No_Requeue} is recognized as a | |
12920 | synonym for @code{No_Requeue_Statements}. This is retained for historical | |
12921 | compatibility purposes (and a warning will be generated for its use if | |
12922 | warnings on oNobsolescent features are activated). | |
12923 | ||
12924 | @node No_Secondary_Stack,No_Select_Statements,No_Requeue_Statements,Partition-Wide Restrictions | |
04d6c745 | 12925 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-secondary-stack}@anchor{1f3} |
64d5610f ML |
12926 | @subsection No_Secondary_Stack |
12927 | ||
12928 | ||
12929 | @geindex No_Secondary_Stack | |
12930 | ||
12931 | [GNAT] This restriction ensures at compile time that the generated code | |
12932 | does not contain any reference to the secondary stack. The secondary | |
12933 | stack is used to implement functions returning unconstrained objects | |
12934 | (arrays or records) on some targets. Suppresses the allocation of | |
12935 | secondary stacks for tasks (excluding the environment task) at run time. | |
12936 | ||
12937 | @node No_Select_Statements,No_Specific_Termination_Handlers,No_Secondary_Stack,Partition-Wide Restrictions | |
04d6c745 | 12938 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-select-statements}@anchor{1f4} |
64d5610f ML |
12939 | @subsection No_Select_Statements |
12940 | ||
12941 | ||
12942 | @geindex No_Select_Statements | |
12943 | ||
12944 | [RM D.7] This restriction ensures at compile time no select statements of any | |
12945 | kind are permitted, that is the keyword @code{select} may not appear. | |
12946 | ||
12947 | @node No_Specific_Termination_Handlers,No_Specification_of_Aspect,No_Select_Statements,Partition-Wide Restrictions | |
04d6c745 | 12948 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-specific-termination-handlers}@anchor{1f5} |
64d5610f ML |
12949 | @subsection No_Specific_Termination_Handlers |
12950 | ||
12951 | ||
12952 | @geindex No_Specific_Termination_Handlers | |
12953 | ||
12954 | [RM D.7] There are no calls to Ada.Task_Termination.Set_Specific_Handler | |
12955 | or to Ada.Task_Termination.Specific_Handler. | |
12956 | ||
12957 | @node No_Specification_of_Aspect,No_Standard_Allocators_After_Elaboration,No_Specific_Termination_Handlers,Partition-Wide Restrictions | |
04d6c745 | 12958 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-specification-of-aspect}@anchor{1f6} |
64d5610f ML |
12959 | @subsection No_Specification_of_Aspect |
12960 | ||
12961 | ||
12962 | @geindex No_Specification_of_Aspect | |
12963 | ||
12964 | [RM 13.12.1] This restriction checks at compile time that no aspect | |
12965 | specification, attribute definition clause, or pragma is given for a | |
12966 | given aspect. | |
12967 | ||
12968 | @node No_Standard_Allocators_After_Elaboration,No_Standard_Storage_Pools,No_Specification_of_Aspect,Partition-Wide Restrictions | |
04d6c745 | 12969 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-standard-allocators-after-elaboration}@anchor{1f7} |
64d5610f ML |
12970 | @subsection No_Standard_Allocators_After_Elaboration |
12971 | ||
12972 | ||
12973 | @geindex No_Standard_Allocators_After_Elaboration | |
12974 | ||
12975 | [RM D.7] Specifies that an allocator using a standard storage pool | |
12976 | should never be evaluated at run time after the elaboration of the | |
12977 | library items of the partition has completed. Otherwise, Storage_Error | |
12978 | is raised. | |
12979 | ||
12980 | @node No_Standard_Storage_Pools,No_Stream_Optimizations,No_Standard_Allocators_After_Elaboration,Partition-Wide Restrictions | |
04d6c745 | 12981 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-standard-storage-pools}@anchor{1f8} |
64d5610f ML |
12982 | @subsection No_Standard_Storage_Pools |
12983 | ||
12984 | ||
12985 | @geindex No_Standard_Storage_Pools | |
12986 | ||
12987 | [GNAT] This restriction ensures at compile time that no access types | |
12988 | use the standard default storage pool. Any access type declared must | |
12989 | have an explicit Storage_Pool attribute defined specifying a | |
12990 | user-defined storage pool. | |
12991 | ||
12992 | @node No_Stream_Optimizations,No_Streams,No_Standard_Storage_Pools,Partition-Wide Restrictions | |
04d6c745 | 12993 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-stream-optimizations}@anchor{1f9} |
64d5610f ML |
12994 | @subsection No_Stream_Optimizations |
12995 | ||
12996 | ||
12997 | @geindex No_Stream_Optimizations | |
12998 | ||
12999 | [GNAT] This restriction affects the performance of stream operations on types | |
13000 | @code{String}, @code{Wide_String} and @code{Wide_Wide_String}. By default, the | |
13001 | compiler uses block reads and writes when manipulating @code{String} objects | |
13002 | due to their superior performance. When this restriction is in effect, the | |
13003 | compiler performs all IO operations on a per-character basis. | |
13004 | ||
13005 | @node No_Streams,No_Tagged_Type_Registration,No_Stream_Optimizations,Partition-Wide Restrictions | |
04d6c745 | 13006 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-streams}@anchor{1fa} |
64d5610f ML |
13007 | @subsection No_Streams |
13008 | ||
13009 | ||
13010 | @geindex No_Streams | |
13011 | ||
13012 | [GNAT] This restriction ensures at compile/bind time that there are no | |
13013 | stream objects created and no use of stream attributes. | |
13014 | This restriction does not forbid dependences on the package | |
13015 | @code{Ada.Streams}. So it is permissible to with | |
13016 | @code{Ada.Streams} (or another package that does so itself) | |
13017 | as long as no actual stream objects are created and no | |
13018 | stream attributes are used. | |
13019 | ||
13020 | Note that the use of restriction allows optimization of tagged types, | |
13021 | since they do not need to worry about dispatching stream operations. | |
13022 | To take maximum advantage of this space-saving optimization, any | |
13023 | unit declaring a tagged type should be compiled with the restriction, | |
13024 | though this is not required. | |
13025 | ||
13026 | @node No_Tagged_Type_Registration,No_Task_Allocators,No_Streams,Partition-Wide Restrictions | |
04d6c745 | 13027 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-tagged-type-registration}@anchor{1fb} |
64d5610f ML |
13028 | @subsection No_Tagged_Type_Registration |
13029 | ||
13030 | ||
13031 | @geindex No_Tagged_Type_Registration | |
13032 | ||
13033 | [GNAT] If this restriction is active, then class-wide streaming | |
13034 | attributes are not supported. In addition, the subprograms in | |
13035 | Ada.Tags are not supported. | |
13036 | If this restriction is active, the generated code is simplified by | |
13037 | omitting the otherwise-required global registration of tagged types when they | |
13038 | are declared. This restriction may be necessary in order to also apply | |
13039 | the No_Elaboration_Code restriction. | |
13040 | ||
13041 | @node No_Task_Allocators,No_Task_At_Interrupt_Priority,No_Tagged_Type_Registration,Partition-Wide Restrictions | |
04d6c745 | 13042 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-allocators}@anchor{1fc} |
64d5610f ML |
13043 | @subsection No_Task_Allocators |
13044 | ||
13045 | ||
13046 | @geindex No_Task_Allocators | |
13047 | ||
13048 | [RM D.7] There are no allocators for task types | |
13049 | or types containing task subcomponents. | |
13050 | ||
13051 | @node No_Task_At_Interrupt_Priority,No_Task_Attributes_Package,No_Task_Allocators,Partition-Wide Restrictions | |
04d6c745 | 13052 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-at-interrupt-priority}@anchor{1fd} |
64d5610f ML |
13053 | @subsection No_Task_At_Interrupt_Priority |
13054 | ||
13055 | ||
13056 | @geindex No_Task_At_Interrupt_Priority | |
13057 | ||
13058 | [GNAT] This restriction ensures at compile time that there is no | |
13059 | Interrupt_Priority aspect or pragma for a task or a task type. As | |
13060 | a consequence, the tasks are always created with a priority below | |
13061 | that an interrupt priority. | |
13062 | ||
13063 | @node No_Task_Attributes_Package,No_Task_Hierarchy,No_Task_At_Interrupt_Priority,Partition-Wide Restrictions | |
04d6c745 | 13064 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-attributes-package}@anchor{1fe} |
64d5610f ML |
13065 | @subsection No_Task_Attributes_Package |
13066 | ||
13067 | ||
13068 | @geindex No_Task_Attributes_Package | |
13069 | ||
13070 | [GNAT] This restriction ensures at compile time that there are no implicit or | |
13071 | explicit dependencies on the package @code{Ada.Task_Attributes}. | |
13072 | ||
13073 | @geindex No_Task_Attributes | |
13074 | ||
13075 | The restriction @code{No_Task_Attributes} is recognized as a synonym | |
13076 | for @code{No_Task_Attributes_Package}. This is retained for historical | |
13077 | compatibility purposes (and a warning will be generated for its use if | |
13078 | warnings on obsolescent features are activated). | |
13079 | ||
13080 | @node No_Task_Hierarchy,No_Task_Termination,No_Task_Attributes_Package,Partition-Wide Restrictions | |
04d6c745 | 13081 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-hierarchy}@anchor{1ff} |
64d5610f ML |
13082 | @subsection No_Task_Hierarchy |
13083 | ||
13084 | ||
13085 | @geindex No_Task_Hierarchy | |
13086 | ||
13087 | [RM D.7] All (non-environment) tasks depend | |
13088 | directly on the environment task of the partition. | |
13089 | ||
13090 | @node No_Task_Termination,No_Tasking,No_Task_Hierarchy,Partition-Wide Restrictions | |
04d6c745 | 13091 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-termination}@anchor{200} |
64d5610f ML |
13092 | @subsection No_Task_Termination |
13093 | ||
13094 | ||
13095 | @geindex No_Task_Termination | |
13096 | ||
13097 | [RM D.7] Tasks that terminate are erroneous. | |
13098 | ||
13099 | @node No_Tasking,No_Terminate_Alternatives,No_Task_Termination,Partition-Wide Restrictions | |
04d6c745 | 13100 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-tasking}@anchor{201} |
64d5610f ML |
13101 | @subsection No_Tasking |
13102 | ||
13103 | ||
13104 | @geindex No_Tasking | |
13105 | ||
13106 | [GNAT] This restriction prevents the declaration of tasks or task types | |
13107 | throughout the partition. It is similar in effect to the use of | |
13108 | @code{Max_Tasks => 0} except that violations are caught at compile time | |
13109 | and cause an error message to be output either by the compiler or | |
13110 | binder. | |
13111 | ||
13112 | @node No_Terminate_Alternatives,No_Unchecked_Access,No_Tasking,Partition-Wide Restrictions | |
04d6c745 | 13113 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-terminate-alternatives}@anchor{202} |
64d5610f ML |
13114 | @subsection No_Terminate_Alternatives |
13115 | ||
13116 | ||
13117 | @geindex No_Terminate_Alternatives | |
13118 | ||
13119 | [RM D.7] There are no selective accepts with terminate alternatives. | |
13120 | ||
13121 | @node No_Unchecked_Access,No_Unchecked_Conversion,No_Terminate_Alternatives,Partition-Wide Restrictions | |
04d6c745 | 13122 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-unchecked-access}@anchor{203} |
64d5610f ML |
13123 | @subsection No_Unchecked_Access |
13124 | ||
13125 | ||
13126 | @geindex No_Unchecked_Access | |
13127 | ||
13128 | [RM H.4] This restriction ensures at compile time that there are no | |
13129 | occurrences of the Unchecked_Access attribute. | |
13130 | ||
13131 | @node No_Unchecked_Conversion,No_Unchecked_Deallocation,No_Unchecked_Access,Partition-Wide Restrictions | |
04d6c745 | 13132 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-unchecked-conversion}@anchor{204} |
64d5610f ML |
13133 | @subsection No_Unchecked_Conversion |
13134 | ||
13135 | ||
13136 | @geindex No_Unchecked_Conversion | |
13137 | ||
13138 | [RM J.13] This restriction ensures at compile time that there are no semantic | |
13139 | dependences on the predefined generic function Unchecked_Conversion. | |
13140 | ||
73918baf | 13141 | @node No_Unchecked_Deallocation,No_Use_Of_Attribute,No_Unchecked_Conversion,Partition-Wide Restrictions |
04d6c745 | 13142 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-unchecked-deallocation}@anchor{205} |
64d5610f ML |
13143 | @subsection No_Unchecked_Deallocation |
13144 | ||
13145 | ||
13146 | @geindex No_Unchecked_Deallocation | |
13147 | ||
13148 | [RM J.13] This restriction ensures at compile time that there are no semantic | |
13149 | dependences on the predefined generic procedure Unchecked_Deallocation. | |
13150 | ||
73918baf | 13151 | @node No_Use_Of_Attribute,No_Use_Of_Entity,No_Unchecked_Deallocation,Partition-Wide Restrictions |
04d6c745 | 13152 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-use-of-attribute}@anchor{206} |
73918baf VI |
13153 | @subsection No_Use_Of_Attribute |
13154 | ||
13155 | ||
13156 | @geindex No_Use_Of_Attribute | |
13157 | ||
13158 | [RM 13.12.1] This is a standard Ada 2012 restriction that is GNAT defined in | |
13159 | earlier versions of Ada. | |
13160 | ||
13161 | @node No_Use_Of_Entity,No_Use_Of_Pragma,No_Use_Of_Attribute,Partition-Wide Restrictions | |
04d6c745 | 13162 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-use-of-entity}@anchor{207} |
64d5610f ML |
13163 | @subsection No_Use_Of_Entity |
13164 | ||
13165 | ||
13166 | @geindex No_Use_Of_Entity | |
13167 | ||
13168 | [GNAT] This restriction ensures at compile time that there are no references | |
13169 | to the entity given in the form | |
13170 | ||
13171 | @example | |
13172 | No_Use_Of_Entity => Name | |
13173 | @end example | |
13174 | ||
13175 | where @code{Name} is the fully qualified entity, for example | |
13176 | ||
13177 | @example | |
13178 | No_Use_Of_Entity => Ada.Text_IO.Put_Line | |
13179 | @end example | |
13180 | ||
73918baf | 13181 | @node No_Use_Of_Pragma,Pure_Barriers,No_Use_Of_Entity,Partition-Wide Restrictions |
04d6c745 | 13182 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-use-of-pragma}@anchor{208} |
73918baf VI |
13183 | @subsection No_Use_Of_Pragma |
13184 | ||
13185 | ||
13186 | @geindex No_Use_Of_Pragma | |
13187 | ||
13188 | [RM 13.12.1] This is a standard Ada 2012 restriction that is GNAT defined in | |
13189 | earlier versions of Ada. | |
13190 | ||
13191 | @node Pure_Barriers,Simple_Barriers,No_Use_Of_Pragma,Partition-Wide Restrictions | |
04d6c745 | 13192 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions pure-barriers}@anchor{209} |
64d5610f ML |
13193 | @subsection Pure_Barriers |
13194 | ||
13195 | ||
13196 | @geindex Pure_Barriers | |
13197 | ||
13198 | [GNAT] This restriction ensures at compile time that protected entry | |
13199 | barriers are restricted to: | |
13200 | ||
13201 | ||
13202 | @itemize * | |
13203 | ||
13204 | @item | |
13205 | components of the protected object (excluding selection from dereferences), | |
13206 | ||
13207 | @item | |
13208 | constant declarations, | |
13209 | ||
13210 | @item | |
13211 | named numbers, | |
13212 | ||
13213 | @item | |
13214 | enumeration literals, | |
13215 | ||
13216 | @item | |
13217 | integer literals, | |
13218 | ||
13219 | @item | |
13220 | real literals, | |
13221 | ||
13222 | @item | |
13223 | character literals, | |
13224 | ||
13225 | @item | |
13226 | implicitly defined comparison operators, | |
13227 | ||
13228 | @item | |
13229 | uses of the Standard.”not” operator, | |
13230 | ||
13231 | @item | |
13232 | short-circuit operator, | |
13233 | ||
13234 | @item | |
13235 | the Count attribute | |
13236 | @end itemize | |
13237 | ||
13238 | This restriction is a relaxation of the Simple_Barriers restriction, | |
13239 | but still ensures absence of side effects, exceptions, and recursion | |
13240 | during the evaluation of the barriers. | |
13241 | ||
13242 | @node Simple_Barriers,Static_Priorities,Pure_Barriers,Partition-Wide Restrictions | |
04d6c745 | 13243 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions simple-barriers}@anchor{20a} |
64d5610f ML |
13244 | @subsection Simple_Barriers |
13245 | ||
13246 | ||
13247 | @geindex Simple_Barriers | |
13248 | ||
13249 | [RM D.7] This restriction ensures at compile time that barriers in entry | |
13250 | declarations for protected types are restricted to either static boolean | |
13251 | expressions or references to simple boolean variables defined in the private | |
13252 | part of the protected type. No other form of entry barriers is permitted. | |
13253 | ||
13254 | @geindex Boolean_Entry_Barriers | |
13255 | ||
13256 | The restriction @code{Boolean_Entry_Barriers} is recognized as a | |
13257 | synonym for @code{Simple_Barriers}. This is retained for historical | |
13258 | compatibility purposes (and a warning will be generated for its use if | |
13259 | warnings on obsolescent features are activated). | |
13260 | ||
13261 | @node Static_Priorities,Static_Storage_Size,Simple_Barriers,Partition-Wide Restrictions | |
04d6c745 | 13262 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions static-priorities}@anchor{20b} |
64d5610f ML |
13263 | @subsection Static_Priorities |
13264 | ||
13265 | ||
13266 | @geindex Static_Priorities | |
13267 | ||
13268 | [GNAT] This restriction ensures at compile time that all priority expressions | |
13269 | are static, and that there are no dependences on the package | |
13270 | @code{Ada.Dynamic_Priorities}. | |
13271 | ||
13272 | @node Static_Storage_Size,,Static_Priorities,Partition-Wide Restrictions | |
04d6c745 | 13273 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions static-storage-size}@anchor{20c} |
64d5610f ML |
13274 | @subsection Static_Storage_Size |
13275 | ||
13276 | ||
13277 | @geindex Static_Storage_Size | |
13278 | ||
13279 | [GNAT] This restriction ensures at compile time that any expression appearing | |
13280 | in a Storage_Size pragma or attribute definition clause is static. | |
13281 | ||
13282 | @node Program Unit Level Restrictions,,Partition-Wide Restrictions,Standard and Implementation Defined Restrictions | |
04d6c745 | 13283 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions id3}@anchor{20d}@anchor{gnat_rm/standard_and_implementation_defined_restrictions program-unit-level-restrictions}@anchor{20e} |
64d5610f ML |
13284 | @section Program Unit Level Restrictions |
13285 | ||
13286 | ||
13287 | The second set of restriction identifiers | |
13288 | does not require partition-wide consistency. | |
13289 | The restriction may be enforced for a single | |
13290 | compilation unit without any effect on any of the | |
13291 | other compilation units in the partition. | |
13292 | ||
13293 | @menu | |
13294 | * No_Elaboration_Code:: | |
13295 | * No_Dynamic_Accessibility_Checks:: | |
13296 | * No_Dynamic_Sized_Objects:: | |
13297 | * No_Entry_Queue:: | |
13298 | * No_Implementation_Aspect_Specifications:: | |
13299 | * No_Implementation_Attributes:: | |
13300 | * No_Implementation_Identifiers:: | |
13301 | * No_Implementation_Pragmas:: | |
13302 | * No_Implementation_Restrictions:: | |
13303 | * No_Implementation_Units:: | |
13304 | * No_Implicit_Aliasing:: | |
13305 | * No_Implicit_Loops:: | |
13306 | * No_Obsolescent_Features:: | |
13307 | * No_Wide_Characters:: | |
13308 | * Static_Dispatch_Tables:: | |
13309 | * SPARK_05:: | |
13310 | ||
13311 | @end menu | |
13312 | ||
13313 | @node No_Elaboration_Code,No_Dynamic_Accessibility_Checks,,Program Unit Level Restrictions | |
04d6c745 | 13314 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-elaboration-code}@anchor{20f} |
64d5610f ML |
13315 | @subsection No_Elaboration_Code |
13316 | ||
13317 | ||
13318 | @geindex No_Elaboration_Code | |
13319 | ||
13320 | [GNAT] This restriction ensures at compile time that no elaboration code is | |
13321 | generated. Note that this is not the same condition as is enforced | |
13322 | by pragma @code{Preelaborate}. There are cases in which pragma | |
13323 | @code{Preelaborate} still permits code to be generated (e.g., code | |
13324 | to initialize a large array to all zeroes), and there are cases of units | |
13325 | which do not meet the requirements for pragma @code{Preelaborate}, | |
13326 | but for which no elaboration code is generated. Generally, it is | |
13327 | the case that preelaborable units will meet the restrictions, with | |
13328 | the exception of large aggregates initialized with an others_clause, | |
13329 | and exception declarations (which generate calls to a run-time | |
13330 | registry procedure). This restriction is enforced on | |
13331 | a unit by unit basis, it need not be obeyed consistently | |
13332 | throughout a partition. | |
13333 | ||
13334 | In the case of aggregates with others, if the aggregate has a dynamic | |
13335 | size, there is no way to eliminate the elaboration code (such dynamic | |
13336 | bounds would be incompatible with @code{Preelaborate} in any case). If | |
13337 | the bounds are static, then use of this restriction actually modifies | |
13338 | the code choice of the compiler to avoid generating a loop, and instead | |
13339 | generate the aggregate statically if possible, no matter how many times | |
13340 | the data for the others clause must be repeatedly generated. | |
13341 | ||
13342 | It is not possible to precisely document | |
13343 | the constructs which are compatible with this restriction, since, | |
13344 | unlike most other restrictions, this is not a restriction on the | |
13345 | source code, but a restriction on the generated object code. For | |
13346 | example, if the source contains a declaration: | |
13347 | ||
13348 | @example | |
13349 | Val : constant Integer := X; | |
13350 | @end example | |
13351 | ||
13352 | where X is not a static constant, it may be possible, depending | |
13353 | on complex optimization circuitry, for the compiler to figure | |
13354 | out the value of X at compile time, in which case this initialization | |
13355 | can be done by the loader, and requires no initialization code. It | |
13356 | is not possible to document the precise conditions under which the | |
13357 | optimizer can figure this out. | |
13358 | ||
13359 | Note that this the implementation of this restriction requires full | |
13360 | code generation. If it is used in conjunction with “semantics only” | |
13361 | checking, then some cases of violations may be missed. | |
13362 | ||
13363 | When this restriction is active, we are not requesting control-flow | |
13364 | preservation with -fpreserve-control-flow, and the static elaboration model is | |
13365 | used, the compiler is allowed to suppress the elaboration counter normally | |
13366 | associated with the unit. This counter is typically used to check for access | |
13367 | before elaboration and to control multiple elaboration attempts. | |
13368 | ||
13369 | @node No_Dynamic_Accessibility_Checks,No_Dynamic_Sized_Objects,No_Elaboration_Code,Program Unit Level Restrictions | |
04d6c745 | 13370 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dynamic-accessibility-checks}@anchor{210} |
64d5610f ML |
13371 | @subsection No_Dynamic_Accessibility_Checks |
13372 | ||
13373 | ||
13374 | @geindex No_Dynamic_Accessibility_Checks | |
13375 | ||
13376 | [GNAT] No dynamic accessibility checks are generated when this restriction is | |
13377 | in effect. Instead, dangling references are prevented via more conservative | |
13378 | compile-time checking. More specifically, existing compile-time checks are | |
13379 | enforced but with more conservative assumptions about the accessibility levels | |
13380 | of the relevant entities. These conservative assumptions eliminate the need for | |
13381 | dynamic accessibility checks. | |
13382 | ||
13383 | These new rules for computing (at compile-time) the accessibility level of an | |
13384 | anonymous access type T are as follows: | |
13385 | ||
13386 | ||
13387 | @itemize * | |
13388 | ||
13389 | @item | |
13390 | If T is a function result type then, from the caller’s perspective, its level | |
13391 | is that of the innermost master enclosing the function call. From the callee’s | |
13392 | perspective, the level of parameters and local variables of the callee is | |
13393 | statically deeper than the level of T. | |
13394 | ||
13395 | For any other accessibility level L such that the level of parameters and local | |
13396 | variables of the callee is statically deeper than L, the level of T (from the | |
13397 | callee’s perspective) is also statically deeper than L. | |
13398 | ||
13399 | @item | |
13400 | If T is the type of a formal parameter then, from the caller’s perspective, | |
13401 | its level is at least as deep as that of the type of the corresponding actual | |
13402 | parameter (whatever that actual parameter might be). From the callee’s | |
13403 | perspective, the level of parameters and local variables of the callee is | |
13404 | statically deeper than the level of T. | |
13405 | ||
13406 | @item | |
13407 | If T is the type of a discriminant then its level is that of the discriminated | |
13408 | type. | |
13409 | ||
13410 | @item | |
13411 | If T is the type of a stand-alone object then its level is the level of the | |
13412 | object. | |
13413 | ||
13414 | @item | |
13415 | In all other cases, the level of T is as defined by the existing rules of Ada. | |
13416 | @end itemize | |
13417 | ||
13418 | @node No_Dynamic_Sized_Objects,No_Entry_Queue,No_Dynamic_Accessibility_Checks,Program Unit Level Restrictions | |
04d6c745 | 13419 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dynamic-sized-objects}@anchor{211} |
64d5610f ML |
13420 | @subsection No_Dynamic_Sized_Objects |
13421 | ||
13422 | ||
13423 | @geindex No_Dynamic_Sized_Objects | |
13424 | ||
13425 | [GNAT] This restriction disallows certain constructs that might lead to the | |
13426 | creation of dynamic-sized composite objects (or array or discriminated type). | |
13427 | An array subtype indication is illegal if the bounds are not static | |
13428 | or references to discriminants of an enclosing type. | |
13429 | A discriminated subtype indication is illegal if the type has | |
13430 | discriminant-dependent array components or a variant part, and the | |
13431 | discriminants are not static. In addition, array and record aggregates are | |
13432 | illegal in corresponding cases. Note that this restriction does not forbid | |
13433 | access discriminants. It is often a good idea to combine this restriction | |
13434 | with No_Secondary_Stack. | |
13435 | ||
13436 | @node No_Entry_Queue,No_Implementation_Aspect_Specifications,No_Dynamic_Sized_Objects,Program Unit Level Restrictions | |
04d6c745 | 13437 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-entry-queue}@anchor{212} |
64d5610f ML |
13438 | @subsection No_Entry_Queue |
13439 | ||
13440 | ||
13441 | @geindex No_Entry_Queue | |
13442 | ||
13443 | [GNAT] This restriction is a declaration that any protected entry compiled in | |
13444 | the scope of the restriction has at most one task waiting on the entry | |
13445 | at any one time, and so no queue is required. This restriction is not | |
13446 | checked at compile time. A program execution is erroneous if an attempt | |
13447 | is made to queue a second task on such an entry. | |
13448 | ||
13449 | @node No_Implementation_Aspect_Specifications,No_Implementation_Attributes,No_Entry_Queue,Program Unit Level Restrictions | |
04d6c745 | 13450 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-aspect-specifications}@anchor{213} |
64d5610f ML |
13451 | @subsection No_Implementation_Aspect_Specifications |
13452 | ||
13453 | ||
13454 | @geindex No_Implementation_Aspect_Specifications | |
13455 | ||
13456 | [RM 13.12.1] This restriction checks at compile time that no | |
13457 | GNAT-defined aspects are present. With this restriction, the only | |
13458 | aspects that can be used are those defined in the Ada Reference Manual. | |
13459 | ||
13460 | @node No_Implementation_Attributes,No_Implementation_Identifiers,No_Implementation_Aspect_Specifications,Program Unit Level Restrictions | |
04d6c745 | 13461 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-attributes}@anchor{214} |
64d5610f ML |
13462 | @subsection No_Implementation_Attributes |
13463 | ||
13464 | ||
13465 | @geindex No_Implementation_Attributes | |
13466 | ||
13467 | [RM 13.12.1] This restriction checks at compile time that no | |
13468 | GNAT-defined attributes are present. With this restriction, the only | |
13469 | attributes that can be used are those defined in the Ada Reference | |
13470 | Manual. | |
13471 | ||
13472 | @node No_Implementation_Identifiers,No_Implementation_Pragmas,No_Implementation_Attributes,Program Unit Level Restrictions | |
04d6c745 | 13473 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-identifiers}@anchor{215} |
64d5610f ML |
13474 | @subsection No_Implementation_Identifiers |
13475 | ||
13476 | ||
13477 | @geindex No_Implementation_Identifiers | |
13478 | ||
13479 | [RM 13.12.1] This restriction checks at compile time that no | |
13480 | implementation-defined identifiers (marked with pragma Implementation_Defined) | |
13481 | occur within language-defined packages. | |
13482 | ||
13483 | @node No_Implementation_Pragmas,No_Implementation_Restrictions,No_Implementation_Identifiers,Program Unit Level Restrictions | |
04d6c745 | 13484 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-pragmas}@anchor{216} |
64d5610f ML |
13485 | @subsection No_Implementation_Pragmas |
13486 | ||
13487 | ||
13488 | @geindex No_Implementation_Pragmas | |
13489 | ||
13490 | [RM 13.12.1] This restriction checks at compile time that no | |
13491 | GNAT-defined pragmas are present. With this restriction, the only | |
13492 | pragmas that can be used are those defined in the Ada Reference Manual. | |
13493 | ||
13494 | @node No_Implementation_Restrictions,No_Implementation_Units,No_Implementation_Pragmas,Program Unit Level Restrictions | |
04d6c745 | 13495 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-restrictions}@anchor{217} |
64d5610f ML |
13496 | @subsection No_Implementation_Restrictions |
13497 | ||
13498 | ||
13499 | @geindex No_Implementation_Restrictions | |
13500 | ||
13501 | [GNAT] This restriction checks at compile time that no GNAT-defined restriction | |
13502 | identifiers (other than @code{No_Implementation_Restrictions} itself) | |
13503 | are present. With this restriction, the only other restriction identifiers | |
13504 | that can be used are those defined in the Ada Reference Manual. | |
13505 | ||
13506 | @node No_Implementation_Units,No_Implicit_Aliasing,No_Implementation_Restrictions,Program Unit Level Restrictions | |
04d6c745 | 13507 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-units}@anchor{218} |
64d5610f ML |
13508 | @subsection No_Implementation_Units |
13509 | ||
13510 | ||
13511 | @geindex No_Implementation_Units | |
13512 | ||
13513 | [RM 13.12.1] This restriction checks at compile time that there is no | |
13514 | mention in the context clause of any implementation-defined descendants | |
13515 | of packages Ada, Interfaces, or System. | |
13516 | ||
13517 | @node No_Implicit_Aliasing,No_Implicit_Loops,No_Implementation_Units,Program Unit Level Restrictions | |
04d6c745 | 13518 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-aliasing}@anchor{219} |
64d5610f ML |
13519 | @subsection No_Implicit_Aliasing |
13520 | ||
13521 | ||
13522 | @geindex No_Implicit_Aliasing | |
13523 | ||
13524 | [GNAT] This restriction, which is not required to be partition-wide consistent, | |
13525 | requires an explicit aliased keyword for an object to which ‘Access, | |
13526 | ‘Unchecked_Access, or ‘Address is applied, and forbids entirely the use of | |
13527 | the ‘Unrestricted_Access attribute for objects. Note: the reason that | |
13528 | Unrestricted_Access is forbidden is that it would require the prefix | |
13529 | to be aliased, and in such cases, it can always be replaced by | |
13530 | the standard attribute Unchecked_Access which is preferable. | |
13531 | ||
13532 | @node No_Implicit_Loops,No_Obsolescent_Features,No_Implicit_Aliasing,Program Unit Level Restrictions | |
04d6c745 | 13533 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-loops}@anchor{21a} |
64d5610f ML |
13534 | @subsection No_Implicit_Loops |
13535 | ||
13536 | ||
13537 | @geindex No_Implicit_Loops | |
13538 | ||
13539 | [GNAT] This restriction ensures that the generated code of the unit marked | |
13540 | with this restriction does not contain any implicit @code{for} loops, either by | |
13541 | modifying the generated code where possible, or by rejecting any construct | |
13542 | that would otherwise generate an implicit @code{for} loop. If this restriction is | |
13543 | active, it is possible to build large array aggregates with all static | |
13544 | components without generating an intermediate temporary, and without generating | |
13545 | a loop to initialize individual components. Otherwise, a loop is created for | |
13546 | arrays larger than about 5000 scalar components. Note that if this restriction | |
13547 | is set in the spec of a package, it will not apply to its body. | |
13548 | ||
13549 | @node No_Obsolescent_Features,No_Wide_Characters,No_Implicit_Loops,Program Unit Level Restrictions | |
04d6c745 | 13550 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-obsolescent-features}@anchor{21b} |
64d5610f ML |
13551 | @subsection No_Obsolescent_Features |
13552 | ||
13553 | ||
13554 | @geindex No_Obsolescent_Features | |
13555 | ||
13556 | [RM 13.12.1] This restriction checks at compile time that no obsolescent | |
13557 | features are used, as defined in Annex J of the Ada Reference Manual. | |
13558 | ||
13559 | @node No_Wide_Characters,Static_Dispatch_Tables,No_Obsolescent_Features,Program Unit Level Restrictions | |
04d6c745 | 13560 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-wide-characters}@anchor{21c} |
64d5610f ML |
13561 | @subsection No_Wide_Characters |
13562 | ||
13563 | ||
13564 | @geindex No_Wide_Characters | |
13565 | ||
13566 | [GNAT] This restriction ensures at compile time that no uses of the types | |
13567 | @code{Wide_Character} or @code{Wide_String} or corresponding wide | |
13568 | wide types | |
13569 | appear, and that no wide or wide wide string or character literals | |
13570 | appear in the program (that is literals representing characters not in | |
13571 | type @code{Character}). | |
13572 | ||
13573 | @node Static_Dispatch_Tables,SPARK_05,No_Wide_Characters,Program Unit Level Restrictions | |
04d6c745 | 13574 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions static-dispatch-tables}@anchor{21d} |
64d5610f ML |
13575 | @subsection Static_Dispatch_Tables |
13576 | ||
13577 | ||
13578 | @geindex Static_Dispatch_Tables | |
13579 | ||
13580 | [GNAT] This restriction checks at compile time that all the artifacts | |
13581 | associated with dispatch tables can be placed in read-only memory. | |
13582 | ||
13583 | @node SPARK_05,,Static_Dispatch_Tables,Program Unit Level Restrictions | |
04d6c745 | 13584 | @anchor{gnat_rm/standard_and_implementation_defined_restrictions spark-05}@anchor{21e} |
64d5610f ML |
13585 | @subsection SPARK_05 |
13586 | ||
13587 | ||
13588 | @geindex SPARK_05 | |
13589 | ||
13590 | [GNAT] This restriction no longer has any effect and is superseded by | |
13591 | SPARK 2014, whose restrictions are checked by the tool GNATprove. To check that | |
13592 | a codebase respects SPARK 2014 restrictions, mark the code with pragma or | |
13593 | aspect @code{SPARK_Mode}, and run the tool GNATprove at Stone assurance level, as | |
13594 | follows: | |
13595 | ||
13596 | @example | |
13597 | gnatprove -P project.gpr --mode=stone | |
13598 | @end example | |
13599 | ||
13600 | or equivalently: | |
13601 | ||
13602 | @example | |
13603 | gnatprove -P project.gpr --mode=check_all | |
13604 | @end example | |
13605 | ||
13606 | @node Implementation Advice,Implementation Defined Characteristics,Standard and Implementation Defined Restrictions,Top | |
04d6c745 | 13607 | @anchor{gnat_rm/implementation_advice doc}@anchor{21f}@anchor{gnat_rm/implementation_advice id1}@anchor{220}@anchor{gnat_rm/implementation_advice implementation-advice}@anchor{a} |
64d5610f ML |
13608 | @chapter Implementation Advice |
13609 | ||
13610 | ||
13611 | The main text of the Ada Reference Manual describes the required | |
13612 | behavior of all Ada compilers, and the GNAT compiler conforms to | |
13613 | these requirements. | |
13614 | ||
13615 | In addition, there are sections throughout the Ada Reference Manual headed | |
13616 | by the phrase ‘Implementation advice’. These sections are not normative, | |
13617 | i.e., they do not specify requirements that all compilers must | |
13618 | follow. Rather they provide advice on generally desirable behavior. | |
13619 | They are not requirements, because they describe behavior that cannot | |
13620 | be provided on all systems, or may be undesirable on some systems. | |
13621 | ||
13622 | As far as practical, GNAT follows the implementation advice in | |
13623 | the Ada Reference Manual. Each such RM section corresponds to a section | |
13624 | in this chapter whose title specifies the | |
13625 | RM section number and paragraph number and the subject of | |
13626 | the advice. The contents of each section consists of the RM text within | |
13627 | quotation marks, | |
13628 | followed by the GNAT interpretation of the advice. Most often, this simply says | |
13629 | ‘followed’, which means that GNAT follows the advice. However, in a | |
13630 | number of cases, GNAT deliberately deviates from this advice, in which | |
13631 | case the text describes what GNAT does and why. | |
13632 | ||
13633 | @geindex Error detection | |
13634 | ||
13635 | @menu | |
13636 | * RM 1.1.3(20); Error Detection: RM 1 1 3 20 Error Detection. | |
13637 | * RM 1.1.3(31); Child Units: RM 1 1 3 31 Child Units. | |
13638 | * RM 1.1.5(12); Bounded Errors: RM 1 1 5 12 Bounded Errors. | |
13639 | * RM 2.8(16); Pragmas: RM 2 8 16 Pragmas. | |
13640 | * RM 2.8(17-19); Pragmas: RM 2 8 17-19 Pragmas. | |
13641 | * RM 3.5.2(5); Alternative Character Sets: RM 3 5 2 5 Alternative Character Sets. | |
13642 | * RM 3.5.4(28); Integer Types: RM 3 5 4 28 Integer Types. | |
13643 | * RM 3.5.4(29); Integer Types: RM 3 5 4 29 Integer Types. | |
13644 | * RM 3.5.5(8); Enumeration Values: RM 3 5 5 8 Enumeration Values. | |
13645 | * RM 3.5.7(17); Float Types: RM 3 5 7 17 Float Types. | |
13646 | * RM 3.6.2(11); Multidimensional Arrays: RM 3 6 2 11 Multidimensional Arrays. | |
13647 | * RM 9.6(30-31); Duration’Small: RM 9 6 30-31 Duration’Small. | |
13648 | * RM 10.2.1(12); Consistent Representation: RM 10 2 1 12 Consistent Representation. | |
13649 | * RM 11.4.1(19); Exception Information: RM 11 4 1 19 Exception Information. | |
13650 | * RM 11.5(28); Suppression of Checks: RM 11 5 28 Suppression of Checks. | |
13651 | * RM 13.1 (21-24); Representation Clauses: RM 13 1 21-24 Representation Clauses. | |
13652 | * RM 13.2(6-8); Packed Types: RM 13 2 6-8 Packed Types. | |
13653 | * RM 13.3(14-19); Address Clauses: RM 13 3 14-19 Address Clauses. | |
13654 | * RM 13.3(29-35); Alignment Clauses: RM 13 3 29-35 Alignment Clauses. | |
13655 | * RM 13.3(42-43); Size Clauses: RM 13 3 42-43 Size Clauses. | |
13656 | * RM 13.3(50-56); Size Clauses: RM 13 3 50-56 Size Clauses. | |
13657 | * RM 13.3(71-73); Component Size Clauses: RM 13 3 71-73 Component Size Clauses. | |
13658 | * RM 13.4(9-10); Enumeration Representation Clauses: RM 13 4 9-10 Enumeration Representation Clauses. | |
13659 | * RM 13.5.1(17-22); Record Representation Clauses: RM 13 5 1 17-22 Record Representation Clauses. | |
13660 | * RM 13.5.2(5); Storage Place Attributes: RM 13 5 2 5 Storage Place Attributes. | |
13661 | * RM 13.5.3(7-8); Bit Ordering: RM 13 5 3 7-8 Bit Ordering. | |
13662 | * RM 13.7(37); Address as Private: RM 13 7 37 Address as Private. | |
13663 | * RM 13.7.1(16); Address Operations: RM 13 7 1 16 Address Operations. | |
13664 | * RM 13.9(14-17); Unchecked Conversion: RM 13 9 14-17 Unchecked Conversion. | |
13665 | * RM 13.11(23-25); Implicit Heap Usage: RM 13 11 23-25 Implicit Heap Usage. | |
13666 | * RM 13.11.2(17); Unchecked Deallocation: RM 13 11 2 17 Unchecked Deallocation. | |
13667 | * RM 13.13.2(1.6); Stream Oriented Attributes: RM 13 13 2 1 6 Stream Oriented Attributes. | |
13668 | * RM A.1(52); Names of Predefined Numeric Types: RM A 1 52 Names of Predefined Numeric Types. | |
13669 | * RM A.3.2(49); Ada.Characters.Handling: RM A 3 2 49 Ada Characters Handling. | |
13670 | * RM A.4.4(106); Bounded-Length String Handling: RM A 4 4 106 Bounded-Length String Handling. | |
13671 | * RM A.5.2(46-47); Random Number Generation: RM A 5 2 46-47 Random Number Generation. | |
13672 | * RM A.10.7(23); Get_Immediate: RM A 10 7 23 Get_Immediate. | |
13673 | * RM A.18; Containers: RM A 18 Containers. | |
13674 | * RM B.1(39-41); Pragma Export: RM B 1 39-41 Pragma Export. | |
13675 | * RM B.2(12-13); Package Interfaces: RM B 2 12-13 Package Interfaces. | |
13676 | * RM B.3(63-71); Interfacing with C: RM B 3 63-71 Interfacing with C. | |
13677 | * RM B.4(95-98); Interfacing with COBOL: RM B 4 95-98 Interfacing with COBOL. | |
13678 | * RM B.5(22-26); Interfacing with Fortran: RM B 5 22-26 Interfacing with Fortran. | |
13679 | * RM C.1(3-5); Access to Machine Operations: RM C 1 3-5 Access to Machine Operations. | |
13680 | * RM C.1(10-16); Access to Machine Operations: RM C 1 10-16 Access to Machine Operations. | |
13681 | * RM C.3(28); Interrupt Support: RM C 3 28 Interrupt Support. | |
13682 | * RM C.3.1(20-21); Protected Procedure Handlers: RM C 3 1 20-21 Protected Procedure Handlers. | |
13683 | * RM C.3.2(25); Package Interrupts: RM C 3 2 25 Package Interrupts. | |
13684 | * RM C.4(14); Pre-elaboration Requirements: RM C 4 14 Pre-elaboration Requirements. | |
13685 | * RM C.5(8); Pragma Discard_Names: RM C 5 8 Pragma Discard_Names. | |
13686 | * RM C.7.2(30); The Package Task_Attributes: RM C 7 2 30 The Package Task_Attributes. | |
13687 | * RM D.3(17); Locking Policies: RM D 3 17 Locking Policies. | |
13688 | * RM D.4(16); Entry Queuing Policies: RM D 4 16 Entry Queuing Policies. | |
13689 | * RM D.6(9-10); Preemptive Abort: RM D 6 9-10 Preemptive Abort. | |
13690 | * RM D.7(21); Tasking Restrictions: RM D 7 21 Tasking Restrictions. | |
13691 | * RM D.8(47-49); Monotonic Time: RM D 8 47-49 Monotonic Time. | |
13692 | * RM E.5(28-29); Partition Communication Subsystem: RM E 5 28-29 Partition Communication Subsystem. | |
13693 | * RM F(7); COBOL Support: RM F 7 COBOL Support. | |
13694 | * RM F.1(2); Decimal Radix Support: RM F 1 2 Decimal Radix Support. | |
13695 | * RM G; Numerics: RM G Numerics. | |
13696 | * RM G.1.1(56-58); Complex Types: RM G 1 1 56-58 Complex Types. | |
13697 | * RM G.1.2(49); Complex Elementary Functions: RM G 1 2 49 Complex Elementary Functions. | |
13698 | * RM G.2.4(19); Accuracy Requirements: RM G 2 4 19 Accuracy Requirements. | |
13699 | * RM G.2.6(15); Complex Arithmetic Accuracy: RM G 2 6 15 Complex Arithmetic Accuracy. | |
13700 | * RM H.6(15/2); Pragma Partition_Elaboration_Policy: RM H 6 15/2 Pragma Partition_Elaboration_Policy. | |
13701 | ||
13702 | @end menu | |
13703 | ||
13704 | @node RM 1 1 3 20 Error Detection,RM 1 1 3 31 Child Units,,Implementation Advice | |
04d6c745 | 13705 | @anchor{gnat_rm/implementation_advice rm-1-1-3-20-error-detection}@anchor{221} |
64d5610f ML |
13706 | @section RM 1.1.3(20): Error Detection |
13707 | ||
13708 | ||
13709 | @quotation | |
13710 | ||
13711 | “If an implementation detects the use of an unsupported Specialized Needs | |
13712 | Annex feature at run time, it should raise @code{Program_Error} if | |
13713 | feasible.” | |
13714 | @end quotation | |
13715 | ||
13716 | Not relevant. All specialized needs annex features are either supported, | |
13717 | or diagnosed at compile time. | |
13718 | ||
13719 | @geindex Child Units | |
13720 | ||
13721 | @node RM 1 1 3 31 Child Units,RM 1 1 5 12 Bounded Errors,RM 1 1 3 20 Error Detection,Implementation Advice | |
04d6c745 | 13722 | @anchor{gnat_rm/implementation_advice rm-1-1-3-31-child-units}@anchor{222} |
64d5610f ML |
13723 | @section RM 1.1.3(31): Child Units |
13724 | ||
13725 | ||
13726 | @quotation | |
13727 | ||
13728 | “If an implementation wishes to provide implementation-defined | |
13729 | extensions to the functionality of a language-defined library unit, it | |
13730 | should normally do so by adding children to the library unit.” | |
13731 | @end quotation | |
13732 | ||
13733 | Followed. | |
13734 | ||
13735 | @geindex Bounded errors | |
13736 | ||
13737 | @node RM 1 1 5 12 Bounded Errors,RM 2 8 16 Pragmas,RM 1 1 3 31 Child Units,Implementation Advice | |
04d6c745 | 13738 | @anchor{gnat_rm/implementation_advice rm-1-1-5-12-bounded-errors}@anchor{223} |
64d5610f ML |
13739 | @section RM 1.1.5(12): Bounded Errors |
13740 | ||
13741 | ||
13742 | @quotation | |
13743 | ||
13744 | “If an implementation detects a bounded error or erroneous | |
13745 | execution, it should raise @code{Program_Error}.” | |
13746 | @end quotation | |
13747 | ||
13748 | Followed in all cases in which the implementation detects a bounded | |
13749 | error or erroneous execution. Not all such situations are detected at | |
13750 | runtime. | |
13751 | ||
13752 | @geindex Pragmas | |
13753 | ||
13754 | @node RM 2 8 16 Pragmas,RM 2 8 17-19 Pragmas,RM 1 1 5 12 Bounded Errors,Implementation Advice | |
04d6c745 | 13755 | @anchor{gnat_rm/implementation_advice id2}@anchor{224}@anchor{gnat_rm/implementation_advice rm-2-8-16-pragmas}@anchor{225} |
64d5610f ML |
13756 | @section RM 2.8(16): Pragmas |
13757 | ||
13758 | ||
13759 | @quotation | |
13760 | ||
13761 | “Normally, implementation-defined pragmas should have no semantic effect | |
13762 | for error-free programs; that is, if the implementation-defined pragmas | |
13763 | are removed from a working program, the program should still be legal, | |
13764 | and should still have the same semantics.” | |
13765 | @end quotation | |
13766 | ||
13767 | The following implementation defined pragmas are exceptions to this | |
13768 | rule: | |
13769 | ||
13770 | ||
13771 | @multitable {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxx} | |
13772 | @headitem | |
13773 | ||
13774 | Pragma | |
13775 | ||
13776 | @tab | |
13777 | ||
13778 | Explanation | |
13779 | ||
13780 | @item | |
13781 | ||
13782 | `Abort_Defer' | |
13783 | ||
13784 | @tab | |
13785 | ||
13786 | Affects semantics | |
13787 | ||
13788 | @item | |
13789 | ||
13790 | `Ada_83' | |
13791 | ||
13792 | @tab | |
13793 | ||
13794 | Affects legality | |
13795 | ||
13796 | @item | |
13797 | ||
13798 | `Assert' | |
13799 | ||
13800 | @tab | |
13801 | ||
13802 | Affects semantics | |
13803 | ||
13804 | @item | |
13805 | ||
13806 | `CPP_Class' | |
13807 | ||
13808 | @tab | |
13809 | ||
13810 | Affects semantics | |
13811 | ||
13812 | @item | |
13813 | ||
13814 | `CPP_Constructor' | |
13815 | ||
13816 | @tab | |
13817 | ||
13818 | Affects semantics | |
13819 | ||
13820 | @item | |
13821 | ||
13822 | `Debug' | |
13823 | ||
13824 | @tab | |
13825 | ||
13826 | Affects semantics | |
13827 | ||
13828 | @item | |
13829 | ||
13830 | `Interface_Name' | |
13831 | ||
13832 | @tab | |
13833 | ||
13834 | Affects semantics | |
13835 | ||
13836 | @item | |
13837 | ||
13838 | `Machine_Attribute' | |
13839 | ||
13840 | @tab | |
13841 | ||
13842 | Affects semantics | |
13843 | ||
13844 | @item | |
13845 | ||
13846 | `Unimplemented_Unit' | |
13847 | ||
13848 | @tab | |
13849 | ||
13850 | Affects legality | |
13851 | ||
13852 | @item | |
13853 | ||
13854 | `Unchecked_Union' | |
13855 | ||
13856 | @tab | |
13857 | ||
13858 | Affects semantics | |
13859 | ||
13860 | @end multitable | |
13861 | ||
13862 | ||
13863 | In each of the above cases, it is essential to the purpose of the pragma | |
13864 | that this advice not be followed. For details see | |
13865 | @ref{7,,Implementation Defined Pragmas}. | |
13866 | ||
13867 | @node RM 2 8 17-19 Pragmas,RM 3 5 2 5 Alternative Character Sets,RM 2 8 16 Pragmas,Implementation Advice | |
04d6c745 | 13868 | @anchor{gnat_rm/implementation_advice rm-2-8-17-19-pragmas}@anchor{226} |
64d5610f ML |
13869 | @section RM 2.8(17-19): Pragmas |
13870 | ||
13871 | ||
13872 | @quotation | |
13873 | ||
13874 | “Normally, an implementation should not define pragmas that can | |
13875 | make an illegal program legal, except as follows: | |
13876 | ||
13877 | ||
13878 | @itemize * | |
13879 | ||
13880 | @item | |
13881 | A pragma used to complete a declaration, such as a pragma @code{Import}; | |
13882 | ||
13883 | @item | |
13884 | A pragma used to configure the environment by adding, removing, or | |
13885 | replacing @code{library_items}.” | |
13886 | @end itemize | |
13887 | @end quotation | |
13888 | ||
04d6c745 | 13889 | See @ref{225,,RM 2.8(16); Pragmas}. |
64d5610f ML |
13890 | |
13891 | @geindex Character Sets | |
13892 | ||
13893 | @geindex Alternative Character Sets | |
13894 | ||
13895 | @node RM 3 5 2 5 Alternative Character Sets,RM 3 5 4 28 Integer Types,RM 2 8 17-19 Pragmas,Implementation Advice | |
04d6c745 | 13896 | @anchor{gnat_rm/implementation_advice rm-3-5-2-5-alternative-character-sets}@anchor{227} |
64d5610f ML |
13897 | @section RM 3.5.2(5): Alternative Character Sets |
13898 | ||
13899 | ||
13900 | @quotation | |
13901 | ||
13902 | “If an implementation supports a mode with alternative interpretations | |
13903 | for @code{Character} and @code{Wide_Character}, the set of graphic | |
13904 | characters of @code{Character} should nevertheless remain a proper | |
13905 | subset of the set of graphic characters of @code{Wide_Character}. Any | |
13906 | character set ‘localizations’ should be reflected in the results of | |
13907 | the subprograms defined in the language-defined package | |
13908 | @code{Characters.Handling} (see A.3) available in such a mode. In a mode with | |
13909 | an alternative interpretation of @code{Character}, the implementation should | |
13910 | also support a corresponding change in what is a legal | |
13911 | @code{identifier_letter}.” | |
13912 | @end quotation | |
13913 | ||
13914 | Not all wide character modes follow this advice, in particular the JIS | |
13915 | and IEC modes reflect standard usage in Japan, and in these encoding, | |
13916 | the upper half of the Latin-1 set is not part of the wide-character | |
13917 | subset, since the most significant bit is used for wide character | |
13918 | encoding. However, this only applies to the external forms. Internally | |
13919 | there is no such restriction. | |
13920 | ||
13921 | @geindex Integer types | |
13922 | ||
13923 | @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 | |
04d6c745 | 13924 | @anchor{gnat_rm/implementation_advice rm-3-5-4-28-integer-types}@anchor{228} |
64d5610f ML |
13925 | @section RM 3.5.4(28): Integer Types |
13926 | ||
13927 | ||
13928 | @quotation | |
13929 | ||
13930 | “An implementation should support @code{Long_Integer} in addition to | |
13931 | @code{Integer} if the target machine supports 32-bit (or longer) | |
13932 | arithmetic. No other named integer subtypes are recommended for package | |
13933 | @code{Standard}. Instead, appropriate named integer subtypes should be | |
13934 | provided in the library package @code{Interfaces} (see B.2).” | |
13935 | @end quotation | |
13936 | ||
13937 | @code{Long_Integer} is supported. Other standard integer types are supported | |
13938 | so this advice is not fully followed. These types | |
13939 | are supported for convenient interface to C, and so that all hardware | |
13940 | types of the machine are easily available. | |
13941 | ||
13942 | @node RM 3 5 4 29 Integer Types,RM 3 5 5 8 Enumeration Values,RM 3 5 4 28 Integer Types,Implementation Advice | |
04d6c745 | 13943 | @anchor{gnat_rm/implementation_advice rm-3-5-4-29-integer-types}@anchor{229} |
64d5610f ML |
13944 | @section RM 3.5.4(29): Integer Types |
13945 | ||
13946 | ||
13947 | @quotation | |
13948 | ||
13949 | “An implementation for a two’s complement machine should support | |
13950 | modular types with a binary modulus up to @code{System.Max_Int*2+2}. An | |
13951 | implementation should support a non-binary modules up to @code{Integer'Last}.” | |
13952 | @end quotation | |
13953 | ||
13954 | Followed. | |
13955 | ||
13956 | @geindex Enumeration values | |
13957 | ||
13958 | @node RM 3 5 5 8 Enumeration Values,RM 3 5 7 17 Float Types,RM 3 5 4 29 Integer Types,Implementation Advice | |
04d6c745 | 13959 | @anchor{gnat_rm/implementation_advice rm-3-5-5-8-enumeration-values}@anchor{22a} |
64d5610f ML |
13960 | @section RM 3.5.5(8): Enumeration Values |
13961 | ||
13962 | ||
13963 | @quotation | |
13964 | ||
13965 | “For the evaluation of a call on @code{S'Pos} for an enumeration | |
13966 | subtype, if the value of the operand does not correspond to the internal | |
13967 | code for any enumeration literal of its type (perhaps due to an | |
13968 | un-initialized variable), then the implementation should raise | |
13969 | @code{Program_Error}. This is particularly important for enumeration | |
13970 | types with noncontiguous internal codes specified by an | |
13971 | enumeration_representation_clause.” | |
13972 | @end quotation | |
13973 | ||
13974 | Followed. | |
13975 | ||
13976 | @geindex Float types | |
13977 | ||
13978 | @node RM 3 5 7 17 Float Types,RM 3 6 2 11 Multidimensional Arrays,RM 3 5 5 8 Enumeration Values,Implementation Advice | |
04d6c745 | 13979 | @anchor{gnat_rm/implementation_advice rm-3-5-7-17-float-types}@anchor{22b} |
64d5610f ML |
13980 | @section RM 3.5.7(17): Float Types |
13981 | ||
13982 | ||
13983 | @quotation | |
13984 | ||
13985 | “An implementation should support @code{Long_Float} in addition to | |
13986 | @code{Float} if the target machine supports 11 or more digits of | |
13987 | precision. No other named floating point subtypes are recommended for | |
13988 | package @code{Standard}. Instead, appropriate named floating point subtypes | |
13989 | should be provided in the library package @code{Interfaces} (see B.2).” | |
13990 | @end quotation | |
13991 | ||
13992 | @code{Short_Float} and @code{Long_Long_Float} are also provided. The | |
13993 | former provides improved compatibility with other implementations | |
13994 | supporting this type. The latter corresponds to the highest precision | |
13995 | floating-point type supported by the hardware. On most machines, this | |
13996 | will be the same as @code{Long_Float}, but on some machines, it will | |
13997 | correspond to the IEEE extended form. The notable case is all x86 | |
13998 | implementations, where @code{Long_Long_Float} corresponds to the 80-bit | |
13999 | extended precision format supported in hardware on this processor. | |
14000 | Note that the 128-bit format on SPARC is not supported, since this | |
14001 | is a software rather than a hardware format. | |
14002 | ||
14003 | @geindex Multidimensional arrays | |
14004 | ||
14005 | @geindex Arrays | |
14006 | @geindex multidimensional | |
14007 | ||
14008 | @node RM 3 6 2 11 Multidimensional Arrays,RM 9 6 30-31 Duration’Small,RM 3 5 7 17 Float Types,Implementation Advice | |
04d6c745 | 14009 | @anchor{gnat_rm/implementation_advice rm-3-6-2-11-multidimensional-arrays}@anchor{22c} |
64d5610f ML |
14010 | @section RM 3.6.2(11): Multidimensional Arrays |
14011 | ||
14012 | ||
14013 | @quotation | |
14014 | ||
14015 | “An implementation should normally represent multidimensional arrays in | |
14016 | row-major order, consistent with the notation used for multidimensional | |
14017 | array aggregates (see 4.3.3). However, if a pragma @code{Convention} | |
14018 | (@code{Fortran}, …) applies to a multidimensional array type, then | |
14019 | column-major order should be used instead (see B.5, `Interfacing with Fortran').” | |
14020 | @end quotation | |
14021 | ||
14022 | Followed. | |
14023 | ||
14024 | @geindex Duration'Small | |
14025 | ||
14026 | @node RM 9 6 30-31 Duration’Small,RM 10 2 1 12 Consistent Representation,RM 3 6 2 11 Multidimensional Arrays,Implementation Advice | |
04d6c745 | 14027 | @anchor{gnat_rm/implementation_advice rm-9-6-30-31-duration-small}@anchor{22d} |
64d5610f ML |
14028 | @section RM 9.6(30-31): Duration’Small |
14029 | ||
14030 | ||
14031 | @quotation | |
14032 | ||
14033 | “Whenever possible in an implementation, the value of @code{Duration'Small} | |
14034 | should be no greater than 100 microseconds.” | |
14035 | @end quotation | |
14036 | ||
14037 | Followed. (@code{Duration'Small} = 10**(-9)). | |
14038 | ||
14039 | @quotation | |
14040 | ||
14041 | “The time base for @code{delay_relative_statements} should be monotonic; | |
14042 | it need not be the same time base as used for @code{Calendar.Clock}.” | |
14043 | @end quotation | |
14044 | ||
14045 | Followed. | |
14046 | ||
14047 | @node RM 10 2 1 12 Consistent Representation,RM 11 4 1 19 Exception Information,RM 9 6 30-31 Duration’Small,Implementation Advice | |
04d6c745 | 14048 | @anchor{gnat_rm/implementation_advice rm-10-2-1-12-consistent-representation}@anchor{22e} |
64d5610f ML |
14049 | @section RM 10.2.1(12): Consistent Representation |
14050 | ||
14051 | ||
14052 | @quotation | |
14053 | ||
14054 | “In an implementation, a type declared in a pre-elaborated package should | |
14055 | have the same representation in every elaboration of a given version of | |
14056 | the package, whether the elaborations occur in distinct executions of | |
14057 | the same program, or in executions of distinct programs or partitions | |
14058 | that include the given version.” | |
14059 | @end quotation | |
14060 | ||
14061 | Followed, except in the case of tagged types. Tagged types involve | |
14062 | implicit pointers to a local copy of a dispatch table, and these pointers | |
14063 | have representations which thus depend on a particular elaboration of the | |
14064 | package. It is not easy to see how it would be possible to follow this | |
14065 | advice without severely impacting efficiency of execution. | |
14066 | ||
14067 | @geindex Exception information | |
14068 | ||
14069 | @node RM 11 4 1 19 Exception Information,RM 11 5 28 Suppression of Checks,RM 10 2 1 12 Consistent Representation,Implementation Advice | |
04d6c745 | 14070 | @anchor{gnat_rm/implementation_advice rm-11-4-1-19-exception-information}@anchor{22f} |
64d5610f ML |
14071 | @section RM 11.4.1(19): Exception Information |
14072 | ||
14073 | ||
14074 | @quotation | |
14075 | ||
14076 | “@code{Exception_Message} by default and @code{Exception_Information} | |
14077 | should produce information useful for | |
14078 | debugging. @code{Exception_Message} should be short, about one | |
14079 | line. @code{Exception_Information} can be long. @code{Exception_Message} | |
14080 | should not include the | |
14081 | @code{Exception_Name}. @code{Exception_Information} should include both | |
14082 | the @code{Exception_Name} and the @code{Exception_Message}.” | |
14083 | @end quotation | |
14084 | ||
14085 | Followed. For each exception that doesn’t have a specified | |
14086 | @code{Exception_Message}, the compiler generates one containing the location | |
14087 | of the raise statement. This location has the form ‘file_name:line’, where | |
14088 | file_name is the short file name (without path information) and line is the line | |
14089 | number in the file. Note that in the case of the Zero Cost Exception | |
14090 | mechanism, these messages become redundant with the Exception_Information that | |
14091 | contains a full backtrace of the calling sequence, so they are disabled. | |
14092 | To disable explicitly the generation of the source location message, use the | |
14093 | Pragma @code{Discard_Names}. | |
14094 | ||
14095 | @geindex Suppression of checks | |
14096 | ||
14097 | @geindex Checks | |
14098 | @geindex suppression of | |
14099 | ||
14100 | @node RM 11 5 28 Suppression of Checks,RM 13 1 21-24 Representation Clauses,RM 11 4 1 19 Exception Information,Implementation Advice | |
04d6c745 | 14101 | @anchor{gnat_rm/implementation_advice rm-11-5-28-suppression-of-checks}@anchor{230} |
64d5610f ML |
14102 | @section RM 11.5(28): Suppression of Checks |
14103 | ||
14104 | ||
14105 | @quotation | |
14106 | ||
14107 | “The implementation should minimize the code executed for checks that | |
14108 | have been suppressed.” | |
14109 | @end quotation | |
14110 | ||
14111 | Followed. | |
14112 | ||
14113 | @geindex Representation clauses | |
14114 | ||
14115 | @node RM 13 1 21-24 Representation Clauses,RM 13 2 6-8 Packed Types,RM 11 5 28 Suppression of Checks,Implementation Advice | |
04d6c745 | 14116 | @anchor{gnat_rm/implementation_advice rm-13-1-21-24-representation-clauses}@anchor{231} |
64d5610f ML |
14117 | @section RM 13.1 (21-24): Representation Clauses |
14118 | ||
14119 | ||
14120 | @quotation | |
14121 | ||
14122 | “The recommended level of support for all representation items is | |
14123 | qualified as follows: | |
14124 | ||
14125 | An implementation need not support representation items containing | |
14126 | nonstatic expressions, except that an implementation should support a | |
14127 | representation item for a given entity if each nonstatic expression in | |
14128 | the representation item is a name that statically denotes a constant | |
14129 | declared before the entity.” | |
14130 | @end quotation | |
14131 | ||
14132 | Followed. In fact, GNAT goes beyond the recommended level of support | |
14133 | by allowing nonstatic expressions in some representation clauses even | |
14134 | without the need to declare constants initialized with the values of | |
14135 | such expressions. | |
14136 | For example: | |
14137 | ||
14138 | @example | |
14139 | X : Integer; | |
14140 | Y : Float; | |
14141 | for Y'Address use X'Address;>> | |
14142 | ||
14143 | ||
14144 | "An implementation need not support a specification for the `@w{`}Size`@w{`} | |
14145 | for a given composite subtype, nor the size or storage place for an | |
14146 | object (including a component) of a given composite subtype, unless the | |
14147 | constraints on the subtype and its composite subcomponents (if any) are | |
14148 | all static constraints." | |
14149 | @end example | |
14150 | ||
14151 | Followed. Size Clauses are not permitted on nonstatic components, as | |
14152 | described above. | |
14153 | ||
14154 | @quotation | |
14155 | ||
14156 | “An aliased component, or a component whose type is by-reference, should | |
14157 | always be allocated at an addressable location.” | |
14158 | @end quotation | |
14159 | ||
14160 | Followed. | |
14161 | ||
14162 | @geindex Packed types | |
14163 | ||
14164 | @node RM 13 2 6-8 Packed Types,RM 13 3 14-19 Address Clauses,RM 13 1 21-24 Representation Clauses,Implementation Advice | |
04d6c745 | 14165 | @anchor{gnat_rm/implementation_advice rm-13-2-6-8-packed-types}@anchor{232} |
64d5610f ML |
14166 | @section RM 13.2(6-8): Packed Types |
14167 | ||
14168 | ||
14169 | @quotation | |
14170 | ||
14171 | “If a type is packed, then the implementation should try to minimize | |
14172 | storage allocated to objects of the type, possibly at the expense of | |
14173 | speed of accessing components, subject to reasonable complexity in | |
14174 | addressing calculations. | |
14175 | ||
14176 | The recommended level of support pragma @code{Pack} is: | |
14177 | ||
14178 | For a packed record type, the components should be packed as tightly as | |
14179 | possible subject to the Sizes of the component subtypes, and subject to | |
14180 | any `record_representation_clause' that applies to the type; the | |
14181 | implementation may, but need not, reorder components or cross aligned | |
14182 | word boundaries to improve the packing. A component whose @code{Size} is | |
14183 | greater than the word size may be allocated an integral number of words.” | |
14184 | @end quotation | |
14185 | ||
14186 | Followed. Tight packing of arrays is supported for all component sizes | |
14187 | up to 64-bits. If the array component size is 1 (that is to say, if | |
14188 | the component is a boolean type or an enumeration type with two values) | |
14189 | then values of the type are implicitly initialized to zero. This | |
14190 | happens both for objects of the packed type, and for objects that have a | |
14191 | subcomponent of the packed type. | |
14192 | ||
14193 | @geindex Address clauses | |
14194 | ||
14195 | @node RM 13 3 14-19 Address Clauses,RM 13 3 29-35 Alignment Clauses,RM 13 2 6-8 Packed Types,Implementation Advice | |
04d6c745 | 14196 | @anchor{gnat_rm/implementation_advice rm-13-3-14-19-address-clauses}@anchor{233} |
64d5610f ML |
14197 | @section RM 13.3(14-19): Address Clauses |
14198 | ||
14199 | ||
14200 | @quotation | |
14201 | ||
14202 | “For an array @code{X}, @code{X'Address} should point at the first | |
14203 | component of the array, and not at the array bounds.” | |
14204 | @end quotation | |
14205 | ||
14206 | Followed. | |
14207 | ||
14208 | @quotation | |
14209 | ||
14210 | “The recommended level of support for the @code{Address} attribute is: | |
14211 | ||
14212 | @code{X'Address} should produce a useful result if @code{X} is an | |
14213 | object that is aliased or of a by-reference type, or is an entity whose | |
14214 | @code{Address} has been specified.” | |
14215 | @end quotation | |
14216 | ||
14217 | Followed. A valid address will be produced even if none of those | |
14218 | conditions have been met. If necessary, the object is forced into | |
14219 | memory to ensure the address is valid. | |
14220 | ||
14221 | @quotation | |
14222 | ||
14223 | “An implementation should support @code{Address} clauses for imported | |
14224 | subprograms.” | |
14225 | @end quotation | |
14226 | ||
14227 | Followed. | |
14228 | ||
14229 | @quotation | |
14230 | ||
14231 | “Objects (including subcomponents) that are aliased or of a by-reference | |
14232 | type should be allocated on storage element boundaries.” | |
14233 | @end quotation | |
14234 | ||
14235 | Followed. | |
14236 | ||
14237 | @quotation | |
14238 | ||
14239 | “If the @code{Address} of an object is specified, or it is imported or exported, | |
14240 | then the implementation should not perform optimizations based on | |
14241 | assumptions of no aliases.” | |
14242 | @end quotation | |
14243 | ||
14244 | Followed. | |
14245 | ||
14246 | @geindex Alignment clauses | |
14247 | ||
14248 | @node RM 13 3 29-35 Alignment Clauses,RM 13 3 42-43 Size Clauses,RM 13 3 14-19 Address Clauses,Implementation Advice | |
04d6c745 | 14249 | @anchor{gnat_rm/implementation_advice rm-13-3-29-35-alignment-clauses}@anchor{234} |
64d5610f ML |
14250 | @section RM 13.3(29-35): Alignment Clauses |
14251 | ||
14252 | ||
14253 | @quotation | |
14254 | ||
14255 | “The recommended level of support for the @code{Alignment} attribute for | |
14256 | subtypes is: | |
14257 | ||
14258 | An implementation should support specified Alignments that are factors | |
14259 | and multiples of the number of storage elements per word, subject to the | |
14260 | following:” | |
14261 | @end quotation | |
14262 | ||
14263 | Followed. | |
14264 | ||
14265 | @quotation | |
14266 | ||
14267 | “An implementation need not support specified Alignments for | |
14268 | combinations of Sizes and Alignments that cannot be easily | |
14269 | loaded and stored by available machine instructions.” | |
14270 | @end quotation | |
14271 | ||
14272 | Followed. | |
14273 | ||
14274 | @quotation | |
14275 | ||
14276 | “An implementation need not support specified Alignments that are | |
14277 | greater than the maximum @code{Alignment} the implementation ever returns by | |
14278 | default.” | |
14279 | @end quotation | |
14280 | ||
14281 | Followed. | |
14282 | ||
14283 | @quotation | |
14284 | ||
14285 | “The recommended level of support for the @code{Alignment} attribute for | |
14286 | objects is: | |
14287 | ||
14288 | Same as above, for subtypes, but in addition:” | |
14289 | @end quotation | |
14290 | ||
14291 | Followed. | |
14292 | ||
14293 | @quotation | |
14294 | ||
14295 | “For stand-alone library-level objects of statically constrained | |
14296 | subtypes, the implementation should support all alignments | |
14297 | supported by the target linker. For example, page alignment is likely to | |
14298 | be supported for such objects, but not for subtypes.” | |
14299 | @end quotation | |
14300 | ||
14301 | Followed. | |
14302 | ||
14303 | @geindex Size clauses | |
14304 | ||
14305 | @node RM 13 3 42-43 Size Clauses,RM 13 3 50-56 Size Clauses,RM 13 3 29-35 Alignment Clauses,Implementation Advice | |
04d6c745 | 14306 | @anchor{gnat_rm/implementation_advice rm-13-3-42-43-size-clauses}@anchor{235} |
64d5610f ML |
14307 | @section RM 13.3(42-43): Size Clauses |
14308 | ||
14309 | ||
14310 | @quotation | |
14311 | ||
14312 | “The recommended level of support for the @code{Size} attribute of | |
14313 | objects is: | |
14314 | ||
14315 | A @code{Size} clause should be supported for an object if the specified | |
14316 | @code{Size} is at least as large as its subtype’s @code{Size}, and | |
14317 | corresponds to a size in storage elements that is a multiple of the | |
14318 | object’s @code{Alignment} (if the @code{Alignment} is nonzero).” | |
14319 | @end quotation | |
14320 | ||
14321 | Followed. | |
14322 | ||
14323 | @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 | |
04d6c745 | 14324 | @anchor{gnat_rm/implementation_advice rm-13-3-50-56-size-clauses}@anchor{236} |
64d5610f ML |
14325 | @section RM 13.3(50-56): Size Clauses |
14326 | ||
14327 | ||
14328 | @quotation | |
14329 | ||
14330 | “If the @code{Size} of a subtype is specified, and allows for efficient | |
14331 | independent addressability (see 9.10) on the target architecture, then | |
14332 | the @code{Size} of the following objects of the subtype should equal the | |
14333 | @code{Size} of the subtype: | |
14334 | ||
14335 | Aliased objects (including components).” | |
14336 | @end quotation | |
14337 | ||
14338 | Followed. | |
14339 | ||
14340 | @quotation | |
14341 | ||
14342 | “@cite{Size} clause on a composite subtype should not affect the | |
14343 | internal layout of components.” | |
14344 | @end quotation | |
14345 | ||
14346 | Followed. But note that this can be overridden by use of the implementation | |
14347 | pragma Implicit_Packing in the case of packed arrays. | |
14348 | ||
14349 | @quotation | |
14350 | ||
14351 | “The recommended level of support for the @code{Size} attribute of subtypes is: | |
14352 | ||
14353 | The @code{Size} (if not specified) of a static discrete or fixed point | |
14354 | subtype should be the number of bits needed to represent each value | |
14355 | belonging to the subtype using an unbiased representation, leaving space | |
14356 | for a sign bit only if the subtype contains negative values. If such a | |
14357 | subtype is a first subtype, then an implementation should support a | |
14358 | specified @code{Size} for it that reflects this representation.” | |
14359 | @end quotation | |
14360 | ||
14361 | Followed. | |
14362 | ||
14363 | @quotation | |
14364 | ||
14365 | “For a subtype implemented with levels of indirection, the @code{Size} | |
14366 | should include the size of the pointers, but not the size of what they | |
14367 | point at.” | |
14368 | @end quotation | |
14369 | ||
14370 | Followed. | |
14371 | ||
14372 | @geindex Component_Size clauses | |
14373 | ||
14374 | @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 | |
04d6c745 | 14375 | @anchor{gnat_rm/implementation_advice rm-13-3-71-73-component-size-clauses}@anchor{237} |
64d5610f ML |
14376 | @section RM 13.3(71-73): Component Size Clauses |
14377 | ||
14378 | ||
14379 | @quotation | |
14380 | ||
14381 | “The recommended level of support for the @code{Component_Size} | |
14382 | attribute is: | |
14383 | ||
14384 | An implementation need not support specified @code{Component_Sizes} that are | |
14385 | less than the @code{Size} of the component subtype.” | |
14386 | @end quotation | |
14387 | ||
14388 | Followed. | |
14389 | ||
14390 | @quotation | |
14391 | ||
14392 | “An implementation should support specified Component_Sizes that | |
14393 | are factors and multiples of the word size. For such | |
14394 | Component_Sizes, the array should contain no gaps between | |
14395 | components. For other Component_Sizes (if supported), the array | |
14396 | should contain no gaps between components when packing is also | |
14397 | specified; the implementation should forbid this combination in cases | |
14398 | where it cannot support a no-gaps representation.” | |
14399 | @end quotation | |
14400 | ||
14401 | Followed. | |
14402 | ||
14403 | @geindex Enumeration representation clauses | |
14404 | ||
14405 | @geindex Representation clauses | |
14406 | @geindex enumeration | |
14407 | ||
14408 | @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 | |
04d6c745 | 14409 | @anchor{gnat_rm/implementation_advice rm-13-4-9-10-enumeration-representation-clauses}@anchor{238} |
64d5610f ML |
14410 | @section RM 13.4(9-10): Enumeration Representation Clauses |
14411 | ||
14412 | ||
14413 | @quotation | |
14414 | ||
14415 | “The recommended level of support for enumeration representation clauses | |
14416 | is: | |
14417 | ||
14418 | An implementation need not support enumeration representation clauses | |
14419 | for boolean types, but should at minimum support the internal codes in | |
14420 | the range @code{System.Min_Int .. System.Max_Int}.” | |
14421 | @end quotation | |
14422 | ||
14423 | Followed. | |
14424 | ||
14425 | @geindex Record representation clauses | |
14426 | ||
14427 | @geindex Representation clauses | |
14428 | @geindex records | |
14429 | ||
14430 | @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 | |
04d6c745 | 14431 | @anchor{gnat_rm/implementation_advice rm-13-5-1-17-22-record-representation-clauses}@anchor{239} |
64d5610f ML |
14432 | @section RM 13.5.1(17-22): Record Representation Clauses |
14433 | ||
14434 | ||
14435 | @quotation | |
14436 | ||
14437 | “The recommended level of support for | |
14438 | `record_representation_clause's is: | |
14439 | ||
14440 | An implementation should support storage places that can be extracted | |
14441 | with a load, mask, shift sequence of machine code, and set with a load, | |
14442 | shift, mask, store sequence, given the available machine instructions | |
14443 | and run-time model.” | |
14444 | @end quotation | |
14445 | ||
14446 | Followed. | |
14447 | ||
14448 | @quotation | |
14449 | ||
14450 | “A storage place should be supported if its size is equal to the | |
14451 | @code{Size} of the component subtype, and it starts and ends on a | |
14452 | boundary that obeys the @code{Alignment} of the component subtype.” | |
14453 | @end quotation | |
14454 | ||
14455 | Followed. | |
14456 | ||
14457 | @quotation | |
14458 | ||
14459 | “If the default bit ordering applies to the declaration of a given type, | |
14460 | then for a component whose subtype’s @code{Size} is less than the word | |
14461 | size, any storage place that does not cross an aligned word boundary | |
14462 | should be supported.” | |
14463 | @end quotation | |
14464 | ||
14465 | Followed. | |
14466 | ||
14467 | @quotation | |
14468 | ||
14469 | “An implementation may reserve a storage place for the tag field of a | |
14470 | tagged type, and disallow other components from overlapping that place.” | |
14471 | @end quotation | |
14472 | ||
14473 | Followed. The storage place for the tag field is the beginning of the tagged | |
14474 | record, and its size is Address’Size. GNAT will reject an explicit component | |
14475 | clause for the tag field. | |
14476 | ||
14477 | @quotation | |
14478 | ||
14479 | “An implementation need not support a `component_clause' for a | |
14480 | component of an extension part if the storage place is not after the | |
14481 | storage places of all components of the parent type, whether or not | |
14482 | those storage places had been specified.” | |
14483 | @end quotation | |
14484 | ||
14485 | Followed. The above advice on record representation clauses is followed, | |
14486 | and all mentioned features are implemented. | |
14487 | ||
14488 | @geindex Storage place attributes | |
14489 | ||
14490 | @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 | |
04d6c745 | 14491 | @anchor{gnat_rm/implementation_advice rm-13-5-2-5-storage-place-attributes}@anchor{23a} |
64d5610f ML |
14492 | @section RM 13.5.2(5): Storage Place Attributes |
14493 | ||
14494 | ||
14495 | @quotation | |
14496 | ||
14497 | “If a component is represented using some form of pointer (such as an | |
14498 | offset) to the actual data of the component, and this data is contiguous | |
14499 | with the rest of the object, then the storage place attributes should | |
14500 | reflect the place of the actual data, not the pointer. If a component is | |
14501 | allocated discontinuously from the rest of the object, then a warning | |
14502 | should be generated upon reference to one of its storage place | |
14503 | attributes.” | |
14504 | @end quotation | |
14505 | ||
14506 | Followed. There are no such components in GNAT. | |
14507 | ||
14508 | @geindex Bit ordering | |
14509 | ||
14510 | @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 | |
04d6c745 | 14511 | @anchor{gnat_rm/implementation_advice rm-13-5-3-7-8-bit-ordering}@anchor{23b} |
64d5610f ML |
14512 | @section RM 13.5.3(7-8): Bit Ordering |
14513 | ||
14514 | ||
14515 | @quotation | |
14516 | ||
14517 | “The recommended level of support for the non-default bit ordering is: | |
14518 | ||
14519 | If @code{Word_Size} = @code{Storage_Unit}, then the implementation | |
14520 | should support the non-default bit ordering in addition to the default | |
14521 | bit ordering.” | |
14522 | @end quotation | |
14523 | ||
14524 | Followed. Word size does not equal storage size in this implementation. | |
14525 | Thus non-default bit ordering is not supported. | |
14526 | ||
14527 | @geindex Address | |
14528 | @geindex as private type | |
14529 | ||
14530 | @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 | |
04d6c745 | 14531 | @anchor{gnat_rm/implementation_advice rm-13-7-37-address-as-private}@anchor{23c} |
64d5610f ML |
14532 | @section RM 13.7(37): Address as Private |
14533 | ||
14534 | ||
14535 | @quotation | |
14536 | ||
14537 | “@cite{Address} should be of a private type.” | |
14538 | @end quotation | |
14539 | ||
14540 | Followed. | |
14541 | ||
14542 | @geindex Operations | |
14543 | @geindex on `@w{`}Address`@w{`} | |
14544 | ||
14545 | @geindex Address | |
14546 | @geindex operations of | |
14547 | ||
14548 | @node RM 13 7 1 16 Address Operations,RM 13 9 14-17 Unchecked Conversion,RM 13 7 37 Address as Private,Implementation Advice | |
04d6c745 | 14549 | @anchor{gnat_rm/implementation_advice rm-13-7-1-16-address-operations}@anchor{23d} |
64d5610f ML |
14550 | @section RM 13.7.1(16): Address Operations |
14551 | ||
14552 | ||
14553 | @quotation | |
14554 | ||
14555 | “Operations in @code{System} and its children should reflect the target | |
14556 | environment semantics as closely as is reasonable. For example, on most | |
14557 | machines, it makes sense for address arithmetic to ‘wrap around’. | |
14558 | Operations that do not make sense should raise @code{Program_Error}.” | |
14559 | @end quotation | |
14560 | ||
14561 | Followed. Address arithmetic is modular arithmetic that wraps around. No | |
14562 | operation raises @code{Program_Error}, since all operations make sense. | |
14563 | ||
14564 | @geindex Unchecked conversion | |
14565 | ||
14566 | @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 | |
04d6c745 | 14567 | @anchor{gnat_rm/implementation_advice rm-13-9-14-17-unchecked-conversion}@anchor{23e} |
64d5610f ML |
14568 | @section RM 13.9(14-17): Unchecked Conversion |
14569 | ||
14570 | ||
14571 | @quotation | |
14572 | ||
14573 | “The @code{Size} of an array object should not include its bounds; hence, | |
14574 | the bounds should not be part of the converted data.” | |
14575 | @end quotation | |
14576 | ||
14577 | Followed. | |
14578 | ||
14579 | @quotation | |
14580 | ||
14581 | “The implementation should not generate unnecessary run-time checks to | |
14582 | ensure that the representation of @code{S} is a representation of the | |
14583 | target type. It should take advantage of the permission to return by | |
14584 | reference when possible. Restrictions on unchecked conversions should be | |
14585 | avoided unless required by the target environment.” | |
14586 | @end quotation | |
14587 | ||
14588 | Followed. There are no restrictions on unchecked conversion. A warning is | |
14589 | generated if the source and target types do not have the same size since | |
14590 | the semantics in this case may be target dependent. | |
14591 | ||
14592 | @quotation | |
14593 | ||
14594 | “The recommended level of support for unchecked conversions is: | |
14595 | ||
14596 | Unchecked conversions should be supported and should be reversible in | |
14597 | the cases where this clause defines the result. To enable meaningful use | |
14598 | of unchecked conversion, a contiguous representation should be used for | |
14599 | elementary subtypes, for statically constrained array subtypes whose | |
14600 | component subtype is one of the subtypes described in this paragraph, | |
14601 | and for record subtypes without discriminants whose component subtypes | |
14602 | are described in this paragraph.” | |
14603 | @end quotation | |
14604 | ||
14605 | Followed. | |
14606 | ||
14607 | @geindex Heap usage | |
14608 | @geindex implicit | |
14609 | ||
14610 | @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 | |
04d6c745 | 14611 | @anchor{gnat_rm/implementation_advice rm-13-11-23-25-implicit-heap-usage}@anchor{23f} |
64d5610f ML |
14612 | @section RM 13.11(23-25): Implicit Heap Usage |
14613 | ||
14614 | ||
14615 | @quotation | |
14616 | ||
14617 | “An implementation should document any cases in which it dynamically | |
14618 | allocates heap storage for a purpose other than the evaluation of an | |
14619 | allocator.” | |
14620 | @end quotation | |
14621 | ||
14622 | Followed, the only other points at which heap storage is dynamically | |
14623 | allocated are as follows: | |
14624 | ||
14625 | ||
14626 | @itemize * | |
14627 | ||
14628 | @item | |
14629 | At initial elaboration time, to allocate dynamically sized global | |
14630 | objects. | |
14631 | ||
14632 | @item | |
14633 | To allocate space for a task when a task is created. | |
14634 | ||
14635 | @item | |
14636 | To extend the secondary stack dynamically when needed. The secondary | |
14637 | stack is used for returning variable length results. | |
14638 | @end itemize | |
14639 | ||
14640 | ||
14641 | @quotation | |
14642 | ||
14643 | “A default (implementation-provided) storage pool for an | |
14644 | access-to-constant type should not have overhead to support deallocation of | |
14645 | individual objects.” | |
14646 | @end quotation | |
14647 | ||
14648 | Followed. | |
14649 | ||
14650 | @quotation | |
14651 | ||
14652 | “A storage pool for an anonymous access type should be created at the | |
14653 | point of an allocator for the type, and be reclaimed when the designated | |
14654 | object becomes inaccessible.” | |
14655 | @end quotation | |
14656 | ||
14657 | Followed. | |
14658 | ||
14659 | @geindex Unchecked deallocation | |
14660 | ||
14661 | @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 | |
04d6c745 | 14662 | @anchor{gnat_rm/implementation_advice rm-13-11-2-17-unchecked-deallocation}@anchor{240} |
64d5610f ML |
14663 | @section RM 13.11.2(17): Unchecked Deallocation |
14664 | ||
14665 | ||
14666 | @quotation | |
14667 | ||
14668 | “For a standard storage pool, @code{Free} should actually reclaim the | |
14669 | storage.” | |
14670 | @end quotation | |
14671 | ||
14672 | Followed. | |
14673 | ||
14674 | @geindex Stream oriented attributes | |
14675 | ||
14676 | @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 | |
04d6c745 | 14677 | @anchor{gnat_rm/implementation_advice rm-13-13-2-1-6-stream-oriented-attributes}@anchor{241} |
64d5610f ML |
14678 | @section RM 13.13.2(1.6): Stream Oriented Attributes |
14679 | ||
14680 | ||
14681 | @quotation | |
14682 | ||
14683 | “If not specified, the value of Stream_Size for an elementary type | |
14684 | should be the number of bits that corresponds to the minimum number of | |
14685 | stream elements required by the first subtype of the type, rounded up | |
14686 | to the nearest factor or multiple of the word size that is also a | |
14687 | multiple of the stream element size.” | |
14688 | @end quotation | |
14689 | ||
14690 | Followed, except that the number of stream elements is 1, 2, 3, 4 or 8. | |
14691 | The Stream_Size may be used to override the default choice. | |
14692 | ||
14693 | The default implementation is based on direct binary representations and is | |
14694 | therefore target- and endianness-dependent. To address this issue, GNAT also | |
14695 | supplies an alternate implementation of the stream attributes @code{Read} and | |
14696 | @code{Write}, which uses the target-independent XDR standard representation for | |
14697 | scalar types. This XDR alternative can be enabled via the binder switch -xdr. | |
14698 | ||
14699 | @geindex XDR representation | |
14700 | ||
14701 | @geindex Read attribute | |
14702 | ||
14703 | @geindex Write attribute | |
14704 | ||
14705 | @geindex Stream oriented attributes | |
14706 | ||
14707 | @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 | |
04d6c745 | 14708 | @anchor{gnat_rm/implementation_advice rm-a-1-52-names-of-predefined-numeric-types}@anchor{242} |
64d5610f ML |
14709 | @section RM A.1(52): Names of Predefined Numeric Types |
14710 | ||
14711 | ||
14712 | @quotation | |
14713 | ||
14714 | “If an implementation provides additional named predefined integer types, | |
14715 | then the names should end with @code{Integer} as in | |
14716 | @code{Long_Integer}. If an implementation provides additional named | |
14717 | predefined floating point types, then the names should end with | |
14718 | @code{Float} as in @code{Long_Float}.” | |
14719 | @end quotation | |
14720 | ||
14721 | Followed. | |
14722 | ||
14723 | @geindex Ada.Characters.Handling | |
14724 | ||
14725 | @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 | |
04d6c745 | 14726 | @anchor{gnat_rm/implementation_advice rm-a-3-2-49-ada-characters-handling}@anchor{243} |
64d5610f ML |
14727 | @section RM A.3.2(49): @code{Ada.Characters.Handling} |
14728 | ||
14729 | ||
14730 | @quotation | |
14731 | ||
14732 | “If an implementation provides a localized definition of @code{Character} | |
14733 | or @code{Wide_Character}, then the effects of the subprograms in | |
14734 | @code{Characters.Handling} should reflect the localizations. | |
14735 | See also 3.5.2.” | |
14736 | @end quotation | |
14737 | ||
14738 | Followed. GNAT provides no such localized definitions. | |
14739 | ||
14740 | @geindex Bounded-length strings | |
14741 | ||
14742 | @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 | |
04d6c745 | 14743 | @anchor{gnat_rm/implementation_advice rm-a-4-4-106-bounded-length-string-handling}@anchor{244} |
64d5610f ML |
14744 | @section RM A.4.4(106): Bounded-Length String Handling |
14745 | ||
14746 | ||
14747 | @quotation | |
14748 | ||
14749 | “Bounded string objects should not be implemented by implicit pointers | |
14750 | and dynamic allocation.” | |
14751 | @end quotation | |
14752 | ||
14753 | Followed. No implicit pointers or dynamic allocation are used. | |
14754 | ||
14755 | @geindex Random number generation | |
14756 | ||
14757 | @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 | |
04d6c745 | 14758 | @anchor{gnat_rm/implementation_advice rm-a-5-2-46-47-random-number-generation}@anchor{245} |
64d5610f ML |
14759 | @section RM A.5.2(46-47): Random Number Generation |
14760 | ||
14761 | ||
14762 | @quotation | |
14763 | ||
14764 | “Any storage associated with an object of type @code{Generator} should be | |
14765 | reclaimed on exit from the scope of the object.” | |
14766 | @end quotation | |
14767 | ||
14768 | Followed. | |
14769 | ||
14770 | @quotation | |
14771 | ||
14772 | “If the generator period is sufficiently long in relation to the number | |
14773 | of distinct initiator values, then each possible value of | |
14774 | @code{Initiator} passed to @code{Reset} should initiate a sequence of | |
14775 | random numbers that does not, in a practical sense, overlap the sequence | |
14776 | initiated by any other value. If this is not possible, then the mapping | |
14777 | between initiator values and generator states should be a rapidly | |
14778 | varying function of the initiator value.” | |
14779 | @end quotation | |
14780 | ||
14781 | Followed. The generator period is sufficiently long for the first | |
14782 | condition here to hold true. | |
14783 | ||
14784 | @geindex Get_Immediate | |
14785 | ||
14786 | @node RM A 10 7 23 Get_Immediate,RM A 18 Containers,RM A 5 2 46-47 Random Number Generation,Implementation Advice | |
04d6c745 | 14787 | @anchor{gnat_rm/implementation_advice rm-a-10-7-23-get-immediate}@anchor{246} |
64d5610f ML |
14788 | @section RM A.10.7(23): @code{Get_Immediate} |
14789 | ||
14790 | ||
14791 | @quotation | |
14792 | ||
14793 | “The @code{Get_Immediate} procedures should be implemented with | |
14794 | unbuffered input. For a device such as a keyboard, input should be | |
14795 | available if a key has already been typed, whereas for a disk | |
14796 | file, input should always be available except at end of file. For a file | |
14797 | associated with a keyboard-like device, any line-editing features of the | |
14798 | underlying operating system should be disabled during the execution of | |
14799 | @code{Get_Immediate}.” | |
14800 | @end quotation | |
14801 | ||
14802 | Followed on all targets except VxWorks. For VxWorks, there is no way to | |
14803 | provide this functionality that does not result in the input buffer being | |
14804 | flushed before the @code{Get_Immediate} call. A special unit | |
14805 | @code{Interfaces.Vxworks.IO} is provided that contains routines to enable | |
14806 | this functionality. | |
14807 | ||
14808 | @geindex Containers | |
14809 | ||
14810 | @node RM A 18 Containers,RM B 1 39-41 Pragma Export,RM A 10 7 23 Get_Immediate,Implementation Advice | |
04d6c745 | 14811 | @anchor{gnat_rm/implementation_advice rm-a-18-containers}@anchor{247} |
64d5610f ML |
14812 | @section RM A.18: @code{Containers} |
14813 | ||
14814 | ||
14815 | All implementation advice pertaining to Ada.Containers and its | |
14816 | child units (that is, all implementation advice occurring within | |
14817 | section A.18 and its subsections) is followed except for A.18.24(17): | |
14818 | ||
14819 | @quotation | |
14820 | ||
14821 | “Bounded ordered set objects should be implemented without implicit pointers or dynamic allocation. “ | |
14822 | @end quotation | |
14823 | ||
14824 | The implementations of the two Reference_Preserving_Key functions of | |
14825 | the generic package Ada.Containers.Bounded_Ordered_Sets each currently make | |
14826 | use of dynamic allocation; other operations on bounded ordered set objects | |
14827 | follow the implementation advice. | |
14828 | ||
14829 | @geindex Export | |
14830 | ||
14831 | @node RM B 1 39-41 Pragma Export,RM B 2 12-13 Package Interfaces,RM A 18 Containers,Implementation Advice | |
04d6c745 | 14832 | @anchor{gnat_rm/implementation_advice rm-b-1-39-41-pragma-export}@anchor{248} |
64d5610f ML |
14833 | @section RM B.1(39-41): Pragma @code{Export} |
14834 | ||
14835 | ||
14836 | @quotation | |
14837 | ||
14838 | “If an implementation supports pragma @code{Export} to a given language, | |
14839 | then it should also allow the main subprogram to be written in that | |
14840 | language. It should support some mechanism for invoking the elaboration | |
14841 | of the Ada library units included in the system, and for invoking the | |
14842 | finalization of the environment task. On typical systems, the | |
14843 | recommended mechanism is to provide two subprograms whose link names are | |
14844 | @code{adainit} and @code{adafinal}. @code{adainit} should contain the | |
14845 | elaboration code for library units. @code{adafinal} should contain the | |
14846 | finalization code. These subprograms should have no effect the second | |
14847 | and subsequent time they are called.” | |
14848 | @end quotation | |
14849 | ||
14850 | Followed. | |
14851 | ||
14852 | @quotation | |
14853 | ||
14854 | “Automatic elaboration of pre-elaborated packages should be | |
14855 | provided when pragma @code{Export} is supported.” | |
14856 | @end quotation | |
14857 | ||
14858 | Followed when the main program is in Ada. If the main program is in a | |
14859 | foreign language, then | |
14860 | @code{adainit} must be called to elaborate pre-elaborated | |
14861 | packages. | |
14862 | ||
14863 | @quotation | |
14864 | ||
14865 | “For each supported convention `L' other than @code{Intrinsic}, an | |
14866 | implementation should support @code{Import} and @code{Export} pragmas | |
14867 | for objects of `L'-compatible types and for subprograms, and pragma | |
14868 | @cite{Convention} for `L'-eligible types and for subprograms, | |
14869 | presuming the other language has corresponding features. Pragma | |
14870 | @code{Convention} need not be supported for scalar types.” | |
14871 | @end quotation | |
14872 | ||
14873 | Followed. | |
14874 | ||
14875 | @geindex Package Interfaces | |
14876 | ||
14877 | @geindex Interfaces | |
14878 | ||
14879 | @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 | |
04d6c745 | 14880 | @anchor{gnat_rm/implementation_advice rm-b-2-12-13-package-interfaces}@anchor{249} |
64d5610f ML |
14881 | @section RM B.2(12-13): Package @code{Interfaces} |
14882 | ||
14883 | ||
14884 | @quotation | |
14885 | ||
14886 | “For each implementation-defined convention identifier, there should be a | |
14887 | child package of package Interfaces with the corresponding name. This | |
14888 | package should contain any declarations that would be useful for | |
14889 | interfacing to the language (implementation) represented by the | |
14890 | convention. Any declarations useful for interfacing to any language on | |
14891 | the given hardware architecture should be provided directly in | |
14892 | @code{Interfaces}.” | |
14893 | @end quotation | |
14894 | ||
14895 | Followed. | |
14896 | ||
14897 | @quotation | |
14898 | ||
14899 | “An implementation supporting an interface to C, COBOL, or Fortran should | |
14900 | provide the corresponding package or packages described in the following | |
14901 | clauses.” | |
14902 | @end quotation | |
14903 | ||
14904 | Followed. GNAT provides all the packages described in this section. | |
14905 | ||
14906 | @geindex C | |
14907 | @geindex interfacing with | |
14908 | ||
14909 | @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 | |
04d6c745 | 14910 | @anchor{gnat_rm/implementation_advice rm-b-3-63-71-interfacing-with-c}@anchor{24a} |
64d5610f ML |
14911 | @section RM B.3(63-71): Interfacing with C |
14912 | ||
14913 | ||
14914 | @quotation | |
14915 | ||
14916 | “An implementation should support the following interface correspondences | |
14917 | between Ada and C.” | |
14918 | @end quotation | |
14919 | ||
14920 | Followed. | |
14921 | ||
14922 | @quotation | |
14923 | ||
14924 | “An Ada procedure corresponds to a void-returning C function.” | |
14925 | @end quotation | |
14926 | ||
14927 | Followed. | |
14928 | ||
14929 | @quotation | |
14930 | ||
14931 | “An Ada function corresponds to a non-void C function.” | |
14932 | @end quotation | |
14933 | ||
14934 | Followed. | |
14935 | ||
14936 | @quotation | |
14937 | ||
14938 | “An Ada @code{in} scalar parameter is passed as a scalar argument to a C | |
14939 | function.” | |
14940 | @end quotation | |
14941 | ||
14942 | Followed. | |
14943 | ||
14944 | @quotation | |
14945 | ||
14946 | “An Ada @code{in} parameter of an access-to-object type with designated | |
14947 | type @code{T} is passed as a @code{t*} argument to a C function, | |
14948 | where @code{t} is the C type corresponding to the Ada type @code{T}.” | |
14949 | @end quotation | |
14950 | ||
14951 | Followed. | |
14952 | ||
14953 | @quotation | |
14954 | ||
14955 | “An Ada access @code{T} parameter, or an Ada @code{out} or @code{in out} | |
14956 | parameter of an elementary type @code{T}, is passed as a @code{t*} | |
14957 | argument to a C function, where @code{t} is the C type corresponding to | |
14958 | the Ada type @code{T}. In the case of an elementary @code{out} or | |
14959 | @code{in out} parameter, a pointer to a temporary copy is used to | |
14960 | preserve by-copy semantics.” | |
14961 | @end quotation | |
14962 | ||
14963 | Followed. | |
14964 | ||
14965 | @quotation | |
14966 | ||
14967 | “An Ada parameter of a record type @code{T}, of any mode, is passed as a | |
14968 | @code{t*} argument to a C function, where @code{t} is the C | |
14969 | structure corresponding to the Ada type @code{T}.” | |
14970 | @end quotation | |
14971 | ||
14972 | Followed. This convention may be overridden by the use of the C_Pass_By_Copy | |
14973 | pragma, or Convention, or by explicitly specifying the mechanism for a given | |
14974 | call using an extended import or export pragma. | |
14975 | ||
14976 | @quotation | |
14977 | ||
14978 | “An Ada parameter of an array type with component type @code{T}, of any | |
14979 | mode, is passed as a @code{t*} argument to a C function, where | |
14980 | @code{t} is the C type corresponding to the Ada type @code{T}.” | |
14981 | @end quotation | |
14982 | ||
14983 | Followed. | |
14984 | ||
14985 | @quotation | |
14986 | ||
14987 | “An Ada parameter of an access-to-subprogram type is passed as a pointer | |
14988 | to a C function whose prototype corresponds to the designated | |
14989 | subprogram’s specification.” | |
14990 | @end quotation | |
14991 | ||
14992 | Followed. | |
14993 | ||
14994 | @geindex COBOL | |
14995 | @geindex interfacing with | |
14996 | ||
14997 | @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 | |
04d6c745 | 14998 | @anchor{gnat_rm/implementation_advice rm-b-4-95-98-interfacing-with-cobol}@anchor{24b} |
64d5610f ML |
14999 | @section RM B.4(95-98): Interfacing with COBOL |
15000 | ||
15001 | ||
15002 | @quotation | |
15003 | ||
15004 | “An Ada implementation should support the following interface | |
15005 | correspondences between Ada and COBOL.” | |
15006 | @end quotation | |
15007 | ||
15008 | Followed. | |
15009 | ||
15010 | @quotation | |
15011 | ||
15012 | “An Ada access @code{T} parameter is passed as a @code{BY REFERENCE} data item of | |
15013 | the COBOL type corresponding to @code{T}.” | |
15014 | @end quotation | |
15015 | ||
15016 | Followed. | |
15017 | ||
15018 | @quotation | |
15019 | ||
15020 | “An Ada in scalar parameter is passed as a @code{BY CONTENT} data item of | |
15021 | the corresponding COBOL type.” | |
15022 | @end quotation | |
15023 | ||
15024 | Followed. | |
15025 | ||
15026 | @quotation | |
15027 | ||
15028 | “Any other Ada parameter is passed as a @code{BY REFERENCE} data item of the | |
15029 | COBOL type corresponding to the Ada parameter type; for scalars, a local | |
15030 | copy is used if necessary to ensure by-copy semantics.” | |
15031 | @end quotation | |
15032 | ||
15033 | Followed. | |
15034 | ||
15035 | @geindex Fortran | |
15036 | @geindex interfacing with | |
15037 | ||
15038 | @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 | |
04d6c745 | 15039 | @anchor{gnat_rm/implementation_advice rm-b-5-22-26-interfacing-with-fortran}@anchor{24c} |
64d5610f ML |
15040 | @section RM B.5(22-26): Interfacing with Fortran |
15041 | ||
15042 | ||
15043 | @quotation | |
15044 | ||
15045 | “An Ada implementation should support the following interface | |
15046 | correspondences between Ada and Fortran:” | |
15047 | @end quotation | |
15048 | ||
15049 | Followed. | |
15050 | ||
15051 | @quotation | |
15052 | ||
15053 | “An Ada procedure corresponds to a Fortran subroutine.” | |
15054 | @end quotation | |
15055 | ||
15056 | Followed. | |
15057 | ||
15058 | @quotation | |
15059 | ||
15060 | “An Ada function corresponds to a Fortran function.” | |
15061 | @end quotation | |
15062 | ||
15063 | Followed. | |
15064 | ||
15065 | @quotation | |
15066 | ||
15067 | “An Ada parameter of an elementary, array, or record type @code{T} is | |
15068 | passed as a @code{T} argument to a Fortran procedure, where @code{T} is | |
15069 | the Fortran type corresponding to the Ada type @code{T}, and where the | |
15070 | INTENT attribute of the corresponding dummy argument matches the Ada | |
15071 | formal parameter mode; the Fortran implementation’s parameter passing | |
15072 | conventions are used. For elementary types, a local copy is used if | |
15073 | necessary to ensure by-copy semantics.” | |
15074 | @end quotation | |
15075 | ||
15076 | Followed. | |
15077 | ||
15078 | @quotation | |
15079 | ||
15080 | “An Ada parameter of an access-to-subprogram type is passed as a | |
15081 | reference to a Fortran procedure whose interface corresponds to the | |
15082 | designated subprogram’s specification.” | |
15083 | @end quotation | |
15084 | ||
15085 | Followed. | |
15086 | ||
15087 | @geindex Machine operations | |
15088 | ||
15089 | @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 | |
04d6c745 | 15090 | @anchor{gnat_rm/implementation_advice rm-c-1-3-5-access-to-machine-operations}@anchor{24d} |
64d5610f ML |
15091 | @section RM C.1(3-5): Access to Machine Operations |
15092 | ||
15093 | ||
15094 | @quotation | |
15095 | ||
15096 | “The machine code or intrinsic support should allow access to all | |
15097 | operations normally available to assembly language programmers for the | |
15098 | target environment, including privileged instructions, if any.” | |
15099 | @end quotation | |
15100 | ||
15101 | Followed. | |
15102 | ||
15103 | @quotation | |
15104 | ||
15105 | “The interfacing pragmas (see Annex B) should support interface to | |
15106 | assembler; the default assembler should be associated with the | |
15107 | convention identifier @code{Assembler}.” | |
15108 | @end quotation | |
15109 | ||
15110 | Followed. | |
15111 | ||
15112 | @quotation | |
15113 | ||
15114 | “If an entity is exported to assembly language, then the implementation | |
15115 | should allocate it at an addressable location, and should ensure that it | |
15116 | is retained by the linking process, even if not otherwise referenced | |
15117 | from the Ada code. The implementation should assume that any call to a | |
15118 | machine code or assembler subprogram is allowed to read or update every | |
15119 | object that is specified as exported.” | |
15120 | @end quotation | |
15121 | ||
15122 | Followed. | |
15123 | ||
15124 | @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 | |
04d6c745 | 15125 | @anchor{gnat_rm/implementation_advice rm-c-1-10-16-access-to-machine-operations}@anchor{24e} |
64d5610f ML |
15126 | @section RM C.1(10-16): Access to Machine Operations |
15127 | ||
15128 | ||
15129 | @quotation | |
15130 | ||
15131 | “The implementation should ensure that little or no overhead is | |
15132 | associated with calling intrinsic and machine-code subprograms.” | |
15133 | @end quotation | |
15134 | ||
15135 | Followed for both intrinsics and machine-code subprograms. | |
15136 | ||
15137 | @quotation | |
15138 | ||
15139 | “It is recommended that intrinsic subprograms be provided for convenient | |
15140 | access to any machine operations that provide special capabilities or | |
15141 | efficiency and that are not otherwise available through the language | |
15142 | constructs.” | |
15143 | @end quotation | |
15144 | ||
15145 | Followed. A full set of machine operation intrinsic subprograms is provided. | |
15146 | ||
15147 | @quotation | |
15148 | ||
15149 | “Atomic read-modify-write operations—e.g., test and set, compare and | |
15150 | swap, decrement and test, enqueue/dequeue.” | |
15151 | @end quotation | |
15152 | ||
15153 | Followed on any target supporting such operations. | |
15154 | ||
15155 | @quotation | |
15156 | ||
15157 | “Standard numeric functions—e.g.:, sin, log.” | |
15158 | @end quotation | |
15159 | ||
15160 | Followed on any target supporting such operations. | |
15161 | ||
15162 | @quotation | |
15163 | ||
15164 | “String manipulation operations—e.g.:, translate and test.” | |
15165 | @end quotation | |
15166 | ||
15167 | Followed on any target supporting such operations. | |
15168 | ||
15169 | @quotation | |
15170 | ||
15171 | “Vector operations—e.g.:, compare vector against thresholds.” | |
15172 | @end quotation | |
15173 | ||
15174 | Followed on any target supporting such operations. | |
15175 | ||
15176 | @quotation | |
15177 | ||
15178 | “Direct operations on I/O ports.” | |
15179 | @end quotation | |
15180 | ||
15181 | Followed on any target supporting such operations. | |
15182 | ||
15183 | @geindex Interrupt support | |
15184 | ||
15185 | @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 | |
04d6c745 | 15186 | @anchor{gnat_rm/implementation_advice rm-c-3-28-interrupt-support}@anchor{24f} |
64d5610f ML |
15187 | @section RM C.3(28): Interrupt Support |
15188 | ||
15189 | ||
15190 | @quotation | |
15191 | ||
15192 | “If the @code{Ceiling_Locking} policy is not in effect, the | |
15193 | implementation should provide means for the application to specify which | |
15194 | interrupts are to be blocked during protected actions, if the underlying | |
15195 | system allows for a finer-grain control of interrupt blocking.” | |
15196 | @end quotation | |
15197 | ||
15198 | Followed. The underlying system does not allow for finer-grain control | |
15199 | of interrupt blocking. | |
15200 | ||
15201 | @geindex Protected procedure handlers | |
15202 | ||
15203 | @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 | |
04d6c745 | 15204 | @anchor{gnat_rm/implementation_advice rm-c-3-1-20-21-protected-procedure-handlers}@anchor{250} |
64d5610f ML |
15205 | @section RM C.3.1(20-21): Protected Procedure Handlers |
15206 | ||
15207 | ||
15208 | @quotation | |
15209 | ||
15210 | “Whenever possible, the implementation should allow interrupt handlers to | |
15211 | be called directly by the hardware.” | |
15212 | @end quotation | |
15213 | ||
15214 | Followed on any target where the underlying operating system permits | |
15215 | such direct calls. | |
15216 | ||
15217 | @quotation | |
15218 | ||
15219 | “Whenever practical, violations of any | |
15220 | implementation-defined restrictions should be detected before run time.” | |
15221 | @end quotation | |
15222 | ||
15223 | Followed. Compile time warnings are given when possible. | |
15224 | ||
15225 | @geindex Package `@w{`}Interrupts`@w{`} | |
15226 | ||
15227 | @geindex Interrupts | |
15228 | ||
15229 | @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 | |
04d6c745 | 15230 | @anchor{gnat_rm/implementation_advice rm-c-3-2-25-package-interrupts}@anchor{251} |
64d5610f ML |
15231 | @section RM C.3.2(25): Package @code{Interrupts} |
15232 | ||
15233 | ||
15234 | @quotation | |
15235 | ||
15236 | “If implementation-defined forms of interrupt handler procedures are | |
15237 | supported, such as protected procedures with parameters, then for each | |
15238 | such form of a handler, a type analogous to @code{Parameterless_Handler} | |
15239 | should be specified in a child package of @code{Interrupts}, with the | |
15240 | same operations as in the predefined package Interrupts.” | |
15241 | @end quotation | |
15242 | ||
15243 | Followed. | |
15244 | ||
15245 | @geindex Pre-elaboration requirements | |
15246 | ||
15247 | @node RM C 4 14 Pre-elaboration Requirements,RM C 5 8 Pragma Discard_Names,RM C 3 2 25 Package Interrupts,Implementation Advice | |
04d6c745 | 15248 | @anchor{gnat_rm/implementation_advice rm-c-4-14-pre-elaboration-requirements}@anchor{252} |
64d5610f ML |
15249 | @section RM C.4(14): Pre-elaboration Requirements |
15250 | ||
15251 | ||
15252 | @quotation | |
15253 | ||
15254 | “It is recommended that pre-elaborated packages be implemented in such a | |
15255 | way that there should be little or no code executed at run time for the | |
15256 | elaboration of entities not already covered by the Implementation | |
15257 | Requirements.” | |
15258 | @end quotation | |
15259 | ||
15260 | Followed. Executable code is generated in some cases, e.g., loops | |
15261 | to initialize large arrays. | |
15262 | ||
15263 | @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 | |
04d6c745 | 15264 | @anchor{gnat_rm/implementation_advice rm-c-5-8-pragma-discard-names}@anchor{253} |
64d5610f ML |
15265 | @section RM C.5(8): Pragma @code{Discard_Names} |
15266 | ||
15267 | ||
15268 | @quotation | |
15269 | ||
15270 | “If the pragma applies to an entity, then the implementation should | |
15271 | reduce the amount of storage used for storing names associated with that | |
15272 | entity.” | |
15273 | @end quotation | |
15274 | ||
15275 | Followed. | |
15276 | ||
15277 | @geindex Package Task_Attributes | |
15278 | ||
15279 | @geindex Task_Attributes | |
15280 | ||
15281 | @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 | |
04d6c745 | 15282 | @anchor{gnat_rm/implementation_advice rm-c-7-2-30-the-package-task-attributes}@anchor{254} |
64d5610f ML |
15283 | @section RM C.7.2(30): The Package Task_Attributes |
15284 | ||
15285 | ||
15286 | @quotation | |
15287 | ||
15288 | “Some implementations are targeted to domains in which memory use at run | |
15289 | time must be completely deterministic. For such implementations, it is | |
15290 | recommended that the storage for task attributes will be pre-allocated | |
15291 | statically and not from the heap. This can be accomplished by either | |
15292 | placing restrictions on the number and the size of the task’s | |
15293 | attributes, or by using the pre-allocated storage for the first @code{N} | |
15294 | attribute objects, and the heap for the others. In the latter case, | |
15295 | @code{N} should be documented.” | |
15296 | @end quotation | |
15297 | ||
15298 | Not followed. This implementation is not targeted to such a domain. | |
15299 | ||
15300 | @geindex Locking Policies | |
15301 | ||
15302 | @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 | |
04d6c745 | 15303 | @anchor{gnat_rm/implementation_advice rm-d-3-17-locking-policies}@anchor{255} |
64d5610f ML |
15304 | @section RM D.3(17): Locking Policies |
15305 | ||
15306 | ||
15307 | @quotation | |
15308 | ||
15309 | “The implementation should use names that end with @code{_Locking} for | |
15310 | locking policies defined by the implementation.” | |
15311 | @end quotation | |
15312 | ||
15313 | Followed. Two implementation-defined locking policies are defined, | |
15314 | whose names (@code{Inheritance_Locking} and | |
15315 | @code{Concurrent_Readers_Locking}) follow this suggestion. | |
15316 | ||
15317 | @geindex Entry queuing policies | |
15318 | ||
15319 | @node RM D 4 16 Entry Queuing Policies,RM D 6 9-10 Preemptive Abort,RM D 3 17 Locking Policies,Implementation Advice | |
04d6c745 | 15320 | @anchor{gnat_rm/implementation_advice rm-d-4-16-entry-queuing-policies}@anchor{256} |
64d5610f ML |
15321 | @section RM D.4(16): Entry Queuing Policies |
15322 | ||
15323 | ||
15324 | @quotation | |
15325 | ||
15326 | “Names that end with @code{_Queuing} should be used | |
15327 | for all implementation-defined queuing policies.” | |
15328 | @end quotation | |
15329 | ||
15330 | Followed. No such implementation-defined queuing policies exist. | |
15331 | ||
15332 | @geindex Preemptive abort | |
15333 | ||
15334 | @node RM D 6 9-10 Preemptive Abort,RM D 7 21 Tasking Restrictions,RM D 4 16 Entry Queuing Policies,Implementation Advice | |
04d6c745 | 15335 | @anchor{gnat_rm/implementation_advice rm-d-6-9-10-preemptive-abort}@anchor{257} |
64d5610f ML |
15336 | @section RM D.6(9-10): Preemptive Abort |
15337 | ||
15338 | ||
15339 | @quotation | |
15340 | ||
15341 | “Even though the `abort_statement' is included in the list of | |
15342 | potentially blocking operations (see 9.5.1), it is recommended that this | |
15343 | statement be implemented in a way that never requires the task executing | |
15344 | the `abort_statement' to block.” | |
15345 | @end quotation | |
15346 | ||
15347 | Followed. | |
15348 | ||
15349 | @quotation | |
15350 | ||
15351 | “On a multi-processor, the delay associated with aborting a task on | |
15352 | another processor should be bounded; the implementation should use | |
15353 | periodic polling, if necessary, to achieve this.” | |
15354 | @end quotation | |
15355 | ||
15356 | Followed. | |
15357 | ||
15358 | @geindex Tasking restrictions | |
15359 | ||
15360 | @node RM D 7 21 Tasking Restrictions,RM D 8 47-49 Monotonic Time,RM D 6 9-10 Preemptive Abort,Implementation Advice | |
04d6c745 | 15361 | @anchor{gnat_rm/implementation_advice rm-d-7-21-tasking-restrictions}@anchor{258} |
64d5610f ML |
15362 | @section RM D.7(21): Tasking Restrictions |
15363 | ||
15364 | ||
15365 | @quotation | |
15366 | ||
15367 | “When feasible, the implementation should take advantage of the specified | |
15368 | restrictions to produce a more efficient implementation.” | |
15369 | @end quotation | |
15370 | ||
15371 | GNAT currently takes advantage of these restrictions by providing an optimized | |
15372 | run time when the Ravenscar profile and the GNAT restricted run time set | |
15373 | of restrictions are specified. See pragma @code{Profile (Ravenscar)} and | |
15374 | pragma @code{Profile (Restricted)} for more details. | |
15375 | ||
15376 | @geindex Time | |
15377 | @geindex monotonic | |
15378 | ||
15379 | @node RM D 8 47-49 Monotonic Time,RM E 5 28-29 Partition Communication Subsystem,RM D 7 21 Tasking Restrictions,Implementation Advice | |
04d6c745 | 15380 | @anchor{gnat_rm/implementation_advice rm-d-8-47-49-monotonic-time}@anchor{259} |
64d5610f ML |
15381 | @section RM D.8(47-49): Monotonic Time |
15382 | ||
15383 | ||
15384 | @quotation | |
15385 | ||
15386 | “When appropriate, implementations should provide configuration | |
15387 | mechanisms to change the value of @code{Tick}.” | |
15388 | @end quotation | |
15389 | ||
15390 | Such configuration mechanisms are not appropriate to this implementation | |
15391 | and are thus not supported. | |
15392 | ||
15393 | @quotation | |
15394 | ||
15395 | “It is recommended that @code{Calendar.Clock} and @code{Real_Time.Clock} | |
15396 | be implemented as transformations of the same time base.” | |
15397 | @end quotation | |
15398 | ||
15399 | Followed. | |
15400 | ||
15401 | @quotation | |
15402 | ||
15403 | “It is recommended that the best time base which exists in | |
15404 | the underlying system be available to the application through | |
15405 | @code{Clock}. @cite{Best} may mean highest accuracy or largest range.” | |
15406 | @end quotation | |
15407 | ||
15408 | Followed. | |
15409 | ||
15410 | @geindex Partition communication subsystem | |
15411 | ||
15412 | @geindex PCS | |
15413 | ||
15414 | @node RM E 5 28-29 Partition Communication Subsystem,RM F 7 COBOL Support,RM D 8 47-49 Monotonic Time,Implementation Advice | |
04d6c745 | 15415 | @anchor{gnat_rm/implementation_advice rm-e-5-28-29-partition-communication-subsystem}@anchor{25a} |
64d5610f ML |
15416 | @section RM E.5(28-29): Partition Communication Subsystem |
15417 | ||
15418 | ||
15419 | @quotation | |
15420 | ||
15421 | “Whenever possible, the PCS on the called partition should allow for | |
15422 | multiple tasks to call the RPC-receiver with different messages and | |
15423 | should allow them to block until the corresponding subprogram body | |
15424 | returns.” | |
15425 | @end quotation | |
15426 | ||
15427 | Followed by GLADE, a separately supplied PCS that can be used with | |
15428 | GNAT. | |
15429 | ||
15430 | @quotation | |
15431 | ||
15432 | “The @code{Write} operation on a stream of type @code{Params_Stream_Type} | |
15433 | should raise @code{Storage_Error} if it runs out of space trying to | |
15434 | write the @code{Item} into the stream.” | |
15435 | @end quotation | |
15436 | ||
15437 | Followed by GLADE, a separately supplied PCS that can be used with | |
15438 | GNAT. | |
15439 | ||
15440 | @geindex COBOL support | |
15441 | ||
15442 | @node RM F 7 COBOL Support,RM F 1 2 Decimal Radix Support,RM E 5 28-29 Partition Communication Subsystem,Implementation Advice | |
04d6c745 | 15443 | @anchor{gnat_rm/implementation_advice rm-f-7-cobol-support}@anchor{25b} |
64d5610f ML |
15444 | @section RM F(7): COBOL Support |
15445 | ||
15446 | ||
15447 | @quotation | |
15448 | ||
15449 | “If COBOL (respectively, C) is widely supported in the target | |
15450 | environment, implementations supporting the Information Systems Annex | |
15451 | should provide the child package @code{Interfaces.COBOL} (respectively, | |
15452 | @code{Interfaces.C}) specified in Annex B and should support a | |
15453 | @code{convention_identifier} of COBOL (respectively, C) in the interfacing | |
15454 | pragmas (see Annex B), thus allowing Ada programs to interface with | |
15455 | programs written in that language.” | |
15456 | @end quotation | |
15457 | ||
15458 | Followed. | |
15459 | ||
15460 | @geindex Decimal radix support | |
15461 | ||
15462 | @node RM F 1 2 Decimal Radix Support,RM G Numerics,RM F 7 COBOL Support,Implementation Advice | |
04d6c745 | 15463 | @anchor{gnat_rm/implementation_advice rm-f-1-2-decimal-radix-support}@anchor{25c} |
64d5610f ML |
15464 | @section RM F.1(2): Decimal Radix Support |
15465 | ||
15466 | ||
15467 | @quotation | |
15468 | ||
15469 | “Packed decimal should be used as the internal representation for objects | |
15470 | of subtype @code{S} when @code{S}’Machine_Radix = 10.” | |
15471 | @end quotation | |
15472 | ||
15473 | Not followed. GNAT ignores @code{S}’Machine_Radix and always uses binary | |
15474 | representations. | |
15475 | ||
15476 | @geindex Numerics | |
15477 | ||
15478 | @node RM G Numerics,RM G 1 1 56-58 Complex Types,RM F 1 2 Decimal Radix Support,Implementation Advice | |
04d6c745 | 15479 | @anchor{gnat_rm/implementation_advice rm-g-numerics}@anchor{25d} |
64d5610f ML |
15480 | @section RM G: Numerics |
15481 | ||
15482 | ||
15483 | @quotation | |
15484 | ||
15485 | “If Fortran (respectively, C) is widely supported in the target | |
15486 | environment, implementations supporting the Numerics Annex | |
15487 | should provide the child package @code{Interfaces.Fortran} (respectively, | |
15488 | @code{Interfaces.C}) specified in Annex B and should support a | |
15489 | @code{convention_identifier} of Fortran (respectively, C) in the interfacing | |
15490 | pragmas (see Annex B), thus allowing Ada programs to interface with | |
15491 | programs written in that language.” | |
15492 | @end quotation | |
15493 | ||
15494 | Followed. | |
15495 | ||
15496 | @geindex Complex types | |
15497 | ||
15498 | @node RM G 1 1 56-58 Complex Types,RM G 1 2 49 Complex Elementary Functions,RM G Numerics,Implementation Advice | |
04d6c745 | 15499 | @anchor{gnat_rm/implementation_advice rm-g-1-1-56-58-complex-types}@anchor{25e} |
64d5610f ML |
15500 | @section RM G.1.1(56-58): Complex Types |
15501 | ||
15502 | ||
15503 | @quotation | |
15504 | ||
15505 | “Because the usual mathematical meaning of multiplication of a complex | |
15506 | operand and a real operand is that of the scaling of both components of | |
15507 | the former by the latter, an implementation should not perform this | |
15508 | operation by first promoting the real operand to complex type and then | |
15509 | performing a full complex multiplication. In systems that, in the | |
15510 | future, support an Ada binding to IEC 559:1989, the latter technique | |
15511 | will not generate the required result when one of the components of the | |
15512 | complex operand is infinite. (Explicit multiplication of the infinite | |
15513 | component by the zero component obtained during promotion yields a NaN | |
15514 | that propagates into the final result.) Analogous advice applies in the | |
15515 | case of multiplication of a complex operand and a pure-imaginary | |
15516 | operand, and in the case of division of a complex operand by a real or | |
15517 | pure-imaginary operand.” | |
15518 | @end quotation | |
15519 | ||
15520 | Not followed. | |
15521 | ||
15522 | @quotation | |
15523 | ||
15524 | “Similarly, because the usual mathematical meaning of addition of a | |
15525 | complex operand and a real operand is that the imaginary operand remains | |
15526 | unchanged, an implementation should not perform this operation by first | |
15527 | promoting the real operand to complex type and then performing a full | |
15528 | complex addition. In implementations in which the @code{Signed_Zeros} | |
15529 | attribute of the component type is @code{True} (and which therefore | |
15530 | conform to IEC 559:1989 in regard to the handling of the sign of zero in | |
15531 | predefined arithmetic operations), the latter technique will not | |
15532 | generate the required result when the imaginary component of the complex | |
15533 | operand is a negatively signed zero. (Explicit addition of the negative | |
15534 | zero to the zero obtained during promotion yields a positive zero.) | |
15535 | Analogous advice applies in the case of addition of a complex operand | |
15536 | and a pure-imaginary operand, and in the case of subtraction of a | |
15537 | complex operand and a real or pure-imaginary operand.” | |
15538 | @end quotation | |
15539 | ||
15540 | Not followed. | |
15541 | ||
15542 | @quotation | |
15543 | ||
15544 | “Implementations in which @code{Real'Signed_Zeros} is @code{True} should | |
15545 | attempt to provide a rational treatment of the signs of zero results and | |
15546 | result components. As one example, the result of the @code{Argument} | |
15547 | function should have the sign of the imaginary component of the | |
15548 | parameter @code{X} when the point represented by that parameter lies on | |
15549 | the positive real axis; as another, the sign of the imaginary component | |
15550 | of the @code{Compose_From_Polar} function should be the same as | |
15551 | (respectively, the opposite of) that of the @code{Argument} parameter when that | |
15552 | parameter has a value of zero and the @code{Modulus} parameter has a | |
15553 | nonnegative (respectively, negative) value.” | |
15554 | @end quotation | |
15555 | ||
15556 | Followed. | |
15557 | ||
15558 | @geindex Complex elementary functions | |
15559 | ||
15560 | @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 | |
04d6c745 | 15561 | @anchor{gnat_rm/implementation_advice rm-g-1-2-49-complex-elementary-functions}@anchor{25f} |
64d5610f ML |
15562 | @section RM G.1.2(49): Complex Elementary Functions |
15563 | ||
15564 | ||
15565 | @quotation | |
15566 | ||
15567 | “Implementations in which @code{Complex_Types.Real'Signed_Zeros} is | |
15568 | @code{True} should attempt to provide a rational treatment of the signs | |
15569 | of zero results and result components. For example, many of the complex | |
15570 | elementary functions have components that are odd functions of one of | |
15571 | the parameter components; in these cases, the result component should | |
15572 | have the sign of the parameter component at the origin. Other complex | |
15573 | elementary functions have zero components whose sign is opposite that of | |
15574 | a parameter component at the origin, or is always positive or always | |
15575 | negative.” | |
15576 | @end quotation | |
15577 | ||
15578 | Followed. | |
15579 | ||
15580 | @geindex Accuracy requirements | |
15581 | ||
15582 | @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 | |
04d6c745 | 15583 | @anchor{gnat_rm/implementation_advice rm-g-2-4-19-accuracy-requirements}@anchor{260} |
64d5610f ML |
15584 | @section RM G.2.4(19): Accuracy Requirements |
15585 | ||
15586 | ||
15587 | @quotation | |
15588 | ||
15589 | “The versions of the forward trigonometric functions without a | |
15590 | @code{Cycle} parameter should not be implemented by calling the | |
15591 | corresponding version with a @code{Cycle} parameter of | |
15592 | @code{2.0*Numerics.Pi}, since this will not provide the required | |
15593 | accuracy in some portions of the domain. For the same reason, the | |
15594 | version of @code{Log} without a @code{Base} parameter should not be | |
15595 | implemented by calling the corresponding version with a @code{Base} | |
15596 | parameter of @code{Numerics.e}.” | |
15597 | @end quotation | |
15598 | ||
15599 | Followed. | |
15600 | ||
15601 | @geindex Complex arithmetic accuracy | |
15602 | ||
15603 | @geindex Accuracy | |
15604 | @geindex complex arithmetic | |
15605 | ||
15606 | @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 | |
04d6c745 | 15607 | @anchor{gnat_rm/implementation_advice rm-g-2-6-15-complex-arithmetic-accuracy}@anchor{261} |
64d5610f ML |
15608 | @section RM G.2.6(15): Complex Arithmetic Accuracy |
15609 | ||
15610 | ||
15611 | @quotation | |
15612 | ||
15613 | “The version of the @code{Compose_From_Polar} function without a | |
15614 | @code{Cycle} parameter should not be implemented by calling the | |
15615 | corresponding version with a @code{Cycle} parameter of | |
15616 | @code{2.0*Numerics.Pi}, since this will not provide the required | |
15617 | accuracy in some portions of the domain.” | |
15618 | @end quotation | |
15619 | ||
15620 | Followed. | |
15621 | ||
15622 | @geindex Sequential elaboration policy | |
15623 | ||
15624 | @node RM H 6 15/2 Pragma Partition_Elaboration_Policy,,RM G 2 6 15 Complex Arithmetic Accuracy,Implementation Advice | |
04d6c745 | 15625 | @anchor{gnat_rm/implementation_advice rm-h-6-15-2-pragma-partition-elaboration-policy}@anchor{262} |
64d5610f ML |
15626 | @section RM H.6(15/2): Pragma Partition_Elaboration_Policy |
15627 | ||
15628 | ||
15629 | @quotation | |
15630 | ||
15631 | “If the partition elaboration policy is @code{Sequential} and the | |
15632 | Environment task becomes permanently blocked during elaboration then the | |
15633 | partition is deadlocked and it is recommended that the partition be | |
15634 | immediately terminated.” | |
15635 | @end quotation | |
15636 | ||
15637 | Not followed. | |
15638 | ||
15639 | @node Implementation Defined Characteristics,Intrinsic Subprograms,Implementation Advice,Top | |
04d6c745 | 15640 | @anchor{gnat_rm/implementation_defined_characteristics doc}@anchor{263}@anchor{gnat_rm/implementation_defined_characteristics id1}@anchor{264}@anchor{gnat_rm/implementation_defined_characteristics implementation-defined-characteristics}@anchor{b} |
64d5610f ML |
15641 | @chapter Implementation Defined Characteristics |
15642 | ||
15643 | ||
15644 | In addition to the implementation dependent pragmas and attributes, and the | |
15645 | implementation advice, there are a number of other Ada features that are | |
15646 | potentially implementation dependent and are designated as | |
15647 | implementation-defined. These are mentioned throughout the Ada Reference | |
15648 | Manual, and are summarized in Annex M. | |
15649 | ||
15650 | A requirement for conforming Ada compilers is that they provide | |
15651 | documentation describing how the implementation deals with each of these | |
15652 | issues. In this chapter you will find each point in Annex M listed, | |
15653 | followed by a description of how GNAT handles the implementation dependence. | |
15654 | ||
15655 | You can use this chapter as a guide to minimizing implementation | |
15656 | dependent features in your programs if portability to other compilers | |
15657 | and other operating systems is an important consideration. The numbers | |
15658 | in each entry below correspond to the paragraph numbers in the Ada | |
15659 | Reference Manual. | |
15660 | ||
15661 | ||
15662 | @itemize * | |
15663 | ||
15664 | @item | |
15665 | “Whether or not each recommendation given in Implementation | |
15666 | Advice is followed. See 1.1.2(37).” | |
15667 | @end itemize | |
15668 | ||
15669 | See @ref{a,,Implementation Advice}. | |
15670 | ||
15671 | ||
15672 | @itemize * | |
15673 | ||
15674 | @item | |
15675 | “Capacity limitations of the implementation. See 1.1.3(3).” | |
15676 | @end itemize | |
15677 | ||
15678 | The complexity of programs that can be processed is limited only by the | |
15679 | total amount of available virtual memory, and disk space for the | |
15680 | generated object files. | |
15681 | ||
15682 | ||
15683 | @itemize * | |
15684 | ||
15685 | @item | |
15686 | “Variations from the standard that are impractical to avoid | |
15687 | given the implementation’s execution environment. See 1.1.3(6).” | |
15688 | @end itemize | |
15689 | ||
15690 | There are no variations from the standard. | |
15691 | ||
15692 | ||
15693 | @itemize * | |
15694 | ||
15695 | @item | |
15696 | “Which code_statements cause external | |
15697 | interactions. See 1.1.3(10).” | |
15698 | @end itemize | |
15699 | ||
15700 | Any `code_statement' can potentially cause external interactions. | |
15701 | ||
15702 | ||
15703 | @itemize * | |
15704 | ||
15705 | @item | |
15706 | “The coded representation for the text of an Ada | |
15707 | program. See 2.1(4).” | |
15708 | @end itemize | |
15709 | ||
15710 | See separate section on source representation. | |
15711 | ||
15712 | ||
15713 | @itemize * | |
15714 | ||
15715 | @item | |
15716 | “The semantics of an Ada program whose text is not in | |
15717 | Normalization Form C. See 2.1(4).” | |
15718 | @end itemize | |
15719 | ||
15720 | See separate section on source representation. | |
15721 | ||
15722 | ||
15723 | @itemize * | |
15724 | ||
15725 | @item | |
15726 | “The representation for an end of line. See 2.2(2).” | |
15727 | @end itemize | |
15728 | ||
15729 | See separate section on source representation. | |
15730 | ||
15731 | ||
15732 | @itemize * | |
15733 | ||
15734 | @item | |
15735 | “Maximum supported line length and lexical element | |
15736 | length. See 2.2(15).” | |
15737 | @end itemize | |
15738 | ||
15739 | The maximum line length is 255 characters and the maximum length of | |
15740 | a lexical element is also 255 characters. This is the default setting | |
15741 | if not overridden by the use of compiler switch `-gnaty' (which | |
15742 | sets the maximum to 79) or `-gnatyMnn' which allows the maximum | |
15743 | line length to be specified to be any value up to 32767. The maximum | |
15744 | length of a lexical element is the same as the maximum line length. | |
15745 | ||
15746 | ||
15747 | @itemize * | |
15748 | ||
15749 | @item | |
15750 | “Implementation defined pragmas. See 2.8(14).” | |
15751 | @end itemize | |
15752 | ||
15753 | See @ref{7,,Implementation Defined Pragmas}. | |
15754 | ||
15755 | ||
15756 | @itemize * | |
15757 | ||
15758 | @item | |
15759 | “Effect of pragma @code{Optimize}. See 2.8(27).” | |
15760 | @end itemize | |
15761 | ||
15762 | Pragma @code{Optimize}, if given with a @code{Time} or @code{Space} | |
15763 | parameter, checks that the optimization flag is set, and aborts if it is | |
15764 | not. | |
15765 | ||
15766 | ||
15767 | @itemize * | |
15768 | ||
15769 | @item | |
15770 | “The message string associated with the Assertion_Error exception raised | |
15771 | by the failure of a predicate check if there is no applicable | |
15772 | Predicate_Failure aspect. See 3.2.4(31).” | |
15773 | @end itemize | |
15774 | ||
15775 | In the case of a Dynamic_Predicate aspect, the string is | |
15776 | “Dynamic_Predicate failed at <source position>”, where | |
15777 | “<source position>” might be something like “foo.adb:123”. | |
15778 | The Static_Predicate case is handled analogously. | |
15779 | ||
15780 | ||
15781 | @itemize * | |
15782 | ||
15783 | @item | |
15784 | “The predefined integer types declared in | |
15785 | @code{Standard}. See 3.5.4(25).” | |
15786 | @end itemize | |
15787 | ||
15788 | ||
15789 | @multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} | |
15790 | @headitem | |
15791 | ||
15792 | Type | |
15793 | ||
15794 | @tab | |
15795 | ||
15796 | Representation | |
15797 | ||
15798 | @item | |
15799 | ||
15800 | `Short_Short_Integer' | |
15801 | ||
15802 | @tab | |
15803 | ||
15804 | 8-bit signed | |
15805 | ||
15806 | @item | |
15807 | ||
15808 | `Short_Integer' | |
15809 | ||
15810 | @tab | |
15811 | ||
15812 | 16-bit signed | |
15813 | ||
15814 | @item | |
15815 | ||
15816 | `Integer' | |
15817 | ||
15818 | @tab | |
15819 | ||
15820 | 32-bit signed | |
15821 | ||
15822 | @item | |
15823 | ||
15824 | `Long_Integer' | |
15825 | ||
15826 | @tab | |
15827 | ||
15828 | 64-bit signed (on most 64-bit targets, | |
15829 | depending on the C definition of long) | |
15830 | 32-bit signed (on all other targets) | |
15831 | ||
15832 | @item | |
15833 | ||
15834 | `Long_Long_Integer' | |
15835 | ||
15836 | @tab | |
15837 | ||
15838 | 64-bit signed | |
15839 | ||
15840 | @item | |
15841 | ||
15842 | `Long_Long_Long_Integer' | |
15843 | ||
15844 | @tab | |
15845 | ||
15846 | 128-bit signed (on 64-bit targets) | |
15847 | 64-bit signed (on 32-bit targets) | |
15848 | ||
15849 | @end multitable | |
15850 | ||
15851 | ||
15852 | ||
15853 | @itemize * | |
15854 | ||
15855 | @item | |
15856 | “Any nonstandard integer types and the operators defined | |
15857 | for them. See 3.5.4(26).” | |
15858 | @end itemize | |
15859 | ||
15860 | There are no nonstandard integer types. | |
15861 | ||
15862 | ||
15863 | @itemize * | |
15864 | ||
15865 | @item | |
15866 | “Any nonstandard real types and the operators defined for | |
15867 | them. See 3.5.6(8).” | |
15868 | @end itemize | |
15869 | ||
15870 | There are no nonstandard real types. | |
15871 | ||
15872 | ||
15873 | @itemize * | |
15874 | ||
15875 | @item | |
15876 | “What combinations of requested decimal precision and range | |
15877 | are supported for floating point types. See 3.5.7(7).” | |
15878 | @end itemize | |
15879 | ||
15880 | The precision and range are defined by the IEEE Standard for Floating-Point | |
15881 | Arithmetic (IEEE 754-2019). | |
15882 | ||
15883 | ||
15884 | @itemize * | |
15885 | ||
15886 | @item | |
15887 | “The predefined floating point types declared in | |
15888 | @code{Standard}. See 3.5.7(16).” | |
15889 | @end itemize | |
15890 | ||
15891 | ||
15892 | @multitable {xxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} | |
15893 | @headitem | |
15894 | ||
15895 | Type | |
15896 | ||
15897 | @tab | |
15898 | ||
15899 | Representation | |
15900 | ||
15901 | @item | |
15902 | ||
15903 | `Short_Float' | |
15904 | ||
15905 | @tab | |
15906 | ||
15907 | IEEE Binary32 (Single) | |
15908 | ||
15909 | @item | |
15910 | ||
15911 | `Float' | |
15912 | ||
15913 | @tab | |
15914 | ||
15915 | IEEE Binary32 (Single) | |
15916 | ||
15917 | @item | |
15918 | ||
15919 | `Long_Float' | |
15920 | ||
15921 | @tab | |
15922 | ||
15923 | IEEE Binary64 (Double) | |
15924 | ||
15925 | @item | |
15926 | ||
15927 | `Long_Long_Float' | |
15928 | ||
15929 | @tab | |
15930 | ||
15931 | IEEE Binary64 (Double) on non-x86 architectures | |
15932 | IEEE 80-bit Extended on x86 architecture | |
15933 | ||
15934 | @end multitable | |
15935 | ||
15936 | ||
15937 | The default rounding mode specified by the IEEE 754 Standard is assumed both | |
15938 | for static and dynamic computations (that is, round to nearest, ties to even). | |
15939 | The input routines yield correctly rounded values for Short_Float, Float, and | |
15940 | Long_Float at least. The output routines can compute up to twice as many exact | |
15941 | digits as the value of @code{T'Digits} for any type, for example 30 digits for | |
15942 | Long_Float; if more digits are requested, zeros are printed. | |
15943 | ||
15944 | ||
15945 | @itemize * | |
15946 | ||
15947 | @item | |
15948 | “The small of an ordinary fixed point type. See 3.5.9(8).” | |
15949 | @end itemize | |
15950 | ||
15951 | The small is the largest power of two that does not exceed the delta. | |
15952 | ||
15953 | ||
15954 | @itemize * | |
15955 | ||
15956 | @item | |
15957 | “What combinations of small, range, and digits are | |
15958 | supported for fixed point types. See 3.5.9(10).” | |
15959 | @end itemize | |
15960 | ||
15961 | For an ordinary fixed point type, on 32-bit platforms, the small must lie in | |
15962 | 2.0**(-80) .. 2.0**80 and the range in -9.0E+36 .. 9.0E+36; any combination | |
15963 | is permitted that does not result in a mantissa larger than 63 bits. | |
15964 | ||
15965 | On 64-bit platforms, the small must lie in 2.0**(-127) .. 2.0**127 and the | |
15966 | range in -1.0E+76 .. 1.0E+76; any combination is permitted that does not | |
15967 | result in a mantissa larger than 63 bits, and any combination is permitted | |
15968 | that results in a mantissa between 64 and 127 bits if the small is the | |
15969 | ratio of two integers that lie in 1 .. 2.0**127. | |
15970 | ||
15971 | If the small is the ratio of two integers with 64-bit magnitude on 32-bit | |
15972 | platforms and 128-bit magnitude on 64-bit platforms, which is the case if | |
15973 | no @code{small} clause is provided, then the operations of the fixed point | |
15974 | type are entirely implemented by means of integer instructions. In the | |
15975 | other cases, some operations, in particular input and output, may be | |
15976 | implemented by means of floating-point instructions and may be affected | |
15977 | by accuracy issues on architectures other than x86. | |
15978 | ||
15979 | For a decimal fixed point type, on 32-bit platforms, the small must lie in | |
15980 | 1.0E-18 .. 1.0E+18 and the digits in 1 .. 18. On 64-bit platforms, the | |
15981 | small must lie in 1.0E-38 .. 1.0E+38 and the digits in 1 .. 38. | |
15982 | ||
15983 | ||
15984 | @itemize * | |
15985 | ||
15986 | @item | |
15987 | “The result of @code{Tags.Expanded_Name} for types declared | |
15988 | within an unnamed `block_statement'. See 3.9(10).” | |
15989 | @end itemize | |
15990 | ||
15991 | Block numbers of the form @code{B@var{nnn}}, where `nnn' is a | |
15992 | decimal integer are allocated. | |
15993 | ||
15994 | ||
15995 | @itemize * | |
15996 | ||
15997 | @item | |
15998 | “The sequence of characters of the value returned by Tags.Expanded_Name | |
15999 | (respectively, Tags.Wide_Expanded_Name) when some of the graphic | |
16000 | characters of Tags.Wide_Wide_Expanded_Name are not defined in Character | |
16001 | (respectively, Wide_Character). See 3.9(10.1).” | |
16002 | @end itemize | |
16003 | ||
16004 | This is handled in the same way as the implementation-defined behavior | |
16005 | referenced in A.4.12(34). | |
16006 | ||
16007 | ||
16008 | @itemize * | |
16009 | ||
16010 | @item | |
16011 | “Implementation-defined attributes. See 4.1.4(12).” | |
16012 | @end itemize | |
16013 | ||
16014 | See @ref{8,,Implementation Defined Attributes}. | |
16015 | ||
16016 | ||
16017 | @itemize * | |
16018 | ||
16019 | @item | |
16020 | “The value of the parameter to Empty for some container aggregates. | |
16021 | See 4.3.5(40).” | |
16022 | @end itemize | |
16023 | ||
16024 | As per the suggestion given in the Annotated Ada RM, the default value | |
16025 | of the formal parameter is used if one exists and zero is used otherwise. | |
16026 | ||
16027 | ||
16028 | @itemize * | |
16029 | ||
16030 | @item | |
16031 | “The maximum number of chunks for a parallel reduction expression without | |
16032 | a chunk_specification. See 4.5.10(21).” | |
16033 | @end itemize | |
16034 | ||
16035 | Feature unimplemented. | |
16036 | ||
16037 | ||
16038 | @itemize * | |
16039 | ||
16040 | @item | |
16041 | “Rounding of real static expressions which are exactly half-way between | |
16042 | two machine numbers. See 4.9(38).” | |
16043 | @end itemize | |
16044 | ||
16045 | Round to even is used in all such cases. | |
16046 | ||
16047 | ||
16048 | @itemize * | |
16049 | ||
16050 | @item | |
16051 | “The maximum number of chunks for a parallel generalized iterator without | |
16052 | a chunk_specification. See 5.5.2(10).” | |
16053 | @end itemize | |
16054 | ||
16055 | Feature unimplemented. | |
16056 | ||
16057 | ||
16058 | @itemize * | |
16059 | ||
16060 | @item | |
16061 | “The number of chunks for an array component iterator. See 5.5.2(11).” | |
16062 | @end itemize | |
16063 | ||
16064 | Feature unimplemented. | |
16065 | ||
16066 | ||
16067 | @itemize * | |
16068 | ||
16069 | @item | |
16070 | “Any extensions of the Global aspect. See 6.1.2(43).” | |
16071 | @end itemize | |
16072 | ||
16073 | Feature unimplemented. | |
16074 | ||
16075 | ||
16076 | @itemize * | |
16077 | ||
16078 | @item | |
16079 | “The circumstances the implementation passes in the null value for a view | |
16080 | conversion of an access type used as an out parameter. See 6.4.1(19).” | |
16081 | @end itemize | |
16082 | ||
16083 | Difficult to characterize. | |
16084 | ||
16085 | ||
16086 | @itemize * | |
16087 | ||
16088 | @item | |
16089 | “Any extensions of the Default_Initial_Condition aspect. See 7.3.3(11).” | |
16090 | @end itemize | |
16091 | ||
16092 | SPARK allows specifying `null' as the Default_Initial_Condition | |
16093 | aspect of a type. See the SPARK reference manual for further details. | |
16094 | ||
16095 | ||
16096 | @itemize * | |
16097 | ||
16098 | @item | |
16099 | “Any implementation-defined time types. See 9.6(6).” | |
16100 | @end itemize | |
16101 | ||
16102 | There are no implementation-defined time types. | |
16103 | ||
16104 | ||
16105 | @itemize * | |
16106 | ||
16107 | @item | |
16108 | “The time base associated with relative delays. See 9.6(20).” | |
16109 | @end itemize | |
16110 | ||
16111 | See 9.6(20). The time base used is that provided by the C library | |
16112 | function @code{gettimeofday}. | |
16113 | ||
16114 | ||
16115 | @itemize * | |
16116 | ||
16117 | @item | |
16118 | “The time base of the type @code{Calendar.Time}. See 9.6(23).” | |
16119 | @end itemize | |
16120 | ||
16121 | The time base used is that provided by the C library function | |
16122 | @code{gettimeofday}. | |
16123 | ||
16124 | ||
16125 | @itemize * | |
16126 | ||
16127 | @item | |
16128 | “The time zone used for package @code{Calendar} | |
16129 | operations. See 9.6(24).” | |
16130 | @end itemize | |
16131 | ||
16132 | The time zone used by package @code{Calendar} is the current system time zone | |
16133 | setting for local time, as accessed by the C library function | |
16134 | @code{localtime}. | |
16135 | ||
16136 | ||
16137 | @itemize * | |
16138 | ||
16139 | @item | |
16140 | “Any limit on `delay_until_statements' of | |
16141 | `select_statements'. See 9.6(29).” | |
16142 | @end itemize | |
16143 | ||
16144 | There are no such limits. | |
16145 | ||
16146 | ||
16147 | @itemize * | |
16148 | ||
16149 | @item | |
16150 | “The result of Calendar.Formatting.Image if its argument represents more | |
16151 | than 100 hours. See 9.6.1(86).” | |
16152 | @end itemize | |
16153 | ||
16154 | Calendar.Time_Error is raised. | |
16155 | ||
16156 | ||
16157 | @itemize * | |
16158 | ||
16159 | @item | |
16160 | “Implementation-defined conflict check policies. See 9.10.1(5).” | |
16161 | @end itemize | |
16162 | ||
16163 | There are no implementation-defined conflict check policies. | |
16164 | ||
16165 | ||
16166 | @itemize * | |
16167 | ||
16168 | @item | |
16169 | “The representation for a compilation. See 10.1(2).” | |
16170 | @end itemize | |
16171 | ||
16172 | A compilation is represented by a sequence of files presented to the | |
16173 | compiler in a single invocation of the `gcc' command. | |
16174 | ||
16175 | ||
16176 | @itemize * | |
16177 | ||
16178 | @item | |
16179 | “Any restrictions on compilations that contain multiple | |
16180 | compilation_units. See 10.1(4).” | |
16181 | @end itemize | |
16182 | ||
16183 | No single file can contain more than one compilation unit, but any | |
16184 | sequence of files can be presented to the compiler as a single | |
16185 | compilation. | |
16186 | ||
16187 | ||
16188 | @itemize * | |
16189 | ||
16190 | @item | |
16191 | “The mechanisms for creating an environment and for adding | |
16192 | and replacing compilation units. See 10.1.4(3).” | |
16193 | @end itemize | |
16194 | ||
16195 | See separate section on compilation model. | |
16196 | ||
16197 | ||
16198 | @itemize * | |
16199 | ||
16200 | @item | |
16201 | “The manner of explicitly assigning library units to a | |
16202 | partition. See 10.2(2).” | |
16203 | @end itemize | |
16204 | ||
16205 | If a unit contains an Ada main program, then the Ada units for the partition | |
16206 | are determined by recursive application of the rules in the Ada Reference | |
16207 | Manual section 10.2(2-6). In other words, the Ada units will be those that | |
16208 | are needed by the main program, and then this definition of need is applied | |
16209 | recursively to those units, and the partition contains the transitive | |
16210 | closure determined by this relationship. In short, all the necessary units | |
16211 | are included, with no need to explicitly specify the list. If additional | |
16212 | units are required, e.g., by foreign language units, then all units must be | |
16213 | mentioned in the context clause of one of the needed Ada units. | |
16214 | ||
16215 | If the partition contains no main program, or if the main program is in | |
16216 | a language other than Ada, then GNAT | |
16217 | provides the binder options `-z' and `-n' respectively, and in | |
16218 | this case a list of units can be explicitly supplied to the binder for | |
16219 | inclusion in the partition (all units needed by these units will also | |
16220 | be included automatically). For full details on the use of these | |
16221 | options, refer to `GNAT Make Program gnatmake' in the | |
16222 | @cite{GNAT User’s Guide}. | |
16223 | ||
16224 | ||
16225 | @itemize * | |
16226 | ||
16227 | @item | |
16228 | “The implementation-defined means, if any, of specifying which compilation | |
16229 | units are needed by a given compilation unit. See 10.2(2).” | |
16230 | @end itemize | |
16231 | ||
16232 | The units needed by a given compilation unit are as defined in | |
16233 | the Ada Reference Manual section 10.2(2-6). There are no | |
16234 | implementation-defined pragmas or other implementation-defined | |
16235 | means for specifying needed units. | |
16236 | ||
16237 | ||
16238 | @itemize * | |
16239 | ||
16240 | @item | |
16241 | “The manner of designating the main subprogram of a | |
16242 | partition. See 10.2(7).” | |
16243 | @end itemize | |
16244 | ||
16245 | The main program is designated by providing the name of the | |
16246 | corresponding @code{ALI} file as the input parameter to the binder. | |
16247 | ||
16248 | ||
16249 | @itemize * | |
16250 | ||
16251 | @item | |
16252 | “The order of elaboration of `library_items'. See 10.2(18).” | |
16253 | @end itemize | |
16254 | ||
16255 | The first constraint on ordering is that it meets the requirements of | |
16256 | Chapter 10 of the Ada Reference Manual. This still leaves some | |
16257 | implementation-dependent choices, which are resolved by analyzing | |
16258 | the elaboration code of each unit and identifying implicit | |
16259 | elaboration-order dependencies. | |
16260 | ||
16261 | ||
16262 | @itemize * | |
16263 | ||
16264 | @item | |
16265 | “Parameter passing and function return for the main | |
16266 | subprogram. See 10.2(21).” | |
16267 | @end itemize | |
16268 | ||
16269 | The main program has no parameters. It may be a procedure, or a function | |
16270 | returning an integer type. In the latter case, the returned integer | |
16271 | value is the return code of the program (overriding any value that | |
16272 | may have been set by a call to @code{Ada.Command_Line.Set_Exit_Status}). | |
16273 | ||
16274 | ||
16275 | @itemize * | |
16276 | ||
16277 | @item | |
16278 | “The mechanisms for building and running partitions. See 10.2(24).” | |
16279 | @end itemize | |
16280 | ||
16281 | GNAT itself supports programs with only a single partition. The GNATDIST | |
16282 | tool provided with the GLADE package (which also includes an implementation | |
16283 | of the PCS) provides a completely flexible method for building and running | |
16284 | programs consisting of multiple partitions. See the separate GLADE manual | |
16285 | for details. | |
16286 | ||
16287 | ||
16288 | @itemize * | |
16289 | ||
16290 | @item | |
16291 | “The details of program execution, including program | |
16292 | termination. See 10.2(25).” | |
16293 | @end itemize | |
16294 | ||
16295 | See separate section on compilation model. | |
16296 | ||
16297 | ||
16298 | @itemize * | |
16299 | ||
16300 | @item | |
16301 | “The semantics of any non-active partitions supported by the | |
16302 | implementation. See 10.2(28).” | |
16303 | @end itemize | |
16304 | ||
16305 | Passive partitions are supported on targets where shared memory is | |
16306 | provided by the operating system. See the GLADE reference manual for | |
16307 | further details. | |
16308 | ||
16309 | ||
16310 | @itemize * | |
16311 | ||
16312 | @item | |
16313 | “The information returned by @code{Exception_Message}. See 11.4.1(10).” | |
16314 | @end itemize | |
16315 | ||
16316 | Exception message returns the null string unless a specific message has | |
16317 | been passed by the program. | |
16318 | ||
16319 | ||
16320 | @itemize * | |
16321 | ||
16322 | @item | |
16323 | “The result of @code{Exceptions.Exception_Name} for types | |
16324 | declared within an unnamed `block_statement'. See 11.4.1(12).” | |
16325 | @end itemize | |
16326 | ||
16327 | Blocks have implementation defined names of the form @code{B@var{nnn}} | |
16328 | where `nnn' is an integer. | |
16329 | ||
16330 | ||
16331 | @itemize * | |
16332 | ||
16333 | @item | |
16334 | “The information returned by | |
16335 | @code{Exception_Information}. See 11.4.1(13).” | |
16336 | @end itemize | |
16337 | ||
16338 | @code{Exception_Information} returns a string in the following format: | |
16339 | ||
16340 | @example | |
16341 | *Exception_Name:* nnnnn | |
16342 | *Message:* mmmmm | |
16343 | *PID:* ppp | |
16344 | *Load address:* 0xhhhh | |
16345 | *Call stack traceback locations:* | |
16346 | 0xhhhh 0xhhhh 0xhhhh ... 0xhhh | |
16347 | @end example | |
16348 | ||
16349 | where | |
16350 | ||
16351 | @quotation | |
16352 | ||
16353 | ||
16354 | @itemize * | |
16355 | ||
16356 | @item | |
16357 | @code{nnnn} is the fully qualified name of the exception in all upper | |
16358 | case letters. This line is always present. | |
16359 | ||
16360 | @item | |
16361 | @code{mmmm} is the message (this line present only if message is non-null) | |
16362 | ||
16363 | @item | |
16364 | @code{ppp} is the Process Id value as a decimal integer (this line is | |
16365 | present only if the Process Id is nonzero). Currently we are | |
16366 | not making use of this field. | |
16367 | ||
16368 | @item | |
16369 | The Load address line, the Call stack traceback locations line and the | |
16370 | following values are present only if at least one traceback location was | |
16371 | recorded. The Load address indicates the address at which the main executable | |
16372 | was loaded; this line may not be present if operating system hasn’t relocated | |
16373 | the main executable. The values are given in C style format, with lower case | |
16374 | letters for a-f, and only as many digits present as are necessary. | |
16375 | The line terminator sequence at the end of each line, including | |
16376 | the last line is a single @code{LF} character (@code{16#0A#}). | |
16377 | @end itemize | |
16378 | @end quotation | |
16379 | ||
16380 | ||
16381 | @itemize * | |
16382 | ||
16383 | @item | |
16384 | “The sequence of characters of the value returned by | |
16385 | Exceptions.Exception_Name (respectively, Exceptions.Wide_Exception_Name) | |
16386 | when some of the graphic characters of Exceptions.Wide_Wide_Exception_Name | |
16387 | are not defined in Character (respectively, Wide_Character). | |
16388 | See 11.4.1(12.1).” | |
16389 | @end itemize | |
16390 | ||
16391 | This is handled in the same way as the implementation-defined behavior | |
16392 | referenced in A.4.12(34). | |
16393 | ||
16394 | ||
16395 | @itemize * | |
16396 | ||
16397 | @item | |
16398 | “The information returned by Exception_Information. See 11.4.1(13).” | |
16399 | @end itemize | |
16400 | ||
16401 | The exception name and the source location at which the exception was | |
16402 | raised are included. | |
16403 | ||
16404 | ||
16405 | @itemize * | |
16406 | ||
16407 | @item | |
16408 | “Implementation-defined policy_identifiers and assertion_aspect_marks | |
16409 | allowed in a pragma Assertion_Policy. See 11.4.2(9).” | |
16410 | @end itemize | |
16411 | ||
16412 | Implementation-defined assertion_aspect_marks include Assert_And_Cut, | |
16413 | Assume, Contract_Cases, Debug, Ghost, Initial_Condition, Loop_Invariant, | |
16414 | Loop_Variant, Postcondition, Precondition, Predicate, Refined_Post, | |
16415 | Statement_Assertions, and Subprogram_Variant. Implementation-defined | |
16416 | policy_identifiers include Ignore and Suppressible. | |
16417 | ||
16418 | ||
16419 | @itemize * | |
16420 | ||
16421 | @item | |
16422 | “The default assertion policy. See 11.4.2(10).” | |
16423 | @end itemize | |
16424 | ||
16425 | The default assertion policy is Ignore, although this can be overridden | |
16426 | via compiler switches such as “-gnata”. | |
16427 | ||
16428 | ||
16429 | @itemize * | |
16430 | ||
16431 | @item | |
16432 | “Implementation-defined check names. See 11.5(27).” | |
16433 | @end itemize | |
16434 | ||
16435 | The implementation defined check names include Alignment_Check, | |
16436 | Atomic_Synchronization, Duplicated_Tag_Check, Container_Checks, | |
16437 | Tampering_Check, Predicate_Check, and Validity_Check. In addition, a user | |
16438 | program can add implementation-defined check names by means of the pragma | |
16439 | Check_Name. See the description of pragma @code{Suppress} for full details. | |
16440 | ||
16441 | ||
16442 | @itemize * | |
16443 | ||
16444 | @item | |
16445 | “Existence and meaning of second parameter of pragma Unsuppress. | |
16446 | See 11.5(27.1).” | |
16447 | @end itemize | |
16448 | ||
16449 | The legality rules for and semantics of the second parameter of pragma | |
16450 | Unsuppress match those for the second argument of pragma Suppress. | |
16451 | ||
16452 | ||
16453 | @itemize * | |
16454 | ||
16455 | @item | |
16456 | “The cases that cause conflicts between the representation of the | |
16457 | ancestors of a type_declaration. See 13.1(13.1).” | |
16458 | @end itemize | |
16459 | ||
16460 | No such cases exist. | |
16461 | ||
16462 | ||
16463 | @itemize * | |
16464 | ||
16465 | @item | |
16466 | “The interpretation of each representation aspect. See 13.1(20).” | |
16467 | @end itemize | |
16468 | ||
16469 | See separate section on data representations. | |
16470 | ||
16471 | ||
16472 | @itemize * | |
16473 | ||
16474 | @item | |
16475 | “Any restrictions placed upon the specification of representation aspects. | |
16476 | See 13.1(20).” | |
16477 | @end itemize | |
16478 | ||
16479 | See separate section on data representations. | |
16480 | ||
16481 | ||
16482 | @itemize * | |
16483 | ||
16484 | @item | |
16485 | “Implementation-defined aspects, including the syntax for specifying | |
16486 | such aspects and the legality rules for such aspects. See 13.1.1(38).” | |
16487 | @end itemize | |
16488 | ||
04d6c745 | 16489 | See @ref{125,,Implementation Defined Aspects}. |
64d5610f ML |
16490 | |
16491 | ||
16492 | @itemize * | |
16493 | ||
16494 | @item | |
16495 | “The set of machine scalars. See 13.3(8.1).” | |
16496 | @end itemize | |
16497 | ||
16498 | See separate section on data representations. | |
16499 | ||
16500 | ||
16501 | @itemize * | |
16502 | ||
16503 | @item | |
16504 | “The meaning of @code{Size} for indefinite subtypes. See 13.3(48).” | |
16505 | @end itemize | |
16506 | ||
16507 | The Size attribute of an indefinite subtype is not less than the Size | |
16508 | attribute of any object of that type. | |
16509 | ||
16510 | ||
16511 | @itemize * | |
16512 | ||
16513 | @item | |
16514 | “The meaning of Object_Size for indefinite subtypes. See 13.3(58).” | |
16515 | @end itemize | |
16516 | ||
16517 | The Object_Size attribute of an indefinite subtype is not less than the | |
16518 | Object_Size attribute of any object of that type. | |
16519 | ||
16520 | ||
16521 | @itemize * | |
16522 | ||
16523 | @item | |
16524 | “The default external representation for a type tag. See 13.3(75).” | |
16525 | @end itemize | |
16526 | ||
16527 | The default external representation for a type tag is the fully expanded | |
16528 | name of the type in upper case letters. | |
16529 | ||
16530 | ||
16531 | @itemize * | |
16532 | ||
16533 | @item | |
16534 | “What determines whether a compilation unit is the same in | |
16535 | two different partitions. See 13.3(76).” | |
16536 | @end itemize | |
16537 | ||
16538 | A compilation unit is the same in two different partitions if and only | |
16539 | if it derives from the same source file. | |
16540 | ||
16541 | ||
16542 | @itemize * | |
16543 | ||
16544 | @item | |
16545 | “Implementation-defined components. See 13.5.1(15).” | |
16546 | @end itemize | |
16547 | ||
16548 | The only implementation defined component is the tag for a tagged type, | |
16549 | which contains a pointer to the dispatching table. | |
16550 | ||
16551 | ||
16552 | @itemize * | |
16553 | ||
16554 | @item | |
16555 | “If @code{Word_Size} = @code{Storage_Unit}, the default bit | |
16556 | ordering. See 13.5.3(5).” | |
16557 | @end itemize | |
16558 | ||
16559 | @code{Word_Size} (32) is not the same as @code{Storage_Unit} (8) for this | |
16560 | implementation, so no non-default bit ordering is supported. The default | |
16561 | bit ordering corresponds to the natural endianness of the target architecture. | |
16562 | ||
16563 | ||
16564 | @itemize * | |
16565 | ||
16566 | @item | |
16567 | “The contents of the visible part of package @code{System}. See 13.7(2).” | |
16568 | @end itemize | |
16569 | ||
16570 | See the definition of package System in @code{system.ads}. | |
16571 | Note that two declarations are added to package System. | |
16572 | ||
16573 | @example | |
16574 | Max_Priority : constant Positive := Priority'Last; | |
16575 | Max_Interrupt_Priority : constant Positive := Interrupt_Priority'Last; | |
16576 | @end example | |
16577 | ||
16578 | ||
16579 | @itemize * | |
16580 | ||
16581 | @item | |
16582 | “The range of Storage_Elements.Storage_Offset, the modulus of | |
16583 | Storage_Elements.Storage_Element, and the declaration of | |
16584 | Storage_Elements.Integer_Address. See 13.7.1(11).” | |
16585 | @end itemize | |
16586 | ||
16587 | See the definition of package System.Storage_Elements in @code{s-stoele.ads}. | |
16588 | ||
16589 | ||
16590 | @itemize * | |
16591 | ||
16592 | @item | |
16593 | “The contents of the visible part of package @code{System.Machine_Code}, | |
16594 | and the meaning of `code_statements'. See 13.8(7).” | |
16595 | @end itemize | |
16596 | ||
16597 | See the definition and documentation in file @code{s-maccod.ads}. | |
16598 | ||
16599 | ||
16600 | @itemize * | |
16601 | ||
16602 | @item | |
16603 | “The result of unchecked conversion for instances with scalar result | |
16604 | types whose result is not defined by the language. See 13.9(11).” | |
16605 | @end itemize | |
16606 | ||
16607 | Unchecked conversion between types of the same size | |
16608 | results in an uninterpreted transmission of the bits from one type | |
16609 | to the other. If the types are of unequal sizes, then in the case of | |
16610 | discrete types, a shorter source is first zero or sign extended as | |
16611 | necessary, and a shorter target is simply truncated on the left. | |
16612 | For all non-discrete types, the source is first copied if necessary | |
16613 | to ensure that the alignment requirements of the target are met, then | |
16614 | a pointer is constructed to the source value, and the result is obtained | |
16615 | by dereferencing this pointer after converting it to be a pointer to the | |
16616 | target type. Unchecked conversions where the target subtype is an | |
16617 | unconstrained array are not permitted. If the target alignment is | |
16618 | greater than the source alignment, then a copy of the result is | |
16619 | made with appropriate alignment | |
16620 | ||
16621 | ||
16622 | @itemize * | |
16623 | ||
16624 | @item | |
16625 | “The result of unchecked conversion for instances with nonscalar result | |
16626 | types whose result is not defined by the language. See 13.9(11).” | |
16627 | @end itemize | |
16628 | ||
16629 | See preceding definition for the scalar result case. | |
16630 | ||
16631 | ||
16632 | @itemize * | |
16633 | ||
16634 | @item | |
16635 | “Whether or not the implementation provides user-accessible | |
16636 | names for the standard pool type(s). See 13.11(17).” | |
16637 | @end itemize | |
16638 | ||
16639 | There are 3 different standard pools used by the compiler when | |
16640 | @code{Storage_Pool} is not specified depending whether the type is local | |
16641 | to a subprogram or defined at the library level and whether | |
16642 | @code{Storage_Size`@w{`}is specified or not. See documentation in the runtime | |
16643 | library units `@w{`}System.Pool_Global}, @code{System.Pool_Size} and | |
16644 | @code{System.Pool_Local} in files @code{s-poosiz.ads}, | |
16645 | @code{s-pooglo.ads} and @code{s-pooloc.ads} for full details on the | |
16646 | default pools used. All these pools are accessible by means of @cite{with}ing | |
16647 | these units. | |
16648 | ||
16649 | ||
16650 | @itemize * | |
16651 | ||
16652 | @item | |
16653 | “The meaning of @code{Storage_Size} when neither the Storage_Size nor the | |
16654 | Storage_Pool is specified for an access type. See 13.11(18).” | |
16655 | @end itemize | |
16656 | ||
16657 | @code{Storage_Size} is measured in storage units, and refers to the | |
16658 | total space available for an access type collection, or to the primary | |
16659 | stack space for a task. | |
16660 | ||
16661 | ||
16662 | @itemize * | |
16663 | ||
16664 | @item | |
16665 | “The effect of specifying aspect Default_Storage_Pool on an instance | |
16666 | of a language-defined generic unit. See 13.11.3(5).” | |
16667 | @end itemize | |
16668 | ||
16669 | Instances of language-defined generic units are treated the same as other | |
16670 | instances with respect to the Default_Storage_Pool aspect. | |
16671 | ||
16672 | ||
16673 | @itemize * | |
16674 | ||
16675 | @item | |
16676 | “Implementation-defined restrictions allowed in a pragma | |
16677 | @code{Restrictions}. See 13.12(8.7).” | |
16678 | @end itemize | |
16679 | ||
16680 | See @ref{9,,Standard and Implementation Defined Restrictions}. | |
16681 | ||
16682 | ||
16683 | @itemize * | |
16684 | ||
16685 | @item | |
16686 | “The consequences of violating limitations on | |
16687 | @code{Restrictions} pragmas. See 13.12(9).” | |
16688 | @end itemize | |
16689 | ||
16690 | Restrictions that can be checked at compile time are enforced at | |
16691 | compile time; violations are illegal. For other restrictions, any | |
16692 | violation during program execution results in erroneous execution. | |
16693 | ||
16694 | ||
16695 | @itemize * | |
16696 | ||
16697 | @item | |
16698 | “Implementation-defined usage profiles allowed in a pragma Profile. | |
16699 | See 13.12(15).” | |
16700 | @end itemize | |
16701 | ||
16702 | See @ref{7,,Implementation Defined Pragmas}. | |
16703 | ||
16704 | ||
16705 | @itemize * | |
16706 | ||
16707 | @item | |
16708 | “The contents of the stream elements read and written by the Read and | |
16709 | Write attributes of elementary types. See 13.13.2(9).” | |
16710 | @end itemize | |
16711 | ||
16712 | The representation is the in-memory representation of the base type of | |
16713 | the type, using the number of bits corresponding to the | |
16714 | @code{type'Size} value, and the natural ordering of the machine. | |
16715 | ||
16716 | ||
16717 | @itemize * | |
16718 | ||
16719 | @item | |
16720 | “The names and characteristics of the numeric subtypes | |
16721 | declared in the visible part of package @code{Standard}. See A.1(3).” | |
16722 | @end itemize | |
16723 | ||
16724 | See items describing the integer and floating-point types supported. | |
16725 | ||
16726 | ||
16727 | @itemize * | |
16728 | ||
16729 | @item | |
16730 | “The values returned by Strings.Hash. See A.4.9(3).” | |
16731 | @end itemize | |
16732 | ||
16733 | This hash function has predictable collisions and is subject to | |
16734 | equivalent substring attacks. It is not suitable for construction of a | |
16735 | hash table keyed on possibly malicious user input. | |
16736 | ||
16737 | ||
16738 | @itemize * | |
16739 | ||
16740 | @item | |
16741 | “The value returned by a call to a Text_Buffer Get procedure if any | |
16742 | character in the returned sequence is not defined in Character. | |
16743 | See A.4.12(34).” | |
16744 | @end itemize | |
16745 | ||
16746 | The contents of a buffer is represented internally as a UTF_8 string. | |
16747 | The value return by Text_Buffer.Get is the result of passing that | |
16748 | UTF_8 string to UTF_Encoding.Strings.Decode. | |
16749 | ||
16750 | ||
16751 | @itemize * | |
16752 | ||
16753 | @item | |
16754 | “The value returned by a call to a Text_Buffer Wide_Get procedure if | |
16755 | any character in the returned sequence is not defined in Wide_Character. | |
16756 | See A.4.12(34).” | |
16757 | @end itemize | |
16758 | ||
16759 | The contents of a buffer is represented internally as a UTF_8 string. | |
16760 | The value return by Text_Buffer.Wide_Get is the result of passing that | |
16761 | UTF_8 string to UTF_Encoding.Wide_Strings.Decode. | |
16762 | ||
16763 | ||
16764 | @itemize * | |
16765 | ||
16766 | @item | |
16767 | “The accuracy actually achieved by the elementary | |
16768 | functions. See A.5.1(1).” | |
16769 | @end itemize | |
16770 | ||
16771 | The elementary functions correspond to the functions available in the C | |
16772 | library. Only fast math mode is implemented. | |
16773 | ||
16774 | ||
16775 | @itemize * | |
16776 | ||
16777 | @item | |
16778 | “The sign of a zero result from some of the operators or | |
16779 | functions in @code{Numerics.Generic_Elementary_Functions}, when | |
16780 | @code{Float_Type'Signed_Zeros} is @code{True}. See A.5.1(46).” | |
16781 | @end itemize | |
16782 | ||
16783 | The sign of zeroes follows the requirements of the IEEE 754 standard on | |
16784 | floating-point. | |
16785 | ||
16786 | ||
16787 | @itemize * | |
16788 | ||
16789 | @item | |
16790 | “The value of | |
16791 | @code{Numerics.Float_Random.Max_Image_Width}. See A.5.2(27).” | |
16792 | @end itemize | |
16793 | ||
16794 | Maximum image width is 6864, see library file @code{s-rannum.ads}. | |
16795 | ||
16796 | ||
16797 | @itemize * | |
16798 | ||
16799 | @item | |
16800 | “The value of | |
16801 | @code{Numerics.Discrete_Random.Max_Image_Width}. See A.5.2(27).” | |
16802 | @end itemize | |
16803 | ||
16804 | Maximum image width is 6864, see library file @code{s-rannum.ads}. | |
16805 | ||
16806 | ||
16807 | @itemize * | |
16808 | ||
16809 | @item | |
16810 | “The string representation of a random number generator’s | |
16811 | state. See A.5.2(38).” | |
16812 | @end itemize | |
16813 | ||
16814 | The value returned by the Image function is the concatenation of | |
16815 | the fixed-width decimal representations of the 624 32-bit integers | |
16816 | of the state vector. | |
16817 | ||
16818 | ||
16819 | @itemize * | |
16820 | ||
16821 | @item | |
16822 | “The values of the @code{Model_Mantissa}, | |
16823 | @code{Model_Emin}, @code{Model_Epsilon}, @code{Model}, | |
16824 | @code{Safe_First}, and @code{Safe_Last} attributes, if the Numerics | |
16825 | Annex is not supported. See A.5.3(72).” | |
16826 | @end itemize | |
16827 | ||
16828 | Running the compiler with `-gnatS' to produce a listing of package | |
16829 | @code{Standard} displays the values of these attributes. | |
16830 | ||
16831 | ||
16832 | @itemize * | |
16833 | ||
16834 | @item | |
16835 | “The value of @code{Buffer_Size} in @code{Storage_IO}. See A.9(10).” | |
16836 | @end itemize | |
16837 | ||
16838 | All type representations are contiguous, and the @code{Buffer_Size} is | |
16839 | the value of @code{type'Size} rounded up to the next storage unit | |
16840 | boundary. | |
16841 | ||
16842 | ||
16843 | @itemize * | |
16844 | ||
16845 | @item | |
16846 | “External files for standard input, standard output, and | |
16847 | standard error See A.10(5).” | |
16848 | @end itemize | |
16849 | ||
16850 | These files are mapped onto the files provided by the C streams | |
16851 | libraries. See source file @code{i-cstrea.ads} for further details. | |
16852 | ||
16853 | ||
16854 | @itemize * | |
16855 | ||
16856 | @item | |
16857 | “The accuracy of the value produced by @code{Put}. See A.10.9(36).” | |
16858 | @end itemize | |
16859 | ||
16860 | If more digits are requested in the output than are represented by the | |
16861 | precision of the value, zeroes are output in the corresponding least | |
16862 | significant digit positions. | |
16863 | ||
16864 | ||
16865 | @itemize * | |
16866 | ||
16867 | @item | |
16868 | “Current size for a stream file for which positioning is not supported. | |
16869 | See A.12.1(1.1).” | |
16870 | @end itemize | |
16871 | ||
16872 | Positioning is supported. | |
16873 | ||
16874 | ||
16875 | @itemize * | |
16876 | ||
16877 | @item | |
16878 | “The meaning of @code{Argument_Count}, @code{Argument}, and | |
16879 | @code{Command_Name}. See A.15(1).” | |
16880 | @end itemize | |
16881 | ||
16882 | These are mapped onto the @code{argv} and @code{argc} parameters of the | |
16883 | main program in the natural manner. | |
16884 | ||
16885 | ||
16886 | @itemize * | |
16887 | ||
16888 | @item | |
16889 | “The interpretation of file names and directory names. See A.16(46).” | |
16890 | @end itemize | |
16891 | ||
16892 | These names are interpreted consistently with the underlying file system. | |
16893 | ||
16894 | ||
16895 | @itemize * | |
16896 | ||
16897 | @item | |
16898 | “The maxium value for a file size in Directories. See A.16(87).” | |
16899 | @end itemize | |
16900 | ||
16901 | Directories.File_Size’Last is equal to Long_Long_Integer’Last . | |
16902 | ||
16903 | ||
16904 | @itemize * | |
16905 | ||
16906 | @item | |
16907 | “The result for Directories.Size for a directory or special file. | |
16908 | See A.16(93).” | |
16909 | @end itemize | |
16910 | ||
16911 | Name_Error is raised. | |
16912 | ||
16913 | ||
16914 | @itemize * | |
16915 | ||
16916 | @item | |
16917 | “The result for Directories.Modification_Time for a directory or special file. | |
16918 | See A.16(93).” | |
16919 | @end itemize | |
16920 | ||
16921 | Name_Error is raised. | |
16922 | ||
16923 | ||
16924 | @itemize * | |
16925 | ||
16926 | @item | |
16927 | “The interpretation of a nonnull search pattern in Directories. | |
16928 | See A.16(104).” | |
16929 | @end itemize | |
16930 | ||
16931 | When the @code{Pattern} parameter is not the null string, it is interpreted | |
16932 | according to the syntax of regular expressions as defined in the | |
16933 | @code{GNAT.Regexp} package. | |
16934 | ||
04d6c745 | 16935 | See @ref{265,,GNAT.Regexp (g-regexp.ads)}. |
64d5610f ML |
16936 | |
16937 | ||
16938 | @itemize * | |
16939 | ||
16940 | @item | |
16941 | “The results of a Directories search if the contents of the directory are | |
16942 | altered while a search is in progress. See A.16(110).” | |
16943 | @end itemize | |
16944 | ||
16945 | The effect of a call to Get_Next_Entry is determined by the current | |
16946 | state of the directory. | |
16947 | ||
16948 | ||
16949 | @itemize * | |
16950 | ||
16951 | @item | |
16952 | “The definition and meaning of an environment variable. See A.17(1).” | |
16953 | @end itemize | |
16954 | ||
16955 | This definition is determined by the underlying operating system. | |
16956 | ||
16957 | ||
16958 | @itemize * | |
16959 | ||
16960 | @item | |
16961 | “The circumstances where an environment variable cannot be defined. | |
16962 | See A.17(16).” | |
f571a201 | 16963 | @end itemize |
64d5610f ML |
16964 | |
16965 | There are no such implementation-defined circumstances. | |
16966 | ||
f571a201 RD |
16967 | |
16968 | @itemize * | |
16969 | ||
64d5610f ML |
16970 | @item |
16971 | “Environment names for which Set has the effect of Clear. See A.17(17).” | |
16972 | @end itemize | |
16973 | ||
16974 | There are no such names. | |
16975 | ||
16976 | ||
16977 | @itemize * | |
16978 | ||
16979 | @item | |
16980 | “The value of Containers.Hash_Type’Modulus. The value of | |
16981 | Containers.Count_Type’Last. See A.18.1(7).” | |
16982 | @end itemize | |
16983 | ||
16984 | Containers.Hash_Type’Modulus is 2**32. | |
16985 | Containers.Count_Type’Last is 2**31 - 1. | |
16986 | ||
16987 | ||
16988 | @itemize * | |
16989 | ||
16990 | @item | |
16991 | “Implementation-defined convention names. See B.1(11).” | |
16992 | @end itemize | |
16993 | ||
16994 | The following convention names are supported | |
16995 | ||
16996 | ||
16997 | @multitable {xxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} | |
16998 | @headitem | |
16999 | ||
17000 | Convention Name | |
17001 | ||
17002 | @tab | |
17003 | ||
17004 | Interpretation | |
17005 | ||
17006 | @item | |
17007 | ||
17008 | `Ada' | |
17009 | ||
17010 | @tab | |
17011 | ||
17012 | Ada | |
17013 | ||
17014 | @item | |
17015 | ||
17016 | `Ada_Pass_By_Copy' | |
17017 | ||
17018 | @tab | |
17019 | ||
17020 | Allowed for any types except by-reference types such as limited | |
17021 | records. Compatible with convention Ada, but causes any parameters | |
17022 | with this convention to be passed by copy. | |
17023 | ||
17024 | @item | |
17025 | ||
17026 | `Ada_Pass_By_Reference' | |
17027 | ||
17028 | @tab | |
17029 | ||
17030 | Allowed for any types except by-copy types such as scalars. | |
17031 | Compatible with convention Ada, but causes any parameters | |
17032 | with this convention to be passed by reference. | |
17033 | ||
17034 | @item | |
17035 | ||
17036 | `Assembler' | |
17037 | ||
17038 | @tab | |
17039 | ||
17040 | Assembly language | |
17041 | ||
17042 | @item | |
17043 | ||
17044 | `Asm' | |
17045 | ||
17046 | @tab | |
17047 | ||
17048 | Synonym for Assembler | |
17049 | ||
17050 | @item | |
17051 | ||
17052 | `Assembly' | |
17053 | ||
17054 | @tab | |
17055 | ||
17056 | Synonym for Assembler | |
17057 | ||
17058 | @item | |
17059 | ||
17060 | `C' | |
17061 | ||
17062 | @tab | |
17063 | ||
17064 | C | |
17065 | ||
17066 | @item | |
17067 | ||
17068 | `C_Pass_By_Copy' | |
17069 | ||
17070 | @tab | |
17071 | ||
17072 | Allowed only for record types, like C, but also notes that record | |
17073 | is to be passed by copy rather than reference. | |
17074 | ||
17075 | @item | |
17076 | ||
17077 | `COBOL' | |
17078 | ||
17079 | @tab | |
17080 | ||
17081 | COBOL | |
17082 | ||
17083 | @item | |
17084 | ||
17085 | `C_Plus_Plus (or CPP)' | |
17086 | ||
17087 | @tab | |
17088 | ||
17089 | C++ | |
17090 | ||
17091 | @item | |
17092 | ||
17093 | `Default' | |
17094 | ||
17095 | @tab | |
17096 | ||
17097 | Treated the same as C | |
17098 | ||
17099 | @item | |
17100 | ||
17101 | `External' | |
17102 | ||
17103 | @tab | |
17104 | ||
17105 | Treated the same as C | |
17106 | ||
17107 | @item | |
17108 | ||
17109 | `Fortran' | |
17110 | ||
17111 | @tab | |
17112 | ||
17113 | Fortran | |
17114 | ||
17115 | @item | |
17116 | ||
17117 | `Intrinsic' | |
17118 | ||
17119 | @tab | |
17120 | ||
17121 | For support of pragma @code{Import} with convention Intrinsic, see | |
17122 | separate section on Intrinsic Subprograms. | |
17123 | ||
17124 | @item | |
17125 | ||
17126 | `Stdcall' | |
17127 | ||
17128 | @tab | |
17129 | ||
17130 | Stdcall (used for Windows implementations only). This convention correspond | |
17131 | to the WINAPI (previously called Pascal convention) C/C++ convention under | |
17132 | Windows. A routine with this convention cleans the stack before | |
17133 | exit. This pragma cannot be applied to a dispatching call. | |
17134 | ||
17135 | @item | |
17136 | ||
17137 | `DLL' | |
17138 | ||
17139 | @tab | |
17140 | ||
17141 | Synonym for Stdcall | |
17142 | ||
17143 | @item | |
17144 | ||
17145 | `Win32' | |
17146 | ||
17147 | @tab | |
17148 | ||
17149 | Synonym for Stdcall | |
17150 | ||
17151 | @item | |
17152 | ||
17153 | `Stubbed' | |
17154 | ||
17155 | @tab | |
17156 | ||
17157 | Stubbed is a special convention used to indicate that the body of the | |
17158 | subprogram will be entirely ignored. Any call to the subprogram | |
17159 | is converted into a raise of the @code{Program_Error} exception. If a | |
17160 | pragma @code{Import} specifies convention @code{stubbed} then no body need | |
17161 | be present at all. This convention is useful during development for the | |
17162 | inclusion of subprograms whose body has not yet been written. | |
17163 | In addition, all otherwise unrecognized convention names are also | |
17164 | treated as being synonymous with convention C. In all implementations, | |
17165 | use of such other names results in a warning. | |
17166 | ||
17167 | @end multitable | |
17168 | ||
17169 | ||
17170 | ||
17171 | @itemize * | |
17172 | ||
17173 | @item | |
17174 | “The meaning of link names. See B.1(36).” | |
17175 | @end itemize | |
17176 | ||
17177 | Link names are the actual names used by the linker. | |
17178 | ||
17179 | ||
17180 | @itemize * | |
17181 | ||
17182 | @item | |
17183 | “The manner of choosing link names when neither the link name nor the | |
17184 | address of an imported or exported entity is specified. See B.1(36).” | |
17185 | @end itemize | |
17186 | ||
17187 | The default linker name is that which would be assigned by the relevant | |
17188 | external language, interpreting the Ada name as being in all lower case | |
17189 | letters. | |
17190 | ||
17191 | ||
17192 | @itemize * | |
17193 | ||
17194 | @item | |
17195 | “The effect of pragma @code{Linker_Options}. See B.1(37).” | |
17196 | @end itemize | |
17197 | ||
17198 | The string passed to @code{Linker_Options} is presented uninterpreted as | |
17199 | an argument to the link command, unless it contains ASCII.NUL characters. | |
17200 | NUL characters if they appear act as argument separators, so for example | |
17201 | ||
17202 | @example | |
17203 | pragma Linker_Options ("-labc" & ASCII.NUL & "-ldef"); | |
17204 | @end example | |
17205 | ||
17206 | causes two separate arguments @code{-labc} and @code{-ldef} to be passed to the | |
17207 | linker. The order of linker options is preserved for a given unit. The final | |
17208 | list of options passed to the linker is in reverse order of the elaboration | |
17209 | order. For example, linker options for a body always appear before the options | |
17210 | from the corresponding package spec. | |
17211 | ||
17212 | ||
17213 | @itemize * | |
17214 | ||
17215 | @item | |
17216 | “The contents of the visible part of package | |
17217 | @code{Interfaces} and its language-defined descendants. See B.2(1).” | |
17218 | @end itemize | |
17219 | ||
17220 | See files with prefix @code{i-} in the distributed library. | |
17221 | ||
17222 | ||
17223 | @itemize * | |
17224 | ||
17225 | @item | |
17226 | “Implementation-defined children of package | |
17227 | @code{Interfaces}. The contents of the visible part of package | |
17228 | @code{Interfaces}. See B.2(11).” | |
17229 | @end itemize | |
17230 | ||
17231 | See files with prefix @code{i-} in the distributed library. | |
17232 | ||
17233 | ||
17234 | @itemize * | |
17235 | ||
17236 | @item | |
17237 | “The definitions of certain types and constants in Interfaces.C. | |
17238 | See B.3(41).” | |
17239 | @end itemize | |
17240 | ||
17241 | See source file @code{i-c.ads}. | |
17242 | ||
17243 | ||
17244 | @itemize * | |
17245 | ||
17246 | @item | |
17247 | “The types @code{Floating}, @code{Long_Floating}, | |
17248 | @code{Binary}, @code{Long_Binary}, @code{Decimal_ Element}, and | |
17249 | @code{COBOL_Character}; and the initialization of the variables | |
17250 | @code{Ada_To_COBOL} and @code{COBOL_To_Ada}, in | |
17251 | @code{Interfaces.COBOL}. See B.4(50).” | |
17252 | @end itemize | |
17253 | ||
17254 | ||
17255 | @multitable {xxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} | |
17256 | @headitem | |
17257 | ||
17258 | COBOL | |
17259 | ||
17260 | @tab | |
17261 | ||
17262 | Ada | |
17263 | ||
17264 | @item | |
17265 | ||
17266 | `Floating' | |
17267 | ||
17268 | @tab | |
17269 | ||
17270 | Float | |
17271 | ||
17272 | @item | |
17273 | ||
17274 | `Long_Floating' | |
17275 | ||
17276 | @tab | |
17277 | ||
17278 | (Floating) Long_Float | |
17279 | ||
17280 | @item | |
17281 | ||
17282 | `Binary' | |
17283 | ||
17284 | @tab | |
17285 | ||
17286 | Integer | |
17287 | ||
17288 | @item | |
17289 | ||
17290 | `Long_Binary' | |
17291 | ||
17292 | @tab | |
17293 | ||
17294 | Long_Long_Integer | |
17295 | ||
17296 | @item | |
17297 | ||
17298 | `Decimal_Element' | |
17299 | ||
17300 | @tab | |
17301 | ||
17302 | Character | |
17303 | ||
17304 | @item | |
17305 | ||
17306 | `COBOL_Character' | |
17307 | ||
17308 | @tab | |
17309 | ||
17310 | Character | |
17311 | ||
17312 | @end multitable | |
17313 | ||
17314 | ||
17315 | For initialization, see the file @code{i-cobol.ads} in the distributed library. | |
17316 | ||
17317 | ||
17318 | @itemize * | |
17319 | ||
17320 | @item | |
17321 | “The types Fortran_Integer, Real, Double_Precision, and Character_Set | |
17322 | in Interfaces.Fortran. See B.5(17).” | |
17323 | @end itemize | |
17324 | ||
17325 | See source file @code{i-fortra.ads}. These types are derived, respectively, | |
17326 | from Integer, Float, Long_Float, and Character. | |
17327 | ||
17328 | ||
17329 | @itemize * | |
17330 | ||
17331 | @item | |
17332 | “Implementation-defined intrinsic subprograms. See C.1(1).” | |
17333 | @end itemize | |
17334 | ||
17335 | See separate section on Intrinsic Subprograms. | |
17336 | ||
17337 | ||
17338 | @itemize * | |
17339 | ||
17340 | @item | |
17341 | “Any restrictions on a protected procedure or its containing type when an | |
17342 | aspect Attach_handler or Interrupt_Handler is specified. See C.3.1(17).” | |
17343 | @end itemize | |
17344 | ||
17345 | There are no such restrictions. | |
17346 | ||
17347 | ||
17348 | @itemize * | |
17349 | ||
17350 | @item | |
17351 | “Any other forms of interrupt handler supported by the Attach_Handler and | |
17352 | Interrupt_Handler aspects. See C.3.1(19).” | |
17353 | @end itemize | |
17354 | ||
17355 | There are no such forms. | |
17356 | ||
17357 | ||
17358 | @itemize * | |
17359 | ||
17360 | @item | |
17361 | “The semantics of some attributes and functions of an entity for which | |
17362 | aspect Discard_Names is True. See C.5(7).” | |
17363 | @end itemize | |
17364 | ||
17365 | If Discard_Names is True for an enumeration type, the Image attribute | |
17366 | provides the image of the Pos of the literal, and Value accepts | |
17367 | Pos values. | |
17368 | ||
17369 | If both of the aspects`@w{`}Discard_Names`@w{`} and @code{No_Tagged_Streams} are true | |
17370 | for a tagged type, its Expanded_Name and External_Tag values are | |
17371 | empty strings. This is useful to avoid exposing entity names at binary | |
17372 | level. | |
17373 | ||
17374 | ||
17375 | @itemize * | |
17376 | ||
17377 | @item | |
17378 | “The modulus and size of Test_and_Set_Flag. See C.6.3(8).” | |
17379 | @end itemize | |
17380 | ||
17381 | The modulus is 2**8. The size is 8. | |
17382 | ||
17383 | ||
17384 | @itemize * | |
17385 | ||
17386 | @item | |
17387 | “The value used to represent the set value for Atomic_Test_and_Set. | |
17388 | See C.6.3(10).” | |
17389 | @end itemize | |
17390 | ||
17391 | The value is 1. | |
17392 | ||
17393 | ||
17394 | @itemize * | |
17395 | ||
17396 | @item | |
17397 | “The result of the @code{Task_Identification.Image} | |
17398 | attribute. See C.7.1(7).” | |
17399 | @end itemize | |
17400 | ||
17401 | The result of this attribute is a string that identifies | |
17402 | the object or component that denotes a given task. If a variable @code{Var} | |
17403 | has a task type, the image for this task will have the form @code{Var_@var{XXXXXXXX}}, | |
17404 | where the suffix `XXXXXXXX' | |
17405 | is the hexadecimal representation of the virtual address of the corresponding | |
17406 | task control block. If the variable is an array of tasks, the image of each | |
17407 | task will have the form of an indexed component indicating the position of a | |
17408 | given task in the array, e.g., @code{Group(5)_@var{XXXXXXX}}. If the task is a | |
17409 | component of a record, the image of the task will have the form of a selected | |
17410 | component. These rules are fully recursive, so that the image of a task that | |
17411 | is a subcomponent of a composite object corresponds to the expression that | |
17412 | designates this task. | |
17413 | ||
17414 | If a task is created by an allocator, its image depends on the context. If the | |
17415 | allocator is part of an object declaration, the rules described above are used | |
17416 | to construct its image, and this image is not affected by subsequent | |
17417 | assignments. If the allocator appears within an expression, the image | |
17418 | includes only the name of the task type. | |
17419 | ||
17420 | If the configuration pragma Discard_Names is present, or if the restriction | |
17421 | No_Implicit_Heap_Allocation is in effect, the image reduces to | |
17422 | the numeric suffix, that is to say the hexadecimal representation of the | |
17423 | virtual address of the control block of the task. | |
17424 | ||
17425 | ||
17426 | @itemize * | |
17427 | ||
17428 | @item | |
17429 | “The value of @code{Current_Task} when in a protected entry | |
17430 | or interrupt handler. See C.7.1(17).” | |
17431 | @end itemize | |
17432 | ||
17433 | Protected entries or interrupt handlers can be executed by any | |
17434 | convenient thread, so the value of @code{Current_Task} is undefined. | |
17435 | ||
17436 | ||
17437 | @itemize * | |
17438 | ||
17439 | @item | |
17440 | “Granularity of locking for Task_Attributes. See C.7.2(16).” | |
17441 | @end itemize | |
17442 | ||
17443 | No locking is needed if the formal type Attribute has the size and | |
17444 | alignment of either Integer or System.Address and the bit representation | |
17445 | of Initial_Value is all zeroes. Otherwise, locking is performed. | |
17446 | ||
17447 | ||
17448 | @itemize * | |
17449 | ||
17450 | @item | |
17451 | “The declarations of @code{Any_Priority} and | |
17452 | @code{Priority}. See D.1(11).” | |
17453 | @end itemize | |
17454 | ||
17455 | See declarations in file @code{system.ads}. | |
17456 | ||
17457 | ||
17458 | @itemize * | |
17459 | ||
17460 | @item | |
17461 | “Implementation-defined execution resources. See D.1(15).” | |
17462 | @end itemize | |
17463 | ||
17464 | There are no implementation-defined execution resources. | |
17465 | ||
17466 | ||
17467 | @itemize * | |
17468 | ||
17469 | @item | |
17470 | “Whether, on a multiprocessor, a task that is waiting for | |
17471 | access to a protected object keeps its processor busy. See D.2.1(3).” | |
17472 | @end itemize | |
17473 | ||
17474 | On a multi-processor, a task that is waiting for access to a protected | |
17475 | object does not keep its processor busy. | |
17476 | ||
17477 | ||
17478 | @itemize * | |
17479 | ||
17480 | @item | |
17481 | “The affect of implementation defined execution resources | |
17482 | on task dispatching. See D.2.1(9).” | |
17483 | @end itemize | |
17484 | ||
17485 | Tasks map to threads in the threads package used by GNAT. Where possible | |
17486 | and appropriate, these threads correspond to native threads of the | |
17487 | underlying operating system. | |
17488 | ||
17489 | ||
17490 | @itemize * | |
17491 | ||
17492 | @item | |
17493 | “Implementation-defined task dispatching policies. See D.2.2(3).” | |
17494 | @end itemize | |
17495 | ||
17496 | There are no implementation-defined task dispatching policies. | |
17497 | ||
17498 | ||
17499 | @itemize * | |
17500 | ||
17501 | @item | |
17502 | “The value of Default_Quantum in Dispatching.Round_Robin. See D.2.5(4).” | |
17503 | @end itemize | |
17504 | ||
17505 | The value is 10 milliseconds. | |
17506 | ||
17507 | ||
17508 | @itemize * | |
17509 | ||
17510 | @item | |
17511 | “Implementation-defined `policy_identifiers' allowed | |
17512 | in a pragma @code{Locking_Policy}. See D.3(4).” | |
17513 | @end itemize | |
17514 | ||
17515 | The two implementation defined policies permitted in GNAT are | |
17516 | @code{Inheritance_Locking} and @code{Concurrent_Readers_Locking}. On | |
17517 | targets that support the @code{Inheritance_Locking} policy, locking is | |
17518 | implemented by inheritance, i.e., the task owning the lock operates | |
17519 | at a priority equal to the highest priority of any task currently | |
17520 | requesting the lock. On targets that support the | |
17521 | @code{Concurrent_Readers_Locking} policy, locking is implemented with a | |
17522 | read/write lock allowing multiple protected object functions to enter | |
17523 | concurrently. | |
17524 | ||
17525 | ||
17526 | @itemize * | |
17527 | ||
17528 | @item | |
17529 | “Default ceiling priorities. See D.3(10).” | |
17530 | @end itemize | |
17531 | ||
17532 | The ceiling priority of protected objects of the type | |
17533 | @code{System.Interrupt_Priority'Last} as described in the Ada | |
17534 | Reference Manual D.3(10), | |
17535 | ||
17536 | ||
17537 | @itemize * | |
17538 | ||
17539 | @item | |
17540 | “The ceiling of any protected object used internally by | |
17541 | the implementation. See D.3(16).” | |
17542 | @end itemize | |
17543 | ||
17544 | The ceiling priority of internal protected objects is | |
17545 | @code{System.Priority'Last}. | |
17546 | ||
17547 | ||
17548 | @itemize * | |
17549 | ||
17550 | @item | |
17551 | “Implementation-defined queuing policies. See D.4(1).” | |
17552 | @end itemize | |
17553 | ||
17554 | There are no implementation-defined queuing policies. | |
17555 | ||
17556 | ||
17557 | @itemize * | |
17558 | ||
17559 | @item | |
17560 | “Implementation-defined admission policies. See D.4.1(1).” | |
17561 | @end itemize | |
17562 | ||
17563 | There are no implementation-defined admission policies. | |
17564 | ||
17565 | ||
17566 | @itemize * | |
17567 | ||
17568 | @item | |
17569 | “Any operations that implicitly require heap storage | |
17570 | allocation. See D.7(8).” | |
17571 | @end itemize | |
17572 | ||
17573 | The only operation that implicitly requires heap storage allocation is | |
17574 | task creation. | |
17575 | ||
17576 | ||
17577 | @itemize * | |
17578 | ||
17579 | @item | |
17580 | “When restriction No_Dynamic_CPU_Assignment applies to a partition, the | |
17581 | processor on which a task with a CPU value of a Not_A_Specific_CPU will | |
17582 | execute. See D.7(10).” | |
17583 | @end itemize | |
17584 | ||
17585 | Unknown. | |
17586 | ||
17587 | ||
17588 | @itemize * | |
17589 | ||
17590 | @item | |
17591 | “When restriction No_Task_Termination applies to a partition, what happens | |
17592 | when a task terminates. See D.7(15.1).” | |
17593 | @end itemize | |
17594 | ||
17595 | Execution is erroneous in that case. | |
17596 | ||
17597 | ||
17598 | @itemize * | |
17599 | ||
17600 | @item | |
17601 | “The behavior when restriction Max_Storage_At_Blocking is violated. | |
17602 | See D.7(17).” | |
17603 | @end itemize | |
17604 | ||
17605 | Execution is erroneous in that case. | |
17606 | ||
17607 | ||
17608 | @itemize * | |
17609 | ||
17610 | @item | |
17611 | “The behavior when restriction Max_Asynchronous_Select_Nesting is violated. | |
17612 | See D.7(18).” | |
17613 | @end itemize | |
17614 | ||
17615 | Execution is erroneous in that case. | |
17616 | ||
17617 | ||
17618 | @itemize * | |
17619 | ||
17620 | @item | |
17621 | “The behavior when restriction Max_Tasks is violated. See D.7(19).” | |
17622 | @end itemize | |
17623 | ||
17624 | Execution is erroneous in that case. | |
17625 | ||
17626 | ||
17627 | @itemize * | |
17628 | ||
17629 | @item | |
17630 | “Whether the use of pragma Restrictions results in a reduction in program | |
17631 | code or data size or execution time. See D.7(20).” | |
f571a201 | 17632 | @end itemize |
64d5610f ML |
17633 | |
17634 | Yes it can, but the precise circumstances and properties of such reductions | |
17635 | are difficult to characterize. | |
17636 | ||
f571a201 RD |
17637 | |
17638 | @itemize * | |
17639 | ||
64d5610f ML |
17640 | @item |
17641 | “The value of Barrier_Limit’Last in Synchronous_Barriers. See D.10.1(4).” | |
17642 | @end itemize | |
17643 | ||
17644 | Synchronous_Barriers.Barrier_Limit’Last is Integer’Last . | |
17645 | ||
17646 | ||
17647 | @itemize * | |
17648 | ||
17649 | @item | |
17650 | “When an aborted task that is waiting on a Synchronous_Barrier is aborted. | |
17651 | See D.10.1(13).” | |
17652 | @end itemize | |
17653 | ||
17654 | Difficult to characterize. | |
17655 | ||
17656 | ||
17657 | @itemize * | |
17658 | ||
17659 | @item | |
17660 | “The value of Min_Handler_Ceiling in Execution_Time.Group_Budgets. | |
17661 | See D.14.2(7).” | |
17662 | @end itemize | |
17663 | ||
17664 | See source file @code{a-etgrbu.ads}. | |
17665 | ||
17666 | ||
17667 | @itemize * | |
17668 | ||
17669 | @item | |
17670 | “The value of CPU_Range’Last in System.Multiprocessors. See D.16(4).” | |
17671 | @end itemize | |
17672 | ||
17673 | See source file @code{s-multip.ads}. | |
17674 | ||
17675 | ||
17676 | @itemize * | |
17677 | ||
17678 | @item | |
17679 | “The processor on which the environment task executes in the absence | |
17680 | of a value for the aspect CPU. See D.16(13).” | |
17681 | @end itemize | |
17682 | ||
17683 | Unknown. | |
17684 | ||
17685 | ||
17686 | @itemize * | |
17687 | ||
17688 | @item | |
17689 | “The means for creating and executing distributed | |
17690 | programs. See E(5).” | |
17691 | @end itemize | |
17692 | ||
17693 | The GLADE package provides a utility GNATDIST for creating and executing | |
17694 | distributed programs. See the GLADE reference manual for further details. | |
17695 | ||
17696 | ||
17697 | @itemize * | |
17698 | ||
17699 | @item | |
17700 | “Any events that can result in a partition becoming | |
17701 | inaccessible. See E.1(7).” | |
17702 | @end itemize | |
17703 | ||
17704 | See the GLADE reference manual for full details on such events. | |
17705 | ||
17706 | ||
17707 | @itemize * | |
17708 | ||
17709 | @item | |
17710 | “The scheduling policies, treatment of priorities, and management of | |
17711 | shared resources between partitions in certain cases. See E.1(11).” | |
17712 | @end itemize | |
17713 | ||
17714 | See the GLADE reference manual for full details on these aspects of | |
17715 | multi-partition execution. | |
17716 | ||
17717 | ||
17718 | @itemize * | |
17719 | ||
17720 | @item | |
17721 | “Whether the execution of the remote subprogram is | |
17722 | immediately aborted as a result of cancellation. See E.4(13).” | |
17723 | @end itemize | |
17724 | ||
17725 | See the GLADE reference manual for details on the effect of abort in | |
17726 | a distributed application. | |
17727 | ||
17728 | ||
17729 | @itemize * | |
17730 | ||
17731 | @item | |
17732 | “The range of type System.RPC.Partition_Id. See E.5(14).” | |
17733 | @end itemize | |
17734 | ||
17735 | System.RPC.Partition_ID’Last is Integer’Last. See source file @code{s-rpc.ads}. | |
17736 | ||
17737 | ||
17738 | @itemize * | |
17739 | ||
17740 | @item | |
17741 | “Implementation-defined interfaces in the PCS. See E.5(26).” | |
17742 | @end itemize | |
17743 | ||
17744 | See the GLADE reference manual for a full description of all | |
17745 | implementation defined interfaces. | |
17746 | ||
17747 | ||
17748 | @itemize * | |
17749 | ||
17750 | @item | |
17751 | “The values of named numbers in the package | |
17752 | @code{Decimal}. See F.2(7).” | |
17753 | @end itemize | |
17754 | ||
17755 | ||
17756 | @multitable {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxx} | |
17757 | @headitem | |
17758 | ||
17759 | Named Number | |
17760 | ||
17761 | @tab | |
17762 | ||
17763 | Value | |
17764 | ||
17765 | @item | |
17766 | ||
17767 | `Max_Scale' | |
17768 | ||
17769 | @tab | |
17770 | ||
17771 | +18 | |
17772 | ||
17773 | @item | |
17774 | ||
17775 | `Min_Scale' | |
17776 | ||
17777 | @tab | |
17778 | ||
17779 | -18 | |
17780 | ||
17781 | @item | |
17782 | ||
17783 | `Min_Delta' | |
17784 | ||
17785 | @tab | |
17786 | ||
17787 | 1.0E-18 | |
17788 | ||
17789 | @item | |
17790 | ||
17791 | `Max_Delta' | |
17792 | ||
17793 | @tab | |
17794 | ||
17795 | 1.0E+18 | |
17796 | ||
17797 | @item | |
17798 | ||
17799 | `Max_Decimal_Digits' | |
17800 | ||
17801 | @tab | |
17802 | ||
17803 | 18 | |
17804 | ||
17805 | @end multitable | |
17806 | ||
17807 | ||
17808 | ||
17809 | @itemize * | |
17810 | ||
17811 | @item | |
17812 | “The value of @code{Max_Picture_Length} in the package | |
17813 | @code{Text_IO.Editing}. See F.3.3(16).” | |
17814 | ||
17815 | 64 | |
17816 | ||
17817 | @item | |
17818 | “The value of @code{Max_Picture_Length} in the package | |
17819 | @code{Wide_Text_IO.Editing}. See F.3.4(5).” | |
17820 | ||
17821 | 64 | |
17822 | ||
17823 | @item | |
17824 | “The accuracy actually achieved by the complex elementary | |
17825 | functions and by other complex arithmetic operations. See G.1(1).” | |
17826 | @end itemize | |
17827 | ||
17828 | Standard library functions are used for the complex arithmetic | |
17829 | operations. Only fast math mode is currently supported. | |
17830 | ||
17831 | ||
17832 | @itemize * | |
17833 | ||
17834 | @item | |
17835 | “The sign of a zero result (or a component thereof) from | |
17836 | any operator or function in @code{Numerics.Generic_Complex_Types}, when | |
17837 | @code{Real'Signed_Zeros} is True. See G.1.1(53).” | |
17838 | @end itemize | |
17839 | ||
17840 | The signs of zero values are as recommended by the relevant | |
17841 | implementation advice. | |
17842 | ||
17843 | ||
17844 | @itemize * | |
17845 | ||
17846 | @item | |
17847 | “The sign of a zero result (or a component thereof) from | |
17848 | any operator or function in | |
17849 | @code{Numerics.Generic_Complex_Elementary_Functions}, when | |
17850 | @code{Real'Signed_Zeros} is @code{True}. See G.1.2(45).” | |
17851 | @end itemize | |
17852 | ||
17853 | The signs of zero values are as recommended by the relevant | |
17854 | implementation advice. | |
17855 | ||
17856 | ||
17857 | @itemize * | |
17858 | ||
17859 | @item | |
17860 | “Whether the strict mode or the relaxed mode is the | |
17861 | default. See G.2(2).” | |
17862 | @end itemize | |
17863 | ||
17864 | The strict mode is the default. There is no separate relaxed mode. GNAT | |
17865 | provides a highly efficient implementation of strict mode. | |
17866 | ||
17867 | ||
17868 | @itemize * | |
17869 | ||
17870 | @item | |
17871 | “The result interval in certain cases of fixed-to-float | |
17872 | conversion. See G.2.1(10).” | |
17873 | @end itemize | |
17874 | ||
17875 | For cases where the result interval is implementation dependent, the | |
17876 | accuracy is that provided by performing all operations in 64-bit IEEE | |
17877 | floating-point format. | |
17878 | ||
17879 | ||
17880 | @itemize * | |
17881 | ||
17882 | @item | |
17883 | “The result of a floating point arithmetic operation in | |
17884 | overflow situations, when the @code{Machine_Overflows} attribute of the | |
17885 | result type is @code{False}. See G.2.1(13).” | |
17886 | @end itemize | |
17887 | ||
17888 | Infinite and NaN values are produced as dictated by the IEEE | |
17889 | floating-point standard. | |
17890 | Note that on machines that are not fully compliant with the IEEE | |
17891 | floating-point standard, such as Alpha, the `-mieee' compiler flag | |
17892 | must be used for achieving IEEE conforming behavior (although at the cost | |
17893 | of a significant performance penalty), so infinite and NaN values are | |
17894 | properly generated. | |
17895 | ||
17896 | ||
17897 | @itemize * | |
17898 | ||
17899 | @item | |
17900 | “The result interval for division (or exponentiation by a | |
17901 | negative exponent), when the floating point hardware implements division | |
17902 | as multiplication by a reciprocal. See G.2.1(16).” | |
17903 | @end itemize | |
17904 | ||
17905 | Not relevant, division is IEEE exact. | |
17906 | ||
17907 | ||
17908 | @itemize * | |
17909 | ||
17910 | @item | |
17911 | “The definition of close result set, which determines the accuracy of | |
17912 | certain fixed point multiplications and divisions. See G.2.3(5).” | |
17913 | @end itemize | |
17914 | ||
17915 | Operations in the close result set are performed using IEEE long format | |
17916 | floating-point arithmetic. The input operands are converted to | |
17917 | floating-point, the operation is done in floating-point, and the result | |
17918 | is converted to the target type. | |
17919 | ||
17920 | ||
17921 | @itemize * | |
17922 | ||
17923 | @item | |
17924 | “Conditions on a `universal_real' operand of a fixed | |
17925 | point multiplication or division for which the result shall be in the | |
17926 | perfect result set. See G.2.3(22).” | |
17927 | @end itemize | |
17928 | ||
17929 | The result is only defined to be in the perfect result set if the result | |
17930 | can be computed by a single scaling operation involving a scale factor | |
17931 | representable in 64 bits. | |
17932 | ||
17933 | ||
17934 | @itemize * | |
17935 | ||
17936 | @item | |
17937 | “The result of a fixed point arithmetic operation in | |
17938 | overflow situations, when the @code{Machine_Overflows} attribute of the | |
17939 | result type is @code{False}. See G.2.3(27).” | |
17940 | @end itemize | |
17941 | ||
17942 | Not relevant, @code{Machine_Overflows} is @code{True} for fixed-point | |
17943 | types. | |
17944 | ||
17945 | ||
17946 | @itemize * | |
17947 | ||
17948 | @item | |
17949 | “The result of an elementary function reference in | |
17950 | overflow situations, when the @code{Machine_Overflows} attribute of the | |
17951 | result type is @code{False}. See G.2.4(4).” | |
17952 | @end itemize | |
17953 | ||
17954 | IEEE infinite and Nan values are produced as appropriate. | |
17955 | ||
17956 | ||
17957 | @itemize * | |
17958 | ||
17959 | @item | |
17960 | “The value of the angle threshold, within which certain | |
17961 | elementary functions, complex arithmetic operations, and complex | |
17962 | elementary functions yield results conforming to a maximum relative | |
17963 | error bound. See G.2.4(10).” | |
17964 | @end itemize | |
17965 | ||
17966 | Information on this subject is not yet available. | |
17967 | ||
17968 | ||
17969 | @itemize * | |
17970 | ||
17971 | @item | |
17972 | “The accuracy of certain elementary functions for | |
17973 | parameters beyond the angle threshold. See G.2.4(10).” | |
17974 | @end itemize | |
17975 | ||
17976 | Information on this subject is not yet available. | |
17977 | ||
17978 | ||
17979 | @itemize * | |
17980 | ||
17981 | @item | |
17982 | “The result of a complex arithmetic operation or complex | |
17983 | elementary function reference in overflow situations, when the | |
17984 | @code{Machine_Overflows} attribute of the corresponding real type is | |
17985 | @code{False}. See G.2.6(5).” | |
17986 | @end itemize | |
17987 | ||
17988 | IEEE infinite and Nan values are produced as appropriate. | |
17989 | ||
17990 | ||
17991 | @itemize * | |
17992 | ||
17993 | @item | |
17994 | “The accuracy of certain complex arithmetic operations and | |
17995 | certain complex elementary functions for parameters (or components | |
17996 | thereof) beyond the angle threshold. See G.2.6(8).” | |
17997 | @end itemize | |
17998 | ||
17999 | Information on those subjects is not yet available. | |
18000 | ||
18001 | ||
18002 | @itemize * | |
18003 | ||
18004 | @item | |
18005 | “The accuracy requirements for the subprograms Solve, Inverse, | |
18006 | Determinant, Eigenvalues and Eigensystem for type Real_Matrix. | |
18007 | See G.3.1(81).” | |
18008 | @end itemize | |
18009 | ||
18010 | Information on those subjects is not yet available. | |
18011 | ||
18012 | ||
18013 | @itemize * | |
18014 | ||
18015 | @item | |
18016 | “The accuracy requirements for the subprograms Solve, Inverse, | |
18017 | Determinant, Eigenvalues and Eigensystem for type Complex_Matrix. | |
18018 | See G.3.2(149).” | |
18019 | @end itemize | |
18020 | ||
18021 | Information on those subjects is not yet available. | |
18022 | ||
18023 | ||
18024 | @itemize * | |
18025 | ||
18026 | @item | |
18027 | “The consequences of violating No_Hidden_Indirect_Globals. See H.4(23.9).” | |
18028 | @end itemize | |
18029 | ||
18030 | Execution is erroneous in that case. | |
18031 | ||
18032 | @node Intrinsic Subprograms,Representation Clauses and Pragmas,Implementation Defined Characteristics,Top | |
04d6c745 | 18033 | @anchor{gnat_rm/intrinsic_subprograms doc}@anchor{266}@anchor{gnat_rm/intrinsic_subprograms id1}@anchor{267}@anchor{gnat_rm/intrinsic_subprograms intrinsic-subprograms}@anchor{c} |
64d5610f ML |
18034 | @chapter Intrinsic Subprograms |
18035 | ||
18036 | ||
18037 | @geindex Intrinsic Subprograms | |
18038 | ||
18039 | GNAT allows a user application program to write the declaration: | |
18040 | ||
18041 | @example | |
18042 | pragma Import (Intrinsic, name); | |
18043 | @end example | |
18044 | ||
18045 | providing that the name corresponds to one of the implemented intrinsic | |
18046 | subprograms in GNAT, and that the parameter profile of the referenced | |
18047 | subprogram meets the requirements. This chapter describes the set of | |
18048 | implemented intrinsic subprograms, and the requirements on parameter profiles. | |
18049 | Note that no body is supplied; as with other uses of pragma Import, the | |
18050 | body is supplied elsewhere (in this case by the compiler itself). Note | |
18051 | that any use of this feature is potentially non-portable, since the | |
18052 | Ada standard does not require Ada compilers to implement this feature. | |
18053 | ||
18054 | @menu | |
18055 | * Intrinsic Operators:: | |
18056 | * Compilation_ISO_Date:: | |
18057 | * Compilation_Date:: | |
18058 | * Compilation_Time:: | |
18059 | * Enclosing_Entity:: | |
18060 | * Exception_Information:: | |
18061 | * Exception_Message:: | |
18062 | * Exception_Name:: | |
18063 | * File:: | |
18064 | * Line:: | |
18065 | * Shifts and Rotates:: | |
18066 | * Source_Location:: | |
18067 | ||
18068 | @end menu | |
18069 | ||
18070 | @node Intrinsic Operators,Compilation_ISO_Date,,Intrinsic Subprograms | |
04d6c745 | 18071 | @anchor{gnat_rm/intrinsic_subprograms id2}@anchor{268}@anchor{gnat_rm/intrinsic_subprograms intrinsic-operators}@anchor{269} |
64d5610f ML |
18072 | @section Intrinsic Operators |
18073 | ||
18074 | ||
18075 | @geindex Intrinsic operator | |
18076 | ||
18077 | All the predefined numeric operators in package Standard | |
18078 | in @code{pragma Import (Intrinsic,..)} | |
18079 | declarations. In the binary operator case, the operands must have the same | |
18080 | size. The operand or operands must also be appropriate for | |
18081 | the operator. For example, for addition, the operands must | |
18082 | both be floating-point or both be fixed-point, and the | |
18083 | right operand for @code{"**"} must have a root type of | |
18084 | @code{Standard.Integer'Base}. | |
18085 | You can use an intrinsic operator declaration as in the following example: | |
18086 | ||
18087 | @example | |
18088 | type Int1 is new Integer; | |
18089 | type Int2 is new Integer; | |
18090 | ||
18091 | function "+" (X1 : Int1; X2 : Int2) return Int1; | |
18092 | function "+" (X1 : Int1; X2 : Int2) return Int2; | |
18093 | pragma Import (Intrinsic, "+"); | |
18094 | @end example | |
18095 | ||
18096 | This declaration would permit ‘mixed mode’ arithmetic on items | |
18097 | of the differing types @code{Int1} and @code{Int2}. | |
18098 | It is also possible to specify such operators for private types, if the | |
18099 | full views are appropriate arithmetic types. | |
18100 | ||
18101 | @node Compilation_ISO_Date,Compilation_Date,Intrinsic Operators,Intrinsic Subprograms | |
04d6c745 | 18102 | @anchor{gnat_rm/intrinsic_subprograms compilation-iso-date}@anchor{26a}@anchor{gnat_rm/intrinsic_subprograms id3}@anchor{26b} |
64d5610f ML |
18103 | @section Compilation_ISO_Date |
18104 | ||
18105 | ||
18106 | @geindex Compilation_ISO_Date | |
18107 | ||
18108 | This intrinsic subprogram is used in the implementation of the | |
18109 | library package @code{GNAT.Source_Info}. The only useful use of the | |
18110 | intrinsic import in this case is the one in this unit, so an | |
18111 | application program should simply call the function | |
18112 | @code{GNAT.Source_Info.Compilation_ISO_Date} to obtain the date of | |
18113 | the current compilation (in local time format YYYY-MM-DD). | |
18114 | ||
18115 | @node Compilation_Date,Compilation_Time,Compilation_ISO_Date,Intrinsic Subprograms | |
04d6c745 | 18116 | @anchor{gnat_rm/intrinsic_subprograms compilation-date}@anchor{26c}@anchor{gnat_rm/intrinsic_subprograms id4}@anchor{26d} |
64d5610f ML |
18117 | @section Compilation_Date |
18118 | ||
18119 | ||
18120 | @geindex Compilation_Date | |
18121 | ||
18122 | Same as Compilation_ISO_Date, except the string is in the form | |
18123 | MMM DD YYYY. | |
18124 | ||
18125 | @node Compilation_Time,Enclosing_Entity,Compilation_Date,Intrinsic Subprograms | |
04d6c745 | 18126 | @anchor{gnat_rm/intrinsic_subprograms compilation-time}@anchor{26e}@anchor{gnat_rm/intrinsic_subprograms id5}@anchor{26f} |
64d5610f ML |
18127 | @section Compilation_Time |
18128 | ||
18129 | ||
18130 | @geindex Compilation_Time | |
18131 | ||
18132 | This intrinsic subprogram is used in the implementation of the | |
18133 | library package @code{GNAT.Source_Info}. The only useful use of the | |
18134 | intrinsic import in this case is the one in this unit, so an | |
18135 | application program should simply call the function | |
18136 | @code{GNAT.Source_Info.Compilation_Time} to obtain the time of | |
18137 | the current compilation (in local time format HH:MM:SS). | |
18138 | ||
18139 | @node Enclosing_Entity,Exception_Information,Compilation_Time,Intrinsic Subprograms | |
04d6c745 | 18140 | @anchor{gnat_rm/intrinsic_subprograms enclosing-entity}@anchor{270}@anchor{gnat_rm/intrinsic_subprograms id6}@anchor{271} |
64d5610f ML |
18141 | @section Enclosing_Entity |
18142 | ||
18143 | ||
18144 | @geindex Enclosing_Entity | |
18145 | ||
18146 | This intrinsic subprogram is used in the implementation of the | |
18147 | library package @code{GNAT.Source_Info}. The only useful use of the | |
18148 | intrinsic import in this case is the one in this unit, so an | |
18149 | application program should simply call the function | |
18150 | @code{GNAT.Source_Info.Enclosing_Entity} to obtain the name of | |
18151 | the current subprogram, package, task, entry, or protected subprogram. | |
18152 | ||
18153 | @node Exception_Information,Exception_Message,Enclosing_Entity,Intrinsic Subprograms | |
04d6c745 | 18154 | @anchor{gnat_rm/intrinsic_subprograms exception-information}@anchor{272}@anchor{gnat_rm/intrinsic_subprograms id7}@anchor{273} |
64d5610f ML |
18155 | @section Exception_Information |
18156 | ||
18157 | ||
18158 | @geindex Exception_Information' | |
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_Information} to obtain | |
18165 | the exception information associated with the current exception. | |
18166 | ||
18167 | @node Exception_Message,Exception_Name,Exception_Information,Intrinsic Subprograms | |
04d6c745 | 18168 | @anchor{gnat_rm/intrinsic_subprograms exception-message}@anchor{274}@anchor{gnat_rm/intrinsic_subprograms id8}@anchor{275} |
64d5610f ML |
18169 | @section Exception_Message |
18170 | ||
18171 | ||
18172 | @geindex Exception_Message | |
18173 | ||
18174 | This intrinsic subprogram is used in the implementation of the | |
18175 | library package @code{GNAT.Current_Exception}. The only useful | |
18176 | use of the intrinsic import in this case is the one in this unit, | |
18177 | so an application program should simply call the function | |
18178 | @code{GNAT.Current_Exception.Exception_Message} to obtain | |
18179 | the message associated with the current exception. | |
18180 | ||
18181 | @node Exception_Name,File,Exception_Message,Intrinsic Subprograms | |
04d6c745 | 18182 | @anchor{gnat_rm/intrinsic_subprograms exception-name}@anchor{276}@anchor{gnat_rm/intrinsic_subprograms id9}@anchor{277} |
64d5610f ML |
18183 | @section Exception_Name |
18184 | ||
18185 | ||
18186 | @geindex Exception_Name | |
18187 | ||
18188 | This intrinsic subprogram is used in the implementation of the | |
18189 | library package @code{GNAT.Current_Exception}. The only useful | |
18190 | use of the intrinsic import in this case is the one in this unit, | |
18191 | so an application program should simply call the function | |
18192 | @code{GNAT.Current_Exception.Exception_Name} to obtain | |
18193 | the name of the current exception. | |
18194 | ||
18195 | @node File,Line,Exception_Name,Intrinsic Subprograms | |
04d6c745 | 18196 | @anchor{gnat_rm/intrinsic_subprograms file}@anchor{278}@anchor{gnat_rm/intrinsic_subprograms id10}@anchor{279} |
64d5610f ML |
18197 | @section File |
18198 | ||
18199 | ||
18200 | @geindex File | |
18201 | ||
18202 | This intrinsic subprogram is used in the implementation of the | |
18203 | library package @code{GNAT.Source_Info}. The only useful use of the | |
18204 | intrinsic import in this case is the one in this unit, so an | |
18205 | application program should simply call the function | |
18206 | @code{GNAT.Source_Info.File} to obtain the name of the current | |
18207 | file. | |
18208 | ||
18209 | @node Line,Shifts and Rotates,File,Intrinsic Subprograms | |
04d6c745 | 18210 | @anchor{gnat_rm/intrinsic_subprograms id11}@anchor{27a}@anchor{gnat_rm/intrinsic_subprograms line}@anchor{27b} |
64d5610f ML |
18211 | @section Line |
18212 | ||
18213 | ||
18214 | @geindex Line | |
18215 | ||
18216 | This intrinsic subprogram is used in the implementation of the | |
18217 | library package @code{GNAT.Source_Info}. The only useful use of the | |
18218 | intrinsic import in this case is the one in this unit, so an | |
18219 | application program should simply call the function | |
18220 | @code{GNAT.Source_Info.Line} to obtain the number of the current | |
18221 | source line. | |
18222 | ||
18223 | @node Shifts and Rotates,Source_Location,Line,Intrinsic Subprograms | |
04d6c745 | 18224 | @anchor{gnat_rm/intrinsic_subprograms id12}@anchor{27c}@anchor{gnat_rm/intrinsic_subprograms shifts-and-rotates}@anchor{27d} |
64d5610f ML |
18225 | @section Shifts and Rotates |
18226 | ||
18227 | ||
18228 | @geindex Shift_Left | |
18229 | ||
18230 | @geindex Shift_Right | |
18231 | ||
18232 | @geindex Shift_Right_Arithmetic | |
18233 | ||
18234 | @geindex Rotate_Left | |
18235 | ||
18236 | @geindex Rotate_Right | |
18237 | ||
18238 | In standard Ada, the shift and rotate functions are available only | |
18239 | for the predefined modular types in package @code{Interfaces}. However, in | |
18240 | GNAT it is possible to define these functions for any integer | |
18241 | type (signed or modular), as in this example: | |
18242 | ||
18243 | @example | |
18244 | function Shift_Left | |
18245 | (Value : T; | |
18246 | Amount : Natural) return T | |
18247 | with Import, Convention => Intrinsic; | |
18248 | @end example | |
18249 | ||
18250 | The function name must be one of | |
18251 | Shift_Left, Shift_Right, Shift_Right_Arithmetic, Rotate_Left, or | |
18252 | Rotate_Right. T must be an integer type. T’Size must be | |
18253 | 8, 16, 32 or 64 bits; if T is modular, the modulus | |
18254 | must be 2**8, 2**16, 2**32 or 2**64. | |
18255 | The result type must be the same as the type of @code{Value}. | |
18256 | The shift amount must be Natural. | |
18257 | The formal parameter names can be anything. | |
18258 | ||
18259 | A more convenient way of providing these shift operators is to use the | |
18260 | Provide_Shift_Operators pragma, which provides the function declarations and | |
18261 | corresponding pragma Import’s for all five shift functions. For signed types | |
18262 | the semantics of these operators is to interpret the bitwise result of the | |
18263 | corresponding operator for modular type. In particular, shifting a negative | |
18264 | number may change its sign bit to positive. | |
18265 | ||
18266 | @node Source_Location,,Shifts and Rotates,Intrinsic Subprograms | |
04d6c745 | 18267 | @anchor{gnat_rm/intrinsic_subprograms id13}@anchor{27e}@anchor{gnat_rm/intrinsic_subprograms source-location}@anchor{27f} |
64d5610f ML |
18268 | @section Source_Location |
18269 | ||
18270 | ||
18271 | @geindex Source_Location | |
18272 | ||
18273 | This intrinsic subprogram is used in the implementation of the | |
18274 | library routine @code{GNAT.Source_Info}. The only useful use of the | |
18275 | intrinsic import in this case is the one in this unit, so an | |
18276 | application program should simply call the function | |
18277 | @code{GNAT.Source_Info.Source_Location} to obtain the current | |
18278 | source file location. | |
18279 | ||
18280 | @node Representation Clauses and Pragmas,Standard Library Routines,Intrinsic Subprograms,Top | |
04d6c745 | 18281 | @anchor{gnat_rm/representation_clauses_and_pragmas doc}@anchor{280}@anchor{gnat_rm/representation_clauses_and_pragmas id1}@anchor{281}@anchor{gnat_rm/representation_clauses_and_pragmas representation-clauses-and-pragmas}@anchor{d} |
64d5610f ML |
18282 | @chapter Representation Clauses and Pragmas |
18283 | ||
18284 | ||
18285 | @geindex Representation Clauses | |
18286 | ||
18287 | @geindex Representation Clause | |
18288 | ||
18289 | @geindex Representation Pragma | |
18290 | ||
18291 | @geindex Pragma | |
18292 | @geindex representation | |
18293 | ||
18294 | This section describes the representation clauses accepted by GNAT, and | |
18295 | their effect on the representation of corresponding data objects. | |
18296 | ||
18297 | GNAT fully implements Annex C (Systems Programming). This means that all | |
18298 | the implementation advice sections in chapter 13 are fully implemented. | |
18299 | However, these sections only require a minimal level of support for | |
18300 | representation clauses. GNAT provides much more extensive capabilities, | |
18301 | and this section describes the additional capabilities provided. | |
18302 | ||
18303 | @menu | |
18304 | * Alignment Clauses:: | |
18305 | * Size Clauses:: | |
18306 | * Storage_Size Clauses:: | |
18307 | * Size of Variant Record Objects:: | |
18308 | * Biased Representation:: | |
18309 | * Value_Size and Object_Size Clauses:: | |
18310 | * Component_Size Clauses:: | |
18311 | * Bit_Order Clauses:: | |
18312 | * Effect of Bit_Order on Byte Ordering:: | |
18313 | * Pragma Pack for Arrays:: | |
18314 | * Pragma Pack for Records:: | |
18315 | * Record Representation Clauses:: | |
18316 | * Handling of Records with Holes:: | |
18317 | * Enumeration Clauses:: | |
18318 | * Address Clauses:: | |
18319 | * Use of Address Clauses for Memory-Mapped I/O:: | |
18320 | * Effect of Convention on Representation:: | |
18321 | * Conventions and Anonymous Access Types:: | |
18322 | * Determining the Representations chosen by GNAT:: | |
18323 | ||
18324 | @end menu | |
18325 | ||
18326 | @node Alignment Clauses,Size Clauses,,Representation Clauses and Pragmas | |
04d6c745 | 18327 | @anchor{gnat_rm/representation_clauses_and_pragmas alignment-clauses}@anchor{282}@anchor{gnat_rm/representation_clauses_and_pragmas id2}@anchor{283} |
64d5610f ML |
18328 | @section Alignment Clauses |
18329 | ||
18330 | ||
18331 | @geindex Alignment Clause | |
18332 | ||
18333 | GNAT requires that all alignment clauses specify 0 or a power of 2, and | |
18334 | all default alignments are always a power of 2. Specifying 0 is the | |
18335 | same as specifying 1. | |
18336 | ||
18337 | The default alignment values are as follows: | |
18338 | ||
18339 | ||
18340 | @itemize * | |
18341 | ||
18342 | @item | |
18343 | `Elementary Types'. | |
18344 | ||
18345 | For elementary types, the alignment is the minimum of the actual size of | |
18346 | objects of the type divided by @code{Storage_Unit}, | |
18347 | and the maximum alignment supported by the target. | |
18348 | (This maximum alignment is given by the GNAT-specific attribute | |
04d6c745 | 18349 | @code{Standard'Maximum_Alignment}; see @ref{193,,Attribute Maximum_Alignment}.) |
64d5610f ML |
18350 | |
18351 | @geindex Maximum_Alignment attribute | |
18352 | ||
18353 | For example, for type @code{Long_Float}, the object size is 8 bytes, and the | |
18354 | default alignment will be 8 on any target that supports alignments | |
18355 | this large, but on some targets, the maximum alignment may be smaller | |
18356 | than 8, in which case objects of type @code{Long_Float} will be maximally | |
18357 | aligned. | |
18358 | ||
18359 | @item | |
18360 | `Arrays'. | |
18361 | ||
18362 | For arrays, the alignment is equal to the alignment of the component type | |
18363 | for the normal case where no packing or component size is given. If the | |
18364 | array is packed, and the packing is effective (see separate section on | |
18365 | packed arrays), then the alignment will be either 4, 2, or 1 for long packed | |
18366 | arrays or arrays whose length is not known at compile time, depending on | |
18367 | whether the component size is divisible by 4, 2, or is odd. For short packed | |
18368 | arrays, which are handled internally as modular types, the alignment | |
18369 | will be as described for elementary types, e.g. a packed array of length | |
18370 | 31 bits will have an object size of four bytes, and an alignment of 4. | |
18371 | ||
18372 | @item | |
18373 | `Records'. | |
18374 | ||
18375 | For the normal unpacked case, the alignment of a record is equal to | |
18376 | the maximum alignment of any of its components. For tagged records, this | |
18377 | includes the implicit access type used for the tag. If a pragma @code{Pack} | |
18378 | is used and all components are packable (see separate section on pragma | |
18379 | @code{Pack}), then the resulting alignment is 1, unless the layout of the | |
18380 | record makes it profitable to increase it. | |
18381 | ||
18382 | A special case is when: | |
18383 | ||
18384 | ||
18385 | @itemize * | |
18386 | ||
18387 | @item | |
18388 | the size of the record is given explicitly, or a | |
18389 | full record representation clause is given, and | |
18390 | ||
18391 | @item | |
18392 | the size of the record is 2, 4, or 8 bytes. | |
18393 | @end itemize | |
18394 | ||
18395 | In this case, an alignment is chosen to match the | |
18396 | size of the record. For example, if we have: | |
18397 | ||
18398 | @example | |
18399 | type Small is record | |
18400 | A, B : Character; | |
18401 | end record; | |
18402 | for Small'Size use 16; | |
18403 | @end example | |
18404 | ||
18405 | then the default alignment of the record type @code{Small} is 2, not 1. This | |
18406 | leads to more efficient code when the record is treated as a unit, and also | |
18407 | allows the type to specified as @code{Atomic} on architectures requiring | |
18408 | strict alignment. | |
18409 | @end itemize | |
18410 | ||
18411 | An alignment clause may specify a larger alignment than the default value | |
18412 | up to some maximum value dependent on the target (obtainable by using the | |
18413 | attribute reference @code{Standard'Maximum_Alignment}). It may also specify | |
18414 | a smaller alignment than the default value for enumeration, integer and | |
18415 | fixed point types, as well as for record types, for example | |
18416 | ||
18417 | @example | |
18418 | type V is record | |
18419 | A : Integer; | |
18420 | end record; | |
18421 | ||
18422 | for V'alignment use 1; | |
18423 | @end example | |
18424 | ||
18425 | @geindex Alignment | |
18426 | @geindex default | |
18427 | ||
18428 | The default alignment for the type @code{V} is 4, as a result of the | |
18429 | Integer field in the record, but it is permissible, as shown, to | |
18430 | override the default alignment of the record with a smaller value. | |
18431 | ||
18432 | @geindex Alignment | |
18433 | @geindex subtypes | |
18434 | ||
18435 | Note that according to the Ada standard, an alignment clause applies only | |
18436 | to the first named subtype. If additional subtypes are declared, then the | |
18437 | compiler is allowed to choose any alignment it likes, and there is no way | |
18438 | to control this choice. Consider: | |
18439 | ||
18440 | @example | |
18441 | type R is range 1 .. 10_000; | |
18442 | for R'Alignment use 1; | |
18443 | subtype RS is R range 1 .. 1000; | |
18444 | @end example | |
18445 | ||
18446 | The alignment clause specifies an alignment of 1 for the first named subtype | |
18447 | @code{R} but this does not necessarily apply to @code{RS}. When writing | |
18448 | portable Ada code, you should avoid writing code that explicitly or | |
18449 | implicitly relies on the alignment of such subtypes. | |
18450 | ||
18451 | For the GNAT compiler, if an explicit alignment clause is given, this | |
18452 | value is also used for any subsequent subtypes. So for GNAT, in the | |
18453 | above example, you can count on the alignment of @code{RS} being 1. But this | |
18454 | assumption is non-portable, and other compilers may choose different | |
18455 | alignments for the subtype @code{RS}. | |
18456 | ||
18457 | @node Size Clauses,Storage_Size Clauses,Alignment Clauses,Representation Clauses and Pragmas | |
04d6c745 | 18458 | @anchor{gnat_rm/representation_clauses_and_pragmas id3}@anchor{284}@anchor{gnat_rm/representation_clauses_and_pragmas size-clauses}@anchor{285} |
64d5610f ML |
18459 | @section Size Clauses |
18460 | ||
18461 | ||
18462 | @geindex Size Clause | |
18463 | ||
18464 | The default size for a type @code{T} is obtainable through the | |
18465 | language-defined attribute @code{T'Size} and also through the | |
18466 | equivalent GNAT-defined attribute @code{T'Value_Size}. | |
18467 | For objects of type @code{T}, GNAT will generally increase the type size | |
18468 | so that the object size (obtainable through the GNAT-defined attribute | |
18469 | @code{T'Object_Size}) | |
18470 | is a multiple of @code{T'Alignment * Storage_Unit}. | |
18471 | ||
18472 | For example: | |
18473 | ||
18474 | @example | |
18475 | type Smallint is range 1 .. 6; | |
18476 | ||
18477 | type Rec is record | |
18478 | Y1 : integer; | |
18479 | Y2 : boolean; | |
18480 | end record; | |
18481 | @end example | |
18482 | ||
18483 | In this example, @code{Smallint'Size} = @code{Smallint'Value_Size} = 3, | |
18484 | as specified by the RM rules, | |
18485 | but objects of this type will have a size of 8 | |
18486 | (@code{Smallint'Object_Size} = 8), | |
18487 | since objects by default occupy an integral number | |
18488 | of storage units. On some targets, notably older | |
18489 | versions of the Digital Alpha, the size of stand | |
18490 | alone objects of this type may be 32, reflecting | |
18491 | the inability of the hardware to do byte load/stores. | |
18492 | ||
18493 | Similarly, the size of type @code{Rec} is 40 bits | |
18494 | (@code{Rec'Size} = @code{Rec'Value_Size} = 40), but | |
18495 | the alignment is 4, so objects of this type will have | |
18496 | their size increased to 64 bits so that it is a multiple | |
18497 | of the alignment (in bits). This decision is | |
18498 | in accordance with the specific Implementation Advice in RM 13.3(43): | |
18499 | ||
18500 | @quotation | |
18501 | ||
18502 | “A @code{Size} clause should be supported for an object if the specified | |
18503 | @code{Size} is at least as large as its subtype’s @code{Size}, and corresponds | |
18504 | to a size in storage elements that is a multiple of the object’s | |
18505 | @code{Alignment} (if the @code{Alignment} is nonzero).” | |
18506 | @end quotation | |
18507 | ||
18508 | An explicit size clause may be used to override the default size by | |
18509 | increasing it. For example, if we have: | |
18510 | ||
18511 | @example | |
18512 | type My_Boolean is new Boolean; | |
18513 | for My_Boolean'Size use 32; | |
18514 | @end example | |
18515 | ||
18516 | then values of this type will always be 32-bit long. In the case of discrete | |
18517 | types, the size can be increased up to 64 bits on 32-bit targets and 128 bits | |
18518 | on 64-bit targets, with the effect that the entire specified field is used to | |
18519 | hold the value, sign- or zero-extended as appropriate. If more than 64 bits | |
18520 | or 128 bits resp. is specified, then padding space is allocated after the | |
18521 | value, and a warning is issued that there are unused bits. | |
18522 | ||
18523 | Similarly the size of records and arrays may be increased, and the effect | |
18524 | is to add padding bits after the value. This also causes a warning message | |
18525 | to be generated. | |
18526 | ||
18527 | The largest Size value permitted in GNAT is 2**31-1. Since this is a | |
18528 | Size in bits, this corresponds to an object of size 256 megabytes (minus | |
18529 | one). This limitation is true on all targets. The reason for this | |
18530 | limitation is that it improves the quality of the code in many cases | |
18531 | if it is known that a Size value can be accommodated in an object of | |
18532 | type Integer. | |
18533 | ||
18534 | @node Storage_Size Clauses,Size of Variant Record Objects,Size Clauses,Representation Clauses and Pragmas | |
04d6c745 | 18535 | @anchor{gnat_rm/representation_clauses_and_pragmas id4}@anchor{286}@anchor{gnat_rm/representation_clauses_and_pragmas storage-size-clauses}@anchor{287} |
64d5610f ML |
18536 | @section Storage_Size Clauses |
18537 | ||
18538 | ||
18539 | @geindex Storage_Size Clause | |
18540 | ||
18541 | For tasks, the @code{Storage_Size} clause specifies the amount of space | |
18542 | to be allocated for the task stack. This cannot be extended, and if the | |
18543 | stack is exhausted, then @code{Storage_Error} will be raised (if stack | |
18544 | checking is enabled). Use a @code{Storage_Size} attribute definition clause, | |
18545 | or a @code{Storage_Size} pragma in the task definition to set the | |
18546 | appropriate required size. A useful technique is to include in every | |
18547 | task definition a pragma of the form: | |
18548 | ||
18549 | @example | |
18550 | pragma Storage_Size (Default_Stack_Size); | |
18551 | @end example | |
18552 | ||
18553 | Then @code{Default_Stack_Size} can be defined in a global package, and | |
18554 | modified as required. Any tasks requiring stack sizes different from the | |
18555 | default can have an appropriate alternative reference in the pragma. | |
18556 | ||
18557 | You can also use the `-d' binder switch to modify the default stack | |
18558 | size. | |
18559 | ||
18560 | For access types, the @code{Storage_Size} clause specifies the maximum | |
18561 | space available for allocation of objects of the type. If this space is | |
18562 | exceeded then @code{Storage_Error} will be raised by an allocation attempt. | |
18563 | In the case where the access type is declared local to a subprogram, the | |
18564 | use of a @code{Storage_Size} clause triggers automatic use of a special | |
18565 | predefined storage pool (@code{System.Pool_Size}) that ensures that all | |
18566 | space for the pool is automatically reclaimed on exit from the scope in | |
18567 | which the type is declared. | |
18568 | ||
18569 | A special case recognized by the compiler is the specification of a | |
18570 | @code{Storage_Size} of zero for an access type. This means that no | |
18571 | items can be allocated from the pool, and this is recognized at compile | |
18572 | time, and all the overhead normally associated with maintaining a fixed | |
18573 | size storage pool is eliminated. Consider the following example: | |
18574 | ||
18575 | @example | |
18576 | procedure p is | |
18577 | type R is array (Natural) of Character; | |
18578 | type P is access all R; | |
18579 | for P'Storage_Size use 0; | |
18580 | -- Above access type intended only for interfacing purposes | |
18581 | ||
18582 | y : P; | |
18583 | ||
18584 | procedure g (m : P); | |
18585 | pragma Import (C, g); | |
18586 | ||
18587 | -- ... | |
18588 | ||
18589 | begin | |
18590 | -- ... | |
18591 | y := new R; | |
18592 | end; | |
18593 | @end example | |
18594 | ||
18595 | As indicated in this example, these dummy storage pools are often useful in | |
18596 | connection with interfacing where no object will ever be allocated. If you | |
18597 | compile the above example, you get the warning: | |
18598 | ||
18599 | @example | |
18600 | p.adb:16:09: warning: allocation from empty storage pool | |
18601 | p.adb:16:09: warning: Storage_Error will be raised at run time | |
18602 | @end example | |
18603 | ||
18604 | Of course in practice, there will not be any explicit allocators in the | |
18605 | case of such an access declaration. | |
18606 | ||
18607 | @node Size of Variant Record Objects,Biased Representation,Storage_Size Clauses,Representation Clauses and Pragmas | |
04d6c745 | 18608 | @anchor{gnat_rm/representation_clauses_and_pragmas id5}@anchor{288}@anchor{gnat_rm/representation_clauses_and_pragmas size-of-variant-record-objects}@anchor{289} |
64d5610f ML |
18609 | @section Size of Variant Record Objects |
18610 | ||
18611 | ||
18612 | @geindex Size | |
18613 | @geindex variant record objects | |
18614 | ||
18615 | @geindex Variant record objects | |
18616 | @geindex size | |
18617 | ||
18618 | In the case of variant record objects, there is a question whether Size gives | |
18619 | information about a particular variant, or the maximum size required | |
18620 | for any variant. Consider the following program | |
18621 | ||
18622 | @example | |
18623 | with Text_IO; use Text_IO; | |
18624 | procedure q is | |
18625 | type R1 (A : Boolean := False) is record | |
18626 | case A is | |
18627 | when True => X : Character; | |
18628 | when False => null; | |
18629 | end case; | |
18630 | end record; | |
18631 | ||
18632 | V1 : R1 (False); | |
18633 | V2 : R1; | |
18634 | ||
18635 | begin | |
18636 | Put_Line (Integer'Image (V1'Size)); | |
18637 | Put_Line (Integer'Image (V2'Size)); | |
18638 | end q; | |
18639 | @end example | |
18640 | ||
18641 | Here we are dealing with a variant record, where the True variant | |
18642 | requires 16 bits, and the False variant requires 8 bits. | |
18643 | In the above example, both V1 and V2 contain the False variant, | |
18644 | which is only 8 bits long. However, the result of running the | |
18645 | program is: | |
18646 | ||
18647 | @example | |
18648 | 8 | |
18649 | 16 | |
18650 | @end example | |
18651 | ||
18652 | The reason for the difference here is that the discriminant value of | |
18653 | V1 is fixed, and will always be False. It is not possible to assign | |
18654 | a True variant value to V1, therefore 8 bits is sufficient. On the | |
18655 | other hand, in the case of V2, the initial discriminant value is | |
18656 | False (from the default), but it is possible to assign a True | |
18657 | variant value to V2, therefore 16 bits must be allocated for V2 | |
18658 | in the general case, even fewer bits may be needed at any particular | |
18659 | point during the program execution. | |
18660 | ||
18661 | As can be seen from the output of this program, the @code{'Size} | |
18662 | attribute applied to such an object in GNAT gives the actual allocated | |
18663 | size of the variable, which is the largest size of any of the variants. | |
18664 | The Ada Reference Manual is not completely clear on what choice should | |
18665 | be made here, but the GNAT behavior seems most consistent with the | |
18666 | language in the RM. | |
18667 | ||
18668 | In some cases, it may be desirable to obtain the size of the current | |
18669 | variant, rather than the size of the largest variant. This can be | |
18670 | achieved in GNAT by making use of the fact that in the case of a | |
18671 | subprogram parameter, GNAT does indeed return the size of the current | |
18672 | variant (because a subprogram has no way of knowing how much space | |
18673 | is actually allocated for the actual). | |
18674 | ||
18675 | Consider the following modified version of the above program: | |
18676 | ||
18677 | @example | |
18678 | with Text_IO; use Text_IO; | |
18679 | procedure q is | |
18680 | type R1 (A : Boolean := False) is record | |
18681 | case A is | |
18682 | when True => X : Character; | |
18683 | when False => null; | |
18684 | end case; | |
18685 | end record; | |
18686 | ||
18687 | V2 : R1; | |
18688 | ||
18689 | function Size (V : R1) return Integer is | |
18690 | begin | |
18691 | return V'Size; | |
18692 | end Size; | |
18693 | ||
18694 | begin | |
18695 | Put_Line (Integer'Image (V2'Size)); | |
18696 | Put_Line (Integer'Image (Size (V2))); | |
18697 | V2 := (True, 'x'); | |
18698 | Put_Line (Integer'Image (V2'Size)); | |
18699 | Put_Line (Integer'Image (Size (V2))); | |
18700 | end q; | |
18701 | @end example | |
18702 | ||
18703 | The output from this program is | |
18704 | ||
18705 | @example | |
18706 | 16 | |
18707 | 8 | |
18708 | 16 | |
18709 | 16 | |
18710 | @end example | |
18711 | ||
18712 | Here we see that while the @code{'Size} attribute always returns | |
18713 | the maximum size, regardless of the current variant value, the | |
18714 | @code{Size} function does indeed return the size of the current | |
18715 | variant value. | |
18716 | ||
18717 | @node Biased Representation,Value_Size and Object_Size Clauses,Size of Variant Record Objects,Representation Clauses and Pragmas | |
04d6c745 | 18718 | @anchor{gnat_rm/representation_clauses_and_pragmas biased-representation}@anchor{28a}@anchor{gnat_rm/representation_clauses_and_pragmas id6}@anchor{28b} |
64d5610f ML |
18719 | @section Biased Representation |
18720 | ||
18721 | ||
18722 | @geindex Size for biased representation | |
18723 | ||
18724 | @geindex Biased representation | |
18725 | ||
18726 | In the case of scalars with a range starting at other than zero, it is | |
18727 | possible in some cases to specify a size smaller than the default minimum | |
18728 | value, and in such cases, GNAT uses an unsigned biased representation, | |
18729 | in which zero is used to represent the lower bound, and successive values | |
18730 | represent successive values of the type. | |
18731 | ||
18732 | For example, suppose we have the declaration: | |
18733 | ||
18734 | @example | |
18735 | type Small is range -7 .. -4; | |
18736 | for Small'Size use 2; | |
18737 | @end example | |
18738 | ||
18739 | Although the default size of type @code{Small} is 4, the @code{Size} | |
18740 | clause is accepted by GNAT and results in the following representation | |
18741 | scheme: | |
18742 | ||
18743 | @example | |
18744 | -7 is represented as 2#00# | |
18745 | -6 is represented as 2#01# | |
18746 | -5 is represented as 2#10# | |
18747 | -4 is represented as 2#11# | |
18748 | @end example | |
18749 | ||
18750 | Biased representation is only used if the specified @code{Size} clause | |
18751 | cannot be accepted in any other manner. These reduced sizes that force | |
18752 | biased representation can be used for all discrete types except for | |
18753 | enumeration types for which a representation clause is given. | |
18754 | ||
18755 | @node Value_Size and Object_Size Clauses,Component_Size Clauses,Biased Representation,Representation Clauses and Pragmas | |
04d6c745 | 18756 | @anchor{gnat_rm/representation_clauses_and_pragmas id7}@anchor{28c}@anchor{gnat_rm/representation_clauses_and_pragmas value-size-and-object-size-clauses}@anchor{28d} |
64d5610f ML |
18757 | @section Value_Size and Object_Size Clauses |
18758 | ||
18759 | ||
18760 | @geindex Value_Size | |
18761 | ||
18762 | @geindex Object_Size | |
18763 | ||
18764 | @geindex Size | |
18765 | @geindex of objects | |
18766 | ||
18767 | In Ada 95 and Ada 2005, @code{T'Size} for a type @code{T} is the minimum | |
18768 | number of bits required to hold values of type @code{T}. | |
18769 | Although this interpretation was allowed in Ada 83, it was not required, | |
18770 | and this requirement in practice can cause some significant difficulties. | |
18771 | For example, in most Ada 83 compilers, @code{Natural'Size} was 32. | |
18772 | However, in Ada 95 and Ada 2005, | |
18773 | @code{Natural'Size} is | |
18774 | typically 31. This means that code may change in behavior when moving | |
18775 | from Ada 83 to Ada 95 or Ada 2005. For example, consider: | |
18776 | ||
18777 | @example | |
18778 | type Rec is record | |
18779 | A : Natural; | |
18780 | B : Natural; | |
18781 | end record; | |
18782 | ||
18783 | for Rec use record | |
18784 | A at 0 range 0 .. Natural'Size - 1; | |
18785 | B at 0 range Natural'Size .. 2 * Natural'Size - 1; | |
18786 | end record; | |
18787 | @end example | |
18788 | ||
18789 | In the above code, since the typical size of @code{Natural} objects | |
18790 | is 32 bits and @code{Natural'Size} is 31, the above code can cause | |
18791 | unexpected inefficient packing in Ada 95 and Ada 2005, and in general | |
18792 | there are cases where the fact that the object size can exceed the | |
18793 | size of the type causes surprises. | |
18794 | ||
18795 | To help get around this problem GNAT provides two implementation | |
18796 | defined attributes, @code{Value_Size} and @code{Object_Size}. When | |
18797 | applied to a type, these attributes yield the size of the type | |
18798 | (corresponding to the RM defined size attribute), and the size of | |
18799 | objects of the type respectively. | |
18800 | ||
18801 | The @code{Object_Size} is used for determining the default size of | |
18802 | objects and components. This size value can be referred to using the | |
18803 | @code{Object_Size} attribute. The phrase ‘is used’ here means that it is | |
18804 | the basis of the determination of the size. The backend is free to | |
18805 | pad this up if necessary for efficiency, e.g., an 8-bit stand-alone | |
18806 | character might be stored in 32 bits on a machine with no efficient | |
18807 | byte access instructions such as the Alpha. | |
18808 | ||
18809 | The default rules for the value of @code{Object_Size} for | |
18810 | discrete types are as follows: | |
18811 | ||
18812 | ||
18813 | @itemize * | |
18814 | ||
18815 | @item | |
18816 | The @code{Object_Size} for base subtypes reflect the natural hardware | |
18817 | size in bits (run the compiler with `-gnatS' to find those values | |
18818 | for numeric types). Enumeration types and fixed-point base subtypes have | |
18819 | 8, 16, 32, or 64 bits for this size, depending on the range of values | |
18820 | to be stored. | |
18821 | ||
18822 | @item | |
18823 | The @code{Object_Size} of a subtype is the same as the | |
18824 | @code{Object_Size} of | |
18825 | the type from which it is obtained. | |
18826 | ||
18827 | @item | |
18828 | The @code{Object_Size} of a derived base type is copied from the parent | |
18829 | base type, and the @code{Object_Size} of a derived first subtype is copied | |
18830 | from the parent first subtype. | |
18831 | @end itemize | |
18832 | ||
18833 | The @code{Value_Size} attribute | |
18834 | is the (minimum) number of bits required to store a value | |
18835 | of the type. | |
18836 | This value is used to determine how tightly to pack | |
18837 | records or arrays with components of this type, and also affects | |
18838 | the semantics of unchecked conversion (unchecked conversions where | |
18839 | the @code{Value_Size} values differ generate a warning, and are potentially | |
18840 | target dependent). | |
18841 | ||
18842 | The default rules for the value of @code{Value_Size} are as follows: | |
18843 | ||
18844 | ||
18845 | @itemize * | |
18846 | ||
18847 | @item | |
18848 | The @code{Value_Size} for a base subtype is the minimum number of bits | |
18849 | required to store all values of the type (including the sign bit | |
18850 | only if negative values are possible). | |
18851 | ||
18852 | @item | |
18853 | If a subtype statically matches the first subtype of a given type, then it has | |
18854 | by default the same @code{Value_Size} as the first subtype. (This is a | |
18855 | consequence of RM 13.1(14): “if two subtypes statically match, | |
18856 | then their subtype-specific aspects are the same”.) | |
18857 | ||
18858 | @item | |
18859 | All other subtypes have a @code{Value_Size} corresponding to the minimum | |
18860 | number of bits required to store all values of the subtype. For | |
18861 | dynamic bounds, it is assumed that the value can range down or up | |
18862 | to the corresponding bound of the ancestor | |
18863 | @end itemize | |
18864 | ||
18865 | The RM defined attribute @code{Size} corresponds to the | |
18866 | @code{Value_Size} attribute. | |
18867 | ||
18868 | The @code{Size} attribute may be defined for a first-named subtype. This sets | |
18869 | the @code{Value_Size} of | |
18870 | the first-named subtype to the given value, and the | |
18871 | @code{Object_Size} of this first-named subtype to the given value padded up | |
18872 | to an appropriate boundary. It is a consequence of the default rules | |
18873 | above that this @code{Object_Size} will apply to all further subtypes. On the | |
18874 | other hand, @code{Value_Size} is affected only for the first subtype, any | |
18875 | dynamic subtypes obtained from it directly, and any statically matching | |
18876 | subtypes. The @code{Value_Size} of any other static subtypes is not affected. | |
18877 | ||
18878 | @code{Value_Size} and | |
18879 | @code{Object_Size} may be explicitly set for any subtype using | |
18880 | an attribute definition clause. Note that the use of these attributes | |
18881 | can cause the RM 13.1(14) rule to be violated. If two access types | |
18882 | reference aliased objects whose subtypes have differing @code{Object_Size} | |
18883 | values as a result of explicit attribute definition clauses, then it | |
18884 | is illegal to convert from one access subtype to the other. For a more | |
18885 | complete description of this additional legality rule, see the | |
18886 | description of the @code{Object_Size} attribute. | |
18887 | ||
18888 | To get a feel for the difference, consider the following examples (note | |
18889 | that in each case the base is @code{Short_Short_Integer} with a size of 8): | |
18890 | ||
18891 | ||
18892 | @multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxx} | |
18893 | @headitem | |
18894 | ||
18895 | Type or subtype declaration | |
18896 | ||
18897 | @tab | |
18898 | ||
18899 | Object_Size | |
18900 | ||
18901 | @tab | |
18902 | ||
18903 | Value_Size | |
18904 | ||
18905 | @item | |
18906 | ||
18907 | @code{type x1 is range 0 .. 5;} | |
18908 | ||
18909 | @tab | |
18910 | ||
18911 | 8 | |
18912 | ||
18913 | @tab | |
18914 | ||
18915 | 3 | |
18916 | ||
18917 | @item | |
18918 | ||
18919 | @code{type x2 is range 0 .. 5;} | |
18920 | @code{for x2'size use 12;} | |
18921 | ||
18922 | @tab | |
18923 | ||
18924 | 16 | |
18925 | ||
18926 | @tab | |
18927 | ||
18928 | 12 | |
18929 | ||
18930 | @item | |
18931 | ||
18932 | @code{subtype x3 is x2 range 0 .. 3;} | |
18933 | ||
18934 | @tab | |
18935 | ||
18936 | 16 | |
18937 | ||
18938 | @tab | |
18939 | ||
18940 | 2 | |
18941 | ||
18942 | @item | |
18943 | ||
18944 | @code{subtype x4 is x2'base range 0 .. 10;} | |
18945 | ||
18946 | @tab | |
18947 | ||
18948 | 8 | |
18949 | ||
18950 | @tab | |
18951 | ||
18952 | 4 | |
18953 | ||
18954 | @item | |
18955 | ||
18956 | @code{dynamic : x2'Base range -64 .. +63;} | |
18957 | ||
18958 | @tab | |
18959 | ||
18960 | @tab | |
18961 | ||
18962 | @item | |
18963 | ||
18964 | @code{subtype x5 is x2 range 0 .. dynamic;} | |
18965 | ||
18966 | @tab | |
18967 | ||
18968 | 16 | |
18969 | ||
18970 | @tab | |
18971 | ||
18972 | 3* | |
18973 | ||
18974 | @item | |
18975 | ||
18976 | @code{subtype x6 is x2'base range 0 .. dynamic;} | |
18977 | ||
18978 | @tab | |
18979 | ||
18980 | 8 | |
18981 | ||
18982 | @tab | |
18983 | ||
18984 | 7* | |
18985 | ||
18986 | @end multitable | |
18987 | ||
18988 | ||
18989 | Note: the entries marked ‘*’ are not actually specified by the Ada | |
18990 | Reference Manual, which has nothing to say about size in the dynamic | |
18991 | case. What GNAT does is to allocate sufficient bits to accommodate any | |
18992 | possible dynamic values for the bounds at run-time. | |
18993 | ||
18994 | So far, so good, but GNAT has to obey the RM rules, so the question is | |
18995 | under what conditions must the RM @code{Size} be used. | |
18996 | The following is a list | |
18997 | of the occasions on which the RM @code{Size} must be used: | |
18998 | ||
18999 | ||
19000 | @itemize * | |
19001 | ||
19002 | @item | |
19003 | Component size for packed arrays or records | |
19004 | ||
19005 | @item | |
19006 | Value of the attribute @code{Size} for a type | |
19007 | ||
19008 | @item | |
19009 | Warning about sizes not matching for unchecked conversion | |
19010 | @end itemize | |
19011 | ||
19012 | For record types, the @code{Object_Size} is always a multiple of the | |
19013 | alignment of the type (this is true for all types). In some cases the | |
19014 | @code{Value_Size} can be smaller. Consider: | |
19015 | ||
19016 | @example | |
19017 | type R is record | |
19018 | X : Integer; | |
19019 | Y : Character; | |
19020 | end record; | |
19021 | @end example | |
19022 | ||
19023 | On a typical 32-bit architecture, the X component will occupy four bytes | |
19024 | and the Y component will occupy one byte, for a total of 5 bytes. As a | |
19025 | result @code{R'Value_Size} will be 40 (bits) since this is the minimum size | |
19026 | required to store a value of this type. For example, it is permissible | |
19027 | to have a component of type R in an array whose component size is | |
19028 | specified to be 40 bits. | |
19029 | ||
19030 | However, @code{R'Object_Size} will be 64 (bits). The difference is due to | |
19031 | the alignment requirement for objects of the record type. The X | |
19032 | component will require four-byte alignment because that is what type | |
19033 | Integer requires, whereas the Y component, a Character, will only | |
19034 | require 1-byte alignment. Since the alignment required for X is the | |
19035 | greatest of all the components’ alignments, that is the alignment | |
19036 | required for the enclosing record type, i.e., 4 bytes or 32 bits. As | |
19037 | indicated above, the actual object size must be rounded up so that it is | |
19038 | a multiple of the alignment value. Therefore, 40 bits rounded up to the | |
19039 | next multiple of 32 yields 64 bits. | |
19040 | ||
19041 | For all other types, the @code{Object_Size} | |
19042 | and @code{Value_Size} are the same (and equivalent to the RM attribute @code{Size}). | |
19043 | Only @code{Size} may be specified for such types. | |
19044 | ||
19045 | Note that @code{Value_Size} can be used to force biased representation | |
19046 | for a particular subtype. Consider this example: | |
19047 | ||
19048 | @example | |
19049 | type R is (A, B, C, D, E, F); | |
19050 | subtype RAB is R range A .. B; | |
19051 | subtype REF is R range E .. F; | |
19052 | @end example | |
19053 | ||
19054 | By default, @code{RAB} | |
19055 | has a size of 1 (sufficient to accommodate the representation | |
19056 | of @code{A} and @code{B}, 0 and 1), and @code{REF} | |
19057 | has a size of 3 (sufficient to accommodate the representation | |
19058 | of @code{E} and @code{F}, 4 and 5). But if we add the | |
19059 | following @code{Value_Size} attribute definition clause: | |
19060 | ||
19061 | @example | |
19062 | for REF'Value_Size use 1; | |
19063 | @end example | |
19064 | ||
19065 | then biased representation is forced for @code{REF}, | |
19066 | and 0 will represent @code{E} and 1 will represent @code{F}. | |
19067 | A warning is issued when a @code{Value_Size} attribute | |
19068 | definition clause forces biased representation. This | |
19069 | warning can be turned off using @code{-gnatw.B}. | |
19070 | ||
19071 | @node Component_Size Clauses,Bit_Order Clauses,Value_Size and Object_Size Clauses,Representation Clauses and Pragmas | |
04d6c745 | 19072 | @anchor{gnat_rm/representation_clauses_and_pragmas component-size-clauses}@anchor{28e}@anchor{gnat_rm/representation_clauses_and_pragmas id8}@anchor{28f} |
64d5610f ML |
19073 | @section Component_Size Clauses |
19074 | ||
19075 | ||
19076 | @geindex Component_Size Clause | |
19077 | ||
19078 | Normally, the value specified in a component size clause must be consistent | |
19079 | with the subtype of the array component with regard to size and alignment. | |
19080 | In other words, the value specified must be at least equal to the size | |
19081 | of this subtype, and must be a multiple of the alignment value. | |
19082 | ||
19083 | In addition, component size clauses are allowed which cause the array | |
19084 | to be packed, by specifying a smaller value. A first case is for | |
19085 | component size values in the range 1 through 63 on 32-bit targets, | |
19086 | and 1 through 127 on 64-bit targets. The value specified may not | |
19087 | be smaller than the Size of the subtype. GNAT will accurately | |
19088 | honor all packing requests in this range. For example, if we have: | |
19089 | ||
19090 | @example | |
19091 | type r is array (1 .. 8) of Natural; | |
19092 | for r'Component_Size use 31; | |
19093 | @end example | |
19094 | ||
19095 | then the resulting array has a length of 31 bytes (248 bits = 8 * 31). | |
19096 | Of course access to the components of such an array is considerably | |
19097 | less efficient than if the natural component size of 32 is used. | |
19098 | A second case is when the subtype of the component is a record type | |
19099 | padded because of its default alignment. For example, if we have: | |
19100 | ||
19101 | @example | |
19102 | type r is record | |
19103 | i : Integer; | |
19104 | j : Integer; | |
19105 | b : Boolean; | |
19106 | end record; | |
19107 | ||
19108 | type a is array (1 .. 8) of r; | |
19109 | for a'Component_Size use 72; | |
19110 | @end example | |
19111 | ||
19112 | then the resulting array has a length of 72 bytes, instead of 96 bytes | |
19113 | if the alignment of the record (4) was obeyed. | |
19114 | ||
19115 | Note that there is no point in giving both a component size clause | |
19116 | and a pragma Pack for the same array type. if such duplicate | |
19117 | clauses are given, the pragma Pack will be ignored. | |
19118 | ||
19119 | @node Bit_Order Clauses,Effect of Bit_Order on Byte Ordering,Component_Size Clauses,Representation Clauses and Pragmas | |
04d6c745 | 19120 | @anchor{gnat_rm/representation_clauses_and_pragmas bit-order-clauses}@anchor{290}@anchor{gnat_rm/representation_clauses_and_pragmas id9}@anchor{291} |
64d5610f ML |
19121 | @section Bit_Order Clauses |
19122 | ||
19123 | ||
19124 | @geindex Bit_Order Clause | |
19125 | ||
19126 | @geindex bit ordering | |
19127 | ||
19128 | @geindex ordering | |
19129 | @geindex of bits | |
19130 | ||
19131 | For record subtypes, GNAT permits the specification of the @code{Bit_Order} | |
19132 | attribute. The specification may either correspond to the default bit | |
19133 | order for the target, in which case the specification has no effect and | |
19134 | places no additional restrictions, or it may be for the non-standard | |
19135 | setting (that is the opposite of the default). | |
19136 | ||
19137 | In the case where the non-standard value is specified, the effect is | |
19138 | to renumber bits within each byte, but the ordering of bytes is not | |
19139 | affected. There are certain | |
19140 | restrictions placed on component clauses as follows: | |
19141 | ||
19142 | ||
19143 | @itemize * | |
19144 | ||
19145 | @item | |
19146 | Components fitting within a single storage unit. | |
19147 | ||
19148 | These are unrestricted, and the effect is merely to renumber bits. For | |
19149 | example if we are on a little-endian machine with @code{Low_Order_First} | |
19150 | being the default, then the following two declarations have exactly | |
19151 | the same effect: | |
19152 | ||
19153 | @example | |
19154 | type R1 is record | |
19155 | A : Boolean; | |
19156 | B : Integer range 1 .. 120; | |
19157 | end record; | |
19158 | ||
19159 | for R1 use record | |
19160 | A at 0 range 0 .. 0; | |
19161 | B at 0 range 1 .. 7; | |
19162 | end record; | |
19163 | ||
19164 | type R2 is record | |
19165 | A : Boolean; | |
19166 | B : Integer range 1 .. 120; | |
19167 | end record; | |
19168 | ||
19169 | for R2'Bit_Order use High_Order_First; | |
19170 | ||
19171 | for R2 use record | |
19172 | A at 0 range 7 .. 7; | |
19173 | B at 0 range 0 .. 6; | |
19174 | end record; | |
19175 | @end example | |
19176 | ||
19177 | The useful application here is to write the second declaration with the | |
19178 | @code{Bit_Order} attribute definition clause, and know that it will be treated | |
19179 | the same, regardless of whether the target is little-endian or big-endian. | |
19180 | ||
19181 | @item | |
19182 | Components occupying an integral number of bytes. | |
19183 | ||
19184 | These are components that exactly fit in two or more bytes. Such component | |
19185 | declarations are allowed, but have no effect, since it is important to realize | |
19186 | that the @code{Bit_Order} specification does not affect the ordering of bytes. | |
19187 | In particular, the following attempt at getting an endian-independent integer | |
19188 | does not work: | |
19189 | ||
19190 | @example | |
19191 | type R2 is record | |
19192 | A : Integer; | |
19193 | end record; | |
19194 | ||
19195 | for R2'Bit_Order use High_Order_First; | |
19196 | ||
19197 | for R2 use record | |
19198 | A at 0 range 0 .. 31; | |
19199 | end record; | |
19200 | @end example | |
19201 | ||
19202 | This declaration will result in a little-endian integer on a | |
19203 | little-endian machine, and a big-endian integer on a big-endian machine. | |
19204 | If byte flipping is required for interoperability between big- and | |
19205 | little-endian machines, this must be explicitly programmed. This capability | |
19206 | is not provided by @code{Bit_Order}. | |
19207 | ||
19208 | @item | |
19209 | Components that are positioned across byte boundaries. | |
19210 | ||
19211 | but do not occupy an integral number of bytes. Given that bytes are not | |
19212 | reordered, such fields would occupy a non-contiguous sequence of bits | |
19213 | in memory, requiring non-trivial code to reassemble. They are for this | |
19214 | reason not permitted, and any component clause specifying such a layout | |
19215 | will be flagged as illegal by GNAT. | |
19216 | @end itemize | |
19217 | ||
19218 | Since the misconception that Bit_Order automatically deals with all | |
19219 | endian-related incompatibilities is a common one, the specification of | |
19220 | a component field that is an integral number of bytes will always | |
19221 | generate a warning. This warning may be suppressed using @code{pragma Warnings (Off)} | |
19222 | if desired. The following section contains additional | |
19223 | details regarding the issue of byte ordering. | |
19224 | ||
19225 | @node Effect of Bit_Order on Byte Ordering,Pragma Pack for Arrays,Bit_Order Clauses,Representation Clauses and Pragmas | |
04d6c745 | 19226 | @anchor{gnat_rm/representation_clauses_and_pragmas effect-of-bit-order-on-byte-ordering}@anchor{292}@anchor{gnat_rm/representation_clauses_and_pragmas id10}@anchor{293} |
64d5610f ML |
19227 | @section Effect of Bit_Order on Byte Ordering |
19228 | ||
19229 | ||
19230 | @geindex byte ordering | |
19231 | ||
19232 | @geindex ordering | |
19233 | @geindex of bytes | |
19234 | ||
19235 | In this section we will review the effect of the @code{Bit_Order} attribute | |
19236 | definition clause on byte ordering. Briefly, it has no effect at all, but | |
19237 | a detailed example will be helpful. Before giving this | |
19238 | example, let us review the precise | |
19239 | definition of the effect of defining @code{Bit_Order}. The effect of a | |
19240 | non-standard bit order is described in section 13.5.3 of the Ada | |
19241 | Reference Manual: | |
19242 | ||
19243 | @quotation | |
19244 | ||
19245 | “2 A bit ordering is a method of interpreting the meaning of | |
19246 | the storage place attributes.” | |
19247 | @end quotation | |
19248 | ||
19249 | To understand the precise definition of storage place attributes in | |
19250 | this context, we visit section 13.5.1 of the manual: | |
19251 | ||
19252 | @quotation | |
19253 | ||
19254 | “13 A record_representation_clause (without the mod_clause) | |
19255 | specifies the layout. The storage place attributes (see 13.5.2) | |
19256 | are taken from the values of the position, first_bit, and last_bit | |
19257 | expressions after normalizing those values so that first_bit is | |
19258 | less than Storage_Unit.” | |
19259 | @end quotation | |
19260 | ||
19261 | The critical point here is that storage places are taken from | |
19262 | the values after normalization, not before. So the @code{Bit_Order} | |
19263 | interpretation applies to normalized values. The interpretation | |
19264 | is described in the later part of the 13.5.3 paragraph: | |
19265 | ||
19266 | @quotation | |
19267 | ||
19268 | “2 A bit ordering is a method of interpreting the meaning of | |
19269 | the storage place attributes. High_Order_First (known in the | |
19270 | vernacular as ‘big endian’) means that the first bit of a | |
19271 | storage element (bit 0) is the most significant bit (interpreting | |
19272 | the sequence of bits that represent a component as an unsigned | |
19273 | integer value). Low_Order_First (known in the vernacular as | |
19274 | ‘little endian’) means the opposite: the first bit is the | |
19275 | least significant.” | |
19276 | @end quotation | |
19277 | ||
19278 | Note that the numbering is with respect to the bits of a storage | |
19279 | unit. In other words, the specification affects only the numbering | |
19280 | of bits within a single storage unit. | |
19281 | ||
19282 | We can make the effect clearer by giving an example. | |
19283 | ||
19284 | Suppose that we have an external device which presents two bytes, the first | |
19285 | byte presented, which is the first (low addressed byte) of the two byte | |
19286 | record is called Master, and the second byte is called Slave. | |
19287 | ||
19288 | The left most (most significant) bit is called Control for each byte, and | |
19289 | the remaining 7 bits are called V1, V2, … V7, where V7 is the rightmost | |
19290 | (least significant) bit. | |
19291 | ||
19292 | On a big-endian machine, we can write the following representation clause | |
19293 | ||
19294 | @example | |
19295 | type Data is record | |
19296 | Master_Control : Bit; | |
19297 | Master_V1 : Bit; | |
19298 | Master_V2 : Bit; | |
19299 | Master_V3 : Bit; | |
19300 | Master_V4 : Bit; | |
19301 | Master_V5 : Bit; | |
19302 | Master_V6 : Bit; | |
19303 | Master_V7 : Bit; | |
19304 | Slave_Control : Bit; | |
19305 | Slave_V1 : Bit; | |
19306 | Slave_V2 : Bit; | |
19307 | Slave_V3 : Bit; | |
19308 | Slave_V4 : Bit; | |
19309 | Slave_V5 : Bit; | |
19310 | Slave_V6 : Bit; | |
19311 | Slave_V7 : Bit; | |
19312 | end record; | |
19313 | ||
19314 | for Data use record | |
19315 | Master_Control at 0 range 0 .. 0; | |
19316 | Master_V1 at 0 range 1 .. 1; | |
19317 | Master_V2 at 0 range 2 .. 2; | |
19318 | Master_V3 at 0 range 3 .. 3; | |
19319 | Master_V4 at 0 range 4 .. 4; | |
19320 | Master_V5 at 0 range 5 .. 5; | |
19321 | Master_V6 at 0 range 6 .. 6; | |
19322 | Master_V7 at 0 range 7 .. 7; | |
19323 | Slave_Control at 1 range 0 .. 0; | |
19324 | Slave_V1 at 1 range 1 .. 1; | |
19325 | Slave_V2 at 1 range 2 .. 2; | |
19326 | Slave_V3 at 1 range 3 .. 3; | |
19327 | Slave_V4 at 1 range 4 .. 4; | |
19328 | Slave_V5 at 1 range 5 .. 5; | |
19329 | Slave_V6 at 1 range 6 .. 6; | |
19330 | Slave_V7 at 1 range 7 .. 7; | |
19331 | end record; | |
19332 | @end example | |
19333 | ||
19334 | Now if we move this to a little endian machine, then the bit ordering within | |
19335 | the byte is backwards, so we have to rewrite the record rep clause as: | |
19336 | ||
19337 | @example | |
19338 | for Data use record | |
19339 | Master_Control at 0 range 7 .. 7; | |
19340 | Master_V1 at 0 range 6 .. 6; | |
19341 | Master_V2 at 0 range 5 .. 5; | |
19342 | Master_V3 at 0 range 4 .. 4; | |
19343 | Master_V4 at 0 range 3 .. 3; | |
19344 | Master_V5 at 0 range 2 .. 2; | |
19345 | Master_V6 at 0 range 1 .. 1; | |
19346 | Master_V7 at 0 range 0 .. 0; | |
19347 | Slave_Control at 1 range 7 .. 7; | |
19348 | Slave_V1 at 1 range 6 .. 6; | |
19349 | Slave_V2 at 1 range 5 .. 5; | |
19350 | Slave_V3 at 1 range 4 .. 4; | |
19351 | Slave_V4 at 1 range 3 .. 3; | |
19352 | Slave_V5 at 1 range 2 .. 2; | |
19353 | Slave_V6 at 1 range 1 .. 1; | |
19354 | Slave_V7 at 1 range 0 .. 0; | |
19355 | end record; | |
19356 | @end example | |
19357 | ||
19358 | It is a nuisance to have to rewrite the clause, especially if | |
19359 | the code has to be maintained on both machines. However, | |
19360 | this is a case that we can handle with the | |
19361 | @code{Bit_Order} attribute if it is implemented. | |
19362 | Note that the implementation is not required on byte addressed | |
19363 | machines, but it is indeed implemented in GNAT. | |
19364 | This means that we can simply use the | |
19365 | first record clause, together with the declaration | |
19366 | ||
19367 | @example | |
19368 | for Data'Bit_Order use High_Order_First; | |
19369 | @end example | |
19370 | ||
19371 | and the effect is what is desired, namely the layout is exactly the same, | |
19372 | independent of whether the code is compiled on a big-endian or little-endian | |
19373 | machine. | |
19374 | ||
19375 | The important point to understand is that byte ordering is not affected. | |
19376 | A @code{Bit_Order} attribute definition never affects which byte a field | |
19377 | ends up in, only where it ends up in that byte. | |
19378 | To make this clear, let us rewrite the record rep clause of the previous | |
19379 | example as: | |
19380 | ||
19381 | @example | |
19382 | for Data'Bit_Order use High_Order_First; | |
19383 | for Data use record | |
19384 | Master_Control at 0 range 0 .. 0; | |
19385 | Master_V1 at 0 range 1 .. 1; | |
19386 | Master_V2 at 0 range 2 .. 2; | |
19387 | Master_V3 at 0 range 3 .. 3; | |
19388 | Master_V4 at 0 range 4 .. 4; | |
19389 | Master_V5 at 0 range 5 .. 5; | |
19390 | Master_V6 at 0 range 6 .. 6; | |
19391 | Master_V7 at 0 range 7 .. 7; | |
19392 | Slave_Control at 0 range 8 .. 8; | |
19393 | Slave_V1 at 0 range 9 .. 9; | |
19394 | Slave_V2 at 0 range 10 .. 10; | |
19395 | Slave_V3 at 0 range 11 .. 11; | |
19396 | Slave_V4 at 0 range 12 .. 12; | |
19397 | Slave_V5 at 0 range 13 .. 13; | |
19398 | Slave_V6 at 0 range 14 .. 14; | |
19399 | Slave_V7 at 0 range 15 .. 15; | |
19400 | end record; | |
19401 | @end example | |
19402 | ||
19403 | This is exactly equivalent to saying (a repeat of the first example): | |
19404 | ||
19405 | @example | |
19406 | for Data'Bit_Order use High_Order_First; | |
19407 | for Data use record | |
19408 | Master_Control at 0 range 0 .. 0; | |
19409 | Master_V1 at 0 range 1 .. 1; | |
19410 | Master_V2 at 0 range 2 .. 2; | |
19411 | Master_V3 at 0 range 3 .. 3; | |
19412 | Master_V4 at 0 range 4 .. 4; | |
19413 | Master_V5 at 0 range 5 .. 5; | |
19414 | Master_V6 at 0 range 6 .. 6; | |
19415 | Master_V7 at 0 range 7 .. 7; | |
19416 | Slave_Control at 1 range 0 .. 0; | |
19417 | Slave_V1 at 1 range 1 .. 1; | |
19418 | Slave_V2 at 1 range 2 .. 2; | |
19419 | Slave_V3 at 1 range 3 .. 3; | |
19420 | Slave_V4 at 1 range 4 .. 4; | |
19421 | Slave_V5 at 1 range 5 .. 5; | |
19422 | Slave_V6 at 1 range 6 .. 6; | |
19423 | Slave_V7 at 1 range 7 .. 7; | |
19424 | end record; | |
19425 | @end example | |
19426 | ||
19427 | Why are they equivalent? Well take a specific field, the @code{Slave_V2} | |
19428 | field. The storage place attributes are obtained by normalizing the | |
19429 | values given so that the @code{First_Bit} value is less than 8. After | |
19430 | normalizing the values (0,10,10) we get (1,2,2) which is exactly what | |
19431 | we specified in the other case. | |
19432 | ||
19433 | Now one might expect that the @code{Bit_Order} attribute might affect | |
19434 | bit numbering within the entire record component (two bytes in this | |
19435 | case, thus affecting which byte fields end up in), but that is not | |
19436 | the way this feature is defined, it only affects numbering of bits, | |
19437 | not which byte they end up in. | |
19438 | ||
19439 | Consequently it never makes sense to specify a starting bit number | |
19440 | greater than 7 (for a byte addressable field) if an attribute | |
19441 | definition for @code{Bit_Order} has been given, and indeed it | |
19442 | may be actively confusing to specify such a value, so the compiler | |
19443 | generates a warning for such usage. | |
19444 | ||
19445 | If you do need to control byte ordering then appropriate conditional | |
19446 | values must be used. If in our example, the slave byte came first on | |
19447 | some machines we might write: | |
19448 | ||
19449 | @example | |
19450 | Master_Byte_First constant Boolean := ...; | |
19451 | ||
19452 | Master_Byte : constant Natural := | |
19453 | 1 - Boolean'Pos (Master_Byte_First); | |
19454 | Slave_Byte : constant Natural := | |
19455 | Boolean'Pos (Master_Byte_First); | |
19456 | ||
19457 | for Data'Bit_Order use High_Order_First; | |
19458 | for Data use record | |
19459 | Master_Control at Master_Byte range 0 .. 0; | |
19460 | Master_V1 at Master_Byte range 1 .. 1; | |
19461 | Master_V2 at Master_Byte range 2 .. 2; | |
19462 | Master_V3 at Master_Byte range 3 .. 3; | |
19463 | Master_V4 at Master_Byte range 4 .. 4; | |
19464 | Master_V5 at Master_Byte range 5 .. 5; | |
19465 | Master_V6 at Master_Byte range 6 .. 6; | |
19466 | Master_V7 at Master_Byte range 7 .. 7; | |
19467 | Slave_Control at Slave_Byte range 0 .. 0; | |
19468 | Slave_V1 at Slave_Byte range 1 .. 1; | |
19469 | Slave_V2 at Slave_Byte range 2 .. 2; | |
19470 | Slave_V3 at Slave_Byte range 3 .. 3; | |
19471 | Slave_V4 at Slave_Byte range 4 .. 4; | |
19472 | Slave_V5 at Slave_Byte range 5 .. 5; | |
19473 | Slave_V6 at Slave_Byte range 6 .. 6; | |
19474 | Slave_V7 at Slave_Byte range 7 .. 7; | |
19475 | end record; | |
19476 | @end example | |
19477 | ||
19478 | Now to switch between machines, all that is necessary is | |
19479 | to set the boolean constant @code{Master_Byte_First} in | |
19480 | an appropriate manner. | |
19481 | ||
19482 | @node Pragma Pack for Arrays,Pragma Pack for Records,Effect of Bit_Order on Byte Ordering,Representation Clauses and Pragmas | |
04d6c745 | 19483 | @anchor{gnat_rm/representation_clauses_and_pragmas id11}@anchor{294}@anchor{gnat_rm/representation_clauses_and_pragmas pragma-pack-for-arrays}@anchor{295} |
64d5610f ML |
19484 | @section Pragma Pack for Arrays |
19485 | ||
19486 | ||
19487 | @geindex Pragma Pack (for arrays) | |
19488 | ||
19489 | Pragma @code{Pack} applied to an array has an effect that depends upon whether the | |
19490 | component type is `packable'. For a component type to be `packable', it must | |
19491 | be one of the following cases: | |
19492 | ||
19493 | ||
19494 | @itemize * | |
19495 | ||
19496 | @item | |
19497 | Any elementary type. | |
19498 | ||
19499 | @item | |
19500 | Any small packed array type with a static size. | |
19501 | ||
19502 | @item | |
19503 | Any small simple record type with a static size. | |
19504 | @end itemize | |
19505 | ||
19506 | For all these cases, if the component subtype size is in the range | |
19507 | 1 through 63 on 32-bit targets, and 1 through 127 on 64-bit targets, | |
19508 | then the effect of the pragma @code{Pack} is exactly as though a | |
19509 | component size were specified giving the component subtype size. | |
19510 | ||
19511 | All other types are non-packable, they occupy an integral number of storage | |
19512 | units and the only effect of pragma Pack is to remove alignment gaps. | |
19513 | ||
19514 | For example if we have: | |
19515 | ||
19516 | @example | |
19517 | type r is range 0 .. 17; | |
19518 | ||
19519 | type ar is array (1 .. 8) of r; | |
19520 | pragma Pack (ar); | |
19521 | @end example | |
19522 | ||
19523 | Then the component size of @code{ar} will be set to 5 (i.e., to @code{r'size}, | |
19524 | and the size of the array @code{ar} will be exactly 40 bits). | |
19525 | ||
19526 | Note that in some cases this rather fierce approach to packing can produce | |
19527 | unexpected effects. For example, in Ada 95 and Ada 2005, | |
19528 | subtype @code{Natural} typically has a size of 31, meaning that if you | |
19529 | pack an array of @code{Natural}, you get 31-bit | |
19530 | close packing, which saves a few bits, but results in far less efficient | |
19531 | access. Since many other Ada compilers will ignore such a packing request, | |
19532 | GNAT will generate a warning on some uses of pragma @code{Pack} that it guesses | |
19533 | might not be what is intended. You can easily remove this warning by | |
19534 | using an explicit @code{Component_Size} setting instead, which never generates | |
19535 | a warning, since the intention of the programmer is clear in this case. | |
19536 | ||
19537 | GNAT treats packed arrays in one of two ways. If the size of the array is | |
19538 | known at compile time and is at most 64 bits on 32-bit targets, and at most | |
19539 | 128 bits on 64-bit targets, then internally the array is represented as a | |
19540 | single modular type, of exactly the appropriate number of bits. If the | |
19541 | length is greater than 64 bits on 32-bit targets, and greater than 128 | |
19542 | bits on 64-bit targets, or is not known at compile time, then the packed | |
19543 | array is represented as an array of bytes, and its length is always a | |
19544 | multiple of 8 bits. | |
19545 | ||
19546 | Note that to represent a packed array as a modular type, the alignment must | |
19547 | be suitable for the modular type involved. For example, on typical machines | |
19548 | a 32-bit packed array will be represented by a 32-bit modular integer with | |
19549 | an alignment of four bytes. If you explicitly override the default alignment | |
19550 | with an alignment clause that is too small, the modular representation | |
19551 | cannot be used. For example, consider the following set of declarations: | |
19552 | ||
19553 | @example | |
19554 | type R is range 1 .. 3; | |
19555 | type S is array (1 .. 31) of R; | |
19556 | for S'Component_Size use 2; | |
19557 | for S'Size use 62; | |
19558 | for S'Alignment use 1; | |
19559 | @end example | |
19560 | ||
19561 | If the alignment clause were not present, then a 62-bit modular | |
19562 | representation would be chosen (typically with an alignment of 4 or 8 | |
19563 | bytes depending on the target). But the default alignment is overridden | |
19564 | with the explicit alignment clause. This means that the modular | |
19565 | representation cannot be used, and instead the array of bytes | |
19566 | representation must be used, meaning that the length must be a multiple | |
19567 | of 8. Thus the above set of declarations will result in a diagnostic | |
19568 | rejecting the size clause and noting that the minimum size allowed is 64. | |
19569 | ||
19570 | @geindex Pragma Pack (for type Natural) | |
19571 | ||
19572 | @geindex Pragma Pack warning | |
19573 | ||
19574 | One special case that is worth noting occurs when the base type of the | |
19575 | component size is 8/16/32 and the subtype is one bit less. Notably this | |
19576 | occurs with subtype @code{Natural}. Consider: | |
19577 | ||
19578 | @example | |
19579 | type Arr is array (1 .. 32) of Natural; | |
19580 | pragma Pack (Arr); | |
19581 | @end example | |
19582 | ||
19583 | In all commonly used Ada 83 compilers, this pragma Pack would be ignored, | |
19584 | since typically @code{Natural'Size} is 32 in Ada 83, and in any case most | |
19585 | Ada 83 compilers did not attempt 31 bit packing. | |
19586 | ||
19587 | In Ada 95 and Ada 2005, @code{Natural'Size} is required to be 31. Furthermore, | |
19588 | GNAT really does pack 31-bit subtype to 31 bits. This may result in a | |
19589 | substantial unintended performance penalty when porting legacy Ada 83 code. | |
19590 | To help prevent this, GNAT generates a warning in such cases. If you really | |
19591 | want 31 bit packing in a case like this, you can set the component size | |
19592 | explicitly: | |
19593 | ||
19594 | @example | |
19595 | type Arr is array (1 .. 32) of Natural; | |
19596 | for Arr'Component_Size use 31; | |
19597 | @end example | |
19598 | ||
19599 | Here 31-bit packing is achieved as required, and no warning is generated, | |
19600 | since in this case the programmer intention is clear. | |
19601 | ||
19602 | @node Pragma Pack for Records,Record Representation Clauses,Pragma Pack for Arrays,Representation Clauses and Pragmas | |
04d6c745 | 19603 | @anchor{gnat_rm/representation_clauses_and_pragmas id12}@anchor{296}@anchor{gnat_rm/representation_clauses_and_pragmas pragma-pack-for-records}@anchor{297} |
64d5610f ML |
19604 | @section Pragma Pack for Records |
19605 | ||
19606 | ||
19607 | @geindex Pragma Pack (for records) | |
19608 | ||
19609 | Pragma @code{Pack} applied to a record will pack the components to reduce | |
19610 | wasted space from alignment gaps and by reducing the amount of space | |
19611 | taken by components. We distinguish between `packable' components and | |
19612 | `non-packable' components. | |
19613 | Components of the following types are considered packable: | |
19614 | ||
19615 | ||
19616 | @itemize * | |
19617 | ||
19618 | @item | |
19619 | Components of an elementary type are packable unless they are aliased, | |
19620 | independent or atomic. | |
19621 | ||
19622 | @item | |
19623 | Small packed arrays, where the size is statically known, are represented | |
19624 | internally as modular integers, and so they are also packable. | |
19625 | ||
19626 | @item | |
19627 | Small simple records, where the size is statically known, are also packable. | |
19628 | @end itemize | |
19629 | ||
19630 | For all these cases, if the @code{'Size} value is in the range 1 through 64 on | |
19631 | 32-bit targets, and 1 through 128 on 64-bit targets, the components occupy | |
19632 | the exact number of bits corresponding to this value and are packed with no | |
19633 | padding bits, i.e. they can start on an arbitrary bit boundary. | |
19634 | ||
19635 | All other types are non-packable, they occupy an integral number of storage | |
19636 | units and the only effect of pragma @code{Pack} is to remove alignment gaps. | |
19637 | ||
19638 | For example, consider the record | |
19639 | ||
19640 | @example | |
19641 | type Rb1 is array (1 .. 13) of Boolean; | |
19642 | pragma Pack (Rb1); | |
19643 | ||
19644 | type Rb2 is array (1 .. 65) of Boolean; | |
19645 | pragma Pack (Rb2); | |
19646 | ||
19647 | type AF is new Float with Atomic; | |
19648 | ||
19649 | type X2 is record | |
19650 | L1 : Boolean; | |
19651 | L2 : Duration; | |
19652 | L3 : AF; | |
19653 | L4 : Boolean; | |
19654 | L5 : Rb1; | |
19655 | L6 : Rb2; | |
19656 | end record; | |
19657 | pragma Pack (X2); | |
19658 | @end example | |
19659 | ||
19660 | The representation for the record @code{X2} is as follows on 32-bit targets: | |
19661 | ||
19662 | @example | |
19663 | for X2'Size use 224; | |
19664 | for X2 use record | |
19665 | L1 at 0 range 0 .. 0; | |
19666 | L2 at 0 range 1 .. 64; | |
19667 | L3 at 12 range 0 .. 31; | |
19668 | L4 at 16 range 0 .. 0; | |
19669 | L5 at 16 range 1 .. 13; | |
19670 | L6 at 18 range 0 .. 71; | |
19671 | end record; | |
19672 | @end example | |
19673 | ||
19674 | Studying this example, we see that the packable fields @code{L1} | |
19675 | and @code{L2} are of length equal to their sizes, and placed at | |
19676 | specific bit boundaries (and not byte boundaries) to eliminate | |
19677 | padding. But @code{L3} is of a non-packable float type (because | |
19678 | it is aliased), so it is on the next appropriate alignment boundary. | |
19679 | ||
19680 | The next two fields are fully packable, so @code{L4} and @code{L5} are | |
19681 | minimally packed with no gaps. However, type @code{Rb2} is a packed | |
19682 | array that is longer than 64 bits, so it is itself non-packable on | |
19683 | 32-bit targets. Thus the @code{L6} field is aligned to the next byte | |
19684 | boundary, and takes an integral number of bytes, i.e., 72 bits. | |
19685 | ||
19686 | @node Record Representation Clauses,Handling of Records with Holes,Pragma Pack for Records,Representation Clauses and Pragmas | |
04d6c745 | 19687 | @anchor{gnat_rm/representation_clauses_and_pragmas id13}@anchor{298}@anchor{gnat_rm/representation_clauses_and_pragmas record-representation-clauses}@anchor{299} |
64d5610f ML |
19688 | @section Record Representation Clauses |
19689 | ||
19690 | ||
19691 | @geindex Record Representation Clause | |
19692 | ||
19693 | Record representation clauses may be given for all record types, including | |
19694 | types obtained by record extension. Component clauses are allowed for any | |
19695 | static component. The restrictions on component clauses depend on the type | |
19696 | of the component. | |
19697 | ||
19698 | @geindex Component Clause | |
19699 | ||
19700 | For all components of an elementary type, the only restriction on component | |
19701 | clauses is that the size must be at least the @code{'Size} value of the type | |
19702 | (actually the Value_Size). There are no restrictions due to alignment, | |
19703 | and such components may freely cross storage boundaries. | |
19704 | ||
19705 | Packed arrays with a size up to and including 64 bits on 32-bit targets, | |
19706 | and up to and including 128 bits on 64-bit targets, are represented | |
19707 | internally using a modular type with the appropriate number of bits, and | |
19708 | thus the same lack of restriction applies. For example, if you declare: | |
19709 | ||
19710 | @example | |
19711 | type R is array (1 .. 49) of Boolean; | |
19712 | pragma Pack (R); | |
19713 | for R'Size use 49; | |
19714 | @end example | |
19715 | ||
19716 | then a component clause for a component of type @code{R} may start on any | |
19717 | specified bit boundary, and may specify a value of 49 bits or greater. | |
19718 | ||
19719 | For packed bit arrays that are longer than 64 bits on 32-bit targets, | |
19720 | and longer than 128 bits on 64-bit targets, there are two cases. If the | |
19721 | component size is a power of 2 (1,2,4,8,16,32,64 bits), including the | |
19722 | important case of single bits or boolean values, then there are no | |
19723 | limitations on placement of such components, and they may start and | |
19724 | end at arbitrary bit boundaries. | |
19725 | ||
19726 | If the component size is not a power of 2 (e.g., 3 or 5), then an array | |
19727 | of this type must always be placed on on a storage unit (byte) boundary | |
19728 | and occupy an integral number of storage units (bytes). Any component | |
19729 | clause that does not meet this requirement will be rejected. | |
19730 | ||
19731 | Any aliased component, or component of an aliased type, must have its | |
19732 | normal alignment and size. A component clause that does not meet this | |
19733 | requirement will be rejected. | |
19734 | ||
19735 | The tag field of a tagged type always occupies an address sized field at | |
19736 | the start of the record. No component clause may attempt to overlay this | |
19737 | tag. When a tagged type appears as a component, the tag field must have | |
19738 | proper alignment | |
19739 | ||
19740 | In the case of a record extension @code{T1}, of a type @code{T}, no component | |
19741 | clause applied to the type @code{T1} can specify a storage location that | |
19742 | would overlap the first @code{T'Object_Size} bits of the record. | |
19743 | ||
19744 | For all other component types, including non-bit-packed arrays, | |
19745 | the component can be placed at an arbitrary bit boundary, | |
19746 | so for example, the following is permitted: | |
19747 | ||
19748 | @example | |
19749 | type R is array (1 .. 10) of Boolean; | |
19750 | for R'Size use 80; | |
19751 | ||
19752 | type Q is record | |
19753 | G, H : Boolean; | |
19754 | L, M : R; | |
19755 | end record; | |
19756 | ||
19757 | for Q use record | |
19758 | G at 0 range 0 .. 0; | |
19759 | H at 0 range 1 .. 1; | |
19760 | L at 0 range 2 .. 81; | |
19761 | R at 0 range 82 .. 161; | |
19762 | end record; | |
19763 | @end example | |
19764 | ||
19765 | @node Handling of Records with Holes,Enumeration Clauses,Record Representation Clauses,Representation Clauses and Pragmas | |
04d6c745 | 19766 | @anchor{gnat_rm/representation_clauses_and_pragmas handling-of-records-with-holes}@anchor{29a}@anchor{gnat_rm/representation_clauses_and_pragmas id14}@anchor{29b} |
64d5610f ML |
19767 | @section Handling of Records with Holes |
19768 | ||
19769 | ||
19770 | @geindex Handling of Records with Holes | |
19771 | ||
19772 | As a result of alignment considerations, records may contain “holes” | |
19773 | or gaps which do not correspond to the data bits of any of the components. | |
19774 | Record representation clauses can also result in holes in records. | |
19775 | ||
19776 | GNAT does not attempt to clear these holes, so in record objects, | |
19777 | they should be considered to hold undefined rubbish. The generated | |
19778 | equality routine just tests components so does not access these | |
19779 | undefined bits, and assignment and copy operations may or may not | |
19780 | preserve the contents of these holes (for assignments, the holes | |
19781 | in the target will in practice contain either the bits that are | |
19782 | present in the holes in the source, or the bits that were present | |
19783 | in the target before the assignment). | |
19784 | ||
19785 | If it is necessary to ensure that holes in records have all zero | |
19786 | bits, then record objects for which this initialization is desired | |
19787 | should be explicitly set to all zero values using Unchecked_Conversion | |
19788 | or address overlays. For example | |
19789 | ||
19790 | @example | |
19791 | type HRec is record | |
19792 | C : Character; | |
19793 | I : Integer; | |
19794 | end record; | |
19795 | @end example | |
19796 | ||
19797 | On typical machines, integers need to be aligned on a four-byte | |
19798 | boundary, resulting in three bytes of undefined rubbish following | |
19799 | the 8-bit field for C. To ensure that the hole in a variable of | |
19800 | type HRec is set to all zero bits, | |
19801 | you could for example do: | |
19802 | ||
19803 | @example | |
19804 | type Base is record | |
19805 | Dummy1, Dummy2 : Integer := 0; | |
19806 | end record; | |
19807 | ||
19808 | BaseVar : Base; | |
19809 | RealVar : Hrec; | |
19810 | for RealVar'Address use BaseVar'Address; | |
19811 | @end example | |
19812 | ||
19813 | Now the 8-bytes of the value of RealVar start out containing all zero | |
19814 | bits. A safer approach is to just define dummy fields, avoiding the | |
19815 | holes, as in: | |
19816 | ||
19817 | @example | |
19818 | type HRec is record | |
19819 | C : Character; | |
19820 | Dummy1 : Short_Short_Integer := 0; | |
19821 | Dummy2 : Short_Short_Integer := 0; | |
19822 | Dummy3 : Short_Short_Integer := 0; | |
19823 | I : Integer; | |
19824 | end record; | |
19825 | @end example | |
19826 | ||
19827 | And to make absolutely sure that the intent of this is followed, you | |
19828 | can use representation clauses: | |
19829 | ||
19830 | @example | |
19831 | for Hrec use record | |
19832 | C at 0 range 0 .. 7; | |
19833 | Dummy1 at 1 range 0 .. 7; | |
19834 | Dummy2 at 2 range 0 .. 7; | |
19835 | Dummy3 at 3 range 0 .. 7; | |
19836 | I at 4 range 0 .. 31; | |
19837 | end record; | |
19838 | for Hrec'Size use 64; | |
19839 | @end example | |
19840 | ||
19841 | @node Enumeration Clauses,Address Clauses,Handling of Records with Holes,Representation Clauses and Pragmas | |
04d6c745 | 19842 | @anchor{gnat_rm/representation_clauses_and_pragmas enumeration-clauses}@anchor{29c}@anchor{gnat_rm/representation_clauses_and_pragmas id15}@anchor{29d} |
64d5610f ML |
19843 | @section Enumeration Clauses |
19844 | ||
19845 | ||
19846 | The only restriction on enumeration clauses is that the range of values | |
19847 | must be representable. For the signed case, if one or more of the | |
19848 | representation values are negative, all values must be in the range: | |
19849 | ||
19850 | @example | |
19851 | System.Min_Int .. System.Max_Int | |
19852 | @end example | |
19853 | ||
19854 | For the unsigned case, where all values are nonnegative, the values must | |
19855 | be in the range: | |
19856 | ||
19857 | @example | |
19858 | 0 .. System.Max_Binary_Modulus; | |
19859 | @end example | |
19860 | ||
19861 | A `confirming' representation clause is one in which the values range | |
19862 | from 0 in sequence, i.e., a clause that confirms the default representation | |
19863 | for an enumeration type. | |
19864 | Such a confirming representation | |
19865 | is permitted by these rules, and is specially recognized by the compiler so | |
19866 | that no extra overhead results from the use of such a clause. | |
19867 | ||
19868 | If an array has an index type which is an enumeration type to which an | |
19869 | enumeration clause has been applied, then the array is stored in a compact | |
19870 | manner. Consider the declarations: | |
19871 | ||
19872 | @example | |
19873 | type r is (A, B, C); | |
19874 | for r use (A => 1, B => 5, C => 10); | |
19875 | type t is array (r) of Character; | |
19876 | @end example | |
19877 | ||
19878 | The array type t corresponds to a vector with exactly three elements and | |
19879 | has a default size equal to @code{3*Character'Size}. This ensures efficient | |
19880 | use of space, but means that accesses to elements of the array will incur | |
19881 | the overhead of converting representation values to the corresponding | |
19882 | positional values, (i.e., the value delivered by the @code{Pos} attribute). | |
19883 | ||
19884 | @node Address Clauses,Use of Address Clauses for Memory-Mapped I/O,Enumeration Clauses,Representation Clauses and Pragmas | |
04d6c745 | 19885 | @anchor{gnat_rm/representation_clauses_and_pragmas address-clauses}@anchor{29e}@anchor{gnat_rm/representation_clauses_and_pragmas id16}@anchor{29f} |
64d5610f ML |
19886 | @section Address Clauses |
19887 | ||
19888 | ||
19889 | @geindex Address Clause | |
19890 | ||
19891 | The reference manual allows a general restriction on representation clauses, | |
19892 | as found in RM 13.1(22): | |
19893 | ||
19894 | @quotation | |
19895 | ||
19896 | “An implementation need not support representation | |
19897 | items containing nonstatic expressions, except that | |
19898 | an implementation should support a representation item | |
19899 | for a given entity if each nonstatic expression in the | |
19900 | representation item is a name that statically denotes | |
19901 | a constant declared before the entity.” | |
19902 | @end quotation | |
19903 | ||
19904 | In practice this is applicable only to address clauses, since this is the | |
19905 | only case in which a nonstatic expression is permitted by the syntax. As | |
19906 | the AARM notes in sections 13.1 (22.a-22.h): | |
19907 | ||
19908 | @quotation | |
19909 | ||
19910 | 22.a Reason: This is to avoid the following sort of thing: | |
19911 | ||
19912 | 22.b X : Integer := F(…); | |
19913 | Y : Address := G(…); | |
19914 | for X’Address use Y; | |
19915 | ||
19916 | 22.c In the above, we have to evaluate the | |
19917 | initialization expression for X before we | |
19918 | know where to put the result. This seems | |
19919 | like an unreasonable implementation burden. | |
19920 | ||
19921 | 22.d The above code should instead be written | |
19922 | like this: | |
19923 | ||
19924 | 22.e Y : constant Address := G(…); | |
19925 | X : Integer := F(…); | |
19926 | for X’Address use Y; | |
19927 | ||
19928 | 22.f This allows the expression ‘Y’ to be safely | |
19929 | evaluated before X is created. | |
19930 | ||
19931 | 22.g The constant could be a formal parameter of mode in. | |
19932 | ||
19933 | 22.h An implementation can support other nonstatic | |
19934 | expressions if it wants to. Expressions of type | |
19935 | Address are hardly ever static, but their value | |
19936 | might be known at compile time anyway in many | |
19937 | cases. | |
19938 | @end quotation | |
19939 | ||
19940 | GNAT does indeed permit many additional cases of nonstatic expressions. In | |
19941 | particular, if the type involved is elementary there are no restrictions | |
19942 | (since in this case, holding a temporary copy of the initialization value, | |
19943 | if one is present, is inexpensive). In addition, if there is no implicit or | |
19944 | explicit initialization, then there are no restrictions. GNAT will reject | |
19945 | only the case where all three of these conditions hold: | |
19946 | ||
19947 | ||
19948 | @itemize * | |
19949 | ||
19950 | @item | |
19951 | The type of the item is non-elementary (e.g., a record or array). | |
19952 | ||
19953 | @item | |
19954 | There is explicit or implicit initialization required for the object. | |
19955 | Note that access values are always implicitly initialized. | |
19956 | ||
19957 | @item | |
19958 | The address value is nonstatic. Here GNAT is more permissive than the | |
19959 | RM, and allows the address value to be the address of a previously declared | |
19960 | stand-alone variable, as long as it does not itself have an address clause. | |
19961 | ||
19962 | @example | |
19963 | Anchor : Some_Initialized_Type; | |
19964 | Overlay : Some_Initialized_Type; | |
19965 | for Overlay'Address use Anchor'Address; | |
19966 | @end example | |
19967 | ||
19968 | However, the prefix of the address clause cannot be an array component, or | |
19969 | a component of a discriminated record. | |
19970 | @end itemize | |
19971 | ||
19972 | As noted above in section 22.h, address values are typically nonstatic. In | |
19973 | particular the To_Address function, even if applied to a literal value, is | |
19974 | a nonstatic function call. To avoid this minor annoyance, GNAT provides | |
19975 | the implementation defined attribute ‘To_Address. The following two | |
19976 | expressions have identical values: | |
19977 | ||
19978 | @geindex Attribute | |
19979 | ||
19980 | @geindex To_Address | |
19981 | ||
19982 | @example | |
19983 | To_Address (16#1234_0000#) | |
19984 | System'To_Address (16#1234_0000#); | |
19985 | @end example | |
19986 | ||
19987 | except that the second form is considered to be a static expression, and | |
19988 | thus when used as an address clause value is always permitted. | |
19989 | ||
19990 | Additionally, GNAT treats as static an address clause that is an | |
19991 | unchecked_conversion of a static integer value. This simplifies the porting | |
19992 | of legacy code, and provides a portable equivalent to the GNAT attribute | |
19993 | @code{To_Address}. | |
19994 | ||
19995 | Another issue with address clauses is the interaction with alignment | |
19996 | requirements. When an address clause is given for an object, the address | |
19997 | value must be consistent with the alignment of the object (which is usually | |
19998 | the same as the alignment of the type of the object). If an address clause | |
19999 | is given that specifies an inappropriately aligned address value, then the | |
20000 | program execution is erroneous. | |
20001 | ||
20002 | Since this source of erroneous behavior can have unfortunate effects on | |
20003 | machines with strict alignment requirements, GNAT | |
20004 | checks (at compile time if possible, generating a warning, or at execution | |
20005 | time with a run-time check) that the alignment is appropriate. If the | |
20006 | run-time check fails, then @code{Program_Error} is raised. This run-time | |
20007 | check is suppressed if range checks are suppressed, or if the special GNAT | |
20008 | check Alignment_Check is suppressed, or if | |
20009 | @code{pragma Restrictions (No_Elaboration_Code)} is in effect. It is also | |
20010 | suppressed by default on non-strict alignment machines (such as the x86). | |
20011 | ||
20012 | In some cases, GNAT does not support an address specification (using either | |
20013 | form of aspect specification syntax) for the declaration of an object that has | |
20014 | an indefinite nominal subtype. An object declaration has an indefinite | |
20015 | nominal subtype if it takes its bounds (for an array type), discriminant | |
20016 | values (for a discriminated type whose discriminants lack defaults), or tag | |
20017 | (for a class-wide type) from its initial value, as in | |
20018 | ||
20019 | @example | |
20020 | X : String := Some_Function_Call; | |
20021 | -- String has no constraint, so bounds for X come from function call | |
20022 | @end example | |
20023 | ||
20024 | This restriction does not apply if the size of the object’s initial value is | |
20025 | known at compile time and the type of the object is not class-wide. | |
20026 | ||
20027 | @geindex Export | |
20028 | ||
20029 | An address clause cannot be given for an exported object. More | |
20030 | understandably the real restriction is that objects with an address | |
20031 | clause cannot be exported. This is because such variables are not | |
20032 | defined by the Ada program, so there is no external object to export. | |
20033 | ||
20034 | @geindex Import | |
20035 | ||
20036 | It is permissible to give an address clause and a pragma Import for the | |
20037 | same object. In this case, the variable is not really defined by the | |
20038 | Ada program, so there is no external symbol to be linked. The link name | |
20039 | and the external name are ignored in this case. The reason that we allow this | |
20040 | combination is that it provides a useful idiom to avoid unwanted | |
20041 | initializations on objects with address clauses. | |
20042 | ||
20043 | When an address clause is given for an object that has implicit or | |
20044 | explicit initialization, then by default initialization takes place. This | |
20045 | means that the effect of the object declaration is to overwrite the | |
20046 | memory at the specified address. This is almost always not what the | |
20047 | programmer wants, so GNAT will output a warning: | |
20048 | ||
20049 | @example | |
20050 | with System; | |
20051 | package G is | |
20052 | type R is record | |
20053 | M : Integer := 0; | |
20054 | end record; | |
20055 | ||
20056 | Ext : R; | |
20057 | for Ext'Address use System'To_Address (16#1234_1234#); | |
20058 | | | |
20059 | >>> warning: implicit initialization of "Ext" may | |
20060 | modify overlaid storage | |
20061 | >>> warning: use pragma Import for "Ext" to suppress | |
20062 | initialization (RM B(24)) | |
20063 | ||
20064 | end G; | |
20065 | @end example | |
20066 | ||
20067 | As indicated by the warning message, the solution is to use a (dummy) pragma | |
20068 | Import to suppress this initialization. The pragma tell the compiler that the | |
20069 | object is declared and initialized elsewhere. The following package compiles | |
20070 | without warnings (and the initialization is suppressed): | |
20071 | ||
20072 | @example | |
20073 | with System; | |
20074 | package G is | |
20075 | type R is record | |
20076 | M : Integer := 0; | |
20077 | end record; | |
20078 | ||
20079 | Ext : R; | |
20080 | for Ext'Address use System'To_Address (16#1234_1234#); | |
20081 | pragma Import (Ada, Ext); | |
20082 | end G; | |
20083 | @end example | |
20084 | ||
20085 | A final issue with address clauses involves their use for overlaying | |
20086 | variables, as in the following example: | |
20087 | ||
20088 | @geindex Overlaying of objects | |
20089 | ||
20090 | @example | |
20091 | A : Integer; | |
20092 | B : Integer; | |
20093 | for B'Address use A'Address; | |
20094 | @end example | |
20095 | ||
20096 | or alternatively, using the form recommended by the RM: | |
20097 | ||
20098 | @example | |
20099 | A : Integer; | |
20100 | Addr : constant Address := A'Address; | |
20101 | B : Integer; | |
20102 | for B'Address use Addr; | |
20103 | @end example | |
20104 | ||
20105 | In both of these cases, @code{A} and @code{B} become aliased to one another | |
20106 | via the address clause. This use of address clauses to overlay | |
20107 | variables, achieving an effect similar to unchecked conversion | |
20108 | was erroneous in Ada 83, but in Ada 95 and Ada 2005 | |
20109 | the effect is implementation defined. Furthermore, the | |
20110 | Ada RM specifically recommends that in a situation | |
20111 | like this, @code{B} should be subject to the following | |
20112 | implementation advice (RM 13.3(19)): | |
20113 | ||
20114 | @quotation | |
20115 | ||
20116 | “19 If the Address of an object is specified, or it is imported | |
20117 | or exported, then the implementation should not perform | |
20118 | optimizations based on assumptions of no aliases.” | |
20119 | @end quotation | |
20120 | ||
20121 | GNAT follows this recommendation, and goes further by also applying | |
20122 | this recommendation to the overlaid variable (@code{A} in the above example) | |
20123 | in this case. This means that the overlay works “as expected”, in that | |
20124 | a modification to one of the variables will affect the value of the other. | |
20125 | ||
20126 | More generally, GNAT interprets this recommendation conservatively for | |
20127 | address clauses: in the cases other than overlays, it considers that the | |
20128 | object is effectively subject to pragma @code{Volatile} and implements the | |
20129 | associated semantics. | |
20130 | ||
20131 | Note that when address clause overlays are used in this way, there is an | |
20132 | issue of unintentional initialization, as shown by this example: | |
20133 | ||
20134 | @example | |
20135 | package Overwrite_Record is | |
20136 | type R is record | |
20137 | A : Character := 'C'; | |
20138 | B : Character := 'A'; | |
20139 | end record; | |
20140 | X : Short_Integer := 3; | |
20141 | Y : R; | |
20142 | for Y'Address use X'Address; | |
20143 | | | |
20144 | >>> warning: default initialization of "Y" may | |
20145 | modify "X", use pragma Import for "Y" to | |
20146 | suppress initialization (RM B.1(24)) | |
20147 | ||
20148 | end Overwrite_Record; | |
20149 | @end example | |
20150 | ||
20151 | Here the default initialization of @code{Y} will clobber the value | |
20152 | of @code{X}, which justifies the warning. The warning notes that | |
20153 | this effect can be eliminated by adding a @code{pragma Import} | |
20154 | which suppresses the initialization: | |
20155 | ||
20156 | @example | |
20157 | package Overwrite_Record is | |
20158 | type R is record | |
20159 | A : Character := 'C'; | |
20160 | B : Character := 'A'; | |
20161 | end record; | |
20162 | X : Short_Integer := 3; | |
20163 | Y : R; | |
20164 | for Y'Address use X'Address; | |
20165 | pragma Import (Ada, Y); | |
20166 | end Overwrite_Record; | |
20167 | @end example | |
20168 | ||
20169 | Note that the use of @code{pragma Initialize_Scalars} may cause variables to | |
20170 | be initialized when they would not otherwise have been in the absence | |
20171 | of the use of this pragma. This may cause an overlay to have this | |
20172 | unintended clobbering effect. The compiler avoids this for scalar | |
20173 | types, but not for composite objects (where in general the effect | |
20174 | of @code{Initialize_Scalars} is part of the initialization routine | |
20175 | for the composite object): | |
20176 | ||
20177 | @example | |
20178 | pragma Initialize_Scalars; | |
20179 | with Ada.Text_IO; use Ada.Text_IO; | |
20180 | procedure Overwrite_Array is | |
20181 | type Arr is array (1 .. 5) of Integer; | |
20182 | X : Arr := (others => 1); | |
20183 | A : Arr; | |
20184 | for A'Address use X'Address; | |
20185 | | | |
20186 | >>> warning: default initialization of "A" may | |
20187 | modify "X", use pragma Import for "A" to | |
20188 | suppress initialization (RM B.1(24)) | |
20189 | ||
20190 | begin | |
20191 | if X /= Arr'(others => 1) then | |
20192 | Put_Line ("X was clobbered"); | |
20193 | else | |
20194 | Put_Line ("X was not clobbered"); | |
20195 | end if; | |
20196 | end Overwrite_Array; | |
20197 | @end example | |
20198 | ||
20199 | The above program generates the warning as shown, and at execution | |
20200 | time, prints @code{X was clobbered}. If the @code{pragma Import} is | |
20201 | added as suggested: | |
20202 | ||
20203 | @example | |
20204 | pragma Initialize_Scalars; | |
20205 | with Ada.Text_IO; use Ada.Text_IO; | |
20206 | procedure Overwrite_Array is | |
20207 | type Arr is array (1 .. 5) of Integer; | |
20208 | X : Arr := (others => 1); | |
20209 | A : Arr; | |
20210 | for A'Address use X'Address; | |
20211 | pragma Import (Ada, A); | |
20212 | begin | |
20213 | if X /= Arr'(others => 1) then | |
20214 | Put_Line ("X was clobbered"); | |
20215 | else | |
20216 | Put_Line ("X was not clobbered"); | |
20217 | end if; | |
20218 | end Overwrite_Array; | |
20219 | @end example | |
20220 | ||
20221 | then the program compiles without the warning and when run will generate | |
20222 | the output @code{X was not clobbered}. | |
20223 | ||
20224 | @node Use of Address Clauses for Memory-Mapped I/O,Effect of Convention on Representation,Address Clauses,Representation Clauses and Pragmas | |
04d6c745 | 20225 | @anchor{gnat_rm/representation_clauses_and_pragmas id17}@anchor{2a0}@anchor{gnat_rm/representation_clauses_and_pragmas use-of-address-clauses-for-memory-mapped-i-o}@anchor{2a1} |
64d5610f ML |
20226 | @section Use of Address Clauses for Memory-Mapped I/O |
20227 | ||
20228 | ||
20229 | @geindex Memory-mapped I/O | |
20230 | ||
20231 | A common pattern is to use an address clause to map an atomic variable to | |
20232 | a location in memory that corresponds to a memory-mapped I/O operation or | |
20233 | operations, for example: | |
20234 | ||
20235 | @example | |
20236 | type Mem_Word is record | |
20237 | A,B,C,D : Byte; | |
20238 | end record; | |
20239 | pragma Atomic (Mem_Word); | |
20240 | for Mem_Word_Size use 32; | |
20241 | ||
20242 | Mem : Mem_Word; | |
20243 | for Mem'Address use some-address; | |
20244 | ... | |
20245 | Temp := Mem; | |
20246 | Temp.A := 32; | |
20247 | Mem := Temp; | |
20248 | @end example | |
20249 | ||
20250 | For a full access (reference or modification) of the variable (Mem) in this | |
20251 | case, as in the above examples, GNAT guarantees that the entire atomic word | |
20252 | will be accessed, in accordance with the RM C.6(15) clause. | |
20253 | ||
20254 | A problem arises with a component access such as: | |
20255 | ||
20256 | @example | |
20257 | Mem.A := 32; | |
20258 | @end example | |
20259 | ||
20260 | Note that the component A is not declared as atomic. This means that it is | |
20261 | not clear what this assignment means. It could correspond to full word read | |
20262 | and write as given in the first example, or on architectures that supported | |
20263 | such an operation it might be a single byte store instruction. The RM does | |
20264 | not have anything to say in this situation, and GNAT does not make any | |
20265 | guarantee. The code generated may vary from target to target. GNAT will issue | |
20266 | a warning in such a case: | |
20267 | ||
20268 | @example | |
20269 | Mem.A := 32; | |
20270 | | | |
20271 | >>> warning: access to non-atomic component of atomic array, | |
20272 | may cause unexpected accesses to atomic object | |
20273 | @end example | |
20274 | ||
20275 | It is best to be explicit in this situation, by either declaring the | |
20276 | components to be atomic if you want the byte store, or explicitly writing | |
20277 | the full word access sequence if that is what the hardware requires. | |
20278 | Alternatively, if the full word access sequence is required, GNAT also | |
20279 | provides the pragma @code{Volatile_Full_Access} which can be used in lieu of | |
20280 | pragma @code{Atomic} and will give the additional guarantee. | |
20281 | ||
20282 | @node Effect of Convention on Representation,Conventions and Anonymous Access Types,Use of Address Clauses for Memory-Mapped I/O,Representation Clauses and Pragmas | |
04d6c745 | 20283 | @anchor{gnat_rm/representation_clauses_and_pragmas effect-of-convention-on-representation}@anchor{2a2}@anchor{gnat_rm/representation_clauses_and_pragmas id18}@anchor{2a3} |
64d5610f ML |
20284 | @section Effect of Convention on Representation |
20285 | ||
20286 | ||
20287 | @geindex Convention | |
20288 | @geindex effect on representation | |
20289 | ||
20290 | Normally the specification of a foreign language convention for a type or | |
20291 | an object has no effect on the chosen representation. In particular, the | |
20292 | representation chosen for data in GNAT generally meets the standard system | |
20293 | conventions, and for example records are laid out in a manner that is | |
20294 | consistent with C. This means that specifying convention C (for example) | |
20295 | has no effect. | |
20296 | ||
20297 | There are four exceptions to this general rule: | |
20298 | ||
20299 | ||
20300 | @itemize * | |
20301 | ||
20302 | @item | |
20303 | `Convention Fortran and array subtypes'. | |
20304 | ||
20305 | If pragma Convention Fortran is specified for an array subtype, then in | |
20306 | accordance with the implementation advice in section 3.6.2(11) of the | |
20307 | Ada Reference Manual, the array will be stored in a Fortran-compatible | |
20308 | column-major manner, instead of the normal default row-major order. | |
20309 | ||
20310 | @item | |
20311 | `Convention C and enumeration types' | |
20312 | ||
20313 | GNAT normally stores enumeration types in 8, 16, or 32 bits as required | |
20314 | to accommodate all values of the type. For example, for the enumeration | |
20315 | type declared by: | |
20316 | ||
20317 | @example | |
20318 | type Color is (Red, Green, Blue); | |
20319 | @end example | |
20320 | ||
20321 | 8 bits is sufficient to store all values of the type, so by default, objects | |
20322 | of type @code{Color} will be represented using 8 bits. However, normal C | |
20323 | convention is to use 32 bits for all enum values in C, since enum values | |
20324 | are essentially of type int. If pragma @code{Convention C} is specified for an | |
20325 | Ada enumeration type, then the size is modified as necessary (usually to | |
20326 | 32 bits) to be consistent with the C convention for enum values. | |
20327 | ||
20328 | Note that this treatment applies only to types. If Convention C is given for | |
20329 | an enumeration object, where the enumeration type is not Convention C, then | |
20330 | Object_Size bits are allocated. For example, for a normal enumeration type, | |
20331 | with less than 256 elements, only 8 bits will be allocated for the object. | |
20332 | Since this may be a surprise in terms of what C expects, GNAT will issue a | |
20333 | warning in this situation. The warning can be suppressed by giving an explicit | |
20334 | size clause specifying the desired size. | |
20335 | ||
20336 | @item | |
20337 | `Convention C/Fortran and Boolean types' | |
20338 | ||
20339 | In C, the usual convention for boolean values, that is values used for | |
20340 | conditions, is that zero represents false, and nonzero values represent | |
20341 | true. In Ada, the normal convention is that two specific values, typically | |
20342 | 0/1, are used to represent false/true respectively. | |
20343 | ||
20344 | Fortran has a similar convention for @code{LOGICAL} values (any nonzero | |
20345 | value represents true). | |
20346 | ||
20347 | To accommodate the Fortran and C conventions, if a pragma Convention specifies | |
20348 | C or Fortran convention for a derived Boolean, as in the following example: | |
20349 | ||
20350 | @example | |
20351 | type C_Switch is new Boolean; | |
20352 | pragma Convention (C, C_Switch); | |
20353 | @end example | |
20354 | ||
20355 | then the GNAT generated code will treat any nonzero value as true. For truth | |
20356 | values generated by GNAT, the conventional value 1 will be used for True, but | |
20357 | when one of these values is read, any nonzero value is treated as True. | |
20358 | @end itemize | |
20359 | ||
20360 | @node Conventions and Anonymous Access Types,Determining the Representations chosen by GNAT,Effect of Convention on Representation,Representation Clauses and Pragmas | |
04d6c745 | 20361 | @anchor{gnat_rm/representation_clauses_and_pragmas conventions-and-anonymous-access-types}@anchor{2a4}@anchor{gnat_rm/representation_clauses_and_pragmas id19}@anchor{2a5} |
64d5610f ML |
20362 | @section Conventions and Anonymous Access Types |
20363 | ||
20364 | ||
20365 | @geindex Anonymous access types | |
20366 | ||
20367 | @geindex Convention for anonymous access types | |
20368 | ||
20369 | The RM is not entirely clear on convention handling in a number of cases, | |
20370 | and in particular, it is not clear on the convention to be given to | |
20371 | anonymous access types in general, and in particular what is to be | |
20372 | done for the case of anonymous access-to-subprogram. | |
20373 | ||
20374 | In GNAT, we decide that if an explicit Convention is applied | |
20375 | to an object or component, and its type is such an anonymous type, | |
20376 | then the convention will apply to this anonymous type as well. This | |
20377 | seems to make sense since it is anomolous in any case to have a | |
20378 | different convention for an object and its type, and there is clearly | |
20379 | no way to explicitly specify a convention for an anonymous type, since | |
20380 | it doesn’t have a name to specify! | |
20381 | ||
20382 | Furthermore, we decide that if a convention is applied to a record type, | |
20383 | then this convention is inherited by any of its components that are of an | |
20384 | anonymous access type which do not have an explicitly specified convention. | |
20385 | ||
20386 | The following program shows these conventions in action: | |
20387 | ||
20388 | @example | |
20389 | package ConvComp is | |
20390 | type Foo is range 1 .. 10; | |
20391 | type T1 is record | |
20392 | A : access function (X : Foo) return Integer; | |
20393 | B : Integer; | |
20394 | end record; | |
20395 | pragma Convention (C, T1); | |
20396 | ||
20397 | type T2 is record | |
20398 | A : access function (X : Foo) return Integer; | |
20399 | pragma Convention (C, A); | |
20400 | B : Integer; | |
20401 | end record; | |
20402 | pragma Convention (COBOL, T2); | |
20403 | ||
20404 | type T3 is record | |
20405 | A : access function (X : Foo) return Integer; | |
20406 | pragma Convention (COBOL, A); | |
20407 | B : Integer; | |
20408 | end record; | |
20409 | pragma Convention (C, T3); | |
20410 | ||
20411 | type T4 is record | |
20412 | A : access function (X : Foo) return Integer; | |
20413 | B : Integer; | |
20414 | end record; | |
20415 | pragma Convention (COBOL, T4); | |
20416 | ||
20417 | function F (X : Foo) return Integer; | |
20418 | pragma Convention (C, F); | |
20419 | ||
20420 | function F (X : Foo) return Integer is (13); | |
20421 | ||
20422 | TV1 : T1 := (F'Access, 12); -- OK | |
20423 | TV2 : T2 := (F'Access, 13); -- OK | |
20424 | ||
20425 | TV3 : T3 := (F'Access, 13); -- ERROR | |
20426 | | | |
20427 | >>> subprogram "F" has wrong convention | |
20428 | >>> does not match access to subprogram declared at line 17 | |
20429 | 38. TV4 : T4 := (F'Access, 13); -- ERROR | |
20430 | | | |
20431 | >>> subprogram "F" has wrong convention | |
20432 | >>> does not match access to subprogram declared at line 24 | |
20433 | 39. end ConvComp; | |
20434 | @end example | |
20435 | ||
20436 | @node Determining the Representations chosen by GNAT,,Conventions and Anonymous Access Types,Representation Clauses and Pragmas | |
04d6c745 | 20437 | @anchor{gnat_rm/representation_clauses_and_pragmas determining-the-representations-chosen-by-gnat}@anchor{2a6}@anchor{gnat_rm/representation_clauses_and_pragmas id20}@anchor{2a7} |
64d5610f ML |
20438 | @section Determining the Representations chosen by GNAT |
20439 | ||
20440 | ||
20441 | @geindex Representation | |
20442 | @geindex determination of | |
20443 | ||
20444 | @geindex -gnatR (gcc) | |
20445 | ||
20446 | Although the descriptions in this section are intended to be complete, it is | |
20447 | often easier to simply experiment to see what GNAT accepts and what the | |
20448 | effect is on the layout of types and objects. | |
20449 | ||
20450 | As required by the Ada RM, if a representation clause is not accepted, then | |
20451 | it must be rejected as illegal by the compiler. However, when a | |
20452 | representation clause or pragma is accepted, there can still be questions | |
20453 | of what the compiler actually does. For example, if a partial record | |
20454 | representation clause specifies the location of some components and not | |
20455 | others, then where are the non-specified components placed? Or if pragma | |
20456 | @code{Pack} is used on a record, then exactly where are the resulting | |
20457 | fields placed? The section on pragma @code{Pack} in this chapter can be | |
20458 | used to answer the second question, but it is often easier to just see | |
20459 | what the compiler does. | |
20460 | ||
20461 | For this purpose, GNAT provides the option `-gnatR'. If you compile | |
20462 | with this option, then the compiler will output information on the actual | |
20463 | representations chosen, in a format similar to source representation | |
20464 | clauses. For example, if we compile the package: | |
20465 | ||
20466 | @example | |
20467 | package q is | |
20468 | type r (x : boolean) is tagged record | |
20469 | case x is | |
20470 | when True => S : String (1 .. 100); | |
20471 | when False => null; | |
20472 | end case; | |
20473 | end record; | |
20474 | ||
20475 | type r2 is new r (false) with record | |
20476 | y2 : integer; | |
20477 | end record; | |
20478 | ||
20479 | for r2 use record | |
20480 | y2 at 16 range 0 .. 31; | |
20481 | end record; | |
20482 | ||
20483 | type x is record | |
20484 | y : character; | |
20485 | end record; | |
20486 | ||
20487 | type x1 is array (1 .. 10) of x; | |
20488 | for x1'component_size use 11; | |
20489 | ||
20490 | type ia is access integer; | |
20491 | ||
20492 | type Rb1 is array (1 .. 13) of Boolean; | |
20493 | pragma Pack (rb1); | |
20494 | ||
20495 | type Rb2 is array (1 .. 65) of Boolean; | |
20496 | pragma Pack (rb2); | |
20497 | ||
20498 | type x2 is record | |
20499 | l1 : Boolean; | |
20500 | l2 : Duration; | |
20501 | l3 : Float; | |
20502 | l4 : Boolean; | |
20503 | l5 : Rb1; | |
20504 | l6 : Rb2; | |
20505 | end record; | |
20506 | pragma Pack (x2); | |
20507 | end q; | |
20508 | @end example | |
20509 | ||
20510 | using the switch `-gnatR' we obtain the following output: | |
20511 | ||
20512 | @example | |
20513 | Representation information for unit q | |
20514 | ------------------------------------- | |
20515 | ||
20516 | for r'Size use ??; | |
20517 | for r'Alignment use 4; | |
20518 | for r use record | |
20519 | x at 4 range 0 .. 7; | |
20520 | _tag at 0 range 0 .. 31; | |
20521 | s at 5 range 0 .. 799; | |
20522 | end record; | |
20523 | ||
20524 | for r2'Size use 160; | |
20525 | for r2'Alignment use 4; | |
20526 | for r2 use record | |
20527 | x at 4 range 0 .. 7; | |
20528 | _tag at 0 range 0 .. 31; | |
20529 | _parent at 0 range 0 .. 63; | |
20530 | y2 at 16 range 0 .. 31; | |
20531 | end record; | |
20532 | ||
20533 | for x'Size use 8; | |
20534 | for x'Alignment use 1; | |
20535 | for x use record | |
20536 | y at 0 range 0 .. 7; | |
20537 | end record; | |
20538 | ||
20539 | for x1'Size use 112; | |
20540 | for x1'Alignment use 1; | |
20541 | for x1'Component_Size use 11; | |
20542 | ||
20543 | for rb1'Size use 13; | |
20544 | for rb1'Alignment use 2; | |
20545 | for rb1'Component_Size use 1; | |
20546 | ||
20547 | for rb2'Size use 72; | |
20548 | for rb2'Alignment use 1; | |
20549 | for rb2'Component_Size use 1; | |
20550 | ||
20551 | for x2'Size use 224; | |
20552 | for x2'Alignment use 4; | |
20553 | for x2 use record | |
20554 | l1 at 0 range 0 .. 0; | |
20555 | l2 at 0 range 1 .. 64; | |
20556 | l3 at 12 range 0 .. 31; | |
20557 | l4 at 16 range 0 .. 0; | |
20558 | l5 at 16 range 1 .. 13; | |
20559 | l6 at 18 range 0 .. 71; | |
20560 | end record; | |
20561 | @end example | |
20562 | ||
20563 | The Size values are actually the Object_Size, i.e., the default size that | |
20564 | will be allocated for objects of the type. | |
20565 | The @code{??} size for type r indicates that we have a variant record, and the | |
20566 | actual size of objects will depend on the discriminant value. | |
20567 | ||
20568 | The Alignment values show the actual alignment chosen by the compiler | |
20569 | for each record or array type. | |
20570 | ||
20571 | The record representation clause for type r shows where all fields | |
20572 | are placed, including the compiler generated tag field (whose location | |
20573 | cannot be controlled by the programmer). | |
20574 | ||
20575 | The record representation clause for the type extension r2 shows all the | |
20576 | fields present, including the parent field, which is a copy of the fields | |
20577 | of the parent type of r2, i.e., r1. | |
20578 | ||
20579 | The component size and size clauses for types rb1 and rb2 show | |
20580 | the exact effect of pragma @code{Pack} on these arrays, and the record | |
20581 | representation clause for type x2 shows how pragma @cite{Pack} affects | |
20582 | this record type. | |
20583 | ||
20584 | In some cases, it may be useful to cut and paste the representation clauses | |
20585 | generated by the compiler into the original source to fix and guarantee | |
20586 | the actual representation to be used. | |
20587 | ||
20588 | @node Standard Library Routines,The Implementation of Standard I/O,Representation Clauses and Pragmas,Top | |
04d6c745 | 20589 | @anchor{gnat_rm/standard_library_routines doc}@anchor{2a8}@anchor{gnat_rm/standard_library_routines id1}@anchor{2a9}@anchor{gnat_rm/standard_library_routines standard-library-routines}@anchor{e} |
64d5610f ML |
20590 | @chapter Standard Library Routines |
20591 | ||
20592 | ||
20593 | The Ada Reference Manual contains in Annex A a full description of an | |
20594 | extensive set of standard library routines that can be used in any Ada | |
20595 | program, and which must be provided by all Ada compilers. They are | |
20596 | analogous to the standard C library used by C programs. | |
20597 | ||
20598 | GNAT implements all of the facilities described in annex A, and for most | |
20599 | purposes the description in the Ada Reference Manual, or appropriate Ada | |
20600 | text book, will be sufficient for making use of these facilities. | |
20601 | ||
20602 | In the case of the input-output facilities, | |
20603 | @ref{f,,The Implementation of Standard I/O}, | |
20604 | gives details on exactly how GNAT interfaces to the | |
20605 | file system. For the remaining packages, the Ada Reference Manual | |
20606 | should be sufficient. The following is a list of the packages included, | |
20607 | together with a brief description of the functionality that is provided. | |
20608 | ||
20609 | For completeness, references are included to other predefined library | |
20610 | routines defined in other sections of the Ada Reference Manual (these are | |
20611 | cross-indexed from Annex A). For further details see the relevant | |
20612 | package declarations in the run-time library. In particular, a few units | |
20613 | are not implemented, as marked by the presence of pragma Unimplemented_Unit, | |
20614 | and in this case the package declaration contains comments explaining why | |
20615 | the unit is not implemented. | |
20616 | ||
20617 | ||
20618 | @table @asis | |
20619 | ||
20620 | @item @code{Ada} `(A.2)' | |
20621 | ||
20622 | This is a parent package for all the standard library packages. It is | |
20623 | usually included implicitly in your program, and itself contains no | |
20624 | useful data or routines. | |
20625 | ||
20626 | @item @code{Ada.Assertions} `(11.4.2)' | |
20627 | ||
20628 | @code{Assertions} provides the @code{Assert} subprograms, and also | |
20629 | the declaration of the @code{Assertion_Error} exception. | |
20630 | ||
20631 | @item @code{Ada.Asynchronous_Task_Control} `(D.11)' | |
20632 | ||
20633 | @code{Asynchronous_Task_Control} provides low level facilities for task | |
20634 | synchronization. It is typically not implemented. See package spec for details. | |
20635 | ||
20636 | @item @code{Ada.Calendar} `(9.6)' | |
20637 | ||
20638 | @code{Calendar} provides time of day access, and routines for | |
20639 | manipulating times and durations. | |
20640 | ||
20641 | @item @code{Ada.Calendar.Arithmetic} `(9.6.1)' | |
20642 | ||
20643 | This package provides additional arithmetic | |
20644 | operations for @code{Calendar}. | |
20645 | ||
20646 | @item @code{Ada.Calendar.Formatting} `(9.6.1)' | |
20647 | ||
20648 | This package provides formatting operations for @code{Calendar}. | |
20649 | ||
20650 | @item @code{Ada.Calendar.Time_Zones} `(9.6.1)' | |
20651 | ||
20652 | This package provides additional @code{Calendar} facilities | |
20653 | for handling time zones. | |
20654 | ||
20655 | @item @code{Ada.Characters} `(A.3.1)' | |
20656 | ||
20657 | This is a dummy parent package that contains no useful entities | |
20658 | ||
20659 | @item @code{Ada.Characters.Conversions} `(A.3.2)' | |
20660 | ||
20661 | This package provides character conversion functions. | |
20662 | ||
20663 | @item @code{Ada.Characters.Handling} `(A.3.2)' | |
20664 | ||
20665 | This package provides some basic character handling capabilities, | |
20666 | including classification functions for classes of characters (e.g., test | |
20667 | for letters, or digits). | |
20668 | ||
20669 | @item @code{Ada.Characters.Latin_1} `(A.3.3)' | |
20670 | ||
20671 | This package includes a complete set of definitions of the characters | |
20672 | that appear in type CHARACTER. It is useful for writing programs that | |
20673 | will run in international environments. For example, if you want an | |
20674 | upper case E with an acute accent in a string, it is often better to use | |
20675 | the definition of @code{UC_E_Acute} in this package. Then your program | |
20676 | will print in an understandable manner even if your environment does not | |
20677 | support these extended characters. | |
20678 | ||
20679 | @item @code{Ada.Command_Line} `(A.15)' | |
20680 | ||
20681 | This package provides access to the command line parameters and the name | |
20682 | of the current program (analogous to the use of @code{argc} and @code{argv} | |
20683 | in C), and also allows the exit status for the program to be set in a | |
20684 | system-independent manner. | |
20685 | ||
20686 | @item @code{Ada.Complex_Text_IO} `(G.1.3)' | |
20687 | ||
20688 | This package provides text input and output of complex numbers. | |
20689 | ||
20690 | @item @code{Ada.Containers} `(A.18.1)' | |
20691 | ||
20692 | A top level package providing a few basic definitions used by all the | |
20693 | following specific child packages that provide specific kinds of | |
20694 | containers. | |
20695 | @end table | |
20696 | ||
20697 | @code{Ada.Containers.Bounded_Priority_Queues} `(A.18.31)' | |
20698 | ||
20699 | @code{Ada.Containers.Bounded_Synchronized_Queues} `(A.18.29)' | |
20700 | ||
20701 | @code{Ada.Containers.Doubly_Linked_Lists} `(A.18.3)' | |
20702 | ||
20703 | @code{Ada.Containers.Generic_Array_Sort} `(A.18.26)' | |
20704 | ||
20705 | @code{Ada.Containers.Generic_Constrained_Array_Sort} `(A.18.26)' | |
20706 | ||
20707 | @code{Ada.Containers.Generic_Sort} `(A.18.26)' | |
20708 | ||
20709 | @code{Ada.Containers.Hashed_Maps} `(A.18.5)' | |
20710 | ||
20711 | @code{Ada.Containers.Hashed_Sets} `(A.18.8)' | |
20712 | ||
20713 | @code{Ada.Containers.Indefinite_Doubly_Linked_Lists} `(A.18.12)' | |
20714 | ||
20715 | @code{Ada.Containers.Indefinite_Hashed_Maps} `(A.18.13)' | |
20716 | ||
20717 | @code{Ada.Containers.Indefinite_Hashed_Sets} `(A.18.15)' | |
20718 | ||
20719 | @code{Ada.Containers.Indefinite_Holders} `(A.18.18)' | |
20720 | ||
20721 | @code{Ada.Containers.Indefinite_Multiway_Trees} `(A.18.17)' | |
20722 | ||
20723 | @code{Ada.Containers.Indefinite_Ordered_Maps} `(A.18.14)' | |
20724 | ||
20725 | @code{Ada.Containers.Indefinite_Ordered_Sets} `(A.18.16)' | |
20726 | ||
20727 | @code{Ada.Containers.Indefinite_Vectors} `(A.18.11)' | |
20728 | ||
20729 | @code{Ada.Containers.Multiway_Trees} `(A.18.10)' | |
20730 | ||
20731 | @code{Ada.Containers.Ordered_Maps} `(A.18.6)' | |
20732 | ||
20733 | @code{Ada.Containers.Ordered_Sets} `(A.18.9)' | |
20734 | ||
20735 | @code{Ada.Containers.Synchronized_Queue_Interfaces} `(A.18.27)' | |
20736 | ||
20737 | @code{Ada.Containers.Unbounded_Priority_Queues} `(A.18.30)' | |
20738 | ||
20739 | @code{Ada.Containers.Unbounded_Synchronized_Queues} `(A.18.28)' | |
20740 | ||
20741 | @code{Ada.Containers.Vectors} `(A.18.2)' | |
20742 | ||
20743 | ||
20744 | @table @asis | |
20745 | ||
20746 | @item @code{Ada.Directories} `(A.16)' | |
20747 | ||
20748 | This package provides operations on directories. | |
20749 | ||
20750 | @item @code{Ada.Directories.Hierarchical_File_Names} `(A.16.1)' | |
20751 | ||
20752 | This package provides additional directory operations handling | |
20753 | hierarchical file names. | |
20754 | ||
20755 | @item @code{Ada.Directories.Information} `(A.16)' | |
20756 | ||
20757 | This is an implementation defined package for additional directory | |
20758 | operations, which is not implemented in GNAT. | |
20759 | ||
20760 | @item @code{Ada.Decimal} `(F.2)' | |
20761 | ||
20762 | This package provides constants describing the range of decimal numbers | |
20763 | implemented, and also a decimal divide routine (analogous to the COBOL | |
20764 | verb DIVIDE … GIVING … REMAINDER …) | |
20765 | ||
20766 | @item @code{Ada.Direct_IO} `(A.8.4)' | |
20767 | ||
20768 | This package provides input-output using a model of a set of records of | |
20769 | fixed-length, containing an arbitrary definite Ada type, indexed by an | |
20770 | integer record number. | |
20771 | ||
20772 | @item @code{Ada.Dispatching} `(D.2.1)' | |
20773 | ||
20774 | A parent package containing definitions for task dispatching operations. | |
20775 | ||
20776 | @item @code{Ada.Dispatching.EDF} `(D.2.6)' | |
20777 | ||
20778 | Not implemented in GNAT. | |
20779 | ||
20780 | @item @code{Ada.Dispatching.Non_Preemptive} `(D.2.4)' | |
20781 | ||
20782 | Not implemented in GNAT. | |
20783 | ||
20784 | @item @code{Ada.Dispatching.Round_Robin} `(D.2.5)' | |
20785 | ||
20786 | Not implemented in GNAT. | |
20787 | ||
20788 | @item @code{Ada.Dynamic_Priorities} `(D.5)' | |
20789 | ||
20790 | This package allows the priorities of a task to be adjusted dynamically | |
20791 | as the task is running. | |
20792 | ||
20793 | @item @code{Ada.Environment_Variables} `(A.17)' | |
20794 | ||
20795 | This package provides facilities for accessing environment variables. | |
20796 | ||
20797 | @item @code{Ada.Exceptions} `(11.4.1)' | |
20798 | ||
20799 | This package provides additional information on exceptions, and also | |
20800 | contains facilities for treating exceptions as data objects, and raising | |
20801 | exceptions with associated messages. | |
20802 | ||
20803 | @item @code{Ada.Execution_Time} `(D.14)' | |
20804 | ||
20805 | This package provides CPU clock functionalities. It is not implemented on | |
20806 | all targets (see package spec for details). | |
20807 | ||
20808 | @item @code{Ada.Execution_Time.Group_Budgets} `(D.14.2)' | |
20809 | ||
20810 | Not implemented in GNAT. | |
20811 | ||
20812 | @item @code{Ada.Execution_Time.Timers} `(D.14.1)’' | |
20813 | ||
20814 | Not implemented in GNAT. | |
20815 | ||
20816 | @item @code{Ada.Finalization} `(7.6)' | |
20817 | ||
20818 | This package contains the declarations and subprograms to support the | |
20819 | use of controlled types, providing for automatic initialization and | |
20820 | finalization (analogous to the constructors and destructors of C++). | |
20821 | ||
20822 | @item @code{Ada.Float_Text_IO} `(A.10.9)' | |
20823 | ||
20824 | A library level instantiation of Text_IO.Float_IO for type Float. | |
20825 | ||
20826 | @item @code{Ada.Float_Wide_Text_IO} `(A.10.9)' | |
20827 | ||
20828 | A library level instantiation of Wide_Text_IO.Float_IO for type Float. | |
20829 | ||
20830 | @item @code{Ada.Float_Wide_Wide_Text_IO} `(A.10.9)' | |
20831 | ||
20832 | A library level instantiation of Wide_Wide_Text_IO.Float_IO for type Float. | |
20833 | ||
20834 | @item @code{Ada.Integer_Text_IO} `(A.10.9)' | |
20835 | ||
20836 | A library level instantiation of Text_IO.Integer_IO for type Integer. | |
20837 | ||
20838 | @item @code{Ada.Integer_Wide_Text_IO} `(A.10.9)' | |
20839 | ||
20840 | A library level instantiation of Wide_Text_IO.Integer_IO for type Integer. | |
20841 | ||
20842 | @item @code{Ada.Integer_Wide_Wide_Text_IO} `(A.10.9)' | |
20843 | ||
20844 | A library level instantiation of Wide_Wide_Text_IO.Integer_IO for type Integer. | |
20845 | ||
20846 | @item @code{Ada.Interrupts} `(C.3.2)' | |
20847 | ||
20848 | This package provides facilities for interfacing to interrupts, which | |
20849 | includes the set of signals or conditions that can be raised and | |
20850 | recognized as interrupts. | |
20851 | ||
20852 | @item @code{Ada.Interrupts.Names} `(C.3.2)' | |
20853 | ||
20854 | This package provides the set of interrupt names (actually signal | |
20855 | or condition names) that can be handled by GNAT. | |
20856 | ||
20857 | @item @code{Ada.IO_Exceptions} `(A.13)' | |
20858 | ||
20859 | This package defines the set of exceptions that can be raised by use of | |
20860 | the standard IO packages. | |
20861 | ||
20862 | @item @code{Ada.Iterator_Interfaces} `(5.5.1)' | |
20863 | ||
20864 | This package provides a generic interface to generalized iterators. | |
20865 | ||
20866 | @item @code{Ada.Locales} `(A.19)' | |
20867 | ||
20868 | This package provides declarations providing information (Language | |
20869 | and Country) about the current locale. | |
20870 | ||
20871 | @item @code{Ada.Numerics} | |
20872 | ||
20873 | This package contains some standard constants and exceptions used | |
20874 | throughout the numerics packages. Note that the constants pi and e are | |
20875 | defined here, and it is better to use these definitions than rolling | |
20876 | your own. | |
20877 | ||
20878 | @item @code{Ada.Numerics.Complex_Arrays} `(G.3.2)' | |
20879 | ||
20880 | Provides operations on arrays of complex numbers. | |
20881 | ||
20882 | @item @code{Ada.Numerics.Complex_Elementary_Functions} | |
20883 | ||
20884 | Provides the implementation of standard elementary functions (such as | |
20885 | log and trigonometric functions) operating on complex numbers using the | |
20886 | standard @code{Float} and the @code{Complex} and @code{Imaginary} types | |
20887 | created by the package @code{Numerics.Complex_Types}. | |
20888 | ||
20889 | @item @code{Ada.Numerics.Complex_Types} | |
20890 | ||
20891 | This is a predefined instantiation of | |
20892 | @code{Numerics.Generic_Complex_Types} using @code{Standard.Float} to | |
20893 | build the type @code{Complex} and @code{Imaginary}. | |
20894 | ||
20895 | @item @code{Ada.Numerics.Discrete_Random} | |
20896 | ||
20897 | This generic package provides a random number generator suitable for generating | |
20898 | uniformly distributed values of a specified discrete subtype. | |
20899 | ||
20900 | @item @code{Ada.Numerics.Float_Random} | |
20901 | ||
20902 | This package provides a random number generator suitable for generating | |
20903 | uniformly distributed floating point values in the unit interval. | |
20904 | ||
20905 | @item @code{Ada.Numerics.Generic_Complex_Elementary_Functions} | |
20906 | ||
20907 | This is a generic version of the package that provides the | |
20908 | implementation of standard elementary functions (such as log and | |
20909 | trigonometric functions) for an arbitrary complex type. | |
20910 | ||
20911 | The following predefined instantiations of this package are provided: | |
20912 | ||
20913 | ||
20914 | @itemize * | |
20915 | ||
20916 | @item | |
20917 | @code{Short_Float} | |
20918 | ||
20919 | @code{Ada.Numerics.Short_Complex_Elementary_Functions} | |
20920 | ||
20921 | @item | |
20922 | @code{Float} | |
20923 | ||
20924 | @code{Ada.Numerics.Complex_Elementary_Functions} | |
20925 | ||
20926 | @item | |
20927 | @code{Long_Float} | |
20928 | ||
20929 | @code{Ada.Numerics.Long_Complex_Elementary_Functions} | |
20930 | @end itemize | |
20931 | ||
20932 | @item @code{Ada.Numerics.Generic_Complex_Types} | |
20933 | ||
20934 | This is a generic package that allows the creation of complex types, | |
20935 | with associated complex arithmetic operations. | |
20936 | ||
20937 | The following predefined instantiations of this package exist | |
20938 | ||
20939 | ||
20940 | @itemize * | |
20941 | ||
20942 | @item | |
20943 | @code{Short_Float} | |
20944 | ||
20945 | @code{Ada.Numerics.Short_Complex_Complex_Types} | |
20946 | ||
20947 | @item | |
20948 | @code{Float} | |
20949 | ||
20950 | @code{Ada.Numerics.Complex_Complex_Types} | |
20951 | ||
20952 | @item | |
20953 | @code{Long_Float} | |
20954 | ||
20955 | @code{Ada.Numerics.Long_Complex_Complex_Types} | |
20956 | @end itemize | |
20957 | ||
20958 | @item @code{Ada.Numerics.Generic_Elementary_Functions} | |
20959 | ||
20960 | This is a generic package that provides the implementation of standard | |
20961 | elementary functions (such as log an trigonometric functions) for an | |
20962 | arbitrary float type. | |
20963 | ||
20964 | The following predefined instantiations of this package exist | |
20965 | ||
20966 | ||
20967 | @itemize * | |
20968 | ||
20969 | @item | |
20970 | @code{Short_Float} | |
20971 | ||
20972 | @code{Ada.Numerics.Short_Elementary_Functions} | |
20973 | ||
20974 | @item | |
20975 | @code{Float} | |
20976 | ||
20977 | @code{Ada.Numerics.Elementary_Functions} | |
20978 | ||
20979 | @item | |
20980 | @code{Long_Float} | |
20981 | ||
20982 | @code{Ada.Numerics.Long_Elementary_Functions} | |
20983 | @end itemize | |
20984 | ||
20985 | @item @code{Ada.Numerics.Generic_Real_Arrays} `(G.3.1)' | |
20986 | ||
20987 | Generic operations on arrays of reals | |
20988 | ||
20989 | @item @code{Ada.Numerics.Real_Arrays} `(G.3.1)' | |
20990 | ||
20991 | Preinstantiation of Ada.Numerics.Generic_Real_Arrays (Float). | |
20992 | ||
20993 | @item @code{Ada.Real_Time} `(D.8)' | |
20994 | ||
20995 | This package provides facilities similar to those of @code{Calendar}, but | |
20996 | operating with a finer clock suitable for real time control. Note that | |
20997 | annex D requires that there be no backward clock jumps, and GNAT generally | |
20998 | guarantees this behavior, but of course if the external clock on which | |
20999 | the GNAT runtime depends is deliberately reset by some external event, | |
21000 | then such a backward jump may occur. | |
21001 | ||
21002 | @item @code{Ada.Real_Time.Timing_Events} `(D.15)' | |
21003 | ||
21004 | Not implemented in GNAT. | |
21005 | ||
21006 | @item @code{Ada.Sequential_IO} `(A.8.1)' | |
21007 | ||
21008 | This package provides input-output facilities for sequential files, | |
21009 | which can contain a sequence of values of a single type, which can be | |
21010 | any Ada type, including indefinite (unconstrained) types. | |
21011 | ||
21012 | @item @code{Ada.Storage_IO} `(A.9)' | |
21013 | ||
21014 | This package provides a facility for mapping arbitrary Ada types to and | |
21015 | from a storage buffer. It is primarily intended for the creation of new | |
21016 | IO packages. | |
21017 | ||
21018 | @item @code{Ada.Streams} `(13.13.1)' | |
21019 | ||
21020 | This is a generic package that provides the basic support for the | |
21021 | concept of streams as used by the stream attributes (@code{Input}, | |
21022 | @code{Output}, @code{Read} and @code{Write}). | |
21023 | ||
21024 | @item @code{Ada.Streams.Stream_IO} `(A.12.1)' | |
21025 | ||
21026 | This package is a specialization of the type @code{Streams} defined in | |
21027 | package @code{Streams} together with a set of operations providing | |
21028 | Stream_IO capability. The Stream_IO model permits both random and | |
21029 | sequential access to a file which can contain an arbitrary set of values | |
21030 | of one or more Ada types. | |
21031 | ||
21032 | @item @code{Ada.Strings} `(A.4.1)' | |
21033 | ||
21034 | This package provides some basic constants used by the string handling | |
21035 | packages. | |
21036 | ||
21037 | @item @code{Ada.Strings.Bounded} `(A.4.4)' | |
21038 | ||
21039 | This package provides facilities for handling variable length | |
21040 | strings. The bounded model requires a maximum length. It is thus | |
21041 | somewhat more limited than the unbounded model, but avoids the use of | |
21042 | dynamic allocation or finalization. | |
21043 | ||
21044 | @item @code{Ada.Strings.Bounded.Equal_Case_Insensitive} `(A.4.10)' | |
21045 | ||
21046 | Provides case-insensitive comparisons of bounded strings | |
21047 | ||
21048 | @item @code{Ada.Strings.Bounded.Hash} `(A.4.9)' | |
21049 | ||
21050 | This package provides a generic hash function for bounded strings | |
21051 | ||
21052 | @item @code{Ada.Strings.Bounded.Hash_Case_Insensitive} `(A.4.9)' | |
21053 | ||
21054 | This package provides a generic hash function for bounded strings that | |
21055 | converts the string to be hashed to lower case. | |
21056 | ||
21057 | @item @code{Ada.Strings.Bounded.Less_Case_Insensitive} `(A.4.10)' | |
21058 | ||
21059 | This package provides a comparison function for bounded strings that works | |
21060 | in a case insensitive manner by converting to lower case before the comparison. | |
21061 | ||
21062 | @item @code{Ada.Strings.Fixed} `(A.4.3)' | |
21063 | ||
21064 | This package provides facilities for handling fixed length strings. | |
21065 | ||
21066 | @item @code{Ada.Strings.Fixed.Equal_Case_Insensitive} `(A.4.10)' | |
21067 | ||
21068 | This package provides an equality function for fixed strings that compares | |
21069 | the strings after converting both to lower case. | |
21070 | ||
21071 | @item @code{Ada.Strings.Fixed.Hash_Case_Insensitive} `(A.4.9)' | |
21072 | ||
21073 | This package provides a case insensitive hash function for fixed strings that | |
21074 | converts the string to lower case before computing the hash. | |
21075 | ||
21076 | @item @code{Ada.Strings.Fixed.Less_Case_Insensitive} `(A.4.10)' | |
21077 | ||
21078 | This package provides a comparison function for fixed strings that works | |
21079 | in a case insensitive manner by converting to lower case before the comparison. | |
21080 | ||
21081 | @item @code{Ada.Strings.Hash} `(A.4.9)' | |
21082 | ||
21083 | This package provides a hash function for strings. | |
21084 | ||
21085 | @item @code{Ada.Strings.Hash_Case_Insensitive} `(A.4.9)' | |
21086 | ||
21087 | This package provides a hash function for strings that is case insensitive. | |
21088 | The string is converted to lower case before computing the hash. | |
21089 | ||
21090 | @item @code{Ada.Strings.Less_Case_Insensitive} `(A.4.10)' | |
21091 | ||
21092 | This package provides a comparison function for\strings that works | |
21093 | in a case insensitive manner by converting to lower case before the comparison. | |
21094 | ||
21095 | @item @code{Ada.Strings.Maps} `(A.4.2)' | |
21096 | ||
21097 | This package provides facilities for handling character mappings and | |
21098 | arbitrarily defined subsets of characters. For instance it is useful in | |
21099 | defining specialized translation tables. | |
21100 | ||
21101 | @item @code{Ada.Strings.Maps.Constants} `(A.4.6)' | |
21102 | ||
21103 | This package provides a standard set of predefined mappings and | |
21104 | predefined character sets. For example, the standard upper to lower case | |
21105 | conversion table is found in this package. Note that upper to lower case | |
21106 | conversion is non-trivial if you want to take the entire set of | |
21107 | characters, including extended characters like E with an acute accent, | |
21108 | into account. You should use the mappings in this package (rather than | |
21109 | adding 32 yourself) to do case mappings. | |
21110 | ||
21111 | @item @code{Ada.Strings.Unbounded} `(A.4.5)' | |
21112 | ||
21113 | This package provides facilities for handling variable length | |
21114 | strings. The unbounded model allows arbitrary length strings, but | |
21115 | requires the use of dynamic allocation and finalization. | |
21116 | ||
21117 | @item @code{Ada.Strings.Unbounded.Equal_Case_Insensitive} `(A.4.10)' | |
21118 | ||
21119 | Provides case-insensitive comparisons of unbounded strings | |
21120 | ||
21121 | @item @code{Ada.Strings.Unbounded.Hash} `(A.4.9)' | |
21122 | ||
21123 | This package provides a generic hash function for unbounded strings | |
21124 | ||
21125 | @item @code{Ada.Strings.Unbounded.Hash_Case_Insensitive} `(A.4.9)' | |
21126 | ||
21127 | This package provides a generic hash function for unbounded strings that | |
21128 | converts the string to be hashed to lower case. | |
21129 | ||
21130 | @item @code{Ada.Strings.Unbounded.Less_Case_Insensitive} `(A.4.10)' | |
21131 | ||
21132 | This package provides a comparison function for unbounded strings that works | |
21133 | in a case insensitive manner by converting to lower case before the comparison. | |
21134 | ||
21135 | @item @code{Ada.Strings.UTF_Encoding} `(A.4.11)' | |
21136 | ||
21137 | This package provides basic definitions for dealing with UTF-encoded strings. | |
21138 | ||
21139 | @item @code{Ada.Strings.UTF_Encoding.Conversions} `(A.4.11)' | |
21140 | ||
21141 | This package provides conversion functions for UTF-encoded strings. | |
21142 | @end table | |
21143 | ||
21144 | @code{Ada.Strings.UTF_Encoding.Strings} `(A.4.11)' | |
21145 | ||
21146 | @code{Ada.Strings.UTF_Encoding.Wide_Strings} `(A.4.11)' | |
21147 | ||
21148 | ||
21149 | @table @asis | |
21150 | ||
21151 | @item @code{Ada.Strings.UTF_Encoding.Wide_Wide_Strings} `(A.4.11)' | |
21152 | ||
21153 | These packages provide facilities for handling UTF encodings for | |
21154 | Strings, Wide_Strings and Wide_Wide_Strings. | |
21155 | @end table | |
21156 | ||
21157 | @code{Ada.Strings.Wide_Bounded} `(A.4.7)' | |
21158 | ||
21159 | @code{Ada.Strings.Wide_Fixed} `(A.4.7)' | |
21160 | ||
21161 | @code{Ada.Strings.Wide_Maps} `(A.4.7)' | |
21162 | ||
21163 | ||
21164 | @table @asis | |
21165 | ||
21166 | @item @code{Ada.Strings.Wide_Unbounded} `(A.4.7)' | |
21167 | ||
21168 | These packages provide analogous capabilities to the corresponding | |
21169 | packages without @code{Wide_} in the name, but operate with the types | |
21170 | @code{Wide_String} and @code{Wide_Character} instead of @code{String} | |
21171 | and @code{Character}. Versions of all the child packages are available. | |
21172 | @end table | |
21173 | ||
21174 | @code{Ada.Strings.Wide_Wide_Bounded} `(A.4.7)' | |
21175 | ||
21176 | @code{Ada.Strings.Wide_Wide_Fixed} `(A.4.7)' | |
21177 | ||
21178 | @code{Ada.Strings.Wide_Wide_Maps} `(A.4.7)' | |
21179 | ||
21180 | ||
21181 | @table @asis | |
21182 | ||
21183 | @item @code{Ada.Strings.Wide_Wide_Unbounded} `(A.4.7)' | |
21184 | ||
21185 | These packages provide analogous capabilities to the corresponding | |
21186 | packages without @code{Wide_} in the name, but operate with the types | |
21187 | @code{Wide_Wide_String} and @code{Wide_Wide_Character} instead | |
21188 | of @code{String} and @code{Character}. | |
21189 | ||
21190 | @item @code{Ada.Synchronous_Barriers} `(D.10.1)' | |
21191 | ||
21192 | This package provides facilities for synchronizing tasks at a low level | |
21193 | with barriers. | |
21194 | ||
21195 | @item @code{Ada.Synchronous_Task_Control} `(D.10)' | |
21196 | ||
21197 | This package provides some standard facilities for controlling task | |
21198 | communication in a synchronous manner. | |
21199 | ||
21200 | @item @code{Ada.Synchronous_Task_Control.EDF} `(D.10)' | |
21201 | ||
21202 | Not implemented in GNAT. | |
21203 | ||
21204 | @item @code{Ada.Tags} | |
21205 | ||
21206 | This package contains definitions for manipulation of the tags of tagged | |
21207 | values. | |
21208 | ||
21209 | @item @code{Ada.Tags.Generic_Dispatching_Constructor} `(3.9)' | |
21210 | ||
21211 | This package provides a way of constructing tagged class-wide values given | |
21212 | only the tag value. | |
21213 | ||
21214 | @item @code{Ada.Task_Attributes} `(C.7.2)' | |
21215 | ||
21216 | This package provides the capability of associating arbitrary | |
21217 | task-specific data with separate tasks. | |
21218 | ||
21219 | @item @code{Ada.Task_Identification} `(C.7.1)' | |
21220 | ||
21221 | This package provides capabilities for task identification. | |
21222 | ||
21223 | @item @code{Ada.Task_Termination} `(C.7.3)' | |
21224 | ||
21225 | This package provides control over task termination. | |
21226 | ||
21227 | @item @code{Ada.Text_IO} | |
21228 | ||
21229 | This package provides basic text input-output capabilities for | |
21230 | character, string and numeric data. The subpackages of this | |
21231 | package are listed next. Note that although these are defined | |
21232 | as subpackages in the RM, they are actually transparently | |
21233 | implemented as child packages in GNAT, meaning that they | |
21234 | are only loaded if needed. | |
21235 | ||
21236 | @item @code{Ada.Text_IO.Decimal_IO} | |
21237 | ||
21238 | Provides input-output facilities for decimal fixed-point types | |
21239 | ||
21240 | @item @code{Ada.Text_IO.Enumeration_IO} | |
21241 | ||
21242 | Provides input-output facilities for enumeration types. | |
21243 | ||
21244 | @item @code{Ada.Text_IO.Fixed_IO} | |
21245 | ||
21246 | Provides input-output facilities for ordinary fixed-point types. | |
21247 | ||
21248 | @item @code{Ada.Text_IO.Float_IO} | |
21249 | ||
21250 | Provides input-output facilities for float types. The following | |
21251 | predefined instantiations of this generic package are available: | |
21252 | ||
21253 | ||
21254 | @itemize * | |
21255 | ||
21256 | @item | |
21257 | @code{Short_Float} | |
21258 | ||
21259 | @code{Short_Float_Text_IO} | |
21260 | ||
21261 | @item | |
21262 | @code{Float} | |
21263 | ||
21264 | @code{Float_Text_IO} | |
21265 | ||
21266 | @item | |
21267 | @code{Long_Float} | |
21268 | ||
21269 | @code{Long_Float_Text_IO} | |
21270 | @end itemize | |
21271 | ||
21272 | @item @code{Ada.Text_IO.Integer_IO} | |
21273 | ||
21274 | Provides input-output facilities for integer types. The following | |
21275 | predefined instantiations of this generic package are available: | |
21276 | ||
21277 | ||
21278 | @itemize * | |
21279 | ||
21280 | @item | |
21281 | @code{Short_Short_Integer} | |
21282 | ||
21283 | @code{Ada.Short_Short_Integer_Text_IO} | |
21284 | ||
21285 | @item | |
21286 | @code{Short_Integer} | |
21287 | ||
21288 | @code{Ada.Short_Integer_Text_IO} | |
21289 | ||
21290 | @item | |
21291 | @code{Integer} | |
21292 | ||
21293 | @code{Ada.Integer_Text_IO} | |
21294 | ||
21295 | @item | |
21296 | @code{Long_Integer} | |
21297 | ||
21298 | @code{Ada.Long_Integer_Text_IO} | |
21299 | ||
21300 | @item | |
21301 | @code{Long_Long_Integer} | |
21302 | ||
21303 | @code{Ada.Long_Long_Integer_Text_IO} | |
21304 | @end itemize | |
21305 | ||
21306 | @item @code{Ada.Text_IO.Modular_IO} | |
21307 | ||
21308 | Provides input-output facilities for modular (unsigned) types. | |
21309 | ||
21310 | @item @code{Ada.Text_IO.Bounded_IO (A.10.11)} | |
21311 | ||
21312 | Provides input-output facilities for bounded strings. | |
21313 | ||
21314 | @item @code{Ada.Text_IO.Complex_IO (G.1.3)} | |
21315 | ||
21316 | This package provides basic text input-output capabilities for complex | |
21317 | data. | |
21318 | ||
21319 | @item @code{Ada.Text_IO.Editing (F.3.3)} | |
21320 | ||
21321 | This package contains routines for edited output, analogous to the use | |
21322 | of pictures in COBOL. The picture formats used by this package are a | |
21323 | close copy of the facility in COBOL. | |
21324 | ||
21325 | @item @code{Ada.Text_IO.Text_Streams (A.12.2)} | |
21326 | ||
21327 | This package provides a facility that allows Text_IO files to be treated | |
21328 | as streams, so that the stream attributes can be used for writing | |
21329 | arbitrary data, including binary data, to Text_IO files. | |
21330 | ||
21331 | @item @code{Ada.Text_IO.Unbounded_IO (A.10.12)} | |
21332 | ||
21333 | This package provides input-output facilities for unbounded strings. | |
21334 | ||
21335 | @item @code{Ada.Unchecked_Conversion (13.9)} | |
21336 | ||
21337 | This generic package allows arbitrary conversion from one type to | |
21338 | another of the same size, providing for breaking the type safety in | |
21339 | special circumstances. | |
21340 | ||
21341 | If the types have the same Size (more accurately the same Value_Size), | |
21342 | then the effect is simply to transfer the bits from the source to the | |
21343 | target type without any modification. This usage is well defined, and | |
21344 | for simple types whose representation is typically the same across | |
21345 | all implementations, gives a portable method of performing such | |
21346 | conversions. | |
21347 | ||
21348 | If the types do not have the same size, then the result is implementation | |
21349 | defined, and thus may be non-portable. The following describes how GNAT | |
21350 | handles such unchecked conversion cases. | |
21351 | ||
21352 | If the types are of different sizes, and are both discrete types, then | |
21353 | the effect is of a normal type conversion without any constraint checking. | |
21354 | In particular if the result type has a larger size, the result will be | |
21355 | zero or sign extended. If the result type has a smaller size, the result | |
21356 | will be truncated by ignoring high order bits. | |
21357 | ||
21358 | If the types are of different sizes, and are not both discrete types, | |
21359 | then the conversion works as though pointers were created to the source | |
21360 | and target, and the pointer value is converted. The effect is that bits | |
21361 | are copied from successive low order storage units and bits of the source | |
21362 | up to the length of the target type. | |
21363 | ||
21364 | A warning is issued if the lengths differ, since the effect in this | |
21365 | case is implementation dependent, and the above behavior may not match | |
21366 | that of some other compiler. | |
21367 | ||
21368 | A pointer to one type may be converted to a pointer to another type using | |
21369 | unchecked conversion. The only case in which the effect is undefined is | |
21370 | when one or both pointers are pointers to unconstrained array types. In | |
21371 | this case, the bounds information may get incorrectly transferred, and in | |
21372 | particular, GNAT uses double size pointers for such types, and it is | |
21373 | meaningless to convert between such pointer types. GNAT will issue a | |
21374 | warning if the alignment of the target designated type is more strict | |
21375 | than the alignment of the source designated type (since the result may | |
21376 | be unaligned in this case). | |
21377 | ||
21378 | A pointer other than a pointer to an unconstrained array type may be | |
21379 | converted to and from System.Address. Such usage is common in Ada 83 | |
21380 | programs, but note that Ada.Address_To_Access_Conversions is the | |
21381 | preferred method of performing such conversions in Ada 95 and Ada 2005. | |
21382 | Neither | |
21383 | unchecked conversion nor Ada.Address_To_Access_Conversions should be | |
21384 | used in conjunction with pointers to unconstrained objects, since | |
21385 | the bounds information cannot be handled correctly in this case. | |
21386 | ||
21387 | @item @code{Ada.Unchecked_Deallocation} `(13.11.2)' | |
21388 | ||
21389 | This generic package allows explicit freeing of storage previously | |
21390 | allocated by use of an allocator. | |
21391 | ||
21392 | @item @code{Ada.Wide_Text_IO} `(A.11)' | |
21393 | ||
21394 | This package is similar to @code{Ada.Text_IO}, except that the external | |
21395 | file supports wide character representations, and the internal types are | |
21396 | @code{Wide_Character} and @code{Wide_String} instead of @code{Character} | |
21397 | and @code{String}. The corresponding set of nested packages and child | |
21398 | packages are defined. | |
21399 | ||
21400 | @item @code{Ada.Wide_Wide_Text_IO} `(A.11)' | |
21401 | ||
21402 | This package is similar to @code{Ada.Text_IO}, except that the external | |
21403 | file supports wide character representations, and the internal types are | |
21404 | @code{Wide_Character} and @code{Wide_String} instead of @code{Character} | |
21405 | and @code{String}. The corresponding set of nested packages and child | |
21406 | packages are defined. | |
21407 | @end table | |
21408 | ||
21409 | For packages in Interfaces and System, all the RM defined packages are | |
21410 | available in GNAT, see the Ada 2012 RM for full details. | |
21411 | ||
21412 | @node The Implementation of Standard I/O,The GNAT Library,Standard Library Routines,Top | |
04d6c745 | 21413 | @anchor{gnat_rm/the_implementation_of_standard_i_o doc}@anchor{2aa}@anchor{gnat_rm/the_implementation_of_standard_i_o id1}@anchor{2ab}@anchor{gnat_rm/the_implementation_of_standard_i_o the-implementation-of-standard-i-o}@anchor{f} |
64d5610f ML |
21414 | @chapter The Implementation of Standard I/O |
21415 | ||
21416 | ||
21417 | GNAT implements all the required input-output facilities described in | |
21418 | A.6 through A.14. These sections of the Ada Reference Manual describe the | |
21419 | required behavior of these packages from the Ada point of view, and if | |
21420 | you are writing a portable Ada program that does not need to know the | |
21421 | exact manner in which Ada maps to the outside world when it comes to | |
21422 | reading or writing external files, then you do not need to read this | |
21423 | chapter. As long as your files are all regular files (not pipes or | |
21424 | devices), and as long as you write and read the files only from Ada, the | |
21425 | description in the Ada Reference Manual is sufficient. | |
21426 | ||
21427 | However, if you want to do input-output to pipes or other devices, such | |
21428 | as the keyboard or screen, or if the files you are dealing with are | |
21429 | either generated by some other language, or to be read by some other | |
21430 | language, then you need to know more about the details of how the GNAT | |
21431 | implementation of these input-output facilities behaves. | |
21432 | ||
21433 | In this chapter we give a detailed description of exactly how GNAT | |
21434 | interfaces to the file system. As always, the sources of the system are | |
21435 | available to you for answering questions at an even more detailed level, | |
21436 | but for most purposes the information in this chapter will suffice. | |
21437 | ||
21438 | Another reason that you may need to know more about how input-output is | |
21439 | implemented arises when you have a program written in mixed languages | |
21440 | where, for example, files are shared between the C and Ada sections of | |
21441 | the same program. GNAT provides some additional facilities, in the form | |
21442 | of additional child library packages, that facilitate this sharing, and | |
21443 | these additional facilities are also described in this chapter. | |
21444 | ||
21445 | @menu | |
21446 | * Standard I/O Packages:: | |
21447 | * FORM Strings:: | |
21448 | * Direct_IO:: | |
21449 | * Sequential_IO:: | |
21450 | * Text_IO:: | |
21451 | * Wide_Text_IO:: | |
21452 | * Wide_Wide_Text_IO:: | |
21453 | * Stream_IO:: | |
21454 | * Text Translation:: | |
21455 | * Shared Files:: | |
21456 | * Filenames encoding:: | |
21457 | * File content encoding:: | |
21458 | * Open Modes:: | |
21459 | * Operations on C Streams:: | |
21460 | * Interfacing to C Streams:: | |
21461 | ||
21462 | @end menu | |
21463 | ||
21464 | @node Standard I/O Packages,FORM Strings,,The Implementation of Standard I/O | |
04d6c745 | 21465 | @anchor{gnat_rm/the_implementation_of_standard_i_o id2}@anchor{2ac}@anchor{gnat_rm/the_implementation_of_standard_i_o standard-i-o-packages}@anchor{2ad} |
64d5610f ML |
21466 | @section Standard I/O Packages |
21467 | ||
21468 | ||
21469 | The Standard I/O packages described in Annex A for | |
21470 | ||
21471 | ||
21472 | @itemize * | |
21473 | ||
21474 | @item | |
21475 | Ada.Text_IO | |
21476 | ||
21477 | @item | |
21478 | Ada.Text_IO.Complex_IO | |
21479 | ||
21480 | @item | |
21481 | Ada.Text_IO.Text_Streams | |
21482 | ||
21483 | @item | |
21484 | Ada.Wide_Text_IO | |
21485 | ||
21486 | @item | |
21487 | Ada.Wide_Text_IO.Complex_IO | |
21488 | ||
21489 | @item | |
21490 | Ada.Wide_Text_IO.Text_Streams | |
21491 | ||
21492 | @item | |
21493 | Ada.Wide_Wide_Text_IO | |
21494 | ||
21495 | @item | |
21496 | Ada.Wide_Wide_Text_IO.Complex_IO | |
21497 | ||
21498 | @item | |
21499 | Ada.Wide_Wide_Text_IO.Text_Streams | |
21500 | ||
21501 | @item | |
21502 | Ada.Stream_IO | |
21503 | ||
21504 | @item | |
21505 | Ada.Sequential_IO | |
21506 | ||
21507 | @item | |
21508 | Ada.Direct_IO | |
21509 | @end itemize | |
21510 | ||
21511 | are implemented using the C | |
21512 | library streams facility; where | |
21513 | ||
21514 | ||
21515 | @itemize * | |
21516 | ||
21517 | @item | |
21518 | All files are opened using @code{fopen}. | |
21519 | ||
21520 | @item | |
21521 | All input/output operations use @code{fread}/@cite{fwrite}. | |
21522 | @end itemize | |
21523 | ||
21524 | There is no internal buffering of any kind at the Ada library level. The only | |
21525 | buffering is that provided at the system level in the implementation of the | |
21526 | library routines that support streams. This facilitates shared use of these | |
21527 | streams by mixed language programs. Note though that system level buffering is | |
21528 | explicitly enabled at elaboration of the standard I/O packages and that can | |
21529 | have an impact on mixed language programs, in particular those using I/O before | |
21530 | calling the Ada elaboration routine (e.g., adainit). It is recommended to call | |
21531 | the Ada elaboration routine before performing any I/O or when impractical, | |
21532 | flush the common I/O streams and in particular Standard_Output before | |
21533 | elaborating the Ada code. | |
21534 | ||
21535 | @node FORM Strings,Direct_IO,Standard I/O Packages,The Implementation of Standard I/O | |
04d6c745 | 21536 | @anchor{gnat_rm/the_implementation_of_standard_i_o form-strings}@anchor{2ae}@anchor{gnat_rm/the_implementation_of_standard_i_o id3}@anchor{2af} |
64d5610f ML |
21537 | @section FORM Strings |
21538 | ||
21539 | ||
21540 | The format of a FORM string in GNAT is: | |
21541 | ||
21542 | @example | |
21543 | "keyword=value,keyword=value,...,keyword=value" | |
21544 | @end example | |
21545 | ||
21546 | where letters may be in upper or lower case, and there are no spaces | |
21547 | between values. The order of the entries is not important. Currently | |
21548 | the following keywords defined. | |
21549 | ||
21550 | @example | |
21551 | TEXT_TRANSLATION=[YES|NO|TEXT|BINARY|U8TEXT|WTEXT|U16TEXT] | |
21552 | SHARED=[YES|NO] | |
21553 | WCEM=[n|h|u|s|e|8|b] | |
21554 | ENCODING=[UTF8|8BITS] | |
21555 | @end example | |
21556 | ||
21557 | The use of these parameters is described later in this section. If an | |
21558 | unrecognized keyword appears in a form string, it is silently ignored | |
21559 | and not considered invalid. | |
21560 | ||
21561 | @node Direct_IO,Sequential_IO,FORM Strings,The Implementation of Standard I/O | |
04d6c745 | 21562 | @anchor{gnat_rm/the_implementation_of_standard_i_o direct-io}@anchor{2b0}@anchor{gnat_rm/the_implementation_of_standard_i_o id4}@anchor{2b1} |
64d5610f ML |
21563 | @section Direct_IO |
21564 | ||
21565 | ||
21566 | Direct_IO can only be instantiated for definite types. This is a | |
21567 | restriction of the Ada language, which means that the records are fixed | |
21568 | length (the length being determined by @code{type'Size}, rounded | |
21569 | up to the next storage unit boundary if necessary). | |
21570 | ||
21571 | The records of a Direct_IO file are simply written to the file in index | |
21572 | sequence, with the first record starting at offset zero, and subsequent | |
21573 | records following. There is no control information of any kind. For | |
21574 | example, if 32-bit integers are being written, each record takes | |
21575 | 4-bytes, so the record at index @code{K} starts at offset | |
21576 | (@code{K}-1)*4. | |
21577 | ||
21578 | There is no limit on the size of Direct_IO files, they are expanded as | |
21579 | necessary to accommodate whatever records are written to the file. | |
21580 | ||
21581 | @node Sequential_IO,Text_IO,Direct_IO,The Implementation of Standard I/O | |
04d6c745 | 21582 | @anchor{gnat_rm/the_implementation_of_standard_i_o id5}@anchor{2b2}@anchor{gnat_rm/the_implementation_of_standard_i_o sequential-io}@anchor{2b3} |
64d5610f ML |
21583 | @section Sequential_IO |
21584 | ||
21585 | ||
21586 | Sequential_IO may be instantiated with either a definite (constrained) | |
21587 | or indefinite (unconstrained) type. | |
21588 | ||
21589 | For the definite type case, the elements written to the file are simply | |
21590 | the memory images of the data values with no control information of any | |
21591 | kind. The resulting file should be read using the same type, no validity | |
21592 | checking is performed on input. | |
21593 | ||
21594 | For the indefinite type case, the elements written consist of two | |
21595 | parts. First is the size of the data item, written as the memory image | |
21596 | of a @code{Interfaces.C.size_t} value, followed by the memory image of | |
21597 | the data value. The resulting file can only be read using the same | |
21598 | (unconstrained) type. Normal assignment checks are performed on these | |
21599 | read operations, and if these checks fail, @code{Data_Error} is | |
21600 | raised. In particular, in the array case, the lengths must match, and in | |
21601 | the variant record case, if the variable for a particular read operation | |
21602 | is constrained, the discriminants must match. | |
21603 | ||
21604 | Note that it is not possible to use Sequential_IO to write variable | |
21605 | length array items, and then read the data back into different length | |
21606 | arrays. For example, the following will raise @code{Data_Error}: | |
21607 | ||
21608 | @example | |
21609 | package IO is new Sequential_IO (String); | |
21610 | F : IO.File_Type; | |
21611 | S : String (1..4); | |
21612 | ... | |
21613 | IO.Create (F) | |
21614 | IO.Write (F, "hello!") | |
21615 | IO.Reset (F, Mode=>In_File); | |
21616 | IO.Read (F, S); | |
21617 | Put_Line (S); | |
21618 | @end example | |
21619 | ||
21620 | On some Ada implementations, this will print @code{hell}, but the program is | |
21621 | clearly incorrect, since there is only one element in the file, and that | |
21622 | element is the string @code{hello!}. | |
21623 | ||
21624 | In Ada 95 and Ada 2005, this kind of behavior can be legitimately achieved | |
21625 | using Stream_IO, and this is the preferred mechanism. In particular, the | |
21626 | above program fragment rewritten to use Stream_IO will work correctly. | |
21627 | ||
21628 | @node Text_IO,Wide_Text_IO,Sequential_IO,The Implementation of Standard I/O | |
04d6c745 | 21629 | @anchor{gnat_rm/the_implementation_of_standard_i_o id6}@anchor{2b4}@anchor{gnat_rm/the_implementation_of_standard_i_o text-io}@anchor{2b5} |
64d5610f ML |
21630 | @section Text_IO |
21631 | ||
21632 | ||
21633 | Text_IO files consist of a stream of characters containing the following | |
21634 | special control characters: | |
21635 | ||
21636 | @example | |
21637 | LF (line feed, 16#0A#) Line Mark | |
21638 | FF (form feed, 16#0C#) Page Mark | |
21639 | @end example | |
21640 | ||
21641 | A canonical Text_IO file is defined as one in which the following | |
21642 | conditions are met: | |
21643 | ||
21644 | ||
21645 | @itemize * | |
21646 | ||
21647 | @item | |
21648 | The character @code{LF} is used only as a line mark, i.e., to mark the end | |
21649 | of the line. | |
21650 | ||
21651 | @item | |
21652 | The character @code{FF} is used only as a page mark, i.e., to mark the | |
21653 | end of a page and consequently can appear only immediately following a | |
21654 | @code{LF} (line mark) character. | |
21655 | ||
21656 | @item | |
21657 | The file ends with either @code{LF} (line mark) or @code{LF}-@cite{FF} | |
21658 | (line mark, page mark). In the former case, the page mark is implicitly | |
21659 | assumed to be present. | |
21660 | @end itemize | |
21661 | ||
21662 | A file written using Text_IO will be in canonical form provided that no | |
21663 | explicit @code{LF} or @code{FF} characters are written using @code{Put} | |
21664 | or @code{Put_Line}. There will be no @code{FF} character at the end of | |
21665 | the file unless an explicit @code{New_Page} operation was performed | |
21666 | before closing the file. | |
21667 | ||
21668 | A canonical Text_IO file that is a regular file (i.e., not a device or a | |
21669 | pipe) can be read using any of the routines in Text_IO. The | |
21670 | semantics in this case will be exactly as defined in the Ada Reference | |
21671 | Manual, and all the routines in Text_IO are fully implemented. | |
21672 | ||
21673 | A text file that does not meet the requirements for a canonical Text_IO | |
21674 | file has one of the following: | |
21675 | ||
21676 | ||
21677 | @itemize * | |
21678 | ||
21679 | @item | |
21680 | The file contains @code{FF} characters not immediately following a | |
21681 | @code{LF} character. | |
21682 | ||
21683 | @item | |
21684 | The file contains @code{LF} or @code{FF} characters written by | |
21685 | @code{Put} or @code{Put_Line}, which are not logically considered to be | |
21686 | line marks or page marks. | |
21687 | ||
21688 | @item | |
21689 | The file ends in a character other than @code{LF} or @code{FF}, | |
21690 | i.e., there is no explicit line mark or page mark at the end of the file. | |
21691 | @end itemize | |
21692 | ||
21693 | Text_IO can be used to read such non-standard text files but subprograms | |
21694 | to do with line or page numbers do not have defined meanings. In | |
21695 | particular, a @code{FF} character that does not follow a @code{LF} | |
21696 | character may or may not be treated as a page mark from the point of | |
21697 | view of page and line numbering. Every @code{LF} character is considered | |
21698 | to end a line, and there is an implied @code{LF} character at the end of | |
21699 | the file. | |
21700 | ||
21701 | @menu | |
21702 | * Stream Pointer Positioning:: | |
21703 | * Reading and Writing Non-Regular Files:: | |
21704 | * Get_Immediate:: | |
21705 | * Treating Text_IO Files as Streams:: | |
21706 | * Text_IO Extensions:: | |
21707 | * Text_IO Facilities for Unbounded Strings:: | |
21708 | ||
21709 | @end menu | |
21710 | ||
21711 | @node Stream Pointer Positioning,Reading and Writing Non-Regular Files,,Text_IO | |
04d6c745 | 21712 | @anchor{gnat_rm/the_implementation_of_standard_i_o id7}@anchor{2b6}@anchor{gnat_rm/the_implementation_of_standard_i_o stream-pointer-positioning}@anchor{2b7} |
64d5610f ML |
21713 | @subsection Stream Pointer Positioning |
21714 | ||
21715 | ||
21716 | @code{Ada.Text_IO} has a definition of current position for a file that | |
21717 | is being read. No internal buffering occurs in Text_IO, and usually the | |
21718 | physical position in the stream used to implement the file corresponds | |
21719 | to this logical position defined by Text_IO. There are two exceptions: | |
21720 | ||
21721 | ||
21722 | @itemize * | |
21723 | ||
21724 | @item | |
21725 | After a call to @code{End_Of_Page} that returns @code{True}, the stream | |
21726 | is positioned past the @code{LF} (line mark) that precedes the page | |
21727 | mark. Text_IO maintains an internal flag so that subsequent read | |
21728 | operations properly handle the logical position which is unchanged by | |
21729 | the @code{End_Of_Page} call. | |
21730 | ||
21731 | @item | |
21732 | After a call to @code{End_Of_File} that returns @code{True}, if the | |
21733 | Text_IO file was positioned before the line mark at the end of file | |
21734 | before the call, then the logical position is unchanged, but the stream | |
21735 | is physically positioned right at the end of file (past the line mark, | |
21736 | and past a possible page mark following the line mark. Again Text_IO | |
21737 | maintains internal flags so that subsequent read operations properly | |
21738 | handle the logical position. | |
21739 | @end itemize | |
21740 | ||
21741 | These discrepancies have no effect on the observable behavior of | |
21742 | Text_IO, but if a single Ada stream is shared between a C program and | |
21743 | Ada program, or shared (using @code{shared=yes} in the form string) | |
21744 | between two Ada files, then the difference may be observable in some | |
21745 | situations. | |
21746 | ||
21747 | @node Reading and Writing Non-Regular Files,Get_Immediate,Stream Pointer Positioning,Text_IO | |
04d6c745 | 21748 | @anchor{gnat_rm/the_implementation_of_standard_i_o id8}@anchor{2b8}@anchor{gnat_rm/the_implementation_of_standard_i_o reading-and-writing-non-regular-files}@anchor{2b9} |
64d5610f ML |
21749 | @subsection Reading and Writing Non-Regular Files |
21750 | ||
21751 | ||
21752 | A non-regular file is a device (such as a keyboard), or a pipe. Text_IO | |
21753 | can be used for reading and writing. Writing is not affected and the | |
21754 | sequence of characters output is identical to the normal file case, but | |
21755 | for reading, the behavior of Text_IO is modified to avoid undesirable | |
21756 | look-ahead as follows: | |
21757 | ||
21758 | An input file that is not a regular file is considered to have no page | |
21759 | marks. Any @code{Ascii.FF} characters (the character normally used for a | |
21760 | page mark) appearing in the file are considered to be data | |
21761 | characters. In particular: | |
21762 | ||
21763 | ||
21764 | @itemize * | |
21765 | ||
21766 | @item | |
21767 | @code{Get_Line} and @code{Skip_Line} do not test for a page mark | |
21768 | following a line mark. If a page mark appears, it will be treated as a | |
21769 | data character. | |
21770 | ||
21771 | @item | |
21772 | This avoids the need to wait for an extra character to be typed or | |
21773 | entered from the pipe to complete one of these operations. | |
21774 | ||
21775 | @item | |
21776 | @code{End_Of_Page} always returns @code{False} | |
21777 | ||
21778 | @item | |
21779 | @code{End_Of_File} will return @code{False} if there is a page mark at | |
21780 | the end of the file. | |
21781 | @end itemize | |
21782 | ||
21783 | Output to non-regular files is the same as for regular files. Page marks | |
21784 | may be written to non-regular files using @code{New_Page}, but as noted | |
21785 | above they will not be treated as page marks on input if the output is | |
21786 | piped to another Ada program. | |
21787 | ||
21788 | Another important discrepancy when reading non-regular files is that the end | |
21789 | of file indication is not ‘sticky’. If an end of file is entered, e.g., by | |
21790 | pressing the @code{EOT} key, | |
21791 | then end of file | |
21792 | is signaled once (i.e., the test @code{End_Of_File} | |
21793 | will yield @code{True}, or a read will | |
21794 | raise @code{End_Error}), but then reading can resume | |
21795 | to read data past that end of | |
21796 | file indication, until another end of file indication is entered. | |
21797 | ||
21798 | @node Get_Immediate,Treating Text_IO Files as Streams,Reading and Writing Non-Regular Files,Text_IO | |
04d6c745 | 21799 | @anchor{gnat_rm/the_implementation_of_standard_i_o get-immediate}@anchor{2ba}@anchor{gnat_rm/the_implementation_of_standard_i_o id9}@anchor{2bb} |
64d5610f ML |
21800 | @subsection Get_Immediate |
21801 | ||
21802 | ||
21803 | @geindex Get_Immediate | |
21804 | ||
21805 | Get_Immediate returns the next character (including control characters) | |
21806 | from the input file. In particular, Get_Immediate will return LF or FF | |
21807 | characters used as line marks or page marks. Such operations leave the | |
21808 | file positioned past the control character, and it is thus not treated | |
21809 | as having its normal function. This means that page, line and column | |
21810 | counts after this kind of Get_Immediate call are set as though the mark | |
21811 | did not occur. In the case where a Get_Immediate leaves the file | |
21812 | positioned between the line mark and page mark (which is not normally | |
21813 | possible), it is undefined whether the FF character will be treated as a | |
21814 | page mark. | |
21815 | ||
21816 | @node Treating Text_IO Files as Streams,Text_IO Extensions,Get_Immediate,Text_IO | |
04d6c745 | 21817 | @anchor{gnat_rm/the_implementation_of_standard_i_o id10}@anchor{2bc}@anchor{gnat_rm/the_implementation_of_standard_i_o treating-text-io-files-as-streams}@anchor{2bd} |
64d5610f ML |
21818 | @subsection Treating Text_IO Files as Streams |
21819 | ||
21820 | ||
21821 | @geindex Stream files | |
21822 | ||
21823 | The package @code{Text_IO.Streams} allows a @code{Text_IO} file to be treated | |
21824 | as a stream. Data written to a @code{Text_IO} file in this stream mode is | |
21825 | binary data. If this binary data contains bytes 16#0A# (@code{LF}) or | |
21826 | 16#0C# (@code{FF}), the resulting file may have non-standard | |
21827 | format. Similarly if read operations are used to read from a Text_IO | |
21828 | file treated as a stream, then @code{LF} and @code{FF} characters may be | |
21829 | skipped and the effect is similar to that described above for | |
21830 | @code{Get_Immediate}. | |
21831 | ||
21832 | @node Text_IO Extensions,Text_IO Facilities for Unbounded Strings,Treating Text_IO Files as Streams,Text_IO | |
04d6c745 | 21833 | @anchor{gnat_rm/the_implementation_of_standard_i_o id11}@anchor{2be}@anchor{gnat_rm/the_implementation_of_standard_i_o text-io-extensions}@anchor{2bf} |
64d5610f ML |
21834 | @subsection Text_IO Extensions |
21835 | ||
21836 | ||
21837 | @geindex Text_IO extensions | |
21838 | ||
21839 | A package GNAT.IO_Aux in the GNAT library provides some useful extensions | |
21840 | to the standard @code{Text_IO} package: | |
21841 | ||
21842 | ||
21843 | @itemize * | |
21844 | ||
21845 | @item | |
21846 | function File_Exists (Name : String) return Boolean; | |
21847 | Determines if a file of the given name exists. | |
21848 | ||
21849 | @item | |
21850 | function Get_Line return String; | |
21851 | Reads a string from the standard input file. The value returned is exactly | |
21852 | the length of the line that was read. | |
21853 | ||
21854 | @item | |
21855 | function Get_Line (File : Ada.Text_IO.File_Type) return String; | |
21856 | Similar, except that the parameter File specifies the file from which | |
21857 | the string is to be read. | |
21858 | @end itemize | |
21859 | ||
21860 | @node Text_IO Facilities for Unbounded Strings,,Text_IO Extensions,Text_IO | |
04d6c745 | 21861 | @anchor{gnat_rm/the_implementation_of_standard_i_o id12}@anchor{2c0}@anchor{gnat_rm/the_implementation_of_standard_i_o text-io-facilities-for-unbounded-strings}@anchor{2c1} |
64d5610f ML |
21862 | @subsection Text_IO Facilities for Unbounded Strings |
21863 | ||
21864 | ||
21865 | @geindex Text_IO for unbounded strings | |
21866 | ||
21867 | @geindex Unbounded_String | |
21868 | @geindex Text_IO operations | |
21869 | ||
21870 | The package @code{Ada.Strings.Unbounded.Text_IO} | |
21871 | in library files @code{a-suteio.ads/adb} contains some GNAT-specific | |
21872 | subprograms useful for Text_IO operations on unbounded strings: | |
21873 | ||
21874 | ||
21875 | @itemize * | |
21876 | ||
21877 | @item | |
21878 | function Get_Line (File : File_Type) return Unbounded_String; | |
21879 | Reads a line from the specified file | |
21880 | and returns the result as an unbounded string. | |
21881 | ||
21882 | @item | |
21883 | procedure Put (File : File_Type; U : Unbounded_String); | |
21884 | Writes the value of the given unbounded string to the specified file | |
21885 | Similar to the effect of | |
21886 | @code{Put (To_String (U))} except that an extra copy is avoided. | |
21887 | ||
21888 | @item | |
21889 | procedure Put_Line (File : File_Type; U : Unbounded_String); | |
21890 | Writes the value of the given unbounded string to the specified file, | |
21891 | followed by a @code{New_Line}. | |
21892 | Similar to the effect of @code{Put_Line (To_String (U))} except | |
21893 | that an extra copy is avoided. | |
21894 | @end itemize | |
21895 | ||
21896 | In the above procedures, @code{File} is of type @code{Ada.Text_IO.File_Type} | |
21897 | and is optional. If the parameter is omitted, then the standard input or | |
21898 | output file is referenced as appropriate. | |
21899 | ||
21900 | The package @code{Ada.Strings.Wide_Unbounded.Wide_Text_IO} in library | |
21901 | files @code{a-swuwti.ads} and @code{a-swuwti.adb} provides similar extended | |
21902 | @code{Wide_Text_IO} functionality for unbounded wide strings. | |
21903 | ||
21904 | The package @code{Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO} in library | |
21905 | files @code{a-szuzti.ads} and @code{a-szuzti.adb} provides similar extended | |
21906 | @code{Wide_Wide_Text_IO} functionality for unbounded wide wide strings. | |
21907 | ||
21908 | @node Wide_Text_IO,Wide_Wide_Text_IO,Text_IO,The Implementation of Standard I/O | |
04d6c745 | 21909 | @anchor{gnat_rm/the_implementation_of_standard_i_o id13}@anchor{2c2}@anchor{gnat_rm/the_implementation_of_standard_i_o wide-text-io}@anchor{2c3} |
64d5610f ML |
21910 | @section Wide_Text_IO |
21911 | ||
21912 | ||
21913 | @code{Wide_Text_IO} is similar in most respects to Text_IO, except that | |
21914 | both input and output files may contain special sequences that represent | |
21915 | wide character values. The encoding scheme for a given file may be | |
21916 | specified using a FORM parameter: | |
21917 | ||
21918 | @example | |
21919 | WCEM=`x` | |
21920 | @end example | |
21921 | ||
21922 | as part of the FORM string (WCEM = wide character encoding method), | |
21923 | where @code{x} is one of the following characters | |
21924 | ||
21925 | ||
21926 | @multitable {xxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxx} | |
21927 | @headitem | |
21928 | ||
21929 | Character | |
21930 | ||
21931 | @tab | |
21932 | ||
21933 | Encoding | |
21934 | ||
21935 | @item | |
21936 | ||
21937 | `h' | |
21938 | ||
21939 | @tab | |
21940 | ||
21941 | Hex ESC encoding | |
21942 | ||
21943 | @item | |
21944 | ||
21945 | `u' | |
21946 | ||
21947 | @tab | |
21948 | ||
21949 | Upper half encoding | |
21950 | ||
21951 | @item | |
21952 | ||
21953 | `s' | |
21954 | ||
21955 | @tab | |
21956 | ||
21957 | Shift-JIS encoding | |
21958 | ||
21959 | @item | |
21960 | ||
21961 | `e' | |
21962 | ||
21963 | @tab | |
21964 | ||
21965 | EUC Encoding | |
21966 | ||
21967 | @item | |
21968 | ||
21969 | `8' | |
21970 | ||
21971 | @tab | |
21972 | ||
21973 | UTF-8 encoding | |
21974 | ||
21975 | @item | |
21976 | ||
21977 | `b' | |
21978 | ||
21979 | @tab | |
21980 | ||
21981 | Brackets encoding | |
21982 | ||
21983 | @end multitable | |
21984 | ||
21985 | ||
21986 | The encoding methods match those that | |
21987 | can be used in a source | |
21988 | program, but there is no requirement that the encoding method used for | |
21989 | the source program be the same as the encoding method used for files, | |
21990 | and different files may use different encoding methods. | |
21991 | ||
21992 | The default encoding method for the standard files, and for opened files | |
21993 | for which no WCEM parameter is given in the FORM string matches the | |
21994 | wide character encoding specified for the main program (the default | |
21995 | being brackets encoding if no coding method was specified with -gnatW). | |
21996 | ||
21997 | ||
21998 | @table @asis | |
21999 | ||
22000 | @item `Hex Coding' | |
22001 | ||
22002 | In this encoding, a wide character is represented by a five character | |
22003 | sequence: | |
22004 | @end table | |
22005 | ||
22006 | @example | |
22007 | ESC a b c d | |
22008 | @end example | |
22009 | ||
22010 | ||
22011 | @quotation | |
22012 | ||
22013 | where @code{a}, @code{b}, @code{c}, @code{d} are the four hexadecimal | |
22014 | characters (using upper case letters) of the wide character code. For | |
22015 | example, ESC A345 is used to represent the wide character with code | |
22016 | 16#A345#. This scheme is compatible with use of the full | |
22017 | @code{Wide_Character} set. | |
22018 | @end quotation | |
22019 | ||
22020 | ||
22021 | @table @asis | |
22022 | ||
22023 | @item `Upper Half Coding' | |
22024 | ||
22025 | The wide character with encoding 16#abcd#, where the upper bit is on | |
22026 | (i.e., a is in the range 8-F) is represented as two bytes 16#ab# and | |
22027 | 16#cd#. The second byte may never be a format control character, but is | |
22028 | not required to be in the upper half. This method can be also used for | |
22029 | shift-JIS or EUC where the internal coding matches the external coding. | |
22030 | ||
22031 | @item `Shift JIS Coding' | |
22032 | ||
22033 | A wide character is represented by a two character sequence 16#ab# and | |
22034 | 16#cd#, with the restrictions described for upper half encoding as | |
22035 | described above. The internal character code is the corresponding JIS | |
22036 | character according to the standard algorithm for Shift-JIS | |
22037 | conversion. Only characters defined in the JIS code set table can be | |
22038 | used with this encoding method. | |
22039 | ||
22040 | @item `EUC Coding' | |
22041 | ||
22042 | A wide character is represented by a two character sequence 16#ab# and | |
22043 | 16#cd#, with both characters being in the upper half. The internal | |
22044 | character code is the corresponding JIS character according to the EUC | |
22045 | encoding algorithm. Only characters defined in the JIS code set table | |
22046 | can be used with this encoding method. | |
22047 | ||
22048 | @item `UTF-8 Coding' | |
22049 | ||
22050 | A wide character is represented using | |
22051 | UCS Transformation Format 8 (UTF-8) as defined in Annex R of ISO | |
22052 | 10646-1/Am.2. Depending on the character value, the representation | |
22053 | is a one, two, or three byte sequence: | |
22054 | @end table | |
22055 | ||
22056 | @example | |
22057 | 16#0000#-16#007f#: 2#0xxxxxxx# | |
22058 | 16#0080#-16#07ff#: 2#110xxxxx# 2#10xxxxxx# | |
22059 | 16#0800#-16#ffff#: 2#1110xxxx# 2#10xxxxxx# 2#10xxxxxx# | |
22060 | @end example | |
22061 | ||
22062 | ||
22063 | @quotation | |
22064 | ||
22065 | where the @code{xxx} bits correspond to the left-padded bits of the | |
22066 | 16-bit character value. Note that all lower half ASCII characters | |
22067 | are represented as ASCII bytes and all upper half characters and | |
22068 | other wide characters are represented as sequences of upper-half | |
22069 | (The full UTF-8 scheme allows for encoding 31-bit characters as | |
22070 | 6-byte sequences, but in this implementation, all UTF-8 sequences | |
22071 | of four or more bytes length will raise a Constraint_Error, as | |
22072 | will all invalid UTF-8 sequences.) | |
22073 | @end quotation | |
22074 | ||
22075 | ||
22076 | @table @asis | |
22077 | ||
22078 | @item `Brackets Coding' | |
22079 | ||
22080 | In this encoding, a wide character is represented by the following eight | |
22081 | character sequence: | |
22082 | @end table | |
22083 | ||
22084 | @example | |
22085 | [ " a b c d " ] | |
22086 | @end example | |
22087 | ||
22088 | ||
22089 | @quotation | |
22090 | ||
22091 | where @code{a}, @code{b}, @code{c}, @code{d} are the four hexadecimal | |
22092 | characters (using uppercase letters) of the wide character code. For | |
22093 | example, @code{["A345"]} is used to represent the wide character with code | |
22094 | @code{16#A345#}. | |
22095 | This scheme is compatible with use of the full Wide_Character set. | |
22096 | On input, brackets coding can also be used for upper half characters, | |
22097 | e.g., @code{["C1"]} for lower case a. However, on output, brackets notation | |
22098 | is only used for wide characters with a code greater than @code{16#FF#}. | |
22099 | ||
22100 | Note that brackets coding is not normally used in the context of | |
22101 | Wide_Text_IO or Wide_Wide_Text_IO, since it is really just designed as | |
22102 | a portable way of encoding source files. In the context of Wide_Text_IO | |
22103 | or Wide_Wide_Text_IO, it can only be used if the file does not contain | |
22104 | any instance of the left bracket character other than to encode wide | |
22105 | character values using the brackets encoding method. In practice it is | |
22106 | expected that some standard wide character encoding method such | |
22107 | as UTF-8 will be used for text input output. | |
22108 | ||
22109 | If brackets notation is used, then any occurrence of a left bracket | |
22110 | in the input file which is not the start of a valid wide character | |
22111 | sequence will cause Constraint_Error to be raised. It is possible to | |
22112 | encode a left bracket as [“5B”] and Wide_Text_IO and Wide_Wide_Text_IO | |
22113 | input will interpret this as a left bracket. | |
22114 | ||
22115 | However, when a left bracket is output, it will be output as a left bracket | |
22116 | and not as [“5B”]. We make this decision because for normal use of | |
22117 | Wide_Text_IO for outputting messages, it is unpleasant to clobber left | |
22118 | brackets. For example, if we write: | |
22119 | ||
22120 | @example | |
22121 | Put_Line ("Start of output [first run]"); | |
22122 | @end example | |
22123 | ||
22124 | we really do not want to have the left bracket in this message clobbered so | |
22125 | that the output reads: | |
22126 | @end quotation | |
22127 | ||
22128 | @example | |
22129 | Start of output ["5B"]first run] | |
22130 | @end example | |
22131 | ||
22132 | ||
22133 | @quotation | |
22134 | ||
22135 | In practice brackets encoding is reasonably useful for normal Put_Line use | |
22136 | since we won’t get confused between left brackets and wide character | |
22137 | sequences in the output. But for input, or when files are written out | |
22138 | and read back in, it really makes better sense to use one of the standard | |
22139 | encoding methods such as UTF-8. | |
22140 | @end quotation | |
22141 | ||
22142 | For the coding schemes other than UTF-8, Hex, or Brackets encoding, | |
22143 | not all wide character | |
22144 | values can be represented. An attempt to output a character that cannot | |
22145 | be represented using the encoding scheme for the file causes | |
22146 | Constraint_Error to be raised. An invalid wide character sequence on | |
22147 | input also causes Constraint_Error to be raised. | |
22148 | ||
22149 | @menu | |
22150 | * Stream Pointer Positioning: Stream Pointer Positioning<2>. | |
22151 | * Reading and Writing Non-Regular Files: Reading and Writing Non-Regular Files<2>. | |
22152 | ||
22153 | @end menu | |
22154 | ||
22155 | @node Stream Pointer Positioning<2>,Reading and Writing Non-Regular Files<2>,,Wide_Text_IO | |
04d6c745 | 22156 | @anchor{gnat_rm/the_implementation_of_standard_i_o id14}@anchor{2c4}@anchor{gnat_rm/the_implementation_of_standard_i_o stream-pointer-positioning-1}@anchor{2c5} |
64d5610f ML |
22157 | @subsection Stream Pointer Positioning |
22158 | ||
22159 | ||
22160 | @code{Ada.Wide_Text_IO} is similar to @code{Ada.Text_IO} in its handling | |
04d6c745 | 22161 | of stream pointer positioning (@ref{2b5,,Text_IO}). There is one additional |
64d5610f ML |
22162 | case: |
22163 | ||
22164 | If @code{Ada.Wide_Text_IO.Look_Ahead} reads a character outside the | |
22165 | normal lower ASCII set, i.e. a character in the range: | |
22166 | ||
22167 | @example | |
22168 | Wide_Character'Val (16#0080#) .. Wide_Character'Val (16#FFFF#) | |
22169 | @end example | |
22170 | ||
22171 | then although the logical position of the file pointer is unchanged by | |
22172 | the @code{Look_Ahead} call, the stream is physically positioned past the | |
22173 | wide character sequence. Again this is to avoid the need for buffering | |
22174 | or backup, and all @code{Wide_Text_IO} routines check the internal | |
22175 | indication that this situation has occurred so that this is not visible | |
22176 | to a normal program using @code{Wide_Text_IO}. However, this discrepancy | |
22177 | can be observed if the wide text file shares a stream with another file. | |
22178 | ||
22179 | @node Reading and Writing Non-Regular Files<2>,,Stream Pointer Positioning<2>,Wide_Text_IO | |
04d6c745 | 22180 | @anchor{gnat_rm/the_implementation_of_standard_i_o id15}@anchor{2c6}@anchor{gnat_rm/the_implementation_of_standard_i_o reading-and-writing-non-regular-files-1}@anchor{2c7} |
64d5610f ML |
22181 | @subsection Reading and Writing Non-Regular Files |
22182 | ||
22183 | ||
22184 | As in the case of Text_IO, when a non-regular file is read, it is | |
22185 | assumed that the file contains no page marks (any form characters are | |
22186 | treated as data characters), and @code{End_Of_Page} always returns | |
22187 | @code{False}. Similarly, the end of file indication is not sticky, so | |
22188 | it is possible to read beyond an end of file. | |
22189 | ||
22190 | @node Wide_Wide_Text_IO,Stream_IO,Wide_Text_IO,The Implementation of Standard I/O | |
04d6c745 | 22191 | @anchor{gnat_rm/the_implementation_of_standard_i_o id16}@anchor{2c8}@anchor{gnat_rm/the_implementation_of_standard_i_o wide-wide-text-io}@anchor{2c9} |
64d5610f ML |
22192 | @section Wide_Wide_Text_IO |
22193 | ||
22194 | ||
22195 | @code{Wide_Wide_Text_IO} is similar in most respects to Text_IO, except that | |
22196 | both input and output files may contain special sequences that represent | |
22197 | wide wide character values. The encoding scheme for a given file may be | |
22198 | specified using a FORM parameter: | |
22199 | ||
22200 | @example | |
22201 | WCEM=`x` | |
22202 | @end example | |
22203 | ||
22204 | as part of the FORM string (WCEM = wide character encoding method), | |
22205 | where @code{x} is one of the following characters | |
22206 | ||
22207 | ||
22208 | @multitable {xxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxx} | |
22209 | @headitem | |
22210 | ||
22211 | Character | |
22212 | ||
22213 | @tab | |
22214 | ||
22215 | Encoding | |
22216 | ||
22217 | @item | |
22218 | ||
22219 | `h' | |
22220 | ||
22221 | @tab | |
22222 | ||
22223 | Hex ESC encoding | |
22224 | ||
22225 | @item | |
22226 | ||
22227 | `u' | |
22228 | ||
22229 | @tab | |
22230 | ||
22231 | Upper half encoding | |
22232 | ||
22233 | @item | |
22234 | ||
22235 | `s' | |
22236 | ||
22237 | @tab | |
22238 | ||
22239 | Shift-JIS encoding | |
22240 | ||
22241 | @item | |
22242 | ||
22243 | `e' | |
22244 | ||
22245 | @tab | |
22246 | ||
22247 | EUC Encoding | |
22248 | ||
22249 | @item | |
22250 | ||
22251 | `8' | |
22252 | ||
22253 | @tab | |
22254 | ||
22255 | UTF-8 encoding | |
22256 | ||
22257 | @item | |
22258 | ||
22259 | `b' | |
22260 | ||
22261 | @tab | |
22262 | ||
22263 | Brackets encoding | |
22264 | ||
22265 | @end multitable | |
22266 | ||
22267 | ||
22268 | The encoding methods match those that | |
22269 | can be used in a source | |
22270 | program, but there is no requirement that the encoding method used for | |
22271 | the source program be the same as the encoding method used for files, | |
22272 | and different files may use different encoding methods. | |
22273 | ||
22274 | The default encoding method for the standard files, and for opened files | |
22275 | for which no WCEM parameter is given in the FORM string matches the | |
22276 | wide character encoding specified for the main program (the default | |
22277 | being brackets encoding if no coding method was specified with -gnatW). | |
22278 | ||
22279 | ||
22280 | @table @asis | |
22281 | ||
22282 | @item `UTF-8 Coding' | |
22283 | ||
22284 | A wide character is represented using | |
22285 | UCS Transformation Format 8 (UTF-8) as defined in Annex R of ISO | |
22286 | 10646-1/Am.2. Depending on the character value, the representation | |
22287 | is a one, two, three, or four byte sequence: | |
22288 | @end table | |
22289 | ||
22290 | @example | |
22291 | 16#000000#-16#00007f#: 2#0xxxxxxx# | |
22292 | 16#000080#-16#0007ff#: 2#110xxxxx# 2#10xxxxxx# | |
22293 | 16#000800#-16#00ffff#: 2#1110xxxx# 2#10xxxxxx# 2#10xxxxxx# | |
22294 | 16#010000#-16#10ffff#: 2#11110xxx# 2#10xxxxxx# 2#10xxxxxx# 2#10xxxxxx# | |
22295 | @end example | |
22296 | ||
22297 | ||
22298 | @quotation | |
22299 | ||
22300 | where the @code{xxx} bits correspond to the left-padded bits of the | |
22301 | 21-bit character value. Note that all lower half ASCII characters | |
22302 | are represented as ASCII bytes and all upper half characters and | |
22303 | other wide characters are represented as sequences of upper-half | |
22304 | characters. | |
22305 | @end quotation | |
22306 | ||
22307 | ||
22308 | @table @asis | |
22309 | ||
22310 | @item `Brackets Coding' | |
22311 | ||
22312 | In this encoding, a wide wide character is represented by the following eight | |
22313 | character sequence if is in wide character range | |
22314 | @end table | |
22315 | ||
22316 | @example | |
22317 | [ " a b c d " ] | |
22318 | @end example | |
22319 | ||
22320 | ||
22321 | @quotation | |
22322 | ||
22323 | and by the following ten character sequence if not | |
22324 | @end quotation | |
22325 | ||
22326 | @example | |
22327 | [ " a b c d e f " ] | |
22328 | @end example | |
22329 | ||
22330 | ||
22331 | @quotation | |
22332 | ||
22333 | where @code{a}, @code{b}, @code{c}, @code{d}, @code{e}, and @code{f} | |
22334 | are the four or six hexadecimal | |
22335 | characters (using uppercase letters) of the wide wide character code. For | |
22336 | example, @code{["01A345"]} is used to represent the wide wide character | |
22337 | with code @code{16#01A345#}. | |
22338 | ||
22339 | This scheme is compatible with use of the full Wide_Wide_Character set. | |
22340 | On input, brackets coding can also be used for upper half characters, | |
22341 | e.g., @code{["C1"]} for lower case a. However, on output, brackets notation | |
22342 | is only used for wide characters with a code greater than @code{16#FF#}. | |
22343 | @end quotation | |
22344 | ||
22345 | If is also possible to use the other Wide_Character encoding methods, | |
22346 | such as Shift-JIS, but the other schemes cannot support the full range | |
22347 | of wide wide characters. | |
22348 | An attempt to output a character that cannot | |
22349 | be represented using the encoding scheme for the file causes | |
22350 | Constraint_Error to be raised. An invalid wide character sequence on | |
22351 | input also causes Constraint_Error to be raised. | |
22352 | ||
22353 | @menu | |
22354 | * Stream Pointer Positioning: Stream Pointer Positioning<3>. | |
22355 | * Reading and Writing Non-Regular Files: Reading and Writing Non-Regular Files<3>. | |
22356 | ||
22357 | @end menu | |
22358 | ||
22359 | @node Stream Pointer Positioning<3>,Reading and Writing Non-Regular Files<3>,,Wide_Wide_Text_IO | |
04d6c745 | 22360 | @anchor{gnat_rm/the_implementation_of_standard_i_o id17}@anchor{2ca}@anchor{gnat_rm/the_implementation_of_standard_i_o stream-pointer-positioning-2}@anchor{2cb} |
64d5610f ML |
22361 | @subsection Stream Pointer Positioning |
22362 | ||
22363 | ||
22364 | @code{Ada.Wide_Wide_Text_IO} is similar to @code{Ada.Text_IO} in its handling | |
04d6c745 | 22365 | of stream pointer positioning (@ref{2b5,,Text_IO}). There is one additional |
64d5610f ML |
22366 | case: |
22367 | ||
22368 | If @code{Ada.Wide_Wide_Text_IO.Look_Ahead} reads a character outside the | |
22369 | normal lower ASCII set, i.e. a character in the range: | |
22370 | ||
22371 | @example | |
22372 | Wide_Wide_Character'Val (16#0080#) .. Wide_Wide_Character'Val (16#10FFFF#) | |
22373 | @end example | |
22374 | ||
22375 | then although the logical position of the file pointer is unchanged by | |
22376 | the @code{Look_Ahead} call, the stream is physically positioned past the | |
22377 | wide character sequence. Again this is to avoid the need for buffering | |
22378 | or backup, and all @code{Wide_Wide_Text_IO} routines check the internal | |
22379 | indication that this situation has occurred so that this is not visible | |
22380 | to a normal program using @code{Wide_Wide_Text_IO}. However, this discrepancy | |
22381 | can be observed if the wide text file shares a stream with another file. | |
22382 | ||
22383 | @node Reading and Writing Non-Regular Files<3>,,Stream Pointer Positioning<3>,Wide_Wide_Text_IO | |
04d6c745 | 22384 | @anchor{gnat_rm/the_implementation_of_standard_i_o id18}@anchor{2cc}@anchor{gnat_rm/the_implementation_of_standard_i_o reading-and-writing-non-regular-files-2}@anchor{2cd} |
64d5610f ML |
22385 | @subsection Reading and Writing Non-Regular Files |
22386 | ||
22387 | ||
22388 | As in the case of Text_IO, when a non-regular file is read, it is | |
22389 | assumed that the file contains no page marks (any form characters are | |
22390 | treated as data characters), and @code{End_Of_Page} always returns | |
22391 | @code{False}. Similarly, the end of file indication is not sticky, so | |
22392 | it is possible to read beyond an end of file. | |
22393 | ||
22394 | @node Stream_IO,Text Translation,Wide_Wide_Text_IO,The Implementation of Standard I/O | |
04d6c745 | 22395 | @anchor{gnat_rm/the_implementation_of_standard_i_o id19}@anchor{2ce}@anchor{gnat_rm/the_implementation_of_standard_i_o stream-io}@anchor{2cf} |
64d5610f ML |
22396 | @section Stream_IO |
22397 | ||
22398 | ||
22399 | A stream file is a sequence of bytes, where individual elements are | |
22400 | written to the file as described in the Ada Reference Manual. The type | |
22401 | @code{Stream_Element} is simply a byte. There are two ways to read or | |
22402 | write a stream file. | |
22403 | ||
22404 | ||
22405 | @itemize * | |
22406 | ||
22407 | @item | |
22408 | The operations @code{Read} and @code{Write} directly read or write a | |
22409 | sequence of stream elements with no control information. | |
22410 | ||
22411 | @item | |
22412 | The stream attributes applied to a stream file transfer data in the | |
22413 | manner described for stream attributes. | |
22414 | @end itemize | |
22415 | ||
22416 | @node Text Translation,Shared Files,Stream_IO,The Implementation of Standard I/O | |
04d6c745 | 22417 | @anchor{gnat_rm/the_implementation_of_standard_i_o id20}@anchor{2d0}@anchor{gnat_rm/the_implementation_of_standard_i_o text-translation}@anchor{2d1} |
64d5610f ML |
22418 | @section Text Translation |
22419 | ||
22420 | ||
22421 | @code{Text_Translation=xxx} may be used as the Form parameter | |
22422 | passed to Text_IO.Create and Text_IO.Open. @code{Text_Translation=xxx} | |
22423 | has no effect on Unix systems. Possible values are: | |
22424 | ||
22425 | ||
22426 | @itemize * | |
22427 | ||
22428 | @item | |
22429 | @code{Yes} or @code{Text} is the default, which means to | |
22430 | translate LF to/from CR/LF on Windows systems. | |
22431 | ||
22432 | @code{No} disables this translation; i.e. it | |
22433 | uses binary mode. For output files, @code{Text_Translation=No} | |
22434 | may be used to create Unix-style files on | |
22435 | Windows. | |
22436 | ||
22437 | @item | |
22438 | @code{wtext} translation enabled in Unicode mode. | |
22439 | (corresponds to _O_WTEXT). | |
22440 | ||
22441 | @item | |
22442 | @code{u8text} translation enabled in Unicode UTF-8 mode. | |
22443 | (corresponds to O_U8TEXT). | |
22444 | ||
22445 | @item | |
22446 | @code{u16text} translation enabled in Unicode UTF-16 | |
22447 | mode. (corresponds to_O_U16TEXT). | |
22448 | @end itemize | |
22449 | ||
22450 | @node Shared Files,Filenames encoding,Text Translation,The Implementation of Standard I/O | |
04d6c745 | 22451 | @anchor{gnat_rm/the_implementation_of_standard_i_o id21}@anchor{2d2}@anchor{gnat_rm/the_implementation_of_standard_i_o shared-files}@anchor{2d3} |
64d5610f ML |
22452 | @section Shared Files |
22453 | ||
22454 | ||
22455 | Section A.14 of the Ada Reference Manual allows implementations to | |
22456 | provide a wide variety of behavior if an attempt is made to access the | |
22457 | same external file with two or more internal files. | |
22458 | ||
22459 | To provide a full range of functionality, while at the same time | |
22460 | minimizing the problems of portability caused by this implementation | |
22461 | dependence, GNAT handles file sharing as follows: | |
22462 | ||
22463 | ||
22464 | @itemize * | |
22465 | ||
22466 | @item | |
22467 | In the absence of a @code{shared=xxx} form parameter, an attempt | |
22468 | to open two or more files with the same full name is considered an error | |
22469 | and is not supported. The exception @code{Use_Error} will be | |
22470 | raised. Note that a file that is not explicitly closed by the program | |
22471 | remains open until the program terminates. | |
22472 | ||
22473 | @item | |
22474 | If the form parameter @code{shared=no} appears in the form string, the | |
22475 | file can be opened or created with its own separate stream identifier, | |
22476 | regardless of whether other files sharing the same external file are | |
22477 | opened. The exact effect depends on how the C stream routines handle | |
22478 | multiple accesses to the same external files using separate streams. | |
22479 | ||
22480 | @item | |
22481 | If the form parameter @code{shared=yes} appears in the form string for | |
22482 | each of two or more files opened using the same full name, the same | |
22483 | stream is shared between these files, and the semantics are as described | |
22484 | in Ada Reference Manual, Section A.14. | |
22485 | @end itemize | |
22486 | ||
22487 | When a program that opens multiple files with the same name is ported | |
22488 | from another Ada compiler to GNAT, the effect will be that | |
22489 | @code{Use_Error} is raised. | |
22490 | ||
22491 | The documentation of the original compiler and the documentation of the | |
22492 | program should then be examined to determine if file sharing was | |
22493 | expected, and @code{shared=xxx} parameters added to @code{Open} | |
22494 | and @code{Create} calls as required. | |
22495 | ||
22496 | When a program is ported from GNAT to some other Ada compiler, no | |
22497 | special attention is required unless the @code{shared=xxx} form | |
22498 | parameter is used in the program. In this case, you must examine the | |
22499 | documentation of the new compiler to see if it supports the required | |
22500 | file sharing semantics, and form strings modified appropriately. Of | |
22501 | course it may be the case that the program cannot be ported if the | |
22502 | target compiler does not support the required functionality. The best | |
22503 | approach in writing portable code is to avoid file sharing (and hence | |
22504 | the use of the @code{shared=xxx} parameter in the form string) | |
22505 | completely. | |
22506 | ||
22507 | One common use of file sharing in Ada 83 is the use of instantiations of | |
22508 | Sequential_IO on the same file with different types, to achieve | |
22509 | heterogeneous input-output. Although this approach will work in GNAT if | |
22510 | @code{shared=yes} is specified, it is preferable in Ada to use Stream_IO | |
22511 | for this purpose (using the stream attributes) | |
22512 | ||
22513 | @node Filenames encoding,File content encoding,Shared Files,The Implementation of Standard I/O | |
04d6c745 | 22514 | @anchor{gnat_rm/the_implementation_of_standard_i_o filenames-encoding}@anchor{2d4}@anchor{gnat_rm/the_implementation_of_standard_i_o id22}@anchor{2d5} |
64d5610f ML |
22515 | @section Filenames encoding |
22516 | ||
22517 | ||
22518 | An encoding form parameter can be used to specify the filename | |
22519 | encoding @code{encoding=xxx}. | |
22520 | ||
22521 | ||
22522 | @itemize * | |
22523 | ||
22524 | @item | |
22525 | If the form parameter @code{encoding=utf8} appears in the form string, the | |
22526 | filename must be encoded in UTF-8. | |
22527 | ||
22528 | @item | |
22529 | If the form parameter @code{encoding=8bits} appears in the form | |
22530 | string, the filename must be a standard 8bits string. | |
22531 | @end itemize | |
22532 | ||
22533 | In the absence of a @code{encoding=xxx} form parameter, the | |
22534 | encoding is controlled by the @code{GNAT_CODE_PAGE} environment | |
22535 | variable. And if not set @code{utf8} is assumed. | |
22536 | ||
22537 | ||
22538 | @table @asis | |
22539 | ||
22540 | @item `CP_ACP' | |
22541 | ||
22542 | The current system Windows ANSI code page. | |
22543 | ||
22544 | @item `CP_UTF8' | |
22545 | ||
22546 | UTF-8 encoding | |
22547 | @end table | |
22548 | ||
22549 | This encoding form parameter is only supported on the Windows | |
22550 | platform. On the other Operating Systems the run-time is supporting | |
22551 | UTF-8 natively. | |
22552 | ||
22553 | @node File content encoding,Open Modes,Filenames encoding,The Implementation of Standard I/O | |
04d6c745 | 22554 | @anchor{gnat_rm/the_implementation_of_standard_i_o file-content-encoding}@anchor{2d6}@anchor{gnat_rm/the_implementation_of_standard_i_o id23}@anchor{2d7} |
64d5610f ML |
22555 | @section File content encoding |
22556 | ||
22557 | ||
22558 | For text files it is possible to specify the encoding to use. This is | |
22559 | controlled by the by the @code{GNAT_CCS_ENCODING} environment | |
22560 | variable. And if not set @code{TEXT} is assumed. | |
22561 | ||
22562 | The possible values are those supported on Windows: | |
22563 | ||
22564 | ||
22565 | @table @asis | |
22566 | ||
22567 | @item `TEXT' | |
22568 | ||
22569 | Translated text mode | |
22570 | ||
22571 | @item `WTEXT' | |
22572 | ||
22573 | Translated unicode encoding | |
22574 | ||
22575 | @item `U16TEXT' | |
22576 | ||
22577 | Unicode 16-bit encoding | |
22578 | ||
22579 | @item `U8TEXT' | |
22580 | ||
22581 | Unicode 8-bit encoding | |
22582 | @end table | |
22583 | ||
22584 | This encoding is only supported on the Windows platform. | |
22585 | ||
22586 | @node Open Modes,Operations on C Streams,File content encoding,The Implementation of Standard I/O | |
04d6c745 | 22587 | @anchor{gnat_rm/the_implementation_of_standard_i_o id24}@anchor{2d8}@anchor{gnat_rm/the_implementation_of_standard_i_o open-modes}@anchor{2d9} |
64d5610f ML |
22588 | @section Open Modes |
22589 | ||
22590 | ||
22591 | @code{Open} and @code{Create} calls result in a call to @code{fopen} | |
22592 | using the mode shown in the following table: | |
22593 | ||
22594 | ||
22595 | @multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxx} | |
22596 | @headitem | |
22597 | ||
22598 | @code{Open} and @code{Create} Call Modes | |
22599 | ||
22600 | @tab | |
22601 | ||
22602 | @tab | |
22603 | ||
22604 | @item | |
22605 | ||
22606 | @tab | |
22607 | ||
22608 | `OPEN' | |
22609 | ||
22610 | @tab | |
22611 | ||
22612 | `CREATE' | |
22613 | ||
22614 | @item | |
22615 | ||
22616 | Append_File | |
22617 | ||
22618 | @tab | |
22619 | ||
22620 | “r+” | |
22621 | ||
22622 | @tab | |
22623 | ||
22624 | “w+” | |
22625 | ||
22626 | @item | |
22627 | ||
22628 | In_File | |
22629 | ||
22630 | @tab | |
22631 | ||
22632 | “r” | |
22633 | ||
22634 | @tab | |
22635 | ||
22636 | “w+” | |
22637 | ||
22638 | @item | |
22639 | ||
22640 | Out_File (Direct_IO) | |
22641 | ||
22642 | @tab | |
22643 | ||
22644 | “r+” | |
22645 | ||
22646 | @tab | |
22647 | ||
22648 | “w” | |
22649 | ||
22650 | @item | |
22651 | ||
22652 | Out_File (all other cases) | |
22653 | ||
22654 | @tab | |
22655 | ||
22656 | “w” | |
22657 | ||
22658 | @tab | |
22659 | ||
22660 | “w” | |
22661 | ||
22662 | @item | |
22663 | ||
22664 | Inout_File | |
22665 | ||
22666 | @tab | |
22667 | ||
22668 | “r+” | |
22669 | ||
22670 | @tab | |
22671 | ||
22672 | “w+” | |
22673 | ||
22674 | @end multitable | |
22675 | ||
22676 | ||
22677 | If text file translation is required, then either @code{b} or @code{t} | |
22678 | is added to the mode, depending on the setting of Text. Text file | |
22679 | translation refers to the mapping of CR/LF sequences in an external file | |
22680 | to LF characters internally. This mapping only occurs in DOS and | |
22681 | DOS-like systems, and is not relevant to other systems. | |
22682 | ||
22683 | A special case occurs with Stream_IO. As shown in the above table, the | |
22684 | file is initially opened in @code{r} or @code{w} mode for the | |
22685 | @code{In_File} and @code{Out_File} cases. If a @code{Set_Mode} operation | |
22686 | subsequently requires switching from reading to writing or vice-versa, | |
22687 | then the file is reopened in @code{r+} mode to permit the required operation. | |
22688 | ||
22689 | @node Operations on C Streams,Interfacing to C Streams,Open Modes,The Implementation of Standard I/O | |
04d6c745 | 22690 | @anchor{gnat_rm/the_implementation_of_standard_i_o id25}@anchor{2da}@anchor{gnat_rm/the_implementation_of_standard_i_o operations-on-c-streams}@anchor{2db} |
64d5610f ML |
22691 | @section Operations on C Streams |
22692 | ||
22693 | ||
22694 | The package @code{Interfaces.C_Streams} provides an Ada program with direct | |
22695 | access to the C library functions for operations on C streams: | |
22696 | ||
22697 | @example | |
22698 | package Interfaces.C_Streams is | |
22699 | -- Note: the reason we do not use the types that are in | |
22700 | -- Interfaces.C is that we want to avoid dragging in the | |
22701 | -- code in this unit if possible. | |
22702 | subtype chars is System.Address; | |
22703 | -- Pointer to null-terminated array of characters | |
22704 | subtype FILEs is System.Address; | |
22705 | -- Corresponds to the C type FILE* | |
22706 | subtype voids is System.Address; | |
22707 | -- Corresponds to the C type void* | |
22708 | subtype int is Integer; | |
22709 | subtype long is Long_Integer; | |
22710 | -- Note: the above types are subtypes deliberately, and it | |
22711 | -- is part of this spec that the above correspondences are | |
22712 | -- guaranteed. This means that it is legitimate to, for | |
22713 | -- example, use Integer instead of int. We provide these | |
22714 | -- synonyms for clarity, but in some cases it may be | |
22715 | -- convenient to use the underlying types (for example to | |
22716 | -- avoid an unnecessary dependency of a spec on the spec | |
22717 | -- of this unit). | |
22718 | type size_t is mod 2 ** Standard'Address_Size; | |
22719 | NULL_Stream : constant FILEs; | |
22720 | -- Value returned (NULL in C) to indicate an | |
22721 | -- fdopen/fopen/tmpfile error | |
22722 | ---------------------------------- | |
22723 | -- Constants Defined in stdio.h -- | |
22724 | ---------------------------------- | |
22725 | EOF : constant int; | |
22726 | -- Used by a number of routines to indicate error or | |
22727 | -- end of file | |
22728 | IOFBF : constant int; | |
22729 | IOLBF : constant int; | |
22730 | IONBF : constant int; | |
22731 | -- Used to indicate buffering mode for setvbuf call | |
22732 | SEEK_CUR : constant int; | |
22733 | SEEK_END : constant int; | |
22734 | SEEK_SET : constant int; | |
22735 | -- Used to indicate origin for fseek call | |
22736 | function stdin return FILEs; | |
22737 | function stdout return FILEs; | |
22738 | function stderr return FILEs; | |
22739 | -- Streams associated with standard files | |
22740 | -------------------------- | |
22741 | -- Standard C functions -- | |
22742 | -------------------------- | |
22743 | -- The functions selected below are ones that are | |
22744 | -- available in UNIX (but not necessarily in ANSI C). | |
22745 | -- These are very thin interfaces | |
22746 | -- which copy exactly the C headers. For more | |
22747 | -- documentation on these functions, see the Microsoft C | |
22748 | -- "Run-Time Library Reference" (Microsoft Press, 1990, | |
22749 | -- ISBN 1-55615-225-6), which includes useful information | |
22750 | -- on system compatibility. | |
22751 | procedure clearerr (stream : FILEs); | |
22752 | function fclose (stream : FILEs) return int; | |
22753 | function fdopen (handle : int; mode : chars) return FILEs; | |
22754 | function feof (stream : FILEs) return int; | |
22755 | function ferror (stream : FILEs) return int; | |
22756 | function fflush (stream : FILEs) return int; | |
22757 | function fgetc (stream : FILEs) return int; | |
22758 | function fgets (strng : chars; n : int; stream : FILEs) | |
22759 | return chars; | |
22760 | function fileno (stream : FILEs) return int; | |
22761 | function fopen (filename : chars; Mode : chars) | |
22762 | return FILEs; | |
22763 | -- Note: to maintain target independence, use | |
22764 | -- text_translation_required, a boolean variable defined in | |
22765 | -- a-sysdep.c to deal with the target dependent text | |
22766 | -- translation requirement. If this variable is set, | |
22767 | -- then b/t should be appended to the standard mode | |
22768 | -- argument to set the text translation mode off or on | |
22769 | -- as required. | |
22770 | function fputc (C : int; stream : FILEs) return int; | |
22771 | function fputs (Strng : chars; Stream : FILEs) return int; | |
22772 | function fread | |
22773 | (buffer : voids; | |
22774 | size : size_t; | |
22775 | count : size_t; | |
22776 | stream : FILEs) | |
22777 | return size_t; | |
22778 | function freopen | |
22779 | (filename : chars; | |
22780 | mode : chars; | |
22781 | stream : FILEs) | |
22782 | return FILEs; | |
22783 | function fseek | |
22784 | (stream : FILEs; | |
22785 | offset : long; | |
22786 | origin : int) | |
22787 | return int; | |
22788 | function ftell (stream : FILEs) return long; | |
22789 | function fwrite | |
22790 | (buffer : voids; | |
22791 | size : size_t; | |
22792 | count : size_t; | |
22793 | stream : FILEs) | |
22794 | return size_t; | |
22795 | function isatty (handle : int) return int; | |
22796 | procedure mktemp (template : chars); | |
22797 | -- The return value (which is just a pointer to template) | |
22798 | -- is discarded | |
22799 | procedure rewind (stream : FILEs); | |
22800 | function rmtmp return int; | |
22801 | function setvbuf | |
22802 | (stream : FILEs; | |
22803 | buffer : chars; | |
22804 | mode : int; | |
22805 | size : size_t) | |
22806 | return int; | |
22807 | ||
22808 | function tmpfile return FILEs; | |
22809 | function ungetc (c : int; stream : FILEs) return int; | |
22810 | function unlink (filename : chars) return int; | |
22811 | --------------------- | |
22812 | -- Extra functions -- | |
22813 | --------------------- | |
22814 | -- These functions supply slightly thicker bindings than | |
22815 | -- those above. They are derived from functions in the | |
22816 | -- C Run-Time Library, but may do a bit more work than | |
22817 | -- just directly calling one of the Library functions. | |
22818 | function is_regular_file (handle : int) return int; | |
22819 | -- Tests if given handle is for a regular file (result 1) | |
22820 | -- or for a non-regular file (pipe or device, result 0). | |
22821 | --------------------------------- | |
22822 | -- Control of Text/Binary Mode -- | |
22823 | --------------------------------- | |
22824 | -- If text_translation_required is true, then the following | |
22825 | -- functions may be used to dynamically switch a file from | |
22826 | -- binary to text mode or vice versa. These functions have | |
22827 | -- no effect if text_translation_required is false (i.e., in | |
22828 | -- normal UNIX mode). Use fileno to get a stream handle. | |
22829 | procedure set_binary_mode (handle : int); | |
22830 | procedure set_text_mode (handle : int); | |
22831 | ---------------------------- | |
22832 | -- Full Path Name support -- | |
22833 | ---------------------------- | |
22834 | procedure full_name (nam : chars; buffer : chars); | |
22835 | -- Given a NUL terminated string representing a file | |
22836 | -- name, returns in buffer a NUL terminated string | |
22837 | -- representing the full path name for the file name. | |
22838 | -- On systems where it is relevant the drive is also | |
22839 | -- part of the full path name. It is the responsibility | |
22840 | -- of the caller to pass an actual parameter for buffer | |
22841 | -- that is big enough for any full path name. Use | |
22842 | -- max_path_len given below as the size of buffer. | |
22843 | max_path_len : integer; | |
22844 | -- Maximum length of an allowable full path name on the | |
22845 | -- system, including a terminating NUL character. | |
22846 | end Interfaces.C_Streams; | |
22847 | @end example | |
22848 | ||
22849 | @node Interfacing to C Streams,,Operations on C Streams,The Implementation of Standard I/O | |
04d6c745 | 22850 | @anchor{gnat_rm/the_implementation_of_standard_i_o id26}@anchor{2dc}@anchor{gnat_rm/the_implementation_of_standard_i_o interfacing-to-c-streams}@anchor{2dd} |
64d5610f ML |
22851 | @section Interfacing to C Streams |
22852 | ||
22853 | ||
22854 | The packages in this section permit interfacing Ada files to C Stream | |
22855 | operations. | |
22856 | ||
22857 | @example | |
22858 | with Interfaces.C_Streams; | |
22859 | package Ada.Sequential_IO.C_Streams is | |
22860 | function C_Stream (F : File_Type) | |
22861 | return Interfaces.C_Streams.FILEs; | |
22862 | procedure Open | |
22863 | (File : in out File_Type; | |
22864 | Mode : in File_Mode; | |
22865 | C_Stream : in Interfaces.C_Streams.FILEs; | |
22866 | Form : in String := ""); | |
22867 | end Ada.Sequential_IO.C_Streams; | |
22868 | ||
22869 | with Interfaces.C_Streams; | |
22870 | package Ada.Direct_IO.C_Streams is | |
22871 | function C_Stream (F : File_Type) | |
22872 | return Interfaces.C_Streams.FILEs; | |
22873 | procedure Open | |
22874 | (File : in out File_Type; | |
22875 | Mode : in File_Mode; | |
22876 | C_Stream : in Interfaces.C_Streams.FILEs; | |
22877 | Form : in String := ""); | |
22878 | end Ada.Direct_IO.C_Streams; | |
22879 | ||
22880 | with Interfaces.C_Streams; | |
22881 | package Ada.Text_IO.C_Streams is | |
22882 | function C_Stream (F : File_Type) | |
22883 | return Interfaces.C_Streams.FILEs; | |
22884 | procedure Open | |
22885 | (File : in out File_Type; | |
22886 | Mode : in File_Mode; | |
22887 | C_Stream : in Interfaces.C_Streams.FILEs; | |
22888 | Form : in String := ""); | |
22889 | end Ada.Text_IO.C_Streams; | |
22890 | ||
22891 | with Interfaces.C_Streams; | |
22892 | package Ada.Wide_Text_IO.C_Streams is | |
22893 | function C_Stream (F : File_Type) | |
22894 | return Interfaces.C_Streams.FILEs; | |
22895 | procedure Open | |
22896 | (File : in out File_Type; | |
22897 | Mode : in File_Mode; | |
22898 | C_Stream : in Interfaces.C_Streams.FILEs; | |
22899 | Form : in String := ""); | |
22900 | end Ada.Wide_Text_IO.C_Streams; | |
22901 | ||
22902 | with Interfaces.C_Streams; | |
22903 | package Ada.Wide_Wide_Text_IO.C_Streams is | |
22904 | function C_Stream (F : File_Type) | |
22905 | return Interfaces.C_Streams.FILEs; | |
22906 | procedure Open | |
22907 | (File : in out File_Type; | |
22908 | Mode : in File_Mode; | |
22909 | C_Stream : in Interfaces.C_Streams.FILEs; | |
22910 | Form : in String := ""); | |
22911 | end Ada.Wide_Wide_Text_IO.C_Streams; | |
22912 | ||
22913 | with Interfaces.C_Streams; | |
22914 | package Ada.Stream_IO.C_Streams is | |
22915 | function C_Stream (F : File_Type) | |
22916 | return Interfaces.C_Streams.FILEs; | |
22917 | procedure Open | |
22918 | (File : in out File_Type; | |
22919 | Mode : in File_Mode; | |
22920 | C_Stream : in Interfaces.C_Streams.FILEs; | |
22921 | Form : in String := ""); | |
22922 | end Ada.Stream_IO.C_Streams; | |
22923 | @end example | |
22924 | ||
22925 | In each of these six packages, the @code{C_Stream} function obtains the | |
22926 | @code{FILE} pointer from a currently opened Ada file. It is then | |
22927 | possible to use the @code{Interfaces.C_Streams} package to operate on | |
22928 | this stream, or the stream can be passed to a C program which can | |
22929 | operate on it directly. Of course the program is responsible for | |
22930 | ensuring that only appropriate sequences of operations are executed. | |
22931 | ||
22932 | One particular use of relevance to an Ada program is that the | |
22933 | @code{setvbuf} function can be used to control the buffering of the | |
22934 | stream used by an Ada file. In the absence of such a call the standard | |
22935 | default buffering is used. | |
22936 | ||
22937 | The @code{Open} procedures in these packages open a file giving an | |
22938 | existing C Stream instead of a file name. Typically this stream is | |
22939 | imported from a C program, allowing an Ada file to operate on an | |
22940 | existing C file. | |
22941 | ||
22942 | @node The GNAT Library,Interfacing to Other Languages,The Implementation of Standard I/O,Top | |
04d6c745 | 22943 | @anchor{gnat_rm/the_gnat_library doc}@anchor{2de}@anchor{gnat_rm/the_gnat_library id1}@anchor{2df}@anchor{gnat_rm/the_gnat_library the-gnat-library}@anchor{10} |
64d5610f ML |
22944 | @chapter The GNAT Library |
22945 | ||
22946 | ||
22947 | The GNAT library contains a number of general and special purpose packages. | |
22948 | It represents functionality that the GNAT developers have found useful, and | |
22949 | which is made available to GNAT users. The packages described here are fully | |
22950 | supported, and upwards compatibility will be maintained in future releases, | |
22951 | so you can use these facilities with the confidence that the same functionality | |
22952 | will be available in future releases. | |
22953 | ||
22954 | The chapter here simply gives a brief summary of the facilities available. | |
22955 | The full documentation is found in the spec file for the package. The full | |
22956 | sources of these library packages, including both spec and body, are provided | |
22957 | with all GNAT releases. For example, to find out the full specifications of | |
22958 | the SPITBOL pattern matching capability, including a full tutorial and | |
22959 | extensive examples, look in the @code{g-spipat.ads} file in the library. | |
22960 | ||
22961 | For each entry here, the package name (as it would appear in a @code{with} | |
22962 | clause) is given, followed by the name of the corresponding spec file in | |
22963 | parentheses. The packages are children in four hierarchies, @code{Ada}, | |
22964 | @code{Interfaces}, @code{System}, and @code{GNAT}, the latter being a | |
22965 | GNAT-specific hierarchy. | |
22966 | ||
22967 | Note that an application program should only use packages in one of these | |
22968 | four hierarchies if the package is defined in the Ada Reference Manual, | |
22969 | or is listed in this section of the GNAT Programmers Reference Manual. | |
22970 | All other units should be considered internal implementation units and | |
22971 | should not be directly @code{with}ed by application code. The use of | |
22972 | a @code{with} clause that references one of these internal implementation | |
22973 | units makes an application potentially dependent on changes in versions | |
22974 | of GNAT, and will generate a warning message. | |
22975 | ||
22976 | @menu | |
22977 | * Ada.Characters.Latin_9 (a-chlat9.ads): Ada Characters Latin_9 a-chlat9 ads. | |
22978 | * Ada.Characters.Wide_Latin_1 (a-cwila1.ads): Ada Characters Wide_Latin_1 a-cwila1 ads. | |
eeba836b | 22979 | * Ada.Characters.Wide_Latin_9 (a-cwila9.ads): Ada Characters Wide_Latin_9 a-cwila9 ads. |
64d5610f ML |
22980 | * Ada.Characters.Wide_Wide_Latin_1 (a-chzla1.ads): Ada Characters Wide_Wide_Latin_1 a-chzla1 ads. |
22981 | * Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads): Ada Characters Wide_Wide_Latin_9 a-chzla9 ads. | |
22982 | * Ada.Containers.Bounded_Holders (a-coboho.ads): Ada Containers Bounded_Holders a-coboho ads. | |
22983 | * Ada.Command_Line.Environment (a-colien.ads): Ada Command_Line Environment a-colien ads. | |
22984 | * Ada.Command_Line.Remove (a-colire.ads): Ada Command_Line Remove a-colire ads. | |
22985 | * Ada.Command_Line.Response_File (a-clrefi.ads): Ada Command_Line Response_File a-clrefi ads. | |
22986 | * Ada.Direct_IO.C_Streams (a-diocst.ads): Ada Direct_IO C_Streams a-diocst ads. | |
22987 | * Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads): Ada Exceptions Is_Null_Occurrence a-einuoc ads. | |
22988 | * Ada.Exceptions.Last_Chance_Handler (a-elchha.ads): Ada Exceptions Last_Chance_Handler a-elchha ads. | |
22989 | * Ada.Exceptions.Traceback (a-exctra.ads): Ada Exceptions Traceback a-exctra ads. | |
22990 | * Ada.Sequential_IO.C_Streams (a-siocst.ads): Ada Sequential_IO C_Streams a-siocst ads. | |
22991 | * Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads): Ada Streams Stream_IO C_Streams a-ssicst ads. | |
22992 | * Ada.Strings.Unbounded.Text_IO (a-suteio.ads): Ada Strings Unbounded Text_IO a-suteio ads. | |
22993 | * Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads): Ada Strings Wide_Unbounded Wide_Text_IO a-swuwti ads. | |
22994 | * Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads): Ada Strings Wide_Wide_Unbounded Wide_Wide_Text_IO a-szuzti ads. | |
22995 | * Ada.Task_Initialization (a-tasini.ads): Ada Task_Initialization a-tasini ads. | |
22996 | * Ada.Text_IO.C_Streams (a-tiocst.ads): Ada Text_IO C_Streams a-tiocst ads. | |
22997 | * Ada.Text_IO.Reset_Standard_Files (a-tirsfi.ads): Ada Text_IO Reset_Standard_Files a-tirsfi ads. | |
22998 | * Ada.Wide_Characters.Unicode (a-wichun.ads): Ada Wide_Characters Unicode a-wichun ads. | |
22999 | * Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads): Ada Wide_Text_IO C_Streams a-wtcstr ads. | |
23000 | * Ada.Wide_Text_IO.Reset_Standard_Files (a-wrstfi.ads): Ada Wide_Text_IO Reset_Standard_Files a-wrstfi ads. | |
23001 | * Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads): Ada Wide_Wide_Characters Unicode a-zchuni ads. | |
23002 | * Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads): Ada Wide_Wide_Text_IO C_Streams a-ztcstr ads. | |
23003 | * Ada.Wide_Wide_Text_IO.Reset_Standard_Files (a-zrstfi.ads): Ada Wide_Wide_Text_IO Reset_Standard_Files a-zrstfi ads. | |
23004 | * GNAT.Altivec (g-altive.ads): GNAT Altivec g-altive ads. | |
23005 | * GNAT.Altivec.Conversions (g-altcon.ads): GNAT Altivec Conversions g-altcon ads. | |
23006 | * GNAT.Altivec.Vector_Operations (g-alveop.ads): GNAT Altivec Vector_Operations g-alveop ads. | |
23007 | * GNAT.Altivec.Vector_Types (g-alvety.ads): GNAT Altivec Vector_Types g-alvety ads. | |
23008 | * GNAT.Altivec.Vector_Views (g-alvevi.ads): GNAT Altivec Vector_Views g-alvevi ads. | |
23009 | * GNAT.Array_Split (g-arrspl.ads): GNAT Array_Split g-arrspl ads. | |
23010 | * GNAT.AWK (g-awk.ads): GNAT AWK g-awk ads. | |
23011 | * GNAT.Binary_Search (g-binsea.ads): GNAT Binary_Search g-binsea ads. | |
23012 | * GNAT.Bind_Environment (g-binenv.ads): GNAT Bind_Environment g-binenv ads. | |
23013 | * GNAT.Branch_Prediction (g-brapre.ads): GNAT Branch_Prediction g-brapre ads. | |
23014 | * GNAT.Bounded_Buffers (g-boubuf.ads): GNAT Bounded_Buffers g-boubuf ads. | |
23015 | * GNAT.Bounded_Mailboxes (g-boumai.ads): GNAT Bounded_Mailboxes g-boumai ads. | |
23016 | * GNAT.Bubble_Sort (g-bubsor.ads): GNAT Bubble_Sort g-bubsor ads. | |
23017 | * GNAT.Bubble_Sort_A (g-busora.ads): GNAT Bubble_Sort_A g-busora ads. | |
23018 | * GNAT.Bubble_Sort_G (g-busorg.ads): GNAT Bubble_Sort_G g-busorg ads. | |
23019 | * GNAT.Byte_Order_Mark (g-byorma.ads): GNAT Byte_Order_Mark g-byorma ads. | |
23020 | * GNAT.Byte_Swapping (g-bytswa.ads): GNAT Byte_Swapping g-bytswa ads. | |
23021 | * GNAT.Calendar (g-calend.ads): GNAT Calendar g-calend ads. | |
23022 | * GNAT.Calendar.Time_IO (g-catiio.ads): GNAT Calendar Time_IO g-catiio ads. | |
23023 | * GNAT.CRC32 (g-crc32.ads): GNAT CRC32 g-crc32 ads. | |
23024 | * GNAT.Case_Util (g-casuti.ads): GNAT Case_Util g-casuti ads. | |
23025 | * GNAT.CGI (g-cgi.ads): GNAT CGI g-cgi ads. | |
23026 | * GNAT.CGI.Cookie (g-cgicoo.ads): GNAT CGI Cookie g-cgicoo ads. | |
23027 | * GNAT.CGI.Debug (g-cgideb.ads): GNAT CGI Debug g-cgideb ads. | |
23028 | * GNAT.Command_Line (g-comlin.ads): GNAT Command_Line g-comlin ads. | |
23029 | * GNAT.Compiler_Version (g-comver.ads): GNAT Compiler_Version g-comver ads. | |
23030 | * GNAT.Ctrl_C (g-ctrl_c.ads): GNAT Ctrl_C g-ctrl_c ads. | |
23031 | * GNAT.Current_Exception (g-curexc.ads): GNAT Current_Exception g-curexc ads. | |
23032 | * GNAT.Debug_Pools (g-debpoo.ads): GNAT Debug_Pools g-debpoo ads. | |
23033 | * GNAT.Debug_Utilities (g-debuti.ads): GNAT Debug_Utilities g-debuti ads. | |
23034 | * GNAT.Decode_String (g-decstr.ads): GNAT Decode_String g-decstr ads. | |
23035 | * GNAT.Decode_UTF8_String (g-deutst.ads): GNAT Decode_UTF8_String g-deutst ads. | |
23036 | * GNAT.Directory_Operations (g-dirope.ads): GNAT Directory_Operations g-dirope ads. | |
23037 | * GNAT.Directory_Operations.Iteration (g-diopit.ads): GNAT Directory_Operations Iteration g-diopit ads. | |
23038 | * GNAT.Dynamic_HTables (g-dynhta.ads): GNAT Dynamic_HTables g-dynhta ads. | |
23039 | * GNAT.Dynamic_Tables (g-dyntab.ads): GNAT Dynamic_Tables g-dyntab ads. | |
23040 | * GNAT.Encode_String (g-encstr.ads): GNAT Encode_String g-encstr ads. | |
23041 | * GNAT.Encode_UTF8_String (g-enutst.ads): GNAT Encode_UTF8_String g-enutst ads. | |
23042 | * GNAT.Exception_Actions (g-excact.ads): GNAT Exception_Actions g-excact ads. | |
23043 | * GNAT.Exception_Traces (g-exctra.ads): GNAT Exception_Traces g-exctra ads. | |
23044 | * GNAT.Exceptions (g-except.ads): GNAT Exceptions g-except ads. | |
23045 | * GNAT.Expect (g-expect.ads): GNAT Expect g-expect ads. | |
23046 | * GNAT.Expect.TTY (g-exptty.ads): GNAT Expect TTY g-exptty ads. | |
23047 | * GNAT.Float_Control (g-flocon.ads): GNAT Float_Control g-flocon ads. | |
23048 | * GNAT.Formatted_String (g-forstr.ads): GNAT Formatted_String g-forstr ads. | |
23049 | * GNAT.Generic_Fast_Math_Functions (g-gfmafu.ads): GNAT Generic_Fast_Math_Functions g-gfmafu ads. | |
23050 | * GNAT.Heap_Sort (g-heasor.ads): GNAT Heap_Sort g-heasor ads. | |
23051 | * GNAT.Heap_Sort_A (g-hesora.ads): GNAT Heap_Sort_A g-hesora ads. | |
23052 | * GNAT.Heap_Sort_G (g-hesorg.ads): GNAT Heap_Sort_G g-hesorg ads. | |
23053 | * GNAT.HTable (g-htable.ads): GNAT HTable g-htable ads. | |
23054 | * GNAT.IO (g-io.ads): GNAT IO g-io ads. | |
23055 | * GNAT.IO_Aux (g-io_aux.ads): GNAT IO_Aux g-io_aux ads. | |
23056 | * GNAT.Lock_Files (g-locfil.ads): GNAT Lock_Files g-locfil ads. | |
23057 | * GNAT.MBBS_Discrete_Random (g-mbdira.ads): GNAT MBBS_Discrete_Random g-mbdira ads. | |
23058 | * GNAT.MBBS_Float_Random (g-mbflra.ads): GNAT MBBS_Float_Random g-mbflra ads. | |
23059 | * GNAT.MD5 (g-md5.ads): GNAT MD5 g-md5 ads. | |
23060 | * GNAT.Memory_Dump (g-memdum.ads): GNAT Memory_Dump g-memdum ads. | |
23061 | * GNAT.Most_Recent_Exception (g-moreex.ads): GNAT Most_Recent_Exception g-moreex ads. | |
23062 | * GNAT.OS_Lib (g-os_lib.ads): GNAT OS_Lib g-os_lib ads. | |
23063 | * GNAT.Perfect_Hash_Generators (g-pehage.ads): GNAT Perfect_Hash_Generators g-pehage ads. | |
23064 | * GNAT.Random_Numbers (g-rannum.ads): GNAT Random_Numbers g-rannum ads. | |
23065 | * GNAT.Regexp (g-regexp.ads): GNAT Regexp g-regexp ads. | |
23066 | * GNAT.Registry (g-regist.ads): GNAT Registry g-regist ads. | |
23067 | * GNAT.Regpat (g-regpat.ads): GNAT Regpat g-regpat ads. | |
23068 | * GNAT.Rewrite_Data (g-rewdat.ads): GNAT Rewrite_Data g-rewdat ads. | |
23069 | * GNAT.Secondary_Stack_Info (g-sestin.ads): GNAT Secondary_Stack_Info g-sestin ads. | |
23070 | * GNAT.Semaphores (g-semaph.ads): GNAT Semaphores g-semaph ads. | |
23071 | * GNAT.Serial_Communications (g-sercom.ads): GNAT Serial_Communications g-sercom ads. | |
23072 | * GNAT.SHA1 (g-sha1.ads): GNAT SHA1 g-sha1 ads. | |
23073 | * GNAT.SHA224 (g-sha224.ads): GNAT SHA224 g-sha224 ads. | |
23074 | * GNAT.SHA256 (g-sha256.ads): GNAT SHA256 g-sha256 ads. | |
23075 | * GNAT.SHA384 (g-sha384.ads): GNAT SHA384 g-sha384 ads. | |
23076 | * GNAT.SHA512 (g-sha512.ads): GNAT SHA512 g-sha512 ads. | |
23077 | * GNAT.Signals (g-signal.ads): GNAT Signals g-signal ads. | |
23078 | * GNAT.Sockets (g-socket.ads): GNAT Sockets g-socket ads. | |
23079 | * GNAT.Source_Info (g-souinf.ads): GNAT Source_Info g-souinf ads. | |
23080 | * GNAT.Spelling_Checker (g-speche.ads): GNAT Spelling_Checker g-speche ads. | |
23081 | * GNAT.Spelling_Checker_Generic (g-spchge.ads): GNAT Spelling_Checker_Generic g-spchge ads. | |
23082 | * GNAT.Spitbol.Patterns (g-spipat.ads): GNAT Spitbol Patterns g-spipat ads. | |
23083 | * GNAT.Spitbol (g-spitbo.ads): GNAT Spitbol g-spitbo ads. | |
23084 | * GNAT.Spitbol.Table_Boolean (g-sptabo.ads): GNAT Spitbol Table_Boolean g-sptabo ads. | |
23085 | * GNAT.Spitbol.Table_Integer (g-sptain.ads): GNAT Spitbol Table_Integer g-sptain ads. | |
23086 | * GNAT.Spitbol.Table_VString (g-sptavs.ads): GNAT Spitbol Table_VString g-sptavs ads. | |
23087 | * GNAT.SSE (g-sse.ads): GNAT SSE g-sse ads. | |
23088 | * GNAT.SSE.Vector_Types (g-ssvety.ads): GNAT SSE Vector_Types g-ssvety ads. | |
23089 | * GNAT.String_Hash (g-strhas.ads): GNAT String_Hash g-strhas ads. | |
23090 | * GNAT.Strings (g-string.ads): GNAT Strings g-string ads. | |
23091 | * GNAT.String_Split (g-strspl.ads): GNAT String_Split g-strspl ads. | |
23092 | * GNAT.Table (g-table.ads): GNAT Table g-table ads. | |
23093 | * GNAT.Task_Lock (g-tasloc.ads): GNAT Task_Lock g-tasloc ads. | |
23094 | * GNAT.Time_Stamp (g-timsta.ads): GNAT Time_Stamp g-timsta ads. | |
23095 | * GNAT.Threads (g-thread.ads): GNAT Threads g-thread ads. | |
23096 | * GNAT.Traceback (g-traceb.ads): GNAT Traceback g-traceb ads. | |
23097 | * GNAT.Traceback.Symbolic (g-trasym.ads): GNAT Traceback Symbolic g-trasym ads. | |
eeba836b RD |
23098 | * GNAT.UTF_32 (g-utf_32.ads): GNAT UTF_32 g-utf_32 ads. |
23099 | * GNAT.UTF_32_Spelling_Checker (g-u3spch.ads): GNAT UTF_32_Spelling_Checker g-u3spch ads. | |
64d5610f ML |
23100 | * GNAT.Wide_Spelling_Checker (g-wispch.ads): GNAT Wide_Spelling_Checker g-wispch ads. |
23101 | * GNAT.Wide_String_Split (g-wistsp.ads): GNAT Wide_String_Split g-wistsp ads. | |
23102 | * GNAT.Wide_Wide_Spelling_Checker (g-zspche.ads): GNAT Wide_Wide_Spelling_Checker g-zspche ads. | |
23103 | * GNAT.Wide_Wide_String_Split (g-zistsp.ads): GNAT Wide_Wide_String_Split g-zistsp ads. | |
23104 | * Interfaces.C.Extensions (i-cexten.ads): Interfaces C Extensions i-cexten ads. | |
23105 | * Interfaces.C.Streams (i-cstrea.ads): Interfaces C Streams i-cstrea ads. | |
23106 | * Interfaces.Packed_Decimal (i-pacdec.ads): Interfaces Packed_Decimal i-pacdec ads. | |
23107 | * Interfaces.VxWorks (i-vxwork.ads): Interfaces VxWorks i-vxwork ads. | |
23108 | * Interfaces.VxWorks.Int_Connection (i-vxinco.ads): Interfaces VxWorks Int_Connection i-vxinco ads. | |
23109 | * Interfaces.VxWorks.IO (i-vxwoio.ads): Interfaces VxWorks IO i-vxwoio ads. | |
23110 | * System.Address_Image (s-addima.ads): System Address_Image s-addima ads. | |
23111 | * System.Assertions (s-assert.ads): System Assertions s-assert ads. | |
23112 | * System.Atomic_Counters (s-atocou.ads): System Atomic_Counters s-atocou ads. | |
23113 | * System.Memory (s-memory.ads): System Memory s-memory ads. | |
23114 | * System.Multiprocessors (s-multip.ads): System Multiprocessors s-multip ads. | |
23115 | * System.Multiprocessors.Dispatching_Domains (s-mudido.ads): System Multiprocessors Dispatching_Domains s-mudido ads. | |
23116 | * System.Partition_Interface (s-parint.ads): System Partition_Interface s-parint ads. | |
23117 | * System.Pool_Global (s-pooglo.ads): System Pool_Global s-pooglo ads. | |
23118 | * System.Pool_Local (s-pooloc.ads): System Pool_Local s-pooloc ads. | |
23119 | * System.Restrictions (s-restri.ads): System Restrictions s-restri ads. | |
23120 | * System.Rident (s-rident.ads): System Rident s-rident ads. | |
23121 | * System.Strings.Stream_Ops (s-ststop.ads): System Strings Stream_Ops s-ststop ads. | |
23122 | * System.Unsigned_Types (s-unstyp.ads): System Unsigned_Types s-unstyp ads. | |
23123 | * System.Wch_Cnv (s-wchcnv.ads): System Wch_Cnv s-wchcnv ads. | |
23124 | * System.Wch_Con (s-wchcon.ads): System Wch_Con s-wchcon ads. | |
23125 | ||
23126 | @end menu | |
23127 | ||
23128 | @node Ada Characters Latin_9 a-chlat9 ads,Ada Characters Wide_Latin_1 a-cwila1 ads,,The GNAT Library | |
04d6c745 | 23129 | @anchor{gnat_rm/the_gnat_library ada-characters-latin-9-a-chlat9-ads}@anchor{2e0}@anchor{gnat_rm/the_gnat_library id2}@anchor{2e1} |
64d5610f ML |
23130 | @section @code{Ada.Characters.Latin_9} (@code{a-chlat9.ads}) |
23131 | ||
23132 | ||
23133 | @geindex Ada.Characters.Latin_9 (a-chlat9.ads) | |
23134 | ||
23135 | @geindex Latin_9 constants for Character | |
23136 | ||
23137 | This child of @code{Ada.Characters} | |
23138 | provides a set of definitions corresponding to those in the | |
23139 | RM-defined package @code{Ada.Characters.Latin_1} but with the | |
eeba836b | 23140 | few modifications required for @code{Latin-9}. |
64d5610f ML |
23141 | The provision of such a package |
23142 | is specifically authorized by the Ada Reference Manual | |
23143 | (RM A.3.3(27)). | |
23144 | ||
eeba836b | 23145 | @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 |
04d6c745 | 23146 | @anchor{gnat_rm/the_gnat_library ada-characters-wide-latin-1-a-cwila1-ads}@anchor{2e2}@anchor{gnat_rm/the_gnat_library id3}@anchor{2e3} |
64d5610f ML |
23147 | @section @code{Ada.Characters.Wide_Latin_1} (@code{a-cwila1.ads}) |
23148 | ||
23149 | ||
23150 | @geindex Ada.Characters.Wide_Latin_1 (a-cwila1.ads) | |
23151 | ||
23152 | @geindex Latin_1 constants for Wide_Character | |
23153 | ||
23154 | This child of @code{Ada.Characters} | |
23155 | provides a set of definitions corresponding to those in the | |
23156 | RM-defined package @code{Ada.Characters.Latin_1} but with the | |
23157 | types of the constants being @code{Wide_Character} | |
23158 | instead of @code{Character}. The provision of such a package | |
23159 | is specifically authorized by the Ada Reference Manual | |
23160 | (RM A.3.3(27)). | |
23161 | ||
eeba836b | 23162 | @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 |
04d6c745 | 23163 | @anchor{gnat_rm/the_gnat_library ada-characters-wide-latin-9-a-cwila9-ads}@anchor{2e4}@anchor{gnat_rm/the_gnat_library id4}@anchor{2e5} |
eeba836b | 23164 | @section @code{Ada.Characters.Wide_Latin_9} (@code{a-cwila9.ads}) |
64d5610f ML |
23165 | |
23166 | ||
eeba836b | 23167 | @geindex Ada.Characters.Wide_Latin_9 (a-cwila9.ads) |
64d5610f ML |
23168 | |
23169 | @geindex Latin_9 constants for Wide_Character | |
23170 | ||
23171 | This child of @code{Ada.Characters} | |
23172 | provides a set of definitions corresponding to those in the | |
23173 | GNAT defined package @code{Ada.Characters.Latin_9} but with the | |
23174 | types of the constants being @code{Wide_Character} | |
23175 | instead of @code{Character}. The provision of such a package | |
23176 | is specifically authorized by the Ada Reference Manual | |
23177 | (RM A.3.3(27)). | |
23178 | ||
eeba836b | 23179 | @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 |
04d6c745 | 23180 | @anchor{gnat_rm/the_gnat_library ada-characters-wide-wide-latin-1-a-chzla1-ads}@anchor{2e6}@anchor{gnat_rm/the_gnat_library id5}@anchor{2e7} |
64d5610f ML |
23181 | @section @code{Ada.Characters.Wide_Wide_Latin_1} (@code{a-chzla1.ads}) |
23182 | ||
23183 | ||
23184 | @geindex Ada.Characters.Wide_Wide_Latin_1 (a-chzla1.ads) | |
23185 | ||
23186 | @geindex Latin_1 constants for Wide_Wide_Character | |
23187 | ||
23188 | This child of @code{Ada.Characters} | |
23189 | provides a set of definitions corresponding to those in the | |
23190 | RM-defined package @code{Ada.Characters.Latin_1} but with the | |
23191 | types of the constants being @code{Wide_Wide_Character} | |
23192 | instead of @code{Character}. The provision of such a package | |
23193 | is specifically authorized by the Ada Reference Manual | |
23194 | (RM A.3.3(27)). | |
23195 | ||
23196 | @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 | |
04d6c745 | 23197 | @anchor{gnat_rm/the_gnat_library ada-characters-wide-wide-latin-9-a-chzla9-ads}@anchor{2e8}@anchor{gnat_rm/the_gnat_library id6}@anchor{2e9} |
64d5610f ML |
23198 | @section @code{Ada.Characters.Wide_Wide_Latin_9} (@code{a-chzla9.ads}) |
23199 | ||
23200 | ||
23201 | @geindex Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads) | |
23202 | ||
23203 | @geindex Latin_9 constants for Wide_Wide_Character | |
23204 | ||
23205 | This child of @code{Ada.Characters} | |
23206 | provides a set of definitions corresponding to those in the | |
23207 | GNAT defined package @code{Ada.Characters.Latin_9} but with the | |
23208 | types of the constants being @code{Wide_Wide_Character} | |
23209 | instead of @code{Character}. The provision of such a package | |
23210 | is specifically authorized by the Ada Reference Manual | |
23211 | (RM A.3.3(27)). | |
23212 | ||
23213 | @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 | |
04d6c745 | 23214 | @anchor{gnat_rm/the_gnat_library ada-containers-bounded-holders-a-coboho-ads}@anchor{2ea}@anchor{gnat_rm/the_gnat_library id7}@anchor{2eb} |
64d5610f ML |
23215 | @section @code{Ada.Containers.Bounded_Holders} (@code{a-coboho.ads}) |
23216 | ||
23217 | ||
23218 | @geindex Ada.Containers.Bounded_Holders (a-coboho.ads) | |
23219 | ||
23220 | @geindex Formal container for vectors | |
23221 | ||
23222 | This child of @code{Ada.Containers} defines a modified version of | |
23223 | Indefinite_Holders that avoids heap allocation. | |
23224 | ||
23225 | @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 | |
04d6c745 | 23226 | @anchor{gnat_rm/the_gnat_library ada-command-line-environment-a-colien-ads}@anchor{2ec}@anchor{gnat_rm/the_gnat_library id8}@anchor{2ed} |
64d5610f ML |
23227 | @section @code{Ada.Command_Line.Environment} (@code{a-colien.ads}) |
23228 | ||
23229 | ||
23230 | @geindex Ada.Command_Line.Environment (a-colien.ads) | |
23231 | ||
23232 | @geindex Environment entries | |
23233 | ||
23234 | This child of @code{Ada.Command_Line} | |
23235 | provides a mechanism for obtaining environment values on systems | |
23236 | where this concept makes sense. | |
23237 | ||
23238 | @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 | |
04d6c745 | 23239 | @anchor{gnat_rm/the_gnat_library ada-command-line-remove-a-colire-ads}@anchor{2ee}@anchor{gnat_rm/the_gnat_library id9}@anchor{2ef} |
64d5610f ML |
23240 | @section @code{Ada.Command_Line.Remove} (@code{a-colire.ads}) |
23241 | ||
23242 | ||
23243 | @geindex Ada.Command_Line.Remove (a-colire.ads) | |
23244 | ||
23245 | @geindex Removing command line arguments | |
23246 | ||
23247 | @geindex Command line | |
23248 | @geindex argument removal | |
23249 | ||
23250 | This child of @code{Ada.Command_Line} | |
23251 | provides a mechanism for logically removing | |
23252 | arguments from the argument list. Once removed, an argument is not visible | |
eeba836b RD |
23253 | to further calls to the subprograms in @code{Ada.Command_Line}. These calls |
23254 | will not see the removed argument. | |
64d5610f ML |
23255 | |
23256 | @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 | |
04d6c745 | 23257 | @anchor{gnat_rm/the_gnat_library ada-command-line-response-file-a-clrefi-ads}@anchor{2f0}@anchor{gnat_rm/the_gnat_library id10}@anchor{2f1} |
64d5610f ML |
23258 | @section @code{Ada.Command_Line.Response_File} (@code{a-clrefi.ads}) |
23259 | ||
23260 | ||
23261 | @geindex Ada.Command_Line.Response_File (a-clrefi.ads) | |
23262 | ||
23263 | @geindex Response file for command line | |
23264 | ||
23265 | @geindex Command line | |
23266 | @geindex response file | |
23267 | ||
23268 | @geindex Command line | |
23269 | @geindex handling long command lines | |
23270 | ||
23271 | This child of @code{Ada.Command_Line} provides a mechanism facilities for | |
23272 | getting command line arguments from a text file, called a “response file”. | |
23273 | Using a response file allow passing a set of arguments to an executable longer | |
23274 | than the maximum allowed by the system on the command line. | |
23275 | ||
23276 | @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 | |
04d6c745 | 23277 | @anchor{gnat_rm/the_gnat_library ada-direct-io-c-streams-a-diocst-ads}@anchor{2f2}@anchor{gnat_rm/the_gnat_library id11}@anchor{2f3} |
64d5610f ML |
23278 | @section @code{Ada.Direct_IO.C_Streams} (@code{a-diocst.ads}) |
23279 | ||
23280 | ||
23281 | @geindex Ada.Direct_IO.C_Streams (a-diocst.ads) | |
23282 | ||
23283 | @geindex C Streams | |
23284 | @geindex Interfacing with Direct_IO | |
23285 | ||
23286 | This package provides subprograms that allow interfacing between | |
23287 | C streams and @code{Direct_IO}. The stream identifier can be | |
23288 | extracted from a file opened on the Ada side, and an Ada file | |
23289 | can be constructed from a stream opened on the C side. | |
23290 | ||
23291 | @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 | |
04d6c745 | 23292 | @anchor{gnat_rm/the_gnat_library ada-exceptions-is-null-occurrence-a-einuoc-ads}@anchor{2f4}@anchor{gnat_rm/the_gnat_library id12}@anchor{2f5} |
64d5610f ML |
23293 | @section @code{Ada.Exceptions.Is_Null_Occurrence} (@code{a-einuoc.ads}) |
23294 | ||
23295 | ||
23296 | @geindex Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads) | |
23297 | ||
23298 | @geindex Null_Occurrence | |
23299 | @geindex testing for | |
23300 | ||
23301 | This child subprogram provides a way of testing for the null | |
23302 | exception occurrence (@code{Null_Occurrence}) without raising | |
23303 | an exception. | |
23304 | ||
23305 | @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 | |
04d6c745 | 23306 | @anchor{gnat_rm/the_gnat_library ada-exceptions-last-chance-handler-a-elchha-ads}@anchor{2f6}@anchor{gnat_rm/the_gnat_library id13}@anchor{2f7} |
64d5610f ML |
23307 | @section @code{Ada.Exceptions.Last_Chance_Handler} (@code{a-elchha.ads}) |
23308 | ||
23309 | ||
23310 | @geindex Ada.Exceptions.Last_Chance_Handler (a-elchha.ads) | |
23311 | ||
23312 | @geindex Null_Occurrence | |
23313 | @geindex testing for | |
23314 | ||
23315 | This child subprogram is used for handling otherwise unhandled | |
23316 | exceptions (hence the name last chance), and perform clean ups before | |
23317 | terminating the program. Note that this subprogram never returns. | |
23318 | ||
23319 | @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 | |
04d6c745 | 23320 | @anchor{gnat_rm/the_gnat_library ada-exceptions-traceback-a-exctra-ads}@anchor{2f8}@anchor{gnat_rm/the_gnat_library id14}@anchor{2f9} |
64d5610f ML |
23321 | @section @code{Ada.Exceptions.Traceback} (@code{a-exctra.ads}) |
23322 | ||
23323 | ||
23324 | @geindex Ada.Exceptions.Traceback (a-exctra.ads) | |
23325 | ||
23326 | @geindex Traceback for Exception Occurrence | |
23327 | ||
23328 | This child package provides the subprogram (@code{Tracebacks}) to | |
23329 | give a traceback array of addresses based on an exception | |
23330 | occurrence. | |
23331 | ||
23332 | @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 | |
04d6c745 | 23333 | @anchor{gnat_rm/the_gnat_library ada-sequential-io-c-streams-a-siocst-ads}@anchor{2fa}@anchor{gnat_rm/the_gnat_library id15}@anchor{2fb} |
64d5610f ML |
23334 | @section @code{Ada.Sequential_IO.C_Streams} (@code{a-siocst.ads}) |
23335 | ||
23336 | ||
23337 | @geindex Ada.Sequential_IO.C_Streams (a-siocst.ads) | |
23338 | ||
23339 | @geindex C Streams | |
23340 | @geindex Interfacing with Sequential_IO | |
23341 | ||
23342 | This package provides subprograms that allow interfacing between | |
23343 | C streams and @code{Sequential_IO}. The stream identifier can be | |
23344 | extracted from a file opened on the Ada side, and an Ada file | |
23345 | can be constructed from a stream opened on the C side. | |
23346 | ||
23347 | @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 | |
04d6c745 | 23348 | @anchor{gnat_rm/the_gnat_library ada-streams-stream-io-c-streams-a-ssicst-ads}@anchor{2fc}@anchor{gnat_rm/the_gnat_library id16}@anchor{2fd} |
64d5610f ML |
23349 | @section @code{Ada.Streams.Stream_IO.C_Streams} (@code{a-ssicst.ads}) |
23350 | ||
23351 | ||
23352 | @geindex Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads) | |
23353 | ||
23354 | @geindex C Streams | |
23355 | @geindex Interfacing with Stream_IO | |
23356 | ||
23357 | This package provides subprograms that allow interfacing between | |
23358 | C streams and @code{Stream_IO}. The stream identifier can be | |
23359 | extracted from a file opened on the Ada side, and an Ada file | |
23360 | can be constructed from a stream opened on the C side. | |
23361 | ||
23362 | @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 | |
04d6c745 | 23363 | @anchor{gnat_rm/the_gnat_library ada-strings-unbounded-text-io-a-suteio-ads}@anchor{2fe}@anchor{gnat_rm/the_gnat_library id17}@anchor{2ff} |
64d5610f ML |
23364 | @section @code{Ada.Strings.Unbounded.Text_IO} (@code{a-suteio.ads}) |
23365 | ||
23366 | ||
23367 | @geindex Ada.Strings.Unbounded.Text_IO (a-suteio.ads) | |
23368 | ||
23369 | @geindex Unbounded_String | |
23370 | @geindex IO support | |
23371 | ||
23372 | @geindex Text_IO | |
23373 | @geindex extensions for unbounded strings | |
23374 | ||
23375 | This package provides subprograms for Text_IO for unbounded | |
23376 | strings, avoiding the necessity for an intermediate operation | |
23377 | with ordinary strings. | |
23378 | ||
23379 | @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 | |
04d6c745 | 23380 | @anchor{gnat_rm/the_gnat_library ada-strings-wide-unbounded-wide-text-io-a-swuwti-ads}@anchor{300}@anchor{gnat_rm/the_gnat_library id18}@anchor{301} |
64d5610f ML |
23381 | @section @code{Ada.Strings.Wide_Unbounded.Wide_Text_IO} (@code{a-swuwti.ads}) |
23382 | ||
23383 | ||
23384 | @geindex Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads) | |
23385 | ||
23386 | @geindex Unbounded_Wide_String | |
23387 | @geindex IO support | |
23388 | ||
23389 | @geindex Text_IO | |
23390 | @geindex extensions for unbounded wide strings | |
23391 | ||
23392 | This package provides subprograms for Text_IO for unbounded | |
23393 | wide strings, avoiding the necessity for an intermediate operation | |
23394 | with ordinary wide strings. | |
23395 | ||
23396 | @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 | |
04d6c745 | 23397 | @anchor{gnat_rm/the_gnat_library ada-strings-wide-wide-unbounded-wide-wide-text-io-a-szuzti-ads}@anchor{302}@anchor{gnat_rm/the_gnat_library id19}@anchor{303} |
64d5610f ML |
23398 | @section @code{Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO} (@code{a-szuzti.ads}) |
23399 | ||
23400 | ||
23401 | @geindex Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads) | |
23402 | ||
23403 | @geindex Unbounded_Wide_Wide_String | |
23404 | @geindex IO support | |
23405 | ||
23406 | @geindex Text_IO | |
23407 | @geindex extensions for unbounded wide wide strings | |
23408 | ||
23409 | This package provides subprograms for Text_IO for unbounded | |
23410 | wide wide strings, avoiding the necessity for an intermediate operation | |
23411 | with ordinary wide wide strings. | |
23412 | ||
23413 | @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 | |
04d6c745 | 23414 | @anchor{gnat_rm/the_gnat_library ada-task-initialization-a-tasini-ads}@anchor{304}@anchor{gnat_rm/the_gnat_library id20}@anchor{305} |
64d5610f ML |
23415 | @section @code{Ada.Task_Initialization} (@code{a-tasini.ads}) |
23416 | ||
23417 | ||
23418 | @geindex Ada.Task_Initialization (a-tasini.ads) | |
23419 | ||
23420 | This package provides a way to set a global initialization handler that | |
23421 | is automatically invoked whenever a task is activated. Handlers are | |
23422 | parameterless procedures. Note that such a handler is only invoked for | |
23423 | those tasks activated after the handler is set. | |
23424 | ||
23425 | @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 | |
04d6c745 | 23426 | @anchor{gnat_rm/the_gnat_library ada-text-io-c-streams-a-tiocst-ads}@anchor{306}@anchor{gnat_rm/the_gnat_library id21}@anchor{307} |
64d5610f ML |
23427 | @section @code{Ada.Text_IO.C_Streams} (@code{a-tiocst.ads}) |
23428 | ||
23429 | ||
23430 | @geindex Ada.Text_IO.C_Streams (a-tiocst.ads) | |
23431 | ||
23432 | @geindex C Streams | |
23433 | @geindex Interfacing with `@w{`}Text_IO`@w{`} | |
23434 | ||
23435 | This package provides subprograms that allow interfacing between | |
23436 | C streams and @code{Text_IO}. The stream identifier can be | |
23437 | extracted from a file opened on the Ada side, and an Ada file | |
23438 | can be constructed from a stream opened on the C side. | |
23439 | ||
23440 | @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 | |
04d6c745 | 23441 | @anchor{gnat_rm/the_gnat_library ada-text-io-reset-standard-files-a-tirsfi-ads}@anchor{308}@anchor{gnat_rm/the_gnat_library id22}@anchor{309} |
64d5610f ML |
23442 | @section @code{Ada.Text_IO.Reset_Standard_Files} (@code{a-tirsfi.ads}) |
23443 | ||
23444 | ||
23445 | @geindex Ada.Text_IO.Reset_Standard_Files (a-tirsfi.ads) | |
23446 | ||
23447 | @geindex Text_IO resetting standard files | |
23448 | ||
23449 | This procedure is used to reset the status of the standard files used | |
23450 | by Ada.Text_IO. This is useful in a situation (such as a restart in an | |
23451 | embedded application) where the status of the files may change during | |
23452 | execution (for example a standard input file may be redefined to be | |
23453 | interactive). | |
23454 | ||
23455 | @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 | |
04d6c745 | 23456 | @anchor{gnat_rm/the_gnat_library ada-wide-characters-unicode-a-wichun-ads}@anchor{30a}@anchor{gnat_rm/the_gnat_library id23}@anchor{30b} |
64d5610f ML |
23457 | @section @code{Ada.Wide_Characters.Unicode} (@code{a-wichun.ads}) |
23458 | ||
23459 | ||
23460 | @geindex Ada.Wide_Characters.Unicode (a-wichun.ads) | |
23461 | ||
23462 | @geindex Unicode categorization | |
23463 | @geindex Wide_Character | |
23464 | ||
23465 | This package provides subprograms that allow categorization of | |
23466 | Wide_Character values according to Unicode categories. | |
23467 | ||
23468 | @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 | |
04d6c745 | 23469 | @anchor{gnat_rm/the_gnat_library ada-wide-text-io-c-streams-a-wtcstr-ads}@anchor{30c}@anchor{gnat_rm/the_gnat_library id24}@anchor{30d} |
64d5610f ML |
23470 | @section @code{Ada.Wide_Text_IO.C_Streams} (@code{a-wtcstr.ads}) |
23471 | ||
23472 | ||
23473 | @geindex Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads) | |
23474 | ||
23475 | @geindex C Streams | |
23476 | @geindex Interfacing with `@w{`}Wide_Text_IO`@w{`} | |
23477 | ||
23478 | This package provides subprograms that allow interfacing between | |
23479 | C streams and @code{Wide_Text_IO}. The stream identifier can be | |
23480 | extracted from a file opened on the Ada side, and an Ada file | |
23481 | can be constructed from a stream opened on the C side. | |
23482 | ||
23483 | @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 | |
04d6c745 | 23484 | @anchor{gnat_rm/the_gnat_library ada-wide-text-io-reset-standard-files-a-wrstfi-ads}@anchor{30e}@anchor{gnat_rm/the_gnat_library id25}@anchor{30f} |
64d5610f ML |
23485 | @section @code{Ada.Wide_Text_IO.Reset_Standard_Files} (@code{a-wrstfi.ads}) |
23486 | ||
23487 | ||
23488 | @geindex Ada.Wide_Text_IO.Reset_Standard_Files (a-wrstfi.ads) | |
23489 | ||
23490 | @geindex Wide_Text_IO resetting standard files | |
23491 | ||
23492 | This procedure is used to reset the status of the standard files used | |
23493 | by Ada.Wide_Text_IO. This is useful in a situation (such as a restart in an | |
23494 | embedded application) where the status of the files may change during | |
23495 | execution (for example a standard input file may be redefined to be | |
23496 | interactive). | |
23497 | ||
23498 | @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 | |
04d6c745 | 23499 | @anchor{gnat_rm/the_gnat_library ada-wide-wide-characters-unicode-a-zchuni-ads}@anchor{310}@anchor{gnat_rm/the_gnat_library id26}@anchor{311} |
64d5610f ML |
23500 | @section @code{Ada.Wide_Wide_Characters.Unicode} (@code{a-zchuni.ads}) |
23501 | ||
23502 | ||
23503 | @geindex Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads) | |
23504 | ||
23505 | @geindex Unicode categorization | |
23506 | @geindex Wide_Wide_Character | |
23507 | ||
23508 | This package provides subprograms that allow categorization of | |
23509 | Wide_Wide_Character values according to Unicode categories. | |
23510 | ||
23511 | @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 | |
04d6c745 | 23512 | @anchor{gnat_rm/the_gnat_library ada-wide-wide-text-io-c-streams-a-ztcstr-ads}@anchor{312}@anchor{gnat_rm/the_gnat_library id27}@anchor{313} |
64d5610f ML |
23513 | @section @code{Ada.Wide_Wide_Text_IO.C_Streams} (@code{a-ztcstr.ads}) |
23514 | ||
23515 | ||
23516 | @geindex Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads) | |
23517 | ||
23518 | @geindex C Streams | |
23519 | @geindex Interfacing with `@w{`}Wide_Wide_Text_IO`@w{`} | |
23520 | ||
23521 | This package provides subprograms that allow interfacing between | |
23522 | C streams and @code{Wide_Wide_Text_IO}. The stream identifier can be | |
23523 | extracted from a file opened on the Ada side, and an Ada file | |
23524 | can be constructed from a stream opened on the C side. | |
23525 | ||
23526 | @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 | |
04d6c745 | 23527 | @anchor{gnat_rm/the_gnat_library ada-wide-wide-text-io-reset-standard-files-a-zrstfi-ads}@anchor{314}@anchor{gnat_rm/the_gnat_library id28}@anchor{315} |
64d5610f ML |
23528 | @section @code{Ada.Wide_Wide_Text_IO.Reset_Standard_Files} (@code{a-zrstfi.ads}) |
23529 | ||
23530 | ||
23531 | @geindex Ada.Wide_Wide_Text_IO.Reset_Standard_Files (a-zrstfi.ads) | |
23532 | ||
23533 | @geindex Wide_Wide_Text_IO resetting standard files | |
23534 | ||
23535 | This procedure is used to reset the status of the standard files used | |
23536 | by Ada.Wide_Wide_Text_IO. This is useful in a situation (such as a | |
23537 | restart in an embedded application) where the status of the files may | |
23538 | change during execution (for example a standard input file may be | |
23539 | redefined to be interactive). | |
23540 | ||
23541 | @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 | |
04d6c745 | 23542 | @anchor{gnat_rm/the_gnat_library gnat-altivec-g-altive-ads}@anchor{316}@anchor{gnat_rm/the_gnat_library id29}@anchor{317} |
64d5610f ML |
23543 | @section @code{GNAT.Altivec} (@code{g-altive.ads}) |
23544 | ||
23545 | ||
23546 | @geindex GNAT.Altivec (g-altive.ads) | |
23547 | ||
23548 | @geindex AltiVec | |
23549 | ||
23550 | This is the root package of the GNAT AltiVec binding. It provides | |
23551 | definitions of constants and types common to all the versions of the | |
23552 | binding. | |
23553 | ||
23554 | @node GNAT Altivec Conversions g-altcon ads,GNAT Altivec Vector_Operations g-alveop ads,GNAT Altivec g-altive ads,The GNAT Library | |
04d6c745 | 23555 | @anchor{gnat_rm/the_gnat_library gnat-altivec-conversions-g-altcon-ads}@anchor{318}@anchor{gnat_rm/the_gnat_library id30}@anchor{319} |
64d5610f ML |
23556 | @section @code{GNAT.Altivec.Conversions} (@code{g-altcon.ads}) |
23557 | ||
23558 | ||
23559 | @geindex GNAT.Altivec.Conversions (g-altcon.ads) | |
23560 | ||
23561 | @geindex AltiVec | |
23562 | ||
23563 | This package provides the Vector/View conversion routines. | |
23564 | ||
23565 | @node GNAT Altivec Vector_Operations g-alveop ads,GNAT Altivec Vector_Types g-alvety ads,GNAT Altivec Conversions g-altcon ads,The GNAT Library | |
04d6c745 | 23566 | @anchor{gnat_rm/the_gnat_library gnat-altivec-vector-operations-g-alveop-ads}@anchor{31a}@anchor{gnat_rm/the_gnat_library id31}@anchor{31b} |
64d5610f ML |
23567 | @section @code{GNAT.Altivec.Vector_Operations} (@code{g-alveop.ads}) |
23568 | ||
23569 | ||
23570 | @geindex GNAT.Altivec.Vector_Operations (g-alveop.ads) | |
23571 | ||
23572 | @geindex AltiVec | |
23573 | ||
23574 | This package exposes the Ada interface to the AltiVec operations on | |
23575 | vector objects. A soft emulation is included by default in the GNAT | |
23576 | library. The hard binding is provided as a separate package. This unit | |
23577 | is common to both bindings. | |
23578 | ||
23579 | @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 | |
04d6c745 | 23580 | @anchor{gnat_rm/the_gnat_library gnat-altivec-vector-types-g-alvety-ads}@anchor{31c}@anchor{gnat_rm/the_gnat_library id32}@anchor{31d} |
64d5610f ML |
23581 | @section @code{GNAT.Altivec.Vector_Types} (@code{g-alvety.ads}) |
23582 | ||
23583 | ||
23584 | @geindex GNAT.Altivec.Vector_Types (g-alvety.ads) | |
23585 | ||
23586 | @geindex AltiVec | |
23587 | ||
23588 | This package exposes the various vector types part of the Ada binding | |
23589 | to AltiVec facilities. | |
23590 | ||
23591 | @node GNAT Altivec Vector_Views g-alvevi ads,GNAT Array_Split g-arrspl ads,GNAT Altivec Vector_Types g-alvety ads,The GNAT Library | |
04d6c745 | 23592 | @anchor{gnat_rm/the_gnat_library gnat-altivec-vector-views-g-alvevi-ads}@anchor{31e}@anchor{gnat_rm/the_gnat_library id33}@anchor{31f} |
64d5610f ML |
23593 | @section @code{GNAT.Altivec.Vector_Views} (@code{g-alvevi.ads}) |
23594 | ||
23595 | ||
23596 | @geindex GNAT.Altivec.Vector_Views (g-alvevi.ads) | |
23597 | ||
23598 | @geindex AltiVec | |
23599 | ||
23600 | This package provides public ‘View’ data types from/to which private | |
23601 | vector representations can be converted via | |
23602 | GNAT.Altivec.Conversions. This allows convenient access to individual | |
23603 | vector elements and provides a simple way to initialize vector | |
23604 | objects. | |
23605 | ||
23606 | @node GNAT Array_Split g-arrspl ads,GNAT AWK g-awk ads,GNAT Altivec Vector_Views g-alvevi ads,The GNAT Library | |
04d6c745 | 23607 | @anchor{gnat_rm/the_gnat_library gnat-array-split-g-arrspl-ads}@anchor{320}@anchor{gnat_rm/the_gnat_library id34}@anchor{321} |
64d5610f ML |
23608 | @section @code{GNAT.Array_Split} (@code{g-arrspl.ads}) |
23609 | ||
23610 | ||
23611 | @geindex GNAT.Array_Split (g-arrspl.ads) | |
23612 | ||
23613 | @geindex Array splitter | |
23614 | ||
23615 | Useful array-manipulation routines: given a set of separators, split | |
23616 | an array wherever the separators appear, and provide direct access | |
23617 | to the resulting slices. | |
23618 | ||
23619 | @node GNAT AWK g-awk ads,GNAT Binary_Search g-binsea ads,GNAT Array_Split g-arrspl ads,The GNAT Library | |
04d6c745 | 23620 | @anchor{gnat_rm/the_gnat_library gnat-awk-g-awk-ads}@anchor{322}@anchor{gnat_rm/the_gnat_library id35}@anchor{323} |
64d5610f ML |
23621 | @section @code{GNAT.AWK} (@code{g-awk.ads}) |
23622 | ||
23623 | ||
23624 | @geindex GNAT.AWK (g-awk.ads) | |
23625 | ||
23626 | @geindex Parsing | |
23627 | ||
23628 | @geindex AWK | |
23629 | ||
23630 | Provides AWK-like parsing functions, with an easy interface for parsing one | |
23631 | or more files containing formatted data. The file is viewed as a database | |
23632 | where each record is a line and a field is a data element in this line. | |
23633 | ||
23634 | @node GNAT Binary_Search g-binsea ads,GNAT Bind_Environment g-binenv ads,GNAT AWK g-awk ads,The GNAT Library | |
04d6c745 | 23635 | @anchor{gnat_rm/the_gnat_library gnat-binary-search-g-binsea-ads}@anchor{324}@anchor{gnat_rm/the_gnat_library id36}@anchor{325} |
64d5610f ML |
23636 | @section @code{GNAT.Binary_Search} (@code{g-binsea.ads}) |
23637 | ||
23638 | ||
23639 | @geindex GNAT.Binary_Search (g-binsea.ads) | |
23640 | ||
23641 | @geindex Binary search | |
23642 | ||
23643 | Allow binary search of a sorted array (or of an array-like container; | |
23644 | the generic does not reference the array directly). | |
23645 | ||
23646 | @node GNAT Bind_Environment g-binenv ads,GNAT Branch_Prediction g-brapre ads,GNAT Binary_Search g-binsea ads,The GNAT Library | |
04d6c745 | 23647 | @anchor{gnat_rm/the_gnat_library gnat-bind-environment-g-binenv-ads}@anchor{326}@anchor{gnat_rm/the_gnat_library id37}@anchor{327} |
64d5610f ML |
23648 | @section @code{GNAT.Bind_Environment} (@code{g-binenv.ads}) |
23649 | ||
23650 | ||
23651 | @geindex GNAT.Bind_Environment (g-binenv.ads) | |
23652 | ||
23653 | @geindex Bind environment | |
23654 | ||
23655 | Provides access to key=value associations captured at bind time. | |
23656 | These associations can be specified using the @code{-V} binder command | |
23657 | line switch. | |
23658 | ||
23659 | @node GNAT Branch_Prediction g-brapre ads,GNAT Bounded_Buffers g-boubuf ads,GNAT Bind_Environment g-binenv ads,The GNAT Library | |
04d6c745 | 23660 | @anchor{gnat_rm/the_gnat_library gnat-branch-prediction-g-brapre-ads}@anchor{328}@anchor{gnat_rm/the_gnat_library id38}@anchor{329} |
64d5610f ML |
23661 | @section @code{GNAT.Branch_Prediction} (@code{g-brapre.ads}) |
23662 | ||
23663 | ||
23664 | @geindex GNAT.Branch_Prediction (g-brapre.ads) | |
23665 | ||
23666 | @geindex Branch Prediction | |
23667 | ||
23668 | Provides routines giving hints to the branch predictor of the code generator. | |
23669 | ||
23670 | @node GNAT Bounded_Buffers g-boubuf ads,GNAT Bounded_Mailboxes g-boumai ads,GNAT Branch_Prediction g-brapre ads,The GNAT Library | |
04d6c745 | 23671 | @anchor{gnat_rm/the_gnat_library gnat-bounded-buffers-g-boubuf-ads}@anchor{32a}@anchor{gnat_rm/the_gnat_library id39}@anchor{32b} |
64d5610f ML |
23672 | @section @code{GNAT.Bounded_Buffers} (@code{g-boubuf.ads}) |
23673 | ||
23674 | ||
23675 | @geindex GNAT.Bounded_Buffers (g-boubuf.ads) | |
23676 | ||
23677 | @geindex Parsing | |
23678 | ||
23679 | @geindex Bounded Buffers | |
23680 | ||
23681 | Provides a concurrent generic bounded buffer abstraction. Instances are | |
23682 | useful directly or as parts of the implementations of other abstractions, | |
23683 | such as mailboxes. | |
23684 | ||
23685 | @node GNAT Bounded_Mailboxes g-boumai ads,GNAT Bubble_Sort g-bubsor ads,GNAT Bounded_Buffers g-boubuf ads,The GNAT Library | |
04d6c745 | 23686 | @anchor{gnat_rm/the_gnat_library gnat-bounded-mailboxes-g-boumai-ads}@anchor{32c}@anchor{gnat_rm/the_gnat_library id40}@anchor{32d} |
64d5610f ML |
23687 | @section @code{GNAT.Bounded_Mailboxes} (@code{g-boumai.ads}) |
23688 | ||
23689 | ||
23690 | @geindex GNAT.Bounded_Mailboxes (g-boumai.ads) | |
23691 | ||
23692 | @geindex Parsing | |
23693 | ||
23694 | @geindex Mailboxes | |
23695 | ||
23696 | Provides a thread-safe asynchronous intertask mailbox communication facility. | |
23697 | ||
23698 | @node GNAT Bubble_Sort g-bubsor ads,GNAT Bubble_Sort_A g-busora ads,GNAT Bounded_Mailboxes g-boumai ads,The GNAT Library | |
04d6c745 | 23699 | @anchor{gnat_rm/the_gnat_library gnat-bubble-sort-g-bubsor-ads}@anchor{32e}@anchor{gnat_rm/the_gnat_library id41}@anchor{32f} |
64d5610f ML |
23700 | @section @code{GNAT.Bubble_Sort} (@code{g-bubsor.ads}) |
23701 | ||
23702 | ||
23703 | @geindex GNAT.Bubble_Sort (g-bubsor.ads) | |
23704 | ||
23705 | @geindex Sorting | |
23706 | ||
23707 | @geindex Bubble sort | |
23708 | ||
23709 | Provides a general implementation of bubble sort usable for sorting arbitrary | |
23710 | data items. Exchange and comparison procedures are provided by passing | |
23711 | access-to-procedure values. | |
23712 | ||
23713 | @node GNAT Bubble_Sort_A g-busora ads,GNAT Bubble_Sort_G g-busorg ads,GNAT Bubble_Sort g-bubsor ads,The GNAT Library | |
04d6c745 | 23714 | @anchor{gnat_rm/the_gnat_library gnat-bubble-sort-a-g-busora-ads}@anchor{330}@anchor{gnat_rm/the_gnat_library id42}@anchor{331} |
64d5610f ML |
23715 | @section @code{GNAT.Bubble_Sort_A} (@code{g-busora.ads}) |
23716 | ||
23717 | ||
23718 | @geindex GNAT.Bubble_Sort_A (g-busora.ads) | |
23719 | ||
23720 | @geindex Sorting | |
23721 | ||
23722 | @geindex Bubble sort | |
23723 | ||
23724 | Provides a general implementation of bubble sort usable for sorting arbitrary | |
23725 | data items. Move and comparison procedures are provided by passing | |
23726 | access-to-procedure values. This is an older version, retained for | |
23727 | compatibility. Usually @code{GNAT.Bubble_Sort} will be preferable. | |
23728 | ||
23729 | @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 | |
04d6c745 | 23730 | @anchor{gnat_rm/the_gnat_library gnat-bubble-sort-g-g-busorg-ads}@anchor{332}@anchor{gnat_rm/the_gnat_library id43}@anchor{333} |
64d5610f ML |
23731 | @section @code{GNAT.Bubble_Sort_G} (@code{g-busorg.ads}) |
23732 | ||
23733 | ||
23734 | @geindex GNAT.Bubble_Sort_G (g-busorg.ads) | |
23735 | ||
23736 | @geindex Sorting | |
23737 | ||
23738 | @geindex Bubble sort | |
23739 | ||
23740 | Similar to @code{Bubble_Sort_A} except that the move and sorting procedures | |
23741 | are provided as generic parameters, this improves efficiency, especially | |
23742 | if the procedures can be inlined, at the expense of duplicating code for | |
23743 | multiple instantiations. | |
23744 | ||
23745 | @node GNAT Byte_Order_Mark g-byorma ads,GNAT Byte_Swapping g-bytswa ads,GNAT Bubble_Sort_G g-busorg ads,The GNAT Library | |
04d6c745 | 23746 | @anchor{gnat_rm/the_gnat_library gnat-byte-order-mark-g-byorma-ads}@anchor{334}@anchor{gnat_rm/the_gnat_library id44}@anchor{335} |
64d5610f ML |
23747 | @section @code{GNAT.Byte_Order_Mark} (@code{g-byorma.ads}) |
23748 | ||
23749 | ||
23750 | @geindex GNAT.Byte_Order_Mark (g-byorma.ads) | |
23751 | ||
23752 | @geindex UTF-8 representation | |
23753 | ||
23754 | @geindex Wide characte representations | |
23755 | ||
23756 | Provides a routine which given a string, reads the start of the string to | |
23757 | see whether it is one of the standard byte order marks (BOM’s) which signal | |
23758 | the encoding of the string. The routine includes detection of special XML | |
23759 | sequences for various UCS input formats. | |
23760 | ||
23761 | @node GNAT Byte_Swapping g-bytswa ads,GNAT Calendar g-calend ads,GNAT Byte_Order_Mark g-byorma ads,The GNAT Library | |
04d6c745 | 23762 | @anchor{gnat_rm/the_gnat_library gnat-byte-swapping-g-bytswa-ads}@anchor{336}@anchor{gnat_rm/the_gnat_library id45}@anchor{337} |
64d5610f ML |
23763 | @section @code{GNAT.Byte_Swapping} (@code{g-bytswa.ads}) |
23764 | ||
23765 | ||
23766 | @geindex GNAT.Byte_Swapping (g-bytswa.ads) | |
23767 | ||
23768 | @geindex Byte swapping | |
23769 | ||
23770 | @geindex Endianness | |
23771 | ||
23772 | General routines for swapping the bytes in 2-, 4-, and 8-byte quantities. | |
23773 | Machine-specific implementations are available in some cases. | |
23774 | ||
23775 | @node GNAT Calendar g-calend ads,GNAT Calendar Time_IO g-catiio ads,GNAT Byte_Swapping g-bytswa ads,The GNAT Library | |
04d6c745 | 23776 | @anchor{gnat_rm/the_gnat_library gnat-calendar-g-calend-ads}@anchor{338}@anchor{gnat_rm/the_gnat_library id46}@anchor{339} |
64d5610f ML |
23777 | @section @code{GNAT.Calendar} (@code{g-calend.ads}) |
23778 | ||
23779 | ||
23780 | @geindex GNAT.Calendar (g-calend.ads) | |
23781 | ||
23782 | @geindex Calendar | |
23783 | ||
23784 | Extends the facilities provided by @code{Ada.Calendar} to include handling | |
23785 | of days of the week, an extended @code{Split} and @code{Time_Of} capability. | |
23786 | Also provides conversion of @code{Ada.Calendar.Time} values to and from the | |
23787 | C @code{timeval} format. | |
23788 | ||
23789 | @node GNAT Calendar Time_IO g-catiio ads,GNAT CRC32 g-crc32 ads,GNAT Calendar g-calend ads,The GNAT Library | |
04d6c745 | 23790 | @anchor{gnat_rm/the_gnat_library gnat-calendar-time-io-g-catiio-ads}@anchor{33a}@anchor{gnat_rm/the_gnat_library id47}@anchor{33b} |
64d5610f ML |
23791 | @section @code{GNAT.Calendar.Time_IO} (@code{g-catiio.ads}) |
23792 | ||
23793 | ||
23794 | @geindex Calendar | |
23795 | ||
23796 | @geindex Time | |
23797 | ||
23798 | @geindex GNAT.Calendar.Time_IO (g-catiio.ads) | |
23799 | ||
23800 | @node GNAT CRC32 g-crc32 ads,GNAT Case_Util g-casuti ads,GNAT Calendar Time_IO g-catiio ads,The GNAT Library | |
04d6c745 | 23801 | @anchor{gnat_rm/the_gnat_library gnat-crc32-g-crc32-ads}@anchor{33c}@anchor{gnat_rm/the_gnat_library id48}@anchor{33d} |
64d5610f ML |
23802 | @section @code{GNAT.CRC32} (@code{g-crc32.ads}) |
23803 | ||
23804 | ||
23805 | @geindex GNAT.CRC32 (g-crc32.ads) | |
23806 | ||
23807 | @geindex CRC32 | |
23808 | ||
23809 | @geindex Cyclic Redundancy Check | |
23810 | ||
23811 | This package implements the CRC-32 algorithm. For a full description | |
23812 | of this algorithm see | |
23813 | `Computation of Cyclic Redundancy Checks via Table Look-Up', | |
23814 | @cite{Communications of the ACM}, Vol. 31 No. 8, pp. 1008-1013, | |
23815 | Aug. 1988. Sarwate, D.V. | |
23816 | ||
23817 | @node GNAT Case_Util g-casuti ads,GNAT CGI g-cgi ads,GNAT CRC32 g-crc32 ads,The GNAT Library | |
04d6c745 | 23818 | @anchor{gnat_rm/the_gnat_library gnat-case-util-g-casuti-ads}@anchor{33e}@anchor{gnat_rm/the_gnat_library id49}@anchor{33f} |
64d5610f ML |
23819 | @section @code{GNAT.Case_Util} (@code{g-casuti.ads}) |
23820 | ||
23821 | ||
23822 | @geindex GNAT.Case_Util (g-casuti.ads) | |
23823 | ||
23824 | @geindex Casing utilities | |
23825 | ||
23826 | @geindex Character handling (`@w{`}GNAT.Case_Util`@w{`}) | |
23827 | ||
23828 | A set of simple routines for handling upper and lower casing of strings | |
23829 | without the overhead of the full casing tables | |
23830 | in @code{Ada.Characters.Handling}. | |
23831 | ||
23832 | @node GNAT CGI g-cgi ads,GNAT CGI Cookie g-cgicoo ads,GNAT Case_Util g-casuti ads,The GNAT Library | |
04d6c745 | 23833 | @anchor{gnat_rm/the_gnat_library gnat-cgi-g-cgi-ads}@anchor{340}@anchor{gnat_rm/the_gnat_library id50}@anchor{341} |
64d5610f ML |
23834 | @section @code{GNAT.CGI} (@code{g-cgi.ads}) |
23835 | ||
23836 | ||
23837 | @geindex GNAT.CGI (g-cgi.ads) | |
23838 | ||
23839 | @geindex CGI (Common Gateway Interface) | |
23840 | ||
23841 | This is a package for interfacing a GNAT program with a Web server via the | |
23842 | Common Gateway Interface (CGI). Basically this package parses the CGI | |
23843 | parameters, which are a set of key/value pairs sent by the Web server. It | |
23844 | builds a table whose index is the key and provides some services to deal | |
23845 | with this table. | |
23846 | ||
23847 | @node GNAT CGI Cookie g-cgicoo ads,GNAT CGI Debug g-cgideb ads,GNAT CGI g-cgi ads,The GNAT Library | |
04d6c745 | 23848 | @anchor{gnat_rm/the_gnat_library gnat-cgi-cookie-g-cgicoo-ads}@anchor{342}@anchor{gnat_rm/the_gnat_library id51}@anchor{343} |
64d5610f ML |
23849 | @section @code{GNAT.CGI.Cookie} (@code{g-cgicoo.ads}) |
23850 | ||
23851 | ||
23852 | @geindex GNAT.CGI.Cookie (g-cgicoo.ads) | |
23853 | ||
23854 | @geindex CGI (Common Gateway Interface) cookie support | |
23855 | ||
23856 | @geindex Cookie support in CGI | |
23857 | ||
23858 | This is a package to interface a GNAT program with a Web server via the | |
23859 | Common Gateway Interface (CGI). It exports services to deal with Web | |
23860 | cookies (piece of information kept in the Web client software). | |
23861 | ||
23862 | @node GNAT CGI Debug g-cgideb ads,GNAT Command_Line g-comlin ads,GNAT CGI Cookie g-cgicoo ads,The GNAT Library | |
04d6c745 | 23863 | @anchor{gnat_rm/the_gnat_library gnat-cgi-debug-g-cgideb-ads}@anchor{344}@anchor{gnat_rm/the_gnat_library id52}@anchor{345} |
64d5610f ML |
23864 | @section @code{GNAT.CGI.Debug} (@code{g-cgideb.ads}) |
23865 | ||
23866 | ||
23867 | @geindex GNAT.CGI.Debug (g-cgideb.ads) | |
23868 | ||
23869 | @geindex CGI (Common Gateway Interface) debugging | |
23870 | ||
23871 | This is a package to help debugging CGI (Common Gateway Interface) | |
23872 | programs written in Ada. | |
23873 | ||
23874 | @node GNAT Command_Line g-comlin ads,GNAT Compiler_Version g-comver ads,GNAT CGI Debug g-cgideb ads,The GNAT Library | |
04d6c745 | 23875 | @anchor{gnat_rm/the_gnat_library gnat-command-line-g-comlin-ads}@anchor{346}@anchor{gnat_rm/the_gnat_library id53}@anchor{347} |
64d5610f ML |
23876 | @section @code{GNAT.Command_Line} (@code{g-comlin.ads}) |
23877 | ||
23878 | ||
23879 | @geindex GNAT.Command_Line (g-comlin.ads) | |
23880 | ||
23881 | @geindex Command line | |
23882 | ||
23883 | Provides a high level interface to @code{Ada.Command_Line} facilities, | |
23884 | including the ability to scan for named switches with optional parameters | |
23885 | and expand file names using wildcard notations. | |
23886 | ||
23887 | @node GNAT Compiler_Version g-comver ads,GNAT Ctrl_C g-ctrl_c ads,GNAT Command_Line g-comlin ads,The GNAT Library | |
04d6c745 | 23888 | @anchor{gnat_rm/the_gnat_library gnat-compiler-version-g-comver-ads}@anchor{348}@anchor{gnat_rm/the_gnat_library id54}@anchor{349} |
64d5610f ML |
23889 | @section @code{GNAT.Compiler_Version} (@code{g-comver.ads}) |
23890 | ||
23891 | ||
23892 | @geindex GNAT.Compiler_Version (g-comver.ads) | |
23893 | ||
23894 | @geindex Compiler Version | |
23895 | ||
23896 | @geindex Version | |
23897 | @geindex of compiler | |
23898 | ||
23899 | Provides a routine for obtaining the version of the compiler used to | |
23900 | compile the program. More accurately this is the version of the binder | |
23901 | used to bind the program (this will normally be the same as the version | |
23902 | of the compiler if a consistent tool set is used to compile all units | |
23903 | of a partition). | |
23904 | ||
23905 | @node GNAT Ctrl_C g-ctrl_c ads,GNAT Current_Exception g-curexc ads,GNAT Compiler_Version g-comver ads,The GNAT Library | |
04d6c745 | 23906 | @anchor{gnat_rm/the_gnat_library gnat-ctrl-c-g-ctrl-c-ads}@anchor{34a}@anchor{gnat_rm/the_gnat_library id55}@anchor{34b} |
64d5610f ML |
23907 | @section @code{GNAT.Ctrl_C} (@code{g-ctrl_c.ads}) |
23908 | ||
23909 | ||
23910 | @geindex GNAT.Ctrl_C (g-ctrl_c.ads) | |
23911 | ||
23912 | @geindex Interrupt | |
23913 | ||
23914 | Provides a simple interface to handle Ctrl-C keyboard events. | |
23915 | ||
23916 | @node GNAT Current_Exception g-curexc ads,GNAT Debug_Pools g-debpoo ads,GNAT Ctrl_C g-ctrl_c ads,The GNAT Library | |
04d6c745 | 23917 | @anchor{gnat_rm/the_gnat_library gnat-current-exception-g-curexc-ads}@anchor{34c}@anchor{gnat_rm/the_gnat_library id56}@anchor{34d} |
64d5610f ML |
23918 | @section @code{GNAT.Current_Exception} (@code{g-curexc.ads}) |
23919 | ||
23920 | ||
23921 | @geindex GNAT.Current_Exception (g-curexc.ads) | |
23922 | ||
23923 | @geindex Current exception | |
23924 | ||
23925 | @geindex Exception retrieval | |
23926 | ||
23927 | Provides access to information on the current exception that has been raised | |
23928 | without the need for using the Ada 95 / Ada 2005 exception choice parameter | |
23929 | specification syntax. | |
23930 | This is particularly useful in simulating typical facilities for | |
23931 | obtaining information about exceptions provided by Ada 83 compilers. | |
23932 | ||
23933 | @node GNAT Debug_Pools g-debpoo ads,GNAT Debug_Utilities g-debuti ads,GNAT Current_Exception g-curexc ads,The GNAT Library | |
04d6c745 | 23934 | @anchor{gnat_rm/the_gnat_library gnat-debug-pools-g-debpoo-ads}@anchor{34e}@anchor{gnat_rm/the_gnat_library id57}@anchor{34f} |
64d5610f ML |
23935 | @section @code{GNAT.Debug_Pools} (@code{g-debpoo.ads}) |
23936 | ||
23937 | ||
23938 | @geindex GNAT.Debug_Pools (g-debpoo.ads) | |
23939 | ||
23940 | @geindex Debugging | |
23941 | ||
23942 | @geindex Debug pools | |
23943 | ||
23944 | @geindex Memory corruption debugging | |
23945 | ||
eeba836b | 23946 | Provides a debugging storage pools that helps tracking memory corruption |
64d5610f ML |
23947 | problems. |
23948 | See @code{The GNAT Debug_Pool Facility} section in the @cite{GNAT User’s Guide}. | |
23949 | ||
23950 | @node GNAT Debug_Utilities g-debuti ads,GNAT Decode_String g-decstr ads,GNAT Debug_Pools g-debpoo ads,The GNAT Library | |
04d6c745 | 23951 | @anchor{gnat_rm/the_gnat_library gnat-debug-utilities-g-debuti-ads}@anchor{350}@anchor{gnat_rm/the_gnat_library id58}@anchor{351} |
64d5610f ML |
23952 | @section @code{GNAT.Debug_Utilities} (@code{g-debuti.ads}) |
23953 | ||
23954 | ||
23955 | @geindex GNAT.Debug_Utilities (g-debuti.ads) | |
23956 | ||
23957 | @geindex Debugging | |
23958 | ||
23959 | Provides a few useful utilities for debugging purposes, including conversion | |
23960 | to and from string images of address values. Supports both C and Ada formats | |
23961 | for hexadecimal literals. | |
23962 | ||
23963 | @node GNAT Decode_String g-decstr ads,GNAT Decode_UTF8_String g-deutst ads,GNAT Debug_Utilities g-debuti ads,The GNAT Library | |
04d6c745 | 23964 | @anchor{gnat_rm/the_gnat_library gnat-decode-string-g-decstr-ads}@anchor{352}@anchor{gnat_rm/the_gnat_library id59}@anchor{353} |
64d5610f ML |
23965 | @section @code{GNAT.Decode_String} (@code{g-decstr.ads}) |
23966 | ||
23967 | ||
23968 | @geindex GNAT.Decode_String (g-decstr.ads) | |
23969 | ||
23970 | @geindex Decoding strings | |
23971 | ||
23972 | @geindex String decoding | |
23973 | ||
23974 | @geindex Wide character encoding | |
23975 | ||
23976 | @geindex UTF-8 | |
23977 | ||
23978 | @geindex Unicode | |
23979 | ||
23980 | A generic package providing routines for decoding wide character and wide wide | |
23981 | character strings encoded as sequences of 8-bit characters using a specified | |
23982 | encoding method. Includes validation routines, and also routines for stepping | |
23983 | to next or previous encoded character in an encoded string. | |
23984 | Useful in conjunction with Unicode character coding. Note there is a | |
23985 | preinstantiation for UTF-8. See next entry. | |
23986 | ||
23987 | @node GNAT Decode_UTF8_String g-deutst ads,GNAT Directory_Operations g-dirope ads,GNAT Decode_String g-decstr ads,The GNAT Library | |
04d6c745 | 23988 | @anchor{gnat_rm/the_gnat_library gnat-decode-utf8-string-g-deutst-ads}@anchor{354}@anchor{gnat_rm/the_gnat_library id60}@anchor{355} |
64d5610f ML |
23989 | @section @code{GNAT.Decode_UTF8_String} (@code{g-deutst.ads}) |
23990 | ||
23991 | ||
23992 | @geindex GNAT.Decode_UTF8_String (g-deutst.ads) | |
23993 | ||
23994 | @geindex Decoding strings | |
23995 | ||
23996 | @geindex Decoding UTF-8 strings | |
23997 | ||
23998 | @geindex UTF-8 string decoding | |
23999 | ||
24000 | @geindex Wide character decoding | |
24001 | ||
24002 | @geindex UTF-8 | |
24003 | ||
24004 | @geindex Unicode | |
24005 | ||
24006 | A preinstantiation of GNAT.Decode_Strings for UTF-8 encoding. | |
24007 | ||
24008 | @node GNAT Directory_Operations g-dirope ads,GNAT Directory_Operations Iteration g-diopit ads,GNAT Decode_UTF8_String g-deutst ads,The GNAT Library | |
04d6c745 | 24009 | @anchor{gnat_rm/the_gnat_library gnat-directory-operations-g-dirope-ads}@anchor{356}@anchor{gnat_rm/the_gnat_library id61}@anchor{357} |
64d5610f ML |
24010 | @section @code{GNAT.Directory_Operations} (@code{g-dirope.ads}) |
24011 | ||
24012 | ||
24013 | @geindex GNAT.Directory_Operations (g-dirope.ads) | |
24014 | ||
24015 | @geindex Directory operations | |
24016 | ||
24017 | Provides a set of routines for manipulating directories, including changing | |
24018 | the current directory, making new directories, and scanning the files in a | |
24019 | directory. | |
24020 | ||
24021 | @node GNAT Directory_Operations Iteration g-diopit ads,GNAT Dynamic_HTables g-dynhta ads,GNAT Directory_Operations g-dirope ads,The GNAT Library | |
04d6c745 | 24022 | @anchor{gnat_rm/the_gnat_library gnat-directory-operations-iteration-g-diopit-ads}@anchor{358}@anchor{gnat_rm/the_gnat_library id62}@anchor{359} |
64d5610f ML |
24023 | @section @code{GNAT.Directory_Operations.Iteration} (@code{g-diopit.ads}) |
24024 | ||
24025 | ||
24026 | @geindex GNAT.Directory_Operations.Iteration (g-diopit.ads) | |
24027 | ||
24028 | @geindex Directory operations iteration | |
24029 | ||
24030 | A child unit of GNAT.Directory_Operations providing additional operations | |
24031 | for iterating through directories. | |
24032 | ||
24033 | @node GNAT Dynamic_HTables g-dynhta ads,GNAT Dynamic_Tables g-dyntab ads,GNAT Directory_Operations Iteration g-diopit ads,The GNAT Library | |
04d6c745 | 24034 | @anchor{gnat_rm/the_gnat_library gnat-dynamic-htables-g-dynhta-ads}@anchor{35a}@anchor{gnat_rm/the_gnat_library id63}@anchor{35b} |
64d5610f ML |
24035 | @section @code{GNAT.Dynamic_HTables} (@code{g-dynhta.ads}) |
24036 | ||
24037 | ||
24038 | @geindex GNAT.Dynamic_HTables (g-dynhta.ads) | |
24039 | ||
24040 | @geindex Hash tables | |
24041 | ||
24042 | A generic implementation of hash tables that can be used to hash arbitrary | |
24043 | data. Provided in two forms, a simple form with built in hash functions, | |
24044 | and a more complex form in which the hash function is supplied. | |
24045 | ||
24046 | This package provides a facility similar to that of @code{GNAT.HTable}, | |
24047 | except that this package declares a type that can be used to define | |
24048 | dynamic instances of the hash table, while an instantiation of | |
24049 | @code{GNAT.HTable} creates a single instance of the hash table. | |
24050 | ||
24051 | @node GNAT Dynamic_Tables g-dyntab ads,GNAT Encode_String g-encstr ads,GNAT Dynamic_HTables g-dynhta ads,The GNAT Library | |
04d6c745 | 24052 | @anchor{gnat_rm/the_gnat_library gnat-dynamic-tables-g-dyntab-ads}@anchor{35c}@anchor{gnat_rm/the_gnat_library id64}@anchor{35d} |
64d5610f ML |
24053 | @section @code{GNAT.Dynamic_Tables} (@code{g-dyntab.ads}) |
24054 | ||
24055 | ||
24056 | @geindex GNAT.Dynamic_Tables (g-dyntab.ads) | |
24057 | ||
24058 | @geindex Table implementation | |
24059 | ||
24060 | @geindex Arrays | |
24061 | @geindex extendable | |
24062 | ||
24063 | A generic package providing a single dimension array abstraction where the | |
24064 | length of the array can be dynamically modified. | |
24065 | ||
24066 | This package provides a facility similar to that of @code{GNAT.Table}, | |
24067 | except that this package declares a type that can be used to define | |
24068 | dynamic instances of the table, while an instantiation of | |
24069 | @code{GNAT.Table} creates a single instance of the table type. | |
24070 | ||
24071 | @node GNAT Encode_String g-encstr ads,GNAT Encode_UTF8_String g-enutst ads,GNAT Dynamic_Tables g-dyntab ads,The GNAT Library | |
04d6c745 | 24072 | @anchor{gnat_rm/the_gnat_library gnat-encode-string-g-encstr-ads}@anchor{35e}@anchor{gnat_rm/the_gnat_library id65}@anchor{35f} |
64d5610f ML |
24073 | @section @code{GNAT.Encode_String} (@code{g-encstr.ads}) |
24074 | ||
24075 | ||
24076 | @geindex GNAT.Encode_String (g-encstr.ads) | |
24077 | ||
24078 | @geindex Encoding strings | |
24079 | ||
24080 | @geindex String encoding | |
24081 | ||
24082 | @geindex Wide character encoding | |
24083 | ||
24084 | @geindex UTF-8 | |
24085 | ||
24086 | @geindex Unicode | |
24087 | ||
24088 | A generic package providing routines for encoding wide character and wide | |
24089 | wide character strings as sequences of 8-bit characters using a specified | |
24090 | encoding method. Useful in conjunction with Unicode character coding. | |
24091 | Note there is a preinstantiation for UTF-8. See next entry. | |
24092 | ||
24093 | @node GNAT Encode_UTF8_String g-enutst ads,GNAT Exception_Actions g-excact ads,GNAT Encode_String g-encstr ads,The GNAT Library | |
04d6c745 | 24094 | @anchor{gnat_rm/the_gnat_library gnat-encode-utf8-string-g-enutst-ads}@anchor{360}@anchor{gnat_rm/the_gnat_library id66}@anchor{361} |
64d5610f ML |
24095 | @section @code{GNAT.Encode_UTF8_String} (@code{g-enutst.ads}) |
24096 | ||
24097 | ||
24098 | @geindex GNAT.Encode_UTF8_String (g-enutst.ads) | |
24099 | ||
24100 | @geindex Encoding strings | |
24101 | ||
24102 | @geindex Encoding UTF-8 strings | |
24103 | ||
24104 | @geindex UTF-8 string encoding | |
24105 | ||
24106 | @geindex Wide character encoding | |
24107 | ||
24108 | @geindex UTF-8 | |
24109 | ||
24110 | @geindex Unicode | |
24111 | ||
24112 | A preinstantiation of GNAT.Encode_Strings for UTF-8 encoding. | |
24113 | ||
24114 | @node GNAT Exception_Actions g-excact ads,GNAT Exception_Traces g-exctra ads,GNAT Encode_UTF8_String g-enutst ads,The GNAT Library | |
04d6c745 | 24115 | @anchor{gnat_rm/the_gnat_library gnat-exception-actions-g-excact-ads}@anchor{362}@anchor{gnat_rm/the_gnat_library id67}@anchor{363} |
64d5610f ML |
24116 | @section @code{GNAT.Exception_Actions} (@code{g-excact.ads}) |
24117 | ||
24118 | ||
24119 | @geindex GNAT.Exception_Actions (g-excact.ads) | |
24120 | ||
24121 | @geindex Exception actions | |
24122 | ||
24123 | Provides callbacks when an exception is raised. Callbacks can be registered | |
24124 | for specific exceptions, or when any exception is raised. This | |
24125 | can be used for instance to force a core dump to ease debugging. | |
24126 | ||
24127 | @node GNAT Exception_Traces g-exctra ads,GNAT Exceptions g-except ads,GNAT Exception_Actions g-excact ads,The GNAT Library | |
04d6c745 | 24128 | @anchor{gnat_rm/the_gnat_library gnat-exception-traces-g-exctra-ads}@anchor{364}@anchor{gnat_rm/the_gnat_library id68}@anchor{365} |
64d5610f ML |
24129 | @section @code{GNAT.Exception_Traces} (@code{g-exctra.ads}) |
24130 | ||
24131 | ||
24132 | @geindex GNAT.Exception_Traces (g-exctra.ads) | |
24133 | ||
24134 | @geindex Exception traces | |
24135 | ||
24136 | @geindex Debugging | |
24137 | ||
24138 | Provides an interface allowing to control automatic output upon exception | |
24139 | occurrences. | |
24140 | ||
24141 | @node GNAT Exceptions g-except ads,GNAT Expect g-expect ads,GNAT Exception_Traces g-exctra ads,The GNAT Library | |
04d6c745 | 24142 | @anchor{gnat_rm/the_gnat_library gnat-exceptions-g-except-ads}@anchor{366}@anchor{gnat_rm/the_gnat_library id69}@anchor{367} |
64d5610f ML |
24143 | @section @code{GNAT.Exceptions} (@code{g-except.ads}) |
24144 | ||
24145 | ||
24146 | @geindex GNAT.Exceptions (g-except.ads) | |
24147 | ||
24148 | @geindex Exceptions | |
24149 | @geindex Pure | |
24150 | ||
24151 | @geindex Pure packages | |
24152 | @geindex exceptions | |
24153 | ||
24154 | Normally it is not possible to raise an exception with | |
24155 | a message from a subprogram in a pure package, since the | |
24156 | necessary types and subprograms are in @code{Ada.Exceptions} | |
24157 | which is not a pure unit. @code{GNAT.Exceptions} provides a | |
24158 | facility for getting around this limitation for a few | |
eeba836b | 24159 | predefined exceptions, and for example allows raising |
64d5610f ML |
24160 | @code{Constraint_Error} with a message from a pure subprogram. |
24161 | ||
24162 | @node GNAT Expect g-expect ads,GNAT Expect TTY g-exptty ads,GNAT Exceptions g-except ads,The GNAT Library | |
04d6c745 | 24163 | @anchor{gnat_rm/the_gnat_library gnat-expect-g-expect-ads}@anchor{368}@anchor{gnat_rm/the_gnat_library id70}@anchor{369} |
64d5610f ML |
24164 | @section @code{GNAT.Expect} (@code{g-expect.ads}) |
24165 | ||
24166 | ||
24167 | @geindex GNAT.Expect (g-expect.ads) | |
24168 | ||
24169 | Provides a set of subprograms similar to what is available | |
24170 | with the standard Tcl Expect tool. | |
24171 | It allows you to easily spawn and communicate with an external process. | |
24172 | You can send commands or inputs to the process, and compare the output | |
24173 | with some expected regular expression. Currently @code{GNAT.Expect} | |
24174 | is implemented on all native GNAT ports. | |
24175 | It is not implemented for cross ports, and in particular is not | |
24176 | implemented for VxWorks or LynxOS. | |
24177 | ||
24178 | @node GNAT Expect TTY g-exptty ads,GNAT Float_Control g-flocon ads,GNAT Expect g-expect ads,The GNAT Library | |
04d6c745 | 24179 | @anchor{gnat_rm/the_gnat_library gnat-expect-tty-g-exptty-ads}@anchor{36a}@anchor{gnat_rm/the_gnat_library id71}@anchor{36b} |
64d5610f ML |
24180 | @section @code{GNAT.Expect.TTY} (@code{g-exptty.ads}) |
24181 | ||
24182 | ||
24183 | @geindex GNAT.Expect.TTY (g-exptty.ads) | |
24184 | ||
24185 | As GNAT.Expect but using pseudo-terminal. | |
24186 | Currently @code{GNAT.Expect.TTY} is implemented on all native GNAT | |
24187 | ports. It is not implemented for cross ports, and | |
24188 | in particular is not implemented for VxWorks or LynxOS. | |
24189 | ||
24190 | @node GNAT Float_Control g-flocon ads,GNAT Formatted_String g-forstr ads,GNAT Expect TTY g-exptty ads,The GNAT Library | |
04d6c745 | 24191 | @anchor{gnat_rm/the_gnat_library gnat-float-control-g-flocon-ads}@anchor{36c}@anchor{gnat_rm/the_gnat_library id72}@anchor{36d} |
64d5610f ML |
24192 | @section @code{GNAT.Float_Control} (@code{g-flocon.ads}) |
24193 | ||
24194 | ||
24195 | @geindex GNAT.Float_Control (g-flocon.ads) | |
24196 | ||
24197 | @geindex Floating-Point Processor | |
24198 | ||
24199 | Provides an interface for resetting the floating-point processor into the | |
24200 | mode required for correct semantic operation in Ada. Some third party | |
24201 | library calls may cause this mode to be modified, and the Reset procedure | |
24202 | in this package can be used to reestablish the required mode. | |
24203 | ||
24204 | @node GNAT Formatted_String g-forstr ads,GNAT Generic_Fast_Math_Functions g-gfmafu ads,GNAT Float_Control g-flocon ads,The GNAT Library | |
04d6c745 | 24205 | @anchor{gnat_rm/the_gnat_library gnat-formatted-string-g-forstr-ads}@anchor{36e}@anchor{gnat_rm/the_gnat_library id73}@anchor{36f} |
64d5610f ML |
24206 | @section @code{GNAT.Formatted_String} (@code{g-forstr.ads}) |
24207 | ||
24208 | ||
24209 | @geindex GNAT.Formatted_String (g-forstr.ads) | |
24210 | ||
24211 | @geindex Formatted String | |
24212 | ||
24213 | Provides support for C/C++ printf() formatted strings. The format is | |
eeba836b | 24214 | copied from the printf() routine and should therefore give identical |
64d5610f ML |
24215 | output. Some generic routines are provided to be able to use types |
24216 | derived from Integer, Float or enumerations as values for the | |
24217 | formatted string. | |
24218 | ||
24219 | @node GNAT Generic_Fast_Math_Functions g-gfmafu ads,GNAT Heap_Sort g-heasor ads,GNAT Formatted_String g-forstr ads,The GNAT Library | |
04d6c745 | 24220 | @anchor{gnat_rm/the_gnat_library gnat-generic-fast-math-functions-g-gfmafu-ads}@anchor{370}@anchor{gnat_rm/the_gnat_library id74}@anchor{371} |
64d5610f ML |
24221 | @section @code{GNAT.Generic_Fast_Math_Functions} (@code{g-gfmafu.ads}) |
24222 | ||
24223 | ||
24224 | @geindex GNAT.Generic_Fast_Math_Functions (g-gfmafu.ads) | |
24225 | ||
24226 | @geindex Mathematical functions | |
24227 | ||
24228 | Provides direct access to the underlying implementation of the common | |
24229 | mathematical functions, generally from the system mathematical library. | |
24230 | This differs from @code{Ada.Numerics.Generic_Elementary_Functions} in that | |
24231 | the implementation may deviate from the semantics specified for these | |
24232 | functions in the Reference Manual, for example @code{Numerics.Argument_Error} | |
24233 | is not raised. On selected platforms, some of these functions may also | |
24234 | have a vector implementation that can be automatically used by the | |
24235 | compiler when auto-vectorization is enabled. | |
24236 | ||
24237 | @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 | |
04d6c745 | 24238 | @anchor{gnat_rm/the_gnat_library gnat-heap-sort-g-heasor-ads}@anchor{372}@anchor{gnat_rm/the_gnat_library id75}@anchor{373} |
64d5610f ML |
24239 | @section @code{GNAT.Heap_Sort} (@code{g-heasor.ads}) |
24240 | ||
24241 | ||
24242 | @geindex GNAT.Heap_Sort (g-heasor.ads) | |
24243 | ||
24244 | @geindex Sorting | |
24245 | ||
24246 | Provides a general implementation of heap sort usable for sorting arbitrary | |
24247 | data items. Exchange and comparison procedures are provided by passing | |
24248 | access-to-procedure values. The algorithm used is a modified heap sort | |
24249 | that performs approximately N*log(N) comparisons in the worst case. | |
24250 | ||
24251 | @node GNAT Heap_Sort_A g-hesora ads,GNAT Heap_Sort_G g-hesorg ads,GNAT Heap_Sort g-heasor ads,The GNAT Library | |
04d6c745 | 24252 | @anchor{gnat_rm/the_gnat_library gnat-heap-sort-a-g-hesora-ads}@anchor{374}@anchor{gnat_rm/the_gnat_library id76}@anchor{375} |
64d5610f ML |
24253 | @section @code{GNAT.Heap_Sort_A} (@code{g-hesora.ads}) |
24254 | ||
24255 | ||
24256 | @geindex GNAT.Heap_Sort_A (g-hesora.ads) | |
24257 | ||
24258 | @geindex Sorting | |
24259 | ||
24260 | Provides a general implementation of heap sort usable for sorting arbitrary | |
24261 | data items. Move and comparison procedures are provided by passing | |
24262 | access-to-procedure values. The algorithm used is a modified heap sort | |
24263 | that performs approximately N*log(N) comparisons in the worst case. | |
24264 | This differs from @code{GNAT.Heap_Sort} in having a less convenient | |
24265 | interface, but may be slightly more efficient. | |
24266 | ||
24267 | @node GNAT Heap_Sort_G g-hesorg ads,GNAT HTable g-htable ads,GNAT Heap_Sort_A g-hesora ads,The GNAT Library | |
04d6c745 | 24268 | @anchor{gnat_rm/the_gnat_library gnat-heap-sort-g-g-hesorg-ads}@anchor{376}@anchor{gnat_rm/the_gnat_library id77}@anchor{377} |
64d5610f ML |
24269 | @section @code{GNAT.Heap_Sort_G} (@code{g-hesorg.ads}) |
24270 | ||
24271 | ||
24272 | @geindex GNAT.Heap_Sort_G (g-hesorg.ads) | |
24273 | ||
24274 | @geindex Sorting | |
24275 | ||
24276 | Similar to @code{Heap_Sort_A} except that the move and sorting procedures | |
24277 | are provided as generic parameters, this improves efficiency, especially | |
24278 | if the procedures can be inlined, at the expense of duplicating code for | |
24279 | multiple instantiations. | |
24280 | ||
24281 | @node GNAT HTable g-htable ads,GNAT IO g-io ads,GNAT Heap_Sort_G g-hesorg ads,The GNAT Library | |
04d6c745 | 24282 | @anchor{gnat_rm/the_gnat_library gnat-htable-g-htable-ads}@anchor{378}@anchor{gnat_rm/the_gnat_library id78}@anchor{379} |
64d5610f ML |
24283 | @section @code{GNAT.HTable} (@code{g-htable.ads}) |
24284 | ||
24285 | ||
24286 | @geindex GNAT.HTable (g-htable.ads) | |
24287 | ||
24288 | @geindex Hash tables | |
24289 | ||
24290 | A generic implementation of hash tables that can be used to hash arbitrary | |
24291 | data. Provides two approaches, one a simple static approach, and the other | |
24292 | allowing arbitrary dynamic hash tables. | |
24293 | ||
24294 | @node GNAT IO g-io ads,GNAT IO_Aux g-io_aux ads,GNAT HTable g-htable ads,The GNAT Library | |
04d6c745 | 24295 | @anchor{gnat_rm/the_gnat_library gnat-io-g-io-ads}@anchor{37a}@anchor{gnat_rm/the_gnat_library id79}@anchor{37b} |
64d5610f ML |
24296 | @section @code{GNAT.IO} (@code{g-io.ads}) |
24297 | ||
24298 | ||
24299 | @geindex GNAT.IO (g-io.ads) | |
24300 | ||
24301 | @geindex Simple I/O | |
24302 | ||
24303 | @geindex Input/Output facilities | |
24304 | ||
24305 | A simple preelaborable input-output package that provides a subset of | |
24306 | simple Text_IO functions for reading characters and strings from | |
24307 | Standard_Input, and writing characters, strings and integers to either | |
24308 | Standard_Output or Standard_Error. | |
24309 | ||
24310 | @node GNAT IO_Aux g-io_aux ads,GNAT Lock_Files g-locfil ads,GNAT IO g-io ads,The GNAT Library | |
04d6c745 | 24311 | @anchor{gnat_rm/the_gnat_library gnat-io-aux-g-io-aux-ads}@anchor{37c}@anchor{gnat_rm/the_gnat_library id80}@anchor{37d} |
64d5610f ML |
24312 | @section @code{GNAT.IO_Aux} (@code{g-io_aux.ads}) |
24313 | ||
24314 | ||
24315 | @geindex GNAT.IO_Aux (g-io_aux.ads) | |
24316 | ||
24317 | @geindex Text_IO | |
24318 | ||
24319 | @geindex Input/Output facilities | |
24320 | ||
24321 | Provides some auxiliary functions for use with Text_IO, including a test | |
24322 | for whether a file exists, and functions for reading a line of text. | |
24323 | ||
24324 | @node GNAT Lock_Files g-locfil ads,GNAT MBBS_Discrete_Random g-mbdira ads,GNAT IO_Aux g-io_aux ads,The GNAT Library | |
04d6c745 | 24325 | @anchor{gnat_rm/the_gnat_library gnat-lock-files-g-locfil-ads}@anchor{37e}@anchor{gnat_rm/the_gnat_library id81}@anchor{37f} |
64d5610f ML |
24326 | @section @code{GNAT.Lock_Files} (@code{g-locfil.ads}) |
24327 | ||
24328 | ||
24329 | @geindex GNAT.Lock_Files (g-locfil.ads) | |
24330 | ||
24331 | @geindex File locking | |
24332 | ||
24333 | @geindex Locking using files | |
24334 | ||
24335 | Provides a general interface for using files as locks. Can be used for | |
24336 | providing program level synchronization. | |
24337 | ||
24338 | @node GNAT MBBS_Discrete_Random g-mbdira ads,GNAT MBBS_Float_Random g-mbflra ads,GNAT Lock_Files g-locfil ads,The GNAT Library | |
04d6c745 | 24339 | @anchor{gnat_rm/the_gnat_library gnat-mbbs-discrete-random-g-mbdira-ads}@anchor{380}@anchor{gnat_rm/the_gnat_library id82}@anchor{381} |
64d5610f ML |
24340 | @section @code{GNAT.MBBS_Discrete_Random} (@code{g-mbdira.ads}) |
24341 | ||
24342 | ||
24343 | @geindex GNAT.MBBS_Discrete_Random (g-mbdira.ads) | |
24344 | ||
24345 | @geindex Random number generation | |
24346 | ||
24347 | The original implementation of @code{Ada.Numerics.Discrete_Random}. Uses | |
24348 | a modified version of the Blum-Blum-Shub generator. | |
24349 | ||
24350 | @node GNAT MBBS_Float_Random g-mbflra ads,GNAT MD5 g-md5 ads,GNAT MBBS_Discrete_Random g-mbdira ads,The GNAT Library | |
04d6c745 | 24351 | @anchor{gnat_rm/the_gnat_library gnat-mbbs-float-random-g-mbflra-ads}@anchor{382}@anchor{gnat_rm/the_gnat_library id83}@anchor{383} |
64d5610f ML |
24352 | @section @code{GNAT.MBBS_Float_Random} (@code{g-mbflra.ads}) |
24353 | ||
24354 | ||
24355 | @geindex GNAT.MBBS_Float_Random (g-mbflra.ads) | |
24356 | ||
24357 | @geindex Random number generation | |
24358 | ||
24359 | The original implementation of @code{Ada.Numerics.Float_Random}. Uses | |
24360 | a modified version of the Blum-Blum-Shub generator. | |
24361 | ||
24362 | @node GNAT MD5 g-md5 ads,GNAT Memory_Dump g-memdum ads,GNAT MBBS_Float_Random g-mbflra ads,The GNAT Library | |
04d6c745 | 24363 | @anchor{gnat_rm/the_gnat_library gnat-md5-g-md5-ads}@anchor{384}@anchor{gnat_rm/the_gnat_library id84}@anchor{385} |
64d5610f ML |
24364 | @section @code{GNAT.MD5} (@code{g-md5.ads}) |
24365 | ||
24366 | ||
24367 | @geindex GNAT.MD5 (g-md5.ads) | |
24368 | ||
24369 | @geindex Message Digest MD5 | |
24370 | ||
24371 | Implements the MD5 Message-Digest Algorithm as described in RFC 1321, and | |
24372 | the HMAC-MD5 message authentication function as described in RFC 2104 and | |
24373 | FIPS PUB 198. | |
24374 | ||
24375 | @node GNAT Memory_Dump g-memdum ads,GNAT Most_Recent_Exception g-moreex ads,GNAT MD5 g-md5 ads,The GNAT Library | |
04d6c745 | 24376 | @anchor{gnat_rm/the_gnat_library gnat-memory-dump-g-memdum-ads}@anchor{386}@anchor{gnat_rm/the_gnat_library id85}@anchor{387} |
64d5610f ML |
24377 | @section @code{GNAT.Memory_Dump} (@code{g-memdum.ads}) |
24378 | ||
24379 | ||
24380 | @geindex GNAT.Memory_Dump (g-memdum.ads) | |
24381 | ||
24382 | @geindex Dump Memory | |
24383 | ||
24384 | Provides a convenient routine for dumping raw memory to either the | |
24385 | standard output or standard error files. Uses GNAT.IO for actual | |
24386 | output. | |
24387 | ||
24388 | @node GNAT Most_Recent_Exception g-moreex ads,GNAT OS_Lib g-os_lib ads,GNAT Memory_Dump g-memdum ads,The GNAT Library | |
04d6c745 | 24389 | @anchor{gnat_rm/the_gnat_library gnat-most-recent-exception-g-moreex-ads}@anchor{388}@anchor{gnat_rm/the_gnat_library id86}@anchor{389} |
64d5610f ML |
24390 | @section @code{GNAT.Most_Recent_Exception} (@code{g-moreex.ads}) |
24391 | ||
24392 | ||
24393 | @geindex GNAT.Most_Recent_Exception (g-moreex.ads) | |
24394 | ||
24395 | @geindex Exception | |
24396 | @geindex obtaining most recent | |
24397 | ||
24398 | Provides access to the most recently raised exception. Can be used for | |
24399 | various logging purposes, including duplicating functionality of some | |
24400 | Ada 83 implementation dependent extensions. | |
24401 | ||
24402 | @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 | |
04d6c745 | 24403 | @anchor{gnat_rm/the_gnat_library gnat-os-lib-g-os-lib-ads}@anchor{38a}@anchor{gnat_rm/the_gnat_library id87}@anchor{38b} |
64d5610f ML |
24404 | @section @code{GNAT.OS_Lib} (@code{g-os_lib.ads}) |
24405 | ||
24406 | ||
24407 | @geindex GNAT.OS_Lib (g-os_lib.ads) | |
24408 | ||
24409 | @geindex Operating System interface | |
24410 | ||
24411 | @geindex Spawn capability | |
24412 | ||
24413 | Provides a range of target independent operating system interface functions, | |
24414 | including time/date management, file operations, subprocess management, | |
24415 | including a portable spawn procedure, and access to environment variables | |
24416 | and error return codes. | |
24417 | ||
24418 | @node GNAT Perfect_Hash_Generators g-pehage ads,GNAT Random_Numbers g-rannum ads,GNAT OS_Lib g-os_lib ads,The GNAT Library | |
04d6c745 | 24419 | @anchor{gnat_rm/the_gnat_library gnat-perfect-hash-generators-g-pehage-ads}@anchor{38c}@anchor{gnat_rm/the_gnat_library id88}@anchor{38d} |
64d5610f ML |
24420 | @section @code{GNAT.Perfect_Hash_Generators} (@code{g-pehage.ads}) |
24421 | ||
24422 | ||
24423 | @geindex GNAT.Perfect_Hash_Generators (g-pehage.ads) | |
24424 | ||
24425 | @geindex Hash functions | |
24426 | ||
24427 | Provides a generator of static minimal perfect hash functions. No | |
24428 | collisions occur and each item can be retrieved from the table in one | |
24429 | probe (perfect property). The hash table size corresponds to the exact | |
24430 | size of the key set and no larger (minimal property). The key set has to | |
eeba836b | 24431 | be known in advance (static property). The hash functions are also order |
64d5610f ML |
24432 | preserving. If w2 is inserted after w1 in the generator, their |
24433 | hashcode are in the same order. These hashing functions are very | |
24434 | convenient for use with realtime applications. | |
24435 | ||
24436 | @node GNAT Random_Numbers g-rannum ads,GNAT Regexp g-regexp ads,GNAT Perfect_Hash_Generators g-pehage ads,The GNAT Library | |
04d6c745 | 24437 | @anchor{gnat_rm/the_gnat_library gnat-random-numbers-g-rannum-ads}@anchor{38e}@anchor{gnat_rm/the_gnat_library id89}@anchor{38f} |
64d5610f ML |
24438 | @section @code{GNAT.Random_Numbers} (@code{g-rannum.ads}) |
24439 | ||
24440 | ||
24441 | @geindex GNAT.Random_Numbers (g-rannum.ads) | |
24442 | ||
24443 | @geindex Random number generation | |
24444 | ||
24445 | Provides random number capabilities which extend those available in the | |
24446 | standard Ada library and are more convenient to use. | |
24447 | ||
24448 | @node GNAT Regexp g-regexp ads,GNAT Registry g-regist ads,GNAT Random_Numbers g-rannum ads,The GNAT Library | |
04d6c745 | 24449 | @anchor{gnat_rm/the_gnat_library gnat-regexp-g-regexp-ads}@anchor{265}@anchor{gnat_rm/the_gnat_library id90}@anchor{390} |
64d5610f ML |
24450 | @section @code{GNAT.Regexp} (@code{g-regexp.ads}) |
24451 | ||
24452 | ||
24453 | @geindex GNAT.Regexp (g-regexp.ads) | |
24454 | ||
24455 | @geindex Regular expressions | |
24456 | ||
24457 | @geindex Pattern matching | |
24458 | ||
24459 | A simple implementation of regular expressions, using a subset of regular | |
24460 | expression syntax copied from familiar Unix style utilities. This is the | |
24461 | simplest of the three pattern matching packages provided, and is particularly | |
24462 | suitable for ‘file globbing’ applications. | |
24463 | ||
24464 | @node GNAT Registry g-regist ads,GNAT Regpat g-regpat ads,GNAT Regexp g-regexp ads,The GNAT Library | |
04d6c745 | 24465 | @anchor{gnat_rm/the_gnat_library gnat-registry-g-regist-ads}@anchor{391}@anchor{gnat_rm/the_gnat_library id91}@anchor{392} |
64d5610f ML |
24466 | @section @code{GNAT.Registry} (@code{g-regist.ads}) |
24467 | ||
24468 | ||
24469 | @geindex GNAT.Registry (g-regist.ads) | |
24470 | ||
24471 | @geindex Windows Registry | |
24472 | ||
24473 | This is a high level binding to the Windows registry. It is possible to | |
24474 | do simple things like reading a key value, creating a new key. For full | |
24475 | registry API, but at a lower level of abstraction, refer to the Win32.Winreg | |
24476 | package provided with the Win32Ada binding | |
24477 | ||
24478 | @node GNAT Regpat g-regpat ads,GNAT Rewrite_Data g-rewdat ads,GNAT Registry g-regist ads,The GNAT Library | |
04d6c745 | 24479 | @anchor{gnat_rm/the_gnat_library gnat-regpat-g-regpat-ads}@anchor{393}@anchor{gnat_rm/the_gnat_library id92}@anchor{394} |
64d5610f ML |
24480 | @section @code{GNAT.Regpat} (@code{g-regpat.ads}) |
24481 | ||
24482 | ||
24483 | @geindex GNAT.Regpat (g-regpat.ads) | |
24484 | ||
24485 | @geindex Regular expressions | |
24486 | ||
24487 | @geindex Pattern matching | |
24488 | ||
24489 | A complete implementation of Unix-style regular expression matching, copied | |
24490 | from the original V7 style regular expression library written in C by | |
24491 | Henry Spencer (and binary compatible with this C library). | |
24492 | ||
24493 | @node GNAT Rewrite_Data g-rewdat ads,GNAT Secondary_Stack_Info g-sestin ads,GNAT Regpat g-regpat ads,The GNAT Library | |
04d6c745 | 24494 | @anchor{gnat_rm/the_gnat_library gnat-rewrite-data-g-rewdat-ads}@anchor{395}@anchor{gnat_rm/the_gnat_library id93}@anchor{396} |
64d5610f ML |
24495 | @section @code{GNAT.Rewrite_Data} (@code{g-rewdat.ads}) |
24496 | ||
24497 | ||
24498 | @geindex GNAT.Rewrite_Data (g-rewdat.ads) | |
24499 | ||
24500 | @geindex Rewrite data | |
24501 | ||
24502 | A unit to rewrite on-the-fly string occurrences in a stream of | |
24503 | data. The implementation has a very minimal memory footprint as the | |
24504 | full content to be processed is not loaded into memory all at once. This makes | |
24505 | this interface usable for large files or socket streams. | |
24506 | ||
24507 | @node GNAT Secondary_Stack_Info g-sestin ads,GNAT Semaphores g-semaph ads,GNAT Rewrite_Data g-rewdat ads,The GNAT Library | |
04d6c745 | 24508 | @anchor{gnat_rm/the_gnat_library gnat-secondary-stack-info-g-sestin-ads}@anchor{397}@anchor{gnat_rm/the_gnat_library id94}@anchor{398} |
64d5610f ML |
24509 | @section @code{GNAT.Secondary_Stack_Info} (@code{g-sestin.ads}) |
24510 | ||
24511 | ||
24512 | @geindex GNAT.Secondary_Stack_Info (g-sestin.ads) | |
24513 | ||
24514 | @geindex Secondary Stack Info | |
24515 | ||
eeba836b | 24516 | Provides the capability to query the high water mark of the current task’s |
64d5610f ML |
24517 | secondary stack. |
24518 | ||
24519 | @node GNAT Semaphores g-semaph ads,GNAT Serial_Communications g-sercom ads,GNAT Secondary_Stack_Info g-sestin ads,The GNAT Library | |
04d6c745 | 24520 | @anchor{gnat_rm/the_gnat_library gnat-semaphores-g-semaph-ads}@anchor{399}@anchor{gnat_rm/the_gnat_library id95}@anchor{39a} |
64d5610f ML |
24521 | @section @code{GNAT.Semaphores} (@code{g-semaph.ads}) |
24522 | ||
24523 | ||
24524 | @geindex GNAT.Semaphores (g-semaph.ads) | |
24525 | ||
24526 | @geindex Semaphores | |
24527 | ||
24528 | Provides classic counting and binary semaphores using protected types. | |
24529 | ||
24530 | @node GNAT Serial_Communications g-sercom ads,GNAT SHA1 g-sha1 ads,GNAT Semaphores g-semaph ads,The GNAT Library | |
04d6c745 | 24531 | @anchor{gnat_rm/the_gnat_library gnat-serial-communications-g-sercom-ads}@anchor{39b}@anchor{gnat_rm/the_gnat_library id96}@anchor{39c} |
64d5610f ML |
24532 | @section @code{GNAT.Serial_Communications} (@code{g-sercom.ads}) |
24533 | ||
24534 | ||
24535 | @geindex GNAT.Serial_Communications (g-sercom.ads) | |
24536 | ||
24537 | @geindex Serial_Communications | |
24538 | ||
24539 | Provides a simple interface to send and receive data over a serial | |
24540 | port. This is only supported on GNU/Linux and Windows. | |
24541 | ||
24542 | @node GNAT SHA1 g-sha1 ads,GNAT SHA224 g-sha224 ads,GNAT Serial_Communications g-sercom ads,The GNAT Library | |
04d6c745 | 24543 | @anchor{gnat_rm/the_gnat_library gnat-sha1-g-sha1-ads}@anchor{39d}@anchor{gnat_rm/the_gnat_library id97}@anchor{39e} |
64d5610f ML |
24544 | @section @code{GNAT.SHA1} (@code{g-sha1.ads}) |
24545 | ||
24546 | ||
24547 | @geindex GNAT.SHA1 (g-sha1.ads) | |
24548 | ||
24549 | @geindex Secure Hash Algorithm SHA-1 | |
24550 | ||
24551 | Implements the SHA-1 Secure Hash Algorithm as described in FIPS PUB 180-3 | |
24552 | and RFC 3174, and the HMAC-SHA1 message authentication function as described | |
24553 | in RFC 2104 and FIPS PUB 198. | |
24554 | ||
24555 | @node GNAT SHA224 g-sha224 ads,GNAT SHA256 g-sha256 ads,GNAT SHA1 g-sha1 ads,The GNAT Library | |
04d6c745 | 24556 | @anchor{gnat_rm/the_gnat_library gnat-sha224-g-sha224-ads}@anchor{39f}@anchor{gnat_rm/the_gnat_library id98}@anchor{3a0} |
64d5610f ML |
24557 | @section @code{GNAT.SHA224} (@code{g-sha224.ads}) |
24558 | ||
24559 | ||
24560 | @geindex GNAT.SHA224 (g-sha224.ads) | |
24561 | ||
24562 | @geindex Secure Hash Algorithm SHA-224 | |
24563 | ||
24564 | Implements the SHA-224 Secure Hash Algorithm as described in FIPS PUB 180-3, | |
24565 | and the HMAC-SHA224 message authentication function as described | |
24566 | in RFC 2104 and FIPS PUB 198. | |
24567 | ||
24568 | @node GNAT SHA256 g-sha256 ads,GNAT SHA384 g-sha384 ads,GNAT SHA224 g-sha224 ads,The GNAT Library | |
04d6c745 | 24569 | @anchor{gnat_rm/the_gnat_library gnat-sha256-g-sha256-ads}@anchor{3a1}@anchor{gnat_rm/the_gnat_library id99}@anchor{3a2} |
64d5610f ML |
24570 | @section @code{GNAT.SHA256} (@code{g-sha256.ads}) |
24571 | ||
24572 | ||
24573 | @geindex GNAT.SHA256 (g-sha256.ads) | |
24574 | ||
24575 | @geindex Secure Hash Algorithm SHA-256 | |
24576 | ||
24577 | Implements the SHA-256 Secure Hash Algorithm as described in FIPS PUB 180-3, | |
24578 | and the HMAC-SHA256 message authentication function as described | |
24579 | in RFC 2104 and FIPS PUB 198. | |
24580 | ||
24581 | @node GNAT SHA384 g-sha384 ads,GNAT SHA512 g-sha512 ads,GNAT SHA256 g-sha256 ads,The GNAT Library | |
04d6c745 | 24582 | @anchor{gnat_rm/the_gnat_library gnat-sha384-g-sha384-ads}@anchor{3a3}@anchor{gnat_rm/the_gnat_library id100}@anchor{3a4} |
64d5610f ML |
24583 | @section @code{GNAT.SHA384} (@code{g-sha384.ads}) |
24584 | ||
24585 | ||
24586 | @geindex GNAT.SHA384 (g-sha384.ads) | |
24587 | ||
24588 | @geindex Secure Hash Algorithm SHA-384 | |
24589 | ||
24590 | Implements the SHA-384 Secure Hash Algorithm as described in FIPS PUB 180-3, | |
24591 | and the HMAC-SHA384 message authentication function as described | |
24592 | in RFC 2104 and FIPS PUB 198. | |
24593 | ||
24594 | @node GNAT SHA512 g-sha512 ads,GNAT Signals g-signal ads,GNAT SHA384 g-sha384 ads,The GNAT Library | |
04d6c745 | 24595 | @anchor{gnat_rm/the_gnat_library gnat-sha512-g-sha512-ads}@anchor{3a5}@anchor{gnat_rm/the_gnat_library id101}@anchor{3a6} |
64d5610f ML |
24596 | @section @code{GNAT.SHA512} (@code{g-sha512.ads}) |
24597 | ||
24598 | ||
24599 | @geindex GNAT.SHA512 (g-sha512.ads) | |
24600 | ||
24601 | @geindex Secure Hash Algorithm SHA-512 | |
24602 | ||
24603 | Implements the SHA-512 Secure Hash Algorithm as described in FIPS PUB 180-3, | |
24604 | and the HMAC-SHA512 message authentication function as described | |
24605 | in RFC 2104 and FIPS PUB 198. | |
24606 | ||
24607 | @node GNAT Signals g-signal ads,GNAT Sockets g-socket ads,GNAT SHA512 g-sha512 ads,The GNAT Library | |
04d6c745 | 24608 | @anchor{gnat_rm/the_gnat_library gnat-signals-g-signal-ads}@anchor{3a7}@anchor{gnat_rm/the_gnat_library id102}@anchor{3a8} |
64d5610f ML |
24609 | @section @code{GNAT.Signals} (@code{g-signal.ads}) |
24610 | ||
24611 | ||
24612 | @geindex GNAT.Signals (g-signal.ads) | |
24613 | ||
24614 | @geindex Signals | |
24615 | ||
24616 | Provides the ability to manipulate the blocked status of signals on supported | |
24617 | targets. | |
24618 | ||
24619 | @node GNAT Sockets g-socket ads,GNAT Source_Info g-souinf ads,GNAT Signals g-signal ads,The GNAT Library | |
04d6c745 | 24620 | @anchor{gnat_rm/the_gnat_library gnat-sockets-g-socket-ads}@anchor{3a9}@anchor{gnat_rm/the_gnat_library id103}@anchor{3aa} |
64d5610f ML |
24621 | @section @code{GNAT.Sockets} (@code{g-socket.ads}) |
24622 | ||
24623 | ||
24624 | @geindex GNAT.Sockets (g-socket.ads) | |
24625 | ||
24626 | @geindex Sockets | |
24627 | ||
24628 | A high level and portable interface to develop sockets based applications. | |
24629 | This package is based on the sockets thin binding found in | |
24630 | @code{GNAT.Sockets.Thin}. Currently @code{GNAT.Sockets} is implemented | |
eeba836b | 24631 | on all native GNAT ports and on VxWorks cross ports. It is not implemented for |
64d5610f ML |
24632 | the LynxOS cross port. |
24633 | ||
24634 | @node GNAT Source_Info g-souinf ads,GNAT Spelling_Checker g-speche ads,GNAT Sockets g-socket ads,The GNAT Library | |
04d6c745 | 24635 | @anchor{gnat_rm/the_gnat_library gnat-source-info-g-souinf-ads}@anchor{3ab}@anchor{gnat_rm/the_gnat_library id104}@anchor{3ac} |
64d5610f ML |
24636 | @section @code{GNAT.Source_Info} (@code{g-souinf.ads}) |
24637 | ||
24638 | ||
24639 | @geindex GNAT.Source_Info (g-souinf.ads) | |
24640 | ||
24641 | @geindex Source Information | |
24642 | ||
24643 | Provides subprograms that give access to source code information known at | |
24644 | compile time, such as the current file name and line number. Also provides | |
24645 | subprograms yielding the date and time of the current compilation (like the | |
24646 | C macros @code{__DATE__} and @code{__TIME__}) | |
24647 | ||
24648 | @node GNAT Spelling_Checker g-speche ads,GNAT Spelling_Checker_Generic g-spchge ads,GNAT Source_Info g-souinf ads,The GNAT Library | |
04d6c745 | 24649 | @anchor{gnat_rm/the_gnat_library gnat-spelling-checker-g-speche-ads}@anchor{3ad}@anchor{gnat_rm/the_gnat_library id105}@anchor{3ae} |
64d5610f ML |
24650 | @section @code{GNAT.Spelling_Checker} (@code{g-speche.ads}) |
24651 | ||
24652 | ||
24653 | @geindex GNAT.Spelling_Checker (g-speche.ads) | |
24654 | ||
24655 | @geindex Spell checking | |
24656 | ||
24657 | Provides a function for determining whether one string is a plausible | |
24658 | near misspelling of another string. | |
24659 | ||
24660 | @node GNAT Spelling_Checker_Generic g-spchge ads,GNAT Spitbol Patterns g-spipat ads,GNAT Spelling_Checker g-speche ads,The GNAT Library | |
04d6c745 | 24661 | @anchor{gnat_rm/the_gnat_library gnat-spelling-checker-generic-g-spchge-ads}@anchor{3af}@anchor{gnat_rm/the_gnat_library id106}@anchor{3b0} |
64d5610f ML |
24662 | @section @code{GNAT.Spelling_Checker_Generic} (@code{g-spchge.ads}) |
24663 | ||
24664 | ||
24665 | @geindex GNAT.Spelling_Checker_Generic (g-spchge.ads) | |
24666 | ||
24667 | @geindex Spell checking | |
24668 | ||
24669 | Provides a generic function that can be instantiated with a string type for | |
24670 | determining whether one string is a plausible near misspelling of another | |
24671 | string. | |
24672 | ||
24673 | @node GNAT Spitbol Patterns g-spipat ads,GNAT Spitbol g-spitbo ads,GNAT Spelling_Checker_Generic g-spchge ads,The GNAT Library | |
04d6c745 | 24674 | @anchor{gnat_rm/the_gnat_library gnat-spitbol-patterns-g-spipat-ads}@anchor{3b1}@anchor{gnat_rm/the_gnat_library id107}@anchor{3b2} |
64d5610f ML |
24675 | @section @code{GNAT.Spitbol.Patterns} (@code{g-spipat.ads}) |
24676 | ||
24677 | ||
24678 | @geindex GNAT.Spitbol.Patterns (g-spipat.ads) | |
24679 | ||
24680 | @geindex SPITBOL pattern matching | |
24681 | ||
24682 | @geindex Pattern matching | |
24683 | ||
24684 | A complete implementation of SNOBOL4 style pattern matching. This is the | |
24685 | most elaborate of the pattern matching packages provided. It fully duplicates | |
24686 | the SNOBOL4 dynamic pattern construction and matching capabilities, using the | |
24687 | efficient algorithm developed by Robert Dewar for the SPITBOL system. | |
24688 | ||
24689 | @node GNAT Spitbol g-spitbo ads,GNAT Spitbol Table_Boolean g-sptabo ads,GNAT Spitbol Patterns g-spipat ads,The GNAT Library | |
04d6c745 | 24690 | @anchor{gnat_rm/the_gnat_library gnat-spitbol-g-spitbo-ads}@anchor{3b3}@anchor{gnat_rm/the_gnat_library id108}@anchor{3b4} |
64d5610f ML |
24691 | @section @code{GNAT.Spitbol} (@code{g-spitbo.ads}) |
24692 | ||
24693 | ||
24694 | @geindex GNAT.Spitbol (g-spitbo.ads) | |
24695 | ||
24696 | @geindex SPITBOL interface | |
24697 | ||
24698 | The top level package of the collection of SPITBOL-style functionality, this | |
24699 | package provides basic SNOBOL4 string manipulation functions, such as | |
24700 | Pad, Reverse, Trim, Substr capability, as well as a generic table function | |
24701 | useful for constructing arbitrary mappings from strings in the style of | |
24702 | the SNOBOL4 TABLE function. | |
24703 | ||
24704 | @node GNAT Spitbol Table_Boolean g-sptabo ads,GNAT Spitbol Table_Integer g-sptain ads,GNAT Spitbol g-spitbo ads,The GNAT Library | |
04d6c745 | 24705 | @anchor{gnat_rm/the_gnat_library gnat-spitbol-table-boolean-g-sptabo-ads}@anchor{3b5}@anchor{gnat_rm/the_gnat_library id109}@anchor{3b6} |
64d5610f ML |
24706 | @section @code{GNAT.Spitbol.Table_Boolean} (@code{g-sptabo.ads}) |
24707 | ||
24708 | ||
24709 | @geindex GNAT.Spitbol.Table_Boolean (g-sptabo.ads) | |
24710 | ||
24711 | @geindex Sets of strings | |
24712 | ||
24713 | @geindex SPITBOL Tables | |
24714 | ||
24715 | A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table} | |
24716 | for type @code{Standard.Boolean}, giving an implementation of sets of | |
24717 | string values. | |
24718 | ||
24719 | @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 | |
04d6c745 | 24720 | @anchor{gnat_rm/the_gnat_library gnat-spitbol-table-integer-g-sptain-ads}@anchor{3b7}@anchor{gnat_rm/the_gnat_library id110}@anchor{3b8} |
64d5610f ML |
24721 | @section @code{GNAT.Spitbol.Table_Integer} (@code{g-sptain.ads}) |
24722 | ||
24723 | ||
24724 | @geindex GNAT.Spitbol.Table_Integer (g-sptain.ads) | |
24725 | ||
24726 | @geindex Integer maps | |
24727 | ||
24728 | @geindex Maps | |
24729 | ||
24730 | @geindex SPITBOL Tables | |
24731 | ||
24732 | A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table} | |
24733 | for type @code{Standard.Integer}, giving an implementation of maps | |
24734 | from string to integer values. | |
24735 | ||
24736 | @node GNAT Spitbol Table_VString g-sptavs ads,GNAT SSE g-sse ads,GNAT Spitbol Table_Integer g-sptain ads,The GNAT Library | |
04d6c745 | 24737 | @anchor{gnat_rm/the_gnat_library gnat-spitbol-table-vstring-g-sptavs-ads}@anchor{3b9}@anchor{gnat_rm/the_gnat_library id111}@anchor{3ba} |
64d5610f ML |
24738 | @section @code{GNAT.Spitbol.Table_VString} (@code{g-sptavs.ads}) |
24739 | ||
24740 | ||
24741 | @geindex GNAT.Spitbol.Table_VString (g-sptavs.ads) | |
24742 | ||
24743 | @geindex String maps | |
24744 | ||
24745 | @geindex Maps | |
24746 | ||
24747 | @geindex SPITBOL Tables | |
24748 | ||
24749 | A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table} for | |
24750 | a variable length string type, giving an implementation of general | |
24751 | maps from strings to strings. | |
24752 | ||
24753 | @node GNAT SSE g-sse ads,GNAT SSE Vector_Types g-ssvety ads,GNAT Spitbol Table_VString g-sptavs ads,The GNAT Library | |
04d6c745 | 24754 | @anchor{gnat_rm/the_gnat_library gnat-sse-g-sse-ads}@anchor{3bb}@anchor{gnat_rm/the_gnat_library id112}@anchor{3bc} |
64d5610f ML |
24755 | @section @code{GNAT.SSE} (@code{g-sse.ads}) |
24756 | ||
24757 | ||
24758 | @geindex GNAT.SSE (g-sse.ads) | |
24759 | ||
24760 | Root of a set of units aimed at offering Ada bindings to a subset of | |
24761 | the Intel(r) Streaming SIMD Extensions with GNAT on the x86 family of | |
24762 | targets. It exposes vector component types together with a general | |
24763 | introduction to the binding contents and use. | |
24764 | ||
24765 | @node GNAT SSE Vector_Types g-ssvety ads,GNAT String_Hash g-strhas ads,GNAT SSE g-sse ads,The GNAT Library | |
04d6c745 | 24766 | @anchor{gnat_rm/the_gnat_library gnat-sse-vector-types-g-ssvety-ads}@anchor{3bd}@anchor{gnat_rm/the_gnat_library id113}@anchor{3be} |
64d5610f ML |
24767 | @section @code{GNAT.SSE.Vector_Types} (@code{g-ssvety.ads}) |
24768 | ||
24769 | ||
24770 | @geindex GNAT.SSE.Vector_Types (g-ssvety.ads) | |
24771 | ||
24772 | SSE vector types for use with SSE related intrinsics. | |
24773 | ||
24774 | @node GNAT String_Hash g-strhas ads,GNAT Strings g-string ads,GNAT SSE Vector_Types g-ssvety ads,The GNAT Library | |
04d6c745 | 24775 | @anchor{gnat_rm/the_gnat_library gnat-string-hash-g-strhas-ads}@anchor{3bf}@anchor{gnat_rm/the_gnat_library id114}@anchor{3c0} |
64d5610f ML |
24776 | @section @code{GNAT.String_Hash} (@code{g-strhas.ads}) |
24777 | ||
24778 | ||
24779 | @geindex GNAT.String_Hash (g-strhas.ads) | |
24780 | ||
24781 | @geindex Hash functions | |
24782 | ||
24783 | Provides a generic hash function working on arrays of scalars. Both the scalar | |
24784 | type and the hash result type are parameters. | |
24785 | ||
24786 | @node GNAT Strings g-string ads,GNAT String_Split g-strspl ads,GNAT String_Hash g-strhas ads,The GNAT Library | |
04d6c745 | 24787 | @anchor{gnat_rm/the_gnat_library gnat-strings-g-string-ads}@anchor{3c1}@anchor{gnat_rm/the_gnat_library id115}@anchor{3c2} |
64d5610f ML |
24788 | @section @code{GNAT.Strings} (@code{g-string.ads}) |
24789 | ||
24790 | ||
24791 | @geindex GNAT.Strings (g-string.ads) | |
24792 | ||
24793 | Common String access types and related subprograms. Basically it | |
24794 | defines a string access and an array of string access types. | |
24795 | ||
24796 | @node GNAT String_Split g-strspl ads,GNAT Table g-table ads,GNAT Strings g-string ads,The GNAT Library | |
04d6c745 | 24797 | @anchor{gnat_rm/the_gnat_library gnat-string-split-g-strspl-ads}@anchor{3c3}@anchor{gnat_rm/the_gnat_library id116}@anchor{3c4} |
64d5610f ML |
24798 | @section @code{GNAT.String_Split} (@code{g-strspl.ads}) |
24799 | ||
24800 | ||
24801 | @geindex GNAT.String_Split (g-strspl.ads) | |
24802 | ||
24803 | @geindex String splitter | |
24804 | ||
24805 | Useful string manipulation routines: given a set of separators, split | |
24806 | a string wherever the separators appear, and provide direct access | |
24807 | to the resulting slices. This package is instantiated from | |
24808 | @code{GNAT.Array_Split}. | |
24809 | ||
24810 | @node GNAT Table g-table ads,GNAT Task_Lock g-tasloc ads,GNAT String_Split g-strspl ads,The GNAT Library | |
04d6c745 | 24811 | @anchor{gnat_rm/the_gnat_library gnat-table-g-table-ads}@anchor{3c5}@anchor{gnat_rm/the_gnat_library id117}@anchor{3c6} |
64d5610f ML |
24812 | @section @code{GNAT.Table} (@code{g-table.ads}) |
24813 | ||
24814 | ||
24815 | @geindex GNAT.Table (g-table.ads) | |
24816 | ||
24817 | @geindex Table implementation | |
24818 | ||
24819 | @geindex Arrays | |
24820 | @geindex extendable | |
24821 | ||
24822 | A generic package providing a single dimension array abstraction where the | |
24823 | length of the array can be dynamically modified. | |
24824 | ||
24825 | This package provides a facility similar to that of @code{GNAT.Dynamic_Tables}, | |
24826 | except that this package declares a single instance of the table type, | |
24827 | while an instantiation of @code{GNAT.Dynamic_Tables} creates a type that can be | |
24828 | used to define dynamic instances of the table. | |
24829 | ||
24830 | @node GNAT Task_Lock g-tasloc ads,GNAT Time_Stamp g-timsta ads,GNAT Table g-table ads,The GNAT Library | |
04d6c745 | 24831 | @anchor{gnat_rm/the_gnat_library gnat-task-lock-g-tasloc-ads}@anchor{3c7}@anchor{gnat_rm/the_gnat_library id118}@anchor{3c8} |
64d5610f ML |
24832 | @section @code{GNAT.Task_Lock} (@code{g-tasloc.ads}) |
24833 | ||
24834 | ||
24835 | @geindex GNAT.Task_Lock (g-tasloc.ads) | |
24836 | ||
24837 | @geindex Task synchronization | |
24838 | ||
24839 | @geindex Task locking | |
24840 | ||
24841 | @geindex Locking | |
24842 | ||
24843 | A very simple facility for locking and unlocking sections of code using a | |
24844 | single global task lock. Appropriate for use in situations where contention | |
24845 | between tasks is very rarely expected. | |
24846 | ||
24847 | @node GNAT Time_Stamp g-timsta ads,GNAT Threads g-thread ads,GNAT Task_Lock g-tasloc ads,The GNAT Library | |
04d6c745 | 24848 | @anchor{gnat_rm/the_gnat_library gnat-time-stamp-g-timsta-ads}@anchor{3c9}@anchor{gnat_rm/the_gnat_library id119}@anchor{3ca} |
64d5610f ML |
24849 | @section @code{GNAT.Time_Stamp} (@code{g-timsta.ads}) |
24850 | ||
24851 | ||
24852 | @geindex GNAT.Time_Stamp (g-timsta.ads) | |
24853 | ||
24854 | @geindex Time stamp | |
24855 | ||
24856 | @geindex Current time | |
24857 | ||
24858 | Provides a simple function that returns a string YYYY-MM-DD HH:MM:SS.SS that | |
24859 | represents the current date and time in ISO 8601 format. This is a very simple | |
24860 | routine with minimal code and there are no dependencies on any other unit. | |
24861 | ||
24862 | @node GNAT Threads g-thread ads,GNAT Traceback g-traceb ads,GNAT Time_Stamp g-timsta ads,The GNAT Library | |
04d6c745 | 24863 | @anchor{gnat_rm/the_gnat_library gnat-threads-g-thread-ads}@anchor{3cb}@anchor{gnat_rm/the_gnat_library id120}@anchor{3cc} |
64d5610f ML |
24864 | @section @code{GNAT.Threads} (@code{g-thread.ads}) |
24865 | ||
24866 | ||
24867 | @geindex GNAT.Threads (g-thread.ads) | |
24868 | ||
24869 | @geindex Foreign threads | |
24870 | ||
24871 | @geindex Threads | |
24872 | @geindex foreign | |
24873 | ||
24874 | Provides facilities for dealing with foreign threads which need to be known | |
24875 | by the GNAT run-time system. Consult the documentation of this package for | |
24876 | further details if your program has threads that are created by a non-Ada | |
24877 | environment which then accesses Ada code. | |
24878 | ||
24879 | @node GNAT Traceback g-traceb ads,GNAT Traceback Symbolic g-trasym ads,GNAT Threads g-thread ads,The GNAT Library | |
04d6c745 | 24880 | @anchor{gnat_rm/the_gnat_library gnat-traceback-g-traceb-ads}@anchor{3cd}@anchor{gnat_rm/the_gnat_library id121}@anchor{3ce} |
64d5610f ML |
24881 | @section @code{GNAT.Traceback} (@code{g-traceb.ads}) |
24882 | ||
24883 | ||
24884 | @geindex GNAT.Traceback (g-traceb.ads) | |
24885 | ||
24886 | @geindex Trace back facilities | |
24887 | ||
24888 | Provides a facility for obtaining non-symbolic traceback information, useful | |
24889 | in various debugging situations. | |
24890 | ||
eeba836b | 24891 | @node GNAT Traceback Symbolic g-trasym ads,GNAT UTF_32 g-utf_32 ads,GNAT Traceback g-traceb ads,The GNAT Library |
04d6c745 | 24892 | @anchor{gnat_rm/the_gnat_library gnat-traceback-symbolic-g-trasym-ads}@anchor{3cf}@anchor{gnat_rm/the_gnat_library id122}@anchor{3d0} |
64d5610f ML |
24893 | @section @code{GNAT.Traceback.Symbolic} (@code{g-trasym.ads}) |
24894 | ||
24895 | ||
24896 | @geindex GNAT.Traceback.Symbolic (g-trasym.ads) | |
24897 | ||
24898 | @geindex Trace back facilities | |
24899 | ||
eeba836b | 24900 | @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 |
04d6c745 | 24901 | @anchor{gnat_rm/the_gnat_library gnat-utf-32-g-utf-32-ads}@anchor{3d1}@anchor{gnat_rm/the_gnat_library id123}@anchor{3d2} |
eeba836b | 24902 | @section @code{GNAT.UTF_32} (@code{g-utf_32.ads}) |
64d5610f ML |
24903 | |
24904 | ||
eeba836b | 24905 | @geindex GNAT.UTF_32 (g-utf_32.ads) |
64d5610f ML |
24906 | |
24907 | @geindex Wide character codes | |
24908 | ||
24909 | This is a package intended to be used in conjunction with the | |
24910 | @code{Wide_Character} type in Ada 95 and the | |
24911 | @code{Wide_Wide_Character} type in Ada 2005 (available | |
24912 | in @code{GNAT} in Ada 2005 mode). This package contains | |
24913 | Unicode categorization routines, as well as lexical | |
24914 | categorization routines corresponding to the Ada 2005 | |
24915 | lexical rules for identifiers and strings, and also a | |
24916 | lower case to upper case fold routine corresponding to | |
24917 | the Ada 2005 rules for identifier equivalence. | |
24918 | ||
eeba836b | 24919 | @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 |
04d6c745 | 24920 | @anchor{gnat_rm/the_gnat_library gnat-utf-32-spelling-checker-g-u3spch-ads}@anchor{3d3}@anchor{gnat_rm/the_gnat_library id124}@anchor{3d4} |
eeba836b | 24921 | @section @code{GNAT.UTF_32_Spelling_Checker} (@code{g-u3spch.ads}) |
64d5610f ML |
24922 | |
24923 | ||
eeba836b | 24924 | @geindex GNAT.UTF_32_Spelling_Checker (g-u3spch.ads) |
64d5610f ML |
24925 | |
24926 | @geindex Spell checking | |
24927 | ||
24928 | Provides a function for determining whether one wide wide string is a plausible | |
24929 | near misspelling of another wide wide string, where the strings are represented | |
24930 | using the UTF_32_String type defined in System.Wch_Cnv. | |
24931 | ||
eeba836b | 24932 | @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 |
04d6c745 | 24933 | @anchor{gnat_rm/the_gnat_library gnat-wide-spelling-checker-g-wispch-ads}@anchor{3d5}@anchor{gnat_rm/the_gnat_library id125}@anchor{3d6} |
64d5610f ML |
24934 | @section @code{GNAT.Wide_Spelling_Checker} (@code{g-wispch.ads}) |
24935 | ||
24936 | ||
24937 | @geindex GNAT.Wide_Spelling_Checker (g-wispch.ads) | |
24938 | ||
24939 | @geindex Spell checking | |
24940 | ||
24941 | Provides a function for determining whether one wide string is a plausible | |
24942 | near misspelling of another wide string. | |
24943 | ||
24944 | @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 | |
04d6c745 | 24945 | @anchor{gnat_rm/the_gnat_library gnat-wide-string-split-g-wistsp-ads}@anchor{3d7}@anchor{gnat_rm/the_gnat_library id126}@anchor{3d8} |
64d5610f ML |
24946 | @section @code{GNAT.Wide_String_Split} (@code{g-wistsp.ads}) |
24947 | ||
24948 | ||
24949 | @geindex GNAT.Wide_String_Split (g-wistsp.ads) | |
24950 | ||
24951 | @geindex Wide_String splitter | |
24952 | ||
24953 | Useful wide string manipulation routines: given a set of separators, split | |
24954 | a wide string wherever the separators appear, and provide direct access | |
24955 | to the resulting slices. This package is instantiated from | |
24956 | @code{GNAT.Array_Split}. | |
24957 | ||
24958 | @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 | |
04d6c745 | 24959 | @anchor{gnat_rm/the_gnat_library gnat-wide-wide-spelling-checker-g-zspche-ads}@anchor{3d9}@anchor{gnat_rm/the_gnat_library id127}@anchor{3da} |
64d5610f ML |
24960 | @section @code{GNAT.Wide_Wide_Spelling_Checker} (@code{g-zspche.ads}) |
24961 | ||
24962 | ||
24963 | @geindex GNAT.Wide_Wide_Spelling_Checker (g-zspche.ads) | |
24964 | ||
24965 | @geindex Spell checking | |
24966 | ||
24967 | Provides a function for determining whether one wide wide string is a plausible | |
24968 | near misspelling of another wide wide string. | |
24969 | ||
24970 | @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 | |
04d6c745 | 24971 | @anchor{gnat_rm/the_gnat_library gnat-wide-wide-string-split-g-zistsp-ads}@anchor{3db}@anchor{gnat_rm/the_gnat_library id128}@anchor{3dc} |
64d5610f ML |
24972 | @section @code{GNAT.Wide_Wide_String_Split} (@code{g-zistsp.ads}) |
24973 | ||
24974 | ||
24975 | @geindex GNAT.Wide_Wide_String_Split (g-zistsp.ads) | |
24976 | ||
24977 | @geindex Wide_Wide_String splitter | |
24978 | ||
24979 | Useful wide wide string manipulation routines: given a set of separators, split | |
24980 | a wide wide string wherever the separators appear, and provide direct access | |
24981 | to the resulting slices. This package is instantiated from | |
24982 | @code{GNAT.Array_Split}. | |
24983 | ||
24984 | @node Interfaces C Extensions i-cexten ads,Interfaces C Streams i-cstrea ads,GNAT Wide_Wide_String_Split g-zistsp ads,The GNAT Library | |
04d6c745 | 24985 | @anchor{gnat_rm/the_gnat_library id129}@anchor{3dd}@anchor{gnat_rm/the_gnat_library interfaces-c-extensions-i-cexten-ads}@anchor{3de} |
64d5610f ML |
24986 | @section @code{Interfaces.C.Extensions} (@code{i-cexten.ads}) |
24987 | ||
24988 | ||
24989 | @geindex Interfaces.C.Extensions (i-cexten.ads) | |
24990 | ||
24991 | This package contains additional C-related definitions, intended | |
24992 | for use with either manually or automatically generated bindings | |
24993 | to C libraries. | |
24994 | ||
24995 | @node Interfaces C Streams i-cstrea ads,Interfaces Packed_Decimal i-pacdec ads,Interfaces C Extensions i-cexten ads,The GNAT Library | |
04d6c745 | 24996 | @anchor{gnat_rm/the_gnat_library id130}@anchor{3df}@anchor{gnat_rm/the_gnat_library interfaces-c-streams-i-cstrea-ads}@anchor{3e0} |
64d5610f ML |
24997 | @section @code{Interfaces.C.Streams} (@code{i-cstrea.ads}) |
24998 | ||
24999 | ||
25000 | @geindex Interfaces.C.Streams (i-cstrea.ads) | |
25001 | ||
25002 | @geindex C streams | |
25003 | @geindex interfacing | |
25004 | ||
25005 | This package is a binding for the most commonly used operations | |
25006 | on C streams. | |
25007 | ||
25008 | @node Interfaces Packed_Decimal i-pacdec ads,Interfaces VxWorks i-vxwork ads,Interfaces C Streams i-cstrea ads,The GNAT Library | |
04d6c745 | 25009 | @anchor{gnat_rm/the_gnat_library id131}@anchor{3e1}@anchor{gnat_rm/the_gnat_library interfaces-packed-decimal-i-pacdec-ads}@anchor{3e2} |
64d5610f ML |
25010 | @section @code{Interfaces.Packed_Decimal} (@code{i-pacdec.ads}) |
25011 | ||
25012 | ||
25013 | @geindex Interfaces.Packed_Decimal (i-pacdec.ads) | |
25014 | ||
25015 | @geindex IBM Packed Format | |
25016 | ||
25017 | @geindex Packed Decimal | |
25018 | ||
25019 | This package provides a set of routines for conversions to and | |
25020 | from a packed decimal format compatible with that used on IBM | |
25021 | mainframes. | |
25022 | ||
25023 | @node Interfaces VxWorks i-vxwork ads,Interfaces VxWorks Int_Connection i-vxinco ads,Interfaces Packed_Decimal i-pacdec ads,The GNAT Library | |
04d6c745 | 25024 | @anchor{gnat_rm/the_gnat_library id132}@anchor{3e3}@anchor{gnat_rm/the_gnat_library interfaces-vxworks-i-vxwork-ads}@anchor{3e4} |
64d5610f ML |
25025 | @section @code{Interfaces.VxWorks} (@code{i-vxwork.ads}) |
25026 | ||
25027 | ||
25028 | @geindex Interfaces.VxWorks (i-vxwork.ads) | |
25029 | ||
25030 | @geindex Interfacing to VxWorks | |
25031 | ||
25032 | @geindex VxWorks | |
25033 | @geindex interfacing | |
25034 | ||
25035 | This package provides a limited binding to the VxWorks API. | |
25036 | In particular, it interfaces with the | |
25037 | VxWorks hardware interrupt facilities. | |
25038 | ||
25039 | @node Interfaces VxWorks Int_Connection i-vxinco ads,Interfaces VxWorks IO i-vxwoio ads,Interfaces VxWorks i-vxwork ads,The GNAT Library | |
04d6c745 | 25040 | @anchor{gnat_rm/the_gnat_library id133}@anchor{3e5}@anchor{gnat_rm/the_gnat_library interfaces-vxworks-int-connection-i-vxinco-ads}@anchor{3e6} |
64d5610f ML |
25041 | @section @code{Interfaces.VxWorks.Int_Connection} (@code{i-vxinco.ads}) |
25042 | ||
25043 | ||
25044 | @geindex Interfaces.VxWorks.Int_Connection (i-vxinco.ads) | |
25045 | ||
25046 | @geindex Interfacing to VxWorks | |
25047 | ||
25048 | @geindex VxWorks | |
25049 | @geindex interfacing | |
25050 | ||
25051 | This package provides a way for users to replace the use of | |
25052 | intConnect() with a custom routine for installing interrupt | |
25053 | handlers. | |
25054 | ||
25055 | @node Interfaces VxWorks IO i-vxwoio ads,System Address_Image s-addima ads,Interfaces VxWorks Int_Connection i-vxinco ads,The GNAT Library | |
04d6c745 | 25056 | @anchor{gnat_rm/the_gnat_library id134}@anchor{3e7}@anchor{gnat_rm/the_gnat_library interfaces-vxworks-io-i-vxwoio-ads}@anchor{3e8} |
64d5610f ML |
25057 | @section @code{Interfaces.VxWorks.IO} (@code{i-vxwoio.ads}) |
25058 | ||
25059 | ||
25060 | @geindex Interfaces.VxWorks.IO (i-vxwoio.ads) | |
25061 | ||
25062 | @geindex Interfacing to VxWorks' I/O | |
25063 | ||
25064 | @geindex VxWorks | |
25065 | @geindex I/O interfacing | |
25066 | ||
25067 | @geindex VxWorks | |
25068 | @geindex Get_Immediate | |
25069 | ||
25070 | @geindex Get_Immediate | |
25071 | @geindex VxWorks | |
25072 | ||
25073 | This package provides a binding to the ioctl (IO/Control) | |
25074 | function of VxWorks, defining a set of option values and | |
25075 | function codes. A particular use of this package is | |
25076 | to enable the use of Get_Immediate under VxWorks. | |
25077 | ||
25078 | @node System Address_Image s-addima ads,System Assertions s-assert ads,Interfaces VxWorks IO i-vxwoio ads,The GNAT Library | |
04d6c745 | 25079 | @anchor{gnat_rm/the_gnat_library id135}@anchor{3e9}@anchor{gnat_rm/the_gnat_library system-address-image-s-addima-ads}@anchor{3ea} |
64d5610f ML |
25080 | @section @code{System.Address_Image} (@code{s-addima.ads}) |
25081 | ||
25082 | ||
25083 | @geindex System.Address_Image (s-addima.ads) | |
25084 | ||
25085 | @geindex Address image | |
25086 | ||
25087 | @geindex Image | |
25088 | @geindex of an address | |
25089 | ||
25090 | This function provides a useful debugging | |
25091 | function that gives an (implementation dependent) | |
25092 | string which identifies an address. | |
25093 | ||
25094 | @node System Assertions s-assert ads,System Atomic_Counters s-atocou ads,System Address_Image s-addima ads,The GNAT Library | |
04d6c745 | 25095 | @anchor{gnat_rm/the_gnat_library id136}@anchor{3eb}@anchor{gnat_rm/the_gnat_library system-assertions-s-assert-ads}@anchor{3ec} |
64d5610f ML |
25096 | @section @code{System.Assertions} (@code{s-assert.ads}) |
25097 | ||
25098 | ||
25099 | @geindex System.Assertions (s-assert.ads) | |
25100 | ||
25101 | @geindex Assertions | |
25102 | ||
25103 | @geindex Assert_Failure | |
25104 | @geindex exception | |
25105 | ||
25106 | This package provides the declaration of the exception raised | |
25107 | by an run-time assertion failure, as well as the routine that | |
25108 | is used internally to raise this assertion. | |
25109 | ||
25110 | @node System Atomic_Counters s-atocou ads,System Memory s-memory ads,System Assertions s-assert ads,The GNAT Library | |
04d6c745 | 25111 | @anchor{gnat_rm/the_gnat_library id137}@anchor{3ed}@anchor{gnat_rm/the_gnat_library system-atomic-counters-s-atocou-ads}@anchor{3ee} |
64d5610f ML |
25112 | @section @code{System.Atomic_Counters} (@code{s-atocou.ads}) |
25113 | ||
25114 | ||
25115 | @geindex System.Atomic_Counters (s-atocou.ads) | |
25116 | ||
25117 | This package provides the declaration of an atomic counter type, | |
25118 | together with efficient routines (using hardware | |
25119 | synchronization primitives) for incrementing, decrementing, | |
25120 | and testing of these counters. This package is implemented | |
25121 | on most targets, including all Alpha, AARCH64, ARM, ia64, PowerPC, SPARC V9, | |
25122 | x86, and x86_64 platforms. | |
25123 | ||
25124 | @node System Memory s-memory ads,System Multiprocessors s-multip ads,System Atomic_Counters s-atocou ads,The GNAT Library | |
04d6c745 | 25125 | @anchor{gnat_rm/the_gnat_library id138}@anchor{3ef}@anchor{gnat_rm/the_gnat_library system-memory-s-memory-ads}@anchor{3f0} |
64d5610f ML |
25126 | @section @code{System.Memory} (@code{s-memory.ads}) |
25127 | ||
25128 | ||
25129 | @geindex System.Memory (s-memory.ads) | |
25130 | ||
25131 | @geindex Memory allocation | |
25132 | ||
25133 | This package provides the interface to the low level routines used | |
25134 | by the generated code for allocation and freeing storage for the | |
25135 | default storage pool (analogous to the C routines malloc and free). | |
25136 | It also provides a reallocation interface analogous to the C routine | |
25137 | realloc. The body of this unit may be modified to provide alternative | |
25138 | allocation mechanisms for the default pool, and in addition, direct | |
25139 | calls to this unit may be made for low level allocation uses (for | |
25140 | example see the body of @code{GNAT.Tables}). | |
25141 | ||
25142 | @node System Multiprocessors s-multip ads,System Multiprocessors Dispatching_Domains s-mudido ads,System Memory s-memory ads,The GNAT Library | |
04d6c745 | 25143 | @anchor{gnat_rm/the_gnat_library id139}@anchor{3f1}@anchor{gnat_rm/the_gnat_library system-multiprocessors-s-multip-ads}@anchor{3f2} |
64d5610f ML |
25144 | @section @code{System.Multiprocessors} (@code{s-multip.ads}) |
25145 | ||
25146 | ||
25147 | @geindex System.Multiprocessors (s-multip.ads) | |
25148 | ||
25149 | @geindex Multiprocessor interface | |
25150 | ||
25151 | This is an Ada 2012 unit defined in the Ada 2012 Reference Manual, but | |
25152 | in GNAT we also make it available in Ada 95 and Ada 2005 (where it is | |
25153 | technically an implementation-defined addition). | |
25154 | ||
25155 | @node System Multiprocessors Dispatching_Domains s-mudido ads,System Partition_Interface s-parint ads,System Multiprocessors s-multip ads,The GNAT Library | |
04d6c745 | 25156 | @anchor{gnat_rm/the_gnat_library id140}@anchor{3f3}@anchor{gnat_rm/the_gnat_library system-multiprocessors-dispatching-domains-s-mudido-ads}@anchor{3f4} |
64d5610f ML |
25157 | @section @code{System.Multiprocessors.Dispatching_Domains} (@code{s-mudido.ads}) |
25158 | ||
25159 | ||
25160 | @geindex System.Multiprocessors.Dispatching_Domains (s-mudido.ads) | |
25161 | ||
25162 | @geindex Multiprocessor interface | |
25163 | ||
25164 | This is an Ada 2012 unit defined in the Ada 2012 Reference Manual, but | |
25165 | in GNAT we also make it available in Ada 95 and Ada 2005 (where it is | |
25166 | technically an implementation-defined addition). | |
25167 | ||
25168 | @node System Partition_Interface s-parint ads,System Pool_Global s-pooglo ads,System Multiprocessors Dispatching_Domains s-mudido ads,The GNAT Library | |
04d6c745 | 25169 | @anchor{gnat_rm/the_gnat_library id141}@anchor{3f5}@anchor{gnat_rm/the_gnat_library system-partition-interface-s-parint-ads}@anchor{3f6} |
64d5610f ML |
25170 | @section @code{System.Partition_Interface} (@code{s-parint.ads}) |
25171 | ||
25172 | ||
25173 | @geindex System.Partition_Interface (s-parint.ads) | |
25174 | ||
25175 | @geindex Partition interfacing functions | |
25176 | ||
25177 | This package provides facilities for partition interfacing. It | |
25178 | is used primarily in a distribution context when using Annex E | |
25179 | with @code{GLADE}. | |
25180 | ||
25181 | @node System Pool_Global s-pooglo ads,System Pool_Local s-pooloc ads,System Partition_Interface s-parint ads,The GNAT Library | |
04d6c745 | 25182 | @anchor{gnat_rm/the_gnat_library id142}@anchor{3f7}@anchor{gnat_rm/the_gnat_library system-pool-global-s-pooglo-ads}@anchor{3f8} |
64d5610f ML |
25183 | @section @code{System.Pool_Global} (@code{s-pooglo.ads}) |
25184 | ||
25185 | ||
25186 | @geindex System.Pool_Global (s-pooglo.ads) | |
25187 | ||
25188 | @geindex Storage pool | |
25189 | @geindex global | |
25190 | ||
25191 | @geindex Global storage pool | |
25192 | ||
25193 | This package provides a storage pool that is equivalent to the default | |
25194 | storage pool used for access types for which no pool is specifically | |
25195 | declared. It uses malloc/free to allocate/free and does not attempt to | |
25196 | do any automatic reclamation. | |
25197 | ||
25198 | @node System Pool_Local s-pooloc ads,System Restrictions s-restri ads,System Pool_Global s-pooglo ads,The GNAT Library | |
04d6c745 | 25199 | @anchor{gnat_rm/the_gnat_library id143}@anchor{3f9}@anchor{gnat_rm/the_gnat_library system-pool-local-s-pooloc-ads}@anchor{3fa} |
64d5610f ML |
25200 | @section @code{System.Pool_Local} (@code{s-pooloc.ads}) |
25201 | ||
25202 | ||
25203 | @geindex System.Pool_Local (s-pooloc.ads) | |
25204 | ||
25205 | @geindex Storage pool | |
25206 | @geindex local | |
25207 | ||
25208 | @geindex Local storage pool | |
25209 | ||
25210 | This package provides a storage pool that is intended for use with locally | |
25211 | defined access types. It uses malloc/free for allocate/free, and maintains | |
25212 | a list of allocated blocks, so that all storage allocated for the pool can | |
25213 | be freed automatically when the pool is finalized. | |
25214 | ||
25215 | @node System Restrictions s-restri ads,System Rident s-rident ads,System Pool_Local s-pooloc ads,The GNAT Library | |
04d6c745 | 25216 | @anchor{gnat_rm/the_gnat_library id144}@anchor{3fb}@anchor{gnat_rm/the_gnat_library system-restrictions-s-restri-ads}@anchor{3fc} |
64d5610f ML |
25217 | @section @code{System.Restrictions} (@code{s-restri.ads}) |
25218 | ||
25219 | ||
25220 | @geindex System.Restrictions (s-restri.ads) | |
25221 | ||
25222 | @geindex Run-time restrictions access | |
25223 | ||
25224 | This package provides facilities for accessing at run time | |
25225 | the status of restrictions specified at compile time for | |
25226 | the partition. Information is available both with regard | |
25227 | to actual restrictions specified, and with regard to | |
25228 | compiler determined information on which restrictions | |
25229 | are violated by one or more packages in the partition. | |
25230 | ||
25231 | @node System Rident s-rident ads,System Strings Stream_Ops s-ststop ads,System Restrictions s-restri ads,The GNAT Library | |
04d6c745 | 25232 | @anchor{gnat_rm/the_gnat_library id145}@anchor{3fd}@anchor{gnat_rm/the_gnat_library system-rident-s-rident-ads}@anchor{3fe} |
64d5610f ML |
25233 | @section @code{System.Rident} (@code{s-rident.ads}) |
25234 | ||
25235 | ||
25236 | @geindex System.Rident (s-rident.ads) | |
25237 | ||
25238 | @geindex Restrictions definitions | |
25239 | ||
25240 | This package provides definitions of the restrictions | |
25241 | identifiers supported by GNAT, and also the format of | |
25242 | the restrictions provided in package System.Restrictions. | |
25243 | It is not normally necessary to @code{with} this generic package | |
25244 | since the necessary instantiation is included in | |
25245 | package System.Restrictions. | |
25246 | ||
25247 | @node System Strings Stream_Ops s-ststop ads,System Unsigned_Types s-unstyp ads,System Rident s-rident ads,The GNAT Library | |
04d6c745 | 25248 | @anchor{gnat_rm/the_gnat_library id146}@anchor{3ff}@anchor{gnat_rm/the_gnat_library system-strings-stream-ops-s-ststop-ads}@anchor{400} |
64d5610f ML |
25249 | @section @code{System.Strings.Stream_Ops} (@code{s-ststop.ads}) |
25250 | ||
25251 | ||
25252 | @geindex System.Strings.Stream_Ops (s-ststop.ads) | |
25253 | ||
25254 | @geindex Stream operations | |
25255 | ||
25256 | @geindex String stream operations | |
25257 | ||
25258 | This package provides a set of stream subprograms for standard string types. | |
25259 | It is intended primarily to support implicit use of such subprograms when | |
25260 | stream attributes are applied to string types, but the subprograms in this | |
25261 | package can be used directly by application programs. | |
25262 | ||
25263 | @node System Unsigned_Types s-unstyp ads,System Wch_Cnv s-wchcnv ads,System Strings Stream_Ops s-ststop ads,The GNAT Library | |
04d6c745 | 25264 | @anchor{gnat_rm/the_gnat_library id147}@anchor{401}@anchor{gnat_rm/the_gnat_library system-unsigned-types-s-unstyp-ads}@anchor{402} |
64d5610f ML |
25265 | @section @code{System.Unsigned_Types} (@code{s-unstyp.ads}) |
25266 | ||
25267 | ||
25268 | @geindex System.Unsigned_Types (s-unstyp.ads) | |
25269 | ||
25270 | This package contains definitions of standard unsigned types that | |
25271 | correspond in size to the standard signed types declared in Standard, | |
25272 | and (unlike the types in Interfaces) have corresponding names. It | |
25273 | also contains some related definitions for other specialized types | |
25274 | used by the compiler in connection with packed array types. | |
25275 | ||
25276 | @node System Wch_Cnv s-wchcnv ads,System Wch_Con s-wchcon ads,System Unsigned_Types s-unstyp ads,The GNAT Library | |
04d6c745 | 25277 | @anchor{gnat_rm/the_gnat_library id148}@anchor{403}@anchor{gnat_rm/the_gnat_library system-wch-cnv-s-wchcnv-ads}@anchor{404} |
64d5610f ML |
25278 | @section @code{System.Wch_Cnv} (@code{s-wchcnv.ads}) |
25279 | ||
25280 | ||
25281 | @geindex System.Wch_Cnv (s-wchcnv.ads) | |
25282 | ||
25283 | @geindex Wide Character | |
25284 | @geindex Representation | |
25285 | ||
25286 | @geindex Wide String | |
25287 | @geindex Conversion | |
25288 | ||
25289 | @geindex Representation of wide characters | |
25290 | ||
25291 | This package provides routines for converting between | |
25292 | wide and wide wide characters and a representation as a value of type | |
25293 | @code{Standard.String}, using a specified wide character | |
25294 | encoding method. It uses definitions in | |
25295 | package @code{System.Wch_Con}. | |
25296 | ||
25297 | @node System Wch_Con s-wchcon ads,,System Wch_Cnv s-wchcnv ads,The GNAT Library | |
04d6c745 | 25298 | @anchor{gnat_rm/the_gnat_library id149}@anchor{405}@anchor{gnat_rm/the_gnat_library system-wch-con-s-wchcon-ads}@anchor{406} |
64d5610f ML |
25299 | @section @code{System.Wch_Con} (@code{s-wchcon.ads}) |
25300 | ||
25301 | ||
25302 | @geindex System.Wch_Con (s-wchcon.ads) | |
25303 | ||
25304 | This package provides definitions and descriptions of | |
25305 | the various methods used for encoding wide characters | |
25306 | in ordinary strings. These definitions are used by | |
25307 | the package @code{System.Wch_Cnv}. | |
25308 | ||
25309 | @node Interfacing to Other Languages,Specialized Needs Annexes,The GNAT Library,Top | |
04d6c745 | 25310 | @anchor{gnat_rm/interfacing_to_other_languages doc}@anchor{407}@anchor{gnat_rm/interfacing_to_other_languages id1}@anchor{408}@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-other-languages}@anchor{11} |
64d5610f ML |
25311 | @chapter Interfacing to Other Languages |
25312 | ||
25313 | ||
25314 | The facilities in Annex B of the Ada Reference Manual are fully | |
25315 | implemented in GNAT, and in addition, a full interface to C++ is | |
25316 | provided. | |
25317 | ||
25318 | @menu | |
25319 | * Interfacing to C:: | |
25320 | * Interfacing to C++:: | |
25321 | * Interfacing to COBOL:: | |
25322 | * Interfacing to Fortran:: | |
25323 | * Interfacing to non-GNAT Ada code:: | |
25324 | ||
25325 | @end menu | |
25326 | ||
25327 | @node Interfacing to C,Interfacing to C++,,Interfacing to Other Languages | |
04d6c745 | 25328 | @anchor{gnat_rm/interfacing_to_other_languages id2}@anchor{409}@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-c}@anchor{40a} |
64d5610f ML |
25329 | @section Interfacing to C |
25330 | ||
25331 | ||
25332 | Interfacing to C with GNAT can use one of two approaches: | |
25333 | ||
25334 | ||
25335 | @itemize * | |
25336 | ||
25337 | @item | |
25338 | The types in the package @code{Interfaces.C} may be used. | |
25339 | ||
25340 | @item | |
25341 | Standard Ada types may be used directly. This may be less portable to | |
25342 | other compilers, but will work on all GNAT compilers, which guarantee | |
25343 | correspondence between the C and Ada types. | |
25344 | @end itemize | |
25345 | ||
25346 | Pragma @code{Convention C} may be applied to Ada types, but mostly has no | |
25347 | effect, since this is the default. The following table shows the | |
25348 | correspondence between Ada scalar types and the corresponding C types. | |
25349 | ||
25350 | ||
25351 | @multitable {xxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} | |
25352 | @headitem | |
25353 | ||
25354 | Ada Type | |
25355 | ||
25356 | @tab | |
25357 | ||
25358 | C Type | |
25359 | ||
25360 | @item | |
25361 | ||
25362 | @code{Integer} | |
25363 | ||
25364 | @tab | |
25365 | ||
25366 | @code{int} | |
25367 | ||
25368 | @item | |
25369 | ||
25370 | @code{Short_Integer} | |
25371 | ||
25372 | @tab | |
25373 | ||
25374 | @code{short} | |
25375 | ||
25376 | @item | |
25377 | ||
25378 | @code{Short_Short_Integer} | |
25379 | ||
25380 | @tab | |
25381 | ||
25382 | @code{signed char} | |
25383 | ||
25384 | @item | |
25385 | ||
25386 | @code{Long_Integer} | |
25387 | ||
25388 | @tab | |
25389 | ||
25390 | @code{long} | |
25391 | ||
25392 | @item | |
25393 | ||
25394 | @code{Long_Long_Integer} | |
25395 | ||
25396 | @tab | |
25397 | ||
25398 | @code{long long} | |
25399 | ||
25400 | @item | |
25401 | ||
25402 | @code{Short_Float} | |
25403 | ||
25404 | @tab | |
25405 | ||
25406 | @code{float} | |
25407 | ||
25408 | @item | |
25409 | ||
25410 | @code{Float} | |
25411 | ||
25412 | @tab | |
25413 | ||
25414 | @code{float} | |
25415 | ||
25416 | @item | |
25417 | ||
25418 | @code{Long_Float} | |
25419 | ||
25420 | @tab | |
25421 | ||
25422 | @code{double} | |
25423 | ||
25424 | @item | |
25425 | ||
25426 | @code{Long_Long_Float} | |
25427 | ||
25428 | @tab | |
25429 | ||
25430 | This is the longest floating-point type supported by the hardware. | |
25431 | ||
25432 | @end multitable | |
25433 | ||
25434 | ||
25435 | Additionally, there are the following general correspondences between Ada | |
25436 | and C types: | |
25437 | ||
25438 | ||
25439 | @itemize * | |
25440 | ||
25441 | @item | |
25442 | Ada enumeration types map to C enumeration types directly if pragma | |
25443 | @code{Convention C} is specified, which causes them to have a length of | |
25444 | 32 bits, except for boolean types which map to C99 @code{bool} and for | |
25445 | which the length is 8 bits. | |
25446 | Without pragma @code{Convention C}, Ada enumeration types map to | |
25447 | 8, 16, or 32 bits (i.e., C types @code{signed char}, @code{short}, | |
25448 | @code{int}, respectively) depending on the number of values passed. | |
25449 | This is the only case in which pragma @code{Convention C} affects the | |
25450 | representation of an Ada type. | |
25451 | ||
25452 | @item | |
25453 | Ada access types map to C pointers, except for the case of pointers to | |
25454 | unconstrained types in Ada, which have no direct C equivalent. | |
25455 | ||
25456 | @item | |
25457 | Ada arrays map directly to C arrays. | |
25458 | ||
25459 | @item | |
25460 | Ada records map directly to C structures. | |
25461 | ||
25462 | @item | |
25463 | Packed Ada records map to C structures where all members are bit fields | |
25464 | of the length corresponding to the @code{type'Size} value in Ada. | |
25465 | @end itemize | |
25466 | ||
25467 | @node Interfacing to C++,Interfacing to COBOL,Interfacing to C,Interfacing to Other Languages | |
04d6c745 | 25468 | @anchor{gnat_rm/interfacing_to_other_languages id3}@anchor{47}@anchor{gnat_rm/interfacing_to_other_languages id4}@anchor{40b} |
64d5610f ML |
25469 | @section Interfacing to C++ |
25470 | ||
25471 | ||
25472 | The interface to C++ makes use of the following pragmas, which are | |
25473 | primarily intended to be constructed automatically using a binding generator | |
25474 | tool, although it is possible to construct them by hand. | |
25475 | ||
25476 | Using these pragmas it is possible to achieve complete | |
25477 | inter-operability between Ada tagged types and C++ class definitions. | |
25478 | See @ref{7,,Implementation Defined Pragmas}, for more details. | |
25479 | ||
25480 | ||
25481 | @table @asis | |
25482 | ||
25483 | @item @code{pragma CPP_Class ([Entity =>] @var{LOCAL_NAME})} | |
25484 | ||
25485 | The argument denotes an entity in the current declarative region that is | |
25486 | declared as a tagged or untagged record type. It indicates that the type | |
25487 | corresponds to an externally declared C++ class type, and is to be laid | |
25488 | out the same way that C++ would lay out the type. | |
25489 | ||
25490 | Note: Pragma @code{CPP_Class} is currently obsolete. It is supported | |
25491 | for backward compatibility but its functionality is available | |
25492 | using pragma @code{Import} with @code{Convention} = @code{CPP}. | |
25493 | ||
25494 | @item @code{pragma CPP_Constructor ([Entity =>] @var{LOCAL_NAME})} | |
25495 | ||
25496 | This pragma identifies an imported function (imported in the usual way | |
25497 | with pragma @code{Import}) as corresponding to a C++ constructor. | |
25498 | @end table | |
25499 | ||
25500 | A few restrictions are placed on the use of the @code{Access} attribute | |
25501 | in conjunction with subprograms subject to convention @code{CPP}: the | |
25502 | attribute may be used neither on primitive operations of a tagged | |
25503 | record type with convention @code{CPP}, imported or not, nor on | |
25504 | subprograms imported with pragma @code{CPP_Constructor}. | |
25505 | ||
25506 | In addition, C++ exceptions are propagated and can be handled in an | |
25507 | @code{others} choice of an exception handler. The corresponding Ada | |
25508 | occurrence has no message, and the simple name of the exception identity | |
25509 | contains @code{Foreign_Exception}. Finalization and awaiting dependent | |
25510 | tasks works properly when such foreign exceptions are propagated. | |
25511 | ||
25512 | It is also possible to import a C++ exception using the following syntax: | |
25513 | ||
25514 | @example | |
25515 | LOCAL_NAME : exception; | |
25516 | pragma Import (Cpp, | |
25517 | [Entity =>] LOCAL_NAME, | |
25518 | [External_Name =>] static_string_EXPRESSION); | |
25519 | @end example | |
25520 | ||
25521 | The @code{External_Name} is the name of the C++ RTTI symbol. You can then | |
25522 | cover a specific C++ exception in an exception handler. | |
25523 | ||
25524 | @node Interfacing to COBOL,Interfacing to Fortran,Interfacing to C++,Interfacing to Other Languages | |
04d6c745 | 25525 | @anchor{gnat_rm/interfacing_to_other_languages id5}@anchor{40c}@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-cobol}@anchor{40d} |
64d5610f ML |
25526 | @section Interfacing to COBOL |
25527 | ||
25528 | ||
25529 | Interfacing to COBOL is achieved as described in section B.4 of | |
25530 | the Ada Reference Manual. | |
25531 | ||
25532 | @node Interfacing to Fortran,Interfacing to non-GNAT Ada code,Interfacing to COBOL,Interfacing to Other Languages | |
04d6c745 | 25533 | @anchor{gnat_rm/interfacing_to_other_languages id6}@anchor{40e}@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-fortran}@anchor{40f} |
64d5610f ML |
25534 | @section Interfacing to Fortran |
25535 | ||
25536 | ||
25537 | Interfacing to Fortran is achieved as described in section B.5 of the | |
25538 | Ada Reference Manual. The pragma @code{Convention Fortran}, applied to a | |
25539 | multi-dimensional array causes the array to be stored in column-major | |
25540 | order as required for convenient interface to Fortran. | |
25541 | ||
25542 | @node Interfacing to non-GNAT Ada code,,Interfacing to Fortran,Interfacing to Other Languages | |
04d6c745 | 25543 | @anchor{gnat_rm/interfacing_to_other_languages id7}@anchor{410}@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-non-gnat-ada-code}@anchor{411} |
64d5610f ML |
25544 | @section Interfacing to non-GNAT Ada code |
25545 | ||
25546 | ||
25547 | It is possible to specify the convention @code{Ada} in a pragma | |
25548 | @code{Import} or pragma @code{Export}. However this refers to | |
25549 | the calling conventions used by GNAT, which may or may not be | |
25550 | similar enough to those used by some other Ada 83 / Ada 95 / Ada 2005 | |
25551 | compiler to allow interoperation. | |
25552 | ||
25553 | If arguments types are kept simple, and if the foreign compiler generally | |
25554 | follows system calling conventions, then it may be possible to integrate | |
25555 | files compiled by other Ada compilers, provided that the elaboration | |
25556 | issues are adequately addressed (for example by eliminating the | |
25557 | need for any load time elaboration). | |
25558 | ||
25559 | In particular, GNAT running on VMS is designed to | |
25560 | be highly compatible with the DEC Ada 83 compiler, so this is one | |
25561 | case in which it is possible to import foreign units of this type, | |
25562 | provided that the data items passed are restricted to simple scalar | |
25563 | values or simple record types without variants, or simple array | |
25564 | types with fixed bounds. | |
25565 | ||
25566 | @node Specialized Needs Annexes,Implementation of Specific Ada Features,Interfacing to Other Languages,Top | |
04d6c745 | 25567 | @anchor{gnat_rm/specialized_needs_annexes doc}@anchor{412}@anchor{gnat_rm/specialized_needs_annexes id1}@anchor{413}@anchor{gnat_rm/specialized_needs_annexes specialized-needs-annexes}@anchor{12} |
64d5610f ML |
25568 | @chapter Specialized Needs Annexes |
25569 | ||
25570 | ||
25571 | Ada 95, Ada 2005, and Ada 2012 define a number of Specialized Needs Annexes, which are not | |
25572 | required in all implementations. However, as described in this chapter, | |
25573 | GNAT implements all of these annexes: | |
25574 | ||
25575 | ||
25576 | @table @asis | |
25577 | ||
25578 | @item `Systems Programming (Annex C)' | |
25579 | ||
25580 | The Systems Programming Annex is fully implemented. | |
25581 | ||
25582 | @item `Real-Time Systems (Annex D)' | |
25583 | ||
25584 | The Real-Time Systems Annex is fully implemented. | |
25585 | ||
25586 | @item `Distributed Systems (Annex E)' | |
25587 | ||
25588 | Stub generation is fully implemented in the GNAT compiler. In addition, | |
25589 | a complete compatible PCS is available as part of the GLADE system, | |
25590 | a separate product. When the two | |
25591 | products are used in conjunction, this annex is fully implemented. | |
25592 | ||
25593 | @item `Information Systems (Annex F)' | |
25594 | ||
25595 | The Information Systems annex is fully implemented. | |
25596 | ||
25597 | @item `Numerics (Annex G)' | |
25598 | ||
25599 | The Numerics Annex is fully implemented. | |
25600 | ||
25601 | @item `Safety and Security / High-Integrity Systems (Annex H)' | |
25602 | ||
25603 | The Safety and Security Annex (termed the High-Integrity Systems Annex | |
25604 | in Ada 2005) is fully implemented. | |
25605 | @end table | |
25606 | ||
25607 | @node Implementation of Specific Ada Features,Implementation of Ada 2012 Features,Specialized Needs Annexes,Top | |
04d6c745 | 25608 | @anchor{gnat_rm/implementation_of_specific_ada_features doc}@anchor{414}@anchor{gnat_rm/implementation_of_specific_ada_features id1}@anchor{415}@anchor{gnat_rm/implementation_of_specific_ada_features implementation-of-specific-ada-features}@anchor{13} |
64d5610f ML |
25609 | @chapter Implementation of Specific Ada Features |
25610 | ||
25611 | ||
25612 | This chapter describes the GNAT implementation of several Ada language | |
25613 | facilities. | |
25614 | ||
25615 | @menu | |
25616 | * Machine Code Insertions:: | |
25617 | * GNAT Implementation of Tasking:: | |
25618 | * GNAT Implementation of Shared Passive Packages:: | |
25619 | * Code Generation for Array Aggregates:: | |
25620 | * The Size of Discriminated Records with Default Discriminants:: | |
25621 | * Image Values For Nonscalar Types:: | |
25622 | * Strict Conformance to the Ada Reference Manual:: | |
25623 | ||
25624 | @end menu | |
25625 | ||
25626 | @node Machine Code Insertions,GNAT Implementation of Tasking,,Implementation of Specific Ada Features | |
04d6c745 | 25627 | @anchor{gnat_rm/implementation_of_specific_ada_features id2}@anchor{416}@anchor{gnat_rm/implementation_of_specific_ada_features machine-code-insertions}@anchor{16d} |
64d5610f ML |
25628 | @section Machine Code Insertions |
25629 | ||
25630 | ||
25631 | @geindex Machine Code insertions | |
25632 | ||
25633 | Package @code{Machine_Code} provides machine code support as described | |
25634 | in the Ada Reference Manual in two separate forms: | |
25635 | ||
25636 | ||
25637 | @itemize * | |
25638 | ||
25639 | @item | |
25640 | Machine code statements, consisting of qualified expressions that | |
25641 | fit the requirements of RM section 13.8. | |
25642 | ||
25643 | @item | |
25644 | An intrinsic callable procedure, providing an alternative mechanism of | |
25645 | including machine instructions in a subprogram. | |
25646 | @end itemize | |
25647 | ||
25648 | The two features are similar, and both are closely related to the mechanism | |
25649 | provided by the asm instruction in the GNU C compiler. Full understanding | |
25650 | and use of the facilities in this package requires understanding the asm | |
25651 | instruction, see the section on Extended Asm in | |
25652 | @cite{Using_the_GNU_Compiler_Collection_(GCC)}. | |
25653 | ||
25654 | Calls to the function @code{Asm} and the procedure @code{Asm} have identical | |
25655 | semantic restrictions and effects as described below. Both are provided so | |
25656 | that the procedure call can be used as a statement, and the function call | |
25657 | can be used to form a code_statement. | |
25658 | ||
25659 | Consider this C @code{asm} instruction: | |
25660 | ||
25661 | @example | |
25662 | asm ("fsinx %1 %0" : "=f" (result) : "f" (angle)); | |
25663 | @end example | |
25664 | ||
25665 | The equivalent can be written for GNAT as: | |
25666 | ||
25667 | @example | |
25668 | Asm ("fsinx %1 %0", | |
25669 | My_Float'Asm_Output ("=f", result), | |
25670 | My_Float'Asm_Input ("f", angle)); | |
25671 | @end example | |
25672 | ||
25673 | The first argument to @code{Asm} is the assembler template, and is | |
25674 | identical to what is used in GNU C. This string must be a static | |
25675 | expression. The second argument is the output operand list. It is | |
25676 | either a single @code{Asm_Output} attribute reference, or a list of such | |
25677 | references enclosed in parentheses (technically an array aggregate of | |
25678 | such references). | |
25679 | ||
25680 | The @code{Asm_Output} attribute denotes a function that takes two | |
25681 | parameters. The first is a string, the second is the name of a variable | |
25682 | of the type designated by the attribute prefix. The first (string) | |
25683 | argument is required to be a static expression and designates the | |
25684 | constraint (see the section on Constraints in | |
25685 | @cite{Using_the_GNU_Compiler_Collection_(GCC)}) | |
25686 | for the parameter; e.g., what kind of register is required. The second | |
25687 | argument is the variable to be written or updated with the | |
25688 | result. The possible values for constraint are the same as those used in | |
25689 | the RTL, and are dependent on the configuration file used to build the | |
25690 | GCC back end. If there are no output operands, then this argument may | |
25691 | either be omitted, or explicitly given as @code{No_Output_Operands}. | |
25692 | No support is provided for GNU C’s symbolic names for output parameters. | |
25693 | ||
25694 | The second argument of @code{my_float'Asm_Output} functions as | |
25695 | though it were an @code{out} parameter, which is a little curious, but | |
25696 | all names have the form of expressions, so there is no syntactic | |
25697 | irregularity, even though normally functions would not be permitted | |
25698 | @code{out} parameters. The third argument is the list of input | |
25699 | operands. It is either a single @code{Asm_Input} attribute reference, or | |
25700 | a list of such references enclosed in parentheses (technically an array | |
25701 | aggregate of such references). | |
25702 | ||
25703 | The @code{Asm_Input} attribute denotes a function that takes two | |
25704 | parameters. The first is a string, the second is an expression of the | |
25705 | type designated by the prefix. The first (string) argument is required | |
25706 | to be a static expression, and is the constraint for the parameter, | |
25707 | (e.g., what kind of register is required). The second argument is the | |
25708 | value to be used as the input argument. The possible values for the | |
25709 | constraint are the same as those used in the RTL, and are dependent on | |
25710 | the configuration file used to built the GCC back end. | |
25711 | No support is provided for GNU C’s symbolic names for input parameters. | |
25712 | ||
25713 | If there are no input operands, this argument may either be omitted, or | |
25714 | explicitly given as @code{No_Input_Operands}. The fourth argument, not | |
25715 | present in the above example, is a list of register names, called the | |
25716 | `clobber' argument. This argument, if given, must be a static string | |
25717 | expression, and is a space or comma separated list of names of registers | |
25718 | that must be considered destroyed as a result of the @code{Asm} call. If | |
25719 | this argument is the null string (the default value), then the code | |
25720 | generator assumes that no additional registers are destroyed. | |
25721 | In addition to registers, the special clobbers @code{memory} and | |
25722 | @code{cc} as described in the GNU C docs are both supported. | |
25723 | ||
25724 | The fifth argument, not present in the above example, called the | |
25725 | `volatile' argument, is by default @code{False}. It can be set to | |
25726 | the literal value @code{True} to indicate to the code generator that all | |
25727 | optimizations with respect to the instruction specified should be | |
25728 | suppressed, and in particular an instruction that has outputs | |
25729 | will still be generated, even if none of the outputs are | |
25730 | used. See @cite{Using_the_GNU_Compiler_Collection_(GCC)} | |
25731 | for the full description. | |
25732 | Generally it is strongly advisable to use Volatile for any ASM statement | |
25733 | that is missing either input or output operands or to avoid unwanted | |
25734 | optimizations. A warning is generated if this advice is not followed. | |
25735 | ||
25736 | No support is provided for GNU C’s @code{asm goto} feature. | |
25737 | ||
25738 | The @code{Asm} subprograms may be used in two ways. First the procedure | |
25739 | forms can be used anywhere a procedure call would be valid, and | |
25740 | correspond to what the RM calls ‘intrinsic’ routines. Such calls can | |
25741 | be used to intersperse machine instructions with other Ada statements. | |
25742 | Second, the function forms, which return a dummy value of the limited | |
25743 | private type @code{Asm_Insn}, can be used in code statements, and indeed | |
25744 | this is the only context where such calls are allowed. Code statements | |
25745 | appear as aggregates of the form: | |
25746 | ||
b71d4b62 RA |
25747 | @example |
25748 | Asm_Insn'(Asm (...)); | |
25749 | Asm_Insn'(Asm_Volatile (...)); | |
25750 | @end example | |
25751 | ||
25752 | In accordance with RM rules, such code statements are allowed only | |
25753 | within subprograms whose entire body consists of such statements. It is | |
25754 | not permissible to intermix such statements with other Ada statements. | |
25755 | ||
25756 | Typically the form using intrinsic procedure calls is more convenient | |
25757 | and more flexible. The code statement form is provided to meet the RM | |
25758 | suggestion that such a facility should be made available. The following | |
25759 | is the exact syntax of the call to @code{Asm}. As usual, if named notation | |
25760 | is used, the arguments may be given in arbitrary order, following the | |
25761 | normal rules for use of positional and named arguments: | |
25762 | ||
25763 | @example | |
25764 | ASM_CALL ::= Asm ( | |
25765 | [Template =>] static_string_EXPRESSION | |
25766 | [,[Outputs =>] OUTPUT_OPERAND_LIST ] | |
25767 | [,[Inputs =>] INPUT_OPERAND_LIST ] | |
25768 | [,[Clobber =>] static_string_EXPRESSION ] | |
25769 | [,[Volatile =>] static_boolean_EXPRESSION] ) | |
25770 | ||
25771 | OUTPUT_OPERAND_LIST ::= | |
25772 | [PREFIX.]No_Output_Operands | |
25773 | | OUTPUT_OPERAND_ATTRIBUTE | |
25774 | | (OUTPUT_OPERAND_ATTRIBUTE @{,OUTPUT_OPERAND_ATTRIBUTE@}) | |
25775 | ||
25776 | OUTPUT_OPERAND_ATTRIBUTE ::= | |
25777 | SUBTYPE_MARK'Asm_Output (static_string_EXPRESSION, NAME) | |
25778 | ||
25779 | INPUT_OPERAND_LIST ::= | |
25780 | [PREFIX.]No_Input_Operands | |
25781 | | INPUT_OPERAND_ATTRIBUTE | |
25782 | | (INPUT_OPERAND_ATTRIBUTE @{,INPUT_OPERAND_ATTRIBUTE@}) | |
25783 | ||
25784 | INPUT_OPERAND_ATTRIBUTE ::= | |
25785 | SUBTYPE_MARK'Asm_Input (static_string_EXPRESSION, EXPRESSION) | |
25786 | @end example | |
25787 | ||
25788 | The identifiers @code{No_Input_Operands} and @code{No_Output_Operands} | |
25789 | are declared in the package @code{Machine_Code} and must be referenced | |
25790 | according to normal visibility rules. In particular if there is no | |
25791 | @code{use} clause for this package, then appropriate package name | |
25792 | qualification is required. | |
25793 | ||
25794 | @node GNAT Implementation of Tasking,GNAT Implementation of Shared Passive Packages,Machine Code Insertions,Implementation of Specific Ada Features | |
04d6c745 | 25795 | @anchor{gnat_rm/implementation_of_specific_ada_features gnat-implementation-of-tasking}@anchor{417}@anchor{gnat_rm/implementation_of_specific_ada_features id3}@anchor{418} |
b71d4b62 RA |
25796 | @section GNAT Implementation of Tasking |
25797 | ||
25798 | ||
25799 | This chapter outlines the basic GNAT approach to tasking (in particular, | |
25800 | a multi-layered library for portability) and discusses issues related | |
25801 | to compliance with the Real-Time Systems Annex. | |
25802 | ||
25803 | @menu | |
25804 | * Mapping Ada Tasks onto the Underlying Kernel Threads:: | |
25805 | * Ensuring Compliance with the Real-Time Annex:: | |
25806 | * Support for Locking Policies:: | |
25807 | ||
25808 | @end menu | |
25809 | ||
25810 | @node Mapping Ada Tasks onto the Underlying Kernel Threads,Ensuring Compliance with the Real-Time Annex,,GNAT Implementation of Tasking | |
04d6c745 | 25811 | @anchor{gnat_rm/implementation_of_specific_ada_features id4}@anchor{419}@anchor{gnat_rm/implementation_of_specific_ada_features mapping-ada-tasks-onto-the-underlying-kernel-threads}@anchor{41a} |
b71d4b62 RA |
25812 | @subsection Mapping Ada Tasks onto the Underlying Kernel Threads |
25813 | ||
25814 | ||
25815 | GNAT’s run-time support comprises two layers: | |
25816 | ||
25817 | ||
25818 | @itemize * | |
25819 | ||
25820 | @item | |
25821 | GNARL (GNAT Run-time Layer) | |
25822 | ||
25823 | @item | |
25824 | GNULL (GNAT Low-level Library) | |
25825 | @end itemize | |
25826 | ||
25827 | In GNAT, Ada’s tasking services rely on a platform and OS independent | |
25828 | layer known as GNARL. This code is responsible for implementing the | |
25829 | correct semantics of Ada’s task creation, rendezvous, protected | |
25830 | operations etc. | |
25831 | ||
25832 | GNARL decomposes Ada’s tasking semantics into simpler lower level | |
25833 | operations such as create a thread, set the priority of a thread, | |
25834 | yield, create a lock, lock/unlock, etc. The spec for these low-level | |
25835 | operations constitutes GNULLI, the GNULL Interface. This interface is | |
25836 | directly inspired from the POSIX real-time API. | |
25837 | ||
25838 | If the underlying executive or OS implements the POSIX standard | |
25839 | faithfully, the GNULL Interface maps as is to the services offered by | |
25840 | the underlying kernel. Otherwise, some target dependent glue code maps | |
25841 | the services offered by the underlying kernel to the semantics expected | |
25842 | by GNARL. | |
25843 | ||
25844 | Whatever the underlying OS (VxWorks, UNIX, Windows, etc.) the | |
25845 | key point is that each Ada task is mapped on a thread in the underlying | |
25846 | kernel. For example, in the case of VxWorks, one Ada task = one VxWorks task. | |
25847 | ||
25848 | In addition Ada task priorities map onto the underlying thread priorities. | |
25849 | Mapping Ada tasks onto the underlying kernel threads has several advantages: | |
25850 | ||
25851 | ||
25852 | @itemize * | |
25853 | ||
25854 | @item | |
25855 | The underlying scheduler is used to schedule the Ada tasks. This | |
25856 | makes Ada tasks as efficient as kernel threads from a scheduling | |
25857 | standpoint. | |
25858 | ||
25859 | @item | |
25860 | Interaction with code written in C containing threads is eased | |
25861 | since at the lowest level Ada tasks and C threads map onto the same | |
25862 | underlying kernel concept. | |
25863 | ||
25864 | @item | |
25865 | When an Ada task is blocked during I/O the remaining Ada tasks are | |
25866 | able to proceed. | |
25867 | ||
25868 | @item | |
25869 | On multiprocessor systems Ada tasks can execute in parallel. | |
25870 | @end itemize | |
25871 | ||
25872 | Some threads libraries offer a mechanism to fork a new process, with the | |
25873 | child process duplicating the threads from the parent. | |
25874 | GNAT does not | |
25875 | support this functionality when the parent contains more than one task. | |
25876 | ||
25877 | @geindex Forking a new process | |
25878 | ||
25879 | @node Ensuring Compliance with the Real-Time Annex,Support for Locking Policies,Mapping Ada Tasks onto the Underlying Kernel Threads,GNAT Implementation of Tasking | |
04d6c745 | 25880 | @anchor{gnat_rm/implementation_of_specific_ada_features ensuring-compliance-with-the-real-time-annex}@anchor{41b}@anchor{gnat_rm/implementation_of_specific_ada_features id5}@anchor{41c} |
b71d4b62 RA |
25881 | @subsection Ensuring Compliance with the Real-Time Annex |
25882 | ||
25883 | ||
25884 | @geindex Real-Time Systems Annex compliance | |
25885 | ||
25886 | Although mapping Ada tasks onto | |
25887 | the underlying threads has significant advantages, it does create some | |
25888 | complications when it comes to respecting the scheduling semantics | |
25889 | specified in the real-time annex (Annex D). | |
25890 | ||
25891 | For instance the Annex D requirement for the @code{FIFO_Within_Priorities} | |
25892 | scheduling policy states: | |
25893 | ||
25894 | @quotation | |
25895 | ||
25896 | `When the active priority of a ready task that is not running | |
25897 | changes, or the setting of its base priority takes effect, the | |
25898 | task is removed from the ready queue for its old active priority | |
25899 | and is added at the tail of the ready queue for its new active | |
25900 | priority, except in the case where the active priority is lowered | |
25901 | due to the loss of inherited priority, in which case the task is | |
25902 | added at the head of the ready queue for its new active priority.' | |
25903 | @end quotation | |
25904 | ||
25905 | While most kernels do put tasks at the end of the priority queue when | |
25906 | a task changes its priority, (which respects the main | |
25907 | FIFO_Within_Priorities requirement), almost none keep a thread at the | |
25908 | beginning of its priority queue when its priority drops from the loss | |
25909 | of inherited priority. | |
25910 | ||
25911 | As a result most vendors have provided incomplete Annex D implementations. | |
25912 | ||
25913 | The GNAT run-time, has a nice cooperative solution to this problem | |
25914 | which ensures that accurate FIFO_Within_Priorities semantics are | |
25915 | respected. | |
25916 | ||
25917 | The principle is as follows. When an Ada task T is about to start | |
25918 | running, it checks whether some other Ada task R with the same | |
25919 | priority as T has been suspended due to the loss of priority | |
25920 | inheritance. If this is the case, T yields and is placed at the end of | |
25921 | its priority queue. When R arrives at the front of the queue it | |
25922 | executes. | |
25923 | ||
25924 | Note that this simple scheme preserves the relative order of the tasks | |
25925 | that were ready to execute in the priority queue where R has been | |
25926 | placed at the end. | |
25927 | ||
25928 | @c Support_for_Locking_Policies | |
25929 | ||
25930 | @node Support for Locking Policies,,Ensuring Compliance with the Real-Time Annex,GNAT Implementation of Tasking | |
04d6c745 | 25931 | @anchor{gnat_rm/implementation_of_specific_ada_features support-for-locking-policies}@anchor{41d} |
b71d4b62 RA |
25932 | @subsection Support for Locking Policies |
25933 | ||
25934 | ||
25935 | This section specifies which policies specified by pragma Locking_Policy | |
25936 | are supported on which platforms. | |
25937 | ||
25938 | GNAT supports the standard @code{Ceiling_Locking} policy, and the | |
25939 | implementation defined @code{Inheritance_Locking} and | |
25940 | @code{Concurrent_Readers_Locking} policies. | |
25941 | ||
25942 | @code{Ceiling_Locking} is supported on all platforms if the operating system | |
25943 | supports it. In particular, @code{Ceiling_Locking} is not supported on | |
25944 | VxWorks. | |
25945 | @code{Inheritance_Locking} is supported on | |
25946 | Linux, | |
25947 | Darwin (Mac OS X), | |
25948 | LynxOS 178, | |
25949 | and VxWorks. | |
25950 | @code{Concurrent_Readers_Locking} is supported on Linux. | |
25951 | ||
25952 | Notes about @code{Ceiling_Locking} on Linux: | |
25953 | If the process is running as ‘root’, ceiling locking is used. | |
25954 | If the capabilities facility is installed | |
25955 | (“sudo apt-get –assume-yes install libcap-dev” on Ubuntu, | |
25956 | for example), | |
25957 | and the program is linked against that library | |
25958 | (“-largs -lcap”), | |
25959 | and the executable file has the cap_sys_nice capability | |
25960 | (“sudo /sbin/setcap cap_sys_nice=ep executable_file_name”), | |
25961 | then ceiling locking is used. | |
25962 | Otherwise, the @code{Ceiling_Locking} policy is ignored. | |
25963 | ||
25964 | @node GNAT Implementation of Shared Passive Packages,Code Generation for Array Aggregates,GNAT Implementation of Tasking,Implementation of Specific Ada Features | |
04d6c745 | 25965 | @anchor{gnat_rm/implementation_of_specific_ada_features gnat-implementation-of-shared-passive-packages}@anchor{41e}@anchor{gnat_rm/implementation_of_specific_ada_features id6}@anchor{41f} |
b71d4b62 RA |
25966 | @section GNAT Implementation of Shared Passive Packages |
25967 | ||
25968 | ||
25969 | @geindex Shared passive packages | |
25970 | ||
25971 | GNAT fully implements the | |
25972 | @geindex pragma Shared_Passive | |
25973 | pragma | |
25974 | @code{Shared_Passive} for | |
25975 | the purpose of designating shared passive packages. | |
25976 | This allows the use of passive partitions in the | |
25977 | context described in the Ada Reference Manual; i.e., for communication | |
25978 | between separate partitions of a distributed application using the | |
25979 | features in Annex E. | |
25980 | ||
25981 | @geindex Annex E | |
25982 | ||
25983 | @geindex Distribution Systems Annex | |
25984 | ||
25985 | However, the implementation approach used by GNAT provides for more | |
25986 | extensive usage as follows: | |
25987 | ||
25988 | ||
25989 | @table @asis | |
25990 | ||
25991 | @item `Communication between separate programs' | |
25992 | ||
25993 | This allows separate programs to access the data in passive | |
25994 | partitions, using protected objects for synchronization where | |
25995 | needed. The only requirement is that the two programs have a | |
25996 | common shared file system. It is even possible for programs | |
25997 | running on different machines with different architectures | |
25998 | (e.g., different endianness) to communicate via the data in | |
25999 | a passive partition. | |
26000 | ||
26001 | @item `Persistence between program runs' | |
26002 | ||
26003 | The data in a passive package can persist from one run of a | |
26004 | program to another, so that a later program sees the final | |
26005 | values stored by a previous run of the same program. | |
26006 | @end table | |
26007 | ||
26008 | The implementation approach used is to store the data in files. A | |
26009 | separate stream file is created for each object in the package, and | |
26010 | an access to an object causes the corresponding file to be read or | |
26011 | written. | |
26012 | ||
26013 | @geindex SHARED_MEMORY_DIRECTORY environment variable | |
26014 | ||
26015 | The environment variable @code{SHARED_MEMORY_DIRECTORY} should be | |
26016 | set to the directory to be used for these files. | |
26017 | The files in this directory | |
26018 | have names that correspond to their fully qualified names. For | |
26019 | example, if we have the package | |
26020 | ||
26021 | @example | |
26022 | package X is | |
26023 | pragma Shared_Passive (X); | |
26024 | Y : Integer; | |
26025 | Z : Float; | |
26026 | end X; | |
26027 | @end example | |
26028 | ||
26029 | and the environment variable is set to @code{/stemp/}, then the files created | |
26030 | will have the names: | |
26031 | ||
26032 | @example | |
26033 | /stemp/x.y | |
26034 | /stemp/x.z | |
26035 | @end example | |
26036 | ||
26037 | These files are created when a value is initially written to the object, and | |
26038 | the files are retained until manually deleted. This provides the persistence | |
26039 | semantics. If no file exists, it means that no partition has assigned a value | |
26040 | to the variable; in this case the initial value declared in the package | |
26041 | will be used. This model ensures that there are no issues in synchronizing | |
26042 | the elaboration process, since elaboration of passive packages elaborates the | |
26043 | initial values, but does not create the files. | |
26044 | ||
26045 | The files are written using normal @code{Stream_IO} access. | |
26046 | If you want to be able | |
26047 | to communicate between programs or partitions running on different | |
26048 | architectures, then you should use the XDR versions of the stream attribute | |
26049 | routines, since these are architecture independent. | |
26050 | ||
26051 | If active synchronization is required for access to the variables in the | |
26052 | shared passive package, then as described in the Ada Reference Manual, the | |
26053 | package may contain protected objects used for this purpose. In this case | |
26054 | a lock file (whose name is @code{___lock}, with three underscores) | |
26055 | is created in the shared memory directory. | |
26056 | ||
26057 | @geindex ___lock file (for shared passive packages) | |
26058 | ||
26059 | This is used to provide the required locking | |
26060 | semantics for proper protected object synchronization. | |
26061 | ||
26062 | @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 | |
04d6c745 | 26063 | @anchor{gnat_rm/implementation_of_specific_ada_features code-generation-for-array-aggregates}@anchor{420}@anchor{gnat_rm/implementation_of_specific_ada_features id7}@anchor{421} |
b71d4b62 RA |
26064 | @section Code Generation for Array Aggregates |
26065 | ||
26066 | ||
26067 | Aggregates have a rich syntax and allow the user to specify the values of | |
26068 | complex data structures by means of a single construct. As a result, the | |
26069 | code generated for aggregates can be quite complex and involve loops, case | |
26070 | statements and multiple assignments. In the simplest cases, however, the | |
26071 | compiler will recognize aggregates whose components and constraints are | |
26072 | fully static, and in those cases the compiler will generate little or no | |
26073 | executable code. The following is an outline of the code that GNAT generates | |
26074 | for various aggregate constructs. For further details, you will find it | |
26075 | useful to examine the output produced by the -gnatG flag to see the expanded | |
26076 | source that is input to the code generator. You may also want to examine | |
26077 | the assembly code generated at various levels of optimization. | |
26078 | ||
26079 | The code generated for aggregates depends on the context, the component values, | |
26080 | and the type. In the context of an object declaration the code generated is | |
26081 | generally simpler than in the case of an assignment. As a general rule, static | |
26082 | component values and static subtypes also lead to simpler code. | |
26083 | ||
26084 | @menu | |
26085 | * Static constant aggregates with static bounds:: | |
26086 | * Constant aggregates with unconstrained nominal types:: | |
26087 | * Aggregates with static bounds:: | |
26088 | * Aggregates with nonstatic bounds:: | |
26089 | * Aggregates in assignment statements:: | |
26090 | ||
26091 | @end menu | |
26092 | ||
26093 | @node Static constant aggregates with static bounds,Constant aggregates with unconstrained nominal types,,Code Generation for Array Aggregates | |
04d6c745 | 26094 | @anchor{gnat_rm/implementation_of_specific_ada_features id8}@anchor{422}@anchor{gnat_rm/implementation_of_specific_ada_features static-constant-aggregates-with-static-bounds}@anchor{423} |
b71d4b62 RA |
26095 | @subsection Static constant aggregates with static bounds |
26096 | ||
26097 | ||
26098 | For the declarations: | |
26099 | ||
26100 | @example | |
26101 | type One_Dim is array (1..10) of integer; | |
26102 | ar0 : constant One_Dim := (1, 2, 3, 4, 5, 6, 7, 8, 9, 0); | |
26103 | @end example | |
26104 | ||
26105 | GNAT generates no executable code: the constant ar0 is placed in static memory. | |
26106 | The same is true for constant aggregates with named associations: | |
26107 | ||
26108 | @example | |
26109 | Cr1 : constant One_Dim := (4 => 16, 2 => 4, 3 => 9, 1 => 1, 5 .. 10 => 0); | |
26110 | Cr3 : constant One_Dim := (others => 7777); | |
26111 | @end example | |
26112 | ||
26113 | The same is true for multidimensional constant arrays such as: | |
26114 | ||
26115 | @example | |
26116 | type two_dim is array (1..3, 1..3) of integer; | |
26117 | Unit : constant two_dim := ( (1,0,0), (0,1,0), (0,0,1)); | |
26118 | @end example | |
26119 | ||
26120 | The same is true for arrays of one-dimensional arrays: the following are | |
26121 | static: | |
26122 | ||
26123 | @example | |
26124 | type ar1b is array (1..3) of boolean; | |
26125 | type ar_ar is array (1..3) of ar1b; | |
26126 | None : constant ar1b := (others => false); -- fully static | |
26127 | None2 : constant ar_ar := (1..3 => None); -- fully static | |
26128 | @end example | |
26129 | ||
26130 | However, for multidimensional aggregates with named associations, GNAT will | |
26131 | generate assignments and loops, even if all associations are static. The | |
26132 | following two declarations generate a loop for the first dimension, and | |
26133 | individual component assignments for the second dimension: | |
26134 | ||
26135 | @example | |
26136 | Zero1: constant two_dim := (1..3 => (1..3 => 0)); | |
26137 | Zero2: constant two_dim := (others => (others => 0)); | |
26138 | @end example | |
26139 | ||
26140 | @node Constant aggregates with unconstrained nominal types,Aggregates with static bounds,Static constant aggregates with static bounds,Code Generation for Array Aggregates | |
04d6c745 | 26141 | @anchor{gnat_rm/implementation_of_specific_ada_features constant-aggregates-with-unconstrained-nominal-types}@anchor{424}@anchor{gnat_rm/implementation_of_specific_ada_features id9}@anchor{425} |
b71d4b62 RA |
26142 | @subsection Constant aggregates with unconstrained nominal types |
26143 | ||
26144 | ||
26145 | In such cases the aggregate itself establishes the subtype, so that | |
26146 | associations with @code{others} cannot be used. GNAT determines the | |
26147 | bounds for the actual subtype of the aggregate, and allocates the | |
26148 | aggregate statically as well. No code is generated for the following: | |
26149 | ||
26150 | @example | |
26151 | type One_Unc is array (natural range <>) of integer; | |
26152 | Cr_Unc : constant One_Unc := (12,24,36); | |
26153 | @end example | |
26154 | ||
26155 | @node Aggregates with static bounds,Aggregates with nonstatic bounds,Constant aggregates with unconstrained nominal types,Code Generation for Array Aggregates | |
04d6c745 | 26156 | @anchor{gnat_rm/implementation_of_specific_ada_features aggregates-with-static-bounds}@anchor{426}@anchor{gnat_rm/implementation_of_specific_ada_features id10}@anchor{427} |
b71d4b62 RA |
26157 | @subsection Aggregates with static bounds |
26158 | ||
26159 | ||
26160 | In all previous examples the aggregate was the initial (and immutable) value | |
26161 | of a constant. If the aggregate initializes a variable, then code is generated | |
26162 | for it as a combination of individual assignments and loops over the target | |
26163 | object. The declarations | |
26164 | ||
26165 | @example | |
26166 | Cr_Var1 : One_Dim := (2, 5, 7, 11, 0, 0, 0, 0, 0, 0); | |
26167 | Cr_Var2 : One_Dim := (others > -1); | |
26168 | @end example | |
26169 | ||
26170 | generate the equivalent of | |
26171 | ||
26172 | @example | |
26173 | Cr_Var1 (1) := 2; | |
26174 | Cr_Var1 (2) := 3; | |
26175 | Cr_Var1 (3) := 5; | |
26176 | Cr_Var1 (4) := 11; | |
26177 | ||
26178 | for I in Cr_Var2'range loop | |
26179 | Cr_Var2 (I) := -1; | |
26180 | end loop; | |
26181 | @end example | |
26182 | ||
26183 | @node Aggregates with nonstatic bounds,Aggregates in assignment statements,Aggregates with static bounds,Code Generation for Array Aggregates | |
04d6c745 | 26184 | @anchor{gnat_rm/implementation_of_specific_ada_features aggregates-with-nonstatic-bounds}@anchor{428}@anchor{gnat_rm/implementation_of_specific_ada_features id11}@anchor{429} |
b71d4b62 RA |
26185 | @subsection Aggregates with nonstatic bounds |
26186 | ||
26187 | ||
26188 | If the bounds of the aggregate are not statically compatible with the bounds | |
26189 | of the nominal subtype of the target, then constraint checks have to be | |
26190 | generated on the bounds. For a multidimensional array, constraint checks may | |
26191 | have to be applied to sub-arrays individually, if they do not have statically | |
26192 | compatible subtypes. | |
26193 | ||
26194 | @node Aggregates in assignment statements,,Aggregates with nonstatic bounds,Code Generation for Array Aggregates | |
04d6c745 | 26195 | @anchor{gnat_rm/implementation_of_specific_ada_features aggregates-in-assignment-statements}@anchor{42a}@anchor{gnat_rm/implementation_of_specific_ada_features id12}@anchor{42b} |
b71d4b62 RA |
26196 | @subsection Aggregates in assignment statements |
26197 | ||
26198 | ||
26199 | In general, aggregate assignment requires the construction of a temporary, | |
26200 | and a copy from the temporary to the target of the assignment. This is because | |
26201 | it is not always possible to convert the assignment into a series of individual | |
26202 | component assignments. For example, consider the simple case: | |
26203 | ||
26204 | @example | |
26205 | A := (A(2), A(1)); | |
26206 | @end example | |
26207 | ||
26208 | This cannot be converted into: | |
26209 | ||
26210 | @example | |
26211 | A(1) := A(2); | |
26212 | A(2) := A(1); | |
26213 | @end example | |
26214 | ||
26215 | So the aggregate has to be built first in a separate location, and then | |
26216 | copied into the target. GNAT recognizes simple cases where this intermediate | |
26217 | step is not required, and the assignments can be performed in place, directly | |
26218 | into the target. The following sufficient criteria are applied: | |
26219 | ||
26220 | ||
26221 | @itemize * | |
26222 | ||
26223 | @item | |
26224 | The bounds of the aggregate are static, and the associations are static. | |
26225 | ||
26226 | @item | |
26227 | The components of the aggregate are static constants, names of | |
26228 | simple variables that are not renamings, or expressions not involving | |
26229 | indexed components whose operands obey these rules. | |
26230 | @end itemize | |
26231 | ||
26232 | If any of these conditions are violated, the aggregate will be built in | |
26233 | a temporary (created either by the front-end or the code generator) and then | |
26234 | that temporary will be copied onto the target. | |
26235 | ||
26236 | @node The Size of Discriminated Records with Default Discriminants,Image Values For Nonscalar Types,Code Generation for Array Aggregates,Implementation of Specific Ada Features | |
04d6c745 | 26237 | @anchor{gnat_rm/implementation_of_specific_ada_features id13}@anchor{42c}@anchor{gnat_rm/implementation_of_specific_ada_features the-size-of-discriminated-records-with-default-discriminants}@anchor{42d} |
b71d4b62 RA |
26238 | @section The Size of Discriminated Records with Default Discriminants |
26239 | ||
26240 | ||
26241 | If a discriminated type @code{T} has discriminants with default values, it is | |
26242 | possible to declare an object of this type without providing an explicit | |
26243 | constraint: | |
26244 | ||
26245 | @example | |
26246 | type Size is range 1..100; | |
26247 | ||
26248 | type Rec (D : Size := 15) is record | |
26249 | Name : String (1..D); | |
26250 | end T; | |
26251 | ||
26252 | Word : Rec; | |
26253 | @end example | |
26254 | ||
26255 | Such an object is said to be `unconstrained'. | |
26256 | The discriminant of the object | |
26257 | can be modified by a full assignment to the object, as long as it preserves the | |
26258 | relation between the value of the discriminant, and the value of the components | |
26259 | that depend on it: | |
26260 | ||
26261 | @example | |
26262 | Word := (3, "yes"); | |
26263 | ||
26264 | Word := (5, "maybe"); | |
26265 | ||
26266 | Word := (5, "no"); -- raises Constraint_Error | |
26267 | @end example | |
26268 | ||
26269 | In order to support this behavior efficiently, an unconstrained object is | |
26270 | given the maximum size that any value of the type requires. In the case | |
26271 | above, @code{Word} has storage for the discriminant and for | |
26272 | a @code{String} of length 100. | |
26273 | It is important to note that unconstrained objects do not require dynamic | |
26274 | allocation. It would be an improper implementation to place on the heap those | |
26275 | components whose size depends on discriminants. (This improper implementation | |
26276 | was used by some Ada83 compilers, where the @code{Name} component above | |
26277 | would have | |
26278 | been stored as a pointer to a dynamic string). Following the principle that | |
26279 | dynamic storage management should never be introduced implicitly, | |
26280 | an Ada compiler should reserve the full size for an unconstrained declared | |
26281 | object, and place it on the stack. | |
26282 | ||
26283 | This maximum size approach | |
26284 | has been a source of surprise to some users, who expect the default | |
26285 | values of the discriminants to determine the size reserved for an | |
26286 | unconstrained object: “If the default is 15, why should the object occupy | |
26287 | a larger size?” | |
26288 | The answer, of course, is that the discriminant may be later modified, | |
26289 | and its full range of values must be taken into account. This is why the | |
26290 | declaration: | |
26291 | ||
26292 | @example | |
26293 | type Rec (D : Positive := 15) is record | |
26294 | Name : String (1..D); | |
26295 | end record; | |
26296 | ||
26297 | Too_Large : Rec; | |
26298 | @end example | |
26299 | ||
26300 | is flagged by the compiler with a warning: | |
26301 | an attempt to create @code{Too_Large} will raise @code{Storage_Error}, | |
26302 | because the required size includes @code{Positive'Last} | |
26303 | bytes. As the first example indicates, the proper approach is to declare an | |
26304 | index type of ‘reasonable’ range so that unconstrained objects are not too | |
26305 | large. | |
26306 | ||
26307 | One final wrinkle: if the object is declared to be @code{aliased}, or if it is | |
26308 | created in the heap by means of an allocator, then it is `not' | |
26309 | unconstrained: | |
26310 | it is constrained by the default values of the discriminants, and those values | |
26311 | cannot be modified by full assignment. This is because in the presence of | |
26312 | aliasing all views of the object (which may be manipulated by different tasks, | |
26313 | say) must be consistent, so it is imperative that the object, once created, | |
26314 | remain invariant. | |
26315 | ||
26316 | @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 | |
04d6c745 | 26317 | @anchor{gnat_rm/implementation_of_specific_ada_features id14}@anchor{42e}@anchor{gnat_rm/implementation_of_specific_ada_features image-values-for-nonscalar-types}@anchor{42f} |
b71d4b62 RA |
26318 | @section Image Values For Nonscalar Types |
26319 | ||
26320 | ||
26321 | Ada 2022 defines the Image, Wide_Image, and Wide_Wide image attributes | |
26322 | for nonscalar types; earlier Ada versions defined these attributes only | |
26323 | for scalar types. Ada RM 4.10 provides some general guidance regarding | |
26324 | the default implementation of these attributes and the GNAT compiler | |
26325 | follows that guidance. However, beyond that the precise details of the | |
26326 | image text generated in these cases are deliberately not documented and are | |
26327 | subject to change. In particular, users should not rely on formatting details | |
26328 | (such as spaces or line breaking), record field order, image values for access | |
26329 | types, image values for types that have ancestor or subcomponent types | |
26330 | declared in non-Ada2022 code, image values for predefined types, or the | |
26331 | compiler’s choices regarding the implementation permissions described in | |
26332 | Ada RM 4.10. This list is not intended to be exhaustive. If more precise | |
26333 | control of image text is required for some type T, then T’Put_Image should be | |
26334 | explicitly specified. | |
26335 | ||
26336 | @node Strict Conformance to the Ada Reference Manual,,Image Values For Nonscalar Types,Implementation of Specific Ada Features | |
04d6c745 | 26337 | @anchor{gnat_rm/implementation_of_specific_ada_features id15}@anchor{430}@anchor{gnat_rm/implementation_of_specific_ada_features strict-conformance-to-the-ada-reference-manual}@anchor{431} |
b71d4b62 RA |
26338 | @section Strict Conformance to the Ada Reference Manual |
26339 | ||
26340 | ||
26341 | The dynamic semantics defined by the Ada Reference Manual impose a set of | |
26342 | run-time checks to be generated. By default, the GNAT compiler will insert many | |
26343 | run-time checks into the compiled code, including most of those required by the | |
26344 | Ada Reference Manual. However, there are two checks that are not enabled in | |
26345 | the default mode for efficiency reasons: checks for access before elaboration | |
26346 | on subprogram calls, and stack overflow checking (most operating systems do not | |
26347 | perform this check by default). | |
26348 | ||
26349 | Strict conformance to the Ada Reference Manual can be achieved by adding two | |
26350 | compiler options for dynamic checks for access-before-elaboration on subprogram | |
26351 | calls and generic instantiations (`-gnatE'), and stack overflow checking | |
26352 | (`-fstack-check'). | |
26353 | ||
26354 | Note that the result of a floating point arithmetic operation in overflow and | |
26355 | invalid situations, when the @code{Machine_Overflows} attribute of the result | |
26356 | type is @code{False}, is to generate IEEE NaN and infinite values. This is the | |
26357 | case for machines compliant with the IEEE floating-point standard, but on | |
26358 | machines that are not fully compliant with this standard, such as Alpha, the | |
26359 | `-mieee' compiler flag must be used for achieving IEEE confirming | |
26360 | behavior (although at the cost of a significant performance penalty), so | |
26361 | infinite and NaN values are properly generated. | |
26362 | ||
26363 | @node Implementation of Ada 2012 Features,GNAT language extensions,Implementation of Specific Ada Features,Top | |
04d6c745 | 26364 | @anchor{gnat_rm/implementation_of_ada_2012_features doc}@anchor{432}@anchor{gnat_rm/implementation_of_ada_2012_features id1}@anchor{433}@anchor{gnat_rm/implementation_of_ada_2012_features implementation-of-ada-2012-features}@anchor{14} |
b71d4b62 RA |
26365 | @chapter Implementation of Ada 2012 Features |
26366 | ||
26367 | ||
26368 | @geindex Ada 2012 implementation status | |
26369 | ||
26370 | @geindex -gnat12 option (gcc) | |
26371 | ||
26372 | @geindex pragma Ada_2012 | |
26373 | ||
26374 | @geindex configuration pragma Ada_2012 | |
26375 | ||
26376 | @geindex Ada_2012 configuration pragma | |
26377 | ||
26378 | This chapter contains a complete list of Ada 2012 features that have been | |
26379 | implemented. | |
26380 | Generally, these features are only | |
26381 | available if the `-gnat12' (Ada 2012 features enabled) option is set, | |
26382 | which is the default behavior, | |
26383 | or if the configuration pragma @code{Ada_2012} is used. | |
26384 | ||
26385 | However, new pragmas, attributes, and restrictions are | |
26386 | unconditionally available, since the Ada 95 standard allows the addition of | |
26387 | new pragmas, attributes, and restrictions (there are exceptions, which are | |
26388 | documented in the individual descriptions), and also certain packages | |
26389 | were made available in earlier versions of Ada. | |
26390 | ||
26391 | An ISO date (YYYY-MM-DD) appears in parentheses on the description line. | |
26392 | This date shows the implementation date of the feature. Any wavefront | |
26393 | subsequent to this date will contain the indicated feature, as will any | |
26394 | subsequent releases. A date of 0000-00-00 means that GNAT has always | |
26395 | implemented the feature, or implemented it as soon as it appeared as a | |
26396 | binding interpretation. | |
26397 | ||
26398 | Each feature corresponds to an Ada Issue (‘AI’) approved by the Ada | |
26399 | standardization group (ISO/IEC JTC1/SC22/WG9) for inclusion in Ada 2012. | |
26400 | The features are ordered based on the relevant sections of the Ada | |
26401 | Reference Manual (“RM”). When a given AI relates to multiple points | |
26402 | in the RM, the earliest is used. | |
26403 | ||
26404 | A complete description of the AIs may be found in | |
26405 | @indicateurl{http://www.ada-auth.org/ai05-summary.html}. | |
26406 | ||
26407 | @geindex AI-0176 (Ada 2012 feature) | |
64d5610f | 26408 | |
64d5610f | 26409 | |
b71d4b62 | 26410 | @itemize * |
64d5610f | 26411 | |
b71d4b62 RA |
26412 | @item |
26413 | `AI-0176 Quantified expressions (2010-09-29)' | |
64d5610f | 26414 | |
b71d4b62 RA |
26415 | Both universally and existentially quantified expressions are implemented. |
26416 | They use the new syntax for iterators proposed in AI05-139-2, as well as | |
26417 | the standard Ada loop syntax. | |
64d5610f | 26418 | |
b71d4b62 RA |
26419 | RM References: 1.01.04 (12) 2.09 (2/2) 4.04 (7) 4.05.09 (0) |
26420 | @end itemize | |
64d5610f | 26421 | |
b71d4b62 | 26422 | @geindex AI-0079 (Ada 2012 feature) |
64d5610f | 26423 | |
64d5610f | 26424 | |
b71d4b62 | 26425 | @itemize * |
64d5610f | 26426 | |
b71d4b62 RA |
26427 | @item |
26428 | `AI-0079 Allow other_format characters in source (2010-07-10)' | |
64d5610f | 26429 | |
b71d4b62 RA |
26430 | Wide characters in the unicode category `other_format' are now allowed in |
26431 | source programs between tokens, but not within a token such as an identifier. | |
64d5610f | 26432 | |
b71d4b62 RA |
26433 | RM References: 2.01 (4/2) 2.02 (7) |
26434 | @end itemize | |
64d5610f | 26435 | |
b71d4b62 | 26436 | @geindex AI-0091 (Ada 2012 feature) |
64d5610f | 26437 | |
64d5610f | 26438 | |
b71d4b62 RA |
26439 | @itemize * |
26440 | ||
26441 | @item | |
26442 | `AI-0091 Do not allow other_format in identifiers (0000-00-00)' | |
64d5610f | 26443 | |
b71d4b62 RA |
26444 | Wide characters in the unicode category `other_format' are not permitted |
26445 | within an identifier, since this can be a security problem. The error | |
26446 | message for this case has been improved to be more specific, but GNAT has | |
26447 | never allowed such characters to appear in identifiers. | |
64d5610f | 26448 | |
b71d4b62 RA |
26449 | 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) |
26450 | @end itemize | |
26451 | ||
26452 | @geindex AI-0100 (Ada 2012 feature) | |
64d5610f ML |
26453 | |
26454 | ||
26455 | @itemize * | |
26456 | ||
26457 | @item | |
b71d4b62 | 26458 | `AI-0100 Placement of pragmas (2010-07-01)' |
64d5610f | 26459 | |
b71d4b62 RA |
26460 | This AI is an earlier version of AI-163. It simplifies the rules |
26461 | for legal placement of pragmas. In the case of lists that allow pragmas, if | |
26462 | the list may have no elements, then the list may consist solely of pragmas. | |
26463 | ||
26464 | RM References: 2.08 (7) | |
64d5610f ML |
26465 | @end itemize |
26466 | ||
b71d4b62 | 26467 | @geindex AI-0163 (Ada 2012 feature) |
64d5610f | 26468 | |
64d5610f | 26469 | |
b71d4b62 | 26470 | @itemize * |
64d5610f | 26471 | |
b71d4b62 RA |
26472 | @item |
26473 | `AI-0163 Pragmas in place of null (2010-07-01)' | |
64d5610f | 26474 | |
b71d4b62 RA |
26475 | A statement sequence may be composed entirely of pragmas. It is no longer |
26476 | necessary to add a dummy @code{null} statement to make the sequence legal. | |
26477 | ||
26478 | RM References: 2.08 (7) 2.08 (16) | |
26479 | @end itemize | |
26480 | ||
26481 | @geindex AI-0080 (Ada 2012 feature) | |
64d5610f ML |
26482 | |
26483 | ||
26484 | @itemize * | |
26485 | ||
26486 | @item | |
b71d4b62 | 26487 | `AI-0080 ‘View of’ not needed if clear from context (0000-00-00)' |
64d5610f | 26488 | |
b71d4b62 | 26489 | This is an editorial change only, described as non-testable in the AI. |
64d5610f | 26490 | |
b71d4b62 RA |
26491 | RM References: 3.01 (7) |
26492 | @end itemize | |
26493 | ||
26494 | @geindex AI-0183 (Ada 2012 feature) | |
26495 | ||
26496 | ||
26497 | @itemize * | |
64d5610f ML |
26498 | |
26499 | @item | |
b71d4b62 RA |
26500 | `AI-0183 Aspect specifications (2010-08-16)' |
26501 | ||
26502 | Aspect specifications have been fully implemented except for pre and post- | |
26503 | conditions, and type invariants, which have their own separate AI’s. All | |
26504 | forms of declarations listed in the AI are supported. The following is a | |
26505 | list of the aspects supported (with GNAT implementation aspects marked) | |
64d5610f ML |
26506 | @end itemize |
26507 | ||
64d5610f | 26508 | |
b71d4b62 RA |
26509 | @multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxx} |
26510 | @headitem | |
64d5610f | 26511 | |
b71d4b62 | 26512 | Supported Aspect |
64d5610f | 26513 | |
b71d4b62 | 26514 | @tab |
64d5610f | 26515 | |
b71d4b62 | 26516 | Source |
64d5610f | 26517 | |
b71d4b62 | 26518 | @item |
64d5610f | 26519 | |
b71d4b62 | 26520 | @code{Ada_2005} |
64d5610f | 26521 | |
b71d4b62 | 26522 | @tab |
64d5610f | 26523 | |
b71d4b62 | 26524 | – GNAT |
64d5610f | 26525 | |
b71d4b62 | 26526 | @item |
64d5610f | 26527 | |
b71d4b62 | 26528 | @code{Ada_2012} |
64d5610f | 26529 | |
b71d4b62 | 26530 | @tab |
64d5610f | 26531 | |
b71d4b62 | 26532 | – GNAT |
64d5610f | 26533 | |
b71d4b62 | 26534 | @item |
64d5610f | 26535 | |
b71d4b62 | 26536 | @code{Address} |
64d5610f | 26537 | |
b71d4b62 RA |
26538 | @tab |
26539 | ||
26540 | @item | |
26541 | ||
26542 | @code{Alignment} | |
26543 | ||
26544 | @tab | |
26545 | ||
26546 | @item | |
26547 | ||
26548 | @code{Atomic} | |
26549 | ||
26550 | @tab | |
26551 | ||
26552 | @item | |
26553 | ||
26554 | @code{Atomic_Components} | |
26555 | ||
26556 | @tab | |
26557 | ||
26558 | @item | |
26559 | ||
26560 | @code{Bit_Order} | |
26561 | ||
26562 | @tab | |
26563 | ||
26564 | @item | |
26565 | ||
26566 | @code{Component_Size} | |
26567 | ||
26568 | @tab | |
26569 | ||
26570 | @item | |
26571 | ||
26572 | @code{Contract_Cases} | |
26573 | ||
26574 | @tab | |
26575 | ||
26576 | – GNAT | |
26577 | ||
26578 | @item | |
26579 | ||
26580 | @code{Discard_Names} | |
26581 | ||
26582 | @tab | |
26583 | ||
26584 | @item | |
26585 | ||
26586 | @code{External_Tag} | |
64d5610f | 26587 | |
b71d4b62 | 26588 | @tab |
64d5610f | 26589 | |
b71d4b62 | 26590 | @item |
64d5610f | 26591 | |
b71d4b62 | 26592 | @code{Favor_Top_Level} |
64d5610f | 26593 | |
b71d4b62 | 26594 | @tab |
64d5610f | 26595 | |
b71d4b62 | 26596 | – GNAT |
64d5610f | 26597 | |
b71d4b62 | 26598 | @item |
64d5610f | 26599 | |
b71d4b62 | 26600 | @code{Inline} |
64d5610f | 26601 | |
b71d4b62 | 26602 | @tab |
64d5610f | 26603 | |
b71d4b62 | 26604 | @item |
64d5610f | 26605 | |
b71d4b62 | 26606 | @code{Inline_Always} |
64d5610f | 26607 | |
b71d4b62 | 26608 | @tab |
64d5610f | 26609 | |
b71d4b62 | 26610 | – GNAT |
64d5610f | 26611 | |
b71d4b62 | 26612 | @item |
64d5610f | 26613 | |
b71d4b62 | 26614 | @code{Invariant} |
64d5610f | 26615 | |
b71d4b62 | 26616 | @tab |
64d5610f | 26617 | |
b71d4b62 | 26618 | – GNAT |
64d5610f | 26619 | |
b71d4b62 | 26620 | @item |
64d5610f | 26621 | |
b71d4b62 | 26622 | @code{Machine_Radix} |
64d5610f | 26623 | |
b71d4b62 | 26624 | @tab |
64d5610f | 26625 | |
b71d4b62 | 26626 | @item |
64d5610f | 26627 | |
b71d4b62 | 26628 | @code{No_Return} |
64d5610f | 26629 | |
b71d4b62 | 26630 | @tab |
64d5610f | 26631 | |
b71d4b62 | 26632 | @item |
64d5610f | 26633 | |
b71d4b62 | 26634 | @code{Object_Size} |
64d5610f | 26635 | |
b71d4b62 | 26636 | @tab |
64d5610f | 26637 | |
b71d4b62 | 26638 | – GNAT |
64d5610f | 26639 | |
b71d4b62 | 26640 | @item |
64d5610f | 26641 | |
b71d4b62 | 26642 | @code{Pack} |
64d5610f | 26643 | |
b71d4b62 | 26644 | @tab |
64d5610f | 26645 | |
b71d4b62 | 26646 | @item |
64d5610f | 26647 | |
b71d4b62 | 26648 | @code{Persistent_BSS} |
64d5610f | 26649 | |
b71d4b62 | 26650 | @tab |
64d5610f | 26651 | |
b71d4b62 | 26652 | – GNAT |
64d5610f | 26653 | |
b71d4b62 | 26654 | @item |
64d5610f | 26655 | |
b71d4b62 | 26656 | @code{Post} |
64d5610f | 26657 | |
b71d4b62 | 26658 | @tab |
64d5610f | 26659 | |
b71d4b62 | 26660 | @item |
64d5610f | 26661 | |
b71d4b62 | 26662 | @code{Pre} |
64d5610f | 26663 | |
b71d4b62 | 26664 | @tab |
64d5610f | 26665 | |
b71d4b62 | 26666 | @item |
64d5610f | 26667 | |
b71d4b62 | 26668 | @code{Predicate} |
64d5610f | 26669 | |
b71d4b62 | 26670 | @tab |
64d5610f | 26671 | |
b71d4b62 | 26672 | @item |
64d5610f | 26673 | |
b71d4b62 | 26674 | @code{Preelaborable_Initialization} |
64d5610f | 26675 | |
b71d4b62 | 26676 | @tab |
64d5610f | 26677 | |
b71d4b62 | 26678 | @item |
64d5610f | 26679 | |
b71d4b62 | 26680 | @code{Pure_Function} |
64d5610f | 26681 | |
b71d4b62 | 26682 | @tab |
64d5610f | 26683 | |
b71d4b62 | 26684 | – GNAT |
64d5610f | 26685 | |
b71d4b62 | 26686 | @item |
64d5610f | 26687 | |
b71d4b62 | 26688 | @code{Remote_Access_Type} |
64d5610f | 26689 | |
b71d4b62 | 26690 | @tab |
64d5610f | 26691 | |
b71d4b62 | 26692 | – GNAT |
64d5610f | 26693 | |
b71d4b62 | 26694 | @item |
64d5610f | 26695 | |
b71d4b62 | 26696 | @code{Shared} |
64d5610f | 26697 | |
b71d4b62 | 26698 | @tab |
64d5610f | 26699 | |
b71d4b62 | 26700 | – GNAT |
64d5610f | 26701 | |
b71d4b62 | 26702 | @item |
64d5610f | 26703 | |
b71d4b62 RA |
26704 | @code{Size} |
26705 | ||
26706 | @tab | |
64d5610f | 26707 | |
b71d4b62 | 26708 | @item |
64d5610f | 26709 | |
b71d4b62 | 26710 | @code{Storage_Pool} |
64d5610f | 26711 | |
b71d4b62 | 26712 | @tab |
64d5610f | 26713 | |
b71d4b62 | 26714 | @item |
64d5610f | 26715 | |
b71d4b62 | 26716 | @code{Storage_Size} |
64d5610f | 26717 | |
b71d4b62 | 26718 | @tab |
64d5610f | 26719 | |
b71d4b62 | 26720 | @item |
64d5610f | 26721 | |
b71d4b62 | 26722 | @code{Stream_Size} |
64d5610f | 26723 | |
b71d4b62 | 26724 | @tab |
64d5610f | 26725 | |
b71d4b62 | 26726 | @item |
64d5610f | 26727 | |
b71d4b62 | 26728 | @code{Suppress} |
64d5610f | 26729 | |
b71d4b62 | 26730 | @tab |
64d5610f | 26731 | |
b71d4b62 | 26732 | @item |
64d5610f | 26733 | |
b71d4b62 | 26734 | @code{Suppress_Debug_Info} |
64d5610f | 26735 | |
b71d4b62 | 26736 | @tab |
64d5610f | 26737 | |
b71d4b62 | 26738 | – GNAT |
64d5610f | 26739 | |
b71d4b62 | 26740 | @item |
64d5610f | 26741 | |
b71d4b62 | 26742 | @code{Test_Case} |
64d5610f | 26743 | |
b71d4b62 | 26744 | @tab |
64d5610f | 26745 | |
b71d4b62 | 26746 | – GNAT |
64d5610f | 26747 | |
b71d4b62 | 26748 | @item |
64d5610f | 26749 | |
b71d4b62 | 26750 | @code{Thread_Local_Storage} |
64d5610f | 26751 | |
b71d4b62 | 26752 | @tab |
64d5610f | 26753 | |
b71d4b62 | 26754 | – GNAT |
64d5610f | 26755 | |
b71d4b62 | 26756 | @item |
64d5610f | 26757 | |
b71d4b62 | 26758 | @code{Type_Invariant} |
64d5610f | 26759 | |
b71d4b62 | 26760 | @tab |
64d5610f | 26761 | |
b71d4b62 | 26762 | @item |
64d5610f | 26763 | |
b71d4b62 | 26764 | @code{Unchecked_Union} |
64d5610f | 26765 | |
b71d4b62 | 26766 | @tab |
64d5610f | 26767 | |
b71d4b62 | 26768 | @item |
64d5610f | 26769 | |
b71d4b62 | 26770 | @code{Universal_Aliasing} |
64d5610f | 26771 | |
b71d4b62 | 26772 | @tab |
64d5610f | 26773 | |
b71d4b62 | 26774 | – GNAT |
64d5610f | 26775 | |
b71d4b62 | 26776 | @item |
64d5610f | 26777 | |
b71d4b62 | 26778 | @code{Unmodified} |
64d5610f | 26779 | |
b71d4b62 | 26780 | @tab |
64d5610f | 26781 | |
b71d4b62 | 26782 | – GNAT |
64d5610f | 26783 | |
b71d4b62 | 26784 | @item |
64d5610f | 26785 | |
b71d4b62 | 26786 | @code{Unreferenced} |
64d5610f | 26787 | |
b71d4b62 | 26788 | @tab |
64d5610f | 26789 | |
b71d4b62 | 26790 | – GNAT |
64d5610f | 26791 | |
b71d4b62 | 26792 | @item |
64d5610f | 26793 | |
b71d4b62 | 26794 | @code{Unreferenced_Objects} |
64d5610f | 26795 | |
b71d4b62 | 26796 | @tab |
64d5610f | 26797 | |
b71d4b62 | 26798 | – GNAT |
64d5610f | 26799 | |
b71d4b62 | 26800 | @item |
64d5610f | 26801 | |
b71d4b62 | 26802 | @code{Unsuppress} |
64d5610f | 26803 | |
b71d4b62 | 26804 | @tab |
64d5610f | 26805 | |
b71d4b62 | 26806 | @item |
64d5610f | 26807 | |
b71d4b62 | 26808 | @code{Value_Size} |
64d5610f | 26809 | |
b71d4b62 | 26810 | @tab |
64d5610f | 26811 | |
b71d4b62 | 26812 | – GNAT |
64d5610f | 26813 | |
b71d4b62 | 26814 | @item |
64d5610f | 26815 | |
b71d4b62 | 26816 | @code{Volatile} |
64d5610f | 26817 | |
b71d4b62 | 26818 | @tab |
64d5610f | 26819 | |
b71d4b62 | 26820 | @item |
64d5610f | 26821 | |
b71d4b62 | 26822 | @code{Volatile_Components} |
64d5610f | 26823 | |
b71d4b62 | 26824 | @tab |
64d5610f | 26825 | |
b71d4b62 | 26826 | @item |
64d5610f | 26827 | |
b71d4b62 | 26828 | @code{Warnings} |
64d5610f | 26829 | |
b71d4b62 | 26830 | @tab |
64d5610f | 26831 | |
b71d4b62 | 26832 | – GNAT |
64d5610f | 26833 | |
b71d4b62 | 26834 | @end multitable |
64d5610f | 26835 | |
64d5610f | 26836 | |
b71d4b62 | 26837 | @quotation |
64d5610f | 26838 | |
b71d4b62 RA |
26839 | Note that for aspects with an expression, e.g. @code{Size}, the expression is |
26840 | treated like a default expression (visibility is analyzed at the point of | |
26841 | occurrence of the aspect, but evaluation of the expression occurs at the | |
26842 | freeze point of the entity involved). | |
64d5610f | 26843 | |
b71d4b62 RA |
26844 | RM References: 3.02.01 (3) 3.02.02 (2) 3.03.01 (2/2) 3.08 (6) |
26845 | 3.09.03 (1.1/2) 6.01 (2/2) 6.07 (2/2) 9.05.02 (2/2) 7.01 (3) 7.03 | |
26846 | (2) 7.03 (3) 9.01 (2/2) 9.01 (3/2) 9.04 (2/2) 9.04 (3/2) | |
26847 | 9.05.02 (2/2) 11.01 (2) 12.01 (3) 12.03 (2/2) 12.04 (2/2) 12.05 (2) | |
26848 | 12.06 (2.1/2) 12.06 (2.2/2) 12.07 (2) 13.01 (0.1/2) 13.03 (5/1) | |
26849 | 13.03.01 (0) | |
26850 | @end quotation | |
64d5610f | 26851 | |
b71d4b62 | 26852 | @geindex AI-0128 (Ada 2012 feature) |
64d5610f ML |
26853 | |
26854 | ||
26855 | @itemize * | |
26856 | ||
26857 | @item | |
b71d4b62 | 26858 | `AI-0128 Inequality is a primitive operation (0000-00-00)' |
64d5610f | 26859 | |
b71d4b62 RA |
26860 | If an equality operator (“=”) is declared for a type, then the implicitly |
26861 | declared inequality operator (“/=”) is a primitive operation of the type. | |
26862 | This is the only reasonable interpretation, and is the one always implemented | |
26863 | by GNAT, but the RM was not entirely clear in making this point. | |
64d5610f | 26864 | |
b71d4b62 | 26865 | RM References: 3.02.03 (6) 6.06 (6) |
64d5610f ML |
26866 | @end itemize |
26867 | ||
b71d4b62 | 26868 | @geindex AI-0003 (Ada 2012 feature) |
64d5610f ML |
26869 | |
26870 | ||
26871 | @itemize * | |
26872 | ||
26873 | @item | |
b71d4b62 | 26874 | `AI-0003 Qualified expressions as names (2010-07-11)' |
64d5610f | 26875 | |
b71d4b62 RA |
26876 | In Ada 2012, a qualified expression is considered to be syntactically a name, |
26877 | meaning that constructs such as @code{A'(F(X)).B} are now legal. This is | |
26878 | useful in disambiguating some cases of overloading. | |
64d5610f | 26879 | |
b71d4b62 RA |
26880 | RM References: 3.03 (11) 3.03 (21) 4.01 (2) 4.04 (7) 4.07 (3) |
26881 | 5.04 (7) | |
64d5610f ML |
26882 | @end itemize |
26883 | ||
b71d4b62 | 26884 | @geindex AI-0120 (Ada 2012 feature) |
64d5610f ML |
26885 | |
26886 | ||
26887 | @itemize * | |
26888 | ||
26889 | @item | |
b71d4b62 | 26890 | `AI-0120 Constant instance of protected object (0000-00-00)' |
64d5610f | 26891 | |
b71d4b62 RA |
26892 | This is an RM editorial change only. The section that lists objects that are |
26893 | constant failed to include the current instance of a protected object | |
26894 | within a protected function. This has always been treated as a constant | |
26895 | in GNAT. | |
64d5610f | 26896 | |
b71d4b62 | 26897 | RM References: 3.03 (21) |
64d5610f ML |
26898 | @end itemize |
26899 | ||
b71d4b62 | 26900 | @geindex AI-0008 (Ada 2012 feature) |
64d5610f ML |
26901 | |
26902 | ||
26903 | @itemize * | |
26904 | ||
26905 | @item | |
b71d4b62 | 26906 | `AI-0008 General access to constrained objects (0000-00-00)' |
64d5610f | 26907 | |
b71d4b62 RA |
26908 | The wording in the RM implied that if you have a general access to a |
26909 | constrained object, it could be used to modify the discriminants. This was | |
26910 | obviously not intended. @code{Constraint_Error} should be raised, and GNAT | |
26911 | has always done so in this situation. | |
64d5610f | 26912 | |
b71d4b62 RA |
26913 | RM References: 3.03 (23) 3.10.02 (26/2) 4.01 (9) 6.04.01 (17) 8.05.01 (5/2) |
26914 | @end itemize | |
64d5610f | 26915 | |
b71d4b62 | 26916 | @geindex AI-0093 (Ada 2012 feature) |
64d5610f | 26917 | |
64d5610f | 26918 | |
b71d4b62 | 26919 | @itemize * |
64d5610f | 26920 | |
b71d4b62 RA |
26921 | @item |
26922 | `AI-0093 Additional rules use immutably limited (0000-00-00)' | |
64d5610f | 26923 | |
b71d4b62 RA |
26924 | This is an editorial change only, to make more widespread use of the Ada 2012 |
26925 | ‘immutably limited’. | |
64d5610f | 26926 | |
b71d4b62 RA |
26927 | RM References: 3.03 (23.4/3) |
26928 | @end itemize | |
64d5610f | 26929 | |
b71d4b62 | 26930 | @geindex AI-0096 (Ada 2012 feature) |
64d5610f | 26931 | |
64d5610f | 26932 | |
b71d4b62 | 26933 | @itemize * |
64d5610f | 26934 | |
b71d4b62 RA |
26935 | @item |
26936 | `AI-0096 Deriving from formal private types (2010-07-20)' | |
64d5610f | 26937 | |
b71d4b62 RA |
26938 | In general it is illegal for a type derived from a formal limited type to be |
26939 | nonlimited. This AI makes an exception to this rule: derivation is legal | |
26940 | if it appears in the private part of the generic, and the formal type is not | |
26941 | tagged. If the type is tagged, the legality check must be applied to the | |
26942 | private part of the package. | |
64d5610f | 26943 | |
b71d4b62 RA |
26944 | RM References: 3.04 (5.1/2) 6.02 (7) |
26945 | @end itemize | |
64d5610f | 26946 | |
b71d4b62 | 26947 | @geindex AI-0181 (Ada 2012 feature) |
64d5610f | 26948 | |
64d5610f | 26949 | |
b71d4b62 | 26950 | @itemize * |
64d5610f | 26951 | |
b71d4b62 RA |
26952 | @item |
26953 | `AI-0181 Soft hyphen is a non-graphic character (2010-07-23)' | |
64d5610f | 26954 | |
b71d4b62 RA |
26955 | From Ada 2005 on, soft hyphen is considered a non-graphic character, which |
26956 | means that it has a special name (@code{SOFT_HYPHEN}) in conjunction with the | |
26957 | @code{Image} and @code{Value} attributes for the character types. Strictly | |
26958 | speaking this is an inconsistency with Ada 95, but in practice the use of | |
26959 | these attributes is so obscure that it will not cause problems. | |
64d5610f | 26960 | |
b71d4b62 RA |
26961 | RM References: 3.05.02 (2/2) A.01 (35/2) A.03.03 (21) |
26962 | @end itemize | |
64d5610f | 26963 | |
b71d4b62 | 26964 | @geindex AI-0182 (Ada 2012 feature) |
64d5610f | 26965 | |
64d5610f | 26966 | |
b71d4b62 | 26967 | @itemize * |
64d5610f | 26968 | |
b71d4b62 RA |
26969 | @item |
26970 | `AI-0182 Additional forms for' @code{Character'Value} `(0000-00-00)' | |
64d5610f | 26971 | |
b71d4b62 RA |
26972 | This AI allows @code{Character'Value} to accept the string @code{'?'} where |
26973 | @code{?} is any character including non-graphic control characters. GNAT has | |
26974 | always accepted such strings. It also allows strings such as | |
26975 | @code{HEX_00000041} to be accepted, but GNAT does not take advantage of this | |
26976 | permission and raises @code{Constraint_Error}, as is certainly still | |
26977 | permitted. | |
64d5610f | 26978 | |
b71d4b62 RA |
26979 | RM References: 3.05 (56/2) |
26980 | @end itemize | |
64d5610f | 26981 | |
b71d4b62 | 26982 | @geindex AI-0214 (Ada 2012 feature) |
64d5610f | 26983 | |
64d5610f | 26984 | |
b71d4b62 | 26985 | @itemize * |
64d5610f | 26986 | |
b71d4b62 RA |
26987 | @item |
26988 | `AI-0214 Defaulted discriminants for limited tagged (2010-10-01)' | |
64d5610f | 26989 | |
b71d4b62 RA |
26990 | Ada 2012 relaxes the restriction that forbids discriminants of tagged types |
26991 | to have default expressions by allowing them when the type is limited. It | |
26992 | is often useful to define a default value for a discriminant even though | |
26993 | it can’t be changed by assignment. | |
64d5610f | 26994 | |
b71d4b62 RA |
26995 | RM References: 3.07 (9.1/2) 3.07.02 (3) |
26996 | @end itemize | |
64d5610f | 26997 | |
b71d4b62 | 26998 | @geindex AI-0102 (Ada 2012 feature) |
64d5610f | 26999 | |
64d5610f | 27000 | |
b71d4b62 | 27001 | @itemize * |
64d5610f | 27002 | |
b71d4b62 RA |
27003 | @item |
27004 | `AI-0102 Some implicit conversions are illegal (0000-00-00)' | |
64d5610f | 27005 | |
b71d4b62 RA |
27006 | It is illegal to assign an anonymous access constant to an anonymous access |
27007 | variable. The RM did not have a clear rule to prevent this, but GNAT has | |
27008 | always generated an error for this usage. | |
64d5610f | 27009 | |
b71d4b62 RA |
27010 | RM References: 3.07 (16) 3.07.01 (9) 6.04.01 (6) 8.06 (27/2) |
27011 | @end itemize | |
64d5610f | 27012 | |
b71d4b62 | 27013 | @geindex AI-0158 (Ada 2012 feature) |
64d5610f | 27014 | |
64d5610f | 27015 | |
b71d4b62 | 27016 | @itemize * |
64d5610f | 27017 | |
b71d4b62 RA |
27018 | @item |
27019 | `AI-0158 Generalizing membership tests (2010-09-16)' | |
64d5610f | 27020 | |
b71d4b62 RA |
27021 | This AI extends the syntax of membership tests to simplify complex conditions |
27022 | that can be expressed as membership in a subset of values of any type. It | |
27023 | introduces syntax for a list of expressions that may be used in loop contexts | |
27024 | as well. | |
64d5610f | 27025 | |
b71d4b62 RA |
27026 | RM References: 3.08.01 (5) 4.04 (3) 4.05.02 (3) 4.05.02 (5) 4.05.02 (27) |
27027 | @end itemize | |
64d5610f | 27028 | |
b71d4b62 | 27029 | @geindex AI-0173 (Ada 2012 feature) |
64d5610f | 27030 | |
64d5610f | 27031 | |
b71d4b62 | 27032 | @itemize * |
64d5610f | 27033 | |
b71d4b62 RA |
27034 | @item |
27035 | `AI-0173 Testing if tags represent abstract types (2010-07-03)' | |
64d5610f | 27036 | |
b71d4b62 RA |
27037 | The function @code{Ada.Tags.Type_Is_Abstract} returns @code{True} if invoked |
27038 | with the tag of an abstract type, and @code{False} otherwise. | |
64d5610f | 27039 | |
b71d4b62 RA |
27040 | RM References: 3.09 (7.4/2) 3.09 (12.4/2) |
27041 | @end itemize | |
64d5610f | 27042 | |
b71d4b62 | 27043 | @geindex AI-0076 (Ada 2012 feature) |
64d5610f | 27044 | |
64d5610f | 27045 | |
b71d4b62 | 27046 | @itemize * |
64d5610f | 27047 | |
b71d4b62 RA |
27048 | @item |
27049 | `AI-0076 function with controlling result (0000-00-00)' | |
64d5610f | 27050 | |
b71d4b62 RA |
27051 | This is an editorial change only. The RM defines calls with controlling |
27052 | results, but uses the term ‘function with controlling result’ without an | |
27053 | explicit definition. | |
64d5610f | 27054 | |
b71d4b62 RA |
27055 | RM References: 3.09.02 (2/2) |
27056 | @end itemize | |
64d5610f | 27057 | |
b71d4b62 | 27058 | @geindex AI-0126 (Ada 2012 feature) |
64d5610f | 27059 | |
64d5610f | 27060 | |
b71d4b62 | 27061 | @itemize * |
64d5610f | 27062 | |
b71d4b62 RA |
27063 | @item |
27064 | `AI-0126 Dispatching with no declared operation (0000-00-00)' | |
64d5610f | 27065 | |
b71d4b62 RA |
27066 | This AI clarifies dispatching rules, and simply confirms that dispatching |
27067 | executes the operation of the parent type when there is no explicitly or | |
27068 | implicitly declared operation for the descendant type. This has always been | |
27069 | the case in all versions of GNAT. | |
64d5610f | 27070 | |
b71d4b62 RA |
27071 | RM References: 3.09.02 (20/2) 3.09.02 (20.1/2) 3.09.02 (20.2/2) |
27072 | @end itemize | |
64d5610f | 27073 | |
b71d4b62 | 27074 | @geindex AI-0097 (Ada 2012 feature) |
64d5610f | 27075 | |
64d5610f | 27076 | |
b71d4b62 | 27077 | @itemize * |
64d5610f | 27078 | |
b71d4b62 RA |
27079 | @item |
27080 | `AI-0097 Treatment of abstract null extension (2010-07-19)' | |
64d5610f | 27081 | |
b71d4b62 RA |
27082 | The RM as written implied that in some cases it was possible to create an |
27083 | object of an abstract type, by having an abstract extension inherit a non- | |
27084 | abstract constructor from its parent type. This mistake has been corrected | |
27085 | in GNAT and in the RM, and this construct is now illegal. | |
64d5610f | 27086 | |
b71d4b62 RA |
27087 | RM References: 3.09.03 (4/2) |
27088 | @end itemize | |
64d5610f | 27089 | |
b71d4b62 | 27090 | @geindex AI-0203 (Ada 2012 feature) |
64d5610f | 27091 | |
64d5610f | 27092 | |
b71d4b62 | 27093 | @itemize * |
64d5610f | 27094 | |
b71d4b62 RA |
27095 | @item |
27096 | `AI-0203 Extended return cannot be abstract (0000-00-00)' | |
64d5610f | 27097 | |
b71d4b62 RA |
27098 | A return_subtype_indication cannot denote an abstract subtype. GNAT has never |
27099 | permitted such usage. | |
64d5610f | 27100 | |
b71d4b62 RA |
27101 | RM References: 3.09.03 (8/3) |
27102 | @end itemize | |
64d5610f | 27103 | |
b71d4b62 | 27104 | @geindex AI-0198 (Ada 2012 feature) |
64d5610f | 27105 | |
64d5610f | 27106 | |
b71d4b62 | 27107 | @itemize * |
64d5610f | 27108 | |
b71d4b62 RA |
27109 | @item |
27110 | `AI-0198 Inheriting abstract operators (0000-00-00)' | |
64d5610f | 27111 | |
b71d4b62 RA |
27112 | This AI resolves a conflict between two rules involving inherited abstract |
27113 | operations and predefined operators. If a derived numeric type inherits | |
27114 | an abstract operator, it overrides the predefined one. This interpretation | |
27115 | was always the one implemented in GNAT. | |
64d5610f | 27116 | |
b71d4b62 RA |
27117 | RM References: 3.09.03 (4/3) |
27118 | @end itemize | |
64d5610f | 27119 | |
b71d4b62 | 27120 | @geindex AI-0073 (Ada 2012 feature) |
64d5610f | 27121 | |
64d5610f | 27122 | |
b71d4b62 | 27123 | @itemize * |
64d5610f | 27124 | |
b71d4b62 RA |
27125 | @item |
27126 | `AI-0073 Functions returning abstract types (2010-07-10)' | |
64d5610f | 27127 | |
b71d4b62 RA |
27128 | This AI covers a number of issues regarding returning abstract types. In |
27129 | particular generic functions cannot have abstract result types or access | |
27130 | result types designated an abstract type. There are some other cases which | |
27131 | are detailed in the AI. Note that this binding interpretation has not been | |
27132 | retrofitted to operate before Ada 2012 mode, since it caused a significant | |
27133 | number of regressions. | |
64d5610f | 27134 | |
b71d4b62 RA |
27135 | RM References: 3.09.03 (8) 3.09.03 (10) 6.05 (8/2) |
27136 | @end itemize | |
64d5610f | 27137 | |
b71d4b62 | 27138 | @geindex AI-0070 (Ada 2012 feature) |
64d5610f | 27139 | |
64d5610f | 27140 | |
b71d4b62 | 27141 | @itemize * |
64d5610f | 27142 | |
b71d4b62 RA |
27143 | @item |
27144 | `AI-0070 Elaboration of interface types (0000-00-00)' | |
64d5610f | 27145 | |
b71d4b62 RA |
27146 | This is an editorial change only, there are no testable consequences short of |
27147 | checking for the absence of generated code for an interface declaration. | |
64d5610f | 27148 | |
b71d4b62 RA |
27149 | RM References: 3.09.04 (18/2) |
27150 | @end itemize | |
64d5610f | 27151 | |
b71d4b62 | 27152 | @geindex AI-0208 (Ada 2012 feature) |
64d5610f | 27153 | |
64d5610f | 27154 | |
b71d4b62 | 27155 | @itemize * |
64d5610f | 27156 | |
b71d4b62 RA |
27157 | @item |
27158 | `AI-0208 Characteristics of incomplete views (0000-00-00)' | |
64d5610f | 27159 | |
b71d4b62 RA |
27160 | The wording in the Ada 2005 RM concerning characteristics of incomplete views |
27161 | was incorrect and implied that some programs intended to be legal were now | |
27162 | illegal. GNAT had never considered such programs illegal, so it has always | |
27163 | implemented the intent of this AI. | |
64d5610f | 27164 | |
b71d4b62 RA |
27165 | RM References: 3.10.01 (2.4/2) 3.10.01 (2.6/2) |
27166 | @end itemize | |
64d5610f | 27167 | |
b71d4b62 | 27168 | @geindex AI-0162 (Ada 2012 feature) |
64d5610f | 27169 | |
64d5610f | 27170 | |
b71d4b62 | 27171 | @itemize * |
64d5610f | 27172 | |
b71d4b62 RA |
27173 | @item |
27174 | `AI-0162 Incomplete type completed by partial view (2010-09-15)' | |
64d5610f | 27175 | |
b71d4b62 RA |
27176 | Incomplete types are made more useful by allowing them to be completed by |
27177 | private types and private extensions. | |
64d5610f | 27178 | |
b71d4b62 RA |
27179 | RM References: 3.10.01 (2.5/2) 3.10.01 (2.6/2) 3.10.01 (3) 3.10.01 (4/2) |
27180 | @end itemize | |
64d5610f | 27181 | |
b71d4b62 | 27182 | @geindex AI-0098 (Ada 2012 feature) |
64d5610f | 27183 | |
64d5610f | 27184 | |
b71d4b62 | 27185 | @itemize * |
64d5610f | 27186 | |
b71d4b62 RA |
27187 | @item |
27188 | `AI-0098 Anonymous subprogram access restrictions (0000-00-00)' | |
64d5610f | 27189 | |
b71d4b62 RA |
27190 | An unintentional omission in the RM implied some inconsistent restrictions on |
27191 | the use of anonymous access to subprogram values. These restrictions were not | |
27192 | intentional, and have never been enforced by GNAT. | |
64d5610f | 27193 | |
b71d4b62 RA |
27194 | RM References: 3.10.01 (6) 3.10.01 (9.2/2) |
27195 | @end itemize | |
64d5610f | 27196 | |
b71d4b62 | 27197 | @geindex AI-0199 (Ada 2012 feature) |
64d5610f | 27198 | |
64d5610f | 27199 | |
b71d4b62 | 27200 | @itemize * |
64d5610f | 27201 | |
b71d4b62 RA |
27202 | @item |
27203 | `AI-0199 Aggregate with anonymous access components (2010-07-14)' | |
64d5610f | 27204 | |
b71d4b62 RA |
27205 | A choice list in a record aggregate can include several components of |
27206 | (distinct) anonymous access types as long as they have matching designated | |
27207 | subtypes. | |
64d5610f | 27208 | |
b71d4b62 RA |
27209 | RM References: 4.03.01 (16) |
27210 | @end itemize | |
64d5610f | 27211 | |
b71d4b62 | 27212 | @geindex AI-0220 (Ada 2012 feature) |
64d5610f | 27213 | |
64d5610f | 27214 | |
b71d4b62 | 27215 | @itemize * |
64d5610f | 27216 | |
b71d4b62 RA |
27217 | @item |
27218 | `AI-0220 Needed components for aggregates (0000-00-00)' | |
64d5610f | 27219 | |
b71d4b62 RA |
27220 | This AI addresses a wording problem in the RM that appears to permit some |
27221 | complex cases of aggregates with nonstatic discriminants. GNAT has always | |
27222 | implemented the intended semantics. | |
64d5610f | 27223 | |
b71d4b62 RA |
27224 | RM References: 4.03.01 (17) |
27225 | @end itemize | |
64d5610f | 27226 | |
b71d4b62 | 27227 | @geindex AI-0147 (Ada 2012 feature) |
64d5610f | 27228 | |
64d5610f | 27229 | |
b71d4b62 | 27230 | @itemize * |
64d5610f | 27231 | |
b71d4b62 RA |
27232 | @item |
27233 | `AI-0147 Conditional expressions (2009-03-29)' | |
64d5610f | 27234 | |
b71d4b62 | 27235 | Conditional expressions are permitted. The form of such an expression is: |
64d5610f | 27236 | |
b71d4b62 RA |
27237 | @example |
27238 | (if expr then expr @{elsif expr then expr@} [else expr]) | |
27239 | @end example | |
64d5610f | 27240 | |
b71d4b62 RA |
27241 | The parentheses can be omitted in contexts where parentheses are present |
27242 | anyway, such as subprogram arguments and pragma arguments. If the `else' | |
27243 | clause is omitted, `else' `True' is assumed; | |
27244 | thus @code{(if A then B)} is a way to conveniently represent | |
27245 | `(A implies B)' in standard logic. | |
64d5610f | 27246 | |
b71d4b62 RA |
27247 | RM References: 4.03.03 (15) 4.04 (1) 4.04 (7) 4.05.07 (0) 4.07 (2) |
27248 | 4.07 (3) 4.09 (12) 4.09 (33) 5.03 (3) 5.03 (4) 7.05 (2.1/2) | |
27249 | @end itemize | |
64d5610f | 27250 | |
b71d4b62 | 27251 | @geindex AI-0037 (Ada 2012 feature) |
64d5610f | 27252 | |
64d5610f | 27253 | |
b71d4b62 | 27254 | @itemize * |
64d5610f | 27255 | |
b71d4b62 RA |
27256 | @item |
27257 | `AI-0037 Out-of-range box associations in aggregate (0000-00-00)' | |
64d5610f | 27258 | |
b71d4b62 RA |
27259 | This AI confirms that an association of the form @code{Indx => <>} in an |
27260 | array aggregate must raise @code{Constraint_Error} if @code{Indx} | |
27261 | is out of range. The RM specified a range check on other associations, but | |
27262 | not when the value of the association was defaulted. GNAT has always inserted | |
27263 | a constraint check on the index value. | |
64d5610f | 27264 | |
b71d4b62 RA |
27265 | RM References: 4.03.03 (29) |
27266 | @end itemize | |
64d5610f | 27267 | |
b71d4b62 | 27268 | @geindex AI-0123 (Ada 2012 feature) |
64d5610f | 27269 | |
64d5610f | 27270 | |
b71d4b62 | 27271 | @itemize * |
64d5610f | 27272 | |
b71d4b62 RA |
27273 | @item |
27274 | `AI-0123 Composability of equality (2010-04-13)' | |
64d5610f | 27275 | |
b71d4b62 RA |
27276 | Equality of untagged record composes, so that the predefined equality for a |
27277 | composite type that includes a component of some untagged record type | |
27278 | @code{R} uses the equality operation of @code{R} (which may be user-defined | |
27279 | or predefined). This makes the behavior of untagged records identical to that | |
27280 | of tagged types in this respect. | |
64d5610f | 27281 | |
b71d4b62 RA |
27282 | This change is an incompatibility with previous versions of Ada, but it |
27283 | corrects a non-uniformity that was often a source of confusion. Analysis of | |
27284 | a large number of industrial programs indicates that in those rare cases | |
27285 | where a composite type had an untagged record component with a user-defined | |
27286 | equality, either there was no use of the composite equality, or else the code | |
27287 | expected the same composability as for tagged types, and thus had a bug that | |
27288 | would be fixed by this change. | |
64d5610f | 27289 | |
b71d4b62 RA |
27290 | RM References: 4.05.02 (9.7/2) 4.05.02 (14) 4.05.02 (15) 4.05.02 (24) |
27291 | 8.05.04 (8) | |
27292 | @end itemize | |
64d5610f | 27293 | |
b71d4b62 | 27294 | @geindex AI-0088 (Ada 2012 feature) |
64d5610f | 27295 | |
64d5610f | 27296 | |
b71d4b62 | 27297 | @itemize * |
64d5610f | 27298 | |
b71d4b62 RA |
27299 | @item |
27300 | `AI-0088 The value of exponentiation (0000-00-00)' | |
64d5610f | 27301 | |
b71d4b62 RA |
27302 | This AI clarifies the equivalence rule given for the dynamic semantics of |
27303 | exponentiation: the value of the operation can be obtained by repeated | |
27304 | multiplication, but the operation can be implemented otherwise (for example | |
27305 | using the familiar divide-by-two-and-square algorithm, even if this is less | |
27306 | accurate), and does not imply repeated reads of a volatile base. | |
64d5610f | 27307 | |
b71d4b62 RA |
27308 | RM References: 4.05.06 (11) |
27309 | @end itemize | |
64d5610f | 27310 | |
b71d4b62 | 27311 | @geindex AI-0188 (Ada 2012 feature) |
64d5610f | 27312 | |
64d5610f | 27313 | |
b71d4b62 | 27314 | @itemize * |
64d5610f | 27315 | |
b71d4b62 RA |
27316 | @item |
27317 | `AI-0188 Case expressions (2010-01-09)' | |
64d5610f | 27318 | |
b71d4b62 | 27319 | Case expressions are permitted. This allows use of constructs such as: |
64d5610f | 27320 | |
b71d4b62 RA |
27321 | @example |
27322 | X := (case Y is when 1 => 2, when 2 => 3, when others => 31) | |
27323 | @end example | |
64d5610f | 27324 | |
b71d4b62 RA |
27325 | RM References: 4.05.07 (0) 4.05.08 (0) 4.09 (12) 4.09 (33) |
27326 | @end itemize | |
64d5610f | 27327 | |
b71d4b62 | 27328 | @geindex AI-0104 (Ada 2012 feature) |
64d5610f ML |
27329 | |
27330 | ||
27331 | @itemize * | |
27332 | ||
27333 | @item | |
b71d4b62 | 27334 | `AI-0104 Null exclusion and uninitialized allocator (2010-07-15)' |
64d5610f | 27335 | |
b71d4b62 RA |
27336 | The assignment @code{Ptr := new not null Some_Ptr;} will raise |
27337 | @code{Constraint_Error} because the default value of the allocated object is | |
27338 | `null'. This useless construct is illegal in Ada 2012. | |
64d5610f | 27339 | |
b71d4b62 | 27340 | RM References: 4.08 (2) |
64d5610f ML |
27341 | @end itemize |
27342 | ||
b71d4b62 | 27343 | @geindex AI-0157 (Ada 2012 feature) |
64d5610f ML |
27344 | |
27345 | ||
27346 | @itemize * | |
27347 | ||
27348 | @item | |
b71d4b62 | 27349 | `AI-0157 Allocation/Deallocation from empty pool (2010-07-11)' |
64d5610f | 27350 | |
b71d4b62 RA |
27351 | Allocation and Deallocation from an empty storage pool (i.e. allocation or |
27352 | deallocation of a pointer for which a static storage size clause of zero | |
27353 | has been given) is now illegal and is detected as such. GNAT | |
27354 | previously gave a warning but not an error. | |
64d5610f | 27355 | |
b71d4b62 | 27356 | RM References: 4.08 (5.3/2) 13.11.02 (4) 13.11.02 (17) |
64d5610f ML |
27357 | @end itemize |
27358 | ||
b71d4b62 | 27359 | @geindex AI-0179 (Ada 2012 feature) |
64d5610f ML |
27360 | |
27361 | ||
27362 | @itemize * | |
27363 | ||
27364 | @item | |
b71d4b62 | 27365 | `AI-0179 Statement not required after label (2010-04-10)' |
64d5610f | 27366 | |
b71d4b62 RA |
27367 | It is not necessary to have a statement following a label, so a label |
27368 | can appear at the end of a statement sequence without the need for putting a | |
27369 | null statement afterwards, but it is not allowable to have only labels and | |
27370 | no real statements in a statement sequence. | |
64d5610f | 27371 | |
b71d4b62 | 27372 | RM References: 5.01 (2) |
64d5610f ML |
27373 | @end itemize |
27374 | ||
b71d4b62 | 27375 | @geindex AI-0139-2 (Ada 2012 feature) |
64d5610f ML |
27376 | |
27377 | ||
27378 | @itemize * | |
27379 | ||
27380 | @item | |
b71d4b62 | 27381 | `AI-0139-2 Syntactic sugar for iterators (2010-09-29)' |
64d5610f | 27382 | |
b71d4b62 RA |
27383 | The new syntax for iterating over arrays and containers is now implemented. |
27384 | Iteration over containers is for now limited to read-only iterators. Only | |
27385 | default iterators are supported, with the syntax: @code{for Elem of C}. | |
64d5610f | 27386 | |
b71d4b62 | 27387 | RM References: 5.05 |
64d5610f ML |
27388 | @end itemize |
27389 | ||
b71d4b62 | 27390 | @geindex AI-0134 (Ada 2012 feature) |
64d5610f ML |
27391 | |
27392 | ||
27393 | @itemize * | |
27394 | ||
27395 | @item | |
b71d4b62 | 27396 | `AI-0134 Profiles must match for full conformance (0000-00-00)' |
64d5610f | 27397 | |
b71d4b62 RA |
27398 | For full conformance, the profiles of anonymous-access-to-subprogram |
27399 | parameters must match. GNAT has always enforced this rule. | |
64d5610f | 27400 | |
b71d4b62 | 27401 | RM References: 6.03.01 (18) |
64d5610f ML |
27402 | @end itemize |
27403 | ||
b71d4b62 | 27404 | @geindex AI-0207 (Ada 2012 feature) |
64d5610f ML |
27405 | |
27406 | ||
27407 | @itemize * | |
27408 | ||
27409 | @item | |
b71d4b62 | 27410 | `AI-0207 Mode conformance and access constant (0000-00-00)' |
64d5610f | 27411 | |
b71d4b62 RA |
27412 | This AI confirms that access_to_constant indication must match for mode |
27413 | conformance. This was implemented in GNAT when the qualifier was originally | |
27414 | introduced in Ada 2005. | |
64d5610f | 27415 | |
b71d4b62 | 27416 | RM References: 6.03.01 (16/2) |
64d5610f ML |
27417 | @end itemize |
27418 | ||
b71d4b62 | 27419 | @geindex AI-0046 (Ada 2012 feature) |
64d5610f ML |
27420 | |
27421 | ||
27422 | @itemize * | |
27423 | ||
27424 | @item | |
b71d4b62 | 27425 | `AI-0046 Null exclusion match for full conformance (2010-07-17)' |
64d5610f | 27426 | |
b71d4b62 RA |
27427 | For full conformance, in the case of access parameters, the null exclusion |
27428 | must match (either both or neither must have @code{not null}). | |
64d5610f | 27429 | |
b71d4b62 | 27430 | RM References: 6.03.02 (18) |
64d5610f ML |
27431 | @end itemize |
27432 | ||
b71d4b62 | 27433 | @geindex AI-0118 (Ada 2012 feature) |
64d5610f ML |
27434 | |
27435 | ||
27436 | @itemize * | |
27437 | ||
27438 | @item | |
b71d4b62 | 27439 | `AI-0118 The association of parameter associations (0000-00-00)' |
64d5610f | 27440 | |
b71d4b62 RA |
27441 | This AI clarifies the rules for named associations in subprogram calls and |
27442 | generic instantiations. The rules have been in place since Ada 83. | |
64d5610f | 27443 | |
b71d4b62 | 27444 | RM References: 6.04.01 (2) 12.03 (9) |
64d5610f ML |
27445 | @end itemize |
27446 | ||
b71d4b62 | 27447 | @geindex AI-0196 (Ada 2012 feature) |
64d5610f ML |
27448 | |
27449 | ||
27450 | @itemize * | |
27451 | ||
27452 | @item | |
b71d4b62 | 27453 | `AI-0196 Null exclusion tests for out parameters (0000-00-00)' |
64d5610f | 27454 | |
b71d4b62 RA |
27455 | Null exclusion checks are not made for @code{out} parameters when |
27456 | evaluating the actual parameters. GNAT has never generated these checks. | |
64d5610f | 27457 | |
b71d4b62 | 27458 | RM References: 6.04.01 (13) |
64d5610f ML |
27459 | @end itemize |
27460 | ||
b71d4b62 | 27461 | @geindex AI-0015 (Ada 2012 feature) |
64d5610f ML |
27462 | |
27463 | ||
27464 | @itemize * | |
27465 | ||
27466 | @item | |
b71d4b62 | 27467 | `AI-0015 Constant return objects (0000-00-00)' |
64d5610f | 27468 | |
b71d4b62 RA |
27469 | The return object declared in an `extended_return_statement' may be |
27470 | declared constant. This was always intended, and GNAT has always allowed it. | |
64d5610f | 27471 | |
b71d4b62 RA |
27472 | RM References: 6.05 (2.1/2) 3.03 (10/2) 3.03 (21) 6.05 (5/2) |
27473 | 6.05 (5.7/2) | |
64d5610f ML |
27474 | @end itemize |
27475 | ||
b71d4b62 | 27476 | @geindex AI-0032 (Ada 2012 feature) |
64d5610f ML |
27477 | |
27478 | ||
27479 | @itemize * | |
27480 | ||
27481 | @item | |
b71d4b62 | 27482 | `AI-0032 Extended return for class-wide functions (0000-00-00)' |
64d5610f | 27483 | |
b71d4b62 RA |
27484 | If a function returns a class-wide type, the object of an extended return |
27485 | statement can be declared with a specific type that is covered by the class- | |
27486 | wide type. This has been implemented in GNAT since the introduction of | |
27487 | extended returns. Note AI-0103 complements this AI by imposing matching | |
27488 | rules for constrained return types. | |
64d5610f | 27489 | |
b71d4b62 RA |
27490 | RM References: 6.05 (5.2/2) 6.05 (5.3/2) 6.05 (5.6/2) 6.05 (5.8/2) |
27491 | 6.05 (8/2) | |
64d5610f ML |
27492 | @end itemize |
27493 | ||
b71d4b62 | 27494 | @geindex AI-0103 (Ada 2012 feature) |
64d5610f ML |
27495 | |
27496 | ||
27497 | @itemize * | |
27498 | ||
27499 | @item | |
b71d4b62 | 27500 | `AI-0103 Static matching for extended return (2010-07-23)' |
64d5610f | 27501 | |
b71d4b62 RA |
27502 | If the return subtype of a function is an elementary type or a constrained |
27503 | type, the subtype indication in an extended return statement must match | |
27504 | statically this return subtype. | |
64d5610f | 27505 | |
b71d4b62 | 27506 | RM References: 6.05 (5.2/2) |
64d5610f ML |
27507 | @end itemize |
27508 | ||
b71d4b62 | 27509 | @geindex AI-0058 (Ada 2012 feature) |
64d5610f ML |
27510 | |
27511 | ||
27512 | @itemize * | |
27513 | ||
27514 | @item | |
b71d4b62 | 27515 | `AI-0058 Abnormal completion of an extended return (0000-00-00)' |
64d5610f | 27516 | |
b71d4b62 RA |
27517 | The RM had some incorrect wording implying wrong treatment of abnormal |
27518 | completion in an extended return. GNAT has always implemented the intended | |
27519 | correct semantics as described by this AI. | |
64d5610f | 27520 | |
b71d4b62 | 27521 | RM References: 6.05 (22/2) |
64d5610f ML |
27522 | @end itemize |
27523 | ||
b71d4b62 | 27524 | @geindex AI-0050 (Ada 2012 feature) |
64d5610f ML |
27525 | |
27526 | ||
27527 | @itemize * | |
27528 | ||
27529 | @item | |
b71d4b62 | 27530 | `AI-0050 Raising Constraint_Error early for function call (0000-00-00)' |
64d5610f | 27531 | |
b71d4b62 RA |
27532 | The implementation permissions for raising @code{Constraint_Error} early on a function call |
27533 | when it was clear an exception would be raised were over-permissive and allowed | |
27534 | mishandling of discriminants in some cases. GNAT did | |
27535 | not take advantage of these incorrect permissions in any case. | |
64d5610f | 27536 | |
b71d4b62 | 27537 | RM References: 6.05 (24/2) |
64d5610f ML |
27538 | @end itemize |
27539 | ||
b71d4b62 | 27540 | @geindex AI-0125 (Ada 2012 feature) |
64d5610f ML |
27541 | |
27542 | ||
27543 | @itemize * | |
27544 | ||
27545 | @item | |
b71d4b62 | 27546 | `AI-0125 Nonoverridable operations of an ancestor (2010-09-28)' |
64d5610f | 27547 | |
b71d4b62 RA |
27548 | In Ada 2012, the declaration of a primitive operation of a type extension |
27549 | or private extension can also override an inherited primitive that is not | |
27550 | visible at the point of this declaration. | |
64d5610f | 27551 | |
b71d4b62 | 27552 | RM References: 7.03.01 (6) 8.03 (23) 8.03.01 (5/2) 8.03.01 (6/2) |
64d5610f ML |
27553 | @end itemize |
27554 | ||
b71d4b62 | 27555 | @geindex AI-0062 (Ada 2012 feature) |
64d5610f ML |
27556 | |
27557 | ||
27558 | @itemize * | |
27559 | ||
27560 | @item | |
b71d4b62 | 27561 | `AI-0062 Null exclusions and deferred constants (0000-00-00)' |
64d5610f | 27562 | |
b71d4b62 RA |
27563 | A full constant may have a null exclusion even if its associated deferred |
27564 | constant does not. GNAT has always allowed this. | |
64d5610f | 27565 | |
b71d4b62 | 27566 | RM References: 7.04 (6/2) 7.04 (7.1/2) |
64d5610f ML |
27567 | @end itemize |
27568 | ||
b71d4b62 | 27569 | @geindex AI-0178 (Ada 2012 feature) |
64d5610f ML |
27570 | |
27571 | ||
27572 | @itemize * | |
27573 | ||
27574 | @item | |
b71d4b62 | 27575 | `AI-0178 Incomplete views are limited (0000-00-00)' |
64d5610f | 27576 | |
b71d4b62 RA |
27577 | This AI clarifies the role of incomplete views and plugs an omission in the |
27578 | RM. GNAT always correctly restricted the use of incomplete views and types. | |
64d5610f | 27579 | |
b71d4b62 | 27580 | RM References: 7.05 (3/2) 7.05 (6/2) |
64d5610f ML |
27581 | @end itemize |
27582 | ||
b71d4b62 | 27583 | @geindex AI-0087 (Ada 2012 feature) |
64d5610f ML |
27584 | |
27585 | ||
27586 | @itemize * | |
27587 | ||
27588 | @item | |
b71d4b62 | 27589 | `AI-0087 Actual for formal nonlimited derived type (2010-07-15)' |
64d5610f | 27590 | |
b71d4b62 RA |
27591 | The actual for a formal nonlimited derived type cannot be limited. In |
27592 | particular, a formal derived type that extends a limited interface but which | |
27593 | is not explicitly limited cannot be instantiated with a limited type. | |
64d5610f | 27594 | |
b71d4b62 | 27595 | RM References: 7.05 (5/2) 12.05.01 (5.1/2) |
64d5610f ML |
27596 | @end itemize |
27597 | ||
b71d4b62 | 27598 | @geindex AI-0099 (Ada 2012 feature) |
64d5610f ML |
27599 | |
27600 | ||
27601 | @itemize * | |
27602 | ||
27603 | @item | |
b71d4b62 | 27604 | `AI-0099 Tag determines whether finalization needed (0000-00-00)' |
64d5610f | 27605 | |
b71d4b62 RA |
27606 | This AI clarifies that ‘needs finalization’ is part of dynamic semantics, |
27607 | and therefore depends on the run-time characteristics of an object (i.e. its | |
27608 | tag) and not on its nominal type. As the AI indicates: “we do not expect | |
27609 | this to affect any implementation’’. | |
64d5610f | 27610 | |
b71d4b62 | 27611 | RM References: 7.06.01 (6) 7.06.01 (7) 7.06.01 (8) 7.06.01 (9/2) |
64d5610f ML |
27612 | @end itemize |
27613 | ||
b71d4b62 | 27614 | @geindex AI-0064 (Ada 2012 feature) |
64d5610f ML |
27615 | |
27616 | ||
27617 | @itemize * | |
27618 | ||
27619 | @item | |
b71d4b62 | 27620 | `AI-0064 Redundant finalization rule (0000-00-00)' |
64d5610f | 27621 | |
b71d4b62 RA |
27622 | This is an editorial change only. The intended behavior is already checked |
27623 | by an existing ACATS test, which GNAT has always executed correctly. | |
64d5610f | 27624 | |
b71d4b62 | 27625 | RM References: 7.06.01 (17.1/1) |
64d5610f ML |
27626 | @end itemize |
27627 | ||
b71d4b62 | 27628 | @geindex AI-0026 (Ada 2012 feature) |
64d5610f ML |
27629 | |
27630 | ||
27631 | @itemize * | |
27632 | ||
27633 | @item | |
b71d4b62 | 27634 | `AI-0026 Missing rules for Unchecked_Union (2010-07-07)' |
64d5610f | 27635 | |
b71d4b62 RA |
27636 | Record representation clauses concerning Unchecked_Union types cannot mention |
27637 | the discriminant of the type. The type of a component declared in the variant | |
27638 | part of an Unchecked_Union cannot be controlled, have controlled components, | |
27639 | nor have protected or task parts. If an Unchecked_Union type is declared | |
27640 | within the body of a generic unit or its descendants, then the type of a | |
27641 | component declared in the variant part cannot be a formal private type or a | |
27642 | formal private extension declared within the same generic unit. | |
64d5610f | 27643 | |
b71d4b62 | 27644 | RM References: 7.06 (9.4/2) B.03.03 (9/2) B.03.03 (10/2) |
64d5610f ML |
27645 | @end itemize |
27646 | ||
b71d4b62 | 27647 | @geindex AI-0205 (Ada 2012 feature) |
64d5610f ML |
27648 | |
27649 | ||
27650 | @itemize * | |
27651 | ||
27652 | @item | |
b71d4b62 | 27653 | `AI-0205 Extended return declares visible name (0000-00-00)' |
64d5610f | 27654 | |
b71d4b62 RA |
27655 | This AI corrects a simple omission in the RM. Return objects have always |
27656 | been visible within an extended return statement. | |
64d5610f | 27657 | |
b71d4b62 | 27658 | RM References: 8.03 (17) |
64d5610f ML |
27659 | @end itemize |
27660 | ||
b71d4b62 | 27661 | @geindex AI-0042 (Ada 2012 feature) |
64d5610f ML |
27662 | |
27663 | ||
27664 | @itemize * | |
27665 | ||
27666 | @item | |
b71d4b62 | 27667 | `AI-0042 Overriding versus implemented-by (0000-00-00)' |
64d5610f | 27668 | |
b71d4b62 RA |
27669 | This AI fixes a wording gap in the RM. An operation of a synchronized |
27670 | interface can be implemented by a protected or task entry, but the abstract | |
27671 | operation is not being overridden in the usual sense, and it must be stated | |
27672 | separately that this implementation is legal. This has always been the case | |
27673 | in GNAT. | |
64d5610f | 27674 | |
b71d4b62 | 27675 | RM References: 9.01 (9.2/2) 9.04 (11.1/2) |
64d5610f ML |
27676 | @end itemize |
27677 | ||
b71d4b62 | 27678 | @geindex AI-0030 (Ada 2012 feature) |
64d5610f ML |
27679 | |
27680 | ||
27681 | @itemize * | |
27682 | ||
27683 | @item | |
b71d4b62 | 27684 | `AI-0030 Requeue on synchronized interfaces (2010-07-19)' |
64d5610f | 27685 | |
b71d4b62 RA |
27686 | Requeue is permitted to a protected, synchronized or task interface primitive |
27687 | providing it is known that the overriding operation is an entry. Otherwise | |
27688 | the requeue statement has the same effect as a procedure call. Use of pragma | |
27689 | @code{Implemented} provides a way to impose a static requirement on the | |
27690 | overriding operation by adhering to one of the implementation kinds: entry, | |
27691 | protected procedure or any of the above. | |
64d5610f | 27692 | |
b71d4b62 RA |
27693 | RM References: 9.05 (9) 9.05.04 (2) 9.05.04 (3) 9.05.04 (5) |
27694 | 9.05.04 (6) 9.05.04 (7) 9.05.04 (12) | |
64d5610f ML |
27695 | @end itemize |
27696 | ||
b71d4b62 | 27697 | @geindex AI-0201 (Ada 2012 feature) |
64d5610f ML |
27698 | |
27699 | ||
27700 | @itemize * | |
27701 | ||
27702 | @item | |
b71d4b62 | 27703 | `AI-0201 Independence of atomic object components (2010-07-22)' |
64d5610f | 27704 | |
b71d4b62 RA |
27705 | If an Atomic object has a pragma @code{Pack} or a @code{Component_Size} |
27706 | attribute, then individual components may not be addressable by independent | |
27707 | tasks. However, if the representation clause has no effect (is confirming), | |
27708 | then independence is not compromised. Furthermore, in GNAT, specification of | |
27709 | other appropriately addressable component sizes (e.g. 16 for 8-bit | |
27710 | characters) also preserves independence. GNAT now gives very clear warnings | |
27711 | both for the declaration of such a type, and for any assignment to its components. | |
64d5610f | 27712 | |
b71d4b62 | 27713 | RM References: 9.10 (1/3) C.06 (22/2) C.06 (23/2) |
64d5610f ML |
27714 | @end itemize |
27715 | ||
b71d4b62 | 27716 | @geindex AI-0009 (Ada 2012 feature) |
64d5610f ML |
27717 | |
27718 | ||
27719 | @itemize * | |
27720 | ||
27721 | @item | |
b71d4b62 | 27722 | `AI-0009 Pragma Independent[_Components] (2010-07-23)' |
64d5610f | 27723 | |
b71d4b62 RA |
27724 | This AI introduces the new pragmas @code{Independent} and |
27725 | @code{Independent_Components}, | |
27726 | which control guaranteeing independence of access to objects and components. | |
27727 | The AI also requires independence not unaffected by confirming rep clauses. | |
64d5610f | 27728 | |
b71d4b62 RA |
27729 | RM References: 9.10 (1) 13.01 (15/1) 13.02 (9) 13.03 (13) C.06 (2) |
27730 | C.06 (4) C.06 (6) C.06 (9) C.06 (13) C.06 (14) | |
64d5610f ML |
27731 | @end itemize |
27732 | ||
b71d4b62 | 27733 | @geindex AI-0072 (Ada 2012 feature) |
64d5610f ML |
27734 | |
27735 | ||
27736 | @itemize * | |
27737 | ||
27738 | @item | |
b71d4b62 | 27739 | `AI-0072 Task signalling using ‘Terminated (0000-00-00)' |
64d5610f | 27740 | |
b71d4b62 RA |
27741 | This AI clarifies that task signalling for reading @code{'Terminated} only |
27742 | occurs if the result is True. GNAT semantics has always been consistent with | |
27743 | this notion of task signalling. | |
64d5610f | 27744 | |
b71d4b62 | 27745 | RM References: 9.10 (6.1/1) |
64d5610f ML |
27746 | @end itemize |
27747 | ||
b71d4b62 | 27748 | @geindex AI-0108 (Ada 2012 feature) |
64d5610f ML |
27749 | |
27750 | ||
27751 | @itemize * | |
27752 | ||
27753 | @item | |
b71d4b62 | 27754 | `AI-0108 Limited incomplete view and discriminants (0000-00-00)' |
64d5610f | 27755 | |
b71d4b62 RA |
27756 | This AI confirms that an incomplete type from a limited view does not have |
27757 | discriminants. This has always been the case in GNAT. | |
64d5610f | 27758 | |
b71d4b62 | 27759 | RM References: 10.01.01 (12.3/2) |
64d5610f ML |
27760 | @end itemize |
27761 | ||
b71d4b62 | 27762 | @geindex AI-0129 (Ada 2012 feature) |
64d5610f ML |
27763 | |
27764 | ||
27765 | @itemize * | |
27766 | ||
27767 | @item | |
b71d4b62 | 27768 | `AI-0129 Limited views and incomplete types (0000-00-00)' |
64d5610f | 27769 | |
b71d4b62 RA |
27770 | This AI clarifies the description of limited views: a limited view of a |
27771 | package includes only one view of a type that has an incomplete declaration | |
27772 | and a full declaration (there is no possible ambiguity in a client package). | |
27773 | This AI also fixes an omission: a nested package in the private part has no | |
27774 | limited view. GNAT always implemented this correctly. | |
64d5610f | 27775 | |
b71d4b62 | 27776 | RM References: 10.01.01 (12.2/2) 10.01.01 (12.3/2) |
64d5610f ML |
27777 | @end itemize |
27778 | ||
b71d4b62 | 27779 | @geindex AI-0077 (Ada 2012 feature) |
64d5610f ML |
27780 | |
27781 | ||
27782 | @itemize * | |
27783 | ||
27784 | @item | |
b71d4b62 | 27785 | `AI-0077 Limited withs and scope of declarations (0000-00-00)' |
64d5610f | 27786 | |
b71d4b62 RA |
27787 | This AI clarifies that a declaration does not include a context clause, |
27788 | and confirms that it is illegal to have a context in which both a limited | |
27789 | and a nonlimited view of a package are accessible. Such double visibility | |
27790 | was always rejected by GNAT. | |
64d5610f | 27791 | |
b71d4b62 | 27792 | RM References: 10.01.02 (12/2) 10.01.02 (21/2) 10.01.02 (22/2) |
64d5610f ML |
27793 | @end itemize |
27794 | ||
b71d4b62 | 27795 | @geindex AI-0122 (Ada 2012 feature) |
64d5610f ML |
27796 | |
27797 | ||
27798 | @itemize * | |
27799 | ||
27800 | @item | |
b71d4b62 | 27801 | `AI-0122 Private with and children of generics (0000-00-00)' |
64d5610f | 27802 | |
b71d4b62 RA |
27803 | This AI clarifies the visibility of private children of generic units within |
27804 | instantiations of a parent. GNAT has always handled this correctly. | |
64d5610f | 27805 | |
b71d4b62 | 27806 | RM References: 10.01.02 (12/2) |
64d5610f ML |
27807 | @end itemize |
27808 | ||
b71d4b62 | 27809 | @geindex AI-0040 (Ada 2012 feature) |
64d5610f ML |
27810 | |
27811 | ||
27812 | @itemize * | |
27813 | ||
27814 | @item | |
b71d4b62 | 27815 | `AI-0040 Limited with clauses on descendant (0000-00-00)' |
64d5610f | 27816 | |
b71d4b62 RA |
27817 | This AI confirms that a limited with clause in a child unit cannot name |
27818 | an ancestor of the unit. This has always been checked in GNAT. | |
64d5610f | 27819 | |
b71d4b62 | 27820 | RM References: 10.01.02 (20/2) |
64d5610f ML |
27821 | @end itemize |
27822 | ||
b71d4b62 | 27823 | @geindex AI-0132 (Ada 2012 feature) |
64d5610f ML |
27824 | |
27825 | ||
27826 | @itemize * | |
27827 | ||
27828 | @item | |
b71d4b62 | 27829 | `AI-0132 Placement of library unit pragmas (0000-00-00)' |
64d5610f | 27830 | |
b71d4b62 RA |
27831 | This AI fills a gap in the description of library unit pragmas. The pragma |
27832 | clearly must apply to a library unit, even if it does not carry the name | |
27833 | of the enclosing unit. GNAT has always enforced the required check. | |
64d5610f | 27834 | |
b71d4b62 | 27835 | RM References: 10.01.05 (7) |
64d5610f ML |
27836 | @end itemize |
27837 | ||
b71d4b62 | 27838 | @geindex AI-0034 (Ada 2012 feature) |
64d5610f ML |
27839 | |
27840 | ||
27841 | @itemize * | |
27842 | ||
27843 | @item | |
b71d4b62 | 27844 | `AI-0034 Categorization of limited views (0000-00-00)' |
64d5610f | 27845 | |
b71d4b62 RA |
27846 | The RM makes certain limited with clauses illegal because of categorization |
27847 | considerations, when the corresponding normal with would be legal. This is | |
27848 | not intended, and GNAT has always implemented the recommended behavior. | |
64d5610f | 27849 | |
b71d4b62 | 27850 | RM References: 10.02.01 (11/1) 10.02.01 (17/2) |
64d5610f ML |
27851 | @end itemize |
27852 | ||
b71d4b62 | 27853 | @geindex AI-0035 (Ada 2012 feature) |
64d5610f ML |
27854 | |
27855 | ||
27856 | @itemize * | |
27857 | ||
27858 | @item | |
b71d4b62 | 27859 | `AI-0035 Inconsistencies with Pure units (0000-00-00)' |
64d5610f | 27860 | |
b71d4b62 RA |
27861 | This AI remedies some inconsistencies in the legality rules for Pure units. |
27862 | Derived access types are legal in a pure unit (on the assumption that the | |
27863 | rule for a zero storage pool size has been enforced on the ancestor type). | |
27864 | The rules are enforced in generic instances and in subunits. GNAT has always | |
27865 | implemented the recommended behavior. | |
64d5610f | 27866 | |
b71d4b62 | 27867 | 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 |
27868 | @end itemize |
27869 | ||
b71d4b62 | 27870 | @geindex AI-0219 (Ada 2012 feature) |
64d5610f ML |
27871 | |
27872 | ||
27873 | @itemize * | |
27874 | ||
27875 | @item | |
b71d4b62 | 27876 | `AI-0219 Pure permissions and limited parameters (2010-05-25)' |
64d5610f | 27877 | |
b71d4b62 RA |
27878 | This AI refines the rules for the cases with limited parameters which do not |
27879 | allow the implementations to omit ‘redundant’. GNAT now properly conforms | |
27880 | to the requirements of this binding interpretation. | |
64d5610f | 27881 | |
b71d4b62 | 27882 | RM References: 10.02.01 (18/2) |
64d5610f ML |
27883 | @end itemize |
27884 | ||
b71d4b62 | 27885 | @geindex AI-0043 (Ada 2012 feature) |
64d5610f ML |
27886 | |
27887 | ||
27888 | @itemize * | |
27889 | ||
27890 | @item | |
b71d4b62 | 27891 | `AI-0043 Rules about raising exceptions (0000-00-00)' |
64d5610f | 27892 | |
b71d4b62 RA |
27893 | This AI covers various omissions in the RM regarding the raising of |
27894 | exceptions. GNAT has always implemented the intended semantics. | |
64d5610f | 27895 | |
b71d4b62 | 27896 | RM References: 11.04.01 (10.1/2) 11 (2) |
64d5610f ML |
27897 | @end itemize |
27898 | ||
b71d4b62 | 27899 | @geindex AI-0200 (Ada 2012 feature) |
64d5610f ML |
27900 | |
27901 | ||
27902 | @itemize * | |
27903 | ||
27904 | @item | |
b71d4b62 | 27905 | `AI-0200 Mismatches in formal package declarations (0000-00-00)' |
64d5610f | 27906 | |
b71d4b62 RA |
27907 | This AI plugs a gap in the RM which appeared to allow some obviously intended |
27908 | illegal instantiations. GNAT has never allowed these instantiations. | |
64d5610f | 27909 | |
b71d4b62 | 27910 | RM References: 12.07 (16) |
64d5610f ML |
27911 | @end itemize |
27912 | ||
b71d4b62 | 27913 | @geindex AI-0112 (Ada 2012 feature) |
64d5610f ML |
27914 | |
27915 | ||
27916 | @itemize * | |
27917 | ||
27918 | @item | |
b71d4b62 | 27919 | `AI-0112 Detection of duplicate pragmas (2010-07-24)' |
64d5610f | 27920 | |
b71d4b62 RA |
27921 | This AI concerns giving names to various representation aspects, but the |
27922 | practical effect is simply to make the use of duplicate | |
27923 | @code{Atomic[_Components]}, | |
27924 | @code{Volatile[_Components]}, and | |
27925 | @code{Independent[_Components]} pragmas illegal, and GNAT | |
27926 | now performs this required check. | |
64d5610f | 27927 | |
b71d4b62 | 27928 | RM References: 13.01 (8) |
64d5610f ML |
27929 | @end itemize |
27930 | ||
b71d4b62 | 27931 | @geindex AI-0106 (Ada 2012 feature) |
64d5610f ML |
27932 | |
27933 | ||
27934 | @itemize * | |
27935 | ||
27936 | @item | |
b71d4b62 | 27937 | `AI-0106 No representation pragmas on generic formals (0000-00-00)' |
64d5610f | 27938 | |
b71d4b62 RA |
27939 | The RM appeared to allow representation pragmas on generic formal parameters, |
27940 | but this was not intended, and GNAT has never permitted this usage. | |
64d5610f | 27941 | |
b71d4b62 | 27942 | RM References: 13.01 (9.1/1) |
64d5610f ML |
27943 | @end itemize |
27944 | ||
b71d4b62 | 27945 | @geindex AI-0012 (Ada 2012 feature) |
64d5610f ML |
27946 | |
27947 | ||
27948 | @itemize * | |
27949 | ||
27950 | @item | |
b71d4b62 | 27951 | `AI-0012 Pack/Component_Size for aliased/atomic (2010-07-15)' |
64d5610f | 27952 | |
b71d4b62 RA |
27953 | It is now illegal to give an inappropriate component size or a pragma |
27954 | @code{Pack} that attempts to change the component size in the case of atomic | |
27955 | or aliased components. Previously GNAT ignored such an attempt with a | |
27956 | warning. | |
64d5610f | 27957 | |
b71d4b62 | 27958 | RM References: 13.02 (6.1/2) 13.02 (7) C.06 (10) C.06 (11) C.06 (21) |
64d5610f ML |
27959 | @end itemize |
27960 | ||
b71d4b62 | 27961 | @geindex AI-0039 (Ada 2012 feature) |
64d5610f ML |
27962 | |
27963 | ||
27964 | @itemize * | |
27965 | ||
27966 | @item | |
b71d4b62 | 27967 | `AI-0039 Stream attributes cannot be dynamic (0000-00-00)' |
64d5610f | 27968 | |
b71d4b62 RA |
27969 | The RM permitted the use of dynamic expressions (such as @code{ptr.all})` |
27970 | for stream attributes, but these were never useful and are now illegal. GNAT | |
27971 | has always regarded such expressions as illegal. | |
64d5610f | 27972 | |
b71d4b62 | 27973 | RM References: 13.03 (4) 13.03 (6) 13.13.02 (38/2) |
64d5610f ML |
27974 | @end itemize |
27975 | ||
b71d4b62 | 27976 | @geindex AI-0095 (Ada 2012 feature) |
64d5610f ML |
27977 | |
27978 | ||
27979 | @itemize * | |
27980 | ||
27981 | @item | |
b71d4b62 | 27982 | `AI-0095 Address of intrinsic subprograms (0000-00-00)' |
64d5610f | 27983 | |
b71d4b62 RA |
27984 | The prefix of @code{'Address} cannot statically denote a subprogram with |
27985 | convention @code{Intrinsic}. The use of the @code{Address} attribute raises | |
27986 | @code{Program_Error} if the prefix denotes a subprogram with convention | |
27987 | @code{Intrinsic}. | |
64d5610f | 27988 | |
b71d4b62 | 27989 | RM References: 13.03 (11/1) |
64d5610f ML |
27990 | @end itemize |
27991 | ||
b71d4b62 | 27992 | @geindex AI-0116 (Ada 2012 feature) |
64d5610f ML |
27993 | |
27994 | ||
27995 | @itemize * | |
27996 | ||
27997 | @item | |
b71d4b62 | 27998 | `AI-0116 Alignment of class-wide objects (0000-00-00)' |
64d5610f | 27999 | |
b71d4b62 RA |
28000 | This AI requires that the alignment of a class-wide object be no greater |
28001 | than the alignment of any type in the class. GNAT has always followed this | |
28002 | recommendation. | |
64d5610f | 28003 | |
b71d4b62 | 28004 | RM References: 13.03 (29) 13.11 (16) |
64d5610f ML |
28005 | @end itemize |
28006 | ||
b71d4b62 | 28007 | @geindex AI-0146 (Ada 2012 feature) |
64d5610f ML |
28008 | |
28009 | ||
28010 | @itemize * | |
28011 | ||
28012 | @item | |
b71d4b62 | 28013 | `AI-0146 Type invariants (2009-09-21)' |
64d5610f | 28014 | |
b71d4b62 RA |
28015 | Type invariants may be specified for private types using the aspect notation. |
28016 | Aspect @code{Type_Invariant} may be specified for any private type, | |
28017 | @code{Type_Invariant'Class} can | |
28018 | only be specified for tagged types, and is inherited by any descendent of the | |
28019 | tagged types. The invariant is a boolean expression that is tested for being | |
28020 | true in the following situations: conversions to the private type, object | |
28021 | declarations for the private type that are default initialized, and | |
28022 | [`in'] `out' | |
28023 | parameters and returned result on return from any primitive operation for | |
28024 | the type that is visible to a client. | |
28025 | GNAT defines the synonyms @code{Invariant} for @code{Type_Invariant} and | |
28026 | @code{Invariant'Class} for @code{Type_Invariant'Class}. | |
64d5610f | 28027 | |
b71d4b62 | 28028 | RM References: 13.03.03 (00) |
64d5610f ML |
28029 | @end itemize |
28030 | ||
b71d4b62 | 28031 | @geindex AI-0078 (Ada 2012 feature) |
64d5610f ML |
28032 | |
28033 | ||
28034 | @itemize * | |
28035 | ||
28036 | @item | |
b71d4b62 | 28037 | `AI-0078 Relax Unchecked_Conversion alignment rules (0000-00-00)' |
64d5610f | 28038 | |
b71d4b62 RA |
28039 | In Ada 2012, compilers are required to support unchecked conversion where the |
28040 | target alignment is a multiple of the source alignment. GNAT always supported | |
28041 | this case (and indeed all cases of differing alignments, doing copies where | |
28042 | required if the alignment was reduced). | |
64d5610f | 28043 | |
b71d4b62 | 28044 | RM References: 13.09 (7) |
64d5610f ML |
28045 | @end itemize |
28046 | ||
b71d4b62 | 28047 | @geindex AI-0195 (Ada 2012 feature) |
64d5610f ML |
28048 | |
28049 | ||
28050 | @itemize * | |
28051 | ||
28052 | @item | |
b71d4b62 | 28053 | `AI-0195 Invalid value handling is implementation defined (2010-07-03)' |
64d5610f | 28054 | |
b71d4b62 RA |
28055 | The handling of invalid values is now designated to be implementation |
28056 | defined. This is a documentation change only, requiring Annex M in the GNAT | |
28057 | Reference Manual to document this handling. | |
28058 | In GNAT, checks for invalid values are made | |
28059 | only when necessary to avoid erroneous behavior. Operations like assignments | |
28060 | which cannot cause erroneous behavior ignore the possibility of invalid | |
28061 | values and do not do a check. The date given above applies only to the | |
28062 | documentation change, this behavior has always been implemented by GNAT. | |
64d5610f | 28063 | |
b71d4b62 | 28064 | RM References: 13.09.01 (10) |
64d5610f ML |
28065 | @end itemize |
28066 | ||
b71d4b62 | 28067 | @geindex AI-0193 (Ada 2012 feature) |
64d5610f ML |
28068 | |
28069 | ||
28070 | @itemize * | |
28071 | ||
28072 | @item | |
b71d4b62 | 28073 | `AI-0193 Alignment of allocators (2010-09-16)' |
64d5610f | 28074 | |
b71d4b62 RA |
28075 | This AI introduces a new attribute @code{Max_Alignment_For_Allocation}, |
28076 | analogous to @code{Max_Size_In_Storage_Elements}, but for alignment instead | |
28077 | of size. | |
64d5610f | 28078 | |
b71d4b62 RA |
28079 | RM References: 13.11 (16) 13.11 (21) 13.11.01 (0) 13.11.01 (1) |
28080 | 13.11.01 (2) 13.11.01 (3) | |
64d5610f ML |
28081 | @end itemize |
28082 | ||
b71d4b62 | 28083 | @geindex AI-0177 (Ada 2012 feature) |
64d5610f ML |
28084 | |
28085 | ||
28086 | @itemize * | |
28087 | ||
28088 | @item | |
b71d4b62 | 28089 | `AI-0177 Parameterized expressions (2010-07-10)' |
64d5610f | 28090 | |
b71d4b62 RA |
28091 | The new Ada 2012 notion of parameterized expressions is implemented. The form |
28092 | is: | |
64d5610f | 28093 | |
b71d4b62 RA |
28094 | @example |
28095 | function-specification is (expression) | |
28096 | @end example | |
28097 | ||
28098 | This is exactly equivalent to the | |
28099 | corresponding function body that returns the expression, but it can appear | |
28100 | in a package spec. Note that the expression must be parenthesized. | |
28101 | ||
28102 | RM References: 13.11.01 (3/2) | |
64d5610f ML |
28103 | @end itemize |
28104 | ||
b71d4b62 | 28105 | @geindex AI-0033 (Ada 2012 feature) |
64d5610f ML |
28106 | |
28107 | ||
28108 | @itemize * | |
28109 | ||
28110 | @item | |
b71d4b62 | 28111 | `AI-0033 Attach/Interrupt_Handler in generic (2010-07-24)' |
64d5610f | 28112 | |
b71d4b62 RA |
28113 | Neither of these two pragmas may appear within a generic template, because |
28114 | the generic might be instantiated at other than the library level. | |
64d5610f | 28115 | |
b71d4b62 | 28116 | RM References: 13.11.02 (16) C.03.01 (7/2) C.03.01 (8/2) |
64d5610f ML |
28117 | @end itemize |
28118 | ||
b71d4b62 | 28119 | @geindex AI-0161 (Ada 2012 feature) |
64d5610f ML |
28120 | |
28121 | ||
28122 | @itemize * | |
28123 | ||
28124 | @item | |
b71d4b62 | 28125 | `AI-0161 Restriction No_Default_Stream_Attributes (2010-09-11)' |
64d5610f | 28126 | |
b71d4b62 RA |
28127 | A new restriction @code{No_Default_Stream_Attributes} prevents the use of any |
28128 | of the default stream attributes for elementary types. If this restriction is | |
28129 | in force, then it is necessary to provide explicit subprograms for any | |
28130 | stream attributes used. | |
64d5610f | 28131 | |
b71d4b62 | 28132 | RM References: 13.12.01 (4/2) 13.13.02 (40/2) 13.13.02 (52/2) |
64d5610f ML |
28133 | @end itemize |
28134 | ||
b71d4b62 | 28135 | @geindex AI-0194 (Ada 2012 feature) |
64d5610f ML |
28136 | |
28137 | ||
28138 | @itemize * | |
28139 | ||
28140 | @item | |
b71d4b62 | 28141 | `AI-0194 Value of Stream_Size attribute (0000-00-00)' |
64d5610f | 28142 | |
b71d4b62 RA |
28143 | The @code{Stream_Size} attribute returns the default number of bits in the |
28144 | stream representation of the given type. | |
28145 | This value is not affected by the presence | |
28146 | of stream subprogram attributes for the type. GNAT has always implemented | |
28147 | this interpretation. | |
64d5610f | 28148 | |
b71d4b62 | 28149 | RM References: 13.13.02 (1.2/2) |
64d5610f ML |
28150 | @end itemize |
28151 | ||
b71d4b62 | 28152 | @geindex AI-0109 (Ada 2012 feature) |
64d5610f ML |
28153 | |
28154 | ||
28155 | @itemize * | |
28156 | ||
28157 | @item | |
b71d4b62 | 28158 | `AI-0109 Redundant check in S’Class’Input (0000-00-00)' |
64d5610f | 28159 | |
b71d4b62 RA |
28160 | This AI is an editorial change only. It removes the need for a tag check |
28161 | that can never fail. | |
64d5610f | 28162 | |
b71d4b62 | 28163 | RM References: 13.13.02 (34/2) |
64d5610f ML |
28164 | @end itemize |
28165 | ||
b71d4b62 | 28166 | @geindex AI-0007 (Ada 2012 feature) |
64d5610f ML |
28167 | |
28168 | ||
28169 | @itemize * | |
28170 | ||
28171 | @item | |
b71d4b62 | 28172 | `AI-0007 Stream read and private scalar types (0000-00-00)' |
64d5610f | 28173 | |
b71d4b62 RA |
28174 | The RM as written appeared to limit the possibilities of declaring read |
28175 | attribute procedures for private scalar types. This limitation was not | |
28176 | intended, and has never been enforced by GNAT. | |
64d5610f | 28177 | |
b71d4b62 | 28178 | RM References: 13.13.02 (50/2) 13.13.02 (51/2) |
64d5610f ML |
28179 | @end itemize |
28180 | ||
b71d4b62 | 28181 | @geindex AI-0065 (Ada 2012 feature) |
64d5610f ML |
28182 | |
28183 | ||
28184 | @itemize * | |
28185 | ||
28186 | @item | |
b71d4b62 | 28187 | `AI-0065 Remote access types and external streaming (0000-00-00)' |
64d5610f | 28188 | |
b71d4b62 RA |
28189 | This AI clarifies the fact that all remote access types support external |
28190 | streaming. This fixes an obvious oversight in the definition of the | |
28191 | language, and GNAT always implemented the intended correct rules. | |
64d5610f | 28192 | |
b71d4b62 | 28193 | RM References: 13.13.02 (52/2) |
64d5610f ML |
28194 | @end itemize |
28195 | ||
b71d4b62 | 28196 | @geindex AI-0019 (Ada 2012 feature) |
64d5610f ML |
28197 | |
28198 | ||
28199 | @itemize * | |
28200 | ||
28201 | @item | |
b71d4b62 | 28202 | `AI-0019 Freezing of primitives for tagged types (0000-00-00)' |
64d5610f | 28203 | |
b71d4b62 RA |
28204 | The RM suggests that primitive subprograms of a specific tagged type are |
28205 | frozen when the tagged type is frozen. This would be an incompatible change | |
28206 | and is not intended. GNAT has never attempted this kind of freezing and its | |
28207 | behavior is consistent with the recommendation of this AI. | |
64d5610f | 28208 | |
b71d4b62 | 28209 | 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 |
28210 | @end itemize |
28211 | ||
b71d4b62 | 28212 | @geindex AI-0017 (Ada 2012 feature) |
64d5610f ML |
28213 | |
28214 | ||
28215 | @itemize * | |
28216 | ||
28217 | @item | |
b71d4b62 | 28218 | `AI-0017 Freezing and incomplete types (0000-00-00)' |
64d5610f | 28219 | |
b71d4b62 RA |
28220 | So-called ‘Taft-amendment types’ (i.e., types that are completed in package |
28221 | bodies) are not frozen by the occurrence of bodies in the | |
28222 | enclosing declarative part. GNAT always implemented this properly. | |
64d5610f | 28223 | |
b71d4b62 | 28224 | RM References: 13.14 (3/1) |
64d5610f ML |
28225 | @end itemize |
28226 | ||
b71d4b62 | 28227 | @geindex AI-0060 (Ada 2012 feature) |
64d5610f ML |
28228 | |
28229 | ||
28230 | @itemize * | |
28231 | ||
28232 | @item | |
b71d4b62 | 28233 | `AI-0060 Extended definition of remote access types (0000-00-00)' |
64d5610f | 28234 | |
b71d4b62 RA |
28235 | This AI extends the definition of remote access types to include access |
28236 | to limited, synchronized, protected or task class-wide interface types. | |
28237 | GNAT already implemented this extension. | |
64d5610f | 28238 | |
b71d4b62 | 28239 | 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 |
28240 | @end itemize |
28241 | ||
b71d4b62 | 28242 | @geindex AI-0114 (Ada 2012 feature) |
64d5610f ML |
28243 | |
28244 | ||
28245 | @itemize * | |
28246 | ||
28247 | @item | |
b71d4b62 | 28248 | `AI-0114 Classification of letters (0000-00-00)' |
64d5610f | 28249 | |
b71d4b62 RA |
28250 | The code points 170 (@code{FEMININE ORDINAL INDICATOR}), |
28251 | 181 (@code{MICRO SIGN}), and | |
28252 | 186 (@code{MASCULINE ORDINAL INDICATOR}) are technically considered | |
28253 | lower case letters by Unicode. | |
28254 | However, they are not allowed in identifiers, and they | |
28255 | return @code{False} to @code{Ada.Characters.Handling.Is_Letter/Is_Lower}. | |
28256 | This behavior is consistent with that defined in Ada 95. | |
64d5610f | 28257 | |
b71d4b62 | 28258 | RM References: A.03.02 (59) A.04.06 (7) |
64d5610f ML |
28259 | @end itemize |
28260 | ||
b71d4b62 | 28261 | @geindex AI-0185 (Ada 2012 feature) |
64d5610f ML |
28262 | |
28263 | ||
28264 | @itemize * | |
28265 | ||
28266 | @item | |
b71d4b62 | 28267 | `AI-0185 Ada.Wide_[Wide_]Characters.Handling (2010-07-06)' |
64d5610f | 28268 | |
b71d4b62 RA |
28269 | Two new packages @code{Ada.Wide_[Wide_]Characters.Handling} provide |
28270 | classification functions for @code{Wide_Character} and | |
28271 | @code{Wide_Wide_Character}, as well as providing | |
28272 | case folding routines for @code{Wide_[Wide_]Character} and | |
28273 | @code{Wide_[Wide_]String}. | |
64d5610f | 28274 | |
b71d4b62 | 28275 | RM References: A.03.05 (0) A.03.06 (0) |
64d5610f ML |
28276 | @end itemize |
28277 | ||
b71d4b62 | 28278 | @geindex AI-0031 (Ada 2012 feature) |
64d5610f ML |
28279 | |
28280 | ||
28281 | @itemize * | |
28282 | ||
28283 | @item | |
b71d4b62 | 28284 | `AI-0031 Add From parameter to Find_Token (2010-07-25)' |
64d5610f | 28285 | |
b71d4b62 RA |
28286 | A new version of @code{Find_Token} is added to all relevant string packages, |
28287 | with an extra parameter @code{From}. Instead of starting at the first | |
28288 | character of the string, the search for a matching Token starts at the | |
28289 | character indexed by the value of @code{From}. | |
28290 | These procedures are available in all versions of Ada | |
28291 | but if used in versions earlier than Ada 2012 they will generate a warning | |
28292 | that an Ada 2012 subprogram is being used. | |
64d5610f | 28293 | |
b71d4b62 RA |
28294 | RM References: A.04.03 (16) A.04.03 (67) A.04.03 (68/1) A.04.04 (51) |
28295 | A.04.05 (46) | |
64d5610f ML |
28296 | @end itemize |
28297 | ||
b71d4b62 | 28298 | @geindex AI-0056 (Ada 2012 feature) |
64d5610f ML |
28299 | |
28300 | ||
28301 | @itemize * | |
28302 | ||
28303 | @item | |
b71d4b62 | 28304 | `AI-0056 Index on null string returns zero (0000-00-00)' |
64d5610f | 28305 | |
b71d4b62 RA |
28306 | The wording in the Ada 2005 RM implied an incompatible handling of the |
28307 | @code{Index} functions, resulting in raising an exception instead of | |
28308 | returning zero in some situations. | |
28309 | This was not intended and has been corrected. | |
28310 | GNAT always returned zero, and is thus consistent with this AI. | |
64d5610f | 28311 | |
b71d4b62 | 28312 | RM References: A.04.03 (56.2/2) A.04.03 (58.5/2) |
64d5610f ML |
28313 | @end itemize |
28314 | ||
b71d4b62 | 28315 | @geindex AI-0137 (Ada 2012 feature) |
64d5610f ML |
28316 | |
28317 | ||
28318 | @itemize * | |
28319 | ||
28320 | @item | |
b71d4b62 | 28321 | `AI-0137 String encoding package (2010-03-25)' |
64d5610f | 28322 | |
b71d4b62 RA |
28323 | The packages @code{Ada.Strings.UTF_Encoding}, together with its child |
28324 | packages, @code{Conversions}, @code{Strings}, @code{Wide_Strings}, | |
28325 | and @code{Wide_Wide_Strings} have been | |
28326 | implemented. These packages (whose documentation can be found in the spec | |
28327 | files @code{a-stuten.ads}, @code{a-suenco.ads}, @code{a-suenst.ads}, | |
28328 | @code{a-suewst.ads}, @code{a-suezst.ads}) allow encoding and decoding of | |
28329 | @code{String}, @code{Wide_String}, and @code{Wide_Wide_String} | |
28330 | values using UTF coding schemes (including UTF-8, UTF-16LE, UTF-16BE, and | |
28331 | UTF-16), as well as conversions between the different UTF encodings. With | |
28332 | the exception of @code{Wide_Wide_Strings}, these packages are available in | |
28333 | Ada 95 and Ada 2005 mode as well as Ada 2012 mode. | |
28334 | The @code{Wide_Wide_Strings} package | |
28335 | is available in Ada 2005 mode as well as Ada 2012 mode (but not in Ada 95 | |
28336 | mode since it uses @code{Wide_Wide_Character}). | |
64d5610f | 28337 | |
b71d4b62 | 28338 | RM References: A.04.11 |
64d5610f ML |
28339 | @end itemize |
28340 | ||
b71d4b62 | 28341 | @geindex AI-0038 (Ada 2012 feature) |
64d5610f ML |
28342 | |
28343 | ||
28344 | @itemize * | |
28345 | ||
28346 | @item | |
b71d4b62 | 28347 | `AI-0038 Minor errors in Text_IO (0000-00-00)' |
64d5610f | 28348 | |
b71d4b62 RA |
28349 | These are minor errors in the description on three points. The intent on |
28350 | all these points has always been clear, and GNAT has always implemented the | |
28351 | correct intended semantics. | |
64d5610f | 28352 | |
b71d4b62 | 28353 | 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 |
28354 | @end itemize |
28355 | ||
b71d4b62 | 28356 | @geindex AI-0044 (Ada 2012 feature) |
64d5610f ML |
28357 | |
28358 | ||
28359 | @itemize * | |
28360 | ||
28361 | @item | |
b71d4b62 | 28362 | `AI-0044 Restrictions on container instantiations (0000-00-00)' |
64d5610f | 28363 | |
b71d4b62 RA |
28364 | This AI places restrictions on allowed instantiations of generic containers. |
28365 | These restrictions are not checked by the compiler, so there is nothing to | |
28366 | change in the implementation. This affects only the RM documentation. | |
64d5610f | 28367 | |
b71d4b62 | 28368 | 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 |
28369 | @end itemize |
28370 | ||
b71d4b62 | 28371 | @geindex AI-0127 (Ada 2012 feature) |
64d5610f ML |
28372 | |
28373 | ||
28374 | @itemize * | |
28375 | ||
28376 | @item | |
b71d4b62 | 28377 | `AI-0127 Adding Locale Capabilities (2010-09-29)' |
64d5610f | 28378 | |
b71d4b62 | 28379 | This package provides an interface for identifying the current locale. |
64d5610f | 28380 | |
b71d4b62 RA |
28381 | RM References: A.19 A.19.01 A.19.02 A.19.03 A.19.05 A.19.06 |
28382 | A.19.07 A.19.08 A.19.09 A.19.10 A.19.11 A.19.12 A.19.13 | |
64d5610f ML |
28383 | @end itemize |
28384 | ||
b71d4b62 | 28385 | @geindex AI-0002 (Ada 2012 feature) |
64d5610f ML |
28386 | |
28387 | ||
28388 | @itemize * | |
28389 | ||
28390 | @item | |
b71d4b62 | 28391 | `AI-0002 Export C with unconstrained arrays (0000-00-00)' |
64d5610f | 28392 | |
b71d4b62 RA |
28393 | The compiler is not required to support exporting an Ada subprogram with |
28394 | convention C if there are parameters or a return type of an unconstrained | |
28395 | array type (such as @code{String}). GNAT allows such declarations but | |
28396 | generates warnings. It is possible, but complicated, to write the | |
28397 | corresponding C code and certainly such code would be specific to GNAT and | |
28398 | non-portable. | |
64d5610f | 28399 | |
b71d4b62 | 28400 | RM References: B.01 (17) B.03 (62) B.03 (71.1/2) |
64d5610f ML |
28401 | @end itemize |
28402 | ||
b71d4b62 | 28403 | @geindex AI05-0216 (Ada 2012 feature) |
64d5610f ML |
28404 | |
28405 | ||
28406 | @itemize * | |
28407 | ||
28408 | @item | |
b71d4b62 | 28409 | `AI-0216 No_Task_Hierarchy forbids local tasks (0000-00-00)' |
64d5610f | 28410 | |
b71d4b62 RA |
28411 | It is clearly the intention that @code{No_Task_Hierarchy} is intended to |
28412 | forbid tasks declared locally within subprograms, or functions returning task | |
28413 | objects, and that is the implementation that GNAT has always provided. | |
28414 | However the language in the RM was not sufficiently clear on this point. | |
28415 | Thus this is a documentation change in the RM only. | |
64d5610f | 28416 | |
b71d4b62 | 28417 | RM References: D.07 (3/3) |
64d5610f ML |
28418 | @end itemize |
28419 | ||
b71d4b62 | 28420 | @geindex AI-0211 (Ada 2012 feature) |
64d5610f ML |
28421 | |
28422 | ||
28423 | @itemize * | |
28424 | ||
28425 | @item | |
b71d4b62 | 28426 | `AI-0211 No_Relative_Delays forbids Set_Handler use (2010-07-09)' |
64d5610f | 28427 | |
b71d4b62 RA |
28428 | The restriction @code{No_Relative_Delays} forbids any calls to the subprogram |
28429 | @code{Ada.Real_Time.Timing_Events.Set_Handler}. | |
64d5610f | 28430 | |
b71d4b62 | 28431 | RM References: D.07 (5) D.07 (10/2) D.07 (10.4/2) D.07 (10.7/2) |
64d5610f ML |
28432 | @end itemize |
28433 | ||
b71d4b62 | 28434 | @geindex AI-0190 (Ada 2012 feature) |
64d5610f ML |
28435 | |
28436 | ||
28437 | @itemize * | |
28438 | ||
28439 | @item | |
b71d4b62 | 28440 | `AI-0190 pragma Default_Storage_Pool (2010-09-15)' |
64d5610f | 28441 | |
b71d4b62 RA |
28442 | This AI introduces a new pragma @code{Default_Storage_Pool}, which can be |
28443 | used to control storage pools globally. | |
28444 | In particular, you can force every access | |
28445 | type that is used for allocation (`new') to have an explicit storage pool, | |
28446 | or you can declare a pool globally to be used for all access types that lack | |
28447 | an explicit one. | |
64d5610f | 28448 | |
b71d4b62 | 28449 | RM References: D.07 (8) |
64d5610f ML |
28450 | @end itemize |
28451 | ||
b71d4b62 | 28452 | @geindex AI-0189 (Ada 2012 feature) |
64d5610f ML |
28453 | |
28454 | ||
28455 | @itemize * | |
28456 | ||
28457 | @item | |
b71d4b62 | 28458 | `AI-0189 No_Allocators_After_Elaboration (2010-01-23)' |
64d5610f | 28459 | |
b71d4b62 RA |
28460 | This AI introduces a new restriction @code{No_Allocators_After_Elaboration}, |
28461 | which says that no dynamic allocation will occur once elaboration is | |
28462 | completed. | |
28463 | In general this requires a run-time check, which is not required, and which | |
28464 | GNAT does not attempt. But the static cases of allocators in a task body or | |
28465 | in the body of the main program are detected and flagged at compile or bind | |
28466 | time. | |
64d5610f | 28467 | |
b71d4b62 | 28468 | RM References: D.07 (19.1/2) H.04 (23.3/2) |
64d5610f ML |
28469 | @end itemize |
28470 | ||
b71d4b62 | 28471 | @geindex AI-0171 (Ada 2012 feature) |
64d5610f ML |
28472 | |
28473 | ||
28474 | @itemize * | |
28475 | ||
28476 | @item | |
b71d4b62 | 28477 | `AI-0171 Pragma CPU and Ravenscar Profile (2010-09-24)' |
64d5610f | 28478 | |
b71d4b62 RA |
28479 | A new package @code{System.Multiprocessors} is added, together with the |
28480 | definition of pragma @code{CPU} for controlling task affinity. A new no | |
28481 | dependence restriction, on @code{System.Multiprocessors.Dispatching_Domains}, | |
28482 | is added to the Ravenscar profile. | |
64d5610f | 28483 | |
b71d4b62 | 28484 | RM References: D.13.01 (4/2) D.16 |
64d5610f ML |
28485 | @end itemize |
28486 | ||
b71d4b62 | 28487 | @geindex AI-0210 (Ada 2012 feature) |
64d5610f ML |
28488 | |
28489 | ||
28490 | @itemize * | |
28491 | ||
28492 | @item | |
b71d4b62 | 28493 | `AI-0210 Correct Timing_Events metric (0000-00-00)' |
64d5610f | 28494 | |
b71d4b62 RA |
28495 | This is a documentation only issue regarding wording of metric requirements, |
28496 | that does not affect the implementation of the compiler. | |
64d5610f | 28497 | |
b71d4b62 | 28498 | RM References: D.15 (24/2) |
64d5610f ML |
28499 | @end itemize |
28500 | ||
b71d4b62 | 28501 | @geindex AI-0206 (Ada 2012 feature) |
64d5610f ML |
28502 | |
28503 | ||
28504 | @itemize * | |
28505 | ||
28506 | @item | |
b71d4b62 | 28507 | `AI-0206 Remote types packages and preelaborate (2010-07-24)' |
64d5610f | 28508 | |
b71d4b62 RA |
28509 | Remote types packages are now allowed to depend on preelaborated packages. |
28510 | This was formerly considered illegal. | |
64d5610f | 28511 | |
b71d4b62 | 28512 | RM References: E.02.02 (6) |
64d5610f ML |
28513 | @end itemize |
28514 | ||
b71d4b62 | 28515 | @geindex AI-0152 (Ada 2012 feature) |
64d5610f ML |
28516 | |
28517 | ||
28518 | @itemize * | |
28519 | ||
28520 | @item | |
b71d4b62 | 28521 | `AI-0152 Restriction No_Anonymous_Allocators (2010-09-08)' |
64d5610f | 28522 | |
b71d4b62 RA |
28523 | Restriction @code{No_Anonymous_Allocators} prevents the use of allocators |
28524 | where the type of the returned value is an anonymous access type. | |
64d5610f | 28525 | |
b71d4b62 | 28526 | RM References: H.04 (8/1) |
64d5610f ML |
28527 | @end itemize |
28528 | ||
b71d4b62 | 28529 | @node GNAT language extensions,Security Hardening Features,Implementation of Ada 2012 Features,Top |
04d6c745 | 28530 | @anchor{gnat_rm/gnat_language_extensions doc}@anchor{434}@anchor{gnat_rm/gnat_language_extensions gnat-language-extensions}@anchor{435}@anchor{gnat_rm/gnat_language_extensions id1}@anchor{436} |
b71d4b62 RA |
28531 | @chapter GNAT language extensions |
28532 | ||
28533 | ||
28534 | The GNAT compiler implements a certain number of language extensions on top of | |
28535 | the latest Ada standard, implementing its own extended superset of Ada. | |
28536 | ||
28537 | There are two sets of language extensions: | |
64d5610f ML |
28538 | |
28539 | ||
28540 | @itemize * | |
28541 | ||
28542 | @item | |
b71d4b62 RA |
28543 | The first is the curated set. The features in that set are features that we |
28544 | consider being worthy additions to the Ada language, and that we want to make | |
28545 | available to users early on. | |
64d5610f | 28546 | |
b71d4b62 RA |
28547 | @item |
28548 | The second is the experimental set. It includes the first, but also | |
28549 | experimental features, that are here because they’re still in an early | |
28550 | prototyping phase. | |
64d5610f ML |
28551 | @end itemize |
28552 | ||
b71d4b62 RA |
28553 | @menu |
28554 | * How to activate the extended GNAT Ada superset:: | |
28555 | * Curated Extensions:: | |
28556 | * Experimental Language Extensions:: | |
64d5610f | 28557 | |
b71d4b62 | 28558 | @end menu |
64d5610f | 28559 | |
b71d4b62 | 28560 | @node How to activate the extended GNAT Ada superset,Curated Extensions,,GNAT language extensions |
04d6c745 | 28561 | @anchor{gnat_rm/gnat_language_extensions how-to-activate-the-extended-gnat-ada-superset}@anchor{437} |
b71d4b62 | 28562 | @section How to activate the extended GNAT Ada superset |
64d5610f | 28563 | |
64d5610f | 28564 | |
b71d4b62 | 28565 | There are two ways to activate the extended GNAT Ada superset: |
64d5610f | 28566 | |
b71d4b62 RA |
28567 | |
28568 | @itemize * | |
28569 | ||
28570 | @item | |
28571 | The @ref{65,,Pragma Extensions_Allowed}. To activate | |
28572 | the curated set of extensions, you should use | |
64d5610f ML |
28573 | @end itemize |
28574 | ||
b71d4b62 RA |
28575 | @example |
28576 | pragma Extensions_Allowed (On) | |
28577 | @end example | |
28578 | ||
28579 | As a configuration pragma, you can either put it at the beginning of a source | |
28580 | file, or in a @code{.adc} file corresponding to your project. | |
64d5610f ML |
28581 | |
28582 | ||
28583 | @itemize * | |
28584 | ||
28585 | @item | |
b71d4b62 RA |
28586 | The @code{-gnatX} option, that you can pass to the compiler directly, will |
28587 | activate the curated subset of extensions. | |
28588 | @end itemize | |
64d5610f | 28589 | |
b71d4b62 RA |
28590 | @cartouche |
28591 | @quotation Attention | |
28592 | You can activate the extended set of extensions by using either | |
28593 | the @code{-gnatX0} command line flag, or the pragma @code{Extensions_Allowed} with | |
28594 | @code{All} as an argument. However, it is not recommended you use this subset | |
28595 | for serious projects, and is only means as a playground/technology preview. | |
28596 | @end quotation | |
28597 | @end cartouche | |
64d5610f | 28598 | |
b71d4b62 | 28599 | @node Curated Extensions,Experimental Language Extensions,How to activate the extended GNAT Ada superset,GNAT language extensions |
04d6c745 | 28600 | @anchor{gnat_rm/gnat_language_extensions curated-extensions}@anchor{438}@anchor{gnat_rm/gnat_language_extensions curated-language-extensions}@anchor{66} |
b71d4b62 | 28601 | @section Curated Extensions |
64d5610f | 28602 | |
64d5610f | 28603 | |
b71d4b62 | 28604 | @menu |
9105cd90 | 28605 | * Local Declarations Without Block:: |
b71d4b62 RA |
28606 | * Conditional when constructs:: |
28607 | * Case pattern matching:: | |
28608 | * Fixed lower bounds for array types and subtypes:: | |
28609 | * Prefixed-view notation for calls to primitive subprograms of untagged types:: | |
28610 | * Expression defaults for generic formal functions:: | |
28611 | * String interpolation:: | |
28612 | * Constrained attribute for generic objects:: | |
28613 | * Static aspect on intrinsic functions:: | |
64d5610f | 28614 | |
b71d4b62 | 28615 | @end menu |
64d5610f | 28616 | |
9105cd90 | 28617 | @node Local Declarations Without Block,Conditional when constructs,,Curated Extensions |
04d6c745 | 28618 | @anchor{gnat_rm/gnat_language_extensions local-declarations-without-block}@anchor{439} |
9105cd90 BD |
28619 | @subsection Local Declarations Without Block |
28620 | ||
28621 | ||
28622 | A basic_declarative_item may appear at the place of any statement. | |
28623 | This avoids the heavy syntax of block_statements just to declare | |
28624 | something locally. | |
28625 | ||
28626 | Link to the original RFC: | |
28627 | @indicateurl{https://github.com/AdaCore/ada-spark-rfcs/blob/master/prototyped/rfc-local-vars-without-block.md} | |
28628 | For example: | |
28629 | ||
28630 | @example | |
28631 | if X > 5 then | |
28632 | X := X + 1; | |
28633 | ||
28634 | Squared : constant Integer := X**2; | |
28635 | ||
28636 | X := X + Squared; | |
28637 | end if; | |
28638 | @end example | |
28639 | ||
28640 | @node Conditional when constructs,Case pattern matching,Local Declarations Without Block,Curated Extensions | |
04d6c745 | 28641 | @anchor{gnat_rm/gnat_language_extensions conditional-when-constructs}@anchor{43a} |
b71d4b62 | 28642 | @subsection Conditional when constructs |
64d5610f | 28643 | |
64d5610f | 28644 | |
b71d4b62 RA |
28645 | This feature extends the use of @code{when} as a way to condition a control-flow |
28646 | related statement, to all control-flow related statements. | |
64d5610f | 28647 | |
b71d4b62 | 28648 | To do a conditional return in a procedure the following syntax should be used: |
64d5610f | 28649 | |
b71d4b62 RA |
28650 | @example |
28651 | procedure P (Condition : Boolean) is | |
28652 | begin | |
28653 | return when Condition; | |
28654 | end; | |
28655 | @end example | |
64d5610f | 28656 | |
b71d4b62 | 28657 | This will return from the procedure if @code{Condition} is true. |
64d5610f | 28658 | |
b71d4b62 | 28659 | When being used in a function the conditional part comes after the return value: |
64d5610f | 28660 | |
b71d4b62 RA |
28661 | @example |
28662 | function Is_Null (I : Integer) return Boolean is | |
28663 | begin | |
28664 | return True when I = 0; | |
28665 | return False; | |
28666 | end; | |
28667 | @end example | |
64d5610f | 28668 | |
b71d4b62 | 28669 | In a similar way to the @code{exit when} a @code{goto ... when} can be employed: |
64d5610f | 28670 | |
b71d4b62 RA |
28671 | @example |
28672 | procedure Low_Level_Optimized is | |
28673 | Flags : Bitmapping; | |
28674 | begin | |
28675 | Do_1 (Flags); | |
28676 | goto Cleanup when Flags (1); | |
64d5610f | 28677 | |
b71d4b62 RA |
28678 | Do_2 (Flags); |
28679 | goto Cleanup when Flags (32); | |
64d5610f | 28680 | |
b71d4b62 | 28681 | -- ... |
64d5610f | 28682 | |
b71d4b62 RA |
28683 | <<Cleanup>> |
28684 | -- ... | |
28685 | end; | |
28686 | @end example | |
64d5610f | 28687 | |
b71d4b62 | 28688 | @c code-block |
64d5610f | 28689 | |
b71d4b62 | 28690 | To use a conditional raise construct: |
64d5610f | 28691 | |
b71d4b62 RA |
28692 | @example |
28693 | procedure Foo is | |
28694 | begin | |
28695 | raise Error when Imported_C_Func /= 0; | |
28696 | end; | |
28697 | @end example | |
64d5610f | 28698 | |
b71d4b62 | 28699 | An exception message can also be added: |
64d5610f | 28700 | |
b71d4b62 RA |
28701 | @example |
28702 | procedure Foo is | |
28703 | begin | |
28704 | raise Error with "Unix Error" | |
28705 | when Imported_C_Func /= 0; | |
28706 | end; | |
28707 | @end example | |
64d5610f | 28708 | |
b71d4b62 RA |
28709 | Link to the original RFC: |
28710 | @indicateurl{https://github.com/AdaCore/ada-spark-rfcs/blob/master/prototyped/rfc-conditional-when-constructs.rst} | |
64d5610f | 28711 | |
b71d4b62 | 28712 | @node Case pattern matching,Fixed lower bounds for array types and subtypes,Conditional when constructs,Curated Extensions |
04d6c745 | 28713 | @anchor{gnat_rm/gnat_language_extensions case-pattern-matching}@anchor{43b} |
b71d4b62 | 28714 | @subsection Case pattern matching |
64d5610f | 28715 | |
64d5610f | 28716 | |
b8a3e2ed | 28717 | The selector for a case statement (but not yet for a case expression) may be of a composite type, subject to |
b71d4b62 RA |
28718 | some restrictions (described below). Aggregate syntax is used for choices |
28719 | of such a case statement; however, in cases where a “normal” aggregate would | |
28720 | require a discrete value, a discrete subtype may be used instead; box | |
28721 | notation can also be used to match all values. | |
64d5610f | 28722 | |
b71d4b62 | 28723 | Consider this example: |
64d5610f | 28724 | |
b71d4b62 RA |
28725 | @example |
28726 | type Rec is record | |
28727 | F1, F2 : Integer; | |
28728 | end record; | |
64d5610f | 28729 | |
b71d4b62 RA |
28730 | procedure Caser_1 (X : Rec) is |
28731 | begin | |
28732 | case X is | |
28733 | when (F1 => Positive, F2 => Positive) => | |
28734 | Do_This; | |
28735 | when (F1 => Natural, F2 => <>) | (F1 => <>, F2 => Natural) => | |
28736 | Do_That; | |
28737 | when others => | |
28738 | Do_The_Other_Thing; | |
28739 | end case; | |
28740 | end Caser_1; | |
28741 | @end example | |
64d5610f | 28742 | |
b71d4b62 RA |
28743 | If @code{Caser_1} is called and both components of X are positive, then |
28744 | @code{Do_This} will be called; otherwise, if either component is nonnegative | |
28745 | then @code{Do_That} will be called; otherwise, @code{Do_The_Other_Thing} will be | |
28746 | called. | |
64d5610f | 28747 | |
b71d4b62 RA |
28748 | In addition, pattern bindings are supported. This is a mechanism |
28749 | for binding a name to a component of a matching value for use within | |
28750 | an alternative of a case statement. For a component association | |
28751 | that occurs within a case choice, the expression may be followed by | |
28752 | @code{is <identifier>}. In the special case of a “box” component association, | |
28753 | the identifier may instead be provided within the box. Either of these | |
28754 | indicates that the given identifier denotes (a constant view of) the matching | |
28755 | subcomponent of the case selector. | |
64d5610f | 28756 | |
b71d4b62 RA |
28757 | @cartouche |
28758 | @quotation Attention | |
28759 | Binding is not yet supported for arrays or subcomponents | |
28760 | thereof. | |
28761 | @end quotation | |
28762 | @end cartouche | |
64d5610f | 28763 | |
b71d4b62 | 28764 | Consider this example (which uses type @code{Rec} from the previous example): |
64d5610f | 28765 | |
b71d4b62 RA |
28766 | @example |
28767 | procedure Caser_2 (X : Rec) is | |
28768 | begin | |
28769 | case X is | |
28770 | when (F1 => Positive is Abc, F2 => Positive) => | |
28771 | Do_This (Abc) | |
28772 | when (F1 => Natural is N1, F2 => <N2>) | | |
28773 | (F1 => <N2>, F2 => Natural is N1) => | |
28774 | Do_That (Param_1 => N1, Param_2 => N2); | |
28775 | when others => | |
28776 | Do_The_Other_Thing; | |
28777 | end case; | |
28778 | end Caser_2; | |
28779 | @end example | |
64d5610f | 28780 | |
b71d4b62 RA |
28781 | This example is the same as the previous one with respect to determining |
28782 | whether @code{Do_This}, @code{Do_That}, or @code{Do_The_Other_Thing} will be called. But | |
28783 | for this version, @code{Do_This} takes a parameter and @code{Do_That} takes two | |
28784 | parameters. If @code{Do_This} is called, the actual parameter in the call will be | |
28785 | @code{X.F1}. | |
64d5610f | 28786 | |
b71d4b62 RA |
28787 | If @code{Do_That} is called, the situation is more complex because there are two |
28788 | choices for that alternative. If @code{Do_That} is called because the first choice | |
28789 | matched (i.e., because @code{X.F1} is nonnegative and either @code{X.F1} or @code{X.F2} | |
28790 | is zero or negative), then the actual parameters of the call will be (in order) | |
28791 | @code{X.F1} and @code{X.F2}. If @code{Do_That} is called because the second choice | |
28792 | matched (and the first one did not), then the actual parameters will be | |
28793 | reversed. | |
64d5610f | 28794 | |
b71d4b62 RA |
28795 | Within the choice list for single alternative, each choice must define the same |
28796 | set of bindings and the component subtypes for for a given identifer must all | |
28797 | statically match. Currently, the case of a binding for a nondiscrete component | |
28798 | is not implemented. | |
64d5610f | 28799 | |
b71d4b62 RA |
28800 | If the set of values that match the choice(s) of an earlier alternative |
28801 | overlaps the corresponding set of a later alternative, then the first set shall | |
28802 | be a proper subset of the second (and the later alternative will not be | |
28803 | executed if the earlier alternative “matches”). All possible values of the | |
28804 | composite type shall be covered. The composite type of the selector shall be an | |
28805 | array or record type that is neither limited nor class-wide. Currently, a “when | |
28806 | others =>” case choice is required; it is intended that this requirement will | |
28807 | be relaxed at some point. | |
64d5610f | 28808 | |
b71d4b62 RA |
28809 | If a subcomponent’s subtype does not meet certain restrictions, then the only |
28810 | value that can be specified for that subcomponent in a case choice expression | |
28811 | is a “box” component association (which matches all possible values for the | |
28812 | subcomponent). This restriction applies if: | |
64d5610f | 28813 | |
64d5610f | 28814 | |
b71d4b62 | 28815 | @itemize - |
64d5610f | 28816 | |
b71d4b62 RA |
28817 | @item |
28818 | the component subtype is not a record, array, or discrete type; or | |
64d5610f ML |
28819 | |
28820 | @item | |
b71d4b62 RA |
28821 | the component subtype is subject to a non-static constraint or has a |
28822 | predicate; or: | |
64d5610f | 28823 | |
b71d4b62 RA |
28824 | @item |
28825 | the component type is an enumeration type that is subject to an enumeration | |
28826 | representation clause; or | |
64d5610f | 28827 | |
b71d4b62 RA |
28828 | @item |
28829 | the component type is a multidimensional array type or an array type with a | |
28830 | nonstatic index subtype. | |
64d5610f ML |
28831 | @end itemize |
28832 | ||
b71d4b62 RA |
28833 | Support for casing on arrays (and on records that contain arrays) is |
28834 | currently subject to some restrictions. Non-positional | |
28835 | array aggregates are not supported as (or within) case choices. Likewise | |
28836 | for array type and subtype names. The current implementation exceeds | |
28837 | compile-time capacity limits in some annoyingly common scenarios; the | |
28838 | message generated in such cases is usually “Capacity exceeded in compiling | |
28839 | case statement with composite selector type”. | |
64d5610f | 28840 | |
b71d4b62 RA |
28841 | Link to the original RFC: |
28842 | @indicateurl{https://github.com/AdaCore/ada-spark-rfcs/blob/master/prototyped/rfc-pattern-matching.rst} | |
64d5610f | 28843 | |
b71d4b62 | 28844 | @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 |
04d6c745 | 28845 | @anchor{gnat_rm/gnat_language_extensions fixed-lower-bounds-for-array-types-and-subtypes}@anchor{43c} |
b71d4b62 | 28846 | @subsection Fixed lower bounds for array types and subtypes |
64d5610f | 28847 | |
64d5610f | 28848 | |
b71d4b62 RA |
28849 | Unconstrained array types and subtypes can be specified with a lower bound that |
28850 | is fixed to a certain value, by writing an index range that uses the syntax | |
28851 | @code{<lower-bound-expression> .. <>}. This guarantees that all objects of the | |
28852 | type or subtype will have the specified lower bound. | |
64d5610f | 28853 | |
b71d4b62 RA |
28854 | For example, a matrix type with fixed lower bounds of zero for each dimension |
28855 | can be declared by the following: | |
64d5610f | 28856 | |
b71d4b62 RA |
28857 | @example |
28858 | type Matrix is | |
28859 | array (Natural range 0 .. <>, Natural range 0 .. <>) of Integer; | |
28860 | @end example | |
64d5610f | 28861 | |
b71d4b62 RA |
28862 | Objects of type @code{Matrix} declared with an index constraint must have index |
28863 | ranges starting at zero: | |
64d5610f | 28864 | |
b71d4b62 RA |
28865 | @example |
28866 | M1 : Matrix (0 .. 9, 0 .. 19); | |
28867 | M2 : Matrix (2 .. 11, 3 .. 22); -- Warning about bounds; will raise CE | |
28868 | @end example | |
64d5610f | 28869 | |
b71d4b62 RA |
28870 | Similarly, a subtype of @code{String} can be declared that specifies the lower |
28871 | bound of objects of that subtype to be @code{1}: | |
64d5610f | 28872 | |
b71d4b62 | 28873 | @quotation |
64d5610f | 28874 | |
b71d4b62 RA |
28875 | @example |
28876 | subtype String_1 is String (1 .. <>); | |
28877 | @end example | |
28878 | @end quotation | |
64d5610f | 28879 | |
b71d4b62 RA |
28880 | If a string slice is passed to a formal of subtype @code{String_1} in a call to a |
28881 | subprogram @code{S}, the slice’s bounds will “slide” so that the lower bound is | |
28882 | @code{1}. | |
64d5610f | 28883 | |
b71d4b62 RA |
28884 | Within @code{S}, the lower bound of the formal is known to be @code{1}, so, unlike a |
28885 | normal unconstrained @code{String} formal, there is no need to worry about | |
28886 | accounting for other possible lower-bound values. Sliding of bounds also occurs | |
28887 | in other contexts, such as for object declarations with an unconstrained | |
28888 | subtype with fixed lower bound, as well as in subtype conversions. | |
64d5610f | 28889 | |
b71d4b62 RA |
28890 | Use of this feature increases safety by simplifying code, and can also improve |
28891 | the efficiency of indexing operations, since the compiler statically knows the | |
28892 | lower bound of unconstrained array formals when the formal’s subtype has index | |
28893 | ranges with static fixed lower bounds. | |
64d5610f | 28894 | |
b71d4b62 RA |
28895 | Link to the original RFC: |
28896 | @indicateurl{https://github.com/AdaCore/ada-spark-rfcs/blob/master/prototyped/rfc-fixed-lower-bound.rst} | |
64d5610f | 28897 | |
b71d4b62 | 28898 | @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 |
04d6c745 | 28899 | @anchor{gnat_rm/gnat_language_extensions prefixed-view-notation-for-calls-to-primitive-subprograms-of-untagged-types}@anchor{43d} |
b71d4b62 RA |
28900 | @subsection Prefixed-view notation for calls to primitive subprograms of untagged types |
28901 | ||
28902 | ||
28903 | When operating on an untagged type, if it has any primitive operations, and the | |
28904 | first parameter of an operation is of the type (or is an access parameter with | |
28905 | an anonymous type that designates the type), you may invoke these operations | |
28906 | using an @code{object.op(...)} notation, where the parameter that would normally be | |
28907 | the first parameter is brought out front, and the remaining parameters (if any) | |
28908 | appear within parentheses after the name of the primitive operation. | |
28909 | ||
28910 | This same notation is already available for tagged types. This extension allows | |
28911 | for untagged types. It is allowed for all primitive operations of the type | |
28912 | independent of whether they were originally declared in a package spec or its | |
28913 | private part, or were inherited and/or overridden as part of a derived type | |
28914 | declaration occuring anywhere, so long as the first parameter is of the type, | |
28915 | or an access parameter designating the type. | |
28916 | ||
28917 | For example: | |
28918 | ||
28919 | @example | |
28920 | generic | |
28921 | type Elem_Type is private; | |
28922 | package Vectors is | |
28923 | type Vector is private; | |
28924 | procedure Add_Element (V : in out Vector; Elem : Elem_Type); | |
28925 | function Nth_Element (V : Vector; N : Positive) return Elem_Type; | |
28926 | function Length (V : Vector) return Natural; | |
28927 | private | |
28928 | function Capacity (V : Vector) return Natural; | |
28929 | -- Return number of elements that may be added without causing | |
28930 | -- any new allocation of space | |
28931 | ||
28932 | type Vector is ... | |
28933 | with Type_Invariant => Vector.Length <= Vector.Capacity; | |
28934 | ... | |
28935 | end Vectors; | |
28936 | ||
28937 | package Int_Vecs is new Vectors(Integer); | |
64d5610f | 28938 | |
b71d4b62 RA |
28939 | V : Int_Vecs.Vector; |
28940 | ... | |
28941 | V.Add_Element(42); | |
28942 | V.Add_Element(-33); | |
64d5610f | 28943 | |
b71d4b62 RA |
28944 | pragma Assert (V.Length = 2); |
28945 | pragma Assert (V.Nth_Element(1) = 42); | |
28946 | @end example | |
64d5610f | 28947 | |
b71d4b62 RA |
28948 | Link to the original RFC: |
28949 | @indicateurl{https://github.com/AdaCore/ada-spark-rfcs/blob/master/prototyped/rfc-prefixed-untagged.rst} | |
64d5610f | 28950 | |
b71d4b62 | 28951 | @node Expression defaults for generic formal functions,String interpolation,Prefixed-view notation for calls to primitive subprograms of untagged types,Curated Extensions |
04d6c745 | 28952 | @anchor{gnat_rm/gnat_language_extensions expression-defaults-for-generic-formal-functions}@anchor{43e} |
b71d4b62 | 28953 | @subsection Expression defaults for generic formal functions |
64d5610f | 28954 | |
64d5610f | 28955 | |
b71d4b62 RA |
28956 | The declaration of a generic formal function is allowed to specify |
28957 | an expression as a default, using the syntax of an expression function. | |
64d5610f | 28958 | |
b71d4b62 | 28959 | Here is an example of this feature: |
64d5610f | 28960 | |
b71d4b62 RA |
28961 | @example |
28962 | generic | |
28963 | type T is private; | |
28964 | with function Copy (Item : T) return T is (Item); -- Defaults to Item | |
28965 | package Stacks is | |
64d5610f | 28966 | |
b71d4b62 | 28967 | type Stack is limited private; |
64d5610f | 28968 | |
b71d4b62 RA |
28969 | procedure Push (S : in out Stack; X : T); -- Calls Copy on X |
28970 | function Pop (S : in out Stack) return T; -- Calls Copy to return item | |
64d5610f | 28971 | |
b71d4b62 RA |
28972 | private |
28973 | -- ... | |
28974 | end Stacks; | |
28975 | @end example | |
64d5610f | 28976 | |
b71d4b62 RA |
28977 | Link to the original RFC: |
28978 | @indicateurl{https://github.com/AdaCore/ada-spark-rfcs/blob/master/prototyped/rfc-expression-functions-as-default-for-generic-formal-function-parameters.rst} | |
64d5610f | 28979 | |
b71d4b62 | 28980 | @node String interpolation,Constrained attribute for generic objects,Expression defaults for generic formal functions,Curated Extensions |
04d6c745 | 28981 | @anchor{gnat_rm/gnat_language_extensions string-interpolation}@anchor{43f} |
b71d4b62 | 28982 | @subsection String interpolation |
64d5610f | 28983 | |
64d5610f | 28984 | |
b71d4b62 | 28985 | The syntax for string literals is extended to support string interpolation. |
64d5610f | 28986 | |
b71d4b62 RA |
28987 | Within an interpolated string literal, an arbitrary expression, when |
28988 | enclosed in @code{@{ ... @}}, is expanded at run time into the result of calling | |
28989 | @code{'Image} on the result of evaluating the expression enclosed by the brace | |
28990 | characters, unless it is already a string or a single character. | |
64d5610f | 28991 | |
b71d4b62 RA |
28992 | Here is an example of this feature where the expressions @code{Name} and @code{X + Y} |
28993 | will be evaluated and included in the string. | |
64d5610f | 28994 | |
b71d4b62 RA |
28995 | @example |
28996 | procedure Test_Interpolation is | |
28997 | X : Integer := 12; | |
28998 | Y : Integer := 15; | |
28999 | Name : String := "Leo"; | |
29000 | begin | |
29001 | Put_Line (f"The name is @{Name@} and the sum is @{X + Y@}."); | |
29002 | end Test_Interpolation; | |
29003 | @end example | |
64d5610f | 29004 | |
b71d4b62 RA |
29005 | In addition, an escape character (@code{\}) is provided for inserting certain |
29006 | standard control characters (such as @code{\t} for tabulation or @code{\n} for | |
29007 | newline) or to escape characters with special significance to the | |
29008 | interpolated string syntax, namely @code{"}, @code{@{}, @code{@}},and @code{\} itself. | |
64d5610f | 29009 | |
64d5610f | 29010 | |
b71d4b62 RA |
29011 | @multitable {xxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxx} |
29012 | @item | |
64d5610f | 29013 | |
b71d4b62 | 29014 | escaped_character |
64d5610f | 29015 | |
b71d4b62 | 29016 | @tab |
64d5610f | 29017 | |
b71d4b62 | 29018 | meaning |
64d5610f | 29019 | |
b71d4b62 | 29020 | @item |
64d5610f | 29021 | |
b71d4b62 | 29022 | @code{\a} |
64d5610f | 29023 | |
b71d4b62 | 29024 | @tab |
64d5610f | 29025 | |
b71d4b62 | 29026 | ALERT |
64d5610f | 29027 | |
b71d4b62 | 29028 | @item |
64d5610f | 29029 | |
b71d4b62 | 29030 | @code{\b} |
64d5610f | 29031 | |
b71d4b62 | 29032 | @tab |
64d5610f | 29033 | |
b71d4b62 | 29034 | BACKSPACE |
64d5610f | 29035 | |
b71d4b62 | 29036 | @item |
64d5610f | 29037 | |
b71d4b62 | 29038 | @code{\f} |
64d5610f | 29039 | |
b71d4b62 | 29040 | @tab |
64d5610f | 29041 | |
b71d4b62 | 29042 | FORM FEED |
64d5610f | 29043 | |
b71d4b62 | 29044 | @item |
64d5610f | 29045 | |
b71d4b62 | 29046 | @code{\n} |
64d5610f | 29047 | |
b71d4b62 | 29048 | @tab |
64d5610f | 29049 | |
b71d4b62 | 29050 | LINE FEED |
64d5610f | 29051 | |
b71d4b62 | 29052 | @item |
64d5610f | 29053 | |
b71d4b62 | 29054 | @code{\r} |
64d5610f | 29055 | |
b71d4b62 | 29056 | @tab |
64d5610f | 29057 | |
b71d4b62 | 29058 | CARRIAGE RETURN |
64d5610f | 29059 | |
b71d4b62 | 29060 | @item |
64d5610f | 29061 | |
b71d4b62 | 29062 | @code{\t} |
64d5610f | 29063 | |
b71d4b62 | 29064 | @tab |
64d5610f | 29065 | |
b71d4b62 | 29066 | CHARACTER TABULATION |
64d5610f | 29067 | |
b71d4b62 | 29068 | @item |
64d5610f | 29069 | |
b71d4b62 | 29070 | @code{\v} |
64d5610f | 29071 | |
b71d4b62 | 29072 | @tab |
64d5610f | 29073 | |
b71d4b62 | 29074 | LINE TABULATION |
64d5610f | 29075 | |
b71d4b62 | 29076 | @item |
64d5610f | 29077 | |
b71d4b62 | 29078 | @code{\0} |
64d5610f | 29079 | |
b71d4b62 | 29080 | @tab |
64d5610f | 29081 | |
b71d4b62 | 29082 | NUL |
64d5610f | 29083 | |
b71d4b62 | 29084 | @item |
64d5610f | 29085 | |
b71d4b62 | 29086 | @code{\\} |
64d5610f | 29087 | |
b71d4b62 | 29088 | @tab |
64d5610f | 29089 | |
b71d4b62 | 29090 | @code{\} |
64d5610f | 29091 | |
b71d4b62 | 29092 | @item |
64d5610f | 29093 | |
b71d4b62 | 29094 | @code{\"} |
64d5610f | 29095 | |
b71d4b62 | 29096 | @tab |
64d5610f | 29097 | |
b71d4b62 | 29098 | @code{"} |
64d5610f | 29099 | |
b71d4b62 | 29100 | @item |
64d5610f | 29101 | |
b71d4b62 | 29102 | @code{\@{} |
64d5610f | 29103 | |
b71d4b62 | 29104 | @tab |
64d5610f | 29105 | |
b71d4b62 | 29106 | @code{@{} |
64d5610f | 29107 | |
b71d4b62 | 29108 | @item |
64d5610f | 29109 | |
b71d4b62 | 29110 | @code{\@}} |
64d5610f | 29111 | |
b71d4b62 | 29112 | @tab |
64d5610f | 29113 | |
b71d4b62 | 29114 | @code{@}} |
64d5610f | 29115 | |
b71d4b62 | 29116 | @end multitable |
64d5610f | 29117 | |
64d5610f | 29118 | |
b71d4b62 RA |
29119 | Note that, unlike normal string literals, doubled characters have no |
29120 | special significance. So to include a double-quote or a brace character | |
29121 | in an interpolated string, they must be preceded by a @code{\}. | |
29122 | For example: | |
64d5610f | 29123 | |
b71d4b62 RA |
29124 | @example |
29125 | Put_Line | |
29126 | (f"X = @{X@} and Y = @{Y@} and X+Y = @{X+Y@};\n" & | |
29127 | f" a double quote is \" and" & | |
29128 | f" an open brace is \@{"); | |
29129 | @end example | |
64d5610f | 29130 | |
b71d4b62 RA |
29131 | Finally, a syntax is provided for creating multi-line string literals, |
29132 | without having to explicitly use an escape sequence such as @code{\n}. For | |
29133 | example: | |
64d5610f | 29134 | |
b71d4b62 RA |
29135 | @example |
29136 | Put_Line | |
29137 | (f"This is a multi-line" | |
29138 | "string literal" | |
29139 | "There is no ambiguity about how many" | |
29140 | "spaces are included in each line"); | |
29141 | @end example | |
64d5610f | 29142 | |
b71d4b62 RA |
29143 | Here is a link to the original RFC : |
29144 | @indicateurl{https://github.com/AdaCore/ada-spark-rfcs/blob/master/prototyped/rfc-string-interpolation.rst} | |
64d5610f | 29145 | |
b71d4b62 | 29146 | @node Constrained attribute for generic objects,Static aspect on intrinsic functions,String interpolation,Curated Extensions |
04d6c745 | 29147 | @anchor{gnat_rm/gnat_language_extensions constrained-attribute-for-generic-objects}@anchor{440} |
b71d4b62 | 29148 | @subsection Constrained attribute for generic objects |
64d5610f ML |
29149 | |
29150 | ||
b71d4b62 RA |
29151 | The @code{Constrained} attribute is permitted for objects of generic types. The |
29152 | result indicates whether the corresponding actual is constrained. | |
64d5610f | 29153 | |
b71d4b62 | 29154 | @node Static aspect on intrinsic functions,,Constrained attribute for generic objects,Curated Extensions |
04d6c745 | 29155 | @anchor{gnat_rm/gnat_language_extensions static-aspect-on-intrinsic-functions}@anchor{441} |
b71d4b62 | 29156 | @subsection @code{Static} aspect on intrinsic functions |
64d5610f | 29157 | |
64d5610f | 29158 | |
b71d4b62 RA |
29159 | The Ada 202x @code{Static} aspect can be specified on Intrinsic imported functions |
29160 | and the compiler will evaluate some of these intrinsics statically, in | |
29161 | particular the @code{Shift_Left} and @code{Shift_Right} intrinsics. | |
64d5610f | 29162 | |
b71d4b62 | 29163 | @node Experimental Language Extensions,,Curated Extensions,GNAT language extensions |
04d6c745 | 29164 | @anchor{gnat_rm/gnat_language_extensions experimental-language-extensions}@anchor{67}@anchor{gnat_rm/gnat_language_extensions id2}@anchor{442} |
b71d4b62 | 29165 | @section Experimental Language Extensions |
64d5610f ML |
29166 | |
29167 | ||
b71d4b62 RA |
29168 | @menu |
29169 | * Pragma Storage_Model:: | |
29170 | * Simpler accessibility model:: | |
64d5610f | 29171 | |
b71d4b62 | 29172 | @end menu |
64d5610f | 29173 | |
b71d4b62 | 29174 | @node Pragma Storage_Model,Simpler accessibility model,,Experimental Language Extensions |
04d6c745 | 29175 | @anchor{gnat_rm/gnat_language_extensions pragma-storage-model}@anchor{443} |
b71d4b62 | 29176 | @subsection Pragma Storage_Model |
64d5610f | 29177 | |
64d5610f | 29178 | |
b71d4b62 RA |
29179 | This feature proposes to redesign the concepts of Storage Pools into a more |
29180 | efficient model allowing higher performances and easier integration with low | |
29181 | footprint embedded run-times. | |
64d5610f | 29182 | |
b71d4b62 RA |
29183 | It also extends it to support distributed memory models, in particular to |
29184 | support interactions with GPU. | |
64d5610f | 29185 | |
b71d4b62 RA |
29186 | Here is a link to the full RFC: |
29187 | @indicateurl{https://github.com/AdaCore/ada-spark-rfcs/blob/master/prototyped/rfc-storage-model.rst} | |
64d5610f | 29188 | |
b71d4b62 | 29189 | @node Simpler accessibility model,,Pragma Storage_Model,Experimental Language Extensions |
04d6c745 | 29190 | @anchor{gnat_rm/gnat_language_extensions simpler-accessibility-model}@anchor{444} |
b71d4b62 | 29191 | @subsection Simpler accessibility model |
64d5610f | 29192 | |
64d5610f | 29193 | |
b71d4b62 RA |
29194 | The goal of this feature is to restore a common understanding of accessibility |
29195 | rules for implementers and users alike. The new rules should both be effective | |
29196 | at preventing errors and feel natural and compatible in an Ada environment | |
29197 | while removing dynamic accessibility checking. | |
29198 | ||
29199 | Here is a link to the full RFC: | |
29200 | @indicateurl{https://github.com/AdaCore/ada-spark-rfcs/blob/master/prototyped/rfc-simpler-accessibility.md} | |
64d5610f | 29201 | |
b71d4b62 | 29202 | @node Security Hardening Features,Obsolescent Features,GNAT language extensions,Top |
04d6c745 | 29203 | @anchor{gnat_rm/security_hardening_features doc}@anchor{445}@anchor{gnat_rm/security_hardening_features id1}@anchor{446}@anchor{gnat_rm/security_hardening_features security-hardening-features}@anchor{15} |
64d5610f ML |
29204 | @chapter Security Hardening Features |
29205 | ||
29206 | ||
29207 | This chapter describes Ada extensions aimed at security hardening that | |
29208 | are provided by GNAT. | |
29209 | ||
29210 | The features in this chapter are currently experimental and subject to | |
29211 | change. | |
29212 | ||
29213 | @c Register Scrubbing: | |
29214 | ||
29215 | @menu | |
29216 | * Register Scrubbing:: | |
29217 | * Stack Scrubbing:: | |
29218 | * Hardened Conditionals:: | |
29219 | * Hardened Booleans:: | |
29220 | * Control Flow Redundancy:: | |
29221 | ||
29222 | @end menu | |
29223 | ||
29224 | @node Register Scrubbing,Stack Scrubbing,,Security Hardening Features | |
04d6c745 | 29225 | @anchor{gnat_rm/security_hardening_features register-scrubbing}@anchor{447} |
64d5610f ML |
29226 | @section Register Scrubbing |
29227 | ||
29228 | ||
29229 | GNAT can generate code to zero-out hardware registers before returning | |
29230 | from a subprogram. | |
29231 | ||
29232 | It can be enabled with the @code{-fzero-call-used-regs=`choice'} | |
29233 | command-line option, to affect all subprograms in a compilation, and | |
29234 | with a @code{Machine_Attribute} pragma, to affect only specific | |
29235 | subprograms. | |
29236 | ||
29237 | @example | |
29238 | procedure Foo; | |
29239 | pragma Machine_Attribute (Foo, "zero_call_used_regs", "used"); | |
29240 | -- Before returning, Foo scrubs only call-clobbered registers | |
29241 | -- that it uses itself. | |
29242 | ||
29243 | function Bar return Integer; | |
29244 | pragma Machine_Attribute (Bar, "zero_call_used_regs", "all"); | |
29245 | -- Before returning, Bar scrubs all call-clobbered registers. | |
92eeb32d AO |
29246 | |
29247 | function Baz return Integer; | |
29248 | pragma Machine_Attribute (Bar, "zero_call_used_regs", "leafy"); | |
29249 | -- Before returning, Bar scrubs call-clobbered registers, either | |
29250 | -- those it uses itself, if it can be identified as a leaf | |
29251 | -- function, or all of them otherwise. | |
64d5610f ML |
29252 | @end example |
29253 | ||
29254 | For usage and more details on the command-line option, on the | |
29255 | @code{zero_call_used_regs} attribute, and on their use with other | |
29256 | programming languages, see @cite{Using the GNU Compiler Collection (GCC)}. | |
29257 | ||
29258 | @c Stack Scrubbing: | |
29259 | ||
29260 | @node Stack Scrubbing,Hardened Conditionals,Register Scrubbing,Security Hardening Features | |
04d6c745 | 29261 | @anchor{gnat_rm/security_hardening_features stack-scrubbing}@anchor{448} |
64d5610f ML |
29262 | @section Stack Scrubbing |
29263 | ||
29264 | ||
29265 | GNAT can generate code to zero-out stack frames used by subprograms. | |
29266 | ||
29267 | It can be activated with the @code{Machine_Attribute} pragma, on | |
29268 | specific subprograms and variables, or their types. (This attribute | |
29269 | always applies to a type, even when it is associated with a subprogram | |
29270 | or a variable.) | |
29271 | ||
29272 | @example | |
29273 | function Foo returns Integer; | |
29274 | pragma Machine_Attribute (Foo, "strub"); | |
29275 | -- Foo and its callers are modified so as to scrub the stack | |
29276 | -- space used by Foo after it returns. Shorthand for: | |
29277 | -- pragma Machine_Attribute (Foo, "strub", "at-calls"); | |
29278 | ||
29279 | procedure Bar; | |
29280 | pragma Machine_Attribute (Bar, "strub", "internal"); | |
29281 | -- Bar is turned into a wrapper for its original body, | |
29282 | -- and they scrub the stack used by the original body. | |
29283 | ||
29284 | Var : Integer; | |
29285 | pragma Machine_Attribute (Var, "strub"); | |
29286 | -- Reading from Var in a subprogram enables stack scrubbing | |
29287 | -- of the stack space used by the subprogram. Furthermore, if | |
29288 | -- Var is declared within a subprogram, this also enables | |
29289 | -- scrubbing of the stack space used by that subprogram. | |
29290 | @end example | |
29291 | ||
29292 | Given these declarations, Foo has its type and body modified as | |
29293 | follows: | |
29294 | ||
29295 | @example | |
29296 | function Foo (<WaterMark> : in out System.Address) returns Integer | |
29297 | is | |
29298 | -- ... | |
29299 | begin | |
29300 | <__strub_update> (<WaterMark>); -- Updates the stack WaterMark. | |
29301 | -- ... | |
29302 | end; | |
29303 | @end example | |
29304 | ||
29305 | whereas its callers are modified from: | |
29306 | ||
29307 | @example | |
29308 | X := Foo; | |
29309 | @end example | |
29310 | ||
29311 | to: | |
29312 | ||
29313 | @example | |
29314 | declare | |
29315 | <WaterMark> : System.Address; | |
29316 | begin | |
29317 | <__strub_enter> (<WaterMark>); -- Initialize <WaterMark>. | |
29318 | X := Foo (<WaterMark>); | |
29319 | <__strub_leave> (<WaterMark>); -- Scrubs stack up to <WaterMark>. | |
29320 | end; | |
29321 | @end example | |
29322 | ||
29323 | As for Bar, because it is strubbed in internal mode, its callers are | |
29324 | not modified. Its definition is modified roughly as follows: | |
29325 | ||
29326 | @example | |
29327 | procedure Bar is | |
29328 | <WaterMark> : System.Address; | |
29329 | procedure Strubbed_Bar (<WaterMark> : in out System.Address) is | |
29330 | begin | |
29331 | <__strub_update> (<WaterMark>); -- Updates the stack WaterMark. | |
29332 | -- original Bar body. | |
29333 | end Strubbed_Bar; | |
29334 | begin | |
29335 | <__strub_enter> (<WaterMark>); -- Initialize <WaterMark>. | |
29336 | Strubbed_Bar (<WaterMark>); | |
29337 | <__strub_leave> (<WaterMark>); -- Scrubs stack up to <WaterMark>. | |
29338 | end Bar; | |
29339 | @end example | |
29340 | ||
29341 | There are also @code{-fstrub=`choice'} command-line options to | |
29342 | control default settings. For usage and more details on the | |
29343 | command-line options, on the @code{strub} attribute, and their use with | |
29344 | other programming languages, see @cite{Using the GNU Compiler Collection (GCC)}. | |
29345 | ||
29346 | Note that Ada secondary stacks are not scrubbed. The restriction | |
29347 | @code{No_Secondary_Stack} avoids their use, and thus their accidental | |
29348 | preservation of data that should be scrubbed. | |
29349 | ||
29350 | Attributes @code{Access} and @code{Unconstrained_Access} of variables and | |
29351 | constants with @code{strub} enabled require types with @code{strub} enabled; | |
29352 | there is no way to express an access-to-strub type otherwise. | |
29353 | @code{Unchecked_Access} bypasses this constraint, but the resulting | |
29354 | access type designates a non-strub type. | |
29355 | ||
29356 | @example | |
29357 | VI : aliased Integer; | |
29358 | pragma Machine_Attribute (VI, "strub"); | |
29359 | XsVI : access Integer := VI'Access; -- Error. | |
29360 | UXsVI : access Integer := VI'Unchecked_Access; -- OK, | |
29361 | -- UXsVI does *not* enable strub in subprograms that | |
29362 | -- dereference it to obtain the UXsVI.all value. | |
29363 | ||
29364 | type Strub_Int is new Integer; | |
29365 | pragma Machine_Attribute (Strub_Int, "strub"); | |
29366 | VSI : aliased Strub_Int; | |
29367 | XsVSI : access Strub_Int := VSI'Access; -- OK, | |
29368 | -- VSI and XsVSI.all both enable strub in subprograms that | |
29369 | -- read their values. | |
29370 | @end example | |
29371 | ||
29372 | Every access-to-subprogram type, renaming, and overriding and | |
29373 | overridden dispatching operations that may refer to a subprogram with | |
29374 | an attribute-modified interface must be annotated with the same | |
29375 | interface-modifying attribute. Access-to-subprogram types can be | |
29376 | explicitly converted to different strub modes, as long as they are | |
29377 | interface-compatible (i.e., adding or removing @code{at-calls} is not | |
29378 | allowed). For example, a @code{strub}-@code{disabled} subprogram can be | |
29379 | turned @code{callable} through such an explicit conversion: | |
29380 | ||
29381 | @example | |
29382 | type TBar is access procedure; | |
29383 | ||
29384 | type TBar_Callable is access procedure; | |
29385 | pragma Machine_Attribute (TBar_Callable, "strub", "callable"); | |
29386 | -- The attribute modifies the procedure type, rather than the | |
29387 | -- access type, because of the extra argument after "strub", | |
29388 | -- only applicable to subprogram types. | |
29389 | ||
29390 | Bar_Callable_Ptr : constant TBar_Callable | |
29391 | := TBar_Callable (TBar'(Bar'Access)); | |
29392 | ||
29393 | procedure Bar_Callable renames Bar_Callable_Ptr.all; | |
29394 | pragma Machine_Attribute (Bar_Callable, "strub", "callable"); | |
29395 | @end example | |
29396 | ||
29397 | Note that the renaming declaration is expanded to a full subprogram | |
29398 | body, it won’t be just an alias. Only if it is inlined will it be as | |
29399 | efficient as a call by dereferencing the access-to-subprogram constant | |
29400 | Bar_Callable_Ptr. | |
29401 | ||
29402 | @c Hardened Conditionals: | |
29403 | ||
29404 | @node Hardened Conditionals,Hardened Booleans,Stack Scrubbing,Security Hardening Features | |
04d6c745 | 29405 | @anchor{gnat_rm/security_hardening_features hardened-conditionals}@anchor{449} |
64d5610f ML |
29406 | @section Hardened Conditionals |
29407 | ||
29408 | ||
29409 | GNAT can harden conditionals to protect against control-flow attacks. | |
29410 | ||
29411 | This is accomplished by two complementary transformations, each | |
29412 | activated by a separate command-line option. | |
29413 | ||
29414 | The option @code{-fharden-compares} enables hardening of compares | |
29415 | that compute results stored in variables, adding verification that the | |
29416 | reversed compare yields the opposite result, turning: | |
29417 | ||
29418 | @example | |
29419 | B := X = Y; | |
29420 | @end example | |
29421 | ||
29422 | into: | |
29423 | ||
29424 | @example | |
29425 | B := X = Y; | |
29426 | declare | |
29427 | NotB : Boolean := X /= Y; -- Computed independently of B. | |
29428 | begin | |
29429 | if B = NotB then | |
29430 | <__builtin_trap>; | |
29431 | end if; | |
29432 | end; | |
29433 | @end example | |
29434 | ||
29435 | The option @code{-fharden-conditional-branches} enables hardening | |
29436 | of compares that guard conditional branches, adding verification of | |
29437 | the reversed compare to both execution paths, turning: | |
29438 | ||
29439 | @example | |
29440 | if X = Y then | |
29441 | X := Z + 1; | |
29442 | else | |
29443 | Y := Z - 1; | |
29444 | end if; | |
29445 | @end example | |
29446 | ||
29447 | into: | |
29448 | ||
29449 | @example | |
29450 | if X = Y then | |
29451 | if X /= Y then -- Computed independently of X = Y. | |
29452 | <__builtin_trap>; | |
29453 | end if; | |
29454 | X := Z + 1; | |
29455 | else | |
29456 | if X /= Y then -- Computed independently of X = Y. | |
29457 | null; | |
29458 | else | |
29459 | <__builtin_trap>; | |
29460 | end if; | |
29461 | Y := Z - 1; | |
29462 | end if; | |
29463 | @end example | |
29464 | ||
29465 | These transformations are introduced late in the compilation pipeline, | |
29466 | long after boolean expressions are decomposed into separate compares, | |
29467 | each one turned into either a conditional branch or a compare whose | |
29468 | result is stored in a boolean variable or temporary. Compiler | |
29469 | optimizations, if enabled, may also turn conditional branches into | |
29470 | stored compares, and vice-versa, or into operations with implied | |
29471 | conditionals (e.g. MIN and MAX). Conditionals may also be optimized | |
29472 | out entirely, if their value can be determined at compile time, and | |
29473 | occasionally multiple compares can be combined into one. | |
29474 | ||
29475 | It is thus difficult to predict which of these two options will affect | |
29476 | a specific compare operation expressed in source code. Using both | |
29477 | options ensures that every compare that is neither optimized out nor | |
29478 | optimized into implied conditionals will be hardened. | |
29479 | ||
29480 | The addition of reversed compares can be observed by enabling the dump | |
29481 | files of the corresponding passes, through command-line options | |
29482 | @code{-fdump-tree-hardcmp} and @code{-fdump-tree-hardcbr}, | |
29483 | respectively. | |
29484 | ||
29485 | They are separate options, however, because of the significantly | |
29486 | different performance impact of the hardening transformations. | |
29487 | ||
29488 | For usage and more details on the command-line options, see | |
29489 | @cite{Using the GNU Compiler Collection (GCC)}. These options can | |
29490 | be used with other programming languages supported by GCC. | |
29491 | ||
29492 | @c Hardened Booleans: | |
29493 | ||
29494 | @node Hardened Booleans,Control Flow Redundancy,Hardened Conditionals,Security Hardening Features | |
04d6c745 | 29495 | @anchor{gnat_rm/security_hardening_features hardened-booleans}@anchor{44a} |
64d5610f ML |
29496 | @section Hardened Booleans |
29497 | ||
29498 | ||
29499 | Ada has built-in support for introducing boolean types with | |
29500 | alternative representations, using representation clauses: | |
29501 | ||
29502 | @example | |
29503 | type HBool is new Boolean; | |
29504 | for HBool use (16#5a#, 16#a5#); | |
29505 | for HBool'Size use 8; | |
29506 | @end example | |
29507 | ||
29508 | When validity checking is enabled, the compiler will check that | |
29509 | variables of such types hold values corresponding to the selected | |
29510 | representations. | |
29511 | ||
29512 | There are multiple strategies for where to introduce validity checking | |
29513 | (see @code{-gnatV} options). Their goal is to guard against | |
29514 | various kinds of programming errors, and GNAT strives to omit checks | |
29515 | when program logic rules out an invalid value, and optimizers may | |
29516 | further remove checks found to be redundant. | |
29517 | ||
29518 | For additional hardening, the @code{hardbool} @code{Machine_Attribute} | |
29519 | pragma can be used to annotate boolean types with representation | |
29520 | clauses, so that expressions of such types used as conditions are | |
29521 | checked even when compiling with @code{-gnatVT}: | |
29522 | ||
29523 | @example | |
29524 | pragma Machine_Attribute (HBool, "hardbool"); | |
29525 | ||
29526 | function To_Boolean (X : HBool) returns Boolean is (Boolean (X)); | |
29527 | @end example | |
29528 | ||
29529 | is compiled roughly like: | |
29530 | ||
29531 | @example | |
29532 | function To_Boolean (X : HBool) returns Boolean is | |
29533 | begin | |
29534 | if X not in True | False then | |
29535 | raise Constraint_Error; | |
29536 | elsif X in True then | |
29537 | return True; | |
29538 | else | |
29539 | return False; | |
29540 | end if; | |
29541 | end To_Boolean; | |
29542 | @end example | |
29543 | ||
29544 | Note that @code{-gnatVn} will disable even @code{hardbool} testing. | |
29545 | ||
29546 | Analogous behavior is available as a GCC extension to the C and | |
29547 | Objective C programming languages, through the @code{hardbool} attribute, | |
29548 | with the difference that, instead of raising a Constraint_Error | |
29549 | exception, when a hardened boolean variable is found to hold a value | |
29550 | that stands for neither True nor False, the program traps. For usage | |
29551 | and more details on that attribute, see @cite{Using the GNU Compiler Collection (GCC)}. | |
29552 | ||
29553 | @c Control Flow Redundancy: | |
29554 | ||
29555 | @node Control Flow Redundancy,,Hardened Booleans,Security Hardening Features | |
04d6c745 | 29556 | @anchor{gnat_rm/security_hardening_features control-flow-redundancy}@anchor{44b} |
64d5610f ML |
29557 | @section Control Flow Redundancy |
29558 | ||
29559 | ||
29560 | GNAT can guard against unexpected execution flows, such as branching | |
29561 | into the middle of subprograms, as in Return Oriented Programming | |
29562 | exploits. | |
29563 | ||
29564 | In units compiled with @code{-fharden-control-flow-redundancy}, | |
29565 | subprograms are instrumented so that, every time they are called, | |
29566 | basic blocks take note as control flows through them, and, before | |
29567 | returning, subprograms verify that the taken notes are consistent with | |
29568 | the control-flow graph. | |
29569 | ||
d4d6eda9 AO |
29570 | The performance impact of verification on leaf subprograms can be much |
29571 | higher, while the averted risks are much lower on them. | |
29572 | Instrumentation can be disabled for leaf subprograms with | |
29573 | @code{-fhardcfr-skip-leaf}. | |
29574 | ||
64d5610f ML |
29575 | Functions with too many basic blocks, or with multiple return points, |
29576 | call a run-time function to perform the verification. Other functions | |
29577 | perform the verification inline before returning. | |
29578 | ||
29579 | Optimizing the inlined verification can be quite time consuming, so | |
29580 | the default upper limit for the inline mode is set at 16 blocks. | |
29581 | Command-line option @code{--param hardcfr-max-inline-blocks=} can | |
29582 | override it. | |
29583 | ||
29584 | Even though typically sparse control-flow graphs exhibit run-time | |
29585 | verification time nearly proportional to the block count of a | |
29586 | subprogram, it may become very significant for generated subprograms | |
29587 | with thousands of blocks. Command-line option | |
29588 | @code{--param hardcfr-max-blocks=} can set an upper limit for | |
29589 | instrumentation. | |
29590 | ||
29591 | For each block that is marked as visited, the mechanism checks that at | |
29592 | least one of its predecessors, and at least one of its successors, are | |
29593 | also marked as visited. | |
29594 | ||
f3597ba6 AO |
29595 | Verification is performed just before a subprogram returns. The |
29596 | following fragment: | |
29597 | ||
29598 | @example | |
29599 | if X then | |
29600 | Y := F (Z); | |
29601 | return; | |
29602 | end if; | |
29603 | @end example | |
29604 | ||
29605 | gets turned into: | |
29606 | ||
29607 | @example | |
29608 | type Visited_Bitmap is array (1..N) of Boolean with Pack; | |
29609 | Visited : aliased Visited_Bitmap := (others => False); | |
29610 | -- Bitmap of visited blocks. N is the basic block count. | |
29611 | [...] | |
29612 | -- Basic block #I | |
29613 | Visited(I) := True; | |
29614 | if X then | |
29615 | -- Basic block #J | |
29616 | Visited(J) := True; | |
29617 | Y := F (Z); | |
29618 | CFR.Check (N, Visited'Access, CFG'Access); | |
29619 | -- CFR is a hypothetical package whose Check procedure calls | |
29620 | -- libgcc's __hardcfr_check, that traps if the Visited bitmap | |
29621 | -- does not hold a valid path in CFG, the run-time | |
29622 | -- representation of the control flow graph in the enclosing | |
29623 | -- subprogram. | |
29624 | return; | |
29625 | end if; | |
29626 | -- Basic block #K | |
29627 | Visited(K) := True; | |
29628 | @end example | |
29629 | ||
29630 | Verification would also be performed before tail calls, if any | |
29631 | front-ends marked them as mandatory or desirable, but none do. | |
29632 | Regular calls are optimized into tail calls too late for this | |
29633 | transformation to act on it. | |
29634 | ||
29635 | In order to avoid adding verification after potential tail calls, | |
29636 | which would prevent tail-call optimization, we recognize returning | |
29637 | calls, i.e., calls whose result, if any, is returned by the calling | |
29638 | subprogram to its caller immediately after the call returns. | |
29639 | Verification is performed before such calls, whether or not they are | |
29640 | ultimately optimized to tail calls. This behavior is enabled by | |
29641 | default whenever sibcall optimization is enabled (see | |
29642 | @code{-foptimize-sibling-calls}); it may be disabled with | |
29643 | @code{-fno-hardcfr-check-returning-calls}, or enabled with | |
29644 | @code{-fhardcfr-check-returning-calls}, regardless of the | |
29645 | optimization, but the lack of other optimizations may prevent calls | |
29646 | from being recognized as returning calls: | |
29647 | ||
29648 | @example | |
29649 | -- CFR.Check here, with -fhardcfr-check-returning-calls. | |
29650 | P (X); | |
29651 | -- CFR.Check here, with -fno-hardcfr-check-returning-calls. | |
29652 | return; | |
29653 | @end example | |
29654 | ||
29655 | or: | |
29656 | ||
29657 | @example | |
29658 | -- CFR.Check here, with -fhardcfr-check-returning-calls. | |
29659 | R := F (X); | |
29660 | -- CFR.Check here, with -fno-hardcfr-check-returning-calls. | |
29661 | return R; | |
29662 | @end example | |
29663 | ||
29664 | Any subprogram from which an exception may escape, i.e., that may | |
29665 | raise or propagate an exception that isn’t handled internally, is | |
29666 | conceptually enclosed by a cleanup handler that performs verification, | |
29667 | unless this is disabled with @code{-fno-hardcfr-check-exceptions}. | |
29668 | With this feature enabled, a subprogram body containing: | |
29669 | ||
29670 | @example | |
29671 | -- ... | |
29672 | Y := F (X); -- May raise exceptions. | |
29673 | -- ... | |
29674 | raise E; -- Not handled internally. | |
29675 | -- ... | |
29676 | @end example | |
29677 | ||
29678 | gets modified as follows: | |
29679 | ||
29680 | @example | |
29681 | begin | |
29682 | -- ... | |
29683 | Y := F (X); -- May raise exceptions. | |
29684 | -- ... | |
29685 | raise E; -- Not handled internally. | |
29686 | -- ... | |
29687 | exception | |
29688 | when others => | |
29689 | CFR.Check (N, Visited'Access, CFG'Access); | |
29690 | raise; | |
29691 | end; | |
29692 | @end example | |
29693 | ||
61736805 AO |
29694 | Verification may also be performed before No_Return calls, whether all |
29695 | of them, with @code{-fhardcfr-check-noreturn-calls=always}; all but | |
79cc2a75 AO |
29696 | internal subprograms involved in exception-raising or -reraising or |
29697 | subprograms explicitly marked with both @code{No_Return} and | |
29698 | @code{Machine_Attribute} @code{expected_throw} pragmas, with | |
61736805 AO |
29699 | @code{-fhardcfr-check-noreturn-calls=no-xthrow} (default); only |
29700 | nothrow ones, with @code{-fhardcfr-check-noreturn-calls=nothrow}; | |
29701 | or none, with @code{-fhardcfr-check-noreturn-calls=never}. | |
f3597ba6 AO |
29702 | |
29703 | When a No_Return call returns control to its caller through an | |
29704 | exception, verification may have already been performed before the | |
61736805 AO |
29705 | call, if @code{-fhardcfr-check-noreturn-calls=always} or |
29706 | @code{-fhardcfr-check-noreturn-calls=no-xthrow} is in effect. The | |
29707 | compiler arranges for already-checked No_Return calls without a | |
f3597ba6 AO |
29708 | preexisting handler to bypass the implicitly-added cleanup handler and |
29709 | thus the redundant check, but a local exception or cleanup handler, if | |
29710 | present, will modify the set of visited blocks, and checking will take | |
29711 | place again when the caller reaches the next verification point, | |
29712 | whether it is a return or reraise statement after the exception is | |
29713 | otherwise handled, or even another No_Return call. | |
64d5610f ML |
29714 | |
29715 | The instrumentation for hardening with control flow redundancy can be | |
29716 | observed in dump files generated by the command-line option | |
29717 | @code{-fdump-tree-hardcfr}. | |
29718 | ||
29719 | For more details on the control flow redundancy command-line options, | |
29720 | see @cite{Using the GNU Compiler Collection (GCC)}. These options | |
29721 | can be used with other programming languages supported by GCC. | |
29722 | ||
29723 | @node Obsolescent Features,Compatibility and Porting Guide,Security Hardening Features,Top | |
04d6c745 | 29724 | @anchor{gnat_rm/obsolescent_features doc}@anchor{44c}@anchor{gnat_rm/obsolescent_features id1}@anchor{44d}@anchor{gnat_rm/obsolescent_features obsolescent-features}@anchor{16} |
64d5610f ML |
29725 | @chapter Obsolescent Features |
29726 | ||
29727 | ||
29728 | This chapter describes features that are provided by GNAT, but are | |
29729 | considered obsolescent since there are preferred ways of achieving | |
29730 | the same effect. These features are provided solely for historical | |
29731 | compatibility purposes. | |
29732 | ||
29733 | @menu | |
29734 | * pragma No_Run_Time:: | |
29735 | * pragma Ravenscar:: | |
29736 | * pragma Restricted_Run_Time:: | |
29737 | * pragma Task_Info:: | |
29738 | * package System.Task_Info (s-tasinf.ads): package System Task_Info s-tasinf ads. | |
29739 | ||
29740 | @end menu | |
29741 | ||
29742 | @node pragma No_Run_Time,pragma Ravenscar,,Obsolescent Features | |
04d6c745 | 29743 | @anchor{gnat_rm/obsolescent_features id2}@anchor{44e}@anchor{gnat_rm/obsolescent_features pragma-no-run-time}@anchor{44f} |
64d5610f ML |
29744 | @section pragma No_Run_Time |
29745 | ||
29746 | ||
29747 | The pragma @code{No_Run_Time} is used to achieve an affect similar | |
29748 | to the use of the “Zero Foot Print” configurable run time, but without | |
29749 | requiring a specially configured run time. The result of using this | |
29750 | pragma, which must be used for all units in a partition, is to restrict | |
29751 | the use of any language features requiring run-time support code. The | |
29752 | preferred usage is to use an appropriately configured run-time that | |
29753 | includes just those features that are to be made accessible. | |
29754 | ||
29755 | @node pragma Ravenscar,pragma Restricted_Run_Time,pragma No_Run_Time,Obsolescent Features | |
04d6c745 | 29756 | @anchor{gnat_rm/obsolescent_features id3}@anchor{450}@anchor{gnat_rm/obsolescent_features pragma-ravenscar}@anchor{451} |
64d5610f ML |
29757 | @section pragma Ravenscar |
29758 | ||
29759 | ||
29760 | The pragma @code{Ravenscar} has exactly the same effect as pragma | |
29761 | @code{Profile (Ravenscar)}. The latter usage is preferred since it | |
29762 | is part of the new Ada 2005 standard. | |
29763 | ||
29764 | @node pragma Restricted_Run_Time,pragma Task_Info,pragma Ravenscar,Obsolescent Features | |
04d6c745 | 29765 | @anchor{gnat_rm/obsolescent_features id4}@anchor{452}@anchor{gnat_rm/obsolescent_features pragma-restricted-run-time}@anchor{453} |
64d5610f ML |
29766 | @section pragma Restricted_Run_Time |
29767 | ||
29768 | ||
29769 | The pragma @code{Restricted_Run_Time} has exactly the same effect as | |
29770 | pragma @code{Profile (Restricted)}. The latter usage is | |
29771 | preferred since the Ada 2005 pragma @code{Profile} is intended for | |
29772 | this kind of implementation dependent addition. | |
29773 | ||
29774 | @node pragma Task_Info,package System Task_Info s-tasinf ads,pragma Restricted_Run_Time,Obsolescent Features | |
04d6c745 | 29775 | @anchor{gnat_rm/obsolescent_features id5}@anchor{454}@anchor{gnat_rm/obsolescent_features pragma-task-info}@anchor{455} |
64d5610f ML |
29776 | @section pragma Task_Info |
29777 | ||
29778 | ||
29779 | The functionality provided by pragma @code{Task_Info} is now part of the | |
29780 | Ada language. The @code{CPU} aspect and the package | |
29781 | @code{System.Multiprocessors} offer a less system-dependent way to specify | |
29782 | task affinity or to query the number of processors. | |
29783 | ||
29784 | Syntax | |
29785 | ||
29786 | @example | |
29787 | pragma Task_Info (EXPRESSION); | |
29788 | @end example | |
29789 | ||
29790 | This pragma appears within a task definition (like pragma | |
29791 | @code{Priority}) and applies to the task in which it appears. The | |
29792 | argument must be of type @code{System.Task_Info.Task_Info_Type}. | |
29793 | The @code{Task_Info} pragma provides system dependent control over | |
29794 | aspects of tasking implementation, for example, the ability to map | |
29795 | tasks to specific processors. For details on the facilities available | |
29796 | for the version of GNAT that you are using, see the documentation | |
29797 | in the spec of package System.Task_Info in the runtime | |
29798 | library. | |
29799 | ||
29800 | @node package System Task_Info s-tasinf ads,,pragma Task_Info,Obsolescent Features | |
04d6c745 | 29801 | @anchor{gnat_rm/obsolescent_features package-system-task-info}@anchor{456}@anchor{gnat_rm/obsolescent_features package-system-task-info-s-tasinf-ads}@anchor{457} |
64d5610f ML |
29802 | @section package System.Task_Info (@code{s-tasinf.ads}) |
29803 | ||
29804 | ||
29805 | This package provides target dependent functionality that is used | |
29806 | to support the @code{Task_Info} pragma. The predefined Ada package | |
29807 | @code{System.Multiprocessors} and the @code{CPU} aspect now provide a | |
29808 | standard replacement for GNAT’s @code{Task_Info} functionality. | |
29809 | ||
29810 | @node Compatibility and Porting Guide,GNU Free Documentation License,Obsolescent Features,Top | |
04d6c745 | 29811 | @anchor{gnat_rm/compatibility_and_porting_guide doc}@anchor{458}@anchor{gnat_rm/compatibility_and_porting_guide compatibility-and-porting-guide}@anchor{17}@anchor{gnat_rm/compatibility_and_porting_guide id1}@anchor{459} |
64d5610f ML |
29812 | @chapter Compatibility and Porting Guide |
29813 | ||
29814 | ||
29815 | This chapter presents some guidelines for developing portable Ada code, | |
29816 | describes the compatibility issues that may arise between | |
29817 | GNAT and other Ada compilation systems (including those for Ada 83), | |
29818 | and shows how GNAT can expedite porting | |
29819 | applications developed in other Ada environments. | |
29820 | ||
29821 | @menu | |
29822 | * Writing Portable Fixed-Point Declarations:: | |
29823 | * Compatibility with Ada 83:: | |
29824 | * Compatibility between Ada 95 and Ada 2005:: | |
29825 | * Implementation-dependent characteristics:: | |
29826 | * Compatibility with Other Ada Systems:: | |
29827 | * Representation Clauses:: | |
29828 | * Compatibility with HP Ada 83:: | |
29829 | ||
29830 | @end menu | |
29831 | ||
29832 | @node Writing Portable Fixed-Point Declarations,Compatibility with Ada 83,,Compatibility and Porting Guide | |
04d6c745 | 29833 | @anchor{gnat_rm/compatibility_and_porting_guide id2}@anchor{45a}@anchor{gnat_rm/compatibility_and_porting_guide writing-portable-fixed-point-declarations}@anchor{45b} |
64d5610f ML |
29834 | @section Writing Portable Fixed-Point Declarations |
29835 | ||
29836 | ||
29837 | The Ada Reference Manual gives an implementation freedom to choose bounds | |
29838 | that are narrower by @code{Small} from the given bounds. | |
29839 | For example, if we write | |
29840 | ||
29841 | @example | |
29842 | type F1 is delta 1.0 range -128.0 .. +128.0; | |
29843 | @end example | |
29844 | ||
29845 | then the implementation is allowed to choose -128.0 .. +127.0 if it | |
29846 | likes, but is not required to do so. | |
29847 | ||
29848 | This leads to possible portability problems, so let’s have a closer | |
29849 | look at this, and figure out how to avoid these problems. | |
29850 | ||
29851 | First, why does this freedom exist, and why would an implementation | |
29852 | take advantage of it? To answer this, take a closer look at the type | |
29853 | declaration for @code{F1} above. If the compiler uses the given bounds, | |
29854 | it would need 9 bits to hold the largest positive value (and typically | |
29855 | that means 16 bits on all machines). But if the implementation chooses | |
29856 | the +127.0 bound then it can fit values of the type in 8 bits. | |
29857 | ||
29858 | Why not make the user write +127.0 if that’s what is wanted? | |
29859 | The rationale is that if you are thinking of fixed point | |
29860 | as a kind of ‘poor man’s floating-point’, then you don’t want | |
29861 | to be thinking about the scaled integers that are used in its | |
29862 | representation. Let’s take another example: | |
29863 | ||
29864 | @example | |
29865 | type F2 is delta 2.0**(-15) range -1.0 .. +1.0; | |
29866 | @end example | |
29867 | ||
29868 | Looking at this declaration, it seems casually as though | |
29869 | it should fit in 16 bits, but again that extra positive value | |
29870 | +1.0 has the scaled integer equivalent of 2**15 which is one too | |
29871 | big for signed 16 bits. The implementation can treat this as: | |
29872 | ||
29873 | @example | |
29874 | type F2 is delta 2.0**(-15) range -1.0 .. +1.0-(2.0**(-15)); | |
29875 | @end example | |
29876 | ||
29877 | and the Ada language design team felt that this was too annoying | |
29878 | to require. We don’t need to debate this decision at this point, | |
29879 | since it is well established (the rule about narrowing the ranges | |
29880 | dates to Ada 83). | |
29881 | ||
29882 | But the important point is that an implementation is not required | |
29883 | to do this narrowing, so we have a potential portability problem. | |
29884 | We could imagine three types of implementation: | |
29885 | ||
29886 | ||
29887 | @enumerate a | |
29888 | ||
29889 | @item | |
29890 | those that narrow the range automatically if they can figure | |
29891 | out that the narrower range will allow storage in a smaller machine unit, | |
29892 | ||
29893 | @item | |
29894 | those that will narrow only if forced to by a @code{'Size} clause, and | |
29895 | ||
29896 | @item | |
29897 | those that will never narrow. | |
29898 | @end enumerate | |
29899 | ||
29900 | Now if we are language theoreticians, we can imagine a fourth | |
29901 | approach: to narrow all the time, e.g. to treat | |
29902 | ||
29903 | @example | |
29904 | type F3 is delta 1.0 range -10.0 .. +23.0; | |
29905 | @end example | |
29906 | ||
29907 | as though it had been written: | |
29908 | ||
29909 | @example | |
29910 | type F3 is delta 1.0 range -9.0 .. +22.0; | |
29911 | @end example | |
29912 | ||
29913 | But although technically allowed, such a behavior would be hostile and silly, | |
29914 | and no real compiler would do this. All real compilers will fall into one of | |
29915 | the categories (a), (b) or (c) above. | |
29916 | ||
29917 | So, how do you get the compiler to do what you want? The answer is give the | |
29918 | actual bounds you want, and then use a @code{'Small} clause and a | |
29919 | @code{'Size} clause to absolutely pin down what the compiler does. | |
29920 | E.g., for @code{F2} above, we will write: | |
29921 | ||
29922 | @example | |
29923 | My_Small : constant := 2.0**(-15); | |
29924 | My_First : constant := -1.0; | |
29925 | My_Last : constant := +1.0 - My_Small; | |
29926 | ||
29927 | type F2 is delta My_Small range My_First .. My_Last; | |
29928 | @end example | |
29929 | ||
29930 | and then add | |
29931 | ||
29932 | @example | |
29933 | for F2'Small use my_Small; | |
29934 | for F2'Size use 16; | |
29935 | @end example | |
29936 | ||
29937 | In practice all compilers will do the same thing here and will give you | |
29938 | what you want, so the above declarations are fully portable. If you really | |
29939 | want to play language lawyer and guard against ludicrous behavior by the | |
29940 | compiler you could add | |
29941 | ||
29942 | @example | |
29943 | Test1 : constant := 1 / Boolean'Pos (F2'First = My_First); | |
29944 | Test2 : constant := 1 / Boolean'Pos (F2'Last = My_Last); | |
29945 | @end example | |
29946 | ||
29947 | One or other or both are allowed to be illegal if the compiler is | |
29948 | behaving in a silly manner, but at least the silly compiler will not | |
29949 | get away with silently messing with your (very clear) intentions. | |
29950 | ||
29951 | If you follow this scheme you will be guaranteed that your fixed-point | |
29952 | types will be portable. | |
29953 | ||
29954 | @node Compatibility with Ada 83,Compatibility between Ada 95 and Ada 2005,Writing Portable Fixed-Point Declarations,Compatibility and Porting Guide | |
04d6c745 | 29955 | @anchor{gnat_rm/compatibility_and_porting_guide compatibility-with-ada-83}@anchor{45c}@anchor{gnat_rm/compatibility_and_porting_guide id3}@anchor{45d} |
64d5610f ML |
29956 | @section Compatibility with Ada 83 |
29957 | ||
29958 | ||
29959 | @geindex Compatibility (between Ada 83 and Ada 95 / Ada 2005 / Ada 2012) | |
29960 | ||
29961 | Ada 95 and the subsequent revisions Ada 2005 and Ada 2012 | |
29962 | are highly upwards compatible with Ada 83. In | |
29963 | particular, the design intention was that the difficulties associated | |
29964 | with moving from Ada 83 to later versions of the standard should be no greater | |
29965 | than those that occur when moving from one Ada 83 system to another. | |
29966 | ||
29967 | However, there are a number of points at which there are minor | |
29968 | incompatibilities. The @cite{Ada 95 Annotated Reference Manual} contains | |
29969 | full details of these issues as they relate to Ada 95, | |
29970 | and should be consulted for a complete treatment. | |
29971 | In practice the | |
29972 | following subsections treat the most likely issues to be encountered. | |
29973 | ||
29974 | @menu | |
29975 | * Legal Ada 83 programs that are illegal in Ada 95:: | |
29976 | * More deterministic semantics:: | |
29977 | * Changed semantics:: | |
29978 | * Other language compatibility issues:: | |
29979 | ||
29980 | @end menu | |
29981 | ||
29982 | @node Legal Ada 83 programs that are illegal in Ada 95,More deterministic semantics,,Compatibility with Ada 83 | |
04d6c745 | 29983 | @anchor{gnat_rm/compatibility_and_porting_guide id4}@anchor{45e}@anchor{gnat_rm/compatibility_and_porting_guide legal-ada-83-programs-that-are-illegal-in-ada-95}@anchor{45f} |
64d5610f ML |
29984 | @subsection Legal Ada 83 programs that are illegal in Ada 95 |
29985 | ||
29986 | ||
29987 | Some legal Ada 83 programs are illegal (i.e., they will fail to compile) in | |
29988 | Ada 95 and later versions of the standard: | |
29989 | ||
29990 | ||
29991 | @itemize * | |
29992 | ||
29993 | @item | |
29994 | `Character literals' | |
29995 | ||
29996 | Some uses of character literals are ambiguous. Since Ada 95 has introduced | |
29997 | @code{Wide_Character} as a new predefined character type, some uses of | |
29998 | character literals that were legal in Ada 83 are illegal in Ada 95. | |
29999 | For example: | |
30000 | ||
30001 | @example | |
30002 | for Char in 'A' .. 'Z' loop ... end loop; | |
30003 | @end example | |
30004 | ||
30005 | The problem is that ‘A’ and ‘Z’ could be from either | |
30006 | @code{Character} or @code{Wide_Character}. The simplest correction | |
30007 | is to make the type explicit; e.g.: | |
30008 | ||
30009 | @example | |
30010 | for Char in Character range 'A' .. 'Z' loop ... end loop; | |
30011 | @end example | |
30012 | ||
30013 | @item | |
30014 | `New reserved words' | |
30015 | ||
30016 | The identifiers @code{abstract}, @code{aliased}, @code{protected}, | |
30017 | @code{requeue}, @code{tagged}, and @code{until} are reserved in Ada 95. | |
30018 | Existing Ada 83 code using any of these identifiers must be edited to | |
30019 | use some alternative name. | |
30020 | ||
30021 | @item | |
30022 | `Freezing rules' | |
30023 | ||
30024 | The rules in Ada 95 are slightly different with regard to the point at | |
30025 | which entities are frozen, and representation pragmas and clauses are | |
30026 | not permitted past the freeze point. This shows up most typically in | |
30027 | the form of an error message complaining that a representation item | |
30028 | appears too late, and the appropriate corrective action is to move | |
30029 | the item nearer to the declaration of the entity to which it refers. | |
30030 | ||
30031 | A particular case is that representation pragmas | |
30032 | cannot be applied to a subprogram body. If necessary, a separate subprogram | |
30033 | declaration must be introduced to which the pragma can be applied. | |
30034 | ||
30035 | @item | |
30036 | `Optional bodies for library packages' | |
30037 | ||
30038 | In Ada 83, a package that did not require a package body was nevertheless | |
30039 | allowed to have one. This lead to certain surprises in compiling large | |
30040 | systems (situations in which the body could be unexpectedly ignored by the | |
30041 | binder). In Ada 95, if a package does not require a body then it is not | |
30042 | permitted to have a body. To fix this problem, simply remove a redundant | |
30043 | body if it is empty, or, if it is non-empty, introduce a dummy declaration | |
30044 | into the spec that makes the body required. One approach is to add a private | |
30045 | part to the package declaration (if necessary), and define a parameterless | |
30046 | procedure called @code{Requires_Body}, which must then be given a dummy | |
30047 | procedure body in the package body, which then becomes required. | |
30048 | Another approach (assuming that this does not introduce elaboration | |
30049 | circularities) is to add an @code{Elaborate_Body} pragma to the package spec, | |
30050 | since one effect of this pragma is to require the presence of a package body. | |
30051 | ||
30052 | @item | |
30053 | `Numeric_Error is the same exception as Constraint_Error' | |
30054 | ||
30055 | In Ada 95, the exception @code{Numeric_Error} is a renaming of @code{Constraint_Error}. | |
30056 | This means that it is illegal to have separate exception handlers for | |
30057 | the two exceptions. The fix is simply to remove the handler for the | |
30058 | @code{Numeric_Error} case (since even in Ada 83, a compiler was free to raise | |
30059 | @code{Constraint_Error} in place of @code{Numeric_Error} in all cases). | |
30060 | ||
30061 | @item | |
30062 | `Indefinite subtypes in generics' | |
30063 | ||
30064 | In Ada 83, it was permissible to pass an indefinite type (e.g, @code{String}) | |
30065 | as the actual for a generic formal private type, but then the instantiation | |
30066 | would be illegal if there were any instances of declarations of variables | |
30067 | of this type in the generic body. In Ada 95, to avoid this clear violation | |
30068 | of the methodological principle known as the ‘contract model’, | |
30069 | the generic declaration explicitly indicates whether | |
30070 | or not such instantiations are permitted. If a generic formal parameter | |
30071 | has explicit unknown discriminants, indicated by using @code{(<>)} after the | |
30072 | subtype name, then it can be instantiated with indefinite types, but no | |
30073 | stand-alone variables can be declared of this type. Any attempt to declare | |
30074 | such a variable will result in an illegality at the time the generic is | |
30075 | declared. If the @code{(<>)} notation is not used, then it is illegal | |
30076 | to instantiate the generic with an indefinite type. | |
30077 | This is the potential incompatibility issue when porting Ada 83 code to Ada 95. | |
30078 | It will show up as a compile time error, and | |
30079 | the fix is usually simply to add the @code{(<>)} to the generic declaration. | |
30080 | @end itemize | |
30081 | ||
30082 | @node More deterministic semantics,Changed semantics,Legal Ada 83 programs that are illegal in Ada 95,Compatibility with Ada 83 | |
04d6c745 | 30083 | @anchor{gnat_rm/compatibility_and_porting_guide id5}@anchor{460}@anchor{gnat_rm/compatibility_and_porting_guide more-deterministic-semantics}@anchor{461} |
64d5610f ML |
30084 | @subsection More deterministic semantics |
30085 | ||
30086 | ||
30087 | ||
30088 | @itemize * | |
30089 | ||
30090 | @item | |
30091 | `Conversions' | |
30092 | ||
30093 | Conversions from real types to integer types round away from 0. In Ada 83 | |
30094 | the conversion Integer(2.5) could deliver either 2 or 3 as its value. This | |
30095 | implementation freedom was intended to support unbiased rounding in | |
30096 | statistical applications, but in practice it interfered with portability. | |
30097 | In Ada 95 the conversion semantics are unambiguous, and rounding away from 0 | |
30098 | is required. Numeric code may be affected by this change in semantics. | |
30099 | Note, though, that this issue is no worse than already existed in Ada 83 | |
30100 | when porting code from one vendor to another. | |
30101 | ||
30102 | @item | |
30103 | `Tasking' | |
30104 | ||
30105 | The Real-Time Annex introduces a set of policies that define the behavior of | |
30106 | features that were implementation dependent in Ada 83, such as the order in | |
30107 | which open select branches are executed. | |
30108 | @end itemize | |
30109 | ||
30110 | @node Changed semantics,Other language compatibility issues,More deterministic semantics,Compatibility with Ada 83 | |
04d6c745 | 30111 | @anchor{gnat_rm/compatibility_and_porting_guide changed-semantics}@anchor{462}@anchor{gnat_rm/compatibility_and_porting_guide id6}@anchor{463} |
64d5610f ML |
30112 | @subsection Changed semantics |
30113 | ||
30114 | ||
30115 | The worst kind of incompatibility is one where a program that is legal in | |
30116 | Ada 83 is also legal in Ada 95 but can have an effect in Ada 95 that was not | |
30117 | possible in Ada 83. Fortunately this is extremely rare, but the one | |
30118 | situation that you should be alert to is the change in the predefined type | |
30119 | @code{Character} from 7-bit ASCII to 8-bit Latin-1. | |
30120 | ||
30121 | @quotation | |
30122 | ||
30123 | @geindex Latin-1 | |
30124 | @end quotation | |
30125 | ||
30126 | ||
30127 | @itemize * | |
30128 | ||
30129 | @item | |
30130 | `Range of type `@w{`}Character`@w{`}' | |
30131 | ||
30132 | The range of @code{Standard.Character} is now the full 256 characters | |
30133 | of Latin-1, whereas in most Ada 83 implementations it was restricted | |
30134 | to 128 characters. Although some of the effects of | |
30135 | this change will be manifest in compile-time rejection of legal | |
30136 | Ada 83 programs it is possible for a working Ada 83 program to have | |
30137 | a different effect in Ada 95, one that was not permitted in Ada 83. | |
30138 | As an example, the expression | |
30139 | @code{Character'Pos(Character'Last)} returned @code{127} in Ada 83 and now | |
30140 | delivers @code{255} as its value. | |
30141 | In general, you should look at the logic of any | |
30142 | character-processing Ada 83 program and see whether it needs to be adapted | |
30143 | to work correctly with Latin-1. Note that the predefined Ada 95 API has a | |
30144 | character handling package that may be relevant if code needs to be adapted | |
30145 | to account for the additional Latin-1 elements. | |
30146 | The desirable fix is to | |
30147 | modify the program to accommodate the full character set, but in some cases | |
30148 | it may be convenient to define a subtype or derived type of Character that | |
30149 | covers only the restricted range. | |
30150 | @end itemize | |
30151 | ||
30152 | @node Other language compatibility issues,,Changed semantics,Compatibility with Ada 83 | |
04d6c745 | 30153 | @anchor{gnat_rm/compatibility_and_porting_guide id7}@anchor{464}@anchor{gnat_rm/compatibility_and_porting_guide other-language-compatibility-issues}@anchor{465} |
64d5610f ML |
30154 | @subsection Other language compatibility issues |
30155 | ||
30156 | ||
30157 | ||
30158 | @itemize * | |
30159 | ||
30160 | @item | |
30161 | `-gnat83' switch | |
30162 | ||
30163 | All implementations of GNAT provide a switch that causes GNAT to operate | |
30164 | in Ada 83 mode. In this mode, some but not all compatibility problems | |
30165 | of the type described above are handled automatically. For example, the | |
30166 | new reserved words introduced in Ada 95 and Ada 2005 are treated simply | |
30167 | as identifiers as in Ada 83. However, | |
30168 | in practice, it is usually advisable to make the necessary modifications | |
30169 | to the program to remove the need for using this switch. | |
30170 | See the @code{Compiling Different Versions of Ada} section in | |
30171 | the @cite{GNAT User’s Guide}. | |
30172 | ||
30173 | @item | |
30174 | Support for removed Ada 83 pragmas and attributes | |
30175 | ||
30176 | A number of pragmas and attributes from Ada 83 were removed from Ada 95, | |
30177 | generally because they were replaced by other mechanisms. Ada 95 and Ada 2005 | |
30178 | compilers are allowed, but not required, to implement these missing | |
30179 | elements. In contrast with some other compilers, GNAT implements all | |
30180 | such pragmas and attributes, eliminating this compatibility concern. These | |
30181 | include @code{pragma Interface} and the floating point type attributes | |
30182 | (@code{Emax}, @code{Mantissa}, etc.), among other items. | |
30183 | @end itemize | |
30184 | ||
30185 | @node Compatibility between Ada 95 and Ada 2005,Implementation-dependent characteristics,Compatibility with Ada 83,Compatibility and Porting Guide | |
04d6c745 | 30186 | @anchor{gnat_rm/compatibility_and_porting_guide compatibility-between-ada-95-and-ada-2005}@anchor{466}@anchor{gnat_rm/compatibility_and_porting_guide id8}@anchor{467} |
64d5610f ML |
30187 | @section Compatibility between Ada 95 and Ada 2005 |
30188 | ||
30189 | ||
30190 | @geindex Compatibility between Ada 95 and Ada 2005 | |
30191 | ||
30192 | Although Ada 2005 was designed to be upwards compatible with Ada 95, there are | |
30193 | a number of incompatibilities. Several are enumerated below; | |
30194 | for a complete description please see the | |
30195 | @cite{Annotated Ada 2005 Reference Manual}, or section 9.1.1 in | |
30196 | @cite{Rationale for Ada 2005}. | |
30197 | ||
30198 | ||
30199 | @itemize * | |
30200 | ||
30201 | @item | |
30202 | `New reserved words.' | |
30203 | ||
30204 | The words @code{interface}, @code{overriding} and @code{synchronized} are | |
30205 | reserved in Ada 2005. | |
30206 | A pre-Ada 2005 program that uses any of these as an identifier will be | |
30207 | illegal. | |
30208 | ||
30209 | @item | |
30210 | `New declarations in predefined packages.' | |
30211 | ||
30212 | A number of packages in the predefined environment contain new declarations: | |
30213 | @code{Ada.Exceptions}, @code{Ada.Real_Time}, @code{Ada.Strings}, | |
30214 | @code{Ada.Strings.Fixed}, @code{Ada.Strings.Bounded}, | |
30215 | @code{Ada.Strings.Unbounded}, @code{Ada.Strings.Wide_Fixed}, | |
30216 | @code{Ada.Strings.Wide_Bounded}, @code{Ada.Strings.Wide_Unbounded}, | |
30217 | @code{Ada.Tags}, @code{Ada.Text_IO}, and @code{Interfaces.C}. | |
30218 | If an Ada 95 program does a @code{with} and @code{use} of any of these | |
30219 | packages, the new declarations may cause name clashes. | |
30220 | ||
30221 | @item | |
30222 | `Access parameters.' | |
30223 | ||
30224 | A nondispatching subprogram with an access parameter cannot be renamed | |
30225 | as a dispatching operation. This was permitted in Ada 95. | |
30226 | ||
30227 | @item | |
30228 | `Access types, discriminants, and constraints.' | |
30229 | ||
30230 | Rule changes in this area have led to some incompatibilities; for example, | |
30231 | constrained subtypes of some access types are not permitted in Ada 2005. | |
30232 | ||
30233 | @item | |
30234 | `Aggregates for limited types.' | |
30235 | ||
30236 | The allowance of aggregates for limited types in Ada 2005 raises the | |
30237 | possibility of ambiguities in legal Ada 95 programs, since additional types | |
30238 | now need to be considered in expression resolution. | |
30239 | ||
30240 | @item | |
30241 | `Fixed-point multiplication and division.' | |
30242 | ||
30243 | Certain expressions involving ‘*’ or ‘/’ for a fixed-point type, which | |
30244 | were legal in Ada 95 and invoked the predefined versions of these operations, | |
30245 | are now ambiguous. | |
30246 | The ambiguity may be resolved either by applying a type conversion to the | |
30247 | expression, or by explicitly invoking the operation from package | |
30248 | @code{Standard}. | |
30249 | ||
30250 | @item | |
30251 | `Return-by-reference types.' | |
30252 | ||
30253 | The Ada 95 return-by-reference mechanism has been removed. Instead, the user | |
30254 | can declare a function returning a value from an anonymous access type. | |
30255 | @end itemize | |
30256 | ||
30257 | @node Implementation-dependent characteristics,Compatibility with Other Ada Systems,Compatibility between Ada 95 and Ada 2005,Compatibility and Porting Guide | |
04d6c745 | 30258 | @anchor{gnat_rm/compatibility_and_porting_guide id9}@anchor{468}@anchor{gnat_rm/compatibility_and_porting_guide implementation-dependent-characteristics}@anchor{469} |
64d5610f ML |
30259 | @section Implementation-dependent characteristics |
30260 | ||
30261 | ||
30262 | Although the Ada language defines the semantics of each construct as | |
30263 | precisely as practical, in some situations (for example for reasons of | |
30264 | efficiency, or where the effect is heavily dependent on the host or target | |
30265 | platform) the implementation is allowed some freedom. In porting Ada 83 | |
30266 | code to GNAT, you need to be aware of whether / how the existing code | |
30267 | exercised such implementation dependencies. Such characteristics fall into | |
30268 | several categories, and GNAT offers specific support in assisting the | |
30269 | transition from certain Ada 83 compilers. | |
30270 | ||
30271 | @menu | |
30272 | * Implementation-defined pragmas:: | |
30273 | * Implementation-defined attributes:: | |
30274 | * Libraries:: | |
30275 | * Elaboration order:: | |
30276 | * Target-specific aspects:: | |
30277 | ||
30278 | @end menu | |
30279 | ||
30280 | @node Implementation-defined pragmas,Implementation-defined attributes,,Implementation-dependent characteristics | |
04d6c745 | 30281 | @anchor{gnat_rm/compatibility_and_porting_guide id10}@anchor{46a}@anchor{gnat_rm/compatibility_and_porting_guide implementation-defined-pragmas}@anchor{46b} |
64d5610f ML |
30282 | @subsection Implementation-defined pragmas |
30283 | ||
30284 | ||
30285 | Ada compilers are allowed to supplement the language-defined pragmas, and | |
30286 | these are a potential source of non-portability. All GNAT-defined pragmas | |
30287 | are described in @ref{7,,Implementation Defined Pragmas}, | |
30288 | and these include several that are specifically | |
30289 | intended to correspond to other vendors’ Ada 83 pragmas. | |
30290 | For migrating from VADS, the pragma @code{Use_VADS_Size} may be useful. | |
30291 | For compatibility with HP Ada 83, GNAT supplies the pragmas | |
30292 | @code{Extend_System}, @code{Ident}, @code{Inline_Generic}, | |
30293 | @code{Interface_Name}, @code{Passive}, @code{Suppress_All}, | |
30294 | and @code{Volatile}. | |
30295 | Other relevant pragmas include @code{External} and @code{Link_With}. | |
30296 | Some vendor-specific | |
30297 | Ada 83 pragmas (@code{Share_Generic}, @code{Subtitle}, and @code{Title}) are | |
30298 | recognized, thus | |
30299 | avoiding compiler rejection of units that contain such pragmas; they are not | |
30300 | relevant in a GNAT context and hence are not otherwise implemented. | |
30301 | ||
30302 | @node Implementation-defined attributes,Libraries,Implementation-defined pragmas,Implementation-dependent characteristics | |
04d6c745 | 30303 | @anchor{gnat_rm/compatibility_and_porting_guide id11}@anchor{46c}@anchor{gnat_rm/compatibility_and_porting_guide implementation-defined-attributes}@anchor{46d} |
64d5610f ML |
30304 | @subsection Implementation-defined attributes |
30305 | ||
30306 | ||
30307 | Analogous to pragmas, the set of attributes may be extended by an | |
30308 | implementation. All GNAT-defined attributes are described in | |
30309 | @ref{8,,Implementation Defined Attributes}, | |
30310 | and these include several that are specifically intended | |
30311 | to correspond to other vendors’ Ada 83 attributes. For migrating from VADS, | |
30312 | the attribute @code{VADS_Size} may be useful. For compatibility with HP | |
30313 | Ada 83, GNAT supplies the attributes @code{Bit}, @code{Machine_Size} and | |
30314 | @code{Type_Class}. | |
30315 | ||
30316 | @node Libraries,Elaboration order,Implementation-defined attributes,Implementation-dependent characteristics | |
04d6c745 | 30317 | @anchor{gnat_rm/compatibility_and_porting_guide id12}@anchor{46e}@anchor{gnat_rm/compatibility_and_porting_guide libraries}@anchor{46f} |
64d5610f ML |
30318 | @subsection Libraries |
30319 | ||
30320 | ||
30321 | Vendors may supply libraries to supplement the standard Ada API. If Ada 83 | |
30322 | code uses vendor-specific libraries then there are several ways to manage | |
30323 | this in Ada 95 and later versions of the standard: | |
30324 | ||
30325 | ||
30326 | @itemize * | |
30327 | ||
30328 | @item | |
30329 | If the source code for the libraries (specs and bodies) are | |
30330 | available, then the libraries can be migrated in the same way as the | |
30331 | application. | |
30332 | ||
30333 | @item | |
30334 | If the source code for the specs but not the bodies are | |
30335 | available, then you can reimplement the bodies. | |
30336 | ||
30337 | @item | |
30338 | Some features introduced by Ada 95 obviate the need for library support. For | |
30339 | example most Ada 83 vendors supplied a package for unsigned integers. The | |
30340 | Ada 95 modular type feature is the preferred way to handle this need, so | |
30341 | instead of migrating or reimplementing the unsigned integer package it may | |
30342 | be preferable to retrofit the application using modular types. | |
30343 | @end itemize | |
30344 | ||
30345 | @node Elaboration order,Target-specific aspects,Libraries,Implementation-dependent characteristics | |
04d6c745 | 30346 | @anchor{gnat_rm/compatibility_and_porting_guide elaboration-order}@anchor{470}@anchor{gnat_rm/compatibility_and_porting_guide id13}@anchor{471} |
64d5610f ML |
30347 | @subsection Elaboration order |
30348 | ||
30349 | ||
30350 | The implementation can choose any elaboration order consistent with the unit | |
30351 | dependency relationship. This freedom means that some orders can result in | |
30352 | Program_Error being raised due to an ‘Access Before Elaboration’: an attempt | |
30353 | to invoke a subprogram before its body has been elaborated, or to instantiate | |
30354 | a generic before the generic body has been elaborated. By default GNAT | |
30355 | attempts to choose a safe order (one that will not encounter access before | |
30356 | elaboration problems) by implicitly inserting @code{Elaborate} or | |
30357 | @code{Elaborate_All} pragmas where | |
30358 | needed. However, this can lead to the creation of elaboration circularities | |
30359 | and a resulting rejection of the program by gnatbind. This issue is | |
30360 | thoroughly described in the `Elaboration Order Handling in GNAT' appendix | |
30361 | in the @cite{GNAT User’s Guide}. | |
30362 | In brief, there are several | |
30363 | ways to deal with this situation: | |
30364 | ||
30365 | ||
30366 | @itemize * | |
30367 | ||
30368 | @item | |
30369 | Modify the program to eliminate the circularities, e.g., by moving | |
30370 | elaboration-time code into explicitly-invoked procedures | |
30371 | ||
30372 | @item | |
30373 | Constrain the elaboration order by including explicit @code{Elaborate_Body} or | |
30374 | @code{Elaborate} pragmas, and then inhibit the generation of implicit | |
30375 | @code{Elaborate_All} | |
30376 | pragmas either globally (as an effect of the `-gnatE' switch) or locally | |
30377 | (by selectively suppressing elaboration checks via pragma | |
30378 | @code{Suppress(Elaboration_Check)} when it is safe to do so). | |
30379 | @end itemize | |
30380 | ||
30381 | @node Target-specific aspects,,Elaboration order,Implementation-dependent characteristics | |
04d6c745 | 30382 | @anchor{gnat_rm/compatibility_and_porting_guide id14}@anchor{472}@anchor{gnat_rm/compatibility_and_porting_guide target-specific-aspects}@anchor{473} |
64d5610f ML |
30383 | @subsection Target-specific aspects |
30384 | ||
30385 | ||
30386 | Low-level applications need to deal with machine addresses, data | |
30387 | representations, interfacing with assembler code, and similar issues. If | |
30388 | such an Ada 83 application is being ported to different target hardware (for | |
30389 | example where the byte endianness has changed) then you will need to | |
30390 | carefully examine the program logic; the porting effort will heavily depend | |
30391 | on the robustness of the original design. Moreover, Ada 95 (and thus | |
30392 | Ada 2005 and Ada 2012) are sometimes | |
30393 | incompatible with typical Ada 83 compiler practices regarding implicit | |
30394 | packing, the meaning of the Size attribute, and the size of access values. | |
04d6c745 | 30395 | GNAT’s approach to these issues is described in @ref{474,,Representation Clauses}. |
64d5610f ML |
30396 | |
30397 | @node Compatibility with Other Ada Systems,Representation Clauses,Implementation-dependent characteristics,Compatibility and Porting Guide | |
04d6c745 | 30398 | @anchor{gnat_rm/compatibility_and_porting_guide compatibility-with-other-ada-systems}@anchor{475}@anchor{gnat_rm/compatibility_and_porting_guide id15}@anchor{476} |
64d5610f ML |
30399 | @section Compatibility with Other Ada Systems |
30400 | ||
30401 | ||
30402 | If programs avoid the use of implementation dependent and | |
30403 | implementation defined features, as documented in the | |
30404 | @cite{Ada Reference Manual}, there should be a high degree of portability between | |
30405 | GNAT and other Ada systems. The following are specific items which | |
30406 | have proved troublesome in moving Ada 95 programs from GNAT to other Ada 95 | |
30407 | compilers, but do not affect porting code to GNAT. | |
30408 | (As of January 2007, GNAT is the only compiler available for Ada 2005; | |
30409 | the following issues may or may not arise for Ada 2005 programs | |
30410 | when other compilers appear.) | |
30411 | ||
30412 | ||
30413 | @itemize * | |
30414 | ||
30415 | @item | |
30416 | `Ada 83 Pragmas and Attributes' | |
30417 | ||
30418 | Ada 95 compilers are allowed, but not required, to implement the missing | |
30419 | Ada 83 pragmas and attributes that are no longer defined in Ada 95. | |
30420 | GNAT implements all such pragmas and attributes, eliminating this as | |
30421 | a compatibility concern, but some other Ada 95 compilers reject these | |
30422 | pragmas and attributes. | |
30423 | ||
30424 | @item | |
30425 | `Specialized Needs Annexes' | |
30426 | ||
30427 | GNAT implements the full set of special needs annexes. At the | |
30428 | current time, it is the only Ada 95 compiler to do so. This means that | |
30429 | programs making use of these features may not be portable to other Ada | |
30430 | 95 compilation systems. | |
30431 | ||
30432 | @item | |
30433 | `Representation Clauses' | |
30434 | ||
30435 | Some other Ada 95 compilers implement only the minimal set of | |
30436 | representation clauses required by the Ada 95 reference manual. GNAT goes | |
30437 | far beyond this minimal set, as described in the next section. | |
30438 | @end itemize | |
30439 | ||
30440 | @node Representation Clauses,Compatibility with HP Ada 83,Compatibility with Other Ada Systems,Compatibility and Porting Guide | |
04d6c745 | 30441 | @anchor{gnat_rm/compatibility_and_porting_guide id16}@anchor{477}@anchor{gnat_rm/compatibility_and_porting_guide representation-clauses}@anchor{474} |
64d5610f ML |
30442 | @section Representation Clauses |
30443 | ||
30444 | ||
30445 | The Ada 83 reference manual was quite vague in describing both the minimal | |
30446 | required implementation of representation clauses, and also their precise | |
30447 | effects. Ada 95 (and thus also Ada 2005) are much more explicit, but the | |
30448 | minimal set of capabilities required is still quite limited. | |
30449 | ||
30450 | GNAT implements the full required set of capabilities in | |
30451 | Ada 95 and Ada 2005, but also goes much further, and in particular | |
30452 | an effort has been made to be compatible with existing Ada 83 usage to the | |
30453 | greatest extent possible. | |
30454 | ||
30455 | A few cases exist in which Ada 83 compiler behavior is incompatible with | |
30456 | the requirements in Ada 95 (and thus also Ada 2005). These are instances of | |
30457 | intentional or accidental dependence on specific implementation dependent | |
30458 | characteristics of these Ada 83 compilers. The following is a list of | |
30459 | the cases most likely to arise in existing Ada 83 code. | |
30460 | ||
30461 | ||
30462 | @itemize * | |
30463 | ||
30464 | @item | |
30465 | `Implicit Packing' | |
30466 | ||
30467 | Some Ada 83 compilers allowed a Size specification to cause implicit | |
30468 | packing of an array or record. This could cause expensive implicit | |
30469 | conversions for change of representation in the presence of derived | |
30470 | types, and the Ada design intends to avoid this possibility. | |
30471 | Subsequent AI’s were issued to make it clear that such implicit | |
30472 | change of representation in response to a Size clause is inadvisable, | |
30473 | and this recommendation is represented explicitly in the Ada 95 (and Ada 2005) | |
30474 | Reference Manuals as implementation advice that is followed by GNAT. | |
30475 | The problem will show up as an error | |
30476 | message rejecting the size clause. The fix is simply to provide | |
30477 | the explicit pragma @code{Pack}, or for more fine tuned control, provide | |
30478 | a Component_Size clause. | |
30479 | ||
30480 | @item | |
30481 | `Meaning of Size Attribute' | |
30482 | ||
30483 | The Size attribute in Ada 95 (and Ada 2005) for discrete types is defined as | |
30484 | the minimal number of bits required to hold values of the type. For example, | |
30485 | on a 32-bit machine, the size of @code{Natural} will typically be 31 and not | |
30486 | 32 (since no sign bit is required). Some Ada 83 compilers gave 31, and | |
30487 | some 32 in this situation. This problem will usually show up as a compile | |
30488 | time error, but not always. It is a good idea to check all uses of the | |
30489 | ‘Size attribute when porting Ada 83 code. The GNAT specific attribute | |
30490 | Object_Size can provide a useful way of duplicating the behavior of | |
30491 | some Ada 83 compiler systems. | |
30492 | ||
30493 | @item | |
30494 | `Size of Access Types' | |
30495 | ||
30496 | A common assumption in Ada 83 code is that an access type is in fact a pointer, | |
30497 | and that therefore it will be the same size as a System.Address value. This | |
30498 | assumption is true for GNAT in most cases with one exception. For the case of | |
30499 | a pointer to an unconstrained array type (where the bounds may vary from one | |
30500 | value of the access type to another), the default is to use a ‘fat pointer’, | |
30501 | which is represented as two separate pointers, one to the bounds, and one to | |
30502 | the array. This representation has a number of advantages, including improved | |
30503 | efficiency. However, it may cause some difficulties in porting existing Ada 83 | |
30504 | code which makes the assumption that, for example, pointers fit in 32 bits on | |
30505 | a machine with 32-bit addressing. | |
30506 | ||
30507 | To get around this problem, GNAT also permits the use of ‘thin pointers’ for | |
30508 | access types in this case (where the designated type is an unconstrained array | |
30509 | type). These thin pointers are indeed the same size as a System.Address value. | |
30510 | To specify a thin pointer, use a size clause for the type, for example: | |
30511 | ||
30512 | @example | |
30513 | type X is access all String; | |
30514 | for X'Size use Standard'Address_Size; | |
30515 | @end example | |
30516 | ||
30517 | which will cause the type X to be represented using a single pointer. | |
30518 | When using this representation, the bounds are right behind the array. | |
30519 | This representation is slightly less efficient, and does not allow quite | |
30520 | such flexibility in the use of foreign pointers or in using the | |
30521 | Unrestricted_Access attribute to create pointers to non-aliased objects. | |
30522 | But for any standard portable use of the access type it will work in | |
30523 | a functionally correct manner and allow porting of existing code. | |
30524 | Note that another way of forcing a thin pointer representation | |
30525 | is to use a component size clause for the element size in an array, | |
30526 | or a record representation clause for an access field in a record. | |
30527 | ||
30528 | See the documentation of Unrestricted_Access in the GNAT RM for a | |
30529 | full discussion of possible problems using this attribute in conjunction | |
30530 | with thin pointers. | |
30531 | @end itemize | |
30532 | ||
30533 | @node Compatibility with HP Ada 83,,Representation Clauses,Compatibility and Porting Guide | |
04d6c745 | 30534 | @anchor{gnat_rm/compatibility_and_porting_guide compatibility-with-hp-ada-83}@anchor{478}@anchor{gnat_rm/compatibility_and_porting_guide id17}@anchor{479} |
64d5610f ML |
30535 | @section Compatibility with HP Ada 83 |
30536 | ||
30537 | ||
30538 | All the HP Ada 83 pragmas and attributes are recognized, although only a subset | |
30539 | of them can sensibly be implemented. The description of pragmas in | |
30540 | @ref{7,,Implementation Defined Pragmas} indicates whether or not they are | |
30541 | applicable to GNAT. | |
30542 | ||
30543 | ||
30544 | @itemize * | |
30545 | ||
30546 | @item | |
30547 | `Default floating-point representation' | |
30548 | ||
30549 | In GNAT, the default floating-point format is IEEE, whereas in HP Ada 83, | |
30550 | it is VMS format. | |
30551 | ||
30552 | @item | |
30553 | `System' | |
30554 | ||
30555 | the package System in GNAT exactly corresponds to the definition in the | |
30556 | Ada 95 reference manual, which means that it excludes many of the | |
30557 | HP Ada 83 extensions. However, a separate package Aux_DEC is provided | |
30558 | that contains the additional definitions, and a special pragma, | |
30559 | Extend_System allows this package to be treated transparently as an | |
30560 | extension of package System. | |
30561 | @end itemize | |
30562 | ||
30563 | @node GNU Free Documentation License,Index,Compatibility and Porting Guide,Top | |
04d6c745 | 30564 | @anchor{share/gnu_free_documentation_license doc}@anchor{47a}@anchor{share/gnu_free_documentation_license gnu-fdl}@anchor{1}@anchor{share/gnu_free_documentation_license gnu-free-documentation-license}@anchor{47b} |
64d5610f ML |
30565 | @chapter GNU Free Documentation License |
30566 | ||
30567 | ||
30568 | Version 1.3, 3 November 2008 | |
30569 | ||
30570 | Copyright 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc | |
30571 | @indicateurl{https://fsf.org/} | |
30572 | ||
30573 | Everyone is permitted to copy and distribute verbatim copies of this | |
30574 | license document, but changing it is not allowed. | |
30575 | ||
30576 | `Preamble' | |
30577 | ||
30578 | The purpose of this License is to make a manual, textbook, or other | |
30579 | functional and useful document “free” in the sense of freedom: to | |
30580 | assure everyone the effective freedom to copy and redistribute it, | |
30581 | with or without modifying it, either commercially or noncommercially. | |
30582 | Secondarily, this License preserves for the author and publisher a way | |
30583 | to get credit for their work, while not being considered responsible | |
30584 | for modifications made by others. | |
30585 | ||
30586 | This License is a kind of “copyleft”, which means that derivative | |
30587 | works of the document must themselves be free in the same sense. It | |
30588 | complements the GNU General Public License, which is a copyleft | |
30589 | license designed for free software. | |
30590 | ||
30591 | We have designed this License in order to use it for manuals for free | |
30592 | software, because free software needs free documentation: a free | |
30593 | program should come with manuals providing the same freedoms that the | |
30594 | software does. But this License is not limited to software manuals; | |
30595 | it can be used for any textual work, regardless of subject matter or | |
30596 | whether it is published as a printed book. We recommend this License | |
30597 | principally for works whose purpose is instruction or reference. | |
30598 | ||
30599 | `1. APPLICABILITY AND DEFINITIONS' | |
30600 | ||
30601 | This License applies to any manual or other work, in any medium, that | |
30602 | contains a notice placed by the copyright holder saying it can be | |
30603 | distributed under the terms of this License. Such a notice grants a | |
30604 | world-wide, royalty-free license, unlimited in duration, to use that | |
30605 | work under the conditions stated herein. The `Document', below, | |
30606 | refers to any such manual or work. Any member of the public is a | |
30607 | licensee, and is addressed as “`you'”. You accept the license if you | |
30608 | copy, modify or distribute the work in a way requiring permission | |
30609 | under copyright law. | |
30610 | ||
30611 | A “`Modified Version'” of the Document means any work containing the | |
30612 | Document or a portion of it, either copied verbatim, or with | |
30613 | modifications and/or translated into another language. | |
30614 | ||
30615 | A “`Secondary Section'” is a named appendix or a front-matter section of | |
30616 | the Document that deals exclusively with the relationship of the | |
30617 | publishers or authors of the Document to the Document’s overall subject | |
30618 | (or to related matters) and contains nothing that could fall directly | |
30619 | within that overall subject. (Thus, if the Document is in part a | |
30620 | textbook of mathematics, a Secondary Section may not explain any | |
30621 | mathematics.) The relationship could be a matter of historical | |
30622 | connection with the subject or with related matters, or of legal, | |
30623 | commercial, philosophical, ethical or political position regarding | |
30624 | them. | |
30625 | ||
30626 | The “`Invariant Sections'” are certain Secondary Sections whose titles | |
30627 | are designated, as being those of Invariant Sections, in the notice | |
30628 | that says that the Document is released under this License. If a | |
30629 | section does not fit the above definition of Secondary then it is not | |
30630 | allowed to be designated as Invariant. The Document may contain zero | |
30631 | Invariant Sections. If the Document does not identify any Invariant | |
30632 | Sections then there are none. | |
30633 | ||
30634 | The “`Cover Texts'” are certain short passages of text that are listed, | |
30635 | as Front-Cover Texts or Back-Cover Texts, in the notice that says that | |
30636 | the Document is released under this License. A Front-Cover Text may | |
30637 | be at most 5 words, and a Back-Cover Text may be at most 25 words. | |
30638 | ||
30639 | A “`Transparent'” copy of the Document means a machine-readable copy, | |
30640 | represented in a format whose specification is available to the | |
30641 | general public, that is suitable for revising the document | |
30642 | straightforwardly with generic text editors or (for images composed of | |
30643 | pixels) generic paint programs or (for drawings) some widely available | |
30644 | drawing editor, and that is suitable for input to text formatters or | |
30645 | for automatic translation to a variety of formats suitable for input | |
30646 | to text formatters. A copy made in an otherwise Transparent file | |
30647 | format whose markup, or absence of markup, has been arranged to thwart | |
30648 | or discourage subsequent modification by readers is not Transparent. | |
30649 | An image format is not Transparent if used for any substantial amount | |
30650 | of text. A copy that is not “Transparent” is called `Opaque'. | |
30651 | ||
30652 | Examples of suitable formats for Transparent copies include plain | |
30653 | ASCII without markup, Texinfo input format, LaTeX input format, SGML | |
30654 | or XML using a publicly available DTD, and standard-conforming simple | |
30655 | HTML, PostScript or PDF designed for human modification. Examples of | |
30656 | transparent image formats include PNG, XCF and JPG. Opaque formats | |
30657 | include proprietary formats that can be read and edited only by | |
30658 | proprietary word processors, SGML or XML for which the DTD and/or | |
30659 | processing tools are not generally available, and the | |
30660 | machine-generated HTML, PostScript or PDF produced by some word | |
30661 | processors for output purposes only. | |
30662 | ||
30663 | The “`Title Page'” means, for a printed book, the title page itself, | |
30664 | plus such following pages as are needed to hold, legibly, the material | |
30665 | this License requires to appear in the title page. For works in | |
30666 | formats which do not have any title page as such, “Title Page” means | |
30667 | the text near the most prominent appearance of the work’s title, | |
30668 | preceding the beginning of the body of the text. | |
30669 | ||
30670 | The “`publisher'” means any person or entity that distributes | |
30671 | copies of the Document to the public. | |
30672 | ||
30673 | A section “`Entitled XYZ'” means a named subunit of the Document whose | |
30674 | title either is precisely XYZ or contains XYZ in parentheses following | |
30675 | text that translates XYZ in another language. (Here XYZ stands for a | |
30676 | specific section name mentioned below, such as “`Acknowledgements'”, | |
30677 | “`Dedications'”, “`Endorsements'”, or “`History'”.) | |
30678 | To “`Preserve the Title'” | |
30679 | of such a section when you modify the Document means that it remains a | |
30680 | section “Entitled XYZ” according to this definition. | |
30681 | ||
30682 | The Document may include Warranty Disclaimers next to the notice which | |
30683 | states that this License applies to the Document. These Warranty | |
30684 | Disclaimers are considered to be included by reference in this | |
30685 | License, but only as regards disclaiming warranties: any other | |
30686 | implication that these Warranty Disclaimers may have is void and has | |
30687 | no effect on the meaning of this License. | |
30688 | ||
30689 | `2. VERBATIM COPYING' | |
30690 | ||
30691 | You may copy and distribute the Document in any medium, either | |
30692 | commercially or noncommercially, provided that this License, the | |
30693 | copyright notices, and the license notice saying this License applies | |
30694 | to the Document are reproduced in all copies, and that you add no other | |
30695 | conditions whatsoever to those of this License. You may not use | |
30696 | technical measures to obstruct or control the reading or further | |
30697 | copying of the copies you make or distribute. However, you may accept | |
30698 | compensation in exchange for copies. If you distribute a large enough | |
30699 | number of copies you must also follow the conditions in section 3. | |
30700 | ||
30701 | You may also lend copies, under the same conditions stated above, and | |
30702 | you may publicly display copies. | |
30703 | ||
30704 | `3. COPYING IN QUANTITY' | |
30705 | ||
30706 | If you publish printed copies (or copies in media that commonly have | |
30707 | printed covers) of the Document, numbering more than 100, and the | |
30708 | Document’s license notice requires Cover Texts, you must enclose the | |
30709 | copies in covers that carry, clearly and legibly, all these Cover | |
30710 | Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on | |
30711 | the back cover. Both covers must also clearly and legibly identify | |
30712 | you as the publisher of these copies. The front cover must present | |
30713 | the full title with all words of the title equally prominent and | |
30714 | visible. You may add other material on the covers in addition. | |
30715 | Copying with changes limited to the covers, as long as they preserve | |
30716 | the title of the Document and satisfy these conditions, can be treated | |
30717 | as verbatim copying in other respects. | |
30718 | ||
30719 | If the required texts for either cover are too voluminous to fit | |
30720 | legibly, you should put the first ones listed (as many as fit | |
30721 | reasonably) on the actual cover, and continue the rest onto adjacent | |
30722 | pages. | |
30723 | ||
30724 | If you publish or distribute Opaque copies of the Document numbering | |
30725 | more than 100, you must either include a machine-readable Transparent | |
30726 | copy along with each Opaque copy, or state in or with each Opaque copy | |
30727 | a computer-network location from which the general network-using | |
30728 | public has access to download using public-standard network protocols | |
30729 | a complete Transparent copy of the Document, free of added material. | |
30730 | If you use the latter option, you must take reasonably prudent steps, | |
30731 | when you begin distribution of Opaque copies in quantity, to ensure | |
30732 | that this Transparent copy will remain thus accessible at the stated | |
30733 | location until at least one year after the last time you distribute an | |
30734 | Opaque copy (directly or through your agents or retailers) of that | |
30735 | edition to the public. | |
30736 | ||
30737 | It is requested, but not required, that you contact the authors of the | |
30738 | Document well before redistributing any large number of copies, to give | |
30739 | them a chance to provide you with an updated version of the Document. | |
30740 | ||
30741 | `4. MODIFICATIONS' | |
30742 | ||
30743 | You may copy and distribute a Modified Version of the Document under | |
30744 | the conditions of sections 2 and 3 above, provided that you release | |
30745 | the Modified Version under precisely this License, with the Modified | |
30746 | Version filling the role of the Document, thus licensing distribution | |
30747 | and modification of the Modified Version to whoever possesses a copy | |
30748 | of it. In addition, you must do these things in the Modified Version: | |
30749 | ||
30750 | ||
30751 | @enumerate A | |
30752 | ||
30753 | @item | |
30754 | Use in the Title Page (and on the covers, if any) a title distinct | |
30755 | from that of the Document, and from those of previous versions | |
30756 | (which should, if there were any, be listed in the History section | |
30757 | of the Document). You may use the same title as a previous version | |
30758 | if the original publisher of that version gives permission. | |
30759 | ||
30760 | @item | |
30761 | List on the Title Page, as authors, one or more persons or entities | |
30762 | responsible for authorship of the modifications in the Modified | |
30763 | Version, together with at least five of the principal authors of the | |
30764 | Document (all of its principal authors, if it has fewer than five), | |
30765 | unless they release you from this requirement. | |
30766 | ||
30767 | @item | |
30768 | State on the Title page the name of the publisher of the | |
30769 | Modified Version, as the publisher. | |
30770 | ||
30771 | @item | |
30772 | Preserve all the copyright notices of the Document. | |
30773 | ||
30774 | @item | |
30775 | Add an appropriate copyright notice for your modifications | |
30776 | adjacent to the other copyright notices. | |
30777 | ||
30778 | @item | |
30779 | Include, immediately after the copyright notices, a license notice | |
30780 | giving the public permission to use the Modified Version under the | |
30781 | terms of this License, in the form shown in the Addendum below. | |
30782 | ||
30783 | @item | |
30784 | Preserve in that license notice the full lists of Invariant Sections | |
30785 | and required Cover Texts given in the Document’s license notice. | |
30786 | ||
30787 | @item | |
30788 | Include an unaltered copy of this License. | |
30789 | ||
30790 | @item | |
30791 | Preserve the section Entitled “History”, Preserve its Title, and add | |
30792 | to it an item stating at least the title, year, new authors, and | |
30793 | publisher of the Modified Version as given on the Title Page. If | |
30794 | there is no section Entitled “History” in the Document, create one | |
30795 | stating the title, year, authors, and publisher of the Document as | |
30796 | given on its Title Page, then add an item describing the Modified | |
30797 | Version as stated in the previous sentence. | |
30798 | ||
30799 | @item | |
30800 | Preserve the network location, if any, given in the Document for | |
30801 | public access to a Transparent copy of the Document, and likewise | |
30802 | the network locations given in the Document for previous versions | |
30803 | it was based on. These may be placed in the “History” section. | |
30804 | You may omit a network location for a work that was published at | |
30805 | least four years before the Document itself, or if the original | |
30806 | publisher of the version it refers to gives permission. | |
30807 | ||
30808 | @item | |
30809 | For any section Entitled “Acknowledgements” or “Dedications”, | |
30810 | Preserve the Title of the section, and preserve in the section all | |
30811 | the substance and tone of each of the contributor acknowledgements | |
30812 | and/or dedications given therein. | |
30813 | ||
30814 | @item | |
30815 | Preserve all the Invariant Sections of the Document, | |
30816 | unaltered in their text and in their titles. Section numbers | |
30817 | or the equivalent are not considered part of the section titles. | |
30818 | ||
30819 | @item | |
30820 | Delete any section Entitled “Endorsements”. Such a section | |
30821 | may not be included in the Modified Version. | |
30822 | ||
30823 | @item | |
30824 | Do not retitle any existing section to be Entitled “Endorsements” | |
30825 | or to conflict in title with any Invariant Section. | |
30826 | ||
30827 | @item | |
30828 | Preserve any Warranty Disclaimers. | |
30829 | @end enumerate | |
30830 | ||
30831 | If the Modified Version includes new front-matter sections or | |
30832 | appendices that qualify as Secondary Sections and contain no material | |
30833 | copied from the Document, you may at your option designate some or all | |
30834 | of these sections as invariant. To do this, add their titles to the | |
30835 | list of Invariant Sections in the Modified Version’s license notice. | |
30836 | These titles must be distinct from any other section titles. | |
30837 | ||
30838 | You may add a section Entitled “Endorsements”, provided it contains | |
30839 | nothing but endorsements of your Modified Version by various | |
30840 | parties—for example, statements of peer review or that the text has | |
30841 | been approved by an organization as the authoritative definition of a | |
30842 | standard. | |
30843 | ||
30844 | You may add a passage of up to five words as a Front-Cover Text, and a | |
30845 | passage of up to 25 words as a Back-Cover Text, to the end of the list | |
30846 | of Cover Texts in the Modified Version. Only one passage of | |
30847 | Front-Cover Text and one of Back-Cover Text may be added by (or | |
30848 | through arrangements made by) any one entity. If the Document already | |
30849 | includes a cover text for the same cover, previously added by you or | |
30850 | by arrangement made by the same entity you are acting on behalf of, | |
30851 | you may not add another; but you may replace the old one, on explicit | |
30852 | permission from the previous publisher that added the old one. | |
30853 | ||
30854 | The author(s) and publisher(s) of the Document do not by this License | |
30855 | give permission to use their names for publicity for or to assert or | |
30856 | imply endorsement of any Modified Version. | |
30857 | ||
30858 | `5. COMBINING DOCUMENTS' | |
30859 | ||
30860 | You may combine the Document with other documents released under this | |
30861 | License, under the terms defined in section 4 above for modified | |
30862 | versions, provided that you include in the combination all of the | |
30863 | Invariant Sections of all of the original documents, unmodified, and | |
30864 | list them all as Invariant Sections of your combined work in its | |
30865 | license notice, and that you preserve all their Warranty Disclaimers. | |
30866 | ||
30867 | The combined work need only contain one copy of this License, and | |
30868 | multiple identical Invariant Sections may be replaced with a single | |
30869 | copy. If there are multiple Invariant Sections with the same name but | |
30870 | different contents, make the title of each such section unique by | |
30871 | adding at the end of it, in parentheses, the name of the original | |
30872 | author or publisher of that section if known, or else a unique number. | |
30873 | Make the same adjustment to the section titles in the list of | |
30874 | Invariant Sections in the license notice of the combined work. | |
30875 | ||
30876 | In the combination, you must combine any sections Entitled “History” | |
30877 | in the various original documents, forming one section Entitled | |
30878 | “History”; likewise combine any sections Entitled “Acknowledgements”, | |
30879 | and any sections Entitled “Dedications”. You must delete all sections | |
30880 | Entitled “Endorsements”. | |
30881 | ||
30882 | `6. COLLECTIONS OF DOCUMENTS' | |
30883 | ||
30884 | You may make a collection consisting of the Document and other documents | |
30885 | released under this License, and replace the individual copies of this | |
30886 | License in the various documents with a single copy that is included in | |
30887 | the collection, provided that you follow the rules of this License for | |
30888 | verbatim copying of each of the documents in all other respects. | |
30889 | ||
30890 | You may extract a single document from such a collection, and distribute | |
30891 | it individually under this License, provided you insert a copy of this | |
30892 | License into the extracted document, and follow this License in all | |
30893 | other respects regarding verbatim copying of that document. | |
30894 | ||
30895 | `7. AGGREGATION WITH INDEPENDENT WORKS' | |
30896 | ||
30897 | A compilation of the Document or its derivatives with other separate | |
30898 | and independent documents or works, in or on a volume of a storage or | |
30899 | distribution medium, is called an “aggregate” if the copyright | |
30900 | resulting from the compilation is not used to limit the legal rights | |
30901 | of the compilation’s users beyond what the individual works permit. | |
30902 | When the Document is included in an aggregate, this License does not | |
30903 | apply to the other works in the aggregate which are not themselves | |
30904 | derivative works of the Document. | |
30905 | ||
30906 | If the Cover Text requirement of section 3 is applicable to these | |
30907 | copies of the Document, then if the Document is less than one half of | |
30908 | the entire aggregate, the Document’s Cover Texts may be placed on | |
30909 | covers that bracket the Document within the aggregate, or the | |
30910 | electronic equivalent of covers if the Document is in electronic form. | |
30911 | Otherwise they must appear on printed covers that bracket the whole | |
30912 | aggregate. | |
30913 | ||
30914 | `8. TRANSLATION' | |
30915 | ||
30916 | Translation is considered a kind of modification, so you may | |
30917 | distribute translations of the Document under the terms of section 4. | |
30918 | Replacing Invariant Sections with translations requires special | |
30919 | permission from their copyright holders, but you may include | |
30920 | translations of some or all Invariant Sections in addition to the | |
30921 | original versions of these Invariant Sections. You may include a | |
30922 | translation of this License, and all the license notices in the | |
30923 | Document, and any Warranty Disclaimers, provided that you also include | |
30924 | the original English version of this License and the original versions | |
30925 | of those notices and disclaimers. In case of a disagreement between | |
30926 | the translation and the original version of this License or a notice | |
30927 | or disclaimer, the original version will prevail. | |
30928 | ||
30929 | If a section in the Document is Entitled “Acknowledgements”, | |
30930 | “Dedications”, or “History”, the requirement (section 4) to Preserve | |
30931 | its Title (section 1) will typically require changing the actual | |
30932 | title. | |
30933 | ||
30934 | `9. TERMINATION' | |
30935 | ||
30936 | You may not copy, modify, sublicense, or distribute the Document | |
30937 | except as expressly provided under this License. Any attempt | |
30938 | otherwise to copy, modify, sublicense, or distribute it is void, and | |
30939 | will automatically terminate your rights under this License. | |
30940 | ||
30941 | However, if you cease all violation of this License, then your license | |
30942 | from a particular copyright holder is reinstated (a) provisionally, | |
30943 | unless and until the copyright holder explicitly and finally | |
30944 | terminates your license, and (b) permanently, if the copyright holder | |
30945 | fails to notify you of the violation by some reasonable means prior to | |
30946 | 60 days after the cessation. | |
30947 | ||
30948 | Moreover, your license from a particular copyright holder is | |
30949 | reinstated permanently if the copyright holder notifies you of the | |
30950 | violation by some reasonable means, this is the first time you have | |
30951 | received notice of violation of this License (for any work) from that | |
30952 | copyright holder, and you cure the violation prior to 30 days after | |
30953 | your receipt of the notice. | |
30954 | ||
30955 | Termination of your rights under this section does not terminate the | |
30956 | licenses of parties who have received copies or rights from you under | |
30957 | this License. If your rights have been terminated and not permanently | |
30958 | reinstated, receipt of a copy of some or all of the same material does | |
30959 | not give you any rights to use it. | |
30960 | ||
30961 | `10. FUTURE REVISIONS OF THIS LICENSE' | |
30962 | ||
30963 | The Free Software Foundation may publish new, revised versions | |
30964 | of the GNU Free Documentation License from time to time. Such new | |
30965 | versions will be similar in spirit to the present version, but may | |
30966 | differ in detail to address new problems or concerns. See | |
30967 | @indicateurl{https://www.gnu.org/copyleft/}. | |
30968 | ||
30969 | Each version of the License is given a distinguishing version number. | |
30970 | If the Document specifies that a particular numbered version of this | |
30971 | License “or any later version” applies to it, you have the option of | |
30972 | following the terms and conditions either of that specified version or | |
30973 | of any later version that has been published (not as a draft) by the | |
30974 | Free Software Foundation. If the Document does not specify a version | |
30975 | number of this License, you may choose any version ever published (not | |
30976 | as a draft) by the Free Software Foundation. If the Document | |
30977 | specifies that a proxy can decide which future versions of this | |
30978 | License can be used, that proxy’s public statement of acceptance of a | |
30979 | version permanently authorizes you to choose that version for the | |
30980 | Document. | |
30981 | ||
30982 | `11. RELICENSING' | |
30983 | ||
30984 | “Massive Multiauthor Collaboration Site” (or “MMC Site”) means any | |
30985 | World Wide Web server that publishes copyrightable works and also | |
30986 | provides prominent facilities for anybody to edit those works. A | |
30987 | public wiki that anybody can edit is an example of such a server. A | |
30988 | “Massive Multiauthor Collaboration” (or “MMC”) contained in the | |
30989 | site means any set of copyrightable works thus published on the MMC | |
30990 | site. | |
30991 | ||
30992 | “CC-BY-SA” means the Creative Commons Attribution-Share Alike 3.0 | |
30993 | license published by Creative Commons Corporation, a not-for-profit | |
30994 | corporation with a principal place of business in San Francisco, | |
30995 | California, as well as future copyleft versions of that license | |
30996 | published by that same organization. | |
30997 | ||
30998 | “Incorporate” means to publish or republish a Document, in whole or | |
30999 | in part, as part of another Document. | |
31000 | ||
31001 | An MMC is “eligible for relicensing” if it is licensed under this | |
31002 | License, and if all works that were first published under this License | |
31003 | somewhere other than this MMC, and subsequently incorporated in whole | |
31004 | or in part into the MMC, (1) had no cover texts or invariant sections, | |
31005 | and (2) were thus incorporated prior to November 1, 2008. | |
31006 | ||
31007 | The operator of an MMC Site may republish an MMC contained in the site | |
31008 | under CC-BY-SA on the same site at any time before August 1, 2009, | |
31009 | provided the MMC is eligible for relicensing. | |
31010 | ||
31011 | `ADDENDUM: How to use this License for your documents' | |
31012 | ||
31013 | To use this License in a document you have written, include a copy of | |
31014 | the License in the document and put the following copyright and | |
31015 | license notices just after the title page: | |
31016 | ||
31017 | @quotation | |
31018 | ||
31019 | Copyright © YEAR YOUR NAME. | |
31020 | Permission is granted to copy, distribute and/or modify this document | |
31021 | under the terms of the GNU Free Documentation License, Version 1.3 | |
31022 | or any later version published by the Free Software Foundation; | |
31023 | with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. | |
31024 | A copy of the license is included in the section entitled “GNU | |
31025 | Free Documentation License”. | |
31026 | @end quotation | |
31027 | ||
31028 | If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, | |
31029 | replace the “with … Texts.” line with this: | |
31030 | ||
31031 | @quotation | |
31032 | ||
31033 | with the Invariant Sections being LIST THEIR TITLES, with the | |
31034 | Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. | |
31035 | @end quotation | |
31036 | ||
31037 | If you have Invariant Sections without Cover Texts, or some other | |
31038 | combination of the three, merge those two alternatives to suit the | |
31039 | situation. | |
31040 | ||
31041 | If your document contains nontrivial examples of program code, we | |
31042 | recommend releasing these examples in parallel under your choice of | |
31043 | free software license, such as the GNU General Public License, | |
31044 | to permit their use in free software. | |
31045 | ||
31046 | @node Index,,GNU Free Documentation License,Top | |
31047 | @unnumbered Index | |
31048 | ||
31049 | ||
31050 | @printindex ge | |
31051 | ||
31052 | ||
31053 | @c %**end of body | |
31054 | @bye |