1 \input texinfo @c -*-texinfo-*-
3 @setfilename gnat_rm.info
4 @documentencoding UTF-8
6 @*Generated by Sphinx 1.4.6.@*
8 @settitle GNAT Reference Manual
13 @dircategory GNU Ada Tools
15 * gnat_rm: (gnat_rm.info). gnat_rm
18 @definfoenclose strong,`,'
19 @definfoenclose emph,`,'
24 GNAT Reference Manual , Aug 01, 2019
28 Copyright @copyright{} 2008-2019, Free Software Foundation
34 @title GNAT Reference Manual
39 @c %** start of user preamble
41 @c %** end of user preamble
45 @top GNAT Reference Manual
50 @anchor{gnat_rm doc}@anchor{0}
51 @emph{GNAT, The GNU Ada Development Environment}
54 @include gcc-common.texi
55 GCC version @value{version-GCC}@*
58 Permission is granted to copy, distribute and/or modify this document
59 under the terms of the GNU Free Documentation License, Version 1.3 or
60 any later version published by the Free Software Foundation; with no
61 Invariant Sections, with the Front-Cover Texts being "GNAT Reference
62 Manual", and with no Back-Cover Texts. A copy of the license is
63 included in the section entitled @ref{1,,GNU Free Documentation License}.
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::
78 * Interfacing to Other Languages::
79 * Specialized Needs Annexes::
80 * Implementation of Specific Ada Features::
81 * Implementation of Ada 2012 Features::
82 * Obsolescent Features::
83 * Compatibility and Porting Guide::
84 * GNU Free Documentation License::
88 --- The Detailed Node Listing ---
92 * What This Reference Manual Contains::
94 * Related Information::
96 Implementation Defined Pragmas
98 * Pragma Abort_Defer::
99 * Pragma Abstract_State::
100 * Pragma Acc_Parallel::
102 * Pragma Acc_Kernels::
110 * Pragma Aggregate_Individually_Assign::
111 * Pragma Allow_Integer_Address::
114 * Pragma Assert_And_Cut::
115 * Pragma Assertion_Policy::
117 * Pragma Assume_No_Invalid_Values::
118 * Pragma Async_Readers::
119 * Pragma Async_Writers::
120 * Pragma Attribute_Definition::
121 * Pragma C_Pass_By_Copy::
123 * Pragma Check_Float_Overflow::
124 * Pragma Check_Name::
125 * Pragma Check_Policy::
127 * Pragma Common_Object::
128 * Pragma Compile_Time_Error::
129 * Pragma Compile_Time_Warning::
130 * Pragma Compiler_Unit::
131 * Pragma Compiler_Unit_Warning::
132 * Pragma Complete_Representation::
133 * Pragma Complex_Representation::
134 * Pragma Component_Alignment::
135 * Pragma Constant_After_Elaboration::
136 * Pragma Contract_Cases::
137 * Pragma Convention_Identifier::
139 * Pragma CPP_Constructor::
140 * Pragma CPP_Virtual::
141 * Pragma CPP_Vtable::
143 * Pragma Deadline_Floor::
144 * Pragma Default_Initial_Condition::
146 * Pragma Debug_Policy::
147 * Pragma Default_Scalar_Storage_Order::
148 * Pragma Default_Storage_Pool::
150 * Pragma Detect_Blocking::
151 * Pragma Disable_Atomic_Synchronization::
152 * Pragma Dispatching_Domain::
153 * Pragma Effective_Reads::
154 * Pragma Effective_Writes::
155 * Pragma Elaboration_Checks::
157 * Pragma Enable_Atomic_Synchronization::
158 * Pragma Export_Function::
159 * Pragma Export_Object::
160 * Pragma Export_Procedure::
161 * Pragma Export_Value::
162 * Pragma Export_Valued_Procedure::
163 * Pragma Extend_System::
164 * Pragma Extensions_Allowed::
165 * Pragma Extensions_Visible::
167 * Pragma External_Name_Casing::
169 * Pragma Favor_Top_Level::
170 * Pragma Finalize_Storage_Only::
171 * Pragma Float_Representation::
175 * Pragma Ignore_Pragma::
176 * Pragma Implementation_Defined::
177 * Pragma Implemented::
178 * Pragma Implicit_Packing::
179 * Pragma Import_Function::
180 * Pragma Import_Object::
181 * Pragma Import_Procedure::
182 * Pragma Import_Valued_Procedure::
183 * Pragma Independent::
184 * Pragma Independent_Components::
185 * Pragma Initial_Condition::
186 * Pragma Initialize_Scalars::
187 * Pragma Initializes::
188 * Pragma Inline_Always::
189 * Pragma Inline_Generic::
191 * Pragma Interface_Name::
192 * Pragma Interrupt_Handler::
193 * Pragma Interrupt_State::
195 * Pragma Keep_Names::
198 * Pragma Linker_Alias::
199 * Pragma Linker_Constructor::
200 * Pragma Linker_Destructor::
201 * Pragma Linker_Section::
203 * Pragma Loop_Invariant::
204 * Pragma Loop_Optimize::
205 * Pragma Loop_Variant::
206 * Pragma Machine_Attribute::
208 * Pragma Main_Storage::
209 * Pragma Max_Queue_Length::
211 * Pragma No_Caching::
212 * Pragma No_Component_Reordering::
213 * Pragma No_Elaboration_Code_All::
214 * Pragma No_Heap_Finalization::
217 * Pragma No_Run_Time::
218 * Pragma No_Strict_Aliasing::
219 * Pragma No_Tagged_Streams::
220 * Pragma Normalize_Scalars::
221 * Pragma Obsolescent::
222 * Pragma Optimize_Alignment::
224 * Pragma Overflow_Mode::
225 * Pragma Overriding_Renamings::
226 * Pragma Partition_Elaboration_Policy::
229 * Pragma Persistent_BSS::
232 * Pragma Postcondition::
233 * Pragma Post_Class::
234 * Pragma Rename_Pragma::
236 * Pragma Precondition::
238 * Pragma Predicate_Failure::
239 * Pragma Preelaborable_Initialization::
240 * Pragma Prefix_Exception_Messages::
242 * Pragma Priority_Specific_Dispatching::
244 * Pragma Profile_Warnings::
245 * Pragma Propagate_Exceptions::
246 * Pragma Provide_Shift_Operators::
247 * Pragma Psect_Object::
248 * Pragma Pure_Function::
251 * Pragma Refined_Depends::
252 * Pragma Refined_Global::
253 * Pragma Refined_Post::
254 * Pragma Refined_State::
255 * Pragma Relative_Deadline::
256 * Pragma Remote_Access_Type::
257 * Pragma Restricted_Run_Time::
258 * Pragma Restriction_Warnings::
259 * Pragma Reviewable::
260 * Pragma Secondary_Stack_Size::
261 * Pragma Share_Generic::
263 * Pragma Short_Circuit_And_Or::
264 * Pragma Short_Descriptors::
265 * Pragma Simple_Storage_Pool_Type::
266 * Pragma Source_File_Name::
267 * Pragma Source_File_Name_Project::
268 * Pragma Source_Reference::
269 * Pragma SPARK_Mode::
270 * Pragma Static_Elaboration_Desired::
271 * Pragma Stream_Convert::
272 * Pragma Style_Checks::
275 * Pragma Suppress_All::
276 * Pragma Suppress_Debug_Info::
277 * Pragma Suppress_Exception_Locations::
278 * Pragma Suppress_Initialization::
280 * Pragma Task_Storage::
282 * Pragma Thread_Local_Storage::
283 * Pragma Time_Slice::
285 * Pragma Type_Invariant::
286 * Pragma Type_Invariant_Class::
287 * Pragma Unchecked_Union::
288 * Pragma Unevaluated_Use_Of_Old::
289 * Pragma Unimplemented_Unit::
290 * Pragma Universal_Aliasing::
291 * Pragma Universal_Data::
292 * Pragma Unmodified::
293 * Pragma Unreferenced::
294 * Pragma Unreferenced_Objects::
295 * Pragma Unreserve_All_Interrupts::
296 * Pragma Unsuppress::
297 * Pragma Use_VADS_Size::
299 * Pragma Validity_Checks::
301 * Pragma Volatile_Full_Access::
302 * Pragma Volatile_Function::
303 * Pragma Warning_As_Error::
305 * Pragma Weak_External::
306 * Pragma Wide_Character_Encoding::
308 Implementation Defined Aspects
310 * Aspect Abstract_State::
312 * Aspect Async_Readers::
313 * Aspect Async_Writers::
314 * Aspect Constant_After_Elaboration::
315 * Aspect Contract_Cases::
317 * Aspect Default_Initial_Condition::
319 * Aspect Dimension_System::
320 * Aspect Disable_Controlled::
321 * Aspect Effective_Reads::
322 * Aspect Effective_Writes::
323 * Aspect Extensions_Visible::
324 * Aspect Favor_Top_Level::
327 * Aspect Initial_Condition::
328 * Aspect Initializes::
329 * Aspect Inline_Always::
331 * Aspect Invariant'Class::
333 * Aspect Linker_Section::
335 * Aspect Max_Queue_Length::
336 * Aspect No_Caching::
337 * Aspect No_Elaboration_Code_All::
339 * Aspect No_Tagged_Streams::
340 * Aspect Object_Size::
341 * Aspect Obsolescent::
343 * Aspect Persistent_BSS::
345 * Aspect Pure_Function::
346 * Aspect Refined_Depends::
347 * Aspect Refined_Global::
348 * Aspect Refined_Post::
349 * Aspect Refined_State::
350 * Aspect Remote_Access_Type::
351 * Aspect Secondary_Stack_Size::
352 * Aspect Scalar_Storage_Order::
354 * Aspect Simple_Storage_Pool::
355 * Aspect Simple_Storage_Pool_Type::
356 * Aspect SPARK_Mode::
357 * Aspect Suppress_Debug_Info::
358 * Aspect Suppress_Initialization::
360 * Aspect Thread_Local_Storage::
361 * Aspect Universal_Aliasing::
362 * Aspect Universal_Data::
363 * Aspect Unmodified::
364 * Aspect Unreferenced::
365 * Aspect Unreferenced_Objects::
366 * Aspect Value_Size::
367 * Aspect Volatile_Full_Access::
368 * Aspect Volatile_Function::
371 Implementation Defined Attributes
373 * Attribute Abort_Signal::
374 * Attribute Address_Size::
375 * Attribute Asm_Input::
376 * Attribute Asm_Output::
377 * Attribute Atomic_Always_Lock_Free::
379 * Attribute Bit_Position::
380 * Attribute Code_Address::
381 * Attribute Compiler_Version::
382 * Attribute Constrained::
383 * Attribute Default_Bit_Order::
384 * Attribute Default_Scalar_Storage_Order::
386 * Attribute Descriptor_Size::
387 * Attribute Elaborated::
388 * Attribute Elab_Body::
389 * Attribute Elab_Spec::
390 * Attribute Elab_Subp_Body::
392 * Attribute Enabled::
393 * Attribute Enum_Rep::
394 * Attribute Enum_Val::
395 * Attribute Epsilon::
396 * Attribute Fast_Math::
397 * Attribute Finalization_Size::
398 * Attribute Fixed_Value::
399 * Attribute From_Any::
400 * Attribute Has_Access_Values::
401 * Attribute Has_Discriminants::
403 * Attribute Integer_Value::
404 * Attribute Invalid_Value::
405 * Attribute Iterable::
407 * Attribute Library_Level::
408 * Attribute Lock_Free::
409 * Attribute Loop_Entry::
410 * Attribute Machine_Size::
411 * Attribute Mantissa::
412 * Attribute Maximum_Alignment::
413 * Attribute Mechanism_Code::
414 * Attribute Null_Parameter::
415 * Attribute Object_Size::
417 * Attribute Passed_By_Reference::
418 * Attribute Pool_Address::
419 * Attribute Range_Length::
420 * Attribute Restriction_Set::
422 * Attribute Safe_Emax::
423 * Attribute Safe_Large::
424 * Attribute Safe_Small::
425 * Attribute Scalar_Storage_Order::
426 * Attribute Simple_Storage_Pool::
428 * Attribute Storage_Unit::
429 * Attribute Stub_Type::
430 * Attribute System_Allocator_Alignment::
431 * Attribute Target_Name::
432 * Attribute To_Address::
434 * Attribute Type_Class::
435 * Attribute Type_Key::
436 * Attribute TypeCode::
437 * Attribute Unconstrained_Array::
438 * Attribute Universal_Literal_String::
439 * Attribute Unrestricted_Access::
441 * Attribute Valid_Scalars::
442 * Attribute VADS_Size::
443 * Attribute Value_Size::
444 * Attribute Wchar_T_Size::
445 * Attribute Word_Size::
447 Standard and Implementation Defined Restrictions
449 * Partition-Wide Restrictions::
450 * Program Unit Level Restrictions::
452 Partition-Wide Restrictions
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::
462 * No_Abort_Statements::
463 * No_Access_Parameter_Allocators::
464 * No_Access_Subprograms::
466 * No_Anonymous_Allocators::
467 * No_Asynchronous_Control::
470 * No_Default_Initialization::
473 * No_Direct_Boolean_Operators::
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::
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::
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::
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::
514 * No_Task_Allocators::
515 * No_Task_At_Interrupt_Priority::
516 * No_Task_Attributes_Package::
517 * No_Task_Hierarchy::
518 * No_Task_Termination::
520 * No_Terminate_Alternatives::
521 * No_Unchecked_Access::
522 * No_Unchecked_Conversion::
523 * No_Unchecked_Deallocation::
527 * Static_Priorities::
528 * Static_Storage_Size::
530 Program Unit Level Restrictions
532 * No_Elaboration_Code::
533 * No_Dynamic_Sized_Objects::
535 * No_Implementation_Aspect_Specifications::
536 * No_Implementation_Attributes::
537 * No_Implementation_Identifiers::
538 * No_Implementation_Pragmas::
539 * No_Implementation_Restrictions::
540 * No_Implementation_Units::
541 * No_Implicit_Aliasing::
542 * No_Implicit_Loops::
543 * No_Obsolescent_Features::
544 * No_Wide_Characters::
545 * Static_Dispatch_Tables::
548 Implementation Advice
550 * RM 1.1.3(20); Error Detection: RM 1 1 3 20 Error Detection.
551 * RM 1.1.3(31); Child Units: RM 1 1 3 31 Child Units.
552 * RM 1.1.5(12); Bounded Errors: RM 1 1 5 12 Bounded Errors.
553 * RM 2.8(16); Pragmas: RM 2 8 16 Pragmas.
554 * RM 2.8(17-19); Pragmas: RM 2 8 17-19 Pragmas.
555 * RM 3.5.2(5); Alternative Character Sets: RM 3 5 2 5 Alternative Character Sets.
556 * RM 3.5.4(28); Integer Types: RM 3 5 4 28 Integer Types.
557 * RM 3.5.4(29); Integer Types: RM 3 5 4 29 Integer Types.
558 * RM 3.5.5(8); Enumeration Values: RM 3 5 5 8 Enumeration Values.
559 * RM 3.5.7(17); Float Types: RM 3 5 7 17 Float Types.
560 * RM 3.6.2(11); Multidimensional Arrays: RM 3 6 2 11 Multidimensional Arrays.
561 * RM 9.6(30-31); Duration'Small: RM 9 6 30-31 Duration'Small.
562 * RM 10.2.1(12); Consistent Representation: RM 10 2 1 12 Consistent Representation.
563 * RM 11.4.1(19); Exception Information: RM 11 4 1 19 Exception Information.
564 * RM 11.5(28); Suppression of Checks: RM 11 5 28 Suppression of Checks.
565 * RM 13.1 (21-24); Representation Clauses: RM 13 1 21-24 Representation Clauses.
566 * RM 13.2(6-8); Packed Types: RM 13 2 6-8 Packed Types.
567 * RM 13.3(14-19); Address Clauses: RM 13 3 14-19 Address Clauses.
568 * RM 13.3(29-35); Alignment Clauses: RM 13 3 29-35 Alignment Clauses.
569 * RM 13.3(42-43); Size Clauses: RM 13 3 42-43 Size Clauses.
570 * RM 13.3(50-56); Size Clauses: RM 13 3 50-56 Size Clauses.
571 * RM 13.3(71-73); Component Size Clauses: RM 13 3 71-73 Component Size Clauses.
572 * RM 13.4(9-10); Enumeration Representation Clauses: RM 13 4 9-10 Enumeration Representation Clauses.
573 * RM 13.5.1(17-22); Record Representation Clauses: RM 13 5 1 17-22 Record Representation Clauses.
574 * RM 13.5.2(5); Storage Place Attributes: RM 13 5 2 5 Storage Place Attributes.
575 * RM 13.5.3(7-8); Bit Ordering: RM 13 5 3 7-8 Bit Ordering.
576 * RM 13.7(37); Address as Private: RM 13 7 37 Address as Private.
577 * RM 13.7.1(16); Address Operations: RM 13 7 1 16 Address Operations.
578 * RM 13.9(14-17); Unchecked Conversion: RM 13 9 14-17 Unchecked Conversion.
579 * RM 13.11(23-25); Implicit Heap Usage: RM 13 11 23-25 Implicit Heap Usage.
580 * RM 13.11.2(17); Unchecked Deallocation: RM 13 11 2 17 Unchecked Deallocation.
581 * RM 13.13.2(1.6); Stream Oriented Attributes: RM 13 13 2 1 6 Stream Oriented Attributes.
582 * RM A.1(52); Names of Predefined Numeric Types: RM A 1 52 Names of Predefined Numeric Types.
583 * RM A.3.2(49); Ada.Characters.Handling: RM A 3 2 49 Ada Characters Handling.
584 * RM A.4.4(106); Bounded-Length String Handling: RM A 4 4 106 Bounded-Length String Handling.
585 * RM A.5.2(46-47); Random Number Generation: RM A 5 2 46-47 Random Number Generation.
586 * RM A.10.7(23); Get_Immediate: RM A 10 7 23 Get_Immediate.
587 * RM B.1(39-41); Pragma Export: RM B 1 39-41 Pragma Export.
588 * RM B.2(12-13); Package Interfaces: RM B 2 12-13 Package Interfaces.
589 * RM B.3(63-71); Interfacing with C: RM B 3 63-71 Interfacing with C.
590 * RM B.4(95-98); Interfacing with COBOL: RM B 4 95-98 Interfacing with COBOL.
591 * RM B.5(22-26); Interfacing with Fortran: RM B 5 22-26 Interfacing with Fortran.
592 * RM C.1(3-5); Access to Machine Operations: RM C 1 3-5 Access to Machine Operations.
593 * RM C.1(10-16); Access to Machine Operations: RM C 1 10-16 Access to Machine Operations.
594 * RM C.3(28); Interrupt Support: RM C 3 28 Interrupt Support.
595 * RM C.3.1(20-21); Protected Procedure Handlers: RM C 3 1 20-21 Protected Procedure Handlers.
596 * RM C.3.2(25); Package Interrupts: RM C 3 2 25 Package Interrupts.
597 * RM C.4(14); Pre-elaboration Requirements: RM C 4 14 Pre-elaboration Requirements.
598 * RM C.5(8); Pragma Discard_Names: RM C 5 8 Pragma Discard_Names.
599 * RM C.7.2(30); The Package Task_Attributes: RM C 7 2 30 The Package Task_Attributes.
600 * RM D.3(17); Locking Policies: RM D 3 17 Locking Policies.
601 * RM D.4(16); Entry Queuing Policies: RM D 4 16 Entry Queuing Policies.
602 * RM D.6(9-10); Preemptive Abort: RM D 6 9-10 Preemptive Abort.
603 * RM D.7(21); Tasking Restrictions: RM D 7 21 Tasking Restrictions.
604 * RM D.8(47-49); Monotonic Time: RM D 8 47-49 Monotonic Time.
605 * RM E.5(28-29); Partition Communication Subsystem: RM E 5 28-29 Partition Communication Subsystem.
606 * RM F(7); COBOL Support: RM F 7 COBOL Support.
607 * RM F.1(2); Decimal Radix Support: RM F 1 2 Decimal Radix Support.
608 * RM G; Numerics: RM G Numerics.
609 * RM G.1.1(56-58); Complex Types: RM G 1 1 56-58 Complex Types.
610 * RM G.1.2(49); Complex Elementary Functions: RM G 1 2 49 Complex Elementary Functions.
611 * RM G.2.4(19); Accuracy Requirements: RM G 2 4 19 Accuracy Requirements.
612 * RM G.2.6(15); Complex Arithmetic Accuracy: RM G 2 6 15 Complex Arithmetic Accuracy.
613 * RM H.6(15/2); Pragma Partition_Elaboration_Policy: RM H 6 15/2 Pragma Partition_Elaboration_Policy.
615 Intrinsic Subprograms
617 * Intrinsic Operators::
618 * Compilation_ISO_Date::
622 * Exception_Information::
623 * Exception_Message::
627 * Shifts and Rotates::
630 Representation Clauses and Pragmas
632 * Alignment Clauses::
634 * Storage_Size Clauses::
635 * Size of Variant Record Objects::
636 * Biased Representation::
637 * Value_Size and Object_Size Clauses::
638 * Component_Size Clauses::
639 * Bit_Order Clauses::
640 * Effect of Bit_Order on Byte Ordering::
641 * Pragma Pack for Arrays::
642 * Pragma Pack for Records::
643 * Record Representation Clauses::
644 * Handling of Records with Holes::
645 * Enumeration Clauses::
647 * Use of Address Clauses for Memory-Mapped I/O::
648 * Effect of Convention on Representation::
649 * Conventions and Anonymous Access Types::
650 * Determining the Representations chosen by GNAT::
652 The Implementation of Standard I/O
654 * Standard I/O Packages::
660 * Wide_Wide_Text_IO::
664 * Filenames encoding::
665 * File content encoding::
667 * Operations on C Streams::
668 * Interfacing to C Streams::
672 * Stream Pointer Positioning::
673 * Reading and Writing Non-Regular Files::
675 * Treating Text_IO Files as Streams::
676 * Text_IO Extensions::
677 * Text_IO Facilities for Unbounded Strings::
681 * Stream Pointer Positioning: Stream Pointer Positioning<2>.
682 * Reading and Writing Non-Regular Files: Reading and Writing Non-Regular Files<2>.
686 * Stream Pointer Positioning: Stream Pointer Positioning<3>.
687 * Reading and Writing Non-Regular Files: Reading and Writing Non-Regular Files<3>.
691 * Ada.Characters.Latin_9 (a-chlat9.ads): Ada Characters Latin_9 a-chlat9 ads.
692 * Ada.Characters.Wide_Latin_1 (a-cwila1.ads): Ada Characters Wide_Latin_1 a-cwila1 ads.
693 * Ada.Characters.Wide_Latin_9 (a-cwila1.ads): Ada Characters Wide_Latin_9 a-cwila1 ads.
694 * Ada.Characters.Wide_Wide_Latin_1 (a-chzla1.ads): Ada Characters Wide_Wide_Latin_1 a-chzla1 ads.
695 * Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads): Ada Characters Wide_Wide_Latin_9 a-chzla9 ads.
696 * Ada.Containers.Formal_Doubly_Linked_Lists (a-cfdlli.ads): Ada Containers Formal_Doubly_Linked_Lists a-cfdlli ads.
697 * Ada.Containers.Formal_Hashed_Maps (a-cfhama.ads): Ada Containers Formal_Hashed_Maps a-cfhama ads.
698 * Ada.Containers.Formal_Hashed_Sets (a-cfhase.ads): Ada Containers Formal_Hashed_Sets a-cfhase ads.
699 * Ada.Containers.Formal_Ordered_Maps (a-cforma.ads): Ada Containers Formal_Ordered_Maps a-cforma ads.
700 * Ada.Containers.Formal_Ordered_Sets (a-cforse.ads): Ada Containers Formal_Ordered_Sets a-cforse ads.
701 * Ada.Containers.Formal_Vectors (a-cofove.ads): Ada Containers Formal_Vectors a-cofove ads.
702 * Ada.Containers.Formal_Indefinite_Vectors (a-cfinve.ads): Ada Containers Formal_Indefinite_Vectors a-cfinve ads.
703 * Ada.Containers.Functional_Vectors (a-cofuve.ads): Ada Containers Functional_Vectors a-cofuve ads.
704 * Ada.Containers.Functional_Sets (a-cofuse.ads): Ada Containers Functional_Sets a-cofuse ads.
705 * Ada.Containers.Functional_Maps (a-cofuma.ads): Ada Containers Functional_Maps a-cofuma ads.
706 * Ada.Containers.Bounded_Holders (a-coboho.ads): Ada Containers Bounded_Holders a-coboho ads.
707 * Ada.Command_Line.Environment (a-colien.ads): Ada Command_Line Environment a-colien ads.
708 * Ada.Command_Line.Remove (a-colire.ads): Ada Command_Line Remove a-colire ads.
709 * Ada.Command_Line.Response_File (a-clrefi.ads): Ada Command_Line Response_File a-clrefi ads.
710 * Ada.Direct_IO.C_Streams (a-diocst.ads): Ada Direct_IO C_Streams a-diocst ads.
711 * Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads): Ada Exceptions Is_Null_Occurrence a-einuoc ads.
712 * Ada.Exceptions.Last_Chance_Handler (a-elchha.ads): Ada Exceptions Last_Chance_Handler a-elchha ads.
713 * Ada.Exceptions.Traceback (a-exctra.ads): Ada Exceptions Traceback a-exctra ads.
714 * Ada.Sequential_IO.C_Streams (a-siocst.ads): Ada Sequential_IO C_Streams a-siocst ads.
715 * Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads): Ada Streams Stream_IO C_Streams a-ssicst ads.
716 * Ada.Strings.Unbounded.Text_IO (a-suteio.ads): Ada Strings Unbounded Text_IO a-suteio ads.
717 * Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads): Ada Strings Wide_Unbounded Wide_Text_IO a-swuwti ads.
718 * Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads): Ada Strings Wide_Wide_Unbounded Wide_Wide_Text_IO a-szuzti ads.
719 * Ada.Text_IO.C_Streams (a-tiocst.ads): Ada Text_IO C_Streams a-tiocst ads.
720 * Ada.Text_IO.Reset_Standard_Files (a-tirsfi.ads): Ada Text_IO Reset_Standard_Files a-tirsfi ads.
721 * Ada.Wide_Characters.Unicode (a-wichun.ads): Ada Wide_Characters Unicode a-wichun ads.
722 * Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads): Ada Wide_Text_IO C_Streams a-wtcstr ads.
723 * Ada.Wide_Text_IO.Reset_Standard_Files (a-wrstfi.ads): Ada Wide_Text_IO Reset_Standard_Files a-wrstfi ads.
724 * Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads): Ada Wide_Wide_Characters Unicode a-zchuni ads.
725 * Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads): Ada Wide_Wide_Text_IO C_Streams a-ztcstr ads.
726 * Ada.Wide_Wide_Text_IO.Reset_Standard_Files (a-zrstfi.ads): Ada Wide_Wide_Text_IO Reset_Standard_Files a-zrstfi ads.
727 * GNAT.Altivec (g-altive.ads): GNAT Altivec g-altive ads.
728 * GNAT.Altivec.Conversions (g-altcon.ads): GNAT Altivec Conversions g-altcon ads.
729 * GNAT.Altivec.Vector_Operations (g-alveop.ads): GNAT Altivec Vector_Operations g-alveop ads.
730 * GNAT.Altivec.Vector_Types (g-alvety.ads): GNAT Altivec Vector_Types g-alvety ads.
731 * GNAT.Altivec.Vector_Views (g-alvevi.ads): GNAT Altivec Vector_Views g-alvevi ads.
732 * GNAT.Array_Split (g-arrspl.ads): GNAT Array_Split g-arrspl ads.
733 * GNAT.AWK (g-awk.ads): GNAT AWK g-awk ads.
734 * GNAT.Bind_Environment (g-binenv.ads): GNAT Bind_Environment g-binenv ads.
735 * GNAT.Branch_Prediction (g-brapre.ads): GNAT Branch_Prediction g-brapre ads.
736 * GNAT.Bounded_Buffers (g-boubuf.ads): GNAT Bounded_Buffers g-boubuf ads.
737 * GNAT.Bounded_Mailboxes (g-boumai.ads): GNAT Bounded_Mailboxes g-boumai ads.
738 * GNAT.Bubble_Sort (g-bubsor.ads): GNAT Bubble_Sort g-bubsor ads.
739 * GNAT.Bubble_Sort_A (g-busora.ads): GNAT Bubble_Sort_A g-busora ads.
740 * GNAT.Bubble_Sort_G (g-busorg.ads): GNAT Bubble_Sort_G g-busorg ads.
741 * GNAT.Byte_Order_Mark (g-byorma.ads): GNAT Byte_Order_Mark g-byorma ads.
742 * GNAT.Byte_Swapping (g-bytswa.ads): GNAT Byte_Swapping g-bytswa ads.
743 * GNAT.Calendar (g-calend.ads): GNAT Calendar g-calend ads.
744 * GNAT.Calendar.Time_IO (g-catiio.ads): GNAT Calendar Time_IO g-catiio ads.
745 * GNAT.CRC32 (g-crc32.ads): GNAT CRC32 g-crc32 ads.
746 * GNAT.Case_Util (g-casuti.ads): GNAT Case_Util g-casuti ads.
747 * GNAT.CGI (g-cgi.ads): GNAT CGI g-cgi ads.
748 * GNAT.CGI.Cookie (g-cgicoo.ads): GNAT CGI Cookie g-cgicoo ads.
749 * GNAT.CGI.Debug (g-cgideb.ads): GNAT CGI Debug g-cgideb ads.
750 * GNAT.Command_Line (g-comlin.ads): GNAT Command_Line g-comlin ads.
751 * GNAT.Compiler_Version (g-comver.ads): GNAT Compiler_Version g-comver ads.
752 * GNAT.Ctrl_C (g-ctrl_c.ads): GNAT Ctrl_C g-ctrl_c ads.
753 * GNAT.Current_Exception (g-curexc.ads): GNAT Current_Exception g-curexc ads.
754 * GNAT.Debug_Pools (g-debpoo.ads): GNAT Debug_Pools g-debpoo ads.
755 * GNAT.Debug_Utilities (g-debuti.ads): GNAT Debug_Utilities g-debuti ads.
756 * GNAT.Decode_String (g-decstr.ads): GNAT Decode_String g-decstr ads.
757 * GNAT.Decode_UTF8_String (g-deutst.ads): GNAT Decode_UTF8_String g-deutst ads.
758 * GNAT.Directory_Operations (g-dirope.ads): GNAT Directory_Operations g-dirope ads.
759 * GNAT.Directory_Operations.Iteration (g-diopit.ads): GNAT Directory_Operations Iteration g-diopit ads.
760 * GNAT.Dynamic_HTables (g-dynhta.ads): GNAT Dynamic_HTables g-dynhta ads.
761 * GNAT.Dynamic_Tables (g-dyntab.ads): GNAT Dynamic_Tables g-dyntab ads.
762 * GNAT.Encode_String (g-encstr.ads): GNAT Encode_String g-encstr ads.
763 * GNAT.Encode_UTF8_String (g-enutst.ads): GNAT Encode_UTF8_String g-enutst ads.
764 * GNAT.Exception_Actions (g-excact.ads): GNAT Exception_Actions g-excact ads.
765 * GNAT.Exception_Traces (g-exctra.ads): GNAT Exception_Traces g-exctra ads.
766 * GNAT.Exceptions (g-except.ads): GNAT Exceptions g-except ads.
767 * GNAT.Expect (g-expect.ads): GNAT Expect g-expect ads.
768 * GNAT.Expect.TTY (g-exptty.ads): GNAT Expect TTY g-exptty ads.
769 * GNAT.Float_Control (g-flocon.ads): GNAT Float_Control g-flocon ads.
770 * GNAT.Formatted_String (g-forstr.ads): GNAT Formatted_String g-forstr ads.
771 * GNAT.Heap_Sort (g-heasor.ads): GNAT Heap_Sort g-heasor ads.
772 * GNAT.Heap_Sort_A (g-hesora.ads): GNAT Heap_Sort_A g-hesora ads.
773 * GNAT.Heap_Sort_G (g-hesorg.ads): GNAT Heap_Sort_G g-hesorg ads.
774 * GNAT.HTable (g-htable.ads): GNAT HTable g-htable ads.
775 * GNAT.IO (g-io.ads): GNAT IO g-io ads.
776 * GNAT.IO_Aux (g-io_aux.ads): GNAT IO_Aux g-io_aux ads.
777 * GNAT.Lock_Files (g-locfil.ads): GNAT Lock_Files g-locfil ads.
778 * GNAT.MBBS_Discrete_Random (g-mbdira.ads): GNAT MBBS_Discrete_Random g-mbdira ads.
779 * GNAT.MBBS_Float_Random (g-mbflra.ads): GNAT MBBS_Float_Random g-mbflra ads.
780 * GNAT.MD5 (g-md5.ads): GNAT MD5 g-md5 ads.
781 * GNAT.Memory_Dump (g-memdum.ads): GNAT Memory_Dump g-memdum ads.
782 * GNAT.Most_Recent_Exception (g-moreex.ads): GNAT Most_Recent_Exception g-moreex ads.
783 * GNAT.OS_Lib (g-os_lib.ads): GNAT OS_Lib g-os_lib ads.
784 * GNAT.Perfect_Hash_Generators (g-pehage.ads): GNAT Perfect_Hash_Generators g-pehage ads.
785 * GNAT.Random_Numbers (g-rannum.ads): GNAT Random_Numbers g-rannum ads.
786 * GNAT.Regexp (g-regexp.ads): GNAT Regexp g-regexp ads.
787 * GNAT.Registry (g-regist.ads): GNAT Registry g-regist ads.
788 * GNAT.Regpat (g-regpat.ads): GNAT Regpat g-regpat ads.
789 * GNAT.Rewrite_Data (g-rewdat.ads): GNAT Rewrite_Data g-rewdat ads.
790 * GNAT.Secondary_Stack_Info (g-sestin.ads): GNAT Secondary_Stack_Info g-sestin ads.
791 * GNAT.Semaphores (g-semaph.ads): GNAT Semaphores g-semaph ads.
792 * GNAT.Serial_Communications (g-sercom.ads): GNAT Serial_Communications g-sercom ads.
793 * GNAT.SHA1 (g-sha1.ads): GNAT SHA1 g-sha1 ads.
794 * GNAT.SHA224 (g-sha224.ads): GNAT SHA224 g-sha224 ads.
795 * GNAT.SHA256 (g-sha256.ads): GNAT SHA256 g-sha256 ads.
796 * GNAT.SHA384 (g-sha384.ads): GNAT SHA384 g-sha384 ads.
797 * GNAT.SHA512 (g-sha512.ads): GNAT SHA512 g-sha512 ads.
798 * GNAT.Signals (g-signal.ads): GNAT Signals g-signal ads.
799 * GNAT.Sockets (g-socket.ads): GNAT Sockets g-socket ads.
800 * GNAT.Source_Info (g-souinf.ads): GNAT Source_Info g-souinf ads.
801 * GNAT.Spelling_Checker (g-speche.ads): GNAT Spelling_Checker g-speche ads.
802 * GNAT.Spelling_Checker_Generic (g-spchge.ads): GNAT Spelling_Checker_Generic g-spchge ads.
803 * GNAT.Spitbol.Patterns (g-spipat.ads): GNAT Spitbol Patterns g-spipat ads.
804 * GNAT.Spitbol (g-spitbo.ads): GNAT Spitbol g-spitbo ads.
805 * GNAT.Spitbol.Table_Boolean (g-sptabo.ads): GNAT Spitbol Table_Boolean g-sptabo ads.
806 * GNAT.Spitbol.Table_Integer (g-sptain.ads): GNAT Spitbol Table_Integer g-sptain ads.
807 * GNAT.Spitbol.Table_VString (g-sptavs.ads): GNAT Spitbol Table_VString g-sptavs ads.
808 * GNAT.SSE (g-sse.ads): GNAT SSE g-sse ads.
809 * GNAT.SSE.Vector_Types (g-ssvety.ads): GNAT SSE Vector_Types g-ssvety ads.
810 * GNAT.String_Hash (g-strhas.ads): GNAT String_Hash g-strhas ads.
811 * GNAT.Strings (g-string.ads): GNAT Strings g-string ads.
812 * GNAT.String_Split (g-strspl.ads): GNAT String_Split g-strspl ads.
813 * GNAT.Table (g-table.ads): GNAT Table g-table ads.
814 * GNAT.Task_Lock (g-tasloc.ads): GNAT Task_Lock g-tasloc ads.
815 * GNAT.Time_Stamp (g-timsta.ads): GNAT Time_Stamp g-timsta ads.
816 * GNAT.Threads (g-thread.ads): GNAT Threads g-thread ads.
817 * GNAT.Traceback (g-traceb.ads): GNAT Traceback g-traceb ads.
818 * GNAT.Traceback.Symbolic (g-trasym.ads): GNAT Traceback Symbolic g-trasym ads.
819 * GNAT.UTF_32 (g-table.ads): GNAT UTF_32 g-table ads.
820 * GNAT.Wide_Spelling_Checker (g-u3spch.ads): GNAT Wide_Spelling_Checker g-u3spch ads.
821 * GNAT.Wide_Spelling_Checker (g-wispch.ads): GNAT Wide_Spelling_Checker g-wispch ads.
822 * GNAT.Wide_String_Split (g-wistsp.ads): GNAT Wide_String_Split g-wistsp ads.
823 * GNAT.Wide_Wide_Spelling_Checker (g-zspche.ads): GNAT Wide_Wide_Spelling_Checker g-zspche ads.
824 * GNAT.Wide_Wide_String_Split (g-zistsp.ads): GNAT Wide_Wide_String_Split g-zistsp ads.
825 * Interfaces.C.Extensions (i-cexten.ads): Interfaces C Extensions i-cexten ads.
826 * Interfaces.C.Streams (i-cstrea.ads): Interfaces C Streams i-cstrea ads.
827 * Interfaces.Packed_Decimal (i-pacdec.ads): Interfaces Packed_Decimal i-pacdec ads.
828 * Interfaces.VxWorks (i-vxwork.ads): Interfaces VxWorks i-vxwork ads.
829 * Interfaces.VxWorks.Int_Connection (i-vxinco.ads): Interfaces VxWorks Int_Connection i-vxinco ads.
830 * Interfaces.VxWorks.IO (i-vxwoio.ads): Interfaces VxWorks IO i-vxwoio ads.
831 * System.Address_Image (s-addima.ads): System Address_Image s-addima ads.
832 * System.Assertions (s-assert.ads): System Assertions s-assert ads.
833 * System.Atomic_Counters (s-atocou.ads): System Atomic_Counters s-atocou ads.
834 * System.Memory (s-memory.ads): System Memory s-memory ads.
835 * System.Multiprocessors (s-multip.ads): System Multiprocessors s-multip ads.
836 * System.Multiprocessors.Dispatching_Domains (s-mudido.ads): System Multiprocessors Dispatching_Domains s-mudido ads.
837 * System.Partition_Interface (s-parint.ads): System Partition_Interface s-parint ads.
838 * System.Pool_Global (s-pooglo.ads): System Pool_Global s-pooglo ads.
839 * System.Pool_Local (s-pooloc.ads): System Pool_Local s-pooloc ads.
840 * System.Restrictions (s-restri.ads): System Restrictions s-restri ads.
841 * System.Rident (s-rident.ads): System Rident s-rident ads.
842 * System.Strings.Stream_Ops (s-ststop.ads): System Strings Stream_Ops s-ststop ads.
843 * System.Unsigned_Types (s-unstyp.ads): System Unsigned_Types s-unstyp ads.
844 * System.Wch_Cnv (s-wchcnv.ads): System Wch_Cnv s-wchcnv ads.
845 * System.Wch_Con (s-wchcon.ads): System Wch_Con s-wchcon ads.
847 Interfacing to Other Languages
850 * Interfacing to C++::
851 * Interfacing to COBOL::
852 * Interfacing to Fortran::
853 * Interfacing to non-GNAT Ada code::
855 Implementation of Specific Ada Features
857 * Machine Code Insertions::
858 * GNAT Implementation of Tasking::
859 * GNAT Implementation of Shared Passive Packages::
860 * Code Generation for Array Aggregates::
861 * The Size of Discriminated Records with Default Discriminants::
862 * Strict Conformance to the Ada Reference Manual::
864 GNAT Implementation of Tasking
866 * Mapping Ada Tasks onto the Underlying Kernel Threads::
867 * Ensuring Compliance with the Real-Time Annex::
868 * Support for Locking Policies::
870 Code Generation for Array Aggregates
872 * Static constant aggregates with static bounds::
873 * Constant aggregates with unconstrained nominal types::
874 * Aggregates with static bounds::
875 * Aggregates with nonstatic bounds::
876 * Aggregates in assignment statements::
880 * pragma No_Run_Time::
882 * pragma Restricted_Run_Time::
884 * package System.Task_Info (s-tasinf.ads): package System Task_Info s-tasinf ads.
886 Compatibility and Porting Guide
888 * Writing Portable Fixed-Point Declarations::
889 * Compatibility with Ada 83::
890 * Compatibility between Ada 95 and Ada 2005::
891 * Implementation-dependent characteristics::
892 * Compatibility with Other Ada Systems::
893 * Representation Clauses::
894 * Compatibility with HP Ada 83::
896 Compatibility with Ada 83
898 * Legal Ada 83 programs that are illegal in Ada 95::
899 * More deterministic semantics::
900 * Changed semantics::
901 * Other language compatibility issues::
903 Implementation-dependent characteristics
905 * Implementation-defined pragmas::
906 * Implementation-defined attributes::
908 * Elaboration order::
909 * Target-specific aspects::
914 @node About This Guide,Implementation Defined Pragmas,Top,Top
915 @anchor{gnat_rm/about_this_guide about-this-guide}@anchor{2}@anchor{gnat_rm/about_this_guide doc}@anchor{3}@anchor{gnat_rm/about_this_guide gnat-reference-manual}@anchor{4}@anchor{gnat_rm/about_this_guide id1}@anchor{5}
916 @chapter About This Guide
920 This manual contains useful information in writing programs using the
921 GNAT compiler. It includes information on implementation dependent
922 characteristics of GNAT, including all the information required by
923 Annex M of the Ada language standard.
925 GNAT implements Ada 95, Ada 2005 and Ada 2012, and it may also be
926 invoked in Ada 83 compatibility mode.
927 By default, GNAT assumes Ada 2012,
928 but you can override with a compiler switch
929 to explicitly specify the language version.
930 (Please refer to the @emph{GNAT User's Guide} for details on these switches.)
931 Throughout this manual, references to 'Ada' without a year suffix
932 apply to all the Ada versions of the language.
934 Ada is designed to be highly portable.
935 In general, a program will have the same effect even when compiled by
936 different compilers on different platforms.
937 However, since Ada is designed to be used in a
938 wide variety of applications, it also contains a number of system
939 dependent features to be used in interfacing to the external world.
941 @geindex Implementation-dependent features
945 Note: Any program that makes use of implementation-dependent features
946 may be non-portable. You should follow good programming practice and
947 isolate and clearly document any sections of your program that make use
948 of these features in a non-portable manner.
951 * What This Reference Manual Contains::
953 * Related Information::
957 @node What This Reference Manual Contains,Conventions,,About This Guide
958 @anchor{gnat_rm/about_this_guide what-this-reference-manual-contains}@anchor{6}
959 @section What This Reference Manual Contains
962 This reference manual contains the following chapters:
968 @ref{7,,Implementation Defined Pragmas}, lists GNAT implementation-dependent
969 pragmas, which can be used to extend and enhance the functionality of the
973 @ref{8,,Implementation Defined Attributes}, lists GNAT
974 implementation-dependent attributes, which can be used to extend and
975 enhance the functionality of the compiler.
978 @ref{9,,Standard and Implementation Defined Restrictions}, lists GNAT
979 implementation-dependent restrictions, which can be used to extend and
980 enhance the functionality of the compiler.
983 @ref{a,,Implementation Advice}, provides information on generally
984 desirable behavior which are not requirements that all compilers must
985 follow since it cannot be provided on all systems, or which may be
986 undesirable on some systems.
989 @ref{b,,Implementation Defined Characteristics}, provides a guide to
990 minimizing implementation dependent features.
993 @ref{c,,Intrinsic Subprograms}, describes the intrinsic subprograms
994 implemented by GNAT, and how they can be imported into user
995 application programs.
998 @ref{d,,Representation Clauses and Pragmas}, describes in detail the
999 way that GNAT represents data, and in particular the exact set
1000 of representation clauses and pragmas that is accepted.
1003 @ref{e,,Standard Library Routines}, provides a listing of packages and a
1004 brief description of the functionality that is provided by Ada's
1005 extensive set of standard library routines as implemented by GNAT.
1008 @ref{f,,The Implementation of Standard I/O}, details how the GNAT
1009 implementation of the input-output facilities.
1012 @ref{10,,The GNAT Library}, is a catalog of packages that complement
1013 the Ada predefined library.
1016 @ref{11,,Interfacing to Other Languages}, describes how programs
1017 written in Ada using GNAT can be interfaced to other programming
1021 @ref{12,,Specialized Needs Annexes}, describes the GNAT implementation of all
1022 of the specialized needs annexes.
1025 @ref{13,,Implementation of Specific Ada Features}, discusses issues related
1026 to GNAT's implementation of machine code insertions, tasking, and several
1030 @ref{14,,Implementation of Ada 2012 Features}, describes the status of the
1031 GNAT implementation of the Ada 2012 language standard.
1034 @ref{15,,Obsolescent Features} documents implementation dependent features,
1035 including pragmas and attributes, which are considered obsolescent, since
1036 there are other preferred ways of achieving the same results. These
1037 obsolescent forms are retained for backwards compatibility.
1040 @ref{16,,Compatibility and Porting Guide} presents some guidelines for
1041 developing portable Ada code, describes the compatibility issues that
1042 may arise between GNAT and other Ada compilation systems (including those
1043 for Ada 83), and shows how GNAT can expedite porting applications
1044 developed in other Ada environments.
1047 @ref{1,,GNU Free Documentation License} contains the license for this document.
1050 @geindex Ada 95 Language Reference Manual
1052 @geindex Ada 2005 Language Reference Manual
1054 This reference manual assumes a basic familiarity with the Ada 95 language, as
1056 @cite{International Standard ANSI/ISO/IEC-8652:1995}.
1057 It does not require knowledge of the new features introduced by Ada 2005 or
1059 All three reference manuals are included in the GNAT documentation
1062 @node Conventions,Related Information,What This Reference Manual Contains,About This Guide
1063 @anchor{gnat_rm/about_this_guide conventions}@anchor{17}
1064 @section Conventions
1067 @geindex Conventions
1068 @geindex typographical
1070 @geindex Typographical conventions
1072 Following are examples of the typographical and graphic conventions used
1079 @code{Functions}, @code{utility program names}, @code{standard names},
1095 [optional information or parameters]
1098 Examples are described by text
1101 and then shown this way.
1105 Commands that are entered by the user are shown as preceded by a prompt string
1106 comprising the @code{$} character followed by a space.
1109 @node Related Information,,Conventions,About This Guide
1110 @anchor{gnat_rm/about_this_guide related-information}@anchor{18}
1111 @section Related Information
1114 See the following documents for further information on GNAT:
1120 @cite{GNAT User's Guide for Native Platforms},
1121 which provides information on how to use the
1122 GNAT development environment.
1125 @cite{Ada 95 Reference Manual}, the Ada 95 programming language standard.
1128 @cite{Ada 95 Annotated Reference Manual}, which is an annotated version
1129 of the Ada 95 standard. The annotations describe
1130 detailed aspects of the design decision, and in particular contain useful
1131 sections on Ada 83 compatibility.
1134 @cite{Ada 2005 Reference Manual}, the Ada 2005 programming language standard.
1137 @cite{Ada 2005 Annotated Reference Manual}, which is an annotated version
1138 of the Ada 2005 standard. The annotations describe
1139 detailed aspects of the design decision.
1142 @cite{Ada 2012 Reference Manual}, the Ada 2012 programming language standard.
1145 @cite{DEC Ada@comma{} Technical Overview and Comparison on DIGITAL Platforms},
1146 which contains specific information on compatibility between GNAT and
1150 @cite{DEC Ada@comma{} Language Reference Manual}, part number AA-PYZAB-TK, which
1151 describes in detail the pragmas and attributes provided by the DEC Ada 83
1155 @node Implementation Defined Pragmas,Implementation Defined Aspects,About This Guide,Top
1156 @anchor{gnat_rm/implementation_defined_pragmas implementation-defined-pragmas}@anchor{7}@anchor{gnat_rm/implementation_defined_pragmas doc}@anchor{19}@anchor{gnat_rm/implementation_defined_pragmas id1}@anchor{1a}
1157 @chapter Implementation Defined Pragmas
1160 Ada defines a set of pragmas that can be used to supply additional
1161 information to the compiler. These language defined pragmas are
1162 implemented in GNAT and work as described in the Ada Reference Manual.
1164 In addition, Ada allows implementations to define additional pragmas
1165 whose meaning is defined by the implementation. GNAT provides a number
1166 of these implementation-defined pragmas, which can be used to extend
1167 and enhance the functionality of the compiler. This section of the GNAT
1168 Reference Manual describes these additional pragmas.
1170 Note that any program using these pragmas might not be portable to other
1171 compilers (although GNAT implements this set of pragmas on all
1172 platforms). Therefore if portability to other compilers is an important
1173 consideration, the use of these pragmas should be minimized.
1176 * Pragma Abort_Defer::
1177 * Pragma Abstract_State::
1178 * Pragma Acc_Parallel::
1180 * Pragma Acc_Kernels::
1188 * Pragma Aggregate_Individually_Assign::
1189 * Pragma Allow_Integer_Address::
1192 * Pragma Assert_And_Cut::
1193 * Pragma Assertion_Policy::
1195 * Pragma Assume_No_Invalid_Values::
1196 * Pragma Async_Readers::
1197 * Pragma Async_Writers::
1198 * Pragma Attribute_Definition::
1199 * Pragma C_Pass_By_Copy::
1201 * Pragma Check_Float_Overflow::
1202 * Pragma Check_Name::
1203 * Pragma Check_Policy::
1205 * Pragma Common_Object::
1206 * Pragma Compile_Time_Error::
1207 * Pragma Compile_Time_Warning::
1208 * Pragma Compiler_Unit::
1209 * Pragma Compiler_Unit_Warning::
1210 * Pragma Complete_Representation::
1211 * Pragma Complex_Representation::
1212 * Pragma Component_Alignment::
1213 * Pragma Constant_After_Elaboration::
1214 * Pragma Contract_Cases::
1215 * Pragma Convention_Identifier::
1216 * Pragma CPP_Class::
1217 * Pragma CPP_Constructor::
1218 * Pragma CPP_Virtual::
1219 * Pragma CPP_Vtable::
1221 * Pragma Deadline_Floor::
1222 * Pragma Default_Initial_Condition::
1224 * Pragma Debug_Policy::
1225 * Pragma Default_Scalar_Storage_Order::
1226 * Pragma Default_Storage_Pool::
1228 * Pragma Detect_Blocking::
1229 * Pragma Disable_Atomic_Synchronization::
1230 * Pragma Dispatching_Domain::
1231 * Pragma Effective_Reads::
1232 * Pragma Effective_Writes::
1233 * Pragma Elaboration_Checks::
1234 * Pragma Eliminate::
1235 * Pragma Enable_Atomic_Synchronization::
1236 * Pragma Export_Function::
1237 * Pragma Export_Object::
1238 * Pragma Export_Procedure::
1239 * Pragma Export_Value::
1240 * Pragma Export_Valued_Procedure::
1241 * Pragma Extend_System::
1242 * Pragma Extensions_Allowed::
1243 * Pragma Extensions_Visible::
1245 * Pragma External_Name_Casing::
1246 * Pragma Fast_Math::
1247 * Pragma Favor_Top_Level::
1248 * Pragma Finalize_Storage_Only::
1249 * Pragma Float_Representation::
1253 * Pragma Ignore_Pragma::
1254 * Pragma Implementation_Defined::
1255 * Pragma Implemented::
1256 * Pragma Implicit_Packing::
1257 * Pragma Import_Function::
1258 * Pragma Import_Object::
1259 * Pragma Import_Procedure::
1260 * Pragma Import_Valued_Procedure::
1261 * Pragma Independent::
1262 * Pragma Independent_Components::
1263 * Pragma Initial_Condition::
1264 * Pragma Initialize_Scalars::
1265 * Pragma Initializes::
1266 * Pragma Inline_Always::
1267 * Pragma Inline_Generic::
1268 * Pragma Interface::
1269 * Pragma Interface_Name::
1270 * Pragma Interrupt_Handler::
1271 * Pragma Interrupt_State::
1272 * Pragma Invariant::
1273 * Pragma Keep_Names::
1275 * Pragma Link_With::
1276 * Pragma Linker_Alias::
1277 * Pragma Linker_Constructor::
1278 * Pragma Linker_Destructor::
1279 * Pragma Linker_Section::
1280 * Pragma Lock_Free::
1281 * Pragma Loop_Invariant::
1282 * Pragma Loop_Optimize::
1283 * Pragma Loop_Variant::
1284 * Pragma Machine_Attribute::
1286 * Pragma Main_Storage::
1287 * Pragma Max_Queue_Length::
1289 * Pragma No_Caching::
1290 * Pragma No_Component_Reordering::
1291 * Pragma No_Elaboration_Code_All::
1292 * Pragma No_Heap_Finalization::
1293 * Pragma No_Inline::
1294 * Pragma No_Return::
1295 * Pragma No_Run_Time::
1296 * Pragma No_Strict_Aliasing::
1297 * Pragma No_Tagged_Streams::
1298 * Pragma Normalize_Scalars::
1299 * Pragma Obsolescent::
1300 * Pragma Optimize_Alignment::
1302 * Pragma Overflow_Mode::
1303 * Pragma Overriding_Renamings::
1304 * Pragma Partition_Elaboration_Policy::
1307 * Pragma Persistent_BSS::
1310 * Pragma Postcondition::
1311 * Pragma Post_Class::
1312 * Pragma Rename_Pragma::
1314 * Pragma Precondition::
1315 * Pragma Predicate::
1316 * Pragma Predicate_Failure::
1317 * Pragma Preelaborable_Initialization::
1318 * Pragma Prefix_Exception_Messages::
1319 * Pragma Pre_Class::
1320 * Pragma Priority_Specific_Dispatching::
1322 * Pragma Profile_Warnings::
1323 * Pragma Propagate_Exceptions::
1324 * Pragma Provide_Shift_Operators::
1325 * Pragma Psect_Object::
1326 * Pragma Pure_Function::
1328 * Pragma Ravenscar::
1329 * Pragma Refined_Depends::
1330 * Pragma Refined_Global::
1331 * Pragma Refined_Post::
1332 * Pragma Refined_State::
1333 * Pragma Relative_Deadline::
1334 * Pragma Remote_Access_Type::
1335 * Pragma Restricted_Run_Time::
1336 * Pragma Restriction_Warnings::
1337 * Pragma Reviewable::
1338 * Pragma Secondary_Stack_Size::
1339 * Pragma Share_Generic::
1341 * Pragma Short_Circuit_And_Or::
1342 * Pragma Short_Descriptors::
1343 * Pragma Simple_Storage_Pool_Type::
1344 * Pragma Source_File_Name::
1345 * Pragma Source_File_Name_Project::
1346 * Pragma Source_Reference::
1347 * Pragma SPARK_Mode::
1348 * Pragma Static_Elaboration_Desired::
1349 * Pragma Stream_Convert::
1350 * Pragma Style_Checks::
1353 * Pragma Suppress_All::
1354 * Pragma Suppress_Debug_Info::
1355 * Pragma Suppress_Exception_Locations::
1356 * Pragma Suppress_Initialization::
1357 * Pragma Task_Name::
1358 * Pragma Task_Storage::
1359 * Pragma Test_Case::
1360 * Pragma Thread_Local_Storage::
1361 * Pragma Time_Slice::
1363 * Pragma Type_Invariant::
1364 * Pragma Type_Invariant_Class::
1365 * Pragma Unchecked_Union::
1366 * Pragma Unevaluated_Use_Of_Old::
1367 * Pragma Unimplemented_Unit::
1368 * Pragma Universal_Aliasing::
1369 * Pragma Universal_Data::
1370 * Pragma Unmodified::
1371 * Pragma Unreferenced::
1372 * Pragma Unreferenced_Objects::
1373 * Pragma Unreserve_All_Interrupts::
1374 * Pragma Unsuppress::
1375 * Pragma Use_VADS_Size::
1377 * Pragma Validity_Checks::
1379 * Pragma Volatile_Full_Access::
1380 * Pragma Volatile_Function::
1381 * Pragma Warning_As_Error::
1383 * Pragma Weak_External::
1384 * Pragma Wide_Character_Encoding::
1388 @node Pragma Abort_Defer,Pragma Abstract_State,,Implementation Defined Pragmas
1389 @anchor{gnat_rm/implementation_defined_pragmas pragma-abort-defer}@anchor{1b}
1390 @section Pragma Abort_Defer
1393 @geindex Deferring aborts
1401 This pragma must appear at the start of the statement sequence of a
1402 handled sequence of statements (right after the @code{begin}). It has
1403 the effect of deferring aborts for the sequence of statements (but not
1404 for the declarations or handlers, if any, associated with this statement
1407 @node Pragma Abstract_State,Pragma Acc_Parallel,Pragma Abort_Defer,Implementation Defined Pragmas
1408 @anchor{gnat_rm/implementation_defined_pragmas pragma-abstract-state}@anchor{1c}@anchor{gnat_rm/implementation_defined_pragmas id2}@anchor{1d}
1409 @section Pragma Abstract_State
1415 pragma Abstract_State (ABSTRACT_STATE_LIST);
1417 ABSTRACT_STATE_LIST ::=
1419 | STATE_NAME_WITH_OPTIONS
1420 | (STATE_NAME_WITH_OPTIONS @{, STATE_NAME_WITH_OPTIONS@} )
1422 STATE_NAME_WITH_OPTIONS ::=
1424 | (STATE_NAME with OPTION_LIST)
1426 OPTION_LIST ::= OPTION @{, OPTION@}
1432 SIMPLE_OPTION ::= Ghost | Synchronous
1434 NAME_VALUE_OPTION ::=
1435 Part_Of => ABSTRACT_STATE
1436 | External [=> EXTERNAL_PROPERTY_LIST]
1438 EXTERNAL_PROPERTY_LIST ::=
1440 | (EXTERNAL_PROPERTY @{, EXTERNAL_PROPERTY@} )
1442 EXTERNAL_PROPERTY ::=
1443 Async_Readers [=> boolean_EXPRESSION]
1444 | Async_Writers [=> boolean_EXPRESSION]
1445 | Effective_Reads [=> boolean_EXPRESSION]
1446 | Effective_Writes [=> boolean_EXPRESSION]
1447 others => boolean_EXPRESSION
1449 STATE_NAME ::= defining_identifier
1451 ABSTRACT_STATE ::= name
1454 For the semantics of this pragma, see the entry for aspect @code{Abstract_State} in
1455 the SPARK 2014 Reference Manual, section 7.1.4.
1457 @node Pragma Acc_Parallel,Pragma Acc_Loop,Pragma Abstract_State,Implementation Defined Pragmas
1458 @anchor{gnat_rm/implementation_defined_pragmas pragma-acc-parallel}@anchor{1e}
1459 @section Pragma Acc_Parallel
1465 pragma Acc_Parallel [( ACC_PARALLEL_CLAUSE [, ACC_PARALLEL_CLAUSE... ])];
1467 ACC_PARALLEL_CLAUSE ::=
1468 Acc_If => boolean_EXPRESSION
1469 | Acc_Private => IDENTIFIERS
1470 | Async => integer_EXPRESSION
1471 | Copy => IDENTIFIERS
1472 | Copy_In => IDENTIFIERS
1473 | Copy_Out => IDENTIFIERS
1474 | Create => IDENTIFIERS
1476 | Device_Ptr => IDENTIFIERS
1477 | First_Private => IDENTIFIERS
1478 | Num_Gangs => integer_EXPRESSION
1479 | Num_Workers => integer_EXPRESSION
1480 | Present => IDENTIFIERS
1481 | Reduction => (REDUCTION_RECORD)
1482 | Vector_Length => integer_EXPRESSION
1485 REDUCTION_RECORD ::=
1487 | "*" => IDENTIFIERS
1488 | "min" => IDENTIFIERS
1489 | "max" => IDENTIFIERS
1490 | "or" => IDENTIFIERS
1491 | "and" => IDENTIFIERS
1495 | (IDENTIFIER, IDENTIFIERS)
1498 | integer_EXPRESSION
1499 | (integer_EXPRESSION, INTEGERS)
1502 Requires the @code{-fopenacc} flag.
1504 Equivalent to the @code{parallel} directive of the OpenAcc standard. This pragma
1505 should be placed in loops. It offloads the content of the loop to an
1508 For more information about the effect of the clauses, see the OpenAcc
1511 @node Pragma Acc_Loop,Pragma Acc_Kernels,Pragma Acc_Parallel,Implementation Defined Pragmas
1512 @anchor{gnat_rm/implementation_defined_pragmas pragma-acc-loop}@anchor{1f}
1513 @section Pragma Acc_Loop
1519 pragma Acc_Loop [( ACC_LOOP_CLAUSE [, ACC_LOOP_CLAUSE... ])];
1523 | Collapse => INTEGER_LITERAL
1524 | Gang [=> GANG_ARG]
1526 | Private => IDENTIFIERS
1527 | Reduction => (REDUCTION_RECORD)
1529 | Tile => SIZE_EXPRESSION
1530 | Vector [=> integer_EXPRESSION]
1531 | Worker [=> integer_EXPRESSION]
1535 | Static => SIZE_EXPRESSION
1539 | integer_EXPRESSION
1542 Requires the @code{-fopenacc} flag.
1544 Equivalent to the @code{loop} directive of the OpenAcc standard. This pragma
1545 should be placed in for loops after the "Acc_Parallel" pragma. It tells the
1546 compiler how to parallelize the loop.
1548 For more information about the effect of the clauses, see the OpenAcc
1551 @node Pragma Acc_Kernels,Pragma Acc_Data,Pragma Acc_Loop,Implementation Defined Pragmas
1552 @anchor{gnat_rm/implementation_defined_pragmas pragma-acc-kernels}@anchor{20}
1553 @section Pragma Acc_Kernels
1559 pragma Acc_Kernels [( ACC_KERNELS_CLAUSE [, ACC_KERNELS_CLAUSE...])];
1561 ACC_KERNELS_CLAUSE ::=
1562 Acc_If => boolean_EXPRESSION
1563 | Async => integer_EXPRESSION
1564 | Copy => IDENTIFIERS
1565 | Copy_In => IDENTIFIERS
1566 | Copy_Out => IDENTIFIERS
1567 | Create => IDENTIFIERS
1569 | Device_Ptr => IDENTIFIERS
1570 | Num_Gangs => integer_EXPRESSION
1571 | Num_Workers => integer_EXPRESSION
1572 | Present => IDENTIFIERS
1573 | Vector_Length => integer_EXPRESSION
1578 | (IDENTIFIER, IDENTIFIERS)
1581 | integer_EXPRESSION
1582 | (integer_EXPRESSION, INTEGERS)
1585 Requires the @code{-fopenacc} flag.
1587 Equivalent to the kernels directive of the OpenAcc standard. This pragma should
1590 For more information about the effect of the clauses, see the OpenAcc
1593 @node Pragma Acc_Data,Pragma Ada_83,Pragma Acc_Kernels,Implementation Defined Pragmas
1594 @anchor{gnat_rm/implementation_defined_pragmas pragma-acc-data}@anchor{21}
1595 @section Pragma Acc_Data
1601 pragma Acc_Data ([ ACC_DATA_CLAUSE [, ACC_DATA_CLAUSE...]]);
1605 | Copy_In => IDENTIFIERS
1606 | Copy_Out => IDENTIFIERS
1607 | Create => IDENTIFIERS
1608 | Device_Ptr => IDENTIFIERS
1609 | Present => IDENTIFIERS
1612 Requires the @code{-fopenacc} flag.
1614 Equivalent to the @code{data} directive of the OpenAcc standard. This pragma
1615 should be placed in loops.
1617 For more information about the effect of the clauses, see the OpenAcc
1620 @node Pragma Ada_83,Pragma Ada_95,Pragma Acc_Data,Implementation Defined Pragmas
1621 @anchor{gnat_rm/implementation_defined_pragmas pragma-ada-83}@anchor{22}
1622 @section Pragma Ada_83
1631 A configuration pragma that establishes Ada 83 mode for the unit to
1632 which it applies, regardless of the mode set by the command line
1633 switches. In Ada 83 mode, GNAT attempts to be as compatible with
1634 the syntax and semantics of Ada 83, as defined in the original Ada
1635 83 Reference Manual as possible. In particular, the keywords added by Ada 95
1636 and Ada 2005 are not recognized, optional package bodies are allowed,
1637 and generics may name types with unknown discriminants without using
1638 the @code{(<>)} notation. In addition, some but not all of the additional
1639 restrictions of Ada 83 are enforced.
1641 Ada 83 mode is intended for two purposes. Firstly, it allows existing
1642 Ada 83 code to be compiled and adapted to GNAT with less effort.
1643 Secondly, it aids in keeping code backwards compatible with Ada 83.
1644 However, there is no guarantee that code that is processed correctly
1645 by GNAT in Ada 83 mode will in fact compile and execute with an Ada
1646 83 compiler, since GNAT does not enforce all the additional checks
1649 @node Pragma Ada_95,Pragma Ada_05,Pragma Ada_83,Implementation Defined Pragmas
1650 @anchor{gnat_rm/implementation_defined_pragmas pragma-ada-95}@anchor{23}
1651 @section Pragma Ada_95
1660 A configuration pragma that establishes Ada 95 mode for the unit to which
1661 it applies, regardless of the mode set by the command line switches.
1662 This mode is set automatically for the @code{Ada} and @code{System}
1663 packages and their children, so you need not specify it in these
1664 contexts. This pragma is useful when writing a reusable component that
1665 itself uses Ada 95 features, but which is intended to be usable from
1666 either Ada 83 or Ada 95 programs.
1668 @node Pragma Ada_05,Pragma Ada_2005,Pragma Ada_95,Implementation Defined Pragmas
1669 @anchor{gnat_rm/implementation_defined_pragmas pragma-ada-05}@anchor{24}
1670 @section Pragma Ada_05
1677 pragma Ada_05 (local_NAME);
1680 A configuration pragma that establishes Ada 2005 mode for the unit to which
1681 it applies, regardless of the mode set by the command line switches.
1682 This pragma is useful when writing a reusable component that
1683 itself uses Ada 2005 features, but which is intended to be usable from
1684 either Ada 83 or Ada 95 programs.
1686 The one argument form (which is not a configuration pragma)
1687 is used for managing the transition from
1688 Ada 95 to Ada 2005 in the run-time library. If an entity is marked
1689 as Ada_2005 only, then referencing the entity in Ada_83 or Ada_95
1690 mode will generate a warning. In addition, in Ada_83 or Ada_95
1691 mode, a preference rule is established which does not choose
1692 such an entity unless it is unambiguously specified. This avoids
1693 extra subprograms marked this way from generating ambiguities in
1694 otherwise legal pre-Ada_2005 programs. The one argument form is
1695 intended for exclusive use in the GNAT run-time library.
1697 @node Pragma Ada_2005,Pragma Ada_12,Pragma Ada_05,Implementation Defined Pragmas
1698 @anchor{gnat_rm/implementation_defined_pragmas pragma-ada-2005}@anchor{25}
1699 @section Pragma Ada_2005
1708 This configuration pragma is a synonym for pragma Ada_05 and has the
1709 same syntax and effect.
1711 @node Pragma Ada_12,Pragma Ada_2012,Pragma Ada_2005,Implementation Defined Pragmas
1712 @anchor{gnat_rm/implementation_defined_pragmas pragma-ada-12}@anchor{26}
1713 @section Pragma Ada_12
1720 pragma Ada_12 (local_NAME);
1723 A configuration pragma that establishes Ada 2012 mode for the unit to which
1724 it applies, regardless of the mode set by the command line switches.
1725 This mode is set automatically for the @code{Ada} and @code{System}
1726 packages and their children, so you need not specify it in these
1727 contexts. This pragma is useful when writing a reusable component that
1728 itself uses Ada 2012 features, but which is intended to be usable from
1729 Ada 83, Ada 95, or Ada 2005 programs.
1731 The one argument form, which is not a configuration pragma,
1732 is used for managing the transition from Ada
1733 2005 to Ada 2012 in the run-time library. If an entity is marked
1734 as Ada_2012 only, then referencing the entity in any pre-Ada_2012
1735 mode will generate a warning. In addition, in any pre-Ada_2012
1736 mode, a preference rule is established which does not choose
1737 such an entity unless it is unambiguously specified. This avoids
1738 extra subprograms marked this way from generating ambiguities in
1739 otherwise legal pre-Ada_2012 programs. The one argument form is
1740 intended for exclusive use in the GNAT run-time library.
1742 @node Pragma Ada_2012,Pragma Aggregate_Individually_Assign,Pragma Ada_12,Implementation Defined Pragmas
1743 @anchor{gnat_rm/implementation_defined_pragmas pragma-ada-2012}@anchor{27}
1744 @section Pragma Ada_2012
1753 This configuration pragma is a synonym for pragma Ada_12 and has the
1754 same syntax and effect.
1756 @node Pragma Aggregate_Individually_Assign,Pragma Allow_Integer_Address,Pragma Ada_2012,Implementation Defined Pragmas
1757 @anchor{gnat_rm/implementation_defined_pragmas pragma-aggregate-individually-assign}@anchor{28}
1758 @section Pragma Aggregate_Individually_Assign
1764 pragma Aggregate_Individually_Assign;
1767 Where possible GNAT will store the binary representation of a record aggregate
1768 in memory for space and performance reasons. This configuration pragma changes
1769 this behaviour so that record aggregates are instead always converted into
1770 individual assignment statements.
1772 @node Pragma Allow_Integer_Address,Pragma Annotate,Pragma Aggregate_Individually_Assign,Implementation Defined Pragmas
1773 @anchor{gnat_rm/implementation_defined_pragmas pragma-allow-integer-address}@anchor{29}
1774 @section Pragma Allow_Integer_Address
1780 pragma Allow_Integer_Address;
1783 In almost all versions of GNAT, @code{System.Address} is a private
1784 type in accordance with the implementation advice in the RM. This
1785 means that integer values,
1786 in particular integer literals, are not allowed as address values.
1787 If the configuration pragma
1788 @code{Allow_Integer_Address} is given, then integer expressions may
1789 be used anywhere a value of type @code{System.Address} is required.
1790 The effect is to introduce an implicit unchecked conversion from the
1791 integer value to type @code{System.Address}. The reverse case of using
1792 an address where an integer type is required is handled analogously.
1793 The following example compiles without errors:
1796 pragma Allow_Integer_Address;
1797 with System; use System;
1798 package AddrAsInt is
1801 for X'Address use 16#1240#;
1802 for Y use at 16#3230#;
1803 m : Address := 16#4000#;
1804 n : constant Address := 4000;
1805 p : constant Address := Address (X + Y);
1806 v : Integer := y'Address;
1807 w : constant Integer := Integer (Y'Address);
1808 type R is new integer;
1811 for Z'Address use RR;
1815 Note that pragma @code{Allow_Integer_Address} is ignored if @code{System.Address}
1816 is not a private type. In implementations of @code{GNAT} where
1817 System.Address is a visible integer type,
1818 this pragma serves no purpose but is ignored
1819 rather than rejected to allow common sets of sources to be used
1820 in the two situations.
1822 @node Pragma Annotate,Pragma Assert,Pragma Allow_Integer_Address,Implementation Defined Pragmas
1823 @anchor{gnat_rm/implementation_defined_pragmas pragma-annotate}@anchor{2a}@anchor{gnat_rm/implementation_defined_pragmas id3}@anchor{2b}
1824 @section Pragma Annotate
1830 pragma Annotate (IDENTIFIER [, IDENTIFIER @{, ARG@}] [, entity => local_NAME]);
1832 ARG ::= NAME | EXPRESSION
1835 This pragma is used to annotate programs. IDENTIFIER identifies
1836 the type of annotation. GNAT verifies that it is an identifier, but does
1837 not otherwise analyze it. The second optional identifier is also left
1838 unanalyzed, and by convention is used to control the action of the tool to
1839 which the annotation is addressed. The remaining ARG arguments
1840 can be either string literals or more generally expressions.
1841 String literals are assumed to be either of type
1842 @code{Standard.String} or else @code{Wide_String} or @code{Wide_Wide_String}
1843 depending on the character literals they contain.
1844 All other kinds of arguments are analyzed as expressions, and must be
1845 unambiguous. The last argument if present must have the identifier
1846 @code{Entity} and GNAT verifies that a local name is given.
1848 The analyzed pragma is retained in the tree, but not otherwise processed
1849 by any part of the GNAT compiler, except to generate corresponding note
1850 lines in the generated ALI file. For the format of these note lines, see
1851 the compiler source file lib-writ.ads. This pragma is intended for use by
1852 external tools, including ASIS. The use of pragma Annotate does not
1853 affect the compilation process in any way. This pragma may be used as
1854 a configuration pragma.
1856 @node Pragma Assert,Pragma Assert_And_Cut,Pragma Annotate,Implementation Defined Pragmas
1857 @anchor{gnat_rm/implementation_defined_pragmas pragma-assert}@anchor{2c}
1858 @section Pragma Assert
1866 [, string_EXPRESSION]);
1869 The effect of this pragma depends on whether the corresponding command
1870 line switch is set to activate assertions. The pragma expands into code
1871 equivalent to the following:
1874 if assertions-enabled then
1875 if not boolean_EXPRESSION then
1876 System.Assertions.Raise_Assert_Failure
1877 (string_EXPRESSION);
1882 The string argument, if given, is the message that will be associated
1883 with the exception occurrence if the exception is raised. If no second
1884 argument is given, the default message is @code{file}:@code{nnn},
1885 where @code{file} is the name of the source file containing the assert,
1886 and @code{nnn} is the line number of the assert.
1888 Note that, as with the @code{if} statement to which it is equivalent, the
1889 type of the expression is either @code{Standard.Boolean}, or any type derived
1890 from this standard type.
1892 Assert checks can be either checked or ignored. By default they are ignored.
1893 They will be checked if either the command line switch @emph{-gnata} is
1894 used, or if an @code{Assertion_Policy} or @code{Check_Policy} pragma is used
1895 to enable @code{Assert_Checks}.
1897 If assertions are ignored, then there
1898 is no run-time effect (and in particular, any side effects from the
1899 expression will not occur at run time). (The expression is still
1900 analyzed at compile time, and may cause types to be frozen if they are
1901 mentioned here for the first time).
1903 If assertions are checked, then the given expression is tested, and if
1904 it is @code{False} then @code{System.Assertions.Raise_Assert_Failure} is called
1905 which results in the raising of @code{Assert_Failure} with the given message.
1907 You should generally avoid side effects in the expression arguments of
1908 this pragma, because these side effects will turn on and off with the
1909 setting of the assertions mode, resulting in assertions that have an
1910 effect on the program. However, the expressions are analyzed for
1911 semantic correctness whether or not assertions are enabled, so turning
1912 assertions on and off cannot affect the legality of a program.
1914 Note that the implementation defined policy @code{DISABLE}, given in a
1915 pragma @code{Assertion_Policy}, can be used to suppress this semantic analysis.
1917 Note: this is a standard language-defined pragma in versions
1918 of Ada from 2005 on. In GNAT, it is implemented in all versions
1919 of Ada, and the DISABLE policy is an implementation-defined
1922 @node Pragma Assert_And_Cut,Pragma Assertion_Policy,Pragma Assert,Implementation Defined Pragmas
1923 @anchor{gnat_rm/implementation_defined_pragmas pragma-assert-and-cut}@anchor{2d}
1924 @section Pragma Assert_And_Cut
1930 pragma Assert_And_Cut (
1932 [, string_EXPRESSION]);
1935 The effect of this pragma is identical to that of pragma @code{Assert},
1936 except that in an @code{Assertion_Policy} pragma, the identifier
1937 @code{Assert_And_Cut} is used to control whether it is ignored or checked
1940 The intention is that this be used within a subprogram when the
1941 given test expresion sums up all the work done so far in the
1942 subprogram, so that the rest of the subprogram can be verified
1943 (informally or formally) using only the entry preconditions,
1944 and the expression in this pragma. This allows dividing up
1945 a subprogram into sections for the purposes of testing or
1946 formal verification. The pragma also serves as useful
1949 @node Pragma Assertion_Policy,Pragma Assume,Pragma Assert_And_Cut,Implementation Defined Pragmas
1950 @anchor{gnat_rm/implementation_defined_pragmas pragma-assertion-policy}@anchor{2e}
1951 @section Pragma Assertion_Policy
1957 pragma Assertion_Policy (CHECK | DISABLE | IGNORE | SUPPRESSIBLE);
1959 pragma Assertion_Policy (
1960 ASSERTION_KIND => POLICY_IDENTIFIER
1961 @{, ASSERTION_KIND => POLICY_IDENTIFIER@});
1963 ASSERTION_KIND ::= RM_ASSERTION_KIND | ID_ASSERTION_KIND
1965 RM_ASSERTION_KIND ::= Assert |
1973 Type_Invariant'Class
1975 ID_ASSERTION_KIND ::= Assertions |
1989 Statement_Assertions
1991 POLICY_IDENTIFIER ::= Check | Disable | Ignore | Suppressible
1994 This is a standard Ada 2012 pragma that is available as an
1995 implementation-defined pragma in earlier versions of Ada.
1996 The assertion kinds @code{RM_ASSERTION_KIND} are those defined in
1997 the Ada standard. The assertion kinds @code{ID_ASSERTION_KIND}
1998 are implementation defined additions recognized by the GNAT compiler.
2000 The pragma applies in both cases to pragmas and aspects with matching
2001 names, e.g. @code{Pre} applies to the Pre aspect, and @code{Precondition}
2002 applies to both the @code{Precondition} pragma
2003 and the aspect @code{Precondition}. Note that the identifiers for
2004 pragmas Pre_Class and Post_Class are Pre'Class and Post'Class (not
2005 Pre_Class and Post_Class), since these pragmas are intended to be
2006 identical to the corresponding aspects).
2008 If the policy is @code{CHECK}, then assertions are enabled, i.e.
2009 the corresponding pragma or aspect is activated.
2010 If the policy is @code{IGNORE}, then assertions are ignored, i.e.
2011 the corresponding pragma or aspect is deactivated.
2012 This pragma overrides the effect of the @emph{-gnata} switch on the
2014 If the policy is @code{SUPPRESSIBLE}, then assertions are enabled by default,
2015 however, if the @emph{-gnatp} switch is specified all assertions are ignored.
2017 The implementation defined policy @code{DISABLE} is like
2018 @code{IGNORE} except that it completely disables semantic
2019 checking of the corresponding pragma or aspect. This is
2020 useful when the pragma or aspect argument references subprograms
2021 in a with'ed package which is replaced by a dummy package
2022 for the final build.
2024 The implementation defined assertion kind @code{Assertions} applies to all
2025 assertion kinds. The form with no assertion kind given implies this
2026 choice, so it applies to all assertion kinds (RM defined, and
2027 implementation defined).
2029 The implementation defined assertion kind @code{Statement_Assertions}
2030 applies to @code{Assert}, @code{Assert_And_Cut},
2031 @code{Assume}, @code{Loop_Invariant}, and @code{Loop_Variant}.
2033 @node Pragma Assume,Pragma Assume_No_Invalid_Values,Pragma Assertion_Policy,Implementation Defined Pragmas
2034 @anchor{gnat_rm/implementation_defined_pragmas pragma-assume}@anchor{2f}
2035 @section Pragma Assume
2043 [, string_EXPRESSION]);
2046 The effect of this pragma is identical to that of pragma @code{Assert},
2047 except that in an @code{Assertion_Policy} pragma, the identifier
2048 @code{Assume} is used to control whether it is ignored or checked
2051 The intention is that this be used for assumptions about the
2052 external environment. So you cannot expect to verify formally
2053 or informally that the condition is met, this must be
2054 established by examining things outside the program itself.
2055 For example, we may have code that depends on the size of
2056 @code{Long_Long_Integer} being at least 64. So we could write:
2059 pragma Assume (Long_Long_Integer'Size >= 64);
2062 This assumption cannot be proved from the program itself,
2063 but it acts as a useful run-time check that the assumption
2064 is met, and documents the need to ensure that it is met by
2065 reference to information outside the program.
2067 @node Pragma Assume_No_Invalid_Values,Pragma Async_Readers,Pragma Assume,Implementation Defined Pragmas
2068 @anchor{gnat_rm/implementation_defined_pragmas pragma-assume-no-invalid-values}@anchor{30}
2069 @section Pragma Assume_No_Invalid_Values
2072 @geindex Invalid representations
2074 @geindex Invalid values
2079 pragma Assume_No_Invalid_Values (On | Off);
2082 This is a configuration pragma that controls the assumptions made by the
2083 compiler about the occurrence of invalid representations (invalid values)
2086 The default behavior (corresponding to an Off argument for this pragma), is
2087 to assume that values may in general be invalid unless the compiler can
2088 prove they are valid. Consider the following example:
2091 V1 : Integer range 1 .. 10;
2092 V2 : Integer range 11 .. 20;
2094 for J in V2 .. V1 loop
2099 if V1 and V2 have valid values, then the loop is known at compile
2100 time not to execute since the lower bound must be greater than the
2101 upper bound. However in default mode, no such assumption is made,
2102 and the loop may execute. If @code{Assume_No_Invalid_Values (On)}
2103 is given, the compiler will assume that any occurrence of a variable
2104 other than in an explicit @code{'Valid} test always has a valid
2105 value, and the loop above will be optimized away.
2107 The use of @code{Assume_No_Invalid_Values (On)} is appropriate if
2108 you know your code is free of uninitialized variables and other
2109 possible sources of invalid representations, and may result in
2110 more efficient code. A program that accesses an invalid representation
2111 with this pragma in effect is erroneous, so no guarantees can be made
2114 It is peculiar though permissible to use this pragma in conjunction
2115 with validity checking (-gnatVa). In such cases, accessing invalid
2116 values will generally give an exception, though formally the program
2117 is erroneous so there are no guarantees that this will always be the
2118 case, and it is recommended that these two options not be used together.
2120 @node Pragma Async_Readers,Pragma Async_Writers,Pragma Assume_No_Invalid_Values,Implementation Defined Pragmas
2121 @anchor{gnat_rm/implementation_defined_pragmas pragma-async-readers}@anchor{31}@anchor{gnat_rm/implementation_defined_pragmas id4}@anchor{32}
2122 @section Pragma Async_Readers
2128 pragma Async_Readers [ (boolean_EXPRESSION) ];
2131 For the semantics of this pragma, see the entry for aspect @code{Async_Readers} in
2132 the SPARK 2014 Reference Manual, section 7.1.2.
2134 @node Pragma Async_Writers,Pragma Attribute_Definition,Pragma Async_Readers,Implementation Defined Pragmas
2135 @anchor{gnat_rm/implementation_defined_pragmas id5}@anchor{33}@anchor{gnat_rm/implementation_defined_pragmas pragma-async-writers}@anchor{34}
2136 @section Pragma Async_Writers
2142 pragma Async_Writers [ (boolean_EXPRESSION) ];
2145 For the semantics of this pragma, see the entry for aspect @code{Async_Writers} in
2146 the SPARK 2014 Reference Manual, section 7.1.2.
2148 @node Pragma Attribute_Definition,Pragma C_Pass_By_Copy,Pragma Async_Writers,Implementation Defined Pragmas
2149 @anchor{gnat_rm/implementation_defined_pragmas pragma-attribute-definition}@anchor{35}
2150 @section Pragma Attribute_Definition
2156 pragma Attribute_Definition
2157 ([Attribute =>] ATTRIBUTE_DESIGNATOR,
2158 [Entity =>] LOCAL_NAME,
2159 [Expression =>] EXPRESSION | NAME);
2162 If @code{Attribute} is a known attribute name, this pragma is equivalent to
2163 the attribute definition clause:
2166 for Entity'Attribute use Expression;
2169 If @code{Attribute} is not a recognized attribute name, the pragma is
2170 ignored, and a warning is emitted. This allows source
2171 code to be written that takes advantage of some new attribute, while remaining
2172 compilable with earlier compilers.
2174 @node Pragma C_Pass_By_Copy,Pragma Check,Pragma Attribute_Definition,Implementation Defined Pragmas
2175 @anchor{gnat_rm/implementation_defined_pragmas pragma-c-pass-by-copy}@anchor{36}
2176 @section Pragma C_Pass_By_Copy
2179 @geindex Passing by copy
2184 pragma C_Pass_By_Copy
2185 ([Max_Size =>] static_integer_EXPRESSION);
2188 Normally the default mechanism for passing C convention records to C
2189 convention subprograms is to pass them by reference, as suggested by RM
2190 B.3(69). Use the configuration pragma @code{C_Pass_By_Copy} to change
2191 this default, by requiring that record formal parameters be passed by
2192 copy if all of the following conditions are met:
2198 The size of the record type does not exceed the value specified for
2202 The record type has @code{Convention C}.
2205 The formal parameter has this record type, and the subprogram has a
2206 foreign (non-Ada) convention.
2209 If these conditions are met the argument is passed by copy; i.e., in a
2210 manner consistent with what C expects if the corresponding formal in the
2211 C prototype is a struct (rather than a pointer to a struct).
2213 You can also pass records by copy by specifying the convention
2214 @code{C_Pass_By_Copy} for the record type, or by using the extended
2215 @code{Import} and @code{Export} pragmas, which allow specification of
2216 passing mechanisms on a parameter by parameter basis.
2218 @node Pragma Check,Pragma Check_Float_Overflow,Pragma C_Pass_By_Copy,Implementation Defined Pragmas
2219 @anchor{gnat_rm/implementation_defined_pragmas pragma-check}@anchor{37}
2220 @section Pragma Check
2225 @geindex Named assertions
2231 [Name =>] CHECK_KIND,
2232 [Check =>] Boolean_EXPRESSION
2233 [, [Message =>] string_EXPRESSION] );
2235 CHECK_KIND ::= IDENTIFIER |
2238 Type_Invariant'Class |
2242 This pragma is similar to the predefined pragma @code{Assert} except that an
2243 extra identifier argument is present. In conjunction with pragma
2244 @code{Check_Policy}, this can be used to define groups of assertions that can
2245 be independently controlled. The identifier @code{Assertion} is special, it
2246 refers to the normal set of pragma @code{Assert} statements.
2248 Checks introduced by this pragma are normally deactivated by default. They can
2249 be activated either by the command line option @emph{-gnata}, which turns on
2250 all checks, or individually controlled using pragma @code{Check_Policy}.
2252 The identifiers @code{Assertions} and @code{Statement_Assertions} are not
2253 permitted as check kinds, since this would cause confusion with the use
2254 of these identifiers in @code{Assertion_Policy} and @code{Check_Policy}
2255 pragmas, where they are used to refer to sets of assertions.
2257 @node Pragma Check_Float_Overflow,Pragma Check_Name,Pragma Check,Implementation Defined Pragmas
2258 @anchor{gnat_rm/implementation_defined_pragmas pragma-check-float-overflow}@anchor{38}
2259 @section Pragma Check_Float_Overflow
2262 @geindex Floating-point overflow
2267 pragma Check_Float_Overflow;
2270 In Ada, the predefined floating-point types (@code{Short_Float},
2271 @code{Float}, @code{Long_Float}, @code{Long_Long_Float}) are
2272 defined to be @emph{unconstrained}. This means that even though each
2273 has a well-defined base range, an operation that delivers a result
2274 outside this base range is not required to raise an exception.
2275 This implementation permission accommodates the notion
2276 of infinities in IEEE floating-point, and corresponds to the
2277 efficient execution mode on most machines. GNAT will not raise
2278 overflow exceptions on these machines; instead it will generate
2279 infinities and NaN's as defined in the IEEE standard.
2281 Generating infinities, although efficient, is not always desirable.
2282 Often the preferable approach is to check for overflow, even at the
2283 (perhaps considerable) expense of run-time performance.
2284 This can be accomplished by defining your own constrained floating-point subtypes -- i.e., by supplying explicit
2285 range constraints -- and indeed such a subtype
2286 can have the same base range as its base type. For example:
2289 subtype My_Float is Float range Float'Range;
2292 Here @code{My_Float} has the same range as
2293 @code{Float} but is constrained, so operations on
2294 @code{My_Float} values will be checked for overflow
2297 This style will achieve the desired goal, but
2298 it is often more convenient to be able to simply use
2299 the standard predefined floating-point types as long
2300 as overflow checking could be guaranteed.
2301 The @code{Check_Float_Overflow}
2302 configuration pragma achieves this effect. If a unit is compiled
2303 subject to this configuration pragma, then all operations
2304 on predefined floating-point types including operations on
2305 base types of these floating-point types will be treated as
2306 though those types were constrained, and overflow checks
2307 will be generated. The @code{Constraint_Error}
2308 exception is raised if the result is out of range.
2310 This mode can also be set by use of the compiler
2311 switch @emph{-gnateF}.
2313 @node Pragma Check_Name,Pragma Check_Policy,Pragma Check_Float_Overflow,Implementation Defined Pragmas
2314 @anchor{gnat_rm/implementation_defined_pragmas pragma-check-name}@anchor{39}
2315 @section Pragma Check_Name
2318 @geindex Defining check names
2320 @geindex Check names
2326 pragma Check_Name (check_name_IDENTIFIER);
2329 This is a configuration pragma that defines a new implementation
2330 defined check name (unless IDENTIFIER matches one of the predefined
2331 check names, in which case the pragma has no effect). Check names
2332 are global to a partition, so if two or more configuration pragmas
2333 are present in a partition mentioning the same name, only one new
2334 check name is introduced.
2336 An implementation defined check name introduced with this pragma may
2337 be used in only three contexts: @code{pragma Suppress},
2338 @code{pragma Unsuppress},
2339 and as the prefix of a @code{Check_Name'Enabled} attribute reference. For
2340 any of these three cases, the check name must be visible. A check
2341 name is visible if it is in the configuration pragmas applying to
2342 the current unit, or if it appears at the start of any unit that
2343 is part of the dependency set of the current unit (e.g., units that
2344 are mentioned in @code{with} clauses).
2346 Check names introduced by this pragma are subject to control by compiler
2347 switches (in particular -gnatp) in the usual manner.
2349 @node Pragma Check_Policy,Pragma Comment,Pragma Check_Name,Implementation Defined Pragmas
2350 @anchor{gnat_rm/implementation_defined_pragmas pragma-check-policy}@anchor{3a}
2351 @section Pragma Check_Policy
2354 @geindex Controlling assertions
2359 @geindex Check pragma control
2361 @geindex Named assertions
2367 ([Name =>] CHECK_KIND,
2368 [Policy =>] POLICY_IDENTIFIER);
2370 pragma Check_Policy (
2371 CHECK_KIND => POLICY_IDENTIFIER
2372 @{, CHECK_KIND => POLICY_IDENTIFIER@});
2374 ASSERTION_KIND ::= RM_ASSERTION_KIND | ID_ASSERTION_KIND
2376 CHECK_KIND ::= IDENTIFIER |
2379 Type_Invariant'Class |
2382 The identifiers Name and Policy are not allowed as CHECK_KIND values. This
2383 avoids confusion between the two possible syntax forms for this pragma.
2385 POLICY_IDENTIFIER ::= ON | OFF | CHECK | DISABLE | IGNORE
2388 This pragma is used to set the checking policy for assertions (specified
2389 by aspects or pragmas), the @code{Debug} pragma, or additional checks
2390 to be checked using the @code{Check} pragma. It may appear either as
2391 a configuration pragma, or within a declarative part of package. In the
2392 latter case, it applies from the point where it appears to the end of
2393 the declarative region (like pragma @code{Suppress}).
2395 The @code{Check_Policy} pragma is similar to the
2396 predefined @code{Assertion_Policy} pragma,
2397 and if the check kind corresponds to one of the assertion kinds that
2398 are allowed by @code{Assertion_Policy}, then the effect is identical.
2400 If the first argument is Debug, then the policy applies to Debug pragmas,
2401 disabling their effect if the policy is @code{OFF}, @code{DISABLE}, or
2402 @code{IGNORE}, and allowing them to execute with normal semantics if
2403 the policy is @code{ON} or @code{CHECK}. In addition if the policy is
2404 @code{DISABLE}, then the procedure call in @code{Debug} pragmas will
2405 be totally ignored and not analyzed semantically.
2407 Finally the first argument may be some other identifier than the above
2408 possibilities, in which case it controls a set of named assertions
2409 that can be checked using pragma @code{Check}. For example, if the pragma:
2412 pragma Check_Policy (Critical_Error, OFF);
2415 is given, then subsequent @code{Check} pragmas whose first argument is also
2416 @code{Critical_Error} will be disabled.
2418 The check policy is @code{OFF} to turn off corresponding checks, and @code{ON}
2419 to turn on corresponding checks. The default for a set of checks for which no
2420 @code{Check_Policy} is given is @code{OFF} unless the compiler switch
2421 @emph{-gnata} is given, which turns on all checks by default.
2423 The check policy settings @code{CHECK} and @code{IGNORE} are recognized
2424 as synonyms for @code{ON} and @code{OFF}. These synonyms are provided for
2425 compatibility with the standard @code{Assertion_Policy} pragma. The check
2426 policy setting @code{DISABLE} causes the second argument of a corresponding
2427 @code{Check} pragma to be completely ignored and not analyzed.
2429 @node Pragma Comment,Pragma Common_Object,Pragma Check_Policy,Implementation Defined Pragmas
2430 @anchor{gnat_rm/implementation_defined_pragmas pragma-comment}@anchor{3b}
2431 @section Pragma Comment
2437 pragma Comment (static_string_EXPRESSION);
2440 This is almost identical in effect to pragma @code{Ident}. It allows the
2441 placement of a comment into the object file and hence into the
2442 executable file if the operating system permits such usage. The
2443 difference is that @code{Comment}, unlike @code{Ident}, has
2444 no limitations on placement of the pragma (it can be placed
2445 anywhere in the main source unit), and if more than one pragma
2446 is used, all comments are retained.
2448 @node Pragma Common_Object,Pragma Compile_Time_Error,Pragma Comment,Implementation Defined Pragmas
2449 @anchor{gnat_rm/implementation_defined_pragmas pragma-common-object}@anchor{3c}
2450 @section Pragma Common_Object
2456 pragma Common_Object (
2457 [Internal =>] LOCAL_NAME
2458 [, [External =>] EXTERNAL_SYMBOL]
2459 [, [Size =>] EXTERNAL_SYMBOL] );
2463 | static_string_EXPRESSION
2466 This pragma enables the shared use of variables stored in overlaid
2467 linker areas corresponding to the use of @code{COMMON}
2468 in Fortran. The single
2469 object @code{LOCAL_NAME} is assigned to the area designated by
2470 the @code{External} argument.
2471 You may define a record to correspond to a series
2472 of fields. The @code{Size} argument
2473 is syntax checked in GNAT, but otherwise ignored.
2475 @code{Common_Object} is not supported on all platforms. If no
2476 support is available, then the code generator will issue a message
2477 indicating that the necessary attribute for implementation of this
2478 pragma is not available.
2480 @node Pragma Compile_Time_Error,Pragma Compile_Time_Warning,Pragma Common_Object,Implementation Defined Pragmas
2481 @anchor{gnat_rm/implementation_defined_pragmas pragma-compile-time-error}@anchor{3d}
2482 @section Pragma Compile_Time_Error
2488 pragma Compile_Time_Error
2489 (boolean_EXPRESSION, static_string_EXPRESSION);
2492 This pragma can be used to generate additional compile time
2494 is particularly useful in generics, where errors can be issued for
2495 specific problematic instantiations. The first parameter is a boolean
2496 expression. The pragma is effective only if the value of this expression
2497 is known at compile time, and has the value True. The set of expressions
2498 whose values are known at compile time includes all static boolean
2499 expressions, and also other values which the compiler can determine
2500 at compile time (e.g., the size of a record type set by an explicit
2501 size representation clause, or the value of a variable which was
2502 initialized to a constant and is known not to have been modified).
2503 If these conditions are met, an error message is generated using
2504 the value given as the second argument. This string value may contain
2505 embedded ASCII.LF characters to break the message into multiple lines.
2507 @node Pragma Compile_Time_Warning,Pragma Compiler_Unit,Pragma Compile_Time_Error,Implementation Defined Pragmas
2508 @anchor{gnat_rm/implementation_defined_pragmas pragma-compile-time-warning}@anchor{3e}
2509 @section Pragma Compile_Time_Warning
2515 pragma Compile_Time_Warning
2516 (boolean_EXPRESSION, static_string_EXPRESSION);
2519 Same as pragma Compile_Time_Error, except a warning is issued instead
2520 of an error message. Note that if this pragma is used in a package that
2521 is with'ed by a client, the client will get the warning even though it
2522 is issued by a with'ed package (normally warnings in with'ed units are
2523 suppressed, but this is a special exception to that rule).
2525 One typical use is within a generic where compile time known characteristics
2526 of formal parameters are tested, and warnings given appropriately. Another use
2527 with a first parameter of True is to warn a client about use of a package,
2528 for example that it is not fully implemented.
2530 @node Pragma Compiler_Unit,Pragma Compiler_Unit_Warning,Pragma Compile_Time_Warning,Implementation Defined Pragmas
2531 @anchor{gnat_rm/implementation_defined_pragmas pragma-compiler-unit}@anchor{3f}
2532 @section Pragma Compiler_Unit
2538 pragma Compiler_Unit;
2541 This pragma is obsolete. It is equivalent to Compiler_Unit_Warning. It is
2542 retained so that old versions of the GNAT run-time that use this pragma can
2543 be compiled with newer versions of the compiler.
2545 @node Pragma Compiler_Unit_Warning,Pragma Complete_Representation,Pragma Compiler_Unit,Implementation Defined Pragmas
2546 @anchor{gnat_rm/implementation_defined_pragmas pragma-compiler-unit-warning}@anchor{40}
2547 @section Pragma Compiler_Unit_Warning
2553 pragma Compiler_Unit_Warning;
2556 This pragma is intended only for internal use in the GNAT run-time library.
2557 It indicates that the unit is used as part of the compiler build. The effect
2558 is to generate warnings for the use of constructs (for example, conditional
2559 expressions) that would cause trouble when bootstrapping using an older
2560 version of GNAT. For the exact list of restrictions, see the compiler sources
2561 and references to Check_Compiler_Unit.
2563 @node Pragma Complete_Representation,Pragma Complex_Representation,Pragma Compiler_Unit_Warning,Implementation Defined Pragmas
2564 @anchor{gnat_rm/implementation_defined_pragmas pragma-complete-representation}@anchor{41}
2565 @section Pragma Complete_Representation
2571 pragma Complete_Representation;
2574 This pragma must appear immediately within a record representation
2575 clause. Typical placements are before the first component clause
2576 or after the last component clause. The effect is to give an error
2577 message if any component is missing a component clause. This pragma
2578 may be used to ensure that a record representation clause is
2579 complete, and that this invariant is maintained if fields are
2580 added to the record in the future.
2582 @node Pragma Complex_Representation,Pragma Component_Alignment,Pragma Complete_Representation,Implementation Defined Pragmas
2583 @anchor{gnat_rm/implementation_defined_pragmas pragma-complex-representation}@anchor{42}
2584 @section Pragma Complex_Representation
2590 pragma Complex_Representation
2591 ([Entity =>] LOCAL_NAME);
2594 The @code{Entity} argument must be the name of a record type which has
2595 two fields of the same floating-point type. The effect of this pragma is
2596 to force gcc to use the special internal complex representation form for
2597 this record, which may be more efficient. Note that this may result in
2598 the code for this type not conforming to standard ABI (application
2599 binary interface) requirements for the handling of record types. For
2600 example, in some environments, there is a requirement for passing
2601 records by pointer, and the use of this pragma may result in passing
2602 this type in floating-point registers.
2604 @node Pragma Component_Alignment,Pragma Constant_After_Elaboration,Pragma Complex_Representation,Implementation Defined Pragmas
2605 @anchor{gnat_rm/implementation_defined_pragmas pragma-component-alignment}@anchor{43}
2606 @section Pragma Component_Alignment
2609 @geindex Alignments of components
2611 @geindex Pragma Component_Alignment
2616 pragma Component_Alignment (
2617 [Form =>] ALIGNMENT_CHOICE
2618 [, [Name =>] type_LOCAL_NAME]);
2620 ALIGNMENT_CHOICE ::=
2627 Specifies the alignment of components in array or record types.
2628 The meaning of the @code{Form} argument is as follows:
2632 @geindex Component_Size (in pragma Component_Alignment)
2638 @item @emph{Component_Size}
2640 Aligns scalar components and subcomponents of the array or record type
2641 on boundaries appropriate to their inherent size (naturally
2642 aligned). For example, 1-byte components are aligned on byte boundaries,
2643 2-byte integer components are aligned on 2-byte boundaries, 4-byte
2644 integer components are aligned on 4-byte boundaries and so on. These
2645 alignment rules correspond to the normal rules for C compilers on all
2646 machines except the VAX.
2648 @geindex Component_Size_4 (in pragma Component_Alignment)
2650 @item @emph{Component_Size_4}
2652 Naturally aligns components with a size of four or fewer
2653 bytes. Components that are larger than 4 bytes are placed on the next
2656 @geindex Storage_Unit (in pragma Component_Alignment)
2658 @item @emph{Storage_Unit}
2660 Specifies that array or record components are byte aligned, i.e.,
2661 aligned on boundaries determined by the value of the constant
2662 @code{System.Storage_Unit}.
2664 @geindex Default (in pragma Component_Alignment)
2666 @item @emph{Default}
2668 Specifies that array or record components are aligned on default
2669 boundaries, appropriate to the underlying hardware or operating system or
2670 both. The @code{Default} choice is the same as @code{Component_Size} (natural
2674 If the @code{Name} parameter is present, @code{type_LOCAL_NAME} must
2675 refer to a local record or array type, and the specified alignment
2676 choice applies to the specified type. The use of
2677 @code{Component_Alignment} together with a pragma @code{Pack} causes the
2678 @code{Component_Alignment} pragma to be ignored. The use of
2679 @code{Component_Alignment} together with a record representation clause
2680 is only effective for fields not specified by the representation clause.
2682 If the @code{Name} parameter is absent, the pragma can be used as either
2683 a configuration pragma, in which case it applies to one or more units in
2684 accordance with the normal rules for configuration pragmas, or it can be
2685 used within a declarative part, in which case it applies to types that
2686 are declared within this declarative part, or within any nested scope
2687 within this declarative part. In either case it specifies the alignment
2688 to be applied to any record or array type which has otherwise standard
2691 If the alignment for a record or array type is not specified (using
2692 pragma @code{Pack}, pragma @code{Component_Alignment}, or a record rep
2693 clause), the GNAT uses the default alignment as described previously.
2695 @node Pragma Constant_After_Elaboration,Pragma Contract_Cases,Pragma Component_Alignment,Implementation Defined Pragmas
2696 @anchor{gnat_rm/implementation_defined_pragmas id6}@anchor{44}@anchor{gnat_rm/implementation_defined_pragmas pragma-constant-after-elaboration}@anchor{45}
2697 @section Pragma Constant_After_Elaboration
2703 pragma Constant_After_Elaboration [ (boolean_EXPRESSION) ];
2706 For the semantics of this pragma, see the entry for aspect
2707 @code{Constant_After_Elaboration} in the SPARK 2014 Reference Manual, section 3.3.1.
2709 @node Pragma Contract_Cases,Pragma Convention_Identifier,Pragma Constant_After_Elaboration,Implementation Defined Pragmas
2710 @anchor{gnat_rm/implementation_defined_pragmas id7}@anchor{46}@anchor{gnat_rm/implementation_defined_pragmas pragma-contract-cases}@anchor{47}
2711 @section Pragma Contract_Cases
2714 @geindex Contract cases
2719 pragma Contract_Cases ((CONTRACT_CASE @{, CONTRACT_CASE));
2721 CONTRACT_CASE ::= CASE_GUARD => CONSEQUENCE
2723 CASE_GUARD ::= boolean_EXPRESSION | others
2725 CONSEQUENCE ::= boolean_EXPRESSION
2728 The @code{Contract_Cases} pragma allows defining fine-grain specifications
2729 that can complement or replace the contract given by a precondition and a
2730 postcondition. Additionally, the @code{Contract_Cases} pragma can be used
2731 by testing and formal verification tools. The compiler checks its validity and,
2732 depending on the assertion policy at the point of declaration of the pragma,
2733 it may insert a check in the executable. For code generation, the contract
2737 pragma Contract_Cases (
2745 C1 : constant Boolean := Cond1; -- evaluated at subprogram entry
2746 C2 : constant Boolean := Cond2; -- evaluated at subprogram entry
2747 pragma Precondition ((C1 and not C2) or (C2 and not C1));
2748 pragma Postcondition (if C1 then Pred1);
2749 pragma Postcondition (if C2 then Pred2);
2752 The precondition ensures that one and only one of the case guards is
2753 satisfied on entry to the subprogram.
2754 The postcondition ensures that for the case guard that was True on entry,
2755 the corrresponding consequence is True on exit. Other consequence expressions
2758 A precondition @code{P} and postcondition @code{Q} can also be
2759 expressed as contract cases:
2762 pragma Contract_Cases (P => Q);
2765 The placement and visibility rules for @code{Contract_Cases} pragmas are
2766 identical to those described for preconditions and postconditions.
2768 The compiler checks that boolean expressions given in case guards and
2769 consequences are valid, where the rules for case guards are the same as
2770 the rule for an expression in @code{Precondition} and the rules for
2771 consequences are the same as the rule for an expression in
2772 @code{Postcondition}. In particular, attributes @code{'Old} and
2773 @code{'Result} can only be used within consequence expressions.
2774 The case guard for the last contract case may be @code{others}, to denote
2775 any case not captured by the previous cases. The
2776 following is an example of use within a package spec:
2779 package Math_Functions is
2781 function Sqrt (Arg : Float) return Float;
2782 pragma Contract_Cases (((Arg in 0.0 .. 99.0) => Sqrt'Result < 10.0,
2783 Arg >= 100.0 => Sqrt'Result >= 10.0,
2784 others => Sqrt'Result = 0.0));
2789 The meaning of contract cases is that only one case should apply at each
2790 call, as determined by the corresponding case guard evaluating to True,
2791 and that the consequence for this case should hold when the subprogram
2794 @node Pragma Convention_Identifier,Pragma CPP_Class,Pragma Contract_Cases,Implementation Defined Pragmas
2795 @anchor{gnat_rm/implementation_defined_pragmas pragma-convention-identifier}@anchor{48}
2796 @section Pragma Convention_Identifier
2799 @geindex Conventions
2805 pragma Convention_Identifier (
2806 [Name =>] IDENTIFIER,
2807 [Convention =>] convention_IDENTIFIER);
2810 This pragma provides a mechanism for supplying synonyms for existing
2811 convention identifiers. The @code{Name} identifier can subsequently
2812 be used as a synonym for the given convention in other pragmas (including
2813 for example pragma @code{Import} or another @code{Convention_Identifier}
2814 pragma). As an example of the use of this, suppose you had legacy code
2815 which used Fortran77 as the identifier for Fortran. Then the pragma:
2818 pragma Convention_Identifier (Fortran77, Fortran);
2821 would allow the use of the convention identifier @code{Fortran77} in
2822 subsequent code, avoiding the need to modify the sources. As another
2823 example, you could use this to parameterize convention requirements
2824 according to systems. Suppose you needed to use @code{Stdcall} on
2825 windows systems, and @code{C} on some other system, then you could
2826 define a convention identifier @code{Library} and use a single
2827 @code{Convention_Identifier} pragma to specify which convention
2828 would be used system-wide.
2830 @node Pragma CPP_Class,Pragma CPP_Constructor,Pragma Convention_Identifier,Implementation Defined Pragmas
2831 @anchor{gnat_rm/implementation_defined_pragmas pragma-cpp-class}@anchor{49}
2832 @section Pragma CPP_Class
2835 @geindex Interfacing with C++
2840 pragma CPP_Class ([Entity =>] LOCAL_NAME);
2843 The argument denotes an entity in the current declarative region that is
2844 declared as a record type. It indicates that the type corresponds to an
2845 externally declared C++ class type, and is to be laid out the same way
2846 that C++ would lay out the type. If the C++ class has virtual primitives
2847 then the record must be declared as a tagged record type.
2849 Types for which @code{CPP_Class} is specified do not have assignment or
2850 equality operators defined (such operations can be imported or declared
2851 as subprograms as required). Initialization is allowed only by constructor
2852 functions (see pragma @code{CPP_Constructor}). Such types are implicitly
2853 limited if not explicitly declared as limited or derived from a limited
2854 type, and an error is issued in that case.
2856 See @ref{4a,,Interfacing to C++} for related information.
2858 Note: Pragma @code{CPP_Class} is currently obsolete. It is supported
2859 for backward compatibility but its functionality is available
2860 using pragma @code{Import} with @code{Convention} = @code{CPP}.
2862 @node Pragma CPP_Constructor,Pragma CPP_Virtual,Pragma CPP_Class,Implementation Defined Pragmas
2863 @anchor{gnat_rm/implementation_defined_pragmas pragma-cpp-constructor}@anchor{4b}
2864 @section Pragma CPP_Constructor
2867 @geindex Interfacing with C++
2872 pragma CPP_Constructor ([Entity =>] LOCAL_NAME
2873 [, [External_Name =>] static_string_EXPRESSION ]
2874 [, [Link_Name =>] static_string_EXPRESSION ]);
2877 This pragma identifies an imported function (imported in the usual way
2878 with pragma @code{Import}) as corresponding to a C++ constructor. If
2879 @code{External_Name} and @code{Link_Name} are not specified then the
2880 @code{Entity} argument is a name that must have been previously mentioned
2881 in a pragma @code{Import} with @code{Convention} = @code{CPP}. Such name
2882 must be of one of the following forms:
2888 @strong{function} @code{Fname} @strong{return} T`
2891 @strong{function} @code{Fname} @strong{return} T'Class
2894 @strong{function} @code{Fname} (...) @strong{return} T`
2897 @strong{function} @code{Fname} (...) @strong{return} T'Class
2900 where @code{T} is a limited record type imported from C++ with pragma
2901 @code{Import} and @code{Convention} = @code{CPP}.
2903 The first two forms import the default constructor, used when an object
2904 of type @code{T} is created on the Ada side with no explicit constructor.
2905 The latter two forms cover all the non-default constructors of the type.
2906 See the GNAT User's Guide for details.
2908 If no constructors are imported, it is impossible to create any objects
2909 on the Ada side and the type is implicitly declared abstract.
2911 Pragma @code{CPP_Constructor} is intended primarily for automatic generation
2912 using an automatic binding generator tool (such as the @code{-fdump-ada-spec}
2914 See @ref{4a,,Interfacing to C++} for more related information.
2916 Note: The use of functions returning class-wide types for constructors is
2917 currently obsolete. They are supported for backward compatibility. The
2918 use of functions returning the type T leave the Ada sources more clear
2919 because the imported C++ constructors always return an object of type T;
2920 that is, they never return an object whose type is a descendant of type T.
2922 @node Pragma CPP_Virtual,Pragma CPP_Vtable,Pragma CPP_Constructor,Implementation Defined Pragmas
2923 @anchor{gnat_rm/implementation_defined_pragmas pragma-cpp-virtual}@anchor{4c}
2924 @section Pragma CPP_Virtual
2927 @geindex Interfacing to C++
2929 This pragma is now obsolete and, other than generating a warning if warnings
2930 on obsolescent features are enabled, is completely ignored.
2931 It is retained for compatibility
2932 purposes. It used to be required to ensure compoatibility with C++, but
2933 is no longer required for that purpose because GNAT generates
2934 the same object layout as the G++ compiler by default.
2936 See @ref{4a,,Interfacing to C++} for related information.
2938 @node Pragma CPP_Vtable,Pragma CPU,Pragma CPP_Virtual,Implementation Defined Pragmas
2939 @anchor{gnat_rm/implementation_defined_pragmas pragma-cpp-vtable}@anchor{4d}
2940 @section Pragma CPP_Vtable
2943 @geindex Interfacing with C++
2945 This pragma is now obsolete and, other than generating a warning if warnings
2946 on obsolescent features are enabled, is completely ignored.
2947 It used to be required to ensure compatibility with C++, but
2948 is no longer required for that purpose because GNAT generates
2949 the same object layout as the G++ compiler by default.
2951 See @ref{4a,,Interfacing to C++} for related information.
2953 @node Pragma CPU,Pragma Deadline_Floor,Pragma CPP_Vtable,Implementation Defined Pragmas
2954 @anchor{gnat_rm/implementation_defined_pragmas pragma-cpu}@anchor{4e}
2961 pragma CPU (EXPRESSION);
2964 This pragma is standard in Ada 2012, but is available in all earlier
2965 versions of Ada as an implementation-defined pragma.
2966 See Ada 2012 Reference Manual for details.
2968 @node Pragma Deadline_Floor,Pragma Default_Initial_Condition,Pragma CPU,Implementation Defined Pragmas
2969 @anchor{gnat_rm/implementation_defined_pragmas pragma-deadline-floor}@anchor{4f}
2970 @section Pragma Deadline_Floor
2976 pragma Deadline_Floor (time_span_EXPRESSION);
2979 This pragma applies only to protected types and specifies the floor
2980 deadline inherited by a task when the task enters a protected object.
2981 It is effective only when the EDF scheduling policy is used.
2983 @node Pragma Default_Initial_Condition,Pragma Debug,Pragma Deadline_Floor,Implementation Defined Pragmas
2984 @anchor{gnat_rm/implementation_defined_pragmas id8}@anchor{50}@anchor{gnat_rm/implementation_defined_pragmas pragma-default-initial-condition}@anchor{51}
2985 @section Pragma Default_Initial_Condition
2991 pragma Default_Initial_Condition [ (null | boolean_EXPRESSION) ];
2994 For the semantics of this pragma, see the entry for aspect
2995 @code{Default_Initial_Condition} in the SPARK 2014 Reference Manual, section 7.3.3.
2997 @node Pragma Debug,Pragma Debug_Policy,Pragma Default_Initial_Condition,Implementation Defined Pragmas
2998 @anchor{gnat_rm/implementation_defined_pragmas pragma-debug}@anchor{52}
2999 @section Pragma Debug
3005 pragma Debug ([CONDITION, ]PROCEDURE_CALL_WITHOUT_SEMICOLON);
3007 PROCEDURE_CALL_WITHOUT_SEMICOLON ::=
3009 | PROCEDURE_PREFIX ACTUAL_PARAMETER_PART
3012 The procedure call argument has the syntactic form of an expression, meeting
3013 the syntactic requirements for pragmas.
3015 If debug pragmas are not enabled or if the condition is present and evaluates
3016 to False, this pragma has no effect. If debug pragmas are enabled, the
3017 semantics of the pragma is exactly equivalent to the procedure call statement
3018 corresponding to the argument with a terminating semicolon. Pragmas are
3019 permitted in sequences of declarations, so you can use pragma @code{Debug} to
3020 intersperse calls to debug procedures in the middle of declarations. Debug
3021 pragmas can be enabled either by use of the command line switch @emph{-gnata}
3022 or by use of the pragma @code{Check_Policy} with a first argument of
3025 @node Pragma Debug_Policy,Pragma Default_Scalar_Storage_Order,Pragma Debug,Implementation Defined Pragmas
3026 @anchor{gnat_rm/implementation_defined_pragmas pragma-debug-policy}@anchor{53}
3027 @section Pragma Debug_Policy
3033 pragma Debug_Policy (CHECK | DISABLE | IGNORE | ON | OFF);
3036 This pragma is equivalent to a corresponding @code{Check_Policy} pragma
3037 with a first argument of @code{Debug}. It is retained for historical
3038 compatibility reasons.
3040 @node Pragma Default_Scalar_Storage_Order,Pragma Default_Storage_Pool,Pragma Debug_Policy,Implementation Defined Pragmas
3041 @anchor{gnat_rm/implementation_defined_pragmas pragma-default-scalar-storage-order}@anchor{54}
3042 @section Pragma Default_Scalar_Storage_Order
3045 @geindex Default_Scalar_Storage_Order
3047 @geindex Scalar_Storage_Order
3052 pragma Default_Scalar_Storage_Order (High_Order_First | Low_Order_First);
3055 Normally if no explicit @code{Scalar_Storage_Order} is given for a record
3056 type or array type, then the scalar storage order defaults to the ordinary
3057 default for the target. But this default may be overridden using this pragma.
3058 The pragma may appear as a configuration pragma, or locally within a package
3059 spec or declarative part. In the latter case, it applies to all subsequent
3060 types declared within that package spec or declarative part.
3062 The following example shows the use of this pragma:
3065 pragma Default_Scalar_Storage_Order (High_Order_First);
3066 with System; use System;
3075 for L2'Scalar_Storage_Order use Low_Order_First;
3084 pragma Default_Scalar_Storage_Order (Low_Order_First);
3091 type H4a is new Inner.L4;
3099 In this example record types with names starting with @emph{L} have @cite{Low_Order_First} scalar
3100 storage order, and record types with names starting with @emph{H} have @code{High_Order_First}.
3101 Note that in the case of @code{H4a}, the order is not inherited
3102 from the parent type. Only an explicitly set @code{Scalar_Storage_Order}
3103 gets inherited on type derivation.
3105 If this pragma is used as a configuration pragma which appears within a
3106 configuration pragma file (as opposed to appearing explicitly at the start
3107 of a single unit), then the binder will require that all units in a partition
3108 be compiled in a similar manner, other than run-time units, which are not
3109 affected by this pragma. Note that the use of this form is discouraged because
3110 it may significantly degrade the run-time performance of the software, instead
3111 the default scalar storage order ought to be changed only on a local basis.
3113 @node Pragma Default_Storage_Pool,Pragma Depends,Pragma Default_Scalar_Storage_Order,Implementation Defined Pragmas
3114 @anchor{gnat_rm/implementation_defined_pragmas pragma-default-storage-pool}@anchor{55}
3115 @section Pragma Default_Storage_Pool
3118 @geindex Default_Storage_Pool
3123 pragma Default_Storage_Pool (storage_pool_NAME | null);
3126 This pragma is standard in Ada 2012, but is available in all earlier
3127 versions of Ada as an implementation-defined pragma.
3128 See Ada 2012 Reference Manual for details.
3130 @node Pragma Depends,Pragma Detect_Blocking,Pragma Default_Storage_Pool,Implementation Defined Pragmas
3131 @anchor{gnat_rm/implementation_defined_pragmas pragma-depends}@anchor{56}@anchor{gnat_rm/implementation_defined_pragmas id9}@anchor{57}
3132 @section Pragma Depends
3138 pragma Depends (DEPENDENCY_RELATION);
3140 DEPENDENCY_RELATION ::=
3142 | (DEPENDENCY_CLAUSE @{, DEPENDENCY_CLAUSE@})
3144 DEPENDENCY_CLAUSE ::=
3145 OUTPUT_LIST =>[+] INPUT_LIST
3146 | NULL_DEPENDENCY_CLAUSE
3148 NULL_DEPENDENCY_CLAUSE ::= null => INPUT_LIST
3150 OUTPUT_LIST ::= OUTPUT | (OUTPUT @{, OUTPUT@})
3152 INPUT_LIST ::= null | INPUT | (INPUT @{, INPUT@})
3154 OUTPUT ::= NAME | FUNCTION_RESULT
3157 where FUNCTION_RESULT is a function Result attribute_reference
3160 For the semantics of this pragma, see the entry for aspect @code{Depends} in the
3161 SPARK 2014 Reference Manual, section 6.1.5.
3163 @node Pragma Detect_Blocking,Pragma Disable_Atomic_Synchronization,Pragma Depends,Implementation Defined Pragmas
3164 @anchor{gnat_rm/implementation_defined_pragmas pragma-detect-blocking}@anchor{58}
3165 @section Pragma Detect_Blocking
3171 pragma Detect_Blocking;
3174 This is a standard pragma in Ada 2005, that is available in all earlier
3175 versions of Ada as an implementation-defined pragma.
3177 This is a configuration pragma that forces the detection of potentially
3178 blocking operations within a protected operation, and to raise Program_Error
3181 @node Pragma Disable_Atomic_Synchronization,Pragma Dispatching_Domain,Pragma Detect_Blocking,Implementation Defined Pragmas
3182 @anchor{gnat_rm/implementation_defined_pragmas pragma-disable-atomic-synchronization}@anchor{59}
3183 @section Pragma Disable_Atomic_Synchronization
3186 @geindex Atomic Synchronization
3191 pragma Disable_Atomic_Synchronization [(Entity)];
3194 Ada requires that accesses (reads or writes) of an atomic variable be
3195 regarded as synchronization points in the case of multiple tasks.
3196 Particularly in the case of multi-processors this may require special
3197 handling, e.g. the generation of memory barriers. This capability may
3198 be turned off using this pragma in cases where it is known not to be
3201 The placement and scope rules for this pragma are the same as those
3202 for @code{pragma Suppress}. In particular it can be used as a
3203 configuration pragma, or in a declaration sequence where it applies
3204 till the end of the scope. If an @code{Entity} argument is present,
3205 the action applies only to that entity.
3207 @node Pragma Dispatching_Domain,Pragma Effective_Reads,Pragma Disable_Atomic_Synchronization,Implementation Defined Pragmas
3208 @anchor{gnat_rm/implementation_defined_pragmas pragma-dispatching-domain}@anchor{5a}
3209 @section Pragma Dispatching_Domain
3215 pragma Dispatching_Domain (EXPRESSION);
3218 This pragma is standard in Ada 2012, but is available in all earlier
3219 versions of Ada as an implementation-defined pragma.
3220 See Ada 2012 Reference Manual for details.
3222 @node Pragma Effective_Reads,Pragma Effective_Writes,Pragma Dispatching_Domain,Implementation Defined Pragmas
3223 @anchor{gnat_rm/implementation_defined_pragmas id10}@anchor{5b}@anchor{gnat_rm/implementation_defined_pragmas pragma-effective-reads}@anchor{5c}
3224 @section Pragma Effective_Reads
3230 pragma Effective_Reads [ (boolean_EXPRESSION) ];
3233 For the semantics of this pragma, see the entry for aspect @code{Effective_Reads} in
3234 the SPARK 2014 Reference Manual, section 7.1.2.
3236 @node Pragma Effective_Writes,Pragma Elaboration_Checks,Pragma Effective_Reads,Implementation Defined Pragmas
3237 @anchor{gnat_rm/implementation_defined_pragmas id11}@anchor{5d}@anchor{gnat_rm/implementation_defined_pragmas pragma-effective-writes}@anchor{5e}
3238 @section Pragma Effective_Writes
3244 pragma Effective_Writes [ (boolean_EXPRESSION) ];
3247 For the semantics of this pragma, see the entry for aspect @code{Effective_Writes}
3248 in the SPARK 2014 Reference Manual, section 7.1.2.
3250 @node Pragma Elaboration_Checks,Pragma Eliminate,Pragma Effective_Writes,Implementation Defined Pragmas
3251 @anchor{gnat_rm/implementation_defined_pragmas pragma-elaboration-checks}@anchor{5f}
3252 @section Pragma Elaboration_Checks
3255 @geindex Elaboration control
3260 pragma Elaboration_Checks (Dynamic | Static);
3263 This is a configuration pragma which specifies the elaboration model to be
3264 used during compilation. For more information on the elaboration models of
3265 GNAT, consult the chapter on elaboration order handling in the @emph{GNAT User's
3268 The pragma may appear in the following contexts:
3274 Configuration pragmas file
3277 Prior to the context clauses of a compilation unit's initial declaration
3280 Any other placement of the pragma will result in a warning and the effects of
3281 the offending pragma will be ignored.
3283 If the pragma argument is @code{Dynamic}, then the dynamic elaboration model is in
3284 effect. If the pragma argument is @code{Static}, then the static elaboration model
3287 @node Pragma Eliminate,Pragma Enable_Atomic_Synchronization,Pragma Elaboration_Checks,Implementation Defined Pragmas
3288 @anchor{gnat_rm/implementation_defined_pragmas pragma-eliminate}@anchor{60}
3289 @section Pragma Eliminate
3292 @geindex Elimination of unused subprograms
3298 [ Unit_Name => ] IDENTIFIER | SELECTED_COMPONENT ,
3299 [ Entity => ] IDENTIFIER |
3300 SELECTED_COMPONENT |
3302 [, Source_Location => SOURCE_TRACE ] );
3304 SOURCE_TRACE ::= STRING_LITERAL
3307 This pragma indicates that the given entity is not used in the program to be
3308 compiled and built, thus allowing the compiler to
3309 eliminate the code or data associated with the named entity. Any reference to
3310 an eliminated entity causes a compile-time or link-time error.
3312 The pragma has the following semantics, where @code{U} is the unit specified by
3313 the @code{Unit_Name} argument and @code{E} is the entity specified by the @code{Entity}
3320 @code{E} must be a subprogram that is explicitly declared either:
3322 o Within @code{U}, or
3324 o Within a generic package that is instantiated in @code{U}, or
3326 o As an instance of generic subprogram instantiated in @code{U}.
3328 Otherwise the pragma is ignored.
3331 If @code{E} is overloaded within @code{U} then, in the absence of a
3332 @code{Source_Location} argument, all overloadings are eliminated.
3335 If @code{E} is overloaded within @code{U} and only some overloadings
3336 are to be eliminated, then each overloading to be eliminated
3337 must be specified in a corresponding pragma @code{Eliminate}
3338 with a @code{Source_Location} argument identifying the line where the
3339 declaration appears, as described below.
3342 If @code{E} is declared as the result of a generic instantiation, then
3343 a @code{Source_Location} argument is needed, as described below
3346 Pragma @code{Eliminate} allows a program to be compiled in a system-independent
3347 manner, so that unused entities are eliminated but without
3348 needing to modify the source text. Normally the required set of
3349 @code{Eliminate} pragmas is constructed automatically using the @code{gnatelim} tool.
3351 Any source file change that removes, splits, or
3352 adds lines may make the set of @code{Eliminate} pragmas invalid because their
3353 @code{Source_Location} argument values may get out of date.
3355 Pragma @code{Eliminate} may be used where the referenced entity is a dispatching
3356 operation. In this case all the subprograms to which the given operation can
3357 dispatch are considered to be unused (are never called as a result of a direct
3358 or a dispatching call).
3360 The string literal given for the source location specifies the line number
3361 of the declaration of the entity, using the following syntax for @code{SOURCE_TRACE}:
3364 SOURCE_TRACE ::= SOURCE_REFERENCE [ LBRACKET SOURCE_TRACE RBRACKET ]
3369 SOURCE_REFERENCE ::= FILE_NAME : LINE_NUMBER
3371 LINE_NUMBER ::= DIGIT @{DIGIT@}
3374 Spaces around the colon in a @code{SOURCE_REFERENCE} are optional.
3376 The source trace that is given as the @code{Source_Location} must obey the
3377 following rules (or else the pragma is ignored), where @code{U} is
3378 the unit @code{U} specified by the @code{Unit_Name} argument and @code{E} is the
3379 subprogram specified by the @code{Entity} argument:
3385 @code{FILE_NAME} is the short name (with no directory
3386 information) of the Ada source file for @code{U}, using the required syntax
3387 for the underlying file system (e.g. case is significant if the underlying
3388 operating system is case sensitive).
3389 If @code{U} is a package and @code{E} is a subprogram declared in the package
3390 specification and its full declaration appears in the package body,
3391 then the relevant source file is the one for the package specification;
3392 analogously if @code{U} is a generic package.
3395 If @code{E} is not declared in a generic instantiation (this includes
3396 generic subprogram instances), the source trace includes only one source
3397 line reference. @code{LINE_NUMBER} gives the line number of the occurrence
3398 of the declaration of @code{E} within the source file (as a decimal literal
3399 without an exponent or point).
3402 If @code{E} is declared by a generic instantiation, its source trace
3403 (from left to right) starts with the source location of the
3404 declaration of @code{E} in the generic unit and ends with the source
3405 location of the instantiation, given in square brackets. This approach is
3406 applied recursively with nested instantiations: the rightmost (nested
3407 most deeply in square brackets) element of the source trace is the location
3408 of the outermost instantiation, and the leftmost element (that is, outside
3409 of any square brackets) is the location of the declaration of @code{E} in
3418 pragma Eliminate (Pkg0, Proc);
3419 -- Eliminate (all overloadings of) Proc in Pkg0
3421 pragma Eliminate (Pkg1, Proc,
3422 Source_Location => "pkg1.ads:8");
3423 -- Eliminate overloading of Proc at line 8 in pkg1.ads
3425 -- Assume the following file contents:
3428 -- 2: type T is private;
3429 -- 3: package Gen_Pkg is
3430 -- 4: procedure Proc(N : T);
3436 -- 2: procedure Q is
3437 -- 3: package Inst_Pkg is new Gen_Pkg(Integer);
3438 -- ... -- No calls on Inst_Pkg.Proc
3441 -- The following pragma eliminates Inst_Pkg.Proc from Q
3442 pragma Eliminate (Q, Proc,
3443 Source_Location => "gen_pkg.ads:4[q.adb:3]");
3447 @node Pragma Enable_Atomic_Synchronization,Pragma Export_Function,Pragma Eliminate,Implementation Defined Pragmas
3448 @anchor{gnat_rm/implementation_defined_pragmas pragma-enable-atomic-synchronization}@anchor{61}
3449 @section Pragma Enable_Atomic_Synchronization
3452 @geindex Atomic Synchronization
3457 pragma Enable_Atomic_Synchronization [(Entity)];
3460 Ada requires that accesses (reads or writes) of an atomic variable be
3461 regarded as synchronization points in the case of multiple tasks.
3462 Particularly in the case of multi-processors this may require special
3463 handling, e.g. the generation of memory barriers. This synchronization
3464 is performed by default, but can be turned off using
3465 @code{pragma Disable_Atomic_Synchronization}. The
3466 @code{Enable_Atomic_Synchronization} pragma can be used to turn
3469 The placement and scope rules for this pragma are the same as those
3470 for @code{pragma Unsuppress}. In particular it can be used as a
3471 configuration pragma, or in a declaration sequence where it applies
3472 till the end of the scope. If an @code{Entity} argument is present,
3473 the action applies only to that entity.
3475 @node Pragma Export_Function,Pragma Export_Object,Pragma Enable_Atomic_Synchronization,Implementation Defined Pragmas
3476 @anchor{gnat_rm/implementation_defined_pragmas pragma-export-function}@anchor{62}
3477 @section Pragma Export_Function
3480 @geindex Argument passing mechanisms
3485 pragma Export_Function (
3486 [Internal =>] LOCAL_NAME
3487 [, [External =>] EXTERNAL_SYMBOL]
3488 [, [Parameter_Types =>] PARAMETER_TYPES]
3489 [, [Result_Type =>] result_SUBTYPE_MARK]
3490 [, [Mechanism =>] MECHANISM]
3491 [, [Result_Mechanism =>] MECHANISM_NAME]);
3495 | static_string_EXPRESSION
3500 | TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@}
3504 | subtype_Name ' Access
3508 | (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@})
3510 MECHANISM_ASSOCIATION ::=
3511 [formal_parameter_NAME =>] MECHANISM_NAME
3513 MECHANISM_NAME ::= Value | Reference
3516 Use this pragma to make a function externally callable and optionally
3517 provide information on mechanisms to be used for passing parameter and
3518 result values. We recommend, for the purposes of improving portability,
3519 this pragma always be used in conjunction with a separate pragma
3520 @code{Export}, which must precede the pragma @code{Export_Function}.
3521 GNAT does not require a separate pragma @code{Export}, but if none is
3522 present, @code{Convention Ada} is assumed, which is usually
3523 not what is wanted, so it is usually appropriate to use this
3524 pragma in conjunction with a @code{Export} or @code{Convention}
3525 pragma that specifies the desired foreign convention.
3526 Pragma @code{Export_Function}
3527 (and @code{Export}, if present) must appear in the same declarative
3528 region as the function to which they apply.
3530 The @code{internal_name} must uniquely designate the function to which the
3531 pragma applies. If more than one function name exists of this name in
3532 the declarative part you must use the @code{Parameter_Types} and
3533 @code{Result_Type} parameters to achieve the required
3534 unique designation. The @cite{subtype_mark}s in these parameters must
3535 exactly match the subtypes in the corresponding function specification,
3536 using positional notation to match parameters with subtype marks.
3537 The form with an @code{'Access} attribute can be used to match an
3538 anonymous access parameter.
3540 @geindex Suppressing external name
3542 Special treatment is given if the EXTERNAL is an explicit null
3543 string or a static string expressions that evaluates to the null
3544 string. In this case, no external name is generated. This form
3545 still allows the specification of parameter mechanisms.
3547 @node Pragma Export_Object,Pragma Export_Procedure,Pragma Export_Function,Implementation Defined Pragmas
3548 @anchor{gnat_rm/implementation_defined_pragmas pragma-export-object}@anchor{63}
3549 @section Pragma Export_Object
3555 pragma Export_Object
3556 [Internal =>] LOCAL_NAME
3557 [, [External =>] EXTERNAL_SYMBOL]
3558 [, [Size =>] EXTERNAL_SYMBOL]
3562 | static_string_EXPRESSION
3565 This pragma designates an object as exported, and apart from the
3566 extended rules for external symbols, is identical in effect to the use of
3567 the normal @code{Export} pragma applied to an object. You may use a
3568 separate Export pragma (and you probably should from the point of view
3569 of portability), but it is not required. @code{Size} is syntax checked,
3570 but otherwise ignored by GNAT.
3572 @node Pragma Export_Procedure,Pragma Export_Value,Pragma Export_Object,Implementation Defined Pragmas
3573 @anchor{gnat_rm/implementation_defined_pragmas pragma-export-procedure}@anchor{64}
3574 @section Pragma Export_Procedure
3580 pragma Export_Procedure (
3581 [Internal =>] LOCAL_NAME
3582 [, [External =>] EXTERNAL_SYMBOL]
3583 [, [Parameter_Types =>] PARAMETER_TYPES]
3584 [, [Mechanism =>] MECHANISM]);
3588 | static_string_EXPRESSION
3593 | TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@}
3597 | subtype_Name ' Access
3601 | (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@})
3603 MECHANISM_ASSOCIATION ::=
3604 [formal_parameter_NAME =>] MECHANISM_NAME
3606 MECHANISM_NAME ::= Value | Reference
3609 This pragma is identical to @code{Export_Function} except that it
3610 applies to a procedure rather than a function and the parameters
3611 @code{Result_Type} and @code{Result_Mechanism} are not permitted.
3612 GNAT does not require a separate pragma @code{Export}, but if none is
3613 present, @code{Convention Ada} is assumed, which is usually
3614 not what is wanted, so it is usually appropriate to use this
3615 pragma in conjunction with a @code{Export} or @code{Convention}
3616 pragma that specifies the desired foreign convention.
3618 @geindex Suppressing external name
3620 Special treatment is given if the EXTERNAL is an explicit null
3621 string or a static string expressions that evaluates to the null
3622 string. In this case, no external name is generated. This form
3623 still allows the specification of parameter mechanisms.
3625 @node Pragma Export_Value,Pragma Export_Valued_Procedure,Pragma Export_Procedure,Implementation Defined Pragmas
3626 @anchor{gnat_rm/implementation_defined_pragmas pragma-export-value}@anchor{65}
3627 @section Pragma Export_Value
3633 pragma Export_Value (
3634 [Value =>] static_integer_EXPRESSION,
3635 [Link_Name =>] static_string_EXPRESSION);
3638 This pragma serves to export a static integer value for external use.
3639 The first argument specifies the value to be exported. The Link_Name
3640 argument specifies the symbolic name to be associated with the integer
3641 value. This pragma is useful for defining a named static value in Ada
3642 that can be referenced in assembly language units to be linked with
3643 the application. This pragma is currently supported only for the
3644 AAMP target and is ignored for other targets.
3646 @node Pragma Export_Valued_Procedure,Pragma Extend_System,Pragma Export_Value,Implementation Defined Pragmas
3647 @anchor{gnat_rm/implementation_defined_pragmas pragma-export-valued-procedure}@anchor{66}
3648 @section Pragma Export_Valued_Procedure
3654 pragma Export_Valued_Procedure (
3655 [Internal =>] LOCAL_NAME
3656 [, [External =>] EXTERNAL_SYMBOL]
3657 [, [Parameter_Types =>] PARAMETER_TYPES]
3658 [, [Mechanism =>] MECHANISM]);
3662 | static_string_EXPRESSION
3667 | TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@}
3671 | subtype_Name ' Access
3675 | (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@})
3677 MECHANISM_ASSOCIATION ::=
3678 [formal_parameter_NAME =>] MECHANISM_NAME
3680 MECHANISM_NAME ::= Value | Reference
3683 This pragma is identical to @code{Export_Procedure} except that the
3684 first parameter of @code{LOCAL_NAME}, which must be present, must be of
3685 mode @code{out}, and externally the subprogram is treated as a function
3686 with this parameter as the result of the function. GNAT provides for
3687 this capability to allow the use of @code{out} and @code{in out}
3688 parameters in interfacing to external functions (which are not permitted
3690 GNAT does not require a separate pragma @code{Export}, but if none is
3691 present, @code{Convention Ada} is assumed, which is almost certainly
3692 not what is wanted since the whole point of this pragma is to interface
3693 with foreign language functions, so it is usually appropriate to use this
3694 pragma in conjunction with a @code{Export} or @code{Convention}
3695 pragma that specifies the desired foreign convention.
3697 @geindex Suppressing external name
3699 Special treatment is given if the EXTERNAL is an explicit null
3700 string or a static string expressions that evaluates to the null
3701 string. In this case, no external name is generated. This form
3702 still allows the specification of parameter mechanisms.
3704 @node Pragma Extend_System,Pragma Extensions_Allowed,Pragma Export_Valued_Procedure,Implementation Defined Pragmas
3705 @anchor{gnat_rm/implementation_defined_pragmas pragma-extend-system}@anchor{67}
3706 @section Pragma Extend_System
3717 pragma Extend_System ([Name =>] IDENTIFIER);
3720 This pragma is used to provide backwards compatibility with other
3721 implementations that extend the facilities of package @code{System}. In
3722 GNAT, @code{System} contains only the definitions that are present in
3723 the Ada RM. However, other implementations, notably the DEC Ada 83
3724 implementation, provide many extensions to package @code{System}.
3726 For each such implementation accommodated by this pragma, GNAT provides a
3727 package @code{Aux_@emph{xxx}}, e.g., @code{Aux_DEC} for the DEC Ada 83
3728 implementation, which provides the required additional definitions. You
3729 can use this package in two ways. You can @code{with} it in the normal
3730 way and access entities either by selection or using a @code{use}
3731 clause. In this case no special processing is required.
3733 However, if existing code contains references such as
3734 @code{System.@emph{xxx}} where @emph{xxx} is an entity in the extended
3735 definitions provided in package @code{System}, you may use this pragma
3736 to extend visibility in @code{System} in a non-standard way that
3737 provides greater compatibility with the existing code. Pragma
3738 @code{Extend_System} is a configuration pragma whose single argument is
3739 the name of the package containing the extended definition
3740 (e.g., @code{Aux_DEC} for the DEC Ada case). A unit compiled under
3741 control of this pragma will be processed using special visibility
3742 processing that looks in package @code{System.Aux_@emph{xxx}} where
3743 @code{Aux_@emph{xxx}} is the pragma argument for any entity referenced in
3744 package @code{System}, but not found in package @code{System}.
3746 You can use this pragma either to access a predefined @code{System}
3747 extension supplied with the compiler, for example @code{Aux_DEC} or
3748 you can construct your own extension unit following the above
3749 definition. Note that such a package is a child of @code{System}
3750 and thus is considered part of the implementation.
3751 To compile it you will have to use the @emph{-gnatg} switch
3752 for compiling System units, as explained in the
3755 @node Pragma Extensions_Allowed,Pragma Extensions_Visible,Pragma Extend_System,Implementation Defined Pragmas
3756 @anchor{gnat_rm/implementation_defined_pragmas pragma-extensions-allowed}@anchor{68}
3757 @section Pragma Extensions_Allowed
3760 @geindex Ada Extensions
3762 @geindex GNAT Extensions
3767 pragma Extensions_Allowed (On | Off);
3770 This configuration pragma enables or disables the implementation
3771 extension mode (the use of Off as a parameter cancels the effect
3772 of the @emph{-gnatX} command switch).
3774 In extension mode, the latest version of the Ada language is
3775 implemented (currently Ada 2012), and in addition a small number
3776 of GNAT specific extensions are recognized as follows:
3781 @item @emph{Constrained attribute for generic objects}
3783 The @code{Constrained} attribute is permitted for objects of
3784 generic types. The result indicates if the corresponding actual
3788 @node Pragma Extensions_Visible,Pragma External,Pragma Extensions_Allowed,Implementation Defined Pragmas
3789 @anchor{gnat_rm/implementation_defined_pragmas id12}@anchor{69}@anchor{gnat_rm/implementation_defined_pragmas pragma-extensions-visible}@anchor{6a}
3790 @section Pragma Extensions_Visible
3796 pragma Extensions_Visible [ (boolean_EXPRESSION) ];
3799 For the semantics of this pragma, see the entry for aspect @code{Extensions_Visible}
3800 in the SPARK 2014 Reference Manual, section 6.1.7.
3802 @node Pragma External,Pragma External_Name_Casing,Pragma Extensions_Visible,Implementation Defined Pragmas
3803 @anchor{gnat_rm/implementation_defined_pragmas pragma-external}@anchor{6b}
3804 @section Pragma External
3811 [ Convention =>] convention_IDENTIFIER,
3812 [ Entity =>] LOCAL_NAME
3813 [, [External_Name =>] static_string_EXPRESSION ]
3814 [, [Link_Name =>] static_string_EXPRESSION ]);
3817 This pragma is identical in syntax and semantics to pragma
3818 @code{Export} as defined in the Ada Reference Manual. It is
3819 provided for compatibility with some Ada 83 compilers that
3820 used this pragma for exactly the same purposes as pragma
3821 @code{Export} before the latter was standardized.
3823 @node Pragma External_Name_Casing,Pragma Fast_Math,Pragma External,Implementation Defined Pragmas
3824 @anchor{gnat_rm/implementation_defined_pragmas pragma-external-name-casing}@anchor{6c}
3825 @section Pragma External_Name_Casing
3828 @geindex Dec Ada 83 casing compatibility
3830 @geindex External Names
3833 @geindex Casing of External names
3838 pragma External_Name_Casing (
3839 Uppercase | Lowercase
3840 [, Uppercase | Lowercase | As_Is]);
3843 This pragma provides control over the casing of external names associated
3844 with Import and Export pragmas. There are two cases to consider:
3850 Implicit external names
3852 Implicit external names are derived from identifiers. The most common case
3853 arises when a standard Ada Import or Export pragma is used with only two
3857 pragma Import (C, C_Routine);
3860 Since Ada is a case-insensitive language, the spelling of the identifier in
3861 the Ada source program does not provide any information on the desired
3862 casing of the external name, and so a convention is needed. In GNAT the
3863 default treatment is that such names are converted to all lower case
3864 letters. This corresponds to the normal C style in many environments.
3865 The first argument of pragma @code{External_Name_Casing} can be used to
3866 control this treatment. If @code{Uppercase} is specified, then the name
3867 will be forced to all uppercase letters. If @code{Lowercase} is specified,
3868 then the normal default of all lower case letters will be used.
3870 This same implicit treatment is also used in the case of extended DEC Ada 83
3871 compatible Import and Export pragmas where an external name is explicitly
3872 specified using an identifier rather than a string.
3875 Explicit external names
3877 Explicit external names are given as string literals. The most common case
3878 arises when a standard Ada Import or Export pragma is used with three
3882 pragma Import (C, C_Routine, "C_routine");
3885 In this case, the string literal normally provides the exact casing required
3886 for the external name. The second argument of pragma
3887 @code{External_Name_Casing} may be used to modify this behavior.
3888 If @code{Uppercase} is specified, then the name
3889 will be forced to all uppercase letters. If @code{Lowercase} is specified,
3890 then the name will be forced to all lowercase letters. A specification of
3891 @code{As_Is} provides the normal default behavior in which the casing is
3892 taken from the string provided.
3895 This pragma may appear anywhere that a pragma is valid. In particular, it
3896 can be used as a configuration pragma in the @code{gnat.adc} file, in which
3897 case it applies to all subsequent compilations, or it can be used as a program
3898 unit pragma, in which case it only applies to the current unit, or it can
3899 be used more locally to control individual Import/Export pragmas.
3901 It was primarily intended for use with OpenVMS systems, where many
3902 compilers convert all symbols to upper case by default. For interfacing to
3903 such compilers (e.g., the DEC C compiler), it may be convenient to use
3907 pragma External_Name_Casing (Uppercase, Uppercase);
3910 to enforce the upper casing of all external symbols.
3912 @node Pragma Fast_Math,Pragma Favor_Top_Level,Pragma External_Name_Casing,Implementation Defined Pragmas
3913 @anchor{gnat_rm/implementation_defined_pragmas pragma-fast-math}@anchor{6d}
3914 @section Pragma Fast_Math
3923 This is a configuration pragma which activates a mode in which speed is
3924 considered more important for floating-point operations than absolutely
3925 accurate adherence to the requirements of the standard. Currently the
3926 following operations are affected:
3931 @item @emph{Complex Multiplication}
3933 The normal simple formula for complex multiplication can result in intermediate
3934 overflows for numbers near the end of the range. The Ada standard requires that
3935 this situation be detected and corrected by scaling, but in Fast_Math mode such
3936 cases will simply result in overflow. Note that to take advantage of this you
3937 must instantiate your own version of @code{Ada.Numerics.Generic_Complex_Types}
3938 under control of the pragma, rather than use the preinstantiated versions.
3941 @node Pragma Favor_Top_Level,Pragma Finalize_Storage_Only,Pragma Fast_Math,Implementation Defined Pragmas
3942 @anchor{gnat_rm/implementation_defined_pragmas id13}@anchor{6e}@anchor{gnat_rm/implementation_defined_pragmas pragma-favor-top-level}@anchor{6f}
3943 @section Pragma Favor_Top_Level
3949 pragma Favor_Top_Level (type_NAME);
3952 The argument of pragma @code{Favor_Top_Level} must be a named access-to-subprogram
3953 type. This pragma is an efficiency hint to the compiler, regarding the use of
3954 @code{'Access} or @code{'Unrestricted_Access} on nested (non-library-level) subprograms.
3955 The pragma means that nested subprograms are not used with this type, or are
3956 rare, so that the generated code should be efficient in the top-level case.
3957 When this pragma is used, dynamically generated trampolines may be used on some
3958 targets for nested subprograms. See restriction @code{No_Implicit_Dynamic_Code}.
3960 @node Pragma Finalize_Storage_Only,Pragma Float_Representation,Pragma Favor_Top_Level,Implementation Defined Pragmas
3961 @anchor{gnat_rm/implementation_defined_pragmas pragma-finalize-storage-only}@anchor{70}
3962 @section Pragma Finalize_Storage_Only
3968 pragma Finalize_Storage_Only (first_subtype_LOCAL_NAME);
3971 The argument of pragma @code{Finalize_Storage_Only} must denote a local type which
3972 is derived from @code{Ada.Finalization.Controlled} or @code{Limited_Controlled}. The
3973 pragma suppresses the call to @code{Finalize} for declared library-level objects
3974 of the argument type. This is mostly useful for types where finalization is
3975 only used to deal with storage reclamation since in most environments it is
3976 not necessary to reclaim memory just before terminating execution, hence the
3977 name. Note that this pragma does not suppress Finalize calls for library-level
3978 heap-allocated objects (see pragma @code{No_Heap_Finalization}).
3980 @node Pragma Float_Representation,Pragma Ghost,Pragma Finalize_Storage_Only,Implementation Defined Pragmas
3981 @anchor{gnat_rm/implementation_defined_pragmas pragma-float-representation}@anchor{71}
3982 @section Pragma Float_Representation
3988 pragma Float_Representation (FLOAT_REP[, float_type_LOCAL_NAME]);
3990 FLOAT_REP ::= VAX_Float | IEEE_Float
3993 In the one argument form, this pragma is a configuration pragma which
3994 allows control over the internal representation chosen for the predefined
3995 floating point types declared in the packages @code{Standard} and
3996 @code{System}. This pragma is only provided for compatibility and has no effect.
3998 The two argument form specifies the representation to be used for
3999 the specified floating-point type. The argument must
4000 be @code{IEEE_Float} to specify the use of IEEE format, as follows:
4006 For a digits value of 6, 32-bit IEEE short format will be used.
4009 For a digits value of 15, 64-bit IEEE long format will be used.
4012 No other value of digits is permitted.
4015 @node Pragma Ghost,Pragma Global,Pragma Float_Representation,Implementation Defined Pragmas
4016 @anchor{gnat_rm/implementation_defined_pragmas pragma-ghost}@anchor{72}@anchor{gnat_rm/implementation_defined_pragmas id14}@anchor{73}
4017 @section Pragma Ghost
4023 pragma Ghost [ (boolean_EXPRESSION) ];
4026 For the semantics of this pragma, see the entry for aspect @code{Ghost} in the SPARK
4027 2014 Reference Manual, section 6.9.
4029 @node Pragma Global,Pragma Ident,Pragma Ghost,Implementation Defined Pragmas
4030 @anchor{gnat_rm/implementation_defined_pragmas pragma-global}@anchor{74}@anchor{gnat_rm/implementation_defined_pragmas id15}@anchor{75}
4031 @section Pragma Global
4037 pragma Global (GLOBAL_SPECIFICATION);
4039 GLOBAL_SPECIFICATION ::=
4042 | (MODED_GLOBAL_LIST @{, MODED_GLOBAL_LIST@})
4044 MODED_GLOBAL_LIST ::= MODE_SELECTOR => GLOBAL_LIST
4046 MODE_SELECTOR ::= In_Out | Input | Output | Proof_In
4047 GLOBAL_LIST ::= GLOBAL_ITEM | (GLOBAL_ITEM @{, GLOBAL_ITEM@})
4048 GLOBAL_ITEM ::= NAME
4051 For the semantics of this pragma, see the entry for aspect @code{Global} in the
4052 SPARK 2014 Reference Manual, section 6.1.4.
4054 @node Pragma Ident,Pragma Ignore_Pragma,Pragma Global,Implementation Defined Pragmas
4055 @anchor{gnat_rm/implementation_defined_pragmas pragma-ident}@anchor{76}
4056 @section Pragma Ident
4062 pragma Ident (static_string_EXPRESSION);
4065 This pragma is identical in effect to pragma @code{Comment}. It is provided
4066 for compatibility with other Ada compilers providing this pragma.
4068 @node Pragma Ignore_Pragma,Pragma Implementation_Defined,Pragma Ident,Implementation Defined Pragmas
4069 @anchor{gnat_rm/implementation_defined_pragmas pragma-ignore-pragma}@anchor{77}
4070 @section Pragma Ignore_Pragma
4076 pragma Ignore_Pragma (pragma_IDENTIFIER);
4079 This is a configuration pragma
4080 that takes a single argument that is a simple identifier. Any subsequent
4081 use of a pragma whose pragma identifier matches this argument will be
4082 silently ignored. This may be useful when legacy code or code intended
4083 for compilation with some other compiler contains pragmas that match the
4084 name, but not the exact implementation, of a GNAT pragma. The use of this
4085 pragma allows such pragmas to be ignored, which may be useful in CodePeer
4086 mode, or during porting of legacy code.
4088 @node Pragma Implementation_Defined,Pragma Implemented,Pragma Ignore_Pragma,Implementation Defined Pragmas
4089 @anchor{gnat_rm/implementation_defined_pragmas pragma-implementation-defined}@anchor{78}
4090 @section Pragma Implementation_Defined
4096 pragma Implementation_Defined (local_NAME);
4099 This pragma marks a previously declared entity as implementation-defined.
4100 For an overloaded entity, applies to the most recent homonym.
4103 pragma Implementation_Defined;
4106 The form with no arguments appears anywhere within a scope, most
4107 typically a package spec, and indicates that all entities that are
4108 defined within the package spec are Implementation_Defined.
4110 This pragma is used within the GNAT runtime library to identify
4111 implementation-defined entities introduced in language-defined units,
4112 for the purpose of implementing the No_Implementation_Identifiers
4115 @node Pragma Implemented,Pragma Implicit_Packing,Pragma Implementation_Defined,Implementation Defined Pragmas
4116 @anchor{gnat_rm/implementation_defined_pragmas pragma-implemented}@anchor{79}
4117 @section Pragma Implemented
4123 pragma Implemented (procedure_LOCAL_NAME, implementation_kind);
4125 implementation_kind ::= By_Entry | By_Protected_Procedure | By_Any
4128 This is an Ada 2012 representation pragma which applies to protected, task
4129 and synchronized interface primitives. The use of pragma Implemented provides
4130 a way to impose a static requirement on the overriding operation by adhering
4131 to one of the three implementation kinds: entry, protected procedure or any of
4132 the above. This pragma is available in all earlier versions of Ada as an
4133 implementation-defined pragma.
4136 type Synch_Iface is synchronized interface;
4137 procedure Prim_Op (Obj : in out Iface) is abstract;
4138 pragma Implemented (Prim_Op, By_Protected_Procedure);
4140 protected type Prot_1 is new Synch_Iface with
4141 procedure Prim_Op; -- Legal
4144 protected type Prot_2 is new Synch_Iface with
4145 entry Prim_Op; -- Illegal
4148 task type Task_Typ is new Synch_Iface with
4149 entry Prim_Op; -- Illegal
4153 When applied to the procedure_or_entry_NAME of a requeue statement, pragma
4154 Implemented determines the runtime behavior of the requeue. Implementation kind
4155 By_Entry guarantees that the action of requeueing will proceed from an entry to
4156 another entry. Implementation kind By_Protected_Procedure transforms the
4157 requeue into a dispatching call, thus eliminating the chance of blocking. Kind
4158 By_Any shares the behavior of By_Entry and By_Protected_Procedure depending on
4159 the target's overriding subprogram kind.
4161 @node Pragma Implicit_Packing,Pragma Import_Function,Pragma Implemented,Implementation Defined Pragmas
4162 @anchor{gnat_rm/implementation_defined_pragmas pragma-implicit-packing}@anchor{7a}
4163 @section Pragma Implicit_Packing
4166 @geindex Rational Profile
4171 pragma Implicit_Packing;
4174 This is a configuration pragma that requests implicit packing for packed
4175 arrays for which a size clause is given but no explicit pragma Pack or
4176 specification of Component_Size is present. It also applies to records
4177 where no record representation clause is present. Consider this example:
4180 type R is array (0 .. 7) of Boolean;
4184 In accordance with the recommendation in the RM (RM 13.3(53)), a Size clause
4185 does not change the layout of a composite object. So the Size clause in the
4186 above example is normally rejected, since the default layout of the array uses
4187 8-bit components, and thus the array requires a minimum of 64 bits.
4189 If this declaration is compiled in a region of code covered by an occurrence
4190 of the configuration pragma Implicit_Packing, then the Size clause in this
4191 and similar examples will cause implicit packing and thus be accepted. For
4192 this implicit packing to occur, the type in question must be an array of small
4193 components whose size is known at compile time, and the Size clause must
4194 specify the exact size that corresponds to the number of elements in the array
4195 multiplied by the size in bits of the component type (both single and
4196 multi-dimensioned arrays can be controlled with this pragma).
4198 @geindex Array packing
4200 Similarly, the following example shows the use in the record case
4204 a, b, c, d, e, f, g, h : boolean;
4210 Without a pragma Pack, each Boolean field requires 8 bits, so the
4211 minimum size is 72 bits, but with a pragma Pack, 16 bits would be
4212 sufficient. The use of pragma Implicit_Packing allows this record
4213 declaration to compile without an explicit pragma Pack.
4215 @node Pragma Import_Function,Pragma Import_Object,Pragma Implicit_Packing,Implementation Defined Pragmas
4216 @anchor{gnat_rm/implementation_defined_pragmas pragma-import-function}@anchor{7b}
4217 @section Pragma Import_Function
4223 pragma Import_Function (
4224 [Internal =>] LOCAL_NAME,
4225 [, [External =>] EXTERNAL_SYMBOL]
4226 [, [Parameter_Types =>] PARAMETER_TYPES]
4227 [, [Result_Type =>] SUBTYPE_MARK]
4228 [, [Mechanism =>] MECHANISM]
4229 [, [Result_Mechanism =>] MECHANISM_NAME]);
4233 | static_string_EXPRESSION
4237 | TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@}
4241 | subtype_Name ' Access
4245 | (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@})
4247 MECHANISM_ASSOCIATION ::=
4248 [formal_parameter_NAME =>] MECHANISM_NAME
4255 This pragma is used in conjunction with a pragma @code{Import} to
4256 specify additional information for an imported function. The pragma
4257 @code{Import} (or equivalent pragma @code{Interface}) must precede the
4258 @code{Import_Function} pragma and both must appear in the same
4259 declarative part as the function specification.
4261 The @code{Internal} argument must uniquely designate
4262 the function to which the
4263 pragma applies. If more than one function name exists of this name in
4264 the declarative part you must use the @code{Parameter_Types} and
4265 @code{Result_Type} parameters to achieve the required unique
4266 designation. Subtype marks in these parameters must exactly match the
4267 subtypes in the corresponding function specification, using positional
4268 notation to match parameters with subtype marks.
4269 The form with an @code{'Access} attribute can be used to match an
4270 anonymous access parameter.
4272 You may optionally use the @code{Mechanism} and @code{Result_Mechanism}
4273 parameters to specify passing mechanisms for the
4274 parameters and result. If you specify a single mechanism name, it
4275 applies to all parameters. Otherwise you may specify a mechanism on a
4276 parameter by parameter basis using either positional or named
4277 notation. If the mechanism is not specified, the default mechanism
4280 @node Pragma Import_Object,Pragma Import_Procedure,Pragma Import_Function,Implementation Defined Pragmas
4281 @anchor{gnat_rm/implementation_defined_pragmas pragma-import-object}@anchor{7c}
4282 @section Pragma Import_Object
4288 pragma Import_Object
4289 [Internal =>] LOCAL_NAME
4290 [, [External =>] EXTERNAL_SYMBOL]
4291 [, [Size =>] EXTERNAL_SYMBOL]);
4295 | static_string_EXPRESSION
4298 This pragma designates an object as imported, and apart from the
4299 extended rules for external symbols, is identical in effect to the use of
4300 the normal @code{Import} pragma applied to an object. Unlike the
4301 subprogram case, you need not use a separate @code{Import} pragma,
4302 although you may do so (and probably should do so from a portability
4303 point of view). @code{size} is syntax checked, but otherwise ignored by
4306 @node Pragma Import_Procedure,Pragma Import_Valued_Procedure,Pragma Import_Object,Implementation Defined Pragmas
4307 @anchor{gnat_rm/implementation_defined_pragmas pragma-import-procedure}@anchor{7d}
4308 @section Pragma Import_Procedure
4314 pragma Import_Procedure (
4315 [Internal =>] LOCAL_NAME
4316 [, [External =>] EXTERNAL_SYMBOL]
4317 [, [Parameter_Types =>] PARAMETER_TYPES]
4318 [, [Mechanism =>] MECHANISM]);
4322 | static_string_EXPRESSION
4326 | TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@}
4330 | subtype_Name ' Access
4334 | (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@})
4336 MECHANISM_ASSOCIATION ::=
4337 [formal_parameter_NAME =>] MECHANISM_NAME
4339 MECHANISM_NAME ::= Value | Reference
4342 This pragma is identical to @code{Import_Function} except that it
4343 applies to a procedure rather than a function and the parameters
4344 @code{Result_Type} and @code{Result_Mechanism} are not permitted.
4346 @node Pragma Import_Valued_Procedure,Pragma Independent,Pragma Import_Procedure,Implementation Defined Pragmas
4347 @anchor{gnat_rm/implementation_defined_pragmas pragma-import-valued-procedure}@anchor{7e}
4348 @section Pragma Import_Valued_Procedure
4354 pragma Import_Valued_Procedure (
4355 [Internal =>] LOCAL_NAME
4356 [, [External =>] EXTERNAL_SYMBOL]
4357 [, [Parameter_Types =>] PARAMETER_TYPES]
4358 [, [Mechanism =>] MECHANISM]);
4362 | static_string_EXPRESSION
4366 | TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@}
4370 | subtype_Name ' Access
4374 | (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@})
4376 MECHANISM_ASSOCIATION ::=
4377 [formal_parameter_NAME =>] MECHANISM_NAME
4379 MECHANISM_NAME ::= Value | Reference
4382 This pragma is identical to @code{Import_Procedure} except that the
4383 first parameter of @code{LOCAL_NAME}, which must be present, must be of
4384 mode @code{out}, and externally the subprogram is treated as a function
4385 with this parameter as the result of the function. The purpose of this
4386 capability is to allow the use of @code{out} and @code{in out}
4387 parameters in interfacing to external functions (which are not permitted
4388 in Ada functions). You may optionally use the @code{Mechanism}
4389 parameters to specify passing mechanisms for the parameters.
4390 If you specify a single mechanism name, it applies to all parameters.
4391 Otherwise you may specify a mechanism on a parameter by parameter
4392 basis using either positional or named notation. If the mechanism is not
4393 specified, the default mechanism is used.
4395 Note that it is important to use this pragma in conjunction with a separate
4396 pragma Import that specifies the desired convention, since otherwise the
4397 default convention is Ada, which is almost certainly not what is required.
4399 @node Pragma Independent,Pragma Independent_Components,Pragma Import_Valued_Procedure,Implementation Defined Pragmas
4400 @anchor{gnat_rm/implementation_defined_pragmas pragma-independent}@anchor{7f}
4401 @section Pragma Independent
4407 pragma Independent (Local_NAME);
4410 This pragma is standard in Ada 2012 mode (which also provides an aspect
4411 of the same name). It is also available as an implementation-defined
4412 pragma in all earlier versions. It specifies that the
4413 designated object or all objects of the designated type must be
4414 independently addressable. This means that separate tasks can safely
4415 manipulate such objects. For example, if two components of a record are
4416 independent, then two separate tasks may access these two components.
4418 constraints on the representation of the object (for instance prohibiting
4421 @node Pragma Independent_Components,Pragma Initial_Condition,Pragma Independent,Implementation Defined Pragmas
4422 @anchor{gnat_rm/implementation_defined_pragmas pragma-independent-components}@anchor{80}
4423 @section Pragma Independent_Components
4429 pragma Independent_Components (Local_NAME);
4432 This pragma is standard in Ada 2012 mode (which also provides an aspect
4433 of the same name). It is also available as an implementation-defined
4434 pragma in all earlier versions. It specifies that the components of the
4435 designated object, or the components of each object of the designated
4437 independently addressable. This means that separate tasks can safely
4438 manipulate separate components in the composite object. This may place
4439 constraints on the representation of the object (for instance prohibiting
4442 @node Pragma Initial_Condition,Pragma Initialize_Scalars,Pragma Independent_Components,Implementation Defined Pragmas
4443 @anchor{gnat_rm/implementation_defined_pragmas id16}@anchor{81}@anchor{gnat_rm/implementation_defined_pragmas pragma-initial-condition}@anchor{82}
4444 @section Pragma Initial_Condition
4450 pragma Initial_Condition (boolean_EXPRESSION);
4453 For the semantics of this pragma, see the entry for aspect @code{Initial_Condition}
4454 in the SPARK 2014 Reference Manual, section 7.1.6.
4456 @node Pragma Initialize_Scalars,Pragma Initializes,Pragma Initial_Condition,Implementation Defined Pragmas
4457 @anchor{gnat_rm/implementation_defined_pragmas pragma-initialize-scalars}@anchor{83}
4458 @section Pragma Initialize_Scalars
4461 @geindex debugging with Initialize_Scalars
4466 pragma Initialize_Scalars
4467 [ ( TYPE_VALUE_PAIR @{, TYPE_VALUE_PAIR@} ) ];
4470 SCALAR_TYPE => static_EXPRESSION
4487 This pragma is similar to @code{Normalize_Scalars} conceptually but has two
4488 important differences.
4490 First, there is no requirement for the pragma to be used uniformly in all units
4491 of a partition. In particular, it is fine to use this just for some or all of
4492 the application units of a partition, without needing to recompile the run-time
4493 library. In the case where some units are compiled with the pragma, and some
4494 without, then a declaration of a variable where the type is defined in package
4495 Standard or is locally declared will always be subject to initialization, as
4496 will any declaration of a scalar variable. For composite variables, whether the
4497 variable is initialized may also depend on whether the package in which the
4498 type of the variable is declared is compiled with the pragma.
4500 The other important difference is that the programmer can control the value
4501 used for initializing scalar objects. This effect can be achieved in several
4508 At compile time, the programmer can specify the invalid value for a
4509 particular family of scalar types using the optional arguments of the pragma.
4511 The compile-time approach is intended to optimize the generated code for the
4512 pragma, by possibly using fast operations such as @code{memset}.
4515 At bind time, the programmer has several options:
4521 Initialization with invalid values (similar to Normalize_Scalars, though
4522 for Initialize_Scalars it is not always possible to determine the invalid
4523 values in complex cases like signed component fields with nonstandard
4527 Initialization with high values.
4530 Initialization with low values.
4533 Initialization with a specific bit pattern.
4536 See the GNAT User's Guide for binder options for specifying these cases.
4538 The bind-time approach is intended to provide fast turnaround for testing
4539 with different values, without having to recompile the program.
4542 At execution time, the programmer can speify the invalid values using an
4543 environment variable. See the GNAT User's Guide for details.
4545 The execution-time approach is intended to provide fast turnaround for
4546 testing with different values, without having to recompile and rebind the
4550 Note that pragma @code{Initialize_Scalars} is particularly useful in conjunction
4551 with the enhanced validity checking that is now provided in GNAT, which checks
4552 for invalid values under more conditions. Using this feature (see description
4553 of the @emph{-gnatV} flag in the GNAT User's Guide) in conjunction with pragma
4554 @code{Initialize_Scalars} provides a powerful new tool to assist in the detection
4555 of problems caused by uninitialized variables.
4557 Note: the use of @code{Initialize_Scalars} has a fairly extensive effect on the
4558 generated code. This may cause your code to be substantially larger. It may
4559 also cause an increase in the amount of stack required, so it is probably a
4560 good idea to turn on stack checking (see description of stack checking in the
4561 GNAT User's Guide) when using this pragma.
4563 @node Pragma Initializes,Pragma Inline_Always,Pragma Initialize_Scalars,Implementation Defined Pragmas
4564 @anchor{gnat_rm/implementation_defined_pragmas pragma-initializes}@anchor{84}@anchor{gnat_rm/implementation_defined_pragmas id17}@anchor{85}
4565 @section Pragma Initializes
4571 pragma Initializes (INITIALIZATION_LIST);
4573 INITIALIZATION_LIST ::=
4575 | (INITIALIZATION_ITEM @{, INITIALIZATION_ITEM@})
4577 INITIALIZATION_ITEM ::= name [=> INPUT_LIST]
4582 | (INPUT @{, INPUT@})
4587 For the semantics of this pragma, see the entry for aspect @code{Initializes} in the
4588 SPARK 2014 Reference Manual, section 7.1.5.
4590 @node Pragma Inline_Always,Pragma Inline_Generic,Pragma Initializes,Implementation Defined Pragmas
4591 @anchor{gnat_rm/implementation_defined_pragmas id18}@anchor{86}@anchor{gnat_rm/implementation_defined_pragmas pragma-inline-always}@anchor{87}
4592 @section Pragma Inline_Always
4598 pragma Inline_Always (NAME [, NAME]);
4601 Similar to pragma @code{Inline} except that inlining is unconditional.
4602 Inline_Always instructs the compiler to inline every direct call to the
4603 subprogram or else to emit a compilation error, independently of any
4604 option, in particular @emph{-gnatn} or @emph{-gnatN} or the optimization level.
4605 It is an error to take the address or access of @code{NAME}. It is also an error to
4606 apply this pragma to a primitive operation of a tagged type. Thanks to such
4607 restrictions, the compiler is allowed to remove the out-of-line body of @code{NAME}.
4609 @node Pragma Inline_Generic,Pragma Interface,Pragma Inline_Always,Implementation Defined Pragmas
4610 @anchor{gnat_rm/implementation_defined_pragmas pragma-inline-generic}@anchor{88}
4611 @section Pragma Inline_Generic
4617 pragma Inline_Generic (GNAME @{, GNAME@});
4619 GNAME ::= generic_unit_NAME | generic_instance_NAME
4622 This pragma is provided for compatibility with Dec Ada 83. It has
4623 no effect in GNAT (which always inlines generics), other
4624 than to check that the given names are all names of generic units or
4627 @node Pragma Interface,Pragma Interface_Name,Pragma Inline_Generic,Implementation Defined Pragmas
4628 @anchor{gnat_rm/implementation_defined_pragmas pragma-interface}@anchor{89}
4629 @section Pragma Interface
4636 [Convention =>] convention_identifier,
4637 [Entity =>] local_NAME
4638 [, [External_Name =>] static_string_expression]
4639 [, [Link_Name =>] static_string_expression]);
4642 This pragma is identical in syntax and semantics to
4643 the standard Ada pragma @code{Import}. It is provided for compatibility
4644 with Ada 83. The definition is upwards compatible both with pragma
4645 @code{Interface} as defined in the Ada 83 Reference Manual, and also
4646 with some extended implementations of this pragma in certain Ada 83
4647 implementations. The only difference between pragma @code{Interface}
4648 and pragma @code{Import} is that there is special circuitry to allow
4649 both pragmas to appear for the same subprogram entity (normally it
4650 is illegal to have multiple @code{Import} pragmas. This is useful in
4651 maintaining Ada 83/Ada 95 compatibility and is compatible with other
4654 @node Pragma Interface_Name,Pragma Interrupt_Handler,Pragma Interface,Implementation Defined Pragmas
4655 @anchor{gnat_rm/implementation_defined_pragmas pragma-interface-name}@anchor{8a}
4656 @section Pragma Interface_Name
4662 pragma Interface_Name (
4663 [Entity =>] LOCAL_NAME
4664 [, [External_Name =>] static_string_EXPRESSION]
4665 [, [Link_Name =>] static_string_EXPRESSION]);
4668 This pragma provides an alternative way of specifying the interface name
4669 for an interfaced subprogram, and is provided for compatibility with Ada
4670 83 compilers that use the pragma for this purpose. You must provide at
4671 least one of @code{External_Name} or @code{Link_Name}.
4673 @node Pragma Interrupt_Handler,Pragma Interrupt_State,Pragma Interface_Name,Implementation Defined Pragmas
4674 @anchor{gnat_rm/implementation_defined_pragmas pragma-interrupt-handler}@anchor{8b}
4675 @section Pragma Interrupt_Handler
4681 pragma Interrupt_Handler (procedure_LOCAL_NAME);
4684 This program unit pragma is supported for parameterless protected procedures
4685 as described in Annex C of the Ada Reference Manual. On the AAMP target
4686 the pragma can also be specified for nonprotected parameterless procedures
4687 that are declared at the library level (which includes procedures
4688 declared at the top level of a library package). In the case of AAMP,
4689 when this pragma is applied to a nonprotected procedure, the instruction
4690 @code{IERET} is generated for returns from the procedure, enabling
4691 maskable interrupts, in place of the normal return instruction.
4693 @node Pragma Interrupt_State,Pragma Invariant,Pragma Interrupt_Handler,Implementation Defined Pragmas
4694 @anchor{gnat_rm/implementation_defined_pragmas pragma-interrupt-state}@anchor{8c}
4695 @section Pragma Interrupt_State
4701 pragma Interrupt_State
4703 [State =>] SYSTEM | RUNTIME | USER);
4706 Normally certain interrupts are reserved to the implementation. Any attempt
4707 to attach an interrupt causes Program_Error to be raised, as described in
4708 RM C.3.2(22). A typical example is the @code{SIGINT} interrupt used in
4709 many systems for an @code{Ctrl-C} interrupt. Normally this interrupt is
4710 reserved to the implementation, so that @code{Ctrl-C} can be used to
4711 interrupt execution. Additionally, signals such as @code{SIGSEGV},
4712 @code{SIGABRT}, @code{SIGFPE} and @code{SIGILL} are often mapped to specific
4713 Ada exceptions, or used to implement run-time functions such as the
4714 @code{abort} statement and stack overflow checking.
4716 Pragma @code{Interrupt_State} provides a general mechanism for overriding
4717 such uses of interrupts. It subsumes the functionality of pragma
4718 @code{Unreserve_All_Interrupts}. Pragma @code{Interrupt_State} is not
4719 available on Windows or VMS. On all other platforms than VxWorks,
4720 it applies to signals; on VxWorks, it applies to vectored hardware interrupts
4721 and may be used to mark interrupts required by the board support package
4724 Interrupts can be in one of three states:
4732 The interrupt is reserved (no Ada handler can be installed), and the
4733 Ada run-time may not install a handler. As a result you are guaranteed
4734 standard system default action if this interrupt is raised. This also allows
4735 installing a low level handler via C APIs such as sigaction(), outside
4741 The interrupt is reserved (no Ada handler can be installed). The run time
4742 is allowed to install a handler for internal control purposes, but is
4743 not required to do so.
4748 The interrupt is unreserved. The user may install an Ada handler via
4749 Ada.Interrupts and pragma Interrupt_Handler or Attach_Handler to provide
4753 These states are the allowed values of the @code{State} parameter of the
4754 pragma. The @code{Name} parameter is a value of the type
4755 @code{Ada.Interrupts.Interrupt_ID}. Typically, it is a name declared in
4756 @code{Ada.Interrupts.Names}.
4758 This is a configuration pragma, and the binder will check that there
4759 are no inconsistencies between different units in a partition in how a
4760 given interrupt is specified. It may appear anywhere a pragma is legal.
4762 The effect is to move the interrupt to the specified state.
4764 By declaring interrupts to be SYSTEM, you guarantee the standard system
4765 action, such as a core dump.
4767 By declaring interrupts to be USER, you guarantee that you can install
4770 Note that certain signals on many operating systems cannot be caught and
4771 handled by applications. In such cases, the pragma is ignored. See the
4772 operating system documentation, or the value of the array @code{Reserved}
4773 declared in the spec of package @code{System.OS_Interface}.
4775 Overriding the default state of signals used by the Ada runtime may interfere
4776 with an application's runtime behavior in the cases of the synchronous signals,
4777 and in the case of the signal used to implement the @code{abort} statement.
4779 @node Pragma Invariant,Pragma Keep_Names,Pragma Interrupt_State,Implementation Defined Pragmas
4780 @anchor{gnat_rm/implementation_defined_pragmas id19}@anchor{8d}@anchor{gnat_rm/implementation_defined_pragmas pragma-invariant}@anchor{8e}
4781 @section Pragma Invariant
4788 ([Entity =>] private_type_LOCAL_NAME,
4789 [Check =>] EXPRESSION
4790 [,[Message =>] String_Expression]);
4793 This pragma provides exactly the same capabilities as the Type_Invariant aspect
4794 defined in AI05-0146-1, and in the Ada 2012 Reference Manual. The
4795 Type_Invariant aspect is fully implemented in Ada 2012 mode, but since it
4796 requires the use of the aspect syntax, which is not available except in 2012
4797 mode, it is not possible to use the Type_Invariant aspect in earlier versions
4798 of Ada. However the Invariant pragma may be used in any version of Ada. Also
4799 note that the aspect Invariant is a synonym in GNAT for the aspect
4800 Type_Invariant, but there is no pragma Type_Invariant.
4802 The pragma must appear within the visible part of the package specification,
4803 after the type to which its Entity argument appears. As with the Invariant
4804 aspect, the Check expression is not analyzed until the end of the visible
4805 part of the package, so it may contain forward references. The Message
4806 argument, if present, provides the exception message used if the invariant
4807 is violated. If no Message parameter is provided, a default message that
4808 identifies the line on which the pragma appears is used.
4810 It is permissible to have multiple Invariants for the same type entity, in
4811 which case they are and'ed together. It is permissible to use this pragma
4812 in Ada 2012 mode, but you cannot have both an invariant aspect and an
4813 invariant pragma for the same entity.
4815 For further details on the use of this pragma, see the Ada 2012 documentation
4816 of the Type_Invariant aspect.
4818 @node Pragma Keep_Names,Pragma License,Pragma Invariant,Implementation Defined Pragmas
4819 @anchor{gnat_rm/implementation_defined_pragmas pragma-keep-names}@anchor{8f}
4820 @section Pragma Keep_Names
4826 pragma Keep_Names ([On =>] enumeration_first_subtype_LOCAL_NAME);
4829 The @code{LOCAL_NAME} argument
4830 must refer to an enumeration first subtype
4831 in the current declarative part. The effect is to retain the enumeration
4832 literal names for use by @code{Image} and @code{Value} even if a global
4833 @code{Discard_Names} pragma applies. This is useful when you want to
4834 generally suppress enumeration literal names and for example you therefore
4835 use a @code{Discard_Names} pragma in the @code{gnat.adc} file, but you
4836 want to retain the names for specific enumeration types.
4838 @node Pragma License,Pragma Link_With,Pragma Keep_Names,Implementation Defined Pragmas
4839 @anchor{gnat_rm/implementation_defined_pragmas pragma-license}@anchor{90}
4840 @section Pragma License
4843 @geindex License checking
4848 pragma License (Unrestricted | GPL | Modified_GPL | Restricted);
4851 This pragma is provided to allow automated checking for appropriate license
4852 conditions with respect to the standard and modified GPL. A pragma
4853 @code{License}, which is a configuration pragma that typically appears at
4854 the start of a source file or in a separate @code{gnat.adc} file, specifies
4855 the licensing conditions of a unit as follows:
4862 This is used for a unit that can be freely used with no license restrictions.
4863 Examples of such units are public domain units, and units from the Ada
4868 This is used for a unit that is licensed under the unmodified GPL, and which
4869 therefore cannot be @code{with}ed by a restricted unit.
4873 This is used for a unit licensed under the GNAT modified GPL that includes
4874 a special exception paragraph that specifically permits the inclusion of
4875 the unit in programs without requiring the entire program to be released
4880 This is used for a unit that is restricted in that it is not permitted to
4881 depend on units that are licensed under the GPL. Typical examples are
4882 proprietary code that is to be released under more restrictive license
4883 conditions. Note that restricted units are permitted to @code{with} units
4884 which are licensed under the modified GPL (this is the whole point of the
4888 Normally a unit with no @code{License} pragma is considered to have an
4889 unknown license, and no checking is done. However, standard GNAT headers
4890 are recognized, and license information is derived from them as follows.
4892 A GNAT license header starts with a line containing 78 hyphens. The following
4893 comment text is searched for the appearance of any of the following strings.
4895 If the string 'GNU General Public License' is found, then the unit is assumed
4896 to have GPL license, unless the string 'As a special exception' follows, in
4897 which case the license is assumed to be modified GPL.
4899 If one of the strings
4900 'This specification is adapted from the Ada Semantic Interface' or
4901 'This specification is derived from the Ada Reference Manual' is found
4902 then the unit is assumed to be unrestricted.
4904 These default actions means that a program with a restricted license pragma
4905 will automatically get warnings if a GPL unit is inappropriately
4906 @code{with}ed. For example, the program:
4911 procedure Secret_Stuff is
4916 if compiled with pragma @code{License} (@code{Restricted}) in a
4917 @code{gnat.adc} file will generate the warning:
4922 >>> license of withed unit "Sem_Ch3" is incompatible
4924 2. with GNAT.Sockets;
4925 3. procedure Secret_Stuff is
4928 Here we get a warning on @code{Sem_Ch3} since it is part of the GNAT
4929 compiler and is licensed under the
4930 GPL, but no warning for @code{GNAT.Sockets} which is part of the GNAT
4931 run time, and is therefore licensed under the modified GPL.
4933 @node Pragma Link_With,Pragma Linker_Alias,Pragma License,Implementation Defined Pragmas
4934 @anchor{gnat_rm/implementation_defined_pragmas pragma-link-with}@anchor{91}
4935 @section Pragma Link_With
4941 pragma Link_With (static_string_EXPRESSION @{,static_string_EXPRESSION@});
4944 This pragma is provided for compatibility with certain Ada 83 compilers.
4945 It has exactly the same effect as pragma @code{Linker_Options} except
4946 that spaces occurring within one of the string expressions are treated
4947 as separators. For example, in the following case:
4950 pragma Link_With ("-labc -ldef");
4953 results in passing the strings @code{-labc} and @code{-ldef} as two
4954 separate arguments to the linker. In addition pragma Link_With allows
4955 multiple arguments, with the same effect as successive pragmas.
4957 @node Pragma Linker_Alias,Pragma Linker_Constructor,Pragma Link_With,Implementation Defined Pragmas
4958 @anchor{gnat_rm/implementation_defined_pragmas pragma-linker-alias}@anchor{92}
4959 @section Pragma Linker_Alias
4965 pragma Linker_Alias (
4966 [Entity =>] LOCAL_NAME,
4967 [Target =>] static_string_EXPRESSION);
4970 @code{LOCAL_NAME} must refer to an object that is declared at the library
4971 level. This pragma establishes the given entity as a linker alias for the
4972 given target. It is equivalent to @code{__attribute__((alias))} in GNU C
4973 and causes @code{LOCAL_NAME} to be emitted as an alias for the symbol
4974 @code{static_string_EXPRESSION} in the object file, that is to say no space
4975 is reserved for @code{LOCAL_NAME} by the assembler and it will be resolved
4976 to the same address as @code{static_string_EXPRESSION} by the linker.
4978 The actual linker name for the target must be used (e.g., the fully
4979 encoded name with qualification in Ada, or the mangled name in C++),
4980 or it must be declared using the C convention with @code{pragma Import}
4981 or @code{pragma Export}.
4983 Not all target machines support this pragma. On some of them it is accepted
4984 only if @code{pragma Weak_External} has been applied to @code{LOCAL_NAME}.
4987 -- Example of the use of pragma Linker_Alias
4991 pragma Export (C, i);
4993 new_name_for_i : Integer;
4994 pragma Linker_Alias (new_name_for_i, "i");
4998 @node Pragma Linker_Constructor,Pragma Linker_Destructor,Pragma Linker_Alias,Implementation Defined Pragmas
4999 @anchor{gnat_rm/implementation_defined_pragmas pragma-linker-constructor}@anchor{93}
5000 @section Pragma Linker_Constructor
5006 pragma Linker_Constructor (procedure_LOCAL_NAME);
5009 @code{procedure_LOCAL_NAME} must refer to a parameterless procedure that
5010 is declared at the library level. A procedure to which this pragma is
5011 applied will be treated as an initialization routine by the linker.
5012 It is equivalent to @code{__attribute__((constructor))} in GNU C and
5013 causes @code{procedure_LOCAL_NAME} to be invoked before the entry point
5014 of the executable is called (or immediately after the shared library is
5015 loaded if the procedure is linked in a shared library), in particular
5016 before the Ada run-time environment is set up.
5018 Because of these specific contexts, the set of operations such a procedure
5019 can perform is very limited and the type of objects it can manipulate is
5020 essentially restricted to the elementary types. In particular, it must only
5021 contain code to which pragma Restrictions (No_Elaboration_Code) applies.
5023 This pragma is used by GNAT to implement auto-initialization of shared Stand
5024 Alone Libraries, which provides a related capability without the restrictions
5025 listed above. Where possible, the use of Stand Alone Libraries is preferable
5026 to the use of this pragma.
5028 @node Pragma Linker_Destructor,Pragma Linker_Section,Pragma Linker_Constructor,Implementation Defined Pragmas
5029 @anchor{gnat_rm/implementation_defined_pragmas pragma-linker-destructor}@anchor{94}
5030 @section Pragma Linker_Destructor
5036 pragma Linker_Destructor (procedure_LOCAL_NAME);
5039 @code{procedure_LOCAL_NAME} must refer to a parameterless procedure that
5040 is declared at the library level. A procedure to which this pragma is
5041 applied will be treated as a finalization routine by the linker.
5042 It is equivalent to @code{__attribute__((destructor))} in GNU C and
5043 causes @code{procedure_LOCAL_NAME} to be invoked after the entry point
5044 of the executable has exited (or immediately before the shared library
5045 is unloaded if the procedure is linked in a shared library), in particular
5046 after the Ada run-time environment is shut down.
5048 See @code{pragma Linker_Constructor} for the set of restrictions that apply
5049 because of these specific contexts.
5051 @node Pragma Linker_Section,Pragma Lock_Free,Pragma Linker_Destructor,Implementation Defined Pragmas
5052 @anchor{gnat_rm/implementation_defined_pragmas id20}@anchor{95}@anchor{gnat_rm/implementation_defined_pragmas pragma-linker-section}@anchor{96}
5053 @section Pragma Linker_Section
5059 pragma Linker_Section (
5060 [Entity =>] LOCAL_NAME,
5061 [Section =>] static_string_EXPRESSION);
5064 @code{LOCAL_NAME} must refer to an object, type, or subprogram that is
5065 declared at the library level. This pragma specifies the name of the
5066 linker section for the given entity. It is equivalent to
5067 @code{__attribute__((section))} in GNU C and causes @code{LOCAL_NAME} to
5068 be placed in the @code{static_string_EXPRESSION} section of the
5069 executable (assuming the linker doesn't rename the section).
5070 GNAT also provides an implementation defined aspect of the same name.
5072 In the case of specifying this aspect for a type, the effect is to
5073 specify the corresponding section for all library-level objects of
5074 the type that do not have an explicit linker section set. Note that
5075 this only applies to whole objects, not to components of composite objects.
5077 In the case of a subprogram, the linker section applies to all previously
5078 declared matching overloaded subprograms in the current declarative part
5079 which do not already have a linker section assigned. The linker section
5080 aspect is useful in this case for specifying different linker sections
5081 for different elements of such an overloaded set.
5083 Note that an empty string specifies that no linker section is specified.
5084 This is not quite the same as omitting the pragma or aspect, since it
5085 can be used to specify that one element of an overloaded set of subprograms
5086 has the default linker section, or that one object of a type for which a
5087 linker section is specified should has the default linker section.
5089 The compiler normally places library-level entities in standard sections
5090 depending on the class: procedures and functions generally go in the
5091 @code{.text} section, initialized variables in the @code{.data} section
5092 and uninitialized variables in the @code{.bss} section.
5094 Other, special sections may exist on given target machines to map special
5095 hardware, for example I/O ports or flash memory. This pragma is a means to
5096 defer the final layout of the executable to the linker, thus fully working
5097 at the symbolic level with the compiler.
5099 Some file formats do not support arbitrary sections so not all target
5100 machines support this pragma. The use of this pragma may cause a program
5101 execution to be erroneous if it is used to place an entity into an
5102 inappropriate section (e.g., a modified variable into the @code{.text}
5103 section). See also @code{pragma Persistent_BSS}.
5106 -- Example of the use of pragma Linker_Section
5110 pragma Volatile (Port_A);
5111 pragma Linker_Section (Port_A, ".bss.port_a");
5114 pragma Volatile (Port_B);
5115 pragma Linker_Section (Port_B, ".bss.port_b");
5117 type Port_Type is new Integer with Linker_Section => ".bss";
5118 PA : Port_Type with Linker_Section => ".bss.PA";
5119 PB : Port_Type; -- ends up in linker section ".bss"
5121 procedure Q with Linker_Section => "Qsection";
5125 @node Pragma Lock_Free,Pragma Loop_Invariant,Pragma Linker_Section,Implementation Defined Pragmas
5126 @anchor{gnat_rm/implementation_defined_pragmas id21}@anchor{97}@anchor{gnat_rm/implementation_defined_pragmas pragma-lock-free}@anchor{98}
5127 @section Pragma Lock_Free
5131 This pragma may be specified for protected types or objects. It specifies that
5132 the implementation of protected operations must be implemented without locks.
5133 Compilation fails if the compiler cannot generate lock-free code for the
5136 The current conditions required to support this pragma are:
5142 Protected type declarations may not contain entries
5145 Protected subprogram declarations may not have nonelementary parameters
5148 In addition, each protected subprogram body must satisfy:
5154 May reference only one protected component
5157 May not reference nonconstant entities outside the protected subprogram
5161 May not contain address representation items, allocators, or quantified
5165 May not contain delay, goto, loop, or procedure-call statements.
5168 May not contain exported and imported entities
5171 May not dereferenced access values
5174 Function calls and attribute references must be static
5177 @node Pragma Loop_Invariant,Pragma Loop_Optimize,Pragma Lock_Free,Implementation Defined Pragmas
5178 @anchor{gnat_rm/implementation_defined_pragmas pragma-loop-invariant}@anchor{99}
5179 @section Pragma Loop_Invariant
5185 pragma Loop_Invariant ( boolean_EXPRESSION );
5188 The effect of this pragma is similar to that of pragma @code{Assert},
5189 except that in an @code{Assertion_Policy} pragma, the identifier
5190 @code{Loop_Invariant} is used to control whether it is ignored or checked
5193 @code{Loop_Invariant} can only appear as one of the items in the sequence
5194 of statements of a loop body, or nested inside block statements that
5195 appear in the sequence of statements of a loop body.
5196 The intention is that it be used to
5197 represent a "loop invariant" assertion, i.e. something that is true each
5198 time through the loop, and which can be used to show that the loop is
5199 achieving its purpose.
5201 Multiple @code{Loop_Invariant} and @code{Loop_Variant} pragmas that
5202 apply to the same loop should be grouped in the same sequence of
5205 To aid in writing such invariants, the special attribute @code{Loop_Entry}
5206 may be used to refer to the value of an expression on entry to the loop. This
5207 attribute can only be used within the expression of a @code{Loop_Invariant}
5208 pragma. For full details, see documentation of attribute @code{Loop_Entry}.
5210 @node Pragma Loop_Optimize,Pragma Loop_Variant,Pragma Loop_Invariant,Implementation Defined Pragmas
5211 @anchor{gnat_rm/implementation_defined_pragmas pragma-loop-optimize}@anchor{9a}
5212 @section Pragma Loop_Optimize
5218 pragma Loop_Optimize (OPTIMIZATION_HINT @{, OPTIMIZATION_HINT@});
5220 OPTIMIZATION_HINT ::= Ivdep | No_Unroll | Unroll | No_Vector | Vector
5223 This pragma must appear immediately within a loop statement. It allows the
5224 programmer to specify optimization hints for the enclosing loop. The hints
5225 are not mutually exclusive and can be freely mixed, but not all combinations
5226 will yield a sensible outcome.
5228 There are five supported optimization hints for a loop:
5236 The programmer asserts that there are no loop-carried dependencies
5237 which would prevent consecutive iterations of the loop from being
5238 executed simultaneously.
5243 The loop must not be unrolled. This is a strong hint: the compiler will not
5244 unroll a loop marked with this hint.
5249 The loop should be unrolled. This is a weak hint: the compiler will try to
5250 apply unrolling to this loop preferably to other optimizations, notably
5251 vectorization, but there is no guarantee that the loop will be unrolled.
5256 The loop must not be vectorized. This is a strong hint: the compiler will not
5257 vectorize a loop marked with this hint.
5262 The loop should be vectorized. This is a weak hint: the compiler will try to
5263 apply vectorization to this loop preferably to other optimizations, notably
5264 unrolling, but there is no guarantee that the loop will be vectorized.
5267 These hints do not remove the need to pass the appropriate switches to the
5268 compiler in order to enable the relevant optimizations, that is to say
5269 @emph{-funroll-loops} for unrolling and @emph{-ftree-vectorize} for
5272 @node Pragma Loop_Variant,Pragma Machine_Attribute,Pragma Loop_Optimize,Implementation Defined Pragmas
5273 @anchor{gnat_rm/implementation_defined_pragmas pragma-loop-variant}@anchor{9b}
5274 @section Pragma Loop_Variant
5280 pragma Loop_Variant ( LOOP_VARIANT_ITEM @{, LOOP_VARIANT_ITEM @} );
5281 LOOP_VARIANT_ITEM ::= CHANGE_DIRECTION => discrete_EXPRESSION
5282 CHANGE_DIRECTION ::= Increases | Decreases
5285 @code{Loop_Variant} can only appear as one of the items in the sequence
5286 of statements of a loop body, or nested inside block statements that
5287 appear in the sequence of statements of a loop body.
5288 It allows the specification of quantities which must always
5289 decrease or increase in successive iterations of the loop. In its simplest
5290 form, just one expression is specified, whose value must increase or decrease
5291 on each iteration of the loop.
5293 In a more complex form, multiple arguments can be given which are intepreted
5294 in a nesting lexicographic manner. For example:
5297 pragma Loop_Variant (Increases => X, Decreases => Y);
5300 specifies that each time through the loop either X increases, or X stays
5301 the same and Y decreases. A @code{Loop_Variant} pragma ensures that the
5302 loop is making progress. It can be useful in helping to show informally
5303 or prove formally that the loop always terminates.
5305 @code{Loop_Variant} is an assertion whose effect can be controlled using
5306 an @code{Assertion_Policy} with a check name of @code{Loop_Variant}. The
5307 policy can be @code{Check} to enable the loop variant check, @code{Ignore}
5308 to ignore the check (in which case the pragma has no effect on the program),
5309 or @code{Disable} in which case the pragma is not even checked for correct
5312 Multiple @code{Loop_Invariant} and @code{Loop_Variant} pragmas that
5313 apply to the same loop should be grouped in the same sequence of
5316 The @code{Loop_Entry} attribute may be used within the expressions of the
5317 @code{Loop_Variant} pragma to refer to values on entry to the loop.
5319 @node Pragma Machine_Attribute,Pragma Main,Pragma Loop_Variant,Implementation Defined Pragmas
5320 @anchor{gnat_rm/implementation_defined_pragmas pragma-machine-attribute}@anchor{9c}
5321 @section Pragma Machine_Attribute
5327 pragma Machine_Attribute (
5328 [Entity =>] LOCAL_NAME,
5329 [Attribute_Name =>] static_string_EXPRESSION
5330 [, [Info =>] static_EXPRESSION @{, static_EXPRESSION@}] );
5333 Machine-dependent attributes can be specified for types and/or
5334 declarations. This pragma is semantically equivalent to
5335 @code{__attribute__((@emph{attribute_name}))} (if @code{info} is not
5336 specified) or @code{__attribute__((@emph{attribute_name(info})))}
5337 or @code{__attribute__((@emph{attribute_name(info,...})))} in GNU C,
5338 where @emph{attribute_name} is recognized by the compiler middle-end
5339 or the @code{TARGET_ATTRIBUTE_TABLE} machine specific macro. Note
5340 that a string literal for the optional parameter @code{info} or the
5341 following ones is transformed by default into an identifier,
5342 which may make this pragma unusable for some attributes.
5343 For further information see @cite{GNU Compiler Collection (GCC) Internals}.
5345 @node Pragma Main,Pragma Main_Storage,Pragma Machine_Attribute,Implementation Defined Pragmas
5346 @anchor{gnat_rm/implementation_defined_pragmas pragma-main}@anchor{9d}
5347 @section Pragma Main
5354 (MAIN_OPTION [, MAIN_OPTION]);
5357 [Stack_Size =>] static_integer_EXPRESSION
5358 | [Task_Stack_Size_Default =>] static_integer_EXPRESSION
5359 | [Time_Slicing_Enabled =>] static_boolean_EXPRESSION
5362 This pragma is provided for compatibility with OpenVMS VAX Systems. It has
5363 no effect in GNAT, other than being syntax checked.
5365 @node Pragma Main_Storage,Pragma Max_Queue_Length,Pragma Main,Implementation Defined Pragmas
5366 @anchor{gnat_rm/implementation_defined_pragmas pragma-main-storage}@anchor{9e}
5367 @section Pragma Main_Storage
5374 (MAIN_STORAGE_OPTION [, MAIN_STORAGE_OPTION]);
5376 MAIN_STORAGE_OPTION ::=
5377 [WORKING_STORAGE =>] static_SIMPLE_EXPRESSION
5378 | [TOP_GUARD =>] static_SIMPLE_EXPRESSION
5381 This pragma is provided for compatibility with OpenVMS VAX Systems. It has
5382 no effect in GNAT, other than being syntax checked.
5384 @node Pragma Max_Queue_Length,Pragma No_Body,Pragma Main_Storage,Implementation Defined Pragmas
5385 @anchor{gnat_rm/implementation_defined_pragmas id22}@anchor{9f}@anchor{gnat_rm/implementation_defined_pragmas pragma-max-queue-length}@anchor{a0}
5386 @section Pragma Max_Queue_Length
5392 pragma Max_Entry_Queue (static_integer_EXPRESSION);
5395 This pragma is used to specify the maximum callers per entry queue for
5396 individual protected entries and entry families. It accepts a single
5397 positive integer as a parameter and must appear after the declaration
5400 @node Pragma No_Body,Pragma No_Caching,Pragma Max_Queue_Length,Implementation Defined Pragmas
5401 @anchor{gnat_rm/implementation_defined_pragmas pragma-no-body}@anchor{a1}
5402 @section Pragma No_Body
5411 There are a number of cases in which a package spec does not require a body,
5412 and in fact a body is not permitted. GNAT will not permit the spec to be
5413 compiled if there is a body around. The pragma No_Body allows you to provide
5414 a body file, even in a case where no body is allowed. The body file must
5415 contain only comments and a single No_Body pragma. This is recognized by
5416 the compiler as indicating that no body is logically present.
5418 This is particularly useful during maintenance when a package is modified in
5419 such a way that a body needed before is no longer needed. The provision of a
5420 dummy body with a No_Body pragma ensures that there is no interference from
5421 earlier versions of the package body.
5423 @node Pragma No_Caching,Pragma No_Component_Reordering,Pragma No_Body,Implementation Defined Pragmas
5424 @anchor{gnat_rm/implementation_defined_pragmas pragma-no-caching}@anchor{a2}@anchor{gnat_rm/implementation_defined_pragmas id23}@anchor{a3}
5425 @section Pragma No_Caching
5431 pragma No_Caching [ (boolean_EXPRESSION) ];
5434 For the semantics of this pragma, see the entry for aspect @code{No_Caching} in
5435 the SPARK 2014 Reference Manual, section 7.1.2.
5437 @node Pragma No_Component_Reordering,Pragma No_Elaboration_Code_All,Pragma No_Caching,Implementation Defined Pragmas
5438 @anchor{gnat_rm/implementation_defined_pragmas pragma-no-component-reordering}@anchor{a4}
5439 @section Pragma No_Component_Reordering
5445 pragma No_Component_Reordering [([Entity =>] type_LOCAL_NAME)];
5448 @code{type_LOCAL_NAME} must refer to a record type declaration in the current
5449 declarative part. The effect is to preclude any reordering of components
5450 for the layout of the record, i.e. the record is laid out by the compiler
5451 in the order in which the components are declared textually. The form with
5452 no argument is a configuration pragma which applies to all record types
5453 declared in units to which the pragma applies and there is a requirement
5454 that this pragma be used consistently within a partition.
5456 @node Pragma No_Elaboration_Code_All,Pragma No_Heap_Finalization,Pragma No_Component_Reordering,Implementation Defined Pragmas
5457 @anchor{gnat_rm/implementation_defined_pragmas id24}@anchor{a5}@anchor{gnat_rm/implementation_defined_pragmas pragma-no-elaboration-code-all}@anchor{a6}
5458 @section Pragma No_Elaboration_Code_All
5464 pragma No_Elaboration_Code_All [(program_unit_NAME)];
5467 This is a program unit pragma (there is also an equivalent aspect of the
5468 same name) that establishes the restriction @code{No_Elaboration_Code} for
5469 the current unit and any extended main source units (body and subunits).
5470 It also has the effect of enforcing a transitive application of this
5471 aspect, so that if any unit is implicitly or explicitly with'ed by the
5472 current unit, it must also have the No_Elaboration_Code_All aspect set.
5473 It may be applied to package or subprogram specs or their generic versions.
5475 @node Pragma No_Heap_Finalization,Pragma No_Inline,Pragma No_Elaboration_Code_All,Implementation Defined Pragmas
5476 @anchor{gnat_rm/implementation_defined_pragmas pragma-no-heap-finalization}@anchor{a7}
5477 @section Pragma No_Heap_Finalization
5483 pragma No_Heap_Finalization [ (first_subtype_LOCAL_NAME) ];
5486 Pragma @code{No_Heap_Finalization} may be used as a configuration pragma or as a
5487 type-specific pragma.
5489 In its configuration form, the pragma must appear within a configuration file
5490 such as gnat.adc, without an argument. The pragma suppresses the call to
5491 @code{Finalize} for heap-allocated objects created through library-level named
5492 access-to-object types in cases where the designated type requires finalization
5495 In its type-specific form, the argument of the pragma must denote a
5496 library-level named access-to-object type. The pragma suppresses the call to
5497 @code{Finalize} for heap-allocated objects created through the specific access type
5498 in cases where the designated type requires finalization actions.
5500 It is still possible to finalize such heap-allocated objects by explicitly
5503 A library-level named access-to-object type declared within a generic unit will
5504 lose its @code{No_Heap_Finalization} pragma when the corresponding instance does not
5505 appear at the library level.
5507 @node Pragma No_Inline,Pragma No_Return,Pragma No_Heap_Finalization,Implementation Defined Pragmas
5508 @anchor{gnat_rm/implementation_defined_pragmas id25}@anchor{a8}@anchor{gnat_rm/implementation_defined_pragmas pragma-no-inline}@anchor{a9}
5509 @section Pragma No_Inline
5515 pragma No_Inline (NAME @{, NAME@});
5518 This pragma suppresses inlining for the callable entity or the instances of
5519 the generic subprogram designated by @code{NAME}, including inlining that
5520 results from the use of pragma @code{Inline}. This pragma is always active,
5521 in particular it is not subject to the use of option @emph{-gnatn} or
5522 @emph{-gnatN}. It is illegal to specify both pragma @code{No_Inline} and
5523 pragma @code{Inline_Always} for the same @code{NAME}.
5525 @node Pragma No_Return,Pragma No_Run_Time,Pragma No_Inline,Implementation Defined Pragmas
5526 @anchor{gnat_rm/implementation_defined_pragmas pragma-no-return}@anchor{aa}
5527 @section Pragma No_Return
5533 pragma No_Return (procedure_LOCAL_NAME @{, procedure_LOCAL_NAME@});
5536 Each @code{procedure_LOCAL_NAME} argument must refer to one or more procedure
5537 declarations in the current declarative part. A procedure to which this
5538 pragma is applied may not contain any explicit @code{return} statements.
5539 In addition, if the procedure contains any implicit returns from falling
5540 off the end of a statement sequence, then execution of that implicit
5541 return will cause Program_Error to be raised.
5543 One use of this pragma is to identify procedures whose only purpose is to raise
5544 an exception. Another use of this pragma is to suppress incorrect warnings
5545 about missing returns in functions, where the last statement of a function
5546 statement sequence is a call to such a procedure.
5548 Note that in Ada 2005 mode, this pragma is part of the language. It is
5549 available in all earlier versions of Ada as an implementation-defined
5552 @node Pragma No_Run_Time,Pragma No_Strict_Aliasing,Pragma No_Return,Implementation Defined Pragmas
5553 @anchor{gnat_rm/implementation_defined_pragmas pragma-no-run-time}@anchor{ab}
5554 @section Pragma No_Run_Time
5563 This is an obsolete configuration pragma that historically was used to
5564 set up a runtime library with no object code. It is now used only for
5565 internal testing. The pragma has been superseded by the reconfigurable
5566 runtime capability of GNAT.
5568 @node Pragma No_Strict_Aliasing,Pragma No_Tagged_Streams,Pragma No_Run_Time,Implementation Defined Pragmas
5569 @anchor{gnat_rm/implementation_defined_pragmas pragma-no-strict-aliasing}@anchor{ac}
5570 @section Pragma No_Strict_Aliasing
5576 pragma No_Strict_Aliasing [([Entity =>] type_LOCAL_NAME)];
5579 @code{type_LOCAL_NAME} must refer to an access type
5580 declaration in the current declarative part. The effect is to inhibit
5581 strict aliasing optimization for the given type. The form with no
5582 arguments is a configuration pragma which applies to all access types
5583 declared in units to which the pragma applies. For a detailed
5584 description of the strict aliasing optimization, and the situations
5585 in which it must be suppressed, see the section on Optimization and Strict Aliasing
5586 in the @cite{GNAT User's Guide}.
5588 This pragma currently has no effects on access to unconstrained array types.
5590 @node Pragma No_Tagged_Streams,Pragma Normalize_Scalars,Pragma No_Strict_Aliasing,Implementation Defined Pragmas
5591 @anchor{gnat_rm/implementation_defined_pragmas pragma-no-tagged-streams}@anchor{ad}@anchor{gnat_rm/implementation_defined_pragmas id26}@anchor{ae}
5592 @section Pragma No_Tagged_Streams
5598 pragma No_Tagged_Streams [([Entity =>] tagged_type_LOCAL_NAME)];
5601 Normally when a tagged type is introduced using a full type declaration,
5602 part of the processing includes generating stream access routines to be
5603 used by stream attributes referencing the type (or one of its subtypes
5604 or derived types). This can involve the generation of significant amounts
5605 of code which is wasted space if stream routines are not needed for the
5608 The @code{No_Tagged_Streams} pragma causes the generation of these stream
5609 routines to be skipped, and any attempt to use stream operations on
5610 types subject to this pragma will be statically rejected as illegal.
5612 There are two forms of the pragma. The form with no arguments must appear
5613 in a declarative sequence or in the declarations of a package spec. This
5614 pragma affects all subsequent root tagged types declared in the declaration
5615 sequence, and specifies that no stream routines be generated. The form with
5616 an argument (for which there is also a corresponding aspect) specifies a
5617 single root tagged type for which stream routines are not to be generated.
5619 Once the pragma has been given for a particular root tagged type, all subtypes
5620 and derived types of this type inherit the pragma automatically, so the effect
5621 applies to a complete hierarchy (this is necessary to deal with the class-wide
5622 dispatching versions of the stream routines).
5624 When pragmas @code{Discard_Names} and @code{No_Tagged_Streams} are simultaneously
5625 applied to a tagged type its Expanded_Name and External_Tag are initialized
5626 with empty strings. This is useful to avoid exposing entity names at binary
5627 level but has a negative impact on the debuggability of tagged types.
5629 @node Pragma Normalize_Scalars,Pragma Obsolescent,Pragma No_Tagged_Streams,Implementation Defined Pragmas
5630 @anchor{gnat_rm/implementation_defined_pragmas pragma-normalize-scalars}@anchor{af}
5631 @section Pragma Normalize_Scalars
5637 pragma Normalize_Scalars;
5640 This is a language defined pragma which is fully implemented in GNAT. The
5641 effect is to cause all scalar objects that are not otherwise initialized
5642 to be initialized. The initial values are implementation dependent and
5648 @item @emph{Standard.Character}
5650 Objects whose root type is Standard.Character are initialized to
5651 Character'Last unless the subtype range excludes NUL (in which case
5652 NUL is used). This choice will always generate an invalid value if
5655 @item @emph{Standard.Wide_Character}
5657 Objects whose root type is Standard.Wide_Character are initialized to
5658 Wide_Character'Last unless the subtype range excludes NUL (in which case
5659 NUL is used). This choice will always generate an invalid value if
5662 @item @emph{Standard.Wide_Wide_Character}
5664 Objects whose root type is Standard.Wide_Wide_Character are initialized to
5665 the invalid value 16#FFFF_FFFF# unless the subtype range excludes NUL (in
5666 which case NUL is used). This choice will always generate an invalid value if
5669 @item @emph{Integer types}
5671 Objects of an integer type are treated differently depending on whether
5672 negative values are present in the subtype. If no negative values are
5673 present, then all one bits is used as the initial value except in the
5674 special case where zero is excluded from the subtype, in which case
5675 all zero bits are used. This choice will always generate an invalid
5676 value if one exists.
5678 For subtypes with negative values present, the largest negative number
5679 is used, except in the unusual case where this largest negative number
5680 is in the subtype, and the largest positive number is not, in which case
5681 the largest positive value is used. This choice will always generate
5682 an invalid value if one exists.
5684 @item @emph{Floating-Point Types}
5686 Objects of all floating-point types are initialized to all 1-bits. For
5687 standard IEEE format, this corresponds to a NaN (not a number) which is
5688 indeed an invalid value.
5690 @item @emph{Fixed-Point Types}
5692 Objects of all fixed-point types are treated as described above for integers,
5693 with the rules applying to the underlying integer value used to represent
5694 the fixed-point value.
5696 @item @emph{Modular types}
5698 Objects of a modular type are initialized to all one bits, except in
5699 the special case where zero is excluded from the subtype, in which
5700 case all zero bits are used. This choice will always generate an
5701 invalid value if one exists.
5703 @item @emph{Enumeration types}
5705 Objects of an enumeration type are initialized to all one-bits, i.e., to
5706 the value @code{2 ** typ'Size - 1} unless the subtype excludes the literal
5707 whose Pos value is zero, in which case a code of zero is used. This choice
5708 will always generate an invalid value if one exists.
5711 @node Pragma Obsolescent,Pragma Optimize_Alignment,Pragma Normalize_Scalars,Implementation Defined Pragmas
5712 @anchor{gnat_rm/implementation_defined_pragmas pragma-obsolescent}@anchor{b0}@anchor{gnat_rm/implementation_defined_pragmas id27}@anchor{b1}
5713 @section Pragma Obsolescent
5721 pragma Obsolescent (
5722 [Message =>] static_string_EXPRESSION
5723 [,[Version =>] Ada_05]]);
5725 pragma Obsolescent (
5727 [,[Message =>] static_string_EXPRESSION
5728 [,[Version =>] Ada_05]] );
5731 This pragma can occur immediately following a declaration of an entity,
5732 including the case of a record component. If no Entity argument is present,
5733 then this declaration is the one to which the pragma applies. If an Entity
5734 parameter is present, it must either match the name of the entity in this
5735 declaration, or alternatively, the pragma can immediately follow an enumeration
5736 type declaration, where the Entity argument names one of the enumeration
5739 This pragma is used to indicate that the named entity
5740 is considered obsolescent and should not be used. Typically this is
5741 used when an API must be modified by eventually removing or modifying
5742 existing subprograms or other entities. The pragma can be used at an
5743 intermediate stage when the entity is still present, but will be
5746 The effect of this pragma is to output a warning message on a reference to
5747 an entity thus marked that the subprogram is obsolescent if the appropriate
5748 warning option in the compiler is activated. If the @code{Message} parameter is
5749 present, then a second warning message is given containing this text. In
5750 addition, a reference to the entity is considered to be a violation of pragma
5751 @code{Restrictions (No_Obsolescent_Features)}.
5753 This pragma can also be used as a program unit pragma for a package,
5754 in which case the entity name is the name of the package, and the
5755 pragma indicates that the entire package is considered
5756 obsolescent. In this case a client @code{with}ing such a package
5757 violates the restriction, and the @code{with} clause is
5758 flagged with warnings if the warning option is set.
5760 If the @code{Version} parameter is present (which must be exactly
5761 the identifier @code{Ada_05}, no other argument is allowed), then the
5762 indication of obsolescence applies only when compiling in Ada 2005
5763 mode. This is primarily intended for dealing with the situations
5764 in the predefined library where subprograms or packages
5765 have become defined as obsolescent in Ada 2005
5766 (e.g., in @code{Ada.Characters.Handling}), but may be used anywhere.
5768 The following examples show typical uses of this pragma:
5772 pragma Obsolescent (p, Message => "use pp instead of p");
5777 pragma Obsolescent ("use q2new instead");
5779 type R is new integer;
5782 Message => "use RR in Ada 2005",
5792 type E is (a, bc, 'd', quack);
5793 pragma Obsolescent (Entity => bc)
5794 pragma Obsolescent (Entity => 'd')
5797 (a, b : character) return character;
5798 pragma Obsolescent (Entity => "+");
5802 Note that, as for all pragmas, if you use a pragma argument identifier,
5803 then all subsequent parameters must also use a pragma argument identifier.
5804 So if you specify @code{Entity =>} for the @code{Entity} argument, and a @code{Message}
5805 argument is present, it must be preceded by @code{Message =>}.
5807 @node Pragma Optimize_Alignment,Pragma Ordered,Pragma Obsolescent,Implementation Defined Pragmas
5808 @anchor{gnat_rm/implementation_defined_pragmas pragma-optimize-alignment}@anchor{b2}
5809 @section Pragma Optimize_Alignment
5813 @geindex default settings
5818 pragma Optimize_Alignment (TIME | SPACE | OFF);
5821 This is a configuration pragma which affects the choice of default alignments
5822 for types and objects where no alignment is explicitly specified. There is a
5823 time/space trade-off in the selection of these values. Large alignments result
5824 in more efficient code, at the expense of larger data space, since sizes have
5825 to be increased to match these alignments. Smaller alignments save space, but
5826 the access code is slower. The normal choice of default alignments for types
5827 and individual alignment promotions for objects (which is what you get if you
5828 do not use this pragma, or if you use an argument of OFF), tries to balance
5829 these two requirements.
5831 Specifying SPACE causes smaller default alignments to be chosen in two cases.
5832 First any packed record is given an alignment of 1. Second, if a size is given
5833 for the type, then the alignment is chosen to avoid increasing this size. For
5845 In the default mode, this type gets an alignment of 4, so that access to the
5846 Integer field X are efficient. But this means that objects of the type end up
5847 with a size of 8 bytes. This is a valid choice, since sizes of objects are
5848 allowed to be bigger than the size of the type, but it can waste space if for
5849 example fields of type R appear in an enclosing record. If the above type is
5850 compiled in @code{Optimize_Alignment (Space)} mode, the alignment is set to 1.
5852 However, there is one case in which SPACE is ignored. If a variable length
5853 record (that is a discriminated record with a component which is an array
5854 whose length depends on a discriminant), has a pragma Pack, then it is not
5855 in general possible to set the alignment of such a record to one, so the
5856 pragma is ignored in this case (with a warning).
5858 Specifying SPACE also disables alignment promotions for standalone objects,
5859 which occur when the compiler increases the alignment of a specific object
5860 without changing the alignment of its type.
5862 Specifying SPACE also disables component reordering in unpacked record types,
5863 which can result in larger sizes in order to meet alignment requirements.
5865 Specifying TIME causes larger default alignments to be chosen in the case of
5866 small types with sizes that are not a power of 2. For example, consider:
5879 The default alignment for this record is normally 1, but if this type is
5880 compiled in @code{Optimize_Alignment (Time)} mode, then the alignment is set
5881 to 4, which wastes space for objects of the type, since they are now 4 bytes
5882 long, but results in more efficient access when the whole record is referenced.
5884 As noted above, this is a configuration pragma, and there is a requirement
5885 that all units in a partition be compiled with a consistent setting of the
5886 optimization setting. This would normally be achieved by use of a configuration
5887 pragma file containing the appropriate setting. The exception to this rule is
5888 that units with an explicit configuration pragma in the same file as the source
5889 unit are excluded from the consistency check, as are all predefined units. The
5890 latter are compiled by default in pragma Optimize_Alignment (Off) mode if no
5891 pragma appears at the start of the file.
5893 @node Pragma Ordered,Pragma Overflow_Mode,Pragma Optimize_Alignment,Implementation Defined Pragmas
5894 @anchor{gnat_rm/implementation_defined_pragmas pragma-ordered}@anchor{b3}
5895 @section Pragma Ordered
5901 pragma Ordered (enumeration_first_subtype_LOCAL_NAME);
5904 Most enumeration types are from a conceptual point of view unordered.
5905 For example, consider:
5908 type Color is (Red, Blue, Green, Yellow);
5911 By Ada semantics @code{Blue > Red} and @code{Green > Blue},
5912 but really these relations make no sense; the enumeration type merely
5913 specifies a set of possible colors, and the order is unimportant.
5915 For unordered enumeration types, it is generally a good idea if
5916 clients avoid comparisons (other than equality or inequality) and
5917 explicit ranges. (A @emph{client} is a unit where the type is referenced,
5918 other than the unit where the type is declared, its body, and its subunits.)
5919 For example, if code buried in some client says:
5922 if Current_Color < Yellow then ...
5923 if Current_Color in Blue .. Green then ...
5926 then the client code is relying on the order, which is undesirable.
5927 It makes the code hard to read and creates maintenance difficulties if
5928 entries have to be added to the enumeration type. Instead,
5929 the code in the client should list the possibilities, or an
5930 appropriate subtype should be declared in the unit that declares
5931 the original enumeration type. E.g., the following subtype could
5932 be declared along with the type @code{Color}:
5935 subtype RBG is Color range Red .. Green;
5938 and then the client could write:
5941 if Current_Color in RBG then ...
5942 if Current_Color = Blue or Current_Color = Green then ...
5945 However, some enumeration types are legitimately ordered from a conceptual
5946 point of view. For example, if you declare:
5949 type Day is (Mon, Tue, Wed, Thu, Fri, Sat, Sun);
5952 then the ordering imposed by the language is reasonable, and
5953 clients can depend on it, writing for example:
5956 if D in Mon .. Fri then ...
5960 The pragma @emph{Ordered} is provided to mark enumeration types that
5961 are conceptually ordered, alerting the reader that clients may depend
5962 on the ordering. GNAT provides a pragma to mark enumerations as ordered
5963 rather than one to mark them as unordered, since in our experience,
5964 the great majority of enumeration types are conceptually unordered.
5966 The types @code{Boolean}, @code{Character}, @code{Wide_Character},
5967 and @code{Wide_Wide_Character}
5968 are considered to be ordered types, so each is declared with a
5969 pragma @code{Ordered} in package @code{Standard}.
5971 Normally pragma @code{Ordered} serves only as documentation and a guide for
5972 coding standards, but GNAT provides a warning switch @emph{-gnatw.u} that
5973 requests warnings for inappropriate uses (comparisons and explicit
5974 subranges) for unordered types. If this switch is used, then any
5975 enumeration type not marked with pragma @code{Ordered} will be considered
5976 as unordered, and will generate warnings for inappropriate uses.
5978 Note that generic types are not considered ordered or unordered (since the
5979 template can be instantiated for both cases), so we never generate warnings
5980 for the case of generic enumerated types.
5982 For additional information please refer to the description of the
5983 @emph{-gnatw.u} switch in the GNAT User's Guide.
5985 @node Pragma Overflow_Mode,Pragma Overriding_Renamings,Pragma Ordered,Implementation Defined Pragmas
5986 @anchor{gnat_rm/implementation_defined_pragmas pragma-overflow-mode}@anchor{b4}
5987 @section Pragma Overflow_Mode
5993 pragma Overflow_Mode
5995 [,[Assertions =>] MODE]);
5997 MODE ::= STRICT | MINIMIZED | ELIMINATED
6000 This pragma sets the current overflow mode to the given setting. For details
6001 of the meaning of these modes, please refer to the
6002 'Overflow Check Handling in GNAT' appendix in the
6003 GNAT User's Guide. If only the @code{General} parameter is present,
6004 the given mode applies to all expressions. If both parameters are present,
6005 the @code{General} mode applies to expressions outside assertions, and
6006 the @code{Eliminated} mode applies to expressions within assertions.
6008 The case of the @code{MODE} parameter is ignored,
6009 so @code{MINIMIZED}, @code{Minimized} and
6010 @code{minimized} all have the same effect.
6012 The @code{Overflow_Mode} pragma has the same scoping and placement
6013 rules as pragma @code{Suppress}, so it can occur either as a
6014 configuration pragma, specifying a default for the whole
6015 program, or in a declarative scope, where it applies to the
6016 remaining declarations and statements in that scope.
6018 The pragma @code{Suppress (Overflow_Check)} suppresses
6019 overflow checking, but does not affect the overflow mode.
6021 The pragma @code{Unsuppress (Overflow_Check)} unsuppresses (enables)
6022 overflow checking, but does not affect the overflow mode.
6024 @node Pragma Overriding_Renamings,Pragma Partition_Elaboration_Policy,Pragma Overflow_Mode,Implementation Defined Pragmas
6025 @anchor{gnat_rm/implementation_defined_pragmas pragma-overriding-renamings}@anchor{b5}
6026 @section Pragma Overriding_Renamings
6029 @geindex Rational profile
6031 @geindex Rational compatibility
6036 pragma Overriding_Renamings;
6039 This is a GNAT configuration pragma to simplify porting
6040 legacy code accepted by the Rational
6041 Ada compiler. In the presence of this pragma, a renaming declaration that
6042 renames an inherited operation declared in the same scope is legal if selected
6043 notation is used as in:
6046 pragma Overriding_Renamings;
6051 function F (..) renames R.F;
6056 RM 8.3 (15) stipulates that an overridden operation is not visible within the
6057 declaration of the overriding operation.
6059 @node Pragma Partition_Elaboration_Policy,Pragma Part_Of,Pragma Overriding_Renamings,Implementation Defined Pragmas
6060 @anchor{gnat_rm/implementation_defined_pragmas pragma-partition-elaboration-policy}@anchor{b6}
6061 @section Pragma Partition_Elaboration_Policy
6067 pragma Partition_Elaboration_Policy (POLICY_IDENTIFIER);
6069 POLICY_IDENTIFIER ::= Concurrent | Sequential
6072 This pragma is standard in Ada 2005, but is available in all earlier
6073 versions of Ada as an implementation-defined pragma.
6074 See Ada 2012 Reference Manual for details.
6076 @node Pragma Part_Of,Pragma Passive,Pragma Partition_Elaboration_Policy,Implementation Defined Pragmas
6077 @anchor{gnat_rm/implementation_defined_pragmas id28}@anchor{b7}@anchor{gnat_rm/implementation_defined_pragmas pragma-part-of}@anchor{b8}
6078 @section Pragma Part_Of
6084 pragma Part_Of (ABSTRACT_STATE);
6086 ABSTRACT_STATE ::= NAME
6089 For the semantics of this pragma, see the entry for aspect @code{Part_Of} in the
6090 SPARK 2014 Reference Manual, section 7.2.6.
6092 @node Pragma Passive,Pragma Persistent_BSS,Pragma Part_Of,Implementation Defined Pragmas
6093 @anchor{gnat_rm/implementation_defined_pragmas pragma-passive}@anchor{b9}
6094 @section Pragma Passive
6100 pragma Passive [(Semaphore | No)];
6103 Syntax checked, but otherwise ignored by GNAT. This is recognized for
6104 compatibility with DEC Ada 83 implementations, where it is used within a
6105 task definition to request that a task be made passive. If the argument
6106 @code{Semaphore} is present, or the argument is omitted, then DEC Ada 83
6107 treats the pragma as an assertion that the containing task is passive
6108 and that optimization of context switch with this task is permitted and
6109 desired. If the argument @code{No} is present, the task must not be
6110 optimized. GNAT does not attempt to optimize any tasks in this manner
6111 (since protected objects are available in place of passive tasks).
6113 For more information on the subject of passive tasks, see the section
6114 'Passive Task Optimization' in the GNAT Users Guide.
6116 @node Pragma Persistent_BSS,Pragma Polling,Pragma Passive,Implementation Defined Pragmas
6117 @anchor{gnat_rm/implementation_defined_pragmas id29}@anchor{ba}@anchor{gnat_rm/implementation_defined_pragmas pragma-persistent-bss}@anchor{bb}
6118 @section Pragma Persistent_BSS
6124 pragma Persistent_BSS [(LOCAL_NAME)]
6127 This pragma allows selected objects to be placed in the @code{.persistent_bss}
6128 section. On some targets the linker and loader provide for special
6129 treatment of this section, allowing a program to be reloaded without
6130 affecting the contents of this data (hence the name persistent).
6132 There are two forms of usage. If an argument is given, it must be the
6133 local name of a library-level object, with no explicit initialization
6134 and whose type is potentially persistent. If no argument is given, then
6135 the pragma is a configuration pragma, and applies to all library-level
6136 objects with no explicit initialization of potentially persistent types.
6138 A potentially persistent type is a scalar type, or an untagged,
6139 non-discriminated record, all of whose components have no explicit
6140 initialization and are themselves of a potentially persistent type,
6141 or an array, all of whose constraints are static, and whose component
6142 type is potentially persistent.
6144 If this pragma is used on a target where this feature is not supported,
6145 then the pragma will be ignored. See also @code{pragma Linker_Section}.
6147 @node Pragma Polling,Pragma Post,Pragma Persistent_BSS,Implementation Defined Pragmas
6148 @anchor{gnat_rm/implementation_defined_pragmas pragma-polling}@anchor{bc}
6149 @section Pragma Polling
6155 pragma Polling (ON | OFF);
6158 This pragma controls the generation of polling code. This is normally off.
6159 If @code{pragma Polling (ON)} is used then periodic calls are generated to
6160 the routine @code{Ada.Exceptions.Poll}. This routine is a separate unit in the
6161 runtime library, and can be found in file @code{a-excpol.adb}.
6163 Pragma @code{Polling} can appear as a configuration pragma (for example it
6164 can be placed in the @code{gnat.adc} file) to enable polling globally, or it
6165 can be used in the statement or declaration sequence to control polling
6168 A call to the polling routine is generated at the start of every loop and
6169 at the start of every subprogram call. This guarantees that the @code{Poll}
6170 routine is called frequently, and places an upper bound (determined by
6171 the complexity of the code) on the period between two @code{Poll} calls.
6173 The primary purpose of the polling interface is to enable asynchronous
6174 aborts on targets that cannot otherwise support it (for example Windows
6175 NT), but it may be used for any other purpose requiring periodic polling.
6176 The standard version is null, and can be replaced by a user program. This
6177 will require re-compilation of the @code{Ada.Exceptions} package that can
6178 be found in files @code{a-except.ads} and @code{a-except.adb}.
6180 A standard alternative unit (in file @code{4wexcpol.adb} in the standard GNAT
6181 distribution) is used to enable the asynchronous abort capability on
6182 targets that do not normally support the capability. The version of
6183 @code{Poll} in this file makes a call to the appropriate runtime routine
6184 to test for an abort condition.
6186 Note that polling can also be enabled by use of the @emph{-gnatP} switch.
6187 See the section on switches for gcc in the @cite{GNAT User's Guide}.
6189 @node Pragma Post,Pragma Postcondition,Pragma Polling,Implementation Defined Pragmas
6190 @anchor{gnat_rm/implementation_defined_pragmas pragma-post}@anchor{bd}
6191 @section Pragma Post
6197 @geindex postconditions
6202 pragma Post (Boolean_Expression);
6205 The @code{Post} pragma is intended to be an exact replacement for
6206 the language-defined
6207 @code{Post} aspect, and shares its restrictions and semantics.
6208 It must appear either immediately following the corresponding
6209 subprogram declaration (only other pragmas may intervene), or
6210 if there is no separate subprogram declaration, then it can
6211 appear at the start of the declarations in a subprogram body
6212 (preceded only by other pragmas).
6214 @node Pragma Postcondition,Pragma Post_Class,Pragma Post,Implementation Defined Pragmas
6215 @anchor{gnat_rm/implementation_defined_pragmas pragma-postcondition}@anchor{be}
6216 @section Pragma Postcondition
6219 @geindex Postcondition
6222 @geindex postconditions
6227 pragma Postcondition (
6228 [Check =>] Boolean_Expression
6229 [,[Message =>] String_Expression]);
6232 The @code{Postcondition} pragma allows specification of automatic
6233 postcondition checks for subprograms. These checks are similar to
6234 assertions, but are automatically inserted just prior to the return
6235 statements of the subprogram with which they are associated (including
6236 implicit returns at the end of procedure bodies and associated
6237 exception handlers).
6239 In addition, the boolean expression which is the condition which
6240 must be true may contain references to function'Result in the case
6241 of a function to refer to the returned value.
6243 @code{Postcondition} pragmas may appear either immediately following the
6244 (separate) declaration of a subprogram, or at the start of the
6245 declarations of a subprogram body. Only other pragmas may intervene
6246 (that is appear between the subprogram declaration and its
6247 postconditions, or appear before the postcondition in the
6248 declaration sequence in a subprogram body). In the case of a
6249 postcondition appearing after a subprogram declaration, the
6250 formal arguments of the subprogram are visible, and can be
6251 referenced in the postcondition expressions.
6253 The postconditions are collected and automatically tested just
6254 before any return (implicit or explicit) in the subprogram body.
6255 A postcondition is only recognized if postconditions are active
6256 at the time the pragma is encountered. The compiler switch @emph{gnata}
6257 turns on all postconditions by default, and pragma @code{Check_Policy}
6258 with an identifier of @code{Postcondition} can also be used to
6259 control whether postconditions are active.
6261 The general approach is that postconditions are placed in the spec
6262 if they represent functional aspects which make sense to the client.
6263 For example we might have:
6266 function Direction return Integer;
6267 pragma Postcondition
6268 (Direction'Result = +1
6270 Direction'Result = -1);
6273 which serves to document that the result must be +1 or -1, and
6274 will test that this is the case at run time if postcondition
6277 Postconditions within the subprogram body can be used to
6278 check that some internal aspect of the implementation,
6279 not visible to the client, is operating as expected.
6280 For instance if a square root routine keeps an internal
6281 counter of the number of times it is called, then we
6282 might have the following postcondition:
6285 Sqrt_Calls : Natural := 0;
6287 function Sqrt (Arg : Float) return Float is
6288 pragma Postcondition
6289 (Sqrt_Calls = Sqrt_Calls'Old + 1);
6294 As this example, shows, the use of the @code{Old} attribute
6295 is often useful in postconditions to refer to the state on
6296 entry to the subprogram.
6298 Note that postconditions are only checked on normal returns
6299 from the subprogram. If an abnormal return results from
6300 raising an exception, then the postconditions are not checked.
6302 If a postcondition fails, then the exception
6303 @code{System.Assertions.Assert_Failure} is raised. If
6304 a message argument was supplied, then the given string
6305 will be used as the exception message. If no message
6306 argument was supplied, then the default message has
6307 the form "Postcondition failed at file_name:line". The
6308 exception is raised in the context of the subprogram
6309 body, so it is possible to catch postcondition failures
6310 within the subprogram body itself.
6312 Within a package spec, normal visibility rules
6313 in Ada would prevent forward references within a
6314 postcondition pragma to functions defined later in
6315 the same package. This would introduce undesirable
6316 ordering constraints. To avoid this problem, all
6317 postcondition pragmas are analyzed at the end of
6318 the package spec, allowing forward references.
6320 The following example shows that this even allows
6321 mutually recursive postconditions as in:
6324 package Parity_Functions is
6325 function Odd (X : Natural) return Boolean;
6326 pragma Postcondition
6330 (x /= 0 and then Even (X - 1))));
6332 function Even (X : Natural) return Boolean;
6333 pragma Postcondition
6337 (x /= 1 and then Odd (X - 1))));
6339 end Parity_Functions;
6342 There are no restrictions on the complexity or form of
6343 conditions used within @code{Postcondition} pragmas.
6344 The following example shows that it is even possible
6345 to verify performance behavior.
6350 Performance : constant Float;
6351 -- Performance constant set by implementation
6352 -- to match target architecture behavior.
6354 procedure Treesort (Arg : String);
6355 -- Sorts characters of argument using N*logN sort
6356 pragma Postcondition
6357 (Float (Clock - Clock'Old) <=
6358 Float (Arg'Length) *
6359 log (Float (Arg'Length)) *
6364 Note: postcondition pragmas associated with subprograms that are
6365 marked as Inline_Always, or those marked as Inline with front-end
6366 inlining (-gnatN option set) are accepted and legality-checked
6367 by the compiler, but are ignored at run-time even if postcondition
6368 checking is enabled.
6370 Note that pragma @code{Postcondition} differs from the language-defined
6371 @code{Post} aspect (and corresponding @code{Post} pragma) in allowing
6372 multiple occurrences, allowing occurences in the body even if there
6373 is a separate spec, and allowing a second string parameter, and the
6374 use of the pragma identifier @code{Check}. Historically, pragma
6375 @code{Postcondition} was implemented prior to the development of
6376 Ada 2012, and has been retained in its original form for
6377 compatibility purposes.
6379 @node Pragma Post_Class,Pragma Rename_Pragma,Pragma Postcondition,Implementation Defined Pragmas
6380 @anchor{gnat_rm/implementation_defined_pragmas pragma-post-class}@anchor{bf}
6381 @section Pragma Post_Class
6387 @geindex postconditions
6392 pragma Post_Class (Boolean_Expression);
6395 The @code{Post_Class} pragma is intended to be an exact replacement for
6396 the language-defined
6397 @code{Post'Class} aspect, and shares its restrictions and semantics.
6398 It must appear either immediately following the corresponding
6399 subprogram declaration (only other pragmas may intervene), or
6400 if there is no separate subprogram declaration, then it can
6401 appear at the start of the declarations in a subprogram body
6402 (preceded only by other pragmas).
6404 Note: This pragma is called @code{Post_Class} rather than
6405 @code{Post'Class} because the latter would not be strictly
6406 conforming to the allowed syntax for pragmas. The motivation
6407 for provinding pragmas equivalent to the aspects is to allow a program
6408 to be written using the pragmas, and then compiled if necessary
6409 using an Ada compiler that does not recognize the pragmas or
6410 aspects, but is prepared to ignore the pragmas. The assertion
6411 policy that controls this pragma is @code{Post'Class}, not
6414 @node Pragma Rename_Pragma,Pragma Pre,Pragma Post_Class,Implementation Defined Pragmas
6415 @anchor{gnat_rm/implementation_defined_pragmas pragma-rename-pragma}@anchor{c0}
6416 @section Pragma Rename_Pragma
6425 pragma Rename_Pragma (
6426 [New_Name =>] IDENTIFIER,
6427 [Renamed =>] pragma_IDENTIFIER);
6430 This pragma provides a mechanism for supplying new names for existing
6431 pragmas. The @code{New_Name} identifier can subsequently be used as a synonym for
6432 the Renamed pragma. For example, suppose you have code that was originally
6433 developed on a compiler that supports Inline_Only as an implementation defined
6434 pragma. And suppose the semantics of pragma Inline_Only are identical to (or at
6435 least very similar to) the GNAT implementation defined pragma
6436 Inline_Always. You could globally replace Inline_Only with Inline_Always.
6438 However, to avoid that source modification, you could instead add a
6439 configuration pragma:
6442 pragma Rename_Pragma (
6443 New_Name => Inline_Only,
6444 Renamed => Inline_Always);
6447 Then GNAT will treat "pragma Inline_Only ..." as if you had written
6448 "pragma Inline_Always ...".
6450 Pragma Inline_Only will not necessarily mean the same thing as the other Ada
6451 compiler; it's up to you to make sure the semantics are close enough.
6453 @node Pragma Pre,Pragma Precondition,Pragma Rename_Pragma,Implementation Defined Pragmas
6454 @anchor{gnat_rm/implementation_defined_pragmas pragma-pre}@anchor{c1}
6461 @geindex preconditions
6466 pragma Pre (Boolean_Expression);
6469 The @code{Pre} pragma is intended to be an exact replacement for
6470 the language-defined
6471 @code{Pre} aspect, and shares its restrictions and semantics.
6472 It must appear either immediately following the corresponding
6473 subprogram declaration (only other pragmas may intervene), or
6474 if there is no separate subprogram declaration, then it can
6475 appear at the start of the declarations in a subprogram body
6476 (preceded only by other pragmas).
6478 @node Pragma Precondition,Pragma Predicate,Pragma Pre,Implementation Defined Pragmas
6479 @anchor{gnat_rm/implementation_defined_pragmas pragma-precondition}@anchor{c2}
6480 @section Pragma Precondition
6483 @geindex Preconditions
6486 @geindex preconditions
6491 pragma Precondition (
6492 [Check =>] Boolean_Expression
6493 [,[Message =>] String_Expression]);
6496 The @code{Precondition} pragma is similar to @code{Postcondition}
6497 except that the corresponding checks take place immediately upon
6498 entry to the subprogram, and if a precondition fails, the exception
6499 is raised in the context of the caller, and the attribute 'Result
6500 cannot be used within the precondition expression.
6502 Otherwise, the placement and visibility rules are identical to those
6503 described for postconditions. The following is an example of use
6504 within a package spec:
6507 package Math_Functions is
6509 function Sqrt (Arg : Float) return Float;
6510 pragma Precondition (Arg >= 0.0)
6515 @code{Precondition} pragmas may appear either immediately following the
6516 (separate) declaration of a subprogram, or at the start of the
6517 declarations of a subprogram body. Only other pragmas may intervene
6518 (that is appear between the subprogram declaration and its
6519 postconditions, or appear before the postcondition in the
6520 declaration sequence in a subprogram body).
6522 Note: precondition pragmas associated with subprograms that are
6523 marked as Inline_Always, or those marked as Inline with front-end
6524 inlining (-gnatN option set) are accepted and legality-checked
6525 by the compiler, but are ignored at run-time even if precondition
6526 checking is enabled.
6528 Note that pragma @code{Precondition} differs from the language-defined
6529 @code{Pre} aspect (and corresponding @code{Pre} pragma) in allowing
6530 multiple occurrences, allowing occurences in the body even if there
6531 is a separate spec, and allowing a second string parameter, and the
6532 use of the pragma identifier @code{Check}. Historically, pragma
6533 @code{Precondition} was implemented prior to the development of
6534 Ada 2012, and has been retained in its original form for
6535 compatibility purposes.
6537 @node Pragma Predicate,Pragma Predicate_Failure,Pragma Precondition,Implementation Defined Pragmas
6538 @anchor{gnat_rm/implementation_defined_pragmas pragma-predicate}@anchor{c3}@anchor{gnat_rm/implementation_defined_pragmas id30}@anchor{c4}
6539 @section Pragma Predicate
6546 ([Entity =>] type_LOCAL_NAME,
6547 [Check =>] EXPRESSION);
6550 This pragma (available in all versions of Ada in GNAT) encompasses both
6551 the @code{Static_Predicate} and @code{Dynamic_Predicate} aspects in
6552 Ada 2012. A predicate is regarded as static if it has an allowed form
6553 for @code{Static_Predicate} and is otherwise treated as a
6554 @code{Dynamic_Predicate}. Otherwise, predicates specified by this
6555 pragma behave exactly as described in the Ada 2012 reference manual.
6556 For example, if we have
6559 type R is range 1 .. 10;
6561 pragma Predicate (Entity => S, Check => S not in 4 .. 6);
6563 pragma Predicate (Entity => Q, Check => F(Q) or G(Q));
6566 the effect is identical to the following Ada 2012 code:
6569 type R is range 1 .. 10;
6571 Static_Predicate => S not in 4 .. 6;
6573 Dynamic_Predicate => F(Q) or G(Q);
6576 Note that there are no pragmas @code{Dynamic_Predicate}
6577 or @code{Static_Predicate}. That is
6578 because these pragmas would affect legality and semantics of
6579 the program and thus do not have a neutral effect if ignored.
6580 The motivation behind providing pragmas equivalent to
6581 corresponding aspects is to allow a program to be written
6582 using the pragmas, and then compiled with a compiler that
6583 will ignore the pragmas. That doesn't work in the case of
6584 static and dynamic predicates, since if the corresponding
6585 pragmas are ignored, then the behavior of the program is
6586 fundamentally changed (for example a membership test
6587 @code{A in B} would not take into account a predicate
6588 defined for subtype B). When following this approach, the
6589 use of predicates should be avoided.
6591 @node Pragma Predicate_Failure,Pragma Preelaborable_Initialization,Pragma Predicate,Implementation Defined Pragmas
6592 @anchor{gnat_rm/implementation_defined_pragmas pragma-predicate-failure}@anchor{c5}
6593 @section Pragma Predicate_Failure
6599 pragma Predicate_Failure
6600 ([Entity =>] type_LOCAL_NAME,
6601 [Message =>] String_Expression);
6604 The @code{Predicate_Failure} pragma is intended to be an exact replacement for
6605 the language-defined
6606 @code{Predicate_Failure} aspect, and shares its restrictions and semantics.
6608 @node Pragma Preelaborable_Initialization,Pragma Prefix_Exception_Messages,Pragma Predicate_Failure,Implementation Defined Pragmas
6609 @anchor{gnat_rm/implementation_defined_pragmas pragma-preelaborable-initialization}@anchor{c6}
6610 @section Pragma Preelaborable_Initialization
6616 pragma Preelaborable_Initialization (DIRECT_NAME);
6619 This pragma is standard in Ada 2005, but is available in all earlier
6620 versions of Ada as an implementation-defined pragma.
6621 See Ada 2012 Reference Manual for details.
6623 @node Pragma Prefix_Exception_Messages,Pragma Pre_Class,Pragma Preelaborable_Initialization,Implementation Defined Pragmas
6624 @anchor{gnat_rm/implementation_defined_pragmas pragma-prefix-exception-messages}@anchor{c7}
6625 @section Pragma Prefix_Exception_Messages
6628 @geindex Prefix_Exception_Messages
6632 @geindex Exception_Message
6637 pragma Prefix_Exception_Messages;
6640 This is an implementation-defined configuration pragma that affects the
6641 behavior of raise statements with a message given as a static string
6642 constant (typically a string literal). In such cases, the string will
6643 be automatically prefixed by the name of the enclosing entity (giving
6644 the package and subprogram containing the raise statement). This helps
6645 to identify where messages are coming from, and this mode is automatic
6646 for the run-time library.
6648 The pragma has no effect if the message is computed with an expression other
6649 than a static string constant, since the assumption in this case is that
6650 the program computes exactly the string it wants. If you still want the
6651 prefixing in this case, you can always call
6652 @code{GNAT.Source_Info.Enclosing_Entity} and prepend the string manually.
6654 @node Pragma Pre_Class,Pragma Priority_Specific_Dispatching,Pragma Prefix_Exception_Messages,Implementation Defined Pragmas
6655 @anchor{gnat_rm/implementation_defined_pragmas pragma-pre-class}@anchor{c8}
6656 @section Pragma Pre_Class
6662 @geindex preconditions
6667 pragma Pre_Class (Boolean_Expression);
6670 The @code{Pre_Class} pragma is intended to be an exact replacement for
6671 the language-defined
6672 @code{Pre'Class} aspect, and shares its restrictions and semantics.
6673 It must appear either immediately following the corresponding
6674 subprogram declaration (only other pragmas may intervene), or
6675 if there is no separate subprogram declaration, then it can
6676 appear at the start of the declarations in a subprogram body
6677 (preceded only by other pragmas).
6679 Note: This pragma is called @code{Pre_Class} rather than
6680 @code{Pre'Class} because the latter would not be strictly
6681 conforming to the allowed syntax for pragmas. The motivation
6682 for providing pragmas equivalent to the aspects is to allow a program
6683 to be written using the pragmas, and then compiled if necessary
6684 using an Ada compiler that does not recognize the pragmas or
6685 aspects, but is prepared to ignore the pragmas. The assertion
6686 policy that controls this pragma is @code{Pre'Class}, not
6689 @node Pragma Priority_Specific_Dispatching,Pragma Profile,Pragma Pre_Class,Implementation Defined Pragmas
6690 @anchor{gnat_rm/implementation_defined_pragmas pragma-priority-specific-dispatching}@anchor{c9}
6691 @section Pragma Priority_Specific_Dispatching
6697 pragma Priority_Specific_Dispatching (
6699 first_priority_EXPRESSION,
6700 last_priority_EXPRESSION)
6702 POLICY_IDENTIFIER ::=
6703 EDF_Across_Priorities |
6704 FIFO_Within_Priorities |
6705 Non_Preemptive_Within_Priorities |
6706 Round_Robin_Within_Priorities
6709 This pragma is standard in Ada 2005, but is available in all earlier
6710 versions of Ada as an implementation-defined pragma.
6711 See Ada 2012 Reference Manual for details.
6713 @node Pragma Profile,Pragma Profile_Warnings,Pragma Priority_Specific_Dispatching,Implementation Defined Pragmas
6714 @anchor{gnat_rm/implementation_defined_pragmas pragma-profile}@anchor{ca}
6715 @section Pragma Profile
6721 pragma Profile (Ravenscar | Restricted | Rational |
6722 GNAT_Extended_Ravenscar | GNAT_Ravenscar_EDF );
6725 This pragma is standard in Ada 2005, but is available in all earlier
6726 versions of Ada as an implementation-defined pragma. This is a
6727 configuration pragma that establishes a set of configuration pragmas
6728 that depend on the argument. @code{Ravenscar} is standard in Ada 2005.
6729 The other possibilities (@code{Restricted}, @code{Rational},
6730 @code{GNAT_Extended_Ravenscar}, @code{GNAT_Ravenscar_EDF})
6731 are implementation-defined. The set of configuration pragmas
6732 is defined in the following sections.
6738 Pragma Profile (Ravenscar)
6740 The @code{Ravenscar} profile is standard in Ada 2005,
6741 but is available in all earlier
6742 versions of Ada as an implementation-defined pragma. This profile
6743 establishes the following set of configuration pragmas:
6749 @code{Task_Dispatching_Policy (FIFO_Within_Priorities)}
6751 [RM D.2.2] Tasks are dispatched following a preemptive
6752 priority-ordered scheduling policy.
6755 @code{Locking_Policy (Ceiling_Locking)}
6757 [RM D.3] While tasks and interrupts execute a protected action, they inherit
6758 the ceiling priority of the corresponding protected object.
6761 @code{Detect_Blocking}
6763 This pragma forces the detection of potentially blocking operations within a
6764 protected operation, and to raise Program_Error if that happens.
6767 plus the following set of restrictions:
6773 @code{Max_Entry_Queue_Length => 1}
6775 No task can be queued on a protected entry.
6778 @code{Max_Protected_Entries => 1}
6781 @code{Max_Task_Entries => 0}
6783 No rendezvous statements are allowed.
6786 @code{No_Abort_Statements}
6789 @code{No_Dynamic_Attachment}
6792 @code{No_Dynamic_Priorities}
6795 @code{No_Implicit_Heap_Allocations}
6798 @code{No_Local_Protected_Objects}
6801 @code{No_Local_Timing_Events}
6804 @code{No_Protected_Type_Allocators}
6807 @code{No_Relative_Delay}
6810 @code{No_Requeue_Statements}
6813 @code{No_Select_Statements}
6816 @code{No_Specific_Termination_Handlers}
6819 @code{No_Task_Allocators}
6822 @code{No_Task_Hierarchy}
6825 @code{No_Task_Termination}
6828 @code{Simple_Barriers}
6831 The Ravenscar profile also includes the following restrictions that specify
6832 that there are no semantic dependences on the corresponding predefined
6839 @code{No_Dependence => Ada.Asynchronous_Task_Control}
6842 @code{No_Dependence => Ada.Calendar}
6845 @code{No_Dependence => Ada.Execution_Time.Group_Budget}
6848 @code{No_Dependence => Ada.Execution_Time.Timers}
6851 @code{No_Dependence => Ada.Task_Attributes}
6854 @code{No_Dependence => System.Multiprocessors.Dispatching_Domains}
6857 This set of configuration pragmas and restrictions correspond to the
6858 definition of the 'Ravenscar Profile' for limited tasking, devised and
6859 published by the @cite{International Real-Time Ada Workshop@comma{} 1997}.
6860 A description is also available at
6861 @indicateurl{http://www-users.cs.york.ac.uk/~burns/ravenscar.ps}.
6863 The original definition of the profile was revised at subsequent IRTAW
6864 meetings. It has been included in the ISO
6865 @cite{Guide for the Use of the Ada Programming Language in High Integrity Systems},
6866 and was made part of the Ada 2005 standard.
6867 The formal definition given by
6868 the Ada Rapporteur Group (ARG) can be found in two Ada Issues (AI-249 and
6869 AI-305) available at
6870 @indicateurl{http://www.ada-auth.org/cgi-bin/cvsweb.cgi/ais/ai-00249.txt} and
6871 @indicateurl{http://www.ada-auth.org/cgi-bin/cvsweb.cgi/ais/ai-00305.txt}.
6873 The above set is a superset of the restrictions provided by pragma
6874 @code{Profile (Restricted)}, it includes six additional restrictions
6875 (@code{Simple_Barriers}, @code{No_Select_Statements},
6876 @code{No_Calendar}, @code{No_Implicit_Heap_Allocations},
6877 @code{No_Relative_Delay} and @code{No_Task_Termination}). This means
6878 that pragma @code{Profile (Ravenscar)}, like the pragma
6879 @code{Profile (Restricted)},
6880 automatically causes the use of a simplified,
6881 more efficient version of the tasking run-time library.
6884 Pragma Profile (GNAT_Extended_Ravenscar)
6886 This profile corresponds to a GNAT specific extension of the
6887 Ravenscar profile. The profile may change in the future although
6888 only in a compatible way: some restrictions may be removed or
6889 relaxed. It is defined as a variation of the Ravenscar profile.
6891 The @code{No_Implicit_Heap_Allocations} restriction has been replaced
6892 by @code{No_Implicit_Task_Allocations} and
6893 @code{No_Implicit_Protected_Object_Allocations}.
6895 The @code{Simple_Barriers} restriction has been replaced by
6896 @code{Pure_Barriers}.
6898 The @code{Max_Protected_Entries}, @code{Max_Entry_Queue_Length}, and
6899 @code{No_Relative_Delay} restrictions have been removed.
6902 Pragma Profile (GNAT_Ravenscar_EDF)
6904 This profile corresponds to the Ravenscar profile but using
6905 EDF_Across_Priority as the Task_Scheduling_Policy.
6908 Pragma Profile (Restricted)
6910 This profile corresponds to the GNAT restricted run time. It
6911 establishes the following set of restrictions:
6917 @code{No_Abort_Statements}
6920 @code{No_Entry_Queue}
6923 @code{No_Task_Hierarchy}
6926 @code{No_Task_Allocators}
6929 @code{No_Dynamic_Priorities}
6932 @code{No_Terminate_Alternatives}
6935 @code{No_Dynamic_Attachment}
6938 @code{No_Protected_Type_Allocators}
6941 @code{No_Local_Protected_Objects}
6944 @code{No_Requeue_Statements}
6947 @code{No_Task_Attributes_Package}
6950 @code{Max_Asynchronous_Select_Nesting = 0}
6953 @code{Max_Task_Entries = 0}
6956 @code{Max_Protected_Entries = 1}
6959 @code{Max_Select_Alternatives = 0}
6962 This set of restrictions causes the automatic selection of a simplified
6963 version of the run time that provides improved performance for the
6964 limited set of tasking functionality permitted by this set of restrictions.
6967 Pragma Profile (Rational)
6969 The Rational profile is intended to facilitate porting legacy code that
6970 compiles with the Rational APEX compiler, even when the code includes non-
6971 conforming Ada constructs. The profile enables the following three pragmas:
6977 @code{pragma Implicit_Packing}
6980 @code{pragma Overriding_Renamings}
6983 @code{pragma Use_VADS_Size}
6987 @node Pragma Profile_Warnings,Pragma Propagate_Exceptions,Pragma Profile,Implementation Defined Pragmas
6988 @anchor{gnat_rm/implementation_defined_pragmas pragma-profile-warnings}@anchor{cb}
6989 @section Pragma Profile_Warnings
6995 pragma Profile_Warnings (Ravenscar | Restricted | Rational);
6998 This is an implementation-defined pragma that is similar in
6999 effect to @code{pragma Profile} except that instead of
7000 generating @code{Restrictions} pragmas, it generates
7001 @code{Restriction_Warnings} pragmas. The result is that
7002 violations of the profile generate warning messages instead
7005 @node Pragma Propagate_Exceptions,Pragma Provide_Shift_Operators,Pragma Profile_Warnings,Implementation Defined Pragmas
7006 @anchor{gnat_rm/implementation_defined_pragmas pragma-propagate-exceptions}@anchor{cc}
7007 @section Pragma Propagate_Exceptions
7010 @geindex Interfacing to C++
7015 pragma Propagate_Exceptions;
7018 This pragma is now obsolete and, other than generating a warning if warnings
7019 on obsolescent features are enabled, is ignored.
7020 It is retained for compatibility
7021 purposes. It used to be used in connection with optimization of
7022 a now-obsolete mechanism for implementation of exceptions.
7024 @node Pragma Provide_Shift_Operators,Pragma Psect_Object,Pragma Propagate_Exceptions,Implementation Defined Pragmas
7025 @anchor{gnat_rm/implementation_defined_pragmas pragma-provide-shift-operators}@anchor{cd}
7026 @section Pragma Provide_Shift_Operators
7029 @geindex Shift operators
7034 pragma Provide_Shift_Operators (integer_first_subtype_LOCAL_NAME);
7037 This pragma can be applied to a first subtype local name that specifies
7038 either an unsigned or signed type. It has the effect of providing the
7039 five shift operators (Shift_Left, Shift_Right, Shift_Right_Arithmetic,
7040 Rotate_Left and Rotate_Right) for the given type. It is similar to
7041 including the function declarations for these five operators, together
7042 with the pragma Import (Intrinsic, ...) statements.
7044 @node Pragma Psect_Object,Pragma Pure_Function,Pragma Provide_Shift_Operators,Implementation Defined Pragmas
7045 @anchor{gnat_rm/implementation_defined_pragmas pragma-psect-object}@anchor{ce}
7046 @section Pragma Psect_Object
7052 pragma Psect_Object (
7053 [Internal =>] LOCAL_NAME,
7054 [, [External =>] EXTERNAL_SYMBOL]
7055 [, [Size =>] EXTERNAL_SYMBOL]);
7059 | static_string_EXPRESSION
7062 This pragma is identical in effect to pragma @code{Common_Object}.
7064 @node Pragma Pure_Function,Pragma Rational,Pragma Psect_Object,Implementation Defined Pragmas
7065 @anchor{gnat_rm/implementation_defined_pragmas pragma-pure-function}@anchor{cf}@anchor{gnat_rm/implementation_defined_pragmas id31}@anchor{d0}
7066 @section Pragma Pure_Function
7072 pragma Pure_Function ([Entity =>] function_LOCAL_NAME);
7075 This pragma appears in the same declarative part as a function
7076 declaration (or a set of function declarations if more than one
7077 overloaded declaration exists, in which case the pragma applies
7078 to all entities). It specifies that the function @code{Entity} is
7079 to be considered pure for the purposes of code generation. This means
7080 that the compiler can assume that there are no side effects, and
7081 in particular that two calls with identical arguments produce the
7082 same result. It also means that the function can be used in an
7085 Note that, quite deliberately, there are no static checks to try
7086 to ensure that this promise is met, so @code{Pure_Function} can be used
7087 with functions that are conceptually pure, even if they do modify
7088 global variables. For example, a square root function that is
7089 instrumented to count the number of times it is called is still
7090 conceptually pure, and can still be optimized, even though it
7091 modifies a global variable (the count). Memo functions are another
7092 example (where a table of previous calls is kept and consulted to
7093 avoid re-computation).
7095 Note also that the normal rules excluding optimization of subprograms
7096 in pure units (when parameter types are descended from System.Address,
7097 or when the full view of a parameter type is limited), do not apply
7098 for the Pure_Function case. If you explicitly specify Pure_Function,
7099 the compiler may optimize away calls with identical arguments, and
7100 if that results in unexpected behavior, the proper action is not to
7101 use the pragma for subprograms that are not (conceptually) pure.
7103 Note: Most functions in a @code{Pure} package are automatically pure, and
7104 there is no need to use pragma @code{Pure_Function} for such functions. One
7105 exception is any function that has at least one formal of type
7106 @code{System.Address} or a type derived from it. Such functions are not
7107 considered pure by default, since the compiler assumes that the
7108 @code{Address} parameter may be functioning as a pointer and that the
7109 referenced data may change even if the address value does not.
7110 Similarly, imported functions are not considered to be pure by default,
7111 since there is no way of checking that they are in fact pure. The use
7112 of pragma @code{Pure_Function} for such a function will override these default
7113 assumption, and cause the compiler to treat a designated subprogram as pure
7116 Note: If pragma @code{Pure_Function} is applied to a renamed function, it
7117 applies to the underlying renamed function. This can be used to
7118 disambiguate cases of overloading where some but not all functions
7119 in a set of overloaded functions are to be designated as pure.
7121 If pragma @code{Pure_Function} is applied to a library-level function, the
7122 function is also considered pure from an optimization point of view, but the
7123 unit is not a Pure unit in the categorization sense. So for example, a function
7124 thus marked is free to @code{with} non-pure units.
7126 @node Pragma Rational,Pragma Ravenscar,Pragma Pure_Function,Implementation Defined Pragmas
7127 @anchor{gnat_rm/implementation_defined_pragmas pragma-rational}@anchor{d1}
7128 @section Pragma Rational
7137 This pragma is considered obsolescent, but is retained for
7138 compatibility purposes. It is equivalent to:
7141 pragma Profile (Rational);
7144 @node Pragma Ravenscar,Pragma Refined_Depends,Pragma Rational,Implementation Defined Pragmas
7145 @anchor{gnat_rm/implementation_defined_pragmas pragma-ravenscar}@anchor{d2}
7146 @section Pragma Ravenscar
7155 This pragma is considered obsolescent, but is retained for
7156 compatibility purposes. It is equivalent to:
7159 pragma Profile (Ravenscar);
7162 which is the preferred method of setting the @code{Ravenscar} profile.
7164 @node Pragma Refined_Depends,Pragma Refined_Global,Pragma Ravenscar,Implementation Defined Pragmas
7165 @anchor{gnat_rm/implementation_defined_pragmas pragma-refined-depends}@anchor{d3}@anchor{gnat_rm/implementation_defined_pragmas id32}@anchor{d4}
7166 @section Pragma Refined_Depends
7172 pragma Refined_Depends (DEPENDENCY_RELATION);
7174 DEPENDENCY_RELATION ::=
7176 | (DEPENDENCY_CLAUSE @{, DEPENDENCY_CLAUSE@})
7178 DEPENDENCY_CLAUSE ::=
7179 OUTPUT_LIST =>[+] INPUT_LIST
7180 | NULL_DEPENDENCY_CLAUSE
7182 NULL_DEPENDENCY_CLAUSE ::= null => INPUT_LIST
7184 OUTPUT_LIST ::= OUTPUT | (OUTPUT @{, OUTPUT@})
7186 INPUT_LIST ::= null | INPUT | (INPUT @{, INPUT@})
7188 OUTPUT ::= NAME | FUNCTION_RESULT
7191 where FUNCTION_RESULT is a function Result attribute_reference
7194 For the semantics of this pragma, see the entry for aspect @code{Refined_Depends} in
7195 the SPARK 2014 Reference Manual, section 6.1.5.
7197 @node Pragma Refined_Global,Pragma Refined_Post,Pragma Refined_Depends,Implementation Defined Pragmas
7198 @anchor{gnat_rm/implementation_defined_pragmas pragma-refined-global}@anchor{d5}@anchor{gnat_rm/implementation_defined_pragmas id33}@anchor{d6}
7199 @section Pragma Refined_Global
7205 pragma Refined_Global (GLOBAL_SPECIFICATION);
7207 GLOBAL_SPECIFICATION ::=
7210 | (MODED_GLOBAL_LIST @{, MODED_GLOBAL_LIST@})
7212 MODED_GLOBAL_LIST ::= MODE_SELECTOR => GLOBAL_LIST
7214 MODE_SELECTOR ::= In_Out | Input | Output | Proof_In
7215 GLOBAL_LIST ::= GLOBAL_ITEM | (GLOBAL_ITEM @{, GLOBAL_ITEM@})
7216 GLOBAL_ITEM ::= NAME
7219 For the semantics of this pragma, see the entry for aspect @code{Refined_Global} in
7220 the SPARK 2014 Reference Manual, section 6.1.4.
7222 @node Pragma Refined_Post,Pragma Refined_State,Pragma Refined_Global,Implementation Defined Pragmas
7223 @anchor{gnat_rm/implementation_defined_pragmas pragma-refined-post}@anchor{d7}@anchor{gnat_rm/implementation_defined_pragmas id34}@anchor{d8}
7224 @section Pragma Refined_Post
7230 pragma Refined_Post (boolean_EXPRESSION);
7233 For the semantics of this pragma, see the entry for aspect @code{Refined_Post} in
7234 the SPARK 2014 Reference Manual, section 7.2.7.
7236 @node Pragma Refined_State,Pragma Relative_Deadline,Pragma Refined_Post,Implementation Defined Pragmas
7237 @anchor{gnat_rm/implementation_defined_pragmas pragma-refined-state}@anchor{d9}@anchor{gnat_rm/implementation_defined_pragmas id35}@anchor{da}
7238 @section Pragma Refined_State
7244 pragma Refined_State (REFINEMENT_LIST);
7247 (REFINEMENT_CLAUSE @{, REFINEMENT_CLAUSE@})
7249 REFINEMENT_CLAUSE ::= state_NAME => CONSTITUENT_LIST
7251 CONSTITUENT_LIST ::=
7254 | (CONSTITUENT @{, CONSTITUENT@})
7256 CONSTITUENT ::= object_NAME | state_NAME
7259 For the semantics of this pragma, see the entry for aspect @code{Refined_State} in
7260 the SPARK 2014 Reference Manual, section 7.2.2.
7262 @node Pragma Relative_Deadline,Pragma Remote_Access_Type,Pragma Refined_State,Implementation Defined Pragmas
7263 @anchor{gnat_rm/implementation_defined_pragmas pragma-relative-deadline}@anchor{db}
7264 @section Pragma Relative_Deadline
7270 pragma Relative_Deadline (time_span_EXPRESSION);
7273 This pragma is standard in Ada 2005, but is available in all earlier
7274 versions of Ada as an implementation-defined pragma.
7275 See Ada 2012 Reference Manual for details.
7277 @node Pragma Remote_Access_Type,Pragma Restricted_Run_Time,Pragma Relative_Deadline,Implementation Defined Pragmas
7278 @anchor{gnat_rm/implementation_defined_pragmas id36}@anchor{dc}@anchor{gnat_rm/implementation_defined_pragmas pragma-remote-access-type}@anchor{dd}
7279 @section Pragma Remote_Access_Type
7285 pragma Remote_Access_Type ([Entity =>] formal_access_type_LOCAL_NAME);
7288 This pragma appears in the formal part of a generic declaration.
7289 It specifies an exception to the RM rule from E.2.2(17/2), which forbids
7290 the use of a remote access to class-wide type as actual for a formal
7293 When this pragma applies to a formal access type @code{Entity}, that
7294 type is treated as a remote access to class-wide type in the generic.
7295 It must be a formal general access type, and its designated type must
7296 be the class-wide type of a formal tagged limited private type from the
7297 same generic declaration.
7299 In the generic unit, the formal type is subject to all restrictions
7300 pertaining to remote access to class-wide types. At instantiation, the
7301 actual type must be a remote access to class-wide type.
7303 @node Pragma Restricted_Run_Time,Pragma Restriction_Warnings,Pragma Remote_Access_Type,Implementation Defined Pragmas
7304 @anchor{gnat_rm/implementation_defined_pragmas pragma-restricted-run-time}@anchor{de}
7305 @section Pragma Restricted_Run_Time
7311 pragma Restricted_Run_Time;
7314 This pragma is considered obsolescent, but is retained for
7315 compatibility purposes. It is equivalent to:
7318 pragma Profile (Restricted);
7321 which is the preferred method of setting the restricted run time
7324 @node Pragma Restriction_Warnings,Pragma Reviewable,Pragma Restricted_Run_Time,Implementation Defined Pragmas
7325 @anchor{gnat_rm/implementation_defined_pragmas pragma-restriction-warnings}@anchor{df}
7326 @section Pragma Restriction_Warnings
7332 pragma Restriction_Warnings
7333 (restriction_IDENTIFIER @{, restriction_IDENTIFIER@});
7336 This pragma allows a series of restriction identifiers to be
7337 specified (the list of allowed identifiers is the same as for
7338 pragma @code{Restrictions}). For each of these identifiers
7339 the compiler checks for violations of the restriction, but
7340 generates a warning message rather than an error message
7341 if the restriction is violated.
7343 One use of this is in situations where you want to know
7344 about violations of a restriction, but you want to ignore some of
7345 these violations. Consider this example, where you want to set
7346 Ada_95 mode and enable style checks, but you want to know about
7347 any other use of implementation pragmas:
7350 pragma Restriction_Warnings (No_Implementation_Pragmas);
7351 pragma Warnings (Off, "violation of No_Implementation_Pragmas");
7353 pragma Style_Checks ("2bfhkM160");
7354 pragma Warnings (On, "violation of No_Implementation_Pragmas");
7357 By including the above lines in a configuration pragmas file,
7358 the Ada_95 and Style_Checks pragmas are accepted without
7359 generating a warning, but any other use of implementation
7360 defined pragmas will cause a warning to be generated.
7362 @node Pragma Reviewable,Pragma Secondary_Stack_Size,Pragma Restriction_Warnings,Implementation Defined Pragmas
7363 @anchor{gnat_rm/implementation_defined_pragmas pragma-reviewable}@anchor{e0}
7364 @section Pragma Reviewable
7373 This pragma is an RM-defined standard pragma, but has no effect on the
7374 program being compiled, or on the code generated for the program.
7376 To obtain the required output specified in RM H.3.1, the compiler must be
7377 run with various special switches as follows:
7383 @emph{Where compiler-generated run-time checks remain}
7385 The switch @emph{-gnatGL}
7386 may be used to list the expanded code in pseudo-Ada form.
7387 Runtime checks show up in the listing either as explicit
7388 checks or operators marked with @{@} to indicate a check is present.
7391 @emph{An identification of known exceptions at compile time}
7393 If the program is compiled with @emph{-gnatwa},
7394 the compiler warning messages will indicate all cases where the compiler
7395 detects that an exception is certain to occur at run time.
7398 @emph{Possible reads of uninitialized variables}
7400 The compiler warns of many such cases, but its output is incomplete.
7404 A supplemental static analysis tool
7405 may be used to obtain a comprehensive list of all
7406 possible points at which uninitialized data may be read.
7412 @emph{Where run-time support routines are implicitly invoked}
7414 In the output from @emph{-gnatGL},
7415 run-time calls are explicitly listed as calls to the relevant
7419 @emph{Object code listing}
7421 This may be obtained either by using the @emph{-S} switch,
7422 or the objdump utility.
7425 @emph{Constructs known to be erroneous at compile time}
7427 These are identified by warnings issued by the compiler (use @emph{-gnatwa}).
7430 @emph{Stack usage information}
7432 Static stack usage data (maximum per-subprogram) can be obtained via the
7433 @emph{-fstack-usage} switch to the compiler.
7434 Dynamic stack usage data (per task) can be obtained via the @emph{-u} switch
7443 @emph{Object code listing of entire partition}
7445 This can be obtained by compiling the partition with @emph{-S},
7446 or by applying objdump
7447 to all the object files that are part of the partition.
7450 @emph{A description of the run-time model}
7452 The full sources of the run-time are available, and the documentation of
7453 these routines describes how these run-time routines interface to the
7454 underlying operating system facilities.
7457 @emph{Control and data-flow information}
7461 A supplemental static analysis tool
7462 may be used to obtain complete control and data-flow information, as well as
7463 comprehensive messages identifying possible problems based on this
7466 @node Pragma Secondary_Stack_Size,Pragma Share_Generic,Pragma Reviewable,Implementation Defined Pragmas
7467 @anchor{gnat_rm/implementation_defined_pragmas id37}@anchor{e1}@anchor{gnat_rm/implementation_defined_pragmas pragma-secondary-stack-size}@anchor{e2}
7468 @section Pragma Secondary_Stack_Size
7474 pragma Secondary_Stack_Size (integer_EXPRESSION);
7477 This pragma appears within the task definition of a single task declaration
7478 or a task type declaration (like pragma @code{Storage_Size}) and applies to all
7479 task objects of that type. The argument specifies the size of the secondary
7480 stack to be used by these task objects, and must be of an integer type. The
7481 secondary stack is used to handle functions that return a variable-sized
7482 result, for example a function returning an unconstrained String.
7484 Note this pragma only applies to targets using fixed secondary stacks, like
7485 VxWorks 653 and bare board targets, where a fixed block for the
7486 secondary stack is allocated from the primary stack of the task. By default,
7487 these targets assign a percentage of the primary stack for the secondary stack,
7488 as defined by @code{System.Parameter.Sec_Stack_Percentage}. With this pragma,
7489 an @code{integer_EXPRESSION} of bytes is assigned from the primary stack instead.
7491 For most targets, the pragma does not apply as the secondary stack grows on
7492 demand: allocated as a chain of blocks in the heap. The default size of these
7493 blocks can be modified via the @code{-D} binder option as described in
7494 @cite{GNAT User's Guide}.
7496 Note that no check is made to see if the secondary stack can fit inside the
7499 Note the pragma cannot appear when the restriction @code{No_Secondary_Stack}
7502 @node Pragma Share_Generic,Pragma Shared,Pragma Secondary_Stack_Size,Implementation Defined Pragmas
7503 @anchor{gnat_rm/implementation_defined_pragmas pragma-share-generic}@anchor{e3}
7504 @section Pragma Share_Generic
7510 pragma Share_Generic (GNAME @{, GNAME@});
7512 GNAME ::= generic_unit_NAME | generic_instance_NAME
7515 This pragma is provided for compatibility with Dec Ada 83. It has
7516 no effect in GNAT (which does not implement shared generics), other
7517 than to check that the given names are all names of generic units or
7520 @node Pragma Shared,Pragma Short_Circuit_And_Or,Pragma Share_Generic,Implementation Defined Pragmas
7521 @anchor{gnat_rm/implementation_defined_pragmas id38}@anchor{e4}@anchor{gnat_rm/implementation_defined_pragmas pragma-shared}@anchor{e5}
7522 @section Pragma Shared
7525 This pragma is provided for compatibility with Ada 83. The syntax and
7526 semantics are identical to pragma Atomic.
7528 @node Pragma Short_Circuit_And_Or,Pragma Short_Descriptors,Pragma Shared,Implementation Defined Pragmas
7529 @anchor{gnat_rm/implementation_defined_pragmas pragma-short-circuit-and-or}@anchor{e6}
7530 @section Pragma Short_Circuit_And_Or
7536 pragma Short_Circuit_And_Or;
7539 This configuration pragma causes any occurrence of the AND operator applied to
7540 operands of type Standard.Boolean to be short-circuited (i.e. the AND operator
7541 is treated as if it were AND THEN). Or is similarly treated as OR ELSE. This
7542 may be useful in the context of certification protocols requiring the use of
7543 short-circuited logical operators. If this configuration pragma occurs locally
7544 within the file being compiled, it applies only to the file being compiled.
7545 There is no requirement that all units in a partition use this option.
7547 @node Pragma Short_Descriptors,Pragma Simple_Storage_Pool_Type,Pragma Short_Circuit_And_Or,Implementation Defined Pragmas
7548 @anchor{gnat_rm/implementation_defined_pragmas pragma-short-descriptors}@anchor{e7}
7549 @section Pragma Short_Descriptors
7555 pragma Short_Descriptors
7558 This pragma is provided for compatibility with other Ada implementations. It
7559 is recognized but ignored by all current versions of GNAT.
7561 @node Pragma Simple_Storage_Pool_Type,Pragma Source_File_Name,Pragma Short_Descriptors,Implementation Defined Pragmas
7562 @anchor{gnat_rm/implementation_defined_pragmas pragma-simple-storage-pool-type}@anchor{e8}@anchor{gnat_rm/implementation_defined_pragmas id39}@anchor{e9}
7563 @section Pragma Simple_Storage_Pool_Type
7566 @geindex Storage pool
7569 @geindex Simple storage pool
7574 pragma Simple_Storage_Pool_Type (type_LOCAL_NAME);
7577 A type can be established as a 'simple storage pool type' by applying
7578 the representation pragma @code{Simple_Storage_Pool_Type} to the type.
7579 A type named in the pragma must be a library-level immutably limited record
7580 type or limited tagged type declared immediately within a package declaration.
7581 The type can also be a limited private type whose full type is allowed as
7582 a simple storage pool type.
7584 For a simple storage pool type @code{SSP}, nonabstract primitive subprograms
7585 @code{Allocate}, @code{Deallocate}, and @code{Storage_Size} can be declared that
7586 are subtype conformant with the following subprogram declarations:
7591 Storage_Address : out System.Address;
7592 Size_In_Storage_Elements : System.Storage_Elements.Storage_Count;
7593 Alignment : System.Storage_Elements.Storage_Count);
7595 procedure Deallocate
7597 Storage_Address : System.Address;
7598 Size_In_Storage_Elements : System.Storage_Elements.Storage_Count;
7599 Alignment : System.Storage_Elements.Storage_Count);
7601 function Storage_Size (Pool : SSP)
7602 return System.Storage_Elements.Storage_Count;
7605 Procedure @code{Allocate} must be declared, whereas @code{Deallocate} and
7606 @code{Storage_Size} are optional. If @code{Deallocate} is not declared, then
7607 applying an unchecked deallocation has no effect other than to set its actual
7608 parameter to null. If @code{Storage_Size} is not declared, then the
7609 @code{Storage_Size} attribute applied to an access type associated with
7610 a pool object of type SSP returns zero. Additional operations can be declared
7611 for a simple storage pool type (such as for supporting a mark/release
7612 storage-management discipline).
7614 An object of a simple storage pool type can be associated with an access
7615 type by specifying the attribute
7616 @ref{ea,,Simple_Storage_Pool}. For example:
7619 My_Pool : My_Simple_Storage_Pool_Type;
7621 type Acc is access My_Data_Type;
7623 for Acc'Simple_Storage_Pool use My_Pool;
7626 See attribute @ref{ea,,Simple_Storage_Pool}
7627 for further details.
7629 @node Pragma Source_File_Name,Pragma Source_File_Name_Project,Pragma Simple_Storage_Pool_Type,Implementation Defined Pragmas
7630 @anchor{gnat_rm/implementation_defined_pragmas pragma-source-file-name}@anchor{eb}@anchor{gnat_rm/implementation_defined_pragmas id40}@anchor{ec}
7631 @section Pragma Source_File_Name
7637 pragma Source_File_Name (
7638 [Unit_Name =>] unit_NAME,
7639 Spec_File_Name => STRING_LITERAL,
7640 [Index => INTEGER_LITERAL]);
7642 pragma Source_File_Name (
7643 [Unit_Name =>] unit_NAME,
7644 Body_File_Name => STRING_LITERAL,
7645 [Index => INTEGER_LITERAL]);
7648 Use this to override the normal naming convention. It is a configuration
7649 pragma, and so has the usual applicability of configuration pragmas
7650 (i.e., it applies to either an entire partition, or to all units in a
7651 compilation, or to a single unit, depending on how it is used.
7652 @code{unit_name} is mapped to @code{file_name_literal}. The identifier for
7653 the second argument is required, and indicates whether this is the file
7654 name for the spec or for the body.
7656 The optional Index argument should be used when a file contains multiple
7657 units, and when you do not want to use @code{gnatchop} to separate then
7658 into multiple files (which is the recommended procedure to limit the
7659 number of recompilations that are needed when some sources change).
7660 For instance, if the source file @code{source.ada} contains
7674 you could use the following configuration pragmas:
7677 pragma Source_File_Name
7678 (B, Spec_File_Name => "source.ada", Index => 1);
7679 pragma Source_File_Name
7680 (A, Body_File_Name => "source.ada", Index => 2);
7683 Note that the @code{gnatname} utility can also be used to generate those
7684 configuration pragmas.
7686 Another form of the @code{Source_File_Name} pragma allows
7687 the specification of patterns defining alternative file naming schemes
7688 to apply to all files.
7691 pragma Source_File_Name
7692 ( [Spec_File_Name =>] STRING_LITERAL
7693 [,[Casing =>] CASING_SPEC]
7694 [,[Dot_Replacement =>] STRING_LITERAL]);
7696 pragma Source_File_Name
7697 ( [Body_File_Name =>] STRING_LITERAL
7698 [,[Casing =>] CASING_SPEC]
7699 [,[Dot_Replacement =>] STRING_LITERAL]);
7701 pragma Source_File_Name
7702 ( [Subunit_File_Name =>] STRING_LITERAL
7703 [,[Casing =>] CASING_SPEC]
7704 [,[Dot_Replacement =>] STRING_LITERAL]);
7706 CASING_SPEC ::= Lowercase | Uppercase | Mixedcase
7709 The first argument is a pattern that contains a single asterisk indicating
7710 the point at which the unit name is to be inserted in the pattern string
7711 to form the file name. The second argument is optional. If present it
7712 specifies the casing of the unit name in the resulting file name string.
7713 The default is lower case. Finally the third argument allows for systematic
7714 replacement of any dots in the unit name by the specified string literal.
7716 Note that Source_File_Name pragmas should not be used if you are using
7717 project files. The reason for this rule is that the project manager is not
7718 aware of these pragmas, and so other tools that use the projet file would not
7719 be aware of the intended naming conventions. If you are using project files,
7720 file naming is controlled by Source_File_Name_Project pragmas, which are
7721 usually supplied automatically by the project manager. A pragma
7722 Source_File_Name cannot appear after a @ref{ed,,Pragma Source_File_Name_Project}.
7724 For more details on the use of the @code{Source_File_Name} pragma, see the
7725 sections on @code{Using Other File Names} and @cite{Alternative File Naming Schemes' in the :title:`GNAT User's Guide}.
7727 @node Pragma Source_File_Name_Project,Pragma Source_Reference,Pragma Source_File_Name,Implementation Defined Pragmas
7728 @anchor{gnat_rm/implementation_defined_pragmas pragma-source-file-name-project}@anchor{ed}@anchor{gnat_rm/implementation_defined_pragmas id41}@anchor{ee}
7729 @section Pragma Source_File_Name_Project
7732 This pragma has the same syntax and semantics as pragma Source_File_Name.
7733 It is only allowed as a stand-alone configuration pragma.
7734 It cannot appear after a @ref{eb,,Pragma Source_File_Name}, and
7735 most importantly, once pragma Source_File_Name_Project appears,
7736 no further Source_File_Name pragmas are allowed.
7738 The intention is that Source_File_Name_Project pragmas are always
7739 generated by the Project Manager in a manner consistent with the naming
7740 specified in a project file, and when naming is controlled in this manner,
7741 it is not permissible to attempt to modify this naming scheme using
7742 Source_File_Name or Source_File_Name_Project pragmas (which would not be
7743 known to the project manager).
7745 @node Pragma Source_Reference,Pragma SPARK_Mode,Pragma Source_File_Name_Project,Implementation Defined Pragmas
7746 @anchor{gnat_rm/implementation_defined_pragmas pragma-source-reference}@anchor{ef}
7747 @section Pragma Source_Reference
7753 pragma Source_Reference (INTEGER_LITERAL, STRING_LITERAL);
7756 This pragma must appear as the first line of a source file.
7757 @code{integer_literal} is the logical line number of the line following
7758 the pragma line (for use in error messages and debugging
7759 information). @code{string_literal} is a static string constant that
7760 specifies the file name to be used in error messages and debugging
7761 information. This is most notably used for the output of @code{gnatchop}
7762 with the @emph{-r} switch, to make sure that the original unchopped
7763 source file is the one referred to.
7765 The second argument must be a string literal, it cannot be a static
7766 string expression other than a string literal. This is because its value
7767 is needed for error messages issued by all phases of the compiler.
7769 @node Pragma SPARK_Mode,Pragma Static_Elaboration_Desired,Pragma Source_Reference,Implementation Defined Pragmas
7770 @anchor{gnat_rm/implementation_defined_pragmas pragma-spark-mode}@anchor{f0}@anchor{gnat_rm/implementation_defined_pragmas id42}@anchor{f1}
7771 @section Pragma SPARK_Mode
7777 pragma SPARK_Mode [(On | Off)] ;
7780 In general a program can have some parts that are in SPARK 2014 (and
7781 follow all the rules in the SPARK Reference Manual), and some parts
7782 that are full Ada 2012.
7784 The SPARK_Mode pragma is used to identify which parts are in SPARK
7785 2014 (by default programs are in full Ada). The SPARK_Mode pragma can
7786 be used in the following places:
7792 As a configuration pragma, in which case it sets the default mode for
7793 all units compiled with this pragma.
7796 Immediately following a library-level subprogram spec
7799 Immediately within a library-level package body
7802 Immediately following the @code{private} keyword of a library-level
7806 Immediately following the @code{begin} keyword of a library-level
7810 Immediately within a library-level subprogram body
7813 Normally a subprogram or package spec/body inherits the current mode
7814 that is active at the point it is declared. But this can be overridden
7815 by pragma within the spec or body as above.
7817 The basic consistency rule is that you can't turn SPARK_Mode back
7818 @code{On}, once you have explicitly (with a pragma) turned if
7819 @code{Off}. So the following rules apply:
7821 If a subprogram spec has SPARK_Mode @code{Off}, then the body must
7822 also have SPARK_Mode @code{Off}.
7824 For a package, we have four parts:
7830 the package public declarations
7833 the package private part
7836 the body of the package
7839 the elaboration code after @code{begin}
7842 For a package, the rule is that if you explicitly turn SPARK_Mode
7843 @code{Off} for any part, then all the following parts must have
7844 SPARK_Mode @code{Off}. Note that this may require repeating a pragma
7845 SPARK_Mode (@code{Off}) in the body. For example, if we have a
7846 configuration pragma SPARK_Mode (@code{On}) that turns the mode on by
7847 default everywhere, and one particular package spec has pragma
7848 SPARK_Mode (@code{Off}), then that pragma will need to be repeated in
7851 @node Pragma Static_Elaboration_Desired,Pragma Stream_Convert,Pragma SPARK_Mode,Implementation Defined Pragmas
7852 @anchor{gnat_rm/implementation_defined_pragmas pragma-static-elaboration-desired}@anchor{f2}
7853 @section Pragma Static_Elaboration_Desired
7859 pragma Static_Elaboration_Desired;
7862 This pragma is used to indicate that the compiler should attempt to initialize
7863 statically the objects declared in the library unit to which the pragma applies,
7864 when these objects are initialized (explicitly or implicitly) by an aggregate.
7865 In the absence of this pragma, aggregates in object declarations are expanded
7866 into assignments and loops, even when the aggregate components are static
7867 constants. When the aggregate is present the compiler builds a static expression
7868 that requires no run-time code, so that the initialized object can be placed in
7869 read-only data space. If the components are not static, or the aggregate has
7870 more that 100 components, the compiler emits a warning that the pragma cannot
7871 be obeyed. (See also the restriction No_Implicit_Loops, which supports static
7872 construction of larger aggregates with static components that include an others
7875 @node Pragma Stream_Convert,Pragma Style_Checks,Pragma Static_Elaboration_Desired,Implementation Defined Pragmas
7876 @anchor{gnat_rm/implementation_defined_pragmas pragma-stream-convert}@anchor{f3}
7877 @section Pragma Stream_Convert
7883 pragma Stream_Convert (
7884 [Entity =>] type_LOCAL_NAME,
7885 [Read =>] function_NAME,
7886 [Write =>] function_NAME);
7889 This pragma provides an efficient way of providing user-defined stream
7890 attributes. Not only is it simpler to use than specifying the attributes
7891 directly, but more importantly, it allows the specification to be made in such
7892 a way that the predefined unit Ada.Streams is not loaded unless it is actually
7893 needed (i.e. unless the stream attributes are actually used); the use of
7894 the Stream_Convert pragma adds no overhead at all, unless the stream
7895 attributes are actually used on the designated type.
7897 The first argument specifies the type for which stream functions are
7898 provided. The second parameter provides a function used to read values
7899 of this type. It must name a function whose argument type may be any
7900 subtype, and whose returned type must be the type given as the first
7901 argument to the pragma.
7903 The meaning of the @code{Read} parameter is that if a stream attribute directly
7904 or indirectly specifies reading of the type given as the first parameter,
7905 then a value of the type given as the argument to the Read function is
7906 read from the stream, and then the Read function is used to convert this
7907 to the required target type.
7909 Similarly the @code{Write} parameter specifies how to treat write attributes
7910 that directly or indirectly apply to the type given as the first parameter.
7911 It must have an input parameter of the type specified by the first parameter,
7912 and the return type must be the same as the input type of the Read function.
7913 The effect is to first call the Write function to convert to the given stream
7914 type, and then write the result type to the stream.
7916 The Read and Write functions must not be overloaded subprograms. If necessary
7917 renamings can be supplied to meet this requirement.
7918 The usage of this attribute is best illustrated by a simple example, taken
7919 from the GNAT implementation of package Ada.Strings.Unbounded:
7922 function To_Unbounded (S : String) return Unbounded_String
7923 renames To_Unbounded_String;
7925 pragma Stream_Convert
7926 (Unbounded_String, To_Unbounded, To_String);
7929 The specifications of the referenced functions, as given in the Ada
7930 Reference Manual are:
7933 function To_Unbounded_String (Source : String)
7934 return Unbounded_String;
7936 function To_String (Source : Unbounded_String)
7940 The effect is that if the value of an unbounded string is written to a stream,
7941 then the representation of the item in the stream is in the same format that
7942 would be used for @code{Standard.String'Output}, and this same representation
7943 is expected when a value of this type is read from the stream. Note that the
7944 value written always includes the bounds, even for Unbounded_String'Write,
7945 since Unbounded_String is not an array type.
7947 Note that the @code{Stream_Convert} pragma is not effective in the case of
7948 a derived type of a non-limited tagged type. If such a type is specified then
7949 the pragma is silently ignored, and the default implementation of the stream
7950 attributes is used instead.
7952 @node Pragma Style_Checks,Pragma Subtitle,Pragma Stream_Convert,Implementation Defined Pragmas
7953 @anchor{gnat_rm/implementation_defined_pragmas pragma-style-checks}@anchor{f4}
7954 @section Pragma Style_Checks
7960 pragma Style_Checks (string_LITERAL | ALL_CHECKS |
7961 On | Off [, LOCAL_NAME]);
7964 This pragma is used in conjunction with compiler switches to control the
7965 built in style checking provided by GNAT. The compiler switches, if set,
7966 provide an initial setting for the switches, and this pragma may be used
7967 to modify these settings, or the settings may be provided entirely by
7968 the use of the pragma. This pragma can be used anywhere that a pragma
7969 is legal, including use as a configuration pragma (including use in
7970 the @code{gnat.adc} file).
7972 The form with a string literal specifies which style options are to be
7973 activated. These are additive, so they apply in addition to any previously
7974 set style check options. The codes for the options are the same as those
7975 used in the @emph{-gnaty} switch to @emph{gcc} or @emph{gnatmake}.
7976 For example the following two methods can be used to enable
7984 pragma Style_Checks ("l");
7993 The form @code{ALL_CHECKS} activates all standard checks (its use is equivalent
7994 to the use of the @code{gnaty} switch with no options.
7995 See the @cite{GNAT User's Guide} for details.)
7997 Note: the behavior is slightly different in GNAT mode (@code{-gnatg} used).
7998 In this case, @code{ALL_CHECKS} implies the standard set of GNAT mode style check
7999 options (i.e. equivalent to @code{-gnatyg}).
8001 The forms with @code{Off} and @code{On}
8002 can be used to temporarily disable style checks
8003 as shown in the following example:
8006 pragma Style_Checks ("k"); -- requires keywords in lower case
8007 pragma Style_Checks (Off); -- turn off style checks
8008 NULL; -- this will not generate an error message
8009 pragma Style_Checks (On); -- turn style checks back on
8010 NULL; -- this will generate an error message
8013 Finally the two argument form is allowed only if the first argument is
8014 @code{On} or @code{Off}. The effect is to turn of semantic style checks
8015 for the specified entity, as shown in the following example:
8018 pragma Style_Checks ("r"); -- require consistency of identifier casing
8020 Rf1 : Integer := ARG; -- incorrect, wrong case
8021 pragma Style_Checks (Off, Arg);
8022 Rf2 : Integer := ARG; -- OK, no error
8025 @node Pragma Subtitle,Pragma Suppress,Pragma Style_Checks,Implementation Defined Pragmas
8026 @anchor{gnat_rm/implementation_defined_pragmas pragma-subtitle}@anchor{f5}
8027 @section Pragma Subtitle
8033 pragma Subtitle ([Subtitle =>] STRING_LITERAL);
8036 This pragma is recognized for compatibility with other Ada compilers
8037 but is ignored by GNAT.
8039 @node Pragma Suppress,Pragma Suppress_All,Pragma Subtitle,Implementation Defined Pragmas
8040 @anchor{gnat_rm/implementation_defined_pragmas pragma-suppress}@anchor{f6}
8041 @section Pragma Suppress
8047 pragma Suppress (Identifier [, [On =>] Name]);
8050 This is a standard pragma, and supports all the check names required in
8051 the RM. It is included here because GNAT recognizes some additional check
8052 names that are implementation defined (as permitted by the RM):
8058 @code{Alignment_Check} can be used to suppress alignment checks
8059 on addresses used in address clauses. Such checks can also be suppressed
8060 by suppressing range checks, but the specific use of @code{Alignment_Check}
8061 allows suppression of alignment checks without suppressing other range checks.
8062 Note that @code{Alignment_Check} is suppressed by default on machines (such as
8063 the x86) with non-strict alignment.
8066 @code{Atomic_Synchronization} can be used to suppress the special memory
8067 synchronization instructions that are normally generated for access to
8068 @code{Atomic} variables to ensure correct synchronization between tasks
8069 that use such variables for synchronization purposes.
8072 @code{Duplicated_Tag_Check} Can be used to suppress the check that is generated
8073 for a duplicated tag value when a tagged type is declared.
8076 @code{Container_Checks} Can be used to suppress all checks within Ada.Containers
8077 and instances of its children, including Tampering_Check.
8080 @code{Tampering_Check} Can be used to suppress tampering check in the containers.
8083 @code{Predicate_Check} can be used to control whether predicate checks are
8084 active. It is applicable only to predicates for which the policy is
8085 @code{Check}. Unlike @code{Assertion_Policy}, which determines if a given
8086 predicate is ignored or checked for the whole program, the use of
8087 @code{Suppress} and @code{Unsuppress} with this check name allows a given
8088 predicate to be turned on and off at specific points in the program.
8091 @code{Validity_Check} can be used specifically to control validity checks.
8092 If @code{Suppress} is used to suppress validity checks, then no validity
8093 checks are performed, including those specified by the appropriate compiler
8094 switch or the @code{Validity_Checks} pragma.
8097 Additional check names previously introduced by use of the @code{Check_Name}
8098 pragma are also allowed.
8101 Note that pragma Suppress gives the compiler permission to omit
8102 checks, but does not require the compiler to omit checks. The compiler
8103 will generate checks if they are essentially free, even when they are
8104 suppressed. In particular, if the compiler can prove that a certain
8105 check will necessarily fail, it will generate code to do an
8106 unconditional 'raise', even if checks are suppressed. The compiler
8109 Of course, run-time checks are omitted whenever the compiler can prove
8110 that they will not fail, whether or not checks are suppressed.
8112 @node Pragma Suppress_All,Pragma Suppress_Debug_Info,Pragma Suppress,Implementation Defined Pragmas
8113 @anchor{gnat_rm/implementation_defined_pragmas pragma-suppress-all}@anchor{f7}
8114 @section Pragma Suppress_All
8120 pragma Suppress_All;
8123 This pragma can appear anywhere within a unit.
8124 The effect is to apply @code{Suppress (All_Checks)} to the unit
8125 in which it appears. This pragma is implemented for compatibility with DEC
8126 Ada 83 usage where it appears at the end of a unit, and for compatibility
8127 with Rational Ada, where it appears as a program unit pragma.
8128 The use of the standard Ada pragma @code{Suppress (All_Checks)}
8129 as a normal configuration pragma is the preferred usage in GNAT.
8131 @node Pragma Suppress_Debug_Info,Pragma Suppress_Exception_Locations,Pragma Suppress_All,Implementation Defined Pragmas
8132 @anchor{gnat_rm/implementation_defined_pragmas pragma-suppress-debug-info}@anchor{f8}@anchor{gnat_rm/implementation_defined_pragmas id43}@anchor{f9}
8133 @section Pragma Suppress_Debug_Info
8139 pragma Suppress_Debug_Info ([Entity =>] LOCAL_NAME);
8142 This pragma can be used to suppress generation of debug information
8143 for the specified entity. It is intended primarily for use in debugging
8144 the debugger, and navigating around debugger problems.
8146 @node Pragma Suppress_Exception_Locations,Pragma Suppress_Initialization,Pragma Suppress_Debug_Info,Implementation Defined Pragmas
8147 @anchor{gnat_rm/implementation_defined_pragmas pragma-suppress-exception-locations}@anchor{fa}
8148 @section Pragma Suppress_Exception_Locations
8154 pragma Suppress_Exception_Locations;
8157 In normal mode, a raise statement for an exception by default generates
8158 an exception message giving the file name and line number for the location
8159 of the raise. This is useful for debugging and logging purposes, but this
8160 entails extra space for the strings for the messages. The configuration
8161 pragma @code{Suppress_Exception_Locations} can be used to suppress the
8162 generation of these strings, with the result that space is saved, but the
8163 exception message for such raises is null. This configuration pragma may
8164 appear in a global configuration pragma file, or in a specific unit as
8165 usual. It is not required that this pragma be used consistently within
8166 a partition, so it is fine to have some units within a partition compiled
8167 with this pragma and others compiled in normal mode without it.
8169 @node Pragma Suppress_Initialization,Pragma Task_Name,Pragma Suppress_Exception_Locations,Implementation Defined Pragmas
8170 @anchor{gnat_rm/implementation_defined_pragmas id44}@anchor{fb}@anchor{gnat_rm/implementation_defined_pragmas pragma-suppress-initialization}@anchor{fc}
8171 @section Pragma Suppress_Initialization
8174 @geindex Suppressing initialization
8176 @geindex Initialization
8177 @geindex suppression of
8182 pragma Suppress_Initialization ([Entity =>] variable_or_subtype_Name);
8185 Here variable_or_subtype_Name is the name introduced by a type declaration
8186 or subtype declaration or the name of a variable introduced by an
8189 In the case of a type or subtype
8190 this pragma suppresses any implicit or explicit initialization
8191 for all variables of the given type or subtype,
8192 including initialization resulting from the use of pragmas
8193 Normalize_Scalars or Initialize_Scalars.
8195 This is considered a representation item, so it cannot be given after
8196 the type is frozen. It applies to all subsequent object declarations,
8197 and also any allocator that creates objects of the type.
8199 If the pragma is given for the first subtype, then it is considered
8200 to apply to the base type and all its subtypes. If the pragma is given
8201 for other than a first subtype, then it applies only to the given subtype.
8202 The pragma may not be given after the type is frozen.
8204 Note that this includes eliminating initialization of discriminants
8205 for discriminated types, and tags for tagged types. In these cases,
8206 you will have to use some non-portable mechanism (e.g. address
8207 overlays or unchecked conversion) to achieve required initialization
8208 of these fields before accessing any object of the corresponding type.
8210 For the variable case, implicit initialization for the named variable
8211 is suppressed, just as though its subtype had been given in a pragma
8212 Suppress_Initialization, as described above.
8214 @node Pragma Task_Name,Pragma Task_Storage,Pragma Suppress_Initialization,Implementation Defined Pragmas
8215 @anchor{gnat_rm/implementation_defined_pragmas pragma-task-name}@anchor{fd}
8216 @section Pragma Task_Name
8222 pragma Task_Name (string_EXPRESSION);
8225 This pragma appears within a task definition (like pragma
8226 @code{Priority}) and applies to the task in which it appears. The
8227 argument must be of type String, and provides a name to be used for
8228 the task instance when the task is created. Note that this expression
8229 is not required to be static, and in particular, it can contain
8230 references to task discriminants. This facility can be used to
8231 provide different names for different tasks as they are created,
8232 as illustrated in the example below.
8234 The task name is recorded internally in the run-time structures
8235 and is accessible to tools like the debugger. In addition the
8236 routine @code{Ada.Task_Identification.Image} will return this
8237 string, with a unique task address appended.
8240 -- Example of the use of pragma Task_Name
8242 with Ada.Task_Identification;
8243 use Ada.Task_Identification;
8244 with Text_IO; use Text_IO;
8247 type Astring is access String;
8249 task type Task_Typ (Name : access String) is
8250 pragma Task_Name (Name.all);
8253 task body Task_Typ is
8254 Nam : constant String := Image (Current_Task);
8256 Put_Line ("-->" & Nam (1 .. 14) & "<--");
8259 type Ptr_Task is access Task_Typ;
8260 Task_Var : Ptr_Task;
8264 new Task_Typ (new String'("This is task 1"));
8266 new Task_Typ (new String'("This is task 2"));
8270 @node Pragma Task_Storage,Pragma Test_Case,Pragma Task_Name,Implementation Defined Pragmas
8271 @anchor{gnat_rm/implementation_defined_pragmas pragma-task-storage}@anchor{fe}
8272 @section Pragma Task_Storage
8278 pragma Task_Storage (
8279 [Task_Type =>] LOCAL_NAME,
8280 [Top_Guard =>] static_integer_EXPRESSION);
8283 This pragma specifies the length of the guard area for tasks. The guard
8284 area is an additional storage area allocated to a task. A value of zero
8285 means that either no guard area is created or a minimal guard area is
8286 created, depending on the target. This pragma can appear anywhere a
8287 @code{Storage_Size} attribute definition clause is allowed for a task
8290 @node Pragma Test_Case,Pragma Thread_Local_Storage,Pragma Task_Storage,Implementation Defined Pragmas
8291 @anchor{gnat_rm/implementation_defined_pragmas pragma-test-case}@anchor{ff}@anchor{gnat_rm/implementation_defined_pragmas id45}@anchor{100}
8292 @section Pragma Test_Case
8301 [Name =>] static_string_Expression
8302 ,[Mode =>] (Nominal | Robustness)
8303 [, Requires => Boolean_Expression]
8304 [, Ensures => Boolean_Expression]);
8307 The @code{Test_Case} pragma allows defining fine-grain specifications
8308 for use by testing tools.
8309 The compiler checks the validity of the @code{Test_Case} pragma, but its
8310 presence does not lead to any modification of the code generated by the
8313 @code{Test_Case} pragmas may only appear immediately following the
8314 (separate) declaration of a subprogram in a package declaration, inside
8315 a package spec unit. Only other pragmas may intervene (that is appear
8316 between the subprogram declaration and a test case).
8318 The compiler checks that boolean expressions given in @code{Requires} and
8319 @code{Ensures} are valid, where the rules for @code{Requires} are the
8320 same as the rule for an expression in @code{Precondition} and the rules
8321 for @code{Ensures} are the same as the rule for an expression in
8322 @code{Postcondition}. In particular, attributes @code{'Old} and
8323 @code{'Result} can only be used within the @code{Ensures}
8324 expression. The following is an example of use within a package spec:
8327 package Math_Functions is
8329 function Sqrt (Arg : Float) return Float;
8330 pragma Test_Case (Name => "Test 1",
8332 Requires => Arg < 10000,
8333 Ensures => Sqrt'Result < 10);
8338 The meaning of a test case is that there is at least one context where
8339 @code{Requires} holds such that, if the associated subprogram is executed in
8340 that context, then @code{Ensures} holds when the subprogram returns.
8341 Mode @code{Nominal} indicates that the input context should also satisfy the
8342 precondition of the subprogram, and the output context should also satisfy its
8343 postcondition. Mode @code{Robustness} indicates that the precondition and
8344 postcondition of the subprogram should be ignored for this test case.
8346 @node Pragma Thread_Local_Storage,Pragma Time_Slice,Pragma Test_Case,Implementation Defined Pragmas
8347 @anchor{gnat_rm/implementation_defined_pragmas pragma-thread-local-storage}@anchor{101}@anchor{gnat_rm/implementation_defined_pragmas id46}@anchor{102}
8348 @section Pragma Thread_Local_Storage
8351 @geindex Task specific storage
8353 @geindex TLS (Thread Local Storage)
8355 @geindex Task_Attributes
8360 pragma Thread_Local_Storage ([Entity =>] LOCAL_NAME);
8363 This pragma specifies that the specified entity, which must be
8364 a variable declared in a library-level package, is to be marked as
8365 "Thread Local Storage" (@code{TLS}). On systems supporting this (which
8366 include Windows, Solaris, GNU/Linux, and VxWorks 6), this causes each
8367 thread (and hence each Ada task) to see a distinct copy of the variable.
8369 The variable must not have default initialization, and if there is
8370 an explicit initialization, it must be either @code{null} for an
8371 access variable, a static expression for a scalar variable, or a fully
8372 static aggregate for a composite type, that is to say, an aggregate all
8373 of whose components are static, and which does not include packed or
8374 discriminated components.
8376 This provides a low-level mechanism similar to that provided by
8377 the @code{Ada.Task_Attributes} package, but much more efficient
8378 and is also useful in writing interface code that will interact
8379 with foreign threads.
8381 If this pragma is used on a system where @code{TLS} is not supported,
8382 then an error message will be generated and the program will be rejected.
8384 @node Pragma Time_Slice,Pragma Title,Pragma Thread_Local_Storage,Implementation Defined Pragmas
8385 @anchor{gnat_rm/implementation_defined_pragmas pragma-time-slice}@anchor{103}
8386 @section Pragma Time_Slice
8392 pragma Time_Slice (static_duration_EXPRESSION);
8395 For implementations of GNAT on operating systems where it is possible
8396 to supply a time slice value, this pragma may be used for this purpose.
8397 It is ignored if it is used in a system that does not allow this control,
8398 or if it appears in other than the main program unit.
8400 @node Pragma Title,Pragma Type_Invariant,Pragma Time_Slice,Implementation Defined Pragmas
8401 @anchor{gnat_rm/implementation_defined_pragmas pragma-title}@anchor{104}
8402 @section Pragma Title
8408 pragma Title (TITLING_OPTION [, TITLING OPTION]);
8411 [Title =>] STRING_LITERAL,
8412 | [Subtitle =>] STRING_LITERAL
8415 Syntax checked but otherwise ignored by GNAT. This is a listing control
8416 pragma used in DEC Ada 83 implementations to provide a title and/or
8417 subtitle for the program listing. The program listing generated by GNAT
8418 does not have titles or subtitles.
8420 Unlike other pragmas, the full flexibility of named notation is allowed
8421 for this pragma, i.e., the parameters may be given in any order if named
8422 notation is used, and named and positional notation can be mixed
8423 following the normal rules for procedure calls in Ada.
8425 @node Pragma Type_Invariant,Pragma Type_Invariant_Class,Pragma Title,Implementation Defined Pragmas
8426 @anchor{gnat_rm/implementation_defined_pragmas pragma-type-invariant}@anchor{105}
8427 @section Pragma Type_Invariant
8433 pragma Type_Invariant
8434 ([Entity =>] type_LOCAL_NAME,
8435 [Check =>] EXPRESSION);
8438 The @code{Type_Invariant} pragma is intended to be an exact
8439 replacement for the language-defined @code{Type_Invariant}
8440 aspect, and shares its restrictions and semantics. It differs
8441 from the language defined @code{Invariant} pragma in that it
8442 does not permit a string parameter, and it is
8443 controlled by the assertion identifier @code{Type_Invariant}
8444 rather than @code{Invariant}.
8446 @node Pragma Type_Invariant_Class,Pragma Unchecked_Union,Pragma Type_Invariant,Implementation Defined Pragmas
8447 @anchor{gnat_rm/implementation_defined_pragmas id47}@anchor{106}@anchor{gnat_rm/implementation_defined_pragmas pragma-type-invariant-class}@anchor{107}
8448 @section Pragma Type_Invariant_Class
8454 pragma Type_Invariant_Class
8455 ([Entity =>] type_LOCAL_NAME,
8456 [Check =>] EXPRESSION);
8459 The @code{Type_Invariant_Class} pragma is intended to be an exact
8460 replacement for the language-defined @code{Type_Invariant'Class}
8461 aspect, and shares its restrictions and semantics.
8463 Note: This pragma is called @code{Type_Invariant_Class} rather than
8464 @code{Type_Invariant'Class} because the latter would not be strictly
8465 conforming to the allowed syntax for pragmas. The motivation
8466 for providing pragmas equivalent to the aspects is to allow a program
8467 to be written using the pragmas, and then compiled if necessary
8468 using an Ada compiler that does not recognize the pragmas or
8469 aspects, but is prepared to ignore the pragmas. The assertion
8470 policy that controls this pragma is @code{Type_Invariant'Class},
8471 not @code{Type_Invariant_Class}.
8473 @node Pragma Unchecked_Union,Pragma Unevaluated_Use_Of_Old,Pragma Type_Invariant_Class,Implementation Defined Pragmas
8474 @anchor{gnat_rm/implementation_defined_pragmas pragma-unchecked-union}@anchor{108}
8475 @section Pragma Unchecked_Union
8478 @geindex Unions in C
8483 pragma Unchecked_Union (first_subtype_LOCAL_NAME);
8486 This pragma is used to specify a representation of a record type that is
8487 equivalent to a C union. It was introduced as a GNAT implementation defined
8488 pragma in the GNAT Ada 95 mode. Ada 2005 includes an extended version of this
8489 pragma, making it language defined, and GNAT fully implements this extended
8490 version in all language modes (Ada 83, Ada 95, and Ada 2005). For full
8491 details, consult the Ada 2012 Reference Manual, section B.3.3.
8493 @node Pragma Unevaluated_Use_Of_Old,Pragma Unimplemented_Unit,Pragma Unchecked_Union,Implementation Defined Pragmas
8494 @anchor{gnat_rm/implementation_defined_pragmas pragma-unevaluated-use-of-old}@anchor{109}
8495 @section Pragma Unevaluated_Use_Of_Old
8498 @geindex Attribute Old
8500 @geindex Attribute Loop_Entry
8502 @geindex Unevaluated_Use_Of_Old
8507 pragma Unevaluated_Use_Of_Old (Error | Warn | Allow);
8510 This pragma controls the processing of attributes Old and Loop_Entry.
8511 If either of these attributes is used in a potentially unevaluated
8512 expression (e.g. the then or else parts of an if expression), then
8513 normally this usage is considered illegal if the prefix of the attribute
8514 is other than an entity name. The language requires this
8515 behavior for Old, and GNAT copies the same rule for Loop_Entry.
8517 The reason for this rule is that otherwise, we can have a situation
8518 where we save the Old value, and this results in an exception, even
8519 though we might not evaluate the attribute. Consider this example:
8522 package UnevalOld is
8524 procedure U (A : String; C : Boolean) -- ERROR
8525 with Post => (if C then A(1)'Old = K else True);
8529 If procedure U is called with a string with a lower bound of 2, and
8530 C false, then an exception would be raised trying to evaluate A(1)
8531 on entry even though the value would not be actually used.
8533 Although the rule guarantees against this possibility, it is sometimes
8534 too restrictive. For example if we know that the string has a lower
8535 bound of 1, then we will never raise an exception.
8536 The pragma @code{Unevaluated_Use_Of_Old} can be
8537 used to modify this behavior. If the argument is @code{Error} then an
8538 error is given (this is the default RM behavior). If the argument is
8539 @code{Warn} then the usage is allowed as legal but with a warning
8540 that an exception might be raised. If the argument is @code{Allow}
8541 then the usage is allowed as legal without generating a warning.
8543 This pragma may appear as a configuration pragma, or in a declarative
8544 part or package specification. In the latter case it applies to
8545 uses up to the end of the corresponding statement sequence or
8546 sequence of package declarations.
8548 @node Pragma Unimplemented_Unit,Pragma Universal_Aliasing,Pragma Unevaluated_Use_Of_Old,Implementation Defined Pragmas
8549 @anchor{gnat_rm/implementation_defined_pragmas pragma-unimplemented-unit}@anchor{10a}
8550 @section Pragma Unimplemented_Unit
8556 pragma Unimplemented_Unit;
8559 If this pragma occurs in a unit that is processed by the compiler, GNAT
8560 aborts with the message @code{xxx not implemented}, where
8561 @code{xxx} is the name of the current compilation unit. This pragma is
8562 intended to allow the compiler to handle unimplemented library units in
8565 The abort only happens if code is being generated. Thus you can use
8566 specs of unimplemented packages in syntax or semantic checking mode.
8568 @node Pragma Universal_Aliasing,Pragma Universal_Data,Pragma Unimplemented_Unit,Implementation Defined Pragmas
8569 @anchor{gnat_rm/implementation_defined_pragmas pragma-universal-aliasing}@anchor{10b}@anchor{gnat_rm/implementation_defined_pragmas id48}@anchor{10c}
8570 @section Pragma Universal_Aliasing
8576 pragma Universal_Aliasing [([Entity =>] type_LOCAL_NAME)];
8579 @code{type_LOCAL_NAME} must refer to a type declaration in the current
8580 declarative part. The effect is to inhibit strict type-based aliasing
8581 optimization for the given type. In other words, the effect is as though
8582 access types designating this type were subject to pragma No_Strict_Aliasing.
8583 For a detailed description of the strict aliasing optimization, and the
8584 situations in which it must be suppressed, see the section on
8585 @code{Optimization and Strict Aliasing} in the @cite{GNAT User's Guide}.
8587 @node Pragma Universal_Data,Pragma Unmodified,Pragma Universal_Aliasing,Implementation Defined Pragmas
8588 @anchor{gnat_rm/implementation_defined_pragmas pragma-universal-data}@anchor{10d}@anchor{gnat_rm/implementation_defined_pragmas id49}@anchor{10e}
8589 @section Pragma Universal_Data
8595 pragma Universal_Data [(library_unit_Name)];
8598 This pragma is supported only for the AAMP target and is ignored for
8599 other targets. The pragma specifies that all library-level objects
8600 (Counter 0 data) associated with the library unit are to be accessed
8601 and updated using universal addressing (24-bit addresses for AAMP5)
8602 rather than the default of 16-bit Data Environment (DENV) addressing.
8603 Use of this pragma will generally result in less efficient code for
8604 references to global data associated with the library unit, but
8605 allows such data to be located anywhere in memory. This pragma is
8606 a library unit pragma, but can also be used as a configuration pragma
8607 (including use in the @code{gnat.adc} file). The functionality
8608 of this pragma is also available by applying the -univ switch on the
8609 compilations of units where universal addressing of the data is desired.
8611 @node Pragma Unmodified,Pragma Unreferenced,Pragma Universal_Data,Implementation Defined Pragmas
8612 @anchor{gnat_rm/implementation_defined_pragmas id50}@anchor{10f}@anchor{gnat_rm/implementation_defined_pragmas pragma-unmodified}@anchor{110}
8613 @section Pragma Unmodified
8622 pragma Unmodified (LOCAL_NAME @{, LOCAL_NAME@});
8625 This pragma signals that the assignable entities (variables,
8626 @code{out} parameters, @code{in out} parameters) whose names are listed are
8627 deliberately not assigned in the current source unit. This
8628 suppresses warnings about the
8629 entities being referenced but not assigned, and in addition a warning will be
8630 generated if one of these entities is in fact assigned in the
8631 same unit as the pragma (or in the corresponding body, or one
8634 This is particularly useful for clearly signaling that a particular
8635 parameter is not modified, even though the spec suggests that it might
8638 For the variable case, warnings are never given for unreferenced variables
8639 whose name contains one of the substrings
8640 @code{DISCARD, DUMMY, IGNORE, JUNK, UNUSED} in any casing. Such names
8641 are typically to be used in cases where such warnings are expected.
8642 Thus it is never necessary to use @code{pragma Unmodified} for such
8643 variables, though it is harmless to do so.
8645 @node Pragma Unreferenced,Pragma Unreferenced_Objects,Pragma Unmodified,Implementation Defined Pragmas
8646 @anchor{gnat_rm/implementation_defined_pragmas pragma-unreferenced}@anchor{111}@anchor{gnat_rm/implementation_defined_pragmas id51}@anchor{112}
8647 @section Pragma Unreferenced
8651 @geindex unreferenced
8656 pragma Unreferenced (LOCAL_NAME @{, LOCAL_NAME@});
8657 pragma Unreferenced (library_unit_NAME @{, library_unit_NAME@});
8660 This pragma signals that the entities whose names are listed are
8661 deliberately not referenced in the current source unit after the
8662 occurrence of the pragma. This
8663 suppresses warnings about the
8664 entities being unreferenced, and in addition a warning will be
8665 generated if one of these entities is in fact subsequently referenced in the
8666 same unit as the pragma (or in the corresponding body, or one
8669 This is particularly useful for clearly signaling that a particular
8670 parameter is not referenced in some particular subprogram implementation
8671 and that this is deliberate. It can also be useful in the case of
8672 objects declared only for their initialization or finalization side
8675 If @code{LOCAL_NAME} identifies more than one matching homonym in the
8676 current scope, then the entity most recently declared is the one to which
8677 the pragma applies. Note that in the case of accept formals, the pragma
8678 Unreferenced may appear immediately after the keyword @code{do} which
8679 allows the indication of whether or not accept formals are referenced
8680 or not to be given individually for each accept statement.
8682 The left hand side of an assignment does not count as a reference for the
8683 purpose of this pragma. Thus it is fine to assign to an entity for which
8684 pragma Unreferenced is given.
8686 Note that if a warning is desired for all calls to a given subprogram,
8687 regardless of whether they occur in the same unit as the subprogram
8688 declaration, then this pragma should not be used (calls from another
8689 unit would not be flagged); pragma Obsolescent can be used instead
8690 for this purpose, see @ref{b0,,Pragma Obsolescent}.
8692 The second form of pragma @code{Unreferenced} is used within a context
8693 clause. In this case the arguments must be unit names of units previously
8694 mentioned in @code{with} clauses (similar to the usage of pragma
8695 @code{Elaborate_All}. The effect is to suppress warnings about unreferenced
8696 units and unreferenced entities within these units.
8698 For the variable case, warnings are never given for unreferenced variables
8699 whose name contains one of the substrings
8700 @code{DISCARD, DUMMY, IGNORE, JUNK, UNUSED} in any casing. Such names
8701 are typically to be used in cases where such warnings are expected.
8702 Thus it is never necessary to use @code{pragma Unreferenced} for such
8703 variables, though it is harmless to do so.
8705 @node Pragma Unreferenced_Objects,Pragma Unreserve_All_Interrupts,Pragma Unreferenced,Implementation Defined Pragmas
8706 @anchor{gnat_rm/implementation_defined_pragmas pragma-unreferenced-objects}@anchor{113}@anchor{gnat_rm/implementation_defined_pragmas id52}@anchor{114}
8707 @section Pragma Unreferenced_Objects
8711 @geindex unreferenced
8716 pragma Unreferenced_Objects (local_subtype_NAME @{, local_subtype_NAME@});
8719 This pragma signals that for the types or subtypes whose names are
8720 listed, objects which are declared with one of these types or subtypes may
8721 not be referenced, and if no references appear, no warnings are given.
8723 This is particularly useful for objects which are declared solely for their
8724 initialization and finalization effect. Such variables are sometimes referred
8725 to as RAII variables (Resource Acquisition Is Initialization). Using this
8726 pragma on the relevant type (most typically a limited controlled type), the
8727 compiler will automatically suppress unwanted warnings about these variables
8728 not being referenced.
8730 @node Pragma Unreserve_All_Interrupts,Pragma Unsuppress,Pragma Unreferenced_Objects,Implementation Defined Pragmas
8731 @anchor{gnat_rm/implementation_defined_pragmas pragma-unreserve-all-interrupts}@anchor{115}
8732 @section Pragma Unreserve_All_Interrupts
8738 pragma Unreserve_All_Interrupts;
8741 Normally certain interrupts are reserved to the implementation. Any attempt
8742 to attach an interrupt causes Program_Error to be raised, as described in
8743 RM C.3.2(22). A typical example is the @code{SIGINT} interrupt used in
8744 many systems for a @code{Ctrl-C} interrupt. Normally this interrupt is
8745 reserved to the implementation, so that @code{Ctrl-C} can be used to
8746 interrupt execution.
8748 If the pragma @code{Unreserve_All_Interrupts} appears anywhere in any unit in
8749 a program, then all such interrupts are unreserved. This allows the
8750 program to handle these interrupts, but disables their standard
8751 functions. For example, if this pragma is used, then pressing
8752 @code{Ctrl-C} will not automatically interrupt execution. However,
8753 a program can then handle the @code{SIGINT} interrupt as it chooses.
8755 For a full list of the interrupts handled in a specific implementation,
8756 see the source code for the spec of @code{Ada.Interrupts.Names} in
8757 file @code{a-intnam.ads}. This is a target dependent file that contains the
8758 list of interrupts recognized for a given target. The documentation in
8759 this file also specifies what interrupts are affected by the use of
8760 the @code{Unreserve_All_Interrupts} pragma.
8762 For a more general facility for controlling what interrupts can be
8763 handled, see pragma @code{Interrupt_State}, which subsumes the functionality
8764 of the @code{Unreserve_All_Interrupts} pragma.
8766 @node Pragma Unsuppress,Pragma Use_VADS_Size,Pragma Unreserve_All_Interrupts,Implementation Defined Pragmas
8767 @anchor{gnat_rm/implementation_defined_pragmas pragma-unsuppress}@anchor{116}
8768 @section Pragma Unsuppress
8774 pragma Unsuppress (IDENTIFIER [, [On =>] NAME]);
8777 This pragma undoes the effect of a previous pragma @code{Suppress}. If
8778 there is no corresponding pragma @code{Suppress} in effect, it has no
8779 effect. The range of the effect is the same as for pragma
8780 @code{Suppress}. The meaning of the arguments is identical to that used
8781 in pragma @code{Suppress}.
8783 One important application is to ensure that checks are on in cases where
8784 code depends on the checks for its correct functioning, so that the code
8785 will compile correctly even if the compiler switches are set to suppress
8786 checks. For example, in a program that depends on external names of tagged
8787 types and wants to ensure that the duplicated tag check occurs even if all
8788 run-time checks are suppressed by a compiler switch, the following
8789 configuration pragma will ensure this test is not suppressed:
8792 pragma Unsuppress (Duplicated_Tag_Check);
8795 This pragma is standard in Ada 2005. It is available in all earlier versions
8796 of Ada as an implementation-defined pragma.
8798 Note that in addition to the checks defined in the Ada RM, GNAT recogizes a
8799 number of implementation-defined check names. See the description of pragma
8800 @code{Suppress} for full details.
8802 @node Pragma Use_VADS_Size,Pragma Unused,Pragma Unsuppress,Implementation Defined Pragmas
8803 @anchor{gnat_rm/implementation_defined_pragmas pragma-use-vads-size}@anchor{117}
8804 @section Pragma Use_VADS_Size
8808 @geindex VADS compatibility
8810 @geindex Rational profile
8815 pragma Use_VADS_Size;
8818 This is a configuration pragma. In a unit to which it applies, any use
8819 of the 'Size attribute is automatically interpreted as a use of the
8820 'VADS_Size attribute. Note that this may result in incorrect semantic
8821 processing of valid Ada 95 or Ada 2005 programs. This is intended to aid in
8822 the handling of existing code which depends on the interpretation of Size
8823 as implemented in the VADS compiler. See description of the VADS_Size
8824 attribute for further details.
8826 @node Pragma Unused,Pragma Validity_Checks,Pragma Use_VADS_Size,Implementation Defined Pragmas
8827 @anchor{gnat_rm/implementation_defined_pragmas pragma-unused}@anchor{118}@anchor{gnat_rm/implementation_defined_pragmas id53}@anchor{119}
8828 @section Pragma Unused
8837 pragma Unused (LOCAL_NAME @{, LOCAL_NAME@});
8840 This pragma signals that the assignable entities (variables,
8841 @code{out} parameters, and @code{in out} parameters) whose names are listed
8842 deliberately do not get assigned or referenced in the current source unit
8843 after the occurrence of the pragma in the current source unit. This
8844 suppresses warnings about the entities that are unreferenced and/or not
8845 assigned, and, in addition, a warning will be generated if one of these
8846 entities gets assigned or subsequently referenced in the same unit as the
8847 pragma (in the corresponding body or one of its subunits).
8849 This is particularly useful for clearly signaling that a particular
8850 parameter is not modified or referenced, even though the spec suggests
8853 For the variable case, warnings are never given for unreferenced
8854 variables whose name contains one of the substrings
8855 @code{DISCARD, DUMMY, IGNORE, JUNK, UNUSED} in any casing. Such names
8856 are typically to be used in cases where such warnings are expected.
8857 Thus it is never necessary to use @code{pragma Unmodified} for such
8858 variables, though it is harmless to do so.
8860 @node Pragma Validity_Checks,Pragma Volatile,Pragma Unused,Implementation Defined Pragmas
8861 @anchor{gnat_rm/implementation_defined_pragmas pragma-validity-checks}@anchor{11a}
8862 @section Pragma Validity_Checks
8868 pragma Validity_Checks (string_LITERAL | ALL_CHECKS | On | Off);
8871 This pragma is used in conjunction with compiler switches to control the
8872 built-in validity checking provided by GNAT. The compiler switches, if set
8873 provide an initial setting for the switches, and this pragma may be used
8874 to modify these settings, or the settings may be provided entirely by
8875 the use of the pragma. This pragma can be used anywhere that a pragma
8876 is legal, including use as a configuration pragma (including use in
8877 the @code{gnat.adc} file).
8879 The form with a string literal specifies which validity options are to be
8880 activated. The validity checks are first set to include only the default
8881 reference manual settings, and then a string of letters in the string
8882 specifies the exact set of options required. The form of this string
8883 is exactly as described for the @emph{-gnatVx} compiler switch (see the
8884 GNAT User's Guide for details). For example the following two
8885 methods can be used to enable validity checking for mode @code{in} and
8886 @code{in out} subprogram parameters:
8893 pragma Validity_Checks ("im");
8898 $ gcc -c -gnatVim ...
8902 The form ALL_CHECKS activates all standard checks (its use is equivalent
8903 to the use of the @code{gnatVa} switch).
8905 The forms with @code{Off} and @code{On} can be used to temporarily disable
8906 validity checks as shown in the following example:
8909 pragma Validity_Checks ("c"); -- validity checks for copies
8910 pragma Validity_Checks (Off); -- turn off validity checks
8911 A := B; -- B will not be validity checked
8912 pragma Validity_Checks (On); -- turn validity checks back on
8913 A := C; -- C will be validity checked
8916 @node Pragma Volatile,Pragma Volatile_Full_Access,Pragma Validity_Checks,Implementation Defined Pragmas
8917 @anchor{gnat_rm/implementation_defined_pragmas id54}@anchor{11b}@anchor{gnat_rm/implementation_defined_pragmas pragma-volatile}@anchor{11c}
8918 @section Pragma Volatile
8924 pragma Volatile (LOCAL_NAME);
8927 This pragma is defined by the Ada Reference Manual, and the GNAT
8928 implementation is fully conformant with this definition. The reason it
8929 is mentioned in this section is that a pragma of the same name was supplied
8930 in some Ada 83 compilers, including DEC Ada 83. The Ada 95 / Ada 2005
8931 implementation of pragma Volatile is upwards compatible with the
8932 implementation in DEC Ada 83.
8934 @node Pragma Volatile_Full_Access,Pragma Volatile_Function,Pragma Volatile,Implementation Defined Pragmas
8935 @anchor{gnat_rm/implementation_defined_pragmas id55}@anchor{11d}@anchor{gnat_rm/implementation_defined_pragmas pragma-volatile-full-access}@anchor{11e}
8936 @section Pragma Volatile_Full_Access
8942 pragma Volatile_Full_Access (LOCAL_NAME);
8945 This is similar in effect to pragma Volatile, except that any reference to the
8946 object is guaranteed to be done only with instructions that read or write all
8947 the bits of the object. Furthermore, if the object is of a composite type,
8948 then any reference to a component of the object is guaranteed to read and/or
8949 write all the bits of the object.
8951 The intention is that this be suitable for use with memory-mapped I/O devices
8952 on some machines. Note that there are two important respects in which this is
8953 different from @code{pragma Atomic}. First a reference to a @code{Volatile_Full_Access}
8954 object is not a sequential action in the RM 9.10 sense and, therefore, does
8955 not create a synchronization point. Second, in the case of @code{pragma Atomic},
8956 there is no guarantee that all the bits will be accessed if the reference
8957 is not to the whole object; the compiler is allowed (and generally will)
8958 access only part of the object in this case.
8960 It is not permissible to specify @code{Atomic} and @code{Volatile_Full_Access} for
8963 It is not permissible to specify @code{Volatile_Full_Access} for a composite
8964 (record or array) type or object that has at least one @code{Aliased} component.
8966 @node Pragma Volatile_Function,Pragma Warning_As_Error,Pragma Volatile_Full_Access,Implementation Defined Pragmas
8967 @anchor{gnat_rm/implementation_defined_pragmas id56}@anchor{11f}@anchor{gnat_rm/implementation_defined_pragmas pragma-volatile-function}@anchor{120}
8968 @section Pragma Volatile_Function
8974 pragma Volatile_Function [ (boolean_EXPRESSION) ];
8977 For the semantics of this pragma, see the entry for aspect @code{Volatile_Function}
8978 in the SPARK 2014 Reference Manual, section 7.1.2.
8980 @node Pragma Warning_As_Error,Pragma Warnings,Pragma Volatile_Function,Implementation Defined Pragmas
8981 @anchor{gnat_rm/implementation_defined_pragmas pragma-warning-as-error}@anchor{121}
8982 @section Pragma Warning_As_Error
8988 pragma Warning_As_Error (static_string_EXPRESSION);
8991 This configuration pragma allows the programmer to specify a set
8992 of warnings that will be treated as errors. Any warning that
8993 matches the pattern given by the pragma argument will be treated
8994 as an error. This gives more precise control than -gnatwe,
8995 which treats warnings as errors.
8997 This pragma can apply to regular warnings (messages enabled by -gnatw)
8998 and to style warnings (messages that start with "(style)",
9001 The pattern may contain asterisks, which match zero or more characters
9002 in the message. For example, you can use @code{pragma Warning_As_Error
9003 ("bits of*unused")} to treat the warning message @code{warning: 960 bits of
9004 "a" unused} as an error. All characters other than asterisk are treated
9005 as literal characters in the match. The match is case insensitive; for
9006 example XYZ matches xyz.
9008 Note that the pattern matches if it occurs anywhere within the warning
9009 message string (it is not necessary to put an asterisk at the start and
9010 the end of the message, since this is implied).
9012 Another possibility for the static_string_EXPRESSION which works whether
9013 or not error tags are enabled (@emph{-gnatw.d}) is to use the
9014 @emph{-gnatw} tag string, enclosed in brackets,
9015 as shown in the example below, to treat a class of warnings as errors.
9017 The above use of patterns to match the message applies only to warning
9018 messages generated by the front end. This pragma can also be applied to
9019 warnings provided by the back end and mentioned in @ref{122,,Pragma Warnings}.
9020 By using a single full @emph{-Wxxx} switch in the pragma, such warnings
9021 can also be treated as errors.
9023 The pragma can appear either in a global configuration pragma file
9024 (e.g. @code{gnat.adc}), or at the start of a file. Given a global
9025 configuration pragma file containing:
9028 pragma Warning_As_Error ("[-gnatwj]");
9031 which will treat all obsolescent feature warnings as errors, the
9032 following program compiles as shown (compile options here are
9033 @emph{-gnatwa.d -gnatl -gnatj55}).
9036 1. pragma Warning_As_Error ("*never assigned*");
9037 2. function Warnerr return String is
9040 >>> error: variable "X" is never read and
9041 never assigned [-gnatwv] [warning-as-error]
9045 >>> warning: variable "Y" is assigned but
9046 never read [-gnatwu]
9052 >>> error: use of "%" is an obsolescent
9053 feature (RM J.2(4)), use """ instead
9054 [-gnatwj] [warning-as-error]
9058 8 lines: No errors, 3 warnings (2 treated as errors)
9061 Note that this pragma does not affect the set of warnings issued in
9062 any way, it merely changes the effect of a matching warning if one
9063 is produced as a result of other warnings options. As shown in this
9064 example, if the pragma results in a warning being treated as an error,
9065 the tag is changed from "warning:" to "error:" and the string
9066 "[warning-as-error]" is appended to the end of the message.
9068 @node Pragma Warnings,Pragma Weak_External,Pragma Warning_As_Error,Implementation Defined Pragmas
9069 @anchor{gnat_rm/implementation_defined_pragmas id57}@anchor{123}@anchor{gnat_rm/implementation_defined_pragmas pragma-warnings}@anchor{122}
9070 @section Pragma Warnings
9076 pragma Warnings ([TOOL_NAME,] DETAILS [, REASON]);
9078 DETAILS ::= On | Off
9079 DETAILS ::= On | Off, local_NAME
9080 DETAILS ::= static_string_EXPRESSION
9081 DETAILS ::= On | Off, static_string_EXPRESSION
9083 TOOL_NAME ::= GNAT | GNATProve
9085 REASON ::= Reason => STRING_LITERAL @{& STRING_LITERAL@}
9088 Note: in Ada 83 mode, a string literal may be used in place of a static string
9089 expression (which does not exist in Ada 83).
9091 Note if the second argument of @code{DETAILS} is a @code{local_NAME} then the
9092 second form is always understood. If the intention is to use
9093 the fourth form, then you can write @code{NAME & ""} to force the
9094 intepretation as a @emph{static_string_EXPRESSION}.
9096 Note: if the first argument is a valid @code{TOOL_NAME}, it will be interpreted
9097 that way. The use of the @code{TOOL_NAME} argument is relevant only to users
9098 of SPARK and GNATprove, see last part of this section for details.
9100 Normally warnings are enabled, with the output being controlled by
9101 the command line switch. Warnings (@code{Off}) turns off generation of
9102 warnings until a Warnings (@code{On}) is encountered or the end of the
9103 current unit. If generation of warnings is turned off using this
9104 pragma, then some or all of the warning messages are suppressed,
9105 regardless of the setting of the command line switches.
9107 The @code{Reason} parameter may optionally appear as the last argument
9108 in any of the forms of this pragma. It is intended purely for the
9109 purposes of documenting the reason for the @code{Warnings} pragma.
9110 The compiler will check that the argument is a static string but
9111 otherwise ignore this argument. Other tools may provide specialized
9112 processing for this string.
9114 The form with a single argument (or two arguments if Reason present),
9115 where the first argument is @code{ON} or @code{OFF}
9116 may be used as a configuration pragma.
9118 If the @code{LOCAL_NAME} parameter is present, warnings are suppressed for
9119 the specified entity. This suppression is effective from the point where
9120 it occurs till the end of the extended scope of the variable (similar to
9121 the scope of @code{Suppress}). This form cannot be used as a configuration
9124 In the case where the first argument is other than @code{ON} or
9126 the third form with a single static_string_EXPRESSION argument (and possible
9127 reason) provides more precise
9128 control over which warnings are active. The string is a list of letters
9129 specifying which warnings are to be activated and which deactivated. The
9130 code for these letters is the same as the string used in the command
9131 line switch controlling warnings. For a brief summary, use the gnatmake
9132 command with no arguments, which will generate usage information containing
9133 the list of warnings switches supported. For
9134 full details see the section on @code{Warning Message Control} in the
9135 @cite{GNAT User's Guide}.
9136 This form can also be used as a configuration pragma.
9138 The warnings controlled by the @code{-gnatw} switch are generated by the
9139 front end of the compiler. The GCC back end can provide additional warnings
9140 and they are controlled by the @code{-W} switch. Such warnings can be
9141 identified by the appearance of a string of the form @code{[-W@{xxx@}]} in the
9142 message which designates the @code{-W@emph{xxx}} switch that controls the message.
9143 The form with a single @emph{static_string_EXPRESSION} argument also works for these
9144 warnings, but the string must be a single full @code{-W@emph{xxx}} switch in this
9145 case. The above reference lists a few examples of these additional warnings.
9147 The specified warnings will be in effect until the end of the program
9148 or another pragma @code{Warnings} is encountered. The effect of the pragma is
9149 cumulative. Initially the set of warnings is the standard default set
9150 as possibly modified by compiler switches. Then each pragma Warning
9151 modifies this set of warnings as specified. This form of the pragma may
9152 also be used as a configuration pragma.
9154 The fourth form, with an @code{On|Off} parameter and a string, is used to
9155 control individual messages, based on their text. The string argument
9156 is a pattern that is used to match against the text of individual
9157 warning messages (not including the initial "warning: " tag).
9159 The pattern may contain asterisks, which match zero or more characters in
9160 the message. For example, you can use
9161 @code{pragma Warnings (Off, "bits of*unused")} to suppress the warning
9162 message @code{warning: 960 bits of "a" unused}. No other regular
9163 expression notations are permitted. All characters other than asterisk in
9164 these three specific cases are treated as literal characters in the match.
9165 The match is case insensitive, for example XYZ matches xyz.
9167 Note that the pattern matches if it occurs anywhere within the warning
9168 message string (it is not necessary to put an asterisk at the start and
9169 the end of the message, since this is implied).
9171 The above use of patterns to match the message applies only to warning
9172 messages generated by the front end. This form of the pragma with a string
9173 argument can also be used to control warnings provided by the back end and
9174 mentioned above. By using a single full @code{-W@emph{xxx}} switch in the pragma,
9175 such warnings can be turned on and off.
9177 There are two ways to use the pragma in this form. The OFF form can be used
9178 as a configuration pragma. The effect is to suppress all warnings (if any)
9179 that match the pattern string throughout the compilation (or match the
9180 -W switch in the back end case).
9182 The second usage is to suppress a warning locally, and in this case, two
9183 pragmas must appear in sequence:
9186 pragma Warnings (Off, Pattern);
9187 ... code where given warning is to be suppressed
9188 pragma Warnings (On, Pattern);
9191 In this usage, the pattern string must match in the Off and On
9192 pragmas, and (if @emph{-gnatw.w} is given) at least one matching
9193 warning must be suppressed.
9195 Note: if the ON form is not found, then the effect of the OFF form extends
9196 until the end of the file (pragma Warnings is purely textual, so its effect
9197 does not stop at the end of the enclosing scope).
9199 Note: to write a string that will match any warning, use the string
9200 @code{"***"}. It will not work to use a single asterisk or two
9201 asterisks since this looks like an operator name. This form with three
9202 asterisks is similar in effect to specifying @code{pragma Warnings (Off)} except (if @code{-gnatw.w} is given) that a matching
9203 @code{pragma Warnings (On, "***")} will be required. This can be
9204 helpful in avoiding forgetting to turn warnings back on.
9206 Note: the debug flag @code{-gnatd.i} (@code{/NOWARNINGS_PRAGMAS} in VMS) can be
9207 used to cause the compiler to entirely ignore all WARNINGS pragmas. This can
9208 be useful in checking whether obsolete pragmas in existing programs are hiding
9211 Note: pragma Warnings does not affect the processing of style messages. See
9212 separate entry for pragma Style_Checks for control of style messages.
9214 Users of the formal verification tool GNATprove for the SPARK subset of Ada may
9215 use the version of the pragma with a @code{TOOL_NAME} parameter.
9217 If present, @code{TOOL_NAME} is the name of a tool, currently either @code{GNAT} for the
9218 compiler or @code{GNATprove} for the formal verification tool. A given tool only
9219 takes into account pragma Warnings that do not specify a tool name, or that
9220 specify the matching tool name. This makes it possible to disable warnings
9221 selectively for each tool, and as a consequence to detect useless pragma
9222 Warnings with switch @code{-gnatw.w}.
9224 @node Pragma Weak_External,Pragma Wide_Character_Encoding,Pragma Warnings,Implementation Defined Pragmas
9225 @anchor{gnat_rm/implementation_defined_pragmas pragma-weak-external}@anchor{124}
9226 @section Pragma Weak_External
9232 pragma Weak_External ([Entity =>] LOCAL_NAME);
9235 @code{LOCAL_NAME} must refer to an object that is declared at the library
9236 level. This pragma specifies that the given entity should be marked as a
9237 weak symbol for the linker. It is equivalent to @code{__attribute__((weak))}
9238 in GNU C and causes @code{LOCAL_NAME} to be emitted as a weak symbol instead
9239 of a regular symbol, that is to say a symbol that does not have to be
9240 resolved by the linker if used in conjunction with a pragma Import.
9242 When a weak symbol is not resolved by the linker, its address is set to
9243 zero. This is useful in writing interfaces to external modules that may
9244 or may not be linked in the final executable, for example depending on
9245 configuration settings.
9247 If a program references at run time an entity to which this pragma has been
9248 applied, and the corresponding symbol was not resolved at link time, then
9249 the execution of the program is erroneous. It is not erroneous to take the
9250 Address of such an entity, for example to guard potential references,
9251 as shown in the example below.
9253 Some file formats do not support weak symbols so not all target machines
9254 support this pragma.
9257 -- Example of the use of pragma Weak_External
9259 package External_Module is
9261 pragma Import (C, key);
9262 pragma Weak_External (key);
9263 function Present return boolean;
9264 end External_Module;
9266 with System; use System;
9267 package body External_Module is
9268 function Present return boolean is
9270 return key'Address /= System.Null_Address;
9272 end External_Module;
9275 @node Pragma Wide_Character_Encoding,,Pragma Weak_External,Implementation Defined Pragmas
9276 @anchor{gnat_rm/implementation_defined_pragmas pragma-wide-character-encoding}@anchor{125}
9277 @section Pragma Wide_Character_Encoding
9283 pragma Wide_Character_Encoding (IDENTIFIER | CHARACTER_LITERAL);
9286 This pragma specifies the wide character encoding to be used in program
9287 source text appearing subsequently. It is a configuration pragma, but may
9288 also be used at any point that a pragma is allowed, and it is permissible
9289 to have more than one such pragma in a file, allowing multiple encodings
9290 to appear within the same file.
9292 However, note that the pragma cannot immediately precede the relevant
9293 wide character, because then the previous encoding will still be in
9294 effect, causing "illegal character" errors.
9296 The argument can be an identifier or a character literal. In the identifier
9297 case, it is one of @code{HEX}, @code{UPPER}, @code{SHIFT_JIS},
9298 @code{EUC}, @code{UTF8}, or @code{BRACKETS}. In the character literal
9299 case it is correspondingly one of the characters @code{h}, @code{u},
9300 @code{s}, @code{e}, @code{8}, or @code{b}.
9302 Note that when the pragma is used within a file, it affects only the
9303 encoding within that file, and does not affect withed units, specs,
9306 @node Implementation Defined Aspects,Implementation Defined Attributes,Implementation Defined Pragmas,Top
9307 @anchor{gnat_rm/implementation_defined_aspects implementation-defined-aspects}@anchor{126}@anchor{gnat_rm/implementation_defined_aspects doc}@anchor{127}@anchor{gnat_rm/implementation_defined_aspects id1}@anchor{128}
9308 @chapter Implementation Defined Aspects
9311 Ada defines (throughout the Ada 2012 reference manual, summarized
9312 in Annex K) a set of aspects that can be specified for certain entities.
9313 These language defined aspects are implemented in GNAT in Ada 2012 mode
9314 and work as described in the Ada 2012 Reference Manual.
9316 In addition, Ada 2012 allows implementations to define additional aspects
9317 whose meaning is defined by the implementation. GNAT provides
9318 a number of these implementation-defined aspects which can be used
9319 to extend and enhance the functionality of the compiler. This section of
9320 the GNAT reference manual describes these additional aspects.
9322 Note that any program using these aspects may not be portable to
9323 other compilers (although GNAT implements this set of aspects on all
9324 platforms). Therefore if portability to other compilers is an important
9325 consideration, you should minimize the use of these aspects.
9327 Note that for many of these aspects, the effect is essentially similar
9328 to the use of a pragma or attribute specification with the same name
9329 applied to the entity. For example, if we write:
9332 type R is range 1 .. 100
9333 with Value_Size => 10;
9336 then the effect is the same as:
9339 type R is range 1 .. 100;
9340 for R'Value_Size use 10;
9346 type R is new Integer
9347 with Shared => True;
9350 then the effect is the same as:
9353 type R is new Integer;
9357 In the documentation below, such cases are simply marked
9358 as being boolean aspects equivalent to the corresponding pragma
9359 or attribute definition clause.
9362 * Aspect Abstract_State::
9364 * Aspect Async_Readers::
9365 * Aspect Async_Writers::
9366 * Aspect Constant_After_Elaboration::
9367 * Aspect Contract_Cases::
9369 * Aspect Default_Initial_Condition::
9370 * Aspect Dimension::
9371 * Aspect Dimension_System::
9372 * Aspect Disable_Controlled::
9373 * Aspect Effective_Reads::
9374 * Aspect Effective_Writes::
9375 * Aspect Extensions_Visible::
9376 * Aspect Favor_Top_Level::
9379 * Aspect Initial_Condition::
9380 * Aspect Initializes::
9381 * Aspect Inline_Always::
9382 * Aspect Invariant::
9383 * Aspect Invariant'Class::
9385 * Aspect Linker_Section::
9386 * Aspect Lock_Free::
9387 * Aspect Max_Queue_Length::
9388 * Aspect No_Caching::
9389 * Aspect No_Elaboration_Code_All::
9390 * Aspect No_Inline::
9391 * Aspect No_Tagged_Streams::
9392 * Aspect Object_Size::
9393 * Aspect Obsolescent::
9395 * Aspect Persistent_BSS::
9396 * Aspect Predicate::
9397 * Aspect Pure_Function::
9398 * Aspect Refined_Depends::
9399 * Aspect Refined_Global::
9400 * Aspect Refined_Post::
9401 * Aspect Refined_State::
9402 * Aspect Remote_Access_Type::
9403 * Aspect Secondary_Stack_Size::
9404 * Aspect Scalar_Storage_Order::
9406 * Aspect Simple_Storage_Pool::
9407 * Aspect Simple_Storage_Pool_Type::
9408 * Aspect SPARK_Mode::
9409 * Aspect Suppress_Debug_Info::
9410 * Aspect Suppress_Initialization::
9411 * Aspect Test_Case::
9412 * Aspect Thread_Local_Storage::
9413 * Aspect Universal_Aliasing::
9414 * Aspect Universal_Data::
9415 * Aspect Unmodified::
9416 * Aspect Unreferenced::
9417 * Aspect Unreferenced_Objects::
9418 * Aspect Value_Size::
9419 * Aspect Volatile_Full_Access::
9420 * Aspect Volatile_Function::
9425 @node Aspect Abstract_State,Aspect Annotate,,Implementation Defined Aspects
9426 @anchor{gnat_rm/implementation_defined_aspects aspect-abstract-state}@anchor{129}
9427 @section Aspect Abstract_State
9430 @geindex Abstract_State
9432 This aspect is equivalent to @ref{1c,,pragma Abstract_State}.
9434 @node Aspect Annotate,Aspect Async_Readers,Aspect Abstract_State,Implementation Defined Aspects
9435 @anchor{gnat_rm/implementation_defined_aspects aspect-annotate}@anchor{12a}
9436 @section Aspect Annotate
9441 There are three forms of this aspect (where ID is an identifier,
9442 and ARG is a general expression),
9443 corresponding to @ref{2a,,pragma Annotate}.
9448 @item @emph{Annotate => ID}
9450 Equivalent to @code{pragma Annotate (ID, Entity => Name);}
9452 @item @emph{Annotate => (ID)}
9454 Equivalent to @code{pragma Annotate (ID, Entity => Name);}
9456 @item @emph{Annotate => (ID ,ID @{, ARG@})}
9458 Equivalent to @code{pragma Annotate (ID, ID @{, ARG@}, Entity => Name);}
9461 @node Aspect Async_Readers,Aspect Async_Writers,Aspect Annotate,Implementation Defined Aspects
9462 @anchor{gnat_rm/implementation_defined_aspects aspect-async-readers}@anchor{12b}
9463 @section Aspect Async_Readers
9466 @geindex Async_Readers
9468 This boolean aspect is equivalent to @ref{31,,pragma Async_Readers}.
9470 @node Aspect Async_Writers,Aspect Constant_After_Elaboration,Aspect Async_Readers,Implementation Defined Aspects
9471 @anchor{gnat_rm/implementation_defined_aspects aspect-async-writers}@anchor{12c}
9472 @section Aspect Async_Writers
9475 @geindex Async_Writers
9477 This boolean aspect is equivalent to @ref{34,,pragma Async_Writers}.
9479 @node Aspect Constant_After_Elaboration,Aspect Contract_Cases,Aspect Async_Writers,Implementation Defined Aspects
9480 @anchor{gnat_rm/implementation_defined_aspects aspect-constant-after-elaboration}@anchor{12d}
9481 @section Aspect Constant_After_Elaboration
9484 @geindex Constant_After_Elaboration
9486 This aspect is equivalent to @ref{45,,pragma Constant_After_Elaboration}.
9488 @node Aspect Contract_Cases,Aspect Depends,Aspect Constant_After_Elaboration,Implementation Defined Aspects
9489 @anchor{gnat_rm/implementation_defined_aspects aspect-contract-cases}@anchor{12e}
9490 @section Aspect Contract_Cases
9493 @geindex Contract_Cases
9495 This aspect is equivalent to @ref{47,,pragma Contract_Cases}, the sequence
9496 of clauses being enclosed in parentheses so that syntactically it is an
9499 @node Aspect Depends,Aspect Default_Initial_Condition,Aspect Contract_Cases,Implementation Defined Aspects
9500 @anchor{gnat_rm/implementation_defined_aspects aspect-depends}@anchor{12f}
9501 @section Aspect Depends
9506 This aspect is equivalent to @ref{56,,pragma Depends}.
9508 @node Aspect Default_Initial_Condition,Aspect Dimension,Aspect Depends,Implementation Defined Aspects
9509 @anchor{gnat_rm/implementation_defined_aspects aspect-default-initial-condition}@anchor{130}
9510 @section Aspect Default_Initial_Condition
9513 @geindex Default_Initial_Condition
9515 This aspect is equivalent to @ref{51,,pragma Default_Initial_Condition}.
9517 @node Aspect Dimension,Aspect Dimension_System,Aspect Default_Initial_Condition,Implementation Defined Aspects
9518 @anchor{gnat_rm/implementation_defined_aspects aspect-dimension}@anchor{131}
9519 @section Aspect Dimension
9524 The @code{Dimension} aspect is used to specify the dimensions of a given
9525 subtype of a dimensioned numeric type. The aspect also specifies a symbol
9526 used when doing formatted output of dimensioned quantities. The syntax is:
9530 ([Symbol =>] SYMBOL, DIMENSION_VALUE @{, DIMENSION_Value@})
9532 SYMBOL ::= STRING_LITERAL | CHARACTER_LITERAL
9536 | others => RATIONAL
9537 | DISCRETE_CHOICE_LIST => RATIONAL
9539 RATIONAL ::= [-] NUMERIC_LITERAL [/ NUMERIC_LITERAL]
9542 This aspect can only be applied to a subtype whose parent type has
9543 a @code{Dimension_System} aspect. The aspect must specify values for
9544 all dimensions of the system. The rational values are the powers of the
9545 corresponding dimensions that are used by the compiler to verify that
9546 physical (numeric) computations are dimensionally consistent. For example,
9547 the computation of a force must result in dimensions (L => 1, M => 1, T => -2).
9548 For further examples of the usage
9549 of this aspect, see package @code{System.Dim.Mks}.
9550 Note that when the dimensioned type is an integer type, then any
9551 dimension value must be an integer literal.
9553 @node Aspect Dimension_System,Aspect Disable_Controlled,Aspect Dimension,Implementation Defined Aspects
9554 @anchor{gnat_rm/implementation_defined_aspects aspect-dimension-system}@anchor{132}
9555 @section Aspect Dimension_System
9558 @geindex Dimension_System
9560 The @code{Dimension_System} aspect is used to define a system of
9561 dimensions that will be used in subsequent subtype declarations with
9562 @code{Dimension} aspects that reference this system. The syntax is:
9565 with Dimension_System => (DIMENSION @{, DIMENSION@});
9567 DIMENSION ::= ([Unit_Name =>] IDENTIFIER,
9568 [Unit_Symbol =>] SYMBOL,
9569 [Dim_Symbol =>] SYMBOL)
9571 SYMBOL ::= CHARACTER_LITERAL | STRING_LITERAL
9574 This aspect is applied to a type, which must be a numeric derived type
9575 (typically a floating-point type), that
9576 will represent values within the dimension system. Each @code{DIMENSION}
9577 corresponds to one particular dimension. A maximum of 7 dimensions may
9578 be specified. @code{Unit_Name} is the name of the dimension (for example
9579 @code{Meter}). @code{Unit_Symbol} is the shorthand used for quantities
9580 of this dimension (for example @code{m} for @code{Meter}).
9581 @code{Dim_Symbol} gives
9582 the identification within the dimension system (typically this is a
9583 single letter, e.g. @code{L} standing for length for unit name @code{Meter}).
9584 The @code{Unit_Symbol} is used in formatted output of dimensioned quantities.
9585 The @code{Dim_Symbol} is used in error messages when numeric operations have
9586 inconsistent dimensions.
9588 GNAT provides the standard definition of the International MKS system in
9589 the run-time package @code{System.Dim.Mks}. You can easily define
9590 similar packages for cgs units or British units, and define conversion factors
9591 between values in different systems. The MKS system is characterized by the
9595 type Mks_Type is new Long_Long_Float with
9596 Dimension_System => (
9597 (Unit_Name => Meter, Unit_Symbol => 'm', Dim_Symbol => 'L'),
9598 (Unit_Name => Kilogram, Unit_Symbol => "kg", Dim_Symbol => 'M'),
9599 (Unit_Name => Second, Unit_Symbol => 's', Dim_Symbol => 'T'),
9600 (Unit_Name => Ampere, Unit_Symbol => 'A', Dim_Symbol => 'I'),
9601 (Unit_Name => Kelvin, Unit_Symbol => 'K', Dim_Symbol => '@@'),
9602 (Unit_Name => Mole, Unit_Symbol => "mol", Dim_Symbol => 'N'),
9603 (Unit_Name => Candela, Unit_Symbol => "cd", Dim_Symbol => 'J'));
9606 Note that in the above type definition, we use the @code{at} symbol (@code{@@}) to
9607 represent a theta character (avoiding the use of extended Latin-1
9608 characters in this context).
9610 See section 'Performing Dimensionality Analysis in GNAT' in the GNAT Users
9611 Guide for detailed examples of use of the dimension system.
9613 @node Aspect Disable_Controlled,Aspect Effective_Reads,Aspect Dimension_System,Implementation Defined Aspects
9614 @anchor{gnat_rm/implementation_defined_aspects aspect-disable-controlled}@anchor{133}
9615 @section Aspect Disable_Controlled
9618 @geindex Disable_Controlled
9620 The aspect @code{Disable_Controlled} is defined for controlled record types. If
9621 active, this aspect causes suppression of all related calls to @code{Initialize},
9622 @code{Adjust}, and @code{Finalize}. The intended use is for conditional compilation,
9623 where for example you might want a record to be controlled or not depending on
9624 whether some run-time check is enabled or suppressed.
9626 @node Aspect Effective_Reads,Aspect Effective_Writes,Aspect Disable_Controlled,Implementation Defined Aspects
9627 @anchor{gnat_rm/implementation_defined_aspects aspect-effective-reads}@anchor{134}
9628 @section Aspect Effective_Reads
9631 @geindex Effective_Reads
9633 This aspect is equivalent to @ref{5c,,pragma Effective_Reads}.
9635 @node Aspect Effective_Writes,Aspect Extensions_Visible,Aspect Effective_Reads,Implementation Defined Aspects
9636 @anchor{gnat_rm/implementation_defined_aspects aspect-effective-writes}@anchor{135}
9637 @section Aspect Effective_Writes
9640 @geindex Effective_Writes
9642 This aspect is equivalent to @ref{5e,,pragma Effective_Writes}.
9644 @node Aspect Extensions_Visible,Aspect Favor_Top_Level,Aspect Effective_Writes,Implementation Defined Aspects
9645 @anchor{gnat_rm/implementation_defined_aspects aspect-extensions-visible}@anchor{136}
9646 @section Aspect Extensions_Visible
9649 @geindex Extensions_Visible
9651 This aspect is equivalent to @ref{6a,,pragma Extensions_Visible}.
9653 @node Aspect Favor_Top_Level,Aspect Ghost,Aspect Extensions_Visible,Implementation Defined Aspects
9654 @anchor{gnat_rm/implementation_defined_aspects aspect-favor-top-level}@anchor{137}
9655 @section Aspect Favor_Top_Level
9658 @geindex Favor_Top_Level
9660 This boolean aspect is equivalent to @ref{6f,,pragma Favor_Top_Level}.
9662 @node Aspect Ghost,Aspect Global,Aspect Favor_Top_Level,Implementation Defined Aspects
9663 @anchor{gnat_rm/implementation_defined_aspects aspect-ghost}@anchor{138}
9664 @section Aspect Ghost
9669 This aspect is equivalent to @ref{72,,pragma Ghost}.
9671 @node Aspect Global,Aspect Initial_Condition,Aspect Ghost,Implementation Defined Aspects
9672 @anchor{gnat_rm/implementation_defined_aspects aspect-global}@anchor{139}
9673 @section Aspect Global
9678 This aspect is equivalent to @ref{74,,pragma Global}.
9680 @node Aspect Initial_Condition,Aspect Initializes,Aspect Global,Implementation Defined Aspects
9681 @anchor{gnat_rm/implementation_defined_aspects aspect-initial-condition}@anchor{13a}
9682 @section Aspect Initial_Condition
9685 @geindex Initial_Condition
9687 This aspect is equivalent to @ref{82,,pragma Initial_Condition}.
9689 @node Aspect Initializes,Aspect Inline_Always,Aspect Initial_Condition,Implementation Defined Aspects
9690 @anchor{gnat_rm/implementation_defined_aspects aspect-initializes}@anchor{13b}
9691 @section Aspect Initializes
9694 @geindex Initializes
9696 This aspect is equivalent to @ref{84,,pragma Initializes}.
9698 @node Aspect Inline_Always,Aspect Invariant,Aspect Initializes,Implementation Defined Aspects
9699 @anchor{gnat_rm/implementation_defined_aspects aspect-inline-always}@anchor{13c}
9700 @section Aspect Inline_Always
9703 @geindex Inline_Always
9705 This boolean aspect is equivalent to @ref{87,,pragma Inline_Always}.
9707 @node Aspect Invariant,Aspect Invariant'Class,Aspect Inline_Always,Implementation Defined Aspects
9708 @anchor{gnat_rm/implementation_defined_aspects aspect-invariant}@anchor{13d}
9709 @section Aspect Invariant
9714 This aspect is equivalent to @ref{8e,,pragma Invariant}. It is a
9715 synonym for the language defined aspect @code{Type_Invariant} except
9716 that it is separately controllable using pragma @code{Assertion_Policy}.
9718 @node Aspect Invariant'Class,Aspect Iterable,Aspect Invariant,Implementation Defined Aspects
9719 @anchor{gnat_rm/implementation_defined_aspects aspect-invariant-class}@anchor{13e}
9720 @section Aspect Invariant'Class
9723 @geindex Invariant'Class
9725 This aspect is equivalent to @ref{107,,pragma Type_Invariant_Class}. It is a
9726 synonym for the language defined aspect @code{Type_Invariant'Class} except
9727 that it is separately controllable using pragma @code{Assertion_Policy}.
9729 @node Aspect Iterable,Aspect Linker_Section,Aspect Invariant'Class,Implementation Defined Aspects
9730 @anchor{gnat_rm/implementation_defined_aspects aspect-iterable}@anchor{13f}
9731 @section Aspect Iterable
9736 This aspect provides a light-weight mechanism for loops and quantified
9737 expressions over container types, without the overhead imposed by the tampering
9738 checks of standard Ada 2012 iterators. The value of the aspect is an aggregate
9739 with six named components, of which the last three are optional: @code{First},
9740 @code{Next}, @code{Has_Element}, @code{Element}, @code{Last}, and @code{Previous}.
9741 When only the first three components are specified, only the
9742 @code{for .. in} form of iteration over cursors is available. When @code{Element}
9743 is specified, both this form and the @code{for .. of} form of iteration over
9744 elements are available. If the last two components are specified, reverse
9745 iterations over the container can be specified (analogous to what can be done
9746 over predefined containers that support the @code{Reverse_Iterator} interface).
9747 The following is a typical example of use:
9750 type List is private with
9751 Iterable => (First => First_Cursor,
9753 Has_Element => Cursor_Has_Element,
9754 [Element => Get_Element]);
9761 The value denoted by @code{First} must denote a primitive operation of the
9762 container type that returns a @code{Cursor}, which must a be a type declared in
9763 the container package or visible from it. For example:
9767 function First_Cursor (Cont : Container) return Cursor;
9774 The value of @code{Next} is a primitive operation of the container type that takes
9775 both a container and a cursor and yields a cursor. For example:
9779 function Advance (Cont : Container; Position : Cursor) return Cursor;
9786 The value of @code{Has_Element} is a primitive operation of the container type
9787 that takes both a container and a cursor and yields a boolean. For example:
9791 function Cursor_Has_Element (Cont : Container; Position : Cursor) return Boolean;
9798 The value of @code{Element} is a primitive operation of the container type that
9799 takes both a container and a cursor and yields an @code{Element_Type}, which must
9800 be a type declared in the container package or visible from it. For example:
9804 function Get_Element (Cont : Container; Position : Cursor) return Element_Type;
9807 This aspect is used in the GNAT-defined formal container packages.
9809 @node Aspect Linker_Section,Aspect Lock_Free,Aspect Iterable,Implementation Defined Aspects
9810 @anchor{gnat_rm/implementation_defined_aspects aspect-linker-section}@anchor{140}
9811 @section Aspect Linker_Section
9814 @geindex Linker_Section
9816 This aspect is equivalent to @ref{96,,pragma Linker_Section}.
9818 @node Aspect Lock_Free,Aspect Max_Queue_Length,Aspect Linker_Section,Implementation Defined Aspects
9819 @anchor{gnat_rm/implementation_defined_aspects aspect-lock-free}@anchor{141}
9820 @section Aspect Lock_Free
9825 This boolean aspect is equivalent to @ref{98,,pragma Lock_Free}.
9827 @node Aspect Max_Queue_Length,Aspect No_Caching,Aspect Lock_Free,Implementation Defined Aspects
9828 @anchor{gnat_rm/implementation_defined_aspects aspect-max-queue-length}@anchor{142}
9829 @section Aspect Max_Queue_Length
9832 @geindex Max_Queue_Length
9834 This aspect is equivalent to @ref{a0,,pragma Max_Queue_Length}.
9836 @node Aspect No_Caching,Aspect No_Elaboration_Code_All,Aspect Max_Queue_Length,Implementation Defined Aspects
9837 @anchor{gnat_rm/implementation_defined_aspects aspect-no-caching}@anchor{143}
9838 @section Aspect No_Caching
9843 This boolean aspect is equivalent to @ref{a2,,pragma No_Caching}.
9845 @node Aspect No_Elaboration_Code_All,Aspect No_Inline,Aspect No_Caching,Implementation Defined Aspects
9846 @anchor{gnat_rm/implementation_defined_aspects aspect-no-elaboration-code-all}@anchor{144}
9847 @section Aspect No_Elaboration_Code_All
9850 @geindex No_Elaboration_Code_All
9852 This aspect is equivalent to @ref{a6,,pragma No_Elaboration_Code_All}
9855 @node Aspect No_Inline,Aspect No_Tagged_Streams,Aspect No_Elaboration_Code_All,Implementation Defined Aspects
9856 @anchor{gnat_rm/implementation_defined_aspects aspect-no-inline}@anchor{145}
9857 @section Aspect No_Inline
9862 This boolean aspect is equivalent to @ref{a9,,pragma No_Inline}.
9864 @node Aspect No_Tagged_Streams,Aspect Object_Size,Aspect No_Inline,Implementation Defined Aspects
9865 @anchor{gnat_rm/implementation_defined_aspects aspect-no-tagged-streams}@anchor{146}
9866 @section Aspect No_Tagged_Streams
9869 @geindex No_Tagged_Streams
9871 This aspect is equivalent to @ref{ad,,pragma No_Tagged_Streams} with an
9872 argument specifying a root tagged type (thus this aspect can only be
9873 applied to such a type).
9875 @node Aspect Object_Size,Aspect Obsolescent,Aspect No_Tagged_Streams,Implementation Defined Aspects
9876 @anchor{gnat_rm/implementation_defined_aspects aspect-object-size}@anchor{147}
9877 @section Aspect Object_Size
9880 @geindex Object_Size
9882 This aspect is equivalent to @ref{148,,attribute Object_Size}.
9884 @node Aspect Obsolescent,Aspect Part_Of,Aspect Object_Size,Implementation Defined Aspects
9885 @anchor{gnat_rm/implementation_defined_aspects aspect-obsolescent}@anchor{149}
9886 @section Aspect Obsolescent
9889 @geindex Obsolsecent
9891 This aspect is equivalent to @ref{b0,,pragma Obsolescent}. Note that the
9892 evaluation of this aspect happens at the point of occurrence, it is not
9893 delayed until the freeze point.
9895 @node Aspect Part_Of,Aspect Persistent_BSS,Aspect Obsolescent,Implementation Defined Aspects
9896 @anchor{gnat_rm/implementation_defined_aspects aspect-part-of}@anchor{14a}
9897 @section Aspect Part_Of
9902 This aspect is equivalent to @ref{b8,,pragma Part_Of}.
9904 @node Aspect Persistent_BSS,Aspect Predicate,Aspect Part_Of,Implementation Defined Aspects
9905 @anchor{gnat_rm/implementation_defined_aspects aspect-persistent-bss}@anchor{14b}
9906 @section Aspect Persistent_BSS
9909 @geindex Persistent_BSS
9911 This boolean aspect is equivalent to @ref{bb,,pragma Persistent_BSS}.
9913 @node Aspect Predicate,Aspect Pure_Function,Aspect Persistent_BSS,Implementation Defined Aspects
9914 @anchor{gnat_rm/implementation_defined_aspects aspect-predicate}@anchor{14c}
9915 @section Aspect Predicate
9920 This aspect is equivalent to @ref{c3,,pragma Predicate}. It is thus
9921 similar to the language defined aspects @code{Dynamic_Predicate}
9922 and @code{Static_Predicate} except that whether the resulting
9923 predicate is static or dynamic is controlled by the form of the
9924 expression. It is also separately controllable using pragma
9925 @code{Assertion_Policy}.
9927 @node Aspect Pure_Function,Aspect Refined_Depends,Aspect Predicate,Implementation Defined Aspects
9928 @anchor{gnat_rm/implementation_defined_aspects aspect-pure-function}@anchor{14d}
9929 @section Aspect Pure_Function
9932 @geindex Pure_Function
9934 This boolean aspect is equivalent to @ref{cf,,pragma Pure_Function}.
9936 @node Aspect Refined_Depends,Aspect Refined_Global,Aspect Pure_Function,Implementation Defined Aspects
9937 @anchor{gnat_rm/implementation_defined_aspects aspect-refined-depends}@anchor{14e}
9938 @section Aspect Refined_Depends
9941 @geindex Refined_Depends
9943 This aspect is equivalent to @ref{d3,,pragma Refined_Depends}.
9945 @node Aspect Refined_Global,Aspect Refined_Post,Aspect Refined_Depends,Implementation Defined Aspects
9946 @anchor{gnat_rm/implementation_defined_aspects aspect-refined-global}@anchor{14f}
9947 @section Aspect Refined_Global
9950 @geindex Refined_Global
9952 This aspect is equivalent to @ref{d5,,pragma Refined_Global}.
9954 @node Aspect Refined_Post,Aspect Refined_State,Aspect Refined_Global,Implementation Defined Aspects
9955 @anchor{gnat_rm/implementation_defined_aspects aspect-refined-post}@anchor{150}
9956 @section Aspect Refined_Post
9959 @geindex Refined_Post
9961 This aspect is equivalent to @ref{d7,,pragma Refined_Post}.
9963 @node Aspect Refined_State,Aspect Remote_Access_Type,Aspect Refined_Post,Implementation Defined Aspects
9964 @anchor{gnat_rm/implementation_defined_aspects aspect-refined-state}@anchor{151}
9965 @section Aspect Refined_State
9968 @geindex Refined_State
9970 This aspect is equivalent to @ref{d9,,pragma Refined_State}.
9972 @node Aspect Remote_Access_Type,Aspect Secondary_Stack_Size,Aspect Refined_State,Implementation Defined Aspects
9973 @anchor{gnat_rm/implementation_defined_aspects aspect-remote-access-type}@anchor{152}
9974 @section Aspect Remote_Access_Type
9977 @geindex Remote_Access_Type
9979 This aspect is equivalent to @ref{dd,,pragma Remote_Access_Type}.
9981 @node Aspect Secondary_Stack_Size,Aspect Scalar_Storage_Order,Aspect Remote_Access_Type,Implementation Defined Aspects
9982 @anchor{gnat_rm/implementation_defined_aspects aspect-secondary-stack-size}@anchor{153}
9983 @section Aspect Secondary_Stack_Size
9986 @geindex Secondary_Stack_Size
9988 This aspect is equivalent to @ref{e2,,pragma Secondary_Stack_Size}.
9990 @node Aspect Scalar_Storage_Order,Aspect Shared,Aspect Secondary_Stack_Size,Implementation Defined Aspects
9991 @anchor{gnat_rm/implementation_defined_aspects aspect-scalar-storage-order}@anchor{154}
9992 @section Aspect Scalar_Storage_Order
9995 @geindex Scalar_Storage_Order
9997 This aspect is equivalent to a @ref{155,,attribute Scalar_Storage_Order}.
9999 @node Aspect Shared,Aspect Simple_Storage_Pool,Aspect Scalar_Storage_Order,Implementation Defined Aspects
10000 @anchor{gnat_rm/implementation_defined_aspects aspect-shared}@anchor{156}
10001 @section Aspect Shared
10006 This boolean aspect is equivalent to @ref{e5,,pragma Shared}
10007 and is thus a synonym for aspect @code{Atomic}.
10009 @node Aspect Simple_Storage_Pool,Aspect Simple_Storage_Pool_Type,Aspect Shared,Implementation Defined Aspects
10010 @anchor{gnat_rm/implementation_defined_aspects aspect-simple-storage-pool}@anchor{157}
10011 @section Aspect Simple_Storage_Pool
10014 @geindex Simple_Storage_Pool
10016 This aspect is equivalent to @ref{ea,,attribute Simple_Storage_Pool}.
10018 @node Aspect Simple_Storage_Pool_Type,Aspect SPARK_Mode,Aspect Simple_Storage_Pool,Implementation Defined Aspects
10019 @anchor{gnat_rm/implementation_defined_aspects aspect-simple-storage-pool-type}@anchor{158}
10020 @section Aspect Simple_Storage_Pool_Type
10023 @geindex Simple_Storage_Pool_Type
10025 This boolean aspect is equivalent to @ref{e8,,pragma Simple_Storage_Pool_Type}.
10027 @node Aspect SPARK_Mode,Aspect Suppress_Debug_Info,Aspect Simple_Storage_Pool_Type,Implementation Defined Aspects
10028 @anchor{gnat_rm/implementation_defined_aspects aspect-spark-mode}@anchor{159}
10029 @section Aspect SPARK_Mode
10032 @geindex SPARK_Mode
10034 This aspect is equivalent to @ref{f0,,pragma SPARK_Mode} and
10035 may be specified for either or both of the specification and body
10036 of a subprogram or package.
10038 @node Aspect Suppress_Debug_Info,Aspect Suppress_Initialization,Aspect SPARK_Mode,Implementation Defined Aspects
10039 @anchor{gnat_rm/implementation_defined_aspects aspect-suppress-debug-info}@anchor{15a}
10040 @section Aspect Suppress_Debug_Info
10043 @geindex Suppress_Debug_Info
10045 This boolean aspect is equivalent to @ref{f8,,pragma Suppress_Debug_Info}.
10047 @node Aspect Suppress_Initialization,Aspect Test_Case,Aspect Suppress_Debug_Info,Implementation Defined Aspects
10048 @anchor{gnat_rm/implementation_defined_aspects aspect-suppress-initialization}@anchor{15b}
10049 @section Aspect Suppress_Initialization
10052 @geindex Suppress_Initialization
10054 This boolean aspect is equivalent to @ref{fc,,pragma Suppress_Initialization}.
10056 @node Aspect Test_Case,Aspect Thread_Local_Storage,Aspect Suppress_Initialization,Implementation Defined Aspects
10057 @anchor{gnat_rm/implementation_defined_aspects aspect-test-case}@anchor{15c}
10058 @section Aspect Test_Case
10063 This aspect is equivalent to @ref{ff,,pragma Test_Case}.
10065 @node Aspect Thread_Local_Storage,Aspect Universal_Aliasing,Aspect Test_Case,Implementation Defined Aspects
10066 @anchor{gnat_rm/implementation_defined_aspects aspect-thread-local-storage}@anchor{15d}
10067 @section Aspect Thread_Local_Storage
10070 @geindex Thread_Local_Storage
10072 This boolean aspect is equivalent to @ref{101,,pragma Thread_Local_Storage}.
10074 @node Aspect Universal_Aliasing,Aspect Universal_Data,Aspect Thread_Local_Storage,Implementation Defined Aspects
10075 @anchor{gnat_rm/implementation_defined_aspects aspect-universal-aliasing}@anchor{15e}
10076 @section Aspect Universal_Aliasing
10079 @geindex Universal_Aliasing
10081 This boolean aspect is equivalent to @ref{10b,,pragma Universal_Aliasing}.
10083 @node Aspect Universal_Data,Aspect Unmodified,Aspect Universal_Aliasing,Implementation Defined Aspects
10084 @anchor{gnat_rm/implementation_defined_aspects aspect-universal-data}@anchor{15f}
10085 @section Aspect Universal_Data
10088 @geindex Universal_Data
10090 This aspect is equivalent to @ref{10d,,pragma Universal_Data}.
10092 @node Aspect Unmodified,Aspect Unreferenced,Aspect Universal_Data,Implementation Defined Aspects
10093 @anchor{gnat_rm/implementation_defined_aspects aspect-unmodified}@anchor{160}
10094 @section Aspect Unmodified
10097 @geindex Unmodified
10099 This boolean aspect is equivalent to @ref{110,,pragma Unmodified}.
10101 @node Aspect Unreferenced,Aspect Unreferenced_Objects,Aspect Unmodified,Implementation Defined Aspects
10102 @anchor{gnat_rm/implementation_defined_aspects aspect-unreferenced}@anchor{161}
10103 @section Aspect Unreferenced
10106 @geindex Unreferenced
10108 This boolean aspect is equivalent to @ref{111,,pragma Unreferenced}. Note that
10109 in the case of formal parameters, it is not permitted to have aspects for
10110 a formal parameter, so in this case the pragma form must be used.
10112 @node Aspect Unreferenced_Objects,Aspect Value_Size,Aspect Unreferenced,Implementation Defined Aspects
10113 @anchor{gnat_rm/implementation_defined_aspects aspect-unreferenced-objects}@anchor{162}
10114 @section Aspect Unreferenced_Objects
10117 @geindex Unreferenced_Objects
10119 This boolean aspect is equivalent to @ref{113,,pragma Unreferenced_Objects}.
10121 @node Aspect Value_Size,Aspect Volatile_Full_Access,Aspect Unreferenced_Objects,Implementation Defined Aspects
10122 @anchor{gnat_rm/implementation_defined_aspects aspect-value-size}@anchor{163}
10123 @section Aspect Value_Size
10126 @geindex Value_Size
10128 This aspect is equivalent to @ref{164,,attribute Value_Size}.
10130 @node Aspect Volatile_Full_Access,Aspect Volatile_Function,Aspect Value_Size,Implementation Defined Aspects
10131 @anchor{gnat_rm/implementation_defined_aspects aspect-volatile-full-access}@anchor{165}
10132 @section Aspect Volatile_Full_Access
10135 @geindex Volatile_Full_Access
10137 This boolean aspect is equivalent to @ref{11e,,pragma Volatile_Full_Access}.
10139 @node Aspect Volatile_Function,Aspect Warnings,Aspect Volatile_Full_Access,Implementation Defined Aspects
10140 @anchor{gnat_rm/implementation_defined_aspects aspect-volatile-function}@anchor{166}
10141 @section Aspect Volatile_Function
10144 @geindex Volatile_Function
10146 This boolean aspect is equivalent to @ref{120,,pragma Volatile_Function}.
10148 @node Aspect Warnings,,Aspect Volatile_Function,Implementation Defined Aspects
10149 @anchor{gnat_rm/implementation_defined_aspects aspect-warnings}@anchor{167}
10150 @section Aspect Warnings
10155 This aspect is equivalent to the two argument form of @ref{122,,pragma Warnings},
10156 where the first argument is @code{ON} or @code{OFF} and the second argument
10159 @node Implementation Defined Attributes,Standard and Implementation Defined Restrictions,Implementation Defined Aspects,Top
10160 @anchor{gnat_rm/implementation_defined_attributes doc}@anchor{168}@anchor{gnat_rm/implementation_defined_attributes implementation-defined-attributes}@anchor{8}@anchor{gnat_rm/implementation_defined_attributes id1}@anchor{169}
10161 @chapter Implementation Defined Attributes
10164 Ada defines (throughout the Ada reference manual,
10165 summarized in Annex K),
10166 a set of attributes that provide useful additional functionality in all
10167 areas of the language. These language defined attributes are implemented
10168 in GNAT and work as described in the Ada Reference Manual.
10170 In addition, Ada allows implementations to define additional
10171 attributes whose meaning is defined by the implementation. GNAT provides
10172 a number of these implementation-dependent attributes which can be used
10173 to extend and enhance the functionality of the compiler. This section of
10174 the GNAT reference manual describes these additional attributes. It also
10175 describes additional implementation-dependent features of standard
10176 language-defined attributes.
10178 Note that any program using these attributes may not be portable to
10179 other compilers (although GNAT implements this set of attributes on all
10180 platforms). Therefore if portability to other compilers is an important
10181 consideration, you should minimize the use of these attributes.
10184 * Attribute Abort_Signal::
10185 * Attribute Address_Size::
10186 * Attribute Asm_Input::
10187 * Attribute Asm_Output::
10188 * Attribute Atomic_Always_Lock_Free::
10190 * Attribute Bit_Position::
10191 * Attribute Code_Address::
10192 * Attribute Compiler_Version::
10193 * Attribute Constrained::
10194 * Attribute Default_Bit_Order::
10195 * Attribute Default_Scalar_Storage_Order::
10196 * Attribute Deref::
10197 * Attribute Descriptor_Size::
10198 * Attribute Elaborated::
10199 * Attribute Elab_Body::
10200 * Attribute Elab_Spec::
10201 * Attribute Elab_Subp_Body::
10203 * Attribute Enabled::
10204 * Attribute Enum_Rep::
10205 * Attribute Enum_Val::
10206 * Attribute Epsilon::
10207 * Attribute Fast_Math::
10208 * Attribute Finalization_Size::
10209 * Attribute Fixed_Value::
10210 * Attribute From_Any::
10211 * Attribute Has_Access_Values::
10212 * Attribute Has_Discriminants::
10214 * Attribute Integer_Value::
10215 * Attribute Invalid_Value::
10216 * Attribute Iterable::
10217 * Attribute Large::
10218 * Attribute Library_Level::
10219 * Attribute Lock_Free::
10220 * Attribute Loop_Entry::
10221 * Attribute Machine_Size::
10222 * Attribute Mantissa::
10223 * Attribute Maximum_Alignment::
10224 * Attribute Mechanism_Code::
10225 * Attribute Null_Parameter::
10226 * Attribute Object_Size::
10228 * Attribute Passed_By_Reference::
10229 * Attribute Pool_Address::
10230 * Attribute Range_Length::
10231 * Attribute Restriction_Set::
10232 * Attribute Result::
10233 * Attribute Safe_Emax::
10234 * Attribute Safe_Large::
10235 * Attribute Safe_Small::
10236 * Attribute Scalar_Storage_Order::
10237 * Attribute Simple_Storage_Pool::
10238 * Attribute Small::
10239 * Attribute Storage_Unit::
10240 * Attribute Stub_Type::
10241 * Attribute System_Allocator_Alignment::
10242 * Attribute Target_Name::
10243 * Attribute To_Address::
10244 * Attribute To_Any::
10245 * Attribute Type_Class::
10246 * Attribute Type_Key::
10247 * Attribute TypeCode::
10248 * Attribute Unconstrained_Array::
10249 * Attribute Universal_Literal_String::
10250 * Attribute Unrestricted_Access::
10251 * Attribute Update::
10252 * Attribute Valid_Scalars::
10253 * Attribute VADS_Size::
10254 * Attribute Value_Size::
10255 * Attribute Wchar_T_Size::
10256 * Attribute Word_Size::
10260 @node Attribute Abort_Signal,Attribute Address_Size,,Implementation Defined Attributes
10261 @anchor{gnat_rm/implementation_defined_attributes attribute-abort-signal}@anchor{16a}
10262 @section Attribute Abort_Signal
10265 @geindex Abort_Signal
10267 @code{Standard'Abort_Signal} (@code{Standard} is the only allowed
10268 prefix) provides the entity for the special exception used to signal
10269 task abort or asynchronous transfer of control. Normally this attribute
10270 should only be used in the tasking runtime (it is highly peculiar, and
10271 completely outside the normal semantics of Ada, for a user program to
10272 intercept the abort exception).
10274 @node Attribute Address_Size,Attribute Asm_Input,Attribute Abort_Signal,Implementation Defined Attributes
10275 @anchor{gnat_rm/implementation_defined_attributes attribute-address-size}@anchor{16b}
10276 @section Attribute Address_Size
10279 @geindex Size of `@w{`}Address`@w{`}
10281 @geindex Address_Size
10283 @code{Standard'Address_Size} (@code{Standard} is the only allowed
10284 prefix) is a static constant giving the number of bits in an
10285 @code{Address}. It is the same value as System.Address'Size,
10286 but has the advantage of being static, while a direct
10287 reference to System.Address'Size is nonstatic because Address
10290 @node Attribute Asm_Input,Attribute Asm_Output,Attribute Address_Size,Implementation Defined Attributes
10291 @anchor{gnat_rm/implementation_defined_attributes attribute-asm-input}@anchor{16c}
10292 @section Attribute Asm_Input
10297 The @code{Asm_Input} attribute denotes a function that takes two
10298 parameters. The first is a string, the second is an expression of the
10299 type designated by the prefix. The first (string) argument is required
10300 to be a static expression, and is the constraint for the parameter,
10301 (e.g., what kind of register is required). The second argument is the
10302 value to be used as the input argument. The possible values for the
10303 constant are the same as those used in the RTL, and are dependent on
10304 the configuration file used to built the GCC back end.
10305 @ref{16d,,Machine Code Insertions}
10307 @node Attribute Asm_Output,Attribute Atomic_Always_Lock_Free,Attribute Asm_Input,Implementation Defined Attributes
10308 @anchor{gnat_rm/implementation_defined_attributes attribute-asm-output}@anchor{16e}
10309 @section Attribute Asm_Output
10312 @geindex Asm_Output
10314 The @code{Asm_Output} attribute denotes a function that takes two
10315 parameters. The first is a string, the second is the name of a variable
10316 of the type designated by the attribute prefix. The first (string)
10317 argument is required to be a static expression and designates the
10318 constraint for the parameter (e.g., what kind of register is
10319 required). The second argument is the variable to be updated with the
10320 result. The possible values for constraint are the same as those used in
10321 the RTL, and are dependent on the configuration file used to build the
10322 GCC back end. If there are no output operands, then this argument may
10323 either be omitted, or explicitly given as @code{No_Output_Operands}.
10324 @ref{16d,,Machine Code Insertions}
10326 @node Attribute Atomic_Always_Lock_Free,Attribute Bit,Attribute Asm_Output,Implementation Defined Attributes
10327 @anchor{gnat_rm/implementation_defined_attributes attribute-atomic-always-lock-free}@anchor{16f}
10328 @section Attribute Atomic_Always_Lock_Free
10331 @geindex Atomic_Always_Lock_Free
10333 The prefix of the @code{Atomic_Always_Lock_Free} attribute is a type.
10334 The result is a Boolean value which is True if the type has discriminants,
10335 and False otherwise. The result indicate whether atomic operations are
10336 supported by the target for the given type.
10338 @node Attribute Bit,Attribute Bit_Position,Attribute Atomic_Always_Lock_Free,Implementation Defined Attributes
10339 @anchor{gnat_rm/implementation_defined_attributes attribute-bit}@anchor{170}
10340 @section Attribute Bit
10345 @code{obj'Bit}, where @code{obj} is any object, yields the bit
10346 offset within the storage unit (byte) that contains the first bit of
10347 storage allocated for the object. The value of this attribute is of the
10348 type @emph{universal_integer}, and is always a non-negative number not
10349 exceeding the value of @code{System.Storage_Unit}.
10351 For an object that is a variable or a constant allocated in a register,
10352 the value is zero. (The use of this attribute does not force the
10353 allocation of a variable to memory).
10355 For an object that is a formal parameter, this attribute applies
10356 to either the matching actual parameter or to a copy of the
10357 matching actual parameter.
10359 For an access object the value is zero. Note that
10360 @code{obj.all'Bit} is subject to an @code{Access_Check} for the
10361 designated object. Similarly for a record component
10362 @code{X.C'Bit} is subject to a discriminant check and
10363 @code{X(I).Bit} and @code{X(I1..I2)'Bit}
10364 are subject to index checks.
10366 This attribute is designed to be compatible with the DEC Ada 83 definition
10367 and implementation of the @code{Bit} attribute.
10369 @node Attribute Bit_Position,Attribute Code_Address,Attribute Bit,Implementation Defined Attributes
10370 @anchor{gnat_rm/implementation_defined_attributes attribute-bit-position}@anchor{171}
10371 @section Attribute Bit_Position
10374 @geindex Bit_Position
10376 @code{R.C'Bit_Position}, where @code{R} is a record object and @code{C} is one
10377 of the fields of the record type, yields the bit
10378 offset within the record contains the first bit of
10379 storage allocated for the object. The value of this attribute is of the
10380 type @emph{universal_integer}. The value depends only on the field
10381 @code{C} and is independent of the alignment of
10382 the containing record @code{R}.
10384 @node Attribute Code_Address,Attribute Compiler_Version,Attribute Bit_Position,Implementation Defined Attributes
10385 @anchor{gnat_rm/implementation_defined_attributes attribute-code-address}@anchor{172}
10386 @section Attribute Code_Address
10389 @geindex Code_Address
10391 @geindex Subprogram address
10393 @geindex Address of subprogram code
10395 The @code{'Address}
10396 attribute may be applied to subprograms in Ada 95 and Ada 2005, but the
10397 intended effect seems to be to provide
10398 an address value which can be used to call the subprogram by means of
10399 an address clause as in the following example:
10405 for L'Address use K'Address;
10406 pragma Import (Ada, L);
10409 A call to @code{L} is then expected to result in a call to @code{K}.
10410 In Ada 83, where there were no access-to-subprogram values, this was
10411 a common work-around for getting the effect of an indirect call.
10412 GNAT implements the above use of @code{Address} and the technique
10413 illustrated by the example code works correctly.
10415 However, for some purposes, it is useful to have the address of the start
10416 of the generated code for the subprogram. On some architectures, this is
10417 not necessarily the same as the @code{Address} value described above.
10418 For example, the @code{Address} value may reference a subprogram
10419 descriptor rather than the subprogram itself.
10421 The @code{'Code_Address} attribute, which can only be applied to
10422 subprogram entities, always returns the address of the start of the
10423 generated code of the specified subprogram, which may or may not be
10424 the same value as is returned by the corresponding @code{'Address}
10427 @node Attribute Compiler_Version,Attribute Constrained,Attribute Code_Address,Implementation Defined Attributes
10428 @anchor{gnat_rm/implementation_defined_attributes attribute-compiler-version}@anchor{173}
10429 @section Attribute Compiler_Version
10432 @geindex Compiler_Version
10434 @code{Standard'Compiler_Version} (@code{Standard} is the only allowed
10435 prefix) yields a static string identifying the version of the compiler
10436 being used to compile the unit containing the attribute reference.
10438 @node Attribute Constrained,Attribute Default_Bit_Order,Attribute Compiler_Version,Implementation Defined Attributes
10439 @anchor{gnat_rm/implementation_defined_attributes attribute-constrained}@anchor{174}
10440 @section Attribute Constrained
10443 @geindex Constrained
10445 In addition to the usage of this attribute in the Ada RM, GNAT
10446 also permits the use of the @code{'Constrained} attribute
10447 in a generic template
10448 for any type, including types without discriminants. The value of this
10449 attribute in the generic instance when applied to a scalar type or a
10450 record type without discriminants is always @code{True}. This usage is
10451 compatible with older Ada compilers, including notably DEC Ada.
10453 @node Attribute Default_Bit_Order,Attribute Default_Scalar_Storage_Order,Attribute Constrained,Implementation Defined Attributes
10454 @anchor{gnat_rm/implementation_defined_attributes attribute-default-bit-order}@anchor{175}
10455 @section Attribute Default_Bit_Order
10458 @geindex Big endian
10460 @geindex Little endian
10462 @geindex Default_Bit_Order
10464 @code{Standard'Default_Bit_Order} (@code{Standard} is the only
10465 permissible prefix), provides the value @code{System.Default_Bit_Order}
10466 as a @code{Pos} value (0 for @code{High_Order_First}, 1 for
10467 @code{Low_Order_First}). This is used to construct the definition of
10468 @code{Default_Bit_Order} in package @code{System}.
10470 @node Attribute Default_Scalar_Storage_Order,Attribute Deref,Attribute Default_Bit_Order,Implementation Defined Attributes
10471 @anchor{gnat_rm/implementation_defined_attributes attribute-default-scalar-storage-order}@anchor{176}
10472 @section Attribute Default_Scalar_Storage_Order
10475 @geindex Big endian
10477 @geindex Little endian
10479 @geindex Default_Scalar_Storage_Order
10481 @code{Standard'Default_Scalar_Storage_Order} (@code{Standard} is the only
10482 permissible prefix), provides the current value of the default scalar storage
10483 order (as specified using pragma @code{Default_Scalar_Storage_Order}, or
10484 equal to @code{Default_Bit_Order} if unspecified) as a
10485 @code{System.Bit_Order} value. This is a static attribute.
10487 @node Attribute Deref,Attribute Descriptor_Size,Attribute Default_Scalar_Storage_Order,Implementation Defined Attributes
10488 @anchor{gnat_rm/implementation_defined_attributes attribute-deref}@anchor{177}
10489 @section Attribute Deref
10494 The attribute @code{typ'Deref(expr)} where @code{expr} is of type @code{System.Address} yields
10495 the variable of type @code{typ} that is located at the given address. It is similar
10496 to @code{(totyp (expr).all)}, where @code{totyp} is an unchecked conversion from address to
10497 a named access-to-@cite{typ} type, except that it yields a variable, so it can be
10498 used on the left side of an assignment.
10500 @node Attribute Descriptor_Size,Attribute Elaborated,Attribute Deref,Implementation Defined Attributes
10501 @anchor{gnat_rm/implementation_defined_attributes attribute-descriptor-size}@anchor{178}
10502 @section Attribute Descriptor_Size
10505 @geindex Descriptor
10507 @geindex Dope vector
10509 @geindex Descriptor_Size
10511 Nonstatic attribute @code{Descriptor_Size} returns the size in bits of the
10512 descriptor allocated for a type. The result is non-zero only for unconstrained
10513 array types and the returned value is of type universal integer. In GNAT, an
10514 array descriptor contains bounds information and is located immediately before
10515 the first element of the array.
10518 type Unconstr_Array is array (Positive range <>) of Boolean;
10519 Put_Line ("Descriptor size = " & Unconstr_Array'Descriptor_Size'Img);
10522 The attribute takes into account any additional padding due to type alignment.
10523 In the example above, the descriptor contains two values of type
10524 @code{Positive} representing the low and high bound. Since @code{Positive} has
10525 a size of 31 bits and an alignment of 4, the descriptor size is @code{2 * Positive'Size + 2} or 64 bits.
10527 @node Attribute Elaborated,Attribute Elab_Body,Attribute Descriptor_Size,Implementation Defined Attributes
10528 @anchor{gnat_rm/implementation_defined_attributes attribute-elaborated}@anchor{179}
10529 @section Attribute Elaborated
10532 @geindex Elaborated
10534 The prefix of the @code{'Elaborated} attribute must be a unit name. The
10535 value is a Boolean which indicates whether or not the given unit has been
10536 elaborated. This attribute is primarily intended for internal use by the
10537 generated code for dynamic elaboration checking, but it can also be used
10538 in user programs. The value will always be True once elaboration of all
10539 units has been completed. An exception is for units which need no
10540 elaboration, the value is always False for such units.
10542 @node Attribute Elab_Body,Attribute Elab_Spec,Attribute Elaborated,Implementation Defined Attributes
10543 @anchor{gnat_rm/implementation_defined_attributes attribute-elab-body}@anchor{17a}
10544 @section Attribute Elab_Body
10549 This attribute can only be applied to a program unit name. It returns
10550 the entity for the corresponding elaboration procedure for elaborating
10551 the body of the referenced unit. This is used in the main generated
10552 elaboration procedure by the binder and is not normally used in any
10553 other context. However, there may be specialized situations in which it
10554 is useful to be able to call this elaboration procedure from Ada code,
10555 e.g., if it is necessary to do selective re-elaboration to fix some
10558 @node Attribute Elab_Spec,Attribute Elab_Subp_Body,Attribute Elab_Body,Implementation Defined Attributes
10559 @anchor{gnat_rm/implementation_defined_attributes attribute-elab-spec}@anchor{17b}
10560 @section Attribute Elab_Spec
10565 This attribute can only be applied to a program unit name. It returns
10566 the entity for the corresponding elaboration procedure for elaborating
10567 the spec of the referenced unit. This is used in the main
10568 generated elaboration procedure by the binder and is not normally used
10569 in any other context. However, there may be specialized situations in
10570 which it is useful to be able to call this elaboration procedure from
10571 Ada code, e.g., if it is necessary to do selective re-elaboration to fix
10574 @node Attribute Elab_Subp_Body,Attribute Emax,Attribute Elab_Spec,Implementation Defined Attributes
10575 @anchor{gnat_rm/implementation_defined_attributes attribute-elab-subp-body}@anchor{17c}
10576 @section Attribute Elab_Subp_Body
10579 @geindex Elab_Subp_Body
10581 This attribute can only be applied to a library level subprogram
10582 name and is only allowed in CodePeer mode. It returns the entity
10583 for the corresponding elaboration procedure for elaborating the body
10584 of the referenced subprogram unit. This is used in the main generated
10585 elaboration procedure by the binder in CodePeer mode only and is unrecognized
10588 @node Attribute Emax,Attribute Enabled,Attribute Elab_Subp_Body,Implementation Defined Attributes
10589 @anchor{gnat_rm/implementation_defined_attributes attribute-emax}@anchor{17d}
10590 @section Attribute Emax
10593 @geindex Ada 83 attributes
10597 The @code{Emax} attribute is provided for compatibility with Ada 83. See
10598 the Ada 83 reference manual for an exact description of the semantics of
10601 @node Attribute Enabled,Attribute Enum_Rep,Attribute Emax,Implementation Defined Attributes
10602 @anchor{gnat_rm/implementation_defined_attributes attribute-enabled}@anchor{17e}
10603 @section Attribute Enabled
10608 The @code{Enabled} attribute allows an application program to check at compile
10609 time to see if the designated check is currently enabled. The prefix is a
10610 simple identifier, referencing any predefined check name (other than
10611 @code{All_Checks}) or a check name introduced by pragma Check_Name. If
10612 no argument is given for the attribute, the check is for the general state
10613 of the check, if an argument is given, then it is an entity name, and the
10614 check indicates whether an @code{Suppress} or @code{Unsuppress} has been
10615 given naming the entity (if not, then the argument is ignored).
10617 Note that instantiations inherit the check status at the point of the
10618 instantiation, so a useful idiom is to have a library package that
10619 introduces a check name with @code{pragma Check_Name}, and then contains
10620 generic packages or subprograms which use the @code{Enabled} attribute
10621 to see if the check is enabled. A user of this package can then issue
10622 a @code{pragma Suppress} or @code{pragma Unsuppress} before instantiating
10623 the package or subprogram, controlling whether the check will be present.
10625 @node Attribute Enum_Rep,Attribute Enum_Val,Attribute Enabled,Implementation Defined Attributes
10626 @anchor{gnat_rm/implementation_defined_attributes attribute-enum-rep}@anchor{17f}
10627 @section Attribute Enum_Rep
10630 @geindex Representation of enums
10634 For every enumeration subtype @code{S}, @code{S'Enum_Rep} denotes a
10635 function with the following spec:
10638 function S'Enum_Rep (Arg : S'Base) return <Universal_Integer>;
10641 It is also allowable to apply @code{Enum_Rep} directly to an object of an
10642 enumeration type or to a non-overloaded enumeration
10643 literal. In this case @code{S'Enum_Rep} is equivalent to
10644 @code{typ'Enum_Rep(S)} where @code{typ} is the type of the
10645 enumeration literal or object.
10647 The function returns the representation value for the given enumeration
10648 value. This will be equal to value of the @code{Pos} attribute in the
10649 absence of an enumeration representation clause. This is a static
10650 attribute (i.e.,:the result is static if the argument is static).
10652 @code{S'Enum_Rep} can also be used with integer types and objects,
10653 in which case it simply returns the integer value. The reason for this
10654 is to allow it to be used for @code{(<>)} discrete formal arguments in
10655 a generic unit that can be instantiated with either enumeration types
10656 or integer types. Note that if @code{Enum_Rep} is used on a modular
10657 type whose upper bound exceeds the upper bound of the largest signed
10658 integer type, and the argument is a variable, so that the universal
10659 integer calculation is done at run time, then the call to @code{Enum_Rep}
10660 may raise @code{Constraint_Error}.
10662 @node Attribute Enum_Val,Attribute Epsilon,Attribute Enum_Rep,Implementation Defined Attributes
10663 @anchor{gnat_rm/implementation_defined_attributes attribute-enum-val}@anchor{180}
10664 @section Attribute Enum_Val
10667 @geindex Representation of enums
10671 For every enumeration subtype @code{S}, @code{S'Enum_Val} denotes a
10672 function with the following spec:
10675 function S'Enum_Val (Arg : <Universal_Integer>) return S'Base;
10678 The function returns the enumeration value whose representation matches the
10679 argument, or raises Constraint_Error if no enumeration literal of the type
10680 has the matching value.
10681 This will be equal to value of the @code{Val} attribute in the
10682 absence of an enumeration representation clause. This is a static
10683 attribute (i.e., the result is static if the argument is static).
10685 @node Attribute Epsilon,Attribute Fast_Math,Attribute Enum_Val,Implementation Defined Attributes
10686 @anchor{gnat_rm/implementation_defined_attributes attribute-epsilon}@anchor{181}
10687 @section Attribute Epsilon
10690 @geindex Ada 83 attributes
10694 The @code{Epsilon} attribute is provided for compatibility with Ada 83. See
10695 the Ada 83 reference manual for an exact description of the semantics of
10698 @node Attribute Fast_Math,Attribute Finalization_Size,Attribute Epsilon,Implementation Defined Attributes
10699 @anchor{gnat_rm/implementation_defined_attributes attribute-fast-math}@anchor{182}
10700 @section Attribute Fast_Math
10705 @code{Standard'Fast_Math} (@code{Standard} is the only allowed
10706 prefix) yields a static Boolean value that is True if pragma
10707 @code{Fast_Math} is active, and False otherwise.
10709 @node Attribute Finalization_Size,Attribute Fixed_Value,Attribute Fast_Math,Implementation Defined Attributes
10710 @anchor{gnat_rm/implementation_defined_attributes attribute-finalization-size}@anchor{183}
10711 @section Attribute Finalization_Size
10714 @geindex Finalization_Size
10716 The prefix of attribute @code{Finalization_Size} must be an object or
10717 a non-class-wide type. This attribute returns the size of any hidden data
10718 reserved by the compiler to handle finalization-related actions. The type of
10719 the attribute is @emph{universal_integer}.
10721 @code{Finalization_Size} yields a value of zero for a type with no controlled
10722 parts, an object whose type has no controlled parts, or an object of a
10723 class-wide type whose tag denotes a type with no controlled parts.
10725 Note that only heap-allocated objects contain finalization data.
10727 @node Attribute Fixed_Value,Attribute From_Any,Attribute Finalization_Size,Implementation Defined Attributes
10728 @anchor{gnat_rm/implementation_defined_attributes attribute-fixed-value}@anchor{184}
10729 @section Attribute Fixed_Value
10732 @geindex Fixed_Value
10734 For every fixed-point type @code{S}, @code{S'Fixed_Value} denotes a
10735 function with the following specification:
10738 function S'Fixed_Value (Arg : <Universal_Integer>) return S;
10741 The value returned is the fixed-point value @code{V} such that:
10747 The effect is thus similar to first converting the argument to the
10748 integer type used to represent @code{S}, and then doing an unchecked
10749 conversion to the fixed-point type. The difference is
10750 that there are full range checks, to ensure that the result is in range.
10751 This attribute is primarily intended for use in implementation of the
10752 input-output functions for fixed-point values.
10754 @node Attribute From_Any,Attribute Has_Access_Values,Attribute Fixed_Value,Implementation Defined Attributes
10755 @anchor{gnat_rm/implementation_defined_attributes attribute-from-any}@anchor{185}
10756 @section Attribute From_Any
10761 This internal attribute is used for the generation of remote subprogram
10762 stubs in the context of the Distributed Systems Annex.
10764 @node Attribute Has_Access_Values,Attribute Has_Discriminants,Attribute From_Any,Implementation Defined Attributes
10765 @anchor{gnat_rm/implementation_defined_attributes attribute-has-access-values}@anchor{186}
10766 @section Attribute Has_Access_Values
10769 @geindex Access values
10770 @geindex testing for
10772 @geindex Has_Access_Values
10774 The prefix of the @code{Has_Access_Values} attribute is a type. The result
10775 is a Boolean value which is True if the is an access type, or is a composite
10776 type with a component (at any nesting depth) that is an access type, and is
10778 The intended use of this attribute is in conjunction with generic
10779 definitions. If the attribute is applied to a generic private type, it
10780 indicates whether or not the corresponding actual type has access values.
10782 @node Attribute Has_Discriminants,Attribute Img,Attribute Has_Access_Values,Implementation Defined Attributes
10783 @anchor{gnat_rm/implementation_defined_attributes attribute-has-discriminants}@anchor{187}
10784 @section Attribute Has_Discriminants
10787 @geindex Discriminants
10788 @geindex testing for
10790 @geindex Has_Discriminants
10792 The prefix of the @code{Has_Discriminants} attribute is a type. The result
10793 is a Boolean value which is True if the type has discriminants, and False
10794 otherwise. The intended use of this attribute is in conjunction with generic
10795 definitions. If the attribute is applied to a generic private type, it
10796 indicates whether or not the corresponding actual type has discriminants.
10798 @node Attribute Img,Attribute Integer_Value,Attribute Has_Discriminants,Implementation Defined Attributes
10799 @anchor{gnat_rm/implementation_defined_attributes attribute-img}@anchor{188}
10800 @section Attribute Img
10805 The @code{Img} attribute differs from @code{Image} in that, while both can be
10806 applied directly to an object, @code{Img} cannot be applied to types.
10808 Example usage of the attribute:
10811 Put_Line ("X = " & X'Img);
10814 which has the same meaning as the more verbose:
10817 Put_Line ("X = " & T'Image (X));
10820 where @code{T} is the (sub)type of the object @code{X}.
10822 Note that technically, in analogy to @code{Image},
10823 @code{X'Img} returns a parameterless function
10824 that returns the appropriate string when called. This means that
10825 @code{X'Img} can be renamed as a function-returning-string, or used
10826 in an instantiation as a function parameter.
10828 @node Attribute Integer_Value,Attribute Invalid_Value,Attribute Img,Implementation Defined Attributes
10829 @anchor{gnat_rm/implementation_defined_attributes attribute-integer-value}@anchor{189}
10830 @section Attribute Integer_Value
10833 @geindex Integer_Value
10835 For every integer type @code{S}, @code{S'Integer_Value} denotes a
10836 function with the following spec:
10839 function S'Integer_Value (Arg : <Universal_Fixed>) return S;
10842 The value returned is the integer value @code{V}, such that:
10848 where @code{T} is the type of @code{Arg}.
10849 The effect is thus similar to first doing an unchecked conversion from
10850 the fixed-point type to its corresponding implementation type, and then
10851 converting the result to the target integer type. The difference is
10852 that there are full range checks, to ensure that the result is in range.
10853 This attribute is primarily intended for use in implementation of the
10854 standard input-output functions for fixed-point values.
10856 @node Attribute Invalid_Value,Attribute Iterable,Attribute Integer_Value,Implementation Defined Attributes
10857 @anchor{gnat_rm/implementation_defined_attributes attribute-invalid-value}@anchor{18a}
10858 @section Attribute Invalid_Value
10861 @geindex Invalid_Value
10863 For every scalar type S, S'Invalid_Value returns an undefined value of the
10864 type. If possible this value is an invalid representation for the type. The
10865 value returned is identical to the value used to initialize an otherwise
10866 uninitialized value of the type if pragma Initialize_Scalars is used,
10867 including the ability to modify the value with the binder -Sxx flag and
10868 relevant environment variables at run time.
10870 @node Attribute Iterable,Attribute Large,Attribute Invalid_Value,Implementation Defined Attributes
10871 @anchor{gnat_rm/implementation_defined_attributes attribute-iterable}@anchor{18b}
10872 @section Attribute Iterable
10877 Equivalent to Aspect Iterable.
10879 @node Attribute Large,Attribute Library_Level,Attribute Iterable,Implementation Defined Attributes
10880 @anchor{gnat_rm/implementation_defined_attributes attribute-large}@anchor{18c}
10881 @section Attribute Large
10884 @geindex Ada 83 attributes
10888 The @code{Large} attribute is provided for compatibility with Ada 83. See
10889 the Ada 83 reference manual for an exact description of the semantics of
10892 @node Attribute Library_Level,Attribute Lock_Free,Attribute Large,Implementation Defined Attributes
10893 @anchor{gnat_rm/implementation_defined_attributes attribute-library-level}@anchor{18d}
10894 @section Attribute Library_Level
10897 @geindex Library_Level
10899 @code{P'Library_Level}, where P is an entity name,
10900 returns a Boolean value which is True if the entity is declared
10901 at the library level, and False otherwise. Note that within a
10902 generic instantition, the name of the generic unit denotes the
10903 instance, which means that this attribute can be used to test
10904 if a generic is instantiated at the library level, as shown
10911 pragma Compile_Time_Error
10912 (not Gen'Library_Level,
10913 "Gen can only be instantiated at library level");
10918 @node Attribute Lock_Free,Attribute Loop_Entry,Attribute Library_Level,Implementation Defined Attributes
10919 @anchor{gnat_rm/implementation_defined_attributes attribute-lock-free}@anchor{18e}
10920 @section Attribute Lock_Free
10925 @code{P'Lock_Free}, where P is a protected object, returns True if a
10926 pragma @code{Lock_Free} applies to P.
10928 @node Attribute Loop_Entry,Attribute Machine_Size,Attribute Lock_Free,Implementation Defined Attributes
10929 @anchor{gnat_rm/implementation_defined_attributes attribute-loop-entry}@anchor{18f}
10930 @section Attribute Loop_Entry
10933 @geindex Loop_Entry
10938 X'Loop_Entry [(loop_name)]
10941 The @code{Loop_Entry} attribute is used to refer to the value that an
10942 expression had upon entry to a given loop in much the same way that the
10943 @code{Old} attribute in a subprogram postcondition can be used to refer
10944 to the value an expression had upon entry to the subprogram. The
10945 relevant loop is either identified by the given loop name, or it is the
10946 innermost enclosing loop when no loop name is given.
10948 A @code{Loop_Entry} attribute can only occur within a
10949 @code{Loop_Variant} or @code{Loop_Invariant} pragma. A common use of
10950 @code{Loop_Entry} is to compare the current value of objects with their
10951 initial value at loop entry, in a @code{Loop_Invariant} pragma.
10953 The effect of using @code{X'Loop_Entry} is the same as declaring
10954 a constant initialized with the initial value of @code{X} at loop
10955 entry. This copy is not performed if the loop is not entered, or if the
10956 corresponding pragmas are ignored or disabled.
10958 @node Attribute Machine_Size,Attribute Mantissa,Attribute Loop_Entry,Implementation Defined Attributes
10959 @anchor{gnat_rm/implementation_defined_attributes attribute-machine-size}@anchor{190}
10960 @section Attribute Machine_Size
10963 @geindex Machine_Size
10965 This attribute is identical to the @code{Object_Size} attribute. It is
10966 provided for compatibility with the DEC Ada 83 attribute of this name.
10968 @node Attribute Mantissa,Attribute Maximum_Alignment,Attribute Machine_Size,Implementation Defined Attributes
10969 @anchor{gnat_rm/implementation_defined_attributes attribute-mantissa}@anchor{191}
10970 @section Attribute Mantissa
10973 @geindex Ada 83 attributes
10977 The @code{Mantissa} attribute is provided for compatibility with Ada 83. See
10978 the Ada 83 reference manual for an exact description of the semantics of
10981 @node Attribute Maximum_Alignment,Attribute Mechanism_Code,Attribute Mantissa,Implementation Defined Attributes
10982 @anchor{gnat_rm/implementation_defined_attributes attribute-maximum-alignment}@anchor{192}@anchor{gnat_rm/implementation_defined_attributes id2}@anchor{193}
10983 @section Attribute Maximum_Alignment
10989 @geindex Maximum_Alignment
10991 @code{Standard'Maximum_Alignment} (@code{Standard} is the only
10992 permissible prefix) provides the maximum useful alignment value for the
10993 target. This is a static value that can be used to specify the alignment
10994 for an object, guaranteeing that it is properly aligned in all
10997 @node Attribute Mechanism_Code,Attribute Null_Parameter,Attribute Maximum_Alignment,Implementation Defined Attributes
10998 @anchor{gnat_rm/implementation_defined_attributes attribute-mechanism-code}@anchor{194}
10999 @section Attribute Mechanism_Code
11002 @geindex Return values
11003 @geindex passing mechanism
11005 @geindex Parameters
11006 @geindex passing mechanism
11008 @geindex Mechanism_Code
11010 @code{func'Mechanism_Code} yields an integer code for the
11011 mechanism used for the result of function @code{func}, and
11012 @code{subprog'Mechanism_Code (n)} yields the mechanism
11013 used for formal parameter number @emph{n} (a static integer value, with 1
11014 meaning the first parameter) of subprogram @code{subprog}. The code returned is:
11028 @node Attribute Null_Parameter,Attribute Object_Size,Attribute Mechanism_Code,Implementation Defined Attributes
11029 @anchor{gnat_rm/implementation_defined_attributes attribute-null-parameter}@anchor{195}
11030 @section Attribute Null_Parameter
11033 @geindex Zero address
11036 @geindex Null_Parameter
11038 A reference @code{T'Null_Parameter} denotes an imaginary object of
11039 type or subtype @code{T} allocated at machine address zero. The attribute
11040 is allowed only as the default expression of a formal parameter, or as
11041 an actual expression of a subprogram call. In either case, the
11042 subprogram must be imported.
11044 The identity of the object is represented by the address zero in the
11045 argument list, independent of the passing mechanism (explicit or
11048 This capability is needed to specify that a zero address should be
11049 passed for a record or other composite object passed by reference.
11050 There is no way of indicating this without the @code{Null_Parameter}
11053 @node Attribute Object_Size,Attribute Old,Attribute Null_Parameter,Implementation Defined Attributes
11054 @anchor{gnat_rm/implementation_defined_attributes attribute-object-size}@anchor{148}@anchor{gnat_rm/implementation_defined_attributes id3}@anchor{196}
11055 @section Attribute Object_Size
11059 @geindex used for objects
11061 @geindex Object_Size
11063 The size of an object is not necessarily the same as the size of the type
11064 of an object. This is because by default object sizes are increased to be
11065 a multiple of the alignment of the object. For example,
11066 @code{Natural'Size} is
11067 31, but by default objects of type @code{Natural} will have a size of 32 bits.
11068 Similarly, a record containing an integer and a character:
11077 will have a size of 40 (that is @code{Rec'Size} will be 40). The
11078 alignment will be 4, because of the
11079 integer field, and so the default size of record objects for this type
11080 will be 64 (8 bytes).
11082 If the alignment of the above record is specified to be 1, then the
11083 object size will be 40 (5 bytes). This is true by default, and also
11084 an object size of 40 can be explicitly specified in this case.
11086 A consequence of this capability is that different object sizes can be
11087 given to subtypes that would otherwise be considered in Ada to be
11088 statically matching. But it makes no sense to consider such subtypes
11089 as statically matching. Consequently, GNAT adds a rule
11090 to the static matching rules that requires object sizes to match.
11091 Consider this example:
11094 1. procedure BadAVConvert is
11095 2. type R is new Integer;
11096 3. subtype R1 is R range 1 .. 10;
11097 4. subtype R2 is R range 1 .. 10;
11098 5. for R1'Object_Size use 8;
11099 6. for R2'Object_Size use 16;
11100 7. type R1P is access all R1;
11101 8. type R2P is access all R2;
11102 9. R1PV : R1P := new R1'(4);
11105 12. R2PV := R2P (R1PV);
11107 >>> target designated subtype not compatible with
11108 type "R1" defined at line 3
11113 In the absence of lines 5 and 6,
11114 types @code{R1} and @code{R2} statically match and
11115 hence the conversion on line 12 is legal. But since lines 5 and 6
11116 cause the object sizes to differ, GNAT considers that types
11117 @code{R1} and @code{R2} are not statically matching, and line 12
11118 generates the diagnostic shown above.
11120 Similar additional checks are performed in other contexts requiring
11121 statically matching subtypes.
11123 @node Attribute Old,Attribute Passed_By_Reference,Attribute Object_Size,Implementation Defined Attributes
11124 @anchor{gnat_rm/implementation_defined_attributes attribute-old}@anchor{197}
11125 @section Attribute Old
11130 In addition to the usage of @code{Old} defined in the Ada 2012 RM (usage
11131 within @code{Post} aspect), GNAT also permits the use of this attribute
11132 in implementation defined pragmas @code{Postcondition},
11133 @code{Contract_Cases} and @code{Test_Case}. Also usages of
11134 @code{Old} which would be illegal according to the Ada 2012 RM
11135 definition are allowed under control of
11136 implementation defined pragma @code{Unevaluated_Use_Of_Old}.
11138 @node Attribute Passed_By_Reference,Attribute Pool_Address,Attribute Old,Implementation Defined Attributes
11139 @anchor{gnat_rm/implementation_defined_attributes attribute-passed-by-reference}@anchor{198}
11140 @section Attribute Passed_By_Reference
11143 @geindex Parameters
11144 @geindex when passed by reference
11146 @geindex Passed_By_Reference
11148 @code{typ'Passed_By_Reference} for any subtype @cite{typ} returns
11149 a value of type @code{Boolean} value that is @code{True} if the type is
11150 normally passed by reference and @code{False} if the type is normally
11151 passed by copy in calls. For scalar types, the result is always @code{False}
11152 and is static. For non-scalar types, the result is nonstatic.
11154 @node Attribute Pool_Address,Attribute Range_Length,Attribute Passed_By_Reference,Implementation Defined Attributes
11155 @anchor{gnat_rm/implementation_defined_attributes attribute-pool-address}@anchor{199}
11156 @section Attribute Pool_Address
11159 @geindex Parameters
11160 @geindex when passed by reference
11162 @geindex Pool_Address
11164 @code{X'Pool_Address} for any object @code{X} returns the address
11165 of X within its storage pool. This is the same as
11166 @code{X'Address}, except that for an unconstrained array whose
11167 bounds are allocated just before the first component,
11168 @code{X'Pool_Address} returns the address of those bounds,
11169 whereas @code{X'Address} returns the address of the first
11172 Here, we are interpreting 'storage pool' broadly to mean
11173 @code{wherever the object is allocated}, which could be a
11174 user-defined storage pool,
11175 the global heap, on the stack, or in a static memory area.
11176 For an object created by @code{new}, @code{Ptr.all'Pool_Address} is
11177 what is passed to @code{Allocate} and returned from @code{Deallocate}.
11179 @node Attribute Range_Length,Attribute Restriction_Set,Attribute Pool_Address,Implementation Defined Attributes
11180 @anchor{gnat_rm/implementation_defined_attributes attribute-range-length}@anchor{19a}
11181 @section Attribute Range_Length
11184 @geindex Range_Length
11186 @code{typ'Range_Length} for any discrete type @cite{typ} yields
11187 the number of values represented by the subtype (zero for a null
11188 range). The result is static for static subtypes. @code{Range_Length}
11189 applied to the index subtype of a one dimensional array always gives the
11190 same result as @code{Length} applied to the array itself.
11192 @node Attribute Restriction_Set,Attribute Result,Attribute Range_Length,Implementation Defined Attributes
11193 @anchor{gnat_rm/implementation_defined_attributes attribute-restriction-set}@anchor{19b}
11194 @section Attribute Restriction_Set
11197 @geindex Restriction_Set
11199 @geindex Restrictions
11201 This attribute allows compile time testing of restrictions that
11202 are currently in effect. It is primarily intended for specializing
11203 code in the run-time based on restrictions that are active (e.g.
11204 don't need to save fpt registers if restriction No_Floating_Point
11205 is known to be in effect), but can be used anywhere.
11207 There are two forms:
11210 System'Restriction_Set (partition_boolean_restriction_NAME)
11211 System'Restriction_Set (No_Dependence => library_unit_NAME);
11214 In the case of the first form, the only restriction names
11215 allowed are parameterless restrictions that are checked
11216 for consistency at bind time. For a complete list see the
11217 subtype @code{System.Rident.Partition_Boolean_Restrictions}.
11219 The result returned is True if the restriction is known to
11220 be in effect, and False if the restriction is known not to
11221 be in effect. An important guarantee is that the value of
11222 a Restriction_Set attribute is known to be consistent throughout
11223 all the code of a partition.
11225 This is trivially achieved if the entire partition is compiled
11226 with a consistent set of restriction pragmas. However, the
11227 compilation model does not require this. It is possible to
11228 compile one set of units with one set of pragmas, and another
11229 set of units with another set of pragmas. It is even possible
11230 to compile a spec with one set of pragmas, and then WITH the
11231 same spec with a different set of pragmas. Inconsistencies
11232 in the actual use of the restriction are checked at bind time.
11234 In order to achieve the guarantee of consistency for the
11235 Restriction_Set pragma, we consider that a use of the pragma
11236 that yields False is equivalent to a violation of the
11239 So for example if you write
11242 if System'Restriction_Set (No_Floating_Point) then
11249 And the result is False, so that the else branch is executed,
11250 you can assume that this restriction is not set for any unit
11251 in the partition. This is checked by considering this use of
11252 the restriction pragma to be a violation of the restriction
11253 No_Floating_Point. This means that no other unit can attempt
11254 to set this restriction (if some unit does attempt to set it,
11255 the binder will refuse to bind the partition).
11257 Technical note: The restriction name and the unit name are
11258 intepreted entirely syntactically, as in the corresponding
11259 Restrictions pragma, they are not analyzed semantically,
11260 so they do not have a type.
11262 @node Attribute Result,Attribute Safe_Emax,Attribute Restriction_Set,Implementation Defined Attributes
11263 @anchor{gnat_rm/implementation_defined_attributes attribute-result}@anchor{19c}
11264 @section Attribute Result
11269 @code{function'Result} can only be used with in a Postcondition pragma
11270 for a function. The prefix must be the name of the corresponding function. This
11271 is used to refer to the result of the function in the postcondition expression.
11272 For a further discussion of the use of this attribute and examples of its use,
11273 see the description of pragma Postcondition.
11275 @node Attribute Safe_Emax,Attribute Safe_Large,Attribute Result,Implementation Defined Attributes
11276 @anchor{gnat_rm/implementation_defined_attributes attribute-safe-emax}@anchor{19d}
11277 @section Attribute Safe_Emax
11280 @geindex Ada 83 attributes
11284 The @code{Safe_Emax} attribute is provided for compatibility with Ada 83. See
11285 the Ada 83 reference manual for an exact description of the semantics of
11288 @node Attribute Safe_Large,Attribute Safe_Small,Attribute Safe_Emax,Implementation Defined Attributes
11289 @anchor{gnat_rm/implementation_defined_attributes attribute-safe-large}@anchor{19e}
11290 @section Attribute Safe_Large
11293 @geindex Ada 83 attributes
11295 @geindex Safe_Large
11297 The @code{Safe_Large} attribute is provided for compatibility with Ada 83. See
11298 the Ada 83 reference manual for an exact description of the semantics of
11301 @node Attribute Safe_Small,Attribute Scalar_Storage_Order,Attribute Safe_Large,Implementation Defined Attributes
11302 @anchor{gnat_rm/implementation_defined_attributes attribute-safe-small}@anchor{19f}
11303 @section Attribute Safe_Small
11306 @geindex Ada 83 attributes
11308 @geindex Safe_Small
11310 The @code{Safe_Small} attribute is provided for compatibility with Ada 83. See
11311 the Ada 83 reference manual for an exact description of the semantics of
11314 @node Attribute Scalar_Storage_Order,Attribute Simple_Storage_Pool,Attribute Safe_Small,Implementation Defined Attributes
11315 @anchor{gnat_rm/implementation_defined_attributes id4}@anchor{1a0}@anchor{gnat_rm/implementation_defined_attributes attribute-scalar-storage-order}@anchor{155}
11316 @section Attribute Scalar_Storage_Order
11319 @geindex Endianness
11321 @geindex Scalar storage order
11323 @geindex Scalar_Storage_Order
11325 For every array or record type @code{S}, the representation attribute
11326 @code{Scalar_Storage_Order} denotes the order in which storage elements
11327 that make up scalar components are ordered within S. The value given must
11328 be a static expression of type System.Bit_Order. The following is an example
11329 of the use of this feature:
11332 -- Component type definitions
11334 subtype Yr_Type is Natural range 0 .. 127;
11335 subtype Mo_Type is Natural range 1 .. 12;
11336 subtype Da_Type is Natural range 1 .. 31;
11338 -- Record declaration
11340 type Date is record
11341 Years_Since_1980 : Yr_Type;
11343 Day_Of_Month : Da_Type;
11346 -- Record representation clause
11348 for Date use record
11349 Years_Since_1980 at 0 range 0 .. 6;
11350 Month at 0 range 7 .. 10;
11351 Day_Of_Month at 0 range 11 .. 15;
11354 -- Attribute definition clauses
11356 for Date'Bit_Order use System.High_Order_First;
11357 for Date'Scalar_Storage_Order use System.High_Order_First;
11358 -- If Scalar_Storage_Order is specified, it must be consistent with
11359 -- Bit_Order, so it's best to always define the latter explicitly if
11360 -- the former is used.
11363 Other properties are as for the standard representation attribute @code{Bit_Order}
11364 defined by Ada RM 13.5.3(4). The default is @code{System.Default_Bit_Order}.
11366 For a record type @code{T}, if @code{T'Scalar_Storage_Order} is
11367 specified explicitly, it shall be equal to @code{T'Bit_Order}. Note:
11368 this means that if a @code{Scalar_Storage_Order} attribute definition
11369 clause is not confirming, then the type's @code{Bit_Order} shall be
11370 specified explicitly and set to the same value.
11372 Derived types inherit an explicitly set scalar storage order from their parent
11373 types. This may be overridden for the derived type by giving an explicit scalar
11374 storage order for it. However, for a record extension, the derived type must
11375 have the same scalar storage order as the parent type.
11377 A component of a record type that is itself a record or an array and that does
11378 not start and end on a byte boundary must have have the same scalar storage
11379 order as the record type. A component of a bit-packed array type that is itself
11380 a record or an array must have the same scalar storage order as the array type.
11382 No component of a type that has an explicit @code{Scalar_Storage_Order}
11383 attribute definition may be aliased.
11385 A confirming @code{Scalar_Storage_Order} attribute definition clause (i.e.
11386 with a value equal to @code{System.Default_Bit_Order}) has no effect.
11388 If the opposite storage order is specified, then whenever the value of
11389 a scalar component of an object of type @code{S} is read, the storage
11390 elements of the enclosing machine scalar are first reversed (before
11391 retrieving the component value, possibly applying some shift and mask
11392 operatings on the enclosing machine scalar), and the opposite operation
11393 is done for writes.
11395 In that case, the restrictions set forth in 13.5.1(10.3/2) for scalar components
11396 are relaxed. Instead, the following rules apply:
11402 the underlying storage elements are those at positions
11403 @code{(position + first_bit / storage_element_size) .. (position + (last_bit + storage_element_size - 1) / storage_element_size)}
11406 the sequence of underlying storage elements shall have
11407 a size no greater than the largest machine scalar
11410 the enclosing machine scalar is defined as the smallest machine
11411 scalar starting at a position no greater than
11412 @code{position + first_bit / storage_element_size} and covering
11413 storage elements at least up to @code{position + (last_bit + storage_element_size - 1) / storage_element_size`}
11416 the position of the component is interpreted relative to that machine
11420 If no scalar storage order is specified for a type (either directly, or by
11421 inheritance in the case of a derived type), then the default is normally
11422 the native ordering of the target, but this default can be overridden using
11423 pragma @code{Default_Scalar_Storage_Order}.
11425 If a component of @code{T} is itself of a record or array type, the specfied
11426 @code{Scalar_Storage_Order} does @emph{not} apply to that nested type: an explicit
11427 attribute definition clause must be provided for the component type as well
11430 Note that the scalar storage order only affects the in-memory data
11431 representation. It has no effect on the representation used by stream
11434 Note that debuggers may be unable to display the correct value of scalar
11435 components of a type for which the opposite storage order is specified.
11437 @node Attribute Simple_Storage_Pool,Attribute Small,Attribute Scalar_Storage_Order,Implementation Defined Attributes
11438 @anchor{gnat_rm/implementation_defined_attributes attribute-simple-storage-pool}@anchor{ea}@anchor{gnat_rm/implementation_defined_attributes id5}@anchor{1a1}
11439 @section Attribute Simple_Storage_Pool
11442 @geindex Storage pool
11445 @geindex Simple storage pool
11447 @geindex Simple_Storage_Pool
11449 For every nonformal, nonderived access-to-object type @code{Acc}, the
11450 representation attribute @code{Simple_Storage_Pool} may be specified
11451 via an attribute_definition_clause (or by specifying the equivalent aspect):
11454 My_Pool : My_Simple_Storage_Pool_Type;
11456 type Acc is access My_Data_Type;
11458 for Acc'Simple_Storage_Pool use My_Pool;
11461 The name given in an attribute_definition_clause for the
11462 @code{Simple_Storage_Pool} attribute shall denote a variable of
11463 a 'simple storage pool type' (see pragma @cite{Simple_Storage_Pool_Type}).
11465 The use of this attribute is only allowed for a prefix denoting a type
11466 for which it has been specified. The type of the attribute is the type
11467 of the variable specified as the simple storage pool of the access type,
11468 and the attribute denotes that variable.
11470 It is illegal to specify both @code{Storage_Pool} and @code{Simple_Storage_Pool}
11471 for the same access type.
11473 If the @code{Simple_Storage_Pool} attribute has been specified for an access
11474 type, then applying the @code{Storage_Pool} attribute to the type is flagged
11475 with a warning and its evaluation raises the exception @code{Program_Error}.
11477 If the Simple_Storage_Pool attribute has been specified for an access
11478 type @code{S}, then the evaluation of the attribute @code{S'Storage_Size}
11479 returns the result of calling @code{Storage_Size (S'Simple_Storage_Pool)},
11480 which is intended to indicate the number of storage elements reserved for
11481 the simple storage pool. If the Storage_Size function has not been defined
11482 for the simple storage pool type, then this attribute returns zero.
11484 If an access type @code{S} has a specified simple storage pool of type
11485 @code{SSP}, then the evaluation of an allocator for that access type calls
11486 the primitive @code{Allocate} procedure for type @code{SSP}, passing
11487 @code{S'Simple_Storage_Pool} as the pool parameter. The detailed
11488 semantics of such allocators is the same as those defined for allocators
11489 in section 13.11 of the @cite{Ada Reference Manual}, with the term
11490 @emph{simple storage pool} substituted for @emph{storage pool}.
11492 If an access type @code{S} has a specified simple storage pool of type
11493 @code{SSP}, then a call to an instance of the @code{Ada.Unchecked_Deallocation}
11494 for that access type invokes the primitive @code{Deallocate} procedure
11495 for type @code{SSP}, passing @code{S'Simple_Storage_Pool} as the pool
11496 parameter. The detailed semantics of such unchecked deallocations is the same
11497 as defined in section 13.11.2 of the Ada Reference Manual, except that the
11498 term @emph{simple storage pool} is substituted for @emph{storage pool}.
11500 @node Attribute Small,Attribute Storage_Unit,Attribute Simple_Storage_Pool,Implementation Defined Attributes
11501 @anchor{gnat_rm/implementation_defined_attributes attribute-small}@anchor{1a2}
11502 @section Attribute Small
11505 @geindex Ada 83 attributes
11509 The @code{Small} attribute is defined in Ada 95 (and Ada 2005) only for
11511 GNAT also allows this attribute to be applied to floating-point types
11512 for compatibility with Ada 83. See
11513 the Ada 83 reference manual for an exact description of the semantics of
11514 this attribute when applied to floating-point types.
11516 @node Attribute Storage_Unit,Attribute Stub_Type,Attribute Small,Implementation Defined Attributes
11517 @anchor{gnat_rm/implementation_defined_attributes attribute-storage-unit}@anchor{1a3}
11518 @section Attribute Storage_Unit
11521 @geindex Storage_Unit
11523 @code{Standard'Storage_Unit} (@code{Standard} is the only permissible
11524 prefix) provides the same value as @code{System.Storage_Unit}.
11526 @node Attribute Stub_Type,Attribute System_Allocator_Alignment,Attribute Storage_Unit,Implementation Defined Attributes
11527 @anchor{gnat_rm/implementation_defined_attributes attribute-stub-type}@anchor{1a4}
11528 @section Attribute Stub_Type
11533 The GNAT implementation of remote access-to-classwide types is
11534 organized as described in AARM section E.4 (20.t): a value of an RACW type
11535 (designating a remote object) is represented as a normal access
11536 value, pointing to a "stub" object which in turn contains the
11537 necessary information to contact the designated remote object. A
11538 call on any dispatching operation of such a stub object does the
11539 remote call, if necessary, using the information in the stub object
11540 to locate the target partition, etc.
11542 For a prefix @code{T} that denotes a remote access-to-classwide type,
11543 @code{T'Stub_Type} denotes the type of the corresponding stub objects.
11545 By construction, the layout of @code{T'Stub_Type} is identical to that of
11546 type @code{RACW_Stub_Type} declared in the internal implementation-defined
11547 unit @code{System.Partition_Interface}. Use of this attribute will create
11548 an implicit dependency on this unit.
11550 @node Attribute System_Allocator_Alignment,Attribute Target_Name,Attribute Stub_Type,Implementation Defined Attributes
11551 @anchor{gnat_rm/implementation_defined_attributes attribute-system-allocator-alignment}@anchor{1a5}
11552 @section Attribute System_Allocator_Alignment
11558 @geindex System_Allocator_Alignment
11560 @code{Standard'System_Allocator_Alignment} (@code{Standard} is the only
11561 permissible prefix) provides the observable guaranted to be honored by
11562 the system allocator (malloc). This is a static value that can be used
11563 in user storage pools based on malloc either to reject allocation
11564 with alignment too large or to enable a realignment circuitry if the
11565 alignment request is larger than this value.
11567 @node Attribute Target_Name,Attribute To_Address,Attribute System_Allocator_Alignment,Implementation Defined Attributes
11568 @anchor{gnat_rm/implementation_defined_attributes attribute-target-name}@anchor{1a6}
11569 @section Attribute Target_Name
11572 @geindex Target_Name
11574 @code{Standard'Target_Name} (@code{Standard} is the only permissible
11575 prefix) provides a static string value that identifies the target
11576 for the current compilation. For GCC implementations, this is the
11577 standard gcc target name without the terminating slash (for
11578 example, GNAT 5.0 on windows yields "i586-pc-mingw32msv").
11580 @node Attribute To_Address,Attribute To_Any,Attribute Target_Name,Implementation Defined Attributes
11581 @anchor{gnat_rm/implementation_defined_attributes attribute-to-address}@anchor{1a7}
11582 @section Attribute To_Address
11585 @geindex To_Address
11587 The @code{System'To_Address}
11588 (@code{System} is the only permissible prefix)
11589 denotes a function identical to
11590 @code{System.Storage_Elements.To_Address} except that
11591 it is a static attribute. This means that if its argument is
11592 a static expression, then the result of the attribute is a
11593 static expression. This means that such an expression can be
11594 used in contexts (e.g., preelaborable packages) which require a
11595 static expression and where the function call could not be used
11596 (since the function call is always nonstatic, even if its
11597 argument is static). The argument must be in the range
11598 -(2**(m-1)) .. 2**m-1, where m is the memory size
11599 (typically 32 or 64). Negative values are intepreted in a
11600 modular manner (e.g., -1 means the same as 16#FFFF_FFFF# on
11601 a 32 bits machine).
11603 @node Attribute To_Any,Attribute Type_Class,Attribute To_Address,Implementation Defined Attributes
11604 @anchor{gnat_rm/implementation_defined_attributes attribute-to-any}@anchor{1a8}
11605 @section Attribute To_Any
11610 This internal attribute is used for the generation of remote subprogram
11611 stubs in the context of the Distributed Systems Annex.
11613 @node Attribute Type_Class,Attribute Type_Key,Attribute To_Any,Implementation Defined Attributes
11614 @anchor{gnat_rm/implementation_defined_attributes attribute-type-class}@anchor{1a9}
11615 @section Attribute Type_Class
11618 @geindex Type_Class
11620 @code{typ'Type_Class} for any type or subtype @cite{typ} yields
11621 the value of the type class for the full type of @cite{typ}. If
11622 @cite{typ} is a generic formal type, the value is the value for the
11623 corresponding actual subtype. The value of this attribute is of type
11624 @code{System.Aux_DEC.Type_Class}, which has the following definition:
11628 (Type_Class_Enumeration,
11629 Type_Class_Integer,
11630 Type_Class_Fixed_Point,
11631 Type_Class_Floating_Point,
11636 Type_Class_Address);
11639 Protected types yield the value @code{Type_Class_Task}, which thus
11640 applies to all concurrent types. This attribute is designed to
11641 be compatible with the DEC Ada 83 attribute of the same name.
11643 @node Attribute Type_Key,Attribute TypeCode,Attribute Type_Class,Implementation Defined Attributes
11644 @anchor{gnat_rm/implementation_defined_attributes attribute-type-key}@anchor{1aa}
11645 @section Attribute Type_Key
11650 The @code{Type_Key} attribute is applicable to a type or subtype and
11651 yields a value of type Standard.String containing encoded information
11652 about the type or subtype. This provides improved compatibility with
11653 other implementations that support this attribute.
11655 @node Attribute TypeCode,Attribute Unconstrained_Array,Attribute Type_Key,Implementation Defined Attributes
11656 @anchor{gnat_rm/implementation_defined_attributes attribute-typecode}@anchor{1ab}
11657 @section Attribute TypeCode
11662 This internal attribute is used for the generation of remote subprogram
11663 stubs in the context of the Distributed Systems Annex.
11665 @node Attribute Unconstrained_Array,Attribute Universal_Literal_String,Attribute TypeCode,Implementation Defined Attributes
11666 @anchor{gnat_rm/implementation_defined_attributes attribute-unconstrained-array}@anchor{1ac}
11667 @section Attribute Unconstrained_Array
11670 @geindex Unconstrained_Array
11672 The @code{Unconstrained_Array} attribute can be used with a prefix that
11673 denotes any type or subtype. It is a static attribute that yields
11674 @code{True} if the prefix designates an unconstrained array,
11675 and @code{False} otherwise. In a generic instance, the result is
11676 still static, and yields the result of applying this test to the
11679 @node Attribute Universal_Literal_String,Attribute Unrestricted_Access,Attribute Unconstrained_Array,Implementation Defined Attributes
11680 @anchor{gnat_rm/implementation_defined_attributes attribute-universal-literal-string}@anchor{1ad}
11681 @section Attribute Universal_Literal_String
11684 @geindex Named numbers
11685 @geindex representation of
11687 @geindex Universal_Literal_String
11689 The prefix of @code{Universal_Literal_String} must be a named
11690 number. The static result is the string consisting of the characters of
11691 the number as defined in the original source. This allows the user
11692 program to access the actual text of named numbers without intermediate
11693 conversions and without the need to enclose the strings in quotes (which
11694 would preclude their use as numbers).
11696 For example, the following program prints the first 50 digits of pi:
11699 with Text_IO; use Text_IO;
11703 Put (Ada.Numerics.Pi'Universal_Literal_String);
11707 @node Attribute Unrestricted_Access,Attribute Update,Attribute Universal_Literal_String,Implementation Defined Attributes
11708 @anchor{gnat_rm/implementation_defined_attributes attribute-unrestricted-access}@anchor{1ae}
11709 @section Attribute Unrestricted_Access
11713 @geindex unrestricted
11715 @geindex Unrestricted_Access
11717 The @code{Unrestricted_Access} attribute is similar to @code{Access}
11718 except that all accessibility and aliased view checks are omitted. This
11719 is a user-beware attribute.
11721 For objects, it is similar to @code{Address}, for which it is a
11722 desirable replacement where the value desired is an access type.
11723 In other words, its effect is similar to first applying the
11724 @code{Address} attribute and then doing an unchecked conversion to a
11725 desired access type.
11727 For subprograms, @code{P'Unrestricted_Access} may be used where
11728 @code{P'Access} would be illegal, to construct a value of a
11729 less-nested named access type that designates a more-nested
11730 subprogram. This value may be used in indirect calls, so long as the
11731 more-nested subprogram still exists; once the subprogram containing it
11732 has returned, such calls are erroneous. For example:
11737 type Less_Nested is not null access procedure;
11738 Global : Less_Nested;
11746 Local_Var : Integer;
11748 procedure More_Nested is
11753 Global := More_Nested'Unrestricted_Access;
11760 When P1 is called from P2, the call via Global is OK, but if P1 were
11761 called after P2 returns, it would be an erroneous use of a dangling
11764 For objects, it is possible to use @code{Unrestricted_Access} for any
11765 type. However, if the result is of an access-to-unconstrained array
11766 subtype, then the resulting pointer has the same scope as the context
11767 of the attribute, and must not be returned to some enclosing scope.
11768 For instance, if a function uses @code{Unrestricted_Access} to create
11769 an access-to-unconstrained-array and returns that value to the caller,
11770 the result will involve dangling pointers. In addition, it is only
11771 valid to create pointers to unconstrained arrays using this attribute
11772 if the pointer has the normal default 'fat' representation where a
11773 pointer has two components, one points to the array and one points to
11774 the bounds. If a size clause is used to force 'thin' representation
11775 for a pointer to unconstrained where there is only space for a single
11776 pointer, then the resulting pointer is not usable.
11778 In the simple case where a direct use of Unrestricted_Access attempts
11779 to make a thin pointer for a non-aliased object, the compiler will
11780 reject the use as illegal, as shown in the following example:
11783 with System; use System;
11784 procedure SliceUA2 is
11785 type A is access all String;
11786 for A'Size use Standard'Address_Size;
11788 procedure P (Arg : A) is
11793 X : String := "hello world!";
11794 X2 : aliased String := "hello world!";
11796 AV : A := X'Unrestricted_Access; -- ERROR
11798 >>> illegal use of Unrestricted_Access attribute
11799 >>> attempt to generate thin pointer to unaliased object
11802 P (X'Unrestricted_Access); -- ERROR
11804 >>> illegal use of Unrestricted_Access attribute
11805 >>> attempt to generate thin pointer to unaliased object
11807 P (X(7 .. 12)'Unrestricted_Access); -- ERROR
11809 >>> illegal use of Unrestricted_Access attribute
11810 >>> attempt to generate thin pointer to unaliased object
11812 P (X2'Unrestricted_Access); -- OK
11816 but other cases cannot be detected by the compiler, and are
11817 considered to be erroneous. Consider the following example:
11820 with System; use System;
11821 with System; use System;
11822 procedure SliceUA is
11823 type AF is access all String;
11825 type A is access all String;
11826 for A'Size use Standard'Address_Size;
11828 procedure P (Arg : A) is
11830 if Arg'Length /= 6 then
11831 raise Program_Error;
11835 X : String := "hello world!";
11836 Y : AF := X (7 .. 12)'Unrestricted_Access;
11843 A normal unconstrained array value
11844 or a constrained array object marked as aliased has the bounds in memory
11845 just before the array, so a thin pointer can retrieve both the data and
11846 the bounds. But in this case, the non-aliased object @code{X} does not have the
11847 bounds before the string. If the size clause for type @code{A}
11848 were not present, then the pointer
11849 would be a fat pointer, where one component is a pointer to the bounds,
11850 and all would be well. But with the size clause present, the conversion from
11851 fat pointer to thin pointer in the call loses the bounds, and so this
11852 is erroneous, and the program likely raises a @code{Program_Error} exception.
11854 In general, it is advisable to completely
11855 avoid mixing the use of thin pointers and the use of
11856 @code{Unrestricted_Access} where the designated type is an
11857 unconstrained array. The use of thin pointers should be restricted to
11858 cases of porting legacy code that implicitly assumes the size of pointers,
11859 and such code should not in any case be using this attribute.
11861 Another erroneous situation arises if the attribute is
11862 applied to a constant. The resulting pointer can be used to access the
11863 constant, but the effect of trying to modify a constant in this manner
11864 is not well-defined. Consider this example:
11867 P : constant Integer := 4;
11868 type R is access all Integer;
11869 RV : R := P'Unrestricted_Access;
11874 Here we attempt to modify the constant P from 4 to 3, but the compiler may
11875 or may not notice this attempt, and subsequent references to P may yield
11876 either the value 3 or the value 4 or the assignment may blow up if the
11877 compiler decides to put P in read-only memory. One particular case where
11878 @code{Unrestricted_Access} can be used in this way is to modify the
11879 value of an @code{in} parameter:
11882 procedure K (S : in String) is
11883 type R is access all Character;
11884 RV : R := S (3)'Unrestricted_Access;
11890 In general this is a risky approach. It may appear to "work" but such uses of
11891 @code{Unrestricted_Access} are potentially non-portable, even from one version
11892 of GNAT to another, so are best avoided if possible.
11894 @node Attribute Update,Attribute Valid_Scalars,Attribute Unrestricted_Access,Implementation Defined Attributes
11895 @anchor{gnat_rm/implementation_defined_attributes attribute-update}@anchor{1af}
11896 @section Attribute Update
11901 The @code{Update} attribute creates a copy of an array or record value
11902 with one or more modified components. The syntax is:
11905 PREFIX'Update ( RECORD_COMPONENT_ASSOCIATION_LIST )
11906 PREFIX'Update ( ARRAY_COMPONENT_ASSOCIATION @{, ARRAY_COMPONENT_ASSOCIATION @} )
11907 PREFIX'Update ( MULTIDIMENSIONAL_ARRAY_COMPONENT_ASSOCIATION
11908 @{, MULTIDIMENSIONAL_ARRAY_COMPONENT_ASSOCIATION @} )
11910 MULTIDIMENSIONAL_ARRAY_COMPONENT_ASSOCIATION ::= INDEX_EXPRESSION_LIST_LIST => EXPRESSION
11911 INDEX_EXPRESSION_LIST_LIST ::= INDEX_EXPRESSION_LIST @{| INDEX_EXPRESSION_LIST @}
11912 INDEX_EXPRESSION_LIST ::= ( EXPRESSION @{, EXPRESSION @} )
11915 where @code{PREFIX} is the name of an array or record object, the
11916 association list in parentheses does not contain an @code{others}
11917 choice and the box symbol @code{<>} may not appear in any
11918 expression. The effect is to yield a copy of the array or record value
11919 which is unchanged apart from the components mentioned in the
11920 association list, which are changed to the indicated value. The
11921 original value of the array or record value is not affected. For
11925 type Arr is Array (1 .. 5) of Integer;
11927 Avar1 : Arr := (1,2,3,4,5);
11928 Avar2 : Arr := Avar1'Update (2 => 10, 3 .. 4 => 20);
11931 yields a value for @code{Avar2} of 1,10,20,20,5 with @code{Avar1}
11932 begin unmodified. Similarly:
11935 type Rec is A, B, C : Integer;
11937 Rvar1 : Rec := (A => 1, B => 2, C => 3);
11938 Rvar2 : Rec := Rvar1'Update (B => 20);
11941 yields a value for @code{Rvar2} of (A => 1, B => 20, C => 3),
11942 with @code{Rvar1} being unmodifed.
11943 Note that the value of the attribute reference is computed
11944 completely before it is used. This means that if you write:
11947 Avar1 := Avar1'Update (1 => 10, 2 => Function_Call);
11950 then the value of @code{Avar1} is not modified if @code{Function_Call}
11951 raises an exception, unlike the effect of a series of direct assignments
11952 to elements of @code{Avar1}. In general this requires that
11953 two extra complete copies of the object are required, which should be
11954 kept in mind when considering efficiency.
11956 The @code{Update} attribute cannot be applied to prefixes of a limited
11957 type, and cannot reference discriminants in the case of a record type.
11958 The accessibility level of an Update attribute result object is defined
11959 as for an aggregate.
11961 In the record case, no component can be mentioned more than once. In
11962 the array case, two overlapping ranges can appear in the association list,
11963 in which case the modifications are processed left to right.
11965 Multi-dimensional arrays can be modified, as shown by this example:
11968 A : array (1 .. 10, 1 .. 10) of Integer;
11970 A := A'Update ((1, 2) => 20, (3, 4) => 30);
11973 which changes element (1,2) to 20 and (3,4) to 30.
11975 @node Attribute Valid_Scalars,Attribute VADS_Size,Attribute Update,Implementation Defined Attributes
11976 @anchor{gnat_rm/implementation_defined_attributes attribute-valid-scalars}@anchor{1b0}
11977 @section Attribute Valid_Scalars
11980 @geindex Valid_Scalars
11982 The @code{'Valid_Scalars} attribute is intended to make it easier to check the
11983 validity of scalar subcomponents of composite objects. The attribute is defined
11984 for any prefix @code{P} which denotes an object. Prefix @code{P} can be any type
11985 except for tagged private or @code{Unchecked_Union} types. The value of the
11986 attribute is of type @code{Boolean}.
11988 @code{P'Valid_Scalars} yields @code{True} if and only if the evaluation of
11989 @code{C'Valid} yields @code{True} for every scalar subcomponent @code{C} of @code{P}, or if
11990 @code{P} has no scalar subcomponents. Attribute @code{'Valid_Scalars} is equivalent
11991 to attribute @code{'Valid} for scalar types.
11993 It is not specified in what order the subcomponents are checked, nor whether
11994 any more are checked after any one of them is determined to be invalid. If the
11995 prefix @code{P} is of a class-wide type @code{T'Class} (where @code{T} is the associated
11996 specific type), or if the prefix @code{P} is of a specific tagged type @code{T}, then
11997 only the subcomponents of @code{T} are checked; in other words, components of
11998 extensions of @code{T} are not checked even if @code{T'Class (P)'Tag /= T'Tag}.
12000 The compiler will issue a warning if it can be determined at compile time that
12001 the prefix of the attribute has no scalar subcomponents.
12003 Note: @code{Valid_Scalars} can generate a lot of code, especially in the case of
12004 a large variant record. If the attribute is called in many places in the same
12005 program applied to objects of the same type, it can reduce program size to
12006 write a function with a single use of the attribute, and then call that
12007 function from multiple places.
12009 @node Attribute VADS_Size,Attribute Value_Size,Attribute Valid_Scalars,Implementation Defined Attributes
12010 @anchor{gnat_rm/implementation_defined_attributes attribute-vads-size}@anchor{1b1}
12011 @section Attribute VADS_Size
12015 @geindex VADS compatibility
12019 The @code{'VADS_Size} attribute is intended to make it easier to port
12020 legacy code which relies on the semantics of @code{'Size} as implemented
12021 by the VADS Ada 83 compiler. GNAT makes a best effort at duplicating the
12022 same semantic interpretation. In particular, @code{'VADS_Size} applied
12023 to a predefined or other primitive type with no Size clause yields the
12024 Object_Size (for example, @code{Natural'Size} is 32 rather than 31 on
12025 typical machines). In addition @code{'VADS_Size} applied to an object
12026 gives the result that would be obtained by applying the attribute to
12027 the corresponding type.
12029 @node Attribute Value_Size,Attribute Wchar_T_Size,Attribute VADS_Size,Implementation Defined Attributes
12030 @anchor{gnat_rm/implementation_defined_attributes id6}@anchor{1b2}@anchor{gnat_rm/implementation_defined_attributes attribute-value-size}@anchor{164}
12031 @section Attribute Value_Size
12035 @geindex setting for not-first subtype
12037 @geindex Value_Size
12039 @code{type'Value_Size} is the number of bits required to represent
12040 a value of the given subtype. It is the same as @code{type'Size},
12041 but, unlike @code{Size}, may be set for non-first subtypes.
12043 @node Attribute Wchar_T_Size,Attribute Word_Size,Attribute Value_Size,Implementation Defined Attributes
12044 @anchor{gnat_rm/implementation_defined_attributes attribute-wchar-t-size}@anchor{1b3}
12045 @section Attribute Wchar_T_Size
12048 @geindex Wchar_T_Size
12050 @code{Standard'Wchar_T_Size} (@code{Standard} is the only permissible
12051 prefix) provides the size in bits of the C @code{wchar_t} type
12052 primarily for constructing the definition of this type in
12053 package @code{Interfaces.C}. The result is a static constant.
12055 @node Attribute Word_Size,,Attribute Wchar_T_Size,Implementation Defined Attributes
12056 @anchor{gnat_rm/implementation_defined_attributes attribute-word-size}@anchor{1b4}
12057 @section Attribute Word_Size
12062 @code{Standard'Word_Size} (@code{Standard} is the only permissible
12063 prefix) provides the value @code{System.Word_Size}. The result is
12066 @node Standard and Implementation Defined Restrictions,Implementation Advice,Implementation Defined Attributes,Top
12067 @anchor{gnat_rm/standard_and_implementation_defined_restrictions standard-and-implementation-defined-restrictions}@anchor{9}@anchor{gnat_rm/standard_and_implementation_defined_restrictions doc}@anchor{1b5}@anchor{gnat_rm/standard_and_implementation_defined_restrictions id1}@anchor{1b6}
12068 @chapter Standard and Implementation Defined Restrictions
12071 All Ada Reference Manual-defined Restriction identifiers are implemented:
12077 language-defined restrictions (see 13.12.1)
12080 tasking restrictions (see D.7)
12083 high integrity restrictions (see H.4)
12086 GNAT implements additional restriction identifiers. All restrictions, whether
12087 language defined or GNAT-specific, are listed in the following.
12090 * Partition-Wide Restrictions::
12091 * Program Unit Level Restrictions::
12095 @node Partition-Wide Restrictions,Program Unit Level Restrictions,,Standard and Implementation Defined Restrictions
12096 @anchor{gnat_rm/standard_and_implementation_defined_restrictions partition-wide-restrictions}@anchor{1b7}@anchor{gnat_rm/standard_and_implementation_defined_restrictions id2}@anchor{1b8}
12097 @section Partition-Wide Restrictions
12100 There are two separate lists of restriction identifiers. The first
12101 set requires consistency throughout a partition (in other words, if the
12102 restriction identifier is used for any compilation unit in the partition,
12103 then all compilation units in the partition must obey the restriction).
12106 * Immediate_Reclamation::
12107 * Max_Asynchronous_Select_Nesting::
12108 * Max_Entry_Queue_Length::
12109 * Max_Protected_Entries::
12110 * Max_Select_Alternatives::
12111 * Max_Storage_At_Blocking::
12112 * Max_Task_Entries::
12114 * No_Abort_Statements::
12115 * No_Access_Parameter_Allocators::
12116 * No_Access_Subprograms::
12118 * No_Anonymous_Allocators::
12119 * No_Asynchronous_Control::
12121 * No_Coextensions::
12122 * No_Default_Initialization::
12125 * No_Direct_Boolean_Operators::
12127 * No_Dispatching_Calls::
12128 * No_Dynamic_Attachment::
12129 * No_Dynamic_Priorities::
12130 * No_Entry_Calls_In_Elaboration_Code::
12131 * No_Enumeration_Maps::
12132 * No_Exception_Handlers::
12133 * No_Exception_Propagation::
12134 * No_Exception_Registration::
12136 * No_Finalization::
12138 * No_Floating_Point::
12139 * No_Implicit_Conditionals::
12140 * No_Implicit_Dynamic_Code::
12141 * No_Implicit_Heap_Allocations::
12142 * No_Implicit_Protected_Object_Allocations::
12143 * No_Implicit_Task_Allocations::
12144 * No_Initialize_Scalars::
12146 * No_Local_Allocators::
12147 * No_Local_Protected_Objects::
12148 * No_Local_Timing_Events::
12149 * No_Long_Long_Integers::
12150 * No_Multiple_Elaboration::
12151 * No_Nested_Finalization::
12152 * No_Protected_Type_Allocators::
12153 * No_Protected_Types::
12156 * No_Relative_Delay::
12157 * No_Requeue_Statements::
12158 * No_Secondary_Stack::
12159 * No_Select_Statements::
12160 * No_Specific_Termination_Handlers::
12161 * No_Specification_of_Aspect::
12162 * No_Standard_Allocators_After_Elaboration::
12163 * No_Standard_Storage_Pools::
12164 * No_Stream_Optimizations::
12166 * No_Task_Allocators::
12167 * No_Task_At_Interrupt_Priority::
12168 * No_Task_Attributes_Package::
12169 * No_Task_Hierarchy::
12170 * No_Task_Termination::
12172 * No_Terminate_Alternatives::
12173 * No_Unchecked_Access::
12174 * No_Unchecked_Conversion::
12175 * No_Unchecked_Deallocation::
12176 * No_Use_Of_Entity::
12178 * Simple_Barriers::
12179 * Static_Priorities::
12180 * Static_Storage_Size::
12184 @node Immediate_Reclamation,Max_Asynchronous_Select_Nesting,,Partition-Wide Restrictions
12185 @anchor{gnat_rm/standard_and_implementation_defined_restrictions immediate-reclamation}@anchor{1b9}
12186 @subsection Immediate_Reclamation
12189 @geindex Immediate_Reclamation
12191 [RM H.4] This restriction ensures that, except for storage occupied by
12192 objects created by allocators and not deallocated via unchecked
12193 deallocation, any storage reserved at run time for an object is
12194 immediately reclaimed when the object no longer exists.
12196 @node Max_Asynchronous_Select_Nesting,Max_Entry_Queue_Length,Immediate_Reclamation,Partition-Wide Restrictions
12197 @anchor{gnat_rm/standard_and_implementation_defined_restrictions max-asynchronous-select-nesting}@anchor{1ba}
12198 @subsection Max_Asynchronous_Select_Nesting
12201 @geindex Max_Asynchronous_Select_Nesting
12203 [RM D.7] Specifies the maximum dynamic nesting level of asynchronous
12204 selects. Violations of this restriction with a value of zero are
12205 detected at compile time. Violations of this restriction with values
12206 other than zero cause Storage_Error to be raised.
12208 @node Max_Entry_Queue_Length,Max_Protected_Entries,Max_Asynchronous_Select_Nesting,Partition-Wide Restrictions
12209 @anchor{gnat_rm/standard_and_implementation_defined_restrictions max-entry-queue-length}@anchor{1bb}
12210 @subsection Max_Entry_Queue_Length
12213 @geindex Max_Entry_Queue_Length
12215 [RM D.7] This restriction is a declaration that any protected entry compiled in
12216 the scope of the restriction has at most the specified number of
12217 tasks waiting on the entry at any one time, and so no queue is required.
12218 Note that this restriction is checked at run time. Violation of this
12219 restriction results in the raising of Program_Error exception at the point of
12222 @geindex Max_Entry_Queue_Depth
12224 The restriction @code{Max_Entry_Queue_Depth} is recognized as a
12225 synonym for @code{Max_Entry_Queue_Length}. This is retained for historical
12226 compatibility purposes (and a warning will be generated for its use if
12227 warnings on obsolescent features are activated).
12229 @node Max_Protected_Entries,Max_Select_Alternatives,Max_Entry_Queue_Length,Partition-Wide Restrictions
12230 @anchor{gnat_rm/standard_and_implementation_defined_restrictions max-protected-entries}@anchor{1bc}
12231 @subsection Max_Protected_Entries
12234 @geindex Max_Protected_Entries
12236 [RM D.7] Specifies the maximum number of entries per protected type. The
12237 bounds of every entry family of a protected unit shall be static, or shall be
12238 defined by a discriminant of a subtype whose corresponding bound is static.
12240 @node Max_Select_Alternatives,Max_Storage_At_Blocking,Max_Protected_Entries,Partition-Wide Restrictions
12241 @anchor{gnat_rm/standard_and_implementation_defined_restrictions max-select-alternatives}@anchor{1bd}
12242 @subsection Max_Select_Alternatives
12245 @geindex Max_Select_Alternatives
12247 [RM D.7] Specifies the maximum number of alternatives in a selective accept.
12249 @node Max_Storage_At_Blocking,Max_Task_Entries,Max_Select_Alternatives,Partition-Wide Restrictions
12250 @anchor{gnat_rm/standard_and_implementation_defined_restrictions max-storage-at-blocking}@anchor{1be}
12251 @subsection Max_Storage_At_Blocking
12254 @geindex Max_Storage_At_Blocking
12256 [RM D.7] Specifies the maximum portion (in storage elements) of a task's
12257 Storage_Size that can be retained by a blocked task. A violation of this
12258 restriction causes Storage_Error to be raised.
12260 @node Max_Task_Entries,Max_Tasks,Max_Storage_At_Blocking,Partition-Wide Restrictions
12261 @anchor{gnat_rm/standard_and_implementation_defined_restrictions max-task-entries}@anchor{1bf}
12262 @subsection Max_Task_Entries
12265 @geindex Max_Task_Entries
12267 [RM D.7] Specifies the maximum number of entries
12268 per task. The bounds of every entry family
12269 of a task unit shall be static, or shall be
12270 defined by a discriminant of a subtype whose
12271 corresponding bound is static.
12273 @node Max_Tasks,No_Abort_Statements,Max_Task_Entries,Partition-Wide Restrictions
12274 @anchor{gnat_rm/standard_and_implementation_defined_restrictions max-tasks}@anchor{1c0}
12275 @subsection Max_Tasks
12280 [RM D.7] Specifies the maximum number of task that may be created, not
12281 counting the creation of the environment task. Violations of this
12282 restriction with a value of zero are detected at compile
12283 time. Violations of this restriction with values other than zero cause
12284 Storage_Error to be raised.
12286 @node No_Abort_Statements,No_Access_Parameter_Allocators,Max_Tasks,Partition-Wide Restrictions
12287 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-abort-statements}@anchor{1c1}
12288 @subsection No_Abort_Statements
12291 @geindex No_Abort_Statements
12293 [RM D.7] There are no abort_statements, and there are
12294 no calls to Task_Identification.Abort_Task.
12296 @node No_Access_Parameter_Allocators,No_Access_Subprograms,No_Abort_Statements,Partition-Wide Restrictions
12297 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-access-parameter-allocators}@anchor{1c2}
12298 @subsection No_Access_Parameter_Allocators
12301 @geindex No_Access_Parameter_Allocators
12303 [RM H.4] This restriction ensures at compile time that there are no
12304 occurrences of an allocator as the actual parameter to an access
12307 @node No_Access_Subprograms,No_Allocators,No_Access_Parameter_Allocators,Partition-Wide Restrictions
12308 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-access-subprograms}@anchor{1c3}
12309 @subsection No_Access_Subprograms
12312 @geindex No_Access_Subprograms
12314 [RM H.4] This restriction ensures at compile time that there are no
12315 declarations of access-to-subprogram types.
12317 @node No_Allocators,No_Anonymous_Allocators,No_Access_Subprograms,Partition-Wide Restrictions
12318 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-allocators}@anchor{1c4}
12319 @subsection No_Allocators
12322 @geindex No_Allocators
12324 [RM H.4] This restriction ensures at compile time that there are no
12325 occurrences of an allocator.
12327 @node No_Anonymous_Allocators,No_Asynchronous_Control,No_Allocators,Partition-Wide Restrictions
12328 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-anonymous-allocators}@anchor{1c5}
12329 @subsection No_Anonymous_Allocators
12332 @geindex No_Anonymous_Allocators
12334 [RM H.4] This restriction ensures at compile time that there are no
12335 occurrences of an allocator of anonymous access type.
12337 @node No_Asynchronous_Control,No_Calendar,No_Anonymous_Allocators,Partition-Wide Restrictions
12338 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-asynchronous-control}@anchor{1c6}
12339 @subsection No_Asynchronous_Control
12342 @geindex No_Asynchronous_Control
12344 [RM J.13] This restriction ensures at compile time that there are no semantic
12345 dependences on the predefined package Asynchronous_Task_Control.
12347 @node No_Calendar,No_Coextensions,No_Asynchronous_Control,Partition-Wide Restrictions
12348 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-calendar}@anchor{1c7}
12349 @subsection No_Calendar
12352 @geindex No_Calendar
12354 [GNAT] This restriction ensures at compile time that there are no semantic
12355 dependences on package Calendar.
12357 @node No_Coextensions,No_Default_Initialization,No_Calendar,Partition-Wide Restrictions
12358 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-coextensions}@anchor{1c8}
12359 @subsection No_Coextensions
12362 @geindex No_Coextensions
12364 [RM H.4] This restriction ensures at compile time that there are no
12365 coextensions. See 3.10.2.
12367 @node No_Default_Initialization,No_Delay,No_Coextensions,Partition-Wide Restrictions
12368 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-default-initialization}@anchor{1c9}
12369 @subsection No_Default_Initialization
12372 @geindex No_Default_Initialization
12374 [GNAT] This restriction prohibits any instance of default initialization
12375 of variables. The binder implements a consistency rule which prevents
12376 any unit compiled without the restriction from with'ing a unit with the
12377 restriction (this allows the generation of initialization procedures to
12378 be skipped, since you can be sure that no call is ever generated to an
12379 initialization procedure in a unit with the restriction active). If used
12380 in conjunction with Initialize_Scalars or Normalize_Scalars, the effect
12381 is to prohibit all cases of variables declared without a specific
12382 initializer (including the case of OUT scalar parameters).
12384 @node No_Delay,No_Dependence,No_Default_Initialization,Partition-Wide Restrictions
12385 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-delay}@anchor{1ca}
12386 @subsection No_Delay
12391 [RM H.4] This restriction ensures at compile time that there are no
12392 delay statements and no semantic dependences on package Calendar.
12394 @node No_Dependence,No_Direct_Boolean_Operators,No_Delay,Partition-Wide Restrictions
12395 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dependence}@anchor{1cb}
12396 @subsection No_Dependence
12399 @geindex No_Dependence
12401 [RM 13.12.1] This restriction ensures at compile time that there are no
12402 dependences on a library unit.
12404 @node No_Direct_Boolean_Operators,No_Dispatch,No_Dependence,Partition-Wide Restrictions
12405 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-direct-boolean-operators}@anchor{1cc}
12406 @subsection No_Direct_Boolean_Operators
12409 @geindex No_Direct_Boolean_Operators
12411 [GNAT] This restriction ensures that no logical operators (and/or/xor)
12412 are used on operands of type Boolean (or any type derived from Boolean).
12413 This is intended for use in safety critical programs where the certification
12414 protocol requires the use of short-circuit (and then, or else) forms for all
12415 composite boolean operations.
12417 @node No_Dispatch,No_Dispatching_Calls,No_Direct_Boolean_Operators,Partition-Wide Restrictions
12418 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dispatch}@anchor{1cd}
12419 @subsection No_Dispatch
12422 @geindex No_Dispatch
12424 [RM H.4] This restriction ensures at compile time that there are no
12425 occurrences of @code{T'Class}, for any (tagged) subtype @code{T}.
12427 @node No_Dispatching_Calls,No_Dynamic_Attachment,No_Dispatch,Partition-Wide Restrictions
12428 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dispatching-calls}@anchor{1ce}
12429 @subsection No_Dispatching_Calls
12432 @geindex No_Dispatching_Calls
12434 [GNAT] This restriction ensures at compile time that the code generated by the
12435 compiler involves no dispatching calls. The use of this restriction allows the
12436 safe use of record extensions, classwide membership tests and other classwide
12437 features not involving implicit dispatching. This restriction ensures that
12438 the code contains no indirect calls through a dispatching mechanism. Note that
12439 this includes internally-generated calls created by the compiler, for example
12440 in the implementation of class-wide objects assignments. The
12441 membership test is allowed in the presence of this restriction, because its
12442 implementation requires no dispatching.
12443 This restriction is comparable to the official Ada restriction
12444 @code{No_Dispatch} except that it is a bit less restrictive in that it allows
12445 all classwide constructs that do not imply dispatching.
12446 The following example indicates constructs that violate this restriction.
12450 type T is tagged record
12453 procedure P (X : T);
12455 type DT is new T with record
12456 More_Data : Natural;
12458 procedure Q (X : DT);
12462 procedure Example is
12463 procedure Test (O : T'Class) is
12464 N : Natural := O'Size;-- Error: Dispatching call
12465 C : T'Class := O; -- Error: implicit Dispatching Call
12467 if O in DT'Class then -- OK : Membership test
12468 Q (DT (O)); -- OK : Type conversion plus direct call
12470 P (O); -- Error: Dispatching call
12476 P (Obj); -- OK : Direct call
12477 P (T (Obj)); -- OK : Type conversion plus direct call
12478 P (T'Class (Obj)); -- Error: Dispatching call
12480 Test (Obj); -- OK : Type conversion
12482 if Obj in T'Class then -- OK : Membership test
12488 @node No_Dynamic_Attachment,No_Dynamic_Priorities,No_Dispatching_Calls,Partition-Wide Restrictions
12489 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dynamic-attachment}@anchor{1cf}
12490 @subsection No_Dynamic_Attachment
12493 @geindex No_Dynamic_Attachment
12495 [RM D.7] This restriction ensures that there is no call to any of the
12496 operations defined in package Ada.Interrupts
12497 (Is_Reserved, Is_Attached, Current_Handler, Attach_Handler, Exchange_Handler,
12498 Detach_Handler, and Reference).
12500 @geindex No_Dynamic_Interrupts
12502 The restriction @code{No_Dynamic_Interrupts} is recognized as a
12503 synonym for @code{No_Dynamic_Attachment}. This is retained for historical
12504 compatibility purposes (and a warning will be generated for its use if
12505 warnings on obsolescent features are activated).
12507 @node No_Dynamic_Priorities,No_Entry_Calls_In_Elaboration_Code,No_Dynamic_Attachment,Partition-Wide Restrictions
12508 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dynamic-priorities}@anchor{1d0}
12509 @subsection No_Dynamic_Priorities
12512 @geindex No_Dynamic_Priorities
12514 [RM D.7] There are no semantic dependencies on the package Dynamic_Priorities.
12516 @node No_Entry_Calls_In_Elaboration_Code,No_Enumeration_Maps,No_Dynamic_Priorities,Partition-Wide Restrictions
12517 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-entry-calls-in-elaboration-code}@anchor{1d1}
12518 @subsection No_Entry_Calls_In_Elaboration_Code
12521 @geindex No_Entry_Calls_In_Elaboration_Code
12523 [GNAT] This restriction ensures at compile time that no task or protected entry
12524 calls are made during elaboration code. As a result of the use of this
12525 restriction, the compiler can assume that no code past an accept statement
12526 in a task can be executed at elaboration time.
12528 @node No_Enumeration_Maps,No_Exception_Handlers,No_Entry_Calls_In_Elaboration_Code,Partition-Wide Restrictions
12529 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-enumeration-maps}@anchor{1d2}
12530 @subsection No_Enumeration_Maps
12533 @geindex No_Enumeration_Maps
12535 [GNAT] This restriction ensures at compile time that no operations requiring
12536 enumeration maps are used (that is Image and Value attributes applied
12537 to enumeration types).
12539 @node No_Exception_Handlers,No_Exception_Propagation,No_Enumeration_Maps,Partition-Wide Restrictions
12540 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-exception-handlers}@anchor{1d3}
12541 @subsection No_Exception_Handlers
12544 @geindex No_Exception_Handlers
12546 [GNAT] This restriction ensures at compile time that there are no explicit
12547 exception handlers. It also indicates that no exception propagation will
12548 be provided. In this mode, exceptions may be raised but will result in
12549 an immediate call to the last chance handler, a routine that the user
12550 must define with the following profile:
12553 procedure Last_Chance_Handler
12554 (Source_Location : System.Address; Line : Integer);
12555 pragma Export (C, Last_Chance_Handler,
12556 "__gnat_last_chance_handler");
12559 The parameter is a C null-terminated string representing a message to be
12560 associated with the exception (typically the source location of the raise
12561 statement generated by the compiler). The Line parameter when nonzero
12562 represents the line number in the source program where the raise occurs.
12564 @node No_Exception_Propagation,No_Exception_Registration,No_Exception_Handlers,Partition-Wide Restrictions
12565 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-exception-propagation}@anchor{1d4}
12566 @subsection No_Exception_Propagation
12569 @geindex No_Exception_Propagation
12571 [GNAT] This restriction guarantees that exceptions are never propagated
12572 to an outer subprogram scope. The only case in which an exception may
12573 be raised is when the handler is statically in the same subprogram, so
12574 that the effect of a raise is essentially like a goto statement. Any
12575 other raise statement (implicit or explicit) will be considered
12576 unhandled. Exception handlers are allowed, but may not contain an
12577 exception occurrence identifier (exception choice). In addition, use of
12578 the package GNAT.Current_Exception is not permitted, and reraise
12579 statements (raise with no operand) are not permitted.
12581 @node No_Exception_Registration,No_Exceptions,No_Exception_Propagation,Partition-Wide Restrictions
12582 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-exception-registration}@anchor{1d5}
12583 @subsection No_Exception_Registration
12586 @geindex No_Exception_Registration
12588 [GNAT] This restriction ensures at compile time that no stream operations for
12589 types Exception_Id or Exception_Occurrence are used. This also makes it
12590 impossible to pass exceptions to or from a partition with this restriction
12591 in a distributed environment. If this restriction is active, the generated
12592 code is simplified by omitting the otherwise-required global registration
12593 of exceptions when they are declared.
12595 @node No_Exceptions,No_Finalization,No_Exception_Registration,Partition-Wide Restrictions
12596 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-exceptions}@anchor{1d6}
12597 @subsection No_Exceptions
12600 @geindex No_Exceptions
12602 [RM H.4] This restriction ensures at compile time that there are no
12603 raise statements and no exception handlers and also suppresses the
12604 generation of language-defined run-time checks.
12606 @node No_Finalization,No_Fixed_Point,No_Exceptions,Partition-Wide Restrictions
12607 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-finalization}@anchor{1d7}
12608 @subsection No_Finalization
12611 @geindex No_Finalization
12613 [GNAT] This restriction disables the language features described in
12614 chapter 7.6 of the Ada 2005 RM as well as all form of code generation
12615 performed by the compiler to support these features. The following types
12616 are no longer considered controlled when this restriction is in effect:
12622 @code{Ada.Finalization.Controlled}
12625 @code{Ada.Finalization.Limited_Controlled}
12628 Derivations from @code{Controlled} or @code{Limited_Controlled}
12640 Array and record types with controlled components
12643 The compiler no longer generates code to initialize, finalize or adjust an
12644 object or a nested component, either declared on the stack or on the heap. The
12645 deallocation of a controlled object no longer finalizes its contents.
12647 @node No_Fixed_Point,No_Floating_Point,No_Finalization,Partition-Wide Restrictions
12648 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-fixed-point}@anchor{1d8}
12649 @subsection No_Fixed_Point
12652 @geindex No_Fixed_Point
12654 [RM H.4] This restriction ensures at compile time that there are no
12655 occurrences of fixed point types and operations.
12657 @node No_Floating_Point,No_Implicit_Conditionals,No_Fixed_Point,Partition-Wide Restrictions
12658 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-floating-point}@anchor{1d9}
12659 @subsection No_Floating_Point
12662 @geindex No_Floating_Point
12664 [RM H.4] This restriction ensures at compile time that there are no
12665 occurrences of floating point types and operations.
12667 @node No_Implicit_Conditionals,No_Implicit_Dynamic_Code,No_Floating_Point,Partition-Wide Restrictions
12668 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-conditionals}@anchor{1da}
12669 @subsection No_Implicit_Conditionals
12672 @geindex No_Implicit_Conditionals
12674 [GNAT] This restriction ensures that the generated code does not contain any
12675 implicit conditionals, either by modifying the generated code where possible,
12676 or by rejecting any construct that would otherwise generate an implicit
12677 conditional. Note that this check does not include run time constraint
12678 checks, which on some targets may generate implicit conditionals as
12679 well. To control the latter, constraint checks can be suppressed in the
12680 normal manner. Constructs generating implicit conditionals include comparisons
12681 of composite objects and the Max/Min attributes.
12683 @node No_Implicit_Dynamic_Code,No_Implicit_Heap_Allocations,No_Implicit_Conditionals,Partition-Wide Restrictions
12684 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-dynamic-code}@anchor{1db}
12685 @subsection No_Implicit_Dynamic_Code
12688 @geindex No_Implicit_Dynamic_Code
12690 @geindex trampoline
12692 [GNAT] This restriction prevents the compiler from building 'trampolines'.
12693 This is a structure that is built on the stack and contains dynamic
12694 code to be executed at run time. On some targets, a trampoline is
12695 built for the following features: @code{Access},
12696 @code{Unrestricted_Access}, or @code{Address} of a nested subprogram;
12697 nested task bodies; primitive operations of nested tagged types.
12698 Trampolines do not work on machines that prevent execution of stack
12699 data. For example, on windows systems, enabling DEP (data execution
12700 protection) will cause trampolines to raise an exception.
12701 Trampolines are also quite slow at run time.
12703 On many targets, trampolines have been largely eliminated. Look at the
12704 version of system.ads for your target --- if it has
12705 Always_Compatible_Rep equal to False, then trampolines are largely
12706 eliminated. In particular, a trampoline is built for the following
12707 features: @code{Address} of a nested subprogram;
12708 @code{Access} or @code{Unrestricted_Access} of a nested subprogram,
12709 but only if pragma Favor_Top_Level applies, or the access type has a
12710 foreign-language convention; primitive operations of nested tagged
12713 @node No_Implicit_Heap_Allocations,No_Implicit_Protected_Object_Allocations,No_Implicit_Dynamic_Code,Partition-Wide Restrictions
12714 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-heap-allocations}@anchor{1dc}
12715 @subsection No_Implicit_Heap_Allocations
12718 @geindex No_Implicit_Heap_Allocations
12720 [RM D.7] No constructs are allowed to cause implicit heap allocation.
12722 @node No_Implicit_Protected_Object_Allocations,No_Implicit_Task_Allocations,No_Implicit_Heap_Allocations,Partition-Wide Restrictions
12723 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-protected-object-allocations}@anchor{1dd}
12724 @subsection No_Implicit_Protected_Object_Allocations
12727 @geindex No_Implicit_Protected_Object_Allocations
12729 [GNAT] No constructs are allowed to cause implicit heap allocation of a
12732 @node No_Implicit_Task_Allocations,No_Initialize_Scalars,No_Implicit_Protected_Object_Allocations,Partition-Wide Restrictions
12733 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-task-allocations}@anchor{1de}
12734 @subsection No_Implicit_Task_Allocations
12737 @geindex No_Implicit_Task_Allocations
12739 [GNAT] No constructs are allowed to cause implicit heap allocation of a task.
12741 @node No_Initialize_Scalars,No_IO,No_Implicit_Task_Allocations,Partition-Wide Restrictions
12742 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-initialize-scalars}@anchor{1df}
12743 @subsection No_Initialize_Scalars
12746 @geindex No_Initialize_Scalars
12748 [GNAT] This restriction ensures that no unit in the partition is compiled with
12749 pragma Initialize_Scalars. This allows the generation of more efficient
12750 code, and in particular eliminates dummy null initialization routines that
12751 are otherwise generated for some record and array types.
12753 @node No_IO,No_Local_Allocators,No_Initialize_Scalars,Partition-Wide Restrictions
12754 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-io}@anchor{1e0}
12760 [RM H.4] This restriction ensures at compile time that there are no
12761 dependences on any of the library units Sequential_IO, Direct_IO,
12762 Text_IO, Wide_Text_IO, Wide_Wide_Text_IO, or Stream_IO.
12764 @node No_Local_Allocators,No_Local_Protected_Objects,No_IO,Partition-Wide Restrictions
12765 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-local-allocators}@anchor{1e1}
12766 @subsection No_Local_Allocators
12769 @geindex No_Local_Allocators
12771 [RM H.4] This restriction ensures at compile time that there are no
12772 occurrences of an allocator in subprograms, generic subprograms, tasks,
12775 @node No_Local_Protected_Objects,No_Local_Timing_Events,No_Local_Allocators,Partition-Wide Restrictions
12776 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-local-protected-objects}@anchor{1e2}
12777 @subsection No_Local_Protected_Objects
12780 @geindex No_Local_Protected_Objects
12782 [RM D.7] This restriction ensures at compile time that protected objects are
12783 only declared at the library level.
12785 @node No_Local_Timing_Events,No_Long_Long_Integers,No_Local_Protected_Objects,Partition-Wide Restrictions
12786 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-local-timing-events}@anchor{1e3}
12787 @subsection No_Local_Timing_Events
12790 @geindex No_Local_Timing_Events
12792 [RM D.7] All objects of type Ada.Timing_Events.Timing_Event are
12793 declared at the library level.
12795 @node No_Long_Long_Integers,No_Multiple_Elaboration,No_Local_Timing_Events,Partition-Wide Restrictions
12796 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-long-long-integers}@anchor{1e4}
12797 @subsection No_Long_Long_Integers
12800 @geindex No_Long_Long_Integers
12802 [GNAT] This partition-wide restriction forbids any explicit reference to
12803 type Standard.Long_Long_Integer, and also forbids declaring range types whose
12804 implicit base type is Long_Long_Integer, and modular types whose size exceeds
12807 @node No_Multiple_Elaboration,No_Nested_Finalization,No_Long_Long_Integers,Partition-Wide Restrictions
12808 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-multiple-elaboration}@anchor{1e5}
12809 @subsection No_Multiple_Elaboration
12812 @geindex No_Multiple_Elaboration
12814 [GNAT] When this restriction is active and the static elaboration model is
12815 used, and -fpreserve-control-flow is not used, the compiler is allowed to
12816 suppress the elaboration counter normally associated with the unit, even if
12817 the unit has elaboration code. This counter is typically used to check for
12818 access before elaboration and to control multiple elaboration attempts. If the
12819 restriction is used, then the situations in which multiple elaboration is
12820 possible, including non-Ada main programs and Stand Alone libraries, are not
12821 permitted and will be diagnosed by the binder.
12823 @node No_Nested_Finalization,No_Protected_Type_Allocators,No_Multiple_Elaboration,Partition-Wide Restrictions
12824 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-nested-finalization}@anchor{1e6}
12825 @subsection No_Nested_Finalization
12828 @geindex No_Nested_Finalization
12830 [RM D.7] All objects requiring finalization are declared at the library level.
12832 @node No_Protected_Type_Allocators,No_Protected_Types,No_Nested_Finalization,Partition-Wide Restrictions
12833 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-protected-type-allocators}@anchor{1e7}
12834 @subsection No_Protected_Type_Allocators
12837 @geindex No_Protected_Type_Allocators
12839 [RM D.7] This restriction ensures at compile time that there are no allocator
12840 expressions that attempt to allocate protected objects.
12842 @node No_Protected_Types,No_Recursion,No_Protected_Type_Allocators,Partition-Wide Restrictions
12843 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-protected-types}@anchor{1e8}
12844 @subsection No_Protected_Types
12847 @geindex No_Protected_Types
12849 [RM H.4] This restriction ensures at compile time that there are no
12850 declarations of protected types or protected objects.
12852 @node No_Recursion,No_Reentrancy,No_Protected_Types,Partition-Wide Restrictions
12853 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-recursion}@anchor{1e9}
12854 @subsection No_Recursion
12857 @geindex No_Recursion
12859 [RM H.4] A program execution is erroneous if a subprogram is invoked as
12860 part of its execution.
12862 @node No_Reentrancy,No_Relative_Delay,No_Recursion,Partition-Wide Restrictions
12863 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-reentrancy}@anchor{1ea}
12864 @subsection No_Reentrancy
12867 @geindex No_Reentrancy
12869 [RM H.4] A program execution is erroneous if a subprogram is executed by
12870 two tasks at the same time.
12872 @node No_Relative_Delay,No_Requeue_Statements,No_Reentrancy,Partition-Wide Restrictions
12873 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-relative-delay}@anchor{1eb}
12874 @subsection No_Relative_Delay
12877 @geindex No_Relative_Delay
12879 [RM D.7] This restriction ensures at compile time that there are no delay
12880 relative statements and prevents expressions such as @code{delay 1.23;} from
12881 appearing in source code.
12883 @node No_Requeue_Statements,No_Secondary_Stack,No_Relative_Delay,Partition-Wide Restrictions
12884 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-requeue-statements}@anchor{1ec}
12885 @subsection No_Requeue_Statements
12888 @geindex No_Requeue_Statements
12890 [RM D.7] This restriction ensures at compile time that no requeue statements
12891 are permitted and prevents keyword @code{requeue} from being used in source
12894 @geindex No_Requeue
12896 The restriction @code{No_Requeue} is recognized as a
12897 synonym for @code{No_Requeue_Statements}. This is retained for historical
12898 compatibility purposes (and a warning will be generated for its use if
12899 warnings on oNobsolescent features are activated).
12901 @node No_Secondary_Stack,No_Select_Statements,No_Requeue_Statements,Partition-Wide Restrictions
12902 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-secondary-stack}@anchor{1ed}
12903 @subsection No_Secondary_Stack
12906 @geindex No_Secondary_Stack
12908 [GNAT] This restriction ensures at compile time that the generated code
12909 does not contain any reference to the secondary stack. The secondary
12910 stack is used to implement functions returning unconstrained objects
12911 (arrays or records) on some targets. Suppresses the allocation of
12912 secondary stacks for tasks (excluding the environment task) at run time.
12914 @node No_Select_Statements,No_Specific_Termination_Handlers,No_Secondary_Stack,Partition-Wide Restrictions
12915 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-select-statements}@anchor{1ee}
12916 @subsection No_Select_Statements
12919 @geindex No_Select_Statements
12921 [RM D.7] This restriction ensures at compile time no select statements of any
12922 kind are permitted, that is the keyword @code{select} may not appear.
12924 @node No_Specific_Termination_Handlers,No_Specification_of_Aspect,No_Select_Statements,Partition-Wide Restrictions
12925 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-specific-termination-handlers}@anchor{1ef}
12926 @subsection No_Specific_Termination_Handlers
12929 @geindex No_Specific_Termination_Handlers
12931 [RM D.7] There are no calls to Ada.Task_Termination.Set_Specific_Handler
12932 or to Ada.Task_Termination.Specific_Handler.
12934 @node No_Specification_of_Aspect,No_Standard_Allocators_After_Elaboration,No_Specific_Termination_Handlers,Partition-Wide Restrictions
12935 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-specification-of-aspect}@anchor{1f0}
12936 @subsection No_Specification_of_Aspect
12939 @geindex No_Specification_of_Aspect
12941 [RM 13.12.1] This restriction checks at compile time that no aspect
12942 specification, attribute definition clause, or pragma is given for a
12945 @node No_Standard_Allocators_After_Elaboration,No_Standard_Storage_Pools,No_Specification_of_Aspect,Partition-Wide Restrictions
12946 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-standard-allocators-after-elaboration}@anchor{1f1}
12947 @subsection No_Standard_Allocators_After_Elaboration
12950 @geindex No_Standard_Allocators_After_Elaboration
12952 [RM D.7] Specifies that an allocator using a standard storage pool
12953 should never be evaluated at run time after the elaboration of the
12954 library items of the partition has completed. Otherwise, Storage_Error
12957 @node No_Standard_Storage_Pools,No_Stream_Optimizations,No_Standard_Allocators_After_Elaboration,Partition-Wide Restrictions
12958 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-standard-storage-pools}@anchor{1f2}
12959 @subsection No_Standard_Storage_Pools
12962 @geindex No_Standard_Storage_Pools
12964 [GNAT] This restriction ensures at compile time that no access types
12965 use the standard default storage pool. Any access type declared must
12966 have an explicit Storage_Pool attribute defined specifying a
12967 user-defined storage pool.
12969 @node No_Stream_Optimizations,No_Streams,No_Standard_Storage_Pools,Partition-Wide Restrictions
12970 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-stream-optimizations}@anchor{1f3}
12971 @subsection No_Stream_Optimizations
12974 @geindex No_Stream_Optimizations
12976 [GNAT] This restriction affects the performance of stream operations on types
12977 @code{String}, @code{Wide_String} and @code{Wide_Wide_String}. By default, the
12978 compiler uses block reads and writes when manipulating @code{String} objects
12979 due to their superior performance. When this restriction is in effect, the
12980 compiler performs all IO operations on a per-character basis.
12982 @node No_Streams,No_Task_Allocators,No_Stream_Optimizations,Partition-Wide Restrictions
12983 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-streams}@anchor{1f4}
12984 @subsection No_Streams
12987 @geindex No_Streams
12989 [GNAT] This restriction ensures at compile/bind time that there are no
12990 stream objects created and no use of stream attributes.
12991 This restriction does not forbid dependences on the package
12992 @code{Ada.Streams}. So it is permissible to with
12993 @code{Ada.Streams} (or another package that does so itself)
12994 as long as no actual stream objects are created and no
12995 stream attributes are used.
12997 Note that the use of restriction allows optimization of tagged types,
12998 since they do not need to worry about dispatching stream operations.
12999 To take maximum advantage of this space-saving optimization, any
13000 unit declaring a tagged type should be compiled with the restriction,
13001 though this is not required.
13003 @node No_Task_Allocators,No_Task_At_Interrupt_Priority,No_Streams,Partition-Wide Restrictions
13004 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-allocators}@anchor{1f5}
13005 @subsection No_Task_Allocators
13008 @geindex No_Task_Allocators
13010 [RM D.7] There are no allocators for task types
13011 or types containing task subcomponents.
13013 @node No_Task_At_Interrupt_Priority,No_Task_Attributes_Package,No_Task_Allocators,Partition-Wide Restrictions
13014 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-at-interrupt-priority}@anchor{1f6}
13015 @subsection No_Task_At_Interrupt_Priority
13018 @geindex No_Task_At_Interrupt_Priority
13020 [GNAT] This restriction ensures at compile time that there is no
13021 Interrupt_Priority aspect or pragma for a task or a task type. As
13022 a consequence, the tasks are always created with a priority below
13023 that an interrupt priority.
13025 @node No_Task_Attributes_Package,No_Task_Hierarchy,No_Task_At_Interrupt_Priority,Partition-Wide Restrictions
13026 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-attributes-package}@anchor{1f7}
13027 @subsection No_Task_Attributes_Package
13030 @geindex No_Task_Attributes_Package
13032 [GNAT] This restriction ensures at compile time that there are no implicit or
13033 explicit dependencies on the package @code{Ada.Task_Attributes}.
13035 @geindex No_Task_Attributes
13037 The restriction @code{No_Task_Attributes} is recognized as a synonym
13038 for @code{No_Task_Attributes_Package}. This is retained for historical
13039 compatibility purposes (and a warning will be generated for its use if
13040 warnings on obsolescent features are activated).
13042 @node No_Task_Hierarchy,No_Task_Termination,No_Task_Attributes_Package,Partition-Wide Restrictions
13043 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-hierarchy}@anchor{1f8}
13044 @subsection No_Task_Hierarchy
13047 @geindex No_Task_Hierarchy
13049 [RM D.7] All (non-environment) tasks depend
13050 directly on the environment task of the partition.
13052 @node No_Task_Termination,No_Tasking,No_Task_Hierarchy,Partition-Wide Restrictions
13053 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-task-termination}@anchor{1f9}
13054 @subsection No_Task_Termination
13057 @geindex No_Task_Termination
13059 [RM D.7] Tasks that terminate are erroneous.
13061 @node No_Tasking,No_Terminate_Alternatives,No_Task_Termination,Partition-Wide Restrictions
13062 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-tasking}@anchor{1fa}
13063 @subsection No_Tasking
13066 @geindex No_Tasking
13068 [GNAT] This restriction prevents the declaration of tasks or task types
13069 throughout the partition. It is similar in effect to the use of
13070 @code{Max_Tasks => 0} except that violations are caught at compile time
13071 and cause an error message to be output either by the compiler or
13074 @node No_Terminate_Alternatives,No_Unchecked_Access,No_Tasking,Partition-Wide Restrictions
13075 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-terminate-alternatives}@anchor{1fb}
13076 @subsection No_Terminate_Alternatives
13079 @geindex No_Terminate_Alternatives
13081 [RM D.7] There are no selective accepts with terminate alternatives.
13083 @node No_Unchecked_Access,No_Unchecked_Conversion,No_Terminate_Alternatives,Partition-Wide Restrictions
13084 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-unchecked-access}@anchor{1fc}
13085 @subsection No_Unchecked_Access
13088 @geindex No_Unchecked_Access
13090 [RM H.4] This restriction ensures at compile time that there are no
13091 occurrences of the Unchecked_Access attribute.
13093 @node No_Unchecked_Conversion,No_Unchecked_Deallocation,No_Unchecked_Access,Partition-Wide Restrictions
13094 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-unchecked-conversion}@anchor{1fd}
13095 @subsection No_Unchecked_Conversion
13098 @geindex No_Unchecked_Conversion
13100 [RM J.13] This restriction ensures at compile time that there are no semantic
13101 dependences on the predefined generic function Unchecked_Conversion.
13103 @node No_Unchecked_Deallocation,No_Use_Of_Entity,No_Unchecked_Conversion,Partition-Wide Restrictions
13104 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-unchecked-deallocation}@anchor{1fe}
13105 @subsection No_Unchecked_Deallocation
13108 @geindex No_Unchecked_Deallocation
13110 [RM J.13] This restriction ensures at compile time that there are no semantic
13111 dependences on the predefined generic procedure Unchecked_Deallocation.
13113 @node No_Use_Of_Entity,Pure_Barriers,No_Unchecked_Deallocation,Partition-Wide Restrictions
13114 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-use-of-entity}@anchor{1ff}
13115 @subsection No_Use_Of_Entity
13118 @geindex No_Use_Of_Entity
13120 [GNAT] This restriction ensures at compile time that there are no references
13121 to the entity given in the form
13124 No_Use_Of_Entity => Name
13127 where @code{Name} is the fully qualified entity, for example
13130 No_Use_Of_Entity => Ada.Text_IO.Put_Line
13133 @node Pure_Barriers,Simple_Barriers,No_Use_Of_Entity,Partition-Wide Restrictions
13134 @anchor{gnat_rm/standard_and_implementation_defined_restrictions pure-barriers}@anchor{200}
13135 @subsection Pure_Barriers
13138 @geindex Pure_Barriers
13140 [GNAT] This restriction ensures at compile time that protected entry
13141 barriers are restricted to:
13147 components of the protected object (excluding selection from dereferences),
13150 constant declarations,
13156 enumeration literals,
13165 character literals,
13168 implicitly defined comparison operators,
13171 uses of the Standard."not" operator,
13174 short-circuit operator,
13177 the Count attribute
13180 This restriction is a relaxation of the Simple_Barriers restriction,
13181 but still ensures absence of side effects, exceptions, and recursion
13182 during the evaluation of the barriers.
13184 @node Simple_Barriers,Static_Priorities,Pure_Barriers,Partition-Wide Restrictions
13185 @anchor{gnat_rm/standard_and_implementation_defined_restrictions simple-barriers}@anchor{201}
13186 @subsection Simple_Barriers
13189 @geindex Simple_Barriers
13191 [RM D.7] This restriction ensures at compile time that barriers in entry
13192 declarations for protected types are restricted to either static boolean
13193 expressions or references to simple boolean variables defined in the private
13194 part of the protected type. No other form of entry barriers is permitted.
13196 @geindex Boolean_Entry_Barriers
13198 The restriction @code{Boolean_Entry_Barriers} is recognized as a
13199 synonym for @code{Simple_Barriers}. This is retained for historical
13200 compatibility purposes (and a warning will be generated for its use if
13201 warnings on obsolescent features are activated).
13203 @node Static_Priorities,Static_Storage_Size,Simple_Barriers,Partition-Wide Restrictions
13204 @anchor{gnat_rm/standard_and_implementation_defined_restrictions static-priorities}@anchor{202}
13205 @subsection Static_Priorities
13208 @geindex Static_Priorities
13210 [GNAT] This restriction ensures at compile time that all priority expressions
13211 are static, and that there are no dependences on the package
13212 @code{Ada.Dynamic_Priorities}.
13214 @node Static_Storage_Size,,Static_Priorities,Partition-Wide Restrictions
13215 @anchor{gnat_rm/standard_and_implementation_defined_restrictions static-storage-size}@anchor{203}
13216 @subsection Static_Storage_Size
13219 @geindex Static_Storage_Size
13221 [GNAT] This restriction ensures at compile time that any expression appearing
13222 in a Storage_Size pragma or attribute definition clause is static.
13224 @node Program Unit Level Restrictions,,Partition-Wide Restrictions,Standard and Implementation Defined Restrictions
13225 @anchor{gnat_rm/standard_and_implementation_defined_restrictions program-unit-level-restrictions}@anchor{204}@anchor{gnat_rm/standard_and_implementation_defined_restrictions id3}@anchor{205}
13226 @section Program Unit Level Restrictions
13229 The second set of restriction identifiers
13230 does not require partition-wide consistency.
13231 The restriction may be enforced for a single
13232 compilation unit without any effect on any of the
13233 other compilation units in the partition.
13236 * No_Elaboration_Code::
13237 * No_Dynamic_Sized_Objects::
13239 * No_Implementation_Aspect_Specifications::
13240 * No_Implementation_Attributes::
13241 * No_Implementation_Identifiers::
13242 * No_Implementation_Pragmas::
13243 * No_Implementation_Restrictions::
13244 * No_Implementation_Units::
13245 * No_Implicit_Aliasing::
13246 * No_Implicit_Loops::
13247 * No_Obsolescent_Features::
13248 * No_Wide_Characters::
13249 * Static_Dispatch_Tables::
13254 @node No_Elaboration_Code,No_Dynamic_Sized_Objects,,Program Unit Level Restrictions
13255 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-elaboration-code}@anchor{206}
13256 @subsection No_Elaboration_Code
13259 @geindex No_Elaboration_Code
13261 [GNAT] This restriction ensures at compile time that no elaboration code is
13262 generated. Note that this is not the same condition as is enforced
13263 by pragma @code{Preelaborate}. There are cases in which pragma
13264 @code{Preelaborate} still permits code to be generated (e.g., code
13265 to initialize a large array to all zeroes), and there are cases of units
13266 which do not meet the requirements for pragma @code{Preelaborate},
13267 but for which no elaboration code is generated. Generally, it is
13268 the case that preelaborable units will meet the restrictions, with
13269 the exception of large aggregates initialized with an others_clause,
13270 and exception declarations (which generate calls to a run-time
13271 registry procedure). This restriction is enforced on
13272 a unit by unit basis, it need not be obeyed consistently
13273 throughout a partition.
13275 In the case of aggregates with others, if the aggregate has a dynamic
13276 size, there is no way to eliminate the elaboration code (such dynamic
13277 bounds would be incompatible with @code{Preelaborate} in any case). If
13278 the bounds are static, then use of this restriction actually modifies
13279 the code choice of the compiler to avoid generating a loop, and instead
13280 generate the aggregate statically if possible, no matter how many times
13281 the data for the others clause must be repeatedly generated.
13283 It is not possible to precisely document
13284 the constructs which are compatible with this restriction, since,
13285 unlike most other restrictions, this is not a restriction on the
13286 source code, but a restriction on the generated object code. For
13287 example, if the source contains a declaration:
13290 Val : constant Integer := X;
13293 where X is not a static constant, it may be possible, depending
13294 on complex optimization circuitry, for the compiler to figure
13295 out the value of X at compile time, in which case this initialization
13296 can be done by the loader, and requires no initialization code. It
13297 is not possible to document the precise conditions under which the
13298 optimizer can figure this out.
13300 Note that this the implementation of this restriction requires full
13301 code generation. If it is used in conjunction with "semantics only"
13302 checking, then some cases of violations may be missed.
13304 When this restriction is active, we are not requesting control-flow
13305 preservation with -fpreserve-control-flow, and the static elaboration model is
13306 used, the compiler is allowed to suppress the elaboration counter normally
13307 associated with the unit. This counter is typically used to check for access
13308 before elaboration and to control multiple elaboration attempts.
13310 @node No_Dynamic_Sized_Objects,No_Entry_Queue,No_Elaboration_Code,Program Unit Level Restrictions
13311 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-dynamic-sized-objects}@anchor{207}
13312 @subsection No_Dynamic_Sized_Objects
13315 @geindex No_Dynamic_Sized_Objects
13317 [GNAT] This restriction disallows certain constructs that might lead to the
13318 creation of dynamic-sized composite objects (or array or discriminated type).
13319 An array subtype indication is illegal if the bounds are not static
13320 or references to discriminants of an enclosing type.
13321 A discriminated subtype indication is illegal if the type has
13322 discriminant-dependent array components or a variant part, and the
13323 discriminants are not static. In addition, array and record aggregates are
13324 illegal in corresponding cases. Note that this restriction does not forbid
13325 access discriminants. It is often a good idea to combine this restriction
13326 with No_Secondary_Stack.
13328 @node No_Entry_Queue,No_Implementation_Aspect_Specifications,No_Dynamic_Sized_Objects,Program Unit Level Restrictions
13329 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-entry-queue}@anchor{208}
13330 @subsection No_Entry_Queue
13333 @geindex No_Entry_Queue
13335 [GNAT] This restriction is a declaration that any protected entry compiled in
13336 the scope of the restriction has at most one task waiting on the entry
13337 at any one time, and so no queue is required. This restriction is not
13338 checked at compile time. A program execution is erroneous if an attempt
13339 is made to queue a second task on such an entry.
13341 @node No_Implementation_Aspect_Specifications,No_Implementation_Attributes,No_Entry_Queue,Program Unit Level Restrictions
13342 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-aspect-specifications}@anchor{209}
13343 @subsection No_Implementation_Aspect_Specifications
13346 @geindex No_Implementation_Aspect_Specifications
13348 [RM 13.12.1] This restriction checks at compile time that no
13349 GNAT-defined aspects are present. With this restriction, the only
13350 aspects that can be used are those defined in the Ada Reference Manual.
13352 @node No_Implementation_Attributes,No_Implementation_Identifiers,No_Implementation_Aspect_Specifications,Program Unit Level Restrictions
13353 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-attributes}@anchor{20a}
13354 @subsection No_Implementation_Attributes
13357 @geindex No_Implementation_Attributes
13359 [RM 13.12.1] This restriction checks at compile time that no
13360 GNAT-defined attributes are present. With this restriction, the only
13361 attributes that can be used are those defined in the Ada Reference
13364 @node No_Implementation_Identifiers,No_Implementation_Pragmas,No_Implementation_Attributes,Program Unit Level Restrictions
13365 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-identifiers}@anchor{20b}
13366 @subsection No_Implementation_Identifiers
13369 @geindex No_Implementation_Identifiers
13371 [RM 13.12.1] This restriction checks at compile time that no
13372 implementation-defined identifiers (marked with pragma Implementation_Defined)
13373 occur within language-defined packages.
13375 @node No_Implementation_Pragmas,No_Implementation_Restrictions,No_Implementation_Identifiers,Program Unit Level Restrictions
13376 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-pragmas}@anchor{20c}
13377 @subsection No_Implementation_Pragmas
13380 @geindex No_Implementation_Pragmas
13382 [RM 13.12.1] This restriction checks at compile time that no
13383 GNAT-defined pragmas are present. With this restriction, the only
13384 pragmas that can be used are those defined in the Ada Reference Manual.
13386 @node No_Implementation_Restrictions,No_Implementation_Units,No_Implementation_Pragmas,Program Unit Level Restrictions
13387 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-restrictions}@anchor{20d}
13388 @subsection No_Implementation_Restrictions
13391 @geindex No_Implementation_Restrictions
13393 [GNAT] This restriction checks at compile time that no GNAT-defined restriction
13394 identifiers (other than @code{No_Implementation_Restrictions} itself)
13395 are present. With this restriction, the only other restriction identifiers
13396 that can be used are those defined in the Ada Reference Manual.
13398 @node No_Implementation_Units,No_Implicit_Aliasing,No_Implementation_Restrictions,Program Unit Level Restrictions
13399 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implementation-units}@anchor{20e}
13400 @subsection No_Implementation_Units
13403 @geindex No_Implementation_Units
13405 [RM 13.12.1] This restriction checks at compile time that there is no
13406 mention in the context clause of any implementation-defined descendants
13407 of packages Ada, Interfaces, or System.
13409 @node No_Implicit_Aliasing,No_Implicit_Loops,No_Implementation_Units,Program Unit Level Restrictions
13410 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-aliasing}@anchor{20f}
13411 @subsection No_Implicit_Aliasing
13414 @geindex No_Implicit_Aliasing
13416 [GNAT] This restriction, which is not required to be partition-wide consistent,
13417 requires an explicit aliased keyword for an object to which 'Access,
13418 'Unchecked_Access, or 'Address is applied, and forbids entirely the use of
13419 the 'Unrestricted_Access attribute for objects. Note: the reason that
13420 Unrestricted_Access is forbidden is that it would require the prefix
13421 to be aliased, and in such cases, it can always be replaced by
13422 the standard attribute Unchecked_Access which is preferable.
13424 @node No_Implicit_Loops,No_Obsolescent_Features,No_Implicit_Aliasing,Program Unit Level Restrictions
13425 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-implicit-loops}@anchor{210}
13426 @subsection No_Implicit_Loops
13429 @geindex No_Implicit_Loops
13431 [GNAT] This restriction ensures that the generated code of the unit marked
13432 with this restriction does not contain any implicit @code{for} loops, either by
13433 modifying the generated code where possible, or by rejecting any construct
13434 that would otherwise generate an implicit @code{for} loop. If this restriction is
13435 active, it is possible to build large array aggregates with all static
13436 components without generating an intermediate temporary, and without generating
13437 a loop to initialize individual components. Otherwise, a loop is created for
13438 arrays larger than about 5000 scalar components. Note that if this restriction
13439 is set in the spec of a package, it will not apply to its body.
13441 @node No_Obsolescent_Features,No_Wide_Characters,No_Implicit_Loops,Program Unit Level Restrictions
13442 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-obsolescent-features}@anchor{211}
13443 @subsection No_Obsolescent_Features
13446 @geindex No_Obsolescent_Features
13448 [RM 13.12.1] This restriction checks at compile time that no obsolescent
13449 features are used, as defined in Annex J of the Ada Reference Manual.
13451 @node No_Wide_Characters,Static_Dispatch_Tables,No_Obsolescent_Features,Program Unit Level Restrictions
13452 @anchor{gnat_rm/standard_and_implementation_defined_restrictions no-wide-characters}@anchor{212}
13453 @subsection No_Wide_Characters
13456 @geindex No_Wide_Characters
13458 [GNAT] This restriction ensures at compile time that no uses of the types
13459 @code{Wide_Character} or @code{Wide_String} or corresponding wide
13461 appear, and that no wide or wide wide string or character literals
13462 appear in the program (that is literals representing characters not in
13463 type @code{Character}).
13465 @node Static_Dispatch_Tables,SPARK_05,No_Wide_Characters,Program Unit Level Restrictions
13466 @anchor{gnat_rm/standard_and_implementation_defined_restrictions static-dispatch-tables}@anchor{213}
13467 @subsection Static_Dispatch_Tables
13470 @geindex Static_Dispatch_Tables
13472 [GNAT] This restriction checks at compile time that all the artifacts
13473 associated with dispatch tables can be placed in read-only memory.
13475 @node SPARK_05,,Static_Dispatch_Tables,Program Unit Level Restrictions
13476 @anchor{gnat_rm/standard_and_implementation_defined_restrictions spark-05}@anchor{214}
13477 @subsection SPARK_05
13482 [GNAT] This restriction checks at compile time that some constructs forbidden
13483 in SPARK 2005 are not present. Note that SPARK 2005 has been superseded by
13484 SPARK 2014, whose restrictions are checked by the tool GNATprove. To check that
13485 a codebase respects SPARK 2014 restrictions, mark the code with pragma or
13486 aspect @code{SPARK_Mode}, and run the tool GNATprove at Stone assurance level, as
13490 gnatprove -P project.gpr --mode=stone
13496 gnatprove -P project.gpr --mode=check_all
13499 With restriction @code{SPARK_05}, error messages related to SPARK 2005 restriction
13503 violation of restriction "SPARK_05" at <source-location>
13509 The restriction @code{SPARK} is recognized as a synonym for @code{SPARK_05}. This is
13510 retained for historical compatibility purposes (and an unconditional warning
13511 will be generated for its use, advising replacement by @code{SPARK_05}).
13513 This is not a replacement for the semantic checks performed by the
13514 SPARK Examiner tool, as the compiler currently only deals with code,
13515 not SPARK 2005 annotations, and does not guarantee catching all
13516 cases of constructs forbidden by SPARK 2005.
13518 Thus it may well be the case that code which passes the compiler with
13519 the SPARK 2005 restriction is rejected by the SPARK Examiner, e.g. due to
13520 the different visibility rules of the Examiner based on SPARK 2005
13521 @code{inherit} annotations.
13523 This restriction can be useful in providing an initial filter for code
13524 developed using SPARK 2005, or in examining legacy code to see how far
13525 it is from meeting SPARK 2005 restrictions.
13527 The list below summarizes the checks that are performed when this
13528 restriction is in force:
13534 No block statements
13537 No case statements with only an others clause
13540 Exit statements in loops must respect the SPARK 2005 language restrictions
13546 Return can only appear as last statement in function
13549 Function must have return statement
13552 Loop parameter specification must include subtype mark
13555 Prefix of expanded name cannot be a loop statement
13558 Abstract subprogram not allowed
13561 User-defined operators not allowed
13564 Access type parameters not allowed
13567 Default expressions for parameters not allowed
13570 Default expressions for record fields not allowed
13573 No tasking constructs allowed
13576 Label needed at end of subprograms and packages
13579 No mixing of positional and named parameter association
13582 No access types as result type
13585 No unconstrained arrays as result types
13591 Initial and later declarations must be in correct order (declaration can't come after body)
13594 No attributes on private types if full declaration not visible
13597 No package declaration within package specification
13600 No controlled types
13603 No discriminant types
13609 Selector name cannot be operator symbol (i.e. operator symbol cannot be prefixed)
13612 Access attribute not allowed
13615 Allocator not allowed
13618 Result of catenation must be String
13621 Operands of catenation must be string literal, static char or another catenation
13624 No conditional expressions
13627 No explicit dereference
13630 Quantified expression not allowed
13633 Slicing not allowed
13636 No exception renaming
13639 No generic renaming
13648 Aggregates must be qualified
13651 Nonstatic choice in array aggregates not allowed
13654 The only view conversions which are allowed as in-out parameters are conversions of a tagged type to an ancestor type
13657 No mixing of positional and named association in aggregate, no multi choice
13660 AND, OR and XOR for arrays only allowed when operands have same static bounds
13663 Fixed point operands to * or / must be qualified or converted
13666 Comparison operators not allowed for Booleans or arrays (except strings)
13669 Equality not allowed for arrays with non-matching static bounds (except strings)
13672 Conversion / qualification not allowed for arrays with non-matching static bounds
13675 Subprogram declaration only allowed in package spec (unless followed by import)
13678 Access types not allowed
13681 Incomplete type declaration not allowed
13684 Object and subtype declarations must respect SPARK 2005 restrictions
13687 Digits or delta constraint not allowed
13690 Decimal fixed point type not allowed
13693 Aliasing of objects not allowed
13696 Modular type modulus must be power of 2
13699 Base not allowed on subtype mark
13702 Unary operators not allowed on modular types (except not)
13705 Untagged record cannot be null
13708 No class-wide operations
13711 Initialization expressions must respect SPARK 2005 restrictions
13714 Nonstatic ranges not allowed except in iteration schemes
13717 String subtypes must have lower bound of 1
13720 Subtype of Boolean cannot have constraint
13723 At most one tagged type or extension per package
13726 Interface is not allowed
13729 Character literal cannot be prefixed (selector name cannot be character literal)
13732 Record aggregate cannot contain 'others'
13735 Component association in record aggregate must contain a single choice
13738 Ancestor part cannot be a type mark
13741 Attributes 'Image, 'Width and 'Value not allowed
13744 Functions may not update globals
13747 Subprograms may not contain direct calls to themselves (prevents recursion within unit)
13750 Call to subprogram not allowed in same unit before body has been seen (prevents recursion within unit)
13753 The following restrictions are enforced, but note that they are actually more
13754 strict that the latest SPARK 2005 language definition:
13760 No derived types other than tagged type extensions
13763 Subtype of unconstrained array must have constraint
13766 This list summarises the main SPARK 2005 language rules that are not
13767 currently checked by the SPARK_05 restriction:
13773 SPARK 2005 annotations are treated as comments so are not checked at all
13776 Based real literals not allowed
13779 Objects cannot be initialized at declaration by calls to user-defined functions
13782 Objects cannot be initialized at declaration by assignments from variables
13785 Objects cannot be initialized at declaration by assignments from indexed/selected components
13788 Ranges shall not be null
13791 A fixed point delta expression must be a simple expression
13794 Restrictions on where renaming declarations may be placed
13797 Externals of mode 'out' cannot be referenced
13800 Externals of mode 'in' cannot be updated
13803 Loop with no iteration scheme or exits only allowed as last statement in main program or task
13806 Subprogram cannot have parent unit name
13809 SPARK 2005 inherited subprogram must be prefixed with overriding
13812 External variables (or functions that reference them) may not be passed as actual parameters
13815 Globals must be explicitly mentioned in contract
13818 Deferred constants cannot be completed by pragma Import
13821 Package initialization cannot read/write variables from other packages
13824 Prefix not allowed for entities that are directly visible
13827 Identifier declaration can't override inherited package name
13830 Cannot use Standard or other predefined packages as identifiers
13833 After renaming, cannot use the original name
13836 Subprograms can only be renamed to remove package prefix
13839 Pragma import must be immediately after entity it names
13842 No mutual recursion between multiple units (this can be checked with gnatcheck)
13845 Note that if a unit is compiled in Ada 95 mode with the SPARK 2005 restriction,
13846 violations will be reported for constructs forbidden in SPARK 95,
13847 instead of SPARK 2005.
13849 @node Implementation Advice,Implementation Defined Characteristics,Standard and Implementation Defined Restrictions,Top
13850 @anchor{gnat_rm/implementation_advice doc}@anchor{215}@anchor{gnat_rm/implementation_advice implementation-advice}@anchor{a}@anchor{gnat_rm/implementation_advice id1}@anchor{216}
13851 @chapter Implementation Advice
13854 The main text of the Ada Reference Manual describes the required
13855 behavior of all Ada compilers, and the GNAT compiler conforms to
13856 these requirements.
13858 In addition, there are sections throughout the Ada Reference Manual headed
13859 by the phrase 'Implementation advice'. These sections are not normative,
13860 i.e., they do not specify requirements that all compilers must
13861 follow. Rather they provide advice on generally desirable behavior.
13862 They are not requirements, because they describe behavior that cannot
13863 be provided on all systems, or may be undesirable on some systems.
13865 As far as practical, GNAT follows the implementation advice in
13866 the Ada Reference Manual. Each such RM section corresponds to a section
13867 in this chapter whose title specifies the
13868 RM section number and paragraph number and the subject of
13869 the advice. The contents of each section consists of the RM text within
13871 followed by the GNAT interpretation of the advice. Most often, this simply says
13872 'followed', which means that GNAT follows the advice. However, in a
13873 number of cases, GNAT deliberately deviates from this advice, in which
13874 case the text describes what GNAT does and why.
13876 @geindex Error detection
13879 * RM 1.1.3(20); Error Detection: RM 1 1 3 20 Error Detection.
13880 * RM 1.1.3(31); Child Units: RM 1 1 3 31 Child Units.
13881 * RM 1.1.5(12); Bounded Errors: RM 1 1 5 12 Bounded Errors.
13882 * RM 2.8(16); Pragmas: RM 2 8 16 Pragmas.
13883 * RM 2.8(17-19); Pragmas: RM 2 8 17-19 Pragmas.
13884 * RM 3.5.2(5); Alternative Character Sets: RM 3 5 2 5 Alternative Character Sets.
13885 * RM 3.5.4(28); Integer Types: RM 3 5 4 28 Integer Types.
13886 * RM 3.5.4(29); Integer Types: RM 3 5 4 29 Integer Types.
13887 * RM 3.5.5(8); Enumeration Values: RM 3 5 5 8 Enumeration Values.
13888 * RM 3.5.7(17); Float Types: RM 3 5 7 17 Float Types.
13889 * RM 3.6.2(11); Multidimensional Arrays: RM 3 6 2 11 Multidimensional Arrays.
13890 * RM 9.6(30-31); Duration'Small: RM 9 6 30-31 Duration'Small.
13891 * RM 10.2.1(12); Consistent Representation: RM 10 2 1 12 Consistent Representation.
13892 * RM 11.4.1(19); Exception Information: RM 11 4 1 19 Exception Information.
13893 * RM 11.5(28); Suppression of Checks: RM 11 5 28 Suppression of Checks.
13894 * RM 13.1 (21-24); Representation Clauses: RM 13 1 21-24 Representation Clauses.
13895 * RM 13.2(6-8); Packed Types: RM 13 2 6-8 Packed Types.
13896 * RM 13.3(14-19); Address Clauses: RM 13 3 14-19 Address Clauses.
13897 * RM 13.3(29-35); Alignment Clauses: RM 13 3 29-35 Alignment Clauses.
13898 * RM 13.3(42-43); Size Clauses: RM 13 3 42-43 Size Clauses.
13899 * RM 13.3(50-56); Size Clauses: RM 13 3 50-56 Size Clauses.
13900 * RM 13.3(71-73); Component Size Clauses: RM 13 3 71-73 Component Size Clauses.
13901 * RM 13.4(9-10); Enumeration Representation Clauses: RM 13 4 9-10 Enumeration Representation Clauses.
13902 * RM 13.5.1(17-22); Record Representation Clauses: RM 13 5 1 17-22 Record Representation Clauses.
13903 * RM 13.5.2(5); Storage Place Attributes: RM 13 5 2 5 Storage Place Attributes.
13904 * RM 13.5.3(7-8); Bit Ordering: RM 13 5 3 7-8 Bit Ordering.
13905 * RM 13.7(37); Address as Private: RM 13 7 37 Address as Private.
13906 * RM 13.7.1(16); Address Operations: RM 13 7 1 16 Address Operations.
13907 * RM 13.9(14-17); Unchecked Conversion: RM 13 9 14-17 Unchecked Conversion.
13908 * RM 13.11(23-25); Implicit Heap Usage: RM 13 11 23-25 Implicit Heap Usage.
13909 * RM 13.11.2(17); Unchecked Deallocation: RM 13 11 2 17 Unchecked Deallocation.
13910 * RM 13.13.2(1.6); Stream Oriented Attributes: RM 13 13 2 1 6 Stream Oriented Attributes.
13911 * RM A.1(52); Names of Predefined Numeric Types: RM A 1 52 Names of Predefined Numeric Types.
13912 * RM A.3.2(49); Ada.Characters.Handling: RM A 3 2 49 Ada Characters Handling.
13913 * RM A.4.4(106); Bounded-Length String Handling: RM A 4 4 106 Bounded-Length String Handling.
13914 * RM A.5.2(46-47); Random Number Generation: RM A 5 2 46-47 Random Number Generation.
13915 * RM A.10.7(23); Get_Immediate: RM A 10 7 23 Get_Immediate.
13916 * RM B.1(39-41); Pragma Export: RM B 1 39-41 Pragma Export.
13917 * RM B.2(12-13); Package Interfaces: RM B 2 12-13 Package Interfaces.
13918 * RM B.3(63-71); Interfacing with C: RM B 3 63-71 Interfacing with C.
13919 * RM B.4(95-98); Interfacing with COBOL: RM B 4 95-98 Interfacing with COBOL.
13920 * RM B.5(22-26); Interfacing with Fortran: RM B 5 22-26 Interfacing with Fortran.
13921 * RM C.1(3-5); Access to Machine Operations: RM C 1 3-5 Access to Machine Operations.
13922 * RM C.1(10-16); Access to Machine Operations: RM C 1 10-16 Access to Machine Operations.
13923 * RM C.3(28); Interrupt Support: RM C 3 28 Interrupt Support.
13924 * RM C.3.1(20-21); Protected Procedure Handlers: RM C 3 1 20-21 Protected Procedure Handlers.
13925 * RM C.3.2(25); Package Interrupts: RM C 3 2 25 Package Interrupts.
13926 * RM C.4(14); Pre-elaboration Requirements: RM C 4 14 Pre-elaboration Requirements.
13927 * RM C.5(8); Pragma Discard_Names: RM C 5 8 Pragma Discard_Names.
13928 * RM C.7.2(30); The Package Task_Attributes: RM C 7 2 30 The Package Task_Attributes.
13929 * RM D.3(17); Locking Policies: RM D 3 17 Locking Policies.
13930 * RM D.4(16); Entry Queuing Policies: RM D 4 16 Entry Queuing Policies.
13931 * RM D.6(9-10); Preemptive Abort: RM D 6 9-10 Preemptive Abort.
13932 * RM D.7(21); Tasking Restrictions: RM D 7 21 Tasking Restrictions.
13933 * RM D.8(47-49); Monotonic Time: RM D 8 47-49 Monotonic Time.
13934 * RM E.5(28-29); Partition Communication Subsystem: RM E 5 28-29 Partition Communication Subsystem.
13935 * RM F(7); COBOL Support: RM F 7 COBOL Support.
13936 * RM F.1(2); Decimal Radix Support: RM F 1 2 Decimal Radix Support.
13937 * RM G; Numerics: RM G Numerics.
13938 * RM G.1.1(56-58); Complex Types: RM G 1 1 56-58 Complex Types.
13939 * RM G.1.2(49); Complex Elementary Functions: RM G 1 2 49 Complex Elementary Functions.
13940 * RM G.2.4(19); Accuracy Requirements: RM G 2 4 19 Accuracy Requirements.
13941 * RM G.2.6(15); Complex Arithmetic Accuracy: RM G 2 6 15 Complex Arithmetic Accuracy.
13942 * RM H.6(15/2); Pragma Partition_Elaboration_Policy: RM H 6 15/2 Pragma Partition_Elaboration_Policy.
13946 @node RM 1 1 3 20 Error Detection,RM 1 1 3 31 Child Units,,Implementation Advice
13947 @anchor{gnat_rm/implementation_advice rm-1-1-3-20-error-detection}@anchor{217}
13948 @section RM 1.1.3(20): Error Detection
13953 "If an implementation detects the use of an unsupported Specialized Needs
13954 Annex feature at run time, it should raise @code{Program_Error} if
13958 Not relevant. All specialized needs annex features are either supported,
13959 or diagnosed at compile time.
13961 @geindex Child Units
13963 @node RM 1 1 3 31 Child Units,RM 1 1 5 12 Bounded Errors,RM 1 1 3 20 Error Detection,Implementation Advice
13964 @anchor{gnat_rm/implementation_advice rm-1-1-3-31-child-units}@anchor{218}
13965 @section RM 1.1.3(31): Child Units
13970 "If an implementation wishes to provide implementation-defined
13971 extensions to the functionality of a language-defined library unit, it
13972 should normally do so by adding children to the library unit."
13977 @geindex Bounded errors
13979 @node RM 1 1 5 12 Bounded Errors,RM 2 8 16 Pragmas,RM 1 1 3 31 Child Units,Implementation Advice
13980 @anchor{gnat_rm/implementation_advice rm-1-1-5-12-bounded-errors}@anchor{219}
13981 @section RM 1.1.5(12): Bounded Errors
13986 "If an implementation detects a bounded error or erroneous
13987 execution, it should raise @code{Program_Error}."
13990 Followed in all cases in which the implementation detects a bounded
13991 error or erroneous execution. Not all such situations are detected at
13996 @node RM 2 8 16 Pragmas,RM 2 8 17-19 Pragmas,RM 1 1 5 12 Bounded Errors,Implementation Advice
13997 @anchor{gnat_rm/implementation_advice id2}@anchor{21a}@anchor{gnat_rm/implementation_advice rm-2-8-16-pragmas}@anchor{21b}
13998 @section RM 2.8(16): Pragmas
14003 "Normally, implementation-defined pragmas should have no semantic effect
14004 for error-free programs; that is, if the implementation-defined pragmas
14005 are removed from a working program, the program should still be legal,
14006 and should still have the same semantics."
14009 The following implementation defined pragmas are exceptions to this
14013 @multitable {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxx}
14056 @emph{CPP_Constructor}
14072 @emph{Interface_Name}
14080 @emph{Machine_Attribute}
14088 @emph{Unimplemented_Unit}
14096 @emph{Unchecked_Union}
14105 In each of the above cases, it is essential to the purpose of the pragma
14106 that this advice not be followed. For details see
14107 @ref{7,,Implementation Defined Pragmas}.
14109 @node RM 2 8 17-19 Pragmas,RM 3 5 2 5 Alternative Character Sets,RM 2 8 16 Pragmas,Implementation Advice
14110 @anchor{gnat_rm/implementation_advice rm-2-8-17-19-pragmas}@anchor{21c}
14111 @section RM 2.8(17-19): Pragmas
14116 "Normally, an implementation should not define pragmas that can
14117 make an illegal program legal, except as follows:
14123 A pragma used to complete a declaration, such as a pragma @code{Import};
14126 A pragma used to configure the environment by adding, removing, or
14127 replacing @code{library_items}."
14131 See @ref{21b,,RM 2.8(16); Pragmas}.
14133 @geindex Character Sets
14135 @geindex Alternative Character Sets
14137 @node RM 3 5 2 5 Alternative Character Sets,RM 3 5 4 28 Integer Types,RM 2 8 17-19 Pragmas,Implementation Advice
14138 @anchor{gnat_rm/implementation_advice rm-3-5-2-5-alternative-character-sets}@anchor{21d}
14139 @section RM 3.5.2(5): Alternative Character Sets
14144 "If an implementation supports a mode with alternative interpretations
14145 for @code{Character} and @code{Wide_Character}, the set of graphic
14146 characters of @code{Character} should nevertheless remain a proper
14147 subset of the set of graphic characters of @code{Wide_Character}. Any
14148 character set 'localizations' should be reflected in the results of
14149 the subprograms defined in the language-defined package
14150 @code{Characters.Handling} (see A.3) available in such a mode. In a mode with
14151 an alternative interpretation of @code{Character}, the implementation should
14152 also support a corresponding change in what is a legal
14153 @code{identifier_letter}."
14156 Not all wide character modes follow this advice, in particular the JIS
14157 and IEC modes reflect standard usage in Japan, and in these encoding,
14158 the upper half of the Latin-1 set is not part of the wide-character
14159 subset, since the most significant bit is used for wide character
14160 encoding. However, this only applies to the external forms. Internally
14161 there is no such restriction.
14163 @geindex Integer types
14165 @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
14166 @anchor{gnat_rm/implementation_advice rm-3-5-4-28-integer-types}@anchor{21e}
14167 @section RM 3.5.4(28): Integer Types
14172 "An implementation should support @code{Long_Integer} in addition to
14173 @code{Integer} if the target machine supports 32-bit (or longer)
14174 arithmetic. No other named integer subtypes are recommended for package
14175 @code{Standard}. Instead, appropriate named integer subtypes should be
14176 provided in the library package @code{Interfaces} (see B.2)."
14179 @code{Long_Integer} is supported. Other standard integer types are supported
14180 so this advice is not fully followed. These types
14181 are supported for convenient interface to C, and so that all hardware
14182 types of the machine are easily available.
14184 @node RM 3 5 4 29 Integer Types,RM 3 5 5 8 Enumeration Values,RM 3 5 4 28 Integer Types,Implementation Advice
14185 @anchor{gnat_rm/implementation_advice rm-3-5-4-29-integer-types}@anchor{21f}
14186 @section RM 3.5.4(29): Integer Types
14191 "An implementation for a two's complement machine should support
14192 modular types with a binary modulus up to @code{System.Max_Int*2+2}. An
14193 implementation should support a non-binary modules up to @code{Integer'Last}."
14198 @geindex Enumeration values
14200 @node RM 3 5 5 8 Enumeration Values,RM 3 5 7 17 Float Types,RM 3 5 4 29 Integer Types,Implementation Advice
14201 @anchor{gnat_rm/implementation_advice rm-3-5-5-8-enumeration-values}@anchor{220}
14202 @section RM 3.5.5(8): Enumeration Values
14207 "For the evaluation of a call on @code{S'Pos} for an enumeration
14208 subtype, if the value of the operand does not correspond to the internal
14209 code for any enumeration literal of its type (perhaps due to an
14210 un-initialized variable), then the implementation should raise
14211 @code{Program_Error}. This is particularly important for enumeration
14212 types with noncontiguous internal codes specified by an
14213 enumeration_representation_clause."
14218 @geindex Float types
14220 @node RM 3 5 7 17 Float Types,RM 3 6 2 11 Multidimensional Arrays,RM 3 5 5 8 Enumeration Values,Implementation Advice
14221 @anchor{gnat_rm/implementation_advice rm-3-5-7-17-float-types}@anchor{221}
14222 @section RM 3.5.7(17): Float Types
14227 "An implementation should support @code{Long_Float} in addition to
14228 @code{Float} if the target machine supports 11 or more digits of
14229 precision. No other named floating point subtypes are recommended for
14230 package @code{Standard}. Instead, appropriate named floating point subtypes
14231 should be provided in the library package @code{Interfaces} (see B.2)."
14234 @code{Short_Float} and @code{Long_Long_Float} are also provided. The
14235 former provides improved compatibility with other implementations
14236 supporting this type. The latter corresponds to the highest precision
14237 floating-point type supported by the hardware. On most machines, this
14238 will be the same as @code{Long_Float}, but on some machines, it will
14239 correspond to the IEEE extended form. The notable case is all ia32
14240 (x86) implementations, where @code{Long_Long_Float} corresponds to
14241 the 80-bit extended precision format supported in hardware on this
14242 processor. Note that the 128-bit format on SPARC is not supported,
14243 since this is a software rather than a hardware format.
14245 @geindex Multidimensional arrays
14248 @geindex multidimensional
14250 @node RM 3 6 2 11 Multidimensional Arrays,RM 9 6 30-31 Duration'Small,RM 3 5 7 17 Float Types,Implementation Advice
14251 @anchor{gnat_rm/implementation_advice rm-3-6-2-11-multidimensional-arrays}@anchor{222}
14252 @section RM 3.6.2(11): Multidimensional Arrays
14257 "An implementation should normally represent multidimensional arrays in
14258 row-major order, consistent with the notation used for multidimensional
14259 array aggregates (see 4.3.3). However, if a pragma @code{Convention}
14260 (@code{Fortran}, ...) applies to a multidimensional array type, then
14261 column-major order should be used instead (see B.5, @emph{Interfacing with Fortran})."
14266 @geindex Duration'Small
14268 @node RM 9 6 30-31 Duration'Small,RM 10 2 1 12 Consistent Representation,RM 3 6 2 11 Multidimensional Arrays,Implementation Advice
14269 @anchor{gnat_rm/implementation_advice rm-9-6-30-31-duration-small}@anchor{223}
14270 @section RM 9.6(30-31): Duration'Small
14275 "Whenever possible in an implementation, the value of @code{Duration'Small}
14276 should be no greater than 100 microseconds."
14279 Followed. (@code{Duration'Small} = 10**(-9)).
14283 "The time base for @code{delay_relative_statements} should be monotonic;
14284 it need not be the same time base as used for @code{Calendar.Clock}."
14289 @node RM 10 2 1 12 Consistent Representation,RM 11 4 1 19 Exception Information,RM 9 6 30-31 Duration'Small,Implementation Advice
14290 @anchor{gnat_rm/implementation_advice rm-10-2-1-12-consistent-representation}@anchor{224}
14291 @section RM 10.2.1(12): Consistent Representation
14296 "In an implementation, a type declared in a pre-elaborated package should
14297 have the same representation in every elaboration of a given version of
14298 the package, whether the elaborations occur in distinct executions of
14299 the same program, or in executions of distinct programs or partitions
14300 that include the given version."
14303 Followed, except in the case of tagged types. Tagged types involve
14304 implicit pointers to a local copy of a dispatch table, and these pointers
14305 have representations which thus depend on a particular elaboration of the
14306 package. It is not easy to see how it would be possible to follow this
14307 advice without severely impacting efficiency of execution.
14309 @geindex Exception information
14311 @node RM 11 4 1 19 Exception Information,RM 11 5 28 Suppression of Checks,RM 10 2 1 12 Consistent Representation,Implementation Advice
14312 @anchor{gnat_rm/implementation_advice rm-11-4-1-19-exception-information}@anchor{225}
14313 @section RM 11.4.1(19): Exception Information
14318 "@code{Exception_Message} by default and @code{Exception_Information}
14319 should produce information useful for
14320 debugging. @code{Exception_Message} should be short, about one
14321 line. @code{Exception_Information} can be long. @code{Exception_Message}
14322 should not include the
14323 @code{Exception_Name}. @code{Exception_Information} should include both
14324 the @code{Exception_Name} and the @code{Exception_Message}."
14327 Followed. For each exception that doesn't have a specified
14328 @code{Exception_Message}, the compiler generates one containing the location
14329 of the raise statement. This location has the form 'file_name:line', where
14330 file_name is the short file name (without path information) and line is the line
14331 number in the file. Note that in the case of the Zero Cost Exception
14332 mechanism, these messages become redundant with the Exception_Information that
14333 contains a full backtrace of the calling sequence, so they are disabled.
14334 To disable explicitly the generation of the source location message, use the
14335 Pragma @code{Discard_Names}.
14337 @geindex Suppression of checks
14340 @geindex suppression of
14342 @node RM 11 5 28 Suppression of Checks,RM 13 1 21-24 Representation Clauses,RM 11 4 1 19 Exception Information,Implementation Advice
14343 @anchor{gnat_rm/implementation_advice rm-11-5-28-suppression-of-checks}@anchor{226}
14344 @section RM 11.5(28): Suppression of Checks
14349 "The implementation should minimize the code executed for checks that
14350 have been suppressed."
14355 @geindex Representation clauses
14357 @node RM 13 1 21-24 Representation Clauses,RM 13 2 6-8 Packed Types,RM 11 5 28 Suppression of Checks,Implementation Advice
14358 @anchor{gnat_rm/implementation_advice rm-13-1-21-24-representation-clauses}@anchor{227}
14359 @section RM 13.1 (21-24): Representation Clauses
14364 "The recommended level of support for all representation items is
14365 qualified as follows:
14367 An implementation need not support representation items containing
14368 nonstatic expressions, except that an implementation should support a
14369 representation item for a given entity if each nonstatic expression in
14370 the representation item is a name that statically denotes a constant
14371 declared before the entity."
14374 Followed. In fact, GNAT goes beyond the recommended level of support
14375 by allowing nonstatic expressions in some representation clauses even
14376 without the need to declare constants initialized with the values of
14383 for Y'Address use X'Address;>>
14386 "An implementation need not support a specification for the `@w{`}Size`@w{`}
14387 for a given composite subtype, nor the size or storage place for an
14388 object (including a component) of a given composite subtype, unless the
14389 constraints on the subtype and its composite subcomponents (if any) are
14390 all static constraints."
14393 Followed. Size Clauses are not permitted on nonstatic components, as
14398 "An aliased component, or a component whose type is by-reference, should
14399 always be allocated at an addressable location."
14404 @geindex Packed types
14406 @node RM 13 2 6-8 Packed Types,RM 13 3 14-19 Address Clauses,RM 13 1 21-24 Representation Clauses,Implementation Advice
14407 @anchor{gnat_rm/implementation_advice rm-13-2-6-8-packed-types}@anchor{228}
14408 @section RM 13.2(6-8): Packed Types
14413 "If a type is packed, then the implementation should try to minimize
14414 storage allocated to objects of the type, possibly at the expense of
14415 speed of accessing components, subject to reasonable complexity in
14416 addressing calculations.
14418 The recommended level of support pragma @code{Pack} is:
14420 For a packed record type, the components should be packed as tightly as
14421 possible subject to the Sizes of the component subtypes, and subject to
14422 any @emph{record_representation_clause} that applies to the type; the
14423 implementation may, but need not, reorder components or cross aligned
14424 word boundaries to improve the packing. A component whose @code{Size} is
14425 greater than the word size may be allocated an integral number of words."
14428 Followed. Tight packing of arrays is supported for all component sizes
14429 up to 64-bits. If the array component size is 1 (that is to say, if
14430 the component is a boolean type or an enumeration type with two values)
14431 then values of the type are implicitly initialized to zero. This
14432 happens both for objects of the packed type, and for objects that have a
14433 subcomponent of the packed type.
14437 "An implementation should support Address clauses for imported
14443 @geindex Address clauses
14445 @node RM 13 3 14-19 Address Clauses,RM 13 3 29-35 Alignment Clauses,RM 13 2 6-8 Packed Types,Implementation Advice
14446 @anchor{gnat_rm/implementation_advice rm-13-3-14-19-address-clauses}@anchor{229}
14447 @section RM 13.3(14-19): Address Clauses
14452 "For an array @code{X}, @code{X'Address} should point at the first
14453 component of the array, and not at the array bounds."
14460 "The recommended level of support for the @code{Address} attribute is:
14462 @code{X'Address} should produce a useful result if @code{X} is an
14463 object that is aliased or of a by-reference type, or is an entity whose
14464 @code{Address} has been specified."
14467 Followed. A valid address will be produced even if none of those
14468 conditions have been met. If necessary, the object is forced into
14469 memory to ensure the address is valid.
14473 "An implementation should support @code{Address} clauses for imported
14481 "Objects (including subcomponents) that are aliased or of a by-reference
14482 type should be allocated on storage element boundaries."
14489 "If the @code{Address} of an object is specified, or it is imported or exported,
14490 then the implementation should not perform optimizations based on
14491 assumptions of no aliases."
14496 @geindex Alignment clauses
14498 @node RM 13 3 29-35 Alignment Clauses,RM 13 3 42-43 Size Clauses,RM 13 3 14-19 Address Clauses,Implementation Advice
14499 @anchor{gnat_rm/implementation_advice rm-13-3-29-35-alignment-clauses}@anchor{22a}
14500 @section RM 13.3(29-35): Alignment Clauses
14505 "The recommended level of support for the @code{Alignment} attribute for
14508 An implementation should support specified Alignments that are factors
14509 and multiples of the number of storage elements per word, subject to the
14517 "An implementation need not support specified Alignments for
14518 combinations of Sizes and Alignments that cannot be easily
14519 loaded and stored by available machine instructions."
14526 "An implementation need not support specified Alignments that are
14527 greater than the maximum @code{Alignment} the implementation ever returns by
14535 "The recommended level of support for the @code{Alignment} attribute for
14538 Same as above, for subtypes, but in addition:"
14545 "For stand-alone library-level objects of statically constrained
14546 subtypes, the implementation should support all alignments
14547 supported by the target linker. For example, page alignment is likely to
14548 be supported for such objects, but not for subtypes."
14553 @geindex Size clauses
14555 @node RM 13 3 42-43 Size Clauses,RM 13 3 50-56 Size Clauses,RM 13 3 29-35 Alignment Clauses,Implementation Advice
14556 @anchor{gnat_rm/implementation_advice rm-13-3-42-43-size-clauses}@anchor{22b}
14557 @section RM 13.3(42-43): Size Clauses
14562 "The recommended level of support for the @code{Size} attribute of
14565 A @code{Size} clause should be supported for an object if the specified
14566 @code{Size} is at least as large as its subtype's @code{Size}, and
14567 corresponds to a size in storage elements that is a multiple of the
14568 object's @code{Alignment} (if the @code{Alignment} is nonzero)."
14573 @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
14574 @anchor{gnat_rm/implementation_advice rm-13-3-50-56-size-clauses}@anchor{22c}
14575 @section RM 13.3(50-56): Size Clauses
14580 "If the @code{Size} of a subtype is specified, and allows for efficient
14581 independent addressability (see 9.10) on the target architecture, then
14582 the @code{Size} of the following objects of the subtype should equal the
14583 @code{Size} of the subtype:
14585 Aliased objects (including components)."
14592 "@cite{Size} clause on a composite subtype should not affect the
14593 internal layout of components."
14596 Followed. But note that this can be overridden by use of the implementation
14597 pragma Implicit_Packing in the case of packed arrays.
14601 "The recommended level of support for the @code{Size} attribute of subtypes is:
14603 The @code{Size} (if not specified) of a static discrete or fixed point
14604 subtype should be the number of bits needed to represent each value
14605 belonging to the subtype using an unbiased representation, leaving space
14606 for a sign bit only if the subtype contains negative values. If such a
14607 subtype is a first subtype, then an implementation should support a
14608 specified @code{Size} for it that reflects this representation."
14615 "For a subtype implemented with levels of indirection, the @code{Size}
14616 should include the size of the pointers, but not the size of what they
14622 @geindex Component_Size clauses
14624 @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
14625 @anchor{gnat_rm/implementation_advice rm-13-3-71-73-component-size-clauses}@anchor{22d}
14626 @section RM 13.3(71-73): Component Size Clauses
14631 "The recommended level of support for the @code{Component_Size}
14634 An implementation need not support specified @code{Component_Sizes} that are
14635 less than the @code{Size} of the component subtype."
14642 "An implementation should support specified Component_Sizes that
14643 are factors and multiples of the word size. For such
14644 Component_Sizes, the array should contain no gaps between
14645 components. For other Component_Sizes (if supported), the array
14646 should contain no gaps between components when packing is also
14647 specified; the implementation should forbid this combination in cases
14648 where it cannot support a no-gaps representation."
14653 @geindex Enumeration representation clauses
14655 @geindex Representation clauses
14656 @geindex enumeration
14658 @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
14659 @anchor{gnat_rm/implementation_advice rm-13-4-9-10-enumeration-representation-clauses}@anchor{22e}
14660 @section RM 13.4(9-10): Enumeration Representation Clauses
14665 "The recommended level of support for enumeration representation clauses
14668 An implementation need not support enumeration representation clauses
14669 for boolean types, but should at minimum support the internal codes in
14670 the range @code{System.Min_Int .. System.Max_Int}."
14675 @geindex Record representation clauses
14677 @geindex Representation clauses
14680 @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
14681 @anchor{gnat_rm/implementation_advice rm-13-5-1-17-22-record-representation-clauses}@anchor{22f}
14682 @section RM 13.5.1(17-22): Record Representation Clauses
14687 "The recommended level of support for
14688 @emph{record_representation_clause}s is:
14690 An implementation should support storage places that can be extracted
14691 with a load, mask, shift sequence of machine code, and set with a load,
14692 shift, mask, store sequence, given the available machine instructions
14693 and run-time model."
14700 "A storage place should be supported if its size is equal to the
14701 @code{Size} of the component subtype, and it starts and ends on a
14702 boundary that obeys the @code{Alignment} of the component subtype."
14709 "If the default bit ordering applies to the declaration of a given type,
14710 then for a component whose subtype's @code{Size} is less than the word
14711 size, any storage place that does not cross an aligned word boundary
14712 should be supported."
14719 "An implementation may reserve a storage place for the tag field of a
14720 tagged type, and disallow other components from overlapping that place."
14723 Followed. The storage place for the tag field is the beginning of the tagged
14724 record, and its size is Address'Size. GNAT will reject an explicit component
14725 clause for the tag field.
14729 "An implementation need not support a @emph{component_clause} for a
14730 component of an extension part if the storage place is not after the
14731 storage places of all components of the parent type, whether or not
14732 those storage places had been specified."
14735 Followed. The above advice on record representation clauses is followed,
14736 and all mentioned features are implemented.
14738 @geindex Storage place attributes
14740 @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
14741 @anchor{gnat_rm/implementation_advice rm-13-5-2-5-storage-place-attributes}@anchor{230}
14742 @section RM 13.5.2(5): Storage Place Attributes
14747 "If a component is represented using some form of pointer (such as an
14748 offset) to the actual data of the component, and this data is contiguous
14749 with the rest of the object, then the storage place attributes should
14750 reflect the place of the actual data, not the pointer. If a component is
14751 allocated discontinuously from the rest of the object, then a warning
14752 should be generated upon reference to one of its storage place
14756 Followed. There are no such components in GNAT.
14758 @geindex Bit ordering
14760 @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
14761 @anchor{gnat_rm/implementation_advice rm-13-5-3-7-8-bit-ordering}@anchor{231}
14762 @section RM 13.5.3(7-8): Bit Ordering
14767 "The recommended level of support for the non-default bit ordering is:
14769 If @code{Word_Size} = @code{Storage_Unit}, then the implementation
14770 should support the non-default bit ordering in addition to the default
14774 Followed. Word size does not equal storage size in this implementation.
14775 Thus non-default bit ordering is not supported.
14778 @geindex as private type
14780 @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
14781 @anchor{gnat_rm/implementation_advice rm-13-7-37-address-as-private}@anchor{232}
14782 @section RM 13.7(37): Address as Private
14787 "@cite{Address} should be of a private type."
14792 @geindex Operations
14793 @geindex on `@w{`}Address`@w{`}
14796 @geindex operations of
14798 @node RM 13 7 1 16 Address Operations,RM 13 9 14-17 Unchecked Conversion,RM 13 7 37 Address as Private,Implementation Advice
14799 @anchor{gnat_rm/implementation_advice rm-13-7-1-16-address-operations}@anchor{233}
14800 @section RM 13.7.1(16): Address Operations
14805 "Operations in @code{System} and its children should reflect the target
14806 environment semantics as closely as is reasonable. For example, on most
14807 machines, it makes sense for address arithmetic to 'wrap around'.
14808 Operations that do not make sense should raise @code{Program_Error}."
14811 Followed. Address arithmetic is modular arithmetic that wraps around. No
14812 operation raises @code{Program_Error}, since all operations make sense.
14814 @geindex Unchecked conversion
14816 @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
14817 @anchor{gnat_rm/implementation_advice rm-13-9-14-17-unchecked-conversion}@anchor{234}
14818 @section RM 13.9(14-17): Unchecked Conversion
14823 "The @code{Size} of an array object should not include its bounds; hence,
14824 the bounds should not be part of the converted data."
14831 "The implementation should not generate unnecessary run-time checks to
14832 ensure that the representation of @code{S} is a representation of the
14833 target type. It should take advantage of the permission to return by
14834 reference when possible. Restrictions on unchecked conversions should be
14835 avoided unless required by the target environment."
14838 Followed. There are no restrictions on unchecked conversion. A warning is
14839 generated if the source and target types do not have the same size since
14840 the semantics in this case may be target dependent.
14844 "The recommended level of support for unchecked conversions is:
14846 Unchecked conversions should be supported and should be reversible in
14847 the cases where this clause defines the result. To enable meaningful use
14848 of unchecked conversion, a contiguous representation should be used for
14849 elementary subtypes, for statically constrained array subtypes whose
14850 component subtype is one of the subtypes described in this paragraph,
14851 and for record subtypes without discriminants whose component subtypes
14852 are described in this paragraph."
14857 @geindex Heap usage
14860 @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
14861 @anchor{gnat_rm/implementation_advice rm-13-11-23-25-implicit-heap-usage}@anchor{235}
14862 @section RM 13.11(23-25): Implicit Heap Usage
14867 "An implementation should document any cases in which it dynamically
14868 allocates heap storage for a purpose other than the evaluation of an
14872 Followed, the only other points at which heap storage is dynamically
14873 allocated are as follows:
14879 At initial elaboration time, to allocate dynamically sized global
14883 To allocate space for a task when a task is created.
14886 To extend the secondary stack dynamically when needed. The secondary
14887 stack is used for returning variable length results.
14893 "A default (implementation-provided) storage pool for an
14894 access-to-constant type should not have overhead to support deallocation of
14895 individual objects."
14902 "A storage pool for an anonymous access type should be created at the
14903 point of an allocator for the type, and be reclaimed when the designated
14904 object becomes inaccessible."
14909 @geindex Unchecked deallocation
14911 @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
14912 @anchor{gnat_rm/implementation_advice rm-13-11-2-17-unchecked-deallocation}@anchor{236}
14913 @section RM 13.11.2(17): Unchecked Deallocation
14918 "For a standard storage pool, @code{Free} should actually reclaim the
14924 @geindex Stream oriented attributes
14926 @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
14927 @anchor{gnat_rm/implementation_advice rm-13-13-2-1-6-stream-oriented-attributes}@anchor{237}
14928 @section RM 13.13.2(1.6): Stream Oriented Attributes
14933 "If not specified, the value of Stream_Size for an elementary type
14934 should be the number of bits that corresponds to the minimum number of
14935 stream elements required by the first subtype of the type, rounded up
14936 to the nearest factor or multiple of the word size that is also a
14937 multiple of the stream element size."
14940 Followed, except that the number of stream elements is a power of 2.
14941 The Stream_Size may be used to override the default choice.
14943 However, such an implementation is based on direct binary
14944 representations and is therefore target- and endianness-dependent. To
14945 address this issue, GNAT also supplies an alternate implementation of
14946 the stream attributes @code{Read} and @code{Write}, which uses the
14947 target-independent XDR standard representation for scalar types.
14949 @geindex XDR representation
14951 @geindex Read attribute
14953 @geindex Write attribute
14955 @geindex Stream oriented attributes
14957 The XDR implementation is provided as an alternative body of the
14958 @code{System.Stream_Attributes} package, in the file
14959 @code{s-stratt-xdr.adb} in the GNAT library.
14960 There is no @code{s-stratt-xdr.ads} file.
14961 In order to install the XDR implementation, do the following:
14967 Replace the default implementation of the
14968 @code{System.Stream_Attributes} package with the XDR implementation.
14969 For example on a Unix platform issue the commands:
14972 $ mv s-stratt.adb s-stratt-default.adb
14973 $ mv s-stratt-xdr.adb s-stratt.adb
14977 Rebuild the GNAT run-time library as documented in
14978 the @emph{GNAT and Libraries} section of the @cite{GNAT User's Guide}.
14981 @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
14982 @anchor{gnat_rm/implementation_advice rm-a-1-52-names-of-predefined-numeric-types}@anchor{238}
14983 @section RM A.1(52): Names of Predefined Numeric Types
14988 "If an implementation provides additional named predefined integer types,
14989 then the names should end with @code{Integer} as in
14990 @code{Long_Integer}. If an implementation provides additional named
14991 predefined floating point types, then the names should end with
14992 @code{Float} as in @code{Long_Float}."
14997 @geindex Ada.Characters.Handling
14999 @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
15000 @anchor{gnat_rm/implementation_advice rm-a-3-2-49-ada-characters-handling}@anchor{239}
15001 @section RM A.3.2(49): @code{Ada.Characters.Handling}
15006 "If an implementation provides a localized definition of @code{Character}
15007 or @code{Wide_Character}, then the effects of the subprograms in
15008 @code{Characters.Handling} should reflect the localizations.
15012 Followed. GNAT provides no such localized definitions.
15014 @geindex Bounded-length strings
15016 @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
15017 @anchor{gnat_rm/implementation_advice rm-a-4-4-106-bounded-length-string-handling}@anchor{23a}
15018 @section RM A.4.4(106): Bounded-Length String Handling
15023 "Bounded string objects should not be implemented by implicit pointers
15024 and dynamic allocation."
15027 Followed. No implicit pointers or dynamic allocation are used.
15029 @geindex Random number generation
15031 @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
15032 @anchor{gnat_rm/implementation_advice rm-a-5-2-46-47-random-number-generation}@anchor{23b}
15033 @section RM A.5.2(46-47): Random Number Generation
15038 "Any storage associated with an object of type @code{Generator} should be
15039 reclaimed on exit from the scope of the object."
15046 "If the generator period is sufficiently long in relation to the number
15047 of distinct initiator values, then each possible value of
15048 @code{Initiator} passed to @code{Reset} should initiate a sequence of
15049 random numbers that does not, in a practical sense, overlap the sequence
15050 initiated by any other value. If this is not possible, then the mapping
15051 between initiator values and generator states should be a rapidly
15052 varying function of the initiator value."
15055 Followed. The generator period is sufficiently long for the first
15056 condition here to hold true.
15058 @geindex Get_Immediate
15060 @node RM A 10 7 23 Get_Immediate,RM B 1 39-41 Pragma Export,RM A 5 2 46-47 Random Number Generation,Implementation Advice
15061 @anchor{gnat_rm/implementation_advice rm-a-10-7-23-get-immediate}@anchor{23c}
15062 @section RM A.10.7(23): @code{Get_Immediate}
15067 "The @code{Get_Immediate} procedures should be implemented with
15068 unbuffered input. For a device such as a keyboard, input should be
15069 available if a key has already been typed, whereas for a disk
15070 file, input should always be available except at end of file. For a file
15071 associated with a keyboard-like device, any line-editing features of the
15072 underlying operating system should be disabled during the execution of
15073 @code{Get_Immediate}."
15076 Followed on all targets except VxWorks. For VxWorks, there is no way to
15077 provide this functionality that does not result in the input buffer being
15078 flushed before the @code{Get_Immediate} call. A special unit
15079 @code{Interfaces.Vxworks.IO} is provided that contains routines to enable
15080 this functionality.
15084 @node RM B 1 39-41 Pragma Export,RM B 2 12-13 Package Interfaces,RM A 10 7 23 Get_Immediate,Implementation Advice
15085 @anchor{gnat_rm/implementation_advice rm-b-1-39-41-pragma-export}@anchor{23d}
15086 @section RM B.1(39-41): Pragma @code{Export}
15091 "If an implementation supports pragma @code{Export} to a given language,
15092 then it should also allow the main subprogram to be written in that
15093 language. It should support some mechanism for invoking the elaboration
15094 of the Ada library units included in the system, and for invoking the
15095 finalization of the environment task. On typical systems, the
15096 recommended mechanism is to provide two subprograms whose link names are
15097 @code{adainit} and @code{adafinal}. @code{adainit} should contain the
15098 elaboration code for library units. @code{adafinal} should contain the
15099 finalization code. These subprograms should have no effect the second
15100 and subsequent time they are called."
15107 "Automatic elaboration of pre-elaborated packages should be
15108 provided when pragma @code{Export} is supported."
15111 Followed when the main program is in Ada. If the main program is in a
15112 foreign language, then
15113 @code{adainit} must be called to elaborate pre-elaborated
15118 "For each supported convention @emph{L} other than @code{Intrinsic}, an
15119 implementation should support @code{Import} and @code{Export} pragmas
15120 for objects of @emph{L}-compatible types and for subprograms, and pragma
15121 @cite{Convention} for @emph{L}-eligible types and for subprograms,
15122 presuming the other language has corresponding features. Pragma
15123 @code{Convention} need not be supported for scalar types."
15128 @geindex Package Interfaces
15130 @geindex Interfaces
15132 @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
15133 @anchor{gnat_rm/implementation_advice rm-b-2-12-13-package-interfaces}@anchor{23e}
15134 @section RM B.2(12-13): Package @code{Interfaces}
15139 "For each implementation-defined convention identifier, there should be a
15140 child package of package Interfaces with the corresponding name. This
15141 package should contain any declarations that would be useful for
15142 interfacing to the language (implementation) represented by the
15143 convention. Any declarations useful for interfacing to any language on
15144 the given hardware architecture should be provided directly in
15145 @code{Interfaces}."
15152 "An implementation supporting an interface to C, COBOL, or Fortran should
15153 provide the corresponding package or packages described in the following
15157 Followed. GNAT provides all the packages described in this section.
15160 @geindex interfacing with
15162 @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
15163 @anchor{gnat_rm/implementation_advice rm-b-3-63-71-interfacing-with-c}@anchor{23f}
15164 @section RM B.3(63-71): Interfacing with C
15169 "An implementation should support the following interface correspondences
15170 between Ada and C."
15177 "An Ada procedure corresponds to a void-returning C function."
15184 "An Ada function corresponds to a non-void C function."
15191 "An Ada @code{in} scalar parameter is passed as a scalar argument to a C
15199 "An Ada @code{in} parameter of an access-to-object type with designated
15200 type @code{T} is passed as a @code{t*} argument to a C function,
15201 where @code{t} is the C type corresponding to the Ada type @code{T}."
15208 "An Ada access @code{T} parameter, or an Ada @code{out} or @code{in out}
15209 parameter of an elementary type @code{T}, is passed as a @code{t*}
15210 argument to a C function, where @code{t} is the C type corresponding to
15211 the Ada type @code{T}. In the case of an elementary @code{out} or
15212 @code{in out} parameter, a pointer to a temporary copy is used to
15213 preserve by-copy semantics."
15220 "An Ada parameter of a record type @code{T}, of any mode, is passed as a
15221 @code{t*} argument to a C function, where @code{t} is the C
15222 structure corresponding to the Ada type @code{T}."
15225 Followed. This convention may be overridden by the use of the C_Pass_By_Copy
15226 pragma, or Convention, or by explicitly specifying the mechanism for a given
15227 call using an extended import or export pragma.
15231 "An Ada parameter of an array type with component type @code{T}, of any
15232 mode, is passed as a @code{t*} argument to a C function, where
15233 @code{t} is the C type corresponding to the Ada type @code{T}."
15240 "An Ada parameter of an access-to-subprogram type is passed as a pointer
15241 to a C function whose prototype corresponds to the designated
15242 subprogram's specification."
15248 @geindex interfacing with
15250 @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
15251 @anchor{gnat_rm/implementation_advice rm-b-4-95-98-interfacing-with-cobol}@anchor{240}
15252 @section RM B.4(95-98): Interfacing with COBOL
15257 "An Ada implementation should support the following interface
15258 correspondences between Ada and COBOL."
15265 "An Ada access @code{T} parameter is passed as a @code{BY REFERENCE} data item of
15266 the COBOL type corresponding to @code{T}."
15273 "An Ada in scalar parameter is passed as a @code{BY CONTENT} data item of
15274 the corresponding COBOL type."
15281 "Any other Ada parameter is passed as a @code{BY REFERENCE} data item of the
15282 COBOL type corresponding to the Ada parameter type; for scalars, a local
15283 copy is used if necessary to ensure by-copy semantics."
15289 @geindex interfacing with
15291 @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
15292 @anchor{gnat_rm/implementation_advice rm-b-5-22-26-interfacing-with-fortran}@anchor{241}
15293 @section RM B.5(22-26): Interfacing with Fortran
15298 "An Ada implementation should support the following interface
15299 correspondences between Ada and Fortran:"
15306 "An Ada procedure corresponds to a Fortran subroutine."
15313 "An Ada function corresponds to a Fortran function."
15320 "An Ada parameter of an elementary, array, or record type @code{T} is
15321 passed as a @code{T} argument to a Fortran procedure, where @code{T} is
15322 the Fortran type corresponding to the Ada type @code{T}, and where the
15323 INTENT attribute of the corresponding dummy argument matches the Ada
15324 formal parameter mode; the Fortran implementation's parameter passing
15325 conventions are used. For elementary types, a local copy is used if
15326 necessary to ensure by-copy semantics."
15333 "An Ada parameter of an access-to-subprogram type is passed as a
15334 reference to a Fortran procedure whose interface corresponds to the
15335 designated subprogram's specification."
15340 @geindex Machine operations
15342 @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
15343 @anchor{gnat_rm/implementation_advice rm-c-1-3-5-access-to-machine-operations}@anchor{242}
15344 @section RM C.1(3-5): Access to Machine Operations
15349 "The machine code or intrinsic support should allow access to all
15350 operations normally available to assembly language programmers for the
15351 target environment, including privileged instructions, if any."
15358 "The interfacing pragmas (see Annex B) should support interface to
15359 assembler; the default assembler should be associated with the
15360 convention identifier @code{Assembler}."
15367 "If an entity is exported to assembly language, then the implementation
15368 should allocate it at an addressable location, and should ensure that it
15369 is retained by the linking process, even if not otherwise referenced
15370 from the Ada code. The implementation should assume that any call to a
15371 machine code or assembler subprogram is allowed to read or update every
15372 object that is specified as exported."
15377 @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
15378 @anchor{gnat_rm/implementation_advice rm-c-1-10-16-access-to-machine-operations}@anchor{243}
15379 @section RM C.1(10-16): Access to Machine Operations
15384 "The implementation should ensure that little or no overhead is
15385 associated with calling intrinsic and machine-code subprograms."
15388 Followed for both intrinsics and machine-code subprograms.
15392 "It is recommended that intrinsic subprograms be provided for convenient
15393 access to any machine operations that provide special capabilities or
15394 efficiency and that are not otherwise available through the language
15398 Followed. A full set of machine operation intrinsic subprograms is provided.
15402 "Atomic read-modify-write operations---e.g., test and set, compare and
15403 swap, decrement and test, enqueue/dequeue."
15406 Followed on any target supporting such operations.
15410 "Standard numeric functions---e.g.:, sin, log."
15413 Followed on any target supporting such operations.
15417 "String manipulation operations---e.g.:, translate and test."
15420 Followed on any target supporting such operations.
15424 "Vector operations---e.g.:, compare vector against thresholds."
15427 Followed on any target supporting such operations.
15431 "Direct operations on I/O ports."
15434 Followed on any target supporting such operations.
15436 @geindex Interrupt support
15438 @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
15439 @anchor{gnat_rm/implementation_advice rm-c-3-28-interrupt-support}@anchor{244}
15440 @section RM C.3(28): Interrupt Support
15445 "If the @code{Ceiling_Locking} policy is not in effect, the
15446 implementation should provide means for the application to specify which
15447 interrupts are to be blocked during protected actions, if the underlying
15448 system allows for a finer-grain control of interrupt blocking."
15451 Followed. The underlying system does not allow for finer-grain control
15452 of interrupt blocking.
15454 @geindex Protected procedure handlers
15456 @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
15457 @anchor{gnat_rm/implementation_advice rm-c-3-1-20-21-protected-procedure-handlers}@anchor{245}
15458 @section RM C.3.1(20-21): Protected Procedure Handlers
15463 "Whenever possible, the implementation should allow interrupt handlers to
15464 be called directly by the hardware."
15467 Followed on any target where the underlying operating system permits
15472 "Whenever practical, violations of any
15473 implementation-defined restrictions should be detected before run time."
15476 Followed. Compile time warnings are given when possible.
15478 @geindex Package `@w{`}Interrupts`@w{`}
15480 @geindex Interrupts
15482 @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
15483 @anchor{gnat_rm/implementation_advice rm-c-3-2-25-package-interrupts}@anchor{246}
15484 @section RM C.3.2(25): Package @code{Interrupts}
15489 "If implementation-defined forms of interrupt handler procedures are
15490 supported, such as protected procedures with parameters, then for each
15491 such form of a handler, a type analogous to @code{Parameterless_Handler}
15492 should be specified in a child package of @code{Interrupts}, with the
15493 same operations as in the predefined package Interrupts."
15498 @geindex Pre-elaboration requirements
15500 @node RM C 4 14 Pre-elaboration Requirements,RM C 5 8 Pragma Discard_Names,RM C 3 2 25 Package Interrupts,Implementation Advice
15501 @anchor{gnat_rm/implementation_advice rm-c-4-14-pre-elaboration-requirements}@anchor{247}
15502 @section RM C.4(14): Pre-elaboration Requirements
15507 "It is recommended that pre-elaborated packages be implemented in such a
15508 way that there should be little or no code executed at run time for the
15509 elaboration of entities not already covered by the Implementation
15513 Followed. Executable code is generated in some cases, e.g., loops
15514 to initialize large arrays.
15516 @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
15517 @anchor{gnat_rm/implementation_advice rm-c-5-8-pragma-discard-names}@anchor{248}
15518 @section RM C.5(8): Pragma @code{Discard_Names}
15523 "If the pragma applies to an entity, then the implementation should
15524 reduce the amount of storage used for storing names associated with that
15530 @geindex Package Task_Attributes
15532 @geindex Task_Attributes
15534 @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
15535 @anchor{gnat_rm/implementation_advice rm-c-7-2-30-the-package-task-attributes}@anchor{249}
15536 @section RM C.7.2(30): The Package Task_Attributes
15541 "Some implementations are targeted to domains in which memory use at run
15542 time must be completely deterministic. For such implementations, it is
15543 recommended that the storage for task attributes will be pre-allocated
15544 statically and not from the heap. This can be accomplished by either
15545 placing restrictions on the number and the size of the task's
15546 attributes, or by using the pre-allocated storage for the first @code{N}
15547 attribute objects, and the heap for the others. In the latter case,
15548 @code{N} should be documented."
15551 Not followed. This implementation is not targeted to such a domain.
15553 @geindex Locking Policies
15555 @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
15556 @anchor{gnat_rm/implementation_advice rm-d-3-17-locking-policies}@anchor{24a}
15557 @section RM D.3(17): Locking Policies
15562 "The implementation should use names that end with @code{_Locking} for
15563 locking policies defined by the implementation."
15566 Followed. Two implementation-defined locking policies are defined,
15567 whose names (@code{Inheritance_Locking} and
15568 @code{Concurrent_Readers_Locking}) follow this suggestion.
15570 @geindex Entry queuing policies
15572 @node RM D 4 16 Entry Queuing Policies,RM D 6 9-10 Preemptive Abort,RM D 3 17 Locking Policies,Implementation Advice
15573 @anchor{gnat_rm/implementation_advice rm-d-4-16-entry-queuing-policies}@anchor{24b}
15574 @section RM D.4(16): Entry Queuing Policies
15579 "Names that end with @code{_Queuing} should be used
15580 for all implementation-defined queuing policies."
15583 Followed. No such implementation-defined queuing policies exist.
15585 @geindex Preemptive abort
15587 @node RM D 6 9-10 Preemptive Abort,RM D 7 21 Tasking Restrictions,RM D 4 16 Entry Queuing Policies,Implementation Advice
15588 @anchor{gnat_rm/implementation_advice rm-d-6-9-10-preemptive-abort}@anchor{24c}
15589 @section RM D.6(9-10): Preemptive Abort
15594 "Even though the @emph{abort_statement} is included in the list of
15595 potentially blocking operations (see 9.5.1), it is recommended that this
15596 statement be implemented in a way that never requires the task executing
15597 the @emph{abort_statement} to block."
15604 "On a multi-processor, the delay associated with aborting a task on
15605 another processor should be bounded; the implementation should use
15606 periodic polling, if necessary, to achieve this."
15611 @geindex Tasking restrictions
15613 @node RM D 7 21 Tasking Restrictions,RM D 8 47-49 Monotonic Time,RM D 6 9-10 Preemptive Abort,Implementation Advice
15614 @anchor{gnat_rm/implementation_advice rm-d-7-21-tasking-restrictions}@anchor{24d}
15615 @section RM D.7(21): Tasking Restrictions
15620 "When feasible, the implementation should take advantage of the specified
15621 restrictions to produce a more efficient implementation."
15624 GNAT currently takes advantage of these restrictions by providing an optimized
15625 run time when the Ravenscar profile and the GNAT restricted run time set
15626 of restrictions are specified. See pragma @code{Profile (Ravenscar)} and
15627 pragma @code{Profile (Restricted)} for more details.
15632 @node RM D 8 47-49 Monotonic Time,RM E 5 28-29 Partition Communication Subsystem,RM D 7 21 Tasking Restrictions,Implementation Advice
15633 @anchor{gnat_rm/implementation_advice rm-d-8-47-49-monotonic-time}@anchor{24e}
15634 @section RM D.8(47-49): Monotonic Time
15639 "When appropriate, implementations should provide configuration
15640 mechanisms to change the value of @code{Tick}."
15643 Such configuration mechanisms are not appropriate to this implementation
15644 and are thus not supported.
15648 "It is recommended that @code{Calendar.Clock} and @code{Real_Time.Clock}
15649 be implemented as transformations of the same time base."
15656 "It is recommended that the best time base which exists in
15657 the underlying system be available to the application through
15658 @code{Clock}. @cite{Best} may mean highest accuracy or largest range."
15663 @geindex Partition communication subsystem
15667 @node RM E 5 28-29 Partition Communication Subsystem,RM F 7 COBOL Support,RM D 8 47-49 Monotonic Time,Implementation Advice
15668 @anchor{gnat_rm/implementation_advice rm-e-5-28-29-partition-communication-subsystem}@anchor{24f}
15669 @section RM E.5(28-29): Partition Communication Subsystem
15674 "Whenever possible, the PCS on the called partition should allow for
15675 multiple tasks to call the RPC-receiver with different messages and
15676 should allow them to block until the corresponding subprogram body
15680 Followed by GLADE, a separately supplied PCS that can be used with
15685 "The @code{Write} operation on a stream of type @code{Params_Stream_Type}
15686 should raise @code{Storage_Error} if it runs out of space trying to
15687 write the @code{Item} into the stream."
15690 Followed by GLADE, a separately supplied PCS that can be used with
15693 @geindex COBOL support
15695 @node RM F 7 COBOL Support,RM F 1 2 Decimal Radix Support,RM E 5 28-29 Partition Communication Subsystem,Implementation Advice
15696 @anchor{gnat_rm/implementation_advice rm-f-7-cobol-support}@anchor{250}
15697 @section RM F(7): COBOL Support
15702 "If COBOL (respectively, C) is widely supported in the target
15703 environment, implementations supporting the Information Systems Annex
15704 should provide the child package @code{Interfaces.COBOL} (respectively,
15705 @code{Interfaces.C}) specified in Annex B and should support a
15706 @code{convention_identifier} of COBOL (respectively, C) in the interfacing
15707 pragmas (see Annex B), thus allowing Ada programs to interface with
15708 programs written in that language."
15713 @geindex Decimal radix support
15715 @node RM F 1 2 Decimal Radix Support,RM G Numerics,RM F 7 COBOL Support,Implementation Advice
15716 @anchor{gnat_rm/implementation_advice rm-f-1-2-decimal-radix-support}@anchor{251}
15717 @section RM F.1(2): Decimal Radix Support
15722 "Packed decimal should be used as the internal representation for objects
15723 of subtype @code{S} when @code{S}'Machine_Radix = 10."
15726 Not followed. GNAT ignores @code{S}'Machine_Radix and always uses binary
15731 @node RM G Numerics,RM G 1 1 56-58 Complex Types,RM F 1 2 Decimal Radix Support,Implementation Advice
15732 @anchor{gnat_rm/implementation_advice rm-g-numerics}@anchor{252}
15733 @section RM G: Numerics
15738 "If Fortran (respectively, C) is widely supported in the target
15739 environment, implementations supporting the Numerics Annex
15740 should provide the child package @code{Interfaces.Fortran} (respectively,
15741 @code{Interfaces.C}) specified in Annex B and should support a
15742 @code{convention_identifier} of Fortran (respectively, C) in the interfacing
15743 pragmas (see Annex B), thus allowing Ada programs to interface with
15744 programs written in that language."
15749 @geindex Complex types
15751 @node RM G 1 1 56-58 Complex Types,RM G 1 2 49 Complex Elementary Functions,RM G Numerics,Implementation Advice
15752 @anchor{gnat_rm/implementation_advice rm-g-1-1-56-58-complex-types}@anchor{253}
15753 @section RM G.1.1(56-58): Complex Types
15758 "Because the usual mathematical meaning of multiplication of a complex
15759 operand and a real operand is that of the scaling of both components of
15760 the former by the latter, an implementation should not perform this
15761 operation by first promoting the real operand to complex type and then
15762 performing a full complex multiplication. In systems that, in the
15763 future, support an Ada binding to IEC 559:1989, the latter technique
15764 will not generate the required result when one of the components of the
15765 complex operand is infinite. (Explicit multiplication of the infinite
15766 component by the zero component obtained during promotion yields a NaN
15767 that propagates into the final result.) Analogous advice applies in the
15768 case of multiplication of a complex operand and a pure-imaginary
15769 operand, and in the case of division of a complex operand by a real or
15770 pure-imaginary operand."
15777 "Similarly, because the usual mathematical meaning of addition of a
15778 complex operand and a real operand is that the imaginary operand remains
15779 unchanged, an implementation should not perform this operation by first
15780 promoting the real operand to complex type and then performing a full
15781 complex addition. In implementations in which the @code{Signed_Zeros}
15782 attribute of the component type is @code{True} (and which therefore
15783 conform to IEC 559:1989 in regard to the handling of the sign of zero in
15784 predefined arithmetic operations), the latter technique will not
15785 generate the required result when the imaginary component of the complex
15786 operand is a negatively signed zero. (Explicit addition of the negative
15787 zero to the zero obtained during promotion yields a positive zero.)
15788 Analogous advice applies in the case of addition of a complex operand
15789 and a pure-imaginary operand, and in the case of subtraction of a
15790 complex operand and a real or pure-imaginary operand."
15797 "Implementations in which @code{Real'Signed_Zeros} is @code{True} should
15798 attempt to provide a rational treatment of the signs of zero results and
15799 result components. As one example, the result of the @code{Argument}
15800 function should have the sign of the imaginary component of the
15801 parameter @code{X} when the point represented by that parameter lies on
15802 the positive real axis; as another, the sign of the imaginary component
15803 of the @code{Compose_From_Polar} function should be the same as
15804 (respectively, the opposite of) that of the @code{Argument} parameter when that
15805 parameter has a value of zero and the @code{Modulus} parameter has a
15806 nonnegative (respectively, negative) value."
15811 @geindex Complex elementary functions
15813 @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
15814 @anchor{gnat_rm/implementation_advice rm-g-1-2-49-complex-elementary-functions}@anchor{254}
15815 @section RM G.1.2(49): Complex Elementary Functions
15820 "Implementations in which @code{Complex_Types.Real'Signed_Zeros} is
15821 @code{True} should attempt to provide a rational treatment of the signs
15822 of zero results and result components. For example, many of the complex
15823 elementary functions have components that are odd functions of one of
15824 the parameter components; in these cases, the result component should
15825 have the sign of the parameter component at the origin. Other complex
15826 elementary functions have zero components whose sign is opposite that of
15827 a parameter component at the origin, or is always positive or always
15833 @geindex Accuracy requirements
15835 @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
15836 @anchor{gnat_rm/implementation_advice rm-g-2-4-19-accuracy-requirements}@anchor{255}
15837 @section RM G.2.4(19): Accuracy Requirements
15842 "The versions of the forward trigonometric functions without a
15843 @code{Cycle} parameter should not be implemented by calling the
15844 corresponding version with a @code{Cycle} parameter of
15845 @code{2.0*Numerics.Pi}, since this will not provide the required
15846 accuracy in some portions of the domain. For the same reason, the
15847 version of @code{Log} without a @code{Base} parameter should not be
15848 implemented by calling the corresponding version with a @code{Base}
15849 parameter of @code{Numerics.e}."
15854 @geindex Complex arithmetic accuracy
15857 @geindex complex arithmetic
15859 @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
15860 @anchor{gnat_rm/implementation_advice rm-g-2-6-15-complex-arithmetic-accuracy}@anchor{256}
15861 @section RM G.2.6(15): Complex Arithmetic Accuracy
15866 "The version of the @code{Compose_From_Polar} function without a
15867 @code{Cycle} parameter should not be implemented by calling the
15868 corresponding version with a @code{Cycle} parameter of
15869 @code{2.0*Numerics.Pi}, since this will not provide the required
15870 accuracy in some portions of the domain."
15875 @geindex Sequential elaboration policy
15877 @node RM H 6 15/2 Pragma Partition_Elaboration_Policy,,RM G 2 6 15 Complex Arithmetic Accuracy,Implementation Advice
15878 @anchor{gnat_rm/implementation_advice rm-h-6-15-2-pragma-partition-elaboration-policy}@anchor{257}
15879 @section RM H.6(15/2): Pragma Partition_Elaboration_Policy
15884 "If the partition elaboration policy is @code{Sequential} and the
15885 Environment task becomes permanently blocked during elaboration then the
15886 partition is deadlocked and it is recommended that the partition be
15887 immediately terminated."
15892 @node Implementation Defined Characteristics,Intrinsic Subprograms,Implementation Advice,Top
15893 @anchor{gnat_rm/implementation_defined_characteristics implementation-defined-characteristics}@anchor{b}@anchor{gnat_rm/implementation_defined_characteristics doc}@anchor{258}@anchor{gnat_rm/implementation_defined_characteristics id1}@anchor{259}
15894 @chapter Implementation Defined Characteristics
15897 In addition to the implementation dependent pragmas and attributes, and the
15898 implementation advice, there are a number of other Ada features that are
15899 potentially implementation dependent and are designated as
15900 implementation-defined. These are mentioned throughout the Ada Reference
15901 Manual, and are summarized in Annex M.
15903 A requirement for conforming Ada compilers is that they provide
15904 documentation describing how the implementation deals with each of these
15905 issues. In this chapter you will find each point in Annex M listed,
15906 followed by a description of how GNAT
15907 handles the implementation dependence.
15909 You can use this chapter as a guide to minimizing implementation
15910 dependent features in your programs if portability to other compilers
15911 and other operating systems is an important consideration. The numbers
15912 in each entry below correspond to the paragraph numbers in the Ada
15919 "Whether or not each recommendation given in Implementation
15920 Advice is followed. See 1.1.2(37)."
15923 See @ref{a,,Implementation Advice}.
15929 "Capacity limitations of the implementation. See 1.1.3(3)."
15932 The complexity of programs that can be processed is limited only by the
15933 total amount of available virtual memory, and disk space for the
15934 generated object files.
15940 "Variations from the standard that are impractical to avoid
15941 given the implementation's execution environment. See 1.1.3(6)."
15944 There are no variations from the standard.
15950 "Which code_statements cause external
15951 interactions. See 1.1.3(10)."
15954 Any @emph{code_statement} can potentially cause external interactions.
15960 "The coded representation for the text of an Ada
15961 program. See 2.1(4)."
15964 See separate section on source representation.
15970 "The control functions allowed in comments. See 2.1(14)."
15973 See separate section on source representation.
15979 "The representation for an end of line. See 2.2(2)."
15982 See separate section on source representation.
15988 "Maximum supported line length and lexical element
15989 length. See 2.2(15)."
15992 The maximum line length is 255 characters and the maximum length of
15993 a lexical element is also 255 characters. This is the default setting
15994 if not overridden by the use of compiler switch @emph{-gnaty} (which
15995 sets the maximum to 79) or @emph{-gnatyMnn} which allows the maximum
15996 line length to be specified to be any value up to 32767. The maximum
15997 length of a lexical element is the same as the maximum line length.
16003 "Implementation defined pragmas. See 2.8(14)."
16006 See @ref{7,,Implementation Defined Pragmas}.
16012 "Effect of pragma @code{Optimize}. See 2.8(27)."
16015 Pragma @code{Optimize}, if given with a @code{Time} or @code{Space}
16016 parameter, checks that the optimization flag is set, and aborts if it is
16023 "The sequence of characters of the value returned by
16024 @code{S'Image} when some of the graphic characters of
16025 @code{S'Wide_Image} are not defined in @code{Character}. See
16029 The sequence of characters is as defined by the wide character encoding
16030 method used for the source. See section on source representation for
16037 "The predefined integer types declared in
16038 @code{Standard}. See 3.5.4(25)."
16042 @multitable {xxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
16053 @emph{Short_Short_Integer}
16061 @emph{Short_Integer}
16065 (Short) 16 bit signed
16077 @emph{Long_Integer}
16081 64 bit signed (on most 64 bit targets,
16082 depending on the C definition of long).
16083 32 bit signed (all other targets)
16087 @emph{Long_Long_Integer}
16100 "Any nonstandard integer types and the operators defined
16101 for them. See 3.5.4(26)."
16104 There are no nonstandard integer types.
16110 "Any nonstandard real types and the operators defined for
16111 them. See 3.5.6(8)."
16114 There are no nonstandard real types.
16120 "What combinations of requested decimal precision and range
16121 are supported for floating point types. See 3.5.7(7)."
16124 The precision and range is as defined by the IEEE standard.
16130 "The predefined floating point types declared in
16131 @code{Standard}. See 3.5.7(16)."
16135 @multitable {xxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
16158 (Short) 32 bit IEEE short
16170 @emph{Long_Long_Float}
16174 64 bit IEEE long (80 bit IEEE long on x86 processors)
16183 "The small of an ordinary fixed point type. See 3.5.9(8)."
16186 @code{Fine_Delta} is 2**(-63)
16192 "What combinations of small, range, and digits are
16193 supported for fixed point types. See 3.5.9(10)."
16196 Any combinations are permitted that do not result in a small less than
16197 @code{Fine_Delta} and do not result in a mantissa larger than 63 bits.
16198 If the mantissa is larger than 53 bits on machines where Long_Long_Float
16199 is 64 bits (true of all architectures except ia32), then the output from
16200 Text_IO is accurate to only 53 bits, rather than the full mantissa. This
16201 is because floating-point conversions are used to convert fixed point.
16207 "The result of @code{Tags.Expanded_Name} for types declared
16208 within an unnamed @emph{block_statement}. See 3.9(10)."
16211 Block numbers of the form @code{B@emph{nnn}}, where @emph{nnn} is a
16212 decimal integer are allocated.
16218 "Implementation-defined attributes. See 4.1.4(12)."
16221 See @ref{8,,Implementation Defined Attributes}.
16227 "Any implementation-defined time types. See 9.6(6)."
16230 There are no implementation-defined time types.
16236 "The time base associated with relative delays."
16239 See 9.6(20). The time base used is that provided by the C library
16240 function @code{gettimeofday}.
16246 "The time base of the type @code{Calendar.Time}. See
16250 The time base used is that provided by the C library function
16251 @code{gettimeofday}.
16257 "The time zone used for package @code{Calendar}
16258 operations. See 9.6(24)."
16261 The time zone used by package @code{Calendar} is the current system time zone
16262 setting for local time, as accessed by the C library function
16269 "Any limit on @emph{delay_until_statements} of
16270 @emph{select_statements}. See 9.6(29)."
16273 There are no such limits.
16279 "Whether or not two non-overlapping parts of a composite
16280 object are independently addressable, in the case where packing, record
16281 layout, or @code{Component_Size} is specified for the object. See
16285 Separate components are independently addressable if they do not share
16286 overlapping storage units.
16292 "The representation for a compilation. See 10.1(2)."
16295 A compilation is represented by a sequence of files presented to the
16296 compiler in a single invocation of the @emph{gcc} command.
16302 "Any restrictions on compilations that contain multiple
16303 compilation_units. See 10.1(4)."
16306 No single file can contain more than one compilation unit, but any
16307 sequence of files can be presented to the compiler as a single
16314 "The mechanisms for creating an environment and for adding
16315 and replacing compilation units. See 10.1.4(3)."
16318 See separate section on compilation model.
16324 "The manner of explicitly assigning library units to a
16325 partition. See 10.2(2)."
16328 If a unit contains an Ada main program, then the Ada units for the partition
16329 are determined by recursive application of the rules in the Ada Reference
16330 Manual section 10.2(2-6). In other words, the Ada units will be those that
16331 are needed by the main program, and then this definition of need is applied
16332 recursively to those units, and the partition contains the transitive
16333 closure determined by this relationship. In short, all the necessary units
16334 are included, with no need to explicitly specify the list. If additional
16335 units are required, e.g., by foreign language units, then all units must be
16336 mentioned in the context clause of one of the needed Ada units.
16338 If the partition contains no main program, or if the main program is in
16339 a language other than Ada, then GNAT
16340 provides the binder options @emph{-z} and @emph{-n} respectively, and in
16341 this case a list of units can be explicitly supplied to the binder for
16342 inclusion in the partition (all units needed by these units will also
16343 be included automatically). For full details on the use of these
16344 options, refer to @emph{GNAT Make Program gnatmake} in the
16345 @cite{GNAT User's Guide}.
16351 "The implementation-defined means, if any, of specifying
16352 which compilation units are needed by a given compilation unit. See
16356 The units needed by a given compilation unit are as defined in
16357 the Ada Reference Manual section 10.2(2-6). There are no
16358 implementation-defined pragmas or other implementation-defined
16359 means for specifying needed units.
16365 "The manner of designating the main subprogram of a
16366 partition. See 10.2(7)."
16369 The main program is designated by providing the name of the
16370 corresponding @code{ALI} file as the input parameter to the binder.
16376 "The order of elaboration of @emph{library_items}. See
16380 The first constraint on ordering is that it meets the requirements of
16381 Chapter 10 of the Ada Reference Manual. This still leaves some
16382 implementation dependent choices, which are resolved by first
16383 elaborating bodies as early as possible (i.e., in preference to specs
16384 where there is a choice), and second by evaluating the immediate with
16385 clauses of a unit to determine the probably best choice, and
16386 third by elaborating in alphabetical order of unit names
16387 where a choice still remains.
16393 "Parameter passing and function return for the main
16394 subprogram. See 10.2(21)."
16397 The main program has no parameters. It may be a procedure, or a function
16398 returning an integer type. In the latter case, the returned integer
16399 value is the return code of the program (overriding any value that
16400 may have been set by a call to @code{Ada.Command_Line.Set_Exit_Status}).
16406 "The mechanisms for building and running partitions. See
16410 GNAT itself supports programs with only a single partition. The GNATDIST
16411 tool provided with the GLADE package (which also includes an implementation
16412 of the PCS) provides a completely flexible method for building and running
16413 programs consisting of multiple partitions. See the separate GLADE manual
16420 "The details of program execution, including program
16421 termination. See 10.2(25)."
16424 See separate section on compilation model.
16430 "The semantics of any non-active partitions supported by the
16431 implementation. See 10.2(28)."
16434 Passive partitions are supported on targets where shared memory is
16435 provided by the operating system. See the GLADE reference manual for
16442 "The information returned by @code{Exception_Message}. See
16446 Exception message returns the null string unless a specific message has
16447 been passed by the program.
16453 "The result of @code{Exceptions.Exception_Name} for types
16454 declared within an unnamed @emph{block_statement}. See 11.4.1(12)."
16457 Blocks have implementation defined names of the form @code{B@emph{nnn}}
16458 where @emph{nnn} is an integer.
16464 "The information returned by
16465 @code{Exception_Information}. See 11.4.1(13)."
16468 @code{Exception_Information} returns a string in the following format:
16471 *Exception_Name:* nnnnn
16474 *Load address:* 0xhhhh
16475 *Call stack traceback locations:*
16476 0xhhhh 0xhhhh 0xhhhh ... 0xhhh
16487 @code{nnnn} is the fully qualified name of the exception in all upper
16488 case letters. This line is always present.
16491 @code{mmmm} is the message (this line present only if message is non-null)
16494 @code{ppp} is the Process Id value as a decimal integer (this line is
16495 present only if the Process Id is nonzero). Currently we are
16496 not making use of this field.
16499 The Load address line, the Call stack traceback locations line and the
16500 following values are present only if at least one traceback location was
16501 recorded. The Load address indicates the address at which the main executable
16502 was loaded; this line may not be present if operating system hasn't relocated
16503 the main executable. The values are given in C style format, with lower case
16504 letters for a-f, and only as many digits present as are necessary.
16505 The line terminator sequence at the end of each line, including
16506 the last line is a single @code{LF} character (@code{16#0A#}).
16514 "Implementation-defined check names. See 11.5(27)."
16517 The implementation defined check names include Alignment_Check,
16518 Atomic_Synchronization, Duplicated_Tag_Check, Container_Checks,
16519 Tampering_Check, Predicate_Check, and Validity_Check. In addition, a user
16520 program can add implementation-defined check names by means of the pragma
16521 Check_Name. See the description of pragma @code{Suppress} for full details.
16527 "The interpretation of each aspect of representation. See
16531 See separate section on data representations.
16537 "Any restrictions placed upon representation items. See
16541 See separate section on data representations.
16547 "The meaning of @code{Size} for indefinite subtypes. See
16551 Size for an indefinite subtype is the maximum possible size, except that
16552 for the case of a subprogram parameter, the size of the parameter object
16553 is the actual size.
16559 "The default external representation for a type tag. See
16563 The default external representation for a type tag is the fully expanded
16564 name of the type in upper case letters.
16570 "What determines whether a compilation unit is the same in
16571 two different partitions. See 13.3(76)."
16574 A compilation unit is the same in two different partitions if and only
16575 if it derives from the same source file.
16581 "Implementation-defined components. See 13.5.1(15)."
16584 The only implementation defined component is the tag for a tagged type,
16585 which contains a pointer to the dispatching table.
16591 "If @code{Word_Size} = @code{Storage_Unit}, the default bit
16592 ordering. See 13.5.3(5)."
16595 @code{Word_Size} (32) is not the same as @code{Storage_Unit} (8) for this
16596 implementation, so no non-default bit ordering is supported. The default
16597 bit ordering corresponds to the natural endianness of the target architecture.
16603 "The contents of the visible part of package @code{System}
16604 and its language-defined children. See 13.7(2)."
16607 See the definition of these packages in files @code{system.ads} and
16608 @code{s-stoele.ads}. Note that two declarations are added to package
16612 Max_Priority : constant Positive := Priority'Last;
16613 Max_Interrupt_Priority : constant Positive := Interrupt_Priority'Last;
16620 "The contents of the visible part of package
16621 @code{System.Machine_Code}, and the meaning of
16622 @emph{code_statements}. See 13.8(7)."
16625 See the definition and documentation in file @code{s-maccod.ads}.
16631 "The effect of unchecked conversion. See 13.9(11)."
16634 Unchecked conversion between types of the same size
16635 results in an uninterpreted transmission of the bits from one type
16636 to the other. If the types are of unequal sizes, then in the case of
16637 discrete types, a shorter source is first zero or sign extended as
16638 necessary, and a shorter target is simply truncated on the left.
16639 For all non-discrete types, the source is first copied if necessary
16640 to ensure that the alignment requirements of the target are met, then
16641 a pointer is constructed to the source value, and the result is obtained
16642 by dereferencing this pointer after converting it to be a pointer to the
16643 target type. Unchecked conversions where the target subtype is an
16644 unconstrained array are not permitted. If the target alignment is
16645 greater than the source alignment, then a copy of the result is
16646 made with appropriate alignment
16652 "The semantics of operations on invalid representations.
16653 See 13.9.2(10-11)."
16656 For assignments and other operations where the use of invalid values cannot
16657 result in erroneous behavior, the compiler ignores the possibility of invalid
16658 values. An exception is raised at the point where an invalid value would
16659 result in erroneous behavior. For example executing:
16662 procedure invalidvals is
16664 Y : Natural range 1 .. 10;
16665 for Y'Address use X'Address;
16666 Z : Natural range 1 .. 10;
16667 A : array (Natural range 1 .. 10) of Integer;
16669 Z := Y; -- no exception
16670 A (Z) := 3; -- exception raised;
16674 As indicated, an exception is raised on the array assignment, but not
16675 on the simple assignment of the invalid negative value from Y to Z.
16681 "The manner of choosing a storage pool for an access type
16682 when @code{Storage_Pool} is not specified for the type. See 13.11(17)."
16685 There are 3 different standard pools used by the compiler when
16686 @code{Storage_Pool} is not specified depending whether the type is local
16687 to a subprogram or defined at the library level and whether
16688 @code{Storage_Size`@w{`}is specified or not. See documentation in the runtime
16689 library units `@w{`}System.Pool_Global}, @code{System.Pool_Size} and
16690 @code{System.Pool_Local} in files @code{s-poosiz.ads},
16691 @code{s-pooglo.ads} and @code{s-pooloc.ads} for full details on the
16692 default pools used.
16698 "Whether or not the implementation provides user-accessible
16699 names for the standard pool type(s). See 13.11(17)."
16702 See documentation in the sources of the run time mentioned in the previous
16703 paragraph. All these pools are accessible by means of @cite{with}ing
16710 "The meaning of @code{Storage_Size}. See 13.11(18)."
16713 @code{Storage_Size} is measured in storage units, and refers to the
16714 total space available for an access type collection, or to the primary
16715 stack space for a task.
16721 "Implementation-defined aspects of storage pools. See
16725 See documentation in the sources of the run time mentioned in the
16726 paragraph about standard storage pools above
16727 for details on GNAT-defined aspects of storage pools.
16733 "The set of restrictions allowed in a pragma
16734 @code{Restrictions}. See 13.12(7)."
16737 See @ref{9,,Standard and Implementation Defined Restrictions}.
16743 "The consequences of violating limitations on
16744 @code{Restrictions} pragmas. See 13.12(9)."
16747 Restrictions that can be checked at compile time result in illegalities
16748 if violated. Currently there are no other consequences of violating
16755 "The representation used by the @code{Read} and
16756 @code{Write} attributes of elementary types in terms of stream
16757 elements. See 13.13.2(9)."
16760 The representation is the in-memory representation of the base type of
16761 the type, using the number of bits corresponding to the
16762 @code{type'Size} value, and the natural ordering of the machine.
16768 "The names and characteristics of the numeric subtypes
16769 declared in the visible part of package @code{Standard}. See A.1(3)."
16772 See items describing the integer and floating-point types supported.
16778 "The string returned by @code{Character_Set_Version}.
16782 @code{Ada.Wide_Characters.Handling.Character_Set_Version} returns
16783 the string "Unicode 4.0", referring to version 4.0 of the
16784 Unicode specification.
16790 "The accuracy actually achieved by the elementary
16791 functions. See A.5.1(1)."
16794 The elementary functions correspond to the functions available in the C
16795 library. Only fast math mode is implemented.
16801 "The sign of a zero result from some of the operators or
16802 functions in @code{Numerics.Generic_Elementary_Functions}, when
16803 @code{Float_Type'Signed_Zeros} is @code{True}. See A.5.1(46)."
16806 The sign of zeroes follows the requirements of the IEEE 754 standard on
16814 @code{Numerics.Float_Random.Max_Image_Width}. See A.5.2(27)."
16817 Maximum image width is 6864, see library file @code{s-rannum.ads}.
16824 @code{Numerics.Discrete_Random.Max_Image_Width}. See A.5.2(27)."
16827 Maximum image width is 6864, see library file @code{s-rannum.ads}.
16833 "The algorithms for random number generation. See
16837 The algorithm is the Mersenne Twister, as documented in the source file
16838 @code{s-rannum.adb}. This version of the algorithm has a period of
16845 "The string representation of a random number generator's
16846 state. See A.5.2(38)."
16849 The value returned by the Image function is the concatenation of
16850 the fixed-width decimal representations of the 624 32-bit integers
16851 of the state vector.
16857 "The minimum time interval between calls to the
16858 time-dependent Reset procedure that are guaranteed to initiate different
16859 random number sequences. See A.5.2(45)."
16862 The minimum period between reset calls to guarantee distinct series of
16863 random numbers is one microsecond.
16869 "The values of the @code{Model_Mantissa},
16870 @code{Model_Emin}, @code{Model_Epsilon}, @code{Model},
16871 @code{Safe_First}, and @code{Safe_Last} attributes, if the Numerics
16872 Annex is not supported. See A.5.3(72)."
16875 Run the compiler with @emph{-gnatS} to produce a listing of package
16876 @code{Standard}, has the values of all numeric attributes.
16882 "Any implementation-defined characteristics of the
16883 input-output packages. See A.7(14)."
16886 There are no special implementation defined characteristics for these
16893 "The value of @code{Buffer_Size} in @code{Storage_IO}. See
16897 All type representations are contiguous, and the @code{Buffer_Size} is
16898 the value of @code{type'Size} rounded up to the next storage unit
16905 "External files for standard input, standard output, and
16906 standard error See A.10(5)."
16909 These files are mapped onto the files provided by the C streams
16910 libraries. See source file @code{i-cstrea.ads} for further details.
16916 "The accuracy of the value produced by @code{Put}. See
16920 If more digits are requested in the output than are represented by the
16921 precision of the value, zeroes are output in the corresponding least
16922 significant digit positions.
16928 "The meaning of @code{Argument_Count}, @code{Argument}, and
16929 @code{Command_Name}. See A.15(1)."
16932 These are mapped onto the @code{argv} and @code{argc} parameters of the
16933 main program in the natural manner.
16939 "The interpretation of the @code{Form} parameter in procedure
16940 @code{Create_Directory}. See A.16(56)."
16943 The @code{Form} parameter is not used.
16949 "The interpretation of the @code{Form} parameter in procedure
16950 @code{Create_Path}. See A.16(60)."
16953 The @code{Form} parameter is not used.
16959 "The interpretation of the @code{Form} parameter in procedure
16960 @code{Copy_File}. See A.16(68)."
16963 The @code{Form} parameter is case-insensitive.
16964 Two fields are recognized in the @code{Form} parameter:
16971 <value> starts immediately after the character '=' and ends with the
16972 character immediately preceding the next comma (',') or with the last
16973 character of the parameter.
16975 The only possible values for preserve= are:
16978 @multitable {xxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
16989 @emph{no_attributes}
16993 Do not try to preserve any file attributes. This is the
16994 default if no preserve= is found in Form.
16998 @emph{all_attributes}
17002 Try to preserve all file attributes (timestamps, access rights).
17010 Preserve the timestamp of the copied file, but not the other
17016 The only possible values for mode= are:
17019 @multitable {xxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
17034 Only do the copy if the destination file does not already exist.
17035 If it already exists, Copy_File fails.
17043 Copy the file in all cases. Overwrite an already existing destination file.
17051 Append the original file to the destination file. If the destination file
17052 does not exist, the destination file is a copy of the source file.
17053 When mode=append, the field preserve=, if it exists, is not taken into account.
17058 If the Form parameter includes one or both of the fields and the value or
17059 values are incorrect, Copy_file fails with Use_Error.
17061 Examples of correct Forms:
17064 Form => "preserve=no_attributes,mode=overwrite" (the default)
17065 Form => "mode=append"
17066 Form => "mode=copy, preserve=all_attributes"
17069 Examples of incorrect Forms:
17072 Form => "preserve=junk"
17073 Form => "mode=internal, preserve=timestamps"
17080 "The interpretation of the @code{Pattern} parameter, when not the null string,
17081 in the @code{Start_Search} and @code{Search} procedures.
17082 See A.16(104) and A.16(112)."
17085 When the @code{Pattern} parameter is not the null string, it is interpreted
17086 according to the syntax of regular expressions as defined in the
17087 @code{GNAT.Regexp} package.
17089 See @ref{25a,,GNAT.Regexp (g-regexp.ads)}.
17095 "Implementation-defined convention names. See B.1(11)."
17098 The following convention names are supported
17101 @multitable {xxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
17120 @emph{Ada_Pass_By_Copy}
17124 Allowed for any types except by-reference types such as limited
17125 records. Compatible with convention Ada, but causes any parameters
17126 with this convention to be passed by copy.
17130 @emph{Ada_Pass_By_Reference}
17134 Allowed for any types except by-copy types such as scalars.
17135 Compatible with convention Ada, but causes any parameters
17136 with this convention to be passed by reference.
17152 Synonym for Assembler
17160 Synonym for Assembler
17172 @emph{C_Pass_By_Copy}
17176 Allowed only for record types, like C, but also notes that record
17177 is to be passed by copy rather than reference.
17189 @emph{C_Plus_Plus (or CPP)}
17201 Treated the same as C
17209 Treated the same as C
17225 For support of pragma @code{Import} with convention Intrinsic, see
17226 separate section on Intrinsic Subprograms.
17234 Stdcall (used for Windows implementations only). This convention correspond
17235 to the WINAPI (previously called Pascal convention) C/C++ convention under
17236 Windows. A routine with this convention cleans the stack before
17237 exit. This pragma cannot be applied to a dispatching call.
17245 Synonym for Stdcall
17253 Synonym for Stdcall
17261 Stubbed is a special convention used to indicate that the body of the
17262 subprogram will be entirely ignored. Any call to the subprogram
17263 is converted into a raise of the @code{Program_Error} exception. If a
17264 pragma @code{Import} specifies convention @code{stubbed} then no body need
17265 be present at all. This convention is useful during development for the
17266 inclusion of subprograms whose body has not yet been written.
17267 In addition, all otherwise unrecognized convention names are also
17268 treated as being synonymous with convention C. In all implementations
17269 except for VMS, use of such other names results in a warning. In VMS
17270 implementations, these names are accepted silently.
17279 "The meaning of link names. See B.1(36)."
17282 Link names are the actual names used by the linker.
17288 "The manner of choosing link names when neither the link
17289 name nor the address of an imported or exported entity is specified. See
17293 The default linker name is that which would be assigned by the relevant
17294 external language, interpreting the Ada name as being in all lower case
17301 "The effect of pragma @code{Linker_Options}. See B.1(37)."
17304 The string passed to @code{Linker_Options} is presented uninterpreted as
17305 an argument to the link command, unless it contains ASCII.NUL characters.
17306 NUL characters if they appear act as argument separators, so for example
17309 pragma Linker_Options ("-labc" & ASCII.NUL & "-ldef");
17312 causes two separate arguments @code{-labc} and @code{-ldef} to be passed to the
17313 linker. The order of linker options is preserved for a given unit. The final
17314 list of options passed to the linker is in reverse order of the elaboration
17315 order. For example, linker options for a body always appear before the options
17316 from the corresponding package spec.
17322 "The contents of the visible part of package
17323 @code{Interfaces} and its language-defined descendants. See B.2(1)."
17326 See files with prefix @code{i-} in the distributed library.
17332 "Implementation-defined children of package
17333 @code{Interfaces}. The contents of the visible part of package
17334 @code{Interfaces}. See B.2(11)."
17337 See files with prefix @code{i-} in the distributed library.
17343 "The types @code{Floating}, @code{Long_Floating},
17344 @code{Binary}, @code{Long_Binary}, @code{Decimal_ Element}, and
17345 @code{COBOL_Character}; and the initialization of the variables
17346 @code{Ada_To_COBOL} and @code{COBOL_To_Ada}, in
17347 @code{Interfaces.COBOL}. See B.4(50)."
17351 @multitable {xxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
17370 @emph{Long_Floating}
17374 (Floating) Long_Float
17394 @emph{Decimal_Element}
17402 @emph{COBOL_Character}
17411 For initialization, see the file @code{i-cobol.ads} in the distributed library.
17417 "Support for access to machine instructions. See C.1(1)."
17420 See documentation in file @code{s-maccod.ads} in the distributed library.
17426 "Implementation-defined aspects of access to machine
17427 operations. See C.1(9)."
17430 See documentation in file @code{s-maccod.ads} in the distributed library.
17436 "Implementation-defined aspects of interrupts. See C.3(2)."
17439 Interrupts are mapped to signals or conditions as appropriate. See
17441 @code{Ada.Interrupt_Names} in source file @code{a-intnam.ads} for details
17442 on the interrupts supported on a particular target.
17448 "Implementation-defined aspects of pre-elaboration. See
17452 GNAT does not permit a partition to be restarted without reloading,
17453 except under control of the debugger.
17459 "The semantics of pragma @code{Discard_Names}. See C.5(7)."
17462 Pragma @code{Discard_Names} causes names of enumeration literals to
17463 be suppressed. In the presence of this pragma, the Image attribute
17464 provides the image of the Pos of the literal, and Value accepts
17467 For tagged types, when pragmas @code{Discard_Names} and @code{No_Tagged_Streams}
17468 simultaneously apply, their Expanded_Name and External_Tag are initialized
17469 with empty strings. This is useful to avoid exposing entity names at binary
17476 "The result of the @code{Task_Identification.Image}
17477 attribute. See C.7.1(7)."
17480 The result of this attribute is a string that identifies
17481 the object or component that denotes a given task. If a variable @code{Var}
17482 has a task type, the image for this task will have the form @code{Var_@emph{XXXXXXXX}},
17483 where the suffix @emph{XXXXXXXX}
17484 is the hexadecimal representation of the virtual address of the corresponding
17485 task control block. If the variable is an array of tasks, the image of each
17486 task will have the form of an indexed component indicating the position of a
17487 given task in the array, e.g., @code{Group(5)_@emph{XXXXXXX}}. If the task is a
17488 component of a record, the image of the task will have the form of a selected
17489 component. These rules are fully recursive, so that the image of a task that
17490 is a subcomponent of a composite object corresponds to the expression that
17491 designates this task.
17493 If a task is created by an allocator, its image depends on the context. If the
17494 allocator is part of an object declaration, the rules described above are used
17495 to construct its image, and this image is not affected by subsequent
17496 assignments. If the allocator appears within an expression, the image
17497 includes only the name of the task type.
17499 If the configuration pragma Discard_Names is present, or if the restriction
17500 No_Implicit_Heap_Allocation is in effect, the image reduces to
17501 the numeric suffix, that is to say the hexadecimal representation of the
17502 virtual address of the control block of the task.
17508 "The value of @code{Current_Task} when in a protected entry
17509 or interrupt handler. See C.7.1(17)."
17512 Protected entries or interrupt handlers can be executed by any
17513 convenient thread, so the value of @code{Current_Task} is undefined.
17519 "The effect of calling @code{Current_Task} from an entry
17520 body or interrupt handler. See C.7.1(19)."
17523 When GNAT can determine statically that @code{Current_Task} is called directly in
17524 the body of an entry (or barrier) then a warning is emitted and @code{Program_Error}
17525 is raised at run time. Otherwise, the effect of calling @code{Current_Task} from an
17526 entry body or interrupt handler is to return the identification of the task
17527 currently executing the code.
17533 "Implementation-defined aspects of
17534 @code{Task_Attributes}. See C.7.2(19)."
17537 There are no implementation-defined aspects of @code{Task_Attributes}.
17543 "Values of all @code{Metrics}. See D(2)."
17546 The metrics information for GNAT depends on the performance of the
17547 underlying operating system. The sources of the run-time for tasking
17548 implementation, together with the output from @emph{-gnatG} can be
17549 used to determine the exact sequence of operating systems calls made
17550 to implement various tasking constructs. Together with appropriate
17551 information on the performance of the underlying operating system,
17552 on the exact target in use, this information can be used to determine
17553 the required metrics.
17559 "The declarations of @code{Any_Priority} and
17560 @code{Priority}. See D.1(11)."
17563 See declarations in file @code{system.ads}.
17569 "Implementation-defined execution resources. See D.1(15)."
17572 There are no implementation-defined execution resources.
17578 "Whether, on a multiprocessor, a task that is waiting for
17579 access to a protected object keeps its processor busy. See D.2.1(3)."
17582 On a multi-processor, a task that is waiting for access to a protected
17583 object does not keep its processor busy.
17589 "The affect of implementation defined execution resources
17590 on task dispatching. See D.2.1(9)."
17593 Tasks map to threads in the threads package used by GNAT. Where possible
17594 and appropriate, these threads correspond to native threads of the
17595 underlying operating system.
17601 "Implementation-defined @emph{policy_identifiers} allowed
17602 in a pragma @code{Task_Dispatching_Policy}. See D.2.2(3)."
17605 There are no implementation-defined policy-identifiers allowed in this
17612 "Implementation-defined aspects of priority inversion. See
17616 Execution of a task cannot be preempted by the implementation processing
17617 of delay expirations for lower priority tasks.
17623 "Implementation-defined task dispatching. See D.2.2(18)."
17626 The policy is the same as that of the underlying threads implementation.
17632 "Implementation-defined @emph{policy_identifiers} allowed
17633 in a pragma @code{Locking_Policy}. See D.3(4)."
17636 The two implementation defined policies permitted in GNAT are
17637 @code{Inheritance_Locking} and @code{Concurrent_Readers_Locking}. On
17638 targets that support the @code{Inheritance_Locking} policy, locking is
17639 implemented by inheritance, i.e., the task owning the lock operates
17640 at a priority equal to the highest priority of any task currently
17641 requesting the lock. On targets that support the
17642 @code{Concurrent_Readers_Locking} policy, locking is implemented with a
17643 read/write lock allowing multiple protected object functions to enter
17650 "Default ceiling priorities. See D.3(10)."
17653 The ceiling priority of protected objects of the type
17654 @code{System.Interrupt_Priority'Last} as described in the Ada
17655 Reference Manual D.3(10),
17661 "The ceiling of any protected object used internally by
17662 the implementation. See D.3(16)."
17665 The ceiling priority of internal protected objects is
17666 @code{System.Priority'Last}.
17672 "Implementation-defined queuing policies. See D.4(1)."
17675 There are no implementation-defined queuing policies.
17681 "On a multiprocessor, any conditions that cause the
17682 completion of an aborted construct to be delayed later than what is
17683 specified for a single processor. See D.6(3)."
17686 The semantics for abort on a multi-processor is the same as on a single
17687 processor, there are no further delays.
17693 "Any operations that implicitly require heap storage
17694 allocation. See D.7(8)."
17697 The only operation that implicitly requires heap storage allocation is
17704 "What happens when a task terminates in the presence of
17705 pragma @code{No_Task_Termination}. See D.7(15)."
17708 Execution is erroneous in that case.
17714 "Implementation-defined aspects of pragma
17715 @code{Restrictions}. See D.7(20)."
17718 There are no such implementation-defined aspects.
17724 "Implementation-defined aspects of package
17725 @code{Real_Time}. See D.8(17)."
17728 There are no implementation defined aspects of package @code{Real_Time}.
17734 "Implementation-defined aspects of
17735 @emph{delay_statements}. See D.9(8)."
17738 Any difference greater than one microsecond will cause the task to be
17739 delayed (see D.9(7)).
17745 "The upper bound on the duration of interrupt blocking
17746 caused by the implementation. See D.12(5)."
17749 The upper bound is determined by the underlying operating system. In
17750 no cases is it more than 10 milliseconds.
17756 "The means for creating and executing distributed
17757 programs. See E(5)."
17760 The GLADE package provides a utility GNATDIST for creating and executing
17761 distributed programs. See the GLADE reference manual for further details.
17767 "Any events that can result in a partition becoming
17768 inaccessible. See E.1(7)."
17771 See the GLADE reference manual for full details on such events.
17777 "The scheduling policies, treatment of priorities, and
17778 management of shared resources between partitions in certain cases. See
17782 See the GLADE reference manual for full details on these aspects of
17783 multi-partition execution.
17789 "Events that cause the version of a compilation unit to
17790 change. See E.3(5)."
17793 Editing the source file of a compilation unit, or the source files of
17794 any units on which it is dependent in a significant way cause the version
17795 to change. No other actions cause the version number to change. All changes
17796 are significant except those which affect only layout, capitalization or
17803 "Whether the execution of the remote subprogram is
17804 immediately aborted as a result of cancellation. See E.4(13)."
17807 See the GLADE reference manual for details on the effect of abort in
17808 a distributed application.
17814 "Implementation-defined aspects of the PCS. See E.5(25)."
17817 See the GLADE reference manual for a full description of all implementation
17818 defined aspects of the PCS.
17824 "Implementation-defined interfaces in the PCS. See
17828 See the GLADE reference manual for a full description of all
17829 implementation defined interfaces.
17835 "The values of named numbers in the package
17836 @code{Decimal}. See F.2(7)."
17840 @multitable {xxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxx}
17883 @emph{Max_Decimal_Digits}
17896 "The value of @code{Max_Picture_Length} in the package
17897 @code{Text_IO.Editing}. See F.3.3(16)."
17906 "The value of @code{Max_Picture_Length} in the package
17907 @code{Wide_Text_IO.Editing}. See F.3.4(5)."
17916 "The accuracy actually achieved by the complex elementary
17917 functions and by other complex arithmetic operations. See G.1(1)."
17920 Standard library functions are used for the complex arithmetic
17921 operations. Only fast math mode is currently supported.
17927 "The sign of a zero result (or a component thereof) from
17928 any operator or function in @code{Numerics.Generic_Complex_Types}, when
17929 @code{Real'Signed_Zeros} is True. See G.1.1(53)."
17932 The signs of zero values are as recommended by the relevant
17933 implementation advice.
17939 "The sign of a zero result (or a component thereof) from
17940 any operator or function in
17941 @code{Numerics.Generic_Complex_Elementary_Functions}, when
17942 @code{Real'Signed_Zeros} is @code{True}. See G.1.2(45)."
17945 The signs of zero values are as recommended by the relevant
17946 implementation advice.
17952 "Whether the strict mode or the relaxed mode is the
17953 default. See G.2(2)."
17956 The strict mode is the default. There is no separate relaxed mode. GNAT
17957 provides a highly efficient implementation of strict mode.
17963 "The result interval in certain cases of fixed-to-float
17964 conversion. See G.2.1(10)."
17967 For cases where the result interval is implementation dependent, the
17968 accuracy is that provided by performing all operations in 64-bit IEEE
17969 floating-point format.
17975 "The result of a floating point arithmetic operation in
17976 overflow situations, when the @code{Machine_Overflows} attribute of the
17977 result type is @code{False}. See G.2.1(13)."
17980 Infinite and NaN values are produced as dictated by the IEEE
17981 floating-point standard.
17982 Note that on machines that are not fully compliant with the IEEE
17983 floating-point standard, such as Alpha, the @emph{-mieee} compiler flag
17984 must be used for achieving IEEE conforming behavior (although at the cost
17985 of a significant performance penalty), so infinite and NaN values are
17986 properly generated.
17992 "The result interval for division (or exponentiation by a
17993 negative exponent), when the floating point hardware implements division
17994 as multiplication by a reciprocal. See G.2.1(16)."
17997 Not relevant, division is IEEE exact.
18003 "The definition of close result set, which determines the
18004 accuracy of certain fixed point multiplications and divisions. See
18008 Operations in the close result set are performed using IEEE long format
18009 floating-point arithmetic. The input operands are converted to
18010 floating-point, the operation is done in floating-point, and the result
18011 is converted to the target type.
18017 "Conditions on a @emph{universal_real} operand of a fixed
18018 point multiplication or division for which the result shall be in the
18019 perfect result set. See G.2.3(22)."
18022 The result is only defined to be in the perfect result set if the result
18023 can be computed by a single scaling operation involving a scale factor
18024 representable in 64-bits.
18030 "The result of a fixed point arithmetic operation in
18031 overflow situations, when the @code{Machine_Overflows} attribute of the
18032 result type is @code{False}. See G.2.3(27)."
18035 Not relevant, @code{Machine_Overflows} is @code{True} for fixed-point
18042 "The result of an elementary function reference in
18043 overflow situations, when the @code{Machine_Overflows} attribute of the
18044 result type is @code{False}. See G.2.4(4)."
18047 IEEE infinite and Nan values are produced as appropriate.
18053 "The value of the angle threshold, within which certain
18054 elementary functions, complex arithmetic operations, and complex
18055 elementary functions yield results conforming to a maximum relative
18056 error bound. See G.2.4(10)."
18059 Information on this subject is not yet available.
18065 "The accuracy of certain elementary functions for
18066 parameters beyond the angle threshold. See G.2.4(10)."
18069 Information on this subject is not yet available.
18075 "The result of a complex arithmetic operation or complex
18076 elementary function reference in overflow situations, when the
18077 @code{Machine_Overflows} attribute of the corresponding real type is
18078 @code{False}. See G.2.6(5)."
18081 IEEE infinite and Nan values are produced as appropriate.
18087 "The accuracy of certain complex arithmetic operations and
18088 certain complex elementary functions for parameters (or components
18089 thereof) beyond the angle threshold. See G.2.6(8)."
18092 Information on those subjects is not yet available.
18098 "Information regarding bounded errors and erroneous
18099 execution. See H.2(1)."
18102 Information on this subject is not yet available.
18108 "Implementation-defined aspects of pragma
18109 @code{Inspection_Point}. See H.3.2(8)."
18112 Pragma @code{Inspection_Point} ensures that the variable is live and can
18113 be examined by the debugger at the inspection point.
18119 "Implementation-defined aspects of pragma
18120 @code{Restrictions}. See H.4(25)."
18123 There are no implementation-defined aspects of pragma @code{Restrictions}. The
18124 use of pragma @code{Restrictions [No_Exceptions]} has no effect on the
18125 generated code. Checks must suppressed by use of pragma @code{Suppress}.
18131 "Any restrictions on pragma @code{Restrictions}. See
18135 There are no restrictions on pragma @code{Restrictions}.
18137 @node Intrinsic Subprograms,Representation Clauses and Pragmas,Implementation Defined Characteristics,Top
18138 @anchor{gnat_rm/intrinsic_subprograms doc}@anchor{25b}@anchor{gnat_rm/intrinsic_subprograms intrinsic-subprograms}@anchor{c}@anchor{gnat_rm/intrinsic_subprograms id1}@anchor{25c}
18139 @chapter Intrinsic Subprograms
18142 @geindex Intrinsic Subprograms
18144 GNAT allows a user application program to write the declaration:
18147 pragma Import (Intrinsic, name);
18150 providing that the name corresponds to one of the implemented intrinsic
18151 subprograms in GNAT, and that the parameter profile of the referenced
18152 subprogram meets the requirements. This chapter describes the set of
18153 implemented intrinsic subprograms, and the requirements on parameter profiles.
18154 Note that no body is supplied; as with other uses of pragma Import, the
18155 body is supplied elsewhere (in this case by the compiler itself). Note
18156 that any use of this feature is potentially non-portable, since the
18157 Ada standard does not require Ada compilers to implement this feature.
18160 * Intrinsic Operators::
18161 * Compilation_ISO_Date::
18162 * Compilation_Date::
18163 * Compilation_Time::
18164 * Enclosing_Entity::
18165 * Exception_Information::
18166 * Exception_Message::
18170 * Shifts and Rotates::
18171 * Source_Location::
18175 @node Intrinsic Operators,Compilation_ISO_Date,,Intrinsic Subprograms
18176 @anchor{gnat_rm/intrinsic_subprograms id2}@anchor{25d}@anchor{gnat_rm/intrinsic_subprograms intrinsic-operators}@anchor{25e}
18177 @section Intrinsic Operators
18180 @geindex Intrinsic operator
18182 All the predefined numeric operators in package Standard
18183 in @code{pragma Import (Intrinsic,..)}
18184 declarations. In the binary operator case, the operands must have the same
18185 size. The operand or operands must also be appropriate for
18186 the operator. For example, for addition, the operands must
18187 both be floating-point or both be fixed-point, and the
18188 right operand for @code{"**"} must have a root type of
18189 @code{Standard.Integer'Base}.
18190 You can use an intrinsic operator declaration as in the following example:
18193 type Int1 is new Integer;
18194 type Int2 is new Integer;
18196 function "+" (X1 : Int1; X2 : Int2) return Int1;
18197 function "+" (X1 : Int1; X2 : Int2) return Int2;
18198 pragma Import (Intrinsic, "+");
18201 This declaration would permit 'mixed mode' arithmetic on items
18202 of the differing types @code{Int1} and @code{Int2}.
18203 It is also possible to specify such operators for private types, if the
18204 full views are appropriate arithmetic types.
18206 @node Compilation_ISO_Date,Compilation_Date,Intrinsic Operators,Intrinsic Subprograms
18207 @anchor{gnat_rm/intrinsic_subprograms id3}@anchor{25f}@anchor{gnat_rm/intrinsic_subprograms compilation-iso-date}@anchor{260}
18208 @section Compilation_ISO_Date
18211 @geindex Compilation_ISO_Date
18213 This intrinsic subprogram is used in the implementation of the
18214 library package @code{GNAT.Source_Info}. The only useful use of the
18215 intrinsic import in this case is the one in this unit, so an
18216 application program should simply call the function
18217 @code{GNAT.Source_Info.Compilation_ISO_Date} to obtain the date of
18218 the current compilation (in local time format YYYY-MM-DD).
18220 @node Compilation_Date,Compilation_Time,Compilation_ISO_Date,Intrinsic Subprograms
18221 @anchor{gnat_rm/intrinsic_subprograms compilation-date}@anchor{261}@anchor{gnat_rm/intrinsic_subprograms id4}@anchor{262}
18222 @section Compilation_Date
18225 @geindex Compilation_Date
18227 Same as Compilation_ISO_Date, except the string is in the form
18230 @node Compilation_Time,Enclosing_Entity,Compilation_Date,Intrinsic Subprograms
18231 @anchor{gnat_rm/intrinsic_subprograms compilation-time}@anchor{263}@anchor{gnat_rm/intrinsic_subprograms id5}@anchor{264}
18232 @section Compilation_Time
18235 @geindex Compilation_Time
18237 This intrinsic subprogram is used in the implementation of the
18238 library package @code{GNAT.Source_Info}. The only useful use of the
18239 intrinsic import in this case is the one in this unit, so an
18240 application program should simply call the function
18241 @code{GNAT.Source_Info.Compilation_Time} to obtain the time of
18242 the current compilation (in local time format HH:MM:SS).
18244 @node Enclosing_Entity,Exception_Information,Compilation_Time,Intrinsic Subprograms
18245 @anchor{gnat_rm/intrinsic_subprograms id6}@anchor{265}@anchor{gnat_rm/intrinsic_subprograms enclosing-entity}@anchor{266}
18246 @section Enclosing_Entity
18249 @geindex Enclosing_Entity
18251 This intrinsic subprogram is used in the implementation of the
18252 library package @code{GNAT.Source_Info}. The only useful use of the
18253 intrinsic import in this case is the one in this unit, so an
18254 application program should simply call the function
18255 @code{GNAT.Source_Info.Enclosing_Entity} to obtain the name of
18256 the current subprogram, package, task, entry, or protected subprogram.
18258 @node Exception_Information,Exception_Message,Enclosing_Entity,Intrinsic Subprograms
18259 @anchor{gnat_rm/intrinsic_subprograms id7}@anchor{267}@anchor{gnat_rm/intrinsic_subprograms exception-information}@anchor{268}
18260 @section Exception_Information
18263 @geindex Exception_Information'
18265 This intrinsic subprogram is used in the implementation of the
18266 library package @code{GNAT.Current_Exception}. The only useful
18267 use of the intrinsic import in this case is the one in this unit,
18268 so an application program should simply call the function
18269 @code{GNAT.Current_Exception.Exception_Information} to obtain
18270 the exception information associated with the current exception.
18272 @node Exception_Message,Exception_Name,Exception_Information,Intrinsic Subprograms
18273 @anchor{gnat_rm/intrinsic_subprograms exception-message}@anchor{269}@anchor{gnat_rm/intrinsic_subprograms id8}@anchor{26a}
18274 @section Exception_Message
18277 @geindex Exception_Message
18279 This intrinsic subprogram is used in the implementation of the
18280 library package @code{GNAT.Current_Exception}. The only useful
18281 use of the intrinsic import in this case is the one in this unit,
18282 so an application program should simply call the function
18283 @code{GNAT.Current_Exception.Exception_Message} to obtain
18284 the message associated with the current exception.
18286 @node Exception_Name,File,Exception_Message,Intrinsic Subprograms
18287 @anchor{gnat_rm/intrinsic_subprograms exception-name}@anchor{26b}@anchor{gnat_rm/intrinsic_subprograms id9}@anchor{26c}
18288 @section Exception_Name
18291 @geindex Exception_Name
18293 This intrinsic subprogram is used in the implementation of the
18294 library package @code{GNAT.Current_Exception}. The only useful
18295 use of the intrinsic import in this case is the one in this unit,
18296 so an application program should simply call the function
18297 @code{GNAT.Current_Exception.Exception_Name} to obtain
18298 the name of the current exception.
18300 @node File,Line,Exception_Name,Intrinsic Subprograms
18301 @anchor{gnat_rm/intrinsic_subprograms id10}@anchor{26d}@anchor{gnat_rm/intrinsic_subprograms file}@anchor{26e}
18307 This intrinsic subprogram is used in the implementation of the
18308 library package @code{GNAT.Source_Info}. The only useful use of the
18309 intrinsic import in this case is the one in this unit, so an
18310 application program should simply call the function
18311 @code{GNAT.Source_Info.File} to obtain the name of the current
18314 @node Line,Shifts and Rotates,File,Intrinsic Subprograms
18315 @anchor{gnat_rm/intrinsic_subprograms id11}@anchor{26f}@anchor{gnat_rm/intrinsic_subprograms line}@anchor{270}
18321 This intrinsic subprogram is used in the implementation of the
18322 library package @code{GNAT.Source_Info}. The only useful use of the
18323 intrinsic import in this case is the one in this unit, so an
18324 application program should simply call the function
18325 @code{GNAT.Source_Info.Line} to obtain the number of the current
18328 @node Shifts and Rotates,Source_Location,Line,Intrinsic Subprograms
18329 @anchor{gnat_rm/intrinsic_subprograms shifts-and-rotates}@anchor{271}@anchor{gnat_rm/intrinsic_subprograms id12}@anchor{272}
18330 @section Shifts and Rotates
18333 @geindex Shift_Left
18335 @geindex Shift_Right
18337 @geindex Shift_Right_Arithmetic
18339 @geindex Rotate_Left
18341 @geindex Rotate_Right
18343 In standard Ada, the shift and rotate functions are available only
18344 for the predefined modular types in package @code{Interfaces}. However, in
18345 GNAT it is possible to define these functions for any integer
18346 type (signed or modular), as in this example:
18349 function Shift_Left
18351 Amount : Natural) return T;
18354 The function name must be one of
18355 Shift_Left, Shift_Right, Shift_Right_Arithmetic, Rotate_Left, or
18356 Rotate_Right. T must be an integer type. T'Size must be
18357 8, 16, 32 or 64 bits; if T is modular, the modulus
18358 must be 2**8, 2**16, 2**32 or 2**64.
18359 The result type must be the same as the type of @code{Value}.
18360 The shift amount must be Natural.
18361 The formal parameter names can be anything.
18363 A more convenient way of providing these shift operators is to use
18364 the Provide_Shift_Operators pragma, which provides the function declarations
18365 and corresponding pragma Import's for all five shift functions.
18367 @node Source_Location,,Shifts and Rotates,Intrinsic Subprograms
18368 @anchor{gnat_rm/intrinsic_subprograms source-location}@anchor{273}@anchor{gnat_rm/intrinsic_subprograms id13}@anchor{274}
18369 @section Source_Location
18372 @geindex Source_Location
18374 This intrinsic subprogram is used in the implementation of the
18375 library routine @code{GNAT.Source_Info}. The only useful use of the
18376 intrinsic import in this case is the one in this unit, so an
18377 application program should simply call the function
18378 @code{GNAT.Source_Info.Source_Location} to obtain the current
18379 source file location.
18381 @node Representation Clauses and Pragmas,Standard Library Routines,Intrinsic Subprograms,Top
18382 @anchor{gnat_rm/representation_clauses_and_pragmas representation-clauses-and-pragmas}@anchor{d}@anchor{gnat_rm/representation_clauses_and_pragmas doc}@anchor{275}@anchor{gnat_rm/representation_clauses_and_pragmas id1}@anchor{276}
18383 @chapter Representation Clauses and Pragmas
18386 @geindex Representation Clauses
18388 @geindex Representation Clause
18390 @geindex Representation Pragma
18393 @geindex representation
18395 This section describes the representation clauses accepted by GNAT, and
18396 their effect on the representation of corresponding data objects.
18398 GNAT fully implements Annex C (Systems Programming). This means that all
18399 the implementation advice sections in chapter 13 are fully implemented.
18400 However, these sections only require a minimal level of support for
18401 representation clauses. GNAT provides much more extensive capabilities,
18402 and this section describes the additional capabilities provided.
18405 * Alignment Clauses::
18407 * Storage_Size Clauses::
18408 * Size of Variant Record Objects::
18409 * Biased Representation::
18410 * Value_Size and Object_Size Clauses::
18411 * Component_Size Clauses::
18412 * Bit_Order Clauses::
18413 * Effect of Bit_Order on Byte Ordering::
18414 * Pragma Pack for Arrays::
18415 * Pragma Pack for Records::
18416 * Record Representation Clauses::
18417 * Handling of Records with Holes::
18418 * Enumeration Clauses::
18419 * Address Clauses::
18420 * Use of Address Clauses for Memory-Mapped I/O::
18421 * Effect of Convention on Representation::
18422 * Conventions and Anonymous Access Types::
18423 * Determining the Representations chosen by GNAT::
18427 @node Alignment Clauses,Size Clauses,,Representation Clauses and Pragmas
18428 @anchor{gnat_rm/representation_clauses_and_pragmas id2}@anchor{277}@anchor{gnat_rm/representation_clauses_and_pragmas alignment-clauses}@anchor{278}
18429 @section Alignment Clauses
18432 @geindex Alignment Clause
18434 GNAT requires that all alignment clauses specify 0 or a power of 2, and
18435 all default alignments are always a power of 2. Specifying 0 is the
18436 same as specifying 1.
18438 The default alignment values are as follows:
18444 @emph{Elementary Types}.
18446 For elementary types, the alignment is the minimum of the actual size of
18447 objects of the type divided by @code{Storage_Unit},
18448 and the maximum alignment supported by the target.
18449 (This maximum alignment is given by the GNAT-specific attribute
18450 @code{Standard'Maximum_Alignment}; see @ref{192,,Attribute Maximum_Alignment}.)
18452 @geindex Maximum_Alignment attribute
18454 For example, for type @code{Long_Float}, the object size is 8 bytes, and the
18455 default alignment will be 8 on any target that supports alignments
18456 this large, but on some targets, the maximum alignment may be smaller
18457 than 8, in which case objects of type @code{Long_Float} will be maximally
18463 For arrays, the alignment is equal to the alignment of the component type
18464 for the normal case where no packing or component size is given. If the
18465 array is packed, and the packing is effective (see separate section on
18466 packed arrays), then the alignment will be either 4, 2, or 1 for long packed
18467 arrays or arrays whose length is not known at compile time, depending on
18468 whether the component size is divisible by 4, 2, or is odd. For short packed
18469 arrays, which are handled internally as modular types, the alignment
18470 will be as described for elementary types, e.g. a packed array of length
18471 31 bits will have an object size of four bytes, and an alignment of 4.
18476 For the normal unpacked case, the alignment of a record is equal to
18477 the maximum alignment of any of its components. For tagged records, this
18478 includes the implicit access type used for the tag. If a pragma @code{Pack}
18479 is used and all components are packable (see separate section on pragma
18480 @code{Pack}), then the resulting alignment is 1, unless the layout of the
18481 record makes it profitable to increase it.
18483 A special case is when:
18489 the size of the record is given explicitly, or a
18490 full record representation clause is given, and
18493 the size of the record is 2, 4, or 8 bytes.
18496 In this case, an alignment is chosen to match the
18497 size of the record. For example, if we have:
18500 type Small is record
18503 for Small'Size use 16;
18506 then the default alignment of the record type @code{Small} is 2, not 1. This
18507 leads to more efficient code when the record is treated as a unit, and also
18508 allows the type to specified as @code{Atomic} on architectures requiring
18512 An alignment clause may specify a larger alignment than the default value
18513 up to some maximum value dependent on the target (obtainable by using the
18514 attribute reference @code{Standard'Maximum_Alignment}). It may also specify
18515 a smaller alignment than the default value for enumeration, integer and
18516 fixed point types, as well as for record types, for example
18523 for V'alignment use 1;
18529 The default alignment for the type @code{V} is 4, as a result of the
18530 Integer field in the record, but it is permissible, as shown, to
18531 override the default alignment of the record with a smaller value.
18536 Note that according to the Ada standard, an alignment clause applies only
18537 to the first named subtype. If additional subtypes are declared, then the
18538 compiler is allowed to choose any alignment it likes, and there is no way
18539 to control this choice. Consider:
18542 type R is range 1 .. 10_000;
18543 for R'Alignment use 1;
18544 subtype RS is R range 1 .. 1000;
18547 The alignment clause specifies an alignment of 1 for the first named subtype
18548 @code{R} but this does not necessarily apply to @code{RS}. When writing
18549 portable Ada code, you should avoid writing code that explicitly or
18550 implicitly relies on the alignment of such subtypes.
18552 For the GNAT compiler, if an explicit alignment clause is given, this
18553 value is also used for any subsequent subtypes. So for GNAT, in the
18554 above example, you can count on the alignment of @code{RS} being 1. But this
18555 assumption is non-portable, and other compilers may choose different
18556 alignments for the subtype @code{RS}.
18558 @node Size Clauses,Storage_Size Clauses,Alignment Clauses,Representation Clauses and Pragmas
18559 @anchor{gnat_rm/representation_clauses_and_pragmas id3}@anchor{279}@anchor{gnat_rm/representation_clauses_and_pragmas size-clauses}@anchor{27a}
18560 @section Size Clauses
18563 @geindex Size Clause
18565 The default size for a type @code{T} is obtainable through the
18566 language-defined attribute @code{T'Size} and also through the
18567 equivalent GNAT-defined attribute @code{T'Value_Size}.
18568 For objects of type @code{T}, GNAT will generally increase the type size
18569 so that the object size (obtainable through the GNAT-defined attribute
18570 @code{T'Object_Size})
18571 is a multiple of @code{T'Alignment * Storage_Unit}.
18576 type Smallint is range 1 .. 6;
18584 In this example, @code{Smallint'Size} = @code{Smallint'Value_Size} = 3,
18585 as specified by the RM rules,
18586 but objects of this type will have a size of 8
18587 (@code{Smallint'Object_Size} = 8),
18588 since objects by default occupy an integral number
18589 of storage units. On some targets, notably older
18590 versions of the Digital Alpha, the size of stand
18591 alone objects of this type may be 32, reflecting
18592 the inability of the hardware to do byte load/stores.
18594 Similarly, the size of type @code{Rec} is 40 bits
18595 (@code{Rec'Size} = @code{Rec'Value_Size} = 40), but
18596 the alignment is 4, so objects of this type will have
18597 their size increased to 64 bits so that it is a multiple
18598 of the alignment (in bits). This decision is
18599 in accordance with the specific Implementation Advice in RM 13.3(43):
18603 "A @code{Size} clause should be supported for an object if the specified
18604 @code{Size} is at least as large as its subtype's @code{Size}, and corresponds
18605 to a size in storage elements that is a multiple of the object's
18606 @code{Alignment} (if the @code{Alignment} is nonzero)."
18609 An explicit size clause may be used to override the default size by
18610 increasing it. For example, if we have:
18613 type My_Boolean is new Boolean;
18614 for My_Boolean'Size use 32;
18617 then values of this type will always be 32 bits long. In the case of
18618 discrete types, the size can be increased up to 64 bits, with the effect
18619 that the entire specified field is used to hold the value, sign- or
18620 zero-extended as appropriate. If more than 64 bits is specified, then
18621 padding space is allocated after the value, and a warning is issued that
18622 there are unused bits.
18624 Similarly the size of records and arrays may be increased, and the effect
18625 is to add padding bits after the value. This also causes a warning message
18628 The largest Size value permitted in GNAT is 2**31-1. Since this is a
18629 Size in bits, this corresponds to an object of size 256 megabytes (minus
18630 one). This limitation is true on all targets. The reason for this
18631 limitation is that it improves the quality of the code in many cases
18632 if it is known that a Size value can be accommodated in an object of
18635 @node Storage_Size Clauses,Size of Variant Record Objects,Size Clauses,Representation Clauses and Pragmas
18636 @anchor{gnat_rm/representation_clauses_and_pragmas storage-size-clauses}@anchor{27b}@anchor{gnat_rm/representation_clauses_and_pragmas id4}@anchor{27c}
18637 @section Storage_Size Clauses
18640 @geindex Storage_Size Clause
18642 For tasks, the @code{Storage_Size} clause specifies the amount of space
18643 to be allocated for the task stack. This cannot be extended, and if the
18644 stack is exhausted, then @code{Storage_Error} will be raised (if stack
18645 checking is enabled). Use a @code{Storage_Size} attribute definition clause,
18646 or a @code{Storage_Size} pragma in the task definition to set the
18647 appropriate required size. A useful technique is to include in every
18648 task definition a pragma of the form:
18651 pragma Storage_Size (Default_Stack_Size);
18654 Then @code{Default_Stack_Size} can be defined in a global package, and
18655 modified as required. Any tasks requiring stack sizes different from the
18656 default can have an appropriate alternative reference in the pragma.
18658 You can also use the @emph{-d} binder switch to modify the default stack
18661 For access types, the @code{Storage_Size} clause specifies the maximum
18662 space available for allocation of objects of the type. If this space is
18663 exceeded then @code{Storage_Error} will be raised by an allocation attempt.
18664 In the case where the access type is declared local to a subprogram, the
18665 use of a @code{Storage_Size} clause triggers automatic use of a special
18666 predefined storage pool (@code{System.Pool_Size}) that ensures that all
18667 space for the pool is automatically reclaimed on exit from the scope in
18668 which the type is declared.
18670 A special case recognized by the compiler is the specification of a
18671 @code{Storage_Size} of zero for an access type. This means that no
18672 items can be allocated from the pool, and this is recognized at compile
18673 time, and all the overhead normally associated with maintaining a fixed
18674 size storage pool is eliminated. Consider the following example:
18678 type R is array (Natural) of Character;
18679 type P is access all R;
18680 for P'Storage_Size use 0;
18681 -- Above access type intended only for interfacing purposes
18685 procedure g (m : P);
18686 pragma Import (C, g);
18696 As indicated in this example, these dummy storage pools are often useful in
18697 connection with interfacing where no object will ever be allocated. If you
18698 compile the above example, you get the warning:
18701 p.adb:16:09: warning: allocation from empty storage pool
18702 p.adb:16:09: warning: Storage_Error will be raised at run time
18705 Of course in practice, there will not be any explicit allocators in the
18706 case of such an access declaration.
18708 @node Size of Variant Record Objects,Biased Representation,Storage_Size Clauses,Representation Clauses and Pragmas
18709 @anchor{gnat_rm/representation_clauses_and_pragmas id5}@anchor{27d}@anchor{gnat_rm/representation_clauses_and_pragmas size-of-variant-record-objects}@anchor{27e}
18710 @section Size of Variant Record Objects
18714 @geindex variant record objects
18716 @geindex Variant record objects
18719 In the case of variant record objects, there is a question whether Size gives
18720 information about a particular variant, or the maximum size required
18721 for any variant. Consider the following program
18724 with Text_IO; use Text_IO;
18726 type R1 (A : Boolean := False) is record
18728 when True => X : Character;
18729 when False => null;
18737 Put_Line (Integer'Image (V1'Size));
18738 Put_Line (Integer'Image (V2'Size));
18742 Here we are dealing with a variant record, where the True variant
18743 requires 16 bits, and the False variant requires 8 bits.
18744 In the above example, both V1 and V2 contain the False variant,
18745 which is only 8 bits long. However, the result of running the
18753 The reason for the difference here is that the discriminant value of
18754 V1 is fixed, and will always be False. It is not possible to assign
18755 a True variant value to V1, therefore 8 bits is sufficient. On the
18756 other hand, in the case of V2, the initial discriminant value is
18757 False (from the default), but it is possible to assign a True
18758 variant value to V2, therefore 16 bits must be allocated for V2
18759 in the general case, even fewer bits may be needed at any particular
18760 point during the program execution.
18762 As can be seen from the output of this program, the @code{'Size}
18763 attribute applied to such an object in GNAT gives the actual allocated
18764 size of the variable, which is the largest size of any of the variants.
18765 The Ada Reference Manual is not completely clear on what choice should
18766 be made here, but the GNAT behavior seems most consistent with the
18767 language in the RM.
18769 In some cases, it may be desirable to obtain the size of the current
18770 variant, rather than the size of the largest variant. This can be
18771 achieved in GNAT by making use of the fact that in the case of a
18772 subprogram parameter, GNAT does indeed return the size of the current
18773 variant (because a subprogram has no way of knowing how much space
18774 is actually allocated for the actual).
18776 Consider the following modified version of the above program:
18779 with Text_IO; use Text_IO;
18781 type R1 (A : Boolean := False) is record
18783 when True => X : Character;
18784 when False => null;
18790 function Size (V : R1) return Integer is
18796 Put_Line (Integer'Image (V2'Size));
18797 Put_Line (Integer'Image (Size (V2)));
18799 Put_Line (Integer'Image (V2'Size));
18800 Put_Line (Integer'Image (Size (V2)));
18804 The output from this program is
18813 Here we see that while the @code{'Size} attribute always returns
18814 the maximum size, regardless of the current variant value, the
18815 @code{Size} function does indeed return the size of the current
18818 @node Biased Representation,Value_Size and Object_Size Clauses,Size of Variant Record Objects,Representation Clauses and Pragmas
18819 @anchor{gnat_rm/representation_clauses_and_pragmas id6}@anchor{27f}@anchor{gnat_rm/representation_clauses_and_pragmas biased-representation}@anchor{280}
18820 @section Biased Representation
18823 @geindex Size for biased representation
18825 @geindex Biased representation
18827 In the case of scalars with a range starting at other than zero, it is
18828 possible in some cases to specify a size smaller than the default minimum
18829 value, and in such cases, GNAT uses an unsigned biased representation,
18830 in which zero is used to represent the lower bound, and successive values
18831 represent successive values of the type.
18833 For example, suppose we have the declaration:
18836 type Small is range -7 .. -4;
18837 for Small'Size use 2;
18840 Although the default size of type @code{Small} is 4, the @code{Size}
18841 clause is accepted by GNAT and results in the following representation
18845 -7 is represented as 2#00#
18846 -6 is represented as 2#01#
18847 -5 is represented as 2#10#
18848 -4 is represented as 2#11#
18851 Biased representation is only used if the specified @code{Size} clause
18852 cannot be accepted in any other manner. These reduced sizes that force
18853 biased representation can be used for all discrete types except for
18854 enumeration types for which a representation clause is given.
18856 @node Value_Size and Object_Size Clauses,Component_Size Clauses,Biased Representation,Representation Clauses and Pragmas
18857 @anchor{gnat_rm/representation_clauses_and_pragmas id7}@anchor{281}@anchor{gnat_rm/representation_clauses_and_pragmas value-size-and-object-size-clauses}@anchor{282}
18858 @section Value_Size and Object_Size Clauses
18861 @geindex Value_Size
18863 @geindex Object_Size
18866 @geindex of objects
18868 In Ada 95 and Ada 2005, @code{T'Size} for a type @code{T} is the minimum
18869 number of bits required to hold values of type @code{T}.
18870 Although this interpretation was allowed in Ada 83, it was not required,
18871 and this requirement in practice can cause some significant difficulties.
18872 For example, in most Ada 83 compilers, @code{Natural'Size} was 32.
18873 However, in Ada 95 and Ada 2005,
18874 @code{Natural'Size} is
18875 typically 31. This means that code may change in behavior when moving
18876 from Ada 83 to Ada 95 or Ada 2005. For example, consider:
18879 type Rec is record;
18885 at 0 range 0 .. Natural'Size - 1;
18886 at 0 range Natural'Size .. 2 * Natural'Size - 1;
18890 In the above code, since the typical size of @code{Natural} objects
18891 is 32 bits and @code{Natural'Size} is 31, the above code can cause
18892 unexpected inefficient packing in Ada 95 and Ada 2005, and in general
18893 there are cases where the fact that the object size can exceed the
18894 size of the type causes surprises.
18896 To help get around this problem GNAT provides two implementation
18897 defined attributes, @code{Value_Size} and @code{Object_Size}. When
18898 applied to a type, these attributes yield the size of the type
18899 (corresponding to the RM defined size attribute), and the size of
18900 objects of the type respectively.
18902 The @code{Object_Size} is used for determining the default size of
18903 objects and components. This size value can be referred to using the
18904 @code{Object_Size} attribute. The phrase 'is used' here means that it is
18905 the basis of the determination of the size. The backend is free to
18906 pad this up if necessary for efficiency, e.g., an 8-bit stand-alone
18907 character might be stored in 32 bits on a machine with no efficient
18908 byte access instructions such as the Alpha.
18910 The default rules for the value of @code{Object_Size} for
18911 discrete types are as follows:
18917 The @code{Object_Size} for base subtypes reflect the natural hardware
18918 size in bits (run the compiler with @emph{-gnatS} to find those values
18919 for numeric types). Enumeration types and fixed-point base subtypes have
18920 8, 16, 32, or 64 bits for this size, depending on the range of values
18924 The @code{Object_Size} of a subtype is the same as the
18925 @code{Object_Size} of
18926 the type from which it is obtained.
18929 The @code{Object_Size} of a derived base type is copied from the parent
18930 base type, and the @code{Object_Size} of a derived first subtype is copied
18931 from the parent first subtype.
18934 The @code{Value_Size} attribute
18935 is the (minimum) number of bits required to store a value
18937 This value is used to determine how tightly to pack
18938 records or arrays with components of this type, and also affects
18939 the semantics of unchecked conversion (unchecked conversions where
18940 the @code{Value_Size} values differ generate a warning, and are potentially
18943 The default rules for the value of @code{Value_Size} are as follows:
18949 The @code{Value_Size} for a base subtype is the minimum number of bits
18950 required to store all values of the type (including the sign bit
18951 only if negative values are possible).
18954 If a subtype statically matches the first subtype of a given type, then it has
18955 by default the same @code{Value_Size} as the first subtype. This is a
18956 consequence of RM 13.1(14): "if two subtypes statically match,
18957 then their subtype-specific aspects are the same".)
18960 All other subtypes have a @code{Value_Size} corresponding to the minimum
18961 number of bits required to store all values of the subtype. For
18962 dynamic bounds, it is assumed that the value can range down or up
18963 to the corresponding bound of the ancestor
18966 The RM defined attribute @code{Size} corresponds to the
18967 @code{Value_Size} attribute.
18969 The @code{Size} attribute may be defined for a first-named subtype. This sets
18970 the @code{Value_Size} of
18971 the first-named subtype to the given value, and the
18972 @code{Object_Size} of this first-named subtype to the given value padded up
18973 to an appropriate boundary. It is a consequence of the default rules
18974 above that this @code{Object_Size} will apply to all further subtypes. On the
18975 other hand, @code{Value_Size} is affected only for the first subtype, any
18976 dynamic subtypes obtained from it directly, and any statically matching
18977 subtypes. The @code{Value_Size} of any other static subtypes is not affected.
18979 @code{Value_Size} and
18980 @code{Object_Size} may be explicitly set for any subtype using
18981 an attribute definition clause. Note that the use of these attributes
18982 can cause the RM 13.1(14) rule to be violated. If two access types
18983 reference aliased objects whose subtypes have differing @code{Object_Size}
18984 values as a result of explicit attribute definition clauses, then it
18985 is illegal to convert from one access subtype to the other. For a more
18986 complete description of this additional legality rule, see the
18987 description of the @code{Object_Size} attribute.
18989 To get a feel for the difference, consider the following examples (note
18990 that in each case the base is @code{Short_Short_Integer} with a size of 8):
18993 @multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxx}
18996 Type or subtype declaration
19008 @code{type x1 is range 0 .. 5;}
19020 @code{type x2 is range 0 .. 5;}
19021 @code{for x2'size use 12;}
19033 @code{subtype x3 is x2 range 0 .. 3;}
19045 @code{subtype x4 is x2'base range 0 .. 10;}
19057 @code{dynamic : x2'Base range -64 .. +63;}
19065 @code{subtype x5 is x2 range 0 .. dynamic;}
19077 @code{subtype x6 is x2'base range 0 .. dynamic;}
19090 Note: the entries marked '*' are not actually specified by the Ada
19091 Reference Manual, which has nothing to say about size in the dynamic
19092 case. What GNAT does is to allocate sufficient bits to accomodate any
19093 possible dynamic values for the bounds at run-time.
19095 So far, so good, but GNAT has to obey the RM rules, so the question is
19096 under what conditions must the RM @code{Size} be used.
19097 The following is a list
19098 of the occasions on which the RM @code{Size} must be used:
19104 Component size for packed arrays or records
19107 Value of the attribute @code{Size} for a type
19110 Warning about sizes not matching for unchecked conversion
19113 For record types, the @code{Object_Size} is always a multiple of the
19114 alignment of the type (this is true for all types). In some cases the
19115 @code{Value_Size} can be smaller. Consider:
19124 On a typical 32-bit architecture, the X component will occupy four bytes
19125 and the Y component will occupy one byte, for a total of 5 bytes. As a
19126 result @code{R'Value_Size} will be 40 (bits) since this is the minimum size
19127 required to store a value of this type. For example, it is permissible
19128 to have a component of type R in an array whose component size is
19129 specified to be 40 bits.
19131 However, @code{R'Object_Size} will be 64 (bits). The difference is due to
19132 the alignment requirement for objects of the record type. The X
19133 component will require four-byte alignment because that is what type
19134 Integer requires, whereas the Y component, a Character, will only
19135 require 1-byte alignment. Since the alignment required for X is the
19136 greatest of all the components' alignments, that is the alignment
19137 required for the enclosing record type, i.e., 4 bytes or 32 bits. As
19138 indicated above, the actual object size must be rounded up so that it is
19139 a multiple of the alignment value. Therefore, 40 bits rounded up to the
19140 next multiple of 32 yields 64 bits.
19142 For all other types, the @code{Object_Size}
19143 and @code{Value_Size} are the same (and equivalent to the RM attribute @code{Size}).
19144 Only @code{Size} may be specified for such types.
19146 Note that @code{Value_Size} can be used to force biased representation
19147 for a particular subtype. Consider this example:
19150 type R is (A, B, C, D, E, F);
19151 subtype RAB is R range A .. B;
19152 subtype REF is R range E .. F;
19155 By default, @code{RAB}
19156 has a size of 1 (sufficient to accommodate the representation
19157 of @code{A} and @code{B}, 0 and 1), and @code{REF}
19158 has a size of 3 (sufficient to accommodate the representation
19159 of @code{E} and @code{F}, 4 and 5). But if we add the
19160 following @code{Value_Size} attribute definition clause:
19163 for REF'Value_Size use 1;
19166 then biased representation is forced for @code{REF},
19167 and 0 will represent @code{E} and 1 will represent @code{F}.
19168 A warning is issued when a @code{Value_Size} attribute
19169 definition clause forces biased representation. This
19170 warning can be turned off using @code{-gnatw.B}.
19172 @node Component_Size Clauses,Bit_Order Clauses,Value_Size and Object_Size Clauses,Representation Clauses and Pragmas
19173 @anchor{gnat_rm/representation_clauses_and_pragmas id8}@anchor{283}@anchor{gnat_rm/representation_clauses_and_pragmas component-size-clauses}@anchor{284}
19174 @section Component_Size Clauses
19177 @geindex Component_Size Clause
19179 Normally, the value specified in a component size clause must be consistent
19180 with the subtype of the array component with regard to size and alignment.
19181 In other words, the value specified must be at least equal to the size
19182 of this subtype, and must be a multiple of the alignment value.
19184 In addition, component size clauses are allowed which cause the array
19185 to be packed, by specifying a smaller value. A first case is for
19186 component size values in the range 1 through 63. The value specified
19187 must not be smaller than the Size of the subtype. GNAT will accurately
19188 honor all packing requests in this range. For example, if we have:
19191 type r is array (1 .. 8) of Natural;
19192 for r'Component_Size use 31;
19195 then the resulting array has a length of 31 bytes (248 bits = 8 * 31).
19196 Of course access to the components of such an array is considerably
19197 less efficient than if the natural component size of 32 is used.
19198 A second case is when the subtype of the component is a record type
19199 padded because of its default alignment. For example, if we have:
19208 type a is array (1 .. 8) of r;
19209 for a'Component_Size use 72;
19212 then the resulting array has a length of 72 bytes, instead of 96 bytes
19213 if the alignment of the record (4) was obeyed.
19215 Note that there is no point in giving both a component size clause
19216 and a pragma Pack for the same array type. if such duplicate
19217 clauses are given, the pragma Pack will be ignored.
19219 @node Bit_Order Clauses,Effect of Bit_Order on Byte Ordering,Component_Size Clauses,Representation Clauses and Pragmas
19220 @anchor{gnat_rm/representation_clauses_and_pragmas bit-order-clauses}@anchor{285}@anchor{gnat_rm/representation_clauses_and_pragmas id9}@anchor{286}
19221 @section Bit_Order Clauses
19224 @geindex Bit_Order Clause
19226 @geindex bit ordering
19231 For record subtypes, GNAT permits the specification of the @code{Bit_Order}
19232 attribute. The specification may either correspond to the default bit
19233 order for the target, in which case the specification has no effect and
19234 places no additional restrictions, or it may be for the non-standard
19235 setting (that is the opposite of the default).
19237 In the case where the non-standard value is specified, the effect is
19238 to renumber bits within each byte, but the ordering of bytes is not
19239 affected. There are certain
19240 restrictions placed on component clauses as follows:
19246 Components fitting within a single storage unit.
19248 These are unrestricted, and the effect is merely to renumber bits. For
19249 example if we are on a little-endian machine with @code{Low_Order_First}
19250 being the default, then the following two declarations have exactly
19256 B : Integer range 1 .. 120;
19260 A at 0 range 0 .. 0;
19261 B at 0 range 1 .. 7;
19266 B : Integer range 1 .. 120;
19269 for R2'Bit_Order use High_Order_First;
19272 A at 0 range 7 .. 7;
19273 B at 0 range 0 .. 6;
19277 The useful application here is to write the second declaration with the
19278 @code{Bit_Order} attribute definition clause, and know that it will be treated
19279 the same, regardless of whether the target is little-endian or big-endian.
19282 Components occupying an integral number of bytes.
19284 These are components that exactly fit in two or more bytes. Such component
19285 declarations are allowed, but have no effect, since it is important to realize
19286 that the @code{Bit_Order} specification does not affect the ordering of bytes.
19287 In particular, the following attempt at getting an endian-independent integer
19295 for R2'Bit_Order use High_Order_First;
19298 A at 0 range 0 .. 31;
19302 This declaration will result in a little-endian integer on a
19303 little-endian machine, and a big-endian integer on a big-endian machine.
19304 If byte flipping is required for interoperability between big- and
19305 little-endian machines, this must be explicitly programmed. This capability
19306 is not provided by @code{Bit_Order}.
19309 Components that are positioned across byte boundaries.
19311 but do not occupy an integral number of bytes. Given that bytes are not
19312 reordered, such fields would occupy a non-contiguous sequence of bits
19313 in memory, requiring non-trivial code to reassemble. They are for this
19314 reason not permitted, and any component clause specifying such a layout
19315 will be flagged as illegal by GNAT.
19318 Since the misconception that Bit_Order automatically deals with all
19319 endian-related incompatibilities is a common one, the specification of
19320 a component field that is an integral number of bytes will always
19321 generate a warning. This warning may be suppressed using @code{pragma Warnings (Off)}
19322 if desired. The following section contains additional
19323 details regarding the issue of byte ordering.
19325 @node Effect of Bit_Order on Byte Ordering,Pragma Pack for Arrays,Bit_Order Clauses,Representation Clauses and Pragmas
19326 @anchor{gnat_rm/representation_clauses_and_pragmas id10}@anchor{287}@anchor{gnat_rm/representation_clauses_and_pragmas effect-of-bit-order-on-byte-ordering}@anchor{288}
19327 @section Effect of Bit_Order on Byte Ordering
19330 @geindex byte ordering
19335 In this section we will review the effect of the @code{Bit_Order} attribute
19336 definition clause on byte ordering. Briefly, it has no effect at all, but
19337 a detailed example will be helpful. Before giving this
19338 example, let us review the precise
19339 definition of the effect of defining @code{Bit_Order}. The effect of a
19340 non-standard bit order is described in section 13.5.3 of the Ada
19345 "2 A bit ordering is a method of interpreting the meaning of
19346 the storage place attributes."
19349 To understand the precise definition of storage place attributes in
19350 this context, we visit section 13.5.1 of the manual:
19354 "13 A record_representation_clause (without the mod_clause)
19355 specifies the layout. The storage place attributes (see 13.5.2)
19356 are taken from the values of the position, first_bit, and last_bit
19357 expressions after normalizing those values so that first_bit is
19358 less than Storage_Unit."
19361 The critical point here is that storage places are taken from
19362 the values after normalization, not before. So the @code{Bit_Order}
19363 interpretation applies to normalized values. The interpretation
19364 is described in the later part of the 13.5.3 paragraph:
19368 "2 A bit ordering is a method of interpreting the meaning of
19369 the storage place attributes. High_Order_First (known in the
19370 vernacular as 'big endian') means that the first bit of a
19371 storage element (bit 0) is the most significant bit (interpreting
19372 the sequence of bits that represent a component as an unsigned
19373 integer value). Low_Order_First (known in the vernacular as
19374 'little endian') means the opposite: the first bit is the
19375 least significant."
19378 Note that the numbering is with respect to the bits of a storage
19379 unit. In other words, the specification affects only the numbering
19380 of bits within a single storage unit.
19382 We can make the effect clearer by giving an example.
19384 Suppose that we have an external device which presents two bytes, the first
19385 byte presented, which is the first (low addressed byte) of the two byte
19386 record is called Master, and the second byte is called Slave.
19388 The left most (most significant bit is called Control for each byte, and
19389 the remaining 7 bits are called V1, V2, ... V7, where V7 is the rightmost
19390 (least significant) bit.
19392 On a big-endian machine, we can write the following representation clause
19395 type Data is record
19396 Master_Control : Bit;
19404 Slave_Control : Bit;
19414 for Data use record
19415 Master_Control at 0 range 0 .. 0;
19416 Master_V1 at 0 range 1 .. 1;
19417 Master_V2 at 0 range 2 .. 2;
19418 Master_V3 at 0 range 3 .. 3;
19419 Master_V4 at 0 range 4 .. 4;
19420 Master_V5 at 0 range 5 .. 5;
19421 Master_V6 at 0 range 6 .. 6;
19422 Master_V7 at 0 range 7 .. 7;
19423 Slave_Control at 1 range 0 .. 0;
19424 Slave_V1 at 1 range 1 .. 1;
19425 Slave_V2 at 1 range 2 .. 2;
19426 Slave_V3 at 1 range 3 .. 3;
19427 Slave_V4 at 1 range 4 .. 4;
19428 Slave_V5 at 1 range 5 .. 5;
19429 Slave_V6 at 1 range 6 .. 6;
19430 Slave_V7 at 1 range 7 .. 7;
19434 Now if we move this to a little endian machine, then the bit ordering within
19435 the byte is backwards, so we have to rewrite the record rep clause as:
19438 for Data use record
19439 Master_Control at 0 range 7 .. 7;
19440 Master_V1 at 0 range 6 .. 6;
19441 Master_V2 at 0 range 5 .. 5;
19442 Master_V3 at 0 range 4 .. 4;
19443 Master_V4 at 0 range 3 .. 3;
19444 Master_V5 at 0 range 2 .. 2;
19445 Master_V6 at 0 range 1 .. 1;
19446 Master_V7 at 0 range 0 .. 0;
19447 Slave_Control at 1 range 7 .. 7;
19448 Slave_V1 at 1 range 6 .. 6;
19449 Slave_V2 at 1 range 5 .. 5;
19450 Slave_V3 at 1 range 4 .. 4;
19451 Slave_V4 at 1 range 3 .. 3;
19452 Slave_V5 at 1 range 2 .. 2;
19453 Slave_V6 at 1 range 1 .. 1;
19454 Slave_V7 at 1 range 0 .. 0;
19458 It is a nuisance to have to rewrite the clause, especially if
19459 the code has to be maintained on both machines. However,
19460 this is a case that we can handle with the
19461 @code{Bit_Order} attribute if it is implemented.
19462 Note that the implementation is not required on byte addressed
19463 machines, but it is indeed implemented in GNAT.
19464 This means that we can simply use the
19465 first record clause, together with the declaration
19468 for Data'Bit_Order use High_Order_First;
19471 and the effect is what is desired, namely the layout is exactly the same,
19472 independent of whether the code is compiled on a big-endian or little-endian
19475 The important point to understand is that byte ordering is not affected.
19476 A @code{Bit_Order} attribute definition never affects which byte a field
19477 ends up in, only where it ends up in that byte.
19478 To make this clear, let us rewrite the record rep clause of the previous
19482 for Data'Bit_Order use High_Order_First;
19483 for Data use record
19484 Master_Control at 0 range 0 .. 0;
19485 Master_V1 at 0 range 1 .. 1;
19486 Master_V2 at 0 range 2 .. 2;
19487 Master_V3 at 0 range 3 .. 3;
19488 Master_V4 at 0 range 4 .. 4;
19489 Master_V5 at 0 range 5 .. 5;
19490 Master_V6 at 0 range 6 .. 6;
19491 Master_V7 at 0 range 7 .. 7;
19492 Slave_Control at 0 range 8 .. 8;
19493 Slave_V1 at 0 range 9 .. 9;
19494 Slave_V2 at 0 range 10 .. 10;
19495 Slave_V3 at 0 range 11 .. 11;
19496 Slave_V4 at 0 range 12 .. 12;
19497 Slave_V5 at 0 range 13 .. 13;
19498 Slave_V6 at 0 range 14 .. 14;
19499 Slave_V7 at 0 range 15 .. 15;
19503 This is exactly equivalent to saying (a repeat of the first example):
19506 for Data'Bit_Order use High_Order_First;
19507 for Data use record
19508 Master_Control at 0 range 0 .. 0;
19509 Master_V1 at 0 range 1 .. 1;
19510 Master_V2 at 0 range 2 .. 2;
19511 Master_V3 at 0 range 3 .. 3;
19512 Master_V4 at 0 range 4 .. 4;
19513 Master_V5 at 0 range 5 .. 5;
19514 Master_V6 at 0 range 6 .. 6;
19515 Master_V7 at 0 range 7 .. 7;
19516 Slave_Control at 1 range 0 .. 0;
19517 Slave_V1 at 1 range 1 .. 1;
19518 Slave_V2 at 1 range 2 .. 2;
19519 Slave_V3 at 1 range 3 .. 3;
19520 Slave_V4 at 1 range 4 .. 4;
19521 Slave_V5 at 1 range 5 .. 5;
19522 Slave_V6 at 1 range 6 .. 6;
19523 Slave_V7 at 1 range 7 .. 7;
19527 Why are they equivalent? Well take a specific field, the @code{Slave_V2}
19528 field. The storage place attributes are obtained by normalizing the
19529 values given so that the @code{First_Bit} value is less than 8. After
19530 normalizing the values (0,10,10) we get (1,2,2) which is exactly what
19531 we specified in the other case.
19533 Now one might expect that the @code{Bit_Order} attribute might affect
19534 bit numbering within the entire record component (two bytes in this
19535 case, thus affecting which byte fields end up in), but that is not
19536 the way this feature is defined, it only affects numbering of bits,
19537 not which byte they end up in.
19539 Consequently it never makes sense to specify a starting bit number
19540 greater than 7 (for a byte addressable field) if an attribute
19541 definition for @code{Bit_Order} has been given, and indeed it
19542 may be actively confusing to specify such a value, so the compiler
19543 generates a warning for such usage.
19545 If you do need to control byte ordering then appropriate conditional
19546 values must be used. If in our example, the slave byte came first on
19547 some machines we might write:
19550 Master_Byte_First constant Boolean := ...;
19552 Master_Byte : constant Natural :=
19553 1 - Boolean'Pos (Master_Byte_First);
19554 Slave_Byte : constant Natural :=
19555 Boolean'Pos (Master_Byte_First);
19557 for Data'Bit_Order use High_Order_First;
19558 for Data use record
19559 Master_Control at Master_Byte range 0 .. 0;
19560 Master_V1 at Master_Byte range 1 .. 1;
19561 Master_V2 at Master_Byte range 2 .. 2;
19562 Master_V3 at Master_Byte range 3 .. 3;
19563 Master_V4 at Master_Byte range 4 .. 4;
19564 Master_V5 at Master_Byte range 5 .. 5;
19565 Master_V6 at Master_Byte range 6 .. 6;
19566 Master_V7 at Master_Byte range 7 .. 7;
19567 Slave_Control at Slave_Byte range 0 .. 0;
19568 Slave_V1 at Slave_Byte range 1 .. 1;
19569 Slave_V2 at Slave_Byte range 2 .. 2;
19570 Slave_V3 at Slave_Byte range 3 .. 3;
19571 Slave_V4 at Slave_Byte range 4 .. 4;
19572 Slave_V5 at Slave_Byte range 5 .. 5;
19573 Slave_V6 at Slave_Byte range 6 .. 6;
19574 Slave_V7 at Slave_Byte range 7 .. 7;
19578 Now to switch between machines, all that is necessary is
19579 to set the boolean constant @code{Master_Byte_First} in
19580 an appropriate manner.
19582 @node Pragma Pack for Arrays,Pragma Pack for Records,Effect of Bit_Order on Byte Ordering,Representation Clauses and Pragmas
19583 @anchor{gnat_rm/representation_clauses_and_pragmas pragma-pack-for-arrays}@anchor{289}@anchor{gnat_rm/representation_clauses_and_pragmas id11}@anchor{28a}
19584 @section Pragma Pack for Arrays
19587 @geindex Pragma Pack (for arrays)
19589 Pragma @code{Pack} applied to an array has an effect that depends upon whether the
19590 component type is @emph{packable}. For a component type to be @emph{packable}, it must
19591 be one of the following cases:
19597 Any elementary type.
19600 Any small packed array type with a static size.
19603 Any small simple record type with a static size.
19606 For all these cases, if the component subtype size is in the range
19607 1 through 64, then the effect of the pragma @code{Pack} is exactly as though a
19608 component size were specified giving the component subtype size.
19610 All other types are non-packable, they occupy an integral number of storage
19611 units and the only effect of pragma Pack is to remove alignment gaps.
19613 For example if we have:
19616 type r is range 0 .. 17;
19618 type ar is array (1 .. 8) of r;
19622 Then the component size of @code{ar} will be set to 5 (i.e., to @code{r'size},
19623 and the size of the array @code{ar} will be exactly 40 bits).
19625 Note that in some cases this rather fierce approach to packing can produce
19626 unexpected effects. For example, in Ada 95 and Ada 2005,
19627 subtype @code{Natural} typically has a size of 31, meaning that if you
19628 pack an array of @code{Natural}, you get 31-bit
19629 close packing, which saves a few bits, but results in far less efficient
19630 access. Since many other Ada compilers will ignore such a packing request,
19631 GNAT will generate a warning on some uses of pragma @code{Pack} that it guesses
19632 might not be what is intended. You can easily remove this warning by
19633 using an explicit @code{Component_Size} setting instead, which never generates
19634 a warning, since the intention of the programmer is clear in this case.
19636 GNAT treats packed arrays in one of two ways. If the size of the array is
19637 known at compile time and is less than 64 bits, then internally the array
19638 is represented as a single modular type, of exactly the appropriate number
19639 of bits. If the length is greater than 63 bits, or is not known at compile
19640 time, then the packed array is represented as an array of bytes, and the
19641 length is always a multiple of 8 bits.
19643 Note that to represent a packed array as a modular type, the alignment must
19644 be suitable for the modular type involved. For example, on typical machines
19645 a 32-bit packed array will be represented by a 32-bit modular integer with
19646 an alignment of four bytes. If you explicitly override the default alignment
19647 with an alignment clause that is too small, the modular representation
19648 cannot be used. For example, consider the following set of declarations:
19651 type R is range 1 .. 3;
19652 type S is array (1 .. 31) of R;
19653 for S'Component_Size use 2;
19655 for S'Alignment use 1;
19658 If the alignment clause were not present, then a 62-bit modular
19659 representation would be chosen (typically with an alignment of 4 or 8
19660 bytes depending on the target). But the default alignment is overridden
19661 with the explicit alignment clause. This means that the modular
19662 representation cannot be used, and instead the array of bytes
19663 representation must be used, meaning that the length must be a multiple
19664 of 8. Thus the above set of declarations will result in a diagnostic
19665 rejecting the size clause and noting that the minimum size allowed is 64.
19667 @geindex Pragma Pack (for type Natural)
19669 @geindex Pragma Pack warning
19671 One special case that is worth noting occurs when the base type of the
19672 component size is 8/16/32 and the subtype is one bit less. Notably this
19673 occurs with subtype @code{Natural}. Consider:
19676 type Arr is array (1 .. 32) of Natural;
19680 In all commonly used Ada 83 compilers, this pragma Pack would be ignored,
19681 since typically @code{Natural'Size} is 32 in Ada 83, and in any case most
19682 Ada 83 compilers did not attempt 31 bit packing.
19684 In Ada 95 and Ada 2005, @code{Natural'Size} is required to be 31. Furthermore,
19685 GNAT really does pack 31-bit subtype to 31 bits. This may result in a
19686 substantial unintended performance penalty when porting legacy Ada 83 code.
19687 To help prevent this, GNAT generates a warning in such cases. If you really
19688 want 31 bit packing in a case like this, you can set the component size
19692 type Arr is array (1 .. 32) of Natural;
19693 for Arr'Component_Size use 31;
19696 Here 31-bit packing is achieved as required, and no warning is generated,
19697 since in this case the programmer intention is clear.
19699 @node Pragma Pack for Records,Record Representation Clauses,Pragma Pack for Arrays,Representation Clauses and Pragmas
19700 @anchor{gnat_rm/representation_clauses_and_pragmas pragma-pack-for-records}@anchor{28b}@anchor{gnat_rm/representation_clauses_and_pragmas id12}@anchor{28c}
19701 @section Pragma Pack for Records
19704 @geindex Pragma Pack (for records)
19706 Pragma @code{Pack} applied to a record will pack the components to reduce
19707 wasted space from alignment gaps and by reducing the amount of space
19708 taken by components. We distinguish between @emph{packable} components and
19709 @emph{non-packable} components.
19710 Components of the following types are considered packable:
19716 Components of an elementary type are packable unless they are aliased,
19717 independent, or of an atomic type.
19720 Small packed arrays, where the size is statically known, are represented
19721 internally as modular integers, and so they are also packable.
19724 Small simple records, where the size is statically known, are also packable.
19727 For all these cases, if the @code{'Size} value is in the range 1 through 64, the
19728 components occupy the exact number of bits corresponding to this value
19729 and are packed with no padding bits, i.e. they can start on an arbitrary
19732 All other types are non-packable, they occupy an integral number of storage
19733 units and the only effect of pragma @code{Pack} is to remove alignment gaps.
19735 For example, consider the record
19738 type Rb1 is array (1 .. 13) of Boolean;
19741 type Rb2 is array (1 .. 65) of Boolean;
19744 type AF is new Float with Atomic;
19757 The representation for the record @code{X2} is as follows:
19760 for X2'Size use 224;
19762 L1 at 0 range 0 .. 0;
19763 L2 at 0 range 1 .. 64;
19764 L3 at 12 range 0 .. 31;
19765 L4 at 16 range 0 .. 0;
19766 L5 at 16 range 1 .. 13;
19767 L6 at 18 range 0 .. 71;
19771 Studying this example, we see that the packable fields @code{L1}
19773 of length equal to their sizes, and placed at specific bit boundaries (and
19774 not byte boundaries) to
19775 eliminate padding. But @code{L3} is of a non-packable float type (because
19776 it is aliased), so it is on the next appropriate alignment boundary.
19778 The next two fields are fully packable, so @code{L4} and @code{L5} are
19779 minimally packed with no gaps. However, type @code{Rb2} is a packed
19780 array that is longer than 64 bits, so it is itself non-packable. Thus
19781 the @code{L6} field is aligned to the next byte boundary, and takes an
19782 integral number of bytes, i.e., 72 bits.
19784 @node Record Representation Clauses,Handling of Records with Holes,Pragma Pack for Records,Representation Clauses and Pragmas
19785 @anchor{gnat_rm/representation_clauses_and_pragmas id13}@anchor{28d}@anchor{gnat_rm/representation_clauses_and_pragmas record-representation-clauses}@anchor{28e}
19786 @section Record Representation Clauses
19789 @geindex Record Representation Clause
19791 Record representation clauses may be given for all record types, including
19792 types obtained by record extension. Component clauses are allowed for any
19793 static component. The restrictions on component clauses depend on the type
19796 @geindex Component Clause
19798 For all components of an elementary type, the only restriction on component
19799 clauses is that the size must be at least the @code{'Size} value of the type
19800 (actually the Value_Size). There are no restrictions due to alignment,
19801 and such components may freely cross storage boundaries.
19803 Packed arrays with a size up to and including 64 bits are represented
19804 internally using a modular type with the appropriate number of bits, and
19805 thus the same lack of restriction applies. For example, if you declare:
19808 type R is array (1 .. 49) of Boolean;
19813 then a component clause for a component of type @code{R} may start on any
19814 specified bit boundary, and may specify a value of 49 bits or greater.
19816 For packed bit arrays that are longer than 64 bits, there are two
19817 cases. If the component size is a power of 2 (1,2,4,8,16,32 bits),
19818 including the important case of single bits or boolean values, then
19819 there are no limitations on placement of such components, and they
19820 may start and end at arbitrary bit boundaries.
19822 If the component size is not a power of 2 (e.g., 3 or 5), then
19823 an array of this type longer than 64 bits must always be placed on
19824 on a storage unit (byte) boundary and occupy an integral number
19825 of storage units (bytes). Any component clause that does not
19826 meet this requirement will be rejected.
19828 Any aliased component, or component of an aliased type, must
19829 have its normal alignment and size. A component clause that
19830 does not meet this requirement will be rejected.
19832 The tag field of a tagged type always occupies an address sized field at
19833 the start of the record. No component clause may attempt to overlay this
19834 tag. When a tagged type appears as a component, the tag field must have
19837 In the case of a record extension @code{T1}, of a type @code{T}, no component clause applied
19838 to the type @code{T1} can specify a storage location that would overlap the first
19839 @code{T'Size} bytes of the record.
19841 For all other component types, including non-bit-packed arrays,
19842 the component can be placed at an arbitrary bit boundary,
19843 so for example, the following is permitted:
19846 type R is array (1 .. 10) of Boolean;
19855 G at 0 range 0 .. 0;
19856 H at 0 range 1 .. 1;
19857 L at 0 range 2 .. 81;
19858 R at 0 range 82 .. 161;
19862 @node Handling of Records with Holes,Enumeration Clauses,Record Representation Clauses,Representation Clauses and Pragmas
19863 @anchor{gnat_rm/representation_clauses_and_pragmas handling-of-records-with-holes}@anchor{28f}@anchor{gnat_rm/representation_clauses_and_pragmas id14}@anchor{290}
19864 @section Handling of Records with Holes
19867 @geindex Handling of Records with Holes
19869 As a result of alignment considerations, records may contain "holes"
19871 which do not correspond to the data bits of any of the components.
19872 Record representation clauses can also result in holes in records.
19874 GNAT does not attempt to clear these holes, so in record objects,
19875 they should be considered to hold undefined rubbish. The generated
19876 equality routine just tests components so does not access these
19877 undefined bits, and assignment and copy operations may or may not
19878 preserve the contents of these holes (for assignments, the holes
19879 in the target will in practice contain either the bits that are
19880 present in the holes in the source, or the bits that were present
19881 in the target before the assignment).
19883 If it is necessary to ensure that holes in records have all zero
19884 bits, then record objects for which this initialization is desired
19885 should be explicitly set to all zero values using Unchecked_Conversion
19886 or address overlays. For example
19889 type HRec is record
19895 On typical machines, integers need to be aligned on a four-byte
19896 boundary, resulting in three bytes of undefined rubbish following
19897 the 8-bit field for C. To ensure that the hole in a variable of
19898 type HRec is set to all zero bits,
19899 you could for example do:
19902 type Base is record
19903 Dummy1, Dummy2 : Integer := 0;
19908 for RealVar'Address use BaseVar'Address;
19911 Now the 8-bytes of the value of RealVar start out containing all zero
19912 bits. A safer approach is to just define dummy fields, avoiding the
19916 type HRec is record
19918 Dummy1 : Short_Short_Integer := 0;
19919 Dummy2 : Short_Short_Integer := 0;
19920 Dummy3 : Short_Short_Integer := 0;
19925 And to make absolutely sure that the intent of this is followed, you
19926 can use representation clauses:
19929 for Hrec use record
19930 C at 0 range 0 .. 7;
19931 Dummy1 at 1 range 0 .. 7;
19932 Dummy2 at 2 range 0 .. 7;
19933 Dummy3 at 3 range 0 .. 7;
19934 I at 4 range 0 .. 31;
19936 for Hrec'Size use 64;
19939 @node Enumeration Clauses,Address Clauses,Handling of Records with Holes,Representation Clauses and Pragmas
19940 @anchor{gnat_rm/representation_clauses_and_pragmas enumeration-clauses}@anchor{291}@anchor{gnat_rm/representation_clauses_and_pragmas id15}@anchor{292}
19941 @section Enumeration Clauses
19944 The only restriction on enumeration clauses is that the range of values
19945 must be representable. For the signed case, if one or more of the
19946 representation values are negative, all values must be in the range:
19949 System.Min_Int .. System.Max_Int
19952 For the unsigned case, where all values are nonnegative, the values must
19956 0 .. System.Max_Binary_Modulus;
19959 A @emph{confirming} representation clause is one in which the values range
19960 from 0 in sequence, i.e., a clause that confirms the default representation
19961 for an enumeration type.
19962 Such a confirming representation
19963 is permitted by these rules, and is specially recognized by the compiler so
19964 that no extra overhead results from the use of such a clause.
19966 If an array has an index type which is an enumeration type to which an
19967 enumeration clause has been applied, then the array is stored in a compact
19968 manner. Consider the declarations:
19971 type r is (A, B, C);
19972 for r use (A => 1, B => 5, C => 10);
19973 type t is array (r) of Character;
19976 The array type t corresponds to a vector with exactly three elements and
19977 has a default size equal to @code{3*Character'Size}. This ensures efficient
19978 use of space, but means that accesses to elements of the array will incur
19979 the overhead of converting representation values to the corresponding
19980 positional values, (i.e., the value delivered by the @code{Pos} attribute).
19982 @node Address Clauses,Use of Address Clauses for Memory-Mapped I/O,Enumeration Clauses,Representation Clauses and Pragmas
19983 @anchor{gnat_rm/representation_clauses_and_pragmas id16}@anchor{293}@anchor{gnat_rm/representation_clauses_and_pragmas address-clauses}@anchor{294}
19984 @section Address Clauses
19987 @geindex Address Clause
19989 The reference manual allows a general restriction on representation clauses,
19990 as found in RM 13.1(22):
19994 "An implementation need not support representation
19995 items containing nonstatic expressions, except that
19996 an implementation should support a representation item
19997 for a given entity if each nonstatic expression in the
19998 representation item is a name that statically denotes
19999 a constant declared before the entity."
20002 In practice this is applicable only to address clauses, since this is the
20003 only case in which a nonstatic expression is permitted by the syntax. As
20004 the AARM notes in sections 13.1 (22.a-22.h):
20008 22.a Reason: This is to avoid the following sort of thing:
20010 22.b X : Integer := F(...);
20011 Y : Address := G(...);
20012 for X'Address use Y;
20014 22.c In the above, we have to evaluate the
20015 initialization expression for X before we
20016 know where to put the result. This seems
20017 like an unreasonable implementation burden.
20019 22.d The above code should instead be written
20022 22.e Y : constant Address := G(...);
20023 X : Integer := F(...);
20024 for X'Address use Y;
20026 22.f This allows the expression 'Y' to be safely
20027 evaluated before X is created.
20029 22.g The constant could be a formal parameter of mode in.
20031 22.h An implementation can support other nonstatic
20032 expressions if it wants to. Expressions of type
20033 Address are hardly ever static, but their value
20034 might be known at compile time anyway in many
20038 GNAT does indeed permit many additional cases of nonstatic expressions. In
20039 particular, if the type involved is elementary there are no restrictions
20040 (since in this case, holding a temporary copy of the initialization value,
20041 if one is present, is inexpensive). In addition, if there is no implicit or
20042 explicit initialization, then there are no restrictions. GNAT will reject
20043 only the case where all three of these conditions hold:
20049 The type of the item is non-elementary (e.g., a record or array).
20052 There is explicit or implicit initialization required for the object.
20053 Note that access values are always implicitly initialized.
20056 The address value is nonstatic. Here GNAT is more permissive than the
20057 RM, and allows the address value to be the address of a previously declared
20058 stand-alone variable, as long as it does not itself have an address clause.
20061 Anchor : Some_Initialized_Type;
20062 Overlay : Some_Initialized_Type;
20063 for Overlay'Address use Anchor'Address;
20066 However, the prefix of the address clause cannot be an array component, or
20067 a component of a discriminated record.
20070 As noted above in section 22.h, address values are typically nonstatic. In
20071 particular the To_Address function, even if applied to a literal value, is
20072 a nonstatic function call. To avoid this minor annoyance, GNAT provides
20073 the implementation defined attribute 'To_Address. The following two
20074 expressions have identical values:
20078 @geindex To_Address
20081 To_Address (16#1234_0000#)
20082 System'To_Address (16#1234_0000#);
20085 except that the second form is considered to be a static expression, and
20086 thus when used as an address clause value is always permitted.
20088 Additionally, GNAT treats as static an address clause that is an
20089 unchecked_conversion of a static integer value. This simplifies the porting
20090 of legacy code, and provides a portable equivalent to the GNAT attribute
20093 Another issue with address clauses is the interaction with alignment
20094 requirements. When an address clause is given for an object, the address
20095 value must be consistent with the alignment of the object (which is usually
20096 the same as the alignment of the type of the object). If an address clause
20097 is given that specifies an inappropriately aligned address value, then the
20098 program execution is erroneous.
20100 Since this source of erroneous behavior can have unfortunate effects on
20101 machines with strict alignment requirements, GNAT
20102 checks (at compile time if possible, generating a warning, or at execution
20103 time with a run-time check) that the alignment is appropriate. If the
20104 run-time check fails, then @code{Program_Error} is raised. This run-time
20105 check is suppressed if range checks are suppressed, or if the special GNAT
20106 check Alignment_Check is suppressed, or if
20107 @code{pragma Restrictions (No_Elaboration_Code)} is in effect. It is also
20108 suppressed by default on non-strict alignment machines (such as the x86).
20110 Finally, GNAT does not permit overlaying of objects of class-wide types. In
20111 most cases, the compiler can detect an attempt at such overlays and will
20112 generate a warning at compile time and a Program_Error exception at run time.
20116 An address clause cannot be given for an exported object. More
20117 understandably the real restriction is that objects with an address
20118 clause cannot be exported. This is because such variables are not
20119 defined by the Ada program, so there is no external object to export.
20123 It is permissible to give an address clause and a pragma Import for the
20124 same object. In this case, the variable is not really defined by the
20125 Ada program, so there is no external symbol to be linked. The link name
20126 and the external name are ignored in this case. The reason that we allow this
20127 combination is that it provides a useful idiom to avoid unwanted
20128 initializations on objects with address clauses.
20130 When an address clause is given for an object that has implicit or
20131 explicit initialization, then by default initialization takes place. This
20132 means that the effect of the object declaration is to overwrite the
20133 memory at the specified address. This is almost always not what the
20134 programmer wants, so GNAT will output a warning:
20144 for Ext'Address use System'To_Address (16#1234_1234#);
20146 >>> warning: implicit initialization of "Ext" may
20147 modify overlaid storage
20148 >>> warning: use pragma Import for "Ext" to suppress
20149 initialization (RM B(24))
20154 As indicated by the warning message, the solution is to use a (dummy) pragma
20155 Import to suppress this initialization. The pragma tell the compiler that the
20156 object is declared and initialized elsewhere. The following package compiles
20157 without warnings (and the initialization is suppressed):
20167 for Ext'Address use System'To_Address (16#1234_1234#);
20168 pragma Import (Ada, Ext);
20172 A final issue with address clauses involves their use for overlaying
20173 variables, as in the following example:
20175 @geindex Overlaying of objects
20180 for B'Address use A'Address;
20183 or alternatively, using the form recommended by the RM:
20187 Addr : constant Address := A'Address;
20189 for B'Address use Addr;
20192 In both of these cases, @code{A} and @code{B} become aliased to one another
20193 via the address clause. This use of address clauses to overlay
20194 variables, achieving an effect similar to unchecked conversion
20195 was erroneous in Ada 83, but in Ada 95 and Ada 2005
20196 the effect is implementation defined. Furthermore, the
20197 Ada RM specifically recommends that in a situation
20198 like this, @code{B} should be subject to the following
20199 implementation advice (RM 13.3(19)):
20203 "19 If the Address of an object is specified, or it is imported
20204 or exported, then the implementation should not perform
20205 optimizations based on assumptions of no aliases."
20208 GNAT follows this recommendation, and goes further by also applying
20209 this recommendation to the overlaid variable (@code{A} in the above example)
20210 in this case. This means that the overlay works "as expected", in that
20211 a modification to one of the variables will affect the value of the other.
20213 More generally, GNAT interprets this recommendation conservatively for
20214 address clauses: in the cases other than overlays, it considers that the
20215 object is effectively subject to pragma @code{Volatile} and implements the
20216 associated semantics.
20218 Note that when address clause overlays are used in this way, there is an
20219 issue of unintentional initialization, as shown by this example:
20222 package Overwrite_Record is
20224 A : Character := 'C';
20225 B : Character := 'A';
20227 X : Short_Integer := 3;
20229 for Y'Address use X'Address;
20231 >>> warning: default initialization of "Y" may
20232 modify "X", use pragma Import for "Y" to
20233 suppress initialization (RM B.1(24))
20235 end Overwrite_Record;
20238 Here the default initialization of @code{Y} will clobber the value
20239 of @code{X}, which justifies the warning. The warning notes that
20240 this effect can be eliminated by adding a @code{pragma Import}
20241 which suppresses the initialization:
20244 package Overwrite_Record is
20246 A : Character := 'C';
20247 B : Character := 'A';
20249 X : Short_Integer := 3;
20251 for Y'Address use X'Address;
20252 pragma Import (Ada, Y);
20253 end Overwrite_Record;
20256 Note that the use of @code{pragma Initialize_Scalars} may cause variables to
20257 be initialized when they would not otherwise have been in the absence
20258 of the use of this pragma. This may cause an overlay to have this
20259 unintended clobbering effect. The compiler avoids this for scalar
20260 types, but not for composite objects (where in general the effect
20261 of @code{Initialize_Scalars} is part of the initialization routine
20262 for the composite object:
20265 pragma Initialize_Scalars;
20266 with Ada.Text_IO; use Ada.Text_IO;
20267 procedure Overwrite_Array is
20268 type Arr is array (1 .. 5) of Integer;
20269 X : Arr := (others => 1);
20271 for A'Address use X'Address;
20273 >>> warning: default initialization of "A" may
20274 modify "X", use pragma Import for "A" to
20275 suppress initialization (RM B.1(24))
20278 if X /= Arr'(others => 1) then
20279 Put_Line ("X was clobbered");
20281 Put_Line ("X was not clobbered");
20283 end Overwrite_Array;
20286 The above program generates the warning as shown, and at execution
20287 time, prints @code{X was clobbered}. If the @code{pragma Import} is
20288 added as suggested:
20291 pragma Initialize_Scalars;
20292 with Ada.Text_IO; use Ada.Text_IO;
20293 procedure Overwrite_Array is
20294 type Arr is array (1 .. 5) of Integer;
20295 X : Arr := (others => 1);
20297 for A'Address use X'Address;
20298 pragma Import (Ada, A);
20300 if X /= Arr'(others => 1) then
20301 Put_Line ("X was clobbered");
20303 Put_Line ("X was not clobbered");
20305 end Overwrite_Array;
20308 then the program compiles without the warning and when run will generate
20309 the output @code{X was not clobbered}.
20311 @node Use of Address Clauses for Memory-Mapped I/O,Effect of Convention on Representation,Address Clauses,Representation Clauses and Pragmas
20312 @anchor{gnat_rm/representation_clauses_and_pragmas id17}@anchor{295}@anchor{gnat_rm/representation_clauses_and_pragmas use-of-address-clauses-for-memory-mapped-i-o}@anchor{296}
20313 @section Use of Address Clauses for Memory-Mapped I/O
20316 @geindex Memory-mapped I/O
20318 A common pattern is to use an address clause to map an atomic variable to
20319 a location in memory that corresponds to a memory-mapped I/O operation or
20320 operations, for example:
20323 type Mem_Word is record
20326 pragma Atomic (Mem_Word);
20327 for Mem_Word_Size use 32;
20330 for Mem'Address use some-address;
20337 For a full access (reference or modification) of the variable (Mem) in this
20338 case, as in the above examples, GNAT guarantees that the entire atomic word
20339 will be accessed, in accordance with the RM C.6(15) clause.
20341 A problem arises with a component access such as:
20347 Note that the component A is not declared as atomic. This means that it is
20348 not clear what this assignment means. It could correspond to full word read
20349 and write as given in the first example, or on architectures that supported
20350 such an operation it might be a single byte store instruction. The RM does
20351 not have anything to say in this situation, and GNAT does not make any
20352 guarantee. The code generated may vary from target to target. GNAT will issue
20353 a warning in such a case:
20358 >>> warning: access to non-atomic component of atomic array,
20359 may cause unexpected accesses to atomic object
20362 It is best to be explicit in this situation, by either declaring the
20363 components to be atomic if you want the byte store, or explicitly writing
20364 the full word access sequence if that is what the hardware requires.
20365 Alternatively, if the full word access sequence is required, GNAT also
20366 provides the pragma @code{Volatile_Full_Access} which can be used in lieu of
20367 pragma @code{Atomic} and will give the additional guarantee.
20369 @node Effect of Convention on Representation,Conventions and Anonymous Access Types,Use of Address Clauses for Memory-Mapped I/O,Representation Clauses and Pragmas
20370 @anchor{gnat_rm/representation_clauses_and_pragmas id18}@anchor{297}@anchor{gnat_rm/representation_clauses_and_pragmas effect-of-convention-on-representation}@anchor{298}
20371 @section Effect of Convention on Representation
20374 @geindex Convention
20375 @geindex effect on representation
20377 Normally the specification of a foreign language convention for a type or
20378 an object has no effect on the chosen representation. In particular, the
20379 representation chosen for data in GNAT generally meets the standard system
20380 conventions, and for example records are laid out in a manner that is
20381 consistent with C. This means that specifying convention C (for example)
20384 There are four exceptions to this general rule:
20390 @emph{Convention Fortran and array subtypes}.
20392 If pragma Convention Fortran is specified for an array subtype, then in
20393 accordance with the implementation advice in section 3.6.2(11) of the
20394 Ada Reference Manual, the array will be stored in a Fortran-compatible
20395 column-major manner, instead of the normal default row-major order.
20398 @emph{Convention C and enumeration types}
20400 GNAT normally stores enumeration types in 8, 16, or 32 bits as required
20401 to accommodate all values of the type. For example, for the enumeration
20405 type Color is (Red, Green, Blue);
20408 8 bits is sufficient to store all values of the type, so by default, objects
20409 of type @code{Color} will be represented using 8 bits. However, normal C
20410 convention is to use 32 bits for all enum values in C, since enum values
20411 are essentially of type int. If pragma @code{Convention C} is specified for an
20412 Ada enumeration type, then the size is modified as necessary (usually to
20413 32 bits) to be consistent with the C convention for enum values.
20415 Note that this treatment applies only to types. If Convention C is given for
20416 an enumeration object, where the enumeration type is not Convention C, then
20417 Object_Size bits are allocated. For example, for a normal enumeration type,
20418 with less than 256 elements, only 8 bits will be allocated for the object.
20419 Since this may be a surprise in terms of what C expects, GNAT will issue a
20420 warning in this situation. The warning can be suppressed by giving an explicit
20421 size clause specifying the desired size.
20424 @emph{Convention C/Fortran and Boolean types}
20426 In C, the usual convention for boolean values, that is values used for
20427 conditions, is that zero represents false, and nonzero values represent
20428 true. In Ada, the normal convention is that two specific values, typically
20429 0/1, are used to represent false/true respectively.
20431 Fortran has a similar convention for @code{LOGICAL} values (any nonzero
20432 value represents true).
20434 To accommodate the Fortran and C conventions, if a pragma Convention specifies
20435 C or Fortran convention for a derived Boolean, as in the following example:
20438 type C_Switch is new Boolean;
20439 pragma Convention (C, C_Switch);
20442 then the GNAT generated code will treat any nonzero value as true. For truth
20443 values generated by GNAT, the conventional value 1 will be used for True, but
20444 when one of these values is read, any nonzero value is treated as True.
20447 @node Conventions and Anonymous Access Types,Determining the Representations chosen by GNAT,Effect of Convention on Representation,Representation Clauses and Pragmas
20448 @anchor{gnat_rm/representation_clauses_and_pragmas conventions-and-anonymous-access-types}@anchor{299}@anchor{gnat_rm/representation_clauses_and_pragmas id19}@anchor{29a}
20449 @section Conventions and Anonymous Access Types
20452 @geindex Anonymous access types
20454 @geindex Convention for anonymous access types
20456 The RM is not entirely clear on convention handling in a number of cases,
20457 and in particular, it is not clear on the convention to be given to
20458 anonymous access types in general, and in particular what is to be
20459 done for the case of anonymous access-to-subprogram.
20461 In GNAT, we decide that if an explicit Convention is applied
20462 to an object or component, and its type is such an anonymous type,
20463 then the convention will apply to this anonymous type as well. This
20464 seems to make sense since it is anomolous in any case to have a
20465 different convention for an object and its type, and there is clearly
20466 no way to explicitly specify a convention for an anonymous type, since
20467 it doesn't have a name to specify!
20469 Furthermore, we decide that if a convention is applied to a record type,
20470 then this convention is inherited by any of its components that are of an
20471 anonymous access type which do not have an explicitly specified convention.
20473 The following program shows these conventions in action:
20476 package ConvComp is
20477 type Foo is range 1 .. 10;
20479 A : access function (X : Foo) return Integer;
20482 pragma Convention (C, T1);
20485 A : access function (X : Foo) return Integer;
20486 pragma Convention (C, A);
20489 pragma Convention (COBOL, T2);
20492 A : access function (X : Foo) return Integer;
20493 pragma Convention (COBOL, A);
20496 pragma Convention (C, T3);
20499 A : access function (X : Foo) return Integer;
20502 pragma Convention (COBOL, T4);
20504 function F (X : Foo) return Integer;
20505 pragma Convention (C, F);
20507 function F (X : Foo) return Integer is (13);
20509 TV1 : T1 := (F'Access, 12); -- OK
20510 TV2 : T2 := (F'Access, 13); -- OK
20512 TV3 : T3 := (F'Access, 13); -- ERROR
20514 >>> subprogram "F" has wrong convention
20515 >>> does not match access to subprogram declared at line 17
20516 38. TV4 : T4 := (F'Access, 13); -- ERROR
20518 >>> subprogram "F" has wrong convention
20519 >>> does not match access to subprogram declared at line 24
20523 @node Determining the Representations chosen by GNAT,,Conventions and Anonymous Access Types,Representation Clauses and Pragmas
20524 @anchor{gnat_rm/representation_clauses_and_pragmas id20}@anchor{29b}@anchor{gnat_rm/representation_clauses_and_pragmas determining-the-representations-chosen-by-gnat}@anchor{29c}
20525 @section Determining the Representations chosen by GNAT
20528 @geindex Representation
20529 @geindex determination of
20531 @geindex -gnatR (gcc)
20533 Although the descriptions in this section are intended to be complete, it is
20534 often easier to simply experiment to see what GNAT accepts and what the
20535 effect is on the layout of types and objects.
20537 As required by the Ada RM, if a representation clause is not accepted, then
20538 it must be rejected as illegal by the compiler. However, when a
20539 representation clause or pragma is accepted, there can still be questions
20540 of what the compiler actually does. For example, if a partial record
20541 representation clause specifies the location of some components and not
20542 others, then where are the non-specified components placed? Or if pragma
20543 @code{Pack} is used on a record, then exactly where are the resulting
20544 fields placed? The section on pragma @code{Pack} in this chapter can be
20545 used to answer the second question, but it is often easier to just see
20546 what the compiler does.
20548 For this purpose, GNAT provides the option @emph{-gnatR}. If you compile
20549 with this option, then the compiler will output information on the actual
20550 representations chosen, in a format similar to source representation
20551 clauses. For example, if we compile the package:
20555 type r (x : boolean) is tagged record
20557 when True => S : String (1 .. 100);
20558 when False => null;
20562 type r2 is new r (false) with record
20567 y2 at 16 range 0 .. 31;
20574 type x1 is array (1 .. 10) of x;
20575 for x1'component_size use 11;
20577 type ia is access integer;
20579 type Rb1 is array (1 .. 13) of Boolean;
20582 type Rb2 is array (1 .. 65) of Boolean;
20597 using the switch @emph{-gnatR} we obtain the following output:
20600 Representation information for unit q
20601 -------------------------------------
20604 for r'Alignment use 4;
20606 x at 4 range 0 .. 7;
20607 _tag at 0 range 0 .. 31;
20608 s at 5 range 0 .. 799;
20611 for r2'Size use 160;
20612 for r2'Alignment use 4;
20614 x at 4 range 0 .. 7;
20615 _tag at 0 range 0 .. 31;
20616 _parent at 0 range 0 .. 63;
20617 y2 at 16 range 0 .. 31;
20621 for x'Alignment use 1;
20623 y at 0 range 0 .. 7;
20626 for x1'Size use 112;
20627 for x1'Alignment use 1;
20628 for x1'Component_Size use 11;
20630 for rb1'Size use 13;
20631 for rb1'Alignment use 2;
20632 for rb1'Component_Size use 1;
20634 for rb2'Size use 72;
20635 for rb2'Alignment use 1;
20636 for rb2'Component_Size use 1;
20638 for x2'Size use 224;
20639 for x2'Alignment use 4;
20641 l1 at 0 range 0 .. 0;
20642 l2 at 0 range 1 .. 64;
20643 l3 at 12 range 0 .. 31;
20644 l4 at 16 range 0 .. 0;
20645 l5 at 16 range 1 .. 13;
20646 l6 at 18 range 0 .. 71;
20650 The Size values are actually the Object_Size, i.e., the default size that
20651 will be allocated for objects of the type.
20652 The @code{??} size for type r indicates that we have a variant record, and the
20653 actual size of objects will depend on the discriminant value.
20655 The Alignment values show the actual alignment chosen by the compiler
20656 for each record or array type.
20658 The record representation clause for type r shows where all fields
20659 are placed, including the compiler generated tag field (whose location
20660 cannot be controlled by the programmer).
20662 The record representation clause for the type extension r2 shows all the
20663 fields present, including the parent field, which is a copy of the fields
20664 of the parent type of r2, i.e., r1.
20666 The component size and size clauses for types rb1 and rb2 show
20667 the exact effect of pragma @code{Pack} on these arrays, and the record
20668 representation clause for type x2 shows how pragma @cite{Pack} affects
20671 In some cases, it may be useful to cut and paste the representation clauses
20672 generated by the compiler into the original source to fix and guarantee
20673 the actual representation to be used.
20675 @node Standard Library Routines,The Implementation of Standard I/O,Representation Clauses and Pragmas,Top
20676 @anchor{gnat_rm/standard_library_routines standard-library-routines}@anchor{e}@anchor{gnat_rm/standard_library_routines doc}@anchor{29d}@anchor{gnat_rm/standard_library_routines id1}@anchor{29e}
20677 @chapter Standard Library Routines
20680 The Ada Reference Manual contains in Annex A a full description of an
20681 extensive set of standard library routines that can be used in any Ada
20682 program, and which must be provided by all Ada compilers. They are
20683 analogous to the standard C library used by C programs.
20685 GNAT implements all of the facilities described in annex A, and for most
20686 purposes the description in the Ada Reference Manual, or appropriate Ada
20687 text book, will be sufficient for making use of these facilities.
20689 In the case of the input-output facilities,
20690 @ref{f,,The Implementation of Standard I/O},
20691 gives details on exactly how GNAT interfaces to the
20692 file system. For the remaining packages, the Ada Reference Manual
20693 should be sufficient. The following is a list of the packages included,
20694 together with a brief description of the functionality that is provided.
20696 For completeness, references are included to other predefined library
20697 routines defined in other sections of the Ada Reference Manual (these are
20698 cross-indexed from Annex A). For further details see the relevant
20699 package declarations in the run-time library. In particular, a few units
20700 are not implemented, as marked by the presence of pragma Unimplemented_Unit,
20701 and in this case the package declaration contains comments explaining why
20702 the unit is not implemented.
20707 @item @code{Ada} @emph{(A.2)}
20709 This is a parent package for all the standard library packages. It is
20710 usually included implicitly in your program, and itself contains no
20711 useful data or routines.
20713 @item @code{Ada.Assertions} @emph{(11.4.2)}
20715 @code{Assertions} provides the @code{Assert} subprograms, and also
20716 the declaration of the @code{Assertion_Error} exception.
20718 @item @code{Ada.Asynchronous_Task_Control} @emph{(D.11)}
20720 @code{Asynchronous_Task_Control} provides low level facilities for task
20721 synchronization. It is typically not implemented. See package spec for details.
20723 @item @code{Ada.Calendar} @emph{(9.6)}
20725 @code{Calendar} provides time of day access, and routines for
20726 manipulating times and durations.
20728 @item @code{Ada.Calendar.Arithmetic} @emph{(9.6.1)}
20730 This package provides additional arithmetic
20731 operations for @code{Calendar}.
20733 @item @code{Ada.Calendar.Formatting} @emph{(9.6.1)}
20735 This package provides formatting operations for @code{Calendar}.
20737 @item @code{Ada.Calendar.Time_Zones} @emph{(9.6.1)}
20739 This package provides additional @code{Calendar} facilities
20740 for handling time zones.
20742 @item @code{Ada.Characters} @emph{(A.3.1)}
20744 This is a dummy parent package that contains no useful entities
20746 @item @code{Ada.Characters.Conversions} @emph{(A.3.2)}
20748 This package provides character conversion functions.
20750 @item @code{Ada.Characters.Handling} @emph{(A.3.2)}
20752 This package provides some basic character handling capabilities,
20753 including classification functions for classes of characters (e.g., test
20754 for letters, or digits).
20756 @item @code{Ada.Characters.Latin_1} @emph{(A.3.3)}
20758 This package includes a complete set of definitions of the characters
20759 that appear in type CHARACTER. It is useful for writing programs that
20760 will run in international environments. For example, if you want an
20761 upper case E with an acute accent in a string, it is often better to use
20762 the definition of @code{UC_E_Acute} in this package. Then your program
20763 will print in an understandable manner even if your environment does not
20764 support these extended characters.
20766 @item @code{Ada.Command_Line} @emph{(A.15)}
20768 This package provides access to the command line parameters and the name
20769 of the current program (analogous to the use of @code{argc} and @code{argv}
20770 in C), and also allows the exit status for the program to be set in a
20771 system-independent manner.
20773 @item @code{Ada.Complex_Text_IO} @emph{(G.1.3)}
20775 This package provides text input and output of complex numbers.
20777 @item @code{Ada.Containers} @emph{(A.18.1)}
20779 A top level package providing a few basic definitions used by all the
20780 following specific child packages that provide specific kinds of
20784 @code{Ada.Containers.Bounded_Priority_Queues} @emph{(A.18.31)}
20786 @code{Ada.Containers.Bounded_Synchronized_Queues} @emph{(A.18.29)}
20788 @code{Ada.Containers.Doubly_Linked_Lists} @emph{(A.18.3)}
20790 @code{Ada.Containers.Generic_Array_Sort} @emph{(A.18.26)}
20792 @code{Ada.Containers.Generic_Constrained_Array_Sort} @emph{(A.18.26)}
20794 @code{Ada.Containers.Generic_Sort} @emph{(A.18.26)}
20796 @code{Ada.Containers.Hashed_Maps} @emph{(A.18.5)}
20798 @code{Ada.Containers.Hashed_Sets} @emph{(A.18.8)}
20800 @code{Ada.Containers.Indefinite_Doubly_Linked_Lists} @emph{(A.18.12)}
20802 @code{Ada.Containers.Indefinite_Hashed_Maps} @emph{(A.18.13)}
20804 @code{Ada.Containers.Indefinite_Hashed_Sets} @emph{(A.18.15)}
20806 @code{Ada.Containers.Indefinite_Holders} @emph{(A.18.18)}
20808 @code{Ada.Containers.Indefinite_Multiway_Trees} @emph{(A.18.17)}
20810 @code{Ada.Containers.Indefinite_Ordered_Maps} @emph{(A.18.14)}
20812 @code{Ada.Containers.Indefinite_Ordered_Sets} @emph{(A.18.16)}
20814 @code{Ada.Containers.Indefinite_Vectors} @emph{(A.18.11)}
20816 @code{Ada.Containers.Multiway_Trees} @emph{(A.18.10)}
20818 @code{Ada.Containers.Ordered_Maps} @emph{(A.18.6)}
20820 @code{Ada.Containers.Ordered_Sets} @emph{(A.18.9)}
20822 @code{Ada.Containers.Synchronized_Queue_Interfaces} @emph{(A.18.27)}
20824 @code{Ada.Containers.Unbounded_Priority_Queues} @emph{(A.18.30)}
20826 @code{Ada.Containers.Unbounded_Synchronized_Queues} @emph{(A.18.28)}
20828 @code{Ada.Containers.Vectors} @emph{(A.18.2)}
20833 @item @code{Ada.Directories} @emph{(A.16)}
20835 This package provides operations on directories.
20837 @item @code{Ada.Directories.Hierarchical_File_Names} @emph{(A.16.1)}
20839 This package provides additional directory operations handling
20840 hiearchical file names.
20842 @item @code{Ada.Directories.Information} @emph{(A.16)}
20844 This is an implementation defined package for additional directory
20845 operations, which is not implemented in GNAT.
20847 @item @code{Ada.Decimal} @emph{(F.2)}
20849 This package provides constants describing the range of decimal numbers
20850 implemented, and also a decimal divide routine (analogous to the COBOL
20851 verb DIVIDE ... GIVING ... REMAINDER ...)
20853 @item @code{Ada.Direct_IO} @emph{(A.8.4)}
20855 This package provides input-output using a model of a set of records of
20856 fixed-length, containing an arbitrary definite Ada type, indexed by an
20857 integer record number.
20859 @item @code{Ada.Dispatching} @emph{(D.2.1)}
20861 A parent package containing definitions for task dispatching operations.
20863 @item @code{Ada.Dispatching.EDF} @emph{(D.2.6)}
20865 Not implemented in GNAT.
20867 @item @code{Ada.Dispatching.Non_Preemptive} @emph{(D.2.4)}
20869 Not implemented in GNAT.
20871 @item @code{Ada.Dispatching.Round_Robin} @emph{(D.2.5)}
20873 Not implemented in GNAT.
20875 @item @code{Ada.Dynamic_Priorities} @emph{(D.5)}
20877 This package allows the priorities of a task to be adjusted dynamically
20878 as the task is running.
20880 @item @code{Ada.Environment_Variables} @emph{(A.17)}
20882 This package provides facilities for accessing environment variables.
20884 @item @code{Ada.Exceptions} @emph{(11.4.1)}
20886 This package provides additional information on exceptions, and also
20887 contains facilities for treating exceptions as data objects, and raising
20888 exceptions with associated messages.
20890 @item @code{Ada.Execution_Time} @emph{(D.14)}
20892 This package provides CPU clock functionalities. It is not implemented on
20893 all targets (see package spec for details).
20895 @item @code{Ada.Execution_Time.Group_Budgets} @emph{(D.14.2)}
20897 Not implemented in GNAT.
20899 @item @code{Ada.Execution_Time.Timers} @emph{(D.14.1)'}
20901 Not implemented in GNAT.
20903 @item @code{Ada.Finalization} @emph{(7.6)}
20905 This package contains the declarations and subprograms to support the
20906 use of controlled types, providing for automatic initialization and
20907 finalization (analogous to the constructors and destructors of C++).
20909 @item @code{Ada.Float_Text_IO} @emph{(A.10.9)}
20911 A library level instantiation of Text_IO.Float_IO for type Float.
20913 @item @code{Ada.Float_Wide_Text_IO} @emph{(A.10.9)}
20915 A library level instantiation of Wide_Text_IO.Float_IO for type Float.
20917 @item @code{Ada.Float_Wide_Wide_Text_IO} @emph{(A.10.9)}
20919 A library level instantiation of Wide_Wide_Text_IO.Float_IO for type Float.
20921 @item @code{Ada.Integer_Text_IO} @emph{(A.10.9)}
20923 A library level instantiation of Text_IO.Integer_IO for type Integer.
20925 @item @code{Ada.Integer_Wide_Text_IO} @emph{(A.10.9)}
20927 A library level instantiation of Wide_Text_IO.Integer_IO for type Integer.
20929 @item @code{Ada.Integer_Wide_Wide_Text_IO} @emph{(A.10.9)}
20931 A library level instantiation of Wide_Wide_Text_IO.Integer_IO for type Integer.
20933 @item @code{Ada.Interrupts} @emph{(C.3.2)}
20935 This package provides facilities for interfacing to interrupts, which
20936 includes the set of signals or conditions that can be raised and
20937 recognized as interrupts.
20939 @item @code{Ada.Interrupts.Names} @emph{(C.3.2)}
20941 This package provides the set of interrupt names (actually signal
20942 or condition names) that can be handled by GNAT.
20944 @item @code{Ada.IO_Exceptions} @emph{(A.13)}
20946 This package defines the set of exceptions that can be raised by use of
20947 the standard IO packages.
20949 @item @code{Ada.Iterator_Interfaces} @emph{(5.5.1)}
20951 This package provides a generic interface to generalized iterators.
20953 @item @code{Ada.Locales} @emph{(A.19)}
20955 This package provides declarations providing information (Language
20956 and Country) about the current locale.
20958 @item @code{Ada.Numerics}
20960 This package contains some standard constants and exceptions used
20961 throughout the numerics packages. Note that the constants pi and e are
20962 defined here, and it is better to use these definitions than rolling
20965 @item @code{Ada.Numerics.Complex_Arrays} @emph{(G.3.2)}
20967 Provides operations on arrays of complex numbers.
20969 @item @code{Ada.Numerics.Complex_Elementary_Functions}
20971 Provides the implementation of standard elementary functions (such as
20972 log and trigonometric functions) operating on complex numbers using the
20973 standard @code{Float} and the @code{Complex} and @code{Imaginary} types
20974 created by the package @code{Numerics.Complex_Types}.
20976 @item @code{Ada.Numerics.Complex_Types}
20978 This is a predefined instantiation of
20979 @code{Numerics.Generic_Complex_Types} using @code{Standard.Float} to
20980 build the type @code{Complex} and @code{Imaginary}.
20982 @item @code{Ada.Numerics.Discrete_Random}
20984 This generic package provides a random number generator suitable for generating
20985 uniformly distributed values of a specified discrete subtype.
20987 @item @code{Ada.Numerics.Float_Random}
20989 This package provides a random number generator suitable for generating
20990 uniformly distributed floating point values in the unit interval.
20992 @item @code{Ada.Numerics.Generic_Complex_Elementary_Functions}
20994 This is a generic version of the package that provides the
20995 implementation of standard elementary functions (such as log and
20996 trigonometric functions) for an arbitrary complex type.
20998 The following predefined instantiations of this package are provided:
21006 @code{Ada.Numerics.Short_Complex_Elementary_Functions}
21011 @code{Ada.Numerics.Complex_Elementary_Functions}
21016 @code{Ada.Numerics.Long_Complex_Elementary_Functions}
21019 @item @code{Ada.Numerics.Generic_Complex_Types}
21021 This is a generic package that allows the creation of complex types,
21022 with associated complex arithmetic operations.
21024 The following predefined instantiations of this package exist
21032 @code{Ada.Numerics.Short_Complex_Complex_Types}
21037 @code{Ada.Numerics.Complex_Complex_Types}
21042 @code{Ada.Numerics.Long_Complex_Complex_Types}
21045 @item @code{Ada.Numerics.Generic_Elementary_Functions}
21047 This is a generic package that provides the implementation of standard
21048 elementary functions (such as log an trigonometric functions) for an
21049 arbitrary float type.
21051 The following predefined instantiations of this package exist
21059 @code{Ada.Numerics.Short_Elementary_Functions}
21064 @code{Ada.Numerics.Elementary_Functions}
21069 @code{Ada.Numerics.Long_Elementary_Functions}
21072 @item @code{Ada.Numerics.Generic_Real_Arrays} @emph{(G.3.1)}
21074 Generic operations on arrays of reals
21076 @item @code{Ada.Numerics.Real_Arrays} @emph{(G.3.1)}
21078 Preinstantiation of Ada.Numerics.Generic_Real_Arrays (Float).
21080 @item @code{Ada.Real_Time} @emph{(D.8)}
21082 This package provides facilities similar to those of @code{Calendar}, but
21083 operating with a finer clock suitable for real time control. Note that
21084 annex D requires that there be no backward clock jumps, and GNAT generally
21085 guarantees this behavior, but of course if the external clock on which
21086 the GNAT runtime depends is deliberately reset by some external event,
21087 then such a backward jump may occur.
21089 @item @code{Ada.Real_Time.Timing_Events} @emph{(D.15)}
21091 Not implemented in GNAT.
21093 @item @code{Ada.Sequential_IO} @emph{(A.8.1)}
21095 This package provides input-output facilities for sequential files,
21096 which can contain a sequence of values of a single type, which can be
21097 any Ada type, including indefinite (unconstrained) types.
21099 @item @code{Ada.Storage_IO} @emph{(A.9)}
21101 This package provides a facility for mapping arbitrary Ada types to and
21102 from a storage buffer. It is primarily intended for the creation of new
21105 @item @code{Ada.Streams} @emph{(13.13.1)}
21107 This is a generic package that provides the basic support for the
21108 concept of streams as used by the stream attributes (@code{Input},
21109 @code{Output}, @code{Read} and @code{Write}).
21111 @item @code{Ada.Streams.Stream_IO} @emph{(A.12.1)}
21113 This package is a specialization of the type @code{Streams} defined in
21114 package @code{Streams} together with a set of operations providing
21115 Stream_IO capability. The Stream_IO model permits both random and
21116 sequential access to a file which can contain an arbitrary set of values
21117 of one or more Ada types.
21119 @item @code{Ada.Strings} @emph{(A.4.1)}
21121 This package provides some basic constants used by the string handling
21124 @item @code{Ada.Strings.Bounded} @emph{(A.4.4)}
21126 This package provides facilities for handling variable length
21127 strings. The bounded model requires a maximum length. It is thus
21128 somewhat more limited than the unbounded model, but avoids the use of
21129 dynamic allocation or finalization.
21131 @item @code{Ada.Strings.Bounded.Equal_Case_Insensitive} @emph{(A.4.10)}
21133 Provides case-insensitive comparisons of bounded strings
21135 @item @code{Ada.Strings.Bounded.Hash} @emph{(A.4.9)}
21137 This package provides a generic hash function for bounded strings
21139 @item @code{Ada.Strings.Bounded.Hash_Case_Insensitive} @emph{(A.4.9)}
21141 This package provides a generic hash function for bounded strings that
21142 converts the string to be hashed to lower case.
21144 @item @code{Ada.Strings.Bounded.Less_Case_Insensitive} @emph{(A.4.10)}
21146 This package provides a comparison function for bounded strings that works
21147 in a case insensitive manner by converting to lower case before the comparison.
21149 @item @code{Ada.Strings.Fixed} @emph{(A.4.3)}
21151 This package provides facilities for handling fixed length strings.
21153 @item @code{Ada.Strings.Fixed.Equal_Case_Insensitive} @emph{(A.4.10)}
21155 This package provides an equality function for fixed strings that compares
21156 the strings after converting both to lower case.
21158 @item @code{Ada.Strings.Fixed.Hash_Case_Insensitive} @emph{(A.4.9)}
21160 This package provides a case insensitive hash function for fixed strings that
21161 converts the string to lower case before computing the hash.
21163 @item @code{Ada.Strings.Fixed.Less_Case_Insensitive} @emph{(A.4.10)}
21165 This package provides a comparison function for fixed strings that works
21166 in a case insensitive manner by converting to lower case before the comparison.
21168 @item @code{Ada.Strings.Hash} @emph{(A.4.9)}
21170 This package provides a hash function for strings.
21172 @item @code{Ada.Strings.Hash_Case_Insensitive} @emph{(A.4.9)}
21174 This package provides a hash function for strings that is case insensitive.
21175 The string is converted to lower case before computing the hash.
21177 @item @code{Ada.Strings.Less_Case_Insensitive} @emph{(A.4.10)}
21179 This package provides a comparison function for\strings that works
21180 in a case insensitive manner by converting to lower case before the comparison.
21182 @item @code{Ada.Strings.Maps} @emph{(A.4.2)}
21184 This package provides facilities for handling character mappings and
21185 arbitrarily defined subsets of characters. For instance it is useful in
21186 defining specialized translation tables.
21188 @item @code{Ada.Strings.Maps.Constants} @emph{(A.4.6)}
21190 This package provides a standard set of predefined mappings and
21191 predefined character sets. For example, the standard upper to lower case
21192 conversion table is found in this package. Note that upper to lower case
21193 conversion is non-trivial if you want to take the entire set of
21194 characters, including extended characters like E with an acute accent,
21195 into account. You should use the mappings in this package (rather than
21196 adding 32 yourself) to do case mappings.
21198 @item @code{Ada.Strings.Unbounded} @emph{(A.4.5)}
21200 This package provides facilities for handling variable length
21201 strings. The unbounded model allows arbitrary length strings, but
21202 requires the use of dynamic allocation and finalization.
21204 @item @code{Ada.Strings.Unbounded.Equal_Case_Insensitive} @emph{(A.4.10)}
21206 Provides case-insensitive comparisons of unbounded strings
21208 @item @code{Ada.Strings.Unbounded.Hash} @emph{(A.4.9)}
21210 This package provides a generic hash function for unbounded strings
21212 @item @code{Ada.Strings.Unbounded.Hash_Case_Insensitive} @emph{(A.4.9)}
21214 This package provides a generic hash function for unbounded strings that
21215 converts the string to be hashed to lower case.
21217 @item @code{Ada.Strings.Unbounded.Less_Case_Insensitive} @emph{(A.4.10)}
21219 This package provides a comparison function for unbounded strings that works
21220 in a case insensitive manner by converting to lower case before the comparison.
21222 @item @code{Ada.Strings.UTF_Encoding} @emph{(A.4.11)}
21224 This package provides basic definitions for dealing with UTF-encoded strings.
21226 @item @code{Ada.Strings.UTF_Encoding.Conversions} @emph{(A.4.11)}
21228 This package provides conversion functions for UTF-encoded strings.
21231 @code{Ada.Strings.UTF_Encoding.Strings} @emph{(A.4.11)}
21233 @code{Ada.Strings.UTF_Encoding.Wide_Strings} @emph{(A.4.11)}
21238 @item @code{Ada.Strings.UTF_Encoding.Wide_Wide_Strings} @emph{(A.4.11)}
21240 These packages provide facilities for handling UTF encodings for
21241 Strings, Wide_Strings and Wide_Wide_Strings.
21244 @code{Ada.Strings.Wide_Bounded} @emph{(A.4.7)}
21246 @code{Ada.Strings.Wide_Fixed} @emph{(A.4.7)}
21248 @code{Ada.Strings.Wide_Maps} @emph{(A.4.7)}
21253 @item @code{Ada.Strings.Wide_Unbounded} @emph{(A.4.7)}
21255 These packages provide analogous capabilities to the corresponding
21256 packages without @code{Wide_} in the name, but operate with the types
21257 @code{Wide_String} and @code{Wide_Character} instead of @code{String}
21258 and @code{Character}. Versions of all the child packages are available.
21261 @code{Ada.Strings.Wide_Wide_Bounded} @emph{(A.4.7)}
21263 @code{Ada.Strings.Wide_Wide_Fixed} @emph{(A.4.7)}
21265 @code{Ada.Strings.Wide_Wide_Maps} @emph{(A.4.7)}
21270 @item @code{Ada.Strings.Wide_Wide_Unbounded} @emph{(A.4.7)}
21272 These packages provide analogous capabilities to the corresponding
21273 packages without @code{Wide_} in the name, but operate with the types
21274 @code{Wide_Wide_String} and @code{Wide_Wide_Character} instead
21275 of @code{String} and @code{Character}.
21277 @item @code{Ada.Synchronous_Barriers} @emph{(D.10.1)}
21279 This package provides facilities for synchronizing tasks at a low level
21282 @item @code{Ada.Synchronous_Task_Control} @emph{(D.10)}
21284 This package provides some standard facilities for controlling task
21285 communication in a synchronous manner.
21287 @item @code{Ada.Synchronous_Task_Control.EDF} @emph{(D.10)}
21289 Not implemented in GNAT.
21291 @item @code{Ada.Tags}
21293 This package contains definitions for manipulation of the tags of tagged
21296 @item @code{Ada.Tags.Generic_Dispatching_Constructor} @emph{(3.9)}
21298 This package provides a way of constructing tagged class-wide values given
21299 only the tag value.
21301 @item @code{Ada.Task_Attributes} @emph{(C.7.2)}
21303 This package provides the capability of associating arbitrary
21304 task-specific data with separate tasks.
21306 @item @code{Ada.Task_Identifification} @emph{(C.7.1)}
21308 This package provides capabilities for task identification.
21310 @item @code{Ada.Task_Termination} @emph{(C.7.3)}
21312 This package provides control over task termination.
21314 @item @code{Ada.Text_IO}
21316 This package provides basic text input-output capabilities for
21317 character, string and numeric data. The subpackages of this
21318 package are listed next. Note that although these are defined
21319 as subpackages in the RM, they are actually transparently
21320 implemented as child packages in GNAT, meaning that they
21321 are only loaded if needed.
21323 @item @code{Ada.Text_IO.Decimal_IO}
21325 Provides input-output facilities for decimal fixed-point types
21327 @item @code{Ada.Text_IO.Enumeration_IO}
21329 Provides input-output facilities for enumeration types.
21331 @item @code{Ada.Text_IO.Fixed_IO}
21333 Provides input-output facilities for ordinary fixed-point types.
21335 @item @code{Ada.Text_IO.Float_IO}
21337 Provides input-output facilities for float types. The following
21338 predefined instantiations of this generic package are available:
21346 @code{Short_Float_Text_IO}
21351 @code{Float_Text_IO}
21356 @code{Long_Float_Text_IO}
21359 @item @code{Ada.Text_IO.Integer_IO}
21361 Provides input-output facilities for integer types. The following
21362 predefined instantiations of this generic package are available:
21368 @code{Short_Short_Integer}
21370 @code{Ada.Short_Short_Integer_Text_IO}
21373 @code{Short_Integer}
21375 @code{Ada.Short_Integer_Text_IO}
21380 @code{Ada.Integer_Text_IO}
21383 @code{Long_Integer}
21385 @code{Ada.Long_Integer_Text_IO}
21388 @code{Long_Long_Integer}
21390 @code{Ada.Long_Long_Integer_Text_IO}
21393 @item @code{Ada.Text_IO.Modular_IO}
21395 Provides input-output facilities for modular (unsigned) types.
21397 @item @code{Ada.Text_IO.Bounded_IO (A.10.11)}
21399 Provides input-output facilities for bounded strings.
21401 @item @code{Ada.Text_IO.Complex_IO (G.1.3)}
21403 This package provides basic text input-output capabilities for complex
21406 @item @code{Ada.Text_IO.Editing (F.3.3)}
21408 This package contains routines for edited output, analogous to the use
21409 of pictures in COBOL. The picture formats used by this package are a
21410 close copy of the facility in COBOL.
21412 @item @code{Ada.Text_IO.Text_Streams (A.12.2)}
21414 This package provides a facility that allows Text_IO files to be treated
21415 as streams, so that the stream attributes can be used for writing
21416 arbitrary data, including binary data, to Text_IO files.
21418 @item @code{Ada.Text_IO.Unbounded_IO (A.10.12)}
21420 This package provides input-output facilities for unbounded strings.
21422 @item @code{Ada.Unchecked_Conversion (13.9)}
21424 This generic package allows arbitrary conversion from one type to
21425 another of the same size, providing for breaking the type safety in
21426 special circumstances.
21428 If the types have the same Size (more accurately the same Value_Size),
21429 then the effect is simply to transfer the bits from the source to the
21430 target type without any modification. This usage is well defined, and
21431 for simple types whose representation is typically the same across
21432 all implementations, gives a portable method of performing such
21435 If the types do not have the same size, then the result is implementation
21436 defined, and thus may be non-portable. The following describes how GNAT
21437 handles such unchecked conversion cases.
21439 If the types are of different sizes, and are both discrete types, then
21440 the effect is of a normal type conversion without any constraint checking.
21441 In particular if the result type has a larger size, the result will be
21442 zero or sign extended. If the result type has a smaller size, the result
21443 will be truncated by ignoring high order bits.
21445 If the types are of different sizes, and are not both discrete types,
21446 then the conversion works as though pointers were created to the source
21447 and target, and the pointer value is converted. The effect is that bits
21448 are copied from successive low order storage units and bits of the source
21449 up to the length of the target type.
21451 A warning is issued if the lengths differ, since the effect in this
21452 case is implementation dependent, and the above behavior may not match
21453 that of some other compiler.
21455 A pointer to one type may be converted to a pointer to another type using
21456 unchecked conversion. The only case in which the effect is undefined is
21457 when one or both pointers are pointers to unconstrained array types. In
21458 this case, the bounds information may get incorrectly transferred, and in
21459 particular, GNAT uses double size pointers for such types, and it is
21460 meaningless to convert between such pointer types. GNAT will issue a
21461 warning if the alignment of the target designated type is more strict
21462 than the alignment of the source designated type (since the result may
21463 be unaligned in this case).
21465 A pointer other than a pointer to an unconstrained array type may be
21466 converted to and from System.Address. Such usage is common in Ada 83
21467 programs, but note that Ada.Address_To_Access_Conversions is the
21468 preferred method of performing such conversions in Ada 95 and Ada 2005.
21470 unchecked conversion nor Ada.Address_To_Access_Conversions should be
21471 used in conjunction with pointers to unconstrained objects, since
21472 the bounds information cannot be handled correctly in this case.
21474 @item @code{Ada.Unchecked_Deallocation} @emph{(13.11.2)}
21476 This generic package allows explicit freeing of storage previously
21477 allocated by use of an allocator.
21479 @item @code{Ada.Wide_Text_IO} @emph{(A.11)}
21481 This package is similar to @code{Ada.Text_IO}, except that the external
21482 file supports wide character representations, and the internal types are
21483 @code{Wide_Character} and @code{Wide_String} instead of @code{Character}
21484 and @code{String}. The corresponding set of nested packages and child
21485 packages are defined.
21487 @item @code{Ada.Wide_Wide_Text_IO} @emph{(A.11)}
21489 This package is similar to @code{Ada.Text_IO}, except that the external
21490 file supports wide character representations, and the internal types are
21491 @code{Wide_Character} and @code{Wide_String} instead of @code{Character}
21492 and @code{String}. The corresponding set of nested packages and child
21493 packages are defined.
21496 For packages in Interfaces and System, all the RM defined packages are
21497 available in GNAT, see the Ada 2012 RM for full details.
21499 @node The Implementation of Standard I/O,The GNAT Library,Standard Library Routines,Top
21500 @anchor{gnat_rm/the_implementation_of_standard_i_o the-implementation-of-standard-i-o}@anchor{f}@anchor{gnat_rm/the_implementation_of_standard_i_o doc}@anchor{29f}@anchor{gnat_rm/the_implementation_of_standard_i_o id1}@anchor{2a0}
21501 @chapter The Implementation of Standard I/O
21504 GNAT implements all the required input-output facilities described in
21505 A.6 through A.14. These sections of the Ada Reference Manual describe the
21506 required behavior of these packages from the Ada point of view, and if
21507 you are writing a portable Ada program that does not need to know the
21508 exact manner in which Ada maps to the outside world when it comes to
21509 reading or writing external files, then you do not need to read this
21510 chapter. As long as your files are all regular files (not pipes or
21511 devices), and as long as you write and read the files only from Ada, the
21512 description in the Ada Reference Manual is sufficient.
21514 However, if you want to do input-output to pipes or other devices, such
21515 as the keyboard or screen, or if the files you are dealing with are
21516 either generated by some other language, or to be read by some other
21517 language, then you need to know more about the details of how the GNAT
21518 implementation of these input-output facilities behaves.
21520 In this chapter we give a detailed description of exactly how GNAT
21521 interfaces to the file system. As always, the sources of the system are
21522 available to you for answering questions at an even more detailed level,
21523 but for most purposes the information in this chapter will suffice.
21525 Another reason that you may need to know more about how input-output is
21526 implemented arises when you have a program written in mixed languages
21527 where, for example, files are shared between the C and Ada sections of
21528 the same program. GNAT provides some additional facilities, in the form
21529 of additional child library packages, that facilitate this sharing, and
21530 these additional facilities are also described in this chapter.
21533 * Standard I/O Packages::
21539 * Wide_Wide_Text_IO::
21541 * Text Translation::
21543 * Filenames encoding::
21544 * File content encoding::
21546 * Operations on C Streams::
21547 * Interfacing to C Streams::
21551 @node Standard I/O Packages,FORM Strings,,The Implementation of Standard I/O
21552 @anchor{gnat_rm/the_implementation_of_standard_i_o standard-i-o-packages}@anchor{2a1}@anchor{gnat_rm/the_implementation_of_standard_i_o id2}@anchor{2a2}
21553 @section Standard I/O Packages
21556 The Standard I/O packages described in Annex A for
21565 Ada.Text_IO.Complex_IO
21568 Ada.Text_IO.Text_Streams
21574 Ada.Wide_Text_IO.Complex_IO
21577 Ada.Wide_Text_IO.Text_Streams
21580 Ada.Wide_Wide_Text_IO
21583 Ada.Wide_Wide_Text_IO.Complex_IO
21586 Ada.Wide_Wide_Text_IO.Text_Streams
21598 are implemented using the C
21599 library streams facility; where
21605 All files are opened using @code{fopen}.
21608 All input/output operations use @code{fread}/@cite{fwrite}.
21611 There is no internal buffering of any kind at the Ada library level. The only
21612 buffering is that provided at the system level in the implementation of the
21613 library routines that support streams. This facilitates shared use of these
21614 streams by mixed language programs. Note though that system level buffering is
21615 explicitly enabled at elaboration of the standard I/O packages and that can
21616 have an impact on mixed language programs, in particular those using I/O before
21617 calling the Ada elaboration routine (e.g., adainit). It is recommended to call
21618 the Ada elaboration routine before performing any I/O or when impractical,
21619 flush the common I/O streams and in particular Standard_Output before
21620 elaborating the Ada code.
21622 @node FORM Strings,Direct_IO,Standard I/O Packages,The Implementation of Standard I/O
21623 @anchor{gnat_rm/the_implementation_of_standard_i_o form-strings}@anchor{2a3}@anchor{gnat_rm/the_implementation_of_standard_i_o id3}@anchor{2a4}
21624 @section FORM Strings
21627 The format of a FORM string in GNAT is:
21630 "keyword=value,keyword=value,...,keyword=value"
21633 where letters may be in upper or lower case, and there are no spaces
21634 between values. The order of the entries is not important. Currently
21635 the following keywords defined.
21638 TEXT_TRANSLATION=[YES|NO|TEXT|BINARY|U8TEXT|WTEXT|U16TEXT]
21640 WCEM=[n|h|u|s|e|8|b]
21641 ENCODING=[UTF8|8BITS]
21644 The use of these parameters is described later in this section. If an
21645 unrecognized keyword appears in a form string, it is silently ignored
21646 and not considered invalid.
21648 @node Direct_IO,Sequential_IO,FORM Strings,The Implementation of Standard I/O
21649 @anchor{gnat_rm/the_implementation_of_standard_i_o direct-io}@anchor{2a5}@anchor{gnat_rm/the_implementation_of_standard_i_o id4}@anchor{2a6}
21653 Direct_IO can only be instantiated for definite types. This is a
21654 restriction of the Ada language, which means that the records are fixed
21655 length (the length being determined by @code{type'Size}, rounded
21656 up to the next storage unit boundary if necessary).
21658 The records of a Direct_IO file are simply written to the file in index
21659 sequence, with the first record starting at offset zero, and subsequent
21660 records following. There is no control information of any kind. For
21661 example, if 32-bit integers are being written, each record takes
21662 4-bytes, so the record at index @code{K} starts at offset
21665 There is no limit on the size of Direct_IO files, they are expanded as
21666 necessary to accommodate whatever records are written to the file.
21668 @node Sequential_IO,Text_IO,Direct_IO,The Implementation of Standard I/O
21669 @anchor{gnat_rm/the_implementation_of_standard_i_o sequential-io}@anchor{2a7}@anchor{gnat_rm/the_implementation_of_standard_i_o id5}@anchor{2a8}
21670 @section Sequential_IO
21673 Sequential_IO may be instantiated with either a definite (constrained)
21674 or indefinite (unconstrained) type.
21676 For the definite type case, the elements written to the file are simply
21677 the memory images of the data values with no control information of any
21678 kind. The resulting file should be read using the same type, no validity
21679 checking is performed on input.
21681 For the indefinite type case, the elements written consist of two
21682 parts. First is the size of the data item, written as the memory image
21683 of a @code{Interfaces.C.size_t} value, followed by the memory image of
21684 the data value. The resulting file can only be read using the same
21685 (unconstrained) type. Normal assignment checks are performed on these
21686 read operations, and if these checks fail, @code{Data_Error} is
21687 raised. In particular, in the array case, the lengths must match, and in
21688 the variant record case, if the variable for a particular read operation
21689 is constrained, the discriminants must match.
21691 Note that it is not possible to use Sequential_IO to write variable
21692 length array items, and then read the data back into different length
21693 arrays. For example, the following will raise @code{Data_Error}:
21696 package IO is new Sequential_IO (String);
21701 IO.Write (F, "hello!")
21702 IO.Reset (F, Mode=>In_File);
21707 On some Ada implementations, this will print @code{hell}, but the program is
21708 clearly incorrect, since there is only one element in the file, and that
21709 element is the string @code{hello!}.
21711 In Ada 95 and Ada 2005, this kind of behavior can be legitimately achieved
21712 using Stream_IO, and this is the preferred mechanism. In particular, the
21713 above program fragment rewritten to use Stream_IO will work correctly.
21715 @node Text_IO,Wide_Text_IO,Sequential_IO,The Implementation of Standard I/O
21716 @anchor{gnat_rm/the_implementation_of_standard_i_o id6}@anchor{2a9}@anchor{gnat_rm/the_implementation_of_standard_i_o text-io}@anchor{2aa}
21720 Text_IO files consist of a stream of characters containing the following
21721 special control characters:
21724 LF (line feed, 16#0A#) Line Mark
21725 FF (form feed, 16#0C#) Page Mark
21728 A canonical Text_IO file is defined as one in which the following
21729 conditions are met:
21735 The character @code{LF} is used only as a line mark, i.e., to mark the end
21739 The character @code{FF} is used only as a page mark, i.e., to mark the
21740 end of a page and consequently can appear only immediately following a
21741 @code{LF} (line mark) character.
21744 The file ends with either @code{LF} (line mark) or @code{LF}-@cite{FF}
21745 (line mark, page mark). In the former case, the page mark is implicitly
21746 assumed to be present.
21749 A file written using Text_IO will be in canonical form provided that no
21750 explicit @code{LF} or @code{FF} characters are written using @code{Put}
21751 or @code{Put_Line}. There will be no @code{FF} character at the end of
21752 the file unless an explicit @code{New_Page} operation was performed
21753 before closing the file.
21755 A canonical Text_IO file that is a regular file (i.e., not a device or a
21756 pipe) can be read using any of the routines in Text_IO. The
21757 semantics in this case will be exactly as defined in the Ada Reference
21758 Manual, and all the routines in Text_IO are fully implemented.
21760 A text file that does not meet the requirements for a canonical Text_IO
21761 file has one of the following:
21767 The file contains @code{FF} characters not immediately following a
21768 @code{LF} character.
21771 The file contains @code{LF} or @code{FF} characters written by
21772 @code{Put} or @code{Put_Line}, which are not logically considered to be
21773 line marks or page marks.
21776 The file ends in a character other than @code{LF} or @code{FF},
21777 i.e., there is no explicit line mark or page mark at the end of the file.
21780 Text_IO can be used to read such non-standard text files but subprograms
21781 to do with line or page numbers do not have defined meanings. In
21782 particular, a @code{FF} character that does not follow a @code{LF}
21783 character may or may not be treated as a page mark from the point of
21784 view of page and line numbering. Every @code{LF} character is considered
21785 to end a line, and there is an implied @code{LF} character at the end of
21789 * Stream Pointer Positioning::
21790 * Reading and Writing Non-Regular Files::
21792 * Treating Text_IO Files as Streams::
21793 * Text_IO Extensions::
21794 * Text_IO Facilities for Unbounded Strings::
21798 @node Stream Pointer Positioning,Reading and Writing Non-Regular Files,,Text_IO
21799 @anchor{gnat_rm/the_implementation_of_standard_i_o id7}@anchor{2ab}@anchor{gnat_rm/the_implementation_of_standard_i_o stream-pointer-positioning}@anchor{2ac}
21800 @subsection Stream Pointer Positioning
21803 @code{Ada.Text_IO} has a definition of current position for a file that
21804 is being read. No internal buffering occurs in Text_IO, and usually the
21805 physical position in the stream used to implement the file corresponds
21806 to this logical position defined by Text_IO. There are two exceptions:
21812 After a call to @code{End_Of_Page} that returns @code{True}, the stream
21813 is positioned past the @code{LF} (line mark) that precedes the page
21814 mark. Text_IO maintains an internal flag so that subsequent read
21815 operations properly handle the logical position which is unchanged by
21816 the @code{End_Of_Page} call.
21819 After a call to @code{End_Of_File} that returns @code{True}, if the
21820 Text_IO file was positioned before the line mark at the end of file
21821 before the call, then the logical position is unchanged, but the stream
21822 is physically positioned right at the end of file (past the line mark,
21823 and past a possible page mark following the line mark. Again Text_IO
21824 maintains internal flags so that subsequent read operations properly
21825 handle the logical position.
21828 These discrepancies have no effect on the observable behavior of
21829 Text_IO, but if a single Ada stream is shared between a C program and
21830 Ada program, or shared (using @code{shared=yes} in the form string)
21831 between two Ada files, then the difference may be observable in some
21834 @node Reading and Writing Non-Regular Files,Get_Immediate,Stream Pointer Positioning,Text_IO
21835 @anchor{gnat_rm/the_implementation_of_standard_i_o reading-and-writing-non-regular-files}@anchor{2ad}@anchor{gnat_rm/the_implementation_of_standard_i_o id8}@anchor{2ae}
21836 @subsection Reading and Writing Non-Regular Files
21839 A non-regular file is a device (such as a keyboard), or a pipe. Text_IO
21840 can be used for reading and writing. Writing is not affected and the
21841 sequence of characters output is identical to the normal file case, but
21842 for reading, the behavior of Text_IO is modified to avoid undesirable
21843 look-ahead as follows:
21845 An input file that is not a regular file is considered to have no page
21846 marks. Any @code{Ascii.FF} characters (the character normally used for a
21847 page mark) appearing in the file are considered to be data
21848 characters. In particular:
21854 @code{Get_Line} and @code{Skip_Line} do not test for a page mark
21855 following a line mark. If a page mark appears, it will be treated as a
21859 This avoids the need to wait for an extra character to be typed or
21860 entered from the pipe to complete one of these operations.
21863 @code{End_Of_Page} always returns @code{False}
21866 @code{End_Of_File} will return @code{False} if there is a page mark at
21867 the end of the file.
21870 Output to non-regular files is the same as for regular files. Page marks
21871 may be written to non-regular files using @code{New_Page}, but as noted
21872 above they will not be treated as page marks on input if the output is
21873 piped to another Ada program.
21875 Another important discrepancy when reading non-regular files is that the end
21876 of file indication is not 'sticky'. If an end of file is entered, e.g., by
21877 pressing the @code{EOT} key,
21879 is signaled once (i.e., the test @code{End_Of_File}
21880 will yield @code{True}, or a read will
21881 raise @code{End_Error}), but then reading can resume
21882 to read data past that end of
21883 file indication, until another end of file indication is entered.
21885 @node Get_Immediate,Treating Text_IO Files as Streams,Reading and Writing Non-Regular Files,Text_IO
21886 @anchor{gnat_rm/the_implementation_of_standard_i_o get-immediate}@anchor{2af}@anchor{gnat_rm/the_implementation_of_standard_i_o id9}@anchor{2b0}
21887 @subsection Get_Immediate
21890 @geindex Get_Immediate
21892 Get_Immediate returns the next character (including control characters)
21893 from the input file. In particular, Get_Immediate will return LF or FF
21894 characters used as line marks or page marks. Such operations leave the
21895 file positioned past the control character, and it is thus not treated
21896 as having its normal function. This means that page, line and column
21897 counts after this kind of Get_Immediate call are set as though the mark
21898 did not occur. In the case where a Get_Immediate leaves the file
21899 positioned between the line mark and page mark (which is not normally
21900 possible), it is undefined whether the FF character will be treated as a
21903 @node Treating Text_IO Files as Streams,Text_IO Extensions,Get_Immediate,Text_IO
21904 @anchor{gnat_rm/the_implementation_of_standard_i_o id10}@anchor{2b1}@anchor{gnat_rm/the_implementation_of_standard_i_o treating-text-io-files-as-streams}@anchor{2b2}
21905 @subsection Treating Text_IO Files as Streams
21908 @geindex Stream files
21910 The package @code{Text_IO.Streams} allows a @code{Text_IO} file to be treated
21911 as a stream. Data written to a @code{Text_IO} file in this stream mode is
21912 binary data. If this binary data contains bytes 16#0A# (@code{LF}) or
21913 16#0C# (@code{FF}), the resulting file may have non-standard
21914 format. Similarly if read operations are used to read from a Text_IO
21915 file treated as a stream, then @code{LF} and @code{FF} characters may be
21916 skipped and the effect is similar to that described above for
21917 @code{Get_Immediate}.
21919 @node Text_IO Extensions,Text_IO Facilities for Unbounded Strings,Treating Text_IO Files as Streams,Text_IO
21920 @anchor{gnat_rm/the_implementation_of_standard_i_o id11}@anchor{2b3}@anchor{gnat_rm/the_implementation_of_standard_i_o text-io-extensions}@anchor{2b4}
21921 @subsection Text_IO Extensions
21924 @geindex Text_IO extensions
21926 A package GNAT.IO_Aux in the GNAT library provides some useful extensions
21927 to the standard @code{Text_IO} package:
21933 function File_Exists (Name : String) return Boolean;
21934 Determines if a file of the given name exists.
21937 function Get_Line return String;
21938 Reads a string from the standard input file. The value returned is exactly
21939 the length of the line that was read.
21942 function Get_Line (File : Ada.Text_IO.File_Type) return String;
21943 Similar, except that the parameter File specifies the file from which
21944 the string is to be read.
21947 @node Text_IO Facilities for Unbounded Strings,,Text_IO Extensions,Text_IO
21948 @anchor{gnat_rm/the_implementation_of_standard_i_o text-io-facilities-for-unbounded-strings}@anchor{2b5}@anchor{gnat_rm/the_implementation_of_standard_i_o id12}@anchor{2b6}
21949 @subsection Text_IO Facilities for Unbounded Strings
21952 @geindex Text_IO for unbounded strings
21954 @geindex Unbounded_String
21955 @geindex Text_IO operations
21957 The package @code{Ada.Strings.Unbounded.Text_IO}
21958 in library files @code{a-suteio.ads/adb} contains some GNAT-specific
21959 subprograms useful for Text_IO operations on unbounded strings:
21965 function Get_Line (File : File_Type) return Unbounded_String;
21966 Reads a line from the specified file
21967 and returns the result as an unbounded string.
21970 procedure Put (File : File_Type; U : Unbounded_String);
21971 Writes the value of the given unbounded string to the specified file
21972 Similar to the effect of
21973 @code{Put (To_String (U))} except that an extra copy is avoided.
21976 procedure Put_Line (File : File_Type; U : Unbounded_String);
21977 Writes the value of the given unbounded string to the specified file,
21978 followed by a @code{New_Line}.
21979 Similar to the effect of @code{Put_Line (To_String (U))} except
21980 that an extra copy is avoided.
21983 In the above procedures, @code{File} is of type @code{Ada.Text_IO.File_Type}
21984 and is optional. If the parameter is omitted, then the standard input or
21985 output file is referenced as appropriate.
21987 The package @code{Ada.Strings.Wide_Unbounded.Wide_Text_IO} in library
21988 files @code{a-swuwti.ads} and @code{a-swuwti.adb} provides similar extended
21989 @code{Wide_Text_IO} functionality for unbounded wide strings.
21991 The package @code{Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO} in library
21992 files @code{a-szuzti.ads} and @code{a-szuzti.adb} provides similar extended
21993 @code{Wide_Wide_Text_IO} functionality for unbounded wide wide strings.
21995 @node Wide_Text_IO,Wide_Wide_Text_IO,Text_IO,The Implementation of Standard I/O
21996 @anchor{gnat_rm/the_implementation_of_standard_i_o wide-text-io}@anchor{2b7}@anchor{gnat_rm/the_implementation_of_standard_i_o id13}@anchor{2b8}
21997 @section Wide_Text_IO
22000 @code{Wide_Text_IO} is similar in most respects to Text_IO, except that
22001 both input and output files may contain special sequences that represent
22002 wide character values. The encoding scheme for a given file may be
22003 specified using a FORM parameter:
22009 as part of the FORM string (WCEM = wide character encoding method),
22010 where @code{x} is one of the following characters
22013 @multitable {xxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxx}
22036 Upper half encoding
22073 The encoding methods match those that
22074 can be used in a source
22075 program, but there is no requirement that the encoding method used for
22076 the source program be the same as the encoding method used for files,
22077 and different files may use different encoding methods.
22079 The default encoding method for the standard files, and for opened files
22080 for which no WCEM parameter is given in the FORM string matches the
22081 wide character encoding specified for the main program (the default
22082 being brackets encoding if no coding method was specified with -gnatW).
22087 @item @emph{Hex Coding}
22089 In this encoding, a wide character is represented by a five character
22100 where @code{a}, @code{b}, @code{c}, @code{d} are the four hexadecimal
22101 characters (using upper case letters) of the wide character code. For
22102 example, ESC A345 is used to represent the wide character with code
22103 16#A345#. This scheme is compatible with use of the full
22104 @code{Wide_Character} set.
22110 @item @emph{Upper Half Coding}
22112 The wide character with encoding 16#abcd#, where the upper bit is on
22113 (i.e., a is in the range 8-F) is represented as two bytes 16#ab# and
22114 16#cd#. The second byte may never be a format control character, but is
22115 not required to be in the upper half. This method can be also used for
22116 shift-JIS or EUC where the internal coding matches the external coding.
22118 @item @emph{Shift JIS Coding}
22120 A wide character is represented by a two character sequence 16#ab# and
22121 16#cd#, with the restrictions described for upper half encoding as
22122 described above. The internal character code is the corresponding JIS
22123 character according to the standard algorithm for Shift-JIS
22124 conversion. Only characters defined in the JIS code set table can be
22125 used with this encoding method.
22127 @item @emph{EUC Coding}
22129 A wide character is represented by a two character sequence 16#ab# and
22130 16#cd#, with both characters being in the upper half. The internal
22131 character code is the corresponding JIS character according to the EUC
22132 encoding algorithm. Only characters defined in the JIS code set table
22133 can be used with this encoding method.
22135 @item @emph{UTF-8 Coding}
22137 A wide character is represented using
22138 UCS Transformation Format 8 (UTF-8) as defined in Annex R of ISO
22139 10646-1/Am.2. Depending on the character value, the representation
22140 is a one, two, or three byte sequence:
22144 16#0000#-16#007f#: 2#0xxxxxxx#
22145 16#0080#-16#07ff#: 2#110xxxxx# 2#10xxxxxx#
22146 16#0800#-16#ffff#: 2#1110xxxx# 2#10xxxxxx# 2#10xxxxxx#
22152 where the @code{xxx} bits correspond to the left-padded bits of the
22153 16-bit character value. Note that all lower half ASCII characters
22154 are represented as ASCII bytes and all upper half characters and
22155 other wide characters are represented as sequences of upper-half
22156 (The full UTF-8 scheme allows for encoding 31-bit characters as
22157 6-byte sequences, but in this implementation, all UTF-8 sequences
22158 of four or more bytes length will raise a Constraint_Error, as
22159 will all invalid UTF-8 sequences.)
22165 @item @emph{Brackets Coding}
22167 In this encoding, a wide character is represented by the following eight
22168 character sequence:
22178 where @code{a}, @code{b}, @code{c}, @code{d} are the four hexadecimal
22179 characters (using uppercase letters) of the wide character code. For
22180 example, @code{["A345"]} is used to represent the wide character with code
22182 This scheme is compatible with use of the full Wide_Character set.
22183 On input, brackets coding can also be used for upper half characters,
22184 e.g., @code{["C1"]} for lower case a. However, on output, brackets notation
22185 is only used for wide characters with a code greater than @code{16#FF#}.
22187 Note that brackets coding is not normally used in the context of
22188 Wide_Text_IO or Wide_Wide_Text_IO, since it is really just designed as
22189 a portable way of encoding source files. In the context of Wide_Text_IO
22190 or Wide_Wide_Text_IO, it can only be used if the file does not contain
22191 any instance of the left bracket character other than to encode wide
22192 character values using the brackets encoding method. In practice it is
22193 expected that some standard wide character encoding method such
22194 as UTF-8 will be used for text input output.
22196 If brackets notation is used, then any occurrence of a left bracket
22197 in the input file which is not the start of a valid wide character
22198 sequence will cause Constraint_Error to be raised. It is possible to
22199 encode a left bracket as ["5B"] and Wide_Text_IO and Wide_Wide_Text_IO
22200 input will interpret this as a left bracket.
22202 However, when a left bracket is output, it will be output as a left bracket
22203 and not as ["5B"]. We make this decision because for normal use of
22204 Wide_Text_IO for outputting messages, it is unpleasant to clobber left
22205 brackets. For example, if we write:
22208 Put_Line ("Start of output [first run]");
22211 we really do not want to have the left bracket in this message clobbered so
22212 that the output reads:
22216 Start of output ["5B"]first run]
22222 In practice brackets encoding is reasonably useful for normal Put_Line use
22223 since we won't get confused between left brackets and wide character
22224 sequences in the output. But for input, or when files are written out
22225 and read back in, it really makes better sense to use one of the standard
22226 encoding methods such as UTF-8.
22229 For the coding schemes other than UTF-8, Hex, or Brackets encoding,
22230 not all wide character
22231 values can be represented. An attempt to output a character that cannot
22232 be represented using the encoding scheme for the file causes
22233 Constraint_Error to be raised. An invalid wide character sequence on
22234 input also causes Constraint_Error to be raised.
22237 * Stream Pointer Positioning: Stream Pointer Positioning<2>.
22238 * Reading and Writing Non-Regular Files: Reading and Writing Non-Regular Files<2>.
22242 @node Stream Pointer Positioning<2>,Reading and Writing Non-Regular Files<2>,,Wide_Text_IO
22243 @anchor{gnat_rm/the_implementation_of_standard_i_o stream-pointer-positioning-1}@anchor{2b9}@anchor{gnat_rm/the_implementation_of_standard_i_o id14}@anchor{2ba}
22244 @subsection Stream Pointer Positioning
22247 @code{Ada.Wide_Text_IO} is similar to @code{Ada.Text_IO} in its handling
22248 of stream pointer positioning (@ref{2aa,,Text_IO}). There is one additional
22251 If @code{Ada.Wide_Text_IO.Look_Ahead} reads a character outside the
22252 normal lower ASCII set (i.e., a character in the range:
22255 Wide_Character'Val (16#0080#) .. Wide_Character'Val (16#FFFF#)
22258 then although the logical position of the file pointer is unchanged by
22259 the @code{Look_Ahead} call, the stream is physically positioned past the
22260 wide character sequence. Again this is to avoid the need for buffering
22261 or backup, and all @code{Wide_Text_IO} routines check the internal
22262 indication that this situation has occurred so that this is not visible
22263 to a normal program using @code{Wide_Text_IO}. However, this discrepancy
22264 can be observed if the wide text file shares a stream with another file.
22266 @node Reading and Writing Non-Regular Files<2>,,Stream Pointer Positioning<2>,Wide_Text_IO
22267 @anchor{gnat_rm/the_implementation_of_standard_i_o reading-and-writing-non-regular-files-1}@anchor{2bb}@anchor{gnat_rm/the_implementation_of_standard_i_o id15}@anchor{2bc}
22268 @subsection Reading and Writing Non-Regular Files
22271 As in the case of Text_IO, when a non-regular file is read, it is
22272 assumed that the file contains no page marks (any form characters are
22273 treated as data characters), and @code{End_Of_Page} always returns
22274 @code{False}. Similarly, the end of file indication is not sticky, so
22275 it is possible to read beyond an end of file.
22277 @node Wide_Wide_Text_IO,Stream_IO,Wide_Text_IO,The Implementation of Standard I/O
22278 @anchor{gnat_rm/the_implementation_of_standard_i_o id16}@anchor{2bd}@anchor{gnat_rm/the_implementation_of_standard_i_o wide-wide-text-io}@anchor{2be}
22279 @section Wide_Wide_Text_IO
22282 @code{Wide_Wide_Text_IO} is similar in most respects to Text_IO, except that
22283 both input and output files may contain special sequences that represent
22284 wide wide character values. The encoding scheme for a given file may be
22285 specified using a FORM parameter:
22291 as part of the FORM string (WCEM = wide character encoding method),
22292 where @code{x} is one of the following characters
22295 @multitable {xxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxx}
22318 Upper half encoding
22355 The encoding methods match those that
22356 can be used in a source
22357 program, but there is no requirement that the encoding method used for
22358 the source program be the same as the encoding method used for files,
22359 and different files may use different encoding methods.
22361 The default encoding method for the standard files, and for opened files
22362 for which no WCEM parameter is given in the FORM string matches the
22363 wide character encoding specified for the main program (the default
22364 being brackets encoding if no coding method was specified with -gnatW).
22369 @item @emph{UTF-8 Coding}
22371 A wide character is represented using
22372 UCS Transformation Format 8 (UTF-8) as defined in Annex R of ISO
22373 10646-1/Am.2. Depending on the character value, the representation
22374 is a one, two, three, or four byte sequence:
22378 16#000000#-16#00007f#: 2#0xxxxxxx#
22379 16#000080#-16#0007ff#: 2#110xxxxx# 2#10xxxxxx#
22380 16#000800#-16#00ffff#: 2#1110xxxx# 2#10xxxxxx# 2#10xxxxxx#
22381 16#010000#-16#10ffff#: 2#11110xxx# 2#10xxxxxx# 2#10xxxxxx# 2#10xxxxxx#
22387 where the @code{xxx} bits correspond to the left-padded bits of the
22388 21-bit character value. Note that all lower half ASCII characters
22389 are represented as ASCII bytes and all upper half characters and
22390 other wide characters are represented as sequences of upper-half
22397 @item @emph{Brackets Coding}
22399 In this encoding, a wide wide character is represented by the following eight
22400 character sequence if is in wide character range
22410 and by the following ten character sequence if not
22414 [ " a b c d e f " ]
22420 where @code{a}, @code{b}, @code{c}, @code{d}, @code{e}, and @code{f}
22421 are the four or six hexadecimal
22422 characters (using uppercase letters) of the wide wide character code. For
22423 example, @code{["01A345"]} is used to represent the wide wide character
22424 with code @code{16#01A345#}.
22426 This scheme is compatible with use of the full Wide_Wide_Character set.
22427 On input, brackets coding can also be used for upper half characters,
22428 e.g., @code{["C1"]} for lower case a. However, on output, brackets notation
22429 is only used for wide characters with a code greater than @code{16#FF#}.
22432 If is also possible to use the other Wide_Character encoding methods,
22433 such as Shift-JIS, but the other schemes cannot support the full range
22434 of wide wide characters.
22435 An attempt to output a character that cannot
22436 be represented using the encoding scheme for the file causes
22437 Constraint_Error to be raised. An invalid wide character sequence on
22438 input also causes Constraint_Error to be raised.
22441 * Stream Pointer Positioning: Stream Pointer Positioning<3>.
22442 * Reading and Writing Non-Regular Files: Reading and Writing Non-Regular Files<3>.
22446 @node Stream Pointer Positioning<3>,Reading and Writing Non-Regular Files<3>,,Wide_Wide_Text_IO
22447 @anchor{gnat_rm/the_implementation_of_standard_i_o stream-pointer-positioning-2}@anchor{2bf}@anchor{gnat_rm/the_implementation_of_standard_i_o id17}@anchor{2c0}
22448 @subsection Stream Pointer Positioning
22451 @code{Ada.Wide_Wide_Text_IO} is similar to @code{Ada.Text_IO} in its handling
22452 of stream pointer positioning (@ref{2aa,,Text_IO}). There is one additional
22455 If @code{Ada.Wide_Wide_Text_IO.Look_Ahead} reads a character outside the
22456 normal lower ASCII set (i.e., a character in the range:
22459 Wide_Wide_Character'Val (16#0080#) .. Wide_Wide_Character'Val (16#10FFFF#)
22462 then although the logical position of the file pointer is unchanged by
22463 the @code{Look_Ahead} call, the stream is physically positioned past the
22464 wide character sequence. Again this is to avoid the need for buffering
22465 or backup, and all @code{Wide_Wide_Text_IO} routines check the internal
22466 indication that this situation has occurred so that this is not visible
22467 to a normal program using @code{Wide_Wide_Text_IO}. However, this discrepancy
22468 can be observed if the wide text file shares a stream with another file.
22470 @node Reading and Writing Non-Regular Files<3>,,Stream Pointer Positioning<3>,Wide_Wide_Text_IO
22471 @anchor{gnat_rm/the_implementation_of_standard_i_o id18}@anchor{2c1}@anchor{gnat_rm/the_implementation_of_standard_i_o reading-and-writing-non-regular-files-2}@anchor{2c2}
22472 @subsection Reading and Writing Non-Regular Files
22475 As in the case of Text_IO, when a non-regular file is read, it is
22476 assumed that the file contains no page marks (any form characters are
22477 treated as data characters), and @code{End_Of_Page} always returns
22478 @code{False}. Similarly, the end of file indication is not sticky, so
22479 it is possible to read beyond an end of file.
22481 @node Stream_IO,Text Translation,Wide_Wide_Text_IO,The Implementation of Standard I/O
22482 @anchor{gnat_rm/the_implementation_of_standard_i_o id19}@anchor{2c3}@anchor{gnat_rm/the_implementation_of_standard_i_o stream-io}@anchor{2c4}
22486 A stream file is a sequence of bytes, where individual elements are
22487 written to the file as described in the Ada Reference Manual. The type
22488 @code{Stream_Element} is simply a byte. There are two ways to read or
22489 write a stream file.
22495 The operations @code{Read} and @code{Write} directly read or write a
22496 sequence of stream elements with no control information.
22499 The stream attributes applied to a stream file transfer data in the
22500 manner described for stream attributes.
22503 @node Text Translation,Shared Files,Stream_IO,The Implementation of Standard I/O
22504 @anchor{gnat_rm/the_implementation_of_standard_i_o id20}@anchor{2c5}@anchor{gnat_rm/the_implementation_of_standard_i_o text-translation}@anchor{2c6}
22505 @section Text Translation
22508 @code{Text_Translation=xxx} may be used as the Form parameter
22509 passed to Text_IO.Create and Text_IO.Open. @code{Text_Translation=xxx}
22510 has no effect on Unix systems. Possible values are:
22516 @code{Yes} or @code{Text} is the default, which means to
22517 translate LF to/from CR/LF on Windows systems.
22519 @code{No} disables this translation; i.e. it
22520 uses binary mode. For output files, @code{Text_Translation=No}
22521 may be used to create Unix-style files on
22525 @code{wtext} translation enabled in Unicode mode.
22526 (corresponds to _O_WTEXT).
22529 @code{u8text} translation enabled in Unicode UTF-8 mode.
22530 (corresponds to O_U8TEXT).
22533 @code{u16text} translation enabled in Unicode UTF-16
22534 mode. (corresponds to_O_U16TEXT).
22537 @node Shared Files,Filenames encoding,Text Translation,The Implementation of Standard I/O
22538 @anchor{gnat_rm/the_implementation_of_standard_i_o id21}@anchor{2c7}@anchor{gnat_rm/the_implementation_of_standard_i_o shared-files}@anchor{2c8}
22539 @section Shared Files
22542 Section A.14 of the Ada Reference Manual allows implementations to
22543 provide a wide variety of behavior if an attempt is made to access the
22544 same external file with two or more internal files.
22546 To provide a full range of functionality, while at the same time
22547 minimizing the problems of portability caused by this implementation
22548 dependence, GNAT handles file sharing as follows:
22554 In the absence of a @code{shared=xxx} form parameter, an attempt
22555 to open two or more files with the same full name is considered an error
22556 and is not supported. The exception @code{Use_Error} will be
22557 raised. Note that a file that is not explicitly closed by the program
22558 remains open until the program terminates.
22561 If the form parameter @code{shared=no} appears in the form string, the
22562 file can be opened or created with its own separate stream identifier,
22563 regardless of whether other files sharing the same external file are
22564 opened. The exact effect depends on how the C stream routines handle
22565 multiple accesses to the same external files using separate streams.
22568 If the form parameter @code{shared=yes} appears in the form string for
22569 each of two or more files opened using the same full name, the same
22570 stream is shared between these files, and the semantics are as described
22571 in Ada Reference Manual, Section A.14.
22574 When a program that opens multiple files with the same name is ported
22575 from another Ada compiler to GNAT, the effect will be that
22576 @code{Use_Error} is raised.
22578 The documentation of the original compiler and the documentation of the
22579 program should then be examined to determine if file sharing was
22580 expected, and @code{shared=xxx} parameters added to @code{Open}
22581 and @code{Create} calls as required.
22583 When a program is ported from GNAT to some other Ada compiler, no
22584 special attention is required unless the @code{shared=xxx} form
22585 parameter is used in the program. In this case, you must examine the
22586 documentation of the new compiler to see if it supports the required
22587 file sharing semantics, and form strings modified appropriately. Of
22588 course it may be the case that the program cannot be ported if the
22589 target compiler does not support the required functionality. The best
22590 approach in writing portable code is to avoid file sharing (and hence
22591 the use of the @code{shared=xxx} parameter in the form string)
22594 One common use of file sharing in Ada 83 is the use of instantiations of
22595 Sequential_IO on the same file with different types, to achieve
22596 heterogeneous input-output. Although this approach will work in GNAT if
22597 @code{shared=yes} is specified, it is preferable in Ada to use Stream_IO
22598 for this purpose (using the stream attributes)
22600 @node Filenames encoding,File content encoding,Shared Files,The Implementation of Standard I/O
22601 @anchor{gnat_rm/the_implementation_of_standard_i_o filenames-encoding}@anchor{2c9}@anchor{gnat_rm/the_implementation_of_standard_i_o id22}@anchor{2ca}
22602 @section Filenames encoding
22605 An encoding form parameter can be used to specify the filename
22606 encoding @code{encoding=xxx}.
22612 If the form parameter @code{encoding=utf8} appears in the form string, the
22613 filename must be encoded in UTF-8.
22616 If the form parameter @code{encoding=8bits} appears in the form
22617 string, the filename must be a standard 8bits string.
22620 In the absence of a @code{encoding=xxx} form parameter, the
22621 encoding is controlled by the @code{GNAT_CODE_PAGE} environment
22622 variable. And if not set @code{utf8} is assumed.
22627 @item @emph{CP_ACP}
22629 The current system Windows ANSI code page.
22631 @item @emph{CP_UTF8}
22636 This encoding form parameter is only supported on the Windows
22637 platform. On the other Operating Systems the run-time is supporting
22640 @node File content encoding,Open Modes,Filenames encoding,The Implementation of Standard I/O
22641 @anchor{gnat_rm/the_implementation_of_standard_i_o file-content-encoding}@anchor{2cb}@anchor{gnat_rm/the_implementation_of_standard_i_o id23}@anchor{2cc}
22642 @section File content encoding
22645 For text files it is possible to specify the encoding to use. This is
22646 controlled by the by the @code{GNAT_CCS_ENCODING} environment
22647 variable. And if not set @code{TEXT} is assumed.
22649 The possible values are those supported on Windows:
22656 Translated text mode
22660 Translated unicode encoding
22662 @item @emph{U16TEXT}
22664 Unicode 16-bit encoding
22666 @item @emph{U8TEXT}
22668 Unicode 8-bit encoding
22671 This encoding is only supported on the Windows platform.
22673 @node Open Modes,Operations on C Streams,File content encoding,The Implementation of Standard I/O
22674 @anchor{gnat_rm/the_implementation_of_standard_i_o open-modes}@anchor{2cd}@anchor{gnat_rm/the_implementation_of_standard_i_o id24}@anchor{2ce}
22675 @section Open Modes
22678 @code{Open} and @code{Create} calls result in a call to @code{fopen}
22679 using the mode shown in the following table:
22682 @multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxx}
22685 @code{Open} and @code{Create} Call Modes
22727 Out_File (Direct_IO)
22739 Out_File (all other cases)
22764 If text file translation is required, then either @code{b} or @code{t}
22765 is added to the mode, depending on the setting of Text. Text file
22766 translation refers to the mapping of CR/LF sequences in an external file
22767 to LF characters internally. This mapping only occurs in DOS and
22768 DOS-like systems, and is not relevant to other systems.
22770 A special case occurs with Stream_IO. As shown in the above table, the
22771 file is initially opened in @code{r} or @code{w} mode for the
22772 @code{In_File} and @code{Out_File} cases. If a @code{Set_Mode} operation
22773 subsequently requires switching from reading to writing or vice-versa,
22774 then the file is reopened in @code{r+} mode to permit the required operation.
22776 @node Operations on C Streams,Interfacing to C Streams,Open Modes,The Implementation of Standard I/O
22777 @anchor{gnat_rm/the_implementation_of_standard_i_o operations-on-c-streams}@anchor{2cf}@anchor{gnat_rm/the_implementation_of_standard_i_o id25}@anchor{2d0}
22778 @section Operations on C Streams
22781 The package @code{Interfaces.C_Streams} provides an Ada program with direct
22782 access to the C library functions for operations on C streams:
22785 package Interfaces.C_Streams is
22786 -- Note: the reason we do not use the types that are in
22787 -- Interfaces.C is that we want to avoid dragging in the
22788 -- code in this unit if possible.
22789 subtype chars is System.Address;
22790 -- Pointer to null-terminated array of characters
22791 subtype FILEs is System.Address;
22792 -- Corresponds to the C type FILE*
22793 subtype voids is System.Address;
22794 -- Corresponds to the C type void*
22795 subtype int is Integer;
22796 subtype long is Long_Integer;
22797 -- Note: the above types are subtypes deliberately, and it
22798 -- is part of this spec that the above correspondences are
22799 -- guaranteed. This means that it is legitimate to, for
22800 -- example, use Integer instead of int. We provide these
22801 -- synonyms for clarity, but in some cases it may be
22802 -- convenient to use the underlying types (for example to
22803 -- avoid an unnecessary dependency of a spec on the spec
22805 type size_t is mod 2 ** Standard'Address_Size;
22806 NULL_Stream : constant FILEs;
22807 -- Value returned (NULL in C) to indicate an
22808 -- fdopen/fopen/tmpfile error
22809 ----------------------------------
22810 -- Constants Defined in stdio.h --
22811 ----------------------------------
22812 EOF : constant int;
22813 -- Used by a number of routines to indicate error or
22815 IOFBF : constant int;
22816 IOLBF : constant int;
22817 IONBF : constant int;
22818 -- Used to indicate buffering mode for setvbuf call
22819 SEEK_CUR : constant int;
22820 SEEK_END : constant int;
22821 SEEK_SET : constant int;
22822 -- Used to indicate origin for fseek call
22823 function stdin return FILEs;
22824 function stdout return FILEs;
22825 function stderr return FILEs;
22826 -- Streams associated with standard files
22827 --------------------------
22828 -- Standard C functions --
22829 --------------------------
22830 -- The functions selected below are ones that are
22831 -- available in UNIX (but not necessarily in ANSI C).
22832 -- These are very thin interfaces
22833 -- which copy exactly the C headers. For more
22834 -- documentation on these functions, see the Microsoft C
22835 -- "Run-Time Library Reference" (Microsoft Press, 1990,
22836 -- ISBN 1-55615-225-6), which includes useful information
22837 -- on system compatibility.
22838 procedure clearerr (stream : FILEs);
22839 function fclose (stream : FILEs) return int;
22840 function fdopen (handle : int; mode : chars) return FILEs;
22841 function feof (stream : FILEs) return int;
22842 function ferror (stream : FILEs) return int;
22843 function fflush (stream : FILEs) return int;
22844 function fgetc (stream : FILEs) return int;
22845 function fgets (strng : chars; n : int; stream : FILEs)
22847 function fileno (stream : FILEs) return int;
22848 function fopen (filename : chars; Mode : chars)
22850 -- Note: to maintain target independence, use
22851 -- text_translation_required, a boolean variable defined in
22852 -- a-sysdep.c to deal with the target dependent text
22853 -- translation requirement. If this variable is set,
22854 -- then b/t should be appended to the standard mode
22855 -- argument to set the text translation mode off or on
22857 function fputc (C : int; stream : FILEs) return int;
22858 function fputs (Strng : chars; Stream : FILEs) return int;
22875 function ftell (stream : FILEs) return long;
22882 function isatty (handle : int) return int;
22883 procedure mktemp (template : chars);
22884 -- The return value (which is just a pointer to template)
22886 procedure rewind (stream : FILEs);
22887 function rmtmp return int;
22895 function tmpfile return FILEs;
22896 function ungetc (c : int; stream : FILEs) return int;
22897 function unlink (filename : chars) return int;
22898 ---------------------
22899 -- Extra functions --
22900 ---------------------
22901 -- These functions supply slightly thicker bindings than
22902 -- those above. They are derived from functions in the
22903 -- C Run-Time Library, but may do a bit more work than
22904 -- just directly calling one of the Library functions.
22905 function is_regular_file (handle : int) return int;
22906 -- Tests if given handle is for a regular file (result 1)
22907 -- or for a non-regular file (pipe or device, result 0).
22908 ---------------------------------
22909 -- Control of Text/Binary Mode --
22910 ---------------------------------
22911 -- If text_translation_required is true, then the following
22912 -- functions may be used to dynamically switch a file from
22913 -- binary to text mode or vice versa. These functions have
22914 -- no effect if text_translation_required is false (i.e., in
22915 -- normal UNIX mode). Use fileno to get a stream handle.
22916 procedure set_binary_mode (handle : int);
22917 procedure set_text_mode (handle : int);
22918 ----------------------------
22919 -- Full Path Name support --
22920 ----------------------------
22921 procedure full_name (nam : chars; buffer : chars);
22922 -- Given a NUL terminated string representing a file
22923 -- name, returns in buffer a NUL terminated string
22924 -- representing the full path name for the file name.
22925 -- On systems where it is relevant the drive is also
22926 -- part of the full path name. It is the responsibility
22927 -- of the caller to pass an actual parameter for buffer
22928 -- that is big enough for any full path name. Use
22929 -- max_path_len given below as the size of buffer.
22930 max_path_len : integer;
22931 -- Maximum length of an allowable full path name on the
22932 -- system, including a terminating NUL character.
22933 end Interfaces.C_Streams;
22936 @node Interfacing to C Streams,,Operations on C Streams,The Implementation of Standard I/O
22937 @anchor{gnat_rm/the_implementation_of_standard_i_o interfacing-to-c-streams}@anchor{2d1}@anchor{gnat_rm/the_implementation_of_standard_i_o id26}@anchor{2d2}
22938 @section Interfacing to C Streams
22941 The packages in this section permit interfacing Ada files to C Stream
22945 with Interfaces.C_Streams;
22946 package Ada.Sequential_IO.C_Streams is
22947 function C_Stream (F : File_Type)
22948 return Interfaces.C_Streams.FILEs;
22950 (File : in out File_Type;
22951 Mode : in File_Mode;
22952 C_Stream : in Interfaces.C_Streams.FILEs;
22953 Form : in String := "");
22954 end Ada.Sequential_IO.C_Streams;
22956 with Interfaces.C_Streams;
22957 package Ada.Direct_IO.C_Streams is
22958 function C_Stream (F : File_Type)
22959 return Interfaces.C_Streams.FILEs;
22961 (File : in out File_Type;
22962 Mode : in File_Mode;
22963 C_Stream : in Interfaces.C_Streams.FILEs;
22964 Form : in String := "");
22965 end Ada.Direct_IO.C_Streams;
22967 with Interfaces.C_Streams;
22968 package Ada.Text_IO.C_Streams is
22969 function C_Stream (F : File_Type)
22970 return Interfaces.C_Streams.FILEs;
22972 (File : in out File_Type;
22973 Mode : in File_Mode;
22974 C_Stream : in Interfaces.C_Streams.FILEs;
22975 Form : in String := "");
22976 end Ada.Text_IO.C_Streams;
22978 with Interfaces.C_Streams;
22979 package Ada.Wide_Text_IO.C_Streams is
22980 function C_Stream (F : File_Type)
22981 return Interfaces.C_Streams.FILEs;
22983 (File : in out File_Type;
22984 Mode : in File_Mode;
22985 C_Stream : in Interfaces.C_Streams.FILEs;
22986 Form : in String := "");
22987 end Ada.Wide_Text_IO.C_Streams;
22989 with Interfaces.C_Streams;
22990 package Ada.Wide_Wide_Text_IO.C_Streams is
22991 function C_Stream (F : File_Type)
22992 return Interfaces.C_Streams.FILEs;
22994 (File : in out File_Type;
22995 Mode : in File_Mode;
22996 C_Stream : in Interfaces.C_Streams.FILEs;
22997 Form : in String := "");
22998 end Ada.Wide_Wide_Text_IO.C_Streams;
23000 with Interfaces.C_Streams;
23001 package Ada.Stream_IO.C_Streams is
23002 function C_Stream (F : File_Type)
23003 return Interfaces.C_Streams.FILEs;
23005 (File : in out File_Type;
23006 Mode : in File_Mode;
23007 C_Stream : in Interfaces.C_Streams.FILEs;
23008 Form : in String := "");
23009 end Ada.Stream_IO.C_Streams;
23012 In each of these six packages, the @code{C_Stream} function obtains the
23013 @code{FILE} pointer from a currently opened Ada file. It is then
23014 possible to use the @code{Interfaces.C_Streams} package to operate on
23015 this stream, or the stream can be passed to a C program which can
23016 operate on it directly. Of course the program is responsible for
23017 ensuring that only appropriate sequences of operations are executed.
23019 One particular use of relevance to an Ada program is that the
23020 @code{setvbuf} function can be used to control the buffering of the
23021 stream used by an Ada file. In the absence of such a call the standard
23022 default buffering is used.
23024 The @code{Open} procedures in these packages open a file giving an
23025 existing C Stream instead of a file name. Typically this stream is
23026 imported from a C program, allowing an Ada file to operate on an
23029 @node The GNAT Library,Interfacing to Other Languages,The Implementation of Standard I/O,Top
23030 @anchor{gnat_rm/the_gnat_library the-gnat-library}@anchor{10}@anchor{gnat_rm/the_gnat_library doc}@anchor{2d3}@anchor{gnat_rm/the_gnat_library id1}@anchor{2d4}
23031 @chapter The GNAT Library
23034 The GNAT library contains a number of general and special purpose packages.
23035 It represents functionality that the GNAT developers have found useful, and
23036 which is made available to GNAT users. The packages described here are fully
23037 supported, and upwards compatibility will be maintained in future releases,
23038 so you can use these facilities with the confidence that the same functionality
23039 will be available in future releases.
23041 The chapter here simply gives a brief summary of the facilities available.
23042 The full documentation is found in the spec file for the package. The full
23043 sources of these library packages, including both spec and body, are provided
23044 with all GNAT releases. For example, to find out the full specifications of
23045 the SPITBOL pattern matching capability, including a full tutorial and
23046 extensive examples, look in the @code{g-spipat.ads} file in the library.
23048 For each entry here, the package name (as it would appear in a @code{with}
23049 clause) is given, followed by the name of the corresponding spec file in
23050 parentheses. The packages are children in four hierarchies, @code{Ada},
23051 @code{Interfaces}, @code{System}, and @code{GNAT}, the latter being a
23052 GNAT-specific hierarchy.
23054 Note that an application program should only use packages in one of these
23055 four hierarchies if the package is defined in the Ada Reference Manual,
23056 or is listed in this section of the GNAT Programmers Reference Manual.
23057 All other units should be considered internal implementation units and
23058 should not be directly @code{with}ed by application code. The use of
23059 a @code{with} clause that references one of these internal implementation
23060 units makes an application potentially dependent on changes in versions
23061 of GNAT, and will generate a warning message.
23064 * Ada.Characters.Latin_9 (a-chlat9.ads): Ada Characters Latin_9 a-chlat9 ads.
23065 * Ada.Characters.Wide_Latin_1 (a-cwila1.ads): Ada Characters Wide_Latin_1 a-cwila1 ads.
23066 * Ada.Characters.Wide_Latin_9 (a-cwila1.ads): Ada Characters Wide_Latin_9 a-cwila1 ads.
23067 * Ada.Characters.Wide_Wide_Latin_1 (a-chzla1.ads): Ada Characters Wide_Wide_Latin_1 a-chzla1 ads.
23068 * Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads): Ada Characters Wide_Wide_Latin_9 a-chzla9 ads.
23069 * Ada.Containers.Formal_Doubly_Linked_Lists (a-cfdlli.ads): Ada Containers Formal_Doubly_Linked_Lists a-cfdlli ads.
23070 * Ada.Containers.Formal_Hashed_Maps (a-cfhama.ads): Ada Containers Formal_Hashed_Maps a-cfhama ads.
23071 * Ada.Containers.Formal_Hashed_Sets (a-cfhase.ads): Ada Containers Formal_Hashed_Sets a-cfhase ads.
23072 * Ada.Containers.Formal_Ordered_Maps (a-cforma.ads): Ada Containers Formal_Ordered_Maps a-cforma ads.
23073 * Ada.Containers.Formal_Ordered_Sets (a-cforse.ads): Ada Containers Formal_Ordered_Sets a-cforse ads.
23074 * Ada.Containers.Formal_Vectors (a-cofove.ads): Ada Containers Formal_Vectors a-cofove ads.
23075 * Ada.Containers.Formal_Indefinite_Vectors (a-cfinve.ads): Ada Containers Formal_Indefinite_Vectors a-cfinve ads.
23076 * Ada.Containers.Functional_Vectors (a-cofuve.ads): Ada Containers Functional_Vectors a-cofuve ads.
23077 * Ada.Containers.Functional_Sets (a-cofuse.ads): Ada Containers Functional_Sets a-cofuse ads.
23078 * Ada.Containers.Functional_Maps (a-cofuma.ads): Ada Containers Functional_Maps a-cofuma ads.
23079 * Ada.Containers.Bounded_Holders (a-coboho.ads): Ada Containers Bounded_Holders a-coboho ads.
23080 * Ada.Command_Line.Environment (a-colien.ads): Ada Command_Line Environment a-colien ads.
23081 * Ada.Command_Line.Remove (a-colire.ads): Ada Command_Line Remove a-colire ads.
23082 * Ada.Command_Line.Response_File (a-clrefi.ads): Ada Command_Line Response_File a-clrefi ads.
23083 * Ada.Direct_IO.C_Streams (a-diocst.ads): Ada Direct_IO C_Streams a-diocst ads.
23084 * Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads): Ada Exceptions Is_Null_Occurrence a-einuoc ads.
23085 * Ada.Exceptions.Last_Chance_Handler (a-elchha.ads): Ada Exceptions Last_Chance_Handler a-elchha ads.
23086 * Ada.Exceptions.Traceback (a-exctra.ads): Ada Exceptions Traceback a-exctra ads.
23087 * Ada.Sequential_IO.C_Streams (a-siocst.ads): Ada Sequential_IO C_Streams a-siocst ads.
23088 * Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads): Ada Streams Stream_IO C_Streams a-ssicst ads.
23089 * Ada.Strings.Unbounded.Text_IO (a-suteio.ads): Ada Strings Unbounded Text_IO a-suteio ads.
23090 * Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads): Ada Strings Wide_Unbounded Wide_Text_IO a-swuwti ads.
23091 * Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads): Ada Strings Wide_Wide_Unbounded Wide_Wide_Text_IO a-szuzti ads.
23092 * Ada.Text_IO.C_Streams (a-tiocst.ads): Ada Text_IO C_Streams a-tiocst ads.
23093 * Ada.Text_IO.Reset_Standard_Files (a-tirsfi.ads): Ada Text_IO Reset_Standard_Files a-tirsfi ads.
23094 * Ada.Wide_Characters.Unicode (a-wichun.ads): Ada Wide_Characters Unicode a-wichun ads.
23095 * Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads): Ada Wide_Text_IO C_Streams a-wtcstr ads.
23096 * Ada.Wide_Text_IO.Reset_Standard_Files (a-wrstfi.ads): Ada Wide_Text_IO Reset_Standard_Files a-wrstfi ads.
23097 * Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads): Ada Wide_Wide_Characters Unicode a-zchuni ads.
23098 * Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads): Ada Wide_Wide_Text_IO C_Streams a-ztcstr ads.
23099 * Ada.Wide_Wide_Text_IO.Reset_Standard_Files (a-zrstfi.ads): Ada Wide_Wide_Text_IO Reset_Standard_Files a-zrstfi ads.
23100 * GNAT.Altivec (g-altive.ads): GNAT Altivec g-altive ads.
23101 * GNAT.Altivec.Conversions (g-altcon.ads): GNAT Altivec Conversions g-altcon ads.
23102 * GNAT.Altivec.Vector_Operations (g-alveop.ads): GNAT Altivec Vector_Operations g-alveop ads.
23103 * GNAT.Altivec.Vector_Types (g-alvety.ads): GNAT Altivec Vector_Types g-alvety ads.
23104 * GNAT.Altivec.Vector_Views (g-alvevi.ads): GNAT Altivec Vector_Views g-alvevi ads.
23105 * GNAT.Array_Split (g-arrspl.ads): GNAT Array_Split g-arrspl ads.
23106 * GNAT.AWK (g-awk.ads): GNAT AWK g-awk ads.
23107 * GNAT.Bind_Environment (g-binenv.ads): GNAT Bind_Environment g-binenv ads.
23108 * GNAT.Branch_Prediction (g-brapre.ads): GNAT Branch_Prediction g-brapre ads.
23109 * GNAT.Bounded_Buffers (g-boubuf.ads): GNAT Bounded_Buffers g-boubuf ads.
23110 * GNAT.Bounded_Mailboxes (g-boumai.ads): GNAT Bounded_Mailboxes g-boumai ads.
23111 * GNAT.Bubble_Sort (g-bubsor.ads): GNAT Bubble_Sort g-bubsor ads.
23112 * GNAT.Bubble_Sort_A (g-busora.ads): GNAT Bubble_Sort_A g-busora ads.
23113 * GNAT.Bubble_Sort_G (g-busorg.ads): GNAT Bubble_Sort_G g-busorg ads.
23114 * GNAT.Byte_Order_Mark (g-byorma.ads): GNAT Byte_Order_Mark g-byorma ads.
23115 * GNAT.Byte_Swapping (g-bytswa.ads): GNAT Byte_Swapping g-bytswa ads.
23116 * GNAT.Calendar (g-calend.ads): GNAT Calendar g-calend ads.
23117 * GNAT.Calendar.Time_IO (g-catiio.ads): GNAT Calendar Time_IO g-catiio ads.
23118 * GNAT.CRC32 (g-crc32.ads): GNAT CRC32 g-crc32 ads.
23119 * GNAT.Case_Util (g-casuti.ads): GNAT Case_Util g-casuti ads.
23120 * GNAT.CGI (g-cgi.ads): GNAT CGI g-cgi ads.
23121 * GNAT.CGI.Cookie (g-cgicoo.ads): GNAT CGI Cookie g-cgicoo ads.
23122 * GNAT.CGI.Debug (g-cgideb.ads): GNAT CGI Debug g-cgideb ads.
23123 * GNAT.Command_Line (g-comlin.ads): GNAT Command_Line g-comlin ads.
23124 * GNAT.Compiler_Version (g-comver.ads): GNAT Compiler_Version g-comver ads.
23125 * GNAT.Ctrl_C (g-ctrl_c.ads): GNAT Ctrl_C g-ctrl_c ads.
23126 * GNAT.Current_Exception (g-curexc.ads): GNAT Current_Exception g-curexc ads.
23127 * GNAT.Debug_Pools (g-debpoo.ads): GNAT Debug_Pools g-debpoo ads.
23128 * GNAT.Debug_Utilities (g-debuti.ads): GNAT Debug_Utilities g-debuti ads.
23129 * GNAT.Decode_String (g-decstr.ads): GNAT Decode_String g-decstr ads.
23130 * GNAT.Decode_UTF8_String (g-deutst.ads): GNAT Decode_UTF8_String g-deutst ads.
23131 * GNAT.Directory_Operations (g-dirope.ads): GNAT Directory_Operations g-dirope ads.
23132 * GNAT.Directory_Operations.Iteration (g-diopit.ads): GNAT Directory_Operations Iteration g-diopit ads.
23133 * GNAT.Dynamic_HTables (g-dynhta.ads): GNAT Dynamic_HTables g-dynhta ads.
23134 * GNAT.Dynamic_Tables (g-dyntab.ads): GNAT Dynamic_Tables g-dyntab ads.
23135 * GNAT.Encode_String (g-encstr.ads): GNAT Encode_String g-encstr ads.
23136 * GNAT.Encode_UTF8_String (g-enutst.ads): GNAT Encode_UTF8_String g-enutst ads.
23137 * GNAT.Exception_Actions (g-excact.ads): GNAT Exception_Actions g-excact ads.
23138 * GNAT.Exception_Traces (g-exctra.ads): GNAT Exception_Traces g-exctra ads.
23139 * GNAT.Exceptions (g-except.ads): GNAT Exceptions g-except ads.
23140 * GNAT.Expect (g-expect.ads): GNAT Expect g-expect ads.
23141 * GNAT.Expect.TTY (g-exptty.ads): GNAT Expect TTY g-exptty ads.
23142 * GNAT.Float_Control (g-flocon.ads): GNAT Float_Control g-flocon ads.
23143 * GNAT.Formatted_String (g-forstr.ads): GNAT Formatted_String g-forstr ads.
23144 * GNAT.Heap_Sort (g-heasor.ads): GNAT Heap_Sort g-heasor ads.
23145 * GNAT.Heap_Sort_A (g-hesora.ads): GNAT Heap_Sort_A g-hesora ads.
23146 * GNAT.Heap_Sort_G (g-hesorg.ads): GNAT Heap_Sort_G g-hesorg ads.
23147 * GNAT.HTable (g-htable.ads): GNAT HTable g-htable ads.
23148 * GNAT.IO (g-io.ads): GNAT IO g-io ads.
23149 * GNAT.IO_Aux (g-io_aux.ads): GNAT IO_Aux g-io_aux ads.
23150 * GNAT.Lock_Files (g-locfil.ads): GNAT Lock_Files g-locfil ads.
23151 * GNAT.MBBS_Discrete_Random (g-mbdira.ads): GNAT MBBS_Discrete_Random g-mbdira ads.
23152 * GNAT.MBBS_Float_Random (g-mbflra.ads): GNAT MBBS_Float_Random g-mbflra ads.
23153 * GNAT.MD5 (g-md5.ads): GNAT MD5 g-md5 ads.
23154 * GNAT.Memory_Dump (g-memdum.ads): GNAT Memory_Dump g-memdum ads.
23155 * GNAT.Most_Recent_Exception (g-moreex.ads): GNAT Most_Recent_Exception g-moreex ads.
23156 * GNAT.OS_Lib (g-os_lib.ads): GNAT OS_Lib g-os_lib ads.
23157 * GNAT.Perfect_Hash_Generators (g-pehage.ads): GNAT Perfect_Hash_Generators g-pehage ads.
23158 * GNAT.Random_Numbers (g-rannum.ads): GNAT Random_Numbers g-rannum ads.
23159 * GNAT.Regexp (g-regexp.ads): GNAT Regexp g-regexp ads.
23160 * GNAT.Registry (g-regist.ads): GNAT Registry g-regist ads.
23161 * GNAT.Regpat (g-regpat.ads): GNAT Regpat g-regpat ads.
23162 * GNAT.Rewrite_Data (g-rewdat.ads): GNAT Rewrite_Data g-rewdat ads.
23163 * GNAT.Secondary_Stack_Info (g-sestin.ads): GNAT Secondary_Stack_Info g-sestin ads.
23164 * GNAT.Semaphores (g-semaph.ads): GNAT Semaphores g-semaph ads.
23165 * GNAT.Serial_Communications (g-sercom.ads): GNAT Serial_Communications g-sercom ads.
23166 * GNAT.SHA1 (g-sha1.ads): GNAT SHA1 g-sha1 ads.
23167 * GNAT.SHA224 (g-sha224.ads): GNAT SHA224 g-sha224 ads.
23168 * GNAT.SHA256 (g-sha256.ads): GNAT SHA256 g-sha256 ads.
23169 * GNAT.SHA384 (g-sha384.ads): GNAT SHA384 g-sha384 ads.
23170 * GNAT.SHA512 (g-sha512.ads): GNAT SHA512 g-sha512 ads.
23171 * GNAT.Signals (g-signal.ads): GNAT Signals g-signal ads.
23172 * GNAT.Sockets (g-socket.ads): GNAT Sockets g-socket ads.
23173 * GNAT.Source_Info (g-souinf.ads): GNAT Source_Info g-souinf ads.
23174 * GNAT.Spelling_Checker (g-speche.ads): GNAT Spelling_Checker g-speche ads.
23175 * GNAT.Spelling_Checker_Generic (g-spchge.ads): GNAT Spelling_Checker_Generic g-spchge ads.
23176 * GNAT.Spitbol.Patterns (g-spipat.ads): GNAT Spitbol Patterns g-spipat ads.
23177 * GNAT.Spitbol (g-spitbo.ads): GNAT Spitbol g-spitbo ads.
23178 * GNAT.Spitbol.Table_Boolean (g-sptabo.ads): GNAT Spitbol Table_Boolean g-sptabo ads.
23179 * GNAT.Spitbol.Table_Integer (g-sptain.ads): GNAT Spitbol Table_Integer g-sptain ads.
23180 * GNAT.Spitbol.Table_VString (g-sptavs.ads): GNAT Spitbol Table_VString g-sptavs ads.
23181 * GNAT.SSE (g-sse.ads): GNAT SSE g-sse ads.
23182 * GNAT.SSE.Vector_Types (g-ssvety.ads): GNAT SSE Vector_Types g-ssvety ads.
23183 * GNAT.String_Hash (g-strhas.ads): GNAT String_Hash g-strhas ads.
23184 * GNAT.Strings (g-string.ads): GNAT Strings g-string ads.
23185 * GNAT.String_Split (g-strspl.ads): GNAT String_Split g-strspl ads.
23186 * GNAT.Table (g-table.ads): GNAT Table g-table ads.
23187 * GNAT.Task_Lock (g-tasloc.ads): GNAT Task_Lock g-tasloc ads.
23188 * GNAT.Time_Stamp (g-timsta.ads): GNAT Time_Stamp g-timsta ads.
23189 * GNAT.Threads (g-thread.ads): GNAT Threads g-thread ads.
23190 * GNAT.Traceback (g-traceb.ads): GNAT Traceback g-traceb ads.
23191 * GNAT.Traceback.Symbolic (g-trasym.ads): GNAT Traceback Symbolic g-trasym ads.
23192 * GNAT.UTF_32 (g-table.ads): GNAT UTF_32 g-table ads.
23193 * GNAT.Wide_Spelling_Checker (g-u3spch.ads): GNAT Wide_Spelling_Checker g-u3spch ads.
23194 * GNAT.Wide_Spelling_Checker (g-wispch.ads): GNAT Wide_Spelling_Checker g-wispch ads.
23195 * GNAT.Wide_String_Split (g-wistsp.ads): GNAT Wide_String_Split g-wistsp ads.
23196 * GNAT.Wide_Wide_Spelling_Checker (g-zspche.ads): GNAT Wide_Wide_Spelling_Checker g-zspche ads.
23197 * GNAT.Wide_Wide_String_Split (g-zistsp.ads): GNAT Wide_Wide_String_Split g-zistsp ads.
23198 * Interfaces.C.Extensions (i-cexten.ads): Interfaces C Extensions i-cexten ads.
23199 * Interfaces.C.Streams (i-cstrea.ads): Interfaces C Streams i-cstrea ads.
23200 * Interfaces.Packed_Decimal (i-pacdec.ads): Interfaces Packed_Decimal i-pacdec ads.
23201 * Interfaces.VxWorks (i-vxwork.ads): Interfaces VxWorks i-vxwork ads.
23202 * Interfaces.VxWorks.Int_Connection (i-vxinco.ads): Interfaces VxWorks Int_Connection i-vxinco ads.
23203 * Interfaces.VxWorks.IO (i-vxwoio.ads): Interfaces VxWorks IO i-vxwoio ads.
23204 * System.Address_Image (s-addima.ads): System Address_Image s-addima ads.
23205 * System.Assertions (s-assert.ads): System Assertions s-assert ads.
23206 * System.Atomic_Counters (s-atocou.ads): System Atomic_Counters s-atocou ads.
23207 * System.Memory (s-memory.ads): System Memory s-memory ads.
23208 * System.Multiprocessors (s-multip.ads): System Multiprocessors s-multip ads.
23209 * System.Multiprocessors.Dispatching_Domains (s-mudido.ads): System Multiprocessors Dispatching_Domains s-mudido ads.
23210 * System.Partition_Interface (s-parint.ads): System Partition_Interface s-parint ads.
23211 * System.Pool_Global (s-pooglo.ads): System Pool_Global s-pooglo ads.
23212 * System.Pool_Local (s-pooloc.ads): System Pool_Local s-pooloc ads.
23213 * System.Restrictions (s-restri.ads): System Restrictions s-restri ads.
23214 * System.Rident (s-rident.ads): System Rident s-rident ads.
23215 * System.Strings.Stream_Ops (s-ststop.ads): System Strings Stream_Ops s-ststop ads.
23216 * System.Unsigned_Types (s-unstyp.ads): System Unsigned_Types s-unstyp ads.
23217 * System.Wch_Cnv (s-wchcnv.ads): System Wch_Cnv s-wchcnv ads.
23218 * System.Wch_Con (s-wchcon.ads): System Wch_Con s-wchcon ads.
23222 @node Ada Characters Latin_9 a-chlat9 ads,Ada Characters Wide_Latin_1 a-cwila1 ads,,The GNAT Library
23223 @anchor{gnat_rm/the_gnat_library id2}@anchor{2d5}@anchor{gnat_rm/the_gnat_library ada-characters-latin-9-a-chlat9-ads}@anchor{2d6}
23224 @section @code{Ada.Characters.Latin_9} (@code{a-chlat9.ads})
23227 @geindex Ada.Characters.Latin_9 (a-chlat9.ads)
23229 @geindex Latin_9 constants for Character
23231 This child of @code{Ada.Characters}
23232 provides a set of definitions corresponding to those in the
23233 RM-defined package @code{Ada.Characters.Latin_1} but with the
23234 few modifications required for @code{Latin-9}
23235 The provision of such a package
23236 is specifically authorized by the Ada Reference Manual
23239 @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
23240 @anchor{gnat_rm/the_gnat_library ada-characters-wide-latin-1-a-cwila1-ads}@anchor{2d7}@anchor{gnat_rm/the_gnat_library id3}@anchor{2d8}
23241 @section @code{Ada.Characters.Wide_Latin_1} (@code{a-cwila1.ads})
23244 @geindex Ada.Characters.Wide_Latin_1 (a-cwila1.ads)
23246 @geindex Latin_1 constants for Wide_Character
23248 This child of @code{Ada.Characters}
23249 provides a set of definitions corresponding to those in the
23250 RM-defined package @code{Ada.Characters.Latin_1} but with the
23251 types of the constants being @code{Wide_Character}
23252 instead of @code{Character}. The provision of such a package
23253 is specifically authorized by the Ada Reference Manual
23256 @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
23257 @anchor{gnat_rm/the_gnat_library id4}@anchor{2d9}@anchor{gnat_rm/the_gnat_library ada-characters-wide-latin-9-a-cwila1-ads}@anchor{2da}
23258 @section @code{Ada.Characters.Wide_Latin_9} (@code{a-cwila1.ads})
23261 @geindex Ada.Characters.Wide_Latin_9 (a-cwila1.ads)
23263 @geindex Latin_9 constants for Wide_Character
23265 This child of @code{Ada.Characters}
23266 provides a set of definitions corresponding to those in the
23267 GNAT defined package @code{Ada.Characters.Latin_9} but with the
23268 types of the constants being @code{Wide_Character}
23269 instead of @code{Character}. The provision of such a package
23270 is specifically authorized by the Ada Reference Manual
23273 @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
23274 @anchor{gnat_rm/the_gnat_library ada-characters-wide-wide-latin-1-a-chzla1-ads}@anchor{2db}@anchor{gnat_rm/the_gnat_library id5}@anchor{2dc}
23275 @section @code{Ada.Characters.Wide_Wide_Latin_1} (@code{a-chzla1.ads})
23278 @geindex Ada.Characters.Wide_Wide_Latin_1 (a-chzla1.ads)
23280 @geindex Latin_1 constants for Wide_Wide_Character
23282 This child of @code{Ada.Characters}
23283 provides a set of definitions corresponding to those in the
23284 RM-defined package @code{Ada.Characters.Latin_1} but with the
23285 types of the constants being @code{Wide_Wide_Character}
23286 instead of @code{Character}. The provision of such a package
23287 is specifically authorized by the Ada Reference Manual
23290 @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
23291 @anchor{gnat_rm/the_gnat_library ada-characters-wide-wide-latin-9-a-chzla9-ads}@anchor{2dd}@anchor{gnat_rm/the_gnat_library id6}@anchor{2de}
23292 @section @code{Ada.Characters.Wide_Wide_Latin_9} (@code{a-chzla9.ads})
23295 @geindex Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads)
23297 @geindex Latin_9 constants for Wide_Wide_Character
23299 This child of @code{Ada.Characters}
23300 provides a set of definitions corresponding to those in the
23301 GNAT defined package @code{Ada.Characters.Latin_9} but with the
23302 types of the constants being @code{Wide_Wide_Character}
23303 instead of @code{Character}. The provision of such a package
23304 is specifically authorized by the Ada Reference Manual
23307 @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
23308 @anchor{gnat_rm/the_gnat_library id7}@anchor{2df}@anchor{gnat_rm/the_gnat_library ada-containers-formal-doubly-linked-lists-a-cfdlli-ads}@anchor{2e0}
23309 @section @code{Ada.Containers.Formal_Doubly_Linked_Lists} (@code{a-cfdlli.ads})
23312 @geindex Ada.Containers.Formal_Doubly_Linked_Lists (a-cfdlli.ads)
23314 @geindex Formal container for doubly linked lists
23316 This child of @code{Ada.Containers} defines a modified version of the
23317 Ada 2005 container for doubly linked lists, meant to facilitate formal
23318 verification of code using such containers. The specification of this
23319 unit is compatible with SPARK 2014.
23321 Note that although this container was designed with formal verification
23322 in mind, it may well be generally useful in that it is a simplified more
23323 efficient version than the one defined in the standard. In particular it
23324 does not have the complex overhead required to detect cursor tampering.
23326 @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
23327 @anchor{gnat_rm/the_gnat_library id8}@anchor{2e1}@anchor{gnat_rm/the_gnat_library ada-containers-formal-hashed-maps-a-cfhama-ads}@anchor{2e2}
23328 @section @code{Ada.Containers.Formal_Hashed_Maps} (@code{a-cfhama.ads})
23331 @geindex Ada.Containers.Formal_Hashed_Maps (a-cfhama.ads)
23333 @geindex Formal container for hashed maps
23335 This child of @code{Ada.Containers} defines a modified version of the
23336 Ada 2005 container for hashed maps, meant to facilitate formal
23337 verification of code using such containers. The specification of this
23338 unit is compatible with SPARK 2014.
23340 Note that although this container was designed with formal verification
23341 in mind, it may well be generally useful in that it is a simplified more
23342 efficient version than the one defined in the standard. In particular it
23343 does not have the complex overhead required to detect cursor tampering.
23345 @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
23346 @anchor{gnat_rm/the_gnat_library id9}@anchor{2e3}@anchor{gnat_rm/the_gnat_library ada-containers-formal-hashed-sets-a-cfhase-ads}@anchor{2e4}
23347 @section @code{Ada.Containers.Formal_Hashed_Sets} (@code{a-cfhase.ads})
23350 @geindex Ada.Containers.Formal_Hashed_Sets (a-cfhase.ads)
23352 @geindex Formal container for hashed sets
23354 This child of @code{Ada.Containers} defines a modified version of the
23355 Ada 2005 container for hashed sets, meant to facilitate formal
23356 verification of code using such containers. The specification of this
23357 unit is compatible with SPARK 2014.
23359 Note that although this container was designed with formal verification
23360 in mind, it may well be generally useful in that it is a simplified more
23361 efficient version than the one defined in the standard. In particular it
23362 does not have the complex overhead required to detect cursor tampering.
23364 @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
23365 @anchor{gnat_rm/the_gnat_library id10}@anchor{2e5}@anchor{gnat_rm/the_gnat_library ada-containers-formal-ordered-maps-a-cforma-ads}@anchor{2e6}
23366 @section @code{Ada.Containers.Formal_Ordered_Maps} (@code{a-cforma.ads})
23369 @geindex Ada.Containers.Formal_Ordered_Maps (a-cforma.ads)
23371 @geindex Formal container for ordered maps
23373 This child of @code{Ada.Containers} defines a modified version of the
23374 Ada 2005 container for ordered maps, meant to facilitate formal
23375 verification of code using such containers. The specification of this
23376 unit is compatible with SPARK 2014.
23378 Note that although this container was designed with formal verification
23379 in mind, it may well be generally useful in that it is a simplified more
23380 efficient version than the one defined in the standard. In particular it
23381 does not have the complex overhead required to detect cursor tampering.
23383 @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
23384 @anchor{gnat_rm/the_gnat_library ada-containers-formal-ordered-sets-a-cforse-ads}@anchor{2e7}@anchor{gnat_rm/the_gnat_library id11}@anchor{2e8}
23385 @section @code{Ada.Containers.Formal_Ordered_Sets} (@code{a-cforse.ads})
23388 @geindex Ada.Containers.Formal_Ordered_Sets (a-cforse.ads)
23390 @geindex Formal container for ordered sets
23392 This child of @code{Ada.Containers} defines a modified version of the
23393 Ada 2005 container for ordered sets, meant to facilitate formal
23394 verification of code using such containers. The specification of this
23395 unit is compatible with SPARK 2014.
23397 Note that although this container was designed with formal verification
23398 in mind, it may well be generally useful in that it is a simplified more
23399 efficient version than the one defined in the standard. In particular it
23400 does not have the complex overhead required to detect cursor tampering.
23402 @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
23403 @anchor{gnat_rm/the_gnat_library id12}@anchor{2e9}@anchor{gnat_rm/the_gnat_library ada-containers-formal-vectors-a-cofove-ads}@anchor{2ea}
23404 @section @code{Ada.Containers.Formal_Vectors} (@code{a-cofove.ads})
23407 @geindex Ada.Containers.Formal_Vectors (a-cofove.ads)
23409 @geindex Formal container for vectors
23411 This child of @code{Ada.Containers} defines a modified version of the
23412 Ada 2005 container for vectors, meant to facilitate formal
23413 verification of code using such containers. The specification of this
23414 unit is compatible with SPARK 2014.
23416 Note that although this container was designed with formal verification
23417 in mind, it may well be generally useful in that it is a simplified more
23418 efficient version than the one defined in the standard. In particular it
23419 does not have the complex overhead required to detect cursor tampering.
23421 @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
23422 @anchor{gnat_rm/the_gnat_library id13}@anchor{2eb}@anchor{gnat_rm/the_gnat_library ada-containers-formal-indefinite-vectors-a-cfinve-ads}@anchor{2ec}
23423 @section @code{Ada.Containers.Formal_Indefinite_Vectors} (@code{a-cfinve.ads})
23426 @geindex Ada.Containers.Formal_Indefinite_Vectors (a-cfinve.ads)
23428 @geindex Formal container for vectors
23430 This child of @code{Ada.Containers} defines a modified version of the
23431 Ada 2005 container for vectors of indefinite elements, meant to
23432 facilitate formal verification of code using such containers. The
23433 specification of this unit is compatible with SPARK 2014.
23435 Note that although this container was designed with formal verification
23436 in mind, it may well be generally useful in that it is a simplified more
23437 efficient version than the one defined in the standard. In particular it
23438 does not have the complex overhead required to detect cursor tampering.
23440 @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
23441 @anchor{gnat_rm/the_gnat_library id14}@anchor{2ed}@anchor{gnat_rm/the_gnat_library ada-containers-functional-vectors-a-cofuve-ads}@anchor{2ee}
23442 @section @code{Ada.Containers.Functional_Vectors} (@code{a-cofuve.ads})
23445 @geindex Ada.Containers.Functional_Vectors (a-cofuve.ads)
23447 @geindex Functional vectors
23449 This child of @code{Ada.Containers} defines immutable vectors. These
23450 containers are unbounded and may contain indefinite elements. Furthermore, to
23451 be usable in every context, they are neither controlled nor limited. As they
23452 are functional, that is, no primitives are provided which would allow modifying
23453 an existing container, these containers can still be used safely.
23455 Their API features functions creating new containers from existing ones.
23456 As a consequence, these containers are highly inefficient. They are also
23457 memory consuming, as the allocated memory is not reclaimed when the container
23458 is no longer referenced. Thus, they should in general be used in ghost code
23459 and annotations, so that they can be removed from the final executable. The
23460 specification of this unit is compatible with SPARK 2014.
23462 @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
23463 @anchor{gnat_rm/the_gnat_library ada-containers-functional-sets-a-cofuse-ads}@anchor{2ef}@anchor{gnat_rm/the_gnat_library id15}@anchor{2f0}
23464 @section @code{Ada.Containers.Functional_Sets} (@code{a-cofuse.ads})
23467 @geindex Ada.Containers.Functional_Sets (a-cofuse.ads)
23469 @geindex Functional sets
23471 This child of @code{Ada.Containers} defines immutable sets. These containers are
23472 unbounded and may contain indefinite elements. Furthermore, to be usable in
23473 every context, they are neither controlled nor limited. As they are functional,
23474 that is, no primitives are provided which would allow modifying an existing
23475 container, these containers can still be used safely.
23477 Their API features functions creating new containers from existing ones.
23478 As a consequence, these containers are highly inefficient. They are also
23479 memory consuming, as the allocated memory is not reclaimed when the container
23480 is no longer referenced. Thus, they should in general be used in ghost code
23481 and annotations, so that they can be removed from the final executable. The
23482 specification of this unit is compatible with SPARK 2014.
23484 @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
23485 @anchor{gnat_rm/the_gnat_library id16}@anchor{2f1}@anchor{gnat_rm/the_gnat_library ada-containers-functional-maps-a-cofuma-ads}@anchor{2f2}
23486 @section @code{Ada.Containers.Functional_Maps} (@code{a-cofuma.ads})
23489 @geindex Ada.Containers.Functional_Maps (a-cofuma.ads)
23491 @geindex Functional maps
23493 This child of @code{Ada.Containers} defines immutable maps. These containers are
23494 unbounded and may contain indefinite elements. Furthermore, to be usable in
23495 every context, they are neither controlled nor limited. As they are functional,
23496 that is, no primitives are provided which would allow modifying an existing
23497 container, these containers can still be used safely.
23499 Their API features functions creating new containers from existing ones.
23500 As a consequence, these containers are highly inefficient. They are also
23501 memory consuming, as the allocated memory is not reclaimed when the container
23502 is no longer referenced. Thus, they should in general be used in ghost code
23503 and annotations, so that they can be removed from the final executable. The
23504 specification of this unit is compatible with SPARK 2014.
23506 @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
23507 @anchor{gnat_rm/the_gnat_library ada-containers-bounded-holders-a-coboho-ads}@anchor{2f3}@anchor{gnat_rm/the_gnat_library id17}@anchor{2f4}
23508 @section @code{Ada.Containers.Bounded_Holders} (@code{a-coboho.ads})
23511 @geindex Ada.Containers.Bounded_Holders (a-coboho.ads)
23513 @geindex Formal container for vectors
23515 This child of @code{Ada.Containers} defines a modified version of
23516 Indefinite_Holders that avoids heap allocation.
23518 @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
23519 @anchor{gnat_rm/the_gnat_library ada-command-line-environment-a-colien-ads}@anchor{2f5}@anchor{gnat_rm/the_gnat_library id18}@anchor{2f6}
23520 @section @code{Ada.Command_Line.Environment} (@code{a-colien.ads})
23523 @geindex Ada.Command_Line.Environment (a-colien.ads)
23525 @geindex Environment entries
23527 This child of @code{Ada.Command_Line}
23528 provides a mechanism for obtaining environment values on systems
23529 where this concept makes sense.
23531 @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
23532 @anchor{gnat_rm/the_gnat_library id19}@anchor{2f7}@anchor{gnat_rm/the_gnat_library ada-command-line-remove-a-colire-ads}@anchor{2f8}
23533 @section @code{Ada.Command_Line.Remove} (@code{a-colire.ads})
23536 @geindex Ada.Command_Line.Remove (a-colire.ads)
23538 @geindex Removing command line arguments
23540 @geindex Command line
23541 @geindex argument removal
23543 This child of @code{Ada.Command_Line}
23544 provides a mechanism for logically removing
23545 arguments from the argument list. Once removed, an argument is not visible
23546 to further calls on the subprograms in @code{Ada.Command_Line} will not
23547 see the removed argument.
23549 @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
23550 @anchor{gnat_rm/the_gnat_library id20}@anchor{2f9}@anchor{gnat_rm/the_gnat_library ada-command-line-response-file-a-clrefi-ads}@anchor{2fa}
23551 @section @code{Ada.Command_Line.Response_File} (@code{a-clrefi.ads})
23554 @geindex Ada.Command_Line.Response_File (a-clrefi.ads)
23556 @geindex Response file for command line
23558 @geindex Command line
23559 @geindex response file
23561 @geindex Command line
23562 @geindex handling long command lines
23564 This child of @code{Ada.Command_Line} provides a mechanism facilities for
23565 getting command line arguments from a text file, called a "response file".
23566 Using a response file allow passing a set of arguments to an executable longer
23567 than the maximum allowed by the system on the command line.
23569 @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
23570 @anchor{gnat_rm/the_gnat_library id21}@anchor{2fb}@anchor{gnat_rm/the_gnat_library ada-direct-io-c-streams-a-diocst-ads}@anchor{2fc}
23571 @section @code{Ada.Direct_IO.C_Streams} (@code{a-diocst.ads})
23574 @geindex Ada.Direct_IO.C_Streams (a-diocst.ads)
23577 @geindex Interfacing with Direct_IO
23579 This package provides subprograms that allow interfacing between
23580 C streams and @code{Direct_IO}. The stream identifier can be
23581 extracted from a file opened on the Ada side, and an Ada file
23582 can be constructed from a stream opened on the C side.
23584 @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
23585 @anchor{gnat_rm/the_gnat_library id22}@anchor{2fd}@anchor{gnat_rm/the_gnat_library ada-exceptions-is-null-occurrence-a-einuoc-ads}@anchor{2fe}
23586 @section @code{Ada.Exceptions.Is_Null_Occurrence} (@code{a-einuoc.ads})
23589 @geindex Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads)
23591 @geindex Null_Occurrence
23592 @geindex testing for
23594 This child subprogram provides a way of testing for the null
23595 exception occurrence (@code{Null_Occurrence}) without raising
23598 @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
23599 @anchor{gnat_rm/the_gnat_library id23}@anchor{2ff}@anchor{gnat_rm/the_gnat_library ada-exceptions-last-chance-handler-a-elchha-ads}@anchor{300}
23600 @section @code{Ada.Exceptions.Last_Chance_Handler} (@code{a-elchha.ads})
23603 @geindex Ada.Exceptions.Last_Chance_Handler (a-elchha.ads)
23605 @geindex Null_Occurrence
23606 @geindex testing for
23608 This child subprogram is used for handling otherwise unhandled
23609 exceptions (hence the name last chance), and perform clean ups before
23610 terminating the program. Note that this subprogram never returns.
23612 @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
23613 @anchor{gnat_rm/the_gnat_library ada-exceptions-traceback-a-exctra-ads}@anchor{301}@anchor{gnat_rm/the_gnat_library id24}@anchor{302}
23614 @section @code{Ada.Exceptions.Traceback} (@code{a-exctra.ads})
23617 @geindex Ada.Exceptions.Traceback (a-exctra.ads)
23619 @geindex Traceback for Exception Occurrence
23621 This child package provides the subprogram (@code{Tracebacks}) to
23622 give a traceback array of addresses based on an exception
23625 @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
23626 @anchor{gnat_rm/the_gnat_library ada-sequential-io-c-streams-a-siocst-ads}@anchor{303}@anchor{gnat_rm/the_gnat_library id25}@anchor{304}
23627 @section @code{Ada.Sequential_IO.C_Streams} (@code{a-siocst.ads})
23630 @geindex Ada.Sequential_IO.C_Streams (a-siocst.ads)
23633 @geindex Interfacing with Sequential_IO
23635 This package provides subprograms that allow interfacing between
23636 C streams and @code{Sequential_IO}. The stream identifier can be
23637 extracted from a file opened on the Ada side, and an Ada file
23638 can be constructed from a stream opened on the C side.
23640 @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
23641 @anchor{gnat_rm/the_gnat_library id26}@anchor{305}@anchor{gnat_rm/the_gnat_library ada-streams-stream-io-c-streams-a-ssicst-ads}@anchor{306}
23642 @section @code{Ada.Streams.Stream_IO.C_Streams} (@code{a-ssicst.ads})
23645 @geindex Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads)
23648 @geindex Interfacing with Stream_IO
23650 This package provides subprograms that allow interfacing between
23651 C streams and @code{Stream_IO}. The stream identifier can be
23652 extracted from a file opened on the Ada side, and an Ada file
23653 can be constructed from a stream opened on the C side.
23655 @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
23656 @anchor{gnat_rm/the_gnat_library ada-strings-unbounded-text-io-a-suteio-ads}@anchor{307}@anchor{gnat_rm/the_gnat_library id27}@anchor{308}
23657 @section @code{Ada.Strings.Unbounded.Text_IO} (@code{a-suteio.ads})
23660 @geindex Ada.Strings.Unbounded.Text_IO (a-suteio.ads)
23662 @geindex Unbounded_String
23663 @geindex IO support
23666 @geindex extensions for unbounded strings
23668 This package provides subprograms for Text_IO for unbounded
23669 strings, avoiding the necessity for an intermediate operation
23670 with ordinary strings.
23672 @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
23673 @anchor{gnat_rm/the_gnat_library id28}@anchor{309}@anchor{gnat_rm/the_gnat_library ada-strings-wide-unbounded-wide-text-io-a-swuwti-ads}@anchor{30a}
23674 @section @code{Ada.Strings.Wide_Unbounded.Wide_Text_IO} (@code{a-swuwti.ads})
23677 @geindex Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads)
23679 @geindex Unbounded_Wide_String
23680 @geindex IO support
23683 @geindex extensions for unbounded wide strings
23685 This package provides subprograms for Text_IO for unbounded
23686 wide strings, avoiding the necessity for an intermediate operation
23687 with ordinary wide strings.
23689 @node Ada Strings Wide_Wide_Unbounded Wide_Wide_Text_IO a-szuzti ads,Ada Text_IO C_Streams a-tiocst ads,Ada Strings Wide_Unbounded Wide_Text_IO a-swuwti ads,The GNAT Library
23690 @anchor{gnat_rm/the_gnat_library id29}@anchor{30b}@anchor{gnat_rm/the_gnat_library ada-strings-wide-wide-unbounded-wide-wide-text-io-a-szuzti-ads}@anchor{30c}
23691 @section @code{Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO} (@code{a-szuzti.ads})
23694 @geindex Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads)
23696 @geindex Unbounded_Wide_Wide_String
23697 @geindex IO support
23700 @geindex extensions for unbounded wide wide strings
23702 This package provides subprograms for Text_IO for unbounded
23703 wide wide strings, avoiding the necessity for an intermediate operation
23704 with ordinary wide wide strings.
23706 @node Ada Text_IO C_Streams a-tiocst ads,Ada Text_IO Reset_Standard_Files a-tirsfi ads,Ada Strings Wide_Wide_Unbounded Wide_Wide_Text_IO a-szuzti ads,The GNAT Library
23707 @anchor{gnat_rm/the_gnat_library ada-text-io-c-streams-a-tiocst-ads}@anchor{30d}@anchor{gnat_rm/the_gnat_library id30}@anchor{30e}
23708 @section @code{Ada.Text_IO.C_Streams} (@code{a-tiocst.ads})
23711 @geindex Ada.Text_IO.C_Streams (a-tiocst.ads)
23714 @geindex Interfacing with `@w{`}Text_IO`@w{`}
23716 This package provides subprograms that allow interfacing between
23717 C streams and @code{Text_IO}. The stream identifier can be
23718 extracted from a file opened on the Ada side, and an Ada file
23719 can be constructed from a stream opened on the C side.
23721 @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
23722 @anchor{gnat_rm/the_gnat_library ada-text-io-reset-standard-files-a-tirsfi-ads}@anchor{30f}@anchor{gnat_rm/the_gnat_library id31}@anchor{310}
23723 @section @code{Ada.Text_IO.Reset_Standard_Files} (@code{a-tirsfi.ads})
23726 @geindex Ada.Text_IO.Reset_Standard_Files (a-tirsfi.ads)
23728 @geindex Text_IO resetting standard files
23730 This procedure is used to reset the status of the standard files used
23731 by Ada.Text_IO. This is useful in a situation (such as a restart in an
23732 embedded application) where the status of the files may change during
23733 execution (for example a standard input file may be redefined to be
23736 @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
23737 @anchor{gnat_rm/the_gnat_library id32}@anchor{311}@anchor{gnat_rm/the_gnat_library ada-wide-characters-unicode-a-wichun-ads}@anchor{312}
23738 @section @code{Ada.Wide_Characters.Unicode} (@code{a-wichun.ads})
23741 @geindex Ada.Wide_Characters.Unicode (a-wichun.ads)
23743 @geindex Unicode categorization
23744 @geindex Wide_Character
23746 This package provides subprograms that allow categorization of
23747 Wide_Character values according to Unicode categories.
23749 @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
23750 @anchor{gnat_rm/the_gnat_library ada-wide-text-io-c-streams-a-wtcstr-ads}@anchor{313}@anchor{gnat_rm/the_gnat_library id33}@anchor{314}
23751 @section @code{Ada.Wide_Text_IO.C_Streams} (@code{a-wtcstr.ads})
23754 @geindex Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads)
23757 @geindex Interfacing with `@w{`}Wide_Text_IO`@w{`}
23759 This package provides subprograms that allow interfacing between
23760 C streams and @code{Wide_Text_IO}. The stream identifier can be
23761 extracted from a file opened on the Ada side, and an Ada file
23762 can be constructed from a stream opened on the C side.
23764 @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
23765 @anchor{gnat_rm/the_gnat_library ada-wide-text-io-reset-standard-files-a-wrstfi-ads}@anchor{315}@anchor{gnat_rm/the_gnat_library id34}@anchor{316}
23766 @section @code{Ada.Wide_Text_IO.Reset_Standard_Files} (@code{a-wrstfi.ads})
23769 @geindex Ada.Wide_Text_IO.Reset_Standard_Files (a-wrstfi.ads)
23771 @geindex Wide_Text_IO resetting standard files
23773 This procedure is used to reset the status of the standard files used
23774 by Ada.Wide_Text_IO. This is useful in a situation (such as a restart in an
23775 embedded application) where the status of the files may change during
23776 execution (for example a standard input file may be redefined to be
23779 @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
23780 @anchor{gnat_rm/the_gnat_library id35}@anchor{317}@anchor{gnat_rm/the_gnat_library ada-wide-wide-characters-unicode-a-zchuni-ads}@anchor{318}
23781 @section @code{Ada.Wide_Wide_Characters.Unicode} (@code{a-zchuni.ads})
23784 @geindex Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads)
23786 @geindex Unicode categorization
23787 @geindex Wide_Wide_Character
23789 This package provides subprograms that allow categorization of
23790 Wide_Wide_Character values according to Unicode categories.
23792 @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
23793 @anchor{gnat_rm/the_gnat_library id36}@anchor{319}@anchor{gnat_rm/the_gnat_library ada-wide-wide-text-io-c-streams-a-ztcstr-ads}@anchor{31a}
23794 @section @code{Ada.Wide_Wide_Text_IO.C_Streams} (@code{a-ztcstr.ads})
23797 @geindex Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads)
23800 @geindex Interfacing with `@w{`}Wide_Wide_Text_IO`@w{`}
23802 This package provides subprograms that allow interfacing between
23803 C streams and @code{Wide_Wide_Text_IO}. The stream identifier can be
23804 extracted from a file opened on the Ada side, and an Ada file
23805 can be constructed from a stream opened on the C side.
23807 @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
23808 @anchor{gnat_rm/the_gnat_library id37}@anchor{31b}@anchor{gnat_rm/the_gnat_library ada-wide-wide-text-io-reset-standard-files-a-zrstfi-ads}@anchor{31c}
23809 @section @code{Ada.Wide_Wide_Text_IO.Reset_Standard_Files} (@code{a-zrstfi.ads})
23812 @geindex Ada.Wide_Wide_Text_IO.Reset_Standard_Files (a-zrstfi.ads)
23814 @geindex Wide_Wide_Text_IO resetting standard files
23816 This procedure is used to reset the status of the standard files used
23817 by Ada.Wide_Wide_Text_IO. This is useful in a situation (such as a
23818 restart in an embedded application) where the status of the files may
23819 change during execution (for example a standard input file may be
23820 redefined to be interactive).
23822 @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
23823 @anchor{gnat_rm/the_gnat_library gnat-altivec-g-altive-ads}@anchor{31d}@anchor{gnat_rm/the_gnat_library id38}@anchor{31e}
23824 @section @code{GNAT.Altivec} (@code{g-altive.ads})
23827 @geindex GNAT.Altivec (g-altive.ads)
23831 This is the root package of the GNAT AltiVec binding. It provides
23832 definitions of constants and types common to all the versions of the
23835 @node GNAT Altivec Conversions g-altcon ads,GNAT Altivec Vector_Operations g-alveop ads,GNAT Altivec g-altive ads,The GNAT Library
23836 @anchor{gnat_rm/the_gnat_library gnat-altivec-conversions-g-altcon-ads}@anchor{31f}@anchor{gnat_rm/the_gnat_library id39}@anchor{320}
23837 @section @code{GNAT.Altivec.Conversions} (@code{g-altcon.ads})
23840 @geindex GNAT.Altivec.Conversions (g-altcon.ads)
23844 This package provides the Vector/View conversion routines.
23846 @node GNAT Altivec Vector_Operations g-alveop ads,GNAT Altivec Vector_Types g-alvety ads,GNAT Altivec Conversions g-altcon ads,The GNAT Library
23847 @anchor{gnat_rm/the_gnat_library gnat-altivec-vector-operations-g-alveop-ads}@anchor{321}@anchor{gnat_rm/the_gnat_library id40}@anchor{322}
23848 @section @code{GNAT.Altivec.Vector_Operations} (@code{g-alveop.ads})
23851 @geindex GNAT.Altivec.Vector_Operations (g-alveop.ads)
23855 This package exposes the Ada interface to the AltiVec operations on
23856 vector objects. A soft emulation is included by default in the GNAT
23857 library. The hard binding is provided as a separate package. This unit
23858 is common to both bindings.
23860 @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
23861 @anchor{gnat_rm/the_gnat_library gnat-altivec-vector-types-g-alvety-ads}@anchor{323}@anchor{gnat_rm/the_gnat_library id41}@anchor{324}
23862 @section @code{GNAT.Altivec.Vector_Types} (@code{g-alvety.ads})
23865 @geindex GNAT.Altivec.Vector_Types (g-alvety.ads)
23869 This package exposes the various vector types part of the Ada binding
23870 to AltiVec facilities.
23872 @node GNAT Altivec Vector_Views g-alvevi ads,GNAT Array_Split g-arrspl ads,GNAT Altivec Vector_Types g-alvety ads,The GNAT Library
23873 @anchor{gnat_rm/the_gnat_library gnat-altivec-vector-views-g-alvevi-ads}@anchor{325}@anchor{gnat_rm/the_gnat_library id42}@anchor{326}
23874 @section @code{GNAT.Altivec.Vector_Views} (@code{g-alvevi.ads})
23877 @geindex GNAT.Altivec.Vector_Views (g-alvevi.ads)
23881 This package provides public 'View' data types from/to which private
23882 vector representations can be converted via
23883 GNAT.Altivec.Conversions. This allows convenient access to individual
23884 vector elements and provides a simple way to initialize vector
23887 @node GNAT Array_Split g-arrspl ads,GNAT AWK g-awk ads,GNAT Altivec Vector_Views g-alvevi ads,The GNAT Library
23888 @anchor{gnat_rm/the_gnat_library gnat-array-split-g-arrspl-ads}@anchor{327}@anchor{gnat_rm/the_gnat_library id43}@anchor{328}
23889 @section @code{GNAT.Array_Split} (@code{g-arrspl.ads})
23892 @geindex GNAT.Array_Split (g-arrspl.ads)
23894 @geindex Array splitter
23896 Useful array-manipulation routines: given a set of separators, split
23897 an array wherever the separators appear, and provide direct access
23898 to the resulting slices.
23900 @node GNAT AWK g-awk ads,GNAT Bind_Environment g-binenv ads,GNAT Array_Split g-arrspl ads,The GNAT Library
23901 @anchor{gnat_rm/the_gnat_library id44}@anchor{329}@anchor{gnat_rm/the_gnat_library gnat-awk-g-awk-ads}@anchor{32a}
23902 @section @code{GNAT.AWK} (@code{g-awk.ads})
23905 @geindex GNAT.AWK (g-awk.ads)
23911 Provides AWK-like parsing functions, with an easy interface for parsing one
23912 or more files containing formatted data. The file is viewed as a database
23913 where each record is a line and a field is a data element in this line.
23915 @node GNAT Bind_Environment g-binenv ads,GNAT Branch_Prediction g-brapre ads,GNAT AWK g-awk ads,The GNAT Library
23916 @anchor{gnat_rm/the_gnat_library gnat-bind-environment-g-binenv-ads}@anchor{32b}@anchor{gnat_rm/the_gnat_library id45}@anchor{32c}
23917 @section @code{GNAT.Bind_Environment} (@code{g-binenv.ads})
23920 @geindex GNAT.Bind_Environment (g-binenv.ads)
23922 @geindex Bind environment
23924 Provides access to key=value associations captured at bind time.
23925 These associations can be specified using the @code{-V} binder command
23928 @node GNAT Branch_Prediction g-brapre ads,GNAT Bounded_Buffers g-boubuf ads,GNAT Bind_Environment g-binenv ads,The GNAT Library
23929 @anchor{gnat_rm/the_gnat_library id46}@anchor{32d}@anchor{gnat_rm/the_gnat_library gnat-branch-prediction-g-brapre-ads}@anchor{32e}
23930 @section @code{GNAT.Branch_Prediction} (@code{g-brapre.ads})
23933 @geindex GNAT.Branch_Prediction (g-brapre.ads)
23935 @geindex Branch Prediction
23937 Provides routines giving hints to the branch predictor of the code generator.
23939 @node GNAT Bounded_Buffers g-boubuf ads,GNAT Bounded_Mailboxes g-boumai ads,GNAT Branch_Prediction g-brapre ads,The GNAT Library
23940 @anchor{gnat_rm/the_gnat_library id47}@anchor{32f}@anchor{gnat_rm/the_gnat_library gnat-bounded-buffers-g-boubuf-ads}@anchor{330}
23941 @section @code{GNAT.Bounded_Buffers} (@code{g-boubuf.ads})
23944 @geindex GNAT.Bounded_Buffers (g-boubuf.ads)
23948 @geindex Bounded Buffers
23950 Provides a concurrent generic bounded buffer abstraction. Instances are
23951 useful directly or as parts of the implementations of other abstractions,
23954 @node GNAT Bounded_Mailboxes g-boumai ads,GNAT Bubble_Sort g-bubsor ads,GNAT Bounded_Buffers g-boubuf ads,The GNAT Library
23955 @anchor{gnat_rm/the_gnat_library gnat-bounded-mailboxes-g-boumai-ads}@anchor{331}@anchor{gnat_rm/the_gnat_library id48}@anchor{332}
23956 @section @code{GNAT.Bounded_Mailboxes} (@code{g-boumai.ads})
23959 @geindex GNAT.Bounded_Mailboxes (g-boumai.ads)
23965 Provides a thread-safe asynchronous intertask mailbox communication facility.
23967 @node GNAT Bubble_Sort g-bubsor ads,GNAT Bubble_Sort_A g-busora ads,GNAT Bounded_Mailboxes g-boumai ads,The GNAT Library
23968 @anchor{gnat_rm/the_gnat_library gnat-bubble-sort-g-bubsor-ads}@anchor{333}@anchor{gnat_rm/the_gnat_library id49}@anchor{334}
23969 @section @code{GNAT.Bubble_Sort} (@code{g-bubsor.ads})
23972 @geindex GNAT.Bubble_Sort (g-bubsor.ads)
23976 @geindex Bubble sort
23978 Provides a general implementation of bubble sort usable for sorting arbitrary
23979 data items. Exchange and comparison procedures are provided by passing
23980 access-to-procedure values.
23982 @node GNAT Bubble_Sort_A g-busora ads,GNAT Bubble_Sort_G g-busorg ads,GNAT Bubble_Sort g-bubsor ads,The GNAT Library
23983 @anchor{gnat_rm/the_gnat_library id50}@anchor{335}@anchor{gnat_rm/the_gnat_library gnat-bubble-sort-a-g-busora-ads}@anchor{336}
23984 @section @code{GNAT.Bubble_Sort_A} (@code{g-busora.ads})
23987 @geindex GNAT.Bubble_Sort_A (g-busora.ads)
23991 @geindex Bubble sort
23993 Provides a general implementation of bubble sort usable for sorting arbitrary
23994 data items. Move and comparison procedures are provided by passing
23995 access-to-procedure values. This is an older version, retained for
23996 compatibility. Usually @code{GNAT.Bubble_Sort} will be preferable.
23998 @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
23999 @anchor{gnat_rm/the_gnat_library gnat-bubble-sort-g-g-busorg-ads}@anchor{337}@anchor{gnat_rm/the_gnat_library id51}@anchor{338}
24000 @section @code{GNAT.Bubble_Sort_G} (@code{g-busorg.ads})
24003 @geindex GNAT.Bubble_Sort_G (g-busorg.ads)
24007 @geindex Bubble sort
24009 Similar to @code{Bubble_Sort_A} except that the move and sorting procedures
24010 are provided as generic parameters, this improves efficiency, especially
24011 if the procedures can be inlined, at the expense of duplicating code for
24012 multiple instantiations.
24014 @node GNAT Byte_Order_Mark g-byorma ads,GNAT Byte_Swapping g-bytswa ads,GNAT Bubble_Sort_G g-busorg ads,The GNAT Library
24015 @anchor{gnat_rm/the_gnat_library gnat-byte-order-mark-g-byorma-ads}@anchor{339}@anchor{gnat_rm/the_gnat_library id52}@anchor{33a}
24016 @section @code{GNAT.Byte_Order_Mark} (@code{g-byorma.ads})
24019 @geindex GNAT.Byte_Order_Mark (g-byorma.ads)
24021 @geindex UTF-8 representation
24023 @geindex Wide characte representations
24025 Provides a routine which given a string, reads the start of the string to
24026 see whether it is one of the standard byte order marks (BOM's) which signal
24027 the encoding of the string. The routine includes detection of special XML
24028 sequences for various UCS input formats.
24030 @node GNAT Byte_Swapping g-bytswa ads,GNAT Calendar g-calend ads,GNAT Byte_Order_Mark g-byorma ads,The GNAT Library
24031 @anchor{gnat_rm/the_gnat_library gnat-byte-swapping-g-bytswa-ads}@anchor{33b}@anchor{gnat_rm/the_gnat_library id53}@anchor{33c}
24032 @section @code{GNAT.Byte_Swapping} (@code{g-bytswa.ads})
24035 @geindex GNAT.Byte_Swapping (g-bytswa.ads)
24037 @geindex Byte swapping
24039 @geindex Endianness
24041 General routines for swapping the bytes in 2-, 4-, and 8-byte quantities.
24042 Machine-specific implementations are available in some cases.
24044 @node GNAT Calendar g-calend ads,GNAT Calendar Time_IO g-catiio ads,GNAT Byte_Swapping g-bytswa ads,The GNAT Library
24045 @anchor{gnat_rm/the_gnat_library id54}@anchor{33d}@anchor{gnat_rm/the_gnat_library gnat-calendar-g-calend-ads}@anchor{33e}
24046 @section @code{GNAT.Calendar} (@code{g-calend.ads})
24049 @geindex GNAT.Calendar (g-calend.ads)
24053 Extends the facilities provided by @code{Ada.Calendar} to include handling
24054 of days of the week, an extended @code{Split} and @code{Time_Of} capability.
24055 Also provides conversion of @code{Ada.Calendar.Time} values to and from the
24056 C @code{timeval} format.
24058 @node GNAT Calendar Time_IO g-catiio ads,GNAT CRC32 g-crc32 ads,GNAT Calendar g-calend ads,The GNAT Library
24059 @anchor{gnat_rm/the_gnat_library id55}@anchor{33f}@anchor{gnat_rm/the_gnat_library gnat-calendar-time-io-g-catiio-ads}@anchor{340}
24060 @section @code{GNAT.Calendar.Time_IO} (@code{g-catiio.ads})
24067 @geindex GNAT.Calendar.Time_IO (g-catiio.ads)
24069 @node GNAT CRC32 g-crc32 ads,GNAT Case_Util g-casuti ads,GNAT Calendar Time_IO g-catiio ads,The GNAT Library
24070 @anchor{gnat_rm/the_gnat_library id56}@anchor{341}@anchor{gnat_rm/the_gnat_library gnat-crc32-g-crc32-ads}@anchor{342}
24071 @section @code{GNAT.CRC32} (@code{g-crc32.ads})
24074 @geindex GNAT.CRC32 (g-crc32.ads)
24078 @geindex Cyclic Redundancy Check
24080 This package implements the CRC-32 algorithm. For a full description
24081 of this algorithm see
24082 @emph{Computation of Cyclic Redundancy Checks via Table Look-Up},
24083 @cite{Communications of the ACM}, Vol. 31 No. 8, pp. 1008-1013,
24084 Aug. 1988. Sarwate, D.V.
24086 @node GNAT Case_Util g-casuti ads,GNAT CGI g-cgi ads,GNAT CRC32 g-crc32 ads,The GNAT Library
24087 @anchor{gnat_rm/the_gnat_library id57}@anchor{343}@anchor{gnat_rm/the_gnat_library gnat-case-util-g-casuti-ads}@anchor{344}
24088 @section @code{GNAT.Case_Util} (@code{g-casuti.ads})
24091 @geindex GNAT.Case_Util (g-casuti.ads)
24093 @geindex Casing utilities
24095 @geindex Character handling (`@w{`}GNAT.Case_Util`@w{`})
24097 A set of simple routines for handling upper and lower casing of strings
24098 without the overhead of the full casing tables
24099 in @code{Ada.Characters.Handling}.
24101 @node GNAT CGI g-cgi ads,GNAT CGI Cookie g-cgicoo ads,GNAT Case_Util g-casuti ads,The GNAT Library
24102 @anchor{gnat_rm/the_gnat_library id58}@anchor{345}@anchor{gnat_rm/the_gnat_library gnat-cgi-g-cgi-ads}@anchor{346}
24103 @section @code{GNAT.CGI} (@code{g-cgi.ads})
24106 @geindex GNAT.CGI (g-cgi.ads)
24108 @geindex CGI (Common Gateway Interface)
24110 This is a package for interfacing a GNAT program with a Web server via the
24111 Common Gateway Interface (CGI). Basically this package parses the CGI
24112 parameters, which are a set of key/value pairs sent by the Web server. It
24113 builds a table whose index is the key and provides some services to deal
24116 @node GNAT CGI Cookie g-cgicoo ads,GNAT CGI Debug g-cgideb ads,GNAT CGI g-cgi ads,The GNAT Library
24117 @anchor{gnat_rm/the_gnat_library gnat-cgi-cookie-g-cgicoo-ads}@anchor{347}@anchor{gnat_rm/the_gnat_library id59}@anchor{348}
24118 @section @code{GNAT.CGI.Cookie} (@code{g-cgicoo.ads})
24121 @geindex GNAT.CGI.Cookie (g-cgicoo.ads)
24123 @geindex CGI (Common Gateway Interface) cookie support
24125 @geindex Cookie support in CGI
24127 This is a package to interface a GNAT program with a Web server via the
24128 Common Gateway Interface (CGI). It exports services to deal with Web
24129 cookies (piece of information kept in the Web client software).
24131 @node GNAT CGI Debug g-cgideb ads,GNAT Command_Line g-comlin ads,GNAT CGI Cookie g-cgicoo ads,The GNAT Library
24132 @anchor{gnat_rm/the_gnat_library gnat-cgi-debug-g-cgideb-ads}@anchor{349}@anchor{gnat_rm/the_gnat_library id60}@anchor{34a}
24133 @section @code{GNAT.CGI.Debug} (@code{g-cgideb.ads})
24136 @geindex GNAT.CGI.Debug (g-cgideb.ads)
24138 @geindex CGI (Common Gateway Interface) debugging
24140 This is a package to help debugging CGI (Common Gateway Interface)
24141 programs written in Ada.
24143 @node GNAT Command_Line g-comlin ads,GNAT Compiler_Version g-comver ads,GNAT CGI Debug g-cgideb ads,The GNAT Library
24144 @anchor{gnat_rm/the_gnat_library id61}@anchor{34b}@anchor{gnat_rm/the_gnat_library gnat-command-line-g-comlin-ads}@anchor{34c}
24145 @section @code{GNAT.Command_Line} (@code{g-comlin.ads})
24148 @geindex GNAT.Command_Line (g-comlin.ads)
24150 @geindex Command line
24152 Provides a high level interface to @code{Ada.Command_Line} facilities,
24153 including the ability to scan for named switches with optional parameters
24154 and expand file names using wildcard notations.
24156 @node GNAT Compiler_Version g-comver ads,GNAT Ctrl_C g-ctrl_c ads,GNAT Command_Line g-comlin ads,The GNAT Library
24157 @anchor{gnat_rm/the_gnat_library gnat-compiler-version-g-comver-ads}@anchor{34d}@anchor{gnat_rm/the_gnat_library id62}@anchor{34e}
24158 @section @code{GNAT.Compiler_Version} (@code{g-comver.ads})
24161 @geindex GNAT.Compiler_Version (g-comver.ads)
24163 @geindex Compiler Version
24166 @geindex of compiler
24168 Provides a routine for obtaining the version of the compiler used to
24169 compile the program. More accurately this is the version of the binder
24170 used to bind the program (this will normally be the same as the version
24171 of the compiler if a consistent tool set is used to compile all units
24174 @node GNAT Ctrl_C g-ctrl_c ads,GNAT Current_Exception g-curexc ads,GNAT Compiler_Version g-comver ads,The GNAT Library
24175 @anchor{gnat_rm/the_gnat_library gnat-ctrl-c-g-ctrl-c-ads}@anchor{34f}@anchor{gnat_rm/the_gnat_library id63}@anchor{350}
24176 @section @code{GNAT.Ctrl_C} (@code{g-ctrl_c.ads})
24179 @geindex GNAT.Ctrl_C (g-ctrl_c.ads)
24183 Provides a simple interface to handle Ctrl-C keyboard events.
24185 @node GNAT Current_Exception g-curexc ads,GNAT Debug_Pools g-debpoo ads,GNAT Ctrl_C g-ctrl_c ads,The GNAT Library
24186 @anchor{gnat_rm/the_gnat_library id64}@anchor{351}@anchor{gnat_rm/the_gnat_library gnat-current-exception-g-curexc-ads}@anchor{352}
24187 @section @code{GNAT.Current_Exception} (@code{g-curexc.ads})
24190 @geindex GNAT.Current_Exception (g-curexc.ads)
24192 @geindex Current exception
24194 @geindex Exception retrieval
24196 Provides access to information on the current exception that has been raised
24197 without the need for using the Ada 95 / Ada 2005 exception choice parameter
24198 specification syntax.
24199 This is particularly useful in simulating typical facilities for
24200 obtaining information about exceptions provided by Ada 83 compilers.
24202 @node GNAT Debug_Pools g-debpoo ads,GNAT Debug_Utilities g-debuti ads,GNAT Current_Exception g-curexc ads,The GNAT Library
24203 @anchor{gnat_rm/the_gnat_library gnat-debug-pools-g-debpoo-ads}@anchor{353}@anchor{gnat_rm/the_gnat_library id65}@anchor{354}
24204 @section @code{GNAT.Debug_Pools} (@code{g-debpoo.ads})
24207 @geindex GNAT.Debug_Pools (g-debpoo.ads)
24211 @geindex Debug pools
24213 @geindex Memory corruption debugging
24215 Provide a debugging storage pools that helps tracking memory corruption
24217 See @code{The GNAT Debug_Pool Facility} section in the @cite{GNAT User's Guide}.
24219 @node GNAT Debug_Utilities g-debuti ads,GNAT Decode_String g-decstr ads,GNAT Debug_Pools g-debpoo ads,The GNAT Library
24220 @anchor{gnat_rm/the_gnat_library gnat-debug-utilities-g-debuti-ads}@anchor{355}@anchor{gnat_rm/the_gnat_library id66}@anchor{356}
24221 @section @code{GNAT.Debug_Utilities} (@code{g-debuti.ads})
24224 @geindex GNAT.Debug_Utilities (g-debuti.ads)
24228 Provides a few useful utilities for debugging purposes, including conversion
24229 to and from string images of address values. Supports both C and Ada formats
24230 for hexadecimal literals.
24232 @node GNAT Decode_String g-decstr ads,GNAT Decode_UTF8_String g-deutst ads,GNAT Debug_Utilities g-debuti ads,The GNAT Library
24233 @anchor{gnat_rm/the_gnat_library id67}@anchor{357}@anchor{gnat_rm/the_gnat_library gnat-decode-string-g-decstr-ads}@anchor{358}
24234 @section @code{GNAT.Decode_String} (@code{g-decstr.ads})
24237 @geindex GNAT.Decode_String (g-decstr.ads)
24239 @geindex Decoding strings
24241 @geindex String decoding
24243 @geindex Wide character encoding
24249 A generic package providing routines for decoding wide character and wide wide
24250 character strings encoded as sequences of 8-bit characters using a specified
24251 encoding method. Includes validation routines, and also routines for stepping
24252 to next or previous encoded character in an encoded string.
24253 Useful in conjunction with Unicode character coding. Note there is a
24254 preinstantiation for UTF-8. See next entry.
24256 @node GNAT Decode_UTF8_String g-deutst ads,GNAT Directory_Operations g-dirope ads,GNAT Decode_String g-decstr ads,The GNAT Library
24257 @anchor{gnat_rm/the_gnat_library gnat-decode-utf8-string-g-deutst-ads}@anchor{359}@anchor{gnat_rm/the_gnat_library id68}@anchor{35a}
24258 @section @code{GNAT.Decode_UTF8_String} (@code{g-deutst.ads})
24261 @geindex GNAT.Decode_UTF8_String (g-deutst.ads)
24263 @geindex Decoding strings
24265 @geindex Decoding UTF-8 strings
24267 @geindex UTF-8 string decoding
24269 @geindex Wide character decoding
24275 A preinstantiation of GNAT.Decode_Strings for UTF-8 encoding.
24277 @node GNAT Directory_Operations g-dirope ads,GNAT Directory_Operations Iteration g-diopit ads,GNAT Decode_UTF8_String g-deutst ads,The GNAT Library
24278 @anchor{gnat_rm/the_gnat_library id69}@anchor{35b}@anchor{gnat_rm/the_gnat_library gnat-directory-operations-g-dirope-ads}@anchor{35c}
24279 @section @code{GNAT.Directory_Operations} (@code{g-dirope.ads})
24282 @geindex GNAT.Directory_Operations (g-dirope.ads)
24284 @geindex Directory operations
24286 Provides a set of routines for manipulating directories, including changing
24287 the current directory, making new directories, and scanning the files in a
24290 @node GNAT Directory_Operations Iteration g-diopit ads,GNAT Dynamic_HTables g-dynhta ads,GNAT Directory_Operations g-dirope ads,The GNAT Library
24291 @anchor{gnat_rm/the_gnat_library id70}@anchor{35d}@anchor{gnat_rm/the_gnat_library gnat-directory-operations-iteration-g-diopit-ads}@anchor{35e}
24292 @section @code{GNAT.Directory_Operations.Iteration} (@code{g-diopit.ads})
24295 @geindex GNAT.Directory_Operations.Iteration (g-diopit.ads)
24297 @geindex Directory operations iteration
24299 A child unit of GNAT.Directory_Operations providing additional operations
24300 for iterating through directories.
24302 @node GNAT Dynamic_HTables g-dynhta ads,GNAT Dynamic_Tables g-dyntab ads,GNAT Directory_Operations Iteration g-diopit ads,The GNAT Library
24303 @anchor{gnat_rm/the_gnat_library id71}@anchor{35f}@anchor{gnat_rm/the_gnat_library gnat-dynamic-htables-g-dynhta-ads}@anchor{360}
24304 @section @code{GNAT.Dynamic_HTables} (@code{g-dynhta.ads})
24307 @geindex GNAT.Dynamic_HTables (g-dynhta.ads)
24309 @geindex Hash tables
24311 A generic implementation of hash tables that can be used to hash arbitrary
24312 data. Provided in two forms, a simple form with built in hash functions,
24313 and a more complex form in which the hash function is supplied.
24315 This package provides a facility similar to that of @code{GNAT.HTable},
24316 except that this package declares a type that can be used to define
24317 dynamic instances of the hash table, while an instantiation of
24318 @code{GNAT.HTable} creates a single instance of the hash table.
24320 @node GNAT Dynamic_Tables g-dyntab ads,GNAT Encode_String g-encstr ads,GNAT Dynamic_HTables g-dynhta ads,The GNAT Library
24321 @anchor{gnat_rm/the_gnat_library gnat-dynamic-tables-g-dyntab-ads}@anchor{361}@anchor{gnat_rm/the_gnat_library id72}@anchor{362}
24322 @section @code{GNAT.Dynamic_Tables} (@code{g-dyntab.ads})
24325 @geindex GNAT.Dynamic_Tables (g-dyntab.ads)
24327 @geindex Table implementation
24330 @geindex extendable
24332 A generic package providing a single dimension array abstraction where the
24333 length of the array can be dynamically modified.
24335 This package provides a facility similar to that of @code{GNAT.Table},
24336 except that this package declares a type that can be used to define
24337 dynamic instances of the table, while an instantiation of
24338 @code{GNAT.Table} creates a single instance of the table type.
24340 @node GNAT Encode_String g-encstr ads,GNAT Encode_UTF8_String g-enutst ads,GNAT Dynamic_Tables g-dyntab ads,The GNAT Library
24341 @anchor{gnat_rm/the_gnat_library id73}@anchor{363}@anchor{gnat_rm/the_gnat_library gnat-encode-string-g-encstr-ads}@anchor{364}
24342 @section @code{GNAT.Encode_String} (@code{g-encstr.ads})
24345 @geindex GNAT.Encode_String (g-encstr.ads)
24347 @geindex Encoding strings
24349 @geindex String encoding
24351 @geindex Wide character encoding
24357 A generic package providing routines for encoding wide character and wide
24358 wide character strings as sequences of 8-bit characters using a specified
24359 encoding method. Useful in conjunction with Unicode character coding.
24360 Note there is a preinstantiation for UTF-8. See next entry.
24362 @node GNAT Encode_UTF8_String g-enutst ads,GNAT Exception_Actions g-excact ads,GNAT Encode_String g-encstr ads,The GNAT Library
24363 @anchor{gnat_rm/the_gnat_library gnat-encode-utf8-string-g-enutst-ads}@anchor{365}@anchor{gnat_rm/the_gnat_library id74}@anchor{366}
24364 @section @code{GNAT.Encode_UTF8_String} (@code{g-enutst.ads})
24367 @geindex GNAT.Encode_UTF8_String (g-enutst.ads)
24369 @geindex Encoding strings
24371 @geindex Encoding UTF-8 strings
24373 @geindex UTF-8 string encoding
24375 @geindex Wide character encoding
24381 A preinstantiation of GNAT.Encode_Strings for UTF-8 encoding.
24383 @node GNAT Exception_Actions g-excact ads,GNAT Exception_Traces g-exctra ads,GNAT Encode_UTF8_String g-enutst ads,The GNAT Library
24384 @anchor{gnat_rm/the_gnat_library gnat-exception-actions-g-excact-ads}@anchor{367}@anchor{gnat_rm/the_gnat_library id75}@anchor{368}
24385 @section @code{GNAT.Exception_Actions} (@code{g-excact.ads})
24388 @geindex GNAT.Exception_Actions (g-excact.ads)
24390 @geindex Exception actions
24392 Provides callbacks when an exception is raised. Callbacks can be registered
24393 for specific exceptions, or when any exception is raised. This
24394 can be used for instance to force a core dump to ease debugging.
24396 @node GNAT Exception_Traces g-exctra ads,GNAT Exceptions g-except ads,GNAT Exception_Actions g-excact ads,The GNAT Library
24397 @anchor{gnat_rm/the_gnat_library gnat-exception-traces-g-exctra-ads}@anchor{369}@anchor{gnat_rm/the_gnat_library id76}@anchor{36a}
24398 @section @code{GNAT.Exception_Traces} (@code{g-exctra.ads})
24401 @geindex GNAT.Exception_Traces (g-exctra.ads)
24403 @geindex Exception traces
24407 Provides an interface allowing to control automatic output upon exception
24410 @node GNAT Exceptions g-except ads,GNAT Expect g-expect ads,GNAT Exception_Traces g-exctra ads,The GNAT Library
24411 @anchor{gnat_rm/the_gnat_library id77}@anchor{36b}@anchor{gnat_rm/the_gnat_library gnat-exceptions-g-except-ads}@anchor{36c}
24412 @section @code{GNAT.Exceptions} (@code{g-except.ads})
24415 @geindex GNAT.Exceptions (g-except.ads)
24417 @geindex Exceptions
24420 @geindex Pure packages
24421 @geindex exceptions
24423 Normally it is not possible to raise an exception with
24424 a message from a subprogram in a pure package, since the
24425 necessary types and subprograms are in @code{Ada.Exceptions}
24426 which is not a pure unit. @code{GNAT.Exceptions} provides a
24427 facility for getting around this limitation for a few
24428 predefined exceptions, and for example allow raising
24429 @code{Constraint_Error} with a message from a pure subprogram.
24431 @node GNAT Expect g-expect ads,GNAT Expect TTY g-exptty ads,GNAT Exceptions g-except ads,The GNAT Library
24432 @anchor{gnat_rm/the_gnat_library id78}@anchor{36d}@anchor{gnat_rm/the_gnat_library gnat-expect-g-expect-ads}@anchor{36e}
24433 @section @code{GNAT.Expect} (@code{g-expect.ads})
24436 @geindex GNAT.Expect (g-expect.ads)
24438 Provides a set of subprograms similar to what is available
24439 with the standard Tcl Expect tool.
24440 It allows you to easily spawn and communicate with an external process.
24441 You can send commands or inputs to the process, and compare the output
24442 with some expected regular expression. Currently @code{GNAT.Expect}
24443 is implemented on all native GNAT ports.
24444 It is not implemented for cross ports, and in particular is not
24445 implemented for VxWorks or LynxOS.
24447 @node GNAT Expect TTY g-exptty ads,GNAT Float_Control g-flocon ads,GNAT Expect g-expect ads,The GNAT Library
24448 @anchor{gnat_rm/the_gnat_library id79}@anchor{36f}@anchor{gnat_rm/the_gnat_library gnat-expect-tty-g-exptty-ads}@anchor{370}
24449 @section @code{GNAT.Expect.TTY} (@code{g-exptty.ads})
24452 @geindex GNAT.Expect.TTY (g-exptty.ads)
24454 As GNAT.Expect but using pseudo-terminal.
24455 Currently @code{GNAT.Expect.TTY} is implemented on all native GNAT
24456 ports. It is not implemented for cross ports, and
24457 in particular is not implemented for VxWorks or LynxOS.
24459 @node GNAT Float_Control g-flocon ads,GNAT Formatted_String g-forstr ads,GNAT Expect TTY g-exptty ads,The GNAT Library
24460 @anchor{gnat_rm/the_gnat_library id80}@anchor{371}@anchor{gnat_rm/the_gnat_library gnat-float-control-g-flocon-ads}@anchor{372}
24461 @section @code{GNAT.Float_Control} (@code{g-flocon.ads})
24464 @geindex GNAT.Float_Control (g-flocon.ads)
24466 @geindex Floating-Point Processor
24468 Provides an interface for resetting the floating-point processor into the
24469 mode required for correct semantic operation in Ada. Some third party
24470 library calls may cause this mode to be modified, and the Reset procedure
24471 in this package can be used to reestablish the required mode.
24473 @node GNAT Formatted_String g-forstr ads,GNAT Heap_Sort g-heasor ads,GNAT Float_Control g-flocon ads,The GNAT Library
24474 @anchor{gnat_rm/the_gnat_library id81}@anchor{373}@anchor{gnat_rm/the_gnat_library gnat-formatted-string-g-forstr-ads}@anchor{374}
24475 @section @code{GNAT.Formatted_String} (@code{g-forstr.ads})
24478 @geindex GNAT.Formatted_String (g-forstr.ads)
24480 @geindex Formatted String
24482 Provides support for C/C++ printf() formatted strings. The format is
24483 copied from the printf() routine and should therefore gives identical
24484 output. Some generic routines are provided to be able to use types
24485 derived from Integer, Float or enumerations as values for the
24488 @node GNAT Heap_Sort g-heasor ads,GNAT Heap_Sort_A g-hesora ads,GNAT Formatted_String g-forstr ads,The GNAT Library
24489 @anchor{gnat_rm/the_gnat_library gnat-heap-sort-g-heasor-ads}@anchor{375}@anchor{gnat_rm/the_gnat_library id82}@anchor{376}
24490 @section @code{GNAT.Heap_Sort} (@code{g-heasor.ads})
24493 @geindex GNAT.Heap_Sort (g-heasor.ads)
24497 Provides a general implementation of heap sort usable for sorting arbitrary
24498 data items. Exchange and comparison procedures are provided by passing
24499 access-to-procedure values. The algorithm used is a modified heap sort
24500 that performs approximately N*log(N) comparisons in the worst case.
24502 @node GNAT Heap_Sort_A g-hesora ads,GNAT Heap_Sort_G g-hesorg ads,GNAT Heap_Sort g-heasor ads,The GNAT Library
24503 @anchor{gnat_rm/the_gnat_library id83}@anchor{377}@anchor{gnat_rm/the_gnat_library gnat-heap-sort-a-g-hesora-ads}@anchor{378}
24504 @section @code{GNAT.Heap_Sort_A} (@code{g-hesora.ads})
24507 @geindex GNAT.Heap_Sort_A (g-hesora.ads)
24511 Provides a general implementation of heap sort usable for sorting arbitrary
24512 data items. Move and comparison procedures are provided by passing
24513 access-to-procedure values. The algorithm used is a modified heap sort
24514 that performs approximately N*log(N) comparisons in the worst case.
24515 This differs from @code{GNAT.Heap_Sort} in having a less convenient
24516 interface, but may be slightly more efficient.
24518 @node GNAT Heap_Sort_G g-hesorg ads,GNAT HTable g-htable ads,GNAT Heap_Sort_A g-hesora ads,The GNAT Library
24519 @anchor{gnat_rm/the_gnat_library id84}@anchor{379}@anchor{gnat_rm/the_gnat_library gnat-heap-sort-g-g-hesorg-ads}@anchor{37a}
24520 @section @code{GNAT.Heap_Sort_G} (@code{g-hesorg.ads})
24523 @geindex GNAT.Heap_Sort_G (g-hesorg.ads)
24527 Similar to @code{Heap_Sort_A} except that the move and sorting procedures
24528 are provided as generic parameters, this improves efficiency, especially
24529 if the procedures can be inlined, at the expense of duplicating code for
24530 multiple instantiations.
24532 @node GNAT HTable g-htable ads,GNAT IO g-io ads,GNAT Heap_Sort_G g-hesorg ads,The GNAT Library
24533 @anchor{gnat_rm/the_gnat_library id85}@anchor{37b}@anchor{gnat_rm/the_gnat_library gnat-htable-g-htable-ads}@anchor{37c}
24534 @section @code{GNAT.HTable} (@code{g-htable.ads})
24537 @geindex GNAT.HTable (g-htable.ads)
24539 @geindex Hash tables
24541 A generic implementation of hash tables that can be used to hash arbitrary
24542 data. Provides two approaches, one a simple static approach, and the other
24543 allowing arbitrary dynamic hash tables.
24545 @node GNAT IO g-io ads,GNAT IO_Aux g-io_aux ads,GNAT HTable g-htable ads,The GNAT Library
24546 @anchor{gnat_rm/the_gnat_library id86}@anchor{37d}@anchor{gnat_rm/the_gnat_library gnat-io-g-io-ads}@anchor{37e}
24547 @section @code{GNAT.IO} (@code{g-io.ads})
24550 @geindex GNAT.IO (g-io.ads)
24552 @geindex Simple I/O
24554 @geindex Input/Output facilities
24556 A simple preelaborable input-output package that provides a subset of
24557 simple Text_IO functions for reading characters and strings from
24558 Standard_Input, and writing characters, strings and integers to either
24559 Standard_Output or Standard_Error.
24561 @node GNAT IO_Aux g-io_aux ads,GNAT Lock_Files g-locfil ads,GNAT IO g-io ads,The GNAT Library
24562 @anchor{gnat_rm/the_gnat_library id87}@anchor{37f}@anchor{gnat_rm/the_gnat_library gnat-io-aux-g-io-aux-ads}@anchor{380}
24563 @section @code{GNAT.IO_Aux} (@code{g-io_aux.ads})
24566 @geindex GNAT.IO_Aux (g-io_aux.ads)
24570 @geindex Input/Output facilities
24572 Provides some auxiliary functions for use with Text_IO, including a test
24573 for whether a file exists, and functions for reading a line of text.
24575 @node GNAT Lock_Files g-locfil ads,GNAT MBBS_Discrete_Random g-mbdira ads,GNAT IO_Aux g-io_aux ads,The GNAT Library
24576 @anchor{gnat_rm/the_gnat_library id88}@anchor{381}@anchor{gnat_rm/the_gnat_library gnat-lock-files-g-locfil-ads}@anchor{382}
24577 @section @code{GNAT.Lock_Files} (@code{g-locfil.ads})
24580 @geindex GNAT.Lock_Files (g-locfil.ads)
24582 @geindex File locking
24584 @geindex Locking using files
24586 Provides a general interface for using files as locks. Can be used for
24587 providing program level synchronization.
24589 @node GNAT MBBS_Discrete_Random g-mbdira ads,GNAT MBBS_Float_Random g-mbflra ads,GNAT Lock_Files g-locfil ads,The GNAT Library
24590 @anchor{gnat_rm/the_gnat_library id89}@anchor{383}@anchor{gnat_rm/the_gnat_library gnat-mbbs-discrete-random-g-mbdira-ads}@anchor{384}
24591 @section @code{GNAT.MBBS_Discrete_Random} (@code{g-mbdira.ads})
24594 @geindex GNAT.MBBS_Discrete_Random (g-mbdira.ads)
24596 @geindex Random number generation
24598 The original implementation of @code{Ada.Numerics.Discrete_Random}. Uses
24599 a modified version of the Blum-Blum-Shub generator.
24601 @node GNAT MBBS_Float_Random g-mbflra ads,GNAT MD5 g-md5 ads,GNAT MBBS_Discrete_Random g-mbdira ads,The GNAT Library
24602 @anchor{gnat_rm/the_gnat_library id90}@anchor{385}@anchor{gnat_rm/the_gnat_library gnat-mbbs-float-random-g-mbflra-ads}@anchor{386}
24603 @section @code{GNAT.MBBS_Float_Random} (@code{g-mbflra.ads})
24606 @geindex GNAT.MBBS_Float_Random (g-mbflra.ads)
24608 @geindex Random number generation
24610 The original implementation of @code{Ada.Numerics.Float_Random}. Uses
24611 a modified version of the Blum-Blum-Shub generator.
24613 @node GNAT MD5 g-md5 ads,GNAT Memory_Dump g-memdum ads,GNAT MBBS_Float_Random g-mbflra ads,The GNAT Library
24614 @anchor{gnat_rm/the_gnat_library id91}@anchor{387}@anchor{gnat_rm/the_gnat_library gnat-md5-g-md5-ads}@anchor{388}
24615 @section @code{GNAT.MD5} (@code{g-md5.ads})
24618 @geindex GNAT.MD5 (g-md5.ads)
24620 @geindex Message Digest MD5
24622 Implements the MD5 Message-Digest Algorithm as described in RFC 1321, and
24623 the HMAC-MD5 message authentication function as described in RFC 2104 and
24626 @node GNAT Memory_Dump g-memdum ads,GNAT Most_Recent_Exception g-moreex ads,GNAT MD5 g-md5 ads,The GNAT Library
24627 @anchor{gnat_rm/the_gnat_library id92}@anchor{389}@anchor{gnat_rm/the_gnat_library gnat-memory-dump-g-memdum-ads}@anchor{38a}
24628 @section @code{GNAT.Memory_Dump} (@code{g-memdum.ads})
24631 @geindex GNAT.Memory_Dump (g-memdum.ads)
24633 @geindex Dump Memory
24635 Provides a convenient routine for dumping raw memory to either the
24636 standard output or standard error files. Uses GNAT.IO for actual
24639 @node GNAT Most_Recent_Exception g-moreex ads,GNAT OS_Lib g-os_lib ads,GNAT Memory_Dump g-memdum ads,The GNAT Library
24640 @anchor{gnat_rm/the_gnat_library gnat-most-recent-exception-g-moreex-ads}@anchor{38b}@anchor{gnat_rm/the_gnat_library id93}@anchor{38c}
24641 @section @code{GNAT.Most_Recent_Exception} (@code{g-moreex.ads})
24644 @geindex GNAT.Most_Recent_Exception (g-moreex.ads)
24647 @geindex obtaining most recent
24649 Provides access to the most recently raised exception. Can be used for
24650 various logging purposes, including duplicating functionality of some
24651 Ada 83 implementation dependent extensions.
24653 @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
24654 @anchor{gnat_rm/the_gnat_library gnat-os-lib-g-os-lib-ads}@anchor{38d}@anchor{gnat_rm/the_gnat_library id94}@anchor{38e}
24655 @section @code{GNAT.OS_Lib} (@code{g-os_lib.ads})
24658 @geindex GNAT.OS_Lib (g-os_lib.ads)
24660 @geindex Operating System interface
24662 @geindex Spawn capability
24664 Provides a range of target independent operating system interface functions,
24665 including time/date management, file operations, subprocess management,
24666 including a portable spawn procedure, and access to environment variables
24667 and error return codes.
24669 @node GNAT Perfect_Hash_Generators g-pehage ads,GNAT Random_Numbers g-rannum ads,GNAT OS_Lib g-os_lib ads,The GNAT Library
24670 @anchor{gnat_rm/the_gnat_library gnat-perfect-hash-generators-g-pehage-ads}@anchor{38f}@anchor{gnat_rm/the_gnat_library id95}@anchor{390}
24671 @section @code{GNAT.Perfect_Hash_Generators} (@code{g-pehage.ads})
24674 @geindex GNAT.Perfect_Hash_Generators (g-pehage.ads)
24676 @geindex Hash functions
24678 Provides a generator of static minimal perfect hash functions. No
24679 collisions occur and each item can be retrieved from the table in one
24680 probe (perfect property). The hash table size corresponds to the exact
24681 size of the key set and no larger (minimal property). The key set has to
24682 be know in advance (static property). The hash functions are also order
24683 preserving. If w2 is inserted after w1 in the generator, their
24684 hashcode are in the same order. These hashing functions are very
24685 convenient for use with realtime applications.
24687 @node GNAT Random_Numbers g-rannum ads,GNAT Regexp g-regexp ads,GNAT Perfect_Hash_Generators g-pehage ads,The GNAT Library
24688 @anchor{gnat_rm/the_gnat_library gnat-random-numbers-g-rannum-ads}@anchor{391}@anchor{gnat_rm/the_gnat_library id96}@anchor{392}
24689 @section @code{GNAT.Random_Numbers} (@code{g-rannum.ads})
24692 @geindex GNAT.Random_Numbers (g-rannum.ads)
24694 @geindex Random number generation
24696 Provides random number capabilities which extend those available in the
24697 standard Ada library and are more convenient to use.
24699 @node GNAT Regexp g-regexp ads,GNAT Registry g-regist ads,GNAT Random_Numbers g-rannum ads,The GNAT Library
24700 @anchor{gnat_rm/the_gnat_library gnat-regexp-g-regexp-ads}@anchor{25a}@anchor{gnat_rm/the_gnat_library id97}@anchor{393}
24701 @section @code{GNAT.Regexp} (@code{g-regexp.ads})
24704 @geindex GNAT.Regexp (g-regexp.ads)
24706 @geindex Regular expressions
24708 @geindex Pattern matching
24710 A simple implementation of regular expressions, using a subset of regular
24711 expression syntax copied from familiar Unix style utilities. This is the
24712 simplest of the three pattern matching packages provided, and is particularly
24713 suitable for 'file globbing' applications.
24715 @node GNAT Registry g-regist ads,GNAT Regpat g-regpat ads,GNAT Regexp g-regexp ads,The GNAT Library
24716 @anchor{gnat_rm/the_gnat_library id98}@anchor{394}@anchor{gnat_rm/the_gnat_library gnat-registry-g-regist-ads}@anchor{395}
24717 @section @code{GNAT.Registry} (@code{g-regist.ads})
24720 @geindex GNAT.Registry (g-regist.ads)
24722 @geindex Windows Registry
24724 This is a high level binding to the Windows registry. It is possible to
24725 do simple things like reading a key value, creating a new key. For full
24726 registry API, but at a lower level of abstraction, refer to the Win32.Winreg
24727 package provided with the Win32Ada binding
24729 @node GNAT Regpat g-regpat ads,GNAT Rewrite_Data g-rewdat ads,GNAT Registry g-regist ads,The GNAT Library
24730 @anchor{gnat_rm/the_gnat_library id99}@anchor{396}@anchor{gnat_rm/the_gnat_library gnat-regpat-g-regpat-ads}@anchor{397}
24731 @section @code{GNAT.Regpat} (@code{g-regpat.ads})
24734 @geindex GNAT.Regpat (g-regpat.ads)
24736 @geindex Regular expressions
24738 @geindex Pattern matching
24740 A complete implementation of Unix-style regular expression matching, copied
24741 from the original V7 style regular expression library written in C by
24742 Henry Spencer (and binary compatible with this C library).
24744 @node GNAT Rewrite_Data g-rewdat ads,GNAT Secondary_Stack_Info g-sestin ads,GNAT Regpat g-regpat ads,The GNAT Library
24745 @anchor{gnat_rm/the_gnat_library id100}@anchor{398}@anchor{gnat_rm/the_gnat_library gnat-rewrite-data-g-rewdat-ads}@anchor{399}
24746 @section @code{GNAT.Rewrite_Data} (@code{g-rewdat.ads})
24749 @geindex GNAT.Rewrite_Data (g-rewdat.ads)
24751 @geindex Rewrite data
24753 A unit to rewrite on-the-fly string occurrences in a stream of
24754 data. The implementation has a very minimal memory footprint as the
24755 full content to be processed is not loaded into memory all at once. This makes
24756 this interface usable for large files or socket streams.
24758 @node GNAT Secondary_Stack_Info g-sestin ads,GNAT Semaphores g-semaph ads,GNAT Rewrite_Data g-rewdat ads,The GNAT Library
24759 @anchor{gnat_rm/the_gnat_library id101}@anchor{39a}@anchor{gnat_rm/the_gnat_library gnat-secondary-stack-info-g-sestin-ads}@anchor{39b}
24760 @section @code{GNAT.Secondary_Stack_Info} (@code{g-sestin.ads})
24763 @geindex GNAT.Secondary_Stack_Info (g-sestin.ads)
24765 @geindex Secondary Stack Info
24767 Provide the capability to query the high water mark of the current task's
24770 @node GNAT Semaphores g-semaph ads,GNAT Serial_Communications g-sercom ads,GNAT Secondary_Stack_Info g-sestin ads,The GNAT Library
24771 @anchor{gnat_rm/the_gnat_library id102}@anchor{39c}@anchor{gnat_rm/the_gnat_library gnat-semaphores-g-semaph-ads}@anchor{39d}
24772 @section @code{GNAT.Semaphores} (@code{g-semaph.ads})
24775 @geindex GNAT.Semaphores (g-semaph.ads)
24777 @geindex Semaphores
24779 Provides classic counting and binary semaphores using protected types.
24781 @node GNAT Serial_Communications g-sercom ads,GNAT SHA1 g-sha1 ads,GNAT Semaphores g-semaph ads,The GNAT Library
24782 @anchor{gnat_rm/the_gnat_library gnat-serial-communications-g-sercom-ads}@anchor{39e}@anchor{gnat_rm/the_gnat_library id103}@anchor{39f}
24783 @section @code{GNAT.Serial_Communications} (@code{g-sercom.ads})
24786 @geindex GNAT.Serial_Communications (g-sercom.ads)
24788 @geindex Serial_Communications
24790 Provides a simple interface to send and receive data over a serial
24791 port. This is only supported on GNU/Linux and Windows.
24793 @node GNAT SHA1 g-sha1 ads,GNAT SHA224 g-sha224 ads,GNAT Serial_Communications g-sercom ads,The GNAT Library
24794 @anchor{gnat_rm/the_gnat_library gnat-sha1-g-sha1-ads}@anchor{3a0}@anchor{gnat_rm/the_gnat_library id104}@anchor{3a1}
24795 @section @code{GNAT.SHA1} (@code{g-sha1.ads})
24798 @geindex GNAT.SHA1 (g-sha1.ads)
24800 @geindex Secure Hash Algorithm SHA-1
24802 Implements the SHA-1 Secure Hash Algorithm as described in FIPS PUB 180-3
24803 and RFC 3174, and the HMAC-SHA1 message authentication function as described
24804 in RFC 2104 and FIPS PUB 198.
24806 @node GNAT SHA224 g-sha224 ads,GNAT SHA256 g-sha256 ads,GNAT SHA1 g-sha1 ads,The GNAT Library
24807 @anchor{gnat_rm/the_gnat_library gnat-sha224-g-sha224-ads}@anchor{3a2}@anchor{gnat_rm/the_gnat_library id105}@anchor{3a3}
24808 @section @code{GNAT.SHA224} (@code{g-sha224.ads})
24811 @geindex GNAT.SHA224 (g-sha224.ads)
24813 @geindex Secure Hash Algorithm SHA-224
24815 Implements the SHA-224 Secure Hash Algorithm as described in FIPS PUB 180-3,
24816 and the HMAC-SHA224 message authentication function as described
24817 in RFC 2104 and FIPS PUB 198.
24819 @node GNAT SHA256 g-sha256 ads,GNAT SHA384 g-sha384 ads,GNAT SHA224 g-sha224 ads,The GNAT Library
24820 @anchor{gnat_rm/the_gnat_library gnat-sha256-g-sha256-ads}@anchor{3a4}@anchor{gnat_rm/the_gnat_library id106}@anchor{3a5}
24821 @section @code{GNAT.SHA256} (@code{g-sha256.ads})
24824 @geindex GNAT.SHA256 (g-sha256.ads)
24826 @geindex Secure Hash Algorithm SHA-256
24828 Implements the SHA-256 Secure Hash Algorithm as described in FIPS PUB 180-3,
24829 and the HMAC-SHA256 message authentication function as described
24830 in RFC 2104 and FIPS PUB 198.
24832 @node GNAT SHA384 g-sha384 ads,GNAT SHA512 g-sha512 ads,GNAT SHA256 g-sha256 ads,The GNAT Library
24833 @anchor{gnat_rm/the_gnat_library gnat-sha384-g-sha384-ads}@anchor{3a6}@anchor{gnat_rm/the_gnat_library id107}@anchor{3a7}
24834 @section @code{GNAT.SHA384} (@code{g-sha384.ads})
24837 @geindex GNAT.SHA384 (g-sha384.ads)
24839 @geindex Secure Hash Algorithm SHA-384
24841 Implements the SHA-384 Secure Hash Algorithm as described in FIPS PUB 180-3,
24842 and the HMAC-SHA384 message authentication function as described
24843 in RFC 2104 and FIPS PUB 198.
24845 @node GNAT SHA512 g-sha512 ads,GNAT Signals g-signal ads,GNAT SHA384 g-sha384 ads,The GNAT Library
24846 @anchor{gnat_rm/the_gnat_library id108}@anchor{3a8}@anchor{gnat_rm/the_gnat_library gnat-sha512-g-sha512-ads}@anchor{3a9}
24847 @section @code{GNAT.SHA512} (@code{g-sha512.ads})
24850 @geindex GNAT.SHA512 (g-sha512.ads)
24852 @geindex Secure Hash Algorithm SHA-512
24854 Implements the SHA-512 Secure Hash Algorithm as described in FIPS PUB 180-3,
24855 and the HMAC-SHA512 message authentication function as described
24856 in RFC 2104 and FIPS PUB 198.
24858 @node GNAT Signals g-signal ads,GNAT Sockets g-socket ads,GNAT SHA512 g-sha512 ads,The GNAT Library
24859 @anchor{gnat_rm/the_gnat_library id109}@anchor{3aa}@anchor{gnat_rm/the_gnat_library gnat-signals-g-signal-ads}@anchor{3ab}
24860 @section @code{GNAT.Signals} (@code{g-signal.ads})
24863 @geindex GNAT.Signals (g-signal.ads)
24867 Provides the ability to manipulate the blocked status of signals on supported
24870 @node GNAT Sockets g-socket ads,GNAT Source_Info g-souinf ads,GNAT Signals g-signal ads,The GNAT Library
24871 @anchor{gnat_rm/the_gnat_library gnat-sockets-g-socket-ads}@anchor{3ac}@anchor{gnat_rm/the_gnat_library id110}@anchor{3ad}
24872 @section @code{GNAT.Sockets} (@code{g-socket.ads})
24875 @geindex GNAT.Sockets (g-socket.ads)
24879 A high level and portable interface to develop sockets based applications.
24880 This package is based on the sockets thin binding found in
24881 @code{GNAT.Sockets.Thin}. Currently @code{GNAT.Sockets} is implemented
24882 on all native GNAT ports and on VxWorks cross prots. It is not implemented for
24883 the LynxOS cross port.
24885 @node GNAT Source_Info g-souinf ads,GNAT Spelling_Checker g-speche ads,GNAT Sockets g-socket ads,The GNAT Library
24886 @anchor{gnat_rm/the_gnat_library gnat-source-info-g-souinf-ads}@anchor{3ae}@anchor{gnat_rm/the_gnat_library id111}@anchor{3af}
24887 @section @code{GNAT.Source_Info} (@code{g-souinf.ads})
24890 @geindex GNAT.Source_Info (g-souinf.ads)
24892 @geindex Source Information
24894 Provides subprograms that give access to source code information known at
24895 compile time, such as the current file name and line number. Also provides
24896 subprograms yielding the date and time of the current compilation (like the
24897 C macros @code{__DATE__} and @code{__TIME__})
24899 @node GNAT Spelling_Checker g-speche ads,GNAT Spelling_Checker_Generic g-spchge ads,GNAT Source_Info g-souinf ads,The GNAT Library
24900 @anchor{gnat_rm/the_gnat_library id112}@anchor{3b0}@anchor{gnat_rm/the_gnat_library gnat-spelling-checker-g-speche-ads}@anchor{3b1}
24901 @section @code{GNAT.Spelling_Checker} (@code{g-speche.ads})
24904 @geindex GNAT.Spelling_Checker (g-speche.ads)
24906 @geindex Spell checking
24908 Provides a function for determining whether one string is a plausible
24909 near misspelling of another string.
24911 @node GNAT Spelling_Checker_Generic g-spchge ads,GNAT Spitbol Patterns g-spipat ads,GNAT Spelling_Checker g-speche ads,The GNAT Library
24912 @anchor{gnat_rm/the_gnat_library gnat-spelling-checker-generic-g-spchge-ads}@anchor{3b2}@anchor{gnat_rm/the_gnat_library id113}@anchor{3b3}
24913 @section @code{GNAT.Spelling_Checker_Generic} (@code{g-spchge.ads})
24916 @geindex GNAT.Spelling_Checker_Generic (g-spchge.ads)
24918 @geindex Spell checking
24920 Provides a generic function that can be instantiated with a string type for
24921 determining whether one string is a plausible near misspelling of another
24924 @node GNAT Spitbol Patterns g-spipat ads,GNAT Spitbol g-spitbo ads,GNAT Spelling_Checker_Generic g-spchge ads,The GNAT Library
24925 @anchor{gnat_rm/the_gnat_library gnat-spitbol-patterns-g-spipat-ads}@anchor{3b4}@anchor{gnat_rm/the_gnat_library id114}@anchor{3b5}
24926 @section @code{GNAT.Spitbol.Patterns} (@code{g-spipat.ads})
24929 @geindex GNAT.Spitbol.Patterns (g-spipat.ads)
24931 @geindex SPITBOL pattern matching
24933 @geindex Pattern matching
24935 A complete implementation of SNOBOL4 style pattern matching. This is the
24936 most elaborate of the pattern matching packages provided. It fully duplicates
24937 the SNOBOL4 dynamic pattern construction and matching capabilities, using the
24938 efficient algorithm developed by Robert Dewar for the SPITBOL system.
24940 @node GNAT Spitbol g-spitbo ads,GNAT Spitbol Table_Boolean g-sptabo ads,GNAT Spitbol Patterns g-spipat ads,The GNAT Library
24941 @anchor{gnat_rm/the_gnat_library gnat-spitbol-g-spitbo-ads}@anchor{3b6}@anchor{gnat_rm/the_gnat_library id115}@anchor{3b7}
24942 @section @code{GNAT.Spitbol} (@code{g-spitbo.ads})
24945 @geindex GNAT.Spitbol (g-spitbo.ads)
24947 @geindex SPITBOL interface
24949 The top level package of the collection of SPITBOL-style functionality, this
24950 package provides basic SNOBOL4 string manipulation functions, such as
24951 Pad, Reverse, Trim, Substr capability, as well as a generic table function
24952 useful for constructing arbitrary mappings from strings in the style of
24953 the SNOBOL4 TABLE function.
24955 @node GNAT Spitbol Table_Boolean g-sptabo ads,GNAT Spitbol Table_Integer g-sptain ads,GNAT Spitbol g-spitbo ads,The GNAT Library
24956 @anchor{gnat_rm/the_gnat_library id116}@anchor{3b8}@anchor{gnat_rm/the_gnat_library gnat-spitbol-table-boolean-g-sptabo-ads}@anchor{3b9}
24957 @section @code{GNAT.Spitbol.Table_Boolean} (@code{g-sptabo.ads})
24960 @geindex GNAT.Spitbol.Table_Boolean (g-sptabo.ads)
24962 @geindex Sets of strings
24964 @geindex SPITBOL Tables
24966 A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table}
24967 for type @code{Standard.Boolean}, giving an implementation of sets of
24970 @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
24971 @anchor{gnat_rm/the_gnat_library gnat-spitbol-table-integer-g-sptain-ads}@anchor{3ba}@anchor{gnat_rm/the_gnat_library id117}@anchor{3bb}
24972 @section @code{GNAT.Spitbol.Table_Integer} (@code{g-sptain.ads})
24975 @geindex GNAT.Spitbol.Table_Integer (g-sptain.ads)
24977 @geindex Integer maps
24981 @geindex SPITBOL Tables
24983 A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table}
24984 for type @code{Standard.Integer}, giving an implementation of maps
24985 from string to integer values.
24987 @node GNAT Spitbol Table_VString g-sptavs ads,GNAT SSE g-sse ads,GNAT Spitbol Table_Integer g-sptain ads,The GNAT Library
24988 @anchor{gnat_rm/the_gnat_library id118}@anchor{3bc}@anchor{gnat_rm/the_gnat_library gnat-spitbol-table-vstring-g-sptavs-ads}@anchor{3bd}
24989 @section @code{GNAT.Spitbol.Table_VString} (@code{g-sptavs.ads})
24992 @geindex GNAT.Spitbol.Table_VString (g-sptavs.ads)
24994 @geindex String maps
24998 @geindex SPITBOL Tables
25000 A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table} for
25001 a variable length string type, giving an implementation of general
25002 maps from strings to strings.
25004 @node GNAT SSE g-sse ads,GNAT SSE Vector_Types g-ssvety ads,GNAT Spitbol Table_VString g-sptavs ads,The GNAT Library
25005 @anchor{gnat_rm/the_gnat_library id119}@anchor{3be}@anchor{gnat_rm/the_gnat_library gnat-sse-g-sse-ads}@anchor{3bf}
25006 @section @code{GNAT.SSE} (@code{g-sse.ads})
25009 @geindex GNAT.SSE (g-sse.ads)
25011 Root of a set of units aimed at offering Ada bindings to a subset of
25012 the Intel(r) Streaming SIMD Extensions with GNAT on the x86 family of
25013 targets. It exposes vector component types together with a general
25014 introduction to the binding contents and use.
25016 @node GNAT SSE Vector_Types g-ssvety ads,GNAT String_Hash g-strhas ads,GNAT SSE g-sse ads,The GNAT Library
25017 @anchor{gnat_rm/the_gnat_library gnat-sse-vector-types-g-ssvety-ads}@anchor{3c0}@anchor{gnat_rm/the_gnat_library id120}@anchor{3c1}
25018 @section @code{GNAT.SSE.Vector_Types} (@code{g-ssvety.ads})
25021 @geindex GNAT.SSE.Vector_Types (g-ssvety.ads)
25023 SSE vector types for use with SSE related intrinsics.
25025 @node GNAT String_Hash g-strhas ads,GNAT Strings g-string ads,GNAT SSE Vector_Types g-ssvety ads,The GNAT Library
25026 @anchor{gnat_rm/the_gnat_library gnat-string-hash-g-strhas-ads}@anchor{3c2}@anchor{gnat_rm/the_gnat_library id121}@anchor{3c3}
25027 @section @code{GNAT.String_Hash} (@code{g-strhas.ads})
25030 @geindex GNAT.String_Hash (g-strhas.ads)
25032 @geindex Hash functions
25034 Provides a generic hash function working on arrays of scalars. Both the scalar
25035 type and the hash result type are parameters.
25037 @node GNAT Strings g-string ads,GNAT String_Split g-strspl ads,GNAT String_Hash g-strhas ads,The GNAT Library
25038 @anchor{gnat_rm/the_gnat_library gnat-strings-g-string-ads}@anchor{3c4}@anchor{gnat_rm/the_gnat_library id122}@anchor{3c5}
25039 @section @code{GNAT.Strings} (@code{g-string.ads})
25042 @geindex GNAT.Strings (g-string.ads)
25044 Common String access types and related subprograms. Basically it
25045 defines a string access and an array of string access types.
25047 @node GNAT String_Split g-strspl ads,GNAT Table g-table ads,GNAT Strings g-string ads,The GNAT Library
25048 @anchor{gnat_rm/the_gnat_library gnat-string-split-g-strspl-ads}@anchor{3c6}@anchor{gnat_rm/the_gnat_library id123}@anchor{3c7}
25049 @section @code{GNAT.String_Split} (@code{g-strspl.ads})
25052 @geindex GNAT.String_Split (g-strspl.ads)
25054 @geindex String splitter
25056 Useful string manipulation routines: given a set of separators, split
25057 a string wherever the separators appear, and provide direct access
25058 to the resulting slices. This package is instantiated from
25059 @code{GNAT.Array_Split}.
25061 @node GNAT Table g-table ads,GNAT Task_Lock g-tasloc ads,GNAT String_Split g-strspl ads,The GNAT Library
25062 @anchor{gnat_rm/the_gnat_library id124}@anchor{3c8}@anchor{gnat_rm/the_gnat_library gnat-table-g-table-ads}@anchor{3c9}
25063 @section @code{GNAT.Table} (@code{g-table.ads})
25066 @geindex GNAT.Table (g-table.ads)
25068 @geindex Table implementation
25071 @geindex extendable
25073 A generic package providing a single dimension array abstraction where the
25074 length of the array can be dynamically modified.
25076 This package provides a facility similar to that of @code{GNAT.Dynamic_Tables},
25077 except that this package declares a single instance of the table type,
25078 while an instantiation of @code{GNAT.Dynamic_Tables} creates a type that can be
25079 used to define dynamic instances of the table.
25081 @node GNAT Task_Lock g-tasloc ads,GNAT Time_Stamp g-timsta ads,GNAT Table g-table ads,The GNAT Library
25082 @anchor{gnat_rm/the_gnat_library id125}@anchor{3ca}@anchor{gnat_rm/the_gnat_library gnat-task-lock-g-tasloc-ads}@anchor{3cb}
25083 @section @code{GNAT.Task_Lock} (@code{g-tasloc.ads})
25086 @geindex GNAT.Task_Lock (g-tasloc.ads)
25088 @geindex Task synchronization
25090 @geindex Task locking
25094 A very simple facility for locking and unlocking sections of code using a
25095 single global task lock. Appropriate for use in situations where contention
25096 between tasks is very rarely expected.
25098 @node GNAT Time_Stamp g-timsta ads,GNAT Threads g-thread ads,GNAT Task_Lock g-tasloc ads,The GNAT Library
25099 @anchor{gnat_rm/the_gnat_library id126}@anchor{3cc}@anchor{gnat_rm/the_gnat_library gnat-time-stamp-g-timsta-ads}@anchor{3cd}
25100 @section @code{GNAT.Time_Stamp} (@code{g-timsta.ads})
25103 @geindex GNAT.Time_Stamp (g-timsta.ads)
25105 @geindex Time stamp
25107 @geindex Current time
25109 Provides a simple function that returns a string YYYY-MM-DD HH:MM:SS.SS that
25110 represents the current date and time in ISO 8601 format. This is a very simple
25111 routine with minimal code and there are no dependencies on any other unit.
25113 @node GNAT Threads g-thread ads,GNAT Traceback g-traceb ads,GNAT Time_Stamp g-timsta ads,The GNAT Library
25114 @anchor{gnat_rm/the_gnat_library id127}@anchor{3ce}@anchor{gnat_rm/the_gnat_library gnat-threads-g-thread-ads}@anchor{3cf}
25115 @section @code{GNAT.Threads} (@code{g-thread.ads})
25118 @geindex GNAT.Threads (g-thread.ads)
25120 @geindex Foreign threads
25125 Provides facilities for dealing with foreign threads which need to be known
25126 by the GNAT run-time system. Consult the documentation of this package for
25127 further details if your program has threads that are created by a non-Ada
25128 environment which then accesses Ada code.
25130 @node GNAT Traceback g-traceb ads,GNAT Traceback Symbolic g-trasym ads,GNAT Threads g-thread ads,The GNAT Library
25131 @anchor{gnat_rm/the_gnat_library id128}@anchor{3d0}@anchor{gnat_rm/the_gnat_library gnat-traceback-g-traceb-ads}@anchor{3d1}
25132 @section @code{GNAT.Traceback} (@code{g-traceb.ads})
25135 @geindex GNAT.Traceback (g-traceb.ads)
25137 @geindex Trace back facilities
25139 Provides a facility for obtaining non-symbolic traceback information, useful
25140 in various debugging situations.
25142 @node GNAT Traceback Symbolic g-trasym ads,GNAT UTF_32 g-table ads,GNAT Traceback g-traceb ads,The GNAT Library
25143 @anchor{gnat_rm/the_gnat_library gnat-traceback-symbolic-g-trasym-ads}@anchor{3d2}@anchor{gnat_rm/the_gnat_library id129}@anchor{3d3}
25144 @section @code{GNAT.Traceback.Symbolic} (@code{g-trasym.ads})
25147 @geindex GNAT.Traceback.Symbolic (g-trasym.ads)
25149 @geindex Trace back facilities
25151 @node GNAT UTF_32 g-table ads,GNAT Wide_Spelling_Checker g-u3spch ads,GNAT Traceback Symbolic g-trasym ads,The GNAT Library
25152 @anchor{gnat_rm/the_gnat_library id130}@anchor{3d4}@anchor{gnat_rm/the_gnat_library gnat-utf-32-g-table-ads}@anchor{3d5}
25153 @section @code{GNAT.UTF_32} (@code{g-table.ads})
25156 @geindex GNAT.UTF_32 (g-table.ads)
25158 @geindex Wide character codes
25160 This is a package intended to be used in conjunction with the
25161 @code{Wide_Character} type in Ada 95 and the
25162 @code{Wide_Wide_Character} type in Ada 2005 (available
25163 in @code{GNAT} in Ada 2005 mode). This package contains
25164 Unicode categorization routines, as well as lexical
25165 categorization routines corresponding to the Ada 2005
25166 lexical rules for identifiers and strings, and also a
25167 lower case to upper case fold routine corresponding to
25168 the Ada 2005 rules for identifier equivalence.
25170 @node GNAT Wide_Spelling_Checker g-u3spch ads,GNAT Wide_Spelling_Checker g-wispch ads,GNAT UTF_32 g-table ads,The GNAT Library
25171 @anchor{gnat_rm/the_gnat_library gnat-wide-spelling-checker-g-u3spch-ads}@anchor{3d6}@anchor{gnat_rm/the_gnat_library id131}@anchor{3d7}
25172 @section @code{GNAT.Wide_Spelling_Checker} (@code{g-u3spch.ads})
25175 @geindex GNAT.Wide_Spelling_Checker (g-u3spch.ads)
25177 @geindex Spell checking
25179 Provides a function for determining whether one wide wide string is a plausible
25180 near misspelling of another wide wide string, where the strings are represented
25181 using the UTF_32_String type defined in System.Wch_Cnv.
25183 @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
25184 @anchor{gnat_rm/the_gnat_library gnat-wide-spelling-checker-g-wispch-ads}@anchor{3d8}@anchor{gnat_rm/the_gnat_library id132}@anchor{3d9}
25185 @section @code{GNAT.Wide_Spelling_Checker} (@code{g-wispch.ads})
25188 @geindex GNAT.Wide_Spelling_Checker (g-wispch.ads)
25190 @geindex Spell checking
25192 Provides a function for determining whether one wide string is a plausible
25193 near misspelling of another wide string.
25195 @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
25196 @anchor{gnat_rm/the_gnat_library id133}@anchor{3da}@anchor{gnat_rm/the_gnat_library gnat-wide-string-split-g-wistsp-ads}@anchor{3db}
25197 @section @code{GNAT.Wide_String_Split} (@code{g-wistsp.ads})
25200 @geindex GNAT.Wide_String_Split (g-wistsp.ads)
25202 @geindex Wide_String splitter
25204 Useful wide string manipulation routines: given a set of separators, split
25205 a wide string wherever the separators appear, and provide direct access
25206 to the resulting slices. This package is instantiated from
25207 @code{GNAT.Array_Split}.
25209 @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
25210 @anchor{gnat_rm/the_gnat_library gnat-wide-wide-spelling-checker-g-zspche-ads}@anchor{3dc}@anchor{gnat_rm/the_gnat_library id134}@anchor{3dd}
25211 @section @code{GNAT.Wide_Wide_Spelling_Checker} (@code{g-zspche.ads})
25214 @geindex GNAT.Wide_Wide_Spelling_Checker (g-zspche.ads)
25216 @geindex Spell checking
25218 Provides a function for determining whether one wide wide string is a plausible
25219 near misspelling of another wide wide string.
25221 @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
25222 @anchor{gnat_rm/the_gnat_library gnat-wide-wide-string-split-g-zistsp-ads}@anchor{3de}@anchor{gnat_rm/the_gnat_library id135}@anchor{3df}
25223 @section @code{GNAT.Wide_Wide_String_Split} (@code{g-zistsp.ads})
25226 @geindex GNAT.Wide_Wide_String_Split (g-zistsp.ads)
25228 @geindex Wide_Wide_String splitter
25230 Useful wide wide string manipulation routines: given a set of separators, split
25231 a wide wide string wherever the separators appear, and provide direct access
25232 to the resulting slices. This package is instantiated from
25233 @code{GNAT.Array_Split}.
25235 @node Interfaces C Extensions i-cexten ads,Interfaces C Streams i-cstrea ads,GNAT Wide_Wide_String_Split g-zistsp ads,The GNAT Library
25236 @anchor{gnat_rm/the_gnat_library interfaces-c-extensions-i-cexten-ads}@anchor{3e0}@anchor{gnat_rm/the_gnat_library id136}@anchor{3e1}
25237 @section @code{Interfaces.C.Extensions} (@code{i-cexten.ads})
25240 @geindex Interfaces.C.Extensions (i-cexten.ads)
25242 This package contains additional C-related definitions, intended
25243 for use with either manually or automatically generated bindings
25246 @node Interfaces C Streams i-cstrea ads,Interfaces Packed_Decimal i-pacdec ads,Interfaces C Extensions i-cexten ads,The GNAT Library
25247 @anchor{gnat_rm/the_gnat_library interfaces-c-streams-i-cstrea-ads}@anchor{3e2}@anchor{gnat_rm/the_gnat_library id137}@anchor{3e3}
25248 @section @code{Interfaces.C.Streams} (@code{i-cstrea.ads})
25251 @geindex Interfaces.C.Streams (i-cstrea.ads)
25254 @geindex interfacing
25256 This package is a binding for the most commonly used operations
25259 @node Interfaces Packed_Decimal i-pacdec ads,Interfaces VxWorks i-vxwork ads,Interfaces C Streams i-cstrea ads,The GNAT Library
25260 @anchor{gnat_rm/the_gnat_library id138}@anchor{3e4}@anchor{gnat_rm/the_gnat_library interfaces-packed-decimal-i-pacdec-ads}@anchor{3e5}
25261 @section @code{Interfaces.Packed_Decimal} (@code{i-pacdec.ads})
25264 @geindex Interfaces.Packed_Decimal (i-pacdec.ads)
25266 @geindex IBM Packed Format
25268 @geindex Packed Decimal
25270 This package provides a set of routines for conversions to and
25271 from a packed decimal format compatible with that used on IBM
25274 @node Interfaces VxWorks i-vxwork ads,Interfaces VxWorks Int_Connection i-vxinco ads,Interfaces Packed_Decimal i-pacdec ads,The GNAT Library
25275 @anchor{gnat_rm/the_gnat_library id139}@anchor{3e6}@anchor{gnat_rm/the_gnat_library interfaces-vxworks-i-vxwork-ads}@anchor{3e7}
25276 @section @code{Interfaces.VxWorks} (@code{i-vxwork.ads})
25279 @geindex Interfaces.VxWorks (i-vxwork.ads)
25281 @geindex Interfacing to VxWorks
25284 @geindex interfacing
25286 This package provides a limited binding to the VxWorks API.
25287 In particular, it interfaces with the
25288 VxWorks hardware interrupt facilities.
25290 @node Interfaces VxWorks Int_Connection i-vxinco ads,Interfaces VxWorks IO i-vxwoio ads,Interfaces VxWorks i-vxwork ads,The GNAT Library
25291 @anchor{gnat_rm/the_gnat_library interfaces-vxworks-int-connection-i-vxinco-ads}@anchor{3e8}@anchor{gnat_rm/the_gnat_library id140}@anchor{3e9}
25292 @section @code{Interfaces.VxWorks.Int_Connection} (@code{i-vxinco.ads})
25295 @geindex Interfaces.VxWorks.Int_Connection (i-vxinco.ads)
25297 @geindex Interfacing to VxWorks
25300 @geindex interfacing
25302 This package provides a way for users to replace the use of
25303 intConnect() with a custom routine for installing interrupt
25306 @node Interfaces VxWorks IO i-vxwoio ads,System Address_Image s-addima ads,Interfaces VxWorks Int_Connection i-vxinco ads,The GNAT Library
25307 @anchor{gnat_rm/the_gnat_library interfaces-vxworks-io-i-vxwoio-ads}@anchor{3ea}@anchor{gnat_rm/the_gnat_library id141}@anchor{3eb}
25308 @section @code{Interfaces.VxWorks.IO} (@code{i-vxwoio.ads})
25311 @geindex Interfaces.VxWorks.IO (i-vxwoio.ads)
25313 @geindex Interfacing to VxWorks' I/O
25316 @geindex I/O interfacing
25319 @geindex Get_Immediate
25321 @geindex Get_Immediate
25324 This package provides a binding to the ioctl (IO/Control)
25325 function of VxWorks, defining a set of option values and
25326 function codes. A particular use of this package is
25327 to enable the use of Get_Immediate under VxWorks.
25329 @node System Address_Image s-addima ads,System Assertions s-assert ads,Interfaces VxWorks IO i-vxwoio ads,The GNAT Library
25330 @anchor{gnat_rm/the_gnat_library system-address-image-s-addima-ads}@anchor{3ec}@anchor{gnat_rm/the_gnat_library id142}@anchor{3ed}
25331 @section @code{System.Address_Image} (@code{s-addima.ads})
25334 @geindex System.Address_Image (s-addima.ads)
25336 @geindex Address image
25339 @geindex of an address
25341 This function provides a useful debugging
25342 function that gives an (implementation dependent)
25343 string which identifies an address.
25345 @node System Assertions s-assert ads,System Atomic_Counters s-atocou ads,System Address_Image s-addima ads,The GNAT Library
25346 @anchor{gnat_rm/the_gnat_library system-assertions-s-assert-ads}@anchor{3ee}@anchor{gnat_rm/the_gnat_library id143}@anchor{3ef}
25347 @section @code{System.Assertions} (@code{s-assert.ads})
25350 @geindex System.Assertions (s-assert.ads)
25352 @geindex Assertions
25354 @geindex Assert_Failure
25357 This package provides the declaration of the exception raised
25358 by an run-time assertion failure, as well as the routine that
25359 is used internally to raise this assertion.
25361 @node System Atomic_Counters s-atocou ads,System Memory s-memory ads,System Assertions s-assert ads,The GNAT Library
25362 @anchor{gnat_rm/the_gnat_library id144}@anchor{3f0}@anchor{gnat_rm/the_gnat_library system-atomic-counters-s-atocou-ads}@anchor{3f1}
25363 @section @code{System.Atomic_Counters} (@code{s-atocou.ads})
25366 @geindex System.Atomic_Counters (s-atocou.ads)
25368 This package provides the declaration of an atomic counter type,
25369 together with efficient routines (using hardware
25370 synchronization primitives) for incrementing, decrementing,
25371 and testing of these counters. This package is implemented
25372 on most targets, including all Alpha, ia64, PowerPC, SPARC V9,
25373 x86, and x86_64 platforms.
25375 @node System Memory s-memory ads,System Multiprocessors s-multip ads,System Atomic_Counters s-atocou ads,The GNAT Library
25376 @anchor{gnat_rm/the_gnat_library system-memory-s-memory-ads}@anchor{3f2}@anchor{gnat_rm/the_gnat_library id145}@anchor{3f3}
25377 @section @code{System.Memory} (@code{s-memory.ads})
25380 @geindex System.Memory (s-memory.ads)
25382 @geindex Memory allocation
25384 This package provides the interface to the low level routines used
25385 by the generated code for allocation and freeing storage for the
25386 default storage pool (analogous to the C routines malloc and free.
25387 It also provides a reallocation interface analogous to the C routine
25388 realloc. The body of this unit may be modified to provide alternative
25389 allocation mechanisms for the default pool, and in addition, direct
25390 calls to this unit may be made for low level allocation uses (for
25391 example see the body of @code{GNAT.Tables}).
25393 @node System Multiprocessors s-multip ads,System Multiprocessors Dispatching_Domains s-mudido ads,System Memory s-memory ads,The GNAT Library
25394 @anchor{gnat_rm/the_gnat_library id146}@anchor{3f4}@anchor{gnat_rm/the_gnat_library system-multiprocessors-s-multip-ads}@anchor{3f5}
25395 @section @code{System.Multiprocessors} (@code{s-multip.ads})
25398 @geindex System.Multiprocessors (s-multip.ads)
25400 @geindex Multiprocessor interface
25402 This is an Ada 2012 unit defined in the Ada 2012 Reference Manual, but
25403 in GNAT we also make it available in Ada 95 and Ada 2005 (where it is
25404 technically an implementation-defined addition).
25406 @node System Multiprocessors Dispatching_Domains s-mudido ads,System Partition_Interface s-parint ads,System Multiprocessors s-multip ads,The GNAT Library
25407 @anchor{gnat_rm/the_gnat_library system-multiprocessors-dispatching-domains-s-mudido-ads}@anchor{3f6}@anchor{gnat_rm/the_gnat_library id147}@anchor{3f7}
25408 @section @code{System.Multiprocessors.Dispatching_Domains} (@code{s-mudido.ads})
25411 @geindex System.Multiprocessors.Dispatching_Domains (s-mudido.ads)
25413 @geindex Multiprocessor interface
25415 This is an Ada 2012 unit defined in the Ada 2012 Reference Manual, but
25416 in GNAT we also make it available in Ada 95 and Ada 2005 (where it is
25417 technically an implementation-defined addition).
25419 @node System Partition_Interface s-parint ads,System Pool_Global s-pooglo ads,System Multiprocessors Dispatching_Domains s-mudido ads,The GNAT Library
25420 @anchor{gnat_rm/the_gnat_library id148}@anchor{3f8}@anchor{gnat_rm/the_gnat_library system-partition-interface-s-parint-ads}@anchor{3f9}
25421 @section @code{System.Partition_Interface} (@code{s-parint.ads})
25424 @geindex System.Partition_Interface (s-parint.ads)
25426 @geindex Partition interfacing functions
25428 This package provides facilities for partition interfacing. It
25429 is used primarily in a distribution context when using Annex E
25432 @node System Pool_Global s-pooglo ads,System Pool_Local s-pooloc ads,System Partition_Interface s-parint ads,The GNAT Library
25433 @anchor{gnat_rm/the_gnat_library id149}@anchor{3fa}@anchor{gnat_rm/the_gnat_library system-pool-global-s-pooglo-ads}@anchor{3fb}
25434 @section @code{System.Pool_Global} (@code{s-pooglo.ads})
25437 @geindex System.Pool_Global (s-pooglo.ads)
25439 @geindex Storage pool
25442 @geindex Global storage pool
25444 This package provides a storage pool that is equivalent to the default
25445 storage pool used for access types for which no pool is specifically
25446 declared. It uses malloc/free to allocate/free and does not attempt to
25447 do any automatic reclamation.
25449 @node System Pool_Local s-pooloc ads,System Restrictions s-restri ads,System Pool_Global s-pooglo ads,The GNAT Library
25450 @anchor{gnat_rm/the_gnat_library system-pool-local-s-pooloc-ads}@anchor{3fc}@anchor{gnat_rm/the_gnat_library id150}@anchor{3fd}
25451 @section @code{System.Pool_Local} (@code{s-pooloc.ads})
25454 @geindex System.Pool_Local (s-pooloc.ads)
25456 @geindex Storage pool
25459 @geindex Local storage pool
25461 This package provides a storage pool that is intended for use with locally
25462 defined access types. It uses malloc/free for allocate/free, and maintains
25463 a list of allocated blocks, so that all storage allocated for the pool can
25464 be freed automatically when the pool is finalized.
25466 @node System Restrictions s-restri ads,System Rident s-rident ads,System Pool_Local s-pooloc ads,The GNAT Library
25467 @anchor{gnat_rm/the_gnat_library system-restrictions-s-restri-ads}@anchor{3fe}@anchor{gnat_rm/the_gnat_library id151}@anchor{3ff}
25468 @section @code{System.Restrictions} (@code{s-restri.ads})
25471 @geindex System.Restrictions (s-restri.ads)
25473 @geindex Run-time restrictions access
25475 This package provides facilities for accessing at run time
25476 the status of restrictions specified at compile time for
25477 the partition. Information is available both with regard
25478 to actual restrictions specified, and with regard to
25479 compiler determined information on which restrictions
25480 are violated by one or more packages in the partition.
25482 @node System Rident s-rident ads,System Strings Stream_Ops s-ststop ads,System Restrictions s-restri ads,The GNAT Library
25483 @anchor{gnat_rm/the_gnat_library system-rident-s-rident-ads}@anchor{400}@anchor{gnat_rm/the_gnat_library id152}@anchor{401}
25484 @section @code{System.Rident} (@code{s-rident.ads})
25487 @geindex System.Rident (s-rident.ads)
25489 @geindex Restrictions definitions
25491 This package provides definitions of the restrictions
25492 identifiers supported by GNAT, and also the format of
25493 the restrictions provided in package System.Restrictions.
25494 It is not normally necessary to @code{with} this generic package
25495 since the necessary instantiation is included in
25496 package System.Restrictions.
25498 @node System Strings Stream_Ops s-ststop ads,System Unsigned_Types s-unstyp ads,System Rident s-rident ads,The GNAT Library
25499 @anchor{gnat_rm/the_gnat_library id153}@anchor{402}@anchor{gnat_rm/the_gnat_library system-strings-stream-ops-s-ststop-ads}@anchor{403}
25500 @section @code{System.Strings.Stream_Ops} (@code{s-ststop.ads})
25503 @geindex System.Strings.Stream_Ops (s-ststop.ads)
25505 @geindex Stream operations
25507 @geindex String stream operations
25509 This package provides a set of stream subprograms for standard string types.
25510 It is intended primarily to support implicit use of such subprograms when
25511 stream attributes are applied to string types, but the subprograms in this
25512 package can be used directly by application programs.
25514 @node System Unsigned_Types s-unstyp ads,System Wch_Cnv s-wchcnv ads,System Strings Stream_Ops s-ststop ads,The GNAT Library
25515 @anchor{gnat_rm/the_gnat_library system-unsigned-types-s-unstyp-ads}@anchor{404}@anchor{gnat_rm/the_gnat_library id154}@anchor{405}
25516 @section @code{System.Unsigned_Types} (@code{s-unstyp.ads})
25519 @geindex System.Unsigned_Types (s-unstyp.ads)
25521 This package contains definitions of standard unsigned types that
25522 correspond in size to the standard signed types declared in Standard,
25523 and (unlike the types in Interfaces) have corresponding names. It
25524 also contains some related definitions for other specialized types
25525 used by the compiler in connection with packed array types.
25527 @node System Wch_Cnv s-wchcnv ads,System Wch_Con s-wchcon ads,System Unsigned_Types s-unstyp ads,The GNAT Library
25528 @anchor{gnat_rm/the_gnat_library system-wch-cnv-s-wchcnv-ads}@anchor{406}@anchor{gnat_rm/the_gnat_library id155}@anchor{407}
25529 @section @code{System.Wch_Cnv} (@code{s-wchcnv.ads})
25532 @geindex System.Wch_Cnv (s-wchcnv.ads)
25534 @geindex Wide Character
25535 @geindex Representation
25537 @geindex Wide String
25538 @geindex Conversion
25540 @geindex Representation of wide characters
25542 This package provides routines for converting between
25543 wide and wide wide characters and a representation as a value of type
25544 @code{Standard.String}, using a specified wide character
25545 encoding method. It uses definitions in
25546 package @code{System.Wch_Con}.
25548 @node System Wch_Con s-wchcon ads,,System Wch_Cnv s-wchcnv ads,The GNAT Library
25549 @anchor{gnat_rm/the_gnat_library id156}@anchor{408}@anchor{gnat_rm/the_gnat_library system-wch-con-s-wchcon-ads}@anchor{409}
25550 @section @code{System.Wch_Con} (@code{s-wchcon.ads})
25553 @geindex System.Wch_Con (s-wchcon.ads)
25555 This package provides definitions and descriptions of
25556 the various methods used for encoding wide characters
25557 in ordinary strings. These definitions are used by
25558 the package @code{System.Wch_Cnv}.
25560 @node Interfacing to Other Languages,Specialized Needs Annexes,The GNAT Library,Top
25561 @anchor{gnat_rm/interfacing_to_other_languages interfacing-to-other-languages}@anchor{11}@anchor{gnat_rm/interfacing_to_other_languages doc}@anchor{40a}@anchor{gnat_rm/interfacing_to_other_languages id1}@anchor{40b}
25562 @chapter Interfacing to Other Languages
25565 The facilities in Annex B of the Ada Reference Manual are fully
25566 implemented in GNAT, and in addition, a full interface to C++ is
25570 * Interfacing to C::
25571 * Interfacing to C++::
25572 * Interfacing to COBOL::
25573 * Interfacing to Fortran::
25574 * Interfacing to non-GNAT Ada code::
25578 @node Interfacing to C,Interfacing to C++,,Interfacing to Other Languages
25579 @anchor{gnat_rm/interfacing_to_other_languages interfacing-to-c}@anchor{40c}@anchor{gnat_rm/interfacing_to_other_languages id2}@anchor{40d}
25580 @section Interfacing to C
25583 Interfacing to C with GNAT can use one of two approaches:
25589 The types in the package @code{Interfaces.C} may be used.
25592 Standard Ada types may be used directly. This may be less portable to
25593 other compilers, but will work on all GNAT compilers, which guarantee
25594 correspondence between the C and Ada types.
25597 Pragma @code{Convention C} may be applied to Ada types, but mostly has no
25598 effect, since this is the default. The following table shows the
25599 correspondence between Ada scalar types and the corresponding C types.
25602 @multitable {xxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
25621 @code{Short_Integer}
25629 @code{Short_Short_Integer}
25637 @code{Long_Integer}
25645 @code{Long_Long_Integer}
25677 @code{Long_Long_Float}
25681 This is the longest floating-point type supported by the hardware.
25686 Additionally, there are the following general correspondences between Ada
25693 Ada enumeration types map to C enumeration types directly if pragma
25694 @code{Convention C} is specified, which causes them to have a length of
25695 32 bits, except for boolean types which map to C99 @code{bool} and for
25696 which the length is 8 bits.
25697 Without pragma @code{Convention C}, Ada enumeration types map to
25698 8, 16, or 32 bits (i.e., C types @code{signed char}, @code{short},
25699 @code{int}, respectively) depending on the number of values passed.
25700 This is the only case in which pragma @code{Convention C} affects the
25701 representation of an Ada type.
25704 Ada access types map to C pointers, except for the case of pointers to
25705 unconstrained types in Ada, which have no direct C equivalent.
25708 Ada arrays map directly to C arrays.
25711 Ada records map directly to C structures.
25714 Packed Ada records map to C structures where all members are bit fields
25715 of the length corresponding to the @code{type'Size} value in Ada.
25718 @node Interfacing to C++,Interfacing to COBOL,Interfacing to C,Interfacing to Other Languages
25719 @anchor{gnat_rm/interfacing_to_other_languages id4}@anchor{40e}@anchor{gnat_rm/interfacing_to_other_languages id3}@anchor{4a}
25720 @section Interfacing to C++
25723 The interface to C++ makes use of the following pragmas, which are
25724 primarily intended to be constructed automatically using a binding generator
25725 tool, although it is possible to construct them by hand.
25727 Using these pragmas it is possible to achieve complete
25728 inter-operability between Ada tagged types and C++ class definitions.
25729 See @ref{7,,Implementation Defined Pragmas}, for more details.
25734 @item @code{pragma CPP_Class ([Entity =>] @emph{LOCAL_NAME})}
25736 The argument denotes an entity in the current declarative region that is
25737 declared as a tagged or untagged record type. It indicates that the type
25738 corresponds to an externally declared C++ class type, and is to be laid
25739 out the same way that C++ would lay out the type.
25741 Note: Pragma @code{CPP_Class} is currently obsolete. It is supported
25742 for backward compatibility but its functionality is available
25743 using pragma @code{Import} with @code{Convention} = @code{CPP}.
25745 @item @code{pragma CPP_Constructor ([Entity =>] @emph{LOCAL_NAME})}
25747 This pragma identifies an imported function (imported in the usual way
25748 with pragma @code{Import}) as corresponding to a C++ constructor.
25751 A few restrictions are placed on the use of the @code{Access} attribute
25752 in conjunction with subprograms subject to convention @code{CPP}: the
25753 attribute may be used neither on primitive operations of a tagged
25754 record type with convention @code{CPP}, imported or not, nor on
25755 subprograms imported with pragma @code{CPP_Constructor}.
25757 In addition, C++ exceptions are propagated and can be handled in an
25758 @code{others} choice of an exception handler. The corresponding Ada
25759 occurrence has no message, and the simple name of the exception identity
25760 contains @code{Foreign_Exception}. Finalization and awaiting dependent
25761 tasks works properly when such foreign exceptions are propagated.
25763 It is also possible to import a C++ exception using the following syntax:
25766 LOCAL_NAME : exception;
25767 pragma Import (Cpp,
25768 [Entity =>] LOCAL_NAME,
25769 [External_Name =>] static_string_EXPRESSION);
25772 The @code{External_Name} is the name of the C++ RTTI symbol. You can then
25773 cover a specific C++ exception in an exception handler.
25775 @node Interfacing to COBOL,Interfacing to Fortran,Interfacing to C++,Interfacing to Other Languages
25776 @anchor{gnat_rm/interfacing_to_other_languages id5}@anchor{40f}@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-cobol}@anchor{410}
25777 @section Interfacing to COBOL
25780 Interfacing to COBOL is achieved as described in section B.4 of
25781 the Ada Reference Manual.
25783 @node Interfacing to Fortran,Interfacing to non-GNAT Ada code,Interfacing to COBOL,Interfacing to Other Languages
25784 @anchor{gnat_rm/interfacing_to_other_languages id6}@anchor{411}@anchor{gnat_rm/interfacing_to_other_languages interfacing-to-fortran}@anchor{412}
25785 @section Interfacing to Fortran
25788 Interfacing to Fortran is achieved as described in section B.5 of the
25789 Ada Reference Manual. The pragma @code{Convention Fortran}, applied to a
25790 multi-dimensional array causes the array to be stored in column-major
25791 order as required for convenient interface to Fortran.
25793 @node Interfacing to non-GNAT Ada code,,Interfacing to Fortran,Interfacing to Other Languages
25794 @anchor{gnat_rm/interfacing_to_other_languages interfacing-to-non-gnat-ada-code}@anchor{413}@anchor{gnat_rm/interfacing_to_other_languages id7}@anchor{414}
25795 @section Interfacing to non-GNAT Ada code
25798 It is possible to specify the convention @code{Ada} in a pragma
25799 @code{Import} or pragma @code{Export}. However this refers to
25800 the calling conventions used by GNAT, which may or may not be
25801 similar enough to those used by some other Ada 83 / Ada 95 / Ada 2005
25802 compiler to allow interoperation.
25804 If arguments types are kept simple, and if the foreign compiler generally
25805 follows system calling conventions, then it may be possible to integrate
25806 files compiled by other Ada compilers, provided that the elaboration
25807 issues are adequately addressed (for example by eliminating the
25808 need for any load time elaboration).
25810 In particular, GNAT running on VMS is designed to
25811 be highly compatible with the DEC Ada 83 compiler, so this is one
25812 case in which it is possible to import foreign units of this type,
25813 provided that the data items passed are restricted to simple scalar
25814 values or simple record types without variants, or simple array
25815 types with fixed bounds.
25817 @node Specialized Needs Annexes,Implementation of Specific Ada Features,Interfacing to Other Languages,Top
25818 @anchor{gnat_rm/specialized_needs_annexes specialized-needs-annexes}@anchor{12}@anchor{gnat_rm/specialized_needs_annexes doc}@anchor{415}@anchor{gnat_rm/specialized_needs_annexes id1}@anchor{416}
25819 @chapter Specialized Needs Annexes
25822 Ada 95, Ada 2005, and Ada 2012 define a number of Specialized Needs Annexes, which are not
25823 required in all implementations. However, as described in this chapter,
25824 GNAT implements all of these annexes:
25829 @item @emph{Systems Programming (Annex C)}
25831 The Systems Programming Annex is fully implemented.
25833 @item @emph{Real-Time Systems (Annex D)}
25835 The Real-Time Systems Annex is fully implemented.
25837 @item @emph{Distributed Systems (Annex E)}
25839 Stub generation is fully implemented in the GNAT compiler. In addition,
25840 a complete compatible PCS is available as part of the GLADE system,
25841 a separate product. When the two
25842 products are used in conjunction, this annex is fully implemented.
25844 @item @emph{Information Systems (Annex F)}
25846 The Information Systems annex is fully implemented.
25848 @item @emph{Numerics (Annex G)}
25850 The Numerics Annex is fully implemented.
25852 @item @emph{Safety and Security / High-Integrity Systems (Annex H)}
25854 The Safety and Security Annex (termed the High-Integrity Systems Annex
25855 in Ada 2005) is fully implemented.
25858 @node Implementation of Specific Ada Features,Implementation of Ada 2012 Features,Specialized Needs Annexes,Top
25859 @anchor{gnat_rm/implementation_of_specific_ada_features implementation-of-specific-ada-features}@anchor{13}@anchor{gnat_rm/implementation_of_specific_ada_features doc}@anchor{417}@anchor{gnat_rm/implementation_of_specific_ada_features id1}@anchor{418}
25860 @chapter Implementation of Specific Ada Features
25863 This chapter describes the GNAT implementation of several Ada language
25867 * Machine Code Insertions::
25868 * GNAT Implementation of Tasking::
25869 * GNAT Implementation of Shared Passive Packages::
25870 * Code Generation for Array Aggregates::
25871 * The Size of Discriminated Records with Default Discriminants::
25872 * Strict Conformance to the Ada Reference Manual::
25876 @node Machine Code Insertions,GNAT Implementation of Tasking,,Implementation of Specific Ada Features
25877 @anchor{gnat_rm/implementation_of_specific_ada_features machine-code-insertions}@anchor{16d}@anchor{gnat_rm/implementation_of_specific_ada_features id2}@anchor{419}
25878 @section Machine Code Insertions
25881 @geindex Machine Code insertions
25883 Package @code{Machine_Code} provides machine code support as described
25884 in the Ada Reference Manual in two separate forms:
25890 Machine code statements, consisting of qualified expressions that
25891 fit the requirements of RM section 13.8.
25894 An intrinsic callable procedure, providing an alternative mechanism of
25895 including machine instructions in a subprogram.
25898 The two features are similar, and both are closely related to the mechanism
25899 provided by the asm instruction in the GNU C compiler. Full understanding
25900 and use of the facilities in this package requires understanding the asm
25901 instruction, see the section on Extended Asm in
25902 @cite{Using_the_GNU_Compiler_Collection_(GCC)}.
25904 Calls to the function @code{Asm} and the procedure @code{Asm} have identical
25905 semantic restrictions and effects as described below. Both are provided so
25906 that the procedure call can be used as a statement, and the function call
25907 can be used to form a code_statement.
25909 Consider this C @code{asm} instruction:
25912 asm ("fsinx %1 %0" : "=f" (result) : "f" (angle));
25915 The equivalent can be written for GNAT as:
25918 Asm ("fsinx %1 %0",
25919 My_Float'Asm_Output ("=f", result),
25920 My_Float'Asm_Input ("f", angle));
25923 The first argument to @code{Asm} is the assembler template, and is
25924 identical to what is used in GNU C. This string must be a static
25925 expression. The second argument is the output operand list. It is
25926 either a single @code{Asm_Output} attribute reference, or a list of such
25927 references enclosed in parentheses (technically an array aggregate of
25930 The @code{Asm_Output} attribute denotes a function that takes two
25931 parameters. The first is a string, the second is the name of a variable
25932 of the type designated by the attribute prefix. The first (string)
25933 argument is required to be a static expression and designates the
25934 constraint (see the section on Constraints in
25935 @cite{Using_the_GNU_Compiler_Collection_(GCC)})
25936 for the parameter; e.g., what kind of register is required. The second
25937 argument is the variable to be written or updated with the
25938 result. The possible values for constraint are the same as those used in
25939 the RTL, and are dependent on the configuration file used to build the
25940 GCC back end. If there are no output operands, then this argument may
25941 either be omitted, or explicitly given as @code{No_Output_Operands}.
25942 No support is provided for GNU C's symbolic names for output parameters.
25944 The second argument of @code{my_float'Asm_Output} functions as
25945 though it were an @code{out} parameter, which is a little curious, but
25946 all names have the form of expressions, so there is no syntactic
25947 irregularity, even though normally functions would not be permitted
25948 @code{out} parameters. The third argument is the list of input
25949 operands. It is either a single @code{Asm_Input} attribute reference, or
25950 a list of such references enclosed in parentheses (technically an array
25951 aggregate of such references).
25953 The @code{Asm_Input} attribute denotes a function that takes two
25954 parameters. The first is a string, the second is an expression of the
25955 type designated by the prefix. The first (string) argument is required
25956 to be a static expression, and is the constraint for the parameter,
25957 (e.g., what kind of register is required). The second argument is the
25958 value to be used as the input argument. The possible values for the
25959 constraint are the same as those used in the RTL, and are dependent on
25960 the configuration file used to built the GCC back end.
25961 No support is provided for GNU C's symbolic names for input parameters.
25963 If there are no input operands, this argument may either be omitted, or
25964 explicitly given as @code{No_Input_Operands}. The fourth argument, not
25965 present in the above example, is a list of register names, called the
25966 @emph{clobber} argument. This argument, if given, must be a static string
25967 expression, and is a space or comma separated list of names of registers
25968 that must be considered destroyed as a result of the @code{Asm} call. If
25969 this argument is the null string (the default value), then the code
25970 generator assumes that no additional registers are destroyed.
25971 In addition to registers, the special clobbers @code{memory} and
25972 @code{cc} as described in the GNU C docs are both supported.
25974 The fifth argument, not present in the above example, called the
25975 @emph{volatile} argument, is by default @code{False}. It can be set to
25976 the literal value @code{True} to indicate to the code generator that all
25977 optimizations with respect to the instruction specified should be
25978 suppressed, and in particular an instruction that has outputs
25979 will still be generated, even if none of the outputs are
25980 used. See @cite{Using_the_GNU_Compiler_Collection_(GCC)}
25981 for the full description.
25982 Generally it is strongly advisable to use Volatile for any ASM statement
25983 that is missing either input or output operands or to avoid unwanted
25984 optimizations. A warning is generated if this advice is not followed.
25986 No support is provided for GNU C's @code{asm goto} feature.
25988 The @code{Asm} subprograms may be used in two ways. First the procedure
25989 forms can be used anywhere a procedure call would be valid, and
25990 correspond to what the RM calls 'intrinsic' routines. Such calls can
25991 be used to intersperse machine instructions with other Ada statements.
25992 Second, the function forms, which return a dummy value of the limited
25993 private type @code{Asm_Insn}, can be used in code statements, and indeed
25994 this is the only context where such calls are allowed. Code statements
25995 appear as aggregates of the form:
25998 Asm_Insn'(Asm (...));
25999 Asm_Insn'(Asm_Volatile (...));
26002 In accordance with RM rules, such code statements are allowed only
26003 within subprograms whose entire body consists of such statements. It is
26004 not permissible to intermix such statements with other Ada statements.
26006 Typically the form using intrinsic procedure calls is more convenient
26007 and more flexible. The code statement form is provided to meet the RM
26008 suggestion that such a facility should be made available. The following
26009 is the exact syntax of the call to @code{Asm}. As usual, if named notation
26010 is used, the arguments may be given in arbitrary order, following the
26011 normal rules for use of positional and named arguments:
26015 [Template =>] static_string_EXPRESSION
26016 [,[Outputs =>] OUTPUT_OPERAND_LIST ]
26017 [,[Inputs =>] INPUT_OPERAND_LIST ]
26018 [,[Clobber =>] static_string_EXPRESSION ]
26019 [,[Volatile =>] static_boolean_EXPRESSION] )
26021 OUTPUT_OPERAND_LIST ::=
26022 [PREFIX.]No_Output_Operands
26023 | OUTPUT_OPERAND_ATTRIBUTE
26024 | (OUTPUT_OPERAND_ATTRIBUTE @{,OUTPUT_OPERAND_ATTRIBUTE@})
26026 OUTPUT_OPERAND_ATTRIBUTE ::=
26027 SUBTYPE_MARK'Asm_Output (static_string_EXPRESSION, NAME)
26029 INPUT_OPERAND_LIST ::=
26030 [PREFIX.]No_Input_Operands
26031 | INPUT_OPERAND_ATTRIBUTE
26032 | (INPUT_OPERAND_ATTRIBUTE @{,INPUT_OPERAND_ATTRIBUTE@})
26034 INPUT_OPERAND_ATTRIBUTE ::=
26035 SUBTYPE_MARK'Asm_Input (static_string_EXPRESSION, EXPRESSION)
26038 The identifiers @code{No_Input_Operands} and @code{No_Output_Operands}
26039 are declared in the package @code{Machine_Code} and must be referenced
26040 according to normal visibility rules. In particular if there is no
26041 @code{use} clause for this package, then appropriate package name
26042 qualification is required.
26044 @node GNAT Implementation of Tasking,GNAT Implementation of Shared Passive Packages,Machine Code Insertions,Implementation of Specific Ada Features
26045 @anchor{gnat_rm/implementation_of_specific_ada_features id3}@anchor{41a}@anchor{gnat_rm/implementation_of_specific_ada_features gnat-implementation-of-tasking}@anchor{41b}
26046 @section GNAT Implementation of Tasking
26049 This chapter outlines the basic GNAT approach to tasking (in particular,
26050 a multi-layered library for portability) and discusses issues related
26051 to compliance with the Real-Time Systems Annex.
26054 * Mapping Ada Tasks onto the Underlying Kernel Threads::
26055 * Ensuring Compliance with the Real-Time Annex::
26056 * Support for Locking Policies::
26060 @node Mapping Ada Tasks onto the Underlying Kernel Threads,Ensuring Compliance with the Real-Time Annex,,GNAT Implementation of Tasking
26061 @anchor{gnat_rm/implementation_of_specific_ada_features mapping-ada-tasks-onto-the-underlying-kernel-threads}@anchor{41c}@anchor{gnat_rm/implementation_of_specific_ada_features id4}@anchor{41d}
26062 @subsection Mapping Ada Tasks onto the Underlying Kernel Threads
26065 GNAT's run-time support comprises two layers:
26071 GNARL (GNAT Run-time Layer)
26074 GNULL (GNAT Low-level Library)
26077 In GNAT, Ada's tasking services rely on a platform and OS independent
26078 layer known as GNARL. This code is responsible for implementing the
26079 correct semantics of Ada's task creation, rendezvous, protected
26082 GNARL decomposes Ada's tasking semantics into simpler lower level
26083 operations such as create a thread, set the priority of a thread,
26084 yield, create a lock, lock/unlock, etc. The spec for these low-level
26085 operations constitutes GNULLI, the GNULL Interface. This interface is
26086 directly inspired from the POSIX real-time API.
26088 If the underlying executive or OS implements the POSIX standard
26089 faithfully, the GNULL Interface maps as is to the services offered by
26090 the underlying kernel. Otherwise, some target dependent glue code maps
26091 the services offered by the underlying kernel to the semantics expected
26094 Whatever the underlying OS (VxWorks, UNIX, Windows, etc.) the
26095 key point is that each Ada task is mapped on a thread in the underlying
26096 kernel. For example, in the case of VxWorks, one Ada task = one VxWorks task.
26098 In addition Ada task priorities map onto the underlying thread priorities.
26099 Mapping Ada tasks onto the underlying kernel threads has several advantages:
26105 The underlying scheduler is used to schedule the Ada tasks. This
26106 makes Ada tasks as efficient as kernel threads from a scheduling
26110 Interaction with code written in C containing threads is eased
26111 since at the lowest level Ada tasks and C threads map onto the same
26112 underlying kernel concept.
26115 When an Ada task is blocked during I/O the remaining Ada tasks are
26119 On multiprocessor systems Ada tasks can execute in parallel.
26122 Some threads libraries offer a mechanism to fork a new process, with the
26123 child process duplicating the threads from the parent.
26125 support this functionality when the parent contains more than one task.
26127 @geindex Forking a new process
26129 @node Ensuring Compliance with the Real-Time Annex,Support for Locking Policies,Mapping Ada Tasks onto the Underlying Kernel Threads,GNAT Implementation of Tasking
26130 @anchor{gnat_rm/implementation_of_specific_ada_features id5}@anchor{41e}@anchor{gnat_rm/implementation_of_specific_ada_features ensuring-compliance-with-the-real-time-annex}@anchor{41f}
26131 @subsection Ensuring Compliance with the Real-Time Annex
26134 @geindex Real-Time Systems Annex compliance
26136 Although mapping Ada tasks onto
26137 the underlying threads has significant advantages, it does create some
26138 complications when it comes to respecting the scheduling semantics
26139 specified in the real-time annex (Annex D).
26141 For instance the Annex D requirement for the @code{FIFO_Within_Priorities}
26142 scheduling policy states:
26146 @emph{When the active priority of a ready task that is not running
26147 changes, or the setting of its base priority takes effect, the
26148 task is removed from the ready queue for its old active priority
26149 and is added at the tail of the ready queue for its new active
26150 priority, except in the case where the active priority is lowered
26151 due to the loss of inherited priority, in which case the task is
26152 added at the head of the ready queue for its new active priority.}
26155 While most kernels do put tasks at the end of the priority queue when
26156 a task changes its priority, (which respects the main
26157 FIFO_Within_Priorities requirement), almost none keep a thread at the
26158 beginning of its priority queue when its priority drops from the loss
26159 of inherited priority.
26161 As a result most vendors have provided incomplete Annex D implementations.
26163 The GNAT run-time, has a nice cooperative solution to this problem
26164 which ensures that accurate FIFO_Within_Priorities semantics are
26167 The principle is as follows. When an Ada task T is about to start
26168 running, it checks whether some other Ada task R with the same
26169 priority as T has been suspended due to the loss of priority
26170 inheritance. If this is the case, T yields and is placed at the end of
26171 its priority queue. When R arrives at the front of the queue it
26174 Note that this simple scheme preserves the relative order of the tasks
26175 that were ready to execute in the priority queue where R has been
26178 @c Support_for_Locking_Policies
26180 @node Support for Locking Policies,,Ensuring Compliance with the Real-Time Annex,GNAT Implementation of Tasking
26181 @anchor{gnat_rm/implementation_of_specific_ada_features support-for-locking-policies}@anchor{420}
26182 @subsection Support for Locking Policies
26185 This section specifies which policies specified by pragma Locking_Policy
26186 are supported on which platforms.
26188 GNAT supports the standard @code{Ceiling_Locking} policy, and the
26189 implementation defined @code{Inheritance_Locking} and
26190 @code{Concurrent_Readers_Locking} policies.
26192 @code{Ceiling_Locking} is supported on all platforms if the operating system
26193 supports it. In particular, @code{Ceiling_Locking} is not supported on
26195 @code{Inheritance_Locking} is supported on
26200 @code{Concurrent_Readers_Locking} is supported on Linux.
26202 Notes about @code{Ceiling_Locking} on Linux:
26203 If the process is running as 'root', ceiling locking is used.
26204 If the capabilities facility is installed
26205 ("sudo apt-get --assume-yes install libcap-dev" on Ubuntu,
26207 and the program is linked against that library
26209 and the executable file has the cap_sys_nice capability
26210 ("sudo /sbin/setcap cap_sys_nice=ep executable_file_name"),
26211 then ceiling locking is used.
26212 Otherwise, the @code{Ceiling_Locking} policy is ignored.
26214 @node GNAT Implementation of Shared Passive Packages,Code Generation for Array Aggregates,GNAT Implementation of Tasking,Implementation of Specific Ada Features
26215 @anchor{gnat_rm/implementation_of_specific_ada_features id6}@anchor{421}@anchor{gnat_rm/implementation_of_specific_ada_features gnat-implementation-of-shared-passive-packages}@anchor{422}
26216 @section GNAT Implementation of Shared Passive Packages
26219 @geindex Shared passive packages
26221 GNAT fully implements the
26222 @geindex pragma Shared_Passive
26224 @code{Shared_Passive} for
26225 the purpose of designating shared passive packages.
26226 This allows the use of passive partitions in the
26227 context described in the Ada Reference Manual; i.e., for communication
26228 between separate partitions of a distributed application using the
26229 features in Annex E.
26233 @geindex Distribution Systems Annex
26235 However, the implementation approach used by GNAT provides for more
26236 extensive usage as follows:
26241 @item @emph{Communication between separate programs}
26243 This allows separate programs to access the data in passive
26244 partitions, using protected objects for synchronization where
26245 needed. The only requirement is that the two programs have a
26246 common shared file system. It is even possible for programs
26247 running on different machines with different architectures
26248 (e.g., different endianness) to communicate via the data in
26249 a passive partition.
26251 @item @emph{Persistence between program runs}
26253 The data in a passive package can persist from one run of a
26254 program to another, so that a later program sees the final
26255 values stored by a previous run of the same program.
26258 The implementation approach used is to store the data in files. A
26259 separate stream file is created for each object in the package, and
26260 an access to an object causes the corresponding file to be read or
26263 @geindex SHARED_MEMORY_DIRECTORY environment variable
26265 The environment variable @code{SHARED_MEMORY_DIRECTORY} should be
26266 set to the directory to be used for these files.
26267 The files in this directory
26268 have names that correspond to their fully qualified names. For
26269 example, if we have the package
26273 pragma Shared_Passive (X);
26279 and the environment variable is set to @code{/stemp/}, then the files created
26280 will have the names:
26287 These files are created when a value is initially written to the object, and
26288 the files are retained until manually deleted. This provides the persistence
26289 semantics. If no file exists, it means that no partition has assigned a value
26290 to the variable; in this case the initial value declared in the package
26291 will be used. This model ensures that there are no issues in synchronizing
26292 the elaboration process, since elaboration of passive packages elaborates the
26293 initial values, but does not create the files.
26295 The files are written using normal @code{Stream_IO} access.
26296 If you want to be able
26297 to communicate between programs or partitions running on different
26298 architectures, then you should use the XDR versions of the stream attribute
26299 routines, since these are architecture independent.
26301 If active synchronization is required for access to the variables in the
26302 shared passive package, then as described in the Ada Reference Manual, the
26303 package may contain protected objects used for this purpose. In this case
26304 a lock file (whose name is @code{___lock} (three underscores)
26305 is created in the shared memory directory.
26307 @geindex ___lock file (for shared passive packages)
26309 This is used to provide the required locking
26310 semantics for proper protected object synchronization.
26312 GNAT supports shared passive packages on all platforms
26313 except for OpenVMS.
26315 @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
26316 @anchor{gnat_rm/implementation_of_specific_ada_features code-generation-for-array-aggregates}@anchor{423}@anchor{gnat_rm/implementation_of_specific_ada_features id7}@anchor{424}
26317 @section Code Generation for Array Aggregates
26320 Aggregates have a rich syntax and allow the user to specify the values of
26321 complex data structures by means of a single construct. As a result, the
26322 code generated for aggregates can be quite complex and involve loops, case
26323 statements and multiple assignments. In the simplest cases, however, the
26324 compiler will recognize aggregates whose components and constraints are
26325 fully static, and in those cases the compiler will generate little or no
26326 executable code. The following is an outline of the code that GNAT generates
26327 for various aggregate constructs. For further details, you will find it
26328 useful to examine the output produced by the -gnatG flag to see the expanded
26329 source that is input to the code generator. You may also want to examine
26330 the assembly code generated at various levels of optimization.
26332 The code generated for aggregates depends on the context, the component values,
26333 and the type. In the context of an object declaration the code generated is
26334 generally simpler than in the case of an assignment. As a general rule, static
26335 component values and static subtypes also lead to simpler code.
26338 * Static constant aggregates with static bounds::
26339 * Constant aggregates with unconstrained nominal types::
26340 * Aggregates with static bounds::
26341 * Aggregates with nonstatic bounds::
26342 * Aggregates in assignment statements::
26346 @node Static constant aggregates with static bounds,Constant aggregates with unconstrained nominal types,,Code Generation for Array Aggregates
26347 @anchor{gnat_rm/implementation_of_specific_ada_features static-constant-aggregates-with-static-bounds}@anchor{425}@anchor{gnat_rm/implementation_of_specific_ada_features id8}@anchor{426}
26348 @subsection Static constant aggregates with static bounds
26351 For the declarations:
26354 type One_Dim is array (1..10) of integer;
26355 ar0 : constant One_Dim := (1, 2, 3, 4, 5, 6, 7, 8, 9, 0);
26358 GNAT generates no executable code: the constant ar0 is placed in static memory.
26359 The same is true for constant aggregates with named associations:
26362 Cr1 : constant One_Dim := (4 => 16, 2 => 4, 3 => 9, 1 => 1, 5 .. 10 => 0);
26363 Cr3 : constant One_Dim := (others => 7777);
26366 The same is true for multidimensional constant arrays such as:
26369 type two_dim is array (1..3, 1..3) of integer;
26370 Unit : constant two_dim := ( (1,0,0), (0,1,0), (0,0,1));
26373 The same is true for arrays of one-dimensional arrays: the following are
26377 type ar1b is array (1..3) of boolean;
26378 type ar_ar is array (1..3) of ar1b;
26379 None : constant ar1b := (others => false); -- fully static
26380 None2 : constant ar_ar := (1..3 => None); -- fully static
26383 However, for multidimensional aggregates with named associations, GNAT will
26384 generate assignments and loops, even if all associations are static. The
26385 following two declarations generate a loop for the first dimension, and
26386 individual component assignments for the second dimension:
26389 Zero1: constant two_dim := (1..3 => (1..3 => 0));
26390 Zero2: constant two_dim := (others => (others => 0));
26393 @node Constant aggregates with unconstrained nominal types,Aggregates with static bounds,Static constant aggregates with static bounds,Code Generation for Array Aggregates
26394 @anchor{gnat_rm/implementation_of_specific_ada_features constant-aggregates-with-unconstrained-nominal-types}@anchor{427}@anchor{gnat_rm/implementation_of_specific_ada_features id9}@anchor{428}
26395 @subsection Constant aggregates with unconstrained nominal types
26398 In such cases the aggregate itself establishes the subtype, so that
26399 associations with @code{others} cannot be used. GNAT determines the
26400 bounds for the actual subtype of the aggregate, and allocates the
26401 aggregate statically as well. No code is generated for the following:
26404 type One_Unc is array (natural range <>) of integer;
26405 Cr_Unc : constant One_Unc := (12,24,36);
26408 @node Aggregates with static bounds,Aggregates with nonstatic bounds,Constant aggregates with unconstrained nominal types,Code Generation for Array Aggregates
26409 @anchor{gnat_rm/implementation_of_specific_ada_features id10}@anchor{429}@anchor{gnat_rm/implementation_of_specific_ada_features aggregates-with-static-bounds}@anchor{42a}
26410 @subsection Aggregates with static bounds
26413 In all previous examples the aggregate was the initial (and immutable) value
26414 of a constant. If the aggregate initializes a variable, then code is generated
26415 for it as a combination of individual assignments and loops over the target
26416 object. The declarations
26419 Cr_Var1 : One_Dim := (2, 5, 7, 11, 0, 0, 0, 0, 0, 0);
26420 Cr_Var2 : One_Dim := (others > -1);
26423 generate the equivalent of
26431 for I in Cr_Var2'range loop
26436 @node Aggregates with nonstatic bounds,Aggregates in assignment statements,Aggregates with static bounds,Code Generation for Array Aggregates
26437 @anchor{gnat_rm/implementation_of_specific_ada_features id11}@anchor{42b}@anchor{gnat_rm/implementation_of_specific_ada_features aggregates-with-nonstatic-bounds}@anchor{42c}
26438 @subsection Aggregates with nonstatic bounds
26441 If the bounds of the aggregate are not statically compatible with the bounds
26442 of the nominal subtype of the target, then constraint checks have to be
26443 generated on the bounds. For a multidimensional array, constraint checks may
26444 have to be applied to sub-arrays individually, if they do not have statically
26445 compatible subtypes.
26447 @node Aggregates in assignment statements,,Aggregates with nonstatic bounds,Code Generation for Array Aggregates
26448 @anchor{gnat_rm/implementation_of_specific_ada_features id12}@anchor{42d}@anchor{gnat_rm/implementation_of_specific_ada_features aggregates-in-assignment-statements}@anchor{42e}
26449 @subsection Aggregates in assignment statements
26452 In general, aggregate assignment requires the construction of a temporary,
26453 and a copy from the temporary to the target of the assignment. This is because
26454 it is not always possible to convert the assignment into a series of individual
26455 component assignments. For example, consider the simple case:
26461 This cannot be converted into:
26468 So the aggregate has to be built first in a separate location, and then
26469 copied into the target. GNAT recognizes simple cases where this intermediate
26470 step is not required, and the assignments can be performed in place, directly
26471 into the target. The following sufficient criteria are applied:
26477 The bounds of the aggregate are static, and the associations are static.
26480 The components of the aggregate are static constants, names of
26481 simple variables that are not renamings, or expressions not involving
26482 indexed components whose operands obey these rules.
26485 If any of these conditions are violated, the aggregate will be built in
26486 a temporary (created either by the front-end or the code generator) and then
26487 that temporary will be copied onto the target.
26489 @node The Size of Discriminated Records with Default Discriminants,Strict Conformance to the Ada Reference Manual,Code Generation for Array Aggregates,Implementation of Specific Ada Features
26490 @anchor{gnat_rm/implementation_of_specific_ada_features id13}@anchor{42f}@anchor{gnat_rm/implementation_of_specific_ada_features the-size-of-discriminated-records-with-default-discriminants}@anchor{430}
26491 @section The Size of Discriminated Records with Default Discriminants
26494 If a discriminated type @code{T} has discriminants with default values, it is
26495 possible to declare an object of this type without providing an explicit
26499 type Size is range 1..100;
26501 type Rec (D : Size := 15) is record
26502 Name : String (1..D);
26508 Such an object is said to be @emph{unconstrained}.
26509 The discriminant of the object
26510 can be modified by a full assignment to the object, as long as it preserves the
26511 relation between the value of the discriminant, and the value of the components
26515 Word := (3, "yes");
26517 Word := (5, "maybe");
26519 Word := (5, "no"); -- raises Constraint_Error
26522 In order to support this behavior efficiently, an unconstrained object is
26523 given the maximum size that any value of the type requires. In the case
26524 above, @code{Word} has storage for the discriminant and for
26525 a @code{String} of length 100.
26526 It is important to note that unconstrained objects do not require dynamic
26527 allocation. It would be an improper implementation to place on the heap those
26528 components whose size depends on discriminants. (This improper implementation
26529 was used by some Ada83 compilers, where the @code{Name} component above
26531 been stored as a pointer to a dynamic string). Following the principle that
26532 dynamic storage management should never be introduced implicitly,
26533 an Ada compiler should reserve the full size for an unconstrained declared
26534 object, and place it on the stack.
26536 This maximum size approach
26537 has been a source of surprise to some users, who expect the default
26538 values of the discriminants to determine the size reserved for an
26539 unconstrained object: "If the default is 15, why should the object occupy
26541 The answer, of course, is that the discriminant may be later modified,
26542 and its full range of values must be taken into account. This is why the
26546 type Rec (D : Positive := 15) is record
26547 Name : String (1..D);
26553 is flagged by the compiler with a warning:
26554 an attempt to create @code{Too_Large} will raise @code{Storage_Error},
26555 because the required size includes @code{Positive'Last}
26556 bytes. As the first example indicates, the proper approach is to declare an
26557 index type of 'reasonable' range so that unconstrained objects are not too
26560 One final wrinkle: if the object is declared to be @code{aliased}, or if it is
26561 created in the heap by means of an allocator, then it is @emph{not}
26563 it is constrained by the default values of the discriminants, and those values
26564 cannot be modified by full assignment. This is because in the presence of
26565 aliasing all views of the object (which may be manipulated by different tasks,
26566 say) must be consistent, so it is imperative that the object, once created,
26569 @node Strict Conformance to the Ada Reference Manual,,The Size of Discriminated Records with Default Discriminants,Implementation of Specific Ada Features
26570 @anchor{gnat_rm/implementation_of_specific_ada_features strict-conformance-to-the-ada-reference-manual}@anchor{431}@anchor{gnat_rm/implementation_of_specific_ada_features id14}@anchor{432}
26571 @section Strict Conformance to the Ada Reference Manual
26574 The dynamic semantics defined by the Ada Reference Manual impose a set of
26575 run-time checks to be generated. By default, the GNAT compiler will insert many
26576 run-time checks into the compiled code, including most of those required by the
26577 Ada Reference Manual. However, there are two checks that are not enabled in
26578 the default mode for efficiency reasons: checks for access before elaboration
26579 on subprogram calls, and stack overflow checking (most operating systems do not
26580 perform this check by default).
26582 Strict conformance to the Ada Reference Manual can be achieved by adding two
26583 compiler options for dynamic checks for access-before-elaboration on subprogram
26584 calls and generic instantiations (@emph{-gnatE}), and stack overflow checking
26585 (@emph{-fstack-check}).
26587 Note that the result of a floating point arithmetic operation in overflow and
26588 invalid situations, when the @code{Machine_Overflows} attribute of the result
26589 type is @code{False}, is to generate IEEE NaN and infinite values. This is the
26590 case for machines compliant with the IEEE floating-point standard, but on
26591 machines that are not fully compliant with this standard, such as Alpha, the
26592 @emph{-mieee} compiler flag must be used for achieving IEEE confirming
26593 behavior (although at the cost of a significant performance penalty), so
26594 infinite and NaN values are properly generated.
26596 @node Implementation of Ada 2012 Features,Obsolescent Features,Implementation of Specific Ada Features,Top
26597 @anchor{gnat_rm/implementation_of_ada_2012_features doc}@anchor{433}@anchor{gnat_rm/implementation_of_ada_2012_features implementation-of-ada-2012-features}@anchor{14}@anchor{gnat_rm/implementation_of_ada_2012_features id1}@anchor{434}
26598 @chapter Implementation of Ada 2012 Features
26601 @geindex Ada 2012 implementation status
26603 @geindex -gnat12 option (gcc)
26605 @geindex pragma Ada_2012
26607 @geindex configuration pragma Ada_2012
26609 @geindex Ada_2012 configuration pragma
26611 This chapter contains a complete list of Ada 2012 features that have been
26613 Generally, these features are only
26614 available if the @emph{-gnat12} (Ada 2012 features enabled) option is set,
26615 which is the default behavior,
26616 or if the configuration pragma @code{Ada_2012} is used.
26618 However, new pragmas, attributes, and restrictions are
26619 unconditionally available, since the Ada 95 standard allows the addition of
26620 new pragmas, attributes, and restrictions (there are exceptions, which are
26621 documented in the individual descriptions), and also certain packages
26622 were made available in earlier versions of Ada.
26624 An ISO date (YYYY-MM-DD) appears in parentheses on the description line.
26625 This date shows the implementation date of the feature. Any wavefront
26626 subsequent to this date will contain the indicated feature, as will any
26627 subsequent releases. A date of 0000-00-00 means that GNAT has always
26628 implemented the feature, or implemented it as soon as it appeared as a
26629 binding interpretation.
26631 Each feature corresponds to an Ada Issue ('AI') approved by the Ada
26632 standardization group (ISO/IEC JTC1/SC22/WG9) for inclusion in Ada 2012.
26633 The features are ordered based on the relevant sections of the Ada
26634 Reference Manual ("RM"). When a given AI relates to multiple points
26635 in the RM, the earliest is used.
26637 A complete description of the AIs may be found in
26638 @indicateurl{http://www.ada-auth.org/ai05-summary.html}.
26640 @geindex AI-0176 (Ada 2012 feature)
26646 @emph{AI-0176 Quantified expressions (2010-09-29)}
26648 Both universally and existentially quantified expressions are implemented.
26649 They use the new syntax for iterators proposed in AI05-139-2, as well as
26650 the standard Ada loop syntax.
26652 RM References: 1.01.04 (12) 2.09 (2/2) 4.04 (7) 4.05.09 (0)
26655 @geindex AI-0079 (Ada 2012 feature)
26661 @emph{AI-0079 Allow other_format characters in source (2010-07-10)}
26663 Wide characters in the unicode category @emph{other_format} are now allowed in
26664 source programs between tokens, but not within a token such as an identifier.
26666 RM References: 2.01 (4/2) 2.02 (7)
26669 @geindex AI-0091 (Ada 2012 feature)
26675 @emph{AI-0091 Do not allow other_format in identifiers (0000-00-00)}
26677 Wide characters in the unicode category @emph{other_format} are not permitted
26678 within an identifier, since this can be a security problem. The error
26679 message for this case has been improved to be more specific, but GNAT has
26680 never allowed such characters to appear in identifiers.
26682 RM References: 2.03 (3.1/2) 2.03 (4/2) 2.03 (5/2) 2.03 (5.1/2) 2.03 (5.2/2) 2.03 (5.3/2) 2.09 (2/2)
26685 @geindex AI-0100 (Ada 2012 feature)
26691 @emph{AI-0100 Placement of pragmas (2010-07-01)}
26693 This AI is an earlier version of AI-163. It simplifies the rules
26694 for legal placement of pragmas. In the case of lists that allow pragmas, if
26695 the list may have no elements, then the list may consist solely of pragmas.
26697 RM References: 2.08 (7)
26700 @geindex AI-0163 (Ada 2012 feature)
26706 @emph{AI-0163 Pragmas in place of null (2010-07-01)}
26708 A statement sequence may be composed entirely of pragmas. It is no longer
26709 necessary to add a dummy @code{null} statement to make the sequence legal.
26711 RM References: 2.08 (7) 2.08 (16)
26714 @geindex AI-0080 (Ada 2012 feature)
26720 @emph{AI-0080 'View of' not needed if clear from context (0000-00-00)}
26722 This is an editorial change only, described as non-testable in the AI.
26724 RM References: 3.01 (7)
26727 @geindex AI-0183 (Ada 2012 feature)
26733 @emph{AI-0183 Aspect specifications (2010-08-16)}
26735 Aspect specifications have been fully implemented except for pre and post-
26736 conditions, and type invariants, which have their own separate AI's. All
26737 forms of declarations listed in the AI are supported. The following is a
26738 list of the aspects supported (with GNAT implementation aspects marked)
26742 @multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxx}
26787 @code{Atomic_Components}
26799 @code{Component_Size}
26805 @code{Contract_Cases}
26813 @code{Discard_Names}
26819 @code{External_Tag}
26825 @code{Favor_Top_Level}
26839 @code{Inline_Always}
26855 @code{Machine_Radix}
26881 @code{Persistent_BSS}
26907 @code{Preelaborable_Initialization}
26913 @code{Pure_Function}
26921 @code{Remote_Access_Type}
26943 @code{Storage_Pool}
26949 @code{Storage_Size}
26967 @code{Suppress_Debug_Info}
26983 @code{Thread_Local_Storage}
26991 @code{Type_Invariant}
26997 @code{Unchecked_Union}
27003 @code{Universal_Aliasing}
27019 @code{Unreferenced}
27027 @code{Unreferenced_Objects}
27055 @code{Volatile_Components}
27072 Note that for aspects with an expression, e.g. @code{Size}, the expression is
27073 treated like a default expression (visibility is analyzed at the point of
27074 occurrence of the aspect, but evaluation of the expression occurs at the
27075 freeze point of the entity involved).
27077 RM References: 3.02.01 (3) 3.02.02 (2) 3.03.01 (2/2) 3.08 (6)
27078 3.09.03 (1.1/2) 6.01 (2/2) 6.07 (2/2) 9.05.02 (2/2) 7.01 (3) 7.03
27079 (2) 7.03 (3) 9.01 (2/2) 9.01 (3/2) 9.04 (2/2) 9.04 (3/2)
27080 9.05.02 (2/2) 11.01 (2) 12.01 (3) 12.03 (2/2) 12.04 (2/2) 12.05 (2)
27081 12.06 (2.1/2) 12.06 (2.2/2) 12.07 (2) 13.01 (0.1/2) 13.03 (5/1)
27085 @geindex AI-0128 (Ada 2012 feature)
27091 @emph{AI-0128 Inequality is a primitive operation (0000-00-00)}
27093 If an equality operator ("=") is declared for a type, then the implicitly
27094 declared inequality operator ("/=") is a primitive operation of the type.
27095 This is the only reasonable interpretation, and is the one always implemented
27096 by GNAT, but the RM was not entirely clear in making this point.
27098 RM References: 3.02.03 (6) 6.06 (6)
27101 @geindex AI-0003 (Ada 2012 feature)
27107 @emph{AI-0003 Qualified expressions as names (2010-07-11)}
27109 In Ada 2012, a qualified expression is considered to be syntactically a name,
27110 meaning that constructs such as @code{A'(F(X)).B} are now legal. This is
27111 useful in disambiguating some cases of overloading.
27113 RM References: 3.03 (11) 3.03 (21) 4.01 (2) 4.04 (7) 4.07 (3)
27117 @geindex AI-0120 (Ada 2012 feature)
27123 @emph{AI-0120 Constant instance of protected object (0000-00-00)}
27125 This is an RM editorial change only. The section that lists objects that are
27126 constant failed to include the current instance of a protected object
27127 within a protected function. This has always been treated as a constant
27130 RM References: 3.03 (21)
27133 @geindex AI-0008 (Ada 2012 feature)
27139 @emph{AI-0008 General access to constrained objects (0000-00-00)}
27141 The wording in the RM implied that if you have a general access to a
27142 constrained object, it could be used to modify the discriminants. This was
27143 obviously not intended. @code{Constraint_Error} should be raised, and GNAT
27144 has always done so in this situation.
27146 RM References: 3.03 (23) 3.10.02 (26/2) 4.01 (9) 6.04.01 (17) 8.05.01 (5/2)
27149 @geindex AI-0093 (Ada 2012 feature)
27155 @emph{AI-0093 Additional rules use immutably limited (0000-00-00)}
27157 This is an editorial change only, to make more widespread use of the Ada 2012
27158 'immutably limited'.
27160 RM References: 3.03 (23.4/3)
27163 @geindex AI-0096 (Ada 2012 feature)
27169 @emph{AI-0096 Deriving from formal private types (2010-07-20)}
27171 In general it is illegal for a type derived from a formal limited type to be
27172 nonlimited. This AI makes an exception to this rule: derivation is legal
27173 if it appears in the private part of the generic, and the formal type is not
27174 tagged. If the type is tagged, the legality check must be applied to the
27175 private part of the package.
27177 RM References: 3.04 (5.1/2) 6.02 (7)
27180 @geindex AI-0181 (Ada 2012 feature)
27186 @emph{AI-0181 Soft hyphen is a non-graphic character (2010-07-23)}
27188 From Ada 2005 on, soft hyphen is considered a non-graphic character, which
27189 means that it has a special name (@code{SOFT_HYPHEN}) in conjunction with the
27190 @code{Image} and @code{Value} attributes for the character types. Strictly
27191 speaking this is an inconsistency with Ada 95, but in practice the use of
27192 these attributes is so obscure that it will not cause problems.
27194 RM References: 3.05.02 (2/2) A.01 (35/2) A.03.03 (21)
27197 @geindex AI-0182 (Ada 2012 feature)
27203 @emph{AI-0182 Additional forms for} @code{Character'Value} @emph{(0000-00-00)}
27205 This AI allows @code{Character'Value} to accept the string @code{'?'} where
27206 @code{?} is any character including non-graphic control characters. GNAT has
27207 always accepted such strings. It also allows strings such as
27208 @code{HEX_00000041} to be accepted, but GNAT does not take advantage of this
27209 permission and raises @code{Constraint_Error}, as is certainly still
27212 RM References: 3.05 (56/2)
27215 @geindex AI-0214 (Ada 2012 feature)
27221 @emph{AI-0214 Defaulted discriminants for limited tagged (2010-10-01)}
27223 Ada 2012 relaxes the restriction that forbids discriminants of tagged types
27224 to have default expressions by allowing them when the type is limited. It
27225 is often useful to define a default value for a discriminant even though
27226 it can't be changed by assignment.
27228 RM References: 3.07 (9.1/2) 3.07.02 (3)
27231 @geindex AI-0102 (Ada 2012 feature)
27237 @emph{AI-0102 Some implicit conversions are illegal (0000-00-00)}
27239 It is illegal to assign an anonymous access constant to an anonymous access
27240 variable. The RM did not have a clear rule to prevent this, but GNAT has
27241 always generated an error for this usage.
27243 RM References: 3.07 (16) 3.07.01 (9) 6.04.01 (6) 8.06 (27/2)
27246 @geindex AI-0158 (Ada 2012 feature)
27252 @emph{AI-0158 Generalizing membership tests (2010-09-16)}
27254 This AI extends the syntax of membership tests to simplify complex conditions
27255 that can be expressed as membership in a subset of values of any type. It
27256 introduces syntax for a list of expressions that may be used in loop contexts
27259 RM References: 3.08.01 (5) 4.04 (3) 4.05.02 (3) 4.05.02 (5) 4.05.02 (27)
27262 @geindex AI-0173 (Ada 2012 feature)
27268 @emph{AI-0173 Testing if tags represent abstract types (2010-07-03)}
27270 The function @code{Ada.Tags.Type_Is_Abstract} returns @code{True} if invoked
27271 with the tag of an abstract type, and @code{False} otherwise.
27273 RM References: 3.09 (7.4/2) 3.09 (12.4/2)
27276 @geindex AI-0076 (Ada 2012 feature)
27282 @emph{AI-0076 function with controlling result (0000-00-00)}
27284 This is an editorial change only. The RM defines calls with controlling
27285 results, but uses the term 'function with controlling result' without an
27286 explicit definition.
27288 RM References: 3.09.02 (2/2)
27291 @geindex AI-0126 (Ada 2012 feature)
27297 @emph{AI-0126 Dispatching with no declared operation (0000-00-00)}
27299 This AI clarifies dispatching rules, and simply confirms that dispatching
27300 executes the operation of the parent type when there is no explicitly or
27301 implicitly declared operation for the descendant type. This has always been
27302 the case in all versions of GNAT.
27304 RM References: 3.09.02 (20/2) 3.09.02 (20.1/2) 3.09.02 (20.2/2)
27307 @geindex AI-0097 (Ada 2012 feature)
27313 @emph{AI-0097 Treatment of abstract null extension (2010-07-19)}
27315 The RM as written implied that in some cases it was possible to create an
27316 object of an abstract type, by having an abstract extension inherit a non-
27317 abstract constructor from its parent type. This mistake has been corrected
27318 in GNAT and in the RM, and this construct is now illegal.
27320 RM References: 3.09.03 (4/2)
27323 @geindex AI-0203 (Ada 2012 feature)
27329 @emph{AI-0203 Extended return cannot be abstract (0000-00-00)}
27331 A return_subtype_indication cannot denote an abstract subtype. GNAT has never
27332 permitted such usage.
27334 RM References: 3.09.03 (8/3)
27337 @geindex AI-0198 (Ada 2012 feature)
27343 @emph{AI-0198 Inheriting abstract operators (0000-00-00)}
27345 This AI resolves a conflict between two rules involving inherited abstract
27346 operations and predefined operators. If a derived numeric type inherits
27347 an abstract operator, it overrides the predefined one. This interpretation
27348 was always the one implemented in GNAT.
27350 RM References: 3.09.03 (4/3)
27353 @geindex AI-0073 (Ada 2012 feature)
27359 @emph{AI-0073 Functions returning abstract types (2010-07-10)}
27361 This AI covers a number of issues regarding returning abstract types. In
27362 particular generic functions cannot have abstract result types or access
27363 result types designated an abstract type. There are some other cases which
27364 are detailed in the AI. Note that this binding interpretation has not been
27365 retrofitted to operate before Ada 2012 mode, since it caused a significant
27366 number of regressions.
27368 RM References: 3.09.03 (8) 3.09.03 (10) 6.05 (8/2)
27371 @geindex AI-0070 (Ada 2012 feature)
27377 @emph{AI-0070 Elaboration of interface types (0000-00-00)}
27379 This is an editorial change only, there are no testable consequences short of
27380 checking for the absence of generated code for an interface declaration.
27382 RM References: 3.09.04 (18/2)
27385 @geindex AI-0208 (Ada 2012 feature)
27391 @emph{AI-0208 Characteristics of incomplete views (0000-00-00)}
27393 The wording in the Ada 2005 RM concerning characteristics of incomplete views
27394 was incorrect and implied that some programs intended to be legal were now
27395 illegal. GNAT had never considered such programs illegal, so it has always
27396 implemented the intent of this AI.
27398 RM References: 3.10.01 (2.4/2) 3.10.01 (2.6/2)
27401 @geindex AI-0162 (Ada 2012 feature)
27407 @emph{AI-0162 Incomplete type completed by partial view (2010-09-15)}
27409 Incomplete types are made more useful by allowing them to be completed by
27410 private types and private extensions.
27412 RM References: 3.10.01 (2.5/2) 3.10.01 (2.6/2) 3.10.01 (3) 3.10.01 (4/2)
27415 @geindex AI-0098 (Ada 2012 feature)
27421 @emph{AI-0098 Anonymous subprogram access restrictions (0000-00-00)}
27423 An unintentional omission in the RM implied some inconsistent restrictions on
27424 the use of anonymous access to subprogram values. These restrictions were not
27425 intentional, and have never been enforced by GNAT.
27427 RM References: 3.10.01 (6) 3.10.01 (9.2/2)
27430 @geindex AI-0199 (Ada 2012 feature)
27436 @emph{AI-0199 Aggregate with anonymous access components (2010-07-14)}
27438 A choice list in a record aggregate can include several components of
27439 (distinct) anonymous access types as long as they have matching designated
27442 RM References: 4.03.01 (16)
27445 @geindex AI-0220 (Ada 2012 feature)
27451 @emph{AI-0220 Needed components for aggregates (0000-00-00)}
27453 This AI addresses a wording problem in the RM that appears to permit some
27454 complex cases of aggregates with nonstatic discriminants. GNAT has always
27455 implemented the intended semantics.
27457 RM References: 4.03.01 (17)
27460 @geindex AI-0147 (Ada 2012 feature)
27466 @emph{AI-0147 Conditional expressions (2009-03-29)}
27468 Conditional expressions are permitted. The form of such an expression is:
27471 (if expr then expr @{elsif expr then expr@} [else expr])
27474 The parentheses can be omitted in contexts where parentheses are present
27475 anyway, such as subprogram arguments and pragma arguments. If the @strong{else}
27476 clause is omitted, @strong{else} @emph{True} is assumed;
27477 thus @code{(if A then B)} is a way to conveniently represent
27478 @emph{(A implies B)} in standard logic.
27480 RM References: 4.03.03 (15) 4.04 (1) 4.04 (7) 4.05.07 (0) 4.07 (2)
27481 4.07 (3) 4.09 (12) 4.09 (33) 5.03 (3) 5.03 (4) 7.05 (2.1/2)
27484 @geindex AI-0037 (Ada 2012 feature)
27490 @emph{AI-0037 Out-of-range box associations in aggregate (0000-00-00)}
27492 This AI confirms that an association of the form @code{Indx => <>} in an
27493 array aggregate must raise @code{Constraint_Error} if @code{Indx}
27494 is out of range. The RM specified a range check on other associations, but
27495 not when the value of the association was defaulted. GNAT has always inserted
27496 a constraint check on the index value.
27498 RM References: 4.03.03 (29)
27501 @geindex AI-0123 (Ada 2012 feature)
27507 @emph{AI-0123 Composability of equality (2010-04-13)}
27509 Equality of untagged record composes, so that the predefined equality for a
27510 composite type that includes a component of some untagged record type
27511 @code{R} uses the equality operation of @code{R} (which may be user-defined
27512 or predefined). This makes the behavior of untagged records identical to that
27513 of tagged types in this respect.
27515 This change is an incompatibility with previous versions of Ada, but it
27516 corrects a non-uniformity that was often a source of confusion. Analysis of
27517 a large number of industrial programs indicates that in those rare cases
27518 where a composite type had an untagged record component with a user-defined
27519 equality, either there was no use of the composite equality, or else the code
27520 expected the same composability as for tagged types, and thus had a bug that
27521 would be fixed by this change.
27523 RM References: 4.05.02 (9.7/2) 4.05.02 (14) 4.05.02 (15) 4.05.02 (24)
27527 @geindex AI-0088 (Ada 2012 feature)
27533 @emph{AI-0088 The value of exponentiation (0000-00-00)}
27535 This AI clarifies the equivalence rule given for the dynamic semantics of
27536 exponentiation: the value of the operation can be obtained by repeated
27537 multiplication, but the operation can be implemented otherwise (for example
27538 using the familiar divide-by-two-and-square algorithm, even if this is less
27539 accurate), and does not imply repeated reads of a volatile base.
27541 RM References: 4.05.06 (11)
27544 @geindex AI-0188 (Ada 2012 feature)
27550 @emph{AI-0188 Case expressions (2010-01-09)}
27552 Case expressions are permitted. This allows use of constructs such as:
27555 X := (case Y is when 1 => 2, when 2 => 3, when others => 31)
27558 RM References: 4.05.07 (0) 4.05.08 (0) 4.09 (12) 4.09 (33)
27561 @geindex AI-0104 (Ada 2012 feature)
27567 @emph{AI-0104 Null exclusion and uninitialized allocator (2010-07-15)}
27569 The assignment @code{Ptr := new not null Some_Ptr;} will raise
27570 @code{Constraint_Error} because the default value of the allocated object is
27571 @strong{null}. This useless construct is illegal in Ada 2012.
27573 RM References: 4.08 (2)
27576 @geindex AI-0157 (Ada 2012 feature)
27582 @emph{AI-0157 Allocation/Deallocation from empty pool (2010-07-11)}
27584 Allocation and Deallocation from an empty storage pool (i.e. allocation or
27585 deallocation of a pointer for which a static storage size clause of zero
27586 has been given) is now illegal and is detected as such. GNAT
27587 previously gave a warning but not an error.
27589 RM References: 4.08 (5.3/2) 13.11.02 (4) 13.11.02 (17)
27592 @geindex AI-0179 (Ada 2012 feature)
27598 @emph{AI-0179 Statement not required after label (2010-04-10)}
27600 It is not necessary to have a statement following a label, so a label
27601 can appear at the end of a statement sequence without the need for putting a
27602 null statement afterwards, but it is not allowable to have only labels and
27603 no real statements in a statement sequence.
27605 RM References: 5.01 (2)
27608 @geindex AI-0139-2 (Ada 2012 feature)
27614 @emph{AI-0139-2 Syntactic sugar for iterators (2010-09-29)}
27616 The new syntax for iterating over arrays and containers is now implemented.
27617 Iteration over containers is for now limited to read-only iterators. Only
27618 default iterators are supported, with the syntax: @code{for Elem of C}.
27620 RM References: 5.05
27623 @geindex AI-0134 (Ada 2012 feature)
27629 @emph{AI-0134 Profiles must match for full conformance (0000-00-00)}
27631 For full conformance, the profiles of anonymous-access-to-subprogram
27632 parameters must match. GNAT has always enforced this rule.
27634 RM References: 6.03.01 (18)
27637 @geindex AI-0207 (Ada 2012 feature)
27643 @emph{AI-0207 Mode conformance and access constant (0000-00-00)}
27645 This AI confirms that access_to_constant indication must match for mode
27646 conformance. This was implemented in GNAT when the qualifier was originally
27647 introduced in Ada 2005.
27649 RM References: 6.03.01 (16/2)
27652 @geindex AI-0046 (Ada 2012 feature)
27658 @emph{AI-0046 Null exclusion match for full conformance (2010-07-17)}
27660 For full conformance, in the case of access parameters, the null exclusion
27661 must match (either both or neither must have @code{not null}).
27663 RM References: 6.03.02 (18)
27666 @geindex AI-0118 (Ada 2012 feature)
27672 @emph{AI-0118 The association of parameter associations (0000-00-00)}
27674 This AI clarifies the rules for named associations in subprogram calls and
27675 generic instantiations. The rules have been in place since Ada 83.
27677 RM References: 6.04.01 (2) 12.03 (9)
27680 @geindex AI-0196 (Ada 2012 feature)
27686 @emph{AI-0196 Null exclusion tests for out parameters (0000-00-00)}
27688 Null exclusion checks are not made for @code{out} parameters when
27689 evaluating the actual parameters. GNAT has never generated these checks.
27691 RM References: 6.04.01 (13)
27694 @geindex AI-0015 (Ada 2012 feature)
27700 @emph{AI-0015 Constant return objects (0000-00-00)}
27702 The return object declared in an @emph{extended_return_statement} may be
27703 declared constant. This was always intended, and GNAT has always allowed it.
27705 RM References: 6.05 (2.1/2) 3.03 (10/2) 3.03 (21) 6.05 (5/2)
27709 @geindex AI-0032 (Ada 2012 feature)
27715 @emph{AI-0032 Extended return for class-wide functions (0000-00-00)}
27717 If a function returns a class-wide type, the object of an extended return
27718 statement can be declared with a specific type that is covered by the class-
27719 wide type. This has been implemented in GNAT since the introduction of
27720 extended returns. Note AI-0103 complements this AI by imposing matching
27721 rules for constrained return types.
27723 RM References: 6.05 (5.2/2) 6.05 (5.3/2) 6.05 (5.6/2) 6.05 (5.8/2)
27727 @geindex AI-0103 (Ada 2012 feature)
27733 @emph{AI-0103 Static matching for extended return (2010-07-23)}
27735 If the return subtype of a function is an elementary type or a constrained
27736 type, the subtype indication in an extended return statement must match
27737 statically this return subtype.
27739 RM References: 6.05 (5.2/2)
27742 @geindex AI-0058 (Ada 2012 feature)
27748 @emph{AI-0058 Abnormal completion of an extended return (0000-00-00)}
27750 The RM had some incorrect wording implying wrong treatment of abnormal
27751 completion in an extended return. GNAT has always implemented the intended
27752 correct semantics as described by this AI.
27754 RM References: 6.05 (22/2)
27757 @geindex AI-0050 (Ada 2012 feature)
27763 @emph{AI-0050 Raising Constraint_Error early for function call (0000-00-00)}
27765 The implementation permissions for raising @code{Constraint_Error} early on a function call
27766 when it was clear an exception would be raised were over-permissive and allowed
27767 mishandling of discriminants in some cases. GNAT did
27768 not take advantage of these incorrect permissions in any case.
27770 RM References: 6.05 (24/2)
27773 @geindex AI-0125 (Ada 2012 feature)
27779 @emph{AI-0125 Nonoverridable operations of an ancestor (2010-09-28)}
27781 In Ada 2012, the declaration of a primitive operation of a type extension
27782 or private extension can also override an inherited primitive that is not
27783 visible at the point of this declaration.
27785 RM References: 7.03.01 (6) 8.03 (23) 8.03.01 (5/2) 8.03.01 (6/2)
27788 @geindex AI-0062 (Ada 2012 feature)
27794 @emph{AI-0062 Null exclusions and deferred constants (0000-00-00)}
27796 A full constant may have a null exclusion even if its associated deferred
27797 constant does not. GNAT has always allowed this.
27799 RM References: 7.04 (6/2) 7.04 (7.1/2)
27802 @geindex AI-0178 (Ada 2012 feature)
27808 @emph{AI-0178 Incomplete views are limited (0000-00-00)}
27810 This AI clarifies the role of incomplete views and plugs an omission in the
27811 RM. GNAT always correctly restricted the use of incomplete views and types.
27813 RM References: 7.05 (3/2) 7.05 (6/2)
27816 @geindex AI-0087 (Ada 2012 feature)
27822 @emph{AI-0087 Actual for formal nonlimited derived type (2010-07-15)}
27824 The actual for a formal nonlimited derived type cannot be limited. In
27825 particular, a formal derived type that extends a limited interface but which
27826 is not explicitly limited cannot be instantiated with a limited type.
27828 RM References: 7.05 (5/2) 12.05.01 (5.1/2)
27831 @geindex AI-0099 (Ada 2012 feature)
27837 @emph{AI-0099 Tag determines whether finalization needed (0000-00-00)}
27839 This AI clarifies that 'needs finalization' is part of dynamic semantics,
27840 and therefore depends on the run-time characteristics of an object (i.e. its
27841 tag) and not on its nominal type. As the AI indicates: "we do not expect
27842 this to affect any implementation'@w{'}.
27844 RM References: 7.06.01 (6) 7.06.01 (7) 7.06.01 (8) 7.06.01 (9/2)
27847 @geindex AI-0064 (Ada 2012 feature)
27853 @emph{AI-0064 Redundant finalization rule (0000-00-00)}
27855 This is an editorial change only. The intended behavior is already checked
27856 by an existing ACATS test, which GNAT has always executed correctly.
27858 RM References: 7.06.01 (17.1/1)
27861 @geindex AI-0026 (Ada 2012 feature)
27867 @emph{AI-0026 Missing rules for Unchecked_Union (2010-07-07)}
27869 Record representation clauses concerning Unchecked_Union types cannot mention
27870 the discriminant of the type. The type of a component declared in the variant
27871 part of an Unchecked_Union cannot be controlled, have controlled components,
27872 nor have protected or task parts. If an Unchecked_Union type is declared
27873 within the body of a generic unit or its descendants, then the type of a
27874 component declared in the variant part cannot be a formal private type or a
27875 formal private extension declared within the same generic unit.
27877 RM References: 7.06 (9.4/2) B.03.03 (9/2) B.03.03 (10/2)
27880 @geindex AI-0205 (Ada 2012 feature)
27886 @emph{AI-0205 Extended return declares visible name (0000-00-00)}
27888 This AI corrects a simple omission in the RM. Return objects have always
27889 been visible within an extended return statement.
27891 RM References: 8.03 (17)
27894 @geindex AI-0042 (Ada 2012 feature)
27900 @emph{AI-0042 Overriding versus implemented-by (0000-00-00)}
27902 This AI fixes a wording gap in the RM. An operation of a synchronized
27903 interface can be implemented by a protected or task entry, but the abstract
27904 operation is not being overridden in the usual sense, and it must be stated
27905 separately that this implementation is legal. This has always been the case
27908 RM References: 9.01 (9.2/2) 9.04 (11.1/2)
27911 @geindex AI-0030 (Ada 2012 feature)
27917 @emph{AI-0030 Requeue on synchronized interfaces (2010-07-19)}
27919 Requeue is permitted to a protected, synchronized or task interface primitive
27920 providing it is known that the overriding operation is an entry. Otherwise
27921 the requeue statement has the same effect as a procedure call. Use of pragma
27922 @code{Implemented} provides a way to impose a static requirement on the
27923 overriding operation by adhering to one of the implementation kinds: entry,
27924 protected procedure or any of the above.
27926 RM References: 9.05 (9) 9.05.04 (2) 9.05.04 (3) 9.05.04 (5)
27927 9.05.04 (6) 9.05.04 (7) 9.05.04 (12)
27930 @geindex AI-0201 (Ada 2012 feature)
27936 @emph{AI-0201 Independence of atomic object components (2010-07-22)}
27938 If an Atomic object has a pragma @code{Pack} or a @code{Component_Size}
27939 attribute, then individual components may not be addressable by independent
27940 tasks. However, if the representation clause has no effect (is confirming),
27941 then independence is not compromised. Furthermore, in GNAT, specification of
27942 other appropriately addressable component sizes (e.g. 16 for 8-bit
27943 characters) also preserves independence. GNAT now gives very clear warnings
27944 both for the declaration of such a type, and for any assignment to its components.
27946 RM References: 9.10 (1/3) C.06 (22/2) C.06 (23/2)
27949 @geindex AI-0009 (Ada 2012 feature)
27955 @emph{AI-0009 Pragma Independent[_Components] (2010-07-23)}
27957 This AI introduces the new pragmas @code{Independent} and
27958 @code{Independent_Components},
27959 which control guaranteeing independence of access to objects and components.
27960 The AI also requires independence not unaffected by confirming rep clauses.
27962 RM References: 9.10 (1) 13.01 (15/1) 13.02 (9) 13.03 (13) C.06 (2)
27963 C.06 (4) C.06 (6) C.06 (9) C.06 (13) C.06 (14)
27966 @geindex AI-0072 (Ada 2012 feature)
27972 @emph{AI-0072 Task signalling using 'Terminated (0000-00-00)}
27974 This AI clarifies that task signalling for reading @code{'Terminated} only
27975 occurs if the result is True. GNAT semantics has always been consistent with
27976 this notion of task signalling.
27978 RM References: 9.10 (6.1/1)
27981 @geindex AI-0108 (Ada 2012 feature)
27987 @emph{AI-0108 Limited incomplete view and discriminants (0000-00-00)}
27989 This AI confirms that an incomplete type from a limited view does not have
27990 discriminants. This has always been the case in GNAT.
27992 RM References: 10.01.01 (12.3/2)
27995 @geindex AI-0129 (Ada 2012 feature)
28001 @emph{AI-0129 Limited views and incomplete types (0000-00-00)}
28003 This AI clarifies the description of limited views: a limited view of a
28004 package includes only one view of a type that has an incomplete declaration
28005 and a full declaration (there is no possible ambiguity in a client package).
28006 This AI also fixes an omission: a nested package in the private part has no
28007 limited view. GNAT always implemented this correctly.
28009 RM References: 10.01.01 (12.2/2) 10.01.01 (12.3/2)
28012 @geindex AI-0077 (Ada 2012 feature)
28018 @emph{AI-0077 Limited withs and scope of declarations (0000-00-00)}
28020 This AI clarifies that a declaration does not include a context clause,
28021 and confirms that it is illegal to have a context in which both a limited
28022 and a nonlimited view of a package are accessible. Such double visibility
28023 was always rejected by GNAT.
28025 RM References: 10.01.02 (12/2) 10.01.02 (21/2) 10.01.02 (22/2)
28028 @geindex AI-0122 (Ada 2012 feature)
28034 @emph{AI-0122 Private with and children of generics (0000-00-00)}
28036 This AI clarifies the visibility of private children of generic units within
28037 instantiations of a parent. GNAT has always handled this correctly.
28039 RM References: 10.01.02 (12/2)
28042 @geindex AI-0040 (Ada 2012 feature)
28048 @emph{AI-0040 Limited with clauses on descendant (0000-00-00)}
28050 This AI confirms that a limited with clause in a child unit cannot name
28051 an ancestor of the unit. This has always been checked in GNAT.
28053 RM References: 10.01.02 (20/2)
28056 @geindex AI-0132 (Ada 2012 feature)
28062 @emph{AI-0132 Placement of library unit pragmas (0000-00-00)}
28064 This AI fills a gap in the description of library unit pragmas. The pragma
28065 clearly must apply to a library unit, even if it does not carry the name
28066 of the enclosing unit. GNAT has always enforced the required check.
28068 RM References: 10.01.05 (7)
28071 @geindex AI-0034 (Ada 2012 feature)
28077 @emph{AI-0034 Categorization of limited views (0000-00-00)}
28079 The RM makes certain limited with clauses illegal because of categorization
28080 considerations, when the corresponding normal with would be legal. This is
28081 not intended, and GNAT has always implemented the recommended behavior.
28083 RM References: 10.02.01 (11/1) 10.02.01 (17/2)
28086 @geindex AI-0035 (Ada 2012 feature)
28092 @emph{AI-0035 Inconsistencies with Pure units (0000-00-00)}
28094 This AI remedies some inconsistencies in the legality rules for Pure units.
28095 Derived access types are legal in a pure unit (on the assumption that the
28096 rule for a zero storage pool size has been enforced on the ancestor type).
28097 The rules are enforced in generic instances and in subunits. GNAT has always
28098 implemented the recommended behavior.
28100 RM References: 10.02.01 (15.1/2) 10.02.01 (15.4/2) 10.02.01 (15.5/2) 10.02.01 (17/2)
28103 @geindex AI-0219 (Ada 2012 feature)
28109 @emph{AI-0219 Pure permissions and limited parameters (2010-05-25)}
28111 This AI refines the rules for the cases with limited parameters which do not
28112 allow the implementations to omit 'redundant'. GNAT now properly conforms
28113 to the requirements of this binding interpretation.
28115 RM References: 10.02.01 (18/2)
28118 @geindex AI-0043 (Ada 2012 feature)
28124 @emph{AI-0043 Rules about raising exceptions (0000-00-00)}
28126 This AI covers various omissions in the RM regarding the raising of
28127 exceptions. GNAT has always implemented the intended semantics.
28129 RM References: 11.04.01 (10.1/2) 11 (2)
28132 @geindex AI-0200 (Ada 2012 feature)
28138 @emph{AI-0200 Mismatches in formal package declarations (0000-00-00)}
28140 This AI plugs a gap in the RM which appeared to allow some obviously intended
28141 illegal instantiations. GNAT has never allowed these instantiations.
28143 RM References: 12.07 (16)
28146 @geindex AI-0112 (Ada 2012 feature)
28152 @emph{AI-0112 Detection of duplicate pragmas (2010-07-24)}
28154 This AI concerns giving names to various representation aspects, but the
28155 practical effect is simply to make the use of duplicate
28156 @code{Atomic[_Components]},
28157 @code{Volatile[_Components]}, and
28158 @code{Independent[_Components]} pragmas illegal, and GNAT
28159 now performs this required check.
28161 RM References: 13.01 (8)
28164 @geindex AI-0106 (Ada 2012 feature)
28170 @emph{AI-0106 No representation pragmas on generic formals (0000-00-00)}
28172 The RM appeared to allow representation pragmas on generic formal parameters,
28173 but this was not intended, and GNAT has never permitted this usage.
28175 RM References: 13.01 (9.1/1)
28178 @geindex AI-0012 (Ada 2012 feature)
28184 @emph{AI-0012 Pack/Component_Size for aliased/atomic (2010-07-15)}
28186 It is now illegal to give an inappropriate component size or a pragma
28187 @code{Pack} that attempts to change the component size in the case of atomic
28188 or aliased components. Previously GNAT ignored such an attempt with a
28191 RM References: 13.02 (6.1/2) 13.02 (7) C.06 (10) C.06 (11) C.06 (21)
28194 @geindex AI-0039 (Ada 2012 feature)
28200 @emph{AI-0039 Stream attributes cannot be dynamic (0000-00-00)}
28202 The RM permitted the use of dynamic expressions (such as @code{ptr.all})`
28203 for stream attributes, but these were never useful and are now illegal. GNAT
28204 has always regarded such expressions as illegal.
28206 RM References: 13.03 (4) 13.03 (6) 13.13.02 (38/2)
28209 @geindex AI-0095 (Ada 2012 feature)
28215 @emph{AI-0095 Address of intrinsic subprograms (0000-00-00)}
28217 The prefix of @code{'Address} cannot statically denote a subprogram with
28218 convention @code{Intrinsic}. The use of the @code{Address} attribute raises
28219 @code{Program_Error} if the prefix denotes a subprogram with convention
28222 RM References: 13.03 (11/1)
28225 @geindex AI-0116 (Ada 2012 feature)
28231 @emph{AI-0116 Alignment of class-wide objects (0000-00-00)}
28233 This AI requires that the alignment of a class-wide object be no greater
28234 than the alignment of any type in the class. GNAT has always followed this
28237 RM References: 13.03 (29) 13.11 (16)
28240 @geindex AI-0146 (Ada 2012 feature)
28246 @emph{AI-0146 Type invariants (2009-09-21)}
28248 Type invariants may be specified for private types using the aspect notation.
28249 Aspect @code{Type_Invariant} may be specified for any private type,
28250 @code{Type_Invariant'Class} can
28251 only be specified for tagged types, and is inherited by any descendent of the
28252 tagged types. The invariant is a boolean expression that is tested for being
28253 true in the following situations: conversions to the private type, object
28254 declarations for the private type that are default initialized, and
28255 [@strong{in}] @strong{out}
28256 parameters and returned result on return from any primitive operation for
28257 the type that is visible to a client.
28258 GNAT defines the synonyms @code{Invariant} for @code{Type_Invariant} and
28259 @code{Invariant'Class} for @code{Type_Invariant'Class}.
28261 RM References: 13.03.03 (00)
28264 @geindex AI-0078 (Ada 2012 feature)
28270 @emph{AI-0078 Relax Unchecked_Conversion alignment rules (0000-00-00)}
28272 In Ada 2012, compilers are required to support unchecked conversion where the
28273 target alignment is a multiple of the source alignment. GNAT always supported
28274 this case (and indeed all cases of differing alignments, doing copies where
28275 required if the alignment was reduced).
28277 RM References: 13.09 (7)
28280 @geindex AI-0195 (Ada 2012 feature)
28286 @emph{AI-0195 Invalid value handling is implementation defined (2010-07-03)}
28288 The handling of invalid values is now designated to be implementation
28289 defined. This is a documentation change only, requiring Annex M in the GNAT
28290 Reference Manual to document this handling.
28291 In GNAT, checks for invalid values are made
28292 only when necessary to avoid erroneous behavior. Operations like assignments
28293 which cannot cause erroneous behavior ignore the possibility of invalid
28294 values and do not do a check. The date given above applies only to the
28295 documentation change, this behavior has always been implemented by GNAT.
28297 RM References: 13.09.01 (10)
28300 @geindex AI-0193 (Ada 2012 feature)
28306 @emph{AI-0193 Alignment of allocators (2010-09-16)}
28308 This AI introduces a new attribute @code{Max_Alignment_For_Allocation},
28309 analogous to @code{Max_Size_In_Storage_Elements}, but for alignment instead
28312 RM References: 13.11 (16) 13.11 (21) 13.11.01 (0) 13.11.01 (1)
28313 13.11.01 (2) 13.11.01 (3)
28316 @geindex AI-0177 (Ada 2012 feature)
28322 @emph{AI-0177 Parameterized expressions (2010-07-10)}
28324 The new Ada 2012 notion of parameterized expressions is implemented. The form
28328 function-specification is (expression)
28331 This is exactly equivalent to the
28332 corresponding function body that returns the expression, but it can appear
28333 in a package spec. Note that the expression must be parenthesized.
28335 RM References: 13.11.01 (3/2)
28338 @geindex AI-0033 (Ada 2012 feature)
28344 @emph{AI-0033 Attach/Interrupt_Handler in generic (2010-07-24)}
28346 Neither of these two pragmas may appear within a generic template, because
28347 the generic might be instantiated at other than the library level.
28349 RM References: 13.11.02 (16) C.03.01 (7/2) C.03.01 (8/2)
28352 @geindex AI-0161 (Ada 2012 feature)
28358 @emph{AI-0161 Restriction No_Default_Stream_Attributes (2010-09-11)}
28360 A new restriction @code{No_Default_Stream_Attributes} prevents the use of any
28361 of the default stream attributes for elementary types. If this restriction is
28362 in force, then it is necessary to provide explicit subprograms for any
28363 stream attributes used.
28365 RM References: 13.12.01 (4/2) 13.13.02 (40/2) 13.13.02 (52/2)
28368 @geindex AI-0194 (Ada 2012 feature)
28374 @emph{AI-0194 Value of Stream_Size attribute (0000-00-00)}
28376 The @code{Stream_Size} attribute returns the default number of bits in the
28377 stream representation of the given type.
28378 This value is not affected by the presence
28379 of stream subprogram attributes for the type. GNAT has always implemented
28380 this interpretation.
28382 RM References: 13.13.02 (1.2/2)
28385 @geindex AI-0109 (Ada 2012 feature)
28391 @emph{AI-0109 Redundant check in S'Class'Input (0000-00-00)}
28393 This AI is an editorial change only. It removes the need for a tag check
28394 that can never fail.
28396 RM References: 13.13.02 (34/2)
28399 @geindex AI-0007 (Ada 2012 feature)
28405 @emph{AI-0007 Stream read and private scalar types (0000-00-00)}
28407 The RM as written appeared to limit the possibilities of declaring read
28408 attribute procedures for private scalar types. This limitation was not
28409 intended, and has never been enforced by GNAT.
28411 RM References: 13.13.02 (50/2) 13.13.02 (51/2)
28414 @geindex AI-0065 (Ada 2012 feature)
28420 @emph{AI-0065 Remote access types and external streaming (0000-00-00)}
28422 This AI clarifies the fact that all remote access types support external
28423 streaming. This fixes an obvious oversight in the definition of the
28424 language, and GNAT always implemented the intended correct rules.
28426 RM References: 13.13.02 (52/2)
28429 @geindex AI-0019 (Ada 2012 feature)
28435 @emph{AI-0019 Freezing of primitives for tagged types (0000-00-00)}
28437 The RM suggests that primitive subprograms of a specific tagged type are
28438 frozen when the tagged type is frozen. This would be an incompatible change
28439 and is not intended. GNAT has never attempted this kind of freezing and its
28440 behavior is consistent with the recommendation of this AI.
28442 RM References: 13.14 (2) 13.14 (3/1) 13.14 (8.1/1) 13.14 (10) 13.14 (14) 13.14 (15.1/2)
28445 @geindex AI-0017 (Ada 2012 feature)
28451 @emph{AI-0017 Freezing and incomplete types (0000-00-00)}
28453 So-called 'Taft-amendment types' (i.e., types that are completed in package
28454 bodies) are not frozen by the occurrence of bodies in the
28455 enclosing declarative part. GNAT always implemented this properly.
28457 RM References: 13.14 (3/1)
28460 @geindex AI-0060 (Ada 2012 feature)
28466 @emph{AI-0060 Extended definition of remote access types (0000-00-00)}
28468 This AI extends the definition of remote access types to include access
28469 to limited, synchronized, protected or task class-wide interface types.
28470 GNAT already implemented this extension.
28472 RM References: A (4) E.02.02 (9/1) E.02.02 (9.2/1) E.02.02 (14/2) E.02.02 (18)
28475 @geindex AI-0114 (Ada 2012 feature)
28481 @emph{AI-0114 Classification of letters (0000-00-00)}
28483 The code points 170 (@code{FEMININE ORDINAL INDICATOR}),
28484 181 (@code{MICRO SIGN}), and
28485 186 (@code{MASCULINE ORDINAL INDICATOR}) are technically considered
28486 lower case letters by Unicode.
28487 However, they are not allowed in identifiers, and they
28488 return @code{False} to @code{Ada.Characters.Handling.Is_Letter/Is_Lower}.
28489 This behavior is consistent with that defined in Ada 95.
28491 RM References: A.03.02 (59) A.04.06 (7)
28494 @geindex AI-0185 (Ada 2012 feature)
28500 @emph{AI-0185 Ada.Wide_[Wide_]Characters.Handling (2010-07-06)}
28502 Two new packages @code{Ada.Wide_[Wide_]Characters.Handling} provide
28503 classification functions for @code{Wide_Character} and
28504 @code{Wide_Wide_Character}, as well as providing
28505 case folding routines for @code{Wide_[Wide_]Character} and
28506 @code{Wide_[Wide_]String}.
28508 RM References: A.03.05 (0) A.03.06 (0)
28511 @geindex AI-0031 (Ada 2012 feature)
28517 @emph{AI-0031 Add From parameter to Find_Token (2010-07-25)}
28519 A new version of @code{Find_Token} is added to all relevant string packages,
28520 with an extra parameter @code{From}. Instead of starting at the first
28521 character of the string, the search for a matching Token starts at the
28522 character indexed by the value of @code{From}.
28523 These procedures are available in all versions of Ada
28524 but if used in versions earlier than Ada 2012 they will generate a warning
28525 that an Ada 2012 subprogram is being used.
28527 RM References: A.04.03 (16) A.04.03 (67) A.04.03 (68/1) A.04.04 (51)
28531 @geindex AI-0056 (Ada 2012 feature)
28537 @emph{AI-0056 Index on null string returns zero (0000-00-00)}
28539 The wording in the Ada 2005 RM implied an incompatible handling of the
28540 @code{Index} functions, resulting in raising an exception instead of
28541 returning zero in some situations.
28542 This was not intended and has been corrected.
28543 GNAT always returned zero, and is thus consistent with this AI.
28545 RM References: A.04.03 (56.2/2) A.04.03 (58.5/2)
28548 @geindex AI-0137 (Ada 2012 feature)
28554 @emph{AI-0137 String encoding package (2010-03-25)}
28556 The packages @code{Ada.Strings.UTF_Encoding}, together with its child
28557 packages, @code{Conversions}, @code{Strings}, @code{Wide_Strings},
28558 and @code{Wide_Wide_Strings} have been
28559 implemented. These packages (whose documentation can be found in the spec
28560 files @code{a-stuten.ads}, @code{a-suenco.ads}, @code{a-suenst.ads},
28561 @code{a-suewst.ads}, @code{a-suezst.ads}) allow encoding and decoding of
28562 @code{String}, @code{Wide_String}, and @code{Wide_Wide_String}
28563 values using UTF coding schemes (including UTF-8, UTF-16LE, UTF-16BE, and
28564 UTF-16), as well as conversions between the different UTF encodings. With
28565 the exception of @code{Wide_Wide_Strings}, these packages are available in
28566 Ada 95 and Ada 2005 mode as well as Ada 2012 mode.
28567 The @code{Wide_Wide_Strings} package
28568 is available in Ada 2005 mode as well as Ada 2012 mode (but not in Ada 95
28569 mode since it uses @code{Wide_Wide_Character}).
28571 RM References: A.04.11
28574 @geindex AI-0038 (Ada 2012 feature)
28580 @emph{AI-0038 Minor errors in Text_IO (0000-00-00)}
28582 These are minor errors in the description on three points. The intent on
28583 all these points has always been clear, and GNAT has always implemented the
28584 correct intended semantics.
28586 RM References: A.10.05 (37) A.10.07 (8/1) A.10.07 (10) A.10.07 (12) A.10.08 (10) A.10.08 (24)
28589 @geindex AI-0044 (Ada 2012 feature)
28595 @emph{AI-0044 Restrictions on container instantiations (0000-00-00)}
28597 This AI places restrictions on allowed instantiations of generic containers.
28598 These restrictions are not checked by the compiler, so there is nothing to
28599 change in the implementation. This affects only the RM documentation.
28601 RM References: A.18 (4/2) A.18.02 (231/2) A.18.03 (145/2) A.18.06 (56/2) A.18.08 (66/2) A.18.09 (79/2) A.18.26 (5/2) A.18.26 (9/2)
28604 @geindex AI-0127 (Ada 2012 feature)
28610 @emph{AI-0127 Adding Locale Capabilities (2010-09-29)}
28612 This package provides an interface for identifying the current locale.
28614 RM References: A.19 A.19.01 A.19.02 A.19.03 A.19.05 A.19.06
28615 A.19.07 A.19.08 A.19.09 A.19.10 A.19.11 A.19.12 A.19.13
28618 @geindex AI-0002 (Ada 2012 feature)
28624 @emph{AI-0002 Export C with unconstrained arrays (0000-00-00)}
28626 The compiler is not required to support exporting an Ada subprogram with
28627 convention C if there are parameters or a return type of an unconstrained
28628 array type (such as @code{String}). GNAT allows such declarations but
28629 generates warnings. It is possible, but complicated, to write the
28630 corresponding C code and certainly such code would be specific to GNAT and
28633 RM References: B.01 (17) B.03 (62) B.03 (71.1/2)
28636 @geindex AI05-0216 (Ada 2012 feature)
28642 @emph{AI-0216 No_Task_Hierarchy forbids local tasks (0000-00-00)}
28644 It is clearly the intention that @code{No_Task_Hierarchy} is intended to
28645 forbid tasks declared locally within subprograms, or functions returning task
28646 objects, and that is the implementation that GNAT has always provided.
28647 However the language in the RM was not sufficiently clear on this point.
28648 Thus this is a documentation change in the RM only.
28650 RM References: D.07 (3/3)
28653 @geindex AI-0211 (Ada 2012 feature)
28659 @emph{AI-0211 No_Relative_Delays forbids Set_Handler use (2010-07-09)}
28661 The restriction @code{No_Relative_Delays} forbids any calls to the subprogram
28662 @code{Ada.Real_Time.Timing_Events.Set_Handler}.
28664 RM References: D.07 (5) D.07 (10/2) D.07 (10.4/2) D.07 (10.7/2)
28667 @geindex AI-0190 (Ada 2012 feature)
28673 @emph{AI-0190 pragma Default_Storage_Pool (2010-09-15)}
28675 This AI introduces a new pragma @code{Default_Storage_Pool}, which can be
28676 used to control storage pools globally.
28677 In particular, you can force every access
28678 type that is used for allocation (@strong{new}) to have an explicit storage pool,
28679 or you can declare a pool globally to be used for all access types that lack
28682 RM References: D.07 (8)
28685 @geindex AI-0189 (Ada 2012 feature)
28691 @emph{AI-0189 No_Allocators_After_Elaboration (2010-01-23)}
28693 This AI introduces a new restriction @code{No_Allocators_After_Elaboration},
28694 which says that no dynamic allocation will occur once elaboration is
28696 In general this requires a run-time check, which is not required, and which
28697 GNAT does not attempt. But the static cases of allocators in a task body or
28698 in the body of the main program are detected and flagged at compile or bind
28701 RM References: D.07 (19.1/2) H.04 (23.3/2)
28704 @geindex AI-0171 (Ada 2012 feature)
28710 @emph{AI-0171 Pragma CPU and Ravenscar Profile (2010-09-24)}
28712 A new package @code{System.Multiprocessors} is added, together with the
28713 definition of pragma @code{CPU} for controlling task affinity. A new no
28714 dependence restriction, on @code{System.Multiprocessors.Dispatching_Domains},
28715 is added to the Ravenscar profile.
28717 RM References: D.13.01 (4/2) D.16
28720 @geindex AI-0210 (Ada 2012 feature)
28726 @emph{AI-0210 Correct Timing_Events metric (0000-00-00)}
28728 This is a documentation only issue regarding wording of metric requirements,
28729 that does not affect the implementation of the compiler.
28731 RM References: D.15 (24/2)
28734 @geindex AI-0206 (Ada 2012 feature)
28740 @emph{AI-0206 Remote types packages and preelaborate (2010-07-24)}
28742 Remote types packages are now allowed to depend on preelaborated packages.
28743 This was formerly considered illegal.
28745 RM References: E.02.02 (6)
28748 @geindex AI-0152 (Ada 2012 feature)
28754 @emph{AI-0152 Restriction No_Anonymous_Allocators (2010-09-08)}
28756 Restriction @code{No_Anonymous_Allocators} prevents the use of allocators
28757 where the type of the returned value is an anonymous access type.
28759 RM References: H.04 (8/1)
28762 @node Obsolescent Features,Compatibility and Porting Guide,Implementation of Ada 2012 Features,Top
28763 @anchor{gnat_rm/obsolescent_features id1}@anchor{435}@anchor{gnat_rm/obsolescent_features doc}@anchor{436}@anchor{gnat_rm/obsolescent_features obsolescent-features}@anchor{15}
28764 @chapter Obsolescent Features
28767 This chapter describes features that are provided by GNAT, but are
28768 considered obsolescent since there are preferred ways of achieving
28769 the same effect. These features are provided solely for historical
28770 compatibility purposes.
28773 * pragma No_Run_Time::
28774 * pragma Ravenscar::
28775 * pragma Restricted_Run_Time::
28776 * pragma Task_Info::
28777 * package System.Task_Info (s-tasinf.ads): package System Task_Info s-tasinf ads.
28781 @node pragma No_Run_Time,pragma Ravenscar,,Obsolescent Features
28782 @anchor{gnat_rm/obsolescent_features id2}@anchor{437}@anchor{gnat_rm/obsolescent_features pragma-no-run-time}@anchor{438}
28783 @section pragma No_Run_Time
28786 The pragma @code{No_Run_Time} is used to achieve an affect similar
28787 to the use of the "Zero Foot Print" configurable run time, but without
28788 requiring a specially configured run time. The result of using this
28789 pragma, which must be used for all units in a partition, is to restrict
28790 the use of any language features requiring run-time support code. The
28791 preferred usage is to use an appropriately configured run-time that
28792 includes just those features that are to be made accessible.
28794 @node pragma Ravenscar,pragma Restricted_Run_Time,pragma No_Run_Time,Obsolescent Features
28795 @anchor{gnat_rm/obsolescent_features id3}@anchor{439}@anchor{gnat_rm/obsolescent_features pragma-ravenscar}@anchor{43a}
28796 @section pragma Ravenscar
28799 The pragma @code{Ravenscar} has exactly the same effect as pragma
28800 @code{Profile (Ravenscar)}. The latter usage is preferred since it
28801 is part of the new Ada 2005 standard.
28803 @node pragma Restricted_Run_Time,pragma Task_Info,pragma Ravenscar,Obsolescent Features
28804 @anchor{gnat_rm/obsolescent_features pragma-restricted-run-time}@anchor{43b}@anchor{gnat_rm/obsolescent_features id4}@anchor{43c}
28805 @section pragma Restricted_Run_Time
28808 The pragma @code{Restricted_Run_Time} has exactly the same effect as
28809 pragma @code{Profile (Restricted)}. The latter usage is
28810 preferred since the Ada 2005 pragma @code{Profile} is intended for
28811 this kind of implementation dependent addition.
28813 @node pragma Task_Info,package System Task_Info s-tasinf ads,pragma Restricted_Run_Time,Obsolescent Features
28814 @anchor{gnat_rm/obsolescent_features pragma-task-info}@anchor{43d}@anchor{gnat_rm/obsolescent_features id5}@anchor{43e}
28815 @section pragma Task_Info
28818 The functionality provided by pragma @code{Task_Info} is now part of the
28819 Ada language. The @code{CPU} aspect and the package
28820 @code{System.Multiprocessors} offer a less system-dependent way to specify
28821 task affinity or to query the number of processsors.
28826 pragma Task_Info (EXPRESSION);
28829 This pragma appears within a task definition (like pragma
28830 @code{Priority}) and applies to the task in which it appears. The
28831 argument must be of type @code{System.Task_Info.Task_Info_Type}.
28832 The @code{Task_Info} pragma provides system dependent control over
28833 aspects of tasking implementation, for example, the ability to map
28834 tasks to specific processors. For details on the facilities available
28835 for the version of GNAT that you are using, see the documentation
28836 in the spec of package System.Task_Info in the runtime
28839 @node package System Task_Info s-tasinf ads,,pragma Task_Info,Obsolescent Features
28840 @anchor{gnat_rm/obsolescent_features package-system-task-info}@anchor{43f}@anchor{gnat_rm/obsolescent_features package-system-task-info-s-tasinf-ads}@anchor{440}
28841 @section package System.Task_Info (@code{s-tasinf.ads})
28844 This package provides target dependent functionality that is used
28845 to support the @code{Task_Info} pragma. The predefined Ada package
28846 @code{System.Multiprocessors} and the @code{CPU} aspect now provide a
28847 standard replacement for GNAT's @code{Task_Info} functionality.
28849 @node Compatibility and Porting Guide,GNU Free Documentation License,Obsolescent Features,Top
28850 @anchor{gnat_rm/compatibility_and_porting_guide compatibility-and-porting-guide}@anchor{16}@anchor{gnat_rm/compatibility_and_porting_guide doc}@anchor{441}@anchor{gnat_rm/compatibility_and_porting_guide id1}@anchor{442}
28851 @chapter Compatibility and Porting Guide
28854 This chapter presents some guidelines for developing portable Ada code,
28855 describes the compatibility issues that may arise between
28856 GNAT and other Ada compilation systems (including those for Ada 83),
28857 and shows how GNAT can expedite porting
28858 applications developed in other Ada environments.
28861 * Writing Portable Fixed-Point Declarations::
28862 * Compatibility with Ada 83::
28863 * Compatibility between Ada 95 and Ada 2005::
28864 * Implementation-dependent characteristics::
28865 * Compatibility with Other Ada Systems::
28866 * Representation Clauses::
28867 * Compatibility with HP Ada 83::
28871 @node Writing Portable Fixed-Point Declarations,Compatibility with Ada 83,,Compatibility and Porting Guide
28872 @anchor{gnat_rm/compatibility_and_porting_guide id2}@anchor{443}@anchor{gnat_rm/compatibility_and_porting_guide writing-portable-fixed-point-declarations}@anchor{444}
28873 @section Writing Portable Fixed-Point Declarations
28876 The Ada Reference Manual gives an implementation freedom to choose bounds
28877 that are narrower by @code{Small} from the given bounds.
28878 For example, if we write
28881 type F1 is delta 1.0 range -128.0 .. +128.0;
28884 then the implementation is allowed to choose -128.0 .. +127.0 if it
28885 likes, but is not required to do so.
28887 This leads to possible portability problems, so let's have a closer
28888 look at this, and figure out how to avoid these problems.
28890 First, why does this freedom exist, and why would an implementation
28891 take advantage of it? To answer this, take a closer look at the type
28892 declaration for @code{F1} above. If the compiler uses the given bounds,
28893 it would need 9 bits to hold the largest positive value (and typically
28894 that means 16 bits on all machines). But if the implementation chooses
28895 the +127.0 bound then it can fit values of the type in 8 bits.
28897 Why not make the user write +127.0 if that's what is wanted?
28898 The rationale is that if you are thinking of fixed point
28899 as a kind of 'poor man's floating-point', then you don't want
28900 to be thinking about the scaled integers that are used in its
28901 representation. Let's take another example:
28904 type F2 is delta 2.0**(-15) range -1.0 .. +1.0;
28907 Looking at this declaration, it seems casually as though
28908 it should fit in 16 bits, but again that extra positive value
28909 +1.0 has the scaled integer equivalent of 2**15 which is one too
28910 big for signed 16 bits. The implementation can treat this as:
28913 type F2 is delta 2.0**(-15) range -1.0 .. +1.0-(2.0**(-15));
28916 and the Ada language design team felt that this was too annoying
28917 to require. We don't need to debate this decision at this point,
28918 since it is well established (the rule about narrowing the ranges
28921 But the important point is that an implementation is not required
28922 to do this narrowing, so we have a potential portability problem.
28923 We could imagine three types of implementation:
28929 those that narrow the range automatically if they can figure
28930 out that the narrower range will allow storage in a smaller machine unit,
28933 those that will narrow only if forced to by a @code{'Size} clause, and
28936 those that will never narrow.
28939 Now if we are language theoreticians, we can imagine a fourth
28940 approach: to narrow all the time, e.g. to treat
28943 type F3 is delta 1.0 range -10.0 .. +23.0;
28946 as though it had been written:
28949 type F3 is delta 1.0 range -9.0 .. +22.0;
28952 But although technically allowed, such a behavior would be hostile and silly,
28953 and no real compiler would do this. All real compilers will fall into one of
28954 the categories (a), (b) or (c) above.
28956 So, how do you get the compiler to do what you want? The answer is give the
28957 actual bounds you want, and then use a @code{'Small} clause and a
28958 @code{'Size} clause to absolutely pin down what the compiler does.
28959 E.g., for @code{F2} above, we will write:
28962 My_Small : constant := 2.0**(-15);
28963 My_First : constant := -1.0;
28964 My_Last : constant := +1.0 - My_Small;
28966 type F2 is delta My_Small range My_First .. My_Last;
28972 for F2'Small use my_Small;
28973 for F2'Size use 16;
28976 In practice all compilers will do the same thing here and will give you
28977 what you want, so the above declarations are fully portable. If you really
28978 want to play language lawyer and guard against ludicrous behavior by the
28979 compiler you could add
28982 Test1 : constant := 1 / Boolean'Pos (F2'First = My_First);
28983 Test2 : constant := 1 / Boolean'Pos (F2'Last = My_Last);
28986 One or other or both are allowed to be illegal if the compiler is
28987 behaving in a silly manner, but at least the silly compiler will not
28988 get away with silently messing with your (very clear) intentions.
28990 If you follow this scheme you will be guaranteed that your fixed-point
28991 types will be portable.
28993 @node Compatibility with Ada 83,Compatibility between Ada 95 and Ada 2005,Writing Portable Fixed-Point Declarations,Compatibility and Porting Guide
28994 @anchor{gnat_rm/compatibility_and_porting_guide compatibility-with-ada-83}@anchor{445}@anchor{gnat_rm/compatibility_and_porting_guide id3}@anchor{446}
28995 @section Compatibility with Ada 83
28998 @geindex Compatibility (between Ada 83 and Ada 95 / Ada 2005 / Ada 2012)
29000 Ada 95 and the subsequent revisions Ada 2005 and Ada 2012
29001 are highly upwards compatible with Ada 83. In
29002 particular, the design intention was that the difficulties associated
29003 with moving from Ada 83 to later versions of the standard should be no greater
29004 than those that occur when moving from one Ada 83 system to another.
29006 However, there are a number of points at which there are minor
29007 incompatibilities. The @cite{Ada 95 Annotated Reference Manual} contains
29008 full details of these issues as they relate to Ada 95,
29009 and should be consulted for a complete treatment.
29011 following subsections treat the most likely issues to be encountered.
29014 * Legal Ada 83 programs that are illegal in Ada 95::
29015 * More deterministic semantics::
29016 * Changed semantics::
29017 * Other language compatibility issues::
29021 @node Legal Ada 83 programs that are illegal in Ada 95,More deterministic semantics,,Compatibility with Ada 83
29022 @anchor{gnat_rm/compatibility_and_porting_guide id4}@anchor{447}@anchor{gnat_rm/compatibility_and_porting_guide legal-ada-83-programs-that-are-illegal-in-ada-95}@anchor{448}
29023 @subsection Legal Ada 83 programs that are illegal in Ada 95
29026 Some legal Ada 83 programs are illegal (i.e., they will fail to compile) in
29027 Ada 95 and later versions of the standard:
29033 @emph{Character literals}
29035 Some uses of character literals are ambiguous. Since Ada 95 has introduced
29036 @code{Wide_Character} as a new predefined character type, some uses of
29037 character literals that were legal in Ada 83 are illegal in Ada 95.
29041 for Char in 'A' .. 'Z' loop ... end loop;
29044 The problem is that 'A' and 'Z' could be from either
29045 @code{Character} or @code{Wide_Character}. The simplest correction
29046 is to make the type explicit; e.g.:
29049 for Char in Character range 'A' .. 'Z' loop ... end loop;
29053 @emph{New reserved words}
29055 The identifiers @code{abstract}, @code{aliased}, @code{protected},
29056 @code{requeue}, @code{tagged}, and @code{until} are reserved in Ada 95.
29057 Existing Ada 83 code using any of these identifiers must be edited to
29058 use some alternative name.
29061 @emph{Freezing rules}
29063 The rules in Ada 95 are slightly different with regard to the point at
29064 which entities are frozen, and representation pragmas and clauses are
29065 not permitted past the freeze point. This shows up most typically in
29066 the form of an error message complaining that a representation item
29067 appears too late, and the appropriate corrective action is to move
29068 the item nearer to the declaration of the entity to which it refers.
29070 A particular case is that representation pragmas
29071 cannot be applied to a subprogram body. If necessary, a separate subprogram
29072 declaration must be introduced to which the pragma can be applied.
29075 @emph{Optional bodies for library packages}
29077 In Ada 83, a package that did not require a package body was nevertheless
29078 allowed to have one. This lead to certain surprises in compiling large
29079 systems (situations in which the body could be unexpectedly ignored by the
29080 binder). In Ada 95, if a package does not require a body then it is not
29081 permitted to have a body. To fix this problem, simply remove a redundant
29082 body if it is empty, or, if it is non-empty, introduce a dummy declaration
29083 into the spec that makes the body required. One approach is to add a private
29084 part to the package declaration (if necessary), and define a parameterless
29085 procedure called @code{Requires_Body}, which must then be given a dummy
29086 procedure body in the package body, which then becomes required.
29087 Another approach (assuming that this does not introduce elaboration
29088 circularities) is to add an @code{Elaborate_Body} pragma to the package spec,
29089 since one effect of this pragma is to require the presence of a package body.
29092 @emph{Numeric_Error is the same exception as Constraint_Error}
29094 In Ada 95, the exception @code{Numeric_Error} is a renaming of @code{Constraint_Error}.
29095 This means that it is illegal to have separate exception handlers for
29096 the two exceptions. The fix is simply to remove the handler for the
29097 @code{Numeric_Error} case (since even in Ada 83, a compiler was free to raise
29098 @code{Constraint_Error} in place of @code{Numeric_Error} in all cases).
29101 @emph{Indefinite subtypes in generics}
29103 In Ada 83, it was permissible to pass an indefinite type (e.g, @code{String})
29104 as the actual for a generic formal private type, but then the instantiation
29105 would be illegal if there were any instances of declarations of variables
29106 of this type in the generic body. In Ada 95, to avoid this clear violation
29107 of the methodological principle known as the 'contract model',
29108 the generic declaration explicitly indicates whether
29109 or not such instantiations are permitted. If a generic formal parameter
29110 has explicit unknown discriminants, indicated by using @code{(<>)} after the
29111 subtype name, then it can be instantiated with indefinite types, but no
29112 stand-alone variables can be declared of this type. Any attempt to declare
29113 such a variable will result in an illegality at the time the generic is
29114 declared. If the @code{(<>)} notation is not used, then it is illegal
29115 to instantiate the generic with an indefinite type.
29116 This is the potential incompatibility issue when porting Ada 83 code to Ada 95.
29117 It will show up as a compile time error, and
29118 the fix is usually simply to add the @code{(<>)} to the generic declaration.
29121 @node More deterministic semantics,Changed semantics,Legal Ada 83 programs that are illegal in Ada 95,Compatibility with Ada 83
29122 @anchor{gnat_rm/compatibility_and_porting_guide more-deterministic-semantics}@anchor{449}@anchor{gnat_rm/compatibility_and_porting_guide id5}@anchor{44a}
29123 @subsection More deterministic semantics
29132 Conversions from real types to integer types round away from 0. In Ada 83
29133 the conversion Integer(2.5) could deliver either 2 or 3 as its value. This
29134 implementation freedom was intended to support unbiased rounding in
29135 statistical applications, but in practice it interfered with portability.
29136 In Ada 95 the conversion semantics are unambiguous, and rounding away from 0
29137 is required. Numeric code may be affected by this change in semantics.
29138 Note, though, that this issue is no worse than already existed in Ada 83
29139 when porting code from one vendor to another.
29144 The Real-Time Annex introduces a set of policies that define the behavior of
29145 features that were implementation dependent in Ada 83, such as the order in
29146 which open select branches are executed.
29149 @node Changed semantics,Other language compatibility issues,More deterministic semantics,Compatibility with Ada 83
29150 @anchor{gnat_rm/compatibility_and_porting_guide id6}@anchor{44b}@anchor{gnat_rm/compatibility_and_porting_guide changed-semantics}@anchor{44c}
29151 @subsection Changed semantics
29154 The worst kind of incompatibility is one where a program that is legal in
29155 Ada 83 is also legal in Ada 95 but can have an effect in Ada 95 that was not
29156 possible in Ada 83. Fortunately this is extremely rare, but the one
29157 situation that you should be alert to is the change in the predefined type
29158 @code{Character} from 7-bit ASCII to 8-bit Latin-1.
29169 @emph{Range of type `@w{`}Character`@w{`}}
29171 The range of @code{Standard.Character} is now the full 256 characters
29172 of Latin-1, whereas in most Ada 83 implementations it was restricted
29173 to 128 characters. Although some of the effects of
29174 this change will be manifest in compile-time rejection of legal
29175 Ada 83 programs it is possible for a working Ada 83 program to have
29176 a different effect in Ada 95, one that was not permitted in Ada 83.
29177 As an example, the expression
29178 @code{Character'Pos(Character'Last)} returned @code{127} in Ada 83 and now
29179 delivers @code{255} as its value.
29180 In general, you should look at the logic of any
29181 character-processing Ada 83 program and see whether it needs to be adapted
29182 to work correctly with Latin-1. Note that the predefined Ada 95 API has a
29183 character handling package that may be relevant if code needs to be adapted
29184 to account for the additional Latin-1 elements.
29185 The desirable fix is to
29186 modify the program to accommodate the full character set, but in some cases
29187 it may be convenient to define a subtype or derived type of Character that
29188 covers only the restricted range.
29191 @node Other language compatibility issues,,Changed semantics,Compatibility with Ada 83
29192 @anchor{gnat_rm/compatibility_and_porting_guide other-language-compatibility-issues}@anchor{44d}@anchor{gnat_rm/compatibility_and_porting_guide id7}@anchor{44e}
29193 @subsection Other language compatibility issues
29200 @emph{-gnat83} switch
29202 All implementations of GNAT provide a switch that causes GNAT to operate
29203 in Ada 83 mode. In this mode, some but not all compatibility problems
29204 of the type described above are handled automatically. For example, the
29205 new reserved words introduced in Ada 95 and Ada 2005 are treated simply
29206 as identifiers as in Ada 83. However,
29207 in practice, it is usually advisable to make the necessary modifications
29208 to the program to remove the need for using this switch.
29209 See the @code{Compiling Different Versions of Ada} section in
29210 the @cite{GNAT User's Guide}.
29213 Support for removed Ada 83 pragmas and attributes
29215 A number of pragmas and attributes from Ada 83 were removed from Ada 95,
29216 generally because they were replaced by other mechanisms. Ada 95 and Ada 2005
29217 compilers are allowed, but not required, to implement these missing
29218 elements. In contrast with some other compilers, GNAT implements all
29219 such pragmas and attributes, eliminating this compatibility concern. These
29220 include @code{pragma Interface} and the floating point type attributes
29221 (@code{Emax}, @code{Mantissa}, etc.), among other items.
29224 @node Compatibility between Ada 95 and Ada 2005,Implementation-dependent characteristics,Compatibility with Ada 83,Compatibility and Porting Guide
29225 @anchor{gnat_rm/compatibility_and_porting_guide compatibility-between-ada-95-and-ada-2005}@anchor{44f}@anchor{gnat_rm/compatibility_and_porting_guide id8}@anchor{450}
29226 @section Compatibility between Ada 95 and Ada 2005
29229 @geindex Compatibility between Ada 95 and Ada 2005
29231 Although Ada 2005 was designed to be upwards compatible with Ada 95, there are
29232 a number of incompatibilities. Several are enumerated below;
29233 for a complete description please see the
29234 @cite{Annotated Ada 2005 Reference Manual}, or section 9.1.1 in
29235 @cite{Rationale for Ada 2005}.
29241 @emph{New reserved words.}
29243 The words @code{interface}, @code{overriding} and @code{synchronized} are
29244 reserved in Ada 2005.
29245 A pre-Ada 2005 program that uses any of these as an identifier will be
29249 @emph{New declarations in predefined packages.}
29251 A number of packages in the predefined environment contain new declarations:
29252 @code{Ada.Exceptions}, @code{Ada.Real_Time}, @code{Ada.Strings},
29253 @code{Ada.Strings.Fixed}, @code{Ada.Strings.Bounded},
29254 @code{Ada.Strings.Unbounded}, @code{Ada.Strings.Wide_Fixed},
29255 @code{Ada.Strings.Wide_Bounded}, @code{Ada.Strings.Wide_Unbounded},
29256 @code{Ada.Tags}, @code{Ada.Text_IO}, and @code{Interfaces.C}.
29257 If an Ada 95 program does a @code{with} and @code{use} of any of these
29258 packages, the new declarations may cause name clashes.
29261 @emph{Access parameters.}
29263 A nondispatching subprogram with an access parameter cannot be renamed
29264 as a dispatching operation. This was permitted in Ada 95.
29267 @emph{Access types, discriminants, and constraints.}
29269 Rule changes in this area have led to some incompatibilities; for example,
29270 constrained subtypes of some access types are not permitted in Ada 2005.
29273 @emph{Aggregates for limited types.}
29275 The allowance of aggregates for limited types in Ada 2005 raises the
29276 possibility of ambiguities in legal Ada 95 programs, since additional types
29277 now need to be considered in expression resolution.
29280 @emph{Fixed-point multiplication and division.}
29282 Certain expressions involving '*' or '/' for a fixed-point type, which
29283 were legal in Ada 95 and invoked the predefined versions of these operations,
29285 The ambiguity may be resolved either by applying a type conversion to the
29286 expression, or by explicitly invoking the operation from package
29290 @emph{Return-by-reference types.}
29292 The Ada 95 return-by-reference mechanism has been removed. Instead, the user
29293 can declare a function returning a value from an anonymous access type.
29296 @node Implementation-dependent characteristics,Compatibility with Other Ada Systems,Compatibility between Ada 95 and Ada 2005,Compatibility and Porting Guide
29297 @anchor{gnat_rm/compatibility_and_porting_guide implementation-dependent-characteristics}@anchor{451}@anchor{gnat_rm/compatibility_and_porting_guide id9}@anchor{452}
29298 @section Implementation-dependent characteristics
29301 Although the Ada language defines the semantics of each construct as
29302 precisely as practical, in some situations (for example for reasons of
29303 efficiency, or where the effect is heavily dependent on the host or target
29304 platform) the implementation is allowed some freedom. In porting Ada 83
29305 code to GNAT, you need to be aware of whether / how the existing code
29306 exercised such implementation dependencies. Such characteristics fall into
29307 several categories, and GNAT offers specific support in assisting the
29308 transition from certain Ada 83 compilers.
29311 * Implementation-defined pragmas::
29312 * Implementation-defined attributes::
29314 * Elaboration order::
29315 * Target-specific aspects::
29319 @node Implementation-defined pragmas,Implementation-defined attributes,,Implementation-dependent characteristics
29320 @anchor{gnat_rm/compatibility_and_porting_guide implementation-defined-pragmas}@anchor{453}@anchor{gnat_rm/compatibility_and_porting_guide id10}@anchor{454}
29321 @subsection Implementation-defined pragmas
29324 Ada compilers are allowed to supplement the language-defined pragmas, and
29325 these are a potential source of non-portability. All GNAT-defined pragmas
29326 are described in @ref{7,,Implementation Defined Pragmas},
29327 and these include several that are specifically
29328 intended to correspond to other vendors' Ada 83 pragmas.
29329 For migrating from VADS, the pragma @code{Use_VADS_Size} may be useful.
29330 For compatibility with HP Ada 83, GNAT supplies the pragmas
29331 @code{Extend_System}, @code{Ident}, @code{Inline_Generic},
29332 @code{Interface_Name}, @code{Passive}, @code{Suppress_All},
29333 and @code{Volatile}.
29334 Other relevant pragmas include @code{External} and @code{Link_With}.
29335 Some vendor-specific
29336 Ada 83 pragmas (@code{Share_Generic}, @code{Subtitle}, and @code{Title}) are
29338 avoiding compiler rejection of units that contain such pragmas; they are not
29339 relevant in a GNAT context and hence are not otherwise implemented.
29341 @node Implementation-defined attributes,Libraries,Implementation-defined pragmas,Implementation-dependent characteristics
29342 @anchor{gnat_rm/compatibility_and_porting_guide id11}@anchor{455}@anchor{gnat_rm/compatibility_and_porting_guide implementation-defined-attributes}@anchor{456}
29343 @subsection Implementation-defined attributes
29346 Analogous to pragmas, the set of attributes may be extended by an
29347 implementation. All GNAT-defined attributes are described in
29348 @ref{8,,Implementation Defined Attributes},
29349 and these include several that are specifically intended
29350 to correspond to other vendors' Ada 83 attributes. For migrating from VADS,
29351 the attribute @code{VADS_Size} may be useful. For compatibility with HP
29352 Ada 83, GNAT supplies the attributes @code{Bit}, @code{Machine_Size} and
29355 @node Libraries,Elaboration order,Implementation-defined attributes,Implementation-dependent characteristics
29356 @anchor{gnat_rm/compatibility_and_porting_guide libraries}@anchor{457}@anchor{gnat_rm/compatibility_and_porting_guide id12}@anchor{458}
29357 @subsection Libraries
29360 Vendors may supply libraries to supplement the standard Ada API. If Ada 83
29361 code uses vendor-specific libraries then there are several ways to manage
29362 this in Ada 95 and later versions of the standard:
29368 If the source code for the libraries (specs and bodies) are
29369 available, then the libraries can be migrated in the same way as the
29373 If the source code for the specs but not the bodies are
29374 available, then you can reimplement the bodies.
29377 Some features introduced by Ada 95 obviate the need for library support. For
29378 example most Ada 83 vendors supplied a package for unsigned integers. The
29379 Ada 95 modular type feature is the preferred way to handle this need, so
29380 instead of migrating or reimplementing the unsigned integer package it may
29381 be preferable to retrofit the application using modular types.
29384 @node Elaboration order,Target-specific aspects,Libraries,Implementation-dependent characteristics
29385 @anchor{gnat_rm/compatibility_and_porting_guide elaboration-order}@anchor{459}@anchor{gnat_rm/compatibility_and_porting_guide id13}@anchor{45a}
29386 @subsection Elaboration order
29389 The implementation can choose any elaboration order consistent with the unit
29390 dependency relationship. This freedom means that some orders can result in
29391 Program_Error being raised due to an 'Access Before Elaboration': an attempt
29392 to invoke a subprogram before its body has been elaborated, or to instantiate
29393 a generic before the generic body has been elaborated. By default GNAT
29394 attempts to choose a safe order (one that will not encounter access before
29395 elaboration problems) by implicitly inserting @code{Elaborate} or
29396 @code{Elaborate_All} pragmas where
29397 needed. However, this can lead to the creation of elaboration circularities
29398 and a resulting rejection of the program by gnatbind. This issue is
29399 thoroughly described in the @emph{Elaboration Order Handling in GNAT} appendix
29400 in the @cite{GNAT User's Guide}.
29401 In brief, there are several
29402 ways to deal with this situation:
29408 Modify the program to eliminate the circularities, e.g., by moving
29409 elaboration-time code into explicitly-invoked procedures
29412 Constrain the elaboration order by including explicit @code{Elaborate_Body} or
29413 @code{Elaborate} pragmas, and then inhibit the generation of implicit
29414 @code{Elaborate_All}
29415 pragmas either globally (as an effect of the @emph{-gnatE} switch) or locally
29416 (by selectively suppressing elaboration checks via pragma
29417 @code{Suppress(Elaboration_Check)} when it is safe to do so).
29420 @node Target-specific aspects,,Elaboration order,Implementation-dependent characteristics
29421 @anchor{gnat_rm/compatibility_and_porting_guide target-specific-aspects}@anchor{45b}@anchor{gnat_rm/compatibility_and_porting_guide id14}@anchor{45c}
29422 @subsection Target-specific aspects
29425 Low-level applications need to deal with machine addresses, data
29426 representations, interfacing with assembler code, and similar issues. If
29427 such an Ada 83 application is being ported to different target hardware (for
29428 example where the byte endianness has changed) then you will need to
29429 carefully examine the program logic; the porting effort will heavily depend
29430 on the robustness of the original design. Moreover, Ada 95 (and thus
29431 Ada 2005 and Ada 2012) are sometimes
29432 incompatible with typical Ada 83 compiler practices regarding implicit
29433 packing, the meaning of the Size attribute, and the size of access values.
29434 GNAT's approach to these issues is described in @ref{45d,,Representation Clauses}.
29436 @node Compatibility with Other Ada Systems,Representation Clauses,Implementation-dependent characteristics,Compatibility and Porting Guide
29437 @anchor{gnat_rm/compatibility_and_porting_guide id15}@anchor{45e}@anchor{gnat_rm/compatibility_and_porting_guide compatibility-with-other-ada-systems}@anchor{45f}
29438 @section Compatibility with Other Ada Systems
29441 If programs avoid the use of implementation dependent and
29442 implementation defined features, as documented in the
29443 @cite{Ada Reference Manual}, there should be a high degree of portability between
29444 GNAT and other Ada systems. The following are specific items which
29445 have proved troublesome in moving Ada 95 programs from GNAT to other Ada 95
29446 compilers, but do not affect porting code to GNAT.
29447 (As of January 2007, GNAT is the only compiler available for Ada 2005;
29448 the following issues may or may not arise for Ada 2005 programs
29449 when other compilers appear.)
29455 @emph{Ada 83 Pragmas and Attributes}
29457 Ada 95 compilers are allowed, but not required, to implement the missing
29458 Ada 83 pragmas and attributes that are no longer defined in Ada 95.
29459 GNAT implements all such pragmas and attributes, eliminating this as
29460 a compatibility concern, but some other Ada 95 compilers reject these
29461 pragmas and attributes.
29464 @emph{Specialized Needs Annexes}
29466 GNAT implements the full set of special needs annexes. At the
29467 current time, it is the only Ada 95 compiler to do so. This means that
29468 programs making use of these features may not be portable to other Ada
29469 95 compilation systems.
29472 @emph{Representation Clauses}
29474 Some other Ada 95 compilers implement only the minimal set of
29475 representation clauses required by the Ada 95 reference manual. GNAT goes
29476 far beyond this minimal set, as described in the next section.
29479 @node Representation Clauses,Compatibility with HP Ada 83,Compatibility with Other Ada Systems,Compatibility and Porting Guide
29480 @anchor{gnat_rm/compatibility_and_porting_guide representation-clauses}@anchor{45d}@anchor{gnat_rm/compatibility_and_porting_guide id16}@anchor{460}
29481 @section Representation Clauses
29484 The Ada 83 reference manual was quite vague in describing both the minimal
29485 required implementation of representation clauses, and also their precise
29486 effects. Ada 95 (and thus also Ada 2005) are much more explicit, but the
29487 minimal set of capabilities required is still quite limited.
29489 GNAT implements the full required set of capabilities in
29490 Ada 95 and Ada 2005, but also goes much further, and in particular
29491 an effort has been made to be compatible with existing Ada 83 usage to the
29492 greatest extent possible.
29494 A few cases exist in which Ada 83 compiler behavior is incompatible with
29495 the requirements in Ada 95 (and thus also Ada 2005). These are instances of
29496 intentional or accidental dependence on specific implementation dependent
29497 characteristics of these Ada 83 compilers. The following is a list of
29498 the cases most likely to arise in existing Ada 83 code.
29504 @emph{Implicit Packing}
29506 Some Ada 83 compilers allowed a Size specification to cause implicit
29507 packing of an array or record. This could cause expensive implicit
29508 conversions for change of representation in the presence of derived
29509 types, and the Ada design intends to avoid this possibility.
29510 Subsequent AI's were issued to make it clear that such implicit
29511 change of representation in response to a Size clause is inadvisable,
29512 and this recommendation is represented explicitly in the Ada 95 (and Ada 2005)
29513 Reference Manuals as implementation advice that is followed by GNAT.
29514 The problem will show up as an error
29515 message rejecting the size clause. The fix is simply to provide
29516 the explicit pragma @code{Pack}, or for more fine tuned control, provide
29517 a Component_Size clause.
29520 @emph{Meaning of Size Attribute}
29522 The Size attribute in Ada 95 (and Ada 2005) for discrete types is defined as
29523 the minimal number of bits required to hold values of the type. For example,
29524 on a 32-bit machine, the size of @code{Natural} will typically be 31 and not
29525 32 (since no sign bit is required). Some Ada 83 compilers gave 31, and
29526 some 32 in this situation. This problem will usually show up as a compile
29527 time error, but not always. It is a good idea to check all uses of the
29528 'Size attribute when porting Ada 83 code. The GNAT specific attribute
29529 Object_Size can provide a useful way of duplicating the behavior of
29530 some Ada 83 compiler systems.
29533 @emph{Size of Access Types}
29535 A common assumption in Ada 83 code is that an access type is in fact a pointer,
29536 and that therefore it will be the same size as a System.Address value. This
29537 assumption is true for GNAT in most cases with one exception. For the case of
29538 a pointer to an unconstrained array type (where the bounds may vary from one
29539 value of the access type to another), the default is to use a 'fat pointer',
29540 which is represented as two separate pointers, one to the bounds, and one to
29541 the array. This representation has a number of advantages, including improved
29542 efficiency. However, it may cause some difficulties in porting existing Ada 83
29543 code which makes the assumption that, for example, pointers fit in 32 bits on
29544 a machine with 32-bit addressing.
29546 To get around this problem, GNAT also permits the use of 'thin pointers' for
29547 access types in this case (where the designated type is an unconstrained array
29548 type). These thin pointers are indeed the same size as a System.Address value.
29549 To specify a thin pointer, use a size clause for the type, for example:
29552 type X is access all String;
29553 for X'Size use Standard'Address_Size;
29556 which will cause the type X to be represented using a single pointer.
29557 When using this representation, the bounds are right behind the array.
29558 This representation is slightly less efficient, and does not allow quite
29559 such flexibility in the use of foreign pointers or in using the
29560 Unrestricted_Access attribute to create pointers to non-aliased objects.
29561 But for any standard portable use of the access type it will work in
29562 a functionally correct manner and allow porting of existing code.
29563 Note that another way of forcing a thin pointer representation
29564 is to use a component size clause for the element size in an array,
29565 or a record representation clause for an access field in a record.
29567 See the documentation of Unrestricted_Access in the GNAT RM for a
29568 full discussion of possible problems using this attribute in conjunction
29569 with thin pointers.
29572 @node Compatibility with HP Ada 83,,Representation Clauses,Compatibility and Porting Guide
29573 @anchor{gnat_rm/compatibility_and_porting_guide compatibility-with-hp-ada-83}@anchor{461}@anchor{gnat_rm/compatibility_and_porting_guide id17}@anchor{462}
29574 @section Compatibility with HP Ada 83
29577 All the HP Ada 83 pragmas and attributes are recognized, although only a subset
29578 of them can sensibly be implemented. The description of pragmas in
29579 @ref{7,,Implementation Defined Pragmas} indicates whether or not they are
29580 applicable to GNAT.
29586 @emph{Default floating-point representation}
29588 In GNAT, the default floating-point format is IEEE, whereas in HP Ada 83,
29594 the package System in GNAT exactly corresponds to the definition in the
29595 Ada 95 reference manual, which means that it excludes many of the
29596 HP Ada 83 extensions. However, a separate package Aux_DEC is provided
29597 that contains the additional definitions, and a special pragma,
29598 Extend_System allows this package to be treated transparently as an
29599 extension of package System.
29602 @node GNU Free Documentation License,Index,Compatibility and Porting Guide,Top
29603 @anchor{share/gnu_free_documentation_license gnu-fdl}@anchor{1}@anchor{share/gnu_free_documentation_license doc}@anchor{463}@anchor{share/gnu_free_documentation_license gnu-free-documentation-license}@anchor{464}
29604 @chapter GNU Free Documentation License
29607 Version 1.3, 3 November 2008
29609 Copyright 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc
29610 @indicateurl{http://fsf.org/}
29612 Everyone is permitted to copy and distribute verbatim copies of this
29613 license document, but changing it is not allowed.
29617 The purpose of this License is to make a manual, textbook, or other
29618 functional and useful document "free" in the sense of freedom: to
29619 assure everyone the effective freedom to copy and redistribute it,
29620 with or without modifying it, either commercially or noncommercially.
29621 Secondarily, this License preserves for the author and publisher a way
29622 to get credit for their work, while not being considered responsible
29623 for modifications made by others.
29625 This License is a kind of "copyleft", which means that derivative
29626 works of the document must themselves be free in the same sense. It
29627 complements the GNU General Public License, which is a copyleft
29628 license designed for free software.
29630 We have designed this License in order to use it for manuals for free
29631 software, because free software needs free documentation: a free
29632 program should come with manuals providing the same freedoms that the
29633 software does. But this License is not limited to software manuals;
29634 it can be used for any textual work, regardless of subject matter or
29635 whether it is published as a printed book. We recommend this License
29636 principally for works whose purpose is instruction or reference.
29638 @strong{1. APPLICABILITY AND DEFINITIONS}
29640 This License applies to any manual or other work, in any medium, that
29641 contains a notice placed by the copyright holder saying it can be
29642 distributed under the terms of this License. Such a notice grants a
29643 world-wide, royalty-free license, unlimited in duration, to use that
29644 work under the conditions stated herein. The @strong{Document}, below,
29645 refers to any such manual or work. Any member of the public is a
29646 licensee, and is addressed as "@strong{you}". You accept the license if you
29647 copy, modify or distribute the work in a way requiring permission
29648 under copyright law.
29650 A "@strong{Modified Version}" of the Document means any work containing the
29651 Document or a portion of it, either copied verbatim, or with
29652 modifications and/or translated into another language.
29654 A "@strong{Secondary Section}" is a named appendix or a front-matter section of
29655 the Document that deals exclusively with the relationship of the
29656 publishers or authors of the Document to the Document's overall subject
29657 (or to related matters) and contains nothing that could fall directly
29658 within that overall subject. (Thus, if the Document is in part a
29659 textbook of mathematics, a Secondary Section may not explain any
29660 mathematics.) The relationship could be a matter of historical
29661 connection with the subject or with related matters, or of legal,
29662 commercial, philosophical, ethical or political position regarding
29665 The "@strong{Invariant Sections}" are certain Secondary Sections whose titles
29666 are designated, as being those of Invariant Sections, in the notice
29667 that says that the Document is released under this License. If a
29668 section does not fit the above definition of Secondary then it is not
29669 allowed to be designated as Invariant. The Document may contain zero
29670 Invariant Sections. If the Document does not identify any Invariant
29671 Sections then there are none.
29673 The "@strong{Cover Texts}" are certain short passages of text that are listed,
29674 as Front-Cover Texts or Back-Cover Texts, in the notice that says that
29675 the Document is released under this License. A Front-Cover Text may
29676 be at most 5 words, and a Back-Cover Text may be at most 25 words.
29678 A "@strong{Transparent}" copy of the Document means a machine-readable copy,
29679 represented in a format whose specification is available to the
29680 general public, that is suitable for revising the document
29681 straightforwardly with generic text editors or (for images composed of
29682 pixels) generic paint programs or (for drawings) some widely available
29683 drawing editor, and that is suitable for input to text formatters or
29684 for automatic translation to a variety of formats suitable for input
29685 to text formatters. A copy made in an otherwise Transparent file
29686 format whose markup, or absence of markup, has been arranged to thwart
29687 or discourage subsequent modification by readers is not Transparent.
29688 An image format is not Transparent if used for any substantial amount
29689 of text. A copy that is not "Transparent" is called @strong{Opaque}.
29691 Examples of suitable formats for Transparent copies include plain
29692 ASCII without markup, Texinfo input format, LaTeX input format, SGML
29693 or XML using a publicly available DTD, and standard-conforming simple
29694 HTML, PostScript or PDF designed for human modification. Examples of
29695 transparent image formats include PNG, XCF and JPG. Opaque formats
29696 include proprietary formats that can be read and edited only by
29697 proprietary word processors, SGML or XML for which the DTD and/or
29698 processing tools are not generally available, and the
29699 machine-generated HTML, PostScript or PDF produced by some word
29700 processors for output purposes only.
29702 The "@strong{Title Page}" means, for a printed book, the title page itself,
29703 plus such following pages as are needed to hold, legibly, the material
29704 this License requires to appear in the title page. For works in
29705 formats which do not have any title page as such, "Title Page" means
29706 the text near the most prominent appearance of the work's title,
29707 preceding the beginning of the body of the text.
29709 The "@strong{publisher}" means any person or entity that distributes
29710 copies of the Document to the public.
29712 A section "@strong{Entitled XYZ}" means a named subunit of the Document whose
29713 title either is precisely XYZ or contains XYZ in parentheses following
29714 text that translates XYZ in another language. (Here XYZ stands for a
29715 specific section name mentioned below, such as "@strong{Acknowledgements}",
29716 "@strong{Dedications}", "@strong{Endorsements}", or "@strong{History}".)
29717 To "@strong{Preserve the Title}"
29718 of such a section when you modify the Document means that it remains a
29719 section "Entitled XYZ" according to this definition.
29721 The Document may include Warranty Disclaimers next to the notice which
29722 states that this License applies to the Document. These Warranty
29723 Disclaimers are considered to be included by reference in this
29724 License, but only as regards disclaiming warranties: any other
29725 implication that these Warranty Disclaimers may have is void and has
29726 no effect on the meaning of this License.
29728 @strong{2. VERBATIM COPYING}
29730 You may copy and distribute the Document in any medium, either
29731 commercially or noncommercially, provided that this License, the
29732 copyright notices, and the license notice saying this License applies
29733 to the Document are reproduced in all copies, and that you add no other
29734 conditions whatsoever to those of this License. You may not use
29735 technical measures to obstruct or control the reading or further
29736 copying of the copies you make or distribute. However, you may accept
29737 compensation in exchange for copies. If you distribute a large enough
29738 number of copies you must also follow the conditions in section 3.
29740 You may also lend copies, under the same conditions stated above, and
29741 you may publicly display copies.
29743 @strong{3. COPYING IN QUANTITY}
29745 If you publish printed copies (or copies in media that commonly have
29746 printed covers) of the Document, numbering more than 100, and the
29747 Document's license notice requires Cover Texts, you must enclose the
29748 copies in covers that carry, clearly and legibly, all these Cover
29749 Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
29750 the back cover. Both covers must also clearly and legibly identify
29751 you as the publisher of these copies. The front cover must present
29752 the full title with all words of the title equally prominent and
29753 visible. You may add other material on the covers in addition.
29754 Copying with changes limited to the covers, as long as they preserve
29755 the title of the Document and satisfy these conditions, can be treated
29756 as verbatim copying in other respects.
29758 If the required texts for either cover are too voluminous to fit
29759 legibly, you should put the first ones listed (as many as fit
29760 reasonably) on the actual cover, and continue the rest onto adjacent
29763 If you publish or distribute Opaque copies of the Document numbering
29764 more than 100, you must either include a machine-readable Transparent
29765 copy along with each Opaque copy, or state in or with each Opaque copy
29766 a computer-network location from which the general network-using
29767 public has access to download using public-standard network protocols
29768 a complete Transparent copy of the Document, free of added material.
29769 If you use the latter option, you must take reasonably prudent steps,
29770 when you begin distribution of Opaque copies in quantity, to ensure
29771 that this Transparent copy will remain thus accessible at the stated
29772 location until at least one year after the last time you distribute an
29773 Opaque copy (directly or through your agents or retailers) of that
29774 edition to the public.
29776 It is requested, but not required, that you contact the authors of the
29777 Document well before redistributing any large number of copies, to give
29778 them a chance to provide you with an updated version of the Document.
29780 @strong{4. MODIFICATIONS}
29782 You may copy and distribute a Modified Version of the Document under
29783 the conditions of sections 2 and 3 above, provided that you release
29784 the Modified Version under precisely this License, with the Modified
29785 Version filling the role of the Document, thus licensing distribution
29786 and modification of the Modified Version to whoever possesses a copy
29787 of it. In addition, you must do these things in the Modified Version:
29793 Use in the Title Page (and on the covers, if any) a title distinct
29794 from that of the Document, and from those of previous versions
29795 (which should, if there were any, be listed in the History section
29796 of the Document). You may use the same title as a previous version
29797 if the original publisher of that version gives permission.
29800 List on the Title Page, as authors, one or more persons or entities
29801 responsible for authorship of the modifications in the Modified
29802 Version, together with at least five of the principal authors of the
29803 Document (all of its principal authors, if it has fewer than five),
29804 unless they release you from this requirement.
29807 State on the Title page the name of the publisher of the
29808 Modified Version, as the publisher.
29811 Preserve all the copyright notices of the Document.
29814 Add an appropriate copyright notice for your modifications
29815 adjacent to the other copyright notices.
29818 Include, immediately after the copyright notices, a license notice
29819 giving the public permission to use the Modified Version under the
29820 terms of this License, in the form shown in the Addendum below.
29823 Preserve in that license notice the full lists of Invariant Sections
29824 and required Cover Texts given in the Document's license notice.
29827 Include an unaltered copy of this License.
29830 Preserve the section Entitled "History", Preserve its Title, and add
29831 to it an item stating at least the title, year, new authors, and
29832 publisher of the Modified Version as given on the Title Page. If
29833 there is no section Entitled "History" in the Document, create one
29834 stating the title, year, authors, and publisher of the Document as
29835 given on its Title Page, then add an item describing the Modified
29836 Version as stated in the previous sentence.
29839 Preserve the network location, if any, given in the Document for
29840 public access to a Transparent copy of the Document, and likewise
29841 the network locations given in the Document for previous versions
29842 it was based on. These may be placed in the "History" section.
29843 You may omit a network location for a work that was published at
29844 least four years before the Document itself, or if the original
29845 publisher of the version it refers to gives permission.
29848 For any section Entitled "Acknowledgements" or "Dedications",
29849 Preserve the Title of the section, and preserve in the section all
29850 the substance and tone of each of the contributor acknowledgements
29851 and/or dedications given therein.
29854 Preserve all the Invariant Sections of the Document,
29855 unaltered in their text and in their titles. Section numbers
29856 or the equivalent are not considered part of the section titles.
29859 Delete any section Entitled "Endorsements". Such a section
29860 may not be included in the Modified Version.
29863 Do not retitle any existing section to be Entitled "Endorsements"
29864 or to conflict in title with any Invariant Section.
29867 Preserve any Warranty Disclaimers.
29870 If the Modified Version includes new front-matter sections or
29871 appendices that qualify as Secondary Sections and contain no material
29872 copied from the Document, you may at your option designate some or all
29873 of these sections as invariant. To do this, add their titles to the
29874 list of Invariant Sections in the Modified Version's license notice.
29875 These titles must be distinct from any other section titles.
29877 You may add a section Entitled "Endorsements", provided it contains
29878 nothing but endorsements of your Modified Version by various
29879 parties---for example, statements of peer review or that the text has
29880 been approved by an organization as the authoritative definition of a
29883 You may add a passage of up to five words as a Front-Cover Text, and a
29884 passage of up to 25 words as a Back-Cover Text, to the end of the list
29885 of Cover Texts in the Modified Version. Only one passage of
29886 Front-Cover Text and one of Back-Cover Text may be added by (or
29887 through arrangements made by) any one entity. If the Document already
29888 includes a cover text for the same cover, previously added by you or
29889 by arrangement made by the same entity you are acting on behalf of,
29890 you may not add another; but you may replace the old one, on explicit
29891 permission from the previous publisher that added the old one.
29893 The author(s) and publisher(s) of the Document do not by this License
29894 give permission to use their names for publicity for or to assert or
29895 imply endorsement of any Modified Version.
29897 @strong{5. COMBINING DOCUMENTS}
29899 You may combine the Document with other documents released under this
29900 License, under the terms defined in section 4 above for modified
29901 versions, provided that you include in the combination all of the
29902 Invariant Sections of all of the original documents, unmodified, and
29903 list them all as Invariant Sections of your combined work in its
29904 license notice, and that you preserve all their Warranty Disclaimers.
29906 The combined work need only contain one copy of this License, and
29907 multiple identical Invariant Sections may be replaced with a single
29908 copy. If there are multiple Invariant Sections with the same name but
29909 different contents, make the title of each such section unique by
29910 adding at the end of it, in parentheses, the name of the original
29911 author or publisher of that section if known, or else a unique number.
29912 Make the same adjustment to the section titles in the list of
29913 Invariant Sections in the license notice of the combined work.
29915 In the combination, you must combine any sections Entitled "History"
29916 in the various original documents, forming one section Entitled
29917 "History"; likewise combine any sections Entitled "Acknowledgements",
29918 and any sections Entitled "Dedications". You must delete all sections
29919 Entitled "Endorsements".
29921 @strong{6. COLLECTIONS OF DOCUMENTS}
29923 You may make a collection consisting of the Document and other documents
29924 released under this License, and replace the individual copies of this
29925 License in the various documents with a single copy that is included in
29926 the collection, provided that you follow the rules of this License for
29927 verbatim copying of each of the documents in all other respects.
29929 You may extract a single document from such a collection, and distribute
29930 it individually under this License, provided you insert a copy of this
29931 License into the extracted document, and follow this License in all
29932 other respects regarding verbatim copying of that document.
29934 @strong{7. AGGREGATION WITH INDEPENDENT WORKS}
29936 A compilation of the Document or its derivatives with other separate
29937 and independent documents or works, in or on a volume of a storage or
29938 distribution medium, is called an "aggregate" if the copyright
29939 resulting from the compilation is not used to limit the legal rights
29940 of the compilation's users beyond what the individual works permit.
29941 When the Document is included in an aggregate, this License does not
29942 apply to the other works in the aggregate which are not themselves
29943 derivative works of the Document.
29945 If the Cover Text requirement of section 3 is applicable to these
29946 copies of the Document, then if the Document is less than one half of
29947 the entire aggregate, the Document's Cover Texts may be placed on
29948 covers that bracket the Document within the aggregate, or the
29949 electronic equivalent of covers if the Document is in electronic form.
29950 Otherwise they must appear on printed covers that bracket the whole
29953 @strong{8. TRANSLATION}
29955 Translation is considered a kind of modification, so you may
29956 distribute translations of the Document under the terms of section 4.
29957 Replacing Invariant Sections with translations requires special
29958 permission from their copyright holders, but you may include
29959 translations of some or all Invariant Sections in addition to the
29960 original versions of these Invariant Sections. You may include a
29961 translation of this License, and all the license notices in the
29962 Document, and any Warranty Disclaimers, provided that you also include
29963 the original English version of this License and the original versions
29964 of those notices and disclaimers. In case of a disagreement between
29965 the translation and the original version of this License or a notice
29966 or disclaimer, the original version will prevail.
29968 If a section in the Document is Entitled "Acknowledgements",
29969 "Dedications", or "History", the requirement (section 4) to Preserve
29970 its Title (section 1) will typically require changing the actual
29973 @strong{9. TERMINATION}
29975 You may not copy, modify, sublicense, or distribute the Document
29976 except as expressly provided under this License. Any attempt
29977 otherwise to copy, modify, sublicense, or distribute it is void, and
29978 will automatically terminate your rights under this License.
29980 However, if you cease all violation of this License, then your license
29981 from a particular copyright holder is reinstated (a) provisionally,
29982 unless and until the copyright holder explicitly and finally
29983 terminates your license, and (b) permanently, if the copyright holder
29984 fails to notify you of the violation by some reasonable means prior to
29985 60 days after the cessation.
29987 Moreover, your license from a particular copyright holder is
29988 reinstated permanently if the copyright holder notifies you of the
29989 violation by some reasonable means, this is the first time you have
29990 received notice of violation of this License (for any work) from that
29991 copyright holder, and you cure the violation prior to 30 days after
29992 your receipt of the notice.
29994 Termination of your rights under this section does not terminate the
29995 licenses of parties who have received copies or rights from you under
29996 this License. If your rights have been terminated and not permanently
29997 reinstated, receipt of a copy of some or all of the same material does
29998 not give you any rights to use it.
30000 @strong{10. FUTURE REVISIONS OF THIS LICENSE}
30002 The Free Software Foundation may publish new, revised versions
30003 of the GNU Free Documentation License from time to time. Such new
30004 versions will be similar in spirit to the present version, but may
30005 differ in detail to address new problems or concerns. See
30006 @indicateurl{http://www.gnu.org/copyleft/}.
30008 Each version of the License is given a distinguishing version number.
30009 If the Document specifies that a particular numbered version of this
30010 License "or any later version" applies to it, you have the option of
30011 following the terms and conditions either of that specified version or
30012 of any later version that has been published (not as a draft) by the
30013 Free Software Foundation. If the Document does not specify a version
30014 number of this License, you may choose any version ever published (not
30015 as a draft) by the Free Software Foundation. If the Document
30016 specifies that a proxy can decide which future versions of this
30017 License can be used, that proxy's public statement of acceptance of a
30018 version permanently authorizes you to choose that version for the
30021 @strong{11. RELICENSING}
30023 "Massive Multiauthor Collaboration Site" (or "MMC Site") means any
30024 World Wide Web server that publishes copyrightable works and also
30025 provides prominent facilities for anybody to edit those works. A
30026 public wiki that anybody can edit is an example of such a server. A
30027 "Massive Multiauthor Collaboration" (or "MMC") contained in the
30028 site means any set of copyrightable works thus published on the MMC
30031 "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0
30032 license published by Creative Commons Corporation, a not-for-profit
30033 corporation with a principal place of business in San Francisco,
30034 California, as well as future copyleft versions of that license
30035 published by that same organization.
30037 "Incorporate" means to publish or republish a Document, in whole or
30038 in part, as part of another Document.
30040 An MMC is "eligible for relicensing" if it is licensed under this
30041 License, and if all works that were first published under this License
30042 somewhere other than this MMC, and subsequently incorporated in whole
30043 or in part into the MMC, (1) had no cover texts or invariant sections,
30044 and (2) were thus incorporated prior to November 1, 2008.
30046 The operator of an MMC Site may republish an MMC contained in the site
30047 under CC-BY-SA on the same site at any time before August 1, 2009,
30048 provided the MMC is eligible for relicensing.
30050 @strong{ADDENDUM: How to use this License for your documents}
30052 To use this License in a document you have written, include a copy of
30053 the License in the document and put the following copyright and
30054 license notices just after the title page:
30058 Copyright © YEAR YOUR NAME.
30059 Permission is granted to copy, distribute and/or modify this document
30060 under the terms of the GNU Free Documentation License, Version 1.3
30061 or any later version published by the Free Software Foundation;
30062 with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
30063 A copy of the license is included in the section entitled "GNU
30064 Free Documentation License".
30067 If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
30068 replace the "with ... Texts." line with this:
30072 with the Invariant Sections being LIST THEIR TITLES, with the
30073 Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
30076 If you have Invariant Sections without Cover Texts, or some other
30077 combination of the three, merge those two alternatives to suit the
30080 If your document contains nontrivial examples of program code, we
30081 recommend releasing these examples in parallel under your choice of
30082 free software license, such as the GNU General Public License,
30083 to permit their use in free software.
30085 @node Index,,GNU Free Documentation License,Top