1 \input texinfo @c -*-texinfo-*-
5 @c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo
7 @c GNAT DOCUMENTATION o
11 @c GNAT is maintained by Ada Core Technologies Inc (http://www.gnat.com). o
13 @c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo
15 @setfilename gnat_rm.info
18 Copyright @copyright{} 1995-2012, Free Software Foundation, Inc.
20 Permission is granted to copy, distribute and/or modify this document
21 under the terms of the GNU Free Documentation License, Version 1.3 or
22 any later version published by the Free Software Foundation; with no
23 Invariant Sections, with the Front-Cover Texts being ``GNAT Reference
24 Manual'', and with no Back-Cover Texts. A copy of the license is
25 included in the section entitled ``GNU Free Documentation License''.
30 @settitle GNAT Reference Manual
32 @setchapternewpage odd
35 @include gcc-common.texi
37 @dircategory GNU Ada tools
39 * GNAT Reference Manual: (gnat_rm). Reference Manual for GNU Ada tools.
43 @title GNAT Reference Manual
44 @subtitle GNAT, The GNU Ada Development Environment
48 @vskip 0pt plus 1filll
55 @node Top, About This Guide, (dir), (dir)
56 @top GNAT Reference Manual
62 GNAT, The GNU Ada Development Environment@*
63 GCC version @value{version-GCC}@*
70 * Implementation Defined Pragmas::
71 * Implementation Defined Aspects::
72 * Implementation Defined Attributes::
73 * Standard and Implementation Defined Restrictions::
74 * Implementation Advice::
75 * Implementation Defined Characteristics::
76 * Intrinsic Subprograms::
77 * Representation Clauses and Pragmas::
78 * Standard Library Routines::
79 * The Implementation of Standard I/O::
81 * Interfacing to Other Languages::
82 * Specialized Needs Annexes::
83 * Implementation of Specific Ada Features::
84 * Implementation of Ada 2012 Features::
85 * Obsolescent Features::
86 * GNU Free Documentation License::
87 * Index:Concept Index.
90 --- The Detailed Node Listing ---
94 * What This Reference Manual Contains::
95 * Related Information::
97 Implementation Defined Pragmas
99 * Pragma Abort_Defer::
100 * Pragma Abstract_State::
107 * Pragma Allow_Integer_Address::
110 * Pragma Assert_And_Cut::
111 * Pragma Assertion_Policy::
113 * Pragma Assume_No_Invalid_Values::
115 * Pragma Async_Readers::
116 * Pragma Async_Writers::
117 * Pragma Attribute_Definition::
118 * Pragma C_Pass_By_Copy::
120 * Pragma Check_Float_Overflow::
121 * Pragma Check_Name::
122 * Pragma Check_Policy::
123 * Pragma CIL_Constructor::
125 * Pragma Common_Object::
126 * Pragma Compile_Time_Error::
127 * Pragma Compile_Time_Warning::
128 * Pragma Compiler_Unit::
129 * Pragma Compiler_Unit_Warning::
130 * Pragma Complete_Representation::
131 * Pragma Complex_Representation::
132 * Pragma Component_Alignment::
133 * Pragma Contract_Cases::
134 * Pragma Convention_Identifier::
136 * Pragma CPP_Constructor::
137 * Pragma CPP_Virtual::
138 * Pragma CPP_Vtable::
141 * Pragma Debug_Policy::
142 * Pragma Default_Scalar_Storage_Order::
143 * Pragma Default_Storage_Pool::
145 * Pragma Detect_Blocking::
146 * Pragma Disable_Atomic_Synchronization::
147 * Pragma Dispatching_Domain::
148 * Pragma Effective_Reads::
149 * Pragma Effective_Writes::
150 * Pragma Elaboration_Checks::
152 * Pragma Enable_Atomic_Synchronization::
153 * Pragma Export_Exception::
154 * Pragma Export_Function::
155 * Pragma Export_Object::
156 * Pragma Export_Procedure::
157 * Pragma Export_Value::
158 * Pragma Export_Valued_Procedure::
159 * Pragma Extend_System::
160 * Pragma Extensions_Allowed::
162 * Pragma External_Name_Casing::
164 * Pragma Favor_Top_Level::
165 * Pragma Finalize_Storage_Only::
166 * Pragma Float_Representation::
169 * Pragma Implementation_Defined::
170 * Pragma Implemented::
171 * Pragma Implicit_Packing::
172 * Pragma Import_Exception::
173 * Pragma Import_Function::
174 * Pragma Import_Object::
175 * Pragma Import_Procedure::
176 * Pragma Import_Valued_Procedure::
177 * Pragma Independent::
178 * Pragma Independent_Components::
179 * Pragma Initial_Condition::
180 * Pragma Initialize_Scalars::
181 * Pragma Initializes::
182 * Pragma Inline_Always::
183 * Pragma Inline_Generic::
185 * Pragma Interface_Name::
186 * Pragma Interrupt_Handler::
187 * Pragma Interrupt_State::
189 * Pragma Java_Constructor::
190 * Pragma Java_Interface::
191 * Pragma Keep_Names::
194 * Pragma Linker_Alias::
195 * Pragma Linker_Constructor::
196 * Pragma Linker_Destructor::
197 * Pragma Linker_Section::
199 * Pragma Long_Float::
200 * Pragma Loop_Invariant::
201 * Pragma Loop_Optimize::
202 * Pragma Loop_Variant::
203 * Pragma Machine_Attribute::
205 * Pragma Main_Storage::
207 * Pragma No_Elaboration_Code_All::
210 * Pragma No_Run_Time::
211 * Pragma No_Strict_Aliasing ::
212 * Pragma No_Tagged_Streams::
213 * Pragma Normalize_Scalars::
214 * Pragma Obsolescent::
215 * Pragma Optimize_Alignment::
217 * Pragma Overflow_Mode::
218 * Pragma Overriding_Renamings::
219 * Pragma Partition_Elaboration_Policy::
222 * Pragma Persistent_BSS::
225 * Pragma Postcondition::
226 * Pragma Post_Class::
228 * Pragma Precondition::
230 * Pragma Preelaborable_Initialization::
231 * Pragma Prefix_Exception_Messages::
233 * Pragma Priority_Specific_Dispatching::
235 * Pragma Profile_Warnings::
236 * Pragma Propagate_Exceptions::
237 * Pragma Provide_Shift_Operators::
238 * Pragma Psect_Object::
239 * Pragma Pure_Function::
242 * Pragma Refined_Depends::
243 * Pragma Refined_Global::
244 * Pragma Refined_Post::
245 * Pragma Refined_State::
246 * Pragma Relative_Deadline::
247 * Pragma Remote_Access_Type::
248 * Pragma Restricted_Run_Time::
249 * Pragma Restriction_Warnings::
250 * Pragma Reviewable::
251 * Pragma Share_Generic::
253 * Pragma Short_Circuit_And_Or::
254 * Pragma Short_Descriptors::
255 * Pragma Simple_Storage_Pool_Type::
256 * Pragma Source_File_Name::
257 * Pragma Source_File_Name_Project::
258 * Pragma Source_Reference::
259 * Pragma SPARK_Mode::
260 * Pragma Static_Elaboration_Desired::
261 * Pragma Stream_Convert::
262 * Pragma Style_Checks::
265 * Pragma Suppress_All::
266 * Pragma Suppress_Debug_Info::
267 * Pragma Suppress_Exception_Locations::
268 * Pragma Suppress_Initialization::
270 * Pragma Task_Storage::
272 * Pragma Thread_Local_Storage::
273 * Pragma Time_Slice::
275 * Pragma Type_Invariant::
276 * Pragma Type_Invariant_Class::
277 * Pragma Unchecked_Union::
278 * Pragma Unevaluated_Use_Of_Old::
279 * Pragma Unimplemented_Unit::
280 * Pragma Universal_Aliasing ::
281 * Pragma Universal_Data::
282 * Pragma Unmodified::
283 * Pragma Unreferenced::
284 * Pragma Unreferenced_Objects::
285 * Pragma Unreserve_All_Interrupts::
286 * Pragma Unsuppress::
287 * Pragma Use_VADS_Size::
288 * Pragma Validity_Checks::
290 * Pragma Warning_As_Error::
292 * Pragma Weak_External::
293 * Pragma Wide_Character_Encoding::
295 Implementation Defined Aspects
297 * Aspect Abstract_State::
299 * Aspect Async_Readers::
300 * Aspect Async_Writers::
301 * Aspect Contract_Cases::
304 * Aspect Dimension_System::
305 * Aspect Effective_Reads::
306 * Aspect Effective_Writes::
307 * Aspect Favor_Top_Level::
309 * Aspect Initial_Condition::
310 * Aspect Initializes::
311 * Aspect Inline_Always::
313 * Aspect Invariant'Class::
315 * Aspect Linker_Section::
316 * Aspect No_Elaboration_Code_All::
317 * Aspect No_Tagged_Streams::
318 * Aspect Object_Size::
319 * Aspect Obsolescent::
321 * Aspect Persistent_BSS::
323 * Aspect Pure_Function::
324 * Aspect Refined_Depends::
325 * Aspect Refined_Global::
326 * Aspect Refined_Post::
327 * Aspect Refined_State::
328 * Aspect Remote_Access_Type::
329 * Aspect Scalar_Storage_Order::
331 * Aspect Simple_Storage_Pool::
332 * Aspect Simple_Storage_Pool_Type::
333 * Aspect SPARK_Mode::
334 * Aspect Suppress_Debug_Info::
335 * Aspect Suppress_Initialization::
337 * Aspect Thread_Local_Storage::
338 * Aspect Universal_Aliasing::
339 * Aspect Universal_Data::
340 * Aspect Unmodified::
341 * Aspect Unreferenced::
342 * Aspect Unreferenced_Objects::
343 * Aspect Value_Size::
346 Implementation Defined Attributes
348 * Attribute Abort_Signal::
349 * Attribute Address_Size::
350 * Attribute Asm_Input::
351 * Attribute Asm_Output::
352 * Attribute AST_Entry::
353 * Attribute Atomic_Always_Lock_Free::
355 * Attribute Bit_Position::
356 * Attribute Code_Address::
357 * Attribute Compiler_Version::
358 * Attribute Constrained::
359 * Attribute Default_Bit_Order::
360 * Attribute Default_Scalar_Storage_Order::
361 * Attribute Descriptor_Size::
362 * Attribute Elaborated::
363 * Attribute Elab_Body::
364 * Attribute Elab_Spec::
365 * Attribute Elab_Subp_Body::
367 * Attribute Enabled::
368 * Attribute Enum_Rep::
369 * Attribute Enum_Val::
370 * Attribute Epsilon::
371 * Attribute Fast_Math::
372 * Attribute Fixed_Value::
373 * Attribute From_Any::
374 * Attribute Has_Access_Values::
375 * Attribute Has_Discriminants::
377 * Attribute Integer_Value::
378 * Attribute Invalid_Value::
379 * Attribute Iterable::
381 * Attribute Library_Level::
382 * Attribute Lock_Free::
383 * Attribute Loop_Entry::
384 * Attribute Machine_Size::
385 * Attribute Mantissa::
386 * Attribute Maximum_Alignment::
387 * Attribute Mechanism_Code::
388 * Attribute Null_Parameter::
389 * Attribute Object_Size::
391 * Attribute Passed_By_Reference::
392 * Attribute Pool_Address::
393 * Attribute Range_Length::
395 * Attribute Restriction_Set::
397 * Attribute Safe_Emax::
398 * Attribute Safe_Large::
399 * Attribute Safe_Small::
400 * Attribute Scalar_Storage_Order::
401 * Attribute Simple_Storage_Pool::
403 * Attribute Storage_Unit::
404 * Attribute Stub_Type::
405 * Attribute System_Allocator_Alignment::
406 * Attribute Target_Name::
407 * Attribute To_Address::
409 * Attribute Type_Class::
410 * Attribute Type_Key::
411 * Attribute TypeCode::
412 * Attribute UET_Address::
413 * Attribute Unconstrained_Array::
414 * Attribute Universal_Literal_String::
415 * Attribute Unrestricted_Access::
417 * Attribute VADS_Size::
418 * Attribute Valid_Scalars::
419 * Attribute Value_Size::
420 * Attribute Wchar_T_Size::
421 * Attribute Word_Size::
423 Standard and Implementation Defined Restrictions
425 * Partition-Wide Restrictions::
426 * Program Unit Level Restrictions::
428 Partition-Wide Restrictions
430 * Immediate_Reclamation::
431 * Max_Asynchronous_Select_Nesting::
432 * Max_Entry_Queue_Length::
433 * Max_Protected_Entries::
434 * Max_Select_Alternatives::
435 * Max_Storage_At_Blocking::
438 * No_Abort_Statements::
439 * No_Access_Parameter_Allocators::
440 * No_Access_Subprograms::
442 * No_Anonymous_Allocators::
445 * No_Default_Initialization::
448 * No_Direct_Boolean_Operators::
450 * No_Dispatching_Calls::
451 * No_Dynamic_Attachment::
452 * No_Dynamic_Priorities::
453 * No_Entry_Calls_In_Elaboration_Code::
454 * No_Enumeration_Maps::
455 * No_Exception_Handlers::
456 * No_Exception_Propagation::
457 * No_Exception_Registration::
461 * No_Floating_Point::
462 * No_Implicit_Conditionals::
463 * No_Implicit_Dynamic_Code::
464 * No_Implicit_Heap_Allocations::
465 * No_Implicit_Loops::
466 * No_Initialize_Scalars::
468 * No_Local_Allocators::
469 * No_Local_Protected_Objects::
470 * No_Local_Timing_Events::
471 * No_Long_Long_Integers::
472 * No_Multiple_Elaboration::
473 * No_Nested_Finalization::
474 * No_Protected_Type_Allocators::
475 * No_Protected_Types::
478 * No_Relative_Delay::
479 * No_Requeue_Statements::
480 * No_Secondary_Stack::
481 * No_Select_Statements::
482 * No_Specific_Termination_Handlers::
483 * No_Specification_of_Aspect::
484 * No_Standard_Allocators_After_Elaboration::
485 * No_Standard_Storage_Pools::
486 * No_Stream_Optimizations::
488 * No_Task_Allocators::
489 * No_Task_Attributes_Package::
490 * No_Task_Hierarchy::
491 * No_Task_Termination::
493 * No_Terminate_Alternatives::
494 * No_Unchecked_Access::
496 * Static_Priorities::
497 * Static_Storage_Size::
499 Program Unit Level Restrictions
501 * No_Elaboration_Code::
503 * No_Implementation_Aspect_Specifications::
504 * No_Implementation_Attributes::
505 * No_Implementation_Identifiers::
506 * No_Implementation_Pragmas::
507 * No_Implementation_Restrictions::
508 * No_Implementation_Units::
509 * No_Implicit_Aliasing::
510 * No_Obsolescent_Features::
511 * No_Wide_Characters::
514 The Implementation of Standard I/O
516 * Standard I/O Packages::
522 * Wide_Wide_Text_IO::
526 * Filenames encoding::
527 * File content encoding::
529 * Operations on C Streams::
530 * Interfacing to C Streams::
534 * Ada.Characters.Latin_9 (a-chlat9.ads)::
535 * Ada.Characters.Wide_Latin_1 (a-cwila1.ads)::
536 * Ada.Characters.Wide_Latin_9 (a-cwila9.ads)::
537 * Ada.Characters.Wide_Wide_Latin_1 (a-chzla1.ads)::
538 * Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads)::
539 * Ada.Containers.Formal_Doubly_Linked_Lists (a-cfdlli.ads)::
540 * Ada.Containers.Formal_Hashed_Maps (a-cfhama.ads)::
541 * Ada.Containers.Formal_Hashed_Sets (a-cfhase.ads)::
542 * Ada.Containers.Formal_Ordered_Maps (a-cforma.ads)::
543 * Ada.Containers.Formal_Ordered_Sets (a-cforse.ads)::
544 * Ada.Containers.Formal_Vectors (a-cofove.ads)::
545 * Ada.Containers.Formal_Indefinite_Vectors (a-cfinve.ads)::
546 * Ada.Containers.Bounded_Holders (a-coboho.ads)::
547 * Ada.Command_Line.Environment (a-colien.ads)::
548 * Ada.Command_Line.Remove (a-colire.ads)::
549 * Ada.Command_Line.Response_File (a-clrefi.ads)::
550 * Ada.Direct_IO.C_Streams (a-diocst.ads)::
551 * Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads)::
552 * Ada.Exceptions.Last_Chance_Handler (a-elchha.ads)::
553 * Ada.Exceptions.Traceback (a-exctra.ads)::
554 * Ada.Sequential_IO.C_Streams (a-siocst.ads)::
555 * Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads)::
556 * Ada.Strings.Unbounded.Text_IO (a-suteio.ads)::
557 * Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads)::
558 * Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads)::
559 * Ada.Text_IO.C_Streams (a-tiocst.ads)::
560 * Ada.Text_IO.Reset_Standard_Files (a-tirsfi.ads)::
561 * Ada.Wide_Characters.Unicode (a-wichun.ads)::
562 * Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads)::
563 * Ada.Wide_Text_IO.Reset_Standard_Files (a-wrstfi.ads)::
564 * Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads)::
565 * Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads)::
566 * Ada.Wide_Wide_Text_IO.Reset_Standard_Files (a-zrstfi.ads)::
567 * GNAT.Altivec (g-altive.ads)::
568 * GNAT.Altivec.Conversions (g-altcon.ads)::
569 * GNAT.Altivec.Vector_Operations (g-alveop.ads)::
570 * GNAT.Altivec.Vector_Types (g-alvety.ads)::
571 * GNAT.Altivec.Vector_Views (g-alvevi.ads)::
572 * GNAT.Array_Split (g-arrspl.ads)::
573 * GNAT.AWK (g-awk.ads)::
574 * GNAT.Bounded_Buffers (g-boubuf.ads)::
575 * GNAT.Bounded_Mailboxes (g-boumai.ads)::
576 * GNAT.Bubble_Sort (g-bubsor.ads)::
577 * GNAT.Bubble_Sort_A (g-busora.ads)::
578 * GNAT.Bubble_Sort_G (g-busorg.ads)::
579 * GNAT.Byte_Order_Mark (g-byorma.ads)::
580 * GNAT.Byte_Swapping (g-bytswa.ads)::
581 * GNAT.Calendar (g-calend.ads)::
582 * GNAT.Calendar.Time_IO (g-catiio.ads)::
583 * GNAT.Case_Util (g-casuti.ads)::
584 * GNAT.CGI (g-cgi.ads)::
585 * GNAT.CGI.Cookie (g-cgicoo.ads)::
586 * GNAT.CGI.Debug (g-cgideb.ads)::
587 * GNAT.Command_Line (g-comlin.ads)::
588 * GNAT.Compiler_Version (g-comver.ads)::
589 * GNAT.Ctrl_C (g-ctrl_c.ads)::
590 * GNAT.CRC32 (g-crc32.ads)::
591 * GNAT.Current_Exception (g-curexc.ads)::
592 * GNAT.Debug_Pools (g-debpoo.ads)::
593 * GNAT.Debug_Utilities (g-debuti.ads)::
594 * GNAT.Decode_String (g-decstr.ads)::
595 * GNAT.Decode_UTF8_String (g-deutst.ads)::
596 * GNAT.Directory_Operations (g-dirope.ads)::
597 * GNAT.Directory_Operations.Iteration (g-diopit.ads)::
598 * GNAT.Dynamic_HTables (g-dynhta.ads)::
599 * GNAT.Dynamic_Tables (g-dyntab.ads)::
600 * GNAT.Encode_String (g-encstr.ads)::
601 * GNAT.Encode_UTF8_String (g-enutst.ads)::
602 * GNAT.Exception_Actions (g-excact.ads)::
603 * GNAT.Exception_Traces (g-exctra.ads)::
604 * GNAT.Exceptions (g-except.ads)::
605 * GNAT.Expect (g-expect.ads)::
606 * GNAT.Expect.TTY (g-exptty.ads)::
607 * GNAT.Float_Control (g-flocon.ads)::
608 * GNAT.Formatted_String (g-forstr.ads)::
609 * GNAT.Heap_Sort (g-heasor.ads)::
610 * GNAT.Heap_Sort_A (g-hesora.ads)::
611 * GNAT.Heap_Sort_G (g-hesorg.ads)::
612 * GNAT.HTable (g-htable.ads)::
613 * GNAT.IO (g-io.ads)::
614 * GNAT.IO_Aux (g-io_aux.ads)::
615 * GNAT.Lock_Files (g-locfil.ads)::
616 * GNAT.MBBS_Discrete_Random (g-mbdira.ads)::
617 * GNAT.MBBS_Float_Random (g-mbflra.ads)::
618 * GNAT.MD5 (g-md5.ads)::
619 * GNAT.Memory_Dump (g-memdum.ads)::
620 * GNAT.Most_Recent_Exception (g-moreex.ads)::
621 * GNAT.OS_Lib (g-os_lib.ads)::
622 * GNAT.Perfect_Hash_Generators (g-pehage.ads)::
623 * GNAT.Random_Numbers (g-rannum.ads)::
624 * GNAT.Regexp (g-regexp.ads)::
625 * GNAT.Registry (g-regist.ads)::
626 * GNAT.Regpat (g-regpat.ads)::
627 * GNAT.Rewrite_Data (g-rewdat.ads)::
628 * GNAT.Secondary_Stack_Info (g-sestin.ads)::
629 * GNAT.Semaphores (g-semaph.ads)::
630 * GNAT.Serial_Communications (g-sercom.ads)::
631 * GNAT.SHA1 (g-sha1.ads)::
632 * GNAT.SHA224 (g-sha224.ads)::
633 * GNAT.SHA256 (g-sha256.ads)::
634 * GNAT.SHA384 (g-sha384.ads)::
635 * GNAT.SHA512 (g-sha512.ads)::
636 * GNAT.Signals (g-signal.ads)::
637 * GNAT.Sockets (g-socket.ads)::
638 * GNAT.Source_Info (g-souinf.ads)::
639 * GNAT.Spelling_Checker (g-speche.ads)::
640 * GNAT.Spelling_Checker_Generic (g-spchge.ads)::
641 * GNAT.Spitbol.Patterns (g-spipat.ads)::
642 * GNAT.Spitbol (g-spitbo.ads)::
643 * GNAT.Spitbol.Table_Boolean (g-sptabo.ads)::
644 * GNAT.Spitbol.Table_Integer (g-sptain.ads)::
645 * GNAT.Spitbol.Table_VString (g-sptavs.ads)::
646 * GNAT.SSE (g-sse.ads)::
647 * GNAT.SSE.Vector_Types (g-ssvety.ads)::
648 * GNAT.Strings (g-string.ads)::
649 * GNAT.String_Split (g-strspl.ads)::
650 * GNAT.Table (g-table.ads)::
651 * GNAT.Task_Lock (g-tasloc.ads)::
652 * GNAT.Threads (g-thread.ads)::
653 * GNAT.Time_Stamp (g-timsta.ads)::
654 * GNAT.Traceback (g-traceb.ads)::
655 * GNAT.Traceback.Symbolic (g-trasym.ads)::
656 * GNAT.UTF_32 (g-utf_32.ads)::
657 * GNAT.UTF_32_Spelling_Checker (g-u3spch.ads)::
658 * GNAT.Wide_Spelling_Checker (g-wispch.ads)::
659 * GNAT.Wide_String_Split (g-wistsp.ads)::
660 * GNAT.Wide_Wide_Spelling_Checker (g-zspche.ads)::
661 * GNAT.Wide_Wide_String_Split (g-zistsp.ads)::
662 * Interfaces.C.Extensions (i-cexten.ads)::
663 * Interfaces.C.Streams (i-cstrea.ads)::
664 * Interfaces.Packed_Decimal (i-pacdec.ads)::
665 * Interfaces.VxWorks (i-vxwork.ads)::
666 * Interfaces.VxWorks.IO (i-vxwoio.ads)::
667 * System.Address_Image (s-addima.ads)::
668 * System.Assertions (s-assert.ads)::
669 * System.Atomic_Counters (s-atocou.ads)::
670 * System.Memory (s-memory.ads)::
671 * System.Multiprocessors (s-multip.ads)::
672 * System.Multiprocessors.Dispatching_Domains (s-mudido.ads)::
673 * System.Partition_Interface (s-parint.ads)::
674 * System.Pool_Global (s-pooglo.ads)::
675 * System.Pool_Local (s-pooloc.ads)::
676 * System.Restrictions (s-restri.ads)::
677 * System.Rident (s-rident.ads)::
678 * System.Strings.Stream_Ops (s-ststop.ads)::
679 * System.Unsigned_Types (s-unstyp.ads)::
680 * System.Wch_Cnv (s-wchcnv.ads)::
681 * System.Wch_Con (s-wchcon.ads)::
685 * Text_IO Stream Pointer Positioning::
686 * Text_IO Reading and Writing Non-Regular Files::
688 * Treating Text_IO Files as Streams::
689 * Text_IO Extensions::
690 * Text_IO Facilities for Unbounded Strings::
694 * Wide_Text_IO Stream Pointer Positioning::
695 * Wide_Text_IO Reading and Writing Non-Regular Files::
699 * Wide_Wide_Text_IO Stream Pointer Positioning::
700 * Wide_Wide_Text_IO Reading and Writing Non-Regular Files::
702 Interfacing to Other Languages
705 * Interfacing to C++::
706 * Interfacing to COBOL::
707 * Interfacing to Fortran::
708 * Interfacing to non-GNAT Ada code::
710 Specialized Needs Annexes
712 Implementation of Specific Ada Features
713 * Machine Code Insertions::
714 * GNAT Implementation of Tasking::
715 * GNAT Implementation of Shared Passive Packages::
716 * Code Generation for Array Aggregates::
717 * The Size of Discriminated Records with Default Discriminants::
718 * Strict Conformance to the Ada Reference Manual::
720 Implementation of Ada 2012 Features
724 GNU Free Documentation License
732 @node About This Guide
733 @unnumbered About This Guide
736 This manual contains useful information in writing programs using the
737 @value{EDITION} compiler. It includes information on implementation dependent
738 characteristics of @value{EDITION}, including all the information required by
739 Annex M of the Ada language standard.
741 @value{EDITION} implements Ada 95, Ada 2005 and Ada 2012, and it may also be
742 invoked in Ada 83 compatibility mode.
743 By default, @value{EDITION} assumes Ada 2012,
744 but you can override with a compiler switch
745 to explicitly specify the language version.
746 (Please refer to @ref{Compiling Different Versions of Ada,,, gnat_ugn,
747 @value{EDITION} User's Guide}, for details on these switches.)
748 Throughout this manual, references to ``Ada'' without a year suffix
749 apply to all the Ada versions of the language.
751 Ada is designed to be highly portable.
752 In general, a program will have the same effect even when compiled by
753 different compilers on different platforms.
754 However, since Ada is designed to be used in a
755 wide variety of applications, it also contains a number of system
756 dependent features to be used in interfacing to the external world.
757 @cindex Implementation-dependent features
760 Note: Any program that makes use of implementation-dependent features
761 may be non-portable. You should follow good programming practice and
762 isolate and clearly document any sections of your program that make use
763 of these features in a non-portable manner.
766 For ease of exposition, ``@value{EDITION}'' will be referred to simply as
767 ``GNAT'' in the remainder of this document.
771 * What This Reference Manual Contains::
773 * Related Information::
776 @node What This Reference Manual Contains
777 @unnumberedsec What This Reference Manual Contains
780 This reference manual contains the following chapters:
784 @ref{Implementation Defined Pragmas}, lists GNAT implementation-dependent
785 pragmas, which can be used to extend and enhance the functionality of the
789 @ref{Implementation Defined Attributes}, lists GNAT
790 implementation-dependent attributes, which can be used to extend and
791 enhance the functionality of the compiler.
794 @ref{Standard and Implementation Defined Restrictions}, lists GNAT
795 implementation-dependent restrictions, which can be used to extend and
796 enhance the functionality of the compiler.
799 @ref{Implementation Advice}, provides information on generally
800 desirable behavior which are not requirements that all compilers must
801 follow since it cannot be provided on all systems, or which may be
802 undesirable on some systems.
805 @ref{Implementation Defined Characteristics}, provides a guide to
806 minimizing implementation dependent features.
809 @ref{Intrinsic Subprograms}, describes the intrinsic subprograms
810 implemented by GNAT, and how they can be imported into user
811 application programs.
814 @ref{Representation Clauses and Pragmas}, describes in detail the
815 way that GNAT represents data, and in particular the exact set
816 of representation clauses and pragmas that is accepted.
819 @ref{Standard Library Routines}, provides a listing of packages and a
820 brief description of the functionality that is provided by Ada's
821 extensive set of standard library routines as implemented by GNAT@.
824 @ref{The Implementation of Standard I/O}, details how the GNAT
825 implementation of the input-output facilities.
828 @ref{The GNAT Library}, is a catalog of packages that complement
829 the Ada predefined library.
832 @ref{Interfacing to Other Languages}, describes how programs
833 written in Ada using GNAT can be interfaced to other programming
836 @ref{Specialized Needs Annexes}, describes the GNAT implementation of all
837 of the specialized needs annexes.
840 @ref{Implementation of Specific Ada Features}, discusses issues related
841 to GNAT's implementation of machine code insertions, tasking, and several
845 @ref{Implementation of Ada 2012 Features}, describes the status of the
846 GNAT implementation of the Ada 2012 language standard.
849 @ref{Obsolescent Features} documents implementation dependent features,
850 including pragmas and attributes, which are considered obsolescent, since
851 there are other preferred ways of achieving the same results. These
852 obsolescent forms are retained for backwards compatibility.
856 @cindex Ada 95 Language Reference Manual
857 @cindex Ada 2005 Language Reference Manual
859 This reference manual assumes a basic familiarity with the Ada 95 language, as
860 described in the International Standard ANSI/ISO/IEC-8652:1995,
862 It does not require knowledge of the new features introduced by Ada 2005,
863 (officially known as ISO/IEC 8652:1995 with Technical Corrigendum 1
865 Both reference manuals are included in the GNAT documentation
869 @unnumberedsec Conventions
870 @cindex Conventions, typographical
871 @cindex Typographical conventions
874 Following are examples of the typographical and graphic conventions used
879 @code{Functions}, @code{utility program names}, @code{standard names},
886 @file{File names}, @samp{button names}, and @samp{field names}.
889 @code{Variables}, @env{environment variables}, and @var{metasyntactic
896 [optional information or parameters]
899 Examples are described by text
901 and then shown this way.
906 Commands that are entered by the user are preceded in this manual by the
907 characters @samp{$ } (dollar sign followed by space). If your system uses this
908 sequence as a prompt, then the commands will appear exactly as you see them
909 in the manual. If your system uses some other prompt, then the command will
910 appear with the @samp{$} replaced by whatever prompt character you are using.
912 @node Related Information
913 @unnumberedsec Related Information
915 See the following documents for further information on GNAT:
919 @xref{Top, @value{EDITION} User's Guide, About This Guide, gnat_ugn,
920 @value{EDITION} User's Guide}, which provides information on how to use the
921 GNAT compiler system.
924 @cite{Ada 95 Reference Manual}, which contains all reference
925 material for the Ada 95 programming language.
928 @cite{Ada 95 Annotated Reference Manual}, which is an annotated version
929 of the Ada 95 standard. The annotations describe
930 detailed aspects of the design decision, and in particular contain useful
931 sections on Ada 83 compatibility.
934 @cite{Ada 2005 Reference Manual}, which contains all reference
935 material for the Ada 2005 programming language.
938 @cite{Ada 2005 Annotated Reference Manual}, which is an annotated version
939 of the Ada 2005 standard. The annotations describe
940 detailed aspects of the design decision, and in particular contain useful
941 sections on Ada 83 and Ada 95 compatibility.
944 @cite{DEC Ada, Technical Overview and Comparison on DIGITAL Platforms},
945 which contains specific information on compatibility between GNAT and
949 @cite{DEC Ada, Language Reference Manual, part number AA-PYZAB-TK} which
950 describes in detail the pragmas and attributes provided by the DEC Ada 83
955 @node Implementation Defined Pragmas
956 @chapter Implementation Defined Pragmas
959 Ada defines a set of pragmas that can be used to supply additional
960 information to the compiler. These language defined pragmas are
961 implemented in GNAT and work as described in the Ada Reference Manual.
963 In addition, Ada allows implementations to define additional pragmas
964 whose meaning is defined by the implementation. GNAT provides a number
965 of these implementation-defined pragmas, which can be used to extend
966 and enhance the functionality of the compiler. This section of the GNAT
967 Reference Manual describes these additional pragmas.
969 Note that any program using these pragmas might not be portable to other
970 compilers (although GNAT implements this set of pragmas on all
971 platforms). Therefore if portability to other compilers is an important
972 consideration, the use of these pragmas should be minimized.
975 * Pragma Abort_Defer::
976 * Pragma Abstract_State::
983 * Pragma Allow_Integer_Address::
986 * Pragma Assert_And_Cut::
987 * Pragma Assertion_Policy::
989 * Pragma Assume_No_Invalid_Values::
991 * Pragma Async_Readers::
992 * Pragma Async_Writers::
993 * Pragma Attribute_Definition::
994 * Pragma C_Pass_By_Copy::
996 * Pragma Check_Float_Overflow::
997 * Pragma Check_Name::
998 * Pragma Check_Policy::
999 * Pragma CIL_Constructor::
1001 * Pragma Common_Object::
1002 * Pragma Compile_Time_Error::
1003 * Pragma Compile_Time_Warning::
1004 * Pragma Compiler_Unit::
1005 * Pragma Compiler_Unit_Warning::
1006 * Pragma Complete_Representation::
1007 * Pragma Complex_Representation::
1008 * Pragma Component_Alignment::
1009 * Pragma Contract_Cases::
1010 * Pragma Convention_Identifier::
1011 * Pragma CPP_Class::
1012 * Pragma CPP_Constructor::
1013 * Pragma CPP_Virtual::
1014 * Pragma CPP_Vtable::
1017 * Pragma Debug_Policy::
1018 * Pragma Default_Scalar_Storage_Order::
1019 * Pragma Default_Storage_Pool::
1021 * Pragma Detect_Blocking::
1022 * Pragma Disable_Atomic_Synchronization::
1023 * Pragma Dispatching_Domain::
1024 * Pragma Effective_Reads::
1025 * Pragma Effective_Writes::
1026 * Pragma Elaboration_Checks::
1027 * Pragma Eliminate::
1028 * Pragma Enable_Atomic_Synchronization::
1029 * Pragma Export_Exception::
1030 * Pragma Export_Function::
1031 * Pragma Export_Object::
1032 * Pragma Export_Procedure::
1033 * Pragma Export_Value::
1034 * Pragma Export_Valued_Procedure::
1035 * Pragma Extend_System::
1036 * Pragma Extensions_Allowed::
1038 * Pragma External_Name_Casing::
1039 * Pragma Fast_Math::
1040 * Pragma Favor_Top_Level::
1041 * Pragma Finalize_Storage_Only::
1042 * Pragma Float_Representation::
1045 * Pragma Implementation_Defined::
1046 * Pragma Implemented::
1047 * Pragma Implicit_Packing::
1048 * Pragma Import_Exception::
1049 * Pragma Import_Function::
1050 * Pragma Import_Object::
1051 * Pragma Import_Procedure::
1052 * Pragma Import_Valued_Procedure::
1053 * Pragma Independent::
1054 * Pragma Independent_Components::
1055 * Pragma Initial_Condition::
1056 * Pragma Initialize_Scalars::
1057 * Pragma Initializes::
1058 * Pragma Inline_Always::
1059 * Pragma Inline_Generic::
1060 * Pragma Interface::
1061 * Pragma Interface_Name::
1062 * Pragma Interrupt_Handler::
1063 * Pragma Interrupt_State::
1064 * Pragma Invariant::
1065 * Pragma Java_Constructor::
1066 * Pragma Java_Interface::
1067 * Pragma Keep_Names::
1069 * Pragma Link_With::
1070 * Pragma Linker_Alias::
1071 * Pragma Linker_Constructor::
1072 * Pragma Linker_Destructor::
1073 * Pragma Linker_Section::
1074 * Pragma Lock_Free::
1075 * Pragma Long_Float::
1076 * Pragma Loop_Invariant::
1077 * Pragma Loop_Optimize::
1078 * Pragma Loop_Variant::
1079 * Pragma Machine_Attribute::
1081 * Pragma Main_Storage::
1083 * Pragma No_Elaboration_Code_All::
1084 * Pragma No_Inline::
1085 * Pragma No_Return::
1086 * Pragma No_Run_Time::
1087 * Pragma No_Strict_Aliasing::
1088 * Pragma No_Tagged_Streams::
1089 * Pragma Normalize_Scalars::
1090 * Pragma Obsolescent::
1091 * Pragma Optimize_Alignment::
1093 * Pragma Overflow_Mode::
1094 * Pragma Overriding_Renamings::
1095 * Pragma Partition_Elaboration_Policy::
1098 * Pragma Persistent_BSS::
1101 * Pragma Postcondition::
1102 * Pragma Post_Class::
1104 * Pragma Precondition::
1105 * Pragma Predicate::
1106 * Pragma Preelaborable_Initialization::
1107 * Pragma Prefix_Exception_Messages::
1108 * Pragma Pre_Class::
1109 * Pragma Priority_Specific_Dispatching::
1111 * Pragma Profile_Warnings::
1112 * Pragma Propagate_Exceptions::
1113 * Pragma Provide_Shift_Operators::
1114 * Pragma Psect_Object::
1115 * Pragma Pure_Function::
1117 * Pragma Ravenscar::
1118 * Pragma Refined_Depends::
1119 * Pragma Refined_Global::
1120 * Pragma Refined_Post::
1121 * Pragma Refined_State::
1122 * Pragma Relative_Deadline::
1123 * Pragma Remote_Access_Type::
1124 * Pragma Restricted_Run_Time::
1125 * Pragma Restriction_Warnings::
1126 * Pragma Reviewable::
1127 * Pragma Share_Generic::
1129 * Pragma Short_Circuit_And_Or::
1130 * Pragma Short_Descriptors::
1131 * Pragma Simple_Storage_Pool_Type::
1132 * Pragma Source_File_Name::
1133 * Pragma Source_File_Name_Project::
1134 * Pragma Source_Reference::
1135 * Pragma SPARK_Mode::
1136 * Pragma Static_Elaboration_Desired::
1137 * Pragma Stream_Convert::
1138 * Pragma Style_Checks::
1141 * Pragma Suppress_All::
1142 * Pragma Suppress_Debug_Info::
1143 * Pragma Suppress_Exception_Locations::
1144 * Pragma Suppress_Initialization::
1145 * Pragma Task_Name::
1146 * Pragma Task_Storage::
1147 * Pragma Test_Case::
1148 * Pragma Thread_Local_Storage::
1149 * Pragma Time_Slice::
1151 * Pragma Type_Invariant::
1152 * Pragma Type_Invariant_Class::
1153 * Pragma Unchecked_Union::
1154 * Pragma Unevaluated_Use_Of_Old::
1155 * Pragma Unimplemented_Unit::
1156 * Pragma Universal_Aliasing ::
1157 * Pragma Universal_Data::
1158 * Pragma Unmodified::
1159 * Pragma Unreferenced::
1160 * Pragma Unreferenced_Objects::
1161 * Pragma Unreserve_All_Interrupts::
1162 * Pragma Unsuppress::
1163 * Pragma Use_VADS_Size::
1164 * Pragma Validity_Checks::
1166 * Pragma Warning_As_Error::
1168 * Pragma Weak_External::
1169 * Pragma Wide_Character_Encoding::
1172 @node Pragma Abort_Defer
1173 @unnumberedsec Pragma Abort_Defer
1175 @cindex Deferring aborts
1183 This pragma must appear at the start of the statement sequence of a
1184 handled sequence of statements (right after the @code{begin}). It has
1185 the effect of deferring aborts for the sequence of statements (but not
1186 for the declarations or handlers, if any, associated with this statement
1189 @node Pragma Abstract_State
1190 @unnumberedsec Pragma Abstract_State
1191 @findex Abstract_State
1193 For the description of this pragma, see SPARK 2014 Reference Manual,
1197 @unnumberedsec Pragma Ada_83
1201 @smallexample @c ada
1206 A configuration pragma that establishes Ada 83 mode for the unit to
1207 which it applies, regardless of the mode set by the command line
1208 switches. In Ada 83 mode, GNAT attempts to be as compatible with
1209 the syntax and semantics of Ada 83, as defined in the original Ada
1210 83 Reference Manual as possible. In particular, the keywords added by Ada 95
1211 and Ada 2005 are not recognized, optional package bodies are allowed,
1212 and generics may name types with unknown discriminants without using
1213 the @code{(<>)} notation. In addition, some but not all of the additional
1214 restrictions of Ada 83 are enforced.
1216 Ada 83 mode is intended for two purposes. Firstly, it allows existing
1217 Ada 83 code to be compiled and adapted to GNAT with less effort.
1218 Secondly, it aids in keeping code backwards compatible with Ada 83.
1219 However, there is no guarantee that code that is processed correctly
1220 by GNAT in Ada 83 mode will in fact compile and execute with an Ada
1221 83 compiler, since GNAT does not enforce all the additional checks
1225 @unnumberedsec Pragma Ada_95
1229 @smallexample @c ada
1234 A configuration pragma that establishes Ada 95 mode for the unit to which
1235 it applies, regardless of the mode set by the command line switches.
1236 This mode is set automatically for the @code{Ada} and @code{System}
1237 packages and their children, so you need not specify it in these
1238 contexts. This pragma is useful when writing a reusable component that
1239 itself uses Ada 95 features, but which is intended to be usable from
1240 either Ada 83 or Ada 95 programs.
1243 @unnumberedsec Pragma Ada_05
1247 @smallexample @c ada
1249 pragma Ada_05 (local_NAME);
1253 A configuration pragma that establishes Ada 2005 mode for the unit to which
1254 it applies, regardless of the mode set by the command line switches.
1255 This pragma is useful when writing a reusable component that
1256 itself uses Ada 2005 features, but which is intended to be usable from
1257 either Ada 83 or Ada 95 programs.
1259 The one argument form (which is not a configuration pragma)
1260 is used for managing the transition from
1261 Ada 95 to Ada 2005 in the run-time library. If an entity is marked
1262 as Ada_2005 only, then referencing the entity in Ada_83 or Ada_95
1263 mode will generate a warning. In addition, in Ada_83 or Ada_95
1264 mode, a preference rule is established which does not choose
1265 such an entity unless it is unambiguously specified. This avoids
1266 extra subprograms marked this way from generating ambiguities in
1267 otherwise legal pre-Ada_2005 programs. The one argument form is
1268 intended for exclusive use in the GNAT run-time library.
1270 @node Pragma Ada_2005
1271 @unnumberedsec Pragma Ada_2005
1275 @smallexample @c ada
1280 This configuration pragma is a synonym for pragma Ada_05 and has the
1281 same syntax and effect.
1284 @unnumberedsec Pragma Ada_12
1288 @smallexample @c ada
1290 pragma Ada_12 (local_NAME);
1294 A configuration pragma that establishes Ada 2012 mode for the unit to which
1295 it applies, regardless of the mode set by the command line switches.
1296 This mode is set automatically for the @code{Ada} and @code{System}
1297 packages and their children, so you need not specify it in these
1298 contexts. This pragma is useful when writing a reusable component that
1299 itself uses Ada 2012 features, but which is intended to be usable from
1300 Ada 83, Ada 95, or Ada 2005 programs.
1302 The one argument form, which is not a configuration pragma,
1303 is used for managing the transition from Ada
1304 2005 to Ada 2012 in the run-time library. If an entity is marked
1305 as Ada_201 only, then referencing the entity in any pre-Ada_2012
1306 mode will generate a warning. In addition, in any pre-Ada_2012
1307 mode, a preference rule is established which does not choose
1308 such an entity unless it is unambiguously specified. This avoids
1309 extra subprograms marked this way from generating ambiguities in
1310 otherwise legal pre-Ada_2012 programs. The one argument form is
1311 intended for exclusive use in the GNAT run-time library.
1313 @node Pragma Ada_2012
1314 @unnumberedsec Pragma Ada_2012
1318 @smallexample @c ada
1323 This configuration pragma is a synonym for pragma Ada_12 and has the
1324 same syntax and effect.
1326 @node Pragma Allow_Integer_Address
1327 @unnumberedsec Pragma Allow_Integer_Address
1328 @findex Allow_Integer_Address
1331 @smallexample @c ada
1332 pragma Allow_Integer_Address;
1336 In almost all versions of GNAT, @code{System.Address} is a private
1337 type in accordance with the implementation advice in the RM. This
1338 means that integer values,
1339 in particular integer literals, are not allowed as address values.
1340 If the configuration pragma
1341 @code{Allow_Integer_Address} is given, then integer expressions may
1342 be used anywhere a value of type @code{System.Address} is required.
1343 The effect is to introduce an implicit unchecked conversion from the
1344 integer value to type @code{System.Address}. The reverse case of using
1345 an address where an integer type is required is handled analogously.
1346 The following example compiles without errors:
1348 @smallexample @c ada
1349 pragma Allow_Integer_Address;
1350 with System; use System;
1351 package AddrAsInt is
1354 for X'Address use 16#1240#;
1355 for Y use at 16#3230#;
1356 m : Address := 16#4000#;
1357 n : constant Address := 4000;
1358 p : constant Address := Address (X + Y);
1359 v : Integer := y'Address;
1360 w : constant Integer := Integer (Y'Address);
1361 type R is new integer;
1364 for Z'Address use RR;
1369 Note that pragma @code{Allow_Integer_Address} is ignored if
1370 @code{System.Address}
1371 is not a private type. In implementations of @code{GNAT} where
1372 System.Address is a visible integer type (notably the implementations
1373 for @code{OpenVMS}), this pragma serves no purpose but is ignored
1374 rather than rejected to allow common sets of sources to be used
1375 in the two situations.
1377 @node Pragma Annotate
1378 @unnumberedsec Pragma Annotate
1382 @smallexample @c ada
1383 pragma Annotate (IDENTIFIER [, IDENTIFIER @{, ARG@}] [, entity => local_NAME]);
1385 ARG ::= NAME | EXPRESSION
1389 This pragma is used to annotate programs. @var{identifier} identifies
1390 the type of annotation. GNAT verifies that it is an identifier, but does
1391 not otherwise analyze it. The second optional identifier is also left
1392 unanalyzed, and by convention is used to control the action of the tool to
1393 which the annotation is addressed. The remaining @var{arg} arguments
1394 can be either string literals or more generally expressions.
1395 String literals are assumed to be either of type
1396 @code{Standard.String} or else @code{Wide_String} or @code{Wide_Wide_String}
1397 depending on the character literals they contain.
1398 All other kinds of arguments are analyzed as expressions, and must be
1399 unambiguous. The last argument if present must have the identifier
1400 @code{Entity} and GNAT verifies that a local name is given.
1402 The analyzed pragma is retained in the tree, but not otherwise processed
1403 by any part of the GNAT compiler, except to generate corresponding note
1404 lines in the generated ALI file. For the format of these note lines, see
1405 the compiler source file lib-writ.ads. This pragma is intended for use by
1406 external tools, including ASIS@. The use of pragma Annotate does not
1407 affect the compilation process in any way. This pragma may be used as
1408 a configuration pragma.
1411 @unnumberedsec Pragma Assert
1415 @smallexample @c ada
1418 [, string_EXPRESSION]);
1422 The effect of this pragma depends on whether the corresponding command
1423 line switch is set to activate assertions. The pragma expands into code
1424 equivalent to the following:
1426 @smallexample @c ada
1427 if assertions-enabled then
1428 if not boolean_EXPRESSION then
1429 System.Assertions.Raise_Assert_Failure
1430 (string_EXPRESSION);
1436 The string argument, if given, is the message that will be associated
1437 with the exception occurrence if the exception is raised. If no second
1438 argument is given, the default message is @samp{@var{file}:@var{nnn}},
1439 where @var{file} is the name of the source file containing the assert,
1440 and @var{nnn} is the line number of the assert. A pragma is not a
1441 statement, so if a statement sequence contains nothing but a pragma
1442 assert, then a null statement is required in addition, as in:
1444 @smallexample @c ada
1447 pragma Assert (K > 3, "Bad value for K");
1453 Note that, as with the @code{if} statement to which it is equivalent, the
1454 type of the expression is either @code{Standard.Boolean}, or any type derived
1455 from this standard type.
1457 Assert checks can be either checked or ignored. By default they are ignored.
1458 They will be checked if either the command line switch @option{-gnata} is
1459 used, or if an @code{Assertion_Policy} or @code{Check_Policy} pragma is used
1460 to enable @code{Assert_Checks}.
1462 If assertions are ignored, then there
1463 is no run-time effect (and in particular, any side effects from the
1464 expression will not occur at run time). (The expression is still
1465 analyzed at compile time, and may cause types to be frozen if they are
1466 mentioned here for the first time).
1468 If assertions are checked, then the given expression is tested, and if
1469 it is @code{False} then @code{System.Assertions.Raise_Assert_Failure} is called
1470 which results in the raising of @code{Assert_Failure} with the given message.
1472 You should generally avoid side effects in the expression arguments of
1473 this pragma, because these side effects will turn on and off with the
1474 setting of the assertions mode, resulting in assertions that have an
1475 effect on the program. However, the expressions are analyzed for
1476 semantic correctness whether or not assertions are enabled, so turning
1477 assertions on and off cannot affect the legality of a program.
1479 Note that the implementation defined policy @code{DISABLE}, given in a
1480 pragma @code{Assertion_Policy}, can be used to suppress this semantic analysis.
1482 Note: this is a standard language-defined pragma in versions
1483 of Ada from 2005 on. In GNAT, it is implemented in all versions
1484 of Ada, and the DISABLE policy is an implementation-defined
1487 @node Pragma Assert_And_Cut
1488 @unnumberedsec Pragma Assert_And_Cut
1489 @findex Assert_And_Cut
1492 @smallexample @c ada
1493 pragma Assert_And_Cut (
1495 [, string_EXPRESSION]);
1499 The effect of this pragma is identical to that of pragma @code{Assert},
1500 except that in an @code{Assertion_Policy} pragma, the identifier
1501 @code{Assert_And_Cut} is used to control whether it is ignored or checked
1504 The intention is that this be used within a subprogram when the
1505 given test expresion sums up all the work done so far in the
1506 subprogram, so that the rest of the subprogram can be verified
1507 (informally or formally) using only the entry preconditions,
1508 and the expression in this pragma. This allows dividing up
1509 a subprogram into sections for the purposes of testing or
1510 formal verification. The pragma also serves as useful
1513 @node Pragma Assertion_Policy
1514 @unnumberedsec Pragma Assertion_Policy
1515 @findex Assertion_Policy
1518 @smallexample @c ada
1519 pragma Assertion_Policy (CHECK | DISABLE | IGNORE);
1521 pragma Assertion_Policy (
1522 ASSERTION_KIND => POLICY_IDENTIFIER
1523 @{, ASSERTION_KIND => POLICY_IDENTIFIER@});
1525 ASSERTION_KIND ::= RM_ASSERTION_KIND | ID_ASSERTION_KIND
1527 RM_ASSERTION_KIND ::= Assert |
1535 Type_Invariant'Class
1537 ID_ASSERTION_KIND ::= Assertions |
1550 Statement_Assertions
1552 POLICY_IDENTIFIER ::= Check | Disable | Ignore
1556 This is a standard Ada 2012 pragma that is available as an
1557 implementation-defined pragma in earlier versions of Ada.
1558 The assertion kinds @code{RM_ASSERTION_KIND} are those defined in
1559 the Ada standard. The assertion kinds @code{ID_ASSERTION_KIND}
1560 are implementation defined additions recognized by the GNAT compiler.
1562 The pragma applies in both cases to pragmas and aspects with matching
1563 names, e.g. @code{Pre} applies to the Pre aspect, and @code{Precondition}
1564 applies to both the @code{Precondition} pragma
1565 and the aspect @code{Precondition}. Note that the identifiers for
1566 pragmas Pre_Class and Post_Class are Pre'Class and Post'Class (not
1567 Pre_Class and Post_Class), since these pragmas are intended to be
1568 identical to the corresponding aspects).
1570 If the policy is @code{CHECK}, then assertions are enabled, i.e.
1571 the corresponding pragma or aspect is activated.
1572 If the policy is @code{IGNORE}, then assertions are ignored, i.e.
1573 the corresponding pragma or aspect is deactivated.
1574 This pragma overrides the effect of the @option{-gnata} switch on the
1577 The implementation defined policy @code{DISABLE} is like
1578 @code{IGNORE} except that it completely disables semantic
1579 checking of the corresponding pragma or aspect. This is
1580 useful when the pragma or aspect argument references subprograms
1581 in a with'ed package which is replaced by a dummy package
1582 for the final build.
1584 The implementation defined assertion kind @code{Assertions} applies to all
1585 assertion kinds. The form with no assertion kind given implies this
1586 choice, so it applies to all assertion kinds (RM defined, and
1587 implementation defined).
1589 The implementation defined assertion kind @code{Statement_Assertions}
1590 applies to @code{Assert}, @code{Assert_And_Cut},
1591 @code{Assume}, @code{Loop_Invariant}, and @code{Loop_Variant}.
1594 @unnumberedsec Pragma Assume
1598 @smallexample @c ada
1601 [, string_EXPRESSION]);
1605 The effect of this pragma is identical to that of pragma @code{Assert},
1606 except that in an @code{Assertion_Policy} pragma, the identifier
1607 @code{Assume} is used to control whether it is ignored or checked
1610 The intention is that this be used for assumptions about the
1611 external environment. So you cannot expect to verify formally
1612 or informally that the condition is met, this must be
1613 established by examining things outside the program itself.
1614 For example, we may have code that depends on the size of
1615 @code{Long_Long_Integer} being at least 64. So we could write:
1617 @smallexample @c ada
1618 pragma Assume (Long_Long_Integer'Size >= 64);
1622 This assumption cannot be proved from the program itself,
1623 but it acts as a useful run-time check that the assumption
1624 is met, and documents the need to ensure that it is met by
1625 reference to information outside the program.
1627 @node Pragma Assume_No_Invalid_Values
1628 @unnumberedsec Pragma Assume_No_Invalid_Values
1629 @findex Assume_No_Invalid_Values
1630 @cindex Invalid representations
1631 @cindex Invalid values
1634 @smallexample @c ada
1635 pragma Assume_No_Invalid_Values (On | Off);
1639 This is a configuration pragma that controls the assumptions made by the
1640 compiler about the occurrence of invalid representations (invalid values)
1643 The default behavior (corresponding to an Off argument for this pragma), is
1644 to assume that values may in general be invalid unless the compiler can
1645 prove they are valid. Consider the following example:
1647 @smallexample @c ada
1648 V1 : Integer range 1 .. 10;
1649 V2 : Integer range 11 .. 20;
1651 for J in V2 .. V1 loop
1657 if V1 and V2 have valid values, then the loop is known at compile
1658 time not to execute since the lower bound must be greater than the
1659 upper bound. However in default mode, no such assumption is made,
1660 and the loop may execute. If @code{Assume_No_Invalid_Values (On)}
1661 is given, the compiler will assume that any occurrence of a variable
1662 other than in an explicit @code{'Valid} test always has a valid
1663 value, and the loop above will be optimized away.
1665 The use of @code{Assume_No_Invalid_Values (On)} is appropriate if
1666 you know your code is free of uninitialized variables and other
1667 possible sources of invalid representations, and may result in
1668 more efficient code. A program that accesses an invalid representation
1669 with this pragma in effect is erroneous, so no guarantees can be made
1672 It is peculiar though permissible to use this pragma in conjunction
1673 with validity checking (-gnatVa). In such cases, accessing invalid
1674 values will generally give an exception, though formally the program
1675 is erroneous so there are no guarantees that this will always be the
1676 case, and it is recommended that these two options not be used together.
1678 @node Pragma Async_Readers
1679 @unnumberedsec Pragma Async_Readers
1680 @findex Async_Readers
1682 For the description of this pragma, see SPARK 2014 Reference Manual,
1685 @node Pragma Async_Writers
1686 @unnumberedsec Pragma Async_Writers
1687 @findex Async_Writers
1689 For the description of this pragma, see SPARK 2014 Reference Manual,
1692 @node Pragma AST_Entry
1693 @unnumberedsec Pragma AST_Entry
1698 @smallexample @c ada
1699 pragma AST_Entry (entry_IDENTIFIER);
1703 This pragma is implemented only in the OpenVMS implementation of GNAT@. The
1704 argument is the simple name of a single entry; at most one @code{AST_Entry}
1705 pragma is allowed for any given entry. This pragma must be used in
1706 conjunction with the @code{AST_Entry} attribute, and is only allowed after
1707 the entry declaration and in the same task type specification or single task
1708 as the entry to which it applies. This pragma specifies that the given entry
1709 may be used to handle an OpenVMS asynchronous system trap (@code{AST})
1710 resulting from an OpenVMS system service call. The pragma does not affect
1711 normal use of the entry. For further details on this pragma, see the
1712 DEC Ada Language Reference Manual, section 9.12a.
1714 @node Pragma Attribute_Definition
1715 @unnumberedsec Pragma Attribute_Definition
1716 @findex Attribute_Definition
1719 @smallexample @c ada
1720 pragma Attribute_Definition
1721 ([Attribute =>] ATTRIBUTE_DESIGNATOR,
1722 [Entity =>] LOCAL_NAME,
1723 [Expression =>] EXPRESSION | NAME);
1727 If @code{Attribute} is a known attribute name, this pragma is equivalent to
1728 the attribute definition clause:
1730 @smallexample @c ada
1731 for Entity'Attribute use Expression;
1734 If @code{Attribute} is not a recognized attribute name, the pragma is
1735 ignored, and a warning is emitted. This allows source
1736 code to be written that takes advantage of some new attribute, while remaining
1737 compilable with earlier compilers.
1739 @node Pragma C_Pass_By_Copy
1740 @unnumberedsec Pragma C_Pass_By_Copy
1741 @cindex Passing by copy
1742 @findex C_Pass_By_Copy
1745 @smallexample @c ada
1746 pragma C_Pass_By_Copy
1747 ([Max_Size =>] static_integer_EXPRESSION);
1751 Normally the default mechanism for passing C convention records to C
1752 convention subprograms is to pass them by reference, as suggested by RM
1753 B.3(69). Use the configuration pragma @code{C_Pass_By_Copy} to change
1754 this default, by requiring that record formal parameters be passed by
1755 copy if all of the following conditions are met:
1759 The size of the record type does not exceed the value specified for
1762 The record type has @code{Convention C}.
1764 The formal parameter has this record type, and the subprogram has a
1765 foreign (non-Ada) convention.
1769 If these conditions are met the argument is passed by copy, i.e.@: in a
1770 manner consistent with what C expects if the corresponding formal in the
1771 C prototype is a struct (rather than a pointer to a struct).
1773 You can also pass records by copy by specifying the convention
1774 @code{C_Pass_By_Copy} for the record type, or by using the extended
1775 @code{Import} and @code{Export} pragmas, which allow specification of
1776 passing mechanisms on a parameter by parameter basis.
1779 @unnumberedsec Pragma Check
1781 @cindex Named assertions
1785 @smallexample @c ada
1787 [Name =>] CHECK_KIND,
1788 [Check =>] Boolean_EXPRESSION
1789 [, [Message =>] string_EXPRESSION] );
1791 CHECK_KIND ::= IDENTIFIER |
1794 Type_Invariant'Class |
1799 This pragma is similar to the predefined pragma @code{Assert} except that an
1800 extra identifier argument is present. In conjunction with pragma
1801 @code{Check_Policy}, this can be used to define groups of assertions that can
1802 be independently controlled. The identifier @code{Assertion} is special, it
1803 refers to the normal set of pragma @code{Assert} statements.
1805 Checks introduced by this pragma are normally deactivated by default. They can
1806 be activated either by the command line option @option{-gnata}, which turns on
1807 all checks, or individually controlled using pragma @code{Check_Policy}.
1809 The identifiers @code{Assertions} and @code{Statement_Assertions} are not
1810 permitted as check kinds, since this would cause confusion with the use
1811 of these identifiers in @code{Assertion_Policy} and @code{Check_Policy}
1812 pragmas, where they are used to refer to sets of assertions.
1814 @node Pragma Check_Float_Overflow
1815 @unnumberedsec Pragma Check_Float_Overflow
1816 @cindex Floating-point overflow
1817 @findex Check_Float_Overflow
1820 @smallexample @c ada
1821 pragma Check_Float_Overflow;
1825 In Ada, the predefined floating-point types (@code{Short_Float},
1826 @code{Float}, @code{Long_Float}, @code{Long_Long_Float}) are
1827 defined to be @emph{unconstrained}. This means that even though each
1828 has a well-defined base range, an operation that delivers a result
1829 outside this base range is not required to raise an exception.
1830 This implementation permission accommodates the notion
1831 of infinities in IEEE floating-point, and corresponds to the
1832 efficient execution mode on most machines. GNAT will not raise
1833 overflow exceptions on these machines; instead it will generate
1834 infinities and NaN's as defined in the IEEE standard.
1836 Generating infinities, although efficient, is not always desirable.
1837 Often the preferable approach is to check for overflow, even at the
1838 (perhaps considerable) expense of run-time performance.
1839 This can be accomplished by defining your own constrained floating-point subtypes -- i.e., by supplying explicit
1840 range constraints -- and indeed such a subtype
1841 can have the same base range as its base type. For example:
1843 @smallexample @c ada
1844 subtype My_Float is Float range Float'Range;
1848 Here @code{My_Float} has the same range as
1849 @code{Float} but is constrained, so operations on
1850 @code{My_Float} values will be checked for overflow
1853 This style will achieve the desired goal, but
1854 it is often more convenient to be able to simply use
1855 the standard predefined floating-point types as long
1856 as overflow checking could be guaranteed.
1857 The @code{Check_Float_Overflow}
1858 configuration pragma achieves this effect. If a unit is compiled
1859 subject to this configuration pragma, then all operations
1860 on predefined floating-point types including operations on
1861 base types of these floating-point types will be treated as
1862 though those types were constrained, and overflow checks
1863 will be generated. The @code{Constraint_Error}
1864 exception is raised if the result is out of range.
1866 This mode can also be set by use of the compiler
1867 switch @option{-gnateF}.
1869 @node Pragma Check_Name
1870 @unnumberedsec Pragma Check_Name
1871 @cindex Defining check names
1872 @cindex Check names, defining
1876 @smallexample @c ada
1877 pragma Check_Name (check_name_IDENTIFIER);
1881 This is a configuration pragma that defines a new implementation
1882 defined check name (unless IDENTIFIER matches one of the predefined
1883 check names, in which case the pragma has no effect). Check names
1884 are global to a partition, so if two or more configuration pragmas
1885 are present in a partition mentioning the same name, only one new
1886 check name is introduced.
1888 An implementation defined check name introduced with this pragma may
1889 be used in only three contexts: @code{pragma Suppress},
1890 @code{pragma Unsuppress},
1891 and as the prefix of a @code{Check_Name'Enabled} attribute reference. For
1892 any of these three cases, the check name must be visible. A check
1893 name is visible if it is in the configuration pragmas applying to
1894 the current unit, or if it appears at the start of any unit that
1895 is part of the dependency set of the current unit (e.g., units that
1896 are mentioned in @code{with} clauses).
1898 Check names introduced by this pragma are subject to control by compiler
1899 switches (in particular -gnatp) in the usual manner.
1901 @node Pragma Check_Policy
1902 @unnumberedsec Pragma Check_Policy
1903 @cindex Controlling assertions
1904 @cindex Assertions, control
1905 @cindex Check pragma control
1906 @cindex Named assertions
1910 @smallexample @c ada
1912 ([Name =>] CHECK_KIND,
1913 [Policy =>] POLICY_IDENTIFIER);
1915 pragma Check_Policy (
1916 CHECK_KIND => POLICY_IDENTIFIER
1917 @{, CHECK_KIND => POLICY_IDENTIFIER@});
1919 ASSERTION_KIND ::= RM_ASSERTION_KIND | ID_ASSERTION_KIND
1921 CHECK_KIND ::= IDENTIFIER |
1924 Type_Invariant'Class |
1927 The identifiers Name and Policy are not allowed as CHECK_KIND values. This
1928 avoids confusion between the two possible syntax forms for this pragma.
1930 POLICY_IDENTIFIER ::= ON | OFF | CHECK | DISABLE | IGNORE
1934 This pragma is used to set the checking policy for assertions (specified
1935 by aspects or pragmas), the @code{Debug} pragma, or additional checks
1936 to be checked using the @code{Check} pragma. It may appear either as
1937 a configuration pragma, or within a declarative part of package. In the
1938 latter case, it applies from the point where it appears to the end of
1939 the declarative region (like pragma @code{Suppress}).
1941 The @code{Check_Policy} pragma is similar to the
1942 predefined @code{Assertion_Policy} pragma,
1943 and if the check kind corresponds to one of the assertion kinds that
1944 are allowed by @code{Assertion_Policy}, then the effect is identical.
1946 If the first argument is Debug, then the policy applies to Debug pragmas,
1947 disabling their effect if the policy is @code{OFF}, @code{DISABLE}, or
1948 @code{IGNORE}, and allowing them to execute with normal semantics if
1949 the policy is @code{ON} or @code{CHECK}. In addition if the policy is
1950 @code{DISABLE}, then the procedure call in @code{Debug} pragmas will
1951 be totally ignored and not analyzed semantically.
1953 Finally the first argument may be some other identifier than the above
1954 possibilities, in which case it controls a set of named assertions
1955 that can be checked using pragma @code{Check}. For example, if the pragma:
1957 @smallexample @c ada
1958 pragma Check_Policy (Critical_Error, OFF);
1962 is given, then subsequent @code{Check} pragmas whose first argument is also
1963 @code{Critical_Error} will be disabled.
1965 The check policy is @code{OFF} to turn off corresponding checks, and @code{ON}
1966 to turn on corresponding checks. The default for a set of checks for which no
1967 @code{Check_Policy} is given is @code{OFF} unless the compiler switch
1968 @option{-gnata} is given, which turns on all checks by default.
1970 The check policy settings @code{CHECK} and @code{IGNORE} are recognized
1971 as synonyms for @code{ON} and @code{OFF}. These synonyms are provided for
1972 compatibility with the standard @code{Assertion_Policy} pragma. The check
1973 policy setting @code{DISABLE} causes the second argument of a corresponding
1974 @code{Check} pragma to be completely ignored and not analyzed.
1976 @node Pragma CIL_Constructor
1977 @unnumberedsec Pragma CIL_Constructor
1978 @findex CIL_Constructor
1982 @smallexample @c ada
1983 pragma CIL_Constructor ([Entity =>] function_LOCAL_NAME);
1987 This pragma is used to assert that the specified Ada function should be
1988 mapped to the .NET constructor for some Ada tagged record type.
1990 See section 4.1 of the
1991 @code{GNAT User's Guide: Supplement for the .NET Platform.}
1992 for related information.
1994 @node Pragma Comment
1995 @unnumberedsec Pragma Comment
2000 @smallexample @c ada
2001 pragma Comment (static_string_EXPRESSION);
2005 This is almost identical in effect to pragma @code{Ident}. It allows the
2006 placement of a comment into the object file and hence into the
2007 executable file if the operating system permits such usage. The
2008 difference is that @code{Comment}, unlike @code{Ident}, has
2009 no limitations on placement of the pragma (it can be placed
2010 anywhere in the main source unit), and if more than one pragma
2011 is used, all comments are retained.
2013 @node Pragma Common_Object
2014 @unnumberedsec Pragma Common_Object
2015 @findex Common_Object
2019 @smallexample @c ada
2020 pragma Common_Object (
2021 [Internal =>] LOCAL_NAME
2022 [, [External =>] EXTERNAL_SYMBOL]
2023 [, [Size =>] EXTERNAL_SYMBOL] );
2027 | static_string_EXPRESSION
2031 This pragma enables the shared use of variables stored in overlaid
2032 linker areas corresponding to the use of @code{COMMON}
2033 in Fortran. The single
2034 object @var{LOCAL_NAME} is assigned to the area designated by
2035 the @var{External} argument.
2036 You may define a record to correspond to a series
2037 of fields. The @var{Size} argument
2038 is syntax checked in GNAT, but otherwise ignored.
2040 @code{Common_Object} is not supported on all platforms. If no
2041 support is available, then the code generator will issue a message
2042 indicating that the necessary attribute for implementation of this
2043 pragma is not available.
2045 @node Pragma Compile_Time_Error
2046 @unnumberedsec Pragma Compile_Time_Error
2047 @findex Compile_Time_Error
2051 @smallexample @c ada
2052 pragma Compile_Time_Error
2053 (boolean_EXPRESSION, static_string_EXPRESSION);
2057 This pragma can be used to generate additional compile time
2059 is particularly useful in generics, where errors can be issued for
2060 specific problematic instantiations. The first parameter is a boolean
2061 expression. The pragma is effective only if the value of this expression
2062 is known at compile time, and has the value True. The set of expressions
2063 whose values are known at compile time includes all static boolean
2064 expressions, and also other values which the compiler can determine
2065 at compile time (e.g., the size of a record type set by an explicit
2066 size representation clause, or the value of a variable which was
2067 initialized to a constant and is known not to have been modified).
2068 If these conditions are met, an error message is generated using
2069 the value given as the second argument. This string value may contain
2070 embedded ASCII.LF characters to break the message into multiple lines.
2072 @node Pragma Compile_Time_Warning
2073 @unnumberedsec Pragma Compile_Time_Warning
2074 @findex Compile_Time_Warning
2078 @smallexample @c ada
2079 pragma Compile_Time_Warning
2080 (boolean_EXPRESSION, static_string_EXPRESSION);
2084 Same as pragma Compile_Time_Error, except a warning is issued instead
2085 of an error message. Note that if this pragma is used in a package that
2086 is with'ed by a client, the client will get the warning even though it
2087 is issued by a with'ed package (normally warnings in with'ed units are
2088 suppressed, but this is a special exception to that rule).
2090 One typical use is within a generic where compile time known characteristics
2091 of formal parameters are tested, and warnings given appropriately. Another use
2092 with a first parameter of True is to warn a client about use of a package,
2093 for example that it is not fully implemented.
2095 @node Pragma Compiler_Unit
2096 @unnumberedsec Pragma Compiler_Unit
2097 @findex Compiler_Unit
2101 @smallexample @c ada
2102 pragma Compiler_Unit;
2106 This pragma is obsolete. It is equivalent to Compiler_Unit_Warning. It is
2107 retained so that old versions of the GNAT run-time that use this pragma can
2108 be compiled with newer versions of the compiler.
2110 @node Pragma Compiler_Unit_Warning
2111 @unnumberedsec Pragma Compiler_Unit_Warning
2112 @findex Compiler_Unit_Warning
2116 @smallexample @c ada
2117 pragma Compiler_Unit_Warning;
2121 This pragma is intended only for internal use in the GNAT run-time library.
2122 It indicates that the unit is used as part of the compiler build. The effect
2123 is to generate warnings for the use of constructs (for example, conditional
2124 expressions) that would cause trouble when bootstrapping using an older
2125 version of GNAT. For the exact list of restrictions, see the compiler sources
2126 and references to Check_Compiler_Unit.
2128 @node Pragma Complete_Representation
2129 @unnumberedsec Pragma Complete_Representation
2130 @findex Complete_Representation
2134 @smallexample @c ada
2135 pragma Complete_Representation;
2139 This pragma must appear immediately within a record representation
2140 clause. Typical placements are before the first component clause
2141 or after the last component clause. The effect is to give an error
2142 message if any component is missing a component clause. This pragma
2143 may be used to ensure that a record representation clause is
2144 complete, and that this invariant is maintained if fields are
2145 added to the record in the future.
2147 @node Pragma Complex_Representation
2148 @unnumberedsec Pragma Complex_Representation
2149 @findex Complex_Representation
2153 @smallexample @c ada
2154 pragma Complex_Representation
2155 ([Entity =>] LOCAL_NAME);
2159 The @var{Entity} argument must be the name of a record type which has
2160 two fields of the same floating-point type. The effect of this pragma is
2161 to force gcc to use the special internal complex representation form for
2162 this record, which may be more efficient. Note that this may result in
2163 the code for this type not conforming to standard ABI (application
2164 binary interface) requirements for the handling of record types. For
2165 example, in some environments, there is a requirement for passing
2166 records by pointer, and the use of this pragma may result in passing
2167 this type in floating-point registers.
2169 @node Pragma Component_Alignment
2170 @unnumberedsec Pragma Component_Alignment
2171 @cindex Alignments of components
2172 @findex Component_Alignment
2176 @smallexample @c ada
2177 pragma Component_Alignment (
2178 [Form =>] ALIGNMENT_CHOICE
2179 [, [Name =>] type_LOCAL_NAME]);
2181 ALIGNMENT_CHOICE ::=
2189 Specifies the alignment of components in array or record types.
2190 The meaning of the @var{Form} argument is as follows:
2193 @findex Component_Size
2194 @item Component_Size
2195 Aligns scalar components and subcomponents of the array or record type
2196 on boundaries appropriate to their inherent size (naturally
2197 aligned). For example, 1-byte components are aligned on byte boundaries,
2198 2-byte integer components are aligned on 2-byte boundaries, 4-byte
2199 integer components are aligned on 4-byte boundaries and so on. These
2200 alignment rules correspond to the normal rules for C compilers on all
2201 machines except the VAX@.
2203 @findex Component_Size_4
2204 @item Component_Size_4
2205 Naturally aligns components with a size of four or fewer
2206 bytes. Components that are larger than 4 bytes are placed on the next
2209 @findex Storage_Unit
2211 Specifies that array or record components are byte aligned, i.e.@:
2212 aligned on boundaries determined by the value of the constant
2213 @code{System.Storage_Unit}.
2217 Specifies that array or record components are aligned on default
2218 boundaries, appropriate to the underlying hardware or operating system or
2219 both. For OpenVMS VAX systems, the @code{Default} choice is the same as
2220 the @code{Storage_Unit} choice (byte alignment). For all other systems,
2221 the @code{Default} choice is the same as @code{Component_Size} (natural
2226 If the @code{Name} parameter is present, @var{type_LOCAL_NAME} must
2227 refer to a local record or array type, and the specified alignment
2228 choice applies to the specified type. The use of
2229 @code{Component_Alignment} together with a pragma @code{Pack} causes the
2230 @code{Component_Alignment} pragma to be ignored. The use of
2231 @code{Component_Alignment} together with a record representation clause
2232 is only effective for fields not specified by the representation clause.
2234 If the @code{Name} parameter is absent, the pragma can be used as either
2235 a configuration pragma, in which case it applies to one or more units in
2236 accordance with the normal rules for configuration pragmas, or it can be
2237 used within a declarative part, in which case it applies to types that
2238 are declared within this declarative part, or within any nested scope
2239 within this declarative part. In either case it specifies the alignment
2240 to be applied to any record or array type which has otherwise standard
2243 If the alignment for a record or array type is not specified (using
2244 pragma @code{Pack}, pragma @code{Component_Alignment}, or a record rep
2245 clause), the GNAT uses the default alignment as described previously.
2247 @node Pragma Contract_Cases
2248 @unnumberedsec Pragma Contract_Cases
2249 @cindex Contract cases
2250 @findex Contract_Cases
2254 @smallexample @c ada
2255 pragma Contract_Cases (
2256 Condition => Consequence
2257 @{,Condition => Consequence@});
2261 The @code{Contract_Cases} pragma allows defining fine-grain specifications
2262 that can complement or replace the contract given by a precondition and a
2263 postcondition. Additionally, the @code{Contract_Cases} pragma can be used
2264 by testing and formal verification tools. The compiler checks its validity and,
2265 depending on the assertion policy at the point of declaration of the pragma,
2266 it may insert a check in the executable. For code generation, the contract
2269 @smallexample @c ada
2270 pragma Contract_Cases (
2278 @smallexample @c ada
2279 C1 : constant Boolean := Cond1; -- evaluated at subprogram entry
2280 C2 : constant Boolean := Cond2; -- evaluated at subprogram entry
2281 pragma Precondition ((C1 and not C2) or (C2 and not C1));
2282 pragma Postcondition (if C1 then Pred1);
2283 pragma Postcondition (if C2 then Pred2);
2287 The precondition ensures that one and only one of the conditions is
2288 satisfied on entry to the subprogram.
2289 The postcondition ensures that for the condition that was True on entry,
2290 the corrresponding consequence is True on exit. Other consequence expressions
2293 A precondition @code{P} and postcondition @code{Q} can also be
2294 expressed as contract cases:
2296 @smallexample @c ada
2297 pragma Contract_Cases (P => Q);
2300 The placement and visibility rules for @code{Contract_Cases} pragmas are
2301 identical to those described for preconditions and postconditions.
2303 The compiler checks that boolean expressions given in conditions and
2304 consequences are valid, where the rules for conditions are the same as
2305 the rule for an expression in @code{Precondition} and the rules for
2306 consequences are the same as the rule for an expression in
2307 @code{Postcondition}. In particular, attributes @code{'Old} and
2308 @code{'Result} can only be used within consequence expressions.
2309 The condition for the last contract case may be @code{others}, to denote
2310 any case not captured by the previous cases. The
2311 following is an example of use within a package spec:
2313 @smallexample @c ada
2314 package Math_Functions is
2316 function Sqrt (Arg : Float) return Float;
2317 pragma Contract_Cases ((Arg in 0 .. 99) => Sqrt'Result < 10,
2318 Arg >= 100 => Sqrt'Result >= 10,
2319 others => Sqrt'Result = 0);
2325 The meaning of contract cases is that only one case should apply at each
2326 call, as determined by the corresponding condition evaluating to True,
2327 and that the consequence for this case should hold when the subprogram
2330 @node Pragma Convention_Identifier
2331 @unnumberedsec Pragma Convention_Identifier
2332 @findex Convention_Identifier
2333 @cindex Conventions, synonyms
2337 @smallexample @c ada
2338 pragma Convention_Identifier (
2339 [Name =>] IDENTIFIER,
2340 [Convention =>] convention_IDENTIFIER);
2344 This pragma provides a mechanism for supplying synonyms for existing
2345 convention identifiers. The @code{Name} identifier can subsequently
2346 be used as a synonym for the given convention in other pragmas (including
2347 for example pragma @code{Import} or another @code{Convention_Identifier}
2348 pragma). As an example of the use of this, suppose you had legacy code
2349 which used Fortran77 as the identifier for Fortran. Then the pragma:
2351 @smallexample @c ada
2352 pragma Convention_Identifier (Fortran77, Fortran);
2356 would allow the use of the convention identifier @code{Fortran77} in
2357 subsequent code, avoiding the need to modify the sources. As another
2358 example, you could use this to parameterize convention requirements
2359 according to systems. Suppose you needed to use @code{Stdcall} on
2360 windows systems, and @code{C} on some other system, then you could
2361 define a convention identifier @code{Library} and use a single
2362 @code{Convention_Identifier} pragma to specify which convention
2363 would be used system-wide.
2365 @node Pragma CPP_Class
2366 @unnumberedsec Pragma CPP_Class
2368 @cindex Interfacing with C++
2372 @smallexample @c ada
2373 pragma CPP_Class ([Entity =>] LOCAL_NAME);
2377 The argument denotes an entity in the current declarative region that is
2378 declared as a record type. It indicates that the type corresponds to an
2379 externally declared C++ class type, and is to be laid out the same way
2380 that C++ would lay out the type. If the C++ class has virtual primitives
2381 then the record must be declared as a tagged record type.
2383 Types for which @code{CPP_Class} is specified do not have assignment or
2384 equality operators defined (such operations can be imported or declared
2385 as subprograms as required). Initialization is allowed only by constructor
2386 functions (see pragma @code{CPP_Constructor}). Such types are implicitly
2387 limited if not explicitly declared as limited or derived from a limited
2388 type, and an error is issued in that case.
2390 See @ref{Interfacing to C++} for related information.
2392 Note: Pragma @code{CPP_Class} is currently obsolete. It is supported
2393 for backward compatibility but its functionality is available
2394 using pragma @code{Import} with @code{Convention} = @code{CPP}.
2396 @node Pragma CPP_Constructor
2397 @unnumberedsec Pragma CPP_Constructor
2398 @cindex Interfacing with C++
2399 @findex CPP_Constructor
2403 @smallexample @c ada
2404 pragma CPP_Constructor ([Entity =>] LOCAL_NAME
2405 [, [External_Name =>] static_string_EXPRESSION ]
2406 [, [Link_Name =>] static_string_EXPRESSION ]);
2410 This pragma identifies an imported function (imported in the usual way
2411 with pragma @code{Import}) as corresponding to a C++ constructor. If
2412 @code{External_Name} and @code{Link_Name} are not specified then the
2413 @code{Entity} argument is a name that must have been previously mentioned
2414 in a pragma @code{Import} with @code{Convention} = @code{CPP}. Such name
2415 must be of one of the following forms:
2419 @code{function @var{Fname} return @var{T}}
2423 @code{function @var{Fname} return @var{T}'Class}
2426 @code{function @var{Fname} (@dots{}) return @var{T}}
2430 @code{function @var{Fname} (@dots{}) return @var{T}'Class}
2434 where @var{T} is a limited record type imported from C++ with pragma
2435 @code{Import} and @code{Convention} = @code{CPP}.
2437 The first two forms import the default constructor, used when an object
2438 of type @var{T} is created on the Ada side with no explicit constructor.
2439 The latter two forms cover all the non-default constructors of the type.
2440 See the @value{EDITION} User's Guide for details.
2442 If no constructors are imported, it is impossible to create any objects
2443 on the Ada side and the type is implicitly declared abstract.
2445 Pragma @code{CPP_Constructor} is intended primarily for automatic generation
2446 using an automatic binding generator tool (such as the @code{-fdump-ada-spec}
2448 See @ref{Interfacing to C++} for more related information.
2450 Note: The use of functions returning class-wide types for constructors is
2451 currently obsolete. They are supported for backward compatibility. The
2452 use of functions returning the type T leave the Ada sources more clear
2453 because the imported C++ constructors always return an object of type T;
2454 that is, they never return an object whose type is a descendant of type T.
2456 @node Pragma CPP_Virtual
2457 @unnumberedsec Pragma CPP_Virtual
2458 @cindex Interfacing to C++
2461 This pragma is now obsolete and, other than generating a warning if warnings
2462 on obsolescent features are enabled, is completely ignored.
2463 It is retained for compatibility
2464 purposes. It used to be required to ensure compoatibility with C++, but
2465 is no longer required for that purpose because GNAT generates
2466 the same object layout as the G++ compiler by default.
2468 See @ref{Interfacing to C++} for related information.
2470 @node Pragma CPP_Vtable
2471 @unnumberedsec Pragma CPP_Vtable
2472 @cindex Interfacing with C++
2475 This pragma is now obsolete and, other than generating a warning if warnings
2476 on obsolescent features are enabled, is completely ignored.
2477 It used to be required to ensure compatibility with C++, but
2478 is no longer required for that purpose because GNAT generates
2479 the same object layout as the G++ compiler by default.
2481 See @ref{Interfacing to C++} for related information.
2484 @unnumberedsec Pragma CPU
2489 @smallexample @c ada
2490 pragma CPU (EXPRESSION);
2494 This pragma is standard in Ada 2012, but is available in all earlier
2495 versions of Ada as an implementation-defined pragma.
2496 See Ada 2012 Reference Manual for details.
2499 @unnumberedsec Pragma Debug
2504 @smallexample @c ada
2505 pragma Debug ([CONDITION, ]PROCEDURE_CALL_WITHOUT_SEMICOLON);
2507 PROCEDURE_CALL_WITHOUT_SEMICOLON ::=
2509 | PROCEDURE_PREFIX ACTUAL_PARAMETER_PART
2513 The procedure call argument has the syntactic form of an expression, meeting
2514 the syntactic requirements for pragmas.
2516 If debug pragmas are not enabled or if the condition is present and evaluates
2517 to False, this pragma has no effect. If debug pragmas are enabled, the
2518 semantics of the pragma is exactly equivalent to the procedure call statement
2519 corresponding to the argument with a terminating semicolon. Pragmas are
2520 permitted in sequences of declarations, so you can use pragma @code{Debug} to
2521 intersperse calls to debug procedures in the middle of declarations. Debug
2522 pragmas can be enabled either by use of the command line switch @option{-gnata}
2523 or by use of the pragma @code{Check_Policy} with a first argument of
2526 @node Pragma Debug_Policy
2527 @unnumberedsec Pragma Debug_Policy
2528 @findex Debug_Policy
2532 @smallexample @c ada
2533 pragma Debug_Policy (CHECK | DISABLE | IGNORE | ON | OFF);
2537 This pragma is equivalent to a corresponding @code{Check_Policy} pragma
2538 with a first argument of @code{Debug}. It is retained for historical
2539 compatibility reasons.
2541 @node Pragma Default_Scalar_Storage_Order
2542 @unnumberedsec Pragma Default_Scalar_Storage_Order
2543 @cindex Default_Scalar_Storage_Order
2544 @cindex Scalar_Storage_Order
2545 @findex Default_Scalar_Storage_Order
2549 @smallexample @c ada
2550 pragma Default_Scalar_Storage_Order (High_Order_First | Low_Order_First);
2554 Normally if no explicit @code{Scalar_Storage_Order} is given for a record
2555 type or array type, then the scalar storage order defaults to the native
2556 order for the target. However, this default may be overridden using
2557 this pragma (except for derived tagged types, which always default to
2558 inheriting the scalar storage order of their parent). The pragma may
2559 appear as a configuration pragma, or locally within a package spec or
2560 declarative part. In the latter case, it applies to all subsequent
2561 types declared within that package spec or declarative part.
2563 If this pragma is used as a configuration pragma which appears within a
2564 configuration pragma file (as opposed to appearing explicitly at the start
2565 of a single unit), then the binder will require that all units in a partition
2566 be compiled in a similar manner, other than run-time units, which are not
2567 affected by this pragma.
2569 The following example shows the use of this pragma:
2571 @smallexample @c ada
2572 pragma Default_Scalar_Storage_Order (High_Order_First);
2573 with System; use System;
2582 for L2'Scalar_Storage_Order use Low_Order_First;
2591 pragma Default_Scalar_Storage_Order (Low_Order_First);
2598 type H4a is new Inner.L4;
2607 In this example record types L.. have @code{Low_Order_First} scalar
2608 storage order, and record types H.. have @code{High_Order_First}.
2609 Note that in the case of @code{H4a}, the order is not inherited
2610 from the parent type. Only an explicitly set @code{Scalar_Storage_Order}
2611 gets inherited on type derivation.
2613 @node Pragma Default_Storage_Pool
2614 @unnumberedsec Pragma Default_Storage_Pool
2615 @cindex Default_Storage_Pool
2616 @findex Default_Storage_Pool
2620 @smallexample @c ada
2621 pragma Default_Storage_Pool (storage_pool_NAME | null);
2625 This pragma is standard in Ada 2012, but is available in all earlier
2626 versions of Ada as an implementation-defined pragma.
2627 See Ada 2012 Reference Manual for details.
2629 @node Pragma Depends
2630 @unnumberedsec Pragma Depends
2633 For the description of this pragma, see SPARK 2014 Reference Manual,
2636 @node Pragma Detect_Blocking
2637 @unnumberedsec Pragma Detect_Blocking
2638 @findex Detect_Blocking
2642 @smallexample @c ada
2643 pragma Detect_Blocking;
2647 This is a standard pragma in Ada 2005, that is available in all earlier
2648 versions of Ada as an implementation-defined pragma.
2650 This is a configuration pragma that forces the detection of potentially
2651 blocking operations within a protected operation, and to raise Program_Error
2654 @node Pragma Disable_Atomic_Synchronization
2655 @unnumberedsec Pragma Disable_Atomic_Synchronization
2656 @cindex Atomic Synchronization
2657 @findex Disable_Atomic_Synchronization
2661 @smallexample @c ada
2662 pragma Disable_Atomic_Synchronization [(Entity)];
2666 Ada requires that accesses (reads or writes) of an atomic variable be
2667 regarded as synchronization points in the case of multiple tasks.
2668 Particularly in the case of multi-processors this may require special
2669 handling, e.g. the generation of memory barriers. This capability may
2670 be turned off using this pragma in cases where it is known not to be
2673 The placement and scope rules for this pragma are the same as those
2674 for @code{pragma Suppress}. In particular it can be used as a
2675 configuration pragma, or in a declaration sequence where it applies
2676 till the end of the scope. If an @code{Entity} argument is present,
2677 the action applies only to that entity.
2679 @node Pragma Dispatching_Domain
2680 @unnumberedsec Pragma Dispatching_Domain
2681 @findex Dispatching_Domain
2685 @smallexample @c ada
2686 pragma Dispatching_Domain (EXPRESSION);
2690 This pragma is standard in Ada 2012, but is available in all earlier
2691 versions of Ada as an implementation-defined pragma.
2692 See Ada 2012 Reference Manual for details.
2694 @node Pragma Effective_Reads
2695 @unnumberedsec Pragma Effective_Reads
2696 @findex Effective_Reads
2698 For the description of this pragma, see SPARK 2014 Reference Manual,
2701 @node Pragma Effective_Writes
2702 @unnumberedsec Pragma Effective_Writes
2703 @findex Effective_Writes
2705 For the description of this pragma, see SPARK 2014 Reference Manual,
2708 @node Pragma Elaboration_Checks
2709 @unnumberedsec Pragma Elaboration_Checks
2710 @cindex Elaboration control
2711 @findex Elaboration_Checks
2715 @smallexample @c ada
2716 pragma Elaboration_Checks (Dynamic | Static);
2720 This is a configuration pragma that provides control over the
2721 elaboration model used by the compilation affected by the
2722 pragma. If the parameter is @code{Dynamic},
2723 then the dynamic elaboration
2724 model described in the Ada Reference Manual is used, as though
2725 the @option{-gnatE} switch had been specified on the command
2726 line. If the parameter is @code{Static}, then the default GNAT static
2727 model is used. This configuration pragma overrides the setting
2728 of the command line. For full details on the elaboration models
2729 used by the GNAT compiler, see @ref{Elaboration Order Handling in GNAT,,,
2730 gnat_ugn, @value{EDITION} User's Guide}.
2732 @node Pragma Eliminate
2733 @unnumberedsec Pragma Eliminate
2734 @cindex Elimination of unused subprograms
2739 @smallexample @c ada
2740 pragma Eliminate ([Entity =>] DEFINING_DESIGNATOR,
2741 [Source_Location =>] STRING_LITERAL);
2745 The string literal given for the source location is a string which
2746 specifies the line number of the occurrence of the entity, using
2747 the syntax for SOURCE_TRACE given below:
2749 @smallexample @c ada
2750 SOURCE_TRACE ::= SOURCE_REFERENCE [LBRACKET SOURCE_TRACE RBRACKET]
2755 SOURCE_REFERENCE ::= FILE_NAME : LINE_NUMBER
2757 LINE_NUMBER ::= DIGIT @{DIGIT@}
2761 Spaces around the colon in a @code{Source_Reference} are optional.
2763 The @code{DEFINING_DESIGNATOR} matches the defining designator used in an
2764 explicit subprogram declaration, where the @code{entity} name in this
2765 designator appears on the source line specified by the source location.
2767 The source trace that is given as the @code{Source_Location} shall obey the
2768 following rules. The @code{FILE_NAME} is the short name (with no directory
2769 information) of an Ada source file, given using exactly the required syntax
2770 for the underlying file system (e.g. case is important if the underlying
2771 operating system is case sensitive). @code{LINE_NUMBER} gives the line
2772 number of the occurrence of the @code{entity}
2773 as a decimal literal without an exponent or point. If an @code{entity} is not
2774 declared in a generic instantiation (this includes generic subprogram
2775 instances), the source trace includes only one source reference. If an entity
2776 is declared inside a generic instantiation, its source trace (when parsing
2777 from left to right) starts with the source location of the declaration of the
2778 entity in the generic unit and ends with the source location of the
2779 instantiation (it is given in square brackets). This approach is recursively
2780 used in case of nested instantiations: the rightmost (nested most deeply in
2781 square brackets) element of the source trace is the location of the outermost
2782 instantiation, the next to left element is the location of the next (first
2783 nested) instantiation in the code of the corresponding generic unit, and so
2784 on, and the leftmost element (that is out of any square brackets) is the
2785 location of the declaration of the entity to eliminate in a generic unit.
2787 Note that the @code{Source_Location} argument specifies which of a set of
2788 similarly named entities is being eliminated, dealing both with overloading,
2789 and also appearance of the same entity name in different scopes.
2791 This pragma indicates that the given entity is not used in the program to be
2792 compiled and built. The effect of the pragma is to allow the compiler to
2793 eliminate the code or data associated with the named entity. Any reference to
2794 an eliminated entity causes a compile-time or link-time error.
2796 The intention of pragma @code{Eliminate} is to allow a program to be compiled
2797 in a system-independent manner, with unused entities eliminated, without
2798 needing to modify the source text. Normally the required set of
2799 @code{Eliminate} pragmas is constructed automatically using the gnatelim tool.
2801 Any source file change that removes, splits, or
2802 adds lines may make the set of Eliminate pragmas invalid because their
2803 @code{Source_Location} argument values may get out of date.
2805 Pragma @code{Eliminate} may be used where the referenced entity is a dispatching
2806 operation. In this case all the subprograms to which the given operation can
2807 dispatch are considered to be unused (are never called as a result of a direct
2808 or a dispatching call).
2810 @node Pragma Enable_Atomic_Synchronization
2811 @unnumberedsec Pragma Enable_Atomic_Synchronization
2812 @cindex Atomic Synchronization
2813 @findex Enable_Atomic_Synchronization
2817 @smallexample @c ada
2818 pragma Enable_Atomic_Synchronization [(Entity)];
2822 Ada requires that accesses (reads or writes) of an atomic variable be
2823 regarded as synchronization points in the case of multiple tasks.
2824 Particularly in the case of multi-processors this may require special
2825 handling, e.g. the generation of memory barriers. This synchronization
2826 is performed by default, but can be turned off using
2827 @code{pragma Disable_Atomic_Synchronization}. The
2828 @code{Enable_Atomic_Synchronization} pragma can be used to turn
2831 The placement and scope rules for this pragma are the same as those
2832 for @code{pragma Unsuppress}. In particular it can be used as a
2833 configuration pragma, or in a declaration sequence where it applies
2834 till the end of the scope. If an @code{Entity} argument is present,
2835 the action applies only to that entity.
2837 @node Pragma Export_Exception
2838 @unnumberedsec Pragma Export_Exception
2840 @findex Export_Exception
2844 @smallexample @c ada
2845 pragma Export_Exception (
2846 [Internal =>] LOCAL_NAME
2847 [, [External =>] EXTERNAL_SYMBOL]
2848 [, [Form =>] Ada | VMS]
2849 [, [Code =>] static_integer_EXPRESSION]);
2853 | static_string_EXPRESSION
2857 This pragma is implemented only in the OpenVMS implementation of GNAT@. It
2858 causes the specified exception to be propagated outside of the Ada program,
2859 so that it can be handled by programs written in other OpenVMS languages.
2860 This pragma establishes an external name for an Ada exception and makes the
2861 name available to the OpenVMS Linker as a global symbol. For further details
2862 on this pragma, see the
2863 DEC Ada Language Reference Manual, section 13.9a3.2.
2865 @node Pragma Export_Function
2866 @unnumberedsec Pragma Export_Function
2867 @cindex Argument passing mechanisms
2868 @findex Export_Function
2873 @smallexample @c ada
2874 pragma Export_Function (
2875 [Internal =>] LOCAL_NAME
2876 [, [External =>] EXTERNAL_SYMBOL]
2877 [, [Parameter_Types =>] PARAMETER_TYPES]
2878 [, [Result_Type =>] result_SUBTYPE_MARK]
2879 [, [Mechanism =>] MECHANISM]
2880 [, [Result_Mechanism =>] MECHANISM_NAME]);
2884 | static_string_EXPRESSION
2889 | TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@}
2893 | subtype_Name ' Access
2897 | (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@})
2899 MECHANISM_ASSOCIATION ::=
2900 [formal_parameter_NAME =>] MECHANISM_NAME
2902 MECHANISM_NAME ::= Value | Reference
2906 Use this pragma to make a function externally callable and optionally
2907 provide information on mechanisms to be used for passing parameter and
2908 result values. We recommend, for the purposes of improving portability,
2909 this pragma always be used in conjunction with a separate pragma
2910 @code{Export}, which must precede the pragma @code{Export_Function}.
2911 GNAT does not require a separate pragma @code{Export}, but if none is
2912 present, @code{Convention Ada} is assumed, which is usually
2913 not what is wanted, so it is usually appropriate to use this
2914 pragma in conjunction with a @code{Export} or @code{Convention}
2915 pragma that specifies the desired foreign convention.
2916 Pragma @code{Export_Function}
2917 (and @code{Export}, if present) must appear in the same declarative
2918 region as the function to which they apply.
2920 @var{internal_name} must uniquely designate the function to which the
2921 pragma applies. If more than one function name exists of this name in
2922 the declarative part you must use the @code{Parameter_Types} and
2923 @code{Result_Type} parameters is mandatory to achieve the required
2924 unique designation. @var{subtype_mark}s in these parameters must
2925 exactly match the subtypes in the corresponding function specification,
2926 using positional notation to match parameters with subtype marks.
2927 The form with an @code{'Access} attribute can be used to match an
2928 anonymous access parameter.
2930 @cindex Suppressing external name
2931 Special treatment is given if the EXTERNAL is an explicit null
2932 string or a static string expressions that evaluates to the null
2933 string. In this case, no external name is generated. This form
2934 still allows the specification of parameter mechanisms.
2936 @node Pragma Export_Object
2937 @unnumberedsec Pragma Export_Object
2938 @findex Export_Object
2942 @smallexample @c ada
2943 pragma Export_Object
2944 [Internal =>] LOCAL_NAME
2945 [, [External =>] EXTERNAL_SYMBOL]
2946 [, [Size =>] EXTERNAL_SYMBOL]
2950 | static_string_EXPRESSION
2954 This pragma designates an object as exported, and apart from the
2955 extended rules for external symbols, is identical in effect to the use of
2956 the normal @code{Export} pragma applied to an object. You may use a
2957 separate Export pragma (and you probably should from the point of view
2958 of portability), but it is not required. @var{Size} is syntax checked,
2959 but otherwise ignored by GNAT@.
2961 @node Pragma Export_Procedure
2962 @unnumberedsec Pragma Export_Procedure
2963 @findex Export_Procedure
2967 @smallexample @c ada
2968 pragma Export_Procedure (
2969 [Internal =>] LOCAL_NAME
2970 [, [External =>] EXTERNAL_SYMBOL]
2971 [, [Parameter_Types =>] PARAMETER_TYPES]
2972 [, [Mechanism =>] MECHANISM]);
2976 | static_string_EXPRESSION
2981 | TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@}
2985 | subtype_Name ' Access
2989 | (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@})
2991 MECHANISM_ASSOCIATION ::=
2992 [formal_parameter_NAME =>] MECHANISM_NAME
2994 MECHANISM_NAME ::= Value | Reference
2998 This pragma is identical to @code{Export_Function} except that it
2999 applies to a procedure rather than a function and the parameters
3000 @code{Result_Type} and @code{Result_Mechanism} are not permitted.
3001 GNAT does not require a separate pragma @code{Export}, but if none is
3002 present, @code{Convention Ada} is assumed, which is usually
3003 not what is wanted, so it is usually appropriate to use this
3004 pragma in conjunction with a @code{Export} or @code{Convention}
3005 pragma that specifies the desired foreign convention.
3007 @cindex Suppressing external name
3008 Special treatment is given if the EXTERNAL is an explicit null
3009 string or a static string expressions that evaluates to the null
3010 string. In this case, no external name is generated. This form
3011 still allows the specification of parameter mechanisms.
3013 @node Pragma Export_Value
3014 @unnumberedsec Pragma Export_Value
3015 @findex Export_Value
3019 @smallexample @c ada
3020 pragma Export_Value (
3021 [Value =>] static_integer_EXPRESSION,
3022 [Link_Name =>] static_string_EXPRESSION);
3026 This pragma serves to export a static integer value for external use.
3027 The first argument specifies the value to be exported. The Link_Name
3028 argument specifies the symbolic name to be associated with the integer
3029 value. This pragma is useful for defining a named static value in Ada
3030 that can be referenced in assembly language units to be linked with
3031 the application. This pragma is currently supported only for the
3032 AAMP target and is ignored for other targets.
3034 @node Pragma Export_Valued_Procedure
3035 @unnumberedsec Pragma Export_Valued_Procedure
3036 @findex Export_Valued_Procedure
3040 @smallexample @c ada
3041 pragma Export_Valued_Procedure (
3042 [Internal =>] LOCAL_NAME
3043 [, [External =>] EXTERNAL_SYMBOL]
3044 [, [Parameter_Types =>] PARAMETER_TYPES]
3045 [, [Mechanism =>] MECHANISM]);
3049 | static_string_EXPRESSION
3054 | TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@}
3058 | subtype_Name ' Access
3062 | (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@})
3064 MECHANISM_ASSOCIATION ::=
3065 [formal_parameter_NAME =>] MECHANISM_NAME
3067 MECHANISM_NAME ::= Value | Reference
3071 This pragma is identical to @code{Export_Procedure} except that the
3072 first parameter of @var{LOCAL_NAME}, which must be present, must be of
3073 mode @code{OUT}, and externally the subprogram is treated as a function
3074 with this parameter as the result of the function. GNAT provides for
3075 this capability to allow the use of @code{OUT} and @code{IN OUT}
3076 parameters in interfacing to external functions (which are not permitted
3078 GNAT does not require a separate pragma @code{Export}, but if none is
3079 present, @code{Convention Ada} is assumed, which is almost certainly
3080 not what is wanted since the whole point of this pragma is to interface
3081 with foreign language functions, so it is usually appropriate to use this
3082 pragma in conjunction with a @code{Export} or @code{Convention}
3083 pragma that specifies the desired foreign convention.
3085 @cindex Suppressing external name
3086 Special treatment is given if the EXTERNAL is an explicit null
3087 string or a static string expressions that evaluates to the null
3088 string. In this case, no external name is generated. This form
3089 still allows the specification of parameter mechanisms.
3091 @node Pragma Extend_System
3092 @unnumberedsec Pragma Extend_System
3093 @cindex @code{system}, extending
3095 @findex Extend_System
3099 @smallexample @c ada
3100 pragma Extend_System ([Name =>] IDENTIFIER);
3104 This pragma is used to provide backwards compatibility with other
3105 implementations that extend the facilities of package @code{System}. In
3106 GNAT, @code{System} contains only the definitions that are present in
3107 the Ada RM@. However, other implementations, notably the DEC Ada 83
3108 implementation, provide many extensions to package @code{System}.
3110 For each such implementation accommodated by this pragma, GNAT provides a
3111 package @code{Aux_@var{xxx}}, e.g.@: @code{Aux_DEC} for the DEC Ada 83
3112 implementation, which provides the required additional definitions. You
3113 can use this package in two ways. You can @code{with} it in the normal
3114 way and access entities either by selection or using a @code{use}
3115 clause. In this case no special processing is required.
3117 However, if existing code contains references such as
3118 @code{System.@var{xxx}} where @var{xxx} is an entity in the extended
3119 definitions provided in package @code{System}, you may use this pragma
3120 to extend visibility in @code{System} in a non-standard way that
3121 provides greater compatibility with the existing code. Pragma
3122 @code{Extend_System} is a configuration pragma whose single argument is
3123 the name of the package containing the extended definition
3124 (e.g.@: @code{Aux_DEC} for the DEC Ada case). A unit compiled under
3125 control of this pragma will be processed using special visibility
3126 processing that looks in package @code{System.Aux_@var{xxx}} where
3127 @code{Aux_@var{xxx}} is the pragma argument for any entity referenced in
3128 package @code{System}, but not found in package @code{System}.
3130 You can use this pragma either to access a predefined @code{System}
3131 extension supplied with the compiler, for example @code{Aux_DEC} or
3132 you can construct your own extension unit following the above
3133 definition. Note that such a package is a child of @code{System}
3134 and thus is considered part of the implementation.
3135 To compile it you will have to use the @option{-gnatg} switch,
3136 or the @option{/GNAT_INTERNAL} qualifier on OpenVMS,
3137 for compiling System units, as explained in the
3138 @value{EDITION} User's Guide.
3140 @node Pragma Extensions_Allowed
3141 @unnumberedsec Pragma Extensions_Allowed
3142 @cindex Ada Extensions
3143 @cindex GNAT Extensions
3144 @findex Extensions_Allowed
3148 @smallexample @c ada
3149 pragma Extensions_Allowed (On | Off);
3153 This configuration pragma enables or disables the implementation
3154 extension mode (the use of Off as a parameter cancels the effect
3155 of the @option{-gnatX} command switch).
3157 In extension mode, the latest version of the Ada language is
3158 implemented (currently Ada 2012), and in addition a small number
3159 of GNAT specific extensions are recognized as follows:
3162 @item Constrained attribute for generic objects
3163 The @code{Constrained} attribute is permitted for objects of
3164 generic types. The result indicates if the corresponding actual
3169 @node Pragma External
3170 @unnumberedsec Pragma External
3175 @smallexample @c ada
3177 [ Convention =>] convention_IDENTIFIER,
3178 [ Entity =>] LOCAL_NAME
3179 [, [External_Name =>] static_string_EXPRESSION ]
3180 [, [Link_Name =>] static_string_EXPRESSION ]);
3184 This pragma is identical in syntax and semantics to pragma
3185 @code{Export} as defined in the Ada Reference Manual. It is
3186 provided for compatibility with some Ada 83 compilers that
3187 used this pragma for exactly the same purposes as pragma
3188 @code{Export} before the latter was standardized.
3190 @node Pragma External_Name_Casing
3191 @unnumberedsec Pragma External_Name_Casing
3192 @cindex Dec Ada 83 casing compatibility
3193 @cindex External Names, casing
3194 @cindex Casing of External names
3195 @findex External_Name_Casing
3199 @smallexample @c ada
3200 pragma External_Name_Casing (
3201 Uppercase | Lowercase
3202 [, Uppercase | Lowercase | As_Is]);
3206 This pragma provides control over the casing of external names associated
3207 with Import and Export pragmas. There are two cases to consider:
3210 @item Implicit external names
3211 Implicit external names are derived from identifiers. The most common case
3212 arises when a standard Ada Import or Export pragma is used with only two
3215 @smallexample @c ada
3216 pragma Import (C, C_Routine);
3220 Since Ada is a case-insensitive language, the spelling of the identifier in
3221 the Ada source program does not provide any information on the desired
3222 casing of the external name, and so a convention is needed. In GNAT the
3223 default treatment is that such names are converted to all lower case
3224 letters. This corresponds to the normal C style in many environments.
3225 The first argument of pragma @code{External_Name_Casing} can be used to
3226 control this treatment. If @code{Uppercase} is specified, then the name
3227 will be forced to all uppercase letters. If @code{Lowercase} is specified,
3228 then the normal default of all lower case letters will be used.
3230 This same implicit treatment is also used in the case of extended DEC Ada 83
3231 compatible Import and Export pragmas where an external name is explicitly
3232 specified using an identifier rather than a string.
3234 @item Explicit external names
3235 Explicit external names are given as string literals. The most common case
3236 arises when a standard Ada Import or Export pragma is used with three
3239 @smallexample @c ada
3240 pragma Import (C, C_Routine, "C_routine");
3244 In this case, the string literal normally provides the exact casing required
3245 for the external name. The second argument of pragma
3246 @code{External_Name_Casing} may be used to modify this behavior.
3247 If @code{Uppercase} is specified, then the name
3248 will be forced to all uppercase letters. If @code{Lowercase} is specified,
3249 then the name will be forced to all lowercase letters. A specification of
3250 @code{As_Is} provides the normal default behavior in which the casing is
3251 taken from the string provided.
3255 This pragma may appear anywhere that a pragma is valid. In particular, it
3256 can be used as a configuration pragma in the @file{gnat.adc} file, in which
3257 case it applies to all subsequent compilations, or it can be used as a program
3258 unit pragma, in which case it only applies to the current unit, or it can
3259 be used more locally to control individual Import/Export pragmas.
3261 It is primarily intended for use with OpenVMS systems, where many
3262 compilers convert all symbols to upper case by default. For interfacing to
3263 such compilers (e.g.@: the DEC C compiler), it may be convenient to use
3266 @smallexample @c ada
3267 pragma External_Name_Casing (Uppercase, Uppercase);
3271 to enforce the upper casing of all external symbols.
3273 @node Pragma Fast_Math
3274 @unnumberedsec Pragma Fast_Math
3279 @smallexample @c ada
3284 This is a configuration pragma which activates a mode in which speed is
3285 considered more important for floating-point operations than absolutely
3286 accurate adherence to the requirements of the standard. Currently the
3287 following operations are affected:
3290 @item Complex Multiplication
3291 The normal simple formula for complex multiplication can result in intermediate
3292 overflows for numbers near the end of the range. The Ada standard requires that
3293 this situation be detected and corrected by scaling, but in Fast_Math mode such
3294 cases will simply result in overflow. Note that to take advantage of this you
3295 must instantiate your own version of @code{Ada.Numerics.Generic_Complex_Types}
3296 under control of the pragma, rather than use the preinstantiated versions.
3299 @node Pragma Favor_Top_Level
3300 @unnumberedsec Pragma Favor_Top_Level
3301 @findex Favor_Top_Level
3305 @smallexample @c ada
3306 pragma Favor_Top_Level (type_NAME);
3310 The named type must be an access-to-subprogram type. This pragma is an
3311 efficiency hint to the compiler, regarding the use of 'Access or
3312 'Unrestricted_Access on nested (non-library-level) subprograms. The
3313 pragma means that nested subprograms are not used with this type, or
3314 are rare, so that the generated code should be efficient in the
3315 top-level case. When this pragma is used, dynamically generated
3316 trampolines may be used on some targets for nested subprograms.
3317 See also the No_Implicit_Dynamic_Code restriction.
3319 @node Pragma Finalize_Storage_Only
3320 @unnumberedsec Pragma Finalize_Storage_Only
3321 @findex Finalize_Storage_Only
3325 @smallexample @c ada
3326 pragma Finalize_Storage_Only (first_subtype_LOCAL_NAME);
3330 This pragma allows the compiler not to emit a Finalize call for objects
3331 defined at the library level. This is mostly useful for types where
3332 finalization is only used to deal with storage reclamation since in most
3333 environments it is not necessary to reclaim memory just before terminating
3334 execution, hence the name.
3336 @node Pragma Float_Representation
3337 @unnumberedsec Pragma Float_Representation
3339 @findex Float_Representation
3343 @smallexample @c ada
3344 pragma Float_Representation (FLOAT_REP[, float_type_LOCAL_NAME]);
3346 FLOAT_REP ::= VAX_Float | IEEE_Float
3350 In the one argument form, this pragma is a configuration pragma which
3351 allows control over the internal representation chosen for the predefined
3352 floating point types declared in the packages @code{Standard} and
3353 @code{System}. On all systems other than OpenVMS, the argument must
3354 be @code{IEEE_Float} and the pragma has no effect. On OpenVMS, the
3355 argument may be @code{VAX_Float} to specify the use of the VAX float
3356 format for the floating-point types in Standard. This requires that
3357 the standard runtime libraries be recompiled.
3359 The two argument form specifies the representation to be used for
3360 the specified floating-point type. On all systems other than OpenVMS,
3362 be @code{IEEE_Float} to specify the use of IEEE format, as follows:
3366 For a digits value of 6, 32-bit IEEE short format will be used.
3368 For a digits value of 15, 64-bit IEEE long format will be used.
3370 No other value of digits is permitted.
3374 argument may be @code{VAX_Float} to specify the use of the VAX float
3379 For digits values up to 6, F float format will be used.
3381 For digits values from 7 to 9, D float format will be used.
3383 For digits values from 10 to 15, G float format will be used.
3385 Digits values above 15 are not allowed.
3389 @unnumberedsec Pragma Global
3392 For the description of this pragma, see SPARK 2014 Reference Manual,
3396 @unnumberedsec Pragma Ident
3401 @smallexample @c ada
3402 pragma Ident (static_string_EXPRESSION);
3406 This pragma is identical in effect to pragma @code{Comment}. It is provided
3407 for compatibility with other Ada compilers providing this pragma.
3409 @node Pragma Implementation_Defined
3410 @unnumberedsec Pragma Implementation_Defined
3411 @findex Implementation_Defined
3415 @smallexample @c ada
3416 pragma Implementation_Defined (local_NAME);
3420 This pragma marks a previously declared entioty as implementation-defined.
3421 For an overloaded entity, applies to the most recent homonym.
3423 @smallexample @c ada
3424 pragma Implementation_Defined;
3428 The form with no arguments appears anywhere within a scope, most
3429 typically a package spec, and indicates that all entities that are
3430 defined within the package spec are Implementation_Defined.
3432 This pragma is used within the GNAT runtime library to identify
3433 implementation-defined entities introduced in language-defined units,
3434 for the purpose of implementing the No_Implementation_Identifiers
3437 @node Pragma Implemented
3438 @unnumberedsec Pragma Implemented
3443 @smallexample @c ada
3444 pragma Implemented (procedure_LOCAL_NAME, implementation_kind);
3446 implementation_kind ::= By_Entry | By_Protected_Procedure | By_Any
3450 This is an Ada 2012 representation pragma which applies to protected, task
3451 and synchronized interface primitives. The use of pragma Implemented provides
3452 a way to impose a static requirement on the overriding operation by adhering
3453 to one of the three implementation kinds: entry, protected procedure or any of
3454 the above. This pragma is available in all earlier versions of Ada as an
3455 implementation-defined pragma.
3457 @smallexample @c ada
3458 type Synch_Iface is synchronized interface;
3459 procedure Prim_Op (Obj : in out Iface) is abstract;
3460 pragma Implemented (Prim_Op, By_Protected_Procedure);
3462 protected type Prot_1 is new Synch_Iface with
3463 procedure Prim_Op; -- Legal
3466 protected type Prot_2 is new Synch_Iface with
3467 entry Prim_Op; -- Illegal
3470 task type Task_Typ is new Synch_Iface with
3471 entry Prim_Op; -- Illegal
3476 When applied to the procedure_or_entry_NAME of a requeue statement, pragma
3477 Implemented determines the runtime behavior of the requeue. Implementation kind
3478 By_Entry guarantees that the action of requeueing will proceed from an entry to
3479 another entry. Implementation kind By_Protected_Procedure transforms the
3480 requeue into a dispatching call, thus eliminating the chance of blocking. Kind
3481 By_Any shares the behavior of By_Entry and By_Protected_Procedure depending on
3482 the target's overriding subprogram kind.
3484 @node Pragma Implicit_Packing
3485 @unnumberedsec Pragma Implicit_Packing
3486 @findex Implicit_Packing
3487 @cindex Rational Profile
3491 @smallexample @c ada
3492 pragma Implicit_Packing;
3496 This is a configuration pragma that requests implicit packing for packed
3497 arrays for which a size clause is given but no explicit pragma Pack or
3498 specification of Component_Size is present. It also applies to records
3499 where no record representation clause is present. Consider this example:
3501 @smallexample @c ada
3502 type R is array (0 .. 7) of Boolean;
3507 In accordance with the recommendation in the RM (RM 13.3(53)), a Size clause
3508 does not change the layout of a composite object. So the Size clause in the
3509 above example is normally rejected, since the default layout of the array uses
3510 8-bit components, and thus the array requires a minimum of 64 bits.
3512 If this declaration is compiled in a region of code covered by an occurrence
3513 of the configuration pragma Implicit_Packing, then the Size clause in this
3514 and similar examples will cause implicit packing and thus be accepted. For
3515 this implicit packing to occur, the type in question must be an array of small
3516 components whose size is known at compile time, and the Size clause must
3517 specify the exact size that corresponds to the number of elements in the array
3518 multiplied by the size in bits of the component type (both single and
3519 multi-dimensioned arrays can be controlled with this pragma).
3521 @cindex Array packing
3523 Similarly, the following example shows the use in the record case
3525 @smallexample @c ada
3527 a, b, c, d, e, f, g, h : boolean;
3534 Without a pragma Pack, each Boolean field requires 8 bits, so the
3535 minimum size is 72 bits, but with a pragma Pack, 16 bits would be
3536 sufficient. The use of pragma Implicit_Packing allows this record
3537 declaration to compile without an explicit pragma Pack.
3538 @node Pragma Import_Exception
3539 @unnumberedsec Pragma Import_Exception
3541 @findex Import_Exception
3545 @smallexample @c ada
3546 pragma Import_Exception (
3547 [Internal =>] LOCAL_NAME
3548 [, [External =>] EXTERNAL_SYMBOL]
3549 [, [Form =>] Ada | VMS]
3550 [, [Code =>] static_integer_EXPRESSION]);
3554 | static_string_EXPRESSION
3558 This pragma is implemented only in the OpenVMS implementation of GNAT@.
3559 It allows OpenVMS conditions (for example, from OpenVMS system services or
3560 other OpenVMS languages) to be propagated to Ada programs as Ada exceptions.
3561 The pragma specifies that the exception associated with an exception
3562 declaration in an Ada program be defined externally (in non-Ada code).
3563 For further details on this pragma, see the
3564 DEC Ada Language Reference Manual, section 13.9a.3.1.
3566 @node Pragma Import_Function
3567 @unnumberedsec Pragma Import_Function
3568 @findex Import_Function
3572 @smallexample @c ada
3573 pragma Import_Function (
3574 [Internal =>] LOCAL_NAME,
3575 [, [External =>] EXTERNAL_SYMBOL]
3576 [, [Parameter_Types =>] PARAMETER_TYPES]
3577 [, [Result_Type =>] SUBTYPE_MARK]
3578 [, [Mechanism =>] MECHANISM]
3579 [, [Result_Mechanism =>] MECHANISM_NAME]);
3583 | static_string_EXPRESSION
3587 | TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@}
3591 | subtype_Name ' Access
3595 | (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@})
3597 MECHANISM_ASSOCIATION ::=
3598 [formal_parameter_NAME =>] MECHANISM_NAME
3606 This pragma is used in conjunction with a pragma @code{Import} to
3607 specify additional information for an imported function. The pragma
3608 @code{Import} (or equivalent pragma @code{Interface}) must precede the
3609 @code{Import_Function} pragma and both must appear in the same
3610 declarative part as the function specification.
3612 The @var{Internal} argument must uniquely designate
3613 the function to which the
3614 pragma applies. If more than one function name exists of this name in
3615 the declarative part you must use the @code{Parameter_Types} and
3616 @var{Result_Type} parameters to achieve the required unique
3617 designation. Subtype marks in these parameters must exactly match the
3618 subtypes in the corresponding function specification, using positional
3619 notation to match parameters with subtype marks.
3620 The form with an @code{'Access} attribute can be used to match an
3621 anonymous access parameter.
3623 You may optionally use the @var{Mechanism} and @var{Result_Mechanism}
3624 parameters to specify passing mechanisms for the
3625 parameters and result. If you specify a single mechanism name, it
3626 applies to all parameters. Otherwise you may specify a mechanism on a
3627 parameter by parameter basis using either positional or named
3628 notation. If the mechanism is not specified, the default mechanism
3631 @node Pragma Import_Object
3632 @unnumberedsec Pragma Import_Object
3633 @findex Import_Object
3637 @smallexample @c ada
3638 pragma Import_Object
3639 [Internal =>] LOCAL_NAME
3640 [, [External =>] EXTERNAL_SYMBOL]
3641 [, [Size =>] EXTERNAL_SYMBOL]);
3645 | static_string_EXPRESSION
3649 This pragma designates an object as imported, and apart from the
3650 extended rules for external symbols, is identical in effect to the use of
3651 the normal @code{Import} pragma applied to an object. Unlike the
3652 subprogram case, you need not use a separate @code{Import} pragma,
3653 although you may do so (and probably should do so from a portability
3654 point of view). @var{size} is syntax checked, but otherwise ignored by
3657 @node Pragma Import_Procedure
3658 @unnumberedsec Pragma Import_Procedure
3659 @findex Import_Procedure
3663 @smallexample @c ada
3664 pragma Import_Procedure (
3665 [Internal =>] LOCAL_NAME
3666 [, [External =>] EXTERNAL_SYMBOL]
3667 [, [Parameter_Types =>] PARAMETER_TYPES]
3668 [, [Mechanism =>] MECHANISM]);
3672 | static_string_EXPRESSION
3676 | TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@}
3680 | subtype_Name ' Access
3684 | (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@})
3686 MECHANISM_ASSOCIATION ::=
3687 [formal_parameter_NAME =>] MECHANISM_NAME
3689 MECHANISM_NAME ::= Value | Reference
3693 This pragma is identical to @code{Import_Function} except that it
3694 applies to a procedure rather than a function and the parameters
3695 @code{Result_Type} and @code{Result_Mechanism} are not permitted.
3697 @node Pragma Import_Valued_Procedure
3698 @unnumberedsec Pragma Import_Valued_Procedure
3699 @findex Import_Valued_Procedure
3703 @smallexample @c ada
3704 pragma Import_Valued_Procedure (
3705 [Internal =>] LOCAL_NAME
3706 [, [External =>] EXTERNAL_SYMBOL]
3707 [, [Parameter_Types =>] PARAMETER_TYPES]
3708 [, [Mechanism =>] MECHANISM]);
3712 | static_string_EXPRESSION
3716 | TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@}
3720 | subtype_Name ' Access
3724 | (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@})
3726 MECHANISM_ASSOCIATION ::=
3727 [formal_parameter_NAME =>] MECHANISM_NAME
3729 MECHANISM_NAME ::= Value | Reference
3733 This pragma is identical to @code{Import_Procedure} except that the
3734 first parameter of @var{LOCAL_NAME}, which must be present, must be of
3735 mode @code{OUT}, and externally the subprogram is treated as a function
3736 with this parameter as the result of the function. The purpose of this
3737 capability is to allow the use of @code{OUT} and @code{IN OUT}
3738 parameters in interfacing to external functions (which are not permitted
3739 in Ada functions). You may optionally use the @code{Mechanism}
3740 parameters to specify passing mechanisms for the parameters.
3741 If you specify a single mechanism name, it applies to all parameters.
3742 Otherwise you may specify a mechanism on a parameter by parameter
3743 basis using either positional or named notation. If the mechanism is not
3744 specified, the default mechanism is used.
3746 Note that it is important to use this pragma in conjunction with a separate
3747 pragma Import that specifies the desired convention, since otherwise the
3748 default convention is Ada, which is almost certainly not what is required.
3750 @node Pragma Independent
3751 @unnumberedsec Pragma Independent
3756 @smallexample @c ada
3757 pragma Independent (Local_NAME);
3761 This pragma is standard in Ada 2012 mode (which also provides an aspect
3762 of the same name). It is also available as an implementation-defined
3763 pragma in all earlier versions. It specifies that the
3764 designated object or all objects of the designated type must be
3765 independently addressable. This means that separate tasks can safely
3766 manipulate such objects. For example, if two components of a record are
3767 independent, then two separate tasks may access these two components.
3769 constraints on the representation of the object (for instance prohibiting
3772 @node Pragma Independent_Components
3773 @unnumberedsec Pragma Independent_Components
3774 @findex Independent_Components
3778 @smallexample @c ada
3779 pragma Independent_Components (Local_NAME);
3783 This pragma is standard in Ada 2012 mode (which also provides an aspect
3784 of the same name). It is also available as an implementation-defined
3785 pragma in all earlier versions. It specifies that the components of the
3786 designated object, or the components of each object of the designated
3788 independently addressable. This means that separate tasks can safely
3789 manipulate separate components in the composite object. This may place
3790 constraints on the representation of the object (for instance prohibiting
3793 @node Pragma Initial_Condition
3794 @unnumberedsec Pragma Initial_Condition
3795 @findex Initial_Condition
3797 For the description of this pragma, see SPARK 2014 Reference Manual,
3800 @node Pragma Initialize_Scalars
3801 @unnumberedsec Pragma Initialize_Scalars
3802 @findex Initialize_Scalars
3803 @cindex debugging with Initialize_Scalars
3807 @smallexample @c ada
3808 pragma Initialize_Scalars;
3812 This pragma is similar to @code{Normalize_Scalars} conceptually but has
3813 two important differences. First, there is no requirement for the pragma
3814 to be used uniformly in all units of a partition, in particular, it is fine
3815 to use this just for some or all of the application units of a partition,
3816 without needing to recompile the run-time library.
3818 In the case where some units are compiled with the pragma, and some without,
3819 then a declaration of a variable where the type is defined in package
3820 Standard or is locally declared will always be subject to initialization,
3821 as will any declaration of a scalar variable. For composite variables,
3822 whether the variable is initialized may also depend on whether the package
3823 in which the type of the variable is declared is compiled with the pragma.
3825 The other important difference is that you can control the value used
3826 for initializing scalar objects. At bind time, you can select several
3827 options for initialization. You can
3828 initialize with invalid values (similar to Normalize_Scalars, though for
3829 Initialize_Scalars it is not always possible to determine the invalid
3830 values in complex cases like signed component fields with non-standard
3831 sizes). You can also initialize with high or
3832 low values, or with a specified bit pattern. See the @value{EDITION}
3833 User's Guide for binder options for specifying these cases.
3835 This means that you can compile a program, and then without having to
3836 recompile the program, you can run it with different values being used
3837 for initializing otherwise uninitialized values, to test if your program
3838 behavior depends on the choice. Of course the behavior should not change,
3839 and if it does, then most likely you have an incorrect reference to an
3840 uninitialized value.
3842 It is even possible to change the value at execution time eliminating even
3843 the need to rebind with a different switch using an environment variable.
3844 See the @value{EDITION} User's Guide for details.
3846 Note that pragma @code{Initialize_Scalars} is particularly useful in
3847 conjunction with the enhanced validity checking that is now provided
3848 in GNAT, which checks for invalid values under more conditions.
3849 Using this feature (see description of the @option{-gnatV} flag in the
3850 @value{EDITION} User's Guide) in conjunction with
3851 pragma @code{Initialize_Scalars}
3852 provides a powerful new tool to assist in the detection of problems
3853 caused by uninitialized variables.
3855 Note: the use of @code{Initialize_Scalars} has a fairly extensive
3856 effect on the generated code. This may cause your code to be
3857 substantially larger. It may also cause an increase in the amount
3858 of stack required, so it is probably a good idea to turn on stack
3859 checking (see description of stack checking in the @value{EDITION}
3860 User's Guide) when using this pragma.
3862 @node Pragma Initializes
3863 @unnumberedsec Pragma Initializes
3866 For the description of this pragma, see SPARK 2014 Reference Manual,
3869 @node Pragma Inline_Always
3870 @unnumberedsec Pragma Inline_Always
3871 @findex Inline_Always
3875 @smallexample @c ada
3876 pragma Inline_Always (NAME [, NAME]);
3880 Similar to pragma @code{Inline} except that inlining is not subject to
3881 the use of option @option{-gnatn} or @option{-gnatN} and the inlining
3882 happens regardless of whether these options are used.
3884 @node Pragma Inline_Generic
3885 @unnumberedsec Pragma Inline_Generic
3886 @findex Inline_Generic
3890 @smallexample @c ada
3891 pragma Inline_Generic (GNAME @{, GNAME@});
3893 GNAME ::= generic_unit_NAME | generic_instance_NAME
3897 This pragma is provided for compatibility with Dec Ada 83. It has
3898 no effect in @code{GNAT} (which always inlines generics), other
3899 than to check that the given names are all names of generic units or
3902 @node Pragma Interface
3903 @unnumberedsec Pragma Interface
3908 @smallexample @c ada
3910 [Convention =>] convention_identifier,
3911 [Entity =>] local_NAME
3912 [, [External_Name =>] static_string_expression]
3913 [, [Link_Name =>] static_string_expression]);
3917 This pragma is identical in syntax and semantics to
3918 the standard Ada pragma @code{Import}. It is provided for compatibility
3919 with Ada 83. The definition is upwards compatible both with pragma
3920 @code{Interface} as defined in the Ada 83 Reference Manual, and also
3921 with some extended implementations of this pragma in certain Ada 83
3922 implementations. The only difference between pragma @code{Interface}
3923 and pragma @code{Import} is that there is special circuitry to allow
3924 both pragmas to appear for the same subprogram entity (normally it
3925 is illegal to have multiple @code{Import} pragmas. This is useful in
3926 maintaining Ada 83/Ada 95 compatibility and is compatible with other
3929 @node Pragma Interface_Name
3930 @unnumberedsec Pragma Interface_Name
3931 @findex Interface_Name
3935 @smallexample @c ada
3936 pragma Interface_Name (
3937 [Entity =>] LOCAL_NAME
3938 [, [External_Name =>] static_string_EXPRESSION]
3939 [, [Link_Name =>] static_string_EXPRESSION]);
3943 This pragma provides an alternative way of specifying the interface name
3944 for an interfaced subprogram, and is provided for compatibility with Ada
3945 83 compilers that use the pragma for this purpose. You must provide at
3946 least one of @var{External_Name} or @var{Link_Name}.
3948 @node Pragma Interrupt_Handler
3949 @unnumberedsec Pragma Interrupt_Handler
3950 @findex Interrupt_Handler
3954 @smallexample @c ada
3955 pragma Interrupt_Handler (procedure_LOCAL_NAME);
3959 This program unit pragma is supported for parameterless protected procedures
3960 as described in Annex C of the Ada Reference Manual. On the AAMP target
3961 the pragma can also be specified for nonprotected parameterless procedures
3962 that are declared at the library level (which includes procedures
3963 declared at the top level of a library package). In the case of AAMP,
3964 when this pragma is applied to a nonprotected procedure, the instruction
3965 @code{IERET} is generated for returns from the procedure, enabling
3966 maskable interrupts, in place of the normal return instruction.
3968 @node Pragma Interrupt_State
3969 @unnumberedsec Pragma Interrupt_State
3970 @findex Interrupt_State
3974 @smallexample @c ada
3975 pragma Interrupt_State
3977 [State =>] SYSTEM | RUNTIME | USER);
3981 Normally certain interrupts are reserved to the implementation. Any attempt
3982 to attach an interrupt causes Program_Error to be raised, as described in
3983 RM C.3.2(22). A typical example is the @code{SIGINT} interrupt used in
3984 many systems for an @kbd{Ctrl-C} interrupt. Normally this interrupt is
3985 reserved to the implementation, so that @kbd{Ctrl-C} can be used to
3986 interrupt execution. Additionally, signals such as @code{SIGSEGV},
3987 @code{SIGABRT}, @code{SIGFPE} and @code{SIGILL} are often mapped to specific
3988 Ada exceptions, or used to implement run-time functions such as the
3989 @code{abort} statement and stack overflow checking.
3991 Pragma @code{Interrupt_State} provides a general mechanism for overriding
3992 such uses of interrupts. It subsumes the functionality of pragma
3993 @code{Unreserve_All_Interrupts}. Pragma @code{Interrupt_State} is not
3994 available on Windows or VMS. On all other platforms than VxWorks,
3995 it applies to signals; on VxWorks, it applies to vectored hardware interrupts
3996 and may be used to mark interrupts required by the board support package
3999 Interrupts can be in one of three states:
4003 The interrupt is reserved (no Ada handler can be installed), and the
4004 Ada run-time may not install a handler. As a result you are guaranteed
4005 standard system default action if this interrupt is raised.
4009 The interrupt is reserved (no Ada handler can be installed). The run time
4010 is allowed to install a handler for internal control purposes, but is
4011 not required to do so.
4015 The interrupt is unreserved. The user may install a handler to provide
4020 These states are the allowed values of the @code{State} parameter of the
4021 pragma. The @code{Name} parameter is a value of the type
4022 @code{Ada.Interrupts.Interrupt_ID}. Typically, it is a name declared in
4023 @code{Ada.Interrupts.Names}.
4025 This is a configuration pragma, and the binder will check that there
4026 are no inconsistencies between different units in a partition in how a
4027 given interrupt is specified. It may appear anywhere a pragma is legal.
4029 The effect is to move the interrupt to the specified state.
4031 By declaring interrupts to be SYSTEM, you guarantee the standard system
4032 action, such as a core dump.
4034 By declaring interrupts to be USER, you guarantee that you can install
4037 Note that certain signals on many operating systems cannot be caught and
4038 handled by applications. In such cases, the pragma is ignored. See the
4039 operating system documentation, or the value of the array @code{Reserved}
4040 declared in the spec of package @code{System.OS_Interface}.
4042 Overriding the default state of signals used by the Ada runtime may interfere
4043 with an application's runtime behavior in the cases of the synchronous signals,
4044 and in the case of the signal used to implement the @code{abort} statement.
4046 @node Pragma Invariant
4047 @unnumberedsec Pragma Invariant
4052 @smallexample @c ada
4054 ([Entity =>] private_type_LOCAL_NAME,
4055 [Check =>] EXPRESSION
4056 [,[Message =>] String_Expression]);
4060 This pragma provides exactly the same capabilities as the Type_Invariant aspect
4061 defined in AI05-0146-1, and in the Ada 2012 Reference Manual. The
4062 Type_Invariant aspect is fully implemented in Ada 2012 mode, but since it
4063 requires the use of the aspect syntax, which is not available except in 2012
4064 mode, it is not possible to use the Type_Invariant aspect in earlier versions
4065 of Ada. However the Invariant pragma may be used in any version of Ada. Also
4066 note that the aspect Invariant is a synonym in GNAT for the aspect
4067 Type_Invariant, but there is no pragma Type_Invariant.
4069 The pragma must appear within the visible part of the package specification,
4070 after the type to which its Entity argument appears. As with the Invariant
4071 aspect, the Check expression is not analyzed until the end of the visible
4072 part of the package, so it may contain forward references. The Message
4073 argument, if present, provides the exception message used if the invariant
4074 is violated. If no Message parameter is provided, a default message that
4075 identifies the line on which the pragma appears is used.
4077 It is permissible to have multiple Invariants for the same type entity, in
4078 which case they are and'ed together. It is permissible to use this pragma
4079 in Ada 2012 mode, but you cannot have both an invariant aspect and an
4080 invariant pragma for the same entity.
4082 For further details on the use of this pragma, see the Ada 2012 documentation
4083 of the Type_Invariant aspect.
4085 @node Pragma Java_Constructor
4086 @unnumberedsec Pragma Java_Constructor
4087 @findex Java_Constructor
4091 @smallexample @c ada
4092 pragma Java_Constructor ([Entity =>] function_LOCAL_NAME);
4096 This pragma is used to assert that the specified Ada function should be
4097 mapped to the Java constructor for some Ada tagged record type.
4099 See section 7.3.2 of the
4100 @code{GNAT User's Guide: Supplement for the JVM Platform.}
4101 for related information.
4103 @node Pragma Java_Interface
4104 @unnumberedsec Pragma Java_Interface
4105 @findex Java_Interface
4109 @smallexample @c ada
4110 pragma Java_Interface ([Entity =>] abstract_tagged_type_LOCAL_NAME);
4114 This pragma is used to assert that the specified Ada abstract tagged type
4115 is to be mapped to a Java interface name.
4117 See sections 7.1 and 7.2 of the
4118 @code{GNAT User's Guide: Supplement for the JVM Platform.}
4119 for related information.
4121 @node Pragma Keep_Names
4122 @unnumberedsec Pragma Keep_Names
4127 @smallexample @c ada
4128 pragma Keep_Names ([On =>] enumeration_first_subtype_LOCAL_NAME);
4132 The @var{LOCAL_NAME} argument
4133 must refer to an enumeration first subtype
4134 in the current declarative part. The effect is to retain the enumeration
4135 literal names for use by @code{Image} and @code{Value} even if a global
4136 @code{Discard_Names} pragma applies. This is useful when you want to
4137 generally suppress enumeration literal names and for example you therefore
4138 use a @code{Discard_Names} pragma in the @file{gnat.adc} file, but you
4139 want to retain the names for specific enumeration types.
4141 @node Pragma License
4142 @unnumberedsec Pragma License
4144 @cindex License checking
4148 @smallexample @c ada
4149 pragma License (Unrestricted | GPL | Modified_GPL | Restricted);
4153 This pragma is provided to allow automated checking for appropriate license
4154 conditions with respect to the standard and modified GPL@. A pragma
4155 @code{License}, which is a configuration pragma that typically appears at
4156 the start of a source file or in a separate @file{gnat.adc} file, specifies
4157 the licensing conditions of a unit as follows:
4161 This is used for a unit that can be freely used with no license restrictions.
4162 Examples of such units are public domain units, and units from the Ada
4166 This is used for a unit that is licensed under the unmodified GPL, and which
4167 therefore cannot be @code{with}'ed by a restricted unit.
4170 This is used for a unit licensed under the GNAT modified GPL that includes
4171 a special exception paragraph that specifically permits the inclusion of
4172 the unit in programs without requiring the entire program to be released
4176 This is used for a unit that is restricted in that it is not permitted to
4177 depend on units that are licensed under the GPL@. Typical examples are
4178 proprietary code that is to be released under more restrictive license
4179 conditions. Note that restricted units are permitted to @code{with} units
4180 which are licensed under the modified GPL (this is the whole point of the
4186 Normally a unit with no @code{License} pragma is considered to have an
4187 unknown license, and no checking is done. However, standard GNAT headers
4188 are recognized, and license information is derived from them as follows.
4190 A GNAT license header starts with a line containing 78 hyphens. The following
4191 comment text is searched for the appearance of any of the following strings.
4193 If the string ``GNU General Public License'' is found, then the unit is assumed
4194 to have GPL license, unless the string ``As a special exception'' follows, in
4195 which case the license is assumed to be modified GPL@.
4197 If one of the strings
4198 ``This specification is adapted from the Ada Semantic Interface'' or
4199 ``This specification is derived from the Ada Reference Manual'' is found
4200 then the unit is assumed to be unrestricted.
4203 These default actions means that a program with a restricted license pragma
4204 will automatically get warnings if a GPL unit is inappropriately
4205 @code{with}'ed. For example, the program:
4207 @smallexample @c ada
4210 procedure Secret_Stuff is
4216 if compiled with pragma @code{License} (@code{Restricted}) in a
4217 @file{gnat.adc} file will generate the warning:
4222 >>> license of withed unit "Sem_Ch3" is incompatible
4224 2. with GNAT.Sockets;
4225 3. procedure Secret_Stuff is
4229 Here we get a warning on @code{Sem_Ch3} since it is part of the GNAT
4230 compiler and is licensed under the
4231 GPL, but no warning for @code{GNAT.Sockets} which is part of the GNAT
4232 run time, and is therefore licensed under the modified GPL@.
4234 @node Pragma Link_With
4235 @unnumberedsec Pragma Link_With
4240 @smallexample @c ada
4241 pragma Link_With (static_string_EXPRESSION @{,static_string_EXPRESSION@});
4245 This pragma is provided for compatibility with certain Ada 83 compilers.
4246 It has exactly the same effect as pragma @code{Linker_Options} except
4247 that spaces occurring within one of the string expressions are treated
4248 as separators. For example, in the following case:
4250 @smallexample @c ada
4251 pragma Link_With ("-labc -ldef");
4255 results in passing the strings @code{-labc} and @code{-ldef} as two
4256 separate arguments to the linker. In addition pragma Link_With allows
4257 multiple arguments, with the same effect as successive pragmas.
4259 @node Pragma Linker_Alias
4260 @unnumberedsec Pragma Linker_Alias
4261 @findex Linker_Alias
4265 @smallexample @c ada
4266 pragma Linker_Alias (
4267 [Entity =>] LOCAL_NAME,
4268 [Target =>] static_string_EXPRESSION);
4272 @var{LOCAL_NAME} must refer to an object that is declared at the library
4273 level. This pragma establishes the given entity as a linker alias for the
4274 given target. It is equivalent to @code{__attribute__((alias))} in GNU C
4275 and causes @var{LOCAL_NAME} to be emitted as an alias for the symbol
4276 @var{static_string_EXPRESSION} in the object file, that is to say no space
4277 is reserved for @var{LOCAL_NAME} by the assembler and it will be resolved
4278 to the same address as @var{static_string_EXPRESSION} by the linker.
4280 The actual linker name for the target must be used (e.g.@: the fully
4281 encoded name with qualification in Ada, or the mangled name in C++),
4282 or it must be declared using the C convention with @code{pragma Import}
4283 or @code{pragma Export}.
4285 Not all target machines support this pragma. On some of them it is accepted
4286 only if @code{pragma Weak_External} has been applied to @var{LOCAL_NAME}.
4288 @smallexample @c ada
4289 -- Example of the use of pragma Linker_Alias
4293 pragma Export (C, i);
4295 new_name_for_i : Integer;
4296 pragma Linker_Alias (new_name_for_i, "i");
4300 @node Pragma Linker_Constructor
4301 @unnumberedsec Pragma Linker_Constructor
4302 @findex Linker_Constructor
4306 @smallexample @c ada
4307 pragma Linker_Constructor (procedure_LOCAL_NAME);
4311 @var{procedure_LOCAL_NAME} must refer to a parameterless procedure that
4312 is declared at the library level. A procedure to which this pragma is
4313 applied will be treated as an initialization routine by the linker.
4314 It is equivalent to @code{__attribute__((constructor))} in GNU C and
4315 causes @var{procedure_LOCAL_NAME} to be invoked before the entry point
4316 of the executable is called (or immediately after the shared library is
4317 loaded if the procedure is linked in a shared library), in particular
4318 before the Ada run-time environment is set up.
4320 Because of these specific contexts, the set of operations such a procedure
4321 can perform is very limited and the type of objects it can manipulate is
4322 essentially restricted to the elementary types. In particular, it must only
4323 contain code to which pragma Restrictions (No_Elaboration_Code) applies.
4325 This pragma is used by GNAT to implement auto-initialization of shared Stand
4326 Alone Libraries, which provides a related capability without the restrictions
4327 listed above. Where possible, the use of Stand Alone Libraries is preferable
4328 to the use of this pragma.
4330 @node Pragma Linker_Destructor
4331 @unnumberedsec Pragma Linker_Destructor
4332 @findex Linker_Destructor
4336 @smallexample @c ada
4337 pragma Linker_Destructor (procedure_LOCAL_NAME);
4341 @var{procedure_LOCAL_NAME} must refer to a parameterless procedure that
4342 is declared at the library level. A procedure to which this pragma is
4343 applied will be treated as a finalization routine by the linker.
4344 It is equivalent to @code{__attribute__((destructor))} in GNU C and
4345 causes @var{procedure_LOCAL_NAME} to be invoked after the entry point
4346 of the executable has exited (or immediately before the shared library
4347 is unloaded if the procedure is linked in a shared library), in particular
4348 after the Ada run-time environment is shut down.
4350 See @code{pragma Linker_Constructor} for the set of restrictions that apply
4351 because of these specific contexts.
4353 @node Pragma Linker_Section
4354 @unnumberedsec Pragma Linker_Section
4355 @findex Linker_Section
4359 @smallexample @c ada
4360 pragma Linker_Section (
4361 [Entity =>] LOCAL_NAME,
4362 [Section =>] static_string_EXPRESSION);
4366 @var{LOCAL_NAME} must refer to an object, type, or subprogram that is
4367 declared at the library level. This pragma specifies the name of the
4368 linker section for the given entity. It is equivalent to
4369 @code{__attribute__((section))} in GNU C and causes @var{LOCAL_NAME} to
4370 be placed in the @var{static_string_EXPRESSION} section of the
4371 executable (assuming the linker doesn't rename the section).
4372 GNAT also provides an implementation defined aspect of the same name.
4374 In the case of specifying this aspect for a type, the effect is to
4375 specify the corresponding for all library level objects of the type which
4376 do not have an explicit linker section set. Note that this only applies to
4377 whole objects, not to components of composite objects.
4379 In the case of a subprogram, the linker section applies to all previously
4380 declared matching overloaded subprograms in the current declarative part
4381 which do not already have a linker section assigned. The linker section
4382 aspect is useful in this case for specifying different linker sections
4383 for different elements of such an overloaded set.
4385 Note that an empty string specifies that no linker section is specified.
4386 This is not quite the same as omitting the pragma or aspect, since it
4387 can be used to specify that one element of an overloaded set of subprograms
4388 has the default linker section, or that one object of a type for which a
4389 linker section is specified should has the default linker section.
4391 The compiler normally places library-level entities in standard sections
4392 depending on the class: procedures and functions generally go in the
4393 @code{.text} section, initialized variables in the @code{.data} section
4394 and uninitialized variables in the @code{.bss} section.
4396 Other, special sections may exist on given target machines to map special
4397 hardware, for example I/O ports or flash memory. This pragma is a means to
4398 defer the final layout of the executable to the linker, thus fully working
4399 at the symbolic level with the compiler.
4401 Some file formats do not support arbitrary sections so not all target
4402 machines support this pragma. The use of this pragma may cause a program
4403 execution to be erroneous if it is used to place an entity into an
4404 inappropriate section (e.g.@: a modified variable into the @code{.text}
4405 section). See also @code{pragma Persistent_BSS}.
4407 @smallexample @c ada
4408 -- Example of the use of pragma Linker_Section
4412 pragma Volatile (Port_A);
4413 pragma Linker_Section (Port_A, ".bss.port_a");
4416 pragma Volatile (Port_B);
4417 pragma Linker_Section (Port_B, ".bss.port_b");
4419 type Port_Type is new Integer with Linker_Section => ".bss";
4420 PA : Port_Type with Linker_Section => ".bss.PA";
4421 PB : Port_Type; -- ends up in linker section ".bss"
4423 procedure Q with Linker_Section => "Qsection";
4427 @node Pragma Lock_Free
4428 @unnumberedsec Pragma Lock_Free
4432 This pragma may be specified for protected types or objects. It specifies that
4433 the implementation of protected operations must be implemented without locks.
4434 Compilation fails if the compiler cannot generate lock-free code for the
4437 @node Pragma Long_Float
4438 @unnumberedsec Pragma Long_Float
4444 @smallexample @c ada
4445 pragma Long_Float (FLOAT_FORMAT);
4447 FLOAT_FORMAT ::= D_Float | G_Float
4451 This pragma is implemented only in the OpenVMS implementation of GNAT@.
4452 It allows control over the internal representation chosen for the predefined
4453 type @code{Long_Float} and for floating point type representations with
4454 @code{digits} specified in the range 7 through 15.
4455 For further details on this pragma, see the
4456 @cite{DEC Ada Language Reference Manual}, section 3.5.7b. Note that to use
4457 this pragma, the standard runtime libraries must be recompiled.
4459 @node Pragma Loop_Invariant
4460 @unnumberedsec Pragma Loop_Invariant
4461 @findex Loop_Invariant
4465 @smallexample @c ada
4466 pragma Loop_Invariant ( boolean_EXPRESSION );
4470 The effect of this pragma is similar to that of pragma @code{Assert},
4471 except that in an @code{Assertion_Policy} pragma, the identifier
4472 @code{Loop_Invariant} is used to control whether it is ignored or checked
4475 @code{Loop_Invariant} can only appear as one of the items in the sequence
4476 of statements of a loop body, or nested inside block statements that
4477 appear in the sequence of statements of a loop body.
4478 The intention is that it be used to
4479 represent a "loop invariant" assertion, i.e. something that is true each
4480 time through the loop, and which can be used to show that the loop is
4481 achieving its purpose.
4483 Multiple @code{Loop_Invariant} and @code{Loop_Variant} pragmas that
4484 apply to the same loop should be grouped in the same sequence of
4487 To aid in writing such invariants, the special attribute @code{Loop_Entry}
4488 may be used to refer to the value of an expression on entry to the loop. This
4489 attribute can only be used within the expression of a @code{Loop_Invariant}
4490 pragma. For full details, see documentation of attribute @code{Loop_Entry}.
4492 @node Pragma Loop_Optimize
4493 @unnumberedsec Pragma Loop_Optimize
4494 @findex Loop_Optimize
4498 @smallexample @c ada
4499 pragma Loop_Optimize (OPTIMIZATION_HINT @{, OPTIMIZATION_HINT@});
4501 OPTIMIZATION_HINT ::= Ivdep | No_Unroll | Unroll | No_Vector | Vector
4505 This pragma must appear immediately within a loop statement. It allows the
4506 programmer to specify optimization hints for the enclosing loop. The hints
4507 are not mutually exclusive and can be freely mixed, but not all combinations
4508 will yield a sensible outcome.
4510 There are five supported optimization hints for a loop:
4515 The programmer asserts that there are no loop-carried dependencies
4516 which would prevent consecutive iterations of the loop from being
4517 executed simultaneously.
4521 The loop must not be unrolled. This is a strong hint: the compiler will not
4522 unroll a loop marked with this hint.
4526 The loop should be unrolled. This is a weak hint: the compiler will try to
4527 apply unrolling to this loop preferably to other optimizations, notably
4528 vectorization, but there is no guarantee that the loop will be unrolled.
4532 The loop must not be vectorized. This is a strong hint: the compiler will not
4533 vectorize a loop marked with this hint.
4537 The loop should be vectorized. This is a weak hint: the compiler will try to
4538 apply vectorization to this loop preferably to other optimizations, notably
4539 unrolling, but there is no guarantee that the loop will be vectorized.
4543 These hints do not remove the need to pass the appropriate switches to the
4544 compiler in order to enable the relevant optimizations, that is to say
4545 @option{-funroll-loops} for unrolling and @option{-ftree-vectorize} for
4548 @node Pragma Loop_Variant
4549 @unnumberedsec Pragma Loop_Variant
4550 @findex Loop_Variant
4554 @smallexample @c ada
4555 pragma Loop_Variant ( LOOP_VARIANT_ITEM @{, LOOP_VARIANT_ITEM @} );
4556 LOOP_VARIANT_ITEM ::= CHANGE_DIRECTION => discrete_EXPRESSION
4557 CHANGE_DIRECTION ::= Increases | Decreases
4561 @code{Loop_Variant} can only appear as one of the items in the sequence
4562 of statements of a loop body, or nested inside block statements that
4563 appear in the sequence of statements of a loop body.
4564 It allows the specification of quantities which must always
4565 decrease or increase in successive iterations of the loop. In its simplest
4566 form, just one expression is specified, whose value must increase or decrease
4567 on each iteration of the loop.
4569 In a more complex form, multiple arguments can be given which are intepreted
4570 in a nesting lexicographic manner. For example:
4572 @smallexample @c ada
4573 pragma Loop_Variant (Increases => X, Decreases => Y);
4577 specifies that each time through the loop either X increases, or X stays
4578 the same and Y decreases. A @code{Loop_Variant} pragma ensures that the
4579 loop is making progress. It can be useful in helping to show informally
4580 or prove formally that the loop always terminates.
4582 @code{Loop_Variant} is an assertion whose effect can be controlled using
4583 an @code{Assertion_Policy} with a check name of @code{Loop_Variant}. The
4584 policy can be @code{Check} to enable the loop variant check, @code{Ignore}
4585 to ignore the check (in which case the pragma has no effect on the program),
4586 or @code{Disable} in which case the pragma is not even checked for correct
4589 Multiple @code{Loop_Invariant} and @code{Loop_Variant} pragmas that
4590 apply to the same loop should be grouped in the same sequence of
4593 The @code{Loop_Entry} attribute may be used within the expressions of the
4594 @code{Loop_Variant} pragma to refer to values on entry to the loop.
4596 @node Pragma Machine_Attribute
4597 @unnumberedsec Pragma Machine_Attribute
4598 @findex Machine_Attribute
4602 @smallexample @c ada
4603 pragma Machine_Attribute (
4604 [Entity =>] LOCAL_NAME,
4605 [Attribute_Name =>] static_string_EXPRESSION
4606 [, [Info =>] static_EXPRESSION] );
4610 Machine-dependent attributes can be specified for types and/or
4611 declarations. This pragma is semantically equivalent to
4612 @code{__attribute__((@var{attribute_name}))} (if @var{info} is not
4613 specified) or @code{__attribute__((@var{attribute_name}(@var{info})))}
4614 in GNU C, where @code{@var{attribute_name}} is recognized by the
4615 compiler middle-end or the @code{TARGET_ATTRIBUTE_TABLE} machine
4616 specific macro. A string literal for the optional parameter @var{info}
4617 is transformed into an identifier, which may make this pragma unusable
4618 for some attributes. @xref{Target Attributes,, Defining target-specific
4619 uses of @code{__attribute__}, gccint, GNU Compiler Collection (GCC)
4620 Internals}, further information.
4623 @unnumberedsec Pragma Main
4629 @smallexample @c ada
4631 (MAIN_OPTION [, MAIN_OPTION]);
4634 [Stack_Size =>] static_integer_EXPRESSION
4635 | [Task_Stack_Size_Default =>] static_integer_EXPRESSION
4636 | [Time_Slicing_Enabled =>] static_boolean_EXPRESSION
4640 This pragma is provided for compatibility with OpenVMS VAX Systems. It has
4641 no effect in GNAT, other than being syntax checked.
4643 @node Pragma Main_Storage
4644 @unnumberedsec Pragma Main_Storage
4646 @findex Main_Storage
4650 @smallexample @c ada
4652 (MAIN_STORAGE_OPTION [, MAIN_STORAGE_OPTION]);
4654 MAIN_STORAGE_OPTION ::=
4655 [WORKING_STORAGE =>] static_SIMPLE_EXPRESSION
4656 | [TOP_GUARD =>] static_SIMPLE_EXPRESSION
4660 This pragma is provided for compatibility with OpenVMS VAX Systems. It has
4661 no effect in GNAT, other than being syntax checked. Note that the pragma
4662 also has no effect in DEC Ada 83 for OpenVMS Alpha Systems.
4664 @node Pragma No_Body
4665 @unnumberedsec Pragma No_Body
4670 @smallexample @c ada
4675 There are a number of cases in which a package spec does not require a body,
4676 and in fact a body is not permitted. GNAT will not permit the spec to be
4677 compiled if there is a body around. The pragma No_Body allows you to provide
4678 a body file, even in a case where no body is allowed. The body file must
4679 contain only comments and a single No_Body pragma. This is recognized by
4680 the compiler as indicating that no body is logically present.
4682 This is particularly useful during maintenance when a package is modified in
4683 such a way that a body needed before is no longer needed. The provision of a
4684 dummy body with a No_Body pragma ensures that there is no interference from
4685 earlier versions of the package body.
4687 @node Pragma No_Elaboration_Code_All
4688 @unnumberedsec Pragma No_Elaboration_Code_All
4689 @findex No_Elaboration_Code_All
4693 @smallexample @c ada
4694 pragma No_Elaboration_Code_All [(program_unit_NAME)];
4698 This is a program unit pragma (there is also an equivalent aspect of the
4699 same name) that establishes the restriction @code{No_Elaboration_Code} for
4700 the current unit and any extended main source units (body and subunits.
4701 It also has has the effect of enforcing a transitive application of this
4702 aspect, so that if any unit is implicitly or explicitly WITH'ed by the
4703 current unit, it must also have the No_Elaboration_Code_All aspect set.
4704 It may be applied to package or subprogram specs or their generic versions.
4706 @node Pragma No_Inline
4707 @unnumberedsec Pragma No_Inline
4712 @smallexample @c ada
4713 pragma No_Inline (NAME @{, NAME@});
4717 This pragma suppresses inlining for the callable entity or the instances of
4718 the generic subprogram designated by @var{NAME}, including inlining that
4719 results from the use of pragma @code{Inline}. This pragma is always active,
4720 in particular it is not subject to the use of option @option{-gnatn} or
4721 @option{-gnatN}. It is illegal to specify both pragma @code{No_Inline} and
4722 pragma @code{Inline_Always} for the same @var{NAME}.
4724 @node Pragma No_Return
4725 @unnumberedsec Pragma No_Return
4730 @smallexample @c ada
4731 pragma No_Return (procedure_LOCAL_NAME @{, procedure_LOCAL_NAME@});
4735 Each @var{procedure_LOCAL_NAME} argument must refer to one or more procedure
4736 declarations in the current declarative part. A procedure to which this
4737 pragma is applied may not contain any explicit @code{return} statements.
4738 In addition, if the procedure contains any implicit returns from falling
4739 off the end of a statement sequence, then execution of that implicit
4740 return will cause Program_Error to be raised.
4742 One use of this pragma is to identify procedures whose only purpose is to raise
4743 an exception. Another use of this pragma is to suppress incorrect warnings
4744 about missing returns in functions, where the last statement of a function
4745 statement sequence is a call to such a procedure.
4747 Note that in Ada 2005 mode, this pragma is part of the language. It is
4748 available in all earlier versions of Ada as an implementation-defined
4751 @node Pragma No_Run_Time
4752 @unnumberedsec Pragma No_Run_Time
4757 @smallexample @c ada
4762 This is an obsolete configuration pragma that historically was used to
4763 set up a runtime library with no object code. It is now used only for
4764 internal testing. The pragma has been superseded by the reconfigurable
4765 runtime capability of @code{GNAT}.
4767 @node Pragma No_Strict_Aliasing
4768 @unnumberedsec Pragma No_Strict_Aliasing
4769 @findex No_Strict_Aliasing
4773 @smallexample @c ada
4774 pragma No_Strict_Aliasing [([Entity =>] type_LOCAL_NAME)];
4778 @var{type_LOCAL_NAME} must refer to an access type
4779 declaration in the current declarative part. The effect is to inhibit
4780 strict aliasing optimization for the given type. The form with no
4781 arguments is a configuration pragma which applies to all access types
4782 declared in units to which the pragma applies. For a detailed
4783 description of the strict aliasing optimization, and the situations
4784 in which it must be suppressed, see @ref{Optimization and Strict
4785 Aliasing,,, gnat_ugn, @value{EDITION} User's Guide}.
4787 This pragma currently has no effects on access to unconstrained array types.
4789 @node Pragma No_Tagged_Streams
4790 @unnumberedsec Pragma No_Tagged_Streams
4791 @findex No_Tagged_Streams
4795 @smallexample @c ada
4796 pragma No_Tagged_Streams;
4797 pragma No_Tagged_Streams [([Entity =>] tagged_type_LOCAL_NAME)];
4801 Normally when a tagged type is introduced using a full type declaration,
4802 part of the processing includes generating stream access routines to be
4803 used by stream attributes referencing the type (or one of its subtypes
4804 or derived types). This can involve the generation of significant amounts
4805 of code which is wasted space if stream routines are not needed for the
4808 The @code{No_Tagged_Streams} pragma causes the generation of these stream
4809 routines to be skipped, and any attempt to use stream operations on
4810 types subject to this pragma will be statically rejected as illegal.
4812 There are two forms of the pragma. The form with no arguments must appear
4813 in a declarative sequence or in the declarations of a package spec. This
4814 pragma affects all subsequent root tagged types declared in the declaration
4815 sequence, and specifies that no stream routines be generated. The form with
4816 an argument (for which there is also a corresponding aspect) specifies a
4817 single root tagged type for which stream routines are not to be generated.
4819 Once the pragma has been given for a particular root tagged type, all subtypes
4820 and derived types of this type inherit the pragma automatically, so the effect
4821 applies to a complete hierarchy (this is necessary to deal with the class-wide
4822 dispatching versions of the stream routines).
4824 @node Pragma Normalize_Scalars
4825 @unnumberedsec Pragma Normalize_Scalars
4826 @findex Normalize_Scalars
4830 @smallexample @c ada
4831 pragma Normalize_Scalars;
4835 This is a language defined pragma which is fully implemented in GNAT@. The
4836 effect is to cause all scalar objects that are not otherwise initialized
4837 to be initialized. The initial values are implementation dependent and
4841 @item Standard.Character
4843 Objects whose root type is Standard.Character are initialized to
4844 Character'Last unless the subtype range excludes NUL (in which case
4845 NUL is used). This choice will always generate an invalid value if
4848 @item Standard.Wide_Character
4850 Objects whose root type is Standard.Wide_Character are initialized to
4851 Wide_Character'Last unless the subtype range excludes NUL (in which case
4852 NUL is used). This choice will always generate an invalid value if
4855 @item Standard.Wide_Wide_Character
4857 Objects whose root type is Standard.Wide_Wide_Character are initialized to
4858 the invalid value 16#FFFF_FFFF# unless the subtype range excludes NUL (in
4859 which case NUL is used). This choice will always generate an invalid value if
4864 Objects of an integer type are treated differently depending on whether
4865 negative values are present in the subtype. If no negative values are
4866 present, then all one bits is used as the initial value except in the
4867 special case where zero is excluded from the subtype, in which case
4868 all zero bits are used. This choice will always generate an invalid
4869 value if one exists.
4871 For subtypes with negative values present, the largest negative number
4872 is used, except in the unusual case where this largest negative number
4873 is in the subtype, and the largest positive number is not, in which case
4874 the largest positive value is used. This choice will always generate
4875 an invalid value if one exists.
4877 @item Floating-Point Types
4878 Objects of all floating-point types are initialized to all 1-bits. For
4879 standard IEEE format, this corresponds to a NaN (not a number) which is
4880 indeed an invalid value.
4882 @item Fixed-Point Types
4883 Objects of all fixed-point types are treated as described above for integers,
4884 with the rules applying to the underlying integer value used to represent
4885 the fixed-point value.
4888 Objects of a modular type are initialized to all one bits, except in
4889 the special case where zero is excluded from the subtype, in which
4890 case all zero bits are used. This choice will always generate an
4891 invalid value if one exists.
4893 @item Enumeration types
4894 Objects of an enumeration type are initialized to all one-bits, i.e.@: to
4895 the value @code{2 ** typ'Size - 1} unless the subtype excludes the literal
4896 whose Pos value is zero, in which case a code of zero is used. This choice
4897 will always generate an invalid value if one exists.
4901 @node Pragma Obsolescent
4902 @unnumberedsec Pragma Obsolescent
4907 @smallexample @c ada
4910 pragma Obsolescent (
4911 [Message =>] static_string_EXPRESSION
4912 [,[Version =>] Ada_05]]);
4914 pragma Obsolescent (
4916 [,[Message =>] static_string_EXPRESSION
4917 [,[Version =>] Ada_05]] );
4921 This pragma can occur immediately following a declaration of an entity,
4922 including the case of a record component. If no Entity argument is present,
4923 then this declaration is the one to which the pragma applies. If an Entity
4924 parameter is present, it must either match the name of the entity in this
4925 declaration, or alternatively, the pragma can immediately follow an enumeration
4926 type declaration, where the Entity argument names one of the enumeration
4929 This pragma is used to indicate that the named entity
4930 is considered obsolescent and should not be used. Typically this is
4931 used when an API must be modified by eventually removing or modifying
4932 existing subprograms or other entities. The pragma can be used at an
4933 intermediate stage when the entity is still present, but will be
4936 The effect of this pragma is to output a warning message on a reference to
4937 an entity thus marked that the subprogram is obsolescent if the appropriate
4938 warning option in the compiler is activated. If the Message parameter is
4939 present, then a second warning message is given containing this text. In
4940 addition, a reference to the entity is considered to be a violation of pragma
4941 Restrictions (No_Obsolescent_Features).
4943 This pragma can also be used as a program unit pragma for a package,
4944 in which case the entity name is the name of the package, and the
4945 pragma indicates that the entire package is considered
4946 obsolescent. In this case a client @code{with}'ing such a package
4947 violates the restriction, and the @code{with} statement is
4948 flagged with warnings if the warning option is set.
4950 If the Version parameter is present (which must be exactly
4951 the identifier Ada_05, no other argument is allowed), then the
4952 indication of obsolescence applies only when compiling in Ada 2005
4953 mode. This is primarily intended for dealing with the situations
4954 in the predefined library where subprograms or packages
4955 have become defined as obsolescent in Ada 2005
4956 (e.g.@: in Ada.Characters.Handling), but may be used anywhere.
4958 The following examples show typical uses of this pragma:
4960 @smallexample @c ada
4962 pragma Obsolescent (p, Message => "use pp instead of p");
4967 pragma Obsolescent ("use q2new instead");
4969 type R is new integer;
4972 Message => "use RR in Ada 2005",
4982 type E is (a, bc, 'd', quack);
4983 pragma Obsolescent (Entity => bc)
4984 pragma Obsolescent (Entity => 'd')
4987 (a, b : character) return character;
4988 pragma Obsolescent (Entity => "+");
4993 Note that, as for all pragmas, if you use a pragma argument identifier,
4994 then all subsequent parameters must also use a pragma argument identifier.
4995 So if you specify "Entity =>" for the Entity argument, and a Message
4996 argument is present, it must be preceded by "Message =>".
4998 @node Pragma Optimize_Alignment
4999 @unnumberedsec Pragma Optimize_Alignment
5000 @findex Optimize_Alignment
5001 @cindex Alignment, default settings
5005 @smallexample @c ada
5006 pragma Optimize_Alignment (TIME | SPACE | OFF);
5010 This is a configuration pragma which affects the choice of default alignments
5011 for types and objects where no alignment is explicitly specified. There is a
5012 time/space trade-off in the selection of these values. Large alignments result
5013 in more efficient code, at the expense of larger data space, since sizes have
5014 to be increased to match these alignments. Smaller alignments save space, but
5015 the access code is slower. The normal choice of default alignments for types
5016 and individual alignment promotions for objects (which is what you get if you
5017 do not use this pragma, or if you use an argument of OFF), tries to balance
5018 these two requirements.
5020 Specifying SPACE causes smaller default alignments to be chosen in two cases.
5021 First any packed record is given an alignment of 1. Second, if a size is given
5022 for the type, then the alignment is chosen to avoid increasing this size. For
5025 @smallexample @c ada
5035 In the default mode, this type gets an alignment of 4, so that access to the
5036 Integer field X are efficient. But this means that objects of the type end up
5037 with a size of 8 bytes. This is a valid choice, since sizes of objects are
5038 allowed to be bigger than the size of the type, but it can waste space if for
5039 example fields of type R appear in an enclosing record. If the above type is
5040 compiled in @code{Optimize_Alignment (Space)} mode, the alignment is set to 1.
5042 However, there is one case in which SPACE is ignored. If a variable length
5043 record (that is a discriminated record with a component which is an array
5044 whose length depends on a discriminant), has a pragma Pack, then it is not
5045 in general possible to set the alignment of such a record to one, so the
5046 pragma is ignored in this case (with a warning).
5048 Specifying SPACE also disables alignment promotions for standalone objects,
5049 which occur when the compiler increases the alignment of a specific object
5050 without changing the alignment of its type.
5052 Specifying TIME causes larger default alignments to be chosen in the case of
5053 small types with sizes that are not a power of 2. For example, consider:
5055 @smallexample @c ada
5067 The default alignment for this record is normally 1, but if this type is
5068 compiled in @code{Optimize_Alignment (Time)} mode, then the alignment is set
5069 to 4, which wastes space for objects of the type, since they are now 4 bytes
5070 long, but results in more efficient access when the whole record is referenced.
5072 As noted above, this is a configuration pragma, and there is a requirement
5073 that all units in a partition be compiled with a consistent setting of the
5074 optimization setting. This would normally be achieved by use of a configuration
5075 pragma file containing the appropriate setting. The exception to this rule is
5076 that units with an explicit configuration pragma in the same file as the source
5077 unit are excluded from the consistency check, as are all predefined units. The
5078 latter are compiled by default in pragma Optimize_Alignment (Off) mode if no
5079 pragma appears at the start of the file.
5081 @node Pragma Ordered
5082 @unnumberedsec Pragma Ordered
5084 @findex pragma @code{Ordered}
5088 @smallexample @c ada
5089 pragma Ordered (enumeration_first_subtype_LOCAL_NAME);
5093 Most enumeration types are from a conceptual point of view unordered.
5094 For example, consider:
5096 @smallexample @c ada
5097 type Color is (Red, Blue, Green, Yellow);
5101 By Ada semantics @code{Blue > Red} and @code{Green > Blue},
5102 but really these relations make no sense; the enumeration type merely
5103 specifies a set of possible colors, and the order is unimportant.
5105 For unordered enumeration types, it is generally a good idea if
5106 clients avoid comparisons (other than equality or inequality) and
5107 explicit ranges. (A @emph{client} is a unit where the type is referenced,
5108 other than the unit where the type is declared, its body, and its subunits.)
5109 For example, if code buried in some client says:
5111 @smallexample @c ada
5112 if Current_Color < Yellow then ...
5113 if Current_Color in Blue .. Green then ...
5117 then the client code is relying on the order, which is undesirable.
5118 It makes the code hard to read and creates maintenance difficulties if
5119 entries have to be added to the enumeration type. Instead,
5120 the code in the client should list the possibilities, or an
5121 appropriate subtype should be declared in the unit that declares
5122 the original enumeration type. E.g., the following subtype could
5123 be declared along with the type @code{Color}:
5125 @smallexample @c ada
5126 subtype RBG is Color range Red .. Green;
5130 and then the client could write:
5132 @smallexample @c ada
5133 if Current_Color in RBG then ...
5134 if Current_Color = Blue or Current_Color = Green then ...
5138 However, some enumeration types are legitimately ordered from a conceptual
5139 point of view. For example, if you declare:
5141 @smallexample @c ada
5142 type Day is (Mon, Tue, Wed, Thu, Fri, Sat, Sun);
5146 then the ordering imposed by the language is reasonable, and
5147 clients can depend on it, writing for example:
5149 @smallexample @c ada
5150 if D in Mon .. Fri then ...
5155 The pragma @option{Ordered} is provided to mark enumeration types that
5156 are conceptually ordered, alerting the reader that clients may depend
5157 on the ordering. GNAT provides a pragma to mark enumerations as ordered
5158 rather than one to mark them as unordered, since in our experience,
5159 the great majority of enumeration types are conceptually unordered.
5161 The types @code{Boolean}, @code{Character}, @code{Wide_Character},
5162 and @code{Wide_Wide_Character}
5163 are considered to be ordered types, so each is declared with a
5164 pragma @code{Ordered} in package @code{Standard}.
5166 Normally pragma @code{Ordered} serves only as documentation and a guide for
5167 coding standards, but GNAT provides a warning switch @option{-gnatw.u} that
5168 requests warnings for inappropriate uses (comparisons and explicit
5169 subranges) for unordered types. If this switch is used, then any
5170 enumeration type not marked with pragma @code{Ordered} will be considered
5171 as unordered, and will generate warnings for inappropriate uses.
5173 Note that generic types are not considered ordered or unordered (since the
5174 template can be instantiated for both cases), so we never generate warnings
5175 for the case of generic enumerated types.
5177 For additional information please refer to the description of the
5178 @option{-gnatw.u} switch in the @value{EDITION} User's Guide.
5180 @node Pragma Overflow_Mode
5181 @unnumberedsec Pragma Overflow_Mode
5182 @findex Overflow checks
5183 @findex Overflow mode
5184 @findex pragma @code{Overflow_Mode}
5188 @smallexample @c ada
5189 pragma Overflow_Mode
5191 [,[Assertions =>] MODE]);
5193 MODE ::= STRICT | MINIMIZED | ELIMINATED
5197 This pragma sets the current overflow mode to the given setting. For details
5198 of the meaning of these modes, please refer to the
5199 ``Overflow Check Handling in GNAT'' appendix in the
5200 @value{EDITION} User's Guide. If only the @code{General} parameter is present,
5201 the given mode applies to all expressions. If both parameters are present,
5202 the @code{General} mode applies to expressions outside assertions, and
5203 the @code{Eliminated} mode applies to expressions within assertions.
5205 The case of the @code{MODE} parameter is ignored,
5206 so @code{MINIMIZED}, @code{Minimized} and
5207 @code{minimized} all have the same effect.
5209 The @code{Overflow_Mode} pragma has the same scoping and placement
5210 rules as pragma @code{Suppress}, so it can occur either as a
5211 configuration pragma, specifying a default for the whole
5212 program, or in a declarative scope, where it applies to the
5213 remaining declarations and statements in that scope.
5215 The pragma @code{Suppress (Overflow_Check)} suppresses
5216 overflow checking, but does not affect the overflow mode.
5218 The pragma @code{Unsuppress (Overflow_Check)} unsuppresses (enables)
5219 overflow checking, but does not affect the overflow mode.
5221 @node Pragma Overriding_Renamings
5222 @unnumberedsec Pragma Overriding_Renamings
5223 @findex Overriding_Renamings
5224 @cindex Rational profile
5225 @cindex Rational compatibility
5229 @smallexample @c ada
5230 pragma Overriding_Renamings;
5234 This is a GNAT configuration pragma to simplify porting
5235 legacy code accepted by the Rational
5236 Ada compiler. In the presence of this pragma, a renaming declaration that
5237 renames an inherited operation declared in the same scope is legal if selected
5238 notation is used as in:
5240 @smallexample @c ada
5241 pragma Overriding_Renamings;
5246 function F (..) renames R.F;
5251 RM 8.3 (15) stipulates that an overridden operation is not visible within the
5252 declaration of the overriding operation.
5254 @node Pragma Partition_Elaboration_Policy
5255 @unnumberedsec Pragma Partition_Elaboration_Policy
5256 @findex Partition_Elaboration_Policy
5260 @smallexample @c ada
5261 pragma Partition_Elaboration_Policy (POLICY_IDENTIFIER);
5263 POLICY_IDENTIFIER ::= Concurrent | Sequential
5267 This pragma is standard in Ada 2005, but is available in all earlier
5268 versions of Ada as an implementation-defined pragma.
5269 See Ada 2012 Reference Manual for details.
5271 @node Pragma Part_Of
5272 @unnumberedsec Pragma Part_Of
5275 For the description of this pragma, see SPARK 2014 Reference Manual,
5278 @node Pragma Passive
5279 @unnumberedsec Pragma Passive
5284 @smallexample @c ada
5285 pragma Passive [(Semaphore | No)];
5289 Syntax checked, but otherwise ignored by GNAT@. This is recognized for
5290 compatibility with DEC Ada 83 implementations, where it is used within a
5291 task definition to request that a task be made passive. If the argument
5292 @code{Semaphore} is present, or the argument is omitted, then DEC Ada 83
5293 treats the pragma as an assertion that the containing task is passive
5294 and that optimization of context switch with this task is permitted and
5295 desired. If the argument @code{No} is present, the task must not be
5296 optimized. GNAT does not attempt to optimize any tasks in this manner
5297 (since protected objects are available in place of passive tasks).
5299 For more information on the subject of passive tasks, see the section
5300 ``Passive Task Optimization'' in the GNAT Users Guide.
5302 @node Pragma Persistent_BSS
5303 @unnumberedsec Pragma Persistent_BSS
5304 @findex Persistent_BSS
5308 @smallexample @c ada
5309 pragma Persistent_BSS [(LOCAL_NAME)]
5313 This pragma allows selected objects to be placed in the @code{.persistent_bss}
5314 section. On some targets the linker and loader provide for special
5315 treatment of this section, allowing a program to be reloaded without
5316 affecting the contents of this data (hence the name persistent).
5318 There are two forms of usage. If an argument is given, it must be the
5319 local name of a library level object, with no explicit initialization
5320 and whose type is potentially persistent. If no argument is given, then
5321 the pragma is a configuration pragma, and applies to all library level
5322 objects with no explicit initialization of potentially persistent types.
5324 A potentially persistent type is a scalar type, or an untagged,
5325 non-discriminated record, all of whose components have no explicit
5326 initialization and are themselves of a potentially persistent type,
5327 or an array, all of whose constraints are static, and whose component
5328 type is potentially persistent.
5330 If this pragma is used on a target where this feature is not supported,
5331 then the pragma will be ignored. See also @code{pragma Linker_Section}.
5333 @node Pragma Polling
5334 @unnumberedsec Pragma Polling
5339 @smallexample @c ada
5340 pragma Polling (ON | OFF);
5344 This pragma controls the generation of polling code. This is normally off.
5345 If @code{pragma Polling (ON)} is used then periodic calls are generated to
5346 the routine @code{Ada.Exceptions.Poll}. This routine is a separate unit in the
5347 runtime library, and can be found in file @file{a-excpol.adb}.
5349 Pragma @code{Polling} can appear as a configuration pragma (for example it
5350 can be placed in the @file{gnat.adc} file) to enable polling globally, or it
5351 can be used in the statement or declaration sequence to control polling
5354 A call to the polling routine is generated at the start of every loop and
5355 at the start of every subprogram call. This guarantees that the @code{Poll}
5356 routine is called frequently, and places an upper bound (determined by
5357 the complexity of the code) on the period between two @code{Poll} calls.
5359 The primary purpose of the polling interface is to enable asynchronous
5360 aborts on targets that cannot otherwise support it (for example Windows
5361 NT), but it may be used for any other purpose requiring periodic polling.
5362 The standard version is null, and can be replaced by a user program. This
5363 will require re-compilation of the @code{Ada.Exceptions} package that can
5364 be found in files @file{a-except.ads} and @file{a-except.adb}.
5366 A standard alternative unit (in file @file{4wexcpol.adb} in the standard GNAT
5367 distribution) is used to enable the asynchronous abort capability on
5368 targets that do not normally support the capability. The version of
5369 @code{Poll} in this file makes a call to the appropriate runtime routine
5370 to test for an abort condition.
5372 Note that polling can also be enabled by use of the @option{-gnatP} switch.
5373 @xref{Switches for gcc,,, gnat_ugn, @value{EDITION} User's Guide}, for
5377 @unnumberedsec Pragma Post
5379 @cindex Checks, postconditions
5380 @findex Postconditions
5384 @smallexample @c ada
5385 pragma Post (Boolean_Expression);
5389 The @code{Post} pragma is intended to be an exact replacement for
5390 the language-defined
5391 @code{Post} aspect, and shares its restrictions and semantics.
5392 It must appear either immediately following the corresponding
5393 subprogram declaration (only other pragmas may intervene), or
5394 if there is no separate subprogram declaration, then it can
5395 appear at the start of the declarations in a subprogram body
5396 (preceded only by other pragmas).
5398 @node Pragma Postcondition
5399 @unnumberedsec Pragma Postcondition
5400 @cindex Postcondition
5401 @cindex Checks, postconditions
5402 @findex Postconditions
5406 @smallexample @c ada
5407 pragma Postcondition (
5408 [Check =>] Boolean_Expression
5409 [,[Message =>] String_Expression]);
5413 The @code{Postcondition} pragma allows specification of automatic
5414 postcondition checks for subprograms. These checks are similar to
5415 assertions, but are automatically inserted just prior to the return
5416 statements of the subprogram with which they are associated (including
5417 implicit returns at the end of procedure bodies and associated
5418 exception handlers).
5420 In addition, the boolean expression which is the condition which
5421 must be true may contain references to function'Result in the case
5422 of a function to refer to the returned value.
5424 @code{Postcondition} pragmas may appear either immediately following the
5425 (separate) declaration of a subprogram, or at the start of the
5426 declarations of a subprogram body. Only other pragmas may intervene
5427 (that is appear between the subprogram declaration and its
5428 postconditions, or appear before the postcondition in the
5429 declaration sequence in a subprogram body). In the case of a
5430 postcondition appearing after a subprogram declaration, the
5431 formal arguments of the subprogram are visible, and can be
5432 referenced in the postcondition expressions.
5434 The postconditions are collected and automatically tested just
5435 before any return (implicit or explicit) in the subprogram body.
5436 A postcondition is only recognized if postconditions are active
5437 at the time the pragma is encountered. The compiler switch @option{gnata}
5438 turns on all postconditions by default, and pragma @code{Check_Policy}
5439 with an identifier of @code{Postcondition} can also be used to
5440 control whether postconditions are active.
5442 The general approach is that postconditions are placed in the spec
5443 if they represent functional aspects which make sense to the client.
5444 For example we might have:
5446 @smallexample @c ada
5447 function Direction return Integer;
5448 pragma Postcondition
5449 (Direction'Result = +1
5451 Direction'Result = -1);
5455 which serves to document that the result must be +1 or -1, and
5456 will test that this is the case at run time if postcondition
5459 Postconditions within the subprogram body can be used to
5460 check that some internal aspect of the implementation,
5461 not visible to the client, is operating as expected.
5462 For instance if a square root routine keeps an internal
5463 counter of the number of times it is called, then we
5464 might have the following postcondition:
5466 @smallexample @c ada
5467 Sqrt_Calls : Natural := 0;
5469 function Sqrt (Arg : Float) return Float is
5470 pragma Postcondition
5471 (Sqrt_Calls = Sqrt_Calls'Old + 1);
5477 As this example, shows, the use of the @code{Old} attribute
5478 is often useful in postconditions to refer to the state on
5479 entry to the subprogram.
5481 Note that postconditions are only checked on normal returns
5482 from the subprogram. If an abnormal return results from
5483 raising an exception, then the postconditions are not checked.
5485 If a postcondition fails, then the exception
5486 @code{System.Assertions.Assert_Failure} is raised. If
5487 a message argument was supplied, then the given string
5488 will be used as the exception message. If no message
5489 argument was supplied, then the default message has
5490 the form "Postcondition failed at file:line". The
5491 exception is raised in the context of the subprogram
5492 body, so it is possible to catch postcondition failures
5493 within the subprogram body itself.
5495 Within a package spec, normal visibility rules
5496 in Ada would prevent forward references within a
5497 postcondition pragma to functions defined later in
5498 the same package. This would introduce undesirable
5499 ordering constraints. To avoid this problem, all
5500 postcondition pragmas are analyzed at the end of
5501 the package spec, allowing forward references.
5503 The following example shows that this even allows
5504 mutually recursive postconditions as in:
5506 @smallexample @c ada
5507 package Parity_Functions is
5508 function Odd (X : Natural) return Boolean;
5509 pragma Postcondition
5513 (x /= 0 and then Even (X - 1))));
5515 function Even (X : Natural) return Boolean;
5516 pragma Postcondition
5520 (x /= 1 and then Odd (X - 1))));
5522 end Parity_Functions;
5526 There are no restrictions on the complexity or form of
5527 conditions used within @code{Postcondition} pragmas.
5528 The following example shows that it is even possible
5529 to verify performance behavior.
5531 @smallexample @c ada
5534 Performance : constant Float;
5535 -- Performance constant set by implementation
5536 -- to match target architecture behavior.
5538 procedure Treesort (Arg : String);
5539 -- Sorts characters of argument using N*logN sort
5540 pragma Postcondition
5541 (Float (Clock - Clock'Old) <=
5542 Float (Arg'Length) *
5543 log (Float (Arg'Length)) *
5549 Note: postcondition pragmas associated with subprograms that are
5550 marked as Inline_Always, or those marked as Inline with front-end
5551 inlining (-gnatN option set) are accepted and legality-checked
5552 by the compiler, but are ignored at run-time even if postcondition
5553 checking is enabled.
5555 Note that pragma @code{Postcondition} differs from the language-defined
5556 @code{Post} aspect (and corresponding @code{Post} pragma) in allowing
5557 multiple occurrences, allowing occurences in the body even if there
5558 is a separate spec, and allowing a second string parameter, and the
5559 use of the pragma identifier @code{Check}. Historically, pragma
5560 @code{Postcondition} was implemented prior to the development of
5561 Ada 2012, and has been retained in its original form for
5562 compatibility purposes.
5564 @node Pragma Post_Class
5565 @unnumberedsec Pragma Post_Class
5567 @cindex Checks, postconditions
5568 @findex Postconditions
5572 @smallexample @c ada
5573 pragma Post_Class (Boolean_Expression);
5577 The @code{Post_Class} pragma is intended to be an exact replacement for
5578 the language-defined
5579 @code{Post'Class} aspect, and shares its restrictions and semantics.
5580 It must appear either immediately following the corresponding
5581 subprogram declaration (only other pragmas may intervene), or
5582 if there is no separate subprogram declaration, then it can
5583 appear at the start of the declarations in a subprogram body
5584 (preceded only by other pragmas).
5586 Note: This pragma is called @code{Post_Class} rather than
5587 @code{Post'Class} because the latter would not be strictly
5588 conforming to the allowed syntax for pragmas. The motivation
5589 for provinding pragmas equivalent to the aspects is to allow a program
5590 to be written using the pragmas, and then compiled if necessary
5591 using an Ada compiler that does not recognize the pragmas or
5592 aspects, but is prepared to ignore the pragmas. The assertion
5593 policy that controls this pragma is @code{Post'Class}, not
5597 @unnumberedsec Pragma Pre
5599 @cindex Checks, preconditions
5600 @findex Preconditions
5604 @smallexample @c ada
5605 pragma Pre (Boolean_Expression);
5609 The @code{Pre} pragma is intended to be an exact replacement for
5610 the language-defined
5611 @code{Pre} aspect, and shares its restrictions and semantics.
5612 It must appear either immediately following the corresponding
5613 subprogram declaration (only other pragmas may intervene), or
5614 if there is no separate subprogram declaration, then it can
5615 appear at the start of the declarations in a subprogram body
5616 (preceded only by other pragmas).
5618 @node Pragma Precondition
5619 @unnumberedsec Pragma Precondition
5620 @cindex Preconditions
5621 @cindex Checks, preconditions
5622 @findex Preconditions
5626 @smallexample @c ada
5627 pragma Precondition (
5628 [Check =>] Boolean_Expression
5629 [,[Message =>] String_Expression]);
5633 The @code{Precondition} pragma is similar to @code{Postcondition}
5634 except that the corresponding checks take place immediately upon
5635 entry to the subprogram, and if a precondition fails, the exception
5636 is raised in the context of the caller, and the attribute 'Result
5637 cannot be used within the precondition expression.
5639 Otherwise, the placement and visibility rules are identical to those
5640 described for postconditions. The following is an example of use
5641 within a package spec:
5643 @smallexample @c ada
5644 package Math_Functions is
5646 function Sqrt (Arg : Float) return Float;
5647 pragma Precondition (Arg >= 0.0)
5653 @code{Precondition} pragmas may appear either immediately following the
5654 (separate) declaration of a subprogram, or at the start of the
5655 declarations of a subprogram body. Only other pragmas may intervene
5656 (that is appear between the subprogram declaration and its
5657 postconditions, or appear before the postcondition in the
5658 declaration sequence in a subprogram body).
5660 Note: precondition pragmas associated with subprograms that are
5661 marked as Inline_Always, or those marked as Inline with front-end
5662 inlining (-gnatN option set) are accepted and legality-checked
5663 by the compiler, but are ignored at run-time even if precondition
5664 checking is enabled.
5666 Note that pragma @code{Precondition} differs from the language-defined
5667 @code{Pre} aspect (and corresponding @code{Pre} pragma) in allowing
5668 multiple occurrences, allowing occurences in the body even if there
5669 is a separate spec, and allowing a second string parameter, and the
5670 use of the pragma identifier @code{Check}. Historically, pragma
5671 @code{Precondition} was implemented prior to the development of
5672 Ada 2012, and has been retained in its original form for
5673 compatibility purposes.
5675 @node Pragma Predicate
5676 @unnumberedsec Pragma Predicate
5678 @findex Predicate pragma
5682 @smallexample @c ada
5684 ([Entity =>] type_LOCAL_NAME,
5685 [Check =>] EXPRESSION);
5689 This pragma (available in all versions of Ada in GNAT) encompasses both
5690 the @code{Static_Predicate} and @code{Dynamic_Predicate} aspects in
5691 Ada 2012. A predicate is regarded as static if it has an allowed form
5692 for @code{Static_Predicate} and is otherwise treated as a
5693 @code{Dynamic_Predicate}. Otherwise, predicates specified by this
5694 pragma behave exactly as described in the Ada 2012 reference manual.
5695 For example, if we have
5697 @smallexample @c ada
5698 type R is range 1 .. 10;
5700 pragma Predicate (Entity => S, Check => S not in 4 .. 6);
5702 pragma Predicate (Entity => Q, Check => F(Q) or G(Q));
5706 the effect is identical to the following Ada 2012 code:
5708 @smallexample @c ada
5709 type R is range 1 .. 10;
5711 Static_Predicate => S not in 4 .. 6;
5713 Dynamic_Predicate => F(Q) or G(Q);
5716 Note that there is are no pragmas @code{Dynamic_Predicate}
5717 or @code{Static_Predicate}. That is
5718 because these pragmas would affect legality and semantics of
5719 the program and thus do not have a neutral effect if ignored.
5720 The motivation behind providing pragmas equivalent to
5721 corresponding aspects is to allow a program to be written
5722 using the pragmas, and then compiled with a compiler that
5723 will ignore the pragmas. That doesn't work in the case of
5724 static and dynamic predicates, since if the corresponding
5725 pragmas are ignored, then the behavior of the program is
5726 fundamentally changed (for example a membership test
5727 @code{A in B} would not take into account a predicate
5728 defined for subtype B). When following this approach, the
5729 use of predicates should be avoided.
5731 @node Pragma Preelaborable_Initialization
5732 @unnumberedsec Pragma Preelaborable_Initialization
5733 @findex Preelaborable_Initialization
5737 @smallexample @c ada
5738 pragma Preelaborable_Initialization (DIRECT_NAME);
5742 This pragma is standard in Ada 2005, but is available in all earlier
5743 versions of Ada as an implementation-defined pragma.
5744 See Ada 2012 Reference Manual for details.
5746 @node Pragma Prefix_Exception_Messages
5747 @unnumberedsec Pragma Prefix_Exception_Messages
5748 @cindex Prefix_Exception_Messages
5750 @cindex Exception_Message
5755 @smallexample @c ada
5756 pragma Prefix_Exception_Messages;
5760 This is an implementation-defined configuration pragma that affects the
5761 behavior of raise statements with a message given as a static string
5762 constant (typically a string literal). In such cases, the string will
5763 be automatically prefixed by the name of the enclosing entity (giving
5764 the package and subprogram containing the raise statement). This helps
5765 to identify where messages are coming from, and this mode is automatic
5766 for the run-time library.
5768 The pragma has no effect if the message is computed with an expression other
5769 than a static string constant, since the assumption in this case is that
5770 the program computes exactly the string it wants. If you still want the
5771 prefixing in this case, you can always call
5772 @code{GNAT.Source_Info.Enclosing_Entity} and prepend the string manually.
5774 @node Pragma Pre_Class
5775 @unnumberedsec Pragma Pre_Class
5777 @cindex Checks, preconditions
5778 @findex Preconditions
5782 @smallexample @c ada
5783 pragma Pre_Class (Boolean_Expression);
5787 The @code{Pre_Class} pragma is intended to be an exact replacement for
5788 the language-defined
5789 @code{Pre'Class} aspect, and shares its restrictions and semantics.
5790 It must appear either immediately following the corresponding
5791 subprogram declaration (only other pragmas may intervene), or
5792 if there is no separate subprogram declaration, then it can
5793 appear at the start of the declarations in a subprogram body
5794 (preceded only by other pragmas).
5796 Note: This pragma is called @code{Pre_Class} rather than
5797 @code{Pre'Class} because the latter would not be strictly
5798 conforming to the allowed syntax for pragmas. The motivation
5799 for providing pragmas equivalent to the aspects is to allow a program
5800 to be written using the pragmas, and then compiled if necessary
5801 using an Ada compiler that does not recognize the pragmas or
5802 aspects, but is prepared to ignore the pragmas. The assertion
5803 policy that controls this pragma is @code{Pre'Class}, not
5806 @node Pragma Priority_Specific_Dispatching
5807 @unnumberedsec Pragma Priority_Specific_Dispatching
5808 @findex Priority_Specific_Dispatching
5812 @smallexample @c ada
5813 pragma Priority_Specific_Dispatching (
5815 first_priority_EXPRESSION,
5816 last_priority_EXPRESSION)
5818 POLICY_IDENTIFIER ::=
5819 EDF_Across_Priorities |
5820 FIFO_Within_Priorities |
5821 Non_Preemptive_Within_Priorities |
5822 Round_Robin_Within_Priorities
5826 This pragma is standard in Ada 2005, but is available in all earlier
5827 versions of Ada as an implementation-defined pragma.
5828 See Ada 2012 Reference Manual for details.
5830 @node Pragma Profile
5831 @unnumberedsec Pragma Profile
5836 @smallexample @c ada
5837 pragma Profile (Ravenscar | Restricted | Rational);
5841 This pragma is standard in Ada 2005, but is available in all earlier
5842 versions of Ada as an implementation-defined pragma. This is a
5843 configuration pragma that establishes a set of configiuration pragmas
5844 that depend on the argument. @code{Ravenscar} is standard in Ada 2005.
5845 The other two possibilities (@code{Restricted} or @code{Rational})
5846 are implementation-defined. The set of configuration pragmas
5847 is defined in the following sections.
5851 @item Pragma Profile (Ravenscar)
5855 The @code{Ravenscar} profile is standard in Ada 2005,
5856 but is available in all earlier
5857 versions of Ada as an implementation-defined pragma. This profile
5858 establishes the following set of configuration pragmas:
5861 @item Task_Dispatching_Policy (FIFO_Within_Priorities)
5862 [RM D.2.2] Tasks are dispatched following a preemptive
5863 priority-ordered scheduling policy.
5865 @item Locking_Policy (Ceiling_Locking)
5866 [RM D.3] While tasks and interrupts execute a protected action, they inherit
5867 the ceiling priority of the corresponding protected object.
5869 @item Detect_Blocking
5870 This pragma forces the detection of potentially blocking operations within a
5871 protected operation, and to raise Program_Error if that happens.
5875 plus the following set of restrictions:
5878 @item Max_Entry_Queue_Length => 1
5879 No task can be queued on a protected entry.
5880 @item Max_Protected_Entries => 1
5881 @item Max_Task_Entries => 0
5882 No rendezvous statements are allowed.
5883 @item No_Abort_Statements
5884 @item No_Dynamic_Attachment
5885 @item No_Dynamic_Priorities
5886 @item No_Implicit_Heap_Allocations
5887 @item No_Local_Protected_Objects
5888 @item No_Local_Timing_Events
5889 @item No_Protected_Type_Allocators
5890 @item No_Relative_Delay
5891 @item No_Requeue_Statements
5892 @item No_Select_Statements
5893 @item No_Specific_Termination_Handlers
5894 @item No_Task_Allocators
5895 @item No_Task_Hierarchy
5896 @item No_Task_Termination
5897 @item Simple_Barriers
5901 The Ravenscar profile also includes the following restrictions that specify
5902 that there are no semantic dependences on the corresponding predefined
5906 @item No_Dependence => Ada.Asynchronous_Task_Control
5907 @item No_Dependence => Ada.Calendar
5908 @item No_Dependence => Ada.Execution_Time.Group_Budget
5909 @item No_Dependence => Ada.Execution_Time.Timers
5910 @item No_Dependence => Ada.Task_Attributes
5911 @item No_Dependence => System.Multiprocessors.Dispatching_Domains
5916 This set of configuration pragmas and restrictions correspond to the
5917 definition of the ``Ravenscar Profile'' for limited tasking, devised and
5918 published by the @cite{International Real-Time Ada Workshop}, 1997,
5919 and whose most recent description is available at
5920 @url{http://www-users.cs.york.ac.uk/~burns/ravenscar.ps}.
5922 The original definition of the profile was revised at subsequent IRTAW
5923 meetings. It has been included in the ISO
5924 @cite{Guide for the Use of the Ada Programming Language in High
5925 Integrity Systems}, and has been approved by ISO/IEC/SC22/WG9 for inclusion in
5926 the next revision of the standard. The formal definition given by
5927 the Ada Rapporteur Group (ARG) can be found in two Ada Issues (AI-249 and
5928 AI-305) available at
5929 @url{http://www.ada-auth.org/cgi-bin/cvsweb.cgi/ais/ai-00249.txt} and
5930 @url{http://www.ada-auth.org/cgi-bin/cvsweb.cgi/ais/ai-00305.txt}.
5932 The above set is a superset of the restrictions provided by pragma
5933 @code{Profile (Restricted)}, it includes six additional restrictions
5934 (@code{Simple_Barriers}, @code{No_Select_Statements},
5935 @code{No_Calendar}, @code{No_Implicit_Heap_Allocations},
5936 @code{No_Relative_Delay} and @code{No_Task_Termination}). This means
5937 that pragma @code{Profile (Ravenscar)}, like the pragma
5938 @code{Profile (Restricted)},
5939 automatically causes the use of a simplified,
5940 more efficient version of the tasking run-time system.
5942 @item Pragma Profile (Restricted)
5943 @findex Restricted Run Time
5945 This profile corresponds to the GNAT restricted run time. It
5946 establishes the following set of restrictions:
5949 @item No_Abort_Statements
5950 @item No_Entry_Queue
5951 @item No_Task_Hierarchy
5952 @item No_Task_Allocators
5953 @item No_Dynamic_Priorities
5954 @item No_Terminate_Alternatives
5955 @item No_Dynamic_Attachment
5956 @item No_Protected_Type_Allocators
5957 @item No_Local_Protected_Objects
5958 @item No_Requeue_Statements
5959 @item No_Task_Attributes_Package
5960 @item Max_Asynchronous_Select_Nesting = 0
5961 @item Max_Task_Entries = 0
5962 @item Max_Protected_Entries = 1
5963 @item Max_Select_Alternatives = 0
5967 This set of restrictions causes the automatic selection of a simplified
5968 version of the run time that provides improved performance for the
5969 limited set of tasking functionality permitted by this set of restrictions.
5971 @item Pragma Profile (Rational)
5972 @findex Rational compatibility mode
5974 The Rational profile is intended to facilitate porting legacy code that
5975 compiles with the Rational APEX compiler, even when the code includes non-
5976 conforming Ada constructs. The profile enables the following three pragmas:
5979 @item pragma Implicit_Packing
5980 @item pragma Overriding_Renamings
5981 @item pragma Use_VADS_Size
5986 @node Pragma Profile_Warnings
5987 @unnumberedsec Pragma Profile_Warnings
5988 @findex Profile_Warnings
5992 @smallexample @c ada
5993 pragma Profile_Warnings (Ravenscar | Restricted | Rational);
5997 This is an implementation-defined pragma that is similar in
5998 effect to @code{pragma Profile} except that instead of
5999 generating @code{Restrictions} pragmas, it generates
6000 @code{Restriction_Warnings} pragmas. The result is that
6001 violations of the profile generate warning messages instead
6004 @node Pragma Propagate_Exceptions
6005 @unnumberedsec Pragma Propagate_Exceptions
6006 @cindex Interfacing to C++
6007 @findex Propagate_Exceptions
6011 @smallexample @c ada
6012 pragma Propagate_Exceptions;
6016 This pragma is now obsolete and, other than generating a warning if warnings
6017 on obsolescent features are enabled, is ignored.
6018 It is retained for compatibility
6019 purposes. It used to be used in connection with optimization of
6020 a now-obsolete mechanism for implementation of exceptions.
6022 @node Pragma Provide_Shift_Operators
6023 @unnumberedsec Pragma Provide_Shift_Operators
6024 @cindex Shift operators
6025 @findex Provide_Shift_Operators
6029 @smallexample @c ada
6030 pragma Provide_Shift_Operators (integer_first_subtype_LOCAL_NAME);
6034 This pragma can be applied to a first subtype local name that specifies
6035 either an unsigned or signed type. It has the effect of providing the
6036 five shift operators (Shift_Left, Shift_Right, Shift_Right_Arithmetic,
6037 Rotate_Left and Rotate_Right) for the given type. It is similar to
6038 including the function declarations for these five operators, together
6039 with the pragma Import (Intrinsic, ...) statements.
6041 @node Pragma Psect_Object
6042 @unnumberedsec Pragma Psect_Object
6043 @findex Psect_Object
6047 @smallexample @c ada
6048 pragma Psect_Object (
6049 [Internal =>] LOCAL_NAME,
6050 [, [External =>] EXTERNAL_SYMBOL]
6051 [, [Size =>] EXTERNAL_SYMBOL]);
6055 | static_string_EXPRESSION
6059 This pragma is identical in effect to pragma @code{Common_Object}.
6061 @node Pragma Pure_Function
6062 @unnumberedsec Pragma Pure_Function
6063 @findex Pure_Function
6067 @smallexample @c ada
6068 pragma Pure_Function ([Entity =>] function_LOCAL_NAME);
6072 This pragma appears in the same declarative part as a function
6073 declaration (or a set of function declarations if more than one
6074 overloaded declaration exists, in which case the pragma applies
6075 to all entities). It specifies that the function @code{Entity} is
6076 to be considered pure for the purposes of code generation. This means
6077 that the compiler can assume that there are no side effects, and
6078 in particular that two calls with identical arguments produce the
6079 same result. It also means that the function can be used in an
6082 Note that, quite deliberately, there are no static checks to try
6083 to ensure that this promise is met, so @code{Pure_Function} can be used
6084 with functions that are conceptually pure, even if they do modify
6085 global variables. For example, a square root function that is
6086 instrumented to count the number of times it is called is still
6087 conceptually pure, and can still be optimized, even though it
6088 modifies a global variable (the count). Memo functions are another
6089 example (where a table of previous calls is kept and consulted to
6090 avoid re-computation).
6092 Note also that the normal rules excluding optimization of subprograms
6093 in pure units (when parameter types are descended from System.Address,
6094 or when the full view of a parameter type is limited), do not apply
6095 for the Pure_Function case. If you explicitly specify Pure_Function,
6096 the compiler may optimize away calls with identical arguments, and
6097 if that results in unexpected behavior, the proper action is not to
6098 use the pragma for subprograms that are not (conceptually) pure.
6101 Note: Most functions in a @code{Pure} package are automatically pure, and
6102 there is no need to use pragma @code{Pure_Function} for such functions. One
6103 exception is any function that has at least one formal of type
6104 @code{System.Address} or a type derived from it. Such functions are not
6105 considered pure by default, since the compiler assumes that the
6106 @code{Address} parameter may be functioning as a pointer and that the
6107 referenced data may change even if the address value does not.
6108 Similarly, imported functions are not considered to be pure by default,
6109 since there is no way of checking that they are in fact pure. The use
6110 of pragma @code{Pure_Function} for such a function will override these default
6111 assumption, and cause the compiler to treat a designated subprogram as pure
6114 Note: If pragma @code{Pure_Function} is applied to a renamed function, it
6115 applies to the underlying renamed function. This can be used to
6116 disambiguate cases of overloading where some but not all functions
6117 in a set of overloaded functions are to be designated as pure.
6119 If pragma @code{Pure_Function} is applied to a library level function, the
6120 function is also considered pure from an optimization point of view, but the
6121 unit is not a Pure unit in the categorization sense. So for example, a function
6122 thus marked is free to @code{with} non-pure units.
6124 @node Pragma Rational
6125 @unnumberedsec Pragma Rational
6130 @smallexample @c ada
6135 This pragma is considered obsolescent, but is retained for
6136 compatibility purposes. It is equivalent to:
6138 @smallexample @c ada
6139 pragma Profile (Rational);
6142 @node Pragma Ravenscar
6143 @unnumberedsec Pragma Ravenscar
6144 @findex Pragma Ravenscar
6148 @smallexample @c ada
6153 This pragma is considered obsolescent, but is retained for
6154 compatibility purposes. It is equivalent to:
6156 @smallexample @c ada
6157 pragma Profile (Ravenscar);
6161 which is the preferred method of setting the @code{Ravenscar} profile.
6163 @node Pragma Refined_Depends
6164 @unnumberedsec Pragma Refined_Depends
6165 @findex Refined_Depends
6167 For the description of this pragma, see SPARK 2014 Reference Manual,
6170 @node Pragma Refined_Global
6171 @unnumberedsec Pragma Refined_Global
6172 @findex Refined_Global
6174 For the description of this pragma, see SPARK 2014 Reference Manual,
6177 @node Pragma Refined_Post
6178 @unnumberedsec Pragma Refined_Post
6179 @findex Refined_Post
6181 For the description of this pragma, see SPARK 2014 Reference Manual,
6184 @node Pragma Refined_State
6185 @unnumberedsec Pragma Refined_State
6186 @findex Refined_State
6188 For the description of this pragma, see SPARK 2014 Reference Manual,
6191 @node Pragma Relative_Deadline
6192 @unnumberedsec Pragma Relative_Deadline
6193 @findex Relative_Deadline
6197 @smallexample @c ada
6198 pragma Relative_Deadline (time_span_EXPRESSION);
6202 This pragma is standard in Ada 2005, but is available in all earlier
6203 versions of Ada as an implementation-defined pragma.
6204 See Ada 2012 Reference Manual for details.
6206 @node Pragma Remote_Access_Type
6207 @unnumberedsec Pragma Remote_Access_Type
6208 @findex Remote_Access_Type
6212 @smallexample @c ada
6213 pragma Remote_Access_Type ([Entity =>] formal_access_type_LOCAL_NAME);
6217 This pragma appears in the formal part of a generic declaration.
6218 It specifies an exception to the RM rule from E.2.2(17/2), which forbids
6219 the use of a remote access to class-wide type as actual for a formal
6222 When this pragma applies to a formal access type @code{Entity}, that
6223 type is treated as a remote access to class-wide type in the generic.
6224 It must be a formal general access type, and its designated type must
6225 be the class-wide type of a formal tagged limited private type from the
6226 same generic declaration.
6228 In the generic unit, the formal type is subject to all restrictions
6229 pertaining to remote access to class-wide types. At instantiation, the
6230 actual type must be a remote access to class-wide type.
6232 @node Pragma Restricted_Run_Time
6233 @unnumberedsec Pragma Restricted_Run_Time
6234 @findex Pragma Restricted_Run_Time
6238 @smallexample @c ada
6239 pragma Restricted_Run_Time;
6243 This pragma is considered obsolescent, but is retained for
6244 compatibility purposes. It is equivalent to:
6246 @smallexample @c ada
6247 pragma Profile (Restricted);
6251 which is the preferred method of setting the restricted run time
6254 @node Pragma Restriction_Warnings
6255 @unnumberedsec Pragma Restriction_Warnings
6256 @findex Restriction_Warnings
6260 @smallexample @c ada
6261 pragma Restriction_Warnings
6262 (restriction_IDENTIFIER @{, restriction_IDENTIFIER@});
6266 This pragma allows a series of restriction identifiers to be
6267 specified (the list of allowed identifiers is the same as for
6268 pragma @code{Restrictions}). For each of these identifiers
6269 the compiler checks for violations of the restriction, but
6270 generates a warning message rather than an error message
6271 if the restriction is violated.
6273 One use of this is in situations where you want to know
6274 about violations of a restriction, but you want to ignore some of
6275 these violations. Consider this example, where you want to set
6276 Ada_95 mode and enable style checks, but you want to know about
6277 any other use of implementation pragmas:
6279 @smallexample @c ada
6280 pragma Restriction_Warnings (No_Implementation_Pragmas);
6281 7 (Off, "violation of*No_Implementation_Pragmas*");
6283 pragma Style_Checks ("2bfhkM160");
6284 pragma Warnings (On, "violation of*No_Implementation_Pragmas*");
6288 By including the above lines in a configuration pragmas file,
6289 the Ada_95 and Style_Checks pragmas are accepted without
6290 generating a warning, but any other use of implementation
6291 defined pragmas will cause a warning to be generated.
6293 @node Pragma Reviewable
6294 @unnumberedsec Pragma Reviewable
6299 @smallexample @c ada
6304 This pragma is an RM-defined standard pragma, but has no effect on the
6305 program being compiled, or on the code generated for the program.
6307 To obtain the required output specified in RM H.3.1, the compiler must be
6308 run with various special switches as follows:
6312 @item Where compiler-generated run-time checks remain
6314 The switch @option{-gnatGL}
6315 @findex @option{-gnatGL}
6316 may be used to list the expanded code in pseudo-Ada form.
6317 Runtime checks show up in the listing either as explicit
6318 checks or operators marked with @{@} to indicate a check is present.
6320 @item An identification of known exceptions at compile time
6322 If the program is compiled with @option{-gnatwa},
6323 @findex @option{-gnatwa}
6324 the compiler warning messages will indicate all cases where the compiler
6325 detects that an exception is certain to occur at run time.
6327 @item Possible reads of uninitialized variables
6329 The compiler warns of many such cases, but its output is incomplete.
6331 The CodePeer analysis tool
6332 @findex CodePeer static analysis tool
6335 A supplemental static analysis tool
6337 may be used to obtain a comprehensive list of all
6338 possible points at which uninitialized data may be read.
6340 @item Where run-time support routines are implicitly invoked
6342 In the output from @option{-gnatGL},
6343 @findex @option{-gnatGL}
6344 run-time calls are explicitly listed as calls to the relevant
6347 @item Object code listing
6349 This may be obtained either by using the @option{-S} switch,
6351 or the objdump utility.
6354 @item Constructs known to be erroneous at compile time
6356 These are identified by warnings issued by the compiler (use @option{-gnatwa}).
6357 @findex @option{-gnatwa}
6359 @item Stack usage information
6361 Static stack usage data (maximum per-subprogram) can be obtained via the
6362 @option{-fstack-usage} switch to the compiler.
6363 @findex @option{-fstack-usage}
6364 Dynamic stack usage data (per task) can be obtained via the @option{-u} switch
6368 The gnatstack utility
6370 can be used to provide additional information on stack usage.
6373 @item Object code listing of entire partition
6375 This can be obtained by compiling the partition with @option{-S},
6377 or by applying objdump
6379 to all the object files that are part of the partition.
6381 @item A description of the run-time model
6383 The full sources of the run-time are available, and the documentation of
6384 these routines describes how these run-time routines interface to the
6385 underlying operating system facilities.
6387 @item Control and data-flow information
6391 @findex CodePeer static analysis tool
6394 A supplemental static analysis tool
6396 may be used to obtain complete control and data-flow information, as well as
6397 comprehensive messages identifying possible problems based on this
6401 @node Pragma Share_Generic
6402 @unnumberedsec Pragma Share_Generic
6403 @findex Share_Generic
6407 @smallexample @c ada
6408 pragma Share_Generic (GNAME @{, GNAME@});
6410 GNAME ::= generic_unit_NAME | generic_instance_NAME
6414 This pragma is provided for compatibility with Dec Ada 83. It has
6415 no effect in @code{GNAT} (which does not implement shared generics), other
6416 than to check that the given names are all names of generic units or
6420 @unnumberedsec Pragma Shared
6424 This pragma is provided for compatibility with Ada 83. The syntax and
6425 semantics are identical to pragma Atomic.
6427 @node Pragma Short_Circuit_And_Or
6428 @unnumberedsec Pragma Short_Circuit_And_Or
6429 @findex Short_Circuit_And_Or
6433 @smallexample @c ada
6434 pragma Short_Circuit_And_Or;
6438 This configuration pragma causes any occurrence of the AND operator applied to
6439 operands of type Standard.Boolean to be short-circuited (i.e. the AND operator
6440 is treated as if it were AND THEN). Or is similarly treated as OR ELSE. This
6441 may be useful in the context of certification protocols requiring the use of
6442 short-circuited logical operators. If this configuration pragma occurs locally
6443 within the file being compiled, it applies only to the file being compiled.
6444 There is no requirement that all units in a partition use this option.
6446 @node Pragma Short_Descriptors
6447 @unnumberedsec Pragma Short_Descriptors
6448 @findex Short_Descriptors
6452 @smallexample @c ada
6453 pragma Short_Descriptors
6457 This pragma is provided for compatibility with other Ada implementations. It
6458 is recognized but ignored by all current versions of GNAT.
6460 @node Pragma Simple_Storage_Pool_Type
6461 @unnumberedsec Pragma Simple_Storage_Pool_Type
6462 @findex Simple_Storage_Pool_Type
6463 @cindex Storage pool, simple
6464 @cindex Simple storage pool
6468 @smallexample @c ada
6469 pragma Simple_Storage_Pool_Type (type_LOCAL_NAME);
6473 A type can be established as a ``simple storage pool type'' by applying
6474 the representation pragma @code{Simple_Storage_Pool_Type} to the type.
6475 A type named in the pragma must be a library-level immutably limited record
6476 type or limited tagged type declared immediately within a package declaration.
6477 The type can also be a limited private type whose full type is allowed as
6478 a simple storage pool type.
6480 For a simple storage pool type @var{SSP}, nonabstract primitive subprograms
6481 @code{Allocate}, @code{Deallocate}, and @code{Storage_Size} can be declared that
6482 are subtype conformant with the following subprogram declarations:
6484 @smallexample @c ada
6487 Storage_Address : out System.Address;
6488 Size_In_Storage_Elements : System.Storage_Elements.Storage_Count;
6489 Alignment : System.Storage_Elements.Storage_Count);
6491 procedure Deallocate
6493 Storage_Address : System.Address;
6494 Size_In_Storage_Elements : System.Storage_Elements.Storage_Count;
6495 Alignment : System.Storage_Elements.Storage_Count);
6497 function Storage_Size (Pool : SSP)
6498 return System.Storage_Elements.Storage_Count;
6502 Procedure @code{Allocate} must be declared, whereas @code{Deallocate} and
6503 @code{Storage_Size} are optional. If @code{Deallocate} is not declared, then
6504 applying an unchecked deallocation has no effect other than to set its actual
6505 parameter to null. If @code{Storage_Size} is not declared, then the
6506 @code{Storage_Size} attribute applied to an access type associated with
6507 a pool object of type SSP returns zero. Additional operations can be declared
6508 for a simple storage pool type (such as for supporting a mark/release
6509 storage-management discipline).
6511 An object of a simple storage pool type can be associated with an access
6512 type by specifying the attribute @code{Simple_Storage_Pool}. For example:
6514 @smallexample @c ada
6516 My_Pool : My_Simple_Storage_Pool_Type;
6518 type Acc is access My_Data_Type;
6520 for Acc'Simple_Storage_Pool use My_Pool;
6525 See attribute @code{Simple_Storage_Pool} for further details.
6527 @node Pragma Source_File_Name
6528 @unnumberedsec Pragma Source_File_Name
6529 @findex Source_File_Name
6533 @smallexample @c ada
6534 pragma Source_File_Name (
6535 [Unit_Name =>] unit_NAME,
6536 Spec_File_Name => STRING_LITERAL,
6537 [Index => INTEGER_LITERAL]);
6539 pragma Source_File_Name (
6540 [Unit_Name =>] unit_NAME,
6541 Body_File_Name => STRING_LITERAL,
6542 [Index => INTEGER_LITERAL]);
6546 Use this to override the normal naming convention. It is a configuration
6547 pragma, and so has the usual applicability of configuration pragmas
6548 (i.e.@: it applies to either an entire partition, or to all units in a
6549 compilation, or to a single unit, depending on how it is used.
6550 @var{unit_name} is mapped to @var{file_name_literal}. The identifier for
6551 the second argument is required, and indicates whether this is the file
6552 name for the spec or for the body.
6554 The optional Index argument should be used when a file contains multiple
6555 units, and when you do not want to use @code{gnatchop} to separate then
6556 into multiple files (which is the recommended procedure to limit the
6557 number of recompilations that are needed when some sources change).
6558 For instance, if the source file @file{source.ada} contains
6560 @smallexample @c ada
6572 you could use the following configuration pragmas:
6574 @smallexample @c ada
6575 pragma Source_File_Name
6576 (B, Spec_File_Name => "source.ada", Index => 1);
6577 pragma Source_File_Name
6578 (A, Body_File_Name => "source.ada", Index => 2);
6581 Note that the @code{gnatname} utility can also be used to generate those
6582 configuration pragmas.
6584 Another form of the @code{Source_File_Name} pragma allows
6585 the specification of patterns defining alternative file naming schemes
6586 to apply to all files.
6588 @smallexample @c ada
6589 pragma Source_File_Name
6590 ( [Spec_File_Name =>] STRING_LITERAL
6591 [,[Casing =>] CASING_SPEC]
6592 [,[Dot_Replacement =>] STRING_LITERAL]);
6594 pragma Source_File_Name
6595 ( [Body_File_Name =>] STRING_LITERAL
6596 [,[Casing =>] CASING_SPEC]
6597 [,[Dot_Replacement =>] STRING_LITERAL]);
6599 pragma Source_File_Name
6600 ( [Subunit_File_Name =>] STRING_LITERAL
6601 [,[Casing =>] CASING_SPEC]
6602 [,[Dot_Replacement =>] STRING_LITERAL]);
6604 CASING_SPEC ::= Lowercase | Uppercase | Mixedcase
6608 The first argument is a pattern that contains a single asterisk indicating
6609 the point at which the unit name is to be inserted in the pattern string
6610 to form the file name. The second argument is optional. If present it
6611 specifies the casing of the unit name in the resulting file name string.
6612 The default is lower case. Finally the third argument allows for systematic
6613 replacement of any dots in the unit name by the specified string literal.
6615 Note that Source_File_Name pragmas should not be used if you are using
6616 project files. The reason for this rule is that the project manager is not
6617 aware of these pragmas, and so other tools that use the projet file would not
6618 be aware of the intended naming conventions. If you are using project files,
6619 file naming is controlled by Source_File_Name_Project pragmas, which are
6620 usually supplied automatically by the project manager. A pragma
6621 Source_File_Name cannot appear after a @ref{Pragma Source_File_Name_Project}.
6623 For more details on the use of the @code{Source_File_Name} pragma,
6624 @xref{Using Other File Names,,, gnat_ugn, @value{EDITION} User's Guide},
6625 and @ref{Alternative File Naming Schemes,,, gnat_ugn, @value{EDITION}
6628 @node Pragma Source_File_Name_Project
6629 @unnumberedsec Pragma Source_File_Name_Project
6630 @findex Source_File_Name_Project
6633 This pragma has the same syntax and semantics as pragma Source_File_Name.
6634 It is only allowed as a stand alone configuration pragma.
6635 It cannot appear after a @ref{Pragma Source_File_Name}, and
6636 most importantly, once pragma Source_File_Name_Project appears,
6637 no further Source_File_Name pragmas are allowed.
6639 The intention is that Source_File_Name_Project pragmas are always
6640 generated by the Project Manager in a manner consistent with the naming
6641 specified in a project file, and when naming is controlled in this manner,
6642 it is not permissible to attempt to modify this naming scheme using
6643 Source_File_Name or Source_File_Name_Project pragmas (which would not be
6644 known to the project manager).
6646 @node Pragma Source_Reference
6647 @unnumberedsec Pragma Source_Reference
6648 @findex Source_Reference
6652 @smallexample @c ada
6653 pragma Source_Reference (INTEGER_LITERAL, STRING_LITERAL);
6657 This pragma must appear as the first line of a source file.
6658 @var{integer_literal} is the logical line number of the line following
6659 the pragma line (for use in error messages and debugging
6660 information). @var{string_literal} is a static string constant that
6661 specifies the file name to be used in error messages and debugging
6662 information. This is most notably used for the output of @code{gnatchop}
6663 with the @option{-r} switch, to make sure that the original unchopped
6664 source file is the one referred to.
6666 The second argument must be a string literal, it cannot be a static
6667 string expression other than a string literal. This is because its value
6668 is needed for error messages issued by all phases of the compiler.
6670 @node Pragma SPARK_Mode
6671 @unnumberedsec Pragma SPARK_Mode
6676 @smallexample @c ada
6677 pragma SPARK_Mode [(On | Off)] ;
6681 In general a program can have some parts that are in SPARK 2014 (and
6682 follow all the rules in the SPARK Reference Manual), and some parts
6683 that are full Ada 2012.
6685 The SPARK_Mode pragma is used to identify which parts are in SPARK
6686 2014 (by default programs are in full Ada). The SPARK_Mode pragma can
6687 be used in the following places:
6692 As a configuration pragma, in which case it sets the default mode for
6693 all units compiled with this pragma.
6696 Immediately following a library-level subprogram spec
6699 Immediately within a library-level package body
6702 Immediately following the @code{private} keyword of a library-level
6706 Immediately following the @code{begin} keyword of a library-level
6710 Immediately within a library-level subprogram body
6715 Normally a subprogram or package spec/body inherits the current mode
6716 that is active at the point it is declared. But this can be overridden
6717 by pragma within the spec or body as above.
6719 The basic consistency rule is that you can't turn SPARK_Mode back
6720 @code{On}, once you have explicitly (with a pragma) turned if
6721 @code{Off}. So the following rules apply:
6724 If a subprogram spec has SPARK_Mode @code{Off}, then the body must
6725 also have SPARK_Mode @code{Off}.
6728 For a package, we have four parts:
6732 the package public declarations
6734 the package private part
6736 the body of the package
6738 the elaboration code after @code{begin}
6742 For a package, the rule is that if you explicitly turn SPARK_Mode
6743 @code{Off} for any part, then all the following parts must have
6744 SPARK_Mode @code{Off}. Note that this may require repeating a pragma
6745 SPARK_Mode (@code{Off}) in the body. For example, if we have a
6746 configuration pragma SPARK_Mode (@code{On}) that turns the mode on by
6747 default everywhere, and one particular package spec has pragma
6748 SPARK_Mode (@code{Off}), then that pragma will need to be repeated in
6751 @node Pragma Static_Elaboration_Desired
6752 @unnumberedsec Pragma Static_Elaboration_Desired
6753 @findex Static_Elaboration_Desired
6757 @smallexample @c ada
6758 pragma Static_Elaboration_Desired;
6762 This pragma is used to indicate that the compiler should attempt to initialize
6763 statically the objects declared in the library unit to which the pragma applies,
6764 when these objects are initialized (explicitly or implicitly) by an aggregate.
6765 In the absence of this pragma, aggregates in object declarations are expanded
6766 into assignments and loops, even when the aggregate components are static
6767 constants. When the aggregate is present the compiler builds a static expression
6768 that requires no run-time code, so that the initialized object can be placed in
6769 read-only data space. If the components are not static, or the aggregate has
6770 more that 100 components, the compiler emits a warning that the pragma cannot
6771 be obeyed. (See also the restriction No_Implicit_Loops, which supports static
6772 construction of larger aggregates with static components that include an others
6775 @node Pragma Stream_Convert
6776 @unnumberedsec Pragma Stream_Convert
6777 @findex Stream_Convert
6781 @smallexample @c ada
6782 pragma Stream_Convert (
6783 [Entity =>] type_LOCAL_NAME,
6784 [Read =>] function_NAME,
6785 [Write =>] function_NAME);
6789 This pragma provides an efficient way of providing user-defined stream
6790 attributes. Not only is it simpler to use than specifying the attributes
6791 directly, but more importantly, it allows the specification to be made in such
6792 a way that the predefined unit Ada.Streams is not loaded unless it is actually
6793 needed (i.e. unless the stream attributes are actually used); the use of
6794 the Stream_Convert pragma adds no overhead at all, unless the stream
6795 attributes are actually used on the designated type.
6797 The first argument specifies the type for which stream functions are
6798 provided. The second parameter provides a function used to read values
6799 of this type. It must name a function whose argument type may be any
6800 subtype, and whose returned type must be the type given as the first
6801 argument to the pragma.
6803 The meaning of the @var{Read} parameter is that if a stream attribute directly
6804 or indirectly specifies reading of the type given as the first parameter,
6805 then a value of the type given as the argument to the Read function is
6806 read from the stream, and then the Read function is used to convert this
6807 to the required target type.
6809 Similarly the @var{Write} parameter specifies how to treat write attributes
6810 that directly or indirectly apply to the type given as the first parameter.
6811 It must have an input parameter of the type specified by the first parameter,
6812 and the return type must be the same as the input type of the Read function.
6813 The effect is to first call the Write function to convert to the given stream
6814 type, and then write the result type to the stream.
6816 The Read and Write functions must not be overloaded subprograms. If necessary
6817 renamings can be supplied to meet this requirement.
6818 The usage of this attribute is best illustrated by a simple example, taken
6819 from the GNAT implementation of package Ada.Strings.Unbounded:
6821 @smallexample @c ada
6822 function To_Unbounded (S : String)
6823 return Unbounded_String
6824 renames To_Unbounded_String;
6826 pragma Stream_Convert
6827 (Unbounded_String, To_Unbounded, To_String);
6831 The specifications of the referenced functions, as given in the Ada
6832 Reference Manual are:
6834 @smallexample @c ada
6835 function To_Unbounded_String (Source : String)
6836 return Unbounded_String;
6838 function To_String (Source : Unbounded_String)
6843 The effect is that if the value of an unbounded string is written to a stream,
6844 then the representation of the item in the stream is in the same format that
6845 would be used for @code{Standard.String'Output}, and this same representation
6846 is expected when a value of this type is read from the stream. Note that the
6847 value written always includes the bounds, even for Unbounded_String'Write,
6848 since Unbounded_String is not an array type.
6850 Note that the @code{Stream_Convert} pragma is not effective in the case of
6851 a derived type of a non-limited tagged type. If such a type is specified then
6852 the pragma is silently ignored, and the default implementation of the stream
6853 attributes is used instead.
6855 @node Pragma Style_Checks
6856 @unnumberedsec Pragma Style_Checks
6857 @findex Style_Checks
6861 @smallexample @c ada
6862 pragma Style_Checks (string_LITERAL | ALL_CHECKS |
6863 On | Off [, LOCAL_NAME]);
6867 This pragma is used in conjunction with compiler switches to control the
6868 built in style checking provided by GNAT@. The compiler switches, if set,
6869 provide an initial setting for the switches, and this pragma may be used
6870 to modify these settings, or the settings may be provided entirely by
6871 the use of the pragma. This pragma can be used anywhere that a pragma
6872 is legal, including use as a configuration pragma (including use in
6873 the @file{gnat.adc} file).
6875 The form with a string literal specifies which style options are to be
6876 activated. These are additive, so they apply in addition to any previously
6877 set style check options. The codes for the options are the same as those
6878 used in the @option{-gnaty} switch to @command{gcc} or @command{gnatmake}.
6879 For example the following two methods can be used to enable
6884 @smallexample @c ada
6885 pragma Style_Checks ("l");
6890 gcc -c -gnatyl @dots{}
6895 The form ALL_CHECKS activates all standard checks (its use is equivalent
6896 to the use of the @code{gnaty} switch with no options. @xref{Top,
6897 @value{EDITION} User's Guide, About This Guide, gnat_ugn,
6898 @value{EDITION} User's Guide}, for details.)
6900 Note: the behavior is slightly different in GNAT mode (@option{-gnatg} used).
6901 In this case, ALL_CHECKS implies the standard set of GNAT mode style check
6902 options (i.e. equivalent to -gnatyg).
6904 The forms with @code{Off} and @code{On}
6905 can be used to temporarily disable style checks
6906 as shown in the following example:
6908 @smallexample @c ada
6912 pragma Style_Checks ("k"); -- requires keywords in lower case
6913 pragma Style_Checks (Off); -- turn off style checks
6914 NULL; -- this will not generate an error message
6915 pragma Style_Checks (On); -- turn style checks back on
6916 NULL; -- this will generate an error message
6920 Finally the two argument form is allowed only if the first argument is
6921 @code{On} or @code{Off}. The effect is to turn of semantic style checks
6922 for the specified entity, as shown in the following example:
6924 @smallexample @c ada
6928 pragma Style_Checks ("r"); -- require consistency of identifier casing
6930 Rf1 : Integer := ARG; -- incorrect, wrong case
6931 pragma Style_Checks (Off, Arg);
6932 Rf2 : Integer := ARG; -- OK, no error
6935 @node Pragma Subtitle
6936 @unnumberedsec Pragma Subtitle
6941 @smallexample @c ada
6942 pragma Subtitle ([Subtitle =>] STRING_LITERAL);
6946 This pragma is recognized for compatibility with other Ada compilers
6947 but is ignored by GNAT@.
6949 @node Pragma Suppress
6950 @unnumberedsec Pragma Suppress
6955 @smallexample @c ada
6956 pragma Suppress (Identifier [, [On =>] Name]);
6960 This is a standard pragma, and supports all the check names required in
6961 the RM. It is included here because GNAT recognizes some additional check
6962 names that are implementation defined (as permitted by the RM):
6967 @code{Alignment_Check} can be used to suppress alignment checks
6968 on addresses used in address clauses. Such checks can also be suppressed
6969 by suppressing range checks, but the specific use of @code{Alignment_Check}
6970 allows suppression of alignment checks without suppressing other range checks.
6973 @code{Atomic_Synchronization} can be used to suppress the special memory
6974 synchronization instructions that are normally generated for access to
6975 @code{Atomic} variables to ensure correct synchronization between tasks
6976 that use such variables for synchronization purposes.
6979 @code{Duplicated_Tag_Check} Can be used to suppress the check that is generated
6980 for a duplicated tag value when a tagged type is declared.
6983 @code{Predicate_Check} can be used to control whether predicate checks are
6984 active. It is applicable only to predicates for which the policy is
6985 @code{Check}. Unlike @code{Assertion_Policy}, which determines if a given
6986 predicate is ignored or checked for the whole program, the use of
6987 @code{Suppress} and @code{Unsuppress} with this check name allows a given
6988 predicate to be turned on and off at specific points in the program.
6991 @code{Validity_Check} can be used specifically to control validity checks.
6992 If @code{Suppress} is used to suppress validity checks, then no validity
6993 checks are performed, including those specified by the appropriate compiler
6994 switch or the @code{Validity_Checks} pragma.
6997 Additional check names previously introduced by use of the @code{Check_Name}
6998 pragma are also allowed.
7003 Note that pragma Suppress gives the compiler permission to omit
7004 checks, but does not require the compiler to omit checks. The compiler
7005 will generate checks if they are essentially free, even when they are
7006 suppressed. In particular, if the compiler can prove that a certain
7007 check will necessarily fail, it will generate code to do an
7008 unconditional ``raise'', even if checks are suppressed. The compiler
7011 Of course, run-time checks are omitted whenever the compiler can prove
7012 that they will not fail, whether or not checks are suppressed.
7014 @node Pragma Suppress_All
7015 @unnumberedsec Pragma Suppress_All
7016 @findex Suppress_All
7020 @smallexample @c ada
7021 pragma Suppress_All;
7025 This pragma can appear anywhere within a unit.
7026 The effect is to apply @code{Suppress (All_Checks)} to the unit
7027 in which it appears. This pragma is implemented for compatibility with DEC
7028 Ada 83 usage where it appears at the end of a unit, and for compatibility
7029 with Rational Ada, where it appears as a program unit pragma.
7030 The use of the standard Ada pragma @code{Suppress (All_Checks)}
7031 as a normal configuration pragma is the preferred usage in GNAT@.
7033 @node Pragma Suppress_Debug_Info
7034 @unnumberedsec Pragma Suppress_Debug_Info
7035 @findex Suppress_Debug_Info
7039 @smallexample @c ada
7040 Suppress_Debug_Info ([Entity =>] LOCAL_NAME);
7044 This pragma can be used to suppress generation of debug information
7045 for the specified entity. It is intended primarily for use in debugging
7046 the debugger, and navigating around debugger problems.
7048 @node Pragma Suppress_Exception_Locations
7049 @unnumberedsec Pragma Suppress_Exception_Locations
7050 @findex Suppress_Exception_Locations
7054 @smallexample @c ada
7055 pragma Suppress_Exception_Locations;
7059 In normal mode, a raise statement for an exception by default generates
7060 an exception message giving the file name and line number for the location
7061 of the raise. This is useful for debugging and logging purposes, but this
7062 entails extra space for the strings for the messages. The configuration
7063 pragma @code{Suppress_Exception_Locations} can be used to suppress the
7064 generation of these strings, with the result that space is saved, but the
7065 exception message for such raises is null. This configuration pragma may
7066 appear in a global configuration pragma file, or in a specific unit as
7067 usual. It is not required that this pragma be used consistently within
7068 a partition, so it is fine to have some units within a partition compiled
7069 with this pragma and others compiled in normal mode without it.
7071 @node Pragma Suppress_Initialization
7072 @unnumberedsec Pragma Suppress_Initialization
7073 @findex Suppress_Initialization
7074 @cindex Suppressing initialization
7075 @cindex Initialization, suppression of
7079 @smallexample @c ada
7080 pragma Suppress_Initialization ([Entity =>] variable_or_subtype_Name);
7084 Here variable_or_subtype_Name is the name introduced by a type declaration
7085 or subtype declaration or the name of a variable introduced by an
7088 In the case of a type or subtype
7089 this pragma suppresses any implicit or explicit initialization
7090 for all variables of the given type or subtype,
7091 including initialization resulting from the use of pragmas
7092 Normalize_Scalars or Initialize_Scalars.
7094 This is considered a representation item, so it cannot be given after
7095 the type is frozen. It applies to all subsequent object declarations,
7096 and also any allocator that creates objects of the type.
7098 If the pragma is given for the first subtype, then it is considered
7099 to apply to the base type and all its subtypes. If the pragma is given
7100 for other than a first subtype, then it applies only to the given subtype.
7101 The pragma may not be given after the type is frozen.
7103 Note that this includes eliminating initialization of discriminants
7104 for discriminated types, and tags for tagged types. In these cases,
7105 you will have to use some non-portable mechanism (e.g. address
7106 overlays or unchecked conversion) to achieve required initialization
7107 of these fields before accessing any object of the corresponding type.
7109 For the variable case, implicit initialization for the named variable
7110 is suppressed, just as though its subtype had been given in a pragma
7111 Suppress_Initialization, as described above.
7113 @node Pragma Task_Name
7114 @unnumberedsec Pragma Task_Name
7119 @smallexample @c ada
7120 pragma Task_Name (string_EXPRESSION);
7124 This pragma appears within a task definition (like pragma
7125 @code{Priority}) and applies to the task in which it appears. The
7126 argument must be of type String, and provides a name to be used for
7127 the task instance when the task is created. Note that this expression
7128 is not required to be static, and in particular, it can contain
7129 references to task discriminants. This facility can be used to
7130 provide different names for different tasks as they are created,
7131 as illustrated in the example below.
7133 The task name is recorded internally in the run-time structures
7134 and is accessible to tools like the debugger. In addition the
7135 routine @code{Ada.Task_Identification.Image} will return this
7136 string, with a unique task address appended.
7138 @smallexample @c ada
7139 -- Example of the use of pragma Task_Name
7141 with Ada.Task_Identification;
7142 use Ada.Task_Identification;
7143 with Text_IO; use Text_IO;
7146 type Astring is access String;
7148 task type Task_Typ (Name : access String) is
7149 pragma Task_Name (Name.all);
7152 task body Task_Typ is
7153 Nam : constant String := Image (Current_Task);
7155 Put_Line ("-->" & Nam (1 .. 14) & "<--");
7158 type Ptr_Task is access Task_Typ;
7159 Task_Var : Ptr_Task;
7163 new Task_Typ (new String'("This is task 1"));
7165 new Task_Typ (new String'("This is task 2"));
7169 @node Pragma Task_Storage
7170 @unnumberedsec Pragma Task_Storage
7171 @findex Task_Storage
7174 @smallexample @c ada
7175 pragma Task_Storage (
7176 [Task_Type =>] LOCAL_NAME,
7177 [Top_Guard =>] static_integer_EXPRESSION);
7181 This pragma specifies the length of the guard area for tasks. The guard
7182 area is an additional storage area allocated to a task. A value of zero
7183 means that either no guard area is created or a minimal guard area is
7184 created, depending on the target. This pragma can appear anywhere a
7185 @code{Storage_Size} attribute definition clause is allowed for a task
7188 @node Pragma Test_Case
7189 @unnumberedsec Pragma Test_Case
7195 @smallexample @c ada
7197 [Name =>] static_string_Expression
7198 ,[Mode =>] (Nominal | Robustness)
7199 [, Requires => Boolean_Expression]
7200 [, Ensures => Boolean_Expression]);
7204 The @code{Test_Case} pragma allows defining fine-grain specifications
7205 for use by testing tools.
7206 The compiler checks the validity of the @code{Test_Case} pragma, but its
7207 presence does not lead to any modification of the code generated by the
7210 @code{Test_Case} pragmas may only appear immediately following the
7211 (separate) declaration of a subprogram in a package declaration, inside
7212 a package spec unit. Only other pragmas may intervene (that is appear
7213 between the subprogram declaration and a test case).
7215 The compiler checks that boolean expressions given in @code{Requires} and
7216 @code{Ensures} are valid, where the rules for @code{Requires} are the
7217 same as the rule for an expression in @code{Precondition} and the rules
7218 for @code{Ensures} are the same as the rule for an expression in
7219 @code{Postcondition}. In particular, attributes @code{'Old} and
7220 @code{'Result} can only be used within the @code{Ensures}
7221 expression. The following is an example of use within a package spec:
7223 @smallexample @c ada
7224 package Math_Functions is
7226 function Sqrt (Arg : Float) return Float;
7227 pragma Test_Case (Name => "Test 1",
7229 Requires => Arg < 10000,
7230 Ensures => Sqrt'Result < 10);
7236 The meaning of a test case is that there is at least one context where
7237 @code{Requires} holds such that, if the associated subprogram is executed in
7238 that context, then @code{Ensures} holds when the subprogram returns.
7239 Mode @code{Nominal} indicates that the input context should also satisfy the
7240 precondition of the subprogram, and the output context should also satisfy its
7241 postcondition. Mode @code{Robustness} indicates that the precondition and
7242 postcondition of the subprogram should be ignored for this test case.
7244 @node Pragma Thread_Local_Storage
7245 @unnumberedsec Pragma Thread_Local_Storage
7246 @findex Thread_Local_Storage
7247 @cindex Task specific storage
7248 @cindex TLS (Thread Local Storage)
7249 @cindex Task_Attributes
7252 @smallexample @c ada
7253 pragma Thread_Local_Storage ([Entity =>] LOCAL_NAME);
7257 This pragma specifies that the specified entity, which must be
7258 a variable declared in a library level package, is to be marked as
7259 "Thread Local Storage" (@code{TLS}). On systems supporting this (which
7260 include Solaris, GNU/Linux and VxWorks 6), this causes each thread
7261 (and hence each Ada task) to see a distinct copy of the variable.
7263 The variable may not have default initialization, and if there is
7264 an explicit initialization, it must be either @code{null} for an
7265 access variable, or a static expression for a scalar variable.
7266 This provides a low level mechanism similar to that provided by
7267 the @code{Ada.Task_Attributes} package, but much more efficient
7268 and is also useful in writing interface code that will interact
7269 with foreign threads.
7271 If this pragma is used on a system where @code{TLS} is not supported,
7272 then an error message will be generated and the program will be rejected.
7274 @node Pragma Time_Slice
7275 @unnumberedsec Pragma Time_Slice
7280 @smallexample @c ada
7281 pragma Time_Slice (static_duration_EXPRESSION);
7285 For implementations of GNAT on operating systems where it is possible
7286 to supply a time slice value, this pragma may be used for this purpose.
7287 It is ignored if it is used in a system that does not allow this control,
7288 or if it appears in other than the main program unit.
7290 Note that the effect of this pragma is identical to the effect of the
7291 DEC Ada 83 pragma of the same name when operating under OpenVMS systems.
7294 @unnumberedsec Pragma Title
7299 @smallexample @c ada
7300 pragma Title (TITLING_OPTION [, TITLING OPTION]);
7303 [Title =>] STRING_LITERAL,
7304 | [Subtitle =>] STRING_LITERAL
7308 Syntax checked but otherwise ignored by GNAT@. This is a listing control
7309 pragma used in DEC Ada 83 implementations to provide a title and/or
7310 subtitle for the program listing. The program listing generated by GNAT
7311 does not have titles or subtitles.
7313 Unlike other pragmas, the full flexibility of named notation is allowed
7314 for this pragma, i.e.@: the parameters may be given in any order if named
7315 notation is used, and named and positional notation can be mixed
7316 following the normal rules for procedure calls in Ada.
7318 @node Pragma Type_Invariant
7319 @unnumberedsec Pragma Type_Invariant
7321 @findex Type_Invariant pragma
7325 @smallexample @c ada
7326 pragma Type_Invariant
7327 ([Entity =>] type_LOCAL_NAME,
7328 [Check =>] EXPRESSION);
7332 The @code{Type_Invariant} pragma is intended to be an exact
7333 replacement for the language-defined @code{Type_Invariant}
7334 aspect, and shares its restrictions and semantics. It differs
7335 from the language defined @code{Invariant} pragma in that it
7336 does not permit a string parameter, and it is
7337 controlled by the assertion identifier @code{Type_Invariant}
7338 rather than @code{Invariant}.
7340 @node Pragma Type_Invariant_Class
7341 @unnumberedsec Pragma Type_Invariant_Class
7343 @findex Type_Invariant_Class pragma
7347 @smallexample @c ada
7348 pragma Type_Invariant_Class
7349 ([Entity =>] type_LOCAL_NAME,
7350 [Check =>] EXPRESSION);
7354 The @code{Type_Invariant_Class} pragma is intended to be an exact
7355 replacement for the language-defined @code{Type_Invariant'Class}
7356 aspect, and shares its restrictions and semantics.
7358 Note: This pragma is called @code{Type_Invariant_Class} rather than
7359 @code{Type_Invariant'Class} because the latter would not be strictly
7360 conforming to the allowed syntax for pragmas. The motivation
7361 for providing pragmas equivalent to the aspects is to allow a program
7362 to be written using the pragmas, and then compiled if necessary
7363 using an Ada compiler that does not recognize the pragmas or
7364 aspects, but is prepared to ignore the pragmas. The assertion
7365 policy that controls this pragma is @code{Type_Invariant'Class},
7366 not @code{Type_Invariant_Class}.
7368 @node Pragma Unchecked_Union
7369 @unnumberedsec Pragma Unchecked_Union
7371 @findex Unchecked_Union
7375 @smallexample @c ada
7376 pragma Unchecked_Union (first_subtype_LOCAL_NAME);
7380 This pragma is used to specify a representation of a record type that is
7381 equivalent to a C union. It was introduced as a GNAT implementation defined
7382 pragma in the GNAT Ada 95 mode. Ada 2005 includes an extended version of this
7383 pragma, making it language defined, and GNAT fully implements this extended
7384 version in all language modes (Ada 83, Ada 95, and Ada 2005). For full
7385 details, consult the Ada 2012 Reference Manual, section B.3.3.
7387 @node Pragma Unevaluated_Use_Of_Old
7388 @unnumberedsec Pragma Unevaluated_Use_Of_Old
7389 @cindex Attribute Old
7390 @cindex Attribute Loop_Entry
7391 @cindex Unevaluated_Use_Of_Old
7392 @findex Unevaluated_Use_Of_Old
7396 @smallexample @c ada
7397 pragma Unevaluated_Use_Of_Old (Error | Warn | Allow);
7401 This pragma controls the processing of attributes Old and Loop_Entry.
7402 If either of these attributes is used in a potentially unevaluated
7403 expression (e.g. the then or else parts of an if expression), then
7404 normally this usage is considered illegal if the prefix of the attribute
7405 is other than an entity name. The language requires this
7406 behavior for Old, and GNAT copies the same rule for Loop_Entry.
7408 The reason for this rule is that otherwise, we can have a situation
7409 where we save the Old value, and this results in an exception, even
7410 though we might not evaluate the attribute. Consider this example:
7412 @smallexample @c ada
7413 package UnevalOld is
7415 procedure U (A : String; C : Boolean) -- ERROR
7416 with Post => (if C then A(1)'Old = K else True);
7421 If procedure U is called with a string with a lower bound of 2, and
7422 C false, then an exception would be raised trying to evaluate A(1)
7423 on entry even though the value would not be actually used.
7425 Although the rule guarantees against this possibility, it is sometimes
7426 too restrictive. For example if we know that the string has a lower
7427 bound of 1, then we will never raise an exception.
7428 The pragma @code{Unevaluated_Use_Of_Old} can be
7429 used to modify this behavior. If the argument is @code{Error} then an
7430 error is given (this is the default RM behavior). If the argument is
7431 @code{Warn} then the usage is allowed as legal but with a warning
7432 that an exception might be raised. If the argument is @code{Allow}
7433 then the usage is allowed as legal without generating a warning.
7435 This pragma may appear as a configuration pragma, or in a declarative
7436 part or package specification. In the latter case it applies to
7437 uses up to the end of the corresponding statement sequence or
7438 sequence of package declarations.
7440 @node Pragma Unimplemented_Unit
7441 @unnumberedsec Pragma Unimplemented_Unit
7442 @findex Unimplemented_Unit
7446 @smallexample @c ada
7447 pragma Unimplemented_Unit;
7451 If this pragma occurs in a unit that is processed by the compiler, GNAT
7452 aborts with the message @samp{@var{xxx} not implemented}, where
7453 @var{xxx} is the name of the current compilation unit. This pragma is
7454 intended to allow the compiler to handle unimplemented library units in
7457 The abort only happens if code is being generated. Thus you can use
7458 specs of unimplemented packages in syntax or semantic checking mode.
7460 @node Pragma Universal_Aliasing
7461 @unnumberedsec Pragma Universal_Aliasing
7462 @findex Universal_Aliasing
7466 @smallexample @c ada
7467 pragma Universal_Aliasing [([Entity =>] type_LOCAL_NAME)];
7471 @var{type_LOCAL_NAME} must refer to a type declaration in the current
7472 declarative part. The effect is to inhibit strict type-based aliasing
7473 optimization for the given type. In other words, the effect is as though
7474 access types designating this type were subject to pragma No_Strict_Aliasing.
7475 For a detailed description of the strict aliasing optimization, and the
7476 situations in which it must be suppressed, @xref{Optimization and Strict
7477 Aliasing,,, gnat_ugn, @value{EDITION} User's Guide}.
7479 @node Pragma Universal_Data
7480 @unnumberedsec Pragma Universal_Data
7481 @findex Universal_Data
7485 @smallexample @c ada
7486 pragma Universal_Data [(library_unit_Name)];
7490 This pragma is supported only for the AAMP target and is ignored for
7491 other targets. The pragma specifies that all library-level objects
7492 (Counter 0 data) associated with the library unit are to be accessed
7493 and updated using universal addressing (24-bit addresses for AAMP5)
7494 rather than the default of 16-bit Data Environment (DENV) addressing.
7495 Use of this pragma will generally result in less efficient code for
7496 references to global data associated with the library unit, but
7497 allows such data to be located anywhere in memory. This pragma is
7498 a library unit pragma, but can also be used as a configuration pragma
7499 (including use in the @file{gnat.adc} file). The functionality
7500 of this pragma is also available by applying the -univ switch on the
7501 compilations of units where universal addressing of the data is desired.
7503 @node Pragma Unmodified
7504 @unnumberedsec Pragma Unmodified
7506 @cindex Warnings, unmodified
7510 @smallexample @c ada
7511 pragma Unmodified (LOCAL_NAME @{, LOCAL_NAME@});
7515 This pragma signals that the assignable entities (variables,
7516 @code{out} parameters, @code{in out} parameters) whose names are listed are
7517 deliberately not assigned in the current source unit. This
7518 suppresses warnings about the
7519 entities being referenced but not assigned, and in addition a warning will be
7520 generated if one of these entities is in fact assigned in the
7521 same unit as the pragma (or in the corresponding body, or one
7524 This is particularly useful for clearly signaling that a particular
7525 parameter is not modified, even though the spec suggests that it might
7528 For the variable case, warnings are never given for unreferenced variables
7529 whose name contains one of the substrings
7530 @code{DISCARD, DUMMY, IGNORE, JUNK, UNUSED} in any casing. Such names
7531 are typically to be used in cases where such warnings are expected.
7532 Thus it is never necessary to use @code{pragma Unmodified} for such
7533 variables, though it is harmless to do so.
7535 @node Pragma Unreferenced
7536 @unnumberedsec Pragma Unreferenced
7537 @findex Unreferenced
7538 @cindex Warnings, unreferenced
7542 @smallexample @c ada
7543 pragma Unreferenced (LOCAL_NAME @{, LOCAL_NAME@});
7544 pragma Unreferenced (library_unit_NAME @{, library_unit_NAME@});
7548 This pragma signals that the entities whose names are listed are
7549 deliberately not referenced in the current source unit after the
7550 occurrence of the pragma. This
7551 suppresses warnings about the
7552 entities being unreferenced, and in addition a warning will be
7553 generated if one of these entities is in fact subsequently referenced in the
7554 same unit as the pragma (or in the corresponding body, or one
7557 This is particularly useful for clearly signaling that a particular
7558 parameter is not referenced in some particular subprogram implementation
7559 and that this is deliberate. It can also be useful in the case of
7560 objects declared only for their initialization or finalization side
7563 If @code{LOCAL_NAME} identifies more than one matching homonym in the
7564 current scope, then the entity most recently declared is the one to which
7565 the pragma applies. Note that in the case of accept formals, the pragma
7566 Unreferenced may appear immediately after the keyword @code{do} which
7567 allows the indication of whether or not accept formals are referenced
7568 or not to be given individually for each accept statement.
7570 The left hand side of an assignment does not count as a reference for the
7571 purpose of this pragma. Thus it is fine to assign to an entity for which
7572 pragma Unreferenced is given.
7574 Note that if a warning is desired for all calls to a given subprogram,
7575 regardless of whether they occur in the same unit as the subprogram
7576 declaration, then this pragma should not be used (calls from another
7577 unit would not be flagged); pragma Obsolescent can be used instead
7578 for this purpose, see @xref{Pragma Obsolescent}.
7580 The second form of pragma @code{Unreferenced} is used within a context
7581 clause. In this case the arguments must be unit names of units previously
7582 mentioned in @code{with} clauses (similar to the usage of pragma
7583 @code{Elaborate_All}. The effect is to suppress warnings about unreferenced
7584 units and unreferenced entities within these units.
7586 For the variable case, warnings are never given for unreferenced variables
7587 whose name contains one of the substrings
7588 @code{DISCARD, DUMMY, IGNORE, JUNK, UNUSED} in any casing. Such names
7589 are typically to be used in cases where such warnings are expected.
7590 Thus it is never necessary to use @code{pragma Unreferenced} for such
7591 variables, though it is harmless to do so.
7593 @node Pragma Unreferenced_Objects
7594 @unnumberedsec Pragma Unreferenced_Objects
7595 @findex Unreferenced_Objects
7596 @cindex Warnings, unreferenced
7600 @smallexample @c ada
7601 pragma Unreferenced_Objects (local_subtype_NAME @{, local_subtype_NAME@});
7605 This pragma signals that for the types or subtypes whose names are
7606 listed, objects which are declared with one of these types or subtypes may
7607 not be referenced, and if no references appear, no warnings are given.
7609 This is particularly useful for objects which are declared solely for their
7610 initialization and finalization effect. Such variables are sometimes referred
7611 to as RAII variables (Resource Acquisition Is Initialization). Using this
7612 pragma on the relevant type (most typically a limited controlled type), the
7613 compiler will automatically suppress unwanted warnings about these variables
7614 not being referenced.
7616 @node Pragma Unreserve_All_Interrupts
7617 @unnumberedsec Pragma Unreserve_All_Interrupts
7618 @findex Unreserve_All_Interrupts
7622 @smallexample @c ada
7623 pragma Unreserve_All_Interrupts;
7627 Normally certain interrupts are reserved to the implementation. Any attempt
7628 to attach an interrupt causes Program_Error to be raised, as described in
7629 RM C.3.2(22). A typical example is the @code{SIGINT} interrupt used in
7630 many systems for a @kbd{Ctrl-C} interrupt. Normally this interrupt is
7631 reserved to the implementation, so that @kbd{Ctrl-C} can be used to
7632 interrupt execution.
7634 If the pragma @code{Unreserve_All_Interrupts} appears anywhere in any unit in
7635 a program, then all such interrupts are unreserved. This allows the
7636 program to handle these interrupts, but disables their standard
7637 functions. For example, if this pragma is used, then pressing
7638 @kbd{Ctrl-C} will not automatically interrupt execution. However,
7639 a program can then handle the @code{SIGINT} interrupt as it chooses.
7641 For a full list of the interrupts handled in a specific implementation,
7642 see the source code for the spec of @code{Ada.Interrupts.Names} in
7643 file @file{a-intnam.ads}. This is a target dependent file that contains the
7644 list of interrupts recognized for a given target. The documentation in
7645 this file also specifies what interrupts are affected by the use of
7646 the @code{Unreserve_All_Interrupts} pragma.
7648 For a more general facility for controlling what interrupts can be
7649 handled, see pragma @code{Interrupt_State}, which subsumes the functionality
7650 of the @code{Unreserve_All_Interrupts} pragma.
7652 @node Pragma Unsuppress
7653 @unnumberedsec Pragma Unsuppress
7658 @smallexample @c ada
7659 pragma Unsuppress (IDENTIFIER [, [On =>] NAME]);
7663 This pragma undoes the effect of a previous pragma @code{Suppress}. If
7664 there is no corresponding pragma @code{Suppress} in effect, it has no
7665 effect. The range of the effect is the same as for pragma
7666 @code{Suppress}. The meaning of the arguments is identical to that used
7667 in pragma @code{Suppress}.
7669 One important application is to ensure that checks are on in cases where
7670 code depends on the checks for its correct functioning, so that the code
7671 will compile correctly even if the compiler switches are set to suppress
7672 checks. For example, in a program that depends on external names of tagged
7673 types and wants to ensure that the duplicated tag check occurs even if all
7674 run-time checks are suppressed by a compiler switch, the following
7675 configuration pragma will ensure this test is not suppressed:
7677 @smallexample @c ada
7678 pragma Unsuppress (Duplicated_Tag_Check);
7682 This pragma is standard in Ada 2005. It is available in all earlier versions
7683 of Ada as an implementation-defined pragma.
7685 Note that in addition to the checks defined in the Ada RM, GNAT recogizes
7686 a number of implementation-defined check names. See description of pragma
7687 @code{Suppress} for full details.
7689 @node Pragma Use_VADS_Size
7690 @unnumberedsec Pragma Use_VADS_Size
7691 @cindex @code{Size}, VADS compatibility
7692 @cindex Rational profile
7693 @findex Use_VADS_Size
7697 @smallexample @c ada
7698 pragma Use_VADS_Size;
7702 This is a configuration pragma. In a unit to which it applies, any use
7703 of the 'Size attribute is automatically interpreted as a use of the
7704 'VADS_Size attribute. Note that this may result in incorrect semantic
7705 processing of valid Ada 95 or Ada 2005 programs. This is intended to aid in
7706 the handling of existing code which depends on the interpretation of Size
7707 as implemented in the VADS compiler. See description of the VADS_Size
7708 attribute for further details.
7710 @node Pragma Validity_Checks
7711 @unnumberedsec Pragma Validity_Checks
7712 @findex Validity_Checks
7716 @smallexample @c ada
7717 pragma Validity_Checks (string_LITERAL | ALL_CHECKS | On | Off);
7721 This pragma is used in conjunction with compiler switches to control the
7722 built-in validity checking provided by GNAT@. The compiler switches, if set
7723 provide an initial setting for the switches, and this pragma may be used
7724 to modify these settings, or the settings may be provided entirely by
7725 the use of the pragma. This pragma can be used anywhere that a pragma
7726 is legal, including use as a configuration pragma (including use in
7727 the @file{gnat.adc} file).
7729 The form with a string literal specifies which validity options are to be
7730 activated. The validity checks are first set to include only the default
7731 reference manual settings, and then a string of letters in the string
7732 specifies the exact set of options required. The form of this string
7733 is exactly as described for the @option{-gnatVx} compiler switch (see the
7734 @value{EDITION} User's Guide for details). For example the following two
7735 methods can be used to enable validity checking for mode @code{in} and
7736 @code{in out} subprogram parameters:
7740 @smallexample @c ada
7741 pragma Validity_Checks ("im");
7746 gcc -c -gnatVim @dots{}
7751 The form ALL_CHECKS activates all standard checks (its use is equivalent
7752 to the use of the @code{gnatva} switch.
7754 The forms with @code{Off} and @code{On}
7755 can be used to temporarily disable validity checks
7756 as shown in the following example:
7758 @smallexample @c ada
7762 pragma Validity_Checks ("c"); -- validity checks for copies
7763 pragma Validity_Checks (Off); -- turn off validity checks
7764 A := B; -- B will not be validity checked
7765 pragma Validity_Checks (On); -- turn validity checks back on
7766 A := C; -- C will be validity checked
7769 @node Pragma Volatile
7770 @unnumberedsec Pragma Volatile
7775 @smallexample @c ada
7776 pragma Volatile (LOCAL_NAME);
7780 This pragma is defined by the Ada Reference Manual, and the GNAT
7781 implementation is fully conformant with this definition. The reason it
7782 is mentioned in this section is that a pragma of the same name was supplied
7783 in some Ada 83 compilers, including DEC Ada 83. The Ada 95 / Ada 2005
7784 implementation of pragma Volatile is upwards compatible with the
7785 implementation in DEC Ada 83.
7787 @node Pragma Warning_As_Error
7788 @unnumberedsec Pragma Warning_As_Error
7789 @findex Warning_As_Error
7793 @smallexample @c ada
7794 pragma Warning_As_Error (static_string_EXPRESSION);
7798 This configuration pragma allows the programmer to specify a set
7799 of warnings that will be treated as errors. Any warning which
7800 matches the pattern given by the pragma argument will be treated
7801 as an error. This gives much more precise control that -gnatwe
7802 which treats all warnings as errors.
7804 The pattern may contain asterisks, which match zero or more characters in
7805 the message. For example, you can use
7806 @code{pragma Warning_As_Error ("bits of*unused")} to treat the warning
7807 message @code{warning: 960 bits of "a" unused} as an error. No other regular
7808 expression notations are permitted. All characters other than asterisk in
7809 these three specific cases are treated as literal characters in the match.
7810 The match is case insensitive, for example XYZ matches xyz.
7812 Note that the pattern matches if it occurs anywhere within the warning
7813 message string (it is not necessary to put an asterisk at the start and
7814 the end of the message, since this is implied).
7816 Another possibility for the static_string_EXPRESSION which works whether
7817 or not error tags are enabled (@option{-gnatw.d}) is to use the
7818 @option{-gnatw} tag string, enclosed in brackets,
7819 as shown in the example below, to treat a class of warnings as errors.
7821 The above use of patterns to match the message applies only to warning
7822 messages generated by the front end. This pragma can also be applied to
7823 warnings provided by the back end and mentioned in @ref{Pragma Warnings}.
7824 By using a single full @option{-Wxxx} switch in the pragma, such warnings
7825 can also be treated as errors.
7827 The pragma can appear either in a global configuration pragma file
7828 (e.g. @file{gnat.adc}), or at the start of a file. Given a global
7829 configuration pragma file containing:
7831 @smallexample @c ada
7832 pragma Warning_As_Error ("[-gnatwj]");
7836 which will treat all obsolescent feature warnings as errors, the
7837 following program compiles as shown (compile options here are
7838 @option{-gnatwa.d -gnatl -gnatj55}).
7840 @smallexample @c ada
7841 1. pragma Warning_As_Error ("*never assigned*");
7842 2. function Warnerr return String is
7845 >>> error: variable "X" is never read and
7846 never assigned [-gnatwv] [warning-as-error]
7850 >>> warning: variable "Y" is assigned but
7851 never read [-gnatwu]
7857 >>> error: use of "%" is an obsolescent
7858 feature (RM J.2(4)), use """ instead
7859 [-gnatwj] [warning-as-error]
7863 8 lines: No errors, 3 warnings (2 treated as errors)
7867 Note that this pragma does not affect the set of warnings issued in
7868 any way, it merely changes the effect of a matching warning if one
7869 is produced as a result of other warnings options. As shown in this
7870 example, if the pragma results in a warning being treated as an error,
7871 the tag is changed from "warning:" to "error:" and the string
7872 "[warning-as-error]" is appended to the end of the message.
7874 @node Pragma Warnings
7875 @unnumberedsec Pragma Warnings
7880 @smallexample @c ada
7881 pragma Warnings (On | Off [,REASON]);
7882 pragma Warnings (On | Off, LOCAL_NAME [,REASON]);
7883 pragma Warnings (static_string_EXPRESSION [,REASON]);
7884 pragma Warnings (On | Off, static_string_EXPRESSION [,REASON]);
7886 REASON ::= Reason => STRING_LITERAL @{& STRING_LITERAL@}
7888 Note: in Ada 83 mode, a string literal may be used in place of
7889 a static string expression (which does not exist in Ada 83).
7893 Normally warnings are enabled, with the output being controlled by
7894 the command line switch. Warnings (@code{Off}) turns off generation of
7895 warnings until a Warnings (@code{On}) is encountered or the end of the
7896 current unit. If generation of warnings is turned off using this
7897 pragma, then some or all of the warning messages are suppressed,
7898 regardless of the setting of the command line switches.
7900 The @code{Reason} parameter may optionally appear as the last argument
7901 in any of the forms of this pragma. It is intended purely for the
7902 purposes of documenting the reason for the @code{Warnings} pragma.
7903 The compiler will check that the argument is a static string but
7904 otherwise ignore this argument. Other tools may provide specialized
7905 processing for this string.
7907 The form with a single argument (or two arguments if Reason present),
7908 where the first argument is @code{ON} or @code{OFF}
7909 may be used as a configuration pragma.
7911 If the @var{LOCAL_NAME} parameter is present, warnings are suppressed for
7912 the specified entity. This suppression is effective from the point where
7913 it occurs till the end of the extended scope of the variable (similar to
7914 the scope of @code{Suppress}). This form cannot be used as a configuration
7917 In the case where the first argument is other than @code{ON} or
7919 the third form with a single static_string_EXPRESSION argument (and possible
7920 reason) provides more precise
7921 control over which warnings are active. The string is a list of letters
7922 specifying which warnings are to be activated and which deactivated. The
7923 code for these letters is the same as the string used in the command
7924 line switch controlling warnings. For a brief summary, use the gnatmake
7925 command with no arguments, which will generate usage information containing
7926 the list of warnings switches supported. For
7927 full details see @ref{Warning Message Control,,, gnat_ugn, @value{EDITION}
7928 User's Guide}. This form can also be used as a configuration pragma.
7931 The warnings controlled by the @option{-gnatw} switch are generated by the
7932 front end of the compiler. The GCC back end can provide additional warnings
7933 and they are controlled by the @option{-W} switch. Such warnings can be
7934 identified by the appearance of a string of the form @code{[-Wxxx]} in the
7935 message which designates the @option{-Wxxx} switch that controls the message.
7936 The form with a single static_string_EXPRESSION argument also works for these
7937 warnings, but the string must be a single full @option{-Wxxx} switch in this
7938 case. The above reference lists a few examples of these additional warnings.
7941 The specified warnings will be in effect until the end of the program
7942 or another pragma Warnings is encountered. The effect of the pragma is
7943 cumulative. Initially the set of warnings is the standard default set
7944 as possibly modified by compiler switches. Then each pragma Warning
7945 modifies this set of warnings as specified. This form of the pragma may
7946 also be used as a configuration pragma.
7948 The fourth form, with an @code{On|Off} parameter and a string, is used to
7949 control individual messages, based on their text. The string argument
7950 is a pattern that is used to match against the text of individual
7951 warning messages (not including the initial "warning: " tag).
7953 The pattern may contain asterisks, which match zero or more characters in
7954 the message. For example, you can use
7955 @code{pragma Warnings (Off, "bits of*unused")} to suppress the warning
7956 message @code{warning: 960 bits of "a" unused}. No other regular
7957 expression notations are permitted. All characters other than asterisk in
7958 these three specific cases are treated as literal characters in the match.
7959 The match is case insensitive, for example XYZ matches xyz.
7961 Note that the pattern matches if it occurs anywhere within the warning
7962 message string (it is not necessary to put an asterisk at the start and
7963 the end of the message, since this is implied).
7965 The above use of patterns to match the message applies only to warning
7966 messages generated by the front end. This form of the pragma with a string
7967 argument can also be used to control warnings provided by the back end and
7968 mentioned above. By using a single full @option{-Wxxx} switch in the pragma,
7969 such warnings can be turned on and off.
7971 There are two ways to use the pragma in this form. The OFF form can be used
7972 as a configuration pragma. The effect is to suppress all warnings (if any)
7973 that match the pattern string throughout the compilation (or match the
7974 -W switch in the back end case).
7976 The second usage is to suppress a warning locally, and in this case, two
7977 pragmas must appear in sequence:
7979 @smallexample @c ada
7980 pragma Warnings (Off, Pattern);
7981 @dots{} code where given warning is to be suppressed
7982 pragma Warnings (On, Pattern);
7986 In this usage, the pattern string must match in the Off and On
7987 pragmas, and (if @option{-gnatw.w} is given) at least one matching
7988 warning must be suppressed.
7990 Note: to write a string that will match any warning, use the string
7991 @code{"***"}. It will not work to use a single asterisk or two
7992 asterisks since this looks like an operator name. This form with three
7993 asterisks is similar in effect to specifying @code{pragma Warnings
7994 (Off)} except (if @option{-gnatw.w} is given) that a matching
7995 @code{pragma Warnings (On, "***")} will be required. This can be
7996 helpful in avoiding forgetting to turn warnings back on.
7998 Note: the debug flag -gnatd.i (@code{/NOWARNINGS_PRAGMAS} in VMS) can be
7999 used to cause the compiler to entirely ignore all WARNINGS pragmas. This can
8000 be useful in checking whether obsolete pragmas in existing programs are hiding
8003 Note: pragma Warnings does not affect the processing of style messages. See
8004 separate entry for pragma Style_Checks for control of style messages.
8006 @node Pragma Weak_External
8007 @unnumberedsec Pragma Weak_External
8008 @findex Weak_External
8012 @smallexample @c ada
8013 pragma Weak_External ([Entity =>] LOCAL_NAME);
8017 @var{LOCAL_NAME} must refer to an object that is declared at the library
8018 level. This pragma specifies that the given entity should be marked as a
8019 weak symbol for the linker. It is equivalent to @code{__attribute__((weak))}
8020 in GNU C and causes @var{LOCAL_NAME} to be emitted as a weak symbol instead
8021 of a regular symbol, that is to say a symbol that does not have to be
8022 resolved by the linker if used in conjunction with a pragma Import.
8024 When a weak symbol is not resolved by the linker, its address is set to
8025 zero. This is useful in writing interfaces to external modules that may
8026 or may not be linked in the final executable, for example depending on
8027 configuration settings.
8029 If a program references at run time an entity to which this pragma has been
8030 applied, and the corresponding symbol was not resolved at link time, then
8031 the execution of the program is erroneous. It is not erroneous to take the
8032 Address of such an entity, for example to guard potential references,
8033 as shown in the example below.
8035 Some file formats do not support weak symbols so not all target machines
8036 support this pragma.
8038 @smallexample @c ada
8039 -- Example of the use of pragma Weak_External
8041 package External_Module is
8043 pragma Import (C, key);
8044 pragma Weak_External (key);
8045 function Present return boolean;
8046 end External_Module;
8048 with System; use System;
8049 package body External_Module is
8050 function Present return boolean is
8052 return key'Address /= System.Null_Address;
8054 end External_Module;
8057 @node Pragma Wide_Character_Encoding
8058 @unnumberedsec Pragma Wide_Character_Encoding
8059 @findex Wide_Character_Encoding
8063 @smallexample @c ada
8064 pragma Wide_Character_Encoding (IDENTIFIER | CHARACTER_LITERAL);
8068 This pragma specifies the wide character encoding to be used in program
8069 source text appearing subsequently. It is a configuration pragma, but may
8070 also be used at any point that a pragma is allowed, and it is permissible
8071 to have more than one such pragma in a file, allowing multiple encodings
8072 to appear within the same file.
8074 The argument can be an identifier or a character literal. In the identifier
8075 case, it is one of @code{HEX}, @code{UPPER}, @code{SHIFT_JIS},
8076 @code{EUC}, @code{UTF8}, or @code{BRACKETS}. In the character literal
8077 case it is correspondingly one of the characters @samp{h}, @samp{u},
8078 @samp{s}, @samp{e}, @samp{8}, or @samp{b}.
8080 Note that when the pragma is used within a file, it affects only the
8081 encoding within that file, and does not affect withed units, specs,
8084 @node Implementation Defined Aspects
8085 @chapter Implementation Defined Aspects
8086 Ada defines (throughout the Ada 2012 reference manual, summarized
8087 in Annex K) a set of aspects that can be specified for certain entities.
8088 These language defined aspects are implemented in GNAT in Ada 2012 mode
8089 and work as described in the Ada 2012 Reference Manual.
8091 In addition, Ada 2012 allows implementations to define additional aspects
8092 whose meaning is defined by the implementation. GNAT provides
8093 a number of these implementation-defined aspects which can be used
8094 to extend and enhance the functionality of the compiler. This section of
8095 the GNAT reference manual describes these additional aspects.
8097 Note that any program using these aspects may not be portable to
8098 other compilers (although GNAT implements this set of aspects on all
8099 platforms). Therefore if portability to other compilers is an important
8100 consideration, you should minimize the use of these aspects.
8102 Note that for many of these aspects, the effect is essentially similar
8103 to the use of a pragma or attribute specification with the same name
8104 applied to the entity. For example, if we write:
8106 @smallexample @c ada
8107 type R is range 1 .. 100
8108 with Value_Size => 10;
8112 then the effect is the same as:
8114 @smallexample @c ada
8115 type R is range 1 .. 100;
8116 for R'Value_Size use 10;
8122 @smallexample @c ada
8123 type R is new Integer
8124 with Shared => True;
8128 then the effect is the same as:
8130 @smallexample @c ada
8131 type R is new Integer;
8136 In the documentation below, such cases are simply marked
8137 as being boolean aspects equivalent to the corresponding pragma
8138 or attribute definition clause.
8141 * Aspect Abstract_State::
8143 * Aspect Async_Readers::
8144 * Aspect Async_Writers::
8145 * Aspect Contract_Cases::
8147 * Aspect Dimension::
8148 * Aspect Dimension_System::
8149 * Aspect Effective_Reads::
8150 * Aspect Effective_Writes::
8151 * Aspect Favor_Top_Level::
8153 * Aspect Initial_Condition::
8154 * Aspect Initializes::
8155 * Aspect Inline_Always::
8156 * Aspect Invariant::
8157 * Aspect Invariant'Class::
8159 * Aspect Linker_Section::
8160 * Aspect Lock_Free::
8161 * Aspect No_Elaboration_Code_All::
8162 * Aspect No_Tagged_Streams::
8163 * Aspect Object_Size::
8164 * Aspect Obsolescent::
8166 * Aspect Persistent_BSS::
8167 * Aspect Predicate::
8168 * Aspect Pure_Function::
8169 * Aspect Refined_Depends::
8170 * Aspect Refined_Global::
8171 * Aspect Refined_Post::
8172 * Aspect Refined_State::
8173 * Aspect Remote_Access_Type::
8174 * Aspect Scalar_Storage_Order::
8176 * Aspect Simple_Storage_Pool::
8177 * Aspect Simple_Storage_Pool_Type::
8178 * Aspect SPARK_Mode::
8179 * Aspect Suppress_Debug_Info::
8180 * Aspect Suppress_Initialization::
8181 * Aspect Test_Case::
8182 * Aspect Thread_Local_Storage::
8183 * Aspect Universal_Aliasing::
8184 * Aspect Universal_Data::
8185 * Aspect Unmodified::
8186 * Aspect Unreferenced::
8187 * Aspect Unreferenced_Objects::
8188 * Aspect Value_Size::
8192 @node Aspect Abstract_State
8193 @unnumberedsec Aspect Abstract_State
8194 @findex Abstract_State
8196 This aspect is equivalent to pragma @code{Abstract_State}.
8198 @node Aspect Annotate
8199 @unnumberedsec Annotate
8202 There are three forms of this aspect (where ID is an identifier,
8203 and ARG is a general expression).
8206 @item Annotate => ID
8207 Equivalent to @code{pragma Annotate (ID, Entity => Name);}
8209 @item Annotate => (ID)
8210 Equivalent to @code{pragma Annotate (ID, Entity => Name);}
8212 @item Annotate => (ID ,ID @{, ARG@})
8213 Equivalent to @code{pragma Annotate (ID, ID @{, ARG@}, Entity => Name);}
8216 @node Aspect Async_Readers
8217 @unnumberedsec Aspect Async_Readers
8218 @findex Async_Readers
8220 This boolean aspect is equivalent to pragma @code{Async_Readers}.
8222 @node Aspect Async_Writers
8223 @unnumberedsec Aspect Async_Writers
8224 @findex Async_Writers
8226 This boolean aspect is equivalent to pragma @code{Async_Writers}.
8228 @node Aspect Contract_Cases
8229 @unnumberedsec Aspect Contract_Cases
8230 @findex Contract_Cases
8232 This aspect is equivalent to pragma @code{Contract_Cases}, the sequence
8233 of clauses being enclosed in parentheses so that syntactically it is an
8236 @node Aspect Depends
8237 @unnumberedsec Aspect Depends
8240 This aspect is equivalent to pragma @code{Depends}.
8242 @node Aspect Dimension
8243 @unnumberedsec Aspect Dimension
8246 The @code{Dimension} aspect is used to specify the dimensions of a given
8247 subtype of a dimensioned numeric type. The aspect also specifies a symbol
8248 used when doing formatted output of dimensioned quantities. The syntax is:
8250 @smallexample @c ada
8252 ([Symbol =>] SYMBOL, DIMENSION_VALUE @{, DIMENSION_Value@})
8254 SYMBOL ::= STRING_LITERAL | CHARACTER_LITERAL
8258 | others => RATIONAL
8259 | DISCRETE_CHOICE_LIST => RATIONAL
8261 RATIONAL ::= [-] NUMERIC_LITERAL [/ NUMERIC_LITERAL]
8265 This aspect can only be applied to a subtype whose parent type has
8266 a @code{Dimension_Systen} aspect. The aspect must specify values for
8267 all dimensions of the system. The rational values are the powers of the
8268 corresponding dimensions that are used by the compiler to verify that
8269 physical (numeric) computations are dimensionally consistent. For example,
8270 the computation of a force must result in dimensions (L => 1, M => 1, T => -2).
8271 For further examples of the usage
8272 of this aspect, see package @code{System.Dim.Mks}.
8273 Note that when the dimensioned type is an integer type, then any
8274 dimension value must be an integer literal.
8276 @node Aspect Dimension_System
8277 @unnumberedsec Aspect Dimension_System
8278 @findex Dimension_System
8280 The @code{Dimension_System} aspect is used to define a system of
8281 dimensions that will be used in subsequent subtype declarations with
8282 @code{Dimension} aspects that reference this system. The syntax is:
8284 @smallexample @c ada
8285 with Dimension_System => (DIMENSION @{, DIMENSION@});
8287 DIMENSION ::= ([Unit_Name =>] IDENTIFIER,
8288 [Unit_Symbol =>] SYMBOL,
8289 [Dim_Symbol =>] SYMBOL)
8291 SYMBOL ::= CHARACTER_LITERAL | STRING_LITERAL
8295 This aspect is applied to a type, which must be a numeric derived type
8296 (typically a floating-point type), that
8297 will represent values within the dimension system. Each @code{DIMENSION}
8298 corresponds to one particular dimension. A maximum of 7 dimensions may
8299 be specified. @code{Unit_Name} is the name of the dimension (for example
8300 @code{Meter}). @code{Unit_Symbol} is the shorthand used for quantities
8301 of this dimension (for example @code{m} for @code{Meter}).
8302 @code{Dim_Symbol} gives
8303 the identification within the dimension system (typically this is a
8304 single letter, e.g. @code{L} standing for length for unit name @code{Meter}).
8305 The @code{Unit_Symbol} is used in formatted output of dimensioned quantities.
8306 The @code{Dim_Symbol} is used in error messages when numeric operations have
8307 inconsistent dimensions.
8309 GNAT provides the standard definition of the International MKS system in
8310 the run-time package @code{System.Dim.Mks}. You can easily define
8311 similar packages for cgs units or British units, and define conversion factors
8312 between values in different systems. The MKS system is characterized by the
8315 @smallexample @c ada
8316 type Mks_Type is new Long_Long_Float with
8317 Dimension_System => (
8318 (Unit_Name => Meter, Unit_Symbol => 'm', Dim_Symbol => 'L'),
8319 (Unit_Name => Kilogram, Unit_Symbol => "kg", Dim_Symbol => 'M'),
8320 (Unit_Name => Second, Unit_Symbol => 's', Dim_Symbol => 'T'),
8321 (Unit_Name => Ampere, Unit_Symbol => 'A', Dim_Symbol => 'I'),
8322 (Unit_Name => Kelvin, Unit_Symbol => 'K', Dim_Symbol => '@'),
8323 (Unit_Name => Mole, Unit_Symbol => "mol", Dim_Symbol => 'N'),
8324 (Unit_Name => Candela, Unit_Symbol => "cd", Dim_Symbol => 'J'));
8328 Note that in the above type definition, we use the symbol @code{@@} to
8329 represent a theta character (avoiding the use of extended Latin-1
8330 characters in this context).
8332 See section ``Performing Dimensionality Analysis in GNAT'' in the GNAT Users
8333 Guide for detailed examples of use of the dimension system.
8335 @node Aspect Effective_Reads
8336 @unnumberedsec Aspect Effective_Reads
8337 @findex Effective_Reads
8339 This aspect is equivalent to pragma @code{Effective_Reads}.
8341 @node Aspect Effective_Writes
8342 @unnumberedsec Aspect Effective_Writes
8343 @findex Effective_Writes
8345 This aspect is equivalent to pragma @code{Effective_Writes}.
8347 @node Aspect Favor_Top_Level
8348 @unnumberedsec Aspect Favor_Top_Level
8349 @findex Favor_Top_Level
8351 This boolean aspect is equivalent to pragma @code{Favor_Top_Level}.
8354 @unnumberedsec Aspect Global
8357 This aspect is equivalent to pragma @code{Global}.
8359 @node Aspect Initial_Condition
8360 @unnumberedsec Aspect Initial_Condition
8361 @findex Initial_Condition
8363 This aspect is equivalent to pragma @code{Initial_Condition}.
8365 @node Aspect Initializes
8366 @unnumberedsec Aspect Initializes
8369 This aspect is equivalent to pragma @code{Initializes}.
8371 @node Aspect Inline_Always
8372 @unnumberedsec Aspect Inline_Always
8373 @findex Inline_Always
8375 This boolean aspect is equivalent to pragma @code{Inline_Always}.
8377 @node Aspect Invariant
8378 @unnumberedsec Aspect Invariant
8381 This aspect is equivalent to pragma @code{Invariant}. It is a
8382 synonym for the language defined aspect @code{Type_Invariant} except
8383 that it is separately controllable using pragma @code{Assertion_Policy}.
8385 @node Aspect Invariant'Class
8386 @unnumberedsec Aspect Invariant'Class
8387 @findex Invariant'Class
8389 This aspect is equivalent to pragma @code{Type_Invariant_Class}. It is a
8390 synonym for the language defined aspect @code{Type_Invariant'Class} except
8391 that it is separately controllable using pragma @code{Assertion_Policy}.
8393 @node Aspect Iterable
8394 @unnumberedsec Aspect Iterable
8397 This aspect is used in the GNAT-defined formal container packages, to provide
8398 a light-weight mechanism for loops over such containers, without the overhead
8399 imposed by the tampering checks of standard Ada2012 iterators. The value of the
8400 aspect is a aggregate with four named components: First, Next, Has_Element,
8401 and Element. The following is a typical example of use:
8403 @smallexample @c ada
8404 type List is private with
8405 Iterable => (First => First_Element,
8407 Has_Element => Get_Element,
8408 Element => List_Element);
8411 @item The value denoted by @code{First} must denote a primitive operation of
8412 the container type that returns a Cursor, which must a be a type declared in
8413 the container package.
8414 @item The value of @code{Next} is a primitive operation of the container type
8415 that takes a cursor and yields a cursor.
8416 @item @code{Has_Element} is an operation that applies to a cursor a yields an
8417 element of the container.
8418 @item @code{Element} is the type of the elements of the container type, and
8419 thus the result of the function denoted by Has_Element.
8422 @node Aspect Linker_Section
8423 @unnumberedsec Aspect Linker_Section
8424 @findex Linker_Section
8426 This aspect is equivalent to an @code{Linker_Section} pragma.
8428 @node Aspect Lock_Free
8429 @unnumberedsec Aspect Lock_Free
8432 This boolean aspect is equivalent to pragma @code{Lock_Free}.
8434 @node Aspect No_Elaboration_Code_All
8435 @unnumberedsec Aspect No_Elaboration_Code_All
8436 @findex No_Elaboration_Code_All
8438 This aspect is equivalent to a @code{pragma No_Elaboration_Code_All}
8439 statement for a program unit.
8441 @node Aspect No_Tagged_Streams
8442 @unnumberedsec Aspect No_Tagged_Streams
8443 @findex No_Tagged_Streams
8445 This aspect is equivalent to a @code{pragma No_Tagged_Streams} with an
8446 argument specifying a root tagged type (thus this aspect can only be
8447 applied to such a type).
8449 @node Aspect Object_Size
8450 @unnumberedsec Aspect Object_Size
8453 This aspect is equivalent to an @code{Object_Size} attribute definition
8456 @node Aspect Obsolescent
8457 @unnumberedsec Aspect Obsolescent
8460 This aspect is equivalent to an @code{Obsolescent} pragma. Note that the
8461 evaluation of this aspect happens at the point of occurrence, it is not
8462 delayed until the freeze point.
8464 @node Aspect Part_Of
8465 @unnumberedsec Aspect Part_Of
8468 This aspect is equivalent to pragma @code{Part_Of}.
8470 @node Aspect Persistent_BSS
8471 @unnumberedsec Aspect Persistent_BSS
8472 @findex Persistent_BSS
8474 This boolean aspect is equivalent to pragma @code{Persistent_BSS}.
8476 @node Aspect Predicate
8477 @unnumberedsec Aspect Predicate
8480 This aspect is equivalent to pragma @code{Predicate}. It is thus
8481 similar to the language defined aspects @code{Dynamic_Predicate}
8482 and @code{Static_Predicate} except that whether the resulting
8483 predicate is static or dynamic is controlled by the form of the
8484 expression. It is also separately controllable using pragma
8485 @code{Assertion_Policy}.
8487 @node Aspect Pure_Function
8488 @unnumberedsec Aspect Pure_Function
8489 @findex Pure_Function
8491 This boolean aspect is equivalent to pragma @code{Pure_Function}.
8493 @node Aspect Refined_Depends
8494 @unnumberedsec Aspect Refined_Depends
8495 @findex Refined_Depends
8497 This aspect is equivalent to pragma @code{Refined_Depends}.
8499 @node Aspect Refined_Global
8500 @unnumberedsec Aspect Refined_Global
8501 @findex Refined_Global
8503 This aspect is equivalent to pragma @code{Refined_Global}.
8505 @node Aspect Refined_Post
8506 @unnumberedsec Aspect Refined_Post
8507 @findex Refined_Post
8509 This aspect is equivalent to pragma @code{Refined_Post}.
8511 @node Aspect Refined_State
8512 @unnumberedsec Aspect Refined_State
8513 @findex Refined_State
8515 This aspect is equivalent to pragma @code{Refined_State}.
8517 @node Aspect Remote_Access_Type
8518 @unnumberedsec Aspect Remote_Access_Type
8519 @findex Remote_Access_Type
8521 This aspect is equivalent to pragma @code{Remote_Access_Type}.
8523 @node Aspect Scalar_Storage_Order
8524 @unnumberedsec Aspect Scalar_Storage_Order
8525 @findex Scalar_Storage_Order
8527 This aspect is equivalent to a @code{Scalar_Storage_Order}
8528 attribute definition clause.
8531 @unnumberedsec Aspect Shared
8534 This booleanaspect is equivalent to pragma @code{Shared},
8535 and is thus a synonym for aspect @code{Atomic}.
8537 @node Aspect Simple_Storage_Pool
8538 @unnumberedsec Aspect Simple_Storage_Pool
8539 @findex Simple_Storage_Pool
8541 This aspect is equivalent to a @code{Simple_Storage_Pool}
8542 attribute definition clause.
8544 @node Aspect Simple_Storage_Pool_Type
8545 @unnumberedsec Aspect Simple_Storage_Pool_Type
8546 @findex Simple_Storage_Pool_Type
8548 This boolean aspect is equivalent to pragma @code{Simple_Storage_Pool_Type}.
8550 @node Aspect SPARK_Mode
8551 @unnumberedsec Aspect SPARK_Mode
8554 This aspect is equivalent to pragma @code{SPARK_Mode} and
8555 may be specified for either or both of the specification and body
8556 of a subprogram or package.
8558 @node Aspect Suppress_Debug_Info
8559 @unnumberedsec Aspect Suppress_Debug_Info
8560 @findex Suppress_Debug_Info
8562 This boolean aspect is equivalent to pragma @code{Suppress_Debug_Info}.
8564 @node Aspect Suppress_Initialization
8565 @unnumberedsec Aspect Suppress_Initialization
8566 @findex Suppress_Initialization
8568 This boolean aspect is equivalent to pragma @code{Suppress_Initialization}.
8570 @node Aspect Test_Case
8571 @unnumberedsec Aspect Test_Case
8574 This aspect is equivalent to pragma @code{Test_Case}.
8576 @node Aspect Thread_Local_Storage
8577 @unnumberedsec Aspect Thread_Local_Storage
8578 @findex Thread_Local_Storage
8580 This boolean aspect is equivalent to pragma @code{Thread_Local_Storage}.
8582 @node Aspect Universal_Aliasing
8583 @unnumberedsec Aspect Universal_Aliasing
8584 @findex Universal_Aliasing
8586 This boolean aspect is equivalent to pragma @code{Universal_Aliasing}.
8588 @node Aspect Universal_Data
8589 @unnumberedsec Aspect Universal_Data
8590 @findex Universal_Data
8592 This aspect is equivalent to pragma @code{Universal_Data}.
8594 @node Aspect Unmodified
8595 @unnumberedsec Aspect Unmodified
8598 This boolean aspect is equivalent to pragma @code{Unmodified}.
8600 @node Aspect Unreferenced
8601 @unnumberedsec Aspect Unreferenced
8602 @findex Unreferenced
8604 This boolean aspect is equivalent to pragma @code{Unreferenced}. Note that
8605 in the case of formal parameters, it is not permitted to have aspects for
8606 a formal parameter, so in this case the pragma form must be used.
8608 @node Aspect Unreferenced_Objects
8609 @unnumberedsec Aspect Unreferenced_Objects
8610 @findex Unreferenced_Objects
8612 This boolean aspect is equivalent to pragma @code{Unreferenced_Objects}.
8614 @node Aspect Value_Size
8615 @unnumberedsec Aspect Value_Size
8618 This aspect is equivalent to a @code{Value_Size}
8619 attribute definition clause.
8621 @node Aspect Warnings
8622 @unnumberedsec Aspect Warnings
8625 This aspect is equivalent to the two argument form of pragma @code{Warnings},
8626 where the first argument is @code{ON} or @code{OFF} and the second argument
8630 @node Implementation Defined Attributes
8631 @chapter Implementation Defined Attributes
8632 Ada defines (throughout the Ada reference manual,
8633 summarized in Annex K),
8634 a set of attributes that provide useful additional functionality in all
8635 areas of the language. These language defined attributes are implemented
8636 in GNAT and work as described in the Ada Reference Manual.
8638 In addition, Ada allows implementations to define additional
8639 attributes whose meaning is defined by the implementation. GNAT provides
8640 a number of these implementation-dependent attributes which can be used
8641 to extend and enhance the functionality of the compiler. This section of
8642 the GNAT reference manual describes these additional attributes. It also
8643 describes additional implementation-dependent features of standard
8644 language-defined attributes.
8646 Note that any program using these attributes may not be portable to
8647 other compilers (although GNAT implements this set of attributes on all
8648 platforms). Therefore if portability to other compilers is an important
8649 consideration, you should minimize the use of these attributes.
8652 * Attribute Abort_Signal::
8653 * Attribute Address_Size::
8654 * Attribute Asm_Input::
8655 * Attribute Asm_Output::
8656 * Attribute AST_Entry::
8657 * Attribute Atomic_Always_Lock_Free::
8659 * Attribute Bit_Position::
8660 * Attribute Code_Address::
8661 * Attribute Compiler_Version::
8662 * Attribute Constrained::
8663 * Attribute Default_Bit_Order::
8664 * Attribute Default_Scalar_Storage_Order::
8665 * Attribute Descriptor_Size::
8666 * Attribute Elaborated::
8667 * Attribute Elab_Body::
8668 * Attribute Elab_Spec::
8669 * Attribute Elab_Subp_Body::
8671 * Attribute Enabled::
8672 * Attribute Enum_Rep::
8673 * Attribute Enum_Val::
8674 * Attribute Epsilon::
8675 * Attribute Fast_Math::
8676 * Attribute Fixed_Value::
8677 * Attribute From_Any::
8678 * Attribute Has_Access_Values::
8679 * Attribute Has_Discriminants::
8681 * Attribute Integer_Value::
8682 * Attribute Invalid_Value::
8683 * Attribute Iterable::
8685 * Attribute Library_Level::
8686 * Attribute Lock_Free::
8687 * Attribute Loop_Entry::
8688 * Attribute Machine_Size::
8689 * Attribute Mantissa::
8690 * Attribute Maximum_Alignment::
8691 * Attribute Mechanism_Code::
8692 * Attribute Null_Parameter::
8693 * Attribute Object_Size::
8695 * Attribute Passed_By_Reference::
8696 * Attribute Pool_Address::
8697 * Attribute Range_Length::
8699 * Attribute Restriction_Set::
8700 * Attribute Result::
8701 * Attribute Safe_Emax::
8702 * Attribute Safe_Large::
8703 * Attribute Safe_Small::
8704 * Attribute Scalar_Storage_Order::
8705 * Attribute Simple_Storage_Pool::
8707 * Attribute Storage_Unit::
8708 * Attribute Stub_Type::
8709 * Attribute System_Allocator_Alignment::
8710 * Attribute Target_Name::
8711 * Attribute To_Address::
8712 * Attribute To_Any::
8713 * Attribute Type_Class::
8714 * Attribute Type_Key::
8715 * Attribute TypeCode::
8716 * Attribute UET_Address::
8717 * Attribute Unconstrained_Array::
8718 * Attribute Universal_Literal_String::
8719 * Attribute Unrestricted_Access::
8720 * Attribute Update::
8721 * Attribute VADS_Size::
8722 * Attribute Valid_Scalars::
8723 * Attribute Value_Size::
8724 * Attribute Wchar_T_Size::
8725 * Attribute Word_Size::
8728 @node Attribute Abort_Signal
8729 @unnumberedsec Attribute Abort_Signal
8730 @findex Abort_Signal
8732 @code{Standard'Abort_Signal} (@code{Standard} is the only allowed
8733 prefix) provides the entity for the special exception used to signal
8734 task abort or asynchronous transfer of control. Normally this attribute
8735 should only be used in the tasking runtime (it is highly peculiar, and
8736 completely outside the normal semantics of Ada, for a user program to
8737 intercept the abort exception).
8739 @node Attribute Address_Size
8740 @unnumberedsec Attribute Address_Size
8741 @cindex Size of @code{Address}
8742 @findex Address_Size
8744 @code{Standard'Address_Size} (@code{Standard} is the only allowed
8745 prefix) is a static constant giving the number of bits in an
8746 @code{Address}. It is the same value as System.Address'Size,
8747 but has the advantage of being static, while a direct
8748 reference to System.Address'Size is non-static because Address
8751 @node Attribute Asm_Input
8752 @unnumberedsec Attribute Asm_Input
8755 The @code{Asm_Input} attribute denotes a function that takes two
8756 parameters. The first is a string, the second is an expression of the
8757 type designated by the prefix. The first (string) argument is required
8758 to be a static expression, and is the constraint for the parameter,
8759 (e.g.@: what kind of register is required). The second argument is the
8760 value to be used as the input argument. The possible values for the
8761 constant are the same as those used in the RTL, and are dependent on
8762 the configuration file used to built the GCC back end.
8763 @ref{Machine Code Insertions}
8765 @node Attribute Asm_Output
8766 @unnumberedsec Attribute Asm_Output
8769 The @code{Asm_Output} attribute denotes a function that takes two
8770 parameters. The first is a string, the second is the name of a variable
8771 of the type designated by the attribute prefix. The first (string)
8772 argument is required to be a static expression and designates the
8773 constraint for the parameter (e.g.@: what kind of register is
8774 required). The second argument is the variable to be updated with the
8775 result. The possible values for constraint are the same as those used in
8776 the RTL, and are dependent on the configuration file used to build the
8777 GCC back end. If there are no output operands, then this argument may
8778 either be omitted, or explicitly given as @code{No_Output_Operands}.
8779 @ref{Machine Code Insertions}
8781 @node Attribute AST_Entry
8782 @unnumberedsec Attribute AST_Entry
8786 This attribute is implemented only in OpenVMS versions of GNAT@. Applied to
8787 the name of an entry, it yields a value of the predefined type AST_Handler
8788 (declared in the predefined package System, as extended by the use of
8789 pragma @code{Extend_System (Aux_DEC)}). This value enables the given entry to
8790 be called when an AST occurs. For further details, refer to the @cite{DEC Ada
8791 Language Reference Manual}, section 9.12a.
8793 @node Attribute Atomic_Always_Lock_Free
8794 @unnumberedsec Attribute Atomic_Always_Lock_Free
8795 @findex Atomic_Always_Lock_Free
8798 The prefix of the @code{Atomic_Always_Lock_Free} attribute is a type.
8799 The result is a Boolean value which is True if the type has discriminants,
8800 and False otherwise. The result indicate whether atomic operations are
8801 supported by the target for the given type.
8804 @unnumberedsec Attribute Bit
8806 @code{@var{obj}'Bit}, where @var{obj} is any object, yields the bit
8807 offset within the storage unit (byte) that contains the first bit of
8808 storage allocated for the object. The value of this attribute is of the
8809 type @code{Universal_Integer}, and is always a non-negative number not
8810 exceeding the value of @code{System.Storage_Unit}.
8812 For an object that is a variable or a constant allocated in a register,
8813 the value is zero. (The use of this attribute does not force the
8814 allocation of a variable to memory).
8816 For an object that is a formal parameter, this attribute applies
8817 to either the matching actual parameter or to a copy of the
8818 matching actual parameter.
8820 For an access object the value is zero. Note that
8821 @code{@var{obj}.all'Bit} is subject to an @code{Access_Check} for the
8822 designated object. Similarly for a record component
8823 @code{@var{X}.@var{C}'Bit} is subject to a discriminant check and
8824 @code{@var{X}(@var{I}).Bit} and @code{@var{X}(@var{I1}..@var{I2})'Bit}
8825 are subject to index checks.
8827 This attribute is designed to be compatible with the DEC Ada 83 definition
8828 and implementation of the @code{Bit} attribute.
8830 @node Attribute Bit_Position
8831 @unnumberedsec Attribute Bit_Position
8832 @findex Bit_Position
8834 @code{@var{R.C}'Bit_Position}, where @var{R} is a record object and C is one
8835 of the fields of the record type, yields the bit
8836 offset within the record contains the first bit of
8837 storage allocated for the object. The value of this attribute is of the
8838 type @code{Universal_Integer}. The value depends only on the field
8839 @var{C} and is independent of the alignment of
8840 the containing record @var{R}.
8842 @node Attribute Code_Address
8843 @unnumberedsec Attribute Code_Address
8844 @findex Code_Address
8845 @cindex Subprogram address
8846 @cindex Address of subprogram code
8849 attribute may be applied to subprograms in Ada 95 and Ada 2005, but the
8850 intended effect seems to be to provide
8851 an address value which can be used to call the subprogram by means of
8852 an address clause as in the following example:
8854 @smallexample @c ada
8855 procedure K is @dots{}
8858 for L'Address use K'Address;
8859 pragma Import (Ada, L);
8863 A call to @code{L} is then expected to result in a call to @code{K}@.
8864 In Ada 83, where there were no access-to-subprogram values, this was
8865 a common work-around for getting the effect of an indirect call.
8866 GNAT implements the above use of @code{Address} and the technique
8867 illustrated by the example code works correctly.
8869 However, for some purposes, it is useful to have the address of the start
8870 of the generated code for the subprogram. On some architectures, this is
8871 not necessarily the same as the @code{Address} value described above.
8872 For example, the @code{Address} value may reference a subprogram
8873 descriptor rather than the subprogram itself.
8875 The @code{'Code_Address} attribute, which can only be applied to
8876 subprogram entities, always returns the address of the start of the
8877 generated code of the specified subprogram, which may or may not be
8878 the same value as is returned by the corresponding @code{'Address}
8881 @node Attribute Compiler_Version
8882 @unnumberedsec Attribute Compiler_Version
8883 @findex Compiler_Version
8885 @code{Standard'Compiler_Version} (@code{Standard} is the only allowed
8886 prefix) yields a static string identifying the version of the compiler
8887 being used to compile the unit containing the attribute reference. A
8888 typical result would be something like
8889 "@value{EDITION} @value{gnat_version} (20090221)".
8891 @node Attribute Constrained
8892 @unnumberedsec Attribute Constrained
8895 In addition to the usage of this attribute in the Ada RM, @code{GNAT}
8896 also permits the use of the @code{'Constrained} attribute
8897 in a generic template
8898 for any type, including types without discriminants. The value of this
8899 attribute in the generic instance when applied to a scalar type or a
8900 record type without discriminants is always @code{True}. This usage is
8901 compatible with older Ada compilers, including notably DEC Ada.
8903 @node Attribute Default_Bit_Order
8904 @unnumberedsec Attribute Default_Bit_Order
8906 @cindex Little endian
8907 @findex Default_Bit_Order
8909 @code{Standard'Default_Bit_Order} (@code{Standard} is the only
8910 permissible prefix), provides the value @code{System.Default_Bit_Order}
8911 as a @code{Pos} value (0 for @code{High_Order_First}, 1 for
8912 @code{Low_Order_First}). This is used to construct the definition of
8913 @code{Default_Bit_Order} in package @code{System}.
8915 @node Attribute Default_Scalar_Storage_Order
8916 @unnumberedsec Attribute Default_Scalar_Storage_Order
8918 @cindex Little endian
8919 @findex Default_Scalar_Storage_Order
8921 @code{Standard'Default_Scalar_Storage_Order} (@code{Standard} is the only
8922 permissible prefix), provides the current value of the default scalar storage
8923 order (as specified using pragma @code{Default_Scalar_Storage_Order}, or
8924 equal to @code{Default_Bit_Order} if unspecified) as a
8925 @code{System.Bit_Order} value. This is a static attribute.
8927 @node Attribute Descriptor_Size
8928 @unnumberedsec Attribute Descriptor_Size
8931 @findex Descriptor_Size
8933 Non-static attribute @code{Descriptor_Size} returns the size in bits of the
8934 descriptor allocated for a type. The result is non-zero only for unconstrained
8935 array types and the returned value is of type universal integer. In GNAT, an
8936 array descriptor contains bounds information and is located immediately before
8937 the first element of the array.
8939 @smallexample @c ada
8940 type Unconstr_Array is array (Positive range <>) of Boolean;
8941 Put_Line ("Descriptor size = " & Unconstr_Array'Descriptor_Size'Img);
8945 The attribute takes into account any additional padding due to type alignment.
8946 In the example above, the descriptor contains two values of type
8947 @code{Positive} representing the low and high bound. Since @code{Positive} has
8948 a size of 31 bits and an alignment of 4, the descriptor size is @code{2 *
8949 Positive'Size + 2} or 64 bits.
8951 @node Attribute Elaborated
8952 @unnumberedsec Attribute Elaborated
8955 The prefix of the @code{'Elaborated} attribute must be a unit name. The
8956 value is a Boolean which indicates whether or not the given unit has been
8957 elaborated. This attribute is primarily intended for internal use by the
8958 generated code for dynamic elaboration checking, but it can also be used
8959 in user programs. The value will always be True once elaboration of all
8960 units has been completed. An exception is for units which need no
8961 elaboration, the value is always False for such units.
8963 @node Attribute Elab_Body
8964 @unnumberedsec Attribute Elab_Body
8967 This attribute can only be applied to a program unit name. It returns
8968 the entity for the corresponding elaboration procedure for elaborating
8969 the body of the referenced unit. This is used in the main generated
8970 elaboration procedure by the binder and is not normally used in any
8971 other context. However, there may be specialized situations in which it
8972 is useful to be able to call this elaboration procedure from Ada code,
8973 e.g.@: if it is necessary to do selective re-elaboration to fix some
8976 @node Attribute Elab_Spec
8977 @unnumberedsec Attribute Elab_Spec
8980 This attribute can only be applied to a program unit name. It returns
8981 the entity for the corresponding elaboration procedure for elaborating
8982 the spec of the referenced unit. This is used in the main
8983 generated elaboration procedure by the binder and is not normally used
8984 in any other context. However, there may be specialized situations in
8985 which it is useful to be able to call this elaboration procedure from
8986 Ada code, e.g.@: if it is necessary to do selective re-elaboration to fix
8989 @node Attribute Elab_Subp_Body
8990 @unnumberedsec Attribute Elab_Subp_Body
8991 @findex Elab_Subp_Body
8993 This attribute can only be applied to a library level subprogram
8994 name and is only allowed in CodePeer mode. It returns the entity
8995 for the corresponding elaboration procedure for elaborating the body
8996 of the referenced subprogram unit. This is used in the main generated
8997 elaboration procedure by the binder in CodePeer mode only and is unrecognized
9000 @node Attribute Emax
9001 @unnumberedsec Attribute Emax
9002 @cindex Ada 83 attributes
9005 The @code{Emax} attribute is provided for compatibility with Ada 83. See
9006 the Ada 83 reference manual for an exact description of the semantics of
9009 @node Attribute Enabled
9010 @unnumberedsec Attribute Enabled
9013 The @code{Enabled} attribute allows an application program to check at compile
9014 time to see if the designated check is currently enabled. The prefix is a
9015 simple identifier, referencing any predefined check name (other than
9016 @code{All_Checks}) or a check name introduced by pragma Check_Name. If
9017 no argument is given for the attribute, the check is for the general state
9018 of the check, if an argument is given, then it is an entity name, and the
9019 check indicates whether an @code{Suppress} or @code{Unsuppress} has been
9020 given naming the entity (if not, then the argument is ignored).
9022 Note that instantiations inherit the check status at the point of the
9023 instantiation, so a useful idiom is to have a library package that
9024 introduces a check name with @code{pragma Check_Name}, and then contains
9025 generic packages or subprograms which use the @code{Enabled} attribute
9026 to see if the check is enabled. A user of this package can then issue
9027 a @code{pragma Suppress} or @code{pragma Unsuppress} before instantiating
9028 the package or subprogram, controlling whether the check will be present.
9030 @node Attribute Enum_Rep
9031 @unnumberedsec Attribute Enum_Rep
9032 @cindex Representation of enums
9035 For every enumeration subtype @var{S}, @code{@var{S}'Enum_Rep} denotes a
9036 function with the following spec:
9038 @smallexample @c ada
9039 function @var{S}'Enum_Rep (Arg : @var{S}'Base)
9040 return @i{Universal_Integer};
9044 It is also allowable to apply @code{Enum_Rep} directly to an object of an
9045 enumeration type or to a non-overloaded enumeration
9046 literal. In this case @code{@var{S}'Enum_Rep} is equivalent to
9047 @code{@var{typ}'Enum_Rep(@var{S})} where @var{typ} is the type of the
9048 enumeration literal or object.
9050 The function returns the representation value for the given enumeration
9051 value. This will be equal to value of the @code{Pos} attribute in the
9052 absence of an enumeration representation clause. This is a static
9053 attribute (i.e.@: the result is static if the argument is static).
9055 @code{@var{S}'Enum_Rep} can also be used with integer types and objects,
9056 in which case it simply returns the integer value. The reason for this
9057 is to allow it to be used for @code{(<>)} discrete formal arguments in
9058 a generic unit that can be instantiated with either enumeration types
9059 or integer types. Note that if @code{Enum_Rep} is used on a modular
9060 type whose upper bound exceeds the upper bound of the largest signed
9061 integer type, and the argument is a variable, so that the universal
9062 integer calculation is done at run time, then the call to @code{Enum_Rep}
9063 may raise @code{Constraint_Error}.
9065 @node Attribute Enum_Val
9066 @unnumberedsec Attribute Enum_Val
9067 @cindex Representation of enums
9070 For every enumeration subtype @var{S}, @code{@var{S}'Enum_Val} denotes a
9071 function with the following spec:
9073 @smallexample @c ada
9074 function @var{S}'Enum_Val (Arg : @i{Universal_Integer)
9075 return @var{S}'Base};
9079 The function returns the enumeration value whose representation matches the
9080 argument, or raises Constraint_Error if no enumeration literal of the type
9081 has the matching value.
9082 This will be equal to value of the @code{Val} attribute in the
9083 absence of an enumeration representation clause. This is a static
9084 attribute (i.e.@: the result is static if the argument is static).
9086 @node Attribute Epsilon
9087 @unnumberedsec Attribute Epsilon
9088 @cindex Ada 83 attributes
9091 The @code{Epsilon} attribute is provided for compatibility with Ada 83. See
9092 the Ada 83 reference manual for an exact description of the semantics of
9095 @node Attribute Fast_Math
9096 @unnumberedsec Attribute Fast_Math
9099 @code{Standard'Fast_Math} (@code{Standard} is the only allowed
9100 prefix) yields a static Boolean value that is True if pragma
9101 @code{Fast_Math} is active, and False otherwise.
9103 @node Attribute Fixed_Value
9104 @unnumberedsec Attribute Fixed_Value
9107 For every fixed-point type @var{S}, @code{@var{S}'Fixed_Value} denotes a
9108 function with the following specification:
9110 @smallexample @c ada
9111 function @var{S}'Fixed_Value (Arg : @i{Universal_Integer})
9116 The value returned is the fixed-point value @var{V} such that
9118 @smallexample @c ada
9119 @var{V} = Arg * @var{S}'Small
9123 The effect is thus similar to first converting the argument to the
9124 integer type used to represent @var{S}, and then doing an unchecked
9125 conversion to the fixed-point type. The difference is
9126 that there are full range checks, to ensure that the result is in range.
9127 This attribute is primarily intended for use in implementation of the
9128 input-output functions for fixed-point values.
9130 @node Attribute From_Any
9131 @unnumberedsec Attribute From_Any
9134 This internal attribute is used for the generation of remote subprogram
9135 stubs in the context of the Distributed Systems Annex.
9137 @node Attribute Has_Access_Values
9138 @unnumberedsec Attribute Has_Access_Values
9139 @cindex Access values, testing for
9140 @findex Has_Access_Values
9142 The prefix of the @code{Has_Access_Values} attribute is a type. The result
9143 is a Boolean value which is True if the is an access type, or is a composite
9144 type with a component (at any nesting depth) that is an access type, and is
9146 The intended use of this attribute is in conjunction with generic
9147 definitions. If the attribute is applied to a generic private type, it
9148 indicates whether or not the corresponding actual type has access values.
9150 @node Attribute Has_Discriminants
9151 @unnumberedsec Attribute Has_Discriminants
9152 @cindex Discriminants, testing for
9153 @findex Has_Discriminants
9155 The prefix of the @code{Has_Discriminants} attribute is a type. The result
9156 is a Boolean value which is True if the type has discriminants, and False
9157 otherwise. The intended use of this attribute is in conjunction with generic
9158 definitions. If the attribute is applied to a generic private type, it
9159 indicates whether or not the corresponding actual type has discriminants.
9162 @unnumberedsec Attribute Img
9165 The @code{Img} attribute differs from @code{Image} in that it is applied
9166 directly to an object, and yields the same result as
9167 @code{Image} for the subtype of the object. This is convenient for
9170 @smallexample @c ada
9171 Put_Line ("X = " & X'Img);
9175 has the same meaning as the more verbose:
9177 @smallexample @c ada
9178 Put_Line ("X = " & @var{T}'Image (X));
9182 where @var{T} is the (sub)type of the object @code{X}.
9184 Note that technically, in analogy to @code{Image},
9185 @code{X'Img} returns a parameterless function
9186 that returns the appropriate string when called. This means that
9187 @code{X'Img} can be renamed as a function-returning-string, or used
9188 in an instantiation as a function parameter.
9190 @node Attribute Integer_Value
9191 @unnumberedsec Attribute Integer_Value
9192 @findex Integer_Value
9194 For every integer type @var{S}, @code{@var{S}'Integer_Value} denotes a
9195 function with the following spec:
9197 @smallexample @c ada
9198 function @var{S}'Integer_Value (Arg : @i{Universal_Fixed})
9203 The value returned is the integer value @var{V}, such that
9205 @smallexample @c ada
9206 Arg = @var{V} * @var{T}'Small
9210 where @var{T} is the type of @code{Arg}.
9211 The effect is thus similar to first doing an unchecked conversion from
9212 the fixed-point type to its corresponding implementation type, and then
9213 converting the result to the target integer type. The difference is
9214 that there are full range checks, to ensure that the result is in range.
9215 This attribute is primarily intended for use in implementation of the
9216 standard input-output functions for fixed-point values.
9218 @node Attribute Invalid_Value
9219 @unnumberedsec Attribute Invalid_Value
9220 @findex Invalid_Value
9222 For every scalar type S, S'Invalid_Value returns an undefined value of the
9223 type. If possible this value is an invalid representation for the type. The
9224 value returned is identical to the value used to initialize an otherwise
9225 uninitialized value of the type if pragma Initialize_Scalars is used,
9226 including the ability to modify the value with the binder -Sxx flag and
9227 relevant environment variables at run time.
9229 @node Attribute Iterable
9230 @unnumberedsec Attribute Iterable
9233 Equivalent to Aspect Iterable.
9235 @node Attribute Large
9236 @unnumberedsec Attribute Large
9237 @cindex Ada 83 attributes
9240 The @code{Large} attribute is provided for compatibility with Ada 83. See
9241 the Ada 83 reference manual for an exact description of the semantics of
9244 @node Attribute Library_Level
9245 @unnumberedsec Attribute Library_Level
9246 @findex Library_Level
9249 @code{P'Library_Level}, where P is an entity name,
9250 returns a Boolean value which is True if the entity is declared
9251 at the library level, and False otherwise. Note that within a
9252 generic instantition, the name of the generic unit denotes the
9253 instance, which means that this attribute can be used to test
9254 if a generic is instantiated at the library level, as shown
9257 @smallexample @c ada
9261 pragma Compile_Time_Error
9262 (not Gen'Library_Level,
9263 "Gen can only be instantiated at library level");
9268 @node Attribute Lock_Free
9269 @unnumberedsec Attribute Lock_Free
9272 @code{P'Lock_Free}, where P is a protected object, returns True if a
9273 pragma @code{Lock_Free} applies to P.
9275 @node Attribute Loop_Entry
9276 @unnumberedsec Attribute Loop_Entry
9281 @smallexample @c ada
9282 X'Loop_Entry [(loop_name)]
9286 The @code{Loop_Entry} attribute is used to refer to the value that an
9287 expression had upon entry to a given loop in much the same way that the
9288 @code{Old} attribute in a subprogram postcondition can be used to refer
9289 to the value an expression had upon entry to the subprogram. The
9290 relevant loop is either identified by the given loop name, or it is the
9291 innermost enclosing loop when no loop name is given.
9294 A @code{Loop_Entry} attribute can only occur within a
9295 @code{Loop_Variant} or @code{Loop_Invariant} pragma. A common use of
9296 @code{Loop_Entry} is to compare the current value of objects with their
9297 initial value at loop entry, in a @code{Loop_Invariant} pragma.
9300 The effect of using @code{X'Loop_Entry} is the same as declaring
9301 a constant initialized with the initial value of @code{X} at loop
9302 entry. This copy is not performed if the loop is not entered, or if the
9303 corresponding pragmas are ignored or disabled.
9305 @node Attribute Machine_Size
9306 @unnumberedsec Attribute Machine_Size
9307 @findex Machine_Size
9309 This attribute is identical to the @code{Object_Size} attribute. It is
9310 provided for compatibility with the DEC Ada 83 attribute of this name.
9312 @node Attribute Mantissa
9313 @unnumberedsec Attribute Mantissa
9314 @cindex Ada 83 attributes
9317 The @code{Mantissa} attribute is provided for compatibility with Ada 83. See
9318 the Ada 83 reference manual for an exact description of the semantics of
9321 @node Attribute Maximum_Alignment
9322 @unnumberedsec Attribute Maximum_Alignment
9323 @cindex Alignment, maximum
9324 @findex Maximum_Alignment
9326 @code{Standard'Maximum_Alignment} (@code{Standard} is the only
9327 permissible prefix) provides the maximum useful alignment value for the
9328 target. This is a static value that can be used to specify the alignment
9329 for an object, guaranteeing that it is properly aligned in all
9332 @node Attribute Mechanism_Code
9333 @unnumberedsec Attribute Mechanism_Code
9334 @cindex Return values, passing mechanism
9335 @cindex Parameters, passing mechanism
9336 @findex Mechanism_Code
9338 @code{@var{function}'Mechanism_Code} yields an integer code for the
9339 mechanism used for the result of function, and
9340 @code{@var{subprogram}'Mechanism_Code (@var{n})} yields the mechanism
9341 used for formal parameter number @var{n} (a static integer value with 1
9342 meaning the first parameter) of @var{subprogram}. The code returned is:
9351 @node Attribute Null_Parameter
9352 @unnumberedsec Attribute Null_Parameter
9353 @cindex Zero address, passing
9354 @findex Null_Parameter
9356 A reference @code{@var{T}'Null_Parameter} denotes an imaginary object of
9357 type or subtype @var{T} allocated at machine address zero. The attribute
9358 is allowed only as the default expression of a formal parameter, or as
9359 an actual expression of a subprogram call. In either case, the
9360 subprogram must be imported.
9362 The identity of the object is represented by the address zero in the
9363 argument list, independent of the passing mechanism (explicit or
9366 This capability is needed to specify that a zero address should be
9367 passed for a record or other composite object passed by reference.
9368 There is no way of indicating this without the @code{Null_Parameter}
9371 @node Attribute Object_Size
9372 @unnumberedsec Attribute Object_Size
9373 @cindex Size, used for objects
9376 The size of an object is not necessarily the same as the size of the type
9377 of an object. This is because by default object sizes are increased to be
9378 a multiple of the alignment of the object. For example,
9379 @code{Natural'Size} is
9380 31, but by default objects of type @code{Natural} will have a size of 32 bits.
9381 Similarly, a record containing an integer and a character:
9383 @smallexample @c ada
9391 will have a size of 40 (that is @code{Rec'Size} will be 40). The
9392 alignment will be 4, because of the
9393 integer field, and so the default size of record objects for this type
9394 will be 64 (8 bytes).
9396 If the alignment of the above record is specified to be 1, then the
9397 object size will be 40 (5 bytes). This is true by default, and also
9398 an object size of 40 can be explicitly specified in this case.
9400 A consequence of this capability is that different object sizes can be
9401 given to subtypes that would otherwise be considered in Ada to be
9402 statically matching. But it makes no sense to consider such subtypes
9403 as statically matching. Consequently, in @code{GNAT} we add a rule
9404 to the static matching rules that requires object sizes to match.
9405 Consider this example:
9407 @smallexample @c ada
9408 1. procedure BadAVConvert is
9409 2. type R is new Integer;
9410 3. subtype R1 is R range 1 .. 10;
9411 4. subtype R2 is R range 1 .. 10;
9412 5. for R1'Object_Size use 8;
9413 6. for R2'Object_Size use 16;
9414 7. type R1P is access all R1;
9415 8. type R2P is access all R2;
9416 9. R1PV : R1P := new R1'(4);
9419 12. R2PV := R2P (R1PV);
9421 >>> target designated subtype not compatible with
9422 type "R1" defined at line 3
9428 In the absence of lines 5 and 6,
9429 types @code{R1} and @code{R2} statically match and
9430 hence the conversion on line 12 is legal. But since lines 5 and 6
9431 cause the object sizes to differ, @code{GNAT} considers that types
9432 @code{R1} and @code{R2} are not statically matching, and line 12
9433 generates the diagnostic shown above.
9436 Similar additional checks are performed in other contexts requiring
9437 statically matching subtypes.
9440 @unnumberedsec Attribute Old
9443 In addition to the usage of @code{Old} defined in the Ada 2012 RM (usage
9444 within @code{Post} aspect), GNAT also permits the use of this attribute
9445 in implementation defined pragmas @code{Postcondition},
9446 @code{Contract_Cases} and @code{Test_Case}. Also usages of
9447 @code{Old} which would be illegal according to the Ada 2012 RM
9448 definition are allowed under control of
9449 implementation defined pragma @code{Unevaluated_Use_Of_Old}.
9451 @node Attribute Passed_By_Reference
9452 @unnumberedsec Attribute Passed_By_Reference
9453 @cindex Parameters, when passed by reference
9454 @findex Passed_By_Reference
9456 @code{@var{type}'Passed_By_Reference} for any subtype @var{type} returns
9457 a value of type @code{Boolean} value that is @code{True} if the type is
9458 normally passed by reference and @code{False} if the type is normally
9459 passed by copy in calls. For scalar types, the result is always @code{False}
9460 and is static. For non-scalar types, the result is non-static.
9462 @node Attribute Pool_Address
9463 @unnumberedsec Attribute Pool_Address
9464 @cindex Parameters, when passed by reference
9465 @findex Pool_Address
9467 @code{@var{X}'Pool_Address} for any object @var{X} returns the address
9468 of X within its storage pool. This is the same as
9469 @code{@var{X}'Address}, except that for an unconstrained array whose
9470 bounds are allocated just before the first component,
9471 @code{@var{X}'Pool_Address} returns the address of those bounds,
9472 whereas @code{@var{X}'Address} returns the address of the first
9475 Here, we are interpreting ``storage pool'' broadly to mean ``wherever
9476 the object is allocated'', which could be a user-defined storage pool,
9477 the global heap, on the stack, or in a static memory area. For an
9478 object created by @code{new}, @code{@var{Ptr.all}'Pool_Address} is
9479 what is passed to @code{Allocate} and returned from @code{Deallocate}.
9481 @node Attribute Range_Length
9482 @unnumberedsec Attribute Range_Length
9483 @findex Range_Length
9485 @code{@var{type}'Range_Length} for any discrete type @var{type} yields
9486 the number of values represented by the subtype (zero for a null
9487 range). The result is static for static subtypes. @code{Range_Length}
9488 applied to the index subtype of a one dimensional array always gives the
9489 same result as @code{Length} applied to the array itself.
9492 @unnumberedsec Attribute Ref
9497 @node Attribute Restriction_Set
9498 @unnumberedsec Attribute Restriction_Set
9499 @findex Restriction_Set
9500 @cindex Restrictions
9502 This attribute allows compile time testing of restrictions that
9503 are currently in effect. It is primarily intended for specializing
9504 code in the run-time based on restrictions that are active (e.g.
9505 don't need to save fpt registers if restriction No_Floating_Point
9506 is known to be in effect), but can be used anywhere.
9508 There are two forms:
9510 @smallexample @c ada
9511 System'Restriction_Set (partition_boolean_restriction_NAME)
9512 System'Restriction_Set (No_Dependence => library_unit_NAME);
9516 In the case of the first form, the only restriction names
9517 allowed are parameterless restrictions that are checked
9518 for consistency at bind time. For a complete list see the
9519 subtype @code{System.Rident.Partition_Boolean_Restrictions}.
9521 The result returned is True if the restriction is known to
9522 be in effect, and False if the restriction is known not to
9523 be in effect. An important guarantee is that the value of
9524 a Restriction_Set attribute is known to be consistent throughout
9525 all the code of a partition.
9527 This is trivially achieved if the entire partition is compiled
9528 with a consistent set of restriction pragmas. However, the
9529 compilation model does not require this. It is possible to
9530 compile one set of units with one set of pragmas, and another
9531 set of units with another set of pragmas. It is even possible
9532 to compile a spec with one set of pragmas, and then WITH the
9533 same spec with a different set of pragmas. Inconsistencies
9534 in the actual use of the restriction are checked at bind time.
9536 In order to achieve the guarantee of consistency for the
9537 Restriction_Set pragma, we consider that a use of the pragma
9538 that yields False is equivalent to a violation of the
9541 So for example if you write
9543 @smallexample @c ada
9544 if System'Restriction_Set (No_Floating_Point) then
9552 And the result is False, so that the else branch is executed,
9553 you can assume that this restriction is not set for any unit
9554 in the partition. This is checked by considering this use of
9555 the restriction pragma to be a violation of the restriction
9556 No_Floating_Point. This means that no other unit can attempt
9557 to set this restriction (if some unit does attempt to set it,
9558 the binder will refuse to bind the partition).
9560 Technical note: The restriction name and the unit name are
9561 intepreted entirely syntactically, as in the corresponding
9562 Restrictions pragma, they are not analyzed semantically,
9563 so they do not have a type.
9565 @node Attribute Result
9566 @unnumberedsec Attribute Result
9569 @code{@var{function}'Result} can only be used with in a Postcondition pragma
9570 for a function. The prefix must be the name of the corresponding function. This
9571 is used to refer to the result of the function in the postcondition expression.
9572 For a further discussion of the use of this attribute and examples of its use,
9573 see the description of pragma Postcondition.
9575 @node Attribute Safe_Emax
9576 @unnumberedsec Attribute Safe_Emax
9577 @cindex Ada 83 attributes
9580 The @code{Safe_Emax} attribute is provided for compatibility with Ada 83. See
9581 the Ada 83 reference manual for an exact description of the semantics of
9584 @node Attribute Safe_Large
9585 @unnumberedsec Attribute Safe_Large
9586 @cindex Ada 83 attributes
9589 The @code{Safe_Large} attribute is provided for compatibility with Ada 83. See
9590 the Ada 83 reference manual for an exact description of the semantics of
9593 @node Attribute Safe_Small
9594 @unnumberedsec Attribute Safe_Small
9595 @cindex Ada 83 attributes
9598 The @code{Safe_Small} attribute is provided for compatibility with Ada 83. See
9599 the Ada 83 reference manual for an exact description of the semantics of
9602 @node Attribute Scalar_Storage_Order
9603 @unnumberedsec Attribute Scalar_Storage_Order
9605 @cindex Scalar storage order
9606 @findex Scalar_Storage_Order
9608 For every array or record type @var{S}, the representation attribute
9609 @code{Scalar_Storage_Order} denotes the order in which storage elements
9610 that make up scalar components are ordered within S. The value given must
9611 be a static expression of type System.Bit_Order. The following is an example
9612 of the use of this feature:
9614 @smallexample @c ada
9615 -- Component type definitions
9617 subtype Yr_Type is Natural range 0 .. 127;
9618 subtype Mo_Type is Natural range 1 .. 12;
9619 subtype Da_Type is Natural range 1 .. 31;
9621 -- Record declaration
9624 Years_Since_1980 : Yr_Type;
9626 Day_Of_Month : Da_Type;
9629 -- Record representation clause
9632 Years_Since_1980 at 0 range 0 .. 6;
9633 Month at 0 range 7 .. 10;
9634 Day_Of_Month at 0 range 11 .. 15;
9637 -- Attribute definition clauses
9639 for Date'Bit_Order use System.High_Order_First;
9640 for Date'Scalar_Storage_Order use System.High_Order_First;
9641 -- If Scalar_Storage_Order is specified, it must be consistent with
9642 -- Bit_Order, so it's best to always define the latter explicitly if
9643 -- the former is used.
9647 Other properties are as for standard representation attribute @code{Bit_Order},
9648 as defined by Ada RM 13.5.3(4). The default is @code{System.Default_Bit_Order}.
9650 For a record type @var{T}, if @code{@var{T}'Scalar_Storage_Order} is
9651 specified explicitly, it shall be equal to @code{@var{T}'Bit_Order}. Note:
9652 this means that if a @code{Scalar_Storage_Order} attribute definition
9653 clause is not confirming, then the type's @code{Bit_Order} shall be
9654 specified explicitly and set to the same value.
9656 Derived types inherit an explicitly set scalar storage order from their parent
9657 types. This may be overridden for the derived type by giving an explicit scalar
9658 storage order for the derived type. For a record extension, the derived type
9659 must have the same scalar storage order as the parent type.
9661 If a component of @var{T} is of a record or array type, then that type must
9662 also have a @code{Scalar_Storage_Order} attribute definition clause.
9664 A component of a record or array type that is a packed array, or that
9665 does not start on a byte boundary, must have the same scalar storage order
9666 as the enclosing record or array type.
9668 No component of a type that has an explicit @code{Scalar_Storage_Order}
9669 attribute definition may be aliased.
9671 A confirming @code{Scalar_Storage_Order} attribute definition clause (i.e.
9672 with a value equal to @code{System.Default_Bit_Order}) has no effect.
9674 If the opposite storage order is specified, then whenever the value of
9675 a scalar component of an object of type @var{S} is read, the storage
9676 elements of the enclosing machine scalar are first reversed (before
9677 retrieving the component value, possibly applying some shift and mask
9678 operatings on the enclosing machine scalar), and the opposite operation
9681 In that case, the restrictions set forth in 13.5.1(10.3/2) for scalar components
9682 are relaxed. Instead, the following rules apply:
9685 @item the underlying storage elements are those at positions
9686 @code{(position + first_bit / storage_element_size) ..
9687 (position + (last_bit + storage_element_size - 1) /
9688 storage_element_size)}
9689 @item the sequence of underlying storage elements shall have
9690 a size no greater than the largest machine scalar
9691 @item the enclosing machine scalar is defined as the smallest machine
9692 scalar starting at a position no greater than
9693 @code{position + first_bit / storage_element_size} and covering
9694 storage elements at least up to @code{position + (last_bit +
9695 storage_element_size - 1) / storage_element_size}
9696 @item the position of the component is interpreted relative to that machine
9701 If no scalar storage order is specified for a type (either directly, or by
9702 inheritance in the case of a derived type), then the default is normally
9703 the native ordering of the target, but this default can be overridden using
9704 pragma @code{Default_Scalar_Storage_Order}.
9706 @node Attribute Simple_Storage_Pool
9707 @unnumberedsec Attribute Simple_Storage_Pool
9708 @cindex Storage pool, simple
9709 @cindex Simple storage pool
9710 @findex Simple_Storage_Pool
9712 For every nonformal, nonderived access-to-object type @var{Acc}, the
9713 representation attribute @code{Simple_Storage_Pool} may be specified
9714 via an attribute_definition_clause (or by specifying the equivalent aspect):
9716 @smallexample @c ada
9718 My_Pool : My_Simple_Storage_Pool_Type;
9720 type Acc is access My_Data_Type;
9722 for Acc'Simple_Storage_Pool use My_Pool;
9727 The name given in an attribute_definition_clause for the
9728 @code{Simple_Storage_Pool} attribute shall denote a variable of
9729 a ``simple storage pool type'' (see pragma @code{Simple_Storage_Pool_Type}).
9731 The use of this attribute is only allowed for a prefix denoting a type
9732 for which it has been specified. The type of the attribute is the type
9733 of the variable specified as the simple storage pool of the access type,
9734 and the attribute denotes that variable.
9736 It is illegal to specify both @code{Storage_Pool} and @code{Simple_Storage_Pool}
9737 for the same access type.
9739 If the @code{Simple_Storage_Pool} attribute has been specified for an access
9740 type, then applying the @code{Storage_Pool} attribute to the type is flagged
9741 with a warning and its evaluation raises the exception @code{Program_Error}.
9743 If the Simple_Storage_Pool attribute has been specified for an access
9744 type @var{S}, then the evaluation of the attribute @code{@var{S}'Storage_Size}
9745 returns the result of calling @code{Storage_Size (@var{S}'Simple_Storage_Pool)},
9746 which is intended to indicate the number of storage elements reserved for
9747 the simple storage pool. If the Storage_Size function has not been defined
9748 for the simple storage pool type, then this attribute returns zero.
9750 If an access type @var{S} has a specified simple storage pool of type
9751 @var{SSP}, then the evaluation of an allocator for that access type calls
9752 the primitive @code{Allocate} procedure for type @var{SSP}, passing
9753 @code{@var{S}'Simple_Storage_Pool} as the pool parameter. The detailed
9754 semantics of such allocators is the same as those defined for allocators
9755 in section 13.11 of the Ada Reference Manual, with the term
9756 ``simple storage pool'' substituted for ``storage pool''.
9758 If an access type @var{S} has a specified simple storage pool of type
9759 @var{SSP}, then a call to an instance of the @code{Ada.Unchecked_Deallocation}
9760 for that access type invokes the primitive @code{Deallocate} procedure
9761 for type @var{SSP}, passing @code{@var{S}'Simple_Storage_Pool} as the pool
9762 parameter. The detailed semantics of such unchecked deallocations is the same
9763 as defined in section 13.11.2 of the Ada Reference Manual, except that the
9764 term ``simple storage pool'' is substituted for ``storage pool''.
9766 @node Attribute Small
9767 @unnumberedsec Attribute Small
9768 @cindex Ada 83 attributes
9771 The @code{Small} attribute is defined in Ada 95 (and Ada 2005) only for
9773 GNAT also allows this attribute to be applied to floating-point types
9774 for compatibility with Ada 83. See
9775 the Ada 83 reference manual for an exact description of the semantics of
9776 this attribute when applied to floating-point types.
9778 @node Attribute Storage_Unit
9779 @unnumberedsec Attribute Storage_Unit
9780 @findex Storage_Unit
9782 @code{Standard'Storage_Unit} (@code{Standard} is the only permissible
9783 prefix) provides the same value as @code{System.Storage_Unit}.
9785 @node Attribute Stub_Type
9786 @unnumberedsec Attribute Stub_Type
9789 The GNAT implementation of remote access-to-classwide types is
9790 organized as described in AARM section E.4 (20.t): a value of an RACW type
9791 (designating a remote object) is represented as a normal access
9792 value, pointing to a "stub" object which in turn contains the
9793 necessary information to contact the designated remote object. A
9794 call on any dispatching operation of such a stub object does the
9795 remote call, if necessary, using the information in the stub object
9796 to locate the target partition, etc.
9798 For a prefix @code{T} that denotes a remote access-to-classwide type,
9799 @code{T'Stub_Type} denotes the type of the corresponding stub objects.
9801 By construction, the layout of @code{T'Stub_Type} is identical to that of
9802 type @code{RACW_Stub_Type} declared in the internal implementation-defined
9803 unit @code{System.Partition_Interface}. Use of this attribute will create
9804 an implicit dependency on this unit.
9806 @node Attribute System_Allocator_Alignment
9807 @unnumberedsec Attribute System_Allocator_Alignment
9808 @cindex Alignment, allocator
9809 @findex System_Allocator_Alignment
9811 @code{Standard'System_Allocator_Alignment} (@code{Standard} is the only
9812 permissible prefix) provides the observable guaranted to be honored by
9813 the system allocator (malloc). This is a static value that can be used
9814 in user storage pools based on malloc either to reject allocation
9815 with alignment too large or to enable a realignment circuitry if the
9816 alignment request is larger than this value.
9818 @node Attribute Target_Name
9819 @unnumberedsec Attribute Target_Name
9822 @code{Standard'Target_Name} (@code{Standard} is the only permissible
9823 prefix) provides a static string value that identifies the target
9824 for the current compilation. For GCC implementations, this is the
9825 standard gcc target name without the terminating slash (for
9826 example, GNAT 5.0 on windows yields "i586-pc-mingw32msv").
9828 @node Attribute To_Address
9829 @unnumberedsec Attribute To_Address
9832 The @code{System'To_Address}
9833 (@code{System} is the only permissible prefix)
9834 denotes a function identical to
9835 @code{System.Storage_Elements.To_Address} except that
9836 it is a static attribute. This means that if its argument is
9837 a static expression, then the result of the attribute is a
9838 static expression. This means that such an expression can be
9839 used in contexts (e.g.@: preelaborable packages) which require a
9840 static expression and where the function call could not be used
9841 (since the function call is always non-static, even if its
9842 argument is static). The argument must be in the range
9843 -(2**(m-1) .. 2**m-1, where m is the memory size
9844 (typically 32 or 64). Negative values are intepreted in a
9845 modular manner (e.g. -1 means the same as 16#FFFF_FFFF# on
9848 @node Attribute To_Any
9849 @unnumberedsec Attribute To_Any
9852 This internal attribute is used for the generation of remote subprogram
9853 stubs in the context of the Distributed Systems Annex.
9855 @node Attribute Type_Class
9856 @unnumberedsec Attribute Type_Class
9859 @code{@var{type}'Type_Class} for any type or subtype @var{type} yields
9860 the value of the type class for the full type of @var{type}. If
9861 @var{type} is a generic formal type, the value is the value for the
9862 corresponding actual subtype. The value of this attribute is of type
9863 @code{System.Aux_DEC.Type_Class}, which has the following definition:
9865 @smallexample @c ada
9867 (Type_Class_Enumeration,
9869 Type_Class_Fixed_Point,
9870 Type_Class_Floating_Point,
9875 Type_Class_Address);
9879 Protected types yield the value @code{Type_Class_Task}, which thus
9880 applies to all concurrent types. This attribute is designed to
9881 be compatible with the DEC Ada 83 attribute of the same name.
9883 @node Attribute Type_Key
9884 @unnumberedsec Attribute Type_Key
9887 The @code{Type_Key} attribute is applicable to a type or subtype and
9888 yields a value of type Standard.String containing encoded information
9889 about the type or subtype. This provides improved compatibility with
9890 other implementations that support this attribute.
9892 @node Attribute TypeCode
9893 @unnumberedsec Attribute TypeCode
9896 This internal attribute is used for the generation of remote subprogram
9897 stubs in the context of the Distributed Systems Annex.
9899 @node Attribute UET_Address
9900 @unnumberedsec Attribute UET_Address
9903 The @code{UET_Address} attribute can only be used for a prefix which
9904 denotes a library package. It yields the address of the unit exception
9905 table when zero cost exception handling is used. This attribute is
9906 intended only for use within the GNAT implementation. See the unit
9907 @code{Ada.Exceptions} in files @file{a-except.ads} and @file{a-except.adb}
9908 for details on how this attribute is used in the implementation.
9910 @node Attribute Unconstrained_Array
9911 @unnumberedsec Attribute Unconstrained_Array
9912 @findex Unconstrained_Array
9914 The @code{Unconstrained_Array} attribute can be used with a prefix that
9915 denotes any type or subtype. It is a static attribute that yields
9916 @code{True} if the prefix designates an unconstrained array,
9917 and @code{False} otherwise. In a generic instance, the result is
9918 still static, and yields the result of applying this test to the
9921 @node Attribute Universal_Literal_String
9922 @unnumberedsec Attribute Universal_Literal_String
9923 @cindex Named numbers, representation of
9924 @findex Universal_Literal_String
9926 The prefix of @code{Universal_Literal_String} must be a named
9927 number. The static result is the string consisting of the characters of
9928 the number as defined in the original source. This allows the user
9929 program to access the actual text of named numbers without intermediate
9930 conversions and without the need to enclose the strings in quotes (which
9931 would preclude their use as numbers).
9933 For example, the following program prints the first 50 digits of pi:
9935 @smallexample @c ada
9936 with Text_IO; use Text_IO;
9940 Put (Ada.Numerics.Pi'Universal_Literal_String);
9944 @node Attribute Unrestricted_Access
9945 @unnumberedsec Attribute Unrestricted_Access
9946 @cindex @code{Access}, unrestricted
9947 @findex Unrestricted_Access
9949 The @code{Unrestricted_Access} attribute is similar to @code{Access}
9950 except that all accessibility and aliased view checks are omitted. This
9951 is a user-beware attribute.
9953 For objects, it is similar to @code{Address}, for which it is a
9954 desirable replacement where the value desired is an access type.
9955 In other words, its effect is similar to first applying the
9956 @code{Address} attribute and then doing an unchecked conversion to a
9957 desired access type.
9959 For subprograms, @code{P'Unrestricted_Access} may be used where
9960 @code{P'Access} would be illegal, to construct a value of a
9961 less-nested named access type that designates a more-nested
9962 subprogram. This value may be used in indirect calls, so long as the
9963 more-nested subprogram still exists; once the subprogram containing it
9964 has returned, such calls are erroneous. For example:
9966 @smallexample @c ada
9969 type Less_Nested is not null access procedure;
9970 Global : Less_Nested;
9978 Local_Var : Integer;
9980 procedure More_Nested is
9985 Global := More_Nested'Unrestricted_Access;
9992 When P1 is called from P2, the call via Global is OK, but if P1 were
9993 called after P2 returns, it would be an erroneous use of a dangling
9996 For objects, it is possible to use @code{Unrestricted_Access} for any
9997 type. However, if the result is of an access-to-unconstrained array
9998 subtype, then the resulting pointer has the same scope as the context
9999 of the attribute, and must not be returned to some enclosing scope.
10000 For instance, if a function uses @code{Unrestricted_Access} to create
10001 an access-to-unconstrained-array and returns that value to the caller,
10002 the result will involve dangling pointers. In addition, it is only
10003 valid to create pointers to unconstrained arrays using this attribute
10004 if the pointer has the normal default ``fat'' representation where a
10005 pointer has two components, one points to the array and one points to
10006 the bounds. If a size clause is used to force ``thin'' representation
10007 for a pointer to unconstrained where there is only space for a single
10008 pointer, then the resulting pointer is not usable.
10010 In the simple case where a direct use of Unrestricted_Access attempts
10011 to make a thin pointer for a non-aliased object, the compiler will
10012 reject the use as illegal, as shown in the following example:
10014 @smallexample @c ada
10015 with System; use System;
10016 procedure SliceUA2 is
10017 type A is access all String;
10018 for A'Size use Standard'Address_Size;
10020 procedure P (Arg : A) is
10025 X : String := "hello world!";
10026 X2 : aliased String := "hello world!";
10028 AV : A := X'Unrestricted_Access; -- ERROR
10030 >>> illegal use of Unrestricted_Access attribute
10031 >>> attempt to generate thin pointer to unaliased object
10034 P (X'Unrestricted_Access); -- ERROR
10036 >>> illegal use of Unrestricted_Access attribute
10037 >>> attempt to generate thin pointer to unaliased object
10039 P (X(7 .. 12)'Unrestricted_Access); -- ERROR
10041 >>> illegal use of Unrestricted_Access attribute
10042 >>> attempt to generate thin pointer to unaliased object
10044 P (X2'Unrestricted_Access); -- OK
10049 but other cases cannot be detected by the compiler, and are
10050 considered to be erroneous. Consider the following example:
10052 @smallexample @c ada
10053 with System; use System;
10054 with System; use System;
10055 procedure SliceUA is
10056 type AF is access all String;
10058 type A is access all String;
10059 for A'Size use Standard'Address_Size;
10061 procedure P (Arg : A) is
10063 if Arg'Length /= 6 then
10064 raise Program_Error;
10068 X : String := "hello world!";
10069 Y : AF := X (7 .. 12)'Unrestricted_Access;
10077 A normal unconstrained array value
10078 or a constrained array object marked as aliased has the bounds in memory
10079 just before the array, so a thin pointer can retrieve both the data and
10080 the bounds. But in this case, the non-aliased object @code{X} does not have the
10081 bounds before the string. If the size clause for type @code{A}
10082 were not present, then the pointer
10083 would be a fat pointer, where one component is a pointer to the bounds,
10084 and all would be well. But with the size clause present, the conversion from
10085 fat pointer to thin pointer in the call loses the bounds, and so this
10086 is erroneous, and the program likely raises a @code{Program_Error} exception.
10088 In general, it is advisable to completely
10089 avoid mixing the use of thin pointers and the use of
10090 @code{Unrestricted_Access} where the designated type is an
10091 unconstrained array. The use of thin pointers should be restricted to
10092 cases of porting legacy code that implicitly assumes the size of pointers,
10093 and such code should not in any case be using this attribute.
10095 Another erroneous situation arises if the attribute is
10096 applied to a constant. The resulting pointer can be used to access the
10097 constant, but the effect of trying to modify a constant in this manner
10098 is not well-defined. Consider this example:
10100 @smallexample @c ada
10101 P : constant Integer := 4;
10102 type R is access all Integer;
10103 RV : R := P'Unrestricted_Access;
10109 Here we attempt to modify the constant P from 4 to 3, but the compiler may
10110 or may not notice this attempt, and subsequent references to P may yield
10111 either the value 3 or the value 4 or the assignment may blow up if the
10112 compiler decides to put P in read-only memory. One particular case where
10113 @code{Unrestricted_Access} can be used in this way is to modify the
10114 value of an @code{IN} parameter:
10116 @smallexample @c ada
10117 procedure K (S : in String) is
10118 type R is access all Character;
10119 RV : R := S (3)'Unrestricted_Access;
10126 In general this is a risky approach. It may appear to "work" but such uses of
10127 @code{Unrestricted_Access} are potentially non-portable, even from one version
10128 of @code{GNAT} to another, so are best avoided if possible.
10130 @node Attribute Update
10131 @unnumberedsec Attribute Update
10134 The @code{Update} attribute creates a copy of an array or record value
10135 with one or more modified components. The syntax is:
10137 @smallexample @c ada
10138 PREFIX'Update ( RECORD_COMPONENT_ASSOCIATION_LIST )
10139 PREFIX'Update ( ARRAY_COMPONENT_ASSOCIATION @{, ARRAY_COMPONENT_ASSOCIATION @} )
10140 PREFIX'Update ( MULTIDIMENSIONAL_ARRAY_COMPONENT_ASSOCIATION
10141 @{, MULTIDIMENSIONAL_ARRAY_COMPONENT_ASSOCIATION @} )
10143 MULTIDIMENSIONAL_ARRAY_COMPONENT_ASSOCIATION ::= INDEX_EXPRESSION_LIST_LIST => EXPRESSION
10144 INDEX_EXPRESSION_LIST_LIST ::= INDEX_EXPRESSION_LIST @{| INDEX_EXPRESSION_LIST @}
10145 INDEX_EXPRESSION_LIST ::= ( EXPRESSION @{, EXPRESSION @} )
10149 where @code{PREFIX} is the name of an array or record object, the
10150 association list in parentheses does not contain an @code{others}
10151 choice and the box symbol @code{<>} may not appear in any
10152 expression. The effect is to yield a copy of the array or record value
10153 which is unchanged apart from the components mentioned in the
10154 association list, which are changed to the indicated value. The
10155 original value of the array or record value is not affected. For
10158 @smallexample @c ada
10159 type Arr is Array (1 .. 5) of Integer;
10161 Avar1 : Arr := (1,2,3,4,5);
10162 Avar2 : Arr := Avar1'Update (2 => 10, 3 .. 4 => 20);
10166 yields a value for @code{Avar2} of 1,10,20,20,5 with @code{Avar1}
10167 begin unmodified. Similarly:
10169 @smallexample @c ada
10170 type Rec is A, B, C : Integer;
10172 Rvar1 : Rec := (A => 1, B => 2, C => 3);
10173 Rvar2 : Rec := Rvar1'Update (B => 20);
10177 yields a value for @code{Rvar2} of (A => 1, B => 20, C => 3),
10178 with @code{Rvar1} being unmodifed.
10179 Note that the value of the attribute reference is computed
10180 completely before it is used. This means that if you write:
10182 @smallexample @c ada
10183 Avar1 := Avar1'Update (1 => 10, 2 => Function_Call);
10187 then the value of @code{Avar1} is not modified if @code{Function_Call}
10188 raises an exception, unlike the effect of a series of direct assignments
10189 to elements of @code{Avar1}. In general this requires that
10190 two extra complete copies of the object are required, which should be
10191 kept in mind when considering efficiency.
10193 The @code{Update} attribute cannot be applied to prefixes of a limited
10194 type, and cannot reference discriminants in the case of a record type.
10195 The accessibility level of an Update attribute result object is defined
10196 as for an aggregate.
10198 In the record case, no component can be mentioned more than once. In
10199 the array case, two overlapping ranges can appear in the association list,
10200 in which case the modifications are processed left to right.
10202 Multi-dimensional arrays can be modified, as shown by this example:
10204 @smallexample @c ada
10205 A : array (1 .. 10, 1 .. 10) of Integer;
10207 A := A'Update ((1, 2) => 20, (3, 4) => 30);
10211 which changes element (1,2) to 20 and (3,4) to 30.
10213 @node Attribute Valid_Scalars
10214 @unnumberedsec Attribute Valid_Scalars
10215 @findex Valid_Scalars
10217 The @code{'Valid_Scalars} attribute is intended to make it easier to
10218 check the validity of scalar subcomponents of composite objects. It
10219 is defined for any prefix @code{X} that denotes an object.
10220 The value of this attribute is of the predefined type Boolean.
10221 @code{X'Valid_Scalars} yields True if and only if evaluation of
10222 @code{P'Valid} yields True for every scalar part P of X or if X has
10223 no scalar parts. It is not specified in what order the scalar parts
10224 are checked, nor whether any more are checked after any one of them
10225 is determined to be invalid. If the prefix @code{X} is of a class-wide
10226 type @code{T'Class} (where @code{T} is the associated specific type),
10227 or if the prefix @code{X} is of a specific tagged type @code{T}, then
10228 only the scalar parts of components of @code{T} are traversed; in other
10229 words, components of extensions of @code{T} are not traversed even if
10230 @code{T'Class (X)'Tag /= T'Tag} . The compiler will issue a warning if it can
10231 be determined at compile time that the prefix of the attribute has no
10232 scalar parts (e.g., if the prefix is of an access type, an interface type,
10233 an undiscriminated task type, or an undiscriminated protected type).
10235 For scalar types, @code{Valid_Scalars} is equivalent to @code{Valid}. The use
10236 of this attribute is not permitted for @code{Unchecked_Union} types for which
10237 in general it is not possible to determine the values of the discriminants.
10239 Note: @code{Valid_Scalars} can generate a lot of code, especially in the case
10240 of a large variant record. If the attribute is called in many places in the
10241 same program applied to objects of the same type, it can reduce program size
10242 to write a function with a single use of the attribute, and then call that
10243 function from multiple places.
10245 @node Attribute VADS_Size
10246 @unnumberedsec Attribute VADS_Size
10247 @cindex @code{Size}, VADS compatibility
10250 The @code{'VADS_Size} attribute is intended to make it easier to port
10251 legacy code which relies on the semantics of @code{'Size} as implemented
10252 by the VADS Ada 83 compiler. GNAT makes a best effort at duplicating the
10253 same semantic interpretation. In particular, @code{'VADS_Size} applied
10254 to a predefined or other primitive type with no Size clause yields the
10255 Object_Size (for example, @code{Natural'Size} is 32 rather than 31 on
10256 typical machines). In addition @code{'VADS_Size} applied to an object
10257 gives the result that would be obtained by applying the attribute to
10258 the corresponding type.
10260 @node Attribute Value_Size
10261 @unnumberedsec Attribute Value_Size
10262 @cindex @code{Size}, setting for not-first subtype
10264 @code{@var{type}'Value_Size} is the number of bits required to represent
10265 a value of the given subtype. It is the same as @code{@var{type}'Size},
10266 but, unlike @code{Size}, may be set for non-first subtypes.
10268 @node Attribute Wchar_T_Size
10269 @unnumberedsec Attribute Wchar_T_Size
10270 @findex Wchar_T_Size
10271 @code{Standard'Wchar_T_Size} (@code{Standard} is the only permissible
10272 prefix) provides the size in bits of the C @code{wchar_t} type
10273 primarily for constructing the definition of this type in
10274 package @code{Interfaces.C}. The result is a static constant.
10276 @node Attribute Word_Size
10277 @unnumberedsec Attribute Word_Size
10279 @code{Standard'Word_Size} (@code{Standard} is the only permissible
10280 prefix) provides the value @code{System.Word_Size}. The result is
10283 @node Standard and Implementation Defined Restrictions
10284 @chapter Standard and Implementation Defined Restrictions
10287 All RM defined Restriction identifiers are implemented:
10290 @item language-defined restrictions (see 13.12.1)
10291 @item tasking restrictions (see D.7)
10292 @item high integrity restrictions (see H.4)
10296 GNAT implements additional restriction identifiers. All restrictions, whether
10297 language defined or GNAT-specific, are listed in the following.
10300 * Partition-Wide Restrictions::
10301 * Program Unit Level Restrictions::
10304 @node Partition-Wide Restrictions
10305 @section Partition-Wide Restrictions
10307 There are two separate lists of restriction identifiers. The first
10308 set requires consistency throughout a partition (in other words, if the
10309 restriction identifier is used for any compilation unit in the partition,
10310 then all compilation units in the partition must obey the restriction).
10313 * Immediate_Reclamation::
10314 * Max_Asynchronous_Select_Nesting::
10315 * Max_Entry_Queue_Length::
10316 * Max_Protected_Entries::
10317 * Max_Select_Alternatives::
10318 * Max_Storage_At_Blocking::
10319 * Max_Task_Entries::
10321 * No_Abort_Statements::
10322 * No_Access_Parameter_Allocators::
10323 * No_Access_Subprograms::
10325 * No_Anonymous_Allocators::
10327 * No_Coextensions::
10328 * No_Default_Initialization::
10331 * No_Direct_Boolean_Operators::
10333 * No_Dispatching_Calls::
10334 * No_Dynamic_Attachment::
10335 * No_Dynamic_Priorities::
10336 * No_Entry_Calls_In_Elaboration_Code::
10337 * No_Enumeration_Maps::
10338 * No_Exception_Handlers::
10339 * No_Exception_Propagation::
10340 * No_Exception_Registration::
10342 * No_Finalization::
10344 * No_Floating_Point::
10345 * No_Implicit_Conditionals::
10346 * No_Implicit_Dynamic_Code::
10347 * No_Implicit_Heap_Allocations::
10348 * No_Implicit_Loops::
10349 * No_Initialize_Scalars::
10351 * No_Local_Allocators::
10352 * No_Local_Protected_Objects::
10353 * No_Local_Timing_Events::
10354 * No_Long_Long_Integers::
10355 * No_Multiple_Elaboration::
10356 * No_Nested_Finalization::
10357 * No_Protected_Type_Allocators::
10358 * No_Protected_Types::
10361 * No_Relative_Delay::
10362 * No_Requeue_Statements::
10363 * No_Secondary_Stack::
10364 * No_Select_Statements::
10365 * No_Specific_Termination_Handlers::
10366 * No_Specification_of_Aspect::
10367 * No_Standard_Allocators_After_Elaboration::
10368 * No_Standard_Storage_Pools::
10369 * No_Stream_Optimizations::
10371 * No_Task_Allocators::
10372 * No_Task_Attributes_Package::
10373 * No_Task_Hierarchy::
10374 * No_Task_Termination::
10376 * No_Terminate_Alternatives::
10377 * No_Unchecked_Access::
10378 * Simple_Barriers::
10379 * Static_Priorities::
10380 * Static_Storage_Size::
10383 @node Immediate_Reclamation
10384 @unnumberedsubsec Immediate_Reclamation
10385 @findex Immediate_Reclamation
10386 [RM H.4] This restriction ensures that, except for storage occupied by
10387 objects created by allocators and not deallocated via unchecked
10388 deallocation, any storage reserved at run time for an object is
10389 immediately reclaimed when the object no longer exists.
10391 @node Max_Asynchronous_Select_Nesting
10392 @unnumberedsubsec Max_Asynchronous_Select_Nesting
10393 @findex Max_Asynchronous_Select_Nesting
10394 [RM D.7] Specifies the maximum dynamic nesting level of asynchronous
10395 selects. Violations of this restriction with a value of zero are
10396 detected at compile time. Violations of this restriction with values
10397 other than zero cause Storage_Error to be raised.
10399 @node Max_Entry_Queue_Length
10400 @unnumberedsubsec Max_Entry_Queue_Length
10401 @findex Max_Entry_Queue_Length
10402 [RM D.7] This restriction is a declaration that any protected entry compiled in
10403 the scope of the restriction has at most the specified number of
10404 tasks waiting on the entry at any one time, and so no queue is required.
10405 Note that this restriction is checked at run time. Violation of this
10406 restriction results in the raising of Program_Error exception at the point of
10409 @findex Max_Entry_Queue_Depth
10410 The restriction @code{Max_Entry_Queue_Depth} is recognized as a
10411 synonym for @code{Max_Entry_Queue_Length}. This is retained for historical
10412 compatibility purposes (and a warning will be generated for its use if
10413 warnings on obsolescent features are activated).
10415 @node Max_Protected_Entries
10416 @unnumberedsubsec Max_Protected_Entries
10417 @findex Max_Protected_Entries
10418 [RM D.7] Specifies the maximum number of entries per protected type. The
10419 bounds of every entry family of a protected unit shall be static, or shall be
10420 defined by a discriminant of a subtype whose corresponding bound is static.
10422 @node Max_Select_Alternatives
10423 @unnumberedsubsec Max_Select_Alternatives
10424 @findex Max_Select_Alternatives
10425 [RM D.7] Specifies the maximum number of alternatives in a selective accept.
10427 @node Max_Storage_At_Blocking
10428 @unnumberedsubsec Max_Storage_At_Blocking
10429 @findex Max_Storage_At_Blocking
10430 [RM D.7] Specifies the maximum portion (in storage elements) of a task's
10431 Storage_Size that can be retained by a blocked task. A violation of this
10432 restriction causes Storage_Error to be raised.
10434 @node Max_Task_Entries
10435 @unnumberedsubsec Max_Task_Entries
10436 @findex Max_Task_Entries
10437 [RM D.7] Specifies the maximum number of entries
10438 per task. The bounds of every entry family
10439 of a task unit shall be static, or shall be
10440 defined by a discriminant of a subtype whose
10441 corresponding bound is static.
10444 @unnumberedsubsec Max_Tasks
10446 [RM D.7] Specifies the maximum number of task that may be created, not
10447 counting the creation of the environment task. Violations of this
10448 restriction with a value of zero are detected at compile
10449 time. Violations of this restriction with values other than zero cause
10450 Storage_Error to be raised.
10452 @node No_Abort_Statements
10453 @unnumberedsubsec No_Abort_Statements
10454 @findex No_Abort_Statements
10455 [RM D.7] There are no abort_statements, and there are
10456 no calls to Task_Identification.Abort_Task.
10458 @node No_Access_Parameter_Allocators
10459 @unnumberedsubsec No_Access_Parameter_Allocators
10460 @findex No_Access_Parameter_Allocators
10461 [RM H.4] This restriction ensures at compile time that there are no
10462 occurrences of an allocator as the actual parameter to an access
10465 @node No_Access_Subprograms
10466 @unnumberedsubsec No_Access_Subprograms
10467 @findex No_Access_Subprograms
10468 [RM H.4] This restriction ensures at compile time that there are no
10469 declarations of access-to-subprogram types.
10471 @node No_Allocators
10472 @unnumberedsubsec No_Allocators
10473 @findex No_Allocators
10474 [RM H.4] This restriction ensures at compile time that there are no
10475 occurrences of an allocator.
10477 @node No_Anonymous_Allocators
10478 @unnumberedsubsec No_Anonymous_Allocators
10479 @findex No_Anonymous_Allocators
10480 [RM H.4] This restriction ensures at compile time that there are no
10481 occurrences of an allocator of anonymous access type.
10484 @unnumberedsubsec No_Calendar
10485 @findex No_Calendar
10486 [GNAT] This restriction ensures at compile time that there is no implicit or
10487 explicit dependence on the package @code{Ada.Calendar}.
10489 @node No_Coextensions
10490 @unnumberedsubsec No_Coextensions
10491 @findex No_Coextensions
10492 [RM H.4] This restriction ensures at compile time that there are no
10493 coextensions. See 3.10.2.
10495 @node No_Default_Initialization
10496 @unnumberedsubsec No_Default_Initialization
10497 @findex No_Default_Initialization
10499 [GNAT] This restriction prohibits any instance of default initialization
10500 of variables. The binder implements a consistency rule which prevents
10501 any unit compiled without the restriction from with'ing a unit with the
10502 restriction (this allows the generation of initialization procedures to
10503 be skipped, since you can be sure that no call is ever generated to an
10504 initialization procedure in a unit with the restriction active). If used
10505 in conjunction with Initialize_Scalars or Normalize_Scalars, the effect
10506 is to prohibit all cases of variables declared without a specific
10507 initializer (including the case of OUT scalar parameters).
10510 @unnumberedsubsec No_Delay
10512 [RM H.4] This restriction ensures at compile time that there are no
10513 delay statements and no dependences on package Calendar.
10515 @node No_Dependence
10516 @unnumberedsubsec No_Dependence
10517 @findex No_Dependence
10518 [RM 13.12.1] This restriction checks at compile time that there are no
10519 dependence on a library unit.
10521 @node No_Direct_Boolean_Operators
10522 @unnumberedsubsec No_Direct_Boolean_Operators
10523 @findex No_Direct_Boolean_Operators
10524 [GNAT] This restriction ensures that no logical operators (and/or/xor)
10525 are used on operands of type Boolean (or any type derived from Boolean).
10526 This is intended for use in safety critical programs where the certification
10527 protocol requires the use of short-circuit (and then, or else) forms for all
10528 composite boolean operations.
10531 @unnumberedsubsec No_Dispatch
10532 @findex No_Dispatch
10533 [RM H.4] This restriction ensures at compile time that there are no
10534 occurrences of @code{T'Class}, for any (tagged) subtype @code{T}.
10536 @node No_Dispatching_Calls
10537 @unnumberedsubsec No_Dispatching_Calls
10538 @findex No_Dispatching_Calls
10539 [GNAT] This restriction ensures at compile time that the code generated by the
10540 compiler involves no dispatching calls. The use of this restriction allows the
10541 safe use of record extensions, classwide membership tests and other classwide
10542 features not involving implicit dispatching. This restriction ensures that
10543 the code contains no indirect calls through a dispatching mechanism. Note that
10544 this includes internally-generated calls created by the compiler, for example
10545 in the implementation of class-wide objects assignments. The
10546 membership test is allowed in the presence of this restriction, because its
10547 implementation requires no dispatching.
10548 This restriction is comparable to the official Ada restriction
10549 @code{No_Dispatch} except that it is a bit less restrictive in that it allows
10550 all classwide constructs that do not imply dispatching.
10551 The following example indicates constructs that violate this restriction.
10555 type T is tagged record
10558 procedure P (X : T);
10560 type DT is new T with record
10561 More_Data : Natural;
10563 procedure Q (X : DT);
10567 procedure Example is
10568 procedure Test (O : T'Class) is
10569 N : Natural := O'Size;-- Error: Dispatching call
10570 C : T'Class := O; -- Error: implicit Dispatching Call
10572 if O in DT'Class then -- OK : Membership test
10573 Q (DT (O)); -- OK : Type conversion plus direct call
10575 P (O); -- Error: Dispatching call
10581 P (Obj); -- OK : Direct call
10582 P (T (Obj)); -- OK : Type conversion plus direct call
10583 P (T'Class (Obj)); -- Error: Dispatching call
10585 Test (Obj); -- OK : Type conversion
10587 if Obj in T'Class then -- OK : Membership test
10593 @node No_Dynamic_Attachment
10594 @unnumberedsubsec No_Dynamic_Attachment
10595 @findex No_Dynamic_Attachment
10596 [RM D.7] This restriction ensures that there is no call to any of the
10597 operations defined in package Ada.Interrupts
10598 (Is_Reserved, Is_Attached, Current_Handler, Attach_Handler, Exchange_Handler,
10599 Detach_Handler, and Reference).
10601 @findex No_Dynamic_Interrupts
10602 The restriction @code{No_Dynamic_Interrupts} is recognized as a
10603 synonym for @code{No_Dynamic_Attachment}. This is retained for historical
10604 compatibility purposes (and a warning will be generated for its use if
10605 warnings on obsolescent features are activated).
10607 @node No_Dynamic_Priorities
10608 @unnumberedsubsec No_Dynamic_Priorities
10609 @findex No_Dynamic_Priorities
10610 [RM D.7] There are no semantic dependencies on the package Dynamic_Priorities.
10612 @node No_Entry_Calls_In_Elaboration_Code
10613 @unnumberedsubsec No_Entry_Calls_In_Elaboration_Code
10614 @findex No_Entry_Calls_In_Elaboration_Code
10615 [GNAT] This restriction ensures at compile time that no task or protected entry
10616 calls are made during elaboration code. As a result of the use of this
10617 restriction, the compiler can assume that no code past an accept statement
10618 in a task can be executed at elaboration time.
10620 @node No_Enumeration_Maps
10621 @unnumberedsubsec No_Enumeration_Maps
10622 @findex No_Enumeration_Maps
10623 [GNAT] This restriction ensures at compile time that no operations requiring
10624 enumeration maps are used (that is Image and Value attributes applied
10625 to enumeration types).
10627 @node No_Exception_Handlers
10628 @unnumberedsubsec No_Exception_Handlers
10629 @findex No_Exception_Handlers
10630 [GNAT] This restriction ensures at compile time that there are no explicit
10631 exception handlers. It also indicates that no exception propagation will
10632 be provided. In this mode, exceptions may be raised but will result in
10633 an immediate call to the last chance handler, a routine that the user
10634 must define with the following profile:
10636 @smallexample @c ada
10637 procedure Last_Chance_Handler
10638 (Source_Location : System.Address; Line : Integer);
10639 pragma Export (C, Last_Chance_Handler,
10640 "__gnat_last_chance_handler");
10643 The parameter is a C null-terminated string representing a message to be
10644 associated with the exception (typically the source location of the raise
10645 statement generated by the compiler). The Line parameter when nonzero
10646 represents the line number in the source program where the raise occurs.
10648 @node No_Exception_Propagation
10649 @unnumberedsubsec No_Exception_Propagation
10650 @findex No_Exception_Propagation
10651 [GNAT] This restriction guarantees that exceptions are never propagated
10652 to an outer subprogram scope. The only case in which an exception may
10653 be raised is when the handler is statically in the same subprogram, so
10654 that the effect of a raise is essentially like a goto statement. Any
10655 other raise statement (implicit or explicit) will be considered
10656 unhandled. Exception handlers are allowed, but may not contain an
10657 exception occurrence identifier (exception choice). In addition, use of
10658 the package GNAT.Current_Exception is not permitted, and reraise
10659 statements (raise with no operand) are not permitted.
10661 @node No_Exception_Registration
10662 @unnumberedsubsec No_Exception_Registration
10663 @findex No_Exception_Registration
10664 [GNAT] This restriction ensures at compile time that no stream operations for
10665 types Exception_Id or Exception_Occurrence are used. This also makes it
10666 impossible to pass exceptions to or from a partition with this restriction
10667 in a distributed environment. If this restriction is active, the generated
10668 code is simplified by omitting the otherwise-required global registration
10669 of exceptions when they are declared.
10671 @node No_Exceptions
10672 @unnumberedsubsec No_Exceptions
10673 @findex No_Exceptions
10674 [RM H.4] This restriction ensures at compile time that there are no
10675 raise statements and no exception handlers.
10677 @node No_Finalization
10678 @unnumberedsubsec No_Finalization
10679 @findex No_Finalization
10680 [GNAT] This restriction disables the language features described in
10681 chapter 7.6 of the Ada 2005 RM as well as all form of code generation
10682 performed by the compiler to support these features. The following types
10683 are no longer considered controlled when this restriction is in effect:
10686 @code{Ada.Finalization.Controlled}
10688 @code{Ada.Finalization.Limited_Controlled}
10690 Derivations from @code{Controlled} or @code{Limited_Controlled}
10698 Array and record types with controlled components
10700 The compiler no longer generates code to initialize, finalize or adjust an
10701 object or a nested component, either declared on the stack or on the heap. The
10702 deallocation of a controlled object no longer finalizes its contents.
10704 @node No_Fixed_Point
10705 @unnumberedsubsec No_Fixed_Point
10706 @findex No_Fixed_Point
10707 [RM H.4] This restriction ensures at compile time that there are no
10708 occurrences of fixed point types and operations.
10710 @node No_Floating_Point
10711 @unnumberedsubsec No_Floating_Point
10712 @findex No_Floating_Point
10713 [RM H.4] This restriction ensures at compile time that there are no
10714 occurrences of floating point types and operations.
10716 @node No_Implicit_Conditionals
10717 @unnumberedsubsec No_Implicit_Conditionals
10718 @findex No_Implicit_Conditionals
10719 [GNAT] This restriction ensures that the generated code does not contain any
10720 implicit conditionals, either by modifying the generated code where possible,
10721 or by rejecting any construct that would otherwise generate an implicit
10722 conditional. Note that this check does not include run time constraint
10723 checks, which on some targets may generate implicit conditionals as
10724 well. To control the latter, constraint checks can be suppressed in the
10725 normal manner. Constructs generating implicit conditionals include comparisons
10726 of composite objects and the Max/Min attributes.
10728 @node No_Implicit_Dynamic_Code
10729 @unnumberedsubsec No_Implicit_Dynamic_Code
10730 @findex No_Implicit_Dynamic_Code
10732 [GNAT] This restriction prevents the compiler from building ``trampolines''.
10733 This is a structure that is built on the stack and contains dynamic
10734 code to be executed at run time. On some targets, a trampoline is
10735 built for the following features: @code{Access},
10736 @code{Unrestricted_Access}, or @code{Address} of a nested subprogram;
10737 nested task bodies; primitive operations of nested tagged types.
10738 Trampolines do not work on machines that prevent execution of stack
10739 data. For example, on windows systems, enabling DEP (data execution
10740 protection) will cause trampolines to raise an exception.
10741 Trampolines are also quite slow at run time.
10743 On many targets, trampolines have been largely eliminated. Look at the
10744 version of system.ads for your target --- if it has
10745 Always_Compatible_Rep equal to False, then trampolines are largely
10746 eliminated. In particular, a trampoline is built for the following
10747 features: @code{Address} of a nested subprogram;
10748 @code{Access} or @code{Unrestricted_Access} of a nested subprogram,
10749 but only if pragma Favor_Top_Level applies, or the access type has a
10750 foreign-language convention; primitive operations of nested tagged
10753 @node No_Implicit_Heap_Allocations
10754 @unnumberedsubsec No_Implicit_Heap_Allocations
10755 @findex No_Implicit_Heap_Allocations
10756 [RM D.7] No constructs are allowed to cause implicit heap allocation.
10758 @node No_Implicit_Loops
10759 @unnumberedsubsec No_Implicit_Loops
10760 @findex No_Implicit_Loops
10761 [GNAT] This restriction ensures that the generated code does not contain any
10762 implicit @code{for} loops, either by modifying
10763 the generated code where possible,
10764 or by rejecting any construct that would otherwise generate an implicit
10765 @code{for} loop. If this restriction is active, it is possible to build
10766 large array aggregates with all static components without generating an
10767 intermediate temporary, and without generating a loop to initialize individual
10768 components. Otherwise, a loop is created for arrays larger than about 5000
10771 @node No_Initialize_Scalars
10772 @unnumberedsubsec No_Initialize_Scalars
10773 @findex No_Initialize_Scalars
10774 [GNAT] This restriction ensures that no unit in the partition is compiled with
10775 pragma Initialize_Scalars. This allows the generation of more efficient
10776 code, and in particular eliminates dummy null initialization routines that
10777 are otherwise generated for some record and array types.
10780 @unnumberedsubsec No_IO
10782 [RM H.4] This restriction ensures at compile time that there are no
10783 dependences on any of the library units Sequential_IO, Direct_IO,
10784 Text_IO, Wide_Text_IO, Wide_Wide_Text_IO, or Stream_IO.
10786 @node No_Local_Allocators
10787 @unnumberedsubsec No_Local_Allocators
10788 @findex No_Local_Allocators
10789 [RM H.4] This restriction ensures at compile time that there are no
10790 occurrences of an allocator in subprograms, generic subprograms, tasks,
10793 @node No_Local_Protected_Objects
10794 @unnumberedsubsec No_Local_Protected_Objects
10795 @findex No_Local_Protected_Objects
10796 [RM D.7] This restriction ensures at compile time that protected objects are
10797 only declared at the library level.
10799 @node No_Local_Timing_Events
10800 @unnumberedsubsec No_Local_Timing_Events
10801 @findex No_Local_Timing_Events
10802 [RM D.7] All objects of type Ada.Timing_Events.Timing_Event are
10803 declared at the library level.
10805 @node No_Long_Long_Integers
10806 @unnumberedsubsec No_Long_Long_Integers
10807 @findex No_Long_Long_Integers
10808 [GNAT] This partition-wide restriction forbids any explicit reference to
10809 type Standard.Long_Long_Integer, and also forbids declaring range types whose
10810 implicit base type is Long_Long_Integer, and modular types whose size exceeds
10813 @node No_Multiple_Elaboration
10814 @unnumberedsubsec No_Multiple_Elaboration
10815 @findex No_Multiple_Elaboration
10816 [GNAT] Normally each package contains a 16-bit counter used to check for access
10817 before elaboration, and to control multiple elaboration attempts.
10818 This counter is eliminated for units compiled with the static model
10819 of elaboration if restriction @code{No_Elaboration_Code}
10820 is active but because of
10821 the need to check for multiple elaboration in the general case, these
10822 counters cannot be eliminated if elaboration code may be present. The
10823 restriction @code{No_Multiple_Elaboration}
10824 allows suppression of these counters
10825 in static elaboration units even if they do have elaboration code. If this
10826 restriction is used, then the situations in which multiple elaboration is
10827 possible, including non-Ada main programs, and Stand Alone libraries, are not
10828 permitted, and will be diagnosed by the binder.
10830 @node No_Nested_Finalization
10831 @unnumberedsubsec No_Nested_Finalization
10832 @findex No_Nested_Finalization
10833 [RM D.7] All objects requiring finalization are declared at the library level.
10835 @node No_Protected_Type_Allocators
10836 @unnumberedsubsec No_Protected_Type_Allocators
10837 @findex No_Protected_Type_Allocators
10838 [RM D.7] This restriction ensures at compile time that there are no allocator
10839 expressions that attempt to allocate protected objects.
10841 @node No_Protected_Types
10842 @unnumberedsubsec No_Protected_Types
10843 @findex No_Protected_Types
10844 [RM H.4] This restriction ensures at compile time that there are no
10845 declarations of protected types or protected objects.
10848 @unnumberedsubsec No_Recursion
10849 @findex No_Recursion
10850 [RM H.4] A program execution is erroneous if a subprogram is invoked as
10851 part of its execution.
10853 @node No_Reentrancy
10854 @unnumberedsubsec No_Reentrancy
10855 @findex No_Reentrancy
10856 [RM H.4] A program execution is erroneous if a subprogram is executed by
10857 two tasks at the same time.
10859 @node No_Relative_Delay
10860 @unnumberedsubsec No_Relative_Delay
10861 @findex No_Relative_Delay
10862 [RM D.7] This restriction ensures at compile time that there are no delay
10863 relative statements and prevents expressions such as @code{delay 1.23;} from
10864 appearing in source code.
10866 @node No_Requeue_Statements
10867 @unnumberedsubsec No_Requeue_Statements
10868 @findex No_Requeue_Statements
10869 [RM D.7] This restriction ensures at compile time that no requeue statements
10870 are permitted and prevents keyword @code{requeue} from being used in source
10874 The restriction @code{No_Requeue} is recognized as a
10875 synonym for @code{No_Requeue_Statements}. This is retained for historical
10876 compatibility purposes (and a warning will be generated for its use if
10877 warnings on oNobsolescent features are activated).
10879 @node No_Secondary_Stack
10880 @unnumberedsubsec No_Secondary_Stack
10881 @findex No_Secondary_Stack
10882 [GNAT] This restriction ensures at compile time that the generated code
10883 does not contain any reference to the secondary stack. The secondary
10884 stack is used to implement functions returning unconstrained objects
10885 (arrays or records) on some targets.
10887 @node No_Select_Statements
10888 @unnumberedsubsec No_Select_Statements
10889 @findex No_Select_Statements
10890 [RM D.7] This restriction ensures at compile time no select statements of any
10891 kind are permitted, that is the keyword @code{select} may not appear.
10893 @node No_Specific_Termination_Handlers
10894 @unnumberedsubsec No_Specific_Termination_Handlers
10895 @findex No_Specific_Termination_Handlers
10896 [RM D.7] There are no calls to Ada.Task_Termination.Set_Specific_Handler
10897 or to Ada.Task_Termination.Specific_Handler.
10899 @node No_Specification_of_Aspect
10900 @unnumberedsubsec No_Specification_of_Aspect
10901 @findex No_Specification_of_Aspect
10902 [RM 13.12.1] This restriction checks at compile time that no aspect
10903 specification, attribute definition clause, or pragma is given for a
10906 @node No_Standard_Allocators_After_Elaboration
10907 @unnumberedsubsec No_Standard_Allocators_After_Elaboration
10908 @findex No_Standard_Allocators_After_Elaboration
10909 [RM D.7] Specifies that an allocator using a standard storage pool
10910 should never be evaluated at run time after the elaboration of the
10911 library items of the partition has completed. Otherwise, Storage_Error
10914 @node No_Standard_Storage_Pools
10915 @unnumberedsubsec No_Standard_Storage_Pools
10916 @findex No_Standard_Storage_Pools
10917 [GNAT] This restriction ensures at compile time that no access types
10918 use the standard default storage pool. Any access type declared must
10919 have an explicit Storage_Pool attribute defined specifying a
10920 user-defined storage pool.
10922 @node No_Stream_Optimizations
10923 @unnumberedsubsec No_Stream_Optimizations
10924 @findex No_Stream_Optimizations
10925 [GNAT] This restriction affects the performance of stream operations on types
10926 @code{String}, @code{Wide_String} and @code{Wide_Wide_String}. By default, the
10927 compiler uses block reads and writes when manipulating @code{String} objects
10928 due to their supperior performance. When this restriction is in effect, the
10929 compiler performs all IO operations on a per-character basis.
10932 @unnumberedsubsec No_Streams
10934 [GNAT] This restriction ensures at compile/bind time that there are no
10935 stream objects created and no use of stream attributes.
10936 This restriction does not forbid dependences on the package
10937 @code{Ada.Streams}. So it is permissible to with
10938 @code{Ada.Streams} (or another package that does so itself)
10939 as long as no actual stream objects are created and no
10940 stream attributes are used.
10942 Note that the use of restriction allows optimization of tagged types,
10943 since they do not need to worry about dispatching stream operations.
10944 To take maximum advantage of this space-saving optimization, any
10945 unit declaring a tagged type should be compiled with the restriction,
10946 though this is not required.
10948 @node No_Task_Allocators
10949 @unnumberedsubsec No_Task_Allocators
10950 @findex No_Task_Allocators
10951 [RM D.7] There are no allocators for task types
10952 or types containing task subcomponents.
10954 @node No_Task_Attributes_Package
10955 @unnumberedsubsec No_Task_Attributes_Package
10956 @findex No_Task_Attributes_Package
10957 [GNAT] This restriction ensures at compile time that there are no implicit or
10958 explicit dependencies on the package @code{Ada.Task_Attributes}.
10960 @findex No_Task_Attributes
10961 The restriction @code{No_Task_Attributes} is recognized as a synonym
10962 for @code{No_Task_Attributes_Package}. This is retained for historical
10963 compatibility purposes (and a warning will be generated for its use if
10964 warnings on obsolescent features are activated).
10966 @node No_Task_Hierarchy
10967 @unnumberedsubsec No_Task_Hierarchy
10968 @findex No_Task_Hierarchy
10969 [RM D.7] All (non-environment) tasks depend
10970 directly on the environment task of the partition.
10972 @node No_Task_Termination
10973 @unnumberedsubsec No_Task_Termination
10974 @findex No_Task_Termination
10975 [RM D.7] Tasks that terminate are erroneous.
10978 @unnumberedsubsec No_Tasking
10980 [GNAT] This restriction prevents the declaration of tasks or task types
10981 throughout the partition. It is similar in effect to the use of
10982 @code{Max_Tasks => 0} except that violations are caught at compile time
10983 and cause an error message to be output either by the compiler or
10986 @node No_Terminate_Alternatives
10987 @unnumberedsubsec No_Terminate_Alternatives
10988 @findex No_Terminate_Alternatives
10989 [RM D.7] There are no selective accepts with terminate alternatives.
10991 @node No_Unchecked_Access
10992 @unnumberedsubsec No_Unchecked_Access
10993 @findex No_Unchecked_Access
10994 [RM H.4] This restriction ensures at compile time that there are no
10995 occurrences of the Unchecked_Access attribute.
10997 @node Simple_Barriers
10998 @unnumberedsubsec Simple_Barriers
10999 @findex Simple_Barriers
11000 [RM D.7] This restriction ensures at compile time that barriers in entry
11001 declarations for protected types are restricted to either static boolean
11002 expressions or references to simple boolean variables defined in the private
11003 part of the protected type. No other form of entry barriers is permitted.
11005 @findex Boolean_Entry_Barriers
11006 The restriction @code{Boolean_Entry_Barriers} is recognized as a
11007 synonym for @code{Simple_Barriers}. This is retained for historical
11008 compatibility purposes (and a warning will be generated for its use if
11009 warnings on obsolescent features are activated).
11011 @node Static_Priorities
11012 @unnumberedsubsec Static_Priorities
11013 @findex Static_Priorities
11014 [GNAT] This restriction ensures at compile time that all priority expressions
11015 are static, and that there are no dependences on the package
11016 @code{Ada.Dynamic_Priorities}.
11018 @node Static_Storage_Size
11019 @unnumberedsubsec Static_Storage_Size
11020 @findex Static_Storage_Size
11021 [GNAT] This restriction ensures at compile time that any expression appearing
11022 in a Storage_Size pragma or attribute definition clause is static.
11024 @node Program Unit Level Restrictions
11025 @section Program Unit Level Restrictions
11028 The second set of restriction identifiers
11029 does not require partition-wide consistency.
11030 The restriction may be enforced for a single
11031 compilation unit without any effect on any of the
11032 other compilation units in the partition.
11035 * No_Elaboration_Code::
11037 * No_Implementation_Aspect_Specifications::
11038 * No_Implementation_Attributes::
11039 * No_Implementation_Identifiers::
11040 * No_Implementation_Pragmas::
11041 * No_Implementation_Restrictions::
11042 * No_Implementation_Units::
11043 * No_Implicit_Aliasing::
11044 * No_Obsolescent_Features::
11045 * No_Wide_Characters::
11049 @node No_Elaboration_Code
11050 @unnumberedsubsec No_Elaboration_Code
11051 @findex No_Elaboration_Code
11052 [GNAT] This restriction ensures at compile time that no elaboration code is
11053 generated. Note that this is not the same condition as is enforced
11054 by pragma @code{Preelaborate}. There are cases in which pragma
11055 @code{Preelaborate} still permits code to be generated (e.g.@: code
11056 to initialize a large array to all zeroes), and there are cases of units
11057 which do not meet the requirements for pragma @code{Preelaborate},
11058 but for which no elaboration code is generated. Generally, it is
11059 the case that preelaborable units will meet the restrictions, with
11060 the exception of large aggregates initialized with an others_clause,
11061 and exception declarations (which generate calls to a run-time
11062 registry procedure). This restriction is enforced on
11063 a unit by unit basis, it need not be obeyed consistently
11064 throughout a partition.
11066 In the case of aggregates with others, if the aggregate has a dynamic
11067 size, there is no way to eliminate the elaboration code (such dynamic
11068 bounds would be incompatible with @code{Preelaborate} in any case). If
11069 the bounds are static, then use of this restriction actually modifies
11070 the code choice of the compiler to avoid generating a loop, and instead
11071 generate the aggregate statically if possible, no matter how many times
11072 the data for the others clause must be repeatedly generated.
11074 It is not possible to precisely document
11075 the constructs which are compatible with this restriction, since,
11076 unlike most other restrictions, this is not a restriction on the
11077 source code, but a restriction on the generated object code. For
11078 example, if the source contains a declaration:
11081 Val : constant Integer := X;
11085 where X is not a static constant, it may be possible, depending
11086 on complex optimization circuitry, for the compiler to figure
11087 out the value of X at compile time, in which case this initialization
11088 can be done by the loader, and requires no initialization code. It
11089 is not possible to document the precise conditions under which the
11090 optimizer can figure this out.
11092 Note that this the implementation of this restriction requires full
11093 code generation. If it is used in conjunction with "semantics only"
11094 checking, then some cases of violations may be missed.
11096 @node No_Entry_Queue
11097 @unnumberedsubsec No_Entry_Queue
11098 @findex No_Entry_Queue
11099 [GNAT] This restriction is a declaration that any protected entry compiled in
11100 the scope of the restriction has at most one task waiting on the entry
11101 at any one time, and so no queue is required. This restriction is not
11102 checked at compile time. A program execution is erroneous if an attempt
11103 is made to queue a second task on such an entry.
11105 @node No_Implementation_Aspect_Specifications
11106 @unnumberedsubsec No_Implementation_Aspect_Specifications
11107 @findex No_Implementation_Aspect_Specifications
11108 [RM 13.12.1] This restriction checks at compile time that no
11109 GNAT-defined aspects are present. With this restriction, the only
11110 aspects that can be used are those defined in the Ada Reference Manual.
11112 @node No_Implementation_Attributes
11113 @unnumberedsubsec No_Implementation_Attributes
11114 @findex No_Implementation_Attributes
11115 [RM 13.12.1] This restriction checks at compile time that no
11116 GNAT-defined attributes are present. With this restriction, the only
11117 attributes that can be used are those defined in the Ada Reference
11120 @node No_Implementation_Identifiers
11121 @unnumberedsubsec No_Implementation_Identifiers
11122 @findex No_Implementation_Identifiers
11123 [RM 13.12.1] This restriction checks at compile time that no
11124 implementation-defined identifiers (marked with pragma Implementation_Defined)
11125 occur within language-defined packages.
11127 @node No_Implementation_Pragmas
11128 @unnumberedsubsec No_Implementation_Pragmas
11129 @findex No_Implementation_Pragmas
11130 [RM 13.12.1] This restriction checks at compile time that no
11131 GNAT-defined pragmas are present. With this restriction, the only
11132 pragmas that can be used are those defined in the Ada Reference Manual.
11134 @node No_Implementation_Restrictions
11135 @unnumberedsubsec No_Implementation_Restrictions
11136 @findex No_Implementation_Restrictions
11137 [GNAT] This restriction checks at compile time that no GNAT-defined restriction
11138 identifiers (other than @code{No_Implementation_Restrictions} itself)
11139 are present. With this restriction, the only other restriction identifiers
11140 that can be used are those defined in the Ada Reference Manual.
11142 @node No_Implementation_Units
11143 @unnumberedsubsec No_Implementation_Units
11144 @findex No_Implementation_Units
11145 [RM 13.12.1] This restriction checks at compile time that there is no
11146 mention in the context clause of any implementation-defined descendants
11147 of packages Ada, Interfaces, or System.
11149 @node No_Implicit_Aliasing
11150 @unnumberedsubsec No_Implicit_Aliasing
11151 @findex No_Implicit_Aliasing
11152 [GNAT] This restriction, which is not required to be partition-wide consistent,
11153 requires an explicit aliased keyword for an object to which 'Access,
11154 'Unchecked_Access, or 'Address is applied, and forbids entirely the use of
11155 the 'Unrestricted_Access attribute for objects. Note: the reason that
11156 Unrestricted_Access is forbidden is that it would require the prefix
11157 to be aliased, and in such cases, it can always be replaced by
11158 the standard attribute Unchecked_Access which is preferable.
11160 @node No_Obsolescent_Features
11161 @unnumberedsubsec No_Obsolescent_Features
11162 @findex No_Obsolescent_Features
11163 [RM 13.12.1] This restriction checks at compile time that no obsolescent
11164 features are used, as defined in Annex J of the Ada Reference Manual.
11166 @node No_Wide_Characters
11167 @unnumberedsubsec No_Wide_Characters
11168 @findex No_Wide_Characters
11169 [GNAT] This restriction ensures at compile time that no uses of the types
11170 @code{Wide_Character} or @code{Wide_String} or corresponding wide
11172 appear, and that no wide or wide wide string or character literals
11173 appear in the program (that is literals representing characters not in
11174 type @code{Character}).
11177 @unnumberedsubsec SPARK_05
11179 [GNAT] This restriction checks at compile time that some constructs
11180 forbidden in SPARK 2005 are not present. Error messages related to
11181 SPARK restriction have the form:
11184 violation of restriction "SPARK_05" at <source-location>
11189 The restriction @code{SPARK} is recognized as a
11190 synonym for @code{SPARK_05}. This is retained for historical
11191 compatibility purposes (and an unconditional warning will be generated
11192 for its use, advising replacement by @code{SPARK}).
11194 This is not a replacement for the semantic checks performed by the
11195 SPARK Examiner tool, as the compiler currently only deals with code,
11196 not SPARK 2005 annotations, and does not guarantee catching all
11197 cases of constructs forbidden by SPARK 2005.
11199 Thus it may well be the case that code which passes the compiler with
11200 the SPARK restriction is rejected by the SPARK Examiner, e.g. due to
11201 the different visibility rules of the Examiner based on SPARK 2005
11202 @code{inherit} annotations.
11204 This restriction can be useful in providing an initial filter for code
11205 developed using SPARK 2005, or in examining legacy code to see how far
11206 it is from meeting SPARK restrictions.
11208 The list below summarizes the checks that are performed when this
11209 restriction is in force:
11211 @item No block statements
11212 @item No case statements with only an others clause
11213 @item Exit statements in loops must respect the SPARK 2005 language restrictions
11214 @item No goto statements
11215 @item Return can only appear as last statement in function
11216 @item Function must have return statement
11217 @item Loop parameter specification must include subtype mark
11218 @item Prefix of expanded name cannot be a loop statement
11219 @item Abstract subprogram not allowed
11220 @item User-defined operators not allowed
11221 @item Access type parameters not allowed
11222 @item Default expressions for parameters not allowed
11223 @item Default expressions for record fields not allowed
11224 @item No tasking constructs allowed
11225 @item Label needed at end of subprograms and packages
11226 @item No mixing of positional and named parameter association
11227 @item No access types as result type
11228 @item No unconstrained arrays as result types
11229 @item No null procedures
11230 @item Initial and later declarations must be in correct order (declaration can't come after body)
11231 @item No attributes on private types if full declaration not visible
11232 @item No package declaration within package specification
11233 @item No controlled types
11234 @item No discriminant types
11235 @item No overloading
11236 @item Selector name cannot be operator symbol (i.e. operator symbol cannot be prefixed)
11237 @item Access attribute not allowed
11238 @item Allocator not allowed
11239 @item Result of catenation must be String
11240 @item Operands of catenation must be string literal, static char or another catenation
11241 @item No conditional expressions
11242 @item No explicit dereference
11243 @item Quantified expression not allowed
11244 @item Slicing not allowed
11245 @item No exception renaming
11246 @item No generic renaming
11247 @item No object renaming
11248 @item No use clause
11249 @item Aggregates must be qualified
11250 @item Non-static choice in array aggregates not allowed
11251 @item The only view conversions which are allowed as in-out parameters are conversions of a tagged type to an ancestor type
11252 @item No mixing of positional and named association in aggregate, no multi choice
11253 @item AND, OR and XOR for arrays only allowed when operands have same static bounds
11254 @item Fixed point operands to * or / must be qualified or converted
11255 @item Comparison operators not allowed for Booleans or arrays (except strings)
11256 @item Equality not allowed for arrays with non-matching static bounds (except strings)
11257 @item Conversion / qualification not allowed for arrays with non-matching static bounds
11258 @item Subprogram declaration only allowed in package spec (unless followed by import)
11259 @item Access types not allowed
11260 @item Incomplete type declaration not allowed
11261 @item Object and subtype declarations must respect SPARK restrictions
11262 @item Digits or delta constraint not allowed
11263 @item Decimal fixed point type not allowed
11264 @item Aliasing of objects not allowed
11265 @item Modular type modulus must be power of 2
11266 @item Base not allowed on subtype mark
11267 @item Unary operators not allowed on modular types (except not)
11268 @item Untagged record cannot be null
11269 @item No class-wide operations
11270 @item Initialization expressions must respect SPARK restrictions
11271 @item Non-static ranges not allowed except in iteration schemes
11272 @item String subtypes must have lower bound of 1
11273 @item Subtype of Boolean cannot have constraint
11274 @item At most one tagged type or extension per package
11275 @item Interface is not allowed
11276 @item Character literal cannot be prefixed (selector name cannot be character literal)
11277 @item Record aggregate cannot contain 'others'
11278 @item Component association in record aggregate must contain a single choice
11279 @item Ancestor part cannot be a type mark
11280 @item Attributes 'Image, 'Width and 'Value not allowed
11281 @item Functions may not update globals
11282 @item Subprograms may not contain direct calls to themselves (prevents recursion within unit)
11283 @item Call to subprogram not allowed in same unit before body has been seen (prevents recursion within unit)
11286 The following restrictions are enforced, but note that they are actually more
11287 strict that the latest SPARK 2005 language definition:
11290 @item No derived types other than tagged type extensions
11291 @item Subtype of unconstrained array must have constraint
11294 This list summarises the main SPARK 2005 language rules that are not
11295 currently checked by the SPARK_05 restriction:
11298 @item SPARK annotations are treated as comments so are not checked at all
11299 @item Based real literals not allowed
11300 @item Objects cannot be initialized at declaration by calls to user-defined functions
11301 @item Objects cannot be initialized at declaration by assignments from variables
11302 @item Objects cannot be initialized at declaration by assignments from indexed/selected components
11303 @item Ranges shall not be null
11304 @item A fixed point delta expression must be a simple expression
11305 @item Restrictions on where renaming declarations may be placed
11306 @item Externals of mode 'out' cannot be referenced
11307 @item Externals of mode 'in' cannot be updated
11308 @item Loop with no iteration scheme or exits only allowed as last statement in main program or task
11309 @item Subprogram cannot have parent unit name
11310 @item SPARK 2005 inherited subprogram must be prefixed with overriding
11311 @item External variables (or functions that reference them) may not be passed as actual parameters
11312 @item Globals must be explicitly mentioned in contract
11313 @item Deferred constants cannot be completed by pragma Import
11314 @item Package initialization cannot read/write variables from other packages
11315 @item Prefix not allowed for entities that are directly visible
11316 @item Identifier declaration can't override inherited package name
11317 @item Cannot use Standard or other predefined packages as identifiers
11318 @item After renaming, cannot use the original name
11319 @item Subprograms can only be renamed to remove package prefix
11320 @item Pragma import must be immediately after entity it names
11321 @item No mutual recursion between multiple units (this can be checked with gnatcheck)
11324 Note that if a unit is compiled in Ada 95 mode with the SPARK restriction,
11325 violations will be reported for constructs forbidden in SPARK 95,
11326 instead of SPARK 2005.
11328 @c ------------------------
11329 @node Implementation Advice
11330 @chapter Implementation Advice
11332 The main text of the Ada Reference Manual describes the required
11333 behavior of all Ada compilers, and the GNAT compiler conforms to
11334 these requirements.
11336 In addition, there are sections throughout the Ada Reference Manual headed
11337 by the phrase ``Implementation advice''. These sections are not normative,
11338 i.e., they do not specify requirements that all compilers must
11339 follow. Rather they provide advice on generally desirable behavior. You
11340 may wonder why they are not requirements. The most typical answer is
11341 that they describe behavior that seems generally desirable, but cannot
11342 be provided on all systems, or which may be undesirable on some systems.
11344 As far as practical, GNAT follows the implementation advice sections in
11345 the Ada Reference Manual. This chapter contains a table giving the
11346 reference manual section number, paragraph number and several keywords
11347 for each advice. Each entry consists of the text of the advice followed
11348 by the GNAT interpretation of this advice. Most often, this simply says
11349 ``followed'', which means that GNAT follows the advice. However, in a
11350 number of cases, GNAT deliberately deviates from this advice, in which
11351 case the text describes what GNAT does and why.
11353 @cindex Error detection
11354 @unnumberedsec 1.1.3(20): Error Detection
11357 If an implementation detects the use of an unsupported Specialized Needs
11358 Annex feature at run time, it should raise @code{Program_Error} if
11361 Not relevant. All specialized needs annex features are either supported,
11362 or diagnosed at compile time.
11364 @cindex Child Units
11365 @unnumberedsec 1.1.3(31): Child Units
11368 If an implementation wishes to provide implementation-defined
11369 extensions to the functionality of a language-defined library unit, it
11370 should normally do so by adding children to the library unit.
11374 @cindex Bounded errors
11375 @unnumberedsec 1.1.5(12): Bounded Errors
11378 If an implementation detects a bounded error or erroneous
11379 execution, it should raise @code{Program_Error}.
11381 Followed in all cases in which the implementation detects a bounded
11382 error or erroneous execution. Not all such situations are detected at
11386 @unnumberedsec 2.8(16): Pragmas
11389 Normally, implementation-defined pragmas should have no semantic effect
11390 for error-free programs; that is, if the implementation-defined pragmas
11391 are removed from a working program, the program should still be legal,
11392 and should still have the same semantics.
11394 The following implementation defined pragmas are exceptions to this
11406 @item CPP_Constructor
11410 @item Interface_Name
11412 @item Machine_Attribute
11414 @item Unimplemented_Unit
11416 @item Unchecked_Union
11421 In each of the above cases, it is essential to the purpose of the pragma
11422 that this advice not be followed. For details see the separate section
11423 on implementation defined pragmas.
11425 @unnumberedsec 2.8(17-19): Pragmas
11428 Normally, an implementation should not define pragmas that can
11429 make an illegal program legal, except as follows:
11433 A pragma used to complete a declaration, such as a pragma @code{Import};
11437 A pragma used to configure the environment by adding, removing, or
11438 replacing @code{library_items}.
11440 See response to paragraph 16 of this same section.
11442 @cindex Character Sets
11443 @cindex Alternative Character Sets
11444 @unnumberedsec 3.5.2(5): Alternative Character Sets
11447 If an implementation supports a mode with alternative interpretations
11448 for @code{Character} and @code{Wide_Character}, the set of graphic
11449 characters of @code{Character} should nevertheless remain a proper
11450 subset of the set of graphic characters of @code{Wide_Character}. Any
11451 character set ``localizations'' should be reflected in the results of
11452 the subprograms defined in the language-defined package
11453 @code{Characters.Handling} (see A.3) available in such a mode. In a mode with
11454 an alternative interpretation of @code{Character}, the implementation should
11455 also support a corresponding change in what is a legal
11456 @code{identifier_letter}.
11458 Not all wide character modes follow this advice, in particular the JIS
11459 and IEC modes reflect standard usage in Japan, and in these encoding,
11460 the upper half of the Latin-1 set is not part of the wide-character
11461 subset, since the most significant bit is used for wide character
11462 encoding. However, this only applies to the external forms. Internally
11463 there is no such restriction.
11465 @cindex Integer types
11466 @unnumberedsec 3.5.4(28): Integer Types
11470 An implementation should support @code{Long_Integer} in addition to
11471 @code{Integer} if the target machine supports 32-bit (or longer)
11472 arithmetic. No other named integer subtypes are recommended for package
11473 @code{Standard}. Instead, appropriate named integer subtypes should be
11474 provided in the library package @code{Interfaces} (see B.2).
11476 @code{Long_Integer} is supported. Other standard integer types are supported
11477 so this advice is not fully followed. These types
11478 are supported for convenient interface to C, and so that all hardware
11479 types of the machine are easily available.
11480 @unnumberedsec 3.5.4(29): Integer Types
11484 An implementation for a two's complement machine should support
11485 modular types with a binary modulus up to @code{System.Max_Int*2+2}. An
11486 implementation should support a non-binary modules up to @code{Integer'Last}.
11490 @cindex Enumeration values
11491 @unnumberedsec 3.5.5(8): Enumeration Values
11494 For the evaluation of a call on @code{@var{S}'Pos} for an enumeration
11495 subtype, if the value of the operand does not correspond to the internal
11496 code for any enumeration literal of its type (perhaps due to an
11497 un-initialized variable), then the implementation should raise
11498 @code{Program_Error}. This is particularly important for enumeration
11499 types with noncontiguous internal codes specified by an
11500 enumeration_representation_clause.
11504 @cindex Float types
11505 @unnumberedsec 3.5.7(17): Float Types
11508 An implementation should support @code{Long_Float} in addition to
11509 @code{Float} if the target machine supports 11 or more digits of
11510 precision. No other named floating point subtypes are recommended for
11511 package @code{Standard}. Instead, appropriate named floating point subtypes
11512 should be provided in the library package @code{Interfaces} (see B.2).
11514 @code{Short_Float} and @code{Long_Long_Float} are also provided. The
11515 former provides improved compatibility with other implementations
11516 supporting this type. The latter corresponds to the highest precision
11517 floating-point type supported by the hardware. On most machines, this
11518 will be the same as @code{Long_Float}, but on some machines, it will
11519 correspond to the IEEE extended form. The notable case is all ia32
11520 (x86) implementations, where @code{Long_Long_Float} corresponds to
11521 the 80-bit extended precision format supported in hardware on this
11522 processor. Note that the 128-bit format on SPARC is not supported,
11523 since this is a software rather than a hardware format.
11525 @cindex Multidimensional arrays
11526 @cindex Arrays, multidimensional
11527 @unnumberedsec 3.6.2(11): Multidimensional Arrays
11530 An implementation should normally represent multidimensional arrays in
11531 row-major order, consistent with the notation used for multidimensional
11532 array aggregates (see 4.3.3). However, if a pragma @code{Convention}
11533 (@code{Fortran}, @dots{}) applies to a multidimensional array type, then
11534 column-major order should be used instead (see B.5, ``Interfacing with
11539 @findex Duration'Small
11540 @unnumberedsec 9.6(30-31): Duration'Small
11543 Whenever possible in an implementation, the value of @code{Duration'Small}
11544 should be no greater than 100 microseconds.
11546 Followed. (@code{Duration'Small} = 10**(@minus{}9)).
11550 The time base for @code{delay_relative_statements} should be monotonic;
11551 it need not be the same time base as used for @code{Calendar.Clock}.
11555 @unnumberedsec 10.2.1(12): Consistent Representation
11558 In an implementation, a type declared in a pre-elaborated package should
11559 have the same representation in every elaboration of a given version of
11560 the package, whether the elaborations occur in distinct executions of
11561 the same program, or in executions of distinct programs or partitions
11562 that include the given version.
11564 Followed, except in the case of tagged types. Tagged types involve
11565 implicit pointers to a local copy of a dispatch table, and these pointers
11566 have representations which thus depend on a particular elaboration of the
11567 package. It is not easy to see how it would be possible to follow this
11568 advice without severely impacting efficiency of execution.
11570 @cindex Exception information
11571 @unnumberedsec 11.4.1(19): Exception Information
11574 @code{Exception_Message} by default and @code{Exception_Information}
11575 should produce information useful for
11576 debugging. @code{Exception_Message} should be short, about one
11577 line. @code{Exception_Information} can be long. @code{Exception_Message}
11578 should not include the
11579 @code{Exception_Name}. @code{Exception_Information} should include both
11580 the @code{Exception_Name} and the @code{Exception_Message}.
11582 Followed. For each exception that doesn't have a specified
11583 @code{Exception_Message}, the compiler generates one containing the location
11584 of the raise statement. This location has the form ``file:line'', where
11585 file is the short file name (without path information) and line is the line
11586 number in the file. Note that in the case of the Zero Cost Exception
11587 mechanism, these messages become redundant with the Exception_Information that
11588 contains a full backtrace of the calling sequence, so they are disabled.
11589 To disable explicitly the generation of the source location message, use the
11590 Pragma @code{Discard_Names}.
11592 @cindex Suppression of checks
11593 @cindex Checks, suppression of
11594 @unnumberedsec 11.5(28): Suppression of Checks
11597 The implementation should minimize the code executed for checks that
11598 have been suppressed.
11602 @cindex Representation clauses
11603 @unnumberedsec 13.1 (21-24): Representation Clauses
11606 The recommended level of support for all representation items is
11607 qualified as follows:
11611 An implementation need not support representation items containing
11612 non-static expressions, except that an implementation should support a
11613 representation item for a given entity if each non-static expression in
11614 the representation item is a name that statically denotes a constant
11615 declared before the entity.
11617 Followed. In fact, GNAT goes beyond the recommended level of support
11618 by allowing nonstatic expressions in some representation clauses even
11619 without the need to declare constants initialized with the values of
11623 @smallexample @c ada
11626 for Y'Address use X'Address;>>
11631 An implementation need not support a specification for the @code{Size}
11632 for a given composite subtype, nor the size or storage place for an
11633 object (including a component) of a given composite subtype, unless the
11634 constraints on the subtype and its composite subcomponents (if any) are
11635 all static constraints.
11637 Followed. Size Clauses are not permitted on non-static components, as
11642 An aliased component, or a component whose type is by-reference, should
11643 always be allocated at an addressable location.
11647 @cindex Packed types
11648 @unnumberedsec 13.2(6-8): Packed Types
11651 If a type is packed, then the implementation should try to minimize
11652 storage allocated to objects of the type, possibly at the expense of
11653 speed of accessing components, subject to reasonable complexity in
11654 addressing calculations.
11658 The recommended level of support pragma @code{Pack} is:
11660 For a packed record type, the components should be packed as tightly as
11661 possible subject to the Sizes of the component subtypes, and subject to
11662 any @code{record_representation_clause} that applies to the type; the
11663 implementation may, but need not, reorder components or cross aligned
11664 word boundaries to improve the packing. A component whose @code{Size} is
11665 greater than the word size may be allocated an integral number of words.
11667 Followed. Tight packing of arrays is supported for all component sizes
11668 up to 64-bits. If the array component size is 1 (that is to say, if
11669 the component is a boolean type or an enumeration type with two values)
11670 then values of the type are implicitly initialized to zero. This
11671 happens both for objects of the packed type, and for objects that have a
11672 subcomponent of the packed type.
11676 An implementation should support Address clauses for imported
11680 @cindex @code{Address} clauses
11681 @unnumberedsec 13.3(14-19): Address Clauses
11685 For an array @var{X}, @code{@var{X}'Address} should point at the first
11686 component of the array, and not at the array bounds.
11692 The recommended level of support for the @code{Address} attribute is:
11694 @code{@var{X}'Address} should produce a useful result if @var{X} is an
11695 object that is aliased or of a by-reference type, or is an entity whose
11696 @code{Address} has been specified.
11698 Followed. A valid address will be produced even if none of those
11699 conditions have been met. If necessary, the object is forced into
11700 memory to ensure the address is valid.
11704 An implementation should support @code{Address} clauses for imported
11711 Objects (including subcomponents) that are aliased or of a by-reference
11712 type should be allocated on storage element boundaries.
11718 If the @code{Address} of an object is specified, or it is imported or exported,
11719 then the implementation should not perform optimizations based on
11720 assumptions of no aliases.
11724 @cindex @code{Alignment} clauses
11725 @unnumberedsec 13.3(29-35): Alignment Clauses
11728 The recommended level of support for the @code{Alignment} attribute for
11731 An implementation should support specified Alignments that are factors
11732 and multiples of the number of storage elements per word, subject to the
11739 An implementation need not support specified @code{Alignment}s for
11740 combinations of @code{Size}s and @code{Alignment}s that cannot be easily
11741 loaded and stored by available machine instructions.
11747 An implementation need not support specified @code{Alignment}s that are
11748 greater than the maximum @code{Alignment} the implementation ever returns by
11755 The recommended level of support for the @code{Alignment} attribute for
11758 Same as above, for subtypes, but in addition:
11764 For stand-alone library-level objects of statically constrained
11765 subtypes, the implementation should support all @code{Alignment}s
11766 supported by the target linker. For example, page alignment is likely to
11767 be supported for such objects, but not for subtypes.
11771 @cindex @code{Size} clauses
11772 @unnumberedsec 13.3(42-43): Size Clauses
11775 The recommended level of support for the @code{Size} attribute of
11778 A @code{Size} clause should be supported for an object if the specified
11779 @code{Size} is at least as large as its subtype's @code{Size}, and
11780 corresponds to a size in storage elements that is a multiple of the
11781 object's @code{Alignment} (if the @code{Alignment} is nonzero).
11785 @unnumberedsec 13.3(50-56): Size Clauses
11788 If the @code{Size} of a subtype is specified, and allows for efficient
11789 independent addressability (see 9.10) on the target architecture, then
11790 the @code{Size} of the following objects of the subtype should equal the
11791 @code{Size} of the subtype:
11793 Aliased objects (including components).
11799 @code{Size} clause on a composite subtype should not affect the
11800 internal layout of components.
11802 Followed. But note that this can be overridden by use of the implementation
11803 pragma Implicit_Packing in the case of packed arrays.
11807 The recommended level of support for the @code{Size} attribute of subtypes is:
11811 The @code{Size} (if not specified) of a static discrete or fixed point
11812 subtype should be the number of bits needed to represent each value
11813 belonging to the subtype using an unbiased representation, leaving space
11814 for a sign bit only if the subtype contains negative values. If such a
11815 subtype is a first subtype, then an implementation should support a
11816 specified @code{Size} for it that reflects this representation.
11822 For a subtype implemented with levels of indirection, the @code{Size}
11823 should include the size of the pointers, but not the size of what they
11828 @cindex @code{Component_Size} clauses
11829 @unnumberedsec 13.3(71-73): Component Size Clauses
11832 The recommended level of support for the @code{Component_Size}
11837 An implementation need not support specified @code{Component_Sizes} that are
11838 less than the @code{Size} of the component subtype.
11844 An implementation should support specified @code{Component_Size}s that
11845 are factors and multiples of the word size. For such
11846 @code{Component_Size}s, the array should contain no gaps between
11847 components. For other @code{Component_Size}s (if supported), the array
11848 should contain no gaps between components when packing is also
11849 specified; the implementation should forbid this combination in cases
11850 where it cannot support a no-gaps representation.
11854 @cindex Enumeration representation clauses
11855 @cindex Representation clauses, enumeration
11856 @unnumberedsec 13.4(9-10): Enumeration Representation Clauses
11859 The recommended level of support for enumeration representation clauses
11862 An implementation need not support enumeration representation clauses
11863 for boolean types, but should at minimum support the internal codes in
11864 the range @code{System.Min_Int.System.Max_Int}.
11868 @cindex Record representation clauses
11869 @cindex Representation clauses, records
11870 @unnumberedsec 13.5.1(17-22): Record Representation Clauses
11873 The recommended level of support for
11874 @*@code{record_representation_clauses} is:
11876 An implementation should support storage places that can be extracted
11877 with a load, mask, shift sequence of machine code, and set with a load,
11878 shift, mask, store sequence, given the available machine instructions
11879 and run-time model.
11885 A storage place should be supported if its size is equal to the
11886 @code{Size} of the component subtype, and it starts and ends on a
11887 boundary that obeys the @code{Alignment} of the component subtype.
11893 If the default bit ordering applies to the declaration of a given type,
11894 then for a component whose subtype's @code{Size} is less than the word
11895 size, any storage place that does not cross an aligned word boundary
11896 should be supported.
11902 An implementation may reserve a storage place for the tag field of a
11903 tagged type, and disallow other components from overlapping that place.
11905 Followed. The storage place for the tag field is the beginning of the tagged
11906 record, and its size is Address'Size. GNAT will reject an explicit component
11907 clause for the tag field.
11911 An implementation need not support a @code{component_clause} for a
11912 component of an extension part if the storage place is not after the
11913 storage places of all components of the parent type, whether or not
11914 those storage places had been specified.
11916 Followed. The above advice on record representation clauses is followed,
11917 and all mentioned features are implemented.
11919 @cindex Storage place attributes
11920 @unnumberedsec 13.5.2(5): Storage Place Attributes
11923 If a component is represented using some form of pointer (such as an
11924 offset) to the actual data of the component, and this data is contiguous
11925 with the rest of the object, then the storage place attributes should
11926 reflect the place of the actual data, not the pointer. If a component is
11927 allocated discontinuously from the rest of the object, then a warning
11928 should be generated upon reference to one of its storage place
11931 Followed. There are no such components in GNAT@.
11933 @cindex Bit ordering
11934 @unnumberedsec 13.5.3(7-8): Bit Ordering
11937 The recommended level of support for the non-default bit ordering is:
11941 If @code{Word_Size} = @code{Storage_Unit}, then the implementation
11942 should support the non-default bit ordering in addition to the default
11945 Followed. Word size does not equal storage size in this implementation.
11946 Thus non-default bit ordering is not supported.
11948 @cindex @code{Address}, as private type
11949 @unnumberedsec 13.7(37): Address as Private
11952 @code{Address} should be of a private type.
11956 @cindex Operations, on @code{Address}
11957 @cindex @code{Address}, operations of
11958 @unnumberedsec 13.7.1(16): Address Operations
11961 Operations in @code{System} and its children should reflect the target
11962 environment semantics as closely as is reasonable. For example, on most
11963 machines, it makes sense for address arithmetic to ``wrap around''.
11964 Operations that do not make sense should raise @code{Program_Error}.
11966 Followed. Address arithmetic is modular arithmetic that wraps around. No
11967 operation raises @code{Program_Error}, since all operations make sense.
11969 @cindex Unchecked conversion
11970 @unnumberedsec 13.9(14-17): Unchecked Conversion
11973 The @code{Size} of an array object should not include its bounds; hence,
11974 the bounds should not be part of the converted data.
11980 The implementation should not generate unnecessary run-time checks to
11981 ensure that the representation of @var{S} is a representation of the
11982 target type. It should take advantage of the permission to return by
11983 reference when possible. Restrictions on unchecked conversions should be
11984 avoided unless required by the target environment.
11986 Followed. There are no restrictions on unchecked conversion. A warning is
11987 generated if the source and target types do not have the same size since
11988 the semantics in this case may be target dependent.
11992 The recommended level of support for unchecked conversions is:
11996 Unchecked conversions should be supported and should be reversible in
11997 the cases where this clause defines the result. To enable meaningful use
11998 of unchecked conversion, a contiguous representation should be used for
11999 elementary subtypes, for statically constrained array subtypes whose
12000 component subtype is one of the subtypes described in this paragraph,
12001 and for record subtypes without discriminants whose component subtypes
12002 are described in this paragraph.
12006 @cindex Heap usage, implicit
12007 @unnumberedsec 13.11(23-25): Implicit Heap Usage
12010 An implementation should document any cases in which it dynamically
12011 allocates heap storage for a purpose other than the evaluation of an
12014 Followed, the only other points at which heap storage is dynamically
12015 allocated are as follows:
12019 At initial elaboration time, to allocate dynamically sized global
12023 To allocate space for a task when a task is created.
12026 To extend the secondary stack dynamically when needed. The secondary
12027 stack is used for returning variable length results.
12032 A default (implementation-provided) storage pool for an
12033 access-to-constant type should not have overhead to support deallocation of
12034 individual objects.
12040 A storage pool for an anonymous access type should be created at the
12041 point of an allocator for the type, and be reclaimed when the designated
12042 object becomes inaccessible.
12046 @cindex Unchecked deallocation
12047 @unnumberedsec 13.11.2(17): Unchecked De-allocation
12050 For a standard storage pool, @code{Free} should actually reclaim the
12055 @cindex Stream oriented attributes
12056 @unnumberedsec 13.13.2(17): Stream Oriented Attributes
12059 If a stream element is the same size as a storage element, then the
12060 normal in-memory representation should be used by @code{Read} and
12061 @code{Write} for scalar objects. Otherwise, @code{Read} and @code{Write}
12062 should use the smallest number of stream elements needed to represent
12063 all values in the base range of the scalar type.
12066 Followed. By default, GNAT uses the interpretation suggested by AI-195,
12067 which specifies using the size of the first subtype.
12068 However, such an implementation is based on direct binary
12069 representations and is therefore target- and endianness-dependent.
12070 To address this issue, GNAT also supplies an alternate implementation
12071 of the stream attributes @code{Read} and @code{Write},
12072 which uses the target-independent XDR standard representation
12074 @cindex XDR representation
12075 @cindex @code{Read} attribute
12076 @cindex @code{Write} attribute
12077 @cindex Stream oriented attributes
12078 The XDR implementation is provided as an alternative body of the
12079 @code{System.Stream_Attributes} package, in the file
12080 @file{s-stratt-xdr.adb} in the GNAT library.
12081 There is no @file{s-stratt-xdr.ads} file.
12082 In order to install the XDR implementation, do the following:
12084 @item Replace the default implementation of the
12085 @code{System.Stream_Attributes} package with the XDR implementation.
12086 For example on a Unix platform issue the commands:
12088 $ mv s-stratt.adb s-stratt-default.adb
12089 $ mv s-stratt-xdr.adb s-stratt.adb
12093 Rebuild the GNAT run-time library as documented in
12094 @ref{GNAT and Libraries,,, gnat_ugn, @value{EDITION} User's Guide}.
12097 @unnumberedsec A.1(52): Names of Predefined Numeric Types
12100 If an implementation provides additional named predefined integer types,
12101 then the names should end with @samp{Integer} as in
12102 @samp{Long_Integer}. If an implementation provides additional named
12103 predefined floating point types, then the names should end with
12104 @samp{Float} as in @samp{Long_Float}.
12108 @findex Ada.Characters.Handling
12109 @unnumberedsec A.3.2(49): @code{Ada.Characters.Handling}
12112 If an implementation provides a localized definition of @code{Character}
12113 or @code{Wide_Character}, then the effects of the subprograms in
12114 @code{Characters.Handling} should reflect the localizations. See also
12117 Followed. GNAT provides no such localized definitions.
12119 @cindex Bounded-length strings
12120 @unnumberedsec A.4.4(106): Bounded-Length String Handling
12123 Bounded string objects should not be implemented by implicit pointers
12124 and dynamic allocation.
12126 Followed. No implicit pointers or dynamic allocation are used.
12128 @cindex Random number generation
12129 @unnumberedsec A.5.2(46-47): Random Number Generation
12132 Any storage associated with an object of type @code{Generator} should be
12133 reclaimed on exit from the scope of the object.
12139 If the generator period is sufficiently long in relation to the number
12140 of distinct initiator values, then each possible value of
12141 @code{Initiator} passed to @code{Reset} should initiate a sequence of
12142 random numbers that does not, in a practical sense, overlap the sequence
12143 initiated by any other value. If this is not possible, then the mapping
12144 between initiator values and generator states should be a rapidly
12145 varying function of the initiator value.
12147 Followed. The generator period is sufficiently long for the first
12148 condition here to hold true.
12150 @findex Get_Immediate
12151 @unnumberedsec A.10.7(23): @code{Get_Immediate}
12154 The @code{Get_Immediate} procedures should be implemented with
12155 unbuffered input. For a device such as a keyboard, input should be
12156 @dfn{available} if a key has already been typed, whereas for a disk
12157 file, input should always be available except at end of file. For a file
12158 associated with a keyboard-like device, any line-editing features of the
12159 underlying operating system should be disabled during the execution of
12160 @code{Get_Immediate}.
12162 Followed on all targets except VxWorks. For VxWorks, there is no way to
12163 provide this functionality that does not result in the input buffer being
12164 flushed before the @code{Get_Immediate} call. A special unit
12165 @code{Interfaces.Vxworks.IO} is provided that contains routines to enable
12166 this functionality.
12169 @unnumberedsec B.1(39-41): Pragma @code{Export}
12172 If an implementation supports pragma @code{Export} to a given language,
12173 then it should also allow the main subprogram to be written in that
12174 language. It should support some mechanism for invoking the elaboration
12175 of the Ada library units included in the system, and for invoking the
12176 finalization of the environment task. On typical systems, the
12177 recommended mechanism is to provide two subprograms whose link names are
12178 @code{adainit} and @code{adafinal}. @code{adainit} should contain the
12179 elaboration code for library units. @code{adafinal} should contain the
12180 finalization code. These subprograms should have no effect the second
12181 and subsequent time they are called.
12187 Automatic elaboration of pre-elaborated packages should be
12188 provided when pragma @code{Export} is supported.
12190 Followed when the main program is in Ada. If the main program is in a
12191 foreign language, then
12192 @code{adainit} must be called to elaborate pre-elaborated
12197 For each supported convention @var{L} other than @code{Intrinsic}, an
12198 implementation should support @code{Import} and @code{Export} pragmas
12199 for objects of @var{L}-compatible types and for subprograms, and pragma
12200 @code{Convention} for @var{L}-eligible types and for subprograms,
12201 presuming the other language has corresponding features. Pragma
12202 @code{Convention} need not be supported for scalar types.
12206 @cindex Package @code{Interfaces}
12208 @unnumberedsec B.2(12-13): Package @code{Interfaces}
12211 For each implementation-defined convention identifier, there should be a
12212 child package of package Interfaces with the corresponding name. This
12213 package should contain any declarations that would be useful for
12214 interfacing to the language (implementation) represented by the
12215 convention. Any declarations useful for interfacing to any language on
12216 the given hardware architecture should be provided directly in
12223 An implementation supporting an interface to C, COBOL, or Fortran should
12224 provide the corresponding package or packages described in the following
12227 Followed. GNAT provides all the packages described in this section.
12229 @cindex C, interfacing with
12230 @unnumberedsec B.3(63-71): Interfacing with C
12233 An implementation should support the following interface correspondences
12234 between Ada and C@.
12240 An Ada procedure corresponds to a void-returning C function.
12246 An Ada function corresponds to a non-void C function.
12252 An Ada @code{in} scalar parameter is passed as a scalar argument to a C
12259 An Ada @code{in} parameter of an access-to-object type with designated
12260 type @var{T} is passed as a @code{@var{t}*} argument to a C function,
12261 where @var{t} is the C type corresponding to the Ada type @var{T}.
12267 An Ada access @var{T} parameter, or an Ada @code{out} or @code{in out}
12268 parameter of an elementary type @var{T}, is passed as a @code{@var{t}*}
12269 argument to a C function, where @var{t} is the C type corresponding to
12270 the Ada type @var{T}. In the case of an elementary @code{out} or
12271 @code{in out} parameter, a pointer to a temporary copy is used to
12272 preserve by-copy semantics.
12278 An Ada parameter of a record type @var{T}, of any mode, is passed as a
12279 @code{@var{t}*} argument to a C function, where @var{t} is the C
12280 structure corresponding to the Ada type @var{T}.
12282 Followed. This convention may be overridden by the use of the C_Pass_By_Copy
12283 pragma, or Convention, or by explicitly specifying the mechanism for a given
12284 call using an extended import or export pragma.
12288 An Ada parameter of an array type with component type @var{T}, of any
12289 mode, is passed as a @code{@var{t}*} argument to a C function, where
12290 @var{t} is the C type corresponding to the Ada type @var{T}.
12296 An Ada parameter of an access-to-subprogram type is passed as a pointer
12297 to a C function whose prototype corresponds to the designated
12298 subprogram's specification.
12302 @cindex COBOL, interfacing with
12303 @unnumberedsec B.4(95-98): Interfacing with COBOL
12306 An Ada implementation should support the following interface
12307 correspondences between Ada and COBOL@.
12313 An Ada access @var{T} parameter is passed as a @samp{BY REFERENCE} data item of
12314 the COBOL type corresponding to @var{T}.
12320 An Ada in scalar parameter is passed as a @samp{BY CONTENT} data item of
12321 the corresponding COBOL type.
12327 Any other Ada parameter is passed as a @samp{BY REFERENCE} data item of the
12328 COBOL type corresponding to the Ada parameter type; for scalars, a local
12329 copy is used if necessary to ensure by-copy semantics.
12333 @cindex Fortran, interfacing with
12334 @unnumberedsec B.5(22-26): Interfacing with Fortran
12337 An Ada implementation should support the following interface
12338 correspondences between Ada and Fortran:
12344 An Ada procedure corresponds to a Fortran subroutine.
12350 An Ada function corresponds to a Fortran function.
12356 An Ada parameter of an elementary, array, or record type @var{T} is
12357 passed as a @var{T} argument to a Fortran procedure, where @var{T} is
12358 the Fortran type corresponding to the Ada type @var{T}, and where the
12359 INTENT attribute of the corresponding dummy argument matches the Ada
12360 formal parameter mode; the Fortran implementation's parameter passing
12361 conventions are used. For elementary types, a local copy is used if
12362 necessary to ensure by-copy semantics.
12368 An Ada parameter of an access-to-subprogram type is passed as a
12369 reference to a Fortran procedure whose interface corresponds to the
12370 designated subprogram's specification.
12374 @cindex Machine operations
12375 @unnumberedsec C.1(3-5): Access to Machine Operations
12378 The machine code or intrinsic support should allow access to all
12379 operations normally available to assembly language programmers for the
12380 target environment, including privileged instructions, if any.
12386 The interfacing pragmas (see Annex B) should support interface to
12387 assembler; the default assembler should be associated with the
12388 convention identifier @code{Assembler}.
12394 If an entity is exported to assembly language, then the implementation
12395 should allocate it at an addressable location, and should ensure that it
12396 is retained by the linking process, even if not otherwise referenced
12397 from the Ada code. The implementation should assume that any call to a
12398 machine code or assembler subprogram is allowed to read or update every
12399 object that is specified as exported.
12403 @unnumberedsec C.1(10-16): Access to Machine Operations
12406 The implementation should ensure that little or no overhead is
12407 associated with calling intrinsic and machine-code subprograms.
12409 Followed for both intrinsics and machine-code subprograms.
12413 It is recommended that intrinsic subprograms be provided for convenient
12414 access to any machine operations that provide special capabilities or
12415 efficiency and that are not otherwise available through the language
12418 Followed. A full set of machine operation intrinsic subprograms is provided.
12422 Atomic read-modify-write operations---e.g.@:, test and set, compare and
12423 swap, decrement and test, enqueue/dequeue.
12425 Followed on any target supporting such operations.
12429 Standard numeric functions---e.g.@:, sin, log.
12431 Followed on any target supporting such operations.
12435 String manipulation operations---e.g.@:, translate and test.
12437 Followed on any target supporting such operations.
12441 Vector operations---e.g.@:, compare vector against thresholds.
12443 Followed on any target supporting such operations.
12447 Direct operations on I/O ports.
12449 Followed on any target supporting such operations.
12451 @cindex Interrupt support
12452 @unnumberedsec C.3(28): Interrupt Support
12455 If the @code{Ceiling_Locking} policy is not in effect, the
12456 implementation should provide means for the application to specify which
12457 interrupts are to be blocked during protected actions, if the underlying
12458 system allows for a finer-grain control of interrupt blocking.
12460 Followed. The underlying system does not allow for finer-grain control
12461 of interrupt blocking.
12463 @cindex Protected procedure handlers
12464 @unnumberedsec C.3.1(20-21): Protected Procedure Handlers
12467 Whenever possible, the implementation should allow interrupt handlers to
12468 be called directly by the hardware.
12470 Followed on any target where the underlying operating system permits
12475 Whenever practical, violations of any
12476 implementation-defined restrictions should be detected before run time.
12478 Followed. Compile time warnings are given when possible.
12480 @cindex Package @code{Interrupts}
12482 @unnumberedsec C.3.2(25): Package @code{Interrupts}
12486 If implementation-defined forms of interrupt handler procedures are
12487 supported, such as protected procedures with parameters, then for each
12488 such form of a handler, a type analogous to @code{Parameterless_Handler}
12489 should be specified in a child package of @code{Interrupts}, with the
12490 same operations as in the predefined package Interrupts.
12494 @cindex Pre-elaboration requirements
12495 @unnumberedsec C.4(14): Pre-elaboration Requirements
12498 It is recommended that pre-elaborated packages be implemented in such a
12499 way that there should be little or no code executed at run time for the
12500 elaboration of entities not already covered by the Implementation
12503 Followed. Executable code is generated in some cases, e.g.@: loops
12504 to initialize large arrays.
12506 @unnumberedsec C.5(8): Pragma @code{Discard_Names}
12509 If the pragma applies to an entity, then the implementation should
12510 reduce the amount of storage used for storing names associated with that
12515 @cindex Package @code{Task_Attributes}
12516 @findex Task_Attributes
12517 @unnumberedsec C.7.2(30): The Package Task_Attributes
12520 Some implementations are targeted to domains in which memory use at run
12521 time must be completely deterministic. For such implementations, it is
12522 recommended that the storage for task attributes will be pre-allocated
12523 statically and not from the heap. This can be accomplished by either
12524 placing restrictions on the number and the size of the task's
12525 attributes, or by using the pre-allocated storage for the first @var{N}
12526 attribute objects, and the heap for the others. In the latter case,
12527 @var{N} should be documented.
12529 Not followed. This implementation is not targeted to such a domain.
12531 @cindex Locking Policies
12532 @unnumberedsec D.3(17): Locking Policies
12536 The implementation should use names that end with @samp{_Locking} for
12537 locking policies defined by the implementation.
12539 Followed. Two implementation-defined locking policies are defined,
12540 whose names (@code{Inheritance_Locking} and
12541 @code{Concurrent_Readers_Locking}) follow this suggestion.
12543 @cindex Entry queuing policies
12544 @unnumberedsec D.4(16): Entry Queuing Policies
12547 Names that end with @samp{_Queuing} should be used
12548 for all implementation-defined queuing policies.
12550 Followed. No such implementation-defined queuing policies exist.
12552 @cindex Preemptive abort
12553 @unnumberedsec D.6(9-10): Preemptive Abort
12556 Even though the @code{abort_statement} is included in the list of
12557 potentially blocking operations (see 9.5.1), it is recommended that this
12558 statement be implemented in a way that never requires the task executing
12559 the @code{abort_statement} to block.
12565 On a multi-processor, the delay associated with aborting a task on
12566 another processor should be bounded; the implementation should use
12567 periodic polling, if necessary, to achieve this.
12571 @cindex Tasking restrictions
12572 @unnumberedsec D.7(21): Tasking Restrictions
12575 When feasible, the implementation should take advantage of the specified
12576 restrictions to produce a more efficient implementation.
12578 GNAT currently takes advantage of these restrictions by providing an optimized
12579 run time when the Ravenscar profile and the GNAT restricted run time set
12580 of restrictions are specified. See pragma @code{Profile (Ravenscar)} and
12581 pragma @code{Profile (Restricted)} for more details.
12583 @cindex Time, monotonic
12584 @unnumberedsec D.8(47-49): Monotonic Time
12587 When appropriate, implementations should provide configuration
12588 mechanisms to change the value of @code{Tick}.
12590 Such configuration mechanisms are not appropriate to this implementation
12591 and are thus not supported.
12595 It is recommended that @code{Calendar.Clock} and @code{Real_Time.Clock}
12596 be implemented as transformations of the same time base.
12602 It is recommended that the @dfn{best} time base which exists in
12603 the underlying system be available to the application through
12604 @code{Clock}. @dfn{Best} may mean highest accuracy or largest range.
12608 @cindex Partition communication subsystem
12610 @unnumberedsec E.5(28-29): Partition Communication Subsystem
12613 Whenever possible, the PCS on the called partition should allow for
12614 multiple tasks to call the RPC-receiver with different messages and
12615 should allow them to block until the corresponding subprogram body
12618 Followed by GLADE, a separately supplied PCS that can be used with
12623 The @code{Write} operation on a stream of type @code{Params_Stream_Type}
12624 should raise @code{Storage_Error} if it runs out of space trying to
12625 write the @code{Item} into the stream.
12627 Followed by GLADE, a separately supplied PCS that can be used with
12630 @cindex COBOL support
12631 @unnumberedsec F(7): COBOL Support
12634 If COBOL (respectively, C) is widely supported in the target
12635 environment, implementations supporting the Information Systems Annex
12636 should provide the child package @code{Interfaces.COBOL} (respectively,
12637 @code{Interfaces.C}) specified in Annex B and should support a
12638 @code{convention_identifier} of COBOL (respectively, C) in the interfacing
12639 pragmas (see Annex B), thus allowing Ada programs to interface with
12640 programs written in that language.
12644 @cindex Decimal radix support
12645 @unnumberedsec F.1(2): Decimal Radix Support
12648 Packed decimal should be used as the internal representation for objects
12649 of subtype @var{S} when @var{S}'Machine_Radix = 10.
12651 Not followed. GNAT ignores @var{S}'Machine_Radix and always uses binary
12655 @unnumberedsec G: Numerics
12658 If Fortran (respectively, C) is widely supported in the target
12659 environment, implementations supporting the Numerics Annex
12660 should provide the child package @code{Interfaces.Fortran} (respectively,
12661 @code{Interfaces.C}) specified in Annex B and should support a
12662 @code{convention_identifier} of Fortran (respectively, C) in the interfacing
12663 pragmas (see Annex B), thus allowing Ada programs to interface with
12664 programs written in that language.
12668 @cindex Complex types
12669 @unnumberedsec G.1.1(56-58): Complex Types
12672 Because the usual mathematical meaning of multiplication of a complex
12673 operand and a real operand is that of the scaling of both components of
12674 the former by the latter, an implementation should not perform this
12675 operation by first promoting the real operand to complex type and then
12676 performing a full complex multiplication. In systems that, in the
12677 future, support an Ada binding to IEC 559:1989, the latter technique
12678 will not generate the required result when one of the components of the
12679 complex operand is infinite. (Explicit multiplication of the infinite
12680 component by the zero component obtained during promotion yields a NaN
12681 that propagates into the final result.) Analogous advice applies in the
12682 case of multiplication of a complex operand and a pure-imaginary
12683 operand, and in the case of division of a complex operand by a real or
12684 pure-imaginary operand.
12690 Similarly, because the usual mathematical meaning of addition of a
12691 complex operand and a real operand is that the imaginary operand remains
12692 unchanged, an implementation should not perform this operation by first
12693 promoting the real operand to complex type and then performing a full
12694 complex addition. In implementations in which the @code{Signed_Zeros}
12695 attribute of the component type is @code{True} (and which therefore
12696 conform to IEC 559:1989 in regard to the handling of the sign of zero in
12697 predefined arithmetic operations), the latter technique will not
12698 generate the required result when the imaginary component of the complex
12699 operand is a negatively signed zero. (Explicit addition of the negative
12700 zero to the zero obtained during promotion yields a positive zero.)
12701 Analogous advice applies in the case of addition of a complex operand
12702 and a pure-imaginary operand, and in the case of subtraction of a
12703 complex operand and a real or pure-imaginary operand.
12709 Implementations in which @code{Real'Signed_Zeros} is @code{True} should
12710 attempt to provide a rational treatment of the signs of zero results and
12711 result components. As one example, the result of the @code{Argument}
12712 function should have the sign of the imaginary component of the
12713 parameter @code{X} when the point represented by that parameter lies on
12714 the positive real axis; as another, the sign of the imaginary component
12715 of the @code{Compose_From_Polar} function should be the same as
12716 (respectively, the opposite of) that of the @code{Argument} parameter when that
12717 parameter has a value of zero and the @code{Modulus} parameter has a
12718 nonnegative (respectively, negative) value.
12722 @cindex Complex elementary functions
12723 @unnumberedsec G.1.2(49): Complex Elementary Functions
12726 Implementations in which @code{Complex_Types.Real'Signed_Zeros} is
12727 @code{True} should attempt to provide a rational treatment of the signs
12728 of zero results and result components. For example, many of the complex
12729 elementary functions have components that are odd functions of one of
12730 the parameter components; in these cases, the result component should
12731 have the sign of the parameter component at the origin. Other complex
12732 elementary functions have zero components whose sign is opposite that of
12733 a parameter component at the origin, or is always positive or always
12738 @cindex Accuracy requirements
12739 @unnumberedsec G.2.4(19): Accuracy Requirements
12742 The versions of the forward trigonometric functions without a
12743 @code{Cycle} parameter should not be implemented by calling the
12744 corresponding version with a @code{Cycle} parameter of
12745 @code{2.0*Numerics.Pi}, since this will not provide the required
12746 accuracy in some portions of the domain. For the same reason, the
12747 version of @code{Log} without a @code{Base} parameter should not be
12748 implemented by calling the corresponding version with a @code{Base}
12749 parameter of @code{Numerics.e}.
12753 @cindex Complex arithmetic accuracy
12754 @cindex Accuracy, complex arithmetic
12755 @unnumberedsec G.2.6(15): Complex Arithmetic Accuracy
12759 The version of the @code{Compose_From_Polar} function without a
12760 @code{Cycle} parameter should not be implemented by calling the
12761 corresponding version with a @code{Cycle} parameter of
12762 @code{2.0*Numerics.Pi}, since this will not provide the required
12763 accuracy in some portions of the domain.
12767 @cindex Sequential elaboration policy
12768 @unnumberedsec H.6(15/2): Pragma Partition_Elaboration_Policy
12772 If the partition elaboration policy is @code{Sequential} and the
12773 Environment task becomes permanently blocked during elaboration then the
12774 partition is deadlocked and it is recommended that the partition be
12775 immediately terminated.
12779 @c -----------------------------------------
12780 @node Implementation Defined Characteristics
12781 @chapter Implementation Defined Characteristics
12784 In addition to the implementation dependent pragmas and attributes, and the
12785 implementation advice, there are a number of other Ada features that are
12786 potentially implementation dependent and are designated as
12787 implementation-defined. These are mentioned throughout the Ada Reference
12788 Manual, and are summarized in Annex M@.
12790 A requirement for conforming Ada compilers is that they provide
12791 documentation describing how the implementation deals with each of these
12792 issues. In this chapter you will find each point in Annex M listed,
12793 followed by a description of how GNAT
12794 handles the implementation dependence.
12796 You can use this chapter as a guide to minimizing implementation
12797 dependent features in your programs if portability to other compilers
12798 and other operating systems is an important consideration. The numbers
12799 in each entry below correspond to the paragraph numbers in the Ada
12808 Whether or not each recommendation given in Implementation
12809 Advice is followed. See 1.1.2(37).
12812 @xref{Implementation Advice}.
12819 Capacity limitations of the implementation. See 1.1.3(3).
12822 The complexity of programs that can be processed is limited only by the
12823 total amount of available virtual memory, and disk space for the
12824 generated object files.
12831 Variations from the standard that are impractical to avoid
12832 given the implementation's execution environment. See 1.1.3(6).
12835 There are no variations from the standard.
12842 Which @code{code_statement}s cause external
12843 interactions. See 1.1.3(10).
12846 Any @code{code_statement} can potentially cause external interactions.
12852 The coded representation for the text of an Ada
12853 program. See 2.1(4).
12856 See separate section on source representation.
12863 The control functions allowed in comments. See 2.1(14).
12866 See separate section on source representation.
12872 The representation for an end of line. See 2.2(2).
12875 See separate section on source representation.
12881 Maximum supported line length and lexical element
12882 length. See 2.2(15).
12885 The maximum line length is 255 characters and the maximum length of
12886 a lexical element is also 255 characters. This is the default setting
12887 if not overridden by the use of compiler switch @option{-gnaty} (which
12888 sets the maximum to 79) or @option{-gnatyMnn} which allows the maximum
12889 line length to be specified to be any value up to 32767. The maximum
12890 length of a lexical element is the same as the maximum line length.
12896 Implementation defined pragmas. See 2.8(14).
12900 @xref{Implementation Defined Pragmas}.
12906 Effect of pragma @code{Optimize}. See 2.8(27).
12909 Pragma @code{Optimize}, if given with a @code{Time} or @code{Space}
12910 parameter, checks that the optimization flag is set, and aborts if it is
12917 The sequence of characters of the value returned by
12918 @code{@var{S}'Image} when some of the graphic characters of
12919 @code{@var{S}'Wide_Image} are not defined in @code{Character}. See
12923 The sequence of characters is as defined by the wide character encoding
12924 method used for the source. See section on source representation for
12931 The predefined integer types declared in
12932 @code{Standard}. See 3.5.4(25).
12936 @item Short_Short_Integer
12938 @item Short_Integer
12939 (Short) 16 bit signed
12943 64 bit signed (on most 64 bit targets, depending on the C definition of long).
12944 32 bit signed (all other targets)
12945 @item Long_Long_Integer
12953 Any nonstandard integer types and the operators defined
12954 for them. See 3.5.4(26).
12957 There are no nonstandard integer types.
12963 Any nonstandard real types and the operators defined for
12964 them. See 3.5.6(8).
12967 There are no nonstandard real types.
12973 What combinations of requested decimal precision and range
12974 are supported for floating point types. See 3.5.7(7).
12977 The precision and range is as defined by the IEEE standard.
12983 The predefined floating point types declared in
12984 @code{Standard}. See 3.5.7(16).
12991 (Short) 32 bit IEEE short
12994 @item Long_Long_Float
12995 64 bit IEEE long (80 bit IEEE long on x86 processors)
13002 The small of an ordinary fixed point type. See 3.5.9(8).
13005 @code{Fine_Delta} is 2**(@minus{}63)
13011 What combinations of small, range, and digits are
13012 supported for fixed point types. See 3.5.9(10).
13015 Any combinations are permitted that do not result in a small less than
13016 @code{Fine_Delta} and do not result in a mantissa larger than 63 bits.
13017 If the mantissa is larger than 53 bits on machines where Long_Long_Float
13018 is 64 bits (true of all architectures except ia32), then the output from
13019 Text_IO is accurate to only 53 bits, rather than the full mantissa. This
13020 is because floating-point conversions are used to convert fixed point.
13026 The result of @code{Tags.Expanded_Name} for types declared
13027 within an unnamed @code{block_statement}. See 3.9(10).
13030 Block numbers of the form @code{B@var{nnn}}, where @var{nnn} is a
13031 decimal integer are allocated.
13037 Implementation-defined attributes. See 4.1.4(12).
13040 @xref{Implementation Defined Attributes}.
13046 Any implementation-defined time types. See 9.6(6).
13049 There are no implementation-defined time types.
13055 The time base associated with relative delays.
13058 See 9.6(20). The time base used is that provided by the C library
13059 function @code{gettimeofday}.
13065 The time base of the type @code{Calendar.Time}. See
13069 The time base used is that provided by the C library function
13070 @code{gettimeofday}.
13076 The time zone used for package @code{Calendar}
13077 operations. See 9.6(24).
13080 The time zone used by package @code{Calendar} is the current system time zone
13081 setting for local time, as accessed by the C library function
13088 Any limit on @code{delay_until_statements} of
13089 @code{select_statements}. See 9.6(29).
13092 There are no such limits.
13098 Whether or not two non-overlapping parts of a composite
13099 object are independently addressable, in the case where packing, record
13100 layout, or @code{Component_Size} is specified for the object. See
13104 Separate components are independently addressable if they do not share
13105 overlapping storage units.
13111 The representation for a compilation. See 10.1(2).
13114 A compilation is represented by a sequence of files presented to the
13115 compiler in a single invocation of the @command{gcc} command.
13121 Any restrictions on compilations that contain multiple
13122 compilation_units. See 10.1(4).
13125 No single file can contain more than one compilation unit, but any
13126 sequence of files can be presented to the compiler as a single
13133 The mechanisms for creating an environment and for adding
13134 and replacing compilation units. See 10.1.4(3).
13137 See separate section on compilation model.
13143 The manner of explicitly assigning library units to a
13144 partition. See 10.2(2).
13147 If a unit contains an Ada main program, then the Ada units for the partition
13148 are determined by recursive application of the rules in the Ada Reference
13149 Manual section 10.2(2-6). In other words, the Ada units will be those that
13150 are needed by the main program, and then this definition of need is applied
13151 recursively to those units, and the partition contains the transitive
13152 closure determined by this relationship. In short, all the necessary units
13153 are included, with no need to explicitly specify the list. If additional
13154 units are required, e.g.@: by foreign language units, then all units must be
13155 mentioned in the context clause of one of the needed Ada units.
13157 If the partition contains no main program, or if the main program is in
13158 a language other than Ada, then GNAT
13159 provides the binder options @option{-z} and @option{-n} respectively, and in
13160 this case a list of units can be explicitly supplied to the binder for
13161 inclusion in the partition (all units needed by these units will also
13162 be included automatically). For full details on the use of these
13163 options, refer to @ref{The GNAT Make Program gnatmake,,, gnat_ugn,
13164 @value{EDITION} User's Guide}.
13170 The implementation-defined means, if any, of specifying
13171 which compilation units are needed by a given compilation unit. See
13175 The units needed by a given compilation unit are as defined in
13176 the Ada Reference Manual section 10.2(2-6). There are no
13177 implementation-defined pragmas or other implementation-defined
13178 means for specifying needed units.
13184 The manner of designating the main subprogram of a
13185 partition. See 10.2(7).
13188 The main program is designated by providing the name of the
13189 corresponding @file{ALI} file as the input parameter to the binder.
13195 The order of elaboration of @code{library_items}. See
13199 The first constraint on ordering is that it meets the requirements of
13200 Chapter 10 of the Ada Reference Manual. This still leaves some
13201 implementation dependent choices, which are resolved by first
13202 elaborating bodies as early as possible (i.e., in preference to specs
13203 where there is a choice), and second by evaluating the immediate with
13204 clauses of a unit to determine the probably best choice, and
13205 third by elaborating in alphabetical order of unit names
13206 where a choice still remains.
13212 Parameter passing and function return for the main
13213 subprogram. See 10.2(21).
13216 The main program has no parameters. It may be a procedure, or a function
13217 returning an integer type. In the latter case, the returned integer
13218 value is the return code of the program (overriding any value that
13219 may have been set by a call to @code{Ada.Command_Line.Set_Exit_Status}).
13225 The mechanisms for building and running partitions. See
13229 GNAT itself supports programs with only a single partition. The GNATDIST
13230 tool provided with the GLADE package (which also includes an implementation
13231 of the PCS) provides a completely flexible method for building and running
13232 programs consisting of multiple partitions. See the separate GLADE manual
13239 The details of program execution, including program
13240 termination. See 10.2(25).
13243 See separate section on compilation model.
13249 The semantics of any non-active partitions supported by the
13250 implementation. See 10.2(28).
13253 Passive partitions are supported on targets where shared memory is
13254 provided by the operating system. See the GLADE reference manual for
13261 The information returned by @code{Exception_Message}. See
13265 Exception message returns the null string unless a specific message has
13266 been passed by the program.
13272 The result of @code{Exceptions.Exception_Name} for types
13273 declared within an unnamed @code{block_statement}. See 11.4.1(12).
13276 Blocks have implementation defined names of the form @code{B@var{nnn}}
13277 where @var{nnn} is an integer.
13283 The information returned by
13284 @code{Exception_Information}. See 11.4.1(13).
13287 @code{Exception_Information} returns a string in the following format:
13290 @emph{Exception_Name:} nnnnn
13291 @emph{Message:} mmmmm
13293 @emph{Load address:} 0xhhhh
13294 @emph{Call stack traceback locations:}
13295 0xhhhh 0xhhhh 0xhhhh ... 0xhhh
13303 @code{nnnn} is the fully qualified name of the exception in all upper
13304 case letters. This line is always present.
13307 @code{mmmm} is the message (this line present only if message is non-null)
13310 @code{ppp} is the Process Id value as a decimal integer (this line is
13311 present only if the Process Id is nonzero). Currently we are
13312 not making use of this field.
13315 The Load address line, the Call stack traceback locations line and the
13316 following values are present only if at least one traceback location was
13317 recorded. The Load address indicates the address at which the main executable
13318 was loaded; this line may not be present if operating system hasn't relocated
13319 the main executable. The values are given in C style format, with lower case
13320 letters for a-f, and only as many digits present as are necessary.
13324 The line terminator sequence at the end of each line, including
13325 the last line is a single @code{LF} character (@code{16#0A#}).
13331 Implementation-defined check names. See 11.5(27).
13334 The implementation defined check name Alignment_Check controls checking of
13335 address clause values for proper alignment (that is, the address supplied
13336 must be consistent with the alignment of the type).
13338 The implementation defined check name Predicate_Check controls whether
13339 predicate checks are generated.
13341 The implementation defined check name Validity_Check controls whether
13342 validity checks are generated.
13344 In addition, a user program can add implementation-defined check names
13345 by means of the pragma Check_Name.
13351 The interpretation of each aspect of representation. See
13355 See separate section on data representations.
13361 Any restrictions placed upon representation items. See
13365 See separate section on data representations.
13371 The meaning of @code{Size} for indefinite subtypes. See
13375 Size for an indefinite subtype is the maximum possible size, except that
13376 for the case of a subprogram parameter, the size of the parameter object
13377 is the actual size.
13383 The default external representation for a type tag. See
13387 The default external representation for a type tag is the fully expanded
13388 name of the type in upper case letters.
13394 What determines whether a compilation unit is the same in
13395 two different partitions. See 13.3(76).
13398 A compilation unit is the same in two different partitions if and only
13399 if it derives from the same source file.
13405 Implementation-defined components. See 13.5.1(15).
13408 The only implementation defined component is the tag for a tagged type,
13409 which contains a pointer to the dispatching table.
13415 If @code{Word_Size} = @code{Storage_Unit}, the default bit
13416 ordering. See 13.5.3(5).
13419 @code{Word_Size} (32) is not the same as @code{Storage_Unit} (8) for this
13420 implementation, so no non-default bit ordering is supported. The default
13421 bit ordering corresponds to the natural endianness of the target architecture.
13427 The contents of the visible part of package @code{System}
13428 and its language-defined children. See 13.7(2).
13431 See the definition of these packages in files @file{system.ads} and
13432 @file{s-stoele.ads}. Note that two declarations are added to package
13435 @smallexample @c ada
13436 Max_Priority : constant Positive :=
13438 Max_Interrupt_Priority : constant Positive :=
13439 Interrupt_Priority'Last;
13446 The contents of the visible part of package
13447 @code{System.Machine_Code}, and the meaning of
13448 @code{code_statements}. See 13.8(7).
13451 See the definition and documentation in file @file{s-maccod.ads}.
13457 The effect of unchecked conversion. See 13.9(11).
13460 Unchecked conversion between types of the same size
13461 results in an uninterpreted transmission of the bits from one type
13462 to the other. If the types are of unequal sizes, then in the case of
13463 discrete types, a shorter source is first zero or sign extended as
13464 necessary, and a shorter target is simply truncated on the left.
13465 For all non-discrete types, the source is first copied if necessary
13466 to ensure that the alignment requirements of the target are met, then
13467 a pointer is constructed to the source value, and the result is obtained
13468 by dereferencing this pointer after converting it to be a pointer to the
13469 target type. Unchecked conversions where the target subtype is an
13470 unconstrained array are not permitted. If the target alignment is
13471 greater than the source alignment, then a copy of the result is
13472 made with appropriate alignment
13478 The semantics of operations on invalid representations.
13482 For assignments and other operations where the use of invalid values cannot
13483 result in erroneous behavior, the compiler ignores the possibility of invalid
13484 values. An exception is raised at the point where an invalid value would
13485 result in erroneous behavior. For example executing:
13487 @smallexample @c ada
13488 procedure invalidvals is
13490 Y : Natural range 1 .. 10;
13491 for Y'Address use X'Address;
13492 Z : Natural range 1 .. 10;
13493 A : array (Natural range 1 .. 10) of Integer;
13495 Z := Y; -- no exception
13496 A (Z) := 3; -- exception raised;
13501 As indicated, an exception is raised on the array assignment, but not
13502 on the simple assignment of the invalid negative value from Y to Z.
13508 The manner of choosing a storage pool for an access type
13509 when @code{Storage_Pool} is not specified for the type. See 13.11(17).
13512 There are 3 different standard pools used by the compiler when
13513 @code{Storage_Pool} is not specified depending whether the type is local
13514 to a subprogram or defined at the library level and whether
13515 @code{Storage_Size}is specified or not. See documentation in the runtime
13516 library units @code{System.Pool_Global}, @code{System.Pool_Size} and
13517 @code{System.Pool_Local} in files @file{s-poosiz.ads},
13518 @file{s-pooglo.ads} and @file{s-pooloc.ads} for full details on the
13519 default pools used.
13525 Whether or not the implementation provides user-accessible
13526 names for the standard pool type(s). See 13.11(17).
13530 See documentation in the sources of the run time mentioned in the previous
13531 paragraph. All these pools are accessible by means of @code{with}'ing
13538 The meaning of @code{Storage_Size}. See 13.11(18).
13541 @code{Storage_Size} is measured in storage units, and refers to the
13542 total space available for an access type collection, or to the primary
13543 stack space for a task.
13549 Implementation-defined aspects of storage pools. See
13553 See documentation in the sources of the run time mentioned in the
13554 paragraph about standard storage pools above
13555 for details on GNAT-defined aspects of storage pools.
13561 The set of restrictions allowed in a pragma
13562 @code{Restrictions}. See 13.12(7).
13565 @xref{Standard and Implementation Defined Restrictions}.
13571 The consequences of violating limitations on
13572 @code{Restrictions} pragmas. See 13.12(9).
13575 Restrictions that can be checked at compile time result in illegalities
13576 if violated. Currently there are no other consequences of violating
13583 The representation used by the @code{Read} and
13584 @code{Write} attributes of elementary types in terms of stream
13585 elements. See 13.13.2(9).
13588 The representation is the in-memory representation of the base type of
13589 the type, using the number of bits corresponding to the
13590 @code{@var{type}'Size} value, and the natural ordering of the machine.
13596 The names and characteristics of the numeric subtypes
13597 declared in the visible part of package @code{Standard}. See A.1(3).
13600 See items describing the integer and floating-point types supported.
13606 The string returned by @code{Character_Set_Version}.
13610 @code{Ada.Wide_Characters.Handling.Character_Set_Version} returns
13611 the string "Unicode 4.0", referring to version 4.0 of the
13612 Unicode specification.
13618 The accuracy actually achieved by the elementary
13619 functions. See A.5.1(1).
13622 The elementary functions correspond to the functions available in the C
13623 library. Only fast math mode is implemented.
13629 The sign of a zero result from some of the operators or
13630 functions in @code{Numerics.Generic_Elementary_Functions}, when
13631 @code{Float_Type'Signed_Zeros} is @code{True}. See A.5.1(46).
13634 The sign of zeroes follows the requirements of the IEEE 754 standard on
13642 @code{Numerics.Float_Random.Max_Image_Width}. See A.5.2(27).
13645 Maximum image width is 6864, see library file @file{s-rannum.ads}.
13652 @code{Numerics.Discrete_Random.Max_Image_Width}. See A.5.2(27).
13655 Maximum image width is 6864, see library file @file{s-rannum.ads}.
13661 The algorithms for random number generation. See
13665 The algorithm is the Mersenne Twister, as documented in the source file
13666 @file{s-rannum.adb}. This version of the algorithm has a period of
13673 The string representation of a random number generator's
13674 state. See A.5.2(38).
13677 The value returned by the Image function is the concatenation of
13678 the fixed-width decimal representations of the 624 32-bit integers
13679 of the state vector.
13685 The minimum time interval between calls to the
13686 time-dependent Reset procedure that are guaranteed to initiate different
13687 random number sequences. See A.5.2(45).
13690 The minimum period between reset calls to guarantee distinct series of
13691 random numbers is one microsecond.
13697 The values of the @code{Model_Mantissa},
13698 @code{Model_Emin}, @code{Model_Epsilon}, @code{Model},
13699 @code{Safe_First}, and @code{Safe_Last} attributes, if the Numerics
13700 Annex is not supported. See A.5.3(72).
13703 Run the compiler with @option{-gnatS} to produce a listing of package
13704 @code{Standard}, has the values of all numeric attributes.
13710 Any implementation-defined characteristics of the
13711 input-output packages. See A.7(14).
13714 There are no special implementation defined characteristics for these
13721 The value of @code{Buffer_Size} in @code{Storage_IO}. See
13725 All type representations are contiguous, and the @code{Buffer_Size} is
13726 the value of @code{@var{type}'Size} rounded up to the next storage unit
13733 External files for standard input, standard output, and
13734 standard error See A.10(5).
13737 These files are mapped onto the files provided by the C streams
13738 libraries. See source file @file{i-cstrea.ads} for further details.
13744 The accuracy of the value produced by @code{Put}. See
13748 If more digits are requested in the output than are represented by the
13749 precision of the value, zeroes are output in the corresponding least
13750 significant digit positions.
13756 The meaning of @code{Argument_Count}, @code{Argument}, and
13757 @code{Command_Name}. See A.15(1).
13760 These are mapped onto the @code{argv} and @code{argc} parameters of the
13761 main program in the natural manner.
13767 The interpretation of the @code{Form} parameter in procedure
13768 @code{Create_Directory}. See A.16(56).
13771 The @code{Form} parameter is not used.
13777 The interpretation of the @code{Form} parameter in procedure
13778 @code{Create_Path}. See A.16(60).
13781 The @code{Form} parameter is not used.
13787 The interpretation of the @code{Form} parameter in procedure
13788 @code{Copy_File}. See A.16(68).
13791 The @code{Form} parameter is case-insensitive.
13793 Two fields are recognized in the @code{Form} parameter:
13797 @item preserve=<value>
13804 <value> starts immediately after the character '=' and ends with the
13805 character immediately preceding the next comma (',') or with the last
13806 character of the parameter.
13808 The only possible values for preserve= are:
13812 @item no_attributes
13813 Do not try to preserve any file attributes. This is the default if no
13814 preserve= is found in Form.
13816 @item all_attributes
13817 Try to preserve all file attributes (timestamps, access rights).
13820 Preserve the timestamp of the copied file, but not the other file attributes.
13825 The only possible values for mode= are:
13830 Only do the copy if the destination file does not already exist. If it already
13831 exists, Copy_File fails.
13834 Copy the file in all cases. Overwrite an already existing destination file.
13837 Append the original file to the destination file. If the destination file does
13838 not exist, the destination file is a copy of the source file. When mode=append,
13839 the field preserve=, if it exists, is not taken into account.
13844 If the Form parameter includes one or both of the fields and the value or
13845 values are incorrect, Copy_file fails with Use_Error.
13847 Examples of correct Forms:
13850 Form => "preserve=no_attributes,mode=overwrite" (the default)
13851 Form => "mode=append"
13852 Form => "mode=copy, preserve=all_attributes"
13856 Examples of incorrect Forms
13859 Form => "preserve=junk"
13860 Form => "mode=internal, preserve=timestamps"
13867 The interpretation of the @code{Pattern} parameter, when not the null string,
13868 in the @code{Start_Search} and @code{Search} procedures.
13869 See A.16(104) and A.16(112).
13872 When the @code{Pattern} parameter is not the null string, it is interpreted
13873 according to the syntax of regular expressions as defined in the
13874 @code{GNAT.Regexp} package.
13875 @xref{GNAT.Regexp (g-regexp.ads)}.
13881 Implementation-defined convention names. See B.1(11).
13884 The following convention names are supported
13889 @item Ada_Pass_By_Copy
13890 Allowed for any types except by-reference types such as limited
13891 records. Compatible with convention Ada, but causes any parameters
13892 with this convention to be passed by copy.
13893 @item Ada_Pass_By_Reference
13894 Allowed for any types except by-copy types such as scalars.
13895 Compatible with convention Ada, but causes any parameters
13896 with this convention to be passed by reference.
13900 Synonym for Assembler
13902 Synonym for Assembler
13905 @item C_Pass_By_Copy
13906 Allowed only for record types, like C, but also notes that record
13907 is to be passed by copy rather than reference.
13910 @item C_Plus_Plus (or CPP)
13913 Treated the same as C
13915 Treated the same as C
13919 For support of pragma @code{Import} with convention Intrinsic, see
13920 separate section on Intrinsic Subprograms.
13922 Stdcall (used for Windows implementations only). This convention correspond
13923 to the WINAPI (previously called Pascal convention) C/C++ convention under
13924 Windows. A routine with this convention cleans the stack before
13925 exit. This pragma cannot be applied to a dispatching call.
13927 Synonym for Stdcall
13929 Synonym for Stdcall
13931 Stubbed is a special convention used to indicate that the body of the
13932 subprogram will be entirely ignored. Any call to the subprogram
13933 is converted into a raise of the @code{Program_Error} exception. If a
13934 pragma @code{Import} specifies convention @code{stubbed} then no body need
13935 be present at all. This convention is useful during development for the
13936 inclusion of subprograms whose body has not yet been written.
13940 In addition, all otherwise unrecognized convention names are also
13941 treated as being synonymous with convention C@. In all implementations
13942 except for VMS, use of such other names results in a warning. In VMS
13943 implementations, these names are accepted silently.
13949 The meaning of link names. See B.1(36).
13952 Link names are the actual names used by the linker.
13958 The manner of choosing link names when neither the link
13959 name nor the address of an imported or exported entity is specified. See
13963 The default linker name is that which would be assigned by the relevant
13964 external language, interpreting the Ada name as being in all lower case
13971 The effect of pragma @code{Linker_Options}. See B.1(37).
13974 The string passed to @code{Linker_Options} is presented uninterpreted as
13975 an argument to the link command, unless it contains ASCII.NUL characters.
13976 NUL characters if they appear act as argument separators, so for example
13978 @smallexample @c ada
13979 pragma Linker_Options ("-labc" & ASCII.NUL & "-ldef");
13983 causes two separate arguments @code{-labc} and @code{-ldef} to be passed to the
13984 linker. The order of linker options is preserved for a given unit. The final
13985 list of options passed to the linker is in reverse order of the elaboration
13986 order. For example, linker options for a body always appear before the options
13987 from the corresponding package spec.
13993 The contents of the visible part of package
13994 @code{Interfaces} and its language-defined descendants. See B.2(1).
13997 See files with prefix @file{i-} in the distributed library.
14003 Implementation-defined children of package
14004 @code{Interfaces}. The contents of the visible part of package
14005 @code{Interfaces}. See B.2(11).
14008 See files with prefix @file{i-} in the distributed library.
14014 The types @code{Floating}, @code{Long_Floating},
14015 @code{Binary}, @code{Long_Binary}, @code{Decimal_ Element}, and
14016 @code{COBOL_Character}; and the initialization of the variables
14017 @code{Ada_To_COBOL} and @code{COBOL_To_Ada}, in
14018 @code{Interfaces.COBOL}. See B.4(50).
14024 @item Long_Floating
14025 (Floating) Long_Float
14030 @item Decimal_Element
14032 @item COBOL_Character
14037 For initialization, see the file @file{i-cobol.ads} in the distributed library.
14043 Support for access to machine instructions. See C.1(1).
14046 See documentation in file @file{s-maccod.ads} in the distributed library.
14052 Implementation-defined aspects of access to machine
14053 operations. See C.1(9).
14056 See documentation in file @file{s-maccod.ads} in the distributed library.
14062 Implementation-defined aspects of interrupts. See C.3(2).
14065 Interrupts are mapped to signals or conditions as appropriate. See
14067 @code{Ada.Interrupt_Names} in source file @file{a-intnam.ads} for details
14068 on the interrupts supported on a particular target.
14074 Implementation-defined aspects of pre-elaboration. See
14078 GNAT does not permit a partition to be restarted without reloading,
14079 except under control of the debugger.
14085 The semantics of pragma @code{Discard_Names}. See C.5(7).
14088 Pragma @code{Discard_Names} causes names of enumeration literals to
14089 be suppressed. In the presence of this pragma, the Image attribute
14090 provides the image of the Pos of the literal, and Value accepts
14097 The result of the @code{Task_Identification.Image}
14098 attribute. See C.7.1(7).
14101 The result of this attribute is a string that identifies
14102 the object or component that denotes a given task. If a variable @code{Var}
14103 has a task type, the image for this task will have the form @code{Var_@var{XXXXXXXX}},
14105 is the hexadecimal representation of the virtual address of the corresponding
14106 task control block. If the variable is an array of tasks, the image of each
14107 task will have the form of an indexed component indicating the position of a
14108 given task in the array, e.g.@: @code{Group(5)_@var{XXXXXXX}}. If the task is a
14109 component of a record, the image of the task will have the form of a selected
14110 component. These rules are fully recursive, so that the image of a task that
14111 is a subcomponent of a composite object corresponds to the expression that
14112 designates this task.
14114 If a task is created by an allocator, its image depends on the context. If the
14115 allocator is part of an object declaration, the rules described above are used
14116 to construct its image, and this image is not affected by subsequent
14117 assignments. If the allocator appears within an expression, the image
14118 includes only the name of the task type.
14120 If the configuration pragma Discard_Names is present, or if the restriction
14121 No_Implicit_Heap_Allocation is in effect, the image reduces to
14122 the numeric suffix, that is to say the hexadecimal representation of the
14123 virtual address of the control block of the task.
14128 The value of @code{Current_Task} when in a protected entry
14129 or interrupt handler. See C.7.1(17).
14132 Protected entries or interrupt handlers can be executed by any
14133 convenient thread, so the value of @code{Current_Task} is undefined.
14139 The effect of calling @code{Current_Task} from an entry
14140 body or interrupt handler. See C.7.1(19).
14143 The effect of calling @code{Current_Task} from an entry body or
14144 interrupt handler is to return the identification of the task currently
14145 executing the code.
14151 Implementation-defined aspects of
14152 @code{Task_Attributes}. See C.7.2(19).
14155 There are no implementation-defined aspects of @code{Task_Attributes}.
14161 Values of all @code{Metrics}. See D(2).
14164 The metrics information for GNAT depends on the performance of the
14165 underlying operating system. The sources of the run-time for tasking
14166 implementation, together with the output from @option{-gnatG} can be
14167 used to determine the exact sequence of operating systems calls made
14168 to implement various tasking constructs. Together with appropriate
14169 information on the performance of the underlying operating system,
14170 on the exact target in use, this information can be used to determine
14171 the required metrics.
14177 The declarations of @code{Any_Priority} and
14178 @code{Priority}. See D.1(11).
14181 See declarations in file @file{system.ads}.
14187 Implementation-defined execution resources. See D.1(15).
14190 There are no implementation-defined execution resources.
14196 Whether, on a multiprocessor, a task that is waiting for
14197 access to a protected object keeps its processor busy. See D.2.1(3).
14200 On a multi-processor, a task that is waiting for access to a protected
14201 object does not keep its processor busy.
14207 The affect of implementation defined execution resources
14208 on task dispatching. See D.2.1(9).
14211 Tasks map to threads in the threads package used by GNAT@. Where possible
14212 and appropriate, these threads correspond to native threads of the
14213 underlying operating system.
14219 Implementation-defined @code{policy_identifiers} allowed
14220 in a pragma @code{Task_Dispatching_Policy}. See D.2.2(3).
14223 There are no implementation-defined policy-identifiers allowed in this
14230 Implementation-defined aspects of priority inversion. See
14234 Execution of a task cannot be preempted by the implementation processing
14235 of delay expirations for lower priority tasks.
14241 Implementation-defined task dispatching. See D.2.2(18).
14244 The policy is the same as that of the underlying threads implementation.
14250 Implementation-defined @code{policy_identifiers} allowed
14251 in a pragma @code{Locking_Policy}. See D.3(4).
14254 The two implementation defined policies permitted in GNAT are
14255 @code{Inheritance_Locking} and @code{Conccurent_Readers_Locking}. On
14256 targets that support the @code{Inheritance_Locking} policy, locking is
14257 implemented by inheritance, i.e.@: the task owning the lock operates
14258 at a priority equal to the highest priority of any task currently
14259 requesting the lock. On targets that support the
14260 @code{Conccurent_Readers_Locking} policy, locking is implemented with a
14261 read/write lock allowing multiple propected object functions to enter
14268 Default ceiling priorities. See D.3(10).
14271 The ceiling priority of protected objects of the type
14272 @code{System.Interrupt_Priority'Last} as described in the Ada
14273 Reference Manual D.3(10),
14279 The ceiling of any protected object used internally by
14280 the implementation. See D.3(16).
14283 The ceiling priority of internal protected objects is
14284 @code{System.Priority'Last}.
14290 Implementation-defined queuing policies. See D.4(1).
14293 There are no implementation-defined queuing policies.
14299 On a multiprocessor, any conditions that cause the
14300 completion of an aborted construct to be delayed later than what is
14301 specified for a single processor. See D.6(3).
14304 The semantics for abort on a multi-processor is the same as on a single
14305 processor, there are no further delays.
14311 Any operations that implicitly require heap storage
14312 allocation. See D.7(8).
14315 The only operation that implicitly requires heap storage allocation is
14322 What happens when a task terminates in the presence of
14323 pragma @code{No_Task_Termination}. See D.7(15).
14326 Execution is erroneous in that case.
14332 Implementation-defined aspects of pragma
14333 @code{Restrictions}. See D.7(20).
14336 There are no such implementation-defined aspects.
14342 Implementation-defined aspects of package
14343 @code{Real_Time}. See D.8(17).
14346 There are no implementation defined aspects of package @code{Real_Time}.
14352 Implementation-defined aspects of
14353 @code{delay_statements}. See D.9(8).
14356 Any difference greater than one microsecond will cause the task to be
14357 delayed (see D.9(7)).
14363 The upper bound on the duration of interrupt blocking
14364 caused by the implementation. See D.12(5).
14367 The upper bound is determined by the underlying operating system. In
14368 no cases is it more than 10 milliseconds.
14374 The means for creating and executing distributed
14375 programs. See E(5).
14378 The GLADE package provides a utility GNATDIST for creating and executing
14379 distributed programs. See the GLADE reference manual for further details.
14385 Any events that can result in a partition becoming
14386 inaccessible. See E.1(7).
14389 See the GLADE reference manual for full details on such events.
14395 The scheduling policies, treatment of priorities, and
14396 management of shared resources between partitions in certain cases. See
14400 See the GLADE reference manual for full details on these aspects of
14401 multi-partition execution.
14407 Events that cause the version of a compilation unit to
14408 change. See E.3(5).
14411 Editing the source file of a compilation unit, or the source files of
14412 any units on which it is dependent in a significant way cause the version
14413 to change. No other actions cause the version number to change. All changes
14414 are significant except those which affect only layout, capitalization or
14421 Whether the execution of the remote subprogram is
14422 immediately aborted as a result of cancellation. See E.4(13).
14425 See the GLADE reference manual for details on the effect of abort in
14426 a distributed application.
14432 Implementation-defined aspects of the PCS@. See E.5(25).
14435 See the GLADE reference manual for a full description of all implementation
14436 defined aspects of the PCS@.
14442 Implementation-defined interfaces in the PCS@. See
14446 See the GLADE reference manual for a full description of all
14447 implementation defined interfaces.
14453 The values of named numbers in the package
14454 @code{Decimal}. See F.2(7).
14466 @item Max_Decimal_Digits
14474 The value of @code{Max_Picture_Length} in the package
14475 @code{Text_IO.Editing}. See F.3.3(16).
14484 The value of @code{Max_Picture_Length} in the package
14485 @code{Wide_Text_IO.Editing}. See F.3.4(5).
14494 The accuracy actually achieved by the complex elementary
14495 functions and by other complex arithmetic operations. See G.1(1).
14498 Standard library functions are used for the complex arithmetic
14499 operations. Only fast math mode is currently supported.
14505 The sign of a zero result (or a component thereof) from
14506 any operator or function in @code{Numerics.Generic_Complex_Types}, when
14507 @code{Real'Signed_Zeros} is True. See G.1.1(53).
14510 The signs of zero values are as recommended by the relevant
14511 implementation advice.
14517 The sign of a zero result (or a component thereof) from
14518 any operator or function in
14519 @code{Numerics.Generic_Complex_Elementary_Functions}, when
14520 @code{Real'Signed_Zeros} is @code{True}. See G.1.2(45).
14523 The signs of zero values are as recommended by the relevant
14524 implementation advice.
14530 Whether the strict mode or the relaxed mode is the
14531 default. See G.2(2).
14534 The strict mode is the default. There is no separate relaxed mode. GNAT
14535 provides a highly efficient implementation of strict mode.
14541 The result interval in certain cases of fixed-to-float
14542 conversion. See G.2.1(10).
14545 For cases where the result interval is implementation dependent, the
14546 accuracy is that provided by performing all operations in 64-bit IEEE
14547 floating-point format.
14553 The result of a floating point arithmetic operation in
14554 overflow situations, when the @code{Machine_Overflows} attribute of the
14555 result type is @code{False}. See G.2.1(13).
14558 Infinite and NaN values are produced as dictated by the IEEE
14559 floating-point standard.
14561 Note that on machines that are not fully compliant with the IEEE
14562 floating-point standard, such as Alpha, the @option{-mieee} compiler flag
14563 must be used for achieving IEEE conforming behavior (although at the cost
14564 of a significant performance penalty), so infinite and NaN values are
14565 properly generated.
14571 The result interval for division (or exponentiation by a
14572 negative exponent), when the floating point hardware implements division
14573 as multiplication by a reciprocal. See G.2.1(16).
14576 Not relevant, division is IEEE exact.
14582 The definition of close result set, which determines the
14583 accuracy of certain fixed point multiplications and divisions. See
14587 Operations in the close result set are performed using IEEE long format
14588 floating-point arithmetic. The input operands are converted to
14589 floating-point, the operation is done in floating-point, and the result
14590 is converted to the target type.
14596 Conditions on a @code{universal_real} operand of a fixed
14597 point multiplication or division for which the result shall be in the
14598 perfect result set. See G.2.3(22).
14601 The result is only defined to be in the perfect result set if the result
14602 can be computed by a single scaling operation involving a scale factor
14603 representable in 64-bits.
14609 The result of a fixed point arithmetic operation in
14610 overflow situations, when the @code{Machine_Overflows} attribute of the
14611 result type is @code{False}. See G.2.3(27).
14614 Not relevant, @code{Machine_Overflows} is @code{True} for fixed-point
14621 The result of an elementary function reference in
14622 overflow situations, when the @code{Machine_Overflows} attribute of the
14623 result type is @code{False}. See G.2.4(4).
14626 IEEE infinite and Nan values are produced as appropriate.
14632 The value of the angle threshold, within which certain
14633 elementary functions, complex arithmetic operations, and complex
14634 elementary functions yield results conforming to a maximum relative
14635 error bound. See G.2.4(10).
14638 Information on this subject is not yet available.
14644 The accuracy of certain elementary functions for
14645 parameters beyond the angle threshold. See G.2.4(10).
14648 Information on this subject is not yet available.
14654 The result of a complex arithmetic operation or complex
14655 elementary function reference in overflow situations, when the
14656 @code{Machine_Overflows} attribute of the corresponding real type is
14657 @code{False}. See G.2.6(5).
14660 IEEE infinite and Nan values are produced as appropriate.
14666 The accuracy of certain complex arithmetic operations and
14667 certain complex elementary functions for parameters (or components
14668 thereof) beyond the angle threshold. See G.2.6(8).
14671 Information on those subjects is not yet available.
14677 Information regarding bounded errors and erroneous
14678 execution. See H.2(1).
14681 Information on this subject is not yet available.
14687 Implementation-defined aspects of pragma
14688 @code{Inspection_Point}. See H.3.2(8).
14691 Pragma @code{Inspection_Point} ensures that the variable is live and can
14692 be examined by the debugger at the inspection point.
14698 Implementation-defined aspects of pragma
14699 @code{Restrictions}. See H.4(25).
14702 There are no implementation-defined aspects of pragma @code{Restrictions}. The
14703 use of pragma @code{Restrictions [No_Exceptions]} has no effect on the
14704 generated code. Checks must suppressed by use of pragma @code{Suppress}.
14710 Any restrictions on pragma @code{Restrictions}. See
14714 There are no restrictions on pragma @code{Restrictions}.
14719 @c =======================
14720 @node Intrinsic Subprograms
14721 @chapter Intrinsic Subprograms
14722 @cindex Intrinsic Subprograms
14725 * Intrinsic Operators::
14726 * Compilation_Date::
14727 * Compilation_Time::
14728 * Enclosing_Entity::
14729 * Exception_Information::
14730 * Exception_Message::
14734 * Shifts and Rotates::
14735 * Source_Location::
14739 GNAT allows a user application program to write the declaration:
14741 @smallexample @c ada
14742 pragma Import (Intrinsic, name);
14746 providing that the name corresponds to one of the implemented intrinsic
14747 subprograms in GNAT, and that the parameter profile of the referenced
14748 subprogram meets the requirements. This chapter describes the set of
14749 implemented intrinsic subprograms, and the requirements on parameter profiles.
14750 Note that no body is supplied; as with other uses of pragma Import, the
14751 body is supplied elsewhere (in this case by the compiler itself). Note
14752 that any use of this feature is potentially non-portable, since the
14753 Ada standard does not require Ada compilers to implement this feature.
14755 @node Intrinsic Operators
14756 @section Intrinsic Operators
14757 @cindex Intrinsic operator
14760 All the predefined numeric operators in package Standard
14761 in @code{pragma Import (Intrinsic,..)}
14762 declarations. In the binary operator case, the operands must have the same
14763 size. The operand or operands must also be appropriate for
14764 the operator. For example, for addition, the operands must
14765 both be floating-point or both be fixed-point, and the
14766 right operand for @code{"**"} must have a root type of
14767 @code{Standard.Integer'Base}.
14768 You can use an intrinsic operator declaration as in the following example:
14770 @smallexample @c ada
14771 type Int1 is new Integer;
14772 type Int2 is new Integer;
14774 function "+" (X1 : Int1; X2 : Int2) return Int1;
14775 function "+" (X1 : Int1; X2 : Int2) return Int2;
14776 pragma Import (Intrinsic, "+");
14780 This declaration would permit ``mixed mode'' arithmetic on items
14781 of the differing types @code{Int1} and @code{Int2}.
14782 It is also possible to specify such operators for private types, if the
14783 full views are appropriate arithmetic types.
14785 @node Compilation_Date
14786 @section Compilation_Date
14787 @cindex Compilation_Date
14789 This intrinsic subprogram is used in the implementation of the
14790 library package @code{GNAT.Source_Info}. The only useful use of the
14791 intrinsic import in this case is the one in this unit, so an
14792 application program should simply call the function
14793 @code{GNAT.Source_Info.Compilation_Date} to obtain the date of
14794 the current compilation (in local time format MMM DD YYYY).
14796 @node Compilation_Time
14797 @section Compilation_Time
14798 @cindex Compilation_Time
14800 This intrinsic subprogram is used in the implementation of the
14801 library package @code{GNAT.Source_Info}. The only useful use of the
14802 intrinsic import in this case is the one in this unit, so an
14803 application program should simply call the function
14804 @code{GNAT.Source_Info.Compilation_Time} to obtain the time of
14805 the current compilation (in local time format HH:MM:SS).
14807 @node Enclosing_Entity
14808 @section Enclosing_Entity
14809 @cindex Enclosing_Entity
14811 This intrinsic subprogram is used in the implementation of the
14812 library package @code{GNAT.Source_Info}. The only useful use of the
14813 intrinsic import in this case is the one in this unit, so an
14814 application program should simply call the function
14815 @code{GNAT.Source_Info.Enclosing_Entity} to obtain the name of
14816 the current subprogram, package, task, entry, or protected subprogram.
14818 @node Exception_Information
14819 @section Exception_Information
14820 @cindex Exception_Information'
14822 This intrinsic subprogram is used in the implementation of the
14823 library package @code{GNAT.Current_Exception}. The only useful
14824 use of the intrinsic import in this case is the one in this unit,
14825 so an application program should simply call the function
14826 @code{GNAT.Current_Exception.Exception_Information} to obtain
14827 the exception information associated with the current exception.
14829 @node Exception_Message
14830 @section Exception_Message
14831 @cindex Exception_Message
14833 This intrinsic subprogram is used in the implementation of the
14834 library package @code{GNAT.Current_Exception}. The only useful
14835 use of the intrinsic import in this case is the one in this unit,
14836 so an application program should simply call the function
14837 @code{GNAT.Current_Exception.Exception_Message} to obtain
14838 the message associated with the current exception.
14840 @node Exception_Name
14841 @section Exception_Name
14842 @cindex Exception_Name
14844 This intrinsic subprogram is used in the implementation of the
14845 library package @code{GNAT.Current_Exception}. The only useful
14846 use of the intrinsic import in this case is the one in this unit,
14847 so an application program should simply call the function
14848 @code{GNAT.Current_Exception.Exception_Name} to obtain
14849 the name of the current exception.
14855 This intrinsic subprogram is used in the implementation of the
14856 library package @code{GNAT.Source_Info}. The only useful use of the
14857 intrinsic import in this case is the one in this unit, so an
14858 application program should simply call the function
14859 @code{GNAT.Source_Info.File} to obtain the name of the current
14866 This intrinsic subprogram is used in the implementation of the
14867 library package @code{GNAT.Source_Info}. The only useful use of the
14868 intrinsic import in this case is the one in this unit, so an
14869 application program should simply call the function
14870 @code{GNAT.Source_Info.Line} to obtain the number of the current
14873 @node Shifts and Rotates
14874 @section Shifts and Rotates
14876 @cindex Shift_Right
14877 @cindex Shift_Right_Arithmetic
14878 @cindex Rotate_Left
14879 @cindex Rotate_Right
14881 In standard Ada, the shift and rotate functions are available only
14882 for the predefined modular types in package @code{Interfaces}. However, in
14883 GNAT it is possible to define these functions for any integer
14884 type (signed or modular), as in this example:
14886 @smallexample @c ada
14887 function Shift_Left
14889 Amount : Natural) return T;
14893 The function name must be one of
14894 Shift_Left, Shift_Right, Shift_Right_Arithmetic, Rotate_Left, or
14895 Rotate_Right. T must be an integer type. T'Size must be
14896 8, 16, 32 or 64 bits; if T is modular, the modulus
14897 must be 2**8, 2**16, 2**32 or 2**64.
14898 The result type must be the same as the type of @code{Value}.
14899 The shift amount must be Natural.
14900 The formal parameter names can be anything.
14902 A more convenient way of providing these shift operators is to use
14903 the Provide_Shift_Operators pragma, which provides the function declarations
14904 and corresponding pragma Import's for all five shift functions.
14906 @node Source_Location
14907 @section Source_Location
14908 @cindex Source_Location
14910 This intrinsic subprogram is used in the implementation of the
14911 library routine @code{GNAT.Source_Info}. The only useful use of the
14912 intrinsic import in this case is the one in this unit, so an
14913 application program should simply call the function
14914 @code{GNAT.Source_Info.Source_Location} to obtain the current
14915 source file location.
14917 @node Representation Clauses and Pragmas
14918 @chapter Representation Clauses and Pragmas
14919 @cindex Representation Clauses
14922 * Alignment Clauses::
14924 * Storage_Size Clauses::
14925 * Size of Variant Record Objects::
14926 * Biased Representation ::
14927 * Value_Size and Object_Size Clauses::
14928 * Component_Size Clauses::
14929 * Bit_Order Clauses::
14930 * Effect of Bit_Order on Byte Ordering::
14931 * Pragma Pack for Arrays::
14932 * Pragma Pack for Records::
14933 * Record Representation Clauses::
14934 * Handling of Records with Holes::
14935 * Enumeration Clauses::
14936 * Address Clauses::
14937 * Use of Address Clauses for Memory-Mapped I/O::
14938 * Effect of Convention on Representation::
14939 * Conventions and Anonymous Access Types::
14940 * Determining the Representations chosen by GNAT::
14944 @cindex Representation Clause
14945 @cindex Representation Pragma
14946 @cindex Pragma, representation
14947 This section describes the representation clauses accepted by GNAT, and
14948 their effect on the representation of corresponding data objects.
14950 GNAT fully implements Annex C (Systems Programming). This means that all
14951 the implementation advice sections in chapter 13 are fully implemented.
14952 However, these sections only require a minimal level of support for
14953 representation clauses. GNAT provides much more extensive capabilities,
14954 and this section describes the additional capabilities provided.
14956 @node Alignment Clauses
14957 @section Alignment Clauses
14958 @cindex Alignment Clause
14961 GNAT requires that all alignment clauses specify a power of 2, and all
14962 default alignments are always a power of 2. The default alignment
14963 values are as follows:
14966 @item @emph{Primitive Types}.
14967 For primitive types, the alignment is the minimum of the actual size of
14968 objects of the type divided by @code{Storage_Unit},
14969 and the maximum alignment supported by the target.
14970 (This maximum alignment is given by the GNAT-specific attribute
14971 @code{Standard'Maximum_Alignment}; see @ref{Attribute Maximum_Alignment}.)
14972 @cindex @code{Maximum_Alignment} attribute
14973 For example, for type @code{Long_Float}, the object size is 8 bytes, and the
14974 default alignment will be 8 on any target that supports alignments
14975 this large, but on some targets, the maximum alignment may be smaller
14976 than 8, in which case objects of type @code{Long_Float} will be maximally
14979 @item @emph{Arrays}.
14980 For arrays, the alignment is equal to the alignment of the component type
14981 for the normal case where no packing or component size is given. If the
14982 array is packed, and the packing is effective (see separate section on
14983 packed arrays), then the alignment will be one for long packed arrays,
14984 or arrays whose length is not known at compile time. For short packed
14985 arrays, which are handled internally as modular types, the alignment
14986 will be as described for primitive types, e.g.@: a packed array of length
14987 31 bits will have an object size of four bytes, and an alignment of 4.
14989 @item @emph{Records}.
14990 For the normal non-packed case, the alignment of a record is equal to
14991 the maximum alignment of any of its components. For tagged records, this
14992 includes the implicit access type used for the tag. If a pragma @code{Pack}
14993 is used and all components are packable (see separate section on pragma
14994 @code{Pack}), then the resulting alignment is 1, unless the layout of the
14995 record makes it profitable to increase it.
14997 A special case is when:
15000 the size of the record is given explicitly, or a
15001 full record representation clause is given, and
15003 the size of the record is 2, 4, or 8 bytes.
15006 In this case, an alignment is chosen to match the
15007 size of the record. For example, if we have:
15009 @smallexample @c ada
15010 type Small is record
15013 for Small'Size use 16;
15017 then the default alignment of the record type @code{Small} is 2, not 1. This
15018 leads to more efficient code when the record is treated as a unit, and also
15019 allows the type to specified as @code{Atomic} on architectures requiring
15025 An alignment clause may specify a larger alignment than the default value
15026 up to some maximum value dependent on the target (obtainable by using the
15027 attribute reference @code{Standard'Maximum_Alignment}). It may also specify
15028 a smaller alignment than the default value for enumeration, integer and
15029 fixed point types, as well as for record types, for example
15031 @smallexample @c ada
15036 for V'alignment use 1;
15040 @cindex Alignment, default
15041 The default alignment for the type @code{V} is 4, as a result of the
15042 Integer field in the record, but it is permissible, as shown, to
15043 override the default alignment of the record with a smaller value.
15045 @cindex Alignment, subtypes
15046 Note that according to the Ada standard, an alignment clause applies only
15047 to the first named subtype. If additional subtypes are declared, then the
15048 compiler is allowed to choose any alignment it likes, and there is no way
15049 to control this choice. Consider:
15051 @smallexample @c ada
15052 type R is range 1 .. 10_000;
15053 for R'Alignment use 1;
15054 subtype RS is R range 1 .. 1000;
15058 The alignment clause specifies an alignment of 1 for the first named subtype
15059 @code{R} but this does not necessarily apply to @code{RS}. When writing
15060 portable Ada code, you should avoid writing code that explicitly or
15061 implicitly relies on the alignment of such subtypes.
15063 For the GNAT compiler, if an explicit alignment clause is given, this
15064 value is also used for any subsequent subtypes. So for GNAT, in the
15065 above example, you can count on the alignment of @code{RS} being 1. But this
15066 assumption is non-portable, and other compilers may choose different
15067 alignments for the subtype @code{RS}.
15070 @section Size Clauses
15071 @cindex Size Clause
15074 The default size for a type @code{T} is obtainable through the
15075 language-defined attribute @code{T'Size} and also through the
15076 equivalent GNAT-defined attribute @code{T'Value_Size}.
15077 For objects of type @code{T}, GNAT will generally increase the type size
15078 so that the object size (obtainable through the GNAT-defined attribute
15079 @code{T'Object_Size})
15080 is a multiple of @code{T'Alignment * Storage_Unit}.
15083 @smallexample @c ada
15084 type Smallint is range 1 .. 6;
15093 In this example, @code{Smallint'Size} = @code{Smallint'Value_Size} = 3,
15094 as specified by the RM rules,
15095 but objects of this type will have a size of 8
15096 (@code{Smallint'Object_Size} = 8),
15097 since objects by default occupy an integral number
15098 of storage units. On some targets, notably older
15099 versions of the Digital Alpha, the size of stand
15100 alone objects of this type may be 32, reflecting
15101 the inability of the hardware to do byte load/stores.
15103 Similarly, the size of type @code{Rec} is 40 bits
15104 (@code{Rec'Size} = @code{Rec'Value_Size} = 40), but
15105 the alignment is 4, so objects of this type will have
15106 their size increased to 64 bits so that it is a multiple
15107 of the alignment (in bits). This decision is
15108 in accordance with the specific Implementation Advice in RM 13.3(43):
15111 A @code{Size} clause should be supported for an object if the specified
15112 @code{Size} is at least as large as its subtype's @code{Size}, and corresponds
15113 to a size in storage elements that is a multiple of the object's
15114 @code{Alignment} (if the @code{Alignment} is nonzero).
15118 An explicit size clause may be used to override the default size by
15119 increasing it. For example, if we have:
15121 @smallexample @c ada
15122 type My_Boolean is new Boolean;
15123 for My_Boolean'Size use 32;
15127 then values of this type will always be 32 bits long. In the case of
15128 discrete types, the size can be increased up to 64 bits, with the effect
15129 that the entire specified field is used to hold the value, sign- or
15130 zero-extended as appropriate. If more than 64 bits is specified, then
15131 padding space is allocated after the value, and a warning is issued that
15132 there are unused bits.
15134 Similarly the size of records and arrays may be increased, and the effect
15135 is to add padding bits after the value. This also causes a warning message
15138 The largest Size value permitted in GNAT is 2**31@minus{}1. Since this is a
15139 Size in bits, this corresponds to an object of size 256 megabytes (minus
15140 one). This limitation is true on all targets. The reason for this
15141 limitation is that it improves the quality of the code in many cases
15142 if it is known that a Size value can be accommodated in an object of
15145 @node Storage_Size Clauses
15146 @section Storage_Size Clauses
15147 @cindex Storage_Size Clause
15150 For tasks, the @code{Storage_Size} clause specifies the amount of space
15151 to be allocated for the task stack. This cannot be extended, and if the
15152 stack is exhausted, then @code{Storage_Error} will be raised (if stack
15153 checking is enabled). Use a @code{Storage_Size} attribute definition clause,
15154 or a @code{Storage_Size} pragma in the task definition to set the
15155 appropriate required size. A useful technique is to include in every
15156 task definition a pragma of the form:
15158 @smallexample @c ada
15159 pragma Storage_Size (Default_Stack_Size);
15163 Then @code{Default_Stack_Size} can be defined in a global package, and
15164 modified as required. Any tasks requiring stack sizes different from the
15165 default can have an appropriate alternative reference in the pragma.
15167 You can also use the @option{-d} binder switch to modify the default stack
15170 For access types, the @code{Storage_Size} clause specifies the maximum
15171 space available for allocation of objects of the type. If this space is
15172 exceeded then @code{Storage_Error} will be raised by an allocation attempt.
15173 In the case where the access type is declared local to a subprogram, the
15174 use of a @code{Storage_Size} clause triggers automatic use of a special
15175 predefined storage pool (@code{System.Pool_Size}) that ensures that all
15176 space for the pool is automatically reclaimed on exit from the scope in
15177 which the type is declared.
15179 A special case recognized by the compiler is the specification of a
15180 @code{Storage_Size} of zero for an access type. This means that no
15181 items can be allocated from the pool, and this is recognized at compile
15182 time, and all the overhead normally associated with maintaining a fixed
15183 size storage pool is eliminated. Consider the following example:
15185 @smallexample @c ada
15187 type R is array (Natural) of Character;
15188 type P is access all R;
15189 for P'Storage_Size use 0;
15190 -- Above access type intended only for interfacing purposes
15194 procedure g (m : P);
15195 pragma Import (C, g);
15206 As indicated in this example, these dummy storage pools are often useful in
15207 connection with interfacing where no object will ever be allocated. If you
15208 compile the above example, you get the warning:
15211 p.adb:16:09: warning: allocation from empty storage pool
15212 p.adb:16:09: warning: Storage_Error will be raised at run time
15216 Of course in practice, there will not be any explicit allocators in the
15217 case of such an access declaration.
15219 @node Size of Variant Record Objects
15220 @section Size of Variant Record Objects
15221 @cindex Size, variant record objects
15222 @cindex Variant record objects, size
15225 In the case of variant record objects, there is a question whether Size gives
15226 information about a particular variant, or the maximum size required
15227 for any variant. Consider the following program
15229 @smallexample @c ada
15230 with Text_IO; use Text_IO;
15232 type R1 (A : Boolean := False) is record
15234 when True => X : Character;
15235 when False => null;
15243 Put_Line (Integer'Image (V1'Size));
15244 Put_Line (Integer'Image (V2'Size));
15249 Here we are dealing with a variant record, where the True variant
15250 requires 16 bits, and the False variant requires 8 bits.
15251 In the above example, both V1 and V2 contain the False variant,
15252 which is only 8 bits long. However, the result of running the
15261 The reason for the difference here is that the discriminant value of
15262 V1 is fixed, and will always be False. It is not possible to assign
15263 a True variant value to V1, therefore 8 bits is sufficient. On the
15264 other hand, in the case of V2, the initial discriminant value is
15265 False (from the default), but it is possible to assign a True
15266 variant value to V2, therefore 16 bits must be allocated for V2
15267 in the general case, even fewer bits may be needed at any particular
15268 point during the program execution.
15270 As can be seen from the output of this program, the @code{'Size}
15271 attribute applied to such an object in GNAT gives the actual allocated
15272 size of the variable, which is the largest size of any of the variants.
15273 The Ada Reference Manual is not completely clear on what choice should
15274 be made here, but the GNAT behavior seems most consistent with the
15275 language in the RM@.
15277 In some cases, it may be desirable to obtain the size of the current
15278 variant, rather than the size of the largest variant. This can be
15279 achieved in GNAT by making use of the fact that in the case of a
15280 subprogram parameter, GNAT does indeed return the size of the current
15281 variant (because a subprogram has no way of knowing how much space
15282 is actually allocated for the actual).
15284 Consider the following modified version of the above program:
15286 @smallexample @c ada
15287 with Text_IO; use Text_IO;
15289 type R1 (A : Boolean := False) is record
15291 when True => X : Character;
15292 when False => null;
15298 function Size (V : R1) return Integer is
15304 Put_Line (Integer'Image (V2'Size));
15305 Put_Line (Integer'IMage (Size (V2)));
15307 Put_Line (Integer'Image (V2'Size));
15308 Put_Line (Integer'IMage (Size (V2)));
15313 The output from this program is
15323 Here we see that while the @code{'Size} attribute always returns
15324 the maximum size, regardless of the current variant value, the
15325 @code{Size} function does indeed return the size of the current
15328 @node Biased Representation
15329 @section Biased Representation
15330 @cindex Size for biased representation
15331 @cindex Biased representation
15334 In the case of scalars with a range starting at other than zero, it is
15335 possible in some cases to specify a size smaller than the default minimum
15336 value, and in such cases, GNAT uses an unsigned biased representation,
15337 in which zero is used to represent the lower bound, and successive values
15338 represent successive values of the type.
15340 For example, suppose we have the declaration:
15342 @smallexample @c ada
15343 type Small is range -7 .. -4;
15344 for Small'Size use 2;
15348 Although the default size of type @code{Small} is 4, the @code{Size}
15349 clause is accepted by GNAT and results in the following representation
15353 -7 is represented as 2#00#
15354 -6 is represented as 2#01#
15355 -5 is represented as 2#10#
15356 -4 is represented as 2#11#
15360 Biased representation is only used if the specified @code{Size} clause
15361 cannot be accepted in any other manner. These reduced sizes that force
15362 biased representation can be used for all discrete types except for
15363 enumeration types for which a representation clause is given.
15365 @node Value_Size and Object_Size Clauses
15366 @section Value_Size and Object_Size Clauses
15368 @findex Object_Size
15369 @cindex Size, of objects
15372 In Ada 95 and Ada 2005, @code{T'Size} for a type @code{T} is the minimum
15373 number of bits required to hold values of type @code{T}.
15374 Although this interpretation was allowed in Ada 83, it was not required,
15375 and this requirement in practice can cause some significant difficulties.
15376 For example, in most Ada 83 compilers, @code{Natural'Size} was 32.
15377 However, in Ada 95 and Ada 2005,
15378 @code{Natural'Size} is
15379 typically 31. This means that code may change in behavior when moving
15380 from Ada 83 to Ada 95 or Ada 2005. For example, consider:
15382 @smallexample @c ada
15383 type Rec is record;
15389 at 0 range 0 .. Natural'Size - 1;
15390 at 0 range Natural'Size .. 2 * Natural'Size - 1;
15395 In the above code, since the typical size of @code{Natural} objects
15396 is 32 bits and @code{Natural'Size} is 31, the above code can cause
15397 unexpected inefficient packing in Ada 95 and Ada 2005, and in general
15398 there are cases where the fact that the object size can exceed the
15399 size of the type causes surprises.
15401 To help get around this problem GNAT provides two implementation
15402 defined attributes, @code{Value_Size} and @code{Object_Size}. When
15403 applied to a type, these attributes yield the size of the type
15404 (corresponding to the RM defined size attribute), and the size of
15405 objects of the type respectively.
15407 The @code{Object_Size} is used for determining the default size of
15408 objects and components. This size value can be referred to using the
15409 @code{Object_Size} attribute. The phrase ``is used'' here means that it is
15410 the basis of the determination of the size. The backend is free to
15411 pad this up if necessary for efficiency, e.g.@: an 8-bit stand-alone
15412 character might be stored in 32 bits on a machine with no efficient
15413 byte access instructions such as the Alpha.
15415 The default rules for the value of @code{Object_Size} for
15416 discrete types are as follows:
15420 The @code{Object_Size} for base subtypes reflect the natural hardware
15421 size in bits (run the compiler with @option{-gnatS} to find those values
15422 for numeric types). Enumeration types and fixed-point base subtypes have
15423 8, 16, 32 or 64 bits for this size, depending on the range of values
15427 The @code{Object_Size} of a subtype is the same as the
15428 @code{Object_Size} of
15429 the type from which it is obtained.
15432 The @code{Object_Size} of a derived base type is copied from the parent
15433 base type, and the @code{Object_Size} of a derived first subtype is copied
15434 from the parent first subtype.
15438 The @code{Value_Size} attribute
15439 is the (minimum) number of bits required to store a value
15441 This value is used to determine how tightly to pack
15442 records or arrays with components of this type, and also affects
15443 the semantics of unchecked conversion (unchecked conversions where
15444 the @code{Value_Size} values differ generate a warning, and are potentially
15447 The default rules for the value of @code{Value_Size} are as follows:
15451 The @code{Value_Size} for a base subtype is the minimum number of bits
15452 required to store all values of the type (including the sign bit
15453 only if negative values are possible).
15456 If a subtype statically matches the first subtype of a given type, then it has
15457 by default the same @code{Value_Size} as the first subtype. This is a
15458 consequence of RM 13.1(14) (``if two subtypes statically match,
15459 then their subtype-specific aspects are the same''.)
15462 All other subtypes have a @code{Value_Size} corresponding to the minimum
15463 number of bits required to store all values of the subtype. For
15464 dynamic bounds, it is assumed that the value can range down or up
15465 to the corresponding bound of the ancestor
15469 The RM defined attribute @code{Size} corresponds to the
15470 @code{Value_Size} attribute.
15472 The @code{Size} attribute may be defined for a first-named subtype. This sets
15473 the @code{Value_Size} of
15474 the first-named subtype to the given value, and the
15475 @code{Object_Size} of this first-named subtype to the given value padded up
15476 to an appropriate boundary. It is a consequence of the default rules
15477 above that this @code{Object_Size} will apply to all further subtypes. On the
15478 other hand, @code{Value_Size} is affected only for the first subtype, any
15479 dynamic subtypes obtained from it directly, and any statically matching
15480 subtypes. The @code{Value_Size} of any other static subtypes is not affected.
15482 @code{Value_Size} and
15483 @code{Object_Size} may be explicitly set for any subtype using
15484 an attribute definition clause. Note that the use of these attributes
15485 can cause the RM 13.1(14) rule to be violated. If two access types
15486 reference aliased objects whose subtypes have differing @code{Object_Size}
15487 values as a result of explicit attribute definition clauses, then it
15488 is illegal to convert from one access subtype to the other. For a more
15489 complete description of this additional legality rule, see the
15490 description of the @code{Object_Size} attribute.
15492 At the implementation level, Esize stores the Object_Size and the
15493 RM_Size field stores the @code{Value_Size} (and hence the value of the
15494 @code{Size} attribute,
15495 which, as noted above, is equivalent to @code{Value_Size}).
15497 To get a feel for the difference, consider the following examples (note
15498 that in each case the base is @code{Short_Short_Integer} with a size of 8):
15501 Object_Size Value_Size
15503 type x1 is range 0 .. 5; 8 3
15505 type x2 is range 0 .. 5;
15506 for x2'size use 12; 16 12
15508 subtype x3 is x2 range 0 .. 3; 16 2
15510 subtype x4 is x2'base range 0 .. 10; 8 4
15512 subtype x5 is x2 range 0 .. dynamic; 16 3*
15514 subtype x6 is x2'base range 0 .. dynamic; 8 3*
15519 Note: the entries marked ``3*'' are not actually specified by the Ada
15520 Reference Manual, but it seems in the spirit of the RM rules to allocate
15521 the minimum number of bits (here 3, given the range for @code{x2})
15522 known to be large enough to hold the given range of values.
15524 So far, so good, but GNAT has to obey the RM rules, so the question is
15525 under what conditions must the RM @code{Size} be used.
15526 The following is a list
15527 of the occasions on which the RM @code{Size} must be used:
15531 Component size for packed arrays or records
15534 Value of the attribute @code{Size} for a type
15537 Warning about sizes not matching for unchecked conversion
15541 For record types, the @code{Object_Size} is always a multiple of the
15542 alignment of the type (this is true for all types). In some cases the
15543 @code{Value_Size} can be smaller. Consider:
15553 On a typical 32-bit architecture, the X component will be four bytes, and
15554 require four-byte alignment, and the Y component will be one byte. In this
15555 case @code{R'Value_Size} will be 40 (bits) since this is the minimum size
15556 required to store a value of this type, and for example, it is permissible
15557 to have a component of type R in an outer array whose component size is
15558 specified to be 48 bits. However, @code{R'Object_Size} will be 64 (bits),
15559 since it must be rounded up so that this value is a multiple of the
15560 alignment (4 bytes = 32 bits).
15563 For all other types, the @code{Object_Size}
15564 and Value_Size are the same (and equivalent to the RM attribute @code{Size}).
15565 Only @code{Size} may be specified for such types.
15567 Note that @code{Value_Size} can be used to force biased representation
15568 for a particular subtype. Consider this example:
15571 type R is (A, B, C, D, E, F);
15572 subtype RAB is R range A .. B;
15573 subtype REF is R range E .. F;
15577 By default, @code{RAB}
15578 has a size of 1 (sufficient to accommodate the representation
15579 of @code{A} and @code{B}, 0 and 1), and @code{REF}
15580 has a size of 3 (sufficient to accommodate the representation
15581 of @code{E} and @code{F}, 4 and 5). But if we add the
15582 following @code{Value_Size} attribute definition clause:
15585 for REF'Value_Size use 1;
15589 then biased representation is forced for @code{REF},
15590 and 0 will represent @code{E} and 1 will represent @code{F}.
15591 A warning is issued when a @code{Value_Size} attribute
15592 definition clause forces biased representation. This
15593 warning can be turned off using @code{-gnatw.B}.
15595 @node Component_Size Clauses
15596 @section Component_Size Clauses
15597 @cindex Component_Size Clause
15600 Normally, the value specified in a component size clause must be consistent
15601 with the subtype of the array component with regard to size and alignment.
15602 In other words, the value specified must be at least equal to the size
15603 of this subtype, and must be a multiple of the alignment value.
15605 In addition, component size clauses are allowed which cause the array
15606 to be packed, by specifying a smaller value. A first case is for
15607 component size values in the range 1 through 63. The value specified
15608 must not be smaller than the Size of the subtype. GNAT will accurately
15609 honor all packing requests in this range. For example, if we have:
15611 @smallexample @c ada
15612 type r is array (1 .. 8) of Natural;
15613 for r'Component_Size use 31;
15617 then the resulting array has a length of 31 bytes (248 bits = 8 * 31).
15618 Of course access to the components of such an array is considerably
15619 less efficient than if the natural component size of 32 is used.
15620 A second case is when the subtype of the component is a record type
15621 padded because of its default alignment. For example, if we have:
15623 @smallexample @c ada
15630 type a is array (1 .. 8) of r;
15631 for a'Component_Size use 72;
15635 then the resulting array has a length of 72 bytes, instead of 96 bytes
15636 if the alignment of the record (4) was obeyed.
15638 Note that there is no point in giving both a component size clause
15639 and a pragma Pack for the same array type. if such duplicate
15640 clauses are given, the pragma Pack will be ignored.
15642 @node Bit_Order Clauses
15643 @section Bit_Order Clauses
15644 @cindex Bit_Order Clause
15645 @cindex bit ordering
15646 @cindex ordering, of bits
15649 For record subtypes, GNAT permits the specification of the @code{Bit_Order}
15650 attribute. The specification may either correspond to the default bit
15651 order for the target, in which case the specification has no effect and
15652 places no additional restrictions, or it may be for the non-standard
15653 setting (that is the opposite of the default).
15655 In the case where the non-standard value is specified, the effect is
15656 to renumber bits within each byte, but the ordering of bytes is not
15657 affected. There are certain
15658 restrictions placed on component clauses as follows:
15662 @item Components fitting within a single storage unit.
15664 These are unrestricted, and the effect is merely to renumber bits. For
15665 example if we are on a little-endian machine with @code{Low_Order_First}
15666 being the default, then the following two declarations have exactly
15669 @smallexample @c ada
15672 B : Integer range 1 .. 120;
15676 A at 0 range 0 .. 0;
15677 B at 0 range 1 .. 7;
15682 B : Integer range 1 .. 120;
15685 for R2'Bit_Order use High_Order_First;
15688 A at 0 range 7 .. 7;
15689 B at 0 range 0 .. 6;
15694 The useful application here is to write the second declaration with the
15695 @code{Bit_Order} attribute definition clause, and know that it will be treated
15696 the same, regardless of whether the target is little-endian or big-endian.
15698 @item Components occupying an integral number of bytes.
15700 These are components that exactly fit in two or more bytes. Such component
15701 declarations are allowed, but have no effect, since it is important to realize
15702 that the @code{Bit_Order} specification does not affect the ordering of bytes.
15703 In particular, the following attempt at getting an endian-independent integer
15706 @smallexample @c ada
15711 for R2'Bit_Order use High_Order_First;
15714 A at 0 range 0 .. 31;
15719 This declaration will result in a little-endian integer on a
15720 little-endian machine, and a big-endian integer on a big-endian machine.
15721 If byte flipping is required for interoperability between big- and
15722 little-endian machines, this must be explicitly programmed. This capability
15723 is not provided by @code{Bit_Order}.
15725 @item Components that are positioned across byte boundaries
15727 but do not occupy an integral number of bytes. Given that bytes are not
15728 reordered, such fields would occupy a non-contiguous sequence of bits
15729 in memory, requiring non-trivial code to reassemble. They are for this
15730 reason not permitted, and any component clause specifying such a layout
15731 will be flagged as illegal by GNAT@.
15736 Since the misconception that Bit_Order automatically deals with all
15737 endian-related incompatibilities is a common one, the specification of
15738 a component field that is an integral number of bytes will always
15739 generate a warning. This warning may be suppressed using @code{pragma
15740 Warnings (Off)} if desired. The following section contains additional
15741 details regarding the issue of byte ordering.
15743 @node Effect of Bit_Order on Byte Ordering
15744 @section Effect of Bit_Order on Byte Ordering
15745 @cindex byte ordering
15746 @cindex ordering, of bytes
15749 In this section we will review the effect of the @code{Bit_Order} attribute
15750 definition clause on byte ordering. Briefly, it has no effect at all, but
15751 a detailed example will be helpful. Before giving this
15752 example, let us review the precise
15753 definition of the effect of defining @code{Bit_Order}. The effect of a
15754 non-standard bit order is described in section 15.5.3 of the Ada
15758 2 A bit ordering is a method of interpreting the meaning of
15759 the storage place attributes.
15763 To understand the precise definition of storage place attributes in
15764 this context, we visit section 13.5.1 of the manual:
15767 13 A record_representation_clause (without the mod_clause)
15768 specifies the layout. The storage place attributes (see 13.5.2)
15769 are taken from the values of the position, first_bit, and last_bit
15770 expressions after normalizing those values so that first_bit is
15771 less than Storage_Unit.
15775 The critical point here is that storage places are taken from
15776 the values after normalization, not before. So the @code{Bit_Order}
15777 interpretation applies to normalized values. The interpretation
15778 is described in the later part of the 15.5.3 paragraph:
15781 2 A bit ordering is a method of interpreting the meaning of
15782 the storage place attributes. High_Order_First (known in the
15783 vernacular as ``big endian'') means that the first bit of a
15784 storage element (bit 0) is the most significant bit (interpreting
15785 the sequence of bits that represent a component as an unsigned
15786 integer value). Low_Order_First (known in the vernacular as
15787 ``little endian'') means the opposite: the first bit is the
15792 Note that the numbering is with respect to the bits of a storage
15793 unit. In other words, the specification affects only the numbering
15794 of bits within a single storage unit.
15796 We can make the effect clearer by giving an example.
15798 Suppose that we have an external device which presents two bytes, the first
15799 byte presented, which is the first (low addressed byte) of the two byte
15800 record is called Master, and the second byte is called Slave.
15802 The left most (most significant bit is called Control for each byte, and
15803 the remaining 7 bits are called V1, V2, @dots{} V7, where V7 is the rightmost
15804 (least significant) bit.
15806 On a big-endian machine, we can write the following representation clause
15808 @smallexample @c ada
15809 type Data is record
15810 Master_Control : Bit;
15818 Slave_Control : Bit;
15828 for Data use record
15829 Master_Control at 0 range 0 .. 0;
15830 Master_V1 at 0 range 1 .. 1;
15831 Master_V2 at 0 range 2 .. 2;
15832 Master_V3 at 0 range 3 .. 3;
15833 Master_V4 at 0 range 4 .. 4;
15834 Master_V5 at 0 range 5 .. 5;
15835 Master_V6 at 0 range 6 .. 6;
15836 Master_V7 at 0 range 7 .. 7;
15837 Slave_Control at 1 range 0 .. 0;
15838 Slave_V1 at 1 range 1 .. 1;
15839 Slave_V2 at 1 range 2 .. 2;
15840 Slave_V3 at 1 range 3 .. 3;
15841 Slave_V4 at 1 range 4 .. 4;
15842 Slave_V5 at 1 range 5 .. 5;
15843 Slave_V6 at 1 range 6 .. 6;
15844 Slave_V7 at 1 range 7 .. 7;
15849 Now if we move this to a little endian machine, then the bit ordering within
15850 the byte is backwards, so we have to rewrite the record rep clause as:
15852 @smallexample @c ada
15853 for Data use record
15854 Master_Control at 0 range 7 .. 7;
15855 Master_V1 at 0 range 6 .. 6;
15856 Master_V2 at 0 range 5 .. 5;
15857 Master_V3 at 0 range 4 .. 4;
15858 Master_V4 at 0 range 3 .. 3;
15859 Master_V5 at 0 range 2 .. 2;
15860 Master_V6 at 0 range 1 .. 1;
15861 Master_V7 at 0 range 0 .. 0;
15862 Slave_Control at 1 range 7 .. 7;
15863 Slave_V1 at 1 range 6 .. 6;
15864 Slave_V2 at 1 range 5 .. 5;
15865 Slave_V3 at 1 range 4 .. 4;
15866 Slave_V4 at 1 range 3 .. 3;
15867 Slave_V5 at 1 range 2 .. 2;
15868 Slave_V6 at 1 range 1 .. 1;
15869 Slave_V7 at 1 range 0 .. 0;
15874 It is a nuisance to have to rewrite the clause, especially if
15875 the code has to be maintained on both machines. However,
15876 this is a case that we can handle with the
15877 @code{Bit_Order} attribute if it is implemented.
15878 Note that the implementation is not required on byte addressed
15879 machines, but it is indeed implemented in GNAT.
15880 This means that we can simply use the
15881 first record clause, together with the declaration
15883 @smallexample @c ada
15884 for Data'Bit_Order use High_Order_First;
15888 and the effect is what is desired, namely the layout is exactly the same,
15889 independent of whether the code is compiled on a big-endian or little-endian
15892 The important point to understand is that byte ordering is not affected.
15893 A @code{Bit_Order} attribute definition never affects which byte a field
15894 ends up in, only where it ends up in that byte.
15895 To make this clear, let us rewrite the record rep clause of the previous
15898 @smallexample @c ada
15899 for Data'Bit_Order use High_Order_First;
15900 for Data use record
15901 Master_Control at 0 range 0 .. 0;
15902 Master_V1 at 0 range 1 .. 1;
15903 Master_V2 at 0 range 2 .. 2;
15904 Master_V3 at 0 range 3 .. 3;
15905 Master_V4 at 0 range 4 .. 4;
15906 Master_V5 at 0 range 5 .. 5;
15907 Master_V6 at 0 range 6 .. 6;
15908 Master_V7 at 0 range 7 .. 7;
15909 Slave_Control at 0 range 8 .. 8;
15910 Slave_V1 at 0 range 9 .. 9;
15911 Slave_V2 at 0 range 10 .. 10;
15912 Slave_V3 at 0 range 11 .. 11;
15913 Slave_V4 at 0 range 12 .. 12;
15914 Slave_V5 at 0 range 13 .. 13;
15915 Slave_V6 at 0 range 14 .. 14;
15916 Slave_V7 at 0 range 15 .. 15;
15921 This is exactly equivalent to saying (a repeat of the first example):
15923 @smallexample @c ada
15924 for Data'Bit_Order use High_Order_First;
15925 for Data use record
15926 Master_Control at 0 range 0 .. 0;
15927 Master_V1 at 0 range 1 .. 1;
15928 Master_V2 at 0 range 2 .. 2;
15929 Master_V3 at 0 range 3 .. 3;
15930 Master_V4 at 0 range 4 .. 4;
15931 Master_V5 at 0 range 5 .. 5;
15932 Master_V6 at 0 range 6 .. 6;
15933 Master_V7 at 0 range 7 .. 7;
15934 Slave_Control at 1 range 0 .. 0;
15935 Slave_V1 at 1 range 1 .. 1;
15936 Slave_V2 at 1 range 2 .. 2;
15937 Slave_V3 at 1 range 3 .. 3;
15938 Slave_V4 at 1 range 4 .. 4;
15939 Slave_V5 at 1 range 5 .. 5;
15940 Slave_V6 at 1 range 6 .. 6;
15941 Slave_V7 at 1 range 7 .. 7;
15946 Why are they equivalent? Well take a specific field, the @code{Slave_V2}
15947 field. The storage place attributes are obtained by normalizing the
15948 values given so that the @code{First_Bit} value is less than 8. After
15949 normalizing the values (0,10,10) we get (1,2,2) which is exactly what
15950 we specified in the other case.
15952 Now one might expect that the @code{Bit_Order} attribute might affect
15953 bit numbering within the entire record component (two bytes in this
15954 case, thus affecting which byte fields end up in), but that is not
15955 the way this feature is defined, it only affects numbering of bits,
15956 not which byte they end up in.
15958 Consequently it never makes sense to specify a starting bit number
15959 greater than 7 (for a byte addressable field) if an attribute
15960 definition for @code{Bit_Order} has been given, and indeed it
15961 may be actively confusing to specify such a value, so the compiler
15962 generates a warning for such usage.
15964 If you do need to control byte ordering then appropriate conditional
15965 values must be used. If in our example, the slave byte came first on
15966 some machines we might write:
15968 @smallexample @c ada
15969 Master_Byte_First constant Boolean := @dots{};
15971 Master_Byte : constant Natural :=
15972 1 - Boolean'Pos (Master_Byte_First);
15973 Slave_Byte : constant Natural :=
15974 Boolean'Pos (Master_Byte_First);
15976 for Data'Bit_Order use High_Order_First;
15977 for Data use record
15978 Master_Control at Master_Byte range 0 .. 0;
15979 Master_V1 at Master_Byte range 1 .. 1;
15980 Master_V2 at Master_Byte range 2 .. 2;
15981 Master_V3 at Master_Byte range 3 .. 3;
15982 Master_V4 at Master_Byte range 4 .. 4;
15983 Master_V5 at Master_Byte range 5 .. 5;
15984 Master_V6 at Master_Byte range 6 .. 6;
15985 Master_V7 at Master_Byte range 7 .. 7;
15986 Slave_Control at Slave_Byte range 0 .. 0;
15987 Slave_V1 at Slave_Byte range 1 .. 1;
15988 Slave_V2 at Slave_Byte range 2 .. 2;
15989 Slave_V3 at Slave_Byte range 3 .. 3;
15990 Slave_V4 at Slave_Byte range 4 .. 4;
15991 Slave_V5 at Slave_Byte range 5 .. 5;
15992 Slave_V6 at Slave_Byte range 6 .. 6;
15993 Slave_V7 at Slave_Byte range 7 .. 7;
15998 Now to switch between machines, all that is necessary is
15999 to set the boolean constant @code{Master_Byte_First} in
16000 an appropriate manner.
16002 @node Pragma Pack for Arrays
16003 @section Pragma Pack for Arrays
16004 @cindex Pragma Pack (for arrays)
16007 Pragma @code{Pack} applied to an array has no effect unless the component type
16008 is packable. For a component type to be packable, it must be one of the
16015 Any type whose size is specified with a size clause
16017 Any packed array type with a static size
16019 Any record type padded because of its default alignment
16023 For all these cases, if the component subtype size is in the range
16024 1 through 63, then the effect of the pragma @code{Pack} is exactly as though a
16025 component size were specified giving the component subtype size.
16026 For example if we have:
16028 @smallexample @c ada
16029 type r is range 0 .. 17;
16031 type ar is array (1 .. 8) of r;
16036 Then the component size of @code{ar} will be set to 5 (i.e.@: to @code{r'size},
16037 and the size of the array @code{ar} will be exactly 40 bits.
16039 Note that in some cases this rather fierce approach to packing can produce
16040 unexpected effects. For example, in Ada 95 and Ada 2005,
16041 subtype @code{Natural} typically has a size of 31, meaning that if you
16042 pack an array of @code{Natural}, you get 31-bit
16043 close packing, which saves a few bits, but results in far less efficient
16044 access. Since many other Ada compilers will ignore such a packing request,
16045 GNAT will generate a warning on some uses of pragma @code{Pack} that it guesses
16046 might not be what is intended. You can easily remove this warning by
16047 using an explicit @code{Component_Size} setting instead, which never generates
16048 a warning, since the intention of the programmer is clear in this case.
16050 GNAT treats packed arrays in one of two ways. If the size of the array is
16051 known at compile time and is less than 64 bits, then internally the array
16052 is represented as a single modular type, of exactly the appropriate number
16053 of bits. If the length is greater than 63 bits, or is not known at compile
16054 time, then the packed array is represented as an array of bytes, and the
16055 length is always a multiple of 8 bits.
16057 Note that to represent a packed array as a modular type, the alignment must
16058 be suitable for the modular type involved. For example, on typical machines
16059 a 32-bit packed array will be represented by a 32-bit modular integer with
16060 an alignment of four bytes. If you explicitly override the default alignment
16061 with an alignment clause that is too small, the modular representation
16062 cannot be used. For example, consider the following set of declarations:
16064 @smallexample @c ada
16065 type R is range 1 .. 3;
16066 type S is array (1 .. 31) of R;
16067 for S'Component_Size use 2;
16069 for S'Alignment use 1;
16073 If the alignment clause were not present, then a 62-bit modular
16074 representation would be chosen (typically with an alignment of 4 or 8
16075 bytes depending on the target). But the default alignment is overridden
16076 with the explicit alignment clause. This means that the modular
16077 representation cannot be used, and instead the array of bytes
16078 representation must be used, meaning that the length must be a multiple
16079 of 8. Thus the above set of declarations will result in a diagnostic
16080 rejecting the size clause and noting that the minimum size allowed is 64.
16082 @cindex Pragma Pack (for type Natural)
16083 @cindex Pragma Pack warning
16085 One special case that is worth noting occurs when the base type of the
16086 component size is 8/16/32 and the subtype is one bit less. Notably this
16087 occurs with subtype @code{Natural}. Consider:
16089 @smallexample @c ada
16090 type Arr is array (1 .. 32) of Natural;
16095 In all commonly used Ada 83 compilers, this pragma Pack would be ignored,
16096 since typically @code{Natural'Size} is 32 in Ada 83, and in any case most
16097 Ada 83 compilers did not attempt 31 bit packing.
16099 In Ada 95 and Ada 2005, @code{Natural'Size} is required to be 31. Furthermore,
16100 GNAT really does pack 31-bit subtype to 31 bits. This may result in a
16101 substantial unintended performance penalty when porting legacy Ada 83 code.
16102 To help prevent this, GNAT generates a warning in such cases. If you really
16103 want 31 bit packing in a case like this, you can set the component size
16106 @smallexample @c ada
16107 type Arr is array (1 .. 32) of Natural;
16108 for Arr'Component_Size use 31;
16112 Here 31-bit packing is achieved as required, and no warning is generated,
16113 since in this case the programmer intention is clear.
16115 @node Pragma Pack for Records
16116 @section Pragma Pack for Records
16117 @cindex Pragma Pack (for records)
16120 Pragma @code{Pack} applied to a record will pack the components to reduce
16121 wasted space from alignment gaps and by reducing the amount of space
16122 taken by components. We distinguish between @emph{packable} components and
16123 @emph{non-packable} components.
16124 Components of the following types are considered packable:
16127 Components of a primitive type are packable unless they are aliased
16128 or of an atomic type.
16131 Small packed arrays, whose size does not exceed 64 bits, and where the
16132 size is statically known at compile time, are represented internally
16133 as modular integers, and so they are also packable.
16138 All packable components occupy the exact number of bits corresponding to
16139 their @code{Size} value, and are packed with no padding bits, i.e.@: they
16140 can start on an arbitrary bit boundary.
16142 All other types are non-packable, they occupy an integral number of
16144 are placed at a boundary corresponding to their alignment requirements.
16146 For example, consider the record
16148 @smallexample @c ada
16149 type Rb1 is array (1 .. 13) of Boolean;
16152 type Rb2 is array (1 .. 65) of Boolean;
16155 type AF is new Float with Atomic;
16169 The representation for the record X2 is as follows:
16171 @smallexample @c ada
16172 for X2'Size use 224;
16174 L1 at 0 range 0 .. 0;
16175 L2 at 0 range 1 .. 64;
16176 L3 at 12 range 0 .. 31;
16177 L4 at 16 range 0 .. 0;
16178 L5 at 16 range 1 .. 13;
16179 L6 at 18 range 0 .. 71;
16184 Studying this example, we see that the packable fields @code{L1}
16186 of length equal to their sizes, and placed at specific bit boundaries (and
16187 not byte boundaries) to
16188 eliminate padding. But @code{L3} is of a non-packable float type (because
16189 it is aliased), so it is on the next appropriate alignment boundary.
16191 The next two fields are fully packable, so @code{L4} and @code{L5} are
16192 minimally packed with no gaps. However, type @code{Rb2} is a packed
16193 array that is longer than 64 bits, so it is itself non-packable. Thus
16194 the @code{L6} field is aligned to the next byte boundary, and takes an
16195 integral number of bytes, i.e.@: 72 bits.
16197 @node Record Representation Clauses
16198 @section Record Representation Clauses
16199 @cindex Record Representation Clause
16202 Record representation clauses may be given for all record types, including
16203 types obtained by record extension. Component clauses are allowed for any
16204 static component. The restrictions on component clauses depend on the type
16207 @cindex Component Clause
16208 For all components of an elementary type, the only restriction on component
16209 clauses is that the size must be at least the 'Size value of the type
16210 (actually the Value_Size). There are no restrictions due to alignment,
16211 and such components may freely cross storage boundaries.
16213 Packed arrays with a size up to and including 64 bits are represented
16214 internally using a modular type with the appropriate number of bits, and
16215 thus the same lack of restriction applies. For example, if you declare:
16217 @smallexample @c ada
16218 type R is array (1 .. 49) of Boolean;
16224 then a component clause for a component of type R may start on any
16225 specified bit boundary, and may specify a value of 49 bits or greater.
16227 For packed bit arrays that are longer than 64 bits, there are two
16228 cases. If the component size is a power of 2 (1,2,4,8,16,32 bits),
16229 including the important case of single bits or boolean values, then
16230 there are no limitations on placement of such components, and they
16231 may start and end at arbitrary bit boundaries.
16233 If the component size is not a power of 2 (e.g.@: 3 or 5), then
16234 an array of this type longer than 64 bits must always be placed on
16235 on a storage unit (byte) boundary and occupy an integral number
16236 of storage units (bytes). Any component clause that does not
16237 meet this requirement will be rejected.
16239 Any aliased component, or component of an aliased type, must
16240 have its normal alignment and size. A component clause that
16241 does not meet this requirement will be rejected.
16243 The tag field of a tagged type always occupies an address sized field at
16244 the start of the record. No component clause may attempt to overlay this
16245 tag. When a tagged type appears as a component, the tag field must have
16248 In the case of a record extension T1, of a type T, no component clause applied
16249 to the type T1 can specify a storage location that would overlap the first
16250 T'Size bytes of the record.
16252 For all other component types, including non-bit-packed arrays,
16253 the component can be placed at an arbitrary bit boundary,
16254 so for example, the following is permitted:
16256 @smallexample @c ada
16257 type R is array (1 .. 10) of Boolean;
16266 G at 0 range 0 .. 0;
16267 H at 0 range 1 .. 1;
16268 L at 0 range 2 .. 81;
16269 R at 0 range 82 .. 161;
16274 Note: the above rules apply to recent releases of GNAT 5.
16275 In GNAT 3, there are more severe restrictions on larger components.
16276 For non-primitive types, including packed arrays with a size greater than
16277 64 bits, component clauses must respect the alignment requirement of the
16278 type, in particular, always starting on a byte boundary, and the length
16279 must be a multiple of the storage unit.
16281 @node Handling of Records with Holes
16282 @section Handling of Records with Holes
16283 @cindex Handling of Records with Holes
16285 As a result of alignment considerations, records may contain "holes"
16287 which do not correspond to the data bits of any of the components.
16288 Record representation clauses can also result in holes in records.
16290 GNAT does not attempt to clear these holes, so in record objects,
16291 they should be considered to hold undefined rubbish. The generated
16292 equality routine just tests components so does not access these
16293 undefined bits, and assignment and copy operations may or may not
16294 preserve the contents of these holes (for assignments, the holes
16295 in the target will in practice contain either the bits that are
16296 present in the holes in the source, or the bits that were present
16297 in the target before the assignment).
16299 If it is necessary to ensure that holes in records have all zero
16300 bits, then record objects for which this initialization is desired
16301 should be explicitly set to all zero values using Unchecked_Conversion
16302 or address overlays. For example
16304 @smallexample @c ada
16305 type HRec is record
16312 On typical machines, integers need to be aligned on a four-byte
16313 boundary, resulting in three bytes of undefined rubbish following
16314 the 8-bit field for C. To ensure that the hole in a variable of
16315 type HRec is set to all zero bits,
16316 you could for example do:
16318 @smallexample @c ada
16319 type Base is record
16320 Dummy1, Dummy2 : Integer := 0;
16325 for RealVar'Address use BaseVar'Address;
16329 Now the 8-bytes of the value of RealVar start out containing all zero
16330 bits. A safer approach is to just define dummy fields, avoiding the
16333 @smallexample @c ada
16334 type HRec is record
16336 Dummy1 : Short_Short_Integer := 0;
16337 Dummy2 : Short_Short_Integer := 0;
16338 Dummy3 : Short_Short_Integer := 0;
16344 And to make absolutely sure that the intent of this is followed, you
16345 can use representation clauses:
16347 @smallexample @c ada
16348 for Hrec use record
16349 C at 0 range 0 .. 7;
16350 Dummy1 at 1 range 0 .. 7;
16351 Dummy2 at 2 range 0 .. 7;
16352 Dummy3 at 3 range 0 .. 7;
16353 I at 4 range 0 .. 31;
16355 for Hrec'Size use 64;
16358 @node Enumeration Clauses
16359 @section Enumeration Clauses
16361 The only restriction on enumeration clauses is that the range of values
16362 must be representable. For the signed case, if one or more of the
16363 representation values are negative, all values must be in the range:
16365 @smallexample @c ada
16366 System.Min_Int .. System.Max_Int
16370 For the unsigned case, where all values are nonnegative, the values must
16373 @smallexample @c ada
16374 0 .. System.Max_Binary_Modulus;
16378 A @emph{confirming} representation clause is one in which the values range
16379 from 0 in sequence, i.e.@: a clause that confirms the default representation
16380 for an enumeration type.
16381 Such a confirming representation
16382 is permitted by these rules, and is specially recognized by the compiler so
16383 that no extra overhead results from the use of such a clause.
16385 If an array has an index type which is an enumeration type to which an
16386 enumeration clause has been applied, then the array is stored in a compact
16387 manner. Consider the declarations:
16389 @smallexample @c ada
16390 type r is (A, B, C);
16391 for r use (A => 1, B => 5, C => 10);
16392 type t is array (r) of Character;
16396 The array type t corresponds to a vector with exactly three elements and
16397 has a default size equal to @code{3*Character'Size}. This ensures efficient
16398 use of space, but means that accesses to elements of the array will incur
16399 the overhead of converting representation values to the corresponding
16400 positional values, (i.e.@: the value delivered by the @code{Pos} attribute).
16402 @node Address Clauses
16403 @section Address Clauses
16404 @cindex Address Clause
16406 The reference manual allows a general restriction on representation clauses,
16407 as found in RM 13.1(22):
16410 An implementation need not support representation
16411 items containing nonstatic expressions, except that
16412 an implementation should support a representation item
16413 for a given entity if each nonstatic expression in the
16414 representation item is a name that statically denotes
16415 a constant declared before the entity.
16419 In practice this is applicable only to address clauses, since this is the
16420 only case in which a non-static expression is permitted by the syntax. As
16421 the AARM notes in sections 13.1 (22.a-22.h):
16424 22.a Reason: This is to avoid the following sort of thing:
16426 22.b X : Integer := F(@dots{});
16427 Y : Address := G(@dots{});
16428 for X'Address use Y;
16430 22.c In the above, we have to evaluate the
16431 initialization expression for X before we
16432 know where to put the result. This seems
16433 like an unreasonable implementation burden.
16435 22.d The above code should instead be written
16438 22.e Y : constant Address := G(@dots{});
16439 X : Integer := F(@dots{});
16440 for X'Address use Y;
16442 22.f This allows the expression ``Y'' to be safely
16443 evaluated before X is created.
16445 22.g The constant could be a formal parameter of mode in.
16447 22.h An implementation can support other nonstatic
16448 expressions if it wants to. Expressions of type
16449 Address are hardly ever static, but their value
16450 might be known at compile time anyway in many
16455 GNAT does indeed permit many additional cases of non-static expressions. In
16456 particular, if the type involved is elementary there are no restrictions
16457 (since in this case, holding a temporary copy of the initialization value,
16458 if one is present, is inexpensive). In addition, if there is no implicit or
16459 explicit initialization, then there are no restrictions. GNAT will reject
16460 only the case where all three of these conditions hold:
16465 The type of the item is non-elementary (e.g.@: a record or array).
16468 There is explicit or implicit initialization required for the object.
16469 Note that access values are always implicitly initialized.
16472 The address value is non-static. Here GNAT is more permissive than the
16473 RM, and allows the address value to be the address of a previously declared
16474 stand-alone variable, as long as it does not itself have an address clause.
16476 @smallexample @c ada
16477 Anchor : Some_Initialized_Type;
16478 Overlay : Some_Initialized_Type;
16479 for Overlay'Address use Anchor'Address;
16483 However, the prefix of the address clause cannot be an array component, or
16484 a component of a discriminated record.
16489 As noted above in section 22.h, address values are typically non-static. In
16490 particular the To_Address function, even if applied to a literal value, is
16491 a non-static function call. To avoid this minor annoyance, GNAT provides
16492 the implementation defined attribute 'To_Address. The following two
16493 expressions have identical values:
16497 @smallexample @c ada
16498 To_Address (16#1234_0000#)
16499 System'To_Address (16#1234_0000#);
16503 except that the second form is considered to be a static expression, and
16504 thus when used as an address clause value is always permitted.
16507 Additionally, GNAT treats as static an address clause that is an
16508 unchecked_conversion of a static integer value. This simplifies the porting
16509 of legacy code, and provides a portable equivalent to the GNAT attribute
16512 Another issue with address clauses is the interaction with alignment
16513 requirements. When an address clause is given for an object, the address
16514 value must be consistent with the alignment of the object (which is usually
16515 the same as the alignment of the type of the object). If an address clause
16516 is given that specifies an inappropriately aligned address value, then the
16517 program execution is erroneous.
16519 Since this source of erroneous behavior can have unfortunate effects, GNAT
16520 checks (at compile time if possible, generating a warning, or at execution
16521 time with a run-time check) that the alignment is appropriate. If the
16522 run-time check fails, then @code{Program_Error} is raised. This run-time
16523 check is suppressed if range checks are suppressed, or if the special GNAT
16524 check Alignment_Check is suppressed, or if
16525 @code{pragma Restrictions (No_Elaboration_Code)} is in effect.
16527 Finally, GNAT does not permit overlaying of objects of controlled types or
16528 composite types containing a controlled component. In most cases, the compiler
16529 can detect an attempt at such overlays and will generate a warning at compile
16530 time and a Program_Error exception at run time.
16533 An address clause cannot be given for an exported object. More
16534 understandably the real restriction is that objects with an address
16535 clause cannot be exported. This is because such variables are not
16536 defined by the Ada program, so there is no external object to export.
16539 It is permissible to give an address clause and a pragma Import for the
16540 same object. In this case, the variable is not really defined by the
16541 Ada program, so there is no external symbol to be linked. The link name
16542 and the external name are ignored in this case. The reason that we allow this
16543 combination is that it provides a useful idiom to avoid unwanted
16544 initializations on objects with address clauses.
16546 When an address clause is given for an object that has implicit or
16547 explicit initialization, then by default initialization takes place. This
16548 means that the effect of the object declaration is to overwrite the
16549 memory at the specified address. This is almost always not what the
16550 programmer wants, so GNAT will output a warning:
16560 for Ext'Address use System'To_Address (16#1234_1234#);
16562 >>> warning: implicit initialization of "Ext" may
16563 modify overlaid storage
16564 >>> warning: use pragma Import for "Ext" to suppress
16565 initialization (RM B(24))
16571 As indicated by the warning message, the solution is to use a (dummy) pragma
16572 Import to suppress this initialization. The pragma tell the compiler that the
16573 object is declared and initialized elsewhere. The following package compiles
16574 without warnings (and the initialization is suppressed):
16576 @smallexample @c ada
16584 for Ext'Address use System'To_Address (16#1234_1234#);
16585 pragma Import (Ada, Ext);
16590 A final issue with address clauses involves their use for overlaying
16591 variables, as in the following example:
16592 @cindex Overlaying of objects
16594 @smallexample @c ada
16597 for B'Address use A'Address;
16601 or alternatively, using the form recommended by the RM:
16603 @smallexample @c ada
16605 Addr : constant Address := A'Address;
16607 for B'Address use Addr;
16611 In both of these cases, @code{A}
16612 and @code{B} become aliased to one another via the
16613 address clause. This use of address clauses to overlay
16614 variables, achieving an effect similar to unchecked
16615 conversion was erroneous in Ada 83, but in Ada 95 and Ada 2005
16616 the effect is implementation defined. Furthermore, the
16617 Ada RM specifically recommends that in a situation
16618 like this, @code{B} should be subject to the following
16619 implementation advice (RM 13.3(19)):
16622 19 If the Address of an object is specified, or it is imported
16623 or exported, then the implementation should not perform
16624 optimizations based on assumptions of no aliases.
16628 GNAT follows this recommendation, and goes further by also applying
16629 this recommendation to the overlaid variable (@code{A}
16630 in the above example) in this case. This means that the overlay
16631 works "as expected", in that a modification to one of the variables
16632 will affect the value of the other.
16634 Note that when address clause overlays are used in this way, there is an
16635 issue of unintentional initialization, as shown by this example:
16637 @smallexample @c ada
16638 package Overwrite_Record is
16640 A : Character := 'C';
16641 B : Character := 'A';
16643 X : Short_Integer := 3;
16645 for Y'Address use X'Address;
16647 >>> warning: default initialization of "Y" may
16648 modify "X", use pragma Import for "Y" to
16649 suppress initialization (RM B.1(24))
16651 end Overwrite_Record;
16655 Here the default initialization of @code{Y} will clobber the value
16656 of @code{X}, which justifies the warning. The warning notes that
16657 this effect can be eliminated by adding a @code{pragma Import}
16658 which suppresses the initialization:
16660 @smallexample @c ada
16661 package Overwrite_Record is
16663 A : Character := 'C';
16664 B : Character := 'A';
16666 X : Short_Integer := 3;
16668 for Y'Address use X'Address;
16669 pragma Import (Ada, Y);
16670 end Overwrite_Record;
16674 Note that the use of @code{pragma Initialize_Scalars} may cause variables to
16675 be initialized when they would not otherwise have been in the absence
16676 of the use of this pragma. This may cause an overlay to have this
16677 unintended clobbering effect. The compiler avoids this for scalar
16678 types, but not for composite objects (where in general the effect
16679 of @code{Initialize_Scalars} is part of the initialization routine
16680 for the composite object:
16682 @smallexample @c ada
16683 pragma Initialize_Scalars;
16684 with Ada.Text_IO; use Ada.Text_IO;
16685 procedure Overwrite_Array is
16686 type Arr is array (1 .. 5) of Integer;
16687 X : Arr := (others => 1);
16689 for A'Address use X'Address;
16691 >>> warning: default initialization of "A" may
16692 modify "X", use pragma Import for "A" to
16693 suppress initialization (RM B.1(24))
16696 if X /= Arr'(others => 1) then
16697 Put_Line ("X was clobbered");
16699 Put_Line ("X was not clobbered");
16701 end Overwrite_Array;
16705 The above program generates the warning as shown, and at execution
16706 time, prints @code{X was clobbered}. If the @code{pragma Import} is
16707 added as suggested:
16709 @smallexample @c ada
16710 pragma Initialize_Scalars;
16711 with Ada.Text_IO; use Ada.Text_IO;
16712 procedure Overwrite_Array is
16713 type Arr is array (1 .. 5) of Integer;
16714 X : Arr := (others => 1);
16716 for A'Address use X'Address;
16717 pragma Import (Ada, A);
16719 if X /= Arr'(others => 1) then
16720 Put_Line ("X was clobbered");
16722 Put_Line ("X was not clobbered");
16724 end Overwrite_Array;
16728 then the program compiles without the warning and when run will generate
16729 the output @code{X was not clobbered}.
16731 @node Use of Address Clauses for Memory-Mapped I/O
16732 @section Use of Address Clauses for Memory-Mapped I/O
16733 @cindex Memory-mapped I/O
16735 A common pattern is to use an address clause to map an atomic variable to
16736 a location in memory that corresponds to a memory-mapped I/O operation or
16737 operations, for example:
16739 @smallexample @c ada
16740 type Mem_Word is record
16743 pragma Atomic (Mem_Word);
16744 for Mem_Word_Size use 32;
16747 for Mem'Address use some-address;
16755 For a full access (reference or modification) of the variable (Mem) in
16756 this case, as in the above examples, GNAT guarantees that the entire atomic
16757 word will be accessed. It is not clear whether the RM requires this. For
16758 example in the above, can the compiler reference only the Mem.A field as
16759 an optimization? Whatever the answer to this question is, GNAT makes the
16760 guarantee that for such a reference, the entire word is read or written.
16762 A problem arises with a component access such as:
16764 @smallexample @c ada
16769 Note that the component A is not declared as atomic. This means that it is
16770 not clear what this assignment means. It could correspond to full word read
16771 and write as given in the first example, or on architectures that supported
16772 such an operation it might be a single byte store instruction. The RM does
16773 not have anything to say in this situation, and GNAT does not make any
16774 guarantee. The code generated may vary from target to target. GNAT will issue
16775 a warning in such a case:
16777 @smallexample @c ada
16780 >>> warning: access to non-atomic component of atomic array,
16781 may cause unexpected accesses to atomic object
16785 It is best to be explicit in this situation, by either declaring the
16786 components to be atomic if you want the byte store, or explicitly writing
16787 the full word access sequence if that is what the hardware requires.
16789 @node Effect of Convention on Representation
16790 @section Effect of Convention on Representation
16791 @cindex Convention, effect on representation
16794 Normally the specification of a foreign language convention for a type or
16795 an object has no effect on the chosen representation. In particular, the
16796 representation chosen for data in GNAT generally meets the standard system
16797 conventions, and for example records are laid out in a manner that is
16798 consistent with C@. This means that specifying convention C (for example)
16801 There are four exceptions to this general rule:
16805 @item Convention Fortran and array subtypes
16806 If pragma Convention Fortran is specified for an array subtype, then in
16807 accordance with the implementation advice in section 3.6.2(11) of the
16808 Ada Reference Manual, the array will be stored in a Fortran-compatible
16809 column-major manner, instead of the normal default row-major order.
16811 @item Convention C and enumeration types
16812 GNAT normally stores enumeration types in 8, 16, or 32 bits as required
16813 to accommodate all values of the type. For example, for the enumeration
16816 @smallexample @c ada
16817 type Color is (Red, Green, Blue);
16821 8 bits is sufficient to store all values of the type, so by default, objects
16822 of type @code{Color} will be represented using 8 bits. However, normal C
16823 convention is to use 32 bits for all enum values in C, since enum values
16824 are essentially of type int. If pragma @code{Convention C} is specified for an
16825 Ada enumeration type, then the size is modified as necessary (usually to
16826 32 bits) to be consistent with the C convention for enum values.
16828 Note that this treatment applies only to types. If Convention C is given for
16829 an enumeration object, where the enumeration type is not Convention C, then
16830 Object_Size bits are allocated. For example, for a normal enumeration type,
16831 with less than 256 elements, only 8 bits will be allocated for the object.
16832 Since this may be a surprise in terms of what C expects, GNAT will issue a
16833 warning in this situation. The warning can be suppressed by giving an explicit
16834 size clause specifying the desired size.
16836 @item Convention C/Fortran and Boolean types
16837 In C, the usual convention for boolean values, that is values used for
16838 conditions, is that zero represents false, and nonzero values represent
16839 true. In Ada, the normal convention is that two specific values, typically
16840 0/1, are used to represent false/true respectively.
16842 Fortran has a similar convention for @code{LOGICAL} values (any nonzero
16843 value represents true).
16845 To accommodate the Fortran and C conventions, if a pragma Convention specifies
16846 C or Fortran convention for a derived Boolean, as in the following example:
16848 @smallexample @c ada
16849 type C_Switch is new Boolean;
16850 pragma Convention (C, C_Switch);
16854 then the GNAT generated code will treat any nonzero value as true. For truth
16855 values generated by GNAT, the conventional value 1 will be used for True, but
16856 when one of these values is read, any nonzero value is treated as True.
16858 @item Access types on OpenVMS
16859 For 64-bit OpenVMS systems, access types (other than those for unconstrained
16860 arrays) are 64-bits long. An exception to this rule is for the case of
16861 C-convention access types where there is no explicit size clause present (or
16862 inherited for derived types). In this case, GNAT chooses to make these
16863 pointers 32-bits, which provides an easier path for migration of 32-bit legacy
16864 code. size clause specifying 64-bits must be used to obtain a 64-bit pointer.
16868 @node Conventions and Anonymous Access Types
16869 @section Conventions and Anonymous Access Types
16870 @cindex Anonymous access types
16871 @cindex Convention for anonymous access types
16873 The RM is not entirely clear on convention handling in a number of cases,
16874 and in particular, it is not clear on the convention to be given to
16875 anonymous access types in general, and in particular what is to be
16876 done for the case of anonymous access-to-subprogram.
16878 In GNAT, we decide that if an explicit Convention is applied
16879 to an object or component, and its type is such an anonymous type,
16880 then the convention will apply to this anonymous type as well. This
16881 seems to make sense since it is anomolous in any case to have a
16882 different convention for an object and its type, and there is clearly
16883 no way to explicitly specify a convention for an anonymous type, since
16884 it doesn't have a name to specify!
16886 Furthermore, we decide that if a convention is applied to a record type,
16887 then this convention is inherited by any of its components that are of an
16888 anonymous access type which do not have an explicitly specified convention.
16890 The following program shows these conventions in action:
16892 @smallexample @c ada
16893 package ConvComp is
16894 type Foo is range 1 .. 10;
16896 A : access function (X : Foo) return Integer;
16899 pragma Convention (C, T1);
16902 A : access function (X : Foo) return Integer;
16903 pragma Convention (C, A);
16906 pragma Convention (COBOL, T2);
16909 A : access function (X : Foo) return Integer;
16910 pragma Convention (COBOL, A);
16913 pragma Convention (C, T3);
16916 A : access function (X : Foo) return Integer;
16919 pragma Convention (COBOL, T4);
16921 function F (X : Foo) return Integer;
16922 pragma Convention (C, F);
16924 function F (X : Foo) return Integer is (13);
16926 TV1 : T1 := (F'Access, 12); -- OK
16927 TV2 : T2 := (F'Access, 13); -- OK
16929 TV3 : T3 := (F'Access, 13); -- ERROR
16931 >>> subprogram "F" has wrong convention
16932 >>> does not match access to subprogram declared at line 17
16933 38. TV4 : T4 := (F'Access, 13); -- ERROR
16935 >>> subprogram "F" has wrong convention
16936 >>> does not match access to subprogram declared at line 24
16940 @node Determining the Representations chosen by GNAT
16941 @section Determining the Representations chosen by GNAT
16942 @cindex Representation, determination of
16943 @cindex @option{-gnatR} switch
16946 Although the descriptions in this section are intended to be complete, it is
16947 often easier to simply experiment to see what GNAT accepts and what the
16948 effect is on the layout of types and objects.
16950 As required by the Ada RM, if a representation clause is not accepted, then
16951 it must be rejected as illegal by the compiler. However, when a
16952 representation clause or pragma is accepted, there can still be questions
16953 of what the compiler actually does. For example, if a partial record
16954 representation clause specifies the location of some components and not
16955 others, then where are the non-specified components placed? Or if pragma
16956 @code{Pack} is used on a record, then exactly where are the resulting
16957 fields placed? The section on pragma @code{Pack} in this chapter can be
16958 used to answer the second question, but it is often easier to just see
16959 what the compiler does.
16961 For this purpose, GNAT provides the option @option{-gnatR}. If you compile
16962 with this option, then the compiler will output information on the actual
16963 representations chosen, in a format similar to source representation
16964 clauses. For example, if we compile the package:
16966 @smallexample @c ada
16968 type r (x : boolean) is tagged record
16970 when True => S : String (1 .. 100);
16971 when False => null;
16975 type r2 is new r (false) with record
16980 y2 at 16 range 0 .. 31;
16987 type x1 is array (1 .. 10) of x;
16988 for x1'component_size use 11;
16990 type ia is access integer;
16992 type Rb1 is array (1 .. 13) of Boolean;
16995 type Rb2 is array (1 .. 65) of Boolean;
17011 using the switch @option{-gnatR} we obtain the following output:
17014 Representation information for unit q
17015 -------------------------------------
17018 for r'Alignment use 4;
17020 x at 4 range 0 .. 7;
17021 _tag at 0 range 0 .. 31;
17022 s at 5 range 0 .. 799;
17025 for r2'Size use 160;
17026 for r2'Alignment use 4;
17028 x at 4 range 0 .. 7;
17029 _tag at 0 range 0 .. 31;
17030 _parent at 0 range 0 .. 63;
17031 y2 at 16 range 0 .. 31;
17035 for x'Alignment use 1;
17037 y at 0 range 0 .. 7;
17040 for x1'Size use 112;
17041 for x1'Alignment use 1;
17042 for x1'Component_Size use 11;
17044 for rb1'Size use 13;
17045 for rb1'Alignment use 2;
17046 for rb1'Component_Size use 1;
17048 for rb2'Size use 72;
17049 for rb2'Alignment use 1;
17050 for rb2'Component_Size use 1;
17052 for x2'Size use 224;
17053 for x2'Alignment use 4;
17055 l1 at 0 range 0 .. 0;
17056 l2 at 0 range 1 .. 64;
17057 l3 at 12 range 0 .. 31;
17058 l4 at 16 range 0 .. 0;
17059 l5 at 16 range 1 .. 13;
17060 l6 at 18 range 0 .. 71;
17065 The Size values are actually the Object_Size, i.e.@: the default size that
17066 will be allocated for objects of the type.
17067 The ?? size for type r indicates that we have a variant record, and the
17068 actual size of objects will depend on the discriminant value.
17070 The Alignment values show the actual alignment chosen by the compiler
17071 for each record or array type.
17073 The record representation clause for type r shows where all fields
17074 are placed, including the compiler generated tag field (whose location
17075 cannot be controlled by the programmer).
17077 The record representation clause for the type extension r2 shows all the
17078 fields present, including the parent field, which is a copy of the fields
17079 of the parent type of r2, i.e.@: r1.
17081 The component size and size clauses for types rb1 and rb2 show
17082 the exact effect of pragma @code{Pack} on these arrays, and the record
17083 representation clause for type x2 shows how pragma @code{Pack} affects
17086 In some cases, it may be useful to cut and paste the representation clauses
17087 generated by the compiler into the original source to fix and guarantee
17088 the actual representation to be used.
17090 @node Standard Library Routines
17091 @chapter Standard Library Routines
17094 The Ada Reference Manual contains in Annex A a full description of an
17095 extensive set of standard library routines that can be used in any Ada
17096 program, and which must be provided by all Ada compilers. They are
17097 analogous to the standard C library used by C programs.
17099 GNAT implements all of the facilities described in annex A, and for most
17100 purposes the description in the Ada Reference Manual, or appropriate Ada
17101 text book, will be sufficient for making use of these facilities.
17103 In the case of the input-output facilities,
17104 @xref{The Implementation of Standard I/O},
17105 gives details on exactly how GNAT interfaces to the
17106 file system. For the remaining packages, the Ada Reference Manual
17107 should be sufficient. The following is a list of the packages included,
17108 together with a brief description of the functionality that is provided.
17110 For completeness, references are included to other predefined library
17111 routines defined in other sections of the Ada Reference Manual (these are
17112 cross-indexed from Annex A). For further details see the relevant
17113 package declarations in the run-time library. In particular, a few units
17114 are not implemented, as marked by the presence of pragma Unimplemented_Unit,
17115 and in this case the package declaration contains comments explaining why
17116 the unit is not implemented.
17120 This is a parent package for all the standard library packages. It is
17121 usually included implicitly in your program, and itself contains no
17122 useful data or routines.
17124 @item Ada.Assertions (11.4.2)
17125 @code{Assertions} provides the @code{Assert} subprograms, and also
17126 the declaration of the @code{Assertion_Error} exception.
17128 @item Ada.Asynchronous_Task_Control (D.11)
17129 @code{Asynchronous_Task_Control} provides low level facilities for task
17130 synchronization. It is typically not implemented. See package spec for details.
17132 @item Ada.Calendar (9.6)
17133 @code{Calendar} provides time of day access, and routines for
17134 manipulating times and durations.
17136 @item Ada.Calendar.Arithmetic (9.6.1)
17137 This package provides additional arithmetic
17138 operations for @code{Calendar}.
17140 @item Ada.Calendar.Formatting (9.6.1)
17141 This package provides formatting operations for @code{Calendar}.
17143 @item Ada.Calendar.Time_Zones (9.6.1)
17144 This package provides additional @code{Calendar} facilities
17145 for handling time zones.
17147 @item Ada.Characters (A.3.1)
17148 This is a dummy parent package that contains no useful entities
17150 @item Ada.Characters.Conversions (A.3.2)
17151 This package provides character conversion functions.
17153 @item Ada.Characters.Handling (A.3.2)
17154 This package provides some basic character handling capabilities,
17155 including classification functions for classes of characters (e.g.@: test
17156 for letters, or digits).
17158 @item Ada.Characters.Latin_1 (A.3.3)
17159 This package includes a complete set of definitions of the characters
17160 that appear in type CHARACTER@. It is useful for writing programs that
17161 will run in international environments. For example, if you want an
17162 upper case E with an acute accent in a string, it is often better to use
17163 the definition of @code{UC_E_Acute} in this package. Then your program
17164 will print in an understandable manner even if your environment does not
17165 support these extended characters.
17167 @item Ada.Command_Line (A.15)
17168 This package provides access to the command line parameters and the name
17169 of the current program (analogous to the use of @code{argc} and @code{argv}
17170 in C), and also allows the exit status for the program to be set in a
17171 system-independent manner.
17173 @item Ada.Complex_Text_IO (G.1.3)
17174 This package provides text input and output of complex numbers.
17176 @item Ada.Containers (A.18.1)
17177 A top level package providing a few basic definitions used by all the
17178 following specific child packages that provide specific kinds of
17181 @item Ada.Containers.Bounded_Priority_Queues (A.18.31)
17183 @item Ada.Containers.Bounded_Synchronized_Queues (A.18.29)
17185 @item Ada.Containers.Doubly_Linked_Lists (A.18.3)
17187 @item Ada.Containers.Generic_Array_Sort (A.18.26)
17189 @item Ada.Containers.Generic_Constrained_Array_Sort (A.18.26)
17191 @item Ada.Containers.Generic_Sort (A.18.26)
17193 @item Ada.Containers.Hashed_Maps (A.18.5)
17195 @item Ada.Containers.Hashed_Sets (A.18.8)
17197 @item Ada.Containers.Indefinite_Doubly_Linked_Lists (A.18.12)
17199 @item Ada.Containers.Indefinite_Hashed_Maps (A.18.13)
17201 @item Ada.Containers.Indefinite_Hashed_Sets (A.18.15)
17203 @item Ada.Containers.Indefinite_Holders (A.18.18)
17205 @item Ada.Containers.Indefinite_Multiway_Trees (A.18.17)
17207 @item Ada.Containers.Indefinite_Ordered_Maps (A.18.14)
17209 @item Ada.Containers.Indefinite_Ordered_Sets (A.18.16)
17211 @item Ada.Containers.Indefinite_Vectors (A.18.11)
17213 @item Ada.Containers.Multiway_Trees (A.18.10)
17215 @item Ada.Containers.Ordered_Maps (A.18.6)
17217 @item Ada.Containers.Ordered_Sets (A.18.9)
17219 @item Ada.Containers.Synchronized_Queue_Interfaces (A.18.27)
17221 @item Ada.Containers.Unbounded_Priority_Queues (A.18.30)
17223 @item Ada.Containers.Unbounded_Synchronized_Queues (A.18.28)
17225 @item Ada.Containers.Vectors (A.18.2)
17227 @item Ada.Directories (A.16)
17228 This package provides operations on directories.
17230 @item Ada.Directories.Hierarchical_File_Names (A.16.1)
17231 This package provides additional directory operations handling
17232 hiearchical file names.
17234 @item Ada.Directories.Information (A.16)
17235 This is an implementation defined package for additional directory
17236 operations, which is not implemented in GNAT.
17238 @item Ada.Decimal (F.2)
17239 This package provides constants describing the range of decimal numbers
17240 implemented, and also a decimal divide routine (analogous to the COBOL
17241 verb DIVIDE @dots{} GIVING @dots{} REMAINDER @dots{})
17243 @item Ada.Direct_IO (A.8.4)
17244 This package provides input-output using a model of a set of records of
17245 fixed-length, containing an arbitrary definite Ada type, indexed by an
17246 integer record number.
17248 @item Ada.Dispatching (D.2.1)
17249 A parent package containing definitions for task dispatching operations.
17251 @item Ada.Dispatching.EDF (D.2.6)
17252 Not implemented in GNAT.
17254 @item Ada.Dispatching.Non_Preemptive (D.2.4)
17255 Not implemented in GNAT.
17257 @item Ada.Dispatching.Round_Robin (D.2.5)
17258 Not implemented in GNAT.
17260 @item Ada.Dynamic_Priorities (D.5)
17261 This package allows the priorities of a task to be adjusted dynamically
17262 as the task is running.
17264 @item Ada.Environment_Variables (A.17)
17265 This package provides facilities for accessing environment variables.
17267 @item Ada.Exceptions (11.4.1)
17268 This package provides additional information on exceptions, and also
17269 contains facilities for treating exceptions as data objects, and raising
17270 exceptions with associated messages.
17272 @item Ada.Execution_Time (D.14)
17273 Not implemented in GNAT.
17275 @item Ada.Execution_Time.Group_Budgets (D.14.2)
17276 Not implemented in GNAT.
17278 @item Ada.Execution_Time.Timers (D.14.1)'
17279 Not implemented in GNAT.
17281 @item Ada.Finalization (7.6)
17282 This package contains the declarations and subprograms to support the
17283 use of controlled types, providing for automatic initialization and
17284 finalization (analogous to the constructors and destructors of C++).
17286 @item Ada.Float_Text_IO (A.10.9)
17287 A library level instantiation of Text_IO.Float_IO for type Float.
17289 @item Ada.Float_Wide_Text_IO (A.10.9)
17290 A library level instantiation of Wide_Text_IO.Float_IO for type Float.
17292 @item Ada.Float_Wide_Wide_Text_IO (A.10.9)
17293 A library level instantiation of Wide_Wide_Text_IO.Float_IO for type Float.
17295 @item Ada.Integer_Text_IO (A.10.9)
17296 A library level instantiation of Text_IO.Integer_IO for type Integer.
17298 @item Ada.Integer_Wide_Text_IO (A.10.9)
17299 A library level instantiation of Wide_Text_IO.Integer_IO for type Integer.
17301 @item Ada.Integer_Wide_Wide_Text_IO (A.10.9)
17302 A library level instantiation of Wide_Wide_Text_IO.Integer_IO for type Integer.
17304 @item Ada.Interrupts (C.3.2)
17305 This package provides facilities for interfacing to interrupts, which
17306 includes the set of signals or conditions that can be raised and
17307 recognized as interrupts.
17309 @item Ada.Interrupts.Names (C.3.2)
17310 This package provides the set of interrupt names (actually signal
17311 or condition names) that can be handled by GNAT@.
17313 @item Ada.IO_Exceptions (A.13)
17314 This package defines the set of exceptions that can be raised by use of
17315 the standard IO packages.
17317 @item Ada.Iterator_Interfaces (5.5.1)
17318 This package provides a generic interface to generalized iterators.
17320 @item Ada.Locales (A.19)
17321 This package provides declarations providing information (Language
17322 and Country) about the current locale.
17325 This package contains some standard constants and exceptions used
17326 throughout the numerics packages. Note that the constants pi and e are
17327 defined here, and it is better to use these definitions than rolling
17330 @item Ada.Numerics.Complex_Arrays (G.3.2)
17331 Provides operations on arrays of complex numbers.
17333 @item Ada.Numerics.Complex_Elementary_Functions
17334 Provides the implementation of standard elementary functions (such as
17335 log and trigonometric functions) operating on complex numbers using the
17336 standard @code{Float} and the @code{Complex} and @code{Imaginary} types
17337 created by the package @code{Numerics.Complex_Types}.
17339 @item Ada.Numerics.Complex_Types
17340 This is a predefined instantiation of
17341 @code{Numerics.Generic_Complex_Types} using @code{Standard.Float} to
17342 build the type @code{Complex} and @code{Imaginary}.
17344 @item Ada.Numerics.Discrete_Random
17345 This generic package provides a random number generator suitable for generating
17346 uniformly distributed values of a specified discrete subtype.
17348 @item Ada.Numerics.Float_Random
17349 This package provides a random number generator suitable for generating
17350 uniformly distributed floating point values in the unit interval.
17352 @item Ada.Numerics.Generic_Complex_Elementary_Functions
17353 This is a generic version of the package that provides the
17354 implementation of standard elementary functions (such as log and
17355 trigonometric functions) for an arbitrary complex type.
17357 The following predefined instantiations of this package are provided:
17361 @code{Ada.Numerics.Short_Complex_Elementary_Functions}
17363 @code{Ada.Numerics.Complex_Elementary_Functions}
17365 @code{Ada.Numerics.Long_Complex_Elementary_Functions}
17368 @item Ada.Numerics.Generic_Complex_Types
17369 This is a generic package that allows the creation of complex types,
17370 with associated complex arithmetic operations.
17372 The following predefined instantiations of this package exist
17375 @code{Ada.Numerics.Short_Complex_Complex_Types}
17377 @code{Ada.Numerics.Complex_Complex_Types}
17379 @code{Ada.Numerics.Long_Complex_Complex_Types}
17382 @item Ada.Numerics.Generic_Elementary_Functions
17383 This is a generic package that provides the implementation of standard
17384 elementary functions (such as log an trigonometric functions) for an
17385 arbitrary float type.
17387 The following predefined instantiations of this package exist
17391 @code{Ada.Numerics.Short_Elementary_Functions}
17393 @code{Ada.Numerics.Elementary_Functions}
17395 @code{Ada.Numerics.Long_Elementary_Functions}
17398 @item Ada.Numerics.Generic_Real_Arrays (G.3.1)
17399 Generic operations on arrays of reals
17401 @item Ada.Numerics.Real_Arrays (G.3.1)
17402 Preinstantiation of Ada.Numerics.Generic_Real_Arrays (Float).
17404 @item Ada.Real_Time (D.8)
17405 This package provides facilities similar to those of @code{Calendar}, but
17406 operating with a finer clock suitable for real time control. Note that
17407 annex D requires that there be no backward clock jumps, and GNAT generally
17408 guarantees this behavior, but of course if the external clock on which
17409 the GNAT runtime depends is deliberately reset by some external event,
17410 then such a backward jump may occur.
17412 @item Ada.Real_Time.Timing_Events (D.15)
17413 Not implemented in GNAT.
17415 @item Ada.Sequential_IO (A.8.1)
17416 This package provides input-output facilities for sequential files,
17417 which can contain a sequence of values of a single type, which can be
17418 any Ada type, including indefinite (unconstrained) types.
17420 @item Ada.Storage_IO (A.9)
17421 This package provides a facility for mapping arbitrary Ada types to and
17422 from a storage buffer. It is primarily intended for the creation of new
17425 @item Ada.Streams (13.13.1)
17426 This is a generic package that provides the basic support for the
17427 concept of streams as used by the stream attributes (@code{Input},
17428 @code{Output}, @code{Read} and @code{Write}).
17430 @item Ada.Streams.Stream_IO (A.12.1)
17431 This package is a specialization of the type @code{Streams} defined in
17432 package @code{Streams} together with a set of operations providing
17433 Stream_IO capability. The Stream_IO model permits both random and
17434 sequential access to a file which can contain an arbitrary set of values
17435 of one or more Ada types.
17437 @item Ada.Strings (A.4.1)
17438 This package provides some basic constants used by the string handling
17441 @item Ada.Strings.Bounded (A.4.4)
17442 This package provides facilities for handling variable length
17443 strings. The bounded model requires a maximum length. It is thus
17444 somewhat more limited than the unbounded model, but avoids the use of
17445 dynamic allocation or finalization.
17447 @item Ada.Strings.Bounded.Equal_Case_Insensitive (A.4.10)
17448 Provides case-insensitive comparisons of bounded strings
17450 @item Ada.Strings.Bounded.Hash (A.4.9)
17451 This package provides a generic hash function for bounded strings
17453 @item Ada.Strings.Bounded.Hash_Case_Insensitive (A.4.9)
17454 This package provides a generic hash function for bounded strings that
17455 converts the string to be hashed to lower case.
17457 @item Ada.Strings.Bounded.Less_Case_Insensitive (A.4.10)
17458 This package provides a comparison function for bounded strings that works
17459 in a case insensitive manner by converting to lower case before the comparison.
17461 @item Ada.Strings.Fixed (A.4.3)
17462 This package provides facilities for handling fixed length strings.
17464 @item Ada.Strings.Fixed.Equal_Case_Insensitive (A.4.10)
17465 This package provides an equality function for fixed strings that compares
17466 the strings after converting both to lower case.
17468 @item Ada.Strings.Fixed.Hash_Case_Insensitive (A.4.9)
17469 This package provides a case insensitive hash function for fixed strings that
17470 converts the string to lower case before computing the hash.
17472 @item Ada.Strings.Fixed.Less_Case_Insensitive (A.4.10)
17473 This package provides a comparison function for fixed strings that works
17474 in a case insensitive manner by converting to lower case before the comparison.
17476 Ada.Strings.Hash (A.4.9)
17477 This package provides a hash function for strings.
17479 Ada.Strings.Hash_Case_Insensitive (A.4.9)
17480 This package provides a hash function for strings that is case insensitive.
17481 The string is converted to lower case before computing the hash.
17483 @item Ada.Strings.Less_Case_Insensitive (A.4.10)
17484 This package provides a comparison function for\strings that works
17485 in a case insensitive manner by converting to lower case before the comparison.
17487 @item Ada.Strings.Maps (A.4.2)
17488 This package provides facilities for handling character mappings and
17489 arbitrarily defined subsets of characters. For instance it is useful in
17490 defining specialized translation tables.
17492 @item Ada.Strings.Maps.Constants (A.4.6)
17493 This package provides a standard set of predefined mappings and
17494 predefined character sets. For example, the standard upper to lower case
17495 conversion table is found in this package. Note that upper to lower case
17496 conversion is non-trivial if you want to take the entire set of
17497 characters, including extended characters like E with an acute accent,
17498 into account. You should use the mappings in this package (rather than
17499 adding 32 yourself) to do case mappings.
17501 @item Ada.Strings.Unbounded (A.4.5)
17502 This package provides facilities for handling variable length
17503 strings. The unbounded model allows arbitrary length strings, but
17504 requires the use of dynamic allocation and finalization.
17506 @item Ada.Strings.Unbounded.Equal_Case_Insensitive (A.4.10)
17507 Provides case-insensitive comparisons of unbounded strings
17509 @item Ada.Strings.Unbounded.Hash (A.4.9)
17510 This package provides a generic hash function for unbounded strings
17512 @item Ada.Strings.Unbounded.Hash_Case_Insensitive (A.4.9)
17513 This package provides a generic hash function for unbounded strings that
17514 converts the string to be hashed to lower case.
17516 @item Ada.Strings.Unbounded.Less_Case_Insensitive (A.4.10)
17517 This package provides a comparison function for unbounded strings that works
17518 in a case insensitive manner by converting to lower case before the comparison.
17520 @item Ada.Strings.UTF_Encoding (A.4.11)
17521 This package provides basic definitions for dealing with UTF-encoded strings.
17523 @item Ada.Strings.UTF_Encoding.Conversions (A.4.11)
17524 This package provides conversion functions for UTF-encoded strings.
17526 @item Ada.Strings.UTF_Encoding.Strings (A.4.11)
17527 @itemx Ada.Strings.UTF_Encoding.Wide_Strings (A.4.11)
17528 @itemx Ada.Strings.UTF_Encoding.Wide_Wide_Strings (A.4.11)
17529 These packages provide facilities for handling UTF encodings for
17530 Strings, Wide_Strings and Wide_Wide_Strings.
17532 @item Ada.Strings.Wide_Bounded (A.4.7)
17533 @itemx Ada.Strings.Wide_Fixed (A.4.7)
17534 @itemx Ada.Strings.Wide_Maps (A.4.7)
17535 @itemx Ada.Strings.Wide_Unbounded (A.4.7)
17536 These packages provide analogous capabilities to the corresponding
17537 packages without @samp{Wide_} in the name, but operate with the types
17538 @code{Wide_String} and @code{Wide_Character} instead of @code{String}
17539 and @code{Character}. Versions of all the child packages are available.
17541 @item Ada.Strings.Wide_Wide_Bounded (A.4.7)
17542 @itemx Ada.Strings.Wide_Wide_Fixed (A.4.7)
17543 @itemx Ada.Strings.Wide_Wide_Maps (A.4.7)
17544 @itemx Ada.Strings.Wide_Wide_Unbounded (A.4.7)
17545 These packages provide analogous capabilities to the corresponding
17546 packages without @samp{Wide_} in the name, but operate with the types
17547 @code{Wide_Wide_String} and @code{Wide_Wide_Character} instead
17548 of @code{String} and @code{Character}.
17550 @item Ada.Synchronous_Barriers (D.10.1)
17551 This package provides facilities for synchronizing tasks at a low level
17554 @item Ada.Synchronous_Task_Control (D.10)
17555 This package provides some standard facilities for controlling task
17556 communication in a synchronous manner.
17558 @item Ada.Synchronous_Task_Control.EDF (D.10)
17559 Not implemented in GNAT.
17562 This package contains definitions for manipulation of the tags of tagged
17565 @item Ada.Tags.Generic_Dispatching_Constructor (3.9)
17566 This package provides a way of constructing tagged class-wide values given
17567 only the tag value.
17569 @item Ada.Task_Attributes (C.7.2)
17570 This package provides the capability of associating arbitrary
17571 task-specific data with separate tasks.
17573 @item Ada.Task_Identifification (C.7.1)
17574 This package provides capabilities for task identification.
17576 @item Ada.Task_Termination (C.7.3)
17577 This package provides control over task termination.
17580 This package provides basic text input-output capabilities for
17581 character, string and numeric data. The subpackages of this
17582 package are listed next. Note that although these are defined
17583 as subpackages in the RM, they are actually transparently
17584 implemented as child packages in GNAT, meaning that they
17585 are only loaded if needed.
17587 @item Ada.Text_IO.Decimal_IO
17588 Provides input-output facilities for decimal fixed-point types
17590 @item Ada.Text_IO.Enumeration_IO
17591 Provides input-output facilities for enumeration types.
17593 @item Ada.Text_IO.Fixed_IO
17594 Provides input-output facilities for ordinary fixed-point types.
17596 @item Ada.Text_IO.Float_IO
17597 Provides input-output facilities for float types. The following
17598 predefined instantiations of this generic package are available:
17602 @code{Short_Float_Text_IO}
17604 @code{Float_Text_IO}
17606 @code{Long_Float_Text_IO}
17609 @item Ada.Text_IO.Integer_IO
17610 Provides input-output facilities for integer types. The following
17611 predefined instantiations of this generic package are available:
17614 @item Short_Short_Integer
17615 @code{Ada.Short_Short_Integer_Text_IO}
17616 @item Short_Integer
17617 @code{Ada.Short_Integer_Text_IO}
17619 @code{Ada.Integer_Text_IO}
17621 @code{Ada.Long_Integer_Text_IO}
17622 @item Long_Long_Integer
17623 @code{Ada.Long_Long_Integer_Text_IO}
17626 @item Ada.Text_IO.Modular_IO
17627 Provides input-output facilities for modular (unsigned) types.
17629 @item Ada.Text_IO.Bounded_IO (A.10.11)
17630 Provides input-output facilities for bounded strings.
17632 @item Ada.Text_IO.Complex_IO (G.1.3)
17633 This package provides basic text input-output capabilities for complex
17636 @item Ada.Text_IO.Editing (F.3.3)
17637 This package contains routines for edited output, analogous to the use
17638 of pictures in COBOL@. The picture formats used by this package are a
17639 close copy of the facility in COBOL@.
17641 @item Ada.Text_IO.Text_Streams (A.12.2)
17642 This package provides a facility that allows Text_IO files to be treated
17643 as streams, so that the stream attributes can be used for writing
17644 arbitrary data, including binary data, to Text_IO files.
17646 @item Ada.Text_IO.Unbounded_IO (A.10.12)
17647 This package provides input-output facilities for unbounded strings.
17649 @item Ada.Unchecked_Conversion (13.9)
17650 This generic package allows arbitrary conversion from one type to
17651 another of the same size, providing for breaking the type safety in
17652 special circumstances.
17654 If the types have the same Size (more accurately the same Value_Size),
17655 then the effect is simply to transfer the bits from the source to the
17656 target type without any modification. This usage is well defined, and
17657 for simple types whose representation is typically the same across
17658 all implementations, gives a portable method of performing such
17661 If the types do not have the same size, then the result is implementation
17662 defined, and thus may be non-portable. The following describes how GNAT
17663 handles such unchecked conversion cases.
17665 If the types are of different sizes, and are both discrete types, then
17666 the effect is of a normal type conversion without any constraint checking.
17667 In particular if the result type has a larger size, the result will be
17668 zero or sign extended. If the result type has a smaller size, the result
17669 will be truncated by ignoring high order bits.
17671 If the types are of different sizes, and are not both discrete types,
17672 then the conversion works as though pointers were created to the source
17673 and target, and the pointer value is converted. The effect is that bits
17674 are copied from successive low order storage units and bits of the source
17675 up to the length of the target type.
17677 A warning is issued if the lengths differ, since the effect in this
17678 case is implementation dependent, and the above behavior may not match
17679 that of some other compiler.
17681 A pointer to one type may be converted to a pointer to another type using
17682 unchecked conversion. The only case in which the effect is undefined is
17683 when one or both pointers are pointers to unconstrained array types. In
17684 this case, the bounds information may get incorrectly transferred, and in
17685 particular, GNAT uses double size pointers for such types, and it is
17686 meaningless to convert between such pointer types. GNAT will issue a
17687 warning if the alignment of the target designated type is more strict
17688 than the alignment of the source designated type (since the result may
17689 be unaligned in this case).
17691 A pointer other than a pointer to an unconstrained array type may be
17692 converted to and from System.Address. Such usage is common in Ada 83
17693 programs, but note that Ada.Address_To_Access_Conversions is the
17694 preferred method of performing such conversions in Ada 95 and Ada 2005.
17696 unchecked conversion nor Ada.Address_To_Access_Conversions should be
17697 used in conjunction with pointers to unconstrained objects, since
17698 the bounds information cannot be handled correctly in this case.
17700 @item Ada.Unchecked_Deallocation (13.11.2)
17701 This generic package allows explicit freeing of storage previously
17702 allocated by use of an allocator.
17704 @item Ada.Wide_Text_IO (A.11)
17705 This package is similar to @code{Ada.Text_IO}, except that the external
17706 file supports wide character representations, and the internal types are
17707 @code{Wide_Character} and @code{Wide_String} instead of @code{Character}
17708 and @code{String}. The corresponding set of nested packages and child
17709 packages are defined.
17711 @item Ada.Wide_Wide_Text_IO (A.11)
17712 This package is similar to @code{Ada.Text_IO}, except that the external
17713 file supports wide character representations, and the internal types are
17714 @code{Wide_Character} and @code{Wide_String} instead of @code{Character}
17715 and @code{String}. The corresponding set of nested packages and child
17716 packages are defined.
17720 For packages in Interfaces and System, all the RM defined packages are
17721 available in GNAT, see the Ada 2012 RM for full details.
17723 @node The Implementation of Standard I/O
17724 @chapter The Implementation of Standard I/O
17727 GNAT implements all the required input-output facilities described in
17728 A.6 through A.14. These sections of the Ada Reference Manual describe the
17729 required behavior of these packages from the Ada point of view, and if
17730 you are writing a portable Ada program that does not need to know the
17731 exact manner in which Ada maps to the outside world when it comes to
17732 reading or writing external files, then you do not need to read this
17733 chapter. As long as your files are all regular files (not pipes or
17734 devices), and as long as you write and read the files only from Ada, the
17735 description in the Ada Reference Manual is sufficient.
17737 However, if you want to do input-output to pipes or other devices, such
17738 as the keyboard or screen, or if the files you are dealing with are
17739 either generated by some other language, or to be read by some other
17740 language, then you need to know more about the details of how the GNAT
17741 implementation of these input-output facilities behaves.
17743 In this chapter we give a detailed description of exactly how GNAT
17744 interfaces to the file system. As always, the sources of the system are
17745 available to you for answering questions at an even more detailed level,
17746 but for most purposes the information in this chapter will suffice.
17748 Another reason that you may need to know more about how input-output is
17749 implemented arises when you have a program written in mixed languages
17750 where, for example, files are shared between the C and Ada sections of
17751 the same program. GNAT provides some additional facilities, in the form
17752 of additional child library packages, that facilitate this sharing, and
17753 these additional facilities are also described in this chapter.
17756 * Standard I/O Packages::
17762 * Wide_Wide_Text_IO::
17764 * Text Translation::
17766 * Filenames encoding::
17767 * File content encoding::
17769 * Operations on C Streams::
17770 * Interfacing to C Streams::
17773 @node Standard I/O Packages
17774 @section Standard I/O Packages
17777 The Standard I/O packages described in Annex A for
17783 Ada.Text_IO.Complex_IO
17785 Ada.Text_IO.Text_Streams
17789 Ada.Wide_Text_IO.Complex_IO
17791 Ada.Wide_Text_IO.Text_Streams
17793 Ada.Wide_Wide_Text_IO
17795 Ada.Wide_Wide_Text_IO.Complex_IO
17797 Ada.Wide_Wide_Text_IO.Text_Streams
17807 are implemented using the C
17808 library streams facility; where
17812 All files are opened using @code{fopen}.
17814 All input/output operations use @code{fread}/@code{fwrite}.
17818 There is no internal buffering of any kind at the Ada library level. The only
17819 buffering is that provided at the system level in the implementation of the
17820 library routines that support streams. This facilitates shared use of these
17821 streams by mixed language programs. Note though that system level buffering is
17822 explicitly enabled at elaboration of the standard I/O packages and that can
17823 have an impact on mixed language programs, in particular those using I/O before
17824 calling the Ada elaboration routine (e.g.@: adainit). It is recommended to call
17825 the Ada elaboration routine before performing any I/O or when impractical,
17826 flush the common I/O streams and in particular Standard_Output before
17827 elaborating the Ada code.
17830 @section FORM Strings
17833 The format of a FORM string in GNAT is:
17836 "keyword=value,keyword=value,@dots{},keyword=value"
17840 where letters may be in upper or lower case, and there are no spaces
17841 between values. The order of the entries is not important. Currently
17842 the following keywords defined.
17845 TEXT_TRANSLATION=[YES|NO|TEXT|BINARY|U8TEXT|WTEXT|U16TEXT]
17847 WCEM=[n|h|u|s|e|8|b]
17848 ENCODING=[UTF8|8BITS]
17852 The use of these parameters is described later in this section. If an
17853 unrecognized keyword appears in a form string, it is silently ignored
17854 and not considered invalid.
17857 For OpenVMS additional FORM string keywords are available for use with
17858 RMS services. The syntax is:
17861 VMS_RMS_Keys=(keyword=value,@dots{},keyword=value)
17865 The following RMS keywords and values are currently defined:
17868 Context=Force_Stream_Mode|Force_Record_Mode
17872 VMS RMS keys are silently ignored on non-VMS systems. On OpenVMS
17873 unimplented RMS keywords, values, or invalid syntax will raise Use_Error.
17879 Direct_IO can only be instantiated for definite types. This is a
17880 restriction of the Ada language, which means that the records are fixed
17881 length (the length being determined by @code{@var{type}'Size}, rounded
17882 up to the next storage unit boundary if necessary).
17884 The records of a Direct_IO file are simply written to the file in index
17885 sequence, with the first record starting at offset zero, and subsequent
17886 records following. There is no control information of any kind. For
17887 example, if 32-bit integers are being written, each record takes
17888 4-bytes, so the record at index @var{K} starts at offset
17889 (@var{K}@minus{}1)*4.
17891 There is no limit on the size of Direct_IO files, they are expanded as
17892 necessary to accommodate whatever records are written to the file.
17894 @node Sequential_IO
17895 @section Sequential_IO
17898 Sequential_IO may be instantiated with either a definite (constrained)
17899 or indefinite (unconstrained) type.
17901 For the definite type case, the elements written to the file are simply
17902 the memory images of the data values with no control information of any
17903 kind. The resulting file should be read using the same type, no validity
17904 checking is performed on input.
17906 For the indefinite type case, the elements written consist of two
17907 parts. First is the size of the data item, written as the memory image
17908 of a @code{Interfaces.C.size_t} value, followed by the memory image of
17909 the data value. The resulting file can only be read using the same
17910 (unconstrained) type. Normal assignment checks are performed on these
17911 read operations, and if these checks fail, @code{Data_Error} is
17912 raised. In particular, in the array case, the lengths must match, and in
17913 the variant record case, if the variable for a particular read operation
17914 is constrained, the discriminants must match.
17916 Note that it is not possible to use Sequential_IO to write variable
17917 length array items, and then read the data back into different length
17918 arrays. For example, the following will raise @code{Data_Error}:
17920 @smallexample @c ada
17921 package IO is new Sequential_IO (String);
17926 IO.Write (F, "hello!")
17927 IO.Reset (F, Mode=>In_File);
17934 On some Ada implementations, this will print @code{hell}, but the program is
17935 clearly incorrect, since there is only one element in the file, and that
17936 element is the string @code{hello!}.
17938 In Ada 95 and Ada 2005, this kind of behavior can be legitimately achieved
17939 using Stream_IO, and this is the preferred mechanism. In particular, the
17940 above program fragment rewritten to use Stream_IO will work correctly.
17946 Text_IO files consist of a stream of characters containing the following
17947 special control characters:
17950 LF (line feed, 16#0A#) Line Mark
17951 FF (form feed, 16#0C#) Page Mark
17955 A canonical Text_IO file is defined as one in which the following
17956 conditions are met:
17960 The character @code{LF} is used only as a line mark, i.e.@: to mark the end
17964 The character @code{FF} is used only as a page mark, i.e.@: to mark the
17965 end of a page and consequently can appear only immediately following a
17966 @code{LF} (line mark) character.
17969 The file ends with either @code{LF} (line mark) or @code{LF}-@code{FF}
17970 (line mark, page mark). In the former case, the page mark is implicitly
17971 assumed to be present.
17975 A file written using Text_IO will be in canonical form provided that no
17976 explicit @code{LF} or @code{FF} characters are written using @code{Put}
17977 or @code{Put_Line}. There will be no @code{FF} character at the end of
17978 the file unless an explicit @code{New_Page} operation was performed
17979 before closing the file.
17981 A canonical Text_IO file that is a regular file (i.e., not a device or a
17982 pipe) can be read using any of the routines in Text_IO@. The
17983 semantics in this case will be exactly as defined in the Ada Reference
17984 Manual, and all the routines in Text_IO are fully implemented.
17986 A text file that does not meet the requirements for a canonical Text_IO
17987 file has one of the following:
17991 The file contains @code{FF} characters not immediately following a
17992 @code{LF} character.
17995 The file contains @code{LF} or @code{FF} characters written by
17996 @code{Put} or @code{Put_Line}, which are not logically considered to be
17997 line marks or page marks.
18000 The file ends in a character other than @code{LF} or @code{FF},
18001 i.e.@: there is no explicit line mark or page mark at the end of the file.
18005 Text_IO can be used to read such non-standard text files but subprograms
18006 to do with line or page numbers do not have defined meanings. In
18007 particular, a @code{FF} character that does not follow a @code{LF}
18008 character may or may not be treated as a page mark from the point of
18009 view of page and line numbering. Every @code{LF} character is considered
18010 to end a line, and there is an implied @code{LF} character at the end of
18014 * Text_IO Stream Pointer Positioning::
18015 * Text_IO Reading and Writing Non-Regular Files::
18017 * Treating Text_IO Files as Streams::
18018 * Text_IO Extensions::
18019 * Text_IO Facilities for Unbounded Strings::
18022 @node Text_IO Stream Pointer Positioning
18023 @subsection Stream Pointer Positioning
18026 @code{Ada.Text_IO} has a definition of current position for a file that
18027 is being read. No internal buffering occurs in Text_IO, and usually the
18028 physical position in the stream used to implement the file corresponds
18029 to this logical position defined by Text_IO@. There are two exceptions:
18033 After a call to @code{End_Of_Page} that returns @code{True}, the stream
18034 is positioned past the @code{LF} (line mark) that precedes the page
18035 mark. Text_IO maintains an internal flag so that subsequent read
18036 operations properly handle the logical position which is unchanged by
18037 the @code{End_Of_Page} call.
18040 After a call to @code{End_Of_File} that returns @code{True}, if the
18041 Text_IO file was positioned before the line mark at the end of file
18042 before the call, then the logical position is unchanged, but the stream
18043 is physically positioned right at the end of file (past the line mark,
18044 and past a possible page mark following the line mark. Again Text_IO
18045 maintains internal flags so that subsequent read operations properly
18046 handle the logical position.
18050 These discrepancies have no effect on the observable behavior of
18051 Text_IO, but if a single Ada stream is shared between a C program and
18052 Ada program, or shared (using @samp{shared=yes} in the form string)
18053 between two Ada files, then the difference may be observable in some
18056 @node Text_IO Reading and Writing Non-Regular Files
18057 @subsection Reading and Writing Non-Regular Files
18060 A non-regular file is a device (such as a keyboard), or a pipe. Text_IO
18061 can be used for reading and writing. Writing is not affected and the
18062 sequence of characters output is identical to the normal file case, but
18063 for reading, the behavior of Text_IO is modified to avoid undesirable
18064 look-ahead as follows:
18066 An input file that is not a regular file is considered to have no page
18067 marks. Any @code{Ascii.FF} characters (the character normally used for a
18068 page mark) appearing in the file are considered to be data
18069 characters. In particular:
18073 @code{Get_Line} and @code{Skip_Line} do not test for a page mark
18074 following a line mark. If a page mark appears, it will be treated as a
18078 This avoids the need to wait for an extra character to be typed or
18079 entered from the pipe to complete one of these operations.
18082 @code{End_Of_Page} always returns @code{False}
18085 @code{End_Of_File} will return @code{False} if there is a page mark at
18086 the end of the file.
18090 Output to non-regular files is the same as for regular files. Page marks
18091 may be written to non-regular files using @code{New_Page}, but as noted
18092 above they will not be treated as page marks on input if the output is
18093 piped to another Ada program.
18095 Another important discrepancy when reading non-regular files is that the end
18096 of file indication is not ``sticky''. If an end of file is entered, e.g.@: by
18097 pressing the @key{EOT} key,
18099 is signaled once (i.e.@: the test @code{End_Of_File}
18100 will yield @code{True}, or a read will
18101 raise @code{End_Error}), but then reading can resume
18102 to read data past that end of
18103 file indication, until another end of file indication is entered.
18105 @node Get_Immediate
18106 @subsection Get_Immediate
18107 @cindex Get_Immediate
18110 Get_Immediate returns the next character (including control characters)
18111 from the input file. In particular, Get_Immediate will return LF or FF
18112 characters used as line marks or page marks. Such operations leave the
18113 file positioned past the control character, and it is thus not treated
18114 as having its normal function. This means that page, line and column
18115 counts after this kind of Get_Immediate call are set as though the mark
18116 did not occur. In the case where a Get_Immediate leaves the file
18117 positioned between the line mark and page mark (which is not normally
18118 possible), it is undefined whether the FF character will be treated as a
18121 @node Treating Text_IO Files as Streams
18122 @subsection Treating Text_IO Files as Streams
18123 @cindex Stream files
18126 The package @code{Text_IO.Streams} allows a Text_IO file to be treated
18127 as a stream. Data written to a Text_IO file in this stream mode is
18128 binary data. If this binary data contains bytes 16#0A# (@code{LF}) or
18129 16#0C# (@code{FF}), the resulting file may have non-standard
18130 format. Similarly if read operations are used to read from a Text_IO
18131 file treated as a stream, then @code{LF} and @code{FF} characters may be
18132 skipped and the effect is similar to that described above for
18133 @code{Get_Immediate}.
18135 @node Text_IO Extensions
18136 @subsection Text_IO Extensions
18137 @cindex Text_IO extensions
18140 A package GNAT.IO_Aux in the GNAT library provides some useful extensions
18141 to the standard @code{Text_IO} package:
18144 @item function File_Exists (Name : String) return Boolean;
18145 Determines if a file of the given name exists.
18147 @item function Get_Line return String;
18148 Reads a string from the standard input file. The value returned is exactly
18149 the length of the line that was read.
18151 @item function Get_Line (File : Ada.Text_IO.File_Type) return String;
18152 Similar, except that the parameter File specifies the file from which
18153 the string is to be read.
18157 @node Text_IO Facilities for Unbounded Strings
18158 @subsection Text_IO Facilities for Unbounded Strings
18159 @cindex Text_IO for unbounded strings
18160 @cindex Unbounded_String, Text_IO operations
18163 The package @code{Ada.Strings.Unbounded.Text_IO}
18164 in library files @code{a-suteio.ads/adb} contains some GNAT-specific
18165 subprograms useful for Text_IO operations on unbounded strings:
18169 @item function Get_Line (File : File_Type) return Unbounded_String;
18170 Reads a line from the specified file
18171 and returns the result as an unbounded string.
18173 @item procedure Put (File : File_Type; U : Unbounded_String);
18174 Writes the value of the given unbounded string to the specified file
18175 Similar to the effect of
18176 @code{Put (To_String (U))} except that an extra copy is avoided.
18178 @item procedure Put_Line (File : File_Type; U : Unbounded_String);
18179 Writes the value of the given unbounded string to the specified file,
18180 followed by a @code{New_Line}.
18181 Similar to the effect of @code{Put_Line (To_String (U))} except
18182 that an extra copy is avoided.
18186 In the above procedures, @code{File} is of type @code{Ada.Text_IO.File_Type}
18187 and is optional. If the parameter is omitted, then the standard input or
18188 output file is referenced as appropriate.
18190 The package @code{Ada.Strings.Wide_Unbounded.Wide_Text_IO} in library
18191 files @file{a-swuwti.ads} and @file{a-swuwti.adb} provides similar extended
18192 @code{Wide_Text_IO} functionality for unbounded wide strings.
18194 The package @code{Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO} in library
18195 files @file{a-szuzti.ads} and @file{a-szuzti.adb} provides similar extended
18196 @code{Wide_Wide_Text_IO} functionality for unbounded wide wide strings.
18199 @section Wide_Text_IO
18202 @code{Wide_Text_IO} is similar in most respects to Text_IO, except that
18203 both input and output files may contain special sequences that represent
18204 wide character values. The encoding scheme for a given file may be
18205 specified using a FORM parameter:
18212 as part of the FORM string (WCEM = wide character encoding method),
18213 where @var{x} is one of the following characters
18219 Upper half encoding
18231 The encoding methods match those that
18232 can be used in a source
18233 program, but there is no requirement that the encoding method used for
18234 the source program be the same as the encoding method used for files,
18235 and different files may use different encoding methods.
18237 The default encoding method for the standard files, and for opened files
18238 for which no WCEM parameter is given in the FORM string matches the
18239 wide character encoding specified for the main program (the default
18240 being brackets encoding if no coding method was specified with -gnatW).
18244 In this encoding, a wide character is represented by a five character
18252 where @var{a}, @var{b}, @var{c}, @var{d} are the four hexadecimal
18253 characters (using upper case letters) of the wide character code. For
18254 example, ESC A345 is used to represent the wide character with code
18255 16#A345#. This scheme is compatible with use of the full
18256 @code{Wide_Character} set.
18258 @item Upper Half Coding
18259 The wide character with encoding 16#abcd#, where the upper bit is on
18260 (i.e.@: a is in the range 8-F) is represented as two bytes 16#ab# and
18261 16#cd#. The second byte may never be a format control character, but is
18262 not required to be in the upper half. This method can be also used for
18263 shift-JIS or EUC where the internal coding matches the external coding.
18265 @item Shift JIS Coding
18266 A wide character is represented by a two character sequence 16#ab# and
18267 16#cd#, with the restrictions described for upper half encoding as
18268 described above. The internal character code is the corresponding JIS
18269 character according to the standard algorithm for Shift-JIS
18270 conversion. Only characters defined in the JIS code set table can be
18271 used with this encoding method.
18274 A wide character is represented by a two character sequence 16#ab# and
18275 16#cd#, with both characters being in the upper half. The internal
18276 character code is the corresponding JIS character according to the EUC
18277 encoding algorithm. Only characters defined in the JIS code set table
18278 can be used with this encoding method.
18281 A wide character is represented using
18282 UCS Transformation Format 8 (UTF-8) as defined in Annex R of ISO
18283 10646-1/Am.2. Depending on the character value, the representation
18284 is a one, two, or three byte sequence:
18287 16#0000#-16#007f#: 2#0xxxxxxx#
18288 16#0080#-16#07ff#: 2#110xxxxx# 2#10xxxxxx#
18289 16#0800#-16#ffff#: 2#1110xxxx# 2#10xxxxxx# 2#10xxxxxx#
18293 where the @var{xxx} bits correspond to the left-padded bits of the
18294 16-bit character value. Note that all lower half ASCII characters
18295 are represented as ASCII bytes and all upper half characters and
18296 other wide characters are represented as sequences of upper-half
18297 (The full UTF-8 scheme allows for encoding 31-bit characters as
18298 6-byte sequences, but in this implementation, all UTF-8 sequences
18299 of four or more bytes length will raise a Constraint_Error, as
18300 will all invalid UTF-8 sequences.)
18302 @item Brackets Coding
18303 In this encoding, a wide character is represented by the following eight
18304 character sequence:
18311 where @code{a}, @code{b}, @code{c}, @code{d} are the four hexadecimal
18312 characters (using uppercase letters) of the wide character code. For
18313 example, @code{["A345"]} is used to represent the wide character with code
18315 This scheme is compatible with use of the full Wide_Character set.
18316 On input, brackets coding can also be used for upper half characters,
18317 e.g.@: @code{["C1"]} for lower case a. However, on output, brackets notation
18318 is only used for wide characters with a code greater than @code{16#FF#}.
18320 Note that brackets coding is not normally used in the context of
18321 Wide_Text_IO or Wide_Wide_Text_IO, since it is really just designed as
18322 a portable way of encoding source files. In the context of Wide_Text_IO
18323 or Wide_Wide_Text_IO, it can only be used if the file does not contain
18324 any instance of the left bracket character other than to encode wide
18325 character values using the brackets encoding method. In practice it is
18326 expected that some standard wide character encoding method such
18327 as UTF-8 will be used for text input output.
18329 If brackets notation is used, then any occurrence of a left bracket
18330 in the input file which is not the start of a valid wide character
18331 sequence will cause Constraint_Error to be raised. It is possible to
18332 encode a left bracket as ["5B"] and Wide_Text_IO and Wide_Wide_Text_IO
18333 input will interpret this as a left bracket.
18335 However, when a left bracket is output, it will be output as a left bracket
18336 and not as ["5B"]. We make this decision because for normal use of
18337 Wide_Text_IO for outputting messages, it is unpleasant to clobber left
18338 brackets. For example, if we write:
18341 Put_Line ("Start of output [first run]");
18345 we really do not want to have the left bracket in this message clobbered so
18346 that the output reads:
18349 Start of output ["5B"]first run]
18353 In practice brackets encoding is reasonably useful for normal Put_Line use
18354 since we won't get confused between left brackets and wide character
18355 sequences in the output. But for input, or when files are written out
18356 and read back in, it really makes better sense to use one of the standard
18357 encoding methods such as UTF-8.
18362 For the coding schemes other than UTF-8, Hex, or Brackets encoding,
18363 not all wide character
18364 values can be represented. An attempt to output a character that cannot
18365 be represented using the encoding scheme for the file causes
18366 Constraint_Error to be raised. An invalid wide character sequence on
18367 input also causes Constraint_Error to be raised.
18370 * Wide_Text_IO Stream Pointer Positioning::
18371 * Wide_Text_IO Reading and Writing Non-Regular Files::
18374 @node Wide_Text_IO Stream Pointer Positioning
18375 @subsection Stream Pointer Positioning
18378 @code{Ada.Wide_Text_IO} is similar to @code{Ada.Text_IO} in its handling
18379 of stream pointer positioning (@pxref{Text_IO}). There is one additional
18382 If @code{Ada.Wide_Text_IO.Look_Ahead} reads a character outside the
18383 normal lower ASCII set (i.e.@: a character in the range:
18385 @smallexample @c ada
18386 Wide_Character'Val (16#0080#) .. Wide_Character'Val (16#FFFF#)
18390 then although the logical position of the file pointer is unchanged by
18391 the @code{Look_Ahead} call, the stream is physically positioned past the
18392 wide character sequence. Again this is to avoid the need for buffering
18393 or backup, and all @code{Wide_Text_IO} routines check the internal
18394 indication that this situation has occurred so that this is not visible
18395 to a normal program using @code{Wide_Text_IO}. However, this discrepancy
18396 can be observed if the wide text file shares a stream with another file.
18398 @node Wide_Text_IO Reading and Writing Non-Regular Files
18399 @subsection Reading and Writing Non-Regular Files
18402 As in the case of Text_IO, when a non-regular file is read, it is
18403 assumed that the file contains no page marks (any form characters are
18404 treated as data characters), and @code{End_Of_Page} always returns
18405 @code{False}. Similarly, the end of file indication is not sticky, so
18406 it is possible to read beyond an end of file.
18408 @node Wide_Wide_Text_IO
18409 @section Wide_Wide_Text_IO
18412 @code{Wide_Wide_Text_IO} is similar in most respects to Text_IO, except that
18413 both input and output files may contain special sequences that represent
18414 wide wide character values. The encoding scheme for a given file may be
18415 specified using a FORM parameter:
18422 as part of the FORM string (WCEM = wide character encoding method),
18423 where @var{x} is one of the following characters
18429 Upper half encoding
18441 The encoding methods match those that
18442 can be used in a source
18443 program, but there is no requirement that the encoding method used for
18444 the source program be the same as the encoding method used for files,
18445 and different files may use different encoding methods.
18447 The default encoding method for the standard files, and for opened files
18448 for which no WCEM parameter is given in the FORM string matches the
18449 wide character encoding specified for the main program (the default
18450 being brackets encoding if no coding method was specified with -gnatW).
18455 A wide character is represented using
18456 UCS Transformation Format 8 (UTF-8) as defined in Annex R of ISO
18457 10646-1/Am.2. Depending on the character value, the representation
18458 is a one, two, three, or four byte sequence:
18461 16#000000#-16#00007f#: 2#0xxxxxxx#
18462 16#000080#-16#0007ff#: 2#110xxxxx# 2#10xxxxxx#
18463 16#000800#-16#00ffff#: 2#1110xxxx# 2#10xxxxxx# 2#10xxxxxx#
18464 16#010000#-16#10ffff#: 2#11110xxx# 2#10xxxxxx# 2#10xxxxxx# 2#10xxxxxx#
18468 where the @var{xxx} bits correspond to the left-padded bits of the
18469 21-bit character value. Note that all lower half ASCII characters
18470 are represented as ASCII bytes and all upper half characters and
18471 other wide characters are represented as sequences of upper-half
18474 @item Brackets Coding
18475 In this encoding, a wide wide character is represented by the following eight
18476 character sequence if is in wide character range
18482 and by the following ten character sequence if not
18485 [ " a b c d e f " ]
18489 where @code{a}, @code{b}, @code{c}, @code{d}, @code{e}, and @code{f}
18490 are the four or six hexadecimal
18491 characters (using uppercase letters) of the wide wide character code. For
18492 example, @code{["01A345"]} is used to represent the wide wide character
18493 with code @code{16#01A345#}.
18495 This scheme is compatible with use of the full Wide_Wide_Character set.
18496 On input, brackets coding can also be used for upper half characters,
18497 e.g.@: @code{["C1"]} for lower case a. However, on output, brackets notation
18498 is only used for wide characters with a code greater than @code{16#FF#}.
18503 If is also possible to use the other Wide_Character encoding methods,
18504 such as Shift-JIS, but the other schemes cannot support the full range
18505 of wide wide characters.
18506 An attempt to output a character that cannot
18507 be represented using the encoding scheme for the file causes
18508 Constraint_Error to be raised. An invalid wide character sequence on
18509 input also causes Constraint_Error to be raised.
18512 * Wide_Wide_Text_IO Stream Pointer Positioning::
18513 * Wide_Wide_Text_IO Reading and Writing Non-Regular Files::
18516 @node Wide_Wide_Text_IO Stream Pointer Positioning
18517 @subsection Stream Pointer Positioning
18520 @code{Ada.Wide_Wide_Text_IO} is similar to @code{Ada.Text_IO} in its handling
18521 of stream pointer positioning (@pxref{Text_IO}). There is one additional
18524 If @code{Ada.Wide_Wide_Text_IO.Look_Ahead} reads a character outside the
18525 normal lower ASCII set (i.e.@: a character in the range:
18527 @smallexample @c ada
18528 Wide_Wide_Character'Val (16#0080#) .. Wide_Wide_Character'Val (16#10FFFF#)
18532 then although the logical position of the file pointer is unchanged by
18533 the @code{Look_Ahead} call, the stream is physically positioned past the
18534 wide character sequence. Again this is to avoid the need for buffering
18535 or backup, and all @code{Wide_Wide_Text_IO} routines check the internal
18536 indication that this situation has occurred so that this is not visible
18537 to a normal program using @code{Wide_Wide_Text_IO}. However, this discrepancy
18538 can be observed if the wide text file shares a stream with another file.
18540 @node Wide_Wide_Text_IO Reading and Writing Non-Regular Files
18541 @subsection Reading and Writing Non-Regular Files
18544 As in the case of Text_IO, when a non-regular file is read, it is
18545 assumed that the file contains no page marks (any form characters are
18546 treated as data characters), and @code{End_Of_Page} always returns
18547 @code{False}. Similarly, the end of file indication is not sticky, so
18548 it is possible to read beyond an end of file.
18554 A stream file is a sequence of bytes, where individual elements are
18555 written to the file as described in the Ada Reference Manual. The type
18556 @code{Stream_Element} is simply a byte. There are two ways to read or
18557 write a stream file.
18561 The operations @code{Read} and @code{Write} directly read or write a
18562 sequence of stream elements with no control information.
18565 The stream attributes applied to a stream file transfer data in the
18566 manner described for stream attributes.
18569 @node Text Translation
18570 @section Text Translation
18573 @samp{Text_Translation=@var{xxx}} may be used as the Form parameter
18574 passed to Text_IO.Create and Text_IO.Open. @samp{Text_Translation=@var{xxx}}
18575 has no effect on Unix systems. Possible values are:
18580 @samp{@var{Yes} or @var{Text}} is the default, which means to
18581 translate LF to/from CR/LF on Windows systems.
18583 @samp{@var{No}} disables this translation; i.e. it
18584 uses binary mode. For output files, @samp{Text_Translation=@var{No}}
18585 may be used to create Unix-style files on
18589 @samp{@var{wtext}} translation enabled in Unicode mode.
18590 (corresponds to _O_WTEXT).
18593 @samp{@var{u8text}} translation enabled in Unicode UTF-8 mode.
18594 (corresponds to O_U8TEXT).
18597 @samp{@var{u16text}} translation enabled in Unicode UTF-16
18598 mode. (corresponds to_O_U16TEXT).
18605 @section Shared Files
18608 Section A.14 of the Ada Reference Manual allows implementations to
18609 provide a wide variety of behavior if an attempt is made to access the
18610 same external file with two or more internal files.
18612 To provide a full range of functionality, while at the same time
18613 minimizing the problems of portability caused by this implementation
18614 dependence, GNAT handles file sharing as follows:
18618 In the absence of a @samp{shared=@var{xxx}} form parameter, an attempt
18619 to open two or more files with the same full name is considered an error
18620 and is not supported. The exception @code{Use_Error} will be
18621 raised. Note that a file that is not explicitly closed by the program
18622 remains open until the program terminates.
18625 If the form parameter @samp{shared=no} appears in the form string, the
18626 file can be opened or created with its own separate stream identifier,
18627 regardless of whether other files sharing the same external file are
18628 opened. The exact effect depends on how the C stream routines handle
18629 multiple accesses to the same external files using separate streams.
18632 If the form parameter @samp{shared=yes} appears in the form string for
18633 each of two or more files opened using the same full name, the same
18634 stream is shared between these files, and the semantics are as described
18635 in Ada Reference Manual, Section A.14.
18639 When a program that opens multiple files with the same name is ported
18640 from another Ada compiler to GNAT, the effect will be that
18641 @code{Use_Error} is raised.
18643 The documentation of the original compiler and the documentation of the
18644 program should then be examined to determine if file sharing was
18645 expected, and @samp{shared=@var{xxx}} parameters added to @code{Open}
18646 and @code{Create} calls as required.
18648 When a program is ported from GNAT to some other Ada compiler, no
18649 special attention is required unless the @samp{shared=@var{xxx}} form
18650 parameter is used in the program. In this case, you must examine the
18651 documentation of the new compiler to see if it supports the required
18652 file sharing semantics, and form strings modified appropriately. Of
18653 course it may be the case that the program cannot be ported if the
18654 target compiler does not support the required functionality. The best
18655 approach in writing portable code is to avoid file sharing (and hence
18656 the use of the @samp{shared=@var{xxx}} parameter in the form string)
18659 One common use of file sharing in Ada 83 is the use of instantiations of
18660 Sequential_IO on the same file with different types, to achieve
18661 heterogeneous input-output. Although this approach will work in GNAT if
18662 @samp{shared=yes} is specified, it is preferable in Ada to use Stream_IO
18663 for this purpose (using the stream attributes)
18665 @node Filenames encoding
18666 @section Filenames encoding
18669 An encoding form parameter can be used to specify the filename
18670 encoding @samp{encoding=@var{xxx}}.
18674 If the form parameter @samp{encoding=utf8} appears in the form string, the
18675 filename must be encoded in UTF-8.
18678 If the form parameter @samp{encoding=8bits} appears in the form
18679 string, the filename must be a standard 8bits string.
18682 In the absence of a @samp{encoding=@var{xxx}} form parameter, the
18683 encoding is controlled by the @samp{GNAT_CODE_PAGE} environment
18684 variable. And if not set @samp{utf8} is assumed.
18688 The current system Windows ANSI code page.
18693 This encoding form parameter is only supported on the Windows
18694 platform. On the other Operating Systems the run-time is supporting
18697 @node File content encoding
18698 @section File content encoding
18701 For text files it is possible to specify the encoding to use. This is
18702 controlled by the by the @samp{GNAT_CCS_ENCODING} environment
18703 variable. And if not set @samp{TEXT} is assumed.
18705 The possible values are those supported on Windows:
18709 Translated text mode
18711 Translated unicode encoding
18713 Unicode 16-bit encoding
18715 Unicode 8-bit encoding
18718 This encoding is only supported on the Windows platform.
18721 @section Open Modes
18724 @code{Open} and @code{Create} calls result in a call to @code{fopen}
18725 using the mode shown in the following table:
18728 @center @code{Open} and @code{Create} Call Modes
18730 @b{OPEN } @b{CREATE}
18731 Append_File "r+" "w+"
18733 Out_File (Direct_IO) "r+" "w"
18734 Out_File (all other cases) "w" "w"
18735 Inout_File "r+" "w+"
18739 If text file translation is required, then either @samp{b} or @samp{t}
18740 is added to the mode, depending on the setting of Text. Text file
18741 translation refers to the mapping of CR/LF sequences in an external file
18742 to LF characters internally. This mapping only occurs in DOS and
18743 DOS-like systems, and is not relevant to other systems.
18745 A special case occurs with Stream_IO@. As shown in the above table, the
18746 file is initially opened in @samp{r} or @samp{w} mode for the
18747 @code{In_File} and @code{Out_File} cases. If a @code{Set_Mode} operation
18748 subsequently requires switching from reading to writing or vice-versa,
18749 then the file is reopened in @samp{r+} mode to permit the required operation.
18751 @node Operations on C Streams
18752 @section Operations on C Streams
18753 The package @code{Interfaces.C_Streams} provides an Ada program with direct
18754 access to the C library functions for operations on C streams:
18756 @smallexample @c adanocomment
18757 package Interfaces.C_Streams is
18758 -- Note: the reason we do not use the types that are in
18759 -- Interfaces.C is that we want to avoid dragging in the
18760 -- code in this unit if possible.
18761 subtype chars is System.Address;
18762 -- Pointer to null-terminated array of characters
18763 subtype FILEs is System.Address;
18764 -- Corresponds to the C type FILE*
18765 subtype voids is System.Address;
18766 -- Corresponds to the C type void*
18767 subtype int is Integer;
18768 subtype long is Long_Integer;
18769 -- Note: the above types are subtypes deliberately, and it
18770 -- is part of this spec that the above correspondences are
18771 -- guaranteed. This means that it is legitimate to, for
18772 -- example, use Integer instead of int. We provide these
18773 -- synonyms for clarity, but in some cases it may be
18774 -- convenient to use the underlying types (for example to
18775 -- avoid an unnecessary dependency of a spec on the spec
18777 type size_t is mod 2 ** Standard'Address_Size;
18778 NULL_Stream : constant FILEs;
18779 -- Value returned (NULL in C) to indicate an
18780 -- fdopen/fopen/tmpfile error
18781 ----------------------------------
18782 -- Constants Defined in stdio.h --
18783 ----------------------------------
18784 EOF : constant int;
18785 -- Used by a number of routines to indicate error or
18787 IOFBF : constant int;
18788 IOLBF : constant int;
18789 IONBF : constant int;
18790 -- Used to indicate buffering mode for setvbuf call
18791 SEEK_CUR : constant int;
18792 SEEK_END : constant int;
18793 SEEK_SET : constant int;
18794 -- Used to indicate origin for fseek call
18795 function stdin return FILEs;
18796 function stdout return FILEs;
18797 function stderr return FILEs;
18798 -- Streams associated with standard files
18799 --------------------------
18800 -- Standard C functions --
18801 --------------------------
18802 -- The functions selected below are ones that are
18803 -- available in UNIX (but not necessarily in ANSI C).
18804 -- These are very thin interfaces
18805 -- which copy exactly the C headers. For more
18806 -- documentation on these functions, see the Microsoft C
18807 -- "Run-Time Library Reference" (Microsoft Press, 1990,
18808 -- ISBN 1-55615-225-6), which includes useful information
18809 -- on system compatibility.
18810 procedure clearerr (stream : FILEs);
18811 function fclose (stream : FILEs) return int;
18812 function fdopen (handle : int; mode : chars) return FILEs;
18813 function feof (stream : FILEs) return int;
18814 function ferror (stream : FILEs) return int;
18815 function fflush (stream : FILEs) return int;
18816 function fgetc (stream : FILEs) return int;
18817 function fgets (strng : chars; n : int; stream : FILEs)
18819 function fileno (stream : FILEs) return int;
18820 function fopen (filename : chars; Mode : chars)
18822 -- Note: to maintain target independence, use
18823 -- text_translation_required, a boolean variable defined in
18824 -- a-sysdep.c to deal with the target dependent text
18825 -- translation requirement. If this variable is set,
18826 -- then b/t should be appended to the standard mode
18827 -- argument to set the text translation mode off or on
18829 function fputc (C : int; stream : FILEs) return int;
18830 function fputs (Strng : chars; Stream : FILEs) return int;
18847 function ftell (stream : FILEs) return long;
18854 function isatty (handle : int) return int;
18855 procedure mktemp (template : chars);
18856 -- The return value (which is just a pointer to template)
18858 procedure rewind (stream : FILEs);
18859 function rmtmp return int;
18867 function tmpfile return FILEs;
18868 function ungetc (c : int; stream : FILEs) return int;
18869 function unlink (filename : chars) return int;
18870 ---------------------
18871 -- Extra functions --
18872 ---------------------
18873 -- These functions supply slightly thicker bindings than
18874 -- those above. They are derived from functions in the
18875 -- C Run-Time Library, but may do a bit more work than
18876 -- just directly calling one of the Library functions.
18877 function is_regular_file (handle : int) return int;
18878 -- Tests if given handle is for a regular file (result 1)
18879 -- or for a non-regular file (pipe or device, result 0).
18880 ---------------------------------
18881 -- Control of Text/Binary Mode --
18882 ---------------------------------
18883 -- If text_translation_required is true, then the following
18884 -- functions may be used to dynamically switch a file from
18885 -- binary to text mode or vice versa. These functions have
18886 -- no effect if text_translation_required is false (i.e.@: in
18887 -- normal UNIX mode). Use fileno to get a stream handle.
18888 procedure set_binary_mode (handle : int);
18889 procedure set_text_mode (handle : int);
18890 ----------------------------
18891 -- Full Path Name support --
18892 ----------------------------
18893 procedure full_name (nam : chars; buffer : chars);
18894 -- Given a NUL terminated string representing a file
18895 -- name, returns in buffer a NUL terminated string
18896 -- representing the full path name for the file name.
18897 -- On systems where it is relevant the drive is also
18898 -- part of the full path name. It is the responsibility
18899 -- of the caller to pass an actual parameter for buffer
18900 -- that is big enough for any full path name. Use
18901 -- max_path_len given below as the size of buffer.
18902 max_path_len : integer;
18903 -- Maximum length of an allowable full path name on the
18904 -- system, including a terminating NUL character.
18905 end Interfaces.C_Streams;
18908 @node Interfacing to C Streams
18909 @section Interfacing to C Streams
18912 The packages in this section permit interfacing Ada files to C Stream
18915 @smallexample @c ada
18916 with Interfaces.C_Streams;
18917 package Ada.Sequential_IO.C_Streams is
18918 function C_Stream (F : File_Type)
18919 return Interfaces.C_Streams.FILEs;
18921 (File : in out File_Type;
18922 Mode : in File_Mode;
18923 C_Stream : in Interfaces.C_Streams.FILEs;
18924 Form : in String := "");
18925 end Ada.Sequential_IO.C_Streams;
18927 with Interfaces.C_Streams;
18928 package Ada.Direct_IO.C_Streams is
18929 function C_Stream (F : File_Type)
18930 return Interfaces.C_Streams.FILEs;
18932 (File : in out File_Type;
18933 Mode : in File_Mode;
18934 C_Stream : in Interfaces.C_Streams.FILEs;
18935 Form : in String := "");
18936 end Ada.Direct_IO.C_Streams;
18938 with Interfaces.C_Streams;
18939 package Ada.Text_IO.C_Streams is
18940 function C_Stream (F : File_Type)
18941 return Interfaces.C_Streams.FILEs;
18943 (File : in out File_Type;
18944 Mode : in File_Mode;
18945 C_Stream : in Interfaces.C_Streams.FILEs;
18946 Form : in String := "");
18947 end Ada.Text_IO.C_Streams;
18949 with Interfaces.C_Streams;
18950 package Ada.Wide_Text_IO.C_Streams is
18951 function C_Stream (F : File_Type)
18952 return Interfaces.C_Streams.FILEs;
18954 (File : in out File_Type;
18955 Mode : in File_Mode;
18956 C_Stream : in Interfaces.C_Streams.FILEs;
18957 Form : in String := "");
18958 end Ada.Wide_Text_IO.C_Streams;
18960 with Interfaces.C_Streams;
18961 package Ada.Wide_Wide_Text_IO.C_Streams is
18962 function C_Stream (F : File_Type)
18963 return Interfaces.C_Streams.FILEs;
18965 (File : in out File_Type;
18966 Mode : in File_Mode;
18967 C_Stream : in Interfaces.C_Streams.FILEs;
18968 Form : in String := "");
18969 end Ada.Wide_Wide_Text_IO.C_Streams;
18971 with Interfaces.C_Streams;
18972 package Ada.Stream_IO.C_Streams is
18973 function C_Stream (F : File_Type)
18974 return Interfaces.C_Streams.FILEs;
18976 (File : in out File_Type;
18977 Mode : in File_Mode;
18978 C_Stream : in Interfaces.C_Streams.FILEs;
18979 Form : in String := "");
18980 end Ada.Stream_IO.C_Streams;
18984 In each of these six packages, the @code{C_Stream} function obtains the
18985 @code{FILE} pointer from a currently opened Ada file. It is then
18986 possible to use the @code{Interfaces.C_Streams} package to operate on
18987 this stream, or the stream can be passed to a C program which can
18988 operate on it directly. Of course the program is responsible for
18989 ensuring that only appropriate sequences of operations are executed.
18991 One particular use of relevance to an Ada program is that the
18992 @code{setvbuf} function can be used to control the buffering of the
18993 stream used by an Ada file. In the absence of such a call the standard
18994 default buffering is used.
18996 The @code{Open} procedures in these packages open a file giving an
18997 existing C Stream instead of a file name. Typically this stream is
18998 imported from a C program, allowing an Ada file to operate on an
19001 @node The GNAT Library
19002 @chapter The GNAT Library
19005 The GNAT library contains a number of general and special purpose packages.
19006 It represents functionality that the GNAT developers have found useful, and
19007 which is made available to GNAT users. The packages described here are fully
19008 supported, and upwards compatibility will be maintained in future releases,
19009 so you can use these facilities with the confidence that the same functionality
19010 will be available in future releases.
19012 The chapter here simply gives a brief summary of the facilities available.
19013 The full documentation is found in the spec file for the package. The full
19014 sources of these library packages, including both spec and body, are provided
19015 with all GNAT releases. For example, to find out the full specifications of
19016 the SPITBOL pattern matching capability, including a full tutorial and
19017 extensive examples, look in the @file{g-spipat.ads} file in the library.
19019 For each entry here, the package name (as it would appear in a @code{with}
19020 clause) is given, followed by the name of the corresponding spec file in
19021 parentheses. The packages are children in four hierarchies, @code{Ada},
19022 @code{Interfaces}, @code{System}, and @code{GNAT}, the latter being a
19023 GNAT-specific hierarchy.
19025 Note that an application program should only use packages in one of these
19026 four hierarchies if the package is defined in the Ada Reference Manual,
19027 or is listed in this section of the GNAT Programmers Reference Manual.
19028 All other units should be considered internal implementation units and
19029 should not be directly @code{with}'ed by application code. The use of
19030 a @code{with} statement that references one of these internal implementation
19031 units makes an application potentially dependent on changes in versions
19032 of GNAT, and will generate a warning message.
19035 * Ada.Characters.Latin_9 (a-chlat9.ads)::
19036 * Ada.Characters.Wide_Latin_1 (a-cwila1.ads)::
19037 * Ada.Characters.Wide_Latin_9 (a-cwila9.ads)::
19038 * Ada.Characters.Wide_Wide_Latin_1 (a-chzla1.ads)::
19039 * Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads)::
19040 * Ada.Containers.Formal_Doubly_Linked_Lists (a-cfdlli.ads)::
19041 * Ada.Containers.Formal_Hashed_Maps (a-cfhama.ads)::
19042 * Ada.Containers.Formal_Hashed_Sets (a-cfhase.ads)::
19043 * Ada.Containers.Formal_Ordered_Maps (a-cforma.ads)::
19044 * Ada.Containers.Formal_Ordered_Sets (a-cforse.ads)::
19045 * Ada.Containers.Formal_Vectors (a-cofove.ads)::
19046 * Ada.Containers.Formal_Indefinite_Vectors (a-cfinve.ads)::
19047 * Ada.Containers.Bounded_Holders (a-coboho.ads)::
19048 * Ada.Command_Line.Environment (a-colien.ads)::
19049 * Ada.Command_Line.Remove (a-colire.ads)::
19050 * Ada.Command_Line.Response_File (a-clrefi.ads)::
19051 * Ada.Direct_IO.C_Streams (a-diocst.ads)::
19052 * Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads)::
19053 * Ada.Exceptions.Last_Chance_Handler (a-elchha.ads)::
19054 * Ada.Exceptions.Traceback (a-exctra.ads)::
19055 * Ada.Sequential_IO.C_Streams (a-siocst.ads)::
19056 * Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads)::
19057 * Ada.Strings.Unbounded.Text_IO (a-suteio.ads)::
19058 * Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads)::
19059 * Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads)::
19060 * Ada.Text_IO.C_Streams (a-tiocst.ads)::
19061 * Ada.Text_IO.Reset_Standard_Files (a-tirsfi.ads)::
19062 * Ada.Wide_Characters.Unicode (a-wichun.ads)::
19063 * Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads)::
19064 * Ada.Wide_Text_IO.Reset_Standard_Files (a-wrstfi.ads)::
19065 * Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads)::
19066 * Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads)::
19067 * Ada.Wide_Wide_Text_IO.Reset_Standard_Files (a-zrstfi.ads)::
19068 * GNAT.Altivec (g-altive.ads)::
19069 * GNAT.Altivec.Conversions (g-altcon.ads)::
19070 * GNAT.Altivec.Vector_Operations (g-alveop.ads)::
19071 * GNAT.Altivec.Vector_Types (g-alvety.ads)::
19072 * GNAT.Altivec.Vector_Views (g-alvevi.ads)::
19073 * GNAT.Array_Split (g-arrspl.ads)::
19074 * GNAT.AWK (g-awk.ads)::
19075 * GNAT.Bounded_Buffers (g-boubuf.ads)::
19076 * GNAT.Bounded_Mailboxes (g-boumai.ads)::
19077 * GNAT.Bubble_Sort (g-bubsor.ads)::
19078 * GNAT.Bubble_Sort_A (g-busora.ads)::
19079 * GNAT.Bubble_Sort_G (g-busorg.ads)::
19080 * GNAT.Byte_Order_Mark (g-byorma.ads)::
19081 * GNAT.Byte_Swapping (g-bytswa.ads)::
19082 * GNAT.Calendar (g-calend.ads)::
19083 * GNAT.Calendar.Time_IO (g-catiio.ads)::
19084 * GNAT.Case_Util (g-casuti.ads)::
19085 * GNAT.CGI (g-cgi.ads)::
19086 * GNAT.CGI.Cookie (g-cgicoo.ads)::
19087 * GNAT.CGI.Debug (g-cgideb.ads)::
19088 * GNAT.Command_Line (g-comlin.ads)::
19089 * GNAT.Compiler_Version (g-comver.ads)::
19090 * GNAT.Ctrl_C (g-ctrl_c.ads)::
19091 * GNAT.CRC32 (g-crc32.ads)::
19092 * GNAT.Current_Exception (g-curexc.ads)::
19093 * GNAT.Debug_Pools (g-debpoo.ads)::
19094 * GNAT.Debug_Utilities (g-debuti.ads)::
19095 * GNAT.Decode_String (g-decstr.ads)::
19096 * GNAT.Decode_UTF8_String (g-deutst.ads)::
19097 * GNAT.Directory_Operations (g-dirope.ads)::
19098 * GNAT.Directory_Operations.Iteration (g-diopit.ads)::
19099 * GNAT.Dynamic_HTables (g-dynhta.ads)::
19100 * GNAT.Dynamic_Tables (g-dyntab.ads)::
19101 * GNAT.Encode_String (g-encstr.ads)::
19102 * GNAT.Encode_UTF8_String (g-enutst.ads)::
19103 * GNAT.Exception_Actions (g-excact.ads)::
19104 * GNAT.Exception_Traces (g-exctra.ads)::
19105 * GNAT.Exceptions (g-except.ads)::
19106 * GNAT.Expect (g-expect.ads)::
19107 * GNAT.Expect.TTY (g-exptty.ads)::
19108 * GNAT.Float_Control (g-flocon.ads)::
19109 * GNAT.Formatted_String (g-forstr.ads)::
19110 * GNAT.Heap_Sort (g-heasor.ads)::
19111 * GNAT.Heap_Sort_A (g-hesora.ads)::
19112 * GNAT.Heap_Sort_G (g-hesorg.ads)::
19113 * GNAT.HTable (g-htable.ads)::
19114 * GNAT.IO (g-io.ads)::
19115 * GNAT.IO_Aux (g-io_aux.ads)::
19116 * GNAT.Lock_Files (g-locfil.ads)::
19117 * GNAT.MBBS_Discrete_Random (g-mbdira.ads)::
19118 * GNAT.MBBS_Float_Random (g-mbflra.ads)::
19119 * GNAT.MD5 (g-md5.ads)::
19120 * GNAT.Memory_Dump (g-memdum.ads)::
19121 * GNAT.Most_Recent_Exception (g-moreex.ads)::
19122 * GNAT.OS_Lib (g-os_lib.ads)::
19123 * GNAT.Perfect_Hash_Generators (g-pehage.ads)::
19124 * GNAT.Random_Numbers (g-rannum.ads)::
19125 * GNAT.Regexp (g-regexp.ads)::
19126 * GNAT.Registry (g-regist.ads)::
19127 * GNAT.Regpat (g-regpat.ads)::
19128 * GNAT.Rewrite_Data (g-rewdat.ads)::
19129 * GNAT.Secondary_Stack_Info (g-sestin.ads)::
19130 * GNAT.Semaphores (g-semaph.ads)::
19131 * GNAT.Serial_Communications (g-sercom.ads)::
19132 * GNAT.SHA1 (g-sha1.ads)::
19133 * GNAT.SHA224 (g-sha224.ads)::
19134 * GNAT.SHA256 (g-sha256.ads)::
19135 * GNAT.SHA384 (g-sha384.ads)::
19136 * GNAT.SHA512 (g-sha512.ads)::
19137 * GNAT.Signals (g-signal.ads)::
19138 * GNAT.Sockets (g-socket.ads)::
19139 * GNAT.Source_Info (g-souinf.ads)::
19140 * GNAT.Spelling_Checker (g-speche.ads)::
19141 * GNAT.Spelling_Checker_Generic (g-spchge.ads)::
19142 * GNAT.Spitbol.Patterns (g-spipat.ads)::
19143 * GNAT.Spitbol (g-spitbo.ads)::
19144 * GNAT.Spitbol.Table_Boolean (g-sptabo.ads)::
19145 * GNAT.Spitbol.Table_Integer (g-sptain.ads)::
19146 * GNAT.Spitbol.Table_VString (g-sptavs.ads)::
19147 * GNAT.SSE (g-sse.ads)::
19148 * GNAT.SSE.Vector_Types (g-ssvety.ads)::
19149 * GNAT.Strings (g-string.ads)::
19150 * GNAT.String_Split (g-strspl.ads)::
19151 * GNAT.Table (g-table.ads)::
19152 * GNAT.Task_Lock (g-tasloc.ads)::
19153 * GNAT.Threads (g-thread.ads)::
19154 * GNAT.Time_Stamp (g-timsta.ads)::
19155 * GNAT.Traceback (g-traceb.ads)::
19156 * GNAT.Traceback.Symbolic (g-trasym.ads)::
19157 * GNAT.UTF_32 (g-utf_32.ads)::
19158 * GNAT.UTF_32_Spelling_Checker (g-u3spch.ads)::
19159 * GNAT.Wide_Spelling_Checker (g-wispch.ads)::
19160 * GNAT.Wide_String_Split (g-wistsp.ads)::
19161 * GNAT.Wide_Wide_Spelling_Checker (g-zspche.ads)::
19162 * GNAT.Wide_Wide_String_Split (g-zistsp.ads)::
19163 * Interfaces.C.Extensions (i-cexten.ads)::
19164 * Interfaces.C.Streams (i-cstrea.ads)::
19165 * Interfaces.Packed_Decimal (i-pacdec.ads)::
19166 * Interfaces.VxWorks (i-vxwork.ads)::
19167 * Interfaces.VxWorks.IO (i-vxwoio.ads)::
19168 * System.Address_Image (s-addima.ads)::
19169 * System.Assertions (s-assert.ads)::
19170 * System.Atomic_Counters (s-atocou.ads)::
19171 * System.Memory (s-memory.ads)::
19172 * System.Multiprocessors (s-multip.ads)::
19173 * System.Multiprocessors.Dispatching_Domains (s-mudido.ads)::
19174 * System.Partition_Interface (s-parint.ads)::
19175 * System.Pool_Global (s-pooglo.ads)::
19176 * System.Pool_Local (s-pooloc.ads)::
19177 * System.Restrictions (s-restri.ads)::
19178 * System.Rident (s-rident.ads)::
19179 * System.Strings.Stream_Ops (s-ststop.ads)::
19180 * System.Unsigned_Types (s-unstyp.ads)::
19181 * System.Wch_Cnv (s-wchcnv.ads)::
19182 * System.Wch_Con (s-wchcon.ads)::
19185 @node Ada.Characters.Latin_9 (a-chlat9.ads)
19186 @section @code{Ada.Characters.Latin_9} (@file{a-chlat9.ads})
19187 @cindex @code{Ada.Characters.Latin_9} (@file{a-chlat9.ads})
19188 @cindex Latin_9 constants for Character
19191 This child of @code{Ada.Characters}
19192 provides a set of definitions corresponding to those in the
19193 RM-defined package @code{Ada.Characters.Latin_1} but with the
19194 few modifications required for @code{Latin-9}
19195 The provision of such a package
19196 is specifically authorized by the Ada Reference Manual
19199 @node Ada.Characters.Wide_Latin_1 (a-cwila1.ads)
19200 @section @code{Ada.Characters.Wide_Latin_1} (@file{a-cwila1.ads})
19201 @cindex @code{Ada.Characters.Wide_Latin_1} (@file{a-cwila1.ads})
19202 @cindex Latin_1 constants for Wide_Character
19205 This child of @code{Ada.Characters}
19206 provides a set of definitions corresponding to those in the
19207 RM-defined package @code{Ada.Characters.Latin_1} but with the
19208 types of the constants being @code{Wide_Character}
19209 instead of @code{Character}. The provision of such a package
19210 is specifically authorized by the Ada Reference Manual
19213 @node Ada.Characters.Wide_Latin_9 (a-cwila9.ads)
19214 @section @code{Ada.Characters.Wide_Latin_9} (@file{a-cwila1.ads})
19215 @cindex @code{Ada.Characters.Wide_Latin_9} (@file{a-cwila1.ads})
19216 @cindex Latin_9 constants for Wide_Character
19219 This child of @code{Ada.Characters}
19220 provides a set of definitions corresponding to those in the
19221 GNAT defined package @code{Ada.Characters.Latin_9} but with the
19222 types of the constants being @code{Wide_Character}
19223 instead of @code{Character}. The provision of such a package
19224 is specifically authorized by the Ada Reference Manual
19227 @node Ada.Characters.Wide_Wide_Latin_1 (a-chzla1.ads)
19228 @section @code{Ada.Characters.Wide_Wide_Latin_1} (@file{a-chzla1.ads})
19229 @cindex @code{Ada.Characters.Wide_Wide_Latin_1} (@file{a-chzla1.ads})
19230 @cindex Latin_1 constants for Wide_Wide_Character
19233 This child of @code{Ada.Characters}
19234 provides a set of definitions corresponding to those in the
19235 RM-defined package @code{Ada.Characters.Latin_1} but with the
19236 types of the constants being @code{Wide_Wide_Character}
19237 instead of @code{Character}. The provision of such a package
19238 is specifically authorized by the Ada Reference Manual
19241 @node Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads)
19242 @section @code{Ada.Characters.Wide_Wide_Latin_9} (@file{a-chzla9.ads})
19243 @cindex @code{Ada.Characters.Wide_Wide_Latin_9} (@file{a-chzla9.ads})
19244 @cindex Latin_9 constants for Wide_Wide_Character
19247 This child of @code{Ada.Characters}
19248 provides a set of definitions corresponding to those in the
19249 GNAT defined package @code{Ada.Characters.Latin_9} but with the
19250 types of the constants being @code{Wide_Wide_Character}
19251 instead of @code{Character}. The provision of such a package
19252 is specifically authorized by the Ada Reference Manual
19255 @node Ada.Containers.Formal_Doubly_Linked_Lists (a-cfdlli.ads)
19256 @section @code{Ada.Containers.Formal_Doubly_Linked_Lists} (@file{a-cfdlli.ads})
19257 @cindex @code{Ada.Containers.Formal_Doubly_Linked_Lists} (@file{a-cfdlli.ads})
19258 @cindex Formal container for doubly linked lists
19261 This child of @code{Ada.Containers} defines a modified version of the
19262 Ada 2005 container for doubly linked lists, meant to facilitate formal
19263 verification of code using such containers. The specification of this
19264 unit is compatible with SPARK 2014.
19266 Note that although this container was designed with formal verification
19267 in mind, it may well be generally useful in that it is a simplified more
19268 efficient version than the one defined in the standard. In particular it
19269 does not have the complex overhead required to detect cursor tampering.
19271 @node Ada.Containers.Formal_Hashed_Maps (a-cfhama.ads)
19272 @section @code{Ada.Containers.Formal_Hashed_Maps} (@file{a-cfhama.ads})
19273 @cindex @code{Ada.Containers.Formal_Hashed_Maps} (@file{a-cfhama.ads})
19274 @cindex Formal container for hashed maps
19277 This child of @code{Ada.Containers} defines a modified version of the
19278 Ada 2005 container for hashed maps, meant to facilitate formal
19279 verification of code using such containers. The specification of this
19280 unit is compatible with SPARK 2014.
19282 Note that although this container was designed with formal verification
19283 in mind, it may well be generally useful in that it is a simplified more
19284 efficient version than the one defined in the standard. In particular it
19285 does not have the complex overhead required to detect cursor tampering.
19287 @node Ada.Containers.Formal_Hashed_Sets (a-cfhase.ads)
19288 @section @code{Ada.Containers.Formal_Hashed_Sets} (@file{a-cfhase.ads})
19289 @cindex @code{Ada.Containers.Formal_Hashed_Sets} (@file{a-cfhase.ads})
19290 @cindex Formal container for hashed sets
19293 This child of @code{Ada.Containers} defines a modified version of the
19294 Ada 2005 container for hashed sets, meant to facilitate formal
19295 verification of code using such containers. The specification of this
19296 unit is compatible with SPARK 2014.
19298 Note that although this container was designed with formal verification
19299 in mind, it may well be generally useful in that it is a simplified more
19300 efficient version than the one defined in the standard. In particular it
19301 does not have the complex overhead required to detect cursor tampering.
19303 @node Ada.Containers.Formal_Ordered_Maps (a-cforma.ads)
19304 @section @code{Ada.Containers.Formal_Ordered_Maps} (@file{a-cforma.ads})
19305 @cindex @code{Ada.Containers.Formal_Ordered_Maps} (@file{a-cforma.ads})
19306 @cindex Formal container for ordered maps
19309 This child of @code{Ada.Containers} defines a modified version of the
19310 Ada 2005 container for ordered maps, meant to facilitate formal
19311 verification of code using such containers. The specification of this
19312 unit is compatible with SPARK 2014.
19314 Note that although this container was designed with formal verification
19315 in mind, it may well be generally useful in that it is a simplified more
19316 efficient version than the one defined in the standard. In particular it
19317 does not have the complex overhead required to detect cursor tampering.
19319 @node Ada.Containers.Formal_Ordered_Sets (a-cforse.ads)
19320 @section @code{Ada.Containers.Formal_Ordered_Sets} (@file{a-cforse.ads})
19321 @cindex @code{Ada.Containers.Formal_Ordered_Sets} (@file{a-cforse.ads})
19322 @cindex Formal container for ordered sets
19325 This child of @code{Ada.Containers} defines a modified version of the
19326 Ada 2005 container for ordered sets, meant to facilitate formal
19327 verification of code using such containers. The specification of this
19328 unit is compatible with SPARK 2014.
19330 Note that although this container was designed with formal verification
19331 in mind, it may well be generally useful in that it is a simplified more
19332 efficient version than the one defined in the standard. In particular it
19333 does not have the complex overhead required to detect cursor tampering.
19335 @node Ada.Containers.Formal_Vectors (a-cofove.ads)
19336 @section @code{Ada.Containers.Formal_Vectors} (@file{a-cofove.ads})
19337 @cindex @code{Ada.Containers.Formal_Vectors} (@file{a-cofove.ads})
19338 @cindex Formal container for vectors
19341 This child of @code{Ada.Containers} defines a modified version of the
19342 Ada 2005 container for vectors, meant to facilitate formal
19343 verification of code using such containers. The specification of this
19344 unit is compatible with SPARK 2014.
19346 Note that although this container was designed with formal verification
19347 in mind, it may well be generally useful in that it is a simplified more
19348 efficient version than the one defined in the standard. In particular it
19349 does not have the complex overhead required to detect cursor tampering.
19351 @node Ada.Containers.Formal_Indefinite_Vectors (a-cfinve.ads)
19352 @section @code{Ada.Containers.Formal_Indefinite_Vectors} (@file{a-cfinve.ads})
19353 @cindex @code{Ada.Containers.Formal_Indefinite_Vectors} (@file{a-cfinve.ads})
19354 @cindex Formal container for vectors
19357 This child of @code{Ada.Containers} defines a modified version of the
19358 Ada 2005 container for vectors of indefinite elements, meant to
19359 facilitate formal verification of code using such containers. The
19360 specification of this unit is compatible with SPARK 2014.
19362 Note that although this container was designed with formal verification
19363 in mind, it may well be generally useful in that it is a simplified more
19364 efficient version than the one defined in the standard. In particular it
19365 does not have the complex overhead required to detect cursor tampering.
19367 @node Ada.Containers.Bounded_Holders (a-coboho.ads)
19368 @section @code{Ada.Containers.Bounded_Holders} (@file{a-coboho.ads})
19369 @cindex @code{Ada.Containers.Bounded_Holders} (@file{a-coboho.ads})
19370 @cindex Formal container for vectors
19373 This child of @code{Ada.Containers} defines a modified version of
19374 Indefinite_Holders that avoids heap allocation.
19376 @node Ada.Command_Line.Environment (a-colien.ads)
19377 @section @code{Ada.Command_Line.Environment} (@file{a-colien.ads})
19378 @cindex @code{Ada.Command_Line.Environment} (@file{a-colien.ads})
19379 @cindex Environment entries
19382 This child of @code{Ada.Command_Line}
19383 provides a mechanism for obtaining environment values on systems
19384 where this concept makes sense.
19386 @node Ada.Command_Line.Remove (a-colire.ads)
19387 @section @code{Ada.Command_Line.Remove} (@file{a-colire.ads})
19388 @cindex @code{Ada.Command_Line.Remove} (@file{a-colire.ads})
19389 @cindex Removing command line arguments
19390 @cindex Command line, argument removal
19393 This child of @code{Ada.Command_Line}
19394 provides a mechanism for logically removing
19395 arguments from the argument list. Once removed, an argument is not visible
19396 to further calls on the subprograms in @code{Ada.Command_Line} will not
19397 see the removed argument.
19399 @node Ada.Command_Line.Response_File (a-clrefi.ads)
19400 @section @code{Ada.Command_Line.Response_File} (@file{a-clrefi.ads})
19401 @cindex @code{Ada.Command_Line.Response_File} (@file{a-clrefi.ads})
19402 @cindex Response file for command line
19403 @cindex Command line, response file
19404 @cindex Command line, handling long command lines
19407 This child of @code{Ada.Command_Line} provides a mechanism facilities for
19408 getting command line arguments from a text file, called a "response file".
19409 Using a response file allow passing a set of arguments to an executable longer
19410 than the maximum allowed by the system on the command line.
19412 @node Ada.Direct_IO.C_Streams (a-diocst.ads)
19413 @section @code{Ada.Direct_IO.C_Streams} (@file{a-diocst.ads})
19414 @cindex @code{Ada.Direct_IO.C_Streams} (@file{a-diocst.ads})
19415 @cindex C Streams, Interfacing with Direct_IO
19418 This package provides subprograms that allow interfacing between
19419 C streams and @code{Direct_IO}. The stream identifier can be
19420 extracted from a file opened on the Ada side, and an Ada file
19421 can be constructed from a stream opened on the C side.
19423 @node Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads)
19424 @section @code{Ada.Exceptions.Is_Null_Occurrence} (@file{a-einuoc.ads})
19425 @cindex @code{Ada.Exceptions.Is_Null_Occurrence} (@file{a-einuoc.ads})
19426 @cindex Null_Occurrence, testing for
19429 This child subprogram provides a way of testing for the null
19430 exception occurrence (@code{Null_Occurrence}) without raising
19433 @node Ada.Exceptions.Last_Chance_Handler (a-elchha.ads)
19434 @section @code{Ada.Exceptions.Last_Chance_Handler} (@file{a-elchha.ads})
19435 @cindex @code{Ada.Exceptions.Last_Chance_Handler} (@file{a-elchha.ads})
19436 @cindex Null_Occurrence, testing for
19439 This child subprogram is used for handling otherwise unhandled
19440 exceptions (hence the name last chance), and perform clean ups before
19441 terminating the program. Note that this subprogram never returns.
19443 @node Ada.Exceptions.Traceback (a-exctra.ads)
19444 @section @code{Ada.Exceptions.Traceback} (@file{a-exctra.ads})
19445 @cindex @code{Ada.Exceptions.Traceback} (@file{a-exctra.ads})
19446 @cindex Traceback for Exception Occurrence
19449 This child package provides the subprogram (@code{Tracebacks}) to
19450 give a traceback array of addresses based on an exception
19453 @node Ada.Sequential_IO.C_Streams (a-siocst.ads)
19454 @section @code{Ada.Sequential_IO.C_Streams} (@file{a-siocst.ads})
19455 @cindex @code{Ada.Sequential_IO.C_Streams} (@file{a-siocst.ads})
19456 @cindex C Streams, Interfacing with Sequential_IO
19459 This package provides subprograms that allow interfacing between
19460 C streams and @code{Sequential_IO}. The stream identifier can be
19461 extracted from a file opened on the Ada side, and an Ada file
19462 can be constructed from a stream opened on the C side.
19464 @node Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads)
19465 @section @code{Ada.Streams.Stream_IO.C_Streams} (@file{a-ssicst.ads})
19466 @cindex @code{Ada.Streams.Stream_IO.C_Streams} (@file{a-ssicst.ads})
19467 @cindex C Streams, Interfacing with Stream_IO
19470 This package provides subprograms that allow interfacing between
19471 C streams and @code{Stream_IO}. The stream identifier can be
19472 extracted from a file opened on the Ada side, and an Ada file
19473 can be constructed from a stream opened on the C side.
19475 @node Ada.Strings.Unbounded.Text_IO (a-suteio.ads)
19476 @section @code{Ada.Strings.Unbounded.Text_IO} (@file{a-suteio.ads})
19477 @cindex @code{Ada.Strings.Unbounded.Text_IO} (@file{a-suteio.ads})
19478 @cindex @code{Unbounded_String}, IO support
19479 @cindex @code{Text_IO}, extensions for unbounded strings
19482 This package provides subprograms for Text_IO for unbounded
19483 strings, avoiding the necessity for an intermediate operation
19484 with ordinary strings.
19486 @node Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads)
19487 @section @code{Ada.Strings.Wide_Unbounded.Wide_Text_IO} (@file{a-swuwti.ads})
19488 @cindex @code{Ada.Strings.Wide_Unbounded.Wide_Text_IO} (@file{a-swuwti.ads})
19489 @cindex @code{Unbounded_Wide_String}, IO support
19490 @cindex @code{Text_IO}, extensions for unbounded wide strings
19493 This package provides subprograms for Text_IO for unbounded
19494 wide strings, avoiding the necessity for an intermediate operation
19495 with ordinary wide strings.
19497 @node Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads)
19498 @section @code{Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO} (@file{a-szuzti.ads})
19499 @cindex @code{Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO} (@file{a-szuzti.ads})
19500 @cindex @code{Unbounded_Wide_Wide_String}, IO support
19501 @cindex @code{Text_IO}, extensions for unbounded wide wide strings
19504 This package provides subprograms for Text_IO for unbounded
19505 wide wide strings, avoiding the necessity for an intermediate operation
19506 with ordinary wide wide strings.
19508 @node Ada.Text_IO.C_Streams (a-tiocst.ads)
19509 @section @code{Ada.Text_IO.C_Streams} (@file{a-tiocst.ads})
19510 @cindex @code{Ada.Text_IO.C_Streams} (@file{a-tiocst.ads})
19511 @cindex C Streams, Interfacing with @code{Text_IO}
19514 This package provides subprograms that allow interfacing between
19515 C streams and @code{Text_IO}. The stream identifier can be
19516 extracted from a file opened on the Ada side, and an Ada file
19517 can be constructed from a stream opened on the C side.
19519 @node Ada.Text_IO.Reset_Standard_Files (a-tirsfi.ads)
19520 @section @code{Ada.Text_IO.Reset_Standard_Files} (@file{a-tirsfi.ads})
19521 @cindex @code{Ada.Text_IO.Reset_Standard_Files} (@file{a-tirsfi.ads})
19522 @cindex @code{Text_IO} resetting standard files
19525 This procedure is used to reset the status of the standard files used
19526 by Ada.Text_IO. This is useful in a situation (such as a restart in an
19527 embedded application) where the status of the files may change during
19528 execution (for example a standard input file may be redefined to be
19531 @node Ada.Wide_Characters.Unicode (a-wichun.ads)
19532 @section @code{Ada.Wide_Characters.Unicode} (@file{a-wichun.ads})
19533 @cindex @code{Ada.Wide_Characters.Unicode} (@file{a-wichun.ads})
19534 @cindex Unicode categorization, Wide_Character
19537 This package provides subprograms that allow categorization of
19538 Wide_Character values according to Unicode categories.
19540 @node Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads)
19541 @section @code{Ada.Wide_Text_IO.C_Streams} (@file{a-wtcstr.ads})
19542 @cindex @code{Ada.Wide_Text_IO.C_Streams} (@file{a-wtcstr.ads})
19543 @cindex C Streams, Interfacing with @code{Wide_Text_IO}
19546 This package provides subprograms that allow interfacing between
19547 C streams and @code{Wide_Text_IO}. The stream identifier can be
19548 extracted from a file opened on the Ada side, and an Ada file
19549 can be constructed from a stream opened on the C side.
19551 @node Ada.Wide_Text_IO.Reset_Standard_Files (a-wrstfi.ads)
19552 @section @code{Ada.Wide_Text_IO.Reset_Standard_Files} (@file{a-wrstfi.ads})
19553 @cindex @code{Ada.Wide_Text_IO.Reset_Standard_Files} (@file{a-wrstfi.ads})
19554 @cindex @code{Wide_Text_IO} resetting standard files
19557 This procedure is used to reset the status of the standard files used
19558 by Ada.Wide_Text_IO. This is useful in a situation (such as a restart in an
19559 embedded application) where the status of the files may change during
19560 execution (for example a standard input file may be redefined to be
19563 @node Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads)
19564 @section @code{Ada.Wide_Wide_Characters.Unicode} (@file{a-zchuni.ads})
19565 @cindex @code{Ada.Wide_Wide_Characters.Unicode} (@file{a-zchuni.ads})
19566 @cindex Unicode categorization, Wide_Wide_Character
19569 This package provides subprograms that allow categorization of
19570 Wide_Wide_Character values according to Unicode categories.
19572 @node Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads)
19573 @section @code{Ada.Wide_Wide_Text_IO.C_Streams} (@file{a-ztcstr.ads})
19574 @cindex @code{Ada.Wide_Wide_Text_IO.C_Streams} (@file{a-ztcstr.ads})
19575 @cindex C Streams, Interfacing with @code{Wide_Wide_Text_IO}
19578 This package provides subprograms that allow interfacing between
19579 C streams and @code{Wide_Wide_Text_IO}. The stream identifier can be
19580 extracted from a file opened on the Ada side, and an Ada file
19581 can be constructed from a stream opened on the C side.
19583 @node Ada.Wide_Wide_Text_IO.Reset_Standard_Files (a-zrstfi.ads)
19584 @section @code{Ada.Wide_Wide_Text_IO.Reset_Standard_Files} (@file{a-zrstfi.ads})
19585 @cindex @code{Ada.Wide_Wide_Text_IO.Reset_Standard_Files} (@file{a-zrstfi.ads})
19586 @cindex @code{Wide_Wide_Text_IO} resetting standard files
19589 This procedure is used to reset the status of the standard files used
19590 by Ada.Wide_Wide_Text_IO. This is useful in a situation (such as a
19591 restart in an embedded application) where the status of the files may
19592 change during execution (for example a standard input file may be
19593 redefined to be interactive).
19595 @node GNAT.Altivec (g-altive.ads)
19596 @section @code{GNAT.Altivec} (@file{g-altive.ads})
19597 @cindex @code{GNAT.Altivec} (@file{g-altive.ads})
19601 This is the root package of the GNAT AltiVec binding. It provides
19602 definitions of constants and types common to all the versions of the
19605 @node GNAT.Altivec.Conversions (g-altcon.ads)
19606 @section @code{GNAT.Altivec.Conversions} (@file{g-altcon.ads})
19607 @cindex @code{GNAT.Altivec.Conversions} (@file{g-altcon.ads})
19611 This package provides the Vector/View conversion routines.
19613 @node GNAT.Altivec.Vector_Operations (g-alveop.ads)
19614 @section @code{GNAT.Altivec.Vector_Operations} (@file{g-alveop.ads})
19615 @cindex @code{GNAT.Altivec.Vector_Operations} (@file{g-alveop.ads})
19619 This package exposes the Ada interface to the AltiVec operations on
19620 vector objects. A soft emulation is included by default in the GNAT
19621 library. The hard binding is provided as a separate package. This unit
19622 is common to both bindings.
19624 @node GNAT.Altivec.Vector_Types (g-alvety.ads)
19625 @section @code{GNAT.Altivec.Vector_Types} (@file{g-alvety.ads})
19626 @cindex @code{GNAT.Altivec.Vector_Types} (@file{g-alvety.ads})
19630 This package exposes the various vector types part of the Ada binding
19631 to AltiVec facilities.
19633 @node GNAT.Altivec.Vector_Views (g-alvevi.ads)
19634 @section @code{GNAT.Altivec.Vector_Views} (@file{g-alvevi.ads})
19635 @cindex @code{GNAT.Altivec.Vector_Views} (@file{g-alvevi.ads})
19639 This package provides public 'View' data types from/to which private
19640 vector representations can be converted via
19641 GNAT.Altivec.Conversions. This allows convenient access to individual
19642 vector elements and provides a simple way to initialize vector
19645 @node GNAT.Array_Split (g-arrspl.ads)
19646 @section @code{GNAT.Array_Split} (@file{g-arrspl.ads})
19647 @cindex @code{GNAT.Array_Split} (@file{g-arrspl.ads})
19648 @cindex Array splitter
19651 Useful array-manipulation routines: given a set of separators, split
19652 an array wherever the separators appear, and provide direct access
19653 to the resulting slices.
19655 @node GNAT.AWK (g-awk.ads)
19656 @section @code{GNAT.AWK} (@file{g-awk.ads})
19657 @cindex @code{GNAT.AWK} (@file{g-awk.ads})
19662 Provides AWK-like parsing functions, with an easy interface for parsing one
19663 or more files containing formatted data. The file is viewed as a database
19664 where each record is a line and a field is a data element in this line.
19666 @node GNAT.Bounded_Buffers (g-boubuf.ads)
19667 @section @code{GNAT.Bounded_Buffers} (@file{g-boubuf.ads})
19668 @cindex @code{GNAT.Bounded_Buffers} (@file{g-boubuf.ads})
19670 @cindex Bounded Buffers
19673 Provides a concurrent generic bounded buffer abstraction. Instances are
19674 useful directly or as parts of the implementations of other abstractions,
19677 @node GNAT.Bounded_Mailboxes (g-boumai.ads)
19678 @section @code{GNAT.Bounded_Mailboxes} (@file{g-boumai.ads})
19679 @cindex @code{GNAT.Bounded_Mailboxes} (@file{g-boumai.ads})
19684 Provides a thread-safe asynchronous intertask mailbox communication facility.
19686 @node GNAT.Bubble_Sort (g-bubsor.ads)
19687 @section @code{GNAT.Bubble_Sort} (@file{g-bubsor.ads})
19688 @cindex @code{GNAT.Bubble_Sort} (@file{g-bubsor.ads})
19690 @cindex Bubble sort
19693 Provides a general implementation of bubble sort usable for sorting arbitrary
19694 data items. Exchange and comparison procedures are provided by passing
19695 access-to-procedure values.
19697 @node GNAT.Bubble_Sort_A (g-busora.ads)
19698 @section @code{GNAT.Bubble_Sort_A} (@file{g-busora.ads})
19699 @cindex @code{GNAT.Bubble_Sort_A} (@file{g-busora.ads})
19701 @cindex Bubble sort
19704 Provides a general implementation of bubble sort usable for sorting arbitrary
19705 data items. Move and comparison procedures are provided by passing
19706 access-to-procedure values. This is an older version, retained for
19707 compatibility. Usually @code{GNAT.Bubble_Sort} will be preferable.
19709 @node GNAT.Bubble_Sort_G (g-busorg.ads)
19710 @section @code{GNAT.Bubble_Sort_G} (@file{g-busorg.ads})
19711 @cindex @code{GNAT.Bubble_Sort_G} (@file{g-busorg.ads})
19713 @cindex Bubble sort
19716 Similar to @code{Bubble_Sort_A} except that the move and sorting procedures
19717 are provided as generic parameters, this improves efficiency, especially
19718 if the procedures can be inlined, at the expense of duplicating code for
19719 multiple instantiations.
19721 @node GNAT.Byte_Order_Mark (g-byorma.ads)
19722 @section @code{GNAT.Byte_Order_Mark} (@file{g-byorma.ads})
19723 @cindex @code{GNAT.Byte_Order_Mark} (@file{g-byorma.ads})
19724 @cindex UTF-8 representation
19725 @cindex Wide characte representations
19728 Provides a routine which given a string, reads the start of the string to
19729 see whether it is one of the standard byte order marks (BOM's) which signal
19730 the encoding of the string. The routine includes detection of special XML
19731 sequences for various UCS input formats.
19733 @node GNAT.Byte_Swapping (g-bytswa.ads)
19734 @section @code{GNAT.Byte_Swapping} (@file{g-bytswa.ads})
19735 @cindex @code{GNAT.Byte_Swapping} (@file{g-bytswa.ads})
19736 @cindex Byte swapping
19740 General routines for swapping the bytes in 2-, 4-, and 8-byte quantities.
19741 Machine-specific implementations are available in some cases.
19743 @node GNAT.Calendar (g-calend.ads)
19744 @section @code{GNAT.Calendar} (@file{g-calend.ads})
19745 @cindex @code{GNAT.Calendar} (@file{g-calend.ads})
19746 @cindex @code{Calendar}
19749 Extends the facilities provided by @code{Ada.Calendar} to include handling
19750 of days of the week, an extended @code{Split} and @code{Time_Of} capability.
19751 Also provides conversion of @code{Ada.Calendar.Time} values to and from the
19752 C @code{timeval} format.
19754 @node GNAT.Calendar.Time_IO (g-catiio.ads)
19755 @section @code{GNAT.Calendar.Time_IO} (@file{g-catiio.ads})
19756 @cindex @code{Calendar}
19758 @cindex @code{GNAT.Calendar.Time_IO} (@file{g-catiio.ads})
19760 @node GNAT.Case_Util (g-casuti.ads)
19761 @section @code{GNAT.Case_Util} (@file{g-casuti.ads})
19762 @cindex @code{GNAT.Case_Util} (@file{g-casuti.ads})
19763 @cindex Casing utilities
19764 @cindex Character handling (@code{GNAT.Case_Util})
19767 A set of simple routines for handling upper and lower casing of strings
19768 without the overhead of the full casing tables
19769 in @code{Ada.Characters.Handling}.
19771 @node GNAT.CGI (g-cgi.ads)
19772 @section @code{GNAT.CGI} (@file{g-cgi.ads})
19773 @cindex @code{GNAT.CGI} (@file{g-cgi.ads})
19774 @cindex CGI (Common Gateway Interface)
19777 This is a package for interfacing a GNAT program with a Web server via the
19778 Common Gateway Interface (CGI)@. Basically this package parses the CGI
19779 parameters, which are a set of key/value pairs sent by the Web server. It
19780 builds a table whose index is the key and provides some services to deal
19783 @node GNAT.CGI.Cookie (g-cgicoo.ads)
19784 @section @code{GNAT.CGI.Cookie} (@file{g-cgicoo.ads})
19785 @cindex @code{GNAT.CGI.Cookie} (@file{g-cgicoo.ads})
19786 @cindex CGI (Common Gateway Interface) cookie support
19787 @cindex Cookie support in CGI
19790 This is a package to interface a GNAT program with a Web server via the
19791 Common Gateway Interface (CGI). It exports services to deal with Web
19792 cookies (piece of information kept in the Web client software).
19794 @node GNAT.CGI.Debug (g-cgideb.ads)
19795 @section @code{GNAT.CGI.Debug} (@file{g-cgideb.ads})
19796 @cindex @code{GNAT.CGI.Debug} (@file{g-cgideb.ads})
19797 @cindex CGI (Common Gateway Interface) debugging
19800 This is a package to help debugging CGI (Common Gateway Interface)
19801 programs written in Ada.
19803 @node GNAT.Command_Line (g-comlin.ads)
19804 @section @code{GNAT.Command_Line} (@file{g-comlin.ads})
19805 @cindex @code{GNAT.Command_Line} (@file{g-comlin.ads})
19806 @cindex Command line
19809 Provides a high level interface to @code{Ada.Command_Line} facilities,
19810 including the ability to scan for named switches with optional parameters
19811 and expand file names using wild card notations.
19813 @node GNAT.Compiler_Version (g-comver.ads)
19814 @section @code{GNAT.Compiler_Version} (@file{g-comver.ads})
19815 @cindex @code{GNAT.Compiler_Version} (@file{g-comver.ads})
19816 @cindex Compiler Version
19817 @cindex Version, of compiler
19820 Provides a routine for obtaining the version of the compiler used to
19821 compile the program. More accurately this is the version of the binder
19822 used to bind the program (this will normally be the same as the version
19823 of the compiler if a consistent tool set is used to compile all units
19826 @node GNAT.Ctrl_C (g-ctrl_c.ads)
19827 @section @code{GNAT.Ctrl_C} (@file{g-ctrl_c.ads})
19828 @cindex @code{GNAT.Ctrl_C} (@file{g-ctrl_c.ads})
19832 Provides a simple interface to handle Ctrl-C keyboard events.
19834 @node GNAT.CRC32 (g-crc32.ads)
19835 @section @code{GNAT.CRC32} (@file{g-crc32.ads})
19836 @cindex @code{GNAT.CRC32} (@file{g-crc32.ads})
19838 @cindex Cyclic Redundancy Check
19841 This package implements the CRC-32 algorithm. For a full description
19842 of this algorithm see
19843 ``Computation of Cyclic Redundancy Checks via Table Look-Up'',
19844 @cite{Communications of the ACM}, Vol.@: 31 No.@: 8, pp.@: 1008-1013,
19845 Aug.@: 1988. Sarwate, D.V@.
19847 @node GNAT.Current_Exception (g-curexc.ads)
19848 @section @code{GNAT.Current_Exception} (@file{g-curexc.ads})
19849 @cindex @code{GNAT.Current_Exception} (@file{g-curexc.ads})
19850 @cindex Current exception
19851 @cindex Exception retrieval
19854 Provides access to information on the current exception that has been raised
19855 without the need for using the Ada 95 / Ada 2005 exception choice parameter
19856 specification syntax.
19857 This is particularly useful in simulating typical facilities for
19858 obtaining information about exceptions provided by Ada 83 compilers.
19860 @node GNAT.Debug_Pools (g-debpoo.ads)
19861 @section @code{GNAT.Debug_Pools} (@file{g-debpoo.ads})
19862 @cindex @code{GNAT.Debug_Pools} (@file{g-debpoo.ads})
19864 @cindex Debug pools
19865 @cindex Memory corruption debugging
19868 Provide a debugging storage pools that helps tracking memory corruption
19869 problems. @xref{The GNAT Debug Pool Facility,,, gnat_ugn,
19870 @value{EDITION} User's Guide}.
19872 @node GNAT.Debug_Utilities (g-debuti.ads)
19873 @section @code{GNAT.Debug_Utilities} (@file{g-debuti.ads})
19874 @cindex @code{GNAT.Debug_Utilities} (@file{g-debuti.ads})
19878 Provides a few useful utilities for debugging purposes, including conversion
19879 to and from string images of address values. Supports both C and Ada formats
19880 for hexadecimal literals.
19882 @node GNAT.Decode_String (g-decstr.ads)
19883 @section @code{GNAT.Decode_String} (@file{g-decstr.ads})
19884 @cindex @code{GNAT.Decode_String} (@file{g-decstr.ads})
19885 @cindex Decoding strings
19886 @cindex String decoding
19887 @cindex Wide character encoding
19892 A generic package providing routines for decoding wide character and wide wide
19893 character strings encoded as sequences of 8-bit characters using a specified
19894 encoding method. Includes validation routines, and also routines for stepping
19895 to next or previous encoded character in an encoded string.
19896 Useful in conjunction with Unicode character coding. Note there is a
19897 preinstantiation for UTF-8. See next entry.
19899 @node GNAT.Decode_UTF8_String (g-deutst.ads)
19900 @section @code{GNAT.Decode_UTF8_String} (@file{g-deutst.ads})
19901 @cindex @code{GNAT.Decode_UTF8_String} (@file{g-deutst.ads})
19902 @cindex Decoding strings
19903 @cindex Decoding UTF-8 strings
19904 @cindex UTF-8 string decoding
19905 @cindex Wide character decoding
19910 A preinstantiation of GNAT.Decode_Strings for UTF-8 encoding.
19912 @node GNAT.Directory_Operations (g-dirope.ads)
19913 @section @code{GNAT.Directory_Operations} (@file{g-dirope.ads})
19914 @cindex @code{GNAT.Directory_Operations} (@file{g-dirope.ads})
19915 @cindex Directory operations
19918 Provides a set of routines for manipulating directories, including changing
19919 the current directory, making new directories, and scanning the files in a
19922 @node GNAT.Directory_Operations.Iteration (g-diopit.ads)
19923 @section @code{GNAT.Directory_Operations.Iteration} (@file{g-diopit.ads})
19924 @cindex @code{GNAT.Directory_Operations.Iteration} (@file{g-diopit.ads})
19925 @cindex Directory operations iteration
19928 A child unit of GNAT.Directory_Operations providing additional operations
19929 for iterating through directories.
19931 @node GNAT.Dynamic_HTables (g-dynhta.ads)
19932 @section @code{GNAT.Dynamic_HTables} (@file{g-dynhta.ads})
19933 @cindex @code{GNAT.Dynamic_HTables} (@file{g-dynhta.ads})
19934 @cindex Hash tables
19937 A generic implementation of hash tables that can be used to hash arbitrary
19938 data. Provided in two forms, a simple form with built in hash functions,
19939 and a more complex form in which the hash function is supplied.
19942 This package provides a facility similar to that of @code{GNAT.HTable},
19943 except that this package declares a type that can be used to define
19944 dynamic instances of the hash table, while an instantiation of
19945 @code{GNAT.HTable} creates a single instance of the hash table.
19947 @node GNAT.Dynamic_Tables (g-dyntab.ads)
19948 @section @code{GNAT.Dynamic_Tables} (@file{g-dyntab.ads})
19949 @cindex @code{GNAT.Dynamic_Tables} (@file{g-dyntab.ads})
19950 @cindex Table implementation
19951 @cindex Arrays, extendable
19954 A generic package providing a single dimension array abstraction where the
19955 length of the array can be dynamically modified.
19958 This package provides a facility similar to that of @code{GNAT.Table},
19959 except that this package declares a type that can be used to define
19960 dynamic instances of the table, while an instantiation of
19961 @code{GNAT.Table} creates a single instance of the table type.
19963 @node GNAT.Encode_String (g-encstr.ads)
19964 @section @code{GNAT.Encode_String} (@file{g-encstr.ads})
19965 @cindex @code{GNAT.Encode_String} (@file{g-encstr.ads})
19966 @cindex Encoding strings
19967 @cindex String encoding
19968 @cindex Wide character encoding
19973 A generic package providing routines for encoding wide character and wide
19974 wide character strings as sequences of 8-bit characters using a specified
19975 encoding method. Useful in conjunction with Unicode character coding.
19976 Note there is a preinstantiation for UTF-8. See next entry.
19978 @node GNAT.Encode_UTF8_String (g-enutst.ads)
19979 @section @code{GNAT.Encode_UTF8_String} (@file{g-enutst.ads})
19980 @cindex @code{GNAT.Encode_UTF8_String} (@file{g-enutst.ads})
19981 @cindex Encoding strings
19982 @cindex Encoding UTF-8 strings
19983 @cindex UTF-8 string encoding
19984 @cindex Wide character encoding
19989 A preinstantiation of GNAT.Encode_Strings for UTF-8 encoding.
19991 @node GNAT.Exception_Actions (g-excact.ads)
19992 @section @code{GNAT.Exception_Actions} (@file{g-excact.ads})
19993 @cindex @code{GNAT.Exception_Actions} (@file{g-excact.ads})
19994 @cindex Exception actions
19997 Provides callbacks when an exception is raised. Callbacks can be registered
19998 for specific exceptions, or when any exception is raised. This
19999 can be used for instance to force a core dump to ease debugging.
20001 @node GNAT.Exception_Traces (g-exctra.ads)
20002 @section @code{GNAT.Exception_Traces} (@file{g-exctra.ads})
20003 @cindex @code{GNAT.Exception_Traces} (@file{g-exctra.ads})
20004 @cindex Exception traces
20008 Provides an interface allowing to control automatic output upon exception
20011 @node GNAT.Exceptions (g-except.ads)
20012 @section @code{GNAT.Exceptions} (@file{g-expect.ads})
20013 @cindex @code{GNAT.Exceptions} (@file{g-expect.ads})
20014 @cindex Exceptions, Pure
20015 @cindex Pure packages, exceptions
20018 Normally it is not possible to raise an exception with
20019 a message from a subprogram in a pure package, since the
20020 necessary types and subprograms are in @code{Ada.Exceptions}
20021 which is not a pure unit. @code{GNAT.Exceptions} provides a
20022 facility for getting around this limitation for a few
20023 predefined exceptions, and for example allow raising
20024 @code{Constraint_Error} with a message from a pure subprogram.
20026 @node GNAT.Expect (g-expect.ads)
20027 @section @code{GNAT.Expect} (@file{g-expect.ads})
20028 @cindex @code{GNAT.Expect} (@file{g-expect.ads})
20031 Provides a set of subprograms similar to what is available
20032 with the standard Tcl Expect tool.
20033 It allows you to easily spawn and communicate with an external process.
20034 You can send commands or inputs to the process, and compare the output
20035 with some expected regular expression. Currently @code{GNAT.Expect}
20036 is implemented on all native GNAT ports except for OpenVMS@.
20037 It is not implemented for cross ports, and in particular is not
20038 implemented for VxWorks or LynxOS@.
20040 @node GNAT.Expect.TTY (g-exptty.ads)
20041 @section @code{GNAT.Expect.TTY} (@file{g-exptty.ads})
20042 @cindex @code{GNAT.Expect.TTY} (@file{g-exptty.ads})
20045 As GNAT.Expect but using pseudo-terminal.
20046 Currently @code{GNAT.Expect.TTY} is implemented on all native GNAT
20047 ports except for OpenVMS@. It is not implemented for cross ports, and
20048 in particular is not implemented for VxWorks or LynxOS@.
20050 @node GNAT.Float_Control (g-flocon.ads)
20051 @section @code{GNAT.Float_Control} (@file{g-flocon.ads})
20052 @cindex @code{GNAT.Float_Control} (@file{g-flocon.ads})
20053 @cindex Floating-Point Processor
20056 Provides an interface for resetting the floating-point processor into the
20057 mode required for correct semantic operation in Ada. Some third party
20058 library calls may cause this mode to be modified, and the Reset procedure
20059 in this package can be used to reestablish the required mode.
20061 @node GNAT.Formatted_String (g-forstr.ads)
20062 @section @code{GNAT.Formatted_String} (@file{g-forstr.ads})
20063 @cindex @code{GNAT.Formatted_String} (@file{g-forstr.ads})
20064 @cindex Formatted String
20067 Provides support for C/C++ printf() formatted strings. The format is
20068 copied from the printf() routine and should therefore gives identical
20069 output. Some generic routines are provided to be able to use types
20070 derived from Integer, Float or enumerations as values for the
20073 @node GNAT.Heap_Sort (g-heasor.ads)
20074 @section @code{GNAT.Heap_Sort} (@file{g-heasor.ads})
20075 @cindex @code{GNAT.Heap_Sort} (@file{g-heasor.ads})
20079 Provides a general implementation of heap sort usable for sorting arbitrary
20080 data items. Exchange and comparison procedures are provided by passing
20081 access-to-procedure values. The algorithm used is a modified heap sort
20082 that performs approximately N*log(N) comparisons in the worst case.
20084 @node GNAT.Heap_Sort_A (g-hesora.ads)
20085 @section @code{GNAT.Heap_Sort_A} (@file{g-hesora.ads})
20086 @cindex @code{GNAT.Heap_Sort_A} (@file{g-hesora.ads})
20090 Provides a general implementation of heap sort usable for sorting arbitrary
20091 data items. Move and comparison procedures are provided by passing
20092 access-to-procedure values. The algorithm used is a modified heap sort
20093 that performs approximately N*log(N) comparisons in the worst case.
20094 This differs from @code{GNAT.Heap_Sort} in having a less convenient
20095 interface, but may be slightly more efficient.
20097 @node GNAT.Heap_Sort_G (g-hesorg.ads)
20098 @section @code{GNAT.Heap_Sort_G} (@file{g-hesorg.ads})
20099 @cindex @code{GNAT.Heap_Sort_G} (@file{g-hesorg.ads})
20103 Similar to @code{Heap_Sort_A} except that the move and sorting procedures
20104 are provided as generic parameters, this improves efficiency, especially
20105 if the procedures can be inlined, at the expense of duplicating code for
20106 multiple instantiations.
20108 @node GNAT.HTable (g-htable.ads)
20109 @section @code{GNAT.HTable} (@file{g-htable.ads})
20110 @cindex @code{GNAT.HTable} (@file{g-htable.ads})
20111 @cindex Hash tables
20114 A generic implementation of hash tables that can be used to hash arbitrary
20115 data. Provides two approaches, one a simple static approach, and the other
20116 allowing arbitrary dynamic hash tables.
20118 @node GNAT.IO (g-io.ads)
20119 @section @code{GNAT.IO} (@file{g-io.ads})
20120 @cindex @code{GNAT.IO} (@file{g-io.ads})
20122 @cindex Input/Output facilities
20125 A simple preelaborable input-output package that provides a subset of
20126 simple Text_IO functions for reading characters and strings from
20127 Standard_Input, and writing characters, strings and integers to either
20128 Standard_Output or Standard_Error.
20130 @node GNAT.IO_Aux (g-io_aux.ads)
20131 @section @code{GNAT.IO_Aux} (@file{g-io_aux.ads})
20132 @cindex @code{GNAT.IO_Aux} (@file{g-io_aux.ads})
20134 @cindex Input/Output facilities
20136 Provides some auxiliary functions for use with Text_IO, including a test
20137 for whether a file exists, and functions for reading a line of text.
20139 @node GNAT.Lock_Files (g-locfil.ads)
20140 @section @code{GNAT.Lock_Files} (@file{g-locfil.ads})
20141 @cindex @code{GNAT.Lock_Files} (@file{g-locfil.ads})
20142 @cindex File locking
20143 @cindex Locking using files
20146 Provides a general interface for using files as locks. Can be used for
20147 providing program level synchronization.
20149 @node GNAT.MBBS_Discrete_Random (g-mbdira.ads)
20150 @section @code{GNAT.MBBS_Discrete_Random} (@file{g-mbdira.ads})
20151 @cindex @code{GNAT.MBBS_Discrete_Random} (@file{g-mbdira.ads})
20152 @cindex Random number generation
20155 The original implementation of @code{Ada.Numerics.Discrete_Random}. Uses
20156 a modified version of the Blum-Blum-Shub generator.
20158 @node GNAT.MBBS_Float_Random (g-mbflra.ads)
20159 @section @code{GNAT.MBBS_Float_Random} (@file{g-mbflra.ads})
20160 @cindex @code{GNAT.MBBS_Float_Random} (@file{g-mbflra.ads})
20161 @cindex Random number generation
20164 The original implementation of @code{Ada.Numerics.Float_Random}. Uses
20165 a modified version of the Blum-Blum-Shub generator.
20167 @node GNAT.MD5 (g-md5.ads)
20168 @section @code{GNAT.MD5} (@file{g-md5.ads})
20169 @cindex @code{GNAT.MD5} (@file{g-md5.ads})
20170 @cindex Message Digest MD5
20173 Implements the MD5 Message-Digest Algorithm as described in RFC 1321, and
20174 the HMAC-MD5 message authentication function as described in RFC 2104 and
20177 @node GNAT.Memory_Dump (g-memdum.ads)
20178 @section @code{GNAT.Memory_Dump} (@file{g-memdum.ads})
20179 @cindex @code{GNAT.Memory_Dump} (@file{g-memdum.ads})
20180 @cindex Dump Memory
20183 Provides a convenient routine for dumping raw memory to either the
20184 standard output or standard error files. Uses GNAT.IO for actual
20187 @node GNAT.Most_Recent_Exception (g-moreex.ads)
20188 @section @code{GNAT.Most_Recent_Exception} (@file{g-moreex.ads})
20189 @cindex @code{GNAT.Most_Recent_Exception} (@file{g-moreex.ads})
20190 @cindex Exception, obtaining most recent
20193 Provides access to the most recently raised exception. Can be used for
20194 various logging purposes, including duplicating functionality of some
20195 Ada 83 implementation dependent extensions.
20197 @node GNAT.OS_Lib (g-os_lib.ads)
20198 @section @code{GNAT.OS_Lib} (@file{g-os_lib.ads})
20199 @cindex @code{GNAT.OS_Lib} (@file{g-os_lib.ads})
20200 @cindex Operating System interface
20201 @cindex Spawn capability
20204 Provides a range of target independent operating system interface functions,
20205 including time/date management, file operations, subprocess management,
20206 including a portable spawn procedure, and access to environment variables
20207 and error return codes.
20209 @node GNAT.Perfect_Hash_Generators (g-pehage.ads)
20210 @section @code{GNAT.Perfect_Hash_Generators} (@file{g-pehage.ads})
20211 @cindex @code{GNAT.Perfect_Hash_Generators} (@file{g-pehage.ads})
20212 @cindex Hash functions
20215 Provides a generator of static minimal perfect hash functions. No
20216 collisions occur and each item can be retrieved from the table in one
20217 probe (perfect property). The hash table size corresponds to the exact
20218 size of the key set and no larger (minimal property). The key set has to
20219 be know in advance (static property). The hash functions are also order
20220 preserving. If w2 is inserted after w1 in the generator, their
20221 hashcode are in the same order. These hashing functions are very
20222 convenient for use with realtime applications.
20224 @node GNAT.Random_Numbers (g-rannum.ads)
20225 @section @code{GNAT.Random_Numbers} (@file{g-rannum.ads})
20226 @cindex @code{GNAT.Random_Numbers} (@file{g-rannum.ads})
20227 @cindex Random number generation
20230 Provides random number capabilities which extend those available in the
20231 standard Ada library and are more convenient to use.
20233 @node GNAT.Regexp (g-regexp.ads)
20234 @section @code{GNAT.Regexp} (@file{g-regexp.ads})
20235 @cindex @code{GNAT.Regexp} (@file{g-regexp.ads})
20236 @cindex Regular expressions
20237 @cindex Pattern matching
20240 A simple implementation of regular expressions, using a subset of regular
20241 expression syntax copied from familiar Unix style utilities. This is the
20242 simplest of the three pattern matching packages provided, and is particularly
20243 suitable for ``file globbing'' applications.
20245 @node GNAT.Registry (g-regist.ads)
20246 @section @code{GNAT.Registry} (@file{g-regist.ads})
20247 @cindex @code{GNAT.Registry} (@file{g-regist.ads})
20248 @cindex Windows Registry
20251 This is a high level binding to the Windows registry. It is possible to
20252 do simple things like reading a key value, creating a new key. For full
20253 registry API, but at a lower level of abstraction, refer to the Win32.Winreg
20254 package provided with the Win32Ada binding
20256 @node GNAT.Regpat (g-regpat.ads)
20257 @section @code{GNAT.Regpat} (@file{g-regpat.ads})
20258 @cindex @code{GNAT.Regpat} (@file{g-regpat.ads})
20259 @cindex Regular expressions
20260 @cindex Pattern matching
20263 A complete implementation of Unix-style regular expression matching, copied
20264 from the original V7 style regular expression library written in C by
20265 Henry Spencer (and binary compatible with this C library).
20267 @node GNAT.Rewrite_Data (g-rewdat.ads)
20268 @section @code{GNAT.Rewrite_Data} (@file{g-rewdat.ads})
20269 @cindex @code{GNAT.Rewrite_Data} (@file{g-rewdat.ads})
20270 @cindex Rewrite data
20273 A unit to rewrite on-the-fly string occurrences in a stream of
20274 data. The implementation has a very minimal memory footprint as the
20275 full content to be processed is not loaded into memory all at once. This makes
20276 this interface usable for large files or socket streams.
20278 @node GNAT.Secondary_Stack_Info (g-sestin.ads)
20279 @section @code{GNAT.Secondary_Stack_Info} (@file{g-sestin.ads})
20280 @cindex @code{GNAT.Secondary_Stack_Info} (@file{g-sestin.ads})
20281 @cindex Secondary Stack Info
20284 Provide the capability to query the high water mark of the current task's
20287 @node GNAT.Semaphores (g-semaph.ads)
20288 @section @code{GNAT.Semaphores} (@file{g-semaph.ads})
20289 @cindex @code{GNAT.Semaphores} (@file{g-semaph.ads})
20293 Provides classic counting and binary semaphores using protected types.
20295 @node GNAT.Serial_Communications (g-sercom.ads)
20296 @section @code{GNAT.Serial_Communications} (@file{g-sercom.ads})
20297 @cindex @code{GNAT.Serial_Communications} (@file{g-sercom.ads})
20298 @cindex Serial_Communications
20301 Provides a simple interface to send and receive data over a serial
20302 port. This is only supported on GNU/Linux and Windows.
20304 @node GNAT.SHA1 (g-sha1.ads)
20305 @section @code{GNAT.SHA1} (@file{g-sha1.ads})
20306 @cindex @code{GNAT.SHA1} (@file{g-sha1.ads})
20307 @cindex Secure Hash Algorithm SHA-1
20310 Implements the SHA-1 Secure Hash Algorithm as described in FIPS PUB 180-3
20311 and RFC 3174, and the HMAC-SHA1 message authentication function as described
20312 in RFC 2104 and FIPS PUB 198.
20314 @node GNAT.SHA224 (g-sha224.ads)
20315 @section @code{GNAT.SHA224} (@file{g-sha224.ads})
20316 @cindex @code{GNAT.SHA224} (@file{g-sha224.ads})
20317 @cindex Secure Hash Algorithm SHA-224
20320 Implements the SHA-224 Secure Hash Algorithm as described in FIPS PUB 180-3,
20321 and the HMAC-SHA224 message authentication function as described
20322 in RFC 2104 and FIPS PUB 198.
20324 @node GNAT.SHA256 (g-sha256.ads)
20325 @section @code{GNAT.SHA256} (@file{g-sha256.ads})
20326 @cindex @code{GNAT.SHA256} (@file{g-sha256.ads})
20327 @cindex Secure Hash Algorithm SHA-256
20330 Implements the SHA-256 Secure Hash Algorithm as described in FIPS PUB 180-3,
20331 and the HMAC-SHA256 message authentication function as described
20332 in RFC 2104 and FIPS PUB 198.
20334 @node GNAT.SHA384 (g-sha384.ads)
20335 @section @code{GNAT.SHA384} (@file{g-sha384.ads})
20336 @cindex @code{GNAT.SHA384} (@file{g-sha384.ads})
20337 @cindex Secure Hash Algorithm SHA-384
20340 Implements the SHA-384 Secure Hash Algorithm as described in FIPS PUB 180-3,
20341 and the HMAC-SHA384 message authentication function as described
20342 in RFC 2104 and FIPS PUB 198.
20344 @node GNAT.SHA512 (g-sha512.ads)
20345 @section @code{GNAT.SHA512} (@file{g-sha512.ads})
20346 @cindex @code{GNAT.SHA512} (@file{g-sha512.ads})
20347 @cindex Secure Hash Algorithm SHA-512
20350 Implements the SHA-512 Secure Hash Algorithm as described in FIPS PUB 180-3,
20351 and the HMAC-SHA512 message authentication function as described
20352 in RFC 2104 and FIPS PUB 198.
20354 @node GNAT.Signals (g-signal.ads)
20355 @section @code{GNAT.Signals} (@file{g-signal.ads})
20356 @cindex @code{GNAT.Signals} (@file{g-signal.ads})
20360 Provides the ability to manipulate the blocked status of signals on supported
20363 @node GNAT.Sockets (g-socket.ads)
20364 @section @code{GNAT.Sockets} (@file{g-socket.ads})
20365 @cindex @code{GNAT.Sockets} (@file{g-socket.ads})
20369 A high level and portable interface to develop sockets based applications.
20370 This package is based on the sockets thin binding found in
20371 @code{GNAT.Sockets.Thin}. Currently @code{GNAT.Sockets} is implemented
20372 on all native GNAT ports except for OpenVMS@. It is not implemented
20373 for the LynxOS@ cross port.
20375 @node GNAT.Source_Info (g-souinf.ads)
20376 @section @code{GNAT.Source_Info} (@file{g-souinf.ads})
20377 @cindex @code{GNAT.Source_Info} (@file{g-souinf.ads})
20378 @cindex Source Information
20381 Provides subprograms that give access to source code information known at
20382 compile time, such as the current file name and line number. Also provides
20383 subprograms yielding the date and time of the current compilation (like the
20384 C macros @code{__DATE__} and @code{__TIME__})
20386 @node GNAT.Spelling_Checker (g-speche.ads)
20387 @section @code{GNAT.Spelling_Checker} (@file{g-speche.ads})
20388 @cindex @code{GNAT.Spelling_Checker} (@file{g-speche.ads})
20389 @cindex Spell checking
20392 Provides a function for determining whether one string is a plausible
20393 near misspelling of another string.
20395 @node GNAT.Spelling_Checker_Generic (g-spchge.ads)
20396 @section @code{GNAT.Spelling_Checker_Generic} (@file{g-spchge.ads})
20397 @cindex @code{GNAT.Spelling_Checker_Generic} (@file{g-spchge.ads})
20398 @cindex Spell checking
20401 Provides a generic function that can be instantiated with a string type for
20402 determining whether one string is a plausible near misspelling of another
20405 @node GNAT.Spitbol.Patterns (g-spipat.ads)
20406 @section @code{GNAT.Spitbol.Patterns} (@file{g-spipat.ads})
20407 @cindex @code{GNAT.Spitbol.Patterns} (@file{g-spipat.ads})
20408 @cindex SPITBOL pattern matching
20409 @cindex Pattern matching
20412 A complete implementation of SNOBOL4 style pattern matching. This is the
20413 most elaborate of the pattern matching packages provided. It fully duplicates
20414 the SNOBOL4 dynamic pattern construction and matching capabilities, using the
20415 efficient algorithm developed by Robert Dewar for the SPITBOL system.
20417 @node GNAT.Spitbol (g-spitbo.ads)
20418 @section @code{GNAT.Spitbol} (@file{g-spitbo.ads})
20419 @cindex @code{GNAT.Spitbol} (@file{g-spitbo.ads})
20420 @cindex SPITBOL interface
20423 The top level package of the collection of SPITBOL-style functionality, this
20424 package provides basic SNOBOL4 string manipulation functions, such as
20425 Pad, Reverse, Trim, Substr capability, as well as a generic table function
20426 useful for constructing arbitrary mappings from strings in the style of
20427 the SNOBOL4 TABLE function.
20429 @node GNAT.Spitbol.Table_Boolean (g-sptabo.ads)
20430 @section @code{GNAT.Spitbol.Table_Boolean} (@file{g-sptabo.ads})
20431 @cindex @code{GNAT.Spitbol.Table_Boolean} (@file{g-sptabo.ads})
20432 @cindex Sets of strings
20433 @cindex SPITBOL Tables
20436 A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table}
20437 for type @code{Standard.Boolean}, giving an implementation of sets of
20440 @node GNAT.Spitbol.Table_Integer (g-sptain.ads)
20441 @section @code{GNAT.Spitbol.Table_Integer} (@file{g-sptain.ads})
20442 @cindex @code{GNAT.Spitbol.Table_Integer} (@file{g-sptain.ads})
20443 @cindex Integer maps
20445 @cindex SPITBOL Tables
20448 A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table}
20449 for type @code{Standard.Integer}, giving an implementation of maps
20450 from string to integer values.
20452 @node GNAT.Spitbol.Table_VString (g-sptavs.ads)
20453 @section @code{GNAT.Spitbol.Table_VString} (@file{g-sptavs.ads})
20454 @cindex @code{GNAT.Spitbol.Table_VString} (@file{g-sptavs.ads})
20455 @cindex String maps
20457 @cindex SPITBOL Tables
20460 A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table} for
20461 a variable length string type, giving an implementation of general
20462 maps from strings to strings.
20464 @node GNAT.SSE (g-sse.ads)
20465 @section @code{GNAT.SSE} (@file{g-sse.ads})
20466 @cindex @code{GNAT.SSE} (@file{g-sse.ads})
20469 Root of a set of units aimed at offering Ada bindings to a subset of
20470 the Intel(r) Streaming SIMD Extensions with GNAT on the x86 family of
20471 targets. It exposes vector component types together with a general
20472 introduction to the binding contents and use.
20474 @node GNAT.SSE.Vector_Types (g-ssvety.ads)
20475 @section @code{GNAT.SSE.Vector_Types} (@file{g-ssvety.ads})
20476 @cindex @code{GNAT.SSE.Vector_Types} (@file{g-ssvety.ads})
20479 SSE vector types for use with SSE related intrinsics.
20481 @node GNAT.Strings (g-string.ads)
20482 @section @code{GNAT.Strings} (@file{g-string.ads})
20483 @cindex @code{GNAT.Strings} (@file{g-string.ads})
20486 Common String access types and related subprograms. Basically it
20487 defines a string access and an array of string access types.
20489 @node GNAT.String_Split (g-strspl.ads)
20490 @section @code{GNAT.String_Split} (@file{g-strspl.ads})
20491 @cindex @code{GNAT.String_Split} (@file{g-strspl.ads})
20492 @cindex String splitter
20495 Useful string manipulation routines: given a set of separators, split
20496 a string wherever the separators appear, and provide direct access
20497 to the resulting slices. This package is instantiated from
20498 @code{GNAT.Array_Split}.
20500 @node GNAT.Table (g-table.ads)
20501 @section @code{GNAT.Table} (@file{g-table.ads})
20502 @cindex @code{GNAT.Table} (@file{g-table.ads})
20503 @cindex Table implementation
20504 @cindex Arrays, extendable
20507 A generic package providing a single dimension array abstraction where the
20508 length of the array can be dynamically modified.
20511 This package provides a facility similar to that of @code{GNAT.Dynamic_Tables},
20512 except that this package declares a single instance of the table type,
20513 while an instantiation of @code{GNAT.Dynamic_Tables} creates a type that can be
20514 used to define dynamic instances of the table.
20516 @node GNAT.Task_Lock (g-tasloc.ads)
20517 @section @code{GNAT.Task_Lock} (@file{g-tasloc.ads})
20518 @cindex @code{GNAT.Task_Lock} (@file{g-tasloc.ads})
20519 @cindex Task synchronization
20520 @cindex Task locking
20524 A very simple facility for locking and unlocking sections of code using a
20525 single global task lock. Appropriate for use in situations where contention
20526 between tasks is very rarely expected.
20528 @node GNAT.Threads (g-thread.ads)
20529 @section @code{GNAT.Threads} (@file{g-thread.ads})
20530 @cindex @code{GNAT.Threads} (@file{g-thread.ads})
20531 @cindex Foreign threads
20532 @cindex Threads, foreign
20535 Provides facilities for dealing with foreign threads which need to be known
20536 by the GNAT run-time system. Consult the documentation of this package for
20537 further details if your program has threads that are created by a non-Ada
20538 environment which then accesses Ada code.
20540 @node GNAT.Time_Stamp (g-timsta.ads)
20541 @section @code{GNAT.Time_Stamp} (@file{g-timsta.ads})
20542 @cindex @code{GNAT.Time_Stamp} (@file{g-timsta.ads})
20544 @cindex Current time
20547 Provides a simple function that returns a string YYYY-MM-DD HH:MM:SS.SS that
20548 represents the current date and time in ISO 8601 format. This is a very simple
20549 routine with minimal code and there are no dependencies on any other unit.
20551 @node GNAT.Traceback (g-traceb.ads)
20552 @section @code{GNAT.Traceback} (@file{g-traceb.ads})
20553 @cindex @code{GNAT.Traceback} (@file{g-traceb.ads})
20554 @cindex Trace back facilities
20557 Provides a facility for obtaining non-symbolic traceback information, useful
20558 in various debugging situations.
20560 @node GNAT.Traceback.Symbolic (g-trasym.ads)
20561 @section @code{GNAT.Traceback.Symbolic} (@file{g-trasym.ads})
20562 @cindex @code{GNAT.Traceback.Symbolic} (@file{g-trasym.ads})
20563 @cindex Trace back facilities
20565 @node GNAT.UTF_32 (g-utf_32.ads)
20566 @section @code{GNAT.UTF_32} (@file{g-table.ads})
20567 @cindex @code{GNAT.UTF_32} (@file{g-table.ads})
20568 @cindex Wide character codes
20571 This is a package intended to be used in conjunction with the
20572 @code{Wide_Character} type in Ada 95 and the
20573 @code{Wide_Wide_Character} type in Ada 2005 (available
20574 in @code{GNAT} in Ada 2005 mode). This package contains
20575 Unicode categorization routines, as well as lexical
20576 categorization routines corresponding to the Ada 2005
20577 lexical rules for identifiers and strings, and also a
20578 lower case to upper case fold routine corresponding to
20579 the Ada 2005 rules for identifier equivalence.
20581 @node GNAT.UTF_32_Spelling_Checker (g-u3spch.ads)
20582 @section @code{GNAT.Wide_Spelling_Checker} (@file{g-u3spch.ads})
20583 @cindex @code{GNAT.Wide_Spelling_Checker} (@file{g-u3spch.ads})
20584 @cindex Spell checking
20587 Provides a function for determining whether one wide wide string is a plausible
20588 near misspelling of another wide wide string, where the strings are represented
20589 using the UTF_32_String type defined in System.Wch_Cnv.
20591 @node GNAT.Wide_Spelling_Checker (g-wispch.ads)
20592 @section @code{GNAT.Wide_Spelling_Checker} (@file{g-wispch.ads})
20593 @cindex @code{GNAT.Wide_Spelling_Checker} (@file{g-wispch.ads})
20594 @cindex Spell checking
20597 Provides a function for determining whether one wide string is a plausible
20598 near misspelling of another wide string.
20600 @node GNAT.Wide_String_Split (g-wistsp.ads)
20601 @section @code{GNAT.Wide_String_Split} (@file{g-wistsp.ads})
20602 @cindex @code{GNAT.Wide_String_Split} (@file{g-wistsp.ads})
20603 @cindex Wide_String splitter
20606 Useful wide string manipulation routines: given a set of separators, split
20607 a wide string wherever the separators appear, and provide direct access
20608 to the resulting slices. This package is instantiated from
20609 @code{GNAT.Array_Split}.
20611 @node GNAT.Wide_Wide_Spelling_Checker (g-zspche.ads)
20612 @section @code{GNAT.Wide_Wide_Spelling_Checker} (@file{g-zspche.ads})
20613 @cindex @code{GNAT.Wide_Wide_Spelling_Checker} (@file{g-zspche.ads})
20614 @cindex Spell checking
20617 Provides a function for determining whether one wide wide string is a plausible
20618 near misspelling of another wide wide string.
20620 @node GNAT.Wide_Wide_String_Split (g-zistsp.ads)
20621 @section @code{GNAT.Wide_Wide_String_Split} (@file{g-zistsp.ads})
20622 @cindex @code{GNAT.Wide_Wide_String_Split} (@file{g-zistsp.ads})
20623 @cindex Wide_Wide_String splitter
20626 Useful wide wide string manipulation routines: given a set of separators, split
20627 a wide wide string wherever the separators appear, and provide direct access
20628 to the resulting slices. This package is instantiated from
20629 @code{GNAT.Array_Split}.
20631 @node Interfaces.C.Extensions (i-cexten.ads)
20632 @section @code{Interfaces.C.Extensions} (@file{i-cexten.ads})
20633 @cindex @code{Interfaces.C.Extensions} (@file{i-cexten.ads})
20636 This package contains additional C-related definitions, intended
20637 for use with either manually or automatically generated bindings
20640 @node Interfaces.C.Streams (i-cstrea.ads)
20641 @section @code{Interfaces.C.Streams} (@file{i-cstrea.ads})
20642 @cindex @code{Interfaces.C.Streams} (@file{i-cstrea.ads})
20643 @cindex C streams, interfacing
20646 This package is a binding for the most commonly used operations
20649 @node Interfaces.Packed_Decimal (i-pacdec.ads)
20650 @section @code{Interfaces.Packed_Decimal} (@file{i-pacdec.ads})
20651 @cindex @code{Interfaces.Packed_Decimal} (@file{i-pacdec.ads})
20652 @cindex IBM Packed Format
20653 @cindex Packed Decimal
20656 This package provides a set of routines for conversions to and
20657 from a packed decimal format compatible with that used on IBM
20660 @node Interfaces.VxWorks (i-vxwork.ads)
20661 @section @code{Interfaces.VxWorks} (@file{i-vxwork.ads})
20662 @cindex @code{Interfaces.VxWorks} (@file{i-vxwork.ads})
20663 @cindex Interfacing to VxWorks
20664 @cindex VxWorks, interfacing
20667 This package provides a limited binding to the VxWorks API.
20668 In particular, it interfaces with the
20669 VxWorks hardware interrupt facilities.
20671 @node Interfaces.VxWorks.IO (i-vxwoio.ads)
20672 @section @code{Interfaces.VxWorks.IO} (@file{i-vxwoio.ads})
20673 @cindex @code{Interfaces.VxWorks.IO} (@file{i-vxwoio.ads})
20674 @cindex Interfacing to VxWorks' I/O
20675 @cindex VxWorks, I/O interfacing
20676 @cindex VxWorks, Get_Immediate
20677 @cindex Get_Immediate, VxWorks
20680 This package provides a binding to the ioctl (IO/Control)
20681 function of VxWorks, defining a set of option values and
20682 function codes. A particular use of this package is
20683 to enable the use of Get_Immediate under VxWorks.
20685 @node System.Address_Image (s-addima.ads)
20686 @section @code{System.Address_Image} (@file{s-addima.ads})
20687 @cindex @code{System.Address_Image} (@file{s-addima.ads})
20688 @cindex Address image
20689 @cindex Image, of an address
20692 This function provides a useful debugging
20693 function that gives an (implementation dependent)
20694 string which identifies an address.
20696 @node System.Assertions (s-assert.ads)
20697 @section @code{System.Assertions} (@file{s-assert.ads})
20698 @cindex @code{System.Assertions} (@file{s-assert.ads})
20700 @cindex Assert_Failure, exception
20703 This package provides the declaration of the exception raised
20704 by an run-time assertion failure, as well as the routine that
20705 is used internally to raise this assertion.
20707 @node System.Atomic_Counters (s-atocou.ads)
20708 @section @code{System.Atomic_Counters} (@file{s-atocou.ads})
20709 @cindex @code{System.Atomic_Counters} (@file{s-atocou.ads})
20712 This package provides the declaration of an atomic counter type,
20713 together with efficient routines (using hardware
20714 synchronization primitives) for incrementing, decrementing,
20715 and testing of these counters. This package is implemented
20716 on most targets, including all Alpha, ia64, PowerPC, SPARC V9,
20717 x86, and x86_64 platforms.
20719 @node System.Memory (s-memory.ads)
20720 @section @code{System.Memory} (@file{s-memory.ads})
20721 @cindex @code{System.Memory} (@file{s-memory.ads})
20722 @cindex Memory allocation
20725 This package provides the interface to the low level routines used
20726 by the generated code for allocation and freeing storage for the
20727 default storage pool (analogous to the C routines malloc and free.
20728 It also provides a reallocation interface analogous to the C routine
20729 realloc. The body of this unit may be modified to provide alternative
20730 allocation mechanisms for the default pool, and in addition, direct
20731 calls to this unit may be made for low level allocation uses (for
20732 example see the body of @code{GNAT.Tables}).
20734 @node System.Multiprocessors (s-multip.ads)
20735 @section @code{System.Multiprocessors} (@file{s-multip.ads})
20736 @cindex @code{System.Multiprocessors} (@file{s-multip.ads})
20737 @cindex Multiprocessor interface
20738 This is an Ada 2012 unit defined in the Ada 2012 Reference Manual, but
20739 in GNAT we also make it available in Ada 95 and Ada 2005 (where it is
20740 technically an implementation-defined addition).
20742 @node System.Multiprocessors.Dispatching_Domains (s-mudido.ads)
20743 @section @code{System.Multiprocessors.Dispatching_Domains} (@file{s-mudido.ads})
20744 @cindex @code{System.Multiprocessors.Dispatching_Domains} (@file{s-mudido.ads})
20745 @cindex Multiprocessor interface
20746 This is an Ada 2012 unit defined in the Ada 2012 Reference Manual, but
20747 in GNAT we also make it available in Ada 95 and Ada 2005 (where it is
20748 technically an implementation-defined addition).
20750 @node System.Partition_Interface (s-parint.ads)
20751 @section @code{System.Partition_Interface} (@file{s-parint.ads})
20752 @cindex @code{System.Partition_Interface} (@file{s-parint.ads})
20753 @cindex Partition interfacing functions
20756 This package provides facilities for partition interfacing. It
20757 is used primarily in a distribution context when using Annex E
20760 @node System.Pool_Global (s-pooglo.ads)
20761 @section @code{System.Pool_Global} (@file{s-pooglo.ads})
20762 @cindex @code{System.Pool_Global} (@file{s-pooglo.ads})
20763 @cindex Storage pool, global
20764 @cindex Global storage pool
20767 This package provides a storage pool that is equivalent to the default
20768 storage pool used for access types for which no pool is specifically
20769 declared. It uses malloc/free to allocate/free and does not attempt to
20770 do any automatic reclamation.
20772 @node System.Pool_Local (s-pooloc.ads)
20773 @section @code{System.Pool_Local} (@file{s-pooloc.ads})
20774 @cindex @code{System.Pool_Local} (@file{s-pooloc.ads})
20775 @cindex Storage pool, local
20776 @cindex Local storage pool
20779 This package provides a storage pool that is intended for use with locally
20780 defined access types. It uses malloc/free for allocate/free, and maintains
20781 a list of allocated blocks, so that all storage allocated for the pool can
20782 be freed automatically when the pool is finalized.
20784 @node System.Restrictions (s-restri.ads)
20785 @section @code{System.Restrictions} (@file{s-restri.ads})
20786 @cindex @code{System.Restrictions} (@file{s-restri.ads})
20787 @cindex Run-time restrictions access
20790 This package provides facilities for accessing at run time
20791 the status of restrictions specified at compile time for
20792 the partition. Information is available both with regard
20793 to actual restrictions specified, and with regard to
20794 compiler determined information on which restrictions
20795 are violated by one or more packages in the partition.
20797 @node System.Rident (s-rident.ads)
20798 @section @code{System.Rident} (@file{s-rident.ads})
20799 @cindex @code{System.Rident} (@file{s-rident.ads})
20800 @cindex Restrictions definitions
20803 This package provides definitions of the restrictions
20804 identifiers supported by GNAT, and also the format of
20805 the restrictions provided in package System.Restrictions.
20806 It is not normally necessary to @code{with} this generic package
20807 since the necessary instantiation is included in
20808 package System.Restrictions.
20810 @node System.Strings.Stream_Ops (s-ststop.ads)
20811 @section @code{System.Strings.Stream_Ops} (@file{s-ststop.ads})
20812 @cindex @code{System.Strings.Stream_Ops} (@file{s-ststop.ads})
20813 @cindex Stream operations
20814 @cindex String stream operations
20817 This package provides a set of stream subprograms for standard string types.
20818 It is intended primarily to support implicit use of such subprograms when
20819 stream attributes are applied to string types, but the subprograms in this
20820 package can be used directly by application programs.
20822 @node System.Unsigned_Types (s-unstyp.ads)
20823 @section @code{System.Unsigned_Types} (@file{s-unstyp.ads})
20824 @cindex @code{System.Unsigned_Types} (@file{s-unstyp.ads})
20827 This package contains definitions of standard unsigned types that
20828 correspond in size to the standard signed types declared in Standard,
20829 and (unlike the types in Interfaces) have corresponding names. It
20830 also contains some related definitions for other specialized types
20831 used by the compiler in connection with packed array types.
20833 @node System.Wch_Cnv (s-wchcnv.ads)
20834 @section @code{System.Wch_Cnv} (@file{s-wchcnv.ads})
20835 @cindex @code{System.Wch_Cnv} (@file{s-wchcnv.ads})
20836 @cindex Wide Character, Representation
20837 @cindex Wide String, Conversion
20838 @cindex Representation of wide characters
20841 This package provides routines for converting between
20842 wide and wide wide characters and a representation as a value of type
20843 @code{Standard.String}, using a specified wide character
20844 encoding method. It uses definitions in
20845 package @code{System.Wch_Con}.
20847 @node System.Wch_Con (s-wchcon.ads)
20848 @section @code{System.Wch_Con} (@file{s-wchcon.ads})
20849 @cindex @code{System.Wch_Con} (@file{s-wchcon.ads})
20852 This package provides definitions and descriptions of
20853 the various methods used for encoding wide characters
20854 in ordinary strings. These definitions are used by
20855 the package @code{System.Wch_Cnv}.
20857 @node Interfacing to Other Languages
20858 @chapter Interfacing to Other Languages
20860 The facilities in annex B of the Ada Reference Manual are fully
20861 implemented in GNAT, and in addition, a full interface to C++ is
20865 * Interfacing to C::
20866 * Interfacing to C++::
20867 * Interfacing to COBOL::
20868 * Interfacing to Fortran::
20869 * Interfacing to non-GNAT Ada code::
20872 @node Interfacing to C
20873 @section Interfacing to C
20876 Interfacing to C with GNAT can use one of two approaches:
20880 The types in the package @code{Interfaces.C} may be used.
20882 Standard Ada types may be used directly. This may be less portable to
20883 other compilers, but will work on all GNAT compilers, which guarantee
20884 correspondence between the C and Ada types.
20888 Pragma @code{Convention C} may be applied to Ada types, but mostly has no
20889 effect, since this is the default. The following table shows the
20890 correspondence between Ada scalar types and the corresponding C types.
20895 @item Short_Integer
20897 @item Short_Short_Integer
20901 @item Long_Long_Integer
20909 @item Long_Long_Float
20910 This is the longest floating-point type supported by the hardware.
20914 Additionally, there are the following general correspondences between Ada
20918 Ada enumeration types map to C enumeration types directly if pragma
20919 @code{Convention C} is specified, which causes them to have int
20920 length. Without pragma @code{Convention C}, Ada enumeration types map to
20921 8, 16, or 32 bits (i.e.@: C types @code{signed char}, @code{short},
20922 @code{int}, respectively) depending on the number of values passed.
20923 This is the only case in which pragma @code{Convention C} affects the
20924 representation of an Ada type.
20927 Ada access types map to C pointers, except for the case of pointers to
20928 unconstrained types in Ada, which have no direct C equivalent.
20931 Ada arrays map directly to C arrays.
20934 Ada records map directly to C structures.
20937 Packed Ada records map to C structures where all members are bit fields
20938 of the length corresponding to the @code{@var{type}'Size} value in Ada.
20941 @node Interfacing to C++
20942 @section Interfacing to C++
20945 The interface to C++ makes use of the following pragmas, which are
20946 primarily intended to be constructed automatically using a binding generator
20947 tool, although it is possible to construct them by hand.
20949 Using these pragmas it is possible to achieve complete
20950 inter-operability between Ada tagged types and C++ class definitions.
20951 See @ref{Implementation Defined Pragmas}, for more details.
20954 @item pragma CPP_Class ([Entity =>] @var{LOCAL_NAME})
20955 The argument denotes an entity in the current declarative region that is
20956 declared as a tagged or untagged record type. It indicates that the type
20957 corresponds to an externally declared C++ class type, and is to be laid
20958 out the same way that C++ would lay out the type.
20960 Note: Pragma @code{CPP_Class} is currently obsolete. It is supported
20961 for backward compatibility but its functionality is available
20962 using pragma @code{Import} with @code{Convention} = @code{CPP}.
20964 @item pragma CPP_Constructor ([Entity =>] @var{LOCAL_NAME})
20965 This pragma identifies an imported function (imported in the usual way
20966 with pragma @code{Import}) as corresponding to a C++ constructor.
20969 A few restrictions are placed on the use of the @code{Access} attribute
20970 in conjunction with subprograms subject to convention @code{CPP}: the
20971 attribute may be used neither on primitive operations of a tagged
20972 record type with convention @code{CPP}, imported or not, nor on
20973 subprograms imported with pragma @code{CPP_Constructor}.
20975 In addition, C++ exceptions are propagated and can be handled in an
20976 @code{others} choice of an exception handler. The corresponding Ada
20977 occurrence has no message, and the simple name of the exception identity
20978 contains @samp{Foreign_Exception}. Finalization and awaiting dependent
20979 tasks works properly when such foreign exceptions are propagated.
20981 It is also possible to import a C++ exception using the following syntax:
20983 @smallexample @c ada
20984 LOCAL_NAME : exception;
20985 pragma Import (Cpp,
20986 [Entity =>] LOCAL_NAME,
20987 [External_Name =>] static_string_EXPRESSION);
20991 The @code{External_Name} is the name of the C++ RTTI symbol. You can then
20992 cover a specific C++ exception in an exception handler.
20994 @node Interfacing to COBOL
20995 @section Interfacing to COBOL
20998 Interfacing to COBOL is achieved as described in section B.4 of
20999 the Ada Reference Manual.
21001 @node Interfacing to Fortran
21002 @section Interfacing to Fortran
21005 Interfacing to Fortran is achieved as described in section B.5 of the
21006 Ada Reference Manual. The pragma @code{Convention Fortran}, applied to a
21007 multi-dimensional array causes the array to be stored in column-major
21008 order as required for convenient interface to Fortran.
21010 @node Interfacing to non-GNAT Ada code
21011 @section Interfacing to non-GNAT Ada code
21013 It is possible to specify the convention @code{Ada} in a pragma
21014 @code{Import} or pragma @code{Export}. However this refers to
21015 the calling conventions used by GNAT, which may or may not be
21016 similar enough to those used by some other Ada 83 / Ada 95 / Ada 2005
21017 compiler to allow interoperation.
21019 If arguments types are kept simple, and if the foreign compiler generally
21020 follows system calling conventions, then it may be possible to integrate
21021 files compiled by other Ada compilers, provided that the elaboration
21022 issues are adequately addressed (for example by eliminating the
21023 need for any load time elaboration).
21025 In particular, GNAT running on VMS is designed to
21026 be highly compatible with the DEC Ada 83 compiler, so this is one
21027 case in which it is possible to import foreign units of this type,
21028 provided that the data items passed are restricted to simple scalar
21029 values or simple record types without variants, or simple array
21030 types with fixed bounds.
21032 @node Specialized Needs Annexes
21033 @chapter Specialized Needs Annexes
21036 Ada 95 and Ada 2005 define a number of Specialized Needs Annexes, which are not
21037 required in all implementations. However, as described in this chapter,
21038 GNAT implements all of these annexes:
21041 @item Systems Programming (Annex C)
21042 The Systems Programming Annex is fully implemented.
21044 @item Real-Time Systems (Annex D)
21045 The Real-Time Systems Annex is fully implemented.
21047 @item Distributed Systems (Annex E)
21048 Stub generation is fully implemented in the GNAT compiler. In addition,
21049 a complete compatible PCS is available as part of the GLADE system,
21050 a separate product. When the two
21051 products are used in conjunction, this annex is fully implemented.
21053 @item Information Systems (Annex F)
21054 The Information Systems annex is fully implemented.
21056 @item Numerics (Annex G)
21057 The Numerics Annex is fully implemented.
21059 @item Safety and Security / High-Integrity Systems (Annex H)
21060 The Safety and Security Annex (termed the High-Integrity Systems Annex
21061 in Ada 2005) is fully implemented.
21064 @node Implementation of Specific Ada Features
21065 @chapter Implementation of Specific Ada Features
21068 This chapter describes the GNAT implementation of several Ada language
21072 * Machine Code Insertions::
21073 * GNAT Implementation of Tasking::
21074 * GNAT Implementation of Shared Passive Packages::
21075 * Code Generation for Array Aggregates::
21076 * The Size of Discriminated Records with Default Discriminants::
21077 * Strict Conformance to the Ada Reference Manual::
21080 @node Machine Code Insertions
21081 @section Machine Code Insertions
21082 @cindex Machine Code insertions
21085 Package @code{Machine_Code} provides machine code support as described
21086 in the Ada Reference Manual in two separate forms:
21089 Machine code statements, consisting of qualified expressions that
21090 fit the requirements of RM section 13.8.
21092 An intrinsic callable procedure, providing an alternative mechanism of
21093 including machine instructions in a subprogram.
21097 The two features are similar, and both are closely related to the mechanism
21098 provided by the asm instruction in the GNU C compiler. Full understanding
21099 and use of the facilities in this package requires understanding the asm
21100 instruction, see @ref{Extended Asm,,, gcc, Using the GNU Compiler
21103 Calls to the function @code{Asm} and the procedure @code{Asm} have identical
21104 semantic restrictions and effects as described below. Both are provided so
21105 that the procedure call can be used as a statement, and the function call
21106 can be used to form a code_statement.
21108 Consider this C @code{asm} instruction:
21110 asm ("fsinx %1 %0" : "=f" (result) : "f" (angle));
21114 The equivalent can be written for GNAT as:
21116 @smallexample @c ada
21117 Asm ("fsinx %1 %0",
21118 My_Float'Asm_Output ("=f", result),
21119 My_Float'Asm_Input ("f", angle));
21123 The first argument to @code{Asm} is the assembler template, and is
21124 identical to what is used in GNU C@. This string must be a static
21125 expression. The second argument is the output operand list. It is
21126 either a single @code{Asm_Output} attribute reference, or a list of such
21127 references enclosed in parentheses (technically an array aggregate of
21130 The @code{Asm_Output} attribute denotes a function that takes two
21131 parameters. The first is a string, the second is the name of a variable
21132 of the type designated by the attribute prefix. The first (string)
21133 argument is required to be a static expression and designates the
21134 constraint (@pxref{Constraints,,, gcc, Using the GNU Compiler
21136 for the parameter (e.g.@: what kind of register is required). The second
21137 argument is the variable to be written or updated with the
21138 result. The possible values for constraint are the same as those used in
21139 the RTL, and are dependent on the configuration file used to build the
21140 GCC back end. If there are no output operands, then this argument may
21141 either be omitted, or explicitly given as @code{No_Output_Operands}.
21142 No support is provided for GNU C's symbolic names for output parameters.
21144 The second argument of @code{@var{my_float}'Asm_Output} functions as
21145 though it were an @code{out} parameter, which is a little curious, but
21146 all names have the form of expressions, so there is no syntactic
21147 irregularity, even though normally functions would not be permitted
21148 @code{out} parameters. The third argument is the list of input
21149 operands. It is either a single @code{Asm_Input} attribute reference, or
21150 a list of such references enclosed in parentheses (technically an array
21151 aggregate of such references).
21153 The @code{Asm_Input} attribute denotes a function that takes two
21154 parameters. The first is a string, the second is an expression of the
21155 type designated by the prefix. The first (string) argument is required
21156 to be a static expression, and is the constraint for the parameter,
21157 (e.g.@: what kind of register is required). The second argument is the
21158 value to be used as the input argument. The possible values for the
21159 constraint are the same as those used in the RTL, and are dependent on
21160 the configuration file used to built the GCC back end.
21161 No support is provided for GNU C's symbolic names for input parameters.
21163 If there are no input operands, this argument may either be omitted, or
21164 explicitly given as @code{No_Input_Operands}. The fourth argument, not
21165 present in the above example, is a list of register names, called the
21166 @dfn{clobber} argument. This argument, if given, must be a static string
21167 expression, and is a space or comma separated list of names of registers
21168 that must be considered destroyed as a result of the @code{Asm} call. If
21169 this argument is the null string (the default value), then the code
21170 generator assumes that no additional registers are destroyed.
21171 In addition to registers, the special clobbers @code{memory} and
21172 @code{cc} as described in the GNU C docs are both supported.
21174 The fifth argument, not present in the above example, called the
21175 @dfn{volatile} argument, is by default @code{False}. It can be set to
21176 the literal value @code{True} to indicate to the code generator that all
21177 optimizations with respect to the instruction specified should be
21178 suppressed, and in particular an instruction that has outputs
21179 will still be generated, even if none of the outputs are
21180 used. @xref{Volatile,,,
21181 gcc, Using the GNU Compiler Collection (GCC)}, for the full description.
21182 Generally it is strongly advisable to use Volatile for any ASM statement
21183 that is missing either input or output operands or to avoid unwanted
21184 optimizations. A warning is generated if this advice is not followed.
21186 No support is provided for GNU C's @code{asm goto} feature.
21188 The @code{Asm} subprograms may be used in two ways. First the procedure
21189 forms can be used anywhere a procedure call would be valid, and
21190 correspond to what the RM calls ``intrinsic'' routines. Such calls can
21191 be used to intersperse machine instructions with other Ada statements.
21192 Second, the function forms, which return a dummy value of the limited
21193 private type @code{Asm_Insn}, can be used in code statements, and indeed
21194 this is the only context where such calls are allowed. Code statements
21195 appear as aggregates of the form:
21197 @smallexample @c ada
21198 Asm_Insn'(Asm (@dots{}));
21199 Asm_Insn'(Asm_Volatile (@dots{}));
21203 In accordance with RM rules, such code statements are allowed only
21204 within subprograms whose entire body consists of such statements. It is
21205 not permissible to intermix such statements with other Ada statements.
21207 Typically the form using intrinsic procedure calls is more convenient
21208 and more flexible. The code statement form is provided to meet the RM
21209 suggestion that such a facility should be made available. The following
21210 is the exact syntax of the call to @code{Asm}. As usual, if named notation
21211 is used, the arguments may be given in arbitrary order, following the
21212 normal rules for use of positional and named arguments:
21216 [Template =>] static_string_EXPRESSION
21217 [,[Outputs =>] OUTPUT_OPERAND_LIST ]
21218 [,[Inputs =>] INPUT_OPERAND_LIST ]
21219 [,[Clobber =>] static_string_EXPRESSION ]
21220 [,[Volatile =>] static_boolean_EXPRESSION] )
21222 OUTPUT_OPERAND_LIST ::=
21223 [PREFIX.]No_Output_Operands
21224 | OUTPUT_OPERAND_ATTRIBUTE
21225 | (OUTPUT_OPERAND_ATTRIBUTE @{,OUTPUT_OPERAND_ATTRIBUTE@})
21227 OUTPUT_OPERAND_ATTRIBUTE ::=
21228 SUBTYPE_MARK'Asm_Output (static_string_EXPRESSION, NAME)
21230 INPUT_OPERAND_LIST ::=
21231 [PREFIX.]No_Input_Operands
21232 | INPUT_OPERAND_ATTRIBUTE
21233 | (INPUT_OPERAND_ATTRIBUTE @{,INPUT_OPERAND_ATTRIBUTE@})
21235 INPUT_OPERAND_ATTRIBUTE ::=
21236 SUBTYPE_MARK'Asm_Input (static_string_EXPRESSION, EXPRESSION)
21240 The identifiers @code{No_Input_Operands} and @code{No_Output_Operands}
21241 are declared in the package @code{Machine_Code} and must be referenced
21242 according to normal visibility rules. In particular if there is no
21243 @code{use} clause for this package, then appropriate package name
21244 qualification is required.
21246 @node GNAT Implementation of Tasking
21247 @section GNAT Implementation of Tasking
21250 This chapter outlines the basic GNAT approach to tasking (in particular,
21251 a multi-layered library for portability) and discusses issues related
21252 to compliance with the Real-Time Systems Annex.
21255 * Mapping Ada Tasks onto the Underlying Kernel Threads::
21256 * Ensuring Compliance with the Real-Time Annex::
21259 @node Mapping Ada Tasks onto the Underlying Kernel Threads
21260 @subsection Mapping Ada Tasks onto the Underlying Kernel Threads
21263 GNAT's run-time support comprises two layers:
21266 @item GNARL (GNAT Run-time Layer)
21267 @item GNULL (GNAT Low-level Library)
21271 In GNAT, Ada's tasking services rely on a platform and OS independent
21272 layer known as GNARL@. This code is responsible for implementing the
21273 correct semantics of Ada's task creation, rendezvous, protected
21276 GNARL decomposes Ada's tasking semantics into simpler lower level
21277 operations such as create a thread, set the priority of a thread,
21278 yield, create a lock, lock/unlock, etc. The spec for these low-level
21279 operations constitutes GNULLI, the GNULL Interface. This interface is
21280 directly inspired from the POSIX real-time API@.
21282 If the underlying executive or OS implements the POSIX standard
21283 faithfully, the GNULL Interface maps as is to the services offered by
21284 the underlying kernel. Otherwise, some target dependent glue code maps
21285 the services offered by the underlying kernel to the semantics expected
21288 Whatever the underlying OS (VxWorks, UNIX, Windows, etc.) the
21289 key point is that each Ada task is mapped on a thread in the underlying
21290 kernel. For example, in the case of VxWorks, one Ada task = one VxWorks task.
21292 In addition Ada task priorities map onto the underlying thread priorities.
21293 Mapping Ada tasks onto the underlying kernel threads has several advantages:
21297 The underlying scheduler is used to schedule the Ada tasks. This
21298 makes Ada tasks as efficient as kernel threads from a scheduling
21302 Interaction with code written in C containing threads is eased
21303 since at the lowest level Ada tasks and C threads map onto the same
21304 underlying kernel concept.
21307 When an Ada task is blocked during I/O the remaining Ada tasks are
21311 On multiprocessor systems Ada tasks can execute in parallel.
21315 Some threads libraries offer a mechanism to fork a new process, with the
21316 child process duplicating the threads from the parent.
21318 support this functionality when the parent contains more than one task.
21319 @cindex Forking a new process
21321 @node Ensuring Compliance with the Real-Time Annex
21322 @subsection Ensuring Compliance with the Real-Time Annex
21323 @cindex Real-Time Systems Annex compliance
21326 Although mapping Ada tasks onto
21327 the underlying threads has significant advantages, it does create some
21328 complications when it comes to respecting the scheduling semantics
21329 specified in the real-time annex (Annex D).
21331 For instance the Annex D requirement for the @code{FIFO_Within_Priorities}
21332 scheduling policy states:
21335 @emph{When the active priority of a ready task that is not running
21336 changes, or the setting of its base priority takes effect, the
21337 task is removed from the ready queue for its old active priority
21338 and is added at the tail of the ready queue for its new active
21339 priority, except in the case where the active priority is lowered
21340 due to the loss of inherited priority, in which case the task is
21341 added at the head of the ready queue for its new active priority.}
21345 While most kernels do put tasks at the end of the priority queue when
21346 a task changes its priority, (which respects the main
21347 FIFO_Within_Priorities requirement), almost none keep a thread at the
21348 beginning of its priority queue when its priority drops from the loss
21349 of inherited priority.
21351 As a result most vendors have provided incomplete Annex D implementations.
21353 The GNAT run-time, has a nice cooperative solution to this problem
21354 which ensures that accurate FIFO_Within_Priorities semantics are
21357 The principle is as follows. When an Ada task T is about to start
21358 running, it checks whether some other Ada task R with the same
21359 priority as T has been suspended due to the loss of priority
21360 inheritance. If this is the case, T yields and is placed at the end of
21361 its priority queue. When R arrives at the front of the queue it
21364 Note that this simple scheme preserves the relative order of the tasks
21365 that were ready to execute in the priority queue where R has been
21368 @node GNAT Implementation of Shared Passive Packages
21369 @section GNAT Implementation of Shared Passive Packages
21370 @cindex Shared passive packages
21373 GNAT fully implements the pragma @code{Shared_Passive} for
21374 @cindex pragma @code{Shared_Passive}
21375 the purpose of designating shared passive packages.
21376 This allows the use of passive partitions in the
21377 context described in the Ada Reference Manual; i.e., for communication
21378 between separate partitions of a distributed application using the
21379 features in Annex E.
21381 @cindex Distribution Systems Annex
21383 However, the implementation approach used by GNAT provides for more
21384 extensive usage as follows:
21387 @item Communication between separate programs
21389 This allows separate programs to access the data in passive
21390 partitions, using protected objects for synchronization where
21391 needed. The only requirement is that the two programs have a
21392 common shared file system. It is even possible for programs
21393 running on different machines with different architectures
21394 (e.g.@: different endianness) to communicate via the data in
21395 a passive partition.
21397 @item Persistence between program runs
21399 The data in a passive package can persist from one run of a
21400 program to another, so that a later program sees the final
21401 values stored by a previous run of the same program.
21406 The implementation approach used is to store the data in files. A
21407 separate stream file is created for each object in the package, and
21408 an access to an object causes the corresponding file to be read or
21411 The environment variable @code{SHARED_MEMORY_DIRECTORY} should be
21412 @cindex @code{SHARED_MEMORY_DIRECTORY} environment variable
21413 set to the directory to be used for these files.
21414 The files in this directory
21415 have names that correspond to their fully qualified names. For
21416 example, if we have the package
21418 @smallexample @c ada
21420 pragma Shared_Passive (X);
21427 and the environment variable is set to @code{/stemp/}, then the files created
21428 will have the names:
21436 These files are created when a value is initially written to the object, and
21437 the files are retained until manually deleted. This provides the persistence
21438 semantics. If no file exists, it means that no partition has assigned a value
21439 to the variable; in this case the initial value declared in the package
21440 will be used. This model ensures that there are no issues in synchronizing
21441 the elaboration process, since elaboration of passive packages elaborates the
21442 initial values, but does not create the files.
21444 The files are written using normal @code{Stream_IO} access.
21445 If you want to be able
21446 to communicate between programs or partitions running on different
21447 architectures, then you should use the XDR versions of the stream attribute
21448 routines, since these are architecture independent.
21450 If active synchronization is required for access to the variables in the
21451 shared passive package, then as described in the Ada Reference Manual, the
21452 package may contain protected objects used for this purpose. In this case
21453 a lock file (whose name is @file{___lock} (three underscores)
21454 is created in the shared memory directory.
21455 @cindex @file{___lock} file (for shared passive packages)
21456 This is used to provide the required locking
21457 semantics for proper protected object synchronization.
21459 As of January 2003, GNAT supports shared passive packages on all platforms
21460 except for OpenVMS.
21462 @node Code Generation for Array Aggregates
21463 @section Code Generation for Array Aggregates
21466 * Static constant aggregates with static bounds::
21467 * Constant aggregates with unconstrained nominal types::
21468 * Aggregates with static bounds::
21469 * Aggregates with non-static bounds::
21470 * Aggregates in assignment statements::
21474 Aggregates have a rich syntax and allow the user to specify the values of
21475 complex data structures by means of a single construct. As a result, the
21476 code generated for aggregates can be quite complex and involve loops, case
21477 statements and multiple assignments. In the simplest cases, however, the
21478 compiler will recognize aggregates whose components and constraints are
21479 fully static, and in those cases the compiler will generate little or no
21480 executable code. The following is an outline of the code that GNAT generates
21481 for various aggregate constructs. For further details, you will find it
21482 useful to examine the output produced by the -gnatG flag to see the expanded
21483 source that is input to the code generator. You may also want to examine
21484 the assembly code generated at various levels of optimization.
21486 The code generated for aggregates depends on the context, the component values,
21487 and the type. In the context of an object declaration the code generated is
21488 generally simpler than in the case of an assignment. As a general rule, static
21489 component values and static subtypes also lead to simpler code.
21491 @node Static constant aggregates with static bounds
21492 @subsection Static constant aggregates with static bounds
21495 For the declarations:
21496 @smallexample @c ada
21497 type One_Dim is array (1..10) of integer;
21498 ar0 : constant One_Dim := (1, 2, 3, 4, 5, 6, 7, 8, 9, 0);
21502 GNAT generates no executable code: the constant ar0 is placed in static memory.
21503 The same is true for constant aggregates with named associations:
21505 @smallexample @c ada
21506 Cr1 : constant One_Dim := (4 => 16, 2 => 4, 3 => 9, 1 => 1, 5 .. 10 => 0);
21507 Cr3 : constant One_Dim := (others => 7777);
21511 The same is true for multidimensional constant arrays such as:
21513 @smallexample @c ada
21514 type two_dim is array (1..3, 1..3) of integer;
21515 Unit : constant two_dim := ( (1,0,0), (0,1,0), (0,0,1));
21519 The same is true for arrays of one-dimensional arrays: the following are
21522 @smallexample @c ada
21523 type ar1b is array (1..3) of boolean;
21524 type ar_ar is array (1..3) of ar1b;
21525 None : constant ar1b := (others => false); -- fully static
21526 None2 : constant ar_ar := (1..3 => None); -- fully static
21530 However, for multidimensional aggregates with named associations, GNAT will
21531 generate assignments and loops, even if all associations are static. The
21532 following two declarations generate a loop for the first dimension, and
21533 individual component assignments for the second dimension:
21535 @smallexample @c ada
21536 Zero1: constant two_dim := (1..3 => (1..3 => 0));
21537 Zero2: constant two_dim := (others => (others => 0));
21540 @node Constant aggregates with unconstrained nominal types
21541 @subsection Constant aggregates with unconstrained nominal types
21544 In such cases the aggregate itself establishes the subtype, so that
21545 associations with @code{others} cannot be used. GNAT determines the
21546 bounds for the actual subtype of the aggregate, and allocates the
21547 aggregate statically as well. No code is generated for the following:
21549 @smallexample @c ada
21550 type One_Unc is array (natural range <>) of integer;
21551 Cr_Unc : constant One_Unc := (12,24,36);
21554 @node Aggregates with static bounds
21555 @subsection Aggregates with static bounds
21558 In all previous examples the aggregate was the initial (and immutable) value
21559 of a constant. If the aggregate initializes a variable, then code is generated
21560 for it as a combination of individual assignments and loops over the target
21561 object. The declarations
21563 @smallexample @c ada
21564 Cr_Var1 : One_Dim := (2, 5, 7, 11, 0, 0, 0, 0, 0, 0);
21565 Cr_Var2 : One_Dim := (others > -1);
21569 generate the equivalent of
21571 @smallexample @c ada
21577 for I in Cr_Var2'range loop
21582 @node Aggregates with non-static bounds
21583 @subsection Aggregates with non-static bounds
21586 If the bounds of the aggregate are not statically compatible with the bounds
21587 of the nominal subtype of the target, then constraint checks have to be
21588 generated on the bounds. For a multidimensional array, constraint checks may
21589 have to be applied to sub-arrays individually, if they do not have statically
21590 compatible subtypes.
21592 @node Aggregates in assignment statements
21593 @subsection Aggregates in assignment statements
21596 In general, aggregate assignment requires the construction of a temporary,
21597 and a copy from the temporary to the target of the assignment. This is because
21598 it is not always possible to convert the assignment into a series of individual
21599 component assignments. For example, consider the simple case:
21601 @smallexample @c ada
21606 This cannot be converted into:
21608 @smallexample @c ada
21614 So the aggregate has to be built first in a separate location, and then
21615 copied into the target. GNAT recognizes simple cases where this intermediate
21616 step is not required, and the assignments can be performed in place, directly
21617 into the target. The following sufficient criteria are applied:
21621 The bounds of the aggregate are static, and the associations are static.
21623 The components of the aggregate are static constants, names of
21624 simple variables that are not renamings, or expressions not involving
21625 indexed components whose operands obey these rules.
21629 If any of these conditions are violated, the aggregate will be built in
21630 a temporary (created either by the front-end or the code generator) and then
21631 that temporary will be copied onto the target.
21633 @node The Size of Discriminated Records with Default Discriminants
21634 @section The Size of Discriminated Records with Default Discriminants
21637 If a discriminated type @code{T} has discriminants with default values, it is
21638 possible to declare an object of this type without providing an explicit
21641 @smallexample @c ada
21643 type Size is range 1..100;
21645 type Rec (D : Size := 15) is record
21646 Name : String (1..D);
21654 Such an object is said to be @emph{unconstrained}.
21655 The discriminant of the object
21656 can be modified by a full assignment to the object, as long as it preserves the
21657 relation between the value of the discriminant, and the value of the components
21660 @smallexample @c ada
21662 Word := (3, "yes");
21664 Word := (5, "maybe");
21666 Word := (5, "no"); -- raises Constraint_Error
21671 In order to support this behavior efficiently, an unconstrained object is
21672 given the maximum size that any value of the type requires. In the case
21673 above, @code{Word} has storage for the discriminant and for
21674 a @code{String} of length 100.
21675 It is important to note that unconstrained objects do not require dynamic
21676 allocation. It would be an improper implementation to place on the heap those
21677 components whose size depends on discriminants. (This improper implementation
21678 was used by some Ada83 compilers, where the @code{Name} component above
21680 been stored as a pointer to a dynamic string). Following the principle that
21681 dynamic storage management should never be introduced implicitly,
21682 an Ada compiler should reserve the full size for an unconstrained declared
21683 object, and place it on the stack.
21685 This maximum size approach
21686 has been a source of surprise to some users, who expect the default
21687 values of the discriminants to determine the size reserved for an
21688 unconstrained object: ``If the default is 15, why should the object occupy
21690 The answer, of course, is that the discriminant may be later modified,
21691 and its full range of values must be taken into account. This is why the
21696 type Rec (D : Positive := 15) is record
21697 Name : String (1..D);
21705 is flagged by the compiler with a warning:
21706 an attempt to create @code{Too_Large} will raise @code{Storage_Error},
21707 because the required size includes @code{Positive'Last}
21708 bytes. As the first example indicates, the proper approach is to declare an
21709 index type of ``reasonable'' range so that unconstrained objects are not too
21712 One final wrinkle: if the object is declared to be @code{aliased}, or if it is
21713 created in the heap by means of an allocator, then it is @emph{not}
21715 it is constrained by the default values of the discriminants, and those values
21716 cannot be modified by full assignment. This is because in the presence of
21717 aliasing all views of the object (which may be manipulated by different tasks,
21718 say) must be consistent, so it is imperative that the object, once created,
21721 @node Strict Conformance to the Ada Reference Manual
21722 @section Strict Conformance to the Ada Reference Manual
21725 The dynamic semantics defined by the Ada Reference Manual impose a set of
21726 run-time checks to be generated. By default, the GNAT compiler will insert many
21727 run-time checks into the compiled code, including most of those required by the
21728 Ada Reference Manual. However, there are three checks that are not enabled
21729 in the default mode for efficiency reasons: arithmetic overflow checking for
21730 integer operations (including division by zero), checks for access before
21731 elaboration on subprogram calls, and stack overflow checking (most operating
21732 systems do not perform this check by default).
21734 Strict conformance to the Ada Reference Manual can be achieved by adding
21735 three compiler options for overflow checking for integer operations
21736 (@option{-gnato}), dynamic checks for access-before-elaboration on subprogram
21737 calls and generic instantiations (@option{-gnatE}), and stack overflow
21738 checking (@option{-fstack-check}).
21740 Note that the result of a floating point arithmetic operation in overflow and
21741 invalid situations, when the @code{Machine_Overflows} attribute of the result
21742 type is @code{False}, is to generate IEEE NaN and infinite values. This is the
21743 case for machines compliant with the IEEE floating-point standard, but on
21744 machines that are not fully compliant with this standard, such as Alpha, the
21745 @option{-mieee} compiler flag must be used for achieving IEEE confirming
21746 behavior (although at the cost of a significant performance penalty), so
21747 infinite and NaN values are properly generated.
21750 @node Implementation of Ada 2012 Features
21751 @chapter Implementation of Ada 2012 Features
21752 @cindex Ada 2012 implementation status
21754 This chapter contains a complete list of Ada 2012 features that have been
21755 implemented as of GNAT version 6.4. Generally, these features are only
21756 available if the @option{-gnat12} (Ada 2012 features enabled) flag is set
21757 @cindex @option{-gnat12} option
21758 or if the configuration pragma @code{Ada_2012} is used.
21759 @cindex pragma @code{Ada_2012}
21760 @cindex configuration pragma @code{Ada_2012}
21761 @cindex @code{Ada_2012} configuration pragma
21762 However, new pragmas, attributes, and restrictions are
21763 unconditionally available, since the Ada 95 standard allows the addition of
21764 new pragmas, attributes, and restrictions (there are exceptions, which are
21765 documented in the individual descriptions), and also certain packages
21766 were made available in earlier versions of Ada.
21768 An ISO date (YYYY-MM-DD) appears in parentheses on the description line.
21769 This date shows the implementation date of the feature. Any wavefront
21770 subsequent to this date will contain the indicated feature, as will any
21771 subsequent releases. A date of 0000-00-00 means that GNAT has always
21772 implemented the feature, or implemented it as soon as it appeared as a
21773 binding interpretation.
21775 Each feature corresponds to an Ada Issue (``AI'') approved by the Ada
21776 standardization group (ISO/IEC JTC1/SC22/WG9) for inclusion in Ada 2012.
21777 The features are ordered based on the relevant sections of the Ada
21778 Reference Manual (``RM''). When a given AI relates to multiple points
21779 in the RM, the earliest is used.
21781 A complete description of the AIs may be found in
21782 @url{www.ada-auth.org/ai05-summary.html}.
21787 @emph{AI-0176 Quantified expressions (2010-09-29)}
21788 @cindex AI-0176 (Ada 2012 feature)
21791 Both universally and existentially quantified expressions are implemented.
21792 They use the new syntax for iterators proposed in AI05-139-2, as well as
21793 the standard Ada loop syntax.
21796 RM References: 1.01.04 (12) 2.09 (2/2) 4.04 (7) 4.05.09 (0)
21799 @emph{AI-0079 Allow @i{other_format} characters in source (2010-07-10)}
21800 @cindex AI-0079 (Ada 2012 feature)
21803 Wide characters in the unicode category @i{other_format} are now allowed in
21804 source programs between tokens, but not within a token such as an identifier.
21807 RM References: 2.01 (4/2) 2.02 (7)
21810 @emph{AI-0091 Do not allow @i{other_format} in identifiers (0000-00-00)}
21811 @cindex AI-0091 (Ada 2012 feature)
21814 Wide characters in the unicode category @i{other_format} are not permitted
21815 within an identifier, since this can be a security problem. The error
21816 message for this case has been improved to be more specific, but GNAT has
21817 never allowed such characters to appear in identifiers.
21820 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)
21823 @emph{AI-0100 Placement of pragmas (2010-07-01)}
21824 @cindex AI-0100 (Ada 2012 feature)
21827 This AI is an earlier version of AI-163. It simplifies the rules
21828 for legal placement of pragmas. In the case of lists that allow pragmas, if
21829 the list may have no elements, then the list may consist solely of pragmas.
21832 RM References: 2.08 (7)
21835 @emph{AI-0163 Pragmas in place of null (2010-07-01)}
21836 @cindex AI-0163 (Ada 2012 feature)
21839 A statement sequence may be composed entirely of pragmas. It is no longer
21840 necessary to add a dummy @code{null} statement to make the sequence legal.
21843 RM References: 2.08 (7) 2.08 (16)
21847 @emph{AI-0080 ``View of'' not needed if clear from context (0000-00-00)}
21848 @cindex AI-0080 (Ada 2012 feature)
21851 This is an editorial change only, described as non-testable in the AI.
21854 RM References: 3.01 (7)
21858 @emph{AI-0183 Aspect specifications (2010-08-16)}
21859 @cindex AI-0183 (Ada 2012 feature)
21862 Aspect specifications have been fully implemented except for pre and post-
21863 conditions, and type invariants, which have their own separate AI's. All
21864 forms of declarations listed in the AI are supported. The following is a
21865 list of the aspects supported (with GNAT implementation aspects marked)
21867 @multitable {@code{Preelaborable_Initialization}} {--GNAT}
21868 @item @code{Ada_2005} @tab -- GNAT
21869 @item @code{Ada_2012} @tab -- GNAT
21870 @item @code{Address} @tab
21871 @item @code{Alignment} @tab
21872 @item @code{Atomic} @tab
21873 @item @code{Atomic_Components} @tab
21874 @item @code{Bit_Order} @tab
21875 @item @code{Component_Size} @tab
21876 @item @code{Contract_Cases} @tab -- GNAT
21877 @item @code{Discard_Names} @tab
21878 @item @code{External_Tag} @tab
21879 @item @code{Favor_Top_Level} @tab -- GNAT
21880 @item @code{Inline} @tab
21881 @item @code{Inline_Always} @tab -- GNAT
21882 @item @code{Invariant} @tab -- GNAT
21883 @item @code{Machine_Radix} @tab
21884 @item @code{No_Return} @tab
21885 @item @code{Object_Size} @tab -- GNAT
21886 @item @code{Pack} @tab
21887 @item @code{Persistent_BSS} @tab -- GNAT
21888 @item @code{Post} @tab
21889 @item @code{Pre} @tab
21890 @item @code{Predicate} @tab
21891 @item @code{Preelaborable_Initialization} @tab
21892 @item @code{Pure_Function} @tab -- GNAT
21893 @item @code{Remote_Access_Type} @tab -- GNAT
21894 @item @code{Shared} @tab -- GNAT
21895 @item @code{Size} @tab
21896 @item @code{Storage_Pool} @tab
21897 @item @code{Storage_Size} @tab
21898 @item @code{Stream_Size} @tab
21899 @item @code{Suppress} @tab
21900 @item @code{Suppress_Debug_Info} @tab -- GNAT
21901 @item @code{Test_Case} @tab -- GNAT
21902 @item @code{Thread_Local_Storage} @tab -- GNAT
21903 @item @code{Type_Invariant} @tab
21904 @item @code{Unchecked_Union} @tab
21905 @item @code{Universal_Aliasing} @tab -- GNAT
21906 @item @code{Unmodified} @tab -- GNAT
21907 @item @code{Unreferenced} @tab -- GNAT
21908 @item @code{Unreferenced_Objects} @tab -- GNAT
21909 @item @code{Unsuppress} @tab
21910 @item @code{Value_Size} @tab -- GNAT
21911 @item @code{Volatile} @tab
21912 @item @code{Volatile_Components}
21913 @item @code{Warnings} @tab -- GNAT
21917 Note that for aspects with an expression, e.g. @code{Size}, the expression is
21918 treated like a default expression (visibility is analyzed at the point of
21919 occurrence of the aspect, but evaluation of the expression occurs at the
21920 freeze point of the entity involved).
21923 RM References: 3.02.01 (3) 3.02.02 (2) 3.03.01 (2/2) 3.08 (6)
21924 3.09.03 (1.1/2) 6.01 (2/2) 6.07 (2/2) 9.05.02 (2/2) 7.01 (3) 7.03
21925 (2) 7.03 (3) 9.01 (2/2) 9.01 (3/2) 9.04 (2/2) 9.04 (3/2)
21926 9.05.02 (2/2) 11.01 (2) 12.01 (3) 12.03 (2/2) 12.04 (2/2) 12.05 (2)
21927 12.06 (2.1/2) 12.06 (2.2/2) 12.07 (2) 13.01 (0.1/2) 13.03 (5/1)
21932 @emph{AI-0128 Inequality is a primitive operation (0000-00-00)}
21933 @cindex AI-0128 (Ada 2012 feature)
21936 If an equality operator ("=") is declared for a type, then the implicitly
21937 declared inequality operator ("/=") is a primitive operation of the type.
21938 This is the only reasonable interpretation, and is the one always implemented
21939 by GNAT, but the RM was not entirely clear in making this point.
21942 RM References: 3.02.03 (6) 6.06 (6)
21945 @emph{AI-0003 Qualified expressions as names (2010-07-11)}
21946 @cindex AI-0003 (Ada 2012 feature)
21949 In Ada 2012, a qualified expression is considered to be syntactically a name,
21950 meaning that constructs such as @code{A'(F(X)).B} are now legal. This is
21951 useful in disambiguating some cases of overloading.
21954 RM References: 3.03 (11) 3.03 (21) 4.01 (2) 4.04 (7) 4.07 (3)
21958 @emph{AI-0120 Constant instance of protected object (0000-00-00)}
21959 @cindex AI-0120 (Ada 2012 feature)
21962 This is an RM editorial change only. The section that lists objects that are
21963 constant failed to include the current instance of a protected object
21964 within a protected function. This has always been treated as a constant
21968 RM References: 3.03 (21)
21971 @emph{AI-0008 General access to constrained objects (0000-00-00)}
21972 @cindex AI-0008 (Ada 2012 feature)
21975 The wording in the RM implied that if you have a general access to a
21976 constrained object, it could be used to modify the discriminants. This was
21977 obviously not intended. @code{Constraint_Error} should be raised, and GNAT
21978 has always done so in this situation.
21981 RM References: 3.03 (23) 3.10.02 (26/2) 4.01 (9) 6.04.01 (17) 8.05.01 (5/2)
21985 @emph{AI-0093 Additional rules use immutably limited (0000-00-00)}
21986 @cindex AI-0093 (Ada 2012 feature)
21989 This is an editorial change only, to make more widespread use of the Ada 2012
21990 ``immutably limited''.
21993 RM References: 3.03 (23.4/3)
21998 @emph{AI-0096 Deriving from formal private types (2010-07-20)}
21999 @cindex AI-0096 (Ada 2012 feature)
22002 In general it is illegal for a type derived from a formal limited type to be
22003 nonlimited. This AI makes an exception to this rule: derivation is legal
22004 if it appears in the private part of the generic, and the formal type is not
22005 tagged. If the type is tagged, the legality check must be applied to the
22006 private part of the package.
22009 RM References: 3.04 (5.1/2) 6.02 (7)
22013 @emph{AI-0181 Soft hyphen is a non-graphic character (2010-07-23)}
22014 @cindex AI-0181 (Ada 2012 feature)
22017 From Ada 2005 on, soft hyphen is considered a non-graphic character, which
22018 means that it has a special name (@code{SOFT_HYPHEN}) in conjunction with the
22019 @code{Image} and @code{Value} attributes for the character types. Strictly
22020 speaking this is an inconsistency with Ada 95, but in practice the use of
22021 these attributes is so obscure that it will not cause problems.
22024 RM References: 3.05.02 (2/2) A.01 (35/2) A.03.03 (21)
22028 @emph{AI-0182 Additional forms for @code{Character'Value} (0000-00-00)}
22029 @cindex AI-0182 (Ada 2012 feature)
22032 This AI allows @code{Character'Value} to accept the string @code{'?'} where
22033 @code{?} is any character including non-graphic control characters. GNAT has
22034 always accepted such strings. It also allows strings such as
22035 @code{HEX_00000041} to be accepted, but GNAT does not take advantage of this
22036 permission and raises @code{Constraint_Error}, as is certainly still
22040 RM References: 3.05 (56/2)
22044 @emph{AI-0214 Defaulted discriminants for limited tagged (2010-10-01)}
22045 @cindex AI-0214 (Ada 2012 feature)
22048 Ada 2012 relaxes the restriction that forbids discriminants of tagged types
22049 to have default expressions by allowing them when the type is limited. It
22050 is often useful to define a default value for a discriminant even though
22051 it can't be changed by assignment.
22054 RM References: 3.07 (9.1/2) 3.07.02 (3)
22058 @emph{AI-0102 Some implicit conversions are illegal (0000-00-00)}
22059 @cindex AI-0102 (Ada 2012 feature)
22062 It is illegal to assign an anonymous access constant to an anonymous access
22063 variable. The RM did not have a clear rule to prevent this, but GNAT has
22064 always generated an error for this usage.
22067 RM References: 3.07 (16) 3.07.01 (9) 6.04.01 (6) 8.06 (27/2)
22071 @emph{AI-0158 Generalizing membership tests (2010-09-16)}
22072 @cindex AI-0158 (Ada 2012 feature)
22075 This AI extends the syntax of membership tests to simplify complex conditions
22076 that can be expressed as membership in a subset of values of any type. It
22077 introduces syntax for a list of expressions that may be used in loop contexts
22081 RM References: 3.08.01 (5) 4.04 (3) 4.05.02 (3) 4.05.02 (5) 4.05.02 (27)
22085 @emph{AI-0173 Testing if tags represent abstract types (2010-07-03)}
22086 @cindex AI-0173 (Ada 2012 feature)
22089 The function @code{Ada.Tags.Type_Is_Abstract} returns @code{True} if invoked
22090 with the tag of an abstract type, and @code{False} otherwise.
22093 RM References: 3.09 (7.4/2) 3.09 (12.4/2)
22098 @emph{AI-0076 function with controlling result (0000-00-00)}
22099 @cindex AI-0076 (Ada 2012 feature)
22102 This is an editorial change only. The RM defines calls with controlling
22103 results, but uses the term ``function with controlling result'' without an
22104 explicit definition.
22107 RM References: 3.09.02 (2/2)
22111 @emph{AI-0126 Dispatching with no declared operation (0000-00-00)}
22112 @cindex AI-0126 (Ada 2012 feature)
22115 This AI clarifies dispatching rules, and simply confirms that dispatching
22116 executes the operation of the parent type when there is no explicitly or
22117 implicitly declared operation for the descendant type. This has always been
22118 the case in all versions of GNAT.
22121 RM References: 3.09.02 (20/2) 3.09.02 (20.1/2) 3.09.02 (20.2/2)
22125 @emph{AI-0097 Treatment of abstract null extension (2010-07-19)}
22126 @cindex AI-0097 (Ada 2012 feature)
22129 The RM as written implied that in some cases it was possible to create an
22130 object of an abstract type, by having an abstract extension inherit a non-
22131 abstract constructor from its parent type. This mistake has been corrected
22132 in GNAT and in the RM, and this construct is now illegal.
22135 RM References: 3.09.03 (4/2)
22139 @emph{AI-0203 Extended return cannot be abstract (0000-00-00)}
22140 @cindex AI-0203 (Ada 2012 feature)
22143 A return_subtype_indication cannot denote an abstract subtype. GNAT has never
22144 permitted such usage.
22147 RM References: 3.09.03 (8/3)
22151 @emph{AI-0198 Inheriting abstract operators (0000-00-00)}
22152 @cindex AI-0198 (Ada 2012 feature)
22155 This AI resolves a conflict between two rules involving inherited abstract
22156 operations and predefined operators. If a derived numeric type inherits
22157 an abstract operator, it overrides the predefined one. This interpretation
22158 was always the one implemented in GNAT.
22161 RM References: 3.09.03 (4/3)
22164 @emph{AI-0073 Functions returning abstract types (2010-07-10)}
22165 @cindex AI-0073 (Ada 2012 feature)
22168 This AI covers a number of issues regarding returning abstract types. In
22169 particular generic functions cannot have abstract result types or access
22170 result types designated an abstract type. There are some other cases which
22171 are detailed in the AI. Note that this binding interpretation has not been
22172 retrofitted to operate before Ada 2012 mode, since it caused a significant
22173 number of regressions.
22176 RM References: 3.09.03 (8) 3.09.03 (10) 6.05 (8/2)
22180 @emph{AI-0070 Elaboration of interface types (0000-00-00)}
22181 @cindex AI-0070 (Ada 2012 feature)
22184 This is an editorial change only, there are no testable consequences short of
22185 checking for the absence of generated code for an interface declaration.
22188 RM References: 3.09.04 (18/2)
22192 @emph{AI-0208 Characteristics of incomplete views (0000-00-00)}
22193 @cindex AI-0208 (Ada 2012 feature)
22196 The wording in the Ada 2005 RM concerning characteristics of incomplete views
22197 was incorrect and implied that some programs intended to be legal were now
22198 illegal. GNAT had never considered such programs illegal, so it has always
22199 implemented the intent of this AI.
22202 RM References: 3.10.01 (2.4/2) 3.10.01 (2.6/2)
22206 @emph{AI-0162 Incomplete type completed by partial view (2010-09-15)}
22207 @cindex AI-0162 (Ada 2012 feature)
22210 Incomplete types are made more useful by allowing them to be completed by
22211 private types and private extensions.
22214 RM References: 3.10.01 (2.5/2) 3.10.01 (2.6/2) 3.10.01 (3) 3.10.01 (4/2)
22219 @emph{AI-0098 Anonymous subprogram access restrictions (0000-00-00)}
22220 @cindex AI-0098 (Ada 2012 feature)
22223 An unintentional omission in the RM implied some inconsistent restrictions on
22224 the use of anonymous access to subprogram values. These restrictions were not
22225 intentional, and have never been enforced by GNAT.
22228 RM References: 3.10.01 (6) 3.10.01 (9.2/2)
22232 @emph{AI-0199 Aggregate with anonymous access components (2010-07-14)}
22233 @cindex AI-0199 (Ada 2012 feature)
22236 A choice list in a record aggregate can include several components of
22237 (distinct) anonymous access types as long as they have matching designated
22241 RM References: 4.03.01 (16)
22245 @emph{AI-0220 Needed components for aggregates (0000-00-00)}
22246 @cindex AI-0220 (Ada 2012 feature)
22249 This AI addresses a wording problem in the RM that appears to permit some
22250 complex cases of aggregates with non-static discriminants. GNAT has always
22251 implemented the intended semantics.
22254 RM References: 4.03.01 (17)
22257 @emph{AI-0147 Conditional expressions (2009-03-29)}
22258 @cindex AI-0147 (Ada 2012 feature)
22261 Conditional expressions are permitted. The form of such an expression is:
22264 (@b{if} @i{expr} @b{then} @i{expr} @{@b{elsif} @i{expr} @b{then} @i{expr}@} [@b{else} @i{expr}])
22267 The parentheses can be omitted in contexts where parentheses are present
22268 anyway, such as subprogram arguments and pragma arguments. If the @b{else}
22269 clause is omitted, @b{else True} is assumed;
22270 thus @code{(@b{if} A @b{then} B)} is a way to conveniently represent
22271 @emph{(A implies B)} in standard logic.
22274 RM References: 4.03.03 (15) 4.04 (1) 4.04 (7) 4.05.07 (0) 4.07 (2)
22275 4.07 (3) 4.09 (12) 4.09 (33) 5.03 (3) 5.03 (4) 7.05 (2.1/2)
22279 @emph{AI-0037 Out-of-range box associations in aggregate (0000-00-00)}
22280 @cindex AI-0037 (Ada 2012 feature)
22283 This AI confirms that an association of the form @code{Indx => <>} in an
22284 array aggregate must raise @code{Constraint_Error} if @code{Indx}
22285 is out of range. The RM specified a range check on other associations, but
22286 not when the value of the association was defaulted. GNAT has always inserted
22287 a constraint check on the index value.
22290 RM References: 4.03.03 (29)
22294 @emph{AI-0123 Composability of equality (2010-04-13)}
22295 @cindex AI-0123 (Ada 2012 feature)
22298 Equality of untagged record composes, so that the predefined equality for a
22299 composite type that includes a component of some untagged record type
22300 @code{R} uses the equality operation of @code{R} (which may be user-defined
22301 or predefined). This makes the behavior of untagged records identical to that
22302 of tagged types in this respect.
22304 This change is an incompatibility with previous versions of Ada, but it
22305 corrects a non-uniformity that was often a source of confusion. Analysis of
22306 a large number of industrial programs indicates that in those rare cases
22307 where a composite type had an untagged record component with a user-defined
22308 equality, either there was no use of the composite equality, or else the code
22309 expected the same composability as for tagged types, and thus had a bug that
22310 would be fixed by this change.
22313 RM References: 4.05.02 (9.7/2) 4.05.02 (14) 4.05.02 (15) 4.05.02 (24)
22318 @emph{AI-0088 The value of exponentiation (0000-00-00)}
22319 @cindex AI-0088 (Ada 2012 feature)
22322 This AI clarifies the equivalence rule given for the dynamic semantics of
22323 exponentiation: the value of the operation can be obtained by repeated
22324 multiplication, but the operation can be implemented otherwise (for example
22325 using the familiar divide-by-two-and-square algorithm, even if this is less
22326 accurate), and does not imply repeated reads of a volatile base.
22329 RM References: 4.05.06 (11)
22332 @emph{AI-0188 Case expressions (2010-01-09)}
22333 @cindex AI-0188 (Ada 2012 feature)
22336 Case expressions are permitted. This allows use of constructs such as:
22338 X := (@b{case} Y @b{is when} 1 => 2, @b{when} 2 => 3, @b{when others} => 31)
22342 RM References: 4.05.07 (0) 4.05.08 (0) 4.09 (12) 4.09 (33)
22345 @emph{AI-0104 Null exclusion and uninitialized allocator (2010-07-15)}
22346 @cindex AI-0104 (Ada 2012 feature)
22349 The assignment @code{Ptr := @b{new not null} Some_Ptr;} will raise
22350 @code{Constraint_Error} because the default value of the allocated object is
22351 @b{null}. This useless construct is illegal in Ada 2012.
22354 RM References: 4.08 (2)
22357 @emph{AI-0157 Allocation/Deallocation from empty pool (2010-07-11)}
22358 @cindex AI-0157 (Ada 2012 feature)
22361 Allocation and Deallocation from an empty storage pool (i.e. allocation or
22362 deallocation of a pointer for which a static storage size clause of zero
22363 has been given) is now illegal and is detected as such. GNAT
22364 previously gave a warning but not an error.
22367 RM References: 4.08 (5.3/2) 13.11.02 (4) 13.11.02 (17)
22370 @emph{AI-0179 Statement not required after label (2010-04-10)}
22371 @cindex AI-0179 (Ada 2012 feature)
22374 It is not necessary to have a statement following a label, so a label
22375 can appear at the end of a statement sequence without the need for putting a
22376 null statement afterwards, but it is not allowable to have only labels and
22377 no real statements in a statement sequence.
22380 RM References: 5.01 (2)
22384 @emph{AI-139-2 Syntactic sugar for iterators (2010-09-29)}
22385 @cindex AI-139-2 (Ada 2012 feature)
22388 The new syntax for iterating over arrays and containers is now implemented.
22389 Iteration over containers is for now limited to read-only iterators. Only
22390 default iterators are supported, with the syntax: @code{@b{for} Elem @b{of} C}.
22393 RM References: 5.05
22396 @emph{AI-0134 Profiles must match for full conformance (0000-00-00)}
22397 @cindex AI-0134 (Ada 2012 feature)
22400 For full conformance, the profiles of anonymous-access-to-subprogram
22401 parameters must match. GNAT has always enforced this rule.
22404 RM References: 6.03.01 (18)
22407 @emph{AI-0207 Mode conformance and access constant (0000-00-00)}
22408 @cindex AI-0207 (Ada 2012 feature)
22411 This AI confirms that access_to_constant indication must match for mode
22412 conformance. This was implemented in GNAT when the qualifier was originally
22413 introduced in Ada 2005.
22416 RM References: 6.03.01 (16/2)
22420 @emph{AI-0046 Null exclusion match for full conformance (2010-07-17)}
22421 @cindex AI-0046 (Ada 2012 feature)
22424 For full conformance, in the case of access parameters, the null exclusion
22425 must match (either both or neither must have @code{@b{not null}}).
22428 RM References: 6.03.02 (18)
22432 @emph{AI-0118 The association of parameter associations (0000-00-00)}
22433 @cindex AI-0118 (Ada 2012 feature)
22436 This AI clarifies the rules for named associations in subprogram calls and
22437 generic instantiations. The rules have been in place since Ada 83.
22440 RM References: 6.04.01 (2) 12.03 (9)
22444 @emph{AI-0196 Null exclusion tests for out parameters (0000-00-00)}
22445 @cindex AI-0196 (Ada 2012 feature)
22448 Null exclusion checks are not made for @code{@b{out}} parameters when
22449 evaluating the actual parameters. GNAT has never generated these checks.
22452 RM References: 6.04.01 (13)
22455 @emph{AI-0015 Constant return objects (0000-00-00)}
22456 @cindex AI-0015 (Ada 2012 feature)
22459 The return object declared in an @i{extended_return_statement} may be
22460 declared constant. This was always intended, and GNAT has always allowed it.
22463 RM References: 6.05 (2.1/2) 3.03 (10/2) 3.03 (21) 6.05 (5/2)
22468 @emph{AI-0032 Extended return for class-wide functions (0000-00-00)}
22469 @cindex AI-0032 (Ada 2012 feature)
22472 If a function returns a class-wide type, the object of an extended return
22473 statement can be declared with a specific type that is covered by the class-
22474 wide type. This has been implemented in GNAT since the introduction of
22475 extended returns. Note AI-0103 complements this AI by imposing matching
22476 rules for constrained return types.
22479 RM References: 6.05 (5.2/2) 6.05 (5.3/2) 6.05 (5.6/2) 6.05 (5.8/2)
22483 @emph{AI-0103 Static matching for extended return (2010-07-23)}
22484 @cindex AI-0103 (Ada 2012 feature)
22487 If the return subtype of a function is an elementary type or a constrained
22488 type, the subtype indication in an extended return statement must match
22489 statically this return subtype.
22492 RM References: 6.05 (5.2/2)
22496 @emph{AI-0058 Abnormal completion of an extended return (0000-00-00)}
22497 @cindex AI-0058 (Ada 2012 feature)
22500 The RM had some incorrect wording implying wrong treatment of abnormal
22501 completion in an extended return. GNAT has always implemented the intended
22502 correct semantics as described by this AI.
22505 RM References: 6.05 (22/2)
22509 @emph{AI-0050 Raising Constraint_Error early for function call (0000-00-00)}
22510 @cindex AI-0050 (Ada 2012 feature)
22513 The implementation permissions for raising @code{Constraint_Error} early on a function call when it was clear an exception would be raised were over-permissive and allowed mishandling of discriminants in some cases. GNAT did
22514 not take advantage of these incorrect permissions in any case.
22517 RM References: 6.05 (24/2)
22521 @emph{AI-0125 Nonoverridable operations of an ancestor (2010-09-28)}
22522 @cindex AI-0125 (Ada 2012 feature)
22525 In Ada 2012, the declaration of a primitive operation of a type extension
22526 or private extension can also override an inherited primitive that is not
22527 visible at the point of this declaration.
22530 RM References: 7.03.01 (6) 8.03 (23) 8.03.01 (5/2) 8.03.01 (6/2)
22533 @emph{AI-0062 Null exclusions and deferred constants (0000-00-00)}
22534 @cindex AI-0062 (Ada 2012 feature)
22537 A full constant may have a null exclusion even if its associated deferred
22538 constant does not. GNAT has always allowed this.
22541 RM References: 7.04 (6/2) 7.04 (7.1/2)
22545 @emph{AI-0178 Incomplete views are limited (0000-00-00)}
22546 @cindex AI-0178 (Ada 2012 feature)
22549 This AI clarifies the role of incomplete views and plugs an omission in the
22550 RM. GNAT always correctly restricted the use of incomplete views and types.
22553 RM References: 7.05 (3/2) 7.05 (6/2)
22556 @emph{AI-0087 Actual for formal nonlimited derived type (2010-07-15)}
22557 @cindex AI-0087 (Ada 2012 feature)
22560 The actual for a formal nonlimited derived type cannot be limited. In
22561 particular, a formal derived type that extends a limited interface but which
22562 is not explicitly limited cannot be instantiated with a limited type.
22565 RM References: 7.05 (5/2) 12.05.01 (5.1/2)
22568 @emph{AI-0099 Tag determines whether finalization needed (0000-00-00)}
22569 @cindex AI-0099 (Ada 2012 feature)
22572 This AI clarifies that ``needs finalization'' is part of dynamic semantics,
22573 and therefore depends on the run-time characteristics of an object (i.e. its
22574 tag) and not on its nominal type. As the AI indicates: ``we do not expect
22575 this to affect any implementation''.
22578 RM References: 7.06.01 (6) 7.06.01 (7) 7.06.01 (8) 7.06.01 (9/2)
22583 @emph{AI-0064 Redundant finalization rule (0000-00-00)}
22584 @cindex AI-0064 (Ada 2012 feature)
22587 This is an editorial change only. The intended behavior is already checked
22588 by an existing ACATS test, which GNAT has always executed correctly.
22591 RM References: 7.06.01 (17.1/1)
22594 @emph{AI-0026 Missing rules for Unchecked_Union (2010-07-07)}
22595 @cindex AI-0026 (Ada 2012 feature)
22598 Record representation clauses concerning Unchecked_Union types cannot mention
22599 the discriminant of the type. The type of a component declared in the variant
22600 part of an Unchecked_Union cannot be controlled, have controlled components,
22601 nor have protected or task parts. If an Unchecked_Union type is declared
22602 within the body of a generic unit or its descendants, then the type of a
22603 component declared in the variant part cannot be a formal private type or a
22604 formal private extension declared within the same generic unit.
22607 RM References: 7.06 (9.4/2) B.03.03 (9/2) B.03.03 (10/2)
22611 @emph{AI-0205 Extended return declares visible name (0000-00-00)}
22612 @cindex AI-0205 (Ada 2012 feature)
22615 This AI corrects a simple omission in the RM. Return objects have always
22616 been visible within an extended return statement.
22619 RM References: 8.03 (17)
22623 @emph{AI-0042 Overriding versus implemented-by (0000-00-00)}
22624 @cindex AI-0042 (Ada 2012 feature)
22627 This AI fixes a wording gap in the RM. An operation of a synchronized
22628 interface can be implemented by a protected or task entry, but the abstract
22629 operation is not being overridden in the usual sense, and it must be stated
22630 separately that this implementation is legal. This has always been the case
22634 RM References: 9.01 (9.2/2) 9.04 (11.1/2)
22637 @emph{AI-0030 Requeue on synchronized interfaces (2010-07-19)}
22638 @cindex AI-0030 (Ada 2012 feature)
22641 Requeue is permitted to a protected, synchronized or task interface primitive
22642 providing it is known that the overriding operation is an entry. Otherwise
22643 the requeue statement has the same effect as a procedure call. Use of pragma
22644 @code{Implemented} provides a way to impose a static requirement on the
22645 overriding operation by adhering to one of the implementation kinds: entry,
22646 protected procedure or any of the above.
22649 RM References: 9.05 (9) 9.05.04 (2) 9.05.04 (3) 9.05.04 (5)
22650 9.05.04 (6) 9.05.04 (7) 9.05.04 (12)
22654 @emph{AI-0201 Independence of atomic object components (2010-07-22)}
22655 @cindex AI-0201 (Ada 2012 feature)
22658 If an Atomic object has a pragma @code{Pack} or a @code{Component_Size}
22659 attribute, then individual components may not be addressable by independent
22660 tasks. However, if the representation clause has no effect (is confirming),
22661 then independence is not compromised. Furthermore, in GNAT, specification of
22662 other appropriately addressable component sizes (e.g. 16 for 8-bit
22663 characters) also preserves independence. GNAT now gives very clear warnings
22664 both for the declaration of such a type, and for any assignment to its components.
22667 RM References: 9.10 (1/3) C.06 (22/2) C.06 (23/2)
22670 @emph{AI-0009 Pragma Independent[_Components] (2010-07-23)}
22671 @cindex AI-0009 (Ada 2012 feature)
22674 This AI introduces the new pragmas @code{Independent} and
22675 @code{Independent_Components},
22676 which control guaranteeing independence of access to objects and components.
22677 The AI also requires independence not unaffected by confirming rep clauses.
22680 RM References: 9.10 (1) 13.01 (15/1) 13.02 (9) 13.03 (13) C.06 (2)
22681 C.06 (4) C.06 (6) C.06 (9) C.06 (13) C.06 (14)
22685 @emph{AI-0072 Task signalling using 'Terminated (0000-00-00)}
22686 @cindex AI-0072 (Ada 2012 feature)
22689 This AI clarifies that task signalling for reading @code{'Terminated} only
22690 occurs if the result is True. GNAT semantics has always been consistent with
22691 this notion of task signalling.
22694 RM References: 9.10 (6.1/1)
22697 @emph{AI-0108 Limited incomplete view and discriminants (0000-00-00)}
22698 @cindex AI-0108 (Ada 2012 feature)
22701 This AI confirms that an incomplete type from a limited view does not have
22702 discriminants. This has always been the case in GNAT.
22705 RM References: 10.01.01 (12.3/2)
22708 @emph{AI-0129 Limited views and incomplete types (0000-00-00)}
22709 @cindex AI-0129 (Ada 2012 feature)
22712 This AI clarifies the description of limited views: a limited view of a
22713 package includes only one view of a type that has an incomplete declaration
22714 and a full declaration (there is no possible ambiguity in a client package).
22715 This AI also fixes an omission: a nested package in the private part has no
22716 limited view. GNAT always implemented this correctly.
22719 RM References: 10.01.01 (12.2/2) 10.01.01 (12.3/2)
22724 @emph{AI-0077 Limited withs and scope of declarations (0000-00-00)}
22725 @cindex AI-0077 (Ada 2012 feature)
22728 This AI clarifies that a declaration does not include a context clause,
22729 and confirms that it is illegal to have a context in which both a limited
22730 and a nonlimited view of a package are accessible. Such double visibility
22731 was always rejected by GNAT.
22734 RM References: 10.01.02 (12/2) 10.01.02 (21/2) 10.01.02 (22/2)
22737 @emph{AI-0122 Private with and children of generics (0000-00-00)}
22738 @cindex AI-0122 (Ada 2012 feature)
22741 This AI clarifies the visibility of private children of generic units within
22742 instantiations of a parent. GNAT has always handled this correctly.
22745 RM References: 10.01.02 (12/2)
22750 @emph{AI-0040 Limited with clauses on descendant (0000-00-00)}
22751 @cindex AI-0040 (Ada 2012 feature)
22754 This AI confirms that a limited with clause in a child unit cannot name
22755 an ancestor of the unit. This has always been checked in GNAT.
22758 RM References: 10.01.02 (20/2)
22761 @emph{AI-0132 Placement of library unit pragmas (0000-00-00)}
22762 @cindex AI-0132 (Ada 2012 feature)
22765 This AI fills a gap in the description of library unit pragmas. The pragma
22766 clearly must apply to a library unit, even if it does not carry the name
22767 of the enclosing unit. GNAT has always enforced the required check.
22770 RM References: 10.01.05 (7)
22774 @emph{AI-0034 Categorization of limited views (0000-00-00)}
22775 @cindex AI-0034 (Ada 2012 feature)
22778 The RM makes certain limited with clauses illegal because of categorization
22779 considerations, when the corresponding normal with would be legal. This is
22780 not intended, and GNAT has always implemented the recommended behavior.
22783 RM References: 10.02.01 (11/1) 10.02.01 (17/2)
22787 @emph{AI-0035 Inconsistencies with Pure units (0000-00-00)}
22788 @cindex AI-0035 (Ada 2012 feature)
22791 This AI remedies some inconsistencies in the legality rules for Pure units.
22792 Derived access types are legal in a pure unit (on the assumption that the
22793 rule for a zero storage pool size has been enforced on the ancestor type).
22794 The rules are enforced in generic instances and in subunits. GNAT has always
22795 implemented the recommended behavior.
22798 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)
22802 @emph{AI-0219 Pure permissions and limited parameters (2010-05-25)}
22803 @cindex AI-0219 (Ada 2012 feature)
22806 This AI refines the rules for the cases with limited parameters which do not
22807 allow the implementations to omit ``redundant''. GNAT now properly conforms
22808 to the requirements of this binding interpretation.
22811 RM References: 10.02.01 (18/2)
22814 @emph{AI-0043 Rules about raising exceptions (0000-00-00)}
22815 @cindex AI-0043 (Ada 2012 feature)
22818 This AI covers various omissions in the RM regarding the raising of
22819 exceptions. GNAT has always implemented the intended semantics.
22822 RM References: 11.04.01 (10.1/2) 11 (2)
22826 @emph{AI-0200 Mismatches in formal package declarations (0000-00-00)}
22827 @cindex AI-0200 (Ada 2012 feature)
22830 This AI plugs a gap in the RM which appeared to allow some obviously intended
22831 illegal instantiations. GNAT has never allowed these instantiations.
22834 RM References: 12.07 (16)
22838 @emph{AI-0112 Detection of duplicate pragmas (2010-07-24)}
22839 @cindex AI-0112 (Ada 2012 feature)
22842 This AI concerns giving names to various representation aspects, but the
22843 practical effect is simply to make the use of duplicate
22844 @code{Atomic}[@code{_Components}],
22845 @code{Volatile}[@code{_Components}] and
22846 @code{Independent}[@code{_Components}] pragmas illegal, and GNAT
22847 now performs this required check.
22850 RM References: 13.01 (8)
22853 @emph{AI-0106 No representation pragmas on generic formals (0000-00-00)}
22854 @cindex AI-0106 (Ada 2012 feature)
22857 The RM appeared to allow representation pragmas on generic formal parameters,
22858 but this was not intended, and GNAT has never permitted this usage.
22861 RM References: 13.01 (9.1/1)
22865 @emph{AI-0012 Pack/Component_Size for aliased/atomic (2010-07-15)}
22866 @cindex AI-0012 (Ada 2012 feature)
22869 It is now illegal to give an inappropriate component size or a pragma
22870 @code{Pack} that attempts to change the component size in the case of atomic
22871 or aliased components. Previously GNAT ignored such an attempt with a
22875 RM References: 13.02 (6.1/2) 13.02 (7) C.06 (10) C.06 (11) C.06 (21)
22879 @emph{AI-0039 Stream attributes cannot be dynamic (0000-00-00)}
22880 @cindex AI-0039 (Ada 2012 feature)
22883 The RM permitted the use of dynamic expressions (such as @code{ptr.@b{all})}
22884 for stream attributes, but these were never useful and are now illegal. GNAT
22885 has always regarded such expressions as illegal.
22888 RM References: 13.03 (4) 13.03 (6) 13.13.02 (38/2)
22892 @emph{AI-0095 Address of intrinsic subprograms (0000-00-00)}
22893 @cindex AI-0095 (Ada 2012 feature)
22896 The prefix of @code{'Address} cannot statically denote a subprogram with
22897 convention @code{Intrinsic}. The use of the @code{Address} attribute raises
22898 @code{Program_Error} if the prefix denotes a subprogram with convention
22902 RM References: 13.03 (11/1)
22906 @emph{AI-0116 Alignment of class-wide objects (0000-00-00)}
22907 @cindex AI-0116 (Ada 2012 feature)
22910 This AI requires that the alignment of a class-wide object be no greater
22911 than the alignment of any type in the class. GNAT has always followed this
22915 RM References: 13.03 (29) 13.11 (16)
22919 @emph{AI-0146 Type invariants (2009-09-21)}
22920 @cindex AI-0146 (Ada 2012 feature)
22923 Type invariants may be specified for private types using the aspect notation.
22924 Aspect @code{Type_Invariant} may be specified for any private type,
22925 @code{Type_Invariant'Class} can
22926 only be specified for tagged types, and is inherited by any descendent of the
22927 tagged types. The invariant is a boolean expression that is tested for being
22928 true in the following situations: conversions to the private type, object
22929 declarations for the private type that are default initialized, and
22931 parameters and returned result on return from any primitive operation for
22932 the type that is visible to a client.
22933 GNAT defines the synonyms @code{Invariant} for @code{Type_Invariant} and
22934 @code{Invariant'Class} for @code{Type_Invariant'Class}.
22937 RM References: 13.03.03 (00)
22940 @emph{AI-0078 Relax Unchecked_Conversion alignment rules (0000-00-00)}
22941 @cindex AI-0078 (Ada 2012 feature)
22944 In Ada 2012, compilers are required to support unchecked conversion where the
22945 target alignment is a multiple of the source alignment. GNAT always supported
22946 this case (and indeed all cases of differing alignments, doing copies where
22947 required if the alignment was reduced).
22950 RM References: 13.09 (7)
22954 @emph{AI-0195 Invalid value handling is implementation defined (2010-07-03)}
22955 @cindex AI-0195 (Ada 2012 feature)
22958 The handling of invalid values is now designated to be implementation
22959 defined. This is a documentation change only, requiring Annex M in the GNAT
22960 Reference Manual to document this handling.
22961 In GNAT, checks for invalid values are made
22962 only when necessary to avoid erroneous behavior. Operations like assignments
22963 which cannot cause erroneous behavior ignore the possibility of invalid
22964 values and do not do a check. The date given above applies only to the
22965 documentation change, this behavior has always been implemented by GNAT.
22968 RM References: 13.09.01 (10)
22971 @emph{AI-0193 Alignment of allocators (2010-09-16)}
22972 @cindex AI-0193 (Ada 2012 feature)
22975 This AI introduces a new attribute @code{Max_Alignment_For_Allocation},
22976 analogous to @code{Max_Size_In_Storage_Elements}, but for alignment instead
22980 RM References: 13.11 (16) 13.11 (21) 13.11.01 (0) 13.11.01 (1)
22981 13.11.01 (2) 13.11.01 (3)
22985 @emph{AI-0177 Parameterized expressions (2010-07-10)}
22986 @cindex AI-0177 (Ada 2012 feature)
22989 The new Ada 2012 notion of parameterized expressions is implemented. The form
22992 @i{function specification} @b{is} (@i{expression})
22996 This is exactly equivalent to the
22997 corresponding function body that returns the expression, but it can appear
22998 in a package spec. Note that the expression must be parenthesized.
23001 RM References: 13.11.01 (3/2)
23004 @emph{AI-0033 Attach/Interrupt_Handler in generic (2010-07-24)}
23005 @cindex AI-0033 (Ada 2012 feature)
23008 Neither of these two pragmas may appear within a generic template, because
23009 the generic might be instantiated at other than the library level.
23012 RM References: 13.11.02 (16) C.03.01 (7/2) C.03.01 (8/2)
23016 @emph{AI-0161 Restriction No_Default_Stream_Attributes (2010-09-11)}
23017 @cindex AI-0161 (Ada 2012 feature)
23020 A new restriction @code{No_Default_Stream_Attributes} prevents the use of any
23021 of the default stream attributes for elementary types. If this restriction is
23022 in force, then it is necessary to provide explicit subprograms for any
23023 stream attributes used.
23026 RM References: 13.12.01 (4/2) 13.13.02 (40/2) 13.13.02 (52/2)
23029 @emph{AI-0194 Value of Stream_Size attribute (0000-00-00)}
23030 @cindex AI-0194 (Ada 2012 feature)
23033 The @code{Stream_Size} attribute returns the default number of bits in the
23034 stream representation of the given type.
23035 This value is not affected by the presence
23036 of stream subprogram attributes for the type. GNAT has always implemented
23037 this interpretation.
23040 RM References: 13.13.02 (1.2/2)
23043 @emph{AI-0109 Redundant check in S'Class'Input (0000-00-00)}
23044 @cindex AI-0109 (Ada 2012 feature)
23047 This AI is an editorial change only. It removes the need for a tag check
23048 that can never fail.
23051 RM References: 13.13.02 (34/2)
23054 @emph{AI-0007 Stream read and private scalar types (0000-00-00)}
23055 @cindex AI-0007 (Ada 2012 feature)
23058 The RM as written appeared to limit the possibilities of declaring read
23059 attribute procedures for private scalar types. This limitation was not
23060 intended, and has never been enforced by GNAT.
23063 RM References: 13.13.02 (50/2) 13.13.02 (51/2)
23067 @emph{AI-0065 Remote access types and external streaming (0000-00-00)}
23068 @cindex AI-0065 (Ada 2012 feature)
23071 This AI clarifies the fact that all remote access types support external
23072 streaming. This fixes an obvious oversight in the definition of the
23073 language, and GNAT always implemented the intended correct rules.
23076 RM References: 13.13.02 (52/2)
23079 @emph{AI-0019 Freezing of primitives for tagged types (0000-00-00)}
23080 @cindex AI-0019 (Ada 2012 feature)
23083 The RM suggests that primitive subprograms of a specific tagged type are
23084 frozen when the tagged type is frozen. This would be an incompatible change
23085 and is not intended. GNAT has never attempted this kind of freezing and its
23086 behavior is consistent with the recommendation of this AI.
23089 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)
23092 @emph{AI-0017 Freezing and incomplete types (0000-00-00)}
23093 @cindex AI-0017 (Ada 2012 feature)
23096 So-called ``Taft-amendment types'' (i.e., types that are completed in package
23097 bodies) are not frozen by the occurrence of bodies in the
23098 enclosing declarative part. GNAT always implemented this properly.
23101 RM References: 13.14 (3/1)
23105 @emph{AI-0060 Extended definition of remote access types (0000-00-00)}
23106 @cindex AI-0060 (Ada 2012 feature)
23109 This AI extends the definition of remote access types to include access
23110 to limited, synchronized, protected or task class-wide interface types.
23111 GNAT already implemented this extension.
23114 RM References: A (4) E.02.02 (9/1) E.02.02 (9.2/1) E.02.02 (14/2) E.02.02 (18)
23117 @emph{AI-0114 Classification of letters (0000-00-00)}
23118 @cindex AI-0114 (Ada 2012 feature)
23121 The code points 170 (@code{FEMININE ORDINAL INDICATOR}),
23122 181 (@code{MICRO SIGN}), and
23123 186 (@code{MASCULINE ORDINAL INDICATOR}) are technically considered
23124 lower case letters by Unicode.
23125 However, they are not allowed in identifiers, and they
23126 return @code{False} to @code{Ada.Characters.Handling.Is_Letter/Is_Lower}.
23127 This behavior is consistent with that defined in Ada 95.
23130 RM References: A.03.02 (59) A.04.06 (7)
23134 @emph{AI-0185 Ada.Wide_[Wide_]Characters.Handling (2010-07-06)}
23135 @cindex AI-0185 (Ada 2012 feature)
23138 Two new packages @code{Ada.Wide_[Wide_]Characters.Handling} provide
23139 classification functions for @code{Wide_Character} and
23140 @code{Wide_Wide_Character}, as well as providing
23141 case folding routines for @code{Wide_[Wide_]Character} and
23142 @code{Wide_[Wide_]String}.
23145 RM References: A.03.05 (0) A.03.06 (0)
23149 @emph{AI-0031 Add From parameter to Find_Token (2010-07-25)}
23150 @cindex AI-0031 (Ada 2012 feature)
23153 A new version of @code{Find_Token} is added to all relevant string packages,
23154 with an extra parameter @code{From}. Instead of starting at the first
23155 character of the string, the search for a matching Token starts at the
23156 character indexed by the value of @code{From}.
23157 These procedures are available in all versions of Ada
23158 but if used in versions earlier than Ada 2012 they will generate a warning
23159 that an Ada 2012 subprogram is being used.
23162 RM References: A.04.03 (16) A.04.03 (67) A.04.03 (68/1) A.04.04 (51)
23167 @emph{AI-0056 Index on null string returns zero (0000-00-00)}
23168 @cindex AI-0056 (Ada 2012 feature)
23171 The wording in the Ada 2005 RM implied an incompatible handling of the
23172 @code{Index} functions, resulting in raising an exception instead of
23173 returning zero in some situations.
23174 This was not intended and has been corrected.
23175 GNAT always returned zero, and is thus consistent with this AI.
23178 RM References: A.04.03 (56.2/2) A.04.03 (58.5/2)
23182 @emph{AI-0137 String encoding package (2010-03-25)}
23183 @cindex AI-0137 (Ada 2012 feature)
23186 The packages @code{Ada.Strings.UTF_Encoding}, together with its child
23187 packages, @code{Conversions}, @code{Strings}, @code{Wide_Strings},
23188 and @code{Wide_Wide_Strings} have been
23189 implemented. These packages (whose documentation can be found in the spec
23190 files @file{a-stuten.ads}, @file{a-suenco.ads}, @file{a-suenst.ads},
23191 @file{a-suewst.ads}, @file{a-suezst.ads}) allow encoding and decoding of
23192 @code{String}, @code{Wide_String}, and @code{Wide_Wide_String}
23193 values using UTF coding schemes (including UTF-8, UTF-16LE, UTF-16BE, and
23194 UTF-16), as well as conversions between the different UTF encodings. With
23195 the exception of @code{Wide_Wide_Strings}, these packages are available in
23196 Ada 95 and Ada 2005 mode as well as Ada 2012 mode.
23197 The @code{Wide_Wide_Strings package}
23198 is available in Ada 2005 mode as well as Ada 2012 mode (but not in Ada 95
23199 mode since it uses @code{Wide_Wide_Character}).
23202 RM References: A.04.11
23205 @emph{AI-0038 Minor errors in Text_IO (0000-00-00)}
23206 @cindex AI-0038 (Ada 2012 feature)
23209 These are minor errors in the description on three points. The intent on
23210 all these points has always been clear, and GNAT has always implemented the
23211 correct intended semantics.
23214 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)
23217 @emph{AI-0044 Restrictions on container instantiations (0000-00-00)}
23218 @cindex AI-0044 (Ada 2012 feature)
23221 This AI places restrictions on allowed instantiations of generic containers.
23222 These restrictions are not checked by the compiler, so there is nothing to
23223 change in the implementation. This affects only the RM documentation.
23226 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)
23229 @emph{AI-0127 Adding Locale Capabilities (2010-09-29)}
23230 @cindex AI-0127 (Ada 2012 feature)
23233 This package provides an interface for identifying the current locale.
23236 RM References: A.19 A.19.01 A.19.02 A.19.03 A.19.05 A.19.06
23237 A.19.07 A.19.08 A.19.09 A.19.10 A.19.11 A.19.12 A.19.13
23242 @emph{AI-0002 Export C with unconstrained arrays (0000-00-00)}
23243 @cindex AI-0002 (Ada 2012 feature)
23246 The compiler is not required to support exporting an Ada subprogram with
23247 convention C if there are parameters or a return type of an unconstrained
23248 array type (such as @code{String}). GNAT allows such declarations but
23249 generates warnings. It is possible, but complicated, to write the
23250 corresponding C code and certainly such code would be specific to GNAT and
23254 RM References: B.01 (17) B.03 (62) B.03 (71.1/2)
23258 @emph{AI-0216 No_Task_Hierarchy forbids local tasks (0000-00-00)}
23259 @cindex AI05-0216 (Ada 2012 feature)
23262 It is clearly the intention that @code{No_Task_Hierarchy} is intended to
23263 forbid tasks declared locally within subprograms, or functions returning task
23264 objects, and that is the implementation that GNAT has always provided.
23265 However the language in the RM was not sufficiently clear on this point.
23266 Thus this is a documentation change in the RM only.
23269 RM References: D.07 (3/3)
23272 @emph{AI-0211 No_Relative_Delays forbids Set_Handler use (2010-07-09)}
23273 @cindex AI-0211 (Ada 2012 feature)
23276 The restriction @code{No_Relative_Delays} forbids any calls to the subprogram
23277 @code{Ada.Real_Time.Timing_Events.Set_Handler}.
23280 RM References: D.07 (5) D.07 (10/2) D.07 (10.4/2) D.07 (10.7/2)
23283 @emph{AI-0190 pragma Default_Storage_Pool (2010-09-15)}
23284 @cindex AI-0190 (Ada 2012 feature)
23287 This AI introduces a new pragma @code{Default_Storage_Pool}, which can be
23288 used to control storage pools globally.
23289 In particular, you can force every access
23290 type that is used for allocation (@b{new}) to have an explicit storage pool,
23291 or you can declare a pool globally to be used for all access types that lack
23295 RM References: D.07 (8)
23298 @emph{AI-0189 No_Allocators_After_Elaboration (2010-01-23)}
23299 @cindex AI-0189 (Ada 2012 feature)
23302 This AI introduces a new restriction @code{No_Allocators_After_Elaboration},
23303 which says that no dynamic allocation will occur once elaboration is
23305 In general this requires a run-time check, which is not required, and which
23306 GNAT does not attempt. But the static cases of allocators in a task body or
23307 in the body of the main program are detected and flagged at compile or bind
23311 RM References: D.07 (19.1/2) H.04 (23.3/2)
23314 @emph{AI-0171 Pragma CPU and Ravenscar Profile (2010-09-24)}
23315 @cindex AI-0171 (Ada 2012 feature)
23318 A new package @code{System.Multiprocessors} is added, together with the
23319 definition of pragma @code{CPU} for controlling task affinity. A new no
23320 dependence restriction, on @code{System.Multiprocessors.Dispatching_Domains},
23321 is added to the Ravenscar profile.
23324 RM References: D.13.01 (4/2) D.16
23328 @emph{AI-0210 Correct Timing_Events metric (0000-00-00)}
23329 @cindex AI-0210 (Ada 2012 feature)
23332 This is a documentation only issue regarding wording of metric requirements,
23333 that does not affect the implementation of the compiler.
23336 RM References: D.15 (24/2)
23340 @emph{AI-0206 Remote types packages and preelaborate (2010-07-24)}
23341 @cindex AI-0206 (Ada 2012 feature)
23344 Remote types packages are now allowed to depend on preelaborated packages.
23345 This was formerly considered illegal.
23348 RM References: E.02.02 (6)
23353 @emph{AI-0152 Restriction No_Anonymous_Allocators (2010-09-08)}
23354 @cindex AI-0152 (Ada 2012 feature)
23357 Restriction @code{No_Anonymous_Allocators} prevents the use of allocators
23358 where the type of the returned value is an anonymous access type.
23361 RM References: H.04 (8/1)
23365 @node Obsolescent Features
23366 @chapter Obsolescent Features
23369 This chapter describes features that are provided by GNAT, but are
23370 considered obsolescent since there are preferred ways of achieving
23371 the same effect. These features are provided solely for historical
23372 compatibility purposes.
23375 * pragma No_Run_Time::
23376 * pragma Ravenscar::
23377 * pragma Restricted_Run_Time::
23378 * pragma Task_Info::
23379 * System.Task_Info (s-tasinf.ads)::
23382 @node pragma No_Run_Time
23383 @section pragma No_Run_Time
23385 The pragma @code{No_Run_Time} is used to achieve an affect similar
23386 to the use of the "Zero Foot Print" configurable run time, but without
23387 requiring a specially configured run time. The result of using this
23388 pragma, which must be used for all units in a partition, is to restrict
23389 the use of any language features requiring run-time support code. The
23390 preferred usage is to use an appropriately configured run-time that
23391 includes just those features that are to be made accessible.
23393 @node pragma Ravenscar
23394 @section pragma Ravenscar
23396 The pragma @code{Ravenscar} has exactly the same effect as pragma
23397 @code{Profile (Ravenscar)}. The latter usage is preferred since it
23398 is part of the new Ada 2005 standard.
23400 @node pragma Restricted_Run_Time
23401 @section pragma Restricted_Run_Time
23403 The pragma @code{Restricted_Run_Time} has exactly the same effect as
23404 pragma @code{Profile (Restricted)}. The latter usage is
23405 preferred since the Ada 2005 pragma @code{Profile} is intended for
23406 this kind of implementation dependent addition.
23408 @node pragma Task_Info
23409 @section pragma Task_Info
23411 The functionality provided by pragma @code{Task_Info} is now part of the
23412 Ada language. The @code{CPU} aspect and the package
23413 @code{System.Multiprocessors} offer a less system-dependent way to specify
23414 task affinity or to query the number of processsors.
23419 @smallexample @c ada
23420 pragma Task_Info (EXPRESSION);
23424 This pragma appears within a task definition (like pragma
23425 @code{Priority}) and applies to the task in which it appears. The
23426 argument must be of type @code{System.Task_Info.Task_Info_Type}.
23427 The @code{Task_Info} pragma provides system dependent control over
23428 aspects of tasking implementation, for example, the ability to map
23429 tasks to specific processors. For details on the facilities available
23430 for the version of GNAT that you are using, see the documentation
23431 in the spec of package System.Task_Info in the runtime
23434 @node System.Task_Info (s-tasinf.ads)
23435 @section package System.Task_Info (@file{s-tasinf.ads})
23438 This package provides target dependent functionality that is used
23439 to support the @code{Task_Info} pragma. The predefined Ada package
23440 @code{System.Multiprocessors} and the @code{CPU} aspect now provide a
23441 standard replacement for GNAT's @code{Task_Info} functionality.
23444 @c GNU Free Documentation License
23446 @node Concept Index