1\input texinfo   @c -*-texinfo-*-
2@c %**start of header
3@setfilename gnat_rm.info
4@documentencoding UTF-8
5@ifinfo
6@*Generated by Sphinx 4.3.0.@*
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@definfoenclose strong,`,'
19@definfoenclose emph,`,'
20@c %**end of header
21
22@copying
23@quotation
24GNAT Reference Manual , Nov 30, 2021
25
26AdaCore
27
28Copyright @copyright{} 2008-2021, Free Software Foundation
29@end quotation
30
31@end copying
32
33@titlepage
34@title GNAT Reference Manual
35@insertcopying
36@end titlepage
37@contents
38
39@c %** start of user preamble
40
41@c %** end of user preamble
42
43@ifnottex
44@node Top
45@top GNAT Reference Manual
46@insertcopying
47@end ifnottex
48
49@c %**start of body
50@anchor{gnat_rm doc}@anchor{0}
51@emph{GNAT, The GNU Ada Development Environment}
52
53
54@include gcc-common.texi
55GCC version @value{version-GCC}@*
56AdaCore
57
58Permission is granted to copy, distribute and/or modify this document
59under the terms of the GNU Free Documentation License, Version 1.3 or
60any later version published by the Free Software Foundation; with no
61Invariant Sections, with the Front-Cover Texts being “GNAT Reference
62Manual”, and with no Back-Cover Texts.  A copy of the license is
63included in the section entitled @ref{1,,GNU Free Documentation License}.
64
65@menu
66* About This Guide::
67* Implementation Defined Pragmas::
68* Implementation Defined Aspects::
69* Implementation Defined Attributes::
70* Standard and Implementation Defined Restrictions::
71* Implementation Advice::
72* Implementation Defined Characteristics::
73* Intrinsic Subprograms::
74* Representation Clauses and Pragmas::
75* Standard Library Routines::
76* The Implementation of Standard I/O::
77* The GNAT Library::
78* Interfacing to Other Languages::
79* Specialized Needs Annexes::
80* Implementation of Specific Ada Features::
81* Implementation of Ada 2012 Features::
82* Security Hardening Features::
83* Obsolescent Features::
84* Compatibility and Porting Guide::
85* GNU Free Documentation License::
86* Index::
87
88@detailmenu
89 --- The Detailed Node Listing ---
90
91About This Guide
92
93* What This Reference Manual Contains::
94* Conventions::
95* Related Information::
96
97Implementation Defined Pragmas
98
99* Pragma Abort_Defer::
100* Pragma Abstract_State::
101* Pragma Ada_83::
102* Pragma Ada_95::
103* Pragma Ada_05::
104* Pragma Ada_2005::
105* Pragma Ada_12::
106* Pragma Ada_2012::
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 Compiler_Unit::
128* Pragma Compiler_Unit_Warning::
129* Pragma Complete_Representation::
130* Pragma Complex_Representation::
131* Pragma Component_Alignment::
132* Pragma Constant_After_Elaboration::
133* Pragma Contract_Cases::
134* Pragma Convention_Identifier::
135* Pragma CPP_Class::
136* Pragma CPP_Constructor::
137* Pragma CPP_Virtual::
138* Pragma CPP_Vtable::
139* Pragma CPU::
140* Pragma Deadline_Floor::
141* Pragma Default_Initial_Condition::
142* Pragma Debug::
143* Pragma Debug_Policy::
144* Pragma Default_Scalar_Storage_Order::
145* Pragma Default_Storage_Pool::
146* Pragma Depends::
147* Pragma Detect_Blocking::
148* Pragma Disable_Atomic_Synchronization::
149* Pragma Dispatching_Domain::
150* Pragma Effective_Reads::
151* Pragma Effective_Writes::
152* Pragma Elaboration_Checks::
153* Pragma Eliminate::
154* Pragma Enable_Atomic_Synchronization::
155* Pragma Export_Function::
156* Pragma Export_Object::
157* Pragma Export_Procedure::
158* Pragma Export_Valued_Procedure::
159* Pragma Extend_System::
160* Pragma Extensions_Allowed::
161* Pragma Extensions_Visible::
162* Pragma External::
163* Pragma External_Name_Casing::
164* Pragma Fast_Math::
165* Pragma Favor_Top_Level::
166* Pragma Finalize_Storage_Only::
167* Pragma Float_Representation::
168* Pragma Ghost::
169* Pragma Global::
170* Pragma Ident::
171* Pragma Ignore_Pragma::
172* Pragma Implementation_Defined::
173* Pragma Implemented::
174* Pragma Implicit_Packing::
175* Pragma Import_Function::
176* Pragma Import_Object::
177* Pragma Import_Procedure::
178* Pragma Import_Valued_Procedure::
179* Pragma Independent::
180* Pragma Independent_Components::
181* Pragma Initial_Condition::
182* Pragma Initialize_Scalars::
183* Pragma Initializes::
184* Pragma Inline_Always::
185* Pragma Inline_Generic::
186* Pragma Interface::
187* Pragma Interface_Name::
188* Pragma Interrupt_Handler::
189* Pragma Interrupt_State::
190* Pragma Invariant::
191* Pragma Keep_Names::
192* Pragma License::
193* Pragma Link_With::
194* Pragma Linker_Alias::
195* Pragma Linker_Constructor::
196* Pragma Linker_Destructor::
197* Pragma Linker_Section::
198* Pragma Lock_Free::
199* Pragma Loop_Invariant::
200* Pragma Loop_Optimize::
201* Pragma Loop_Variant::
202* Pragma Machine_Attribute::
203* Pragma Main::
204* Pragma Main_Storage::
205* Pragma Max_Queue_Length::
206* Pragma No_Body::
207* Pragma No_Caching::
208* Pragma No_Component_Reordering::
209* Pragma No_Elaboration_Code_All::
210* Pragma No_Heap_Finalization::
211* Pragma No_Inline::
212* Pragma No_Return::
213* Pragma No_Strict_Aliasing::
214* Pragma No_Tagged_Streams::
215* Pragma Normalize_Scalars::
216* Pragma Obsolescent::
217* Pragma Optimize_Alignment::
218* Pragma Ordered::
219* Pragma Overflow_Mode::
220* Pragma Overriding_Renamings::
221* Pragma Partition_Elaboration_Policy::
222* Pragma Part_Of::
223* Pragma Passive::
224* Pragma Persistent_BSS::
225* Pragma Post::
226* Pragma Postcondition::
227* Pragma Post_Class::
228* Pragma Pre::
229* Pragma Precondition::
230* Pragma Predicate::
231* Pragma Predicate_Failure::
232* Pragma Preelaborable_Initialization::
233* Pragma Prefix_Exception_Messages::
234* Pragma Pre_Class::
235* Pragma Priority_Specific_Dispatching::
236* Pragma Profile::
237* Pragma Profile_Warnings::
238* Pragma Propagate_Exceptions::
239* Pragma Provide_Shift_Operators::
240* Pragma Psect_Object::
241* Pragma Pure_Function::
242* Pragma Rational::
243* Pragma Ravenscar::
244* Pragma Refined_Depends::
245* Pragma Refined_Global::
246* Pragma Refined_Post::
247* Pragma Refined_State::
248* Pragma Relative_Deadline::
249* Pragma Remote_Access_Type::
250* Pragma Rename_Pragma::
251* Pragma Restricted_Run_Time::
252* Pragma Restriction_Warnings::
253* Pragma Reviewable::
254* Pragma Secondary_Stack_Size::
255* Pragma Share_Generic::
256* Pragma Shared::
257* Pragma Short_Circuit_And_Or::
258* Pragma Short_Descriptors::
259* Pragma Simple_Storage_Pool_Type::
260* Pragma Source_File_Name::
261* Pragma Source_File_Name_Project::
262* Pragma Source_Reference::
263* Pragma SPARK_Mode::
264* Pragma Static_Elaboration_Desired::
265* Pragma Stream_Convert::
266* Pragma Style_Checks::
267* Pragma Subtitle::
268* Pragma Suppress::
269* Pragma Suppress_All::
270* Pragma Suppress_Debug_Info::
271* Pragma Suppress_Exception_Locations::
272* Pragma Suppress_Initialization::
273* Pragma Task_Name::
274* Pragma Task_Storage::
275* Pragma Test_Case::
276* Pragma Thread_Local_Storage::
277* Pragma Time_Slice::
278* Pragma Title::
279* Pragma Type_Invariant::
280* Pragma Type_Invariant_Class::
281* Pragma Unchecked_Union::
282* Pragma Unevaluated_Use_Of_Old::
283* Pragma Unimplemented_Unit::
284* Pragma Universal_Aliasing::
285* Pragma Unmodified::
286* Pragma Unreferenced::
287* Pragma Unreferenced_Objects::
288* Pragma Unreserve_All_Interrupts::
289* Pragma Unsuppress::
290* Pragma Use_VADS_Size::
291* Pragma Unused::
292* Pragma Validity_Checks::
293* Pragma Volatile::
294* Pragma Volatile_Full_Access::
295* Pragma Volatile_Function::
296* Pragma Warning_As_Error::
297* Pragma Warnings::
298* Pragma Weak_External::
299* Pragma Wide_Character_Encoding::
300
301Implementation Defined Aspects
302
303* Aspect Abstract_State::
304* Aspect Annotate::
305* Aspect Async_Readers::
306* Aspect Async_Writers::
307* Aspect Constant_After_Elaboration::
308* Aspect Contract_Cases::
309* Aspect Depends::
310* Aspect Default_Initial_Condition::
311* Aspect Dimension::
312* Aspect Dimension_System::
313* Aspect Disable_Controlled::
314* Aspect Effective_Reads::
315* Aspect Effective_Writes::
316* Aspect Extensions_Visible::
317* Aspect Favor_Top_Level::
318* Aspect Ghost::
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::
349* Aspect Simple_Storage_Pool::
350* Aspect Simple_Storage_Pool_Type::
351* Aspect SPARK_Mode::
352* Aspect Suppress_Debug_Info::
353* Aspect Suppress_Initialization::
354* Aspect Test_Case::
355* Aspect Thread_Local_Storage::
356* Aspect Universal_Aliasing::
357* Aspect Unmodified::
358* Aspect Unreferenced::
359* Aspect Unreferenced_Objects::
360* Aspect Value_Size::
361* Aspect Volatile_Full_Access::
362* Aspect Volatile_Function::
363* Aspect Warnings::
364
365Implementation Defined Attributes
366
367* Attribute Abort_Signal::
368* Attribute Address_Size::
369* Attribute Asm_Input::
370* Attribute Asm_Output::
371* Attribute Atomic_Always_Lock_Free::
372* Attribute Bit::
373* Attribute Bit_Position::
374* Attribute Code_Address::
375* Attribute Compiler_Version::
376* Attribute Constrained::
377* Attribute Default_Bit_Order::
378* Attribute Default_Scalar_Storage_Order::
379* Attribute Deref::
380* Attribute Descriptor_Size::
381* Attribute Elaborated::
382* Attribute Elab_Body::
383* Attribute Elab_Spec::
384* Attribute Elab_Subp_Body::
385* Attribute Emax::
386* Attribute Enabled::
387* Attribute Enum_Rep::
388* Attribute Enum_Val::
389* Attribute Epsilon::
390* Attribute Fast_Math::
391* Attribute Finalization_Size::
392* Attribute Fixed_Value::
393* Attribute From_Any::
394* Attribute Has_Access_Values::
395* Attribute Has_Discriminants::
396* Attribute Has_Tagged_Values::
397* Attribute Img::
398* Attribute Initialized::
399* Attribute Integer_Value::
400* Attribute Invalid_Value::
401* Attribute Iterable::
402* Attribute Large::
403* Attribute Library_Level::
404* Attribute Lock_Free::
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_Image::
441* Attribute Valid_Scalars::
442* Attribute VADS_Size::
443* Attribute Value_Size::
444* Attribute Wchar_T_Size::
445* Attribute Word_Size::
446
447Standard and Implementation Defined Restrictions
448
449* Partition-Wide Restrictions::
450* Program Unit Level Restrictions::
451
452Partition-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_Timing_Events::
497* No_Long_Long_Integers::
498* No_Multiple_Elaboration::
499* No_Nested_Finalization::
500* No_Protected_Type_Allocators::
501* No_Protected_Types::
502* No_Recursion::
503* No_Reentrancy::
504* No_Relative_Delay::
505* No_Requeue_Statements::
506* No_Secondary_Stack::
507* No_Select_Statements::
508* No_Specific_Termination_Handlers::
509* No_Specification_of_Aspect::
510* No_Standard_Allocators_After_Elaboration::
511* No_Standard_Storage_Pools::
512* No_Stream_Optimizations::
513* No_Streams::
514* No_Task_Allocators::
515* No_Task_At_Interrupt_Priority::
516* No_Task_Attributes_Package::
517* No_Task_Hierarchy::
518* No_Task_Termination::
519* No_Tasking::
520* No_Terminate_Alternatives::
521* No_Unchecked_Access::
522* No_Unchecked_Conversion::
523* No_Unchecked_Deallocation::
524* No_Use_Of_Entity::
525* Pure_Barriers::
526* Simple_Barriers::
527* Static_Priorities::
528* Static_Storage_Size::
529
530Program Unit Level Restrictions
531
532* No_Elaboration_Code::
533* No_Dynamic_Accessibility_Checks::
534* No_Dynamic_Sized_Objects::
535* No_Entry_Queue::
536* No_Implementation_Aspect_Specifications::
537* No_Implementation_Attributes::
538* No_Implementation_Identifiers::
539* No_Implementation_Pragmas::
540* No_Implementation_Restrictions::
541* No_Implementation_Units::
542* No_Implicit_Aliasing::
543* No_Implicit_Loops::
544* No_Obsolescent_Features::
545* No_Wide_Characters::
546* Static_Dispatch_Tables::
547* SPARK_05::
548
549Implementation Advice
550
551* RM 1.1.3(20); Error Detection: RM 1 1 3 20 Error Detection.
552* RM 1.1.3(31); Child Units: RM 1 1 3 31 Child Units.
553* RM 1.1.5(12); Bounded Errors: RM 1 1 5 12 Bounded Errors.
554* RM 2.8(16); Pragmas: RM 2 8 16 Pragmas.
555* RM 2.8(17-19); Pragmas: RM 2 8 17-19 Pragmas.
556* RM 3.5.2(5); Alternative Character Sets: RM 3 5 2 5 Alternative Character Sets.
557* RM 3.5.4(28); Integer Types: RM 3 5 4 28 Integer Types.
558* RM 3.5.4(29); Integer Types: RM 3 5 4 29 Integer Types.
559* RM 3.5.5(8); Enumeration Values: RM 3 5 5 8 Enumeration Values.
560* RM 3.5.7(17); Float Types: RM 3 5 7 17 Float Types.
561* RM 3.6.2(11); Multidimensional Arrays: RM 3 6 2 11 Multidimensional Arrays.
562* RM 9.6(30-31); Duration’Small: RM 9 6 30-31 Duration’Small.
563* RM 10.2.1(12); Consistent Representation: RM 10 2 1 12 Consistent Representation.
564* RM 11.4.1(19); Exception Information: RM 11 4 1 19 Exception Information.
565* RM 11.5(28); Suppression of Checks: RM 11 5 28 Suppression of Checks.
566* RM 13.1 (21-24); Representation Clauses: RM 13 1 21-24 Representation Clauses.
567* RM 13.2(6-8); Packed Types: RM 13 2 6-8 Packed Types.
568* RM 13.3(14-19); Address Clauses: RM 13 3 14-19 Address Clauses.
569* RM 13.3(29-35); Alignment Clauses: RM 13 3 29-35 Alignment Clauses.
570* RM 13.3(42-43); Size Clauses: RM 13 3 42-43 Size Clauses.
571* RM 13.3(50-56); Size Clauses: RM 13 3 50-56 Size Clauses.
572* RM 13.3(71-73); Component Size Clauses: RM 13 3 71-73 Component Size Clauses.
573* RM 13.4(9-10); Enumeration Representation Clauses: RM 13 4 9-10 Enumeration Representation Clauses.
574* RM 13.5.1(17-22); Record Representation Clauses: RM 13 5 1 17-22 Record Representation Clauses.
575* RM 13.5.2(5); Storage Place Attributes: RM 13 5 2 5 Storage Place Attributes.
576* RM 13.5.3(7-8); Bit Ordering: RM 13 5 3 7-8 Bit Ordering.
577* RM 13.7(37); Address as Private: RM 13 7 37 Address as Private.
578* RM 13.7.1(16); Address Operations: RM 13 7 1 16 Address Operations.
579* RM 13.9(14-17); Unchecked Conversion: RM 13 9 14-17 Unchecked Conversion.
580* RM 13.11(23-25); Implicit Heap Usage: RM 13 11 23-25 Implicit Heap Usage.
581* RM 13.11.2(17); Unchecked Deallocation: RM 13 11 2 17 Unchecked Deallocation.
582* RM 13.13.2(1.6); Stream Oriented Attributes: RM 13 13 2 1 6 Stream Oriented Attributes.
583* RM A.1(52); Names of Predefined Numeric Types: RM A 1 52 Names of Predefined Numeric Types.
584* RM A.3.2(49); Ada.Characters.Handling: RM A 3 2 49 Ada Characters Handling.
585* RM A.4.4(106); Bounded-Length String Handling: RM A 4 4 106 Bounded-Length String Handling.
586* RM A.5.2(46-47); Random Number Generation: RM A 5 2 46-47 Random Number Generation.
587* RM A.10.7(23); Get_Immediate: RM A 10 7 23 Get_Immediate.
588* RM A.18; Containers: RM A 18 Containers.
589* RM B.1(39-41); Pragma Export: RM B 1 39-41 Pragma Export.
590* RM B.2(12-13); Package Interfaces: RM B 2 12-13 Package Interfaces.
591* RM B.3(63-71); Interfacing with C: RM B 3 63-71 Interfacing with C.
592* RM B.4(95-98); Interfacing with COBOL: RM B 4 95-98 Interfacing with COBOL.
593* RM B.5(22-26); Interfacing with Fortran: RM B 5 22-26 Interfacing with Fortran.
594* RM C.1(3-5); Access to Machine Operations: RM C 1 3-5 Access to Machine Operations.
595* RM C.1(10-16); Access to Machine Operations: RM C 1 10-16 Access to Machine Operations.
596* RM C.3(28); Interrupt Support: RM C 3 28 Interrupt Support.
597* RM C.3.1(20-21); Protected Procedure Handlers: RM C 3 1 20-21 Protected Procedure Handlers.
598* RM C.3.2(25); Package Interrupts: RM C 3 2 25 Package Interrupts.
599* RM C.4(14); Pre-elaboration Requirements: RM C 4 14 Pre-elaboration Requirements.
600* RM C.5(8); Pragma Discard_Names: RM C 5 8 Pragma Discard_Names.
601* RM C.7.2(30); The Package Task_Attributes: RM C 7 2 30 The Package Task_Attributes.
602* RM D.3(17); Locking Policies: RM D 3 17 Locking Policies.
603* RM D.4(16); Entry Queuing Policies: RM D 4 16 Entry Queuing Policies.
604* RM D.6(9-10); Preemptive Abort: RM D 6 9-10 Preemptive Abort.
605* RM D.7(21); Tasking Restrictions: RM D 7 21 Tasking Restrictions.
606* RM D.8(47-49); Monotonic Time: RM D 8 47-49 Monotonic Time.
607* RM E.5(28-29); Partition Communication Subsystem: RM E 5 28-29 Partition Communication Subsystem.
608* RM F(7); COBOL Support: RM F 7 COBOL Support.
609* RM F.1(2); Decimal Radix Support: RM F 1 2 Decimal Radix Support.
610* RM G; Numerics: RM G Numerics.
611* RM G.1.1(56-58); Complex Types: RM G 1 1 56-58 Complex Types.
612* RM G.1.2(49); Complex Elementary Functions: RM G 1 2 49 Complex Elementary Functions.
613* RM G.2.4(19); Accuracy Requirements: RM G 2 4 19 Accuracy Requirements.
614* RM G.2.6(15); Complex Arithmetic Accuracy: RM G 2 6 15 Complex Arithmetic Accuracy.
615* RM H.6(15/2); Pragma Partition_Elaboration_Policy: RM H 6 15/2 Pragma Partition_Elaboration_Policy.
616
617Intrinsic Subprograms
618
619* Intrinsic Operators::
620* Compilation_ISO_Date::
621* Compilation_Date::
622* Compilation_Time::
623* Enclosing_Entity::
624* Exception_Information::
625* Exception_Message::
626* Exception_Name::
627* File::
628* Line::
629* Shifts and Rotates::
630* Source_Location::
631
632Representation Clauses and Pragmas
633
634* Alignment Clauses::
635* Size Clauses::
636* Storage_Size Clauses::
637* Size of Variant Record Objects::
638* Biased Representation::
639* Value_Size and Object_Size Clauses::
640* Component_Size Clauses::
641* Bit_Order Clauses::
642* Effect of Bit_Order on Byte Ordering::
643* Pragma Pack for Arrays::
644* Pragma Pack for Records::
645* Record Representation Clauses::
646* Handling of Records with Holes::
647* Enumeration Clauses::
648* Address Clauses::
649* Use of Address Clauses for Memory-Mapped I/O::
650* Effect of Convention on Representation::
651* Conventions and Anonymous Access Types::
652* Determining the Representations chosen by GNAT::
653
654The Implementation of Standard I/O
655
656* Standard I/O Packages::
657* FORM Strings::
658* Direct_IO::
659* Sequential_IO::
660* Text_IO::
661* Wide_Text_IO::
662* Wide_Wide_Text_IO::
663* Stream_IO::
664* Text Translation::
665* Shared Files::
666* Filenames encoding::
667* File content encoding::
668* Open Modes::
669* Operations on C Streams::
670* Interfacing to C Streams::
671
672Text_IO
673
674* Stream Pointer Positioning::
675* Reading and Writing Non-Regular Files::
676* Get_Immediate::
677* Treating Text_IO Files as Streams::
678* Text_IO Extensions::
679* Text_IO Facilities for Unbounded Strings::
680
681Wide_Text_IO
682
683* Stream Pointer Positioning: Stream Pointer Positioning<2>.
684* Reading and Writing Non-Regular Files: Reading and Writing Non-Regular Files<2>.
685
686Wide_Wide_Text_IO
687
688* Stream Pointer Positioning: Stream Pointer Positioning<3>.
689* Reading and Writing Non-Regular Files: Reading and Writing Non-Regular Files<3>.
690
691The GNAT Library
692
693* Ada.Characters.Latin_9 (a-chlat9.ads): Ada Characters Latin_9 a-chlat9 ads.
694* Ada.Characters.Wide_Latin_1 (a-cwila1.ads): Ada Characters Wide_Latin_1 a-cwila1 ads.
695* Ada.Characters.Wide_Latin_9 (a-cwila1.ads): Ada Characters Wide_Latin_9 a-cwila1 ads.
696* Ada.Characters.Wide_Wide_Latin_1 (a-chzla1.ads): Ada Characters Wide_Wide_Latin_1 a-chzla1 ads.
697* Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads): Ada Characters Wide_Wide_Latin_9 a-chzla9 ads.
698* Ada.Containers.Formal_Doubly_Linked_Lists (a-cfdlli.ads): Ada Containers Formal_Doubly_Linked_Lists a-cfdlli ads.
699* Ada.Containers.Formal_Hashed_Maps (a-cfhama.ads): Ada Containers Formal_Hashed_Maps a-cfhama ads.
700* Ada.Containers.Formal_Hashed_Sets (a-cfhase.ads): Ada Containers Formal_Hashed_Sets a-cfhase ads.
701* Ada.Containers.Formal_Ordered_Maps (a-cforma.ads): Ada Containers Formal_Ordered_Maps a-cforma ads.
702* Ada.Containers.Formal_Ordered_Sets (a-cforse.ads): Ada Containers Formal_Ordered_Sets a-cforse ads.
703* Ada.Containers.Formal_Vectors (a-cofove.ads): Ada Containers Formal_Vectors a-cofove ads.
704* Ada.Containers.Formal_Indefinite_Vectors (a-cfinve.ads): Ada Containers Formal_Indefinite_Vectors a-cfinve ads.
705* Ada.Containers.Functional_Vectors (a-cofuve.ads): Ada Containers Functional_Vectors a-cofuve ads.
706* Ada.Containers.Functional_Sets (a-cofuse.ads): Ada Containers Functional_Sets a-cofuse ads.
707* Ada.Containers.Functional_Maps (a-cofuma.ads): Ada Containers Functional_Maps a-cofuma ads.
708* Ada.Containers.Bounded_Holders (a-coboho.ads): Ada Containers Bounded_Holders a-coboho ads.
709* Ada.Command_Line.Environment (a-colien.ads): Ada Command_Line Environment a-colien ads.
710* Ada.Command_Line.Remove (a-colire.ads): Ada Command_Line Remove a-colire ads.
711* Ada.Command_Line.Response_File (a-clrefi.ads): Ada Command_Line Response_File a-clrefi ads.
712* Ada.Direct_IO.C_Streams (a-diocst.ads): Ada Direct_IO C_Streams a-diocst ads.
713* Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads): Ada Exceptions Is_Null_Occurrence a-einuoc ads.
714* Ada.Exceptions.Last_Chance_Handler (a-elchha.ads): Ada Exceptions Last_Chance_Handler a-elchha ads.
715* Ada.Exceptions.Traceback (a-exctra.ads): Ada Exceptions Traceback a-exctra ads.
716* Ada.Sequential_IO.C_Streams (a-siocst.ads): Ada Sequential_IO C_Streams a-siocst ads.
717* Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads): Ada Streams Stream_IO C_Streams a-ssicst ads.
718* Ada.Strings.Unbounded.Text_IO (a-suteio.ads): Ada Strings Unbounded Text_IO a-suteio ads.
719* Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads): Ada Strings Wide_Unbounded Wide_Text_IO a-swuwti ads.
720* Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads): Ada Strings Wide_Wide_Unbounded Wide_Wide_Text_IO a-szuzti ads.
721* Ada.Task_Initialization (a-tasini.ads): Ada Task_Initialization a-tasini ads.
722* Ada.Text_IO.C_Streams (a-tiocst.ads): Ada Text_IO C_Streams a-tiocst ads.
723* Ada.Text_IO.Reset_Standard_Files (a-tirsfi.ads): Ada Text_IO Reset_Standard_Files a-tirsfi ads.
724* Ada.Wide_Characters.Unicode (a-wichun.ads): Ada Wide_Characters Unicode a-wichun ads.
725* Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads): Ada Wide_Text_IO C_Streams a-wtcstr ads.
726* Ada.Wide_Text_IO.Reset_Standard_Files (a-wrstfi.ads): Ada Wide_Text_IO Reset_Standard_Files a-wrstfi ads.
727* Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads): Ada Wide_Wide_Characters Unicode a-zchuni ads.
728* Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads): Ada Wide_Wide_Text_IO C_Streams a-ztcstr ads.
729* Ada.Wide_Wide_Text_IO.Reset_Standard_Files (a-zrstfi.ads): Ada Wide_Wide_Text_IO Reset_Standard_Files a-zrstfi ads.
730* GNAT.Altivec (g-altive.ads): GNAT Altivec g-altive ads.
731* GNAT.Altivec.Conversions (g-altcon.ads): GNAT Altivec Conversions g-altcon ads.
732* GNAT.Altivec.Vector_Operations (g-alveop.ads): GNAT Altivec Vector_Operations g-alveop ads.
733* GNAT.Altivec.Vector_Types (g-alvety.ads): GNAT Altivec Vector_Types g-alvety ads.
734* GNAT.Altivec.Vector_Views (g-alvevi.ads): GNAT Altivec Vector_Views g-alvevi ads.
735* GNAT.Array_Split (g-arrspl.ads): GNAT Array_Split g-arrspl ads.
736* GNAT.AWK (g-awk.ads): GNAT AWK g-awk ads.
737* GNAT.Bind_Environment (g-binenv.ads): GNAT Bind_Environment g-binenv ads.
738* GNAT.Branch_Prediction (g-brapre.ads): GNAT Branch_Prediction g-brapre ads.
739* GNAT.Bounded_Buffers (g-boubuf.ads): GNAT Bounded_Buffers g-boubuf ads.
740* GNAT.Bounded_Mailboxes (g-boumai.ads): GNAT Bounded_Mailboxes g-boumai ads.
741* GNAT.Bubble_Sort (g-bubsor.ads): GNAT Bubble_Sort g-bubsor ads.
742* GNAT.Bubble_Sort_A (g-busora.ads): GNAT Bubble_Sort_A g-busora ads.
743* GNAT.Bubble_Sort_G (g-busorg.ads): GNAT Bubble_Sort_G g-busorg ads.
744* GNAT.Byte_Order_Mark (g-byorma.ads): GNAT Byte_Order_Mark g-byorma ads.
745* GNAT.Byte_Swapping (g-bytswa.ads): GNAT Byte_Swapping g-bytswa ads.
746* GNAT.Calendar (g-calend.ads): GNAT Calendar g-calend ads.
747* GNAT.Calendar.Time_IO (g-catiio.ads): GNAT Calendar Time_IO g-catiio ads.
748* GNAT.CRC32 (g-crc32.ads): GNAT CRC32 g-crc32 ads.
749* GNAT.Case_Util (g-casuti.ads): GNAT Case_Util g-casuti ads.
750* GNAT.CGI (g-cgi.ads): GNAT CGI g-cgi ads.
751* GNAT.CGI.Cookie (g-cgicoo.ads): GNAT CGI Cookie g-cgicoo ads.
752* GNAT.CGI.Debug (g-cgideb.ads): GNAT CGI Debug g-cgideb ads.
753* GNAT.Command_Line (g-comlin.ads): GNAT Command_Line g-comlin ads.
754* GNAT.Compiler_Version (g-comver.ads): GNAT Compiler_Version g-comver ads.
755* GNAT.Ctrl_C (g-ctrl_c.ads): GNAT Ctrl_C g-ctrl_c ads.
756* GNAT.Current_Exception (g-curexc.ads): GNAT Current_Exception g-curexc ads.
757* GNAT.Debug_Pools (g-debpoo.ads): GNAT Debug_Pools g-debpoo ads.
758* GNAT.Debug_Utilities (g-debuti.ads): GNAT Debug_Utilities g-debuti ads.
759* GNAT.Decode_String (g-decstr.ads): GNAT Decode_String g-decstr ads.
760* GNAT.Decode_UTF8_String (g-deutst.ads): GNAT Decode_UTF8_String g-deutst ads.
761* GNAT.Directory_Operations (g-dirope.ads): GNAT Directory_Operations g-dirope ads.
762* GNAT.Directory_Operations.Iteration (g-diopit.ads): GNAT Directory_Operations Iteration g-diopit ads.
763* GNAT.Dynamic_HTables (g-dynhta.ads): GNAT Dynamic_HTables g-dynhta ads.
764* GNAT.Dynamic_Tables (g-dyntab.ads): GNAT Dynamic_Tables g-dyntab ads.
765* GNAT.Encode_String (g-encstr.ads): GNAT Encode_String g-encstr ads.
766* GNAT.Encode_UTF8_String (g-enutst.ads): GNAT Encode_UTF8_String g-enutst ads.
767* GNAT.Exception_Actions (g-excact.ads): GNAT Exception_Actions g-excact ads.
768* GNAT.Exception_Traces (g-exctra.ads): GNAT Exception_Traces g-exctra ads.
769* GNAT.Exceptions (g-except.ads): GNAT Exceptions g-except ads.
770* GNAT.Expect (g-expect.ads): GNAT Expect g-expect ads.
771* GNAT.Expect.TTY (g-exptty.ads): GNAT Expect TTY g-exptty ads.
772* GNAT.Float_Control (g-flocon.ads): GNAT Float_Control g-flocon ads.
773* GNAT.Formatted_String (g-forstr.ads): GNAT Formatted_String g-forstr ads.
774* GNAT.Heap_Sort (g-heasor.ads): GNAT Heap_Sort g-heasor ads.
775* GNAT.Heap_Sort_A (g-hesora.ads): GNAT Heap_Sort_A g-hesora ads.
776* GNAT.Heap_Sort_G (g-hesorg.ads): GNAT Heap_Sort_G g-hesorg ads.
777* GNAT.HTable (g-htable.ads): GNAT HTable g-htable ads.
778* GNAT.IO (g-io.ads): GNAT IO g-io ads.
779* GNAT.IO_Aux (g-io_aux.ads): GNAT IO_Aux g-io_aux ads.
780* GNAT.Lock_Files (g-locfil.ads): GNAT Lock_Files g-locfil ads.
781* GNAT.MBBS_Discrete_Random (g-mbdira.ads): GNAT MBBS_Discrete_Random g-mbdira ads.
782* GNAT.MBBS_Float_Random (g-mbflra.ads): GNAT MBBS_Float_Random g-mbflra ads.
783* GNAT.MD5 (g-md5.ads): GNAT MD5 g-md5 ads.
784* GNAT.Memory_Dump (g-memdum.ads): GNAT Memory_Dump g-memdum ads.
785* GNAT.Most_Recent_Exception (g-moreex.ads): GNAT Most_Recent_Exception g-moreex ads.
786* GNAT.OS_Lib (g-os_lib.ads): GNAT OS_Lib g-os_lib ads.
787* GNAT.Perfect_Hash_Generators (g-pehage.ads): GNAT Perfect_Hash_Generators g-pehage ads.
788* GNAT.Random_Numbers (g-rannum.ads): GNAT Random_Numbers g-rannum ads.
789* GNAT.Regexp (g-regexp.ads): GNAT Regexp g-regexp ads.
790* GNAT.Registry (g-regist.ads): GNAT Registry g-regist ads.
791* GNAT.Regpat (g-regpat.ads): GNAT Regpat g-regpat ads.
792* GNAT.Rewrite_Data (g-rewdat.ads): GNAT Rewrite_Data g-rewdat ads.
793* GNAT.Secondary_Stack_Info (g-sestin.ads): GNAT Secondary_Stack_Info g-sestin ads.
794* GNAT.Semaphores (g-semaph.ads): GNAT Semaphores g-semaph ads.
795* GNAT.Serial_Communications (g-sercom.ads): GNAT Serial_Communications g-sercom ads.
796* GNAT.SHA1 (g-sha1.ads): GNAT SHA1 g-sha1 ads.
797* GNAT.SHA224 (g-sha224.ads): GNAT SHA224 g-sha224 ads.
798* GNAT.SHA256 (g-sha256.ads): GNAT SHA256 g-sha256 ads.
799* GNAT.SHA384 (g-sha384.ads): GNAT SHA384 g-sha384 ads.
800* GNAT.SHA512 (g-sha512.ads): GNAT SHA512 g-sha512 ads.
801* GNAT.Signals (g-signal.ads): GNAT Signals g-signal ads.
802* GNAT.Sockets (g-socket.ads): GNAT Sockets g-socket ads.
803* GNAT.Source_Info (g-souinf.ads): GNAT Source_Info g-souinf ads.
804* GNAT.Spelling_Checker (g-speche.ads): GNAT Spelling_Checker g-speche ads.
805* GNAT.Spelling_Checker_Generic (g-spchge.ads): GNAT Spelling_Checker_Generic g-spchge ads.
806* GNAT.Spitbol.Patterns (g-spipat.ads): GNAT Spitbol Patterns g-spipat ads.
807* GNAT.Spitbol (g-spitbo.ads): GNAT Spitbol g-spitbo ads.
808* GNAT.Spitbol.Table_Boolean (g-sptabo.ads): GNAT Spitbol Table_Boolean g-sptabo ads.
809* GNAT.Spitbol.Table_Integer (g-sptain.ads): GNAT Spitbol Table_Integer g-sptain ads.
810* GNAT.Spitbol.Table_VString (g-sptavs.ads): GNAT Spitbol Table_VString g-sptavs ads.
811* GNAT.SSE (g-sse.ads): GNAT SSE g-sse ads.
812* GNAT.SSE.Vector_Types (g-ssvety.ads): GNAT SSE Vector_Types g-ssvety ads.
813* GNAT.String_Hash (g-strhas.ads): GNAT String_Hash g-strhas ads.
814* GNAT.Strings (g-string.ads): GNAT Strings g-string ads.
815* GNAT.String_Split (g-strspl.ads): GNAT String_Split g-strspl ads.
816* GNAT.Table (g-table.ads): GNAT Table g-table ads.
817* GNAT.Task_Lock (g-tasloc.ads): GNAT Task_Lock g-tasloc ads.
818* GNAT.Time_Stamp (g-timsta.ads): GNAT Time_Stamp g-timsta ads.
819* GNAT.Threads (g-thread.ads): GNAT Threads g-thread ads.
820* GNAT.Traceback (g-traceb.ads): GNAT Traceback g-traceb ads.
821* GNAT.Traceback.Symbolic (g-trasym.ads): GNAT Traceback Symbolic g-trasym ads.
822* GNAT.UTF_32 (g-table.ads): GNAT UTF_32 g-table ads.
823* GNAT.Wide_Spelling_Checker (g-u3spch.ads): GNAT Wide_Spelling_Checker g-u3spch ads.
824* GNAT.Wide_Spelling_Checker (g-wispch.ads): GNAT Wide_Spelling_Checker g-wispch ads.
825* GNAT.Wide_String_Split (g-wistsp.ads): GNAT Wide_String_Split g-wistsp ads.
826* GNAT.Wide_Wide_Spelling_Checker (g-zspche.ads): GNAT Wide_Wide_Spelling_Checker g-zspche ads.
827* GNAT.Wide_Wide_String_Split (g-zistsp.ads): GNAT Wide_Wide_String_Split g-zistsp ads.
828* Interfaces.C.Extensions (i-cexten.ads): Interfaces C Extensions i-cexten ads.
829* Interfaces.C.Streams (i-cstrea.ads): Interfaces C Streams i-cstrea ads.
830* Interfaces.Packed_Decimal (i-pacdec.ads): Interfaces Packed_Decimal i-pacdec ads.
831* Interfaces.VxWorks (i-vxwork.ads): Interfaces VxWorks i-vxwork ads.
832* Interfaces.VxWorks.Int_Connection (i-vxinco.ads): Interfaces VxWorks Int_Connection i-vxinco ads.
833* Interfaces.VxWorks.IO (i-vxwoio.ads): Interfaces VxWorks IO i-vxwoio ads.
834* System.Address_Image (s-addima.ads): System Address_Image s-addima ads.
835* System.Assertions (s-assert.ads): System Assertions s-assert ads.
836* System.Atomic_Counters (s-atocou.ads): System Atomic_Counters s-atocou ads.
837* System.Memory (s-memory.ads): System Memory s-memory ads.
838* System.Multiprocessors (s-multip.ads): System Multiprocessors s-multip ads.
839* System.Multiprocessors.Dispatching_Domains (s-mudido.ads): System Multiprocessors Dispatching_Domains s-mudido ads.
840* System.Partition_Interface (s-parint.ads): System Partition_Interface s-parint ads.
841* System.Pool_Global (s-pooglo.ads): System Pool_Global s-pooglo ads.
842* System.Pool_Local (s-pooloc.ads): System Pool_Local s-pooloc ads.
843* System.Restrictions (s-restri.ads): System Restrictions s-restri ads.
844* System.Rident (s-rident.ads): System Rident s-rident ads.
845* System.Strings.Stream_Ops (s-ststop.ads): System Strings Stream_Ops s-ststop ads.
846* System.Unsigned_Types (s-unstyp.ads): System Unsigned_Types s-unstyp ads.
847* System.Wch_Cnv (s-wchcnv.ads): System Wch_Cnv s-wchcnv ads.
848* System.Wch_Con (s-wchcon.ads): System Wch_Con s-wchcon ads.
849
850Interfacing to Other Languages
851
852* Interfacing to C::
853* Interfacing to C++::
854* Interfacing to COBOL::
855* Interfacing to Fortran::
856* Interfacing to non-GNAT Ada code::
857
858Implementation of Specific Ada Features
859
860* Machine Code Insertions::
861* GNAT Implementation of Tasking::
862* GNAT Implementation of Shared Passive Packages::
863* Code Generation for Array Aggregates::
864* The Size of Discriminated Records with Default Discriminants::
865* Image Values For Nonscalar Types::
866* Strict Conformance to the Ada Reference Manual::
867
868GNAT Implementation of Tasking
869
870* Mapping Ada Tasks onto the Underlying Kernel Threads::
871* Ensuring Compliance with the Real-Time Annex::
872* Support for Locking Policies::
873
874Code Generation for Array Aggregates
875
876* Static constant aggregates with static bounds::
877* Constant aggregates with unconstrained nominal types::
878* Aggregates with static bounds::
879* Aggregates with nonstatic bounds::
880* Aggregates in assignment statements::
881
882Security Hardening Features
883
884* Register Scrubbing::
885* Stack Scrubbing::
886* Hardened Conditionals::
887
888Obsolescent Features
889
890* pragma No_Run_Time::
891* pragma Ravenscar::
892* pragma Restricted_Run_Time::
893* pragma Task_Info::
894* package System.Task_Info (s-tasinf.ads): package System Task_Info s-tasinf ads.
895
896Compatibility and Porting Guide
897
898* Writing Portable Fixed-Point Declarations::
899* Compatibility with Ada 83::
900* Compatibility between Ada 95 and Ada 2005::
901* Implementation-dependent characteristics::
902* Compatibility with Other Ada Systems::
903* Representation Clauses::
904* Compatibility with HP Ada 83::
905
906Compatibility with Ada 83
907
908* Legal Ada 83 programs that are illegal in Ada 95::
909* More deterministic semantics::
910* Changed semantics::
911* Other language compatibility issues::
912
913Implementation-dependent characteristics
914
915* Implementation-defined pragmas::
916* Implementation-defined attributes::
917* Libraries::
918* Elaboration order::
919* Target-specific aspects::
920
921@end detailmenu
922@end menu
923
924@node About This Guide,Implementation Defined Pragmas,Top,Top
925@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}
926@chapter About This Guide
927
928
929
930This manual contains useful information in writing programs using the
931GNAT compiler.  It includes information on implementation dependent
932characteristics of GNAT, including all the information required by
933Annex M of the Ada language standard.
934
935GNAT implements Ada 95, Ada 2005 and Ada 2012, and it may also be
936invoked in Ada 83 compatibility mode.
937By default, GNAT assumes Ada 2012,
938but you can override with a compiler switch
939to explicitly specify the language version.
940(Please refer to the @emph{GNAT User’s Guide} for details on these switches.)
941Throughout this manual, references to ‘Ada’ without a year suffix
942apply to all the Ada versions of the language.
943
944Ada is designed to be highly portable.
945In general, a program will have the same effect even when compiled by
946different compilers on different platforms.
947However, since Ada is designed to be used in a
948wide variety of applications, it also contains a number of system
949dependent features to be used in interfacing to the external world.
950
951@geindex Implementation-dependent features
952
953@geindex Portability
954
955Note: Any program that makes use of implementation-dependent features
956may be non-portable.  You should follow good programming practice and
957isolate and clearly document any sections of your program that make use
958of these features in a non-portable manner.
959
960@menu
961* What This Reference Manual Contains::
962* Conventions::
963* Related Information::
964
965@end menu
966
967@node What This Reference Manual Contains,Conventions,,About This Guide
968@anchor{gnat_rm/about_this_guide what-this-reference-manual-contains}@anchor{6}
969@section What This Reference Manual Contains
970
971
972This reference manual contains the following chapters:
973
974
975@itemize *
976
977@item
978@ref{7,,Implementation Defined Pragmas}, lists GNAT implementation-dependent
979pragmas, which can be used to extend and enhance the functionality of the
980compiler.
981
982@item
983@ref{8,,Implementation Defined Attributes}, lists GNAT
984implementation-dependent attributes, which can be used to extend and
985enhance the functionality of the compiler.
986
987@item
988@ref{9,,Standard and Implementation Defined Restrictions}, lists GNAT
989implementation-dependent restrictions, which can be used to extend and
990enhance the functionality of the compiler.
991
992@item
993@ref{a,,Implementation Advice}, provides information on generally
994desirable behavior which are not requirements that all compilers must
995follow since it cannot be provided on all systems, or which may be
996undesirable on some systems.
997
998@item
999@ref{b,,Implementation Defined Characteristics}, provides a guide to
1000minimizing implementation dependent features.
1001
1002@item
1003@ref{c,,Intrinsic Subprograms}, describes the intrinsic subprograms
1004implemented by GNAT, and how they can be imported into user
1005application programs.
1006
1007@item
1008@ref{d,,Representation Clauses and Pragmas}, describes in detail the
1009way that GNAT represents data, and in particular the exact set
1010of representation clauses and pragmas that is accepted.
1011
1012@item
1013@ref{e,,Standard Library Routines}, provides a listing of packages and a
1014brief description of the functionality that is provided by Ada’s
1015extensive set of standard library routines as implemented by GNAT.
1016
1017@item
1018@ref{f,,The Implementation of Standard I/O}, details how the GNAT
1019implementation of the input-output facilities.
1020
1021@item
1022@ref{10,,The GNAT Library}, is a catalog of packages that complement
1023the Ada predefined library.
1024
1025@item
1026@ref{11,,Interfacing to Other Languages}, describes how programs
1027written in Ada using GNAT can be interfaced to other programming
1028languages.
1029
1030@item
1031@ref{12,,Specialized Needs Annexes}, describes the GNAT implementation of all
1032of the specialized needs annexes.
1033
1034@item
1035@ref{13,,Implementation of Specific Ada Features}, discusses issues related
1036to GNAT’s implementation of machine code insertions, tasking, and several
1037other features.
1038
1039@item
1040@ref{14,,Implementation of Ada 2012 Features}, describes the status of the
1041GNAT implementation of the Ada 2012 language standard.
1042
1043@item
1044@ref{15,,Security Hardening Features} documents GNAT extensions aimed
1045at security hardening.
1046
1047@item
1048@ref{16,,Obsolescent Features} documents implementation dependent features,
1049including pragmas and attributes, which are considered obsolescent, since
1050there are other preferred ways of achieving the same results. These
1051obsolescent forms are retained for backwards compatibility.
1052
1053@item
1054@ref{17,,Compatibility and Porting Guide} presents some guidelines for
1055developing portable Ada code, describes the compatibility issues that
1056may arise between GNAT and other Ada compilation systems (including those
1057for Ada 83), and shows how GNAT can expedite porting applications
1058developed in other Ada environments.
1059
1060@item
1061@ref{1,,GNU Free Documentation License} contains the license for this document.
1062@end itemize
1063
1064@geindex Ada 95 Language Reference Manual
1065
1066@geindex Ada 2005 Language Reference Manual
1067
1068This reference manual assumes a basic familiarity with the Ada 95 language, as
1069described in the
1070@cite{International Standard ANSI/ISO/IEC-8652:1995}.
1071It does not require knowledge of the new features introduced by Ada 2005 or
1072Ada 2012.
1073All three reference manuals are included in the GNAT documentation
1074package.
1075
1076@node Conventions,Related Information,What This Reference Manual Contains,About This Guide
1077@anchor{gnat_rm/about_this_guide conventions}@anchor{18}
1078@section Conventions
1079
1080
1081@geindex Conventions
1082@geindex typographical
1083
1084@geindex Typographical conventions
1085
1086Following are examples of the typographical and graphic conventions used
1087in this guide:
1088
1089
1090@itemize *
1091
1092@item
1093@code{Functions}, @code{utility program names}, @code{standard names},
1094and @code{classes}.
1095
1096@item
1097@code{Option flags}
1098
1099@item
1100@code{File names}
1101
1102@item
1103@code{Variables}
1104
1105@item
1106@emph{Emphasis}
1107
1108@item
1109[optional information or parameters]
1110
1111@item
1112Examples are described by text
1113
1114@example
1115and then shown this way.
1116@end example
1117
1118@item
1119Commands that are entered by the user are shown as preceded by a prompt string
1120comprising the @code{$} character followed by a space.
1121@end itemize
1122
1123@node Related Information,,Conventions,About This Guide
1124@anchor{gnat_rm/about_this_guide related-information}@anchor{19}
1125@section Related Information
1126
1127
1128See the following documents for further information on GNAT:
1129
1130
1131@itemize *
1132
1133@item
1134@cite{GNAT User’s Guide for Native Platforms},
1135which provides information on how to use the
1136GNAT development environment.
1137
1138@item
1139@cite{Ada 95 Reference Manual}, the Ada 95 programming language standard.
1140
1141@item
1142@cite{Ada 95 Annotated Reference Manual}, which is an annotated version
1143of the Ada 95 standard.  The annotations describe
1144detailed aspects of the design decision, and in particular contain useful
1145sections on Ada 83 compatibility.
1146
1147@item
1148@cite{Ada 2005 Reference Manual}, the Ada 2005 programming language standard.
1149
1150@item
1151@cite{Ada 2005 Annotated Reference Manual}, which is an annotated version
1152of the Ada 2005 standard.  The annotations describe
1153detailed aspects of the design decision.
1154
1155@item
1156@cite{Ada 2012 Reference Manual}, the Ada 2012 programming language standard.
1157
1158@item
1159@cite{DEC Ada@comma{} Technical Overview and Comparison on DIGITAL Platforms},
1160which contains specific information on compatibility between GNAT and
1161DEC Ada 83 systems.
1162
1163@item
1164@cite{DEC Ada@comma{} Language Reference Manual}, part number AA-PYZAB-TK, which
1165describes in detail the pragmas and attributes provided by the DEC Ada 83
1166compiler system.
1167@end itemize
1168
1169@node Implementation Defined Pragmas,Implementation Defined Aspects,About This Guide,Top
1170@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}
1171@chapter Implementation Defined Pragmas
1172
1173
1174Ada defines a set of pragmas that can be used to supply additional
1175information to the compiler.  These language defined pragmas are
1176implemented in GNAT and work as described in the Ada Reference Manual.
1177
1178In addition, Ada allows implementations to define additional pragmas
1179whose meaning is defined by the implementation.  GNAT provides a number
1180of these implementation-defined pragmas, which can be used to extend
1181and enhance the functionality of the compiler.  This section of the GNAT
1182Reference Manual describes these additional pragmas.
1183
1184Note that any program using these pragmas might not be portable to other
1185compilers (although GNAT implements this set of pragmas on all
1186platforms).  Therefore if portability to other compilers is an important
1187consideration, the use of these pragmas should be minimized.
1188
1189@menu
1190* Pragma Abort_Defer::
1191* Pragma Abstract_State::
1192* Pragma Ada_83::
1193* Pragma Ada_95::
1194* Pragma Ada_05::
1195* Pragma Ada_2005::
1196* Pragma Ada_12::
1197* Pragma Ada_2012::
1198* Pragma Aggregate_Individually_Assign::
1199* Pragma Allow_Integer_Address::
1200* Pragma Annotate::
1201* Pragma Assert::
1202* Pragma Assert_And_Cut::
1203* Pragma Assertion_Policy::
1204* Pragma Assume::
1205* Pragma Assume_No_Invalid_Values::
1206* Pragma Async_Readers::
1207* Pragma Async_Writers::
1208* Pragma Attribute_Definition::
1209* Pragma C_Pass_By_Copy::
1210* Pragma Check::
1211* Pragma Check_Float_Overflow::
1212* Pragma Check_Name::
1213* Pragma Check_Policy::
1214* Pragma Comment::
1215* Pragma Common_Object::
1216* Pragma Compile_Time_Error::
1217* Pragma Compile_Time_Warning::
1218* Pragma Compiler_Unit::
1219* Pragma Compiler_Unit_Warning::
1220* Pragma Complete_Representation::
1221* Pragma Complex_Representation::
1222* Pragma Component_Alignment::
1223* Pragma Constant_After_Elaboration::
1224* Pragma Contract_Cases::
1225* Pragma Convention_Identifier::
1226* Pragma CPP_Class::
1227* Pragma CPP_Constructor::
1228* Pragma CPP_Virtual::
1229* Pragma CPP_Vtable::
1230* Pragma CPU::
1231* Pragma Deadline_Floor::
1232* Pragma Default_Initial_Condition::
1233* Pragma Debug::
1234* Pragma Debug_Policy::
1235* Pragma Default_Scalar_Storage_Order::
1236* Pragma Default_Storage_Pool::
1237* Pragma Depends::
1238* Pragma Detect_Blocking::
1239* Pragma Disable_Atomic_Synchronization::
1240* Pragma Dispatching_Domain::
1241* Pragma Effective_Reads::
1242* Pragma Effective_Writes::
1243* Pragma Elaboration_Checks::
1244* Pragma Eliminate::
1245* Pragma Enable_Atomic_Synchronization::
1246* Pragma Export_Function::
1247* Pragma Export_Object::
1248* Pragma Export_Procedure::
1249* Pragma Export_Valued_Procedure::
1250* Pragma Extend_System::
1251* Pragma Extensions_Allowed::
1252* Pragma Extensions_Visible::
1253* Pragma External::
1254* Pragma External_Name_Casing::
1255* Pragma Fast_Math::
1256* Pragma Favor_Top_Level::
1257* Pragma Finalize_Storage_Only::
1258* Pragma Float_Representation::
1259* Pragma Ghost::
1260* Pragma Global::
1261* Pragma Ident::
1262* Pragma Ignore_Pragma::
1263* Pragma Implementation_Defined::
1264* Pragma Implemented::
1265* Pragma Implicit_Packing::
1266* Pragma Import_Function::
1267* Pragma Import_Object::
1268* Pragma Import_Procedure::
1269* Pragma Import_Valued_Procedure::
1270* Pragma Independent::
1271* Pragma Independent_Components::
1272* Pragma Initial_Condition::
1273* Pragma Initialize_Scalars::
1274* Pragma Initializes::
1275* Pragma Inline_Always::
1276* Pragma Inline_Generic::
1277* Pragma Interface::
1278* Pragma Interface_Name::
1279* Pragma Interrupt_Handler::
1280* Pragma Interrupt_State::
1281* Pragma Invariant::
1282* Pragma Keep_Names::
1283* Pragma License::
1284* Pragma Link_With::
1285* Pragma Linker_Alias::
1286* Pragma Linker_Constructor::
1287* Pragma Linker_Destructor::
1288* Pragma Linker_Section::
1289* Pragma Lock_Free::
1290* Pragma Loop_Invariant::
1291* Pragma Loop_Optimize::
1292* Pragma Loop_Variant::
1293* Pragma Machine_Attribute::
1294* Pragma Main::
1295* Pragma Main_Storage::
1296* Pragma Max_Queue_Length::
1297* Pragma No_Body::
1298* Pragma No_Caching::
1299* Pragma No_Component_Reordering::
1300* Pragma No_Elaboration_Code_All::
1301* Pragma No_Heap_Finalization::
1302* Pragma No_Inline::
1303* Pragma No_Return::
1304* Pragma No_Strict_Aliasing::
1305* Pragma No_Tagged_Streams::
1306* Pragma Normalize_Scalars::
1307* Pragma Obsolescent::
1308* Pragma Optimize_Alignment::
1309* Pragma Ordered::
1310* Pragma Overflow_Mode::
1311* Pragma Overriding_Renamings::
1312* Pragma Partition_Elaboration_Policy::
1313* Pragma Part_Of::
1314* Pragma Passive::
1315* Pragma Persistent_BSS::
1316* Pragma Post::
1317* Pragma Postcondition::
1318* Pragma Post_Class::
1319* Pragma Pre::
1320* Pragma Precondition::
1321* Pragma Predicate::
1322* Pragma Predicate_Failure::
1323* Pragma Preelaborable_Initialization::
1324* Pragma Prefix_Exception_Messages::
1325* Pragma Pre_Class::
1326* Pragma Priority_Specific_Dispatching::
1327* Pragma Profile::
1328* Pragma Profile_Warnings::
1329* Pragma Propagate_Exceptions::
1330* Pragma Provide_Shift_Operators::
1331* Pragma Psect_Object::
1332* Pragma Pure_Function::
1333* Pragma Rational::
1334* Pragma Ravenscar::
1335* Pragma Refined_Depends::
1336* Pragma Refined_Global::
1337* Pragma Refined_Post::
1338* Pragma Refined_State::
1339* Pragma Relative_Deadline::
1340* Pragma Remote_Access_Type::
1341* Pragma Rename_Pragma::
1342* Pragma Restricted_Run_Time::
1343* Pragma Restriction_Warnings::
1344* Pragma Reviewable::
1345* Pragma Secondary_Stack_Size::
1346* Pragma Share_Generic::
1347* Pragma Shared::
1348* Pragma Short_Circuit_And_Or::
1349* Pragma Short_Descriptors::
1350* Pragma Simple_Storage_Pool_Type::
1351* Pragma Source_File_Name::
1352* Pragma Source_File_Name_Project::
1353* Pragma Source_Reference::
1354* Pragma SPARK_Mode::
1355* Pragma Static_Elaboration_Desired::
1356* Pragma Stream_Convert::
1357* Pragma Style_Checks::
1358* Pragma Subtitle::
1359* Pragma Suppress::
1360* Pragma Suppress_All::
1361* Pragma Suppress_Debug_Info::
1362* Pragma Suppress_Exception_Locations::
1363* Pragma Suppress_Initialization::
1364* Pragma Task_Name::
1365* Pragma Task_Storage::
1366* Pragma Test_Case::
1367* Pragma Thread_Local_Storage::
1368* Pragma Time_Slice::
1369* Pragma Title::
1370* Pragma Type_Invariant::
1371* Pragma Type_Invariant_Class::
1372* Pragma Unchecked_Union::
1373* Pragma Unevaluated_Use_Of_Old::
1374* Pragma Unimplemented_Unit::
1375* Pragma Universal_Aliasing::
1376* Pragma Unmodified::
1377* Pragma Unreferenced::
1378* Pragma Unreferenced_Objects::
1379* Pragma Unreserve_All_Interrupts::
1380* Pragma Unsuppress::
1381* Pragma Use_VADS_Size::
1382* Pragma Unused::
1383* Pragma Validity_Checks::
1384* Pragma Volatile::
1385* Pragma Volatile_Full_Access::
1386* Pragma Volatile_Function::
1387* Pragma Warning_As_Error::
1388* Pragma Warnings::
1389* Pragma Weak_External::
1390* Pragma Wide_Character_Encoding::
1391
1392@end menu
1393
1394@node Pragma Abort_Defer,Pragma Abstract_State,,Implementation Defined Pragmas
1395@anchor{gnat_rm/implementation_defined_pragmas pragma-abort-defer}@anchor{1c}
1396@section Pragma Abort_Defer
1397
1398
1399@geindex Deferring aborts
1400
1401Syntax:
1402
1403@example
1404pragma Abort_Defer;
1405@end example
1406
1407This pragma must appear at the start of the statement sequence of a
1408handled sequence of statements (right after the @code{begin}).  It has
1409the effect of deferring aborts for the sequence of statements (but not
1410for the declarations or handlers, if any, associated with this statement
1411sequence). This can also be useful for adding a polling point in Ada code,
1412where asynchronous abort of tasks is checked when leaving the statement
1413sequence, and is lighter than, for example, using @code{delay 0.0;}, since with
1414zero-cost exception handling, propagating exceptions (implicitly used to
1415implement task abort) cannot be done reliably in an asynchronous way.
1416
1417An example of usage would be:
1418
1419@example
1420--  Add a polling point to check for task aborts
1421
1422begin
1423   pragma Abort_Defer;
1424end;
1425@end example
1426
1427@node Pragma Abstract_State,Pragma Ada_83,Pragma Abort_Defer,Implementation Defined Pragmas
1428@anchor{gnat_rm/implementation_defined_pragmas id2}@anchor{1d}@anchor{gnat_rm/implementation_defined_pragmas pragma-abstract-state}@anchor{1e}
1429@section Pragma Abstract_State
1430
1431
1432Syntax:
1433
1434@example
1435pragma Abstract_State (ABSTRACT_STATE_LIST);
1436
1437ABSTRACT_STATE_LIST ::=
1438     null
1439  |  STATE_NAME_WITH_OPTIONS
1440  | (STATE_NAME_WITH_OPTIONS @{, STATE_NAME_WITH_OPTIONS@} )
1441
1442STATE_NAME_WITH_OPTIONS ::=
1443     STATE_NAME
1444  | (STATE_NAME with OPTION_LIST)
1445
1446OPTION_LIST ::= OPTION @{, OPTION@}
1447
1448OPTION ::=
1449    SIMPLE_OPTION
1450  | NAME_VALUE_OPTION
1451
1452SIMPLE_OPTION ::= Ghost | Synchronous
1453
1454NAME_VALUE_OPTION ::=
1455    Part_Of => ABSTRACT_STATE
1456  | External [=> EXTERNAL_PROPERTY_LIST]
1457
1458EXTERNAL_PROPERTY_LIST ::=
1459     EXTERNAL_PROPERTY
1460  | (EXTERNAL_PROPERTY @{, EXTERNAL_PROPERTY@} )
1461
1462EXTERNAL_PROPERTY ::=
1463    Async_Readers    [=> boolean_EXPRESSION]
1464  | Async_Writers    [=> boolean_EXPRESSION]
1465  | Effective_Reads  [=> boolean_EXPRESSION]
1466  | Effective_Writes [=> boolean_EXPRESSION]
1467    others            => boolean_EXPRESSION
1468
1469STATE_NAME ::= defining_identifier
1470
1471ABSTRACT_STATE ::= name
1472@end example
1473
1474For the semantics of this pragma, see the entry for aspect @code{Abstract_State} in
1475the SPARK 2014 Reference Manual, section 7.1.4.
1476
1477@node Pragma Ada_83,Pragma Ada_95,Pragma Abstract_State,Implementation Defined Pragmas
1478@anchor{gnat_rm/implementation_defined_pragmas pragma-ada-83}@anchor{1f}
1479@section Pragma Ada_83
1480
1481
1482Syntax:
1483
1484@example
1485pragma Ada_83;
1486@end example
1487
1488A configuration pragma that establishes Ada 83 mode for the unit to
1489which it applies, regardless of the mode set by the command line
1490switches.  In Ada 83 mode, GNAT attempts to be as compatible with
1491the syntax and semantics of Ada 83, as defined in the original Ada
149283 Reference Manual as possible.  In particular, the keywords added by Ada 95
1493and Ada 2005 are not recognized, optional package bodies are allowed,
1494and generics may name types with unknown discriminants without using
1495the @code{(<>)} notation.  In addition, some but not all of the additional
1496restrictions of Ada 83 are enforced.
1497
1498Ada 83 mode is intended for two purposes.  Firstly, it allows existing
1499Ada 83 code to be compiled and adapted to GNAT with less effort.
1500Secondly, it aids in keeping code backwards compatible with Ada 83.
1501However, there is no guarantee that code that is processed correctly
1502by GNAT in Ada 83 mode will in fact compile and execute with an Ada
150383 compiler, since GNAT does not enforce all the additional checks
1504required by Ada 83.
1505
1506@node Pragma Ada_95,Pragma Ada_05,Pragma Ada_83,Implementation Defined Pragmas
1507@anchor{gnat_rm/implementation_defined_pragmas pragma-ada-95}@anchor{20}
1508@section Pragma Ada_95
1509
1510
1511Syntax:
1512
1513@example
1514pragma Ada_95;
1515@end example
1516
1517A configuration pragma that establishes Ada 95 mode for the unit to which
1518it applies, regardless of the mode set by the command line switches.
1519This mode is set automatically for the @code{Ada} and @code{System}
1520packages and their children, so you need not specify it in these
1521contexts.  This pragma is useful when writing a reusable component that
1522itself uses Ada 95 features, but which is intended to be usable from
1523either Ada 83 or Ada 95 programs.
1524
1525@node Pragma Ada_05,Pragma Ada_2005,Pragma Ada_95,Implementation Defined Pragmas
1526@anchor{gnat_rm/implementation_defined_pragmas pragma-ada-05}@anchor{21}
1527@section Pragma Ada_05
1528
1529
1530Syntax:
1531
1532@example
1533pragma Ada_05;
1534pragma Ada_05 (local_NAME);
1535@end example
1536
1537A configuration pragma that establishes Ada 2005 mode for the unit to which
1538it applies, regardless of the mode set by the command line switches.
1539This pragma is useful when writing a reusable component that
1540itself uses Ada 2005 features, but which is intended to be usable from
1541either Ada 83 or Ada 95 programs.
1542
1543The one argument form (which is not a configuration pragma)
1544is used for managing the transition from
1545Ada 95 to Ada 2005 in the run-time library. If an entity is marked
1546as Ada_2005 only, then referencing the entity in Ada_83 or Ada_95
1547mode will generate a warning. In addition, in Ada_83 or Ada_95
1548mode, a preference rule is established which does not choose
1549such an entity unless it is unambiguously specified. This avoids
1550extra subprograms marked this way from generating ambiguities in
1551otherwise legal pre-Ada_2005 programs. The one argument form is
1552intended for exclusive use in the GNAT run-time library.
1553
1554@node Pragma Ada_2005,Pragma Ada_12,Pragma Ada_05,Implementation Defined Pragmas
1555@anchor{gnat_rm/implementation_defined_pragmas pragma-ada-2005}@anchor{22}
1556@section Pragma Ada_2005
1557
1558
1559Syntax:
1560
1561@example
1562pragma Ada_2005;
1563@end example
1564
1565This configuration pragma is a synonym for pragma Ada_05 and has the
1566same syntax and effect.
1567
1568@node Pragma Ada_12,Pragma Ada_2012,Pragma Ada_2005,Implementation Defined Pragmas
1569@anchor{gnat_rm/implementation_defined_pragmas pragma-ada-12}@anchor{23}
1570@section Pragma Ada_12
1571
1572
1573Syntax:
1574
1575@example
1576pragma Ada_12;
1577pragma Ada_12 (local_NAME);
1578@end example
1579
1580A configuration pragma that establishes Ada 2012 mode for the unit to which
1581it applies, regardless of the mode set by the command line switches.
1582This mode is set automatically for the @code{Ada} and @code{System}
1583packages and their children, so you need not specify it in these
1584contexts.  This pragma is useful when writing a reusable component that
1585itself uses Ada 2012 features, but which is intended to be usable from
1586Ada 83, Ada 95, or Ada 2005 programs.
1587
1588The one argument form, which is not a configuration pragma,
1589is used for managing the transition from Ada
15902005 to Ada 2012 in the run-time library. If an entity is marked
1591as Ada_2012 only, then referencing the entity in any pre-Ada_2012
1592mode will generate a warning. In addition, in any pre-Ada_2012
1593mode, a preference rule is established which does not choose
1594such an entity unless it is unambiguously specified. This avoids
1595extra subprograms marked this way from generating ambiguities in
1596otherwise legal pre-Ada_2012 programs. The one argument form is
1597intended for exclusive use in the GNAT run-time library.
1598
1599@node Pragma Ada_2012,Pragma Aggregate_Individually_Assign,Pragma Ada_12,Implementation Defined Pragmas
1600@anchor{gnat_rm/implementation_defined_pragmas pragma-ada-2012}@anchor{24}
1601@section Pragma Ada_2012
1602
1603
1604Syntax:
1605
1606@example
1607pragma Ada_2012;
1608@end example
1609
1610This configuration pragma is a synonym for pragma Ada_12 and has the
1611same syntax and effect.
1612
1613@node Pragma Aggregate_Individually_Assign,Pragma Allow_Integer_Address,Pragma Ada_2012,Implementation Defined Pragmas
1614@anchor{gnat_rm/implementation_defined_pragmas pragma-aggregate-individually-assign}@anchor{25}
1615@section Pragma Aggregate_Individually_Assign
1616
1617
1618Syntax:
1619
1620@example
1621pragma Aggregate_Individually_Assign;
1622@end example
1623
1624Where possible, GNAT will store the binary representation of a record aggregate
1625in memory for space and performance reasons. This configuration pragma changes
1626this behavior so that record aggregates are instead always converted into
1627individual assignment statements.
1628
1629@node Pragma Allow_Integer_Address,Pragma Annotate,Pragma Aggregate_Individually_Assign,Implementation Defined Pragmas
1630@anchor{gnat_rm/implementation_defined_pragmas pragma-allow-integer-address}@anchor{26}
1631@section Pragma Allow_Integer_Address
1632
1633
1634Syntax:
1635
1636@example
1637pragma Allow_Integer_Address;
1638@end example
1639
1640In almost all versions of GNAT, @code{System.Address} is a private
1641type in accordance with the implementation advice in the RM. This
1642means that integer values,
1643in particular integer literals, are not allowed as address values.
1644If the configuration pragma
1645@code{Allow_Integer_Address} is given, then integer expressions may
1646be used anywhere a value of type @code{System.Address} is required.
1647The effect is to introduce an implicit unchecked conversion from the
1648integer value to type @code{System.Address}. The reverse case of using
1649an address where an integer type is required is handled analogously.
1650The following example compiles without errors:
1651
1652@example
1653pragma Allow_Integer_Address;
1654with System; use System;
1655package AddrAsInt is
1656   X : Integer;
1657   Y : Integer;
1658   for X'Address use 16#1240#;
1659   for Y use at 16#3230#;
1660   m : Address := 16#4000#;
1661   n : constant Address := 4000;
1662   p : constant Address := Address (X + Y);
1663   v : Integer := y'Address;
1664   w : constant Integer := Integer (Y'Address);
1665   type R is new integer;
1666   RR : R := 1000;
1667   Z : Integer;
1668   for Z'Address use RR;
1669end AddrAsInt;
1670@end example
1671
1672Note that pragma @code{Allow_Integer_Address} is ignored if @code{System.Address}
1673is not a private type. In implementations of @code{GNAT} where
1674System.Address is a visible integer type,
1675this pragma serves no purpose but is ignored
1676rather than rejected to allow common sets of sources to be used
1677in the two situations.
1678
1679@node Pragma Annotate,Pragma Assert,Pragma Allow_Integer_Address,Implementation Defined Pragmas
1680@anchor{gnat_rm/implementation_defined_pragmas id3}@anchor{27}@anchor{gnat_rm/implementation_defined_pragmas pragma-annotate}@anchor{28}
1681@section Pragma Annotate
1682
1683
1684Syntax:
1685
1686@example
1687pragma Annotate (IDENTIFIER [, IDENTIFIER @{, ARG@}] [, entity => local_NAME]);
1688
1689ARG ::= NAME | EXPRESSION
1690@end example
1691
1692This pragma is used to annotate programs.  IDENTIFIER identifies
1693the type of annotation.  GNAT verifies that it is an identifier, but does
1694not otherwise analyze it. The second optional identifier is also left
1695unanalyzed, and by convention is used to control the action of the tool to
1696which the annotation is addressed.  The remaining ARG arguments
1697can be either string literals or more generally expressions.
1698String literals (and concatenations of string literals) are assumed to be
1699either of type
1700@code{Standard.String} or else @code{Wide_String} or @code{Wide_Wide_String}
1701depending on the character literals they contain.
1702All other kinds of arguments are analyzed as expressions, and must be
1703unambiguous. The last argument if present must have the identifier
1704@code{Entity} and GNAT verifies that a local name is given.
1705
1706The analyzed pragma is retained in the tree, but not otherwise processed
1707by any part of the GNAT compiler, except to generate corresponding note
1708lines in the generated ALI file. For the format of these note lines, see
1709the compiler source file lib-writ.ads. This pragma is intended for use by
1710external tools, including ASIS. The use of pragma Annotate does not
1711affect the compilation process in any way. This pragma may be used as
1712a configuration pragma.
1713
1714@node Pragma Assert,Pragma Assert_And_Cut,Pragma Annotate,Implementation Defined Pragmas
1715@anchor{gnat_rm/implementation_defined_pragmas pragma-assert}@anchor{29}
1716@section Pragma Assert
1717
1718
1719Syntax:
1720
1721@example
1722pragma Assert (
1723  boolean_EXPRESSION
1724  [, string_EXPRESSION]);
1725@end example
1726
1727The effect of this pragma depends on whether the corresponding command
1728line switch is set to activate assertions.  The pragma expands into code
1729equivalent to the following:
1730
1731@example
1732if assertions-enabled then
1733   if not boolean_EXPRESSION then
1734      System.Assertions.Raise_Assert_Failure
1735        (string_EXPRESSION);
1736   end if;
1737end if;
1738@end example
1739
1740The string argument, if given, is the message that will be associated
1741with the exception occurrence if the exception is raised.  If no second
1742argument is given, the default message is @code{file}:@code{nnn},
1743where @code{file} is the name of the source file containing the assert,
1744and @code{nnn} is the line number of the assert.
1745
1746Note that, as with the @code{if} statement to which it is equivalent, the
1747type of the expression is either @code{Standard.Boolean}, or any type derived
1748from this standard type.
1749
1750Assert checks can be either checked or ignored. By default they are ignored.
1751They will be checked if either the command line switch @emph{-gnata} is
1752used, or if an @code{Assertion_Policy} or @code{Check_Policy} pragma is used
1753to enable @code{Assert_Checks}.
1754
1755If assertions are ignored, then there
1756is no run-time effect (and in particular, any side effects from the
1757expression will not occur at run time).  (The expression is still
1758analyzed at compile time, and may cause types to be frozen if they are
1759mentioned here for the first time).
1760
1761If assertions are checked, then the given expression is tested, and if
1762it is @code{False} then @code{System.Assertions.Raise_Assert_Failure} is called
1763which results in the raising of @code{Assert_Failure} with the given message.
1764
1765You should generally avoid side effects in the expression arguments of
1766this pragma, because these side effects will turn on and off with the
1767setting of the assertions mode, resulting in assertions that have an
1768effect on the program.  However, the expressions are analyzed for
1769semantic correctness whether or not assertions are enabled, so turning
1770assertions on and off cannot affect the legality of a program.
1771
1772Note that the implementation defined policy @code{DISABLE}, given in a
1773pragma @code{Assertion_Policy}, can be used to suppress this semantic analysis.
1774
1775Note: this is a standard language-defined pragma in versions
1776of Ada from 2005 on. In GNAT, it is implemented in all versions
1777of Ada, and the DISABLE policy is an implementation-defined
1778addition.
1779
1780@node Pragma Assert_And_Cut,Pragma Assertion_Policy,Pragma Assert,Implementation Defined Pragmas
1781@anchor{gnat_rm/implementation_defined_pragmas pragma-assert-and-cut}@anchor{2a}
1782@section Pragma Assert_And_Cut
1783
1784
1785Syntax:
1786
1787@example
1788pragma Assert_And_Cut (
1789  boolean_EXPRESSION
1790  [, string_EXPRESSION]);
1791@end example
1792
1793The effect of this pragma is identical to that of pragma @code{Assert},
1794except that in an @code{Assertion_Policy} pragma, the identifier
1795@code{Assert_And_Cut} is used to control whether it is ignored or checked
1796(or disabled).
1797
1798The intention is that this be used within a subprogram when the
1799given test expresion sums up all the work done so far in the
1800subprogram, so that the rest of the subprogram can be verified
1801(informally or formally) using only the entry preconditions,
1802and the expression in this pragma. This allows dividing up
1803a subprogram into sections for the purposes of testing or
1804formal verification. The pragma also serves as useful
1805documentation.
1806
1807@node Pragma Assertion_Policy,Pragma Assume,Pragma Assert_And_Cut,Implementation Defined Pragmas
1808@anchor{gnat_rm/implementation_defined_pragmas pragma-assertion-policy}@anchor{2b}
1809@section Pragma Assertion_Policy
1810
1811
1812Syntax:
1813
1814@example
1815pragma Assertion_Policy (CHECK | DISABLE | IGNORE | SUPPRESSIBLE);
1816
1817pragma Assertion_Policy (
1818    ASSERTION_KIND => POLICY_IDENTIFIER
1819 @{, ASSERTION_KIND => POLICY_IDENTIFIER@});
1820
1821ASSERTION_KIND ::= RM_ASSERTION_KIND | ID_ASSERTION_KIND
1822
1823RM_ASSERTION_KIND ::= Assert                    |
1824                      Static_Predicate          |
1825                      Dynamic_Predicate         |
1826                      Pre                       |
1827                      Pre'Class                 |
1828                      Post                      |
1829                      Post'Class                |
1830                      Type_Invariant            |
1831                      Type_Invariant'Class      |
1832                      Default_Initial_Condition
1833
1834ID_ASSERTION_KIND ::= Assertions           |
1835                      Assert_And_Cut       |
1836                      Assume               |
1837                      Contract_Cases       |
1838                      Debug                |
1839                      Ghost                |
1840                      Initial_Condition    |
1841                      Invariant            |
1842                      Invariant'Class      |
1843                      Loop_Invariant       |
1844                      Loop_Variant         |
1845                      Postcondition        |
1846                      Precondition         |
1847                      Predicate            |
1848                      Refined_Post         |
1849                      Statement_Assertions |
1850                      Subprogram_Variant
1851
1852POLICY_IDENTIFIER ::= Check | Disable | Ignore | Suppressible
1853@end example
1854
1855This is a standard Ada 2012 pragma that is available as an
1856implementation-defined pragma in earlier versions of Ada.
1857The assertion kinds @code{RM_ASSERTION_KIND} are those defined in
1858the Ada standard. The assertion kinds @code{ID_ASSERTION_KIND}
1859are implementation defined additions recognized by the GNAT compiler.
1860
1861The pragma applies in both cases to pragmas and aspects with matching
1862names, e.g. @code{Pre} applies to the Pre aspect, and @code{Precondition}
1863applies to both the @code{Precondition} pragma
1864and the aspect @code{Precondition}. Note that the identifiers for
1865pragmas Pre_Class and Post_Class are Pre’Class and Post’Class (not
1866Pre_Class and Post_Class), since these pragmas are intended to be
1867identical to the corresponding aspects).
1868
1869If the policy is @code{CHECK}, then assertions are enabled, i.e.
1870the corresponding pragma or aspect is activated.
1871If the policy is @code{IGNORE}, then assertions are ignored, i.e.
1872the corresponding pragma or aspect is deactivated.
1873This pragma overrides the effect of the @emph{-gnata} switch on the
1874command line.
1875If the policy is @code{SUPPRESSIBLE}, then assertions are enabled by default,
1876however, if the @emph{-gnatp} switch is specified all assertions are ignored.
1877
1878The implementation defined policy @code{DISABLE} is like
1879@code{IGNORE} except that it completely disables semantic
1880checking of the corresponding pragma or aspect. This is
1881useful when the pragma or aspect argument references subprograms
1882in a with’ed package which is replaced by a dummy package
1883for the final build.
1884
1885The implementation defined assertion kind @code{Assertions} applies to all
1886assertion kinds. The form with no assertion kind given implies this
1887choice, so it applies to all assertion kinds (RM defined, and
1888implementation defined).
1889
1890The implementation defined assertion kind @code{Statement_Assertions}
1891applies to @code{Assert}, @code{Assert_And_Cut},
1892@code{Assume}, @code{Loop_Invariant}, and @code{Loop_Variant}.
1893
1894@node Pragma Assume,Pragma Assume_No_Invalid_Values,Pragma Assertion_Policy,Implementation Defined Pragmas
1895@anchor{gnat_rm/implementation_defined_pragmas pragma-assume}@anchor{2c}
1896@section Pragma Assume
1897
1898
1899Syntax:
1900
1901@example
1902pragma Assume (
1903  boolean_EXPRESSION
1904  [, string_EXPRESSION]);
1905@end example
1906
1907The effect of this pragma is identical to that of pragma @code{Assert},
1908except that in an @code{Assertion_Policy} pragma, the identifier
1909@code{Assume} is used to control whether it is ignored or checked
1910(or disabled).
1911
1912The intention is that this be used for assumptions about the
1913external environment. So you cannot expect to verify formally
1914or informally that the condition is met, this must be
1915established by examining things outside the program itself.
1916For example, we may have code that depends on the size of
1917@code{Long_Long_Integer} being at least 64. So we could write:
1918
1919@example
1920pragma Assume (Long_Long_Integer'Size >= 64);
1921@end example
1922
1923This assumption cannot be proved from the program itself,
1924but it acts as a useful run-time check that the assumption
1925is met, and documents the need to ensure that it is met by
1926reference to information outside the program.
1927
1928@node Pragma Assume_No_Invalid_Values,Pragma Async_Readers,Pragma Assume,Implementation Defined Pragmas
1929@anchor{gnat_rm/implementation_defined_pragmas pragma-assume-no-invalid-values}@anchor{2d}
1930@section Pragma Assume_No_Invalid_Values
1931
1932
1933@geindex Invalid representations
1934
1935@geindex Invalid values
1936
1937Syntax:
1938
1939@example
1940pragma Assume_No_Invalid_Values (On | Off);
1941@end example
1942
1943This is a configuration pragma that controls the assumptions made by the
1944compiler about the occurrence of invalid representations (invalid values)
1945in the code.
1946
1947The default behavior (corresponding to an Off argument for this pragma), is
1948to assume that values may in general be invalid unless the compiler can
1949prove they are valid. Consider the following example:
1950
1951@example
1952V1 : Integer range 1 .. 10;
1953V2 : Integer range 11 .. 20;
1954...
1955for J in V2 .. V1 loop
1956   ...
1957end loop;
1958@end example
1959
1960if V1 and V2 have valid values, then the loop is known at compile
1961time not to execute since the lower bound must be greater than the
1962upper bound. However in default mode, no such assumption is made,
1963and the loop may execute. If @code{Assume_No_Invalid_Values (On)}
1964is given, the compiler will assume that any occurrence of a variable
1965other than in an explicit @code{'Valid} test always has a valid
1966value, and the loop above will be optimized away.
1967
1968The use of @code{Assume_No_Invalid_Values (On)} is appropriate if
1969you know your code is free of uninitialized variables and other
1970possible sources of invalid representations, and may result in
1971more efficient code. A program that accesses an invalid representation
1972with this pragma in effect is erroneous, so no guarantees can be made
1973about its behavior.
1974
1975It is peculiar though permissible to use this pragma in conjunction
1976with validity checking (-gnatVa). In such cases, accessing invalid
1977values will generally give an exception, though formally the program
1978is erroneous so there are no guarantees that this will always be the
1979case, and it is recommended that these two options not be used together.
1980
1981@node Pragma Async_Readers,Pragma Async_Writers,Pragma Assume_No_Invalid_Values,Implementation Defined Pragmas
1982@anchor{gnat_rm/implementation_defined_pragmas id4}@anchor{2e}@anchor{gnat_rm/implementation_defined_pragmas pragma-async-readers}@anchor{2f}
1983@section Pragma Async_Readers
1984
1985
1986Syntax:
1987
1988@example
1989pragma Async_Readers [ (boolean_EXPRESSION) ];
1990@end example
1991
1992For the semantics of this pragma, see the entry for aspect @code{Async_Readers} in
1993the SPARK 2014 Reference Manual, section 7.1.2.
1994
1995@node Pragma Async_Writers,Pragma Attribute_Definition,Pragma Async_Readers,Implementation Defined Pragmas
1996@anchor{gnat_rm/implementation_defined_pragmas id5}@anchor{30}@anchor{gnat_rm/implementation_defined_pragmas pragma-async-writers}@anchor{31}
1997@section Pragma Async_Writers
1998
1999
2000Syntax:
2001
2002@example
2003pragma Async_Writers [ (boolean_EXPRESSION) ];
2004@end example
2005
2006For the semantics of this pragma, see the entry for aspect @code{Async_Writers} in
2007the SPARK 2014 Reference Manual, section 7.1.2.
2008
2009@node Pragma Attribute_Definition,Pragma C_Pass_By_Copy,Pragma Async_Writers,Implementation Defined Pragmas
2010@anchor{gnat_rm/implementation_defined_pragmas pragma-attribute-definition}@anchor{32}
2011@section Pragma Attribute_Definition
2012
2013
2014Syntax:
2015
2016@example
2017pragma Attribute_Definition
2018  ([Attribute  =>] ATTRIBUTE_DESIGNATOR,
2019   [Entity     =>] LOCAL_NAME,
2020   [Expression =>] EXPRESSION | NAME);
2021@end example
2022
2023If @code{Attribute} is a known attribute name, this pragma is equivalent to
2024the attribute definition clause:
2025
2026@example
2027for Entity'Attribute use Expression;
2028@end example
2029
2030If @code{Attribute} is not a recognized attribute name, the pragma is
2031ignored, and a warning is emitted. This allows source
2032code to be written that takes advantage of some new attribute, while remaining
2033compilable with earlier compilers.
2034
2035@node Pragma C_Pass_By_Copy,Pragma Check,Pragma Attribute_Definition,Implementation Defined Pragmas
2036@anchor{gnat_rm/implementation_defined_pragmas pragma-c-pass-by-copy}@anchor{33}
2037@section Pragma C_Pass_By_Copy
2038
2039
2040@geindex Passing by copy
2041
2042Syntax:
2043
2044@example
2045pragma C_Pass_By_Copy
2046  ([Max_Size =>] static_integer_EXPRESSION);
2047@end example
2048
2049Normally the default mechanism for passing C convention records to C
2050convention subprograms is to pass them by reference, as suggested by RM
2051B.3(69).  Use the configuration pragma @code{C_Pass_By_Copy} to change
2052this default, by requiring that record formal parameters be passed by
2053copy if all of the following conditions are met:
2054
2055
2056@itemize *
2057
2058@item
2059The size of the record type does not exceed the value specified for
2060@code{Max_Size}.
2061
2062@item
2063The record type has @code{Convention C}.
2064
2065@item
2066The formal parameter has this record type, and the subprogram has a
2067foreign (non-Ada) convention.
2068@end itemize
2069
2070If these conditions are met the argument is passed by copy; i.e., in a
2071manner consistent with what C expects if the corresponding formal in the
2072C prototype is a struct (rather than a pointer to a struct).
2073
2074You can also pass records by copy by specifying the convention
2075@code{C_Pass_By_Copy} for the record type, or by using the extended
2076@code{Import} and @code{Export} pragmas, which allow specification of
2077passing mechanisms on a parameter by parameter basis.
2078
2079@node Pragma Check,Pragma Check_Float_Overflow,Pragma C_Pass_By_Copy,Implementation Defined Pragmas
2080@anchor{gnat_rm/implementation_defined_pragmas pragma-check}@anchor{34}
2081@section Pragma Check
2082
2083
2084@geindex Assertions
2085
2086@geindex Named assertions
2087
2088Syntax:
2089
2090@example
2091pragma Check (
2092     [Name    =>] CHECK_KIND,
2093     [Check   =>] Boolean_EXPRESSION
2094  [, [Message =>] string_EXPRESSION] );
2095
2096CHECK_KIND ::= IDENTIFIER           |
2097               Pre'Class            |
2098               Post'Class           |
2099               Type_Invariant'Class |
2100               Invariant'Class
2101@end example
2102
2103This pragma is similar to the predefined pragma @code{Assert} except that an
2104extra identifier argument is present. In conjunction with pragma
2105@code{Check_Policy}, this can be used to define groups of assertions that can
2106be independently controlled. The identifier @code{Assertion} is special, it
2107refers to the normal set of pragma @code{Assert} statements.
2108
2109Checks introduced by this pragma are normally deactivated by default. They can
2110be activated either by the command line option @emph{-gnata}, which turns on
2111all checks, or individually controlled using pragma @code{Check_Policy}.
2112
2113The identifiers @code{Assertions} and @code{Statement_Assertions} are not
2114permitted as check kinds, since this would cause confusion with the use
2115of these identifiers in @code{Assertion_Policy} and @code{Check_Policy}
2116pragmas, where they are used to refer to sets of assertions.
2117
2118@node Pragma Check_Float_Overflow,Pragma Check_Name,Pragma Check,Implementation Defined Pragmas
2119@anchor{gnat_rm/implementation_defined_pragmas pragma-check-float-overflow}@anchor{35}
2120@section Pragma Check_Float_Overflow
2121
2122
2123@geindex Floating-point overflow
2124
2125Syntax:
2126
2127@example
2128pragma Check_Float_Overflow;
2129@end example
2130
2131In Ada, the predefined floating-point types (@code{Short_Float},
2132@code{Float}, @code{Long_Float}, @code{Long_Long_Float}) are
2133defined to be @emph{unconstrained}. This means that even though each
2134has a well-defined base range, an operation that delivers a result
2135outside this base range is not required to raise an exception.
2136This implementation permission accommodates the notion
2137of infinities in IEEE floating-point, and corresponds to the
2138efficient execution mode on most machines. GNAT will not raise
2139overflow exceptions on these machines; instead it will generate
2140infinities and NaN’s as defined in the IEEE standard.
2141
2142Generating infinities, although efficient, is not always desirable.
2143Often the preferable approach is to check for overflow, even at the
2144(perhaps considerable) expense of run-time performance.
2145This can be accomplished by defining your own constrained floating-point subtypes – i.e., by supplying explicit
2146range constraints – and indeed such a subtype
2147can have the same base range as its base type. For example:
2148
2149@example
2150subtype My_Float is Float range Float'Range;
2151@end example
2152
2153Here @code{My_Float} has the same range as
2154@code{Float} but is constrained, so operations on
2155@code{My_Float} values will be checked for overflow
2156against this range.
2157
2158This style will achieve the desired goal, but
2159it is often more convenient to be able to simply use
2160the standard predefined floating-point types as long
2161as overflow checking could be guaranteed.
2162The @code{Check_Float_Overflow}
2163configuration pragma achieves this effect. If a unit is compiled
2164subject to this configuration pragma, then all operations
2165on predefined floating-point types including operations on
2166base types of these floating-point types will be treated as
2167though those types were constrained, and overflow checks
2168will be generated. The @code{Constraint_Error}
2169exception is raised if the result is out of range.
2170
2171This mode can also be set by use of the compiler
2172switch @emph{-gnateF}.
2173
2174@node Pragma Check_Name,Pragma Check_Policy,Pragma Check_Float_Overflow,Implementation Defined Pragmas
2175@anchor{gnat_rm/implementation_defined_pragmas pragma-check-name}@anchor{36}
2176@section Pragma Check_Name
2177
2178
2179@geindex Defining check names
2180
2181@geindex Check names
2182@geindex defining
2183
2184Syntax:
2185
2186@example
2187pragma Check_Name (check_name_IDENTIFIER);
2188@end example
2189
2190This is a configuration pragma that defines a new implementation
2191defined check name (unless IDENTIFIER matches one of the predefined
2192check names, in which case the pragma has no effect). Check names
2193are global to a partition, so if two or more configuration pragmas
2194are present in a partition mentioning the same name, only one new
2195check name is introduced.
2196
2197An implementation defined check name introduced with this pragma may
2198be used in only three contexts: @code{pragma Suppress},
2199@code{pragma Unsuppress},
2200and as the prefix of a @code{Check_Name'Enabled} attribute reference. For
2201any of these three cases, the check name must be visible. A check
2202name is visible if it is in the configuration pragmas applying to
2203the current unit, or if it appears at the start of any unit that
2204is part of the dependency set of the current unit (e.g., units that
2205are mentioned in @code{with} clauses).
2206
2207Check names introduced by this pragma are subject to control by compiler
2208switches (in particular -gnatp) in the usual manner.
2209
2210@node Pragma Check_Policy,Pragma Comment,Pragma Check_Name,Implementation Defined Pragmas
2211@anchor{gnat_rm/implementation_defined_pragmas pragma-check-policy}@anchor{37}
2212@section Pragma Check_Policy
2213
2214
2215@geindex Controlling assertions
2216
2217@geindex Assertions
2218@geindex control
2219
2220@geindex Check pragma control
2221
2222@geindex Named assertions
2223
2224Syntax:
2225
2226@example
2227pragma Check_Policy
2228 ([Name   =>] CHECK_KIND,
2229  [Policy =>] POLICY_IDENTIFIER);
2230
2231pragma Check_Policy (
2232    CHECK_KIND => POLICY_IDENTIFIER
2233 @{, CHECK_KIND => POLICY_IDENTIFIER@});
2234
2235ASSERTION_KIND ::= RM_ASSERTION_KIND | ID_ASSERTION_KIND
2236
2237CHECK_KIND ::= IDENTIFIER           |
2238               Pre'Class            |
2239               Post'Class           |
2240               Type_Invariant'Class |
2241               Invariant'Class
2242
2243The identifiers Name and Policy are not allowed as CHECK_KIND values. This
2244avoids confusion between the two possible syntax forms for this pragma.
2245
2246POLICY_IDENTIFIER ::= ON | OFF | CHECK | DISABLE | IGNORE
2247@end example
2248
2249This pragma is used to set the checking policy for assertions (specified
2250by aspects or pragmas), the @code{Debug} pragma, or additional checks
2251to be checked using the @code{Check} pragma. It may appear either as
2252a configuration pragma, or within a declarative part of package. In the
2253latter case, it applies from the point where it appears to the end of
2254the declarative region (like pragma @code{Suppress}).
2255
2256The @code{Check_Policy} pragma is similar to the
2257predefined @code{Assertion_Policy} pragma,
2258and if the check kind corresponds to one of the assertion kinds that
2259are allowed by @code{Assertion_Policy}, then the effect is identical.
2260
2261If the first argument is Debug, then the policy applies to Debug pragmas,
2262disabling their effect if the policy is @code{OFF}, @code{DISABLE}, or
2263@code{IGNORE}, and allowing them to execute with normal semantics if
2264the policy is @code{ON} or @code{CHECK}. In addition if the policy is
2265@code{DISABLE}, then the procedure call in @code{Debug} pragmas will
2266be totally ignored and not analyzed semantically.
2267
2268Finally the first argument may be some other identifier than the above
2269possibilities, in which case it controls a set of named assertions
2270that can be checked using pragma @code{Check}. For example, if the pragma:
2271
2272@example
2273pragma Check_Policy (Critical_Error, OFF);
2274@end example
2275
2276is given, then subsequent @code{Check} pragmas whose first argument is also
2277@code{Critical_Error} will be disabled.
2278
2279The check policy is @code{OFF} to turn off corresponding checks, and @code{ON}
2280to turn on corresponding checks. The default for a set of checks for which no
2281@code{Check_Policy} is given is @code{OFF} unless the compiler switch
2282@emph{-gnata} is given, which turns on all checks by default.
2283
2284The check policy settings @code{CHECK} and @code{IGNORE} are recognized
2285as synonyms for @code{ON} and @code{OFF}. These synonyms are provided for
2286compatibility with the standard @code{Assertion_Policy} pragma. The check
2287policy setting @code{DISABLE} causes the second argument of a corresponding
2288@code{Check} pragma to be completely ignored and not analyzed.
2289
2290@node Pragma Comment,Pragma Common_Object,Pragma Check_Policy,Implementation Defined Pragmas
2291@anchor{gnat_rm/implementation_defined_pragmas pragma-comment}@anchor{38}
2292@section Pragma Comment
2293
2294
2295Syntax:
2296
2297@example
2298pragma Comment (static_string_EXPRESSION);
2299@end example
2300
2301This is almost identical in effect to pragma @code{Ident}.  It allows the
2302placement of a comment into the object file and hence into the
2303executable file if the operating system permits such usage.  The
2304difference is that @code{Comment}, unlike @code{Ident}, has
2305no limitations on placement of the pragma (it can be placed
2306anywhere in the main source unit), and if more than one pragma
2307is used, all comments are retained.
2308
2309@node Pragma Common_Object,Pragma Compile_Time_Error,Pragma Comment,Implementation Defined Pragmas
2310@anchor{gnat_rm/implementation_defined_pragmas pragma-common-object}@anchor{39}
2311@section Pragma Common_Object
2312
2313
2314Syntax:
2315
2316@example
2317pragma Common_Object (
2318     [Internal =>] LOCAL_NAME
2319  [, [External =>] EXTERNAL_SYMBOL]
2320  [, [Size     =>] EXTERNAL_SYMBOL] );
2321
2322EXTERNAL_SYMBOL ::=
2323  IDENTIFIER
2324| static_string_EXPRESSION
2325@end example
2326
2327This pragma enables the shared use of variables stored in overlaid
2328linker areas corresponding to the use of @code{COMMON}
2329in Fortran.  The single
2330object @code{LOCAL_NAME} is assigned to the area designated by
2331the @code{External} argument.
2332You may define a record to correspond to a series
2333of fields.  The @code{Size} argument
2334is syntax checked in GNAT, but otherwise ignored.
2335
2336@code{Common_Object} is not supported on all platforms.  If no
2337support is available, then the code generator will issue a message
2338indicating that the necessary attribute for implementation of this
2339pragma is not available.
2340
2341@node Pragma Compile_Time_Error,Pragma Compile_Time_Warning,Pragma Common_Object,Implementation Defined Pragmas
2342@anchor{gnat_rm/implementation_defined_pragmas compile-time-error}@anchor{3a}@anchor{gnat_rm/implementation_defined_pragmas pragma-compile-time-error}@anchor{3b}
2343@section Pragma Compile_Time_Error
2344
2345
2346Syntax:
2347
2348@example
2349pragma Compile_Time_Error
2350         (boolean_EXPRESSION, static_string_EXPRESSION);
2351@end example
2352
2353This pragma can be used to generate additional compile time
2354error messages. It
2355is particularly useful in generics, where errors can be issued for
2356specific problematic instantiations. The first parameter is a boolean
2357expression. The pragma ensures that the value of an expression
2358is known at compile time, and has the value False. The set of expressions
2359whose values are known at compile time includes all static boolean
2360expressions, and also other values which the compiler can determine
2361at compile time (e.g., the size of a record type set by an explicit
2362size representation clause, or the value of a variable which was
2363initialized to a constant and is known not to have been modified).
2364If these conditions are not met, an error message is generated using
2365the value given as the second argument. This string value may contain
2366embedded ASCII.LF characters to break the message into multiple lines.
2367
2368@node Pragma Compile_Time_Warning,Pragma Compiler_Unit,Pragma Compile_Time_Error,Implementation Defined Pragmas
2369@anchor{gnat_rm/implementation_defined_pragmas pragma-compile-time-warning}@anchor{3c}
2370@section Pragma Compile_Time_Warning
2371
2372
2373Syntax:
2374
2375@example
2376pragma Compile_Time_Warning
2377         (boolean_EXPRESSION, static_string_EXPRESSION);
2378@end example
2379
2380Same as pragma Compile_Time_Error, except a warning is issued instead
2381of an error message. If switch @emph{-gnatw_C} is used, a warning is only issued
2382if the value of the expression is known to be True at compile time, not when
2383the value of the expression is not known at compile time.
2384Note that if this pragma is used in a package that
2385is with’ed by a client, the client will get the warning even though it
2386is issued by a with’ed package (normally warnings in with’ed units are
2387suppressed, but this is a special exception to that rule).
2388
2389One typical use is within a generic where compile time known characteristics
2390of formal parameters are tested, and warnings given appropriately. Another use
2391with a first parameter of True is to warn a client about use of a package,
2392for example that it is not fully implemented.
2393
2394In previous versions of the compiler, combining @emph{-gnatwe} with
2395Compile_Time_Warning resulted in a fatal error. Now the compiler always emits
2396a warning. You can use @ref{3a,,Pragma Compile_Time_Error} to force the generation of
2397an error.
2398
2399@node Pragma Compiler_Unit,Pragma Compiler_Unit_Warning,Pragma Compile_Time_Warning,Implementation Defined Pragmas
2400@anchor{gnat_rm/implementation_defined_pragmas pragma-compiler-unit}@anchor{3d}
2401@section Pragma Compiler_Unit
2402
2403
2404Syntax:
2405
2406@example
2407pragma Compiler_Unit;
2408@end example
2409
2410This pragma is obsolete. It is equivalent to Compiler_Unit_Warning. It is
2411retained so that old versions of the GNAT run-time that use this pragma can
2412be compiled with newer versions of the compiler.
2413
2414@node Pragma Compiler_Unit_Warning,Pragma Complete_Representation,Pragma Compiler_Unit,Implementation Defined Pragmas
2415@anchor{gnat_rm/implementation_defined_pragmas pragma-compiler-unit-warning}@anchor{3e}
2416@section Pragma Compiler_Unit_Warning
2417
2418
2419Syntax:
2420
2421@example
2422pragma Compiler_Unit_Warning;
2423@end example
2424
2425This pragma is intended only for internal use in the GNAT run-time library.
2426It indicates that the unit is used as part of the compiler build. The effect
2427is to generate warnings for the use of constructs (for example, conditional
2428expressions) that would cause trouble when bootstrapping using an older
2429version of GNAT. For the exact list of restrictions, see the compiler sources
2430and references to Check_Compiler_Unit.
2431
2432@node Pragma Complete_Representation,Pragma Complex_Representation,Pragma Compiler_Unit_Warning,Implementation Defined Pragmas
2433@anchor{gnat_rm/implementation_defined_pragmas pragma-complete-representation}@anchor{3f}
2434@section Pragma Complete_Representation
2435
2436
2437Syntax:
2438
2439@example
2440pragma Complete_Representation;
2441@end example
2442
2443This pragma must appear immediately within a record representation
2444clause. Typical placements are before the first component clause
2445or after the last component clause. The effect is to give an error
2446message if any component is missing a component clause. This pragma
2447may be used to ensure that a record representation clause is
2448complete, and that this invariant is maintained if fields are
2449added to the record in the future.
2450
2451@node Pragma Complex_Representation,Pragma Component_Alignment,Pragma Complete_Representation,Implementation Defined Pragmas
2452@anchor{gnat_rm/implementation_defined_pragmas pragma-complex-representation}@anchor{40}
2453@section Pragma Complex_Representation
2454
2455
2456Syntax:
2457
2458@example
2459pragma Complex_Representation
2460        ([Entity =>] LOCAL_NAME);
2461@end example
2462
2463The @code{Entity} argument must be the name of a record type which has
2464two fields of the same floating-point type.  The effect of this pragma is
2465to force gcc to use the special internal complex representation form for
2466this record, which may be more efficient.  Note that this may result in
2467the code for this type not conforming to standard ABI (application
2468binary interface) requirements for the handling of record types.  For
2469example, in some environments, there is a requirement for passing
2470records by pointer, and the use of this pragma may result in passing
2471this type in floating-point registers.
2472
2473@node Pragma Component_Alignment,Pragma Constant_After_Elaboration,Pragma Complex_Representation,Implementation Defined Pragmas
2474@anchor{gnat_rm/implementation_defined_pragmas pragma-component-alignment}@anchor{41}
2475@section Pragma Component_Alignment
2476
2477
2478@geindex Alignments of components
2479
2480@geindex Pragma Component_Alignment
2481
2482Syntax:
2483
2484@example
2485pragma Component_Alignment (
2486     [Form =>] ALIGNMENT_CHOICE
2487  [, [Name =>] type_LOCAL_NAME]);
2488
2489ALIGNMENT_CHOICE ::=
2490  Component_Size
2491| Component_Size_4
2492| Storage_Unit
2493| Default
2494@end example
2495
2496Specifies the alignment of components in array or record types.
2497The meaning of the @code{Form} argument is as follows:
2498
2499@quotation
2500
2501@geindex Component_Size (in pragma Component_Alignment)
2502@end quotation
2503
2504
2505@table @asis
2506
2507@item @emph{Component_Size}
2508
2509Aligns scalar components and subcomponents of the array or record type
2510on boundaries appropriate to their inherent size (naturally
2511aligned).  For example, 1-byte components are aligned on byte boundaries,
25122-byte integer components are aligned on 2-byte boundaries, 4-byte
2513integer components are aligned on 4-byte boundaries and so on.  These
2514alignment rules correspond to the normal rules for C compilers on all
2515machines except the VAX.
2516
2517@geindex Component_Size_4 (in pragma Component_Alignment)
2518
2519@item @emph{Component_Size_4}
2520
2521Naturally aligns components with a size of four or fewer
2522bytes.  Components that are larger than 4 bytes are placed on the next
25234-byte boundary.
2524
2525@geindex Storage_Unit (in pragma Component_Alignment)
2526
2527@item @emph{Storage_Unit}
2528
2529Specifies that array or record components are byte aligned, i.e.,
2530aligned on boundaries determined by the value of the constant
2531@code{System.Storage_Unit}.
2532
2533@geindex Default (in pragma Component_Alignment)
2534
2535@item @emph{Default}
2536
2537Specifies that array or record components are aligned on default
2538boundaries, appropriate to the underlying hardware or operating system or
2539both. The @code{Default} choice is the same as @code{Component_Size} (natural
2540alignment).
2541@end table
2542
2543If the @code{Name} parameter is present, @code{type_LOCAL_NAME} must
2544refer to a local record or array type, and the specified alignment
2545choice applies to the specified type.  The use of
2546@code{Component_Alignment} together with a pragma @code{Pack} causes the
2547@code{Component_Alignment} pragma to be ignored.  The use of
2548@code{Component_Alignment} together with a record representation clause
2549is only effective for fields not specified by the representation clause.
2550
2551If the @code{Name} parameter is absent, the pragma can be used as either
2552a configuration pragma, in which case it applies to one or more units in
2553accordance with the normal rules for configuration pragmas, or it can be
2554used within a declarative part, in which case it applies to types that
2555are declared within this declarative part, or within any nested scope
2556within this declarative part.  In either case it specifies the alignment
2557to be applied to any record or array type which has otherwise standard
2558representation.
2559
2560If the alignment for a record or array type is not specified (using
2561pragma @code{Pack}, pragma @code{Component_Alignment}, or a record rep
2562clause), the GNAT uses the default alignment as described previously.
2563
2564@node Pragma Constant_After_Elaboration,Pragma Contract_Cases,Pragma Component_Alignment,Implementation Defined Pragmas
2565@anchor{gnat_rm/implementation_defined_pragmas id6}@anchor{42}@anchor{gnat_rm/implementation_defined_pragmas pragma-constant-after-elaboration}@anchor{43}
2566@section Pragma Constant_After_Elaboration
2567
2568
2569Syntax:
2570
2571@example
2572pragma Constant_After_Elaboration [ (boolean_EXPRESSION) ];
2573@end example
2574
2575For the semantics of this pragma, see the entry for aspect
2576@code{Constant_After_Elaboration} in the SPARK 2014 Reference Manual, section 3.3.1.
2577
2578@node Pragma Contract_Cases,Pragma Convention_Identifier,Pragma Constant_After_Elaboration,Implementation Defined Pragmas
2579@anchor{gnat_rm/implementation_defined_pragmas id7}@anchor{44}@anchor{gnat_rm/implementation_defined_pragmas pragma-contract-cases}@anchor{45}
2580@section Pragma Contract_Cases
2581
2582
2583@geindex Contract cases
2584
2585Syntax:
2586
2587@example
2588pragma Contract_Cases ((CONTRACT_CASE @{, CONTRACT_CASE));
2589
2590CONTRACT_CASE ::= CASE_GUARD => CONSEQUENCE
2591
2592CASE_GUARD ::= boolean_EXPRESSION | others
2593
2594CONSEQUENCE ::= boolean_EXPRESSION
2595@end example
2596
2597The @code{Contract_Cases} pragma allows defining fine-grain specifications
2598that can complement or replace the contract given by a precondition and a
2599postcondition. Additionally, the @code{Contract_Cases} pragma can be used
2600by testing and formal verification tools. The compiler checks its validity and,
2601depending on the assertion policy at the point of declaration of the pragma,
2602it may insert a check in the executable. For code generation, the contract
2603cases
2604
2605@example
2606pragma Contract_Cases (
2607  Cond1 => Pred1,
2608  Cond2 => Pred2);
2609@end example
2610
2611are equivalent to
2612
2613@example
2614C1 : constant Boolean := Cond1;  --  evaluated at subprogram entry
2615C2 : constant Boolean := Cond2;  --  evaluated at subprogram entry
2616pragma Precondition ((C1 and not C2) or (C2 and not C1));
2617pragma Postcondition (if C1 then Pred1);
2618pragma Postcondition (if C2 then Pred2);
2619@end example
2620
2621The precondition ensures that one and only one of the case guards is
2622satisfied on entry to the subprogram.
2623The postcondition ensures that for the case guard that was True on entry,
2624the corresponding consequence is True on exit. Other consequence expressions
2625are not evaluated.
2626
2627A precondition @code{P} and postcondition @code{Q} can also be
2628expressed as contract cases:
2629
2630@example
2631pragma Contract_Cases (P => Q);
2632@end example
2633
2634The placement and visibility rules for @code{Contract_Cases} pragmas are
2635identical to those described for preconditions and postconditions.
2636
2637The compiler checks that boolean expressions given in case guards and
2638consequences are valid, where the rules for case guards are the same as
2639the rule for an expression in @code{Precondition} and the rules for
2640consequences are the same as the rule for an expression in
2641@code{Postcondition}. In particular, attributes @code{'Old} and
2642@code{'Result} can only be used within consequence expressions.
2643The case guard for the last contract case may be @code{others}, to denote
2644any case not captured by the previous cases. The
2645following is an example of use within a package spec:
2646
2647@example
2648package Math_Functions is
2649   ...
2650   function Sqrt (Arg : Float) return Float;
2651   pragma Contract_Cases (((Arg in 0.0 .. 99.0) => Sqrt'Result < 10.0,
2652                           Arg >= 100.0         => Sqrt'Result >= 10.0,
2653                           others               => Sqrt'Result = 0.0));
2654   ...
2655end Math_Functions;
2656@end example
2657
2658The meaning of contract cases is that only one case should apply at each
2659call, as determined by the corresponding case guard evaluating to True,
2660and that the consequence for this case should hold when the subprogram
2661returns.
2662
2663@node Pragma Convention_Identifier,Pragma CPP_Class,Pragma Contract_Cases,Implementation Defined Pragmas
2664@anchor{gnat_rm/implementation_defined_pragmas pragma-convention-identifier}@anchor{46}
2665@section Pragma Convention_Identifier
2666
2667
2668@geindex Conventions
2669@geindex synonyms
2670
2671Syntax:
2672
2673@example
2674pragma Convention_Identifier (
2675         [Name =>]       IDENTIFIER,
2676         [Convention =>] convention_IDENTIFIER);
2677@end example
2678
2679This pragma provides a mechanism for supplying synonyms for existing
2680convention identifiers. The @code{Name} identifier can subsequently
2681be used as a synonym for the given convention in other pragmas (including
2682for example pragma @code{Import} or another @code{Convention_Identifier}
2683pragma). As an example of the use of this, suppose you had legacy code
2684which used Fortran77 as the identifier for Fortran. Then the pragma:
2685
2686@example
2687pragma Convention_Identifier (Fortran77, Fortran);
2688@end example
2689
2690would allow the use of the convention identifier @code{Fortran77} in
2691subsequent code, avoiding the need to modify the sources. As another
2692example, you could use this to parameterize convention requirements
2693according to systems. Suppose you needed to use @code{Stdcall} on
2694windows systems, and @code{C} on some other system, then you could
2695define a convention identifier @code{Library} and use a single
2696@code{Convention_Identifier} pragma to specify which convention
2697would be used system-wide.
2698
2699@node Pragma CPP_Class,Pragma CPP_Constructor,Pragma Convention_Identifier,Implementation Defined Pragmas
2700@anchor{gnat_rm/implementation_defined_pragmas pragma-cpp-class}@anchor{47}
2701@section Pragma CPP_Class
2702
2703
2704@geindex Interfacing with C++
2705
2706Syntax:
2707
2708@example
2709pragma CPP_Class ([Entity =>] LOCAL_NAME);
2710@end example
2711
2712The argument denotes an entity in the current declarative region that is
2713declared as a record type. It indicates that the type corresponds to an
2714externally declared C++ class type, and is to be laid out the same way
2715that C++ would lay out the type. If the C++ class has virtual primitives
2716then the record must be declared as a tagged record type.
2717
2718Types for which @code{CPP_Class} is specified do not have assignment or
2719equality operators defined (such operations can be imported or declared
2720as subprograms as required). Initialization is allowed only by constructor
2721functions (see pragma @code{CPP_Constructor}). Such types are implicitly
2722limited if not explicitly declared as limited or derived from a limited
2723type, and an error is issued in that case.
2724
2725See @ref{48,,Interfacing to C++} for related information.
2726
2727Note: Pragma @code{CPP_Class} is currently obsolete. It is supported
2728for backward compatibility but its functionality is available
2729using pragma @code{Import} with @code{Convention} = @code{CPP}.
2730
2731@node Pragma CPP_Constructor,Pragma CPP_Virtual,Pragma CPP_Class,Implementation Defined Pragmas
2732@anchor{gnat_rm/implementation_defined_pragmas pragma-cpp-constructor}@anchor{49}
2733@section Pragma CPP_Constructor
2734
2735
2736@geindex Interfacing with C++
2737
2738Syntax:
2739
2740@example
2741pragma CPP_Constructor ([Entity =>] LOCAL_NAME
2742  [, [External_Name =>] static_string_EXPRESSION ]
2743  [, [Link_Name     =>] static_string_EXPRESSION ]);
2744@end example
2745
2746This pragma identifies an imported function (imported in the usual way
2747with pragma @code{Import}) as corresponding to a C++ constructor. If
2748@code{External_Name} and @code{Link_Name} are not specified then the
2749@code{Entity} argument is a name that must have been previously mentioned
2750in a pragma @code{Import} with @code{Convention} = @code{CPP}. Such name
2751must be of one of the following forms:
2752
2753
2754@itemize *
2755
2756@item
2757@strong{function} @code{Fname} @strong{return} T`
2758
2759@item
2760@strong{function} @code{Fname} @strong{return} T’Class
2761
2762@item
2763@strong{function} @code{Fname} (…) @strong{return} T`
2764
2765@item
2766@strong{function} @code{Fname} (…) @strong{return} T’Class
2767@end itemize
2768
2769where @code{T} is a limited record type imported from C++ with pragma
2770@code{Import} and @code{Convention} = @code{CPP}.
2771
2772The first two forms import the default constructor, used when an object
2773of type @code{T} is created on the Ada side with no explicit constructor.
2774The latter two forms cover all the non-default constructors of the type.
2775See the GNAT User’s Guide for details.
2776
2777If no constructors are imported, it is impossible to create any objects
2778on the Ada side and the type is implicitly declared abstract.
2779
2780Pragma @code{CPP_Constructor} is intended primarily for automatic generation
2781using an automatic binding generator tool (such as the @code{-fdump-ada-spec}
2782GCC switch).
2783See @ref{48,,Interfacing to C++} for more related information.
2784
2785Note: The use of functions returning class-wide types for constructors is
2786currently obsolete. They are supported for backward compatibility. The
2787use of functions returning the type T leave the Ada sources more clear
2788because the imported C++ constructors always return an object of type T;
2789that is, they never return an object whose type is a descendant of type T.
2790
2791@node Pragma CPP_Virtual,Pragma CPP_Vtable,Pragma CPP_Constructor,Implementation Defined Pragmas
2792@anchor{gnat_rm/implementation_defined_pragmas pragma-cpp-virtual}@anchor{4a}
2793@section Pragma CPP_Virtual
2794
2795
2796@geindex Interfacing to C++
2797
2798This pragma is now obsolete and, other than generating a warning if warnings
2799on obsolescent features are enabled, is completely ignored.
2800It is retained for compatibility
2801purposes. It used to be required to ensure compoatibility with C++, but
2802is no longer required for that purpose because GNAT generates
2803the same object layout as the G++ compiler by default.
2804
2805See @ref{48,,Interfacing to C++} for related information.
2806
2807@node Pragma CPP_Vtable,Pragma CPU,Pragma CPP_Virtual,Implementation Defined Pragmas
2808@anchor{gnat_rm/implementation_defined_pragmas pragma-cpp-vtable}@anchor{4b}
2809@section Pragma CPP_Vtable
2810
2811
2812@geindex Interfacing with C++
2813
2814This pragma is now obsolete and, other than generating a warning if warnings
2815on obsolescent features are enabled, is completely ignored.
2816It used to be required to ensure compatibility with C++, but
2817is no longer required for that purpose because GNAT generates
2818the same object layout as the G++ compiler by default.
2819
2820See @ref{48,,Interfacing to C++} for related information.
2821
2822@node Pragma CPU,Pragma Deadline_Floor,Pragma CPP_Vtable,Implementation Defined Pragmas
2823@anchor{gnat_rm/implementation_defined_pragmas pragma-cpu}@anchor{4c}
2824@section Pragma CPU
2825
2826
2827Syntax:
2828
2829@example
2830pragma CPU (EXPRESSION);
2831@end example
2832
2833This pragma is standard in Ada 2012, but is available in all earlier
2834versions of Ada as an implementation-defined pragma.
2835See Ada 2012 Reference Manual for details.
2836
2837@node Pragma Deadline_Floor,Pragma Default_Initial_Condition,Pragma CPU,Implementation Defined Pragmas
2838@anchor{gnat_rm/implementation_defined_pragmas pragma-deadline-floor}@anchor{4d}
2839@section Pragma Deadline_Floor
2840
2841
2842Syntax:
2843
2844@example
2845pragma Deadline_Floor (time_span_EXPRESSION);
2846@end example
2847
2848This pragma applies only to protected types and specifies the floor
2849deadline inherited by a task when the task enters a protected object.
2850It is effective only when the EDF scheduling policy is used.
2851
2852@node Pragma Default_Initial_Condition,Pragma Debug,Pragma Deadline_Floor,Implementation Defined Pragmas
2853@anchor{gnat_rm/implementation_defined_pragmas id8}@anchor{4e}@anchor{gnat_rm/implementation_defined_pragmas pragma-default-initial-condition}@anchor{4f}
2854@section Pragma Default_Initial_Condition
2855
2856
2857Syntax:
2858
2859@example
2860pragma Default_Initial_Condition [ (null | boolean_EXPRESSION) ];
2861@end example
2862
2863For the semantics of this pragma, see the entry for aspect
2864@code{Default_Initial_Condition} in the SPARK 2014 Reference Manual, section 7.3.3.
2865
2866@node Pragma Debug,Pragma Debug_Policy,Pragma Default_Initial_Condition,Implementation Defined Pragmas
2867@anchor{gnat_rm/implementation_defined_pragmas pragma-debug}@anchor{50}
2868@section Pragma Debug
2869
2870
2871Syntax:
2872
2873@example
2874pragma Debug ([CONDITION, ]PROCEDURE_CALL_WITHOUT_SEMICOLON);
2875
2876PROCEDURE_CALL_WITHOUT_SEMICOLON ::=
2877  PROCEDURE_NAME
2878| PROCEDURE_PREFIX ACTUAL_PARAMETER_PART
2879@end example
2880
2881The procedure call argument has the syntactic form of an expression, meeting
2882the syntactic requirements for pragmas.
2883
2884If debug pragmas are not enabled or if the condition is present and evaluates
2885to False, this pragma has no effect. If debug pragmas are enabled, the
2886semantics of the pragma is exactly equivalent to the procedure call statement
2887corresponding to the argument with a terminating semicolon. Pragmas are
2888permitted in sequences of declarations, so you can use pragma @code{Debug} to
2889intersperse calls to debug procedures in the middle of declarations. Debug
2890pragmas can be enabled either by use of the command line switch @emph{-gnata}
2891or by use of the pragma @code{Check_Policy} with a first argument of
2892@code{Debug}.
2893
2894@node Pragma Debug_Policy,Pragma Default_Scalar_Storage_Order,Pragma Debug,Implementation Defined Pragmas
2895@anchor{gnat_rm/implementation_defined_pragmas pragma-debug-policy}@anchor{51}
2896@section Pragma Debug_Policy
2897
2898
2899Syntax:
2900
2901@example
2902pragma Debug_Policy (CHECK | DISABLE | IGNORE | ON | OFF);
2903@end example
2904
2905This pragma is equivalent to a corresponding @code{Check_Policy} pragma
2906with a first argument of @code{Debug}. It is retained for historical
2907compatibility reasons.
2908
2909@node Pragma Default_Scalar_Storage_Order,Pragma Default_Storage_Pool,Pragma Debug_Policy,Implementation Defined Pragmas
2910@anchor{gnat_rm/implementation_defined_pragmas pragma-default-scalar-storage-order}@anchor{52}
2911@section Pragma Default_Scalar_Storage_Order
2912
2913
2914@geindex Default_Scalar_Storage_Order
2915
2916@geindex Scalar_Storage_Order
2917
2918Syntax:
2919
2920@example
2921pragma Default_Scalar_Storage_Order (High_Order_First | Low_Order_First);
2922@end example
2923
2924Normally if no explicit @code{Scalar_Storage_Order} is given for a record
2925type or array type, then the scalar storage order defaults to the ordinary
2926default for the target. But this default may be overridden using this pragma.
2927The pragma may appear as a configuration pragma, or locally within a package
2928spec or declarative part. In the latter case, it applies to all subsequent
2929types declared within that package spec or declarative part.
2930
2931The following example shows the use of this pragma:
2932
2933@example
2934pragma Default_Scalar_Storage_Order (High_Order_First);
2935with System; use System;
2936package DSSO1 is
2937   type H1 is record
2938      a : Integer;
2939   end record;
2940
2941   type L2 is record
2942      a : Integer;
2943   end record;
2944   for L2'Scalar_Storage_Order use Low_Order_First;
2945
2946   type L2a is new L2;
2947
2948   package Inner is
2949      type H3 is record
2950         a : Integer;
2951      end record;
2952
2953      pragma Default_Scalar_Storage_Order (Low_Order_First);
2954
2955      type L4 is record
2956         a : Integer;
2957      end record;
2958   end Inner;
2959
2960   type H4a is new Inner.L4;
2961
2962   type H5 is record
2963      a : Integer;
2964   end record;
2965end DSSO1;
2966@end example
2967
2968In this example record types with names starting with @emph{L} have @cite{Low_Order_First} scalar
2969storage order, and record types with names starting with @emph{H} have @code{High_Order_First}.
2970Note that in the case of @code{H4a}, the order is not inherited
2971from the parent type. Only an explicitly set @code{Scalar_Storage_Order}
2972gets inherited on type derivation.
2973
2974If this pragma is used as a configuration pragma which appears within a
2975configuration pragma file (as opposed to appearing explicitly at the start
2976of a single unit), then the binder will require that all units in a partition
2977be compiled in a similar manner, other than run-time units, which are not
2978affected by this pragma. Note that the use of this form is discouraged because
2979it may significantly degrade the run-time performance of the software, instead
2980the default scalar storage order ought to be changed only on a local basis.
2981
2982@node Pragma Default_Storage_Pool,Pragma Depends,Pragma Default_Scalar_Storage_Order,Implementation Defined Pragmas
2983@anchor{gnat_rm/implementation_defined_pragmas pragma-default-storage-pool}@anchor{53}
2984@section Pragma Default_Storage_Pool
2985
2986
2987@geindex Default_Storage_Pool
2988
2989Syntax:
2990
2991@example
2992pragma Default_Storage_Pool (storage_pool_NAME | null);
2993@end example
2994
2995This pragma is standard in Ada 2012, but is available in all earlier
2996versions of Ada as an implementation-defined pragma.
2997See Ada 2012 Reference Manual for details.
2998
2999@node Pragma Depends,Pragma Detect_Blocking,Pragma Default_Storage_Pool,Implementation Defined Pragmas
3000@anchor{gnat_rm/implementation_defined_pragmas id9}@anchor{54}@anchor{gnat_rm/implementation_defined_pragmas pragma-depends}@anchor{55}
3001@section Pragma Depends
3002
3003
3004Syntax:
3005
3006@example
3007pragma Depends (DEPENDENCY_RELATION);
3008
3009DEPENDENCY_RELATION ::=
3010     null
3011  | (DEPENDENCY_CLAUSE @{, DEPENDENCY_CLAUSE@})
3012
3013DEPENDENCY_CLAUSE ::=
3014    OUTPUT_LIST =>[+] INPUT_LIST
3015  | NULL_DEPENDENCY_CLAUSE
3016
3017NULL_DEPENDENCY_CLAUSE ::= null => INPUT_LIST
3018
3019OUTPUT_LIST ::= OUTPUT | (OUTPUT @{, OUTPUT@})
3020
3021INPUT_LIST ::= null | INPUT | (INPUT @{, INPUT@})
3022
3023OUTPUT ::= NAME | FUNCTION_RESULT
3024INPUT  ::= NAME
3025
3026where FUNCTION_RESULT is a function Result attribute_reference
3027@end example
3028
3029For the semantics of this pragma, see the entry for aspect @code{Depends} in the
3030SPARK 2014 Reference Manual, section 6.1.5.
3031
3032@node Pragma Detect_Blocking,Pragma Disable_Atomic_Synchronization,Pragma Depends,Implementation Defined Pragmas
3033@anchor{gnat_rm/implementation_defined_pragmas pragma-detect-blocking}@anchor{56}
3034@section Pragma Detect_Blocking
3035
3036
3037Syntax:
3038
3039@example
3040pragma Detect_Blocking;
3041@end example
3042
3043This is a standard pragma in Ada 2005, that is available in all earlier
3044versions of Ada as an implementation-defined pragma.
3045
3046This is a configuration pragma that forces the detection of potentially
3047blocking operations within a protected operation, and to raise Program_Error
3048if that happens.
3049
3050@node Pragma Disable_Atomic_Synchronization,Pragma Dispatching_Domain,Pragma Detect_Blocking,Implementation Defined Pragmas
3051@anchor{gnat_rm/implementation_defined_pragmas pragma-disable-atomic-synchronization}@anchor{57}
3052@section Pragma Disable_Atomic_Synchronization
3053
3054
3055@geindex Atomic Synchronization
3056
3057Syntax:
3058
3059@example
3060pragma Disable_Atomic_Synchronization [(Entity)];
3061@end example
3062
3063Ada requires that accesses (reads or writes) of an atomic variable be
3064regarded as synchronization points in the case of multiple tasks.
3065Particularly in the case of multi-processors this may require special
3066handling, e.g. the generation of memory barriers. This capability may
3067be turned off using this pragma in cases where it is known not to be
3068required.
3069
3070The placement and scope rules for this pragma are the same as those
3071for @code{pragma Suppress}. In particular it can be used as a
3072configuration  pragma, or in a declaration sequence where it applies
3073till the end of the scope. If an @code{Entity} argument is present,
3074the action applies only to that entity.
3075
3076@node Pragma Dispatching_Domain,Pragma Effective_Reads,Pragma Disable_Atomic_Synchronization,Implementation Defined Pragmas
3077@anchor{gnat_rm/implementation_defined_pragmas pragma-dispatching-domain}@anchor{58}
3078@section Pragma Dispatching_Domain
3079
3080
3081Syntax:
3082
3083@example
3084pragma Dispatching_Domain (EXPRESSION);
3085@end example
3086
3087This pragma is standard in Ada 2012, but is available in all earlier
3088versions of Ada as an implementation-defined pragma.
3089See Ada 2012 Reference Manual for details.
3090
3091@node Pragma Effective_Reads,Pragma Effective_Writes,Pragma Dispatching_Domain,Implementation Defined Pragmas
3092@anchor{gnat_rm/implementation_defined_pragmas id10}@anchor{59}@anchor{gnat_rm/implementation_defined_pragmas pragma-effective-reads}@anchor{5a}
3093@section Pragma Effective_Reads
3094
3095
3096Syntax:
3097
3098@example
3099pragma Effective_Reads [ (boolean_EXPRESSION) ];
3100@end example
3101
3102For the semantics of this pragma, see the entry for aspect @code{Effective_Reads} in
3103the SPARK 2014 Reference Manual, section 7.1.2.
3104
3105@node Pragma Effective_Writes,Pragma Elaboration_Checks,Pragma Effective_Reads,Implementation Defined Pragmas
3106@anchor{gnat_rm/implementation_defined_pragmas id11}@anchor{5b}@anchor{gnat_rm/implementation_defined_pragmas pragma-effective-writes}@anchor{5c}
3107@section Pragma Effective_Writes
3108
3109
3110Syntax:
3111
3112@example
3113pragma Effective_Writes [ (boolean_EXPRESSION) ];
3114@end example
3115
3116For the semantics of this pragma, see the entry for aspect @code{Effective_Writes}
3117in the SPARK 2014 Reference Manual, section 7.1.2.
3118
3119@node Pragma Elaboration_Checks,Pragma Eliminate,Pragma Effective_Writes,Implementation Defined Pragmas
3120@anchor{gnat_rm/implementation_defined_pragmas pragma-elaboration-checks}@anchor{5d}
3121@section Pragma Elaboration_Checks
3122
3123
3124@geindex Elaboration control
3125
3126Syntax:
3127
3128@example
3129pragma Elaboration_Checks (Dynamic | Static);
3130@end example
3131
3132This is a configuration pragma which specifies the elaboration model to be
3133used during compilation. For more information on the elaboration models of
3134GNAT, consult the chapter on elaboration order handling in the @emph{GNAT User’s
3135Guide}.
3136
3137The pragma may appear in the following contexts:
3138
3139
3140@itemize *
3141
3142@item
3143Configuration pragmas file
3144
3145@item
3146Prior to the context clauses of a compilation unit’s initial declaration
3147@end itemize
3148
3149Any other placement of the pragma will result in a warning and the effects of
3150the offending pragma will be ignored.
3151
3152If the pragma argument is @code{Dynamic}, then the dynamic elaboration model is in
3153effect. If the pragma argument is @code{Static}, then the static elaboration model
3154is in effect.
3155
3156@node Pragma Eliminate,Pragma Enable_Atomic_Synchronization,Pragma Elaboration_Checks,Implementation Defined Pragmas
3157@anchor{gnat_rm/implementation_defined_pragmas pragma-eliminate}@anchor{5e}
3158@section Pragma Eliminate
3159
3160
3161@geindex Elimination of unused subprograms
3162
3163Syntax:
3164
3165@example
3166pragma Eliminate (
3167            [  Unit_Name       => ] IDENTIFIER | SELECTED_COMPONENT ,
3168            [  Entity          => ] IDENTIFIER |
3169                                    SELECTED_COMPONENT |
3170                                    STRING_LITERAL
3171            [, Source_Location =>   SOURCE_TRACE ] );
3172
3173        SOURCE_TRACE    ::= STRING_LITERAL
3174@end example
3175
3176This pragma indicates that the given entity is not used in the program to be
3177compiled and built, thus allowing the compiler to
3178eliminate the code or data associated with the named entity. Any reference to
3179an eliminated entity causes a compile-time or link-time error.
3180
3181The pragma has the following semantics, where @code{U} is the unit specified by
3182the @code{Unit_Name} argument and @code{E} is the entity specified by the @code{Entity}
3183argument:
3184
3185
3186@itemize *
3187
3188@item
3189@code{E} must be a subprogram that is explicitly declared either:
3190
3191o  Within @code{U}, or
3192
3193o  Within a generic package that is instantiated in @code{U}, or
3194
3195o  As an instance of generic subprogram instantiated in @code{U}.
3196
3197Otherwise the pragma is ignored.
3198
3199@item
3200If @code{E} is overloaded within @code{U} then, in the absence of a
3201@code{Source_Location} argument, all overloadings are eliminated.
3202
3203@item
3204If @code{E} is overloaded within @code{U} and only some overloadings
3205are to be eliminated, then each overloading to be eliminated
3206must be specified in a corresponding pragma @code{Eliminate}
3207with a @code{Source_Location} argument identifying the line where the
3208declaration appears, as described below.
3209
3210@item
3211If @code{E} is declared as the result of a generic instantiation, then
3212a @code{Source_Location} argument is needed, as described below
3213@end itemize
3214
3215Pragma @code{Eliminate} allows a program to be compiled in a system-independent
3216manner, so that unused entities are eliminated but without
3217needing to modify the source text. Normally the required set of
3218@code{Eliminate} pragmas is constructed automatically using the @code{gnatelim} tool.
3219
3220Any source file change that removes, splits, or
3221adds lines may make the set of @code{Eliminate} pragmas invalid because their
3222@code{Source_Location} argument values may get out of date.
3223
3224Pragma @code{Eliminate} may be used where the referenced entity is a dispatching
3225operation. In this case all the subprograms to which the given operation can
3226dispatch are considered to be unused (are never called as a result of a direct
3227or a dispatching call).
3228
3229The string literal given for the source location specifies the line number
3230of the declaration of the entity, using the following syntax for @code{SOURCE_TRACE}:
3231
3232@example
3233SOURCE_TRACE     ::= SOURCE_REFERENCE [ LBRACKET SOURCE_TRACE RBRACKET ]
3234
3235LBRACKET         ::= '['
3236RBRACKET         ::= ']'
3237
3238SOURCE_REFERENCE ::= FILE_NAME : LINE_NUMBER
3239
3240LINE_NUMBER      ::= DIGIT @{DIGIT@}
3241@end example
3242
3243Spaces around the colon in a @code{SOURCE_REFERENCE} are optional.
3244
3245The source trace that is given as the @code{Source_Location} must obey the
3246following rules (or else the pragma is ignored), where @code{U} is
3247the unit @code{U} specified by the @code{Unit_Name} argument and @code{E} is the
3248subprogram specified by the @code{Entity} argument:
3249
3250
3251@itemize *
3252
3253@item
3254@code{FILE_NAME} is the short name (with no directory
3255information) of the Ada source file for @code{U}, using the required syntax
3256for the underlying file system (e.g. case is significant if the underlying
3257operating system is case sensitive).
3258If @code{U} is a package and @code{E} is a subprogram declared in the package
3259specification and its full declaration appears in the package body,
3260then the  relevant source file is the one for the package specification;
3261analogously if @code{U} is a generic package.
3262
3263@item
3264If @code{E} is not declared in a generic instantiation (this includes
3265generic subprogram instances), the source trace includes only one source
3266line reference. @code{LINE_NUMBER} gives the line number of the occurrence
3267of the declaration of @code{E} within the source file (as a decimal literal
3268without an exponent or point).
3269
3270@item
3271If @code{E} is declared by a generic instantiation, its source trace
3272(from left to right) starts with the source location of the
3273declaration of @code{E} in the generic unit and ends with the source
3274location of the instantiation, given in square brackets. This approach is
3275applied recursively with nested instantiations: the rightmost (nested
3276most deeply in square brackets) element of the source trace is the location
3277of the outermost instantiation, and the leftmost element (that is, outside
3278of any square brackets) is the location of the declaration of @code{E} in
3279the generic unit.
3280@end itemize
3281
3282Examples:
3283
3284@quotation
3285
3286@example
3287pragma Eliminate (Pkg0, Proc);
3288-- Eliminate (all overloadings of) Proc in Pkg0
3289
3290pragma Eliminate (Pkg1, Proc,
3291                  Source_Location => "pkg1.ads:8");
3292-- Eliminate overloading of Proc at line 8 in pkg1.ads
3293
3294-- Assume the following file contents:
3295--   gen_pkg.ads
3296--   1: generic
3297--   2:   type T is private;
3298--   3: package Gen_Pkg is
3299--   4:   procedure Proc(N : T);
3300--  ...   ...
3301--  ... end Gen_Pkg;
3302--
3303--    q.adb
3304--   1: with Gen_Pkg;
3305--   2: procedure Q is
3306--   3:   package Inst_Pkg is new Gen_Pkg(Integer);
3307--  ...   -- No calls on Inst_Pkg.Proc
3308--  ... end Q;
3309
3310-- The following pragma eliminates Inst_Pkg.Proc from Q
3311pragma Eliminate (Q, Proc,
3312                  Source_Location => "gen_pkg.ads:4[q.adb:3]");
3313@end example
3314@end quotation
3315
3316@node Pragma Enable_Atomic_Synchronization,Pragma Export_Function,Pragma Eliminate,Implementation Defined Pragmas
3317@anchor{gnat_rm/implementation_defined_pragmas pragma-enable-atomic-synchronization}@anchor{5f}
3318@section Pragma Enable_Atomic_Synchronization
3319
3320
3321@geindex Atomic Synchronization
3322
3323Syntax:
3324
3325@example
3326pragma Enable_Atomic_Synchronization [(Entity)];
3327@end example
3328
3329Ada requires that accesses (reads or writes) of an atomic variable be
3330regarded as synchronization points in the case of multiple tasks.
3331Particularly in the case of multi-processors this may require special
3332handling, e.g. the generation of memory barriers. This synchronization
3333is performed by default, but can be turned off using
3334@code{pragma Disable_Atomic_Synchronization}. The
3335@code{Enable_Atomic_Synchronization} pragma can be used to turn
3336it back on.
3337
3338The placement and scope rules for this pragma are the same as those
3339for @code{pragma Unsuppress}. In particular it can be used as a
3340configuration  pragma, or in a declaration sequence where it applies
3341till the end of the scope. If an @code{Entity} argument is present,
3342the action applies only to that entity.
3343
3344@node Pragma Export_Function,Pragma Export_Object,Pragma Enable_Atomic_Synchronization,Implementation Defined Pragmas
3345@anchor{gnat_rm/implementation_defined_pragmas pragma-export-function}@anchor{60}
3346@section Pragma Export_Function
3347
3348
3349@geindex Argument passing mechanisms
3350
3351Syntax:
3352
3353@example
3354pragma Export_Function (
3355     [Internal         =>] LOCAL_NAME
3356  [, [External         =>] EXTERNAL_SYMBOL]
3357  [, [Parameter_Types  =>] PARAMETER_TYPES]
3358  [, [Result_Type      =>] result_SUBTYPE_MARK]
3359  [, [Mechanism        =>] MECHANISM]
3360  [, [Result_Mechanism =>] MECHANISM_NAME]);
3361
3362EXTERNAL_SYMBOL ::=
3363  IDENTIFIER
3364| static_string_EXPRESSION
3365| ""
3366
3367PARAMETER_TYPES ::=
3368  null
3369| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@}
3370
3371TYPE_DESIGNATOR ::=
3372  subtype_NAME
3373| subtype_Name ' Access
3374
3375MECHANISM ::=
3376  MECHANISM_NAME
3377| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@})
3378
3379MECHANISM_ASSOCIATION ::=
3380  [formal_parameter_NAME =>] MECHANISM_NAME
3381
3382MECHANISM_NAME ::= Value | Reference
3383@end example
3384
3385Use this pragma to make a function externally callable and optionally
3386provide information on mechanisms to be used for passing parameter and
3387result values.  We recommend, for the purposes of improving portability,
3388this pragma always be used in conjunction with a separate pragma
3389@code{Export}, which must precede the pragma @code{Export_Function}.
3390GNAT does not require a separate pragma @code{Export}, but if none is
3391present, @code{Convention Ada} is assumed, which is usually
3392not what is wanted, so it is usually appropriate to use this
3393pragma in conjunction with a @code{Export} or @code{Convention}
3394pragma that specifies the desired foreign convention.
3395Pragma @code{Export_Function}
3396(and @code{Export}, if present) must appear in the same declarative
3397region as the function to which they apply.
3398
3399The @code{internal_name} must uniquely designate the function to which the
3400pragma applies.  If more than one function name exists of this name in
3401the declarative part you must use the @code{Parameter_Types} and
3402@code{Result_Type} parameters to achieve the required
3403unique designation.  The @cite{subtype_mark}s in these parameters must
3404exactly match the subtypes in the corresponding function specification,
3405using positional notation to match parameters with subtype marks.
3406The form with an @code{'Access} attribute can be used to match an
3407anonymous access parameter.
3408
3409@geindex Suppressing external name
3410
3411Special treatment is given if the EXTERNAL is an explicit null
3412string or a static string expressions that evaluates to the null
3413string. In this case, no external name is generated. This form
3414still allows the specification of parameter mechanisms.
3415
3416@node Pragma Export_Object,Pragma Export_Procedure,Pragma Export_Function,Implementation Defined Pragmas
3417@anchor{gnat_rm/implementation_defined_pragmas pragma-export-object}@anchor{61}
3418@section Pragma Export_Object
3419
3420
3421Syntax:
3422
3423@example
3424pragma Export_Object
3425      [Internal =>] LOCAL_NAME
3426   [, [External =>] EXTERNAL_SYMBOL]
3427   [, [Size     =>] EXTERNAL_SYMBOL]
3428
3429EXTERNAL_SYMBOL ::=
3430  IDENTIFIER
3431| static_string_EXPRESSION
3432@end example
3433
3434This pragma designates an object as exported, and apart from the
3435extended rules for external symbols, is identical in effect to the use of
3436the normal @code{Export} pragma applied to an object.  You may use a
3437separate Export pragma (and you probably should from the point of view
3438of portability), but it is not required.  @code{Size} is syntax checked,
3439but otherwise ignored by GNAT.
3440
3441@node Pragma Export_Procedure,Pragma Export_Valued_Procedure,Pragma Export_Object,Implementation Defined Pragmas
3442@anchor{gnat_rm/implementation_defined_pragmas pragma-export-procedure}@anchor{62}
3443@section Pragma Export_Procedure
3444
3445
3446Syntax:
3447
3448@example
3449pragma Export_Procedure (
3450     [Internal        =>] LOCAL_NAME
3451  [, [External        =>] EXTERNAL_SYMBOL]
3452  [, [Parameter_Types =>] PARAMETER_TYPES]
3453  [, [Mechanism       =>] MECHANISM]);
3454
3455EXTERNAL_SYMBOL ::=
3456  IDENTIFIER
3457| static_string_EXPRESSION
3458| ""
3459
3460PARAMETER_TYPES ::=
3461  null
3462| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@}
3463
3464TYPE_DESIGNATOR ::=
3465  subtype_NAME
3466| subtype_Name ' Access
3467
3468MECHANISM ::=
3469  MECHANISM_NAME
3470| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@})
3471
3472MECHANISM_ASSOCIATION ::=
3473  [formal_parameter_NAME =>] MECHANISM_NAME
3474
3475MECHANISM_NAME ::= Value | Reference
3476@end example
3477
3478This pragma is identical to @code{Export_Function} except that it
3479applies to a procedure rather than a function and the parameters
3480@code{Result_Type} and @code{Result_Mechanism} are not permitted.
3481GNAT does not require a separate pragma @code{Export}, but if none is
3482present, @code{Convention Ada} is assumed, which is usually
3483not what is wanted, so it is usually appropriate to use this
3484pragma in conjunction with a @code{Export} or @code{Convention}
3485pragma that specifies the desired foreign convention.
3486
3487@geindex Suppressing external name
3488
3489Special treatment is given if the EXTERNAL is an explicit null
3490string or a static string expressions that evaluates to the null
3491string. In this case, no external name is generated. This form
3492still allows the specification of parameter mechanisms.
3493
3494@node Pragma Export_Valued_Procedure,Pragma Extend_System,Pragma Export_Procedure,Implementation Defined Pragmas
3495@anchor{gnat_rm/implementation_defined_pragmas pragma-export-valued-procedure}@anchor{63}
3496@section Pragma Export_Valued_Procedure
3497
3498
3499Syntax:
3500
3501@example
3502pragma Export_Valued_Procedure (
3503     [Internal        =>] LOCAL_NAME
3504  [, [External        =>] EXTERNAL_SYMBOL]
3505  [, [Parameter_Types =>] PARAMETER_TYPES]
3506  [, [Mechanism       =>] MECHANISM]);
3507
3508EXTERNAL_SYMBOL ::=
3509  IDENTIFIER
3510| static_string_EXPRESSION
3511| ""
3512
3513PARAMETER_TYPES ::=
3514  null
3515| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@}
3516
3517TYPE_DESIGNATOR ::=
3518  subtype_NAME
3519| subtype_Name ' Access
3520
3521MECHANISM ::=
3522  MECHANISM_NAME
3523| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@})
3524
3525MECHANISM_ASSOCIATION ::=
3526  [formal_parameter_NAME =>] MECHANISM_NAME
3527
3528MECHANISM_NAME ::= Value | Reference
3529@end example
3530
3531This pragma is identical to @code{Export_Procedure} except that the
3532first parameter of @code{LOCAL_NAME}, which must be present, must be of
3533mode @code{out}, and externally the subprogram is treated as a function
3534with this parameter as the result of the function.  GNAT provides for
3535this capability to allow the use of @code{out} and @code{in out}
3536parameters in interfacing to external functions (which are not permitted
3537in Ada functions).
3538GNAT does not require a separate pragma @code{Export}, but if none is
3539present, @code{Convention Ada} is assumed, which is almost certainly
3540not what is wanted since the whole point of this pragma is to interface
3541with foreign language functions, so it is usually appropriate to use this
3542pragma in conjunction with a @code{Export} or @code{Convention}
3543pragma that specifies the desired foreign convention.
3544
3545@geindex Suppressing external name
3546
3547Special treatment is given if the EXTERNAL is an explicit null
3548string or a static string expressions that evaluates to the null
3549string. In this case, no external name is generated. This form
3550still allows the specification of parameter mechanisms.
3551
3552@node Pragma Extend_System,Pragma Extensions_Allowed,Pragma Export_Valued_Procedure,Implementation Defined Pragmas
3553@anchor{gnat_rm/implementation_defined_pragmas pragma-extend-system}@anchor{64}
3554@section Pragma Extend_System
3555
3556
3557@geindex System
3558@geindex extending
3559
3560@geindex DEC Ada 83
3561
3562Syntax:
3563
3564@example
3565pragma Extend_System ([Name =>] IDENTIFIER);
3566@end example
3567
3568This pragma is used to provide backwards compatibility with other
3569implementations that extend the facilities of package @code{System}.  In
3570GNAT, @code{System} contains only the definitions that are present in
3571the Ada RM.  However, other implementations, notably the DEC Ada 83
3572implementation, provide many extensions to package @code{System}.
3573
3574For each such implementation accommodated by this pragma, GNAT provides a
3575package @code{Aux_@emph{xxx}}, e.g., @code{Aux_DEC} for the DEC Ada 83
3576implementation, which provides the required additional definitions.  You
3577can use this package in two ways.  You can @code{with} it in the normal
3578way and access entities either by selection or using a @code{use}
3579clause.  In this case no special processing is required.
3580
3581However, if existing code contains references such as
3582@code{System.@emph{xxx}} where @emph{xxx} is an entity in the extended
3583definitions provided in package @code{System}, you may use this pragma
3584to extend visibility in @code{System} in a non-standard way that
3585provides greater compatibility with the existing code.  Pragma
3586@code{Extend_System} is a configuration pragma whose single argument is
3587the name of the package containing the extended definition
3588(e.g., @code{Aux_DEC} for the DEC Ada case).  A unit compiled under
3589control of this pragma will be processed using special visibility
3590processing that looks in package @code{System.Aux_@emph{xxx}} where
3591@code{Aux_@emph{xxx}} is the pragma argument for any entity referenced in
3592package @code{System}, but not found in package @code{System}.
3593
3594You can use this pragma either to access a predefined @code{System}
3595extension supplied with the compiler, for example @code{Aux_DEC} or
3596you can construct your own extension unit following the above
3597definition.  Note that such a package is a child of @code{System}
3598and thus is considered part of the implementation.
3599To compile it you will have to use the @emph{-gnatg} switch
3600for compiling System units, as explained in the
3601GNAT User’s Guide.
3602
3603@node Pragma Extensions_Allowed,Pragma Extensions_Visible,Pragma Extend_System,Implementation Defined Pragmas
3604@anchor{gnat_rm/implementation_defined_pragmas pragma-extensions-allowed}@anchor{65}
3605@section Pragma Extensions_Allowed
3606
3607
3608@geindex Ada Extensions
3609
3610@geindex GNAT Extensions
3611
3612Syntax:
3613
3614@example
3615pragma Extensions_Allowed (On | Off);
3616@end example
3617
3618This configuration pragma enables or disables the implementation
3619extension mode (the use of Off as a parameter cancels the effect
3620of the @emph{-gnatX} command switch).
3621
3622In extension mode, the latest version of the Ada language is
3623implemented (currently Ada 2022), and in addition a number
3624of GNAT specific extensions are recognized as follows:
3625
3626
3627@itemize *
3628
3629@item
3630Constrained attribute for generic objects
3631
3632The @code{Constrained} attribute is permitted for objects of
3633generic types. The result indicates if the corresponding actual
3634is constrained.
3635
3636@item
3637@code{Static} aspect on intrinsic functions
3638
3639The Ada 202x @code{Static} aspect can be specified on Intrinsic imported
3640functions and the compiler will evaluate some of these intrinsic statically,
3641in particular the @code{Shift_Left} and @code{Shift_Right} intrinsics.
3642
3643@item
3644@code{'Reduce} attribute
3645
3646This attribute part of the Ada 202x language definition is provided for
3647now under -gnatX to confirm and potentially refine its usage and syntax.
3648
3649@item
3650@code{[]} aggregates
3651
3652This new aggregate syntax for arrays and containers is provided under -gnatX
3653to experiment and confirm this new language syntax.
3654
3655@item
3656Additional @code{when} constructs
3657
3658In addition to the @code{exit when CONDITION} control structure, several
3659additional constructs are allowed following this format. Including
3660@code{return when CONDITION}, @code{goto when CONDITION}, and
3661@code{raise [with EXCEPTION_MESSAGE] when CONDITION.}
3662
3663Some examples:
3664
3665@example
3666return Result when Variable > 10;
3667
3668raise Program_Error with "Element is null" when Element = null;
3669
3670goto End_Of_Subprogram when Variable = -1;
3671@end example
3672
3673@item
3674Casing on composite values (aka pattern matching)
3675
3676The selector for a case statement may be of a composite type, subject to
3677some restrictions (described below). Aggregate syntax is used for choices
3678of such a case statement; however, in cases where a “normal” aggregate would
3679require a discrete value, a discrete subtype may be used instead; box
3680notation can also be used to match all values.
3681
3682Consider this example:
3683
3684@example
3685type Rec is record
3686   F1, F2 : Integer;
3687end record;
3688
3689procedure Caser_1 (X : Rec) is
3690begin
3691   case X is
3692      when (F1 => Positive, F2 => Positive) =>
3693         Do_This;
3694      when (F1 => Natural, F2 => <>) | (F1 => <>, F2 => Natural) =>
3695         Do_That;
3696      when others =>
3697          Do_The_Other_Thing;
3698   end case;
3699end Caser_1;
3700@end example
3701
3702If Caser_1 is called and both components of X are positive, then
3703Do_This will be called; otherwise, if either component is nonnegative
3704then Do_That will be called; otherwise, Do_The_Other_Thing will be called.
3705
3706If the set of values that match the choice(s) of an earlier alternative
3707overlaps the corresponding set of a later alternative, then the first
3708set shall be a proper subset of the second (and the later alternative
3709will not be executed if the earlier alternative “matches”). All possible
3710values of the composite type shall be covered. The composite type of the
3711selector shall be an array or record type that is neither limited
3712class-wide.
3713
3714If a subcomponent’s subtype does not meet certain restrictions, then
3715the only value that can be specified for that subcomponent in a case
3716choice expression is a “box” component association (which matches all
3717possible values for the subcomponent). This restriction applies if
3718
3719
3720@itemize -
3721
3722@item
3723the component subtype is not a record, array, or discrete type; or
3724
3725@item
3726the component subtype is subject to a non-static constraint or
3727has a predicate; or
3728
3729@item
3730the component type is an enumeration type that is subject to an
3731enumeration representation clause; or
3732
3733@item
3734the component type is a multidimensional array type or an
3735array type with a nonstatic index subtype.
3736@end itemize
3737
3738Support for casing on arrays (and on records that contain arrays) is
3739currently subject to some restrictions. Non-positional
3740array aggregates are not supported as (or within) case choices. Likewise
3741for array type and subtype names. The current implementation exceeds
3742compile-time capacity limits in some annoyingly common scenarios; the
3743message generated in such cases is usually “Capacity exceeded in compiling
3744case statement with composite selector type”.
3745
3746In addition, pattern bindings are supported. This is a mechanism
3747for binding a name to a component of a matching value for use within
3748an alternative of a case statement. For a component association
3749that occurs within a case choice, the expression may be followed by
3750“is <identifier>”. In the special case of a “box” component association,
3751the identifier may instead be provided within the box. Either of these
3752indicates that the given identifer denotes (a constant view of) the matching
3753subcomponent of the case selector. Binding is not yet supported for arrays
3754or subcomponents thereof.
3755
3756Consider this example (which uses type Rec from the previous example):
3757
3758@example
3759procedure Caser_2 (X : Rec) is
3760begin
3761   case X is
3762      when (F1 => Positive is Abc, F2 => Positive) =>
3763         Do_This (Abc)
3764      when (F1 => Natural is N1, F2 => <N2>) |
3765           (F1 => <N2>, F2 => Natural is N1) =>
3766         Do_That (Param_1 => N1, Param_2 => N2);
3767      when others =>
3768         Do_The_Other_Thing;
3769   end case;
3770end Caser_2;
3771@end example
3772
3773This example is the same as the previous one with respect to
3774determining whether Do_This, Do_That, or Do_The_Other_Thing will
3775be called. But for this version, Do_This takes a parameter and Do_That
3776takes two parameters. If Do_This is called, the actual parameter in the
3777call will be X.F1.
3778
3779If Do_That is called, the situation is more complex because there are two
3780choices for that alternative. If Do_That is called because the first choice
3781matched (i.e., because X.F1 is nonnegative and either X.F1 or X.F2 is zero
3782or negative), then the actual parameters of the call will be (in order)
3783X.F1 and X.F2. If Do_That is called because the second choice matched (and
3784the first one did not), then the actual parameters will be reversed.
3785
3786Within the choice list for single alternative, each choice must
3787define the same set of bindings and the component subtypes for
3788for a given identifer must all statically match. Currently, the case
3789of a binding for a nondiscrete component is not implemented.
3790
3791@item
3792Fixed lower bounds for array types and subtypes
3793
3794Unconstrained array types and subtypes can be specified with a lower bound
3795that is fixed to a certain value, by writing an index range that uses the
3796syntax “<lower-bound-expression> .. <>”. This guarantees that all objects
3797of the type or subtype will have the specified lower bound.
3798
3799For example, a matrix type with fixed lower bounds of zero for each
3800dimension can be declared by the following:
3801
3802@example
3803type Matrix is
3804  array (Natural range 0 .. <>, Natural range 0 .. <>) of Integer;
3805@end example
3806
3807Objects of type Matrix declared with an index constraint must have index
3808ranges starting at zero:
3809
3810@example
3811M1 : Matrix (0 .. 9, 0 .. 19);
3812M2 : Matrix (2 .. 11, 3 .. 22);  -- Warning about bounds; will raise CE
3813@end example
3814
3815Similarly, a subtype of String can be declared that specifies the lower
3816bound of objects of that subtype to be 1:
3817
3818@quotation
3819
3820@example
3821subtype String_1 is String (1 .. <>);
3822@end example
3823@end quotation
3824
3825If a string slice is passed to a formal of subtype String_1 in a call to
3826a subprogram S, the slice’s bounds will “slide” so that the lower bound
3827is 1. Within S, the lower bound of the formal is known to be 1, so, unlike
3828a normal unconstrained String formal, there is no need to worry about
3829accounting for other possible lower-bound values. Sliding of bounds also
3830occurs in other contexts, such as for object declarations with an
3831unconstrained subtype with fixed lower bound, as well as in subtype
3832conversions.
3833
3834Use of this feature increases safety by simplifying code, and can also
3835improve the efficiency of indexing operations, since the compiler statically
3836knows the lower bound of unconstrained array formals when the formal’s
3837subtype has index ranges with static fixed lower bounds.
3838
3839@item
3840Prefixed-view notation for calls to primitive subprograms of untagged types
3841
3842Since Ada 2005, calls to primitive subprograms of a tagged type that
3843have a “prefixed view” (see RM 4.1.3(9.2)) have been allowed to be
3844written using the form of a selected_component, with the first actual
3845parameter given as the prefix and the name of the subprogram as a
3846selector. This prefixed-view notation for calls is extended so as to
3847also allow such syntax for calls to primitive subprograms of untagged
3848types. The primitives of an untagged type T that have a prefixed view
3849are those where the first formal parameter of the subprogram either
3850is of type T or is an anonymous access parameter whose designated type
3851is T. For a type that has a component that happens to have the same
3852simple name as one of the type’s primitive subprograms, where the
3853component is visible at the point of a selected_component using that
3854name, preference is given to the component in a selected_component
3855(as is currently the case for tagged types with such component names).
3856
3857@item
3858Expression defaults for generic formal functions
3859
3860The declaration of a generic formal function is allowed to specify
3861an expression as a default, using the syntax of an expression function.
3862
3863Here is an example of this feature:
3864
3865@example
3866generic
3867   type T is private;
3868   with function Copy (Item : T) return T is (Item); -- Defaults to Item
3869package Stacks is
3870
3871   type Stack is limited private;
3872
3873   procedure Push (S : in out Stack; X : T); -- Calls Copy on X
3874
3875   function Pop (S : in out Stack) return T; -- Calls Copy to return item
3876
3877private
3878   -- ...
3879end Stacks;
3880@end example
3881@end itemize
3882
3883@node Pragma Extensions_Visible,Pragma External,Pragma Extensions_Allowed,Implementation Defined Pragmas
3884@anchor{gnat_rm/implementation_defined_pragmas id12}@anchor{66}@anchor{gnat_rm/implementation_defined_pragmas pragma-extensions-visible}@anchor{67}
3885@section Pragma Extensions_Visible
3886
3887
3888Syntax:
3889
3890@example
3891pragma Extensions_Visible [ (boolean_EXPRESSION) ];
3892@end example
3893
3894For the semantics of this pragma, see the entry for aspect @code{Extensions_Visible}
3895in the SPARK 2014 Reference Manual, section 6.1.7.
3896
3897@node Pragma External,Pragma External_Name_Casing,Pragma Extensions_Visible,Implementation Defined Pragmas
3898@anchor{gnat_rm/implementation_defined_pragmas pragma-external}@anchor{68}
3899@section Pragma External
3900
3901
3902Syntax:
3903
3904@example
3905pragma External (
3906  [   Convention    =>] convention_IDENTIFIER,
3907  [   Entity        =>] LOCAL_NAME
3908  [, [External_Name =>] static_string_EXPRESSION ]
3909  [, [Link_Name     =>] static_string_EXPRESSION ]);
3910@end example
3911
3912This pragma is identical in syntax and semantics to pragma
3913@code{Export} as defined in the Ada Reference Manual.  It is
3914provided for compatibility with some Ada 83 compilers that
3915used this pragma for exactly the same purposes as pragma
3916@code{Export} before the latter was standardized.
3917
3918@node Pragma External_Name_Casing,Pragma Fast_Math,Pragma External,Implementation Defined Pragmas
3919@anchor{gnat_rm/implementation_defined_pragmas pragma-external-name-casing}@anchor{69}
3920@section Pragma External_Name_Casing
3921
3922
3923@geindex Dec Ada 83 casing compatibility
3924
3925@geindex External Names
3926@geindex casing
3927
3928@geindex Casing of External names
3929
3930Syntax:
3931
3932@example
3933pragma External_Name_Casing (
3934  Uppercase | Lowercase
3935  [, Uppercase | Lowercase | As_Is]);
3936@end example
3937
3938This pragma provides control over the casing of external names associated
3939with Import and Export pragmas.  There are two cases to consider:
3940
3941
3942@itemize *
3943
3944@item
3945Implicit external names
3946
3947Implicit external names are derived from identifiers.  The most common case
3948arises when a standard Ada Import or Export pragma is used with only two
3949arguments, as in:
3950
3951@example
3952pragma Import (C, C_Routine);
3953@end example
3954
3955Since Ada is a case-insensitive language, the spelling of the identifier in
3956the Ada source program does not provide any information on the desired
3957casing of the external name, and so a convention is needed.  In GNAT the
3958default treatment is that such names are converted to all lower case
3959letters.  This corresponds to the normal C style in many environments.
3960The first argument of pragma @code{External_Name_Casing} can be used to
3961control this treatment.  If @code{Uppercase} is specified, then the name
3962will be forced to all uppercase letters.  If @code{Lowercase} is specified,
3963then the normal default of all lower case letters will be used.
3964
3965This same implicit treatment is also used in the case of extended DEC Ada 83
3966compatible Import and Export pragmas where an external name is explicitly
3967specified using an identifier rather than a string.
3968
3969@item
3970Explicit external names
3971
3972Explicit external names are given as string literals.  The most common case
3973arises when a standard Ada Import or Export pragma is used with three
3974arguments, as in:
3975
3976@example
3977pragma Import (C, C_Routine, "C_routine");
3978@end example
3979
3980In this case, the string literal normally provides the exact casing required
3981for the external name.  The second argument of pragma
3982@code{External_Name_Casing} may be used to modify this behavior.
3983If @code{Uppercase} is specified, then the name
3984will be forced to all uppercase letters.  If @code{Lowercase} is specified,
3985then the name will be forced to all lowercase letters.  A specification of
3986@code{As_Is} provides the normal default behavior in which the casing is
3987taken from the string provided.
3988@end itemize
3989
3990This pragma may appear anywhere that a pragma is valid. In particular, it
3991can be used as a configuration pragma in the @code{gnat.adc} file, in which
3992case it applies to all subsequent compilations, or it can be used as a program
3993unit pragma, in which case it only applies to the current unit, or it can
3994be used more locally to control individual Import/Export pragmas.
3995
3996It was primarily intended for use with OpenVMS systems, where many
3997compilers convert all symbols to upper case by default.  For interfacing to
3998such compilers (e.g., the DEC C compiler), it may be convenient to use
3999the pragma:
4000
4001@example
4002pragma External_Name_Casing (Uppercase, Uppercase);
4003@end example
4004
4005to enforce the upper casing of all external symbols.
4006
4007@node Pragma Fast_Math,Pragma Favor_Top_Level,Pragma External_Name_Casing,Implementation Defined Pragmas
4008@anchor{gnat_rm/implementation_defined_pragmas pragma-fast-math}@anchor{6a}
4009@section Pragma Fast_Math
4010
4011
4012Syntax:
4013
4014@example
4015pragma Fast_Math;
4016@end example
4017
4018This is a configuration pragma which activates a mode in which speed is
4019considered more important for floating-point operations than absolutely
4020accurate adherence to the requirements of the standard. Currently the
4021following operations are affected:
4022
4023
4024@table @asis
4025
4026@item @emph{Complex Multiplication}
4027
4028The normal simple formula for complex multiplication can result in intermediate
4029overflows for numbers near the end of the range. The Ada standard requires that
4030this situation be detected and corrected by scaling, but in Fast_Math mode such
4031cases will simply result in overflow. Note that to take advantage of this you
4032must instantiate your own version of @code{Ada.Numerics.Generic_Complex_Types}
4033under control of the pragma, rather than use the preinstantiated versions.
4034@end table
4035
4036@node Pragma Favor_Top_Level,Pragma Finalize_Storage_Only,Pragma Fast_Math,Implementation Defined Pragmas
4037@anchor{gnat_rm/implementation_defined_pragmas id13}@anchor{6b}@anchor{gnat_rm/implementation_defined_pragmas pragma-favor-top-level}@anchor{6c}
4038@section Pragma Favor_Top_Level
4039
4040
4041Syntax:
4042
4043@example
4044pragma Favor_Top_Level (type_NAME);
4045@end example
4046
4047The argument of pragma @code{Favor_Top_Level} must be a named access-to-subprogram
4048type. This pragma is an efficiency hint to the compiler, regarding the use of
4049@code{'Access} or @code{'Unrestricted_Access} on nested (non-library-level) subprograms.
4050The pragma means that nested subprograms are not used with this type, or are
4051rare, so that the generated code should be efficient in the top-level case.
4052When this pragma is used, dynamically generated trampolines may be used on some
4053targets for nested subprograms. See restriction @code{No_Implicit_Dynamic_Code}.
4054
4055@node Pragma Finalize_Storage_Only,Pragma Float_Representation,Pragma Favor_Top_Level,Implementation Defined Pragmas
4056@anchor{gnat_rm/implementation_defined_pragmas pragma-finalize-storage-only}@anchor{6d}
4057@section Pragma Finalize_Storage_Only
4058
4059
4060Syntax:
4061
4062@example
4063pragma Finalize_Storage_Only (first_subtype_LOCAL_NAME);
4064@end example
4065
4066The argument of pragma @code{Finalize_Storage_Only} must denote a local type which
4067is derived from @code{Ada.Finalization.Controlled} or @code{Limited_Controlled}. The
4068pragma suppresses the call to @code{Finalize} for declared library-level objects
4069of the argument type. This is mostly useful for types where finalization is
4070only used to deal with storage reclamation since in most environments it is
4071not necessary to reclaim memory just before terminating execution, hence the
4072name. Note that this pragma does not suppress Finalize calls for library-level
4073heap-allocated objects (see pragma @code{No_Heap_Finalization}).
4074
4075@node Pragma Float_Representation,Pragma Ghost,Pragma Finalize_Storage_Only,Implementation Defined Pragmas
4076@anchor{gnat_rm/implementation_defined_pragmas pragma-float-representation}@anchor{6e}
4077@section Pragma Float_Representation
4078
4079
4080Syntax:
4081
4082@example
4083pragma Float_Representation (FLOAT_REP[, float_type_LOCAL_NAME]);
4084
4085FLOAT_REP ::= VAX_Float | IEEE_Float
4086@end example
4087
4088In the one argument form, this pragma is a configuration pragma which
4089allows control over the internal representation chosen for the predefined
4090floating point types declared in the packages @code{Standard} and
4091@code{System}. This pragma is only provided for compatibility and has no effect.
4092
4093The two argument form specifies the representation to be used for
4094the specified floating-point type. The argument must
4095be @code{IEEE_Float} to specify the use of IEEE format, as follows:
4096
4097
4098@itemize *
4099
4100@item
4101For a digits value of 6, 32-bit IEEE short format will be used.
4102
4103@item
4104For a digits value of 15, 64-bit IEEE long format will be used.
4105
4106@item
4107No other value of digits is permitted.
4108@end itemize
4109
4110@node Pragma Ghost,Pragma Global,Pragma Float_Representation,Implementation Defined Pragmas
4111@anchor{gnat_rm/implementation_defined_pragmas id14}@anchor{6f}@anchor{gnat_rm/implementation_defined_pragmas pragma-ghost}@anchor{70}
4112@section Pragma Ghost
4113
4114
4115Syntax:
4116
4117@example
4118pragma Ghost [ (boolean_EXPRESSION) ];
4119@end example
4120
4121For the semantics of this pragma, see the entry for aspect @code{Ghost} in the SPARK
41222014 Reference Manual, section 6.9.
4123
4124@node Pragma Global,Pragma Ident,Pragma Ghost,Implementation Defined Pragmas
4125@anchor{gnat_rm/implementation_defined_pragmas id15}@anchor{71}@anchor{gnat_rm/implementation_defined_pragmas pragma-global}@anchor{72}
4126@section Pragma Global
4127
4128
4129Syntax:
4130
4131@example
4132pragma Global (GLOBAL_SPECIFICATION);
4133
4134GLOBAL_SPECIFICATION ::=
4135     null
4136  | (GLOBAL_LIST)
4137  | (MODED_GLOBAL_LIST @{, MODED_GLOBAL_LIST@})
4138
4139MODED_GLOBAL_LIST ::= MODE_SELECTOR => GLOBAL_LIST
4140
4141MODE_SELECTOR ::= In_Out | Input | Output | Proof_In
4142GLOBAL_LIST   ::= GLOBAL_ITEM | (GLOBAL_ITEM @{, GLOBAL_ITEM@})
4143GLOBAL_ITEM   ::= NAME
4144@end example
4145
4146For the semantics of this pragma, see the entry for aspect @code{Global} in the
4147SPARK 2014 Reference Manual, section 6.1.4.
4148
4149@node Pragma Ident,Pragma Ignore_Pragma,Pragma Global,Implementation Defined Pragmas
4150@anchor{gnat_rm/implementation_defined_pragmas pragma-ident}@anchor{73}
4151@section Pragma Ident
4152
4153
4154Syntax:
4155
4156@example
4157pragma Ident (static_string_EXPRESSION);
4158@end example
4159
4160This pragma is identical in effect to pragma @code{Comment}. It is provided
4161for compatibility with other Ada compilers providing this pragma.
4162
4163@node Pragma Ignore_Pragma,Pragma Implementation_Defined,Pragma Ident,Implementation Defined Pragmas
4164@anchor{gnat_rm/implementation_defined_pragmas pragma-ignore-pragma}@anchor{74}
4165@section Pragma Ignore_Pragma
4166
4167
4168Syntax:
4169
4170@example
4171pragma Ignore_Pragma (pragma_IDENTIFIER);
4172@end example
4173
4174This is a configuration pragma
4175that takes a single argument that is a simple identifier. Any subsequent
4176use of a pragma whose pragma identifier matches this argument will be
4177silently ignored. This may be useful when legacy code or code intended
4178for compilation with some other compiler contains pragmas that match the
4179name, but not the exact implementation, of a GNAT pragma. The use of this
4180pragma allows such pragmas to be ignored, which may be useful in CodePeer
4181mode, or during porting of legacy code.
4182
4183@node Pragma Implementation_Defined,Pragma Implemented,Pragma Ignore_Pragma,Implementation Defined Pragmas
4184@anchor{gnat_rm/implementation_defined_pragmas pragma-implementation-defined}@anchor{75}
4185@section Pragma Implementation_Defined
4186
4187
4188Syntax:
4189
4190@example
4191pragma Implementation_Defined (local_NAME);
4192@end example
4193
4194This pragma marks a previously declared entity as implementation-defined.
4195For an overloaded entity, applies to the most recent homonym.
4196
4197@example
4198pragma Implementation_Defined;
4199@end example
4200
4201The form with no arguments appears anywhere within a scope, most
4202typically a package spec, and indicates that all entities that are
4203defined within the package spec are Implementation_Defined.
4204
4205This pragma is used within the GNAT runtime library to identify
4206implementation-defined entities introduced in language-defined units,
4207for the purpose of implementing the No_Implementation_Identifiers
4208restriction.
4209
4210@node Pragma Implemented,Pragma Implicit_Packing,Pragma Implementation_Defined,Implementation Defined Pragmas
4211@anchor{gnat_rm/implementation_defined_pragmas pragma-implemented}@anchor{76}
4212@section Pragma Implemented
4213
4214
4215Syntax:
4216
4217@example
4218pragma Implemented (procedure_LOCAL_NAME, implementation_kind);
4219
4220implementation_kind ::= By_Entry | By_Protected_Procedure | By_Any
4221@end example
4222
4223This is an Ada 2012 representation pragma which applies to protected, task
4224and synchronized interface primitives. The use of pragma Implemented provides
4225a way to impose a static requirement on the overriding operation by adhering
4226to one of the three implementation kinds: entry, protected procedure or any of
4227the above. This pragma is available in all earlier versions of Ada as an
4228implementation-defined pragma.
4229
4230@example
4231type Synch_Iface is synchronized interface;
4232procedure Prim_Op (Obj : in out Iface) is abstract;
4233pragma Implemented (Prim_Op, By_Protected_Procedure);
4234
4235protected type Prot_1 is new Synch_Iface with
4236   procedure Prim_Op;  --  Legal
4237end Prot_1;
4238
4239protected type Prot_2 is new Synch_Iface with
4240   entry Prim_Op;      --  Illegal
4241end Prot_2;
4242
4243task type Task_Typ is new Synch_Iface with
4244   entry Prim_Op;      --  Illegal
4245end Task_Typ;
4246@end example
4247
4248When applied to the procedure_or_entry_NAME of a requeue statement, pragma
4249Implemented determines the runtime behavior of the requeue. Implementation kind
4250By_Entry guarantees that the action of requeueing will proceed from an entry to
4251another entry. Implementation kind By_Protected_Procedure transforms the
4252requeue into a dispatching call, thus eliminating the chance of blocking. Kind
4253By_Any shares the behavior of By_Entry and By_Protected_Procedure depending on
4254the target’s overriding subprogram kind.
4255
4256@node Pragma Implicit_Packing,Pragma Import_Function,Pragma Implemented,Implementation Defined Pragmas
4257@anchor{gnat_rm/implementation_defined_pragmas pragma-implicit-packing}@anchor{77}
4258@section Pragma Implicit_Packing
4259
4260
4261@geindex Rational Profile
4262
4263Syntax:
4264
4265@example
4266pragma Implicit_Packing;
4267@end example
4268
4269This is a configuration pragma that requests implicit packing for packed
4270arrays for which a size clause is given but no explicit pragma Pack or
4271specification of Component_Size is present. It also applies to records
4272where no record representation clause is present. Consider this example:
4273
4274@example
4275type R is array (0 .. 7) of Boolean;
4276for R'Size use 8;
4277@end example
4278
4279In accordance with the recommendation in the RM (RM 13.3(53)), a Size clause
4280does not change the layout of a composite object. So the Size clause in the
4281above example is normally rejected, since the default layout of the array uses
42828-bit components, and thus the array requires a minimum of 64 bits.
4283
4284If this declaration is compiled in a region of code covered by an occurrence
4285of the configuration pragma Implicit_Packing, then the Size clause in this
4286and similar examples will cause implicit packing and thus be accepted. For
4287this implicit packing to occur, the type in question must be an array of small
4288components whose size is known at compile time, and the Size clause must
4289specify the exact size that corresponds to the number of elements in the array
4290multiplied by the size in bits of the component type (both single and
4291multi-dimensioned arrays can be controlled with this pragma).
4292
4293@geindex Array packing
4294
4295Similarly, the following example shows the use in the record case
4296
4297@example
4298type r is record
4299   a, b, c, d, e, f, g, h : boolean;
4300   chr                    : character;
4301end record;
4302for r'size use 16;
4303@end example
4304
4305Without a pragma Pack, each Boolean field requires 8 bits, so the
4306minimum size is 72 bits, but with a pragma Pack, 16 bits would be
4307sufficient. The use of pragma Implicit_Packing allows this record
4308declaration to compile without an explicit pragma Pack.
4309
4310@node Pragma Import_Function,Pragma Import_Object,Pragma Implicit_Packing,Implementation Defined Pragmas
4311@anchor{gnat_rm/implementation_defined_pragmas pragma-import-function}@anchor{78}
4312@section Pragma Import_Function
4313
4314
4315Syntax:
4316
4317@example
4318pragma Import_Function (
4319     [Internal                 =>] LOCAL_NAME,
4320  [, [External                 =>] EXTERNAL_SYMBOL]
4321  [, [Parameter_Types          =>] PARAMETER_TYPES]
4322  [, [Result_Type              =>] SUBTYPE_MARK]
4323  [, [Mechanism                =>] MECHANISM]
4324  [, [Result_Mechanism         =>] MECHANISM_NAME]);
4325
4326EXTERNAL_SYMBOL ::=
4327  IDENTIFIER
4328| static_string_EXPRESSION
4329
4330PARAMETER_TYPES ::=
4331  null
4332| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@}
4333
4334TYPE_DESIGNATOR ::=
4335  subtype_NAME
4336| subtype_Name ' Access
4337
4338MECHANISM ::=
4339  MECHANISM_NAME
4340| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@})
4341
4342MECHANISM_ASSOCIATION ::=
4343  [formal_parameter_NAME =>] MECHANISM_NAME
4344
4345MECHANISM_NAME ::=
4346  Value
4347| Reference
4348@end example
4349
4350This pragma is used in conjunction with a pragma @code{Import} to
4351specify additional information for an imported function.  The pragma
4352@code{Import} (or equivalent pragma @code{Interface}) must precede the
4353@code{Import_Function} pragma and both must appear in the same
4354declarative part as the function specification.
4355
4356The @code{Internal} argument must uniquely designate
4357the function to which the
4358pragma applies.  If more than one function name exists of this name in
4359the declarative part you must use the @code{Parameter_Types} and
4360@code{Result_Type} parameters to achieve the required unique
4361designation.  Subtype marks in these parameters must exactly match the
4362subtypes in the corresponding function specification, using positional
4363notation to match parameters with subtype marks.
4364The form with an @code{'Access} attribute can be used to match an
4365anonymous access parameter.
4366
4367You may optionally use the @code{Mechanism} and @code{Result_Mechanism}
4368parameters to specify passing mechanisms for the
4369parameters and result.  If you specify a single mechanism name, it
4370applies to all parameters.  Otherwise you may specify a mechanism on a
4371parameter by parameter basis using either positional or named
4372notation.  If the mechanism is not specified, the default mechanism
4373is used.
4374
4375@node Pragma Import_Object,Pragma Import_Procedure,Pragma Import_Function,Implementation Defined Pragmas
4376@anchor{gnat_rm/implementation_defined_pragmas pragma-import-object}@anchor{79}
4377@section Pragma Import_Object
4378
4379
4380Syntax:
4381
4382@example
4383pragma Import_Object
4384     [Internal =>] LOCAL_NAME
4385  [, [External =>] EXTERNAL_SYMBOL]
4386  [, [Size     =>] EXTERNAL_SYMBOL]);
4387
4388EXTERNAL_SYMBOL ::=
4389  IDENTIFIER
4390| static_string_EXPRESSION
4391@end example
4392
4393This pragma designates an object as imported, and apart from the
4394extended rules for external symbols, is identical in effect to the use of
4395the normal @code{Import} pragma applied to an object.  Unlike the
4396subprogram case, you need not use a separate @code{Import} pragma,
4397although you may do so (and probably should do so from a portability
4398point of view).  @code{size} is syntax checked, but otherwise ignored by
4399GNAT.
4400
4401@node Pragma Import_Procedure,Pragma Import_Valued_Procedure,Pragma Import_Object,Implementation Defined Pragmas
4402@anchor{gnat_rm/implementation_defined_pragmas pragma-import-procedure}@anchor{7a}
4403@section Pragma Import_Procedure
4404
4405
4406Syntax:
4407
4408@example
4409pragma Import_Procedure (
4410     [Internal                 =>] LOCAL_NAME
4411  [, [External                 =>] EXTERNAL_SYMBOL]
4412  [, [Parameter_Types          =>] PARAMETER_TYPES]
4413  [, [Mechanism                =>] MECHANISM]);
4414
4415EXTERNAL_SYMBOL ::=
4416  IDENTIFIER
4417| static_string_EXPRESSION
4418
4419PARAMETER_TYPES ::=
4420  null
4421| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@}
4422
4423TYPE_DESIGNATOR ::=
4424  subtype_NAME
4425| subtype_Name ' Access
4426
4427MECHANISM ::=
4428  MECHANISM_NAME
4429| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@})
4430
4431MECHANISM_ASSOCIATION ::=
4432  [formal_parameter_NAME =>] MECHANISM_NAME
4433
4434MECHANISM_NAME ::= Value | Reference
4435@end example
4436
4437This pragma is identical to @code{Import_Function} except that it
4438applies to a procedure rather than a function and the parameters
4439@code{Result_Type} and @code{Result_Mechanism} are not permitted.
4440
4441@node Pragma Import_Valued_Procedure,Pragma Independent,Pragma Import_Procedure,Implementation Defined Pragmas
4442@anchor{gnat_rm/implementation_defined_pragmas pragma-import-valued-procedure}@anchor{7b}
4443@section Pragma Import_Valued_Procedure
4444
4445
4446Syntax:
4447
4448@example
4449pragma Import_Valued_Procedure (
4450     [Internal                 =>] LOCAL_NAME
4451  [, [External                 =>] EXTERNAL_SYMBOL]
4452  [, [Parameter_Types          =>] PARAMETER_TYPES]
4453  [, [Mechanism                =>] MECHANISM]);
4454
4455EXTERNAL_SYMBOL ::=
4456  IDENTIFIER
4457| static_string_EXPRESSION
4458
4459PARAMETER_TYPES ::=
4460  null
4461| TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@}
4462
4463TYPE_DESIGNATOR ::=
4464  subtype_NAME
4465| subtype_Name ' Access
4466
4467MECHANISM ::=
4468  MECHANISM_NAME
4469| (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@})
4470
4471MECHANISM_ASSOCIATION ::=
4472  [formal_parameter_NAME =>] MECHANISM_NAME
4473
4474MECHANISM_NAME ::= Value | Reference
4475@end example
4476
4477This pragma is identical to @code{Import_Procedure} except that the
4478first parameter of @code{LOCAL_NAME}, which must be present, must be of
4479mode @code{out}, and externally the subprogram is treated as a function
4480with this parameter as the result of the function.  The purpose of this
4481capability is to allow the use of @code{out} and @code{in out}
4482parameters in interfacing to external functions (which are not permitted
4483in Ada functions).  You may optionally use the @code{Mechanism}
4484parameters to specify passing mechanisms for the parameters.
4485If you specify a single mechanism name, it applies to all parameters.
4486Otherwise you may specify a mechanism on a parameter by parameter
4487basis using either positional or named notation.  If the mechanism is not
4488specified, the default mechanism is used.
4489
4490Note that it is important to use this pragma in conjunction with a separate
4491pragma Import that specifies the desired convention, since otherwise the
4492default convention is Ada, which is almost certainly not what is required.
4493
4494@node Pragma Independent,Pragma Independent_Components,Pragma Import_Valued_Procedure,Implementation Defined Pragmas
4495@anchor{gnat_rm/implementation_defined_pragmas pragma-independent}@anchor{7c}
4496@section Pragma Independent
4497
4498
4499Syntax:
4500
4501@example
4502pragma Independent (Local_NAME);
4503@end example
4504
4505This pragma is standard in Ada 2012 mode (which also provides an aspect
4506of the same name). It is also available as an implementation-defined
4507pragma in all earlier versions. It specifies that the
4508designated object or all objects of the designated type must be
4509independently addressable. This means that separate tasks can safely
4510manipulate such objects. For example, if two components of a record are
4511independent, then two separate tasks may access these two components.
4512This may place
4513constraints on the representation of the object (for instance prohibiting
4514tight packing).
4515
4516@node Pragma Independent_Components,Pragma Initial_Condition,Pragma Independent,Implementation Defined Pragmas
4517@anchor{gnat_rm/implementation_defined_pragmas pragma-independent-components}@anchor{7d}
4518@section Pragma Independent_Components
4519
4520
4521Syntax:
4522
4523@example
4524pragma Independent_Components (Local_NAME);
4525@end example
4526
4527This pragma is standard in Ada 2012 mode (which also provides an aspect
4528of the same name). It is also available as an implementation-defined
4529pragma in all earlier versions. It specifies that the components of the
4530designated object, or the components of each object of the designated
4531type, must be
4532independently addressable. This means that separate tasks can safely
4533manipulate separate components in the composite object. This may place
4534constraints on the representation of the object (for instance prohibiting
4535tight packing).
4536
4537@node Pragma Initial_Condition,Pragma Initialize_Scalars,Pragma Independent_Components,Implementation Defined Pragmas
4538@anchor{gnat_rm/implementation_defined_pragmas id16}@anchor{7e}@anchor{gnat_rm/implementation_defined_pragmas pragma-initial-condition}@anchor{7f}
4539@section Pragma Initial_Condition
4540
4541
4542Syntax:
4543
4544@example
4545pragma Initial_Condition (boolean_EXPRESSION);
4546@end example
4547
4548For the semantics of this pragma, see the entry for aspect @code{Initial_Condition}
4549in the SPARK 2014 Reference Manual, section 7.1.6.
4550
4551@node Pragma Initialize_Scalars,Pragma Initializes,Pragma Initial_Condition,Implementation Defined Pragmas
4552@anchor{gnat_rm/implementation_defined_pragmas pragma-initialize-scalars}@anchor{80}
4553@section Pragma Initialize_Scalars
4554
4555
4556@geindex debugging with Initialize_Scalars
4557
4558Syntax:
4559
4560@example
4561pragma Initialize_Scalars
4562  [ ( TYPE_VALUE_PAIR @{, TYPE_VALUE_PAIR@} ) ];
4563
4564TYPE_VALUE_PAIR ::=
4565  SCALAR_TYPE => static_EXPRESSION
4566
4567SCALAR_TYPE :=
4568  Short_Float
4569| Float
4570| Long_Float
4571| Long_Long_Flat
4572| Signed_8
4573| Signed_16
4574| Signed_32
4575| Signed_64
4576| Unsigned_8
4577| Unsigned_16
4578| Unsigned_32
4579| Unsigned_64
4580@end example
4581
4582This pragma is similar to @code{Normalize_Scalars} conceptually but has two
4583important differences.
4584
4585First, there is no requirement for the pragma to be used uniformly in all units
4586of a partition. In particular, it is fine to use this just for some or all of
4587the application units of a partition, without needing to recompile the run-time
4588library. In the case where some units are compiled with the pragma, and some
4589without, then a declaration of a variable where the type is defined in package
4590Standard or is locally declared will always be subject to initialization, as
4591will any declaration of a scalar variable. For composite variables, whether the
4592variable is initialized may also depend on whether the package in which the
4593type of the variable is declared is compiled with the pragma.
4594
4595The other important difference is that the programmer can control the value
4596used for initializing scalar objects. This effect can be achieved in several
4597different ways:
4598
4599
4600@itemize *
4601
4602@item
4603At compile time, the programmer can specify the invalid value for a
4604particular family of scalar types using the optional arguments of the pragma.
4605
4606The compile-time approach is intended to optimize the generated code for the
4607pragma, by possibly using fast operations such as @code{memset}. Note that such
4608optimizations require using values where the bytes all have the same binary
4609representation.
4610
4611@item
4612At bind time, the programmer has several options:
4613
4614
4615@itemize *
4616
4617@item
4618Initialization with invalid values (similar to Normalize_Scalars, though
4619for Initialize_Scalars it is not always possible to determine the invalid
4620values in complex cases like signed component fields with nonstandard
4621sizes).
4622
4623@item
4624Initialization with high values.
4625
4626@item
4627Initialization with low values.
4628
4629@item
4630Initialization with a specific bit pattern.
4631@end itemize
4632
4633See the GNAT User’s Guide for binder options for specifying these cases.
4634
4635The bind-time approach is intended to provide fast turnaround for testing
4636with different values, without having to recompile the program.
4637
4638@item
4639At execution time, the programmer can specify the invalid values using an
4640environment variable. See the GNAT User’s Guide for details.
4641
4642The execution-time approach is intended to provide fast turnaround for
4643testing with different values, without having to recompile and rebind the
4644program.
4645@end itemize
4646
4647Note that pragma @code{Initialize_Scalars} is particularly useful in conjunction
4648with the enhanced validity checking that is now provided in GNAT, which checks
4649for invalid values under more conditions. Using this feature (see description
4650of the @emph{-gnatV} flag in the GNAT User’s Guide) in conjunction with pragma
4651@code{Initialize_Scalars} provides a powerful new tool to assist in the detection
4652of problems caused by uninitialized variables.
4653
4654Note: the use of @code{Initialize_Scalars} has a fairly extensive effect on the
4655generated code. This may cause your code to be substantially larger. It may
4656also cause an increase in the amount of stack required, so it is probably a
4657good idea to turn on stack checking (see description of stack checking in the
4658GNAT User’s Guide) when using this pragma.
4659
4660@node Pragma Initializes,Pragma Inline_Always,Pragma Initialize_Scalars,Implementation Defined Pragmas
4661@anchor{gnat_rm/implementation_defined_pragmas id17}@anchor{81}@anchor{gnat_rm/implementation_defined_pragmas pragma-initializes}@anchor{82}
4662@section Pragma Initializes
4663
4664
4665Syntax:
4666
4667@example
4668pragma Initializes (INITIALIZATION_LIST);
4669
4670INITIALIZATION_LIST ::=
4671     null
4672  | (INITIALIZATION_ITEM @{, INITIALIZATION_ITEM@})
4673
4674INITIALIZATION_ITEM ::= name [=> INPUT_LIST]
4675
4676INPUT_LIST ::=
4677     null
4678  |  INPUT
4679  | (INPUT @{, INPUT@})
4680
4681INPUT ::= name
4682@end example
4683
4684For the semantics of this pragma, see the entry for aspect @code{Initializes} in the
4685SPARK 2014 Reference Manual, section 7.1.5.
4686
4687@node Pragma Inline_Always,Pragma Inline_Generic,Pragma Initializes,Implementation Defined Pragmas
4688@anchor{gnat_rm/implementation_defined_pragmas id18}@anchor{83}@anchor{gnat_rm/implementation_defined_pragmas pragma-inline-always}@anchor{84}
4689@section Pragma Inline_Always
4690
4691
4692Syntax:
4693
4694@example
4695pragma Inline_Always (NAME [, NAME]);
4696@end example
4697
4698Similar to pragma @code{Inline} except that inlining is unconditional.
4699Inline_Always instructs the compiler to inline every direct call to the
4700subprogram or else to emit a compilation error, independently of any
4701option, in particular @emph{-gnatn} or @emph{-gnatN} or the optimization level.
4702It is an error to take the address or access of @code{NAME}. It is also an error to
4703apply this pragma to a primitive operation of a tagged type. Thanks to such
4704restrictions, the compiler is allowed to remove the out-of-line body of @code{NAME}.
4705
4706@node Pragma Inline_Generic,Pragma Interface,Pragma Inline_Always,Implementation Defined Pragmas
4707@anchor{gnat_rm/implementation_defined_pragmas pragma-inline-generic}@anchor{85}
4708@section Pragma Inline_Generic
4709
4710
4711Syntax:
4712
4713@example
4714pragma Inline_Generic (GNAME @{, GNAME@});
4715
4716GNAME ::= generic_unit_NAME | generic_instance_NAME
4717@end example
4718
4719This pragma is provided for compatibility with Dec Ada 83. It has
4720no effect in GNAT (which always inlines generics), other
4721than to check that the given names are all names of generic units or
4722generic instances.
4723
4724@node Pragma Interface,Pragma Interface_Name,Pragma Inline_Generic,Implementation Defined Pragmas
4725@anchor{gnat_rm/implementation_defined_pragmas pragma-interface}@anchor{86}
4726@section Pragma Interface
4727
4728
4729Syntax:
4730
4731@example
4732pragma Interface (
4733     [Convention    =>] convention_identifier,
4734     [Entity        =>] local_NAME
4735  [, [External_Name =>] static_string_expression]
4736  [, [Link_Name     =>] static_string_expression]);
4737@end example
4738
4739This pragma is identical in syntax and semantics to
4740the standard Ada pragma @code{Import}.  It is provided for compatibility
4741with Ada 83.  The definition is upwards compatible both with pragma
4742@code{Interface} as defined in the Ada 83 Reference Manual, and also
4743with some extended implementations of this pragma in certain Ada 83
4744implementations.  The only difference between pragma @code{Interface}
4745and pragma @code{Import} is that there is special circuitry to allow
4746both pragmas to appear for the same subprogram entity (normally it
4747is illegal to have multiple @code{Import} pragmas. This is useful in
4748maintaining Ada 83/Ada 95 compatibility and is compatible with other
4749Ada 83 compilers.
4750
4751@node Pragma Interface_Name,Pragma Interrupt_Handler,Pragma Interface,Implementation Defined Pragmas
4752@anchor{gnat_rm/implementation_defined_pragmas pragma-interface-name}@anchor{87}
4753@section Pragma Interface_Name
4754
4755
4756Syntax:
4757
4758@example
4759pragma Interface_Name (
4760     [Entity        =>] LOCAL_NAME
4761  [, [External_Name =>] static_string_EXPRESSION]
4762  [, [Link_Name     =>] static_string_EXPRESSION]);
4763@end example
4764
4765This pragma provides an alternative way of specifying the interface name
4766for an interfaced subprogram, and is provided for compatibility with Ada
476783 compilers that use the pragma for this purpose.  You must provide at
4768least one of @code{External_Name} or @code{Link_Name}.
4769
4770@node Pragma Interrupt_Handler,Pragma Interrupt_State,Pragma Interface_Name,Implementation Defined Pragmas
4771@anchor{gnat_rm/implementation_defined_pragmas pragma-interrupt-handler}@anchor{88}
4772@section Pragma Interrupt_Handler
4773
4774
4775Syntax:
4776
4777@example
4778pragma Interrupt_Handler (procedure_LOCAL_NAME);
4779@end example
4780
4781This program unit pragma is supported for parameterless protected procedures
4782as described in Annex C of the Ada Reference Manual.
4783
4784@node Pragma Interrupt_State,Pragma Invariant,Pragma Interrupt_Handler,Implementation Defined Pragmas
4785@anchor{gnat_rm/implementation_defined_pragmas pragma-interrupt-state}@anchor{89}
4786@section Pragma Interrupt_State
4787
4788
4789Syntax:
4790
4791@example
4792pragma Interrupt_State
4793 ([Name  =>] value,
4794  [State =>] SYSTEM | RUNTIME | USER);
4795@end example
4796
4797Normally certain interrupts are reserved to the implementation.  Any attempt
4798to attach an interrupt causes Program_Error to be raised, as described in
4799RM C.3.2(22).  A typical example is the @code{SIGINT} interrupt used in
4800many systems for an @code{Ctrl-C} interrupt.  Normally this interrupt is
4801reserved to the implementation, so that @code{Ctrl-C} can be used to
4802interrupt execution.  Additionally, signals such as @code{SIGSEGV},
4803@code{SIGABRT}, @code{SIGFPE} and @code{SIGILL} are often mapped to specific
4804Ada exceptions, or used to implement run-time functions such as the
4805@code{abort} statement and stack overflow checking.
4806
4807Pragma @code{Interrupt_State} provides a general mechanism for overriding
4808such uses of interrupts.  It subsumes the functionality of pragma
4809@code{Unreserve_All_Interrupts}.  Pragma @code{Interrupt_State} is not
4810available on Windows.  On all other platforms than VxWorks,
4811it applies to signals; on VxWorks, it applies to vectored hardware interrupts
4812and may be used to mark interrupts required by the board support package
4813as reserved.
4814
4815Interrupts can be in one of three states:
4816
4817
4818@itemize *
4819
4820@item
4821System
4822
4823The interrupt is reserved (no Ada handler can be installed), and the
4824Ada run-time may not install a handler. As a result you are guaranteed
4825standard system default action if this interrupt is raised. This also allows
4826installing a low level handler via C APIs such as sigaction(), outside
4827of Ada control.
4828
4829@item
4830Runtime
4831
4832The interrupt is reserved (no Ada handler can be installed). The run time
4833is allowed to install a handler for internal control purposes, but is
4834not required to do so.
4835
4836@item
4837User
4838
4839The interrupt is unreserved.  The user may install an Ada handler via
4840Ada.Interrupts and pragma Interrupt_Handler or Attach_Handler to provide
4841some other action.
4842@end itemize
4843
4844These states are the allowed values of the @code{State} parameter of the
4845pragma.  The @code{Name} parameter is a value of the type
4846@code{Ada.Interrupts.Interrupt_ID}.  Typically, it is a name declared in
4847@code{Ada.Interrupts.Names}.
4848
4849This is a configuration pragma, and the binder will check that there
4850are no inconsistencies between different units in a partition in how a
4851given interrupt is specified. It may appear anywhere a pragma is legal.
4852
4853The effect is to move the interrupt to the specified state.
4854
4855By declaring interrupts to be SYSTEM, you guarantee the standard system
4856action, such as a core dump.
4857
4858By declaring interrupts to be USER, you guarantee that you can install
4859a handler.
4860
4861Note that certain signals on many operating systems cannot be caught and
4862handled by applications.  In such cases, the pragma is ignored.  See the
4863operating system documentation, or the value of the array @code{Reserved}
4864declared in the spec of package @code{System.OS_Interface}.
4865
4866Overriding the default state of signals used by the Ada runtime may interfere
4867with an application’s runtime behavior in the cases of the synchronous signals,
4868and in the case of the signal used to implement the @code{abort} statement.
4869
4870@node Pragma Invariant,Pragma Keep_Names,Pragma Interrupt_State,Implementation Defined Pragmas
4871@anchor{gnat_rm/implementation_defined_pragmas id19}@anchor{8a}@anchor{gnat_rm/implementation_defined_pragmas pragma-invariant}@anchor{8b}
4872@section Pragma Invariant
4873
4874
4875Syntax:
4876
4877@example
4878pragma Invariant
4879  ([Entity =>]    private_type_LOCAL_NAME,
4880   [Check  =>]    EXPRESSION
4881   [,[Message =>] String_Expression]);
4882@end example
4883
4884This pragma provides exactly the same capabilities as the Type_Invariant aspect
4885defined in AI05-0146-1, and in the Ada 2012 Reference Manual. The
4886Type_Invariant aspect is fully implemented in Ada 2012 mode, but since it
4887requires the use of the aspect syntax, which is not available except in 2012
4888mode, it is not possible to use the Type_Invariant aspect in earlier versions
4889of Ada. However the Invariant pragma may be used in any version of Ada. Also
4890note that the aspect Invariant is a synonym in GNAT for the aspect
4891Type_Invariant, but there is no pragma Type_Invariant.
4892
4893The pragma must appear within the visible part of the package specification,
4894after the type to which its Entity argument appears. As with the Invariant
4895aspect, the Check expression is not analyzed until the end of the visible
4896part of the package, so it may contain forward references. The Message
4897argument, if present, provides the exception message used if the invariant
4898is violated. If no Message parameter is provided, a default message that
4899identifies the line on which the pragma appears is used.
4900
4901It is permissible to have multiple Invariants for the same type entity, in
4902which case they are and’ed together. It is permissible to use this pragma
4903in Ada 2012 mode, but you cannot have both an invariant aspect and an
4904invariant pragma for the same entity.
4905
4906For further details on the use of this pragma, see the Ada 2012 documentation
4907of the Type_Invariant aspect.
4908
4909@node Pragma Keep_Names,Pragma License,Pragma Invariant,Implementation Defined Pragmas
4910@anchor{gnat_rm/implementation_defined_pragmas pragma-keep-names}@anchor{8c}
4911@section Pragma Keep_Names
4912
4913
4914Syntax:
4915
4916@example
4917pragma Keep_Names ([On =>] enumeration_first_subtype_LOCAL_NAME);
4918@end example
4919
4920The @code{LOCAL_NAME} argument
4921must refer to an enumeration first subtype
4922in the current declarative part. The effect is to retain the enumeration
4923literal names for use by @code{Image} and @code{Value} even if a global
4924@code{Discard_Names} pragma applies. This is useful when you want to
4925generally suppress enumeration literal names and for example you therefore
4926use a @code{Discard_Names} pragma in the @code{gnat.adc} file, but you
4927want to retain the names for specific enumeration types.
4928
4929@node Pragma License,Pragma Link_With,Pragma Keep_Names,Implementation Defined Pragmas
4930@anchor{gnat_rm/implementation_defined_pragmas pragma-license}@anchor{8d}
4931@section Pragma License
4932
4933
4934@geindex License checking
4935
4936Syntax:
4937
4938@example
4939pragma License (Unrestricted | GPL | Modified_GPL | Restricted);
4940@end example
4941
4942This pragma is provided to allow automated checking for appropriate license
4943conditions with respect to the standard and modified GPL.  A pragma
4944@code{License}, which is a configuration pragma that typically appears at
4945the start of a source file or in a separate @code{gnat.adc} file, specifies
4946the licensing conditions of a unit as follows:
4947
4948
4949@itemize *
4950
4951@item
4952Unrestricted
4953This is used for a unit that can be freely used with no license restrictions.
4954Examples of such units are public domain units, and units from the Ada
4955Reference Manual.
4956
4957@item
4958GPL
4959This is used for a unit that is licensed under the unmodified GPL, and which
4960therefore cannot be @code{with}ed by a restricted unit.
4961
4962@item
4963Modified_GPL
4964This is used for a unit licensed under the GNAT modified GPL that includes
4965a special exception paragraph that specifically permits the inclusion of
4966the unit in programs without requiring the entire program to be released
4967under the GPL.
4968
4969@item
4970Restricted
4971This is used for a unit that is restricted in that it is not permitted to
4972depend on units that are licensed under the GPL.  Typical examples are
4973proprietary code that is to be released under more restrictive license
4974conditions.  Note that restricted units are permitted to @code{with} units
4975which are licensed under the modified GPL (this is the whole point of the
4976modified GPL).
4977@end itemize
4978
4979Normally a unit with no @code{License} pragma is considered to have an
4980unknown license, and no checking is done.  However, standard GNAT headers
4981are recognized, and license information is derived from them as follows.
4982
4983A GNAT license header starts with a line containing 78 hyphens.  The following
4984comment text is searched for the appearance of any of the following strings.
4985
4986If the string ‘GNU General Public License’ is found, then the unit is assumed
4987to have GPL license, unless the string ‘As a special exception’ follows, in
4988which case the license is assumed to be modified GPL.
4989
4990If one of the strings
4991‘This specification is adapted from the Ada Semantic Interface’ or
4992‘This specification is derived from the Ada Reference Manual’ is found
4993then the unit is assumed to be unrestricted.
4994
4995These default actions means that a program with a restricted license pragma
4996will automatically get warnings if a GPL unit is inappropriately
4997@code{with}ed.  For example, the program:
4998
4999@example
5000with Sem_Ch3;
5001with GNAT.Sockets;
5002procedure Secret_Stuff is
5003  ...
5004end Secret_Stuff
5005@end example
5006
5007if compiled with pragma @code{License} (@code{Restricted}) in a
5008@code{gnat.adc} file will generate the warning:
5009
5010@example
50111.  with Sem_Ch3;
5012        |
5013   >>> license of withed unit "Sem_Ch3" is incompatible
5014
50152.  with GNAT.Sockets;
50163.  procedure Secret_Stuff is
5017@end example
5018
5019Here we get a warning on @code{Sem_Ch3} since it is part of the GNAT
5020compiler and is licensed under the
5021GPL, but no warning for @code{GNAT.Sockets} which is part of the GNAT
5022run time, and is therefore licensed under the modified GPL.
5023
5024@node Pragma Link_With,Pragma Linker_Alias,Pragma License,Implementation Defined Pragmas
5025@anchor{gnat_rm/implementation_defined_pragmas pragma-link-with}@anchor{8e}
5026@section Pragma Link_With
5027
5028
5029Syntax:
5030
5031@example
5032pragma Link_With (static_string_EXPRESSION @{,static_string_EXPRESSION@});
5033@end example
5034
5035This pragma is provided for compatibility with certain Ada 83 compilers.
5036It has exactly the same effect as pragma @code{Linker_Options} except
5037that spaces occurring within one of the string expressions are treated
5038as separators. For example, in the following case:
5039
5040@example
5041pragma Link_With ("-labc -ldef");
5042@end example
5043
5044results in passing the strings @code{-labc} and @code{-ldef} as two
5045separate arguments to the linker. In addition pragma Link_With allows
5046multiple arguments, with the same effect as successive pragmas.
5047
5048@node Pragma Linker_Alias,Pragma Linker_Constructor,Pragma Link_With,Implementation Defined Pragmas
5049@anchor{gnat_rm/implementation_defined_pragmas pragma-linker-alias}@anchor{8f}
5050@section Pragma Linker_Alias
5051
5052
5053Syntax:
5054
5055@example
5056pragma Linker_Alias (
5057  [Entity =>] LOCAL_NAME,
5058  [Target =>] static_string_EXPRESSION);
5059@end example
5060
5061@code{LOCAL_NAME} must refer to an object that is declared at the library
5062level. This pragma establishes the given entity as a linker alias for the
5063given target. It is equivalent to @code{__attribute__((alias))} in GNU C
5064and causes @code{LOCAL_NAME} to be emitted as an alias for the symbol
5065@code{static_string_EXPRESSION} in the object file, that is to say no space
5066is reserved for @code{LOCAL_NAME} by the assembler and it will be resolved
5067to the same address as @code{static_string_EXPRESSION} by the linker.
5068
5069The actual linker name for the target must be used (e.g., the fully
5070encoded name with qualification in Ada, or the mangled name in C++),
5071or it must be declared using the C convention with @code{pragma Import}
5072or @code{pragma Export}.
5073
5074Not all target machines support this pragma. On some of them it is accepted
5075only if @code{pragma Weak_External} has been applied to @code{LOCAL_NAME}.
5076
5077@example
5078--  Example of the use of pragma Linker_Alias
5079
5080package p is
5081  i : Integer := 1;
5082  pragma Export (C, i);
5083
5084  new_name_for_i : Integer;
5085  pragma Linker_Alias (new_name_for_i, "i");
5086end p;
5087@end example
5088
5089@node Pragma Linker_Constructor,Pragma Linker_Destructor,Pragma Linker_Alias,Implementation Defined Pragmas
5090@anchor{gnat_rm/implementation_defined_pragmas pragma-linker-constructor}@anchor{90}
5091@section Pragma Linker_Constructor
5092
5093
5094Syntax:
5095
5096@example
5097pragma Linker_Constructor (procedure_LOCAL_NAME);
5098@end example
5099
5100@code{procedure_LOCAL_NAME} must refer to a parameterless procedure that
5101is declared at the library level. A procedure to which this pragma is
5102applied will be treated as an initialization routine by the linker.
5103It is equivalent to @code{__attribute__((constructor))} in GNU C and
5104causes @code{procedure_LOCAL_NAME} to be invoked before the entry point
5105of the executable is called (or immediately after the shared library is
5106loaded if the procedure is linked in a shared library), in particular
5107before the Ada run-time environment is set up.
5108
5109Because of these specific contexts, the set of operations such a procedure
5110can perform is very limited and the type of objects it can manipulate is
5111essentially restricted to the elementary types. In particular, it must only
5112contain code to which pragma Restrictions (No_Elaboration_Code) applies.
5113
5114This pragma is used by GNAT to implement auto-initialization of shared Stand
5115Alone Libraries, which provides a related capability without the restrictions
5116listed above. Where possible, the use of Stand Alone Libraries is preferable
5117to the use of this pragma.
5118
5119@node Pragma Linker_Destructor,Pragma Linker_Section,Pragma Linker_Constructor,Implementation Defined Pragmas
5120@anchor{gnat_rm/implementation_defined_pragmas pragma-linker-destructor}@anchor{91}
5121@section Pragma Linker_Destructor
5122
5123
5124Syntax:
5125
5126@example
5127pragma Linker_Destructor (procedure_LOCAL_NAME);
5128@end example
5129
5130@code{procedure_LOCAL_NAME} must refer to a parameterless procedure that
5131is declared at the library level. A procedure to which this pragma is
5132applied will be treated as a finalization routine by the linker.
5133It is equivalent to @code{__attribute__((destructor))} in GNU C and
5134causes @code{procedure_LOCAL_NAME} to be invoked after the entry point
5135of the executable has exited (or immediately before the shared library
5136is unloaded if the procedure is linked in a shared library), in particular
5137after the Ada run-time environment is shut down.
5138
5139See @code{pragma Linker_Constructor} for the set of restrictions that apply
5140because of these specific contexts.
5141
5142@node Pragma Linker_Section,Pragma Lock_Free,Pragma Linker_Destructor,Implementation Defined Pragmas
5143@anchor{gnat_rm/implementation_defined_pragmas id20}@anchor{92}@anchor{gnat_rm/implementation_defined_pragmas pragma-linker-section}@anchor{93}
5144@section Pragma Linker_Section
5145
5146
5147Syntax:
5148
5149@example
5150pragma Linker_Section (
5151  [Entity  =>] LOCAL_NAME,
5152  [Section =>] static_string_EXPRESSION);
5153@end example
5154
5155@code{LOCAL_NAME} must refer to an object, type, or subprogram that is
5156declared at the library level. This pragma specifies the name of the
5157linker section for the given entity. It is equivalent to
5158@code{__attribute__((section))} in GNU C and causes @code{LOCAL_NAME} to
5159be placed in the @code{static_string_EXPRESSION} section of the
5160executable (assuming the linker doesn’t rename the section).
5161GNAT also provides an implementation defined aspect of the same name.
5162
5163In the case of specifying this aspect for a type, the effect is to
5164specify the corresponding section for all library-level objects of
5165the type that do not have an explicit linker section set. Note that
5166this only applies to whole objects, not to components of composite objects.
5167
5168In the case of a subprogram, the linker section applies to all previously
5169declared matching overloaded subprograms in the current declarative part
5170which do not already have a linker section assigned. The linker section
5171aspect is useful in this case for specifying different linker sections
5172for different elements of such an overloaded set.
5173
5174Note that an empty string specifies that no linker section is specified.
5175This is not quite the same as omitting the pragma or aspect, since it
5176can be used to specify that one element of an overloaded set of subprograms
5177has the default linker section, or that one object of a type for which a
5178linker section is specified should has the default linker section.
5179
5180The compiler normally places library-level entities in standard sections
5181depending on the class: procedures and functions generally go in the
5182@code{.text} section, initialized variables in the @code{.data} section
5183and uninitialized variables in the @code{.bss} section.
5184
5185Other, special sections may exist on given target machines to map special
5186hardware, for example I/O ports or flash memory. This pragma is a means to
5187defer the final layout of the executable to the linker, thus fully working
5188at the symbolic level with the compiler.
5189
5190Some file formats do not support arbitrary sections so not all target
5191machines support this pragma. The use of this pragma may cause a program
5192execution to be erroneous if it is used to place an entity into an
5193inappropriate section (e.g., a modified variable into the @code{.text}
5194section). See also @code{pragma Persistent_BSS}.
5195
5196@example
5197--  Example of the use of pragma Linker_Section
5198
5199package IO_Card is
5200  Port_A : Integer;
5201  pragma Volatile (Port_A);
5202  pragma Linker_Section (Port_A, ".bss.port_a");
5203
5204  Port_B : Integer;
5205  pragma Volatile (Port_B);
5206  pragma Linker_Section (Port_B, ".bss.port_b");
5207
5208  type Port_Type is new Integer with Linker_Section => ".bss";
5209  PA : Port_Type with Linker_Section => ".bss.PA";
5210  PB : Port_Type; --  ends up in linker section ".bss"
5211
5212  procedure Q with Linker_Section => "Qsection";
5213end IO_Card;
5214@end example
5215
5216@node Pragma Lock_Free,Pragma Loop_Invariant,Pragma Linker_Section,Implementation Defined Pragmas
5217@anchor{gnat_rm/implementation_defined_pragmas id21}@anchor{94}@anchor{gnat_rm/implementation_defined_pragmas pragma-lock-free}@anchor{95}
5218@section Pragma Lock_Free
5219
5220
5221Syntax:
5222This pragma may be specified for protected types or objects. It specifies that
5223the implementation of protected operations must be implemented without locks.
5224Compilation fails if the compiler cannot generate lock-free code for the
5225operations.
5226
5227The current conditions required to support this pragma are:
5228
5229
5230@itemize *
5231
5232@item
5233Protected type declarations may not contain entries
5234
5235@item
5236Protected subprogram declarations may not have nonelementary parameters
5237@end itemize
5238
5239In addition, each protected subprogram body must satisfy:
5240
5241
5242@itemize *
5243
5244@item
5245May reference only one protected component
5246
5247@item
5248May not reference nonconstant entities outside the protected subprogram
5249scope.
5250
5251@item
5252May not contain address representation items, allocators, or quantified
5253expressions.
5254
5255@item
5256May not contain delay, goto, loop, or procedure-call statements.
5257
5258@item
5259May not contain exported and imported entities
5260
5261@item
5262May not dereferenced access values
5263
5264@item
5265Function calls and attribute references must be static
5266@end itemize
5267
5268@node Pragma Loop_Invariant,Pragma Loop_Optimize,Pragma Lock_Free,Implementation Defined Pragmas
5269@anchor{gnat_rm/implementation_defined_pragmas pragma-loop-invariant}@anchor{96}
5270@section Pragma Loop_Invariant
5271
5272
5273Syntax:
5274
5275@example
5276pragma Loop_Invariant ( boolean_EXPRESSION );
5277@end example
5278
5279The effect of this pragma is similar to that of pragma @code{Assert},
5280except that in an @code{Assertion_Policy} pragma, the identifier
5281@code{Loop_Invariant} is used to control whether it is ignored or checked
5282(or disabled).
5283
5284@code{Loop_Invariant} can only appear as one of the items in the sequence
5285of statements of a loop body, or nested inside block statements that
5286appear in the sequence of statements of a loop body.
5287The intention is that it be used to
5288represent a “loop invariant” assertion, i.e. something that is true each
5289time through the loop, and which can be used to show that the loop is
5290achieving its purpose.
5291
5292Multiple @code{Loop_Invariant} and @code{Loop_Variant} pragmas that
5293apply to the same loop should be grouped in the same sequence of
5294statements.
5295
5296To aid in writing such invariants, the special attribute @code{Loop_Entry}
5297may be used to refer to the value of an expression on entry to the loop. This
5298attribute can only be used within the expression of a @code{Loop_Invariant}
5299pragma. For full details, see documentation of attribute @code{Loop_Entry}.
5300
5301@node Pragma Loop_Optimize,Pragma Loop_Variant,Pragma Loop_Invariant,Implementation Defined Pragmas
5302@anchor{gnat_rm/implementation_defined_pragmas pragma-loop-optimize}@anchor{97}
5303@section Pragma Loop_Optimize
5304
5305
5306Syntax:
5307
5308@example
5309pragma Loop_Optimize (OPTIMIZATION_HINT @{, OPTIMIZATION_HINT@});
5310
5311OPTIMIZATION_HINT ::= Ivdep | No_Unroll | Unroll | No_Vector | Vector
5312@end example
5313
5314This pragma must appear immediately within a loop statement.  It allows the
5315programmer to specify optimization hints for the enclosing loop.  The hints
5316are not mutually exclusive and can be freely mixed, but not all combinations
5317will yield a sensible outcome.
5318
5319There are five supported optimization hints for a loop:
5320
5321
5322@itemize *
5323
5324@item
5325Ivdep
5326
5327The programmer asserts that there are no loop-carried dependencies
5328which would prevent consecutive iterations of the loop from being
5329executed simultaneously.
5330
5331@item
5332No_Unroll
5333
5334The loop must not be unrolled.  This is a strong hint: the compiler will not
5335unroll a loop marked with this hint.
5336
5337@item
5338Unroll
5339
5340The loop should be unrolled.  This is a weak hint: the compiler will try to
5341apply unrolling to this loop preferably to other optimizations, notably
5342vectorization, but there is no guarantee that the loop will be unrolled.
5343
5344@item
5345No_Vector
5346
5347The loop must not be vectorized.  This is a strong hint: the compiler will not
5348vectorize a loop marked with this hint.
5349
5350@item
5351Vector
5352
5353The loop should be vectorized.  This is a weak hint: the compiler will try to
5354apply vectorization to this loop preferably to other optimizations, notably
5355unrolling, but there is no guarantee that the loop will be vectorized.
5356@end itemize
5357
5358These hints do not remove the need to pass the appropriate switches to the
5359compiler in order to enable the relevant optimizations, that is to say
5360@emph{-funroll-loops} for unrolling and @emph{-ftree-vectorize} for
5361vectorization.
5362
5363@node Pragma Loop_Variant,Pragma Machine_Attribute,Pragma Loop_Optimize,Implementation Defined Pragmas
5364@anchor{gnat_rm/implementation_defined_pragmas pragma-loop-variant}@anchor{98}
5365@section Pragma Loop_Variant
5366
5367
5368Syntax:
5369
5370@example
5371pragma Loop_Variant ( LOOP_VARIANT_ITEM @{, LOOP_VARIANT_ITEM @} );
5372LOOP_VARIANT_ITEM ::= CHANGE_DIRECTION => discrete_EXPRESSION
5373CHANGE_DIRECTION ::= Increases | Decreases
5374@end example
5375
5376@code{Loop_Variant} can only appear as one of the items in the sequence
5377of statements of a loop body, or nested inside block statements that
5378appear in the sequence of statements of a loop body.
5379It allows the specification of quantities which must always
5380decrease or increase in successive iterations of the loop. In its simplest
5381form, just one expression is specified, whose value must increase or decrease
5382on each iteration of the loop.
5383
5384In a more complex form, multiple arguments can be given which are intepreted
5385in a nesting lexicographic manner. For example:
5386
5387@example
5388pragma Loop_Variant (Increases => X, Decreases => Y);
5389@end example
5390
5391specifies that each time through the loop either X increases, or X stays
5392the same and Y decreases. A @code{Loop_Variant} pragma ensures that the
5393loop is making progress. It can be useful in helping to show informally
5394or prove formally that the loop always terminates.
5395
5396@code{Loop_Variant} is an assertion whose effect can be controlled using
5397an @code{Assertion_Policy} with a check name of @code{Loop_Variant}. The
5398policy can be @code{Check} to enable the loop variant check, @code{Ignore}
5399to ignore the check (in which case the pragma has no effect on the program),
5400or @code{Disable} in which case the pragma is not even checked for correct
5401syntax.
5402
5403Multiple @code{Loop_Invariant} and @code{Loop_Variant} pragmas that
5404apply to the same loop should be grouped in the same sequence of
5405statements.
5406
5407The @code{Loop_Entry} attribute may be used within the expressions of the
5408@code{Loop_Variant} pragma to refer to values on entry to the loop.
5409
5410@node Pragma Machine_Attribute,Pragma Main,Pragma Loop_Variant,Implementation Defined Pragmas
5411@anchor{gnat_rm/implementation_defined_pragmas pragma-machine-attribute}@anchor{99}
5412@section Pragma Machine_Attribute
5413
5414
5415Syntax:
5416
5417@example
5418pragma Machine_Attribute (
5419     [Entity         =>] LOCAL_NAME,
5420     [Attribute_Name =>] static_string_EXPRESSION
5421  [, [Info           =>] static_EXPRESSION @{, static_EXPRESSION@}] );
5422@end example
5423
5424Machine-dependent attributes can be specified for types and/or
5425declarations.  This pragma is semantically equivalent to
5426@code{__attribute__((@emph{attribute_name}))} (if @code{info} is not
5427specified) or @code{__attribute__((@emph{attribute_name(info})))}
5428or @code{__attribute__((@emph{attribute_name(info,...})))} in GNU C,
5429where @emph{attribute_name} is recognized by the compiler middle-end
5430or the @code{TARGET_ATTRIBUTE_TABLE} machine specific macro.  Note
5431that a string literal for the optional parameter @code{info} or the
5432following ones is transformed by default into an identifier,
5433which may make this pragma unusable for some attributes.
5434For further information see @cite{GNU Compiler Collection (GCC) Internals}.
5435
5436@node Pragma Main,Pragma Main_Storage,Pragma Machine_Attribute,Implementation Defined Pragmas
5437@anchor{gnat_rm/implementation_defined_pragmas pragma-main}@anchor{9a}
5438@section Pragma Main
5439
5440
5441Syntax:
5442
5443@example
5444pragma Main
5445 (MAIN_OPTION [, MAIN_OPTION]);
5446
5447MAIN_OPTION ::=
5448  [Stack_Size              =>] static_integer_EXPRESSION
5449| [Task_Stack_Size_Default =>] static_integer_EXPRESSION
5450| [Time_Slicing_Enabled    =>] static_boolean_EXPRESSION
5451@end example
5452
5453This pragma is provided for compatibility with OpenVMS VAX Systems.  It has
5454no effect in GNAT, other than being syntax checked.
5455
5456@node Pragma Main_Storage,Pragma Max_Queue_Length,Pragma Main,Implementation Defined Pragmas
5457@anchor{gnat_rm/implementation_defined_pragmas pragma-main-storage}@anchor{9b}
5458@section Pragma Main_Storage
5459
5460
5461Syntax:
5462
5463@example
5464pragma Main_Storage
5465  (MAIN_STORAGE_OPTION [, MAIN_STORAGE_OPTION]);
5466
5467MAIN_STORAGE_OPTION ::=
5468  [WORKING_STORAGE =>] static_SIMPLE_EXPRESSION
5469| [TOP_GUARD       =>] static_SIMPLE_EXPRESSION
5470@end example
5471
5472This pragma is provided for compatibility with OpenVMS VAX Systems.  It has
5473no effect in GNAT, other than being syntax checked.
5474
5475@node Pragma Max_Queue_Length,Pragma No_Body,Pragma Main_Storage,Implementation Defined Pragmas
5476@anchor{gnat_rm/implementation_defined_pragmas id22}@anchor{9c}@anchor{gnat_rm/implementation_defined_pragmas pragma-max-queue-length}@anchor{9d}
5477@section Pragma Max_Queue_Length
5478
5479
5480Syntax:
5481
5482@example
5483pragma Max_Entry_Queue (static_integer_EXPRESSION);
5484@end example
5485
5486This pragma is used to specify the maximum callers per entry queue for
5487individual protected entries and entry families. It accepts a single
5488integer (-1 or more) as a parameter and must appear after the declaration of an
5489entry.
5490
5491A value of -1 represents no additional restriction on queue length.
5492
5493@node Pragma No_Body,Pragma No_Caching,Pragma Max_Queue_Length,Implementation Defined Pragmas
5494@anchor{gnat_rm/implementation_defined_pragmas pragma-no-body}@anchor{9e}
5495@section Pragma No_Body
5496
5497
5498Syntax:
5499
5500@example
5501pragma No_Body;
5502@end example
5503
5504There are a number of cases in which a package spec does not require a body,
5505and in fact a body is not permitted. GNAT will not permit the spec to be
5506compiled if there is a body around. The pragma No_Body allows you to provide
5507a body file, even in a case where no body is allowed. The body file must
5508contain only comments and a single No_Body pragma. This is recognized by
5509the compiler as indicating that no body is logically present.
5510
5511This is particularly useful during maintenance when a package is modified in
5512such a way that a body needed before is no longer needed. The provision of a
5513dummy body with a No_Body pragma ensures that there is no interference from
5514earlier versions of the package body.
5515
5516@node Pragma No_Caching,Pragma No_Component_Reordering,Pragma No_Body,Implementation Defined Pragmas
5517@anchor{gnat_rm/implementation_defined_pragmas id23}@anchor{9f}@anchor{gnat_rm/implementation_defined_pragmas pragma-no-caching}@anchor{a0}
5518@section Pragma No_Caching
5519
5520
5521Syntax:
5522
5523@example
5524pragma No_Caching [ (boolean_EXPRESSION) ];
5525@end example
5526
5527For the semantics of this pragma, see the entry for aspect @code{No_Caching} in
5528the SPARK 2014 Reference Manual, section 7.1.2.
5529
5530@node Pragma No_Component_Reordering,Pragma No_Elaboration_Code_All,Pragma No_Caching,Implementation Defined Pragmas
5531@anchor{gnat_rm/implementation_defined_pragmas pragma-no-component-reordering}@anchor{a1}
5532@section Pragma No_Component_Reordering
5533
5534
5535Syntax:
5536
5537@example
5538pragma No_Component_Reordering [([Entity =>] type_LOCAL_NAME)];
5539@end example
5540
5541@code{type_LOCAL_NAME} must refer to a record type declaration in the current
5542declarative part. The effect is to preclude any reordering of components
5543for the layout of the record, i.e. the record is laid out by the compiler
5544in the order in which the components are declared textually. The form with
5545no argument is a configuration pragma which applies to all record types
5546declared in units to which the pragma applies and there is a requirement
5547that this pragma be used consistently within a partition.
5548
5549@node Pragma No_Elaboration_Code_All,Pragma No_Heap_Finalization,Pragma No_Component_Reordering,Implementation Defined Pragmas
5550@anchor{gnat_rm/implementation_defined_pragmas id24}@anchor{a2}@anchor{gnat_rm/implementation_defined_pragmas pragma-no-elaboration-code-all}@anchor{a3}
5551@section Pragma No_Elaboration_Code_All
5552
5553
5554Syntax:
5555
5556@example
5557pragma No_Elaboration_Code_All [(program_unit_NAME)];
5558@end example
5559
5560This is a program unit pragma (there is also an equivalent aspect of the
5561same name) that establishes the restriction @code{No_Elaboration_Code} for
5562the current unit and any extended main source units (body and subunits).
5563It also has the effect of enforcing a transitive application of this
5564aspect, so that if any unit is implicitly or explicitly with’ed by the
5565current unit, it must also have the No_Elaboration_Code_All aspect set.
5566It may be applied to package or subprogram specs or their generic versions.
5567
5568@node Pragma No_Heap_Finalization,Pragma No_Inline,Pragma No_Elaboration_Code_All,Implementation Defined Pragmas
5569@anchor{gnat_rm/implementation_defined_pragmas pragma-no-heap-finalization}@anchor{a4}
5570@section Pragma No_Heap_Finalization
5571
5572
5573Syntax:
5574
5575@example
5576pragma No_Heap_Finalization [ (first_subtype_LOCAL_NAME) ];
5577@end example
5578
5579Pragma @code{No_Heap_Finalization} may be used as a configuration pragma or as a
5580type-specific pragma.
5581
5582In its configuration form, the pragma must appear within a configuration file
5583such as gnat.adc, without an argument. The pragma suppresses the call to
5584@code{Finalize} for heap-allocated objects created through library-level named
5585access-to-object types in cases where the designated type requires finalization
5586actions.
5587
5588In its type-specific form, the argument of the pragma must denote a
5589library-level named access-to-object type. The pragma suppresses the call to
5590@code{Finalize} for heap-allocated objects created through the specific access type
5591in cases where the designated type requires finalization actions.
5592
5593It is still possible to finalize such heap-allocated objects by explicitly
5594deallocating them.
5595
5596A library-level named access-to-object type declared within a generic unit will
5597lose its @code{No_Heap_Finalization} pragma when the corresponding instance does not
5598appear at the library level.
5599
5600@node Pragma No_Inline,Pragma No_Return,Pragma No_Heap_Finalization,Implementation Defined Pragmas
5601@anchor{gnat_rm/implementation_defined_pragmas id25}@anchor{a5}@anchor{gnat_rm/implementation_defined_pragmas pragma-no-inline}@anchor{a6}
5602@section Pragma No_Inline
5603
5604
5605Syntax:
5606
5607@example
5608pragma No_Inline (NAME @{, NAME@});
5609@end example
5610
5611This pragma suppresses inlining for the callable entity or the instances of
5612the generic subprogram designated by @code{NAME}, including inlining that
5613results from the use of pragma @code{Inline}.  This pragma is always active,
5614in particular it is not subject to the use of option @emph{-gnatn} or
5615@emph{-gnatN}.  It is illegal to specify both pragma @code{No_Inline} and
5616pragma @code{Inline_Always} for the same @code{NAME}.
5617
5618@node Pragma No_Return,Pragma No_Strict_Aliasing,Pragma No_Inline,Implementation Defined Pragmas
5619@anchor{gnat_rm/implementation_defined_pragmas pragma-no-return}@anchor{a7}
5620@section Pragma No_Return
5621
5622
5623Syntax:
5624
5625@example
5626pragma No_Return (procedure_LOCAL_NAME @{, procedure_LOCAL_NAME@});
5627@end example
5628
5629Each @code{procedure_LOCAL_NAME} argument must refer to one or more procedure
5630declarations in the current declarative part.  A procedure to which this
5631pragma is applied may not contain any explicit @code{return} statements.
5632In addition, if the procedure contains any implicit returns from falling
5633off the end of a statement sequence, then execution of that implicit
5634return will cause Program_Error to be raised.
5635
5636One use of this pragma is to identify procedures whose only purpose is to raise
5637an exception. Another use of this pragma is to suppress incorrect warnings
5638about missing returns in functions, where the last statement of a function
5639statement sequence is a call to such a procedure.
5640
5641Note that in Ada 2005 mode, this pragma is part of the language. It is
5642available in all earlier versions of Ada as an implementation-defined
5643pragma.
5644
5645@node Pragma No_Strict_Aliasing,Pragma No_Tagged_Streams,Pragma No_Return,Implementation Defined Pragmas
5646@anchor{gnat_rm/implementation_defined_pragmas pragma-no-strict-aliasing}@anchor{a8}
5647@section Pragma No_Strict_Aliasing
5648
5649
5650Syntax:
5651
5652@example
5653pragma No_Strict_Aliasing [([Entity =>] type_LOCAL_NAME)];
5654@end example
5655
5656@code{type_LOCAL_NAME} must refer to an access type
5657declaration in the current declarative part.  The effect is to inhibit
5658strict aliasing optimization for the given type.  The form with no
5659arguments is a configuration pragma which applies to all access types
5660declared in units to which the pragma applies. For a detailed
5661description of the strict aliasing optimization, and the situations
5662in which it must be suppressed, see the section on Optimization and Strict Aliasing
5663in the @cite{GNAT User’s Guide}.
5664
5665This pragma currently has no effects on access to unconstrained array types.
5666
5667@node Pragma No_Tagged_Streams,Pragma Normalize_Scalars,Pragma No_Strict_Aliasing,Implementation Defined Pragmas
5668@anchor{gnat_rm/implementation_defined_pragmas id26}@anchor{a9}@anchor{gnat_rm/implementation_defined_pragmas pragma-no-tagged-streams}@anchor{aa}
5669@section Pragma No_Tagged_Streams
5670
5671
5672Syntax:
5673
5674@example
5675pragma No_Tagged_Streams [([Entity =>] tagged_type_LOCAL_NAME)];
5676@end example
5677
5678Normally when a tagged type is introduced using a full type declaration,
5679part of the processing includes generating stream access routines to be
5680used by stream attributes referencing the type (or one of its subtypes
5681or derived types). This can involve the generation of significant amounts
5682of code which is wasted space if stream routines are not needed for the
5683type in question.
5684
5685The @code{No_Tagged_Streams} pragma causes the generation of these stream
5686routines to be skipped, and any attempt to use stream operations on
5687types subject to this pragma will be statically rejected as illegal.
5688
5689There are two forms of the pragma. The form with no arguments must appear
5690in a declarative sequence or in the declarations of a package spec. This
5691pragma affects all subsequent root tagged types declared in the declaration
5692sequence, and specifies that no stream routines be generated. The form with
5693an argument (for which there is also a corresponding aspect) specifies a
5694single root tagged type for which stream routines are not to be generated.
5695
5696Once the pragma has been given for a particular root tagged type, all subtypes
5697and derived types of this type inherit the pragma automatically, so the effect
5698applies to a complete hierarchy (this is necessary to deal with the class-wide
5699dispatching versions of the stream routines).
5700
5701When pragmas @code{Discard_Names} and @code{No_Tagged_Streams} are simultaneously
5702applied to a tagged type its Expanded_Name and External_Tag are initialized
5703with empty strings. This is useful to avoid exposing entity names at binary
5704level but has a negative impact on the debuggability of tagged types.
5705
5706@node Pragma Normalize_Scalars,Pragma Obsolescent,Pragma No_Tagged_Streams,Implementation Defined Pragmas
5707@anchor{gnat_rm/implementation_defined_pragmas pragma-normalize-scalars}@anchor{ab}
5708@section Pragma Normalize_Scalars
5709
5710
5711Syntax:
5712
5713@example
5714pragma Normalize_Scalars;
5715@end example
5716
5717This is a language defined pragma which is fully implemented in GNAT.  The
5718effect is to cause all scalar objects that are not otherwise initialized
5719to be initialized.  The initial values are implementation dependent and
5720are as follows:
5721
5722
5723@table @asis
5724
5725@item @emph{Standard.Character}
5726
5727Objects whose root type is Standard.Character are initialized to
5728Character’Last unless the subtype range excludes NUL (in which case
5729NUL is used). This choice will always generate an invalid value if
5730one exists.
5731
5732@item @emph{Standard.Wide_Character}
5733
5734Objects whose root type is Standard.Wide_Character are initialized to
5735Wide_Character’Last unless the subtype range excludes NUL (in which case
5736NUL is used). This choice will always generate an invalid value if
5737one exists.
5738
5739@item @emph{Standard.Wide_Wide_Character}
5740
5741Objects whose root type is Standard.Wide_Wide_Character are initialized to
5742the invalid value 16#FFFF_FFFF# unless the subtype range excludes NUL (in
5743which case NUL is used). This choice will always generate an invalid value if
5744one exists.
5745
5746@item @emph{Integer types}
5747
5748Objects of an integer type are treated differently depending on whether
5749negative values are present in the subtype. If no negative values are
5750present, then all one bits is used as the initial value except in the
5751special case where zero is excluded from the subtype, in which case
5752all zero bits are used. This choice will always generate an invalid
5753value if one exists.
5754
5755For subtypes with negative values present, the largest negative number
5756is used, except in the unusual case where this largest negative number
5757is in the subtype, and the largest positive number is not, in which case
5758the largest positive value is used. This choice will always generate
5759an invalid value if one exists.
5760
5761@item @emph{Floating-Point Types}
5762
5763Objects of all floating-point types are initialized to all 1-bits. For
5764standard IEEE format, this corresponds to a NaN (not a number) which is
5765indeed an invalid value.
5766
5767@item @emph{Fixed-Point Types}
5768
5769Objects of all fixed-point types are treated as described above for integers,
5770with the rules applying to the underlying integer value used to represent
5771the fixed-point value.
5772
5773@item @emph{Modular types}
5774
5775Objects of a modular type are initialized to all one bits, except in
5776the special case where zero is excluded from the subtype, in which
5777case all zero bits are used. This choice will always generate an
5778invalid value if one exists.
5779
5780@item @emph{Enumeration types}
5781
5782Objects of an enumeration type are initialized to all one-bits, i.e., to
5783the value @code{2 ** typ'Size - 1} unless the subtype excludes the literal
5784whose Pos value is zero, in which case a code of zero is used. This choice
5785will always generate an invalid value if one exists.
5786@end table
5787
5788@node Pragma Obsolescent,Pragma Optimize_Alignment,Pragma Normalize_Scalars,Implementation Defined Pragmas
5789@anchor{gnat_rm/implementation_defined_pragmas id27}@anchor{ac}@anchor{gnat_rm/implementation_defined_pragmas pragma-obsolescent}@anchor{ad}
5790@section Pragma Obsolescent
5791
5792
5793Syntax:
5794
5795@example
5796pragma Obsolescent;
5797
5798pragma Obsolescent (
5799  [Message =>] static_string_EXPRESSION
5800[,[Version =>] Ada_05]]);
5801
5802pragma Obsolescent (
5803  [Entity  =>] NAME
5804[,[Message =>] static_string_EXPRESSION
5805[,[Version =>] Ada_05]] );
5806@end example
5807
5808This pragma can occur immediately following a declaration of an entity,
5809including the case of a record component. If no Entity argument is present,
5810then this declaration is the one to which the pragma applies. If an Entity
5811parameter is present, it must either match the name of the entity in this
5812declaration, or alternatively, the pragma can immediately follow an enumeration
5813type declaration, where the Entity argument names one of the enumeration
5814literals.
5815
5816This pragma is used to indicate that the named entity
5817is considered obsolescent and should not be used. Typically this is
5818used when an API must be modified by eventually removing or modifying
5819existing subprograms or other entities. The pragma can be used at an
5820intermediate stage when the entity is still present, but will be
5821removed later.
5822
5823The effect of this pragma is to output a warning message on a reference to
5824an entity thus marked that the subprogram is obsolescent if the appropriate
5825warning option in the compiler is activated. If the @code{Message} parameter is
5826present, then a second warning message is given containing this text. In
5827addition, a reference to the entity is considered to be a violation of pragma
5828@code{Restrictions (No_Obsolescent_Features)}.
5829
5830This pragma can also be used as a program unit pragma for a package,
5831in which case the entity name is the name of the package, and the
5832pragma indicates that the entire package is considered
5833obsolescent. In this case a client @code{with}ing such a package
5834violates the restriction, and the @code{with} clause is
5835flagged with warnings if the warning option is set.
5836
5837If the @code{Version} parameter is present (which must be exactly
5838the identifier @code{Ada_05}, no other argument is allowed), then the
5839indication of obsolescence applies only when compiling in Ada 2005
5840mode. This is primarily intended for dealing with the situations
5841in the predefined library where subprograms or packages
5842have become defined as obsolescent in Ada 2005
5843(e.g., in @code{Ada.Characters.Handling}), but may be used anywhere.
5844
5845The following examples show typical uses of this pragma:
5846
5847@example
5848package p is
5849   pragma Obsolescent (p, Message => "use pp instead of p");
5850end p;
5851
5852package q is
5853   procedure q2;
5854   pragma Obsolescent ("use q2new instead");
5855
5856   type R is new integer;
5857   pragma Obsolescent
5858     (Entity  => R,
5859      Message => "use RR in Ada 2005",
5860      Version => Ada_05);
5861
5862   type M is record
5863      F1 : Integer;
5864      F2 : Integer;
5865      pragma Obsolescent;
5866      F3 : Integer;
5867   end record;
5868
5869   type E is (a, bc, 'd', quack);
5870   pragma Obsolescent (Entity => bc)
5871   pragma Obsolescent (Entity => 'd')
5872
5873   function "+"
5874     (a, b : character) return character;
5875   pragma Obsolescent (Entity => "+");
5876end;
5877@end example
5878
5879Note that, as for all pragmas, if you use a pragma argument identifier,
5880then all subsequent parameters must also use a pragma argument identifier.
5881So if you specify @code{Entity =>} for the @code{Entity} argument, and a @code{Message}
5882argument is present, it must be preceded by @code{Message =>}.
5883
5884@node Pragma Optimize_Alignment,Pragma Ordered,Pragma Obsolescent,Implementation Defined Pragmas
5885@anchor{gnat_rm/implementation_defined_pragmas pragma-optimize-alignment}@anchor{ae}
5886@section Pragma Optimize_Alignment
5887
5888
5889@geindex Alignment
5890@geindex default settings
5891
5892Syntax:
5893
5894@example
5895pragma Optimize_Alignment (TIME | SPACE | OFF);
5896@end example
5897
5898This is a configuration pragma which affects the choice of default alignments
5899for types and objects where no alignment is explicitly specified. There is a
5900time/space trade-off in the selection of these values. Large alignments result
5901in more efficient code, at the expense of larger data space, since sizes have
5902to be increased to match these alignments. Smaller alignments save space, but
5903the access code is slower. The normal choice of default alignments for types
5904and individual alignment promotions for objects (which is what you get if you
5905do not use this pragma, or if you use an argument of OFF), tries to balance
5906these two requirements.
5907
5908Specifying SPACE causes smaller default alignments to be chosen in two cases.
5909First any packed record is given an alignment of 1. Second, if a size is given
5910for the type, then the alignment is chosen to avoid increasing this size. For
5911example, consider:
5912
5913@example
5914type R is record
5915   X : Integer;
5916   Y : Character;
5917end record;
5918
5919for R'Size use 5*8;
5920@end example
5921
5922In the default mode, this type gets an alignment of 4, so that access to the
5923Integer field X are efficient. But this means that objects of the type end up
5924with a size of 8 bytes. This is a valid choice, since sizes of objects are
5925allowed to be bigger than the size of the type, but it can waste space if for
5926example fields of type R appear in an enclosing record. If the above type is
5927compiled in @code{Optimize_Alignment (Space)} mode, the alignment is set to 1.
5928
5929However, there is one case in which SPACE is ignored. If a variable length
5930record (that is a discriminated record with a component which is an array
5931whose length depends on a discriminant), has a pragma Pack, then it is not
5932in general possible to set the alignment of such a record to one, so the
5933pragma is ignored in this case (with a warning).
5934
5935Specifying SPACE also disables alignment promotions for standalone objects,
5936which occur when the compiler increases the alignment of a specific object
5937without changing the alignment of its type.
5938
5939Specifying SPACE also disables component reordering in unpacked record types,
5940which can result in larger sizes in order to meet alignment requirements.
5941
5942Specifying TIME causes larger default alignments to be chosen in the case of
5943small types with sizes that are not a power of 2. For example, consider:
5944
5945@example
5946type R is record
5947   A : Character;
5948   B : Character;
5949   C : Boolean;
5950end record;
5951
5952pragma Pack (R);
5953for R'Size use 17;
5954@end example
5955
5956The default alignment for this record is normally 1, but if this type is
5957compiled in @code{Optimize_Alignment (Time)} mode, then the alignment is set
5958to 4, which wastes space for objects of the type, since they are now 4 bytes
5959long, but results in more efficient access when the whole record is referenced.
5960
5961As noted above, this is a configuration pragma, and there is a requirement
5962that all units in a partition be compiled with a consistent setting of the
5963optimization setting. This would normally be achieved by use of a configuration
5964pragma file containing the appropriate setting. The exception to this rule is
5965that units with an explicit configuration pragma in the same file as the source
5966unit are excluded from the consistency check, as are all predefined units. The
5967latter are compiled by default in pragma Optimize_Alignment (Off) mode if no
5968pragma appears at the start of the file.
5969
5970@node Pragma Ordered,Pragma Overflow_Mode,Pragma Optimize_Alignment,Implementation Defined Pragmas
5971@anchor{gnat_rm/implementation_defined_pragmas pragma-ordered}@anchor{af}
5972@section Pragma Ordered
5973
5974
5975Syntax:
5976
5977@example
5978pragma Ordered (enumeration_first_subtype_LOCAL_NAME);
5979@end example
5980
5981Most enumeration types are from a conceptual point of view unordered.
5982For example, consider:
5983
5984@example
5985type Color is (Red, Blue, Green, Yellow);
5986@end example
5987
5988By Ada semantics @code{Blue > Red} and @code{Green > Blue},
5989but really these relations make no sense; the enumeration type merely
5990specifies a set of possible colors, and the order is unimportant.
5991
5992For unordered enumeration types, it is generally a good idea if
5993clients avoid comparisons (other than equality or inequality) and
5994explicit ranges. (A @emph{client} is a unit where the type is referenced,
5995other than the unit where the type is declared, its body, and its subunits.)
5996For example, if code buried in some client says:
5997
5998@example
5999if Current_Color < Yellow then ...
6000if Current_Color in Blue .. Green then ...
6001@end example
6002
6003then the client code is relying on the order, which is undesirable.
6004It makes the code hard to read and creates maintenance difficulties if
6005entries have to be added to the enumeration type. Instead,
6006the code in the client should list the possibilities, or an
6007appropriate subtype should be declared in the unit that declares
6008the original enumeration type. E.g., the following subtype could
6009be declared along with the type @code{Color}:
6010
6011@example
6012subtype RBG is Color range Red .. Green;
6013@end example
6014
6015and then the client could write:
6016
6017@example
6018if Current_Color in RBG then ...
6019if Current_Color = Blue or Current_Color = Green then ...
6020@end example
6021
6022However, some enumeration types are legitimately ordered from a conceptual
6023point of view. For example, if you declare:
6024
6025@example
6026type Day is (Mon, Tue, Wed, Thu, Fri, Sat, Sun);
6027@end example
6028
6029then the ordering imposed by the language is reasonable, and
6030clients can depend on it, writing for example:
6031
6032@example
6033if D in Mon .. Fri then ...
6034if D < Wed then ...
6035@end example
6036
6037The pragma @emph{Ordered} is provided to mark enumeration types that
6038are conceptually ordered, alerting the reader that clients may depend
6039on the ordering. GNAT provides a pragma to mark enumerations as ordered
6040rather than one to mark them as unordered, since in our experience,
6041the great majority of enumeration types are conceptually unordered.
6042
6043The types @code{Boolean}, @code{Character}, @code{Wide_Character},
6044and @code{Wide_Wide_Character}
6045are considered to be ordered types, so each is declared with a
6046pragma @code{Ordered} in package @code{Standard}.
6047
6048Normally pragma @code{Ordered} serves only as documentation and a guide for
6049coding standards, but GNAT provides a warning switch @emph{-gnatw.u} that
6050requests warnings for inappropriate uses (comparisons and explicit
6051subranges) for unordered types. If this switch is used, then any
6052enumeration type not marked with pragma @code{Ordered} will be considered
6053as unordered, and will generate warnings for inappropriate uses.
6054
6055Note that generic types are not considered ordered or unordered (since the
6056template can be instantiated for both cases), so we never generate warnings
6057for the case of generic enumerated types.
6058
6059For additional information please refer to the description of the
6060@emph{-gnatw.u} switch in the GNAT User’s Guide.
6061
6062@node Pragma Overflow_Mode,Pragma Overriding_Renamings,Pragma Ordered,Implementation Defined Pragmas
6063@anchor{gnat_rm/implementation_defined_pragmas pragma-overflow-mode}@anchor{b0}
6064@section Pragma Overflow_Mode
6065
6066
6067Syntax:
6068
6069@example
6070pragma Overflow_Mode
6071 (  [General    =>] MODE
6072  [,[Assertions =>] MODE]);
6073
6074MODE ::= STRICT | MINIMIZED | ELIMINATED
6075@end example
6076
6077This pragma sets the current overflow mode to the given setting. For details
6078of the meaning of these modes, please refer to the
6079‘Overflow Check Handling in GNAT’ appendix in the
6080GNAT User’s Guide. If only the @code{General} parameter is present,
6081the given mode applies to all expressions. If both parameters are present,
6082the @code{General} mode applies to expressions outside assertions, and
6083the @code{Eliminated} mode applies to expressions within assertions.
6084
6085The case of the @code{MODE} parameter is ignored,
6086so @code{MINIMIZED}, @code{Minimized} and
6087@code{minimized} all have the same effect.
6088
6089The @code{Overflow_Mode} pragma has the same scoping and placement
6090rules as pragma @code{Suppress}, so it can occur either as a
6091configuration pragma, specifying a default for the whole
6092program, or in a declarative scope, where it applies to the
6093remaining declarations and statements in that scope.
6094
6095The pragma @code{Suppress (Overflow_Check)} suppresses
6096overflow checking, but does not affect the overflow mode.
6097
6098The pragma @code{Unsuppress (Overflow_Check)} unsuppresses (enables)
6099overflow checking, but does not affect the overflow mode.
6100
6101@node Pragma Overriding_Renamings,Pragma Partition_Elaboration_Policy,Pragma Overflow_Mode,Implementation Defined Pragmas
6102@anchor{gnat_rm/implementation_defined_pragmas pragma-overriding-renamings}@anchor{b1}
6103@section Pragma Overriding_Renamings
6104
6105
6106@geindex Rational profile
6107
6108@geindex Rational compatibility
6109
6110Syntax:
6111
6112@example
6113pragma Overriding_Renamings;
6114@end example
6115
6116This is a GNAT configuration pragma to simplify porting
6117legacy code accepted by the Rational
6118Ada compiler. In the presence of this pragma, a renaming declaration that
6119renames an inherited operation declared in the same scope is legal if selected
6120notation is used as in:
6121
6122@example
6123pragma Overriding_Renamings;
6124...
6125package R is
6126  function F (..);
6127  ...
6128  function F (..) renames R.F;
6129end R;
6130@end example
6131
6132even though
6133RM 8.3 (15) stipulates that an overridden operation is not visible within the
6134declaration of the overriding operation.
6135
6136@node Pragma Partition_Elaboration_Policy,Pragma Part_Of,Pragma Overriding_Renamings,Implementation Defined Pragmas
6137@anchor{gnat_rm/implementation_defined_pragmas pragma-partition-elaboration-policy}@anchor{b2}
6138@section Pragma Partition_Elaboration_Policy
6139
6140
6141Syntax:
6142
6143@example
6144pragma Partition_Elaboration_Policy (POLICY_IDENTIFIER);
6145
6146POLICY_IDENTIFIER ::= Concurrent | Sequential
6147@end example
6148
6149This pragma is standard in Ada 2005, but is available in all earlier
6150versions of Ada as an implementation-defined pragma.
6151See Ada 2012 Reference Manual for details.
6152
6153@node Pragma Part_Of,Pragma Passive,Pragma Partition_Elaboration_Policy,Implementation Defined Pragmas
6154@anchor{gnat_rm/implementation_defined_pragmas id28}@anchor{b3}@anchor{gnat_rm/implementation_defined_pragmas pragma-part-of}@anchor{b4}
6155@section Pragma Part_Of
6156
6157
6158Syntax:
6159
6160@example
6161pragma Part_Of (ABSTRACT_STATE);
6162
6163ABSTRACT_STATE ::= NAME
6164@end example
6165
6166For the semantics of this pragma, see the entry for aspect @code{Part_Of} in the
6167SPARK 2014 Reference Manual, section 7.2.6.
6168
6169@node Pragma Passive,Pragma Persistent_BSS,Pragma Part_Of,Implementation Defined Pragmas
6170@anchor{gnat_rm/implementation_defined_pragmas pragma-passive}@anchor{b5}
6171@section Pragma Passive
6172
6173
6174Syntax:
6175
6176@example
6177pragma Passive [(Semaphore | No)];
6178@end example
6179
6180Syntax checked, but otherwise ignored by GNAT.  This is recognized for
6181compatibility with DEC Ada 83 implementations, where it is used within a
6182task definition to request that a task be made passive.  If the argument
6183@code{Semaphore} is present, or the argument is omitted, then DEC Ada 83
6184treats the pragma as an assertion that the containing task is passive
6185and that optimization of context switch with this task is permitted and
6186desired.  If the argument @code{No} is present, the task must not be
6187optimized.  GNAT does not attempt to optimize any tasks in this manner
6188(since protected objects are available in place of passive tasks).
6189
6190For more information on the subject of passive tasks, see the section
6191‘Passive Task Optimization’ in the GNAT Users Guide.
6192
6193@node Pragma Persistent_BSS,Pragma Post,Pragma Passive,Implementation Defined Pragmas
6194@anchor{gnat_rm/implementation_defined_pragmas id29}@anchor{b6}@anchor{gnat_rm/implementation_defined_pragmas pragma-persistent-bss}@anchor{b7}
6195@section Pragma Persistent_BSS
6196
6197
6198Syntax:
6199
6200@example
6201pragma Persistent_BSS [(LOCAL_NAME)]
6202@end example
6203
6204This pragma allows selected objects to be placed in the @code{.persistent_bss}
6205section. On some targets the linker and loader provide for special
6206treatment of this section, allowing a program to be reloaded without
6207affecting the contents of this data (hence the name persistent).
6208
6209There are two forms of usage. If an argument is given, it must be the
6210local name of a library-level object, with no explicit initialization
6211and whose type is potentially persistent. If no argument is given, then
6212the pragma is a configuration pragma, and applies to all library-level
6213objects with no explicit initialization of potentially persistent types.
6214
6215A potentially persistent type is a scalar type, or an untagged,
6216non-discriminated record, all of whose components have no explicit
6217initialization and are themselves of a potentially persistent type,
6218or an array, all of whose constraints are static, and whose component
6219type is potentially persistent.
6220
6221If this pragma is used on a target where this feature is not supported,
6222then the pragma will be ignored. See also @code{pragma Linker_Section}.
6223
6224@node Pragma Post,Pragma Postcondition,Pragma Persistent_BSS,Implementation Defined Pragmas
6225@anchor{gnat_rm/implementation_defined_pragmas pragma-post}@anchor{b8}
6226@section Pragma Post
6227
6228
6229@geindex Post
6230
6231@geindex Checks
6232@geindex postconditions
6233
6234Syntax:
6235
6236@example
6237pragma Post (Boolean_Expression);
6238@end example
6239
6240The @code{Post} pragma is intended to be an exact replacement for
6241the language-defined
6242@code{Post} aspect, and shares its restrictions and semantics.
6243It must appear either immediately following the corresponding
6244subprogram declaration (only other pragmas may intervene), or
6245if there is no separate subprogram declaration, then it can
6246appear at the start of the declarations in a subprogram body
6247(preceded only by other pragmas).
6248
6249@node Pragma Postcondition,Pragma Post_Class,Pragma Post,Implementation Defined Pragmas
6250@anchor{gnat_rm/implementation_defined_pragmas pragma-postcondition}@anchor{b9}
6251@section Pragma Postcondition
6252
6253
6254@geindex Postcondition
6255
6256@geindex Checks
6257@geindex postconditions
6258
6259Syntax:
6260
6261@example
6262pragma Postcondition (
6263   [Check   =>] Boolean_Expression
6264 [,[Message =>] String_Expression]);
6265@end example
6266
6267The @code{Postcondition} pragma allows specification of automatic
6268postcondition checks for subprograms. These checks are similar to
6269assertions, but are automatically inserted just prior to the return
6270statements of the subprogram with which they are associated (including
6271implicit returns at the end of procedure bodies and associated
6272exception handlers).
6273
6274In addition, the boolean expression which is the condition which
6275must be true may contain references to function’Result in the case
6276of a function to refer to the returned value.
6277
6278@code{Postcondition} pragmas may appear either immediately following the
6279(separate) declaration of a subprogram, or at the start of the
6280declarations of a subprogram body. Only other pragmas may intervene
6281(that is appear between the subprogram declaration and its
6282postconditions, or appear before the postcondition in the
6283declaration sequence in a subprogram body). In the case of a
6284postcondition appearing after a subprogram declaration, the
6285formal arguments of the subprogram are visible, and can be
6286referenced in the postcondition expressions.
6287
6288The postconditions are collected and automatically tested just
6289before any return (implicit or explicit) in the subprogram body.
6290A postcondition is only recognized if postconditions are active
6291at the time the pragma is encountered. The compiler switch @emph{gnata}
6292turns on all postconditions by default, and pragma @code{Check_Policy}
6293with an identifier of @code{Postcondition} can also be used to
6294control whether postconditions are active.
6295
6296The general approach is that postconditions are placed in the spec
6297if they represent functional aspects which make sense to the client.
6298For example we might have:
6299
6300@example
6301function Direction return Integer;
6302pragma Postcondition
6303 (Direction'Result = +1
6304    or else
6305  Direction'Result = -1);
6306@end example
6307
6308which serves to document that the result must be +1 or -1, and
6309will test that this is the case at run time if postcondition
6310checking is active.
6311
6312Postconditions within the subprogram body can be used to
6313check that some internal aspect of the implementation,
6314not visible to the client, is operating as expected.
6315For instance if a square root routine keeps an internal
6316counter of the number of times it is called, then we
6317might have the following postcondition:
6318
6319@example
6320Sqrt_Calls : Natural := 0;
6321
6322function Sqrt (Arg : Float) return Float is
6323  pragma Postcondition
6324    (Sqrt_Calls = Sqrt_Calls'Old + 1);
6325  ...
6326end Sqrt
6327@end example
6328
6329As this example, shows, the use of the @code{Old} attribute
6330is often useful in postconditions to refer to the state on
6331entry to the subprogram.
6332
6333Note that postconditions are only checked on normal returns
6334from the subprogram. If an abnormal return results from
6335raising an exception, then the postconditions are not checked.
6336
6337If a postcondition fails, then the exception
6338@code{System.Assertions.Assert_Failure} is raised. If
6339a message argument was supplied, then the given string
6340will be used as the exception message. If no message
6341argument was supplied, then the default message has
6342the form “Postcondition failed at file_name:line”. The
6343exception is raised in the context of the subprogram
6344body, so it is possible to catch postcondition failures
6345within the subprogram body itself.
6346
6347Within a package spec, normal visibility rules
6348in Ada would prevent forward references within a
6349postcondition pragma to functions defined later in
6350the same package. This would introduce undesirable
6351ordering constraints. To avoid this problem, all
6352postcondition pragmas are analyzed at the end of
6353the package spec, allowing forward references.
6354
6355The following example shows that this even allows
6356mutually recursive postconditions as in:
6357
6358@example
6359package Parity_Functions is
6360   function Odd  (X : Natural) return Boolean;
6361   pragma Postcondition
6362     (Odd'Result =
6363        (x = 1
6364          or else
6365        (x /= 0 and then Even (X - 1))));
6366
6367   function Even (X : Natural) return Boolean;
6368   pragma Postcondition
6369     (Even'Result =
6370        (x = 0
6371          or else
6372        (x /= 1 and then Odd (X - 1))));
6373
6374end Parity_Functions;
6375@end example
6376
6377There are no restrictions on the complexity or form of
6378conditions used within @code{Postcondition} pragmas.
6379The following example shows that it is even possible
6380to verify performance behavior.
6381
6382@example
6383package Sort is
6384
6385   Performance : constant Float;
6386   --  Performance constant set by implementation
6387   --  to match target architecture behavior.
6388
6389   procedure Treesort (Arg : String);
6390   --  Sorts characters of argument using N*logN sort
6391   pragma Postcondition
6392     (Float (Clock - Clock'Old) <=
6393        Float (Arg'Length) *
6394        log (Float (Arg'Length)) *
6395        Performance);
6396end Sort;
6397@end example
6398
6399Note: postcondition pragmas associated with subprograms that are
6400marked as Inline_Always, or those marked as Inline with front-end
6401inlining (-gnatN option set) are accepted and legality-checked
6402by the compiler, but are ignored at run-time even if postcondition
6403checking is enabled.
6404
6405Note that pragma @code{Postcondition} differs from the language-defined
6406@code{Post} aspect (and corresponding @code{Post} pragma) in allowing
6407multiple occurrences, allowing occurences in the body even if there
6408is a separate spec, and allowing a second string parameter, and the
6409use of the pragma identifier @code{Check}. Historically, pragma
6410@code{Postcondition} was implemented prior to the development of
6411Ada 2012, and has been retained in its original form for
6412compatibility purposes.
6413
6414@node Pragma Post_Class,Pragma Pre,Pragma Postcondition,Implementation Defined Pragmas
6415@anchor{gnat_rm/implementation_defined_pragmas pragma-post-class}@anchor{ba}
6416@section Pragma Post_Class
6417
6418
6419@geindex Post
6420
6421@geindex Checks
6422@geindex postconditions
6423
6424Syntax:
6425
6426@example
6427pragma Post_Class (Boolean_Expression);
6428@end example
6429
6430The @code{Post_Class} pragma is intended to be an exact replacement for
6431the language-defined
6432@code{Post'Class} aspect, and shares its restrictions and semantics.
6433It must appear either immediately following the corresponding
6434subprogram declaration (only other pragmas may intervene), or
6435if there is no separate subprogram declaration, then it can
6436appear at the start of the declarations in a subprogram body
6437(preceded only by other pragmas).
6438
6439Note: This pragma is called @code{Post_Class} rather than
6440@code{Post'Class} because the latter would not be strictly
6441conforming to the allowed syntax for pragmas. The motivation
6442for provinding pragmas equivalent to the aspects is to allow a program
6443to be written using the pragmas, and then compiled if necessary
6444using an Ada compiler that does not recognize the pragmas or
6445aspects, but is prepared to ignore the pragmas. The assertion
6446policy that controls this pragma is @code{Post'Class}, not
6447@code{Post_Class}.
6448
6449@node Pragma Pre,Pragma Precondition,Pragma Post_Class,Implementation Defined Pragmas
6450@anchor{gnat_rm/implementation_defined_pragmas pragma-pre}@anchor{bb}
6451@section Pragma Pre
6452
6453
6454@geindex Pre
6455
6456@geindex Checks
6457@geindex preconditions
6458
6459Syntax:
6460
6461@example
6462pragma Pre (Boolean_Expression);
6463@end example
6464
6465The @code{Pre} pragma is intended to be an exact replacement for
6466the language-defined
6467@code{Pre} aspect, and shares its restrictions and semantics.
6468It must appear either immediately following the corresponding
6469subprogram declaration (only other pragmas may intervene), or
6470if there is no separate subprogram declaration, then it can
6471appear at the start of the declarations in a subprogram body
6472(preceded only by other pragmas).
6473
6474@node Pragma Precondition,Pragma Predicate,Pragma Pre,Implementation Defined Pragmas
6475@anchor{gnat_rm/implementation_defined_pragmas pragma-precondition}@anchor{bc}
6476@section Pragma Precondition
6477
6478
6479@geindex Preconditions
6480
6481@geindex Checks
6482@geindex preconditions
6483
6484Syntax:
6485
6486@example
6487pragma Precondition (
6488   [Check   =>] Boolean_Expression
6489 [,[Message =>] String_Expression]);
6490@end example
6491
6492The @code{Precondition} pragma is similar to @code{Postcondition}
6493except that the corresponding checks take place immediately upon
6494entry to the subprogram, and if a precondition fails, the exception
6495is raised in the context of the caller, and the attribute ‘Result
6496cannot be used within the precondition expression.
6497
6498Otherwise, the placement and visibility rules are identical to those
6499described for postconditions. The following is an example of use
6500within a package spec:
6501
6502@example
6503package Math_Functions is
6504   ...
6505   function Sqrt (Arg : Float) return Float;
6506   pragma Precondition (Arg >= 0.0)
6507   ...
6508end Math_Functions;
6509@end example
6510
6511@code{Precondition} pragmas may appear either immediately following the
6512(separate) declaration of a subprogram, or at the start of the
6513declarations of a subprogram body. Only other pragmas may intervene
6514(that is appear between the subprogram declaration and its
6515postconditions, or appear before the postcondition in the
6516declaration sequence in a subprogram body).
6517
6518Note: precondition pragmas associated with subprograms that are
6519marked as Inline_Always, or those marked as Inline with front-end
6520inlining (-gnatN option set) are accepted and legality-checked
6521by the compiler, but are ignored at run-time even if precondition
6522checking is enabled.
6523
6524Note that pragma @code{Precondition} differs from the language-defined
6525@code{Pre} aspect (and corresponding @code{Pre} pragma) in allowing
6526multiple occurrences, allowing occurences in the body even if there
6527is a separate spec, and allowing a second string parameter, and the
6528use of the pragma identifier @code{Check}. Historically, pragma
6529@code{Precondition} was implemented prior to the development of
6530Ada 2012, and has been retained in its original form for
6531compatibility purposes.
6532
6533@node Pragma Predicate,Pragma Predicate_Failure,Pragma Precondition,Implementation Defined Pragmas
6534@anchor{gnat_rm/implementation_defined_pragmas id30}@anchor{bd}@anchor{gnat_rm/implementation_defined_pragmas pragma-predicate}@anchor{be}
6535@section Pragma Predicate
6536
6537
6538Syntax:
6539
6540@example
6541pragma Predicate
6542  ([Entity =>] type_LOCAL_NAME,
6543   [Check  =>] EXPRESSION);
6544@end example
6545
6546This pragma (available in all versions of Ada in GNAT) encompasses both
6547the @code{Static_Predicate} and @code{Dynamic_Predicate} aspects in
6548Ada 2012. A predicate is regarded as static if it has an allowed form
6549for @code{Static_Predicate} and is otherwise treated as a
6550@code{Dynamic_Predicate}. Otherwise, predicates specified by this
6551pragma behave exactly as described in the Ada 2012 reference manual.
6552For example, if we have
6553
6554@example
6555type R is range 1 .. 10;
6556subtype S is R;
6557pragma Predicate (Entity => S, Check => S not in 4 .. 6);
6558subtype Q is R
6559pragma Predicate (Entity => Q, Check => F(Q) or G(Q));
6560@end example
6561
6562the effect is identical to the following Ada 2012 code:
6563
6564@example
6565type R is range 1 .. 10;
6566subtype S is R with
6567  Static_Predicate => S not in 4 .. 6;
6568subtype Q is R with
6569  Dynamic_Predicate => F(Q) or G(Q);
6570@end example
6571
6572Note that there are no pragmas @code{Dynamic_Predicate}
6573or @code{Static_Predicate}. That is
6574because these pragmas would affect legality and semantics of
6575the program and thus do not have a neutral effect if ignored.
6576The motivation behind providing pragmas equivalent to
6577corresponding aspects is to allow a program to be written
6578using the pragmas, and then compiled with a compiler that
6579will ignore the pragmas. That doesn’t work in the case of
6580static and dynamic predicates, since if the corresponding
6581pragmas are ignored, then the behavior of the program is
6582fundamentally changed (for example a membership test
6583@code{A in B} would not take into account a predicate
6584defined for subtype B). When following this approach, the
6585use of predicates should be avoided.
6586
6587@node Pragma Predicate_Failure,Pragma Preelaborable_Initialization,Pragma Predicate,Implementation Defined Pragmas
6588@anchor{gnat_rm/implementation_defined_pragmas pragma-predicate-failure}@anchor{bf}
6589@section Pragma Predicate_Failure
6590
6591
6592Syntax:
6593
6594@example
6595pragma Predicate_Failure
6596  ([Entity  =>] type_LOCAL_NAME,
6597   [Message =>] String_Expression);
6598@end example
6599
6600The @code{Predicate_Failure} pragma is intended to be an exact replacement for
6601the language-defined
6602@code{Predicate_Failure} aspect, and shares its restrictions and semantics.
6603
6604@node Pragma Preelaborable_Initialization,Pragma Prefix_Exception_Messages,Pragma Predicate_Failure,Implementation Defined Pragmas
6605@anchor{gnat_rm/implementation_defined_pragmas pragma-preelaborable-initialization}@anchor{c0}
6606@section Pragma Preelaborable_Initialization
6607
6608
6609Syntax:
6610
6611@example
6612pragma Preelaborable_Initialization (DIRECT_NAME);
6613@end example
6614
6615This pragma is standard in Ada 2005, but is available in all earlier
6616versions of Ada as an implementation-defined pragma.
6617See Ada 2012 Reference Manual for details.
6618
6619@node Pragma Prefix_Exception_Messages,Pragma Pre_Class,Pragma Preelaborable_Initialization,Implementation Defined Pragmas
6620@anchor{gnat_rm/implementation_defined_pragmas pragma-prefix-exception-messages}@anchor{c1}
6621@section Pragma Prefix_Exception_Messages
6622
6623
6624@geindex Prefix_Exception_Messages
6625
6626@geindex exception
6627
6628@geindex Exception_Message
6629
6630Syntax:
6631
6632@example
6633pragma Prefix_Exception_Messages;
6634@end example
6635
6636This is an implementation-defined configuration pragma that affects the
6637behavior of raise statements with a message given as a static string
6638constant (typically a string literal). In such cases, the string will
6639be automatically prefixed by the name of the enclosing entity (giving
6640the package and subprogram containing the raise statement). This helps
6641to identify where messages are coming from, and this mode is automatic
6642for the run-time library.
6643
6644The pragma has no effect if the message is computed with an expression other
6645than a static string constant, since the assumption in this case is that
6646the program computes exactly the string it wants. If you still want the
6647prefixing in this case, you can always call
6648@code{GNAT.Source_Info.Enclosing_Entity} and prepend the string manually.
6649
6650@node Pragma Pre_Class,Pragma Priority_Specific_Dispatching,Pragma Prefix_Exception_Messages,Implementation Defined Pragmas
6651@anchor{gnat_rm/implementation_defined_pragmas pragma-pre-class}@anchor{c2}
6652@section Pragma Pre_Class
6653
6654
6655@geindex Pre_Class
6656
6657@geindex Checks
6658@geindex preconditions
6659
6660Syntax:
6661
6662@example
6663pragma Pre_Class (Boolean_Expression);
6664@end example
6665
6666The @code{Pre_Class} pragma is intended to be an exact replacement for
6667the language-defined
6668@code{Pre'Class} aspect, and shares its restrictions and semantics.
6669It must appear either immediately following the corresponding
6670subprogram declaration (only other pragmas may intervene), or
6671if there is no separate subprogram declaration, then it can
6672appear at the start of the declarations in a subprogram body
6673(preceded only by other pragmas).
6674
6675Note: This pragma is called @code{Pre_Class} rather than
6676@code{Pre'Class} because the latter would not be strictly
6677conforming to the allowed syntax for pragmas. The motivation
6678for providing pragmas equivalent to the aspects is to allow a program
6679to be written using the pragmas, and then compiled if necessary
6680using an Ada compiler that does not recognize the pragmas or
6681aspects, but is prepared to ignore the pragmas. The assertion
6682policy that controls this pragma is @code{Pre'Class}, not
6683@code{Pre_Class}.
6684
6685@node Pragma Priority_Specific_Dispatching,Pragma Profile,Pragma Pre_Class,Implementation Defined Pragmas
6686@anchor{gnat_rm/implementation_defined_pragmas pragma-priority-specific-dispatching}@anchor{c3}
6687@section Pragma Priority_Specific_Dispatching
6688
6689
6690Syntax:
6691
6692@example
6693pragma Priority_Specific_Dispatching (
6694   POLICY_IDENTIFIER,
6695   first_priority_EXPRESSION,
6696   last_priority_EXPRESSION)
6697
6698POLICY_IDENTIFIER ::=
6699   EDF_Across_Priorities            |
6700   FIFO_Within_Priorities           |
6701   Non_Preemptive_Within_Priorities |
6702   Round_Robin_Within_Priorities
6703@end example
6704
6705This pragma is standard in Ada 2005, but is available in all earlier
6706versions of Ada as an implementation-defined pragma.
6707See Ada 2012 Reference Manual for details.
6708
6709@node Pragma Profile,Pragma Profile_Warnings,Pragma Priority_Specific_Dispatching,Implementation Defined Pragmas
6710@anchor{gnat_rm/implementation_defined_pragmas pragma-profile}@anchor{c4}
6711@section Pragma Profile
6712
6713
6714Syntax:
6715
6716@example
6717pragma Profile (Ravenscar | Restricted | Rational | Jorvik |
6718                GNAT_Extended_Ravenscar | GNAT_Ravenscar_EDF );
6719@end example
6720
6721This pragma is standard in Ada 2005, but is available in all earlier
6722versions of Ada as an implementation-defined pragma. This is a
6723configuration pragma that establishes a set of configuration pragmas
6724that depend on the argument. @code{Ravenscar} is standard in Ada 2005.
6725@code{Jorvik} is standard in Ada 202x.
6726The other possibilities (@code{Restricted}, @code{Rational},
6727@code{GNAT_Extended_Ravenscar}, @code{GNAT_Ravenscar_EDF})
6728are implementation-defined.  @code{GNAT_Extended_Ravenscar} is an alias for @code{Jorvik}.
6729
6730The set of configuration pragmas is defined in the following sections.
6731
6732
6733@itemize *
6734
6735@item
6736Pragma Profile (Ravenscar)
6737
6738The @code{Ravenscar} profile is standard in Ada 2005,
6739but is available in all earlier
6740versions of Ada as an implementation-defined pragma. This profile
6741establishes the following set of configuration pragmas:
6742
6743
6744@itemize *
6745
6746@item
6747@code{Task_Dispatching_Policy (FIFO_Within_Priorities)}
6748
6749[RM D.2.2] Tasks are dispatched following a preemptive
6750priority-ordered scheduling policy.
6751
6752@item
6753@code{Locking_Policy (Ceiling_Locking)}
6754
6755[RM D.3] While tasks and interrupts execute a protected action, they inherit
6756the ceiling priority of the corresponding protected object.
6757
6758@item
6759@code{Detect_Blocking}
6760
6761This pragma forces the detection of potentially blocking operations within a
6762protected operation, and to raise Program_Error if that happens.
6763@end itemize
6764
6765plus the following set of restrictions:
6766
6767
6768@itemize *
6769
6770@item
6771@code{Max_Entry_Queue_Length => 1}
6772
6773No task can be queued on a protected entry.
6774
6775@item
6776@code{Max_Protected_Entries => 1}
6777
6778@item
6779@code{Max_Task_Entries => 0}
6780
6781No rendezvous statements are allowed.
6782
6783@item
6784@code{No_Abort_Statements}
6785
6786@item
6787@code{No_Dynamic_Attachment}
6788
6789@item
6790@code{No_Dynamic_Priorities}
6791
6792@item
6793@code{No_Implicit_Heap_Allocations}
6794
6795@item
6796@code{No_Local_Protected_Objects}
6797
6798@item
6799@code{No_Local_Timing_Events}
6800
6801@item
6802@code{No_Protected_Type_Allocators}
6803
6804@item
6805@code{No_Relative_Delay}
6806
6807@item
6808@code{No_Requeue_Statements}
6809
6810@item
6811@code{No_Select_Statements}
6812
6813@item
6814@code{No_Specific_Termination_Handlers}
6815
6816@item
6817@code{No_Task_Allocators}
6818
6819@item
6820@code{No_Task_Hierarchy}
6821
6822@item
6823@code{No_Task_Termination}
6824
6825@item
6826@code{Simple_Barriers}
6827@end itemize
6828
6829The Ravenscar profile also includes the following restrictions that specify
6830that there are no semantic dependencies on the corresponding predefined
6831packages:
6832
6833
6834@itemize *
6835
6836@item
6837@code{No_Dependence => Ada.Asynchronous_Task_Control}
6838
6839@item
6840@code{No_Dependence => Ada.Calendar}
6841
6842@item
6843@code{No_Dependence => Ada.Execution_Time.Group_Budget}
6844
6845@item
6846@code{No_Dependence => Ada.Execution_Time.Timers}
6847
6848@item
6849@code{No_Dependence => Ada.Task_Attributes}
6850
6851@item
6852@code{No_Dependence => System.Multiprocessors.Dispatching_Domains}
6853@end itemize
6854
6855This set of configuration pragmas and restrictions correspond to the
6856definition of the ‘Ravenscar Profile’ for limited tasking, devised and
6857published by the @cite{International Real-Time Ada Workshop@comma{} 1997}.
6858A description is also available at
6859@indicateurl{http://www-users.cs.york.ac.uk/~burns/ravenscar.ps}.
6860
6861The original definition of the profile was revised at subsequent IRTAW
6862meetings. It has been included in the ISO
6863@cite{Guide for the Use of the Ada Programming Language in High Integrity Systems},
6864and was made part of the Ada 2005 standard.
6865The formal definition given by
6866the Ada Rapporteur Group (ARG) can be found in two Ada Issues (AI-249 and
6867AI-305) available at
6868@indicateurl{http://www.ada-auth.org/cgi-bin/cvsweb.cgi/ais/ai-00249.txt} and
6869@indicateurl{http://www.ada-auth.org/cgi-bin/cvsweb.cgi/ais/ai-00305.txt}.
6870
6871The above set is a superset of the restrictions provided by pragma
6872@code{Profile (Restricted)}, it includes six additional restrictions
6873(@code{Simple_Barriers}, @code{No_Select_Statements},
6874@code{No_Calendar}, @code{No_Implicit_Heap_Allocations},
6875@code{No_Relative_Delay} and @code{No_Task_Termination}).  This means
6876that pragma @code{Profile (Ravenscar)}, like the pragma
6877@code{Profile (Restricted)},
6878automatically causes the use of a simplified,
6879more efficient version of the tasking run-time library.
6880
6881@item
6882Pragma Profile (Jorvik)
6883
6884@code{Jorvik} is the new profile added to the Ada 202x draft standard,
6885previously implemented under the name @code{GNAT_Extended_Ravenscar}.
6886
6887The @code{No_Implicit_Heap_Allocations} restriction has been replaced
6888by @code{No_Implicit_Task_Allocations} and
6889@code{No_Implicit_Protected_Object_Allocations}.
6890
6891The @code{Simple_Barriers} restriction has been replaced by
6892@code{Pure_Barriers}.
6893
6894The @code{Max_Protected_Entries}, @code{Max_Entry_Queue_Length}, and
6895@code{No_Relative_Delay} restrictions have been removed.
6896
6897Details on the rationale for @code{Jorvik} and implications for use may be
6898found in @cite{A New Ravenscar-Based Profile} by P. Rogers, J. Ruiz,
6899T. Gingold and P. Bernardi, in @cite{Reliable Software Technologies – Ada Europe 2017}, Springer-Verlag Lecture Notes in Computer Science,
6900Number 10300.
6901
6902@item
6903Pragma Profile (GNAT_Ravenscar_EDF)
6904
6905This profile corresponds to the Ravenscar profile but using
6906EDF_Across_Priority as the Task_Scheduling_Policy.
6907
6908@item
6909Pragma Profile (Restricted)
6910
6911This profile corresponds to the GNAT restricted run time. It
6912establishes the following set of restrictions:
6913
6914
6915@itemize *
6916
6917@item
6918@code{No_Abort_Statements}
6919
6920@item
6921@code{No_Entry_Queue}
6922
6923@item
6924@code{No_Task_Hierarchy}
6925
6926@item
6927@code{No_Task_Allocators}
6928
6929@item
6930@code{No_Dynamic_Priorities}
6931
6932@item
6933@code{No_Terminate_Alternatives}
6934
6935@item
6936@code{No_Dynamic_Attachment}
6937
6938@item
6939@code{No_Protected_Type_Allocators}
6940
6941@item
6942@code{No_Local_Protected_Objects}
6943
6944@item
6945@code{No_Requeue_Statements}
6946
6947@item
6948@code{No_Task_Attributes_Package}
6949
6950@item
6951@code{Max_Asynchronous_Select_Nesting =  0}
6952
6953@item
6954@code{Max_Task_Entries =  0}
6955
6956@item
6957@code{Max_Protected_Entries = 1}
6958
6959@item
6960@code{Max_Select_Alternatives = 0}
6961@end itemize
6962
6963This set of restrictions causes the automatic selection of a simplified
6964version of the run time that provides improved performance for the
6965limited set of tasking functionality permitted by this set of restrictions.
6966
6967@item
6968Pragma Profile (Rational)
6969
6970The Rational profile is intended to facilitate porting legacy code that
6971compiles with the Rational APEX compiler, even when the code includes non-
6972conforming Ada constructs.  The profile enables the following three pragmas:
6973
6974
6975@itemize *
6976
6977@item
6978@code{pragma Implicit_Packing}
6979
6980@item
6981@code{pragma Overriding_Renamings}
6982
6983@item
6984@code{pragma Use_VADS_Size}
6985@end itemize
6986@end itemize
6987
6988@node Pragma Profile_Warnings,Pragma Propagate_Exceptions,Pragma Profile,Implementation Defined Pragmas
6989@anchor{gnat_rm/implementation_defined_pragmas pragma-profile-warnings}@anchor{c5}
6990@section Pragma Profile_Warnings
6991
6992
6993Syntax:
6994
6995@example
6996pragma Profile_Warnings (Ravenscar | Restricted | Rational);
6997@end example
6998
6999This is an implementation-defined pragma that is similar in
7000effect to @code{pragma Profile} except that instead of
7001generating @code{Restrictions} pragmas, it generates
7002@code{Restriction_Warnings} pragmas. The result is that
7003violations of the profile generate warning messages instead
7004of error messages.
7005
7006@node Pragma Propagate_Exceptions,Pragma Provide_Shift_Operators,Pragma Profile_Warnings,Implementation Defined Pragmas
7007@anchor{gnat_rm/implementation_defined_pragmas pragma-propagate-exceptions}@anchor{c6}
7008@section Pragma Propagate_Exceptions
7009
7010
7011@geindex Interfacing to C++
7012
7013Syntax:
7014
7015@example
7016pragma Propagate_Exceptions;
7017@end example
7018
7019This pragma is now obsolete and, other than generating a warning if warnings
7020on obsolescent features are enabled, is ignored.
7021It is retained for compatibility
7022purposes. It used to be used in connection with optimization of
7023a now-obsolete mechanism for implementation of exceptions.
7024
7025@node Pragma Provide_Shift_Operators,Pragma Psect_Object,Pragma Propagate_Exceptions,Implementation Defined Pragmas
7026@anchor{gnat_rm/implementation_defined_pragmas pragma-provide-shift-operators}@anchor{c7}
7027@section Pragma Provide_Shift_Operators
7028
7029
7030@geindex Shift operators
7031
7032Syntax:
7033
7034@example
7035pragma Provide_Shift_Operators (integer_first_subtype_LOCAL_NAME);
7036@end example
7037
7038This pragma can be applied to a first subtype local name that specifies
7039either an unsigned or signed type. It has the effect of providing the
7040five shift operators (Shift_Left, Shift_Right, Shift_Right_Arithmetic,
7041Rotate_Left and Rotate_Right) for the given type. It is similar to
7042including the function declarations for these five operators, together
7043with the pragma Import (Intrinsic, …) statements.
7044
7045@node Pragma Psect_Object,Pragma Pure_Function,Pragma Provide_Shift_Operators,Implementation Defined Pragmas
7046@anchor{gnat_rm/implementation_defined_pragmas pragma-psect-object}@anchor{c8}
7047@section Pragma Psect_Object
7048
7049
7050Syntax:
7051
7052@example
7053pragma Psect_Object (
7054     [Internal =>] LOCAL_NAME,
7055  [, [External =>] EXTERNAL_SYMBOL]
7056  [, [Size     =>] EXTERNAL_SYMBOL]);
7057
7058EXTERNAL_SYMBOL ::=
7059  IDENTIFIER
7060| static_string_EXPRESSION
7061@end example
7062
7063This pragma is identical in effect to pragma @code{Common_Object}.
7064
7065@node Pragma Pure_Function,Pragma Rational,Pragma Psect_Object,Implementation Defined Pragmas
7066@anchor{gnat_rm/implementation_defined_pragmas id31}@anchor{c9}@anchor{gnat_rm/implementation_defined_pragmas pragma-pure-function}@anchor{ca}
7067@section Pragma Pure_Function
7068
7069
7070Syntax:
7071
7072@example
7073pragma Pure_Function ([Entity =>] function_LOCAL_NAME);
7074@end example
7075
7076This pragma appears in the same declarative part as a function
7077declaration (or a set of function declarations if more than one
7078overloaded declaration exists, in which case the pragma applies
7079to all entities).  It specifies that the function @code{Entity} is
7080to be considered pure for the purposes of code generation.  This means
7081that the compiler can assume that there are no side effects, and
7082in particular that two calls with identical arguments produce the
7083same result.  It also means that the function can be used in an
7084address clause.
7085
7086Note that, quite deliberately, there are no static checks to try
7087to ensure that this promise is met, so @code{Pure_Function} can be used
7088with functions that are conceptually pure, even if they do modify
7089global variables.  For example, a square root function that is
7090instrumented to count the number of times it is called is still
7091conceptually pure, and can still be optimized, even though it
7092modifies a global variable (the count).  Memo functions are another
7093example (where a table of previous calls is kept and consulted to
7094avoid re-computation).
7095
7096Note also that the normal rules excluding optimization of subprograms
7097in pure units (when parameter types are descended from System.Address,
7098or when the full view of a parameter type is limited), do not apply
7099for the Pure_Function case. If you explicitly specify Pure_Function,
7100the compiler may optimize away calls with identical arguments, and
7101if that results in unexpected behavior, the proper action is not to
7102use the pragma for subprograms that are not (conceptually) pure.
7103
7104Note: Most functions in a @code{Pure} package are automatically pure, and
7105there is no need to use pragma @code{Pure_Function} for such functions.  One
7106exception is any function that has at least one formal of type
7107@code{System.Address} or a type derived from it.  Such functions are not
7108considered pure by default, since the compiler assumes that the
7109@code{Address} parameter may be functioning as a pointer and that the
7110referenced data may change even if the address value does not.
7111Similarly, imported functions are not considered to be pure by default,
7112since there is no way of checking that they are in fact pure.  The use
7113of pragma @code{Pure_Function} for such a function will override these default
7114assumption, and cause the compiler to treat a designated subprogram as pure
7115in these cases.
7116
7117Note: If pragma @code{Pure_Function} is applied to a renamed function, it
7118applies to the underlying renamed function.  This can be used to
7119disambiguate cases of overloading where some but not all functions
7120in a set of overloaded functions are to be designated as pure.
7121
7122If pragma @code{Pure_Function} is applied to a library-level function, the
7123function is also considered pure from an optimization point of view, but the
7124unit is not a Pure unit in the categorization sense. So for example, a function
7125thus marked is free to @code{with} non-pure units.
7126
7127@node Pragma Rational,Pragma Ravenscar,Pragma Pure_Function,Implementation Defined Pragmas
7128@anchor{gnat_rm/implementation_defined_pragmas pragma-rational}@anchor{cb}
7129@section Pragma Rational
7130
7131
7132Syntax:
7133
7134@example
7135pragma Rational;
7136@end example
7137
7138This pragma is considered obsolescent, but is retained for
7139compatibility purposes. It is equivalent to:
7140
7141@example
7142pragma Profile (Rational);
7143@end example
7144
7145@node Pragma Ravenscar,Pragma Refined_Depends,Pragma Rational,Implementation Defined Pragmas
7146@anchor{gnat_rm/implementation_defined_pragmas pragma-ravenscar}@anchor{cc}
7147@section Pragma Ravenscar
7148
7149
7150Syntax:
7151
7152@example
7153pragma Ravenscar;
7154@end example
7155
7156This pragma is considered obsolescent, but is retained for
7157compatibility purposes. It is equivalent to:
7158
7159@example
7160pragma Profile (Ravenscar);
7161@end example
7162
7163which is the preferred method of setting the @code{Ravenscar} profile.
7164
7165@node Pragma Refined_Depends,Pragma Refined_Global,Pragma Ravenscar,Implementation Defined Pragmas
7166@anchor{gnat_rm/implementation_defined_pragmas id32}@anchor{cd}@anchor{gnat_rm/implementation_defined_pragmas pragma-refined-depends}@anchor{ce}
7167@section Pragma Refined_Depends
7168
7169
7170Syntax:
7171
7172@example
7173pragma Refined_Depends (DEPENDENCY_RELATION);
7174
7175DEPENDENCY_RELATION ::=
7176     null
7177  | (DEPENDENCY_CLAUSE @{, DEPENDENCY_CLAUSE@})
7178
7179DEPENDENCY_CLAUSE ::=
7180    OUTPUT_LIST =>[+] INPUT_LIST
7181  | NULL_DEPENDENCY_CLAUSE
7182
7183NULL_DEPENDENCY_CLAUSE ::= null => INPUT_LIST
7184
7185OUTPUT_LIST ::= OUTPUT | (OUTPUT @{, OUTPUT@})
7186
7187INPUT_LIST ::= null | INPUT | (INPUT @{, INPUT@})
7188
7189OUTPUT ::= NAME | FUNCTION_RESULT
7190INPUT  ::= NAME
7191
7192where FUNCTION_RESULT is a function Result attribute_reference
7193@end example
7194
7195For the semantics of this pragma, see the entry for aspect @code{Refined_Depends} in
7196the SPARK 2014 Reference Manual, section 6.1.5.
7197
7198@node Pragma Refined_Global,Pragma Refined_Post,Pragma Refined_Depends,Implementation Defined Pragmas
7199@anchor{gnat_rm/implementation_defined_pragmas id33}@anchor{cf}@anchor{gnat_rm/implementation_defined_pragmas pragma-refined-global}@anchor{d0}
7200@section Pragma Refined_Global
7201
7202
7203Syntax:
7204
7205@example
7206pragma Refined_Global (GLOBAL_SPECIFICATION);
7207
7208GLOBAL_SPECIFICATION ::=
7209     null
7210  | (GLOBAL_LIST)
7211  | (MODED_GLOBAL_LIST @{, MODED_GLOBAL_LIST@})
7212
7213MODED_GLOBAL_LIST ::= MODE_SELECTOR => GLOBAL_LIST
7214
7215MODE_SELECTOR ::= In_Out | Input | Output | Proof_In
7216GLOBAL_LIST   ::= GLOBAL_ITEM | (GLOBAL_ITEM @{, GLOBAL_ITEM@})
7217GLOBAL_ITEM   ::= NAME
7218@end example
7219
7220For the semantics of this pragma, see the entry for aspect @code{Refined_Global} in
7221the SPARK 2014 Reference Manual, section 6.1.4.
7222
7223@node Pragma Refined_Post,Pragma Refined_State,Pragma Refined_Global,Implementation Defined Pragmas
7224@anchor{gnat_rm/implementation_defined_pragmas id34}@anchor{d1}@anchor{gnat_rm/implementation_defined_pragmas pragma-refined-post}@anchor{d2}
7225@section Pragma Refined_Post
7226
7227
7228Syntax:
7229
7230@example
7231pragma Refined_Post (boolean_EXPRESSION);
7232@end example
7233
7234For the semantics of this pragma, see the entry for aspect @code{Refined_Post} in
7235the SPARK 2014 Reference Manual, section 7.2.7.
7236
7237@node Pragma Refined_State,Pragma Relative_Deadline,Pragma Refined_Post,Implementation Defined Pragmas
7238@anchor{gnat_rm/implementation_defined_pragmas id35}@anchor{d3}@anchor{gnat_rm/implementation_defined_pragmas pragma-refined-state}@anchor{d4}
7239@section Pragma Refined_State
7240
7241
7242Syntax:
7243
7244@example
7245pragma Refined_State (REFINEMENT_LIST);
7246
7247REFINEMENT_LIST ::=
7248  (REFINEMENT_CLAUSE @{, REFINEMENT_CLAUSE@})
7249
7250REFINEMENT_CLAUSE ::= state_NAME => CONSTITUENT_LIST
7251
7252CONSTITUENT_LIST ::=
7253     null
7254  |  CONSTITUENT
7255  | (CONSTITUENT @{, CONSTITUENT@})
7256
7257CONSTITUENT ::= object_NAME | state_NAME
7258@end example
7259
7260For the semantics of this pragma, see the entry for aspect @code{Refined_State} in
7261the SPARK 2014 Reference Manual, section 7.2.2.
7262
7263@node Pragma Relative_Deadline,Pragma Remote_Access_Type,Pragma Refined_State,Implementation Defined Pragmas
7264@anchor{gnat_rm/implementation_defined_pragmas pragma-relative-deadline}@anchor{d5}
7265@section Pragma Relative_Deadline
7266
7267
7268Syntax:
7269
7270@example
7271pragma Relative_Deadline (time_span_EXPRESSION);
7272@end example
7273
7274This pragma is standard in Ada 2005, but is available in all earlier
7275versions of Ada as an implementation-defined pragma.
7276See Ada 2012 Reference Manual for details.
7277
7278@node Pragma Remote_Access_Type,Pragma Rename_Pragma,Pragma Relative_Deadline,Implementation Defined Pragmas
7279@anchor{gnat_rm/implementation_defined_pragmas id36}@anchor{d6}@anchor{gnat_rm/implementation_defined_pragmas pragma-remote-access-type}@anchor{d7}
7280@section Pragma Remote_Access_Type
7281
7282
7283Syntax:
7284
7285@example
7286pragma Remote_Access_Type ([Entity =>] formal_access_type_LOCAL_NAME);
7287@end example
7288
7289This pragma appears in the formal part of a generic declaration.
7290It specifies an exception to the RM rule from E.2.2(17/2), which forbids
7291the use of a remote access to class-wide type as actual for a formal
7292access type.
7293
7294When this pragma applies to a formal access type @code{Entity}, that
7295type is treated as a remote access to class-wide type in the generic.
7296It must be a formal general access type, and its designated type must
7297be the class-wide type of a formal tagged limited private type from the
7298same generic declaration.
7299
7300In the generic unit, the formal type is subject to all restrictions
7301pertaining to remote access to class-wide types. At instantiation, the
7302actual type must be a remote access to class-wide type.
7303
7304@node Pragma Rename_Pragma,Pragma Restricted_Run_Time,Pragma Remote_Access_Type,Implementation Defined Pragmas
7305@anchor{gnat_rm/implementation_defined_pragmas pragma-rename-pragma}@anchor{d8}
7306@section Pragma Rename_Pragma
7307
7308
7309@geindex Pragmas
7310@geindex synonyms
7311
7312Syntax:
7313
7314@example
7315pragma Rename_Pragma (
7316         [New_Name =>] IDENTIFIER,
7317         [Renamed  =>] pragma_IDENTIFIER);
7318@end example
7319
7320This pragma provides a mechanism for supplying new names for existing
7321pragmas. The @code{New_Name} identifier can subsequently be used as a synonym for
7322the Renamed pragma. For example, suppose you have code that was originally
7323developed on a compiler that supports Inline_Only as an implementation defined
7324pragma. And suppose the semantics of pragma Inline_Only are identical to (or at
7325least very similar to) the GNAT implementation defined pragma
7326Inline_Always. You could globally replace Inline_Only with Inline_Always.
7327
7328However, to avoid that source modification, you could instead add a
7329configuration pragma:
7330
7331@example
7332pragma Rename_Pragma (
7333         New_Name => Inline_Only,
7334         Renamed  => Inline_Always);
7335@end example
7336
7337Then GNAT will treat “pragma Inline_Only …” as if you had written
7338“pragma Inline_Always …”.
7339
7340Pragma Inline_Only will not necessarily mean the same thing as the other Ada
7341compiler; it’s up to you to make sure the semantics are close enough.
7342
7343@node Pragma Restricted_Run_Time,Pragma Restriction_Warnings,Pragma Rename_Pragma,Implementation Defined Pragmas
7344@anchor{gnat_rm/implementation_defined_pragmas pragma-restricted-run-time}@anchor{d9}
7345@section Pragma Restricted_Run_Time
7346
7347
7348Syntax:
7349
7350@example
7351pragma Restricted_Run_Time;
7352@end example
7353
7354This pragma is considered obsolescent, but is retained for
7355compatibility purposes. It is equivalent to:
7356
7357@example
7358pragma Profile (Restricted);
7359@end example
7360
7361which is the preferred method of setting the restricted run time
7362profile.
7363
7364@node Pragma Restriction_Warnings,Pragma Reviewable,Pragma Restricted_Run_Time,Implementation Defined Pragmas
7365@anchor{gnat_rm/implementation_defined_pragmas pragma-restriction-warnings}@anchor{da}
7366@section Pragma Restriction_Warnings
7367
7368
7369Syntax:
7370
7371@example
7372pragma Restriction_Warnings
7373  (restriction_IDENTIFIER @{, restriction_IDENTIFIER@});
7374@end example
7375
7376This pragma allows a series of restriction identifiers to be
7377specified (the list of allowed identifiers is the same as for
7378pragma @code{Restrictions}). For each of these identifiers
7379the compiler checks for violations of the restriction, but
7380generates a warning message rather than an error message
7381if the restriction is violated.
7382
7383One use of this is in situations where you want to know
7384about violations of a restriction, but you want to ignore some of
7385these violations. Consider this example, where you want to set
7386Ada_95 mode and enable style checks, but you want to know about
7387any other use of implementation pragmas:
7388
7389@example
7390pragma Restriction_Warnings (No_Implementation_Pragmas);
7391pragma Warnings (Off, "violation of No_Implementation_Pragmas");
7392pragma Ada_95;
7393pragma Style_Checks ("2bfhkM160");
7394pragma Warnings (On, "violation of No_Implementation_Pragmas");
7395@end example
7396
7397By including the above lines in a configuration pragmas file,
7398the Ada_95 and Style_Checks pragmas are accepted without
7399generating a warning, but any other use of implementation
7400defined pragmas will cause a warning to be generated.
7401
7402@node Pragma Reviewable,Pragma Secondary_Stack_Size,Pragma Restriction_Warnings,Implementation Defined Pragmas
7403@anchor{gnat_rm/implementation_defined_pragmas pragma-reviewable}@anchor{db}
7404@section Pragma Reviewable
7405
7406
7407Syntax:
7408
7409@example
7410pragma Reviewable;
7411@end example
7412
7413This pragma is an RM-defined standard pragma, but has no effect on the
7414program being compiled, or on the code generated for the program.
7415
7416To obtain the required output specified in RM H.3.1, the compiler must be
7417run with various special switches as follows:
7418
7419
7420@itemize *
7421
7422@item
7423@emph{Where compiler-generated run-time checks remain}
7424
7425The switch @emph{-gnatGL}
7426may be used to list the expanded code in pseudo-Ada form.
7427Runtime checks show up in the listing either as explicit
7428checks or operators marked with @{@} to indicate a check is present.
7429
7430@item
7431@emph{An identification of known exceptions at compile time}
7432
7433If the program is compiled with @emph{-gnatwa},
7434the compiler warning messages will indicate all cases where the compiler
7435detects that an exception is certain to occur at run time.
7436
7437@item
7438@emph{Possible reads of uninitialized variables}
7439
7440The compiler warns of many such cases, but its output is incomplete.
7441@end itemize
7442
7443
7444A supplemental static analysis tool
7445may be used to obtain a comprehensive list of all
7446possible points at which uninitialized data may be read.
7447
7448
7449@itemize *
7450
7451@item
7452@emph{Where run-time support routines are implicitly invoked}
7453
7454In the output from @emph{-gnatGL},
7455run-time calls are explicitly listed as calls to the relevant
7456run-time routine.
7457
7458@item
7459@emph{Object code listing}
7460
7461This may be obtained either by using the @emph{-S} switch,
7462or the objdump utility.
7463
7464@item
7465@emph{Constructs known to be erroneous at compile time}
7466
7467These are identified by warnings issued by the compiler (use @emph{-gnatwa}).
7468
7469@item
7470@emph{Stack usage information}
7471
7472Static stack usage data (maximum per-subprogram) can be obtained via the
7473@emph{-fstack-usage} switch to the compiler.
7474Dynamic stack usage data (per task) can be obtained via the @emph{-u} switch
7475to gnatbind
7476@end itemize
7477
7478
7479
7480@itemize *
7481
7482@item
7483@emph{Object code listing of entire partition}
7484
7485This can be obtained by compiling the partition with @emph{-S},
7486or by applying objdump
7487to all the object files that are part of the partition.
7488
7489@item
7490@emph{A description of the run-time model}
7491
7492The full sources of the run-time are available, and the documentation of
7493these routines describes how these run-time routines interface to the
7494underlying operating system facilities.
7495
7496@item
7497@emph{Control and data-flow information}
7498@end itemize
7499
7500
7501A supplemental static analysis tool
7502may be used to obtain complete control and data-flow information, as well as
7503comprehensive messages identifying possible problems based on this
7504information.
7505
7506@node Pragma Secondary_Stack_Size,Pragma Share_Generic,Pragma Reviewable,Implementation Defined Pragmas
7507@anchor{gnat_rm/implementation_defined_pragmas id37}@anchor{dc}@anchor{gnat_rm/implementation_defined_pragmas pragma-secondary-stack-size}@anchor{dd}
7508@section Pragma Secondary_Stack_Size
7509
7510
7511Syntax:
7512
7513@example
7514pragma Secondary_Stack_Size (integer_EXPRESSION);
7515@end example
7516
7517This pragma appears within the task definition of a single task declaration
7518or a task type declaration (like pragma @code{Storage_Size}) and applies to all
7519task objects of that type. The argument specifies the size of the secondary
7520stack to be used by these task objects, and must be of an integer type. The
7521secondary stack is used to handle functions that return a variable-sized
7522result, for example a function returning an unconstrained String.
7523
7524Note this pragma only applies to targets using fixed secondary stacks, like
7525VxWorks 653 and bare board targets, where a fixed block for the
7526secondary stack is allocated from the primary stack of the task. By default,
7527these targets assign a percentage of the primary stack for the secondary stack,
7528as defined by @code{System.Parameter.Sec_Stack_Percentage}. With this pragma,
7529an @code{integer_EXPRESSION} of bytes is assigned from the primary stack instead.
7530
7531For most targets, the pragma does not apply as the secondary stack grows on
7532demand: allocated as a chain of blocks in the heap. The default size of these
7533blocks can be modified via the @code{-D} binder option as described in
7534@cite{GNAT User’s Guide}.
7535
7536Note that no check is made to see if the secondary stack can fit inside the
7537primary stack.
7538
7539Note the pragma cannot appear when the restriction @code{No_Secondary_Stack}
7540is in effect.
7541
7542@node Pragma Share_Generic,Pragma Shared,Pragma Secondary_Stack_Size,Implementation Defined Pragmas
7543@anchor{gnat_rm/implementation_defined_pragmas pragma-share-generic}@anchor{de}
7544@section Pragma Share_Generic
7545
7546
7547Syntax:
7548
7549@example
7550pragma Share_Generic (GNAME @{, GNAME@});
7551
7552GNAME ::= generic_unit_NAME | generic_instance_NAME
7553@end example
7554
7555This pragma is provided for compatibility with Dec Ada 83. It has
7556no effect in GNAT (which does not implement shared generics), other
7557than to check that the given names are all names of generic units or
7558generic instances.
7559
7560@node Pragma Shared,Pragma Short_Circuit_And_Or,Pragma Share_Generic,Implementation Defined Pragmas
7561@anchor{gnat_rm/implementation_defined_pragmas id38}@anchor{df}@anchor{gnat_rm/implementation_defined_pragmas pragma-shared}@anchor{e0}
7562@section Pragma Shared
7563
7564
7565This pragma is provided for compatibility with Ada 83. The syntax and
7566semantics are identical to pragma Atomic.
7567
7568@node Pragma Short_Circuit_And_Or,Pragma Short_Descriptors,Pragma Shared,Implementation Defined Pragmas
7569@anchor{gnat_rm/implementation_defined_pragmas pragma-short-circuit-and-or}@anchor{e1}
7570@section Pragma Short_Circuit_And_Or
7571
7572
7573Syntax:
7574
7575@example
7576pragma Short_Circuit_And_Or;
7577@end example
7578
7579This configuration pragma causes any occurrence of the AND operator applied to
7580operands of type Standard.Boolean to be short-circuited (i.e. the AND operator
7581is treated as if it were AND THEN). Or is similarly treated as OR ELSE. This
7582may be useful in the context of certification protocols requiring the use of
7583short-circuited logical operators. If this configuration pragma occurs locally
7584within the file being compiled, it applies only to the file being compiled.
7585There is no requirement that all units in a partition use this option.
7586
7587@node Pragma Short_Descriptors,Pragma Simple_Storage_Pool_Type,Pragma Short_Circuit_And_Or,Implementation Defined Pragmas
7588@anchor{gnat_rm/implementation_defined_pragmas pragma-short-descriptors}@anchor{e2}
7589@section Pragma Short_Descriptors
7590
7591
7592Syntax:
7593
7594@example
7595pragma Short_Descriptors
7596@end example
7597
7598This pragma is provided for compatibility with other Ada implementations. It
7599is recognized but ignored by all current versions of GNAT.
7600
7601@node Pragma Simple_Storage_Pool_Type,Pragma Source_File_Name,Pragma Short_Descriptors,Implementation Defined Pragmas
7602@anchor{gnat_rm/implementation_defined_pragmas id39}@anchor{e3}@anchor{gnat_rm/implementation_defined_pragmas pragma-simple-storage-pool-type}@anchor{e4}
7603@section Pragma Simple_Storage_Pool_Type
7604
7605
7606@geindex Storage pool
7607@geindex simple
7608
7609@geindex Simple storage pool
7610
7611Syntax:
7612
7613@example
7614pragma Simple_Storage_Pool_Type (type_LOCAL_NAME);
7615@end example
7616
7617A type can be established as a ‘simple storage pool type’ by applying
7618the representation pragma @code{Simple_Storage_Pool_Type} to the type.
7619A type named in the pragma must be a library-level immutably limited record
7620type or limited tagged type declared immediately within a package declaration.
7621The type can also be a limited private type whose full type is allowed as
7622a simple storage pool type.
7623
7624For a simple storage pool type @code{SSP}, nonabstract primitive subprograms
7625@code{Allocate}, @code{Deallocate}, and @code{Storage_Size} can be declared that
7626are subtype conformant with the following subprogram declarations:
7627
7628@example
7629procedure Allocate
7630  (Pool                     : in out SSP;
7631   Storage_Address          : out System.Address;
7632   Size_In_Storage_Elements : System.Storage_Elements.Storage_Count;
7633   Alignment                : System.Storage_Elements.Storage_Count);
7634
7635procedure Deallocate
7636  (Pool : in out SSP;
7637   Storage_Address          : System.Address;
7638   Size_In_Storage_Elements : System.Storage_Elements.Storage_Count;
7639   Alignment                : System.Storage_Elements.Storage_Count);
7640
7641function Storage_Size (Pool : SSP)
7642  return System.Storage_Elements.Storage_Count;
7643@end example
7644
7645Procedure @code{Allocate} must be declared, whereas @code{Deallocate} and
7646@code{Storage_Size} are optional. If @code{Deallocate} is not declared, then
7647applying an unchecked deallocation has no effect other than to set its actual
7648parameter to null. If @code{Storage_Size} is not declared, then the
7649@code{Storage_Size} attribute applied to an access type associated with
7650a pool object of type SSP returns zero. Additional operations can be declared
7651for a simple storage pool type (such as for supporting a mark/release
7652storage-management discipline).
7653
7654An object of a simple storage pool type can be associated with an access
7655type by specifying the attribute
7656@ref{e5,,Simple_Storage_Pool}. For example:
7657
7658@example
7659My_Pool : My_Simple_Storage_Pool_Type;
7660
7661type Acc is access My_Data_Type;
7662
7663for Acc'Simple_Storage_Pool use My_Pool;
7664@end example
7665
7666See attribute @ref{e5,,Simple_Storage_Pool}
7667for further details.
7668
7669@node Pragma Source_File_Name,Pragma Source_File_Name_Project,Pragma Simple_Storage_Pool_Type,Implementation Defined Pragmas
7670@anchor{gnat_rm/implementation_defined_pragmas id40}@anchor{e6}@anchor{gnat_rm/implementation_defined_pragmas pragma-source-file-name}@anchor{e7}
7671@section Pragma Source_File_Name
7672
7673
7674Syntax:
7675
7676@example
7677pragma Source_File_Name (
7678  [Unit_Name   =>] unit_NAME,
7679  Spec_File_Name =>  STRING_LITERAL,
7680  [Index => INTEGER_LITERAL]);
7681
7682pragma Source_File_Name (
7683  [Unit_Name   =>] unit_NAME,
7684  Body_File_Name =>  STRING_LITERAL,
7685  [Index => INTEGER_LITERAL]);
7686@end example
7687
7688Use this to override the normal naming convention.  It is a configuration
7689pragma, and so has the usual applicability of configuration pragmas
7690(i.e., it applies to either an entire partition, or to all units in a
7691compilation, or to a single unit, depending on how it is used.
7692@code{unit_name} is mapped to @code{file_name_literal}.  The identifier for
7693the second argument is required, and indicates whether this is the file
7694name for the spec or for the body.
7695
7696The optional Index argument should be used when a file contains multiple
7697units, and when you do not want to use @code{gnatchop} to separate then
7698into multiple files (which is the recommended procedure to limit the
7699number of recompilations that are needed when some sources change).
7700For instance, if the source file @code{source.ada} contains
7701
7702@example
7703package B is
7704...
7705end B;
7706
7707with B;
7708procedure A is
7709begin
7710   ..
7711end A;
7712@end example
7713
7714you could use the following configuration pragmas:
7715
7716@example
7717pragma Source_File_Name
7718  (B, Spec_File_Name => "source.ada", Index => 1);
7719pragma Source_File_Name
7720  (A, Body_File_Name => "source.ada", Index => 2);
7721@end example
7722
7723Note that the @code{gnatname} utility can also be used to generate those
7724configuration pragmas.
7725
7726Another form of the @code{Source_File_Name} pragma allows
7727the specification of patterns defining alternative file naming schemes
7728to apply to all files.
7729
7730@example
7731pragma Source_File_Name
7732  (  [Spec_File_Name  =>] STRING_LITERAL
7733   [,[Casing          =>] CASING_SPEC]
7734   [,[Dot_Replacement =>] STRING_LITERAL]);
7735
7736pragma Source_File_Name
7737  (  [Body_File_Name  =>] STRING_LITERAL
7738   [,[Casing          =>] CASING_SPEC]
7739   [,[Dot_Replacement =>] STRING_LITERAL]);
7740
7741pragma Source_File_Name
7742  (  [Subunit_File_Name =>] STRING_LITERAL
7743   [,[Casing            =>] CASING_SPEC]
7744   [,[Dot_Replacement   =>] STRING_LITERAL]);
7745
7746CASING_SPEC ::= Lowercase | Uppercase | Mixedcase
7747@end example
7748
7749The first argument is a pattern that contains a single asterisk indicating
7750the point at which the unit name is to be inserted in the pattern string
7751to form the file name.  The second argument is optional.  If present it
7752specifies the casing of the unit name in the resulting file name string.
7753The default is lower case.  Finally the third argument allows for systematic
7754replacement of any dots in the unit name by the specified string literal.
7755
7756Note that Source_File_Name pragmas should not be used if you are using
7757project files. The reason for this rule is that the project manager is not
7758aware of these pragmas, and so other tools that use the projet file would not
7759be aware of the intended naming conventions. If you are using project files,
7760file naming is controlled by Source_File_Name_Project pragmas, which are
7761usually supplied automatically by the project manager. A pragma
7762Source_File_Name cannot appear after a @ref{e8,,Pragma Source_File_Name_Project}.
7763
7764For more details on the use of the @code{Source_File_Name} pragma, see the
7765sections on @cite{Using Other File Names} and @cite{Alternative File Naming Schemes}
7766in the @cite{GNAT User’s Guide}.
7767
7768@node Pragma Source_File_Name_Project,Pragma Source_Reference,Pragma Source_File_Name,Implementation Defined Pragmas
7769@anchor{gnat_rm/implementation_defined_pragmas id41}@anchor{e9}@anchor{gnat_rm/implementation_defined_pragmas pragma-source-file-name-project}@anchor{e8}
7770@section Pragma Source_File_Name_Project
7771
7772
7773This pragma has the same syntax and semantics as pragma Source_File_Name.
7774It is only allowed as a stand-alone configuration pragma.
7775It cannot appear after a @ref{e7,,Pragma Source_File_Name}, and
7776most importantly, once pragma Source_File_Name_Project appears,
7777no further Source_File_Name pragmas are allowed.
7778
7779The intention is that Source_File_Name_Project pragmas are always
7780generated by the Project Manager in a manner consistent with the naming
7781specified in a project file, and when naming is controlled in this manner,
7782it is not permissible to attempt to modify this naming scheme using
7783Source_File_Name or Source_File_Name_Project pragmas (which would not be
7784known to the project manager).
7785
7786@node Pragma Source_Reference,Pragma SPARK_Mode,Pragma Source_File_Name_Project,Implementation Defined Pragmas
7787@anchor{gnat_rm/implementation_defined_pragmas pragma-source-reference}@anchor{ea}
7788@section Pragma Source_Reference
7789
7790
7791Syntax:
7792
7793@example
7794pragma Source_Reference (INTEGER_LITERAL, STRING_LITERAL);
7795@end example
7796
7797This pragma must appear as the first line of a source file.
7798@code{integer_literal} is the logical line number of the line following
7799the pragma line (for use in error messages and debugging
7800information).  @code{string_literal} is a static string constant that
7801specifies the file name to be used in error messages and debugging
7802information.  This is most notably used for the output of @code{gnatchop}
7803with the @emph{-r} switch, to make sure that the original unchopped
7804source file is the one referred to.
7805
7806The second argument must be a string literal, it cannot be a static
7807string expression other than a string literal.  This is because its value
7808is needed for error messages issued by all phases of the compiler.
7809
7810@node Pragma SPARK_Mode,Pragma Static_Elaboration_Desired,Pragma Source_Reference,Implementation Defined Pragmas
7811@anchor{gnat_rm/implementation_defined_pragmas id42}@anchor{eb}@anchor{gnat_rm/implementation_defined_pragmas pragma-spark-mode}@anchor{ec}
7812@section Pragma SPARK_Mode
7813
7814
7815Syntax:
7816
7817@example
7818pragma SPARK_Mode [(On | Off)] ;
7819@end example
7820
7821In general a program can have some parts that are in SPARK 2014 (and
7822follow all the rules in the SPARK Reference Manual), and some parts
7823that are full Ada 2012.
7824
7825The SPARK_Mode pragma is used to identify which parts are in SPARK
78262014 (by default programs are in full Ada). The SPARK_Mode pragma can
7827be used in the following places:
7828
7829
7830@itemize *
7831
7832@item
7833As a configuration pragma, in which case it sets the default mode for
7834all units compiled with this pragma.
7835
7836@item
7837Immediately following a library-level subprogram spec
7838
7839@item
7840Immediately within a library-level package body
7841
7842@item
7843Immediately following the @code{private} keyword of a library-level
7844package spec
7845
7846@item
7847Immediately following the @code{begin} keyword of a library-level
7848package body
7849
7850@item
7851Immediately within a library-level subprogram body
7852@end itemize
7853
7854Normally a subprogram or package spec/body inherits the current mode
7855that is active at the point it is declared. But this can be overridden
7856by pragma within the spec or body as above.
7857
7858The basic consistency rule is that you can’t turn SPARK_Mode back
7859@code{On}, once you have explicitly (with a pragma) turned if
7860@code{Off}. So the following rules apply:
7861
7862If a subprogram spec has SPARK_Mode @code{Off}, then the body must
7863also have SPARK_Mode @code{Off}.
7864
7865For a package, we have four parts:
7866
7867
7868@itemize *
7869
7870@item
7871the package public declarations
7872
7873@item
7874the package private part
7875
7876@item
7877the body of the package
7878
7879@item
7880the elaboration code after @code{begin}
7881@end itemize
7882
7883For a package, the rule is that if you explicitly turn SPARK_Mode
7884@code{Off} for any part, then all the following parts must have
7885SPARK_Mode @code{Off}. Note that this may require repeating a pragma
7886SPARK_Mode (@code{Off}) in the body. For example, if we have a
7887configuration pragma SPARK_Mode (@code{On}) that turns the mode on by
7888default everywhere, and one particular package spec has pragma
7889SPARK_Mode (@code{Off}), then that pragma will need to be repeated in
7890the package body.
7891
7892@node Pragma Static_Elaboration_Desired,Pragma Stream_Convert,Pragma SPARK_Mode,Implementation Defined Pragmas
7893@anchor{gnat_rm/implementation_defined_pragmas pragma-static-elaboration-desired}@anchor{ed}
7894@section Pragma Static_Elaboration_Desired
7895
7896
7897Syntax:
7898
7899@example
7900pragma Static_Elaboration_Desired;
7901@end example
7902
7903This pragma is used to indicate that the compiler should attempt to initialize
7904statically the objects declared in the library unit to which the pragma applies,
7905when these objects are initialized (explicitly or implicitly) by an aggregate.
7906In the absence of this pragma, aggregates in object declarations are expanded
7907into assignments and loops, even when the aggregate components are static
7908constants. When the aggregate is present the compiler builds a static expression
7909that requires no run-time code, so that the initialized object can be placed in
7910read-only data space. If the components are not static, or the aggregate has
7911more that 100 components, the compiler emits a warning that the pragma cannot
7912be obeyed. (See also the restriction No_Implicit_Loops, which supports static
7913construction of larger aggregates with static components that include an others
7914choice.)
7915
7916@node Pragma Stream_Convert,Pragma Style_Checks,Pragma Static_Elaboration_Desired,Implementation Defined Pragmas
7917@anchor{gnat_rm/implementation_defined_pragmas pragma-stream-convert}@anchor{ee}
7918@section Pragma Stream_Convert
7919
7920
7921Syntax:
7922
7923@example
7924pragma Stream_Convert (
7925  [Entity =>] type_LOCAL_NAME,
7926  [Read   =>] function_NAME,
7927  [Write  =>] function_NAME);
7928@end example
7929
7930This pragma provides an efficient way of providing user-defined stream
7931attributes.  Not only is it simpler to use than specifying the attributes
7932directly, but more importantly, it allows the specification to be made in such
7933a way that the predefined unit Ada.Streams is not loaded unless it is actually
7934needed (i.e. unless the stream attributes are actually used); the use of
7935the Stream_Convert pragma adds no overhead at all, unless the stream
7936attributes are actually used on the designated type.
7937
7938The first argument specifies the type for which stream functions are
7939provided.  The second parameter provides a function used to read values
7940of this type.  It must name a function whose argument type may be any
7941subtype, and whose returned type must be the type given as the first
7942argument to the pragma.
7943
7944The meaning of the @code{Read} parameter is that if a stream attribute directly
7945or indirectly specifies reading of the type given as the first parameter,
7946then a value of the type given as the argument to the Read function is
7947read from the stream, and then the Read function is used to convert this
7948to the required target type.
7949
7950Similarly the @code{Write} parameter specifies how to treat write attributes
7951that directly or indirectly apply to the type given as the first parameter.
7952It must have an input parameter of the type specified by the first parameter,
7953and the return type must be the same as the input type of the Read function.
7954The effect is to first call the Write function to convert to the given stream
7955type, and then write the result type to the stream.
7956
7957The Read and Write functions must not be overloaded subprograms.  If necessary
7958renamings can be supplied to meet this requirement.
7959The usage of this attribute is best illustrated by a simple example, taken
7960from the GNAT implementation of package Ada.Strings.Unbounded:
7961
7962@example
7963function To_Unbounded (S : String) return Unbounded_String
7964  renames To_Unbounded_String;
7965
7966pragma Stream_Convert
7967  (Unbounded_String, To_Unbounded, To_String);
7968@end example
7969
7970The specifications of the referenced functions, as given in the Ada
7971Reference Manual are:
7972
7973@example
7974function To_Unbounded_String (Source : String)
7975  return Unbounded_String;
7976
7977function To_String (Source : Unbounded_String)
7978  return String;
7979@end example
7980
7981The effect is that if the value of an unbounded string is written to a stream,
7982then the representation of the item in the stream is in the same format that
7983would be used for @code{Standard.String'Output}, and this same representation
7984is expected when a value of this type is read from the stream. Note that the
7985value written always includes the bounds, even for Unbounded_String’Write,
7986since Unbounded_String is not an array type.
7987
7988Note that the @code{Stream_Convert} pragma is not effective in the case of
7989a derived type of a non-limited tagged type. If such a type is specified then
7990the pragma is silently ignored, and the default implementation of the stream
7991attributes is used instead.
7992
7993@node Pragma Style_Checks,Pragma Subtitle,Pragma Stream_Convert,Implementation Defined Pragmas
7994@anchor{gnat_rm/implementation_defined_pragmas pragma-style-checks}@anchor{ef}
7995@section Pragma Style_Checks
7996
7997
7998Syntax:
7999
8000@example
8001pragma Style_Checks (string_LITERAL | ALL_CHECKS |
8002                     On | Off [, LOCAL_NAME]);
8003@end example
8004
8005This pragma is used in conjunction with compiler switches to control the
8006built in style checking provided by GNAT.  The compiler switches, if set,
8007provide an initial setting for the switches, and this pragma may be used
8008to modify these settings, or the settings may be provided entirely by
8009the use of the pragma.  This pragma can be used anywhere that a pragma
8010is legal, including use as a configuration pragma (including use in
8011the @code{gnat.adc} file).
8012
8013The form with a string literal specifies which style options are to be
8014activated.  These are additive, so they apply in addition to any previously
8015set style check options.  The codes for the options are the same as those
8016used in the @emph{-gnaty} switch to @emph{gcc} or @emph{gnatmake}.
8017For example the following two methods can be used to enable
8018layout checking:
8019
8020
8021@itemize *
8022
8023@item
8024@example
8025pragma Style_Checks ("l");
8026@end example
8027
8028@item
8029@example
8030gcc -c -gnatyl ...
8031@end example
8032@end itemize
8033
8034The form @code{ALL_CHECKS} activates all standard checks (its use is equivalent
8035to the use of the @code{gnaty} switch with no options.
8036See the @cite{GNAT User’s Guide} for details.)
8037
8038Note: the behavior is slightly different in GNAT mode (@code{-gnatg} used).
8039In this case, @code{ALL_CHECKS} implies the standard set of GNAT mode style check
8040options (i.e. equivalent to @code{-gnatyg}).
8041
8042The forms with @code{Off} and @code{On}
8043can be used to temporarily disable style checks
8044as shown in the following example:
8045
8046@example
8047pragma Style_Checks ("k"); -- requires keywords in lower case
8048pragma Style_Checks (Off); -- turn off style checks
8049NULL;                      -- this will not generate an error message
8050pragma Style_Checks (On);  -- turn style checks back on
8051NULL;                      -- this will generate an error message
8052@end example
8053
8054Finally the two argument form is allowed only if the first argument is
8055@code{On} or @code{Off}.  The effect is to turn of semantic style checks
8056for the specified entity, as shown in the following example:
8057
8058@example
8059pragma Style_Checks ("r"); -- require consistency of identifier casing
8060Arg : Integer;
8061Rf1 : Integer := ARG;      -- incorrect, wrong case
8062pragma Style_Checks (Off, Arg);
8063Rf2 : Integer := ARG;      -- OK, no error
8064@end example
8065
8066@node Pragma Subtitle,Pragma Suppress,Pragma Style_Checks,Implementation Defined Pragmas
8067@anchor{gnat_rm/implementation_defined_pragmas pragma-subtitle}@anchor{f0}
8068@section Pragma Subtitle
8069
8070
8071Syntax:
8072
8073@example
8074pragma Subtitle ([Subtitle =>] STRING_LITERAL);
8075@end example
8076
8077This pragma is recognized for compatibility with other Ada compilers
8078but is ignored by GNAT.
8079
8080@node Pragma Suppress,Pragma Suppress_All,Pragma Subtitle,Implementation Defined Pragmas
8081@anchor{gnat_rm/implementation_defined_pragmas pragma-suppress}@anchor{f1}
8082@section Pragma Suppress
8083
8084
8085Syntax:
8086
8087@example
8088pragma Suppress (Identifier [, [On =>] Name]);
8089@end example
8090
8091This is a standard pragma, and supports all the check names required in
8092the RM. It is included here because GNAT recognizes some additional check
8093names that are implementation defined (as permitted by the RM):
8094
8095
8096@itemize *
8097
8098@item
8099@code{Alignment_Check} can be used to suppress alignment checks
8100on addresses used in address clauses. Such checks can also be suppressed
8101by suppressing range checks, but the specific use of @code{Alignment_Check}
8102allows suppression of alignment checks without suppressing other range checks.
8103Note that @code{Alignment_Check} is suppressed by default on machines (such as
8104the x86) with non-strict alignment.
8105
8106@item
8107@code{Atomic_Synchronization} can be used to suppress the special memory
8108synchronization instructions that are normally generated for access to
8109@code{Atomic} variables to ensure correct synchronization between tasks
8110that use such variables for synchronization purposes.
8111
8112@item
8113@code{Duplicated_Tag_Check} Can be used to suppress the check that is generated
8114for a duplicated tag value when a tagged type is declared.
8115
8116@item
8117@code{Container_Checks} Can be used to suppress all checks within Ada.Containers
8118and instances of its children, including Tampering_Check.
8119
8120@item
8121@code{Tampering_Check} Can be used to suppress tampering check in the containers.
8122
8123@item
8124@code{Predicate_Check} can be used to control whether predicate checks are
8125active. It is applicable only to predicates for which the policy is
8126@code{Check}. Unlike @code{Assertion_Policy}, which determines if a given
8127predicate is ignored or checked for the whole program, the use of
8128@code{Suppress} and @code{Unsuppress} with this check name allows a given
8129predicate to be turned on and off at specific points in the program.
8130
8131@item
8132@code{Validity_Check} can be used specifically to control validity checks.
8133If @code{Suppress} is used to suppress validity checks, then no validity
8134checks are performed, including those specified by the appropriate compiler
8135switch or the @code{Validity_Checks} pragma.
8136
8137@item
8138Additional check names previously introduced by use of the @code{Check_Name}
8139pragma are also allowed.
8140@end itemize
8141
8142Note that pragma Suppress gives the compiler permission to omit
8143checks, but does not require the compiler to omit checks. The compiler
8144will generate checks if they are essentially free, even when they are
8145suppressed. In particular, if the compiler can prove that a certain
8146check will necessarily fail, it will generate code to do an
8147unconditional ‘raise’, even if checks are suppressed. The compiler
8148warns in this case.
8149
8150Of course, run-time checks are omitted whenever the compiler can prove
8151that they will not fail, whether or not checks are suppressed.
8152
8153@node Pragma Suppress_All,Pragma Suppress_Debug_Info,Pragma Suppress,Implementation Defined Pragmas
8154@anchor{gnat_rm/implementation_defined_pragmas pragma-suppress-all}@anchor{f2}
8155@section Pragma Suppress_All
8156
8157
8158Syntax:
8159
8160@example
8161pragma Suppress_All;
8162@end example
8163
8164This pragma can appear anywhere within a unit.
8165The effect is to apply @code{Suppress (All_Checks)} to the unit
8166in which it appears.  This pragma is implemented for compatibility with DEC
8167Ada 83 usage where it appears at the end of a unit, and for compatibility
8168with Rational Ada, where it appears as a program unit pragma.
8169The use of the standard Ada pragma @code{Suppress (All_Checks)}
8170as a normal configuration pragma is the preferred usage in GNAT.
8171
8172@node Pragma Suppress_Debug_Info,Pragma Suppress_Exception_Locations,Pragma Suppress_All,Implementation Defined Pragmas
8173@anchor{gnat_rm/implementation_defined_pragmas id43}@anchor{f3}@anchor{gnat_rm/implementation_defined_pragmas pragma-suppress-debug-info}@anchor{f4}
8174@section Pragma Suppress_Debug_Info
8175
8176
8177Syntax:
8178
8179@example
8180pragma Suppress_Debug_Info ([Entity =>] LOCAL_NAME);
8181@end example
8182
8183This pragma can be used to suppress generation of debug information
8184for the specified entity. It is intended primarily for use in debugging
8185the debugger, and navigating around debugger problems.
8186
8187@node Pragma Suppress_Exception_Locations,Pragma Suppress_Initialization,Pragma Suppress_Debug_Info,Implementation Defined Pragmas
8188@anchor{gnat_rm/implementation_defined_pragmas pragma-suppress-exception-locations}@anchor{f5}
8189@section Pragma Suppress_Exception_Locations
8190
8191
8192Syntax:
8193
8194@example
8195pragma Suppress_Exception_Locations;
8196@end example
8197
8198In normal mode, a raise statement for an exception by default generates
8199an exception message giving the file name and line number for the location
8200of the raise. This is useful for debugging and logging purposes, but this
8201entails extra space for the strings for the messages. The configuration
8202pragma @code{Suppress_Exception_Locations} can be used to suppress the
8203generation of these strings, with the result that space is saved, but the
8204exception message for such raises is null. This configuration pragma may
8205appear in a global configuration pragma file, or in a specific unit as
8206usual. It is not required that this pragma be used consistently within
8207a partition, so it is fine to have some units within a partition compiled
8208with this pragma and others compiled in normal mode without it.
8209
8210@node Pragma Suppress_Initialization,Pragma Task_Name,Pragma Suppress_Exception_Locations,Implementation Defined Pragmas
8211@anchor{gnat_rm/implementation_defined_pragmas id44}@anchor{f6}@anchor{gnat_rm/implementation_defined_pragmas pragma-suppress-initialization}@anchor{f7}
8212@section Pragma Suppress_Initialization
8213
8214
8215@geindex Suppressing initialization
8216
8217@geindex Initialization
8218@geindex suppression of
8219
8220Syntax:
8221
8222@example
8223pragma Suppress_Initialization ([Entity =>] variable_or_subtype_Name);
8224@end example
8225
8226Here variable_or_subtype_Name is the name introduced by a type declaration
8227or subtype declaration or the name of a variable introduced by an
8228object declaration.
8229
8230In the case of a type or subtype
8231this pragma suppresses any implicit or explicit initialization
8232for all variables of the given type or subtype,
8233including initialization resulting from the use of pragmas
8234Normalize_Scalars or Initialize_Scalars.
8235
8236This is considered a representation item, so it cannot be given after
8237the type is frozen. It applies to all subsequent object declarations,
8238and also any allocator that creates objects of the type.
8239
8240If the pragma is given for the first subtype, then it is considered
8241to apply to the base type and all its subtypes. If the pragma is given
8242for other than a first subtype, then it applies only to the given subtype.
8243The pragma may not be given after the type is frozen.
8244
8245Note that this includes eliminating initialization of discriminants
8246for discriminated types, and tags for tagged types. In these cases,
8247you will have to use some non-portable mechanism (e.g. address
8248overlays or unchecked conversion) to achieve required initialization
8249of these fields before accessing any object of the corresponding type.
8250
8251For the variable case, implicit initialization for the named variable
8252is suppressed, just as though its subtype had been given in a pragma
8253Suppress_Initialization, as described above.
8254
8255@node Pragma Task_Name,Pragma Task_Storage,Pragma Suppress_Initialization,Implementation Defined Pragmas
8256@anchor{gnat_rm/implementation_defined_pragmas pragma-task-name}@anchor{f8}
8257@section Pragma Task_Name
8258
8259
8260Syntax
8261
8262@example
8263pragma Task_Name (string_EXPRESSION);
8264@end example
8265
8266This pragma appears within a task definition (like pragma
8267@code{Priority}) and applies to the task in which it appears.  The
8268argument must be of type String, and provides a name to be used for
8269the task instance when the task is created.  Note that this expression
8270is not required to be static, and in particular, it can contain
8271references to task discriminants.  This facility can be used to
8272provide different names for different tasks as they are created,
8273as illustrated in the example below.
8274
8275The task name is recorded internally in the run-time structures
8276and is accessible to tools like the debugger.  In addition the
8277routine @code{Ada.Task_Identification.Image} will return this
8278string, with a unique task address appended.
8279
8280@example
8281--  Example of the use of pragma Task_Name
8282
8283with Ada.Task_Identification;
8284use Ada.Task_Identification;
8285with Text_IO; use Text_IO;
8286procedure t3 is
8287
8288   type Astring is access String;
8289
8290   task type Task_Typ (Name : access String) is
8291      pragma Task_Name (Name.all);
8292   end Task_Typ;
8293
8294   task body Task_Typ is
8295      Nam : constant String := Image (Current_Task);
8296   begin
8297      Put_Line ("-->" & Nam (1 .. 14) & "<--");
8298   end Task_Typ;
8299
8300   type Ptr_Task is access Task_Typ;
8301   Task_Var : Ptr_Task;
8302
8303begin
8304   Task_Var :=
8305     new Task_Typ (new String'("This is task 1"));
8306   Task_Var :=
8307     new Task_Typ (new String'("This is task 2"));
8308end;
8309@end example
8310
8311@node Pragma Task_Storage,Pragma Test_Case,Pragma Task_Name,Implementation Defined Pragmas
8312@anchor{gnat_rm/implementation_defined_pragmas pragma-task-storage}@anchor{f9}
8313@section Pragma Task_Storage
8314
8315
8316Syntax:
8317
8318@example
8319pragma Task_Storage (
8320  [Task_Type =>] LOCAL_NAME,
8321  [Top_Guard =>] static_integer_EXPRESSION);
8322@end example
8323
8324This pragma specifies the length of the guard area for tasks.  The guard
8325area is an additional storage area allocated to a task.  A value of zero
8326means that either no guard area is created or a minimal guard area is
8327created, depending on the target.  This pragma can appear anywhere a
8328@code{Storage_Size} attribute definition clause is allowed for a task
8329type.
8330
8331@node Pragma Test_Case,Pragma Thread_Local_Storage,Pragma Task_Storage,Implementation Defined Pragmas
8332@anchor{gnat_rm/implementation_defined_pragmas id45}@anchor{fa}@anchor{gnat_rm/implementation_defined_pragmas pragma-test-case}@anchor{fb}
8333@section Pragma Test_Case
8334
8335
8336@geindex Test cases
8337
8338Syntax:
8339
8340@example
8341pragma Test_Case (
8342   [Name     =>] static_string_Expression
8343  ,[Mode     =>] (Nominal | Robustness)
8344 [, Requires =>  Boolean_Expression]
8345 [, Ensures  =>  Boolean_Expression]);
8346@end example
8347
8348The @code{Test_Case} pragma allows defining fine-grain specifications
8349for use by testing tools.
8350The compiler checks the validity of the @code{Test_Case} pragma, but its
8351presence does not lead to any modification of the code generated by the
8352compiler.
8353
8354@code{Test_Case} pragmas may only appear immediately following the
8355(separate) declaration of a subprogram in a package declaration, inside
8356a package spec unit. Only other pragmas may intervene (that is appear
8357between the subprogram declaration and a test case).
8358
8359The compiler checks that boolean expressions given in @code{Requires} and
8360@code{Ensures} are valid, where the rules for @code{Requires} are the
8361same as the rule for an expression in @code{Precondition} and the rules
8362for @code{Ensures} are the same as the rule for an expression in
8363@code{Postcondition}. In particular, attributes @code{'Old} and
8364@code{'Result} can only be used within the @code{Ensures}
8365expression. The following is an example of use within a package spec:
8366
8367@example
8368package Math_Functions is
8369   ...
8370   function Sqrt (Arg : Float) return Float;
8371   pragma Test_Case (Name     => "Test 1",
8372                     Mode     => Nominal,
8373                     Requires => Arg < 10000.0,
8374                     Ensures  => Sqrt'Result < 10.0);
8375   ...
8376end Math_Functions;
8377@end example
8378
8379The meaning of a test case is that there is at least one context where
8380@code{Requires} holds such that, if the associated subprogram is executed in
8381that context, then @code{Ensures} holds when the subprogram returns.
8382Mode @code{Nominal} indicates that the input context should also satisfy the
8383precondition of the subprogram, and the output context should also satisfy its
8384postcondition. Mode @code{Robustness} indicates that the precondition and
8385postcondition of the subprogram should be ignored for this test case.
8386
8387@node Pragma Thread_Local_Storage,Pragma Time_Slice,Pragma Test_Case,Implementation Defined Pragmas
8388@anchor{gnat_rm/implementation_defined_pragmas id46}@anchor{fc}@anchor{gnat_rm/implementation_defined_pragmas pragma-thread-local-storage}@anchor{fd}
8389@section Pragma Thread_Local_Storage
8390
8391
8392@geindex Task specific storage
8393
8394@geindex TLS (Thread Local Storage)
8395
8396@geindex Task_Attributes
8397
8398Syntax:
8399
8400@example
8401pragma Thread_Local_Storage ([Entity =>] LOCAL_NAME);
8402@end example
8403
8404This pragma specifies that the specified entity, which must be
8405a variable declared in a library-level package, is to be marked as
8406“Thread Local Storage” (@code{TLS}). On systems supporting this (which
8407include Windows, Solaris, GNU/Linux, and VxWorks 6), this causes each
8408thread (and hence each Ada task) to see a distinct copy of the variable.
8409
8410The variable must not have default initialization, and if there is
8411an explicit initialization, it must be either @code{null} for an
8412access variable, a static expression for a scalar variable, or a fully
8413static aggregate for a composite type, that is to say, an aggregate all
8414of whose components are static, and which does not include packed or
8415discriminated components.
8416
8417This provides a low-level mechanism similar to that provided by
8418the @code{Ada.Task_Attributes} package, but much more efficient
8419and is also useful in writing interface code that will interact
8420with foreign threads.
8421
8422If this pragma is used on a system where @code{TLS} is not supported,
8423then an error message will be generated and the program will be rejected.
8424
8425@node Pragma Time_Slice,Pragma Title,Pragma Thread_Local_Storage,Implementation Defined Pragmas
8426@anchor{gnat_rm/implementation_defined_pragmas pragma-time-slice}@anchor{fe}
8427@section Pragma Time_Slice
8428
8429
8430Syntax:
8431
8432@example
8433pragma Time_Slice (static_duration_EXPRESSION);
8434@end example
8435
8436For implementations of GNAT on operating systems where it is possible
8437to supply a time slice value, this pragma may be used for this purpose.
8438It is ignored if it is used in a system that does not allow this control,
8439or if it appears in other than the main program unit.
8440
8441@node Pragma Title,Pragma Type_Invariant,Pragma Time_Slice,Implementation Defined Pragmas
8442@anchor{gnat_rm/implementation_defined_pragmas pragma-title}@anchor{ff}
8443@section Pragma Title
8444
8445
8446Syntax:
8447
8448@example
8449pragma Title (TITLING_OPTION [, TITLING OPTION]);
8450
8451TITLING_OPTION ::=
8452  [Title    =>] STRING_LITERAL,
8453| [Subtitle =>] STRING_LITERAL
8454@end example
8455
8456Syntax checked but otherwise ignored by GNAT.  This is a listing control
8457pragma used in DEC Ada 83 implementations to provide a title and/or
8458subtitle for the program listing.  The program listing generated by GNAT
8459does not have titles or subtitles.
8460
8461Unlike other pragmas, the full flexibility of named notation is allowed
8462for this pragma, i.e., the parameters may be given in any order if named
8463notation is used, and named and positional notation can be mixed
8464following the normal rules for procedure calls in Ada.
8465
8466@node Pragma Type_Invariant,Pragma Type_Invariant_Class,Pragma Title,Implementation Defined Pragmas
8467@anchor{gnat_rm/implementation_defined_pragmas pragma-type-invariant}@anchor{100}
8468@section Pragma Type_Invariant
8469
8470
8471Syntax:
8472
8473@example
8474pragma Type_Invariant
8475  ([Entity =>] type_LOCAL_NAME,
8476   [Check  =>] EXPRESSION);
8477@end example
8478
8479The @code{Type_Invariant} pragma is intended to be an exact
8480replacement for the language-defined @code{Type_Invariant}
8481aspect, and shares its restrictions and semantics. It differs
8482from the language defined @code{Invariant} pragma in that it
8483does not permit a string parameter, and it is
8484controlled by the assertion identifier @code{Type_Invariant}
8485rather than @code{Invariant}.
8486
8487@node Pragma Type_Invariant_Class,Pragma Unchecked_Union,Pragma Type_Invariant,Implementation Defined Pragmas
8488@anchor{gnat_rm/implementation_defined_pragmas id47}@anchor{101}@anchor{gnat_rm/implementation_defined_pragmas pragma-type-invariant-class}@anchor{102}
8489@section Pragma Type_Invariant_Class
8490
8491
8492Syntax:
8493
8494@example
8495pragma Type_Invariant_Class
8496  ([Entity =>] type_LOCAL_NAME,
8497   [Check  =>] EXPRESSION);
8498@end example
8499
8500The @code{Type_Invariant_Class} pragma is intended to be an exact
8501replacement for the language-defined @code{Type_Invariant'Class}
8502aspect, and shares its restrictions and semantics.
8503
8504Note: This pragma is called @code{Type_Invariant_Class} rather than
8505@code{Type_Invariant'Class} because the latter would not be strictly
8506conforming to the allowed syntax for pragmas. The motivation
8507for providing pragmas equivalent to the aspects is to allow a program
8508to be written using the pragmas, and then compiled if necessary
8509using an Ada compiler that does not recognize the pragmas or
8510aspects, but is prepared to ignore the pragmas. The assertion
8511policy that controls this pragma is @code{Type_Invariant'Class},
8512not @code{Type_Invariant_Class}.
8513
8514@node Pragma Unchecked_Union,Pragma Unevaluated_Use_Of_Old,Pragma Type_Invariant_Class,Implementation Defined Pragmas
8515@anchor{gnat_rm/implementation_defined_pragmas pragma-unchecked-union}@anchor{103}
8516@section Pragma Unchecked_Union
8517
8518
8519@geindex Unions in C
8520
8521Syntax:
8522
8523@example
8524pragma Unchecked_Union (first_subtype_LOCAL_NAME);
8525@end example
8526
8527This pragma is used to specify a representation of a record type that is
8528equivalent to a C union. It was introduced as a GNAT implementation defined
8529pragma in the GNAT Ada 95 mode. Ada 2005 includes an extended version of this
8530pragma, making it language defined, and GNAT fully implements this extended
8531version in all language modes (Ada 83, Ada 95, and Ada 2005). For full
8532details, consult the Ada 2012 Reference Manual, section B.3.3.
8533
8534@node Pragma Unevaluated_Use_Of_Old,Pragma Unimplemented_Unit,Pragma Unchecked_Union,Implementation Defined Pragmas
8535@anchor{gnat_rm/implementation_defined_pragmas pragma-unevaluated-use-of-old}@anchor{104}
8536@section Pragma Unevaluated_Use_Of_Old
8537
8538
8539@geindex Attribute Old
8540
8541@geindex Attribute Loop_Entry
8542
8543@geindex Unevaluated_Use_Of_Old
8544
8545Syntax:
8546
8547@example
8548pragma Unevaluated_Use_Of_Old (Error | Warn | Allow);
8549@end example
8550
8551This pragma controls the processing of attributes Old and Loop_Entry.
8552If either of these attributes is used in a potentially unevaluated
8553expression  (e.g. the then or else parts of an if expression), then
8554normally this usage is considered illegal if the prefix of the attribute
8555is other than an entity name. The language requires this
8556behavior for Old, and GNAT copies the same rule for Loop_Entry.
8557
8558The reason for this rule is that otherwise, we can have a situation
8559where we save the Old value, and this results in an exception, even
8560though we might not evaluate the attribute. Consider this example:
8561
8562@example
8563package UnevalOld is
8564   K : Character;
8565   procedure U (A : String; C : Boolean)  -- ERROR
8566     with Post => (if C then A(1)'Old = K else True);
8567end;
8568@end example
8569
8570If procedure U is called with a string with a lower bound of 2, and
8571C false, then an exception would be raised trying to evaluate A(1)
8572on entry even though the value would not be actually used.
8573
8574Although the rule guarantees against this possibility, it is sometimes
8575too restrictive. For example if we know that the string has a lower
8576bound of 1, then we will never raise an exception.
8577The pragma @code{Unevaluated_Use_Of_Old} can be
8578used to modify this behavior. If the argument is @code{Error} then an
8579error is given (this is the default RM behavior). If the argument is
8580@code{Warn} then the usage is allowed as legal but with a warning
8581that an exception might be raised. If the argument is @code{Allow}
8582then the usage is allowed as legal without generating a warning.
8583
8584This pragma may appear as a configuration pragma, or in a declarative
8585part or package specification. In the latter case it applies to
8586uses up to the end of the corresponding statement sequence or
8587sequence of package declarations.
8588
8589@node Pragma Unimplemented_Unit,Pragma Universal_Aliasing,Pragma Unevaluated_Use_Of_Old,Implementation Defined Pragmas
8590@anchor{gnat_rm/implementation_defined_pragmas pragma-unimplemented-unit}@anchor{105}
8591@section Pragma Unimplemented_Unit
8592
8593
8594Syntax:
8595
8596@example
8597pragma Unimplemented_Unit;
8598@end example
8599
8600If this pragma occurs in a unit that is processed by the compiler, GNAT
8601aborts with the message @code{xxx not implemented}, where
8602@code{xxx} is the name of the current compilation unit.  This pragma is
8603intended to allow the compiler to handle unimplemented library units in
8604a clean manner.
8605
8606The abort only happens if code is being generated.  Thus you can use
8607specs of unimplemented packages in syntax or semantic checking mode.
8608
8609@node Pragma Universal_Aliasing,Pragma Unmodified,Pragma Unimplemented_Unit,Implementation Defined Pragmas
8610@anchor{gnat_rm/implementation_defined_pragmas id48}@anchor{106}@anchor{gnat_rm/implementation_defined_pragmas pragma-universal-aliasing}@anchor{107}
8611@section Pragma Universal_Aliasing
8612
8613
8614Syntax:
8615
8616@example
8617pragma Universal_Aliasing [([Entity =>] type_LOCAL_NAME)];
8618@end example
8619
8620@code{type_LOCAL_NAME} must refer to a type declaration in the current
8621declarative part.  The effect is to inhibit strict type-based aliasing
8622optimization for the given type.  In other words, the effect is as though
8623access types designating this type were subject to pragma No_Strict_Aliasing.
8624For a detailed description of the strict aliasing optimization, and the
8625situations in which it must be suppressed, see the section on
8626@code{Optimization and Strict Aliasing} in the @cite{GNAT User’s Guide}.
8627
8628@node Pragma Unmodified,Pragma Unreferenced,Pragma Universal_Aliasing,Implementation Defined Pragmas
8629@anchor{gnat_rm/implementation_defined_pragmas id49}@anchor{108}@anchor{gnat_rm/implementation_defined_pragmas pragma-unmodified}@anchor{109}
8630@section Pragma Unmodified
8631
8632
8633@geindex Warnings
8634@geindex unmodified
8635
8636Syntax:
8637
8638@example
8639pragma Unmodified (LOCAL_NAME @{, LOCAL_NAME@});
8640@end example
8641
8642This pragma signals that the assignable entities (variables,
8643@code{out} parameters, @code{in out} parameters) whose names are listed are
8644deliberately not assigned in the current source unit. This
8645suppresses warnings about the
8646entities being referenced but not assigned, and in addition a warning will be
8647generated if one of these entities is in fact assigned in the
8648same unit as the pragma (or in the corresponding body, or one
8649of its subunits).
8650
8651This is particularly useful for clearly signaling that a particular
8652parameter is not modified, even though the spec suggests that it might
8653be.
8654
8655For the variable case, warnings are never given for unreferenced variables
8656whose name contains one of the substrings
8657@code{DISCARD, DUMMY, IGNORE, JUNK, UNUSED} in any casing. Such names
8658are typically to be used in cases where such warnings are expected.
8659Thus it is never necessary to use @code{pragma Unmodified} for such
8660variables, though it is harmless to do so.
8661
8662@node Pragma Unreferenced,Pragma Unreferenced_Objects,Pragma Unmodified,Implementation Defined Pragmas
8663@anchor{gnat_rm/implementation_defined_pragmas id50}@anchor{10a}@anchor{gnat_rm/implementation_defined_pragmas pragma-unreferenced}@anchor{10b}
8664@section Pragma Unreferenced
8665
8666
8667@geindex Warnings
8668@geindex unreferenced
8669
8670Syntax:
8671
8672@example
8673pragma Unreferenced (LOCAL_NAME @{, LOCAL_NAME@});
8674pragma Unreferenced (library_unit_NAME @{, library_unit_NAME@});
8675@end example
8676
8677This pragma signals that the entities whose names are listed are
8678deliberately not referenced in the current source unit after the
8679occurrence of the pragma. This
8680suppresses warnings about the
8681entities being unreferenced, and in addition a warning will be
8682generated if one of these entities is in fact subsequently referenced in the
8683same unit as the pragma (or in the corresponding body, or one
8684of its subunits).
8685
8686This is particularly useful for clearly signaling that a particular
8687parameter is not referenced in some particular subprogram implementation
8688and that this is deliberate. It can also be useful in the case of
8689objects declared only for their initialization or finalization side
8690effects.
8691
8692If @code{LOCAL_NAME} identifies more than one matching homonym in the
8693current scope, then the entity most recently declared is the one to which
8694the pragma applies. Note that in the case of accept formals, the pragma
8695Unreferenced may appear immediately after the keyword @code{do} which
8696allows the indication of whether or not accept formals are referenced
8697or not to be given individually for each accept statement.
8698
8699The left hand side of an assignment does not count as a reference for the
8700purpose of this pragma. Thus it is fine to assign to an entity for which
8701pragma Unreferenced is given.
8702
8703Note that if a warning is desired for all calls to a given subprogram,
8704regardless of whether they occur in the same unit as the subprogram
8705declaration, then this pragma should not be used (calls from another
8706unit would not be flagged); pragma Obsolescent can be used instead
8707for this purpose, see @ref{ad,,Pragma Obsolescent}.
8708
8709The second form of pragma @code{Unreferenced} is used within a context
8710clause. In this case the arguments must be unit names of units previously
8711mentioned in @code{with} clauses (similar to the usage of pragma
8712@code{Elaborate_All}. The effect is to suppress warnings about unreferenced
8713units and unreferenced entities within these units.
8714
8715For the variable case, warnings are never given for unreferenced variables
8716whose name contains one of the substrings
8717@code{DISCARD, DUMMY, IGNORE, JUNK, UNUSED} in any casing. Such names
8718are typically to be used in cases where such warnings are expected.
8719Thus it is never necessary to use @code{pragma Unreferenced} for such
8720variables, though it is harmless to do so.
8721
8722@node Pragma Unreferenced_Objects,Pragma Unreserve_All_Interrupts,Pragma Unreferenced,Implementation Defined Pragmas
8723@anchor{gnat_rm/implementation_defined_pragmas id51}@anchor{10c}@anchor{gnat_rm/implementation_defined_pragmas pragma-unreferenced-objects}@anchor{10d}
8724@section Pragma Unreferenced_Objects
8725
8726
8727@geindex Warnings
8728@geindex unreferenced
8729
8730Syntax:
8731
8732@example
8733pragma Unreferenced_Objects (local_subtype_NAME @{, local_subtype_NAME@});
8734@end example
8735
8736This pragma signals that for the types or subtypes whose names are
8737listed, objects which are declared with one of these types or subtypes may
8738not be referenced, and if no references appear, no warnings are given.
8739
8740This is particularly useful for objects which are declared solely for their
8741initialization and finalization effect. Such variables are sometimes referred
8742to as RAII variables (Resource Acquisition Is Initialization). Using this
8743pragma on the relevant type (most typically a limited controlled type), the
8744compiler will automatically suppress unwanted warnings about these variables
8745not being referenced.
8746
8747@node Pragma Unreserve_All_Interrupts,Pragma Unsuppress,Pragma Unreferenced_Objects,Implementation Defined Pragmas
8748@anchor{gnat_rm/implementation_defined_pragmas pragma-unreserve-all-interrupts}@anchor{10e}
8749@section Pragma Unreserve_All_Interrupts
8750
8751
8752Syntax:
8753
8754@example
8755pragma Unreserve_All_Interrupts;
8756@end example
8757
8758Normally certain interrupts are reserved to the implementation.  Any attempt
8759to attach an interrupt causes Program_Error to be raised, as described in
8760RM C.3.2(22).  A typical example is the @code{SIGINT} interrupt used in
8761many systems for a @code{Ctrl-C} interrupt.  Normally this interrupt is
8762reserved to the implementation, so that @code{Ctrl-C} can be used to
8763interrupt execution.
8764
8765If the pragma @code{Unreserve_All_Interrupts} appears anywhere in any unit in
8766a program, then all such interrupts are unreserved.  This allows the
8767program to handle these interrupts, but disables their standard
8768functions.  For example, if this pragma is used, then pressing
8769@code{Ctrl-C} will not automatically interrupt execution.  However,
8770a program can then handle the @code{SIGINT} interrupt as it chooses.
8771
8772For a full list of the interrupts handled in a specific implementation,
8773see the source code for the spec of @code{Ada.Interrupts.Names} in
8774file @code{a-intnam.ads}.  This is a target dependent file that contains the
8775list of interrupts recognized for a given target.  The documentation in
8776this file also specifies what interrupts are affected by the use of
8777the @code{Unreserve_All_Interrupts} pragma.
8778
8779For a more general facility for controlling what interrupts can be
8780handled, see pragma @code{Interrupt_State}, which subsumes the functionality
8781of the @code{Unreserve_All_Interrupts} pragma.
8782
8783@node Pragma Unsuppress,Pragma Use_VADS_Size,Pragma Unreserve_All_Interrupts,Implementation Defined Pragmas
8784@anchor{gnat_rm/implementation_defined_pragmas pragma-unsuppress}@anchor{10f}
8785@section Pragma Unsuppress
8786
8787
8788Syntax:
8789
8790@example
8791pragma Unsuppress (IDENTIFIER [, [On =>] NAME]);
8792@end example
8793
8794This pragma undoes the effect of a previous pragma @code{Suppress}.  If
8795there is no corresponding pragma @code{Suppress} in effect, it has no
8796effect.  The range of the effect is the same as for pragma
8797@code{Suppress}.  The meaning of the arguments is identical to that used
8798in pragma @code{Suppress}.
8799
8800One important application is to ensure that checks are on in cases where
8801code depends on the checks for its correct functioning, so that the code
8802will compile correctly even if the compiler switches are set to suppress
8803checks. For example, in a program that depends on external names of tagged
8804types and wants to ensure that the duplicated tag check occurs even if all
8805run-time checks are suppressed by a compiler switch, the following
8806configuration pragma will ensure this test is not suppressed:
8807
8808@example
8809pragma Unsuppress (Duplicated_Tag_Check);
8810@end example
8811
8812This pragma is standard in Ada 2005. It is available in all earlier versions
8813of Ada as an implementation-defined pragma.
8814
8815Note that in addition to the checks defined in the Ada RM, GNAT recogizes a
8816number of implementation-defined check names. See the description of pragma
8817@code{Suppress} for full details.
8818
8819@node Pragma Use_VADS_Size,Pragma Unused,Pragma Unsuppress,Implementation Defined Pragmas
8820@anchor{gnat_rm/implementation_defined_pragmas pragma-use-vads-size}@anchor{110}
8821@section Pragma Use_VADS_Size
8822
8823
8824@geindex Size
8825@geindex VADS compatibility
8826
8827@geindex Rational profile
8828
8829Syntax:
8830
8831@example
8832pragma Use_VADS_Size;
8833@end example
8834
8835This is a configuration pragma.  In a unit to which it applies, any use
8836of the ‘Size attribute is automatically interpreted as a use of the
8837‘VADS_Size attribute.  Note that this may result in incorrect semantic
8838processing of valid Ada 95 or Ada 2005 programs.  This is intended to aid in
8839the handling of existing code which depends on the interpretation of Size
8840as implemented in the VADS compiler.  See description of the VADS_Size
8841attribute for further details.
8842
8843@node Pragma Unused,Pragma Validity_Checks,Pragma Use_VADS_Size,Implementation Defined Pragmas
8844@anchor{gnat_rm/implementation_defined_pragmas id52}@anchor{111}@anchor{gnat_rm/implementation_defined_pragmas pragma-unused}@anchor{112}
8845@section Pragma Unused
8846
8847
8848@geindex Warnings
8849@geindex unused
8850
8851Syntax:
8852
8853@example
8854pragma Unused (LOCAL_NAME @{, LOCAL_NAME@});
8855@end example
8856
8857This pragma signals that the assignable entities (variables,
8858@code{out} parameters, and @code{in out} parameters) whose names are listed
8859deliberately do not get assigned or referenced in the current source unit
8860after the occurrence of the pragma in the current source unit. This
8861suppresses warnings about the entities that are unreferenced and/or not
8862assigned, and, in addition, a warning will be generated if one of these
8863entities gets assigned or subsequently referenced in the same unit as the
8864pragma (in the corresponding body or one of its subunits).
8865
8866This is particularly useful for clearly signaling that a particular
8867parameter is not modified or referenced, even though the spec suggests
8868that it might be.
8869
8870For the variable case, warnings are never given for unreferenced
8871variables whose name contains one of the substrings
8872@code{DISCARD, DUMMY, IGNORE, JUNK, UNUSED} in any casing. Such names
8873are typically to be used in cases where such warnings are expected.
8874Thus it is never necessary to use @code{pragma Unmodified} for such
8875variables, though it is harmless to do so.
8876
8877@node Pragma Validity_Checks,Pragma Volatile,Pragma Unused,Implementation Defined Pragmas
8878@anchor{gnat_rm/implementation_defined_pragmas pragma-validity-checks}@anchor{113}
8879@section Pragma Validity_Checks
8880
8881
8882Syntax:
8883
8884@example
8885pragma Validity_Checks (string_LITERAL | ALL_CHECKS | On | Off);
8886@end example
8887
8888This pragma is used in conjunction with compiler switches to control the
8889built-in validity checking provided by GNAT.  The compiler switches, if set
8890provide an initial setting for the switches, and this pragma may be used
8891to modify these settings, or the settings may be provided entirely by
8892the use of the pragma.  This pragma can be used anywhere that a pragma
8893is legal, including use as a configuration pragma (including use in
8894the @code{gnat.adc} file).
8895
8896The form with a string literal specifies which validity options are to be
8897activated.  The validity checks are first set to include only the default
8898reference manual settings, and then a string of letters in the string
8899specifies the exact set of options required.  The form of this string
8900is exactly as described for the @emph{-gnatVx} compiler switch (see the
8901GNAT User’s Guide for details).  For example the following two
8902methods can be used to enable validity checking for mode @code{in} and
8903@code{in out} subprogram parameters:
8904
8905
8906@itemize *
8907
8908@item
8909@example
8910pragma Validity_Checks ("im");
8911@end example
8912
8913@item
8914@example
8915$ gcc -c -gnatVim ...
8916@end example
8917@end itemize
8918
8919The form ALL_CHECKS activates all standard checks (its use is equivalent
8920to the use of the @code{gnatVa} switch).
8921
8922The forms with @code{Off} and @code{On} can be used to temporarily disable
8923validity checks as shown in the following example:
8924
8925@example
8926pragma Validity_Checks ("c"); -- validity checks for copies
8927pragma Validity_Checks (Off); -- turn off validity checks
8928A := B;                       -- B will not be validity checked
8929pragma Validity_Checks (On);  -- turn validity checks back on
8930A := C;                       -- C will be validity checked
8931@end example
8932
8933@node Pragma Volatile,Pragma Volatile_Full_Access,Pragma Validity_Checks,Implementation Defined Pragmas
8934@anchor{gnat_rm/implementation_defined_pragmas id53}@anchor{114}@anchor{gnat_rm/implementation_defined_pragmas pragma-volatile}@anchor{115}
8935@section Pragma Volatile
8936
8937
8938Syntax:
8939
8940@example
8941pragma Volatile (LOCAL_NAME);
8942@end example
8943
8944This pragma is defined by the Ada Reference Manual, and the GNAT
8945implementation is fully conformant with this definition.  The reason it
8946is mentioned in this section is that a pragma of the same name was supplied
8947in some Ada 83 compilers, including DEC Ada 83.  The Ada 95 / Ada 2005
8948implementation of pragma Volatile is upwards compatible with the
8949implementation in DEC Ada 83.
8950
8951@node Pragma Volatile_Full_Access,Pragma Volatile_Function,Pragma Volatile,Implementation Defined Pragmas
8952@anchor{gnat_rm/implementation_defined_pragmas id54}@anchor{116}@anchor{gnat_rm/implementation_defined_pragmas pragma-volatile-full-access}@anchor{117}
8953@section Pragma Volatile_Full_Access
8954
8955
8956Syntax:
8957
8958@example
8959pragma Volatile_Full_Access (LOCAL_NAME);
8960@end example
8961
8962This is similar in effect to pragma Volatile, except that any reference to the
8963object is guaranteed to be done only with instructions that read or write all
8964the bits of the object. Furthermore, if the object is of a composite type,
8965then any reference to a subcomponent of the object is guaranteed to read
8966and/or write all the bits of the object.
8967
8968The intention is that this be suitable for use with memory-mapped I/O devices
8969on some machines. Note that there are two important respects in which this is
8970different from @code{pragma Atomic}. First a reference to a @code{Volatile_Full_Access}
8971object is not a sequential action in the RM 9.10 sense and, therefore, does
8972not create a synchronization point. Second, in the case of @code{pragma Atomic},
8973there is no guarantee that all the bits will be accessed if the reference
8974is not to the whole object; the compiler is allowed (and generally will)
8975access only part of the object in this case.
8976
8977@node Pragma Volatile_Function,Pragma Warning_As_Error,Pragma Volatile_Full_Access,Implementation Defined Pragmas
8978@anchor{gnat_rm/implementation_defined_pragmas id55}@anchor{118}@anchor{gnat_rm/implementation_defined_pragmas pragma-volatile-function}@anchor{119}
8979@section Pragma Volatile_Function
8980
8981
8982Syntax:
8983
8984@example
8985pragma Volatile_Function [ (boolean_EXPRESSION) ];
8986@end example
8987
8988For the semantics of this pragma, see the entry for aspect @code{Volatile_Function}
8989in the SPARK 2014 Reference Manual, section 7.1.2.
8990
8991@node Pragma Warning_As_Error,Pragma Warnings,Pragma Volatile_Function,Implementation Defined Pragmas
8992@anchor{gnat_rm/implementation_defined_pragmas pragma-warning-as-error}@anchor{11a}
8993@section Pragma Warning_As_Error
8994
8995
8996Syntax:
8997
8998@example
8999pragma Warning_As_Error (static_string_EXPRESSION);
9000@end example
9001
9002This configuration pragma allows the programmer to specify a set
9003of warnings that will be treated as errors. Any warning that
9004matches the pattern given by the pragma argument will be treated
9005as an error. This gives more precise control than -gnatwe,
9006which treats warnings as errors.
9007
9008This pragma can apply to regular warnings (messages enabled by -gnatw)
9009and to style warnings (messages that start with “(style)”,
9010enabled by -gnaty).
9011
9012The pattern may contain asterisks, which match zero or more characters
9013in the message. For example, you can use @code{pragma Warning_As_Error
9014("bits of*unused")} to treat the warning message @code{warning: 960 bits of
9015"a" unused} as an error. All characters other than asterisk are treated
9016as literal characters in the match. The match is case insensitive; for
9017example XYZ matches xyz.
9018
9019Note that the pattern matches if it occurs anywhere within the warning
9020message string (it is not necessary to put an asterisk at the start and
9021the end of the message, since this is implied).
9022
9023Another possibility for the static_string_EXPRESSION which works whether
9024or not error tags are enabled (@emph{-gnatw.d}) is to use a single
9025@emph{-gnatw} tag string, enclosed in brackets,
9026as shown in the example below, to treat one category of warnings as errors.
9027Note that if you want to treat multiple categories of warnings as errors,
9028you can use multiple pragma Warning_As_Error.
9029
9030The above use of patterns to match the message applies only to warning
9031messages generated by the front end. This pragma can also be applied to
9032warnings provided by the back end and mentioned in @ref{11b,,Pragma Warnings}.
9033By using a single full @emph{-Wxxx} switch in the pragma, such warnings
9034can also be treated as errors.
9035
9036The pragma can appear either in a global configuration pragma file
9037(e.g. @code{gnat.adc}), or at the start of a file. Given a global
9038configuration pragma file containing:
9039
9040@example
9041pragma Warning_As_Error ("[-gnatwj]");
9042@end example
9043
9044which will treat all obsolescent feature warnings as errors, the
9045following program compiles as shown (compile options here are
9046@emph{-gnatwa.d -gnatl -gnatj55}).
9047
9048@example
9049    1. pragma Warning_As_Error ("*never assigned*");
9050    2. function Warnerr return String is
9051    3.    X : Integer;
9052          |
9053       >>> error: variable "X" is never read and
9054           never assigned [-gnatwv] [warning-as-error]
9055
9056    4.    Y : Integer;
9057          |
9058       >>> warning: variable "Y" is assigned but
9059           never read [-gnatwu]
9060
9061    5. begin
9062    6.    Y := 0;
9063    7.    return %ABC%;
9064                 |
9065       >>> error: use of "%" is an obsolescent
9066           feature (RM J.2(4)), use """ instead
9067           [-gnatwj] [warning-as-error]
9068
9069    8. end;
9070
90718 lines: No errors, 3 warnings (2 treated as errors)
9072@end example
9073
9074Note that this pragma does not affect the set of warnings issued in
9075any way, it merely changes the effect of a matching warning if one
9076is produced as a result of other warnings options. As shown in this
9077example, if the pragma results in a warning being treated as an error,
9078the tag is changed from “warning:” to “error:” and the string
9079“[warning-as-error]” is appended to the end of the message.
9080
9081@node Pragma Warnings,Pragma Weak_External,Pragma Warning_As_Error,Implementation Defined Pragmas
9082@anchor{gnat_rm/implementation_defined_pragmas id56}@anchor{11c}@anchor{gnat_rm/implementation_defined_pragmas pragma-warnings}@anchor{11b}
9083@section Pragma Warnings
9084
9085
9086Syntax:
9087
9088@example
9089pragma Warnings ([TOOL_NAME,] DETAILS [, REASON]);
9090
9091DETAILS ::= On | Off
9092DETAILS ::= On | Off, local_NAME
9093DETAILS ::= static_string_EXPRESSION
9094DETAILS ::= On | Off, static_string_EXPRESSION
9095
9096TOOL_NAME ::= GNAT | GNATprove
9097
9098REASON ::= Reason => STRING_LITERAL @{& STRING_LITERAL@}
9099@end example
9100
9101Note: in Ada 83 mode, a string literal may be used in place of a static string
9102expression (which does not exist in Ada 83).
9103
9104Note if the second argument of @code{DETAILS} is a @code{local_NAME} then the
9105second form is always understood. If the intention is to use
9106the fourth form, then you can write @code{NAME & ""} to force the
9107intepretation as a @emph{static_string_EXPRESSION}.
9108
9109Note: if the first argument is a valid @code{TOOL_NAME}, it will be interpreted
9110that way. The use of the @code{TOOL_NAME} argument is relevant only to users
9111of SPARK and GNATprove, see last part of this section for details.
9112
9113Normally warnings are enabled, with the output being controlled by
9114the command line switch.  Warnings (@code{Off}) turns off generation of
9115warnings until a Warnings (@code{On}) is encountered or the end of the
9116current unit.  If generation of warnings is turned off using this
9117pragma, then some or all of the warning messages are suppressed,
9118regardless of the setting of the command line switches.
9119
9120The @code{Reason} parameter may optionally appear as the last argument
9121in any of the forms of this pragma. It is intended purely for the
9122purposes of documenting the reason for the @code{Warnings} pragma.
9123The compiler will check that the argument is a static string but
9124otherwise ignore this argument. Other tools may provide specialized
9125processing for this string.
9126
9127The form with a single argument (or two arguments if Reason present),
9128where the first argument is @code{ON} or @code{OFF}
9129may be used as a configuration pragma.
9130
9131If the @code{LOCAL_NAME} parameter is present, warnings are suppressed for
9132the specified entity.  This suppression is effective from the point where
9133it occurs till the end of the extended scope of the variable (similar to
9134the scope of @code{Suppress}). This form cannot be used as a configuration
9135pragma.
9136
9137In the case where the first argument is other than @code{ON} or
9138@code{OFF},
9139the third form with a single static_string_EXPRESSION argument (and possible
9140reason) provides more precise
9141control over which warnings are active. The string is a list of letters
9142specifying which warnings are to be activated and which deactivated. The
9143code for these letters is the same as the string used in the command
9144line switch controlling warnings. For a brief summary, use the gnatmake
9145command with no arguments, which will generate usage information containing
9146the list of warnings switches supported. For
9147full details see the section on @code{Warning Message Control} in the
9148@cite{GNAT User’s Guide}.
9149This form can also be used as a configuration pragma.
9150
9151The warnings controlled by the @code{-gnatw} switch are generated by the
9152front end of the compiler. The GCC back end can provide additional warnings
9153and they are controlled by the @code{-W} switch. Such warnings can be
9154identified by the appearance of a string of the form @code{[-W@{xxx@}]} in the
9155message which designates the @code{-W@emph{xxx}} switch that controls the message.
9156The form with a single @emph{static_string_EXPRESSION} argument also works for these
9157warnings, but the string must be a single full @code{-W@emph{xxx}} switch in this
9158case. The above reference lists a few examples of these additional warnings.
9159
9160The specified warnings will be in effect until the end of the program
9161or another pragma @code{Warnings} is encountered. The effect of the pragma is
9162cumulative. Initially the set of warnings is the standard default set
9163as possibly modified by compiler switches. Then each pragma Warning
9164modifies this set of warnings as specified. This form of the pragma may
9165also be used as a configuration pragma.
9166
9167The fourth form, with an @code{On|Off} parameter and a string, is used to
9168control individual messages, based on their text. The string argument
9169is a pattern that is used to match against the text of individual
9170warning messages (not including the initial “warning: ” tag).
9171
9172The pattern may contain asterisks, which match zero or more characters in
9173the message. For example, you can use
9174@code{pragma Warnings (Off, "bits of*unused")} to suppress the warning
9175message @code{warning: 960 bits of "a" unused}. No other regular
9176expression notations are permitted. All characters other than asterisk in
9177these three specific cases are treated as literal characters in the match.
9178The match is case insensitive, for example XYZ matches xyz.
9179
9180Note that the pattern matches if it occurs anywhere within the warning
9181message string (it is not necessary to put an asterisk at the start and
9182the end of the message, since this is implied).
9183
9184The above use of patterns to match the message applies only to warning
9185messages generated by the front end. This form of the pragma with a string
9186argument can also be used to control warnings provided by the back end and
9187mentioned above. By using a single full @code{-W@emph{xxx}} switch in the pragma,
9188such warnings can be turned on and off.
9189
9190There are two ways to use the pragma in this form. The OFF form can be used
9191as a configuration pragma. The effect is to suppress all warnings (if any)
9192that match the pattern string throughout the compilation (or match the
9193-W switch in the back end case).
9194
9195The second usage is to suppress a warning locally, and in this case, two
9196pragmas must appear in sequence:
9197
9198@example
9199pragma Warnings (Off, Pattern);
9200... code where given warning is to be suppressed
9201pragma Warnings (On, Pattern);
9202@end example
9203
9204In this usage, the pattern string must match in the Off and On
9205pragmas, and (if @emph{-gnatw.w} is given) at least one matching
9206warning must be suppressed.
9207
9208Note: if the ON form is not found, then the effect of the OFF form extends
9209until the end of the file (pragma Warnings is purely textual, so its effect
9210does not stop at the end of the enclosing scope).
9211
9212Note: to write a string that will match any warning, use the string
9213@code{"***"}. It will not work to use a single asterisk or two
9214asterisks since this looks like an operator name. This form with three
9215asterisks is similar in effect to specifying @code{pragma Warnings (Off)} except (if @code{-gnatw.w} is given) that a matching
9216@code{pragma Warnings (On, "***")} will be required. This can be
9217helpful in avoiding forgetting to turn warnings back on.
9218
9219Note: the debug flag @code{-gnatd.i} can be
9220used to cause the compiler to entirely ignore all WARNINGS pragmas. This can
9221be useful in checking whether obsolete pragmas in existing programs are hiding
9222real problems.
9223
9224Note: pragma Warnings does not affect the processing of style messages. See
9225separate entry for pragma Style_Checks for control of style messages.
9226
9227Users of the formal verification tool GNATprove for the SPARK subset of Ada may
9228use the version of the pragma with a @code{TOOL_NAME} parameter.
9229
9230If present, @code{TOOL_NAME} is the name of a tool, currently either @code{GNAT} for the
9231compiler or @code{GNATprove} for the formal verification tool. A given tool only
9232takes into account pragma Warnings that do not specify a tool name, or that
9233specify the matching tool name. This makes it possible to disable warnings
9234selectively for each tool, and as a consequence to detect useless pragma
9235Warnings with switch @code{-gnatw.w}.
9236
9237@node Pragma Weak_External,Pragma Wide_Character_Encoding,Pragma Warnings,Implementation Defined Pragmas
9238@anchor{gnat_rm/implementation_defined_pragmas pragma-weak-external}@anchor{11d}
9239@section Pragma Weak_External
9240
9241
9242Syntax:
9243
9244@example
9245pragma Weak_External ([Entity =>] LOCAL_NAME);
9246@end example
9247
9248@code{LOCAL_NAME} must refer to an object that is declared at the library
9249level. This pragma specifies that the given entity should be marked as a
9250weak symbol for the linker. It is equivalent to @code{__attribute__((weak))}
9251in GNU C and causes @code{LOCAL_NAME} to be emitted as a weak symbol instead
9252of a regular symbol, that is to say a symbol that does not have to be
9253resolved by the linker if used in conjunction with a pragma Import.
9254
9255When a weak symbol is not resolved by the linker, its address is set to
9256zero. This is useful in writing interfaces to external modules that may
9257or may not be linked in the final executable, for example depending on
9258configuration settings.
9259
9260If a program references at run time an entity to which this pragma has been
9261applied, and the corresponding symbol was not resolved at link time, then
9262the execution of the program is erroneous. It is not erroneous to take the
9263Address of such an entity, for example to guard potential references,
9264as shown in the example below.
9265
9266Some file formats do not support weak symbols so not all target machines
9267support this pragma.
9268
9269@example
9270--  Example of the use of pragma Weak_External
9271
9272package External_Module is
9273  key : Integer;
9274  pragma Import (C, key);
9275  pragma Weak_External (key);
9276  function Present return boolean;
9277end External_Module;
9278
9279with System; use System;
9280package body External_Module is
9281  function Present return boolean is
9282  begin
9283    return key'Address /= System.Null_Address;
9284  end Present;
9285end External_Module;
9286@end example
9287
9288@node Pragma Wide_Character_Encoding,,Pragma Weak_External,Implementation Defined Pragmas
9289@anchor{gnat_rm/implementation_defined_pragmas pragma-wide-character-encoding}@anchor{11e}
9290@section Pragma Wide_Character_Encoding
9291
9292
9293Syntax:
9294
9295@example
9296pragma Wide_Character_Encoding (IDENTIFIER | CHARACTER_LITERAL);
9297@end example
9298
9299This pragma specifies the wide character encoding to be used in program
9300source text appearing subsequently. It is a configuration pragma, but may
9301also be used at any point that a pragma is allowed, and it is permissible
9302to have more than one such pragma in a file, allowing multiple encodings
9303to appear within the same file.
9304
9305However, note that the pragma cannot immediately precede the relevant
9306wide character, because then the previous encoding will still be in
9307effect, causing “illegal character” errors.
9308
9309The argument can be an identifier or a character literal. In the identifier
9310case, it is one of @code{HEX}, @code{UPPER}, @code{SHIFT_JIS},
9311@code{EUC}, @code{UTF8}, or @code{BRACKETS}. In the character literal
9312case it is correspondingly one of the characters @code{h}, @code{u},
9313@code{s}, @code{e}, @code{8}, or @code{b}.
9314
9315Note that when the pragma is used within a file, it affects only the
9316encoding within that file, and does not affect withed units, specs,
9317or subunits.
9318
9319@node Implementation Defined Aspects,Implementation Defined Attributes,Implementation Defined Pragmas,Top
9320@anchor{gnat_rm/implementation_defined_aspects doc}@anchor{11f}@anchor{gnat_rm/implementation_defined_aspects id1}@anchor{120}@anchor{gnat_rm/implementation_defined_aspects implementation-defined-aspects}@anchor{121}
9321@chapter Implementation Defined Aspects
9322
9323
9324Ada defines (throughout the Ada 2012 reference manual, summarized
9325in Annex K) a set of aspects that can be specified for certain entities.
9326These language defined aspects are implemented in GNAT in Ada 2012 mode
9327and work as described in the Ada 2012 Reference Manual.
9328
9329In addition, Ada 2012 allows implementations to define additional aspects
9330whose meaning is defined by the implementation.  GNAT provides
9331a number of these implementation-defined aspects which can be used
9332to extend and enhance the functionality of the compiler.  This section of
9333the GNAT reference manual describes these additional aspects.
9334
9335Note that any program using these aspects may not be portable to
9336other compilers (although GNAT implements this set of aspects on all
9337platforms).  Therefore if portability to other compilers is an important
9338consideration, you should minimize the use of these aspects.
9339
9340Note that for many of these aspects, the effect is essentially similar
9341to the use of a pragma or attribute specification with the same name
9342applied to the entity. For example, if we write:
9343
9344@example
9345type R is range 1 .. 100
9346  with Value_Size => 10;
9347@end example
9348
9349then the effect is the same as:
9350
9351@example
9352type R is range 1 .. 100;
9353for R'Value_Size use 10;
9354@end example
9355
9356and if we write:
9357
9358@example
9359type R is new Integer
9360  with Shared => True;
9361@end example
9362
9363then the effect is the same as:
9364
9365@example
9366type R is new Integer;
9367pragma Shared (R);
9368@end example
9369
9370In the documentation below, such cases are simply marked
9371as being boolean aspects equivalent to the corresponding pragma
9372or attribute definition clause.
9373
9374@menu
9375* Aspect Abstract_State::
9376* Aspect Annotate::
9377* Aspect Async_Readers::
9378* Aspect Async_Writers::
9379* Aspect Constant_After_Elaboration::
9380* Aspect Contract_Cases::
9381* Aspect Depends::
9382* Aspect Default_Initial_Condition::
9383* Aspect Dimension::
9384* Aspect Dimension_System::
9385* Aspect Disable_Controlled::
9386* Aspect Effective_Reads::
9387* Aspect Effective_Writes::
9388* Aspect Extensions_Visible::
9389* Aspect Favor_Top_Level::
9390* Aspect Ghost::
9391* Aspect Global::
9392* Aspect Initial_Condition::
9393* Aspect Initializes::
9394* Aspect Inline_Always::
9395* Aspect Invariant::
9396* Aspect Invariant’Class::
9397* Aspect Iterable::
9398* Aspect Linker_Section::
9399* Aspect Lock_Free::
9400* Aspect Max_Queue_Length::
9401* Aspect No_Caching::
9402* Aspect No_Elaboration_Code_All::
9403* Aspect No_Inline::
9404* Aspect No_Tagged_Streams::
9405* Aspect No_Task_Parts::
9406* Aspect Object_Size::
9407* Aspect Obsolescent::
9408* Aspect Part_Of::
9409* Aspect Persistent_BSS::
9410* Aspect Predicate::
9411* Aspect Pure_Function::
9412* Aspect Refined_Depends::
9413* Aspect Refined_Global::
9414* Aspect Refined_Post::
9415* Aspect Refined_State::
9416* Aspect Relaxed_Initialization::
9417* Aspect Remote_Access_Type::
9418* Aspect Secondary_Stack_Size::
9419* Aspect Scalar_Storage_Order::
9420* Aspect Shared::
9421* Aspect Simple_Storage_Pool::
9422* Aspect Simple_Storage_Pool_Type::
9423* Aspect SPARK_Mode::
9424* Aspect Suppress_Debug_Info::
9425* Aspect Suppress_Initialization::
9426* Aspect Test_Case::
9427* Aspect Thread_Local_Storage::
9428* Aspect Universal_Aliasing::
9429* Aspect Unmodified::
9430* Aspect Unreferenced::
9431* Aspect Unreferenced_Objects::
9432* Aspect Value_Size::
9433* Aspect Volatile_Full_Access::
9434* Aspect Volatile_Function::
9435* Aspect Warnings::
9436
9437@end menu
9438
9439@node Aspect Abstract_State,Aspect Annotate,,Implementation Defined Aspects
9440@anchor{gnat_rm/implementation_defined_aspects aspect-abstract-state}@anchor{122}
9441@section Aspect Abstract_State
9442
9443
9444@geindex Abstract_State
9445
9446This aspect is equivalent to @ref{1e,,pragma Abstract_State}.
9447
9448@node Aspect Annotate,Aspect Async_Readers,Aspect Abstract_State,Implementation Defined Aspects
9449@anchor{gnat_rm/implementation_defined_aspects aspect-annotate}@anchor{123}
9450@section Aspect Annotate
9451
9452
9453@geindex Annotate
9454
9455There are three forms of this aspect (where ID is an identifier,
9456and ARG is a general expression),
9457corresponding to @ref{28,,pragma Annotate}.
9458
9459
9460@table @asis
9461
9462@item @emph{Annotate => ID}
9463
9464Equivalent to @code{pragma Annotate (ID, Entity => Name);}
9465
9466@item @emph{Annotate => (ID)}
9467
9468Equivalent to @code{pragma Annotate (ID, Entity => Name);}
9469
9470@item @emph{Annotate => (ID ,ID @{, ARG@})}
9471
9472Equivalent to @code{pragma Annotate (ID, ID @{, ARG@}, Entity => Name);}
9473@end table
9474
9475@node Aspect Async_Readers,Aspect Async_Writers,Aspect Annotate,Implementation Defined Aspects
9476@anchor{gnat_rm/implementation_defined_aspects aspect-async-readers}@anchor{124}
9477@section Aspect Async_Readers
9478
9479
9480@geindex Async_Readers
9481
9482This boolean aspect is equivalent to @ref{2f,,pragma Async_Readers}.
9483
9484@node Aspect Async_Writers,Aspect Constant_After_Elaboration,Aspect Async_Readers,Implementation Defined Aspects
9485@anchor{gnat_rm/implementation_defined_aspects aspect-async-writers}@anchor{125}
9486@section Aspect Async_Writers
9487
9488
9489@geindex Async_Writers
9490
9491This boolean aspect is equivalent to @ref{31,,pragma Async_Writers}.
9492
9493@node Aspect Constant_After_Elaboration,Aspect Contract_Cases,Aspect Async_Writers,Implementation Defined Aspects
9494@anchor{gnat_rm/implementation_defined_aspects aspect-constant-after-elaboration}@anchor{126}
9495@section Aspect Constant_After_Elaboration
9496
9497
9498@geindex Constant_After_Elaboration
9499
9500This aspect is equivalent to @ref{43,,pragma Constant_After_Elaboration}.
9501
9502@node Aspect Contract_Cases,Aspect Depends,Aspect Constant_After_Elaboration,Implementation Defined Aspects
9503@anchor{gnat_rm/implementation_defined_aspects aspect-contract-cases}@anchor{127}
9504@section Aspect Contract_Cases
9505
9506
9507@geindex Contract_Cases
9508
9509This aspect is equivalent to @ref{45,,pragma Contract_Cases}, the sequence
9510of clauses being enclosed in parentheses so that syntactically it is an
9511aggregate.
9512
9513@node Aspect Depends,Aspect Default_Initial_Condition,Aspect Contract_Cases,Implementation Defined Aspects
9514@anchor{gnat_rm/implementation_defined_aspects aspect-depends}@anchor{128}
9515@section Aspect Depends
9516
9517
9518@geindex Depends
9519
9520This aspect is equivalent to @ref{55,,pragma Depends}.
9521
9522@node Aspect Default_Initial_Condition,Aspect Dimension,Aspect Depends,Implementation Defined Aspects
9523@anchor{gnat_rm/implementation_defined_aspects aspect-default-initial-condition}@anchor{129}
9524@section Aspect Default_Initial_Condition
9525
9526
9527@geindex Default_Initial_Condition
9528
9529This aspect is equivalent to @ref{4f,,pragma Default_Initial_Condition}.
9530
9531@node Aspect Dimension,Aspect Dimension_System,Aspect Default_Initial_Condition,Implementation Defined Aspects
9532@anchor{gnat_rm/implementation_defined_aspects aspect-dimension}@anchor{12a}
9533@section Aspect Dimension
9534
9535
9536@geindex Dimension
9537
9538The @code{Dimension} aspect is used to specify the dimensions of a given
9539subtype of a dimensioned numeric type. The aspect also specifies a symbol
9540used when doing formatted output of dimensioned quantities. The syntax is:
9541
9542@example
9543with Dimension =>
9544  ([Symbol =>] SYMBOL, DIMENSION_VALUE @{, DIMENSION_Value@})
9545
9546SYMBOL ::= STRING_LITERAL | CHARACTER_LITERAL
9547
9548DIMENSION_VALUE ::=
9549  RATIONAL
9550| others               => RATIONAL
9551| DISCRETE_CHOICE_LIST => RATIONAL
9552
9553RATIONAL ::= [-] NUMERIC_LITERAL [/ NUMERIC_LITERAL]
9554@end example
9555
9556This aspect can only be applied to a subtype whose parent type has
9557a @code{Dimension_System} aspect. The aspect must specify values for
9558all dimensions of the system. The rational values are the powers of the
9559corresponding dimensions that are used by the compiler to verify that
9560physical (numeric) computations are dimensionally consistent. For example,
9561the computation of a force must result in dimensions (L => 1, M => 1, T => -2).
9562For further examples of the usage
9563of this aspect, see package @code{System.Dim.Mks}.
9564Note that when the dimensioned type is an integer type, then any
9565dimension value must be an integer literal.
9566
9567@node Aspect Dimension_System,Aspect Disable_Controlled,Aspect Dimension,Implementation Defined Aspects
9568@anchor{gnat_rm/implementation_defined_aspects aspect-dimension-system}@anchor{12b}
9569@section Aspect Dimension_System
9570
9571
9572@geindex Dimension_System
9573
9574The @code{Dimension_System} aspect is used to define a system of
9575dimensions that will be used in subsequent subtype declarations with
9576@code{Dimension} aspects that reference this system. The syntax is:
9577
9578@example
9579with Dimension_System => (DIMENSION @{, DIMENSION@});
9580
9581DIMENSION ::= ([Unit_Name   =>] IDENTIFIER,
9582               [Unit_Symbol =>] SYMBOL,
9583               [Dim_Symbol  =>] SYMBOL)
9584
9585SYMBOL ::= CHARACTER_LITERAL | STRING_LITERAL
9586@end example
9587
9588This aspect is applied to a type, which must be a numeric derived type
9589(typically a floating-point type), that
9590will represent values within the dimension system. Each @code{DIMENSION}
9591corresponds to one particular dimension. A maximum of 7 dimensions may
9592be specified. @code{Unit_Name} is the name of the dimension (for example
9593@code{Meter}). @code{Unit_Symbol} is the shorthand used for quantities
9594of this dimension (for example @code{m} for @code{Meter}).
9595@code{Dim_Symbol} gives
9596the identification within the dimension system (typically this is a
9597single letter, e.g. @code{L} standing for length for unit name @code{Meter}).
9598The @code{Unit_Symbol} is used in formatted output of dimensioned quantities.
9599The @code{Dim_Symbol} is used in error messages when numeric operations have
9600inconsistent dimensions.
9601
9602GNAT provides the standard definition of the International MKS system in
9603the run-time package @code{System.Dim.Mks}. You can easily define
9604similar packages for cgs units or British units, and define conversion factors
9605between values in different systems. The MKS system is characterized by the
9606following aspect:
9607
9608@example
9609type Mks_Type is new Long_Long_Float with
9610  Dimension_System => (
9611    (Unit_Name => Meter,    Unit_Symbol => 'm',   Dim_Symbol => 'L'),
9612    (Unit_Name => Kilogram, Unit_Symbol => "kg",  Dim_Symbol => 'M'),
9613    (Unit_Name => Second,   Unit_Symbol => 's',   Dim_Symbol => 'T'),
9614    (Unit_Name => Ampere,   Unit_Symbol => 'A',   Dim_Symbol => 'I'),
9615    (Unit_Name => Kelvin,   Unit_Symbol => 'K',   Dim_Symbol => '@@'),
9616    (Unit_Name => Mole,     Unit_Symbol => "mol", Dim_Symbol => 'N'),
9617    (Unit_Name => Candela,  Unit_Symbol => "cd",  Dim_Symbol => 'J'));
9618@end example
9619
9620Note that in the above type definition, we use the @code{at} symbol (@code{@@}) to
9621represent a theta character (avoiding the use of extended Latin-1
9622characters in this context).
9623
9624See section ‘Performing Dimensionality Analysis in GNAT’ in the GNAT Users
9625Guide for detailed examples of use of the dimension system.
9626
9627@node Aspect Disable_Controlled,Aspect Effective_Reads,Aspect Dimension_System,Implementation Defined Aspects
9628@anchor{gnat_rm/implementation_defined_aspects aspect-disable-controlled}@anchor{12c}
9629@section Aspect Disable_Controlled
9630
9631
9632@geindex Disable_Controlled
9633
9634The aspect  @code{Disable_Controlled} is defined for controlled record types. If
9635active, this aspect causes suppression of all related calls to @code{Initialize},
9636@code{Adjust}, and @code{Finalize}. The intended use is for conditional compilation,
9637where for example you might want a record to be controlled or not depending on
9638whether some run-time check is enabled or suppressed.
9639
9640@node Aspect Effective_Reads,Aspect Effective_Writes,Aspect Disable_Controlled,Implementation Defined Aspects
9641@anchor{gnat_rm/implementation_defined_aspects aspect-effective-reads}@anchor{12d}
9642@section Aspect Effective_Reads
9643
9644
9645@geindex Effective_Reads
9646
9647This aspect is equivalent to @ref{5a,,pragma Effective_Reads}.
9648
9649@node Aspect Effective_Writes,Aspect Extensions_Visible,Aspect Effective_Reads,Implementation Defined Aspects
9650@anchor{gnat_rm/implementation_defined_aspects aspect-effective-writes}@anchor{12e}
9651@section Aspect Effective_Writes
9652
9653
9654@geindex Effective_Writes
9655
9656This aspect is equivalent to @ref{5c,,pragma Effective_Writes}.
9657
9658@node Aspect Extensions_Visible,Aspect Favor_Top_Level,Aspect Effective_Writes,Implementation Defined Aspects
9659@anchor{gnat_rm/implementation_defined_aspects aspect-extensions-visible}@anchor{12f}
9660@section Aspect Extensions_Visible
9661
9662
9663@geindex Extensions_Visible
9664
9665This aspect is equivalent to @ref{67,,pragma Extensions_Visible}.
9666
9667@node Aspect Favor_Top_Level,Aspect Ghost,Aspect Extensions_Visible,Implementation Defined Aspects
9668@anchor{gnat_rm/implementation_defined_aspects aspect-favor-top-level}@anchor{130}
9669@section Aspect Favor_Top_Level
9670
9671
9672@geindex Favor_Top_Level
9673
9674This boolean aspect is equivalent to @ref{6c,,pragma Favor_Top_Level}.
9675
9676@node Aspect Ghost,Aspect Global,Aspect Favor_Top_Level,Implementation Defined Aspects
9677@anchor{gnat_rm/implementation_defined_aspects aspect-ghost}@anchor{131}
9678@section Aspect Ghost
9679
9680
9681@geindex Ghost
9682
9683This aspect is equivalent to @ref{70,,pragma Ghost}.
9684
9685@node Aspect Global,Aspect Initial_Condition,Aspect Ghost,Implementation Defined Aspects
9686@anchor{gnat_rm/implementation_defined_aspects aspect-global}@anchor{132}
9687@section Aspect Global
9688
9689
9690@geindex Global
9691
9692This aspect is equivalent to @ref{72,,pragma Global}.
9693
9694@node Aspect Initial_Condition,Aspect Initializes,Aspect Global,Implementation Defined Aspects
9695@anchor{gnat_rm/implementation_defined_aspects aspect-initial-condition}@anchor{133}
9696@section Aspect Initial_Condition
9697
9698
9699@geindex Initial_Condition
9700
9701This aspect is equivalent to @ref{7f,,pragma Initial_Condition}.
9702
9703@node Aspect Initializes,Aspect Inline_Always,Aspect Initial_Condition,Implementation Defined Aspects
9704@anchor{gnat_rm/implementation_defined_aspects aspect-initializes}@anchor{134}
9705@section Aspect Initializes
9706
9707
9708@geindex Initializes
9709
9710This aspect is equivalent to @ref{82,,pragma Initializes}.
9711
9712@node Aspect Inline_Always,Aspect Invariant,Aspect Initializes,Implementation Defined Aspects
9713@anchor{gnat_rm/implementation_defined_aspects aspect-inline-always}@anchor{135}
9714@section Aspect Inline_Always
9715
9716
9717@geindex Inline_Always
9718
9719This boolean aspect is equivalent to @ref{84,,pragma Inline_Always}.
9720
9721@node Aspect Invariant,Aspect Invariant’Class,Aspect Inline_Always,Implementation Defined Aspects
9722@anchor{gnat_rm/implementation_defined_aspects aspect-invariant}@anchor{136}
9723@section Aspect Invariant
9724
9725
9726@geindex Invariant
9727
9728This aspect is equivalent to @ref{8b,,pragma Invariant}. It is a
9729synonym for the language defined aspect @code{Type_Invariant} except
9730that it is separately controllable using pragma @code{Assertion_Policy}.
9731
9732@node Aspect Invariant’Class,Aspect Iterable,Aspect Invariant,Implementation Defined Aspects
9733@anchor{gnat_rm/implementation_defined_aspects aspect-invariant-class}@anchor{137}
9734@section Aspect Invariant’Class
9735
9736
9737@geindex Invariant'Class
9738
9739This aspect is equivalent to @ref{102,,pragma Type_Invariant_Class}. It is a
9740synonym for the language defined aspect @code{Type_Invariant'Class} except
9741that it is separately controllable using pragma @code{Assertion_Policy}.
9742
9743@node Aspect Iterable,Aspect Linker_Section,Aspect Invariant’Class,Implementation Defined Aspects
9744@anchor{gnat_rm/implementation_defined_aspects aspect-iterable}@anchor{138}
9745@section Aspect Iterable
9746
9747
9748@geindex Iterable
9749
9750This aspect provides a light-weight mechanism for loops and quantified
9751expressions over container types, without the overhead imposed by the tampering
9752checks of standard Ada 2012 iterators. The value of the aspect is an aggregate
9753with six named components, of which the last three are optional: @code{First},
9754@code{Next}, @code{Has_Element}, @code{Element}, @code{Last}, and @code{Previous}.
9755When only the first three components are specified, only the
9756@code{for .. in} form of iteration over cursors is available. When @code{Element}
9757is specified, both this form and the @code{for .. of} form of iteration over
9758elements are available. If the last two components are specified, reverse
9759iterations over the container can be specified (analogous to what can be done
9760over predefined containers that support the @code{Reverse_Iterator} interface).
9761The following is a typical example of use:
9762
9763@example
9764type List is private with
9765    Iterable => (First        => First_Cursor,
9766                 Next         => Advance,
9767                 Has_Element  => Cursor_Has_Element,
9768                [Element      => Get_Element]);
9769@end example
9770
9771
9772@itemize *
9773
9774@item
9775The value denoted by @code{First} must denote a primitive operation of the
9776container type that returns a @code{Cursor}, which must a be a type declared in
9777the container package or visible from it. For example:
9778@end itemize
9779
9780@example
9781function First_Cursor (Cont : Container) return Cursor;
9782@end example
9783
9784
9785@itemize *
9786
9787@item
9788The value of @code{Next} is a primitive operation of the container type that takes
9789both a container and a cursor and yields a cursor. For example:
9790@end itemize
9791
9792@example
9793function Advance (Cont : Container; Position : Cursor) return Cursor;
9794@end example
9795
9796
9797@itemize *
9798
9799@item
9800The value of @code{Has_Element} is a primitive operation of the container type
9801that takes both a container and a cursor and yields a boolean. For example:
9802@end itemize
9803
9804@example
9805function Cursor_Has_Element (Cont : Container; Position : Cursor) return Boolean;
9806@end example
9807
9808
9809@itemize *
9810
9811@item
9812The value of @code{Element} is a primitive operation of the container type that
9813takes both a container and a cursor and yields an @code{Element_Type}, which must
9814be a type declared in the container package or visible from it. For example:
9815@end itemize
9816
9817@example
9818function Get_Element (Cont : Container; Position : Cursor) return Element_Type;
9819@end example
9820
9821This aspect is used in the GNAT-defined formal container packages.
9822
9823@node Aspect Linker_Section,Aspect Lock_Free,Aspect Iterable,Implementation Defined Aspects
9824@anchor{gnat_rm/implementation_defined_aspects aspect-linker-section}@anchor{139}
9825@section Aspect Linker_Section
9826
9827
9828@geindex Linker_Section
9829
9830This aspect is equivalent to @ref{93,,pragma Linker_Section}.
9831
9832@node Aspect Lock_Free,Aspect Max_Queue_Length,Aspect Linker_Section,Implementation Defined Aspects
9833@anchor{gnat_rm/implementation_defined_aspects aspect-lock-free}@anchor{13a}
9834@section Aspect Lock_Free
9835
9836
9837@geindex Lock_Free
9838
9839This boolean aspect is equivalent to @ref{95,,pragma Lock_Free}.
9840
9841@node Aspect Max_Queue_Length,Aspect No_Caching,Aspect Lock_Free,Implementation Defined Aspects
9842@anchor{gnat_rm/implementation_defined_aspects aspect-max-queue-length}@anchor{13b}
9843@section Aspect Max_Queue_Length
9844
9845
9846@geindex Max_Queue_Length
9847
9848This aspect is equivalent to @ref{9d,,pragma Max_Queue_Length}.
9849
9850@node Aspect No_Caching,Aspect No_Elaboration_Code_All,Aspect Max_Queue_Length,Implementation Defined Aspects
9851@anchor{gnat_rm/implementation_defined_aspects aspect-no-caching}@anchor{13c}
9852@section Aspect No_Caching
9853
9854
9855@geindex No_Caching
9856
9857This boolean aspect is equivalent to @ref{a0,,pragma No_Caching}.
9858
9859@node Aspect No_Elaboration_Code_All,Aspect No_Inline,Aspect No_Caching,Implementation Defined Aspects
9860@anchor{gnat_rm/implementation_defined_aspects aspect-no-elaboration-code-all}@anchor{13d}
9861@section Aspect No_Elaboration_Code_All
9862
9863
9864@geindex No_Elaboration_Code_All
9865
9866This aspect is equivalent to @ref{a3,,pragma No_Elaboration_Code_All}
9867for a program unit.
9868
9869@node Aspect No_Inline,Aspect No_Tagged_Streams,Aspect No_Elaboration_Code_All,Implementation Defined Aspects
9870@anchor{gnat_rm/implementation_defined_aspects aspect-no-inline}@anchor{13e}
9871@section Aspect No_Inline
9872
9873
9874@geindex No_Inline
9875
9876This boolean aspect is equivalent to @ref{a6,,pragma No_Inline}.
9877
9878@node Aspect No_Tagged_Streams,Aspect No_Task_Parts,Aspect No_Inline,Implementation Defined Aspects
9879@anchor{gnat_rm/implementation_defined_aspects aspect-no-tagged-streams}@anchor{13f}
9880@section Aspect No_Tagged_Streams
9881
9882
9883@geindex No_Tagged_Streams
9884
9885This aspect is equivalent to @ref{aa,,pragma No_Tagged_Streams} with an
9886argument specifying a root tagged type (thus this aspect can only be
9887applied to such a type).
9888
9889@node Aspect No_Task_Parts,Aspect Object_Size,Aspect No_Tagged_Streams,Implementation Defined Aspects
9890@anchor{gnat_rm/implementation_defined_aspects aspect-no-task-parts}@anchor{140}
9891@section Aspect No_Task_Parts
9892
9893
9894@geindex No_Task_Parts
9895
9896Applies to a type. If True, requires that the type and any descendants
9897do not have any task parts. The rules for this aspect are the same as
9898for the language-defined No_Controlled_Parts aspect (see RM-H.4.1),
9899replacing “controlled” with “task”.
9900
9901If No_Task_Parts is True for a type T, then the compiler can optimize
9902away certain tasking-related code that would otherwise be needed
9903for T’Class, because descendants of T might contain tasks.
9904
9905@node Aspect Object_Size,Aspect Obsolescent,Aspect No_Task_Parts,Implementation Defined Aspects
9906@anchor{gnat_rm/implementation_defined_aspects aspect-object-size}@anchor{141}
9907@section Aspect Object_Size
9908
9909
9910@geindex Object_Size
9911
9912This aspect is equivalent to @ref{142,,attribute Object_Size}.
9913
9914@node Aspect Obsolescent,Aspect Part_Of,Aspect Object_Size,Implementation Defined Aspects
9915@anchor{gnat_rm/implementation_defined_aspects aspect-obsolescent}@anchor{143}
9916@section Aspect Obsolescent
9917
9918
9919@geindex Obsolsecent
9920
9921This aspect is equivalent to @ref{ad,,pragma Obsolescent}. Note that the
9922evaluation of this aspect happens at the point of occurrence, it is not
9923delayed until the freeze point.
9924
9925@node Aspect Part_Of,Aspect Persistent_BSS,Aspect Obsolescent,Implementation Defined Aspects
9926@anchor{gnat_rm/implementation_defined_aspects aspect-part-of}@anchor{144}
9927@section Aspect Part_Of
9928
9929
9930@geindex Part_Of
9931
9932This aspect is equivalent to @ref{b4,,pragma Part_Of}.
9933
9934@node Aspect Persistent_BSS,Aspect Predicate,Aspect Part_Of,Implementation Defined Aspects
9935@anchor{gnat_rm/implementation_defined_aspects aspect-persistent-bss}@anchor{145}
9936@section Aspect Persistent_BSS
9937
9938
9939@geindex Persistent_BSS
9940
9941This boolean aspect is equivalent to @ref{b7,,pragma Persistent_BSS}.
9942
9943@node Aspect Predicate,Aspect Pure_Function,Aspect Persistent_BSS,Implementation Defined Aspects
9944@anchor{gnat_rm/implementation_defined_aspects aspect-predicate}@anchor{146}
9945@section Aspect Predicate
9946
9947
9948@geindex Predicate
9949
9950This aspect is equivalent to @ref{be,,pragma Predicate}. It is thus
9951similar to the language defined aspects @code{Dynamic_Predicate}
9952and @code{Static_Predicate} except that whether the resulting
9953predicate is static or dynamic is controlled by the form of the
9954expression. It is also separately controllable using pragma
9955@code{Assertion_Policy}.
9956
9957@node Aspect Pure_Function,Aspect Refined_Depends,Aspect Predicate,Implementation Defined Aspects
9958@anchor{gnat_rm/implementation_defined_aspects aspect-pure-function}@anchor{147}
9959@section Aspect Pure_Function
9960
9961
9962@geindex Pure_Function
9963
9964This boolean aspect is equivalent to @ref{ca,,pragma Pure_Function}.
9965
9966@node Aspect Refined_Depends,Aspect Refined_Global,Aspect Pure_Function,Implementation Defined Aspects
9967@anchor{gnat_rm/implementation_defined_aspects aspect-refined-depends}@anchor{148}
9968@section Aspect Refined_Depends
9969
9970
9971@geindex Refined_Depends
9972
9973This aspect is equivalent to @ref{ce,,pragma Refined_Depends}.
9974
9975@node Aspect Refined_Global,Aspect Refined_Post,Aspect Refined_Depends,Implementation Defined Aspects
9976@anchor{gnat_rm/implementation_defined_aspects aspect-refined-global}@anchor{149}
9977@section Aspect Refined_Global
9978
9979
9980@geindex Refined_Global
9981
9982This aspect is equivalent to @ref{d0,,pragma Refined_Global}.
9983
9984@node Aspect Refined_Post,Aspect Refined_State,Aspect Refined_Global,Implementation Defined Aspects
9985@anchor{gnat_rm/implementation_defined_aspects aspect-refined-post}@anchor{14a}
9986@section Aspect Refined_Post
9987
9988
9989@geindex Refined_Post
9990
9991This aspect is equivalent to @ref{d2,,pragma Refined_Post}.
9992
9993@node Aspect Refined_State,Aspect Relaxed_Initialization,Aspect Refined_Post,Implementation Defined Aspects
9994@anchor{gnat_rm/implementation_defined_aspects aspect-refined-state}@anchor{14b}
9995@section Aspect Refined_State
9996
9997
9998@geindex Refined_State
9999
10000This aspect is equivalent to @ref{d4,,pragma Refined_State}.
10001
10002@node Aspect Relaxed_Initialization,Aspect Remote_Access_Type,Aspect Refined_State,Implementation Defined Aspects
10003@anchor{gnat_rm/implementation_defined_aspects aspect-relaxed-initialization}@anchor{14c}
10004@section Aspect Relaxed_Initialization
10005
10006
10007@geindex Refined_Initialization
10008
10009For the syntax and semantics of this aspect, see the SPARK 2014 Reference
10010Manual, section 6.10.
10011
10012@node Aspect Remote_Access_Type,Aspect Secondary_Stack_Size,Aspect Relaxed_Initialization,Implementation Defined Aspects
10013@anchor{gnat_rm/implementation_defined_aspects aspect-remote-access-type}@anchor{14d}
10014@section Aspect Remote_Access_Type
10015
10016
10017@geindex Remote_Access_Type
10018
10019This aspect is equivalent to @ref{d7,,pragma Remote_Access_Type}.
10020
10021@node Aspect Secondary_Stack_Size,Aspect Scalar_Storage_Order,Aspect Remote_Access_Type,Implementation Defined Aspects
10022@anchor{gnat_rm/implementation_defined_aspects aspect-secondary-stack-size}@anchor{14e}
10023@section Aspect Secondary_Stack_Size
10024
10025
10026@geindex Secondary_Stack_Size
10027
10028This aspect is equivalent to @ref{dd,,pragma Secondary_Stack_Size}.
10029
10030@node Aspect Scalar_Storage_Order,Aspect Shared,Aspect Secondary_Stack_Size,Implementation Defined Aspects
10031@anchor{gnat_rm/implementation_defined_aspects aspect-scalar-storage-order}@anchor{14f}
10032@section Aspect Scalar_Storage_Order
10033
10034
10035@geindex Scalar_Storage_Order
10036
10037This aspect is equivalent to a @ref{150,,attribute Scalar_Storage_Order}.
10038
10039@node Aspect Shared,Aspect Simple_Storage_Pool,Aspect Scalar_Storage_Order,Implementation Defined Aspects
10040@anchor{gnat_rm/implementation_defined_aspects aspect-shared}@anchor{151}
10041@section Aspect Shared
10042
10043
10044@geindex Shared
10045
10046This boolean aspect is equivalent to @ref{e0,,pragma Shared}
10047and is thus a synonym for aspect @code{Atomic}.
10048
10049@node Aspect Simple_Storage_Pool,Aspect Simple_Storage_Pool_Type,Aspect Shared,Implementation Defined Aspects
10050@anchor{gnat_rm/implementation_defined_aspects aspect-simple-storage-pool}@anchor{152}
10051@section Aspect Simple_Storage_Pool
10052
10053
10054@geindex Simple_Storage_Pool
10055
10056This aspect is equivalent to @ref{e5,,attribute Simple_Storage_Pool}.
10057
10058@node Aspect Simple_Storage_Pool_Type,Aspect SPARK_Mode,Aspect Simple_Storage_Pool,Implementation Defined Aspects
10059@anchor{gnat_rm/implementation_defined_aspects aspect-simple-storage-pool-type}@anchor{153}
10060@section Aspect Simple_Storage_Pool_Type
10061
10062
10063@geindex Simple_Storage_Pool_Type
10064
10065This boolean aspect is equivalent to @ref{e4,,pragma Simple_Storage_Pool_Type}.
10066
10067@node Aspect SPARK_Mode,Aspect Suppress_Debug_Info,Aspect Simple_Storage_Pool_Type,Implementation Defined Aspects
10068@anchor{gnat_rm/implementation_defined_aspects aspect-spark-mode}@anchor{154}
10069@section Aspect SPARK_Mode
10070
10071
10072@geindex SPARK_Mode
10073
10074This aspect is equivalent to @ref{ec,,pragma SPARK_Mode} and
10075may be specified for either or both of the specification and body
10076of a subprogram or package.
10077
10078@node Aspect Suppress_Debug_Info,Aspect Suppress_Initialization,Aspect SPARK_Mode,Implementation Defined Aspects
10079@anchor{gnat_rm/implementation_defined_aspects aspect-suppress-debug-info}@anchor{155}
10080@section Aspect Suppress_Debug_Info
10081
10082
10083@geindex Suppress_Debug_Info
10084
10085This boolean aspect is equivalent to @ref{f4,,pragma Suppress_Debug_Info}.
10086
10087@node Aspect Suppress_Initialization,Aspect Test_Case,Aspect Suppress_Debug_Info,Implementation Defined Aspects
10088@anchor{gnat_rm/implementation_defined_aspects aspect-suppress-initialization}@anchor{156}
10089@section Aspect Suppress_Initialization
10090
10091
10092@geindex Suppress_Initialization
10093
10094This boolean aspect is equivalent to @ref{f7,,pragma Suppress_Initialization}.
10095
10096@node Aspect Test_Case,Aspect Thread_Local_Storage,Aspect Suppress_Initialization,Implementation Defined Aspects
10097@anchor{gnat_rm/implementation_defined_aspects aspect-test-case}@anchor{157}
10098@section Aspect Test_Case
10099
10100
10101@geindex Test_Case
10102
10103This aspect is equivalent to @ref{fb,,pragma Test_Case}.
10104
10105@node Aspect Thread_Local_Storage,Aspect Universal_Aliasing,Aspect Test_Case,Implementation Defined Aspects
10106@anchor{gnat_rm/implementation_defined_aspects aspect-thread-local-storage}@anchor{158}
10107@section Aspect Thread_Local_Storage
10108
10109
10110@geindex Thread_Local_Storage
10111
10112This boolean aspect is equivalent to @ref{fd,,pragma Thread_Local_Storage}.
10113
10114@node Aspect Universal_Aliasing,Aspect Unmodified,Aspect Thread_Local_Storage,Implementation Defined Aspects
10115@anchor{gnat_rm/implementation_defined_aspects aspect-universal-aliasing}@anchor{159}
10116@section Aspect Universal_Aliasing
10117
10118
10119@geindex Universal_Aliasing
10120
10121This boolean aspect is equivalent to @ref{107,,pragma Universal_Aliasing}.
10122
10123@node Aspect Unmodified,Aspect Unreferenced,Aspect Universal_Aliasing,Implementation Defined Aspects
10124@anchor{gnat_rm/implementation_defined_aspects aspect-unmodified}@anchor{15a}
10125@section Aspect Unmodified
10126
10127
10128@geindex Unmodified
10129
10130This boolean aspect is equivalent to @ref{109,,pragma Unmodified}.
10131
10132@node Aspect Unreferenced,Aspect Unreferenced_Objects,Aspect Unmodified,Implementation Defined Aspects
10133@anchor{gnat_rm/implementation_defined_aspects aspect-unreferenced}@anchor{15b}
10134@section Aspect Unreferenced
10135
10136
10137@geindex Unreferenced
10138
10139This boolean aspect is equivalent to @ref{10b,,pragma Unreferenced}.
10140
10141When using the @code{-gnat2022} switch, this aspect is also supported on formal
10142parameters, which is in particular the only form possible for expression
10143functions.
10144
10145@node Aspect Unreferenced_Objects,Aspect Value_Size,Aspect Unreferenced,Implementation Defined Aspects
10146@anchor{gnat_rm/implementation_defined_aspects aspect-unreferenced-objects}@anchor{15c}
10147@section Aspect Unreferenced_Objects
10148
10149
10150@geindex Unreferenced_Objects
10151
10152This boolean aspect is equivalent to @ref{10d,,pragma Unreferenced_Objects}.
10153
10154@node Aspect Value_Size,Aspect Volatile_Full_Access,Aspect Unreferenced_Objects,Implementation Defined Aspects
10155@anchor{gnat_rm/implementation_defined_aspects aspect-value-size}@anchor{15d}
10156@section Aspect Value_Size
10157
10158
10159@geindex Value_Size
10160
10161This aspect is equivalent to @ref{15e,,attribute Value_Size}.
10162
10163@node Aspect Volatile_Full_Access,Aspect Volatile_Function,Aspect Value_Size,Implementation Defined Aspects
10164@anchor{gnat_rm/implementation_defined_aspects aspect-volatile-full-access}@anchor{15f}
10165@section Aspect Volatile_Full_Access
10166
10167
10168@geindex Volatile_Full_Access
10169
10170This boolean aspect is equivalent to @ref{117,,pragma Volatile_Full_Access}.
10171
10172@node Aspect Volatile_Function,Aspect Warnings,Aspect Volatile_Full_Access,Implementation Defined Aspects
10173@anchor{gnat_rm/implementation_defined_aspects aspect-volatile-function}@anchor{160}
10174@section Aspect Volatile_Function
10175
10176
10177@geindex Volatile_Function
10178
10179This boolean aspect is equivalent to @ref{119,,pragma Volatile_Function}.
10180
10181@node Aspect Warnings,,Aspect Volatile_Function,Implementation Defined Aspects
10182@anchor{gnat_rm/implementation_defined_aspects aspect-warnings}@anchor{161}
10183@section Aspect Warnings
10184
10185
10186@geindex Warnings
10187
10188This aspect is equivalent to the two argument form of @ref{11b,,pragma Warnings},
10189where the first argument is @code{ON} or @code{OFF} and the second argument
10190is the entity.
10191
10192@node Implementation Defined Attributes,Standard and Implementation Defined Restrictions,Implementation Defined Aspects,Top
10193@anchor{gnat_rm/implementation_defined_attributes doc}@anchor{162}@anchor{gnat_rm/implementation_defined_attributes id1}@anchor{163}@anchor{gnat_rm/implementation_defined_attributes implementation-defined-attributes}@anchor{8}
10194@chapter Implementation Defined Attributes
10195
10196
10197Ada defines (throughout the Ada reference manual,
10198summarized in Annex K),
10199a set of attributes that provide useful additional functionality in all
10200areas of the language.  These language defined attributes are implemented
10201in GNAT and work as described in the Ada Reference Manual.
10202
10203In addition, Ada allows implementations to define additional
10204attributes whose meaning is defined by the implementation.  GNAT provides
10205a number of these implementation-dependent attributes which can be used
10206to extend and enhance the functionality of the compiler.  This section of
10207the GNAT reference manual describes these additional attributes.  It also
10208describes additional implementation-dependent features of standard
10209language-defined attributes.
10210
10211Note that any program using these attributes may not be portable to
10212other compilers (although GNAT implements this set of attributes on all
10213platforms).  Therefore if portability to other compilers is an important
10214consideration, you should minimize the use of these attributes.
10215
10216@menu
10217* Attribute Abort_Signal::
10218* Attribute Address_Size::
10219* Attribute Asm_Input::
10220* Attribute Asm_Output::
10221* Attribute Atomic_Always_Lock_Free::
10222* Attribute Bit::
10223* Attribute Bit_Position::
10224* Attribute Code_Address::
10225* Attribute Compiler_Version::
10226* Attribute Constrained::
10227* Attribute Default_Bit_Order::
10228* Attribute Default_Scalar_Storage_Order::
10229* Attribute Deref::
10230* Attribute Descriptor_Size::
10231* Attribute Elaborated::
10232* Attribute Elab_Body::
10233* Attribute Elab_Spec::
10234* Attribute Elab_Subp_Body::
10235* Attribute Emax::
10236* Attribute Enabled::
10237* Attribute Enum_Rep::
10238* Attribute Enum_Val::
10239* Attribute Epsilon::
10240* Attribute Fast_Math::
10241* Attribute Finalization_Size::
10242* Attribute Fixed_Value::
10243* Attribute From_Any::
10244* Attribute Has_Access_Values::
10245* Attribute Has_Discriminants::
10246* Attribute Has_Tagged_Values::
10247* Attribute Img::
10248* Attribute Initialized::
10249* Attribute Integer_Value::
10250* Attribute Invalid_Value::
10251* Attribute Iterable::
10252* Attribute Large::
10253* Attribute Library_Level::
10254* Attribute Lock_Free::
10255* Attribute Loop_Entry::
10256* Attribute Machine_Size::
10257* Attribute Mantissa::
10258* Attribute Maximum_Alignment::
10259* Attribute Max_Integer_Size::
10260* Attribute Mechanism_Code::
10261* Attribute Null_Parameter::
10262* Attribute Object_Size::
10263* Attribute Old::
10264* Attribute Passed_By_Reference::
10265* Attribute Pool_Address::
10266* Attribute Range_Length::
10267* Attribute Restriction_Set::
10268* Attribute Result::
10269* Attribute Safe_Emax::
10270* Attribute Safe_Large::
10271* Attribute Safe_Small::
10272* Attribute Scalar_Storage_Order::
10273* Attribute Simple_Storage_Pool::
10274* Attribute Small::
10275* Attribute Small_Denominator::
10276* Attribute Small_Numerator::
10277* Attribute Storage_Unit::
10278* Attribute Stub_Type::
10279* Attribute System_Allocator_Alignment::
10280* Attribute Target_Name::
10281* Attribute To_Address::
10282* Attribute To_Any::
10283* Attribute Type_Class::
10284* Attribute Type_Key::
10285* Attribute TypeCode::
10286* Attribute Unconstrained_Array::
10287* Attribute Universal_Literal_String::
10288* Attribute Unrestricted_Access::
10289* Attribute Update::
10290* Attribute Valid_Image::
10291* Attribute Valid_Scalars::
10292* Attribute VADS_Size::
10293* Attribute Value_Size::
10294* Attribute Wchar_T_Size::
10295* Attribute Word_Size::
10296
10297@end menu
10298
10299@node Attribute Abort_Signal,Attribute Address_Size,,Implementation Defined Attributes
10300@anchor{gnat_rm/implementation_defined_attributes attribute-abort-signal}@anchor{164}
10301@section Attribute Abort_Signal
10302
10303
10304@geindex Abort_Signal
10305
10306@code{Standard'Abort_Signal} (@code{Standard} is the only allowed
10307prefix) provides the entity for the special exception used to signal
10308task abort or asynchronous transfer of control.  Normally this attribute
10309should only be used in the tasking runtime (it is highly peculiar, and
10310completely outside the normal semantics of Ada, for a user program to
10311intercept the abort exception).
10312
10313@node Attribute Address_Size,Attribute Asm_Input,Attribute Abort_Signal,Implementation Defined Attributes
10314@anchor{gnat_rm/implementation_defined_attributes attribute-address-size}@anchor{165}
10315@section Attribute Address_Size
10316
10317
10318@geindex Size of `@w{`}Address`@w{`}
10319
10320@geindex Address_Size
10321
10322@code{Standard'Address_Size} (@code{Standard} is the only allowed
10323prefix) is a static constant giving the number of bits in an
10324@code{Address}. It is the same value as System.Address’Size,
10325but has the advantage of being static, while a direct
10326reference to System.Address’Size is nonstatic because Address
10327is a private type.
10328
10329@node Attribute Asm_Input,Attribute Asm_Output,Attribute Address_Size,Implementation Defined Attributes
10330@anchor{gnat_rm/implementation_defined_attributes attribute-asm-input}@anchor{166}
10331@section Attribute Asm_Input
10332
10333
10334@geindex Asm_Input
10335
10336The @code{Asm_Input} attribute denotes a function that takes two
10337parameters.  The first is a string, the second is an expression of the
10338type designated by the prefix.  The first (string) argument is required
10339to be a static expression, and is the constraint for the parameter,
10340(e.g., what kind of register is required).  The second argument is the
10341value to be used as the input argument.  The possible values for the
10342constant are the same as those used in the RTL, and are dependent on
10343the configuration file used to built the GCC back end.
10344@ref{167,,Machine Code Insertions}
10345
10346@node Attribute Asm_Output,Attribute Atomic_Always_Lock_Free,Attribute Asm_Input,Implementation Defined Attributes
10347@anchor{gnat_rm/implementation_defined_attributes attribute-asm-output}@anchor{168}
10348@section Attribute Asm_Output
10349
10350
10351@geindex Asm_Output
10352
10353The @code{Asm_Output} attribute denotes a function that takes two
10354parameters.  The first is a string, the second is the name of a variable
10355of the type designated by the attribute prefix.  The first (string)
10356argument is required to be a static expression and designates the
10357constraint for the parameter (e.g., what kind of register is
10358required).  The second argument is the variable to be updated with the
10359result.  The possible values for constraint are the same as those used in
10360the RTL, and are dependent on the configuration file used to build the
10361GCC back end.  If there are no output operands, then this argument may
10362either be omitted, or explicitly given as @code{No_Output_Operands}.
10363@ref{167,,Machine Code Insertions}
10364
10365@node Attribute Atomic_Always_Lock_Free,Attribute Bit,Attribute Asm_Output,Implementation Defined Attributes
10366@anchor{gnat_rm/implementation_defined_attributes attribute-atomic-always-lock-free}@anchor{169}
10367@section Attribute Atomic_Always_Lock_Free
10368
10369
10370@geindex Atomic_Always_Lock_Free
10371
10372The prefix of the @code{Atomic_Always_Lock_Free} attribute is a type.
10373The result is a Boolean value which is True if the type has discriminants,
10374and False otherwise.  The result indicate whether atomic operations are
10375supported by the target for the given type.
10376
10377@node Attribute Bit,Attribute Bit_Position,Attribute Atomic_Always_Lock_Free,Implementation Defined Attributes
10378@anchor{gnat_rm/implementation_defined_attributes attribute-bit}@anchor{16a}
10379@section Attribute Bit
10380
10381
10382@geindex Bit
10383
10384@code{obj'Bit}, where @code{obj} is any object, yields the bit
10385offset within the storage unit (byte) that contains the first bit of
10386storage allocated for the object.  The value of this attribute is of the
10387type @emph{universal_integer} and is always a nonnegative number smaller
10388than @code{System.Storage_Unit}.
10389
10390For an object that is a variable or a constant allocated in a register,
10391the value is zero.  (The use of this attribute does not force the
10392allocation of a variable to memory).
10393
10394For an object that is a formal parameter, this attribute applies
10395to either the matching actual parameter or to a copy of the
10396matching actual parameter.
10397
10398For an access object the value is zero.  Note that
10399@code{obj.all'Bit} is subject to an @code{Access_Check} for the
10400designated object.  Similarly for a record component
10401@code{X.C'Bit} is subject to a discriminant check and
10402@code{X(I).Bit} and @code{X(I1..I2)'Bit}
10403are subject to index checks.
10404
10405This attribute is designed to be compatible with the DEC Ada 83 definition
10406and implementation of the @code{Bit} attribute.
10407
10408@node Attribute Bit_Position,Attribute Code_Address,Attribute Bit,Implementation Defined Attributes
10409@anchor{gnat_rm/implementation_defined_attributes attribute-bit-position}@anchor{16b}
10410@section Attribute Bit_Position
10411
10412
10413@geindex Bit_Position
10414
10415@code{R.C'Bit_Position}, where @code{R} is a record object and @code{C} is one
10416of the fields of the record type, yields the bit
10417offset within the record contains the first bit of
10418storage allocated for the object.  The value of this attribute is of the
10419type @emph{universal_integer}.  The value depends only on the field
10420@code{C} and is independent of the alignment of
10421the containing record @code{R}.
10422
10423@node Attribute Code_Address,Attribute Compiler_Version,Attribute Bit_Position,Implementation Defined Attributes
10424@anchor{gnat_rm/implementation_defined_attributes attribute-code-address}@anchor{16c}
10425@section Attribute Code_Address
10426
10427
10428@geindex Code_Address
10429
10430@geindex Subprogram address
10431
10432@geindex Address of subprogram code
10433
10434The @code{'Address}
10435attribute may be applied to subprograms in Ada 95 and Ada 2005, but the
10436intended effect seems to be to provide
10437an address value which can be used to call the subprogram by means of
10438an address clause as in the following example:
10439
10440@example
10441procedure K is ...
10442
10443procedure L;
10444for L'Address use K'Address;
10445pragma Import (Ada, L);
10446@end example
10447
10448A call to @code{L} is then expected to result in a call to @code{K}.
10449In Ada 83, where there were no access-to-subprogram values, this was
10450a common work-around for getting the effect of an indirect call.
10451GNAT implements the above use of @code{Address} and the technique
10452illustrated by the example code works correctly.
10453
10454However, for some purposes, it is useful to have the address of the start
10455of the generated code for the subprogram.  On some architectures, this is
10456not necessarily the same as the @code{Address} value described above.
10457For example, the @code{Address} value may reference a subprogram
10458descriptor rather than the subprogram itself.
10459
10460The @code{'Code_Address} attribute, which can only be applied to
10461subprogram entities, always returns the address of the start of the
10462generated code of the specified subprogram, which may or may not be
10463the same value as is returned by the corresponding @code{'Address}
10464attribute.
10465
10466@node Attribute Compiler_Version,Attribute Constrained,Attribute Code_Address,Implementation Defined Attributes
10467@anchor{gnat_rm/implementation_defined_attributes attribute-compiler-version}@anchor{16d}
10468@section Attribute Compiler_Version
10469
10470
10471@geindex Compiler_Version
10472
10473@code{Standard'Compiler_Version} (@code{Standard} is the only allowed
10474prefix) yields a static string identifying the version of the compiler
10475being used to compile the unit containing the attribute reference.
10476
10477@node Attribute Constrained,Attribute Default_Bit_Order,Attribute Compiler_Version,Implementation Defined Attributes
10478@anchor{gnat_rm/implementation_defined_attributes attribute-constrained}@anchor{16e}
10479@section Attribute Constrained
10480
10481
10482@geindex Constrained
10483
10484In addition to the usage of this attribute in the Ada RM, GNAT
10485also permits the use of the @code{'Constrained} attribute
10486in a generic template
10487for any type, including types without discriminants. The value of this
10488attribute in the generic instance when applied to a scalar type or a
10489record type without discriminants is always @code{True}. This usage is
10490compatible with older Ada compilers, including notably DEC Ada.
10491
10492@node Attribute Default_Bit_Order,Attribute Default_Scalar_Storage_Order,Attribute Constrained,Implementation Defined Attributes
10493@anchor{gnat_rm/implementation_defined_attributes attribute-default-bit-order}@anchor{16f}
10494@section Attribute Default_Bit_Order
10495
10496
10497@geindex Big endian
10498
10499@geindex Little endian
10500
10501@geindex Default_Bit_Order
10502
10503@code{Standard'Default_Bit_Order} (@code{Standard} is the only
10504allowed prefix), provides the value @code{System.Default_Bit_Order}
10505as a @code{Pos} value (0 for @code{High_Order_First}, 1 for
10506@code{Low_Order_First}).  This is used to construct the definition of
10507@code{Default_Bit_Order} in package @code{System}.
10508
10509@node Attribute Default_Scalar_Storage_Order,Attribute Deref,Attribute Default_Bit_Order,Implementation Defined Attributes
10510@anchor{gnat_rm/implementation_defined_attributes attribute-default-scalar-storage-order}@anchor{170}
10511@section Attribute Default_Scalar_Storage_Order
10512
10513
10514@geindex Big endian
10515
10516@geindex Little endian
10517
10518@geindex Default_Scalar_Storage_Order
10519
10520@code{Standard'Default_Scalar_Storage_Order} (@code{Standard} is the only
10521allowed prefix), provides the current value of the default scalar storage
10522order (as specified using pragma @code{Default_Scalar_Storage_Order}, or
10523equal to @code{Default_Bit_Order} if unspecified) as a
10524@code{System.Bit_Order} value. This is a static attribute.
10525
10526@node Attribute Deref,Attribute Descriptor_Size,Attribute Default_Scalar_Storage_Order,Implementation Defined Attributes
10527@anchor{gnat_rm/implementation_defined_attributes attribute-deref}@anchor{171}
10528@section Attribute Deref
10529
10530
10531@geindex Deref
10532
10533The attribute @code{typ'Deref(expr)} where @code{expr} is of type @code{System.Address} yields
10534the variable of type @code{typ} that is located at the given address. It is similar
10535to @code{(totyp (expr).all)}, where @code{totyp} is an unchecked conversion from address to
10536a named access-to-@cite{typ} type, except that it yields a variable, so it can be
10537used on the left side of an assignment.
10538
10539@node Attribute Descriptor_Size,Attribute Elaborated,Attribute Deref,Implementation Defined Attributes
10540@anchor{gnat_rm/implementation_defined_attributes attribute-descriptor-size}@anchor{172}
10541@section Attribute Descriptor_Size
10542
10543
10544@geindex Descriptor
10545
10546@geindex Dope vector
10547
10548@geindex Descriptor_Size
10549
10550Nonstatic attribute @code{Descriptor_Size} returns the size in bits of the
10551descriptor allocated for a type.  The result is non-zero only for unconstrained
10552array types and the returned value is of type universal integer.  In GNAT, an
10553array descriptor contains bounds information and is located immediately before
10554the first element of the array.
10555
10556@example
10557type Unconstr_Array is array (Short_Short_Integer range <>) of Positive;
10558Put_Line ("Descriptor size = " & Unconstr_Array'Descriptor_Size'Img);
10559@end example
10560
10561The attribute takes into account any padding due to the alignment of the
10562component type. In the example above, the descriptor contains two values
10563of type @code{Short_Short_Integer} representing the low and high bound. But,
10564since @code{Positive} has an alignment of 4, the size of the descriptor is
10565@code{2 * Short_Short_Integer'Size} rounded up to the next multiple of 32,
10566which yields a size of 32 bits, i.e. including 16 bits of padding.
10567
10568@node Attribute Elaborated,Attribute Elab_Body,Attribute Descriptor_Size,Implementation Defined Attributes
10569@anchor{gnat_rm/implementation_defined_attributes attribute-elaborated}@anchor{173}
10570@section Attribute Elaborated
10571
10572
10573@geindex Elaborated
10574
10575The prefix of the @code{'Elaborated} attribute must be a unit name.  The
10576value is a Boolean which indicates whether or not the given unit has been
10577elaborated.  This attribute is primarily intended for internal use by the
10578generated code for dynamic elaboration checking, but it can also be used
10579in user programs.  The value will always be True once elaboration of all
10580units has been completed.  An exception is for units which need no
10581elaboration, the value is always False for such units.
10582
10583@node Attribute Elab_Body,Attribute Elab_Spec,Attribute Elaborated,Implementation Defined Attributes
10584@anchor{gnat_rm/implementation_defined_attributes attribute-elab-body}@anchor{174}
10585@section Attribute Elab_Body
10586
10587
10588@geindex Elab_Body
10589
10590This attribute can only be applied to a program unit name.  It returns
10591the entity for the corresponding elaboration procedure for elaborating
10592the body of the referenced unit.  This is used in the main generated
10593elaboration procedure by the binder and is not normally used in any
10594other context.  However, there may be specialized situations in which it
10595is useful to be able to call this elaboration procedure from Ada code,
10596e.g., if it is necessary to do selective re-elaboration to fix some
10597error.
10598
10599@node Attribute Elab_Spec,Attribute Elab_Subp_Body,Attribute Elab_Body,Implementation Defined Attributes
10600@anchor{gnat_rm/implementation_defined_attributes attribute-elab-spec}@anchor{175}
10601@section Attribute Elab_Spec
10602
10603
10604@geindex Elab_Spec
10605
10606This attribute can only be applied to a program unit name.  It returns
10607the entity for the corresponding elaboration procedure for elaborating
10608the spec of the referenced unit.  This is used in the main
10609generated elaboration procedure by the binder and is not normally used
10610in any other context.  However, there may be specialized situations in
10611which it is useful to be able to call this elaboration procedure from
10612Ada code, e.g., if it is necessary to do selective re-elaboration to fix
10613some error.
10614
10615@node Attribute Elab_Subp_Body,Attribute Emax,Attribute Elab_Spec,Implementation Defined Attributes
10616@anchor{gnat_rm/implementation_defined_attributes attribute-elab-subp-body}@anchor{176}
10617@section Attribute Elab_Subp_Body
10618
10619
10620@geindex Elab_Subp_Body
10621
10622This attribute can only be applied to a library level subprogram
10623name and is only allowed in CodePeer mode. It returns the entity
10624for the corresponding elaboration procedure for elaborating the body
10625of the referenced subprogram unit. This is used in the main generated
10626elaboration procedure by the binder in CodePeer mode only and is unrecognized
10627otherwise.
10628
10629@node Attribute Emax,Attribute Enabled,Attribute Elab_Subp_Body,Implementation Defined Attributes
10630@anchor{gnat_rm/implementation_defined_attributes attribute-emax}@anchor{177}
10631@section Attribute Emax
10632
10633
10634@geindex Ada 83 attributes
10635
10636@geindex Emax
10637
10638The @code{Emax} attribute is provided for compatibility with Ada 83.  See
10639the Ada 83 reference manual for an exact description of the semantics of
10640this attribute.
10641
10642@node Attribute Enabled,Attribute Enum_Rep,Attribute Emax,Implementation Defined Attributes
10643@anchor{gnat_rm/implementation_defined_attributes attribute-enabled}@anchor{178}
10644@section Attribute Enabled
10645
10646
10647@geindex Enabled
10648
10649The @code{Enabled} attribute allows an application program to check at compile
10650time to see if the designated check is currently enabled. The prefix is a
10651simple identifier, referencing any predefined check name (other than
10652@code{All_Checks}) or a check name introduced by pragma Check_Name. If
10653no argument is given for the attribute, the check is for the general state
10654of the check, if an argument is given, then it is an entity name, and the
10655check indicates whether an @code{Suppress} or @code{Unsuppress} has been
10656given naming the entity (if not, then the argument is ignored).
10657
10658Note that instantiations inherit the check status at the point of the
10659instantiation, so a useful idiom is to have a library package that
10660introduces a check name with @code{pragma Check_Name}, and then contains
10661generic packages or subprograms which use the @code{Enabled} attribute
10662to see if the check is enabled. A user of this package can then issue
10663a @code{pragma Suppress} or @code{pragma Unsuppress} before instantiating
10664the package or subprogram, controlling whether the check will be present.
10665
10666@node Attribute Enum_Rep,Attribute Enum_Val,Attribute Enabled,Implementation Defined Attributes
10667@anchor{gnat_rm/implementation_defined_attributes attribute-enum-rep}@anchor{179}
10668@section Attribute Enum_Rep
10669
10670
10671@geindex Representation of enums
10672
10673@geindex Enum_Rep
10674
10675Note that this attribute is now standard in Ada 202x and is available
10676as an implementation defined attribute for earlier Ada versions.
10677
10678For every enumeration subtype @code{S}, @code{S'Enum_Rep} denotes a
10679function with the following spec:
10680
10681@example
10682function S'Enum_Rep (Arg : S'Base) return <Universal_Integer>;
10683@end example
10684
10685It is also allowable to apply @code{Enum_Rep} directly to an object of an
10686enumeration type or to a non-overloaded enumeration
10687literal.  In this case @code{S'Enum_Rep} is equivalent to
10688@code{typ'Enum_Rep(S)} where @code{typ} is the type of the
10689enumeration literal or object.
10690
10691The function returns the representation value for the given enumeration
10692value.  This will be equal to value of the @code{Pos} attribute in the
10693absence of an enumeration representation clause.  This is a static
10694attribute (i.e., the result is static if the argument is static).
10695
10696@code{S'Enum_Rep} can also be used with integer types and objects,
10697in which case it simply returns the integer value.  The reason for this
10698is to allow it to be used for @code{(<>)} discrete formal arguments in
10699a generic unit that can be instantiated with either enumeration types
10700or integer types.  Note that if @code{Enum_Rep} is used on a modular
10701type whose upper bound exceeds the upper bound of the largest signed
10702integer type, and the argument is a variable, so that the universal
10703integer calculation is done at run time, then the call to @code{Enum_Rep}
10704may raise @code{Constraint_Error}.
10705
10706@node Attribute Enum_Val,Attribute Epsilon,Attribute Enum_Rep,Implementation Defined Attributes
10707@anchor{gnat_rm/implementation_defined_attributes attribute-enum-val}@anchor{17a}
10708@section Attribute Enum_Val
10709
10710
10711@geindex Representation of enums
10712
10713@geindex Enum_Val
10714
10715Note that this attribute is now standard in Ada 202x and is available
10716as an implementation defined attribute for earlier Ada versions.
10717
10718For every enumeration subtype @code{S}, @code{S'Enum_Val} denotes a
10719function with the following spec:
10720
10721@example
10722function S'Enum_Val (Arg : <Universal_Integer>) return S'Base;
10723@end example
10724
10725The function returns the enumeration value whose representation matches the
10726argument, or raises Constraint_Error if no enumeration literal of the type
10727has the matching value.
10728This will be equal to value of the @code{Val} attribute in the
10729absence of an enumeration representation clause.  This is a static
10730attribute (i.e., the result is static if the argument is static).
10731
10732@node Attribute Epsilon,Attribute Fast_Math,Attribute Enum_Val,Implementation Defined Attributes
10733@anchor{gnat_rm/implementation_defined_attributes attribute-epsilon}@anchor{17b}
10734@section Attribute Epsilon
10735
10736
10737@geindex Ada 83 attributes
10738
10739@geindex Epsilon
10740
10741The @code{Epsilon} attribute is provided for compatibility with Ada 83.  See
10742the Ada 83 reference manual for an exact description of the semantics of
10743this attribute.
10744
10745@node Attribute Fast_Math,Attribute Finalization_Size,Attribute Epsilon,Implementation Defined Attributes
10746@anchor{gnat_rm/implementation_defined_attributes attribute-fast-math}@anchor{17c}
10747@section Attribute Fast_Math
10748
10749
10750@geindex Fast_Math
10751
10752@code{Standard'Fast_Math} (@code{Standard} is the only allowed
10753prefix) yields a static Boolean value that is True if pragma
10754@code{Fast_Math} is active, and False otherwise.
10755
10756@node Attribute Finalization_Size,Attribute Fixed_Value,Attribute Fast_Math,Implementation Defined Attributes
10757@anchor{gnat_rm/implementation_defined_attributes attribute-finalization-size}@anchor{17d}
10758@section Attribute Finalization_Size
10759
10760
10761@geindex Finalization_Size
10762
10763The prefix of attribute @code{Finalization_Size} must be an object or
10764a non-class-wide type. This attribute returns the size of any hidden data
10765reserved by the compiler to handle finalization-related actions. The type of
10766the attribute is @emph{universal_integer}.
10767
10768@code{Finalization_Size} yields a value of zero for a type with no controlled
10769parts, an object whose type has no controlled parts, or an object of a
10770class-wide type whose tag denotes a type with no controlled parts.
10771
10772Note that only heap-allocated objects contain finalization data.
10773
10774@node Attribute Fixed_Value,Attribute From_Any,Attribute Finalization_Size,Implementation Defined Attributes
10775@anchor{gnat_rm/implementation_defined_attributes attribute-fixed-value}@anchor{17e}
10776@section Attribute Fixed_Value
10777
10778
10779@geindex Fixed_Value
10780
10781For every fixed-point type @code{S}, @code{S'Fixed_Value} denotes a
10782function with the following specification:
10783
10784@example
10785function S'Fixed_Value (Arg : <Universal_Integer>) return S;
10786@end example
10787
10788The value returned is the fixed-point value @code{V} such that:
10789
10790@example
10791V = Arg * S'Small
10792@end example
10793
10794The effect is thus similar to first converting the argument to the
10795integer type used to represent @code{S}, and then doing an unchecked
10796conversion to the fixed-point type.  The difference is
10797that there are full range checks, to ensure that the result is in range.
10798This attribute is primarily intended for use in implementation of the
10799input-output functions for fixed-point values.
10800
10801@node Attribute From_Any,Attribute Has_Access_Values,Attribute Fixed_Value,Implementation Defined Attributes
10802@anchor{gnat_rm/implementation_defined_attributes attribute-from-any}@anchor{17f}
10803@section Attribute From_Any
10804
10805
10806@geindex From_Any
10807
10808This internal attribute is used for the generation of remote subprogram
10809stubs in the context of the Distributed Systems Annex.
10810
10811@node Attribute Has_Access_Values,Attribute Has_Discriminants,Attribute From_Any,Implementation Defined Attributes
10812@anchor{gnat_rm/implementation_defined_attributes attribute-has-access-values}@anchor{180}
10813@section Attribute Has_Access_Values
10814
10815
10816@geindex Access values
10817@geindex testing for
10818
10819@geindex Has_Access_Values
10820
10821The prefix of the @code{Has_Access_Values} attribute is a type.  The result
10822is a Boolean value which is True if the is an access type, or is a composite
10823type with a component (at any nesting depth) that is an access type, and is
10824False otherwise.
10825The intended use of this attribute is in conjunction with generic
10826definitions.  If the attribute is applied to a generic private type, it
10827indicates whether or not the corresponding actual type has access values.
10828
10829@node Attribute Has_Discriminants,Attribute Has_Tagged_Values,Attribute Has_Access_Values,Implementation Defined Attributes
10830@anchor{gnat_rm/implementation_defined_attributes attribute-has-discriminants}@anchor{181}
10831@section Attribute Has_Discriminants
10832
10833
10834@geindex Discriminants
10835@geindex testing for
10836
10837@geindex Has_Discriminants
10838
10839The prefix of the @code{Has_Discriminants} attribute is a type.  The result
10840is a Boolean value which is True if the type has discriminants, and False
10841otherwise.  The intended use of this attribute is in conjunction with generic
10842definitions.  If the attribute is applied to a generic private type, it
10843indicates whether or not the corresponding actual type has discriminants.
10844
10845@node Attribute Has_Tagged_Values,Attribute Img,Attribute Has_Discriminants,Implementation Defined Attributes
10846@anchor{gnat_rm/implementation_defined_attributes attribute-has-tagged-values}@anchor{182}
10847@section Attribute Has_Tagged_Values
10848
10849
10850@geindex Tagged values
10851@geindex testing for
10852
10853@geindex Has_Tagged_Values
10854
10855The prefix of the @code{Has_Tagged_Values} attribute is a type. The result is a
10856Boolean value which is True if the type is a composite type (array or record)
10857that is either a tagged type or has a subcomponent that is tagged, and is False
10858otherwise. The intended use of this attribute is in conjunction with generic
10859definitions. If the attribute is applied to a generic private type, it
10860indicates whether or not the corresponding actual type has access values.
10861
10862@node Attribute Img,Attribute Initialized,Attribute Has_Tagged_Values,Implementation Defined Attributes
10863@anchor{gnat_rm/implementation_defined_attributes attribute-img}@anchor{183}
10864@section Attribute Img
10865
10866
10867@geindex Img
10868
10869The @code{Img} attribute differs from @code{Image} in that, while both can be
10870applied directly to an object, @code{Img} cannot be applied to types.
10871
10872Example usage of the attribute:
10873
10874@example
10875Put_Line ("X = " & X'Img);
10876@end example
10877
10878which has the same meaning as the more verbose:
10879
10880@example
10881Put_Line ("X = " & T'Image (X));
10882@end example
10883
10884where @code{T} is the (sub)type of the object @code{X}.
10885
10886Note that technically, in analogy to @code{Image},
10887@code{X'Img} returns a parameterless function
10888that returns the appropriate string when called. This means that
10889@code{X'Img} can be renamed as a function-returning-string, or used
10890in an instantiation as a function parameter.
10891
10892@node Attribute Initialized,Attribute Integer_Value,Attribute Img,Implementation Defined Attributes
10893@anchor{gnat_rm/implementation_defined_attributes attribute-initialized}@anchor{184}
10894@section Attribute Initialized
10895
10896
10897@geindex Initialized
10898
10899For the syntax and semantics of this attribute, see the SPARK 2014 Reference
10900Manual, section 6.10.
10901
10902@node Attribute Integer_Value,Attribute Invalid_Value,Attribute Initialized,Implementation Defined Attributes
10903@anchor{gnat_rm/implementation_defined_attributes attribute-integer-value}@anchor{185}
10904@section Attribute Integer_Value
10905
10906
10907@geindex Integer_Value
10908
10909For every integer type @code{S}, @code{S'Integer_Value} denotes a
10910function with the following spec:
10911
10912@example
10913function S'Integer_Value (Arg : <Universal_Fixed>) return S;
10914@end example
10915
10916The value returned is the integer value @code{V}, such that:
10917
10918@example
10919Arg = V * T'Small
10920@end example
10921
10922where @code{T} is the type of @code{Arg}.
10923The effect is thus similar to first doing an unchecked conversion from
10924the fixed-point type to its corresponding implementation type, and then
10925converting the result to the target integer type.  The difference is
10926that there are full range checks, to ensure that the result is in range.
10927This attribute is primarily intended for use in implementation of the
10928standard input-output functions for fixed-point values.
10929
10930@node Attribute Invalid_Value,Attribute Iterable,Attribute Integer_Value,Implementation Defined Attributes
10931@anchor{gnat_rm/implementation_defined_attributes attribute-invalid-value}@anchor{186}
10932@section Attribute Invalid_Value
10933
10934
10935@geindex Invalid_Value
10936
10937For every scalar type S, S’Invalid_Value returns an undefined value of the
10938type. If possible this value is an invalid representation for the type. The
10939value returned is identical to the value used to initialize an otherwise
10940uninitialized value of the type if pragma Initialize_Scalars is used,
10941including the ability to modify the value with the binder -Sxx flag and
10942relevant environment variables at run time.
10943
10944@node Attribute Iterable,Attribute Large,Attribute Invalid_Value,Implementation Defined Attributes
10945@anchor{gnat_rm/implementation_defined_attributes attribute-iterable}@anchor{187}
10946@section Attribute Iterable
10947
10948
10949@geindex Iterable
10950
10951Equivalent to Aspect Iterable.
10952
10953@node Attribute Large,Attribute Library_Level,Attribute Iterable,Implementation Defined Attributes
10954@anchor{gnat_rm/implementation_defined_attributes attribute-large}@anchor{188}
10955@section Attribute Large
10956
10957
10958@geindex Ada 83 attributes
10959
10960@geindex Large
10961
10962The @code{Large} attribute is provided for compatibility with Ada 83.  See
10963the Ada 83 reference manual for an exact description of the semantics of
10964this attribute.
10965
10966@node Attribute Library_Level,Attribute Lock_Free,Attribute Large,Implementation Defined Attributes
10967@anchor{gnat_rm/implementation_defined_attributes attribute-library-level}@anchor{189}
10968@section Attribute Library_Level
10969
10970
10971@geindex Library_Level
10972
10973@code{P'Library_Level}, where P is an entity name,
10974returns a Boolean value which is True if the entity is declared
10975at the library level, and False otherwise. Note that within a
10976generic instantition, the name of the generic unit denotes the
10977instance, which means that this attribute can be used to test
10978if a generic is instantiated at the library level, as shown
10979in this example:
10980
10981@example
10982generic
10983  ...
10984package Gen is
10985  pragma Compile_Time_Error
10986    (not Gen'Library_Level,
10987     "Gen can only be instantiated at library level");
10988  ...
10989end Gen;
10990@end example
10991
10992@node Attribute Lock_Free,Attribute Loop_Entry,Attribute Library_Level,Implementation Defined Attributes
10993@anchor{gnat_rm/implementation_defined_attributes attribute-lock-free}@anchor{18a}
10994@section Attribute Lock_Free
10995
10996
10997@geindex Lock_Free
10998
10999@code{P'Lock_Free}, where P is a protected object, returns True if a
11000pragma @code{Lock_Free} applies to P.
11001
11002@node Attribute Loop_Entry,Attribute Machine_Size,Attribute Lock_Free,Implementation Defined Attributes
11003@anchor{gnat_rm/implementation_defined_attributes attribute-loop-entry}@anchor{18b}
11004@section Attribute Loop_Entry
11005
11006
11007@geindex Loop_Entry
11008
11009Syntax:
11010
11011@example
11012X'Loop_Entry [(loop_name)]
11013@end example
11014
11015The @code{Loop_Entry} attribute is used to refer to the value that an
11016expression had upon entry to a given loop in much the same way that the
11017@code{Old} attribute in a subprogram postcondition can be used to refer
11018to the value an expression had upon entry to the subprogram. The
11019relevant loop is either identified by the given loop name, or it is the
11020innermost enclosing loop when no loop name is given.
11021
11022A @code{Loop_Entry} attribute can only occur within a
11023@code{Loop_Variant} or @code{Loop_Invariant} pragma. A common use of
11024@code{Loop_Entry} is to compare the current value of objects with their
11025initial value at loop entry, in a @code{Loop_Invariant} pragma.
11026
11027The effect of using @code{X'Loop_Entry} is the same as declaring
11028a constant initialized with the initial value of @code{X} at loop
11029entry. This copy is not performed if the loop is not entered, or if the
11030corresponding pragmas are ignored or disabled.
11031
11032@node Attribute Machine_Size,Attribute Mantissa,Attribute Loop_Entry,Implementation Defined Attributes
11033@anchor{gnat_rm/implementation_defined_attributes attribute-machine-size}@anchor{18c}
11034@section Attribute Machine_Size
11035
11036
11037@geindex Machine_Size
11038
11039This attribute is identical to the @code{Object_Size} attribute.  It is
11040provided for compatibility with the DEC Ada 83 attribute of this name.
11041
11042@node Attribute Mantissa,Attribute Maximum_Alignment,Attribute Machine_Size,Implementation Defined Attributes
11043@anchor{gnat_rm/implementation_defined_attributes attribute-mantissa}@anchor{18d}
11044@section Attribute Mantissa
11045
11046
11047@geindex Ada 83 attributes
11048
11049@geindex Mantissa
11050
11051The @code{Mantissa} attribute is provided for compatibility with Ada 83.  See
11052the Ada 83 reference manual for an exact description of the semantics of
11053this attribute.
11054
11055@node Attribute Maximum_Alignment,Attribute Max_Integer_Size,Attribute Mantissa,Implementation Defined Attributes
11056@anchor{gnat_rm/implementation_defined_attributes attribute-maximum-alignment}@anchor{18e}@anchor{gnat_rm/implementation_defined_attributes id2}@anchor{18f}
11057@section Attribute Maximum_Alignment
11058
11059
11060@geindex Alignment
11061@geindex maximum
11062
11063@geindex Maximum_Alignment
11064
11065@code{Standard'Maximum_Alignment} (@code{Standard} is the only
11066allowed prefix) provides the maximum useful alignment value for the
11067target.  This is a static value that can be used to specify the alignment
11068for an object, guaranteeing that it is properly aligned in all
11069cases.
11070
11071@node Attribute Max_Integer_Size,Attribute Mechanism_Code,Attribute Maximum_Alignment,Implementation Defined Attributes
11072@anchor{gnat_rm/implementation_defined_attributes attribute-max-integer-size}@anchor{190}
11073@section Attribute Max_Integer_Size
11074
11075
11076@geindex Max_Integer_Size
11077
11078@code{Standard'Max_Integer_Size} (@code{Standard} is the only allowed
11079prefix) provides the size of the largest supported integer type for
11080the target. The result is a static constant.
11081
11082@node Attribute Mechanism_Code,Attribute Null_Parameter,Attribute Max_Integer_Size,Implementation Defined Attributes
11083@anchor{gnat_rm/implementation_defined_attributes attribute-mechanism-code}@anchor{191}
11084@section Attribute Mechanism_Code
11085
11086
11087@geindex Return values
11088@geindex passing mechanism
11089
11090@geindex Parameters
11091@geindex passing mechanism
11092
11093@geindex Mechanism_Code
11094
11095@code{func'Mechanism_Code} yields an integer code for the
11096mechanism used for the result of function @code{func}, and
11097@code{subprog'Mechanism_Code (n)} yields the mechanism
11098used for formal parameter number @emph{n} (a static integer value, with 1
11099meaning the first parameter) of subprogram @code{subprog}.  The code returned is:
11100
11101
11102@table @asis
11103
11104@item @emph{1}
11105
11106by copy (value)
11107
11108@item @emph{2}
11109
11110by reference
11111@end table
11112
11113@node Attribute Null_Parameter,Attribute Object_Size,Attribute Mechanism_Code,Implementation Defined Attributes
11114@anchor{gnat_rm/implementation_defined_attributes attribute-null-parameter}@anchor{192}
11115@section Attribute Null_Parameter
11116
11117
11118@geindex Zero address
11119@geindex passing
11120
11121@geindex Null_Parameter
11122
11123A reference @code{T'Null_Parameter} denotes an imaginary object of
11124type or subtype @code{T} allocated at machine address zero.  The attribute
11125is allowed only as the default expression of a formal parameter, or as
11126an actual expression of a subprogram call.  In either case, the
11127subprogram must be imported.
11128
11129The identity of the object is represented by the address zero in the
11130argument list, independent of the passing mechanism (explicit or
11131default).
11132
11133This capability is needed to specify that a zero address should be
11134passed for a record or other composite object passed by reference.
11135There is no way of indicating this without the @code{Null_Parameter}
11136attribute.
11137
11138@node Attribute Object_Size,Attribute Old,Attribute Null_Parameter,Implementation Defined Attributes
11139@anchor{gnat_rm/implementation_defined_attributes attribute-object-size}@anchor{142}@anchor{gnat_rm/implementation_defined_attributes id3}@anchor{193}
11140@section Attribute Object_Size
11141
11142
11143@geindex Size
11144@geindex used for objects
11145
11146@geindex Object_Size
11147
11148The size of an object is not necessarily the same as the size of the type
11149of an object.  This is because by default object sizes are increased to be
11150a multiple of the alignment of the object.  For example,
11151@code{Natural'Size} is
1115231, but by default objects of type @code{Natural} will have a size of 32 bits.
11153Similarly, a record containing an integer and a character:
11154
11155@example
11156type Rec is record
11157   I : Integer;
11158   C : Character;
11159end record;
11160@end example
11161
11162will have a size of 40 (that is @code{Rec'Size} will be 40).  The
11163alignment will be 4, because of the
11164integer field, and so the default size of record objects for this type
11165will be 64 (8 bytes).
11166
11167If the alignment of the above record is specified to be 1, then the
11168object size will be 40 (5 bytes). This is true by default, and also
11169an object size of 40 can be explicitly specified in this case.
11170
11171A consequence of this capability is that different object sizes can be
11172given to subtypes that would otherwise be considered in Ada to be
11173statically matching.  But it makes no sense to consider such subtypes
11174as statically matching.  Consequently, GNAT adds a rule
11175to the static matching rules that requires object sizes to match.
11176Consider this example:
11177
11178@example
11179 1. procedure BadAVConvert is
11180 2.    type R is new Integer;
11181 3.    subtype R1 is R range 1 .. 10;
11182 4.    subtype R2 is R range 1 .. 10;
11183 5.    for R1'Object_Size use 8;
11184 6.    for R2'Object_Size use 16;
11185 7.    type R1P is access all R1;
11186 8.    type R2P is access all R2;
11187 9.    R1PV : R1P := new R1'(4);
1118810.    R2PV : R2P;
1118911. begin
1119012.    R2PV := R2P (R1PV);
11191               |
11192       >>> target designated subtype not compatible with
11193           type "R1" defined at line 3
11194
1119513. end;
11196@end example
11197
11198In the absence of lines 5 and 6,
11199types @code{R1} and @code{R2} statically match and
11200hence the conversion on line 12 is legal. But since lines 5 and 6
11201cause the object sizes to differ, GNAT considers that types
11202@code{R1} and @code{R2} are not statically matching, and line 12
11203generates the diagnostic shown above.
11204
11205Similar additional checks are performed in other contexts requiring
11206statically matching subtypes.
11207
11208@node Attribute Old,Attribute Passed_By_Reference,Attribute Object_Size,Implementation Defined Attributes
11209@anchor{gnat_rm/implementation_defined_attributes attribute-old}@anchor{194}
11210@section Attribute Old
11211
11212
11213@geindex Old
11214
11215In addition to the usage of @code{Old} defined in the Ada 2012 RM (usage
11216within @code{Post} aspect), GNAT also permits the use of this attribute
11217in implementation defined pragmas @code{Postcondition},
11218@code{Contract_Cases} and @code{Test_Case}. Also usages of
11219@code{Old} which would be illegal according to the Ada 2012 RM
11220definition are allowed under control of
11221implementation defined pragma @code{Unevaluated_Use_Of_Old}.
11222
11223@node Attribute Passed_By_Reference,Attribute Pool_Address,Attribute Old,Implementation Defined Attributes
11224@anchor{gnat_rm/implementation_defined_attributes attribute-passed-by-reference}@anchor{195}
11225@section Attribute Passed_By_Reference
11226
11227
11228@geindex Parameters
11229@geindex when passed by reference
11230
11231@geindex Passed_By_Reference
11232
11233@code{typ'Passed_By_Reference} for any subtype @cite{typ} returns
11234a value of type @code{Boolean} value that is @code{True} if the type is
11235normally passed by reference and @code{False} if the type is normally
11236passed by copy in calls.  For scalar types, the result is always @code{False}
11237and is static.  For non-scalar types, the result is nonstatic.
11238
11239@node Attribute Pool_Address,Attribute Range_Length,Attribute Passed_By_Reference,Implementation Defined Attributes
11240@anchor{gnat_rm/implementation_defined_attributes attribute-pool-address}@anchor{196}
11241@section Attribute Pool_Address
11242
11243
11244@geindex Pool_Address
11245
11246@code{X'Pool_Address} for any object @code{X} returns the address
11247of X within its storage pool. This is the same as
11248@code{X'Address}, except that for an unconstrained array whose
11249bounds are allocated just before the first component,
11250@code{X'Pool_Address} returns the address of those bounds,
11251whereas @code{X'Address} returns the address of the first
11252component.
11253
11254Here, we are interpreting ‘storage pool’ broadly to mean
11255@code{wherever the object is allocated}, which could be a
11256user-defined storage pool,
11257the global heap, on the stack, or in a static memory area.
11258For an object created by @code{new}, @code{Ptr.all'Pool_Address} is
11259what is passed to @code{Allocate} and returned from @code{Deallocate}.
11260
11261@node Attribute Range_Length,Attribute Restriction_Set,Attribute Pool_Address,Implementation Defined Attributes
11262@anchor{gnat_rm/implementation_defined_attributes attribute-range-length}@anchor{197}
11263@section Attribute Range_Length
11264
11265
11266@geindex Range_Length
11267
11268@code{typ'Range_Length} for any discrete type @cite{typ} yields
11269the number of values represented by the subtype (zero for a null
11270range).  The result is static for static subtypes.  @code{Range_Length}
11271applied to the index subtype of a one dimensional array always gives the
11272same result as @code{Length} applied to the array itself.
11273
11274@node Attribute Restriction_Set,Attribute Result,Attribute Range_Length,Implementation Defined Attributes
11275@anchor{gnat_rm/implementation_defined_attributes attribute-restriction-set}@anchor{198}
11276@section Attribute Restriction_Set
11277
11278
11279@geindex Restriction_Set
11280
11281@geindex Restrictions
11282
11283This attribute allows compile time testing of restrictions that
11284are currently in effect. It is primarily intended for specializing
11285code in the run-time based on restrictions that are active (e.g.
11286don’t need to save fpt registers if restriction No_Floating_Point
11287is known to be in effect), but can be used anywhere.
11288
11289There are two forms:
11290
11291@example
11292System'Restriction_Set (partition_boolean_restriction_NAME)
11293System'Restriction_Set (No_Dependence => library_unit_NAME);
11294@end example
11295
11296In the case of the first form, the only restriction names
11297allowed are parameterless restrictions that are checked
11298for consistency at bind time. For a complete list see the
11299subtype @code{System.Rident.Partition_Boolean_Restrictions}.
11300
11301The result returned is True if the restriction is known to
11302be in effect, and False if the restriction is known not to
11303be in effect. An important guarantee is that the value of
11304a Restriction_Set attribute is known to be consistent throughout
11305all the code of a partition.
11306
11307This is trivially achieved if the entire partition is compiled
11308with a consistent set of restriction pragmas. However, the
11309compilation model does not require this. It is possible to
11310compile one set of units with one set of pragmas, and another
11311set of units with another set of pragmas. It is even possible
11312to compile a spec with one set of pragmas, and then WITH the
11313same spec with a different set of pragmas. Inconsistencies
11314in the actual use of the restriction are checked at bind time.
11315
11316In order to achieve the guarantee of consistency for the
11317Restriction_Set pragma, we consider that a use of the pragma
11318that yields False is equivalent to a violation of the
11319restriction.
11320
11321So for example if you write
11322
11323@example
11324if System'Restriction_Set (No_Floating_Point) then
11325   ...
11326else
11327   ...
11328end if;
11329@end example
11330
11331And the result is False, so that the else branch is executed,
11332you can assume that this restriction is not set for any unit
11333in the partition. This is checked by considering this use of
11334the restriction pragma to be a violation of the restriction
11335No_Floating_Point. This means that no other unit can attempt
11336to set this restriction (if some unit does attempt to set it,
11337the binder will refuse to bind the partition).
11338
11339Technical note: The restriction name and the unit name are
11340intepreted entirely syntactically, as in the corresponding
11341Restrictions pragma, they are not analyzed semantically,
11342so they do not have a type.
11343
11344@node Attribute Result,Attribute Safe_Emax,Attribute Restriction_Set,Implementation Defined Attributes
11345@anchor{gnat_rm/implementation_defined_attributes attribute-result}@anchor{199}
11346@section Attribute Result
11347
11348
11349@geindex Result
11350
11351@code{function'Result} can only be used with in a Postcondition pragma
11352for a function. The prefix must be the name of the corresponding function. This
11353is used to refer to the result of the function in the postcondition expression.
11354For a further discussion of the use of this attribute and examples of its use,
11355see the description of pragma Postcondition.
11356
11357@node Attribute Safe_Emax,Attribute Safe_Large,Attribute Result,Implementation Defined Attributes
11358@anchor{gnat_rm/implementation_defined_attributes attribute-safe-emax}@anchor{19a}
11359@section Attribute Safe_Emax
11360
11361
11362@geindex Ada 83 attributes
11363
11364@geindex Safe_Emax
11365
11366The @code{Safe_Emax} attribute is provided for compatibility with Ada 83.  See
11367the Ada 83 reference manual for an exact description of the semantics of
11368this attribute.
11369
11370@node Attribute Safe_Large,Attribute Safe_Small,Attribute Safe_Emax,Implementation Defined Attributes
11371@anchor{gnat_rm/implementation_defined_attributes attribute-safe-large}@anchor{19b}
11372@section Attribute Safe_Large
11373
11374
11375@geindex Ada 83 attributes
11376
11377@geindex Safe_Large
11378
11379The @code{Safe_Large} attribute is provided for compatibility with Ada 83.  See
11380the Ada 83 reference manual for an exact description of the semantics of
11381this attribute.
11382
11383@node Attribute Safe_Small,Attribute Scalar_Storage_Order,Attribute Safe_Large,Implementation Defined Attributes
11384@anchor{gnat_rm/implementation_defined_attributes attribute-safe-small}@anchor{19c}
11385@section Attribute Safe_Small
11386
11387
11388@geindex Ada 83 attributes
11389
11390@geindex Safe_Small
11391
11392The @code{Safe_Small} attribute is provided for compatibility with Ada 83.  See
11393the Ada 83 reference manual for an exact description of the semantics of
11394this attribute.
11395
11396@node Attribute Scalar_Storage_Order,Attribute Simple_Storage_Pool,Attribute Safe_Small,Implementation Defined Attributes
11397@anchor{gnat_rm/implementation_defined_attributes attribute-scalar-storage-order}@anchor{150}@anchor{gnat_rm/implementation_defined_attributes id4}@anchor{19d}
11398@section Attribute Scalar_Storage_Order
11399
11400
11401@geindex Endianness
11402
11403@geindex Scalar storage order
11404
11405@geindex Scalar_Storage_Order
11406
11407For every array or record type @code{S}, the representation attribute
11408@code{Scalar_Storage_Order} denotes the order in which storage elements
11409that make up scalar components are ordered within S. The value given must
11410be a static expression of type System.Bit_Order. The following is an example
11411of the use of this feature:
11412
11413@example
11414--  Component type definitions
11415
11416subtype Yr_Type is Natural range 0 .. 127;
11417subtype Mo_Type is Natural range 1 .. 12;
11418subtype Da_Type is Natural range 1 .. 31;
11419
11420--  Record declaration
11421
11422type Date is record
11423   Years_Since_1980 : Yr_Type;
11424   Month            : Mo_Type;
11425   Day_Of_Month     : Da_Type;
11426end record;
11427
11428--  Record representation clause
11429
11430for Date use record
11431   Years_Since_1980 at 0 range 0  ..  6;
11432   Month            at 0 range 7  .. 10;
11433   Day_Of_Month     at 0 range 11 .. 15;
11434end record;
11435
11436--  Attribute definition clauses
11437
11438for Date'Bit_Order use System.High_Order_First;
11439for Date'Scalar_Storage_Order use System.High_Order_First;
11440--  If Scalar_Storage_Order is specified, it must be consistent with
11441--  Bit_Order, so it's best to always define the latter explicitly if
11442--  the former is used.
11443@end example
11444
11445Other properties are as for the standard representation attribute @code{Bit_Order}
11446defined by Ada RM 13.5.3(4). The default is @code{System.Default_Bit_Order}.
11447
11448For a record type @code{T}, if @code{T'Scalar_Storage_Order} is
11449specified explicitly, it shall be equal to @code{T'Bit_Order}. Note:
11450this means that if a @code{Scalar_Storage_Order} attribute definition
11451clause is not confirming, then the type’s @code{Bit_Order} shall be
11452specified explicitly and set to the same value.
11453
11454Derived types inherit an explicitly set scalar storage order from their parent
11455types. This may be overridden for the derived type by giving an explicit scalar
11456storage order for it. However, for a record extension, the derived type must
11457have the same scalar storage order as the parent type.
11458
11459A component of a record type that is itself a record or an array and that does
11460not start and end on a byte boundary must have have the same scalar storage
11461order as the record type. A component of a bit-packed array type that is itself
11462a record or an array must have the same scalar storage order as the array type.
11463
11464No component of a type that has an explicit @code{Scalar_Storage_Order}
11465attribute definition may be aliased.
11466
11467A confirming @code{Scalar_Storage_Order} attribute definition clause (i.e.
11468with a value equal to @code{System.Default_Bit_Order}) has no effect.
11469
11470If the opposite storage order is specified, then whenever the value of
11471a scalar component of an object of type @code{S} is read, the storage
11472elements of the enclosing machine scalar are first reversed (before
11473retrieving the component value, possibly applying some shift and mask
11474operatings on the enclosing machine scalar), and the opposite operation
11475is done for writes.
11476
11477In that case, the restrictions set forth in 13.5.1(10.3/2) for scalar components
11478are relaxed. Instead, the following rules apply:
11479
11480
11481@itemize *
11482
11483@item
11484the underlying storage elements are those at positions
11485@code{(position + first_bit / storage_element_size) .. (position + (last_bit + storage_element_size - 1) / storage_element_size)}
11486
11487@item
11488the sequence of underlying storage elements shall have
11489a size no greater than the largest machine scalar
11490
11491@item
11492the enclosing machine scalar is defined as the smallest machine
11493scalar starting at a position no greater than
11494@code{position + first_bit / storage_element_size} and covering
11495storage elements at least up to @code{position + (last_bit + storage_element_size - 1) / storage_element_size`}
11496
11497@item
11498the position of the component is interpreted relative to that machine
11499scalar.
11500@end itemize
11501
11502If no scalar storage order is specified for a type (either directly, or by
11503inheritance in the case of a derived type), then the default is normally
11504the native ordering of the target, but this default can be overridden using
11505pragma @code{Default_Scalar_Storage_Order}.
11506
11507If a component of @code{T} is itself of a record or array type, the specfied
11508@code{Scalar_Storage_Order} does @emph{not} apply to that nested type: an explicit
11509attribute definition clause must be provided for the component type as well
11510if desired.
11511
11512Representation changes that explicitly or implicitly toggle the scalar storage
11513order are not supported and may result in erroneous execution of the program,
11514except when performed by means of an instance of @code{Ada.Unchecked_Conversion}.
11515
11516In particular, overlays are not supported and a warning is given for them:
11517
11518@example
11519type Rec_LE is record
11520   I : Integer;
11521end record;
11522
11523for Rec_LE use record
11524   I at 0 range 0 .. 31;
11525end record;
11526
11527for Rec_LE'Bit_Order use System.Low_Order_First;
11528for Rec_LE'Scalar_Storage_Order use System.Low_Order_First;
11529
11530type Rec_BE is record
11531   I : Integer;
11532end record;
11533
11534for Rec_BE use record
11535   I at 0 range 0 .. 31;
11536end record;
11537
11538for Rec_BE'Bit_Order use System.High_Order_First;
11539for Rec_BE'Scalar_Storage_Order use System.High_Order_First;
11540
11541R_LE : Rec_LE;
11542
11543R_BE : Rec_BE;
11544for R_BE'Address use R_LE'Address;
11545@end example
11546
11547@code{warning: overlay changes scalar storage order [enabled by default]}
11548
11549In most cases, such representation changes ought to be replaced by an
11550instantiation of a function or procedure provided by @code{GNAT.Byte_Swapping}.
11551
11552Note that the scalar storage order only affects the in-memory data
11553representation. It has no effect on the representation used by stream
11554attributes.
11555
11556Note that debuggers may be unable to display the correct value of scalar
11557components of a type for which the opposite storage order is specified.
11558
11559@node Attribute Simple_Storage_Pool,Attribute Small,Attribute Scalar_Storage_Order,Implementation Defined Attributes
11560@anchor{gnat_rm/implementation_defined_attributes attribute-simple-storage-pool}@anchor{e5}@anchor{gnat_rm/implementation_defined_attributes id5}@anchor{19e}
11561@section Attribute Simple_Storage_Pool
11562
11563
11564@geindex Storage pool
11565@geindex simple
11566
11567@geindex Simple storage pool
11568
11569@geindex Simple_Storage_Pool
11570
11571For every nonformal, nonderived access-to-object type @code{Acc}, the
11572representation attribute @code{Simple_Storage_Pool} may be specified
11573via an attribute_definition_clause (or by specifying the equivalent aspect):
11574
11575@example
11576My_Pool : My_Simple_Storage_Pool_Type;
11577
11578type Acc is access My_Data_Type;
11579
11580for Acc'Simple_Storage_Pool use My_Pool;
11581@end example
11582
11583The name given in an attribute_definition_clause for the
11584@code{Simple_Storage_Pool} attribute shall denote a variable of
11585a ‘simple storage pool type’ (see pragma @cite{Simple_Storage_Pool_Type}).
11586
11587The use of this attribute is only allowed for a prefix denoting a type
11588for which it has been specified. The type of the attribute is the type
11589of the variable specified as the simple storage pool of the access type,
11590and the attribute denotes that variable.
11591
11592It is illegal to specify both @code{Storage_Pool} and @code{Simple_Storage_Pool}
11593for the same access type.
11594
11595If the @code{Simple_Storage_Pool} attribute has been specified for an access
11596type, then applying the @code{Storage_Pool} attribute to the type is flagged
11597with a warning and its evaluation raises the exception @code{Program_Error}.
11598
11599If the Simple_Storage_Pool attribute has been specified for an access
11600type @code{S}, then the evaluation of the attribute @code{S'Storage_Size}
11601returns the result of calling @code{Storage_Size (S'Simple_Storage_Pool)},
11602which is intended to indicate the number of storage elements reserved for
11603the simple storage pool. If the Storage_Size function has not been defined
11604for the simple storage pool type, then this attribute returns zero.
11605
11606If an access type @code{S} has a specified simple storage pool of type
11607@code{SSP}, then the evaluation of an allocator for that access type calls
11608the primitive @code{Allocate} procedure for type @code{SSP}, passing
11609@code{S'Simple_Storage_Pool} as the pool parameter. The detailed
11610semantics of such allocators is the same as those defined for allocators
11611in section 13.11 of the @cite{Ada Reference Manual}, with the term
11612@emph{simple storage pool} substituted for @emph{storage pool}.
11613
11614If an access type @code{S} has a specified simple storage pool of type
11615@code{SSP}, then a call to an instance of the @code{Ada.Unchecked_Deallocation}
11616for that access type invokes the primitive @code{Deallocate} procedure
11617for type @code{SSP}, passing @code{S'Simple_Storage_Pool} as the pool
11618parameter. The detailed semantics of such unchecked deallocations is the same
11619as defined in section 13.11.2 of the Ada Reference Manual, except that the
11620term @emph{simple storage pool} is substituted for @emph{storage pool}.
11621
11622@node Attribute Small,Attribute Small_Denominator,Attribute Simple_Storage_Pool,Implementation Defined Attributes
11623@anchor{gnat_rm/implementation_defined_attributes attribute-small}@anchor{19f}
11624@section Attribute Small
11625
11626
11627@geindex Ada 83 attributes
11628
11629@geindex Small
11630
11631The @code{Small} attribute is defined in Ada 95 (and Ada 2005) only for
11632fixed-point types.
11633GNAT also allows this attribute to be applied to floating-point types
11634for compatibility with Ada 83.  See
11635the Ada 83 reference manual for an exact description of the semantics of
11636this attribute when applied to floating-point types.
11637
11638@node Attribute Small_Denominator,Attribute Small_Numerator,Attribute Small,Implementation Defined Attributes
11639@anchor{gnat_rm/implementation_defined_attributes attribute-small-denominator}@anchor{1a0}
11640@section Attribute Small_Denominator
11641
11642
11643@geindex Small
11644
11645@geindex Small_Denominator
11646
11647@code{typ'Small_Denominator} for any fixed-point subtype @cite{typ} yields the
11648denominator in the representation of @code{typ'Small} as a rational number
11649with coprime factors (i.e. as an irreducible fraction).
11650
11651@node Attribute Small_Numerator,Attribute Storage_Unit,Attribute Small_Denominator,Implementation Defined Attributes
11652@anchor{gnat_rm/implementation_defined_attributes attribute-small-numerator}@anchor{1a1}
11653@section Attribute Small_Numerator
11654
11655
11656@geindex Small
11657
11658@geindex Small_Numerator
11659
11660@code{typ'Small_Numerator} for any fixed-point subtype @cite{typ} yields the
11661numerator in the representation of @code{typ'Small} as a rational number
11662with coprime factors (i.e. as an irreducible fraction).
11663
11664@node Attribute Storage_Unit,Attribute Stub_Type,Attribute Small_Numerator,Implementation Defined Attributes
11665@anchor{gnat_rm/implementation_defined_attributes attribute-storage-unit}@anchor{1a2}
11666@section Attribute Storage_Unit
11667
11668
11669@geindex Storage_Unit
11670
11671@code{Standard'Storage_Unit} (@code{Standard} is the only allowed
11672prefix) provides the same value as @code{System.Storage_Unit}.
11673
11674@node Attribute Stub_Type,Attribute System_Allocator_Alignment,Attribute Storage_Unit,Implementation Defined Attributes
11675@anchor{gnat_rm/implementation_defined_attributes attribute-stub-type}@anchor{1a3}
11676@section Attribute Stub_Type
11677
11678
11679@geindex Stub_Type
11680
11681The GNAT implementation of remote access-to-classwide types is
11682organized as described in AARM section E.4 (20.t): a value of an RACW type
11683(designating a remote object) is represented as a normal access
11684value, pointing to a “stub” object which in turn contains the
11685necessary information to contact the designated remote object. A
11686call on any dispatching operation of such a stub object does the
11687remote call, if necessary, using the information in the stub object
11688to locate the target partition, etc.
11689
11690For a prefix @code{T} that denotes a remote access-to-classwide type,
11691@code{T'Stub_Type} denotes the type of the corresponding stub objects.
11692
11693By construction, the layout of @code{T'Stub_Type} is identical to that of
11694type @code{RACW_Stub_Type} declared in the internal implementation-defined
11695unit @code{System.Partition_Interface}. Use of this attribute will create
11696an implicit dependency on this unit.
11697
11698@node Attribute System_Allocator_Alignment,Attribute Target_Name,Attribute Stub_Type,Implementation Defined Attributes
11699@anchor{gnat_rm/implementation_defined_attributes attribute-system-allocator-alignment}@anchor{1a4}
11700@section Attribute System_Allocator_Alignment
11701
11702
11703@geindex Alignment
11704@geindex allocator
11705
11706@geindex System_Allocator_Alignment
11707
11708@code{Standard'System_Allocator_Alignment} (@code{Standard} is the only
11709allowed prefix) provides the observable guaranted to be honored by
11710the system allocator (malloc). This is a static value that can be used
11711in user storage pools based on malloc either to reject allocation
11712with alignment too large or to enable a realignment circuitry if the
11713alignment request is larger than this value.
11714
11715@node Attribute Target_Name,Attribute To_Address,Attribute System_Allocator_Alignment,Implementation Defined Attributes
11716@anchor{gnat_rm/implementation_defined_attributes attribute-target-name}@anchor{1a5}
11717@section Attribute Target_Name
11718
11719
11720@geindex Target_Name
11721
11722@code{Standard'Target_Name} (@code{Standard} is the only allowed
11723prefix) provides a static string value that identifies the target
11724for the current compilation. For GCC implementations, this is the
11725standard gcc target name without the terminating slash (for
11726example, GNAT 5.0 on windows yields “i586-pc-mingw32msv”).
11727
11728@node Attribute To_Address,Attribute To_Any,Attribute Target_Name,Implementation Defined Attributes
11729@anchor{gnat_rm/implementation_defined_attributes attribute-to-address}@anchor{1a6}
11730@section Attribute To_Address
11731
11732
11733@geindex To_Address
11734
11735The @code{System'To_Address}
11736(@code{System} is the only allowed prefix)
11737denotes a function identical to
11738@code{System.Storage_Elements.To_Address} except that
11739it is a static attribute.  This means that if its argument is
11740a static expression, then the result of the attribute is a
11741static expression.  This means that such an expression can be
11742used in contexts (e.g., preelaborable packages) which require a
11743static expression and where the function call could not be used
11744(since the function call is always nonstatic, even if its
11745argument is static). The argument must be in the range
11746-(2**(m-1)) .. 2**m-1, where m is the memory size
11747(typically 32 or 64). Negative values are intepreted in a
11748modular manner (e.g., -1 means the same as 16#FFFF_FFFF# on
11749a 32 bits machine).
11750
11751@node Attribute To_Any,Attribute Type_Class,Attribute To_Address,Implementation Defined Attributes
11752@anchor{gnat_rm/implementation_defined_attributes attribute-to-any}@anchor{1a7}
11753@section Attribute To_Any
11754
11755
11756@geindex To_Any
11757
11758This internal attribute is used for the generation of remote subprogram
11759stubs in the context of the Distributed Systems Annex.
11760
11761@node Attribute Type_Class,Attribute Type_Key,Attribute To_Any,Implementation Defined Attributes
11762@anchor{gnat_rm/implementation_defined_attributes attribute-type-class}@anchor{1a8}
11763@section Attribute Type_Class
11764
11765
11766@geindex Type_Class
11767
11768@code{typ'Type_Class} for any type or subtype @cite{typ} yields
11769the value of the type class for the full type of @cite{typ}.  If
11770@cite{typ} is a generic formal type, the value is the value for the
11771corresponding actual subtype.  The value of this attribute is of type
11772@code{System.Aux_DEC.Type_Class}, which has the following definition:
11773
11774@example
11775type Type_Class is
11776  (Type_Class_Enumeration,
11777   Type_Class_Integer,
11778   Type_Class_Fixed_Point,
11779   Type_Class_Floating_Point,
11780   Type_Class_Array,
11781   Type_Class_Record,
11782   Type_Class_Access,
11783   Type_Class_Task,
11784   Type_Class_Address);
11785@end example
11786
11787Protected types yield the value @code{Type_Class_Task}, which thus
11788applies to all concurrent types.  This attribute is designed to
11789be compatible with the DEC Ada 83 attribute of the same name.
11790
11791@node Attribute Type_Key,Attribute TypeCode,Attribute Type_Class,Implementation Defined Attributes
11792@anchor{gnat_rm/implementation_defined_attributes attribute-type-key}@anchor{1a9}
11793@section Attribute Type_Key
11794
11795
11796@geindex Type_Key
11797
11798The @code{Type_Key} attribute is applicable to a type or subtype and
11799yields a value of type Standard.String containing encoded information
11800about the type or subtype. This provides improved compatibility with
11801other implementations that support this attribute.
11802
11803@node Attribute TypeCode,Attribute Unconstrained_Array,Attribute Type_Key,Implementation Defined Attributes
11804@anchor{gnat_rm/implementation_defined_attributes attribute-typecode}@anchor{1aa}
11805@section Attribute TypeCode
11806
11807
11808@geindex TypeCode
11809
11810This internal attribute is used for the generation of remote subprogram
11811stubs in the context of the Distributed Systems Annex.
11812
11813@node Attribute Unconstrained_Array,Attribute Universal_Literal_String,Attribute TypeCode,Implementation Defined Attributes
11814@anchor{gnat_rm/implementation_defined_attributes attribute-unconstrained-array}@anchor{1ab}
11815@section Attribute Unconstrained_Array
11816
11817
11818@geindex Unconstrained_Array
11819
11820The @code{Unconstrained_Array} attribute can be used with a prefix that
11821denotes any type or subtype. It is a static attribute that yields
11822@code{True} if the prefix designates an unconstrained array,
11823and @code{False} otherwise. In a generic instance, the result is
11824still static, and yields the result of applying this test to the
11825generic actual.
11826
11827@node Attribute Universal_Literal_String,Attribute Unrestricted_Access,Attribute Unconstrained_Array,Implementation Defined Attributes
11828@anchor{gnat_rm/implementation_defined_attributes attribute-universal-literal-string}@anchor{1ac}
11829@section Attribute Universal_Literal_String
11830
11831
11832@geindex Named numbers
11833@geindex representation of
11834
11835@geindex Universal_Literal_String
11836
11837The prefix of @code{Universal_Literal_String} must be a named
11838number.  The static result is the string consisting of the characters of
11839the number as defined in the original source.  This allows the user
11840program to access the actual text of named numbers without intermediate
11841conversions and without the need to enclose the strings in quotes (which
11842would preclude their use as numbers).
11843
11844For example, the following program prints the first 50 digits of pi:
11845
11846@example
11847with Text_IO; use Text_IO;
11848with Ada.Numerics;
11849procedure Pi is
11850begin
11851   Put (Ada.Numerics.Pi'Universal_Literal_String);
11852end;
11853@end example
11854
11855@node Attribute Unrestricted_Access,Attribute Update,Attribute Universal_Literal_String,Implementation Defined Attributes
11856@anchor{gnat_rm/implementation_defined_attributes attribute-unrestricted-access}@anchor{1ad}
11857@section Attribute Unrestricted_Access
11858
11859
11860@geindex Access
11861@geindex unrestricted
11862
11863@geindex Unrestricted_Access
11864
11865The @code{Unrestricted_Access} attribute is similar to @code{Access}
11866except that all accessibility and aliased view checks are omitted.  This
11867is a user-beware attribute.
11868
11869For objects, it is similar to @code{Address}, for which it is a
11870desirable replacement where the value desired is an access type.
11871In other words, its effect is similar to first applying the
11872@code{Address} attribute and then doing an unchecked conversion to a
11873desired access type.
11874
11875For subprograms, @code{P'Unrestricted_Access} may be used where
11876@code{P'Access} would be illegal, to construct a value of a
11877less-nested named access type that designates a more-nested
11878subprogram. This value may be used in indirect calls, so long as the
11879more-nested subprogram still exists; once the subprogram containing it
11880has returned, such calls are erroneous. For example:
11881
11882@example
11883package body P is
11884
11885   type Less_Nested is not null access procedure;
11886   Global : Less_Nested;
11887
11888   procedure P1 is
11889   begin
11890      Global.all;
11891   end P1;
11892
11893   procedure P2 is
11894      Local_Var : Integer;
11895
11896      procedure More_Nested is
11897      begin
11898         ... Local_Var ...
11899      end More_Nested;
11900   begin
11901      Global := More_Nested'Unrestricted_Access;
11902      P1;
11903   end P2;
11904
11905end P;
11906@end example
11907
11908When P1 is called from P2, the call via Global is OK, but if P1 were
11909called after P2 returns, it would be an erroneous use of a dangling
11910pointer.
11911
11912For objects, it is possible to use @code{Unrestricted_Access} for any
11913type. However, if the result is of an access-to-unconstrained array
11914subtype, then the resulting pointer has the same scope as the context
11915of the attribute, and must not be returned to some enclosing scope.
11916For instance, if a function uses @code{Unrestricted_Access} to create
11917an access-to-unconstrained-array and returns that value to the caller,
11918the result will involve dangling pointers. In addition, it is only
11919valid to create pointers to unconstrained arrays using this attribute
11920if the pointer has the normal default ‘fat’ representation where a
11921pointer has two components, one points to the array and one points to
11922the bounds. If a size clause is used to force ‘thin’ representation
11923for a pointer to unconstrained where there is only space for a single
11924pointer, then the resulting pointer is not usable.
11925
11926In the simple case where a direct use of Unrestricted_Access attempts
11927to make a thin pointer for a non-aliased object, the compiler will
11928reject the use as illegal, as shown in the following example:
11929
11930@example
11931with System; use System;
11932procedure SliceUA2 is
11933   type A is access all String;
11934   for A'Size use Standard'Address_Size;
11935
11936   procedure P (Arg : A) is
11937   begin
11938      null;
11939   end P;
11940
11941   X : String := "hello world!";
11942   X2 : aliased String := "hello world!";
11943
11944   AV : A := X'Unrestricted_Access;    -- ERROR
11945             |
11946>>> illegal use of Unrestricted_Access attribute
11947>>> attempt to generate thin pointer to unaliased object
11948
11949begin
11950   P (X'Unrestricted_Access);          -- ERROR
11951      |
11952>>> illegal use of Unrestricted_Access attribute
11953>>> attempt to generate thin pointer to unaliased object
11954
11955   P (X(7 .. 12)'Unrestricted_Access); -- ERROR
11956      |
11957>>> illegal use of Unrestricted_Access attribute
11958>>> attempt to generate thin pointer to unaliased object
11959
11960   P (X2'Unrestricted_Access);         -- OK
11961end;
11962@end example
11963
11964but other cases cannot be detected by the compiler, and are
11965considered to be erroneous. Consider the following example:
11966
11967@example
11968with System; use System;
11969with System; use System;
11970procedure SliceUA is
11971   type AF is access all String;
11972
11973   type A is access all String;
11974   for A'Size use Standard'Address_Size;
11975
11976   procedure P (Arg : A) is
11977   begin
11978      if Arg'Length /= 6 then
11979         raise Program_Error;
11980      end if;
11981   end P;
11982
11983   X : String := "hello world!";
11984   Y : AF := X (7 .. 12)'Unrestricted_Access;
11985
11986begin
11987   P (A (Y));
11988end;
11989@end example
11990
11991A normal unconstrained array value
11992or a constrained array object marked as aliased has the bounds in memory
11993just before the array, so a thin pointer can retrieve both the data and
11994the bounds.  But in this case, the non-aliased object @code{X} does not have the
11995bounds before the string.  If the size clause for type @code{A}
11996were not present, then the pointer
11997would be a fat pointer, where one component is a pointer to the bounds,
11998and all would be well.  But with the size clause present, the conversion from
11999fat pointer to thin pointer in the call loses the bounds, and so this
12000is erroneous, and the program likely raises a @code{Program_Error} exception.
12001
12002In general, it is advisable to completely
12003avoid mixing the use of thin pointers and the use of
12004@code{Unrestricted_Access} where the designated type is an
12005unconstrained array.  The use of thin pointers should be restricted to
12006cases of porting legacy code that implicitly assumes the size of pointers,
12007and such code should not in any case be using this attribute.
12008
12009Another erroneous situation arises if the attribute is
12010applied to a constant. The resulting pointer can be used to access the
12011constant, but the effect of trying to modify a constant in this manner
12012is not well-defined. Consider this example:
12013
12014@example
12015P : constant Integer := 4;
12016type R is access all Integer;
12017RV : R := P'Unrestricted_Access;
12018..
12019RV.all := 3;
12020@end example
12021
12022Here we attempt to modify the constant P from 4 to 3, but the compiler may
12023or may not notice this attempt, and subsequent references to P may yield
12024either the value 3 or the value 4 or the assignment may blow up if the
12025compiler decides to put P in read-only memory. One particular case where
12026@code{Unrestricted_Access} can be used in this way is to modify the
12027value of an @code{in} parameter:
12028
12029@example
12030procedure K (S : in String) is
12031   type R is access all Character;
12032   RV : R := S (3)'Unrestricted_Access;
12033begin
12034   RV.all := 'a';
12035end;
12036@end example
12037
12038In general this is a risky approach. It may appear to “work” but such uses of
12039@code{Unrestricted_Access} are potentially non-portable, even from one version
12040of GNAT to another, so are best avoided if possible.
12041
12042@node Attribute Update,Attribute Valid_Image,Attribute Unrestricted_Access,Implementation Defined Attributes
12043@anchor{gnat_rm/implementation_defined_attributes attribute-update}@anchor{1ae}
12044@section Attribute Update
12045
12046
12047@geindex Update
12048
12049The @code{Update} attribute creates a copy of an array or record value
12050with one or more modified components. The syntax is:
12051
12052@example
12053PREFIX'Update ( RECORD_COMPONENT_ASSOCIATION_LIST )
12054PREFIX'Update ( ARRAY_COMPONENT_ASSOCIATION @{, ARRAY_COMPONENT_ASSOCIATION @} )
12055PREFIX'Update ( MULTIDIMENSIONAL_ARRAY_COMPONENT_ASSOCIATION
12056                @{, MULTIDIMENSIONAL_ARRAY_COMPONENT_ASSOCIATION @} )
12057
12058MULTIDIMENSIONAL_ARRAY_COMPONENT_ASSOCIATION ::= INDEX_EXPRESSION_LIST_LIST => EXPRESSION
12059INDEX_EXPRESSION_LIST_LIST                   ::= INDEX_EXPRESSION_LIST @{| INDEX_EXPRESSION_LIST @}
12060INDEX_EXPRESSION_LIST                        ::= ( EXPRESSION @{, EXPRESSION @} )
12061@end example
12062
12063where @code{PREFIX} is the name of an array or record object, the
12064association list in parentheses does not contain an @code{others}
12065choice and the box symbol @code{<>} may not appear in any
12066expression. The effect is to yield a copy of the array or record value
12067which is unchanged apart from the components mentioned in the
12068association list, which are changed to the indicated value. The
12069original value of the array or record value is not affected. For
12070example:
12071
12072@example
12073type Arr is Array (1 .. 5) of Integer;
12074...
12075Avar1 : Arr := (1,2,3,4,5);
12076Avar2 : Arr := Avar1'Update (2 => 10, 3 .. 4 => 20);
12077@end example
12078
12079yields a value for @code{Avar2} of 1,10,20,20,5 with @code{Avar1}
12080begin unmodified. Similarly:
12081
12082@example
12083type Rec is A, B, C : Integer;
12084...
12085Rvar1 : Rec := (A => 1, B => 2, C => 3);
12086Rvar2 : Rec := Rvar1'Update (B => 20);
12087@end example
12088
12089yields a value for @code{Rvar2} of (A => 1, B => 20, C => 3),
12090with @code{Rvar1} being unmodifed.
12091Note that the value of the attribute reference is computed
12092completely before it is used. This means that if you write:
12093
12094@example
12095Avar1 := Avar1'Update (1 => 10, 2 => Function_Call);
12096@end example
12097
12098then the value of @code{Avar1} is not modified if @code{Function_Call}
12099raises an exception, unlike the effect of a series of direct assignments
12100to elements of @code{Avar1}. In general this requires that
12101two extra complete copies of the object are required, which should be
12102kept in mind when considering efficiency.
12103
12104The @code{Update} attribute cannot be applied to prefixes of a limited
12105type, and cannot reference discriminants in the case of a record type.
12106The accessibility level of an Update attribute result object is defined
12107as for an aggregate.
12108
12109In the record case, no component can be mentioned more than once. In
12110the array case, two overlapping ranges can appear in the association list,
12111in which case the modifications are processed left to right.
12112
12113Multi-dimensional arrays can be modified, as shown by this example:
12114
12115@example
12116A : array (1 .. 10, 1 .. 10) of Integer;
12117..
12118A := A'Update ((1, 2) => 20, (3, 4) => 30);
12119@end example
12120
12121which changes element (1,2) to 20 and (3,4) to 30.
12122
12123@node Attribute Valid_Image,Attribute Valid_Scalars,Attribute Update,Implementation Defined Attributes
12124@anchor{gnat_rm/implementation_defined_attributes attribute-valid-image}@anchor{1af}
12125@section Attribute Valid_Image
12126
12127
12128@geindex Valid_Image
12129
12130The @code{'Valid_Image} attribute is defined for enumeration types other than
12131those in package Standard. This attribute is a function that takes
12132a String, and returns Boolean. @code{T'Valid_Image (S)} returns True
12133if and only if @code{T'Value (S)} would not raise Constraint_Error.
12134
12135@node Attribute Valid_Scalars,Attribute VADS_Size,Attribute Valid_Image,Implementation Defined Attributes
12136@anchor{gnat_rm/implementation_defined_attributes attribute-valid-scalars}@anchor{1b0}
12137@section Attribute Valid_Scalars
12138
12139
12140@geindex Valid_Scalars
12141
12142The @code{'Valid_Scalars} attribute is intended to make it easier to check the
12143validity of scalar subcomponents of composite objects. The attribute is defined
12144for any prefix @code{P} which denotes an object. Prefix @code{P} can be any type
12145except for tagged private or @code{Unchecked_Union} types. The value of the
12146attribute is of type @code{Boolean}.
12147
12148@code{P'Valid_Scalars} yields @code{True} if and only if the evaluation of
12149@code{C'Valid} yields @code{True} for every scalar subcomponent @code{C} of @code{P}, or if
12150@code{P} has no scalar subcomponents. Attribute @code{'Valid_Scalars} is equivalent
12151to attribute @code{'Valid} for scalar types.
12152
12153It is not specified in what order the subcomponents are checked, nor whether
12154any more are checked after any one of them is determined to be invalid. If the
12155prefix @code{P} is of a class-wide type @code{T'Class} (where @code{T} is the associated
12156specific type), or if the prefix @code{P} is of a specific tagged type @code{T}, then
12157only the subcomponents of @code{T} are checked; in other words, components of
12158extensions of @code{T} are not checked even if @code{T'Class (P)'Tag /= T'Tag}.
12159
12160The compiler will issue a warning if it can be determined at compile time that
12161the prefix of the attribute has no scalar subcomponents.
12162
12163Note: @code{Valid_Scalars} can generate a lot of code, especially in the case of
12164a large variant record. If the attribute is called in many places in the same
12165program applied to objects of the same type, it can reduce program size to
12166write a function with a single use of the attribute, and then call that
12167function from multiple places.
12168
12169@node Attribute VADS_Size,Attribute Value_Size,Attribute Valid_Scalars,Implementation Defined Attributes
12170@anchor{gnat_rm/implementation_defined_attributes attribute-vads-size}@anchor{1b1}
12171@section Attribute VADS_Size
12172
12173
12174@geindex Size
12175@geindex VADS compatibility
12176
12177@geindex VADS_Size
12178
12179The @code{'VADS_Size} attribute is intended to make it easier to port
12180legacy code which relies on the semantics of @code{'Size} as implemented
12181by the VADS Ada 83 compiler.  GNAT makes a best effort at duplicating the
12182same semantic interpretation.  In particular, @code{'VADS_Size} applied
12183to a predefined or other primitive type with no Size clause yields the
12184Object_Size (for example, @code{Natural'Size} is 32 rather than 31 on
12185typical machines).  In addition @code{'VADS_Size} applied to an object
12186gives the result that would be obtained by applying the attribute to
12187the corresponding type.
12188
12189@node Attribute Value_Size,Attribute Wchar_T_Size,Attribute VADS_Size,Implementation Defined Attributes
12190@anchor{gnat_rm/implementation_defined_attributes attribute-value-size}@anchor{15e}@anchor{gnat_rm/implementation_defined_attributes id6}@anchor{1b2}
12191@section Attribute Value_Size
12192
12193
12194@geindex Size
12195@geindex setting for not-first subtype
12196
12197@geindex Value_Size
12198
12199@code{type'Value_Size} is the number of bits required to represent
12200a value of the given subtype.  It is the same as @code{type'Size},
12201but, unlike @code{Size}, may be set for non-first subtypes.
12202
12203@node Attribute Wchar_T_Size,Attribute Word_Size,Attribute Value_Size,Implementation Defined Attributes
12204@anchor{gnat_rm/implementation_defined_attributes attribute-wchar-t-size}@anchor{1b3}
12205@section Attribute Wchar_T_Size
12206
12207
12208@geindex Wchar_T_Size
12209
12210@code{Standard'Wchar_T_Size} (@code{Standard} is the only allowed
12211prefix) provides the size in bits of the C @code{wchar_t} type
12212primarily for constructing the definition of this type in
12213package @code{Interfaces.C}. The result is a static constant.
12214
12215@node Attribute Word_Size,,Attribute Wchar_T_Size,Implementation Defined Attributes
12216@anchor{gnat_rm/implementation_defined_attributes attribute-word-size}@anchor{1b4}
12217@section Attribute Word_Size
12218
12219
12220@geindex Word_Size
12221
12222@code{Standard'Word_Size} (@code{Standard} is the only allowed
12223prefix) provides the value @code{System.Word_Size}. The result is
12224a static constant.
12225
12226@node Standard and Implementation Defined Restrictions,Implementation Advice,Implementation Defined Attributes,Top
12227@anchor{gnat_rm/standard_and_implementation_defined_restrictions doc}@anchor{1b5}@anchor{gnat_rm/standard_and_implementation_defined_restrictions id1}@anchor{1b6}@anchor{gnat_rm/standard_and_implementation_defined_restrictions standard-and-implementation-defined-restrictions}@anchor{9}
12228@chapter Standard and Implementation Defined Restrictions
12229
12230
12231All Ada Reference Manual-defined Restriction identifiers are implemented:
12232
12233
12234@itemize *
12235
12236@item
12237language-defined restrictions (see 13.12.1)
12238
12239@item
12240tasking restrictions (see D.7)
12241
12242@item
12243high integrity restrictions (see H.4)
12244@end itemize
12245
12246GNAT implements additional restriction identifiers. All restrictions, whether
12247language defined or GNAT-specific, are listed in the following.
12248
12249@menu
12250* Partition-Wide Restrictions::
12251* Program Unit Level Restrictions::
12252
12253@end menu
12254
12255@node Partition-Wide Restrictions,Program Unit Level Restrictions,,Standard and Implementation Defined Restrictions
12256@anchor{gnat_rm/standard_and_implementation_defined_restrictions id2}@anchor{1b7}@anchor{gnat_rm/standard_and_implementation_defined_restrictions partition-wide-restrictions}@anchor{1b8}
12257@section Partition-Wide Restrictions
12258
12259
12260There are two separate lists of restriction identifiers. The first
12261set requires consistency throughout a partition (in other words, if the
12262restriction identifier is used for any compilation unit in the partition,
12263then all compilation units in the partition must obey the restriction).
12264
12265@menu
12266* Immediate_Reclamation::
12267* Max_Asynchronous_Select_Nesting::
12268* Max_Entry_Queue_Length::
12269* Max_Protected_Entries::
12270* Max_Select_Alternatives::
12271* Max_Storage_At_Blocking::
12272* Max_Task_Entries::
12273* Max_Tasks::
12274* No_Abort_Statements::
12275* No_Access_Parameter_Allocators::
12276* No_Access_Subprograms::
12277* No_Allocators::
12278* No_Anonymous_Allocators::
12279* No_Asynchronous_Control::
12280* No_Calendar::
12281* No_Coextensions::
12282* No_Default_Initialization::
12283* No_Delay::
12284* No_Dependence::
12285* No_Direct_Boolean_Operators::
12286* No_Dispatch::
12287* No_Dispatching_Calls::
12288* No_Dynamic_Attachment::
12289* No_Dynamic_Priorities::
12290* No_Entry_Calls_In_Elaboration_Code::
12291* No_Enumeration_Maps::
12292* No_Exception_Handlers::
12293* No_Exception_Propagation::
12294* No_Exception_Registration::
12295* No_Exceptions::
12296* No_Finalization::
12297* No_Fixed_Point::
12298* No_Floating_Point::
12299* No_Implicit_Conditionals::
12300* No_Implicit_Dynamic_Code::
12301* No_Implicit_Heap_Allocations::
12302* No_Implicit_Protected_Object_Allocations::
12303* No_Implicit_Task_Allocations::
12304* No_Initialize_Scalars::
12305* No_IO::
12306* No_Local_Allocators::
12307* No_Local_Protected_Objects::
12308* No_Local_Timing_Events::
12309* No_Long_Long_Integers::
12310* No_Multiple_Elaboration::
12311* No_Nested_Finalization::
12312* No_Protected_Type_Allocators::
12313* No_Protected_Types::
12314* No_Recursion::
12315* No_Reentrancy::
12316* No_Relative_Delay::
12317* No_Requeue_Statements::
12318* No_Secondary_Stack::
12319* No_Select_Statements::
12320* No_Specific_Termination_Handlers::
12321* No_Specification_of_Aspect::
12322* No_Standard_Allocators_After_Elaboration::
12323* No_Standard_Storage_Pools::
12324* No_Stream_Optimizations::
12325* No_Streams::
12326* No_Task_Allocators::
12327* No_Task_At_Interrupt_Priority::
12328* No_Task_Attributes_Package::
12329* No_Task_Hierarchy::
12330* No_Task_Termination::
12331* No_Tasking::
12332* No_Terminate_Alternatives::
12333* No_Unchecked_Access::
12334* No_Unchecked_Conversion::
12335* No_Unchecked_Deallocation::
12336* No_Use_Of_Entity::
12337* Pure_Barriers::
12338* Simple_Barriers::
12339* Static_Priorities::
12340* Static_Storage_Size::
12341
12342@end menu
12343
12344@node Immediate_Reclamation,Max_Asynchronous_Select_Nesting,,Partition-Wide Restrictions
12345@anchor{gnat_rm/standard_and_implementation_defined_restrictions immediate-reclamation}@anchor{1b9}
12346@subsection Immediate_Reclamation
12347
12348
12349@geindex Immediate_Reclamation
12350
12351[RM H.4] This restriction ensures that, except for storage occupied by
12352objects created by allocators and not deallocated via unchecked
12353deallocation, any storage reserved at run time for an object is
12354immediately reclaimed when the object no longer exists.
12355
12356@node Max_Asynchronous_Select_Nesting,Max_Entry_Queue_Length,Immediate_Reclamation,Partition-Wide Restrictions
12357@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-asynchronous-select-nesting}@anchor{1ba}
12358@subsection Max_Asynchronous_Select_Nesting
12359
12360
12361@geindex Max_Asynchronous_Select_Nesting
12362
12363[RM D.7] Specifies the maximum dynamic nesting level of asynchronous
12364selects. Violations of this restriction with a value of zero are
12365detected at compile time. Violations of this restriction with values
12366other than zero cause Storage_Error to be raised.
12367
12368@node Max_Entry_Queue_Length,Max_Protected_Entries,Max_Asynchronous_Select_Nesting,Partition-Wide Restrictions
12369@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-entry-queue-length}@anchor{1bb}
12370@subsection Max_Entry_Queue_Length
12371
12372
12373@geindex Max_Entry_Queue_Length
12374
12375[RM D.7] This restriction is a declaration that any protected entry compiled in
12376the scope of the restriction has at most the specified number of
12377tasks waiting on the entry at any one time, and so no queue is required.
12378Note that this restriction is checked at run time. Violation of this
12379restriction results in the raising of Program_Error exception at the point of
12380the call.
12381
12382@geindex Max_Entry_Queue_Depth
12383
12384The restriction @code{Max_Entry_Queue_Depth} is recognized as a
12385synonym for @code{Max_Entry_Queue_Length}. This is retained for historical
12386compatibility purposes (and a warning will be generated for its use if
12387warnings on obsolescent features are activated).
12388
12389@node Max_Protected_Entries,Max_Select_Alternatives,Max_Entry_Queue_Length,Partition-Wide Restrictions
12390@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-protected-entries}@anchor{1bc}
12391@subsection Max_Protected_Entries
12392
12393
12394@geindex Max_Protected_Entries
12395
12396[RM D.7] Specifies the maximum number of entries per protected type. The
12397bounds of every entry family of a protected unit shall be static, or shall be
12398defined by a discriminant of a subtype whose corresponding bound is static.
12399
12400@node Max_Select_Alternatives,Max_Storage_At_Blocking,Max_Protected_Entries,Partition-Wide Restrictions
12401@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-select-alternatives}@anchor{1bd}
12402@subsection Max_Select_Alternatives
12403
12404
12405@geindex Max_Select_Alternatives
12406
12407[RM D.7] Specifies the maximum number of alternatives in a selective accept.
12408
12409@node Max_Storage_At_Blocking,Max_Task_Entries,Max_Select_Alternatives,Partition-Wide Restrictions
12410@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-storage-at-blocking}@anchor{1be}
12411@subsection Max_Storage_At_Blocking
12412
12413
12414@geindex Max_Storage_At_Blocking
12415
12416[RM D.7] Specifies the maximum portion (in storage elements) of a task’s
12417Storage_Size that can be retained by a blocked task. A violation of this
12418restriction causes Storage_Error to be raised.
12419
12420@node Max_Task_Entries,Max_Tasks,Max_Storage_At_Blocking,Partition-Wide Restrictions
12421@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-task-entries}@anchor{1bf}
12422@subsection Max_Task_Entries
12423
12424
12425@geindex Max_Task_Entries
12426
12427[RM D.7] Specifies the maximum number of entries
12428per task.  The bounds of every entry family
12429of a task unit shall be static, or shall be
12430defined by a discriminant of a subtype whose
12431corresponding bound is static.
12432
12433@node Max_Tasks,No_Abort_Statements,Max_Task_Entries,Partition-Wide Restrictions
12434@anchor{gnat_rm/standard_and_implementation_defined_restrictions max-tasks}@anchor{1c0}
12435@subsection Max_Tasks
12436
12437
12438@geindex Max_Tasks
12439
12440[RM D.7] Specifies the maximum number of task that may be created, not
12441counting the creation of the environment task.  Violations of this
12442restriction with a value of zero are detected at compile
12443time. Violations of this restriction with values other than zero cause
12444Storage_Error to be raised.
12445
12446@node No_Abort_Statements,No_Access_Parameter_Allocators,Max_Tasks,Partition-Wide Restrictions
12447@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-abort-statements}@anchor{1c1}
12448@subsection No_Abort_Statements
12449
12450
12451@geindex No_Abort_Statements
12452
12453[RM D.7] There are no abort_statements, and there are
12454no calls to Task_Identification.Abort_Task.
12455
12456@node No_Access_Parameter_Allocators,No_Access_Subprograms,No_Abort_Statements,Partition-Wide Restrictions
12457@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-access-parameter-allocators}@anchor{1c2}
12458@subsection No_Access_Parameter_Allocators
12459
12460
12461@geindex No_Access_Parameter_Allocators
12462
12463[RM H.4] This restriction ensures at compile time that there are no
12464occurrences of an allocator as the actual parameter to an access
12465parameter.
12466
12467@node No_Access_Subprograms,No_Allocators,No_Access_Parameter_Allocators,Partition-Wide Restrictions
12468@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-access-subprograms}@anchor{1c3}
12469@subsection No_Access_Subprograms
12470
12471
12472@geindex No_Access_Subprograms
12473
12474[RM H.4] This restriction ensures at compile time that there are no
12475declarations of access-to-subprogram types.
12476
12477@node No_Allocators,No_Anonymous_Allocators,No_Access_Subprograms,Partition-Wide Restrictions
12478@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-allocators}@anchor{1c4}
12479@subsection No_Allocators
12480
12481
12482@geindex No_Allocators
12483
12484[RM H.4] This restriction ensures at compile time that there are no
12485occurrences of an allocator.
12486
12487@node No_Anonymous_Allocators,No_Asynchronous_Control,No_Allocators,Partition-Wide Restrictions
12488@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-anonymous-allocators}@anchor{1c5}
12489@subsection No_Anonymous_Allocators
12490
12491
12492@geindex No_Anonymous_Allocators
12493
12494[RM H.4] This restriction ensures at compile time that there are no
12495occurrences of an allocator of anonymous access type.
12496
12497@node No_Asynchronous_Control,No_Calendar,No_Anonymous_Allocators,Partition-Wide Restrictions
12498@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-asynchronous-control}@anchor{1c6}
12499@subsection No_Asynchronous_Control
12500
12501
12502@geindex No_Asynchronous_Control
12503
12504[RM J.13] This restriction ensures at compile time that there are no semantic
12505dependences on the predefined package Asynchronous_Task_Control.
12506
12507@node No_Calendar,No_Coextensions,No_Asynchronous_Control,Partition-Wide Restrictions
12508@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-calendar}@anchor{1c7}
12509@subsection No_Calendar
12510
12511
12512@geindex No_Calendar
12513
12514[GNAT] This restriction ensures at compile time that there are no semantic
12515dependences on package Calendar.
12516
12517@node No_Coextensions,No_Default_Initialization,No_Calendar,Partition-Wide Restrictions
12518@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-coextensions}@anchor{1c8}
12519@subsection No_Coextensions
12520
12521
12522@geindex No_Coextensions
12523
12524[RM H.4] This restriction ensures at compile time that there are no
12525coextensions. See 3.10.2.
12526
12527@node No_Default_Initialization,No_Delay,No_Coextensions,Partition-Wide Restrictions
12528@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-default-initialization}@anchor{1c9}
12529@subsection No_Default_Initialization
12530
12531
12532@geindex No_Default_Initialization
12533
12534[GNAT] This restriction prohibits any instance of default initialization
12535of variables.  The binder implements a consistency rule which prevents
12536any unit compiled without the restriction from with’ing a unit with the
12537restriction (this allows the generation of initialization procedures to
12538be skipped, since you can be sure that no call is ever generated to an
12539initialization procedure in a unit with the restriction active). If used
12540in conjunction with Initialize_Scalars or Normalize_Scalars, the effect
12541is to prohibit all cases of variables declared without a specific
12542initializer (including the case of OUT scalar parameters).
12543
12544@node No_Delay,No_Dependence,No_Default_Initialization,Partition-Wide Restrictions
12545@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-delay}@anchor{1ca}
12546@subsection No_Delay
12547
12548
12549@geindex No_Delay
12550
12551[RM H.4] This restriction ensures at compile time that there are no
12552delay statements and no semantic dependences on package Calendar.
12553
12554@node No_Dependence,No_Direct_Boolean_Operators,No_Delay,Partition-Wide Restrictions
12555@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dependence}@anchor{1cb}
12556@subsection No_Dependence
12557
12558
12559@geindex No_Dependence
12560
12561[RM 13.12.1] This restriction ensures at compile time that there are no
12562dependences on a library unit.
12563
12564@node No_Direct_Boolean_Operators,No_Dispatch,No_Dependence,Partition-Wide Restrictions
12565@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-direct-boolean-operators}@anchor{1cc}
12566@subsection No_Direct_Boolean_Operators
12567
12568
12569@geindex No_Direct_Boolean_Operators
12570
12571[GNAT] This restriction ensures that no logical operators (and/or/xor)
12572are used on operands of type Boolean (or any type derived from Boolean).
12573This is intended for use in safety critical programs where the certification
12574protocol requires the use of short-circuit (and then, or else) forms for all
12575composite boolean operations.
12576
12577@node No_Dispatch,No_Dispatching_Calls,No_Direct_Boolean_Operators,Partition-Wide Restrictions
12578@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dispatch}@anchor{1cd}
12579@subsection No_Dispatch
12580
12581
12582@geindex No_Dispatch
12583
12584[RM H.4] This restriction ensures at compile time that there are no
12585occurrences of @code{T'Class}, for any (tagged) subtype @code{T}.
12586
12587@node No_Dispatching_Calls,No_Dynamic_Attachment,No_Dispatch,Partition-Wide Restrictions
12588@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dispatching-calls}@anchor{1ce}
12589@subsection No_Dispatching_Calls
12590
12591
12592@geindex No_Dispatching_Calls
12593
12594[GNAT] This restriction ensures at compile time that the code generated by the
12595compiler involves no dispatching calls. The use of this restriction allows the
12596safe use of record extensions, classwide membership tests and other classwide
12597features not involving implicit dispatching. This restriction ensures that
12598the code contains no indirect calls through a dispatching mechanism. Note that
12599this includes internally-generated calls created by the compiler, for example
12600in the implementation of class-wide objects assignments. The
12601membership test is allowed in the presence of this restriction, because its
12602implementation requires no dispatching.
12603This restriction is comparable to the official Ada restriction
12604@code{No_Dispatch} except that it is a bit less restrictive in that it allows
12605all classwide constructs that do not imply dispatching.
12606The following example indicates constructs that violate this restriction.
12607
12608@example
12609package Pkg is
12610  type T is tagged record
12611    Data : Natural;
12612  end record;
12613  procedure P (X : T);
12614
12615  type DT is new T with record
12616    More_Data : Natural;
12617  end record;
12618  procedure Q (X : DT);
12619end Pkg;
12620
12621with Pkg; use Pkg;
12622procedure Example is
12623  procedure Test (O : T'Class) is
12624    N : Natural := O'Size; --  Error: Dispatching call
12625    C : T'Class := O;      --  Error: implicit Dispatching Call
12626  begin
12627    if O in DT'Class then  --  OK   : Membership test
12628       Q (DT (O));         --  OK   : Type conversion plus direct call
12629    else
12630       P (O);              --  Error: Dispatching call
12631    end if;
12632  end Test;
12633
12634  Obj : DT;
12635begin
12636  P (Obj);                 --  OK   : Direct call
12637  P (T (Obj));             --  OK   : Type conversion plus direct call
12638  P (T'Class (Obj));       --  Error: Dispatching call
12639
12640  Test (Obj);              --  OK   : Type conversion
12641
12642  if Obj in T'Class then   --  OK   : Membership test
12643     null;
12644  end if;
12645end Example;
12646@end example
12647
12648@node No_Dynamic_Attachment,No_Dynamic_Priorities,No_Dispatching_Calls,Partition-Wide Restrictions
12649@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dynamic-attachment}@anchor{1cf}
12650@subsection No_Dynamic_Attachment
12651
12652
12653@geindex No_Dynamic_Attachment
12654
12655[RM D.7] This restriction ensures that there is no call to any of the
12656operations defined in package Ada.Interrupts
12657(Is_Reserved, Is_Attached, Current_Handler, Attach_Handler, Exchange_Handler,
12658Detach_Handler, and Reference).
12659
12660@geindex No_Dynamic_Interrupts
12661
12662The restriction @code{No_Dynamic_Interrupts} is recognized as a
12663synonym for @code{No_Dynamic_Attachment}. This is retained for historical
12664compatibility purposes (and a warning will be generated for its use if
12665warnings on obsolescent features are activated).
12666
12667@node No_Dynamic_Priorities,No_Entry_Calls_In_Elaboration_Code,No_Dynamic_Attachment,Partition-Wide Restrictions
12668@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dynamic-priorities}@anchor{1d0}
12669@subsection No_Dynamic_Priorities
12670
12671
12672@geindex No_Dynamic_Priorities
12673
12674[RM D.7] There are no semantic dependencies on the package Dynamic_Priorities.
12675
12676@node No_Entry_Calls_In_Elaboration_Code,No_Enumeration_Maps,No_Dynamic_Priorities,Partition-Wide Restrictions
12677@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-entry-calls-in-elaboration-code}@anchor{1d1}
12678@subsection No_Entry_Calls_In_Elaboration_Code
12679
12680
12681@geindex No_Entry_Calls_In_Elaboration_Code
12682
12683[GNAT] This restriction ensures at compile time that no task or protected entry
12684calls are made during elaboration code.  As a result of the use of this
12685restriction, the compiler can assume that no code past an accept statement
12686in a task can be executed at elaboration time.
12687
12688@node No_Enumeration_Maps,No_Exception_Handlers,No_Entry_Calls_In_Elaboration_Code,Partition-Wide Restrictions
12689@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-enumeration-maps}@anchor{1d2}
12690@subsection No_Enumeration_Maps
12691
12692
12693@geindex No_Enumeration_Maps
12694
12695[GNAT] This restriction ensures at compile time that no operations requiring
12696enumeration maps are used (that is Image and Value attributes applied
12697to enumeration types).
12698
12699@node No_Exception_Handlers,No_Exception_Propagation,No_Enumeration_Maps,Partition-Wide Restrictions
12700@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-exception-handlers}@anchor{1d3}
12701@subsection No_Exception_Handlers
12702
12703
12704@geindex No_Exception_Handlers
12705
12706[GNAT] This restriction ensures at compile time that there are no explicit
12707exception handlers. It also indicates that no exception propagation will
12708be provided. In this mode, exceptions may be raised but will result in
12709an immediate call to the last chance handler, a routine that the user
12710must define with the following profile:
12711
12712@example
12713procedure Last_Chance_Handler
12714  (Source_Location : System.Address; Line : Integer);
12715pragma Export (C, Last_Chance_Handler,
12716               "__gnat_last_chance_handler");
12717@end example
12718
12719The parameter is a C null-terminated string representing a message to be
12720associated with the exception (typically the source location of the raise
12721statement generated by the compiler). The Line parameter when nonzero
12722represents the line number in the source program where the raise occurs.
12723
12724@node No_Exception_Propagation,No_Exception_Registration,No_Exception_Handlers,Partition-Wide Restrictions
12725@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-exception-propagation}@anchor{1d4}
12726@subsection No_Exception_Propagation
12727
12728
12729@geindex No_Exception_Propagation
12730
12731[GNAT] This restriction guarantees that exceptions are never propagated
12732to an outer subprogram scope. The only case in which an exception may
12733be raised is when the handler is statically in the same subprogram, so
12734that the effect of a raise is essentially like a goto statement. Any
12735other raise statement (implicit or explicit) will be considered
12736unhandled. Exception handlers are allowed, but may not contain an
12737exception occurrence identifier (exception choice). In addition, use of
12738the package GNAT.Current_Exception is not permitted, and reraise
12739statements (raise with no operand) are not permitted.
12740
12741@node No_Exception_Registration,No_Exceptions,No_Exception_Propagation,Partition-Wide Restrictions
12742@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-exception-registration}@anchor{1d5}
12743@subsection No_Exception_Registration
12744
12745
12746@geindex No_Exception_Registration
12747
12748[GNAT] This restriction ensures at compile time that no stream operations for
12749types Exception_Id or Exception_Occurrence are used. This also makes it
12750impossible to pass exceptions to or from a partition with this restriction
12751in a distributed environment. If this restriction is active, the generated
12752code is simplified by omitting the otherwise-required global registration
12753of exceptions when they are declared.
12754
12755@node No_Exceptions,No_Finalization,No_Exception_Registration,Partition-Wide Restrictions
12756@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-exceptions}@anchor{1d6}
12757@subsection No_Exceptions
12758
12759
12760@geindex No_Exceptions
12761
12762[RM H.4] This restriction ensures at compile time that there are no
12763raise statements and no exception handlers and also suppresses the
12764generation of language-defined run-time checks.
12765
12766@node No_Finalization,No_Fixed_Point,No_Exceptions,Partition-Wide Restrictions
12767@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-finalization}@anchor{1d7}
12768@subsection No_Finalization
12769
12770
12771@geindex No_Finalization
12772
12773[GNAT] This restriction disables the language features described in
12774chapter 7.6 of the Ada 2005 RM as well as all form of code generation
12775performed by the compiler to support these features. The following types
12776are no longer considered controlled when this restriction is in effect:
12777
12778
12779@itemize *
12780
12781@item
12782@code{Ada.Finalization.Controlled}
12783
12784@item
12785@code{Ada.Finalization.Limited_Controlled}
12786
12787@item
12788Derivations from @code{Controlled} or @code{Limited_Controlled}
12789
12790@item
12791Class-wide types
12792
12793@item
12794Protected types
12795
12796@item
12797Task types
12798
12799@item
12800Array and record types with controlled components
12801@end itemize
12802
12803The compiler no longer generates code to initialize, finalize or adjust an
12804object or a nested component, either declared on the stack or on the heap. The
12805deallocation of a controlled object no longer finalizes its contents.
12806
12807@node No_Fixed_Point,No_Floating_Point,No_Finalization,Partition-Wide Restrictions
12808@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-fixed-point}@anchor{1d8}
12809@subsection No_Fixed_Point
12810
12811
12812@geindex No_Fixed_Point
12813
12814[RM H.4] This restriction ensures at compile time that there are no
12815occurrences of fixed point types and operations.
12816
12817@node No_Floating_Point,No_Implicit_Conditionals,No_Fixed_Point,Partition-Wide Restrictions
12818@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-floating-point}@anchor{1d9}
12819@subsection No_Floating_Point
12820
12821
12822@geindex No_Floating_Point
12823
12824[RM H.4] This restriction ensures at compile time that there are no
12825occurrences of floating point types and operations.
12826
12827@node No_Implicit_Conditionals,No_Implicit_Dynamic_Code,No_Floating_Point,Partition-Wide Restrictions
12828@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-conditionals}@anchor{1da}
12829@subsection No_Implicit_Conditionals
12830
12831
12832@geindex No_Implicit_Conditionals
12833
12834[GNAT] This restriction ensures that the generated code does not contain any
12835implicit conditionals, either by modifying the generated code where possible,
12836or by rejecting any construct that would otherwise generate an implicit
12837conditional. Note that this check does not include run time constraint
12838checks, which on some targets may generate implicit conditionals as
12839well. To control the latter, constraint checks can be suppressed in the
12840normal manner. Constructs generating implicit conditionals include comparisons
12841of composite objects and the Max/Min attributes.
12842
12843@node No_Implicit_Dynamic_Code,No_Implicit_Heap_Allocations,No_Implicit_Conditionals,Partition-Wide Restrictions
12844@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-dynamic-code}@anchor{1db}
12845@subsection No_Implicit_Dynamic_Code
12846
12847
12848@geindex No_Implicit_Dynamic_Code
12849
12850@geindex trampoline
12851
12852[GNAT] This restriction prevents the compiler from building ‘trampolines’.
12853This is a structure that is built on the stack and contains dynamic
12854code to be executed at run time. On some targets, a trampoline is
12855built for the following features: @code{Access},
12856@code{Unrestricted_Access}, or @code{Address} of a nested subprogram;
12857nested task bodies; primitive operations of nested tagged types.
12858Trampolines do not work on machines that prevent execution of stack
12859data. For example, on windows systems, enabling DEP (data execution
12860protection) will cause trampolines to raise an exception.
12861Trampolines are also quite slow at run time.
12862
12863On many targets, trampolines have been largely eliminated. Look at the
12864version of system.ads for your target — if it has
12865Always_Compatible_Rep equal to False, then trampolines are largely
12866eliminated. In particular, a trampoline is built for the following
12867features: @code{Address} of a nested subprogram;
12868@code{Access} or @code{Unrestricted_Access} of a nested subprogram,
12869but only if pragma Favor_Top_Level applies, or the access type has a
12870foreign-language convention; primitive operations of nested tagged
12871types.
12872
12873@node No_Implicit_Heap_Allocations,No_Implicit_Protected_Object_Allocations,No_Implicit_Dynamic_Code,Partition-Wide Restrictions
12874@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-heap-allocations}@anchor{1dc}
12875@subsection No_Implicit_Heap_Allocations
12876
12877
12878@geindex No_Implicit_Heap_Allocations
12879
12880[RM D.7] No constructs are allowed to cause implicit heap allocation.
12881
12882@node No_Implicit_Protected_Object_Allocations,No_Implicit_Task_Allocations,No_Implicit_Heap_Allocations,Partition-Wide Restrictions
12883@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-protected-object-allocations}@anchor{1dd}
12884@subsection No_Implicit_Protected_Object_Allocations
12885
12886
12887@geindex No_Implicit_Protected_Object_Allocations
12888
12889[GNAT] No constructs are allowed to cause implicit heap allocation of a
12890protected object.
12891
12892@node No_Implicit_Task_Allocations,No_Initialize_Scalars,No_Implicit_Protected_Object_Allocations,Partition-Wide Restrictions
12893@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-task-allocations}@anchor{1de}
12894@subsection No_Implicit_Task_Allocations
12895
12896
12897@geindex No_Implicit_Task_Allocations
12898
12899[GNAT] No constructs are allowed to cause implicit heap allocation of a task.
12900
12901@node No_Initialize_Scalars,No_IO,No_Implicit_Task_Allocations,Partition-Wide Restrictions
12902@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-initialize-scalars}@anchor{1df}
12903@subsection No_Initialize_Scalars
12904
12905
12906@geindex No_Initialize_Scalars
12907
12908[GNAT] This restriction ensures that no unit in the partition is compiled with
12909pragma Initialize_Scalars. This allows the generation of more efficient
12910code, and in particular eliminates dummy null initialization routines that
12911are otherwise generated for some record and array types.
12912
12913@node No_IO,No_Local_Allocators,No_Initialize_Scalars,Partition-Wide Restrictions
12914@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-io}@anchor{1e0}
12915@subsection No_IO
12916
12917
12918@geindex No_IO
12919
12920[RM H.4] This restriction ensures at compile time that there are no
12921dependences on any of the library units Sequential_IO, Direct_IO,
12922Text_IO, Wide_Text_IO, Wide_Wide_Text_IO, or Stream_IO.
12923
12924@node No_Local_Allocators,No_Local_Protected_Objects,No_IO,Partition-Wide Restrictions
12925@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-local-allocators}@anchor{1e1}
12926@subsection No_Local_Allocators
12927
12928
12929@geindex No_Local_Allocators
12930
12931[RM H.4] This restriction ensures at compile time that there are no
12932occurrences of an allocator in subprograms, generic subprograms, tasks,
12933and entry bodies.
12934
12935@node No_Local_Protected_Objects,No_Local_Timing_Events,No_Local_Allocators,Partition-Wide Restrictions
12936@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-local-protected-objects}@anchor{1e2}
12937@subsection No_Local_Protected_Objects
12938
12939
12940@geindex No_Local_Protected_Objects
12941
12942[RM D.7] This restriction ensures at compile time that protected objects are
12943only declared at the library level.
12944
12945@node No_Local_Timing_Events,No_Long_Long_Integers,No_Local_Protected_Objects,Partition-Wide Restrictions
12946@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-local-timing-events}@anchor{1e3}
12947@subsection No_Local_Timing_Events
12948
12949
12950@geindex No_Local_Timing_Events
12951
12952[RM D.7] All objects of type Ada.Real_Time.Timing_Events.Timing_Event are
12953declared at the library level.
12954
12955@node No_Long_Long_Integers,No_Multiple_Elaboration,No_Local_Timing_Events,Partition-Wide Restrictions
12956@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-long-long-integers}@anchor{1e4}
12957@subsection No_Long_Long_Integers
12958
12959
12960@geindex No_Long_Long_Integers
12961
12962[GNAT] This partition-wide restriction forbids any explicit reference to
12963type Standard.Long_Long_Integer, and also forbids declaring range types whose
12964implicit base type is Long_Long_Integer, and modular types whose size exceeds
12965Long_Integer’Size.
12966
12967@node No_Multiple_Elaboration,No_Nested_Finalization,No_Long_Long_Integers,Partition-Wide Restrictions
12968@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-multiple-elaboration}@anchor{1e5}
12969@subsection No_Multiple_Elaboration
12970
12971
12972@geindex No_Multiple_Elaboration
12973
12974[GNAT] When this restriction is active and the static elaboration model is
12975used, and -fpreserve-control-flow is not used, the compiler is allowed to
12976suppress the elaboration counter normally associated with the unit, even if
12977the unit has elaboration code. This counter is typically used to check for
12978access before elaboration and to control multiple elaboration attempts. If the
12979restriction is used, then the situations in which multiple elaboration is
12980possible, including non-Ada main programs and Stand Alone libraries, are not
12981permitted and will be diagnosed by the binder.
12982
12983@node No_Nested_Finalization,No_Protected_Type_Allocators,No_Multiple_Elaboration,Partition-Wide Restrictions
12984@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-nested-finalization}@anchor{1e6}
12985@subsection No_Nested_Finalization
12986
12987
12988@geindex No_Nested_Finalization
12989
12990[RM D.7] All objects requiring finalization are declared at the library level.
12991
12992@node No_Protected_Type_Allocators,No_Protected_Types,No_Nested_Finalization,Partition-Wide Restrictions
12993@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-protected-type-allocators}@anchor{1e7}
12994@subsection No_Protected_Type_Allocators
12995
12996
12997@geindex No_Protected_Type_Allocators
12998
12999[RM D.7] This restriction ensures at compile time that there are no allocator
13000expressions that attempt to allocate protected objects.
13001
13002@node No_Protected_Types,No_Recursion,No_Protected_Type_Allocators,Partition-Wide Restrictions
13003@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-protected-types}@anchor{1e8}
13004@subsection No_Protected_Types
13005
13006
13007@geindex No_Protected_Types
13008
13009[RM H.4] This restriction ensures at compile time that there are no
13010declarations of protected types or protected objects.
13011
13012@node No_Recursion,No_Reentrancy,No_Protected_Types,Partition-Wide Restrictions
13013@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-recursion}@anchor{1e9}
13014@subsection No_Recursion
13015
13016
13017@geindex No_Recursion
13018
13019[RM H.4] A program execution is erroneous if a subprogram is invoked as
13020part of its execution.
13021
13022@node No_Reentrancy,No_Relative_Delay,No_Recursion,Partition-Wide Restrictions
13023@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-reentrancy}@anchor{1ea}
13024@subsection No_Reentrancy
13025
13026
13027@geindex No_Reentrancy
13028
13029[RM H.4] A program execution is erroneous if a subprogram is executed by
13030two tasks at the same time.
13031
13032@node No_Relative_Delay,No_Requeue_Statements,No_Reentrancy,Partition-Wide Restrictions
13033@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-relative-delay}@anchor{1eb}
13034@subsection No_Relative_Delay
13035
13036
13037@geindex No_Relative_Delay
13038
13039[RM D.7] This restriction ensures at compile time that there are no delay
13040relative statements and prevents expressions such as @code{delay 1.23;} from
13041appearing in source code.
13042
13043@node No_Requeue_Statements,No_Secondary_Stack,No_Relative_Delay,Partition-Wide Restrictions
13044@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-requeue-statements}@anchor{1ec}
13045@subsection No_Requeue_Statements
13046
13047
13048@geindex No_Requeue_Statements
13049
13050[RM D.7] This restriction ensures at compile time that no requeue statements
13051are permitted and prevents keyword @code{requeue} from being used in source
13052code.
13053
13054@geindex No_Requeue
13055
13056The restriction @code{No_Requeue} is recognized as a
13057synonym for @code{No_Requeue_Statements}. This is retained for historical
13058compatibility purposes (and a warning will be generated for its use if
13059warnings on oNobsolescent features are activated).
13060
13061@node No_Secondary_Stack,No_Select_Statements,No_Requeue_Statements,Partition-Wide Restrictions
13062@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-secondary-stack}@anchor{1ed}
13063@subsection No_Secondary_Stack
13064
13065
13066@geindex No_Secondary_Stack
13067
13068[GNAT] This restriction ensures at compile time that the generated code
13069does not contain any reference to the secondary stack.  The secondary
13070stack is used to implement functions returning unconstrained objects
13071(arrays or records) on some targets. Suppresses the allocation of
13072secondary stacks for tasks (excluding the environment task) at run time.
13073
13074@node No_Select_Statements,No_Specific_Termination_Handlers,No_Secondary_Stack,Partition-Wide Restrictions
13075@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-select-statements}@anchor{1ee}
13076@subsection No_Select_Statements
13077
13078
13079@geindex No_Select_Statements
13080
13081[RM D.7] This restriction ensures at compile time no select statements of any
13082kind are permitted, that is the keyword @code{select} may not appear.
13083
13084@node No_Specific_Termination_Handlers,No_Specification_of_Aspect,No_Select_Statements,Partition-Wide Restrictions
13085@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-specific-termination-handlers}@anchor{1ef}
13086@subsection No_Specific_Termination_Handlers
13087
13088
13089@geindex No_Specific_Termination_Handlers
13090
13091[RM D.7] There are no calls to Ada.Task_Termination.Set_Specific_Handler
13092or to Ada.Task_Termination.Specific_Handler.
13093
13094@node No_Specification_of_Aspect,No_Standard_Allocators_After_Elaboration,No_Specific_Termination_Handlers,Partition-Wide Restrictions
13095@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-specification-of-aspect}@anchor{1f0}
13096@subsection No_Specification_of_Aspect
13097
13098
13099@geindex No_Specification_of_Aspect
13100
13101[RM 13.12.1] This restriction checks at compile time that no aspect
13102specification, attribute definition clause, or pragma is given for a
13103given aspect.
13104
13105@node No_Standard_Allocators_After_Elaboration,No_Standard_Storage_Pools,No_Specification_of_Aspect,Partition-Wide Restrictions
13106@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-standard-allocators-after-elaboration}@anchor{1f1}
13107@subsection No_Standard_Allocators_After_Elaboration
13108
13109
13110@geindex No_Standard_Allocators_After_Elaboration
13111
13112[RM D.7] Specifies that an allocator using a standard storage pool
13113should never be evaluated at run time after the elaboration of the
13114library items of the partition has completed. Otherwise, Storage_Error
13115is raised.
13116
13117@node No_Standard_Storage_Pools,No_Stream_Optimizations,No_Standard_Allocators_After_Elaboration,Partition-Wide Restrictions
13118@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-standard-storage-pools}@anchor{1f2}
13119@subsection No_Standard_Storage_Pools
13120
13121
13122@geindex No_Standard_Storage_Pools
13123
13124[GNAT] This restriction ensures at compile time that no access types
13125use the standard default storage pool.  Any access type declared must
13126have an explicit Storage_Pool attribute defined specifying a
13127user-defined storage pool.
13128
13129@node No_Stream_Optimizations,No_Streams,No_Standard_Storage_Pools,Partition-Wide Restrictions
13130@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-stream-optimizations}@anchor{1f3}
13131@subsection No_Stream_Optimizations
13132
13133
13134@geindex No_Stream_Optimizations
13135
13136[GNAT] This restriction affects the performance of stream operations on types
13137@code{String}, @code{Wide_String} and @code{Wide_Wide_String}. By default, the
13138compiler uses block reads and writes when manipulating @code{String} objects
13139due to their superior performance. When this restriction is in effect, the
13140compiler performs all IO operations on a per-character basis.
13141
13142@node No_Streams,No_Task_Allocators,No_Stream_Optimizations,Partition-Wide Restrictions
13143@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-streams}@anchor{1f4}
13144@subsection No_Streams
13145
13146
13147@geindex No_Streams
13148
13149[GNAT] This restriction ensures at compile/bind time that there are no
13150stream objects created and no use of stream attributes.
13151This restriction does not forbid dependences on the package
13152@code{Ada.Streams}. So it is permissible to with
13153@code{Ada.Streams} (or another package that does so itself)
13154as long as no actual stream objects are created and no
13155stream attributes are used.
13156
13157Note that the use of restriction allows optimization of tagged types,
13158since they do not need to worry about dispatching stream operations.
13159To take maximum advantage of this space-saving optimization, any
13160unit declaring a tagged type should be compiled with the restriction,
13161though this is not required.
13162
13163@node No_Task_Allocators,No_Task_At_Interrupt_Priority,No_Streams,Partition-Wide Restrictions
13164@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-allocators}@anchor{1f5}
13165@subsection No_Task_Allocators
13166
13167
13168@geindex No_Task_Allocators
13169
13170[RM D.7] There are no allocators for task types
13171or types containing task subcomponents.
13172
13173@node No_Task_At_Interrupt_Priority,No_Task_Attributes_Package,No_Task_Allocators,Partition-Wide Restrictions
13174@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-at-interrupt-priority}@anchor{1f6}
13175@subsection No_Task_At_Interrupt_Priority
13176
13177
13178@geindex No_Task_At_Interrupt_Priority
13179
13180[GNAT] This restriction ensures at compile time that there is no
13181Interrupt_Priority aspect or pragma for a task or a task type. As
13182a consequence, the tasks are always created with a priority below
13183that an interrupt priority.
13184
13185@node No_Task_Attributes_Package,No_Task_Hierarchy,No_Task_At_Interrupt_Priority,Partition-Wide Restrictions
13186@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-attributes-package}@anchor{1f7}
13187@subsection No_Task_Attributes_Package
13188
13189
13190@geindex No_Task_Attributes_Package
13191
13192[GNAT] This restriction ensures at compile time that there are no implicit or
13193explicit dependencies on the package @code{Ada.Task_Attributes}.
13194
13195@geindex No_Task_Attributes
13196
13197The restriction @code{No_Task_Attributes} is recognized as a synonym
13198for @code{No_Task_Attributes_Package}. This is retained for historical
13199compatibility purposes (and a warning will be generated for its use if
13200warnings on obsolescent features are activated).
13201
13202@node No_Task_Hierarchy,No_Task_Termination,No_Task_Attributes_Package,Partition-Wide Restrictions
13203@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-hierarchy}@anchor{1f8}
13204@subsection No_Task_Hierarchy
13205
13206
13207@geindex No_Task_Hierarchy
13208
13209[RM D.7] All (non-environment) tasks depend
13210directly on the environment task of the partition.
13211
13212@node No_Task_Termination,No_Tasking,No_Task_Hierarchy,Partition-Wide Restrictions
13213@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-termination}@anchor{1f9}
13214@subsection No_Task_Termination
13215
13216
13217@geindex No_Task_Termination
13218
13219[RM D.7] Tasks that terminate are erroneous.
13220
13221@node No_Tasking,No_Terminate_Alternatives,No_Task_Termination,Partition-Wide Restrictions
13222@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-tasking}@anchor{1fa}
13223@subsection No_Tasking
13224
13225
13226@geindex No_Tasking
13227
13228[GNAT] This restriction prevents the declaration of tasks or task types
13229throughout the partition.  It is similar in effect to the use of
13230@code{Max_Tasks => 0} except that violations are caught at compile time
13231and cause an error message to be output either by the compiler or
13232binder.
13233
13234@node No_Terminate_Alternatives,No_Unchecked_Access,No_Tasking,Partition-Wide Restrictions
13235@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-terminate-alternatives}@anchor{1fb}
13236@subsection No_Terminate_Alternatives
13237
13238
13239@geindex No_Terminate_Alternatives
13240
13241[RM D.7] There are no selective accepts with terminate alternatives.
13242
13243@node No_Unchecked_Access,No_Unchecked_Conversion,No_Terminate_Alternatives,Partition-Wide Restrictions
13244@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-unchecked-access}@anchor{1fc}
13245@subsection No_Unchecked_Access
13246
13247
13248@geindex No_Unchecked_Access
13249
13250[RM H.4] This restriction ensures at compile time that there are no
13251occurrences of the Unchecked_Access attribute.
13252
13253@node No_Unchecked_Conversion,No_Unchecked_Deallocation,No_Unchecked_Access,Partition-Wide Restrictions
13254@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-unchecked-conversion}@anchor{1fd}
13255@subsection No_Unchecked_Conversion
13256
13257
13258@geindex No_Unchecked_Conversion
13259
13260[RM J.13] This restriction ensures at compile time that there are no semantic
13261dependences on the predefined generic function Unchecked_Conversion.
13262
13263@node No_Unchecked_Deallocation,No_Use_Of_Entity,No_Unchecked_Conversion,Partition-Wide Restrictions
13264@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-unchecked-deallocation}@anchor{1fe}
13265@subsection No_Unchecked_Deallocation
13266
13267
13268@geindex No_Unchecked_Deallocation
13269
13270[RM J.13] This restriction ensures at compile time that there are no semantic
13271dependences on the predefined generic procedure Unchecked_Deallocation.
13272
13273@node No_Use_Of_Entity,Pure_Barriers,No_Unchecked_Deallocation,Partition-Wide Restrictions
13274@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-use-of-entity}@anchor{1ff}
13275@subsection No_Use_Of_Entity
13276
13277
13278@geindex No_Use_Of_Entity
13279
13280[GNAT] This restriction ensures at compile time that there are no references
13281to the entity given in the form
13282
13283@example
13284No_Use_Of_Entity => Name
13285@end example
13286
13287where @code{Name} is the fully qualified entity, for example
13288
13289@example
13290No_Use_Of_Entity => Ada.Text_IO.Put_Line
13291@end example
13292
13293@node Pure_Barriers,Simple_Barriers,No_Use_Of_Entity,Partition-Wide Restrictions
13294@anchor{gnat_rm/standard_and_implementation_defined_restrictions pure-barriers}@anchor{200}
13295@subsection Pure_Barriers
13296
13297
13298@geindex Pure_Barriers
13299
13300[GNAT] This restriction ensures at compile time that protected entry
13301barriers are restricted to:
13302
13303
13304@itemize *
13305
13306@item
13307components of the protected object (excluding selection from dereferences),
13308
13309@item
13310constant declarations,
13311
13312@item
13313named numbers,
13314
13315@item
13316enumeration literals,
13317
13318@item
13319integer literals,
13320
13321@item
13322real literals,
13323
13324@item
13325character literals,
13326
13327@item
13328implicitly defined comparison operators,
13329
13330@item
13331uses of the Standard.”not” operator,
13332
13333@item
13334short-circuit operator,
13335
13336@item
13337the Count attribute
13338@end itemize
13339
13340This restriction is a relaxation of the Simple_Barriers restriction,
13341but still ensures absence of side effects, exceptions, and recursion
13342during the evaluation of the barriers.
13343
13344@node Simple_Barriers,Static_Priorities,Pure_Barriers,Partition-Wide Restrictions
13345@anchor{gnat_rm/standard_and_implementation_defined_restrictions simple-barriers}@anchor{201}
13346@subsection Simple_Barriers
13347
13348
13349@geindex Simple_Barriers
13350
13351[RM D.7] This restriction ensures at compile time that barriers in entry
13352declarations for protected types are restricted to either static boolean
13353expressions or references to simple boolean variables defined in the private
13354part of the protected type.  No other form of entry barriers is permitted.
13355
13356@geindex Boolean_Entry_Barriers
13357
13358The restriction @code{Boolean_Entry_Barriers} is recognized as a
13359synonym for @code{Simple_Barriers}. This is retained for historical
13360compatibility purposes (and a warning will be generated for its use if
13361warnings on obsolescent features are activated).
13362
13363@node Static_Priorities,Static_Storage_Size,Simple_Barriers,Partition-Wide Restrictions
13364@anchor{gnat_rm/standard_and_implementation_defined_restrictions static-priorities}@anchor{202}
13365@subsection Static_Priorities
13366
13367
13368@geindex Static_Priorities
13369
13370[GNAT] This restriction ensures at compile time that all priority expressions
13371are static, and that there are no dependences on the package
13372@code{Ada.Dynamic_Priorities}.
13373
13374@node Static_Storage_Size,,Static_Priorities,Partition-Wide Restrictions
13375@anchor{gnat_rm/standard_and_implementation_defined_restrictions static-storage-size}@anchor{203}
13376@subsection Static_Storage_Size
13377
13378
13379@geindex Static_Storage_Size
13380
13381[GNAT] This restriction ensures at compile time that any expression appearing
13382in a Storage_Size pragma or attribute definition clause is static.
13383
13384@node Program Unit Level Restrictions,,Partition-Wide Restrictions,Standard and Implementation Defined Restrictions
13385@anchor{gnat_rm/standard_and_implementation_defined_restrictions id3}@anchor{204}@anchor{gnat_rm/standard_and_implementation_defined_restrictions program-unit-level-restrictions}@anchor{205}
13386@section Program Unit Level Restrictions
13387
13388
13389The second set of restriction identifiers
13390does not require partition-wide consistency.
13391The restriction may be enforced for a single
13392compilation unit without any effect on any of the
13393other compilation units in the partition.
13394
13395@menu
13396* No_Elaboration_Code::
13397* No_Dynamic_Accessibility_Checks::
13398* No_Dynamic_Sized_Objects::
13399* No_Entry_Queue::
13400* No_Implementation_Aspect_Specifications::
13401* No_Implementation_Attributes::
13402* No_Implementation_Identifiers::
13403* No_Implementation_Pragmas::
13404* No_Implementation_Restrictions::
13405* No_Implementation_Units::
13406* No_Implicit_Aliasing::
13407* No_Implicit_Loops::
13408* No_Obsolescent_Features::
13409* No_Wide_Characters::
13410* Static_Dispatch_Tables::
13411* SPARK_05::
13412
13413@end menu
13414
13415@node No_Elaboration_Code,No_Dynamic_Accessibility_Checks,,Program Unit Level Restrictions
13416@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-elaboration-code}@anchor{206}
13417@subsection No_Elaboration_Code
13418
13419
13420@geindex No_Elaboration_Code
13421
13422[GNAT] This restriction ensures at compile time that no elaboration code is
13423generated.  Note that this is not the same condition as is enforced
13424by pragma @code{Preelaborate}.  There are cases in which pragma
13425@code{Preelaborate} still permits code to be generated (e.g., code
13426to initialize a large array to all zeroes), and there are cases of units
13427which do not meet the requirements for pragma @code{Preelaborate},
13428but for which no elaboration code is generated.  Generally, it is
13429the case that preelaborable units will meet the restrictions, with
13430the exception of large aggregates initialized with an others_clause,
13431and exception declarations (which generate calls to a run-time
13432registry procedure).  This restriction is enforced on
13433a unit by unit basis, it need not be obeyed consistently
13434throughout a partition.
13435
13436In the case of aggregates with others, if the aggregate has a dynamic
13437size, there is no way to eliminate the elaboration code (such dynamic
13438bounds would be incompatible with @code{Preelaborate} in any case). If
13439the bounds are static, then use of this restriction actually modifies
13440the code choice of the compiler to avoid generating a loop, and instead
13441generate the aggregate statically if possible, no matter how many times
13442the data for the others clause must be repeatedly generated.
13443
13444It is not possible to precisely document
13445the constructs which are compatible with this restriction, since,
13446unlike most other restrictions, this is not a restriction on the
13447source code, but a restriction on the generated object code. For
13448example, if the source contains a declaration:
13449
13450@example
13451Val : constant Integer := X;
13452@end example
13453
13454where X is not a static constant, it may be possible, depending
13455on complex optimization circuitry, for the compiler to figure
13456out the value of X at compile time, in which case this initialization
13457can be done by the loader, and requires no initialization code. It
13458is not possible to document the precise conditions under which the
13459optimizer can figure this out.
13460
13461Note that this the implementation of this restriction requires full
13462code generation. If it is used in conjunction with “semantics only”
13463checking, then some cases of violations may be missed.
13464
13465When this restriction is active, we are not requesting control-flow
13466preservation with -fpreserve-control-flow, and the static elaboration model is
13467used, the compiler is allowed to suppress the elaboration counter normally
13468associated with the unit. This counter is typically used to check for access
13469before elaboration and to control multiple elaboration attempts.
13470
13471@node No_Dynamic_Accessibility_Checks,No_Dynamic_Sized_Objects,No_Elaboration_Code,Program Unit Level Restrictions
13472@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dynamic-accessibility-checks}@anchor{207}
13473@subsection No_Dynamic_Accessibility_Checks
13474
13475
13476@geindex No_Dynamic_Accessibility_Checks
13477
13478[GNAT] No dynamic accessibility checks are generated when this restriction is
13479in effect. Instead, dangling references are prevented via more conservative
13480compile-time checking. More specifically, existing compile-time checks are
13481enforced but with more conservative assumptions about the accessibility levels
13482of the relevant entities. These conservative assumptions eliminate the need for
13483dynamic accessibility checks.
13484
13485These new rules for computing (at compile-time) the accessibility level of an
13486anonymous access type T are as follows:
13487
13488
13489@itemize *
13490
13491@item
13492If T is a function result type then, from the caller’s perspective, its level
13493is that of the innermost master enclosing the function call. From the callee’s
13494perspective, the level of parameters and local variables of the callee is
13495statically deeper than the level of T.
13496
13497For any other accessibility level L such that the level of parameters and local
13498variables of the callee is statically deeper than L, the level of T (from the
13499callee’s perspective) is also statically deeper than L.
13500
13501@item
13502If T is the type of a formal parameter then, from the caller’s perspective,
13503its level is at least as deep as that of the type of the corresponding actual
13504parameter (whatever that actual parameter might be). From the callee’s
13505perspective, the level of parameters and local variables of the callee is
13506statically deeper than the level of T.
13507
13508@item
13509If T is the type of a discriminant then its level is that of the discriminated
13510type.
13511
13512@item
13513If T is the type of a stand-alone object then its level is the level of the
13514object.
13515
13516@item
13517In all other cases, the level of T is as defined by the existing rules of Ada.
13518@end itemize
13519
13520@node No_Dynamic_Sized_Objects,No_Entry_Queue,No_Dynamic_Accessibility_Checks,Program Unit Level Restrictions
13521@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dynamic-sized-objects}@anchor{208}
13522@subsection No_Dynamic_Sized_Objects
13523
13524
13525@geindex No_Dynamic_Sized_Objects
13526
13527[GNAT] This restriction disallows certain constructs that might lead to the
13528creation of dynamic-sized composite objects (or array or discriminated type).
13529An array subtype indication is illegal if the bounds are not static
13530or references to discriminants of an enclosing type.
13531A discriminated subtype indication is illegal if the type has
13532discriminant-dependent array components or a variant part, and the
13533discriminants are not static. In addition, array and record aggregates are
13534illegal in corresponding cases. Note that this restriction does not forbid
13535access discriminants. It is often a good idea to combine this restriction
13536with No_Secondary_Stack.
13537
13538@node No_Entry_Queue,No_Implementation_Aspect_Specifications,No_Dynamic_Sized_Objects,Program Unit Level Restrictions
13539@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-entry-queue}@anchor{209}
13540@subsection No_Entry_Queue
13541
13542
13543@geindex No_Entry_Queue
13544
13545[GNAT] This restriction is a declaration that any protected entry compiled in
13546the scope of the restriction has at most one task waiting on the entry
13547at any one time, and so no queue is required.  This restriction is not
13548checked at compile time.  A program execution is erroneous if an attempt
13549is made to queue a second task on such an entry.
13550
13551@node No_Implementation_Aspect_Specifications,No_Implementation_Attributes,No_Entry_Queue,Program Unit Level Restrictions
13552@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-aspect-specifications}@anchor{20a}
13553@subsection No_Implementation_Aspect_Specifications
13554
13555
13556@geindex No_Implementation_Aspect_Specifications
13557
13558[RM 13.12.1] This restriction checks at compile time that no
13559GNAT-defined aspects are present.  With this restriction, the only
13560aspects that can be used are those defined in the Ada Reference Manual.
13561
13562@node No_Implementation_Attributes,No_Implementation_Identifiers,No_Implementation_Aspect_Specifications,Program Unit Level Restrictions
13563@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-attributes}@anchor{20b}
13564@subsection No_Implementation_Attributes
13565
13566
13567@geindex No_Implementation_Attributes
13568
13569[RM 13.12.1] This restriction checks at compile time that no
13570GNAT-defined attributes are present.  With this restriction, the only
13571attributes that can be used are those defined in the Ada Reference
13572Manual.
13573
13574@node No_Implementation_Identifiers,No_Implementation_Pragmas,No_Implementation_Attributes,Program Unit Level Restrictions
13575@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-identifiers}@anchor{20c}
13576@subsection No_Implementation_Identifiers
13577
13578
13579@geindex No_Implementation_Identifiers
13580
13581[RM 13.12.1] This restriction checks at compile time that no
13582implementation-defined identifiers (marked with pragma Implementation_Defined)
13583occur within language-defined packages.
13584
13585@node No_Implementation_Pragmas,No_Implementation_Restrictions,No_Implementation_Identifiers,Program Unit Level Restrictions
13586@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-pragmas}@anchor{20d}
13587@subsection No_Implementation_Pragmas
13588
13589
13590@geindex No_Implementation_Pragmas
13591
13592[RM 13.12.1] This restriction checks at compile time that no
13593GNAT-defined pragmas are present.  With this restriction, the only
13594pragmas that can be used are those defined in the Ada Reference Manual.
13595
13596@node No_Implementation_Restrictions,No_Implementation_Units,No_Implementation_Pragmas,Program Unit Level Restrictions
13597@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-restrictions}@anchor{20e}
13598@subsection No_Implementation_Restrictions
13599
13600
13601@geindex No_Implementation_Restrictions
13602
13603[GNAT] This restriction checks at compile time that no GNAT-defined restriction
13604identifiers (other than @code{No_Implementation_Restrictions} itself)
13605are present.  With this restriction, the only other restriction identifiers
13606that can be used are those defined in the Ada Reference Manual.
13607
13608@node No_Implementation_Units,No_Implicit_Aliasing,No_Implementation_Restrictions,Program Unit Level Restrictions
13609@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-units}@anchor{20f}
13610@subsection No_Implementation_Units
13611
13612
13613@geindex No_Implementation_Units
13614
13615[RM 13.12.1] This restriction checks at compile time that there is no
13616mention in the context clause of any implementation-defined descendants
13617of packages Ada, Interfaces, or System.
13618
13619@node No_Implicit_Aliasing,No_Implicit_Loops,No_Implementation_Units,Program Unit Level Restrictions
13620@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-aliasing}@anchor{210}
13621@subsection No_Implicit_Aliasing
13622
13623
13624@geindex No_Implicit_Aliasing
13625
13626[GNAT] This restriction, which is not required to be partition-wide consistent,
13627requires an explicit aliased keyword for an object to which ‘Access,
13628‘Unchecked_Access, or ‘Address is applied, and forbids entirely the use of
13629the ‘Unrestricted_Access attribute for objects. Note: the reason that
13630Unrestricted_Access is forbidden is that it would require the prefix
13631to be aliased, and in such cases, it can always be replaced by
13632the standard attribute Unchecked_Access which is preferable.
13633
13634@node No_Implicit_Loops,No_Obsolescent_Features,No_Implicit_Aliasing,Program Unit Level Restrictions
13635@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-loops}@anchor{211}
13636@subsection No_Implicit_Loops
13637
13638
13639@geindex No_Implicit_Loops
13640
13641[GNAT] This restriction ensures that the generated code of the unit marked
13642with this restriction does not contain any implicit @code{for} loops, either by
13643modifying the generated code where possible, or by rejecting any construct
13644that would otherwise generate an implicit @code{for} loop. If this restriction is
13645active, it is possible to build large array aggregates with all static
13646components without generating an intermediate temporary, and without generating
13647a loop to initialize individual components. Otherwise, a loop is created for
13648arrays larger than about 5000 scalar components. Note that if this restriction
13649is set in the spec of a package, it will not apply to its body.
13650
13651@node No_Obsolescent_Features,No_Wide_Characters,No_Implicit_Loops,Program Unit Level Restrictions
13652@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-obsolescent-features}@anchor{212}
13653@subsection No_Obsolescent_Features
13654
13655
13656@geindex No_Obsolescent_Features
13657
13658[RM 13.12.1] This restriction checks at compile time that no obsolescent
13659features are used, as defined in Annex J of the Ada Reference Manual.
13660
13661@node No_Wide_Characters,Static_Dispatch_Tables,No_Obsolescent_Features,Program Unit Level Restrictions
13662@anchor{gnat_rm/standard_and_implementation_defined_restrictions no-wide-characters}@anchor{213}
13663@subsection No_Wide_Characters
13664
13665
13666@geindex No_Wide_Characters
13667
13668[GNAT] This restriction ensures at compile time that no uses of the types
13669@code{Wide_Character} or @code{Wide_String} or corresponding wide
13670wide types
13671appear, and that no wide or wide wide string or character literals
13672appear in the program (that is literals representing characters not in
13673type @code{Character}).
13674
13675@node Static_Dispatch_Tables,SPARK_05,No_Wide_Characters,Program Unit Level Restrictions
13676@anchor{gnat_rm/standard_and_implementation_defined_restrictions static-dispatch-tables}@anchor{214}
13677@subsection Static_Dispatch_Tables
13678
13679
13680@geindex Static_Dispatch_Tables
13681
13682[GNAT] This restriction checks at compile time that all the artifacts
13683associated with dispatch tables can be placed in read-only memory.
13684
13685@node SPARK_05,,Static_Dispatch_Tables,Program Unit Level Restrictions
13686@anchor{gnat_rm/standard_and_implementation_defined_restrictions spark-05}@anchor{215}
13687@subsection SPARK_05
13688
13689
13690@geindex SPARK_05
13691
13692[GNAT] This restriction no longer has any effect and is superseded by
13693SPARK 2014, whose restrictions are checked by the tool GNATprove. To check that
13694a codebase respects SPARK 2014 restrictions, mark the code with pragma or
13695aspect @code{SPARK_Mode}, and run the tool GNATprove at Stone assurance level, as
13696follows:
13697
13698@example
13699gnatprove -P project.gpr --mode=stone
13700@end example
13701
13702or equivalently:
13703
13704@example
13705gnatprove -P project.gpr --mode=check_all
13706@end example
13707
13708@node Implementation Advice,Implementation Defined Characteristics,Standard and Implementation Defined Restrictions,Top
13709@anchor{gnat_rm/implementation_advice doc}@anchor{216}@anchor{gnat_rm/implementation_advice id1}@anchor{217}@anchor{gnat_rm/implementation_advice implementation-advice}@anchor{a}
13710@chapter Implementation Advice
13711
13712
13713The main text of the Ada Reference Manual describes the required
13714behavior of all Ada compilers, and the GNAT compiler conforms to
13715these requirements.
13716
13717In addition, there are sections throughout the Ada Reference Manual headed
13718by the phrase ‘Implementation advice’.  These sections are not normative,
13719i.e., they do not specify requirements that all compilers must
13720follow.  Rather they provide advice on generally desirable behavior.
13721They are not requirements, because they describe behavior that cannot
13722be provided on all systems, or may be undesirable on some systems.
13723
13724As far as practical, GNAT follows the implementation advice in
13725the Ada Reference Manual.  Each such RM section corresponds to a section
13726in this chapter whose title specifies the
13727RM section number and paragraph number and the subject of
13728the advice.  The contents of each section consists of the RM text within
13729quotation marks,
13730followed by the GNAT interpretation of the advice.  Most often, this simply says
13731‘followed’, which means that GNAT follows the advice.  However, in a
13732number of cases, GNAT deliberately deviates from this advice, in which
13733case the text describes what GNAT does and why.
13734
13735@geindex Error detection
13736
13737@menu
13738* RM 1.1.3(20); Error Detection: RM 1 1 3 20 Error Detection.
13739* RM 1.1.3(31); Child Units: RM 1 1 3 31 Child Units.
13740* RM 1.1.5(12); Bounded Errors: RM 1 1 5 12 Bounded Errors.
13741* RM 2.8(16); Pragmas: RM 2 8 16 Pragmas.
13742* RM 2.8(17-19); Pragmas: RM 2 8 17-19 Pragmas.
13743* RM 3.5.2(5); Alternative Character Sets: RM 3 5 2 5 Alternative Character Sets.
13744* RM 3.5.4(28); Integer Types: RM 3 5 4 28 Integer Types.
13745* RM 3.5.4(29); Integer Types: RM 3 5 4 29 Integer Types.
13746* RM 3.5.5(8); Enumeration Values: RM 3 5 5 8 Enumeration Values.
13747* RM 3.5.7(17); Float Types: RM 3 5 7 17 Float Types.
13748* RM 3.6.2(11); Multidimensional Arrays: RM 3 6 2 11 Multidimensional Arrays.
13749* RM 9.6(30-31); Duration’Small: RM 9 6 30-31 Duration’Small.
13750* RM 10.2.1(12); Consistent Representation: RM 10 2 1 12 Consistent Representation.
13751* RM 11.4.1(19); Exception Information: RM 11 4 1 19 Exception Information.
13752* RM 11.5(28); Suppression of Checks: RM 11 5 28 Suppression of Checks.
13753* RM 13.1 (21-24); Representation Clauses: RM 13 1 21-24 Representation Clauses.
13754* RM 13.2(6-8); Packed Types: RM 13 2 6-8 Packed Types.
13755* RM 13.3(14-19); Address Clauses: RM 13 3 14-19 Address Clauses.
13756* RM 13.3(29-35); Alignment Clauses: RM 13 3 29-35 Alignment Clauses.
13757* RM 13.3(42-43); Size Clauses: RM 13 3 42-43 Size Clauses.
13758* RM 13.3(50-56); Size Clauses: RM 13 3 50-56 Size Clauses.
13759* RM 13.3(71-73); Component Size Clauses: RM 13 3 71-73 Component Size Clauses.
13760* RM 13.4(9-10); Enumeration Representation Clauses: RM 13 4 9-10 Enumeration Representation Clauses.
13761* RM 13.5.1(17-22); Record Representation Clauses: RM 13 5 1 17-22 Record Representation Clauses.
13762* RM 13.5.2(5); Storage Place Attributes: RM 13 5 2 5 Storage Place Attributes.
13763* RM 13.5.3(7-8); Bit Ordering: RM 13 5 3 7-8 Bit Ordering.
13764* RM 13.7(37); Address as Private: RM 13 7 37 Address as Private.
13765* RM 13.7.1(16); Address Operations: RM 13 7 1 16 Address Operations.
13766* RM 13.9(14-17); Unchecked Conversion: RM 13 9 14-17 Unchecked Conversion.
13767* RM 13.11(23-25); Implicit Heap Usage: RM 13 11 23-25 Implicit Heap Usage.
13768* RM 13.11.2(17); Unchecked Deallocation: RM 13 11 2 17 Unchecked Deallocation.
13769* RM 13.13.2(1.6); Stream Oriented Attributes: RM 13 13 2 1 6 Stream Oriented Attributes.
13770* RM A.1(52); Names of Predefined Numeric Types: RM A 1 52 Names of Predefined Numeric Types.
13771* RM A.3.2(49); Ada.Characters.Handling: RM A 3 2 49 Ada Characters Handling.
13772* RM A.4.4(106); Bounded-Length String Handling: RM A 4 4 106 Bounded-Length String Handling.
13773* RM A.5.2(46-47); Random Number Generation: RM A 5 2 46-47 Random Number Generation.
13774* RM A.10.7(23); Get_Immediate: RM A 10 7 23 Get_Immediate.
13775* RM A.18; Containers: RM A 18 Containers.
13776* RM B.1(39-41); Pragma Export: RM B 1 39-41 Pragma Export.
13777* RM B.2(12-13); Package Interfaces: RM B 2 12-13 Package Interfaces.
13778* RM B.3(63-71); Interfacing with C: RM B 3 63-71 Interfacing with C.
13779* RM B.4(95-98); Interfacing with COBOL: RM B 4 95-98 Interfacing with COBOL.
13780* RM B.5(22-26); Interfacing with Fortran: RM B 5 22-26 Interfacing with Fortran.
13781* RM C.1(3-5); Access to Machine Operations: RM C 1 3-5 Access to Machine Operations.
13782* RM C.1(10-16); Access to Machine Operations: RM C 1 10-16 Access to Machine Operations.
13783* RM C.3(28); Interrupt Support: RM C 3 28 Interrupt Support.
13784* RM C.3.1(20-21); Protected Procedure Handlers: RM C 3 1 20-21 Protected Procedure Handlers.
13785* RM C.3.2(25); Package Interrupts: RM C 3 2 25 Package Interrupts.
13786* RM C.4(14); Pre-elaboration Requirements: RM C 4 14 Pre-elaboration Requirements.
13787* RM C.5(8); Pragma Discard_Names: RM C 5 8 Pragma Discard_Names.
13788* RM C.7.2(30); The Package Task_Attributes: RM C 7 2 30 The Package Task_Attributes.
13789* RM D.3(17); Locking Policies: RM D 3 17 Locking Policies.
13790* RM D.4(16); Entry Queuing Policies: RM D 4 16 Entry Queuing Policies.
13791* RM D.6(9-10); Preemptive Abort: RM D 6 9-10 Preemptive Abort.
13792* RM D.7(21); Tasking Restrictions: RM D 7 21 Tasking Restrictions.
13793* RM D.8(47-49); Monotonic Time: RM D 8 47-49 Monotonic Time.
13794* RM E.5(28-29); Partition Communication Subsystem: RM E 5 28-29 Partition Communication Subsystem.
13795* RM F(7); COBOL Support: RM F 7 COBOL Support.
13796* RM F.1(2); Decimal Radix Support: RM F 1 2 Decimal Radix Support.
13797* RM G; Numerics: RM G Numerics.
13798* RM G.1.1(56-58); Complex Types: RM G 1 1 56-58 Complex Types.
13799* RM G.1.2(49); Complex Elementary Functions: RM G 1 2 49 Complex Elementary Functions.
13800* RM G.2.4(19); Accuracy Requirements: RM G 2 4 19 Accuracy Requirements.
13801* RM G.2.6(15); Complex Arithmetic Accuracy: RM G 2 6 15 Complex Arithmetic Accuracy.
13802* RM H.6(15/2); Pragma Partition_Elaboration_Policy: RM H 6 15/2 Pragma Partition_Elaboration_Policy.
13803
13804@end menu
13805
13806@node RM 1 1 3 20 Error Detection,RM 1 1 3 31 Child Units,,Implementation Advice
13807@anchor{gnat_rm/implementation_advice rm-1-1-3-20-error-detection}@anchor{218}
13808@section RM 1.1.3(20): Error Detection
13809
13810
13811@quotation
13812
13813“If an implementation detects the use of an unsupported Specialized Needs
13814Annex feature at run time, it should raise @code{Program_Error} if
13815feasible.”
13816@end quotation
13817
13818Not relevant.  All specialized needs annex features are either supported,
13819or diagnosed at compile time.
13820
13821@geindex Child Units
13822
13823@node RM 1 1 3 31 Child Units,RM 1 1 5 12 Bounded Errors,RM 1 1 3 20 Error Detection,Implementation Advice
13824@anchor{gnat_rm/implementation_advice rm-1-1-3-31-child-units}@anchor{219}
13825@section RM 1.1.3(31): Child Units
13826
13827
13828@quotation
13829
13830“If an implementation wishes to provide implementation-defined
13831extensions to the functionality of a language-defined library unit, it
13832should normally do so by adding children to the library unit.”
13833@end quotation
13834
13835Followed.
13836
13837@geindex Bounded errors
13838
13839@node RM 1 1 5 12 Bounded Errors,RM 2 8 16 Pragmas,RM 1 1 3 31 Child Units,Implementation Advice
13840@anchor{gnat_rm/implementation_advice rm-1-1-5-12-bounded-errors}@anchor{21a}
13841@section RM 1.1.5(12): Bounded Errors
13842
13843
13844@quotation
13845
13846“If an implementation detects a bounded error or erroneous
13847execution, it should raise @code{Program_Error}.”
13848@end quotation
13849
13850Followed in all cases in which the implementation detects a bounded
13851error or erroneous execution.  Not all such situations are detected at
13852runtime.
13853
13854@geindex Pragmas
13855
13856@node RM 2 8 16 Pragmas,RM 2 8 17-19 Pragmas,RM 1 1 5 12 Bounded Errors,Implementation Advice
13857@anchor{gnat_rm/implementation_advice id2}@anchor{21b}@anchor{gnat_rm/implementation_advice rm-2-8-16-pragmas}@anchor{21c}
13858@section RM 2.8(16): Pragmas
13859
13860
13861@quotation
13862
13863“Normally, implementation-defined pragmas should have no semantic effect
13864for error-free programs; that is, if the implementation-defined pragmas
13865are removed from a working program, the program should still be legal,
13866and should still have the same semantics.”
13867@end quotation
13868
13869The following implementation defined pragmas are exceptions to this
13870rule:
13871
13872
13873@multitable {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxx}
13874@headitem
13875
13876Pragma
13877
13878@tab
13879
13880Explanation
13881
13882@item
13883
13884@emph{Abort_Defer}
13885
13886@tab
13887
13888Affects semantics
13889
13890@item
13891
13892@emph{Ada_83}
13893
13894@tab
13895
13896Affects legality
13897
13898@item
13899
13900@emph{Assert}
13901
13902@tab
13903
13904Affects semantics
13905
13906@item
13907
13908@emph{CPP_Class}
13909
13910@tab
13911
13912Affects semantics
13913
13914@item
13915
13916@emph{CPP_Constructor}
13917
13918@tab
13919
13920Affects semantics
13921
13922@item
13923
13924@emph{Debug}
13925
13926@tab
13927
13928Affects semantics
13929
13930@item
13931
13932@emph{Interface_Name}
13933
13934@tab
13935
13936Affects semantics
13937
13938@item
13939
13940@emph{Machine_Attribute}
13941
13942@tab
13943
13944Affects semantics
13945
13946@item
13947
13948@emph{Unimplemented_Unit}
13949
13950@tab
13951
13952Affects legality
13953
13954@item
13955
13956@emph{Unchecked_Union}
13957
13958@tab
13959
13960Affects semantics
13961
13962@end multitable
13963
13964
13965In each of the above cases, it is essential to the purpose of the pragma
13966that this advice not be followed.  For details see
13967@ref{7,,Implementation Defined Pragmas}.
13968
13969@node RM 2 8 17-19 Pragmas,RM 3 5 2 5 Alternative Character Sets,RM 2 8 16 Pragmas,Implementation Advice
13970@anchor{gnat_rm/implementation_advice rm-2-8-17-19-pragmas}@anchor{21d}
13971@section RM 2.8(17-19): Pragmas
13972
13973
13974@quotation
13975
13976“Normally, an implementation should not define pragmas that can
13977make an illegal program legal, except as follows:
13978
13979
13980@itemize *
13981
13982@item
13983A pragma used to complete a declaration, such as a pragma @code{Import};
13984
13985@item
13986A pragma used to configure the environment by adding, removing, or
13987replacing @code{library_items}.”
13988@end itemize
13989@end quotation
13990
13991See @ref{21c,,RM 2.8(16); Pragmas}.
13992
13993@geindex Character Sets
13994
13995@geindex Alternative Character Sets
13996
13997@node RM 3 5 2 5 Alternative Character Sets,RM 3 5 4 28 Integer Types,RM 2 8 17-19 Pragmas,Implementation Advice
13998@anchor{gnat_rm/implementation_advice rm-3-5-2-5-alternative-character-sets}@anchor{21e}
13999@section RM 3.5.2(5): Alternative Character Sets
14000
14001
14002@quotation
14003
14004“If an implementation supports a mode with alternative interpretations
14005for @code{Character} and @code{Wide_Character}, the set of graphic
14006characters of @code{Character} should nevertheless remain a proper
14007subset of the set of graphic characters of @code{Wide_Character}.  Any
14008character set ‘localizations’ should be reflected in the results of
14009the subprograms defined in the language-defined package
14010@code{Characters.Handling} (see A.3) available in such a mode.  In a mode with
14011an alternative interpretation of @code{Character}, the implementation should
14012also support a corresponding change in what is a legal
14013@code{identifier_letter}.”
14014@end quotation
14015
14016Not all wide character modes follow this advice, in particular the JIS
14017and IEC modes reflect standard usage in Japan, and in these encoding,
14018the upper half of the Latin-1 set is not part of the wide-character
14019subset, since the most significant bit is used for wide character
14020encoding.  However, this only applies to the external forms.  Internally
14021there is no such restriction.
14022
14023@geindex Integer types
14024
14025@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
14026@anchor{gnat_rm/implementation_advice rm-3-5-4-28-integer-types}@anchor{21f}
14027@section RM 3.5.4(28): Integer Types
14028
14029
14030@quotation
14031
14032“An implementation should support @code{Long_Integer} in addition to
14033@code{Integer} if the target machine supports 32-bit (or longer)
14034arithmetic.  No other named integer subtypes are recommended for package
14035@code{Standard}.  Instead, appropriate named integer subtypes should be
14036provided in the library package @code{Interfaces} (see B.2).”
14037@end quotation
14038
14039@code{Long_Integer} is supported.  Other standard integer types are supported
14040so this advice is not fully followed.  These types
14041are supported for convenient interface to C, and so that all hardware
14042types of the machine are easily available.
14043
14044@node RM 3 5 4 29 Integer Types,RM 3 5 5 8 Enumeration Values,RM 3 5 4 28 Integer Types,Implementation Advice
14045@anchor{gnat_rm/implementation_advice rm-3-5-4-29-integer-types}@anchor{220}
14046@section RM 3.5.4(29): Integer Types
14047
14048
14049@quotation
14050
14051“An implementation for a two’s complement machine should support
14052modular types with a binary modulus up to @code{System.Max_Int*2+2}.  An
14053implementation should support a non-binary modules up to @code{Integer'Last}.”
14054@end quotation
14055
14056Followed.
14057
14058@geindex Enumeration values
14059
14060@node RM 3 5 5 8 Enumeration Values,RM 3 5 7 17 Float Types,RM 3 5 4 29 Integer Types,Implementation Advice
14061@anchor{gnat_rm/implementation_advice rm-3-5-5-8-enumeration-values}@anchor{221}
14062@section RM 3.5.5(8): Enumeration Values
14063
14064
14065@quotation
14066
14067“For the evaluation of a call on @code{S'Pos} for an enumeration
14068subtype, if the value of the operand does not correspond to the internal
14069code for any enumeration literal of its type (perhaps due to an
14070un-initialized variable), then the implementation should raise
14071@code{Program_Error}.  This is particularly important for enumeration
14072types with noncontiguous internal codes specified by an
14073enumeration_representation_clause.”
14074@end quotation
14075
14076Followed.
14077
14078@geindex Float types
14079
14080@node RM 3 5 7 17 Float Types,RM 3 6 2 11 Multidimensional Arrays,RM 3 5 5 8 Enumeration Values,Implementation Advice
14081@anchor{gnat_rm/implementation_advice rm-3-5-7-17-float-types}@anchor{222}
14082@section RM 3.5.7(17): Float Types
14083
14084
14085@quotation
14086
14087“An implementation should support @code{Long_Float} in addition to
14088@code{Float} if the target machine supports 11 or more digits of
14089precision.  No other named floating point subtypes are recommended for
14090package @code{Standard}.  Instead, appropriate named floating point subtypes
14091should be provided in the library package @code{Interfaces} (see B.2).”
14092@end quotation
14093
14094@code{Short_Float} and @code{Long_Long_Float} are also provided.  The
14095former provides improved compatibility with other implementations
14096supporting this type.  The latter corresponds to the highest precision
14097floating-point type supported by the hardware.  On most machines, this
14098will be the same as @code{Long_Float}, but on some machines, it will
14099correspond to the IEEE extended form.  The notable case is all x86
14100implementations, where @code{Long_Long_Float} corresponds to the 80-bit
14101extended precision format supported in hardware on this processor.
14102Note that the 128-bit format on SPARC is not supported, since this
14103is a software rather than a hardware format.
14104
14105@geindex Multidimensional arrays
14106
14107@geindex Arrays
14108@geindex multidimensional
14109
14110@node RM 3 6 2 11 Multidimensional Arrays,RM 9 6 30-31 Duration’Small,RM 3 5 7 17 Float Types,Implementation Advice
14111@anchor{gnat_rm/implementation_advice rm-3-6-2-11-multidimensional-arrays}@anchor{223}
14112@section RM 3.6.2(11): Multidimensional Arrays
14113
14114
14115@quotation
14116
14117“An implementation should normally represent multidimensional arrays in
14118row-major order, consistent with the notation used for multidimensional
14119array aggregates (see 4.3.3).  However, if a pragma @code{Convention}
14120(@code{Fortran}, …) applies to a multidimensional array type, then
14121column-major order should be used instead (see B.5, @emph{Interfacing with Fortran}).”
14122@end quotation
14123
14124Followed.
14125
14126@geindex Duration'Small
14127
14128@node RM 9 6 30-31 Duration’Small,RM 10 2 1 12 Consistent Representation,RM 3 6 2 11 Multidimensional Arrays,Implementation Advice
14129@anchor{gnat_rm/implementation_advice rm-9-6-30-31-duration-small}@anchor{224}
14130@section RM 9.6(30-31): Duration’Small
14131
14132
14133@quotation
14134
14135“Whenever possible in an implementation, the value of @code{Duration'Small}
14136should be no greater than 100 microseconds.”
14137@end quotation
14138
14139Followed.  (@code{Duration'Small} = 10**(-9)).
14140
14141@quotation
14142
14143“The time base for @code{delay_relative_statements} should be monotonic;
14144it need not be the same time base as used for @code{Calendar.Clock}.”
14145@end quotation
14146
14147Followed.
14148
14149@node RM 10 2 1 12 Consistent Representation,RM 11 4 1 19 Exception Information,RM 9 6 30-31 Duration’Small,Implementation Advice
14150@anchor{gnat_rm/implementation_advice rm-10-2-1-12-consistent-representation}@anchor{225}
14151@section RM 10.2.1(12): Consistent Representation
14152
14153
14154@quotation
14155
14156“In an implementation, a type declared in a pre-elaborated package should
14157have the same representation in every elaboration of a given version of
14158the package, whether the elaborations occur in distinct executions of
14159the same program, or in executions of distinct programs or partitions
14160that include the given version.”
14161@end quotation
14162
14163Followed, except in the case of tagged types.  Tagged types involve
14164implicit pointers to a local copy of a dispatch table, and these pointers
14165have representations which thus depend on a particular elaboration of the
14166package.  It is not easy to see how it would be possible to follow this
14167advice without severely impacting efficiency of execution.
14168
14169@geindex Exception information
14170
14171@node RM 11 4 1 19 Exception Information,RM 11 5 28 Suppression of Checks,RM 10 2 1 12 Consistent Representation,Implementation Advice
14172@anchor{gnat_rm/implementation_advice rm-11-4-1-19-exception-information}@anchor{226}
14173@section RM 11.4.1(19): Exception Information
14174
14175
14176@quotation
14177
14178“@code{Exception_Message} by default and @code{Exception_Information}
14179should produce information useful for
14180debugging.  @code{Exception_Message} should be short, about one
14181line.  @code{Exception_Information} can be long.  @code{Exception_Message}
14182should not include the
14183@code{Exception_Name}.  @code{Exception_Information} should include both
14184the @code{Exception_Name} and the @code{Exception_Message}.”
14185@end quotation
14186
14187Followed.  For each exception that doesn’t have a specified
14188@code{Exception_Message}, the compiler generates one containing the location
14189of the raise statement.  This location has the form ‘file_name:line’, where
14190file_name is the short file name (without path information) and line is the line
14191number in the file.  Note that in the case of the Zero Cost Exception
14192mechanism, these messages become redundant with the Exception_Information that
14193contains a full backtrace of the calling sequence, so they are disabled.
14194To disable explicitly the generation of the source location message, use the
14195Pragma @code{Discard_Names}.
14196
14197@geindex Suppression of checks
14198
14199@geindex Checks
14200@geindex suppression of
14201
14202@node RM 11 5 28 Suppression of Checks,RM 13 1 21-24 Representation Clauses,RM 11 4 1 19 Exception Information,Implementation Advice
14203@anchor{gnat_rm/implementation_advice rm-11-5-28-suppression-of-checks}@anchor{227}
14204@section RM 11.5(28): Suppression of Checks
14205
14206
14207@quotation
14208
14209“The implementation should minimize the code executed for checks that
14210have been suppressed.”
14211@end quotation
14212
14213Followed.
14214
14215@geindex Representation clauses
14216
14217@node RM 13 1 21-24 Representation Clauses,RM 13 2 6-8 Packed Types,RM 11 5 28 Suppression of Checks,Implementation Advice
14218@anchor{gnat_rm/implementation_advice rm-13-1-21-24-representation-clauses}@anchor{228}
14219@section RM 13.1 (21-24): Representation Clauses
14220
14221
14222@quotation
14223
14224“The recommended level of support for all representation items is
14225qualified as follows:
14226
14227An implementation need not support representation items containing
14228nonstatic expressions, except that an implementation should support a
14229representation item for a given entity if each nonstatic expression in
14230the representation item is a name that statically denotes a constant
14231declared before the entity.”
14232@end quotation
14233
14234Followed.  In fact, GNAT goes beyond the recommended level of support
14235by allowing nonstatic expressions in some representation clauses even
14236without the need to declare constants initialized with the values of
14237such expressions.
14238For example:
14239
14240@example
14241  X : Integer;
14242  Y : Float;
14243  for Y'Address use X'Address;>>
14244
14245
14246"An implementation need not support a specification for the `@w{`}Size`@w{`}
14247for a given composite subtype, nor the size or storage place for an
14248object (including a component) of a given composite subtype, unless the
14249constraints on the subtype and its composite subcomponents (if any) are
14250all static constraints."
14251@end example
14252
14253Followed.  Size Clauses are not permitted on nonstatic components, as
14254described above.
14255
14256@quotation
14257
14258“An aliased component, or a component whose type is by-reference, should
14259always be allocated at an addressable location.”
14260@end quotation
14261
14262Followed.
14263
14264@geindex Packed types
14265
14266@node RM 13 2 6-8 Packed Types,RM 13 3 14-19 Address Clauses,RM 13 1 21-24 Representation Clauses,Implementation Advice
14267@anchor{gnat_rm/implementation_advice rm-13-2-6-8-packed-types}@anchor{229}
14268@section RM 13.2(6-8): Packed Types
14269
14270
14271@quotation
14272
14273“If a type is packed, then the implementation should try to minimize
14274storage allocated to objects of the type, possibly at the expense of
14275speed of accessing components, subject to reasonable complexity in
14276addressing calculations.
14277
14278The recommended level of support pragma @code{Pack} is:
14279
14280For a packed record type, the components should be packed as tightly as
14281possible subject to the Sizes of the component subtypes, and subject to
14282any @emph{record_representation_clause} that applies to the type; the
14283implementation may, but need not, reorder components or cross aligned
14284word boundaries to improve the packing.  A component whose @code{Size} is
14285greater than the word size may be allocated an integral number of words.”
14286@end quotation
14287
14288Followed.  Tight packing of arrays is supported for all component sizes
14289up to 64-bits. If the array component size is 1 (that is to say, if
14290the component is a boolean type or an enumeration type with two values)
14291then values of the type are implicitly initialized to zero. This
14292happens both for objects of the packed type, and for objects that have a
14293subcomponent of the packed type.
14294
14295@quotation
14296
14297“An implementation should support Address clauses for imported
14298subprograms.”
14299@end quotation
14300
14301Followed.
14302
14303@geindex Address clauses
14304
14305@node RM 13 3 14-19 Address Clauses,RM 13 3 29-35 Alignment Clauses,RM 13 2 6-8 Packed Types,Implementation Advice
14306@anchor{gnat_rm/implementation_advice rm-13-3-14-19-address-clauses}@anchor{22a}
14307@section RM 13.3(14-19): Address Clauses
14308
14309
14310@quotation
14311
14312“For an array @code{X}, @code{X'Address} should point at the first
14313component of the array, and not at the array bounds.”
14314@end quotation
14315
14316Followed.
14317
14318@quotation
14319
14320“The recommended level of support for the @code{Address} attribute is:
14321
14322@code{X'Address} should produce a useful result if @code{X} is an
14323object that is aliased or of a by-reference type, or is an entity whose
14324@code{Address} has been specified.”
14325@end quotation
14326
14327Followed.  A valid address will be produced even if none of those
14328conditions have been met.  If necessary, the object is forced into
14329memory to ensure the address is valid.
14330
14331@quotation
14332
14333“An implementation should support @code{Address} clauses for imported
14334subprograms.”
14335@end quotation
14336
14337Followed.
14338
14339@quotation
14340
14341“Objects (including subcomponents) that are aliased or of a by-reference
14342type should be allocated on storage element boundaries.”
14343@end quotation
14344
14345Followed.
14346
14347@quotation
14348
14349“If the @code{Address} of an object is specified, or it is imported or exported,
14350then the implementation should not perform optimizations based on
14351assumptions of no aliases.”
14352@end quotation
14353
14354Followed.
14355
14356@geindex Alignment clauses
14357
14358@node RM 13 3 29-35 Alignment Clauses,RM 13 3 42-43 Size Clauses,RM 13 3 14-19 Address Clauses,Implementation Advice
14359@anchor{gnat_rm/implementation_advice rm-13-3-29-35-alignment-clauses}@anchor{22b}
14360@section RM 13.3(29-35): Alignment Clauses
14361
14362
14363@quotation
14364
14365“The recommended level of support for the @code{Alignment} attribute for
14366subtypes is:
14367
14368An implementation should support specified Alignments that are factors
14369and multiples of the number of storage elements per word, subject to the
14370following:”
14371@end quotation
14372
14373Followed.
14374
14375@quotation
14376
14377“An implementation need not support specified Alignments for
14378combinations of Sizes and Alignments that cannot be easily
14379loaded and stored by available machine instructions.”
14380@end quotation
14381
14382Followed.
14383
14384@quotation
14385
14386“An implementation need not support specified Alignments that are
14387greater than the maximum @code{Alignment} the implementation ever returns by
14388default.”
14389@end quotation
14390
14391Followed.
14392
14393@quotation
14394
14395“The recommended level of support for the @code{Alignment} attribute for
14396objects is:
14397
14398Same as above, for subtypes, but in addition:”
14399@end quotation
14400
14401Followed.
14402
14403@quotation
14404
14405“For stand-alone library-level objects of statically constrained
14406subtypes, the implementation should support all alignments
14407supported by the target linker.  For example, page alignment is likely to
14408be supported for such objects, but not for subtypes.”
14409@end quotation
14410
14411Followed.
14412
14413@geindex Size clauses
14414
14415@node RM 13 3 42-43 Size Clauses,RM 13 3 50-56 Size Clauses,RM 13 3 29-35 Alignment Clauses,Implementation Advice
14416@anchor{gnat_rm/implementation_advice rm-13-3-42-43-size-clauses}@anchor{22c}
14417@section RM 13.3(42-43): Size Clauses
14418
14419
14420@quotation
14421
14422“The recommended level of support for the @code{Size} attribute of
14423objects is:
14424
14425A @code{Size} clause should be supported for an object if the specified
14426@code{Size} is at least as large as its subtype’s @code{Size}, and
14427corresponds to a size in storage elements that is a multiple of the
14428object’s @code{Alignment} (if the @code{Alignment} is nonzero).”
14429@end quotation
14430
14431Followed.
14432
14433@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
14434@anchor{gnat_rm/implementation_advice rm-13-3-50-56-size-clauses}@anchor{22d}
14435@section RM 13.3(50-56): Size Clauses
14436
14437
14438@quotation
14439
14440“If the @code{Size} of a subtype is specified, and allows for efficient
14441independent addressability (see 9.10) on the target architecture, then
14442the @code{Size} of the following objects of the subtype should equal the
14443@code{Size} of the subtype:
14444
14445Aliased objects (including components).”
14446@end quotation
14447
14448Followed.
14449
14450@quotation
14451
14452“@cite{Size} clause on a composite subtype should not affect the
14453internal layout of components.”
14454@end quotation
14455
14456Followed. But note that this can be overridden by use of the implementation
14457pragma Implicit_Packing in the case of packed arrays.
14458
14459@quotation
14460
14461“The recommended level of support for the @code{Size} attribute of subtypes is:
14462
14463The @code{Size} (if not specified) of a static discrete or fixed point
14464subtype should be the number of bits needed to represent each value
14465belonging to the subtype using an unbiased representation, leaving space
14466for a sign bit only if the subtype contains negative values.  If such a
14467subtype is a first subtype, then an implementation should support a
14468specified @code{Size} for it that reflects this representation.”
14469@end quotation
14470
14471Followed.
14472
14473@quotation
14474
14475“For a subtype implemented with levels of indirection, the @code{Size}
14476should include the size of the pointers, but not the size of what they
14477point at.”
14478@end quotation
14479
14480Followed.
14481
14482@geindex Component_Size clauses
14483
14484@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
14485@anchor{gnat_rm/implementation_advice rm-13-3-71-73-component-size-clauses}@anchor{22e}
14486@section RM 13.3(71-73): Component Size Clauses
14487
14488
14489@quotation
14490
14491“The recommended level of support for the @code{Component_Size}
14492attribute is:
14493
14494An implementation need not support specified @code{Component_Sizes} that are
14495less than the @code{Size} of the component subtype.”
14496@end quotation
14497
14498Followed.
14499
14500@quotation
14501
14502“An implementation should support specified Component_Sizes that
14503are factors and multiples of the word size.  For such
14504Component_Sizes, the array should contain no gaps between
14505components.  For other Component_Sizes (if supported), the array
14506should contain no gaps between components when packing is also
14507specified; the implementation should forbid this combination in cases
14508where it cannot support a no-gaps representation.”
14509@end quotation
14510
14511Followed.
14512
14513@geindex Enumeration representation clauses
14514
14515@geindex Representation clauses
14516@geindex enumeration
14517
14518@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
14519@anchor{gnat_rm/implementation_advice rm-13-4-9-10-enumeration-representation-clauses}@anchor{22f}
14520@section RM 13.4(9-10): Enumeration Representation Clauses
14521
14522
14523@quotation
14524
14525“The recommended level of support for enumeration representation clauses
14526is:
14527
14528An implementation need not support enumeration representation clauses
14529for boolean types, but should at minimum support the internal codes in
14530the range @code{System.Min_Int .. System.Max_Int}.”
14531@end quotation
14532
14533Followed.
14534
14535@geindex Record representation clauses
14536
14537@geindex Representation clauses
14538@geindex records
14539
14540@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
14541@anchor{gnat_rm/implementation_advice rm-13-5-1-17-22-record-representation-clauses}@anchor{230}
14542@section RM 13.5.1(17-22): Record Representation Clauses
14543
14544
14545@quotation
14546
14547“The recommended level of support for
14548@emph{record_representation_clause}s is:
14549
14550An implementation should support storage places that can be extracted
14551with a load, mask, shift sequence of machine code, and set with a load,
14552shift, mask, store sequence, given the available machine instructions
14553and run-time model.”
14554@end quotation
14555
14556Followed.
14557
14558@quotation
14559
14560“A storage place should be supported if its size is equal to the
14561@code{Size} of the component subtype, and it starts and ends on a
14562boundary that obeys the @code{Alignment} of the component subtype.”
14563@end quotation
14564
14565Followed.
14566
14567@quotation
14568
14569“If the default bit ordering applies to the declaration of a given type,
14570then for a component whose subtype’s @code{Size} is less than the word
14571size, any storage place that does not cross an aligned word boundary
14572should be supported.”
14573@end quotation
14574
14575Followed.
14576
14577@quotation
14578
14579“An implementation may reserve a storage place for the tag field of a
14580tagged type, and disallow other components from overlapping that place.”
14581@end quotation
14582
14583Followed.  The storage place for the tag field is the beginning of the tagged
14584record, and its size is Address’Size.  GNAT will reject an explicit component
14585clause for the tag field.
14586
14587@quotation
14588
14589“An implementation need not support a @emph{component_clause} for a
14590component of an extension part if the storage place is not after the
14591storage places of all components of the parent type, whether or not
14592those storage places had been specified.”
14593@end quotation
14594
14595Followed.  The above advice on record representation clauses is followed,
14596and all mentioned features are implemented.
14597
14598@geindex Storage place attributes
14599
14600@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
14601@anchor{gnat_rm/implementation_advice rm-13-5-2-5-storage-place-attributes}@anchor{231}
14602@section RM 13.5.2(5): Storage Place Attributes
14603
14604
14605@quotation
14606
14607“If a component is represented using some form of pointer (such as an
14608offset) to the actual data of the component, and this data is contiguous
14609with the rest of the object, then the storage place attributes should
14610reflect the place of the actual data, not the pointer.  If a component is
14611allocated discontinuously from the rest of the object, then a warning
14612should be generated upon reference to one of its storage place
14613attributes.”
14614@end quotation
14615
14616Followed.  There are no such components in GNAT.
14617
14618@geindex Bit ordering
14619
14620@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
14621@anchor{gnat_rm/implementation_advice rm-13-5-3-7-8-bit-ordering}@anchor{232}
14622@section RM 13.5.3(7-8): Bit Ordering
14623
14624
14625@quotation
14626
14627“The recommended level of support for the non-default bit ordering is:
14628
14629If @code{Word_Size} = @code{Storage_Unit}, then the implementation
14630should support the non-default bit ordering in addition to the default
14631bit ordering.”
14632@end quotation
14633
14634Followed.  Word size does not equal storage size in this implementation.
14635Thus non-default bit ordering is not supported.
14636
14637@geindex Address
14638@geindex as private type
14639
14640@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
14641@anchor{gnat_rm/implementation_advice rm-13-7-37-address-as-private}@anchor{233}
14642@section RM 13.7(37): Address as Private
14643
14644
14645@quotation
14646
14647“@cite{Address} should be of a private type.”
14648@end quotation
14649
14650Followed.
14651
14652@geindex Operations
14653@geindex on `@w{`}Address`@w{`}
14654
14655@geindex Address
14656@geindex operations of
14657
14658@node RM 13 7 1 16 Address Operations,RM 13 9 14-17 Unchecked Conversion,RM 13 7 37 Address as Private,Implementation Advice
14659@anchor{gnat_rm/implementation_advice rm-13-7-1-16-address-operations}@anchor{234}
14660@section RM 13.7.1(16): Address Operations
14661
14662
14663@quotation
14664
14665“Operations in @code{System} and its children should reflect the target
14666environment semantics as closely as is reasonable.  For example, on most
14667machines, it makes sense for address arithmetic to ‘wrap around’.
14668Operations that do not make sense should raise @code{Program_Error}.”
14669@end quotation
14670
14671Followed.  Address arithmetic is modular arithmetic that wraps around.  No
14672operation raises @code{Program_Error}, since all operations make sense.
14673
14674@geindex Unchecked conversion
14675
14676@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
14677@anchor{gnat_rm/implementation_advice rm-13-9-14-17-unchecked-conversion}@anchor{235}
14678@section RM 13.9(14-17): Unchecked Conversion
14679
14680
14681@quotation
14682
14683“The @code{Size} of an array object should not include its bounds; hence,
14684the bounds should not be part of the converted data.”
14685@end quotation
14686
14687Followed.
14688
14689@quotation
14690
14691“The implementation should not generate unnecessary run-time checks to
14692ensure that the representation of @code{S} is a representation of the
14693target type.  It should take advantage of the permission to return by
14694reference when possible.  Restrictions on unchecked conversions should be
14695avoided unless required by the target environment.”
14696@end quotation
14697
14698Followed.  There are no restrictions on unchecked conversion.  A warning is
14699generated if the source and target types do not have the same size since
14700the semantics in this case may be target dependent.
14701
14702@quotation
14703
14704“The recommended level of support for unchecked conversions is:
14705
14706Unchecked conversions should be supported and should be reversible in
14707the cases where this clause defines the result.  To enable meaningful use
14708of unchecked conversion, a contiguous representation should be used for
14709elementary subtypes, for statically constrained array subtypes whose
14710component subtype is one of the subtypes described in this paragraph,
14711and for record subtypes without discriminants whose component subtypes
14712are described in this paragraph.”
14713@end quotation
14714
14715Followed.
14716
14717@geindex Heap usage
14718@geindex implicit
14719
14720@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
14721@anchor{gnat_rm/implementation_advice rm-13-11-23-25-implicit-heap-usage}@anchor{236}
14722@section RM 13.11(23-25): Implicit Heap Usage
14723
14724
14725@quotation
14726
14727“An implementation should document any cases in which it dynamically
14728allocates heap storage for a purpose other than the evaluation of an
14729allocator.”
14730@end quotation
14731
14732Followed, the only other points at which heap storage is dynamically
14733allocated are as follows:
14734
14735
14736@itemize *
14737
14738@item
14739At initial elaboration time, to allocate dynamically sized global
14740objects.
14741
14742@item
14743To allocate space for a task when a task is created.
14744
14745@item
14746To extend the secondary stack dynamically when needed.  The secondary
14747stack is used for returning variable length results.
14748@end itemize
14749
14750
14751@quotation
14752
14753“A default (implementation-provided) storage pool for an
14754access-to-constant type should not have overhead to support deallocation of
14755individual objects.”
14756@end quotation
14757
14758Followed.
14759
14760@quotation
14761
14762“A storage pool for an anonymous access type should be created at the
14763point of an allocator for the type, and be reclaimed when the designated
14764object becomes inaccessible.”
14765@end quotation
14766
14767Followed.
14768
14769@geindex Unchecked deallocation
14770
14771@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
14772@anchor{gnat_rm/implementation_advice rm-13-11-2-17-unchecked-deallocation}@anchor{237}
14773@section RM 13.11.2(17): Unchecked Deallocation
14774
14775
14776@quotation
14777
14778“For a standard storage pool, @code{Free} should actually reclaim the
14779storage.”
14780@end quotation
14781
14782Followed.
14783
14784@geindex Stream oriented attributes
14785
14786@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
14787@anchor{gnat_rm/implementation_advice rm-13-13-2-1-6-stream-oriented-attributes}@anchor{238}
14788@section RM 13.13.2(1.6): Stream Oriented Attributes
14789
14790
14791@quotation
14792
14793“If not specified, the value of Stream_Size for an elementary type
14794should be the number of bits that corresponds to the minimum number of
14795stream elements required by the first subtype of the type, rounded up
14796to the nearest factor or multiple of the word size that is also a
14797multiple of the stream element size.”
14798@end quotation
14799
14800Followed, except that the number of stream elements is 1, 2, 3, 4 or 8.
14801The Stream_Size may be used to override the default choice.
14802
14803The default implementation is based on direct binary representations and is
14804therefore target- and endianness-dependent.  To address this issue, GNAT also
14805supplies an alternate implementation of the stream attributes @code{Read} and
14806@code{Write}, which uses the target-independent XDR standard representation for
14807scalar types. This XDR alternative can be enabled via the binder switch -xdr.
14808
14809@geindex XDR representation
14810
14811@geindex Read attribute
14812
14813@geindex Write attribute
14814
14815@geindex Stream oriented attributes
14816
14817@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
14818@anchor{gnat_rm/implementation_advice rm-a-1-52-names-of-predefined-numeric-types}@anchor{239}
14819@section RM A.1(52): Names of Predefined Numeric Types
14820
14821
14822@quotation
14823
14824“If an implementation provides additional named predefined integer types,
14825then the names should end with @code{Integer} as in
14826@code{Long_Integer}.  If an implementation provides additional named
14827predefined floating point types, then the names should end with
14828@code{Float} as in @code{Long_Float}.”
14829@end quotation
14830
14831Followed.
14832
14833@geindex Ada.Characters.Handling
14834
14835@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
14836@anchor{gnat_rm/implementation_advice rm-a-3-2-49-ada-characters-handling}@anchor{23a}
14837@section RM A.3.2(49): @code{Ada.Characters.Handling}
14838
14839
14840@quotation
14841
14842“If an implementation provides a localized definition of @code{Character}
14843or @code{Wide_Character}, then the effects of the subprograms in
14844@code{Characters.Handling} should reflect the localizations.
14845See also 3.5.2.”
14846@end quotation
14847
14848Followed.  GNAT provides no such localized definitions.
14849
14850@geindex Bounded-length strings
14851
14852@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
14853@anchor{gnat_rm/implementation_advice rm-a-4-4-106-bounded-length-string-handling}@anchor{23b}
14854@section RM A.4.4(106): Bounded-Length String Handling
14855
14856
14857@quotation
14858
14859“Bounded string objects should not be implemented by implicit pointers
14860and dynamic allocation.”
14861@end quotation
14862
14863Followed.  No implicit pointers or dynamic allocation are used.
14864
14865@geindex Random number generation
14866
14867@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
14868@anchor{gnat_rm/implementation_advice rm-a-5-2-46-47-random-number-generation}@anchor{23c}
14869@section RM A.5.2(46-47): Random Number Generation
14870
14871
14872@quotation
14873
14874“Any storage associated with an object of type @code{Generator} should be
14875reclaimed on exit from the scope of the object.”
14876@end quotation
14877
14878Followed.
14879
14880@quotation
14881
14882“If the generator period is sufficiently long in relation to the number
14883of distinct initiator values, then each possible value of
14884@code{Initiator} passed to @code{Reset} should initiate a sequence of
14885random numbers that does not, in a practical sense, overlap the sequence
14886initiated by any other value.  If this is not possible, then the mapping
14887between initiator values and generator states should be a rapidly
14888varying function of the initiator value.”
14889@end quotation
14890
14891Followed.  The generator period is sufficiently long for the first
14892condition here to hold true.
14893
14894@geindex Get_Immediate
14895
14896@node RM A 10 7 23 Get_Immediate,RM A 18 Containers,RM A 5 2 46-47 Random Number Generation,Implementation Advice
14897@anchor{gnat_rm/implementation_advice rm-a-10-7-23-get-immediate}@anchor{23d}
14898@section RM A.10.7(23): @code{Get_Immediate}
14899
14900
14901@quotation
14902
14903“The @code{Get_Immediate} procedures should be implemented with
14904unbuffered input.  For a device such as a keyboard, input should be
14905available if a key has already been typed, whereas for a disk
14906file, input should always be available except at end of file.  For a file
14907associated with a keyboard-like device, any line-editing features of the
14908underlying operating system should be disabled during the execution of
14909@code{Get_Immediate}.”
14910@end quotation
14911
14912Followed on all targets except VxWorks. For VxWorks, there is no way to
14913provide this functionality that does not result in the input buffer being
14914flushed before the @code{Get_Immediate} call. A special unit
14915@code{Interfaces.Vxworks.IO} is provided that contains routines to enable
14916this functionality.
14917
14918@geindex Containers
14919
14920@node RM A 18 Containers,RM B 1 39-41 Pragma Export,RM A 10 7 23 Get_Immediate,Implementation Advice
14921@anchor{gnat_rm/implementation_advice rm-a-18-containers}@anchor{23e}
14922@section RM A.18: @code{Containers}
14923
14924
14925All implementation advice pertaining to Ada.Containers and its
14926child units (that is, all implementation advice occurring within
14927section A.18 and its subsections) is followed except for A.18.24(17):
14928
14929@quotation
14930
14931“Bounded ordered set objects should be implemented without implicit pointers or dynamic allocation. “
14932@end quotation
14933
14934The implementations of the two Reference_Preserving_Key functions of
14935the generic package Ada.Containers.Bounded_Ordered_Sets each currently make
14936use of dynamic allocation; other operations on bounded ordered set objects
14937follow the implementation advice.
14938
14939@geindex Export
14940
14941@node RM B 1 39-41 Pragma Export,RM B 2 12-13 Package Interfaces,RM A 18 Containers,Implementation Advice
14942@anchor{gnat_rm/implementation_advice rm-b-1-39-41-pragma-export}@anchor{23f}
14943@section RM B.1(39-41): Pragma @code{Export}
14944
14945
14946@quotation
14947
14948“If an implementation supports pragma @code{Export} to a given language,
14949then it should also allow the main subprogram to be written in that
14950language.  It should support some mechanism for invoking the elaboration
14951of the Ada library units included in the system, and for invoking the
14952finalization of the environment task.  On typical systems, the
14953recommended mechanism is to provide two subprograms whose link names are
14954@code{adainit} and @code{adafinal}.  @code{adainit} should contain the
14955elaboration code for library units.  @code{adafinal} should contain the
14956finalization code.  These subprograms should have no effect the second
14957and subsequent time they are called.”
14958@end quotation
14959
14960Followed.
14961
14962@quotation
14963
14964“Automatic elaboration of pre-elaborated packages should be
14965provided when pragma @code{Export} is supported.”
14966@end quotation
14967
14968Followed when the main program is in Ada.  If the main program is in a
14969foreign language, then
14970@code{adainit} must be called to elaborate pre-elaborated
14971packages.
14972
14973@quotation
14974
14975“For each supported convention @emph{L} other than @code{Intrinsic}, an
14976implementation should support @code{Import} and @code{Export} pragmas
14977for objects of @emph{L}-compatible types and for subprograms, and pragma
14978@cite{Convention} for @emph{L}-eligible types and for subprograms,
14979presuming the other language has corresponding features.  Pragma
14980@code{Convention} need not be supported for scalar types.”
14981@end quotation
14982
14983Followed.
14984
14985@geindex Package Interfaces
14986
14987@geindex Interfaces
14988
14989@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
14990@anchor{gnat_rm/implementation_advice rm-b-2-12-13-package-interfaces}@anchor{240}
14991@section RM B.2(12-13): Package @code{Interfaces}
14992
14993
14994@quotation
14995
14996“For each implementation-defined convention identifier, there should be a
14997child package of package Interfaces with the corresponding name.  This
14998package should contain any declarations that would be useful for
14999interfacing to the language (implementation) represented by the
15000convention.  Any declarations useful for interfacing to any language on
15001the given hardware architecture should be provided directly in
15002@code{Interfaces}.”
15003@end quotation
15004
15005Followed.
15006
15007@quotation
15008
15009“An implementation supporting an interface to C, COBOL, or Fortran should
15010provide the corresponding package or packages described in the following
15011clauses.”
15012@end quotation
15013
15014Followed.  GNAT provides all the packages described in this section.
15015
15016@geindex C
15017@geindex interfacing with
15018
15019@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
15020@anchor{gnat_rm/implementation_advice rm-b-3-63-71-interfacing-with-c}@anchor{241}
15021@section RM B.3(63-71): Interfacing with C
15022
15023
15024@quotation
15025
15026“An implementation should support the following interface correspondences
15027between Ada and C.”
15028@end quotation
15029
15030Followed.
15031
15032@quotation
15033
15034“An Ada procedure corresponds to a void-returning C function.”
15035@end quotation
15036
15037Followed.
15038
15039@quotation
15040
15041“An Ada function corresponds to a non-void C function.”
15042@end quotation
15043
15044Followed.
15045
15046@quotation
15047
15048“An Ada @code{in} scalar parameter is passed as a scalar argument to a C
15049function.”
15050@end quotation
15051
15052Followed.
15053
15054@quotation
15055
15056“An Ada @code{in} parameter of an access-to-object type with designated
15057type @code{T} is passed as a @code{t*} argument to a C function,
15058where @code{t} is the C type corresponding to the Ada type @code{T}.”
15059@end quotation
15060
15061Followed.
15062
15063@quotation
15064
15065“An Ada access @code{T} parameter, or an Ada @code{out} or @code{in out}
15066parameter of an elementary type @code{T}, is passed as a @code{t*}
15067argument to a C function, where @code{t} is the C type corresponding to
15068the Ada type @code{T}.  In the case of an elementary @code{out} or
15069@code{in out} parameter, a pointer to a temporary copy is used to
15070preserve by-copy semantics.”
15071@end quotation
15072
15073Followed.
15074
15075@quotation
15076
15077“An Ada parameter of a record type @code{T}, of any mode, is passed as a
15078@code{t*} argument to a C function, where @code{t} is the C
15079structure corresponding to the Ada type @code{T}.”
15080@end quotation
15081
15082Followed.  This convention may be overridden by the use of the C_Pass_By_Copy
15083pragma, or Convention, or by explicitly specifying the mechanism for a given
15084call using an extended import or export pragma.
15085
15086@quotation
15087
15088“An Ada parameter of an array type with component type @code{T}, of any
15089mode, is passed as a @code{t*} argument to a C function, where
15090@code{t} is the C type corresponding to the Ada type @code{T}.”
15091@end quotation
15092
15093Followed.
15094
15095@quotation
15096
15097“An Ada parameter of an access-to-subprogram type is passed as a pointer
15098to a C function whose prototype corresponds to the designated
15099subprogram’s specification.”
15100@end quotation
15101
15102Followed.
15103
15104@geindex COBOL
15105@geindex interfacing with
15106
15107@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
15108@anchor{gnat_rm/implementation_advice rm-b-4-95-98-interfacing-with-cobol}@anchor{242}
15109@section RM B.4(95-98): Interfacing with COBOL
15110
15111
15112@quotation
15113
15114“An Ada implementation should support the following interface
15115correspondences between Ada and COBOL.”
15116@end quotation
15117
15118Followed.
15119
15120@quotation
15121
15122“An Ada access @code{T} parameter is passed as a @code{BY REFERENCE} data item of
15123the COBOL type corresponding to @code{T}.”
15124@end quotation
15125
15126Followed.
15127
15128@quotation
15129
15130“An Ada in scalar parameter is passed as a @code{BY CONTENT} data item of
15131the corresponding COBOL type.”
15132@end quotation
15133
15134Followed.
15135
15136@quotation
15137
15138“Any other Ada parameter is passed as a @code{BY REFERENCE} data item of the
15139COBOL type corresponding to the Ada parameter type; for scalars, a local
15140copy is used if necessary to ensure by-copy semantics.”
15141@end quotation
15142
15143Followed.
15144
15145@geindex Fortran
15146@geindex interfacing with
15147
15148@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
15149@anchor{gnat_rm/implementation_advice rm-b-5-22-26-interfacing-with-fortran}@anchor{243}
15150@section RM B.5(22-26): Interfacing with Fortran
15151
15152
15153@quotation
15154
15155“An Ada implementation should support the following interface
15156correspondences between Ada and Fortran:”
15157@end quotation
15158
15159Followed.
15160
15161@quotation
15162
15163“An Ada procedure corresponds to a Fortran subroutine.”
15164@end quotation
15165
15166Followed.
15167
15168@quotation
15169
15170“An Ada function corresponds to a Fortran function.”
15171@end quotation
15172
15173Followed.
15174
15175@quotation
15176
15177“An Ada parameter of an elementary, array, or record type @code{T} is
15178passed as a @code{T} argument to a Fortran procedure, where @code{T} is
15179the Fortran type corresponding to the Ada type @code{T}, and where the
15180INTENT attribute of the corresponding dummy argument matches the Ada
15181formal parameter mode; the Fortran implementation’s parameter passing
15182conventions are used.  For elementary types, a local copy is used if
15183necessary to ensure by-copy semantics.”
15184@end quotation
15185
15186Followed.
15187
15188@quotation
15189
15190“An Ada parameter of an access-to-subprogram type is passed as a
15191reference to a Fortran procedure whose interface corresponds to the
15192designated subprogram’s specification.”
15193@end quotation
15194
15195Followed.
15196
15197@geindex Machine operations
15198
15199@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
15200@anchor{gnat_rm/implementation_advice rm-c-1-3-5-access-to-machine-operations}@anchor{244}
15201@section RM C.1(3-5): Access to Machine Operations
15202
15203
15204@quotation
15205
15206“The machine code or intrinsic support should allow access to all
15207operations normally available to assembly language programmers for the
15208target environment, including privileged instructions, if any.”
15209@end quotation
15210
15211Followed.
15212
15213@quotation
15214
15215“The interfacing pragmas (see Annex B) should support interface to
15216assembler; the default assembler should be associated with the
15217convention identifier @code{Assembler}.”
15218@end quotation
15219
15220Followed.
15221
15222@quotation
15223
15224“If an entity is exported to assembly language, then the implementation
15225should allocate it at an addressable location, and should ensure that it
15226is retained by the linking process, even if not otherwise referenced
15227from the Ada code.  The implementation should assume that any call to a
15228machine code or assembler subprogram is allowed to read or update every
15229object that is specified as exported.”
15230@end quotation
15231
15232Followed.
15233
15234@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
15235@anchor{gnat_rm/implementation_advice rm-c-1-10-16-access-to-machine-operations}@anchor{245}
15236@section RM C.1(10-16): Access to Machine Operations
15237
15238
15239@quotation
15240
15241“The implementation should ensure that little or no overhead is
15242associated with calling intrinsic and machine-code subprograms.”
15243@end quotation
15244
15245Followed for both intrinsics and machine-code subprograms.
15246
15247@quotation
15248
15249“It is recommended that intrinsic subprograms be provided for convenient
15250access to any machine operations that provide special capabilities or
15251efficiency and that are not otherwise available through the language
15252constructs.”
15253@end quotation
15254
15255Followed.  A full set of machine operation intrinsic subprograms is provided.
15256
15257@quotation
15258
15259“Atomic read-modify-write operations—e.g., test and set, compare and
15260swap, decrement and test, enqueue/dequeue.”
15261@end quotation
15262
15263Followed on any target supporting such operations.
15264
15265@quotation
15266
15267“Standard numeric functions—e.g.:, sin, log.”
15268@end quotation
15269
15270Followed on any target supporting such operations.
15271
15272@quotation
15273
15274“String manipulation operations—e.g.:, translate and test.”
15275@end quotation
15276
15277Followed on any target supporting such operations.
15278
15279@quotation
15280
15281“Vector operations—e.g.:, compare vector against thresholds.”
15282@end quotation
15283
15284Followed on any target supporting such operations.
15285
15286@quotation
15287
15288“Direct operations on I/O ports.”
15289@end quotation
15290
15291Followed on any target supporting such operations.
15292
15293@geindex Interrupt support
15294
15295@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
15296@anchor{gnat_rm/implementation_advice rm-c-3-28-interrupt-support}@anchor{246}
15297@section RM C.3(28): Interrupt Support
15298
15299
15300@quotation
15301
15302“If the @code{Ceiling_Locking} policy is not in effect, the
15303implementation should provide means for the application to specify which
15304interrupts are to be blocked during protected actions, if the underlying
15305system allows for a finer-grain control of interrupt blocking.”
15306@end quotation
15307
15308Followed.  The underlying system does not allow for finer-grain control
15309of interrupt blocking.
15310
15311@geindex Protected procedure handlers
15312
15313@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
15314@anchor{gnat_rm/implementation_advice rm-c-3-1-20-21-protected-procedure-handlers}@anchor{247}
15315@section RM C.3.1(20-21): Protected Procedure Handlers
15316
15317
15318@quotation
15319
15320“Whenever possible, the implementation should allow interrupt handlers to
15321be called directly by the hardware.”
15322@end quotation
15323
15324Followed on any target where the underlying operating system permits
15325such direct calls.
15326
15327@quotation
15328
15329“Whenever practical, violations of any
15330implementation-defined restrictions should be detected before run time.”
15331@end quotation
15332
15333Followed.  Compile time warnings are given when possible.
15334
15335@geindex Package `@w{`}Interrupts`@w{`}
15336
15337@geindex Interrupts
15338
15339@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
15340@anchor{gnat_rm/implementation_advice rm-c-3-2-25-package-interrupts}@anchor{248}
15341@section RM C.3.2(25): Package @code{Interrupts}
15342
15343
15344@quotation
15345
15346“If implementation-defined forms of interrupt handler procedures are
15347supported, such as protected procedures with parameters, then for each
15348such form of a handler, a type analogous to @code{Parameterless_Handler}
15349should be specified in a child package of @code{Interrupts}, with the
15350same operations as in the predefined package Interrupts.”
15351@end quotation
15352
15353Followed.
15354
15355@geindex Pre-elaboration requirements
15356
15357@node RM C 4 14 Pre-elaboration Requirements,RM C 5 8 Pragma Discard_Names,RM C 3 2 25 Package Interrupts,Implementation Advice
15358@anchor{gnat_rm/implementation_advice rm-c-4-14-pre-elaboration-requirements}@anchor{249}
15359@section RM C.4(14): Pre-elaboration Requirements
15360
15361
15362@quotation
15363
15364“It is recommended that pre-elaborated packages be implemented in such a
15365way that there should be little or no code executed at run time for the
15366elaboration of entities not already covered by the Implementation
15367Requirements.”
15368@end quotation
15369
15370Followed.  Executable code is generated in some cases, e.g., loops
15371to initialize large arrays.
15372
15373@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
15374@anchor{gnat_rm/implementation_advice rm-c-5-8-pragma-discard-names}@anchor{24a}
15375@section RM C.5(8): Pragma @code{Discard_Names}
15376
15377
15378@quotation
15379
15380“If the pragma applies to an entity, then the implementation should
15381reduce the amount of storage used for storing names associated with that
15382entity.”
15383@end quotation
15384
15385Followed.
15386
15387@geindex Package Task_Attributes
15388
15389@geindex Task_Attributes
15390
15391@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
15392@anchor{gnat_rm/implementation_advice rm-c-7-2-30-the-package-task-attributes}@anchor{24b}
15393@section RM C.7.2(30): The Package Task_Attributes
15394
15395
15396@quotation
15397
15398“Some implementations are targeted to domains in which memory use at run
15399time must be completely deterministic.  For such implementations, it is
15400recommended that the storage for task attributes will be pre-allocated
15401statically and not from the heap.  This can be accomplished by either
15402placing restrictions on the number and the size of the task’s
15403attributes, or by using the pre-allocated storage for the first @code{N}
15404attribute objects, and the heap for the others.  In the latter case,
15405@code{N} should be documented.”
15406@end quotation
15407
15408Not followed.  This implementation is not targeted to such a domain.
15409
15410@geindex Locking Policies
15411
15412@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
15413@anchor{gnat_rm/implementation_advice rm-d-3-17-locking-policies}@anchor{24c}
15414@section RM D.3(17): Locking Policies
15415
15416
15417@quotation
15418
15419“The implementation should use names that end with @code{_Locking} for
15420locking policies defined by the implementation.”
15421@end quotation
15422
15423Followed.  Two implementation-defined locking policies are defined,
15424whose names (@code{Inheritance_Locking} and
15425@code{Concurrent_Readers_Locking}) follow this suggestion.
15426
15427@geindex Entry queuing policies
15428
15429@node RM D 4 16 Entry Queuing Policies,RM D 6 9-10 Preemptive Abort,RM D 3 17 Locking Policies,Implementation Advice
15430@anchor{gnat_rm/implementation_advice rm-d-4-16-entry-queuing-policies}@anchor{24d}
15431@section RM D.4(16): Entry Queuing Policies
15432
15433
15434@quotation
15435
15436“Names that end with @code{_Queuing} should be used
15437for all implementation-defined queuing policies.”
15438@end quotation
15439
15440Followed.  No such implementation-defined queuing policies exist.
15441
15442@geindex Preemptive abort
15443
15444@node RM D 6 9-10 Preemptive Abort,RM D 7 21 Tasking Restrictions,RM D 4 16 Entry Queuing Policies,Implementation Advice
15445@anchor{gnat_rm/implementation_advice rm-d-6-9-10-preemptive-abort}@anchor{24e}
15446@section RM D.6(9-10): Preemptive Abort
15447
15448
15449@quotation
15450
15451“Even though the @emph{abort_statement} is included in the list of
15452potentially blocking operations (see 9.5.1), it is recommended that this
15453statement be implemented in a way that never requires the task executing
15454the @emph{abort_statement} to block.”
15455@end quotation
15456
15457Followed.
15458
15459@quotation
15460
15461“On a multi-processor, the delay associated with aborting a task on
15462another processor should be bounded; the implementation should use
15463periodic polling, if necessary, to achieve this.”
15464@end quotation
15465
15466Followed.
15467
15468@geindex Tasking restrictions
15469
15470@node RM D 7 21 Tasking Restrictions,RM D 8 47-49 Monotonic Time,RM D 6 9-10 Preemptive Abort,Implementation Advice
15471@anchor{gnat_rm/implementation_advice rm-d-7-21-tasking-restrictions}@anchor{24f}
15472@section RM D.7(21): Tasking Restrictions
15473
15474
15475@quotation
15476
15477“When feasible, the implementation should take advantage of the specified
15478restrictions to produce a more efficient implementation.”
15479@end quotation
15480
15481GNAT currently takes advantage of these restrictions by providing an optimized
15482run time when the Ravenscar profile and the GNAT restricted run time set
15483of restrictions are specified.  See pragma @code{Profile (Ravenscar)} and
15484pragma @code{Profile (Restricted)} for more details.
15485
15486@geindex Time
15487@geindex monotonic
15488
15489@node RM D 8 47-49 Monotonic Time,RM E 5 28-29 Partition Communication Subsystem,RM D 7 21 Tasking Restrictions,Implementation Advice
15490@anchor{gnat_rm/implementation_advice rm-d-8-47-49-monotonic-time}@anchor{250}
15491@section RM D.8(47-49): Monotonic Time
15492
15493
15494@quotation
15495
15496“When appropriate, implementations should provide configuration
15497mechanisms to change the value of @code{Tick}.”
15498@end quotation
15499
15500Such configuration mechanisms are not appropriate to this implementation
15501and are thus not supported.
15502
15503@quotation
15504
15505“It is recommended that @code{Calendar.Clock} and @code{Real_Time.Clock}
15506be implemented as transformations of the same time base.”
15507@end quotation
15508
15509Followed.
15510
15511@quotation
15512
15513“It is recommended that the best time base which exists in
15514the underlying system be available to the application through
15515@code{Clock}.  @cite{Best} may mean highest accuracy or largest range.”
15516@end quotation
15517
15518Followed.
15519
15520@geindex Partition communication subsystem
15521
15522@geindex PCS
15523
15524@node RM E 5 28-29 Partition Communication Subsystem,RM F 7 COBOL Support,RM D 8 47-49 Monotonic Time,Implementation Advice
15525@anchor{gnat_rm/implementation_advice rm-e-5-28-29-partition-communication-subsystem}@anchor{251}
15526@section RM E.5(28-29): Partition Communication Subsystem
15527
15528
15529@quotation
15530
15531“Whenever possible, the PCS on the called partition should allow for
15532multiple tasks to call the RPC-receiver with different messages and
15533should allow them to block until the corresponding subprogram body
15534returns.”
15535@end quotation
15536
15537Followed by GLADE, a separately supplied PCS that can be used with
15538GNAT.
15539
15540@quotation
15541
15542“The @code{Write} operation on a stream of type @code{Params_Stream_Type}
15543should raise @code{Storage_Error} if it runs out of space trying to
15544write the @code{Item} into the stream.”
15545@end quotation
15546
15547Followed by GLADE, a separately supplied PCS that can be used with
15548GNAT.
15549
15550@geindex COBOL support
15551
15552@node RM F 7 COBOL Support,RM F 1 2 Decimal Radix Support,RM E 5 28-29 Partition Communication Subsystem,Implementation Advice
15553@anchor{gnat_rm/implementation_advice rm-f-7-cobol-support}@anchor{252}
15554@section RM F(7): COBOL Support
15555
15556
15557@quotation
15558
15559“If COBOL (respectively, C) is widely supported in the target
15560environment, implementations supporting the Information Systems Annex
15561should provide the child package @code{Interfaces.COBOL} (respectively,
15562@code{Interfaces.C}) specified in Annex B and should support a
15563@code{convention_identifier} of COBOL (respectively, C) in the interfacing
15564pragmas (see Annex B), thus allowing Ada programs to interface with
15565programs written in that language.”
15566@end quotation
15567
15568Followed.
15569
15570@geindex Decimal radix support
15571
15572@node RM F 1 2 Decimal Radix Support,RM G Numerics,RM F 7 COBOL Support,Implementation Advice
15573@anchor{gnat_rm/implementation_advice rm-f-1-2-decimal-radix-support}@anchor{253}
15574@section RM F.1(2): Decimal Radix Support
15575
15576
15577@quotation
15578
15579“Packed decimal should be used as the internal representation for objects
15580of subtype @code{S} when @code{S}’Machine_Radix = 10.”
15581@end quotation
15582
15583Not followed.  GNAT ignores @code{S}’Machine_Radix and always uses binary
15584representations.
15585
15586@geindex Numerics
15587
15588@node RM G Numerics,RM G 1 1 56-58 Complex Types,RM F 1 2 Decimal Radix Support,Implementation Advice
15589@anchor{gnat_rm/implementation_advice rm-g-numerics}@anchor{254}
15590@section RM G: Numerics
15591
15592
15593@quotation
15594
15595“If Fortran (respectively, C) is widely supported in the target
15596environment, implementations supporting the Numerics Annex
15597should provide the child package @code{Interfaces.Fortran} (respectively,
15598@code{Interfaces.C}) specified in Annex B and should support a
15599@code{convention_identifier} of Fortran (respectively, C) in the interfacing
15600pragmas (see Annex B), thus allowing Ada programs to interface with
15601programs written in that language.”
15602@end quotation
15603
15604Followed.
15605
15606@geindex Complex types
15607
15608@node RM G 1 1 56-58 Complex Types,RM G 1 2 49 Complex Elementary Functions,RM G Numerics,Implementation Advice
15609@anchor{gnat_rm/implementation_advice rm-g-1-1-56-58-complex-types}@anchor{255}
15610@section RM G.1.1(56-58): Complex Types
15611
15612
15613@quotation
15614
15615“Because the usual mathematical meaning of multiplication of a complex
15616operand and a real operand is that of the scaling of both components of
15617the former by the latter, an implementation should not perform this
15618operation by first promoting the real operand to complex type and then
15619performing a full complex multiplication.  In systems that, in the
15620future, support an Ada binding to IEC 559:1989, the latter technique
15621will not generate the required result when one of the components of the
15622complex operand is infinite.  (Explicit multiplication of the infinite
15623component by the zero component obtained during promotion yields a NaN
15624that propagates into the final result.) Analogous advice applies in the
15625case of multiplication of a complex operand and a pure-imaginary
15626operand, and in the case of division of a complex operand by a real or
15627pure-imaginary operand.”
15628@end quotation
15629
15630Not followed.
15631
15632@quotation
15633
15634“Similarly, because the usual mathematical meaning of addition of a
15635complex operand and a real operand is that the imaginary operand remains
15636unchanged, an implementation should not perform this operation by first
15637promoting the real operand to complex type and then performing a full
15638complex addition.  In implementations in which the @code{Signed_Zeros}
15639attribute of the component type is @code{True} (and which therefore
15640conform to IEC 559:1989 in regard to the handling of the sign of zero in
15641predefined arithmetic operations), the latter technique will not
15642generate the required result when the imaginary component of the complex
15643operand is a negatively signed zero.  (Explicit addition of the negative
15644zero to the zero obtained during promotion yields a positive zero.)
15645Analogous advice applies in the case of addition of a complex operand
15646and a pure-imaginary operand, and in the case of subtraction of a
15647complex operand and a real or pure-imaginary operand.”
15648@end quotation
15649
15650Not followed.
15651
15652@quotation
15653
15654“Implementations in which @code{Real'Signed_Zeros} is @code{True} should
15655attempt to provide a rational treatment of the signs of zero results and
15656result components.  As one example, the result of the @code{Argument}
15657function should have the sign of the imaginary component of the
15658parameter @code{X} when the point represented by that parameter lies on
15659the positive real axis; as another, the sign of the imaginary component
15660of the @code{Compose_From_Polar} function should be the same as
15661(respectively, the opposite of) that of the @code{Argument} parameter when that
15662parameter has a value of zero and the @code{Modulus} parameter has a
15663nonnegative (respectively, negative) value.”
15664@end quotation
15665
15666Followed.
15667
15668@geindex Complex elementary functions
15669
15670@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
15671@anchor{gnat_rm/implementation_advice rm-g-1-2-49-complex-elementary-functions}@anchor{256}
15672@section RM G.1.2(49): Complex Elementary Functions
15673
15674
15675@quotation
15676
15677“Implementations in which @code{Complex_Types.Real'Signed_Zeros} is
15678@code{True} should attempt to provide a rational treatment of the signs
15679of zero results and result components.  For example, many of the complex
15680elementary functions have components that are odd functions of one of
15681the parameter components; in these cases, the result component should
15682have the sign of the parameter component at the origin.  Other complex
15683elementary functions have zero components whose sign is opposite that of
15684a parameter component at the origin, or is always positive or always
15685negative.”
15686@end quotation
15687
15688Followed.
15689
15690@geindex Accuracy requirements
15691
15692@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
15693@anchor{gnat_rm/implementation_advice rm-g-2-4-19-accuracy-requirements}@anchor{257}
15694@section RM G.2.4(19): Accuracy Requirements
15695
15696
15697@quotation
15698
15699“The versions of the forward trigonometric functions without a
15700@code{Cycle} parameter should not be implemented by calling the
15701corresponding version with a @code{Cycle} parameter of
15702@code{2.0*Numerics.Pi}, since this will not provide the required
15703accuracy in some portions of the domain.  For the same reason, the
15704version of @code{Log} without a @code{Base} parameter should not be
15705implemented by calling the corresponding version with a @code{Base}
15706parameter of @code{Numerics.e}.”
15707@end quotation
15708
15709Followed.
15710
15711@geindex Complex arithmetic accuracy
15712
15713@geindex Accuracy
15714@geindex complex arithmetic
15715
15716@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
15717@anchor{gnat_rm/implementation_advice rm-g-2-6-15-complex-arithmetic-accuracy}@anchor{258}
15718@section RM G.2.6(15): Complex Arithmetic Accuracy
15719
15720
15721@quotation
15722
15723“The version of the @code{Compose_From_Polar} function without a
15724@code{Cycle} parameter should not be implemented by calling the
15725corresponding version with a @code{Cycle} parameter of
15726@code{2.0*Numerics.Pi}, since this will not provide the required
15727accuracy in some portions of the domain.”
15728@end quotation
15729
15730Followed.
15731
15732@geindex Sequential elaboration policy
15733
15734@node RM H 6 15/2 Pragma Partition_Elaboration_Policy,,RM G 2 6 15 Complex Arithmetic Accuracy,Implementation Advice
15735@anchor{gnat_rm/implementation_advice rm-h-6-15-2-pragma-partition-elaboration-policy}@anchor{259}
15736@section RM H.6(15/2): Pragma Partition_Elaboration_Policy
15737
15738
15739@quotation
15740
15741“If the partition elaboration policy is @code{Sequential} and the
15742Environment task becomes permanently blocked during elaboration then the
15743partition is deadlocked and it is recommended that the partition be
15744immediately terminated.”
15745@end quotation
15746
15747Not followed.
15748
15749@node Implementation Defined Characteristics,Intrinsic Subprograms,Implementation Advice,Top
15750@anchor{gnat_rm/implementation_defined_characteristics doc}@anchor{25a}@anchor{gnat_rm/implementation_defined_characteristics id1}@anchor{25b}@anchor{gnat_rm/implementation_defined_characteristics implementation-defined-characteristics}@anchor{b}
15751@chapter Implementation Defined Characteristics
15752
15753
15754In addition to the implementation dependent pragmas and attributes, and the
15755implementation advice, there are a number of other Ada features that are
15756potentially implementation dependent and are designated as
15757implementation-defined. These are mentioned throughout the Ada Reference
15758Manual, and are summarized in Annex M.
15759
15760A requirement for conforming Ada compilers is that they provide
15761documentation describing how the implementation deals with each of these
15762issues.  In this chapter you will find each point in Annex M listed,
15763followed by a description of how GNAT handles the implementation dependence.
15764
15765You can use this chapter as a guide to minimizing implementation
15766dependent features in your programs if portability to other compilers
15767and other operating systems is an important consideration.  The numbers
15768in each entry below correspond to the paragraph numbers in the Ada
15769Reference Manual.
15770
15771
15772@itemize *
15773
15774@item
15775“Whether or not each recommendation given in Implementation
15776Advice is followed.  See 1.1.2(37).”
15777@end itemize
15778
15779See @ref{a,,Implementation Advice}.
15780
15781
15782@itemize *
15783
15784@item
15785“Capacity limitations of the implementation.  See 1.1.3(3).”
15786@end itemize
15787
15788The complexity of programs that can be processed is limited only by the
15789total amount of available virtual memory, and disk space for the
15790generated object files.
15791
15792
15793@itemize *
15794
15795@item
15796“Variations from the standard that are impractical to avoid
15797given the implementation’s execution environment.  See 1.1.3(6).”
15798@end itemize
15799
15800There are no variations from the standard.
15801
15802
15803@itemize *
15804
15805@item
15806“Which code_statements cause external
15807interactions.  See 1.1.3(10).”
15808@end itemize
15809
15810Any @emph{code_statement} can potentially cause external interactions.
15811
15812
15813@itemize *
15814
15815@item
15816“The coded representation for the text of an Ada
15817program.  See 2.1(4).”
15818@end itemize
15819
15820See separate section on source representation.
15821
15822
15823@itemize *
15824
15825@item
15826
15827@table @asis
15828
15829@item “The semantics of an Ada program whose text is not in
15830
15831Normalization Form C.  See 2.1(4).”
15832@end table
15833@end itemize
15834
15835See separate section on source representation.
15836
15837
15838@itemize *
15839
15840@item
15841“The representation for an end of line.  See 2.2(2).”
15842@end itemize
15843
15844See separate section on source representation.
15845
15846
15847@itemize *
15848
15849@item
15850“Maximum supported line length and lexical element
15851length.  See 2.2(15).”
15852@end itemize
15853
15854The maximum line length is 255 characters and the maximum length of
15855a lexical element is also 255 characters. This is the default setting
15856if not overridden by the use of compiler switch @emph{-gnaty} (which
15857sets the maximum to 79) or @emph{-gnatyMnn} which allows the maximum
15858line length to be specified to be any value up to 32767. The maximum
15859length of a lexical element is the same as the maximum line length.
15860
15861
15862@itemize *
15863
15864@item
15865“Implementation defined pragmas.  See 2.8(14).”
15866@end itemize
15867
15868See @ref{7,,Implementation Defined Pragmas}.
15869
15870
15871@itemize *
15872
15873@item
15874“Effect of pragma @code{Optimize}.  See 2.8(27).”
15875@end itemize
15876
15877Pragma @code{Optimize}, if given with a @code{Time} or @code{Space}
15878parameter, checks that the optimization flag is set, and aborts if it is
15879not.
15880
15881
15882@itemize *
15883
15884@item
15885“The message string associated with the Assertion_Error exception raised
15886by the failure of a predicate check if there is no applicable
15887Predicate_Failure aspect.  See 3.2.4(31).”
15888@end itemize
15889
15890In the case of a Dynamic_Predicate aspect, the string is
15891“Dynamic_Predicate failed at <source position>”, where
15892“<source position>” might be something like “foo.adb:123”.
15893The Static_Predicate case is handled analogously.
15894
15895
15896@itemize *
15897
15898@item
15899“The predefined integer types declared in
15900@code{Standard}.  See 3.5.4(25).”
15901@end itemize
15902
15903
15904@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
15905@headitem
15906
15907Type
15908
15909@tab
15910
15911Representation
15912
15913@item
15914
15915@emph{Short_Short_Integer}
15916
15917@tab
15918
159198-bit signed
15920
15921@item
15922
15923@emph{Short_Integer}
15924
15925@tab
15926
1592716-bit signed
15928
15929@item
15930
15931@emph{Integer}
15932
15933@tab
15934
1593532-bit signed
15936
15937@item
15938
15939@emph{Long_Integer}
15940
15941@tab
15942
1594364-bit signed (on most 64-bit targets,
15944depending on the C definition of long)
1594532-bit signed (on all other targets)
15946
15947@item
15948
15949@emph{Long_Long_Integer}
15950
15951@tab
15952
1595364-bit signed
15954
15955@item
15956
15957@emph{Long_Long_Long_Integer}
15958
15959@tab
15960
15961128-bit signed (on 64-bit targets)
1596264-bit signed (on 32-bit targets)
15963
15964@end multitable
15965
15966
15967
15968@itemize *
15969
15970@item
15971“Any nonstandard integer types and the operators defined
15972for them.  See 3.5.4(26).”
15973@end itemize
15974
15975There are no nonstandard integer types.
15976
15977
15978@itemize *
15979
15980@item
15981“Any nonstandard real types and the operators defined for
15982them.  See 3.5.6(8).”
15983@end itemize
15984
15985There are no nonstandard real types.
15986
15987
15988@itemize *
15989
15990@item
15991“What combinations of requested decimal precision and range
15992are supported for floating point types.  See 3.5.7(7).”
15993@end itemize
15994
15995The precision and range are defined by the IEEE Standard for Floating-Point
15996Arithmetic (IEEE 754-2019).
15997
15998
15999@itemize *
16000
16001@item
16002“The predefined floating point types declared in
16003@code{Standard}.  See 3.5.7(16).”
16004@end itemize
16005
16006
16007@multitable {xxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
16008@headitem
16009
16010Type
16011
16012@tab
16013
16014Representation
16015
16016@item
16017
16018@emph{Short_Float}
16019
16020@tab
16021
16022IEEE Binary32 (Single)
16023
16024@item
16025
16026@emph{Float}
16027
16028@tab
16029
16030IEEE Binary32 (Single)
16031
16032@item
16033
16034@emph{Long_Float}
16035
16036@tab
16037
16038IEEE Binary64 (Double)
16039
16040@item
16041
16042@emph{Long_Long_Float}
16043
16044@tab
16045
16046IEEE Binary64 (Double) on non-x86 architectures
16047IEEE 80-bit Extended on x86 architecture
16048
16049@end multitable
16050
16051
16052The default rounding mode specified by the IEEE 754 Standard is assumed both
16053for static and dynamic computations (that is, round to nearest, ties to even).
16054The input routines yield correctly rounded values for Short_Float, Float, and
16055Long_Float at least. The output routines can compute up to twice as many exact
16056digits as the value of @code{T'Digits} for any type, for example 30 digits for
16057Long_Float; if more digits are requested, zeros are printed.
16058
16059
16060@itemize *
16061
16062@item
16063“The small of an ordinary fixed point type.  See 3.5.9(8).”
16064@end itemize
16065
16066The small is the largest power of two that does not exceed the delta.
16067
16068
16069@itemize *
16070
16071@item
16072“What combinations of small, range, and digits are
16073supported for fixed point types.  See 3.5.9(10).”
16074@end itemize
16075
16076For an ordinary fixed point type, on 32-bit platforms, the small must lie in
160772.0**(-80) .. 2.0**80 and the range in -9.0E+36 .. 9.0E+36; any combination
16078is permitted that does not result in a mantissa larger than 63 bits.
16079
16080On 64-bit platforms, the small must lie in 2.0**(-127) .. 2.0**127 and the
16081range in -1.0E+76 .. 1.0E+76; any combination is permitted that does not
16082result in a mantissa larger than 63 bits, and any combination is permitted
16083that results in a mantissa between 64 and 127 bits if the small is the
16084ratio of two integers that lie in 1 .. 2.0**127.
16085
16086If the small is the ratio of two integers with 64-bit magnitude on 32-bit
16087platforms and 128-bit magnitude on 64-bit platforms, which is the case if
16088no @code{small} clause is provided, then the operations of the fixed point
16089type are entirely implemented by means of integer instructions.  In the
16090other cases, some operations, in particular input and output, may be
16091implemented by means of floating-point instructions and may be affected
16092by accuracy issues on architectures other than x86.
16093
16094For a decimal fixed point type, on 32-bit platforms, the small must lie in
160951.0E-18 .. 1.0E+18 and the digits in 1 .. 18.  On 64-bit platforms, the
16096small must lie in 1.0E-38 .. 1.0E+38 and the digits in 1 .. 38.
16097
16098
16099@itemize *
16100
16101@item
16102“The result of @code{Tags.Expanded_Name} for types declared
16103within an unnamed @emph{block_statement}.  See 3.9(10).”
16104@end itemize
16105
16106Block numbers of the form @code{B@emph{nnn}}, where @emph{nnn} is a
16107decimal integer are allocated.
16108
16109
16110@itemize *
16111
16112@item
16113“The sequence of characters of the value returned by Tags.Expanded_Name
16114(respectively, Tags.Wide_Expanded_Name) when some of the graphic
16115characters of Tags.Wide_Wide_Expanded_Name are not defined in Character
16116(respectively, Wide_Character).  See 3.9(10.1).”
16117@end itemize
16118
16119This is handled in the same way as the implementation-defined behavior
16120referenced in A.4.12(34).
16121
16122
16123@itemize *
16124
16125@item
16126“Implementation-defined attributes.  See 4.1.4(12).”
16127@end itemize
16128
16129See @ref{8,,Implementation Defined Attributes}.
16130
16131
16132@itemize *
16133
16134@item
16135“The value of the parameter to Empty for some container aggregates.
16136See 4.3.5(40).”
16137@end itemize
16138
16139As per the suggestion given in the Annotated Ada RM, the default value
16140of the formal parameter is used if one exists and zero is used otherwise.
16141
16142
16143@itemize *
16144
16145@item
16146“The maximum number of chunks for a parallel reduction expression without
16147a chunk_specification.  See 4.5.10(21).”
16148@end itemize
16149
16150Feature unimplemented.
16151
16152
16153@itemize *
16154
16155@item
16156“Rounding of real static expressions which are exactly half-way between
16157two machine numbers.  See 4.9(38).”
16158@end itemize
16159
16160Round to even is used in all such cases.
16161
16162
16163@itemize *
16164
16165@item
16166
16167@table @asis
16168
16169@item “The maximum number of chunks for a parallel generalized iterator without
16170
16171a chunk_specification.  See 5.5.2(10).”
16172@end table
16173@end itemize
16174
16175Feature unimplemented.
16176
16177
16178@itemize *
16179
16180@item
16181“The number of chunks for an array component iterator.  See 5.5.2(11).”
16182@end itemize
16183
16184Feature unimplemented.
16185
16186
16187@itemize *
16188
16189@item
16190“Any extensions of the Global aspect.  See 6.1.2(43).”
16191@end itemize
16192
16193Feature unimplemented.
16194
16195
16196@itemize *
16197
16198@item
16199“The circumstances the implementation passes in the null value for a view
16200conversion of an access type used as an out parameter.  See 6.4.1(19).”
16201@end itemize
16202
16203Difficult to characterize.
16204
16205
16206@itemize *
16207
16208@item
16209“Any extensions of the Default_Initial_Condition aspect.  See 7.3.3(11).”
16210@end itemize
16211
16212SPARK allows specifying @emph{null} as the Default_Initial_Condition
16213aspect of a type. See the SPARK reference manual for further details.
16214
16215
16216@itemize *
16217
16218@item
16219“Any implementation-defined time types.  See 9.6(6).”
16220@end itemize
16221
16222There are no implementation-defined time types.
16223
16224
16225@itemize *
16226
16227@item
16228“The time base associated with relative delays.  See 9.6(20).”
16229@end itemize
16230
16231See 9.6(20).  The time base used is that provided by the C library
16232function @code{gettimeofday}.
16233
16234
16235@itemize *
16236
16237@item
16238“The time base of the type @code{Calendar.Time}.  See 9.6(23).”
16239@end itemize
16240
16241The time base used is that provided by the C library function
16242@code{gettimeofday}.
16243
16244
16245@itemize *
16246
16247@item
16248“The time zone used for package @code{Calendar}
16249operations.  See 9.6(24).”
16250@end itemize
16251
16252The time zone used by package @code{Calendar} is the current system time zone
16253setting for local time, as accessed by the C library function
16254@code{localtime}.
16255
16256
16257@itemize *
16258
16259@item
16260“Any limit on @emph{delay_until_statements} of
16261@emph{select_statements}.  See 9.6(29).”
16262@end itemize
16263
16264There are no such limits.
16265
16266
16267@itemize *
16268
16269@item
16270
16271@table @asis
16272
16273@item “The result of Calendar.Formatting.Image if its argument represents more
16274
16275than 100 hours.  See 9.6.1(86).”
16276@end table
16277@end itemize
16278
16279Calendar.Time_Error is raised.
16280
16281
16282@itemize *
16283
16284@item
16285“Implementation-defined conflict check policies.  See 9.10.1(5).”
16286@end itemize
16287
16288There are no implementation-defined conflict check policies.
16289
16290
16291@itemize *
16292
16293@item
16294“The representation for a compilation.  See 10.1(2).”
16295@end itemize
16296
16297A compilation is represented by a sequence of files presented to the
16298compiler in a single invocation of the @emph{gcc} command.
16299
16300
16301@itemize *
16302
16303@item
16304“Any restrictions on compilations that contain multiple
16305compilation_units.  See 10.1(4).”
16306@end itemize
16307
16308No single file can contain more than one compilation unit, but any
16309sequence of files can be presented to the compiler as a single
16310compilation.
16311
16312
16313@itemize *
16314
16315@item
16316“The mechanisms for creating an environment and for adding
16317and replacing compilation units.  See 10.1.4(3).”
16318@end itemize
16319
16320See separate section on compilation model.
16321
16322
16323@itemize *
16324
16325@item
16326“The manner of explicitly assigning library units to a
16327partition.  See 10.2(2).”
16328@end itemize
16329
16330If a unit contains an Ada main program, then the Ada units for the partition
16331are determined by recursive application of the rules in the Ada Reference
16332Manual section 10.2(2-6).  In other words, the Ada units will be those that
16333are needed by the main program, and then this definition of need is applied
16334recursively to those units, and the partition contains the transitive
16335closure determined by this relationship.  In short, all the necessary units
16336are included, with no need to explicitly specify the list.  If additional
16337units are required, e.g., by foreign language units, then all units must be
16338mentioned in the context clause of one of the needed Ada units.
16339
16340If the partition contains no main program, or if the main program is in
16341a language other than Ada, then GNAT
16342provides the binder options @emph{-z} and @emph{-n} respectively, and in
16343this case a list of units can be explicitly supplied to the binder for
16344inclusion in the partition (all units needed by these units will also
16345be included automatically).  For full details on the use of these
16346options, refer to @emph{GNAT Make Program gnatmake} in the
16347@cite{GNAT User’s Guide}.
16348
16349
16350@itemize *
16351
16352@item
16353“The implementation-defined means, if any, of specifying which compilation
16354units are needed by a given compilation unit.  See 10.2(2).”
16355@end itemize
16356
16357The units needed by a given compilation unit are as defined in
16358the Ada Reference Manual section 10.2(2-6).  There are no
16359implementation-defined pragmas or other implementation-defined
16360means for specifying needed units.
16361
16362
16363@itemize *
16364
16365@item
16366“The manner of designating the main subprogram of a
16367partition.  See 10.2(7).”
16368@end itemize
16369
16370The main program is designated by providing the name of the
16371corresponding @code{ALI} file as the input parameter to the binder.
16372
16373
16374@itemize *
16375
16376@item
16377“The order of elaboration of @emph{library_items}.  See 10.2(18).”
16378@end itemize
16379
16380The first constraint on ordering is that it meets the requirements of
16381Chapter 10 of the Ada Reference Manual.  This still leaves some
16382implementation-dependent choices, which are resolved by analyzing
16383the elaboration code of each unit and identifying implicit
16384elaboration-order dependencies.
16385
16386
16387@itemize *
16388
16389@item
16390“Parameter passing and function return for the main
16391subprogram.  See 10.2(21).”
16392@end itemize
16393
16394The main program has no parameters.  It may be a procedure, or a function
16395returning an integer type.  In the latter case, the returned integer
16396value is the return code of the program (overriding any value that
16397may have been set by a call to @code{Ada.Command_Line.Set_Exit_Status}).
16398
16399
16400@itemize *
16401
16402@item
16403“The mechanisms for building and running partitions.  See 10.2(24).”
16404@end itemize
16405
16406GNAT itself supports programs with only a single partition. The GNATDIST
16407tool provided with the GLADE package (which also includes an implementation
16408of the PCS) provides a completely flexible method for building and running
16409programs consisting of multiple partitions. See the separate GLADE manual
16410for details.
16411
16412
16413@itemize *
16414
16415@item
16416“The details of program execution, including program
16417termination.  See 10.2(25).”
16418@end itemize
16419
16420See separate section on compilation model.
16421
16422
16423@itemize *
16424
16425@item
16426“The semantics of any non-active partitions supported by the
16427implementation.  See 10.2(28).”
16428@end itemize
16429
16430Passive partitions are supported on targets where shared memory is
16431provided by the operating system. See the GLADE reference manual for
16432further details.
16433
16434
16435@itemize *
16436
16437@item
16438“The information returned by @code{Exception_Message}.  See 11.4.1(10).”
16439@end itemize
16440
16441Exception message returns the null string unless a specific message has
16442been passed by the program.
16443
16444
16445@itemize *
16446
16447@item
16448“The result of @code{Exceptions.Exception_Name} for types
16449declared within an unnamed @emph{block_statement}.  See 11.4.1(12).”
16450@end itemize
16451
16452Blocks have implementation defined names of the form @code{B@emph{nnn}}
16453where @emph{nnn} is an integer.
16454
16455
16456@itemize *
16457
16458@item
16459“The information returned by
16460@code{Exception_Information}.  See 11.4.1(13).”
16461@end itemize
16462
16463@code{Exception_Information} returns a string in the following format:
16464
16465@example
16466*Exception_Name:* nnnnn
16467*Message:* mmmmm
16468*PID:* ppp
16469*Load address:* 0xhhhh
16470*Call stack traceback locations:*
164710xhhhh 0xhhhh 0xhhhh ... 0xhhh
16472@end example
16473
16474where
16475
16476@quotation
16477
16478
16479@itemize *
16480
16481@item
16482@code{nnnn} is the fully qualified name of the exception in all upper
16483case letters. This line is always present.
16484
16485@item
16486@code{mmmm} is the message (this line present only if message is non-null)
16487
16488@item
16489@code{ppp} is the Process Id value as a decimal integer (this line is
16490present only if the Process Id is nonzero). Currently we are
16491not making use of this field.
16492
16493@item
16494The Load address line, the Call stack traceback locations line and the
16495following values are present only if at least one traceback location was
16496recorded. The Load address indicates the address at which the main executable
16497was loaded; this line may not be present if operating system hasn’t relocated
16498the main executable. The values are given in C style format, with lower case
16499letters for a-f, and only as many digits present as are necessary.
16500The line terminator sequence at the end of each line, including
16501the last line is a single @code{LF} character (@code{16#0A#}).
16502@end itemize
16503@end quotation
16504
16505
16506@itemize *
16507
16508@item
16509“The sequence of characters of the value returned by
16510Exceptions.Exception_Name (respectively, Exceptions.Wide_Exception_Name)
16511when some of the graphic characters of Exceptions.Wide_Wide_Exception_Name
16512are not defined in Character (respectively, Wide_Character).
16513See 11.4.1(12.1).”
16514@end itemize
16515
16516This is handled in the same way as the implementation-defined behavior
16517referenced in A.4.12(34).
16518
16519
16520@itemize *
16521
16522@item
16523“The information returned by Exception_Information.  See 11.4.1(13).”
16524@end itemize
16525
16526The exception name and the source location at which the exception was
16527raised are included.
16528
16529
16530@itemize *
16531
16532@item
16533“Implementation-defined policy_identifiers and assertion_aspect_marks
16534allowed in a pragma Assertion_Policy.  See 11.4.2(9).”
16535@end itemize
16536
16537Implementation-defined assertion_aspect_marks include Assert_And_Cut,
16538Assume, Contract_Cases, Debug, Ghost, Initial_Condition, Loop_Invariant,
16539Loop_Variant, Postcondition, Precondition, Predicate, Refined_Post,
16540Statement_Assertions, and Subprogram_Variant. Implementation-defined
16541policy_identifiers include Ignore and Suppressible.
16542
16543
16544@itemize *
16545
16546@item
16547“The default assertion policy.  See 11.4.2(10).”
16548@end itemize
16549
16550The default assertion policy is Ignore, although this can be overridden
16551via compiler switches such as “-gnata”.
16552
16553
16554@itemize *
16555
16556@item
16557“Implementation-defined check names.  See 11.5(27).”
16558@end itemize
16559
16560The implementation defined check names include Alignment_Check,
16561Atomic_Synchronization, Duplicated_Tag_Check, Container_Checks,
16562Tampering_Check, Predicate_Check, and Validity_Check. In addition, a user
16563program can add implementation-defined check names by means of the pragma
16564Check_Name. See the description of pragma @code{Suppress} for full details.
16565
16566
16567@itemize *
16568
16569@item
16570“Existence and meaning of second parameter of pragma Unsuppress.
16571See 11.5(27.1).”
16572@end itemize
16573
16574The legality rules for and semantics of the second parameter of pragma
16575Unsuppress match those for the second argument of pragma Suppress.
16576
16577
16578@itemize *
16579
16580@item
16581
16582@table @asis
16583
16584@item “The cases that cause conflicts between the representation of the
16585
16586ancestors of a type_declaration.  See 13.1(13.1).”
16587@end table
16588@end itemize
16589
16590No such cases exist.
16591
16592
16593@itemize *
16594
16595@item
16596“The interpretation of each representation aspect.  See 13.1(20).”
16597@end itemize
16598
16599See separate section on data representations.
16600
16601
16602@itemize *
16603
16604@item
16605“Any restrictions placed upon the specification of representation aspects.
16606See 13.1(20).”
16607@end itemize
16608
16609See separate section on data representations.
16610
16611
16612@itemize *
16613
16614@item
16615“Implementation-defined aspects, including the syntax for specifying
16616such aspects and the legality rules for such aspects.  See 13.1.1(38).”
16617@end itemize
16618
16619See @ref{121,,Implementation Defined Aspects}.
16620
16621
16622@itemize *
16623
16624@item
16625“The set of machine scalars.  See 13.3(8.1).”
16626@end itemize
16627
16628See separate section on data representations.
16629
16630
16631@itemize *
16632
16633@item
16634“The meaning of @code{Size} for indefinite subtypes.  See 13.3(48).”
16635@end itemize
16636
16637The Size attribute of an indefinite subtype is not less than the Size
16638attribute of any object of that type.
16639
16640
16641@itemize *
16642
16643@item
16644“The meaning of Object_Size for indefinite subtypes.  See 13.3(58).”
16645@end itemize
16646
16647The Object_Size attribute of an indefinite subtype is not less than the
16648Object_Size attribute of any object of that type.
16649
16650
16651@itemize *
16652
16653@item
16654“The default external representation for a type tag.  See 13.3(75).”
16655@end itemize
16656
16657The default external representation for a type tag is the fully expanded
16658name of the type in upper case letters.
16659
16660
16661@itemize *
16662
16663@item
16664“What determines whether a compilation unit is the same in
16665two different partitions.  See 13.3(76).”
16666@end itemize
16667
16668A compilation unit is the same in two different partitions if and only
16669if it derives from the same source file.
16670
16671
16672@itemize *
16673
16674@item
16675“Implementation-defined components.  See 13.5.1(15).”
16676@end itemize
16677
16678The only implementation defined component is the tag for a tagged type,
16679which contains a pointer to the dispatching table.
16680
16681
16682@itemize *
16683
16684@item
16685“If @code{Word_Size} = @code{Storage_Unit}, the default bit
16686ordering.  See 13.5.3(5).”
16687@end itemize
16688
16689@code{Word_Size} (32) is not the same as @code{Storage_Unit} (8) for this
16690implementation, so no non-default bit ordering is supported.  The default
16691bit ordering corresponds to the natural endianness of the target architecture.
16692
16693
16694@itemize *
16695
16696@item
16697“The contents of the visible part of package @code{System}.  See 13.7(2).”
16698@end itemize
16699
16700See the definition of package System in @code{system.ads}.
16701Note that two declarations are added to package System.
16702
16703@example
16704Max_Priority           : constant Positive := Priority'Last;
16705Max_Interrupt_Priority : constant Positive := Interrupt_Priority'Last;
16706@end example
16707
16708
16709@itemize *
16710
16711@item
16712“The range of Storage_Elements.Storage_Offset, the modulus of
16713Storage_Elements.Storage_Element, and the declaration of
16714Storage_Elements.Integer_Address.  See 13.7.1(11).”
16715@end itemize
16716
16717See the definition of package System.Storage_Elements in @code{s-stoele.ads}.
16718
16719
16720@itemize *
16721
16722@item
16723“The contents of the visible part of package @code{System.Machine_Code},
16724and the meaning of @emph{code_statements}.  See 13.8(7).”
16725@end itemize
16726
16727See the definition and documentation in file @code{s-maccod.ads}.
16728
16729
16730@itemize *
16731
16732@item
16733“The result of unchecked conversion for instances with scalar result
16734types whose result is not defined by the language.  See 13.9(11).”
16735@end itemize
16736
16737Unchecked conversion between types of the same size
16738results in an uninterpreted transmission of the bits from one type
16739to the other.  If the types are of unequal sizes, then in the case of
16740discrete types, a shorter source is first zero or sign extended as
16741necessary, and a shorter target is simply truncated on the left.
16742For all non-discrete types, the source is first copied if necessary
16743to ensure that the alignment requirements of the target are met, then
16744a pointer is constructed to the source value, and the result is obtained
16745by dereferencing this pointer after converting it to be a pointer to the
16746target type. Unchecked conversions where the target subtype is an
16747unconstrained array are not permitted. If the target alignment is
16748greater than the source alignment, then a copy of the result is
16749made with appropriate alignment
16750
16751
16752@itemize *
16753
16754@item
16755“The result of unchecked conversion for instances with nonscalar result
16756types whose result is not defined by the language.  See 13.9(11).”
16757@end itemize
16758
16759See preceding definition for the scalar result case.
16760
16761
16762@itemize *
16763
16764@item
16765“Whether or not the implementation provides user-accessible
16766names for the standard pool type(s).  See 13.11(17).”
16767@end itemize
16768
16769There are 3 different standard pools used by the compiler when
16770@code{Storage_Pool} is not specified depending whether the type is local
16771to a subprogram or defined at the library level and whether
16772@code{Storage_Size`@w{`}is specified or not. See documentation in the runtime
16773library units `@w{`}System.Pool_Global}, @code{System.Pool_Size} and
16774@code{System.Pool_Local} in files @code{s-poosiz.ads},
16775@code{s-pooglo.ads} and @code{s-pooloc.ads} for full details on the
16776default pools used.  All these pools are accessible by means of @cite{with}ing
16777these units.
16778
16779
16780@itemize *
16781
16782@item
16783“The meaning of @code{Storage_Size} when neither the Storage_Size nor the
16784Storage_Pool is specified for an access type.  See 13.11(18).”
16785@end itemize
16786
16787@code{Storage_Size} is measured in storage units, and refers to the
16788total space available for an access type collection, or to the primary
16789stack space for a task.
16790
16791
16792@itemize *
16793
16794@item
16795“The effect of specifying aspect Default_Storage_Pool on an instance
16796of a language-defined generic unit.  See 13.11.3(5).”
16797@end itemize
16798
16799Instances of language-defined generic units are treated the same as other
16800instances with respect to the Default_Storage_Pool aspect.
16801
16802
16803@itemize *
16804
16805@item
16806“Implementation-defined restrictions allowed in a pragma
16807@code{Restrictions}.  See 13.12(8.7).”
16808@end itemize
16809
16810See @ref{9,,Standard and Implementation Defined Restrictions}.
16811
16812
16813@itemize *
16814
16815@item
16816“The consequences of violating limitations on
16817@code{Restrictions} pragmas.  See 13.12(9).”
16818@end itemize
16819
16820Restrictions that can be checked at compile time are enforced at
16821compile time; violations are illegal. For other restrictions, any
16822violation during program execution results in erroneous execution.
16823
16824
16825@itemize *
16826
16827@item
16828“Implementation-defined usage profiles allowed in a pragma Profile.
16829See 13.12(15).”
16830@end itemize
16831
16832See @ref{7,,Implementation Defined Pragmas}.
16833
16834
16835@itemize *
16836
16837@item
16838“The contents of the stream elements read and written by the Read and
16839Write attributes of elementary types.  See 13.13.2(9).”
16840@end itemize
16841
16842The representation is the in-memory representation of the base type of
16843the type, using the number of bits corresponding to the
16844@code{type'Size} value, and the natural ordering of the machine.
16845
16846
16847@itemize *
16848
16849@item
16850“The names and characteristics of the numeric subtypes
16851declared in the visible part of package @code{Standard}.  See A.1(3).”
16852@end itemize
16853
16854See items describing the integer and floating-point types supported.
16855
16856
16857@itemize *
16858
16859@item
16860“The values returned by Strings.Hash.  See A.4.9(3).”
16861@end itemize
16862
16863This hash function has predictable collisions and is subject to
16864equivalent substring attacks. It is not suitable for construction of a
16865hash table keyed on possibly malicious user input.
16866
16867
16868@itemize *
16869
16870@item
16871“The value returned by a call to a Text_Buffer Get procedure if any
16872character in the returned sequence is not defined in Character.
16873See A.4.12(34).”
16874@end itemize
16875
16876The contents of a buffer is represented internally as a UTF_8 string.
16877The value return by Text_Buffer.Get is the result of passing that
16878UTF_8 string to UTF_Encoding.Strings.Decode.
16879
16880
16881@itemize *
16882
16883@item
16884“The value returned by a call to a Text_Buffer Wide_Get procedure if
16885any character in the returned sequence is not defined in Wide_Character.
16886See A.4.12(34).”
16887@end itemize
16888
16889The contents of a buffer is represented internally as a UTF_8 string.
16890The value return by Text_Buffer.Wide_Get is the result of passing that
16891UTF_8 string to UTF_Encoding.Wide_Strings.Decode.
16892
16893
16894@itemize *
16895
16896@item
16897“The accuracy actually achieved by the elementary
16898functions.  See A.5.1(1).”
16899@end itemize
16900
16901The elementary functions correspond to the functions available in the C
16902library.  Only fast math mode is implemented.
16903
16904
16905@itemize *
16906
16907@item
16908“The sign of a zero result from some of the operators or
16909functions in @code{Numerics.Generic_Elementary_Functions}, when
16910@code{Float_Type'Signed_Zeros} is @code{True}.  See A.5.1(46).”
16911@end itemize
16912
16913The sign of zeroes follows the requirements of the IEEE 754 standard on
16914floating-point.
16915
16916
16917@itemize *
16918
16919@item
16920“The value of
16921@code{Numerics.Float_Random.Max_Image_Width}.  See A.5.2(27).”
16922@end itemize
16923
16924Maximum image width is 6864, see library file @code{s-rannum.ads}.
16925
16926
16927@itemize *
16928
16929@item
16930“The value of
16931@code{Numerics.Discrete_Random.Max_Image_Width}.  See A.5.2(27).”
16932@end itemize
16933
16934Maximum image width is 6864, see library file @code{s-rannum.ads}.
16935
16936
16937@itemize *
16938
16939@item
16940“The string representation of a random number generator’s
16941state.  See A.5.2(38).”
16942@end itemize
16943
16944The value returned by the Image function is the concatenation of
16945the fixed-width decimal representations of the 624 32-bit integers
16946of the state vector.
16947
16948
16949@itemize *
16950
16951@item
16952“The values of the @code{Model_Mantissa},
16953@code{Model_Emin}, @code{Model_Epsilon}, @code{Model},
16954@code{Safe_First}, and @code{Safe_Last} attributes, if the Numerics
16955Annex is not supported.  See A.5.3(72).”
16956@end itemize
16957
16958Running the compiler with @emph{-gnatS} to produce a listing of package
16959@code{Standard} displays the values of these attributes.
16960
16961
16962@itemize *
16963
16964@item
16965“The value of @code{Buffer_Size} in @code{Storage_IO}.  See A.9(10).”
16966@end itemize
16967
16968All type representations are contiguous, and the @code{Buffer_Size} is
16969the value of @code{type'Size} rounded up to the next storage unit
16970boundary.
16971
16972
16973@itemize *
16974
16975@item
16976“External files for standard input, standard output, and
16977standard error See A.10(5).”
16978@end itemize
16979
16980These files are mapped onto the files provided by the C streams
16981libraries. See source file @code{i-cstrea.ads} for further details.
16982
16983
16984@itemize *
16985
16986@item
16987“The accuracy of the value produced by @code{Put}.  See A.10.9(36).”
16988@end itemize
16989
16990If more digits are requested in the output than are represented by the
16991precision of the value, zeroes are output in the corresponding least
16992significant digit positions.
16993
16994
16995@itemize *
16996
16997@item
16998“Current size for a stream file for which positioning is not supported.
16999See A.12.1(1.1).”
17000@end itemize
17001
17002Positioning is supported.
17003
17004
17005@itemize *
17006
17007@item
17008“The meaning of @code{Argument_Count}, @code{Argument}, and
17009@code{Command_Name}.  See A.15(1).”
17010@end itemize
17011
17012These are mapped onto the @code{argv} and @code{argc} parameters of the
17013main program in the natural manner.
17014
17015
17016@itemize *
17017
17018@item
17019“The interpretation of file names and directory names.  See A.16(46).”
17020@end itemize
17021
17022These names are interpreted consistently with the underlying file system.
17023
17024
17025@itemize *
17026
17027@item
17028“The maxium value for a file size in Directories.  See A.16(87).”
17029@end itemize
17030
17031Directories.File_Size’Last is equal to Long_Long_Integer’Last .
17032
17033
17034@itemize *
17035
17036@item
17037
17038@table @asis
17039
17040@item “The result for Directories.Size for a directory or special file.
17041
17042See A.16(93).”
17043@end table
17044@end itemize
17045
17046Name_Error is raised.
17047
17048
17049@itemize *
17050
17051@item
17052
17053@table @asis
17054
17055@item “The result for Directories.Modification_Time for a directory or special file.
17056
17057See A.16(93).”
17058@end table
17059@end itemize
17060
17061Name_Error is raised.
17062
17063
17064@itemize *
17065
17066@item
17067
17068@table @asis
17069
17070@item “The interpretation of a nonnull search pattern in Directories.
17071
17072See A.16(104).”
17073@end table
17074@end itemize
17075
17076When the @code{Pattern} parameter is not the null string, it is interpreted
17077according to the syntax of regular expressions as defined in the
17078@code{GNAT.Regexp} package.
17079
17080See @ref{25c,,GNAT.Regexp (g-regexp.ads)}.
17081
17082
17083@itemize *
17084
17085@item
17086
17087@table @asis
17088
17089@item “The results of a Directories search if the contents of the directory are
17090
17091altered while a search is in progress.  See A.16(110).”
17092@end table
17093@end itemize
17094
17095The effect of a call to Get_Next_Entry is determined by the current
17096state of the directory.
17097
17098
17099@itemize *
17100
17101@item
17102“The definition and meaning of an environment variable.  See A.17(1).”
17103@end itemize
17104
17105This definition is determined by the underlying operating system.
17106
17107
17108@itemize *
17109
17110@item
17111“The circumstances where an environment variable cannot be defined.
17112See A.17(16).”
17113
17114There are no such implementation-defined circumstances.
17115
17116@item
17117“Environment names for which Set has the effect of Clear.  See A.17(17).”
17118@end itemize
17119
17120There are no such names.
17121
17122
17123@itemize *
17124
17125@item
17126“The value of Containers.Hash_Type’Modulus. The value of
17127Containers.Count_Type’Last.  See A.18.1(7).”
17128@end itemize
17129
17130Containers.Hash_Type’Modulus is 2**32.
17131Containers.Count_Type’Last is 2**31 - 1.
17132
17133
17134@itemize *
17135
17136@item
17137“Implementation-defined convention names.  See B.1(11).”
17138@end itemize
17139
17140The following convention names are supported
17141
17142
17143@multitable {xxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
17144@headitem
17145
17146Convention Name
17147
17148@tab
17149
17150Interpretation
17151
17152@item
17153
17154@emph{Ada}
17155
17156@tab
17157
17158Ada
17159
17160@item
17161
17162@emph{Ada_Pass_By_Copy}
17163
17164@tab
17165
17166Allowed for any types except by-reference types such as limited
17167records. Compatible with convention Ada, but causes any parameters
17168with this convention to be passed by copy.
17169
17170@item
17171
17172@emph{Ada_Pass_By_Reference}
17173
17174@tab
17175
17176Allowed for any types except by-copy types such as scalars.
17177Compatible with convention Ada, but causes any parameters
17178with this convention to be passed by reference.
17179
17180@item
17181
17182@emph{Assembler}
17183
17184@tab
17185
17186Assembly language
17187
17188@item
17189
17190@emph{Asm}
17191
17192@tab
17193
17194Synonym for Assembler
17195
17196@item
17197
17198@emph{Assembly}
17199
17200@tab
17201
17202Synonym for Assembler
17203
17204@item
17205
17206@emph{C}
17207
17208@tab
17209
17210C
17211
17212@item
17213
17214@emph{C_Pass_By_Copy}
17215
17216@tab
17217
17218Allowed only for record types, like C, but also notes that record
17219is to be passed by copy rather than reference.
17220
17221@item
17222
17223@emph{COBOL}
17224
17225@tab
17226
17227COBOL
17228
17229@item
17230
17231@emph{C_Plus_Plus (or CPP)}
17232
17233@tab
17234
17235C++
17236
17237@item
17238
17239@emph{Default}
17240
17241@tab
17242
17243Treated the same as C
17244
17245@item
17246
17247@emph{External}
17248
17249@tab
17250
17251Treated the same as C
17252
17253@item
17254
17255@emph{Fortran}
17256
17257@tab
17258
17259Fortran
17260
17261@item
17262
17263@emph{Intrinsic}
17264
17265@tab
17266
17267For support of pragma @code{Import} with convention Intrinsic, see
17268separate section on Intrinsic Subprograms.
17269
17270@item
17271
17272@emph{Stdcall}
17273
17274@tab
17275
17276Stdcall (used for Windows implementations only).  This convention correspond
17277to the WINAPI (previously called Pascal convention) C/C++ convention under
17278Windows.  A routine with this convention cleans the stack before
17279exit. This pragma cannot be applied to a dispatching call.
17280
17281@item
17282
17283@emph{DLL}
17284
17285@tab
17286
17287Synonym for Stdcall
17288
17289@item
17290
17291@emph{Win32}
17292
17293@tab
17294
17295Synonym for Stdcall
17296
17297@item
17298
17299@emph{Stubbed}
17300
17301@tab
17302
17303Stubbed is a special convention used to indicate that the body of the
17304subprogram will be entirely ignored.  Any call to the subprogram
17305is converted into a raise of the @code{Program_Error} exception.  If a
17306pragma @code{Import} specifies convention @code{stubbed} then no body need
17307be present at all.  This convention is useful during development for the
17308inclusion of subprograms whose body has not yet been written.
17309In addition, all otherwise unrecognized convention names are also
17310treated as being synonymous with convention C.  In all implementations,
17311use of such other names results in a warning.
17312
17313@end multitable
17314
17315
17316
17317@itemize *
17318
17319@item
17320“The meaning of link names.  See B.1(36).”
17321@end itemize
17322
17323Link names are the actual names used by the linker.
17324
17325
17326@itemize *
17327
17328@item
17329“The manner of choosing link names when neither the link name nor the
17330address of an imported or exported entity is specified.  See B.1(36).”
17331@end itemize
17332
17333The default linker name is that which would be assigned by the relevant
17334external language, interpreting the Ada name as being in all lower case
17335letters.
17336
17337
17338@itemize *
17339
17340@item
17341“The effect of pragma @code{Linker_Options}.  See B.1(37).”
17342@end itemize
17343
17344The string passed to @code{Linker_Options} is presented uninterpreted as
17345an argument to the link command, unless it contains ASCII.NUL characters.
17346NUL characters if they appear act as argument separators, so for example
17347
17348@example
17349pragma Linker_Options ("-labc" & ASCII.NUL & "-ldef");
17350@end example
17351
17352causes two separate arguments @code{-labc} and @code{-ldef} to be passed to the
17353linker. The order of linker options is preserved for a given unit. The final
17354list of options passed to the linker is in reverse order of the elaboration
17355order. For example, linker options for a body always appear before the options
17356from the corresponding package spec.
17357
17358
17359@itemize *
17360
17361@item
17362“The contents of the visible part of package
17363@code{Interfaces} and its language-defined descendants.  See B.2(1).”
17364@end itemize
17365
17366See files with prefix @code{i-} in the distributed library.
17367
17368
17369@itemize *
17370
17371@item
17372“Implementation-defined children of package
17373@code{Interfaces}.  The contents of the visible part of package
17374@code{Interfaces}.  See B.2(11).”
17375@end itemize
17376
17377See files with prefix @code{i-} in the distributed library.
17378
17379
17380@itemize *
17381
17382@item
17383“The definitions of certain types and constants in Interfaces.C.
17384See B.3(41).”
17385@end itemize
17386
17387See source file @code{i-c.ads}.
17388
17389
17390@itemize *
17391
17392@item
17393“The types @code{Floating}, @code{Long_Floating},
17394@code{Binary}, @code{Long_Binary}, @code{Decimal_ Element}, and
17395@code{COBOL_Character}; and the initialization of the variables
17396@code{Ada_To_COBOL} and @code{COBOL_To_Ada}, in
17397@code{Interfaces.COBOL}.  See B.4(50).”
17398@end itemize
17399
17400
17401@multitable {xxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
17402@headitem
17403
17404COBOL
17405
17406@tab
17407
17408Ada
17409
17410@item
17411
17412@emph{Floating}
17413
17414@tab
17415
17416Float
17417
17418@item
17419
17420@emph{Long_Floating}
17421
17422@tab
17423
17424(Floating) Long_Float
17425
17426@item
17427
17428@emph{Binary}
17429
17430@tab
17431
17432Integer
17433
17434@item
17435
17436@emph{Long_Binary}
17437
17438@tab
17439
17440Long_Long_Integer
17441
17442@item
17443
17444@emph{Decimal_Element}
17445
17446@tab
17447
17448Character
17449
17450@item
17451
17452@emph{COBOL_Character}
17453
17454@tab
17455
17456Character
17457
17458@end multitable
17459
17460
17461For initialization, see the file @code{i-cobol.ads} in the distributed library.
17462
17463
17464@itemize *
17465
17466@item
17467“The types Fortran_Integer, Real, Double_Precision, and Character_Set
17468in Interfaces.Fortran.  See B.5(17).”
17469@end itemize
17470
17471See source file @code{i-fortra.ads}. These types are derived, respectively,
17472from Integer, Float, Long_Float, and Character.
17473
17474
17475@itemize *
17476
17477@item
17478“Implementation-defined intrinsic subprograms.  See C.1(1).”
17479@end itemize
17480
17481See separate section on Intrinsic Subprograms.
17482
17483
17484@itemize *
17485
17486@item
17487“Any restrictions on a protected procedure or its containing type when an
17488aspect Attach_handler or Interrupt_Handler is specified.  See C.3.1(17).”
17489@end itemize
17490
17491There are no such restrictions.
17492
17493
17494@itemize *
17495
17496@item
17497“Any other forms of interrupt handler supported by the Attach_Handler and
17498Interrupt_Handler aspects.  See C.3.1(19).”
17499@end itemize
17500
17501There are no such forms.
17502
17503
17504@itemize *
17505
17506@item
17507
17508@table @asis
17509
17510@item “The semantics of some attributes and functions of an entity for which
17511
17512aspect Discard_Names is True.  See C.5(7).”
17513@end table
17514@end itemize
17515
17516If Discard_Names is True for an enumeration type, the Image attribute
17517provides the image of the Pos of the literal, and Value accepts
17518Pos values.
17519
17520If both of the aspects`@w{`}Discard_Names`@w{`} and @code{No_Tagged_Streams} are true
17521for a tagged type, its Expanded_Name and External_Tag values are
17522empty strings. This is useful to avoid exposing entity names at binary
17523level.
17524
17525
17526@itemize *
17527
17528@item
17529“The modulus and size of Test_and_Set_Flag.  See C.6.3(8).”
17530@end itemize
17531
17532The modulus is 2**8. The size is 8.
17533
17534
17535@itemize *
17536
17537@item
17538“The value used to represent the set value for Atomic_Test_and_Set.
17539See C.6.3(10).”
17540@end itemize
17541
17542The value is 1.
17543
17544
17545@itemize *
17546
17547@item
17548“The result of the @code{Task_Identification.Image}
17549attribute.  See C.7.1(7).”
17550@end itemize
17551
17552The result of this attribute is a string that identifies
17553the object or component that denotes a given task. If a variable @code{Var}
17554has a task type, the image for this task will have the form @code{Var_@emph{XXXXXXXX}},
17555where the suffix @emph{XXXXXXXX}
17556is the hexadecimal representation of the virtual address of the corresponding
17557task control block. If the variable is an array of tasks, the image of each
17558task will have the form of an indexed component indicating the position of a
17559given task in the array, e.g., @code{Group(5)_@emph{XXXXXXX}}. If the task is a
17560component of a record, the image of the task will have the form of a selected
17561component. These rules are fully recursive, so that the image of a task that
17562is a subcomponent of a composite object corresponds to the expression that
17563designates this task.
17564
17565If a task is created by an allocator, its image depends on the context. If the
17566allocator is part of an object declaration, the rules described above are used
17567to construct its image, and this image is not affected by subsequent
17568assignments. If the allocator appears within an expression, the image
17569includes only the name of the task type.
17570
17571If the configuration pragma Discard_Names is present, or if the restriction
17572No_Implicit_Heap_Allocation is in effect,  the image reduces to
17573the numeric suffix, that is to say the hexadecimal representation of the
17574virtual address of the control block of the task.
17575
17576
17577@itemize *
17578
17579@item
17580“The value of @code{Current_Task} when in a protected entry
17581or interrupt handler.  See C.7.1(17).”
17582@end itemize
17583
17584Protected entries or interrupt handlers can be executed by any
17585convenient thread, so the value of @code{Current_Task} is undefined.
17586
17587
17588@itemize *
17589
17590@item
17591“Granularity of locking for Task_Attributes.  See C.7.2(16).”
17592@end itemize
17593
17594No locking is needed if the formal type Attribute has the size and
17595alignment of either Integer or System.Address and the bit representation
17596of Initial_Value is all zeroes. Otherwise, locking is performed.
17597
17598
17599@itemize *
17600
17601@item
17602“The declarations of @code{Any_Priority} and
17603@code{Priority}.  See D.1(11).”
17604@end itemize
17605
17606See declarations in file @code{system.ads}.
17607
17608
17609@itemize *
17610
17611@item
17612“Implementation-defined execution resources.  See D.1(15).”
17613@end itemize
17614
17615There are no implementation-defined execution resources.
17616
17617
17618@itemize *
17619
17620@item
17621“Whether, on a multiprocessor, a task that is waiting for
17622access to a protected object keeps its processor busy.  See D.2.1(3).”
17623@end itemize
17624
17625On a multi-processor, a task that is waiting for access to a protected
17626object does not keep its processor busy.
17627
17628
17629@itemize *
17630
17631@item
17632“The affect of implementation defined execution resources
17633on task dispatching.  See D.2.1(9).”
17634@end itemize
17635
17636Tasks map to threads in the threads package used by GNAT.  Where possible
17637and appropriate, these threads correspond to native threads of the
17638underlying operating system.
17639
17640
17641@itemize *
17642
17643@item
17644“Implementation-defined task dispatching policies.  See D.2.2(3).”
17645@end itemize
17646
17647There are no implementation-defined task dispatching policies.
17648
17649
17650@itemize *
17651
17652@item
17653“The value of Default_Quantum in Dispatching.Round_Robin.  See D.2.5(4).”
17654@end itemize
17655
17656The value is 10 milliseconds.
17657
17658
17659@itemize *
17660
17661@item
17662“Implementation-defined @emph{policy_identifiers} allowed
17663in a pragma @code{Locking_Policy}.  See D.3(4).”
17664@end itemize
17665
17666The two implementation defined policies permitted in GNAT are
17667@code{Inheritance_Locking} and  @code{Concurrent_Readers_Locking}. On
17668targets that support the @code{Inheritance_Locking} policy, locking is
17669implemented by inheritance, i.e., the task owning the lock operates
17670at a priority equal to the highest priority of any task currently
17671requesting the lock. On targets that support the
17672@code{Concurrent_Readers_Locking} policy, locking is implemented with a
17673read/write lock allowing multiple protected object functions to enter
17674concurrently.
17675
17676
17677@itemize *
17678
17679@item
17680“Default ceiling priorities.  See D.3(10).”
17681@end itemize
17682
17683The ceiling priority of protected objects of the type
17684@code{System.Interrupt_Priority'Last} as described in the Ada
17685Reference Manual D.3(10),
17686
17687
17688@itemize *
17689
17690@item
17691“The ceiling of any protected object used internally by
17692the implementation.  See D.3(16).”
17693@end itemize
17694
17695The ceiling priority of internal protected objects is
17696@code{System.Priority'Last}.
17697
17698
17699@itemize *
17700
17701@item
17702“Implementation-defined queuing policies.  See D.4(1).”
17703@end itemize
17704
17705There are no implementation-defined queuing policies.
17706
17707
17708@itemize *
17709
17710@item
17711“Implementation-defined admission policies.  See D.4.1(1).”
17712@end itemize
17713
17714There are no implementation-defined admission policies.
17715
17716
17717@itemize *
17718
17719@item
17720“Any operations that implicitly require heap storage
17721allocation.  See D.7(8).”
17722@end itemize
17723
17724The only operation that implicitly requires heap storage allocation is
17725task creation.
17726
17727
17728@itemize *
17729
17730@item
17731“When restriction No_Dynamic_CPU_Assignment applies to a partition, the
17732processor on which a task with a CPU value of a Not_A_Specific_CPU will
17733execute.  See D.7(10).”
17734@end itemize
17735
17736Unknown.
17737
17738
17739@itemize *
17740
17741@item
17742
17743@table @asis
17744
17745@item “When restriction No_Task_Termination applies to a partition, what happens
17746
17747when a task terminates.  See D.7(15.1).”
17748@end table
17749@end itemize
17750
17751Execution is erroneous in that case.
17752
17753
17754@itemize *
17755
17756@item
17757
17758@table @asis
17759
17760@item “The behavior when restriction Max_Storage_At_Blocking is violated.
17761
17762See D.7(17).”
17763@end table
17764@end itemize
17765
17766Execution is erroneous in that case.
17767
17768
17769@itemize *
17770
17771@item
17772“The behavior when restriction Max_Asynchronous_Select_Nesting is violated.
17773See D.7(18).”
17774@end itemize
17775
17776Execution is erroneous in that case.
17777
17778
17779@itemize *
17780
17781@item
17782“The behavior when restriction Max_Tasks is violated.  See D.7(19).”
17783@end itemize
17784
17785Execution is erroneous in that case.
17786
17787
17788@itemize *
17789
17790@item
17791
17792@table @asis
17793
17794@item “Whether the use of pragma Restrictions results in a reduction in program
17795
17796code or data size or execution time.  See D.7(20).”
17797
17798Yes it can, but the precise circumstances and properties of such reductions
17799are difficult to characterize.
17800@end table
17801
17802@item
17803“The value of Barrier_Limit’Last in Synchronous_Barriers.  See D.10.1(4).”
17804@end itemize
17805
17806Synchronous_Barriers.Barrier_Limit’Last is Integer’Last .
17807
17808
17809@itemize *
17810
17811@item
17812“When an aborted task that is waiting on a Synchronous_Barrier is aborted.
17813See D.10.1(13).”
17814@end itemize
17815
17816Difficult to characterize.
17817
17818
17819@itemize *
17820
17821@item
17822
17823@table @asis
17824
17825@item “The value of Min_Handler_Ceiling in Execution_Time.Group_Budgets.
17826
17827See D.14.2(7).”
17828@end table
17829@end itemize
17830
17831See source file @code{a-etgrbu.ads}.
17832
17833
17834@itemize *
17835
17836@item
17837“The value of CPU_Range’Last in System.Multiprocessors.  See D.16(4).”
17838@end itemize
17839
17840See source file @code{s-multip.ads}.
17841
17842
17843@itemize *
17844
17845@item
17846“The processor on which the environment task executes in the absence
17847of a value for the aspect CPU.  See D.16(13).”
17848@end itemize
17849
17850Unknown.
17851
17852
17853@itemize *
17854
17855@item
17856“The means for creating and executing distributed
17857programs.  See E(5).”
17858@end itemize
17859
17860The GLADE package provides a utility GNATDIST for creating and executing
17861distributed programs. See the GLADE reference manual for further details.
17862
17863
17864@itemize *
17865
17866@item
17867“Any events that can result in a partition becoming
17868inaccessible.  See E.1(7).”
17869@end itemize
17870
17871See the GLADE reference manual for full details on such events.
17872
17873
17874@itemize *
17875
17876@item
17877“The scheduling policies, treatment of priorities, and management of
17878shared resources between partitions in certain cases.  See E.1(11).”
17879@end itemize
17880
17881See the GLADE reference manual for full details on these aspects of
17882multi-partition execution.
17883
17884
17885@itemize *
17886
17887@item
17888“Whether the execution of the remote subprogram is
17889immediately aborted as a result of cancellation.  See E.4(13).”
17890@end itemize
17891
17892See the GLADE reference manual for details on the effect of abort in
17893a distributed application.
17894
17895
17896@itemize *
17897
17898@item
17899“The range of type System.RPC.Partition_Id.  See E.5(14).”
17900@end itemize
17901
17902System.RPC.Partion_ID’Last is Integer’Last. See source file @code{s-rpc.ads}.
17903
17904
17905@itemize *
17906
17907@item
17908“Implementation-defined interfaces in the PCS.  See E.5(26).”
17909@end itemize
17910
17911See the GLADE reference manual for a full description of all
17912implementation defined interfaces.
17913
17914
17915@itemize *
17916
17917@item
17918“The values of named numbers in the package
17919@code{Decimal}.  See F.2(7).”
17920@end itemize
17921
17922
17923@multitable {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxx}
17924@headitem
17925
17926Named Number
17927
17928@tab
17929
17930Value
17931
17932@item
17933
17934@emph{Max_Scale}
17935
17936@tab
17937
17938+18
17939
17940@item
17941
17942@emph{Min_Scale}
17943
17944@tab
17945
17946-18
17947
17948@item
17949
17950@emph{Min_Delta}
17951
17952@tab
17953
179541.0E-18
17955
17956@item
17957
17958@emph{Max_Delta}
17959
17960@tab
17961
179621.0E+18
17963
17964@item
17965
17966@emph{Max_Decimal_Digits}
17967
17968@tab
17969
1797018
17971
17972@end multitable
17973
17974
17975
17976@itemize *
17977
17978@item
17979“The value of @code{Max_Picture_Length} in the package
17980@code{Text_IO.Editing}.  See F.3.3(16).”
17981@end itemize
17982
1798364
17984
17985
17986@itemize *
17987
17988@item
17989“The value of @code{Max_Picture_Length} in the package
17990@code{Wide_Text_IO.Editing}.  See F.3.4(5).”
17991@end itemize
17992
1799364
17994
17995
17996@itemize *
17997
17998@item
17999“The accuracy actually achieved by the complex elementary
18000functions and by other complex arithmetic operations.  See G.1(1).”
18001@end itemize
18002
18003Standard library functions are used for the complex arithmetic
18004operations.  Only fast math mode is currently supported.
18005
18006
18007@itemize *
18008
18009@item
18010“The sign of a zero result (or a component thereof) from
18011any operator or function in @code{Numerics.Generic_Complex_Types}, when
18012@code{Real'Signed_Zeros} is True.  See G.1.1(53).”
18013@end itemize
18014
18015The signs of zero values are as recommended by the relevant
18016implementation advice.
18017
18018
18019@itemize *
18020
18021@item
18022“The sign of a zero result (or a component thereof) from
18023any operator or function in
18024@code{Numerics.Generic_Complex_Elementary_Functions}, when
18025@code{Real'Signed_Zeros} is @code{True}.  See G.1.2(45).”
18026@end itemize
18027
18028The signs of zero values are as recommended by the relevant
18029implementation advice.
18030
18031
18032@itemize *
18033
18034@item
18035“Whether the strict mode or the relaxed mode is the
18036default.  See G.2(2).”
18037@end itemize
18038
18039The strict mode is the default.  There is no separate relaxed mode.  GNAT
18040provides a highly efficient implementation of strict mode.
18041
18042
18043@itemize *
18044
18045@item
18046“The result interval in certain cases of fixed-to-float
18047conversion.  See G.2.1(10).”
18048@end itemize
18049
18050For cases where the result interval is implementation dependent, the
18051accuracy is that provided by performing all operations in 64-bit IEEE
18052floating-point format.
18053
18054
18055@itemize *
18056
18057@item
18058“The result of a floating point arithmetic operation in
18059overflow situations, when the @code{Machine_Overflows} attribute of the
18060result type is @code{False}.  See G.2.1(13).”
18061@end itemize
18062
18063Infinite and NaN values are produced as dictated by the IEEE
18064floating-point standard.
18065Note that on machines that are not fully compliant with the IEEE
18066floating-point standard, such as Alpha, the @emph{-mieee} compiler flag
18067must be used for achieving IEEE conforming behavior (although at the cost
18068of a significant performance penalty), so infinite and NaN values are
18069properly generated.
18070
18071
18072@itemize *
18073
18074@item
18075“The result interval for division (or exponentiation by a
18076negative exponent), when the floating point hardware implements division
18077as multiplication by a reciprocal.  See G.2.1(16).”
18078@end itemize
18079
18080Not relevant, division is IEEE exact.
18081
18082
18083@itemize *
18084
18085@item
18086“The definition of close result set, which determines the accuracy of
18087certain fixed point multiplications and divisions.  See G.2.3(5).”
18088@end itemize
18089
18090Operations in the close result set are performed using IEEE long format
18091floating-point arithmetic.  The input operands are converted to
18092floating-point, the operation is done in floating-point, and the result
18093is converted to the target type.
18094
18095
18096@itemize *
18097
18098@item
18099“Conditions on a @emph{universal_real} operand of a fixed
18100point multiplication or division for which the result shall be in the
18101perfect result set.  See G.2.3(22).”
18102@end itemize
18103
18104The result is only defined to be in the perfect result set if the result
18105can be computed by a single scaling operation involving a scale factor
18106representable in 64 bits.
18107
18108
18109@itemize *
18110
18111@item
18112“The result of a fixed point arithmetic operation in
18113overflow situations, when the @code{Machine_Overflows} attribute of the
18114result type is @code{False}.  See G.2.3(27).”
18115@end itemize
18116
18117Not relevant, @code{Machine_Overflows} is @code{True} for fixed-point
18118types.
18119
18120
18121@itemize *
18122
18123@item
18124“The result of an elementary function reference in
18125overflow situations, when the @code{Machine_Overflows} attribute of the
18126result type is @code{False}.  See G.2.4(4).”
18127@end itemize
18128
18129IEEE infinite and Nan values are produced as appropriate.
18130
18131
18132@itemize *
18133
18134@item
18135“The value of the angle threshold, within which certain
18136elementary functions, complex arithmetic operations, and complex
18137elementary functions yield results conforming to a maximum relative
18138error bound.  See G.2.4(10).”
18139@end itemize
18140
18141Information on this subject is not yet available.
18142
18143
18144@itemize *
18145
18146@item
18147“The accuracy of certain elementary functions for
18148parameters beyond the angle threshold.  See G.2.4(10).”
18149@end itemize
18150
18151Information on this subject is not yet available.
18152
18153
18154@itemize *
18155
18156@item
18157“The result of a complex arithmetic operation or complex
18158elementary function reference in overflow situations, when the
18159@code{Machine_Overflows} attribute of the corresponding real type is
18160@code{False}.  See G.2.6(5).”
18161@end itemize
18162
18163IEEE infinite and Nan values are produced as appropriate.
18164
18165
18166@itemize *
18167
18168@item
18169“The accuracy of certain complex arithmetic operations and
18170certain complex elementary functions for parameters (or components
18171thereof) beyond the angle threshold.  See G.2.6(8).”
18172@end itemize
18173
18174Information on those subjects is not yet available.
18175
18176
18177@itemize *
18178
18179@item
18180
18181@table @asis
18182
18183@item “The accuracy requirements for the subprograms Solve, Inverse,
18184
18185Determinant, Eigenvalues and Eigensystem for type Real_Matrix.
18186See G.3.1(81).”
18187@end table
18188@end itemize
18189
18190Information on those subjects is not yet available.
18191
18192
18193@itemize *
18194
18195@item
18196
18197@table @asis
18198
18199@item “The accuracy requirements for the subprograms Solve, Inverse,
18200
18201Determinant, Eigenvalues and Eigensystem for type Complex_Matrix.
18202See G.3.2(149).”
18203@end table
18204@end itemize
18205
18206Information on those subjects is not yet available.
18207
18208
18209@itemize *
18210
18211@item
18212“The consequences of violating No_Hidden_Indirect_Globals.  See H.4(23.9).”
18213@end itemize
18214
18215Execution is erroneous in that case.
18216
18217@node Intrinsic Subprograms,Representation Clauses and Pragmas,Implementation Defined Characteristics,Top
18218@anchor{gnat_rm/intrinsic_subprograms doc}@anchor{25d}@anchor{gnat_rm/intrinsic_subprograms id1}@anchor{25e}@anchor{gnat_rm/intrinsic_subprograms intrinsic-subprograms}@anchor{c}
18219@chapter Intrinsic Subprograms
18220
18221
18222@geindex Intrinsic Subprograms
18223
18224GNAT allows a user application program to write the declaration:
18225
18226@example
18227pragma Import (Intrinsic, name);
18228@end example
18229
18230providing that the name corresponds to one of the implemented intrinsic
18231subprograms in GNAT, and that the parameter profile of the referenced
18232subprogram meets the requirements.  This chapter describes the set of
18233implemented intrinsic subprograms, and the requirements on parameter profiles.
18234Note that no body is supplied; as with other uses of pragma Import, the
18235body is supplied elsewhere (in this case by the compiler itself).  Note
18236that any use of this feature is potentially non-portable, since the
18237Ada standard does not require Ada compilers to implement this feature.
18238
18239@menu
18240* Intrinsic Operators::
18241* Compilation_ISO_Date::
18242* Compilation_Date::
18243* Compilation_Time::
18244* Enclosing_Entity::
18245* Exception_Information::
18246* Exception_Message::
18247* Exception_Name::
18248* File::
18249* Line::
18250* Shifts and Rotates::
18251* Source_Location::
18252
18253@end menu
18254
18255@node Intrinsic Operators,Compilation_ISO_Date,,Intrinsic Subprograms
18256@anchor{gnat_rm/intrinsic_subprograms id2}@anchor{25f}@anchor{gnat_rm/intrinsic_subprograms intrinsic-operators}@anchor{260}
18257@section Intrinsic Operators
18258
18259
18260@geindex Intrinsic operator
18261
18262All the predefined numeric operators in package Standard
18263in @code{pragma Import (Intrinsic,..)}
18264declarations.  In the binary operator case, the operands must have the same
18265size.  The operand or operands must also be appropriate for
18266the operator.  For example, for addition, the operands must
18267both be floating-point or both be fixed-point, and the
18268right operand for @code{"**"} must have a root type of
18269@code{Standard.Integer'Base}.
18270You can use an intrinsic operator declaration as in the following example:
18271
18272@example
18273type Int1 is new Integer;
18274type Int2 is new Integer;
18275
18276function "+" (X1 : Int1; X2 : Int2) return Int1;
18277function "+" (X1 : Int1; X2 : Int2) return Int2;
18278pragma Import (Intrinsic, "+");
18279@end example
18280
18281This declaration would permit ‘mixed mode’ arithmetic on items
18282of the differing types @code{Int1} and @code{Int2}.
18283It is also possible to specify such operators for private types, if the
18284full views are appropriate arithmetic types.
18285
18286@node Compilation_ISO_Date,Compilation_Date,Intrinsic Operators,Intrinsic Subprograms
18287@anchor{gnat_rm/intrinsic_subprograms compilation-iso-date}@anchor{261}@anchor{gnat_rm/intrinsic_subprograms id3}@anchor{262}
18288@section Compilation_ISO_Date
18289
18290
18291@geindex Compilation_ISO_Date
18292
18293This intrinsic subprogram is used in the implementation of the
18294library package @code{GNAT.Source_Info}.  The only useful use of the
18295intrinsic import in this case is the one in this unit, so an
18296application program should simply call the function
18297@code{GNAT.Source_Info.Compilation_ISO_Date} to obtain the date of
18298the current compilation (in local time format YYYY-MM-DD).
18299
18300@node Compilation_Date,Compilation_Time,Compilation_ISO_Date,Intrinsic Subprograms
18301@anchor{gnat_rm/intrinsic_subprograms compilation-date}@anchor{263}@anchor{gnat_rm/intrinsic_subprograms id4}@anchor{264}
18302@section Compilation_Date
18303
18304
18305@geindex Compilation_Date
18306
18307Same as Compilation_ISO_Date, except the string is in the form
18308MMM DD YYYY.
18309
18310@node Compilation_Time,Enclosing_Entity,Compilation_Date,Intrinsic Subprograms
18311@anchor{gnat_rm/intrinsic_subprograms compilation-time}@anchor{265}@anchor{gnat_rm/intrinsic_subprograms id5}@anchor{266}
18312@section Compilation_Time
18313
18314
18315@geindex Compilation_Time
18316
18317This intrinsic subprogram is used in the implementation of the
18318library package @code{GNAT.Source_Info}.  The only useful use of the
18319intrinsic import in this case is the one in this unit, so an
18320application program should simply call the function
18321@code{GNAT.Source_Info.Compilation_Time} to obtain the time of
18322the current compilation (in local time format HH:MM:SS).
18323
18324@node Enclosing_Entity,Exception_Information,Compilation_Time,Intrinsic Subprograms
18325@anchor{gnat_rm/intrinsic_subprograms enclosing-entity}@anchor{267}@anchor{gnat_rm/intrinsic_subprograms id6}@anchor{268}
18326@section Enclosing_Entity
18327
18328
18329@geindex Enclosing_Entity
18330
18331This intrinsic subprogram is used in the implementation of the
18332library package @code{GNAT.Source_Info}.  The only useful use of the
18333intrinsic import in this case is the one in this unit, so an
18334application program should simply call the function
18335@code{GNAT.Source_Info.Enclosing_Entity} to obtain the name of
18336the current subprogram, package, task, entry, or protected subprogram.
18337
18338@node Exception_Information,Exception_Message,Enclosing_Entity,Intrinsic Subprograms
18339@anchor{gnat_rm/intrinsic_subprograms exception-information}@anchor{269}@anchor{gnat_rm/intrinsic_subprograms id7}@anchor{26a}
18340@section Exception_Information
18341
18342
18343@geindex Exception_Information'
18344
18345This intrinsic subprogram is used in the implementation of the
18346library package @code{GNAT.Current_Exception}.  The only useful
18347use of the intrinsic import in this case is the one in this unit,
18348so an application program should simply call the function
18349@code{GNAT.Current_Exception.Exception_Information} to obtain
18350the exception information associated with the current exception.
18351
18352@node Exception_Message,Exception_Name,Exception_Information,Intrinsic Subprograms
18353@anchor{gnat_rm/intrinsic_subprograms exception-message}@anchor{26b}@anchor{gnat_rm/intrinsic_subprograms id8}@anchor{26c}
18354@section Exception_Message
18355
18356
18357@geindex Exception_Message
18358
18359This intrinsic subprogram is used in the implementation of the
18360library package @code{GNAT.Current_Exception}.  The only useful
18361use of the intrinsic import in this case is the one in this unit,
18362so an application program should simply call the function
18363@code{GNAT.Current_Exception.Exception_Message} to obtain
18364the message associated with the current exception.
18365
18366@node Exception_Name,File,Exception_Message,Intrinsic Subprograms
18367@anchor{gnat_rm/intrinsic_subprograms exception-name}@anchor{26d}@anchor{gnat_rm/intrinsic_subprograms id9}@anchor{26e}
18368@section Exception_Name
18369
18370
18371@geindex Exception_Name
18372
18373This intrinsic subprogram is used in the implementation of the
18374library package @code{GNAT.Current_Exception}.  The only useful
18375use of the intrinsic import in this case is the one in this unit,
18376so an application program should simply call the function
18377@code{GNAT.Current_Exception.Exception_Name} to obtain
18378the name of the current exception.
18379
18380@node File,Line,Exception_Name,Intrinsic Subprograms
18381@anchor{gnat_rm/intrinsic_subprograms file}@anchor{26f}@anchor{gnat_rm/intrinsic_subprograms id10}@anchor{270}
18382@section File
18383
18384
18385@geindex File
18386
18387This intrinsic subprogram is used in the implementation of the
18388library package @code{GNAT.Source_Info}.  The only useful use of the
18389intrinsic import in this case is the one in this unit, so an
18390application program should simply call the function
18391@code{GNAT.Source_Info.File} to obtain the name of the current
18392file.
18393
18394@node Line,Shifts and Rotates,File,Intrinsic Subprograms
18395@anchor{gnat_rm/intrinsic_subprograms id11}@anchor{271}@anchor{gnat_rm/intrinsic_subprograms line}@anchor{272}
18396@section Line
18397
18398
18399@geindex Line
18400
18401This intrinsic subprogram is used in the implementation of the
18402library package @code{GNAT.Source_Info}.  The only useful use of the
18403intrinsic import in this case is the one in this unit, so an
18404application program should simply call the function
18405@code{GNAT.Source_Info.Line} to obtain the number of the current
18406source line.
18407
18408@node Shifts and Rotates,Source_Location,Line,Intrinsic Subprograms
18409@anchor{gnat_rm/intrinsic_subprograms id12}@anchor{273}@anchor{gnat_rm/intrinsic_subprograms shifts-and-rotates}@anchor{274}
18410@section Shifts and Rotates
18411
18412
18413@geindex Shift_Left
18414
18415@geindex Shift_Right
18416
18417@geindex Shift_Right_Arithmetic
18418
18419@geindex Rotate_Left
18420
18421@geindex Rotate_Right
18422
18423In standard Ada, the shift and rotate functions are available only
18424for the predefined modular types in package @code{Interfaces}.  However, in
18425GNAT it is possible to define these functions for any integer
18426type (signed or modular), as in this example:
18427
18428@example
18429function Shift_Left
18430  (Value  : T;
18431   Amount : Natural) return T
18432with Import, Convention => Intrinsic;
18433@end example
18434
18435The function name must be one of
18436Shift_Left, Shift_Right, Shift_Right_Arithmetic, Rotate_Left, or
18437Rotate_Right. T must be an integer type. T’Size must be
184388, 16, 32 or 64 bits; if T is modular, the modulus
18439must be 2**8, 2**16, 2**32 or 2**64.
18440The result type must be the same as the type of @code{Value}.
18441The shift amount must be Natural.
18442The formal parameter names can be anything.
18443
18444A more convenient way of providing these shift operators is to use the
18445Provide_Shift_Operators pragma, which provides the function declarations and
18446corresponding pragma Import’s for all five shift functions. For signed types
18447the semantics of these operators is to interpret the bitwise result of the
18448corresponding operator for modular type. In particular, shifting a negative
18449number may change its sign bit to positive.
18450
18451@node Source_Location,,Shifts and Rotates,Intrinsic Subprograms
18452@anchor{gnat_rm/intrinsic_subprograms id13}@anchor{275}@anchor{gnat_rm/intrinsic_subprograms source-location}@anchor{276}
18453@section Source_Location
18454
18455
18456@geindex Source_Location
18457
18458This intrinsic subprogram is used in the implementation of the
18459library routine @code{GNAT.Source_Info}.  The only useful use of the
18460intrinsic import in this case is the one in this unit, so an
18461application program should simply call the function
18462@code{GNAT.Source_Info.Source_Location} to obtain the current
18463source file location.
18464
18465@node Representation Clauses and Pragmas,Standard Library Routines,Intrinsic Subprograms,Top
18466@anchor{gnat_rm/representation_clauses_and_pragmas doc}@anchor{277}@anchor{gnat_rm/representation_clauses_and_pragmas id1}@anchor{278}@anchor{gnat_rm/representation_clauses_and_pragmas representation-clauses-and-pragmas}@anchor{d}
18467@chapter Representation Clauses and Pragmas
18468
18469
18470@geindex Representation Clauses
18471
18472@geindex Representation Clause
18473
18474@geindex Representation Pragma
18475
18476@geindex Pragma
18477@geindex representation
18478
18479This section describes the representation clauses accepted by GNAT, and
18480their effect on the representation of corresponding data objects.
18481
18482GNAT fully implements Annex C (Systems Programming).  This means that all
18483the implementation advice sections in chapter 13 are fully implemented.
18484However, these sections only require a minimal level of support for
18485representation clauses.  GNAT provides much more extensive capabilities,
18486and this section describes the additional capabilities provided.
18487
18488@menu
18489* Alignment Clauses::
18490* Size Clauses::
18491* Storage_Size Clauses::
18492* Size of Variant Record Objects::
18493* Biased Representation::
18494* Value_Size and Object_Size Clauses::
18495* Component_Size Clauses::
18496* Bit_Order Clauses::
18497* Effect of Bit_Order on Byte Ordering::
18498* Pragma Pack for Arrays::
18499* Pragma Pack for Records::
18500* Record Representation Clauses::
18501* Handling of Records with Holes::
18502* Enumeration Clauses::
18503* Address Clauses::
18504* Use of Address Clauses for Memory-Mapped I/O::
18505* Effect of Convention on Representation::
18506* Conventions and Anonymous Access Types::
18507* Determining the Representations chosen by GNAT::
18508
18509@end menu
18510
18511@node Alignment Clauses,Size Clauses,,Representation Clauses and Pragmas
18512@anchor{gnat_rm/representation_clauses_and_pragmas alignment-clauses}@anchor{279}@anchor{gnat_rm/representation_clauses_and_pragmas id2}@anchor{27a}
18513@section Alignment Clauses
18514
18515
18516@geindex Alignment Clause
18517
18518GNAT requires that all alignment clauses specify 0 or a power of 2, and
18519all default alignments are always a power of 2. Specifying 0 is the
18520same as specifying 1.
18521
18522The default alignment values are as follows:
18523
18524
18525@itemize *
18526
18527@item
18528@emph{Elementary Types}.
18529
18530For elementary types, the alignment is the minimum of the actual size of
18531objects of the type divided by @code{Storage_Unit},
18532and the maximum alignment supported by the target.
18533(This maximum alignment is given by the GNAT-specific attribute
18534@code{Standard'Maximum_Alignment}; see @ref{18e,,Attribute Maximum_Alignment}.)
18535
18536@geindex Maximum_Alignment attribute
18537
18538For example, for type @code{Long_Float}, the object size is 8 bytes, and the
18539default alignment will be 8 on any target that supports alignments
18540this large, but on some targets, the maximum alignment may be smaller
18541than 8, in which case objects of type @code{Long_Float} will be maximally
18542aligned.
18543
18544@item
18545@emph{Arrays}.
18546
18547For arrays, the alignment is equal to the alignment of the component type
18548for the normal case where no packing or component size is given.  If the
18549array is packed, and the packing is effective (see separate section on
18550packed arrays), then the alignment will be either 4, 2, or 1 for long packed
18551arrays or arrays whose length is not known at compile time, depending on
18552whether the component size is divisible by 4, 2, or is odd.  For short packed
18553arrays, which are handled internally as modular types, the alignment
18554will be as described for elementary types, e.g. a packed array of length
1855531 bits will have an object size of four bytes, and an alignment of 4.
18556
18557@item
18558@emph{Records}.
18559
18560For the normal unpacked case, the alignment of a record is equal to
18561the maximum alignment of any of its components.  For tagged records, this
18562includes the implicit access type used for the tag.  If a pragma @code{Pack}
18563is used and all components are packable (see separate section on pragma
18564@code{Pack}), then the resulting alignment is 1, unless the layout of the
18565record makes it profitable to increase it.
18566
18567A special case is when:
18568
18569
18570@itemize *
18571
18572@item
18573the size of the record is given explicitly, or a
18574full record representation clause is given, and
18575
18576@item
18577the size of the record is 2, 4, or 8 bytes.
18578@end itemize
18579
18580In this case, an alignment is chosen to match the
18581size of the record. For example, if we have:
18582
18583@example
18584type Small is record
18585   A, B : Character;
18586end record;
18587for Small'Size use 16;
18588@end example
18589
18590then the default alignment of the record type @code{Small} is 2, not 1. This
18591leads to more efficient code when the record is treated as a unit, and also
18592allows the type to specified as @code{Atomic} on architectures requiring
18593strict alignment.
18594@end itemize
18595
18596An alignment clause may specify a larger alignment than the default value
18597up to some maximum value dependent on the target (obtainable by using the
18598attribute reference @code{Standard'Maximum_Alignment}). It may also specify
18599a smaller alignment than the default value for enumeration, integer and
18600fixed point types, as well as for record types, for example
18601
18602@example
18603type V is record
18604   A : Integer;
18605end record;
18606
18607for V'alignment use 1;
18608@end example
18609
18610@geindex Alignment
18611@geindex default
18612
18613The default alignment for the type @code{V} is 4, as a result of the
18614Integer field in the record, but it is permissible, as shown, to
18615override the default alignment of the record with a smaller value.
18616
18617@geindex Alignment
18618@geindex subtypes
18619
18620Note that according to the Ada standard, an alignment clause applies only
18621to the first named subtype. If additional subtypes are declared, then the
18622compiler is allowed to choose any alignment it likes, and there is no way
18623to control this choice. Consider:
18624
18625@example
18626type R is range 1 .. 10_000;
18627for R'Alignment use 1;
18628subtype RS is R range 1 .. 1000;
18629@end example
18630
18631The alignment clause specifies an alignment of 1 for the first named subtype
18632@code{R} but this does not necessarily apply to @code{RS}. When writing
18633portable Ada code, you should avoid writing code that explicitly or
18634implicitly relies on the alignment of such subtypes.
18635
18636For the GNAT compiler, if an explicit alignment clause is given, this
18637value is also used for any subsequent subtypes. So for GNAT, in the
18638above example, you can count on the alignment of @code{RS} being 1. But this
18639assumption is non-portable, and other compilers may choose different
18640alignments for the subtype @code{RS}.
18641
18642@node Size Clauses,Storage_Size Clauses,Alignment Clauses,Representation Clauses and Pragmas
18643@anchor{gnat_rm/representation_clauses_and_pragmas id3}@anchor{27b}@anchor{gnat_rm/representation_clauses_and_pragmas size-clauses}@anchor{27c}
18644@section Size Clauses
18645
18646
18647@geindex Size Clause
18648
18649The default size for a type @code{T} is obtainable through the
18650language-defined attribute @code{T'Size} and also through the
18651equivalent GNAT-defined attribute @code{T'Value_Size}.
18652For objects of type @code{T}, GNAT will generally increase the type size
18653so that the object size (obtainable through the GNAT-defined attribute
18654@code{T'Object_Size})
18655is a multiple of @code{T'Alignment * Storage_Unit}.
18656
18657For example:
18658
18659@example
18660type Smallint is range 1 .. 6;
18661
18662type Rec is record
18663   Y1 : integer;
18664   Y2 : boolean;
18665end record;
18666@end example
18667
18668In this example, @code{Smallint'Size} = @code{Smallint'Value_Size} = 3,
18669as specified by the RM rules,
18670but objects of this type will have a size of 8
18671(@code{Smallint'Object_Size} = 8),
18672since objects by default occupy an integral number
18673of storage units.  On some targets, notably older
18674versions of the Digital Alpha, the size of stand
18675alone objects of this type may be 32, reflecting
18676the inability of the hardware to do byte load/stores.
18677
18678Similarly, the size of type @code{Rec} is 40 bits
18679(@code{Rec'Size} = @code{Rec'Value_Size} = 40), but
18680the alignment is 4, so objects of this type will have
18681their size increased to 64 bits so that it is a multiple
18682of the alignment (in bits).  This decision is
18683in accordance with the specific Implementation Advice in RM 13.3(43):
18684
18685@quotation
18686
18687“A @code{Size} clause should be supported for an object if the specified
18688@code{Size} is at least as large as its subtype’s @code{Size}, and corresponds
18689to a size in storage elements that is a multiple of the object’s
18690@code{Alignment} (if the @code{Alignment} is nonzero).”
18691@end quotation
18692
18693An explicit size clause may be used to override the default size by
18694increasing it.  For example, if we have:
18695
18696@example
18697type My_Boolean is new Boolean;
18698for My_Boolean'Size use 32;
18699@end example
18700
18701then values of this type will always be 32-bit long.  In the case of discrete
18702types, the size can be increased up to 64 bits on 32-bit targets and 128 bits
18703on 64-bit targets, with the effect that the entire specified field is used to
18704hold the value, sign- or zero-extended as appropriate.  If more than 64 bits
18705or 128 bits resp. is specified, then padding space is allocated after the
18706value, and a warning is issued that there are unused bits.
18707
18708Similarly the size of records and arrays may be increased, and the effect
18709is to add padding bits after the value.  This also causes a warning message
18710to be generated.
18711
18712The largest Size value permitted in GNAT is 2**31-1.  Since this is a
18713Size in bits, this corresponds to an object of size 256 megabytes (minus
18714one).  This limitation is true on all targets.  The reason for this
18715limitation is that it improves the quality of the code in many cases
18716if it is known that a Size value can be accommodated in an object of
18717type Integer.
18718
18719@node Storage_Size Clauses,Size of Variant Record Objects,Size Clauses,Representation Clauses and Pragmas
18720@anchor{gnat_rm/representation_clauses_and_pragmas id4}@anchor{27d}@anchor{gnat_rm/representation_clauses_and_pragmas storage-size-clauses}@anchor{27e}
18721@section Storage_Size Clauses
18722
18723
18724@geindex Storage_Size Clause
18725
18726For tasks, the @code{Storage_Size} clause specifies the amount of space
18727to be allocated for the task stack.  This cannot be extended, and if the
18728stack is exhausted, then @code{Storage_Error} will be raised (if stack
18729checking is enabled).  Use a @code{Storage_Size} attribute definition clause,
18730or a @code{Storage_Size} pragma in the task definition to set the
18731appropriate required size.  A useful technique is to include in every
18732task definition a pragma of the form:
18733
18734@example
18735pragma Storage_Size (Default_Stack_Size);
18736@end example
18737
18738Then @code{Default_Stack_Size} can be defined in a global package, and
18739modified as required. Any tasks requiring stack sizes different from the
18740default can have an appropriate alternative reference in the pragma.
18741
18742You can also use the @emph{-d} binder switch to modify the default stack
18743size.
18744
18745For access types, the @code{Storage_Size} clause specifies the maximum
18746space available for allocation of objects of the type.  If this space is
18747exceeded then @code{Storage_Error} will be raised by an allocation attempt.
18748In the case where the access type is declared local to a subprogram, the
18749use of a @code{Storage_Size} clause triggers automatic use of a special
18750predefined storage pool (@code{System.Pool_Size}) that ensures that all
18751space for the pool is automatically reclaimed on exit from the scope in
18752which the type is declared.
18753
18754A special case recognized by the compiler is the specification of a
18755@code{Storage_Size} of zero for an access type.  This means that no
18756items can be allocated from the pool, and this is recognized at compile
18757time, and all the overhead normally associated with maintaining a fixed
18758size storage pool is eliminated.  Consider the following example:
18759
18760@example
18761procedure p is
18762   type R is array (Natural) of Character;
18763   type P is access all R;
18764   for P'Storage_Size use 0;
18765   --  Above access type intended only for interfacing purposes
18766
18767   y : P;
18768
18769   procedure g (m : P);
18770   pragma Import (C, g);
18771
18772   --  ...
18773
18774begin
18775   --  ...
18776   y := new R;
18777end;
18778@end example
18779
18780As indicated in this example, these dummy storage pools are often useful in
18781connection with interfacing where no object will ever be allocated.  If you
18782compile the above example, you get the warning:
18783
18784@example
18785p.adb:16:09: warning: allocation from empty storage pool
18786p.adb:16:09: warning: Storage_Error will be raised at run time
18787@end example
18788
18789Of course in practice, there will not be any explicit allocators in the
18790case of such an access declaration.
18791
18792@node Size of Variant Record Objects,Biased Representation,Storage_Size Clauses,Representation Clauses and Pragmas
18793@anchor{gnat_rm/representation_clauses_and_pragmas id5}@anchor{27f}@anchor{gnat_rm/representation_clauses_and_pragmas size-of-variant-record-objects}@anchor{280}
18794@section Size of Variant Record Objects
18795
18796
18797@geindex Size
18798@geindex variant record objects
18799
18800@geindex Variant record objects
18801@geindex size
18802
18803In the case of variant record objects, there is a question whether Size gives
18804information about a particular variant, or the maximum size required
18805for any variant.  Consider the following program
18806
18807@example
18808with Text_IO; use Text_IO;
18809procedure q is
18810   type R1 (A : Boolean := False) is record
18811     case A is
18812       when True  => X : Character;
18813       when False => null;
18814     end case;
18815   end record;
18816
18817   V1 : R1 (False);
18818   V2 : R1;
18819
18820begin
18821   Put_Line (Integer'Image (V1'Size));
18822   Put_Line (Integer'Image (V2'Size));
18823end q;
18824@end example
18825
18826Here we are dealing with a variant record, where the True variant
18827requires 16 bits, and the False variant requires 8 bits.
18828In the above example, both V1 and V2 contain the False variant,
18829which is only 8 bits long.  However, the result of running the
18830program is:
18831
18832@example
188338
1883416
18835@end example
18836
18837The reason for the difference here is that the discriminant value of
18838V1 is fixed, and will always be False.  It is not possible to assign
18839a True variant value to V1, therefore 8 bits is sufficient.  On the
18840other hand, in the case of V2, the initial discriminant value is
18841False (from the default), but it is possible to assign a True
18842variant value to V2, therefore 16 bits must be allocated for V2
18843in the general case, even fewer bits may be needed at any particular
18844point during the program execution.
18845
18846As can be seen from the output of this program, the @code{'Size}
18847attribute applied to such an object in GNAT gives the actual allocated
18848size of the variable, which is the largest size of any of the variants.
18849The Ada Reference Manual is not completely clear on what choice should
18850be made here, but the GNAT behavior seems most consistent with the
18851language in the RM.
18852
18853In some cases, it may be desirable to obtain the size of the current
18854variant, rather than the size of the largest variant.  This can be
18855achieved in GNAT by making use of the fact that in the case of a
18856subprogram parameter, GNAT does indeed return the size of the current
18857variant (because a subprogram has no way of knowing how much space
18858is actually allocated for the actual).
18859
18860Consider the following modified version of the above program:
18861
18862@example
18863with Text_IO; use Text_IO;
18864procedure q is
18865   type R1 (A : Boolean := False) is record
18866     case A is
18867       when True  => X : Character;
18868       when False => null;
18869     end case;
18870   end record;
18871
18872   V2 : R1;
18873
18874   function Size (V : R1) return Integer is
18875   begin
18876      return V'Size;
18877   end Size;
18878
18879begin
18880   Put_Line (Integer'Image (V2'Size));
18881   Put_Line (Integer'Image (Size (V2)));
18882   V2 := (True, 'x');
18883   Put_Line (Integer'Image (V2'Size));
18884   Put_Line (Integer'Image (Size (V2)));
18885end q;
18886@end example
18887
18888The output from this program is
18889
18890@example
1889116
188928
1889316
1889416
18895@end example
18896
18897Here we see that while the @code{'Size} attribute always returns
18898the maximum size, regardless of the current variant value, the
18899@code{Size} function does indeed return the size of the current
18900variant value.
18901
18902@node Biased Representation,Value_Size and Object_Size Clauses,Size of Variant Record Objects,Representation Clauses and Pragmas
18903@anchor{gnat_rm/representation_clauses_and_pragmas biased-representation}@anchor{281}@anchor{gnat_rm/representation_clauses_and_pragmas id6}@anchor{282}
18904@section Biased Representation
18905
18906
18907@geindex Size for biased representation
18908
18909@geindex Biased representation
18910
18911In the case of scalars with a range starting at other than zero, it is
18912possible in some cases to specify a size smaller than the default minimum
18913value, and in such cases, GNAT uses an unsigned biased representation,
18914in which zero is used to represent the lower bound, and successive values
18915represent successive values of the type.
18916
18917For example, suppose we have the declaration:
18918
18919@example
18920type Small is range -7 .. -4;
18921for Small'Size use 2;
18922@end example
18923
18924Although the default size of type @code{Small} is 4, the @code{Size}
18925clause is accepted by GNAT and results in the following representation
18926scheme:
18927
18928@example
18929-7 is represented as 2#00#
18930-6 is represented as 2#01#
18931-5 is represented as 2#10#
18932-4 is represented as 2#11#
18933@end example
18934
18935Biased representation is only used if the specified @code{Size} clause
18936cannot be accepted in any other manner.  These reduced sizes that force
18937biased representation can be used for all discrete types except for
18938enumeration types for which a representation clause is given.
18939
18940@node Value_Size and Object_Size Clauses,Component_Size Clauses,Biased Representation,Representation Clauses and Pragmas
18941@anchor{gnat_rm/representation_clauses_and_pragmas id7}@anchor{283}@anchor{gnat_rm/representation_clauses_and_pragmas value-size-and-object-size-clauses}@anchor{284}
18942@section Value_Size and Object_Size Clauses
18943
18944
18945@geindex Value_Size
18946
18947@geindex Object_Size
18948
18949@geindex Size
18950@geindex of objects
18951
18952In Ada 95 and Ada 2005, @code{T'Size} for a type @code{T} is the minimum
18953number of bits required to hold values of type @code{T}.
18954Although this interpretation was allowed in Ada 83, it was not required,
18955and this requirement in practice can cause some significant difficulties.
18956For example, in most Ada 83 compilers, @code{Natural'Size} was 32.
18957However, in Ada 95 and Ada 2005,
18958@code{Natural'Size} is
18959typically 31.  This means that code may change in behavior when moving
18960from Ada 83 to Ada 95 or Ada 2005.  For example, consider:
18961
18962@example
18963type Rec is record;
18964   A : Natural;
18965   B : Natural;
18966end record;
18967
18968for Rec use record
18969   at 0  range 0 .. Natural'Size - 1;
18970   at 0  range Natural'Size .. 2 * Natural'Size - 1;
18971end record;
18972@end example
18973
18974In the above code, since the typical size of @code{Natural} objects
18975is 32 bits and @code{Natural'Size} is 31, the above code can cause
18976unexpected inefficient packing in Ada 95 and Ada 2005, and in general
18977there are cases where the fact that the object size can exceed the
18978size of the type causes surprises.
18979
18980To help get around this problem GNAT provides two implementation
18981defined attributes, @code{Value_Size} and @code{Object_Size}.  When
18982applied to a type, these attributes yield the size of the type
18983(corresponding to the RM defined size attribute), and the size of
18984objects of the type respectively.
18985
18986The @code{Object_Size} is used for determining the default size of
18987objects and components.  This size value can be referred to using the
18988@code{Object_Size} attribute.  The phrase ‘is used’ here means that it is
18989the basis of the determination of the size.  The backend is free to
18990pad this up if necessary for efficiency, e.g., an 8-bit stand-alone
18991character might be stored in 32 bits on a machine with no efficient
18992byte access instructions such as the Alpha.
18993
18994The default rules for the value of @code{Object_Size} for
18995discrete types are as follows:
18996
18997
18998@itemize *
18999
19000@item
19001The @code{Object_Size} for base subtypes reflect the natural hardware
19002size in bits (run the compiler with @emph{-gnatS} to find those values
19003for numeric types). Enumeration types and fixed-point base subtypes have
190048, 16, 32, or 64 bits for this size, depending on the range of values
19005to be stored.
19006
19007@item
19008The @code{Object_Size} of a subtype is the same as the
19009@code{Object_Size} of
19010the type from which it is obtained.
19011
19012@item
19013The @code{Object_Size} of a derived base type is copied from the parent
19014base type, and the @code{Object_Size} of a derived first subtype is copied
19015from the parent first subtype.
19016@end itemize
19017
19018The @code{Value_Size} attribute
19019is the (minimum) number of bits required to store a value
19020of the type.
19021This value is used to determine how tightly to pack
19022records or arrays with components of this type, and also affects
19023the semantics of unchecked conversion (unchecked conversions where
19024the @code{Value_Size} values differ generate a warning, and are potentially
19025target dependent).
19026
19027The default rules for the value of @code{Value_Size} are as follows:
19028
19029
19030@itemize *
19031
19032@item
19033The @code{Value_Size} for a base subtype is the minimum number of bits
19034required to store all values of the type (including the sign bit
19035only if negative values are possible).
19036
19037@item
19038If a subtype statically matches the first subtype of a given type, then it has
19039by default the same @code{Value_Size} as the first subtype.  This is a
19040consequence of RM 13.1(14): “if two subtypes statically match,
19041then their subtype-specific aspects are the same”.)
19042
19043@item
19044All other subtypes have a @code{Value_Size} corresponding to the minimum
19045number of bits required to store all values of the subtype.  For
19046dynamic bounds, it is assumed that the value can range down or up
19047to the corresponding bound of the ancestor
19048@end itemize
19049
19050The RM defined attribute @code{Size} corresponds to the
19051@code{Value_Size} attribute.
19052
19053The @code{Size} attribute may be defined for a first-named subtype.  This sets
19054the @code{Value_Size} of
19055the first-named subtype to the given value, and the
19056@code{Object_Size} of this first-named subtype to the given value padded up
19057to an appropriate boundary.  It is a consequence of the default rules
19058above that this @code{Object_Size} will apply to all further subtypes.  On the
19059other hand, @code{Value_Size} is affected only for the first subtype, any
19060dynamic subtypes obtained from it directly, and any statically matching
19061subtypes.  The @code{Value_Size} of any other static subtypes is not affected.
19062
19063@code{Value_Size} and
19064@code{Object_Size} may be explicitly set for any subtype using
19065an attribute definition clause.  Note that the use of these attributes
19066can cause the RM 13.1(14) rule to be violated.  If two access types
19067reference aliased objects whose subtypes have differing @code{Object_Size}
19068values as a result of explicit attribute definition clauses, then it
19069is illegal to convert from one access subtype to the other. For a more
19070complete description of this additional legality rule, see the
19071description of the @code{Object_Size} attribute.
19072
19073To get a feel for the difference, consider the following examples (note
19074that in each case the base is @code{Short_Short_Integer} with a size of 8):
19075
19076
19077@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxx}
19078@headitem
19079
19080Type or subtype declaration
19081
19082@tab
19083
19084Object_Size
19085
19086@tab
19087
19088Value_Size
19089
19090@item
19091
19092@code{type x1 is range 0 .. 5;}
19093
19094@tab
19095
190968
19097
19098@tab
19099
191003
19101
19102@item
19103
19104@code{type x2 is range 0 .. 5;}
19105@code{for x2'size use 12;}
19106
19107@tab
19108
1910916
19110
19111@tab
19112
1911312
19114
19115@item
19116
19117@code{subtype x3 is x2 range 0 .. 3;}
19118
19119@tab
19120
1912116
19122
19123@tab
19124
191252
19126
19127@item
19128
19129@code{subtype x4 is x2'base range 0 .. 10;}
19130
19131@tab
19132
191338
19134
19135@tab
19136
191374
19138
19139@item
19140
19141@code{dynamic : x2'Base range -64 .. +63;}
19142
19143@tab
19144
19145@tab
19146
19147@item
19148
19149@code{subtype x5 is x2 range 0 .. dynamic;}
19150
19151@tab
19152
1915316
19154
19155@tab
19156
191573*
19158
19159@item
19160
19161@code{subtype x6 is x2'base range 0 .. dynamic;}
19162
19163@tab
19164
191658
19166
19167@tab
19168
191697*
19170
19171@end multitable
19172
19173
19174Note: the entries marked ‘*’ are not actually specified by the Ada
19175Reference Manual, which has nothing to say about size in the dynamic
19176case. What GNAT does is to allocate sufficient bits to accommodate any
19177possible dynamic values for the bounds at run-time.
19178
19179So far, so good, but GNAT has to obey the RM rules, so the question is
19180under what conditions must the RM @code{Size} be used.
19181The following is a list
19182of the occasions on which the RM @code{Size} must be used:
19183
19184
19185@itemize *
19186
19187@item
19188Component size for packed arrays or records
19189
19190@item
19191Value of the attribute @code{Size} for a type
19192
19193@item
19194Warning about sizes not matching for unchecked conversion
19195@end itemize
19196
19197For record types, the @code{Object_Size} is always a multiple of the
19198alignment of the type (this is true for all types). In some cases the
19199@code{Value_Size} can be smaller. Consider:
19200
19201@example
19202type R is record
19203  X : Integer;
19204  Y : Character;
19205end record;
19206@end example
19207
19208On a typical 32-bit architecture, the X component will occupy four bytes
19209and the Y component will occupy one byte, for a total of 5 bytes. As a
19210result @code{R'Value_Size} will be 40 (bits) since this is the minimum size
19211required to store a value of this type. For example, it is permissible
19212to have a component of type R in an array whose component size is
19213specified to be 40 bits.
19214
19215However, @code{R'Object_Size} will be 64 (bits). The difference is due to
19216the alignment requirement for objects of the record type. The X
19217component will require four-byte alignment because that is what type
19218Integer requires, whereas the Y component, a Character, will only
19219require 1-byte alignment. Since the alignment required for X is the
19220greatest of all the components’ alignments, that is the alignment
19221required for the enclosing record type, i.e., 4 bytes or 32 bits. As
19222indicated above, the actual object size must be rounded up so that it is
19223a multiple of the alignment value. Therefore, 40 bits rounded up to the
19224next multiple of 32 yields 64 bits.
19225
19226For all other types, the @code{Object_Size}
19227and @code{Value_Size} are the same (and equivalent to the RM attribute @code{Size}).
19228Only @code{Size} may be specified for such types.
19229
19230Note that @code{Value_Size} can be used to force biased representation
19231for a particular subtype. Consider this example:
19232
19233@example
19234type R is (A, B, C, D, E, F);
19235subtype RAB is R range A .. B;
19236subtype REF is R range E .. F;
19237@end example
19238
19239By default, @code{RAB}
19240has a size of 1 (sufficient to accommodate the representation
19241of @code{A} and @code{B}, 0 and 1), and @code{REF}
19242has a size of 3 (sufficient to accommodate the representation
19243of @code{E} and @code{F}, 4 and 5). But if we add the
19244following @code{Value_Size} attribute definition clause:
19245
19246@example
19247for REF'Value_Size use 1;
19248@end example
19249
19250then biased representation is forced for @code{REF},
19251and 0 will represent @code{E} and 1 will represent @code{F}.
19252A warning is issued when a @code{Value_Size} attribute
19253definition clause forces biased representation. This
19254warning can be turned off using @code{-gnatw.B}.
19255
19256@node Component_Size Clauses,Bit_Order Clauses,Value_Size and Object_Size Clauses,Representation Clauses and Pragmas
19257@anchor{gnat_rm/representation_clauses_and_pragmas component-size-clauses}@anchor{285}@anchor{gnat_rm/representation_clauses_and_pragmas id8}@anchor{286}
19258@section Component_Size Clauses
19259
19260
19261@geindex Component_Size Clause
19262
19263Normally, the value specified in a component size clause must be consistent
19264with the subtype of the array component with regard to size and alignment.
19265In other words, the value specified must be at least equal to the size
19266of this subtype, and must be a multiple of the alignment value.
19267
19268In addition, component size clauses are allowed which cause the array
19269to be packed, by specifying a smaller value.  A first case is for
19270component size values in the range 1 through 63 on 32-bit targets,
19271and 1 through 127 on 64-bit targets.  The value specified may not
19272be smaller than the Size of the subtype.  GNAT will accurately
19273honor all packing requests in this range.  For example, if we have:
19274
19275@example
19276type r is array (1 .. 8) of Natural;
19277for r'Component_Size use 31;
19278@end example
19279
19280then the resulting array has a length of 31 bytes (248 bits = 8 * 31).
19281Of course access to the components of such an array is considerably
19282less efficient than if the natural component size of 32 is used.
19283A second case is when the subtype of the component is a record type
19284padded because of its default alignment.  For example, if we have:
19285
19286@example
19287type r is record
19288  i : Integer;
19289  j : Integer;
19290  b : Boolean;
19291end record;
19292
19293type a is array (1 .. 8) of r;
19294for a'Component_Size use 72;
19295@end example
19296
19297then the resulting array has a length of 72 bytes, instead of 96 bytes
19298if the alignment of the record (4) was obeyed.
19299
19300Note that there is no point in giving both a component size clause
19301and a pragma Pack for the same array type. if such duplicate
19302clauses are given, the pragma Pack will be ignored.
19303
19304@node Bit_Order Clauses,Effect of Bit_Order on Byte Ordering,Component_Size Clauses,Representation Clauses and Pragmas
19305@anchor{gnat_rm/representation_clauses_and_pragmas bit-order-clauses}@anchor{287}@anchor{gnat_rm/representation_clauses_and_pragmas id9}@anchor{288}
19306@section Bit_Order Clauses
19307
19308
19309@geindex Bit_Order Clause
19310
19311@geindex bit ordering
19312
19313@geindex ordering
19314@geindex of bits
19315
19316For record subtypes, GNAT permits the specification of the @code{Bit_Order}
19317attribute.  The specification may either correspond to the default bit
19318order for the target, in which case the specification has no effect and
19319places no additional restrictions, or it may be for the non-standard
19320setting (that is the opposite of the default).
19321
19322In the case where the non-standard value is specified, the effect is
19323to renumber bits within each byte, but the ordering of bytes is not
19324affected.  There are certain
19325restrictions placed on component clauses as follows:
19326
19327
19328@itemize *
19329
19330@item
19331Components fitting within a single storage unit.
19332
19333These are unrestricted, and the effect is merely to renumber bits.  For
19334example if we are on a little-endian machine with @code{Low_Order_First}
19335being the default, then the following two declarations have exactly
19336the same effect:
19337
19338@example
19339type R1 is record
19340   A : Boolean;
19341   B : Integer range 1 .. 120;
19342end record;
19343
19344for R1 use record
19345   A at 0 range 0 .. 0;
19346   B at 0 range 1 .. 7;
19347end record;
19348
19349type R2 is record
19350   A : Boolean;
19351   B : Integer range 1 .. 120;
19352end record;
19353
19354for R2'Bit_Order use High_Order_First;
19355
19356for R2 use record
19357   A at 0 range 7 .. 7;
19358   B at 0 range 0 .. 6;
19359end record;
19360@end example
19361
19362The useful application here is to write the second declaration with the
19363@code{Bit_Order} attribute definition clause, and know that it will be treated
19364the same, regardless of whether the target is little-endian or big-endian.
19365
19366@item
19367Components occupying an integral number of bytes.
19368
19369These are components that exactly fit in two or more bytes.  Such component
19370declarations are allowed, but have no effect, since it is important to realize
19371that the @code{Bit_Order} specification does not affect the ordering of bytes.
19372In particular, the following attempt at getting an endian-independent integer
19373does not work:
19374
19375@example
19376type R2 is record
19377   A : Integer;
19378end record;
19379
19380for R2'Bit_Order use High_Order_First;
19381
19382for R2 use record
19383   A at 0 range 0 .. 31;
19384end record;
19385@end example
19386
19387This declaration will result in a little-endian integer on a
19388little-endian machine, and a big-endian integer on a big-endian machine.
19389If byte flipping is required for interoperability between big- and
19390little-endian machines, this must be explicitly programmed.  This capability
19391is not provided by @code{Bit_Order}.
19392
19393@item
19394Components that are positioned across byte boundaries.
19395
19396but do not occupy an integral number of bytes.  Given that bytes are not
19397reordered, such fields would occupy a non-contiguous sequence of bits
19398in memory, requiring non-trivial code to reassemble.  They are for this
19399reason not permitted, and any component clause specifying such a layout
19400will be flagged as illegal by GNAT.
19401@end itemize
19402
19403Since the misconception that Bit_Order automatically deals with all
19404endian-related incompatibilities is a common one, the specification of
19405a component field that is an integral number of bytes will always
19406generate a warning.  This warning may be suppressed using @code{pragma Warnings (Off)}
19407if desired.  The following section contains additional
19408details regarding the issue of byte ordering.
19409
19410@node Effect of Bit_Order on Byte Ordering,Pragma Pack for Arrays,Bit_Order Clauses,Representation Clauses and Pragmas
19411@anchor{gnat_rm/representation_clauses_and_pragmas effect-of-bit-order-on-byte-ordering}@anchor{289}@anchor{gnat_rm/representation_clauses_and_pragmas id10}@anchor{28a}
19412@section Effect of Bit_Order on Byte Ordering
19413
19414
19415@geindex byte ordering
19416
19417@geindex ordering
19418@geindex of bytes
19419
19420In this section we will review the effect of the @code{Bit_Order} attribute
19421definition clause on byte ordering.  Briefly, it has no effect at all, but
19422a detailed example will be helpful.  Before giving this
19423example, let us review the precise
19424definition of the effect of defining @code{Bit_Order}.  The effect of a
19425non-standard bit order is described in section 13.5.3 of the Ada
19426Reference Manual:
19427
19428@quotation
19429
19430“2   A bit ordering is a method of interpreting the meaning of
19431the storage place attributes.”
19432@end quotation
19433
19434To understand the precise definition of storage place attributes in
19435this context, we visit section 13.5.1 of the manual:
19436
19437@quotation
19438
19439“13   A record_representation_clause (without the mod_clause)
19440specifies the layout.  The storage place attributes (see 13.5.2)
19441are taken from the values of the position, first_bit, and last_bit
19442expressions after normalizing those values so that first_bit is
19443less than Storage_Unit.”
19444@end quotation
19445
19446The critical point here is that storage places are taken from
19447the values after normalization, not before.  So the @code{Bit_Order}
19448interpretation applies to normalized values.  The interpretation
19449is described in the later part of the 13.5.3 paragraph:
19450
19451@quotation
19452
19453“2   A bit ordering is a method of interpreting the meaning of
19454the storage place attributes.  High_Order_First (known in the
19455vernacular as ‘big endian’) means that the first bit of a
19456storage element (bit 0) is the most significant bit (interpreting
19457the sequence of bits that represent a component as an unsigned
19458integer value).  Low_Order_First (known in the vernacular as
19459‘little endian’) means the opposite: the first bit is the
19460least significant.”
19461@end quotation
19462
19463Note that the numbering is with respect to the bits of a storage
19464unit.  In other words, the specification affects only the numbering
19465of bits within a single storage unit.
19466
19467We can make the effect clearer by giving an example.
19468
19469Suppose that we have an external device which presents two bytes, the first
19470byte presented, which is the first (low addressed byte) of the two byte
19471record is called Master, and the second byte is called Slave.
19472
19473The left most (most significant bit is called Control for each byte, and
19474the remaining 7 bits are called V1, V2, … V7, where V7 is the rightmost
19475(least significant) bit.
19476
19477On a big-endian machine, we can write the following representation clause
19478
19479@example
19480type Data is record
19481   Master_Control : Bit;
19482   Master_V1      : Bit;
19483   Master_V2      : Bit;
19484   Master_V3      : Bit;
19485   Master_V4      : Bit;
19486   Master_V5      : Bit;
19487   Master_V6      : Bit;
19488   Master_V7      : Bit;
19489   Slave_Control  : Bit;
19490   Slave_V1       : Bit;
19491   Slave_V2       : Bit;
19492   Slave_V3       : Bit;
19493   Slave_V4       : Bit;
19494   Slave_V5       : Bit;
19495   Slave_V6       : Bit;
19496   Slave_V7       : Bit;
19497end record;
19498
19499for Data use record
19500   Master_Control at 0 range 0 .. 0;
19501   Master_V1      at 0 range 1 .. 1;
19502   Master_V2      at 0 range 2 .. 2;
19503   Master_V3      at 0 range 3 .. 3;
19504   Master_V4      at 0 range 4 .. 4;
19505   Master_V5      at 0 range 5 .. 5;
19506   Master_V6      at 0 range 6 .. 6;
19507   Master_V7      at 0 range 7 .. 7;
19508   Slave_Control  at 1 range 0 .. 0;
19509   Slave_V1       at 1 range 1 .. 1;
19510   Slave_V2       at 1 range 2 .. 2;
19511   Slave_V3       at 1 range 3 .. 3;
19512   Slave_V4       at 1 range 4 .. 4;
19513   Slave_V5       at 1 range 5 .. 5;
19514   Slave_V6       at 1 range 6 .. 6;
19515   Slave_V7       at 1 range 7 .. 7;
19516end record;
19517@end example
19518
19519Now if we move this to a little endian machine, then the bit ordering within
19520the byte is backwards, so we have to rewrite the record rep clause as:
19521
19522@example
19523for Data use record
19524   Master_Control at 0 range 7 .. 7;
19525   Master_V1      at 0 range 6 .. 6;
19526   Master_V2      at 0 range 5 .. 5;
19527   Master_V3      at 0 range 4 .. 4;
19528   Master_V4      at 0 range 3 .. 3;
19529   Master_V5      at 0 range 2 .. 2;
19530   Master_V6      at 0 range 1 .. 1;
19531   Master_V7      at 0 range 0 .. 0;
19532   Slave_Control  at 1 range 7 .. 7;
19533   Slave_V1       at 1 range 6 .. 6;
19534   Slave_V2       at 1 range 5 .. 5;
19535   Slave_V3       at 1 range 4 .. 4;
19536   Slave_V4       at 1 range 3 .. 3;
19537   Slave_V5       at 1 range 2 .. 2;
19538   Slave_V6       at 1 range 1 .. 1;
19539   Slave_V7       at 1 range 0 .. 0;
19540end record;
19541@end example
19542
19543It is a nuisance to have to rewrite the clause, especially if
19544the code has to be maintained on both machines.  However,
19545this is a case that we can handle with the
19546@code{Bit_Order} attribute if it is implemented.
19547Note that the implementation is not required on byte addressed
19548machines, but it is indeed implemented in GNAT.
19549This means that we can simply use the
19550first record clause, together with the declaration
19551
19552@example
19553for Data'Bit_Order use High_Order_First;
19554@end example
19555
19556and the effect is what is desired, namely the layout is exactly the same,
19557independent of whether the code is compiled on a big-endian or little-endian
19558machine.
19559
19560The important point to understand is that byte ordering is not affected.
19561A @code{Bit_Order} attribute definition never affects which byte a field
19562ends up in, only where it ends up in that byte.
19563To make this clear, let us rewrite the record rep clause of the previous
19564example as:
19565
19566@example
19567for Data'Bit_Order use High_Order_First;
19568for Data use record
19569   Master_Control at 0 range  0 .. 0;
19570   Master_V1      at 0 range  1 .. 1;
19571   Master_V2      at 0 range  2 .. 2;
19572   Master_V3      at 0 range  3 .. 3;
19573   Master_V4      at 0 range  4 .. 4;
19574   Master_V5      at 0 range  5 .. 5;
19575   Master_V6      at 0 range  6 .. 6;
19576   Master_V7      at 0 range  7 .. 7;
19577   Slave_Control  at 0 range  8 .. 8;
19578   Slave_V1       at 0 range  9 .. 9;
19579   Slave_V2       at 0 range 10 .. 10;
19580   Slave_V3       at 0 range 11 .. 11;
19581   Slave_V4       at 0 range 12 .. 12;
19582   Slave_V5       at 0 range 13 .. 13;
19583   Slave_V6       at 0 range 14 .. 14;
19584   Slave_V7       at 0 range 15 .. 15;
19585end record;
19586@end example
19587
19588This is exactly equivalent to saying (a repeat of the first example):
19589
19590@example
19591for Data'Bit_Order use High_Order_First;
19592for Data use record
19593   Master_Control at 0 range 0 .. 0;
19594   Master_V1      at 0 range 1 .. 1;
19595   Master_V2      at 0 range 2 .. 2;
19596   Master_V3      at 0 range 3 .. 3;
19597   Master_V4      at 0 range 4 .. 4;
19598   Master_V5      at 0 range 5 .. 5;
19599   Master_V6      at 0 range 6 .. 6;
19600   Master_V7      at 0 range 7 .. 7;
19601   Slave_Control  at 1 range 0 .. 0;
19602   Slave_V1       at 1 range 1 .. 1;
19603   Slave_V2       at 1 range 2 .. 2;
19604   Slave_V3       at 1 range 3 .. 3;
19605   Slave_V4       at 1 range 4 .. 4;
19606   Slave_V5       at 1 range 5 .. 5;
19607   Slave_V6       at 1 range 6 .. 6;
19608   Slave_V7       at 1 range 7 .. 7;
19609end record;
19610@end example
19611
19612Why are they equivalent? Well take a specific field, the @code{Slave_V2}
19613field.  The storage place attributes are obtained by normalizing the
19614values given so that the @code{First_Bit} value is less than 8.  After
19615normalizing the values (0,10,10) we get (1,2,2) which is exactly what
19616we specified in the other case.
19617
19618Now one might expect that the @code{Bit_Order} attribute might affect
19619bit numbering within the entire record component (two bytes in this
19620case, thus affecting which byte fields end up in), but that is not
19621the way this feature is defined, it only affects numbering of bits,
19622not which byte they end up in.
19623
19624Consequently it never makes sense to specify a starting bit number
19625greater than 7 (for a byte addressable field) if an attribute
19626definition for @code{Bit_Order} has been given, and indeed it
19627may be actively confusing to specify such a value, so the compiler
19628generates a warning for such usage.
19629
19630If you do need to control byte ordering then appropriate conditional
19631values must be used.  If in our example, the slave byte came first on
19632some machines we might write:
19633
19634@example
19635Master_Byte_First constant Boolean := ...;
19636
19637Master_Byte : constant Natural :=
19638                1 - Boolean'Pos (Master_Byte_First);
19639Slave_Byte  : constant Natural :=
19640                Boolean'Pos (Master_Byte_First);
19641
19642for Data'Bit_Order use High_Order_First;
19643for Data use record
19644   Master_Control at Master_Byte range 0 .. 0;
19645   Master_V1      at Master_Byte range 1 .. 1;
19646   Master_V2      at Master_Byte range 2 .. 2;
19647   Master_V3      at Master_Byte range 3 .. 3;
19648   Master_V4      at Master_Byte range 4 .. 4;
19649   Master_V5      at Master_Byte range 5 .. 5;
19650   Master_V6      at Master_Byte range 6 .. 6;
19651   Master_V7      at Master_Byte range 7 .. 7;
19652   Slave_Control  at Slave_Byte  range 0 .. 0;
19653   Slave_V1       at Slave_Byte  range 1 .. 1;
19654   Slave_V2       at Slave_Byte  range 2 .. 2;
19655   Slave_V3       at Slave_Byte  range 3 .. 3;
19656   Slave_V4       at Slave_Byte  range 4 .. 4;
19657   Slave_V5       at Slave_Byte  range 5 .. 5;
19658   Slave_V6       at Slave_Byte  range 6 .. 6;
19659   Slave_V7       at Slave_Byte  range 7 .. 7;
19660end record;
19661@end example
19662
19663Now to switch between machines, all that is necessary is
19664to set the boolean constant @code{Master_Byte_First} in
19665an appropriate manner.
19666
19667@node Pragma Pack for Arrays,Pragma Pack for Records,Effect of Bit_Order on Byte Ordering,Representation Clauses and Pragmas
19668@anchor{gnat_rm/representation_clauses_and_pragmas id11}@anchor{28b}@anchor{gnat_rm/representation_clauses_and_pragmas pragma-pack-for-arrays}@anchor{28c}
19669@section Pragma Pack for Arrays
19670
19671
19672@geindex Pragma Pack (for arrays)
19673
19674Pragma @code{Pack} applied to an array has an effect that depends upon whether the
19675component type is @emph{packable}.  For a component type to be @emph{packable}, it must
19676be one of the following cases:
19677
19678
19679@itemize *
19680
19681@item
19682Any elementary type.
19683
19684@item
19685Any small packed array type with a static size.
19686
19687@item
19688Any small simple record type with a static size.
19689@end itemize
19690
19691For all these cases, if the component subtype size is in the range
196921 through 63 on 32-bit targets, and 1 through 127 on 64-bit targets,
19693then the effect of the pragma @code{Pack} is exactly as though a
19694component size were specified giving the component subtype size.
19695
19696All other types are non-packable, they occupy an integral number of storage
19697units and the only effect of pragma Pack is to remove alignment gaps.
19698
19699For example if we have:
19700
19701@example
19702type r is range 0 .. 17;
19703
19704type ar is array (1 .. 8) of r;
19705pragma Pack (ar);
19706@end example
19707
19708Then the component size of @code{ar} will be set to 5 (i.e., to @code{r'size},
19709and the size of the array @code{ar} will be exactly 40 bits).
19710
19711Note that in some cases this rather fierce approach to packing can produce
19712unexpected effects.  For example, in Ada 95 and Ada 2005,
19713subtype @code{Natural} typically has a size of 31, meaning that if you
19714pack an array of @code{Natural}, you get 31-bit
19715close packing, which saves a few bits, but results in far less efficient
19716access.  Since many other Ada compilers will ignore such a packing request,
19717GNAT will generate a warning on some uses of pragma @code{Pack} that it guesses
19718might not be what is intended.  You can easily remove this warning by
19719using an explicit @code{Component_Size} setting instead, which never generates
19720a warning, since the intention of the programmer is clear in this case.
19721
19722GNAT treats packed arrays in one of two ways.  If the size of the array is
19723known at compile time and is at most 64 bits on 32-bit targets, and at most
19724128 bits on 64-bit targets, then internally the array is represented as a
19725single modular type, of exactly the appropriate number of bits.  If the
19726length is greater than 64 bits on 32-bit targets, and greater than 128
19727bits on 64-bit targets, or is not known at compile time, then the packed
19728array is represented as an array of bytes, and its length is always a
19729multiple of 8 bits.
19730
19731Note that to represent a packed array as a modular type, the alignment must
19732be suitable for the modular type involved. For example, on typical machines
19733a 32-bit packed array will be represented by a 32-bit modular integer with
19734an alignment of four bytes. If you explicitly override the default alignment
19735with an alignment clause that is too small, the modular representation
19736cannot be used. For example, consider the following set of declarations:
19737
19738@example
19739type R is range 1 .. 3;
19740type S is array (1 .. 31) of R;
19741for S'Component_Size use 2;
19742for S'Size use 62;
19743for S'Alignment use 1;
19744@end example
19745
19746If the alignment clause were not present, then a 62-bit modular
19747representation would be chosen (typically with an alignment of 4 or 8
19748bytes depending on the target). But the default alignment is overridden
19749with the explicit alignment clause. This means that the modular
19750representation cannot be used, and instead the array of bytes
19751representation must be used, meaning that the length must be a multiple
19752of 8. Thus the above set of declarations will result in a diagnostic
19753rejecting the size clause and noting that the minimum size allowed is 64.
19754
19755@geindex Pragma Pack (for type Natural)
19756
19757@geindex Pragma Pack warning
19758
19759One special case that is worth noting occurs when the base type of the
19760component size is 8/16/32 and the subtype is one bit less. Notably this
19761occurs with subtype @code{Natural}. Consider:
19762
19763@example
19764type Arr is array (1 .. 32) of Natural;
19765pragma Pack (Arr);
19766@end example
19767
19768In all commonly used Ada 83 compilers, this pragma Pack would be ignored,
19769since typically @code{Natural'Size} is 32 in Ada 83, and in any case most
19770Ada 83 compilers did not attempt 31 bit packing.
19771
19772In Ada 95 and Ada 2005, @code{Natural'Size} is required to be 31. Furthermore,
19773GNAT really does pack 31-bit subtype to 31 bits. This may result in a
19774substantial unintended performance penalty when porting legacy Ada 83 code.
19775To help prevent this, GNAT generates a warning in such cases. If you really
19776want 31 bit packing in a case like this, you can set the component size
19777explicitly:
19778
19779@example
19780type Arr is array (1 .. 32) of Natural;
19781for Arr'Component_Size use 31;
19782@end example
19783
19784Here 31-bit packing is achieved as required, and no warning is generated,
19785since in this case the programmer intention is clear.
19786
19787@node Pragma Pack for Records,Record Representation Clauses,Pragma Pack for Arrays,Representation Clauses and Pragmas
19788@anchor{gnat_rm/representation_clauses_and_pragmas id12}@anchor{28d}@anchor{gnat_rm/representation_clauses_and_pragmas pragma-pack-for-records}@anchor{28e}
19789@section Pragma Pack for Records
19790
19791
19792@geindex Pragma Pack (for records)
19793
19794Pragma @code{Pack} applied to a record will pack the components to reduce
19795wasted space from alignment gaps and by reducing the amount of space
19796taken by components.  We distinguish between @emph{packable} components and
19797@emph{non-packable} components.
19798Components of the following types are considered packable:
19799
19800
19801@itemize *
19802
19803@item
19804Components of an elementary type are packable unless they are aliased,
19805independent or atomic.
19806
19807@item
19808Small packed arrays, where the size is statically known, are represented
19809internally as modular integers, and so they are also packable.
19810
19811@item
19812Small simple records, where the size is statically known, are also packable.
19813@end itemize
19814
19815For all these cases, if the @code{'Size} value is in the range 1 through 64 on
1981632-bit targets, and 1 through 128 on 64-bit targets, the components occupy
19817the exact number of bits corresponding to this value and are packed with no
19818padding bits, i.e. they can start on an arbitrary bit boundary.
19819
19820All other types are non-packable, they occupy an integral number of storage
19821units and the only effect of pragma @code{Pack} is to remove alignment gaps.
19822
19823For example, consider the record
19824
19825@example
19826type Rb1 is array (1 .. 13) of Boolean;
19827pragma Pack (Rb1);
19828
19829type Rb2 is array (1 .. 65) of Boolean;
19830pragma Pack (Rb2);
19831
19832type AF is new Float with Atomic;
19833
19834type X2 is record
19835   L1 : Boolean;
19836   L2 : Duration;
19837   L3 : AF;
19838   L4 : Boolean;
19839   L5 : Rb1;
19840   L6 : Rb2;
19841end record;
19842pragma Pack (X2);
19843@end example
19844
19845The representation for the record @code{X2} is as follows on 32-bit targets:
19846
19847@example
19848for X2'Size use 224;
19849for X2 use record
19850   L1 at  0 range  0 .. 0;
19851   L2 at  0 range  1 .. 64;
19852   L3 at 12 range  0 .. 31;
19853   L4 at 16 range  0 .. 0;
19854   L5 at 16 range  1 .. 13;
19855   L6 at 18 range  0 .. 71;
19856end record;
19857@end example
19858
19859Studying this example, we see that the packable fields @code{L1}
19860and @code{L2} are of length equal to their sizes, and placed at
19861specific bit boundaries (and not byte boundaries) to eliminate
19862padding.  But @code{L3} is of a non-packable float type (because
19863it is aliased), so it is on the next appropriate alignment boundary.
19864
19865The next two fields are fully packable, so @code{L4} and @code{L5} are
19866minimally packed with no gaps.  However, type @code{Rb2} is a packed
19867array that is longer than 64 bits, so it is itself non-packable on
1986832-bit targets.  Thus the @code{L6} field is aligned to the next byte
19869boundary, and takes an integral number of bytes, i.e., 72 bits.
19870
19871@node Record Representation Clauses,Handling of Records with Holes,Pragma Pack for Records,Representation Clauses and Pragmas
19872@anchor{gnat_rm/representation_clauses_and_pragmas id13}@anchor{28f}@anchor{gnat_rm/representation_clauses_and_pragmas record-representation-clauses}@anchor{290}
19873@section Record Representation Clauses
19874
19875
19876@geindex Record Representation Clause
19877
19878Record representation clauses may be given for all record types, including
19879types obtained by record extension.  Component clauses are allowed for any
19880static component.  The restrictions on component clauses depend on the type
19881of the component.
19882
19883@geindex Component Clause
19884
19885For all components of an elementary type, the only restriction on component
19886clauses is that the size must be at least the @code{'Size} value of the type
19887(actually the Value_Size).  There are no restrictions due to alignment,
19888and such components may freely cross storage boundaries.
19889
19890Packed arrays with a size up to and including 64 bits on 32-bit targets,
19891and up to and including 128 bits on 64-bit targets, are represented
19892internally using a modular type with the appropriate number of bits, and
19893thus the same lack of restriction applies.  For example, if you declare:
19894
19895@example
19896type R is array (1 .. 49) of Boolean;
19897pragma Pack (R);
19898for R'Size use 49;
19899@end example
19900
19901then a component clause for a component of type @code{R} may start on any
19902specified bit boundary, and may specify a value of 49 bits or greater.
19903
19904For packed bit arrays that are longer than 64 bits on 32-bit targets,
19905and longer than 128 bits on 64-bit targets, there are two cases. If the
19906component size is a power of 2 (1,2,4,8,16,32,64 bits), including the
19907important case of single bits or boolean values, then there are no
19908limitations on placement of such components, and they may start and
19909end at arbitrary bit boundaries.
19910
19911If the component size is not a power of 2 (e.g., 3 or 5), then an array
19912of this type must always be placed on on a storage unit (byte) boundary
19913and occupy an integral number of storage units (bytes). Any component
19914clause that does not meet this requirement will be rejected.
19915
19916Any aliased component, or component of an aliased type, must have its
19917normal alignment and size. A component clause that does not meet this
19918requirement will be rejected.
19919
19920The tag field of a tagged type always occupies an address sized field at
19921the start of the record.  No component clause may attempt to overlay this
19922tag. When a tagged type appears as a component, the tag field must have
19923proper alignment
19924
19925In the case of a record extension @code{T1}, of a type @code{T}, no component
19926clause applied to the type @code{T1} can specify a storage location that
19927would overlap the first @code{T'Object_Size} bits of the record.
19928
19929For all other component types, including non-bit-packed arrays,
19930the component can be placed at an arbitrary bit boundary,
19931so for example, the following is permitted:
19932
19933@example
19934type R is array (1 .. 10) of Boolean;
19935for R'Size use 80;
19936
19937type Q is record
19938   G, H : Boolean;
19939   L, M : R;
19940end record;
19941
19942for Q use record
19943   G at 0 range  0 ..   0;
19944   H at 0 range  1 ..   1;
19945   L at 0 range  2 ..  81;
19946   R at 0 range 82 .. 161;
19947end record;
19948@end example
19949
19950@node Handling of Records with Holes,Enumeration Clauses,Record Representation Clauses,Representation Clauses and Pragmas
19951@anchor{gnat_rm/representation_clauses_and_pragmas handling-of-records-with-holes}@anchor{291}@anchor{gnat_rm/representation_clauses_and_pragmas id14}@anchor{292}
19952@section Handling of Records with Holes
19953
19954
19955@geindex Handling of Records with Holes
19956
19957As a result of alignment considerations, records may contain “holes”
19958or gaps which do not correspond to the data bits of any of the components.
19959Record representation clauses can also result in holes in records.
19960
19961GNAT does not attempt to clear these holes, so in record objects,
19962they should be considered to hold undefined rubbish. The generated
19963equality routine just tests components so does not access these
19964undefined bits, and assignment and copy operations may or may not
19965preserve the contents of these holes (for assignments, the holes
19966in the target will in practice contain either the bits that are
19967present in the holes in the source, or the bits that were present
19968in the target before the assignment).
19969
19970If it is necessary to ensure that holes in records have all zero
19971bits, then record objects for which this initialization is desired
19972should be explicitly set to all zero values using Unchecked_Conversion
19973or address overlays. For example
19974
19975@example
19976type HRec is record
19977   C : Character;
19978   I : Integer;
19979end record;
19980@end example
19981
19982On typical machines, integers need to be aligned on a four-byte
19983boundary, resulting in three bytes of undefined rubbish following
19984the 8-bit field for C. To ensure that the hole in a variable of
19985type HRec is set to all zero bits,
19986you could for example do:
19987
19988@example
19989type Base is record
19990   Dummy1, Dummy2 : Integer := 0;
19991end record;
19992
19993BaseVar : Base;
19994RealVar : Hrec;
19995for RealVar'Address use BaseVar'Address;
19996@end example
19997
19998Now the 8-bytes of the value of RealVar start out containing all zero
19999bits. A safer approach is to just define dummy fields, avoiding the
20000holes, as in:
20001
20002@example
20003type HRec is record
20004   C      : Character;
20005   Dummy1 : Short_Short_Integer := 0;
20006   Dummy2 : Short_Short_Integer := 0;
20007   Dummy3 : Short_Short_Integer := 0;
20008   I      : Integer;
20009end record;
20010@end example
20011
20012And to make absolutely sure that the intent of this is followed, you
20013can use representation clauses:
20014
20015@example
20016for Hrec use record
20017   C      at 0 range 0 .. 7;
20018   Dummy1 at 1 range 0 .. 7;
20019   Dummy2 at 2 range 0 .. 7;
20020   Dummy3 at 3 range 0 .. 7;
20021   I      at 4 range 0 .. 31;
20022end record;
20023for Hrec'Size use 64;
20024@end example
20025
20026@node Enumeration Clauses,Address Clauses,Handling of Records with Holes,Representation Clauses and Pragmas
20027@anchor{gnat_rm/representation_clauses_and_pragmas enumeration-clauses}@anchor{293}@anchor{gnat_rm/representation_clauses_and_pragmas id15}@anchor{294}
20028@section Enumeration Clauses
20029
20030
20031The only restriction on enumeration clauses is that the range of values
20032must be representable.  For the signed case, if one or more of the
20033representation values are negative, all values must be in the range:
20034
20035@example
20036System.Min_Int .. System.Max_Int
20037@end example
20038
20039For the unsigned case, where all values are nonnegative, the values must
20040be in the range:
20041
20042@example
200430 .. System.Max_Binary_Modulus;
20044@end example
20045
20046A @emph{confirming} representation clause is one in which the values range
20047from 0 in sequence, i.e., a clause that confirms the default representation
20048for an enumeration type.
20049Such a confirming representation
20050is permitted by these rules, and is specially recognized by the compiler so
20051that no extra overhead results from the use of such a clause.
20052
20053If an array has an index type which is an enumeration type to which an
20054enumeration clause has been applied, then the array is stored in a compact
20055manner.  Consider the declarations:
20056
20057@example
20058type r is (A, B, C);
20059for r use (A => 1, B => 5, C => 10);
20060type t is array (r) of Character;
20061@end example
20062
20063The array type t corresponds to a vector with exactly three elements and
20064has a default size equal to @code{3*Character'Size}.  This ensures efficient
20065use of space, but means that accesses to elements of the array will incur
20066the overhead of converting representation values to the corresponding
20067positional values, (i.e., the value delivered by the @code{Pos} attribute).
20068
20069@node Address Clauses,Use of Address Clauses for Memory-Mapped I/O,Enumeration Clauses,Representation Clauses and Pragmas
20070@anchor{gnat_rm/representation_clauses_and_pragmas address-clauses}@anchor{295}@anchor{gnat_rm/representation_clauses_and_pragmas id16}@anchor{296}
20071@section Address Clauses
20072
20073
20074@geindex Address Clause
20075
20076The reference manual allows a general restriction on representation clauses,
20077as found in RM 13.1(22):
20078
20079@quotation
20080
20081“An implementation need not support representation
20082items containing nonstatic expressions, except that
20083an implementation should support a representation item
20084for a given entity if each nonstatic expression in the
20085representation item is a name that statically denotes
20086a constant declared before the entity.”
20087@end quotation
20088
20089In practice this is applicable only to address clauses, since this is the
20090only case in which a nonstatic expression is permitted by the syntax.  As
20091the AARM notes in sections 13.1 (22.a-22.h):
20092
20093@quotation
20094
2009522.a   Reason: This is to avoid the following sort of thing:
20096
2009722.b        X : Integer := F(…);
20098Y : Address := G(…);
20099for X’Address use Y;
20100
2010122.c   In the above, we have to evaluate the
20102initialization expression for X before we
20103know where to put the result.  This seems
20104like an unreasonable implementation burden.
20105
2010622.d   The above code should instead be written
20107like this:
20108
2010922.e        Y : constant Address := G(…);
20110X : Integer := F(…);
20111for X’Address use Y;
20112
2011322.f   This allows the expression ‘Y’ to be safely
20114evaluated before X is created.
20115
2011622.g   The constant could be a formal parameter of mode in.
20117
2011822.h   An implementation can support other nonstatic
20119expressions if it wants to.  Expressions of type
20120Address are hardly ever static, but their value
20121might be known at compile time anyway in many
20122cases.
20123@end quotation
20124
20125GNAT does indeed permit many additional cases of nonstatic expressions.  In
20126particular, if the type involved is elementary there are no restrictions
20127(since in this case, holding a temporary copy of the initialization value,
20128if one is present, is inexpensive).  In addition, if there is no implicit or
20129explicit initialization, then there are no restrictions.  GNAT will reject
20130only the case where all three of these conditions hold:
20131
20132
20133@itemize *
20134
20135@item
20136The type of the item is non-elementary (e.g., a record or array).
20137
20138@item
20139There is explicit or implicit initialization required for the object.
20140Note that access values are always implicitly initialized.
20141
20142@item
20143The address value is nonstatic.  Here GNAT is more permissive than the
20144RM, and allows the address value to be the address of a previously declared
20145stand-alone variable, as long as it does not itself have an address clause.
20146
20147@example
20148Anchor  : Some_Initialized_Type;
20149Overlay : Some_Initialized_Type;
20150for Overlay'Address use Anchor'Address;
20151@end example
20152
20153However, the prefix of the address clause cannot be an array component, or
20154a component of a discriminated record.
20155@end itemize
20156
20157As noted above in section 22.h, address values are typically nonstatic.  In
20158particular the To_Address function, even if applied to a literal value, is
20159a nonstatic function call.  To avoid this minor annoyance, GNAT provides
20160the implementation defined attribute ‘To_Address.  The following two
20161expressions have identical values:
20162
20163@geindex Attribute
20164
20165@geindex To_Address
20166
20167@example
20168To_Address (16#1234_0000#)
20169System'To_Address (16#1234_0000#);
20170@end example
20171
20172except that the second form is considered to be a static expression, and
20173thus when used as an address clause value is always permitted.
20174
20175Additionally, GNAT treats as static an address clause that is an
20176unchecked_conversion of a static integer value.  This simplifies the porting
20177of legacy code, and provides a portable equivalent to the GNAT attribute
20178@code{To_Address}.
20179
20180Another issue with address clauses is the interaction with alignment
20181requirements.  When an address clause is given for an object, the address
20182value must be consistent with the alignment of the object (which is usually
20183the same as the alignment of the type of the object).  If an address clause
20184is given that specifies an inappropriately aligned address value, then the
20185program execution is erroneous.
20186
20187Since this source of erroneous behavior can have unfortunate effects on
20188machines with strict alignment requirements, GNAT
20189checks (at compile time if possible, generating a warning, or at execution
20190time with a run-time check) that the alignment is appropriate.  If the
20191run-time check fails, then @code{Program_Error} is raised.  This run-time
20192check is suppressed if range checks are suppressed, or if the special GNAT
20193check Alignment_Check is suppressed, or if
20194@code{pragma Restrictions (No_Elaboration_Code)} is in effect. It is also
20195suppressed by default on non-strict alignment machines (such as the x86).
20196
20197Finally, GNAT does not permit overlaying of objects of class-wide types. In
20198most cases, the compiler can detect an attempt at such overlays and will
20199generate a warning at compile time and a Program_Error exception at run time.
20200
20201@geindex Export
20202
20203An address clause cannot be given for an exported object.  More
20204understandably the real restriction is that objects with an address
20205clause cannot be exported.  This is because such variables are not
20206defined by the Ada program, so there is no external object to export.
20207
20208@geindex Import
20209
20210It is permissible to give an address clause and a pragma Import for the
20211same object.  In this case, the variable is not really defined by the
20212Ada program, so there is no external symbol to be linked.  The link name
20213and the external name are ignored in this case.  The reason that we allow this
20214combination is that it provides a useful idiom to avoid unwanted
20215initializations on objects with address clauses.
20216
20217When an address clause is given for an object that has implicit or
20218explicit initialization, then by default initialization takes place.  This
20219means that the effect of the object declaration is to overwrite the
20220memory at the specified address.  This is almost always not what the
20221programmer wants, so GNAT will output a warning:
20222
20223@example
20224with System;
20225package G is
20226   type R is record
20227      M : Integer := 0;
20228   end record;
20229
20230   Ext : R;
20231   for Ext'Address use System'To_Address (16#1234_1234#);
20232       |
20233>>> warning: implicit initialization of "Ext" may
20234    modify overlaid storage
20235>>> warning: use pragma Import for "Ext" to suppress
20236    initialization (RM B(24))
20237
20238end G;
20239@end example
20240
20241As indicated by the warning message, the solution is to use a (dummy) pragma
20242Import to suppress this initialization.  The pragma tell the compiler that the
20243object is declared and initialized elsewhere.  The following package compiles
20244without warnings (and the initialization is suppressed):
20245
20246@example
20247with System;
20248package G is
20249   type R is record
20250      M : Integer := 0;
20251   end record;
20252
20253   Ext : R;
20254   for Ext'Address use System'To_Address (16#1234_1234#);
20255   pragma Import (Ada, Ext);
20256end G;
20257@end example
20258
20259A final issue with address clauses involves their use for overlaying
20260variables, as in the following example:
20261
20262@geindex Overlaying of objects
20263
20264@example
20265A : Integer;
20266B : Integer;
20267for B'Address use A'Address;
20268@end example
20269
20270or alternatively, using the form recommended by the RM:
20271
20272@example
20273A    : Integer;
20274Addr : constant Address := A'Address;
20275B    : Integer;
20276for B'Address use Addr;
20277@end example
20278
20279In both of these cases, @code{A} and @code{B} become aliased to one another
20280via the address clause. This use of address clauses to overlay
20281variables, achieving an effect similar to unchecked conversion
20282was erroneous in Ada 83, but in Ada 95 and Ada 2005
20283the effect is implementation defined. Furthermore, the
20284Ada RM specifically recommends that in a situation
20285like this, @code{B} should be subject to the following
20286implementation advice (RM 13.3(19)):
20287
20288@quotation
20289
20290“19  If the Address of an object is specified, or it is imported
20291or exported, then the implementation should not perform
20292optimizations based on assumptions of no aliases.”
20293@end quotation
20294
20295GNAT follows this recommendation, and goes further by also applying
20296this recommendation to the overlaid variable (@code{A} in the above example)
20297in this case. This means that the overlay works “as expected”, in that
20298a modification to one of the variables will affect the value of the other.
20299
20300More generally, GNAT interprets this recommendation conservatively for
20301address clauses: in the cases other than overlays, it considers that the
20302object is effectively subject to pragma @code{Volatile} and implements the
20303associated semantics.
20304
20305Note that when address clause overlays are used in this way, there is an
20306issue of unintentional initialization, as shown by this example:
20307
20308@example
20309package Overwrite_Record is
20310   type R is record
20311      A : Character := 'C';
20312      B : Character := 'A';
20313   end record;
20314   X : Short_Integer := 3;
20315   Y : R;
20316   for Y'Address use X'Address;
20317       |
20318>>> warning: default initialization of "Y" may
20319    modify "X", use pragma Import for "Y" to
20320    suppress initialization (RM B.1(24))
20321
20322end Overwrite_Record;
20323@end example
20324
20325Here the default initialization of @code{Y} will clobber the value
20326of @code{X}, which justifies the warning. The warning notes that
20327this effect can be eliminated by adding a @code{pragma Import}
20328which suppresses the initialization:
20329
20330@example
20331package Overwrite_Record is
20332   type R is record
20333      A : Character := 'C';
20334      B : Character := 'A';
20335   end record;
20336   X : Short_Integer := 3;
20337   Y : R;
20338   for Y'Address use X'Address;
20339   pragma Import (Ada, Y);
20340end Overwrite_Record;
20341@end example
20342
20343Note that the use of @code{pragma Initialize_Scalars} may cause variables to
20344be initialized when they would not otherwise have been in the absence
20345of the use of this pragma. This may cause an overlay to have this
20346unintended clobbering effect. The compiler avoids this for scalar
20347types, but not for composite objects (where in general the effect
20348of @code{Initialize_Scalars} is part of the initialization routine
20349for the composite object):
20350
20351@example
20352pragma Initialize_Scalars;
20353with Ada.Text_IO;  use Ada.Text_IO;
20354procedure Overwrite_Array is
20355   type Arr is array (1 .. 5) of Integer;
20356   X : Arr := (others => 1);
20357   A : Arr;
20358   for A'Address use X'Address;
20359       |
20360>>> warning: default initialization of "A" may
20361    modify "X", use pragma Import for "A" to
20362    suppress initialization (RM B.1(24))
20363
20364begin
20365   if X /= Arr'(others => 1) then
20366      Put_Line ("X was clobbered");
20367   else
20368      Put_Line ("X was not clobbered");
20369   end if;
20370end Overwrite_Array;
20371@end example
20372
20373The above program generates the warning as shown, and at execution
20374time, prints @code{X was clobbered}. If the @code{pragma Import} is
20375added as suggested:
20376
20377@example
20378pragma Initialize_Scalars;
20379with Ada.Text_IO;  use Ada.Text_IO;
20380procedure Overwrite_Array is
20381   type Arr is array (1 .. 5) of Integer;
20382   X : Arr := (others => 1);
20383   A : Arr;
20384   for A'Address use X'Address;
20385   pragma Import (Ada, A);
20386begin
20387   if X /= Arr'(others => 1) then
20388      Put_Line ("X was clobbered");
20389   else
20390      Put_Line ("X was not clobbered");
20391   end if;
20392end Overwrite_Array;
20393@end example
20394
20395then the program compiles without the warning and when run will generate
20396the output @code{X was not clobbered}.
20397
20398@node Use of Address Clauses for Memory-Mapped I/O,Effect of Convention on Representation,Address Clauses,Representation Clauses and Pragmas
20399@anchor{gnat_rm/representation_clauses_and_pragmas id17}@anchor{297}@anchor{gnat_rm/representation_clauses_and_pragmas use-of-address-clauses-for-memory-mapped-i-o}@anchor{298}
20400@section Use of Address Clauses for Memory-Mapped I/O
20401
20402
20403@geindex Memory-mapped I/O
20404
20405A common pattern is to use an address clause to map an atomic variable to
20406a location in memory that corresponds to a memory-mapped I/O operation or
20407operations, for example:
20408
20409@example
20410type Mem_Word is record
20411   A,B,C,D : Byte;
20412end record;
20413pragma Atomic (Mem_Word);
20414for Mem_Word_Size use 32;
20415
20416Mem : Mem_Word;
20417for Mem'Address use some-address;
20418...
20419Temp := Mem;
20420Temp.A := 32;
20421Mem := Temp;
20422@end example
20423
20424For a full access (reference or modification) of the variable (Mem) in this
20425case, as in the above examples, GNAT guarantees that the entire atomic word
20426will be accessed, in accordance with the RM C.6(15) clause.
20427
20428A problem arises with a component access such as:
20429
20430@example
20431Mem.A := 32;
20432@end example
20433
20434Note that the component A is not declared as atomic. This means that it is
20435not clear what this assignment means. It could correspond to full word read
20436and write as given in the first example, or on architectures that supported
20437such an operation it might be a single byte store instruction. The RM does
20438not have anything to say in this situation, and GNAT does not make any
20439guarantee. The code generated may vary from target to target. GNAT will issue
20440a warning in such a case:
20441
20442@example
20443Mem.A := 32;
20444|
20445>>> warning: access to non-atomic component of atomic array,
20446    may cause unexpected accesses to atomic object
20447@end example
20448
20449It is best to be explicit in this situation, by either declaring the
20450components to be atomic if you want the byte store, or explicitly writing
20451the full word access sequence if that is what the hardware requires.
20452Alternatively, if the full word access sequence is required, GNAT also
20453provides the pragma @code{Volatile_Full_Access} which can be used in lieu of
20454pragma @code{Atomic} and will give the additional guarantee.
20455
20456@node Effect of Convention on Representation,Conventions and Anonymous Access Types,Use of Address Clauses for Memory-Mapped I/O,Representation Clauses and Pragmas
20457@anchor{gnat_rm/representation_clauses_and_pragmas effect-of-convention-on-representation}@anchor{299}@anchor{gnat_rm/representation_clauses_and_pragmas id18}@anchor{29a}
20458@section Effect of Convention on Representation
20459
20460
20461@geindex Convention
20462@geindex effect on representation
20463
20464Normally the specification of a foreign language convention for a type or
20465an object has no effect on the chosen representation.  In particular, the
20466representation chosen for data in GNAT generally meets the standard system
20467conventions, and for example records are laid out in a manner that is
20468consistent with C.  This means that specifying convention C (for example)
20469has no effect.
20470
20471There are four exceptions to this general rule:
20472
20473
20474@itemize *
20475
20476@item
20477@emph{Convention Fortran and array subtypes}.
20478
20479If pragma Convention Fortran is specified for an array subtype, then in
20480accordance with the implementation advice in section 3.6.2(11) of the
20481Ada Reference Manual, the array will be stored in a Fortran-compatible
20482column-major manner, instead of the normal default row-major order.
20483
20484@item
20485@emph{Convention C and enumeration types}
20486
20487GNAT normally stores enumeration types in 8, 16, or 32 bits as required
20488to accommodate all values of the type.  For example, for the enumeration
20489type declared by:
20490
20491@example
20492type Color is (Red, Green, Blue);
20493@end example
20494
204958 bits is sufficient to store all values of the type, so by default, objects
20496of type @code{Color} will be represented using 8 bits.  However, normal C
20497convention is to use 32 bits for all enum values in C, since enum values
20498are essentially of type int.  If pragma @code{Convention C} is specified for an
20499Ada enumeration type, then the size is modified as necessary (usually to
2050032 bits) to be consistent with the C convention for enum values.
20501
20502Note that this treatment applies only to types. If Convention C is given for
20503an enumeration object, where the enumeration type is not Convention C, then
20504Object_Size bits are allocated. For example, for a normal enumeration type,
20505with less than 256 elements, only 8 bits will be allocated for the object.
20506Since this may be a surprise in terms of what C expects, GNAT will issue a
20507warning in this situation. The warning can be suppressed by giving an explicit
20508size clause specifying the desired size.
20509
20510@item
20511@emph{Convention C/Fortran and Boolean types}
20512
20513In C, the usual convention for boolean values, that is values used for
20514conditions, is that zero represents false, and nonzero values represent
20515true.  In Ada, the normal convention is that two specific values, typically
205160/1, are used to represent false/true respectively.
20517
20518Fortran has a similar convention for @code{LOGICAL} values (any nonzero
20519value represents true).
20520
20521To accommodate the Fortran and C conventions, if a pragma Convention specifies
20522C or Fortran convention for a derived Boolean, as in the following example:
20523
20524@example
20525type C_Switch is new Boolean;
20526pragma Convention (C, C_Switch);
20527@end example
20528
20529then the GNAT generated code will treat any nonzero value as true.  For truth
20530values generated by GNAT, the conventional value 1 will be used for True, but
20531when one of these values is read, any nonzero value is treated as True.
20532@end itemize
20533
20534@node Conventions and Anonymous Access Types,Determining the Representations chosen by GNAT,Effect of Convention on Representation,Representation Clauses and Pragmas
20535@anchor{gnat_rm/representation_clauses_and_pragmas conventions-and-anonymous-access-types}@anchor{29b}@anchor{gnat_rm/representation_clauses_and_pragmas id19}@anchor{29c}
20536@section Conventions and Anonymous Access Types
20537
20538
20539@geindex Anonymous access types
20540
20541@geindex Convention for anonymous access types
20542
20543The RM is not entirely clear on convention handling in a number of cases,
20544and in particular, it is not clear on the convention to be given to
20545anonymous access types in general, and in particular what is to be
20546done for the case of anonymous access-to-subprogram.
20547
20548In GNAT, we decide that if an explicit Convention is applied
20549to an object or component, and its type is such an anonymous type,
20550then the convention will apply to this anonymous type as well. This
20551seems to make sense since it is anomolous in any case to have a
20552different convention for an object and its type, and there is clearly
20553no way to explicitly specify a convention for an anonymous type, since
20554it doesn’t have a name to specify!
20555
20556Furthermore, we decide that if a convention is applied to a record type,
20557then this convention is inherited by any of its components that are of an
20558anonymous access type which do not have an explicitly specified convention.
20559
20560The following program shows these conventions in action:
20561
20562@example
20563package ConvComp is
20564   type Foo is range 1 .. 10;
20565   type T1 is record
20566      A : access function (X : Foo) return Integer;
20567      B : Integer;
20568   end record;
20569   pragma Convention (C, T1);
20570
20571   type T2 is record
20572      A : access function (X : Foo) return Integer;
20573      pragma Convention  (C, A);
20574      B : Integer;
20575   end record;
20576   pragma Convention (COBOL, T2);
20577
20578   type T3 is record
20579      A : access function (X : Foo) return Integer;
20580      pragma Convention  (COBOL, A);
20581      B : Integer;
20582   end record;
20583   pragma Convention (C, T3);
20584
20585   type T4 is record
20586      A : access function (X : Foo) return Integer;
20587      B : Integer;
20588   end record;
20589   pragma Convention (COBOL, T4);
20590
20591   function F (X : Foo) return Integer;
20592   pragma Convention (C, F);
20593
20594   function F (X : Foo) return Integer is (13);
20595
20596   TV1 : T1 := (F'Access, 12);  -- OK
20597   TV2 : T2 := (F'Access, 13);  -- OK
20598
20599   TV3 : T3 := (F'Access, 13);  -- ERROR
20600                |
20601>>> subprogram "F" has wrong convention
20602>>> does not match access to subprogram declared at line 17
20603     38.    TV4 : T4 := (F'Access, 13);  -- ERROR
20604                |
20605>>> subprogram "F" has wrong convention
20606>>> does not match access to subprogram declared at line 24
20607     39. end ConvComp;
20608@end example
20609
20610@node Determining the Representations chosen by GNAT,,Conventions and Anonymous Access Types,Representation Clauses and Pragmas
20611@anchor{gnat_rm/representation_clauses_and_pragmas determining-the-representations-chosen-by-gnat}@anchor{29d}@anchor{gnat_rm/representation_clauses_and_pragmas id20}@anchor{29e}
20612@section Determining the Representations chosen by GNAT
20613
20614
20615@geindex Representation
20616@geindex determination of
20617
20618@geindex -gnatR (gcc)
20619
20620Although the descriptions in this section are intended to be complete, it is
20621often easier to simply experiment to see what GNAT accepts and what the
20622effect is on the layout of types and objects.
20623
20624As required by the Ada RM, if a representation clause is not accepted, then
20625it must be rejected as illegal by the compiler.  However, when a
20626representation clause or pragma is accepted, there can still be questions
20627of what the compiler actually does.  For example, if a partial record
20628representation clause specifies the location of some components and not
20629others, then where are the non-specified components placed? Or if pragma
20630@code{Pack} is used on a record, then exactly where are the resulting
20631fields placed? The section on pragma @code{Pack} in this chapter can be
20632used to answer the second question, but it is often easier to just see
20633what the compiler does.
20634
20635For this purpose, GNAT provides the option @emph{-gnatR}.  If you compile
20636with this option, then the compiler will output information on the actual
20637representations chosen, in a format similar to source representation
20638clauses.  For example, if we compile the package:
20639
20640@example
20641package q is
20642   type r (x : boolean) is tagged record
20643      case x is
20644         when True => S : String (1 .. 100);
20645         when False => null;
20646      end case;
20647   end record;
20648
20649   type r2 is new r (false) with record
20650      y2 : integer;
20651   end record;
20652
20653   for r2 use record
20654      y2 at 16 range 0 .. 31;
20655   end record;
20656
20657   type x is record
20658      y : character;
20659   end record;
20660
20661   type x1 is array (1 .. 10) of x;
20662   for x1'component_size use 11;
20663
20664   type ia is access integer;
20665
20666   type Rb1 is array (1 .. 13) of Boolean;
20667   pragma Pack (rb1);
20668
20669   type Rb2 is array (1 .. 65) of Boolean;
20670   pragma Pack (rb2);
20671
20672   type x2 is record
20673      l1 : Boolean;
20674      l2 : Duration;
20675      l3 : Float;
20676      l4 : Boolean;
20677      l5 : Rb1;
20678      l6 : Rb2;
20679   end record;
20680   pragma Pack (x2);
20681end q;
20682@end example
20683
20684using the switch @emph{-gnatR} we obtain the following output:
20685
20686@example
20687Representation information for unit q
20688-------------------------------------
20689
20690for r'Size use ??;
20691for r'Alignment use 4;
20692for r use record
20693   x    at 4 range  0 .. 7;
20694   _tag at 0 range  0 .. 31;
20695   s    at 5 range  0 .. 799;
20696end record;
20697
20698for r2'Size use 160;
20699for r2'Alignment use 4;
20700for r2 use record
20701   x       at  4 range  0 .. 7;
20702   _tag    at  0 range  0 .. 31;
20703   _parent at  0 range  0 .. 63;
20704   y2      at 16 range  0 .. 31;
20705end record;
20706
20707for x'Size use 8;
20708for x'Alignment use 1;
20709for x use record
20710   y at 0 range  0 .. 7;
20711end record;
20712
20713for x1'Size use 112;
20714for x1'Alignment use 1;
20715for x1'Component_Size use 11;
20716
20717for rb1'Size use 13;
20718for rb1'Alignment use 2;
20719for rb1'Component_Size use 1;
20720
20721for rb2'Size use 72;
20722for rb2'Alignment use 1;
20723for rb2'Component_Size use 1;
20724
20725for x2'Size use 224;
20726for x2'Alignment use 4;
20727for x2 use record
20728   l1 at  0 range  0 .. 0;
20729   l2 at  0 range  1 .. 64;
20730   l3 at 12 range  0 .. 31;
20731   l4 at 16 range  0 .. 0;
20732   l5 at 16 range  1 .. 13;
20733   l6 at 18 range  0 .. 71;
20734end record;
20735@end example
20736
20737The Size values are actually the Object_Size, i.e., the default size that
20738will be allocated for objects of the type.
20739The @code{??} size for type r indicates that we have a variant record, and the
20740actual size of objects will depend on the discriminant value.
20741
20742The Alignment values show the actual alignment chosen by the compiler
20743for each record or array type.
20744
20745The record representation clause for type r shows where all fields
20746are placed, including the compiler generated tag field (whose location
20747cannot be controlled by the programmer).
20748
20749The record representation clause for the type extension r2 shows all the
20750fields present, including the parent field, which is a copy of the fields
20751of the parent type of r2, i.e., r1.
20752
20753The component size and size clauses for types rb1 and rb2 show
20754the exact effect of pragma @code{Pack} on these arrays, and the record
20755representation clause for type x2 shows how pragma @cite{Pack} affects
20756this record type.
20757
20758In some cases, it may be useful to cut and paste the representation clauses
20759generated by the compiler into the original source to fix and guarantee
20760the actual representation to be used.
20761
20762@node Standard Library Routines,The Implementation of Standard I/O,Representation Clauses and Pragmas,Top
20763@anchor{gnat_rm/standard_library_routines doc}@anchor{29f}@anchor{gnat_rm/standard_library_routines id1}@anchor{2a0}@anchor{gnat_rm/standard_library_routines standard-library-routines}@anchor{e}
20764@chapter Standard Library Routines
20765
20766
20767The Ada Reference Manual contains in Annex A a full description of an
20768extensive set of standard library routines that can be used in any Ada
20769program, and which must be provided by all Ada compilers.  They are
20770analogous to the standard C library used by C programs.
20771
20772GNAT implements all of the facilities described in annex A, and for most
20773purposes the description in the Ada Reference Manual, or appropriate Ada
20774text book, will be sufficient for making use of these facilities.
20775
20776In the case of the input-output facilities,
20777@ref{f,,The Implementation of Standard I/O},
20778gives details on exactly how GNAT interfaces to the
20779file system.  For the remaining packages, the Ada Reference Manual
20780should be sufficient.  The following is a list of the packages included,
20781together with a brief description of the functionality that is provided.
20782
20783For completeness, references are included to other predefined library
20784routines defined in other sections of the Ada Reference Manual (these are
20785cross-indexed from Annex A). For further details see the relevant
20786package declarations in the run-time library. In particular, a few units
20787are not implemented, as marked by the presence of pragma Unimplemented_Unit,
20788and in this case the package declaration contains comments explaining why
20789the unit is not implemented.
20790
20791
20792@table @asis
20793
20794@item @code{Ada} @emph{(A.2)}
20795
20796This is a parent package for all the standard library packages.  It is
20797usually included implicitly in your program, and itself contains no
20798useful data or routines.
20799
20800@item @code{Ada.Assertions} @emph{(11.4.2)}
20801
20802@code{Assertions} provides the @code{Assert} subprograms, and also
20803the declaration of the @code{Assertion_Error} exception.
20804
20805@item @code{Ada.Asynchronous_Task_Control} @emph{(D.11)}
20806
20807@code{Asynchronous_Task_Control} provides low level facilities for task
20808synchronization. It is typically not implemented. See package spec for details.
20809
20810@item @code{Ada.Calendar} @emph{(9.6)}
20811
20812@code{Calendar} provides time of day access, and routines for
20813manipulating times and durations.
20814
20815@item @code{Ada.Calendar.Arithmetic} @emph{(9.6.1)}
20816
20817This package provides additional arithmetic
20818operations for @code{Calendar}.
20819
20820@item @code{Ada.Calendar.Formatting} @emph{(9.6.1)}
20821
20822This package provides formatting operations for @code{Calendar}.
20823
20824@item @code{Ada.Calendar.Time_Zones} @emph{(9.6.1)}
20825
20826This package provides additional @code{Calendar} facilities
20827for handling time zones.
20828
20829@item @code{Ada.Characters} @emph{(A.3.1)}
20830
20831This is a dummy parent package that contains no useful entities
20832
20833@item @code{Ada.Characters.Conversions} @emph{(A.3.2)}
20834
20835This package provides character conversion functions.
20836
20837@item @code{Ada.Characters.Handling} @emph{(A.3.2)}
20838
20839This package provides some basic character handling capabilities,
20840including classification functions for classes of characters (e.g., test
20841for letters, or digits).
20842
20843@item @code{Ada.Characters.Latin_1} @emph{(A.3.3)}
20844
20845This package includes a complete set of definitions of the characters
20846that appear in type CHARACTER.  It is useful for writing programs that
20847will run in international environments.  For example, if you want an
20848upper case E with an acute accent in a string, it is often better to use
20849the definition of @code{UC_E_Acute} in this package.  Then your program
20850will print in an understandable manner even if your environment does not
20851support these extended characters.
20852
20853@item @code{Ada.Command_Line} @emph{(A.15)}
20854
20855This package provides access to the command line parameters and the name
20856of the current program (analogous to the use of @code{argc} and @code{argv}
20857in C), and also allows the exit status for the program to be set in a
20858system-independent manner.
20859
20860@item @code{Ada.Complex_Text_IO} @emph{(G.1.3)}
20861
20862This package provides text input and output of complex numbers.
20863
20864@item @code{Ada.Containers} @emph{(A.18.1)}
20865
20866A top level package providing a few basic definitions used by all the
20867following specific child packages that provide specific kinds of
20868containers.
20869@end table
20870
20871@code{Ada.Containers.Bounded_Priority_Queues} @emph{(A.18.31)}
20872
20873@code{Ada.Containers.Bounded_Synchronized_Queues} @emph{(A.18.29)}
20874
20875@code{Ada.Containers.Doubly_Linked_Lists} @emph{(A.18.3)}
20876
20877@code{Ada.Containers.Generic_Array_Sort} @emph{(A.18.26)}
20878
20879@code{Ada.Containers.Generic_Constrained_Array_Sort} @emph{(A.18.26)}
20880
20881@code{Ada.Containers.Generic_Sort} @emph{(A.18.26)}
20882
20883@code{Ada.Containers.Hashed_Maps} @emph{(A.18.5)}
20884
20885@code{Ada.Containers.Hashed_Sets} @emph{(A.18.8)}
20886
20887@code{Ada.Containers.Indefinite_Doubly_Linked_Lists} @emph{(A.18.12)}
20888
20889@code{Ada.Containers.Indefinite_Hashed_Maps} @emph{(A.18.13)}
20890
20891@code{Ada.Containers.Indefinite_Hashed_Sets} @emph{(A.18.15)}
20892
20893@code{Ada.Containers.Indefinite_Holders} @emph{(A.18.18)}
20894
20895@code{Ada.Containers.Indefinite_Multiway_Trees} @emph{(A.18.17)}
20896
20897@code{Ada.Containers.Indefinite_Ordered_Maps} @emph{(A.18.14)}
20898
20899@code{Ada.Containers.Indefinite_Ordered_Sets} @emph{(A.18.16)}
20900
20901@code{Ada.Containers.Indefinite_Vectors} @emph{(A.18.11)}
20902
20903@code{Ada.Containers.Multiway_Trees} @emph{(A.18.10)}
20904
20905@code{Ada.Containers.Ordered_Maps} @emph{(A.18.6)}
20906
20907@code{Ada.Containers.Ordered_Sets} @emph{(A.18.9)}
20908
20909@code{Ada.Containers.Synchronized_Queue_Interfaces} @emph{(A.18.27)}
20910
20911@code{Ada.Containers.Unbounded_Priority_Queues} @emph{(A.18.30)}
20912
20913@code{Ada.Containers.Unbounded_Synchronized_Queues} @emph{(A.18.28)}
20914
20915@code{Ada.Containers.Vectors} @emph{(A.18.2)}
20916
20917
20918@table @asis
20919
20920@item @code{Ada.Directories} @emph{(A.16)}
20921
20922This package provides operations on directories.
20923
20924@item @code{Ada.Directories.Hierarchical_File_Names} @emph{(A.16.1)}
20925
20926This package provides additional directory operations handling
20927hiearchical file names.
20928
20929@item @code{Ada.Directories.Information} @emph{(A.16)}
20930
20931This is an implementation defined package for additional directory
20932operations, which is not implemented in GNAT.
20933
20934@item @code{Ada.Decimal} @emph{(F.2)}
20935
20936This package provides constants describing the range of decimal numbers
20937implemented, and also a decimal divide routine (analogous to the COBOL
20938verb DIVIDE … GIVING … REMAINDER …)
20939
20940@item @code{Ada.Direct_IO} @emph{(A.8.4)}
20941
20942This package provides input-output using a model of a set of records of
20943fixed-length, containing an arbitrary definite Ada type, indexed by an
20944integer record number.
20945
20946@item @code{Ada.Dispatching} @emph{(D.2.1)}
20947
20948A parent package containing definitions for task dispatching operations.
20949
20950@item @code{Ada.Dispatching.EDF} @emph{(D.2.6)}
20951
20952Not implemented in GNAT.
20953
20954@item @code{Ada.Dispatching.Non_Preemptive} @emph{(D.2.4)}
20955
20956Not implemented in GNAT.
20957
20958@item @code{Ada.Dispatching.Round_Robin} @emph{(D.2.5)}
20959
20960Not implemented in GNAT.
20961
20962@item @code{Ada.Dynamic_Priorities} @emph{(D.5)}
20963
20964This package allows the priorities of a task to be adjusted dynamically
20965as the task is running.
20966
20967@item @code{Ada.Environment_Variables} @emph{(A.17)}
20968
20969This package provides facilities for accessing environment variables.
20970
20971@item @code{Ada.Exceptions} @emph{(11.4.1)}
20972
20973This package provides additional information on exceptions, and also
20974contains facilities for treating exceptions as data objects, and raising
20975exceptions with associated messages.
20976
20977@item @code{Ada.Execution_Time} @emph{(D.14)}
20978
20979This package provides CPU clock functionalities. It is not implemented on
20980all targets (see package spec for details).
20981
20982@item @code{Ada.Execution_Time.Group_Budgets} @emph{(D.14.2)}
20983
20984Not implemented in GNAT.
20985
20986@item @code{Ada.Execution_Time.Timers} @emph{(D.14.1)’}
20987
20988Not implemented in GNAT.
20989
20990@item @code{Ada.Finalization} @emph{(7.6)}
20991
20992This package contains the declarations and subprograms to support the
20993use of controlled types, providing for automatic initialization and
20994finalization (analogous to the constructors and destructors of C++).
20995
20996@item @code{Ada.Float_Text_IO} @emph{(A.10.9)}
20997
20998A library level instantiation of Text_IO.Float_IO for type Float.
20999
21000@item @code{Ada.Float_Wide_Text_IO} @emph{(A.10.9)}
21001
21002A library level instantiation of Wide_Text_IO.Float_IO for type Float.
21003
21004@item @code{Ada.Float_Wide_Wide_Text_IO} @emph{(A.10.9)}
21005
21006A library level instantiation of Wide_Wide_Text_IO.Float_IO for type Float.
21007
21008@item @code{Ada.Integer_Text_IO} @emph{(A.10.9)}
21009
21010A library level instantiation of Text_IO.Integer_IO for type Integer.
21011
21012@item @code{Ada.Integer_Wide_Text_IO} @emph{(A.10.9)}
21013
21014A library level instantiation of Wide_Text_IO.Integer_IO for type Integer.
21015
21016@item @code{Ada.Integer_Wide_Wide_Text_IO} @emph{(A.10.9)}
21017
21018A library level instantiation of Wide_Wide_Text_IO.Integer_IO for type Integer.
21019
21020@item @code{Ada.Interrupts} @emph{(C.3.2)}
21021
21022This package provides facilities for interfacing to interrupts, which
21023includes the set of signals or conditions that can be raised and
21024recognized as interrupts.
21025
21026@item @code{Ada.Interrupts.Names} @emph{(C.3.2)}
21027
21028This package provides the set of interrupt names (actually signal
21029or condition names) that can be handled by GNAT.
21030
21031@item @code{Ada.IO_Exceptions} @emph{(A.13)}
21032
21033This package defines the set of exceptions that can be raised by use of
21034the standard IO packages.
21035
21036@item @code{Ada.Iterator_Interfaces} @emph{(5.5.1)}
21037
21038This package provides a generic interface to generalized iterators.
21039
21040@item @code{Ada.Locales} @emph{(A.19)}
21041
21042This package provides declarations providing information (Language
21043and Country) about the current locale.
21044
21045@item @code{Ada.Numerics}
21046
21047This package contains some standard constants and exceptions used
21048throughout the numerics packages.  Note that the constants pi and e are
21049defined here, and it is better to use these definitions than rolling
21050your own.
21051
21052@item @code{Ada.Numerics.Complex_Arrays} @emph{(G.3.2)}
21053
21054Provides operations on arrays of complex numbers.
21055
21056@item @code{Ada.Numerics.Complex_Elementary_Functions}
21057
21058Provides the implementation of standard elementary functions (such as
21059log and trigonometric functions) operating on complex numbers using the
21060standard @code{Float} and the @code{Complex} and @code{Imaginary} types
21061created by the package @code{Numerics.Complex_Types}.
21062
21063@item @code{Ada.Numerics.Complex_Types}
21064
21065This is a predefined instantiation of
21066@code{Numerics.Generic_Complex_Types} using @code{Standard.Float} to
21067build the type @code{Complex} and @code{Imaginary}.
21068
21069@item @code{Ada.Numerics.Discrete_Random}
21070
21071This generic package provides a random number generator suitable for generating
21072uniformly distributed values of a specified discrete subtype.
21073
21074@item @code{Ada.Numerics.Float_Random}
21075
21076This package provides a random number generator suitable for generating
21077uniformly distributed floating point values in the unit interval.
21078
21079@item @code{Ada.Numerics.Generic_Complex_Elementary_Functions}
21080
21081This is a generic version of the package that provides the
21082implementation of standard elementary functions (such as log and
21083trigonometric functions) for an arbitrary complex type.
21084
21085The following predefined instantiations of this package are provided:
21086
21087
21088@itemize *
21089
21090@item
21091@code{Short_Float}
21092
21093@code{Ada.Numerics.Short_Complex_Elementary_Functions}
21094
21095@item
21096@code{Float}
21097
21098@code{Ada.Numerics.Complex_Elementary_Functions}
21099
21100@item
21101@code{Long_Float}
21102
21103@code{Ada.Numerics.Long_Complex_Elementary_Functions}
21104@end itemize
21105
21106@item @code{Ada.Numerics.Generic_Complex_Types}
21107
21108This is a generic package that allows the creation of complex types,
21109with associated complex arithmetic operations.
21110
21111The following predefined instantiations of this package exist
21112
21113
21114@itemize *
21115
21116@item
21117@code{Short_Float}
21118
21119@code{Ada.Numerics.Short_Complex_Complex_Types}
21120
21121@item
21122@code{Float}
21123
21124@code{Ada.Numerics.Complex_Complex_Types}
21125
21126@item
21127@code{Long_Float}
21128
21129@code{Ada.Numerics.Long_Complex_Complex_Types}
21130@end itemize
21131
21132@item @code{Ada.Numerics.Generic_Elementary_Functions}
21133
21134This is a generic package that provides the implementation of standard
21135elementary functions (such as log an trigonometric functions) for an
21136arbitrary float type.
21137
21138The following predefined instantiations of this package exist
21139
21140
21141@itemize *
21142
21143@item
21144@code{Short_Float}
21145
21146@code{Ada.Numerics.Short_Elementary_Functions}
21147
21148@item
21149@code{Float}
21150
21151@code{Ada.Numerics.Elementary_Functions}
21152
21153@item
21154@code{Long_Float}
21155
21156@code{Ada.Numerics.Long_Elementary_Functions}
21157@end itemize
21158
21159@item @code{Ada.Numerics.Generic_Real_Arrays} @emph{(G.3.1)}
21160
21161Generic operations on arrays of reals
21162
21163@item @code{Ada.Numerics.Real_Arrays} @emph{(G.3.1)}
21164
21165Preinstantiation of Ada.Numerics.Generic_Real_Arrays (Float).
21166
21167@item @code{Ada.Real_Time} @emph{(D.8)}
21168
21169This package provides facilities similar to those of @code{Calendar}, but
21170operating with a finer clock suitable for real time control. Note that
21171annex D requires that there be no backward clock jumps, and GNAT generally
21172guarantees this behavior, but of course if the external clock on which
21173the GNAT runtime depends is deliberately reset by some external event,
21174then such a backward jump may occur.
21175
21176@item @code{Ada.Real_Time.Timing_Events} @emph{(D.15)}
21177
21178Not implemented in GNAT.
21179
21180@item @code{Ada.Sequential_IO} @emph{(A.8.1)}
21181
21182This package provides input-output facilities for sequential files,
21183which can contain a sequence of values of a single type, which can be
21184any Ada type, including indefinite (unconstrained) types.
21185
21186@item @code{Ada.Storage_IO} @emph{(A.9)}
21187
21188This package provides a facility for mapping arbitrary Ada types to and
21189from a storage buffer.  It is primarily intended for the creation of new
21190IO packages.
21191
21192@item @code{Ada.Streams} @emph{(13.13.1)}
21193
21194This is a generic package that provides the basic support for the
21195concept of streams as used by the stream attributes (@code{Input},
21196@code{Output}, @code{Read} and @code{Write}).
21197
21198@item @code{Ada.Streams.Stream_IO} @emph{(A.12.1)}
21199
21200This package is a specialization of the type @code{Streams} defined in
21201package @code{Streams} together with a set of operations providing
21202Stream_IO capability.  The Stream_IO model permits both random and
21203sequential access to a file which can contain an arbitrary set of values
21204of one or more Ada types.
21205
21206@item @code{Ada.Strings} @emph{(A.4.1)}
21207
21208This package provides some basic constants used by the string handling
21209packages.
21210
21211@item @code{Ada.Strings.Bounded} @emph{(A.4.4)}
21212
21213This package provides facilities for handling variable length
21214strings.  The bounded model requires a maximum length.  It is thus
21215somewhat more limited than the unbounded model, but avoids the use of
21216dynamic allocation or finalization.
21217
21218@item @code{Ada.Strings.Bounded.Equal_Case_Insensitive} @emph{(A.4.10)}
21219
21220Provides case-insensitive comparisons of bounded strings
21221
21222@item @code{Ada.Strings.Bounded.Hash} @emph{(A.4.9)}
21223
21224This package provides a generic hash function for bounded strings
21225
21226@item @code{Ada.Strings.Bounded.Hash_Case_Insensitive} @emph{(A.4.9)}
21227
21228This package provides a generic hash function for bounded strings that
21229converts the string to be hashed to lower case.
21230
21231@item @code{Ada.Strings.Bounded.Less_Case_Insensitive} @emph{(A.4.10)}
21232
21233This package provides a comparison function for bounded strings that works
21234in a case insensitive manner by converting to lower case before the comparison.
21235
21236@item @code{Ada.Strings.Fixed} @emph{(A.4.3)}
21237
21238This package provides facilities for handling fixed length strings.
21239
21240@item @code{Ada.Strings.Fixed.Equal_Case_Insensitive} @emph{(A.4.10)}
21241
21242This package provides an equality function for fixed strings that compares
21243the strings after converting both to lower case.
21244
21245@item @code{Ada.Strings.Fixed.Hash_Case_Insensitive} @emph{(A.4.9)}
21246
21247This package provides a case insensitive hash function for fixed strings that
21248converts the string to lower case before computing the hash.
21249
21250@item @code{Ada.Strings.Fixed.Less_Case_Insensitive} @emph{(A.4.10)}
21251
21252This package provides a comparison function for fixed strings that works
21253in a case insensitive manner by converting to lower case before the comparison.
21254
21255@item @code{Ada.Strings.Hash} @emph{(A.4.9)}
21256
21257This package provides a hash function for strings.
21258
21259@item @code{Ada.Strings.Hash_Case_Insensitive} @emph{(A.4.9)}
21260
21261This package provides a hash function for strings that is case insensitive.
21262The string is converted to lower case before computing the hash.
21263
21264@item @code{Ada.Strings.Less_Case_Insensitive} @emph{(A.4.10)}
21265
21266This package provides a comparison function for\strings that works
21267in a case insensitive manner by converting to lower case before the comparison.
21268
21269@item @code{Ada.Strings.Maps} @emph{(A.4.2)}
21270
21271This package provides facilities for handling character mappings and
21272arbitrarily defined subsets of characters.  For instance it is useful in
21273defining specialized translation tables.
21274
21275@item @code{Ada.Strings.Maps.Constants} @emph{(A.4.6)}
21276
21277This package provides a standard set of predefined mappings and
21278predefined character sets.  For example, the standard upper to lower case
21279conversion table is found in this package.  Note that upper to lower case
21280conversion is non-trivial if you want to take the entire set of
21281characters, including extended characters like E with an acute accent,
21282into account.  You should use the mappings in this package (rather than
21283adding 32 yourself) to do case mappings.
21284
21285@item @code{Ada.Strings.Unbounded} @emph{(A.4.5)}
21286
21287This package provides facilities for handling variable length
21288strings.  The unbounded model allows arbitrary length strings, but
21289requires the use of dynamic allocation and finalization.
21290
21291@item @code{Ada.Strings.Unbounded.Equal_Case_Insensitive} @emph{(A.4.10)}
21292
21293Provides case-insensitive comparisons of unbounded strings
21294
21295@item @code{Ada.Strings.Unbounded.Hash} @emph{(A.4.9)}
21296
21297This package provides a generic hash function for unbounded strings
21298
21299@item @code{Ada.Strings.Unbounded.Hash_Case_Insensitive} @emph{(A.4.9)}
21300
21301This package provides a generic hash function for unbounded strings that
21302converts the string to be hashed to lower case.
21303
21304@item @code{Ada.Strings.Unbounded.Less_Case_Insensitive} @emph{(A.4.10)}
21305
21306This package provides a comparison function for unbounded strings that works
21307in a case insensitive manner by converting to lower case before the comparison.
21308
21309@item @code{Ada.Strings.UTF_Encoding} @emph{(A.4.11)}
21310
21311This package provides basic definitions for dealing with UTF-encoded strings.
21312
21313@item @code{Ada.Strings.UTF_Encoding.Conversions} @emph{(A.4.11)}
21314
21315This package provides conversion functions for UTF-encoded strings.
21316@end table
21317
21318@code{Ada.Strings.UTF_Encoding.Strings} @emph{(A.4.11)}
21319
21320@code{Ada.Strings.UTF_Encoding.Wide_Strings} @emph{(A.4.11)}
21321
21322
21323@table @asis
21324
21325@item @code{Ada.Strings.UTF_Encoding.Wide_Wide_Strings} @emph{(A.4.11)}
21326
21327These packages provide facilities for handling UTF encodings for
21328Strings, Wide_Strings and Wide_Wide_Strings.
21329@end table
21330
21331@code{Ada.Strings.Wide_Bounded} @emph{(A.4.7)}
21332
21333@code{Ada.Strings.Wide_Fixed} @emph{(A.4.7)}
21334
21335@code{Ada.Strings.Wide_Maps} @emph{(A.4.7)}
21336
21337
21338@table @asis
21339
21340@item @code{Ada.Strings.Wide_Unbounded} @emph{(A.4.7)}
21341
21342These packages provide analogous capabilities to the corresponding
21343packages without @code{Wide_} in the name, but operate with the types
21344@code{Wide_String} and @code{Wide_Character} instead of @code{String}
21345and @code{Character}. Versions of all the child packages are available.
21346@end table
21347
21348@code{Ada.Strings.Wide_Wide_Bounded} @emph{(A.4.7)}
21349
21350@code{Ada.Strings.Wide_Wide_Fixed} @emph{(A.4.7)}
21351
21352@code{Ada.Strings.Wide_Wide_Maps} @emph{(A.4.7)}
21353
21354
21355@table @asis
21356
21357@item @code{Ada.Strings.Wide_Wide_Unbounded} @emph{(A.4.7)}
21358
21359These packages provide analogous capabilities to the corresponding
21360packages without @code{Wide_} in the name, but operate with the types
21361@code{Wide_Wide_String} and @code{Wide_Wide_Character} instead
21362of @code{String} and @code{Character}.
21363
21364@item @code{Ada.Synchronous_Barriers} @emph{(D.10.1)}
21365
21366This package provides facilities for synchronizing tasks at a low level
21367with barriers.
21368
21369@item @code{Ada.Synchronous_Task_Control} @emph{(D.10)}
21370
21371This package provides some standard facilities for controlling task
21372communication in a synchronous manner.
21373
21374@item @code{Ada.Synchronous_Task_Control.EDF} @emph{(D.10)}
21375
21376Not implemented in GNAT.
21377
21378@item @code{Ada.Tags}
21379
21380This package contains definitions for manipulation of the tags of tagged
21381values.
21382
21383@item @code{Ada.Tags.Generic_Dispatching_Constructor} @emph{(3.9)}
21384
21385This package provides a way of constructing tagged class-wide values given
21386only the tag value.
21387
21388@item @code{Ada.Task_Attributes} @emph{(C.7.2)}
21389
21390This package provides the capability of associating arbitrary
21391task-specific data with separate tasks.
21392
21393@item @code{Ada.Task_Identifification} @emph{(C.7.1)}
21394
21395This package provides capabilities for task identification.
21396
21397@item @code{Ada.Task_Termination} @emph{(C.7.3)}
21398
21399This package provides control over task termination.
21400
21401@item @code{Ada.Text_IO}
21402
21403This package provides basic text input-output capabilities for
21404character, string and numeric data.  The subpackages of this
21405package are listed next. Note that although these are defined
21406as subpackages in the RM, they are actually transparently
21407implemented as child packages in GNAT, meaning that they
21408are only loaded if needed.
21409
21410@item @code{Ada.Text_IO.Decimal_IO}
21411
21412Provides input-output facilities for decimal fixed-point types
21413
21414@item @code{Ada.Text_IO.Enumeration_IO}
21415
21416Provides input-output facilities for enumeration types.
21417
21418@item @code{Ada.Text_IO.Fixed_IO}
21419
21420Provides input-output facilities for ordinary fixed-point types.
21421
21422@item @code{Ada.Text_IO.Float_IO}
21423
21424Provides input-output facilities for float types.  The following
21425predefined instantiations of this generic package are available:
21426
21427
21428@itemize *
21429
21430@item
21431@code{Short_Float}
21432
21433@code{Short_Float_Text_IO}
21434
21435@item
21436@code{Float}
21437
21438@code{Float_Text_IO}
21439
21440@item
21441@code{Long_Float}
21442
21443@code{Long_Float_Text_IO}
21444@end itemize
21445
21446@item @code{Ada.Text_IO.Integer_IO}
21447
21448Provides input-output facilities for integer types.  The following
21449predefined instantiations of this generic package are available:
21450
21451
21452@itemize *
21453
21454@item
21455@code{Short_Short_Integer}
21456
21457@code{Ada.Short_Short_Integer_Text_IO}
21458
21459@item
21460@code{Short_Integer}
21461
21462@code{Ada.Short_Integer_Text_IO}
21463
21464@item
21465@code{Integer}
21466
21467@code{Ada.Integer_Text_IO}
21468
21469@item
21470@code{Long_Integer}
21471
21472@code{Ada.Long_Integer_Text_IO}
21473
21474@item
21475@code{Long_Long_Integer}
21476
21477@code{Ada.Long_Long_Integer_Text_IO}
21478@end itemize
21479
21480@item @code{Ada.Text_IO.Modular_IO}
21481
21482Provides input-output facilities for modular (unsigned) types.
21483
21484@item @code{Ada.Text_IO.Bounded_IO (A.10.11)}
21485
21486Provides input-output facilities for bounded strings.
21487
21488@item @code{Ada.Text_IO.Complex_IO (G.1.3)}
21489
21490This package provides basic text input-output capabilities for complex
21491data.
21492
21493@item @code{Ada.Text_IO.Editing (F.3.3)}
21494
21495This package contains routines for edited output, analogous to the use
21496of pictures in COBOL.  The picture formats used by this package are a
21497close copy of the facility in COBOL.
21498
21499@item @code{Ada.Text_IO.Text_Streams (A.12.2)}
21500
21501This package provides a facility that allows Text_IO files to be treated
21502as streams, so that the stream attributes can be used for writing
21503arbitrary data, including binary data, to Text_IO files.
21504
21505@item @code{Ada.Text_IO.Unbounded_IO (A.10.12)}
21506
21507This package provides input-output facilities for unbounded strings.
21508
21509@item @code{Ada.Unchecked_Conversion (13.9)}
21510
21511This generic package allows arbitrary conversion from one type to
21512another of the same size, providing for breaking the type safety in
21513special circumstances.
21514
21515If the types have the same Size (more accurately the same Value_Size),
21516then the effect is simply to transfer the bits from the source to the
21517target type without any modification.  This usage is well defined, and
21518for simple types whose representation is typically the same across
21519all implementations, gives a portable method of performing such
21520conversions.
21521
21522If the types do not have the same size, then the result is implementation
21523defined, and thus may be non-portable.  The following describes how GNAT
21524handles such unchecked conversion cases.
21525
21526If the types are of different sizes, and are both discrete types, then
21527the effect is of a normal type conversion without any constraint checking.
21528In particular if the result type has a larger size, the result will be
21529zero or sign extended.  If the result type has a smaller size, the result
21530will be truncated by ignoring high order bits.
21531
21532If the types are of different sizes, and are not both discrete types,
21533then the conversion works as though pointers were created to the source
21534and target, and the pointer value is converted.  The effect is that bits
21535are copied from successive low order storage units and bits of the source
21536up to the length of the target type.
21537
21538A warning is issued if the lengths differ, since the effect in this
21539case is implementation dependent, and the above behavior may not match
21540that of some other compiler.
21541
21542A pointer to one type may be converted to a pointer to another type using
21543unchecked conversion.  The only case in which the effect is undefined is
21544when one or both pointers are pointers to unconstrained array types.  In
21545this case, the bounds information may get incorrectly transferred, and in
21546particular, GNAT uses double size pointers for such types, and it is
21547meaningless to convert between such pointer types.  GNAT will issue a
21548warning if the alignment of the target designated type is more strict
21549than the alignment of the source designated type (since the result may
21550be unaligned in this case).
21551
21552A pointer other than a pointer to an unconstrained array type may be
21553converted to and from System.Address.  Such usage is common in Ada 83
21554programs, but note that Ada.Address_To_Access_Conversions is the
21555preferred method of performing such conversions in Ada 95 and Ada 2005.
21556Neither
21557unchecked conversion nor Ada.Address_To_Access_Conversions should be
21558used in conjunction with pointers to unconstrained objects, since
21559the bounds information cannot be handled correctly in this case.
21560
21561@item @code{Ada.Unchecked_Deallocation} @emph{(13.11.2)}
21562
21563This generic package allows explicit freeing of storage previously
21564allocated by use of an allocator.
21565
21566@item @code{Ada.Wide_Text_IO} @emph{(A.11)}
21567
21568This package is similar to @code{Ada.Text_IO}, except that the external
21569file supports wide character representations, and the internal types are
21570@code{Wide_Character} and @code{Wide_String} instead of @code{Character}
21571and @code{String}. The corresponding set of nested packages and child
21572packages are defined.
21573
21574@item @code{Ada.Wide_Wide_Text_IO} @emph{(A.11)}
21575
21576This package is similar to @code{Ada.Text_IO}, except that the external
21577file supports wide character representations, and the internal types are
21578@code{Wide_Character} and @code{Wide_String} instead of @code{Character}
21579and @code{String}. The corresponding set of nested packages and child
21580packages are defined.
21581@end table
21582
21583For packages in Interfaces and System, all the RM defined packages are
21584available in GNAT, see the Ada 2012 RM for full details.
21585
21586@node The Implementation of Standard I/O,The GNAT Library,Standard Library Routines,Top
21587@anchor{gnat_rm/the_implementation_of_standard_i_o doc}@anchor{2a1}@anchor{gnat_rm/the_implementation_of_standard_i_o id1}@anchor{2a2}@anchor{gnat_rm/the_implementation_of_standard_i_o the-implementation-of-standard-i-o}@anchor{f}
21588@chapter The Implementation of Standard I/O
21589
21590
21591GNAT implements all the required input-output facilities described in
21592A.6 through A.14.  These sections of the Ada Reference Manual describe the
21593required behavior of these packages from the Ada point of view, and if
21594you are writing a portable Ada program that does not need to know the
21595exact manner in which Ada maps to the outside world when it comes to
21596reading or writing external files, then you do not need to read this
21597chapter.  As long as your files are all regular files (not pipes or
21598devices), and as long as you write and read the files only from Ada, the
21599description in the Ada Reference Manual is sufficient.
21600
21601However, if you want to do input-output to pipes or other devices, such
21602as the keyboard or screen, or if the files you are dealing with are
21603either generated by some other language, or to be read by some other
21604language, then you need to know more about the details of how the GNAT
21605implementation of these input-output facilities behaves.
21606
21607In this chapter we give a detailed description of exactly how GNAT
21608interfaces to the file system.  As always, the sources of the system are
21609available to you for answering questions at an even more detailed level,
21610but for most purposes the information in this chapter will suffice.
21611
21612Another reason that you may need to know more about how input-output is
21613implemented arises when you have a program written in mixed languages
21614where, for example, files are shared between the C and Ada sections of
21615the same program.  GNAT provides some additional facilities, in the form
21616of additional child library packages, that facilitate this sharing, and
21617these additional facilities are also described in this chapter.
21618
21619@menu
21620* Standard I/O Packages::
21621* FORM Strings::
21622* Direct_IO::
21623* Sequential_IO::
21624* Text_IO::
21625* Wide_Text_IO::
21626* Wide_Wide_Text_IO::
21627* Stream_IO::
21628* Text Translation::
21629* Shared Files::
21630* Filenames encoding::
21631* File content encoding::
21632* Open Modes::
21633* Operations on C Streams::
21634* Interfacing to C Streams::
21635
21636@end menu
21637
21638@node Standard I/O Packages,FORM Strings,,The Implementation of Standard I/O
21639@anchor{gnat_rm/the_implementation_of_standard_i_o id2}@anchor{2a3}@anchor{gnat_rm/the_implementation_of_standard_i_o standard-i-o-packages}@anchor{2a4}
21640@section Standard I/O Packages
21641
21642
21643The Standard I/O packages described in Annex A for
21644
21645
21646@itemize *
21647
21648@item
21649Ada.Text_IO
21650
21651@item
21652Ada.Text_IO.Complex_IO
21653
21654@item
21655Ada.Text_IO.Text_Streams
21656
21657@item
21658Ada.Wide_Text_IO
21659
21660@item
21661Ada.Wide_Text_IO.Complex_IO
21662
21663@item
21664Ada.Wide_Text_IO.Text_Streams
21665
21666@item
21667Ada.Wide_Wide_Text_IO
21668
21669@item
21670Ada.Wide_Wide_Text_IO.Complex_IO
21671
21672@item
21673Ada.Wide_Wide_Text_IO.Text_Streams
21674
21675@item
21676Ada.Stream_IO
21677
21678@item
21679Ada.Sequential_IO
21680
21681@item
21682Ada.Direct_IO
21683@end itemize
21684
21685are implemented using the C
21686library streams facility; where
21687
21688
21689@itemize *
21690
21691@item
21692All files are opened using @code{fopen}.
21693
21694@item
21695All input/output operations use @code{fread}/@cite{fwrite}.
21696@end itemize
21697
21698There is no internal buffering of any kind at the Ada library level. The only
21699buffering is that provided at the system level in the implementation of the
21700library routines that support streams. This facilitates shared use of these
21701streams by mixed language programs. Note though that system level buffering is
21702explicitly enabled at elaboration of the standard I/O packages and that can
21703have an impact on mixed language programs, in particular those using I/O before
21704calling the Ada elaboration routine (e.g., adainit). It is recommended to call
21705the Ada elaboration routine before performing any I/O or when impractical,
21706flush the common I/O streams and in particular Standard_Output before
21707elaborating the Ada code.
21708
21709@node FORM Strings,Direct_IO,Standard I/O Packages,The Implementation of Standard I/O
21710@anchor{gnat_rm/the_implementation_of_standard_i_o form-strings}@anchor{2a5}@anchor{gnat_rm/the_implementation_of_standard_i_o id3}@anchor{2a6}
21711@section FORM Strings
21712
21713
21714The format of a FORM string in GNAT is:
21715
21716@example
21717"keyword=value,keyword=value,...,keyword=value"
21718@end example
21719
21720where letters may be in upper or lower case, and there are no spaces
21721between values.  The order of the entries is not important.  Currently
21722the following keywords defined.
21723
21724@example
21725TEXT_TRANSLATION=[YES|NO|TEXT|BINARY|U8TEXT|WTEXT|U16TEXT]
21726SHARED=[YES|NO]
21727WCEM=[n|h|u|s|e|8|b]
21728ENCODING=[UTF8|8BITS]
21729@end example
21730
21731The use of these parameters is described later in this section. If an
21732unrecognized keyword appears in a form string, it is silently ignored
21733and not considered invalid.
21734
21735@node Direct_IO,Sequential_IO,FORM Strings,The Implementation of Standard I/O
21736@anchor{gnat_rm/the_implementation_of_standard_i_o direct-io}@anchor{2a7}@anchor{gnat_rm/the_implementation_of_standard_i_o id4}@anchor{2a8}
21737@section Direct_IO
21738
21739
21740Direct_IO can only be instantiated for definite types.  This is a
21741restriction of the Ada language, which means that the records are fixed
21742length (the length being determined by @code{type'Size}, rounded
21743up to the next storage unit boundary if necessary).
21744
21745The records of a Direct_IO file are simply written to the file in index
21746sequence, with the first record starting at offset zero, and subsequent
21747records following.  There is no control information of any kind.  For
21748example, if 32-bit integers are being written, each record takes
217494-bytes, so the record at index @code{K} starts at offset
21750(@code{K}-1)*4.
21751
21752There is no limit on the size of Direct_IO files, they are expanded as
21753necessary to accommodate whatever records are written to the file.
21754
21755@node Sequential_IO,Text_IO,Direct_IO,The Implementation of Standard I/O
21756@anchor{gnat_rm/the_implementation_of_standard_i_o id5}@anchor{2a9}@anchor{gnat_rm/the_implementation_of_standard_i_o sequential-io}@anchor{2aa}
21757@section Sequential_IO
21758
21759
21760Sequential_IO may be instantiated with either a definite (constrained)
21761or indefinite (unconstrained) type.
21762
21763For the definite type case, the elements written to the file are simply
21764the memory images of the data values with no control information of any
21765kind.  The resulting file should be read using the same type, no validity
21766checking is performed on input.
21767
21768For the indefinite type case, the elements written consist of two
21769parts.  First is the size of the data item, written as the memory image
21770of a @code{Interfaces.C.size_t} value, followed by the memory image of
21771the data value.  The resulting file can only be read using the same
21772(unconstrained) type.  Normal assignment checks are performed on these
21773read operations, and if these checks fail, @code{Data_Error} is
21774raised.  In particular, in the array case, the lengths must match, and in
21775the variant record case, if the variable for a particular read operation
21776is constrained, the discriminants must match.
21777
21778Note that it is not possible to use Sequential_IO to write variable
21779length array items, and then read the data back into different length
21780arrays.  For example, the following will raise @code{Data_Error}:
21781
21782@example
21783package IO is new Sequential_IO (String);
21784F : IO.File_Type;
21785S : String (1..4);
21786...
21787IO.Create (F)
21788IO.Write (F, "hello!")
21789IO.Reset (F, Mode=>In_File);
21790IO.Read (F, S);
21791Put_Line (S);
21792@end example
21793
21794On some Ada implementations, this will print @code{hell}, but the program is
21795clearly incorrect, since there is only one element in the file, and that
21796element is the string @code{hello!}.
21797
21798In Ada 95 and Ada 2005, this kind of behavior can be legitimately achieved
21799using Stream_IO, and this is the preferred mechanism.  In particular, the
21800above program fragment rewritten to use Stream_IO will work correctly.
21801
21802@node Text_IO,Wide_Text_IO,Sequential_IO,The Implementation of Standard I/O
21803@anchor{gnat_rm/the_implementation_of_standard_i_o id6}@anchor{2ab}@anchor{gnat_rm/the_implementation_of_standard_i_o text-io}@anchor{2ac}
21804@section Text_IO
21805
21806
21807Text_IO files consist of a stream of characters containing the following
21808special control characters:
21809
21810@example
21811LF (line feed, 16#0A#) Line Mark
21812FF (form feed, 16#0C#) Page Mark
21813@end example
21814
21815A canonical Text_IO file is defined as one in which the following
21816conditions are met:
21817
21818
21819@itemize *
21820
21821@item
21822The character @code{LF} is used only as a line mark, i.e., to mark the end
21823of the line.
21824
21825@item
21826The character @code{FF} is used only as a page mark, i.e., to mark the
21827end of a page and consequently can appear only immediately following a
21828@code{LF} (line mark) character.
21829
21830@item
21831The file ends with either @code{LF} (line mark) or @code{LF}-@cite{FF}
21832(line mark, page mark).  In the former case, the page mark is implicitly
21833assumed to be present.
21834@end itemize
21835
21836A file written using Text_IO will be in canonical form provided that no
21837explicit @code{LF} or @code{FF} characters are written using @code{Put}
21838or @code{Put_Line}.  There will be no @code{FF} character at the end of
21839the file unless an explicit @code{New_Page} operation was performed
21840before closing the file.
21841
21842A canonical Text_IO file that is a regular file (i.e., not a device or a
21843pipe) can be read using any of the routines in Text_IO.  The
21844semantics in this case will be exactly as defined in the Ada Reference
21845Manual, and all the routines in Text_IO are fully implemented.
21846
21847A text file that does not meet the requirements for a canonical Text_IO
21848file has one of the following:
21849
21850
21851@itemize *
21852
21853@item
21854The file contains @code{FF} characters not immediately following a
21855@code{LF} character.
21856
21857@item
21858The file contains @code{LF} or @code{FF} characters written by
21859@code{Put} or @code{Put_Line}, which are not logically considered to be
21860line marks or page marks.
21861
21862@item
21863The file ends in a character other than @code{LF} or @code{FF},
21864i.e., there is no explicit line mark or page mark at the end of the file.
21865@end itemize
21866
21867Text_IO can be used to read such non-standard text files but subprograms
21868to do with line or page numbers do not have defined meanings.  In
21869particular, a @code{FF} character that does not follow a @code{LF}
21870character may or may not be treated as a page mark from the point of
21871view of page and line numbering.  Every @code{LF} character is considered
21872to end a line, and there is an implied @code{LF} character at the end of
21873the file.
21874
21875@menu
21876* Stream Pointer Positioning::
21877* Reading and Writing Non-Regular Files::
21878* Get_Immediate::
21879* Treating Text_IO Files as Streams::
21880* Text_IO Extensions::
21881* Text_IO Facilities for Unbounded Strings::
21882
21883@end menu
21884
21885@node Stream Pointer Positioning,Reading and Writing Non-Regular Files,,Text_IO
21886@anchor{gnat_rm/the_implementation_of_standard_i_o id7}@anchor{2ad}@anchor{gnat_rm/the_implementation_of_standard_i_o stream-pointer-positioning}@anchor{2ae}
21887@subsection Stream Pointer Positioning
21888
21889
21890@code{Ada.Text_IO} has a definition of current position for a file that
21891is being read.  No internal buffering occurs in Text_IO, and usually the
21892physical position in the stream used to implement the file corresponds
21893to this logical position defined by Text_IO.  There are two exceptions:
21894
21895
21896@itemize *
21897
21898@item
21899After a call to @code{End_Of_Page} that returns @code{True}, the stream
21900is positioned past the @code{LF} (line mark) that precedes the page
21901mark.  Text_IO maintains an internal flag so that subsequent read
21902operations properly handle the logical position which is unchanged by
21903the @code{End_Of_Page} call.
21904
21905@item
21906After a call to @code{End_Of_File} that returns @code{True}, if the
21907Text_IO file was positioned before the line mark at the end of file
21908before the call, then the logical position is unchanged, but the stream
21909is physically positioned right at the end of file (past the line mark,
21910and past a possible page mark following the line mark.  Again Text_IO
21911maintains internal flags so that subsequent read operations properly
21912handle the logical position.
21913@end itemize
21914
21915These discrepancies have no effect on the observable behavior of
21916Text_IO, but if a single Ada stream is shared between a C program and
21917Ada program, or shared (using @code{shared=yes} in the form string)
21918between two Ada files, then the difference may be observable in some
21919situations.
21920
21921@node Reading and Writing Non-Regular Files,Get_Immediate,Stream Pointer Positioning,Text_IO
21922@anchor{gnat_rm/the_implementation_of_standard_i_o id8}@anchor{2af}@anchor{gnat_rm/the_implementation_of_standard_i_o reading-and-writing-non-regular-files}@anchor{2b0}
21923@subsection Reading and Writing Non-Regular Files
21924
21925
21926A non-regular file is a device (such as a keyboard), or a pipe.  Text_IO
21927can be used for reading and writing.  Writing is not affected and the
21928sequence of characters output is identical to the normal file case, but
21929for reading, the behavior of Text_IO is modified to avoid undesirable
21930look-ahead as follows:
21931
21932An input file that is not a regular file is considered to have no page
21933marks.  Any @code{Ascii.FF} characters (the character normally used for a
21934page mark) appearing in the file are considered to be data
21935characters.  In particular:
21936
21937
21938@itemize *
21939
21940@item
21941@code{Get_Line} and @code{Skip_Line} do not test for a page mark
21942following a line mark.  If a page mark appears, it will be treated as a
21943data character.
21944
21945@item
21946This avoids the need to wait for an extra character to be typed or
21947entered from the pipe to complete one of these operations.
21948
21949@item
21950@code{End_Of_Page} always returns @code{False}
21951
21952@item
21953@code{End_Of_File} will return @code{False} if there is a page mark at
21954the end of the file.
21955@end itemize
21956
21957Output to non-regular files is the same as for regular files.  Page marks
21958may be written to non-regular files using @code{New_Page}, but as noted
21959above they will not be treated as page marks on input if the output is
21960piped to another Ada program.
21961
21962Another important discrepancy when reading non-regular files is that the end
21963of file indication is not ‘sticky’.  If an end of file is entered, e.g., by
21964pressing the @code{EOT} key,
21965then end of file
21966is signaled once (i.e., the test @code{End_Of_File}
21967will yield @code{True}, or a read will
21968raise @code{End_Error}), but then reading can resume
21969to read data past that end of
21970file indication, until another end of file indication is entered.
21971
21972@node Get_Immediate,Treating Text_IO Files as Streams,Reading and Writing Non-Regular Files,Text_IO
21973@anchor{gnat_rm/the_implementation_of_standard_i_o get-immediate}@anchor{2b1}@anchor{gnat_rm/the_implementation_of_standard_i_o id9}@anchor{2b2}
21974@subsection Get_Immediate
21975
21976
21977@geindex Get_Immediate
21978
21979Get_Immediate returns the next character (including control characters)
21980from the input file.  In particular, Get_Immediate will return LF or FF
21981characters used as line marks or page marks.  Such operations leave the
21982file positioned past the control character, and it is thus not treated
21983as having its normal function.  This means that page, line and column
21984counts after this kind of Get_Immediate call are set as though the mark
21985did not occur.  In the case where a Get_Immediate leaves the file
21986positioned between the line mark and page mark (which is not normally
21987possible), it is undefined whether the FF character will be treated as a
21988page mark.
21989
21990@node Treating Text_IO Files as Streams,Text_IO Extensions,Get_Immediate,Text_IO
21991@anchor{gnat_rm/the_implementation_of_standard_i_o id10}@anchor{2b3}@anchor{gnat_rm/the_implementation_of_standard_i_o treating-text-io-files-as-streams}@anchor{2b4}
21992@subsection Treating Text_IO Files as Streams
21993
21994
21995@geindex Stream files
21996
21997The package @code{Text_IO.Streams} allows a @code{Text_IO} file to be treated
21998as a stream.  Data written to a @code{Text_IO} file in this stream mode is
21999binary data.  If this binary data contains bytes 16#0A# (@code{LF}) or
2200016#0C# (@code{FF}), the resulting file may have non-standard
22001format.  Similarly if read operations are used to read from a Text_IO
22002file treated as a stream, then @code{LF} and @code{FF} characters may be
22003skipped and the effect is similar to that described above for
22004@code{Get_Immediate}.
22005
22006@node Text_IO Extensions,Text_IO Facilities for Unbounded Strings,Treating Text_IO Files as Streams,Text_IO
22007@anchor{gnat_rm/the_implementation_of_standard_i_o id11}@anchor{2b5}@anchor{gnat_rm/the_implementation_of_standard_i_o text-io-extensions}@anchor{2b6}
22008@subsection Text_IO Extensions
22009
22010
22011@geindex Text_IO extensions
22012
22013A package GNAT.IO_Aux in the GNAT library provides some useful extensions
22014to the standard @code{Text_IO} package:
22015
22016
22017@itemize *
22018
22019@item
22020function File_Exists (Name : String) return Boolean;
22021Determines if a file of the given name exists.
22022
22023@item
22024function Get_Line return String;
22025Reads a string from the standard input file.  The value returned is exactly
22026the length of the line that was read.
22027
22028@item
22029function Get_Line (File : Ada.Text_IO.File_Type) return String;
22030Similar, except that the parameter File specifies the file from which
22031the string is to be read.
22032@end itemize
22033
22034@node Text_IO Facilities for Unbounded Strings,,Text_IO Extensions,Text_IO
22035@anchor{gnat_rm/the_implementation_of_standard_i_o id12}@anchor{2b7}@anchor{gnat_rm/the_implementation_of_standard_i_o text-io-facilities-for-unbounded-strings}@anchor{2b8}
22036@subsection Text_IO Facilities for Unbounded Strings
22037
22038
22039@geindex Text_IO for unbounded strings
22040
22041@geindex Unbounded_String
22042@geindex Text_IO operations
22043
22044The package @code{Ada.Strings.Unbounded.Text_IO}
22045in library files @code{a-suteio.ads/adb} contains some GNAT-specific
22046subprograms useful for Text_IO operations on unbounded strings:
22047
22048
22049@itemize *
22050
22051@item
22052function Get_Line (File : File_Type) return Unbounded_String;
22053Reads a line from the specified file
22054and returns the result as an unbounded string.
22055
22056@item
22057procedure Put (File : File_Type; U : Unbounded_String);
22058Writes the value of the given unbounded string to the specified file
22059Similar to the effect of
22060@code{Put (To_String (U))} except that an extra copy is avoided.
22061
22062@item
22063procedure Put_Line (File : File_Type; U : Unbounded_String);
22064Writes the value of the given unbounded string to the specified file,
22065followed by a @code{New_Line}.
22066Similar to the effect of @code{Put_Line (To_String (U))} except
22067that an extra copy is avoided.
22068@end itemize
22069
22070In the above procedures, @code{File} is of type @code{Ada.Text_IO.File_Type}
22071and is optional.  If the parameter is omitted, then the standard input or
22072output file is referenced as appropriate.
22073
22074The package @code{Ada.Strings.Wide_Unbounded.Wide_Text_IO} in library
22075files @code{a-swuwti.ads} and @code{a-swuwti.adb} provides similar extended
22076@code{Wide_Text_IO} functionality for unbounded wide strings.
22077
22078The package @code{Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO} in library
22079files @code{a-szuzti.ads} and @code{a-szuzti.adb} provides similar extended
22080@code{Wide_Wide_Text_IO} functionality for unbounded wide wide strings.
22081
22082@node Wide_Text_IO,Wide_Wide_Text_IO,Text_IO,The Implementation of Standard I/O
22083@anchor{gnat_rm/the_implementation_of_standard_i_o id13}@anchor{2b9}@anchor{gnat_rm/the_implementation_of_standard_i_o wide-text-io}@anchor{2ba}
22084@section Wide_Text_IO
22085
22086
22087@code{Wide_Text_IO} is similar in most respects to Text_IO, except that
22088both input and output files may contain special sequences that represent
22089wide character values.  The encoding scheme for a given file may be
22090specified using a FORM parameter:
22091
22092@example
22093WCEM=`x`
22094@end example
22095
22096as part of the FORM string (WCEM = wide character encoding method),
22097where @code{x} is one of the following characters
22098
22099
22100@multitable {xxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxx}
22101@headitem
22102
22103Character
22104
22105@tab
22106
22107Encoding
22108
22109@item
22110
22111@emph{h}
22112
22113@tab
22114
22115Hex ESC encoding
22116
22117@item
22118
22119@emph{u}
22120
22121@tab
22122
22123Upper half encoding
22124
22125@item
22126
22127@emph{s}
22128
22129@tab
22130
22131Shift-JIS encoding
22132
22133@item
22134
22135@emph{e}
22136
22137@tab
22138
22139EUC Encoding
22140
22141@item
22142
22143@emph{8}
22144
22145@tab
22146
22147UTF-8 encoding
22148
22149@item
22150
22151@emph{b}
22152
22153@tab
22154
22155Brackets encoding
22156
22157@end multitable
22158
22159
22160The encoding methods match those that
22161can be used in a source
22162program, but there is no requirement that the encoding method used for
22163the source program be the same as the encoding method used for files,
22164and different files may use different encoding methods.
22165
22166The default encoding method for the standard files, and for opened files
22167for which no WCEM parameter is given in the FORM string matches the
22168wide character encoding specified for the main program (the default
22169being brackets encoding if no coding method was specified with -gnatW).
22170
22171
22172@table @asis
22173
22174@item @emph{Hex Coding}
22175
22176In this encoding, a wide character is represented by a five character
22177sequence:
22178@end table
22179
22180@example
22181ESC a b c d
22182@end example
22183
22184
22185@quotation
22186
22187where @code{a}, @code{b}, @code{c}, @code{d} are the four hexadecimal
22188characters (using upper case letters) of the wide character code.  For
22189example, ESC A345 is used to represent the wide character with code
2219016#A345#.  This scheme is compatible with use of the full
22191@code{Wide_Character} set.
22192@end quotation
22193
22194
22195@table @asis
22196
22197@item @emph{Upper Half Coding}
22198
22199The wide character with encoding 16#abcd#, where the upper bit is on
22200(i.e., a is in the range 8-F) is represented as two bytes 16#ab# and
2220116#cd#.  The second byte may never be a format control character, but is
22202not required to be in the upper half.  This method can be also used for
22203shift-JIS or EUC where the internal coding matches the external coding.
22204
22205@item @emph{Shift JIS Coding}
22206
22207A wide character is represented by a two character sequence 16#ab# and
2220816#cd#, with the restrictions described for upper half encoding as
22209described above.  The internal character code is the corresponding JIS
22210character according to the standard algorithm for Shift-JIS
22211conversion.  Only characters defined in the JIS code set table can be
22212used with this encoding method.
22213
22214@item @emph{EUC Coding}
22215
22216A wide character is represented by a two character sequence 16#ab# and
2221716#cd#, with both characters being in the upper half.  The internal
22218character code is the corresponding JIS character according to the EUC
22219encoding algorithm.  Only characters defined in the JIS code set table
22220can be used with this encoding method.
22221
22222@item @emph{UTF-8 Coding}
22223
22224A wide character is represented using
22225UCS Transformation Format 8 (UTF-8) as defined in Annex R of ISO
2222610646-1/Am.2.  Depending on the character value, the representation
22227is a one, two, or three byte sequence:
22228@end table
22229
22230@example
2223116#0000#-16#007f#: 2#0xxxxxxx#
2223216#0080#-16#07ff#: 2#110xxxxx# 2#10xxxxxx#
2223316#0800#-16#ffff#: 2#1110xxxx# 2#10xxxxxx# 2#10xxxxxx#
22234@end example
22235
22236
22237@quotation
22238
22239where the @code{xxx} bits correspond to the left-padded bits of the
2224016-bit character value.  Note that all lower half ASCII characters
22241are represented as ASCII bytes and all upper half characters and
22242other wide characters are represented as sequences of upper-half
22243(The full UTF-8 scheme allows for encoding 31-bit characters as
222446-byte sequences, but in this implementation, all UTF-8 sequences
22245of four or more bytes length will raise a Constraint_Error, as
22246will all invalid UTF-8 sequences.)
22247@end quotation
22248
22249
22250@table @asis
22251
22252@item @emph{Brackets Coding}
22253
22254In this encoding, a wide character is represented by the following eight
22255character sequence:
22256@end table
22257
22258@example
22259[ " a b c d " ]
22260@end example
22261
22262
22263@quotation
22264
22265where @code{a}, @code{b}, @code{c}, @code{d} are the four hexadecimal
22266characters (using uppercase letters) of the wide character code.  For
22267example, @code{["A345"]} is used to represent the wide character with code
22268@code{16#A345#}.
22269This scheme is compatible with use of the full Wide_Character set.
22270On input, brackets coding can also be used for upper half characters,
22271e.g., @code{["C1"]} for lower case a.  However, on output, brackets notation
22272is only used for wide characters with a code greater than @code{16#FF#}.
22273
22274Note that brackets coding is not normally used in the context of
22275Wide_Text_IO or Wide_Wide_Text_IO, since it is really just designed as
22276a portable way of encoding source files. In the context of Wide_Text_IO
22277or Wide_Wide_Text_IO, it can only be used if the file does not contain
22278any instance of the left bracket character other than to encode wide
22279character values using the brackets encoding method. In practice it is
22280expected that some standard wide character encoding method such
22281as UTF-8 will be used for text input output.
22282
22283If brackets notation is used, then any occurrence of a left bracket
22284in the input file which is not the start of a valid wide character
22285sequence will cause Constraint_Error to be raised. It is possible to
22286encode a left bracket as [“5B”] and Wide_Text_IO and Wide_Wide_Text_IO
22287input will interpret this as a left bracket.
22288
22289However, when a left bracket is output, it will be output as a left bracket
22290and not as [“5B”]. We make this decision because for normal use of
22291Wide_Text_IO for outputting messages, it is unpleasant to clobber left
22292brackets. For example, if we write:
22293
22294@example
22295Put_Line ("Start of output [first run]");
22296@end example
22297
22298we really do not want to have the left bracket in this message clobbered so
22299that the output reads:
22300@end quotation
22301
22302@example
22303Start of output ["5B"]first run]
22304@end example
22305
22306
22307@quotation
22308
22309In practice brackets encoding is reasonably useful for normal Put_Line use
22310since we won’t get confused between left brackets and wide character
22311sequences in the output. But for input, or when files are written out
22312and read back in, it really makes better sense to use one of the standard
22313encoding methods such as UTF-8.
22314@end quotation
22315
22316For the coding schemes other than UTF-8, Hex, or Brackets encoding,
22317not all wide character
22318values can be represented.  An attempt to output a character that cannot
22319be represented using the encoding scheme for the file causes
22320Constraint_Error to be raised.  An invalid wide character sequence on
22321input also causes Constraint_Error to be raised.
22322
22323@menu
22324* Stream Pointer Positioning: Stream Pointer Positioning<2>.
22325* Reading and Writing Non-Regular Files: Reading and Writing Non-Regular Files<2>.
22326
22327@end menu
22328
22329@node Stream Pointer Positioning<2>,Reading and Writing Non-Regular Files<2>,,Wide_Text_IO
22330@anchor{gnat_rm/the_implementation_of_standard_i_o id14}@anchor{2bb}@anchor{gnat_rm/the_implementation_of_standard_i_o stream-pointer-positioning-1}@anchor{2bc}
22331@subsection Stream Pointer Positioning
22332
22333
22334@code{Ada.Wide_Text_IO} is similar to @code{Ada.Text_IO} in its handling
22335of stream pointer positioning (@ref{2ac,,Text_IO}).  There is one additional
22336case:
22337
22338If @code{Ada.Wide_Text_IO.Look_Ahead} reads a character outside the
22339normal lower ASCII set (i.e., a character in the range:
22340
22341@example
22342Wide_Character'Val (16#0080#) .. Wide_Character'Val (16#FFFF#)
22343@end example
22344
22345then although the logical position of the file pointer is unchanged by
22346the @code{Look_Ahead} call, the stream is physically positioned past the
22347wide character sequence.  Again this is to avoid the need for buffering
22348or backup, and all @code{Wide_Text_IO} routines check the internal
22349indication that this situation has occurred so that this is not visible
22350to a normal program using @code{Wide_Text_IO}.  However, this discrepancy
22351can be observed if the wide text file shares a stream with another file.
22352
22353@node Reading and Writing Non-Regular Files<2>,,Stream Pointer Positioning<2>,Wide_Text_IO
22354@anchor{gnat_rm/the_implementation_of_standard_i_o id15}@anchor{2bd}@anchor{gnat_rm/the_implementation_of_standard_i_o reading-and-writing-non-regular-files-1}@anchor{2be}
22355@subsection Reading and Writing Non-Regular Files
22356
22357
22358As in the case of Text_IO, when a non-regular file is read, it is
22359assumed that the file contains no page marks (any form characters are
22360treated as data characters), and @code{End_Of_Page} always returns
22361@code{False}.  Similarly, the end of file indication is not sticky, so
22362it is possible to read beyond an end of file.
22363
22364@node Wide_Wide_Text_IO,Stream_IO,Wide_Text_IO,The Implementation of Standard I/O
22365@anchor{gnat_rm/the_implementation_of_standard_i_o id16}@anchor{2bf}@anchor{gnat_rm/the_implementation_of_standard_i_o wide-wide-text-io}@anchor{2c0}
22366@section Wide_Wide_Text_IO
22367
22368
22369@code{Wide_Wide_Text_IO} is similar in most respects to Text_IO, except that
22370both input and output files may contain special sequences that represent
22371wide wide character values.  The encoding scheme for a given file may be
22372specified using a FORM parameter:
22373
22374@example
22375WCEM=`x`
22376@end example
22377
22378as part of the FORM string (WCEM = wide character encoding method),
22379where @code{x} is one of the following characters
22380
22381
22382@multitable {xxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxx}
22383@headitem
22384
22385Character
22386
22387@tab
22388
22389Encoding
22390
22391@item
22392
22393@emph{h}
22394
22395@tab
22396
22397Hex ESC encoding
22398
22399@item
22400
22401@emph{u}
22402
22403@tab
22404
22405Upper half encoding
22406
22407@item
22408
22409@emph{s}
22410
22411@tab
22412
22413Shift-JIS encoding
22414
22415@item
22416
22417@emph{e}
22418
22419@tab
22420
22421EUC Encoding
22422
22423@item
22424
22425@emph{8}
22426
22427@tab
22428
22429UTF-8 encoding
22430
22431@item
22432
22433@emph{b}
22434
22435@tab
22436
22437Brackets encoding
22438
22439@end multitable
22440
22441
22442The encoding methods match those that
22443can be used in a source
22444program, but there is no requirement that the encoding method used for
22445the source program be the same as the encoding method used for files,
22446and different files may use different encoding methods.
22447
22448The default encoding method for the standard files, and for opened files
22449for which no WCEM parameter is given in the FORM string matches the
22450wide character encoding specified for the main program (the default
22451being brackets encoding if no coding method was specified with -gnatW).
22452
22453
22454@table @asis
22455
22456@item @emph{UTF-8 Coding}
22457
22458A wide character is represented using
22459UCS Transformation Format 8 (UTF-8) as defined in Annex R of ISO
2246010646-1/Am.2.  Depending on the character value, the representation
22461is a one, two, three, or four byte sequence:
22462@end table
22463
22464@example
2246516#000000#-16#00007f#: 2#0xxxxxxx#
2246616#000080#-16#0007ff#: 2#110xxxxx# 2#10xxxxxx#
2246716#000800#-16#00ffff#: 2#1110xxxx# 2#10xxxxxx# 2#10xxxxxx#
2246816#010000#-16#10ffff#: 2#11110xxx# 2#10xxxxxx# 2#10xxxxxx# 2#10xxxxxx#
22469@end example
22470
22471
22472@quotation
22473
22474where the @code{xxx} bits correspond to the left-padded bits of the
2247521-bit character value.  Note that all lower half ASCII characters
22476are represented as ASCII bytes and all upper half characters and
22477other wide characters are represented as sequences of upper-half
22478characters.
22479@end quotation
22480
22481
22482@table @asis
22483
22484@item @emph{Brackets Coding}
22485
22486In this encoding, a wide wide character is represented by the following eight
22487character sequence if is in wide character range
22488@end table
22489
22490@example
22491[ " a b c d " ]
22492@end example
22493
22494
22495@quotation
22496
22497and by the following ten character sequence if not
22498@end quotation
22499
22500@example
22501[ " a b c d e f " ]
22502@end example
22503
22504
22505@quotation
22506
22507where @code{a}, @code{b}, @code{c}, @code{d}, @code{e}, and @code{f}
22508are the four or six hexadecimal
22509characters (using uppercase letters) of the wide wide character code.  For
22510example, @code{["01A345"]} is used to represent the wide wide character
22511with code @code{16#01A345#}.
22512
22513This scheme is compatible with use of the full Wide_Wide_Character set.
22514On input, brackets coding can also be used for upper half characters,
22515e.g., @code{["C1"]} for lower case a.  However, on output, brackets notation
22516is only used for wide characters with a code greater than @code{16#FF#}.
22517@end quotation
22518
22519If is also possible to use the other Wide_Character encoding methods,
22520such as Shift-JIS, but the other schemes cannot support the full range
22521of wide wide characters.
22522An attempt to output a character that cannot
22523be represented using the encoding scheme for the file causes
22524Constraint_Error to be raised.  An invalid wide character sequence on
22525input also causes Constraint_Error to be raised.
22526
22527@menu
22528* Stream Pointer Positioning: Stream Pointer Positioning<3>.
22529* Reading and Writing Non-Regular Files: Reading and Writing Non-Regular Files<3>.
22530
22531@end menu
22532
22533@node Stream Pointer Positioning<3>,Reading and Writing Non-Regular Files<3>,,Wide_Wide_Text_IO
22534@anchor{gnat_rm/the_implementation_of_standard_i_o id17}@anchor{2c1}@anchor{gnat_rm/the_implementation_of_standard_i_o stream-pointer-positioning-2}@anchor{2c2}
22535@subsection Stream Pointer Positioning
22536
22537
22538@code{Ada.Wide_Wide_Text_IO} is similar to @code{Ada.Text_IO} in its handling
22539of stream pointer positioning (@ref{2ac,,Text_IO}).  There is one additional
22540case:
22541
22542If @code{Ada.Wide_Wide_Text_IO.Look_Ahead} reads a character outside the
22543normal lower ASCII set (i.e., a character in the range:
22544
22545@example
22546Wide_Wide_Character'Val (16#0080#) .. Wide_Wide_Character'Val (16#10FFFF#)
22547@end example
22548
22549then although the logical position of the file pointer is unchanged by
22550the @code{Look_Ahead} call, the stream is physically positioned past the
22551wide character sequence.  Again this is to avoid the need for buffering
22552or backup, and all @code{Wide_Wide_Text_IO} routines check the internal
22553indication that this situation has occurred so that this is not visible
22554to a normal program using @code{Wide_Wide_Text_IO}.  However, this discrepancy
22555can be observed if the wide text file shares a stream with another file.
22556
22557@node Reading and Writing Non-Regular Files<3>,,Stream Pointer Positioning<3>,Wide_Wide_Text_IO
22558@anchor{gnat_rm/the_implementation_of_standard_i_o id18}@anchor{2c3}@anchor{gnat_rm/the_implementation_of_standard_i_o reading-and-writing-non-regular-files-2}@anchor{2c4}
22559@subsection Reading and Writing Non-Regular Files
22560
22561
22562As in the case of Text_IO, when a non-regular file is read, it is
22563assumed that the file contains no page marks (any form characters are
22564treated as data characters), and @code{End_Of_Page} always returns
22565@code{False}.  Similarly, the end of file indication is not sticky, so
22566it is possible to read beyond an end of file.
22567
22568@node Stream_IO,Text Translation,Wide_Wide_Text_IO,The Implementation of Standard I/O
22569@anchor{gnat_rm/the_implementation_of_standard_i_o id19}@anchor{2c5}@anchor{gnat_rm/the_implementation_of_standard_i_o stream-io}@anchor{2c6}
22570@section Stream_IO
22571
22572
22573A stream file is a sequence of bytes, where individual elements are
22574written to the file as described in the Ada Reference Manual.  The type
22575@code{Stream_Element} is simply a byte.  There are two ways to read or
22576write a stream file.
22577
22578
22579@itemize *
22580
22581@item
22582The operations @code{Read} and @code{Write} directly read or write a
22583sequence of stream elements with no control information.
22584
22585@item
22586The stream attributes applied to a stream file transfer data in the
22587manner described for stream attributes.
22588@end itemize
22589
22590@node Text Translation,Shared Files,Stream_IO,The Implementation of Standard I/O
22591@anchor{gnat_rm/the_implementation_of_standard_i_o id20}@anchor{2c7}@anchor{gnat_rm/the_implementation_of_standard_i_o text-translation}@anchor{2c8}
22592@section Text Translation
22593
22594
22595@code{Text_Translation=xxx} may be used as the Form parameter
22596passed to Text_IO.Create and Text_IO.Open. @code{Text_Translation=xxx}
22597has no effect on Unix systems. Possible values are:
22598
22599
22600@itemize *
22601
22602@item
22603@code{Yes} or @code{Text} is the default, which means to
22604translate LF to/from CR/LF on Windows systems.
22605
22606@code{No} disables this translation; i.e. it
22607uses binary mode. For output files, @code{Text_Translation=No}
22608may be used to create Unix-style files on
22609Windows.
22610
22611@item
22612@code{wtext} translation enabled in Unicode mode.
22613(corresponds to _O_WTEXT).
22614
22615@item
22616@code{u8text} translation enabled in Unicode UTF-8 mode.
22617(corresponds to O_U8TEXT).
22618
22619@item
22620@code{u16text} translation enabled in Unicode UTF-16
22621mode. (corresponds to_O_U16TEXT).
22622@end itemize
22623
22624@node Shared Files,Filenames encoding,Text Translation,The Implementation of Standard I/O
22625@anchor{gnat_rm/the_implementation_of_standard_i_o id21}@anchor{2c9}@anchor{gnat_rm/the_implementation_of_standard_i_o shared-files}@anchor{2ca}
22626@section Shared Files
22627
22628
22629Section A.14 of the Ada Reference Manual allows implementations to
22630provide a wide variety of behavior if an attempt is made to access the
22631same external file with two or more internal files.
22632
22633To provide a full range of functionality, while at the same time
22634minimizing the problems of portability caused by this implementation
22635dependence, GNAT handles file sharing as follows:
22636
22637
22638@itemize *
22639
22640@item
22641In the absence of a @code{shared=xxx} form parameter, an attempt
22642to open two or more files with the same full name is considered an error
22643and is not supported.  The exception @code{Use_Error} will be
22644raised.  Note that a file that is not explicitly closed by the program
22645remains open until the program terminates.
22646
22647@item
22648If the form parameter @code{shared=no} appears in the form string, the
22649file can be opened or created with its own separate stream identifier,
22650regardless of whether other files sharing the same external file are
22651opened.  The exact effect depends on how the C stream routines handle
22652multiple accesses to the same external files using separate streams.
22653
22654@item
22655If the form parameter @code{shared=yes} appears in the form string for
22656each of two or more files opened using the same full name, the same
22657stream is shared between these files, and the semantics are as described
22658in Ada Reference Manual, Section A.14.
22659@end itemize
22660
22661When a program that opens multiple files with the same name is ported
22662from another Ada compiler to GNAT, the effect will be that
22663@code{Use_Error} is raised.
22664
22665The documentation of the original compiler and the documentation of the
22666program should then be examined to determine if file sharing was
22667expected, and @code{shared=xxx} parameters added to @code{Open}
22668and @code{Create} calls as required.
22669
22670When a program is ported from GNAT to some other Ada compiler, no
22671special attention is required unless the @code{shared=xxx} form
22672parameter is used in the program.  In this case, you must examine the
22673documentation of the new compiler to see if it supports the required
22674file sharing semantics, and form strings modified appropriately.  Of
22675course it may be the case that the program cannot be ported if the
22676target compiler does not support the required functionality.  The best
22677approach in writing portable code is to avoid file sharing (and hence
22678the use of the @code{shared=xxx} parameter in the form string)
22679completely.
22680
22681One common use of file sharing in Ada 83 is the use of instantiations of
22682Sequential_IO on the same file with different types, to achieve
22683heterogeneous input-output.  Although this approach will work in GNAT if
22684@code{shared=yes} is specified, it is preferable in Ada to use Stream_IO
22685for this purpose (using the stream attributes)
22686
22687@node Filenames encoding,File content encoding,Shared Files,The Implementation of Standard I/O
22688@anchor{gnat_rm/the_implementation_of_standard_i_o filenames-encoding}@anchor{2cb}@anchor{gnat_rm/the_implementation_of_standard_i_o id22}@anchor{2cc}
22689@section Filenames encoding
22690
22691
22692An encoding form parameter can be used to specify the filename
22693encoding @code{encoding=xxx}.
22694
22695
22696@itemize *
22697
22698@item
22699If the form parameter @code{encoding=utf8} appears in the form string, the
22700filename must be encoded in UTF-8.
22701
22702@item
22703If the form parameter @code{encoding=8bits} appears in the form
22704string, the filename must be a standard 8bits string.
22705@end itemize
22706
22707In the absence of a @code{encoding=xxx} form parameter, the
22708encoding is controlled by the @code{GNAT_CODE_PAGE} environment
22709variable. And if not set @code{utf8} is assumed.
22710
22711
22712@table @asis
22713
22714@item @emph{CP_ACP}
22715
22716The current system Windows ANSI code page.
22717
22718@item @emph{CP_UTF8}
22719
22720UTF-8 encoding
22721@end table
22722
22723This encoding form parameter is only supported on the Windows
22724platform. On the other Operating Systems the run-time is supporting
22725UTF-8 natively.
22726
22727@node File content encoding,Open Modes,Filenames encoding,The Implementation of Standard I/O
22728@anchor{gnat_rm/the_implementation_of_standard_i_o file-content-encoding}@anchor{2cd}@anchor{gnat_rm/the_implementation_of_standard_i_o id23}@anchor{2ce}
22729@section File content encoding
22730
22731
22732For text files it is possible to specify the encoding to use. This is
22733controlled by the by the @code{GNAT_CCS_ENCODING} environment
22734variable. And if not set @code{TEXT} is assumed.
22735
22736The possible values are those supported on Windows:
22737
22738
22739@table @asis
22740
22741@item @emph{TEXT}
22742
22743Translated text mode
22744
22745@item @emph{WTEXT}
22746
22747Translated unicode encoding
22748
22749@item @emph{U16TEXT}
22750
22751Unicode 16-bit encoding
22752
22753@item @emph{U8TEXT}
22754
22755Unicode 8-bit encoding
22756@end table
22757
22758This encoding is only supported on the Windows platform.
22759
22760@node Open Modes,Operations on C Streams,File content encoding,The Implementation of Standard I/O
22761@anchor{gnat_rm/the_implementation_of_standard_i_o id24}@anchor{2cf}@anchor{gnat_rm/the_implementation_of_standard_i_o open-modes}@anchor{2d0}
22762@section Open Modes
22763
22764
22765@code{Open} and @code{Create} calls result in a call to @code{fopen}
22766using the mode shown in the following table:
22767
22768
22769@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxx}
22770@headitem
22771
22772@code{Open} and @code{Create} Call Modes
22773
22774@tab
22775
22776@tab
22777
22778@item
22779
22780@tab
22781
22782@strong{OPEN}
22783
22784@tab
22785
22786@strong{CREATE}
22787
22788@item
22789
22790Append_File
22791
22792@tab
22793
22794“r+”
22795
22796@tab
22797
22798“w+”
22799
22800@item
22801
22802In_File
22803
22804@tab
22805
22806“r”
22807
22808@tab
22809
22810“w+”
22811
22812@item
22813
22814Out_File (Direct_IO)
22815
22816@tab
22817
22818“r+”
22819
22820@tab
22821
22822“w”
22823
22824@item
22825
22826Out_File (all other cases)
22827
22828@tab
22829
22830“w”
22831
22832@tab
22833
22834“w”
22835
22836@item
22837
22838Inout_File
22839
22840@tab
22841
22842“r+”
22843
22844@tab
22845
22846“w+”
22847
22848@end multitable
22849
22850
22851If text file translation is required, then either @code{b} or @code{t}
22852is added to the mode, depending on the setting of Text.  Text file
22853translation refers to the mapping of CR/LF sequences in an external file
22854to LF characters internally.  This mapping only occurs in DOS and
22855DOS-like systems, and is not relevant to other systems.
22856
22857A special case occurs with Stream_IO.  As shown in the above table, the
22858file is initially opened in @code{r} or @code{w} mode for the
22859@code{In_File} and @code{Out_File} cases.  If a @code{Set_Mode} operation
22860subsequently requires switching from reading to writing or vice-versa,
22861then the file is reopened in @code{r+} mode to permit the required operation.
22862
22863@node Operations on C Streams,Interfacing to C Streams,Open Modes,The Implementation of Standard I/O
22864@anchor{gnat_rm/the_implementation_of_standard_i_o id25}@anchor{2d1}@anchor{gnat_rm/the_implementation_of_standard_i_o operations-on-c-streams}@anchor{2d2}
22865@section Operations on C Streams
22866
22867
22868The package @code{Interfaces.C_Streams} provides an Ada program with direct
22869access to the C library functions for operations on C streams:
22870
22871@example
22872package Interfaces.C_Streams is
22873  -- Note: the reason we do not use the types that are in
22874  -- Interfaces.C is that we want to avoid dragging in the
22875  -- code in this unit if possible.
22876  subtype chars is System.Address;
22877  -- Pointer to null-terminated array of characters
22878  subtype FILEs is System.Address;
22879  -- Corresponds to the C type FILE*
22880  subtype voids is System.Address;
22881  -- Corresponds to the C type void*
22882  subtype int is Integer;
22883  subtype long is Long_Integer;
22884  -- Note: the above types are subtypes deliberately, and it
22885  -- is part of this spec that the above correspondences are
22886  -- guaranteed.  This means that it is legitimate to, for
22887  -- example, use Integer instead of int.  We provide these
22888  -- synonyms for clarity, but in some cases it may be
22889  -- convenient to use the underlying types (for example to
22890  -- avoid an unnecessary dependency of a spec on the spec
22891  -- of this unit).
22892  type size_t is mod 2 ** Standard'Address_Size;
22893  NULL_Stream : constant FILEs;
22894  -- Value returned (NULL in C) to indicate an
22895  -- fdopen/fopen/tmpfile error
22896  ----------------------------------
22897  -- Constants Defined in stdio.h --
22898  ----------------------------------
22899  EOF : constant int;
22900  -- Used by a number of routines to indicate error or
22901  -- end of file
22902  IOFBF : constant int;
22903  IOLBF : constant int;
22904  IONBF : constant int;
22905  -- Used to indicate buffering mode for setvbuf call
22906  SEEK_CUR : constant int;
22907  SEEK_END : constant int;
22908  SEEK_SET : constant int;
22909  -- Used to indicate origin for fseek call
22910  function stdin return FILEs;
22911  function stdout return FILEs;
22912  function stderr return FILEs;
22913  -- Streams associated with standard files
22914  --------------------------
22915  -- Standard C functions --
22916  --------------------------
22917  -- The functions selected below are ones that are
22918  -- available in UNIX (but not necessarily in ANSI C).
22919  -- These are very thin interfaces
22920  -- which copy exactly the C headers.  For more
22921  -- documentation on these functions, see the Microsoft C
22922  -- "Run-Time Library Reference" (Microsoft Press, 1990,
22923  -- ISBN 1-55615-225-6), which includes useful information
22924  -- on system compatibility.
22925  procedure clearerr (stream : FILEs);
22926  function fclose (stream : FILEs) return int;
22927  function fdopen (handle : int; mode : chars) return FILEs;
22928  function feof (stream : FILEs) return int;
22929  function ferror (stream : FILEs) return int;
22930  function fflush (stream : FILEs) return int;
22931  function fgetc (stream : FILEs) return int;
22932  function fgets (strng : chars; n : int; stream : FILEs)
22933      return chars;
22934  function fileno (stream : FILEs) return int;
22935  function fopen (filename : chars; Mode : chars)
22936      return FILEs;
22937  -- Note: to maintain target independence, use
22938  -- text_translation_required, a boolean variable defined in
22939  -- a-sysdep.c to deal with the target dependent text
22940  -- translation requirement.  If this variable is set,
22941  -- then  b/t should be appended to the standard mode
22942  -- argument to set the text translation mode off or on
22943  -- as required.
22944  function fputc (C : int; stream : FILEs) return int;
22945  function fputs (Strng : chars; Stream : FILEs) return int;
22946  function fread
22947     (buffer : voids;
22948      size : size_t;
22949      count : size_t;
22950      stream : FILEs)
22951      return size_t;
22952  function freopen
22953     (filename : chars;
22954      mode : chars;
22955      stream : FILEs)
22956      return FILEs;
22957  function fseek
22958     (stream : FILEs;
22959      offset : long;
22960      origin : int)
22961      return int;
22962  function ftell (stream : FILEs) return long;
22963  function fwrite
22964     (buffer : voids;
22965      size : size_t;
22966      count : size_t;
22967      stream : FILEs)
22968      return size_t;
22969  function isatty (handle : int) return int;
22970  procedure mktemp (template : chars);
22971  -- The return value (which is just a pointer to template)
22972  -- is discarded
22973  procedure rewind (stream : FILEs);
22974  function rmtmp return int;
22975  function setvbuf
22976     (stream : FILEs;
22977      buffer : chars;
22978      mode : int;
22979      size : size_t)
22980      return int;
22981
22982  function tmpfile return FILEs;
22983  function ungetc (c : int; stream : FILEs) return int;
22984  function unlink (filename : chars) return int;
22985  ---------------------
22986  -- Extra functions --
22987  ---------------------
22988  -- These functions supply slightly thicker bindings than
22989  -- those above.  They are derived from functions in the
22990  -- C Run-Time Library, but may do a bit more work than
22991  -- just directly calling one of the Library functions.
22992  function is_regular_file (handle : int) return int;
22993  -- Tests if given handle is for a regular file (result 1)
22994  -- or for a non-regular file (pipe or device, result 0).
22995  ---------------------------------
22996  -- Control of Text/Binary Mode --
22997  ---------------------------------
22998  -- If text_translation_required is true, then the following
22999  -- functions may be used to dynamically switch a file from
23000  -- binary to text mode or vice versa.  These functions have
23001  -- no effect if text_translation_required is false (i.e., in
23002  -- normal UNIX mode).  Use fileno to get a stream handle.
23003  procedure set_binary_mode (handle : int);
23004  procedure set_text_mode (handle : int);
23005  ----------------------------
23006  -- Full Path Name support --
23007  ----------------------------
23008  procedure full_name (nam : chars; buffer : chars);
23009  -- Given a NUL terminated string representing a file
23010  -- name, returns in buffer a NUL terminated string
23011  -- representing the full path name for the file name.
23012  -- On systems where it is relevant the   drive is also
23013  -- part of the full path name.  It is the responsibility
23014  -- of the caller to pass an actual parameter for buffer
23015  -- that is big enough for any full path name.  Use
23016  -- max_path_len given below as the size of buffer.
23017  max_path_len : integer;
23018  -- Maximum length of an allowable full path name on the
23019  -- system, including a terminating NUL character.
23020end Interfaces.C_Streams;
23021@end example
23022
23023@node Interfacing to C Streams,,Operations on C Streams,The Implementation of Standard I/O
23024@anchor{gnat_rm/the_implementation_of_standard_i_o id26}@anchor{2d3}@anchor{gnat_rm/the_implementation_of_standard_i_o interfacing-to-c-streams}@anchor{2d4}
23025@section Interfacing to C Streams
23026
23027
23028The packages in this section permit interfacing Ada files to C Stream
23029operations.
23030
23031@example
23032with Interfaces.C_Streams;
23033package Ada.Sequential_IO.C_Streams is
23034   function C_Stream (F : File_Type)
23035      return Interfaces.C_Streams.FILEs;
23036   procedure Open
23037     (File : in out File_Type;
23038      Mode : in File_Mode;
23039      C_Stream : in Interfaces.C_Streams.FILEs;
23040      Form : in String := "");
23041end Ada.Sequential_IO.C_Streams;
23042
23043 with Interfaces.C_Streams;
23044 package Ada.Direct_IO.C_Streams is
23045    function C_Stream (F : File_Type)
23046       return Interfaces.C_Streams.FILEs;
23047    procedure Open
23048      (File : in out File_Type;
23049       Mode : in File_Mode;
23050       C_Stream : in Interfaces.C_Streams.FILEs;
23051       Form : in String := "");
23052 end Ada.Direct_IO.C_Streams;
23053
23054 with Interfaces.C_Streams;
23055 package Ada.Text_IO.C_Streams is
23056    function C_Stream (F : File_Type)
23057       return Interfaces.C_Streams.FILEs;
23058    procedure Open
23059      (File : in out File_Type;
23060       Mode : in File_Mode;
23061       C_Stream : in Interfaces.C_Streams.FILEs;
23062       Form : in String := "");
23063 end Ada.Text_IO.C_Streams;
23064
23065 with Interfaces.C_Streams;
23066 package Ada.Wide_Text_IO.C_Streams is
23067    function C_Stream (F : File_Type)
23068       return Interfaces.C_Streams.FILEs;
23069    procedure Open
23070      (File : in out File_Type;
23071       Mode : in File_Mode;
23072       C_Stream : in Interfaces.C_Streams.FILEs;
23073       Form : in String := "");
23074end Ada.Wide_Text_IO.C_Streams;
23075
23076 with Interfaces.C_Streams;
23077 package Ada.Wide_Wide_Text_IO.C_Streams is
23078    function C_Stream (F : File_Type)
23079       return Interfaces.C_Streams.FILEs;
23080    procedure Open
23081      (File : in out File_Type;
23082       Mode : in File_Mode;
23083       C_Stream : in Interfaces.C_Streams.FILEs;
23084       Form : in String := "");
23085end Ada.Wide_Wide_Text_IO.C_Streams;
23086
23087with Interfaces.C_Streams;
23088package Ada.Stream_IO.C_Streams is
23089   function C_Stream (F : File_Type)
23090      return Interfaces.C_Streams.FILEs;
23091   procedure Open
23092     (File : in out File_Type;
23093      Mode : in File_Mode;
23094      C_Stream : in Interfaces.C_Streams.FILEs;
23095      Form : in String := "");
23096end Ada.Stream_IO.C_Streams;
23097@end example
23098
23099In each of these six packages, the @code{C_Stream} function obtains the
23100@code{FILE} pointer from a currently opened Ada file.  It is then
23101possible to use the @code{Interfaces.C_Streams} package to operate on
23102this stream, or the stream can be passed to a C program which can
23103operate on it directly.  Of course the program is responsible for
23104ensuring that only appropriate sequences of operations are executed.
23105
23106One particular use of relevance to an Ada program is that the
23107@code{setvbuf} function can be used to control the buffering of the
23108stream used by an Ada file.  In the absence of such a call the standard
23109default buffering is used.
23110
23111The @code{Open} procedures in these packages open a file giving an
23112existing C Stream instead of a file name.  Typically this stream is
23113imported from a C program, allowing an Ada file to operate on an
23114existing C file.
23115
23116@node The GNAT Library,Interfacing to Other Languages,The Implementation of Standard I/O,Top
23117@anchor{gnat_rm/the_gnat_library doc}@anchor{2d5}@anchor{gnat_rm/the_gnat_library id1}@anchor{2d6}@anchor{gnat_rm/the_gnat_library the-gnat-library}@anchor{10}
23118@chapter The GNAT Library
23119
23120
23121The GNAT library contains a number of general and special purpose packages.
23122It represents functionality that the GNAT developers have found useful, and
23123which is made available to GNAT users.  The packages described here are fully
23124supported, and upwards compatibility will be maintained in future releases,
23125so you can use these facilities with the confidence that the same functionality
23126will be available in future releases.
23127
23128The chapter here simply gives a brief summary of the facilities available.
23129The full documentation is found in the spec file for the package.  The full
23130sources of these library packages, including both spec and body, are provided
23131with all GNAT releases.  For example, to find out the full specifications of
23132the SPITBOL pattern matching capability, including a full tutorial and
23133extensive examples, look in the @code{g-spipat.ads} file in the library.
23134
23135For each entry here, the package name (as it would appear in a @code{with}
23136clause) is given, followed by the name of the corresponding spec file in
23137parentheses.  The packages are children in four hierarchies, @code{Ada},
23138@code{Interfaces}, @code{System}, and @code{GNAT}, the latter being a
23139GNAT-specific hierarchy.
23140
23141Note that an application program should only use packages in one of these
23142four hierarchies if the package is defined in the Ada Reference Manual,
23143or is listed in this section of the GNAT Programmers Reference Manual.
23144All other units should be considered internal implementation units and
23145should not be directly @code{with}ed by application code.  The use of
23146a @code{with} clause that references one of these internal implementation
23147units makes an application potentially dependent on changes in versions
23148of GNAT, and will generate a warning message.
23149
23150@menu
23151* Ada.Characters.Latin_9 (a-chlat9.ads): Ada Characters Latin_9 a-chlat9 ads.
23152* Ada.Characters.Wide_Latin_1 (a-cwila1.ads): Ada Characters Wide_Latin_1 a-cwila1 ads.
23153* Ada.Characters.Wide_Latin_9 (a-cwila1.ads): Ada Characters Wide_Latin_9 a-cwila1 ads.
23154* Ada.Characters.Wide_Wide_Latin_1 (a-chzla1.ads): Ada Characters Wide_Wide_Latin_1 a-chzla1 ads.
23155* Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads): Ada Characters Wide_Wide_Latin_9 a-chzla9 ads.
23156* Ada.Containers.Formal_Doubly_Linked_Lists (a-cfdlli.ads): Ada Containers Formal_Doubly_Linked_Lists a-cfdlli ads.
23157* Ada.Containers.Formal_Hashed_Maps (a-cfhama.ads): Ada Containers Formal_Hashed_Maps a-cfhama ads.
23158* Ada.Containers.Formal_Hashed_Sets (a-cfhase.ads): Ada Containers Formal_Hashed_Sets a-cfhase ads.
23159* Ada.Containers.Formal_Ordered_Maps (a-cforma.ads): Ada Containers Formal_Ordered_Maps a-cforma ads.
23160* Ada.Containers.Formal_Ordered_Sets (a-cforse.ads): Ada Containers Formal_Ordered_Sets a-cforse ads.
23161* Ada.Containers.Formal_Vectors (a-cofove.ads): Ada Containers Formal_Vectors a-cofove ads.
23162* Ada.Containers.Formal_Indefinite_Vectors (a-cfinve.ads): Ada Containers Formal_Indefinite_Vectors a-cfinve ads.
23163* Ada.Containers.Functional_Vectors (a-cofuve.ads): Ada Containers Functional_Vectors a-cofuve ads.
23164* Ada.Containers.Functional_Sets (a-cofuse.ads): Ada Containers Functional_Sets a-cofuse ads.
23165* Ada.Containers.Functional_Maps (a-cofuma.ads): Ada Containers Functional_Maps a-cofuma ads.
23166* Ada.Containers.Bounded_Holders (a-coboho.ads): Ada Containers Bounded_Holders a-coboho ads.
23167* Ada.Command_Line.Environment (a-colien.ads): Ada Command_Line Environment a-colien ads.
23168* Ada.Command_Line.Remove (a-colire.ads): Ada Command_Line Remove a-colire ads.
23169* Ada.Command_Line.Response_File (a-clrefi.ads): Ada Command_Line Response_File a-clrefi ads.
23170* Ada.Direct_IO.C_Streams (a-diocst.ads): Ada Direct_IO C_Streams a-diocst ads.
23171* Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads): Ada Exceptions Is_Null_Occurrence a-einuoc ads.
23172* Ada.Exceptions.Last_Chance_Handler (a-elchha.ads): Ada Exceptions Last_Chance_Handler a-elchha ads.
23173* Ada.Exceptions.Traceback (a-exctra.ads): Ada Exceptions Traceback a-exctra ads.
23174* Ada.Sequential_IO.C_Streams (a-siocst.ads): Ada Sequential_IO C_Streams a-siocst ads.
23175* Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads): Ada Streams Stream_IO C_Streams a-ssicst ads.
23176* Ada.Strings.Unbounded.Text_IO (a-suteio.ads): Ada Strings Unbounded Text_IO a-suteio ads.
23177* Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads): Ada Strings Wide_Unbounded Wide_Text_IO a-swuwti ads.
23178* Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads): Ada Strings Wide_Wide_Unbounded Wide_Wide_Text_IO a-szuzti ads.
23179* Ada.Task_Initialization (a-tasini.ads): Ada Task_Initialization a-tasini ads.
23180* Ada.Text_IO.C_Streams (a-tiocst.ads): Ada Text_IO C_Streams a-tiocst ads.
23181* Ada.Text_IO.Reset_Standard_Files (a-tirsfi.ads): Ada Text_IO Reset_Standard_Files a-tirsfi ads.
23182* Ada.Wide_Characters.Unicode (a-wichun.ads): Ada Wide_Characters Unicode a-wichun ads.
23183* Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads): Ada Wide_Text_IO C_Streams a-wtcstr ads.
23184* Ada.Wide_Text_IO.Reset_Standard_Files (a-wrstfi.ads): Ada Wide_Text_IO Reset_Standard_Files a-wrstfi ads.
23185* Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads): Ada Wide_Wide_Characters Unicode a-zchuni ads.
23186* Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads): Ada Wide_Wide_Text_IO C_Streams a-ztcstr ads.
23187* Ada.Wide_Wide_Text_IO.Reset_Standard_Files (a-zrstfi.ads): Ada Wide_Wide_Text_IO Reset_Standard_Files a-zrstfi ads.
23188* GNAT.Altivec (g-altive.ads): GNAT Altivec g-altive ads.
23189* GNAT.Altivec.Conversions (g-altcon.ads): GNAT Altivec Conversions g-altcon ads.
23190* GNAT.Altivec.Vector_Operations (g-alveop.ads): GNAT Altivec Vector_Operations g-alveop ads.
23191* GNAT.Altivec.Vector_Types (g-alvety.ads): GNAT Altivec Vector_Types g-alvety ads.
23192* GNAT.Altivec.Vector_Views (g-alvevi.ads): GNAT Altivec Vector_Views g-alvevi ads.
23193* GNAT.Array_Split (g-arrspl.ads): GNAT Array_Split g-arrspl ads.
23194* GNAT.AWK (g-awk.ads): GNAT AWK g-awk ads.
23195* GNAT.Bind_Environment (g-binenv.ads): GNAT Bind_Environment g-binenv ads.
23196* GNAT.Branch_Prediction (g-brapre.ads): GNAT Branch_Prediction g-brapre ads.
23197* GNAT.Bounded_Buffers (g-boubuf.ads): GNAT Bounded_Buffers g-boubuf ads.
23198* GNAT.Bounded_Mailboxes (g-boumai.ads): GNAT Bounded_Mailboxes g-boumai ads.
23199* GNAT.Bubble_Sort (g-bubsor.ads): GNAT Bubble_Sort g-bubsor ads.
23200* GNAT.Bubble_Sort_A (g-busora.ads): GNAT Bubble_Sort_A g-busora ads.
23201* GNAT.Bubble_Sort_G (g-busorg.ads): GNAT Bubble_Sort_G g-busorg ads.
23202* GNAT.Byte_Order_Mark (g-byorma.ads): GNAT Byte_Order_Mark g-byorma ads.
23203* GNAT.Byte_Swapping (g-bytswa.ads): GNAT Byte_Swapping g-bytswa ads.
23204* GNAT.Calendar (g-calend.ads): GNAT Calendar g-calend ads.
23205* GNAT.Calendar.Time_IO (g-catiio.ads): GNAT Calendar Time_IO g-catiio ads.
23206* GNAT.CRC32 (g-crc32.ads): GNAT CRC32 g-crc32 ads.
23207* GNAT.Case_Util (g-casuti.ads): GNAT Case_Util g-casuti ads.
23208* GNAT.CGI (g-cgi.ads): GNAT CGI g-cgi ads.
23209* GNAT.CGI.Cookie (g-cgicoo.ads): GNAT CGI Cookie g-cgicoo ads.
23210* GNAT.CGI.Debug (g-cgideb.ads): GNAT CGI Debug g-cgideb ads.
23211* GNAT.Command_Line (g-comlin.ads): GNAT Command_Line g-comlin ads.
23212* GNAT.Compiler_Version (g-comver.ads): GNAT Compiler_Version g-comver ads.
23213* GNAT.Ctrl_C (g-ctrl_c.ads): GNAT Ctrl_C g-ctrl_c ads.
23214* GNAT.Current_Exception (g-curexc.ads): GNAT Current_Exception g-curexc ads.
23215* GNAT.Debug_Pools (g-debpoo.ads): GNAT Debug_Pools g-debpoo ads.
23216* GNAT.Debug_Utilities (g-debuti.ads): GNAT Debug_Utilities g-debuti ads.
23217* GNAT.Decode_String (g-decstr.ads): GNAT Decode_String g-decstr ads.
23218* GNAT.Decode_UTF8_String (g-deutst.ads): GNAT Decode_UTF8_String g-deutst ads.
23219* GNAT.Directory_Operations (g-dirope.ads): GNAT Directory_Operations g-dirope ads.
23220* GNAT.Directory_Operations.Iteration (g-diopit.ads): GNAT Directory_Operations Iteration g-diopit ads.
23221* GNAT.Dynamic_HTables (g-dynhta.ads): GNAT Dynamic_HTables g-dynhta ads.
23222* GNAT.Dynamic_Tables (g-dyntab.ads): GNAT Dynamic_Tables g-dyntab ads.
23223* GNAT.Encode_String (g-encstr.ads): GNAT Encode_String g-encstr ads.
23224* GNAT.Encode_UTF8_String (g-enutst.ads): GNAT Encode_UTF8_String g-enutst ads.
23225* GNAT.Exception_Actions (g-excact.ads): GNAT Exception_Actions g-excact ads.
23226* GNAT.Exception_Traces (g-exctra.ads): GNAT Exception_Traces g-exctra ads.
23227* GNAT.Exceptions (g-except.ads): GNAT Exceptions g-except ads.
23228* GNAT.Expect (g-expect.ads): GNAT Expect g-expect ads.
23229* GNAT.Expect.TTY (g-exptty.ads): GNAT Expect TTY g-exptty ads.
23230* GNAT.Float_Control (g-flocon.ads): GNAT Float_Control g-flocon ads.
23231* GNAT.Formatted_String (g-forstr.ads): GNAT Formatted_String g-forstr ads.
23232* GNAT.Heap_Sort (g-heasor.ads): GNAT Heap_Sort g-heasor ads.
23233* GNAT.Heap_Sort_A (g-hesora.ads): GNAT Heap_Sort_A g-hesora ads.
23234* GNAT.Heap_Sort_G (g-hesorg.ads): GNAT Heap_Sort_G g-hesorg ads.
23235* GNAT.HTable (g-htable.ads): GNAT HTable g-htable ads.
23236* GNAT.IO (g-io.ads): GNAT IO g-io ads.
23237* GNAT.IO_Aux (g-io_aux.ads): GNAT IO_Aux g-io_aux ads.
23238* GNAT.Lock_Files (g-locfil.ads): GNAT Lock_Files g-locfil ads.
23239* GNAT.MBBS_Discrete_Random (g-mbdira.ads): GNAT MBBS_Discrete_Random g-mbdira ads.
23240* GNAT.MBBS_Float_Random (g-mbflra.ads): GNAT MBBS_Float_Random g-mbflra ads.
23241* GNAT.MD5 (g-md5.ads): GNAT MD5 g-md5 ads.
23242* GNAT.Memory_Dump (g-memdum.ads): GNAT Memory_Dump g-memdum ads.
23243* GNAT.Most_Recent_Exception (g-moreex.ads): GNAT Most_Recent_Exception g-moreex ads.
23244* GNAT.OS_Lib (g-os_lib.ads): GNAT OS_Lib g-os_lib ads.
23245* GNAT.Perfect_Hash_Generators (g-pehage.ads): GNAT Perfect_Hash_Generators g-pehage ads.
23246* GNAT.Random_Numbers (g-rannum.ads): GNAT Random_Numbers g-rannum ads.
23247* GNAT.Regexp (g-regexp.ads): GNAT Regexp g-regexp ads.
23248* GNAT.Registry (g-regist.ads): GNAT Registry g-regist ads.
23249* GNAT.Regpat (g-regpat.ads): GNAT Regpat g-regpat ads.
23250* GNAT.Rewrite_Data (g-rewdat.ads): GNAT Rewrite_Data g-rewdat ads.
23251* GNAT.Secondary_Stack_Info (g-sestin.ads): GNAT Secondary_Stack_Info g-sestin ads.
23252* GNAT.Semaphores (g-semaph.ads): GNAT Semaphores g-semaph ads.
23253* GNAT.Serial_Communications (g-sercom.ads): GNAT Serial_Communications g-sercom ads.
23254* GNAT.SHA1 (g-sha1.ads): GNAT SHA1 g-sha1 ads.
23255* GNAT.SHA224 (g-sha224.ads): GNAT SHA224 g-sha224 ads.
23256* GNAT.SHA256 (g-sha256.ads): GNAT SHA256 g-sha256 ads.
23257* GNAT.SHA384 (g-sha384.ads): GNAT SHA384 g-sha384 ads.
23258* GNAT.SHA512 (g-sha512.ads): GNAT SHA512 g-sha512 ads.
23259* GNAT.Signals (g-signal.ads): GNAT Signals g-signal ads.
23260* GNAT.Sockets (g-socket.ads): GNAT Sockets g-socket ads.
23261* GNAT.Source_Info (g-souinf.ads): GNAT Source_Info g-souinf ads.
23262* GNAT.Spelling_Checker (g-speche.ads): GNAT Spelling_Checker g-speche ads.
23263* GNAT.Spelling_Checker_Generic (g-spchge.ads): GNAT Spelling_Checker_Generic g-spchge ads.
23264* GNAT.Spitbol.Patterns (g-spipat.ads): GNAT Spitbol Patterns g-spipat ads.
23265* GNAT.Spitbol (g-spitbo.ads): GNAT Spitbol g-spitbo ads.
23266* GNAT.Spitbol.Table_Boolean (g-sptabo.ads): GNAT Spitbol Table_Boolean g-sptabo ads.
23267* GNAT.Spitbol.Table_Integer (g-sptain.ads): GNAT Spitbol Table_Integer g-sptain ads.
23268* GNAT.Spitbol.Table_VString (g-sptavs.ads): GNAT Spitbol Table_VString g-sptavs ads.
23269* GNAT.SSE (g-sse.ads): GNAT SSE g-sse ads.
23270* GNAT.SSE.Vector_Types (g-ssvety.ads): GNAT SSE Vector_Types g-ssvety ads.
23271* GNAT.String_Hash (g-strhas.ads): GNAT String_Hash g-strhas ads.
23272* GNAT.Strings (g-string.ads): GNAT Strings g-string ads.
23273* GNAT.String_Split (g-strspl.ads): GNAT String_Split g-strspl ads.
23274* GNAT.Table (g-table.ads): GNAT Table g-table ads.
23275* GNAT.Task_Lock (g-tasloc.ads): GNAT Task_Lock g-tasloc ads.
23276* GNAT.Time_Stamp (g-timsta.ads): GNAT Time_Stamp g-timsta ads.
23277* GNAT.Threads (g-thread.ads): GNAT Threads g-thread ads.
23278* GNAT.Traceback (g-traceb.ads): GNAT Traceback g-traceb ads.
23279* GNAT.Traceback.Symbolic (g-trasym.ads): GNAT Traceback Symbolic g-trasym ads.
23280* GNAT.UTF_32 (g-table.ads): GNAT UTF_32 g-table ads.
23281* GNAT.Wide_Spelling_Checker (g-u3spch.ads): GNAT Wide_Spelling_Checker g-u3spch ads.
23282* GNAT.Wide_Spelling_Checker (g-wispch.ads): GNAT Wide_Spelling_Checker g-wispch ads.
23283* GNAT.Wide_String_Split (g-wistsp.ads): GNAT Wide_String_Split g-wistsp ads.
23284* GNAT.Wide_Wide_Spelling_Checker (g-zspche.ads): GNAT Wide_Wide_Spelling_Checker g-zspche ads.
23285* GNAT.Wide_Wide_String_Split (g-zistsp.ads): GNAT Wide_Wide_String_Split g-zistsp ads.
23286* Interfaces.C.Extensions (i-cexten.ads): Interfaces C Extensions i-cexten ads.
23287* Interfaces.C.Streams (i-cstrea.ads): Interfaces C Streams i-cstrea ads.
23288* Interfaces.Packed_Decimal (i-pacdec.ads): Interfaces Packed_Decimal i-pacdec ads.
23289* Interfaces.VxWorks (i-vxwork.ads): Interfaces VxWorks i-vxwork ads.
23290* Interfaces.VxWorks.Int_Connection (i-vxinco.ads): Interfaces VxWorks Int_Connection i-vxinco ads.
23291* Interfaces.VxWorks.IO (i-vxwoio.ads): Interfaces VxWorks IO i-vxwoio ads.
23292* System.Address_Image (s-addima.ads): System Address_Image s-addima ads.
23293* System.Assertions (s-assert.ads): System Assertions s-assert ads.
23294* System.Atomic_Counters (s-atocou.ads): System Atomic_Counters s-atocou ads.
23295* System.Memory (s-memory.ads): System Memory s-memory ads.
23296* System.Multiprocessors (s-multip.ads): System Multiprocessors s-multip ads.
23297* System.Multiprocessors.Dispatching_Domains (s-mudido.ads): System Multiprocessors Dispatching_Domains s-mudido ads.
23298* System.Partition_Interface (s-parint.ads): System Partition_Interface s-parint ads.
23299* System.Pool_Global (s-pooglo.ads): System Pool_Global s-pooglo ads.
23300* System.Pool_Local (s-pooloc.ads): System Pool_Local s-pooloc ads.
23301* System.Restrictions (s-restri.ads): System Restrictions s-restri ads.
23302* System.Rident (s-rident.ads): System Rident s-rident ads.
23303* System.Strings.Stream_Ops (s-ststop.ads): System Strings Stream_Ops s-ststop ads.
23304* System.Unsigned_Types (s-unstyp.ads): System Unsigned_Types s-unstyp ads.
23305* System.Wch_Cnv (s-wchcnv.ads): System Wch_Cnv s-wchcnv ads.
23306* System.Wch_Con (s-wchcon.ads): System Wch_Con s-wchcon ads.
23307
23308@end menu
23309
23310@node Ada Characters Latin_9 a-chlat9 ads,Ada Characters Wide_Latin_1 a-cwila1 ads,,The GNAT Library
23311@anchor{gnat_rm/the_gnat_library ada-characters-latin-9-a-chlat9-ads}@anchor{2d7}@anchor{gnat_rm/the_gnat_library id2}@anchor{2d8}
23312@section @code{Ada.Characters.Latin_9} (@code{a-chlat9.ads})
23313
23314
23315@geindex Ada.Characters.Latin_9 (a-chlat9.ads)
23316
23317@geindex Latin_9 constants for Character
23318
23319This child of @code{Ada.Characters}
23320provides a set of definitions corresponding to those in the
23321RM-defined package @code{Ada.Characters.Latin_1} but with the
23322few modifications required for @code{Latin-9}
23323The provision of such a package
23324is specifically authorized by the Ada Reference Manual
23325(RM A.3.3(27)).
23326
23327@node Ada Characters Wide_Latin_1 a-cwila1 ads,Ada Characters Wide_Latin_9 a-cwila1 ads,Ada Characters Latin_9 a-chlat9 ads,The GNAT Library
23328@anchor{gnat_rm/the_gnat_library ada-characters-wide-latin-1-a-cwila1-ads}@anchor{2d9}@anchor{gnat_rm/the_gnat_library id3}@anchor{2da}
23329@section @code{Ada.Characters.Wide_Latin_1} (@code{a-cwila1.ads})
23330
23331
23332@geindex Ada.Characters.Wide_Latin_1 (a-cwila1.ads)
23333
23334@geindex Latin_1 constants for Wide_Character
23335
23336This child of @code{Ada.Characters}
23337provides a set of definitions corresponding to those in the
23338RM-defined package @code{Ada.Characters.Latin_1} but with the
23339types of the constants being @code{Wide_Character}
23340instead of @code{Character}.  The provision of such a package
23341is specifically authorized by the Ada Reference Manual
23342(RM A.3.3(27)).
23343
23344@node Ada Characters Wide_Latin_9 a-cwila1 ads,Ada Characters Wide_Wide_Latin_1 a-chzla1 ads,Ada Characters Wide_Latin_1 a-cwila1 ads,The GNAT Library
23345@anchor{gnat_rm/the_gnat_library ada-characters-wide-latin-9-a-cwila1-ads}@anchor{2db}@anchor{gnat_rm/the_gnat_library id4}@anchor{2dc}
23346@section @code{Ada.Characters.Wide_Latin_9} (@code{a-cwila1.ads})
23347
23348
23349@geindex Ada.Characters.Wide_Latin_9 (a-cwila1.ads)
23350
23351@geindex Latin_9 constants for Wide_Character
23352
23353This child of @code{Ada.Characters}
23354provides a set of definitions corresponding to those in the
23355GNAT defined package @code{Ada.Characters.Latin_9} but with the
23356types of the constants being @code{Wide_Character}
23357instead of @code{Character}.  The provision of such a package
23358is specifically authorized by the Ada Reference Manual
23359(RM A.3.3(27)).
23360
23361@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-cwila1 ads,The GNAT Library
23362@anchor{gnat_rm/the_gnat_library ada-characters-wide-wide-latin-1-a-chzla1-ads}@anchor{2dd}@anchor{gnat_rm/the_gnat_library id5}@anchor{2de}
23363@section @code{Ada.Characters.Wide_Wide_Latin_1} (@code{a-chzla1.ads})
23364
23365
23366@geindex Ada.Characters.Wide_Wide_Latin_1 (a-chzla1.ads)
23367
23368@geindex Latin_1 constants for Wide_Wide_Character
23369
23370This child of @code{Ada.Characters}
23371provides a set of definitions corresponding to those in the
23372RM-defined package @code{Ada.Characters.Latin_1} but with the
23373types of the constants being @code{Wide_Wide_Character}
23374instead of @code{Character}.  The provision of such a package
23375is specifically authorized by the Ada Reference Manual
23376(RM A.3.3(27)).
23377
23378@node Ada Characters Wide_Wide_Latin_9 a-chzla9 ads,Ada Containers Formal_Doubly_Linked_Lists a-cfdlli ads,Ada Characters Wide_Wide_Latin_1 a-chzla1 ads,The GNAT Library
23379@anchor{gnat_rm/the_gnat_library ada-characters-wide-wide-latin-9-a-chzla9-ads}@anchor{2df}@anchor{gnat_rm/the_gnat_library id6}@anchor{2e0}
23380@section @code{Ada.Characters.Wide_Wide_Latin_9} (@code{a-chzla9.ads})
23381
23382
23383@geindex Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads)
23384
23385@geindex Latin_9 constants for Wide_Wide_Character
23386
23387This child of @code{Ada.Characters}
23388provides a set of definitions corresponding to those in the
23389GNAT defined package @code{Ada.Characters.Latin_9} but with the
23390types of the constants being @code{Wide_Wide_Character}
23391instead of @code{Character}.  The provision of such a package
23392is specifically authorized by the Ada Reference Manual
23393(RM A.3.3(27)).
23394
23395@node Ada Containers Formal_Doubly_Linked_Lists a-cfdlli ads,Ada Containers Formal_Hashed_Maps a-cfhama ads,Ada Characters Wide_Wide_Latin_9 a-chzla9 ads,The GNAT Library
23396@anchor{gnat_rm/the_gnat_library ada-containers-formal-doubly-linked-lists-a-cfdlli-ads}@anchor{2e1}@anchor{gnat_rm/the_gnat_library id7}@anchor{2e2}
23397@section @code{Ada.Containers.Formal_Doubly_Linked_Lists} (@code{a-cfdlli.ads})
23398
23399
23400@geindex Ada.Containers.Formal_Doubly_Linked_Lists (a-cfdlli.ads)
23401
23402@geindex Formal container for doubly linked lists
23403
23404This child of @code{Ada.Containers} defines a modified version of the
23405Ada 2005 container for doubly linked lists, meant to facilitate formal
23406verification of code using such containers. The specification of this
23407unit is compatible with SPARK 2014.
23408
23409Note that although this container was designed with formal verification
23410in mind, it may well be generally useful in that it is a simplified more
23411efficient version than the one defined in the standard. In particular it
23412does not have the complex overhead required to detect cursor tampering.
23413
23414@node Ada Containers Formal_Hashed_Maps a-cfhama ads,Ada Containers Formal_Hashed_Sets a-cfhase ads,Ada Containers Formal_Doubly_Linked_Lists a-cfdlli ads,The GNAT Library
23415@anchor{gnat_rm/the_gnat_library ada-containers-formal-hashed-maps-a-cfhama-ads}@anchor{2e3}@anchor{gnat_rm/the_gnat_library id8}@anchor{2e4}
23416@section @code{Ada.Containers.Formal_Hashed_Maps} (@code{a-cfhama.ads})
23417
23418
23419@geindex Ada.Containers.Formal_Hashed_Maps (a-cfhama.ads)
23420
23421@geindex Formal container for hashed maps
23422
23423This child of @code{Ada.Containers} defines a modified version of the
23424Ada 2005 container for hashed maps, meant to facilitate formal
23425verification of code using such containers. The specification of this
23426unit is compatible with SPARK 2014.
23427
23428Note that although this container was designed with formal verification
23429in mind, it may well be generally useful in that it is a simplified more
23430efficient version than the one defined in the standard. In particular it
23431does not have the complex overhead required to detect cursor tampering.
23432
23433@node Ada Containers Formal_Hashed_Sets a-cfhase ads,Ada Containers Formal_Ordered_Maps a-cforma ads,Ada Containers Formal_Hashed_Maps a-cfhama ads,The GNAT Library
23434@anchor{gnat_rm/the_gnat_library ada-containers-formal-hashed-sets-a-cfhase-ads}@anchor{2e5}@anchor{gnat_rm/the_gnat_library id9}@anchor{2e6}
23435@section @code{Ada.Containers.Formal_Hashed_Sets} (@code{a-cfhase.ads})
23436
23437
23438@geindex Ada.Containers.Formal_Hashed_Sets (a-cfhase.ads)
23439
23440@geindex Formal container for hashed sets
23441
23442This child of @code{Ada.Containers} defines a modified version of the
23443Ada 2005 container for hashed sets, meant to facilitate formal
23444verification of code using such containers. The specification of this
23445unit is compatible with SPARK 2014.
23446
23447Note that although this container was designed with formal verification
23448in mind, it may well be generally useful in that it is a simplified more
23449efficient version than the one defined in the standard. In particular it
23450does not have the complex overhead required to detect cursor tampering.
23451
23452@node Ada Containers Formal_Ordered_Maps a-cforma ads,Ada Containers Formal_Ordered_Sets a-cforse ads,Ada Containers Formal_Hashed_Sets a-cfhase ads,The GNAT Library
23453@anchor{gnat_rm/the_gnat_library ada-containers-formal-ordered-maps-a-cforma-ads}@anchor{2e7}@anchor{gnat_rm/the_gnat_library id10}@anchor{2e8}
23454@section @code{Ada.Containers.Formal_Ordered_Maps} (@code{a-cforma.ads})
23455
23456
23457@geindex Ada.Containers.Formal_Ordered_Maps (a-cforma.ads)
23458
23459@geindex Formal container for ordered maps
23460
23461This child of @code{Ada.Containers} defines a modified version of the
23462Ada 2005 container for ordered maps, meant to facilitate formal
23463verification of code using such containers. The specification of this
23464unit is compatible with SPARK 2014.
23465
23466Note that although this container was designed with formal verification
23467in mind, it may well be generally useful in that it is a simplified more
23468efficient version than the one defined in the standard. In particular it
23469does not have the complex overhead required to detect cursor tampering.
23470
23471@node Ada Containers Formal_Ordered_Sets a-cforse ads,Ada Containers Formal_Vectors a-cofove ads,Ada Containers Formal_Ordered_Maps a-cforma ads,The GNAT Library
23472@anchor{gnat_rm/the_gnat_library ada-containers-formal-ordered-sets-a-cforse-ads}@anchor{2e9}@anchor{gnat_rm/the_gnat_library id11}@anchor{2ea}
23473@section @code{Ada.Containers.Formal_Ordered_Sets} (@code{a-cforse.ads})
23474
23475
23476@geindex Ada.Containers.Formal_Ordered_Sets (a-cforse.ads)
23477
23478@geindex Formal container for ordered sets
23479
23480This child of @code{Ada.Containers} defines a modified version of the
23481Ada 2005 container for ordered sets, meant to facilitate formal
23482verification of code using such containers. The specification of this
23483unit is compatible with SPARK 2014.
23484
23485Note that although this container was designed with formal verification
23486in mind, it may well be generally useful in that it is a simplified more
23487efficient version than the one defined in the standard. In particular it
23488does not have the complex overhead required to detect cursor tampering.
23489
23490@node Ada Containers Formal_Vectors a-cofove ads,Ada Containers Formal_Indefinite_Vectors a-cfinve ads,Ada Containers Formal_Ordered_Sets a-cforse ads,The GNAT Library
23491@anchor{gnat_rm/the_gnat_library ada-containers-formal-vectors-a-cofove-ads}@anchor{2eb}@anchor{gnat_rm/the_gnat_library id12}@anchor{2ec}
23492@section @code{Ada.Containers.Formal_Vectors} (@code{a-cofove.ads})
23493
23494
23495@geindex Ada.Containers.Formal_Vectors (a-cofove.ads)
23496
23497@geindex Formal container for vectors
23498
23499This child of @code{Ada.Containers} defines a modified version of the
23500Ada 2005 container for vectors, meant to facilitate formal
23501verification of code using such containers. The specification of this
23502unit is compatible with SPARK 2014.
23503
23504Note that although this container was designed with formal verification
23505in mind, it may well be generally useful in that it is a simplified more
23506efficient version than the one defined in the standard. In particular it
23507does not have the complex overhead required to detect cursor tampering.
23508
23509@node Ada Containers Formal_Indefinite_Vectors a-cfinve ads,Ada Containers Functional_Vectors a-cofuve ads,Ada Containers Formal_Vectors a-cofove ads,The GNAT Library
23510@anchor{gnat_rm/the_gnat_library ada-containers-formal-indefinite-vectors-a-cfinve-ads}@anchor{2ed}@anchor{gnat_rm/the_gnat_library id13}@anchor{2ee}
23511@section @code{Ada.Containers.Formal_Indefinite_Vectors} (@code{a-cfinve.ads})
23512
23513
23514@geindex Ada.Containers.Formal_Indefinite_Vectors (a-cfinve.ads)
23515
23516@geindex Formal container for vectors
23517
23518This child of @code{Ada.Containers} defines a modified version of the
23519Ada 2005 container for vectors of indefinite elements, meant to
23520facilitate formal verification of code using such containers. The
23521specification of this unit is compatible with SPARK 2014.
23522
23523Note that although this container was designed with formal verification
23524in mind, it may well be generally useful in that it is a simplified more
23525efficient version than the one defined in the standard. In particular it
23526does not have the complex overhead required to detect cursor tampering.
23527
23528@node Ada Containers Functional_Vectors a-cofuve ads,Ada Containers Functional_Sets a-cofuse ads,Ada Containers Formal_Indefinite_Vectors a-cfinve ads,The GNAT Library
23529@anchor{gnat_rm/the_gnat_library ada-containers-functional-vectors-a-cofuve-ads}@anchor{2ef}@anchor{gnat_rm/the_gnat_library id14}@anchor{2f0}
23530@section @code{Ada.Containers.Functional_Vectors} (@code{a-cofuve.ads})
23531
23532
23533@geindex Ada.Containers.Functional_Vectors (a-cofuve.ads)
23534
23535@geindex Functional vectors
23536
23537This child of @code{Ada.Containers} defines immutable vectors. These
23538containers are unbounded and may contain indefinite elements. Furthermore, to
23539be usable in every context, they are neither controlled nor limited. As they
23540are functional, that is, no primitives are provided which would allow modifying
23541an existing container, these containers can still be used safely.
23542
23543Their API features functions creating new containers from existing ones.
23544As a consequence, these containers are highly inefficient. They are also
23545memory consuming, as the allocated memory is not reclaimed when the container
23546is no longer referenced. Thus, they should in general be used in ghost code
23547and annotations, so that they can be removed from the final executable. The
23548specification of this unit is compatible with SPARK 2014.
23549
23550@node Ada Containers Functional_Sets a-cofuse ads,Ada Containers Functional_Maps a-cofuma ads,Ada Containers Functional_Vectors a-cofuve ads,The GNAT Library
23551@anchor{gnat_rm/the_gnat_library ada-containers-functional-sets-a-cofuse-ads}@anchor{2f1}@anchor{gnat_rm/the_gnat_library id15}@anchor{2f2}
23552@section @code{Ada.Containers.Functional_Sets} (@code{a-cofuse.ads})
23553
23554
23555@geindex Ada.Containers.Functional_Sets (a-cofuse.ads)
23556
23557@geindex Functional sets
23558
23559This child of @code{Ada.Containers} defines immutable sets. These containers are
23560unbounded and may contain indefinite elements. Furthermore, to be usable in
23561every context, they are neither controlled nor limited. As they are functional,
23562that is, no primitives are provided which would allow modifying an existing
23563container, these containers can still be used safely.
23564
23565Their API features functions creating new containers from existing ones.
23566As a consequence, these containers are highly inefficient. They are also
23567memory consuming, as the allocated memory is not reclaimed when the container
23568is no longer referenced. Thus, they should in general be used in ghost code
23569and annotations, so that they can be removed from the final executable. The
23570specification of this unit is compatible with SPARK 2014.
23571
23572@node Ada Containers Functional_Maps a-cofuma ads,Ada Containers Bounded_Holders a-coboho ads,Ada Containers Functional_Sets a-cofuse ads,The GNAT Library
23573@anchor{gnat_rm/the_gnat_library ada-containers-functional-maps-a-cofuma-ads}@anchor{2f3}@anchor{gnat_rm/the_gnat_library id16}@anchor{2f4}
23574@section @code{Ada.Containers.Functional_Maps} (@code{a-cofuma.ads})
23575
23576
23577@geindex Ada.Containers.Functional_Maps (a-cofuma.ads)
23578
23579@geindex Functional maps
23580
23581This child of @code{Ada.Containers} defines immutable maps. These containers are
23582unbounded and may contain indefinite elements. Furthermore, to be usable in
23583every context, they are neither controlled nor limited. As they are functional,
23584that is, no primitives are provided which would allow modifying an existing
23585container, these containers can still be used safely.
23586
23587Their API features functions creating new containers from existing ones.
23588As a consequence, these containers are highly inefficient. They are also
23589memory consuming, as the allocated memory is not reclaimed when the container
23590is no longer referenced. Thus, they should in general be used in ghost code
23591and annotations, so that they can be removed from the final executable. The
23592specification of this unit is compatible with SPARK 2014.
23593
23594@node Ada Containers Bounded_Holders a-coboho ads,Ada Command_Line Environment a-colien ads,Ada Containers Functional_Maps a-cofuma ads,The GNAT Library
23595@anchor{gnat_rm/the_gnat_library ada-containers-bounded-holders-a-coboho-ads}@anchor{2f5}@anchor{gnat_rm/the_gnat_library id17}@anchor{2f6}
23596@section @code{Ada.Containers.Bounded_Holders} (@code{a-coboho.ads})
23597
23598
23599@geindex Ada.Containers.Bounded_Holders (a-coboho.ads)
23600
23601@geindex Formal container for vectors
23602
23603This child of @code{Ada.Containers} defines a modified version of
23604Indefinite_Holders that avoids heap allocation.
23605
23606@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
23607@anchor{gnat_rm/the_gnat_library ada-command-line-environment-a-colien-ads}@anchor{2f7}@anchor{gnat_rm/the_gnat_library id18}@anchor{2f8}
23608@section @code{Ada.Command_Line.Environment} (@code{a-colien.ads})
23609
23610
23611@geindex Ada.Command_Line.Environment (a-colien.ads)
23612
23613@geindex Environment entries
23614
23615This child of @code{Ada.Command_Line}
23616provides a mechanism for obtaining environment values on systems
23617where this concept makes sense.
23618
23619@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
23620@anchor{gnat_rm/the_gnat_library ada-command-line-remove-a-colire-ads}@anchor{2f9}@anchor{gnat_rm/the_gnat_library id19}@anchor{2fa}
23621@section @code{Ada.Command_Line.Remove} (@code{a-colire.ads})
23622
23623
23624@geindex Ada.Command_Line.Remove (a-colire.ads)
23625
23626@geindex Removing command line arguments
23627
23628@geindex Command line
23629@geindex argument removal
23630
23631This child of @code{Ada.Command_Line}
23632provides a mechanism for logically removing
23633arguments from the argument list.  Once removed, an argument is not visible
23634to further calls on the subprograms in @code{Ada.Command_Line} will not
23635see the removed argument.
23636
23637@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
23638@anchor{gnat_rm/the_gnat_library ada-command-line-response-file-a-clrefi-ads}@anchor{2fb}@anchor{gnat_rm/the_gnat_library id20}@anchor{2fc}
23639@section @code{Ada.Command_Line.Response_File} (@code{a-clrefi.ads})
23640
23641
23642@geindex Ada.Command_Line.Response_File (a-clrefi.ads)
23643
23644@geindex Response file for command line
23645
23646@geindex Command line
23647@geindex response file
23648
23649@geindex Command line
23650@geindex handling long command lines
23651
23652This child of @code{Ada.Command_Line} provides a mechanism facilities for
23653getting command line arguments from a text file, called a “response file”.
23654Using a response file allow passing a set of arguments to an executable longer
23655than the maximum allowed by the system on the command line.
23656
23657@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
23658@anchor{gnat_rm/the_gnat_library ada-direct-io-c-streams-a-diocst-ads}@anchor{2fd}@anchor{gnat_rm/the_gnat_library id21}@anchor{2fe}
23659@section @code{Ada.Direct_IO.C_Streams} (@code{a-diocst.ads})
23660
23661
23662@geindex Ada.Direct_IO.C_Streams (a-diocst.ads)
23663
23664@geindex C Streams
23665@geindex Interfacing with Direct_IO
23666
23667This package provides subprograms that allow interfacing between
23668C streams and @code{Direct_IO}.  The stream identifier can be
23669extracted from a file opened on the Ada side, and an Ada file
23670can be constructed from a stream opened on the C side.
23671
23672@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
23673@anchor{gnat_rm/the_gnat_library ada-exceptions-is-null-occurrence-a-einuoc-ads}@anchor{2ff}@anchor{gnat_rm/the_gnat_library id22}@anchor{300}
23674@section @code{Ada.Exceptions.Is_Null_Occurrence} (@code{a-einuoc.ads})
23675
23676
23677@geindex Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads)
23678
23679@geindex Null_Occurrence
23680@geindex testing for
23681
23682This child subprogram provides a way of testing for the null
23683exception occurrence (@code{Null_Occurrence}) without raising
23684an exception.
23685
23686@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
23687@anchor{gnat_rm/the_gnat_library ada-exceptions-last-chance-handler-a-elchha-ads}@anchor{301}@anchor{gnat_rm/the_gnat_library id23}@anchor{302}
23688@section @code{Ada.Exceptions.Last_Chance_Handler} (@code{a-elchha.ads})
23689
23690
23691@geindex Ada.Exceptions.Last_Chance_Handler (a-elchha.ads)
23692
23693@geindex Null_Occurrence
23694@geindex testing for
23695
23696This child subprogram is used for handling otherwise unhandled
23697exceptions (hence the name last chance), and perform clean ups before
23698terminating the program. Note that this subprogram never returns.
23699
23700@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
23701@anchor{gnat_rm/the_gnat_library ada-exceptions-traceback-a-exctra-ads}@anchor{303}@anchor{gnat_rm/the_gnat_library id24}@anchor{304}
23702@section @code{Ada.Exceptions.Traceback} (@code{a-exctra.ads})
23703
23704
23705@geindex Ada.Exceptions.Traceback (a-exctra.ads)
23706
23707@geindex Traceback for Exception Occurrence
23708
23709This child package provides the subprogram (@code{Tracebacks}) to
23710give a traceback array of addresses based on an exception
23711occurrence.
23712
23713@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
23714@anchor{gnat_rm/the_gnat_library ada-sequential-io-c-streams-a-siocst-ads}@anchor{305}@anchor{gnat_rm/the_gnat_library id25}@anchor{306}
23715@section @code{Ada.Sequential_IO.C_Streams} (@code{a-siocst.ads})
23716
23717
23718@geindex Ada.Sequential_IO.C_Streams (a-siocst.ads)
23719
23720@geindex C Streams
23721@geindex Interfacing with Sequential_IO
23722
23723This package provides subprograms that allow interfacing between
23724C streams and @code{Sequential_IO}.  The stream identifier can be
23725extracted from a file opened on the Ada side, and an Ada file
23726can be constructed from a stream opened on the C side.
23727
23728@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
23729@anchor{gnat_rm/the_gnat_library ada-streams-stream-io-c-streams-a-ssicst-ads}@anchor{307}@anchor{gnat_rm/the_gnat_library id26}@anchor{308}
23730@section @code{Ada.Streams.Stream_IO.C_Streams} (@code{a-ssicst.ads})
23731
23732
23733@geindex Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads)
23734
23735@geindex C Streams
23736@geindex Interfacing with Stream_IO
23737
23738This package provides subprograms that allow interfacing between
23739C streams and @code{Stream_IO}.  The stream identifier can be
23740extracted from a file opened on the Ada side, and an Ada file
23741can be constructed from a stream opened on the C side.
23742
23743@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
23744@anchor{gnat_rm/the_gnat_library ada-strings-unbounded-text-io-a-suteio-ads}@anchor{309}@anchor{gnat_rm/the_gnat_library id27}@anchor{30a}
23745@section @code{Ada.Strings.Unbounded.Text_IO} (@code{a-suteio.ads})
23746
23747
23748@geindex Ada.Strings.Unbounded.Text_IO (a-suteio.ads)
23749
23750@geindex Unbounded_String
23751@geindex IO support
23752
23753@geindex Text_IO
23754@geindex extensions for unbounded strings
23755
23756This package provides subprograms for Text_IO for unbounded
23757strings, avoiding the necessity for an intermediate operation
23758with ordinary strings.
23759
23760@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
23761@anchor{gnat_rm/the_gnat_library ada-strings-wide-unbounded-wide-text-io-a-swuwti-ads}@anchor{30b}@anchor{gnat_rm/the_gnat_library id28}@anchor{30c}
23762@section @code{Ada.Strings.Wide_Unbounded.Wide_Text_IO} (@code{a-swuwti.ads})
23763
23764
23765@geindex Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads)
23766
23767@geindex Unbounded_Wide_String
23768@geindex IO support
23769
23770@geindex Text_IO
23771@geindex extensions for unbounded wide strings
23772
23773This package provides subprograms for Text_IO for unbounded
23774wide strings, avoiding the necessity for an intermediate operation
23775with ordinary wide strings.
23776
23777@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
23778@anchor{gnat_rm/the_gnat_library ada-strings-wide-wide-unbounded-wide-wide-text-io-a-szuzti-ads}@anchor{30d}@anchor{gnat_rm/the_gnat_library id29}@anchor{30e}
23779@section @code{Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO} (@code{a-szuzti.ads})
23780
23781
23782@geindex Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads)
23783
23784@geindex Unbounded_Wide_Wide_String
23785@geindex IO support
23786
23787@geindex Text_IO
23788@geindex extensions for unbounded wide wide strings
23789
23790This package provides subprograms for Text_IO for unbounded
23791wide wide strings, avoiding the necessity for an intermediate operation
23792with ordinary wide wide strings.
23793
23794@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
23795@anchor{gnat_rm/the_gnat_library ada-task-initialization-a-tasini-ads}@anchor{30f}@anchor{gnat_rm/the_gnat_library id30}@anchor{310}
23796@section @code{Ada.Task_Initialization} (@code{a-tasini.ads})
23797
23798
23799@geindex Ada.Task_Initialization (a-tasini.ads)
23800
23801This package provides a way to set a global initialization handler that
23802is automatically invoked whenever a task is activated. Handlers are
23803parameterless procedures. Note that such a handler is only invoked for
23804those tasks activated after the handler is set.
23805
23806@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
23807@anchor{gnat_rm/the_gnat_library ada-text-io-c-streams-a-tiocst-ads}@anchor{311}@anchor{gnat_rm/the_gnat_library id31}@anchor{312}
23808@section @code{Ada.Text_IO.C_Streams} (@code{a-tiocst.ads})
23809
23810
23811@geindex Ada.Text_IO.C_Streams (a-tiocst.ads)
23812
23813@geindex C Streams
23814@geindex Interfacing with `@w{`}Text_IO`@w{`}
23815
23816This package provides subprograms that allow interfacing between
23817C streams and @code{Text_IO}.  The stream identifier can be
23818extracted from a file opened on the Ada side, and an Ada file
23819can be constructed from a stream opened on the C side.
23820
23821@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
23822@anchor{gnat_rm/the_gnat_library ada-text-io-reset-standard-files-a-tirsfi-ads}@anchor{313}@anchor{gnat_rm/the_gnat_library id32}@anchor{314}
23823@section @code{Ada.Text_IO.Reset_Standard_Files} (@code{a-tirsfi.ads})
23824
23825
23826@geindex Ada.Text_IO.Reset_Standard_Files (a-tirsfi.ads)
23827
23828@geindex Text_IO resetting standard files
23829
23830This procedure is used to reset the status of the standard files used
23831by Ada.Text_IO.  This is useful in a situation (such as a restart in an
23832embedded application) where the status of the files may change during
23833execution (for example a standard input file may be redefined to be
23834interactive).
23835
23836@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
23837@anchor{gnat_rm/the_gnat_library ada-wide-characters-unicode-a-wichun-ads}@anchor{315}@anchor{gnat_rm/the_gnat_library id33}@anchor{316}
23838@section @code{Ada.Wide_Characters.Unicode} (@code{a-wichun.ads})
23839
23840
23841@geindex Ada.Wide_Characters.Unicode (a-wichun.ads)
23842
23843@geindex Unicode categorization
23844@geindex Wide_Character
23845
23846This package provides subprograms that allow categorization of
23847Wide_Character values according to Unicode categories.
23848
23849@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
23850@anchor{gnat_rm/the_gnat_library ada-wide-text-io-c-streams-a-wtcstr-ads}@anchor{317}@anchor{gnat_rm/the_gnat_library id34}@anchor{318}
23851@section @code{Ada.Wide_Text_IO.C_Streams} (@code{a-wtcstr.ads})
23852
23853
23854@geindex Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads)
23855
23856@geindex C Streams
23857@geindex Interfacing with `@w{`}Wide_Text_IO`@w{`}
23858
23859This package provides subprograms that allow interfacing between
23860C streams and @code{Wide_Text_IO}.  The stream identifier can be
23861extracted from a file opened on the Ada side, and an Ada file
23862can be constructed from a stream opened on the C side.
23863
23864@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
23865@anchor{gnat_rm/the_gnat_library ada-wide-text-io-reset-standard-files-a-wrstfi-ads}@anchor{319}@anchor{gnat_rm/the_gnat_library id35}@anchor{31a}
23866@section @code{Ada.Wide_Text_IO.Reset_Standard_Files} (@code{a-wrstfi.ads})
23867
23868
23869@geindex Ada.Wide_Text_IO.Reset_Standard_Files (a-wrstfi.ads)
23870
23871@geindex Wide_Text_IO resetting standard files
23872
23873This procedure is used to reset the status of the standard files used
23874by Ada.Wide_Text_IO.  This is useful in a situation (such as a restart in an
23875embedded application) where the status of the files may change during
23876execution (for example a standard input file may be redefined to be
23877interactive).
23878
23879@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
23880@anchor{gnat_rm/the_gnat_library ada-wide-wide-characters-unicode-a-zchuni-ads}@anchor{31b}@anchor{gnat_rm/the_gnat_library id36}@anchor{31c}
23881@section @code{Ada.Wide_Wide_Characters.Unicode} (@code{a-zchuni.ads})
23882
23883
23884@geindex Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads)
23885
23886@geindex Unicode categorization
23887@geindex Wide_Wide_Character
23888
23889This package provides subprograms that allow categorization of
23890Wide_Wide_Character values according to Unicode categories.
23891
23892@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
23893@anchor{gnat_rm/the_gnat_library ada-wide-wide-text-io-c-streams-a-ztcstr-ads}@anchor{31d}@anchor{gnat_rm/the_gnat_library id37}@anchor{31e}
23894@section @code{Ada.Wide_Wide_Text_IO.C_Streams} (@code{a-ztcstr.ads})
23895
23896
23897@geindex Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads)
23898
23899@geindex C Streams
23900@geindex Interfacing with `@w{`}Wide_Wide_Text_IO`@w{`}
23901
23902This package provides subprograms that allow interfacing between
23903C streams and @code{Wide_Wide_Text_IO}.  The stream identifier can be
23904extracted from a file opened on the Ada side, and an Ada file
23905can be constructed from a stream opened on the C side.
23906
23907@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
23908@anchor{gnat_rm/the_gnat_library ada-wide-wide-text-io-reset-standard-files-a-zrstfi-ads}@anchor{31f}@anchor{gnat_rm/the_gnat_library id38}@anchor{320}
23909@section @code{Ada.Wide_Wide_Text_IO.Reset_Standard_Files} (@code{a-zrstfi.ads})
23910
23911
23912@geindex Ada.Wide_Wide_Text_IO.Reset_Standard_Files (a-zrstfi.ads)
23913
23914@geindex Wide_Wide_Text_IO resetting standard files
23915
23916This procedure is used to reset the status of the standard files used
23917by Ada.Wide_Wide_Text_IO. This is useful in a situation (such as a
23918restart in an embedded application) where the status of the files may
23919change during execution (for example a standard input file may be
23920redefined to be interactive).
23921
23922@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
23923@anchor{gnat_rm/the_gnat_library gnat-altivec-g-altive-ads}@anchor{321}@anchor{gnat_rm/the_gnat_library id39}@anchor{322}
23924@section @code{GNAT.Altivec} (@code{g-altive.ads})
23925
23926
23927@geindex GNAT.Altivec (g-altive.ads)
23928
23929@geindex AltiVec
23930
23931This is the root package of the GNAT AltiVec binding. It provides
23932definitions of constants and types common to all the versions of the
23933binding.
23934
23935@node GNAT Altivec Conversions g-altcon ads,GNAT Altivec Vector_Operations g-alveop ads,GNAT Altivec g-altive ads,The GNAT Library
23936@anchor{gnat_rm/the_gnat_library gnat-altivec-conversions-g-altcon-ads}@anchor{323}@anchor{gnat_rm/the_gnat_library id40}@anchor{324}
23937@section @code{GNAT.Altivec.Conversions} (@code{g-altcon.ads})
23938
23939
23940@geindex GNAT.Altivec.Conversions (g-altcon.ads)
23941
23942@geindex AltiVec
23943
23944This package provides the Vector/View conversion routines.
23945
23946@node GNAT Altivec Vector_Operations g-alveop ads,GNAT Altivec Vector_Types g-alvety ads,GNAT Altivec Conversions g-altcon ads,The GNAT Library
23947@anchor{gnat_rm/the_gnat_library gnat-altivec-vector-operations-g-alveop-ads}@anchor{325}@anchor{gnat_rm/the_gnat_library id41}@anchor{326}
23948@section @code{GNAT.Altivec.Vector_Operations} (@code{g-alveop.ads})
23949
23950
23951@geindex GNAT.Altivec.Vector_Operations (g-alveop.ads)
23952
23953@geindex AltiVec
23954
23955This package exposes the Ada interface to the AltiVec operations on
23956vector objects. A soft emulation is included by default in the GNAT
23957library. The hard binding is provided as a separate package. This unit
23958is common to both bindings.
23959
23960@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
23961@anchor{gnat_rm/the_gnat_library gnat-altivec-vector-types-g-alvety-ads}@anchor{327}@anchor{gnat_rm/the_gnat_library id42}@anchor{328}
23962@section @code{GNAT.Altivec.Vector_Types} (@code{g-alvety.ads})
23963
23964
23965@geindex GNAT.Altivec.Vector_Types (g-alvety.ads)
23966
23967@geindex AltiVec
23968
23969This package exposes the various vector types part of the Ada binding
23970to AltiVec facilities.
23971
23972@node GNAT Altivec Vector_Views g-alvevi ads,GNAT Array_Split g-arrspl ads,GNAT Altivec Vector_Types g-alvety ads,The GNAT Library
23973@anchor{gnat_rm/the_gnat_library gnat-altivec-vector-views-g-alvevi-ads}@anchor{329}@anchor{gnat_rm/the_gnat_library id43}@anchor{32a}
23974@section @code{GNAT.Altivec.Vector_Views} (@code{g-alvevi.ads})
23975
23976
23977@geindex GNAT.Altivec.Vector_Views (g-alvevi.ads)
23978
23979@geindex AltiVec
23980
23981This package provides public ‘View’ data types from/to which private
23982vector representations can be converted via
23983GNAT.Altivec.Conversions. This allows convenient access to individual
23984vector elements and provides a simple way to initialize vector
23985objects.
23986
23987@node GNAT Array_Split g-arrspl ads,GNAT AWK g-awk ads,GNAT Altivec Vector_Views g-alvevi ads,The GNAT Library
23988@anchor{gnat_rm/the_gnat_library gnat-array-split-g-arrspl-ads}@anchor{32b}@anchor{gnat_rm/the_gnat_library id44}@anchor{32c}
23989@section @code{GNAT.Array_Split} (@code{g-arrspl.ads})
23990
23991
23992@geindex GNAT.Array_Split (g-arrspl.ads)
23993
23994@geindex Array splitter
23995
23996Useful array-manipulation routines: given a set of separators, split
23997an array wherever the separators appear, and provide direct access
23998to the resulting slices.
23999
24000@node GNAT AWK g-awk ads,GNAT Bind_Environment g-binenv ads,GNAT Array_Split g-arrspl ads,The GNAT Library
24001@anchor{gnat_rm/the_gnat_library gnat-awk-g-awk-ads}@anchor{32d}@anchor{gnat_rm/the_gnat_library id45}@anchor{32e}
24002@section @code{GNAT.AWK} (@code{g-awk.ads})
24003
24004
24005@geindex GNAT.AWK (g-awk.ads)
24006
24007@geindex Parsing
24008
24009@geindex AWK
24010
24011Provides AWK-like parsing functions, with an easy interface for parsing one
24012or more files containing formatted data.  The file is viewed as a database
24013where each record is a line and a field is a data element in this line.
24014
24015@node GNAT Bind_Environment g-binenv ads,GNAT Branch_Prediction g-brapre ads,GNAT AWK g-awk ads,The GNAT Library
24016@anchor{gnat_rm/the_gnat_library gnat-bind-environment-g-binenv-ads}@anchor{32f}@anchor{gnat_rm/the_gnat_library id46}@anchor{330}
24017@section @code{GNAT.Bind_Environment} (@code{g-binenv.ads})
24018
24019
24020@geindex GNAT.Bind_Environment (g-binenv.ads)
24021
24022@geindex Bind environment
24023
24024Provides access to key=value associations captured at bind time.
24025These associations can be specified using the @code{-V} binder command
24026line switch.
24027
24028@node GNAT Branch_Prediction g-brapre ads,GNAT Bounded_Buffers g-boubuf ads,GNAT Bind_Environment g-binenv ads,The GNAT Library
24029@anchor{gnat_rm/the_gnat_library gnat-branch-prediction-g-brapre-ads}@anchor{331}@anchor{gnat_rm/the_gnat_library id47}@anchor{332}
24030@section @code{GNAT.Branch_Prediction} (@code{g-brapre.ads})
24031
24032
24033@geindex GNAT.Branch_Prediction (g-brapre.ads)
24034
24035@geindex Branch Prediction
24036
24037Provides routines giving hints to the branch predictor of the code generator.
24038
24039@node GNAT Bounded_Buffers g-boubuf ads,GNAT Bounded_Mailboxes g-boumai ads,GNAT Branch_Prediction g-brapre ads,The GNAT Library
24040@anchor{gnat_rm/the_gnat_library gnat-bounded-buffers-g-boubuf-ads}@anchor{333}@anchor{gnat_rm/the_gnat_library id48}@anchor{334}
24041@section @code{GNAT.Bounded_Buffers} (@code{g-boubuf.ads})
24042
24043
24044@geindex GNAT.Bounded_Buffers (g-boubuf.ads)
24045
24046@geindex Parsing
24047
24048@geindex Bounded Buffers
24049
24050Provides a concurrent generic bounded buffer abstraction.  Instances are
24051useful directly or as parts of the implementations of other abstractions,
24052such as mailboxes.
24053
24054@node GNAT Bounded_Mailboxes g-boumai ads,GNAT Bubble_Sort g-bubsor ads,GNAT Bounded_Buffers g-boubuf ads,The GNAT Library
24055@anchor{gnat_rm/the_gnat_library gnat-bounded-mailboxes-g-boumai-ads}@anchor{335}@anchor{gnat_rm/the_gnat_library id49}@anchor{336}
24056@section @code{GNAT.Bounded_Mailboxes} (@code{g-boumai.ads})
24057
24058
24059@geindex GNAT.Bounded_Mailboxes (g-boumai.ads)
24060
24061@geindex Parsing
24062
24063@geindex Mailboxes
24064
24065Provides a thread-safe asynchronous intertask mailbox communication facility.
24066
24067@node GNAT Bubble_Sort g-bubsor ads,GNAT Bubble_Sort_A g-busora ads,GNAT Bounded_Mailboxes g-boumai ads,The GNAT Library
24068@anchor{gnat_rm/the_gnat_library gnat-bubble-sort-g-bubsor-ads}@anchor{337}@anchor{gnat_rm/the_gnat_library id50}@anchor{338}
24069@section @code{GNAT.Bubble_Sort} (@code{g-bubsor.ads})
24070
24071
24072@geindex GNAT.Bubble_Sort (g-bubsor.ads)
24073
24074@geindex Sorting
24075
24076@geindex Bubble sort
24077
24078Provides a general implementation of bubble sort usable for sorting arbitrary
24079data items.  Exchange and comparison procedures are provided by passing
24080access-to-procedure values.
24081
24082@node GNAT Bubble_Sort_A g-busora ads,GNAT Bubble_Sort_G g-busorg ads,GNAT Bubble_Sort g-bubsor ads,The GNAT Library
24083@anchor{gnat_rm/the_gnat_library gnat-bubble-sort-a-g-busora-ads}@anchor{339}@anchor{gnat_rm/the_gnat_library id51}@anchor{33a}
24084@section @code{GNAT.Bubble_Sort_A} (@code{g-busora.ads})
24085
24086
24087@geindex GNAT.Bubble_Sort_A (g-busora.ads)
24088
24089@geindex Sorting
24090
24091@geindex Bubble sort
24092
24093Provides a general implementation of bubble sort usable for sorting arbitrary
24094data items.  Move and comparison procedures are provided by passing
24095access-to-procedure values. This is an older version, retained for
24096compatibility. Usually @code{GNAT.Bubble_Sort} will be preferable.
24097
24098@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
24099@anchor{gnat_rm/the_gnat_library gnat-bubble-sort-g-g-busorg-ads}@anchor{33b}@anchor{gnat_rm/the_gnat_library id52}@anchor{33c}
24100@section @code{GNAT.Bubble_Sort_G} (@code{g-busorg.ads})
24101
24102
24103@geindex GNAT.Bubble_Sort_G (g-busorg.ads)
24104
24105@geindex Sorting
24106
24107@geindex Bubble sort
24108
24109Similar to @code{Bubble_Sort_A} except that the move and sorting procedures
24110are provided as generic parameters, this improves efficiency, especially
24111if the procedures can be inlined, at the expense of duplicating code for
24112multiple instantiations.
24113
24114@node GNAT Byte_Order_Mark g-byorma ads,GNAT Byte_Swapping g-bytswa ads,GNAT Bubble_Sort_G g-busorg ads,The GNAT Library
24115@anchor{gnat_rm/the_gnat_library gnat-byte-order-mark-g-byorma-ads}@anchor{33d}@anchor{gnat_rm/the_gnat_library id53}@anchor{33e}
24116@section @code{GNAT.Byte_Order_Mark} (@code{g-byorma.ads})
24117
24118
24119@geindex GNAT.Byte_Order_Mark (g-byorma.ads)
24120
24121@geindex UTF-8 representation
24122
24123@geindex Wide characte representations
24124
24125Provides a routine which given a string, reads the start of the string to
24126see whether it is one of the standard byte order marks (BOM’s) which signal
24127the encoding of the string. The routine includes detection of special XML
24128sequences for various UCS input formats.
24129
24130@node GNAT Byte_Swapping g-bytswa ads,GNAT Calendar g-calend ads,GNAT Byte_Order_Mark g-byorma ads,The GNAT Library
24131@anchor{gnat_rm/the_gnat_library gnat-byte-swapping-g-bytswa-ads}@anchor{33f}@anchor{gnat_rm/the_gnat_library id54}@anchor{340}
24132@section @code{GNAT.Byte_Swapping} (@code{g-bytswa.ads})
24133
24134
24135@geindex GNAT.Byte_Swapping (g-bytswa.ads)
24136
24137@geindex Byte swapping
24138
24139@geindex Endianness
24140
24141General routines for swapping the bytes in 2-, 4-, and 8-byte quantities.
24142Machine-specific implementations are available in some cases.
24143
24144@node GNAT Calendar g-calend ads,GNAT Calendar Time_IO g-catiio ads,GNAT Byte_Swapping g-bytswa ads,The GNAT Library
24145@anchor{gnat_rm/the_gnat_library gnat-calendar-g-calend-ads}@anchor{341}@anchor{gnat_rm/the_gnat_library id55}@anchor{342}
24146@section @code{GNAT.Calendar} (@code{g-calend.ads})
24147
24148
24149@geindex GNAT.Calendar (g-calend.ads)
24150
24151@geindex Calendar
24152
24153Extends the facilities provided by @code{Ada.Calendar} to include handling
24154of days of the week, an extended @code{Split} and @code{Time_Of} capability.
24155Also provides conversion of @code{Ada.Calendar.Time} values to and from the
24156C @code{timeval} format.
24157
24158@node GNAT Calendar Time_IO g-catiio ads,GNAT CRC32 g-crc32 ads,GNAT Calendar g-calend ads,The GNAT Library
24159@anchor{gnat_rm/the_gnat_library gnat-calendar-time-io-g-catiio-ads}@anchor{343}@anchor{gnat_rm/the_gnat_library id56}@anchor{344}
24160@section @code{GNAT.Calendar.Time_IO} (@code{g-catiio.ads})
24161
24162
24163@geindex Calendar
24164
24165@geindex Time
24166
24167@geindex GNAT.Calendar.Time_IO (g-catiio.ads)
24168
24169@node GNAT CRC32 g-crc32 ads,GNAT Case_Util g-casuti ads,GNAT Calendar Time_IO g-catiio ads,The GNAT Library
24170@anchor{gnat_rm/the_gnat_library gnat-crc32-g-crc32-ads}@anchor{345}@anchor{gnat_rm/the_gnat_library id57}@anchor{346}
24171@section @code{GNAT.CRC32} (@code{g-crc32.ads})
24172
24173
24174@geindex GNAT.CRC32 (g-crc32.ads)
24175
24176@geindex CRC32
24177
24178@geindex Cyclic Redundancy Check
24179
24180This package implements the CRC-32 algorithm.  For a full description
24181of this algorithm see
24182@emph{Computation of Cyclic Redundancy Checks via Table Look-Up},
24183@cite{Communications of the ACM}, Vol. 31 No. 8, pp. 1008-1013,
24184Aug. 1988.  Sarwate, D.V.
24185
24186@node GNAT Case_Util g-casuti ads,GNAT CGI g-cgi ads,GNAT CRC32 g-crc32 ads,The GNAT Library
24187@anchor{gnat_rm/the_gnat_library gnat-case-util-g-casuti-ads}@anchor{347}@anchor{gnat_rm/the_gnat_library id58}@anchor{348}
24188@section @code{GNAT.Case_Util} (@code{g-casuti.ads})
24189
24190
24191@geindex GNAT.Case_Util (g-casuti.ads)
24192
24193@geindex Casing utilities
24194
24195@geindex Character handling (`@w{`}GNAT.Case_Util`@w{`})
24196
24197A set of simple routines for handling upper and lower casing of strings
24198without the overhead of the full casing tables
24199in @code{Ada.Characters.Handling}.
24200
24201@node GNAT CGI g-cgi ads,GNAT CGI Cookie g-cgicoo ads,GNAT Case_Util g-casuti ads,The GNAT Library
24202@anchor{gnat_rm/the_gnat_library gnat-cgi-g-cgi-ads}@anchor{349}@anchor{gnat_rm/the_gnat_library id59}@anchor{34a}
24203@section @code{GNAT.CGI} (@code{g-cgi.ads})
24204
24205
24206@geindex GNAT.CGI (g-cgi.ads)
24207
24208@geindex CGI (Common Gateway Interface)
24209
24210This is a package for interfacing a GNAT program with a Web server via the
24211Common Gateway Interface (CGI).  Basically this package parses the CGI
24212parameters, which are a set of key/value pairs sent by the Web server.  It
24213builds a table whose index is the key and provides some services to deal
24214with this table.
24215
24216@node GNAT CGI Cookie g-cgicoo ads,GNAT CGI Debug g-cgideb ads,GNAT CGI g-cgi ads,The GNAT Library
24217@anchor{gnat_rm/the_gnat_library gnat-cgi-cookie-g-cgicoo-ads}@anchor{34b}@anchor{gnat_rm/the_gnat_library id60}@anchor{34c}
24218@section @code{GNAT.CGI.Cookie} (@code{g-cgicoo.ads})
24219
24220
24221@geindex GNAT.CGI.Cookie (g-cgicoo.ads)
24222
24223@geindex CGI (Common Gateway Interface) cookie support
24224
24225@geindex Cookie support in CGI
24226
24227This is a package to interface a GNAT program with a Web server via the
24228Common Gateway Interface (CGI).  It exports services to deal with Web
24229cookies (piece of information kept in the Web client software).
24230
24231@node GNAT CGI Debug g-cgideb ads,GNAT Command_Line g-comlin ads,GNAT CGI Cookie g-cgicoo ads,The GNAT Library
24232@anchor{gnat_rm/the_gnat_library gnat-cgi-debug-g-cgideb-ads}@anchor{34d}@anchor{gnat_rm/the_gnat_library id61}@anchor{34e}
24233@section @code{GNAT.CGI.Debug} (@code{g-cgideb.ads})
24234
24235
24236@geindex GNAT.CGI.Debug (g-cgideb.ads)
24237
24238@geindex CGI (Common Gateway Interface) debugging
24239
24240This is a package to help debugging CGI (Common Gateway Interface)
24241programs written in Ada.
24242
24243@node GNAT Command_Line g-comlin ads,GNAT Compiler_Version g-comver ads,GNAT CGI Debug g-cgideb ads,The GNAT Library
24244@anchor{gnat_rm/the_gnat_library gnat-command-line-g-comlin-ads}@anchor{34f}@anchor{gnat_rm/the_gnat_library id62}@anchor{350}
24245@section @code{GNAT.Command_Line} (@code{g-comlin.ads})
24246
24247
24248@geindex GNAT.Command_Line (g-comlin.ads)
24249
24250@geindex Command line
24251
24252Provides a high level interface to @code{Ada.Command_Line} facilities,
24253including the ability to scan for named switches with optional parameters
24254and expand file names using wildcard notations.
24255
24256@node GNAT Compiler_Version g-comver ads,GNAT Ctrl_C g-ctrl_c ads,GNAT Command_Line g-comlin ads,The GNAT Library
24257@anchor{gnat_rm/the_gnat_library gnat-compiler-version-g-comver-ads}@anchor{351}@anchor{gnat_rm/the_gnat_library id63}@anchor{352}
24258@section @code{GNAT.Compiler_Version} (@code{g-comver.ads})
24259
24260
24261@geindex GNAT.Compiler_Version (g-comver.ads)
24262
24263@geindex Compiler Version
24264
24265@geindex Version
24266@geindex of compiler
24267
24268Provides a routine for obtaining the version of the compiler used to
24269compile the program. More accurately this is the version of the binder
24270used to bind the program (this will normally be the same as the version
24271of the compiler if a consistent tool set is used to compile all units
24272of a partition).
24273
24274@node GNAT Ctrl_C g-ctrl_c ads,GNAT Current_Exception g-curexc ads,GNAT Compiler_Version g-comver ads,The GNAT Library
24275@anchor{gnat_rm/the_gnat_library gnat-ctrl-c-g-ctrl-c-ads}@anchor{353}@anchor{gnat_rm/the_gnat_library id64}@anchor{354}
24276@section @code{GNAT.Ctrl_C} (@code{g-ctrl_c.ads})
24277
24278
24279@geindex GNAT.Ctrl_C (g-ctrl_c.ads)
24280
24281@geindex Interrupt
24282
24283Provides a simple interface to handle Ctrl-C keyboard events.
24284
24285@node GNAT Current_Exception g-curexc ads,GNAT Debug_Pools g-debpoo ads,GNAT Ctrl_C g-ctrl_c ads,The GNAT Library
24286@anchor{gnat_rm/the_gnat_library gnat-current-exception-g-curexc-ads}@anchor{355}@anchor{gnat_rm/the_gnat_library id65}@anchor{356}
24287@section @code{GNAT.Current_Exception} (@code{g-curexc.ads})
24288
24289
24290@geindex GNAT.Current_Exception (g-curexc.ads)
24291
24292@geindex Current exception
24293
24294@geindex Exception retrieval
24295
24296Provides access to information on the current exception that has been raised
24297without the need for using the Ada 95 / Ada 2005 exception choice parameter
24298specification syntax.
24299This is particularly useful in simulating typical facilities for
24300obtaining information about exceptions provided by Ada 83 compilers.
24301
24302@node GNAT Debug_Pools g-debpoo ads,GNAT Debug_Utilities g-debuti ads,GNAT Current_Exception g-curexc ads,The GNAT Library
24303@anchor{gnat_rm/the_gnat_library gnat-debug-pools-g-debpoo-ads}@anchor{357}@anchor{gnat_rm/the_gnat_library id66}@anchor{358}
24304@section @code{GNAT.Debug_Pools} (@code{g-debpoo.ads})
24305
24306
24307@geindex GNAT.Debug_Pools (g-debpoo.ads)
24308
24309@geindex Debugging
24310
24311@geindex Debug pools
24312
24313@geindex Memory corruption debugging
24314
24315Provide a debugging storage pools that helps tracking memory corruption
24316problems.
24317See @code{The GNAT Debug_Pool Facility} section in the @cite{GNAT User’s Guide}.
24318
24319@node GNAT Debug_Utilities g-debuti ads,GNAT Decode_String g-decstr ads,GNAT Debug_Pools g-debpoo ads,The GNAT Library
24320@anchor{gnat_rm/the_gnat_library gnat-debug-utilities-g-debuti-ads}@anchor{359}@anchor{gnat_rm/the_gnat_library id67}@anchor{35a}
24321@section @code{GNAT.Debug_Utilities} (@code{g-debuti.ads})
24322
24323
24324@geindex GNAT.Debug_Utilities (g-debuti.ads)
24325
24326@geindex Debugging
24327
24328Provides a few useful utilities for debugging purposes, including conversion
24329to and from string images of address values. Supports both C and Ada formats
24330for hexadecimal literals.
24331
24332@node GNAT Decode_String g-decstr ads,GNAT Decode_UTF8_String g-deutst ads,GNAT Debug_Utilities g-debuti ads,The GNAT Library
24333@anchor{gnat_rm/the_gnat_library gnat-decode-string-g-decstr-ads}@anchor{35b}@anchor{gnat_rm/the_gnat_library id68}@anchor{35c}
24334@section @code{GNAT.Decode_String} (@code{g-decstr.ads})
24335
24336
24337@geindex GNAT.Decode_String (g-decstr.ads)
24338
24339@geindex Decoding strings
24340
24341@geindex String decoding
24342
24343@geindex Wide character encoding
24344
24345@geindex UTF-8
24346
24347@geindex Unicode
24348
24349A generic package providing routines for decoding wide character and wide wide
24350character strings encoded as sequences of 8-bit characters using a specified
24351encoding method. Includes validation routines, and also routines for stepping
24352to next or previous encoded character in an encoded string.
24353Useful in conjunction with Unicode character coding. Note there is a
24354preinstantiation for UTF-8. See next entry.
24355
24356@node GNAT Decode_UTF8_String g-deutst ads,GNAT Directory_Operations g-dirope ads,GNAT Decode_String g-decstr ads,The GNAT Library
24357@anchor{gnat_rm/the_gnat_library gnat-decode-utf8-string-g-deutst-ads}@anchor{35d}@anchor{gnat_rm/the_gnat_library id69}@anchor{35e}
24358@section @code{GNAT.Decode_UTF8_String} (@code{g-deutst.ads})
24359
24360
24361@geindex GNAT.Decode_UTF8_String (g-deutst.ads)
24362
24363@geindex Decoding strings
24364
24365@geindex Decoding UTF-8 strings
24366
24367@geindex UTF-8 string decoding
24368
24369@geindex Wide character decoding
24370
24371@geindex UTF-8
24372
24373@geindex Unicode
24374
24375A preinstantiation of GNAT.Decode_Strings for UTF-8 encoding.
24376
24377@node GNAT Directory_Operations g-dirope ads,GNAT Directory_Operations Iteration g-diopit ads,GNAT Decode_UTF8_String g-deutst ads,The GNAT Library
24378@anchor{gnat_rm/the_gnat_library gnat-directory-operations-g-dirope-ads}@anchor{35f}@anchor{gnat_rm/the_gnat_library id70}@anchor{360}
24379@section @code{GNAT.Directory_Operations} (@code{g-dirope.ads})
24380
24381
24382@geindex GNAT.Directory_Operations (g-dirope.ads)
24383
24384@geindex Directory operations
24385
24386Provides a set of routines for manipulating directories, including changing
24387the current directory, making new directories, and scanning the files in a
24388directory.
24389
24390@node GNAT Directory_Operations Iteration g-diopit ads,GNAT Dynamic_HTables g-dynhta ads,GNAT Directory_Operations g-dirope ads,The GNAT Library
24391@anchor{gnat_rm/the_gnat_library gnat-directory-operations-iteration-g-diopit-ads}@anchor{361}@anchor{gnat_rm/the_gnat_library id71}@anchor{362}
24392@section @code{GNAT.Directory_Operations.Iteration} (@code{g-diopit.ads})
24393
24394
24395@geindex GNAT.Directory_Operations.Iteration (g-diopit.ads)
24396
24397@geindex Directory operations iteration
24398
24399A child unit of GNAT.Directory_Operations providing additional operations
24400for iterating through directories.
24401
24402@node GNAT Dynamic_HTables g-dynhta ads,GNAT Dynamic_Tables g-dyntab ads,GNAT Directory_Operations Iteration g-diopit ads,The GNAT Library
24403@anchor{gnat_rm/the_gnat_library gnat-dynamic-htables-g-dynhta-ads}@anchor{363}@anchor{gnat_rm/the_gnat_library id72}@anchor{364}
24404@section @code{GNAT.Dynamic_HTables} (@code{g-dynhta.ads})
24405
24406
24407@geindex GNAT.Dynamic_HTables (g-dynhta.ads)
24408
24409@geindex Hash tables
24410
24411A generic implementation of hash tables that can be used to hash arbitrary
24412data.  Provided in two forms, a simple form with built in hash functions,
24413and a more complex form in which the hash function is supplied.
24414
24415This package provides a facility similar to that of @code{GNAT.HTable},
24416except that this package declares a type that can be used to define
24417dynamic instances of the hash table, while an instantiation of
24418@code{GNAT.HTable} creates a single instance of the hash table.
24419
24420@node GNAT Dynamic_Tables g-dyntab ads,GNAT Encode_String g-encstr ads,GNAT Dynamic_HTables g-dynhta ads,The GNAT Library
24421@anchor{gnat_rm/the_gnat_library gnat-dynamic-tables-g-dyntab-ads}@anchor{365}@anchor{gnat_rm/the_gnat_library id73}@anchor{366}
24422@section @code{GNAT.Dynamic_Tables} (@code{g-dyntab.ads})
24423
24424
24425@geindex GNAT.Dynamic_Tables (g-dyntab.ads)
24426
24427@geindex Table implementation
24428
24429@geindex Arrays
24430@geindex extendable
24431
24432A generic package providing a single dimension array abstraction where the
24433length of the array can be dynamically modified.
24434
24435This package provides a facility similar to that of @code{GNAT.Table},
24436except that this package declares a type that can be used to define
24437dynamic instances of the table, while an instantiation of
24438@code{GNAT.Table} creates a single instance of the table type.
24439
24440@node GNAT Encode_String g-encstr ads,GNAT Encode_UTF8_String g-enutst ads,GNAT Dynamic_Tables g-dyntab ads,The GNAT Library
24441@anchor{gnat_rm/the_gnat_library gnat-encode-string-g-encstr-ads}@anchor{367}@anchor{gnat_rm/the_gnat_library id74}@anchor{368}
24442@section @code{GNAT.Encode_String} (@code{g-encstr.ads})
24443
24444
24445@geindex GNAT.Encode_String (g-encstr.ads)
24446
24447@geindex Encoding strings
24448
24449@geindex String encoding
24450
24451@geindex Wide character encoding
24452
24453@geindex UTF-8
24454
24455@geindex Unicode
24456
24457A generic package providing routines for encoding wide character and wide
24458wide character strings as sequences of 8-bit characters using a specified
24459encoding method. Useful in conjunction with Unicode character coding.
24460Note there is a preinstantiation for UTF-8. See next entry.
24461
24462@node GNAT Encode_UTF8_String g-enutst ads,GNAT Exception_Actions g-excact ads,GNAT Encode_String g-encstr ads,The GNAT Library
24463@anchor{gnat_rm/the_gnat_library gnat-encode-utf8-string-g-enutst-ads}@anchor{369}@anchor{gnat_rm/the_gnat_library id75}@anchor{36a}
24464@section @code{GNAT.Encode_UTF8_String} (@code{g-enutst.ads})
24465
24466
24467@geindex GNAT.Encode_UTF8_String (g-enutst.ads)
24468
24469@geindex Encoding strings
24470
24471@geindex Encoding UTF-8 strings
24472
24473@geindex UTF-8 string encoding
24474
24475@geindex Wide character encoding
24476
24477@geindex UTF-8
24478
24479@geindex Unicode
24480
24481A preinstantiation of GNAT.Encode_Strings for UTF-8 encoding.
24482
24483@node GNAT Exception_Actions g-excact ads,GNAT Exception_Traces g-exctra ads,GNAT Encode_UTF8_String g-enutst ads,The GNAT Library
24484@anchor{gnat_rm/the_gnat_library gnat-exception-actions-g-excact-ads}@anchor{36b}@anchor{gnat_rm/the_gnat_library id76}@anchor{36c}
24485@section @code{GNAT.Exception_Actions} (@code{g-excact.ads})
24486
24487
24488@geindex GNAT.Exception_Actions (g-excact.ads)
24489
24490@geindex Exception actions
24491
24492Provides callbacks when an exception is raised. Callbacks can be registered
24493for specific exceptions, or when any exception is raised. This
24494can be used for instance to force a core dump to ease debugging.
24495
24496@node GNAT Exception_Traces g-exctra ads,GNAT Exceptions g-except ads,GNAT Exception_Actions g-excact ads,The GNAT Library
24497@anchor{gnat_rm/the_gnat_library gnat-exception-traces-g-exctra-ads}@anchor{36d}@anchor{gnat_rm/the_gnat_library id77}@anchor{36e}
24498@section @code{GNAT.Exception_Traces} (@code{g-exctra.ads})
24499
24500
24501@geindex GNAT.Exception_Traces (g-exctra.ads)
24502
24503@geindex Exception traces
24504
24505@geindex Debugging
24506
24507Provides an interface allowing to control automatic output upon exception
24508occurrences.
24509
24510@node GNAT Exceptions g-except ads,GNAT Expect g-expect ads,GNAT Exception_Traces g-exctra ads,The GNAT Library
24511@anchor{gnat_rm/the_gnat_library gnat-exceptions-g-except-ads}@anchor{36f}@anchor{gnat_rm/the_gnat_library id78}@anchor{370}
24512@section @code{GNAT.Exceptions} (@code{g-except.ads})
24513
24514
24515@geindex GNAT.Exceptions (g-except.ads)
24516
24517@geindex Exceptions
24518@geindex Pure
24519
24520@geindex Pure packages
24521@geindex exceptions
24522
24523Normally it is not possible to raise an exception with
24524a message from a subprogram in a pure package, since the
24525necessary types and subprograms are in @code{Ada.Exceptions}
24526which is not a pure unit. @code{GNAT.Exceptions} provides a
24527facility for getting around this limitation for a few
24528predefined exceptions, and for example allow raising
24529@code{Constraint_Error} with a message from a pure subprogram.
24530
24531@node GNAT Expect g-expect ads,GNAT Expect TTY g-exptty ads,GNAT Exceptions g-except ads,The GNAT Library
24532@anchor{gnat_rm/the_gnat_library gnat-expect-g-expect-ads}@anchor{371}@anchor{gnat_rm/the_gnat_library id79}@anchor{372}
24533@section @code{GNAT.Expect} (@code{g-expect.ads})
24534
24535
24536@geindex GNAT.Expect (g-expect.ads)
24537
24538Provides a set of subprograms similar to what is available
24539with the standard Tcl Expect tool.
24540It allows you to easily spawn and communicate with an external process.
24541You can send commands or inputs to the process, and compare the output
24542with some expected regular expression. Currently @code{GNAT.Expect}
24543is implemented on all native GNAT ports.
24544It is not implemented for cross ports, and in particular is not
24545implemented for VxWorks or LynxOS.
24546
24547@node GNAT Expect TTY g-exptty ads,GNAT Float_Control g-flocon ads,GNAT Expect g-expect ads,The GNAT Library
24548@anchor{gnat_rm/the_gnat_library gnat-expect-tty-g-exptty-ads}@anchor{373}@anchor{gnat_rm/the_gnat_library id80}@anchor{374}
24549@section @code{GNAT.Expect.TTY} (@code{g-exptty.ads})
24550
24551
24552@geindex GNAT.Expect.TTY (g-exptty.ads)
24553
24554As GNAT.Expect but using pseudo-terminal.
24555Currently @code{GNAT.Expect.TTY} is implemented on all native GNAT
24556ports. It is not implemented for cross ports, and
24557in particular is not implemented for VxWorks or LynxOS.
24558
24559@node GNAT Float_Control g-flocon ads,GNAT Formatted_String g-forstr ads,GNAT Expect TTY g-exptty ads,The GNAT Library
24560@anchor{gnat_rm/the_gnat_library gnat-float-control-g-flocon-ads}@anchor{375}@anchor{gnat_rm/the_gnat_library id81}@anchor{376}
24561@section @code{GNAT.Float_Control} (@code{g-flocon.ads})
24562
24563
24564@geindex GNAT.Float_Control (g-flocon.ads)
24565
24566@geindex Floating-Point Processor
24567
24568Provides an interface for resetting the floating-point processor into the
24569mode required for correct semantic operation in Ada.  Some third party
24570library calls may cause this mode to be modified, and the Reset procedure
24571in this package can be used to reestablish the required mode.
24572
24573@node GNAT Formatted_String g-forstr ads,GNAT Heap_Sort g-heasor ads,GNAT Float_Control g-flocon ads,The GNAT Library
24574@anchor{gnat_rm/the_gnat_library gnat-formatted-string-g-forstr-ads}@anchor{377}@anchor{gnat_rm/the_gnat_library id82}@anchor{378}
24575@section @code{GNAT.Formatted_String} (@code{g-forstr.ads})
24576
24577
24578@geindex GNAT.Formatted_String (g-forstr.ads)
24579
24580@geindex Formatted String
24581
24582Provides support for C/C++ printf() formatted strings. The format is
24583copied from the printf() routine and should therefore gives identical
24584output. Some generic routines are provided to be able to use types
24585derived from Integer, Float or enumerations as values for the
24586formatted string.
24587
24588@node GNAT Heap_Sort g-heasor ads,GNAT Heap_Sort_A g-hesora ads,GNAT Formatted_String g-forstr ads,The GNAT Library
24589@anchor{gnat_rm/the_gnat_library gnat-heap-sort-g-heasor-ads}@anchor{379}@anchor{gnat_rm/the_gnat_library id83}@anchor{37a}
24590@section @code{GNAT.Heap_Sort} (@code{g-heasor.ads})
24591
24592
24593@geindex GNAT.Heap_Sort (g-heasor.ads)
24594
24595@geindex Sorting
24596
24597Provides a general implementation of heap sort usable for sorting arbitrary
24598data items. Exchange and comparison procedures are provided by passing
24599access-to-procedure values.  The algorithm used is a modified heap sort
24600that performs approximately N*log(N) comparisons in the worst case.
24601
24602@node GNAT Heap_Sort_A g-hesora ads,GNAT Heap_Sort_G g-hesorg ads,GNAT Heap_Sort g-heasor ads,The GNAT Library
24603@anchor{gnat_rm/the_gnat_library gnat-heap-sort-a-g-hesora-ads}@anchor{37b}@anchor{gnat_rm/the_gnat_library id84}@anchor{37c}
24604@section @code{GNAT.Heap_Sort_A} (@code{g-hesora.ads})
24605
24606
24607@geindex GNAT.Heap_Sort_A (g-hesora.ads)
24608
24609@geindex Sorting
24610
24611Provides a general implementation of heap sort usable for sorting arbitrary
24612data items. Move and comparison procedures are provided by passing
24613access-to-procedure values.  The algorithm used is a modified heap sort
24614that performs approximately N*log(N) comparisons in the worst case.
24615This differs from @code{GNAT.Heap_Sort} in having a less convenient
24616interface, but may be slightly more efficient.
24617
24618@node GNAT Heap_Sort_G g-hesorg ads,GNAT HTable g-htable ads,GNAT Heap_Sort_A g-hesora ads,The GNAT Library
24619@anchor{gnat_rm/the_gnat_library gnat-heap-sort-g-g-hesorg-ads}@anchor{37d}@anchor{gnat_rm/the_gnat_library id85}@anchor{37e}
24620@section @code{GNAT.Heap_Sort_G} (@code{g-hesorg.ads})
24621
24622
24623@geindex GNAT.Heap_Sort_G (g-hesorg.ads)
24624
24625@geindex Sorting
24626
24627Similar to @code{Heap_Sort_A} except that the move and sorting procedures
24628are provided as generic parameters, this improves efficiency, especially
24629if the procedures can be inlined, at the expense of duplicating code for
24630multiple instantiations.
24631
24632@node GNAT HTable g-htable ads,GNAT IO g-io ads,GNAT Heap_Sort_G g-hesorg ads,The GNAT Library
24633@anchor{gnat_rm/the_gnat_library gnat-htable-g-htable-ads}@anchor{37f}@anchor{gnat_rm/the_gnat_library id86}@anchor{380}
24634@section @code{GNAT.HTable} (@code{g-htable.ads})
24635
24636
24637@geindex GNAT.HTable (g-htable.ads)
24638
24639@geindex Hash tables
24640
24641A generic implementation of hash tables that can be used to hash arbitrary
24642data.  Provides two approaches, one a simple static approach, and the other
24643allowing arbitrary dynamic hash tables.
24644
24645@node GNAT IO g-io ads,GNAT IO_Aux g-io_aux ads,GNAT HTable g-htable ads,The GNAT Library
24646@anchor{gnat_rm/the_gnat_library gnat-io-g-io-ads}@anchor{381}@anchor{gnat_rm/the_gnat_library id87}@anchor{382}
24647@section @code{GNAT.IO} (@code{g-io.ads})
24648
24649
24650@geindex GNAT.IO (g-io.ads)
24651
24652@geindex Simple I/O
24653
24654@geindex Input/Output facilities
24655
24656A simple preelaborable input-output package that provides a subset of
24657simple Text_IO functions for reading characters and strings from
24658Standard_Input, and writing characters, strings and integers to either
24659Standard_Output or Standard_Error.
24660
24661@node GNAT IO_Aux g-io_aux ads,GNAT Lock_Files g-locfil ads,GNAT IO g-io ads,The GNAT Library
24662@anchor{gnat_rm/the_gnat_library gnat-io-aux-g-io-aux-ads}@anchor{383}@anchor{gnat_rm/the_gnat_library id88}@anchor{384}
24663@section @code{GNAT.IO_Aux} (@code{g-io_aux.ads})
24664
24665
24666@geindex GNAT.IO_Aux (g-io_aux.ads)
24667
24668@geindex Text_IO
24669
24670@geindex Input/Output facilities
24671
24672Provides some auxiliary functions for use with Text_IO, including a test
24673for whether a file exists, and functions for reading a line of text.
24674
24675@node GNAT Lock_Files g-locfil ads,GNAT MBBS_Discrete_Random g-mbdira ads,GNAT IO_Aux g-io_aux ads,The GNAT Library
24676@anchor{gnat_rm/the_gnat_library gnat-lock-files-g-locfil-ads}@anchor{385}@anchor{gnat_rm/the_gnat_library id89}@anchor{386}
24677@section @code{GNAT.Lock_Files} (@code{g-locfil.ads})
24678
24679
24680@geindex GNAT.Lock_Files (g-locfil.ads)
24681
24682@geindex File locking
24683
24684@geindex Locking using files
24685
24686Provides a general interface for using files as locks.  Can be used for
24687providing program level synchronization.
24688
24689@node GNAT MBBS_Discrete_Random g-mbdira ads,GNAT MBBS_Float_Random g-mbflra ads,GNAT Lock_Files g-locfil ads,The GNAT Library
24690@anchor{gnat_rm/the_gnat_library gnat-mbbs-discrete-random-g-mbdira-ads}@anchor{387}@anchor{gnat_rm/the_gnat_library id90}@anchor{388}
24691@section @code{GNAT.MBBS_Discrete_Random} (@code{g-mbdira.ads})
24692
24693
24694@geindex GNAT.MBBS_Discrete_Random (g-mbdira.ads)
24695
24696@geindex Random number generation
24697
24698The original implementation of @code{Ada.Numerics.Discrete_Random}.  Uses
24699a modified version of the Blum-Blum-Shub generator.
24700
24701@node GNAT MBBS_Float_Random g-mbflra ads,GNAT MD5 g-md5 ads,GNAT MBBS_Discrete_Random g-mbdira ads,The GNAT Library
24702@anchor{gnat_rm/the_gnat_library gnat-mbbs-float-random-g-mbflra-ads}@anchor{389}@anchor{gnat_rm/the_gnat_library id91}@anchor{38a}
24703@section @code{GNAT.MBBS_Float_Random} (@code{g-mbflra.ads})
24704
24705
24706@geindex GNAT.MBBS_Float_Random (g-mbflra.ads)
24707
24708@geindex Random number generation
24709
24710The original implementation of @code{Ada.Numerics.Float_Random}.  Uses
24711a modified version of the Blum-Blum-Shub generator.
24712
24713@node GNAT MD5 g-md5 ads,GNAT Memory_Dump g-memdum ads,GNAT MBBS_Float_Random g-mbflra ads,The GNAT Library
24714@anchor{gnat_rm/the_gnat_library gnat-md5-g-md5-ads}@anchor{38b}@anchor{gnat_rm/the_gnat_library id92}@anchor{38c}
24715@section @code{GNAT.MD5} (@code{g-md5.ads})
24716
24717
24718@geindex GNAT.MD5 (g-md5.ads)
24719
24720@geindex Message Digest MD5
24721
24722Implements the MD5 Message-Digest Algorithm as described in RFC 1321, and
24723the HMAC-MD5 message authentication function as described in RFC 2104 and
24724FIPS PUB 198.
24725
24726@node GNAT Memory_Dump g-memdum ads,GNAT Most_Recent_Exception g-moreex ads,GNAT MD5 g-md5 ads,The GNAT Library
24727@anchor{gnat_rm/the_gnat_library gnat-memory-dump-g-memdum-ads}@anchor{38d}@anchor{gnat_rm/the_gnat_library id93}@anchor{38e}
24728@section @code{GNAT.Memory_Dump} (@code{g-memdum.ads})
24729
24730
24731@geindex GNAT.Memory_Dump (g-memdum.ads)
24732
24733@geindex Dump Memory
24734
24735Provides a convenient routine for dumping raw memory to either the
24736standard output or standard error files. Uses GNAT.IO for actual
24737output.
24738
24739@node GNAT Most_Recent_Exception g-moreex ads,GNAT OS_Lib g-os_lib ads,GNAT Memory_Dump g-memdum ads,The GNAT Library
24740@anchor{gnat_rm/the_gnat_library gnat-most-recent-exception-g-moreex-ads}@anchor{38f}@anchor{gnat_rm/the_gnat_library id94}@anchor{390}
24741@section @code{GNAT.Most_Recent_Exception} (@code{g-moreex.ads})
24742
24743
24744@geindex GNAT.Most_Recent_Exception (g-moreex.ads)
24745
24746@geindex Exception
24747@geindex obtaining most recent
24748
24749Provides access to the most recently raised exception.  Can be used for
24750various logging purposes, including duplicating functionality of some
24751Ada 83 implementation dependent extensions.
24752
24753@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
24754@anchor{gnat_rm/the_gnat_library gnat-os-lib-g-os-lib-ads}@anchor{391}@anchor{gnat_rm/the_gnat_library id95}@anchor{392}
24755@section @code{GNAT.OS_Lib} (@code{g-os_lib.ads})
24756
24757
24758@geindex GNAT.OS_Lib (g-os_lib.ads)
24759
24760@geindex Operating System interface
24761
24762@geindex Spawn capability
24763
24764Provides a range of target independent operating system interface functions,
24765including time/date management, file operations, subprocess management,
24766including a portable spawn procedure, and access to environment variables
24767and error return codes.
24768
24769@node GNAT Perfect_Hash_Generators g-pehage ads,GNAT Random_Numbers g-rannum ads,GNAT OS_Lib g-os_lib ads,The GNAT Library
24770@anchor{gnat_rm/the_gnat_library gnat-perfect-hash-generators-g-pehage-ads}@anchor{393}@anchor{gnat_rm/the_gnat_library id96}@anchor{394}
24771@section @code{GNAT.Perfect_Hash_Generators} (@code{g-pehage.ads})
24772
24773
24774@geindex GNAT.Perfect_Hash_Generators (g-pehage.ads)
24775
24776@geindex Hash functions
24777
24778Provides a generator of static minimal perfect hash functions. No
24779collisions occur and each item can be retrieved from the table in one
24780probe (perfect property). The hash table size corresponds to the exact
24781size of the key set and no larger (minimal property). The key set has to
24782be know in advance (static property). The hash functions are also order
24783preserving. If w2 is inserted after w1 in the generator, their
24784hashcode are in the same order. These hashing functions are very
24785convenient for use with realtime applications.
24786
24787@node GNAT Random_Numbers g-rannum ads,GNAT Regexp g-regexp ads,GNAT Perfect_Hash_Generators g-pehage ads,The GNAT Library
24788@anchor{gnat_rm/the_gnat_library gnat-random-numbers-g-rannum-ads}@anchor{395}@anchor{gnat_rm/the_gnat_library id97}@anchor{396}
24789@section @code{GNAT.Random_Numbers} (@code{g-rannum.ads})
24790
24791
24792@geindex GNAT.Random_Numbers (g-rannum.ads)
24793
24794@geindex Random number generation
24795
24796Provides random number capabilities which extend those available in the
24797standard Ada library and are more convenient to use.
24798
24799@node GNAT Regexp g-regexp ads,GNAT Registry g-regist ads,GNAT Random_Numbers g-rannum ads,The GNAT Library
24800@anchor{gnat_rm/the_gnat_library gnat-regexp-g-regexp-ads}@anchor{25c}@anchor{gnat_rm/the_gnat_library id98}@anchor{397}
24801@section @code{GNAT.Regexp} (@code{g-regexp.ads})
24802
24803
24804@geindex GNAT.Regexp (g-regexp.ads)
24805
24806@geindex Regular expressions
24807
24808@geindex Pattern matching
24809
24810A simple implementation of regular expressions, using a subset of regular
24811expression syntax copied from familiar Unix style utilities.  This is the
24812simplest of the three pattern matching packages provided, and is particularly
24813suitable for ‘file globbing’ applications.
24814
24815@node GNAT Registry g-regist ads,GNAT Regpat g-regpat ads,GNAT Regexp g-regexp ads,The GNAT Library
24816@anchor{gnat_rm/the_gnat_library gnat-registry-g-regist-ads}@anchor{398}@anchor{gnat_rm/the_gnat_library id99}@anchor{399}
24817@section @code{GNAT.Registry} (@code{g-regist.ads})
24818
24819
24820@geindex GNAT.Registry (g-regist.ads)
24821
24822@geindex Windows Registry
24823
24824This is a high level binding to the Windows registry.  It is possible to
24825do simple things like reading a key value, creating a new key.  For full
24826registry API, but at a lower level of abstraction, refer to the Win32.Winreg
24827package provided with the Win32Ada binding
24828
24829@node GNAT Regpat g-regpat ads,GNAT Rewrite_Data g-rewdat ads,GNAT Registry g-regist ads,The GNAT Library
24830@anchor{gnat_rm/the_gnat_library gnat-regpat-g-regpat-ads}@anchor{39a}@anchor{gnat_rm/the_gnat_library id100}@anchor{39b}
24831@section @code{GNAT.Regpat} (@code{g-regpat.ads})
24832
24833
24834@geindex GNAT.Regpat (g-regpat.ads)
24835
24836@geindex Regular expressions
24837
24838@geindex Pattern matching
24839
24840A complete implementation of Unix-style regular expression matching, copied
24841from the original V7 style regular expression library written in C by
24842Henry Spencer (and binary compatible with this C library).
24843
24844@node GNAT Rewrite_Data g-rewdat ads,GNAT Secondary_Stack_Info g-sestin ads,GNAT Regpat g-regpat ads,The GNAT Library
24845@anchor{gnat_rm/the_gnat_library gnat-rewrite-data-g-rewdat-ads}@anchor{39c}@anchor{gnat_rm/the_gnat_library id101}@anchor{39d}
24846@section @code{GNAT.Rewrite_Data} (@code{g-rewdat.ads})
24847
24848
24849@geindex GNAT.Rewrite_Data (g-rewdat.ads)
24850
24851@geindex Rewrite data
24852
24853A unit to rewrite on-the-fly string occurrences in a stream of
24854data. The implementation has a very minimal memory footprint as the
24855full content to be processed is not loaded into memory all at once. This makes
24856this interface usable for large files or socket streams.
24857
24858@node GNAT Secondary_Stack_Info g-sestin ads,GNAT Semaphores g-semaph ads,GNAT Rewrite_Data g-rewdat ads,The GNAT Library
24859@anchor{gnat_rm/the_gnat_library gnat-secondary-stack-info-g-sestin-ads}@anchor{39e}@anchor{gnat_rm/the_gnat_library id102}@anchor{39f}
24860@section @code{GNAT.Secondary_Stack_Info} (@code{g-sestin.ads})
24861
24862
24863@geindex GNAT.Secondary_Stack_Info (g-sestin.ads)
24864
24865@geindex Secondary Stack Info
24866
24867Provide the capability to query the high water mark of the current task’s
24868secondary stack.
24869
24870@node GNAT Semaphores g-semaph ads,GNAT Serial_Communications g-sercom ads,GNAT Secondary_Stack_Info g-sestin ads,The GNAT Library
24871@anchor{gnat_rm/the_gnat_library gnat-semaphores-g-semaph-ads}@anchor{3a0}@anchor{gnat_rm/the_gnat_library id103}@anchor{3a1}
24872@section @code{GNAT.Semaphores} (@code{g-semaph.ads})
24873
24874
24875@geindex GNAT.Semaphores (g-semaph.ads)
24876
24877@geindex Semaphores
24878
24879Provides classic counting and binary semaphores using protected types.
24880
24881@node GNAT Serial_Communications g-sercom ads,GNAT SHA1 g-sha1 ads,GNAT Semaphores g-semaph ads,The GNAT Library
24882@anchor{gnat_rm/the_gnat_library gnat-serial-communications-g-sercom-ads}@anchor{3a2}@anchor{gnat_rm/the_gnat_library id104}@anchor{3a3}
24883@section @code{GNAT.Serial_Communications} (@code{g-sercom.ads})
24884
24885
24886@geindex GNAT.Serial_Communications (g-sercom.ads)
24887
24888@geindex Serial_Communications
24889
24890Provides a simple interface to send and receive data over a serial
24891port. This is only supported on GNU/Linux and Windows.
24892
24893@node GNAT SHA1 g-sha1 ads,GNAT SHA224 g-sha224 ads,GNAT Serial_Communications g-sercom ads,The GNAT Library
24894@anchor{gnat_rm/the_gnat_library gnat-sha1-g-sha1-ads}@anchor{3a4}@anchor{gnat_rm/the_gnat_library id105}@anchor{3a5}
24895@section @code{GNAT.SHA1} (@code{g-sha1.ads})
24896
24897
24898@geindex GNAT.SHA1 (g-sha1.ads)
24899
24900@geindex Secure Hash Algorithm SHA-1
24901
24902Implements the SHA-1 Secure Hash Algorithm as described in FIPS PUB 180-3
24903and RFC 3174, and the HMAC-SHA1 message authentication function as described
24904in RFC 2104 and FIPS PUB 198.
24905
24906@node GNAT SHA224 g-sha224 ads,GNAT SHA256 g-sha256 ads,GNAT SHA1 g-sha1 ads,The GNAT Library
24907@anchor{gnat_rm/the_gnat_library gnat-sha224-g-sha224-ads}@anchor{3a6}@anchor{gnat_rm/the_gnat_library id106}@anchor{3a7}
24908@section @code{GNAT.SHA224} (@code{g-sha224.ads})
24909
24910
24911@geindex GNAT.SHA224 (g-sha224.ads)
24912
24913@geindex Secure Hash Algorithm SHA-224
24914
24915Implements the SHA-224 Secure Hash Algorithm as described in FIPS PUB 180-3,
24916and the HMAC-SHA224 message authentication function as described
24917in RFC 2104 and FIPS PUB 198.
24918
24919@node GNAT SHA256 g-sha256 ads,GNAT SHA384 g-sha384 ads,GNAT SHA224 g-sha224 ads,The GNAT Library
24920@anchor{gnat_rm/the_gnat_library gnat-sha256-g-sha256-ads}@anchor{3a8}@anchor{gnat_rm/the_gnat_library id107}@anchor{3a9}
24921@section @code{GNAT.SHA256} (@code{g-sha256.ads})
24922
24923
24924@geindex GNAT.SHA256 (g-sha256.ads)
24925
24926@geindex Secure Hash Algorithm SHA-256
24927
24928Implements the SHA-256 Secure Hash Algorithm as described in FIPS PUB 180-3,
24929and the HMAC-SHA256 message authentication function as described
24930in RFC 2104 and FIPS PUB 198.
24931
24932@node GNAT SHA384 g-sha384 ads,GNAT SHA512 g-sha512 ads,GNAT SHA256 g-sha256 ads,The GNAT Library
24933@anchor{gnat_rm/the_gnat_library gnat-sha384-g-sha384-ads}@anchor{3aa}@anchor{gnat_rm/the_gnat_library id108}@anchor{3ab}
24934@section @code{GNAT.SHA384} (@code{g-sha384.ads})
24935
24936
24937@geindex GNAT.SHA384 (g-sha384.ads)
24938
24939@geindex Secure Hash Algorithm SHA-384
24940
24941Implements the SHA-384 Secure Hash Algorithm as described in FIPS PUB 180-3,
24942and the HMAC-SHA384 message authentication function as described
24943in RFC 2104 and FIPS PUB 198.
24944
24945@node GNAT SHA512 g-sha512 ads,GNAT Signals g-signal ads,GNAT SHA384 g-sha384 ads,The GNAT Library
24946@anchor{gnat_rm/the_gnat_library gnat-sha512-g-sha512-ads}@anchor{3ac}@anchor{gnat_rm/the_gnat_library id109}@anchor{3ad}
24947@section @code{GNAT.SHA512} (@code{g-sha512.ads})
24948
24949
24950@geindex GNAT.SHA512 (g-sha512.ads)
24951
24952@geindex Secure Hash Algorithm SHA-512
24953
24954Implements the SHA-512 Secure Hash Algorithm as described in FIPS PUB 180-3,
24955and the HMAC-SHA512 message authentication function as described
24956in RFC 2104 and FIPS PUB 198.
24957
24958@node GNAT Signals g-signal ads,GNAT Sockets g-socket ads,GNAT SHA512 g-sha512 ads,The GNAT Library
24959@anchor{gnat_rm/the_gnat_library gnat-signals-g-signal-ads}@anchor{3ae}@anchor{gnat_rm/the_gnat_library id110}@anchor{3af}
24960@section @code{GNAT.Signals} (@code{g-signal.ads})
24961
24962
24963@geindex GNAT.Signals (g-signal.ads)
24964
24965@geindex Signals
24966
24967Provides the ability to manipulate the blocked status of signals on supported
24968targets.
24969
24970@node GNAT Sockets g-socket ads,GNAT Source_Info g-souinf ads,GNAT Signals g-signal ads,The GNAT Library
24971@anchor{gnat_rm/the_gnat_library gnat-sockets-g-socket-ads}@anchor{3b0}@anchor{gnat_rm/the_gnat_library id111}@anchor{3b1}
24972@section @code{GNAT.Sockets} (@code{g-socket.ads})
24973
24974
24975@geindex GNAT.Sockets (g-socket.ads)
24976
24977@geindex Sockets
24978
24979A high level and portable interface to develop sockets based applications.
24980This package is based on the sockets thin binding found in
24981@code{GNAT.Sockets.Thin}. Currently @code{GNAT.Sockets} is implemented
24982on all native GNAT ports and on VxWorks cross prots.  It is not implemented for
24983the LynxOS cross port.
24984
24985@node GNAT Source_Info g-souinf ads,GNAT Spelling_Checker g-speche ads,GNAT Sockets g-socket ads,The GNAT Library
24986@anchor{gnat_rm/the_gnat_library gnat-source-info-g-souinf-ads}@anchor{3b2}@anchor{gnat_rm/the_gnat_library id112}@anchor{3b3}
24987@section @code{GNAT.Source_Info} (@code{g-souinf.ads})
24988
24989
24990@geindex GNAT.Source_Info (g-souinf.ads)
24991
24992@geindex Source Information
24993
24994Provides subprograms that give access to source code information known at
24995compile time, such as the current file name and line number. Also provides
24996subprograms yielding the date and time of the current compilation (like the
24997C macros @code{__DATE__} and @code{__TIME__})
24998
24999@node GNAT Spelling_Checker g-speche ads,GNAT Spelling_Checker_Generic g-spchge ads,GNAT Source_Info g-souinf ads,The GNAT Library
25000@anchor{gnat_rm/the_gnat_library gnat-spelling-checker-g-speche-ads}@anchor{3b4}@anchor{gnat_rm/the_gnat_library id113}@anchor{3b5}
25001@section @code{GNAT.Spelling_Checker} (@code{g-speche.ads})
25002
25003
25004@geindex GNAT.Spelling_Checker (g-speche.ads)
25005
25006@geindex Spell checking
25007
25008Provides a function for determining whether one string is a plausible
25009near misspelling of another string.
25010
25011@node GNAT Spelling_Checker_Generic g-spchge ads,GNAT Spitbol Patterns g-spipat ads,GNAT Spelling_Checker g-speche ads,The GNAT Library
25012@anchor{gnat_rm/the_gnat_library gnat-spelling-checker-generic-g-spchge-ads}@anchor{3b6}@anchor{gnat_rm/the_gnat_library id114}@anchor{3b7}
25013@section @code{GNAT.Spelling_Checker_Generic} (@code{g-spchge.ads})
25014
25015
25016@geindex GNAT.Spelling_Checker_Generic (g-spchge.ads)
25017
25018@geindex Spell checking
25019
25020Provides a generic function that can be instantiated with a string type for
25021determining whether one string is a plausible near misspelling of another
25022string.
25023
25024@node GNAT Spitbol Patterns g-spipat ads,GNAT Spitbol g-spitbo ads,GNAT Spelling_Checker_Generic g-spchge ads,The GNAT Library
25025@anchor{gnat_rm/the_gnat_library gnat-spitbol-patterns-g-spipat-ads}@anchor{3b8}@anchor{gnat_rm/the_gnat_library id115}@anchor{3b9}
25026@section @code{GNAT.Spitbol.Patterns} (@code{g-spipat.ads})
25027
25028
25029@geindex GNAT.Spitbol.Patterns (g-spipat.ads)
25030
25031@geindex SPITBOL pattern matching
25032
25033@geindex Pattern matching
25034
25035A complete implementation of SNOBOL4 style pattern matching.  This is the
25036most elaborate of the pattern matching packages provided.  It fully duplicates
25037the SNOBOL4 dynamic pattern construction and matching capabilities, using the
25038efficient algorithm developed by Robert Dewar for the SPITBOL system.
25039
25040@node GNAT Spitbol g-spitbo ads,GNAT Spitbol Table_Boolean g-sptabo ads,GNAT Spitbol Patterns g-spipat ads,The GNAT Library
25041@anchor{gnat_rm/the_gnat_library gnat-spitbol-g-spitbo-ads}@anchor{3ba}@anchor{gnat_rm/the_gnat_library id116}@anchor{3bb}
25042@section @code{GNAT.Spitbol} (@code{g-spitbo.ads})
25043
25044
25045@geindex GNAT.Spitbol (g-spitbo.ads)
25046
25047@geindex SPITBOL interface
25048
25049The top level package of the collection of SPITBOL-style functionality, this
25050package provides basic SNOBOL4 string manipulation functions, such as
25051Pad, Reverse, Trim, Substr capability, as well as a generic table function
25052useful for constructing arbitrary mappings from strings in the style of
25053the SNOBOL4 TABLE function.
25054
25055@node GNAT Spitbol Table_Boolean g-sptabo ads,GNAT Spitbol Table_Integer g-sptain ads,GNAT Spitbol g-spitbo ads,The GNAT Library
25056@anchor{gnat_rm/the_gnat_library gnat-spitbol-table-boolean-g-sptabo-ads}@anchor{3bc}@anchor{gnat_rm/the_gnat_library id117}@anchor{3bd}
25057@section @code{GNAT.Spitbol.Table_Boolean} (@code{g-sptabo.ads})
25058
25059
25060@geindex GNAT.Spitbol.Table_Boolean (g-sptabo.ads)
25061
25062@geindex Sets of strings
25063
25064@geindex SPITBOL Tables
25065
25066A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table}
25067for type @code{Standard.Boolean}, giving an implementation of sets of
25068string values.
25069
25070@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
25071@anchor{gnat_rm/the_gnat_library gnat-spitbol-table-integer-g-sptain-ads}@anchor{3be}@anchor{gnat_rm/the_gnat_library id118}@anchor{3bf}
25072@section @code{GNAT.Spitbol.Table_Integer} (@code{g-sptain.ads})
25073
25074
25075@geindex GNAT.Spitbol.Table_Integer (g-sptain.ads)
25076
25077@geindex Integer maps
25078
25079@geindex Maps
25080
25081@geindex SPITBOL Tables
25082
25083A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table}
25084for type @code{Standard.Integer}, giving an implementation of maps
25085from string to integer values.
25086
25087@node GNAT Spitbol Table_VString g-sptavs ads,GNAT SSE g-sse ads,GNAT Spitbol Table_Integer g-sptain ads,The GNAT Library
25088@anchor{gnat_rm/the_gnat_library gnat-spitbol-table-vstring-g-sptavs-ads}@anchor{3c0}@anchor{gnat_rm/the_gnat_library id119}@anchor{3c1}
25089@section @code{GNAT.Spitbol.Table_VString} (@code{g-sptavs.ads})
25090
25091
25092@geindex GNAT.Spitbol.Table_VString (g-sptavs.ads)
25093
25094@geindex String maps
25095
25096@geindex Maps
25097
25098@geindex SPITBOL Tables
25099
25100A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table} for
25101a variable length string type, giving an implementation of general
25102maps from strings to strings.
25103
25104@node GNAT SSE g-sse ads,GNAT SSE Vector_Types g-ssvety ads,GNAT Spitbol Table_VString g-sptavs ads,The GNAT Library
25105@anchor{gnat_rm/the_gnat_library gnat-sse-g-sse-ads}@anchor{3c2}@anchor{gnat_rm/the_gnat_library id120}@anchor{3c3}
25106@section @code{GNAT.SSE} (@code{g-sse.ads})
25107
25108
25109@geindex GNAT.SSE (g-sse.ads)
25110
25111Root of a set of units aimed at offering Ada bindings to a subset of
25112the Intel(r) Streaming SIMD Extensions with GNAT on the x86 family of
25113targets.  It exposes vector component types together with a general
25114introduction to the binding contents and use.
25115
25116@node GNAT SSE Vector_Types g-ssvety ads,GNAT String_Hash g-strhas ads,GNAT SSE g-sse ads,The GNAT Library
25117@anchor{gnat_rm/the_gnat_library gnat-sse-vector-types-g-ssvety-ads}@anchor{3c4}@anchor{gnat_rm/the_gnat_library id121}@anchor{3c5}
25118@section @code{GNAT.SSE.Vector_Types} (@code{g-ssvety.ads})
25119
25120
25121@geindex GNAT.SSE.Vector_Types (g-ssvety.ads)
25122
25123SSE vector types for use with SSE related intrinsics.
25124
25125@node GNAT String_Hash g-strhas ads,GNAT Strings g-string ads,GNAT SSE Vector_Types g-ssvety ads,The GNAT Library
25126@anchor{gnat_rm/the_gnat_library gnat-string-hash-g-strhas-ads}@anchor{3c6}@anchor{gnat_rm/the_gnat_library id122}@anchor{3c7}
25127@section @code{GNAT.String_Hash} (@code{g-strhas.ads})
25128
25129
25130@geindex GNAT.String_Hash (g-strhas.ads)
25131
25132@geindex Hash functions
25133
25134Provides a generic hash function working on arrays of scalars. Both the scalar
25135type and the hash result type are parameters.
25136
25137@node GNAT Strings g-string ads,GNAT String_Split g-strspl ads,GNAT String_Hash g-strhas ads,The GNAT Library
25138@anchor{gnat_rm/the_gnat_library gnat-strings-g-string-ads}@anchor{3c8}@anchor{gnat_rm/the_gnat_library id123}@anchor{3c9}
25139@section @code{GNAT.Strings} (@code{g-string.ads})
25140
25141
25142@geindex GNAT.Strings (g-string.ads)
25143
25144Common String access types and related subprograms. Basically it
25145defines a string access and an array of string access types.
25146
25147@node GNAT String_Split g-strspl ads,GNAT Table g-table ads,GNAT Strings g-string ads,The GNAT Library
25148@anchor{gnat_rm/the_gnat_library gnat-string-split-g-strspl-ads}@anchor{3ca}@anchor{gnat_rm/the_gnat_library id124}@anchor{3cb}
25149@section @code{GNAT.String_Split} (@code{g-strspl.ads})
25150
25151
25152@geindex GNAT.String_Split (g-strspl.ads)
25153
25154@geindex String splitter
25155
25156Useful string manipulation routines: given a set of separators, split
25157a string wherever the separators appear, and provide direct access
25158to the resulting slices. This package is instantiated from
25159@code{GNAT.Array_Split}.
25160
25161@node GNAT Table g-table ads,GNAT Task_Lock g-tasloc ads,GNAT String_Split g-strspl ads,The GNAT Library
25162@anchor{gnat_rm/the_gnat_library gnat-table-g-table-ads}@anchor{3cc}@anchor{gnat_rm/the_gnat_library id125}@anchor{3cd}
25163@section @code{GNAT.Table} (@code{g-table.ads})
25164
25165
25166@geindex GNAT.Table (g-table.ads)
25167
25168@geindex Table implementation
25169
25170@geindex Arrays
25171@geindex extendable
25172
25173A generic package providing a single dimension array abstraction where the
25174length of the array can be dynamically modified.
25175
25176This package provides a facility similar to that of @code{GNAT.Dynamic_Tables},
25177except that this package declares a single instance of the table type,
25178while an instantiation of @code{GNAT.Dynamic_Tables} creates a type that can be
25179used to define dynamic instances of the table.
25180
25181@node GNAT Task_Lock g-tasloc ads,GNAT Time_Stamp g-timsta ads,GNAT Table g-table ads,The GNAT Library
25182@anchor{gnat_rm/the_gnat_library gnat-task-lock-g-tasloc-ads}@anchor{3ce}@anchor{gnat_rm/the_gnat_library id126}@anchor{3cf}
25183@section @code{GNAT.Task_Lock} (@code{g-tasloc.ads})
25184
25185
25186@geindex GNAT.Task_Lock (g-tasloc.ads)
25187
25188@geindex Task synchronization
25189
25190@geindex Task locking
25191
25192@geindex Locking
25193
25194A very simple facility for locking and unlocking sections of code using a
25195single global task lock.  Appropriate for use in situations where contention
25196between tasks is very rarely expected.
25197
25198@node GNAT Time_Stamp g-timsta ads,GNAT Threads g-thread ads,GNAT Task_Lock g-tasloc ads,The GNAT Library
25199@anchor{gnat_rm/the_gnat_library gnat-time-stamp-g-timsta-ads}@anchor{3d0}@anchor{gnat_rm/the_gnat_library id127}@anchor{3d1}
25200@section @code{GNAT.Time_Stamp} (@code{g-timsta.ads})
25201
25202
25203@geindex GNAT.Time_Stamp (g-timsta.ads)
25204
25205@geindex Time stamp
25206
25207@geindex Current time
25208
25209Provides a simple function that returns a string YYYY-MM-DD HH:MM:SS.SS that
25210represents the current date and time in ISO 8601 format. This is a very simple
25211routine with minimal code and there are no dependencies on any other unit.
25212
25213@node GNAT Threads g-thread ads,GNAT Traceback g-traceb ads,GNAT Time_Stamp g-timsta ads,The GNAT Library
25214@anchor{gnat_rm/the_gnat_library gnat-threads-g-thread-ads}@anchor{3d2}@anchor{gnat_rm/the_gnat_library id128}@anchor{3d3}
25215@section @code{GNAT.Threads} (@code{g-thread.ads})
25216
25217
25218@geindex GNAT.Threads (g-thread.ads)
25219
25220@geindex Foreign threads
25221
25222@geindex Threads
25223@geindex foreign
25224
25225Provides facilities for dealing with foreign threads which need to be known
25226by the GNAT run-time system. Consult the documentation of this package for
25227further details if your program has threads that are created by a non-Ada
25228environment which then accesses Ada code.
25229
25230@node GNAT Traceback g-traceb ads,GNAT Traceback Symbolic g-trasym ads,GNAT Threads g-thread ads,The GNAT Library
25231@anchor{gnat_rm/the_gnat_library gnat-traceback-g-traceb-ads}@anchor{3d4}@anchor{gnat_rm/the_gnat_library id129}@anchor{3d5}
25232@section @code{GNAT.Traceback} (@code{g-traceb.ads})
25233
25234
25235@geindex GNAT.Traceback (g-traceb.ads)
25236
25237@geindex Trace back facilities
25238
25239Provides a facility for obtaining non-symbolic traceback information, useful
25240in various debugging situations.
25241
25242@node GNAT Traceback Symbolic g-trasym ads,GNAT UTF_32 g-table ads,GNAT Traceback g-traceb ads,The GNAT Library
25243@anchor{gnat_rm/the_gnat_library gnat-traceback-symbolic-g-trasym-ads}@anchor{3d6}@anchor{gnat_rm/the_gnat_library id130}@anchor{3d7}
25244@section @code{GNAT.Traceback.Symbolic} (@code{g-trasym.ads})
25245
25246
25247@geindex GNAT.Traceback.Symbolic (g-trasym.ads)
25248
25249@geindex Trace back facilities
25250
25251@node GNAT UTF_32 g-table ads,GNAT Wide_Spelling_Checker g-u3spch ads,GNAT Traceback Symbolic g-trasym ads,The GNAT Library
25252@anchor{gnat_rm/the_gnat_library gnat-utf-32-g-table-ads}@anchor{3d8}@anchor{gnat_rm/the_gnat_library id131}@anchor{3d9}
25253@section @code{GNAT.UTF_32} (@code{g-table.ads})
25254
25255
25256@geindex GNAT.UTF_32 (g-table.ads)
25257
25258@geindex Wide character codes
25259
25260This is a package intended to be used in conjunction with the
25261@code{Wide_Character} type in Ada 95 and the
25262@code{Wide_Wide_Character} type in Ada 2005 (available
25263in @code{GNAT} in Ada 2005 mode). This package contains
25264Unicode categorization routines, as well as lexical
25265categorization routines corresponding to the Ada 2005
25266lexical rules for identifiers and strings, and also a
25267lower case to upper case fold routine corresponding to
25268the Ada 2005 rules for identifier equivalence.
25269
25270@node GNAT Wide_Spelling_Checker g-u3spch ads,GNAT Wide_Spelling_Checker g-wispch ads,GNAT UTF_32 g-table ads,The GNAT Library
25271@anchor{gnat_rm/the_gnat_library gnat-wide-spelling-checker-g-u3spch-ads}@anchor{3da}@anchor{gnat_rm/the_gnat_library id132}@anchor{3db}
25272@section @code{GNAT.Wide_Spelling_Checker} (@code{g-u3spch.ads})
25273
25274
25275@geindex GNAT.Wide_Spelling_Checker (g-u3spch.ads)
25276
25277@geindex Spell checking
25278
25279Provides a function for determining whether one wide wide string is a plausible
25280near misspelling of another wide wide string, where the strings are represented
25281using the UTF_32_String type defined in System.Wch_Cnv.
25282
25283@node GNAT Wide_Spelling_Checker g-wispch ads,GNAT Wide_String_Split g-wistsp ads,GNAT Wide_Spelling_Checker g-u3spch ads,The GNAT Library
25284@anchor{gnat_rm/the_gnat_library gnat-wide-spelling-checker-g-wispch-ads}@anchor{3dc}@anchor{gnat_rm/the_gnat_library id133}@anchor{3dd}
25285@section @code{GNAT.Wide_Spelling_Checker} (@code{g-wispch.ads})
25286
25287
25288@geindex GNAT.Wide_Spelling_Checker (g-wispch.ads)
25289
25290@geindex Spell checking
25291
25292Provides a function for determining whether one wide string is a plausible
25293near misspelling of another wide string.
25294
25295@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
25296@anchor{gnat_rm/the_gnat_library gnat-wide-string-split-g-wistsp-ads}@anchor{3de}@anchor{gnat_rm/the_gnat_library id134}@anchor{3df}
25297@section @code{GNAT.Wide_String_Split} (@code{g-wistsp.ads})
25298
25299
25300@geindex GNAT.Wide_String_Split (g-wistsp.ads)
25301
25302@geindex Wide_String splitter
25303
25304Useful wide string manipulation routines: given a set of separators, split
25305a wide string wherever the separators appear, and provide direct access
25306to the resulting slices. This package is instantiated from
25307@code{GNAT.Array_Split}.
25308
25309@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
25310@anchor{gnat_rm/the_gnat_library gnat-wide-wide-spelling-checker-g-zspche-ads}@anchor{3e0}@anchor{gnat_rm/the_gnat_library id135}@anchor{3e1}
25311@section @code{GNAT.Wide_Wide_Spelling_Checker} (@code{g-zspche.ads})
25312
25313
25314@geindex GNAT.Wide_Wide_Spelling_Checker (g-zspche.ads)
25315
25316@geindex Spell checking
25317
25318Provides a function for determining whether one wide wide string is a plausible
25319near misspelling of another wide wide string.
25320
25321@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
25322@anchor{gnat_rm/the_gnat_library gnat-wide-wide-string-split-g-zistsp-ads}@anchor{3e2}@anchor{gnat_rm/the_gnat_library id136}@anchor{3e3}
25323@section @code{GNAT.Wide_Wide_String_Split} (@code{g-zistsp.ads})
25324
25325
25326@geindex GNAT.Wide_Wide_String_Split (g-zistsp.ads)
25327
25328@geindex Wide_Wide_String splitter
25329
25330Useful wide wide string manipulation routines: given a set of separators, split
25331a wide wide string wherever the separators appear, and provide direct access
25332to the resulting slices. This package is instantiated from
25333@code{GNAT.Array_Split}.
25334
25335@node Interfaces C Extensions i-cexten ads,Interfaces C Streams i-cstrea ads,GNAT Wide_Wide_String_Split g-zistsp ads,The GNAT Library
25336@anchor{gnat_rm/the_gnat_library id137}@anchor{3e4}@anchor{gnat_rm/the_gnat_library interfaces-c-extensions-i-cexten-ads}@anchor{3e5}
25337@section @code{Interfaces.C.Extensions} (@code{i-cexten.ads})
25338
25339
25340@geindex Interfaces.C.Extensions (i-cexten.ads)
25341
25342This package contains additional C-related definitions, intended
25343for use with either manually or automatically generated bindings
25344to C libraries.
25345
25346@node Interfaces C Streams i-cstrea ads,Interfaces Packed_Decimal i-pacdec ads,Interfaces C Extensions i-cexten ads,The GNAT Library
25347@anchor{gnat_rm/the_gnat_library id138}@anchor{3e6}@anchor{gnat_rm/the_gnat_library interfaces-c-streams-i-cstrea-ads}@anchor{3e7}
25348@section @code{Interfaces.C.Streams} (@code{i-cstrea.ads})
25349
25350
25351@geindex Interfaces.C.Streams (i-cstrea.ads)
25352
25353@geindex C streams
25354@geindex interfacing
25355
25356This package is a binding for the most commonly used operations
25357on C streams.
25358
25359@node Interfaces Packed_Decimal i-pacdec ads,Interfaces VxWorks i-vxwork ads,Interfaces C Streams i-cstrea ads,The GNAT Library
25360@anchor{gnat_rm/the_gnat_library id139}@anchor{3e8}@anchor{gnat_rm/the_gnat_library interfaces-packed-decimal-i-pacdec-ads}@anchor{3e9}
25361@section @code{Interfaces.Packed_Decimal} (@code{i-pacdec.ads})
25362
25363
25364@geindex Interfaces.Packed_Decimal (i-pacdec.ads)
25365
25366@geindex IBM Packed Format
25367
25368@geindex Packed Decimal
25369
25370This package provides a set of routines for conversions to and
25371from a packed decimal format compatible with that used on IBM
25372mainframes.
25373
25374@node Interfaces VxWorks i-vxwork ads,Interfaces VxWorks Int_Connection i-vxinco ads,Interfaces Packed_Decimal i-pacdec ads,The GNAT Library
25375@anchor{gnat_rm/the_gnat_library id140}@anchor{3ea}@anchor{gnat_rm/the_gnat_library interfaces-vxworks-i-vxwork-ads}@anchor{3eb}
25376@section @code{Interfaces.VxWorks} (@code{i-vxwork.ads})
25377
25378
25379@geindex Interfaces.VxWorks (i-vxwork.ads)
25380
25381@geindex Interfacing to VxWorks
25382
25383@geindex VxWorks
25384@geindex interfacing
25385
25386This package provides a limited binding to the VxWorks API.
25387In particular, it interfaces with the
25388VxWorks hardware interrupt facilities.
25389
25390@node Interfaces VxWorks Int_Connection i-vxinco ads,Interfaces VxWorks IO i-vxwoio ads,Interfaces VxWorks i-vxwork ads,The GNAT Library
25391@anchor{gnat_rm/the_gnat_library id141}@anchor{3ec}@anchor{gnat_rm/the_gnat_library interfaces-vxworks-int-connection-i-vxinco-ads}@anchor{3ed}
25392@section @code{Interfaces.VxWorks.Int_Connection} (@code{i-vxinco.ads})
25393
25394
25395@geindex Interfaces.VxWorks.Int_Connection (i-vxinco.ads)
25396
25397@geindex Interfacing to VxWorks
25398
25399@geindex VxWorks
25400@geindex interfacing
25401
25402This package provides a way for users to replace the use of
25403intConnect() with a custom routine for installing interrupt
25404handlers.
25405
25406@node Interfaces VxWorks IO i-vxwoio ads,System Address_Image s-addima ads,Interfaces VxWorks Int_Connection i-vxinco ads,The GNAT Library
25407@anchor{gnat_rm/the_gnat_library id142}@anchor{3ee}@anchor{gnat_rm/the_gnat_library interfaces-vxworks-io-i-vxwoio-ads}@anchor{3ef}
25408@section @code{Interfaces.VxWorks.IO} (@code{i-vxwoio.ads})
25409
25410
25411@geindex Interfaces.VxWorks.IO (i-vxwoio.ads)
25412
25413@geindex Interfacing to VxWorks' I/O
25414
25415@geindex VxWorks
25416@geindex I/O interfacing
25417
25418@geindex VxWorks
25419@geindex Get_Immediate
25420
25421@geindex Get_Immediate
25422@geindex VxWorks
25423
25424This package provides a binding to the ioctl (IO/Control)
25425function of VxWorks, defining a set of option values and
25426function codes. A particular use of this package is
25427to enable the use of Get_Immediate under VxWorks.
25428
25429@node System Address_Image s-addima ads,System Assertions s-assert ads,Interfaces VxWorks IO i-vxwoio ads,The GNAT Library
25430@anchor{gnat_rm/the_gnat_library id143}@anchor{3f0}@anchor{gnat_rm/the_gnat_library system-address-image-s-addima-ads}@anchor{3f1}
25431@section @code{System.Address_Image} (@code{s-addima.ads})
25432
25433
25434@geindex System.Address_Image (s-addima.ads)
25435
25436@geindex Address image
25437
25438@geindex Image
25439@geindex of an address
25440
25441This function provides a useful debugging
25442function that gives an (implementation dependent)
25443string which identifies an address.
25444
25445@node System Assertions s-assert ads,System Atomic_Counters s-atocou ads,System Address_Image s-addima ads,The GNAT Library
25446@anchor{gnat_rm/the_gnat_library id144}@anchor{3f2}@anchor{gnat_rm/the_gnat_library system-assertions-s-assert-ads}@anchor{3f3}
25447@section @code{System.Assertions} (@code{s-assert.ads})
25448
25449
25450@geindex System.Assertions (s-assert.ads)
25451
25452@geindex Assertions
25453
25454@geindex Assert_Failure
25455@geindex exception
25456
25457This package provides the declaration of the exception raised
25458by an run-time assertion failure, as well as the routine that
25459is used internally to raise this assertion.
25460
25461@node System Atomic_Counters s-atocou ads,System Memory s-memory ads,System Assertions s-assert ads,The GNAT Library
25462@anchor{gnat_rm/the_gnat_library id145}@anchor{3f4}@anchor{gnat_rm/the_gnat_library system-atomic-counters-s-atocou-ads}@anchor{3f5}
25463@section @code{System.Atomic_Counters} (@code{s-atocou.ads})
25464
25465
25466@geindex System.Atomic_Counters (s-atocou.ads)
25467
25468This package provides the declaration of an atomic counter type,
25469together with efficient routines (using hardware
25470synchronization primitives) for incrementing, decrementing,
25471and testing of these counters. This package is implemented
25472on most targets, including all Alpha, AARCH64, ARM, ia64, PowerPC, SPARC V9,
25473x86, and x86_64 platforms.
25474
25475@node System Memory s-memory ads,System Multiprocessors s-multip ads,System Atomic_Counters s-atocou ads,The GNAT Library
25476@anchor{gnat_rm/the_gnat_library id146}@anchor{3f6}@anchor{gnat_rm/the_gnat_library system-memory-s-memory-ads}@anchor{3f7}
25477@section @code{System.Memory} (@code{s-memory.ads})
25478
25479
25480@geindex System.Memory (s-memory.ads)
25481
25482@geindex Memory allocation
25483
25484This package provides the interface to the low level routines used
25485by the generated code for allocation and freeing storage for the
25486default storage pool (analogous to the C routines malloc and free.
25487It also provides a reallocation interface analogous to the C routine
25488realloc. The body of this unit may be modified to provide alternative
25489allocation mechanisms for the default pool, and in addition, direct
25490calls to this unit may be made for low level allocation uses (for
25491example see the body of @code{GNAT.Tables}).
25492
25493@node System Multiprocessors s-multip ads,System Multiprocessors Dispatching_Domains s-mudido ads,System Memory s-memory ads,The GNAT Library
25494@anchor{gnat_rm/the_gnat_library id147}@anchor{3f8}@anchor{gnat_rm/the_gnat_library system-multiprocessors-s-multip-ads}@anchor{3f9}
25495@section @code{System.Multiprocessors} (@code{s-multip.ads})
25496
25497
25498@geindex System.Multiprocessors (s-multip.ads)
25499
25500@geindex Multiprocessor interface
25501
25502This is an Ada 2012 unit defined in the Ada 2012 Reference Manual, but
25503in GNAT we also make it available in Ada 95 and Ada 2005 (where it is
25504technically an implementation-defined addition).
25505
25506@node System Multiprocessors Dispatching_Domains s-mudido ads,System Partition_Interface s-parint ads,System Multiprocessors s-multip ads,The GNAT Library
25507@anchor{gnat_rm/the_gnat_library id148}@anchor{3fa}@anchor{gnat_rm/the_gnat_library system-multiprocessors-dispatching-domains-s-mudido-ads}@anchor{3fb}
25508@section @code{System.Multiprocessors.Dispatching_Domains} (@code{s-mudido.ads})
25509
25510
25511@geindex System.Multiprocessors.Dispatching_Domains (s-mudido.ads)
25512
25513@geindex Multiprocessor interface
25514
25515This is an Ada 2012 unit defined in the Ada 2012 Reference Manual, but
25516in GNAT we also make it available in Ada 95 and Ada 2005 (where it is
25517technically an implementation-defined addition).
25518
25519@node System Partition_Interface s-parint ads,System Pool_Global s-pooglo ads,System Multiprocessors Dispatching_Domains s-mudido ads,The GNAT Library
25520@anchor{gnat_rm/the_gnat_library id149}@anchor{3fc}@anchor{gnat_rm/the_gnat_library system-partition-interface-s-parint-ads}@anchor{3fd}
25521@section @code{System.Partition_Interface} (@code{s-parint.ads})
25522
25523
25524@geindex System.Partition_Interface (s-parint.ads)
25525
25526@geindex Partition interfacing functions
25527
25528This package provides facilities for partition interfacing.  It
25529is used primarily in a distribution context when using Annex E
25530with @code{GLADE}.
25531
25532@node System Pool_Global s-pooglo ads,System Pool_Local s-pooloc ads,System Partition_Interface s-parint ads,The GNAT Library
25533@anchor{gnat_rm/the_gnat_library id150}@anchor{3fe}@anchor{gnat_rm/the_gnat_library system-pool-global-s-pooglo-ads}@anchor{3ff}
25534@section @code{System.Pool_Global} (@code{s-pooglo.ads})
25535
25536
25537@geindex System.Pool_Global (s-pooglo.ads)
25538
25539@geindex Storage pool
25540@geindex global
25541
25542@geindex Global storage pool
25543
25544This package provides a storage pool that is equivalent to the default
25545storage pool used for access types for which no pool is specifically
25546declared. It uses malloc/free to allocate/free and does not attempt to
25547do any automatic reclamation.
25548
25549@node System Pool_Local s-pooloc ads,System Restrictions s-restri ads,System Pool_Global s-pooglo ads,The GNAT Library
25550@anchor{gnat_rm/the_gnat_library id151}@anchor{400}@anchor{gnat_rm/the_gnat_library system-pool-local-s-pooloc-ads}@anchor{401}
25551@section @code{System.Pool_Local} (@code{s-pooloc.ads})
25552
25553
25554@geindex System.Pool_Local (s-pooloc.ads)
25555
25556@geindex Storage pool
25557@geindex local
25558
25559@geindex Local storage pool
25560
25561This package provides a storage pool that is intended for use with locally
25562defined access types. It uses malloc/free for allocate/free, and maintains
25563a list of allocated blocks, so that all storage allocated for the pool can
25564be freed automatically when the pool is finalized.
25565
25566@node System Restrictions s-restri ads,System Rident s-rident ads,System Pool_Local s-pooloc ads,The GNAT Library
25567@anchor{gnat_rm/the_gnat_library id152}@anchor{402}@anchor{gnat_rm/the_gnat_library system-restrictions-s-restri-ads}@anchor{403}
25568@section @code{System.Restrictions} (@code{s-restri.ads})
25569
25570
25571@geindex System.Restrictions (s-restri.ads)
25572
25573@geindex Run-time restrictions access
25574
25575This package provides facilities for accessing at run time
25576the status of restrictions specified at compile time for
25577the partition. Information is available both with regard
25578to actual restrictions specified, and with regard to
25579compiler determined information on which restrictions
25580are violated by one or more packages in the partition.
25581
25582@node System Rident s-rident ads,System Strings Stream_Ops s-ststop ads,System Restrictions s-restri ads,The GNAT Library
25583@anchor{gnat_rm/the_gnat_library id153}@anchor{404}@anchor{gnat_rm/the_gnat_library system-rident-s-rident-ads}@anchor{405}
25584@section @code{System.Rident} (@code{s-rident.ads})
25585
25586
25587@geindex System.Rident (s-rident.ads)
25588
25589@geindex Restrictions definitions
25590
25591This package provides definitions of the restrictions
25592identifiers supported by GNAT, and also the format of
25593the restrictions provided in package System.Restrictions.
25594It is not normally necessary to @code{with} this generic package
25595since the necessary instantiation is included in
25596package System.Restrictions.
25597
25598@node System Strings Stream_Ops s-ststop ads,System Unsigned_Types s-unstyp ads,System Rident s-rident ads,The GNAT Library
25599@anchor{gnat_rm/the_gnat_library id154}@anchor{406}@anchor{gnat_rm/the_gnat_library system-strings-stream-ops-s-ststop-ads}@anchor{407}
25600@section @code{System.Strings.Stream_Ops} (@code{s-ststop.ads})
25601
25602
25603@geindex System.Strings.Stream_Ops (s-ststop.ads)
25604
25605@geindex Stream operations
25606
25607@geindex String stream operations
25608
25609This package provides a set of stream subprograms for standard string types.
25610It is intended primarily to support implicit use of such subprograms when
25611stream attributes are applied to string types, but the subprograms in this
25612package can be used directly by application programs.
25613
25614@node System Unsigned_Types s-unstyp ads,System Wch_Cnv s-wchcnv ads,System Strings Stream_Ops s-ststop ads,The GNAT Library
25615@anchor{gnat_rm/the_gnat_library id155}@anchor{408}@anchor{gnat_rm/the_gnat_library system-unsigned-types-s-unstyp-ads}@anchor{409}
25616@section @code{System.Unsigned_Types} (@code{s-unstyp.ads})
25617
25618
25619@geindex System.Unsigned_Types (s-unstyp.ads)
25620
25621This package contains definitions of standard unsigned types that
25622correspond in size to the standard signed types declared in Standard,
25623and (unlike the types in Interfaces) have corresponding names. It
25624also contains some related definitions for other specialized types
25625used by the compiler in connection with packed array types.
25626
25627@node System Wch_Cnv s-wchcnv ads,System Wch_Con s-wchcon ads,System Unsigned_Types s-unstyp ads,The GNAT Library
25628@anchor{gnat_rm/the_gnat_library id156}@anchor{40a}@anchor{gnat_rm/the_gnat_library system-wch-cnv-s-wchcnv-ads}@anchor{40b}
25629@section @code{System.Wch_Cnv} (@code{s-wchcnv.ads})
25630
25631
25632@geindex System.Wch_Cnv (s-wchcnv.ads)
25633
25634@geindex Wide Character
25635@geindex Representation
25636
25637@geindex Wide String
25638@geindex Conversion
25639
25640@geindex Representation of wide characters
25641
25642This package provides routines for converting between
25643wide and wide wide characters and a representation as a value of type
25644@code{Standard.String}, using a specified wide character
25645encoding method.  It uses definitions in
25646package @code{System.Wch_Con}.
25647
25648@node System Wch_Con s-wchcon ads,,System Wch_Cnv s-wchcnv ads,The GNAT Library
25649@anchor{gnat_rm/the_gnat_library id157}@anchor{40c}@anchor{gnat_rm/the_gnat_library system-wch-con-s-wchcon-ads}@anchor{40d}
25650@section @code{System.Wch_Con} (@code{s-wchcon.ads})
25651
25652
25653@geindex System.Wch_Con (s-wchcon.ads)
25654
25655This package provides definitions and descriptions of
25656the various methods used for encoding wide characters
25657in ordinary strings.  These definitions are used by
25658the package @code{System.Wch_Cnv}.
25659
25660@node Interfacing to Other Languages,Specialized Needs Annexes,The GNAT Library,Top
25661@anchor{gnat_rm/interfacing_to_other_languages doc}@anchor{40e}@anchor{gnat_rm/interfacing_to_other_languages id1}@anchor{40f}@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-other-languages}@anchor{11}
25662@chapter Interfacing to Other Languages
25663
25664
25665The facilities in Annex B of the Ada Reference Manual are fully
25666implemented in GNAT, and in addition, a full interface to C++ is
25667provided.
25668
25669@menu
25670* Interfacing to C::
25671* Interfacing to C++::
25672* Interfacing to COBOL::
25673* Interfacing to Fortran::
25674* Interfacing to non-GNAT Ada code::
25675
25676@end menu
25677
25678@node Interfacing to C,Interfacing to C++,,Interfacing to Other Languages
25679@anchor{gnat_rm/interfacing_to_other_languages id2}@anchor{410}@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-c}@anchor{411}
25680@section Interfacing to C
25681
25682
25683Interfacing to C with GNAT can use one of two approaches:
25684
25685
25686@itemize *
25687
25688@item
25689The types in the package @code{Interfaces.C} may be used.
25690
25691@item
25692Standard Ada types may be used directly.  This may be less portable to
25693other compilers, but will work on all GNAT compilers, which guarantee
25694correspondence between the C and Ada types.
25695@end itemize
25696
25697Pragma @code{Convention C} may be applied to Ada types, but mostly has no
25698effect, since this is the default.  The following table shows the
25699correspondence between Ada scalar types and the corresponding C types.
25700
25701
25702@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
25703@headitem
25704
25705Ada Type
25706
25707@tab
25708
25709C Type
25710
25711@item
25712
25713@code{Integer}
25714
25715@tab
25716
25717@code{int}
25718
25719@item
25720
25721@code{Short_Integer}
25722
25723@tab
25724
25725@code{short}
25726
25727@item
25728
25729@code{Short_Short_Integer}
25730
25731@tab
25732
25733@code{signed char}
25734
25735@item
25736
25737@code{Long_Integer}
25738
25739@tab
25740
25741@code{long}
25742
25743@item
25744
25745@code{Long_Long_Integer}
25746
25747@tab
25748
25749@code{long long}
25750
25751@item
25752
25753@code{Short_Float}
25754
25755@tab
25756
25757@code{float}
25758
25759@item
25760
25761@code{Float}
25762
25763@tab
25764
25765@code{float}
25766
25767@item
25768
25769@code{Long_Float}
25770
25771@tab
25772
25773@code{double}
25774
25775@item
25776
25777@code{Long_Long_Float}
25778
25779@tab
25780
25781This is the longest floating-point type supported by the hardware.
25782
25783@end multitable
25784
25785
25786Additionally, there are the following general correspondences between Ada
25787and C types:
25788
25789
25790@itemize *
25791
25792@item
25793Ada enumeration types map to C enumeration types directly if pragma
25794@code{Convention C} is specified, which causes them to have a length of
2579532 bits, except for boolean types which map to C99 @code{bool} and for
25796which the length is 8 bits.
25797Without pragma @code{Convention C}, Ada enumeration types map to
257988, 16, or 32 bits (i.e., C types @code{signed char}, @code{short},
25799@code{int}, respectively) depending on the number of values passed.
25800This is the only case in which pragma @code{Convention C} affects the
25801representation of an Ada type.
25802
25803@item
25804Ada access types map to C pointers, except for the case of pointers to
25805unconstrained types in Ada, which have no direct C equivalent.
25806
25807@item
25808Ada arrays map directly to C arrays.
25809
25810@item
25811Ada records map directly to C structures.
25812
25813@item
25814Packed Ada records map to C structures where all members are bit fields
25815of the length corresponding to the @code{type'Size} value in Ada.
25816@end itemize
25817
25818@node Interfacing to C++,Interfacing to COBOL,Interfacing to C,Interfacing to Other Languages
25819@anchor{gnat_rm/interfacing_to_other_languages id3}@anchor{48}@anchor{gnat_rm/interfacing_to_other_languages id4}@anchor{412}
25820@section Interfacing to C++
25821
25822
25823The interface to C++ makes use of the following pragmas, which are
25824primarily intended to be constructed automatically using a binding generator
25825tool, although it is possible to construct them by hand.
25826
25827Using these pragmas it is possible to achieve complete
25828inter-operability between Ada tagged types and C++ class definitions.
25829See @ref{7,,Implementation Defined Pragmas}, for more details.
25830
25831
25832@table @asis
25833
25834@item @code{pragma CPP_Class ([Entity =>] @emph{LOCAL_NAME})}
25835
25836The argument denotes an entity in the current declarative region that is
25837declared as a tagged or untagged record type. It indicates that the type
25838corresponds to an externally declared C++ class type, and is to be laid
25839out the same way that C++ would lay out the type.
25840
25841Note: Pragma @code{CPP_Class} is currently obsolete. It is supported
25842for backward compatibility but its functionality is available
25843using pragma @code{Import} with @code{Convention} = @code{CPP}.
25844
25845@item @code{pragma CPP_Constructor ([Entity =>] @emph{LOCAL_NAME})}
25846
25847This pragma identifies an imported function (imported in the usual way
25848with pragma @code{Import}) as corresponding to a C++ constructor.
25849@end table
25850
25851A few restrictions are placed on the use of the @code{Access} attribute
25852in conjunction with subprograms subject to convention @code{CPP}: the
25853attribute may be used neither on primitive operations of a tagged
25854record type with convention @code{CPP}, imported or not, nor on
25855subprograms imported with pragma @code{CPP_Constructor}.
25856
25857In addition, C++ exceptions are propagated and can be handled in an
25858@code{others} choice of an exception handler. The corresponding Ada
25859occurrence has no message, and the simple name of the exception identity
25860contains @code{Foreign_Exception}. Finalization and awaiting dependent
25861tasks works properly when such foreign exceptions are propagated.
25862
25863It is also possible to import a C++ exception using the following syntax:
25864
25865@example
25866LOCAL_NAME : exception;
25867pragma Import (Cpp,
25868  [Entity =>] LOCAL_NAME,
25869  [External_Name =>] static_string_EXPRESSION);
25870@end example
25871
25872The @code{External_Name} is the name of the C++ RTTI symbol. You can then
25873cover a specific C++ exception in an exception handler.
25874
25875@node Interfacing to COBOL,Interfacing to Fortran,Interfacing to C++,Interfacing to Other Languages
25876@anchor{gnat_rm/interfacing_to_other_languages id5}@anchor{413}@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-cobol}@anchor{414}
25877@section Interfacing to COBOL
25878
25879
25880Interfacing to COBOL is achieved as described in section B.4 of
25881the Ada Reference Manual.
25882
25883@node Interfacing to Fortran,Interfacing to non-GNAT Ada code,Interfacing to COBOL,Interfacing to Other Languages
25884@anchor{gnat_rm/interfacing_to_other_languages id6}@anchor{415}@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-fortran}@anchor{416}
25885@section Interfacing to Fortran
25886
25887
25888Interfacing to Fortran is achieved as described in section B.5 of the
25889Ada Reference Manual.  The pragma @code{Convention Fortran}, applied to a
25890multi-dimensional array causes the array to be stored in column-major
25891order as required for convenient interface to Fortran.
25892
25893@node Interfacing to non-GNAT Ada code,,Interfacing to Fortran,Interfacing to Other Languages
25894@anchor{gnat_rm/interfacing_to_other_languages id7}@anchor{417}@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-non-gnat-ada-code}@anchor{418}
25895@section Interfacing to non-GNAT Ada code
25896
25897
25898It is possible to specify the convention @code{Ada} in a pragma
25899@code{Import} or pragma @code{Export}.  However this refers to
25900the calling conventions used by GNAT, which may or may not be
25901similar enough to those used by some other Ada 83 / Ada 95 / Ada 2005
25902compiler to allow interoperation.
25903
25904If arguments types are kept simple, and if the foreign compiler generally
25905follows system calling conventions, then it may be possible to integrate
25906files compiled by other Ada compilers, provided that the elaboration
25907issues are adequately addressed (for example by eliminating the
25908need for any load time elaboration).
25909
25910In particular, GNAT running on VMS is designed to
25911be highly compatible with the DEC Ada 83 compiler, so this is one
25912case in which it is possible to import foreign units of this type,
25913provided that the data items passed are restricted to simple scalar
25914values or simple record types without variants, or simple array
25915types with fixed bounds.
25916
25917@node Specialized Needs Annexes,Implementation of Specific Ada Features,Interfacing to Other Languages,Top
25918@anchor{gnat_rm/specialized_needs_annexes doc}@anchor{419}@anchor{gnat_rm/specialized_needs_annexes id1}@anchor{41a}@anchor{gnat_rm/specialized_needs_annexes specialized-needs-annexes}@anchor{12}
25919@chapter Specialized Needs Annexes
25920
25921
25922Ada 95, Ada 2005, and Ada 2012 define a number of Specialized Needs Annexes, which are not
25923required in all implementations.  However, as described in this chapter,
25924GNAT implements all of these annexes:
25925
25926
25927@table @asis
25928
25929@item @emph{Systems Programming (Annex C)}
25930
25931The Systems Programming Annex is fully implemented.
25932
25933@item @emph{Real-Time Systems (Annex D)}
25934
25935The Real-Time Systems Annex is fully implemented.
25936
25937@item @emph{Distributed Systems (Annex E)}
25938
25939Stub generation is fully implemented in the GNAT compiler.  In addition,
25940a complete compatible PCS is available as part of the GLADE system,
25941a separate product.  When the two
25942products are used in conjunction, this annex is fully implemented.
25943
25944@item @emph{Information Systems (Annex F)}
25945
25946The Information Systems annex is fully implemented.
25947
25948@item @emph{Numerics (Annex G)}
25949
25950The Numerics Annex is fully implemented.
25951
25952@item @emph{Safety and Security / High-Integrity Systems (Annex H)}
25953
25954The Safety and Security Annex (termed the High-Integrity Systems Annex
25955in Ada 2005) is fully implemented.
25956@end table
25957
25958@node Implementation of Specific Ada Features,Implementation of Ada 2012 Features,Specialized Needs Annexes,Top
25959@anchor{gnat_rm/implementation_of_specific_ada_features doc}@anchor{41b}@anchor{gnat_rm/implementation_of_specific_ada_features id1}@anchor{41c}@anchor{gnat_rm/implementation_of_specific_ada_features implementation-of-specific-ada-features}@anchor{13}
25960@chapter Implementation of Specific Ada Features
25961
25962
25963This chapter describes the GNAT implementation of several Ada language
25964facilities.
25965
25966@menu
25967* Machine Code Insertions::
25968* GNAT Implementation of Tasking::
25969* GNAT Implementation of Shared Passive Packages::
25970* Code Generation for Array Aggregates::
25971* The Size of Discriminated Records with Default Discriminants::
25972* Image Values For Nonscalar Types::
25973* Strict Conformance to the Ada Reference Manual::
25974
25975@end menu
25976
25977@node Machine Code Insertions,GNAT Implementation of Tasking,,Implementation of Specific Ada Features
25978@anchor{gnat_rm/implementation_of_specific_ada_features id2}@anchor{41d}@anchor{gnat_rm/implementation_of_specific_ada_features machine-code-insertions}@anchor{167}
25979@section Machine Code Insertions
25980
25981
25982@geindex Machine Code insertions
25983
25984Package @code{Machine_Code} provides machine code support as described
25985in the Ada Reference Manual in two separate forms:
25986
25987
25988@itemize *
25989
25990@item
25991Machine code statements, consisting of qualified expressions that
25992fit the requirements of RM section 13.8.
25993
25994@item
25995An intrinsic callable procedure, providing an alternative mechanism of
25996including machine instructions in a subprogram.
25997@end itemize
25998
25999The two features are similar, and both are closely related to the mechanism
26000provided by the asm instruction in the GNU C compiler.  Full understanding
26001and use of the facilities in this package requires understanding the asm
26002instruction, see the section on Extended Asm in
26003@cite{Using_the_GNU_Compiler_Collection_(GCC)}.
26004
26005Calls to the function @code{Asm} and the procedure @code{Asm} have identical
26006semantic restrictions and effects as described below.  Both are provided so
26007that the procedure call can be used as a statement, and the function call
26008can be used to form a code_statement.
26009
26010Consider this C @code{asm} instruction:
26011
26012@example
26013asm ("fsinx %1 %0" : "=f" (result) : "f" (angle));
26014@end example
26015
26016The equivalent can be written for GNAT as:
26017
26018@example
26019Asm ("fsinx %1 %0",
26020     My_Float'Asm_Output ("=f", result),
26021     My_Float'Asm_Input  ("f",  angle));
26022@end example
26023
26024The first argument to @code{Asm} is the assembler template, and is
26025identical to what is used in GNU C.  This string must be a static
26026expression.  The second argument is the output operand list.  It is
26027either a single @code{Asm_Output} attribute reference, or a list of such
26028references enclosed in parentheses (technically an array aggregate of
26029such references).
26030
26031The @code{Asm_Output} attribute denotes a function that takes two
26032parameters.  The first is a string, the second is the name of a variable
26033of the type designated by the attribute prefix.  The first (string)
26034argument is required to be a static expression and designates the
26035constraint (see the section on Constraints in
26036@cite{Using_the_GNU_Compiler_Collection_(GCC)})
26037for the parameter; e.g., what kind of register is required.  The second
26038argument is the variable to be written or updated with the
26039result.  The possible values for constraint are the same as those used in
26040the RTL, and are dependent on the configuration file used to build the
26041GCC back end.  If there are no output operands, then this argument may
26042either be omitted, or explicitly given as @code{No_Output_Operands}.
26043No support is provided for GNU C’s symbolic names for output parameters.
26044
26045The second argument of @code{my_float'Asm_Output} functions as
26046though it were an @code{out} parameter, which is a little curious, but
26047all names have the form of expressions, so there is no syntactic
26048irregularity, even though normally functions would not be permitted
26049@code{out} parameters.  The third argument is the list of input
26050operands.  It is either a single @code{Asm_Input} attribute reference, or
26051a list of such references enclosed in parentheses (technically an array
26052aggregate of such references).
26053
26054The @code{Asm_Input} attribute denotes a function that takes two
26055parameters.  The first is a string, the second is an expression of the
26056type designated by the prefix.  The first (string) argument is required
26057to be a static expression, and is the constraint for the parameter,
26058(e.g., what kind of register is required).  The second argument is the
26059value to be used as the input argument.  The possible values for the
26060constraint are the same as those used in the RTL, and are dependent on
26061the configuration file used to built the GCC back end.
26062No support is provided for GNU C’s symbolic names for input parameters.
26063
26064If there are no input operands, this argument may either be omitted, or
26065explicitly given as @code{No_Input_Operands}.  The fourth argument, not
26066present in the above example, is a list of register names, called the
26067@emph{clobber} argument.  This argument, if given, must be a static string
26068expression, and is a space or comma separated list of names of registers
26069that must be considered destroyed as a result of the @code{Asm} call.  If
26070this argument is the null string (the default value), then the code
26071generator assumes that no additional registers are destroyed.
26072In addition to registers, the special clobbers @code{memory} and
26073@code{cc} as described in the GNU C docs are both supported.
26074
26075The fifth argument, not present in the above example, called the
26076@emph{volatile} argument, is by default @code{False}.  It can be set to
26077the literal value @code{True} to indicate to the code generator that all
26078optimizations with respect to the instruction specified should be
26079suppressed, and in particular an instruction that has outputs
26080will still be generated, even if none of the outputs are
26081used.  See @cite{Using_the_GNU_Compiler_Collection_(GCC)}
26082for the full description.
26083Generally it is strongly advisable to use Volatile for any ASM statement
26084that is missing either input or output operands or to avoid unwanted
26085optimizations. A warning is generated if this advice is not followed.
26086
26087No support is provided for GNU C’s @code{asm goto} feature.
26088
26089The @code{Asm} subprograms may be used in two ways.  First the procedure
26090forms can be used anywhere a procedure call would be valid, and
26091correspond to what the RM calls ‘intrinsic’ routines.  Such calls can
26092be used to intersperse machine instructions with other Ada statements.
26093Second, the function forms, which return a dummy value of the limited
26094private type @code{Asm_Insn}, can be used in code statements, and indeed
26095this is the only context where such calls are allowed.  Code statements
26096appear as aggregates of the form:
26097
26098@example
26099Asm_Insn'(Asm (...));
26100Asm_Insn'(Asm_Volatile (...));
26101@end example
26102
26103In accordance with RM rules, such code statements are allowed only
26104within subprograms whose entire body consists of such statements.  It is
26105not permissible to intermix such statements with other Ada statements.
26106
26107Typically the form using intrinsic procedure calls is more convenient
26108and more flexible.  The code statement form is provided to meet the RM
26109suggestion that such a facility should be made available.  The following
26110is the exact syntax of the call to @code{Asm}. As usual, if named notation
26111is used, the arguments may be given in arbitrary order, following the
26112normal rules for use of positional and named arguments:
26113
26114@example
26115ASM_CALL ::= Asm (
26116                 [Template =>] static_string_EXPRESSION
26117               [,[Outputs  =>] OUTPUT_OPERAND_LIST      ]
26118               [,[Inputs   =>] INPUT_OPERAND_LIST       ]
26119               [,[Clobber  =>] static_string_EXPRESSION ]
26120               [,[Volatile =>] static_boolean_EXPRESSION] )
26121
26122OUTPUT_OPERAND_LIST ::=
26123  [PREFIX.]No_Output_Operands
26124| OUTPUT_OPERAND_ATTRIBUTE
26125| (OUTPUT_OPERAND_ATTRIBUTE @{,OUTPUT_OPERAND_ATTRIBUTE@})
26126
26127OUTPUT_OPERAND_ATTRIBUTE ::=
26128  SUBTYPE_MARK'Asm_Output (static_string_EXPRESSION, NAME)
26129
26130INPUT_OPERAND_LIST ::=
26131  [PREFIX.]No_Input_Operands
26132| INPUT_OPERAND_ATTRIBUTE
26133| (INPUT_OPERAND_ATTRIBUTE @{,INPUT_OPERAND_ATTRIBUTE@})
26134
26135INPUT_OPERAND_ATTRIBUTE ::=
26136  SUBTYPE_MARK'Asm_Input (static_string_EXPRESSION, EXPRESSION)
26137@end example
26138
26139The identifiers @code{No_Input_Operands} and @code{No_Output_Operands}
26140are declared in the package @code{Machine_Code} and must be referenced
26141according to normal visibility rules. In particular if there is no
26142@code{use} clause for this package, then appropriate package name
26143qualification is required.
26144
26145@node GNAT Implementation of Tasking,GNAT Implementation of Shared Passive Packages,Machine Code Insertions,Implementation of Specific Ada Features
26146@anchor{gnat_rm/implementation_of_specific_ada_features gnat-implementation-of-tasking}@anchor{41e}@anchor{gnat_rm/implementation_of_specific_ada_features id3}@anchor{41f}
26147@section GNAT Implementation of Tasking
26148
26149
26150This chapter outlines the basic GNAT approach to tasking (in particular,
26151a multi-layered library for portability) and discusses issues related
26152to compliance with the Real-Time Systems Annex.
26153
26154@menu
26155* Mapping Ada Tasks onto the Underlying Kernel Threads::
26156* Ensuring Compliance with the Real-Time Annex::
26157* Support for Locking Policies::
26158
26159@end menu
26160
26161@node Mapping Ada Tasks onto the Underlying Kernel Threads,Ensuring Compliance with the Real-Time Annex,,GNAT Implementation of Tasking
26162@anchor{gnat_rm/implementation_of_specific_ada_features id4}@anchor{420}@anchor{gnat_rm/implementation_of_specific_ada_features mapping-ada-tasks-onto-the-underlying-kernel-threads}@anchor{421}
26163@subsection Mapping Ada Tasks onto the Underlying Kernel Threads
26164
26165
26166GNAT’s run-time support comprises two layers:
26167
26168
26169@itemize *
26170
26171@item
26172GNARL (GNAT Run-time Layer)
26173
26174@item
26175GNULL (GNAT Low-level Library)
26176@end itemize
26177
26178In GNAT, Ada’s tasking services rely on a platform and OS independent
26179layer known as GNARL.  This code is responsible for implementing the
26180correct semantics of Ada’s task creation, rendezvous, protected
26181operations etc.
26182
26183GNARL decomposes Ada’s tasking semantics into simpler lower level
26184operations such as create a thread, set the priority of a thread,
26185yield, create a lock, lock/unlock, etc.  The spec for these low-level
26186operations constitutes GNULLI, the GNULL Interface.  This interface is
26187directly inspired from the POSIX real-time API.
26188
26189If the underlying executive or OS implements the POSIX standard
26190faithfully, the GNULL Interface maps as is to the services offered by
26191the underlying kernel.  Otherwise, some target dependent glue code maps
26192the services offered by the underlying kernel to the semantics expected
26193by GNARL.
26194
26195Whatever the underlying OS (VxWorks, UNIX, Windows, etc.) the
26196key point is that each Ada task is mapped on a thread in the underlying
26197kernel.  For example, in the case of VxWorks, one Ada task = one VxWorks task.
26198
26199In addition Ada task priorities map onto the underlying thread priorities.
26200Mapping Ada tasks onto the underlying kernel threads has several advantages:
26201
26202
26203@itemize *
26204
26205@item
26206The underlying scheduler is used to schedule the Ada tasks.  This
26207makes Ada tasks as efficient as kernel threads from a scheduling
26208standpoint.
26209
26210@item
26211Interaction with code written in C containing threads is eased
26212since at the lowest level Ada tasks and C threads map onto the same
26213underlying kernel concept.
26214
26215@item
26216When an Ada task is blocked during I/O the remaining Ada tasks are
26217able to proceed.
26218
26219@item
26220On multiprocessor systems Ada tasks can execute in parallel.
26221@end itemize
26222
26223Some threads libraries offer a mechanism to fork a new process, with the
26224child process duplicating the threads from the parent.
26225GNAT does not
26226support this functionality when the parent contains more than one task.
26227
26228@geindex Forking a new process
26229
26230@node Ensuring Compliance with the Real-Time Annex,Support for Locking Policies,Mapping Ada Tasks onto the Underlying Kernel Threads,GNAT Implementation of Tasking
26231@anchor{gnat_rm/implementation_of_specific_ada_features ensuring-compliance-with-the-real-time-annex}@anchor{422}@anchor{gnat_rm/implementation_of_specific_ada_features id5}@anchor{423}
26232@subsection Ensuring Compliance with the Real-Time Annex
26233
26234
26235@geindex Real-Time Systems Annex compliance
26236
26237Although mapping Ada tasks onto
26238the underlying threads has significant advantages, it does create some
26239complications when it comes to respecting the scheduling semantics
26240specified in the real-time annex (Annex D).
26241
26242For instance the Annex D requirement for the @code{FIFO_Within_Priorities}
26243scheduling policy states:
26244
26245@quotation
26246
26247@emph{When the active priority of a ready task that is not running
26248changes, or the setting of its base priority takes effect, the
26249task is removed from the ready queue for its old active priority
26250and is added at the tail of the ready queue for its new active
26251priority, except in the case where the active priority is lowered
26252due to the loss of inherited priority, in which case the task is
26253added at the head of the ready queue for its new active priority.}
26254@end quotation
26255
26256While most kernels do put tasks at the end of the priority queue when
26257a task changes its priority, (which respects the main
26258FIFO_Within_Priorities requirement), almost none keep a thread at the
26259beginning of its priority queue when its priority drops from the loss
26260of inherited priority.
26261
26262As a result most vendors have provided incomplete Annex D implementations.
26263
26264The GNAT run-time, has a nice cooperative solution to this problem
26265which ensures that accurate FIFO_Within_Priorities semantics are
26266respected.
26267
26268The principle is as follows.  When an Ada task T is about to start
26269running, it checks whether some other Ada task R with the same
26270priority as T has been suspended due to the loss of priority
26271inheritance.  If this is the case, T yields and is placed at the end of
26272its priority queue.  When R arrives at the front of the queue it
26273executes.
26274
26275Note that this simple scheme preserves the relative order of the tasks
26276that were ready to execute in the priority queue where R has been
26277placed at the end.
26278
26279@c Support_for_Locking_Policies
26280
26281@node Support for Locking Policies,,Ensuring Compliance with the Real-Time Annex,GNAT Implementation of Tasking
26282@anchor{gnat_rm/implementation_of_specific_ada_features support-for-locking-policies}@anchor{424}
26283@subsection Support for Locking Policies
26284
26285
26286This section specifies which policies specified by pragma Locking_Policy
26287are supported on which platforms.
26288
26289GNAT supports the standard @code{Ceiling_Locking} policy, and the
26290implementation defined @code{Inheritance_Locking} and
26291@code{Concurrent_Readers_Locking} policies.
26292
26293@code{Ceiling_Locking} is supported on all platforms if the operating system
26294supports it. In particular, @code{Ceiling_Locking} is not supported on
26295VxWorks.
26296@code{Inheritance_Locking} is supported on
26297Linux,
26298Darwin (Mac OS X),
26299LynxOS 178,
26300and VxWorks.
26301@code{Concurrent_Readers_Locking} is supported on Linux.
26302
26303Notes about @code{Ceiling_Locking} on Linux:
26304If the process is running as ‘root’, ceiling locking is used.
26305If the capabilities facility is installed
26306(“sudo apt-get –assume-yes install libcap-dev” on Ubuntu,
26307for example),
26308and the program is linked against that library
26309(“-largs -lcap”),
26310and the executable file has the cap_sys_nice capability
26311(“sudo /sbin/setcap cap_sys_nice=ep executable_file_name”),
26312then ceiling locking is used.
26313Otherwise, the @code{Ceiling_Locking} policy is ignored.
26314
26315@node GNAT Implementation of Shared Passive Packages,Code Generation for Array Aggregates,GNAT Implementation of Tasking,Implementation of Specific Ada Features
26316@anchor{gnat_rm/implementation_of_specific_ada_features gnat-implementation-of-shared-passive-packages}@anchor{425}@anchor{gnat_rm/implementation_of_specific_ada_features id6}@anchor{426}
26317@section GNAT Implementation of Shared Passive Packages
26318
26319
26320@geindex Shared passive packages
26321
26322GNAT fully implements the
26323@geindex pragma Shared_Passive
26324pragma
26325@code{Shared_Passive} for
26326the purpose of designating shared passive packages.
26327This allows the use of passive partitions in the
26328context described in the Ada Reference Manual; i.e., for communication
26329between separate partitions of a distributed application using the
26330features in Annex E.
26331
26332@geindex Annex E
26333
26334@geindex Distribution Systems Annex
26335
26336However, the implementation approach used by GNAT provides for more
26337extensive usage as follows:
26338
26339
26340@table @asis
26341
26342@item @emph{Communication between separate programs}
26343
26344This allows separate programs to access the data in passive
26345partitions, using protected objects for synchronization where
26346needed. The only requirement is that the two programs have a
26347common shared file system. It is even possible for programs
26348running on different machines with different architectures
26349(e.g., different endianness) to communicate via the data in
26350a passive partition.
26351
26352@item @emph{Persistence between program runs}
26353
26354The data in a passive package can persist from one run of a
26355program to another, so that a later program sees the final
26356values stored by a previous run of the same program.
26357@end table
26358
26359The implementation approach used is to store the data in files. A
26360separate stream file is created for each object in the package, and
26361an access to an object causes the corresponding file to be read or
26362written.
26363
26364@geindex SHARED_MEMORY_DIRECTORY environment variable
26365
26366The environment variable @code{SHARED_MEMORY_DIRECTORY} should be
26367set to the directory to be used for these files.
26368The files in this directory
26369have names that correspond to their fully qualified names. For
26370example, if we have the package
26371
26372@example
26373package X is
26374  pragma Shared_Passive (X);
26375  Y : Integer;
26376  Z : Float;
26377end X;
26378@end example
26379
26380and the environment variable is set to @code{/stemp/}, then the files created
26381will have the names:
26382
26383@example
26384/stemp/x.y
26385/stemp/x.z
26386@end example
26387
26388These files are created when a value is initially written to the object, and
26389the files are retained until manually deleted. This provides the persistence
26390semantics. If no file exists, it means that no partition has assigned a value
26391to the variable; in this case the initial value declared in the package
26392will be used. This model ensures that there are no issues in synchronizing
26393the elaboration process, since elaboration of passive packages elaborates the
26394initial values, but does not create the files.
26395
26396The files are written using normal @code{Stream_IO} access.
26397If you want to be able
26398to communicate between programs or partitions running on different
26399architectures, then you should use the XDR versions of the stream attribute
26400routines, since these are architecture independent.
26401
26402If active synchronization is required for access to the variables in the
26403shared passive package, then as described in the Ada Reference Manual, the
26404package may contain protected objects used for this purpose. In this case
26405a lock file (whose name is @code{___lock} (three underscores)
26406is created in the shared memory directory.
26407
26408@geindex ___lock file (for shared passive packages)
26409
26410This is used to provide the required locking
26411semantics for proper protected object synchronization.
26412
26413@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
26414@anchor{gnat_rm/implementation_of_specific_ada_features code-generation-for-array-aggregates}@anchor{427}@anchor{gnat_rm/implementation_of_specific_ada_features id7}@anchor{428}
26415@section Code Generation for Array Aggregates
26416
26417
26418Aggregates have a rich syntax and allow the user to specify the values of
26419complex data structures by means of a single construct.  As a result, the
26420code generated for aggregates can be quite complex and involve loops, case
26421statements and multiple assignments.  In the simplest cases, however, the
26422compiler will recognize aggregates whose components and constraints are
26423fully static, and in those cases the compiler will generate little or no
26424executable code.  The following is an outline of the code that GNAT generates
26425for various aggregate constructs.  For further details, you will find it
26426useful to examine the output produced by the -gnatG flag to see the expanded
26427source that is input to the code generator.  You may also want to examine
26428the assembly code generated at various levels of optimization.
26429
26430The code generated for aggregates depends on the context, the component values,
26431and the type.  In the context of an object declaration the code generated is
26432generally simpler than in the case of an assignment.  As a general rule, static
26433component values and static subtypes also lead to simpler code.
26434
26435@menu
26436* Static constant aggregates with static bounds::
26437* Constant aggregates with unconstrained nominal types::
26438* Aggregates with static bounds::
26439* Aggregates with nonstatic bounds::
26440* Aggregates in assignment statements::
26441
26442@end menu
26443
26444@node Static constant aggregates with static bounds,Constant aggregates with unconstrained nominal types,,Code Generation for Array Aggregates
26445@anchor{gnat_rm/implementation_of_specific_ada_features id8}@anchor{429}@anchor{gnat_rm/implementation_of_specific_ada_features static-constant-aggregates-with-static-bounds}@anchor{42a}
26446@subsection Static constant aggregates with static bounds
26447
26448
26449For the declarations:
26450
26451@example
26452type One_Dim is array (1..10) of integer;
26453ar0 : constant One_Dim := (1, 2, 3, 4, 5, 6, 7, 8, 9, 0);
26454@end example
26455
26456GNAT generates no executable code: the constant ar0 is placed in static memory.
26457The same is true for constant aggregates with named associations:
26458
26459@example
26460Cr1 : constant One_Dim := (4 => 16, 2 => 4, 3 => 9, 1 => 1, 5 .. 10 => 0);
26461Cr3 : constant One_Dim := (others => 7777);
26462@end example
26463
26464The same is true for multidimensional constant arrays such as:
26465
26466@example
26467type two_dim is array (1..3, 1..3) of integer;
26468Unit : constant two_dim := ( (1,0,0), (0,1,0), (0,0,1));
26469@end example
26470
26471The same is true for arrays of one-dimensional arrays: the following are
26472static:
26473
26474@example
26475type ar1b  is array (1..3) of boolean;
26476type ar_ar is array (1..3) of ar1b;
26477None  : constant ar1b := (others => false);     --  fully static
26478None2 : constant ar_ar := (1..3 => None);       --  fully static
26479@end example
26480
26481However, for multidimensional aggregates with named associations, GNAT will
26482generate assignments and loops, even if all associations are static.  The
26483following two declarations generate a loop for the first dimension, and
26484individual component assignments for the second dimension:
26485
26486@example
26487Zero1: constant two_dim := (1..3 => (1..3 => 0));
26488Zero2: constant two_dim := (others => (others => 0));
26489@end example
26490
26491@node Constant aggregates with unconstrained nominal types,Aggregates with static bounds,Static constant aggregates with static bounds,Code Generation for Array Aggregates
26492@anchor{gnat_rm/implementation_of_specific_ada_features constant-aggregates-with-unconstrained-nominal-types}@anchor{42b}@anchor{gnat_rm/implementation_of_specific_ada_features id9}@anchor{42c}
26493@subsection Constant aggregates with unconstrained nominal types
26494
26495
26496In such cases the aggregate itself establishes the subtype, so that
26497associations with @code{others} cannot be used.  GNAT determines the
26498bounds for the actual subtype of the aggregate, and allocates the
26499aggregate statically as well.  No code is generated for the following:
26500
26501@example
26502type One_Unc is array (natural range <>) of integer;
26503Cr_Unc : constant One_Unc := (12,24,36);
26504@end example
26505
26506@node Aggregates with static bounds,Aggregates with nonstatic bounds,Constant aggregates with unconstrained nominal types,Code Generation for Array Aggregates
26507@anchor{gnat_rm/implementation_of_specific_ada_features aggregates-with-static-bounds}@anchor{42d}@anchor{gnat_rm/implementation_of_specific_ada_features id10}@anchor{42e}
26508@subsection Aggregates with static bounds
26509
26510
26511In all previous examples the aggregate was the initial (and immutable) value
26512of a constant.  If the aggregate initializes a variable, then code is generated
26513for it as a combination of individual assignments and loops over the target
26514object.  The declarations
26515
26516@example
26517Cr_Var1 : One_Dim := (2, 5, 7, 11, 0, 0, 0, 0, 0, 0);
26518Cr_Var2 : One_Dim := (others > -1);
26519@end example
26520
26521generate the equivalent of
26522
26523@example
26524Cr_Var1 (1) := 2;
26525Cr_Var1 (2) := 3;
26526Cr_Var1 (3) := 5;
26527Cr_Var1 (4) := 11;
26528
26529for I in Cr_Var2'range loop
26530   Cr_Var2 (I) := -1;
26531end loop;
26532@end example
26533
26534@node Aggregates with nonstatic bounds,Aggregates in assignment statements,Aggregates with static bounds,Code Generation for Array Aggregates
26535@anchor{gnat_rm/implementation_of_specific_ada_features aggregates-with-nonstatic-bounds}@anchor{42f}@anchor{gnat_rm/implementation_of_specific_ada_features id11}@anchor{430}
26536@subsection Aggregates with nonstatic bounds
26537
26538
26539If the bounds of the aggregate are not statically compatible with the bounds
26540of the nominal subtype  of the target, then constraint checks have to be
26541generated on the bounds.  For a multidimensional array, constraint checks may
26542have to be applied to sub-arrays individually, if they do not have statically
26543compatible subtypes.
26544
26545@node Aggregates in assignment statements,,Aggregates with nonstatic bounds,Code Generation for Array Aggregates
26546@anchor{gnat_rm/implementation_of_specific_ada_features aggregates-in-assignment-statements}@anchor{431}@anchor{gnat_rm/implementation_of_specific_ada_features id12}@anchor{432}
26547@subsection Aggregates in assignment statements
26548
26549
26550In general, aggregate assignment requires the construction of a temporary,
26551and a copy from the temporary to the target of the assignment.  This is because
26552it is not always possible to convert the assignment into a series of individual
26553component assignments.  For example, consider the simple case:
26554
26555@example
26556A := (A(2), A(1));
26557@end example
26558
26559This cannot be converted into:
26560
26561@example
26562A(1) := A(2);
26563A(2) := A(1);
26564@end example
26565
26566So the aggregate has to be built first in a separate location, and then
26567copied into the target.  GNAT recognizes simple cases where this intermediate
26568step is not required, and the assignments can be performed in place, directly
26569into the target.  The following sufficient criteria are applied:
26570
26571
26572@itemize *
26573
26574@item
26575The bounds of the aggregate are static, and the associations are static.
26576
26577@item
26578The components of the aggregate are static constants, names of
26579simple variables that are not renamings, or expressions not involving
26580indexed components whose operands obey these rules.
26581@end itemize
26582
26583If any of these conditions are violated, the aggregate will be built in
26584a temporary (created either by the front-end or the code generator) and then
26585that temporary will be copied onto the target.
26586
26587@node The Size of Discriminated Records with Default Discriminants,Image Values For Nonscalar Types,Code Generation for Array Aggregates,Implementation of Specific Ada Features
26588@anchor{gnat_rm/implementation_of_specific_ada_features id13}@anchor{433}@anchor{gnat_rm/implementation_of_specific_ada_features the-size-of-discriminated-records-with-default-discriminants}@anchor{434}
26589@section The Size of Discriminated Records with Default Discriminants
26590
26591
26592If a discriminated type @code{T} has discriminants with default values, it is
26593possible to declare an object of this type without providing an explicit
26594constraint:
26595
26596@example
26597type Size is range 1..100;
26598
26599type Rec (D : Size := 15) is record
26600   Name : String (1..D);
26601end T;
26602
26603Word : Rec;
26604@end example
26605
26606Such an object is said to be @emph{unconstrained}.
26607The discriminant of the object
26608can be modified by a full assignment to the object, as long as it preserves the
26609relation between the value of the discriminant, and the value of the components
26610that depend on it:
26611
26612@example
26613Word := (3, "yes");
26614
26615Word := (5, "maybe");
26616
26617Word := (5, "no"); -- raises Constraint_Error
26618@end example
26619
26620In order to support this behavior efficiently, an unconstrained object is
26621given the maximum size that any value of the type requires. In the case
26622above, @code{Word} has storage for the discriminant and for
26623a @code{String} of length 100.
26624It is important to note that unconstrained objects do not require dynamic
26625allocation. It would be an improper implementation to place on the heap those
26626components whose size depends on discriminants. (This improper implementation
26627was used by some Ada83 compilers, where the @code{Name} component above
26628would have
26629been stored as a pointer to a dynamic string). Following the principle that
26630dynamic storage management should never be introduced implicitly,
26631an Ada compiler should reserve the full size for an unconstrained declared
26632object, and place it on the stack.
26633
26634This maximum size approach
26635has been a source of surprise to some users, who expect the default
26636values of the discriminants to determine the size reserved for an
26637unconstrained object: “If the default is 15, why should the object occupy
26638a larger size?”
26639The answer, of course, is that the discriminant may be later modified,
26640and its full range of values must be taken into account. This is why the
26641declaration:
26642
26643@example
26644type Rec (D : Positive := 15) is record
26645   Name : String (1..D);
26646end record;
26647
26648Too_Large : Rec;
26649@end example
26650
26651is flagged by the compiler with a warning:
26652an attempt to create @code{Too_Large} will raise @code{Storage_Error},
26653because the required size includes @code{Positive'Last}
26654bytes. As the first example indicates, the proper approach is to declare an
26655index type of ‘reasonable’ range so that unconstrained objects are not too
26656large.
26657
26658One final wrinkle: if the object is declared to be @code{aliased}, or if it is
26659created in the heap by means of an allocator, then it is @emph{not}
26660unconstrained:
26661it is constrained by the default values of the discriminants, and those values
26662cannot be modified by full assignment. This is because in the presence of
26663aliasing all views of the object (which may be manipulated by different tasks,
26664say) must be consistent, so it is imperative that the object, once created,
26665remain invariant.
26666
26667@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
26668@anchor{gnat_rm/implementation_of_specific_ada_features id14}@anchor{435}@anchor{gnat_rm/implementation_of_specific_ada_features image-values-for-nonscalar-types}@anchor{436}
26669@section Image Values For Nonscalar Types
26670
26671
26672Ada 2022 defines the Image, Wide_Image, and Wide_Wide image attributes
26673for nonscalar types; earlier Ada versions defined these attributes only
26674for scalar types. Ada RM 4.10 provides some general guidance regarding
26675the default implementation of these attributes and the GNAT compiler
26676follows that guidance. However, beyond that the precise details of the
26677image text generated in these cases are deliberately not documented and are
26678subject to change. In particular, users should not rely on formatting details
26679(such as spaces or line breaking), record field order, image values for access
26680types, image values for types that have ancestor or subcomponent types
26681declared in non-Ada2022 code, image values for predefined types, or the
26682compiler’s choices regarding the implementation permissions described in
26683Ada RM 4.10. This list is not intended to be exhaustive. If more precise
26684control of image text is required for some type T, then T’Put_Image should be
26685explicitly specified.
26686
26687@node Strict Conformance to the Ada Reference Manual,,Image Values For Nonscalar Types,Implementation of Specific Ada Features
26688@anchor{gnat_rm/implementation_of_specific_ada_features id15}@anchor{437}@anchor{gnat_rm/implementation_of_specific_ada_features strict-conformance-to-the-ada-reference-manual}@anchor{438}
26689@section Strict Conformance to the Ada Reference Manual
26690
26691
26692The dynamic semantics defined by the Ada Reference Manual impose a set of
26693run-time checks to be generated. By default, the GNAT compiler will insert many
26694run-time checks into the compiled code, including most of those required by the
26695Ada Reference Manual. However, there are two checks that are not enabled in
26696the default mode for efficiency reasons: checks for access before elaboration
26697on subprogram calls, and stack overflow checking (most operating systems do not
26698perform this check by default).
26699
26700Strict conformance to the Ada Reference Manual can be achieved by adding two
26701compiler options for dynamic checks for access-before-elaboration on subprogram
26702calls and generic instantiations (@emph{-gnatE}), and stack overflow checking
26703(@emph{-fstack-check}).
26704
26705Note that the result of a floating point arithmetic operation in overflow and
26706invalid situations, when the @code{Machine_Overflows} attribute of the result
26707type is @code{False}, is to generate IEEE NaN and infinite values. This is the
26708case for machines compliant with the IEEE floating-point standard, but on
26709machines that are not fully compliant with this standard, such as Alpha, the
26710@emph{-mieee} compiler flag must be used for achieving IEEE confirming
26711behavior (although at the cost of a significant performance penalty), so
26712infinite and NaN values are properly generated.
26713
26714@node Implementation of Ada 2012 Features,Security Hardening Features,Implementation of Specific Ada Features,Top
26715@anchor{gnat_rm/implementation_of_ada_2012_features doc}@anchor{439}@anchor{gnat_rm/implementation_of_ada_2012_features id1}@anchor{43a}@anchor{gnat_rm/implementation_of_ada_2012_features implementation-of-ada-2012-features}@anchor{14}
26716@chapter Implementation of Ada 2012 Features
26717
26718
26719@geindex Ada 2012 implementation status
26720
26721@geindex -gnat12 option (gcc)
26722
26723@geindex pragma Ada_2012
26724
26725@geindex configuration pragma Ada_2012
26726
26727@geindex Ada_2012 configuration pragma
26728
26729This chapter contains a complete list of Ada 2012 features that have been
26730implemented.
26731Generally, these features are only
26732available if the @emph{-gnat12} (Ada 2012 features enabled) option is set,
26733which is the default behavior,
26734or if the configuration pragma @code{Ada_2012} is used.
26735
26736However, new pragmas, attributes, and restrictions are
26737unconditionally available, since the Ada 95 standard allows the addition of
26738new pragmas, attributes, and restrictions (there are exceptions, which are
26739documented in the individual descriptions), and also certain packages
26740were made available in earlier versions of Ada.
26741
26742An ISO date (YYYY-MM-DD) appears in parentheses on the description line.
26743This date shows the implementation date of the feature. Any wavefront
26744subsequent to this date will contain the indicated feature, as will any
26745subsequent releases. A date of 0000-00-00 means that GNAT has always
26746implemented the feature, or implemented it as soon as it appeared as a
26747binding interpretation.
26748
26749Each feature corresponds to an Ada Issue (‘AI’) approved by the Ada
26750standardization group (ISO/IEC JTC1/SC22/WG9) for inclusion in Ada 2012.
26751The features are ordered based on the relevant sections of the Ada
26752Reference Manual (“RM”).  When a given AI relates to multiple points
26753in the RM, the earliest is used.
26754
26755A complete description of the AIs may be found in
26756@indicateurl{http://www.ada-auth.org/ai05-summary.html}.
26757
26758@geindex AI-0176 (Ada 2012 feature)
26759
26760
26761@itemize *
26762
26763@item
26764@emph{AI-0176 Quantified expressions (2010-09-29)}
26765
26766Both universally and existentially quantified expressions are implemented.
26767They use the new syntax for iterators proposed in AI05-139-2, as well as
26768the standard Ada loop syntax.
26769
26770RM References:  1.01.04 (12)   2.09 (2/2)   4.04 (7)   4.05.09 (0)
26771@end itemize
26772
26773@geindex AI-0079 (Ada 2012 feature)
26774
26775
26776@itemize *
26777
26778@item
26779@emph{AI-0079 Allow other_format characters in source (2010-07-10)}
26780
26781Wide characters in the unicode category @emph{other_format} are now allowed in
26782source programs between tokens, but not within a token such as an identifier.
26783
26784RM References:  2.01 (4/2)   2.02 (7)
26785@end itemize
26786
26787@geindex AI-0091 (Ada 2012 feature)
26788
26789
26790@itemize *
26791
26792@item
26793@emph{AI-0091 Do not allow other_format in identifiers (0000-00-00)}
26794
26795Wide characters in the unicode category @emph{other_format} are not permitted
26796within  an identifier, since this can be a security problem. The error
26797message for this case has been improved to be more specific, but GNAT has
26798never allowed such characters to appear in identifiers.
26799
26800RM 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)
26801@end itemize
26802
26803@geindex AI-0100 (Ada 2012 feature)
26804
26805
26806@itemize *
26807
26808@item
26809@emph{AI-0100 Placement of pragmas  (2010-07-01)}
26810
26811This AI is an earlier version of AI-163. It simplifies the rules
26812for legal placement of pragmas. In the case of lists that allow pragmas, if
26813the list may have no elements, then the list may consist solely of pragmas.
26814
26815RM References:  2.08 (7)
26816@end itemize
26817
26818@geindex AI-0163 (Ada 2012 feature)
26819
26820
26821@itemize *
26822
26823@item
26824@emph{AI-0163 Pragmas in place of null (2010-07-01)}
26825
26826A statement sequence may be composed entirely of pragmas. It is no longer
26827necessary to add a dummy @code{null} statement to make the sequence legal.
26828
26829RM References:  2.08 (7)   2.08 (16)
26830@end itemize
26831
26832@geindex AI-0080 (Ada 2012 feature)
26833
26834
26835@itemize *
26836
26837@item
26838@emph{AI-0080 ‘View of’ not needed if clear from context (0000-00-00)}
26839
26840This is an editorial change only, described as non-testable in the AI.
26841
26842RM References:  3.01 (7)
26843@end itemize
26844
26845@geindex AI-0183 (Ada 2012 feature)
26846
26847
26848@itemize *
26849
26850@item
26851@emph{AI-0183 Aspect specifications (2010-08-16)}
26852
26853Aspect specifications have been fully implemented except for pre and post-
26854conditions, and type invariants, which have their own separate AI’s. All
26855forms of declarations listed in the AI are supported. The following is a
26856list of the aspects supported (with GNAT implementation aspects marked)
26857@end itemize
26858
26859
26860@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxx}
26861@headitem
26862
26863Supported Aspect
26864
26865@tab
26866
26867Source
26868
26869@item
26870
26871@code{Ada_2005}
26872
26873@tab
26874
26875– GNAT
26876
26877@item
26878
26879@code{Ada_2012}
26880
26881@tab
26882
26883– GNAT
26884
26885@item
26886
26887@code{Address}
26888
26889@tab
26890
26891@item
26892
26893@code{Alignment}
26894
26895@tab
26896
26897@item
26898
26899@code{Atomic}
26900
26901@tab
26902
26903@item
26904
26905@code{Atomic_Components}
26906
26907@tab
26908
26909@item
26910
26911@code{Bit_Order}
26912
26913@tab
26914
26915@item
26916
26917@code{Component_Size}
26918
26919@tab
26920
26921@item
26922
26923@code{Contract_Cases}
26924
26925@tab
26926
26927– GNAT
26928
26929@item
26930
26931@code{Discard_Names}
26932
26933@tab
26934
26935@item
26936
26937@code{External_Tag}
26938
26939@tab
26940
26941@item
26942
26943@code{Favor_Top_Level}
26944
26945@tab
26946
26947– GNAT
26948
26949@item
26950
26951@code{Inline}
26952
26953@tab
26954
26955@item
26956
26957@code{Inline_Always}
26958
26959@tab
26960
26961– GNAT
26962
26963@item
26964
26965@code{Invariant}
26966
26967@tab
26968
26969– GNAT
26970
26971@item
26972
26973@code{Machine_Radix}
26974
26975@tab
26976
26977@item
26978
26979@code{No_Return}
26980
26981@tab
26982
26983@item
26984
26985@code{Object_Size}
26986
26987@tab
26988
26989– GNAT
26990
26991@item
26992
26993@code{Pack}
26994
26995@tab
26996
26997@item
26998
26999@code{Persistent_BSS}
27000
27001@tab
27002
27003– GNAT
27004
27005@item
27006
27007@code{Post}
27008
27009@tab
27010
27011@item
27012
27013@code{Pre}
27014
27015@tab
27016
27017@item
27018
27019@code{Predicate}
27020
27021@tab
27022
27023@item
27024
27025@code{Preelaborable_Initialization}
27026
27027@tab
27028
27029@item
27030
27031@code{Pure_Function}
27032
27033@tab
27034
27035– GNAT
27036
27037@item
27038
27039@code{Remote_Access_Type}
27040
27041@tab
27042
27043– GNAT
27044
27045@item
27046
27047@code{Shared}
27048
27049@tab
27050
27051– GNAT
27052
27053@item
27054
27055@code{Size}
27056
27057@tab
27058
27059@item
27060
27061@code{Storage_Pool}
27062
27063@tab
27064
27065@item
27066
27067@code{Storage_Size}
27068
27069@tab
27070
27071@item
27072
27073@code{Stream_Size}
27074
27075@tab
27076
27077@item
27078
27079@code{Suppress}
27080
27081@tab
27082
27083@item
27084
27085@code{Suppress_Debug_Info}
27086
27087@tab
27088
27089– GNAT
27090
27091@item
27092
27093@code{Test_Case}
27094
27095@tab
27096
27097– GNAT
27098
27099@item
27100
27101@code{Thread_Local_Storage}
27102
27103@tab
27104
27105– GNAT
27106
27107@item
27108
27109@code{Type_Invariant}
27110
27111@tab
27112
27113@item
27114
27115@code{Unchecked_Union}
27116
27117@tab
27118
27119@item
27120
27121@code{Universal_Aliasing}
27122
27123@tab
27124
27125– GNAT
27126
27127@item
27128
27129@code{Unmodified}
27130
27131@tab
27132
27133– GNAT
27134
27135@item
27136
27137@code{Unreferenced}
27138
27139@tab
27140
27141– GNAT
27142
27143@item
27144
27145@code{Unreferenced_Objects}
27146
27147@tab
27148
27149– GNAT
27150
27151@item
27152
27153@code{Unsuppress}
27154
27155@tab
27156
27157@item
27158
27159@code{Value_Size}
27160
27161@tab
27162
27163– GNAT
27164
27165@item
27166
27167@code{Volatile}
27168
27169@tab
27170
27171@item
27172
27173@code{Volatile_Components}
27174
27175@tab
27176
27177@item
27178
27179@code{Warnings}
27180
27181@tab
27182
27183– GNAT
27184
27185@end multitable
27186
27187
27188@quotation
27189
27190Note that for aspects with an expression, e.g. @code{Size}, the expression is
27191treated like a default expression (visibility is analyzed at the point of
27192occurrence of the aspect, but evaluation of the expression occurs at the
27193freeze point of the entity involved).
27194
27195RM References:  3.02.01 (3)   3.02.02 (2)   3.03.01 (2/2)   3.08 (6)
271963.09.03 (1.1/2)   6.01 (2/2)   6.07 (2/2)   9.05.02 (2/2)   7.01 (3)   7.03
27197(2)   7.03 (3)   9.01 (2/2)   9.01 (3/2)   9.04 (2/2)   9.04 (3/2)
271989.05.02 (2/2)   11.01 (2)   12.01 (3)   12.03 (2/2)   12.04 (2/2)   12.05 (2)
2719912.06 (2.1/2)   12.06 (2.2/2)   12.07 (2)   13.01 (0.1/2)   13.03 (5/1)
2720013.03.01 (0)
27201@end quotation
27202
27203@geindex AI-0128 (Ada 2012 feature)
27204
27205
27206@itemize *
27207
27208@item
27209@emph{AI-0128 Inequality is a primitive operation (0000-00-00)}
27210
27211If an equality operator (“=”) is declared for a type, then the implicitly
27212declared inequality operator (“/=”) is a primitive operation of the type.
27213This is the only reasonable interpretation, and is the one always implemented
27214by GNAT, but the RM was not entirely clear in making this point.
27215
27216RM References:  3.02.03 (6)   6.06 (6)
27217@end itemize
27218
27219@geindex AI-0003 (Ada 2012 feature)
27220
27221
27222@itemize *
27223
27224@item
27225@emph{AI-0003 Qualified expressions as names (2010-07-11)}
27226
27227In Ada 2012, a qualified expression is considered to be syntactically a name,
27228meaning that constructs such as @code{A'(F(X)).B} are now legal. This is
27229useful in disambiguating some cases of overloading.
27230
27231RM References:  3.03 (11)   3.03 (21)   4.01 (2)   4.04 (7)   4.07 (3)
272325.04 (7)
27233@end itemize
27234
27235@geindex AI-0120 (Ada 2012 feature)
27236
27237
27238@itemize *
27239
27240@item
27241@emph{AI-0120 Constant instance of protected object (0000-00-00)}
27242
27243This is an RM editorial change only. The section that lists objects that are
27244constant failed to include the current instance of a protected object
27245within a protected function. This has always been treated as a constant
27246in GNAT.
27247
27248RM References:  3.03 (21)
27249@end itemize
27250
27251@geindex AI-0008 (Ada 2012 feature)
27252
27253
27254@itemize *
27255
27256@item
27257@emph{AI-0008 General access to constrained objects (0000-00-00)}
27258
27259The wording in the RM implied that if you have a general access to a
27260constrained object, it could be used to modify the discriminants. This was
27261obviously not intended. @code{Constraint_Error} should be raised, and GNAT
27262has always done so in this situation.
27263
27264RM References:  3.03 (23)   3.10.02 (26/2)   4.01 (9)   6.04.01 (17)   8.05.01 (5/2)
27265@end itemize
27266
27267@geindex AI-0093 (Ada 2012 feature)
27268
27269
27270@itemize *
27271
27272@item
27273@emph{AI-0093 Additional rules use immutably limited (0000-00-00)}
27274
27275This is an editorial change only, to make more widespread use of the Ada 2012
27276‘immutably limited’.
27277
27278RM References:  3.03 (23.4/3)
27279@end itemize
27280
27281@geindex AI-0096 (Ada 2012 feature)
27282
27283
27284@itemize *
27285
27286@item
27287@emph{AI-0096 Deriving from formal private types (2010-07-20)}
27288
27289In general it is illegal for a type derived from a formal limited type to be
27290nonlimited.  This AI makes an exception to this rule: derivation is legal
27291if it appears in the private part of the generic, and the formal type is not
27292tagged. If the type is tagged, the legality check must be applied to the
27293private part of the package.
27294
27295RM References:  3.04 (5.1/2)   6.02 (7)
27296@end itemize
27297
27298@geindex AI-0181 (Ada 2012 feature)
27299
27300
27301@itemize *
27302
27303@item
27304@emph{AI-0181 Soft hyphen is a non-graphic character (2010-07-23)}
27305
27306From Ada 2005 on, soft hyphen is considered a non-graphic character, which
27307means that it has a special name (@code{SOFT_HYPHEN}) in conjunction with the
27308@code{Image} and @code{Value} attributes for the character types. Strictly
27309speaking this is an inconsistency with Ada 95, but in practice the use of
27310these attributes is so obscure that it will not cause problems.
27311
27312RM References:  3.05.02 (2/2)   A.01 (35/2)   A.03.03 (21)
27313@end itemize
27314
27315@geindex AI-0182 (Ada 2012 feature)
27316
27317
27318@itemize *
27319
27320@item
27321@emph{AI-0182 Additional forms for} @code{Character'Value} @emph{(0000-00-00)}
27322
27323This AI allows @code{Character'Value} to accept the string @code{'?'} where
27324@code{?} is any character including non-graphic control characters. GNAT has
27325always accepted such strings. It also allows strings such as
27326@code{HEX_00000041} to be accepted, but GNAT does not take advantage of this
27327permission and raises @code{Constraint_Error}, as is certainly still
27328permitted.
27329
27330RM References:  3.05 (56/2)
27331@end itemize
27332
27333@geindex AI-0214 (Ada 2012 feature)
27334
27335
27336@itemize *
27337
27338@item
27339@emph{AI-0214 Defaulted discriminants for limited tagged (2010-10-01)}
27340
27341Ada 2012 relaxes the restriction that forbids discriminants of tagged types
27342to have default expressions by allowing them when the type is limited. It
27343is often useful to define a default value for a discriminant even though
27344it can’t be changed by assignment.
27345
27346RM References:  3.07 (9.1/2)   3.07.02 (3)
27347@end itemize
27348
27349@geindex AI-0102 (Ada 2012 feature)
27350
27351
27352@itemize *
27353
27354@item
27355@emph{AI-0102 Some implicit conversions are illegal (0000-00-00)}
27356
27357It is illegal to assign an anonymous access constant to an anonymous access
27358variable. The RM did not have a clear rule to prevent this, but GNAT has
27359always generated an error for this usage.
27360
27361RM References:  3.07 (16)   3.07.01 (9)   6.04.01 (6)   8.06 (27/2)
27362@end itemize
27363
27364@geindex AI-0158 (Ada 2012 feature)
27365
27366
27367@itemize *
27368
27369@item
27370@emph{AI-0158 Generalizing membership tests (2010-09-16)}
27371
27372This AI extends the syntax of membership tests to simplify complex conditions
27373that can be expressed as membership in a subset of values of any type. It
27374introduces syntax for a list of expressions that may be used in loop contexts
27375as well.
27376
27377RM References:  3.08.01 (5)   4.04 (3)   4.05.02 (3)   4.05.02 (5)   4.05.02 (27)
27378@end itemize
27379
27380@geindex AI-0173 (Ada 2012 feature)
27381
27382
27383@itemize *
27384
27385@item
27386@emph{AI-0173 Testing if tags represent abstract types (2010-07-03)}
27387
27388The function @code{Ada.Tags.Type_Is_Abstract} returns @code{True} if invoked
27389with the tag of an abstract type, and @code{False} otherwise.
27390
27391RM References:  3.09 (7.4/2)   3.09 (12.4/2)
27392@end itemize
27393
27394@geindex AI-0076 (Ada 2012 feature)
27395
27396
27397@itemize *
27398
27399@item
27400@emph{AI-0076 function with controlling result (0000-00-00)}
27401
27402This is an editorial change only. The RM defines calls with controlling
27403results, but uses the term ‘function with controlling result’ without an
27404explicit definition.
27405
27406RM References:  3.09.02 (2/2)
27407@end itemize
27408
27409@geindex AI-0126 (Ada 2012 feature)
27410
27411
27412@itemize *
27413
27414@item
27415@emph{AI-0126 Dispatching with no declared operation (0000-00-00)}
27416
27417This AI clarifies dispatching rules, and simply confirms that dispatching
27418executes the operation of the parent type when there is no explicitly or
27419implicitly declared operation for the descendant type. This has always been
27420the case in all versions of GNAT.
27421
27422RM References:  3.09.02 (20/2)   3.09.02 (20.1/2)   3.09.02 (20.2/2)
27423@end itemize
27424
27425@geindex AI-0097 (Ada 2012 feature)
27426
27427
27428@itemize *
27429
27430@item
27431@emph{AI-0097 Treatment of abstract null extension (2010-07-19)}
27432
27433The RM as written implied that in some cases it was possible to create an
27434object of an abstract type, by having an abstract extension inherit a non-
27435abstract constructor from its parent type. This mistake has been corrected
27436in GNAT and in the RM, and this construct is now illegal.
27437
27438RM References:  3.09.03 (4/2)
27439@end itemize
27440
27441@geindex AI-0203 (Ada 2012 feature)
27442
27443
27444@itemize *
27445
27446@item
27447@emph{AI-0203 Extended return cannot be abstract (0000-00-00)}
27448
27449A return_subtype_indication cannot denote an abstract subtype. GNAT has never
27450permitted such usage.
27451
27452RM References:  3.09.03 (8/3)
27453@end itemize
27454
27455@geindex AI-0198 (Ada 2012 feature)
27456
27457
27458@itemize *
27459
27460@item
27461@emph{AI-0198 Inheriting abstract operators  (0000-00-00)}
27462
27463This AI resolves a conflict between two rules involving inherited abstract
27464operations and predefined operators. If a derived numeric type inherits
27465an abstract operator, it overrides the predefined one. This interpretation
27466was always the one implemented in GNAT.
27467
27468RM References:  3.09.03 (4/3)
27469@end itemize
27470
27471@geindex AI-0073 (Ada 2012 feature)
27472
27473
27474@itemize *
27475
27476@item
27477@emph{AI-0073 Functions returning abstract types (2010-07-10)}
27478
27479This AI covers a number of issues regarding returning abstract types. In
27480particular generic functions cannot have abstract result types or access
27481result types designated an abstract type. There are some other cases which
27482are detailed in the AI. Note that this binding interpretation has not been
27483retrofitted to operate before Ada 2012 mode, since it caused a significant
27484number of regressions.
27485
27486RM References:  3.09.03 (8)   3.09.03 (10)   6.05 (8/2)
27487@end itemize
27488
27489@geindex AI-0070 (Ada 2012 feature)
27490
27491
27492@itemize *
27493
27494@item
27495@emph{AI-0070 Elaboration of interface types (0000-00-00)}
27496
27497This is an editorial change only, there are no testable consequences short of
27498checking for the absence of generated code for an interface declaration.
27499
27500RM References:  3.09.04 (18/2)
27501@end itemize
27502
27503@geindex AI-0208 (Ada 2012 feature)
27504
27505
27506@itemize *
27507
27508@item
27509@emph{AI-0208 Characteristics of incomplete views (0000-00-00)}
27510
27511The wording in the Ada 2005 RM concerning characteristics of incomplete views
27512was incorrect and implied that some programs intended to be legal were now
27513illegal. GNAT had never considered such programs illegal, so it has always
27514implemented the intent of this AI.
27515
27516RM References:  3.10.01 (2.4/2)   3.10.01 (2.6/2)
27517@end itemize
27518
27519@geindex AI-0162 (Ada 2012 feature)
27520
27521
27522@itemize *
27523
27524@item
27525@emph{AI-0162 Incomplete type completed by partial view (2010-09-15)}
27526
27527Incomplete types are made more useful by allowing them to be completed by
27528private types and private extensions.
27529
27530RM References:  3.10.01 (2.5/2)   3.10.01 (2.6/2)   3.10.01 (3)   3.10.01 (4/2)
27531@end itemize
27532
27533@geindex AI-0098 (Ada 2012 feature)
27534
27535
27536@itemize *
27537
27538@item
27539@emph{AI-0098 Anonymous subprogram access restrictions (0000-00-00)}
27540
27541An unintentional omission in the RM implied some inconsistent restrictions on
27542the use of anonymous access to subprogram values. These restrictions were not
27543intentional, and have never been enforced by GNAT.
27544
27545RM References:  3.10.01 (6)   3.10.01 (9.2/2)
27546@end itemize
27547
27548@geindex AI-0199 (Ada 2012 feature)
27549
27550
27551@itemize *
27552
27553@item
27554@emph{AI-0199 Aggregate with anonymous access components (2010-07-14)}
27555
27556A choice list in a record aggregate can include several components of
27557(distinct) anonymous access types as long as they have matching designated
27558subtypes.
27559
27560RM References:  4.03.01 (16)
27561@end itemize
27562
27563@geindex AI-0220 (Ada 2012 feature)
27564
27565
27566@itemize *
27567
27568@item
27569@emph{AI-0220 Needed components for aggregates (0000-00-00)}
27570
27571This AI addresses a wording problem in the RM that appears to permit some
27572complex cases of aggregates with nonstatic discriminants. GNAT has always
27573implemented the intended semantics.
27574
27575RM References:  4.03.01 (17)
27576@end itemize
27577
27578@geindex AI-0147 (Ada 2012 feature)
27579
27580
27581@itemize *
27582
27583@item
27584@emph{AI-0147 Conditional expressions (2009-03-29)}
27585
27586Conditional expressions are permitted. The form of such an expression is:
27587
27588@example
27589(if expr then expr @{elsif expr then expr@} [else expr])
27590@end example
27591
27592The parentheses can be omitted in contexts where parentheses are present
27593anyway, such as subprogram arguments and pragma arguments. If the @strong{else}
27594clause is omitted, @strong{else} @emph{True} is assumed;
27595thus @code{(if A then B)} is a way to conveniently represent
27596@emph{(A implies B)} in standard logic.
27597
27598RM References:  4.03.03 (15)   4.04 (1)   4.04 (7)   4.05.07 (0)   4.07 (2)
275994.07 (3)   4.09 (12)   4.09 (33)   5.03 (3)   5.03 (4)   7.05 (2.1/2)
27600@end itemize
27601
27602@geindex AI-0037 (Ada 2012 feature)
27603
27604
27605@itemize *
27606
27607@item
27608@emph{AI-0037 Out-of-range box associations in aggregate (0000-00-00)}
27609
27610This AI confirms that an association of the form @code{Indx => <>} in an
27611array aggregate must raise @code{Constraint_Error} if @code{Indx}
27612is out of range. The RM specified a range check on other associations, but
27613not when the value of the association was defaulted. GNAT has always inserted
27614a constraint check on the index value.
27615
27616RM References:  4.03.03 (29)
27617@end itemize
27618
27619@geindex AI-0123 (Ada 2012 feature)
27620
27621
27622@itemize *
27623
27624@item
27625@emph{AI-0123 Composability of equality (2010-04-13)}
27626
27627Equality of untagged record composes, so that the predefined equality for a
27628composite type that includes a component of some untagged record type
27629@code{R} uses the equality operation of @code{R} (which may be user-defined
27630or predefined). This makes the behavior of untagged records identical to that
27631of tagged types in this respect.
27632
27633This change is an incompatibility with previous versions of Ada, but it
27634corrects a non-uniformity that was often a source of confusion. Analysis of
27635a large number of industrial programs indicates that in those rare cases
27636where a composite type had an untagged record component with a user-defined
27637equality, either there was no use of the composite equality, or else the code
27638expected the same composability as for tagged types, and thus had a bug that
27639would be fixed by this change.
27640
27641RM References:  4.05.02 (9.7/2)   4.05.02 (14)   4.05.02 (15)   4.05.02 (24)
276428.05.04 (8)
27643@end itemize
27644
27645@geindex AI-0088 (Ada 2012 feature)
27646
27647
27648@itemize *
27649
27650@item
27651@emph{AI-0088 The value of exponentiation (0000-00-00)}
27652
27653This AI clarifies the equivalence rule given for the dynamic semantics of
27654exponentiation: the value of the operation can be obtained by repeated
27655multiplication, but the operation can be implemented otherwise (for example
27656using the familiar divide-by-two-and-square algorithm, even if this is less
27657accurate), and does not imply repeated reads of a volatile base.
27658
27659RM References:  4.05.06 (11)
27660@end itemize
27661
27662@geindex AI-0188 (Ada 2012 feature)
27663
27664
27665@itemize *
27666
27667@item
27668@emph{AI-0188 Case expressions (2010-01-09)}
27669
27670Case expressions are permitted. This allows use of constructs such as:
27671
27672@example
27673X := (case Y is when 1 => 2, when 2 => 3, when others => 31)
27674@end example
27675
27676RM References:  4.05.07 (0)   4.05.08 (0)   4.09 (12)   4.09 (33)
27677@end itemize
27678
27679@geindex AI-0104 (Ada 2012 feature)
27680
27681
27682@itemize *
27683
27684@item
27685@emph{AI-0104 Null exclusion and uninitialized allocator (2010-07-15)}
27686
27687The assignment @code{Ptr := new not null Some_Ptr;} will raise
27688@code{Constraint_Error} because the default value of the allocated object is
27689@strong{null}. This useless construct is illegal in Ada 2012.
27690
27691RM References:  4.08 (2)
27692@end itemize
27693
27694@geindex AI-0157 (Ada 2012 feature)
27695
27696
27697@itemize *
27698
27699@item
27700@emph{AI-0157 Allocation/Deallocation from empty pool (2010-07-11)}
27701
27702Allocation and Deallocation from an empty storage pool (i.e. allocation or
27703deallocation of a pointer for which a static storage size clause of zero
27704has been given) is now illegal and is detected as such. GNAT
27705previously gave a warning but not an error.
27706
27707RM References:  4.08 (5.3/2)   13.11.02 (4)   13.11.02 (17)
27708@end itemize
27709
27710@geindex AI-0179 (Ada 2012 feature)
27711
27712
27713@itemize *
27714
27715@item
27716@emph{AI-0179 Statement not required after label (2010-04-10)}
27717
27718It is not necessary to have a statement following a label, so a label
27719can appear at the end of a statement sequence without the need for putting a
27720null statement afterwards, but it is not allowable to have only labels and
27721no real statements in a statement sequence.
27722
27723RM References:  5.01 (2)
27724@end itemize
27725
27726@geindex AI-0139-2 (Ada 2012 feature)
27727
27728
27729@itemize *
27730
27731@item
27732@emph{AI-0139-2 Syntactic sugar for iterators (2010-09-29)}
27733
27734The new syntax for iterating over arrays and containers is now implemented.
27735Iteration over containers is for now limited to read-only iterators. Only
27736default iterators are supported, with the syntax:  @code{for Elem of C}.
27737
27738RM References:  5.05
27739@end itemize
27740
27741@geindex AI-0134 (Ada 2012 feature)
27742
27743
27744@itemize *
27745
27746@item
27747@emph{AI-0134 Profiles must match for full conformance (0000-00-00)}
27748
27749For full conformance, the profiles of anonymous-access-to-subprogram
27750parameters must match. GNAT has always enforced this rule.
27751
27752RM References:  6.03.01 (18)
27753@end itemize
27754
27755@geindex AI-0207 (Ada 2012 feature)
27756
27757
27758@itemize *
27759
27760@item
27761@emph{AI-0207 Mode conformance and access constant (0000-00-00)}
27762
27763This AI confirms that access_to_constant indication must match for mode
27764conformance. This was implemented in GNAT when the qualifier was originally
27765introduced in Ada 2005.
27766
27767RM References:  6.03.01 (16/2)
27768@end itemize
27769
27770@geindex AI-0046 (Ada 2012 feature)
27771
27772
27773@itemize *
27774
27775@item
27776@emph{AI-0046 Null exclusion match for full conformance (2010-07-17)}
27777
27778For full conformance, in the case of access parameters, the null exclusion
27779must match (either both or neither must have @code{not null}).
27780
27781RM References:  6.03.02 (18)
27782@end itemize
27783
27784@geindex AI-0118 (Ada 2012 feature)
27785
27786
27787@itemize *
27788
27789@item
27790@emph{AI-0118 The association of parameter associations (0000-00-00)}
27791
27792This AI clarifies the rules for named associations in subprogram calls and
27793generic instantiations. The rules have been in place since Ada 83.
27794
27795RM References:  6.04.01 (2)   12.03 (9)
27796@end itemize
27797
27798@geindex AI-0196 (Ada 2012 feature)
27799
27800
27801@itemize *
27802
27803@item
27804@emph{AI-0196 Null exclusion tests for out parameters (0000-00-00)}
27805
27806Null exclusion checks are not made for @code{out} parameters when
27807evaluating the actual parameters. GNAT has never generated these checks.
27808
27809RM References:  6.04.01 (13)
27810@end itemize
27811
27812@geindex AI-0015 (Ada 2012 feature)
27813
27814
27815@itemize *
27816
27817@item
27818@emph{AI-0015 Constant return objects (0000-00-00)}
27819
27820The return object declared in an @emph{extended_return_statement} may be
27821declared constant. This was always intended, and GNAT has always allowed it.
27822
27823RM References:  6.05 (2.1/2)   3.03 (10/2)   3.03 (21)   6.05 (5/2)
278246.05 (5.7/2)
27825@end itemize
27826
27827@geindex AI-0032 (Ada 2012 feature)
27828
27829
27830@itemize *
27831
27832@item
27833@emph{AI-0032 Extended return for class-wide functions (0000-00-00)}
27834
27835If a function returns a class-wide type, the object of an extended return
27836statement can be declared with a specific type that is covered by the class-
27837wide type. This has been implemented in GNAT since the introduction of
27838extended returns. Note AI-0103 complements this AI by imposing matching
27839rules for constrained return types.
27840
27841RM References:  6.05 (5.2/2)   6.05 (5.3/2)   6.05 (5.6/2)   6.05 (5.8/2)
278426.05 (8/2)
27843@end itemize
27844
27845@geindex AI-0103 (Ada 2012 feature)
27846
27847
27848@itemize *
27849
27850@item
27851@emph{AI-0103 Static matching for extended return (2010-07-23)}
27852
27853If the return subtype of a function is an elementary type or a constrained
27854type, the subtype indication in an extended return statement must match
27855statically this return subtype.
27856
27857RM References:  6.05 (5.2/2)
27858@end itemize
27859
27860@geindex AI-0058 (Ada 2012 feature)
27861
27862
27863@itemize *
27864
27865@item
27866@emph{AI-0058 Abnormal completion of an extended return (0000-00-00)}
27867
27868The RM had some incorrect wording implying wrong treatment of abnormal
27869completion in an extended return. GNAT has always implemented the intended
27870correct semantics as described by this AI.
27871
27872RM References:  6.05 (22/2)
27873@end itemize
27874
27875@geindex AI-0050 (Ada 2012 feature)
27876
27877
27878@itemize *
27879
27880@item
27881@emph{AI-0050 Raising Constraint_Error early for function call (0000-00-00)}
27882
27883The implementation permissions for raising @code{Constraint_Error} early on a function call
27884when it was clear an exception would be raised were over-permissive and allowed
27885mishandling of discriminants in some cases. GNAT did
27886not take advantage of these incorrect permissions in any case.
27887
27888RM References:  6.05 (24/2)
27889@end itemize
27890
27891@geindex AI-0125 (Ada 2012 feature)
27892
27893
27894@itemize *
27895
27896@item
27897@emph{AI-0125 Nonoverridable operations of an ancestor (2010-09-28)}
27898
27899In Ada 2012, the declaration of a primitive operation of a type extension
27900or private extension can also override an inherited primitive that is not
27901visible at the point of this declaration.
27902
27903RM References:  7.03.01 (6)   8.03 (23)   8.03.01 (5/2)   8.03.01 (6/2)
27904@end itemize
27905
27906@geindex AI-0062 (Ada 2012 feature)
27907
27908
27909@itemize *
27910
27911@item
27912@emph{AI-0062 Null exclusions and deferred constants (0000-00-00)}
27913
27914A full constant may have a null exclusion even if its associated deferred
27915constant does not. GNAT has always allowed this.
27916
27917RM References:  7.04 (6/2)   7.04 (7.1/2)
27918@end itemize
27919
27920@geindex AI-0178 (Ada 2012 feature)
27921
27922
27923@itemize *
27924
27925@item
27926@emph{AI-0178 Incomplete views are limited (0000-00-00)}
27927
27928This AI clarifies the role of incomplete views and plugs an omission in the
27929RM. GNAT always correctly restricted the use of incomplete views and types.
27930
27931RM References:  7.05 (3/2)   7.05 (6/2)
27932@end itemize
27933
27934@geindex AI-0087 (Ada 2012 feature)
27935
27936
27937@itemize *
27938
27939@item
27940@emph{AI-0087 Actual for formal nonlimited derived type (2010-07-15)}
27941
27942The actual for a formal nonlimited derived type cannot be limited. In
27943particular, a formal derived type that extends a limited interface but which
27944is not explicitly limited cannot be instantiated with a limited type.
27945
27946RM References:  7.05 (5/2)   12.05.01 (5.1/2)
27947@end itemize
27948
27949@geindex AI-0099 (Ada 2012 feature)
27950
27951
27952@itemize *
27953
27954@item
27955@emph{AI-0099 Tag determines whether finalization needed (0000-00-00)}
27956
27957This AI clarifies that ‘needs finalization’ is part of dynamic semantics,
27958and therefore depends on the run-time characteristics of an object (i.e. its
27959tag) and not on its nominal type. As the AI indicates: “we do not expect
27960this to affect any implementation’’.
27961
27962RM References:  7.06.01 (6)   7.06.01 (7)   7.06.01 (8)   7.06.01 (9/2)
27963@end itemize
27964
27965@geindex AI-0064 (Ada 2012 feature)
27966
27967
27968@itemize *
27969
27970@item
27971@emph{AI-0064 Redundant finalization rule (0000-00-00)}
27972
27973This is an editorial change only. The intended behavior is already checked
27974by an existing ACATS test, which GNAT has always executed correctly.
27975
27976RM References:  7.06.01 (17.1/1)
27977@end itemize
27978
27979@geindex AI-0026 (Ada 2012 feature)
27980
27981
27982@itemize *
27983
27984@item
27985@emph{AI-0026 Missing rules for Unchecked_Union (2010-07-07)}
27986
27987Record representation clauses concerning Unchecked_Union types cannot mention
27988the discriminant of the type. The type of a component declared in the variant
27989part of an Unchecked_Union cannot be controlled, have controlled components,
27990nor have protected or task parts. If an Unchecked_Union type is declared
27991within the body of a generic unit or its descendants, then the type of a
27992component declared in the variant part cannot be a formal private type or a
27993formal private extension declared within the same generic unit.
27994
27995RM References:  7.06 (9.4/2)   B.03.03 (9/2)   B.03.03 (10/2)
27996@end itemize
27997
27998@geindex AI-0205 (Ada 2012 feature)
27999
28000
28001@itemize *
28002
28003@item
28004@emph{AI-0205 Extended return declares visible name (0000-00-00)}
28005
28006This AI corrects a simple omission in the RM. Return objects have always
28007been visible within an extended return statement.
28008
28009RM References:  8.03 (17)
28010@end itemize
28011
28012@geindex AI-0042 (Ada 2012 feature)
28013
28014
28015@itemize *
28016
28017@item
28018@emph{AI-0042 Overriding versus implemented-by (0000-00-00)}
28019
28020This AI fixes a wording gap in the RM. An operation of a synchronized
28021interface can be implemented by a protected or task entry, but the abstract
28022operation is not being overridden in the usual sense, and it must be stated
28023separately that this implementation is legal. This has always been the case
28024in GNAT.
28025
28026RM References:  9.01 (9.2/2)   9.04 (11.1/2)
28027@end itemize
28028
28029@geindex AI-0030 (Ada 2012 feature)
28030
28031
28032@itemize *
28033
28034@item
28035@emph{AI-0030 Requeue on synchronized interfaces (2010-07-19)}
28036
28037Requeue is permitted to a protected, synchronized or task interface primitive
28038providing it is known that the overriding operation is an entry. Otherwise
28039the requeue statement has the same effect as a procedure call. Use of pragma
28040@code{Implemented} provides a way to impose a static requirement on the
28041overriding operation by adhering to one of the implementation kinds: entry,
28042protected procedure or any of the above.
28043
28044RM References:  9.05 (9)   9.05.04 (2)   9.05.04 (3)   9.05.04 (5)
280459.05.04 (6)   9.05.04 (7)   9.05.04 (12)
28046@end itemize
28047
28048@geindex AI-0201 (Ada 2012 feature)
28049
28050
28051@itemize *
28052
28053@item
28054@emph{AI-0201 Independence of atomic object components (2010-07-22)}
28055
28056If an Atomic object has a pragma @code{Pack} or a @code{Component_Size}
28057attribute, then individual components may not be addressable by independent
28058tasks. However, if the representation clause has no effect (is confirming),
28059then independence is not compromised. Furthermore, in GNAT, specification of
28060other appropriately addressable component sizes (e.g. 16 for 8-bit
28061characters) also preserves independence. GNAT now gives very clear warnings
28062both for the declaration of such a type, and for any assignment to its components.
28063
28064RM References:  9.10 (1/3)   C.06 (22/2)   C.06 (23/2)
28065@end itemize
28066
28067@geindex AI-0009 (Ada 2012 feature)
28068
28069
28070@itemize *
28071
28072@item
28073@emph{AI-0009 Pragma Independent[_Components] (2010-07-23)}
28074
28075This AI introduces the new pragmas @code{Independent} and
28076@code{Independent_Components},
28077which control guaranteeing independence of access to objects and components.
28078The AI also requires independence not unaffected by confirming rep clauses.
28079
28080RM References:  9.10 (1)   13.01 (15/1)   13.02 (9)   13.03 (13)   C.06 (2)
28081C.06 (4)   C.06 (6)   C.06 (9)   C.06 (13)   C.06 (14)
28082@end itemize
28083
28084@geindex AI-0072 (Ada 2012 feature)
28085
28086
28087@itemize *
28088
28089@item
28090@emph{AI-0072 Task signalling using ‘Terminated (0000-00-00)}
28091
28092This AI clarifies that task signalling for reading @code{'Terminated} only
28093occurs if the result is True. GNAT semantics has always been consistent with
28094this notion of task signalling.
28095
28096RM References:  9.10 (6.1/1)
28097@end itemize
28098
28099@geindex AI-0108 (Ada 2012 feature)
28100
28101
28102@itemize *
28103
28104@item
28105@emph{AI-0108 Limited incomplete view and discriminants (0000-00-00)}
28106
28107This AI confirms that an incomplete type from a limited view does not have
28108discriminants. This has always been the case in GNAT.
28109
28110RM References:  10.01.01 (12.3/2)
28111@end itemize
28112
28113@geindex AI-0129 (Ada 2012 feature)
28114
28115
28116@itemize *
28117
28118@item
28119@emph{AI-0129 Limited views and incomplete types (0000-00-00)}
28120
28121This AI clarifies the description of limited views: a limited view of a
28122package includes only one view of a type that has an incomplete declaration
28123and a full declaration (there is no possible ambiguity in a client package).
28124This AI also fixes an omission: a nested package in the private part has no
28125limited view. GNAT always implemented this correctly.
28126
28127RM References:  10.01.01 (12.2/2)   10.01.01 (12.3/2)
28128@end itemize
28129
28130@geindex AI-0077 (Ada 2012 feature)
28131
28132
28133@itemize *
28134
28135@item
28136@emph{AI-0077 Limited withs and scope of declarations (0000-00-00)}
28137
28138This AI clarifies that a declaration does not include a context clause,
28139and confirms that it is illegal to have a context in which both a limited
28140and a nonlimited view of a package are accessible. Such double visibility
28141was always rejected by GNAT.
28142
28143RM References:  10.01.02 (12/2)   10.01.02 (21/2)   10.01.02 (22/2)
28144@end itemize
28145
28146@geindex AI-0122 (Ada 2012 feature)
28147
28148
28149@itemize *
28150
28151@item
28152@emph{AI-0122 Private with and children of generics (0000-00-00)}
28153
28154This AI clarifies the visibility of private children of generic units within
28155instantiations of a parent. GNAT has always handled this correctly.
28156
28157RM References:  10.01.02 (12/2)
28158@end itemize
28159
28160@geindex AI-0040 (Ada 2012 feature)
28161
28162
28163@itemize *
28164
28165@item
28166@emph{AI-0040 Limited with clauses on descendant (0000-00-00)}
28167
28168This AI confirms that a limited with clause in a child unit cannot name
28169an ancestor of the unit. This has always been checked in GNAT.
28170
28171RM References:  10.01.02 (20/2)
28172@end itemize
28173
28174@geindex AI-0132 (Ada 2012 feature)
28175
28176
28177@itemize *
28178
28179@item
28180@emph{AI-0132 Placement of library unit pragmas (0000-00-00)}
28181
28182This AI fills a gap in the description of library unit pragmas. The pragma
28183clearly must apply to a library unit, even if it does not carry the name
28184of the enclosing unit. GNAT has always enforced the required check.
28185
28186RM References:  10.01.05 (7)
28187@end itemize
28188
28189@geindex AI-0034 (Ada 2012 feature)
28190
28191
28192@itemize *
28193
28194@item
28195@emph{AI-0034 Categorization of limited views (0000-00-00)}
28196
28197The RM makes certain limited with clauses illegal because of categorization
28198considerations, when the corresponding normal with would be legal. This is
28199not intended, and GNAT has always implemented the recommended behavior.
28200
28201RM References:  10.02.01 (11/1)   10.02.01 (17/2)
28202@end itemize
28203
28204@geindex AI-0035 (Ada 2012 feature)
28205
28206
28207@itemize *
28208
28209@item
28210@emph{AI-0035 Inconsistencies with Pure units (0000-00-00)}
28211
28212This AI remedies some inconsistencies in the legality rules for Pure units.
28213Derived access types are legal in a pure unit (on the assumption that the
28214rule for a zero storage pool size has been enforced on the ancestor type).
28215The rules are enforced in generic instances and in subunits. GNAT has always
28216implemented the recommended behavior.
28217
28218RM References:  10.02.01 (15.1/2)   10.02.01 (15.4/2)   10.02.01 (15.5/2)   10.02.01 (17/2)
28219@end itemize
28220
28221@geindex AI-0219 (Ada 2012 feature)
28222
28223
28224@itemize *
28225
28226@item
28227@emph{AI-0219 Pure permissions and limited parameters (2010-05-25)}
28228
28229This AI refines the rules for the cases with limited parameters which do not
28230allow the implementations to omit ‘redundant’. GNAT now properly conforms
28231to the requirements of this binding interpretation.
28232
28233RM References:  10.02.01 (18/2)
28234@end itemize
28235
28236@geindex AI-0043 (Ada 2012 feature)
28237
28238
28239@itemize *
28240
28241@item
28242@emph{AI-0043 Rules about raising exceptions (0000-00-00)}
28243
28244This AI covers various omissions in the RM regarding the raising of
28245exceptions. GNAT has always implemented the intended semantics.
28246
28247RM References:  11.04.01 (10.1/2)   11 (2)
28248@end itemize
28249
28250@geindex AI-0200 (Ada 2012 feature)
28251
28252
28253@itemize *
28254
28255@item
28256@emph{AI-0200 Mismatches in formal package declarations (0000-00-00)}
28257
28258This AI plugs a gap in the RM which appeared to allow some obviously intended
28259illegal instantiations. GNAT has never allowed these instantiations.
28260
28261RM References:  12.07 (16)
28262@end itemize
28263
28264@geindex AI-0112 (Ada 2012 feature)
28265
28266
28267@itemize *
28268
28269@item
28270@emph{AI-0112 Detection of duplicate pragmas (2010-07-24)}
28271
28272This AI concerns giving names to various representation aspects, but the
28273practical effect is simply to make the use of duplicate
28274@code{Atomic[_Components]},
28275@code{Volatile[_Components]}, and
28276@code{Independent[_Components]} pragmas illegal, and GNAT
28277now performs this required check.
28278
28279RM References:  13.01 (8)
28280@end itemize
28281
28282@geindex AI-0106 (Ada 2012 feature)
28283
28284
28285@itemize *
28286
28287@item
28288@emph{AI-0106 No representation pragmas on generic formals (0000-00-00)}
28289
28290The RM appeared to allow representation pragmas on generic formal parameters,
28291but this was not intended, and GNAT has never permitted this usage.
28292
28293RM References:  13.01 (9.1/1)
28294@end itemize
28295
28296@geindex AI-0012 (Ada 2012 feature)
28297
28298
28299@itemize *
28300
28301@item
28302@emph{AI-0012 Pack/Component_Size for aliased/atomic (2010-07-15)}
28303
28304It is now illegal to give an inappropriate component size or a pragma
28305@code{Pack} that attempts to change the component size in the case of atomic
28306or aliased components. Previously GNAT ignored such an attempt with a
28307warning.
28308
28309RM References:  13.02 (6.1/2)   13.02 (7)   C.06 (10)   C.06 (11)   C.06 (21)
28310@end itemize
28311
28312@geindex AI-0039 (Ada 2012 feature)
28313
28314
28315@itemize *
28316
28317@item
28318@emph{AI-0039 Stream attributes cannot be dynamic (0000-00-00)}
28319
28320The RM permitted the use of dynamic expressions (such as @code{ptr.all})`
28321for stream attributes, but these were never useful and are now illegal. GNAT
28322has always regarded such expressions as illegal.
28323
28324RM References:  13.03 (4)   13.03 (6)   13.13.02 (38/2)
28325@end itemize
28326
28327@geindex AI-0095 (Ada 2012 feature)
28328
28329
28330@itemize *
28331
28332@item
28333@emph{AI-0095 Address of intrinsic subprograms (0000-00-00)}
28334
28335The prefix of @code{'Address} cannot statically denote a subprogram with
28336convention @code{Intrinsic}. The use of the @code{Address} attribute raises
28337@code{Program_Error} if the prefix denotes a subprogram with convention
28338@code{Intrinsic}.
28339
28340RM References:  13.03 (11/1)
28341@end itemize
28342
28343@geindex AI-0116 (Ada 2012 feature)
28344
28345
28346@itemize *
28347
28348@item
28349@emph{AI-0116 Alignment of class-wide objects (0000-00-00)}
28350
28351This AI requires that the alignment of a class-wide object be no greater
28352than the alignment of any type in the class. GNAT has always followed this
28353recommendation.
28354
28355RM References:  13.03 (29)   13.11 (16)
28356@end itemize
28357
28358@geindex AI-0146 (Ada 2012 feature)
28359
28360
28361@itemize *
28362
28363@item
28364@emph{AI-0146 Type invariants (2009-09-21)}
28365
28366Type invariants may be specified for private types using the aspect notation.
28367Aspect @code{Type_Invariant} may be specified for any private type,
28368@code{Type_Invariant'Class} can
28369only be specified for tagged types, and is inherited by any descendent of the
28370tagged types. The invariant is a boolean expression that is tested for being
28371true in the following situations: conversions to the private type, object
28372declarations for the private type that are default initialized, and
28373[@strong{in}] @strong{out}
28374parameters and returned result on return from any primitive operation for
28375the type that is visible to a client.
28376GNAT defines the synonyms @code{Invariant} for @code{Type_Invariant} and
28377@code{Invariant'Class} for @code{Type_Invariant'Class}.
28378
28379RM References:  13.03.03 (00)
28380@end itemize
28381
28382@geindex AI-0078 (Ada 2012 feature)
28383
28384
28385@itemize *
28386
28387@item
28388@emph{AI-0078 Relax Unchecked_Conversion alignment rules (0000-00-00)}
28389
28390In Ada 2012, compilers are required to support unchecked conversion where the
28391target alignment is a multiple of the source alignment. GNAT always supported
28392this case (and indeed all cases of differing alignments, doing copies where
28393required if the alignment was reduced).
28394
28395RM References:  13.09 (7)
28396@end itemize
28397
28398@geindex AI-0195 (Ada 2012 feature)
28399
28400
28401@itemize *
28402
28403@item
28404@emph{AI-0195 Invalid value handling is implementation defined (2010-07-03)}
28405
28406The handling of invalid values is now designated to be implementation
28407defined. This is a documentation change only, requiring Annex M in the GNAT
28408Reference Manual to document this handling.
28409In GNAT, checks for invalid values are made
28410only when necessary to avoid erroneous behavior. Operations like assignments
28411which cannot cause erroneous behavior ignore the possibility of invalid
28412values and do not do a check. The date given above applies only to the
28413documentation change, this behavior has always been implemented by GNAT.
28414
28415RM References:  13.09.01 (10)
28416@end itemize
28417
28418@geindex AI-0193 (Ada 2012 feature)
28419
28420
28421@itemize *
28422
28423@item
28424@emph{AI-0193 Alignment of allocators (2010-09-16)}
28425
28426This AI introduces a new attribute @code{Max_Alignment_For_Allocation},
28427analogous to @code{Max_Size_In_Storage_Elements}, but for alignment instead
28428of size.
28429
28430RM References:  13.11 (16)   13.11 (21)   13.11.01 (0)   13.11.01 (1)
2843113.11.01 (2)   13.11.01 (3)
28432@end itemize
28433
28434@geindex AI-0177 (Ada 2012 feature)
28435
28436
28437@itemize *
28438
28439@item
28440@emph{AI-0177 Parameterized expressions (2010-07-10)}
28441
28442The new Ada 2012 notion of parameterized expressions is implemented. The form
28443is:
28444
28445@example
28446function-specification is (expression)
28447@end example
28448
28449This is exactly equivalent to the
28450corresponding function body that returns the expression, but it can appear
28451in a package spec. Note that the expression must be parenthesized.
28452
28453RM References:  13.11.01 (3/2)
28454@end itemize
28455
28456@geindex AI-0033 (Ada 2012 feature)
28457
28458
28459@itemize *
28460
28461@item
28462@emph{AI-0033 Attach/Interrupt_Handler in generic (2010-07-24)}
28463
28464Neither of these two pragmas may appear within a generic template, because
28465the generic might be instantiated at other than the library level.
28466
28467RM References:  13.11.02 (16)   C.03.01 (7/2)   C.03.01 (8/2)
28468@end itemize
28469
28470@geindex AI-0161 (Ada 2012 feature)
28471
28472
28473@itemize *
28474
28475@item
28476@emph{AI-0161 Restriction No_Default_Stream_Attributes (2010-09-11)}
28477
28478A new restriction @code{No_Default_Stream_Attributes} prevents the use of any
28479of the default stream attributes for elementary types. If this restriction is
28480in force, then it is necessary to provide explicit subprograms for any
28481stream attributes used.
28482
28483RM References:  13.12.01 (4/2)   13.13.02 (40/2)   13.13.02 (52/2)
28484@end itemize
28485
28486@geindex AI-0194 (Ada 2012 feature)
28487
28488
28489@itemize *
28490
28491@item
28492@emph{AI-0194 Value of Stream_Size attribute (0000-00-00)}
28493
28494The @code{Stream_Size} attribute returns the default number of bits in the
28495stream representation of the given type.
28496This value is not affected by the presence
28497of stream subprogram attributes for the type. GNAT has always implemented
28498this interpretation.
28499
28500RM References:  13.13.02 (1.2/2)
28501@end itemize
28502
28503@geindex AI-0109 (Ada 2012 feature)
28504
28505
28506@itemize *
28507
28508@item
28509@emph{AI-0109 Redundant check in S’Class’Input (0000-00-00)}
28510
28511This AI is an editorial change only. It removes the need for a tag check
28512that can never fail.
28513
28514RM References:  13.13.02 (34/2)
28515@end itemize
28516
28517@geindex AI-0007 (Ada 2012 feature)
28518
28519
28520@itemize *
28521
28522@item
28523@emph{AI-0007 Stream read and private scalar types (0000-00-00)}
28524
28525The RM as written appeared to limit the possibilities of declaring read
28526attribute procedures for private scalar types. This limitation was not
28527intended, and has never been enforced by GNAT.
28528
28529RM References:  13.13.02 (50/2)   13.13.02 (51/2)
28530@end itemize
28531
28532@geindex AI-0065 (Ada 2012 feature)
28533
28534
28535@itemize *
28536
28537@item
28538@emph{AI-0065 Remote access types and external streaming (0000-00-00)}
28539
28540This AI clarifies the fact that all remote access types support external
28541streaming. This fixes an obvious oversight in the definition of the
28542language, and GNAT always implemented the intended correct rules.
28543
28544RM References:  13.13.02 (52/2)
28545@end itemize
28546
28547@geindex AI-0019 (Ada 2012 feature)
28548
28549
28550@itemize *
28551
28552@item
28553@emph{AI-0019 Freezing of primitives for tagged types (0000-00-00)}
28554
28555The RM suggests that primitive subprograms of a specific tagged type are
28556frozen when the tagged type is frozen. This would be an incompatible change
28557and is not intended. GNAT has never attempted this kind of freezing and its
28558behavior is consistent with the recommendation of this AI.
28559
28560RM References:  13.14 (2)   13.14 (3/1)   13.14 (8.1/1)   13.14 (10)   13.14 (14)   13.14 (15.1/2)
28561@end itemize
28562
28563@geindex AI-0017 (Ada 2012 feature)
28564
28565
28566@itemize *
28567
28568@item
28569@emph{AI-0017 Freezing and incomplete types (0000-00-00)}
28570
28571So-called ‘Taft-amendment types’ (i.e., types that are completed in package
28572bodies) are not frozen by the occurrence of bodies in the
28573enclosing declarative part. GNAT always implemented this properly.
28574
28575RM References:  13.14 (3/1)
28576@end itemize
28577
28578@geindex AI-0060 (Ada 2012 feature)
28579
28580
28581@itemize *
28582
28583@item
28584@emph{AI-0060 Extended definition of remote access types (0000-00-00)}
28585
28586This AI extends the definition of remote access types to include access
28587to limited, synchronized, protected or task class-wide interface types.
28588GNAT already implemented this extension.
28589
28590RM References:  A (4)   E.02.02 (9/1)   E.02.02 (9.2/1)   E.02.02 (14/2)   E.02.02 (18)
28591@end itemize
28592
28593@geindex AI-0114 (Ada 2012 feature)
28594
28595
28596@itemize *
28597
28598@item
28599@emph{AI-0114 Classification of letters (0000-00-00)}
28600
28601The code points 170 (@code{FEMININE ORDINAL INDICATOR}),
28602181 (@code{MICRO SIGN}), and
28603186 (@code{MASCULINE ORDINAL INDICATOR}) are technically considered
28604lower case letters by Unicode.
28605However, they are not allowed in identifiers, and they
28606return @code{False} to @code{Ada.Characters.Handling.Is_Letter/Is_Lower}.
28607This behavior is consistent with that defined in Ada 95.
28608
28609RM References:  A.03.02 (59)   A.04.06 (7)
28610@end itemize
28611
28612@geindex AI-0185 (Ada 2012 feature)
28613
28614
28615@itemize *
28616
28617@item
28618@emph{AI-0185 Ada.Wide_[Wide_]Characters.Handling (2010-07-06)}
28619
28620Two new packages @code{Ada.Wide_[Wide_]Characters.Handling} provide
28621classification functions for @code{Wide_Character} and
28622@code{Wide_Wide_Character}, as well as providing
28623case folding routines for @code{Wide_[Wide_]Character} and
28624@code{Wide_[Wide_]String}.
28625
28626RM References:  A.03.05 (0)   A.03.06 (0)
28627@end itemize
28628
28629@geindex AI-0031 (Ada 2012 feature)
28630
28631
28632@itemize *
28633
28634@item
28635@emph{AI-0031 Add From parameter to Find_Token (2010-07-25)}
28636
28637A new version of @code{Find_Token} is added to all relevant string packages,
28638with an extra parameter @code{From}. Instead of starting at the first
28639character of the string, the search for a matching Token starts at the
28640character indexed by the value of @code{From}.
28641These procedures are available in all versions of Ada
28642but if used in versions earlier than Ada 2012 they will generate a warning
28643that an Ada 2012 subprogram is being used.
28644
28645RM References:  A.04.03 (16)   A.04.03 (67)   A.04.03 (68/1)   A.04.04 (51)
28646A.04.05 (46)
28647@end itemize
28648
28649@geindex AI-0056 (Ada 2012 feature)
28650
28651
28652@itemize *
28653
28654@item
28655@emph{AI-0056 Index on null string returns zero (0000-00-00)}
28656
28657The wording in the Ada 2005 RM implied an incompatible handling of the
28658@code{Index} functions, resulting in raising an exception instead of
28659returning zero in some situations.
28660This was not intended and has been corrected.
28661GNAT always returned zero, and is thus consistent with this AI.
28662
28663RM References:  A.04.03 (56.2/2)   A.04.03 (58.5/2)
28664@end itemize
28665
28666@geindex AI-0137 (Ada 2012 feature)
28667
28668
28669@itemize *
28670
28671@item
28672@emph{AI-0137 String encoding package (2010-03-25)}
28673
28674The packages @code{Ada.Strings.UTF_Encoding}, together with its child
28675packages, @code{Conversions}, @code{Strings}, @code{Wide_Strings},
28676and @code{Wide_Wide_Strings} have been
28677implemented. These packages (whose documentation can be found in the spec
28678files @code{a-stuten.ads}, @code{a-suenco.ads}, @code{a-suenst.ads},
28679@code{a-suewst.ads}, @code{a-suezst.ads}) allow encoding and decoding of
28680@code{String}, @code{Wide_String}, and @code{Wide_Wide_String}
28681values using UTF coding schemes (including UTF-8, UTF-16LE, UTF-16BE, and
28682UTF-16), as well as conversions between the different UTF encodings. With
28683the exception of @code{Wide_Wide_Strings}, these packages are available in
28684Ada 95 and Ada 2005 mode as well as Ada 2012 mode.
28685The @code{Wide_Wide_Strings} package
28686is available in Ada 2005 mode as well as Ada 2012 mode (but not in Ada 95
28687mode since it uses @code{Wide_Wide_Character}).
28688
28689RM References:  A.04.11
28690@end itemize
28691
28692@geindex AI-0038 (Ada 2012 feature)
28693
28694
28695@itemize *
28696
28697@item
28698@emph{AI-0038 Minor errors in Text_IO (0000-00-00)}
28699
28700These are minor errors in the description on three points. The intent on
28701all these points has always been clear, and GNAT has always implemented the
28702correct intended semantics.
28703
28704RM 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)
28705@end itemize
28706
28707@geindex AI-0044 (Ada 2012 feature)
28708
28709
28710@itemize *
28711
28712@item
28713@emph{AI-0044 Restrictions on container instantiations (0000-00-00)}
28714
28715This AI places restrictions on allowed instantiations of generic containers.
28716These restrictions are not checked by the compiler, so there is nothing to
28717change in the implementation. This affects only the RM documentation.
28718
28719RM 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)
28720@end itemize
28721
28722@geindex AI-0127 (Ada 2012 feature)
28723
28724
28725@itemize *
28726
28727@item
28728@emph{AI-0127 Adding Locale Capabilities (2010-09-29)}
28729
28730This package provides an interface for identifying the current locale.
28731
28732RM References:  A.19    A.19.01    A.19.02    A.19.03    A.19.05    A.19.06
28733A.19.07    A.19.08    A.19.09    A.19.10    A.19.11    A.19.12    A.19.13
28734@end itemize
28735
28736@geindex AI-0002 (Ada 2012 feature)
28737
28738
28739@itemize *
28740
28741@item
28742@emph{AI-0002 Export C with unconstrained arrays (0000-00-00)}
28743
28744The compiler is not required to support exporting an Ada subprogram with
28745convention C if there are parameters or a return type of an unconstrained
28746array type (such as @code{String}). GNAT allows such declarations but
28747generates warnings. It is possible, but complicated, to write the
28748corresponding C code and certainly such code would be specific to GNAT and
28749non-portable.
28750
28751RM References:  B.01 (17)   B.03 (62)   B.03 (71.1/2)
28752@end itemize
28753
28754@geindex AI05-0216 (Ada 2012 feature)
28755
28756
28757@itemize *
28758
28759@item
28760@emph{AI-0216 No_Task_Hierarchy forbids local tasks (0000-00-00)}
28761
28762It is clearly the intention that @code{No_Task_Hierarchy} is intended to
28763forbid tasks declared locally within subprograms, or functions returning task
28764objects, and that is the implementation that GNAT has always provided.
28765However the language in the RM was not sufficiently clear on this point.
28766Thus this is a documentation change in the RM only.
28767
28768RM References:  D.07 (3/3)
28769@end itemize
28770
28771@geindex AI-0211 (Ada 2012 feature)
28772
28773
28774@itemize *
28775
28776@item
28777@emph{AI-0211 No_Relative_Delays forbids Set_Handler use (2010-07-09)}
28778
28779The restriction @code{No_Relative_Delays} forbids any calls to the subprogram
28780@code{Ada.Real_Time.Timing_Events.Set_Handler}.
28781
28782RM References:  D.07 (5)   D.07 (10/2)   D.07 (10.4/2)   D.07 (10.7/2)
28783@end itemize
28784
28785@geindex AI-0190 (Ada 2012 feature)
28786
28787
28788@itemize *
28789
28790@item
28791@emph{AI-0190 pragma Default_Storage_Pool (2010-09-15)}
28792
28793This AI introduces a new pragma @code{Default_Storage_Pool}, which can be
28794used to control storage pools globally.
28795In particular, you can force every access
28796type that is used for allocation (@strong{new}) to have an explicit storage pool,
28797or you can declare a pool globally to be used for all access types that lack
28798an explicit one.
28799
28800RM References:  D.07 (8)
28801@end itemize
28802
28803@geindex AI-0189 (Ada 2012 feature)
28804
28805
28806@itemize *
28807
28808@item
28809@emph{AI-0189 No_Allocators_After_Elaboration (2010-01-23)}
28810
28811This AI introduces a new restriction @code{No_Allocators_After_Elaboration},
28812which says that no dynamic allocation will occur once elaboration is
28813completed.
28814In general this requires a run-time check, which is not required, and which
28815GNAT does not attempt. But the static cases of allocators in a task body or
28816in the body of the main program are detected and flagged at compile or bind
28817time.
28818
28819RM References:  D.07 (19.1/2)   H.04 (23.3/2)
28820@end itemize
28821
28822@geindex AI-0171 (Ada 2012 feature)
28823
28824
28825@itemize *
28826
28827@item
28828@emph{AI-0171 Pragma CPU and Ravenscar Profile (2010-09-24)}
28829
28830A new package @code{System.Multiprocessors} is added, together with the
28831definition of pragma @code{CPU} for controlling task affinity. A new no
28832dependence restriction, on @code{System.Multiprocessors.Dispatching_Domains},
28833is added to the Ravenscar profile.
28834
28835RM References:  D.13.01 (4/2)   D.16
28836@end itemize
28837
28838@geindex AI-0210 (Ada 2012 feature)
28839
28840
28841@itemize *
28842
28843@item
28844@emph{AI-0210 Correct Timing_Events metric (0000-00-00)}
28845
28846This is a documentation only issue regarding wording of metric requirements,
28847that does not affect the implementation of the compiler.
28848
28849RM References:  D.15 (24/2)
28850@end itemize
28851
28852@geindex AI-0206 (Ada 2012 feature)
28853
28854
28855@itemize *
28856
28857@item
28858@emph{AI-0206 Remote types packages and preelaborate (2010-07-24)}
28859
28860Remote types packages are now allowed to depend on preelaborated packages.
28861This was formerly considered illegal.
28862
28863RM References:  E.02.02 (6)
28864@end itemize
28865
28866@geindex AI-0152 (Ada 2012 feature)
28867
28868
28869@itemize *
28870
28871@item
28872@emph{AI-0152 Restriction No_Anonymous_Allocators (2010-09-08)}
28873
28874Restriction @code{No_Anonymous_Allocators} prevents the use of allocators
28875where the type of the returned value is an anonymous access type.
28876
28877RM References:  H.04 (8/1)
28878@end itemize
28879
28880@node Security Hardening Features,Obsolescent Features,Implementation of Ada 2012 Features,Top
28881@anchor{gnat_rm/security_hardening_features doc}@anchor{43b}@anchor{gnat_rm/security_hardening_features id1}@anchor{43c}@anchor{gnat_rm/security_hardening_features security-hardening-features}@anchor{15}
28882@chapter Security Hardening Features
28883
28884
28885This chapter describes Ada extensions aimed at security hardening that
28886are provided by GNAT.
28887
28888@c Register Scrubbing:
28889
28890@menu
28891* Register Scrubbing::
28892* Stack Scrubbing::
28893* Hardened Conditionals::
28894
28895@end menu
28896
28897@node Register Scrubbing,Stack Scrubbing,,Security Hardening Features
28898@anchor{gnat_rm/security_hardening_features register-scrubbing}@anchor{43d}
28899@section Register Scrubbing
28900
28901
28902GNAT can generate code to zero-out hardware registers before returning
28903from a subprogram.
28904
28905It can be enabled with the @emph{-fzero-call-used-regs} command line
28906option, to affect all subprograms in a compilation, and with a
28907@code{Machine_Attribute} pragma, to affect only specific subprograms.
28908
28909@example
28910procedure Foo;
28911pragma Machine_Attribute (Foo, "zero_call_used_regs", "used");
28912--  Before returning, Foo scrubs only call-clobbered registers
28913--  that it uses itself.
28914
28915function Bar return Integer;
28916pragma Machine_Attribute (Bar, "zero_call_used_regs", "all");
28917--  Before returning, Bar scrubs all call-clobbered registers.
28918@end example
28919
28920For usage and more details on the command line option, and on the
28921@code{zero_call_used_regs} attribute, see @cite{Using the GNU Compiler Collection (GCC)}.
28922
28923@c Stack Scrubbing:
28924
28925@node Stack Scrubbing,Hardened Conditionals,Register Scrubbing,Security Hardening Features
28926@anchor{gnat_rm/security_hardening_features stack-scrubbing}@anchor{43e}
28927@section Stack Scrubbing
28928
28929
28930GNAT can generate code to zero-out stack frames used by subprograms.
28931
28932It can be activated with the @code{Machine_Attribute} pragma, on
28933specific subprograms and variables.
28934
28935@example
28936function Foo returns Integer;
28937pragma Machine_Attribute (Foo, "strub");
28938--  Foo and its callers are modified so as to scrub the stack
28939--  space used by Foo after it returns.
28940
28941procedure Bar;
28942pragma Machine_Attribute (Bar, "strub", "internal");
28943--  Bar is turned into a wrapper for its original body,
28944--  and they scrub the stack used by the original body.
28945
28946Var : Integer;
28947pragma Machine_Attribute (Var, "strub");
28948--  Reading from Var in a subprogram enables stack scrubbing
28949--  of the stack space used by the subprogram.
28950@end example
28951
28952There are also @emph{-fstrub} command line options to control default
28953settings.  For usage and more details on the command line option, and
28954on the @code{strub} attribute, see @cite{Using the GNU Compiler Collection (GCC)}.
28955
28956Note that Ada secondary stacks are not scrubbed.  The restriction
28957@code{No_Secondary_Stack} avoids their use, and thus their accidental
28958preservation of data that should be scrubbed.
28959
28960Attributes @code{Access} and @code{Unconstrained_Access} of variables and
28961constants with @code{strub} enabled require types with @code{strub} enabled;
28962there is no way to express an access-to-strub type otherwise.
28963@code{Unchecked_Access} bypasses this constraint, but the resulting
28964access type designates a non-strub type.
28965
28966@example
28967VI : Integer;
28968XsVI : access Integer := VI'Access; -- Error.
28969UXsVI : access Integer := VI'Unchecked_Access; -- OK,
28970-- UXsVI.all does not enable strub in the enclosing subprogram.
28971
28972type Strub_Int is new Integer;
28973pragma Machine_Attribute (Strub_Int, "strub");
28974VSI : Strub_Int;
28975XsVSI : access Strub_Int := VSI'Access; -- OK.
28976-- XsVSI.all enables strub in the enclosing subprogram.
28977@end example
28978
28979Every access-to-subprogram type, renaming, and overriding and
28980overridden dispatching operations that may refer to a subprogram with
28981an attribute-modified interface must be annotated with the same
28982interface-modifying attribute.  Access-to-subprogram types can be
28983explicitly converted to different strub modes, as long as they are
28984interface-compatible (i.e., adding or removing @code{at-calls} is not
28985allowed).  For example, a @code{strub}-@code{disabled} subprogram can be
28986turned @code{callable} through such an explicit conversion:
28987
28988@example
28989type TBar is access procedure;
28990
28991type TBar_Callable is access procedure;
28992pragma Machine_Attribute (TBar_Callable, "strub", "callable");
28993
28994Bar_Callable_Ptr : constant TBar_Callable
28995           := TBar_Callable (TBar'(Bar'Access));
28996
28997procedure Bar_Callable renames Bar_Callable_Ptr.all;
28998pragma Machine_Attribute (Bar_Callable, "strub", "callable");
28999@end example
29000
29001Note that the renaming declaration is expanded to a full subprogram
29002body, it won’t be just an alias.  Only if it is inlined will it be as
29003efficient as a call by dereferencing the access-to-subprogram constant
29004Bar_Callable_Ptr.
29005
29006@c Hardened Conditionals:
29007
29008@node Hardened Conditionals,,Stack Scrubbing,Security Hardening Features
29009@anchor{gnat_rm/security_hardening_features hardened-conditionals}@anchor{43f}
29010@section Hardened Conditionals
29011
29012
29013GNAT can harden conditionals to protect against control flow attacks.
29014
29015This is accomplished by two complementary transformations, each
29016activated by a separate command-line option.
29017
29018The option @emph{-fharden-compares} enables hardening of compares that
29019compute results stored in variables, adding verification that the
29020reversed compare yields the opposite result.
29021
29022The option @emph{-fharden-conditional-branches} enables hardening of
29023compares that guard conditional branches, adding verification of the
29024reversed compare to both execution paths.
29025
29026These transformations are introduced late in the compilation pipeline,
29027long after boolean expressions are decomposed into separate compares,
29028each one turned into either a conditional branch or a compare whose
29029result is stored in a boolean variable or temporary.  Compiler
29030optimizations, if enabled, may also turn conditional branches into
29031stored compares, and vice-versa, or into operations with implied
29032conditionals (e.g. MIN and MAX).  Conditionals may also be optimized
29033out entirely, if their value can be determined at compile time, and
29034occasionally multiple compares can be combined into one.
29035
29036It is thus difficult to predict which of these two options will affect
29037a specific compare operation expressed in source code.  Using both
29038options ensures that every compare that is neither optimized out nor
29039optimized into implied conditionals will be hardened.
29040
29041The addition of reversed compares can be observed by enabling the dump
29042files of the corresponding passes, through command line options
29043@emph{-fdump-tree-hardcmp} and @emph{-fdump-tree-hardcbr}, respectively.
29044
29045They are separate options, however, because of the significantly
29046different performance impact of the hardening transformations.
29047
29048@node Obsolescent Features,Compatibility and Porting Guide,Security Hardening Features,Top
29049@anchor{gnat_rm/obsolescent_features doc}@anchor{440}@anchor{gnat_rm/obsolescent_features id1}@anchor{441}@anchor{gnat_rm/obsolescent_features obsolescent-features}@anchor{16}
29050@chapter Obsolescent Features
29051
29052
29053This chapter describes features that are provided by GNAT, but are
29054considered obsolescent since there are preferred ways of achieving
29055the same effect. These features are provided solely for historical
29056compatibility purposes.
29057
29058@menu
29059* pragma No_Run_Time::
29060* pragma Ravenscar::
29061* pragma Restricted_Run_Time::
29062* pragma Task_Info::
29063* package System.Task_Info (s-tasinf.ads): package System Task_Info s-tasinf ads.
29064
29065@end menu
29066
29067@node pragma No_Run_Time,pragma Ravenscar,,Obsolescent Features
29068@anchor{gnat_rm/obsolescent_features id2}@anchor{442}@anchor{gnat_rm/obsolescent_features pragma-no-run-time}@anchor{443}
29069@section pragma No_Run_Time
29070
29071
29072The pragma @code{No_Run_Time} is used to achieve an affect similar
29073to the use of the “Zero Foot Print” configurable run time, but without
29074requiring a specially configured run time. The result of using this
29075pragma, which must be used for all units in a partition, is to restrict
29076the use of any language features requiring run-time support code. The
29077preferred usage is to use an appropriately configured run-time that
29078includes just those features that are to be made accessible.
29079
29080@node pragma Ravenscar,pragma Restricted_Run_Time,pragma No_Run_Time,Obsolescent Features
29081@anchor{gnat_rm/obsolescent_features id3}@anchor{444}@anchor{gnat_rm/obsolescent_features pragma-ravenscar}@anchor{445}
29082@section pragma Ravenscar
29083
29084
29085The pragma @code{Ravenscar} has exactly the same effect as pragma
29086@code{Profile (Ravenscar)}. The latter usage is preferred since it
29087is part of the new Ada 2005 standard.
29088
29089@node pragma Restricted_Run_Time,pragma Task_Info,pragma Ravenscar,Obsolescent Features
29090@anchor{gnat_rm/obsolescent_features id4}@anchor{446}@anchor{gnat_rm/obsolescent_features pragma-restricted-run-time}@anchor{447}
29091@section pragma Restricted_Run_Time
29092
29093
29094The pragma @code{Restricted_Run_Time} has exactly the same effect as
29095pragma @code{Profile (Restricted)}. The latter usage is
29096preferred since the Ada 2005 pragma @code{Profile} is intended for
29097this kind of implementation dependent addition.
29098
29099@node pragma Task_Info,package System Task_Info s-tasinf ads,pragma Restricted_Run_Time,Obsolescent Features
29100@anchor{gnat_rm/obsolescent_features id5}@anchor{448}@anchor{gnat_rm/obsolescent_features pragma-task-info}@anchor{449}
29101@section pragma Task_Info
29102
29103
29104The functionality provided by pragma @code{Task_Info} is now part of the
29105Ada language. The @code{CPU} aspect and the package
29106@code{System.Multiprocessors} offer a less system-dependent way to specify
29107task affinity or to query the number of processors.
29108
29109Syntax
29110
29111@example
29112pragma Task_Info (EXPRESSION);
29113@end example
29114
29115This pragma appears within a task definition (like pragma
29116@code{Priority}) and applies to the task in which it appears.  The
29117argument must be of type @code{System.Task_Info.Task_Info_Type}.
29118The @code{Task_Info} pragma provides system dependent control over
29119aspects of tasking implementation, for example, the ability to map
29120tasks to specific processors.  For details on the facilities available
29121for the version of GNAT that you are using, see the documentation
29122in the spec of package System.Task_Info in the runtime
29123library.
29124
29125@node package System Task_Info s-tasinf ads,,pragma Task_Info,Obsolescent Features
29126@anchor{gnat_rm/obsolescent_features package-system-task-info}@anchor{44a}@anchor{gnat_rm/obsolescent_features package-system-task-info-s-tasinf-ads}@anchor{44b}
29127@section package System.Task_Info (@code{s-tasinf.ads})
29128
29129
29130This package provides target dependent functionality that is used
29131to support the @code{Task_Info} pragma. The predefined Ada package
29132@code{System.Multiprocessors} and the @code{CPU} aspect now provide a
29133standard replacement for GNAT’s @code{Task_Info} functionality.
29134
29135@node Compatibility and Porting Guide,GNU Free Documentation License,Obsolescent Features,Top
29136@anchor{gnat_rm/compatibility_and_porting_guide doc}@anchor{44c}@anchor{gnat_rm/compatibility_and_porting_guide compatibility-and-porting-guide}@anchor{17}@anchor{gnat_rm/compatibility_and_porting_guide id1}@anchor{44d}
29137@chapter Compatibility and Porting Guide
29138
29139
29140This chapter presents some guidelines for developing portable Ada code,
29141describes the compatibility issues that may arise between
29142GNAT and other Ada compilation systems (including those for Ada 83),
29143and shows how GNAT can expedite porting
29144applications developed in other Ada environments.
29145
29146@menu
29147* Writing Portable Fixed-Point Declarations::
29148* Compatibility with Ada 83::
29149* Compatibility between Ada 95 and Ada 2005::
29150* Implementation-dependent characteristics::
29151* Compatibility with Other Ada Systems::
29152* Representation Clauses::
29153* Compatibility with HP Ada 83::
29154
29155@end menu
29156
29157@node Writing Portable Fixed-Point Declarations,Compatibility with Ada 83,,Compatibility and Porting Guide
29158@anchor{gnat_rm/compatibility_and_porting_guide id2}@anchor{44e}@anchor{gnat_rm/compatibility_and_porting_guide writing-portable-fixed-point-declarations}@anchor{44f}
29159@section Writing Portable Fixed-Point Declarations
29160
29161
29162The Ada Reference Manual gives an implementation freedom to choose bounds
29163that are narrower by @code{Small} from the given bounds.
29164For example, if we write
29165
29166@example
29167type F1 is delta 1.0 range -128.0 .. +128.0;
29168@end example
29169
29170then the implementation is allowed to choose -128.0 .. +127.0 if it
29171likes, but is not required to do so.
29172
29173This leads to possible portability problems, so let’s have a closer
29174look at this, and figure out how to avoid these problems.
29175
29176First, why does this freedom exist, and why would an implementation
29177take advantage of it? To answer this, take a closer look at the type
29178declaration for @code{F1} above. If the compiler uses the given bounds,
29179it would need 9 bits to hold the largest positive value (and typically
29180that means 16 bits on all machines). But if the implementation chooses
29181the +127.0 bound then it can fit values of the type in 8 bits.
29182
29183Why not make the user write +127.0 if that’s what is wanted?
29184The rationale is that if you are thinking of fixed point
29185as a kind of ‘poor man’s floating-point’, then you don’t want
29186to be thinking about the scaled integers that are used in its
29187representation. Let’s take another example:
29188
29189@example
29190type F2 is delta 2.0**(-15) range -1.0 .. +1.0;
29191@end example
29192
29193Looking at this declaration, it seems casually as though
29194it should fit in 16 bits, but again that extra positive value
29195+1.0 has the scaled integer equivalent of 2**15 which is one too
29196big for signed 16 bits. The implementation can treat this as:
29197
29198@example
29199type F2 is delta 2.0**(-15) range -1.0 .. +1.0-(2.0**(-15));
29200@end example
29201
29202and the Ada language design team felt that this was too annoying
29203to require. We don’t need to debate this decision at this point,
29204since it is well established (the rule about narrowing the ranges
29205dates to Ada 83).
29206
29207But the important point is that an implementation is not required
29208to do this narrowing, so we have a potential portability problem.
29209We could imagine three types of implementation:
29210
29211
29212@enumerate a
29213
29214@item
29215those that narrow the range automatically if they can figure
29216out that the narrower range will allow storage in a smaller machine unit,
29217
29218@item
29219those that will narrow only if forced to by a @code{'Size} clause, and
29220
29221@item
29222those that will never narrow.
29223@end enumerate
29224
29225Now if we are language theoreticians, we can imagine a fourth
29226approach: to narrow all the time, e.g. to treat
29227
29228@example
29229type F3 is delta 1.0 range -10.0 .. +23.0;
29230@end example
29231
29232as though it had been written:
29233
29234@example
29235type F3 is delta 1.0 range -9.0 .. +22.0;
29236@end example
29237
29238But although technically allowed, such a behavior would be hostile and silly,
29239and no real compiler would do this. All real compilers will fall into one of
29240the categories (a), (b) or (c) above.
29241
29242So, how do you get the compiler to do what you want? The answer is give the
29243actual bounds you want, and then use a @code{'Small} clause and a
29244@code{'Size} clause to absolutely pin down what the compiler does.
29245E.g., for @code{F2} above, we will write:
29246
29247@example
29248My_Small : constant := 2.0**(-15);
29249My_First : constant := -1.0;
29250My_Last  : constant := +1.0 - My_Small;
29251
29252type F2 is delta My_Small range My_First .. My_Last;
29253@end example
29254
29255and then add
29256
29257@example
29258for F2'Small use my_Small;
29259for F2'Size  use 16;
29260@end example
29261
29262In practice all compilers will do the same thing here and will give you
29263what you want, so the above declarations are fully portable. If you really
29264want to play language lawyer and guard against ludicrous behavior by the
29265compiler you could add
29266
29267@example
29268Test1 : constant := 1 / Boolean'Pos (F2'First = My_First);
29269Test2 : constant := 1 / Boolean'Pos (F2'Last  = My_Last);
29270@end example
29271
29272One or other or both are allowed to be illegal if the compiler is
29273behaving in a silly manner, but at least the silly compiler will not
29274get away with silently messing with your (very clear) intentions.
29275
29276If you follow this scheme you will be guaranteed that your fixed-point
29277types will be portable.
29278
29279@node Compatibility with Ada 83,Compatibility between Ada 95 and Ada 2005,Writing Portable Fixed-Point Declarations,Compatibility and Porting Guide
29280@anchor{gnat_rm/compatibility_and_porting_guide compatibility-with-ada-83}@anchor{450}@anchor{gnat_rm/compatibility_and_porting_guide id3}@anchor{451}
29281@section Compatibility with Ada 83
29282
29283
29284@geindex Compatibility (between Ada 83 and Ada 95 / Ada 2005 / Ada 2012)
29285
29286Ada 95 and the subsequent revisions Ada 2005 and Ada 2012
29287are highly upwards compatible with Ada 83.  In
29288particular, the design intention was that the difficulties associated
29289with moving from Ada 83 to later versions of the standard should be no greater
29290than those that occur when moving from one Ada 83 system to another.
29291
29292However, there are a number of points at which there are minor
29293incompatibilities.  The @cite{Ada 95 Annotated Reference Manual} contains
29294full details of these issues as they relate to Ada 95,
29295and should be consulted for a complete treatment.
29296In practice the
29297following subsections treat the most likely issues to be encountered.
29298
29299@menu
29300* Legal Ada 83 programs that are illegal in Ada 95::
29301* More deterministic semantics::
29302* Changed semantics::
29303* Other language compatibility issues::
29304
29305@end menu
29306
29307@node Legal Ada 83 programs that are illegal in Ada 95,More deterministic semantics,,Compatibility with Ada 83
29308@anchor{gnat_rm/compatibility_and_porting_guide id4}@anchor{452}@anchor{gnat_rm/compatibility_and_porting_guide legal-ada-83-programs-that-are-illegal-in-ada-95}@anchor{453}
29309@subsection Legal Ada 83 programs that are illegal in Ada 95
29310
29311
29312Some legal Ada 83 programs are illegal (i.e., they will fail to compile) in
29313Ada 95 and later versions of the standard:
29314
29315
29316@itemize *
29317
29318@item
29319@emph{Character literals}
29320
29321Some uses of character literals are ambiguous.  Since Ada 95 has introduced
29322@code{Wide_Character} as a new predefined character type, some uses of
29323character literals that were legal in Ada 83 are illegal in Ada 95.
29324For example:
29325
29326@example
29327for Char in 'A' .. 'Z' loop ... end loop;
29328@end example
29329
29330The problem is that ‘A’ and ‘Z’ could be from either
29331@code{Character} or @code{Wide_Character}.  The simplest correction
29332is to make the type explicit; e.g.:
29333
29334@example
29335for Char in Character range 'A' .. 'Z' loop ... end loop;
29336@end example
29337
29338@item
29339@emph{New reserved words}
29340
29341The identifiers @code{abstract}, @code{aliased}, @code{protected},
29342@code{requeue}, @code{tagged}, and @code{until} are reserved in Ada 95.
29343Existing Ada 83 code using any of these identifiers must be edited to
29344use some alternative name.
29345
29346@item
29347@emph{Freezing rules}
29348
29349The rules in Ada 95 are slightly different with regard to the point at
29350which entities are frozen, and representation pragmas and clauses are
29351not permitted past the freeze point.  This shows up most typically in
29352the form of an error message complaining that a representation item
29353appears too late, and the appropriate corrective action is to move
29354the item nearer to the declaration of the entity to which it refers.
29355
29356A particular case is that representation pragmas
29357cannot be applied to a subprogram body.  If necessary, a separate subprogram
29358declaration must be introduced to which the pragma can be applied.
29359
29360@item
29361@emph{Optional bodies for library packages}
29362
29363In Ada 83, a package that did not require a package body was nevertheless
29364allowed to have one.  This lead to certain surprises in compiling large
29365systems (situations in which the body could be unexpectedly ignored by the
29366binder).  In Ada 95, if a package does not require a body then it is not
29367permitted to have a body.  To fix this problem, simply remove a redundant
29368body if it is empty, or, if it is non-empty, introduce a dummy declaration
29369into the spec that makes the body required.  One approach is to add a private
29370part to the package declaration (if necessary), and define a parameterless
29371procedure called @code{Requires_Body}, which must then be given a dummy
29372procedure body in the package body, which then becomes required.
29373Another approach (assuming that this does not introduce elaboration
29374circularities) is to add an @code{Elaborate_Body} pragma to the package spec,
29375since one effect of this pragma is to require the presence of a package body.
29376
29377@item
29378@emph{Numeric_Error is the same exception as Constraint_Error}
29379
29380In Ada 95, the exception @code{Numeric_Error} is a renaming of @code{Constraint_Error}.
29381This means that it is illegal to have separate exception handlers for
29382the two exceptions.  The fix is simply to remove the handler for the
29383@code{Numeric_Error} case (since even in Ada 83, a compiler was free to raise
29384@code{Constraint_Error} in place of @code{Numeric_Error} in all cases).
29385
29386@item
29387@emph{Indefinite subtypes in generics}
29388
29389In Ada 83, it was permissible to pass an indefinite type (e.g, @code{String})
29390as the actual for a generic formal private type, but then the instantiation
29391would be illegal if there were any instances of declarations of variables
29392of this type in the generic body.  In Ada 95, to avoid this clear violation
29393of the methodological principle known as the ‘contract model’,
29394the generic declaration explicitly indicates whether
29395or not such instantiations are permitted.  If a generic formal parameter
29396has explicit unknown discriminants, indicated by using @code{(<>)} after the
29397subtype name, then it can be instantiated with indefinite types, but no
29398stand-alone variables can be declared of this type.  Any attempt to declare
29399such a variable will result in an illegality at the time the generic is
29400declared.  If the @code{(<>)} notation is not used, then it is illegal
29401to instantiate the generic with an indefinite type.
29402This is the potential incompatibility issue when porting Ada 83 code to Ada 95.
29403It will show up as a compile time error, and
29404the fix is usually simply to add the @code{(<>)} to the generic declaration.
29405@end itemize
29406
29407@node More deterministic semantics,Changed semantics,Legal Ada 83 programs that are illegal in Ada 95,Compatibility with Ada 83
29408@anchor{gnat_rm/compatibility_and_porting_guide id5}@anchor{454}@anchor{gnat_rm/compatibility_and_porting_guide more-deterministic-semantics}@anchor{455}
29409@subsection More deterministic semantics
29410
29411
29412
29413@itemize *
29414
29415@item
29416@emph{Conversions}
29417
29418Conversions from real types to integer types round away from 0.  In Ada 83
29419the conversion Integer(2.5) could deliver either 2 or 3 as its value.  This
29420implementation freedom was intended to support unbiased rounding in
29421statistical applications, but in practice it interfered with portability.
29422In Ada 95 the conversion semantics are unambiguous, and rounding away from 0
29423is required.  Numeric code may be affected by this change in semantics.
29424Note, though, that this issue is no worse than already existed in Ada 83
29425when porting code from one vendor to another.
29426
29427@item
29428@emph{Tasking}
29429
29430The Real-Time Annex introduces a set of policies that define the behavior of
29431features that were implementation dependent in Ada 83, such as the order in
29432which open select branches are executed.
29433@end itemize
29434
29435@node Changed semantics,Other language compatibility issues,More deterministic semantics,Compatibility with Ada 83
29436@anchor{gnat_rm/compatibility_and_porting_guide changed-semantics}@anchor{456}@anchor{gnat_rm/compatibility_and_porting_guide id6}@anchor{457}
29437@subsection Changed semantics
29438
29439
29440The worst kind of incompatibility is one where a program that is legal in
29441Ada 83 is also legal in Ada 95 but can have an effect in Ada 95 that was not
29442possible in Ada 83.  Fortunately this is extremely rare, but the one
29443situation that you should be alert to is the change in the predefined type
29444@code{Character} from 7-bit ASCII to 8-bit Latin-1.
29445
29446@quotation
29447
29448@geindex Latin-1
29449@end quotation
29450
29451
29452@itemize *
29453
29454@item
29455@emph{Range of type `@w{`}Character`@w{`}}
29456
29457The range of @code{Standard.Character} is now the full 256 characters
29458of Latin-1, whereas in most Ada 83 implementations it was restricted
29459to 128 characters. Although some of the effects of
29460this change will be manifest in compile-time rejection of legal
29461Ada 83 programs it is possible for a working Ada 83 program to have
29462a different effect in Ada 95, one that was not permitted in Ada 83.
29463As an example, the expression
29464@code{Character'Pos(Character'Last)} returned @code{127} in Ada 83 and now
29465delivers @code{255} as its value.
29466In general, you should look at the logic of any
29467character-processing Ada 83 program and see whether it needs to be adapted
29468to work correctly with Latin-1.  Note that the predefined Ada 95 API has a
29469character handling package that may be relevant if code needs to be adapted
29470to account for the additional Latin-1 elements.
29471The desirable fix is to
29472modify the program to accommodate the full character set, but in some cases
29473it may be convenient to define a subtype or derived type of Character that
29474covers only the restricted range.
29475@end itemize
29476
29477@node Other language compatibility issues,,Changed semantics,Compatibility with Ada 83
29478@anchor{gnat_rm/compatibility_and_porting_guide id7}@anchor{458}@anchor{gnat_rm/compatibility_and_porting_guide other-language-compatibility-issues}@anchor{459}
29479@subsection Other language compatibility issues
29480
29481
29482
29483@itemize *
29484
29485@item
29486@emph{-gnat83} switch
29487
29488All implementations of GNAT provide a switch that causes GNAT to operate
29489in Ada 83 mode.  In this mode, some but not all compatibility problems
29490of the type described above are handled automatically.  For example, the
29491new reserved words introduced in Ada 95 and Ada 2005 are treated simply
29492as identifiers as in Ada 83.  However,
29493in practice, it is usually advisable to make the necessary modifications
29494to the program to remove the need for using this switch.
29495See the @code{Compiling Different Versions of Ada} section in
29496the @cite{GNAT User’s Guide}.
29497
29498@item
29499Support for removed Ada 83 pragmas and attributes
29500
29501A number of pragmas and attributes from Ada 83 were removed from Ada 95,
29502generally because they were replaced by other mechanisms.  Ada 95 and Ada 2005
29503compilers are allowed, but not required, to implement these missing
29504elements.  In contrast with some other compilers, GNAT implements all
29505such pragmas and attributes, eliminating this compatibility concern.  These
29506include @code{pragma Interface} and the floating point type attributes
29507(@code{Emax}, @code{Mantissa}, etc.), among other items.
29508@end itemize
29509
29510@node Compatibility between Ada 95 and Ada 2005,Implementation-dependent characteristics,Compatibility with Ada 83,Compatibility and Porting Guide
29511@anchor{gnat_rm/compatibility_and_porting_guide compatibility-between-ada-95-and-ada-2005}@anchor{45a}@anchor{gnat_rm/compatibility_and_porting_guide id8}@anchor{45b}
29512@section Compatibility between Ada 95 and Ada 2005
29513
29514
29515@geindex Compatibility between Ada 95 and Ada 2005
29516
29517Although Ada 2005 was designed to be upwards compatible with Ada 95, there are
29518a number of incompatibilities. Several are enumerated below;
29519for a complete description please see the
29520@cite{Annotated Ada 2005 Reference Manual}, or section 9.1.1 in
29521@cite{Rationale for Ada 2005}.
29522
29523
29524@itemize *
29525
29526@item
29527@emph{New reserved words.}
29528
29529The words @code{interface}, @code{overriding} and @code{synchronized} are
29530reserved in Ada 2005.
29531A pre-Ada 2005 program that uses any of these as an identifier will be
29532illegal.
29533
29534@item
29535@emph{New declarations in predefined packages.}
29536
29537A number of packages in the predefined environment contain new declarations:
29538@code{Ada.Exceptions}, @code{Ada.Real_Time}, @code{Ada.Strings},
29539@code{Ada.Strings.Fixed}, @code{Ada.Strings.Bounded},
29540@code{Ada.Strings.Unbounded}, @code{Ada.Strings.Wide_Fixed},
29541@code{Ada.Strings.Wide_Bounded}, @code{Ada.Strings.Wide_Unbounded},
29542@code{Ada.Tags}, @code{Ada.Text_IO}, and @code{Interfaces.C}.
29543If an Ada 95 program does a @code{with} and @code{use} of any of these
29544packages, the new declarations may cause name clashes.
29545
29546@item
29547@emph{Access parameters.}
29548
29549A nondispatching subprogram with an access parameter cannot be renamed
29550as a dispatching operation.  This was permitted in Ada 95.
29551
29552@item
29553@emph{Access types, discriminants, and constraints.}
29554
29555Rule changes in this area have led to some incompatibilities; for example,
29556constrained subtypes of some access types are not permitted in Ada 2005.
29557
29558@item
29559@emph{Aggregates for limited types.}
29560
29561The allowance of aggregates for limited types in Ada 2005 raises the
29562possibility of ambiguities in legal Ada 95 programs, since additional types
29563now need to be considered in expression resolution.
29564
29565@item
29566@emph{Fixed-point multiplication and division.}
29567
29568Certain expressions involving ‘*’ or ‘/’ for a fixed-point type, which
29569were legal in Ada 95 and invoked the predefined versions of these operations,
29570are now ambiguous.
29571The ambiguity may be resolved either by applying a type conversion to the
29572expression, or by explicitly invoking the operation from package
29573@code{Standard}.
29574
29575@item
29576@emph{Return-by-reference types.}
29577
29578The Ada 95 return-by-reference mechanism has been removed.  Instead, the user
29579can declare a function returning a value from an anonymous access type.
29580@end itemize
29581
29582@node Implementation-dependent characteristics,Compatibility with Other Ada Systems,Compatibility between Ada 95 and Ada 2005,Compatibility and Porting Guide
29583@anchor{gnat_rm/compatibility_and_porting_guide id9}@anchor{45c}@anchor{gnat_rm/compatibility_and_porting_guide implementation-dependent-characteristics}@anchor{45d}
29584@section Implementation-dependent characteristics
29585
29586
29587Although the Ada language defines the semantics of each construct as
29588precisely as practical, in some situations (for example for reasons of
29589efficiency, or where the effect is heavily dependent on the host or target
29590platform) the implementation is allowed some freedom.  In porting Ada 83
29591code to GNAT, you need to be aware of whether / how the existing code
29592exercised such implementation dependencies.  Such characteristics fall into
29593several categories, and GNAT offers specific support in assisting the
29594transition from certain Ada 83 compilers.
29595
29596@menu
29597* Implementation-defined pragmas::
29598* Implementation-defined attributes::
29599* Libraries::
29600* Elaboration order::
29601* Target-specific aspects::
29602
29603@end menu
29604
29605@node Implementation-defined pragmas,Implementation-defined attributes,,Implementation-dependent characteristics
29606@anchor{gnat_rm/compatibility_and_porting_guide id10}@anchor{45e}@anchor{gnat_rm/compatibility_and_porting_guide implementation-defined-pragmas}@anchor{45f}
29607@subsection Implementation-defined pragmas
29608
29609
29610Ada compilers are allowed to supplement the language-defined pragmas, and
29611these are a potential source of non-portability.  All GNAT-defined pragmas
29612are described in @ref{7,,Implementation Defined Pragmas},
29613and these include several that are specifically
29614intended to correspond to other vendors’ Ada 83 pragmas.
29615For migrating from VADS, the pragma @code{Use_VADS_Size} may be useful.
29616For compatibility with HP Ada 83, GNAT supplies the pragmas
29617@code{Extend_System}, @code{Ident}, @code{Inline_Generic},
29618@code{Interface_Name}, @code{Passive}, @code{Suppress_All},
29619and @code{Volatile}.
29620Other relevant pragmas include @code{External} and @code{Link_With}.
29621Some vendor-specific
29622Ada 83 pragmas (@code{Share_Generic}, @code{Subtitle}, and @code{Title}) are
29623recognized, thus
29624avoiding compiler rejection of units that contain such pragmas; they are not
29625relevant in a GNAT context and hence are not otherwise implemented.
29626
29627@node Implementation-defined attributes,Libraries,Implementation-defined pragmas,Implementation-dependent characteristics
29628@anchor{gnat_rm/compatibility_and_porting_guide id11}@anchor{460}@anchor{gnat_rm/compatibility_and_porting_guide implementation-defined-attributes}@anchor{461}
29629@subsection Implementation-defined attributes
29630
29631
29632Analogous to pragmas, the set of attributes may be extended by an
29633implementation.  All GNAT-defined attributes are described in
29634@ref{8,,Implementation Defined Attributes},
29635and these include several that are specifically intended
29636to correspond to other vendors’ Ada 83 attributes.  For migrating from VADS,
29637the attribute @code{VADS_Size} may be useful.  For compatibility with HP
29638Ada 83, GNAT supplies the attributes @code{Bit}, @code{Machine_Size} and
29639@code{Type_Class}.
29640
29641@node Libraries,Elaboration order,Implementation-defined attributes,Implementation-dependent characteristics
29642@anchor{gnat_rm/compatibility_and_porting_guide id12}@anchor{462}@anchor{gnat_rm/compatibility_and_porting_guide libraries}@anchor{463}
29643@subsection Libraries
29644
29645
29646Vendors may supply libraries to supplement the standard Ada API.  If Ada 83
29647code uses vendor-specific libraries then there are several ways to manage
29648this in Ada 95 and later versions of the standard:
29649
29650
29651@itemize *
29652
29653@item
29654If the source code for the libraries (specs and bodies) are
29655available, then the libraries can be migrated in the same way as the
29656application.
29657
29658@item
29659If the source code for the specs but not the bodies are
29660available, then you can reimplement the bodies.
29661
29662@item
29663Some features introduced by Ada 95 obviate the need for library support.  For
29664example most Ada 83 vendors supplied a package for unsigned integers.  The
29665Ada 95 modular type feature is the preferred way to handle this need, so
29666instead of migrating or reimplementing the unsigned integer package it may
29667be preferable to retrofit the application using modular types.
29668@end itemize
29669
29670@node Elaboration order,Target-specific aspects,Libraries,Implementation-dependent characteristics
29671@anchor{gnat_rm/compatibility_and_porting_guide elaboration-order}@anchor{464}@anchor{gnat_rm/compatibility_and_porting_guide id13}@anchor{465}
29672@subsection Elaboration order
29673
29674
29675The implementation can choose any elaboration order consistent with the unit
29676dependency relationship.  This freedom means that some orders can result in
29677Program_Error being raised due to an ‘Access Before Elaboration’: an attempt
29678to invoke a subprogram before its body has been elaborated, or to instantiate
29679a generic before the generic body has been elaborated.  By default GNAT
29680attempts to choose a safe order (one that will not encounter access before
29681elaboration problems) by implicitly inserting @code{Elaborate} or
29682@code{Elaborate_All} pragmas where
29683needed.  However, this can lead to the creation of elaboration circularities
29684and a resulting rejection of the program by gnatbind.  This issue is
29685thoroughly described in the @emph{Elaboration Order Handling in GNAT} appendix
29686in the @cite{GNAT User’s Guide}.
29687In brief, there are several
29688ways to deal with this situation:
29689
29690
29691@itemize *
29692
29693@item
29694Modify the program to eliminate the circularities, e.g., by moving
29695elaboration-time code into explicitly-invoked procedures
29696
29697@item
29698Constrain the elaboration order by including explicit @code{Elaborate_Body} or
29699@code{Elaborate} pragmas, and then inhibit the generation of implicit
29700@code{Elaborate_All}
29701pragmas either globally (as an effect of the @emph{-gnatE} switch) or locally
29702(by selectively suppressing elaboration checks via pragma
29703@code{Suppress(Elaboration_Check)} when it is safe to do so).
29704@end itemize
29705
29706@node Target-specific aspects,,Elaboration order,Implementation-dependent characteristics
29707@anchor{gnat_rm/compatibility_and_porting_guide id14}@anchor{466}@anchor{gnat_rm/compatibility_and_porting_guide target-specific-aspects}@anchor{467}
29708@subsection Target-specific aspects
29709
29710
29711Low-level applications need to deal with machine addresses, data
29712representations, interfacing with assembler code, and similar issues.  If
29713such an Ada 83 application is being ported to different target hardware (for
29714example where the byte endianness has changed) then you will need to
29715carefully examine the program logic; the porting effort will heavily depend
29716on the robustness of the original design.  Moreover, Ada 95 (and thus
29717Ada 2005 and Ada 2012) are sometimes
29718incompatible with typical Ada 83 compiler practices regarding implicit
29719packing, the meaning of the Size attribute, and the size of access values.
29720GNAT’s approach to these issues is described in @ref{468,,Representation Clauses}.
29721
29722@node Compatibility with Other Ada Systems,Representation Clauses,Implementation-dependent characteristics,Compatibility and Porting Guide
29723@anchor{gnat_rm/compatibility_and_porting_guide compatibility-with-other-ada-systems}@anchor{469}@anchor{gnat_rm/compatibility_and_porting_guide id15}@anchor{46a}
29724@section Compatibility with Other Ada Systems
29725
29726
29727If programs avoid the use of implementation dependent and
29728implementation defined features, as documented in the
29729@cite{Ada Reference Manual}, there should be a high degree of portability between
29730GNAT and other Ada systems.  The following are specific items which
29731have proved troublesome in moving Ada 95 programs from GNAT to other Ada 95
29732compilers, but do not affect porting code to GNAT.
29733(As of January 2007, GNAT is the only compiler available for Ada 2005;
29734the following issues may or may not arise for Ada 2005 programs
29735when other compilers appear.)
29736
29737
29738@itemize *
29739
29740@item
29741@emph{Ada 83 Pragmas and Attributes}
29742
29743Ada 95 compilers are allowed, but not required, to implement the missing
29744Ada 83 pragmas and attributes that are no longer defined in Ada 95.
29745GNAT implements all such pragmas and attributes, eliminating this as
29746a compatibility concern, but some other Ada 95 compilers reject these
29747pragmas and attributes.
29748
29749@item
29750@emph{Specialized Needs Annexes}
29751
29752GNAT implements the full set of special needs annexes.  At the
29753current time, it is the only Ada 95 compiler to do so.  This means that
29754programs making use of these features may not be portable to other Ada
2975595 compilation systems.
29756
29757@item
29758@emph{Representation Clauses}
29759
29760Some other Ada 95 compilers implement only the minimal set of
29761representation clauses required by the Ada 95 reference manual.  GNAT goes
29762far beyond this minimal set, as described in the next section.
29763@end itemize
29764
29765@node Representation Clauses,Compatibility with HP Ada 83,Compatibility with Other Ada Systems,Compatibility and Porting Guide
29766@anchor{gnat_rm/compatibility_and_porting_guide id16}@anchor{46b}@anchor{gnat_rm/compatibility_and_porting_guide representation-clauses}@anchor{468}
29767@section Representation Clauses
29768
29769
29770The Ada 83 reference manual was quite vague in describing both the minimal
29771required implementation of representation clauses, and also their precise
29772effects.  Ada 95 (and thus also Ada 2005) are much more explicit, but the
29773minimal set of capabilities required is still quite limited.
29774
29775GNAT implements the full required set of capabilities in
29776Ada 95 and Ada 2005, but also goes much further, and in particular
29777an effort has been made to be compatible with existing Ada 83 usage to the
29778greatest extent possible.
29779
29780A few cases exist in which Ada 83 compiler behavior is incompatible with
29781the requirements in Ada 95 (and thus also Ada 2005).  These are instances of
29782intentional or accidental dependence on specific implementation dependent
29783characteristics of these Ada 83 compilers.  The following is a list of
29784the cases most likely to arise in existing Ada 83 code.
29785
29786
29787@itemize *
29788
29789@item
29790@emph{Implicit Packing}
29791
29792Some Ada 83 compilers allowed a Size specification to cause implicit
29793packing of an array or record.  This could cause expensive implicit
29794conversions for change of representation in the presence of derived
29795types, and the Ada design intends to avoid this possibility.
29796Subsequent AI’s were issued to make it clear that such implicit
29797change of representation in response to a Size clause is inadvisable,
29798and this recommendation is represented explicitly in the Ada 95 (and Ada 2005)
29799Reference Manuals as implementation advice that is followed by GNAT.
29800The problem will show up as an error
29801message rejecting the size clause.  The fix is simply to provide
29802the explicit pragma @code{Pack}, or for more fine tuned control, provide
29803a Component_Size clause.
29804
29805@item
29806@emph{Meaning of Size Attribute}
29807
29808The Size attribute in Ada 95 (and Ada 2005) for discrete types is defined as
29809the minimal number of bits required to hold values of the type.  For example,
29810on a 32-bit machine, the size of @code{Natural} will typically be 31 and not
2981132 (since no sign bit is required).  Some Ada 83 compilers gave 31, and
29812some 32 in this situation.  This problem will usually show up as a compile
29813time error, but not always.  It is a good idea to check all uses of the
29814‘Size attribute when porting Ada 83 code.  The GNAT specific attribute
29815Object_Size can provide a useful way of duplicating the behavior of
29816some Ada 83 compiler systems.
29817
29818@item
29819@emph{Size of Access Types}
29820
29821A common assumption in Ada 83 code is that an access type is in fact a pointer,
29822and that therefore it will be the same size as a System.Address value.  This
29823assumption is true for GNAT in most cases with one exception.  For the case of
29824a pointer to an unconstrained array type (where the bounds may vary from one
29825value of the access type to another), the default is to use a ‘fat pointer’,
29826which is represented as two separate pointers, one to the bounds, and one to
29827the array.  This representation has a number of advantages, including improved
29828efficiency.  However, it may cause some difficulties in porting existing Ada 83
29829code which makes the assumption that, for example, pointers fit in 32 bits on
29830a machine with 32-bit addressing.
29831
29832To get around this problem, GNAT also permits the use of ‘thin pointers’ for
29833access types in this case (where the designated type is an unconstrained array
29834type).  These thin pointers are indeed the same size as a System.Address value.
29835To specify a thin pointer, use a size clause for the type, for example:
29836
29837@example
29838type X is access all String;
29839for X'Size use Standard'Address_Size;
29840@end example
29841
29842which will cause the type X to be represented using a single pointer.
29843When using this representation, the bounds are right behind the array.
29844This representation is slightly less efficient, and does not allow quite
29845such flexibility in the use of foreign pointers or in using the
29846Unrestricted_Access attribute to create pointers to non-aliased objects.
29847But for any standard portable use of the access type it will work in
29848a functionally correct manner and allow porting of existing code.
29849Note that another way of forcing a thin pointer representation
29850is to use a component size clause for the element size in an array,
29851or a record representation clause for an access field in a record.
29852
29853See the documentation of Unrestricted_Access in the GNAT RM for a
29854full discussion of possible problems using this attribute in conjunction
29855with thin pointers.
29856@end itemize
29857
29858@node Compatibility with HP Ada 83,,Representation Clauses,Compatibility and Porting Guide
29859@anchor{gnat_rm/compatibility_and_porting_guide compatibility-with-hp-ada-83}@anchor{46c}@anchor{gnat_rm/compatibility_and_porting_guide id17}@anchor{46d}
29860@section Compatibility with HP Ada 83
29861
29862
29863All the HP Ada 83 pragmas and attributes are recognized, although only a subset
29864of them can sensibly be implemented.  The description of pragmas in
29865@ref{7,,Implementation Defined Pragmas} indicates whether or not they are
29866applicable to GNAT.
29867
29868
29869@itemize *
29870
29871@item
29872@emph{Default floating-point representation}
29873
29874In GNAT, the default floating-point format is IEEE, whereas in HP Ada 83,
29875it is VMS format.
29876
29877@item
29878@emph{System}
29879
29880the package System in GNAT exactly corresponds to the definition in the
29881Ada 95 reference manual, which means that it excludes many of the
29882HP Ada 83 extensions.  However, a separate package Aux_DEC is provided
29883that contains the additional definitions, and a special pragma,
29884Extend_System allows this package to be treated transparently as an
29885extension of package System.
29886@end itemize
29887
29888@node GNU Free Documentation License,Index,Compatibility and Porting Guide,Top
29889@anchor{share/gnu_free_documentation_license doc}@anchor{46e}@anchor{share/gnu_free_documentation_license gnu-fdl}@anchor{1}@anchor{share/gnu_free_documentation_license gnu-free-documentation-license}@anchor{46f}
29890@chapter GNU Free Documentation License
29891
29892
29893Version 1.3, 3 November 2008
29894
29895Copyright  2000, 2001, 2002, 2007, 2008  Free Software Foundation, Inc
29896@indicateurl{http://fsf.org/}
29897
29898Everyone is permitted to copy and distribute verbatim copies of this
29899license document, but changing it is not allowed.
29900
29901@strong{Preamble}
29902
29903The purpose of this License is to make a manual, textbook, or other
29904functional and useful document “free” in the sense of freedom: to
29905assure everyone the effective freedom to copy and redistribute it,
29906with or without modifying it, either commercially or noncommercially.
29907Secondarily, this License preserves for the author and publisher a way
29908to get credit for their work, while not being considered responsible
29909for modifications made by others.
29910
29911This License is a kind of “copyleft”, which means that derivative
29912works of the document must themselves be free in the same sense.  It
29913complements the GNU General Public License, which is a copyleft
29914license designed for free software.
29915
29916We have designed this License in order to use it for manuals for free
29917software, because free software needs free documentation: a free
29918program should come with manuals providing the same freedoms that the
29919software does.  But this License is not limited to software manuals;
29920it can be used for any textual work, regardless of subject matter or
29921whether it is published as a printed book.  We recommend this License
29922principally for works whose purpose is instruction or reference.
29923
29924@strong{1. APPLICABILITY AND DEFINITIONS}
29925
29926This License applies to any manual or other work, in any medium, that
29927contains a notice placed by the copyright holder saying it can be
29928distributed under the terms of this License.  Such a notice grants a
29929world-wide, royalty-free license, unlimited in duration, to use that
29930work under the conditions stated herein.  The @strong{Document}, below,
29931refers to any such manual or work.  Any member of the public is a
29932licensee, and is addressed as “@strong{you}”.  You accept the license if you
29933copy, modify or distribute the work in a way requiring permission
29934under copyright law.
29935
29936A “@strong{Modified Version}” of the Document means any work containing the
29937Document or a portion of it, either copied verbatim, or with
29938modifications and/or translated into another language.
29939
29940A “@strong{Secondary Section}” is a named appendix or a front-matter section of
29941the Document that deals exclusively with the relationship of the
29942publishers or authors of the Document to the Document’s overall subject
29943(or to related matters) and contains nothing that could fall directly
29944within that overall subject.  (Thus, if the Document is in part a
29945textbook of mathematics, a Secondary Section may not explain any
29946mathematics.)  The relationship could be a matter of historical
29947connection with the subject or with related matters, or of legal,
29948commercial, philosophical, ethical or political position regarding
29949them.
29950
29951The “@strong{Invariant Sections}” are certain Secondary Sections whose titles
29952are designated, as being those of Invariant Sections, in the notice
29953that says that the Document is released under this License.  If a
29954section does not fit the above definition of Secondary then it is not
29955allowed to be designated as Invariant.  The Document may contain zero
29956Invariant Sections.  If the Document does not identify any Invariant
29957Sections then there are none.
29958
29959The “@strong{Cover Texts}” are certain short passages of text that are listed,
29960as Front-Cover Texts or Back-Cover Texts, in the notice that says that
29961the Document is released under this License.  A Front-Cover Text may
29962be at most 5 words, and a Back-Cover Text may be at most 25 words.
29963
29964A “@strong{Transparent}” copy of the Document means a machine-readable copy,
29965represented in a format whose specification is available to the
29966general public, that is suitable for revising the document
29967straightforwardly with generic text editors or (for images composed of
29968pixels) generic paint programs or (for drawings) some widely available
29969drawing editor, and that is suitable for input to text formatters or
29970for automatic translation to a variety of formats suitable for input
29971to text formatters.  A copy made in an otherwise Transparent file
29972format whose markup, or absence of markup, has been arranged to thwart
29973or discourage subsequent modification by readers is not Transparent.
29974An image format is not Transparent if used for any substantial amount
29975of text.  A copy that is not “Transparent” is called @strong{Opaque}.
29976
29977Examples of suitable formats for Transparent copies include plain
29978ASCII without markup, Texinfo input format, LaTeX input format, SGML
29979or XML using a publicly available DTD, and standard-conforming simple
29980HTML, PostScript or PDF designed for human modification.  Examples of
29981transparent image formats include PNG, XCF and JPG.  Opaque formats
29982include proprietary formats that can be read and edited only by
29983proprietary word processors, SGML or XML for which the DTD and/or
29984processing tools are not generally available, and the
29985machine-generated HTML, PostScript or PDF produced by some word
29986processors for output purposes only.
29987
29988The “@strong{Title Page}” means, for a printed book, the title page itself,
29989plus such following pages as are needed to hold, legibly, the material
29990this License requires to appear in the title page.  For works in
29991formats which do not have any title page as such, “Title Page” means
29992the text near the most prominent appearance of the work’s title,
29993preceding the beginning of the body of the text.
29994
29995The “@strong{publisher}” means any person or entity that distributes
29996copies of the Document to the public.
29997
29998A section “@strong{Entitled XYZ}” means a named subunit of the Document whose
29999title either is precisely XYZ or contains XYZ in parentheses following
30000text that translates XYZ in another language.  (Here XYZ stands for a
30001specific section name mentioned below, such as “@strong{Acknowledgements}”,
30002“@strong{Dedications}”, “@strong{Endorsements}”, or “@strong{History}”.)
30003To “@strong{Preserve the Title}”
30004of such a section when you modify the Document means that it remains a
30005section “Entitled XYZ” according to this definition.
30006
30007The Document may include Warranty Disclaimers next to the notice which
30008states that this License applies to the Document.  These Warranty
30009Disclaimers are considered to be included by reference in this
30010License, but only as regards disclaiming warranties: any other
30011implication that these Warranty Disclaimers may have is void and has
30012no effect on the meaning of this License.
30013
30014@strong{2. VERBATIM COPYING}
30015
30016You may copy and distribute the Document in any medium, either
30017commercially or noncommercially, provided that this License, the
30018copyright notices, and the license notice saying this License applies
30019to the Document are reproduced in all copies, and that you add no other
30020conditions whatsoever to those of this License.  You may not use
30021technical measures to obstruct or control the reading or further
30022copying of the copies you make or distribute.  However, you may accept
30023compensation in exchange for copies.  If you distribute a large enough
30024number of copies you must also follow the conditions in section 3.
30025
30026You may also lend copies, under the same conditions stated above, and
30027you may publicly display copies.
30028
30029@strong{3. COPYING IN QUANTITY}
30030
30031If you publish printed copies (or copies in media that commonly have
30032printed covers) of the Document, numbering more than 100, and the
30033Document’s license notice requires Cover Texts, you must enclose the
30034copies in covers that carry, clearly and legibly, all these Cover
30035Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
30036the back cover.  Both covers must also clearly and legibly identify
30037you as the publisher of these copies.  The front cover must present
30038the full title with all words of the title equally prominent and
30039visible.  You may add other material on the covers in addition.
30040Copying with changes limited to the covers, as long as they preserve
30041the title of the Document and satisfy these conditions, can be treated
30042as verbatim copying in other respects.
30043
30044If the required texts for either cover are too voluminous to fit
30045legibly, you should put the first ones listed (as many as fit
30046reasonably) on the actual cover, and continue the rest onto adjacent
30047pages.
30048
30049If you publish or distribute Opaque copies of the Document numbering
30050more than 100, you must either include a machine-readable Transparent
30051copy along with each Opaque copy, or state in or with each Opaque copy
30052a computer-network location from which the general network-using
30053public has access to download using public-standard network protocols
30054a complete Transparent copy of the Document, free of added material.
30055If you use the latter option, you must take reasonably prudent steps,
30056when you begin distribution of Opaque copies in quantity, to ensure
30057that this Transparent copy will remain thus accessible at the stated
30058location until at least one year after the last time you distribute an
30059Opaque copy (directly or through your agents or retailers) of that
30060edition to the public.
30061
30062It is requested, but not required, that you contact the authors of the
30063Document well before redistributing any large number of copies, to give
30064them a chance to provide you with an updated version of the Document.
30065
30066@strong{4. MODIFICATIONS}
30067
30068You may copy and distribute a Modified Version of the Document under
30069the conditions of sections 2 and 3 above, provided that you release
30070the Modified Version under precisely this License, with the Modified
30071Version filling the role of the Document, thus licensing distribution
30072and modification of the Modified Version to whoever possesses a copy
30073of it.  In addition, you must do these things in the Modified Version:
30074
30075
30076@enumerate A
30077
30078@item
30079Use in the Title Page (and on the covers, if any) a title distinct
30080from that of the Document, and from those of previous versions
30081(which should, if there were any, be listed in the History section
30082of the Document).  You may use the same title as a previous version
30083if the original publisher of that version gives permission.
30084
30085@item
30086List on the Title Page, as authors, one or more persons or entities
30087responsible for authorship of the modifications in the Modified
30088Version, together with at least five of the principal authors of the
30089Document (all of its principal authors, if it has fewer than five),
30090unless they release you from this requirement.
30091
30092@item
30093State on the Title page the name of the publisher of the
30094Modified Version, as the publisher.
30095
30096@item
30097Preserve all the copyright notices of the Document.
30098
30099@item
30100Add an appropriate copyright notice for your modifications
30101adjacent to the other copyright notices.
30102
30103@item
30104Include, immediately after the copyright notices, a license notice
30105giving the public permission to use the Modified Version under the
30106terms of this License, in the form shown in the Addendum below.
30107
30108@item
30109Preserve in that license notice the full lists of Invariant Sections
30110and required Cover Texts given in the Document’s license notice.
30111
30112@item
30113Include an unaltered copy of this License.
30114
30115@item
30116Preserve the section Entitled “History”, Preserve its Title, and add
30117to it an item stating at least the title, year, new authors, and
30118publisher of the Modified Version as given on the Title Page.  If
30119there is no section Entitled “History” in the Document, create one
30120stating the title, year, authors, and publisher of the Document as
30121given on its Title Page, then add an item describing the Modified
30122Version as stated in the previous sentence.
30123
30124@item
30125Preserve the network location, if any, given in the Document for
30126public access to a Transparent copy of the Document, and likewise
30127the network locations given in the Document for previous versions
30128it was based on.  These may be placed in the “History” section.
30129You may omit a network location for a work that was published at
30130least four years before the Document itself, or if the original
30131publisher of the version it refers to gives permission.
30132
30133@item
30134For any section Entitled “Acknowledgements” or “Dedications”,
30135Preserve the Title of the section, and preserve in the section all
30136the substance and tone of each of the contributor acknowledgements
30137and/or dedications given therein.
30138
30139@item
30140Preserve all the Invariant Sections of the Document,
30141unaltered in their text and in their titles.  Section numbers
30142or the equivalent are not considered part of the section titles.
30143
30144@item
30145Delete any section Entitled “Endorsements”.  Such a section
30146may not be included in the Modified Version.
30147
30148@item
30149Do not retitle any existing section to be Entitled “Endorsements”
30150or to conflict in title with any Invariant Section.
30151
30152@item
30153Preserve any Warranty Disclaimers.
30154@end enumerate
30155
30156If the Modified Version includes new front-matter sections or
30157appendices that qualify as Secondary Sections and contain no material
30158copied from the Document, you may at your option designate some or all
30159of these sections as invariant.  To do this, add their titles to the
30160list of Invariant Sections in the Modified Version’s license notice.
30161These titles must be distinct from any other section titles.
30162
30163You may add a section Entitled “Endorsements”, provided it contains
30164nothing but endorsements of your Modified Version by various
30165parties—for example, statements of peer review or that the text has
30166been approved by an organization as the authoritative definition of a
30167standard.
30168
30169You may add a passage of up to five words as a Front-Cover Text, and a
30170passage of up to 25 words as a Back-Cover Text, to the end of the list
30171of Cover Texts in the Modified Version.  Only one passage of
30172Front-Cover Text and one of Back-Cover Text may be added by (or
30173through arrangements made by) any one entity.  If the Document already
30174includes a cover text for the same cover, previously added by you or
30175by arrangement made by the same entity you are acting on behalf of,
30176you may not add another; but you may replace the old one, on explicit
30177permission from the previous publisher that added the old one.
30178
30179The author(s) and publisher(s) of the Document do not by this License
30180give permission to use their names for publicity for or to assert or
30181imply endorsement of any Modified Version.
30182
30183@strong{5. COMBINING DOCUMENTS}
30184
30185You may combine the Document with other documents released under this
30186License, under the terms defined in section 4 above for modified
30187versions, provided that you include in the combination all of the
30188Invariant Sections of all of the original documents, unmodified, and
30189list them all as Invariant Sections of your combined work in its
30190license notice, and that you preserve all their Warranty Disclaimers.
30191
30192The combined work need only contain one copy of this License, and
30193multiple identical Invariant Sections may be replaced with a single
30194copy.  If there are multiple Invariant Sections with the same name but
30195different contents, make the title of each such section unique by
30196adding at the end of it, in parentheses, the name of the original
30197author or publisher of that section if known, or else a unique number.
30198Make the same adjustment to the section titles in the list of
30199Invariant Sections in the license notice of the combined work.
30200
30201In the combination, you must combine any sections Entitled “History”
30202in the various original documents, forming one section Entitled
30203“History”; likewise combine any sections Entitled “Acknowledgements”,
30204and any sections Entitled “Dedications”.  You must delete all sections
30205Entitled “Endorsements”.
30206
30207@strong{6. COLLECTIONS OF DOCUMENTS}
30208
30209You may make a collection consisting of the Document and other documents
30210released under this License, and replace the individual copies of this
30211License in the various documents with a single copy that is included in
30212the collection, provided that you follow the rules of this License for
30213verbatim copying of each of the documents in all other respects.
30214
30215You may extract a single document from such a collection, and distribute
30216it individually under this License, provided you insert a copy of this
30217License into the extracted document, and follow this License in all
30218other respects regarding verbatim copying of that document.
30219
30220@strong{7. AGGREGATION WITH INDEPENDENT WORKS}
30221
30222A compilation of the Document or its derivatives with other separate
30223and independent documents or works, in or on a volume of a storage or
30224distribution medium, is called an “aggregate” if the copyright
30225resulting from the compilation is not used to limit the legal rights
30226of the compilation’s users beyond what the individual works permit.
30227When the Document is included in an aggregate, this License does not
30228apply to the other works in the aggregate which are not themselves
30229derivative works of the Document.
30230
30231If the Cover Text requirement of section 3 is applicable to these
30232copies of the Document, then if the Document is less than one half of
30233the entire aggregate, the Document’s Cover Texts may be placed on
30234covers that bracket the Document within the aggregate, or the
30235electronic equivalent of covers if the Document is in electronic form.
30236Otherwise they must appear on printed covers that bracket the whole
30237aggregate.
30238
30239@strong{8. TRANSLATION}
30240
30241Translation is considered a kind of modification, so you may
30242distribute translations of the Document under the terms of section 4.
30243Replacing Invariant Sections with translations requires special
30244permission from their copyright holders, but you may include
30245translations of some or all Invariant Sections in addition to the
30246original versions of these Invariant Sections.  You may include a
30247translation of this License, and all the license notices in the
30248Document, and any Warranty Disclaimers, provided that you also include
30249the original English version of this License and the original versions
30250of those notices and disclaimers.  In case of a disagreement between
30251the translation and the original version of this License or a notice
30252or disclaimer, the original version will prevail.
30253
30254If a section in the Document is Entitled “Acknowledgements”,
30255“Dedications”, or “History”, the requirement (section 4) to Preserve
30256its Title (section 1) will typically require changing the actual
30257title.
30258
30259@strong{9. TERMINATION}
30260
30261You may not copy, modify, sublicense, or distribute the Document
30262except as expressly provided under this License.  Any attempt
30263otherwise to copy, modify, sublicense, or distribute it is void, and
30264will automatically terminate your rights under this License.
30265
30266However, if you cease all violation of this License, then your license
30267from a particular copyright holder is reinstated (a) provisionally,
30268unless and until the copyright holder explicitly and finally
30269terminates your license, and (b) permanently, if the copyright holder
30270fails to notify you of the violation by some reasonable means prior to
3027160 days after the cessation.
30272
30273Moreover, your license from a particular copyright holder is
30274reinstated permanently if the copyright holder notifies you of the
30275violation by some reasonable means, this is the first time you have
30276received notice of violation of this License (for any work) from that
30277copyright holder, and you cure the violation prior to 30 days after
30278your receipt of the notice.
30279
30280Termination of your rights under this section does not terminate the
30281licenses of parties who have received copies or rights from you under
30282this License.  If your rights have been terminated and not permanently
30283reinstated, receipt of a copy of some or all of the same material does
30284not give you any rights to use it.
30285
30286@strong{10. FUTURE REVISIONS OF THIS LICENSE}
30287
30288The Free Software Foundation may publish new, revised versions
30289of the GNU Free Documentation License from time to time.  Such new
30290versions will be similar in spirit to the present version, but may
30291differ in detail to address new problems or concerns.  See
30292@indicateurl{http://www.gnu.org/copyleft/}.
30293
30294Each version of the License is given a distinguishing version number.
30295If the Document specifies that a particular numbered version of this
30296License “or any later version” applies to it, you have the option of
30297following the terms and conditions either of that specified version or
30298of any later version that has been published (not as a draft) by the
30299Free Software Foundation.  If the Document does not specify a version
30300number of this License, you may choose any version ever published (not
30301as a draft) by the Free Software Foundation.  If the Document
30302specifies that a proxy can decide which future versions of this
30303License can be used, that proxy’s public statement of acceptance of a
30304version permanently authorizes you to choose that version for the
30305Document.
30306
30307@strong{11. RELICENSING}
30308
30309“Massive Multiauthor Collaboration Site” (or “MMC Site”) means any
30310World Wide Web server that publishes copyrightable works and also
30311provides prominent facilities for anybody to edit those works.  A
30312public wiki that anybody can edit is an example of such a server.  A
30313“Massive Multiauthor Collaboration” (or “MMC”) contained in the
30314site means any set of copyrightable works thus published on the MMC
30315site.
30316
30317“CC-BY-SA” means the Creative Commons Attribution-Share Alike 3.0
30318license published by Creative Commons Corporation, a not-for-profit
30319corporation with a principal place of business in San Francisco,
30320California, as well as future copyleft versions of that license
30321published by that same organization.
30322
30323“Incorporate” means to publish or republish a Document, in whole or
30324in part, as part of another Document.
30325
30326An MMC is “eligible for relicensing” if it is licensed under this
30327License, and if all works that were first published under this License
30328somewhere other than this MMC, and subsequently incorporated in whole
30329or in part into the MMC, (1) had no cover texts or invariant sections,
30330and (2) were thus incorporated prior to November 1, 2008.
30331
30332The operator of an MMC Site may republish an MMC contained in the site
30333under CC-BY-SA on the same site at any time before August 1, 2009,
30334provided the MMC is eligible for relicensing.
30335
30336@strong{ADDENDUM: How to use this License for your documents}
30337
30338To use this License in a document you have written, include a copy of
30339the License in the document and put the following copyright and
30340license notices just after the title page:
30341
30342@quotation
30343
30344Copyright © YEAR  YOUR NAME.
30345Permission is granted to copy, distribute and/or modify this document
30346under the terms of the GNU Free Documentation License, Version 1.3
30347or any later version published by the Free Software Foundation;
30348with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
30349A copy of the license is included in the section entitled “GNU
30350Free Documentation License”.
30351@end quotation
30352
30353If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
30354replace the “with … Texts.” line with this:
30355
30356@quotation
30357
30358with the Invariant Sections being LIST THEIR TITLES, with the
30359Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
30360@end quotation
30361
30362If you have Invariant Sections without Cover Texts, or some other
30363combination of the three, merge those two alternatives to suit the
30364situation.
30365
30366If your document contains nontrivial examples of program code, we
30367recommend releasing these examples in parallel under your choice of
30368free software license, such as the GNU General Public License,
30369to permit their use in free software.
30370
30371@node Index,,GNU Free Documentation License,Top
30372@unnumbered Index
30373
30374
30375@printindex ge
30376
30377
30378@c %**end of body
30379@bye
30380