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-2008, 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''.
29 @set DEFAULTLANGUAGEVERSION Ada 2005
30 @set NONDEFAULTLANGUAGEVERSION Ada 95
32 @settitle GNAT Reference Manual
34 @setchapternewpage odd
37 @include gcc-common.texi
39 @dircategory GNU Ada tools
41 * GNAT Reference Manual: (gnat_rm). Reference Manual for GNU Ada tools.
45 @title GNAT Reference Manual
46 @subtitle GNAT, The GNU Ada Compiler
50 @vskip 0pt plus 1filll
57 @node Top, About This Guide, (dir), (dir)
58 @top GNAT Reference Manual
64 GNAT, The GNU Ada Compiler@*
65 GCC version @value{version-GCC}@*
72 * Implementation Defined Pragmas::
73 * Implementation Defined Attributes::
74 * Implementation Defined Restrictions::
75 * Implementation Advice::
76 * Implementation Defined Characteristics::
77 * Intrinsic Subprograms::
78 * Representation Clauses and Pragmas::
79 * Standard Library Routines::
80 * The Implementation of Standard I/O::
82 * Interfacing to Other Languages::
83 * Specialized Needs Annexes::
84 * Implementation of Specific Ada Features::
85 * Implementation of Ada 2012 Features::
86 * Obsolescent Features::
87 * GNU Free Documentation License::
90 --- The Detailed Node Listing ---
94 * What This Reference Manual Contains::
95 * Related Information::
97 Implementation Defined Pragmas
99 * Pragma Abort_Defer::
108 * Pragma Assertion_Policy::
109 * Pragma Assume_No_Invalid_Values::
111 * Pragma C_Pass_By_Copy::
113 * Pragma Check_Name::
114 * Pragma Check_Policy::
116 * Pragma Common_Object::
117 * Pragma Compile_Time_Error::
118 * Pragma Compile_Time_Warning::
119 * Pragma Compiler_Unit::
120 * Pragma Complete_Representation::
121 * Pragma Complex_Representation::
122 * Pragma Component_Alignment::
123 * Pragma Convention_Identifier::
125 * Pragma CPP_Constructor::
126 * Pragma CPP_Virtual::
127 * Pragma CPP_Vtable::
129 * Pragma Debug_Policy::
130 * Pragma Detect_Blocking::
131 * Pragma Elaboration_Checks::
133 * Pragma Export_Exception::
134 * Pragma Export_Function::
135 * Pragma Export_Object::
136 * Pragma Export_Procedure::
137 * Pragma Export_Value::
138 * Pragma Export_Valued_Procedure::
139 * Pragma Extend_System::
140 * Pragma Extensions_Allowed::
142 * Pragma External_Name_Casing::
144 * Pragma Favor_Top_Level::
145 * Pragma Finalize_Storage_Only::
146 * Pragma Float_Representation::
148 * Pragma Implemented::
149 * Pragma Implicit_Packing::
150 * Pragma Import_Exception::
151 * Pragma Import_Function::
152 * Pragma Import_Object::
153 * Pragma Import_Procedure::
154 * Pragma Import_Valued_Procedure::
155 * Pragma Initialize_Scalars::
156 * Pragma Inline_Always::
157 * Pragma Inline_Generic::
159 * Pragma Interface_Name::
160 * Pragma Interrupt_Handler::
161 * Pragma Interrupt_State::
163 * Pragma Keep_Names::
166 * Pragma Linker_Alias::
167 * Pragma Linker_Constructor::
168 * Pragma Linker_Destructor::
169 * Pragma Linker_Section::
170 * Pragma Long_Float::
171 * Pragma Machine_Attribute::
173 * Pragma Main_Storage::
176 * Pragma No_Strict_Aliasing ::
177 * Pragma Normalize_Scalars::
178 * Pragma Obsolescent::
179 * Pragma Optimize_Alignment::
182 * Pragma Persistent_BSS::
184 * Pragma Postcondition::
185 * Pragma Precondition::
186 * Pragma Profile (Ravenscar)::
187 * Pragma Profile (Restricted)::
188 * Pragma Psect_Object::
189 * Pragma Pure_Function::
190 * Pragma Remote_Access_Type::
191 * Pragma Restriction_Warnings::
193 * Pragma Short_Circuit_And_Or::
194 * Pragma Short_Descriptors::
195 * Pragma Simple_Storage_Pool_Type::
196 * Pragma Source_File_Name::
197 * Pragma Source_File_Name_Project::
198 * Pragma Source_Reference::
199 * Pragma Static_Elaboration_Desired::
200 * Pragma Stream_Convert::
201 * Pragma Style_Checks::
204 * Pragma Suppress_All::
205 * Pragma Suppress_Exception_Locations::
206 * Pragma Suppress_Initialization::
209 * Pragma Task_Storage::
211 * Pragma Thread_Local_Storage::
212 * Pragma Time_Slice::
214 * Pragma Unchecked_Union::
215 * Pragma Unimplemented_Unit::
216 * Pragma Universal_Aliasing ::
217 * Pragma Universal_Data::
218 * Pragma Unmodified::
219 * Pragma Unreferenced::
220 * Pragma Unreferenced_Objects::
221 * Pragma Unreserve_All_Interrupts::
222 * Pragma Unsuppress::
223 * Pragma Use_VADS_Size::
224 * Pragma Validity_Checks::
227 * Pragma Weak_External::
228 * Pragma Wide_Character_Encoding::
230 Implementation Defined Attributes
241 * Default_Bit_Order::
253 * Has_Access_Values::
254 * Has_Discriminants::
261 * Max_Interrupt_Priority::
263 * Maximum_Alignment::
268 * Passed_By_Reference::
274 * Simple_Storage_Pool::
278 * System_Allocator_Alignment::
284 * Unconstrained_Array::
285 * Universal_Literal_String::
286 * Unrestricted_Access::
292 Implementation Defined Restrictions
294 * Partition-Wide Restrictions::
295 * Program Unit Level Restrictions::
297 Partition-Wide Restrictions
299 * Immediate_Reclamation::
300 * Max_Asynchronous_Select_Nesting::
301 * Max_Entry_Queue_Length::
302 * Max_Protected_Entries::
303 * Max_Select_Alternatives::
304 * Max_Storage_At_Blocking::
307 * No_Abort_Statements::
308 * No_Access_Parameter_Allocators::
309 * No_Access_Subprograms::
311 * No_Anonymous_Allocators::
314 * No_Default_Initialization::
317 * No_Direct_Boolean_Operators::
319 * No_Dispatching_Calls::
320 * No_Dynamic_Attachment::
321 * No_Dynamic_Priorities::
322 * No_Entry_Calls_In_Elaboration_Code::
323 * No_Enumeration_Maps::
324 * No_Exception_Handlers::
325 * No_Exception_Propagation::
326 * No_Exception_Registration::
330 * No_Floating_Point::
331 * No_Implicit_Conditionals::
332 * No_Implicit_Dynamic_Code::
333 * No_Implicit_Heap_Allocations::
334 * No_Implicit_Loops::
335 * No_Initialize_Scalars::
337 * No_Local_Allocators::
338 * No_Local_Protected_Objects::
339 * No_Local_Timing_Events::
340 * No_Nested_Finalization::
341 * No_Protected_Type_Allocators::
342 * No_Protected_Types::
345 * No_Relative_Delay::
346 * No_Requeue_Statements::
347 * No_Secondary_Stack::
348 * No_Select_Statements::
349 * No_Specific_Termination_Handlers::
350 * No_Specification_of_Aspect::
351 * No_Standard_Allocators_After_Elaboration::
352 * No_Standard_Storage_Pools::
353 * No_Stream_Optimizations::
355 * No_Task_Allocators::
356 * No_Task_Attributes_Package::
357 * No_Task_Hierarchy::
358 * No_Task_Termination::
360 * No_Terminate_Alternatives::
361 * No_Unchecked_Access::
363 * Static_Priorities::
364 * Static_Storage_Size::
366 Program Unit Level Restrictions
368 * No_Elaboration_Code::
370 * No_Implementation_Aspect_Specifications::
371 * No_Implementation_Attributes::
372 * No_Implementation_Identifiers::
373 * No_Implementation_Pragmas::
374 * No_Implementation_Restrictions::
375 * No_Implementation_Units::
376 * No_Implicit_Aliasing::
377 * No_Obsolescent_Features::
378 * No_Wide_Characters::
381 The Implementation of Standard I/O
383 * Standard I/O Packages::
389 * Wide_Wide_Text_IO::
393 * Filenames encoding::
395 * Operations on C Streams::
396 * Interfacing to C Streams::
400 * Ada.Characters.Latin_9 (a-chlat9.ads)::
401 * Ada.Characters.Wide_Latin_1 (a-cwila1.ads)::
402 * Ada.Characters.Wide_Latin_9 (a-cwila9.ads)::
403 * Ada.Characters.Wide_Wide_Latin_1 (a-chzla1.ads)::
404 * Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads)::
405 * Ada.Containers.Formal_Doubly_Linked_Lists (a-cfdlli.ads)::
406 * Ada.Containers.Formal_Hashed_Maps (a-cfhama.ads)::
407 * Ada.Containers.Formal_Hashed_Sets (a-cfhase.ads)::
408 * Ada.Containers.Formal_Ordered_Maps (a-cforma.ads)::
409 * Ada.Containers.Formal_Ordered_Sets (a-cforse.ads)::
410 * Ada.Containers.Formal_Vectors (a-cofove.ads)::
411 * Ada.Command_Line.Environment (a-colien.ads)::
412 * Ada.Command_Line.Remove (a-colire.ads)::
413 * Ada.Command_Line.Response_File (a-clrefi.ads)::
414 * Ada.Direct_IO.C_Streams (a-diocst.ads)::
415 * Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads)::
416 * Ada.Exceptions.Last_Chance_Handler (a-elchha.ads)::
417 * Ada.Exceptions.Traceback (a-exctra.ads)::
418 * Ada.Sequential_IO.C_Streams (a-siocst.ads)::
419 * Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads)::
420 * Ada.Strings.Unbounded.Text_IO (a-suteio.ads)::
421 * Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads)::
422 * Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads)::
423 * Ada.Text_IO.C_Streams (a-tiocst.ads)::
424 * Ada.Text_IO.Reset_Standard_Files (a-tirsfi.ads)::
425 * Ada.Wide_Characters.Unicode (a-wichun.ads)::
426 * Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads)::
427 * Ada.Wide_Text_IO.Reset_Standard_Files (a-wrstfi.ads)::
428 * Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads)::
429 * Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads)::
430 * Ada.Wide_Wide_Text_IO.Reset_Standard_Files (a-zrstfi.ads)::
431 * GNAT.Altivec (g-altive.ads)::
432 * GNAT.Altivec.Conversions (g-altcon.ads)::
433 * GNAT.Altivec.Vector_Operations (g-alveop.ads)::
434 * GNAT.Altivec.Vector_Types (g-alvety.ads)::
435 * GNAT.Altivec.Vector_Views (g-alvevi.ads)::
436 * GNAT.Array_Split (g-arrspl.ads)::
437 * GNAT.AWK (g-awk.ads)::
438 * GNAT.Bounded_Buffers (g-boubuf.ads)::
439 * GNAT.Bounded_Mailboxes (g-boumai.ads)::
440 * GNAT.Bubble_Sort (g-bubsor.ads)::
441 * GNAT.Bubble_Sort_A (g-busora.ads)::
442 * GNAT.Bubble_Sort_G (g-busorg.ads)::
443 * GNAT.Byte_Order_Mark (g-byorma.ads)::
444 * GNAT.Byte_Swapping (g-bytswa.ads)::
445 * GNAT.Calendar (g-calend.ads)::
446 * GNAT.Calendar.Time_IO (g-catiio.ads)::
447 * GNAT.Case_Util (g-casuti.ads)::
448 * GNAT.CGI (g-cgi.ads)::
449 * GNAT.CGI.Cookie (g-cgicoo.ads)::
450 * GNAT.CGI.Debug (g-cgideb.ads)::
451 * GNAT.Command_Line (g-comlin.ads)::
452 * GNAT.Compiler_Version (g-comver.ads)::
453 * GNAT.Ctrl_C (g-ctrl_c.ads)::
454 * GNAT.CRC32 (g-crc32.ads)::
455 * GNAT.Current_Exception (g-curexc.ads)::
456 * GNAT.Debug_Pools (g-debpoo.ads)::
457 * GNAT.Debug_Utilities (g-debuti.ads)::
458 * GNAT.Decode_String (g-decstr.ads)::
459 * GNAT.Decode_UTF8_String (g-deutst.ads)::
460 * GNAT.Directory_Operations (g-dirope.ads)::
461 * GNAT.Directory_Operations.Iteration (g-diopit.ads)::
462 * GNAT.Dynamic_HTables (g-dynhta.ads)::
463 * GNAT.Dynamic_Tables (g-dyntab.ads)::
464 * GNAT.Encode_String (g-encstr.ads)::
465 * GNAT.Encode_UTF8_String (g-enutst.ads)::
466 * GNAT.Exception_Actions (g-excact.ads)::
467 * GNAT.Exception_Traces (g-exctra.ads)::
468 * GNAT.Exceptions (g-except.ads)::
469 * GNAT.Expect (g-expect.ads)::
470 * GNAT.Expect.TTY (g-exptty.ads)::
471 * GNAT.Float_Control (g-flocon.ads)::
472 * GNAT.Heap_Sort (g-heasor.ads)::
473 * GNAT.Heap_Sort_A (g-hesora.ads)::
474 * GNAT.Heap_Sort_G (g-hesorg.ads)::
475 * GNAT.HTable (g-htable.ads)::
476 * GNAT.IO (g-io.ads)::
477 * GNAT.IO_Aux (g-io_aux.ads)::
478 * GNAT.Lock_Files (g-locfil.ads)::
479 * GNAT.MBBS_Discrete_Random (g-mbdira.ads)::
480 * GNAT.MBBS_Float_Random (g-mbflra.ads)::
481 * GNAT.MD5 (g-md5.ads)::
482 * GNAT.Memory_Dump (g-memdum.ads)::
483 * GNAT.Most_Recent_Exception (g-moreex.ads)::
484 * GNAT.OS_Lib (g-os_lib.ads)::
485 * GNAT.Perfect_Hash_Generators (g-pehage.ads)::
486 * GNAT.Random_Numbers (g-rannum.ads)::
487 * GNAT.Regexp (g-regexp.ads)::
488 * GNAT.Registry (g-regist.ads)::
489 * GNAT.Regpat (g-regpat.ads)::
490 * GNAT.Secondary_Stack_Info (g-sestin.ads)::
491 * GNAT.Semaphores (g-semaph.ads)::
492 * GNAT.Serial_Communications (g-sercom.ads)::
493 * GNAT.SHA1 (g-sha1.ads)::
494 * GNAT.SHA224 (g-sha224.ads)::
495 * GNAT.SHA256 (g-sha256.ads)::
496 * GNAT.SHA384 (g-sha384.ads)::
497 * GNAT.SHA512 (g-sha512.ads)::
498 * GNAT.Signals (g-signal.ads)::
499 * GNAT.Sockets (g-socket.ads)::
500 * GNAT.Source_Info (g-souinf.ads)::
501 * GNAT.Spelling_Checker (g-speche.ads)::
502 * GNAT.Spelling_Checker_Generic (g-spchge.ads)::
503 * GNAT.Spitbol.Patterns (g-spipat.ads)::
504 * GNAT.Spitbol (g-spitbo.ads)::
505 * GNAT.Spitbol.Table_Boolean (g-sptabo.ads)::
506 * GNAT.Spitbol.Table_Integer (g-sptain.ads)::
507 * GNAT.Spitbol.Table_VString (g-sptavs.ads)::
508 * GNAT.SSE (g-sse.ads)::
509 * GNAT.SSE.Vector_Types (g-ssvety.ads)::
510 * GNAT.Strings (g-string.ads)::
511 * GNAT.String_Split (g-strspl.ads)::
512 * GNAT.Table (g-table.ads)::
513 * GNAT.Task_Lock (g-tasloc.ads)::
514 * GNAT.Threads (g-thread.ads)::
515 * GNAT.Time_Stamp (g-timsta.ads)::
516 * GNAT.Traceback (g-traceb.ads)::
517 * GNAT.Traceback.Symbolic (g-trasym.ads)::
518 * GNAT.UTF_32 (g-utf_32.ads)::
519 * GNAT.UTF_32_Spelling_Checker (g-u3spch.ads)::
520 * GNAT.Wide_Spelling_Checker (g-wispch.ads)::
521 * GNAT.Wide_String_Split (g-wistsp.ads)::
522 * GNAT.Wide_Wide_Spelling_Checker (g-zspche.ads)::
523 * GNAT.Wide_Wide_String_Split (g-zistsp.ads)::
524 * Interfaces.C.Extensions (i-cexten.ads)::
525 * Interfaces.C.Streams (i-cstrea.ads)::
526 * Interfaces.CPP (i-cpp.ads)::
527 * Interfaces.Packed_Decimal (i-pacdec.ads)::
528 * Interfaces.VxWorks (i-vxwork.ads)::
529 * Interfaces.VxWorks.IO (i-vxwoio.ads)::
530 * System.Address_Image (s-addima.ads)::
531 * System.Assertions (s-assert.ads)::
532 * System.Memory (s-memory.ads)::
533 * System.Partition_Interface (s-parint.ads)::
534 * System.Pool_Global (s-pooglo.ads)::
535 * System.Pool_Local (s-pooloc.ads)::
536 * System.Restrictions (s-restri.ads)::
537 * System.Rident (s-rident.ads)::
538 * System.Strings.Stream_Ops (s-ststop.ads)::
539 * System.Task_Info (s-tasinf.ads)::
540 * System.Wch_Cnv (s-wchcnv.ads)::
541 * System.Wch_Con (s-wchcon.ads)::
545 * Text_IO Stream Pointer Positioning::
546 * Text_IO Reading and Writing Non-Regular Files::
548 * Treating Text_IO Files as Streams::
549 * Text_IO Extensions::
550 * Text_IO Facilities for Unbounded Strings::
554 * Wide_Text_IO Stream Pointer Positioning::
555 * Wide_Text_IO Reading and Writing Non-Regular Files::
559 * Wide_Wide_Text_IO Stream Pointer Positioning::
560 * Wide_Wide_Text_IO Reading and Writing Non-Regular Files::
562 Interfacing to Other Languages
565 * Interfacing to C++::
566 * Interfacing to COBOL::
567 * Interfacing to Fortran::
568 * Interfacing to non-GNAT Ada code::
570 Specialized Needs Annexes
572 Implementation of Specific Ada Features
573 * Machine Code Insertions::
574 * GNAT Implementation of Tasking::
575 * GNAT Implementation of Shared Passive Packages::
576 * Code Generation for Array Aggregates::
577 * The Size of Discriminated Records with Default Discriminants::
578 * Strict Conformance to the Ada Reference Manual::
580 Implementation of Ada 2012 Features
584 GNU Free Documentation License
591 @node About This Guide
592 @unnumbered About This Guide
595 This manual contains useful information in writing programs using the
596 @value{EDITION} compiler. It includes information on implementation dependent
597 characteristics of @value{EDITION}, including all the information required by
598 Annex M of the Ada language standard.
600 @value{EDITION} implements Ada 95 and Ada 2005, and it may also be invoked in
601 Ada 83 compatibility mode.
602 By default, @value{EDITION} assumes @value{DEFAULTLANGUAGEVERSION},
603 but you can override with a compiler switch
604 to explicitly specify the language version.
605 (Please refer to @ref{Compiling Different Versions of Ada,,, gnat_ugn,
606 @value{EDITION} User's Guide}, for details on these switches.)
607 Throughout this manual, references to ``Ada'' without a year suffix
608 apply to both the Ada 95 and Ada 2005 versions of the language.
610 Ada is designed to be highly portable.
611 In general, a program will have the same effect even when compiled by
612 different compilers on different platforms.
613 However, since Ada is designed to be used in a
614 wide variety of applications, it also contains a number of system
615 dependent features to be used in interfacing to the external world.
616 @cindex Implementation-dependent features
619 Note: Any program that makes use of implementation-dependent features
620 may be non-portable. You should follow good programming practice and
621 isolate and clearly document any sections of your program that make use
622 of these features in a non-portable manner.
625 For ease of exposition, ``@value{EDITION}'' will be referred to simply as
626 ``GNAT'' in the remainder of this document.
630 * What This Reference Manual Contains::
632 * Related Information::
635 @node What This Reference Manual Contains
636 @unnumberedsec What This Reference Manual Contains
639 This reference manual contains the following chapters:
643 @ref{Implementation Defined Pragmas}, lists GNAT implementation-dependent
644 pragmas, which can be used to extend and enhance the functionality of the
648 @ref{Implementation Defined Attributes}, lists GNAT
649 implementation-dependent attributes, which can be used to extend and
650 enhance the functionality of the compiler.
653 @ref{Implementation Defined Restrictions}, lists GNAT
654 implementation-dependent restrictions, which can be used to extend and
655 enhance the functionality of the compiler.
658 @ref{Implementation Advice}, provides information on generally
659 desirable behavior which are not requirements that all compilers must
660 follow since it cannot be provided on all systems, or which may be
661 undesirable on some systems.
664 @ref{Implementation Defined Characteristics}, provides a guide to
665 minimizing implementation dependent features.
668 @ref{Intrinsic Subprograms}, describes the intrinsic subprograms
669 implemented by GNAT, and how they can be imported into user
670 application programs.
673 @ref{Representation Clauses and Pragmas}, describes in detail the
674 way that GNAT represents data, and in particular the exact set
675 of representation clauses and pragmas that is accepted.
678 @ref{Standard Library Routines}, provides a listing of packages and a
679 brief description of the functionality that is provided by Ada's
680 extensive set of standard library routines as implemented by GNAT@.
683 @ref{The Implementation of Standard I/O}, details how the GNAT
684 implementation of the input-output facilities.
687 @ref{The GNAT Library}, is a catalog of packages that complement
688 the Ada predefined library.
691 @ref{Interfacing to Other Languages}, describes how programs
692 written in Ada using GNAT can be interfaced to other programming
695 @ref{Specialized Needs Annexes}, describes the GNAT implementation of all
696 of the specialized needs annexes.
699 @ref{Implementation of Specific Ada Features}, discusses issues related
700 to GNAT's implementation of machine code insertions, tasking, and several
704 @ref{Implementation of Ada 2012 Features}, describes the status of the
705 GNAT implementation of the Ada 2012 language standard.
708 @ref{Obsolescent Features} documents implementation dependent features,
709 including pragmas and attributes, which are considered obsolescent, since
710 there are other preferred ways of achieving the same results. These
711 obsolescent forms are retained for backwards compatibility.
715 @cindex Ada 95 Language Reference Manual
716 @cindex Ada 2005 Language Reference Manual
718 This reference manual assumes a basic familiarity with the Ada 95 language, as
719 described in the International Standard ANSI/ISO/IEC-8652:1995,
721 It does not require knowledge of the new features introduced by Ada 2005,
722 (officially known as ISO/IEC 8652:1995 with Technical Corrigendum 1
724 Both reference manuals are included in the GNAT documentation
728 @unnumberedsec Conventions
729 @cindex Conventions, typographical
730 @cindex Typographical conventions
733 Following are examples of the typographical and graphic conventions used
738 @code{Functions}, @code{utility program names}, @code{standard names},
745 @file{File names}, @samp{button names}, and @samp{field names}.
748 @code{Variables}, @env{environment variables}, and @var{metasyntactic
755 [optional information or parameters]
758 Examples are described by text
760 and then shown this way.
765 Commands that are entered by the user are preceded in this manual by the
766 characters @samp{$ } (dollar sign followed by space). If your system uses this
767 sequence as a prompt, then the commands will appear exactly as you see them
768 in the manual. If your system uses some other prompt, then the command will
769 appear with the @samp{$} replaced by whatever prompt character you are using.
771 @node Related Information
772 @unnumberedsec Related Information
774 See the following documents for further information on GNAT:
778 @xref{Top, @value{EDITION} User's Guide, About This Guide, gnat_ugn,
779 @value{EDITION} User's Guide}, which provides information on how to use the
780 GNAT compiler system.
783 @cite{Ada 95 Reference Manual}, which contains all reference
784 material for the Ada 95 programming language.
787 @cite{Ada 95 Annotated Reference Manual}, which is an annotated version
788 of the Ada 95 standard. The annotations describe
789 detailed aspects of the design decision, and in particular contain useful
790 sections on Ada 83 compatibility.
793 @cite{Ada 2005 Reference Manual}, which contains all reference
794 material for the Ada 2005 programming language.
797 @cite{Ada 2005 Annotated Reference Manual}, which is an annotated version
798 of the Ada 2005 standard. The annotations describe
799 detailed aspects of the design decision, and in particular contain useful
800 sections on Ada 83 and Ada 95 compatibility.
803 @cite{DEC Ada, Technical Overview and Comparison on DIGITAL Platforms},
804 which contains specific information on compatibility between GNAT and
808 @cite{DEC Ada, Language Reference Manual, part number AA-PYZAB-TK} which
809 describes in detail the pragmas and attributes provided by the DEC Ada 83
814 @node Implementation Defined Pragmas
815 @chapter Implementation Defined Pragmas
818 Ada defines a set of pragmas that can be used to supply additional
819 information to the compiler. These language defined pragmas are
820 implemented in GNAT and work as described in the Ada Reference Manual.
822 In addition, Ada allows implementations to define additional pragmas
823 whose meaning is defined by the implementation. GNAT provides a number
824 of these implementation-defined pragmas, which can be used to extend
825 and enhance the functionality of the compiler. This section of the GNAT
826 Reference Manual describes these additional pragmas.
828 Note that any program using these pragmas might not be portable to other
829 compilers (although GNAT implements this set of pragmas on all
830 platforms). Therefore if portability to other compilers is an important
831 consideration, the use of these pragmas should be minimized.
834 * Pragma Abort_Defer::
843 * Pragma Assertion_Policy::
844 * Pragma Assume_No_Invalid_Values::
846 * Pragma C_Pass_By_Copy::
848 * Pragma Check_Name::
849 * Pragma Check_Policy::
851 * Pragma Common_Object::
852 * Pragma Compile_Time_Error::
853 * Pragma Compile_Time_Warning::
854 * Pragma Compiler_Unit::
855 * Pragma Complete_Representation::
856 * Pragma Complex_Representation::
857 * Pragma Component_Alignment::
858 * Pragma Convention_Identifier::
860 * Pragma CPP_Constructor::
861 * Pragma CPP_Virtual::
862 * Pragma CPP_Vtable::
864 * Pragma Debug_Policy::
865 * Pragma Detect_Blocking::
866 * Pragma Elaboration_Checks::
868 * Pragma Export_Exception::
869 * Pragma Export_Function::
870 * Pragma Export_Object::
871 * Pragma Export_Procedure::
872 * Pragma Export_Value::
873 * Pragma Export_Valued_Procedure::
874 * Pragma Extend_System::
875 * Pragma Extensions_Allowed::
877 * Pragma External_Name_Casing::
879 * Pragma Favor_Top_Level::
880 * Pragma Finalize_Storage_Only::
881 * Pragma Float_Representation::
883 * Pragma Implemented::
884 * Pragma Implicit_Packing::
885 * Pragma Import_Exception::
886 * Pragma Import_Function::
887 * Pragma Import_Object::
888 * Pragma Import_Procedure::
889 * Pragma Import_Valued_Procedure::
890 * Pragma Initialize_Scalars::
891 * Pragma Inline_Always::
892 * Pragma Inline_Generic::
894 * Pragma Interface_Name::
895 * Pragma Interrupt_Handler::
896 * Pragma Interrupt_State::
898 * Pragma Keep_Names::
901 * Pragma Linker_Alias::
902 * Pragma Linker_Constructor::
903 * Pragma Linker_Destructor::
904 * Pragma Linker_Section::
905 * Pragma Long_Float::
906 * Pragma Machine_Attribute::
908 * Pragma Main_Storage::
911 * Pragma No_Strict_Aliasing::
912 * Pragma Normalize_Scalars::
913 * Pragma Obsolescent::
914 * Pragma Optimize_Alignment::
917 * Pragma Persistent_BSS::
919 * Pragma Postcondition::
920 * Pragma Precondition::
921 * Pragma Profile (Ravenscar)::
922 * Pragma Profile (Restricted)::
923 * Pragma Psect_Object::
924 * Pragma Pure_Function::
925 * Pragma Remote_Access_Type::
926 * Pragma Restriction_Warnings::
928 * Pragma Short_Circuit_And_Or::
929 * Pragma Short_Descriptors::
930 * Pragma Simple_Storage_Pool_Type::
931 * Pragma Source_File_Name::
932 * Pragma Source_File_Name_Project::
933 * Pragma Source_Reference::
934 * Pragma Static_Elaboration_Desired::
935 * Pragma Stream_Convert::
936 * Pragma Style_Checks::
939 * Pragma Suppress_All::
940 * Pragma Suppress_Exception_Locations::
941 * Pragma Suppress_Initialization::
944 * Pragma Task_Storage::
946 * Pragma Thread_Local_Storage::
947 * Pragma Time_Slice::
949 * Pragma Unchecked_Union::
950 * Pragma Unimplemented_Unit::
951 * Pragma Universal_Aliasing ::
952 * Pragma Universal_Data::
953 * Pragma Unmodified::
954 * Pragma Unreferenced::
955 * Pragma Unreferenced_Objects::
956 * Pragma Unreserve_All_Interrupts::
957 * Pragma Unsuppress::
958 * Pragma Use_VADS_Size::
959 * Pragma Validity_Checks::
962 * Pragma Weak_External::
963 * Pragma Wide_Character_Encoding::
966 @node Pragma Abort_Defer
967 @unnumberedsec Pragma Abort_Defer
969 @cindex Deferring aborts
977 This pragma must appear at the start of the statement sequence of a
978 handled sequence of statements (right after the @code{begin}). It has
979 the effect of deferring aborts for the sequence of statements (but not
980 for the declarations or handlers, if any, associated with this statement
984 @unnumberedsec Pragma Ada_83
993 A configuration pragma that establishes Ada 83 mode for the unit to
994 which it applies, regardless of the mode set by the command line
995 switches. In Ada 83 mode, GNAT attempts to be as compatible with
996 the syntax and semantics of Ada 83, as defined in the original Ada
997 83 Reference Manual as possible. In particular, the keywords added by Ada 95
998 and Ada 2005 are not recognized, optional package bodies are allowed,
999 and generics may name types with unknown discriminants without using
1000 the @code{(<>)} notation. In addition, some but not all of the additional
1001 restrictions of Ada 83 are enforced.
1003 Ada 83 mode is intended for two purposes. Firstly, it allows existing
1004 Ada 83 code to be compiled and adapted to GNAT with less effort.
1005 Secondly, it aids in keeping code backwards compatible with Ada 83.
1006 However, there is no guarantee that code that is processed correctly
1007 by GNAT in Ada 83 mode will in fact compile and execute with an Ada
1008 83 compiler, since GNAT does not enforce all the additional checks
1012 @unnumberedsec Pragma Ada_95
1016 @smallexample @c ada
1021 A configuration pragma that establishes Ada 95 mode for the unit to which
1022 it applies, regardless of the mode set by the command line switches.
1023 This mode is set automatically for the @code{Ada} and @code{System}
1024 packages and their children, so you need not specify it in these
1025 contexts. This pragma is useful when writing a reusable component that
1026 itself uses Ada 95 features, but which is intended to be usable from
1027 either Ada 83 or Ada 95 programs.
1030 @unnumberedsec Pragma Ada_05
1034 @smallexample @c ada
1039 A configuration pragma that establishes Ada 2005 mode for the unit to which
1040 it applies, regardless of the mode set by the command line switches.
1041 This pragma is useful when writing a reusable component that
1042 itself uses Ada 2005 features, but which is intended to be usable from
1043 either Ada 83 or Ada 95 programs.
1045 @node Pragma Ada_2005
1046 @unnumberedsec Pragma Ada_2005
1050 @smallexample @c ada
1055 This configuration pragma is a synonym for pragma Ada_05 and has the
1056 same syntax and effect.
1059 @unnumberedsec Pragma Ada_12
1063 @smallexample @c ada
1068 A configuration pragma that establishes Ada 2012 mode for the unit to which
1069 it applies, regardless of the mode set by the command line switches.
1070 This mode is set automatically for the @code{Ada} and @code{System}
1071 packages and their children, so you need not specify it in these
1072 contexts. This pragma is useful when writing a reusable component that
1073 itself uses Ada 2012 features, but which is intended to be usable from
1074 Ada 83, Ada 95, or Ada 2005 programs.
1076 @node Pragma Ada_2012
1077 @unnumberedsec Pragma Ada_2012
1081 @smallexample @c ada
1086 This configuration pragma is a synonym for pragma Ada_12 and has the
1087 same syntax and effect.
1089 @node Pragma Annotate
1090 @unnumberedsec Pragma Annotate
1094 @smallexample @c ada
1095 pragma Annotate (IDENTIFIER [,IDENTIFIER @{, ARG@}]);
1097 ARG ::= NAME | EXPRESSION
1101 This pragma is used to annotate programs. @var{identifier} identifies
1102 the type of annotation. GNAT verifies that it is an identifier, but does
1103 not otherwise analyze it. The second optional identifier is also left
1104 unanalyzed, and by convention is used to control the action of the tool to
1105 which the annotation is addressed. The remaining @var{arg} arguments
1106 can be either string literals or more generally expressions.
1107 String literals are assumed to be either of type
1108 @code{Standard.String} or else @code{Wide_String} or @code{Wide_Wide_String}
1109 depending on the character literals they contain.
1110 All other kinds of arguments are analyzed as expressions, and must be
1113 The analyzed pragma is retained in the tree, but not otherwise processed
1114 by any part of the GNAT compiler, except to generate corresponding note
1115 lines in the generated ALI file. For the format of these note lines, see
1116 the compiler source file lib-writ.ads. This pragma is intended for use by
1117 external tools, including ASIS@. The use of pragma Annotate does not
1118 affect the compilation process in any way. This pragma may be used as
1119 a configuration pragma.
1122 @unnumberedsec Pragma Assert
1126 @smallexample @c ada
1129 [, string_EXPRESSION]);
1133 The effect of this pragma depends on whether the corresponding command
1134 line switch is set to activate assertions. The pragma expands into code
1135 equivalent to the following:
1137 @smallexample @c ada
1138 if assertions-enabled then
1139 if not boolean_EXPRESSION then
1140 System.Assertions.Raise_Assert_Failure
1141 (string_EXPRESSION);
1147 The string argument, if given, is the message that will be associated
1148 with the exception occurrence if the exception is raised. If no second
1149 argument is given, the default message is @samp{@var{file}:@var{nnn}},
1150 where @var{file} is the name of the source file containing the assert,
1151 and @var{nnn} is the line number of the assert. A pragma is not a
1152 statement, so if a statement sequence contains nothing but a pragma
1153 assert, then a null statement is required in addition, as in:
1155 @smallexample @c ada
1158 pragma Assert (K > 3, "Bad value for K");
1164 Note that, as with the @code{if} statement to which it is equivalent, the
1165 type of the expression is either @code{Standard.Boolean}, or any type derived
1166 from this standard type.
1168 If assertions are disabled (switch @option{-gnata} not used), then there
1169 is no run-time effect (and in particular, any side effects from the
1170 expression will not occur at run time). (The expression is still
1171 analyzed at compile time, and may cause types to be frozen if they are
1172 mentioned here for the first time).
1174 If assertions are enabled, then the given expression is tested, and if
1175 it is @code{False} then @code{System.Assertions.Raise_Assert_Failure} is called
1176 which results in the raising of @code{Assert_Failure} with the given message.
1178 You should generally avoid side effects in the expression arguments of
1179 this pragma, because these side effects will turn on and off with the
1180 setting of the assertions mode, resulting in assertions that have an
1181 effect on the program. However, the expressions are analyzed for
1182 semantic correctness whether or not assertions are enabled, so turning
1183 assertions on and off cannot affect the legality of a program.
1185 Note that the implementation defined policy @code{DISABLE}, given in a
1186 pragma Assertion_Policy, can be used to suppress this semantic analysis.
1188 Note: this is a standard language-defined pragma in versions
1189 of Ada from 2005 on. In GNAT, it is implemented in all versions
1190 of Ada, and the DISABLE policy is an implementation-defined
1194 @node Pragma Assertion_Policy
1195 @unnumberedsec Pragma Assertion_Policy
1196 @findex Debug_Policy
1200 @smallexample @c ada
1201 pragma Assertion_Policy (CHECK | DISABLE | IGNORE);
1205 If the argument is @code{CHECK}, then pragma @code{Assert} is enabled.
1206 If the argument is @code{IGNORE}, then pragma @code{Assert} is ignored.
1207 This pragma overrides the effect of the @option{-gnata} switch on the
1210 The implementation defined policy @code{DISABLE} is like
1211 @code{IGNORE} except that it completely disables semantic
1212 checking of the argument to @code{pragma Assert}. This may
1213 be useful when the pragma argument references subprograms
1214 in a with'ed package which is replaced by a dummy package
1215 for the final build.
1217 Note: this is a standard language-defined pragma in versions
1218 of Ada from 2005 on. In GNAT, it is implemented in all versions
1219 of Ada, and the DISABLE policy is an implementation-defined
1222 @node Pragma Assume_No_Invalid_Values
1223 @unnumberedsec Pragma Assume_No_Invalid_Values
1224 @findex Assume_No_Invalid_Values
1225 @cindex Invalid representations
1226 @cindex Invalid values
1229 @smallexample @c ada
1230 pragma Assume_No_Invalid_Values (On | Off);
1234 This is a configuration pragma that controls the assumptions made by the
1235 compiler about the occurrence of invalid representations (invalid values)
1238 The default behavior (corresponding to an Off argument for this pragma), is
1239 to assume that values may in general be invalid unless the compiler can
1240 prove they are valid. Consider the following example:
1242 @smallexample @c ada
1243 V1 : Integer range 1 .. 10;
1244 V2 : Integer range 11 .. 20;
1246 for J in V2 .. V1 loop
1252 if V1 and V2 have valid values, then the loop is known at compile
1253 time not to execute since the lower bound must be greater than the
1254 upper bound. However in default mode, no such assumption is made,
1255 and the loop may execute. If @code{Assume_No_Invalid_Values (On)}
1256 is given, the compiler will assume that any occurrence of a variable
1257 other than in an explicit @code{'Valid} test always has a valid
1258 value, and the loop above will be optimized away.
1260 The use of @code{Assume_No_Invalid_Values (On)} is appropriate if
1261 you know your code is free of uninitialized variables and other
1262 possible sources of invalid representations, and may result in
1263 more efficient code. A program that accesses an invalid representation
1264 with this pragma in effect is erroneous, so no guarantees can be made
1267 It is peculiar though permissible to use this pragma in conjunction
1268 with validity checking (-gnatVa). In such cases, accessing invalid
1269 values will generally give an exception, though formally the program
1270 is erroneous so there are no guarantees that this will always be the
1271 case, and it is recommended that these two options not be used together.
1273 @node Pragma Ast_Entry
1274 @unnumberedsec Pragma Ast_Entry
1279 @smallexample @c ada
1280 pragma AST_Entry (entry_IDENTIFIER);
1284 This pragma is implemented only in the OpenVMS implementation of GNAT@. The
1285 argument is the simple name of a single entry; at most one @code{AST_Entry}
1286 pragma is allowed for any given entry. This pragma must be used in
1287 conjunction with the @code{AST_Entry} attribute, and is only allowed after
1288 the entry declaration and in the same task type specification or single task
1289 as the entry to which it applies. This pragma specifies that the given entry
1290 may be used to handle an OpenVMS asynchronous system trap (@code{AST})
1291 resulting from an OpenVMS system service call. The pragma does not affect
1292 normal use of the entry. For further details on this pragma, see the
1293 DEC Ada Language Reference Manual, section 9.12a.
1295 @node Pragma C_Pass_By_Copy
1296 @unnumberedsec Pragma C_Pass_By_Copy
1297 @cindex Passing by copy
1298 @findex C_Pass_By_Copy
1301 @smallexample @c ada
1302 pragma C_Pass_By_Copy
1303 ([Max_Size =>] static_integer_EXPRESSION);
1307 Normally the default mechanism for passing C convention records to C
1308 convention subprograms is to pass them by reference, as suggested by RM
1309 B.3(69). Use the configuration pragma @code{C_Pass_By_Copy} to change
1310 this default, by requiring that record formal parameters be passed by
1311 copy if all of the following conditions are met:
1315 The size of the record type does not exceed the value specified for
1318 The record type has @code{Convention C}.
1320 The formal parameter has this record type, and the subprogram has a
1321 foreign (non-Ada) convention.
1325 If these conditions are met the argument is passed by copy, i.e.@: in a
1326 manner consistent with what C expects if the corresponding formal in the
1327 C prototype is a struct (rather than a pointer to a struct).
1329 You can also pass records by copy by specifying the convention
1330 @code{C_Pass_By_Copy} for the record type, or by using the extended
1331 @code{Import} and @code{Export} pragmas, which allow specification of
1332 passing mechanisms on a parameter by parameter basis.
1335 @unnumberedsec Pragma Check
1337 @cindex Named assertions
1341 @smallexample @c ada
1343 [Name =>] Identifier,
1344 [Check =>] Boolean_EXPRESSION
1345 [, [Message =>] string_EXPRESSION] );
1349 This pragma is similar to the predefined pragma @code{Assert} except that an
1350 extra identifier argument is present. In conjunction with pragma
1351 @code{Check_Policy}, this can be used to define groups of assertions that can
1352 be independently controlled. The identifier @code{Assertion} is special, it
1353 refers to the normal set of pragma @code{Assert} statements. The identifiers
1354 @code{Precondition} and @code{Postcondition} correspond to the pragmas of these
1355 names, so these three names would normally not be used directly in a pragma
1358 Checks introduced by this pragma are normally deactivated by default. They can
1359 be activated either by the command line option @option{-gnata}, which turns on
1360 all checks, or individually controlled using pragma @code{Check_Policy}.
1362 @node Pragma Check_Name
1363 @unnumberedsec Pragma Check_Name
1364 @cindex Defining check names
1365 @cindex Check names, defining
1369 @smallexample @c ada
1370 pragma Check_Name (check_name_IDENTIFIER);
1374 This is a configuration pragma that defines a new implementation
1375 defined check name (unless IDENTIFIER matches one of the predefined
1376 check names, in which case the pragma has no effect). Check names
1377 are global to a partition, so if two or more configuration pragmas
1378 are present in a partition mentioning the same name, only one new
1379 check name is introduced.
1381 An implementation defined check name introduced with this pragma may
1382 be used in only three contexts: @code{pragma Suppress},
1383 @code{pragma Unsuppress},
1384 and as the prefix of a @code{Check_Name'Enabled} attribute reference. For
1385 any of these three cases, the check name must be visible. A check
1386 name is visible if it is in the configuration pragmas applying to
1387 the current unit, or if it appears at the start of any unit that
1388 is part of the dependency set of the current unit (e.g., units that
1389 are mentioned in @code{with} clauses).
1391 @node Pragma Check_Policy
1392 @unnumberedsec Pragma Check_Policy
1393 @cindex Controlling assertions
1394 @cindex Assertions, control
1395 @cindex Check pragma control
1396 @cindex Named assertions
1400 @smallexample @c ada
1402 ([Name =>] Identifier,
1403 [Policy =>] POLICY_IDENTIFIER);
1405 POLICY_IDENTIFIER ::= ON | OFF | CHECK | DISABLE | IGNORE
1409 This pragma is similar to the predefined pragma @code{Assertion_Policy},
1410 except that it controls sets of named assertions introduced using the
1411 @code{Check} pragmas. It can be used as a configuration pragma or (unlike
1412 @code{Assertion_Policy}) can be used within a declarative part, in which case
1413 it controls the status to the end of the corresponding construct (in a manner
1414 identical to pragma @code{Suppress)}.
1416 The identifier given as the first argument corresponds to a name used in
1417 associated @code{Check} pragmas. For example, if the pragma:
1419 @smallexample @c ada
1420 pragma Check_Policy (Critical_Error, OFF);
1424 is given, then subsequent @code{Check} pragmas whose first argument is also
1425 @code{Critical_Error} will be disabled. The special identifier @code{Assertion}
1426 controls the behavior of normal @code{Assert} pragmas (thus a pragma
1427 @code{Check_Policy} with this identifier is similar to the normal
1428 @code{Assertion_Policy} pragma except that it can appear within a
1431 The special identifiers @code{Precondition} and @code{Postcondition} control
1432 the status of preconditions and postconditions. If a @code{Precondition} pragma
1433 is encountered, it is ignored if turned off by a @code{Check_Policy} specifying
1434 that @code{Precondition} checks are @code{Off} or @code{Ignored}. Similarly use
1435 of the name @code{Postcondition} controls whether @code{Postcondition} pragmas
1438 The check policy is @code{OFF} to turn off corresponding checks, and @code{ON}
1439 to turn on corresponding checks. The default for a set of checks for which no
1440 @code{Check_Policy} is given is @code{OFF} unless the compiler switch
1441 @option{-gnata} is given, which turns on all checks by default.
1443 The check policy settings @code{CHECK} and @code{IGNORE} are also recognized
1444 as synonyms for @code{ON} and @code{OFF}. These synonyms are provided for
1445 compatibility with the standard @code{Assertion_Policy} pragma.
1447 The implementation defined policy @code{DISABLE} is like
1448 @code{OFF} except that it completely disables semantic
1449 checking of the argument to the corresponding class of
1450 pragmas. This may be useful when the pragma arguments reference
1451 subprograms in a with'ed package which is replaced by a dummy package
1452 for the final build.
1454 @node Pragma Comment
1455 @unnumberedsec Pragma Comment
1460 @smallexample @c ada
1461 pragma Comment (static_string_EXPRESSION);
1465 This is almost identical in effect to pragma @code{Ident}. It allows the
1466 placement of a comment into the object file and hence into the
1467 executable file if the operating system permits such usage. The
1468 difference is that @code{Comment}, unlike @code{Ident}, has
1469 no limitations on placement of the pragma (it can be placed
1470 anywhere in the main source unit), and if more than one pragma
1471 is used, all comments are retained.
1473 @node Pragma Common_Object
1474 @unnumberedsec Pragma Common_Object
1475 @findex Common_Object
1479 @smallexample @c ada
1480 pragma Common_Object (
1481 [Internal =>] LOCAL_NAME
1482 [, [External =>] EXTERNAL_SYMBOL]
1483 [, [Size =>] EXTERNAL_SYMBOL] );
1487 | static_string_EXPRESSION
1491 This pragma enables the shared use of variables stored in overlaid
1492 linker areas corresponding to the use of @code{COMMON}
1493 in Fortran. The single
1494 object @var{LOCAL_NAME} is assigned to the area designated by
1495 the @var{External} argument.
1496 You may define a record to correspond to a series
1497 of fields. The @var{Size} argument
1498 is syntax checked in GNAT, but otherwise ignored.
1500 @code{Common_Object} is not supported on all platforms. If no
1501 support is available, then the code generator will issue a message
1502 indicating that the necessary attribute for implementation of this
1503 pragma is not available.
1505 @node Pragma Compile_Time_Error
1506 @unnumberedsec Pragma Compile_Time_Error
1507 @findex Compile_Time_Error
1511 @smallexample @c ada
1512 pragma Compile_Time_Error
1513 (boolean_EXPRESSION, static_string_EXPRESSION);
1517 This pragma can be used to generate additional compile time
1519 is particularly useful in generics, where errors can be issued for
1520 specific problematic instantiations. The first parameter is a boolean
1521 expression. The pragma is effective only if the value of this expression
1522 is known at compile time, and has the value True. The set of expressions
1523 whose values are known at compile time includes all static boolean
1524 expressions, and also other values which the compiler can determine
1525 at compile time (e.g., the size of a record type set by an explicit
1526 size representation clause, or the value of a variable which was
1527 initialized to a constant and is known not to have been modified).
1528 If these conditions are met, an error message is generated using
1529 the value given as the second argument. This string value may contain
1530 embedded ASCII.LF characters to break the message into multiple lines.
1532 @node Pragma Compile_Time_Warning
1533 @unnumberedsec Pragma Compile_Time_Warning
1534 @findex Compile_Time_Warning
1538 @smallexample @c ada
1539 pragma Compile_Time_Warning
1540 (boolean_EXPRESSION, static_string_EXPRESSION);
1544 Same as pragma Compile_Time_Error, except a warning is issued instead
1545 of an error message. Note that if this pragma is used in a package that
1546 is with'ed by a client, the client will get the warning even though it
1547 is issued by a with'ed package (normally warnings in with'ed units are
1548 suppressed, but this is a special exception to that rule).
1550 One typical use is within a generic where compile time known characteristics
1551 of formal parameters are tested, and warnings given appropriately. Another use
1552 with a first parameter of True is to warn a client about use of a package,
1553 for example that it is not fully implemented.
1555 @node Pragma Compiler_Unit
1556 @unnumberedsec Pragma Compiler_Unit
1557 @findex Compiler_Unit
1561 @smallexample @c ada
1562 pragma Compiler_Unit;
1566 This pragma is intended only for internal use in the GNAT run-time library.
1567 It indicates that the unit is used as part of the compiler build. The effect
1568 is to disallow constructs (raise with message, conditional expressions etc)
1569 that would cause trouble when bootstrapping using an older version of GNAT.
1570 For the exact list of restrictions, see the compiler sources and references
1571 to Is_Compiler_Unit.
1573 @node Pragma Complete_Representation
1574 @unnumberedsec Pragma Complete_Representation
1575 @findex Complete_Representation
1579 @smallexample @c ada
1580 pragma Complete_Representation;
1584 This pragma must appear immediately within a record representation
1585 clause. Typical placements are before the first component clause
1586 or after the last component clause. The effect is to give an error
1587 message if any component is missing a component clause. This pragma
1588 may be used to ensure that a record representation clause is
1589 complete, and that this invariant is maintained if fields are
1590 added to the record in the future.
1592 @node Pragma Complex_Representation
1593 @unnumberedsec Pragma Complex_Representation
1594 @findex Complex_Representation
1598 @smallexample @c ada
1599 pragma Complex_Representation
1600 ([Entity =>] LOCAL_NAME);
1604 The @var{Entity} argument must be the name of a record type which has
1605 two fields of the same floating-point type. The effect of this pragma is
1606 to force gcc to use the special internal complex representation form for
1607 this record, which may be more efficient. Note that this may result in
1608 the code for this type not conforming to standard ABI (application
1609 binary interface) requirements for the handling of record types. For
1610 example, in some environments, there is a requirement for passing
1611 records by pointer, and the use of this pragma may result in passing
1612 this type in floating-point registers.
1614 @node Pragma Component_Alignment
1615 @unnumberedsec Pragma Component_Alignment
1616 @cindex Alignments of components
1617 @findex Component_Alignment
1621 @smallexample @c ada
1622 pragma Component_Alignment (
1623 [Form =>] ALIGNMENT_CHOICE
1624 [, [Name =>] type_LOCAL_NAME]);
1626 ALIGNMENT_CHOICE ::=
1634 Specifies the alignment of components in array or record types.
1635 The meaning of the @var{Form} argument is as follows:
1638 @findex Component_Size
1639 @item Component_Size
1640 Aligns scalar components and subcomponents of the array or record type
1641 on boundaries appropriate to their inherent size (naturally
1642 aligned). For example, 1-byte components are aligned on byte boundaries,
1643 2-byte integer components are aligned on 2-byte boundaries, 4-byte
1644 integer components are aligned on 4-byte boundaries and so on. These
1645 alignment rules correspond to the normal rules for C compilers on all
1646 machines except the VAX@.
1648 @findex Component_Size_4
1649 @item Component_Size_4
1650 Naturally aligns components with a size of four or fewer
1651 bytes. Components that are larger than 4 bytes are placed on the next
1654 @findex Storage_Unit
1656 Specifies that array or record components are byte aligned, i.e.@:
1657 aligned on boundaries determined by the value of the constant
1658 @code{System.Storage_Unit}.
1662 Specifies that array or record components are aligned on default
1663 boundaries, appropriate to the underlying hardware or operating system or
1664 both. For OpenVMS VAX systems, the @code{Default} choice is the same as
1665 the @code{Storage_Unit} choice (byte alignment). For all other systems,
1666 the @code{Default} choice is the same as @code{Component_Size} (natural
1671 If the @code{Name} parameter is present, @var{type_LOCAL_NAME} must
1672 refer to a local record or array type, and the specified alignment
1673 choice applies to the specified type. The use of
1674 @code{Component_Alignment} together with a pragma @code{Pack} causes the
1675 @code{Component_Alignment} pragma to be ignored. The use of
1676 @code{Component_Alignment} together with a record representation clause
1677 is only effective for fields not specified by the representation clause.
1679 If the @code{Name} parameter is absent, the pragma can be used as either
1680 a configuration pragma, in which case it applies to one or more units in
1681 accordance with the normal rules for configuration pragmas, or it can be
1682 used within a declarative part, in which case it applies to types that
1683 are declared within this declarative part, or within any nested scope
1684 within this declarative part. In either case it specifies the alignment
1685 to be applied to any record or array type which has otherwise standard
1688 If the alignment for a record or array type is not specified (using
1689 pragma @code{Pack}, pragma @code{Component_Alignment}, or a record rep
1690 clause), the GNAT uses the default alignment as described previously.
1692 @node Pragma Convention_Identifier
1693 @unnumberedsec Pragma Convention_Identifier
1694 @findex Convention_Identifier
1695 @cindex Conventions, synonyms
1699 @smallexample @c ada
1700 pragma Convention_Identifier (
1701 [Name =>] IDENTIFIER,
1702 [Convention =>] convention_IDENTIFIER);
1706 This pragma provides a mechanism for supplying synonyms for existing
1707 convention identifiers. The @code{Name} identifier can subsequently
1708 be used as a synonym for the given convention in other pragmas (including
1709 for example pragma @code{Import} or another @code{Convention_Identifier}
1710 pragma). As an example of the use of this, suppose you had legacy code
1711 which used Fortran77 as the identifier for Fortran. Then the pragma:
1713 @smallexample @c ada
1714 pragma Convention_Identifier (Fortran77, Fortran);
1718 would allow the use of the convention identifier @code{Fortran77} in
1719 subsequent code, avoiding the need to modify the sources. As another
1720 example, you could use this to parameterize convention requirements
1721 according to systems. Suppose you needed to use @code{Stdcall} on
1722 windows systems, and @code{C} on some other system, then you could
1723 define a convention identifier @code{Library} and use a single
1724 @code{Convention_Identifier} pragma to specify which convention
1725 would be used system-wide.
1727 @node Pragma CPP_Class
1728 @unnumberedsec Pragma CPP_Class
1730 @cindex Interfacing with C++
1734 @smallexample @c ada
1735 pragma CPP_Class ([Entity =>] LOCAL_NAME);
1739 The argument denotes an entity in the current declarative region that is
1740 declared as a record type. It indicates that the type corresponds to an
1741 externally declared C++ class type, and is to be laid out the same way
1742 that C++ would lay out the type. If the C++ class has virtual primitives
1743 then the record must be declared as a tagged record type.
1745 Types for which @code{CPP_Class} is specified do not have assignment or
1746 equality operators defined (such operations can be imported or declared
1747 as subprograms as required). Initialization is allowed only by constructor
1748 functions (see pragma @code{CPP_Constructor}). Such types are implicitly
1749 limited if not explicitly declared as limited or derived from a limited
1750 type, and an error is issued in that case.
1752 Pragma @code{CPP_Class} is intended primarily for automatic generation
1753 using an automatic binding generator tool.
1754 See @ref{Interfacing to C++} for related information.
1756 Note: Pragma @code{CPP_Class} is currently obsolete. It is supported
1757 for backward compatibility but its functionality is available
1758 using pragma @code{Import} with @code{Convention} = @code{CPP}.
1760 @node Pragma CPP_Constructor
1761 @unnumberedsec Pragma CPP_Constructor
1762 @cindex Interfacing with C++
1763 @findex CPP_Constructor
1767 @smallexample @c ada
1768 pragma CPP_Constructor ([Entity =>] LOCAL_NAME
1769 [, [External_Name =>] static_string_EXPRESSION ]
1770 [, [Link_Name =>] static_string_EXPRESSION ]);
1774 This pragma identifies an imported function (imported in the usual way
1775 with pragma @code{Import}) as corresponding to a C++ constructor. If
1776 @code{External_Name} and @code{Link_Name} are not specified then the
1777 @code{Entity} argument is a name that must have been previously mentioned
1778 in a pragma @code{Import} with @code{Convention} = @code{CPP}. Such name
1779 must be of one of the following forms:
1783 @code{function @var{Fname} return @var{T}}
1787 @code{function @var{Fname} return @var{T}'Class}
1790 @code{function @var{Fname} (@dots{}) return @var{T}}
1794 @code{function @var{Fname} (@dots{}) return @var{T}'Class}
1798 where @var{T} is a limited record type imported from C++ with pragma
1799 @code{Import} and @code{Convention} = @code{CPP}.
1801 The first two forms import the default constructor, used when an object
1802 of type @var{T} is created on the Ada side with no explicit constructor.
1803 The latter two forms cover all the non-default constructors of the type.
1804 See the GNAT users guide for details.
1806 If no constructors are imported, it is impossible to create any objects
1807 on the Ada side and the type is implicitly declared abstract.
1809 Pragma @code{CPP_Constructor} is intended primarily for automatic generation
1810 using an automatic binding generator tool.
1811 See @ref{Interfacing to C++} for more related information.
1813 Note: The use of functions returning class-wide types for constructors is
1814 currently obsolete. They are supported for backward compatibility. The
1815 use of functions returning the type T leave the Ada sources more clear
1816 because the imported C++ constructors always return an object of type T;
1817 that is, they never return an object whose type is a descendant of type T.
1819 @node Pragma CPP_Virtual
1820 @unnumberedsec Pragma CPP_Virtual
1821 @cindex Interfacing to C++
1824 This pragma is now obsolete has has no effect because GNAT generates
1825 the same object layout than the G++ compiler.
1827 See @ref{Interfacing to C++} for related information.
1829 @node Pragma CPP_Vtable
1830 @unnumberedsec Pragma CPP_Vtable
1831 @cindex Interfacing with C++
1834 This pragma is now obsolete has has no effect because GNAT generates
1835 the same object layout than the G++ compiler.
1837 See @ref{Interfacing to C++} for related information.
1840 @unnumberedsec Pragma Debug
1845 @smallexample @c ada
1846 pragma Debug ([CONDITION, ]PROCEDURE_CALL_WITHOUT_SEMICOLON);
1848 PROCEDURE_CALL_WITHOUT_SEMICOLON ::=
1850 | PROCEDURE_PREFIX ACTUAL_PARAMETER_PART
1854 The procedure call argument has the syntactic form of an expression, meeting
1855 the syntactic requirements for pragmas.
1857 If debug pragmas are not enabled or if the condition is present and evaluates
1858 to False, this pragma has no effect. If debug pragmas are enabled, the
1859 semantics of the pragma is exactly equivalent to the procedure call statement
1860 corresponding to the argument with a terminating semicolon. Pragmas are
1861 permitted in sequences of declarations, so you can use pragma @code{Debug} to
1862 intersperse calls to debug procedures in the middle of declarations. Debug
1863 pragmas can be enabled either by use of the command line switch @option{-gnata}
1864 or by use of the configuration pragma @code{Debug_Policy}.
1866 @node Pragma Debug_Policy
1867 @unnumberedsec Pragma Debug_Policy
1868 @findex Debug_Policy
1872 @smallexample @c ada
1873 pragma Debug_Policy (CHECK | DISABLE | IGNORE);
1877 If the argument is @code{CHECK}, then pragma @code{DEBUG} is enabled.
1878 If the argument is @code{IGNORE}, then pragma @code{DEBUG} is ignored.
1879 This pragma overrides the effect of the @option{-gnata} switch on the
1882 The implementation defined policy @code{DISABLE} is like
1883 @code{IGNORE} except that it completely disables semantic
1884 checking of the argument to @code{pragma Debug}. This may
1885 be useful when the pragma argument references subprograms
1886 in a with'ed package which is replaced by a dummy package
1887 for the final build.
1889 @node Pragma Detect_Blocking
1890 @unnumberedsec Pragma Detect_Blocking
1891 @findex Detect_Blocking
1895 @smallexample @c ada
1896 pragma Detect_Blocking;
1900 This is a configuration pragma that forces the detection of potentially
1901 blocking operations within a protected operation, and to raise Program_Error
1904 @node Pragma Elaboration_Checks
1905 @unnumberedsec Pragma Elaboration_Checks
1906 @cindex Elaboration control
1907 @findex Elaboration_Checks
1911 @smallexample @c ada
1912 pragma Elaboration_Checks (Dynamic | Static);
1916 This is a configuration pragma that provides control over the
1917 elaboration model used by the compilation affected by the
1918 pragma. If the parameter is @code{Dynamic},
1919 then the dynamic elaboration
1920 model described in the Ada Reference Manual is used, as though
1921 the @option{-gnatE} switch had been specified on the command
1922 line. If the parameter is @code{Static}, then the default GNAT static
1923 model is used. This configuration pragma overrides the setting
1924 of the command line. For full details on the elaboration models
1925 used by the GNAT compiler, see @ref{Elaboration Order Handling in GNAT,,,
1926 gnat_ugn, @value{EDITION} User's Guide}.
1928 @node Pragma Eliminate
1929 @unnumberedsec Pragma Eliminate
1930 @cindex Elimination of unused subprograms
1935 @smallexample @c ada
1936 pragma Eliminate ([Entity =>] DEFINING_DESIGNATOR,
1937 [Source_Location =>] STRING_LITERAL);
1941 The string literal given for the source location is a string which
1942 specifies the line number of the occurrence of the entity, using
1943 the syntax for SOURCE_TRACE given below:
1945 @smallexample @c ada
1946 SOURCE_TRACE ::= SOURCE_REFERENCE [LBRACKET SOURCE_TRACE RBRACKET]
1951 SOURCE_REFERENCE ::= FILE_NAME : LINE_NUMBER
1953 LINE_NUMBER ::= DIGIT @{DIGIT@}
1957 Spaces around the colon in a @code{Source_Reference} are optional.
1959 The @code{DEFINING_DESIGNATOR} matches the defining designator used in an
1960 explicit subprogram declaration, where the @code{entity} name in this
1961 designator appears on the source line specified by the source location.
1963 The source trace that is given as the @code{Source_Location} shall obey the
1964 following rules. The @code{FILE_NAME} is the short name (with no directory
1965 information) of an Ada source file, given using exactly the required syntax
1966 for the underlying file system (e.g. case is important if the underlying
1967 operating system is case sensitive). @code{LINE_NUMBER} gives the line
1968 number of the occurrence of the @code{entity}
1969 as a decimal literal without an exponent or point. If an @code{entity} is not
1970 declared in a generic instantiation (this includes generic subprogram
1971 instances), the source trace includes only one source reference. If an entity
1972 is declared inside a generic instantiation, its source trace (when parsing
1973 from left to right) starts with the source location of the declaration of the
1974 entity in the generic unit and ends with the source location of the
1975 instantiation (it is given in square brackets). This approach is recursively
1976 used in case of nested instantiations: the rightmost (nested most deeply in
1977 square brackets) element of the source trace is the location of the outermost
1978 instantiation, the next to left element is the location of the next (first
1979 nested) instantiation in the code of the corresponding generic unit, and so
1980 on, and the leftmost element (that is out of any square brackets) is the
1981 location of the declaration of the entity to eliminate in a generic unit.
1983 Note that the @code{Source_Location} argument specifies which of a set of
1984 similarly named entities is being eliminated, dealing both with overloading,
1985 and also appearence of the same entity name in different scopes.
1987 This pragma indicates that the given entity is not used in the program to be
1988 compiled and built. The effect of the pragma is to allow the compiler to
1989 eliminate the code or data associated with the named entity. Any reference to
1990 an eliminated entity causes a compile-time or link-time error.
1992 The intention of pragma @code{Eliminate} is to allow a program to be compiled
1993 in a system-independent manner, with unused entities eliminated, without
1994 needing to modify the source text. Normally the required set of
1995 @code{Eliminate} pragmas is constructed automatically using the gnatelim tool.
1997 Any source file change that removes, splits, or
1998 adds lines may make the set of Eliminate pragmas invalid because their
1999 @code{Source_Location} argument values may get out of date.
2001 Pragma @code{Eliminate} may be used where the referenced entity is a dispatching
2002 operation. In this case all the subprograms to which the given operation can
2003 dispatch are considered to be unused (are never called as a result of a direct
2004 or a dispatching call).
2006 @node Pragma Export_Exception
2007 @unnumberedsec Pragma Export_Exception
2009 @findex Export_Exception
2013 @smallexample @c ada
2014 pragma Export_Exception (
2015 [Internal =>] LOCAL_NAME
2016 [, [External =>] EXTERNAL_SYMBOL]
2017 [, [Form =>] Ada | VMS]
2018 [, [Code =>] static_integer_EXPRESSION]);
2022 | static_string_EXPRESSION
2026 This pragma is implemented only in the OpenVMS implementation of GNAT@. It
2027 causes the specified exception to be propagated outside of the Ada program,
2028 so that it can be handled by programs written in other OpenVMS languages.
2029 This pragma establishes an external name for an Ada exception and makes the
2030 name available to the OpenVMS Linker as a global symbol. For further details
2031 on this pragma, see the
2032 DEC Ada Language Reference Manual, section 13.9a3.2.
2034 @node Pragma Export_Function
2035 @unnumberedsec Pragma Export_Function
2036 @cindex Argument passing mechanisms
2037 @findex Export_Function
2042 @smallexample @c ada
2043 pragma Export_Function (
2044 [Internal =>] LOCAL_NAME
2045 [, [External =>] EXTERNAL_SYMBOL]
2046 [, [Parameter_Types =>] PARAMETER_TYPES]
2047 [, [Result_Type =>] result_SUBTYPE_MARK]
2048 [, [Mechanism =>] MECHANISM]
2049 [, [Result_Mechanism =>] MECHANISM_NAME]);
2053 | static_string_EXPRESSION
2058 | TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@}
2062 | subtype_Name ' Access
2066 | (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@})
2068 MECHANISM_ASSOCIATION ::=
2069 [formal_parameter_NAME =>] MECHANISM_NAME
2074 | Descriptor [([Class =>] CLASS_NAME)]
2075 | Short_Descriptor [([Class =>] CLASS_NAME)]
2077 CLASS_NAME ::= ubs | ubsb | uba | s | sb | a
2081 Use this pragma to make a function externally callable and optionally
2082 provide information on mechanisms to be used for passing parameter and
2083 result values. We recommend, for the purposes of improving portability,
2084 this pragma always be used in conjunction with a separate pragma
2085 @code{Export}, which must precede the pragma @code{Export_Function}.
2086 GNAT does not require a separate pragma @code{Export}, but if none is
2087 present, @code{Convention Ada} is assumed, which is usually
2088 not what is wanted, so it is usually appropriate to use this
2089 pragma in conjunction with a @code{Export} or @code{Convention}
2090 pragma that specifies the desired foreign convention.
2091 Pragma @code{Export_Function}
2092 (and @code{Export}, if present) must appear in the same declarative
2093 region as the function to which they apply.
2095 @var{internal_name} must uniquely designate the function to which the
2096 pragma applies. If more than one function name exists of this name in
2097 the declarative part you must use the @code{Parameter_Types} and
2098 @code{Result_Type} parameters is mandatory to achieve the required
2099 unique designation. @var{subtype_mark}s in these parameters must
2100 exactly match the subtypes in the corresponding function specification,
2101 using positional notation to match parameters with subtype marks.
2102 The form with an @code{'Access} attribute can be used to match an
2103 anonymous access parameter.
2106 @cindex Passing by descriptor
2107 Passing by descriptor is supported only on the OpenVMS ports of GNAT@.
2108 The default behavior for Export_Function is to accept either 64bit or
2109 32bit descriptors unless short_descriptor is specified, then only 32bit
2110 descriptors are accepted.
2112 @cindex Suppressing external name
2113 Special treatment is given if the EXTERNAL is an explicit null
2114 string or a static string expressions that evaluates to the null
2115 string. In this case, no external name is generated. This form
2116 still allows the specification of parameter mechanisms.
2118 @node Pragma Export_Object
2119 @unnumberedsec Pragma Export_Object
2120 @findex Export_Object
2124 @smallexample @c ada
2125 pragma Export_Object
2126 [Internal =>] LOCAL_NAME
2127 [, [External =>] EXTERNAL_SYMBOL]
2128 [, [Size =>] EXTERNAL_SYMBOL]
2132 | static_string_EXPRESSION
2136 This pragma designates an object as exported, and apart from the
2137 extended rules for external symbols, is identical in effect to the use of
2138 the normal @code{Export} pragma applied to an object. You may use a
2139 separate Export pragma (and you probably should from the point of view
2140 of portability), but it is not required. @var{Size} is syntax checked,
2141 but otherwise ignored by GNAT@.
2143 @node Pragma Export_Procedure
2144 @unnumberedsec Pragma Export_Procedure
2145 @findex Export_Procedure
2149 @smallexample @c ada
2150 pragma Export_Procedure (
2151 [Internal =>] LOCAL_NAME
2152 [, [External =>] EXTERNAL_SYMBOL]
2153 [, [Parameter_Types =>] PARAMETER_TYPES]
2154 [, [Mechanism =>] MECHANISM]);
2158 | static_string_EXPRESSION
2163 | TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@}
2167 | subtype_Name ' Access
2171 | (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@})
2173 MECHANISM_ASSOCIATION ::=
2174 [formal_parameter_NAME =>] MECHANISM_NAME
2179 | Descriptor [([Class =>] CLASS_NAME)]
2180 | Short_Descriptor [([Class =>] CLASS_NAME)]
2182 CLASS_NAME ::= ubs | ubsb | uba | s | sb | a
2186 This pragma is identical to @code{Export_Function} except that it
2187 applies to a procedure rather than a function and the parameters
2188 @code{Result_Type} and @code{Result_Mechanism} are not permitted.
2189 GNAT does not require a separate pragma @code{Export}, but if none is
2190 present, @code{Convention Ada} is assumed, which is usually
2191 not what is wanted, so it is usually appropriate to use this
2192 pragma in conjunction with a @code{Export} or @code{Convention}
2193 pragma that specifies the desired foreign convention.
2196 @cindex Passing by descriptor
2197 Passing by descriptor is supported only on the OpenVMS ports of GNAT@.
2198 The default behavior for Export_Procedure is to accept either 64bit or
2199 32bit descriptors unless short_descriptor is specified, then only 32bit
2200 descriptors are accepted.
2202 @cindex Suppressing external name
2203 Special treatment is given if the EXTERNAL is an explicit null
2204 string or a static string expressions that evaluates to the null
2205 string. In this case, no external name is generated. This form
2206 still allows the specification of parameter mechanisms.
2208 @node Pragma Export_Value
2209 @unnumberedsec Pragma Export_Value
2210 @findex Export_Value
2214 @smallexample @c ada
2215 pragma Export_Value (
2216 [Value =>] static_integer_EXPRESSION,
2217 [Link_Name =>] static_string_EXPRESSION);
2221 This pragma serves to export a static integer value for external use.
2222 The first argument specifies the value to be exported. The Link_Name
2223 argument specifies the symbolic name to be associated with the integer
2224 value. This pragma is useful for defining a named static value in Ada
2225 that can be referenced in assembly language units to be linked with
2226 the application. This pragma is currently supported only for the
2227 AAMP target and is ignored for other targets.
2229 @node Pragma Export_Valued_Procedure
2230 @unnumberedsec Pragma Export_Valued_Procedure
2231 @findex Export_Valued_Procedure
2235 @smallexample @c ada
2236 pragma Export_Valued_Procedure (
2237 [Internal =>] LOCAL_NAME
2238 [, [External =>] EXTERNAL_SYMBOL]
2239 [, [Parameter_Types =>] PARAMETER_TYPES]
2240 [, [Mechanism =>] MECHANISM]);
2244 | static_string_EXPRESSION
2249 | TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@}
2253 | subtype_Name ' Access
2257 | (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@})
2259 MECHANISM_ASSOCIATION ::=
2260 [formal_parameter_NAME =>] MECHANISM_NAME
2265 | Descriptor [([Class =>] CLASS_NAME)]
2266 | Short_Descriptor [([Class =>] CLASS_NAME)]
2268 CLASS_NAME ::= ubs | ubsb | uba | s | sb | a
2272 This pragma is identical to @code{Export_Procedure} except that the
2273 first parameter of @var{LOCAL_NAME}, which must be present, must be of
2274 mode @code{OUT}, and externally the subprogram is treated as a function
2275 with this parameter as the result of the function. GNAT provides for
2276 this capability to allow the use of @code{OUT} and @code{IN OUT}
2277 parameters in interfacing to external functions (which are not permitted
2279 GNAT does not require a separate pragma @code{Export}, but if none is
2280 present, @code{Convention Ada} is assumed, which is almost certainly
2281 not what is wanted since the whole point of this pragma is to interface
2282 with foreign language functions, so it is usually appropriate to use this
2283 pragma in conjunction with a @code{Export} or @code{Convention}
2284 pragma that specifies the desired foreign convention.
2287 @cindex Passing by descriptor
2288 Passing by descriptor is supported only on the OpenVMS ports of GNAT@.
2289 The default behavior for Export_Valued_Procedure is to accept either 64bit or
2290 32bit descriptors unless short_descriptor is specified, then only 32bit
2291 descriptors are accepted.
2293 @cindex Suppressing external name
2294 Special treatment is given if the EXTERNAL is an explicit null
2295 string or a static string expressions that evaluates to the null
2296 string. In this case, no external name is generated. This form
2297 still allows the specification of parameter mechanisms.
2299 @node Pragma Extend_System
2300 @unnumberedsec Pragma Extend_System
2301 @cindex @code{system}, extending
2303 @findex Extend_System
2307 @smallexample @c ada
2308 pragma Extend_System ([Name =>] IDENTIFIER);
2312 This pragma is used to provide backwards compatibility with other
2313 implementations that extend the facilities of package @code{System}. In
2314 GNAT, @code{System} contains only the definitions that are present in
2315 the Ada RM@. However, other implementations, notably the DEC Ada 83
2316 implementation, provide many extensions to package @code{System}.
2318 For each such implementation accommodated by this pragma, GNAT provides a
2319 package @code{Aux_@var{xxx}}, e.g.@: @code{Aux_DEC} for the DEC Ada 83
2320 implementation, which provides the required additional definitions. You
2321 can use this package in two ways. You can @code{with} it in the normal
2322 way and access entities either by selection or using a @code{use}
2323 clause. In this case no special processing is required.
2325 However, if existing code contains references such as
2326 @code{System.@var{xxx}} where @var{xxx} is an entity in the extended
2327 definitions provided in package @code{System}, you may use this pragma
2328 to extend visibility in @code{System} in a non-standard way that
2329 provides greater compatibility with the existing code. Pragma
2330 @code{Extend_System} is a configuration pragma whose single argument is
2331 the name of the package containing the extended definition
2332 (e.g.@: @code{Aux_DEC} for the DEC Ada case). A unit compiled under
2333 control of this pragma will be processed using special visibility
2334 processing that looks in package @code{System.Aux_@var{xxx}} where
2335 @code{Aux_@var{xxx}} is the pragma argument for any entity referenced in
2336 package @code{System}, but not found in package @code{System}.
2338 You can use this pragma either to access a predefined @code{System}
2339 extension supplied with the compiler, for example @code{Aux_DEC} or
2340 you can construct your own extension unit following the above
2341 definition. Note that such a package is a child of @code{System}
2342 and thus is considered part of the implementation. To compile
2343 it you will have to use the appropriate switch for compiling
2345 @xref{Top, @value{EDITION} User's Guide, About This Guide, gnat_ugn, @value{EDITION} User's Guide},
2348 @node Pragma Extensions_Allowed
2349 @unnumberedsec Pragma Extensions_Allowed
2350 @cindex Ada Extensions
2351 @cindex GNAT Extensions
2352 @findex Extensions_Allowed
2356 @smallexample @c ada
2357 pragma Extensions_Allowed (On | Off);
2361 This configuration pragma enables or disables the implementation
2362 extension mode (the use of Off as a parameter cancels the effect
2363 of the @option{-gnatX} command switch).
2365 In extension mode, the latest version of the Ada language is
2366 implemented (currently Ada 2012), and in addition a small number
2367 of GNAT specific extensions are recognized as follows:
2370 @item Constrained attribute for generic objects
2371 The @code{Constrained} attribute is permitted for objects of
2372 generic types. The result indicates if the corresponding actual
2377 @node Pragma External
2378 @unnumberedsec Pragma External
2383 @smallexample @c ada
2385 [ Convention =>] convention_IDENTIFIER,
2386 [ Entity =>] LOCAL_NAME
2387 [, [External_Name =>] static_string_EXPRESSION ]
2388 [, [Link_Name =>] static_string_EXPRESSION ]);
2392 This pragma is identical in syntax and semantics to pragma
2393 @code{Export} as defined in the Ada Reference Manual. It is
2394 provided for compatibility with some Ada 83 compilers that
2395 used this pragma for exactly the same purposes as pragma
2396 @code{Export} before the latter was standardized.
2398 @node Pragma External_Name_Casing
2399 @unnumberedsec Pragma External_Name_Casing
2400 @cindex Dec Ada 83 casing compatibility
2401 @cindex External Names, casing
2402 @cindex Casing of External names
2403 @findex External_Name_Casing
2407 @smallexample @c ada
2408 pragma External_Name_Casing (
2409 Uppercase | Lowercase
2410 [, Uppercase | Lowercase | As_Is]);
2414 This pragma provides control over the casing of external names associated
2415 with Import and Export pragmas. There are two cases to consider:
2418 @item Implicit external names
2419 Implicit external names are derived from identifiers. The most common case
2420 arises when a standard Ada Import or Export pragma is used with only two
2423 @smallexample @c ada
2424 pragma Import (C, C_Routine);
2428 Since Ada is a case-insensitive language, the spelling of the identifier in
2429 the Ada source program does not provide any information on the desired
2430 casing of the external name, and so a convention is needed. In GNAT the
2431 default treatment is that such names are converted to all lower case
2432 letters. This corresponds to the normal C style in many environments.
2433 The first argument of pragma @code{External_Name_Casing} can be used to
2434 control this treatment. If @code{Uppercase} is specified, then the name
2435 will be forced to all uppercase letters. If @code{Lowercase} is specified,
2436 then the normal default of all lower case letters will be used.
2438 This same implicit treatment is also used in the case of extended DEC Ada 83
2439 compatible Import and Export pragmas where an external name is explicitly
2440 specified using an identifier rather than a string.
2442 @item Explicit external names
2443 Explicit external names are given as string literals. The most common case
2444 arises when a standard Ada Import or Export pragma is used with three
2447 @smallexample @c ada
2448 pragma Import (C, C_Routine, "C_routine");
2452 In this case, the string literal normally provides the exact casing required
2453 for the external name. The second argument of pragma
2454 @code{External_Name_Casing} may be used to modify this behavior.
2455 If @code{Uppercase} is specified, then the name
2456 will be forced to all uppercase letters. If @code{Lowercase} is specified,
2457 then the name will be forced to all lowercase letters. A specification of
2458 @code{As_Is} provides the normal default behavior in which the casing is
2459 taken from the string provided.
2463 This pragma may appear anywhere that a pragma is valid. In particular, it
2464 can be used as a configuration pragma in the @file{gnat.adc} file, in which
2465 case it applies to all subsequent compilations, or it can be used as a program
2466 unit pragma, in which case it only applies to the current unit, or it can
2467 be used more locally to control individual Import/Export pragmas.
2469 It is primarily intended for use with OpenVMS systems, where many
2470 compilers convert all symbols to upper case by default. For interfacing to
2471 such compilers (e.g.@: the DEC C compiler), it may be convenient to use
2474 @smallexample @c ada
2475 pragma External_Name_Casing (Uppercase, Uppercase);
2479 to enforce the upper casing of all external symbols.
2481 @node Pragma Fast_Math
2482 @unnumberedsec Pragma Fast_Math
2487 @smallexample @c ada
2492 This is a configuration pragma which activates a mode in which speed is
2493 considered more important for floating-point operations than absolutely
2494 accurate adherence to the requirements of the standard. Currently the
2495 following operations are affected:
2498 @item Complex Multiplication
2499 The normal simple formula for complex multiplication can result in intermediate
2500 overflows for numbers near the end of the range. The Ada standard requires that
2501 this situation be detected and corrected by scaling, but in Fast_Math mode such
2502 cases will simply result in overflow. Note that to take advantage of this you
2503 must instantiate your own version of @code{Ada.Numerics.Generic_Complex_Types}
2504 under control of the pragma, rather than use the preinstantiated versions.
2507 @node Pragma Favor_Top_Level
2508 @unnumberedsec Pragma Favor_Top_Level
2509 @findex Favor_Top_Level
2513 @smallexample @c ada
2514 pragma Favor_Top_Level (type_NAME);
2518 The named type must be an access-to-subprogram type. This pragma is an
2519 efficiency hint to the compiler, regarding the use of 'Access or
2520 'Unrestricted_Access on nested (non-library-level) subprograms. The
2521 pragma means that nested subprograms are not used with this type, or
2522 are rare, so that the generated code should be efficient in the
2523 top-level case. When this pragma is used, dynamically generated
2524 trampolines may be used on some targets for nested subprograms.
2525 See also the No_Implicit_Dynamic_Code restriction.
2527 @node Pragma Finalize_Storage_Only
2528 @unnumberedsec Pragma Finalize_Storage_Only
2529 @findex Finalize_Storage_Only
2533 @smallexample @c ada
2534 pragma Finalize_Storage_Only (first_subtype_LOCAL_NAME);
2538 This pragma allows the compiler not to emit a Finalize call for objects
2539 defined at the library level. This is mostly useful for types where
2540 finalization is only used to deal with storage reclamation since in most
2541 environments it is not necessary to reclaim memory just before terminating
2542 execution, hence the name.
2544 @node Pragma Float_Representation
2545 @unnumberedsec Pragma Float_Representation
2547 @findex Float_Representation
2551 @smallexample @c ada
2552 pragma Float_Representation (FLOAT_REP[, float_type_LOCAL_NAME]);
2554 FLOAT_REP ::= VAX_Float | IEEE_Float
2558 In the one argument form, this pragma is a configuration pragma which
2559 allows control over the internal representation chosen for the predefined
2560 floating point types declared in the packages @code{Standard} and
2561 @code{System}. On all systems other than OpenVMS, the argument must
2562 be @code{IEEE_Float} and the pragma has no effect. On OpenVMS, the
2563 argument may be @code{VAX_Float} to specify the use of the VAX float
2564 format for the floating-point types in Standard. This requires that
2565 the standard runtime libraries be recompiled.
2567 The two argument form specifies the representation to be used for
2568 the specified floating-point type. On all systems other than OpenVMS,
2570 be @code{IEEE_Float} and the pragma has no effect. On OpenVMS, the
2571 argument may be @code{VAX_Float} to specify the use of the VAX float
2576 For digits values up to 6, F float format will be used.
2578 For digits values from 7 to 9, D float format will be used.
2580 For digits values from 10 to 15, G float format will be used.
2582 Digits values above 15 are not allowed.
2586 @unnumberedsec Pragma Ident
2591 @smallexample @c ada
2592 pragma Ident (static_string_EXPRESSION);
2596 This pragma provides a string identification in the generated object file,
2597 if the system supports the concept of this kind of identification string.
2598 This pragma is allowed only in the outermost declarative part or
2599 declarative items of a compilation unit. If more than one @code{Ident}
2600 pragma is given, only the last one processed is effective.
2602 On OpenVMS systems, the effect of the pragma is identical to the effect of
2603 the DEC Ada 83 pragma of the same name. Note that in DEC Ada 83, the
2604 maximum allowed length is 31 characters, so if it is important to
2605 maintain compatibility with this compiler, you should obey this length
2608 @node Pragma Implemented
2609 @unnumberedsec Pragma Implemented
2614 @smallexample @c ada
2615 pragma Implemented (procedure_LOCAL_NAME, implementation_kind);
2617 implementation_kind ::= By_Entry | By_Protected_Procedure | By_Any
2621 This is an Ada 2012 representation pragma which applies to protected, task
2622 and synchronized interface primitives. The use of pragma Implemented provides
2623 a way to impose a static requirement on the overriding operation by adhering
2624 to one of the three implementation kids: entry, protected procedure or any of
2627 @smallexample @c ada
2628 type Synch_Iface is synchronized interface;
2629 procedure Prim_Op (Obj : in out Iface) is abstract;
2630 pragma Implemented (Prim_Op, By_Protected_Procedure);
2632 protected type Prot_1 is new Synch_Iface with
2633 procedure Prim_Op; -- Legal
2636 protected type Prot_2 is new Synch_Iface with
2637 entry Prim_Op; -- Illegal
2640 task type Task_Typ is new Synch_Iface with
2641 entry Prim_Op; -- Illegal
2646 When applied to the procedure_or_entry_NAME of a requeue statement, pragma
2647 Implemented determines the runtime behavior of the requeue. Implementation kind
2648 By_Entry guarantees that the action of requeueing will proceed from an entry to
2649 another entry. Implementation kind By_Protected_Procedure transforms the
2650 requeue into a dispatching call, thus eliminating the chance of blocking. Kind
2651 By_Any shares the behavior of By_Entry and By_Protected_Procedure depending on
2652 the target's overriding subprogram kind.
2654 @node Pragma Implicit_Packing
2655 @unnumberedsec Pragma Implicit_Packing
2656 @findex Implicit_Packing
2660 @smallexample @c ada
2661 pragma Implicit_Packing;
2665 This is a configuration pragma that requests implicit packing for packed
2666 arrays for which a size clause is given but no explicit pragma Pack or
2667 specification of Component_Size is present. It also applies to records
2668 where no record representation clause is present. Consider this example:
2670 @smallexample @c ada
2671 type R is array (0 .. 7) of Boolean;
2676 In accordance with the recommendation in the RM (RM 13.3(53)), a Size clause
2677 does not change the layout of a composite object. So the Size clause in the
2678 above example is normally rejected, since the default layout of the array uses
2679 8-bit components, and thus the array requires a minimum of 64 bits.
2681 If this declaration is compiled in a region of code covered by an occurrence
2682 of the configuration pragma Implicit_Packing, then the Size clause in this
2683 and similar examples will cause implicit packing and thus be accepted. For
2684 this implicit packing to occur, the type in question must be an array of small
2685 components whose size is known at compile time, and the Size clause must
2686 specify the exact size that corresponds to the length of the array multiplied
2687 by the size in bits of the component type.
2688 @cindex Array packing
2690 Similarly, the following example shows the use in the record case
2692 @smallexample @c ada
2694 a, b, c, d, e, f, g, h : boolean;
2701 Without a pragma Pack, each Boolean field requires 8 bits, so the
2702 minimum size is 72 bits, but with a pragma Pack, 16 bits would be
2703 sufficient. The use of pragma Implicit_Packing allows this record
2704 declaration to compile without an explicit pragma Pack.
2705 @node Pragma Import_Exception
2706 @unnumberedsec Pragma Import_Exception
2708 @findex Import_Exception
2712 @smallexample @c ada
2713 pragma Import_Exception (
2714 [Internal =>] LOCAL_NAME
2715 [, [External =>] EXTERNAL_SYMBOL]
2716 [, [Form =>] Ada | VMS]
2717 [, [Code =>] static_integer_EXPRESSION]);
2721 | static_string_EXPRESSION
2725 This pragma is implemented only in the OpenVMS implementation of GNAT@.
2726 It allows OpenVMS conditions (for example, from OpenVMS system services or
2727 other OpenVMS languages) to be propagated to Ada programs as Ada exceptions.
2728 The pragma specifies that the exception associated with an exception
2729 declaration in an Ada program be defined externally (in non-Ada code).
2730 For further details on this pragma, see the
2731 DEC Ada Language Reference Manual, section 13.9a.3.1.
2733 @node Pragma Import_Function
2734 @unnumberedsec Pragma Import_Function
2735 @findex Import_Function
2739 @smallexample @c ada
2740 pragma Import_Function (
2741 [Internal =>] LOCAL_NAME,
2742 [, [External =>] EXTERNAL_SYMBOL]
2743 [, [Parameter_Types =>] PARAMETER_TYPES]
2744 [, [Result_Type =>] SUBTYPE_MARK]
2745 [, [Mechanism =>] MECHANISM]
2746 [, [Result_Mechanism =>] MECHANISM_NAME]
2747 [, [First_Optional_Parameter =>] IDENTIFIER]);
2751 | static_string_EXPRESSION
2755 | TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@}
2759 | subtype_Name ' Access
2763 | (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@})
2765 MECHANISM_ASSOCIATION ::=
2766 [formal_parameter_NAME =>] MECHANISM_NAME
2771 | Descriptor [([Class =>] CLASS_NAME)]
2772 | Short_Descriptor [([Class =>] CLASS_NAME)]
2774 CLASS_NAME ::= ubs | ubsb | uba | s | sb | a | nca
2778 This pragma is used in conjunction with a pragma @code{Import} to
2779 specify additional information for an imported function. The pragma
2780 @code{Import} (or equivalent pragma @code{Interface}) must precede the
2781 @code{Import_Function} pragma and both must appear in the same
2782 declarative part as the function specification.
2784 The @var{Internal} argument must uniquely designate
2785 the function to which the
2786 pragma applies. If more than one function name exists of this name in
2787 the declarative part you must use the @code{Parameter_Types} and
2788 @var{Result_Type} parameters to achieve the required unique
2789 designation. Subtype marks in these parameters must exactly match the
2790 subtypes in the corresponding function specification, using positional
2791 notation to match parameters with subtype marks.
2792 The form with an @code{'Access} attribute can be used to match an
2793 anonymous access parameter.
2795 You may optionally use the @var{Mechanism} and @var{Result_Mechanism}
2796 parameters to specify passing mechanisms for the
2797 parameters and result. If you specify a single mechanism name, it
2798 applies to all parameters. Otherwise you may specify a mechanism on a
2799 parameter by parameter basis using either positional or named
2800 notation. If the mechanism is not specified, the default mechanism
2804 @cindex Passing by descriptor
2805 Passing by descriptor is supported only on the OpenVMS ports of GNAT@.
2806 The default behavior for Import_Function is to pass a 64bit descriptor
2807 unless short_descriptor is specified, then a 32bit descriptor is passed.
2809 @code{First_Optional_Parameter} applies only to OpenVMS ports of GNAT@.
2810 It specifies that the designated parameter and all following parameters
2811 are optional, meaning that they are not passed at the generated code
2812 level (this is distinct from the notion of optional parameters in Ada
2813 where the parameters are passed anyway with the designated optional
2814 parameters). All optional parameters must be of mode @code{IN} and have
2815 default parameter values that are either known at compile time
2816 expressions, or uses of the @code{'Null_Parameter} attribute.
2818 @node Pragma Import_Object
2819 @unnumberedsec Pragma Import_Object
2820 @findex Import_Object
2824 @smallexample @c ada
2825 pragma Import_Object
2826 [Internal =>] LOCAL_NAME
2827 [, [External =>] EXTERNAL_SYMBOL]
2828 [, [Size =>] EXTERNAL_SYMBOL]);
2832 | static_string_EXPRESSION
2836 This pragma designates an object as imported, and apart from the
2837 extended rules for external symbols, is identical in effect to the use of
2838 the normal @code{Import} pragma applied to an object. Unlike the
2839 subprogram case, you need not use a separate @code{Import} pragma,
2840 although you may do so (and probably should do so from a portability
2841 point of view). @var{size} is syntax checked, but otherwise ignored by
2844 @node Pragma Import_Procedure
2845 @unnumberedsec Pragma Import_Procedure
2846 @findex Import_Procedure
2850 @smallexample @c ada
2851 pragma Import_Procedure (
2852 [Internal =>] LOCAL_NAME
2853 [, [External =>] EXTERNAL_SYMBOL]
2854 [, [Parameter_Types =>] PARAMETER_TYPES]
2855 [, [Mechanism =>] MECHANISM]
2856 [, [First_Optional_Parameter =>] IDENTIFIER]);
2860 | static_string_EXPRESSION
2864 | TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@}
2868 | subtype_Name ' Access
2872 | (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@})
2874 MECHANISM_ASSOCIATION ::=
2875 [formal_parameter_NAME =>] MECHANISM_NAME
2880 | Descriptor [([Class =>] CLASS_NAME)]
2881 | Short_Descriptor [([Class =>] CLASS_NAME)]
2883 CLASS_NAME ::= ubs | ubsb | uba | s | sb | a | nca
2887 This pragma is identical to @code{Import_Function} except that it
2888 applies to a procedure rather than a function and the parameters
2889 @code{Result_Type} and @code{Result_Mechanism} are not permitted.
2891 @node Pragma Import_Valued_Procedure
2892 @unnumberedsec Pragma Import_Valued_Procedure
2893 @findex Import_Valued_Procedure
2897 @smallexample @c ada
2898 pragma Import_Valued_Procedure (
2899 [Internal =>] LOCAL_NAME
2900 [, [External =>] EXTERNAL_SYMBOL]
2901 [, [Parameter_Types =>] PARAMETER_TYPES]
2902 [, [Mechanism =>] MECHANISM]
2903 [, [First_Optional_Parameter =>] IDENTIFIER]);
2907 | static_string_EXPRESSION
2911 | TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@}
2915 | subtype_Name ' Access
2919 | (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@})
2921 MECHANISM_ASSOCIATION ::=
2922 [formal_parameter_NAME =>] MECHANISM_NAME
2927 | Descriptor [([Class =>] CLASS_NAME)]
2928 | Short_Descriptor [([Class =>] CLASS_NAME)]
2930 CLASS_NAME ::= ubs | ubsb | uba | s | sb | a | nca
2934 This pragma is identical to @code{Import_Procedure} except that the
2935 first parameter of @var{LOCAL_NAME}, which must be present, must be of
2936 mode @code{OUT}, and externally the subprogram is treated as a function
2937 with this parameter as the result of the function. The purpose of this
2938 capability is to allow the use of @code{OUT} and @code{IN OUT}
2939 parameters in interfacing to external functions (which are not permitted
2940 in Ada functions). You may optionally use the @code{Mechanism}
2941 parameters to specify passing mechanisms for the parameters.
2942 If you specify a single mechanism name, it applies to all parameters.
2943 Otherwise you may specify a mechanism on a parameter by parameter
2944 basis using either positional or named notation. If the mechanism is not
2945 specified, the default mechanism is used.
2947 Note that it is important to use this pragma in conjunction with a separate
2948 pragma Import that specifies the desired convention, since otherwise the
2949 default convention is Ada, which is almost certainly not what is required.
2951 @node Pragma Initialize_Scalars
2952 @unnumberedsec Pragma Initialize_Scalars
2953 @findex Initialize_Scalars
2954 @cindex debugging with Initialize_Scalars
2958 @smallexample @c ada
2959 pragma Initialize_Scalars;
2963 This pragma is similar to @code{Normalize_Scalars} conceptually but has
2964 two important differences. First, there is no requirement for the pragma
2965 to be used uniformly in all units of a partition, in particular, it is fine
2966 to use this just for some or all of the application units of a partition,
2967 without needing to recompile the run-time library.
2969 In the case where some units are compiled with the pragma, and some without,
2970 then a declaration of a variable where the type is defined in package
2971 Standard or is locally declared will always be subject to initialization,
2972 as will any declaration of a scalar variable. For composite variables,
2973 whether the variable is initialized may also depend on whether the package
2974 in which the type of the variable is declared is compiled with the pragma.
2976 The other important difference is that you can control the value used
2977 for initializing scalar objects. At bind time, you can select several
2978 options for initialization. You can
2979 initialize with invalid values (similar to Normalize_Scalars, though for
2980 Initialize_Scalars it is not always possible to determine the invalid
2981 values in complex cases like signed component fields with non-standard
2982 sizes). You can also initialize with high or
2983 low values, or with a specified bit pattern. See the users guide for binder
2984 options for specifying these cases.
2986 This means that you can compile a program, and then without having to
2987 recompile the program, you can run it with different values being used
2988 for initializing otherwise uninitialized values, to test if your program
2989 behavior depends on the choice. Of course the behavior should not change,
2990 and if it does, then most likely you have an erroneous reference to an
2991 uninitialized value.
2993 It is even possible to change the value at execution time eliminating even
2994 the need to rebind with a different switch using an environment variable.
2995 See the GNAT users guide for details.
2997 Note that pragma @code{Initialize_Scalars} is particularly useful in
2998 conjunction with the enhanced validity checking that is now provided
2999 in GNAT, which checks for invalid values under more conditions.
3000 Using this feature (see description of the @option{-gnatV} flag in the
3001 users guide) in conjunction with pragma @code{Initialize_Scalars}
3002 provides a powerful new tool to assist in the detection of problems
3003 caused by uninitialized variables.
3005 Note: the use of @code{Initialize_Scalars} has a fairly extensive
3006 effect on the generated code. This may cause your code to be
3007 substantially larger. It may also cause an increase in the amount
3008 of stack required, so it is probably a good idea to turn on stack
3009 checking (see description of stack checking in the GNAT users guide)
3010 when using this pragma.
3012 @node Pragma Inline_Always
3013 @unnumberedsec Pragma Inline_Always
3014 @findex Inline_Always
3018 @smallexample @c ada
3019 pragma Inline_Always (NAME [, NAME]);
3023 Similar to pragma @code{Inline} except that inlining is not subject to
3024 the use of option @option{-gnatn} and the inlining happens regardless of
3025 whether this option is used.
3027 @node Pragma Inline_Generic
3028 @unnumberedsec Pragma Inline_Generic
3029 @findex Inline_Generic
3033 @smallexample @c ada
3034 pragma Inline_Generic (generic_package_NAME);
3038 This is implemented for compatibility with DEC Ada 83 and is recognized,
3039 but otherwise ignored, by GNAT@. All generic instantiations are inlined
3040 by default when using GNAT@.
3042 @node Pragma Interface
3043 @unnumberedsec Pragma Interface
3048 @smallexample @c ada
3050 [Convention =>] convention_identifier,
3051 [Entity =>] local_NAME
3052 [, [External_Name =>] static_string_expression]
3053 [, [Link_Name =>] static_string_expression]);
3057 This pragma is identical in syntax and semantics to
3058 the standard Ada pragma @code{Import}. It is provided for compatibility
3059 with Ada 83. The definition is upwards compatible both with pragma
3060 @code{Interface} as defined in the Ada 83 Reference Manual, and also
3061 with some extended implementations of this pragma in certain Ada 83
3062 implementations. The only difference between pragma @code{Interface}
3063 and pragma @code{Import} is that there is special circuitry to allow
3064 both pragmas to appear for the same subprogram entity (normally it
3065 is illegal to have multiple @code{Import} pragmas. This is useful in
3066 maintaining Ada 83/Ada 95 compatibility and is compatible with other
3069 @node Pragma Interface_Name
3070 @unnumberedsec Pragma Interface_Name
3071 @findex Interface_Name
3075 @smallexample @c ada
3076 pragma Interface_Name (
3077 [Entity =>] LOCAL_NAME
3078 [, [External_Name =>] static_string_EXPRESSION]
3079 [, [Link_Name =>] static_string_EXPRESSION]);
3083 This pragma provides an alternative way of specifying the interface name
3084 for an interfaced subprogram, and is provided for compatibility with Ada
3085 83 compilers that use the pragma for this purpose. You must provide at
3086 least one of @var{External_Name} or @var{Link_Name}.
3088 @node Pragma Interrupt_Handler
3089 @unnumberedsec Pragma Interrupt_Handler
3090 @findex Interrupt_Handler
3094 @smallexample @c ada
3095 pragma Interrupt_Handler (procedure_LOCAL_NAME);
3099 This program unit pragma is supported for parameterless protected procedures
3100 as described in Annex C of the Ada Reference Manual. On the AAMP target
3101 the pragma can also be specified for nonprotected parameterless procedures
3102 that are declared at the library level (which includes procedures
3103 declared at the top level of a library package). In the case of AAMP,
3104 when this pragma is applied to a nonprotected procedure, the instruction
3105 @code{IERET} is generated for returns from the procedure, enabling
3106 maskable interrupts, in place of the normal return instruction.
3108 @node Pragma Interrupt_State
3109 @unnumberedsec Pragma Interrupt_State
3110 @findex Interrupt_State
3114 @smallexample @c ada
3115 pragma Interrupt_State
3117 [State =>] SYSTEM | RUNTIME | USER);
3121 Normally certain interrupts are reserved to the implementation. Any attempt
3122 to attach an interrupt causes Program_Error to be raised, as described in
3123 RM C.3.2(22). A typical example is the @code{SIGINT} interrupt used in
3124 many systems for an @kbd{Ctrl-C} interrupt. Normally this interrupt is
3125 reserved to the implementation, so that @kbd{Ctrl-C} can be used to
3126 interrupt execution. Additionally, signals such as @code{SIGSEGV},
3127 @code{SIGABRT}, @code{SIGFPE} and @code{SIGILL} are often mapped to specific
3128 Ada exceptions, or used to implement run-time functions such as the
3129 @code{abort} statement and stack overflow checking.
3131 Pragma @code{Interrupt_State} provides a general mechanism for overriding
3132 such uses of interrupts. It subsumes the functionality of pragma
3133 @code{Unreserve_All_Interrupts}. Pragma @code{Interrupt_State} is not
3134 available on Windows or VMS. On all other platforms than VxWorks,
3135 it applies to signals; on VxWorks, it applies to vectored hardware interrupts
3136 and may be used to mark interrupts required by the board support package
3139 Interrupts can be in one of three states:
3143 The interrupt is reserved (no Ada handler can be installed), and the
3144 Ada run-time may not install a handler. As a result you are guaranteed
3145 standard system default action if this interrupt is raised.
3149 The interrupt is reserved (no Ada handler can be installed). The run time
3150 is allowed to install a handler for internal control purposes, but is
3151 not required to do so.
3155 The interrupt is unreserved. The user may install a handler to provide
3160 These states are the allowed values of the @code{State} parameter of the
3161 pragma. The @code{Name} parameter is a value of the type
3162 @code{Ada.Interrupts.Interrupt_ID}. Typically, it is a name declared in
3163 @code{Ada.Interrupts.Names}.
3165 This is a configuration pragma, and the binder will check that there
3166 are no inconsistencies between different units in a partition in how a
3167 given interrupt is specified. It may appear anywhere a pragma is legal.
3169 The effect is to move the interrupt to the specified state.
3171 By declaring interrupts to be SYSTEM, you guarantee the standard system
3172 action, such as a core dump.
3174 By declaring interrupts to be USER, you guarantee that you can install
3177 Note that certain signals on many operating systems cannot be caught and
3178 handled by applications. In such cases, the pragma is ignored. See the
3179 operating system documentation, or the value of the array @code{Reserved}
3180 declared in the spec of package @code{System.OS_Interface}.
3182 Overriding the default state of signals used by the Ada runtime may interfere
3183 with an application's runtime behavior in the cases of the synchronous signals,
3184 and in the case of the signal used to implement the @code{abort} statement.
3186 @node Pragma Invariant
3187 @unnumberedsec Pragma Invariant
3192 @smallexample @c ada
3194 ([Entity =>] private_type_LOCAL_NAME,
3195 [Check =>] EXPRESSION
3196 [,[Message =>] String_Expression]);
3200 This pragma provides exactly the same capabilities as the Invariant aspect
3201 defined in AI05-0146-1, and in the Ada 2012 Reference Manual. The Invariant
3202 aspect is fully implemented in Ada 2012 mode, but since it requires the use
3203 of the aspect syntax, which is not available exception in 2012 mode, it is
3204 not possible to use the Invariant aspect in earlier versions of Ada. However
3205 the Invariant pragma may be used in any version of Ada.
3207 The pragma must appear within the visible part of the package specification,
3208 after the type to which its Entity argument appears. As with the Invariant
3209 aspect, the Check expression is not analyzed until the end of the visible
3210 part of the package, so it may contain forward references. The Message
3211 argument, if present, provides the exception message used if the invariant
3212 is violated. If no Message parameter is provided, a default message that
3213 identifies the line on which the pragma appears is used.
3215 It is permissible to have multiple Invariants for the same type entity, in
3216 which case they are and'ed together. It is permissible to use this pragma
3217 in Ada 2012 mode, but you cannot have both an invariant aspect and an
3218 invariant pragma for the same entity.
3220 For further details on the use of this pragma, see the Ada 2012 documentation
3221 of the Invariant aspect.
3223 @node Pragma Keep_Names
3224 @unnumberedsec Pragma Keep_Names
3229 @smallexample @c ada
3230 pragma Keep_Names ([On =>] enumeration_first_subtype_LOCAL_NAME);
3234 The @var{LOCAL_NAME} argument
3235 must refer to an enumeration first subtype
3236 in the current declarative part. The effect is to retain the enumeration
3237 literal names for use by @code{Image} and @code{Value} even if a global
3238 @code{Discard_Names} pragma applies. This is useful when you want to
3239 generally suppress enumeration literal names and for example you therefore
3240 use a @code{Discard_Names} pragma in the @file{gnat.adc} file, but you
3241 want to retain the names for specific enumeration types.
3243 @node Pragma License
3244 @unnumberedsec Pragma License
3246 @cindex License checking
3250 @smallexample @c ada
3251 pragma License (Unrestricted | GPL | Modified_GPL | Restricted);
3255 This pragma is provided to allow automated checking for appropriate license
3256 conditions with respect to the standard and modified GPL@. A pragma
3257 @code{License}, which is a configuration pragma that typically appears at
3258 the start of a source file or in a separate @file{gnat.adc} file, specifies
3259 the licensing conditions of a unit as follows:
3263 This is used for a unit that can be freely used with no license restrictions.
3264 Examples of such units are public domain units, and units from the Ada
3268 This is used for a unit that is licensed under the unmodified GPL, and which
3269 therefore cannot be @code{with}'ed by a restricted unit.
3272 This is used for a unit licensed under the GNAT modified GPL that includes
3273 a special exception paragraph that specifically permits the inclusion of
3274 the unit in programs without requiring the entire program to be released
3278 This is used for a unit that is restricted in that it is not permitted to
3279 depend on units that are licensed under the GPL@. Typical examples are
3280 proprietary code that is to be released under more restrictive license
3281 conditions. Note that restricted units are permitted to @code{with} units
3282 which are licensed under the modified GPL (this is the whole point of the
3288 Normally a unit with no @code{License} pragma is considered to have an
3289 unknown license, and no checking is done. However, standard GNAT headers
3290 are recognized, and license information is derived from them as follows.
3294 A GNAT license header starts with a line containing 78 hyphens. The following
3295 comment text is searched for the appearance of any of the following strings.
3297 If the string ``GNU General Public License'' is found, then the unit is assumed
3298 to have GPL license, unless the string ``As a special exception'' follows, in
3299 which case the license is assumed to be modified GPL@.
3301 If one of the strings
3302 ``This specification is adapted from the Ada Semantic Interface'' or
3303 ``This specification is derived from the Ada Reference Manual'' is found
3304 then the unit is assumed to be unrestricted.
3308 These default actions means that a program with a restricted license pragma
3309 will automatically get warnings if a GPL unit is inappropriately
3310 @code{with}'ed. For example, the program:
3312 @smallexample @c ada
3315 procedure Secret_Stuff is
3321 if compiled with pragma @code{License} (@code{Restricted}) in a
3322 @file{gnat.adc} file will generate the warning:
3327 >>> license of withed unit "Sem_Ch3" is incompatible
3329 2. with GNAT.Sockets;
3330 3. procedure Secret_Stuff is
3334 Here we get a warning on @code{Sem_Ch3} since it is part of the GNAT
3335 compiler and is licensed under the
3336 GPL, but no warning for @code{GNAT.Sockets} which is part of the GNAT
3337 run time, and is therefore licensed under the modified GPL@.
3339 @node Pragma Link_With
3340 @unnumberedsec Pragma Link_With
3345 @smallexample @c ada
3346 pragma Link_With (static_string_EXPRESSION @{,static_string_EXPRESSION@});
3350 This pragma is provided for compatibility with certain Ada 83 compilers.
3351 It has exactly the same effect as pragma @code{Linker_Options} except
3352 that spaces occurring within one of the string expressions are treated
3353 as separators. For example, in the following case:
3355 @smallexample @c ada
3356 pragma Link_With ("-labc -ldef");
3360 results in passing the strings @code{-labc} and @code{-ldef} as two
3361 separate arguments to the linker. In addition pragma Link_With allows
3362 multiple arguments, with the same effect as successive pragmas.
3364 @node Pragma Linker_Alias
3365 @unnumberedsec Pragma Linker_Alias
3366 @findex Linker_Alias
3370 @smallexample @c ada
3371 pragma Linker_Alias (
3372 [Entity =>] LOCAL_NAME,
3373 [Target =>] static_string_EXPRESSION);
3377 @var{LOCAL_NAME} must refer to an object that is declared at the library
3378 level. This pragma establishes the given entity as a linker alias for the
3379 given target. It is equivalent to @code{__attribute__((alias))} in GNU C
3380 and causes @var{LOCAL_NAME} to be emitted as an alias for the symbol
3381 @var{static_string_EXPRESSION} in the object file, that is to say no space
3382 is reserved for @var{LOCAL_NAME} by the assembler and it will be resolved
3383 to the same address as @var{static_string_EXPRESSION} by the linker.
3385 The actual linker name for the target must be used (e.g.@: the fully
3386 encoded name with qualification in Ada, or the mangled name in C++),
3387 or it must be declared using the C convention with @code{pragma Import}
3388 or @code{pragma Export}.
3390 Not all target machines support this pragma. On some of them it is accepted
3391 only if @code{pragma Weak_External} has been applied to @var{LOCAL_NAME}.
3393 @smallexample @c ada
3394 -- Example of the use of pragma Linker_Alias
3398 pragma Export (C, i);
3400 new_name_for_i : Integer;
3401 pragma Linker_Alias (new_name_for_i, "i");
3405 @node Pragma Linker_Constructor
3406 @unnumberedsec Pragma Linker_Constructor
3407 @findex Linker_Constructor
3411 @smallexample @c ada
3412 pragma Linker_Constructor (procedure_LOCAL_NAME);
3416 @var{procedure_LOCAL_NAME} must refer to a parameterless procedure that
3417 is declared at the library level. A procedure to which this pragma is
3418 applied will be treated as an initialization routine by the linker.
3419 It is equivalent to @code{__attribute__((constructor))} in GNU C and
3420 causes @var{procedure_LOCAL_NAME} to be invoked before the entry point
3421 of the executable is called (or immediately after the shared library is
3422 loaded if the procedure is linked in a shared library), in particular
3423 before the Ada run-time environment is set up.
3425 Because of these specific contexts, the set of operations such a procedure
3426 can perform is very limited and the type of objects it can manipulate is
3427 essentially restricted to the elementary types. In particular, it must only
3428 contain code to which pragma Restrictions (No_Elaboration_Code) applies.
3430 This pragma is used by GNAT to implement auto-initialization of shared Stand
3431 Alone Libraries, which provides a related capability without the restrictions
3432 listed above. Where possible, the use of Stand Alone Libraries is preferable
3433 to the use of this pragma.
3435 @node Pragma Linker_Destructor
3436 @unnumberedsec Pragma Linker_Destructor
3437 @findex Linker_Destructor
3441 @smallexample @c ada
3442 pragma Linker_Destructor (procedure_LOCAL_NAME);
3446 @var{procedure_LOCAL_NAME} must refer to a parameterless procedure that
3447 is declared at the library level. A procedure to which this pragma is
3448 applied will be treated as a finalization routine by the linker.
3449 It is equivalent to @code{__attribute__((destructor))} in GNU C and
3450 causes @var{procedure_LOCAL_NAME} to be invoked after the entry point
3451 of the executable has exited (or immediately before the shared library
3452 is unloaded if the procedure is linked in a shared library), in particular
3453 after the Ada run-time environment is shut down.
3455 See @code{pragma Linker_Constructor} for the set of restrictions that apply
3456 because of these specific contexts.
3458 @node Pragma Linker_Section
3459 @unnumberedsec Pragma Linker_Section
3460 @findex Linker_Section
3464 @smallexample @c ada
3465 pragma Linker_Section (
3466 [Entity =>] LOCAL_NAME,
3467 [Section =>] static_string_EXPRESSION);
3471 @var{LOCAL_NAME} must refer to an object that is declared at the library
3472 level. This pragma specifies the name of the linker section for the given
3473 entity. It is equivalent to @code{__attribute__((section))} in GNU C and
3474 causes @var{LOCAL_NAME} to be placed in the @var{static_string_EXPRESSION}
3475 section of the executable (assuming the linker doesn't rename the section).
3477 The compiler normally places library-level objects in standard sections
3478 depending on their type: procedures and functions generally go in the
3479 @code{.text} section, initialized variables in the @code{.data} section
3480 and uninitialized variables in the @code{.bss} section.
3482 Other, special sections may exist on given target machines to map special
3483 hardware, for example I/O ports or flash memory. This pragma is a means to
3484 defer the final layout of the executable to the linker, thus fully working
3485 at the symbolic level with the compiler.
3487 Some file formats do not support arbitrary sections so not all target
3488 machines support this pragma. The use of this pragma may cause a program
3489 execution to be erroneous if it is used to place an entity into an
3490 inappropriate section (e.g.@: a modified variable into the @code{.text}
3491 section). See also @code{pragma Persistent_BSS}.
3493 @smallexample @c ada
3494 -- Example of the use of pragma Linker_Section
3498 pragma Volatile (Port_A);
3499 pragma Linker_Section (Port_A, ".bss.port_a");
3502 pragma Volatile (Port_B);
3503 pragma Linker_Section (Port_B, ".bss.port_b");
3507 @node Pragma Long_Float
3508 @unnumberedsec Pragma Long_Float
3514 @smallexample @c ada
3515 pragma Long_Float (FLOAT_FORMAT);
3517 FLOAT_FORMAT ::= D_Float | G_Float
3521 This pragma is implemented only in the OpenVMS implementation of GNAT@.
3522 It allows control over the internal representation chosen for the predefined
3523 type @code{Long_Float} and for floating point type representations with
3524 @code{digits} specified in the range 7 through 15.
3525 For further details on this pragma, see the
3526 @cite{DEC Ada Language Reference Manual}, section 3.5.7b. Note that to use
3527 this pragma, the standard runtime libraries must be recompiled.
3529 @node Pragma Machine_Attribute
3530 @unnumberedsec Pragma Machine_Attribute
3531 @findex Machine_Attribute
3535 @smallexample @c ada
3536 pragma Machine_Attribute (
3537 [Entity =>] LOCAL_NAME,
3538 [Attribute_Name =>] static_string_EXPRESSION
3539 [, [Info =>] static_EXPRESSION] );
3543 Machine-dependent attributes can be specified for types and/or
3544 declarations. This pragma is semantically equivalent to
3545 @code{__attribute__((@var{attribute_name}))} (if @var{info} is not
3546 specified) or @code{__attribute__((@var{attribute_name}(@var{info})))}
3547 in GNU C, where @code{@var{attribute_name}} is recognized by the
3548 compiler middle-end or the @code{TARGET_ATTRIBUTE_TABLE} machine
3549 specific macro. A string literal for the optional parameter @var{info}
3550 is transformed into an identifier, which may make this pragma unusable
3551 for some attributes. @xref{Target Attributes,, Defining target-specific
3552 uses of @code{__attribute__}, gccint, GNU Compiler Collection (GCC)
3553 Internals}, further information.
3556 @unnumberedsec Pragma Main
3562 @smallexample @c ada
3564 (MAIN_OPTION [, MAIN_OPTION]);
3567 [Stack_Size =>] static_integer_EXPRESSION
3568 | [Task_Stack_Size_Default =>] static_integer_EXPRESSION
3569 | [Time_Slicing_Enabled =>] static_boolean_EXPRESSION
3573 This pragma is provided for compatibility with OpenVMS VAX Systems. It has
3574 no effect in GNAT, other than being syntax checked.
3576 @node Pragma Main_Storage
3577 @unnumberedsec Pragma Main_Storage
3579 @findex Main_Storage
3583 @smallexample @c ada
3585 (MAIN_STORAGE_OPTION [, MAIN_STORAGE_OPTION]);
3587 MAIN_STORAGE_OPTION ::=
3588 [WORKING_STORAGE =>] static_SIMPLE_EXPRESSION
3589 | [TOP_GUARD =>] static_SIMPLE_EXPRESSION
3593 This pragma is provided for compatibility with OpenVMS VAX Systems. It has
3594 no effect in GNAT, other than being syntax checked. Note that the pragma
3595 also has no effect in DEC Ada 83 for OpenVMS Alpha Systems.
3597 @node Pragma No_Body
3598 @unnumberedsec Pragma No_Body
3603 @smallexample @c ada
3608 There are a number of cases in which a package spec does not require a body,
3609 and in fact a body is not permitted. GNAT will not permit the spec to be
3610 compiled if there is a body around. The pragma No_Body allows you to provide
3611 a body file, even in a case where no body is allowed. The body file must
3612 contain only comments and a single No_Body pragma. This is recognized by
3613 the compiler as indicating that no body is logically present.
3615 This is particularly useful during maintenance when a package is modified in
3616 such a way that a body needed before is no longer needed. The provision of a
3617 dummy body with a No_Body pragma ensures that there is no interference from
3618 earlier versions of the package body.
3620 @node Pragma No_Return
3621 @unnumberedsec Pragma No_Return
3626 @smallexample @c ada
3627 pragma No_Return (procedure_LOCAL_NAME @{, procedure_LOCAL_NAME@});
3631 Each @var{procedure_LOCAL_NAME} argument must refer to one or more procedure
3632 declarations in the current declarative part. A procedure to which this
3633 pragma is applied may not contain any explicit @code{return} statements.
3634 In addition, if the procedure contains any implicit returns from falling
3635 off the end of a statement sequence, then execution of that implicit
3636 return will cause Program_Error to be raised.
3638 One use of this pragma is to identify procedures whose only purpose is to raise
3639 an exception. Another use of this pragma is to suppress incorrect warnings
3640 about missing returns in functions, where the last statement of a function
3641 statement sequence is a call to such a procedure.
3643 Note that in Ada 2005 mode, this pragma is part of the language, and is
3644 identical in effect to the pragma as implemented in Ada 95 mode.
3646 @node Pragma No_Strict_Aliasing
3647 @unnumberedsec Pragma No_Strict_Aliasing
3648 @findex No_Strict_Aliasing
3652 @smallexample @c ada
3653 pragma No_Strict_Aliasing [([Entity =>] type_LOCAL_NAME)];
3657 @var{type_LOCAL_NAME} must refer to an access type
3658 declaration in the current declarative part. The effect is to inhibit
3659 strict aliasing optimization for the given type. The form with no
3660 arguments is a configuration pragma which applies to all access types
3661 declared in units to which the pragma applies. For a detailed
3662 description of the strict aliasing optimization, and the situations
3663 in which it must be suppressed, see @ref{Optimization and Strict
3664 Aliasing,,, gnat_ugn, @value{EDITION} User's Guide}.
3666 This pragma currently has no effects on access to unconstrained array types.
3668 @node Pragma Normalize_Scalars
3669 @unnumberedsec Pragma Normalize_Scalars
3670 @findex Normalize_Scalars
3674 @smallexample @c ada
3675 pragma Normalize_Scalars;
3679 This is a language defined pragma which is fully implemented in GNAT@. The
3680 effect is to cause all scalar objects that are not otherwise initialized
3681 to be initialized. The initial values are implementation dependent and
3685 @item Standard.Character
3687 Objects whose root type is Standard.Character are initialized to
3688 Character'Last unless the subtype range excludes NUL (in which case
3689 NUL is used). This choice will always generate an invalid value if
3692 @item Standard.Wide_Character
3694 Objects whose root type is Standard.Wide_Character are initialized to
3695 Wide_Character'Last unless the subtype range excludes NUL (in which case
3696 NUL is used). This choice will always generate an invalid value if
3699 @item Standard.Wide_Wide_Character
3701 Objects whose root type is Standard.Wide_Wide_Character are initialized to
3702 the invalid value 16#FFFF_FFFF# unless the subtype range excludes NUL (in
3703 which case NUL is used). This choice will always generate an invalid value if
3708 Objects of an integer type are treated differently depending on whether
3709 negative values are present in the subtype. If no negative values are
3710 present, then all one bits is used as the initial value except in the
3711 special case where zero is excluded from the subtype, in which case
3712 all zero bits are used. This choice will always generate an invalid
3713 value if one exists.
3715 For subtypes with negative values present, the largest negative number
3716 is used, except in the unusual case where this largest negative number
3717 is in the subtype, and the largest positive number is not, in which case
3718 the largest positive value is used. This choice will always generate
3719 an invalid value if one exists.
3721 @item Floating-Point Types
3722 Objects of all floating-point types are initialized to all 1-bits. For
3723 standard IEEE format, this corresponds to a NaN (not a number) which is
3724 indeed an invalid value.
3726 @item Fixed-Point Types
3727 Objects of all fixed-point types are treated as described above for integers,
3728 with the rules applying to the underlying integer value used to represent
3729 the fixed-point value.
3732 Objects of a modular type are initialized to all one bits, except in
3733 the special case where zero is excluded from the subtype, in which
3734 case all zero bits are used. This choice will always generate an
3735 invalid value if one exists.
3737 @item Enumeration types
3738 Objects of an enumeration type are initialized to all one-bits, i.e.@: to
3739 the value @code{2 ** typ'Size - 1} unless the subtype excludes the literal
3740 whose Pos value is zero, in which case a code of zero is used. This choice
3741 will always generate an invalid value if one exists.
3745 @node Pragma Obsolescent
3746 @unnumberedsec Pragma Obsolescent
3751 @smallexample @c ada
3754 pragma Obsolescent (
3755 [Message =>] static_string_EXPRESSION
3756 [,[Version =>] Ada_05]]);
3758 pragma Obsolescent (
3760 [,[Message =>] static_string_EXPRESSION
3761 [,[Version =>] Ada_05]] );
3765 This pragma can occur immediately following a declaration of an entity,
3766 including the case of a record component. If no Entity argument is present,
3767 then this declaration is the one to which the pragma applies. If an Entity
3768 parameter is present, it must either match the name of the entity in this
3769 declaration, or alternatively, the pragma can immediately follow an enumeration
3770 type declaration, where the Entity argument names one of the enumeration
3773 This pragma is used to indicate that the named entity
3774 is considered obsolescent and should not be used. Typically this is
3775 used when an API must be modified by eventually removing or modifying
3776 existing subprograms or other entities. The pragma can be used at an
3777 intermediate stage when the entity is still present, but will be
3780 The effect of this pragma is to output a warning message on a reference to
3781 an entity thus marked that the subprogram is obsolescent if the appropriate
3782 warning option in the compiler is activated. If the Message parameter is
3783 present, then a second warning message is given containing this text. In
3784 addition, a reference to the entity is considered to be a violation of pragma
3785 Restrictions (No_Obsolescent_Features).
3787 This pragma can also be used as a program unit pragma for a package,
3788 in which case the entity name is the name of the package, and the
3789 pragma indicates that the entire package is considered
3790 obsolescent. In this case a client @code{with}'ing such a package
3791 violates the restriction, and the @code{with} statement is
3792 flagged with warnings if the warning option is set.
3794 If the Version parameter is present (which must be exactly
3795 the identifier Ada_05, no other argument is allowed), then the
3796 indication of obsolescence applies only when compiling in Ada 2005
3797 mode. This is primarily intended for dealing with the situations
3798 in the predefined library where subprograms or packages
3799 have become defined as obsolescent in Ada 2005
3800 (e.g.@: in Ada.Characters.Handling), but may be used anywhere.
3802 The following examples show typical uses of this pragma:
3804 @smallexample @c ada
3806 pragma Obsolescent (p, Message => "use pp instead of p");
3811 pragma Obsolescent ("use q2new instead");
3813 type R is new integer;
3816 Message => "use RR in Ada 2005",
3826 type E is (a, bc, 'd', quack);
3827 pragma Obsolescent (Entity => bc)
3828 pragma Obsolescent (Entity => 'd')
3831 (a, b : character) return character;
3832 pragma Obsolescent (Entity => "+");
3837 Note that, as for all pragmas, if you use a pragma argument identifier,
3838 then all subsequent parameters must also use a pragma argument identifier.
3839 So if you specify "Entity =>" for the Entity argument, and a Message
3840 argument is present, it must be preceded by "Message =>".
3842 @node Pragma Optimize_Alignment
3843 @unnumberedsec Pragma Optimize_Alignment
3844 @findex Optimize_Alignment
3845 @cindex Alignment, default settings
3849 @smallexample @c ada
3850 pragma Optimize_Alignment (TIME | SPACE | OFF);
3854 This is a configuration pragma which affects the choice of default alignments
3855 for types where no alignment is explicitly specified. There is a time/space
3856 trade-off in the selection of these values. Large alignments result in more
3857 efficient code, at the expense of larger data space, since sizes have to be
3858 increased to match these alignments. Smaller alignments save space, but the
3859 access code is slower. The normal choice of default alignments (which is what
3860 you get if you do not use this pragma, or if you use an argument of OFF),
3861 tries to balance these two requirements.
3863 Specifying SPACE causes smaller default alignments to be chosen in two cases.
3864 First any packed record is given an alignment of 1. Second, if a size is given
3865 for the type, then the alignment is chosen to avoid increasing this size. For
3868 @smallexample @c ada
3878 In the default mode, this type gets an alignment of 4, so that access to the
3879 Integer field X are efficient. But this means that objects of the type end up
3880 with a size of 8 bytes. This is a valid choice, since sizes of objects are
3881 allowed to be bigger than the size of the type, but it can waste space if for
3882 example fields of type R appear in an enclosing record. If the above type is
3883 compiled in @code{Optimize_Alignment (Space)} mode, the alignment is set to 1.
3885 Specifying TIME causes larger default alignments to be chosen in the case of
3886 small types with sizes that are not a power of 2. For example, consider:
3888 @smallexample @c ada
3900 The default alignment for this record is normally 1, but if this type is
3901 compiled in @code{Optimize_Alignment (Time)} mode, then the alignment is set
3902 to 4, which wastes space for objects of the type, since they are now 4 bytes
3903 long, but results in more efficient access when the whole record is referenced.
3905 As noted above, this is a configuration pragma, and there is a requirement
3906 that all units in a partition be compiled with a consistent setting of the
3907 optimization setting. This would normally be achieved by use of a configuration
3908 pragma file containing the appropriate setting. The exception to this rule is
3909 that units with an explicit configuration pragma in the same file as the source
3910 unit are excluded from the consistency check, as are all predefined units. The
3911 latter are compiled by default in pragma Optimize_Alignment (Off) mode if no
3912 pragma appears at the start of the file.
3914 @node Pragma Ordered
3915 @unnumberedsec Pragma Ordered
3917 @findex pragma @code{Ordered}
3921 @smallexample @c ada
3922 pragma Ordered (enumeration_first_subtype_LOCAL_NAME);
3926 Most enumeration types are from a conceptual point of view unordered.
3927 For example, consider:
3929 @smallexample @c ada
3930 type Color is (Red, Blue, Green, Yellow);
3934 By Ada semantics @code{Blue > Red} and @code{Green > Blue},
3935 but really these relations make no sense; the enumeration type merely
3936 specifies a set of possible colors, and the order is unimportant.
3938 For unordered enumeration types, it is generally a good idea if
3939 clients avoid comparisons (other than equality or inequality) and
3940 explicit ranges. (A @emph{client} is a unit where the type is referenced,
3941 other than the unit where the type is declared, its body, and its subunits.)
3942 For example, if code buried in some client says:
3944 @smallexample @c ada
3945 if Current_Color < Yellow then ...
3946 if Current_Color in Blue .. Green then ...
3950 then the client code is relying on the order, which is undesirable.
3951 It makes the code hard to read and creates maintenance difficulties if
3952 entries have to be added to the enumeration type. Instead,
3953 the code in the client should list the possibilities, or an
3954 appropriate subtype should be declared in the unit that declares
3955 the original enumeration type. E.g., the following subtype could
3956 be declared along with the type @code{Color}:
3958 @smallexample @c ada
3959 subtype RBG is Color range Red .. Green;
3963 and then the client could write:
3965 @smallexample @c ada
3966 if Current_Color in RBG then ...
3967 if Current_Color = Blue or Current_Color = Green then ...
3971 However, some enumeration types are legitimately ordered from a conceptual
3972 point of view. For example, if you declare:
3974 @smallexample @c ada
3975 type Day is (Mon, Tue, Wed, Thu, Fri, Sat, Sun);
3979 then the ordering imposed by the language is reasonable, and
3980 clients can depend on it, writing for example:
3982 @smallexample @c ada
3983 if D in Mon .. Fri then ...
3988 The pragma @option{Ordered} is provided to mark enumeration types that
3989 are conceptually ordered, alerting the reader that clients may depend
3990 on the ordering. GNAT provides a pragma to mark enumerations as ordered
3991 rather than one to mark them as unordered, since in our experience,
3992 the great majority of enumeration types are conceptually unordered.
3994 The types @code{Boolean}, @code{Character}, @code{Wide_Character},
3995 and @code{Wide_Wide_Character}
3996 are considered to be ordered types, so each is declared with a
3997 pragma @code{Ordered} in package @code{Standard}.
3999 Normally pragma @code{Ordered} serves only as documentation and a guide for
4000 coding standards, but GNAT provides a warning switch @option{-gnatw.u} that
4001 requests warnings for inappropriate uses (comparisons and explicit
4002 subranges) for unordered types. If this switch is used, then any
4003 enumeration type not marked with pragma @code{Ordered} will be considered
4004 as unordered, and will generate warnings for inappropriate uses.
4006 For additional information please refer to the description of the
4007 @option{-gnatw.u} switch in the @value{EDITION} User's Guide.
4009 @node Pragma Passive
4010 @unnumberedsec Pragma Passive
4015 @smallexample @c ada
4016 pragma Passive [(Semaphore | No)];
4020 Syntax checked, but otherwise ignored by GNAT@. This is recognized for
4021 compatibility with DEC Ada 83 implementations, where it is used within a
4022 task definition to request that a task be made passive. If the argument
4023 @code{Semaphore} is present, or the argument is omitted, then DEC Ada 83
4024 treats the pragma as an assertion that the containing task is passive
4025 and that optimization of context switch with this task is permitted and
4026 desired. If the argument @code{No} is present, the task must not be
4027 optimized. GNAT does not attempt to optimize any tasks in this manner
4028 (since protected objects are available in place of passive tasks).
4030 @node Pragma Persistent_BSS
4031 @unnumberedsec Pragma Persistent_BSS
4032 @findex Persistent_BSS
4036 @smallexample @c ada
4037 pragma Persistent_BSS [(LOCAL_NAME)]
4041 This pragma allows selected objects to be placed in the @code{.persistent_bss}
4042 section. On some targets the linker and loader provide for special
4043 treatment of this section, allowing a program to be reloaded without
4044 affecting the contents of this data (hence the name persistent).
4046 There are two forms of usage. If an argument is given, it must be the
4047 local name of a library level object, with no explicit initialization
4048 and whose type is potentially persistent. If no argument is given, then
4049 the pragma is a configuration pragma, and applies to all library level
4050 objects with no explicit initialization of potentially persistent types.
4052 A potentially persistent type is a scalar type, or a non-tagged,
4053 non-discriminated record, all of whose components have no explicit
4054 initialization and are themselves of a potentially persistent type,
4055 or an array, all of whose constraints are static, and whose component
4056 type is potentially persistent.
4058 If this pragma is used on a target where this feature is not supported,
4059 then the pragma will be ignored. See also @code{pragma Linker_Section}.
4061 @node Pragma Polling
4062 @unnumberedsec Pragma Polling
4067 @smallexample @c ada
4068 pragma Polling (ON | OFF);
4072 This pragma controls the generation of polling code. This is normally off.
4073 If @code{pragma Polling (ON)} is used then periodic calls are generated to
4074 the routine @code{Ada.Exceptions.Poll}. This routine is a separate unit in the
4075 runtime library, and can be found in file @file{a-excpol.adb}.
4077 Pragma @code{Polling} can appear as a configuration pragma (for example it
4078 can be placed in the @file{gnat.adc} file) to enable polling globally, or it
4079 can be used in the statement or declaration sequence to control polling
4082 A call to the polling routine is generated at the start of every loop and
4083 at the start of every subprogram call. This guarantees that the @code{Poll}
4084 routine is called frequently, and places an upper bound (determined by
4085 the complexity of the code) on the period between two @code{Poll} calls.
4087 The primary purpose of the polling interface is to enable asynchronous
4088 aborts on targets that cannot otherwise support it (for example Windows
4089 NT), but it may be used for any other purpose requiring periodic polling.
4090 The standard version is null, and can be replaced by a user program. This
4091 will require re-compilation of the @code{Ada.Exceptions} package that can
4092 be found in files @file{a-except.ads} and @file{a-except.adb}.
4094 A standard alternative unit (in file @file{4wexcpol.adb} in the standard GNAT
4095 distribution) is used to enable the asynchronous abort capability on
4096 targets that do not normally support the capability. The version of
4097 @code{Poll} in this file makes a call to the appropriate runtime routine
4098 to test for an abort condition.
4100 Note that polling can also be enabled by use of the @option{-gnatP} switch.
4101 @xref{Switches for gcc,,, gnat_ugn, @value{EDITION} User's Guide}, for
4104 @node Pragma Postcondition
4105 @unnumberedsec Pragma Postcondition
4106 @cindex Postconditions
4107 @cindex Checks, postconditions
4108 @findex Postconditions
4112 @smallexample @c ada
4113 pragma Postcondition (
4114 [Check =>] Boolean_Expression
4115 [,[Message =>] String_Expression]);
4119 The @code{Postcondition} pragma allows specification of automatic
4120 postcondition checks for subprograms. These checks are similar to
4121 assertions, but are automatically inserted just prior to the return
4122 statements of the subprogram with which they are associated (including
4123 implicit returns at the end of procedure bodies and associated
4124 exception handlers).
4126 In addition, the boolean expression which is the condition which
4127 must be true may contain references to function'Result in the case
4128 of a function to refer to the returned value.
4130 @code{Postcondition} pragmas may appear either immediately following the
4131 (separate) declaration of a subprogram, or at the start of the
4132 declarations of a subprogram body. Only other pragmas may intervene
4133 (that is appear between the subprogram declaration and its
4134 postconditions, or appear before the postcondition in the
4135 declaration sequence in a subprogram body). In the case of a
4136 postcondition appearing after a subprogram declaration, the
4137 formal arguments of the subprogram are visible, and can be
4138 referenced in the postcondition expressions.
4140 The postconditions are collected and automatically tested just
4141 before any return (implicit or explicit) in the subprogram body.
4142 A postcondition is only recognized if postconditions are active
4143 at the time the pragma is encountered. The compiler switch @option{gnata}
4144 turns on all postconditions by default, and pragma @code{Check_Policy}
4145 with an identifier of @code{Postcondition} can also be used to
4146 control whether postconditions are active.
4148 The general approach is that postconditions are placed in the spec
4149 if they represent functional aspects which make sense to the client.
4150 For example we might have:
4152 @smallexample @c ada
4153 function Direction return Integer;
4154 pragma Postcondition
4155 (Direction'Result = +1
4157 Direction'Result = -1);
4161 which serves to document that the result must be +1 or -1, and
4162 will test that this is the case at run time if postcondition
4165 Postconditions within the subprogram body can be used to
4166 check that some internal aspect of the implementation,
4167 not visible to the client, is operating as expected.
4168 For instance if a square root routine keeps an internal
4169 counter of the number of times it is called, then we
4170 might have the following postcondition:
4172 @smallexample @c ada
4173 Sqrt_Calls : Natural := 0;
4175 function Sqrt (Arg : Float) return Float is
4176 pragma Postcondition
4177 (Sqrt_Calls = Sqrt_Calls'Old + 1);
4183 As this example, shows, the use of the @code{Old} attribute
4184 is often useful in postconditions to refer to the state on
4185 entry to the subprogram.
4187 Note that postconditions are only checked on normal returns
4188 from the subprogram. If an abnormal return results from
4189 raising an exception, then the postconditions are not checked.
4191 If a postcondition fails, then the exception
4192 @code{System.Assertions.Assert_Failure} is raised. If
4193 a message argument was supplied, then the given string
4194 will be used as the exception message. If no message
4195 argument was supplied, then the default message has
4196 the form "Postcondition failed at file:line". The
4197 exception is raised in the context of the subprogram
4198 body, so it is possible to catch postcondition failures
4199 within the subprogram body itself.
4201 Within a package spec, normal visibility rules
4202 in Ada would prevent forward references within a
4203 postcondition pragma to functions defined later in
4204 the same package. This would introduce undesirable
4205 ordering constraints. To avoid this problem, all
4206 postcondition pragmas are analyzed at the end of
4207 the package spec, allowing forward references.
4209 The following example shows that this even allows
4210 mutually recursive postconditions as in:
4212 @smallexample @c ada
4213 package Parity_Functions is
4214 function Odd (X : Natural) return Boolean;
4215 pragma Postcondition
4219 (x /= 0 and then Even (X - 1))));
4221 function Even (X : Natural) return Boolean;
4222 pragma Postcondition
4226 (x /= 1 and then Odd (X - 1))));
4228 end Parity_Functions;
4232 There are no restrictions on the complexity or form of
4233 conditions used within @code{Postcondition} pragmas.
4234 The following example shows that it is even possible
4235 to verify performance behavior.
4237 @smallexample @c ada
4240 Performance : constant Float;
4241 -- Performance constant set by implementation
4242 -- to match target architecture behavior.
4244 procedure Treesort (Arg : String);
4245 -- Sorts characters of argument using N*logN sort
4246 pragma Postcondition
4247 (Float (Clock - Clock'Old) <=
4248 Float (Arg'Length) *
4249 log (Float (Arg'Length)) *
4255 Note: postcondition pragmas associated with subprograms that are
4256 marked as Inline_Always, or those marked as Inline with front-end
4257 inlining (-gnatN option set) are accepted and legality-checked
4258 by the compiler, but are ignored at run-time even if postcondition
4259 checking is enabled.
4261 @node Pragma Precondition
4262 @unnumberedsec Pragma Precondition
4263 @cindex Preconditions
4264 @cindex Checks, preconditions
4265 @findex Preconditions
4269 @smallexample @c ada
4270 pragma Precondition (
4271 [Check =>] Boolean_Expression
4272 [,[Message =>] String_Expression]);
4276 The @code{Precondition} pragma is similar to @code{Postcondition}
4277 except that the corresponding checks take place immediately upon
4278 entry to the subprogram, and if a precondition fails, the exception
4279 is raised in the context of the caller, and the attribute 'Result
4280 cannot be used within the precondition expression.
4282 Otherwise, the placement and visibility rules are identical to those
4283 described for postconditions. The following is an example of use
4284 within a package spec:
4286 @smallexample @c ada
4287 package Math_Functions is
4289 function Sqrt (Arg : Float) return Float;
4290 pragma Precondition (Arg >= 0.0)
4296 @code{Precondition} pragmas may appear either immediately following the
4297 (separate) declaration of a subprogram, or at the start of the
4298 declarations of a subprogram body. Only other pragmas may intervene
4299 (that is appear between the subprogram declaration and its
4300 postconditions, or appear before the postcondition in the
4301 declaration sequence in a subprogram body).
4303 Note: postcondition pragmas associated with subprograms that are
4304 marked as Inline_Always, or those marked as Inline with front-end
4305 inlining (-gnatN option set) are accepted and legality-checked
4306 by the compiler, but are ignored at run-time even if postcondition
4307 checking is enabled.
4309 @node Pragma Profile (Ravenscar)
4310 @unnumberedsec Pragma Profile (Ravenscar)
4315 @smallexample @c ada
4316 pragma Profile (Ravenscar);
4320 A configuration pragma that establishes the following set of configuration
4324 @item Task_Dispatching_Policy (FIFO_Within_Priorities)
4325 [RM D.2.2] Tasks are dispatched following a preemptive
4326 priority-ordered scheduling policy.
4328 @item Locking_Policy (Ceiling_Locking)
4329 [RM D.3] While tasks and interrupts execute a protected action, they inherit
4330 the ceiling priority of the corresponding protected object.
4332 @c @item Detect_Blocking
4333 @c This pragma forces the detection of potentially blocking operations within a
4334 @c protected operation, and to raise Program_Error if that happens.
4338 plus the following set of restrictions:
4341 @item Max_Entry_Queue_Length => 1
4342 No task can be queued on a protected entry.
4343 @item Max_Protected_Entries => 1
4344 @item Max_Task_Entries => 0
4345 No rendezvous statements are allowed.
4346 @item No_Abort_Statements
4347 @item No_Dynamic_Attachment
4348 @item No_Dynamic_Priorities
4349 @item No_Implicit_Heap_Allocations
4350 @item No_Local_Protected_Objects
4351 @item No_Local_Timing_Events
4352 @item No_Protected_Type_Allocators
4353 @item No_Relative_Delay
4354 @item No_Requeue_Statements
4355 @item No_Select_Statements
4356 @item No_Specific_Termination_Handlers
4357 @item No_Task_Allocators
4358 @item No_Task_Hierarchy
4359 @item No_Task_Termination
4360 @item Simple_Barriers
4364 The Ravenscar profile also includes the following restrictions that specify
4365 that there are no semantic dependences on the corresponding predefined
4369 @item No_Dependence => Ada.Asynchronous_Task_Control
4370 @item No_Dependence => Ada.Calendar
4371 @item No_Dependence => Ada.Execution_Time.Group_Budget
4372 @item No_Dependence => Ada.Execution_Time.Timers
4373 @item No_Dependence => Ada.Task_Attributes
4374 @item No_Dependence => System.Multiprocessors.Dispatching_Domains
4379 This set of configuration pragmas and restrictions correspond to the
4380 definition of the ``Ravenscar Profile'' for limited tasking, devised and
4381 published by the @cite{International Real-Time Ada Workshop}, 1997,
4382 and whose most recent description is available at
4383 @url{http://www-users.cs.york.ac.uk/~burns/ravenscar.ps}.
4385 The original definition of the profile was revised at subsequent IRTAW
4386 meetings. It has been included in the ISO
4387 @cite{Guide for the Use of the Ada Programming Language in High
4388 Integrity Systems}, and has been approved by ISO/IEC/SC22/WG9 for inclusion in
4389 the next revision of the standard. The formal definition given by
4390 the Ada Rapporteur Group (ARG) can be found in two Ada Issues (AI-249 and
4391 AI-305) available at
4392 @url{http://www.ada-auth.org/cgi-bin/cvsweb.cgi/ais/ai-00249.txt} and
4393 @url{http://www.ada-auth.org/cgi-bin/cvsweb.cgi/ais/ai-00305.txt}.
4395 The above set is a superset of the restrictions provided by pragma
4396 @code{Profile (Restricted)}, it includes six additional restrictions
4397 (@code{Simple_Barriers}, @code{No_Select_Statements},
4398 @code{No_Calendar}, @code{No_Implicit_Heap_Allocations},
4399 @code{No_Relative_Delay} and @code{No_Task_Termination}). This means
4400 that pragma @code{Profile (Ravenscar)}, like the pragma
4401 @code{Profile (Restricted)},
4402 automatically causes the use of a simplified,
4403 more efficient version of the tasking run-time system.
4405 @node Pragma Profile (Restricted)
4406 @unnumberedsec Pragma Profile (Restricted)
4407 @findex Restricted Run Time
4411 @smallexample @c ada
4412 pragma Profile (Restricted);
4416 A configuration pragma that establishes the following set of restrictions:
4419 @item No_Abort_Statements
4420 @item No_Entry_Queue
4421 @item No_Task_Hierarchy
4422 @item No_Task_Allocators
4423 @item No_Dynamic_Priorities
4424 @item No_Terminate_Alternatives
4425 @item No_Dynamic_Attachment
4426 @item No_Protected_Type_Allocators
4427 @item No_Local_Protected_Objects
4428 @item No_Requeue_Statements
4429 @item No_Task_Attributes_Package
4430 @item Max_Asynchronous_Select_Nesting = 0
4431 @item Max_Task_Entries = 0
4432 @item Max_Protected_Entries = 1
4433 @item Max_Select_Alternatives = 0
4437 This set of restrictions causes the automatic selection of a simplified
4438 version of the run time that provides improved performance for the
4439 limited set of tasking functionality permitted by this set of restrictions.
4441 @node Pragma Psect_Object
4442 @unnumberedsec Pragma Psect_Object
4443 @findex Psect_Object
4447 @smallexample @c ada
4448 pragma Psect_Object (
4449 [Internal =>] LOCAL_NAME,
4450 [, [External =>] EXTERNAL_SYMBOL]
4451 [, [Size =>] EXTERNAL_SYMBOL]);
4455 | static_string_EXPRESSION
4459 This pragma is identical in effect to pragma @code{Common_Object}.
4461 @node Pragma Pure_Function
4462 @unnumberedsec Pragma Pure_Function
4463 @findex Pure_Function
4467 @smallexample @c ada
4468 pragma Pure_Function ([Entity =>] function_LOCAL_NAME);
4472 This pragma appears in the same declarative part as a function
4473 declaration (or a set of function declarations if more than one
4474 overloaded declaration exists, in which case the pragma applies
4475 to all entities). It specifies that the function @code{Entity} is
4476 to be considered pure for the purposes of code generation. This means
4477 that the compiler can assume that there are no side effects, and
4478 in particular that two calls with identical arguments produce the
4479 same result. It also means that the function can be used in an
4482 Note that, quite deliberately, there are no static checks to try
4483 to ensure that this promise is met, so @code{Pure_Function} can be used
4484 with functions that are conceptually pure, even if they do modify
4485 global variables. For example, a square root function that is
4486 instrumented to count the number of times it is called is still
4487 conceptually pure, and can still be optimized, even though it
4488 modifies a global variable (the count). Memo functions are another
4489 example (where a table of previous calls is kept and consulted to
4490 avoid re-computation).
4492 Note also that the normal rules excluding optimization of subprograms
4493 in pure units (when parameter types are descended from System.Address,
4494 or when the full view of a parameter type is limited), do not apply
4495 for the Pure_Function case. If you explicitly specify Pure_Function,
4496 the compiler may optimize away calls with identical arguments, and
4497 if that results in unexpected behavior, the proper action is not to
4498 use the pragma for subprograms that are not (conceptually) pure.
4501 Note: Most functions in a @code{Pure} package are automatically pure, and
4502 there is no need to use pragma @code{Pure_Function} for such functions. One
4503 exception is any function that has at least one formal of type
4504 @code{System.Address} or a type derived from it. Such functions are not
4505 considered pure by default, since the compiler assumes that the
4506 @code{Address} parameter may be functioning as a pointer and that the
4507 referenced data may change even if the address value does not.
4508 Similarly, imported functions are not considered to be pure by default,
4509 since there is no way of checking that they are in fact pure. The use
4510 of pragma @code{Pure_Function} for such a function will override these default
4511 assumption, and cause the compiler to treat a designated subprogram as pure
4514 Note: If pragma @code{Pure_Function} is applied to a renamed function, it
4515 applies to the underlying renamed function. This can be used to
4516 disambiguate cases of overloading where some but not all functions
4517 in a set of overloaded functions are to be designated as pure.
4519 If pragma @code{Pure_Function} is applied to a library level function, the
4520 function is also considered pure from an optimization point of view, but the
4521 unit is not a Pure unit in the categorization sense. So for example, a function
4522 thus marked is free to @code{with} non-pure units.
4524 @node Pragma Remote_Access_Type
4525 @unnumberedsec Pragma Remote_Access_Type
4526 @findex Remote_Access_Type
4530 @smallexample @c ada
4531 pragma Remote_Access_Type ([Entity =>] formal_access_type_LOCAL_NAME);
4535 This pragma appears in the formal part of a generic declaration.
4536 It specifies an exception to the RM rule from E.2.2(17/2), which forbids
4537 the use of a remote access to class-wide type as actual for a formal
4540 When this pragma applies to a formal access type @code{Entity}, that
4541 type is treated as a remote access to class-wide type in the generic.
4542 It must be a formal general access type, and its designated type must
4543 be the class-wide type of a formal tagged limited private type from the
4544 same generic declaration.
4546 In the generic unit, the formal type is subject to all restrictions
4547 pertaining to remote access to class-wide types. At instantiation, the
4548 actual type must be a remote access to class-wide type.
4550 @node Pragma Restriction_Warnings
4551 @unnumberedsec Pragma Restriction_Warnings
4552 @findex Restriction_Warnings
4556 @smallexample @c ada
4557 pragma Restriction_Warnings
4558 (restriction_IDENTIFIER @{, restriction_IDENTIFIER@});
4562 This pragma allows a series of restriction identifiers to be
4563 specified (the list of allowed identifiers is the same as for
4564 pragma @code{Restrictions}). For each of these identifiers
4565 the compiler checks for violations of the restriction, but
4566 generates a warning message rather than an error message
4567 if the restriction is violated.
4570 @unnumberedsec Pragma Shared
4574 This pragma is provided for compatibility with Ada 83. The syntax and
4575 semantics are identical to pragma Atomic.
4577 @node Pragma Short_Circuit_And_Or
4578 @unnumberedsec Pragma Short_Circuit_And_Or
4579 @findex Short_Circuit_And_Or
4582 This configuration pragma causes any occurrence of the AND operator applied to
4583 operands of type Standard.Boolean to be short-circuited (i.e. the AND operator
4584 is treated as if it were AND THEN). Or is similarly treated as OR ELSE. This
4585 may be useful in the context of certification protocols requiring the use of
4586 short-circuited logical operators. If this configuration pragma occurs locally
4587 within the file being compiled, it applies only to the file being compiled.
4588 There is no requirement that all units in a partition use this option.
4590 @node Pragma Short_Descriptors
4591 @unnumberedsec Pragma Short_Descriptors
4592 @findex Short_Descriptors
4596 @smallexample @c ada
4597 pragma Short_Descriptors
4601 In VMS versions of the compiler, this configuration pragma causes all
4602 occurrences of the mechanism types Descriptor[_xxx] to be treated as
4603 Short_Descriptor[_xxx]. This is helpful in porting legacy applications from a
4604 32-bit environment to a 64-bit environment. This pragma is ignored for non-VMS
4607 @node Pragma Simple_Storage_Pool_Type
4608 @unnumberedsec Pragma Simple_Storage_Pool_Type
4609 @findex Simple_Storage_Pool_Type
4610 @cindex Storage pool, simple
4611 @cindex Simple storage pool
4615 @smallexample @c ada
4616 pragma Simple_Storage_Pool_Type (type_LOCAL_NAME);
4620 A type can be established as a ``simple storage pool type'' by applying
4621 the representation pragma @code{Simple_Storage_Pool_Type} to the type.
4622 A type named in the pragma must be a library-level immutably limited record
4623 type or limited tagged type declared immediately within a package declaration.
4624 The type can also be a limited private type whose full type is allowed as
4625 a simple storage pool type.
4627 For a simple storage pool type @var{SSP}, nonabstract primitive subprograms
4628 @code{Allocate}, @code{Deallocate}, and @code{Storage_Size} can be declared that
4629 are subtype conformant with the following subprogram declarations:
4631 @smallexample @c ada
4634 Storage_Address : out System.Address;
4635 Size_In_Storage_Elements : System.Storage_Elements.Storage_Count;
4636 Alignment : System.Storage_Elements.Storage_Count);
4638 procedure Deallocate
4640 Storage_Address : System.Address;
4641 Size_In_Storage_Elements : System.Storage_Elements.Storage_Count;
4642 Alignment : System.Storage_Elements.Storage_Count);
4644 function Storage_Size (Pool : SSP)
4645 return System.Storage_Elements.Storage_Count;
4649 Procedure @code{Allocate} must be declared, whereas @code{Deallocate} and
4650 @code{Storage_Size} are optional. If @code{Deallocate} is not declared, then
4651 applying an unchecked deallocation has no effect other than to set its actual
4652 parameter to null. If @code{Storage_Size} is not declared, then the
4653 @code{Storage_Size} attribute applied to an access type associated with
4654 a pool object of type SSP returns zero. Additional operations can be declared
4655 for a simple storage pool type (such as for supporting a mark/release
4656 storage-management discipline).
4658 An object of a simple storage pool type can be associated with an access
4659 type by specifying the attribute @code{Simple_Storage_Pool}. For example:
4661 @smallexample @c ada
4663 My_Pool : My_Simple_Storage_Pool_Type;
4665 type Acc is access My_Data_Type;
4667 for Acc'Simple_Storage_Pool use My_Pool;
4672 See attribute @code{Simple_Storage_Pool} for further details.
4674 @node Pragma Source_File_Name
4675 @unnumberedsec Pragma Source_File_Name
4676 @findex Source_File_Name
4680 @smallexample @c ada
4681 pragma Source_File_Name (
4682 [Unit_Name =>] unit_NAME,
4683 Spec_File_Name => STRING_LITERAL,
4684 [Index => INTEGER_LITERAL]);
4686 pragma Source_File_Name (
4687 [Unit_Name =>] unit_NAME,
4688 Body_File_Name => STRING_LITERAL,
4689 [Index => INTEGER_LITERAL]);
4693 Use this to override the normal naming convention. It is a configuration
4694 pragma, and so has the usual applicability of configuration pragmas
4695 (i.e.@: it applies to either an entire partition, or to all units in a
4696 compilation, or to a single unit, depending on how it is used.
4697 @var{unit_name} is mapped to @var{file_name_literal}. The identifier for
4698 the second argument is required, and indicates whether this is the file
4699 name for the spec or for the body.
4701 The optional Index argument should be used when a file contains multiple
4702 units, and when you do not want to use @code{gnatchop} to separate then
4703 into multiple files (which is the recommended procedure to limit the
4704 number of recompilations that are needed when some sources change).
4705 For instance, if the source file @file{source.ada} contains
4707 @smallexample @c ada
4719 you could use the following configuration pragmas:
4721 @smallexample @c ada
4722 pragma Source_File_Name
4723 (B, Spec_File_Name => "source.ada", Index => 1);
4724 pragma Source_File_Name
4725 (A, Body_File_Name => "source.ada", Index => 2);
4728 Note that the @code{gnatname} utility can also be used to generate those
4729 configuration pragmas.
4731 Another form of the @code{Source_File_Name} pragma allows
4732 the specification of patterns defining alternative file naming schemes
4733 to apply to all files.
4735 @smallexample @c ada
4736 pragma Source_File_Name
4737 ( [Spec_File_Name =>] STRING_LITERAL
4738 [,[Casing =>] CASING_SPEC]
4739 [,[Dot_Replacement =>] STRING_LITERAL]);
4741 pragma Source_File_Name
4742 ( [Body_File_Name =>] STRING_LITERAL
4743 [,[Casing =>] CASING_SPEC]
4744 [,[Dot_Replacement =>] STRING_LITERAL]);
4746 pragma Source_File_Name
4747 ( [Subunit_File_Name =>] STRING_LITERAL
4748 [,[Casing =>] CASING_SPEC]
4749 [,[Dot_Replacement =>] STRING_LITERAL]);
4751 CASING_SPEC ::= Lowercase | Uppercase | Mixedcase
4755 The first argument is a pattern that contains a single asterisk indicating
4756 the point at which the unit name is to be inserted in the pattern string
4757 to form the file name. The second argument is optional. If present it
4758 specifies the casing of the unit name in the resulting file name string.
4759 The default is lower case. Finally the third argument allows for systematic
4760 replacement of any dots in the unit name by the specified string literal.
4762 Note that Source_File_Name pragmas should not be used if you are using
4763 project files. The reason for this rule is that the project manager is not
4764 aware of these pragmas, and so other tools that use the projet file would not
4765 be aware of the intended naming conventions. If you are using project files,
4766 file naming is controlled by Source_File_Name_Project pragmas, which are
4767 usually supplied automatically by the project manager. A pragma
4768 Source_File_Name cannot appear after a @ref{Pragma Source_File_Name_Project}.
4770 For more details on the use of the @code{Source_File_Name} pragma,
4771 @xref{Using Other File Names,,, gnat_ugn, @value{EDITION} User's Guide},
4772 and @ref{Alternative File Naming Schemes,,, gnat_ugn, @value{EDITION}
4775 @node Pragma Source_File_Name_Project
4776 @unnumberedsec Pragma Source_File_Name_Project
4777 @findex Source_File_Name_Project
4780 This pragma has the same syntax and semantics as pragma Source_File_Name.
4781 It is only allowed as a stand alone configuration pragma.
4782 It cannot appear after a @ref{Pragma Source_File_Name}, and
4783 most importantly, once pragma Source_File_Name_Project appears,
4784 no further Source_File_Name pragmas are allowed.
4786 The intention is that Source_File_Name_Project pragmas are always
4787 generated by the Project Manager in a manner consistent with the naming
4788 specified in a project file, and when naming is controlled in this manner,
4789 it is not permissible to attempt to modify this naming scheme using
4790 Source_File_Name or Source_File_Name_Project pragmas (which would not be
4791 known to the project manager).
4793 @node Pragma Source_Reference
4794 @unnumberedsec Pragma Source_Reference
4795 @findex Source_Reference
4799 @smallexample @c ada
4800 pragma Source_Reference (INTEGER_LITERAL, STRING_LITERAL);
4804 This pragma must appear as the first line of a source file.
4805 @var{integer_literal} is the logical line number of the line following
4806 the pragma line (for use in error messages and debugging
4807 information). @var{string_literal} is a static string constant that
4808 specifies the file name to be used in error messages and debugging
4809 information. This is most notably used for the output of @code{gnatchop}
4810 with the @option{-r} switch, to make sure that the original unchopped
4811 source file is the one referred to.
4813 The second argument must be a string literal, it cannot be a static
4814 string expression other than a string literal. This is because its value
4815 is needed for error messages issued by all phases of the compiler.
4817 @node Pragma Static_Elaboration_Desired
4818 @unnumberedsec Pragma Static_Elaboration_Desired
4819 @findex Static_Elaboration_Desired
4823 @smallexample @c ada
4824 pragma Static_Elaboration_Desired;
4828 This pragma is used to indicate that the compiler should attempt to initialize
4829 statically the objects declared in the library unit to which the pragma applies,
4830 when these objects are initialized (explicitly or implicitly) by an aggregate.
4831 In the absence of this pragma, aggregates in object declarations are expanded
4832 into assignments and loops, even when the aggregate components are static
4833 constants. When the aggregate is present the compiler builds a static expression
4834 that requires no run-time code, so that the initialized object can be placed in
4835 read-only data space. If the components are not static, or the aggregate has
4836 more that 100 components, the compiler emits a warning that the pragma cannot
4837 be obeyed. (See also the restriction No_Implicit_Loops, which supports static
4838 construction of larger aggregates with static components that include an others
4841 @node Pragma Stream_Convert
4842 @unnumberedsec Pragma Stream_Convert
4843 @findex Stream_Convert
4847 @smallexample @c ada
4848 pragma Stream_Convert (
4849 [Entity =>] type_LOCAL_NAME,
4850 [Read =>] function_NAME,
4851 [Write =>] function_NAME);
4855 This pragma provides an efficient way of providing stream functions for
4856 types defined in packages. Not only is it simpler to use than declaring
4857 the necessary functions with attribute representation clauses, but more
4858 significantly, it allows the declaration to made in such a way that the
4859 stream packages are not loaded unless they are needed. The use of
4860 the Stream_Convert pragma adds no overhead at all, unless the stream
4861 attributes are actually used on the designated type.
4863 The first argument specifies the type for which stream functions are
4864 provided. The second parameter provides a function used to read values
4865 of this type. It must name a function whose argument type may be any
4866 subtype, and whose returned type must be the type given as the first
4867 argument to the pragma.
4869 The meaning of the @var{Read}
4870 parameter is that if a stream attribute directly
4871 or indirectly specifies reading of the type given as the first parameter,
4872 then a value of the type given as the argument to the Read function is
4873 read from the stream, and then the Read function is used to convert this
4874 to the required target type.
4876 Similarly the @var{Write} parameter specifies how to treat write attributes
4877 that directly or indirectly apply to the type given as the first parameter.
4878 It must have an input parameter of the type specified by the first parameter,
4879 and the return type must be the same as the input type of the Read function.
4880 The effect is to first call the Write function to convert to the given stream
4881 type, and then write the result type to the stream.
4883 The Read and Write functions must not be overloaded subprograms. If necessary
4884 renamings can be supplied to meet this requirement.
4885 The usage of this attribute is best illustrated by a simple example, taken
4886 from the GNAT implementation of package Ada.Strings.Unbounded:
4888 @smallexample @c ada
4889 function To_Unbounded (S : String)
4890 return Unbounded_String
4891 renames To_Unbounded_String;
4893 pragma Stream_Convert
4894 (Unbounded_String, To_Unbounded, To_String);
4898 The specifications of the referenced functions, as given in the Ada
4899 Reference Manual are:
4901 @smallexample @c ada
4902 function To_Unbounded_String (Source : String)
4903 return Unbounded_String;
4905 function To_String (Source : Unbounded_String)
4910 The effect is that if the value of an unbounded string is written to a stream,
4911 then the representation of the item in the stream is in the same format that
4912 would be used for @code{Standard.String'Output}, and this same representation
4913 is expected when a value of this type is read from the stream. Note that the
4914 value written always includes the bounds, even for Unbounded_String'Write,
4915 since Unbounded_String is not an array type.
4917 @node Pragma Style_Checks
4918 @unnumberedsec Pragma Style_Checks
4919 @findex Style_Checks
4923 @smallexample @c ada
4924 pragma Style_Checks (string_LITERAL | ALL_CHECKS |
4925 On | Off [, LOCAL_NAME]);
4929 This pragma is used in conjunction with compiler switches to control the
4930 built in style checking provided by GNAT@. The compiler switches, if set,
4931 provide an initial setting for the switches, and this pragma may be used
4932 to modify these settings, or the settings may be provided entirely by
4933 the use of the pragma. This pragma can be used anywhere that a pragma
4934 is legal, including use as a configuration pragma (including use in
4935 the @file{gnat.adc} file).
4937 The form with a string literal specifies which style options are to be
4938 activated. These are additive, so they apply in addition to any previously
4939 set style check options. The codes for the options are the same as those
4940 used in the @option{-gnaty} switch to @command{gcc} or @command{gnatmake}.
4941 For example the following two methods can be used to enable
4946 @smallexample @c ada
4947 pragma Style_Checks ("l");
4952 gcc -c -gnatyl @dots{}
4957 The form ALL_CHECKS activates all standard checks (its use is equivalent
4958 to the use of the @code{gnaty} switch with no options. @xref{Top,
4959 @value{EDITION} User's Guide, About This Guide, gnat_ugn,
4960 @value{EDITION} User's Guide}, for details.)
4962 Note: the behavior is slightly different in GNAT mode (@option{-gnatg} used).
4963 In this case, ALL_CHECKS implies the standard set of GNAT mode style check
4964 options (i.e. equivalent to -gnatyg).
4966 The forms with @code{Off} and @code{On}
4967 can be used to temporarily disable style checks
4968 as shown in the following example:
4970 @smallexample @c ada
4974 pragma Style_Checks ("k"); -- requires keywords in lower case
4975 pragma Style_Checks (Off); -- turn off style checks
4976 NULL; -- this will not generate an error message
4977 pragma Style_Checks (On); -- turn style checks back on
4978 NULL; -- this will generate an error message
4982 Finally the two argument form is allowed only if the first argument is
4983 @code{On} or @code{Off}. The effect is to turn of semantic style checks
4984 for the specified entity, as shown in the following example:
4986 @smallexample @c ada
4990 pragma Style_Checks ("r"); -- require consistency of identifier casing
4992 Rf1 : Integer := ARG; -- incorrect, wrong case
4993 pragma Style_Checks (Off, Arg);
4994 Rf2 : Integer := ARG; -- OK, no error
4997 @node Pragma Subtitle
4998 @unnumberedsec Pragma Subtitle
5003 @smallexample @c ada
5004 pragma Subtitle ([Subtitle =>] STRING_LITERAL);
5008 This pragma is recognized for compatibility with other Ada compilers
5009 but is ignored by GNAT@.
5011 @node Pragma Suppress
5012 @unnumberedsec Pragma Suppress
5017 @smallexample @c ada
5018 pragma Suppress (Identifier [, [On =>] Name]);
5022 This is a standard pragma, and supports all the check names required in
5023 the RM. It is included here because GNAT recognizes one additional check
5024 name: @code{Alignment_Check} which can be used to suppress alignment checks
5025 on addresses used in address clauses. Such checks can also be suppressed
5026 by suppressing range checks, but the specific use of @code{Alignment_Check}
5027 allows suppression of alignment checks without suppressing other range checks.
5029 Note that pragma Suppress gives the compiler permission to omit
5030 checks, but does not require the compiler to omit checks. The compiler
5031 will generate checks if they are essentially free, even when they are
5032 suppressed. In particular, if the compiler can prove that a certain
5033 check will necessarily fail, it will generate code to do an
5034 unconditional ``raise'', even if checks are suppressed. The compiler
5037 Of course, run-time checks are omitted whenever the compiler can prove
5038 that they will not fail, whether or not checks are suppressed.
5040 @node Pragma Suppress_All
5041 @unnumberedsec Pragma Suppress_All
5042 @findex Suppress_All
5046 @smallexample @c ada
5047 pragma Suppress_All;
5051 This pragma can appear anywhere within a unit.
5052 The effect is to apply @code{Suppress (All_Checks)} to the unit
5053 in which it appears. This pragma is implemented for compatibility with DEC
5054 Ada 83 usage where it appears at the end of a unit, and for compatibility
5055 with Rational Ada, where it appears as a program unit pragma.
5056 The use of the standard Ada pragma @code{Suppress (All_Checks)}
5057 as a normal configuration pragma is the preferred usage in GNAT@.
5059 @node Pragma Suppress_Exception_Locations
5060 @unnumberedsec Pragma Suppress_Exception_Locations
5061 @findex Suppress_Exception_Locations
5065 @smallexample @c ada
5066 pragma Suppress_Exception_Locations;
5070 In normal mode, a raise statement for an exception by default generates
5071 an exception message giving the file name and line number for the location
5072 of the raise. This is useful for debugging and logging purposes, but this
5073 entails extra space for the strings for the messages. The configuration
5074 pragma @code{Suppress_Exception_Locations} can be used to suppress the
5075 generation of these strings, with the result that space is saved, but the
5076 exception message for such raises is null. This configuration pragma may
5077 appear in a global configuration pragma file, or in a specific unit as
5078 usual. It is not required that this pragma be used consistently within
5079 a partition, so it is fine to have some units within a partition compiled
5080 with this pragma and others compiled in normal mode without it.
5082 @node Pragma Suppress_Initialization
5083 @unnumberedsec Pragma Suppress_Initialization
5084 @findex Suppress_Initialization
5085 @cindex Suppressing initialization
5086 @cindex Initialization, suppression of
5090 @smallexample @c ada
5091 pragma Suppress_Initialization ([Entity =>] subtype_Name);
5095 Here subtype_Name is the name introduced by a type declaration
5096 or subtype declaration.
5097 This pragma suppresses any implicit or explicit initialization
5098 for all variables of the given type or subtype,
5099 including initialization resulting from the use of pragmas
5100 Normalize_Scalars or Initialize_Scalars.
5102 This is considered a representation item, so it cannot be given after
5103 the type is frozen. It applies to all subsequent object declarations,
5104 and also any allocator that creates objects of the type.
5106 If the pragma is given for the first subtype, then it is considered
5107 to apply to the base type and all its subtypes. If the pragma is given
5108 for other than a first subtype, then it applies only to the given subtype.
5109 The pragma may not be given after the type is frozen.
5111 @node Pragma Task_Info
5112 @unnumberedsec Pragma Task_Info
5117 @smallexample @c ada
5118 pragma Task_Info (EXPRESSION);
5122 This pragma appears within a task definition (like pragma
5123 @code{Priority}) and applies to the task in which it appears. The
5124 argument must be of type @code{System.Task_Info.Task_Info_Type}.
5125 The @code{Task_Info} pragma provides system dependent control over
5126 aspects of tasking implementation, for example, the ability to map
5127 tasks to specific processors. For details on the facilities available
5128 for the version of GNAT that you are using, see the documentation
5129 in the spec of package System.Task_Info in the runtime
5132 @node Pragma Task_Name
5133 @unnumberedsec Pragma Task_Name
5138 @smallexample @c ada
5139 pragma Task_Name (string_EXPRESSION);
5143 This pragma appears within a task definition (like pragma
5144 @code{Priority}) and applies to the task in which it appears. The
5145 argument must be of type String, and provides a name to be used for
5146 the task instance when the task is created. Note that this expression
5147 is not required to be static, and in particular, it can contain
5148 references to task discriminants. This facility can be used to
5149 provide different names for different tasks as they are created,
5150 as illustrated in the example below.
5152 The task name is recorded internally in the run-time structures
5153 and is accessible to tools like the debugger. In addition the
5154 routine @code{Ada.Task_Identification.Image} will return this
5155 string, with a unique task address appended.
5157 @smallexample @c ada
5158 -- Example of the use of pragma Task_Name
5160 with Ada.Task_Identification;
5161 use Ada.Task_Identification;
5162 with Text_IO; use Text_IO;
5165 type Astring is access String;
5167 task type Task_Typ (Name : access String) is
5168 pragma Task_Name (Name.all);
5171 task body Task_Typ is
5172 Nam : constant String := Image (Current_Task);
5174 Put_Line ("-->" & Nam (1 .. 14) & "<--");
5177 type Ptr_Task is access Task_Typ;
5178 Task_Var : Ptr_Task;
5182 new Task_Typ (new String'("This is task 1"));
5184 new Task_Typ (new String'("This is task 2"));
5188 @node Pragma Task_Storage
5189 @unnumberedsec Pragma Task_Storage
5190 @findex Task_Storage
5193 @smallexample @c ada
5194 pragma Task_Storage (
5195 [Task_Type =>] LOCAL_NAME,
5196 [Top_Guard =>] static_integer_EXPRESSION);
5200 This pragma specifies the length of the guard area for tasks. The guard
5201 area is an additional storage area allocated to a task. A value of zero
5202 means that either no guard area is created or a minimal guard area is
5203 created, depending on the target. This pragma can appear anywhere a
5204 @code{Storage_Size} attribute definition clause is allowed for a task
5207 @node Pragma Test_Case
5208 @unnumberedsec Pragma Test_Case
5214 @smallexample @c ada
5216 [Name =>] static_string_Expression
5217 ,[Mode =>] (Nominal | Robustness)
5218 [, Requires => Boolean_Expression]
5219 [, Ensures => Boolean_Expression]);
5223 The @code{Test_Case} pragma allows defining fine-grain specifications
5224 for use by testing and verification tools. The compiler checks its
5225 validity but the presence of pragma @code{Test_Case} does not lead to
5226 any modification of the code generated by the compiler.
5228 @code{Test_Case} pragmas may only appear immediately following the
5229 (separate) declaration of a subprogram in a package declaration, inside
5230 a package spec unit. Only other pragmas may intervene (that is appear
5231 between the subprogram declaration and a test case).
5233 The compiler checks that boolean expressions given in @code{Requires} and
5234 @code{Ensures} are valid, where the rules for @code{Requires} are the
5235 same as the rule for an expression in @code{Precondition} and the rules
5236 for @code{Ensures} are the same as the rule for an expression in
5237 @code{Postcondition}. In particular, attributes @code{'Old} and
5238 @code{'Result} can only be used within the @code{Ensures}
5239 expression. The following is an example of use within a package spec:
5241 @smallexample @c ada
5242 package Math_Functions is
5244 function Sqrt (Arg : Float) return Float;
5245 pragma Test_Case (Name => "Test 1",
5247 Requires => Arg < 100,
5248 Ensures => Sqrt'Result < 10);
5254 The meaning of a test case is that, if the associated subprogram is
5255 executed in a context where @code{Requires} holds, then @code{Ensures}
5256 should hold when the subprogram returns. Mode @code{Nominal} indicates
5257 that the input context should satisfy the precondition of the
5258 subprogram, and the output context should then satisfy its
5259 postcondition. More @code{Robustness} indicates that the pre- and
5260 postcondition of the subprogram should be ignored for this test case.
5262 @node Pragma Thread_Local_Storage
5263 @unnumberedsec Pragma Thread_Local_Storage
5264 @findex Thread_Local_Storage
5265 @cindex Task specific storage
5266 @cindex TLS (Thread Local Storage)
5269 @smallexample @c ada
5270 pragma Thread_Local_Storage ([Entity =>] LOCAL_NAME);
5274 This pragma specifies that the specified entity, which must be
5275 a variable declared in a library level package, is to be marked as
5276 "Thread Local Storage" (@code{TLS}). On systems supporting this (which
5277 include Solaris, GNU/Linux and VxWorks 6), this causes each thread
5278 (and hence each Ada task) to see a distinct copy of the variable.
5280 The variable may not have default initialization, and if there is
5281 an explicit initialization, it must be either @code{null} for an
5282 access variable, or a static expression for a scalar variable.
5283 This provides a low level mechanism similar to that provided by
5284 the @code{Ada.Task_Attributes} package, but much more efficient
5285 and is also useful in writing interface code that will interact
5286 with foreign threads.
5288 If this pragma is used on a system where @code{TLS} is not supported,
5289 then an error message will be generated and the program will be rejected.
5291 @node Pragma Time_Slice
5292 @unnumberedsec Pragma Time_Slice
5297 @smallexample @c ada
5298 pragma Time_Slice (static_duration_EXPRESSION);
5302 For implementations of GNAT on operating systems where it is possible
5303 to supply a time slice value, this pragma may be used for this purpose.
5304 It is ignored if it is used in a system that does not allow this control,
5305 or if it appears in other than the main program unit.
5307 Note that the effect of this pragma is identical to the effect of the
5308 DEC Ada 83 pragma of the same name when operating under OpenVMS systems.
5311 @unnumberedsec Pragma Title
5316 @smallexample @c ada
5317 pragma Title (TITLING_OPTION [, TITLING OPTION]);
5320 [Title =>] STRING_LITERAL,
5321 | [Subtitle =>] STRING_LITERAL
5325 Syntax checked but otherwise ignored by GNAT@. This is a listing control
5326 pragma used in DEC Ada 83 implementations to provide a title and/or
5327 subtitle for the program listing. The program listing generated by GNAT
5328 does not have titles or subtitles.
5330 Unlike other pragmas, the full flexibility of named notation is allowed
5331 for this pragma, i.e.@: the parameters may be given in any order if named
5332 notation is used, and named and positional notation can be mixed
5333 following the normal rules for procedure calls in Ada.
5335 @node Pragma Unchecked_Union
5336 @unnumberedsec Pragma Unchecked_Union
5338 @findex Unchecked_Union
5342 @smallexample @c ada
5343 pragma Unchecked_Union (first_subtype_LOCAL_NAME);
5347 This pragma is used to specify a representation of a record type that is
5348 equivalent to a C union. It was introduced as a GNAT implementation defined
5349 pragma in the GNAT Ada 95 mode. Ada 2005 includes an extended version of this
5350 pragma, making it language defined, and GNAT fully implements this extended
5351 version in all language modes (Ada 83, Ada 95, and Ada 2005). For full
5352 details, consult the Ada 2005 Reference Manual, section B.3.3.
5354 @node Pragma Unimplemented_Unit
5355 @unnumberedsec Pragma Unimplemented_Unit
5356 @findex Unimplemented_Unit
5360 @smallexample @c ada
5361 pragma Unimplemented_Unit;
5365 If this pragma occurs in a unit that is processed by the compiler, GNAT
5366 aborts with the message @samp{@var{xxx} not implemented}, where
5367 @var{xxx} is the name of the current compilation unit. This pragma is
5368 intended to allow the compiler to handle unimplemented library units in
5371 The abort only happens if code is being generated. Thus you can use
5372 specs of unimplemented packages in syntax or semantic checking mode.
5374 @node Pragma Universal_Aliasing
5375 @unnumberedsec Pragma Universal_Aliasing
5376 @findex Universal_Aliasing
5380 @smallexample @c ada
5381 pragma Universal_Aliasing [([Entity =>] type_LOCAL_NAME)];
5385 @var{type_LOCAL_NAME} must refer to a type declaration in the current
5386 declarative part. The effect is to inhibit strict type-based aliasing
5387 optimization for the given type. In other words, the effect is as though
5388 access types designating this type were subject to pragma No_Strict_Aliasing.
5389 For a detailed description of the strict aliasing optimization, and the
5390 situations in which it must be suppressed, @xref{Optimization and Strict
5391 Aliasing,,, gnat_ugn, @value{EDITION} User's Guide}.
5393 @node Pragma Universal_Data
5394 @unnumberedsec Pragma Universal_Data
5395 @findex Universal_Data
5399 @smallexample @c ada
5400 pragma Universal_Data [(library_unit_Name)];
5404 This pragma is supported only for the AAMP target and is ignored for
5405 other targets. The pragma specifies that all library-level objects
5406 (Counter 0 data) associated with the library unit are to be accessed
5407 and updated using universal addressing (24-bit addresses for AAMP5)
5408 rather than the default of 16-bit Data Environment (DENV) addressing.
5409 Use of this pragma will generally result in less efficient code for
5410 references to global data associated with the library unit, but
5411 allows such data to be located anywhere in memory. This pragma is
5412 a library unit pragma, but can also be used as a configuration pragma
5413 (including use in the @file{gnat.adc} file). The functionality
5414 of this pragma is also available by applying the -univ switch on the
5415 compilations of units where universal addressing of the data is desired.
5417 @node Pragma Unmodified
5418 @unnumberedsec Pragma Unmodified
5420 @cindex Warnings, unmodified
5424 @smallexample @c ada
5425 pragma Unmodified (LOCAL_NAME @{, LOCAL_NAME@});
5429 This pragma signals that the assignable entities (variables,
5430 @code{out} parameters, @code{in out} parameters) whose names are listed are
5431 deliberately not assigned in the current source unit. This
5432 suppresses warnings about the
5433 entities being referenced but not assigned, and in addition a warning will be
5434 generated if one of these entities is in fact assigned in the
5435 same unit as the pragma (or in the corresponding body, or one
5438 This is particularly useful for clearly signaling that a particular
5439 parameter is not modified, even though the spec suggests that it might
5442 @node Pragma Unreferenced
5443 @unnumberedsec Pragma Unreferenced
5444 @findex Unreferenced
5445 @cindex Warnings, unreferenced
5449 @smallexample @c ada
5450 pragma Unreferenced (LOCAL_NAME @{, LOCAL_NAME@});
5451 pragma Unreferenced (library_unit_NAME @{, library_unit_NAME@});
5455 This pragma signals that the entities whose names are listed are
5456 deliberately not referenced in the current source unit. This
5457 suppresses warnings about the
5458 entities being unreferenced, and in addition a warning will be
5459 generated if one of these entities is in fact subsequently referenced in the
5460 same unit as the pragma (or in the corresponding body, or one
5463 This is particularly useful for clearly signaling that a particular
5464 parameter is not referenced in some particular subprogram implementation
5465 and that this is deliberate. It can also be useful in the case of
5466 objects declared only for their initialization or finalization side
5469 If @code{LOCAL_NAME} identifies more than one matching homonym in the
5470 current scope, then the entity most recently declared is the one to which
5471 the pragma applies. Note that in the case of accept formals, the pragma
5472 Unreferenced may appear immediately after the keyword @code{do} which
5473 allows the indication of whether or not accept formals are referenced
5474 or not to be given individually for each accept statement.
5476 The left hand side of an assignment does not count as a reference for the
5477 purpose of this pragma. Thus it is fine to assign to an entity for which
5478 pragma Unreferenced is given.
5480 Note that if a warning is desired for all calls to a given subprogram,
5481 regardless of whether they occur in the same unit as the subprogram
5482 declaration, then this pragma should not be used (calls from another
5483 unit would not be flagged); pragma Obsolescent can be used instead
5484 for this purpose, see @xref{Pragma Obsolescent}.
5486 The second form of pragma @code{Unreferenced} is used within a context
5487 clause. In this case the arguments must be unit names of units previously
5488 mentioned in @code{with} clauses (similar to the usage of pragma
5489 @code{Elaborate_All}. The effect is to suppress warnings about unreferenced
5490 units and unreferenced entities within these units.
5492 @node Pragma Unreferenced_Objects
5493 @unnumberedsec Pragma Unreferenced_Objects
5494 @findex Unreferenced_Objects
5495 @cindex Warnings, unreferenced
5499 @smallexample @c ada
5500 pragma Unreferenced_Objects (local_subtype_NAME @{, local_subtype_NAME@});
5504 This pragma signals that for the types or subtypes whose names are
5505 listed, objects which are declared with one of these types or subtypes may
5506 not be referenced, and if no references appear, no warnings are given.
5508 This is particularly useful for objects which are declared solely for their
5509 initialization and finalization effect. Such variables are sometimes referred
5510 to as RAII variables (Resource Acquisition Is Initialization). Using this
5511 pragma on the relevant type (most typically a limited controlled type), the
5512 compiler will automatically suppress unwanted warnings about these variables
5513 not being referenced.
5515 @node Pragma Unreserve_All_Interrupts
5516 @unnumberedsec Pragma Unreserve_All_Interrupts
5517 @findex Unreserve_All_Interrupts
5521 @smallexample @c ada
5522 pragma Unreserve_All_Interrupts;
5526 Normally certain interrupts are reserved to the implementation. Any attempt
5527 to attach an interrupt causes Program_Error to be raised, as described in
5528 RM C.3.2(22). A typical example is the @code{SIGINT} interrupt used in
5529 many systems for a @kbd{Ctrl-C} interrupt. Normally this interrupt is
5530 reserved to the implementation, so that @kbd{Ctrl-C} can be used to
5531 interrupt execution.
5533 If the pragma @code{Unreserve_All_Interrupts} appears anywhere in any unit in
5534 a program, then all such interrupts are unreserved. This allows the
5535 program to handle these interrupts, but disables their standard
5536 functions. For example, if this pragma is used, then pressing
5537 @kbd{Ctrl-C} will not automatically interrupt execution. However,
5538 a program can then handle the @code{SIGINT} interrupt as it chooses.
5540 For a full list of the interrupts handled in a specific implementation,
5541 see the source code for the spec of @code{Ada.Interrupts.Names} in
5542 file @file{a-intnam.ads}. This is a target dependent file that contains the
5543 list of interrupts recognized for a given target. The documentation in
5544 this file also specifies what interrupts are affected by the use of
5545 the @code{Unreserve_All_Interrupts} pragma.
5547 For a more general facility for controlling what interrupts can be
5548 handled, see pragma @code{Interrupt_State}, which subsumes the functionality
5549 of the @code{Unreserve_All_Interrupts} pragma.
5551 @node Pragma Unsuppress
5552 @unnumberedsec Pragma Unsuppress
5557 @smallexample @c ada
5558 pragma Unsuppress (IDENTIFIER [, [On =>] NAME]);
5562 This pragma undoes the effect of a previous pragma @code{Suppress}. If
5563 there is no corresponding pragma @code{Suppress} in effect, it has no
5564 effect. The range of the effect is the same as for pragma
5565 @code{Suppress}. The meaning of the arguments is identical to that used
5566 in pragma @code{Suppress}.
5568 One important application is to ensure that checks are on in cases where
5569 code depends on the checks for its correct functioning, so that the code
5570 will compile correctly even if the compiler switches are set to suppress
5573 @node Pragma Use_VADS_Size
5574 @unnumberedsec Pragma Use_VADS_Size
5575 @cindex @code{Size}, VADS compatibility
5576 @findex Use_VADS_Size
5580 @smallexample @c ada
5581 pragma Use_VADS_Size;
5585 This is a configuration pragma. In a unit to which it applies, any use
5586 of the 'Size attribute is automatically interpreted as a use of the
5587 'VADS_Size attribute. Note that this may result in incorrect semantic
5588 processing of valid Ada 95 or Ada 2005 programs. This is intended to aid in
5589 the handling of existing code which depends on the interpretation of Size
5590 as implemented in the VADS compiler. See description of the VADS_Size
5591 attribute for further details.
5593 @node Pragma Validity_Checks
5594 @unnumberedsec Pragma Validity_Checks
5595 @findex Validity_Checks
5599 @smallexample @c ada
5600 pragma Validity_Checks (string_LITERAL | ALL_CHECKS | On | Off);
5604 This pragma is used in conjunction with compiler switches to control the
5605 built-in validity checking provided by GNAT@. The compiler switches, if set
5606 provide an initial setting for the switches, and this pragma may be used
5607 to modify these settings, or the settings may be provided entirely by
5608 the use of the pragma. This pragma can be used anywhere that a pragma
5609 is legal, including use as a configuration pragma (including use in
5610 the @file{gnat.adc} file).
5612 The form with a string literal specifies which validity options are to be
5613 activated. The validity checks are first set to include only the default
5614 reference manual settings, and then a string of letters in the string
5615 specifies the exact set of options required. The form of this string
5616 is exactly as described for the @option{-gnatVx} compiler switch (see the
5617 GNAT users guide for details). For example the following two methods
5618 can be used to enable validity checking for mode @code{in} and
5619 @code{in out} subprogram parameters:
5623 @smallexample @c ada
5624 pragma Validity_Checks ("im");
5629 gcc -c -gnatVim @dots{}
5634 The form ALL_CHECKS activates all standard checks (its use is equivalent
5635 to the use of the @code{gnatva} switch.
5637 The forms with @code{Off} and @code{On}
5638 can be used to temporarily disable validity checks
5639 as shown in the following example:
5641 @smallexample @c ada
5645 pragma Validity_Checks ("c"); -- validity checks for copies
5646 pragma Validity_Checks (Off); -- turn off validity checks
5647 A := B; -- B will not be validity checked
5648 pragma Validity_Checks (On); -- turn validity checks back on
5649 A := C; -- C will be validity checked
5652 @node Pragma Volatile
5653 @unnumberedsec Pragma Volatile
5658 @smallexample @c ada
5659 pragma Volatile (LOCAL_NAME);
5663 This pragma is defined by the Ada Reference Manual, and the GNAT
5664 implementation is fully conformant with this definition. The reason it
5665 is mentioned in this section is that a pragma of the same name was supplied
5666 in some Ada 83 compilers, including DEC Ada 83. The Ada 95 / Ada 2005
5667 implementation of pragma Volatile is upwards compatible with the
5668 implementation in DEC Ada 83.
5670 @node Pragma Warnings
5671 @unnumberedsec Pragma Warnings
5676 @smallexample @c ada
5677 pragma Warnings (On | Off);
5678 pragma Warnings (On | Off, LOCAL_NAME);
5679 pragma Warnings (static_string_EXPRESSION);
5680 pragma Warnings (On | Off, static_string_EXPRESSION);
5684 Normally warnings are enabled, with the output being controlled by
5685 the command line switch. Warnings (@code{Off}) turns off generation of
5686 warnings until a Warnings (@code{On}) is encountered or the end of the
5687 current unit. If generation of warnings is turned off using this
5688 pragma, then no warning messages are output, regardless of the
5689 setting of the command line switches.
5691 The form with a single argument may be used as a configuration pragma.
5693 If the @var{LOCAL_NAME} parameter is present, warnings are suppressed for
5694 the specified entity. This suppression is effective from the point where
5695 it occurs till the end of the extended scope of the variable (similar to
5696 the scope of @code{Suppress}).
5698 The form with a single static_string_EXPRESSION argument provides more precise
5699 control over which warnings are active. The string is a list of letters
5700 specifying which warnings are to be activated and which deactivated. The
5701 code for these letters is the same as the string used in the command
5702 line switch controlling warnings. For a brief summary, use the gnatmake
5703 command with no arguments, which will generate usage information containing
5704 the list of warnings switches supported. For
5705 full details see @ref{Warning Message Control,,, gnat_ugn, @value{EDITION}
5709 The specified warnings will be in effect until the end of the program
5710 or another pragma Warnings is encountered. The effect of the pragma is
5711 cumulative. Initially the set of warnings is the standard default set
5712 as possibly modified by compiler switches. Then each pragma Warning
5713 modifies this set of warnings as specified. This form of the pragma may
5714 also be used as a configuration pragma.
5716 The fourth form, with an @code{On|Off} parameter and a string, is used to
5717 control individual messages, based on their text. The string argument
5718 is a pattern that is used to match against the text of individual
5719 warning messages (not including the initial "warning: " tag).
5721 The pattern may contain asterisks, which match zero or more characters in
5722 the message. For example, you can use
5723 @code{pragma Warnings (Off, "*bits of*unused")} to suppress the warning
5724 message @code{warning: 960 bits of "a" unused}. No other regular
5725 expression notations are permitted. All characters other than asterisk in
5726 these three specific cases are treated as literal characters in the match.
5728 There are two ways to use the pragma in this form. The OFF form can be used as a
5729 configuration pragma. The effect is to suppress all warnings (if any)
5730 that match the pattern string throughout the compilation.
5732 The second usage is to suppress a warning locally, and in this case, two
5733 pragmas must appear in sequence:
5735 @smallexample @c ada
5736 pragma Warnings (Off, Pattern);
5737 @dots{} code where given warning is to be suppressed
5738 pragma Warnings (On, Pattern);
5742 In this usage, the pattern string must match in the Off and On pragmas,
5743 and at least one matching warning must be suppressed.
5745 Note: to write a string that will match any warning, use the string
5746 @code{"***"}. It will not work to use a single asterisk or two asterisks
5747 since this looks like an operator name. This form with three asterisks
5748 is similar in effect to specifying @code{pragma Warnings (Off)} except that a
5749 matching @code{pragma Warnings (On, "***")} will be required. This can be
5750 helpful in avoiding forgetting to turn warnings back on.
5752 Note: the debug flag -gnatd.i (@code{/NOWARNINGS_PRAGMAS} in VMS) can be
5753 used to cause the compiler to entirely ignore all WARNINGS pragmas. This can
5754 be useful in checking whether obsolete pragmas in existing programs are hiding
5757 Note: pragma Warnings does not affect the processing of style messages. See
5758 separate entry for pragma Style_Checks for control of style messages.
5760 @node Pragma Weak_External
5761 @unnumberedsec Pragma Weak_External
5762 @findex Weak_External
5766 @smallexample @c ada
5767 pragma Weak_External ([Entity =>] LOCAL_NAME);
5771 @var{LOCAL_NAME} must refer to an object that is declared at the library
5772 level. This pragma specifies that the given entity should be marked as a
5773 weak symbol for the linker. It is equivalent to @code{__attribute__((weak))}
5774 in GNU C and causes @var{LOCAL_NAME} to be emitted as a weak symbol instead
5775 of a regular symbol, that is to say a symbol that does not have to be
5776 resolved by the linker if used in conjunction with a pragma Import.
5778 When a weak symbol is not resolved by the linker, its address is set to
5779 zero. This is useful in writing interfaces to external modules that may
5780 or may not be linked in the final executable, for example depending on
5781 configuration settings.
5783 If a program references at run time an entity to which this pragma has been
5784 applied, and the corresponding symbol was not resolved at link time, then
5785 the execution of the program is erroneous. It is not erroneous to take the
5786 Address of such an entity, for example to guard potential references,
5787 as shown in the example below.
5789 Some file formats do not support weak symbols so not all target machines
5790 support this pragma.
5792 @smallexample @c ada
5793 -- Example of the use of pragma Weak_External
5795 package External_Module is
5797 pragma Import (C, key);
5798 pragma Weak_External (key);
5799 function Present return boolean;
5800 end External_Module;
5802 with System; use System;
5803 package body External_Module is
5804 function Present return boolean is
5806 return key'Address /= System.Null_Address;
5808 end External_Module;
5811 @node Pragma Wide_Character_Encoding
5812 @unnumberedsec Pragma Wide_Character_Encoding
5813 @findex Wide_Character_Encoding
5817 @smallexample @c ada
5818 pragma Wide_Character_Encoding (IDENTIFIER | CHARACTER_LITERAL);
5822 This pragma specifies the wide character encoding to be used in program
5823 source text appearing subsequently. It is a configuration pragma, but may
5824 also be used at any point that a pragma is allowed, and it is permissible
5825 to have more than one such pragma in a file, allowing multiple encodings
5826 to appear within the same file.
5828 The argument can be an identifier or a character literal. In the identifier
5829 case, it is one of @code{HEX}, @code{UPPER}, @code{SHIFT_JIS},
5830 @code{EUC}, @code{UTF8}, or @code{BRACKETS}. In the character literal
5831 case it is correspondingly one of the characters @samp{h}, @samp{u},
5832 @samp{s}, @samp{e}, @samp{8}, or @samp{b}.
5834 Note that when the pragma is used within a file, it affects only the
5835 encoding within that file, and does not affect withed units, specs,
5838 @node Implementation Defined Attributes
5839 @chapter Implementation Defined Attributes
5840 Ada defines (throughout the Ada reference manual,
5841 summarized in Annex K),
5842 a set of attributes that provide useful additional functionality in all
5843 areas of the language. These language defined attributes are implemented
5844 in GNAT and work as described in the Ada Reference Manual.
5846 In addition, Ada allows implementations to define additional
5847 attributes whose meaning is defined by the implementation. GNAT provides
5848 a number of these implementation-dependent attributes which can be used
5849 to extend and enhance the functionality of the compiler. This section of
5850 the GNAT reference manual describes these additional attributes.
5852 Note that any program using these attributes may not be portable to
5853 other compilers (although GNAT implements this set of attributes on all
5854 platforms). Therefore if portability to other compilers is an important
5855 consideration, you should minimize the use of these attributes.
5865 * Compiler_Version::
5867 * Default_Bit_Order::
5879 * Has_Access_Values::
5880 * Has_Discriminants::
5887 * Max_Interrupt_Priority::
5889 * Maximum_Alignment::
5894 * Passed_By_Reference::
5901 * Simple_Storage_Pool::
5905 * System_Allocator_Alignment::
5911 * Unconstrained_Array::
5912 * Universal_Literal_String::
5913 * Unrestricted_Access::
5921 @unnumberedsec Abort_Signal
5922 @findex Abort_Signal
5924 @code{Standard'Abort_Signal} (@code{Standard} is the only allowed
5925 prefix) provides the entity for the special exception used to signal
5926 task abort or asynchronous transfer of control. Normally this attribute
5927 should only be used in the tasking runtime (it is highly peculiar, and
5928 completely outside the normal semantics of Ada, for a user program to
5929 intercept the abort exception).
5932 @unnumberedsec Address_Size
5933 @cindex Size of @code{Address}
5934 @findex Address_Size
5936 @code{Standard'Address_Size} (@code{Standard} is the only allowed
5937 prefix) is a static constant giving the number of bits in an
5938 @code{Address}. It is the same value as System.Address'Size,
5939 but has the advantage of being static, while a direct
5940 reference to System.Address'Size is non-static because Address
5944 @unnumberedsec Asm_Input
5947 The @code{Asm_Input} attribute denotes a function that takes two
5948 parameters. The first is a string, the second is an expression of the
5949 type designated by the prefix. The first (string) argument is required
5950 to be a static expression, and is the constraint for the parameter,
5951 (e.g.@: what kind of register is required). The second argument is the
5952 value to be used as the input argument. The possible values for the
5953 constant are the same as those used in the RTL, and are dependent on
5954 the configuration file used to built the GCC back end.
5955 @ref{Machine Code Insertions}
5958 @unnumberedsec Asm_Output
5961 The @code{Asm_Output} attribute denotes a function that takes two
5962 parameters. The first is a string, the second is the name of a variable
5963 of the type designated by the attribute prefix. The first (string)
5964 argument is required to be a static expression and designates the
5965 constraint for the parameter (e.g.@: what kind of register is
5966 required). The second argument is the variable to be updated with the
5967 result. The possible values for constraint are the same as those used in
5968 the RTL, and are dependent on the configuration file used to build the
5969 GCC back end. If there are no output operands, then this argument may
5970 either be omitted, or explicitly given as @code{No_Output_Operands}.
5971 @ref{Machine Code Insertions}
5974 @unnumberedsec AST_Entry
5978 This attribute is implemented only in OpenVMS versions of GNAT@. Applied to
5979 the name of an entry, it yields a value of the predefined type AST_Handler
5980 (declared in the predefined package System, as extended by the use of
5981 pragma @code{Extend_System (Aux_DEC)}). This value enables the given entry to
5982 be called when an AST occurs. For further details, refer to the @cite{DEC Ada
5983 Language Reference Manual}, section 9.12a.
5988 @code{@var{obj}'Bit}, where @var{obj} is any object, yields the bit
5989 offset within the storage unit (byte) that contains the first bit of
5990 storage allocated for the object. The value of this attribute is of the
5991 type @code{Universal_Integer}, and is always a non-negative number not
5992 exceeding the value of @code{System.Storage_Unit}.
5994 For an object that is a variable or a constant allocated in a register,
5995 the value is zero. (The use of this attribute does not force the
5996 allocation of a variable to memory).
5998 For an object that is a formal parameter, this attribute applies
5999 to either the matching actual parameter or to a copy of the
6000 matching actual parameter.
6002 For an access object the value is zero. Note that
6003 @code{@var{obj}.all'Bit} is subject to an @code{Access_Check} for the
6004 designated object. Similarly for a record component
6005 @code{@var{X}.@var{C}'Bit} is subject to a discriminant check and
6006 @code{@var{X}(@var{I}).Bit} and @code{@var{X}(@var{I1}..@var{I2})'Bit}
6007 are subject to index checks.
6009 This attribute is designed to be compatible with the DEC Ada 83 definition
6010 and implementation of the @code{Bit} attribute.
6013 @unnumberedsec Bit_Position
6014 @findex Bit_Position
6016 @code{@var{R.C}'Bit_Position}, where @var{R} is a record object and C is one
6017 of the fields of the record type, yields the bit
6018 offset within the record contains the first bit of
6019 storage allocated for the object. The value of this attribute is of the
6020 type @code{Universal_Integer}. The value depends only on the field
6021 @var{C} and is independent of the alignment of
6022 the containing record @var{R}.
6024 @node Compiler_Version
6025 @unnumberedsec Compiler_Version
6026 @findex Compiler_Version
6028 @code{Standard'Compiler_Version} (@code{Standard} is the only allowed
6029 prefix) yields a static string identifying the version of the compiler
6030 being used to compile the unit containing the attribute reference. A
6031 typical result would be something like "@value{EDITION} @i{version} (20090221)".
6034 @unnumberedsec Code_Address
6035 @findex Code_Address
6036 @cindex Subprogram address
6037 @cindex Address of subprogram code
6040 attribute may be applied to subprograms in Ada 95 and Ada 2005, but the
6041 intended effect seems to be to provide
6042 an address value which can be used to call the subprogram by means of
6043 an address clause as in the following example:
6045 @smallexample @c ada
6046 procedure K is @dots{}
6049 for L'Address use K'Address;
6050 pragma Import (Ada, L);
6054 A call to @code{L} is then expected to result in a call to @code{K}@.
6055 In Ada 83, where there were no access-to-subprogram values, this was
6056 a common work-around for getting the effect of an indirect call.
6057 GNAT implements the above use of @code{Address} and the technique
6058 illustrated by the example code works correctly.
6060 However, for some purposes, it is useful to have the address of the start
6061 of the generated code for the subprogram. On some architectures, this is
6062 not necessarily the same as the @code{Address} value described above.
6063 For example, the @code{Address} value may reference a subprogram
6064 descriptor rather than the subprogram itself.
6066 The @code{'Code_Address} attribute, which can only be applied to
6067 subprogram entities, always returns the address of the start of the
6068 generated code of the specified subprogram, which may or may not be
6069 the same value as is returned by the corresponding @code{'Address}
6072 @node Default_Bit_Order
6073 @unnumberedsec Default_Bit_Order
6075 @cindex Little endian
6076 @findex Default_Bit_Order
6078 @code{Standard'Default_Bit_Order} (@code{Standard} is the only
6079 permissible prefix), provides the value @code{System.Default_Bit_Order}
6080 as a @code{Pos} value (0 for @code{High_Order_First}, 1 for
6081 @code{Low_Order_First}). This is used to construct the definition of
6082 @code{Default_Bit_Order} in package @code{System}.
6084 @node Descriptor_Size
6085 @unnumberedsec Descriptor_Size
6088 @findex Descriptor_Size
6090 Non-static attribute @code{Descriptor_Size} returns the size in bits of the
6091 descriptor allocated for a type. The result is non-zero only for unconstrained
6092 array types and the returned value is of type universal integer. In GNAT, an
6093 array descriptor contains bounds information and is located immediately before
6094 the first element of the array.
6096 @smallexample @c ada
6097 type Unconstr_Array is array (Positive range <>) of Boolean;
6098 Put_Line ("Descriptor size = " & Unconstr_Array'Descriptor_Size'Img);
6102 The attribute takes into account any additional padding due to type alignment.
6103 In the example above, the descriptor contains two values of type
6104 @code{Positive} representing the low and high bound. Since @code{Positive} has
6105 a size of 31 bits and an alignment of 4, the descriptor size is @code{2 *
6106 Positive'Size + 2} or 64 bits.
6109 @unnumberedsec Elaborated
6112 The prefix of the @code{'Elaborated} attribute must be a unit name. The
6113 value is a Boolean which indicates whether or not the given unit has been
6114 elaborated. This attribute is primarily intended for internal use by the
6115 generated code for dynamic elaboration checking, but it can also be used
6116 in user programs. The value will always be True once elaboration of all
6117 units has been completed. An exception is for units which need no
6118 elaboration, the value is always False for such units.
6121 @unnumberedsec Elab_Body
6124 This attribute can only be applied to a program unit name. It returns
6125 the entity for the corresponding elaboration procedure for elaborating
6126 the body of the referenced unit. This is used in the main generated
6127 elaboration procedure by the binder and is not normally used in any
6128 other context. However, there may be specialized situations in which it
6129 is useful to be able to call this elaboration procedure from Ada code,
6130 e.g.@: if it is necessary to do selective re-elaboration to fix some
6134 @unnumberedsec Elab_Spec
6137 This attribute can only be applied to a program unit name. It returns
6138 the entity for the corresponding elaboration procedure for elaborating
6139 the spec of the referenced unit. This is used in the main
6140 generated elaboration procedure by the binder and is not normally used
6141 in any other context. However, there may be specialized situations in
6142 which it is useful to be able to call this elaboration procedure from
6143 Ada code, e.g.@: if it is necessary to do selective re-elaboration to fix
6146 @node Elab_Subp_Body
6147 @unnumberedsec Elab_Subp_Body
6148 @findex Elab_Subp_Body
6150 This attribute can only be applied to a library level subprogram
6151 name and is only allowed in CodePeer mode. It returns the entity
6152 for the corresponding elaboration procedure for elaborating the body
6153 of the referenced subprogram unit. This is used in the main generated
6154 elaboration procedure by the binder in CodePeer mode only and is unrecognized
6159 @cindex Ada 83 attributes
6162 The @code{Emax} attribute is provided for compatibility with Ada 83. See
6163 the Ada 83 reference manual for an exact description of the semantics of
6167 @unnumberedsec Enabled
6170 The @code{Enabled} attribute allows an application program to check at compile
6171 time to see if the designated check is currently enabled. The prefix is a
6172 simple identifier, referencing any predefined check name (other than
6173 @code{All_Checks}) or a check name introduced by pragma Check_Name. If
6174 no argument is given for the attribute, the check is for the general state
6175 of the check, if an argument is given, then it is an entity name, and the
6176 check indicates whether an @code{Suppress} or @code{Unsuppress} has been
6177 given naming the entity (if not, then the argument is ignored).
6179 Note that instantiations inherit the check status at the point of the
6180 instantiation, so a useful idiom is to have a library package that
6181 introduces a check name with @code{pragma Check_Name}, and then contains
6182 generic packages or subprograms which use the @code{Enabled} attribute
6183 to see if the check is enabled. A user of this package can then issue
6184 a @code{pragma Suppress} or @code{pragma Unsuppress} before instantiating
6185 the package or subprogram, controlling whether the check will be present.
6188 @unnumberedsec Enum_Rep
6189 @cindex Representation of enums
6192 For every enumeration subtype @var{S}, @code{@var{S}'Enum_Rep} denotes a
6193 function with the following spec:
6195 @smallexample @c ada
6196 function @var{S}'Enum_Rep (Arg : @var{S}'Base)
6197 return @i{Universal_Integer};
6201 It is also allowable to apply @code{Enum_Rep} directly to an object of an
6202 enumeration type or to a non-overloaded enumeration
6203 literal. In this case @code{@var{S}'Enum_Rep} is equivalent to
6204 @code{@var{typ}'Enum_Rep(@var{S})} where @var{typ} is the type of the
6205 enumeration literal or object.
6207 The function returns the representation value for the given enumeration
6208 value. This will be equal to value of the @code{Pos} attribute in the
6209 absence of an enumeration representation clause. This is a static
6210 attribute (i.e.@: the result is static if the argument is static).
6212 @code{@var{S}'Enum_Rep} can also be used with integer types and objects,
6213 in which case it simply returns the integer value. The reason for this
6214 is to allow it to be used for @code{(<>)} discrete formal arguments in
6215 a generic unit that can be instantiated with either enumeration types
6216 or integer types. Note that if @code{Enum_Rep} is used on a modular
6217 type whose upper bound exceeds the upper bound of the largest signed
6218 integer type, and the argument is a variable, so that the universal
6219 integer calculation is done at run time, then the call to @code{Enum_Rep}
6220 may raise @code{Constraint_Error}.
6223 @unnumberedsec Enum_Val
6224 @cindex Representation of enums
6227 For every enumeration subtype @var{S}, @code{@var{S}'Enum_Val} denotes a
6228 function with the following spec:
6230 @smallexample @c ada
6231 function @var{S}'Enum_Val (Arg : @i{Universal_Integer)
6232 return @var{S}'Base};
6236 The function returns the enumeration value whose representation matches the
6237 argument, or raises Constraint_Error if no enumeration literal of the type
6238 has the matching value.
6239 This will be equal to value of the @code{Val} attribute in the
6240 absence of an enumeration representation clause. This is a static
6241 attribute (i.e.@: the result is static if the argument is static).
6244 @unnumberedsec Epsilon
6245 @cindex Ada 83 attributes
6248 The @code{Epsilon} attribute is provided for compatibility with Ada 83. See
6249 the Ada 83 reference manual for an exact description of the semantics of
6253 @unnumberedsec Fixed_Value
6256 For every fixed-point type @var{S}, @code{@var{S}'Fixed_Value} denotes a
6257 function with the following specification:
6259 @smallexample @c ada
6260 function @var{S}'Fixed_Value (Arg : @i{Universal_Integer})
6265 The value returned is the fixed-point value @var{V} such that
6267 @smallexample @c ada
6268 @var{V} = Arg * @var{S}'Small
6272 The effect is thus similar to first converting the argument to the
6273 integer type used to represent @var{S}, and then doing an unchecked
6274 conversion to the fixed-point type. The difference is
6275 that there are full range checks, to ensure that the result is in range.
6276 This attribute is primarily intended for use in implementation of the
6277 input-output functions for fixed-point values.
6279 @node Has_Access_Values
6280 @unnumberedsec Has_Access_Values
6281 @cindex Access values, testing for
6282 @findex Has_Access_Values
6284 The prefix of the @code{Has_Access_Values} attribute is a type. The result
6285 is a Boolean value which is True if the is an access type, or is a composite
6286 type with a component (at any nesting depth) that is an access type, and is
6288 The intended use of this attribute is in conjunction with generic
6289 definitions. If the attribute is applied to a generic private type, it
6290 indicates whether or not the corresponding actual type has access values.
6292 @node Has_Discriminants
6293 @unnumberedsec Has_Discriminants
6294 @cindex Discriminants, testing for
6295 @findex Has_Discriminants
6297 The prefix of the @code{Has_Discriminants} attribute is a type. The result
6298 is a Boolean value which is True if the type has discriminants, and False
6299 otherwise. The intended use of this attribute is in conjunction with generic
6300 definitions. If the attribute is applied to a generic private type, it
6301 indicates whether or not the corresponding actual type has discriminants.
6307 The @code{Img} attribute differs from @code{Image} in that it may be
6308 applied to objects as well as types, in which case it gives the
6309 @code{Image} for the subtype of the object. This is convenient for
6312 @smallexample @c ada
6313 Put_Line ("X = " & X'Img);
6317 has the same meaning as the more verbose:
6319 @smallexample @c ada
6320 Put_Line ("X = " & @var{T}'Image (X));
6324 where @var{T} is the (sub)type of the object @code{X}.
6327 @unnumberedsec Integer_Value
6328 @findex Integer_Value
6330 For every integer type @var{S}, @code{@var{S}'Integer_Value} denotes a
6331 function with the following spec:
6333 @smallexample @c ada
6334 function @var{S}'Integer_Value (Arg : @i{Universal_Fixed})
6339 The value returned is the integer value @var{V}, such that
6341 @smallexample @c ada
6342 Arg = @var{V} * @var{T}'Small
6346 where @var{T} is the type of @code{Arg}.
6347 The effect is thus similar to first doing an unchecked conversion from
6348 the fixed-point type to its corresponding implementation type, and then
6349 converting the result to the target integer type. The difference is
6350 that there are full range checks, to ensure that the result is in range.
6351 This attribute is primarily intended for use in implementation of the
6352 standard input-output functions for fixed-point values.
6355 @unnumberedsec Invalid_Value
6356 @findex Invalid_Value
6358 For every scalar type S, S'Invalid_Value returns an undefined value of the
6359 type. If possible this value is an invalid representation for the type. The
6360 value returned is identical to the value used to initialize an otherwise
6361 uninitialized value of the type if pragma Initialize_Scalars is used,
6362 including the ability to modify the value with the binder -Sxx flag and
6363 relevant environment variables at run time.
6366 @unnumberedsec Large
6367 @cindex Ada 83 attributes
6370 The @code{Large} attribute is provided for compatibility with Ada 83. See
6371 the Ada 83 reference manual for an exact description of the semantics of
6375 @unnumberedsec Machine_Size
6376 @findex Machine_Size
6378 This attribute is identical to the @code{Object_Size} attribute. It is
6379 provided for compatibility with the DEC Ada 83 attribute of this name.
6382 @unnumberedsec Mantissa
6383 @cindex Ada 83 attributes
6386 The @code{Mantissa} attribute is provided for compatibility with Ada 83. See
6387 the Ada 83 reference manual for an exact description of the semantics of
6390 @node Max_Interrupt_Priority
6391 @unnumberedsec Max_Interrupt_Priority
6392 @cindex Interrupt priority, maximum
6393 @findex Max_Interrupt_Priority
6395 @code{Standard'Max_Interrupt_Priority} (@code{Standard} is the only
6396 permissible prefix), provides the same value as
6397 @code{System.Max_Interrupt_Priority}.
6400 @unnumberedsec Max_Priority
6401 @cindex Priority, maximum
6402 @findex Max_Priority
6404 @code{Standard'Max_Priority} (@code{Standard} is the only permissible
6405 prefix) provides the same value as @code{System.Max_Priority}.
6407 @node Maximum_Alignment
6408 @unnumberedsec Maximum_Alignment
6409 @cindex Alignment, maximum
6410 @findex Maximum_Alignment
6412 @code{Standard'Maximum_Alignment} (@code{Standard} is the only
6413 permissible prefix) provides the maximum useful alignment value for the
6414 target. This is a static value that can be used to specify the alignment
6415 for an object, guaranteeing that it is properly aligned in all
6418 @node Mechanism_Code
6419 @unnumberedsec Mechanism_Code
6420 @cindex Return values, passing mechanism
6421 @cindex Parameters, passing mechanism
6422 @findex Mechanism_Code
6424 @code{@var{function}'Mechanism_Code} yields an integer code for the
6425 mechanism used for the result of function, and
6426 @code{@var{subprogram}'Mechanism_Code (@var{n})} yields the mechanism
6427 used for formal parameter number @var{n} (a static integer value with 1
6428 meaning the first parameter) of @var{subprogram}. The code returned is:
6436 by descriptor (default descriptor class)
6438 by descriptor (UBS: unaligned bit string)
6440 by descriptor (UBSB: aligned bit string with arbitrary bounds)
6442 by descriptor (UBA: unaligned bit array)
6444 by descriptor (S: string, also scalar access type parameter)
6446 by descriptor (SB: string with arbitrary bounds)
6448 by descriptor (A: contiguous array)
6450 by descriptor (NCA: non-contiguous array)
6454 Values from 3 through 10 are only relevant to Digital OpenVMS implementations.
6457 @node Null_Parameter
6458 @unnumberedsec Null_Parameter
6459 @cindex Zero address, passing
6460 @findex Null_Parameter
6462 A reference @code{@var{T}'Null_Parameter} denotes an imaginary object of
6463 type or subtype @var{T} allocated at machine address zero. The attribute
6464 is allowed only as the default expression of a formal parameter, or as
6465 an actual expression of a subprogram call. In either case, the
6466 subprogram must be imported.
6468 The identity of the object is represented by the address zero in the
6469 argument list, independent of the passing mechanism (explicit or
6472 This capability is needed to specify that a zero address should be
6473 passed for a record or other composite object passed by reference.
6474 There is no way of indicating this without the @code{Null_Parameter}
6478 @unnumberedsec Object_Size
6479 @cindex Size, used for objects
6482 The size of an object is not necessarily the same as the size of the type
6483 of an object. This is because by default object sizes are increased to be
6484 a multiple of the alignment of the object. For example,
6485 @code{Natural'Size} is
6486 31, but by default objects of type @code{Natural} will have a size of 32 bits.
6487 Similarly, a record containing an integer and a character:
6489 @smallexample @c ada
6497 will have a size of 40 (that is @code{Rec'Size} will be 40). The
6498 alignment will be 4, because of the
6499 integer field, and so the default size of record objects for this type
6500 will be 64 (8 bytes).
6504 @cindex Capturing Old values
6505 @cindex Postconditions
6507 The attribute Prefix'Old can be used within a
6508 subprogram body or within a precondition or
6509 postcondition pragma. The effect is to
6510 refer to the value of the prefix on entry. So for
6511 example if you have an argument of a record type X called Arg1,
6512 you can refer to Arg1.Field'Old which yields the value of
6513 Arg1.Field on entry. The implementation simply involves generating
6514 an object declaration which captures the value on entry.
6515 The prefix must denote an object of a nonlimited type (since limited types
6516 cannot be copied to capture their values) and it must not reference a local
6517 variable (since local variables do not exist at subprogram entry time). Note
6518 that the variable introduced by a quantified expression is a local variable.
6519 The following example shows the use of 'Old to implement
6520 a test of a postcondition:
6522 @smallexample @c ada
6533 package body Old_Pkg is
6534 Count : Natural := 0;
6538 ... code manipulating the value of Count
6540 pragma Assert (Count = Count'Old + 1);
6546 Note that it is allowed to apply 'Old to a constant entity, but this will
6547 result in a warning, since the old and new values will always be the same.
6549 @node Passed_By_Reference
6550 @unnumberedsec Passed_By_Reference
6551 @cindex Parameters, when passed by reference
6552 @findex Passed_By_Reference
6554 @code{@var{type}'Passed_By_Reference} for any subtype @var{type} returns
6555 a value of type @code{Boolean} value that is @code{True} if the type is
6556 normally passed by reference and @code{False} if the type is normally
6557 passed by copy in calls. For scalar types, the result is always @code{False}
6558 and is static. For non-scalar types, the result is non-static.
6561 @unnumberedsec Pool_Address
6562 @cindex Parameters, when passed by reference
6563 @findex Pool_Address
6565 @code{@var{X}'Pool_Address} for any object @var{X} returns the address
6566 of X within its storage pool. This is the same as
6567 @code{@var{X}'Address}, except that for an unconstrained array whose
6568 bounds are allocated just before the first component,
6569 @code{@var{X}'Pool_Address} returns the address of those bounds,
6570 whereas @code{@var{X}'Address} returns the address of the first
6573 Here, we are interpreting ``storage pool'' broadly to mean ``wherever
6574 the object is allocated'', which could be a user-defined storage pool,
6575 the global heap, on the stack, or in a static memory area. For an
6576 object created by @code{new}, @code{@var{Ptr.all}'Pool_Address} is
6577 what is passed to @code{Allocate} and returned from @code{Deallocate}.
6580 @unnumberedsec Range_Length
6581 @findex Range_Length
6583 @code{@var{type}'Range_Length} for any discrete type @var{type} yields
6584 the number of values represented by the subtype (zero for a null
6585 range). The result is static for static subtypes. @code{Range_Length}
6586 applied to the index subtype of a one dimensional array always gives the
6587 same result as @code{Range} applied to the array itself.
6593 The @code{System.Address'Ref}
6594 (@code{System.Address} is the only permissible prefix)
6595 denotes a function identical to
6596 @code{System.Storage_Elements.To_Address} except that
6597 it is a static attribute. See @ref{To_Address} for more details.
6600 @unnumberedsec Result
6603 @code{@var{function}'Result} can only be used with in a Postcondition pragma
6604 for a function. The prefix must be the name of the corresponding function. This
6605 is used to refer to the result of the function in the postcondition expression.
6606 For a further discussion of the use of this attribute and examples of its use,
6607 see the description of pragma Postcondition.
6610 @unnumberedsec Safe_Emax
6611 @cindex Ada 83 attributes
6614 The @code{Safe_Emax} attribute is provided for compatibility with Ada 83. See
6615 the Ada 83 reference manual for an exact description of the semantics of
6619 @unnumberedsec Safe_Large
6620 @cindex Ada 83 attributes
6623 The @code{Safe_Large} attribute is provided for compatibility with Ada 83. See
6624 the Ada 83 reference manual for an exact description of the semantics of
6627 @node Simple_Storage_Pool
6628 @unnumberedsec Simple_Storage_Pool
6629 @cindex Storage pool, simple
6630 @cindex Simple storage pool
6631 @findex Simple_Storage_Pool
6633 For every nonformal, nonderived access-to-object type @var{Acc}, the
6634 representation attribute @code{Simple_Storage_Pool} may be specified
6635 via an attribute_definition_clause (or by specifying the equivalent aspect):
6637 @smallexample @c ada
6639 My_Pool : My_Simple_Storage_Pool_Type;
6641 type Acc is access My_Data_Type;
6643 for Acc'Simple_Storage_Pool use My_Pool;
6648 The name given in an attribute_definition_clause for the
6649 @code{Simple_Storage_Pool} attribute shall denote a variable of
6650 a ``simple storage pool type'' (see pragma @code{Simple_Storage_Pool_Type}).
6652 The use of this attribute is only allowed for a prefix denoting a type
6653 for which it has been specified. The type of the attribute is the type
6654 of the variable specified as the simple storage pool of the access type,
6655 and the attribute denotes that variable.
6657 It is illegal to specify both @code{Storage_Pool} and @code{Simple_Storage_Pool}
6658 for the same access type.
6660 If the @code{Simple_Storage_Pool} attribute has been specified for an access
6661 type, then applying the @code{Storage_Pool} attribute to the type is flagged
6662 with a warning and its evaluation raises the exception @code{Program_Error}.
6664 If the Simple_Storage_Pool attribute has been specified for an access
6665 type @var{S}, then the evaluation of the attribute @code{@var{S}'Storage_Size}
6666 returns the result of calling @code{Storage_Size (@var{S}'Simple_Storage_Pool)},
6667 which is intended to indicate the number of storage elements reserved for
6668 the simple storage pool. If the Storage_Size function has not been defined
6669 for the simple storage pool type, then this attribute returns zero.
6671 If an access type @var{S} has a specified simple storage pool of type
6672 @var{SSP}, then the evaluation of an allocator for that access type calls
6673 the primitive @code{Allocate} procedure for type @var{SSP}, passing
6674 @code{@var{S}'Simple_Storage_Pool} as the pool parameter. The detailed
6675 semantics of such allocators is the same as those defined for allocators
6676 in section 13.11 of the Ada Reference Manual, with the term
6677 ``simple storage pool'' substituted for ``storage pool''.
6679 If an access type @var{S} has a specified simple storage pool of type
6680 @var{SSP}, then a call to an instance of the @code{Ada.Unchecked_Deallocation}
6681 for that access type invokes the primitive @code{Deallocate} procedure
6682 for type @var{SSP}, passing @code{@var{S}'Simple_Storage_Pool} as the pool
6683 parameter. The detailed semantics of such unchecked deallocations is the same
6684 as defined in section 13.11.2 of the Ada Reference Manual, except that the
6685 term ``simple storage pool'' is substituted for ``storage pool''.
6688 @unnumberedsec Small
6689 @cindex Ada 83 attributes
6692 The @code{Small} attribute is defined in Ada 95 (and Ada 2005) only for
6694 GNAT also allows this attribute to be applied to floating-point types
6695 for compatibility with Ada 83. See
6696 the Ada 83 reference manual for an exact description of the semantics of
6697 this attribute when applied to floating-point types.
6700 @unnumberedsec Storage_Unit
6701 @findex Storage_Unit
6703 @code{Standard'Storage_Unit} (@code{Standard} is the only permissible
6704 prefix) provides the same value as @code{System.Storage_Unit}.
6707 @unnumberedsec Stub_Type
6710 The GNAT implementation of remote access-to-classwide types is
6711 organized as described in AARM section E.4 (20.t): a value of an RACW type
6712 (designating a remote object) is represented as a normal access
6713 value, pointing to a "stub" object which in turn contains the
6714 necessary information to contact the designated remote object. A
6715 call on any dispatching operation of such a stub object does the
6716 remote call, if necessary, using the information in the stub object
6717 to locate the target partition, etc.
6719 For a prefix @code{T} that denotes a remote access-to-classwide type,
6720 @code{T'Stub_Type} denotes the type of the corresponding stub objects.
6722 By construction, the layout of @code{T'Stub_Type} is identical to that of
6723 type @code{RACW_Stub_Type} declared in the internal implementation-defined
6724 unit @code{System.Partition_Interface}. Use of this attribute will create
6725 an implicit dependency on this unit.
6727 @node System_Allocator_Alignment
6728 @unnumberedsec System_Allocator_Alignment
6729 @cindex Alignment, allocator
6730 @findex System_Allocator_Alignment
6732 @code{Standard'System_Allocator_Alignment} (@code{Standard} is the only
6733 permissible prefix) provides the observable guaranted to be honored by
6734 the system allocator (malloc). This is a static value that can be used
6735 in user storage pools based on malloc either to reject allocation
6736 with alignment too large or to enable a realignment circuitry if the
6737 alignment request is larger than this value.
6740 @unnumberedsec Target_Name
6743 @code{Standard'Target_Name} (@code{Standard} is the only permissible
6744 prefix) provides a static string value that identifies the target
6745 for the current compilation. For GCC implementations, this is the
6746 standard gcc target name without the terminating slash (for
6747 example, GNAT 5.0 on windows yields "i586-pc-mingw32msv").
6753 @code{Standard'Tick} (@code{Standard} is the only permissible prefix)
6754 provides the same value as @code{System.Tick},
6757 @unnumberedsec To_Address
6760 The @code{System'To_Address}
6761 (@code{System} is the only permissible prefix)
6762 denotes a function identical to
6763 @code{System.Storage_Elements.To_Address} except that
6764 it is a static attribute. This means that if its argument is
6765 a static expression, then the result of the attribute is a
6766 static expression. The result is that such an expression can be
6767 used in contexts (e.g.@: preelaborable packages) which require a
6768 static expression and where the function call could not be used
6769 (since the function call is always non-static, even if its
6770 argument is static).
6773 @unnumberedsec Type_Class
6776 @code{@var{type}'Type_Class} for any type or subtype @var{type} yields
6777 the value of the type class for the full type of @var{type}. If
6778 @var{type} is a generic formal type, the value is the value for the
6779 corresponding actual subtype. The value of this attribute is of type
6780 @code{System.Aux_DEC.Type_Class}, which has the following definition:
6782 @smallexample @c ada
6784 (Type_Class_Enumeration,
6786 Type_Class_Fixed_Point,
6787 Type_Class_Floating_Point,
6792 Type_Class_Address);
6796 Protected types yield the value @code{Type_Class_Task}, which thus
6797 applies to all concurrent types. This attribute is designed to
6798 be compatible with the DEC Ada 83 attribute of the same name.
6801 @unnumberedsec UET_Address
6804 The @code{UET_Address} attribute can only be used for a prefix which
6805 denotes a library package. It yields the address of the unit exception
6806 table when zero cost exception handling is used. This attribute is
6807 intended only for use within the GNAT implementation. See the unit
6808 @code{Ada.Exceptions} in files @file{a-except.ads} and @file{a-except.adb}
6809 for details on how this attribute is used in the implementation.
6811 @node Unconstrained_Array
6812 @unnumberedsec Unconstrained_Array
6813 @findex Unconstrained_Array
6815 The @code{Unconstrained_Array} attribute can be used with a prefix that
6816 denotes any type or subtype. It is a static attribute that yields
6817 @code{True} if the prefix designates an unconstrained array,
6818 and @code{False} otherwise. In a generic instance, the result is
6819 still static, and yields the result of applying this test to the
6822 @node Universal_Literal_String
6823 @unnumberedsec Universal_Literal_String
6824 @cindex Named numbers, representation of
6825 @findex Universal_Literal_String
6827 The prefix of @code{Universal_Literal_String} must be a named
6828 number. The static result is the string consisting of the characters of
6829 the number as defined in the original source. This allows the user
6830 program to access the actual text of named numbers without intermediate
6831 conversions and without the need to enclose the strings in quotes (which
6832 would preclude their use as numbers).
6834 For example, the following program prints the first 50 digits of pi:
6836 @smallexample @c ada
6837 with Text_IO; use Text_IO;
6841 Put (Ada.Numerics.Pi'Universal_Literal_String);
6845 @node Unrestricted_Access
6846 @unnumberedsec Unrestricted_Access
6847 @cindex @code{Access}, unrestricted
6848 @findex Unrestricted_Access
6850 The @code{Unrestricted_Access} attribute is similar to @code{Access}
6851 except that all accessibility and aliased view checks are omitted. This
6852 is a user-beware attribute. It is similar to
6853 @code{Address}, for which it is a desirable replacement where the value
6854 desired is an access type. In other words, its effect is identical to
6855 first applying the @code{Address} attribute and then doing an unchecked
6856 conversion to a desired access type. In GNAT, but not necessarily in
6857 other implementations, the use of static chains for inner level
6858 subprograms means that @code{Unrestricted_Access} applied to a
6859 subprogram yields a value that can be called as long as the subprogram
6860 is in scope (normal Ada accessibility rules restrict this usage).
6862 It is possible to use @code{Unrestricted_Access} for any type, but care
6863 must be exercised if it is used to create pointers to unconstrained
6864 objects. In this case, the resulting pointer has the same scope as the
6865 context of the attribute, and may not be returned to some enclosing
6866 scope. For instance, a function cannot use @code{Unrestricted_Access}
6867 to create a unconstrained pointer and then return that value to the
6871 @unnumberedsec VADS_Size
6872 @cindex @code{Size}, VADS compatibility
6875 The @code{'VADS_Size} attribute is intended to make it easier to port
6876 legacy code which relies on the semantics of @code{'Size} as implemented
6877 by the VADS Ada 83 compiler. GNAT makes a best effort at duplicating the
6878 same semantic interpretation. In particular, @code{'VADS_Size} applied
6879 to a predefined or other primitive type with no Size clause yields the
6880 Object_Size (for example, @code{Natural'Size} is 32 rather than 31 on
6881 typical machines). In addition @code{'VADS_Size} applied to an object
6882 gives the result that would be obtained by applying the attribute to
6883 the corresponding type.
6886 @unnumberedsec Value_Size
6887 @cindex @code{Size}, setting for not-first subtype
6889 @code{@var{type}'Value_Size} is the number of bits required to represent
6890 a value of the given subtype. It is the same as @code{@var{type}'Size},
6891 but, unlike @code{Size}, may be set for non-first subtypes.
6894 @unnumberedsec Wchar_T_Size
6895 @findex Wchar_T_Size
6896 @code{Standard'Wchar_T_Size} (@code{Standard} is the only permissible
6897 prefix) provides the size in bits of the C @code{wchar_t} type
6898 primarily for constructing the definition of this type in
6899 package @code{Interfaces.C}.
6902 @unnumberedsec Word_Size
6904 @code{Standard'Word_Size} (@code{Standard} is the only permissible
6905 prefix) provides the value @code{System.Word_Size}.
6907 @node Implementation Defined Restrictions
6908 @chapter Implementation Defined Restrictions
6911 All RM defined Restriction identifiers are implemented:
6914 @item language-defined restrictions (see 13.12.1)
6915 @item tasking restrictions (see D.7)
6916 @item high integrity restrictions (see H.4)
6920 GNAT implements additional restriction identifiers. All restrictions, whether
6921 language defined or GNAT-specific, are listed in the following.
6924 * Partition-Wide Restrictions::
6925 * Program Unit Level Restrictions::
6928 @node Partition-Wide Restrictions
6929 @section Partition-Wide Restrictions
6931 There are two separate lists of restriction identifiers. The first
6932 set requires consistency throughout a partition (in other words, if the
6933 restriction identifier is used for any compilation unit in the partition,
6934 then all compilation units in the partition must obey the restriction).
6937 * Immediate_Reclamation::
6938 * Max_Asynchronous_Select_Nesting::
6939 * Max_Entry_Queue_Length::
6940 * Max_Protected_Entries::
6941 * Max_Select_Alternatives::
6942 * Max_Storage_At_Blocking::
6943 * Max_Task_Entries::
6945 * No_Abort_Statements::
6946 * No_Access_Parameter_Allocators::
6947 * No_Access_Subprograms::
6949 * No_Anonymous_Allocators::
6952 * No_Default_Initialization::
6955 * No_Direct_Boolean_Operators::
6957 * No_Dispatching_Calls::
6958 * No_Dynamic_Attachment::
6959 * No_Dynamic_Priorities::
6960 * No_Entry_Calls_In_Elaboration_Code::
6961 * No_Enumeration_Maps::
6962 * No_Exception_Handlers::
6963 * No_Exception_Propagation::
6964 * No_Exception_Registration::
6968 * No_Floating_Point::
6969 * No_Implicit_Conditionals::
6970 * No_Implicit_Dynamic_Code::
6971 * No_Implicit_Heap_Allocations::
6972 * No_Implicit_Loops::
6973 * No_Initialize_Scalars::
6975 * No_Local_Allocators::
6976 * No_Local_Protected_Objects::
6977 * No_Local_Timing_Events::
6978 * No_Nested_Finalization::
6979 * No_Protected_Type_Allocators::
6980 * No_Protected_Types::
6983 * No_Relative_Delay::
6984 * No_Requeue_Statements::
6985 * No_Secondary_Stack::
6986 * No_Select_Statements::
6987 * No_Specific_Termination_Handlers::
6988 * No_Specification_of_Aspect::
6989 * No_Standard_Allocators_After_Elaboration::
6990 * No_Standard_Storage_Pools::
6991 * No_Stream_Optimizations::
6993 * No_Task_Allocators::
6994 * No_Task_Attributes_Package::
6995 * No_Task_Hierarchy::
6996 * No_Task_Termination::
6998 * No_Terminate_Alternatives::
6999 * No_Unchecked_Access::
7001 * Static_Priorities::
7002 * Static_Storage_Size::
7005 @node Immediate_Reclamation
7006 @unnumberedsubsec Immediate_Reclamation
7007 @findex Immediate_Reclamation
7008 [RM H.4] This restriction ensures that, except for storage occupied by
7009 objects created by allocators and not deallocated via unchecked
7010 deallocation, any storage reserved at run time for an object is
7011 immediately reclaimed when the object no longer exists.
7013 @node Max_Asynchronous_Select_Nesting
7014 @unnumberedsubsec Max_Asynchronous_Select_Nesting
7015 @findex Max_Asynchronous_Select_Nesting
7016 [RM D.7] Specifies the maximum dynamic nesting level of asynchronous
7017 selects. Violations of this restriction with a value of zero are
7018 detected at compile time. Violations of this restriction with values
7019 other than zero cause Storage_Error to be raised.
7021 @node Max_Entry_Queue_Length
7022 @unnumberedsubsec Max_Entry_Queue_Length
7023 @findex Max_Entry_Queue_Length
7024 [RM D.7] This restriction is a declaration that any protected entry compiled in
7025 the scope of the restriction has at most the specified number of
7026 tasks waiting on the entry at any one time, and so no queue is required.
7027 Note that this restriction is checked at run time. Violation of this
7028 restriction results in the raising of Program_Error exception at the point of
7031 @node Max_Protected_Entries
7032 @unnumberedsubsec Max_Protected_Entries
7033 @findex Max_Protected_Entries
7034 [RM D.7] Specifies the maximum number of entries per protected type. The
7035 bounds of every entry family of a protected unit shall be static, or shall be
7036 defined by a discriminant of a subtype whose corresponding bound is static.
7038 @node Max_Select_Alternatives
7039 @unnumberedsubsec Max_Select_Alternatives
7040 @findex Max_Select_Alternatives
7041 [RM D.7] Specifies the maximum number of alternatives in a selective accept.
7043 @node Max_Storage_At_Blocking
7044 @unnumberedsubsec Max_Storage_At_Blocking
7045 @findex Max_Storage_At_Blocking
7046 [RM D.7] Specifies the maximum portion (in storage elements) of a task's
7047 Storage_Size that can be retained by a blocked task. A violation of this
7048 restriction causes Storage_Error to be raised.
7050 @node Max_Task_Entries
7051 @unnumberedsubsec Max_Task_Entries
7052 @findex Max_Task_Entries
7053 [RM D.7] Specifies the maximum number of entries
7054 per task. The bounds of every entry family
7055 of a task unit shall be static, or shall be
7056 defined by a discriminant of a subtype whose
7057 corresponding bound is static.
7060 @unnumberedsubsec Max_Tasks
7062 [RM D.7] Specifies the maximum number of task that may be created, not
7063 counting the creation of the environment task. Violations of this
7064 restriction with a value of zero are detected at compile
7065 time. Violations of this restriction with values other than zero cause
7066 Storage_Error to be raised.
7068 @node No_Abort_Statements
7069 @unnumberedsubsec No_Abort_Statements
7070 @findex No_Abort_Statements
7071 [RM D.7] There are no abort_statements, and there are
7072 no calls to Task_Identification.Abort_Task.
7074 @node No_Access_Parameter_Allocators
7075 @unnumberedsubsec No_Access_Parameter_Allocators
7076 @findex No_Access_Parameter_Allocators
7077 [RM H.4] This restriction ensures at compile time that there are no
7078 occurrences of an allocator as the actual parameter to an access
7081 @node No_Access_Subprograms
7082 @unnumberedsubsec No_Access_Subprograms
7083 @findex No_Access_Subprograms
7084 [RM H.4] This restriction ensures at compile time that there are no
7085 declarations of access-to-subprogram types.
7088 @unnumberedsubsec No_Allocators
7089 @findex No_Allocators
7090 [RM H.4] This restriction ensures at compile time that there are no
7091 occurrences of an allocator.
7093 @node No_Anonymous_Allocators
7094 @unnumberedsubsec No_Anonymous_Allocators
7095 @findex No_Anonymous_Allocators
7096 [RM H.4] This restriction ensures at compile time that there are no
7097 occurrences of an allocator of anonymous access type.
7100 @unnumberedsubsec No_Calendar
7102 [GNAT] This restriction ensures at compile time that there is no implicit or
7103 explicit dependence on the package @code{Ada.Calendar}.
7105 @node No_Coextensions
7106 @unnumberedsubsec No_Coextensions
7107 @findex No_Coextensions
7108 [RM H.4] This restriction ensures at compile time that there are no
7109 coextensions. See 3.10.2.
7111 @node No_Default_Initialization
7112 @unnumberedsubsec No_Default_Initialization
7113 @findex No_Default_Initialization
7115 [GNAT] This restriction prohibits any instance of default initialization
7116 of variables. The binder implements a consistency rule which prevents
7117 any unit compiled without the restriction from with'ing a unit with the
7118 restriction (this allows the generation of initialization procedures to
7119 be skipped, since you can be sure that no call is ever generated to an
7120 initialization procedure in a unit with the restriction active). If used
7121 in conjunction with Initialize_Scalars or Normalize_Scalars, the effect
7122 is to prohibit all cases of variables declared without a specific
7123 initializer (including the case of OUT scalar parameters).
7126 @unnumberedsubsec No_Delay
7128 [RM H.4] This restriction ensures at compile time that there are no
7129 delay statements and no dependences on package Calendar.
7132 @unnumberedsubsec No_Dependence
7133 @findex No_Dependence
7134 [RM 13.12.1] This restriction checks at compile time that there are no
7135 dependence on a library unit.
7137 @node No_Direct_Boolean_Operators
7138 @unnumberedsubsec No_Direct_Boolean_Operators
7139 @findex No_Direct_Boolean_Operators
7140 [GNAT] This restriction ensures that no logical (and/or/xor) are used on
7141 operands of type Boolean (or any type derived
7142 from Boolean). This is intended for use in safety critical programs
7143 where the certification protocol requires the use of short-circuit
7144 (and then, or else) forms for all composite boolean operations.
7147 @unnumberedsubsec No_Dispatch
7149 [RM H.4] This restriction ensures at compile time that there are no
7150 occurrences of @code{T'Class}, for any (tagged) subtype @code{T}.
7152 @node No_Dispatching_Calls
7153 @unnumberedsubsec No_Dispatching_Calls
7154 @findex No_Dispatching_Calls
7155 [GNAT] This restriction ensures at compile time that the code generated by the
7156 compiler involves no dispatching calls. The use of this restriction allows the
7157 safe use of record extensions, classwide membership tests and other classwide
7158 features not involving implicit dispatching. This restriction ensures that
7159 the code contains no indirect calls through a dispatching mechanism. Note that
7160 this includes internally-generated calls created by the compiler, for example
7161 in the implementation of class-wide objects assignments. The
7162 membership test is allowed in the presence of this restriction, because its
7163 implementation requires no dispatching.
7164 This restriction is comparable to the official Ada restriction
7165 @code{No_Dispatch} except that it is a bit less restrictive in that it allows
7166 all classwide constructs that do not imply dispatching.
7167 The following example indicates constructs that violate this restriction.
7171 type T is tagged record
7174 procedure P (X : T);
7176 type DT is new T with record
7177 More_Data : Natural;
7179 procedure Q (X : DT);
7183 procedure Example is
7184 procedure Test (O : T'Class) is
7185 N : Natural := O'Size;-- Error: Dispatching call
7186 C : T'Class := O; -- Error: implicit Dispatching Call
7188 if O in DT'Class then -- OK : Membership test
7189 Q (DT (O)); -- OK : Type conversion plus direct call
7191 P (O); -- Error: Dispatching call
7197 P (Obj); -- OK : Direct call
7198 P (T (Obj)); -- OK : Type conversion plus direct call
7199 P (T'Class (Obj)); -- Error: Dispatching call
7201 Test (Obj); -- OK : Type conversion
7203 if Obj in T'Class then -- OK : Membership test
7209 @node No_Dynamic_Attachment
7210 @unnumberedsubsec No_Dynamic_Attachment
7211 @findex No_Dynamic_Attachment
7212 [RM D.7] This restriction ensures that there is no call to any of the
7213 operations defined in package Ada.Interrupts
7214 (Is_Reserved, Is_Attached, Current_Handler, Attach_Handler, Exchange_Handler,
7215 Detach_Handler, and Reference).
7217 @node No_Dynamic_Priorities
7218 @unnumberedsubsec No_Dynamic_Priorities
7219 @findex No_Dynamic_Priorities
7220 [RM D.7] There are no semantic dependencies on the package Dynamic_Priorities.
7222 @node No_Entry_Calls_In_Elaboration_Code
7223 @unnumberedsubsec No_Entry_Calls_In_Elaboration_Code
7224 @findex No_Entry_Calls_In_Elaboration_Code
7225 [GNAT] This restriction ensures at compile time that no task or protected entry
7226 calls are made during elaboration code. As a result of the use of this
7227 restriction, the compiler can assume that no code past an accept statement
7228 in a task can be executed at elaboration time.
7230 @node No_Enumeration_Maps
7231 @unnumberedsubsec No_Enumeration_Maps
7232 @findex No_Enumeration_Maps
7233 [GNAT] This restriction ensures at compile time that no operations requiring
7234 enumeration maps are used (that is Image and Value attributes applied
7235 to enumeration types).
7237 @node No_Exception_Handlers
7238 @unnumberedsubsec No_Exception_Handlers
7239 @findex No_Exception_Handlers
7240 [GNAT] This restriction ensures at compile time that there are no explicit
7241 exception handlers. It also indicates that no exception propagation will
7242 be provided. In this mode, exceptions may be raised but will result in
7243 an immediate call to the last chance handler, a routine that the user
7244 must define with the following profile:
7246 @smallexample @c ada
7247 procedure Last_Chance_Handler
7248 (Source_Location : System.Address; Line : Integer);
7249 pragma Export (C, Last_Chance_Handler,
7250 "__gnat_last_chance_handler");
7253 The parameter is a C null-terminated string representing a message to be
7254 associated with the exception (typically the source location of the raise
7255 statement generated by the compiler). The Line parameter when nonzero
7256 represents the line number in the source program where the raise occurs.
7258 @node No_Exception_Propagation
7259 @unnumberedsubsec No_Exception_Propagation
7260 @findex No_Exception_Propagation
7261 [GNAT] This restriction guarantees that exceptions are never propagated
7262 to an outer subprogram scope. The only case in which an exception may
7263 be raised is when the handler is statically in the same subprogram, so
7264 that the effect of a raise is essentially like a goto statement. Any
7265 other raise statement (implicit or explicit) will be considered
7266 unhandled. Exception handlers are allowed, but may not contain an
7267 exception occurrence identifier (exception choice). In addition, use of
7268 the package GNAT.Current_Exception is not permitted, and reraise
7269 statements (raise with no operand) are not permitted.
7271 @node No_Exception_Registration
7272 @unnumberedsubsec No_Exception_Registration
7273 @findex No_Exception_Registration
7274 [GNAT] This restriction ensures at compile time that no stream operations for
7275 types Exception_Id or Exception_Occurrence are used. This also makes it
7276 impossible to pass exceptions to or from a partition with this restriction
7277 in a distributed environment. If this exception is active, then the generated
7278 code is simplified by omitting the otherwise-required global registration
7279 of exceptions when they are declared.
7282 @unnumberedsubsec No_Exceptions
7283 @findex No_Exceptions
7284 [RM H.4] This restriction ensures at compile time that there are no
7285 raise statements and no exception handlers.
7287 @node No_Finalization
7288 @unnumberedsubsec No_Finalization
7289 @findex No_Finalization
7290 [GNAT] This restriction disables the language features described in
7291 chapter 7.6 of the Ada 2005 RM as well as all form of code generation
7292 performed by the compiler to support these features. The following types
7293 are no longer considered controlled when this restriction is in effect:
7296 @code{Ada.Finalization.Controlled}
7298 @code{Ada.Finalization.Limited_Controlled}
7300 Derivations from @code{Controlled} or @code{Limited_Controlled}
7308 Array and record types with controlled components
7310 The compiler no longer generates code to initialize, finalize or adjust an
7311 object or a nested component, either declared on the stack or on the heap. The
7312 deallocation of a controlled object no longer finalizes its contents.
7314 @node No_Fixed_Point
7315 @unnumberedsubsec No_Fixed_Point
7316 @findex No_Fixed_Point
7317 [RM H.4] This restriction ensures at compile time that there are no
7318 occurrences of fixed point types and operations.
7320 @node No_Floating_Point
7321 @unnumberedsubsec No_Floating_Point
7322 @findex No_Floating_Point
7323 [RM H.4] This restriction ensures at compile time that there are no
7324 occurrences of floating point types and operations.
7326 @node No_Implicit_Conditionals
7327 @unnumberedsubsec No_Implicit_Conditionals
7328 @findex No_Implicit_Conditionals
7329 [GNAT] This restriction ensures that the generated code does not contain any
7330 implicit conditionals, either by modifying the generated code where possible,
7331 or by rejecting any construct that would otherwise generate an implicit
7332 conditional. Note that this check does not include run time constraint
7333 checks, which on some targets may generate implicit conditionals as
7334 well. To control the latter, constraint checks can be suppressed in the
7335 normal manner. Constructs generating implicit conditionals include comparisons
7336 of composite objects and the Max/Min attributes.
7338 @node No_Implicit_Dynamic_Code
7339 @unnumberedsubsec No_Implicit_Dynamic_Code
7340 @findex No_Implicit_Dynamic_Code
7342 [GNAT] This restriction prevents the compiler from building ``trampolines''.
7343 This is a structure that is built on the stack and contains dynamic
7344 code to be executed at run time. On some targets, a trampoline is
7345 built for the following features: @code{Access},
7346 @code{Unrestricted_Access}, or @code{Address} of a nested subprogram;
7347 nested task bodies; primitive operations of nested tagged types.
7348 Trampolines do not work on machines that prevent execution of stack
7349 data. For example, on windows systems, enabling DEP (data execution
7350 protection) will cause trampolines to raise an exception.
7351 Trampolines are also quite slow at run time.
7353 On many targets, trampolines have been largely eliminated. Look at the
7354 version of system.ads for your target --- if it has
7355 Always_Compatible_Rep equal to False, then trampolines are largely
7356 eliminated. In particular, a trampoline is built for the following
7357 features: @code{Address} of a nested subprogram;
7358 @code{Access} or @code{Unrestricted_Access} of a nested subprogram,
7359 but only if pragma Favor_Top_Level applies, or the access type has a
7360 foreign-language convention; primitive operations of nested tagged
7363 @node No_Implicit_Heap_Allocations
7364 @unnumberedsubsec No_Implicit_Heap_Allocations
7365 @findex No_Implicit_Heap_Allocations
7366 [RM D.7] No constructs are allowed to cause implicit heap allocation.
7368 @node No_Implicit_Loops
7369 @unnumberedsubsec No_Implicit_Loops
7370 @findex No_Implicit_Loops
7371 [GNAT] This restriction ensures that the generated code does not contain any
7372 implicit @code{for} loops, either by modifying
7373 the generated code where possible,
7374 or by rejecting any construct that would otherwise generate an implicit
7375 @code{for} loop. If this restriction is active, it is possible to build
7376 large array aggregates with all static components without generating an
7377 intermediate temporary, and without generating a loop to initialize individual
7378 components. Otherwise, a loop is created for arrays larger than about 5000
7381 @node No_Initialize_Scalars
7382 @unnumberedsubsec No_Initialize_Scalars
7383 @findex No_Initialize_Scalars
7384 [GNAT] This restriction ensures that no unit in the partition is compiled with
7385 pragma Initialize_Scalars. This allows the generation of more efficient
7386 code, and in particular eliminates dummy null initialization routines that
7387 are otherwise generated for some record and array types.
7390 @unnumberedsubsec No_IO
7392 [RM H.4] This restriction ensures at compile time that there are no
7393 dependences on any of the library units Sequential_IO, Direct_IO,
7394 Text_IO, Wide_Text_IO, Wide_Wide_Text_IO, or Stream_IO.
7396 @node No_Local_Allocators
7397 @unnumberedsubsec No_Local_Allocators
7398 @findex No_Local_Allocators
7399 [RM H.4] This restriction ensures at compile time that there are no
7400 occurrences of an allocator in subprograms, generic subprograms, tasks,
7403 @node No_Local_Protected_Objects
7404 @unnumberedsubsec No_Local_Protected_Objects
7405 @findex No_Local_Protected_Objects
7406 [RM D.7] This restriction ensures at compile time that protected objects are
7407 only declared at the library level.
7409 @node No_Local_Timing_Events
7410 @unnumberedsubsec No_Local_Timing_Events
7411 @findex No_Local_Timing_Events
7412 [RM D.7] All objects of type Ada.Timing_Events.Timing_Event are
7413 declared at the library level.
7415 @node No_Nested_Finalization
7416 @unnumberedsubsec No_Nested_Finalization
7417 @findex No_Nested_Finalization
7418 [RM D.7] All objects requiring finalization are declared at the library level.
7420 @node No_Protected_Type_Allocators
7421 @unnumberedsubsec No_Protected_Type_Allocators
7422 @findex No_Protected_Type_Allocators
7423 [RM D.7] This restriction ensures at compile time that there are no allocator
7424 expressions that attempt to allocate protected objects.
7426 @node No_Protected_Types
7427 @unnumberedsubsec No_Protected_Types
7428 @findex No_Protected_Types
7429 [RM H.4] This restriction ensures at compile time that there are no
7430 declarations of protected types or protected objects.
7433 @unnumberedsubsec No_Recursion
7434 @findex No_Recursion
7435 [RM H.4] A program execution is erroneous if a subprogram is invoked as
7436 part of its execution.
7439 @unnumberedsubsec No_Reentrancy
7440 @findex No_Reentrancy
7441 [RM H.4] A program execution is erroneous if a subprogram is executed by
7442 two tasks at the same time.
7444 @node No_Relative_Delay
7445 @unnumberedsubsec No_Relative_Delay
7446 @findex No_Relative_Delay
7447 [RM D.7] This restriction ensures at compile time that there are no delay
7448 relative statements and prevents expressions such as @code{delay 1.23;} from
7449 appearing in source code.
7451 @node No_Requeue_Statements
7452 @unnumberedsubsec No_Requeue_Statements
7453 @findex No_Requeue_Statements
7454 [RM D.7] This restriction ensures at compile time that no requeue statements
7455 are permitted and prevents keyword @code{requeue} from being used in source
7458 @node No_Secondary_Stack
7459 @unnumberedsubsec No_Secondary_Stack
7460 @findex No_Secondary_Stack
7461 [GNAT] This restriction ensures at compile time that the generated code
7462 does not contain any reference to the secondary stack. The secondary
7463 stack is used to implement functions returning unconstrained objects
7464 (arrays or records) on some targets.
7466 @node No_Select_Statements
7467 @unnumberedsubsec No_Select_Statements
7468 @findex No_Select_Statements
7469 [RM D.7] This restriction ensures at compile time no select statements of any
7470 kind are permitted, that is the keyword @code{select} may not appear.
7472 @node No_Specific_Termination_Handlers
7473 @unnumberedsubsec No_Specific_Termination_Handlers
7474 @findex No_Specific_Termination_Handlers
7475 [RM D.7] There are no calls to Ada.Task_Termination.Set_Specific_Handler
7476 or to Ada.Task_Termination.Specific_Handler.
7478 @node No_Specification_of_Aspect
7479 @unnumberedsubsec No_Specification_of_Aspect
7480 @findex No_Specification_of_Aspect
7481 [RM 13.12.1] This restriction checks at compile time that no aspect
7482 specification, attribute definition clause, or pragma is given for a
7485 @node No_Standard_Allocators_After_Elaboration
7486 @unnumberedsubsec No_Standard_Allocators_After_Elaboration
7487 @findex No_Standard_Allocators_After_Elaboration
7488 [RM D.7] Specifies that an allocator using a standard storage pool
7489 should never be evaluated at run time after the elaboration of the
7490 library items of the partition has completed. Otherwise, Storage_Error
7493 @node No_Standard_Storage_Pools
7494 @unnumberedsubsec No_Standard_Storage_Pools
7495 @findex No_Standard_Storage_Pools
7496 [GNAT] This restriction ensures at compile time that no access types
7497 use the standard default storage pool. Any access type declared must
7498 have an explicit Storage_Pool attribute defined specifying a
7499 user-defined storage pool.
7501 @node No_Stream_Optimizations
7502 @unnumberedsubsec No_Stream_Optimizations
7503 @findex No_Stream_Optimizations
7504 [GNAT] This restriction affects the performance of stream operations on types
7505 @code{String}, @code{Wide_String} and @code{Wide_Wide_String}. By default, the
7506 compiler uses block reads and writes when manipulating @code{String} objects
7507 due to their supperior performance. When this restriction is in effect, the
7508 compiler performs all IO operations on a per-character basis.
7511 @unnumberedsubsec No_Streams
7513 [GNAT] This restriction ensures at compile/bind time that there are no
7514 stream objects created and no use of stream attributes.
7515 This restriction does not forbid dependences on the package
7516 @code{Ada.Streams}. So it is permissible to with
7517 @code{Ada.Streams} (or another package that does so itself)
7518 as long as no actual stream objects are created and no
7519 stream attributes are used.
7521 Note that the use of restriction allows optimization of tagged types,
7522 since they do not need to worry about dispatching stream operations.
7523 To take maximum advantage of this space-saving optimization, any
7524 unit declaring a tagged type should be compiled with the restriction,
7525 though this is not required.
7527 @node No_Task_Allocators
7528 @unnumberedsubsec No_Task_Allocators
7529 @findex No_Task_Allocators
7530 [RM D.7] There are no allocators for task types
7531 or types containing task subcomponents.
7533 @node No_Task_Attributes_Package
7534 @unnumberedsubsec No_Task_Attributes_Package
7535 @findex No_Task_Attributes_Package
7536 [GNAT] This restriction ensures at compile time that there are no implicit or
7537 explicit dependencies on the package @code{Ada.Task_Attributes}.
7539 @node No_Task_Hierarchy
7540 @unnumberedsubsec No_Task_Hierarchy
7541 @findex No_Task_Hierarchy
7542 [RM D.7] All (non-environment) tasks depend
7543 directly on the environment task of the partition.
7545 @node No_Task_Termination
7546 @unnumberedsubsec No_Task_Termination
7547 @findex No_Task_Termination
7548 [RM D.7] Tasks which terminate are erroneous.
7551 @unnumberedsubsec No_Tasking
7553 [GNAT] This restriction prevents the declaration of tasks or task types
7554 throughout the partition. It is similar in effect to the use of
7555 @code{Max_Tasks => 0} except that violations are caught at compile time
7556 and cause an error message to be output either by the compiler or
7559 @node No_Terminate_Alternatives
7560 @unnumberedsubsec No_Terminate_Alternatives
7561 @findex No_Terminate_Alternatives
7562 [RM D.7] There are no selective accepts with terminate alternatives.
7564 @node No_Unchecked_Access
7565 @unnumberedsubsec No_Unchecked_Access
7566 @findex No_Unchecked_Access
7567 [RM H.4] This restriction ensures at compile time that there are no
7568 occurrences of the Unchecked_Access attribute.
7570 @node Simple_Barriers
7571 @unnumberedsubsec Simple_Barriers
7572 @findex Simple_Barriers
7573 [RM D.7] This restriction ensures at compile time that barriers in entry
7574 declarations for protected types are restricted to either static boolean
7575 expressions or references to simple boolean variables defined in the private
7576 part of the protected type. No other form of entry barriers is permitted.
7578 @node Static_Priorities
7579 @unnumberedsubsec Static_Priorities
7580 @findex Static_Priorities
7581 [GNAT] This restriction ensures at compile time that all priority expressions
7582 are static, and that there are no dependences on the package
7583 @code{Ada.Dynamic_Priorities}.
7585 @node Static_Storage_Size
7586 @unnumberedsubsec Static_Storage_Size
7587 @findex Static_Storage_Size
7588 [GNAT] This restriction ensures at compile time that any expression appearing
7589 in a Storage_Size pragma or attribute definition clause is static.
7591 @node Program Unit Level Restrictions
7592 @section Program Unit Level Restrictions
7595 The second set of restriction identifiers
7596 does not require partition-wide consistency.
7597 The restriction may be enforced for a single
7598 compilation unit without any effect on any of the
7599 other compilation units in the partition.
7602 * No_Elaboration_Code::
7604 * No_Implementation_Aspect_Specifications::
7605 * No_Implementation_Attributes::
7606 * No_Implementation_Identifiers::
7607 * No_Implementation_Pragmas::
7608 * No_Implementation_Restrictions::
7609 * No_Implementation_Units::
7610 * No_Implicit_Aliasing::
7611 * No_Obsolescent_Features::
7612 * No_Wide_Characters::
7616 @node No_Elaboration_Code
7617 @unnumberedsubsec No_Elaboration_Code
7618 @findex No_Elaboration_Code
7619 [GNAT] This restriction ensures at compile time that no elaboration code is
7620 generated. Note that this is not the same condition as is enforced
7621 by pragma @code{Preelaborate}. There are cases in which pragma
7622 @code{Preelaborate} still permits code to be generated (e.g.@: code
7623 to initialize a large array to all zeroes), and there are cases of units
7624 which do not meet the requirements for pragma @code{Preelaborate},
7625 but for which no elaboration code is generated. Generally, it is
7626 the case that preelaborable units will meet the restrictions, with
7627 the exception of large aggregates initialized with an others_clause,
7628 and exception declarations (which generate calls to a run-time
7629 registry procedure). This restriction is enforced on
7630 a unit by unit basis, it need not be obeyed consistently
7631 throughout a partition.
7633 In the case of aggregates with others, if the aggregate has a dynamic
7634 size, there is no way to eliminate the elaboration code (such dynamic
7635 bounds would be incompatible with @code{Preelaborate} in any case). If
7636 the bounds are static, then use of this restriction actually modifies
7637 the code choice of the compiler to avoid generating a loop, and instead
7638 generate the aggregate statically if possible, no matter how many times
7639 the data for the others clause must be repeatedly generated.
7641 It is not possible to precisely document
7642 the constructs which are compatible with this restriction, since,
7643 unlike most other restrictions, this is not a restriction on the
7644 source code, but a restriction on the generated object code. For
7645 example, if the source contains a declaration:
7648 Val : constant Integer := X;
7652 where X is not a static constant, it may be possible, depending
7653 on complex optimization circuitry, for the compiler to figure
7654 out the value of X at compile time, in which case this initialization
7655 can be done by the loader, and requires no initialization code. It
7656 is not possible to document the precise conditions under which the
7657 optimizer can figure this out.
7659 Note that this the implementation of this restriction requires full
7660 code generation. If it is used in conjunction with "semantics only"
7661 checking, then some cases of violations may be missed.
7663 @node No_Entry_Queue
7664 @unnumberedsubsec No_Entry_Queue
7665 @findex No_Entry_Queue
7666 [GNAT] This restriction is a declaration that any protected entry compiled in
7667 the scope of the restriction has at most one task waiting on the entry
7668 at any one time, and so no queue is required. This restriction is not
7669 checked at compile time. A program execution is erroneous if an attempt
7670 is made to queue a second task on such an entry.
7672 @node No_Implementation_Aspect_Specifications
7673 @unnumberedsubsec No_Implementation_Aspect_Specifications
7674 @findex No_Implementation_Aspect_Specifications
7675 [RM 13.12.1] This restriction checks at compile time that no
7676 GNAT-defined aspects are present. With this restriction, the only
7677 aspects that can be used are those defined in the Ada Reference Manual.
7679 @node No_Implementation_Attributes
7680 @unnumberedsubsec No_Implementation_Attributes
7681 @findex No_Implementation_Attributes
7682 [RM 13.12.1] This restriction checks at compile time that no
7683 GNAT-defined attributes are present. With this restriction, the only
7684 attributes that can be used are those defined in the Ada Reference
7687 @node No_Implementation_Identifiers
7688 @unnumberedsubsec No_Implementation_Identifiers
7689 @findex No_Implementation_Identifiers
7690 [RM 13.12.1] This restriction checks at compile time that no
7691 implementation-defined identifiers occur within language-defined
7694 @node No_Implementation_Pragmas
7695 @unnumberedsubsec No_Implementation_Pragmas
7696 @findex No_Implementation_Pragmas
7697 [RM 13.12.1] This restriction checks at compile time that no
7698 GNAT-defined pragmas are present. With this restriction, the only
7699 pragmas that can be used are those defined in the Ada Reference Manual.
7701 @node No_Implementation_Restrictions
7702 @unnumberedsubsec No_Implementation_Restrictions
7703 @findex No_Implementation_Restrictions
7704 [GNAT] This restriction checks at compile time that no GNAT-defined restriction
7705 identifiers (other than @code{No_Implementation_Restrictions} itself)
7706 are present. With this restriction, the only other restriction identifiers
7707 that can be used are those defined in the Ada Reference Manual.
7709 @node No_Implementation_Units
7710 @unnumberedsubsec No_Implementation_Units
7711 @findex No_Implementation_Units
7712 [RM 13.12.1] This restriction checks at compile time that there is no
7713 mention in the context clause of any implementation-defined descendants
7714 of packages Ada, Interfaces, or System.
7716 @node No_Implicit_Aliasing
7717 @unnumberedsubsec No_Implicit_Aliasing
7718 @findex No_Implicit_Aliasing
7719 [GNAT] This restriction, which is not required to be partition-wide consistent,
7720 requires an explicit aliased keyword for an object to which 'Access,
7721 'Unchecked_Access, or 'Address is applied, and forbids entirely the use of
7722 the 'Unrestricted_Access attribute for objects. Note: the reason that
7723 Unrestricted_Access is forbidden is that it would require the prefix
7724 to be aliased, and in such cases, it can always be replaced by
7725 the standard attribute Unchecked_Access which is preferable.
7727 @node No_Obsolescent_Features
7728 @unnumberedsubsec No_Obsolescent_Features
7729 @findex No_Obsolescent_Features
7730 [RM 13.12.1] This restriction checks at compile time that no obsolescent
7731 features are used, as defined in Annex J of the Ada Reference Manual.
7733 @node No_Wide_Characters
7734 @unnumberedsubsec No_Wide_Characters
7735 @findex No_Wide_Characters
7736 [GNAT] This restriction ensures at compile time that no uses of the types
7737 @code{Wide_Character} or @code{Wide_String} or corresponding wide
7739 appear, and that no wide or wide wide string or character literals
7740 appear in the program (that is literals representing characters not in
7741 type @code{Character}.
7744 @unnumberedsubsec SPARK
7746 [GNAT] This restriction checks at compile time that some constructs
7747 forbidden in SPARK are not present. The SPARK version used as a
7748 reference is the same as the Ada mode for the unit, so a unit compiled
7749 in Ada 95 mode with SPARK restrictions will be checked for constructs
7750 forbidden in SPARK 95. Error messages related to SPARK restriction have
7754 violation of restriction "SPARK" at <file>
7758 This is not a replacement for the semantic checks performed by the
7759 SPARK Examiner tool, as the compiler only deals currently with code,
7760 not at all with SPARK annotations and does not guarantee catching all
7761 cases of constructs forbidden by SPARK.
7763 Thus it may well be the case that code which
7764 passes the compiler in SPARK mode is rejected by the SPARK Examiner,
7765 e.g. due to the different visibility rules of the Examiner based on
7766 SPARK @code{inherit} annotations.
7768 This restriction can be useful in providing an initial filter for
7769 code developed using SPARK, or in examining legacy code to see how far
7770 it is from meeting SPARK restrictions.
7772 @c ------------------------
7773 @node Implementation Advice
7774 @chapter Implementation Advice
7776 The main text of the Ada Reference Manual describes the required
7777 behavior of all Ada compilers, and the GNAT compiler conforms to
7780 In addition, there are sections throughout the Ada Reference Manual headed
7781 by the phrase ``Implementation advice''. These sections are not normative,
7782 i.e., they do not specify requirements that all compilers must
7783 follow. Rather they provide advice on generally desirable behavior. You
7784 may wonder why they are not requirements. The most typical answer is
7785 that they describe behavior that seems generally desirable, but cannot
7786 be provided on all systems, or which may be undesirable on some systems.
7788 As far as practical, GNAT follows the implementation advice sections in
7789 the Ada Reference Manual. This chapter contains a table giving the
7790 reference manual section number, paragraph number and several keywords
7791 for each advice. Each entry consists of the text of the advice followed
7792 by the GNAT interpretation of this advice. Most often, this simply says
7793 ``followed'', which means that GNAT follows the advice. However, in a
7794 number of cases, GNAT deliberately deviates from this advice, in which
7795 case the text describes what GNAT does and why.
7797 @cindex Error detection
7798 @unnumberedsec 1.1.3(20): Error Detection
7801 If an implementation detects the use of an unsupported Specialized Needs
7802 Annex feature at run time, it should raise @code{Program_Error} if
7805 Not relevant. All specialized needs annex features are either supported,
7806 or diagnosed at compile time.
7809 @unnumberedsec 1.1.3(31): Child Units
7812 If an implementation wishes to provide implementation-defined
7813 extensions to the functionality of a language-defined library unit, it
7814 should normally do so by adding children to the library unit.
7818 @cindex Bounded errors
7819 @unnumberedsec 1.1.5(12): Bounded Errors
7822 If an implementation detects a bounded error or erroneous
7823 execution, it should raise @code{Program_Error}.
7825 Followed in all cases in which the implementation detects a bounded
7826 error or erroneous execution. Not all such situations are detected at
7830 @unnumberedsec 2.8(16): Pragmas
7833 Normally, implementation-defined pragmas should have no semantic effect
7834 for error-free programs; that is, if the implementation-defined pragmas
7835 are removed from a working program, the program should still be legal,
7836 and should still have the same semantics.
7838 The following implementation defined pragmas are exceptions to this
7850 @item CPP_Constructor
7854 @item Interface_Name
7856 @item Machine_Attribute
7858 @item Unimplemented_Unit
7860 @item Unchecked_Union
7865 In each of the above cases, it is essential to the purpose of the pragma
7866 that this advice not be followed. For details see the separate section
7867 on implementation defined pragmas.
7869 @unnumberedsec 2.8(17-19): Pragmas
7872 Normally, an implementation should not define pragmas that can
7873 make an illegal program legal, except as follows:
7877 A pragma used to complete a declaration, such as a pragma @code{Import};
7881 A pragma used to configure the environment by adding, removing, or
7882 replacing @code{library_items}.
7884 See response to paragraph 16 of this same section.
7886 @cindex Character Sets
7887 @cindex Alternative Character Sets
7888 @unnumberedsec 3.5.2(5): Alternative Character Sets
7891 If an implementation supports a mode with alternative interpretations
7892 for @code{Character} and @code{Wide_Character}, the set of graphic
7893 characters of @code{Character} should nevertheless remain a proper
7894 subset of the set of graphic characters of @code{Wide_Character}. Any
7895 character set ``localizations'' should be reflected in the results of
7896 the subprograms defined in the language-defined package
7897 @code{Characters.Handling} (see A.3) available in such a mode. In a mode with
7898 an alternative interpretation of @code{Character}, the implementation should
7899 also support a corresponding change in what is a legal
7900 @code{identifier_letter}.
7902 Not all wide character modes follow this advice, in particular the JIS
7903 and IEC modes reflect standard usage in Japan, and in these encoding,
7904 the upper half of the Latin-1 set is not part of the wide-character
7905 subset, since the most significant bit is used for wide character
7906 encoding. However, this only applies to the external forms. Internally
7907 there is no such restriction.
7909 @cindex Integer types
7910 @unnumberedsec 3.5.4(28): Integer Types
7914 An implementation should support @code{Long_Integer} in addition to
7915 @code{Integer} if the target machine supports 32-bit (or longer)
7916 arithmetic. No other named integer subtypes are recommended for package
7917 @code{Standard}. Instead, appropriate named integer subtypes should be
7918 provided in the library package @code{Interfaces} (see B.2).
7920 @code{Long_Integer} is supported. Other standard integer types are supported
7921 so this advice is not fully followed. These types
7922 are supported for convenient interface to C, and so that all hardware
7923 types of the machine are easily available.
7924 @unnumberedsec 3.5.4(29): Integer Types
7928 An implementation for a two's complement machine should support
7929 modular types with a binary modulus up to @code{System.Max_Int*2+2}. An
7930 implementation should support a non-binary modules up to @code{Integer'Last}.
7934 @cindex Enumeration values
7935 @unnumberedsec 3.5.5(8): Enumeration Values
7938 For the evaluation of a call on @code{@var{S}'Pos} for an enumeration
7939 subtype, if the value of the operand does not correspond to the internal
7940 code for any enumeration literal of its type (perhaps due to an
7941 un-initialized variable), then the implementation should raise
7942 @code{Program_Error}. This is particularly important for enumeration
7943 types with noncontiguous internal codes specified by an
7944 enumeration_representation_clause.
7949 @unnumberedsec 3.5.7(17): Float Types
7952 An implementation should support @code{Long_Float} in addition to
7953 @code{Float} if the target machine supports 11 or more digits of
7954 precision. No other named floating point subtypes are recommended for
7955 package @code{Standard}. Instead, appropriate named floating point subtypes
7956 should be provided in the library package @code{Interfaces} (see B.2).
7958 @code{Short_Float} and @code{Long_Long_Float} are also provided. The
7959 former provides improved compatibility with other implementations
7960 supporting this type. The latter corresponds to the highest precision
7961 floating-point type supported by the hardware. On most machines, this
7962 will be the same as @code{Long_Float}, but on some machines, it will
7963 correspond to the IEEE extended form. The notable case is all ia32
7964 (x86) implementations, where @code{Long_Long_Float} corresponds to
7965 the 80-bit extended precision format supported in hardware on this
7966 processor. Note that the 128-bit format on SPARC is not supported,
7967 since this is a software rather than a hardware format.
7969 @cindex Multidimensional arrays
7970 @cindex Arrays, multidimensional
7971 @unnumberedsec 3.6.2(11): Multidimensional Arrays
7974 An implementation should normally represent multidimensional arrays in
7975 row-major order, consistent with the notation used for multidimensional
7976 array aggregates (see 4.3.3). However, if a pragma @code{Convention}
7977 (@code{Fortran}, @dots{}) applies to a multidimensional array type, then
7978 column-major order should be used instead (see B.5, ``Interfacing with
7983 @findex Duration'Small
7984 @unnumberedsec 9.6(30-31): Duration'Small
7987 Whenever possible in an implementation, the value of @code{Duration'Small}
7988 should be no greater than 100 microseconds.
7990 Followed. (@code{Duration'Small} = 10**(@minus{}9)).
7994 The time base for @code{delay_relative_statements} should be monotonic;
7995 it need not be the same time base as used for @code{Calendar.Clock}.
7999 @unnumberedsec 10.2.1(12): Consistent Representation
8002 In an implementation, a type declared in a pre-elaborated package should
8003 have the same representation in every elaboration of a given version of
8004 the package, whether the elaborations occur in distinct executions of
8005 the same program, or in executions of distinct programs or partitions
8006 that include the given version.
8008 Followed, except in the case of tagged types. Tagged types involve
8009 implicit pointers to a local copy of a dispatch table, and these pointers
8010 have representations which thus depend on a particular elaboration of the
8011 package. It is not easy to see how it would be possible to follow this
8012 advice without severely impacting efficiency of execution.
8014 @cindex Exception information
8015 @unnumberedsec 11.4.1(19): Exception Information
8018 @code{Exception_Message} by default and @code{Exception_Information}
8019 should produce information useful for
8020 debugging. @code{Exception_Message} should be short, about one
8021 line. @code{Exception_Information} can be long. @code{Exception_Message}
8022 should not include the
8023 @code{Exception_Name}. @code{Exception_Information} should include both
8024 the @code{Exception_Name} and the @code{Exception_Message}.
8026 Followed. For each exception that doesn't have a specified
8027 @code{Exception_Message}, the compiler generates one containing the location
8028 of the raise statement. This location has the form ``file:line'', where
8029 file is the short file name (without path information) and line is the line
8030 number in the file. Note that in the case of the Zero Cost Exception
8031 mechanism, these messages become redundant with the Exception_Information that
8032 contains a full backtrace of the calling sequence, so they are disabled.
8033 To disable explicitly the generation of the source location message, use the
8034 Pragma @code{Discard_Names}.
8036 @cindex Suppression of checks
8037 @cindex Checks, suppression of
8038 @unnumberedsec 11.5(28): Suppression of Checks
8041 The implementation should minimize the code executed for checks that
8042 have been suppressed.
8046 @cindex Representation clauses
8047 @unnumberedsec 13.1 (21-24): Representation Clauses
8050 The recommended level of support for all representation items is
8051 qualified as follows:
8055 An implementation need not support representation items containing
8056 non-static expressions, except that an implementation should support a
8057 representation item for a given entity if each non-static expression in
8058 the representation item is a name that statically denotes a constant
8059 declared before the entity.
8061 Followed. In fact, GNAT goes beyond the recommended level of support
8062 by allowing nonstatic expressions in some representation clauses even
8063 without the need to declare constants initialized with the values of
8067 @smallexample @c ada
8070 for Y'Address use X'Address;>>
8075 An implementation need not support a specification for the @code{Size}
8076 for a given composite subtype, nor the size or storage place for an
8077 object (including a component) of a given composite subtype, unless the
8078 constraints on the subtype and its composite subcomponents (if any) are
8079 all static constraints.
8081 Followed. Size Clauses are not permitted on non-static components, as
8086 An aliased component, or a component whose type is by-reference, should
8087 always be allocated at an addressable location.
8091 @cindex Packed types
8092 @unnumberedsec 13.2(6-8): Packed Types
8095 If a type is packed, then the implementation should try to minimize
8096 storage allocated to objects of the type, possibly at the expense of
8097 speed of accessing components, subject to reasonable complexity in
8098 addressing calculations.
8102 The recommended level of support pragma @code{Pack} is:
8104 For a packed record type, the components should be packed as tightly as
8105 possible subject to the Sizes of the component subtypes, and subject to
8106 any @code{record_representation_clause} that applies to the type; the
8107 implementation may, but need not, reorder components or cross aligned
8108 word boundaries to improve the packing. A component whose @code{Size} is
8109 greater than the word size may be allocated an integral number of words.
8111 Followed. Tight packing of arrays is supported for all component sizes
8112 up to 64-bits. If the array component size is 1 (that is to say, if
8113 the component is a boolean type or an enumeration type with two values)
8114 then values of the type are implicitly initialized to zero. This
8115 happens both for objects of the packed type, and for objects that have a
8116 subcomponent of the packed type.
8120 An implementation should support Address clauses for imported
8124 @cindex @code{Address} clauses
8125 @unnumberedsec 13.3(14-19): Address Clauses
8129 For an array @var{X}, @code{@var{X}'Address} should point at the first
8130 component of the array, and not at the array bounds.
8136 The recommended level of support for the @code{Address} attribute is:
8138 @code{@var{X}'Address} should produce a useful result if @var{X} is an
8139 object that is aliased or of a by-reference type, or is an entity whose
8140 @code{Address} has been specified.
8142 Followed. A valid address will be produced even if none of those
8143 conditions have been met. If necessary, the object is forced into
8144 memory to ensure the address is valid.
8148 An implementation should support @code{Address} clauses for imported
8155 Objects (including subcomponents) that are aliased or of a by-reference
8156 type should be allocated on storage element boundaries.
8162 If the @code{Address} of an object is specified, or it is imported or exported,
8163 then the implementation should not perform optimizations based on
8164 assumptions of no aliases.
8168 @cindex @code{Alignment} clauses
8169 @unnumberedsec 13.3(29-35): Alignment Clauses
8172 The recommended level of support for the @code{Alignment} attribute for
8175 An implementation should support specified Alignments that are factors
8176 and multiples of the number of storage elements per word, subject to the
8183 An implementation need not support specified @code{Alignment}s for
8184 combinations of @code{Size}s and @code{Alignment}s that cannot be easily
8185 loaded and stored by available machine instructions.
8191 An implementation need not support specified @code{Alignment}s that are
8192 greater than the maximum @code{Alignment} the implementation ever returns by
8199 The recommended level of support for the @code{Alignment} attribute for
8202 Same as above, for subtypes, but in addition:
8208 For stand-alone library-level objects of statically constrained
8209 subtypes, the implementation should support all @code{Alignment}s
8210 supported by the target linker. For example, page alignment is likely to
8211 be supported for such objects, but not for subtypes.
8215 @cindex @code{Size} clauses
8216 @unnumberedsec 13.3(42-43): Size Clauses
8219 The recommended level of support for the @code{Size} attribute of
8222 A @code{Size} clause should be supported for an object if the specified
8223 @code{Size} is at least as large as its subtype's @code{Size}, and
8224 corresponds to a size in storage elements that is a multiple of the
8225 object's @code{Alignment} (if the @code{Alignment} is nonzero).
8229 @unnumberedsec 13.3(50-56): Size Clauses
8232 If the @code{Size} of a subtype is specified, and allows for efficient
8233 independent addressability (see 9.10) on the target architecture, then
8234 the @code{Size} of the following objects of the subtype should equal the
8235 @code{Size} of the subtype:
8237 Aliased objects (including components).
8243 @code{Size} clause on a composite subtype should not affect the
8244 internal layout of components.
8246 Followed. But note that this can be overridden by use of the implementation
8247 pragma Implicit_Packing in the case of packed arrays.
8251 The recommended level of support for the @code{Size} attribute of subtypes is:
8255 The @code{Size} (if not specified) of a static discrete or fixed point
8256 subtype should be the number of bits needed to represent each value
8257 belonging to the subtype using an unbiased representation, leaving space
8258 for a sign bit only if the subtype contains negative values. If such a
8259 subtype is a first subtype, then an implementation should support a
8260 specified @code{Size} for it that reflects this representation.
8266 For a subtype implemented with levels of indirection, the @code{Size}
8267 should include the size of the pointers, but not the size of what they
8272 @cindex @code{Component_Size} clauses
8273 @unnumberedsec 13.3(71-73): Component Size Clauses
8276 The recommended level of support for the @code{Component_Size}
8281 An implementation need not support specified @code{Component_Sizes} that are
8282 less than the @code{Size} of the component subtype.
8288 An implementation should support specified @code{Component_Size}s that
8289 are factors and multiples of the word size. For such
8290 @code{Component_Size}s, the array should contain no gaps between
8291 components. For other @code{Component_Size}s (if supported), the array
8292 should contain no gaps between components when packing is also
8293 specified; the implementation should forbid this combination in cases
8294 where it cannot support a no-gaps representation.
8298 @cindex Enumeration representation clauses
8299 @cindex Representation clauses, enumeration
8300 @unnumberedsec 13.4(9-10): Enumeration Representation Clauses
8303 The recommended level of support for enumeration representation clauses
8306 An implementation need not support enumeration representation clauses
8307 for boolean types, but should at minimum support the internal codes in
8308 the range @code{System.Min_Int.System.Max_Int}.
8312 @cindex Record representation clauses
8313 @cindex Representation clauses, records
8314 @unnumberedsec 13.5.1(17-22): Record Representation Clauses
8317 The recommended level of support for
8318 @*@code{record_representation_clauses} is:
8320 An implementation should support storage places that can be extracted
8321 with a load, mask, shift sequence of machine code, and set with a load,
8322 shift, mask, store sequence, given the available machine instructions
8329 A storage place should be supported if its size is equal to the
8330 @code{Size} of the component subtype, and it starts and ends on a
8331 boundary that obeys the @code{Alignment} of the component subtype.
8337 If the default bit ordering applies to the declaration of a given type,
8338 then for a component whose subtype's @code{Size} is less than the word
8339 size, any storage place that does not cross an aligned word boundary
8340 should be supported.
8346 An implementation may reserve a storage place for the tag field of a
8347 tagged type, and disallow other components from overlapping that place.
8349 Followed. The storage place for the tag field is the beginning of the tagged
8350 record, and its size is Address'Size. GNAT will reject an explicit component
8351 clause for the tag field.
8355 An implementation need not support a @code{component_clause} for a
8356 component of an extension part if the storage place is not after the
8357 storage places of all components of the parent type, whether or not
8358 those storage places had been specified.
8360 Followed. The above advice on record representation clauses is followed,
8361 and all mentioned features are implemented.
8363 @cindex Storage place attributes
8364 @unnumberedsec 13.5.2(5): Storage Place Attributes
8367 If a component is represented using some form of pointer (such as an
8368 offset) to the actual data of the component, and this data is contiguous
8369 with the rest of the object, then the storage place attributes should
8370 reflect the place of the actual data, not the pointer. If a component is
8371 allocated discontinuously from the rest of the object, then a warning
8372 should be generated upon reference to one of its storage place
8375 Followed. There are no such components in GNAT@.
8377 @cindex Bit ordering
8378 @unnumberedsec 13.5.3(7-8): Bit Ordering
8381 The recommended level of support for the non-default bit ordering is:
8385 If @code{Word_Size} = @code{Storage_Unit}, then the implementation
8386 should support the non-default bit ordering in addition to the default
8389 Followed. Word size does not equal storage size in this implementation.
8390 Thus non-default bit ordering is not supported.
8392 @cindex @code{Address}, as private type
8393 @unnumberedsec 13.7(37): Address as Private
8396 @code{Address} should be of a private type.
8400 @cindex Operations, on @code{Address}
8401 @cindex @code{Address}, operations of
8402 @unnumberedsec 13.7.1(16): Address Operations
8405 Operations in @code{System} and its children should reflect the target
8406 environment semantics as closely as is reasonable. For example, on most
8407 machines, it makes sense for address arithmetic to ``wrap around''.
8408 Operations that do not make sense should raise @code{Program_Error}.
8410 Followed. Address arithmetic is modular arithmetic that wraps around. No
8411 operation raises @code{Program_Error}, since all operations make sense.
8413 @cindex Unchecked conversion
8414 @unnumberedsec 13.9(14-17): Unchecked Conversion
8417 The @code{Size} of an array object should not include its bounds; hence,
8418 the bounds should not be part of the converted data.
8424 The implementation should not generate unnecessary run-time checks to
8425 ensure that the representation of @var{S} is a representation of the
8426 target type. It should take advantage of the permission to return by
8427 reference when possible. Restrictions on unchecked conversions should be
8428 avoided unless required by the target environment.
8430 Followed. There are no restrictions on unchecked conversion. A warning is
8431 generated if the source and target types do not have the same size since
8432 the semantics in this case may be target dependent.
8436 The recommended level of support for unchecked conversions is:
8440 Unchecked conversions should be supported and should be reversible in
8441 the cases where this clause defines the result. To enable meaningful use
8442 of unchecked conversion, a contiguous representation should be used for
8443 elementary subtypes, for statically constrained array subtypes whose
8444 component subtype is one of the subtypes described in this paragraph,
8445 and for record subtypes without discriminants whose component subtypes
8446 are described in this paragraph.
8450 @cindex Heap usage, implicit
8451 @unnumberedsec 13.11(23-25): Implicit Heap Usage
8454 An implementation should document any cases in which it dynamically
8455 allocates heap storage for a purpose other than the evaluation of an
8458 Followed, the only other points at which heap storage is dynamically
8459 allocated are as follows:
8463 At initial elaboration time, to allocate dynamically sized global
8467 To allocate space for a task when a task is created.
8470 To extend the secondary stack dynamically when needed. The secondary
8471 stack is used for returning variable length results.
8476 A default (implementation-provided) storage pool for an
8477 access-to-constant type should not have overhead to support deallocation of
8484 A storage pool for an anonymous access type should be created at the
8485 point of an allocator for the type, and be reclaimed when the designated
8486 object becomes inaccessible.
8490 @cindex Unchecked deallocation
8491 @unnumberedsec 13.11.2(17): Unchecked De-allocation
8494 For a standard storage pool, @code{Free} should actually reclaim the
8499 @cindex Stream oriented attributes
8500 @unnumberedsec 13.13.2(17): Stream Oriented Attributes
8503 If a stream element is the same size as a storage element, then the
8504 normal in-memory representation should be used by @code{Read} and
8505 @code{Write} for scalar objects. Otherwise, @code{Read} and @code{Write}
8506 should use the smallest number of stream elements needed to represent
8507 all values in the base range of the scalar type.
8510 Followed. By default, GNAT uses the interpretation suggested by AI-195,
8511 which specifies using the size of the first subtype.
8512 However, such an implementation is based on direct binary
8513 representations and is therefore target- and endianness-dependent.
8514 To address this issue, GNAT also supplies an alternate implementation
8515 of the stream attributes @code{Read} and @code{Write},
8516 which uses the target-independent XDR standard representation
8518 @cindex XDR representation
8519 @cindex @code{Read} attribute
8520 @cindex @code{Write} attribute
8521 @cindex Stream oriented attributes
8522 The XDR implementation is provided as an alternative body of the
8523 @code{System.Stream_Attributes} package, in the file
8524 @file{s-stratt-xdr.adb} in the GNAT library.
8525 There is no @file{s-stratt-xdr.ads} file.
8526 In order to install the XDR implementation, do the following:
8528 @item Replace the default implementation of the
8529 @code{System.Stream_Attributes} package with the XDR implementation.
8530 For example on a Unix platform issue the commands:
8532 $ mv s-stratt.adb s-stratt-default.adb
8533 $ mv s-stratt-xdr.adb s-stratt.adb
8537 Rebuild the GNAT run-time library as documented in
8538 @ref{GNAT and Libraries,,, gnat_ugn, @value{EDITION} User's Guide}.
8541 @unnumberedsec A.1(52): Names of Predefined Numeric Types
8544 If an implementation provides additional named predefined integer types,
8545 then the names should end with @samp{Integer} as in
8546 @samp{Long_Integer}. If an implementation provides additional named
8547 predefined floating point types, then the names should end with
8548 @samp{Float} as in @samp{Long_Float}.
8552 @findex Ada.Characters.Handling
8553 @unnumberedsec A.3.2(49): @code{Ada.Characters.Handling}
8556 If an implementation provides a localized definition of @code{Character}
8557 or @code{Wide_Character}, then the effects of the subprograms in
8558 @code{Characters.Handling} should reflect the localizations. See also
8561 Followed. GNAT provides no such localized definitions.
8563 @cindex Bounded-length strings
8564 @unnumberedsec A.4.4(106): Bounded-Length String Handling
8567 Bounded string objects should not be implemented by implicit pointers
8568 and dynamic allocation.
8570 Followed. No implicit pointers or dynamic allocation are used.
8572 @cindex Random number generation
8573 @unnumberedsec A.5.2(46-47): Random Number Generation
8576 Any storage associated with an object of type @code{Generator} should be
8577 reclaimed on exit from the scope of the object.
8583 If the generator period is sufficiently long in relation to the number
8584 of distinct initiator values, then each possible value of
8585 @code{Initiator} passed to @code{Reset} should initiate a sequence of
8586 random numbers that does not, in a practical sense, overlap the sequence
8587 initiated by any other value. If this is not possible, then the mapping
8588 between initiator values and generator states should be a rapidly
8589 varying function of the initiator value.
8591 Followed. The generator period is sufficiently long for the first
8592 condition here to hold true.
8594 @findex Get_Immediate
8595 @unnumberedsec A.10.7(23): @code{Get_Immediate}
8598 The @code{Get_Immediate} procedures should be implemented with
8599 unbuffered input. For a device such as a keyboard, input should be
8600 @dfn{available} if a key has already been typed, whereas for a disk
8601 file, input should always be available except at end of file. For a file
8602 associated with a keyboard-like device, any line-editing features of the
8603 underlying operating system should be disabled during the execution of
8604 @code{Get_Immediate}.
8606 Followed on all targets except VxWorks. For VxWorks, there is no way to
8607 provide this functionality that does not result in the input buffer being
8608 flushed before the @code{Get_Immediate} call. A special unit
8609 @code{Interfaces.Vxworks.IO} is provided that contains routines to enable
8613 @unnumberedsec B.1(39-41): Pragma @code{Export}
8616 If an implementation supports pragma @code{Export} to a given language,
8617 then it should also allow the main subprogram to be written in that
8618 language. It should support some mechanism for invoking the elaboration
8619 of the Ada library units included in the system, and for invoking the
8620 finalization of the environment task. On typical systems, the
8621 recommended mechanism is to provide two subprograms whose link names are
8622 @code{adainit} and @code{adafinal}. @code{adainit} should contain the
8623 elaboration code for library units. @code{adafinal} should contain the
8624 finalization code. These subprograms should have no effect the second
8625 and subsequent time they are called.
8631 Automatic elaboration of pre-elaborated packages should be
8632 provided when pragma @code{Export} is supported.
8634 Followed when the main program is in Ada. If the main program is in a
8635 foreign language, then
8636 @code{adainit} must be called to elaborate pre-elaborated
8641 For each supported convention @var{L} other than @code{Intrinsic}, an
8642 implementation should support @code{Import} and @code{Export} pragmas
8643 for objects of @var{L}-compatible types and for subprograms, and pragma
8644 @code{Convention} for @var{L}-eligible types and for subprograms,
8645 presuming the other language has corresponding features. Pragma
8646 @code{Convention} need not be supported for scalar types.
8650 @cindex Package @code{Interfaces}
8652 @unnumberedsec B.2(12-13): Package @code{Interfaces}
8655 For each implementation-defined convention identifier, there should be a
8656 child package of package Interfaces with the corresponding name. This
8657 package should contain any declarations that would be useful for
8658 interfacing to the language (implementation) represented by the
8659 convention. Any declarations useful for interfacing to any language on
8660 the given hardware architecture should be provided directly in
8663 Followed. An additional package not defined
8664 in the Ada Reference Manual is @code{Interfaces.CPP}, used
8665 for interfacing to C++.
8669 An implementation supporting an interface to C, COBOL, or Fortran should
8670 provide the corresponding package or packages described in the following
8673 Followed. GNAT provides all the packages described in this section.
8675 @cindex C, interfacing with
8676 @unnumberedsec B.3(63-71): Interfacing with C
8679 An implementation should support the following interface correspondences
8686 An Ada procedure corresponds to a void-returning C function.
8692 An Ada function corresponds to a non-void C function.
8698 An Ada @code{in} scalar parameter is passed as a scalar argument to a C
8705 An Ada @code{in} parameter of an access-to-object type with designated
8706 type @var{T} is passed as a @code{@var{t}*} argument to a C function,
8707 where @var{t} is the C type corresponding to the Ada type @var{T}.
8713 An Ada access @var{T} parameter, or an Ada @code{out} or @code{in out}
8714 parameter of an elementary type @var{T}, is passed as a @code{@var{t}*}
8715 argument to a C function, where @var{t} is the C type corresponding to
8716 the Ada type @var{T}. In the case of an elementary @code{out} or
8717 @code{in out} parameter, a pointer to a temporary copy is used to
8718 preserve by-copy semantics.
8724 An Ada parameter of a record type @var{T}, of any mode, is passed as a
8725 @code{@var{t}*} argument to a C function, where @var{t} is the C
8726 structure corresponding to the Ada type @var{T}.
8728 Followed. This convention may be overridden by the use of the C_Pass_By_Copy
8729 pragma, or Convention, or by explicitly specifying the mechanism for a given
8730 call using an extended import or export pragma.
8734 An Ada parameter of an array type with component type @var{T}, of any
8735 mode, is passed as a @code{@var{t}*} argument to a C function, where
8736 @var{t} is the C type corresponding to the Ada type @var{T}.
8742 An Ada parameter of an access-to-subprogram type is passed as a pointer
8743 to a C function whose prototype corresponds to the designated
8744 subprogram's specification.
8748 @cindex COBOL, interfacing with
8749 @unnumberedsec B.4(95-98): Interfacing with COBOL
8752 An Ada implementation should support the following interface
8753 correspondences between Ada and COBOL@.
8759 An Ada access @var{T} parameter is passed as a @samp{BY REFERENCE} data item of
8760 the COBOL type corresponding to @var{T}.
8766 An Ada in scalar parameter is passed as a @samp{BY CONTENT} data item of
8767 the corresponding COBOL type.
8773 Any other Ada parameter is passed as a @samp{BY REFERENCE} data item of the
8774 COBOL type corresponding to the Ada parameter type; for scalars, a local
8775 copy is used if necessary to ensure by-copy semantics.
8779 @cindex Fortran, interfacing with
8780 @unnumberedsec B.5(22-26): Interfacing with Fortran
8783 An Ada implementation should support the following interface
8784 correspondences between Ada and Fortran:
8790 An Ada procedure corresponds to a Fortran subroutine.
8796 An Ada function corresponds to a Fortran function.
8802 An Ada parameter of an elementary, array, or record type @var{T} is
8803 passed as a @var{T} argument to a Fortran procedure, where @var{T} is
8804 the Fortran type corresponding to the Ada type @var{T}, and where the
8805 INTENT attribute of the corresponding dummy argument matches the Ada
8806 formal parameter mode; the Fortran implementation's parameter passing
8807 conventions are used. For elementary types, a local copy is used if
8808 necessary to ensure by-copy semantics.
8814 An Ada parameter of an access-to-subprogram type is passed as a
8815 reference to a Fortran procedure whose interface corresponds to the
8816 designated subprogram's specification.
8820 @cindex Machine operations
8821 @unnumberedsec C.1(3-5): Access to Machine Operations
8824 The machine code or intrinsic support should allow access to all
8825 operations normally available to assembly language programmers for the
8826 target environment, including privileged instructions, if any.
8832 The interfacing pragmas (see Annex B) should support interface to
8833 assembler; the default assembler should be associated with the
8834 convention identifier @code{Assembler}.
8840 If an entity is exported to assembly language, then the implementation
8841 should allocate it at an addressable location, and should ensure that it
8842 is retained by the linking process, even if not otherwise referenced
8843 from the Ada code. The implementation should assume that any call to a
8844 machine code or assembler subprogram is allowed to read or update every
8845 object that is specified as exported.
8849 @unnumberedsec C.1(10-16): Access to Machine Operations
8852 The implementation should ensure that little or no overhead is
8853 associated with calling intrinsic and machine-code subprograms.
8855 Followed for both intrinsics and machine-code subprograms.
8859 It is recommended that intrinsic subprograms be provided for convenient
8860 access to any machine operations that provide special capabilities or
8861 efficiency and that are not otherwise available through the language
8864 Followed. A full set of machine operation intrinsic subprograms is provided.
8868 Atomic read-modify-write operations---e.g.@:, test and set, compare and
8869 swap, decrement and test, enqueue/dequeue.
8871 Followed on any target supporting such operations.
8875 Standard numeric functions---e.g.@:, sin, log.
8877 Followed on any target supporting such operations.
8881 String manipulation operations---e.g.@:, translate and test.
8883 Followed on any target supporting such operations.
8887 Vector operations---e.g.@:, compare vector against thresholds.
8889 Followed on any target supporting such operations.
8893 Direct operations on I/O ports.
8895 Followed on any target supporting such operations.
8897 @cindex Interrupt support
8898 @unnumberedsec C.3(28): Interrupt Support
8901 If the @code{Ceiling_Locking} policy is not in effect, the
8902 implementation should provide means for the application to specify which
8903 interrupts are to be blocked during protected actions, if the underlying
8904 system allows for a finer-grain control of interrupt blocking.
8906 Followed. The underlying system does not allow for finer-grain control
8907 of interrupt blocking.
8909 @cindex Protected procedure handlers
8910 @unnumberedsec C.3.1(20-21): Protected Procedure Handlers
8913 Whenever possible, the implementation should allow interrupt handlers to
8914 be called directly by the hardware.
8918 This is never possible under IRIX, so this is followed by default.
8920 Followed on any target where the underlying operating system permits
8925 Whenever practical, violations of any
8926 implementation-defined restrictions should be detected before run time.
8928 Followed. Compile time warnings are given when possible.
8930 @cindex Package @code{Interrupts}
8932 @unnumberedsec C.3.2(25): Package @code{Interrupts}
8936 If implementation-defined forms of interrupt handler procedures are
8937 supported, such as protected procedures with parameters, then for each
8938 such form of a handler, a type analogous to @code{Parameterless_Handler}
8939 should be specified in a child package of @code{Interrupts}, with the
8940 same operations as in the predefined package Interrupts.
8944 @cindex Pre-elaboration requirements
8945 @unnumberedsec C.4(14): Pre-elaboration Requirements
8948 It is recommended that pre-elaborated packages be implemented in such a
8949 way that there should be little or no code executed at run time for the
8950 elaboration of entities not already covered by the Implementation
8953 Followed. Executable code is generated in some cases, e.g.@: loops
8954 to initialize large arrays.
8956 @unnumberedsec C.5(8): Pragma @code{Discard_Names}
8959 If the pragma applies to an entity, then the implementation should
8960 reduce the amount of storage used for storing names associated with that
8965 @cindex Package @code{Task_Attributes}
8966 @findex Task_Attributes
8967 @unnumberedsec C.7.2(30): The Package Task_Attributes
8970 Some implementations are targeted to domains in which memory use at run
8971 time must be completely deterministic. For such implementations, it is
8972 recommended that the storage for task attributes will be pre-allocated
8973 statically and not from the heap. This can be accomplished by either
8974 placing restrictions on the number and the size of the task's
8975 attributes, or by using the pre-allocated storage for the first @var{N}
8976 attribute objects, and the heap for the others. In the latter case,
8977 @var{N} should be documented.
8979 Not followed. This implementation is not targeted to such a domain.
8981 @cindex Locking Policies
8982 @unnumberedsec D.3(17): Locking Policies
8986 The implementation should use names that end with @samp{_Locking} for
8987 locking policies defined by the implementation.
8989 Followed. Two implementation-defined locking policies are defined,
8990 whose names (@code{Inheritance_Locking} and
8991 @code{Concurrent_Readers_Locking}) follow this suggestion.
8993 @cindex Entry queuing policies
8994 @unnumberedsec D.4(16): Entry Queuing Policies
8997 Names that end with @samp{_Queuing} should be used
8998 for all implementation-defined queuing policies.
9000 Followed. No such implementation-defined queuing policies exist.
9002 @cindex Preemptive abort
9003 @unnumberedsec D.6(9-10): Preemptive Abort
9006 Even though the @code{abort_statement} is included in the list of
9007 potentially blocking operations (see 9.5.1), it is recommended that this
9008 statement be implemented in a way that never requires the task executing
9009 the @code{abort_statement} to block.
9015 On a multi-processor, the delay associated with aborting a task on
9016 another processor should be bounded; the implementation should use
9017 periodic polling, if necessary, to achieve this.
9021 @cindex Tasking restrictions
9022 @unnumberedsec D.7(21): Tasking Restrictions
9025 When feasible, the implementation should take advantage of the specified
9026 restrictions to produce a more efficient implementation.
9028 GNAT currently takes advantage of these restrictions by providing an optimized
9029 run time when the Ravenscar profile and the GNAT restricted run time set
9030 of restrictions are specified. See pragma @code{Profile (Ravenscar)} and
9031 pragma @code{Profile (Restricted)} for more details.
9033 @cindex Time, monotonic
9034 @unnumberedsec D.8(47-49): Monotonic Time
9037 When appropriate, implementations should provide configuration
9038 mechanisms to change the value of @code{Tick}.
9040 Such configuration mechanisms are not appropriate to this implementation
9041 and are thus not supported.
9045 It is recommended that @code{Calendar.Clock} and @code{Real_Time.Clock}
9046 be implemented as transformations of the same time base.
9052 It is recommended that the @dfn{best} time base which exists in
9053 the underlying system be available to the application through
9054 @code{Clock}. @dfn{Best} may mean highest accuracy or largest range.
9058 @cindex Partition communication subsystem
9060 @unnumberedsec E.5(28-29): Partition Communication Subsystem
9063 Whenever possible, the PCS on the called partition should allow for
9064 multiple tasks to call the RPC-receiver with different messages and
9065 should allow them to block until the corresponding subprogram body
9068 Followed by GLADE, a separately supplied PCS that can be used with
9073 The @code{Write} operation on a stream of type @code{Params_Stream_Type}
9074 should raise @code{Storage_Error} if it runs out of space trying to
9075 write the @code{Item} into the stream.
9077 Followed by GLADE, a separately supplied PCS that can be used with
9080 @cindex COBOL support
9081 @unnumberedsec F(7): COBOL Support
9084 If COBOL (respectively, C) is widely supported in the target
9085 environment, implementations supporting the Information Systems Annex
9086 should provide the child package @code{Interfaces.COBOL} (respectively,
9087 @code{Interfaces.C}) specified in Annex B and should support a
9088 @code{convention_identifier} of COBOL (respectively, C) in the interfacing
9089 pragmas (see Annex B), thus allowing Ada programs to interface with
9090 programs written in that language.
9094 @cindex Decimal radix support
9095 @unnumberedsec F.1(2): Decimal Radix Support
9098 Packed decimal should be used as the internal representation for objects
9099 of subtype @var{S} when @var{S}'Machine_Radix = 10.
9101 Not followed. GNAT ignores @var{S}'Machine_Radix and always uses binary
9105 @unnumberedsec G: Numerics
9108 If Fortran (respectively, C) is widely supported in the target
9109 environment, implementations supporting the Numerics Annex
9110 should provide the child package @code{Interfaces.Fortran} (respectively,
9111 @code{Interfaces.C}) specified in Annex B and should support a
9112 @code{convention_identifier} of Fortran (respectively, C) in the interfacing
9113 pragmas (see Annex B), thus allowing Ada programs to interface with
9114 programs written in that language.
9118 @cindex Complex types
9119 @unnumberedsec G.1.1(56-58): Complex Types
9122 Because the usual mathematical meaning of multiplication of a complex
9123 operand and a real operand is that of the scaling of both components of
9124 the former by the latter, an implementation should not perform this
9125 operation by first promoting the real operand to complex type and then
9126 performing a full complex multiplication. In systems that, in the
9127 future, support an Ada binding to IEC 559:1989, the latter technique
9128 will not generate the required result when one of the components of the
9129 complex operand is infinite. (Explicit multiplication of the infinite
9130 component by the zero component obtained during promotion yields a NaN
9131 that propagates into the final result.) Analogous advice applies in the
9132 case of multiplication of a complex operand and a pure-imaginary
9133 operand, and in the case of division of a complex operand by a real or
9134 pure-imaginary operand.
9140 Similarly, because the usual mathematical meaning of addition of a
9141 complex operand and a real operand is that the imaginary operand remains
9142 unchanged, an implementation should not perform this operation by first
9143 promoting the real operand to complex type and then performing a full
9144 complex addition. In implementations in which the @code{Signed_Zeros}
9145 attribute of the component type is @code{True} (and which therefore
9146 conform to IEC 559:1989 in regard to the handling of the sign of zero in
9147 predefined arithmetic operations), the latter technique will not
9148 generate the required result when the imaginary component of the complex
9149 operand is a negatively signed zero. (Explicit addition of the negative
9150 zero to the zero obtained during promotion yields a positive zero.)
9151 Analogous advice applies in the case of addition of a complex operand
9152 and a pure-imaginary operand, and in the case of subtraction of a
9153 complex operand and a real or pure-imaginary operand.
9159 Implementations in which @code{Real'Signed_Zeros} is @code{True} should
9160 attempt to provide a rational treatment of the signs of zero results and
9161 result components. As one example, the result of the @code{Argument}
9162 function should have the sign of the imaginary component of the
9163 parameter @code{X} when the point represented by that parameter lies on
9164 the positive real axis; as another, the sign of the imaginary component
9165 of the @code{Compose_From_Polar} function should be the same as
9166 (respectively, the opposite of) that of the @code{Argument} parameter when that
9167 parameter has a value of zero and the @code{Modulus} parameter has a
9168 nonnegative (respectively, negative) value.
9172 @cindex Complex elementary functions
9173 @unnumberedsec G.1.2(49): Complex Elementary Functions
9176 Implementations in which @code{Complex_Types.Real'Signed_Zeros} is
9177 @code{True} should attempt to provide a rational treatment of the signs
9178 of zero results and result components. For example, many of the complex
9179 elementary functions have components that are odd functions of one of
9180 the parameter components; in these cases, the result component should
9181 have the sign of the parameter component at the origin. Other complex
9182 elementary functions have zero components whose sign is opposite that of
9183 a parameter component at the origin, or is always positive or always
9188 @cindex Accuracy requirements
9189 @unnumberedsec G.2.4(19): Accuracy Requirements
9192 The versions of the forward trigonometric functions without a
9193 @code{Cycle} parameter should not be implemented by calling the
9194 corresponding version with a @code{Cycle} parameter of
9195 @code{2.0*Numerics.Pi}, since this will not provide the required
9196 accuracy in some portions of the domain. For the same reason, the
9197 version of @code{Log} without a @code{Base} parameter should not be
9198 implemented by calling the corresponding version with a @code{Base}
9199 parameter of @code{Numerics.e}.
9203 @cindex Complex arithmetic accuracy
9204 @cindex Accuracy, complex arithmetic
9205 @unnumberedsec G.2.6(15): Complex Arithmetic Accuracy
9209 The version of the @code{Compose_From_Polar} function without a
9210 @code{Cycle} parameter should not be implemented by calling the
9211 corresponding version with a @code{Cycle} parameter of
9212 @code{2.0*Numerics.Pi}, since this will not provide the required
9213 accuracy in some portions of the domain.
9217 @c -----------------------------------------
9218 @node Implementation Defined Characteristics
9219 @chapter Implementation Defined Characteristics
9222 In addition to the implementation dependent pragmas and attributes, and the
9223 implementation advice, there are a number of other Ada features that are
9224 potentially implementation dependent and are designated as
9225 implementation-defined. These are mentioned throughout the Ada Reference
9226 Manual, and are summarized in Annex M@.
9228 A requirement for conforming Ada compilers is that they provide
9229 documentation describing how the implementation deals with each of these
9230 issues. In this chapter, you will find each point in Annex M listed
9231 followed by a description in italic font of how GNAT
9235 implementation on IRIX 5.3 operating system or greater
9237 handles the implementation dependence.
9239 You can use this chapter as a guide to minimizing implementation
9240 dependent features in your programs if portability to other compilers
9241 and other operating systems is an important consideration. The numbers
9242 in each section below correspond to the paragraph number in the Ada
9248 @strong{2}. Whether or not each recommendation given in Implementation
9249 Advice is followed. See 1.1.2(37).
9252 @xref{Implementation Advice}.
9257 @strong{3}. Capacity limitations of the implementation. See 1.1.3(3).
9260 The complexity of programs that can be processed is limited only by the
9261 total amount of available virtual memory, and disk space for the
9262 generated object files.
9267 @strong{4}. Variations from the standard that are impractical to avoid
9268 given the implementation's execution environment. See 1.1.3(6).
9271 There are no variations from the standard.
9276 @strong{5}. Which @code{code_statement}s cause external
9277 interactions. See 1.1.3(10).
9280 Any @code{code_statement} can potentially cause external interactions.
9285 @strong{6}. The coded representation for the text of an Ada
9286 program. See 2.1(4).
9289 See separate section on source representation.
9294 @strong{7}. The control functions allowed in comments. See 2.1(14).
9297 See separate section on source representation.
9302 @strong{8}. The representation for an end of line. See 2.2(2).
9305 See separate section on source representation.
9310 @strong{9}. Maximum supported line length and lexical element
9311 length. See 2.2(15).
9314 The maximum line length is 255 characters and the maximum length of a
9315 lexical element is also 255 characters.
9320 @strong{10}. Implementation defined pragmas. See 2.8(14).
9324 @xref{Implementation Defined Pragmas}.
9329 @strong{11}. Effect of pragma @code{Optimize}. See 2.8(27).
9332 Pragma @code{Optimize}, if given with a @code{Time} or @code{Space}
9333 parameter, checks that the optimization flag is set, and aborts if it is
9339 @strong{12}. The sequence of characters of the value returned by
9340 @code{@var{S}'Image} when some of the graphic characters of
9341 @code{@var{S}'Wide_Image} are not defined in @code{Character}. See
9345 The sequence of characters is as defined by the wide character encoding
9346 method used for the source. See section on source representation for
9352 @strong{13}. The predefined integer types declared in
9353 @code{Standard}. See 3.5.4(25).
9357 @item Short_Short_Integer
9360 (Short) 16 bit signed
9364 64 bit signed (on most 64 bit targets, depending on the C definition of long).
9365 32 bit signed (all other targets)
9366 @item Long_Long_Integer
9373 @strong{14}. Any nonstandard integer types and the operators defined
9374 for them. See 3.5.4(26).
9377 There are no nonstandard integer types.
9382 @strong{15}. Any nonstandard real types and the operators defined for
9386 There are no nonstandard real types.
9391 @strong{16}. What combinations of requested decimal precision and range
9392 are supported for floating point types. See 3.5.7(7).
9395 The precision and range is as defined by the IEEE standard.
9400 @strong{17}. The predefined floating point types declared in
9401 @code{Standard}. See 3.5.7(16).
9408 (Short) 32 bit IEEE short
9411 @item Long_Long_Float
9412 64 bit IEEE long (80 bit IEEE long on x86 processors)
9418 @strong{18}. The small of an ordinary fixed point type. See 3.5.9(8).
9421 @code{Fine_Delta} is 2**(@minus{}63)
9426 @strong{19}. What combinations of small, range, and digits are
9427 supported for fixed point types. See 3.5.9(10).
9430 Any combinations are permitted that do not result in a small less than
9431 @code{Fine_Delta} and do not result in a mantissa larger than 63 bits.
9432 If the mantissa is larger than 53 bits on machines where Long_Long_Float
9433 is 64 bits (true of all architectures except ia32), then the output from
9434 Text_IO is accurate to only 53 bits, rather than the full mantissa. This
9435 is because floating-point conversions are used to convert fixed point.
9440 @strong{20}. The result of @code{Tags.Expanded_Name} for types declared
9441 within an unnamed @code{block_statement}. See 3.9(10).
9444 Block numbers of the form @code{B@var{nnn}}, where @var{nnn} is a
9445 decimal integer are allocated.
9450 @strong{21}. Implementation-defined attributes. See 4.1.4(12).
9453 @xref{Implementation Defined Attributes}.
9458 @strong{22}. Any implementation-defined time types. See 9.6(6).
9461 There are no implementation-defined time types.
9466 @strong{23}. The time base associated with relative delays.
9469 See 9.6(20). The time base used is that provided by the C library
9470 function @code{gettimeofday}.
9475 @strong{24}. The time base of the type @code{Calendar.Time}. See
9479 The time base used is that provided by the C library function
9480 @code{gettimeofday}.
9485 @strong{25}. The time zone used for package @code{Calendar}
9486 operations. See 9.6(24).
9489 The time zone used by package @code{Calendar} is the current system time zone
9490 setting for local time, as accessed by the C library function
9496 @strong{26}. Any limit on @code{delay_until_statements} of
9497 @code{select_statements}. See 9.6(29).
9500 There are no such limits.
9505 @strong{27}. Whether or not two non-overlapping parts of a composite
9506 object are independently addressable, in the case where packing, record
9507 layout, or @code{Component_Size} is specified for the object. See
9511 Separate components are independently addressable if they do not share
9512 overlapping storage units.
9517 @strong{28}. The representation for a compilation. See 10.1(2).
9520 A compilation is represented by a sequence of files presented to the
9521 compiler in a single invocation of the @command{gcc} command.
9526 @strong{29}. Any restrictions on compilations that contain multiple
9527 compilation_units. See 10.1(4).
9530 No single file can contain more than one compilation unit, but any
9531 sequence of files can be presented to the compiler as a single
9537 @strong{30}. The mechanisms for creating an environment and for adding
9538 and replacing compilation units. See 10.1.4(3).
9541 See separate section on compilation model.
9546 @strong{31}. The manner of explicitly assigning library units to a
9547 partition. See 10.2(2).
9550 If a unit contains an Ada main program, then the Ada units for the partition
9551 are determined by recursive application of the rules in the Ada Reference
9552 Manual section 10.2(2-6). In other words, the Ada units will be those that
9553 are needed by the main program, and then this definition of need is applied
9554 recursively to those units, and the partition contains the transitive
9555 closure determined by this relationship. In short, all the necessary units
9556 are included, with no need to explicitly specify the list. If additional
9557 units are required, e.g.@: by foreign language units, then all units must be
9558 mentioned in the context clause of one of the needed Ada units.
9560 If the partition contains no main program, or if the main program is in
9561 a language other than Ada, then GNAT
9562 provides the binder options @option{-z} and @option{-n} respectively, and in
9563 this case a list of units can be explicitly supplied to the binder for
9564 inclusion in the partition (all units needed by these units will also
9565 be included automatically). For full details on the use of these
9566 options, refer to @ref{The GNAT Make Program gnatmake,,, gnat_ugn,
9567 @value{EDITION} User's Guide}.
9572 @strong{32}. The implementation-defined means, if any, of specifying
9573 which compilation units are needed by a given compilation unit. See
9577 The units needed by a given compilation unit are as defined in
9578 the Ada Reference Manual section 10.2(2-6). There are no
9579 implementation-defined pragmas or other implementation-defined
9580 means for specifying needed units.
9585 @strong{33}. The manner of designating the main subprogram of a
9586 partition. See 10.2(7).
9589 The main program is designated by providing the name of the
9590 corresponding @file{ALI} file as the input parameter to the binder.
9595 @strong{34}. The order of elaboration of @code{library_items}. See
9599 The first constraint on ordering is that it meets the requirements of
9600 Chapter 10 of the Ada Reference Manual. This still leaves some
9601 implementation dependent choices, which are resolved by first
9602 elaborating bodies as early as possible (i.e., in preference to specs
9603 where there is a choice), and second by evaluating the immediate with
9604 clauses of a unit to determine the probably best choice, and
9605 third by elaborating in alphabetical order of unit names
9606 where a choice still remains.
9611 @strong{35}. Parameter passing and function return for the main
9612 subprogram. See 10.2(21).
9615 The main program has no parameters. It may be a procedure, or a function
9616 returning an integer type. In the latter case, the returned integer
9617 value is the return code of the program (overriding any value that
9618 may have been set by a call to @code{Ada.Command_Line.Set_Exit_Status}).
9623 @strong{36}. The mechanisms for building and running partitions. See
9627 GNAT itself supports programs with only a single partition. The GNATDIST
9628 tool provided with the GLADE package (which also includes an implementation
9629 of the PCS) provides a completely flexible method for building and running
9630 programs consisting of multiple partitions. See the separate GLADE manual
9636 @strong{37}. The details of program execution, including program
9637 termination. See 10.2(25).
9640 See separate section on compilation model.
9645 @strong{38}. The semantics of any non-active partitions supported by the
9646 implementation. See 10.2(28).
9649 Passive partitions are supported on targets where shared memory is
9650 provided by the operating system. See the GLADE reference manual for
9656 @strong{39}. The information returned by @code{Exception_Message}. See
9660 Exception message returns the null string unless a specific message has
9661 been passed by the program.
9666 @strong{40}. The result of @code{Exceptions.Exception_Name} for types
9667 declared within an unnamed @code{block_statement}. See 11.4.1(12).
9670 Blocks have implementation defined names of the form @code{B@var{nnn}}
9671 where @var{nnn} is an integer.
9676 @strong{41}. The information returned by
9677 @code{Exception_Information}. See 11.4.1(13).
9680 @code{Exception_Information} returns a string in the following format:
9683 @emph{Exception_Name:} nnnnn
9684 @emph{Message:} mmmmm
9686 @emph{Call stack traceback locations:}
9687 0xhhhh 0xhhhh 0xhhhh ... 0xhhh
9695 @code{nnnn} is the fully qualified name of the exception in all upper
9696 case letters. This line is always present.
9699 @code{mmmm} is the message (this line present only if message is non-null)
9702 @code{ppp} is the Process Id value as a decimal integer (this line is
9703 present only if the Process Id is nonzero). Currently we are
9704 not making use of this field.
9707 The Call stack traceback locations line and the following values
9708 are present only if at least one traceback location was recorded.
9709 The values are given in C style format, with lower case letters
9710 for a-f, and only as many digits present as are necessary.
9714 The line terminator sequence at the end of each line, including
9715 the last line is a single @code{LF} character (@code{16#0A#}).
9720 @strong{42}. Implementation-defined check names. See 11.5(27).
9723 The implementation defined check name Alignment_Check controls checking of
9724 address clause values for proper alignment (that is, the address supplied
9725 must be consistent with the alignment of the type).
9727 In addition, a user program can add implementation-defined check names
9728 by means of the pragma Check_Name.
9733 @strong{43}. The interpretation of each aspect of representation. See
9737 See separate section on data representations.
9742 @strong{44}. Any restrictions placed upon representation items. See
9746 See separate section on data representations.
9751 @strong{45}. The meaning of @code{Size} for indefinite subtypes. See
9755 Size for an indefinite subtype is the maximum possible size, except that
9756 for the case of a subprogram parameter, the size of the parameter object
9762 @strong{46}. The default external representation for a type tag. See
9766 The default external representation for a type tag is the fully expanded
9767 name of the type in upper case letters.
9772 @strong{47}. What determines whether a compilation unit is the same in
9773 two different partitions. See 13.3(76).
9776 A compilation unit is the same in two different partitions if and only
9777 if it derives from the same source file.
9782 @strong{48}. Implementation-defined components. See 13.5.1(15).
9785 The only implementation defined component is the tag for a tagged type,
9786 which contains a pointer to the dispatching table.
9791 @strong{49}. If @code{Word_Size} = @code{Storage_Unit}, the default bit
9792 ordering. See 13.5.3(5).
9795 @code{Word_Size} (32) is not the same as @code{Storage_Unit} (8) for this
9796 implementation, so no non-default bit ordering is supported. The default
9797 bit ordering corresponds to the natural endianness of the target architecture.
9802 @strong{50}. The contents of the visible part of package @code{System}
9803 and its language-defined children. See 13.7(2).
9806 See the definition of these packages in files @file{system.ads} and
9807 @file{s-stoele.ads}.
9812 @strong{51}. The contents of the visible part of package
9813 @code{System.Machine_Code}, and the meaning of
9814 @code{code_statements}. See 13.8(7).
9817 See the definition and documentation in file @file{s-maccod.ads}.
9822 @strong{52}. The effect of unchecked conversion. See 13.9(11).
9825 Unchecked conversion between types of the same size
9826 results in an uninterpreted transmission of the bits from one type
9827 to the other. If the types are of unequal sizes, then in the case of
9828 discrete types, a shorter source is first zero or sign extended as
9829 necessary, and a shorter target is simply truncated on the left.
9830 For all non-discrete types, the source is first copied if necessary
9831 to ensure that the alignment requirements of the target are met, then
9832 a pointer is constructed to the source value, and the result is obtained
9833 by dereferencing this pointer after converting it to be a pointer to the
9834 target type. Unchecked conversions where the target subtype is an
9835 unconstrained array are not permitted. If the target alignment is
9836 greater than the source alignment, then a copy of the result is
9837 made with appropriate alignment
9842 @strong{53}. The semantics of operations on invalid representations.
9846 For assignments and other operations where the use of invalid values cannot
9847 result in erroneous behavior, the compiler ignores the possibility of invalid
9848 values. An exception is raised at the point where an invalid value would
9849 result in erroneous behavior. For example executing:
9851 @smallexample @c ada
9852 procedure invalidvals is
9854 Y : Natural range 1 .. 10;
9855 for Y'Address use X'Address;
9856 Z : Natural range 1 .. 10;
9857 A : array (Natural range 1 .. 10) of Integer;
9859 Z := Y; -- no exception
9860 A (Z) := 3; -- exception raised;
9865 As indicated, an exception is raised on the array assignment, but not
9866 on the simple assignment of the invalid negative value from Y to Z.
9871 @strong{53}. The manner of choosing a storage pool for an access type
9872 when @code{Storage_Pool} is not specified for the type. See 13.11(17).
9875 There are 3 different standard pools used by the compiler when
9876 @code{Storage_Pool} is not specified depending whether the type is local
9877 to a subprogram or defined at the library level and whether
9878 @code{Storage_Size}is specified or not. See documentation in the runtime
9879 library units @code{System.Pool_Global}, @code{System.Pool_Size} and
9880 @code{System.Pool_Local} in files @file{s-poosiz.ads},
9881 @file{s-pooglo.ads} and @file{s-pooloc.ads} for full details on the
9887 @strong{54}. Whether or not the implementation provides user-accessible
9888 names for the standard pool type(s). See 13.11(17).
9892 See documentation in the sources of the run time mentioned in paragraph
9893 @strong{53} . All these pools are accessible by means of @code{with}'ing
9899 @strong{55}. The meaning of @code{Storage_Size}. See 13.11(18).
9902 @code{Storage_Size} is measured in storage units, and refers to the
9903 total space available for an access type collection, or to the primary
9904 stack space for a task.
9909 @strong{56}. Implementation-defined aspects of storage pools. See
9913 See documentation in the sources of the run time mentioned in paragraph
9914 @strong{53} for details on GNAT-defined aspects of storage pools.
9919 @strong{57}. The set of restrictions allowed in a pragma
9920 @code{Restrictions}. See 13.12(7).
9923 @xref{Implementation Defined Restrictions}.
9928 @strong{58}. The consequences of violating limitations on
9929 @code{Restrictions} pragmas. See 13.12(9).
9932 Restrictions that can be checked at compile time result in illegalities
9933 if violated. Currently there are no other consequences of violating
9939 @strong{59}. The representation used by the @code{Read} and
9940 @code{Write} attributes of elementary types in terms of stream
9941 elements. See 13.13.2(9).
9944 The representation is the in-memory representation of the base type of
9945 the type, using the number of bits corresponding to the
9946 @code{@var{type}'Size} value, and the natural ordering of the machine.
9951 @strong{60}. The names and characteristics of the numeric subtypes
9952 declared in the visible part of package @code{Standard}. See A.1(3).
9955 See items describing the integer and floating-point types supported.
9960 @strong{61}. The accuracy actually achieved by the elementary
9961 functions. See A.5.1(1).
9964 The elementary functions correspond to the functions available in the C
9965 library. Only fast math mode is implemented.
9970 @strong{62}. The sign of a zero result from some of the operators or
9971 functions in @code{Numerics.Generic_Elementary_Functions}, when
9972 @code{Float_Type'Signed_Zeros} is @code{True}. See A.5.1(46).
9975 The sign of zeroes follows the requirements of the IEEE 754 standard on
9981 @strong{63}. The value of
9982 @code{Numerics.Float_Random.Max_Image_Width}. See A.5.2(27).
9985 Maximum image width is 6864, see library file @file{s-rannum.ads}.
9990 @strong{64}. The value of
9991 @code{Numerics.Discrete_Random.Max_Image_Width}. See A.5.2(27).
9994 Maximum image width is 6864, see library file @file{s-rannum.ads}.
9999 @strong{65}. The algorithms for random number generation. See
10003 The algorithm is the Mersenne Twister, as documented in the source file
10004 @file{s-rannum.adb}. This version of the algorithm has a period of
10010 @strong{66}. The string representation of a random number generator's
10011 state. See A.5.2(38).
10014 The value returned by the Image function is the concatenation of
10015 the fixed-width decimal representations of the 624 32-bit integers
10016 of the state vector.
10021 @strong{67}. The minimum time interval between calls to the
10022 time-dependent Reset procedure that are guaranteed to initiate different
10023 random number sequences. See A.5.2(45).
10026 The minimum period between reset calls to guarantee distinct series of
10027 random numbers is one microsecond.
10032 @strong{68}. The values of the @code{Model_Mantissa},
10033 @code{Model_Emin}, @code{Model_Epsilon}, @code{Model},
10034 @code{Safe_First}, and @code{Safe_Last} attributes, if the Numerics
10035 Annex is not supported. See A.5.3(72).
10038 Run the compiler with @option{-gnatS} to produce a listing of package
10039 @code{Standard}, has the values of all numeric attributes.
10044 @strong{69}. Any implementation-defined characteristics of the
10045 input-output packages. See A.7(14).
10048 There are no special implementation defined characteristics for these
10054 @strong{70}. The value of @code{Buffer_Size} in @code{Storage_IO}. See
10058 All type representations are contiguous, and the @code{Buffer_Size} is
10059 the value of @code{@var{type}'Size} rounded up to the next storage unit
10065 @strong{71}. External files for standard input, standard output, and
10066 standard error See A.10(5).
10069 These files are mapped onto the files provided by the C streams
10070 libraries. See source file @file{i-cstrea.ads} for further details.
10075 @strong{72}. The accuracy of the value produced by @code{Put}. See
10079 If more digits are requested in the output than are represented by the
10080 precision of the value, zeroes are output in the corresponding least
10081 significant digit positions.
10086 @strong{73}. The meaning of @code{Argument_Count}, @code{Argument}, and
10087 @code{Command_Name}. See A.15(1).
10090 These are mapped onto the @code{argv} and @code{argc} parameters of the
10091 main program in the natural manner.
10096 @strong{74}. The interpretation of the @code{Form} parameter in procedure
10097 @code{Create_Directory}. See A.16(56).
10100 The @code{Form} parameter is not used.
10105 @strong{75}. The interpretation of the @code{Form} parameter in procedure
10106 @code{Create_Path}. See A.16(60).
10109 The @code{Form} parameter is not used.
10114 @strong{76}. The interpretation of the @code{Form} parameter in procedure
10115 @code{Copy_File}. See A.16(68).
10118 The @code{Form} parameter is case-insensitive.
10120 Two fields are recognized in the @code{Form} parameter:
10124 @item preserve=<value>
10131 <value> starts immediately after the character '=' and ends with the
10132 character immediately preceding the next comma (',') or with the last
10133 character of the parameter.
10135 The only possible values for preserve= are:
10139 @item no_attributes
10140 Do not try to preserve any file attributes. This is the default if no
10141 preserve= is found in Form.
10143 @item all_attributes
10144 Try to preserve all file attributes (timestamps, access rights).
10147 Preserve the timestamp of the copied file, but not the other file attributes.
10152 The only possible values for mode= are:
10157 Only do the copy if the destination file does not already exist. If it already
10158 exists, Copy_File fails.
10161 Copy the file in all cases. Overwrite an already existing destination file.
10164 Append the original file to the destination file. If the destination file does
10165 not exist, the destination file is a copy of the source file. When mode=append,
10166 the field preserve=, if it exists, is not taken into account.
10171 If the Form parameter includes one or both of the fields and the value or
10172 values are incorrect, Copy_file fails with Use_Error.
10174 Examples of correct Forms:
10177 Form => "preserve=no_attributes,mode=overwrite" (the default)
10178 Form => "mode=append"
10179 Form => "mode=copy, preserve=all_attributes"
10183 Examples of incorrect Forms
10186 Form => "preserve=junk"
10187 Form => "mode=internal, preserve=timestamps"
10193 @strong{77}. Implementation-defined convention names. See B.1(11).
10196 The following convention names are supported
10201 @item Ada_Pass_By_Copy
10202 Allowed for any types except by-reference types such as limited
10203 records. Compatible with convention Ada, but causes any parameters
10204 with this convention to be passed by copy.
10205 @item Ada_Pass_By_Reference
10206 Allowed for any types except by-copy types such as scalars.
10207 Compatible with convention Ada, but causes any parameters
10208 with this convention to be passed by reference.
10212 Synonym for Assembler
10214 Synonym for Assembler
10217 @item C_Pass_By_Copy
10218 Allowed only for record types, like C, but also notes that record
10219 is to be passed by copy rather than reference.
10222 @item C_Plus_Plus (or CPP)
10225 Treated the same as C
10227 Treated the same as C
10231 For support of pragma @code{Import} with convention Intrinsic, see
10232 separate section on Intrinsic Subprograms.
10234 Stdcall (used for Windows implementations only). This convention correspond
10235 to the WINAPI (previously called Pascal convention) C/C++ convention under
10236 Windows. A routine with this convention cleans the stack before
10237 exit. This pragma cannot be applied to a dispatching call.
10239 Synonym for Stdcall
10241 Synonym for Stdcall
10243 Stubbed is a special convention used to indicate that the body of the
10244 subprogram will be entirely ignored. Any call to the subprogram
10245 is converted into a raise of the @code{Program_Error} exception. If a
10246 pragma @code{Import} specifies convention @code{stubbed} then no body need
10247 be present at all. This convention is useful during development for the
10248 inclusion of subprograms whose body has not yet been written.
10252 In addition, all otherwise unrecognized convention names are also
10253 treated as being synonymous with convention C@. In all implementations
10254 except for VMS, use of such other names results in a warning. In VMS
10255 implementations, these names are accepted silently.
10260 @strong{78}. The meaning of link names. See B.1(36).
10263 Link names are the actual names used by the linker.
10268 @strong{79}. The manner of choosing link names when neither the link
10269 name nor the address of an imported or exported entity is specified. See
10273 The default linker name is that which would be assigned by the relevant
10274 external language, interpreting the Ada name as being in all lower case
10280 @strong{80}. The effect of pragma @code{Linker_Options}. See B.1(37).
10283 The string passed to @code{Linker_Options} is presented uninterpreted as
10284 an argument to the link command, unless it contains ASCII.NUL characters.
10285 NUL characters if they appear act as argument separators, so for example
10287 @smallexample @c ada
10288 pragma Linker_Options ("-labc" & ASCII.NUL & "-ldef");
10292 causes two separate arguments @code{-labc} and @code{-ldef} to be passed to the
10293 linker. The order of linker options is preserved for a given unit. The final
10294 list of options passed to the linker is in reverse order of the elaboration
10295 order. For example, linker options for a body always appear before the options
10296 from the corresponding package spec.
10301 @strong{81}. The contents of the visible part of package
10302 @code{Interfaces} and its language-defined descendants. See B.2(1).
10305 See files with prefix @file{i-} in the distributed library.
10310 @strong{82}. Implementation-defined children of package
10311 @code{Interfaces}. The contents of the visible part of package
10312 @code{Interfaces}. See B.2(11).
10315 See files with prefix @file{i-} in the distributed library.
10320 @strong{83}. The types @code{Floating}, @code{Long_Floating},
10321 @code{Binary}, @code{Long_Binary}, @code{Decimal_ Element}, and
10322 @code{COBOL_Character}; and the initialization of the variables
10323 @code{Ada_To_COBOL} and @code{COBOL_To_Ada}, in
10324 @code{Interfaces.COBOL}. See B.4(50).
10330 @item Long_Floating
10331 (Floating) Long_Float
10336 @item Decimal_Element
10338 @item COBOL_Character
10343 For initialization, see the file @file{i-cobol.ads} in the distributed library.
10348 @strong{84}. Support for access to machine instructions. See C.1(1).
10351 See documentation in file @file{s-maccod.ads} in the distributed library.
10356 @strong{85}. Implementation-defined aspects of access to machine
10357 operations. See C.1(9).
10360 See documentation in file @file{s-maccod.ads} in the distributed library.
10365 @strong{86}. Implementation-defined aspects of interrupts. See C.3(2).
10368 Interrupts are mapped to signals or conditions as appropriate. See
10370 @code{Ada.Interrupt_Names} in source file @file{a-intnam.ads} for details
10371 on the interrupts supported on a particular target.
10376 @strong{87}. Implementation-defined aspects of pre-elaboration. See
10380 GNAT does not permit a partition to be restarted without reloading,
10381 except under control of the debugger.
10386 @strong{88}. The semantics of pragma @code{Discard_Names}. See C.5(7).
10389 Pragma @code{Discard_Names} causes names of enumeration literals to
10390 be suppressed. In the presence of this pragma, the Image attribute
10391 provides the image of the Pos of the literal, and Value accepts
10397 @strong{89}. The result of the @code{Task_Identification.Image}
10398 attribute. See C.7.1(7).
10401 The result of this attribute is a string that identifies
10402 the object or component that denotes a given task. If a variable @code{Var}
10403 has a task type, the image for this task will have the form @code{Var_@var{XXXXXXXX}},
10405 is the hexadecimal representation of the virtual address of the corresponding
10406 task control block. If the variable is an array of tasks, the image of each
10407 task will have the form of an indexed component indicating the position of a
10408 given task in the array, e.g.@: @code{Group(5)_@var{XXXXXXX}}. If the task is a
10409 component of a record, the image of the task will have the form of a selected
10410 component. These rules are fully recursive, so that the image of a task that
10411 is a subcomponent of a composite object corresponds to the expression that
10412 designates this task.
10414 If a task is created by an allocator, its image depends on the context. If the
10415 allocator is part of an object declaration, the rules described above are used
10416 to construct its image, and this image is not affected by subsequent
10417 assignments. If the allocator appears within an expression, the image
10418 includes only the name of the task type.
10420 If the configuration pragma Discard_Names is present, or if the restriction
10421 No_Implicit_Heap_Allocation is in effect, the image reduces to
10422 the numeric suffix, that is to say the hexadecimal representation of the
10423 virtual address of the control block of the task.
10427 @strong{90}. The value of @code{Current_Task} when in a protected entry
10428 or interrupt handler. See C.7.1(17).
10431 Protected entries or interrupt handlers can be executed by any
10432 convenient thread, so the value of @code{Current_Task} is undefined.
10437 @strong{91}. The effect of calling @code{Current_Task} from an entry
10438 body or interrupt handler. See C.7.1(19).
10441 The effect of calling @code{Current_Task} from an entry body or
10442 interrupt handler is to return the identification of the task currently
10443 executing the code.
10448 @strong{92}. Implementation-defined aspects of
10449 @code{Task_Attributes}. See C.7.2(19).
10452 There are no implementation-defined aspects of @code{Task_Attributes}.
10457 @strong{93}. Values of all @code{Metrics}. See D(2).
10460 The metrics information for GNAT depends on the performance of the
10461 underlying operating system. The sources of the run-time for tasking
10462 implementation, together with the output from @option{-gnatG} can be
10463 used to determine the exact sequence of operating systems calls made
10464 to implement various tasking constructs. Together with appropriate
10465 information on the performance of the underlying operating system,
10466 on the exact target in use, this information can be used to determine
10467 the required metrics.
10472 @strong{94}. The declarations of @code{Any_Priority} and
10473 @code{Priority}. See D.1(11).
10476 See declarations in file @file{system.ads}.
10481 @strong{95}. Implementation-defined execution resources. See D.1(15).
10484 There are no implementation-defined execution resources.
10489 @strong{96}. Whether, on a multiprocessor, a task that is waiting for
10490 access to a protected object keeps its processor busy. See D.2.1(3).
10493 On a multi-processor, a task that is waiting for access to a protected
10494 object does not keep its processor busy.
10499 @strong{97}. The affect of implementation defined execution resources
10500 on task dispatching. See D.2.1(9).
10505 Tasks map to IRIX threads, and the dispatching policy is as defined by
10506 the IRIX implementation of threads.
10508 Tasks map to threads in the threads package used by GNAT@. Where possible
10509 and appropriate, these threads correspond to native threads of the
10510 underlying operating system.
10515 @strong{98}. Implementation-defined @code{policy_identifiers} allowed
10516 in a pragma @code{Task_Dispatching_Policy}. See D.2.2(3).
10519 There are no implementation-defined policy-identifiers allowed in this
10525 @strong{99}. Implementation-defined aspects of priority inversion. See
10529 Execution of a task cannot be preempted by the implementation processing
10530 of delay expirations for lower priority tasks.
10535 @strong{100}. Implementation-defined task dispatching. See D.2.2(18).
10540 Tasks map to IRIX threads, and the dispatching policy is as defined by
10541 the IRIX implementation of threads.
10543 The policy is the same as that of the underlying threads implementation.
10548 @strong{101}. Implementation-defined @code{policy_identifiers} allowed
10549 in a pragma @code{Locking_Policy}. See D.3(4).
10552 The two implementation defined policies permitted in GNAT are
10553 @code{Inheritance_Locking} and @code{Conccurent_Readers_Locking}. On
10554 targets that support the @code{Inheritance_Locking} policy, locking is
10555 implemented by inheritance, i.e.@: the task owning the lock operates
10556 at a priority equal to the highest priority of any task currently
10557 requesting the lock. On targets that support the
10558 @code{Conccurent_Readers_Locking} policy, locking is implemented with a
10559 read/write lock allowing multiple propected object functions to enter
10565 @strong{102}. Default ceiling priorities. See D.3(10).
10568 The ceiling priority of protected objects of the type
10569 @code{System.Interrupt_Priority'Last} as described in the Ada
10570 Reference Manual D.3(10),
10575 @strong{103}. The ceiling of any protected object used internally by
10576 the implementation. See D.3(16).
10579 The ceiling priority of internal protected objects is
10580 @code{System.Priority'Last}.
10585 @strong{104}. Implementation-defined queuing policies. See D.4(1).
10588 There are no implementation-defined queuing policies.
10593 @strong{105}. On a multiprocessor, any conditions that cause the
10594 completion of an aborted construct to be delayed later than what is
10595 specified for a single processor. See D.6(3).
10598 The semantics for abort on a multi-processor is the same as on a single
10599 processor, there are no further delays.
10604 @strong{106}. Any operations that implicitly require heap storage
10605 allocation. See D.7(8).
10608 The only operation that implicitly requires heap storage allocation is
10614 @strong{107}. Implementation-defined aspects of pragma
10615 @code{Restrictions}. See D.7(20).
10618 There are no such implementation-defined aspects.
10623 @strong{108}. Implementation-defined aspects of package
10624 @code{Real_Time}. See D.8(17).
10627 There are no implementation defined aspects of package @code{Real_Time}.
10632 @strong{109}. Implementation-defined aspects of
10633 @code{delay_statements}. See D.9(8).
10636 Any difference greater than one microsecond will cause the task to be
10637 delayed (see D.9(7)).
10642 @strong{110}. The upper bound on the duration of interrupt blocking
10643 caused by the implementation. See D.12(5).
10646 The upper bound is determined by the underlying operating system. In
10647 no cases is it more than 10 milliseconds.
10652 @strong{111}. The means for creating and executing distributed
10653 programs. See E(5).
10656 The GLADE package provides a utility GNATDIST for creating and executing
10657 distributed programs. See the GLADE reference manual for further details.
10662 @strong{112}. Any events that can result in a partition becoming
10663 inaccessible. See E.1(7).
10666 See the GLADE reference manual for full details on such events.
10671 @strong{113}. The scheduling policies, treatment of priorities, and
10672 management of shared resources between partitions in certain cases. See
10676 See the GLADE reference manual for full details on these aspects of
10677 multi-partition execution.
10682 @strong{114}. Events that cause the version of a compilation unit to
10683 change. See E.3(5).
10686 Editing the source file of a compilation unit, or the source files of
10687 any units on which it is dependent in a significant way cause the version
10688 to change. No other actions cause the version number to change. All changes
10689 are significant except those which affect only layout, capitalization or
10695 @strong{115}. Whether the execution of the remote subprogram is
10696 immediately aborted as a result of cancellation. See E.4(13).
10699 See the GLADE reference manual for details on the effect of abort in
10700 a distributed application.
10705 @strong{116}. Implementation-defined aspects of the PCS@. See E.5(25).
10708 See the GLADE reference manual for a full description of all implementation
10709 defined aspects of the PCS@.
10714 @strong{117}. Implementation-defined interfaces in the PCS@. See
10718 See the GLADE reference manual for a full description of all
10719 implementation defined interfaces.
10724 @strong{118}. The values of named numbers in the package
10725 @code{Decimal}. See F.2(7).
10737 @item Max_Decimal_Digits
10744 @strong{119}. The value of @code{Max_Picture_Length} in the package
10745 @code{Text_IO.Editing}. See F.3.3(16).
10753 @strong{120}. The value of @code{Max_Picture_Length} in the package
10754 @code{Wide_Text_IO.Editing}. See F.3.4(5).
10762 @strong{121}. The accuracy actually achieved by the complex elementary
10763 functions and by other complex arithmetic operations. See G.1(1).
10766 Standard library functions are used for the complex arithmetic
10767 operations. Only fast math mode is currently supported.
10772 @strong{122}. The sign of a zero result (or a component thereof) from
10773 any operator or function in @code{Numerics.Generic_Complex_Types}, when
10774 @code{Real'Signed_Zeros} is True. See G.1.1(53).
10777 The signs of zero values are as recommended by the relevant
10778 implementation advice.
10783 @strong{123}. The sign of a zero result (or a component thereof) from
10784 any operator or function in
10785 @code{Numerics.Generic_Complex_Elementary_Functions}, when
10786 @code{Real'Signed_Zeros} is @code{True}. See G.1.2(45).
10789 The signs of zero values are as recommended by the relevant
10790 implementation advice.
10795 @strong{124}. Whether the strict mode or the relaxed mode is the
10796 default. See G.2(2).
10799 The strict mode is the default. There is no separate relaxed mode. GNAT
10800 provides a highly efficient implementation of strict mode.
10805 @strong{125}. The result interval in certain cases of fixed-to-float
10806 conversion. See G.2.1(10).
10809 For cases where the result interval is implementation dependent, the
10810 accuracy is that provided by performing all operations in 64-bit IEEE
10811 floating-point format.
10816 @strong{126}. The result of a floating point arithmetic operation in
10817 overflow situations, when the @code{Machine_Overflows} attribute of the
10818 result type is @code{False}. See G.2.1(13).
10821 Infinite and NaN values are produced as dictated by the IEEE
10822 floating-point standard.
10824 Note that on machines that are not fully compliant with the IEEE
10825 floating-point standard, such as Alpha, the @option{-mieee} compiler flag
10826 must be used for achieving IEEE conforming behavior (although at the cost
10827 of a significant performance penalty), so infinite and NaN values are
10828 properly generated.
10833 @strong{127}. The result interval for division (or exponentiation by a
10834 negative exponent), when the floating point hardware implements division
10835 as multiplication by a reciprocal. See G.2.1(16).
10838 Not relevant, division is IEEE exact.
10843 @strong{128}. The definition of close result set, which determines the
10844 accuracy of certain fixed point multiplications and divisions. See
10848 Operations in the close result set are performed using IEEE long format
10849 floating-point arithmetic. The input operands are converted to
10850 floating-point, the operation is done in floating-point, and the result
10851 is converted to the target type.
10856 @strong{129}. Conditions on a @code{universal_real} operand of a fixed
10857 point multiplication or division for which the result shall be in the
10858 perfect result set. See G.2.3(22).
10861 The result is only defined to be in the perfect result set if the result
10862 can be computed by a single scaling operation involving a scale factor
10863 representable in 64-bits.
10868 @strong{130}. The result of a fixed point arithmetic operation in
10869 overflow situations, when the @code{Machine_Overflows} attribute of the
10870 result type is @code{False}. See G.2.3(27).
10873 Not relevant, @code{Machine_Overflows} is @code{True} for fixed-point
10879 @strong{131}. The result of an elementary function reference in
10880 overflow situations, when the @code{Machine_Overflows} attribute of the
10881 result type is @code{False}. See G.2.4(4).
10884 IEEE infinite and Nan values are produced as appropriate.
10889 @strong{132}. The value of the angle threshold, within which certain
10890 elementary functions, complex arithmetic operations, and complex
10891 elementary functions yield results conforming to a maximum relative
10892 error bound. See G.2.4(10).
10895 Information on this subject is not yet available.
10900 @strong{133}. The accuracy of certain elementary functions for
10901 parameters beyond the angle threshold. See G.2.4(10).
10904 Information on this subject is not yet available.
10909 @strong{134}. The result of a complex arithmetic operation or complex
10910 elementary function reference in overflow situations, when the
10911 @code{Machine_Overflows} attribute of the corresponding real type is
10912 @code{False}. See G.2.6(5).
10915 IEEE infinite and Nan values are produced as appropriate.
10920 @strong{135}. The accuracy of certain complex arithmetic operations and
10921 certain complex elementary functions for parameters (or components
10922 thereof) beyond the angle threshold. See G.2.6(8).
10925 Information on those subjects is not yet available.
10930 @strong{136}. Information regarding bounded errors and erroneous
10931 execution. See H.2(1).
10934 Information on this subject is not yet available.
10939 @strong{137}. Implementation-defined aspects of pragma
10940 @code{Inspection_Point}. See H.3.2(8).
10943 Pragma @code{Inspection_Point} ensures that the variable is live and can
10944 be examined by the debugger at the inspection point.
10949 @strong{138}. Implementation-defined aspects of pragma
10950 @code{Restrictions}. See H.4(25).
10953 There are no implementation-defined aspects of pragma @code{Restrictions}. The
10954 use of pragma @code{Restrictions [No_Exceptions]} has no effect on the
10955 generated code. Checks must suppressed by use of pragma @code{Suppress}.
10960 @strong{139}. Any restrictions on pragma @code{Restrictions}. See
10964 There are no restrictions on pragma @code{Restrictions}.
10966 @node Intrinsic Subprograms
10967 @chapter Intrinsic Subprograms
10968 @cindex Intrinsic Subprograms
10971 * Intrinsic Operators::
10972 * Enclosing_Entity::
10973 * Exception_Information::
10974 * Exception_Message::
10978 * Shifts and Rotates::
10979 * Source_Location::
10983 GNAT allows a user application program to write the declaration:
10985 @smallexample @c ada
10986 pragma Import (Intrinsic, name);
10990 providing that the name corresponds to one of the implemented intrinsic
10991 subprograms in GNAT, and that the parameter profile of the referenced
10992 subprogram meets the requirements. This chapter describes the set of
10993 implemented intrinsic subprograms, and the requirements on parameter profiles.
10994 Note that no body is supplied; as with other uses of pragma Import, the
10995 body is supplied elsewhere (in this case by the compiler itself). Note
10996 that any use of this feature is potentially non-portable, since the
10997 Ada standard does not require Ada compilers to implement this feature.
10999 @node Intrinsic Operators
11000 @section Intrinsic Operators
11001 @cindex Intrinsic operator
11004 All the predefined numeric operators in package Standard
11005 in @code{pragma Import (Intrinsic,..)}
11006 declarations. In the binary operator case, the operands must have the same
11007 size. The operand or operands must also be appropriate for
11008 the operator. For example, for addition, the operands must
11009 both be floating-point or both be fixed-point, and the
11010 right operand for @code{"**"} must have a root type of
11011 @code{Standard.Integer'Base}.
11012 You can use an intrinsic operator declaration as in the following example:
11014 @smallexample @c ada
11015 type Int1 is new Integer;
11016 type Int2 is new Integer;
11018 function "+" (X1 : Int1; X2 : Int2) return Int1;
11019 function "+" (X1 : Int1; X2 : Int2) return Int2;
11020 pragma Import (Intrinsic, "+");
11024 This declaration would permit ``mixed mode'' arithmetic on items
11025 of the differing types @code{Int1} and @code{Int2}.
11026 It is also possible to specify such operators for private types, if the
11027 full views are appropriate arithmetic types.
11029 @node Enclosing_Entity
11030 @section Enclosing_Entity
11031 @cindex Enclosing_Entity
11033 This intrinsic subprogram is used in the implementation of the
11034 library routine @code{GNAT.Source_Info}. The only useful use of the
11035 intrinsic import in this case is the one in this unit, so an
11036 application program should simply call the function
11037 @code{GNAT.Source_Info.Enclosing_Entity} to obtain the name of
11038 the current subprogram, package, task, entry, or protected subprogram.
11040 @node Exception_Information
11041 @section Exception_Information
11042 @cindex Exception_Information'
11044 This intrinsic subprogram is used in the implementation of the
11045 library routine @code{GNAT.Current_Exception}. The only useful
11046 use of the intrinsic import in this case is the one in this unit,
11047 so an application program should simply call the function
11048 @code{GNAT.Current_Exception.Exception_Information} to obtain
11049 the exception information associated with the current exception.
11051 @node Exception_Message
11052 @section Exception_Message
11053 @cindex Exception_Message
11055 This intrinsic subprogram is used in the implementation of the
11056 library routine @code{GNAT.Current_Exception}. The only useful
11057 use of the intrinsic import in this case is the one in this unit,
11058 so an application program should simply call the function
11059 @code{GNAT.Current_Exception.Exception_Message} to obtain
11060 the message associated with the current exception.
11062 @node Exception_Name
11063 @section Exception_Name
11064 @cindex Exception_Name
11066 This intrinsic subprogram is used in the implementation of the
11067 library routine @code{GNAT.Current_Exception}. The only useful
11068 use of the intrinsic import in this case is the one in this unit,
11069 so an application program should simply call the function
11070 @code{GNAT.Current_Exception.Exception_Name} to obtain
11071 the name of the current exception.
11077 This intrinsic subprogram is used in the implementation of the
11078 library routine @code{GNAT.Source_Info}. The only useful use of the
11079 intrinsic import in this case is the one in this unit, so an
11080 application program should simply call the function
11081 @code{GNAT.Source_Info.File} to obtain the name of the current
11088 This intrinsic subprogram is used in the implementation of the
11089 library routine @code{GNAT.Source_Info}. The only useful use of the
11090 intrinsic import in this case is the one in this unit, so an
11091 application program should simply call the function
11092 @code{GNAT.Source_Info.Line} to obtain the number of the current
11095 @node Shifts and Rotates
11096 @section Shifts and Rotates
11098 @cindex Shift_Right
11099 @cindex Shift_Right_Arithmetic
11100 @cindex Rotate_Left
11101 @cindex Rotate_Right
11103 In standard Ada, the shift and rotate functions are available only
11104 for the predefined modular types in package @code{Interfaces}. However, in
11105 GNAT it is possible to define these functions for any integer
11106 type (signed or modular), as in this example:
11108 @smallexample @c ada
11109 function Shift_Left
11116 The function name must be one of
11117 Shift_Left, Shift_Right, Shift_Right_Arithmetic, Rotate_Left, or
11118 Rotate_Right. T must be an integer type. T'Size must be
11119 8, 16, 32 or 64 bits; if T is modular, the modulus
11120 must be 2**8, 2**16, 2**32 or 2**64.
11121 The result type must be the same as the type of @code{Value}.
11122 The shift amount must be Natural.
11123 The formal parameter names can be anything.
11125 @node Source_Location
11126 @section Source_Location
11127 @cindex Source_Location
11129 This intrinsic subprogram is used in the implementation of the
11130 library routine @code{GNAT.Source_Info}. The only useful use of the
11131 intrinsic import in this case is the one in this unit, so an
11132 application program should simply call the function
11133 @code{GNAT.Source_Info.Source_Location} to obtain the current
11134 source file location.
11136 @node Representation Clauses and Pragmas
11137 @chapter Representation Clauses and Pragmas
11138 @cindex Representation Clauses
11141 * Alignment Clauses::
11143 * Storage_Size Clauses::
11144 * Size of Variant Record Objects::
11145 * Biased Representation ::
11146 * Value_Size and Object_Size Clauses::
11147 * Component_Size Clauses::
11148 * Bit_Order Clauses::
11149 * Effect of Bit_Order on Byte Ordering::
11150 * Pragma Pack for Arrays::
11151 * Pragma Pack for Records::
11152 * Record Representation Clauses::
11153 * Enumeration Clauses::
11154 * Address Clauses::
11155 * Effect of Convention on Representation::
11156 * Determining the Representations chosen by GNAT::
11160 @cindex Representation Clause
11161 @cindex Representation Pragma
11162 @cindex Pragma, representation
11163 This section describes the representation clauses accepted by GNAT, and
11164 their effect on the representation of corresponding data objects.
11166 GNAT fully implements Annex C (Systems Programming). This means that all
11167 the implementation advice sections in chapter 13 are fully implemented.
11168 However, these sections only require a minimal level of support for
11169 representation clauses. GNAT provides much more extensive capabilities,
11170 and this section describes the additional capabilities provided.
11172 @node Alignment Clauses
11173 @section Alignment Clauses
11174 @cindex Alignment Clause
11177 GNAT requires that all alignment clauses specify a power of 2, and all
11178 default alignments are always a power of 2. The default alignment
11179 values are as follows:
11182 @item @emph{Primitive Types}.
11183 For primitive types, the alignment is the minimum of the actual size of
11184 objects of the type divided by @code{Storage_Unit},
11185 and the maximum alignment supported by the target.
11186 (This maximum alignment is given by the GNAT-specific attribute
11187 @code{Standard'Maximum_Alignment}; see @ref{Maximum_Alignment}.)
11188 @cindex @code{Maximum_Alignment} attribute
11189 For example, for type @code{Long_Float}, the object size is 8 bytes, and the
11190 default alignment will be 8 on any target that supports alignments
11191 this large, but on some targets, the maximum alignment may be smaller
11192 than 8, in which case objects of type @code{Long_Float} will be maximally
11195 @item @emph{Arrays}.
11196 For arrays, the alignment is equal to the alignment of the component type
11197 for the normal case where no packing or component size is given. If the
11198 array is packed, and the packing is effective (see separate section on
11199 packed arrays), then the alignment will be one for long packed arrays,
11200 or arrays whose length is not known at compile time. For short packed
11201 arrays, which are handled internally as modular types, the alignment
11202 will be as described for primitive types, e.g.@: a packed array of length
11203 31 bits will have an object size of four bytes, and an alignment of 4.
11205 @item @emph{Records}.
11206 For the normal non-packed case, the alignment of a record is equal to
11207 the maximum alignment of any of its components. For tagged records, this
11208 includes the implicit access type used for the tag. If a pragma @code{Pack}
11209 is used and all components are packable (see separate section on pragma
11210 @code{Pack}), then the resulting alignment is 1, unless the layout of the
11211 record makes it profitable to increase it.
11213 A special case is when:
11216 the size of the record is given explicitly, or a
11217 full record representation clause is given, and
11219 the size of the record is 2, 4, or 8 bytes.
11222 In this case, an alignment is chosen to match the
11223 size of the record. For example, if we have:
11225 @smallexample @c ada
11226 type Small is record
11229 for Small'Size use 16;
11233 then the default alignment of the record type @code{Small} is 2, not 1. This
11234 leads to more efficient code when the record is treated as a unit, and also
11235 allows the type to specified as @code{Atomic} on architectures requiring
11241 An alignment clause may specify a larger alignment than the default value
11242 up to some maximum value dependent on the target (obtainable by using the
11243 attribute reference @code{Standard'Maximum_Alignment}). It may also specify
11244 a smaller alignment than the default value for enumeration, integer and
11245 fixed point types, as well as for record types, for example
11247 @smallexample @c ada
11252 for V'alignment use 1;
11256 @cindex Alignment, default
11257 The default alignment for the type @code{V} is 4, as a result of the
11258 Integer field in the record, but it is permissible, as shown, to
11259 override the default alignment of the record with a smaller value.
11261 @cindex Alignment, subtypes
11262 Note that according to the Ada standard, an alignment clause applies only
11263 to the first named subtype. If additional subtypes are declared, then the
11264 compiler is allowed to choose any alignment it likes, and there is no way
11265 to control this choice. Consider:
11267 @smallexample @c ada
11268 type R is range 1 .. 10_000;
11269 for R'Alignment use 1;
11270 subtype RS is R range 1 .. 1000;
11274 The alignment clause specifies an alignment of 1 for the first named subtype
11275 @code{R} but this does not necessarily apply to @code{RS}. When writing
11276 portable Ada code, you should avoid writing code that explicitly or
11277 implicitly relies on the alignment of such subtypes.
11279 For the GNAT compiler, if an explicit alignment clause is given, this
11280 value is also used for any subsequent subtypes. So for GNAT, in the
11281 above example, you can count on the alignment of @code{RS} being 1. But this
11282 assumption is non-portable, and other compilers may choose different
11283 alignments for the subtype @code{RS}.
11286 @section Size Clauses
11287 @cindex Size Clause
11290 The default size for a type @code{T} is obtainable through the
11291 language-defined attribute @code{T'Size} and also through the
11292 equivalent GNAT-defined attribute @code{T'Value_Size}.
11293 For objects of type @code{T}, GNAT will generally increase the type size
11294 so that the object size (obtainable through the GNAT-defined attribute
11295 @code{T'Object_Size})
11296 is a multiple of @code{T'Alignment * Storage_Unit}.
11299 @smallexample @c ada
11300 type Smallint is range 1 .. 6;
11309 In this example, @code{Smallint'Size} = @code{Smallint'Value_Size} = 3,
11310 as specified by the RM rules,
11311 but objects of this type will have a size of 8
11312 (@code{Smallint'Object_Size} = 8),
11313 since objects by default occupy an integral number
11314 of storage units. On some targets, notably older
11315 versions of the Digital Alpha, the size of stand
11316 alone objects of this type may be 32, reflecting
11317 the inability of the hardware to do byte load/stores.
11319 Similarly, the size of type @code{Rec} is 40 bits
11320 (@code{Rec'Size} = @code{Rec'Value_Size} = 40), but
11321 the alignment is 4, so objects of this type will have
11322 their size increased to 64 bits so that it is a multiple
11323 of the alignment (in bits). This decision is
11324 in accordance with the specific Implementation Advice in RM 13.3(43):
11327 A @code{Size} clause should be supported for an object if the specified
11328 @code{Size} is at least as large as its subtype's @code{Size}, and corresponds
11329 to a size in storage elements that is a multiple of the object's
11330 @code{Alignment} (if the @code{Alignment} is nonzero).
11334 An explicit size clause may be used to override the default size by
11335 increasing it. For example, if we have:
11337 @smallexample @c ada
11338 type My_Boolean is new Boolean;
11339 for My_Boolean'Size use 32;
11343 then values of this type will always be 32 bits long. In the case of
11344 discrete types, the size can be increased up to 64 bits, with the effect
11345 that the entire specified field is used to hold the value, sign- or
11346 zero-extended as appropriate. If more than 64 bits is specified, then
11347 padding space is allocated after the value, and a warning is issued that
11348 there are unused bits.
11350 Similarly the size of records and arrays may be increased, and the effect
11351 is to add padding bits after the value. This also causes a warning message
11354 The largest Size value permitted in GNAT is 2**31@minus{}1. Since this is a
11355 Size in bits, this corresponds to an object of size 256 megabytes (minus
11356 one). This limitation is true on all targets. The reason for this
11357 limitation is that it improves the quality of the code in many cases
11358 if it is known that a Size value can be accommodated in an object of
11361 @node Storage_Size Clauses
11362 @section Storage_Size Clauses
11363 @cindex Storage_Size Clause
11366 For tasks, the @code{Storage_Size} clause specifies the amount of space
11367 to be allocated for the task stack. This cannot be extended, and if the
11368 stack is exhausted, then @code{Storage_Error} will be raised (if stack
11369 checking is enabled). Use a @code{Storage_Size} attribute definition clause,
11370 or a @code{Storage_Size} pragma in the task definition to set the
11371 appropriate required size. A useful technique is to include in every
11372 task definition a pragma of the form:
11374 @smallexample @c ada
11375 pragma Storage_Size (Default_Stack_Size);
11379 Then @code{Default_Stack_Size} can be defined in a global package, and
11380 modified as required. Any tasks requiring stack sizes different from the
11381 default can have an appropriate alternative reference in the pragma.
11383 You can also use the @option{-d} binder switch to modify the default stack
11386 For access types, the @code{Storage_Size} clause specifies the maximum
11387 space available for allocation of objects of the type. If this space is
11388 exceeded then @code{Storage_Error} will be raised by an allocation attempt.
11389 In the case where the access type is declared local to a subprogram, the
11390 use of a @code{Storage_Size} clause triggers automatic use of a special
11391 predefined storage pool (@code{System.Pool_Size}) that ensures that all
11392 space for the pool is automatically reclaimed on exit from the scope in
11393 which the type is declared.
11395 A special case recognized by the compiler is the specification of a
11396 @code{Storage_Size} of zero for an access type. This means that no
11397 items can be allocated from the pool, and this is recognized at compile
11398 time, and all the overhead normally associated with maintaining a fixed
11399 size storage pool is eliminated. Consider the following example:
11401 @smallexample @c ada
11403 type R is array (Natural) of Character;
11404 type P is access all R;
11405 for P'Storage_Size use 0;
11406 -- Above access type intended only for interfacing purposes
11410 procedure g (m : P);
11411 pragma Import (C, g);
11422 As indicated in this example, these dummy storage pools are often useful in
11423 connection with interfacing where no object will ever be allocated. If you
11424 compile the above example, you get the warning:
11427 p.adb:16:09: warning: allocation from empty storage pool
11428 p.adb:16:09: warning: Storage_Error will be raised at run time
11432 Of course in practice, there will not be any explicit allocators in the
11433 case of such an access declaration.
11435 @node Size of Variant Record Objects
11436 @section Size of Variant Record Objects
11437 @cindex Size, variant record objects
11438 @cindex Variant record objects, size
11441 In the case of variant record objects, there is a question whether Size gives
11442 information about a particular variant, or the maximum size required
11443 for any variant. Consider the following program
11445 @smallexample @c ada
11446 with Text_IO; use Text_IO;
11448 type R1 (A : Boolean := False) is record
11450 when True => X : Character;
11451 when False => null;
11459 Put_Line (Integer'Image (V1'Size));
11460 Put_Line (Integer'Image (V2'Size));
11465 Here we are dealing with a variant record, where the True variant
11466 requires 16 bits, and the False variant requires 8 bits.
11467 In the above example, both V1 and V2 contain the False variant,
11468 which is only 8 bits long. However, the result of running the
11477 The reason for the difference here is that the discriminant value of
11478 V1 is fixed, and will always be False. It is not possible to assign
11479 a True variant value to V1, therefore 8 bits is sufficient. On the
11480 other hand, in the case of V2, the initial discriminant value is
11481 False (from the default), but it is possible to assign a True
11482 variant value to V2, therefore 16 bits must be allocated for V2
11483 in the general case, even fewer bits may be needed at any particular
11484 point during the program execution.
11486 As can be seen from the output of this program, the @code{'Size}
11487 attribute applied to such an object in GNAT gives the actual allocated
11488 size of the variable, which is the largest size of any of the variants.
11489 The Ada Reference Manual is not completely clear on what choice should
11490 be made here, but the GNAT behavior seems most consistent with the
11491 language in the RM@.
11493 In some cases, it may be desirable to obtain the size of the current
11494 variant, rather than the size of the largest variant. This can be
11495 achieved in GNAT by making use of the fact that in the case of a
11496 subprogram parameter, GNAT does indeed return the size of the current
11497 variant (because a subprogram has no way of knowing how much space
11498 is actually allocated for the actual).
11500 Consider the following modified version of the above program:
11502 @smallexample @c ada
11503 with Text_IO; use Text_IO;
11505 type R1 (A : Boolean := False) is record
11507 when True => X : Character;
11508 when False => null;
11514 function Size (V : R1) return Integer is
11520 Put_Line (Integer'Image (V2'Size));
11521 Put_Line (Integer'IMage (Size (V2)));
11523 Put_Line (Integer'Image (V2'Size));
11524 Put_Line (Integer'IMage (Size (V2)));
11529 The output from this program is
11539 Here we see that while the @code{'Size} attribute always returns
11540 the maximum size, regardless of the current variant value, the
11541 @code{Size} function does indeed return the size of the current
11544 @node Biased Representation
11545 @section Biased Representation
11546 @cindex Size for biased representation
11547 @cindex Biased representation
11550 In the case of scalars with a range starting at other than zero, it is
11551 possible in some cases to specify a size smaller than the default minimum
11552 value, and in such cases, GNAT uses an unsigned biased representation,
11553 in which zero is used to represent the lower bound, and successive values
11554 represent successive values of the type.
11556 For example, suppose we have the declaration:
11558 @smallexample @c ada
11559 type Small is range -7 .. -4;
11560 for Small'Size use 2;
11564 Although the default size of type @code{Small} is 4, the @code{Size}
11565 clause is accepted by GNAT and results in the following representation
11569 -7 is represented as 2#00#
11570 -6 is represented as 2#01#
11571 -5 is represented as 2#10#
11572 -4 is represented as 2#11#
11576 Biased representation is only used if the specified @code{Size} clause
11577 cannot be accepted in any other manner. These reduced sizes that force
11578 biased representation can be used for all discrete types except for
11579 enumeration types for which a representation clause is given.
11581 @node Value_Size and Object_Size Clauses
11582 @section Value_Size and Object_Size Clauses
11584 @findex Object_Size
11585 @cindex Size, of objects
11588 In Ada 95 and Ada 2005, @code{T'Size} for a type @code{T} is the minimum
11589 number of bits required to hold values of type @code{T}.
11590 Although this interpretation was allowed in Ada 83, it was not required,
11591 and this requirement in practice can cause some significant difficulties.
11592 For example, in most Ada 83 compilers, @code{Natural'Size} was 32.
11593 However, in Ada 95 and Ada 2005,
11594 @code{Natural'Size} is
11595 typically 31. This means that code may change in behavior when moving
11596 from Ada 83 to Ada 95 or Ada 2005. For example, consider:
11598 @smallexample @c ada
11599 type Rec is record;
11605 at 0 range 0 .. Natural'Size - 1;
11606 at 0 range Natural'Size .. 2 * Natural'Size - 1;
11611 In the above code, since the typical size of @code{Natural} objects
11612 is 32 bits and @code{Natural'Size} is 31, the above code can cause
11613 unexpected inefficient packing in Ada 95 and Ada 2005, and in general
11614 there are cases where the fact that the object size can exceed the
11615 size of the type causes surprises.
11617 To help get around this problem GNAT provides two implementation
11618 defined attributes, @code{Value_Size} and @code{Object_Size}. When
11619 applied to a type, these attributes yield the size of the type
11620 (corresponding to the RM defined size attribute), and the size of
11621 objects of the type respectively.
11623 The @code{Object_Size} is used for determining the default size of
11624 objects and components. This size value can be referred to using the
11625 @code{Object_Size} attribute. The phrase ``is used'' here means that it is
11626 the basis of the determination of the size. The backend is free to
11627 pad this up if necessary for efficiency, e.g.@: an 8-bit stand-alone
11628 character might be stored in 32 bits on a machine with no efficient
11629 byte access instructions such as the Alpha.
11631 The default rules for the value of @code{Object_Size} for
11632 discrete types are as follows:
11636 The @code{Object_Size} for base subtypes reflect the natural hardware
11637 size in bits (run the compiler with @option{-gnatS} to find those values
11638 for numeric types). Enumeration types and fixed-point base subtypes have
11639 8, 16, 32 or 64 bits for this size, depending on the range of values
11643 The @code{Object_Size} of a subtype is the same as the
11644 @code{Object_Size} of
11645 the type from which it is obtained.
11648 The @code{Object_Size} of a derived base type is copied from the parent
11649 base type, and the @code{Object_Size} of a derived first subtype is copied
11650 from the parent first subtype.
11654 The @code{Value_Size} attribute
11655 is the (minimum) number of bits required to store a value
11657 This value is used to determine how tightly to pack
11658 records or arrays with components of this type, and also affects
11659 the semantics of unchecked conversion (unchecked conversions where
11660 the @code{Value_Size} values differ generate a warning, and are potentially
11663 The default rules for the value of @code{Value_Size} are as follows:
11667 The @code{Value_Size} for a base subtype is the minimum number of bits
11668 required to store all values of the type (including the sign bit
11669 only if negative values are possible).
11672 If a subtype statically matches the first subtype of a given type, then it has
11673 by default the same @code{Value_Size} as the first subtype. This is a
11674 consequence of RM 13.1(14) (``if two subtypes statically match,
11675 then their subtype-specific aspects are the same''.)
11678 All other subtypes have a @code{Value_Size} corresponding to the minimum
11679 number of bits required to store all values of the subtype. For
11680 dynamic bounds, it is assumed that the value can range down or up
11681 to the corresponding bound of the ancestor
11685 The RM defined attribute @code{Size} corresponds to the
11686 @code{Value_Size} attribute.
11688 The @code{Size} attribute may be defined for a first-named subtype. This sets
11689 the @code{Value_Size} of
11690 the first-named subtype to the given value, and the
11691 @code{Object_Size} of this first-named subtype to the given value padded up
11692 to an appropriate boundary. It is a consequence of the default rules
11693 above that this @code{Object_Size} will apply to all further subtypes. On the
11694 other hand, @code{Value_Size} is affected only for the first subtype, any
11695 dynamic subtypes obtained from it directly, and any statically matching
11696 subtypes. The @code{Value_Size} of any other static subtypes is not affected.
11698 @code{Value_Size} and
11699 @code{Object_Size} may be explicitly set for any subtype using
11700 an attribute definition clause. Note that the use of these attributes
11701 can cause the RM 13.1(14) rule to be violated. If two access types
11702 reference aliased objects whose subtypes have differing @code{Object_Size}
11703 values as a result of explicit attribute definition clauses, then it
11704 is erroneous to convert from one access subtype to the other.
11706 At the implementation level, Esize stores the Object_Size and the
11707 RM_Size field stores the @code{Value_Size} (and hence the value of the
11708 @code{Size} attribute,
11709 which, as noted above, is equivalent to @code{Value_Size}).
11711 To get a feel for the difference, consider the following examples (note
11712 that in each case the base is @code{Short_Short_Integer} with a size of 8):
11715 Object_Size Value_Size
11717 type x1 is range 0 .. 5; 8 3
11719 type x2 is range 0 .. 5;
11720 for x2'size use 12; 16 12
11722 subtype x3 is x2 range 0 .. 3; 16 2
11724 subtype x4 is x2'base range 0 .. 10; 8 4
11726 subtype x5 is x2 range 0 .. dynamic; 16 3*
11728 subtype x6 is x2'base range 0 .. dynamic; 8 3*
11733 Note: the entries marked ``3*'' are not actually specified by the Ada
11734 Reference Manual, but it seems in the spirit of the RM rules to allocate
11735 the minimum number of bits (here 3, given the range for @code{x2})
11736 known to be large enough to hold the given range of values.
11738 So far, so good, but GNAT has to obey the RM rules, so the question is
11739 under what conditions must the RM @code{Size} be used.
11740 The following is a list
11741 of the occasions on which the RM @code{Size} must be used:
11745 Component size for packed arrays or records
11748 Value of the attribute @code{Size} for a type
11751 Warning about sizes not matching for unchecked conversion
11755 For record types, the @code{Object_Size} is always a multiple of the
11756 alignment of the type (this is true for all types). In some cases the
11757 @code{Value_Size} can be smaller. Consider:
11767 On a typical 32-bit architecture, the X component will be four bytes, and
11768 require four-byte alignment, and the Y component will be one byte. In this
11769 case @code{R'Value_Size} will be 40 (bits) since this is the minimum size
11770 required to store a value of this type, and for example, it is permissible
11771 to have a component of type R in an outer array whose component size is
11772 specified to be 48 bits. However, @code{R'Object_Size} will be 64 (bits),
11773 since it must be rounded up so that this value is a multiple of the
11774 alignment (4 bytes = 32 bits).
11777 For all other types, the @code{Object_Size}
11778 and Value_Size are the same (and equivalent to the RM attribute @code{Size}).
11779 Only @code{Size} may be specified for such types.
11781 @node Component_Size Clauses
11782 @section Component_Size Clauses
11783 @cindex Component_Size Clause
11786 Normally, the value specified in a component size clause must be consistent
11787 with the subtype of the array component with regard to size and alignment.
11788 In other words, the value specified must be at least equal to the size
11789 of this subtype, and must be a multiple of the alignment value.
11791 In addition, component size clauses are allowed which cause the array
11792 to be packed, by specifying a smaller value. A first case is for
11793 component size values in the range 1 through 63. The value specified
11794 must not be smaller than the Size of the subtype. GNAT will accurately
11795 honor all packing requests in this range. For example, if we have:
11797 @smallexample @c ada
11798 type r is array (1 .. 8) of Natural;
11799 for r'Component_Size use 31;
11803 then the resulting array has a length of 31 bytes (248 bits = 8 * 31).
11804 Of course access to the components of such an array is considerably
11805 less efficient than if the natural component size of 32 is used.
11806 A second case is when the subtype of the component is a record type
11807 padded because of its default alignment. For example, if we have:
11809 @smallexample @c ada
11816 type a is array (1 .. 8) of r;
11817 for a'Component_Size use 72;
11821 then the resulting array has a length of 72 bytes, instead of 96 bytes
11822 if the alignment of the record (4) was obeyed.
11824 Note that there is no point in giving both a component size clause
11825 and a pragma Pack for the same array type. if such duplicate
11826 clauses are given, the pragma Pack will be ignored.
11828 @node Bit_Order Clauses
11829 @section Bit_Order Clauses
11830 @cindex Bit_Order Clause
11831 @cindex bit ordering
11832 @cindex ordering, of bits
11835 For record subtypes, GNAT permits the specification of the @code{Bit_Order}
11836 attribute. The specification may either correspond to the default bit
11837 order for the target, in which case the specification has no effect and
11838 places no additional restrictions, or it may be for the non-standard
11839 setting (that is the opposite of the default).
11841 In the case where the non-standard value is specified, the effect is
11842 to renumber bits within each byte, but the ordering of bytes is not
11843 affected. There are certain
11844 restrictions placed on component clauses as follows:
11848 @item Components fitting within a single storage unit.
11850 These are unrestricted, and the effect is merely to renumber bits. For
11851 example if we are on a little-endian machine with @code{Low_Order_First}
11852 being the default, then the following two declarations have exactly
11855 @smallexample @c ada
11858 B : Integer range 1 .. 120;
11862 A at 0 range 0 .. 0;
11863 B at 0 range 1 .. 7;
11868 B : Integer range 1 .. 120;
11871 for R2'Bit_Order use High_Order_First;
11874 A at 0 range 7 .. 7;
11875 B at 0 range 0 .. 6;
11880 The useful application here is to write the second declaration with the
11881 @code{Bit_Order} attribute definition clause, and know that it will be treated
11882 the same, regardless of whether the target is little-endian or big-endian.
11884 @item Components occupying an integral number of bytes.
11886 These are components that exactly fit in two or more bytes. Such component
11887 declarations are allowed, but have no effect, since it is important to realize
11888 that the @code{Bit_Order} specification does not affect the ordering of bytes.
11889 In particular, the following attempt at getting an endian-independent integer
11892 @smallexample @c ada
11897 for R2'Bit_Order use High_Order_First;
11900 A at 0 range 0 .. 31;
11905 This declaration will result in a little-endian integer on a
11906 little-endian machine, and a big-endian integer on a big-endian machine.
11907 If byte flipping is required for interoperability between big- and
11908 little-endian machines, this must be explicitly programmed. This capability
11909 is not provided by @code{Bit_Order}.
11911 @item Components that are positioned across byte boundaries
11913 but do not occupy an integral number of bytes. Given that bytes are not
11914 reordered, such fields would occupy a non-contiguous sequence of bits
11915 in memory, requiring non-trivial code to reassemble. They are for this
11916 reason not permitted, and any component clause specifying such a layout
11917 will be flagged as illegal by GNAT@.
11922 Since the misconception that Bit_Order automatically deals with all
11923 endian-related incompatibilities is a common one, the specification of
11924 a component field that is an integral number of bytes will always
11925 generate a warning. This warning may be suppressed using @code{pragma
11926 Warnings (Off)} if desired. The following section contains additional
11927 details regarding the issue of byte ordering.
11929 @node Effect of Bit_Order on Byte Ordering
11930 @section Effect of Bit_Order on Byte Ordering
11931 @cindex byte ordering
11932 @cindex ordering, of bytes
11935 In this section we will review the effect of the @code{Bit_Order} attribute
11936 definition clause on byte ordering. Briefly, it has no effect at all, but
11937 a detailed example will be helpful. Before giving this
11938 example, let us review the precise
11939 definition of the effect of defining @code{Bit_Order}. The effect of a
11940 non-standard bit order is described in section 15.5.3 of the Ada
11944 2 A bit ordering is a method of interpreting the meaning of
11945 the storage place attributes.
11949 To understand the precise definition of storage place attributes in
11950 this context, we visit section 13.5.1 of the manual:
11953 13 A record_representation_clause (without the mod_clause)
11954 specifies the layout. The storage place attributes (see 13.5.2)
11955 are taken from the values of the position, first_bit, and last_bit
11956 expressions after normalizing those values so that first_bit is
11957 less than Storage_Unit.
11961 The critical point here is that storage places are taken from
11962 the values after normalization, not before. So the @code{Bit_Order}
11963 interpretation applies to normalized values. The interpretation
11964 is described in the later part of the 15.5.3 paragraph:
11967 2 A bit ordering is a method of interpreting the meaning of
11968 the storage place attributes. High_Order_First (known in the
11969 vernacular as ``big endian'') means that the first bit of a
11970 storage element (bit 0) is the most significant bit (interpreting
11971 the sequence of bits that represent a component as an unsigned
11972 integer value). Low_Order_First (known in the vernacular as
11973 ``little endian'') means the opposite: the first bit is the
11978 Note that the numbering is with respect to the bits of a storage
11979 unit. In other words, the specification affects only the numbering
11980 of bits within a single storage unit.
11982 We can make the effect clearer by giving an example.
11984 Suppose that we have an external device which presents two bytes, the first
11985 byte presented, which is the first (low addressed byte) of the two byte
11986 record is called Master, and the second byte is called Slave.
11988 The left most (most significant bit is called Control for each byte, and
11989 the remaining 7 bits are called V1, V2, @dots{} V7, where V7 is the rightmost
11990 (least significant) bit.
11992 On a big-endian machine, we can write the following representation clause
11994 @smallexample @c ada
11995 type Data is record
11996 Master_Control : Bit;
12004 Slave_Control : Bit;
12014 for Data use record
12015 Master_Control at 0 range 0 .. 0;
12016 Master_V1 at 0 range 1 .. 1;
12017 Master_V2 at 0 range 2 .. 2;
12018 Master_V3 at 0 range 3 .. 3;
12019 Master_V4 at 0 range 4 .. 4;
12020 Master_V5 at 0 range 5 .. 5;
12021 Master_V6 at 0 range 6 .. 6;
12022 Master_V7 at 0 range 7 .. 7;
12023 Slave_Control at 1 range 0 .. 0;
12024 Slave_V1 at 1 range 1 .. 1;
12025 Slave_V2 at 1 range 2 .. 2;
12026 Slave_V3 at 1 range 3 .. 3;
12027 Slave_V4 at 1 range 4 .. 4;
12028 Slave_V5 at 1 range 5 .. 5;
12029 Slave_V6 at 1 range 6 .. 6;
12030 Slave_V7 at 1 range 7 .. 7;
12035 Now if we move this to a little endian machine, then the bit ordering within
12036 the byte is backwards, so we have to rewrite the record rep clause as:
12038 @smallexample @c ada
12039 for Data use record
12040 Master_Control at 0 range 7 .. 7;
12041 Master_V1 at 0 range 6 .. 6;
12042 Master_V2 at 0 range 5 .. 5;
12043 Master_V3 at 0 range 4 .. 4;
12044 Master_V4 at 0 range 3 .. 3;
12045 Master_V5 at 0 range 2 .. 2;
12046 Master_V6 at 0 range 1 .. 1;
12047 Master_V7 at 0 range 0 .. 0;
12048 Slave_Control at 1 range 7 .. 7;
12049 Slave_V1 at 1 range 6 .. 6;
12050 Slave_V2 at 1 range 5 .. 5;
12051 Slave_V3 at 1 range 4 .. 4;
12052 Slave_V4 at 1 range 3 .. 3;
12053 Slave_V5 at 1 range 2 .. 2;
12054 Slave_V6 at 1 range 1 .. 1;
12055 Slave_V7 at 1 range 0 .. 0;
12060 It is a nuisance to have to rewrite the clause, especially if
12061 the code has to be maintained on both machines. However,
12062 this is a case that we can handle with the
12063 @code{Bit_Order} attribute if it is implemented.
12064 Note that the implementation is not required on byte addressed
12065 machines, but it is indeed implemented in GNAT.
12066 This means that we can simply use the
12067 first record clause, together with the declaration
12069 @smallexample @c ada
12070 for Data'Bit_Order use High_Order_First;
12074 and the effect is what is desired, namely the layout is exactly the same,
12075 independent of whether the code is compiled on a big-endian or little-endian
12078 The important point to understand is that byte ordering is not affected.
12079 A @code{Bit_Order} attribute definition never affects which byte a field
12080 ends up in, only where it ends up in that byte.
12081 To make this clear, let us rewrite the record rep clause of the previous
12084 @smallexample @c ada
12085 for Data'Bit_Order use High_Order_First;
12086 for Data use record
12087 Master_Control at 0 range 0 .. 0;
12088 Master_V1 at 0 range 1 .. 1;
12089 Master_V2 at 0 range 2 .. 2;
12090 Master_V3 at 0 range 3 .. 3;
12091 Master_V4 at 0 range 4 .. 4;
12092 Master_V5 at 0 range 5 .. 5;
12093 Master_V6 at 0 range 6 .. 6;
12094 Master_V7 at 0 range 7 .. 7;
12095 Slave_Control at 0 range 8 .. 8;
12096 Slave_V1 at 0 range 9 .. 9;
12097 Slave_V2 at 0 range 10 .. 10;
12098 Slave_V3 at 0 range 11 .. 11;
12099 Slave_V4 at 0 range 12 .. 12;
12100 Slave_V5 at 0 range 13 .. 13;
12101 Slave_V6 at 0 range 14 .. 14;
12102 Slave_V7 at 0 range 15 .. 15;
12107 This is exactly equivalent to saying (a repeat of the first example):
12109 @smallexample @c ada
12110 for Data'Bit_Order use High_Order_First;
12111 for Data use record
12112 Master_Control at 0 range 0 .. 0;
12113 Master_V1 at 0 range 1 .. 1;
12114 Master_V2 at 0 range 2 .. 2;
12115 Master_V3 at 0 range 3 .. 3;
12116 Master_V4 at 0 range 4 .. 4;
12117 Master_V5 at 0 range 5 .. 5;
12118 Master_V6 at 0 range 6 .. 6;
12119 Master_V7 at 0 range 7 .. 7;
12120 Slave_Control at 1 range 0 .. 0;
12121 Slave_V1 at 1 range 1 .. 1;
12122 Slave_V2 at 1 range 2 .. 2;
12123 Slave_V3 at 1 range 3 .. 3;
12124 Slave_V4 at 1 range 4 .. 4;
12125 Slave_V5 at 1 range 5 .. 5;
12126 Slave_V6 at 1 range 6 .. 6;
12127 Slave_V7 at 1 range 7 .. 7;
12132 Why are they equivalent? Well take a specific field, the @code{Slave_V2}
12133 field. The storage place attributes are obtained by normalizing the
12134 values given so that the @code{First_Bit} value is less than 8. After
12135 normalizing the values (0,10,10) we get (1,2,2) which is exactly what
12136 we specified in the other case.
12138 Now one might expect that the @code{Bit_Order} attribute might affect
12139 bit numbering within the entire record component (two bytes in this
12140 case, thus affecting which byte fields end up in), but that is not
12141 the way this feature is defined, it only affects numbering of bits,
12142 not which byte they end up in.
12144 Consequently it never makes sense to specify a starting bit number
12145 greater than 7 (for a byte addressable field) if an attribute
12146 definition for @code{Bit_Order} has been given, and indeed it
12147 may be actively confusing to specify such a value, so the compiler
12148 generates a warning for such usage.
12150 If you do need to control byte ordering then appropriate conditional
12151 values must be used. If in our example, the slave byte came first on
12152 some machines we might write:
12154 @smallexample @c ada
12155 Master_Byte_First constant Boolean := @dots{};
12157 Master_Byte : constant Natural :=
12158 1 - Boolean'Pos (Master_Byte_First);
12159 Slave_Byte : constant Natural :=
12160 Boolean'Pos (Master_Byte_First);
12162 for Data'Bit_Order use High_Order_First;
12163 for Data use record
12164 Master_Control at Master_Byte range 0 .. 0;
12165 Master_V1 at Master_Byte range 1 .. 1;
12166 Master_V2 at Master_Byte range 2 .. 2;
12167 Master_V3 at Master_Byte range 3 .. 3;
12168 Master_V4 at Master_Byte range 4 .. 4;
12169 Master_V5 at Master_Byte range 5 .. 5;
12170 Master_V6 at Master_Byte range 6 .. 6;
12171 Master_V7 at Master_Byte range 7 .. 7;
12172 Slave_Control at Slave_Byte range 0 .. 0;
12173 Slave_V1 at Slave_Byte range 1 .. 1;
12174 Slave_V2 at Slave_Byte range 2 .. 2;
12175 Slave_V3 at Slave_Byte range 3 .. 3;
12176 Slave_V4 at Slave_Byte range 4 .. 4;
12177 Slave_V5 at Slave_Byte range 5 .. 5;
12178 Slave_V6 at Slave_Byte range 6 .. 6;
12179 Slave_V7 at Slave_Byte range 7 .. 7;
12184 Now to switch between machines, all that is necessary is
12185 to set the boolean constant @code{Master_Byte_First} in
12186 an appropriate manner.
12188 @node Pragma Pack for Arrays
12189 @section Pragma Pack for Arrays
12190 @cindex Pragma Pack (for arrays)
12193 Pragma @code{Pack} applied to an array has no effect unless the component type
12194 is packable. For a component type to be packable, it must be one of the
12201 Any type whose size is specified with a size clause
12203 Any packed array type with a static size
12205 Any record type padded because of its default alignment
12209 For all these cases, if the component subtype size is in the range
12210 1 through 63, then the effect of the pragma @code{Pack} is exactly as though a
12211 component size were specified giving the component subtype size.
12212 For example if we have:
12214 @smallexample @c ada
12215 type r is range 0 .. 17;
12217 type ar is array (1 .. 8) of r;
12222 Then the component size of @code{ar} will be set to 5 (i.e.@: to @code{r'size},
12223 and the size of the array @code{ar} will be exactly 40 bits.
12225 Note that in some cases this rather fierce approach to packing can produce
12226 unexpected effects. For example, in Ada 95 and Ada 2005,
12227 subtype @code{Natural} typically has a size of 31, meaning that if you
12228 pack an array of @code{Natural}, you get 31-bit
12229 close packing, which saves a few bits, but results in far less efficient
12230 access. Since many other Ada compilers will ignore such a packing request,
12231 GNAT will generate a warning on some uses of pragma @code{Pack} that it guesses
12232 might not be what is intended. You can easily remove this warning by
12233 using an explicit @code{Component_Size} setting instead, which never generates
12234 a warning, since the intention of the programmer is clear in this case.
12236 GNAT treats packed arrays in one of two ways. If the size of the array is
12237 known at compile time and is less than 64 bits, then internally the array
12238 is represented as a single modular type, of exactly the appropriate number
12239 of bits. If the length is greater than 63 bits, or is not known at compile
12240 time, then the packed array is represented as an array of bytes, and the
12241 length is always a multiple of 8 bits.
12243 Note that to represent a packed array as a modular type, the alignment must
12244 be suitable for the modular type involved. For example, on typical machines
12245 a 32-bit packed array will be represented by a 32-bit modular integer with
12246 an alignment of four bytes. If you explicitly override the default alignment
12247 with an alignment clause that is too small, the modular representation
12248 cannot be used. For example, consider the following set of declarations:
12250 @smallexample @c ada
12251 type R is range 1 .. 3;
12252 type S is array (1 .. 31) of R;
12253 for S'Component_Size use 2;
12255 for S'Alignment use 1;
12259 If the alignment clause were not present, then a 62-bit modular
12260 representation would be chosen (typically with an alignment of 4 or 8
12261 bytes depending on the target). But the default alignment is overridden
12262 with the explicit alignment clause. This means that the modular
12263 representation cannot be used, and instead the array of bytes
12264 representation must be used, meaning that the length must be a multiple
12265 of 8. Thus the above set of declarations will result in a diagnostic
12266 rejecting the size clause and noting that the minimum size allowed is 64.
12268 @cindex Pragma Pack (for type Natural)
12269 @cindex Pragma Pack warning
12271 One special case that is worth noting occurs when the base type of the
12272 component size is 8/16/32 and the subtype is one bit less. Notably this
12273 occurs with subtype @code{Natural}. Consider:
12275 @smallexample @c ada
12276 type Arr is array (1 .. 32) of Natural;
12281 In all commonly used Ada 83 compilers, this pragma Pack would be ignored,
12282 since typically @code{Natural'Size} is 32 in Ada 83, and in any case most
12283 Ada 83 compilers did not attempt 31 bit packing.
12285 In Ada 95 and Ada 2005, @code{Natural'Size} is required to be 31. Furthermore,
12286 GNAT really does pack 31-bit subtype to 31 bits. This may result in a
12287 substantial unintended performance penalty when porting legacy Ada 83 code.
12288 To help prevent this, GNAT generates a warning in such cases. If you really
12289 want 31 bit packing in a case like this, you can set the component size
12292 @smallexample @c ada
12293 type Arr is array (1 .. 32) of Natural;
12294 for Arr'Component_Size use 31;
12298 Here 31-bit packing is achieved as required, and no warning is generated,
12299 since in this case the programmer intention is clear.
12301 @node Pragma Pack for Records
12302 @section Pragma Pack for Records
12303 @cindex Pragma Pack (for records)
12306 Pragma @code{Pack} applied to a record will pack the components to reduce
12307 wasted space from alignment gaps and by reducing the amount of space
12308 taken by components. We distinguish between @emph{packable} components and
12309 @emph{non-packable} components.
12310 Components of the following types are considered packable:
12313 All primitive types are packable.
12316 Small packed arrays, whose size does not exceed 64 bits, and where the
12317 size is statically known at compile time, are represented internally
12318 as modular integers, and so they are also packable.
12323 All packable components occupy the exact number of bits corresponding to
12324 their @code{Size} value, and are packed with no padding bits, i.e.@: they
12325 can start on an arbitrary bit boundary.
12327 All other types are non-packable, they occupy an integral number of
12329 are placed at a boundary corresponding to their alignment requirements.
12331 For example, consider the record
12333 @smallexample @c ada
12334 type Rb1 is array (1 .. 13) of Boolean;
12337 type Rb2 is array (1 .. 65) of Boolean;
12352 The representation for the record x2 is as follows:
12354 @smallexample @c ada
12355 for x2'Size use 224;
12357 l1 at 0 range 0 .. 0;
12358 l2 at 0 range 1 .. 64;
12359 l3 at 12 range 0 .. 31;
12360 l4 at 16 range 0 .. 0;
12361 l5 at 16 range 1 .. 13;
12362 l6 at 18 range 0 .. 71;
12367 Studying this example, we see that the packable fields @code{l1}
12369 of length equal to their sizes, and placed at specific bit boundaries (and
12370 not byte boundaries) to
12371 eliminate padding. But @code{l3} is of a non-packable float type, so
12372 it is on the next appropriate alignment boundary.
12374 The next two fields are fully packable, so @code{l4} and @code{l5} are
12375 minimally packed with no gaps. However, type @code{Rb2} is a packed
12376 array that is longer than 64 bits, so it is itself non-packable. Thus
12377 the @code{l6} field is aligned to the next byte boundary, and takes an
12378 integral number of bytes, i.e.@: 72 bits.
12380 @node Record Representation Clauses
12381 @section Record Representation Clauses
12382 @cindex Record Representation Clause
12385 Record representation clauses may be given for all record types, including
12386 types obtained by record extension. Component clauses are allowed for any
12387 static component. The restrictions on component clauses depend on the type
12390 @cindex Component Clause
12391 For all components of an elementary type, the only restriction on component
12392 clauses is that the size must be at least the 'Size value of the type
12393 (actually the Value_Size). There are no restrictions due to alignment,
12394 and such components may freely cross storage boundaries.
12396 Packed arrays with a size up to and including 64 bits are represented
12397 internally using a modular type with the appropriate number of bits, and
12398 thus the same lack of restriction applies. For example, if you declare:
12400 @smallexample @c ada
12401 type R is array (1 .. 49) of Boolean;
12407 then a component clause for a component of type R may start on any
12408 specified bit boundary, and may specify a value of 49 bits or greater.
12410 For packed bit arrays that are longer than 64 bits, there are two
12411 cases. If the component size is a power of 2 (1,2,4,8,16,32 bits),
12412 including the important case of single bits or boolean values, then
12413 there are no limitations on placement of such components, and they
12414 may start and end at arbitrary bit boundaries.
12416 If the component size is not a power of 2 (e.g.@: 3 or 5), then
12417 an array of this type longer than 64 bits must always be placed on
12418 on a storage unit (byte) boundary and occupy an integral number
12419 of storage units (bytes). Any component clause that does not
12420 meet this requirement will be rejected.
12422 Any aliased component, or component of an aliased type, must
12423 have its normal alignment and size. A component clause that
12424 does not meet this requirement will be rejected.
12426 The tag field of a tagged type always occupies an address sized field at
12427 the start of the record. No component clause may attempt to overlay this
12428 tag. When a tagged type appears as a component, the tag field must have
12431 In the case of a record extension T1, of a type T, no component clause applied
12432 to the type T1 can specify a storage location that would overlap the first
12433 T'Size bytes of the record.
12435 For all other component types, including non-bit-packed arrays,
12436 the component can be placed at an arbitrary bit boundary,
12437 so for example, the following is permitted:
12439 @smallexample @c ada
12440 type R is array (1 .. 10) of Boolean;
12449 G at 0 range 0 .. 0;
12450 H at 0 range 1 .. 1;
12451 L at 0 range 2 .. 81;
12452 R at 0 range 82 .. 161;
12457 Note: the above rules apply to recent releases of GNAT 5.
12458 In GNAT 3, there are more severe restrictions on larger components.
12459 For non-primitive types, including packed arrays with a size greater than
12460 64 bits, component clauses must respect the alignment requirement of the
12461 type, in particular, always starting on a byte boundary, and the length
12462 must be a multiple of the storage unit.
12464 @node Enumeration Clauses
12465 @section Enumeration Clauses
12467 The only restriction on enumeration clauses is that the range of values
12468 must be representable. For the signed case, if one or more of the
12469 representation values are negative, all values must be in the range:
12471 @smallexample @c ada
12472 System.Min_Int .. System.Max_Int
12476 For the unsigned case, where all values are nonnegative, the values must
12479 @smallexample @c ada
12480 0 .. System.Max_Binary_Modulus;
12484 A @emph{confirming} representation clause is one in which the values range
12485 from 0 in sequence, i.e.@: a clause that confirms the default representation
12486 for an enumeration type.
12487 Such a confirming representation
12488 is permitted by these rules, and is specially recognized by the compiler so
12489 that no extra overhead results from the use of such a clause.
12491 If an array has an index type which is an enumeration type to which an
12492 enumeration clause has been applied, then the array is stored in a compact
12493 manner. Consider the declarations:
12495 @smallexample @c ada
12496 type r is (A, B, C);
12497 for r use (A => 1, B => 5, C => 10);
12498 type t is array (r) of Character;
12502 The array type t corresponds to a vector with exactly three elements and
12503 has a default size equal to @code{3*Character'Size}. This ensures efficient
12504 use of space, but means that accesses to elements of the array will incur
12505 the overhead of converting representation values to the corresponding
12506 positional values, (i.e.@: the value delivered by the @code{Pos} attribute).
12508 @node Address Clauses
12509 @section Address Clauses
12510 @cindex Address Clause
12512 The reference manual allows a general restriction on representation clauses,
12513 as found in RM 13.1(22):
12516 An implementation need not support representation
12517 items containing nonstatic expressions, except that
12518 an implementation should support a representation item
12519 for a given entity if each nonstatic expression in the
12520 representation item is a name that statically denotes
12521 a constant declared before the entity.
12525 In practice this is applicable only to address clauses, since this is the
12526 only case in which a non-static expression is permitted by the syntax. As
12527 the AARM notes in sections 13.1 (22.a-22.h):
12530 22.a Reason: This is to avoid the following sort of thing:
12532 22.b X : Integer := F(@dots{});
12533 Y : Address := G(@dots{});
12534 for X'Address use Y;
12536 22.c In the above, we have to evaluate the
12537 initialization expression for X before we
12538 know where to put the result. This seems
12539 like an unreasonable implementation burden.
12541 22.d The above code should instead be written
12544 22.e Y : constant Address := G(@dots{});
12545 X : Integer := F(@dots{});
12546 for X'Address use Y;
12548 22.f This allows the expression ``Y'' to be safely
12549 evaluated before X is created.
12551 22.g The constant could be a formal parameter of mode in.
12553 22.h An implementation can support other nonstatic
12554 expressions if it wants to. Expressions of type
12555 Address are hardly ever static, but their value
12556 might be known at compile time anyway in many
12561 GNAT does indeed permit many additional cases of non-static expressions. In
12562 particular, if the type involved is elementary there are no restrictions
12563 (since in this case, holding a temporary copy of the initialization value,
12564 if one is present, is inexpensive). In addition, if there is no implicit or
12565 explicit initialization, then there are no restrictions. GNAT will reject
12566 only the case where all three of these conditions hold:
12571 The type of the item is non-elementary (e.g.@: a record or array).
12574 There is explicit or implicit initialization required for the object.
12575 Note that access values are always implicitly initialized.
12578 The address value is non-static. Here GNAT is more permissive than the
12579 RM, and allows the address value to be the address of a previously declared
12580 stand-alone variable, as long as it does not itself have an address clause.
12582 @smallexample @c ada
12583 Anchor : Some_Initialized_Type;
12584 Overlay : Some_Initialized_Type;
12585 for Overlay'Address use Anchor'Address;
12589 However, the prefix of the address clause cannot be an array component, or
12590 a component of a discriminated record.
12595 As noted above in section 22.h, address values are typically non-static. In
12596 particular the To_Address function, even if applied to a literal value, is
12597 a non-static function call. To avoid this minor annoyance, GNAT provides
12598 the implementation defined attribute 'To_Address. The following two
12599 expressions have identical values:
12603 @smallexample @c ada
12604 To_Address (16#1234_0000#)
12605 System'To_Address (16#1234_0000#);
12609 except that the second form is considered to be a static expression, and
12610 thus when used as an address clause value is always permitted.
12613 Additionally, GNAT treats as static an address clause that is an
12614 unchecked_conversion of a static integer value. This simplifies the porting
12615 of legacy code, and provides a portable equivalent to the GNAT attribute
12618 Another issue with address clauses is the interaction with alignment
12619 requirements. When an address clause is given for an object, the address
12620 value must be consistent with the alignment of the object (which is usually
12621 the same as the alignment of the type of the object). If an address clause
12622 is given that specifies an inappropriately aligned address value, then the
12623 program execution is erroneous.
12625 Since this source of erroneous behavior can have unfortunate effects, GNAT
12626 checks (at compile time if possible, generating a warning, or at execution
12627 time with a run-time check) that the alignment is appropriate. If the
12628 run-time check fails, then @code{Program_Error} is raised. This run-time
12629 check is suppressed if range checks are suppressed, or if the special GNAT
12630 check Alignment_Check is suppressed, or if
12631 @code{pragma Restrictions (No_Elaboration_Code)} is in effect.
12633 Finally, GNAT does not permit overlaying of objects of controlled types or
12634 composite types containing a controlled component. In most cases, the compiler
12635 can detect an attempt at such overlays and will generate a warning at compile
12636 time and a Program_Error exception at run time.
12639 An address clause cannot be given for an exported object. More
12640 understandably the real restriction is that objects with an address
12641 clause cannot be exported. This is because such variables are not
12642 defined by the Ada program, so there is no external object to export.
12645 It is permissible to give an address clause and a pragma Import for the
12646 same object. In this case, the variable is not really defined by the
12647 Ada program, so there is no external symbol to be linked. The link name
12648 and the external name are ignored in this case. The reason that we allow this
12649 combination is that it provides a useful idiom to avoid unwanted
12650 initializations on objects with address clauses.
12652 When an address clause is given for an object that has implicit or
12653 explicit initialization, then by default initialization takes place. This
12654 means that the effect of the object declaration is to overwrite the
12655 memory at the specified address. This is almost always not what the
12656 programmer wants, so GNAT will output a warning:
12666 for Ext'Address use System'To_Address (16#1234_1234#);
12668 >>> warning: implicit initialization of "Ext" may
12669 modify overlaid storage
12670 >>> warning: use pragma Import for "Ext" to suppress
12671 initialization (RM B(24))
12677 As indicated by the warning message, the solution is to use a (dummy) pragma
12678 Import to suppress this initialization. The pragma tell the compiler that the
12679 object is declared and initialized elsewhere. The following package compiles
12680 without warnings (and the initialization is suppressed):
12682 @smallexample @c ada
12690 for Ext'Address use System'To_Address (16#1234_1234#);
12691 pragma Import (Ada, Ext);
12696 A final issue with address clauses involves their use for overlaying
12697 variables, as in the following example:
12698 @cindex Overlaying of objects
12700 @smallexample @c ada
12703 for B'Address use A'Address;
12707 or alternatively, using the form recommended by the RM:
12709 @smallexample @c ada
12711 Addr : constant Address := A'Address;
12713 for B'Address use Addr;
12717 In both of these cases, @code{A}
12718 and @code{B} become aliased to one another via the
12719 address clause. This use of address clauses to overlay
12720 variables, achieving an effect similar to unchecked
12721 conversion was erroneous in Ada 83, but in Ada 95 and Ada 2005
12722 the effect is implementation defined. Furthermore, the
12723 Ada RM specifically recommends that in a situation
12724 like this, @code{B} should be subject to the following
12725 implementation advice (RM 13.3(19)):
12728 19 If the Address of an object is specified, or it is imported
12729 or exported, then the implementation should not perform
12730 optimizations based on assumptions of no aliases.
12734 GNAT follows this recommendation, and goes further by also applying
12735 this recommendation to the overlaid variable (@code{A}
12736 in the above example) in this case. This means that the overlay
12737 works "as expected", in that a modification to one of the variables
12738 will affect the value of the other.
12740 @node Effect of Convention on Representation
12741 @section Effect of Convention on Representation
12742 @cindex Convention, effect on representation
12745 Normally the specification of a foreign language convention for a type or
12746 an object has no effect on the chosen representation. In particular, the
12747 representation chosen for data in GNAT generally meets the standard system
12748 conventions, and for example records are laid out in a manner that is
12749 consistent with C@. This means that specifying convention C (for example)
12752 There are four exceptions to this general rule:
12756 @item Convention Fortran and array subtypes
12757 If pragma Convention Fortran is specified for an array subtype, then in
12758 accordance with the implementation advice in section 3.6.2(11) of the
12759 Ada Reference Manual, the array will be stored in a Fortran-compatible
12760 column-major manner, instead of the normal default row-major order.
12762 @item Convention C and enumeration types
12763 GNAT normally stores enumeration types in 8, 16, or 32 bits as required
12764 to accommodate all values of the type. For example, for the enumeration
12767 @smallexample @c ada
12768 type Color is (Red, Green, Blue);
12772 8 bits is sufficient to store all values of the type, so by default, objects
12773 of type @code{Color} will be represented using 8 bits. However, normal C
12774 convention is to use 32 bits for all enum values in C, since enum values
12775 are essentially of type int. If pragma @code{Convention C} is specified for an
12776 Ada enumeration type, then the size is modified as necessary (usually to
12777 32 bits) to be consistent with the C convention for enum values.
12779 Note that this treatment applies only to types. If Convention C is given for
12780 an enumeration object, where the enumeration type is not Convention C, then
12781 Object_Size bits are allocated. For example, for a normal enumeration type,
12782 with less than 256 elements, only 8 bits will be allocated for the object.
12783 Since this may be a surprise in terms of what C expects, GNAT will issue a
12784 warning in this situation. The warning can be suppressed by giving an explicit
12785 size clause specifying the desired size.
12787 @item Convention C/Fortran and Boolean types
12788 In C, the usual convention for boolean values, that is values used for
12789 conditions, is that zero represents false, and nonzero values represent
12790 true. In Ada, the normal convention is that two specific values, typically
12791 0/1, are used to represent false/true respectively.
12793 Fortran has a similar convention for @code{LOGICAL} values (any nonzero
12794 value represents true).
12796 To accommodate the Fortran and C conventions, if a pragma Convention specifies
12797 C or Fortran convention for a derived Boolean, as in the following example:
12799 @smallexample @c ada
12800 type C_Switch is new Boolean;
12801 pragma Convention (C, C_Switch);
12805 then the GNAT generated code will treat any nonzero value as true. For truth
12806 values generated by GNAT, the conventional value 1 will be used for True, but
12807 when one of these values is read, any nonzero value is treated as True.
12809 @item Access types on OpenVMS
12810 For 64-bit OpenVMS systems, access types (other than those for unconstrained
12811 arrays) are 64-bits long. An exception to this rule is for the case of
12812 C-convention access types where there is no explicit size clause present (or
12813 inherited for derived types). In this case, GNAT chooses to make these
12814 pointers 32-bits, which provides an easier path for migration of 32-bit legacy
12815 code. size clause specifying 64-bits must be used to obtain a 64-bit pointer.
12819 @node Determining the Representations chosen by GNAT
12820 @section Determining the Representations chosen by GNAT
12821 @cindex Representation, determination of
12822 @cindex @option{-gnatR} switch
12825 Although the descriptions in this section are intended to be complete, it is
12826 often easier to simply experiment to see what GNAT accepts and what the
12827 effect is on the layout of types and objects.
12829 As required by the Ada RM, if a representation clause is not accepted, then
12830 it must be rejected as illegal by the compiler. However, when a
12831 representation clause or pragma is accepted, there can still be questions
12832 of what the compiler actually does. For example, if a partial record
12833 representation clause specifies the location of some components and not
12834 others, then where are the non-specified components placed? Or if pragma
12835 @code{Pack} is used on a record, then exactly where are the resulting
12836 fields placed? The section on pragma @code{Pack} in this chapter can be
12837 used to answer the second question, but it is often easier to just see
12838 what the compiler does.
12840 For this purpose, GNAT provides the option @option{-gnatR}. If you compile
12841 with this option, then the compiler will output information on the actual
12842 representations chosen, in a format similar to source representation
12843 clauses. For example, if we compile the package:
12845 @smallexample @c ada
12847 type r (x : boolean) is tagged record
12849 when True => S : String (1 .. 100);
12850 when False => null;
12854 type r2 is new r (false) with record
12859 y2 at 16 range 0 .. 31;
12866 type x1 is array (1 .. 10) of x;
12867 for x1'component_size use 11;
12869 type ia is access integer;
12871 type Rb1 is array (1 .. 13) of Boolean;
12874 type Rb2 is array (1 .. 65) of Boolean;
12890 using the switch @option{-gnatR} we obtain the following output:
12893 Representation information for unit q
12894 -------------------------------------
12897 for r'Alignment use 4;
12899 x at 4 range 0 .. 7;
12900 _tag at 0 range 0 .. 31;
12901 s at 5 range 0 .. 799;
12904 for r2'Size use 160;
12905 for r2'Alignment use 4;
12907 x at 4 range 0 .. 7;
12908 _tag at 0 range 0 .. 31;
12909 _parent at 0 range 0 .. 63;
12910 y2 at 16 range 0 .. 31;
12914 for x'Alignment use 1;
12916 y at 0 range 0 .. 7;
12919 for x1'Size use 112;
12920 for x1'Alignment use 1;
12921 for x1'Component_Size use 11;
12923 for rb1'Size use 13;
12924 for rb1'Alignment use 2;
12925 for rb1'Component_Size use 1;
12927 for rb2'Size use 72;
12928 for rb2'Alignment use 1;
12929 for rb2'Component_Size use 1;
12931 for x2'Size use 224;
12932 for x2'Alignment use 4;
12934 l1 at 0 range 0 .. 0;
12935 l2 at 0 range 1 .. 64;
12936 l3 at 12 range 0 .. 31;
12937 l4 at 16 range 0 .. 0;
12938 l5 at 16 range 1 .. 13;
12939 l6 at 18 range 0 .. 71;
12944 The Size values are actually the Object_Size, i.e.@: the default size that
12945 will be allocated for objects of the type.
12946 The ?? size for type r indicates that we have a variant record, and the
12947 actual size of objects will depend on the discriminant value.
12949 The Alignment values show the actual alignment chosen by the compiler
12950 for each record or array type.
12952 The record representation clause for type r shows where all fields
12953 are placed, including the compiler generated tag field (whose location
12954 cannot be controlled by the programmer).
12956 The record representation clause for the type extension r2 shows all the
12957 fields present, including the parent field, which is a copy of the fields
12958 of the parent type of r2, i.e.@: r1.
12960 The component size and size clauses for types rb1 and rb2 show
12961 the exact effect of pragma @code{Pack} on these arrays, and the record
12962 representation clause for type x2 shows how pragma @code{Pack} affects
12965 In some cases, it may be useful to cut and paste the representation clauses
12966 generated by the compiler into the original source to fix and guarantee
12967 the actual representation to be used.
12969 @node Standard Library Routines
12970 @chapter Standard Library Routines
12973 The Ada Reference Manual contains in Annex A a full description of an
12974 extensive set of standard library routines that can be used in any Ada
12975 program, and which must be provided by all Ada compilers. They are
12976 analogous to the standard C library used by C programs.
12978 GNAT implements all of the facilities described in annex A, and for most
12979 purposes the description in the Ada Reference Manual, or appropriate Ada
12980 text book, will be sufficient for making use of these facilities.
12982 In the case of the input-output facilities,
12983 @xref{The Implementation of Standard I/O},
12984 gives details on exactly how GNAT interfaces to the
12985 file system. For the remaining packages, the Ada Reference Manual
12986 should be sufficient. The following is a list of the packages included,
12987 together with a brief description of the functionality that is provided.
12989 For completeness, references are included to other predefined library
12990 routines defined in other sections of the Ada Reference Manual (these are
12991 cross-indexed from Annex A).
12995 This is a parent package for all the standard library packages. It is
12996 usually included implicitly in your program, and itself contains no
12997 useful data or routines.
12999 @item Ada.Calendar (9.6)
13000 @code{Calendar} provides time of day access, and routines for
13001 manipulating times and durations.
13003 @item Ada.Characters (A.3.1)
13004 This is a dummy parent package that contains no useful entities
13006 @item Ada.Characters.Handling (A.3.2)
13007 This package provides some basic character handling capabilities,
13008 including classification functions for classes of characters (e.g.@: test
13009 for letters, or digits).
13011 @item Ada.Characters.Latin_1 (A.3.3)
13012 This package includes a complete set of definitions of the characters
13013 that appear in type CHARACTER@. It is useful for writing programs that
13014 will run in international environments. For example, if you want an
13015 upper case E with an acute accent in a string, it is often better to use
13016 the definition of @code{UC_E_Acute} in this package. Then your program
13017 will print in an understandable manner even if your environment does not
13018 support these extended characters.
13020 @item Ada.Command_Line (A.15)
13021 This package provides access to the command line parameters and the name
13022 of the current program (analogous to the use of @code{argc} and @code{argv}
13023 in C), and also allows the exit status for the program to be set in a
13024 system-independent manner.
13026 @item Ada.Decimal (F.2)
13027 This package provides constants describing the range of decimal numbers
13028 implemented, and also a decimal divide routine (analogous to the COBOL
13029 verb DIVIDE @dots{} GIVING @dots{} REMAINDER @dots{})
13031 @item Ada.Direct_IO (A.8.4)
13032 This package provides input-output using a model of a set of records of
13033 fixed-length, containing an arbitrary definite Ada type, indexed by an
13034 integer record number.
13036 @item Ada.Dynamic_Priorities (D.5)
13037 This package allows the priorities of a task to be adjusted dynamically
13038 as the task is running.
13040 @item Ada.Exceptions (11.4.1)
13041 This package provides additional information on exceptions, and also
13042 contains facilities for treating exceptions as data objects, and raising
13043 exceptions with associated messages.
13045 @item Ada.Finalization (7.6)
13046 This package contains the declarations and subprograms to support the
13047 use of controlled types, providing for automatic initialization and
13048 finalization (analogous to the constructors and destructors of C++)
13050 @item Ada.Interrupts (C.3.2)
13051 This package provides facilities for interfacing to interrupts, which
13052 includes the set of signals or conditions that can be raised and
13053 recognized as interrupts.
13055 @item Ada.Interrupts.Names (C.3.2)
13056 This package provides the set of interrupt names (actually signal
13057 or condition names) that can be handled by GNAT@.
13059 @item Ada.IO_Exceptions (A.13)
13060 This package defines the set of exceptions that can be raised by use of
13061 the standard IO packages.
13064 This package contains some standard constants and exceptions used
13065 throughout the numerics packages. Note that the constants pi and e are
13066 defined here, and it is better to use these definitions than rolling
13069 @item Ada.Numerics.Complex_Elementary_Functions
13070 Provides the implementation of standard elementary functions (such as
13071 log and trigonometric functions) operating on complex numbers using the
13072 standard @code{Float} and the @code{Complex} and @code{Imaginary} types
13073 created by the package @code{Numerics.Complex_Types}.
13075 @item Ada.Numerics.Complex_Types
13076 This is a predefined instantiation of
13077 @code{Numerics.Generic_Complex_Types} using @code{Standard.Float} to
13078 build the type @code{Complex} and @code{Imaginary}.
13080 @item Ada.Numerics.Discrete_Random
13081 This generic package provides a random number generator suitable for generating
13082 uniformly distributed values of a specified discrete subtype.
13084 @item Ada.Numerics.Float_Random
13085 This package provides a random number generator suitable for generating
13086 uniformly distributed floating point values in the unit interval.
13088 @item Ada.Numerics.Generic_Complex_Elementary_Functions
13089 This is a generic version of the package that provides the
13090 implementation of standard elementary functions (such as log and
13091 trigonometric functions) for an arbitrary complex type.
13093 The following predefined instantiations of this package are provided:
13097 @code{Ada.Numerics.Short_Complex_Elementary_Functions}
13099 @code{Ada.Numerics.Complex_Elementary_Functions}
13101 @code{Ada.Numerics.Long_Complex_Elementary_Functions}
13104 @item Ada.Numerics.Generic_Complex_Types
13105 This is a generic package that allows the creation of complex types,
13106 with associated complex arithmetic operations.
13108 The following predefined instantiations of this package exist
13111 @code{Ada.Numerics.Short_Complex_Complex_Types}
13113 @code{Ada.Numerics.Complex_Complex_Types}
13115 @code{Ada.Numerics.Long_Complex_Complex_Types}
13118 @item Ada.Numerics.Generic_Elementary_Functions
13119 This is a generic package that provides the implementation of standard
13120 elementary functions (such as log an trigonometric functions) for an
13121 arbitrary float type.
13123 The following predefined instantiations of this package exist
13127 @code{Ada.Numerics.Short_Elementary_Functions}
13129 @code{Ada.Numerics.Elementary_Functions}
13131 @code{Ada.Numerics.Long_Elementary_Functions}
13134 @item Ada.Real_Time (D.8)
13135 This package provides facilities similar to those of @code{Calendar}, but
13136 operating with a finer clock suitable for real time control. Note that
13137 annex D requires that there be no backward clock jumps, and GNAT generally
13138 guarantees this behavior, but of course if the external clock on which
13139 the GNAT runtime depends is deliberately reset by some external event,
13140 then such a backward jump may occur.
13142 @item Ada.Sequential_IO (A.8.1)
13143 This package provides input-output facilities for sequential files,
13144 which can contain a sequence of values of a single type, which can be
13145 any Ada type, including indefinite (unconstrained) types.
13147 @item Ada.Storage_IO (A.9)
13148 This package provides a facility for mapping arbitrary Ada types to and
13149 from a storage buffer. It is primarily intended for the creation of new
13152 @item Ada.Streams (13.13.1)
13153 This is a generic package that provides the basic support for the
13154 concept of streams as used by the stream attributes (@code{Input},
13155 @code{Output}, @code{Read} and @code{Write}).
13157 @item Ada.Streams.Stream_IO (A.12.1)
13158 This package is a specialization of the type @code{Streams} defined in
13159 package @code{Streams} together with a set of operations providing
13160 Stream_IO capability. The Stream_IO model permits both random and
13161 sequential access to a file which can contain an arbitrary set of values
13162 of one or more Ada types.
13164 @item Ada.Strings (A.4.1)
13165 This package provides some basic constants used by the string handling
13168 @item Ada.Strings.Bounded (A.4.4)
13169 This package provides facilities for handling variable length
13170 strings. The bounded model requires a maximum length. It is thus
13171 somewhat more limited than the unbounded model, but avoids the use of
13172 dynamic allocation or finalization.
13174 @item Ada.Strings.Fixed (A.4.3)
13175 This package provides facilities for handling fixed length strings.
13177 @item Ada.Strings.Maps (A.4.2)
13178 This package provides facilities for handling character mappings and
13179 arbitrarily defined subsets of characters. For instance it is useful in
13180 defining specialized translation tables.
13182 @item Ada.Strings.Maps.Constants (A.4.6)
13183 This package provides a standard set of predefined mappings and
13184 predefined character sets. For example, the standard upper to lower case
13185 conversion table is found in this package. Note that upper to lower case
13186 conversion is non-trivial if you want to take the entire set of
13187 characters, including extended characters like E with an acute accent,
13188 into account. You should use the mappings in this package (rather than
13189 adding 32 yourself) to do case mappings.
13191 @item Ada.Strings.Unbounded (A.4.5)
13192 This package provides facilities for handling variable length
13193 strings. The unbounded model allows arbitrary length strings, but
13194 requires the use of dynamic allocation and finalization.
13196 @item Ada.Strings.Wide_Bounded (A.4.7)
13197 @itemx Ada.Strings.Wide_Fixed (A.4.7)
13198 @itemx Ada.Strings.Wide_Maps (A.4.7)
13199 @itemx Ada.Strings.Wide_Maps.Constants (A.4.7)
13200 @itemx Ada.Strings.Wide_Unbounded (A.4.7)
13201 These packages provide analogous capabilities to the corresponding
13202 packages without @samp{Wide_} in the name, but operate with the types
13203 @code{Wide_String} and @code{Wide_Character} instead of @code{String}
13204 and @code{Character}.
13206 @item Ada.Strings.Wide_Wide_Bounded (A.4.7)
13207 @itemx Ada.Strings.Wide_Wide_Fixed (A.4.7)
13208 @itemx Ada.Strings.Wide_Wide_Maps (A.4.7)
13209 @itemx Ada.Strings.Wide_Wide_Maps.Constants (A.4.7)
13210 @itemx Ada.Strings.Wide_Wide_Unbounded (A.4.7)
13211 These packages provide analogous capabilities to the corresponding
13212 packages without @samp{Wide_} in the name, but operate with the types
13213 @code{Wide_Wide_String} and @code{Wide_Wide_Character} instead
13214 of @code{String} and @code{Character}.
13216 @item Ada.Synchronous_Task_Control (D.10)
13217 This package provides some standard facilities for controlling task
13218 communication in a synchronous manner.
13221 This package contains definitions for manipulation of the tags of tagged
13224 @item Ada.Task_Attributes
13225 This package provides the capability of associating arbitrary
13226 task-specific data with separate tasks.
13229 This package provides basic text input-output capabilities for
13230 character, string and numeric data. The subpackages of this
13231 package are listed next.
13233 @item Ada.Text_IO.Decimal_IO
13234 Provides input-output facilities for decimal fixed-point types
13236 @item Ada.Text_IO.Enumeration_IO
13237 Provides input-output facilities for enumeration types.
13239 @item Ada.Text_IO.Fixed_IO
13240 Provides input-output facilities for ordinary fixed-point types.
13242 @item Ada.Text_IO.Float_IO
13243 Provides input-output facilities for float types. The following
13244 predefined instantiations of this generic package are available:
13248 @code{Short_Float_Text_IO}
13250 @code{Float_Text_IO}
13252 @code{Long_Float_Text_IO}
13255 @item Ada.Text_IO.Integer_IO
13256 Provides input-output facilities for integer types. The following
13257 predefined instantiations of this generic package are available:
13260 @item Short_Short_Integer
13261 @code{Ada.Short_Short_Integer_Text_IO}
13262 @item Short_Integer
13263 @code{Ada.Short_Integer_Text_IO}
13265 @code{Ada.Integer_Text_IO}
13267 @code{Ada.Long_Integer_Text_IO}
13268 @item Long_Long_Integer
13269 @code{Ada.Long_Long_Integer_Text_IO}
13272 @item Ada.Text_IO.Modular_IO
13273 Provides input-output facilities for modular (unsigned) types
13275 @item Ada.Text_IO.Complex_IO (G.1.3)
13276 This package provides basic text input-output capabilities for complex
13279 @item Ada.Text_IO.Editing (F.3.3)
13280 This package contains routines for edited output, analogous to the use
13281 of pictures in COBOL@. The picture formats used by this package are a
13282 close copy of the facility in COBOL@.
13284 @item Ada.Text_IO.Text_Streams (A.12.2)
13285 This package provides a facility that allows Text_IO files to be treated
13286 as streams, so that the stream attributes can be used for writing
13287 arbitrary data, including binary data, to Text_IO files.
13289 @item Ada.Unchecked_Conversion (13.9)
13290 This generic package allows arbitrary conversion from one type to
13291 another of the same size, providing for breaking the type safety in
13292 special circumstances.
13294 If the types have the same Size (more accurately the same Value_Size),
13295 then the effect is simply to transfer the bits from the source to the
13296 target type without any modification. This usage is well defined, and
13297 for simple types whose representation is typically the same across
13298 all implementations, gives a portable method of performing such
13301 If the types do not have the same size, then the result is implementation
13302 defined, and thus may be non-portable. The following describes how GNAT
13303 handles such unchecked conversion cases.
13305 If the types are of different sizes, and are both discrete types, then
13306 the effect is of a normal type conversion without any constraint checking.
13307 In particular if the result type has a larger size, the result will be
13308 zero or sign extended. If the result type has a smaller size, the result
13309 will be truncated by ignoring high order bits.
13311 If the types are of different sizes, and are not both discrete types,
13312 then the conversion works as though pointers were created to the source
13313 and target, and the pointer value is converted. The effect is that bits
13314 are copied from successive low order storage units and bits of the source
13315 up to the length of the target type.
13317 A warning is issued if the lengths differ, since the effect in this
13318 case is implementation dependent, and the above behavior may not match
13319 that of some other compiler.
13321 A pointer to one type may be converted to a pointer to another type using
13322 unchecked conversion. The only case in which the effect is undefined is
13323 when one or both pointers are pointers to unconstrained array types. In
13324 this case, the bounds information may get incorrectly transferred, and in
13325 particular, GNAT uses double size pointers for such types, and it is
13326 meaningless to convert between such pointer types. GNAT will issue a
13327 warning if the alignment of the target designated type is more strict
13328 than the alignment of the source designated type (since the result may
13329 be unaligned in this case).
13331 A pointer other than a pointer to an unconstrained array type may be
13332 converted to and from System.Address. Such usage is common in Ada 83
13333 programs, but note that Ada.Address_To_Access_Conversions is the
13334 preferred method of performing such conversions in Ada 95 and Ada 2005.
13336 unchecked conversion nor Ada.Address_To_Access_Conversions should be
13337 used in conjunction with pointers to unconstrained objects, since
13338 the bounds information cannot be handled correctly in this case.
13340 @item Ada.Unchecked_Deallocation (13.11.2)
13341 This generic package allows explicit freeing of storage previously
13342 allocated by use of an allocator.
13344 @item Ada.Wide_Text_IO (A.11)
13345 This package is similar to @code{Ada.Text_IO}, except that the external
13346 file supports wide character representations, and the internal types are
13347 @code{Wide_Character} and @code{Wide_String} instead of @code{Character}
13348 and @code{String}. It contains generic subpackages listed next.
13350 @item Ada.Wide_Text_IO.Decimal_IO
13351 Provides input-output facilities for decimal fixed-point types
13353 @item Ada.Wide_Text_IO.Enumeration_IO
13354 Provides input-output facilities for enumeration types.
13356 @item Ada.Wide_Text_IO.Fixed_IO
13357 Provides input-output facilities for ordinary fixed-point types.
13359 @item Ada.Wide_Text_IO.Float_IO
13360 Provides input-output facilities for float types. The following
13361 predefined instantiations of this generic package are available:
13365 @code{Short_Float_Wide_Text_IO}
13367 @code{Float_Wide_Text_IO}
13369 @code{Long_Float_Wide_Text_IO}
13372 @item Ada.Wide_Text_IO.Integer_IO
13373 Provides input-output facilities for integer types. The following
13374 predefined instantiations of this generic package are available:
13377 @item Short_Short_Integer
13378 @code{Ada.Short_Short_Integer_Wide_Text_IO}
13379 @item Short_Integer
13380 @code{Ada.Short_Integer_Wide_Text_IO}
13382 @code{Ada.Integer_Wide_Text_IO}
13384 @code{Ada.Long_Integer_Wide_Text_IO}
13385 @item Long_Long_Integer
13386 @code{Ada.Long_Long_Integer_Wide_Text_IO}
13389 @item Ada.Wide_Text_IO.Modular_IO
13390 Provides input-output facilities for modular (unsigned) types
13392 @item Ada.Wide_Text_IO.Complex_IO (G.1.3)
13393 This package is similar to @code{Ada.Text_IO.Complex_IO}, except that the
13394 external file supports wide character representations.
13396 @item Ada.Wide_Text_IO.Editing (F.3.4)
13397 This package is similar to @code{Ada.Text_IO.Editing}, except that the
13398 types are @code{Wide_Character} and @code{Wide_String} instead of
13399 @code{Character} and @code{String}.
13401 @item Ada.Wide_Text_IO.Streams (A.12.3)
13402 This package is similar to @code{Ada.Text_IO.Streams}, except that the
13403 types are @code{Wide_Character} and @code{Wide_String} instead of
13404 @code{Character} and @code{String}.
13406 @item Ada.Wide_Wide_Text_IO (A.11)
13407 This package is similar to @code{Ada.Text_IO}, except that the external
13408 file supports wide character representations, and the internal types are
13409 @code{Wide_Character} and @code{Wide_String} instead of @code{Character}
13410 and @code{String}. It contains generic subpackages listed next.
13412 @item Ada.Wide_Wide_Text_IO.Decimal_IO
13413 Provides input-output facilities for decimal fixed-point types
13415 @item Ada.Wide_Wide_Text_IO.Enumeration_IO
13416 Provides input-output facilities for enumeration types.
13418 @item Ada.Wide_Wide_Text_IO.Fixed_IO
13419 Provides input-output facilities for ordinary fixed-point types.
13421 @item Ada.Wide_Wide_Text_IO.Float_IO
13422 Provides input-output facilities for float types. The following
13423 predefined instantiations of this generic package are available:
13427 @code{Short_Float_Wide_Wide_Text_IO}
13429 @code{Float_Wide_Wide_Text_IO}
13431 @code{Long_Float_Wide_Wide_Text_IO}
13434 @item Ada.Wide_Wide_Text_IO.Integer_IO
13435 Provides input-output facilities for integer types. The following
13436 predefined instantiations of this generic package are available:
13439 @item Short_Short_Integer
13440 @code{Ada.Short_Short_Integer_Wide_Wide_Text_IO}
13441 @item Short_Integer
13442 @code{Ada.Short_Integer_Wide_Wide_Text_IO}
13444 @code{Ada.Integer_Wide_Wide_Text_IO}
13446 @code{Ada.Long_Integer_Wide_Wide_Text_IO}
13447 @item Long_Long_Integer
13448 @code{Ada.Long_Long_Integer_Wide_Wide_Text_IO}
13451 @item Ada.Wide_Wide_Text_IO.Modular_IO
13452 Provides input-output facilities for modular (unsigned) types
13454 @item Ada.Wide_Wide_Text_IO.Complex_IO (G.1.3)
13455 This package is similar to @code{Ada.Text_IO.Complex_IO}, except that the
13456 external file supports wide character representations.
13458 @item Ada.Wide_Wide_Text_IO.Editing (F.3.4)
13459 This package is similar to @code{Ada.Text_IO.Editing}, except that the
13460 types are @code{Wide_Character} and @code{Wide_String} instead of
13461 @code{Character} and @code{String}.
13463 @item Ada.Wide_Wide_Text_IO.Streams (A.12.3)
13464 This package is similar to @code{Ada.Text_IO.Streams}, except that the
13465 types are @code{Wide_Character} and @code{Wide_String} instead of
13466 @code{Character} and @code{String}.
13469 @node The Implementation of Standard I/O
13470 @chapter The Implementation of Standard I/O
13473 GNAT implements all the required input-output facilities described in
13474 A.6 through A.14. These sections of the Ada Reference Manual describe the
13475 required behavior of these packages from the Ada point of view, and if
13476 you are writing a portable Ada program that does not need to know the
13477 exact manner in which Ada maps to the outside world when it comes to
13478 reading or writing external files, then you do not need to read this
13479 chapter. As long as your files are all regular files (not pipes or
13480 devices), and as long as you write and read the files only from Ada, the
13481 description in the Ada Reference Manual is sufficient.
13483 However, if you want to do input-output to pipes or other devices, such
13484 as the keyboard or screen, or if the files you are dealing with are
13485 either generated by some other language, or to be read by some other
13486 language, then you need to know more about the details of how the GNAT
13487 implementation of these input-output facilities behaves.
13489 In this chapter we give a detailed description of exactly how GNAT
13490 interfaces to the file system. As always, the sources of the system are
13491 available to you for answering questions at an even more detailed level,
13492 but for most purposes the information in this chapter will suffice.
13494 Another reason that you may need to know more about how input-output is
13495 implemented arises when you have a program written in mixed languages
13496 where, for example, files are shared between the C and Ada sections of
13497 the same program. GNAT provides some additional facilities, in the form
13498 of additional child library packages, that facilitate this sharing, and
13499 these additional facilities are also described in this chapter.
13502 * Standard I/O Packages::
13508 * Wide_Wide_Text_IO::
13510 * Text Translation::
13512 * Filenames encoding::
13514 * Operations on C Streams::
13515 * Interfacing to C Streams::
13518 @node Standard I/O Packages
13519 @section Standard I/O Packages
13522 The Standard I/O packages described in Annex A for
13528 Ada.Text_IO.Complex_IO
13530 Ada.Text_IO.Text_Streams
13534 Ada.Wide_Text_IO.Complex_IO
13536 Ada.Wide_Text_IO.Text_Streams
13538 Ada.Wide_Wide_Text_IO
13540 Ada.Wide_Wide_Text_IO.Complex_IO
13542 Ada.Wide_Wide_Text_IO.Text_Streams
13552 are implemented using the C
13553 library streams facility; where
13557 All files are opened using @code{fopen}.
13559 All input/output operations use @code{fread}/@code{fwrite}.
13563 There is no internal buffering of any kind at the Ada library level. The only
13564 buffering is that provided at the system level in the implementation of the
13565 library routines that support streams. This facilitates shared use of these
13566 streams by mixed language programs. Note though that system level buffering is
13567 explicitly enabled at elaboration of the standard I/O packages and that can
13568 have an impact on mixed language programs, in particular those using I/O before
13569 calling the Ada elaboration routine (e.g.@: adainit). It is recommended to call
13570 the Ada elaboration routine before performing any I/O or when impractical,
13571 flush the common I/O streams and in particular Standard_Output before
13572 elaborating the Ada code.
13575 @section FORM Strings
13578 The format of a FORM string in GNAT is:
13581 "keyword=value,keyword=value,@dots{},keyword=value"
13585 where letters may be in upper or lower case, and there are no spaces
13586 between values. The order of the entries is not important. Currently
13587 the following keywords defined.
13590 TEXT_TRANSLATION=[YES|NO]
13592 WCEM=[n|h|u|s|e|8|b]
13593 ENCODING=[UTF8|8BITS]
13597 The use of these parameters is described later in this section.
13603 Direct_IO can only be instantiated for definite types. This is a
13604 restriction of the Ada language, which means that the records are fixed
13605 length (the length being determined by @code{@var{type}'Size}, rounded
13606 up to the next storage unit boundary if necessary).
13608 The records of a Direct_IO file are simply written to the file in index
13609 sequence, with the first record starting at offset zero, and subsequent
13610 records following. There is no control information of any kind. For
13611 example, if 32-bit integers are being written, each record takes
13612 4-bytes, so the record at index @var{K} starts at offset
13613 (@var{K}@minus{}1)*4.
13615 There is no limit on the size of Direct_IO files, they are expanded as
13616 necessary to accommodate whatever records are written to the file.
13618 @node Sequential_IO
13619 @section Sequential_IO
13622 Sequential_IO may be instantiated with either a definite (constrained)
13623 or indefinite (unconstrained) type.
13625 For the definite type case, the elements written to the file are simply
13626 the memory images of the data values with no control information of any
13627 kind. The resulting file should be read using the same type, no validity
13628 checking is performed on input.
13630 For the indefinite type case, the elements written consist of two
13631 parts. First is the size of the data item, written as the memory image
13632 of a @code{Interfaces.C.size_t} value, followed by the memory image of
13633 the data value. The resulting file can only be read using the same
13634 (unconstrained) type. Normal assignment checks are performed on these
13635 read operations, and if these checks fail, @code{Data_Error} is
13636 raised. In particular, in the array case, the lengths must match, and in
13637 the variant record case, if the variable for a particular read operation
13638 is constrained, the discriminants must match.
13640 Note that it is not possible to use Sequential_IO to write variable
13641 length array items, and then read the data back into different length
13642 arrays. For example, the following will raise @code{Data_Error}:
13644 @smallexample @c ada
13645 package IO is new Sequential_IO (String);
13650 IO.Write (F, "hello!")
13651 IO.Reset (F, Mode=>In_File);
13658 On some Ada implementations, this will print @code{hell}, but the program is
13659 clearly incorrect, since there is only one element in the file, and that
13660 element is the string @code{hello!}.
13662 In Ada 95 and Ada 2005, this kind of behavior can be legitimately achieved
13663 using Stream_IO, and this is the preferred mechanism. In particular, the
13664 above program fragment rewritten to use Stream_IO will work correctly.
13670 Text_IO files consist of a stream of characters containing the following
13671 special control characters:
13674 LF (line feed, 16#0A#) Line Mark
13675 FF (form feed, 16#0C#) Page Mark
13679 A canonical Text_IO file is defined as one in which the following
13680 conditions are met:
13684 The character @code{LF} is used only as a line mark, i.e.@: to mark the end
13688 The character @code{FF} is used only as a page mark, i.e.@: to mark the
13689 end of a page and consequently can appear only immediately following a
13690 @code{LF} (line mark) character.
13693 The file ends with either @code{LF} (line mark) or @code{LF}-@code{FF}
13694 (line mark, page mark). In the former case, the page mark is implicitly
13695 assumed to be present.
13699 A file written using Text_IO will be in canonical form provided that no
13700 explicit @code{LF} or @code{FF} characters are written using @code{Put}
13701 or @code{Put_Line}. There will be no @code{FF} character at the end of
13702 the file unless an explicit @code{New_Page} operation was performed
13703 before closing the file.
13705 A canonical Text_IO file that is a regular file (i.e., not a device or a
13706 pipe) can be read using any of the routines in Text_IO@. The
13707 semantics in this case will be exactly as defined in the Ada Reference
13708 Manual, and all the routines in Text_IO are fully implemented.
13710 A text file that does not meet the requirements for a canonical Text_IO
13711 file has one of the following:
13715 The file contains @code{FF} characters not immediately following a
13716 @code{LF} character.
13719 The file contains @code{LF} or @code{FF} characters written by
13720 @code{Put} or @code{Put_Line}, which are not logically considered to be
13721 line marks or page marks.
13724 The file ends in a character other than @code{LF} or @code{FF},
13725 i.e.@: there is no explicit line mark or page mark at the end of the file.
13729 Text_IO can be used to read such non-standard text files but subprograms
13730 to do with line or page numbers do not have defined meanings. In
13731 particular, a @code{FF} character that does not follow a @code{LF}
13732 character may or may not be treated as a page mark from the point of
13733 view of page and line numbering. Every @code{LF} character is considered
13734 to end a line, and there is an implied @code{LF} character at the end of
13738 * Text_IO Stream Pointer Positioning::
13739 * Text_IO Reading and Writing Non-Regular Files::
13741 * Treating Text_IO Files as Streams::
13742 * Text_IO Extensions::
13743 * Text_IO Facilities for Unbounded Strings::
13746 @node Text_IO Stream Pointer Positioning
13747 @subsection Stream Pointer Positioning
13750 @code{Ada.Text_IO} has a definition of current position for a file that
13751 is being read. No internal buffering occurs in Text_IO, and usually the
13752 physical position in the stream used to implement the file corresponds
13753 to this logical position defined by Text_IO@. There are two exceptions:
13757 After a call to @code{End_Of_Page} that returns @code{True}, the stream
13758 is positioned past the @code{LF} (line mark) that precedes the page
13759 mark. Text_IO maintains an internal flag so that subsequent read
13760 operations properly handle the logical position which is unchanged by
13761 the @code{End_Of_Page} call.
13764 After a call to @code{End_Of_File} that returns @code{True}, if the
13765 Text_IO file was positioned before the line mark at the end of file
13766 before the call, then the logical position is unchanged, but the stream
13767 is physically positioned right at the end of file (past the line mark,
13768 and past a possible page mark following the line mark. Again Text_IO
13769 maintains internal flags so that subsequent read operations properly
13770 handle the logical position.
13774 These discrepancies have no effect on the observable behavior of
13775 Text_IO, but if a single Ada stream is shared between a C program and
13776 Ada program, or shared (using @samp{shared=yes} in the form string)
13777 between two Ada files, then the difference may be observable in some
13780 @node Text_IO Reading and Writing Non-Regular Files
13781 @subsection Reading and Writing Non-Regular Files
13784 A non-regular file is a device (such as a keyboard), or a pipe. Text_IO
13785 can be used for reading and writing. Writing is not affected and the
13786 sequence of characters output is identical to the normal file case, but
13787 for reading, the behavior of Text_IO is modified to avoid undesirable
13788 look-ahead as follows:
13790 An input file that is not a regular file is considered to have no page
13791 marks. Any @code{Ascii.FF} characters (the character normally used for a
13792 page mark) appearing in the file are considered to be data
13793 characters. In particular:
13797 @code{Get_Line} and @code{Skip_Line} do not test for a page mark
13798 following a line mark. If a page mark appears, it will be treated as a
13802 This avoids the need to wait for an extra character to be typed or
13803 entered from the pipe to complete one of these operations.
13806 @code{End_Of_Page} always returns @code{False}
13809 @code{End_Of_File} will return @code{False} if there is a page mark at
13810 the end of the file.
13814 Output to non-regular files is the same as for regular files. Page marks
13815 may be written to non-regular files using @code{New_Page}, but as noted
13816 above they will not be treated as page marks on input if the output is
13817 piped to another Ada program.
13819 Another important discrepancy when reading non-regular files is that the end
13820 of file indication is not ``sticky''. If an end of file is entered, e.g.@: by
13821 pressing the @key{EOT} key,
13823 is signaled once (i.e.@: the test @code{End_Of_File}
13824 will yield @code{True}, or a read will
13825 raise @code{End_Error}), but then reading can resume
13826 to read data past that end of
13827 file indication, until another end of file indication is entered.
13829 @node Get_Immediate
13830 @subsection Get_Immediate
13831 @cindex Get_Immediate
13834 Get_Immediate returns the next character (including control characters)
13835 from the input file. In particular, Get_Immediate will return LF or FF
13836 characters used as line marks or page marks. Such operations leave the
13837 file positioned past the control character, and it is thus not treated
13838 as having its normal function. This means that page, line and column
13839 counts after this kind of Get_Immediate call are set as though the mark
13840 did not occur. In the case where a Get_Immediate leaves the file
13841 positioned between the line mark and page mark (which is not normally
13842 possible), it is undefined whether the FF character will be treated as a
13845 @node Treating Text_IO Files as Streams
13846 @subsection Treating Text_IO Files as Streams
13847 @cindex Stream files
13850 The package @code{Text_IO.Streams} allows a Text_IO file to be treated
13851 as a stream. Data written to a Text_IO file in this stream mode is
13852 binary data. If this binary data contains bytes 16#0A# (@code{LF}) or
13853 16#0C# (@code{FF}), the resulting file may have non-standard
13854 format. Similarly if read operations are used to read from a Text_IO
13855 file treated as a stream, then @code{LF} and @code{FF} characters may be
13856 skipped and the effect is similar to that described above for
13857 @code{Get_Immediate}.
13859 @node Text_IO Extensions
13860 @subsection Text_IO Extensions
13861 @cindex Text_IO extensions
13864 A package GNAT.IO_Aux in the GNAT library provides some useful extensions
13865 to the standard @code{Text_IO} package:
13868 @item function File_Exists (Name : String) return Boolean;
13869 Determines if a file of the given name exists.
13871 @item function Get_Line return String;
13872 Reads a string from the standard input file. The value returned is exactly
13873 the length of the line that was read.
13875 @item function Get_Line (File : Ada.Text_IO.File_Type) return String;
13876 Similar, except that the parameter File specifies the file from which
13877 the string is to be read.
13881 @node Text_IO Facilities for Unbounded Strings
13882 @subsection Text_IO Facilities for Unbounded Strings
13883 @cindex Text_IO for unbounded strings
13884 @cindex Unbounded_String, Text_IO operations
13887 The package @code{Ada.Strings.Unbounded.Text_IO}
13888 in library files @code{a-suteio.ads/adb} contains some GNAT-specific
13889 subprograms useful for Text_IO operations on unbounded strings:
13893 @item function Get_Line (File : File_Type) return Unbounded_String;
13894 Reads a line from the specified file
13895 and returns the result as an unbounded string.
13897 @item procedure Put (File : File_Type; U : Unbounded_String);
13898 Writes the value of the given unbounded string to the specified file
13899 Similar to the effect of
13900 @code{Put (To_String (U))} except that an extra copy is avoided.
13902 @item procedure Put_Line (File : File_Type; U : Unbounded_String);
13903 Writes the value of the given unbounded string to the specified file,
13904 followed by a @code{New_Line}.
13905 Similar to the effect of @code{Put_Line (To_String (U))} except
13906 that an extra copy is avoided.
13910 In the above procedures, @code{File} is of type @code{Ada.Text_IO.File_Type}
13911 and is optional. If the parameter is omitted, then the standard input or
13912 output file is referenced as appropriate.
13914 The package @code{Ada.Strings.Wide_Unbounded.Wide_Text_IO} in library
13915 files @file{a-swuwti.ads} and @file{a-swuwti.adb} provides similar extended
13916 @code{Wide_Text_IO} functionality for unbounded wide strings.
13918 The package @code{Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO} in library
13919 files @file{a-szuzti.ads} and @file{a-szuzti.adb} provides similar extended
13920 @code{Wide_Wide_Text_IO} functionality for unbounded wide wide strings.
13923 @section Wide_Text_IO
13926 @code{Wide_Text_IO} is similar in most respects to Text_IO, except that
13927 both input and output files may contain special sequences that represent
13928 wide character values. The encoding scheme for a given file may be
13929 specified using a FORM parameter:
13936 as part of the FORM string (WCEM = wide character encoding method),
13937 where @var{x} is one of the following characters
13943 Upper half encoding
13955 The encoding methods match those that
13956 can be used in a source
13957 program, but there is no requirement that the encoding method used for
13958 the source program be the same as the encoding method used for files,
13959 and different files may use different encoding methods.
13961 The default encoding method for the standard files, and for opened files
13962 for which no WCEM parameter is given in the FORM string matches the
13963 wide character encoding specified for the main program (the default
13964 being brackets encoding if no coding method was specified with -gnatW).
13968 In this encoding, a wide character is represented by a five character
13976 where @var{a}, @var{b}, @var{c}, @var{d} are the four hexadecimal
13977 characters (using upper case letters) of the wide character code. For
13978 example, ESC A345 is used to represent the wide character with code
13979 16#A345#. This scheme is compatible with use of the full
13980 @code{Wide_Character} set.
13982 @item Upper Half Coding
13983 The wide character with encoding 16#abcd#, where the upper bit is on
13984 (i.e.@: a is in the range 8-F) is represented as two bytes 16#ab# and
13985 16#cd#. The second byte may never be a format control character, but is
13986 not required to be in the upper half. This method can be also used for
13987 shift-JIS or EUC where the internal coding matches the external coding.
13989 @item Shift JIS Coding
13990 A wide character is represented by a two character sequence 16#ab# and
13991 16#cd#, with the restrictions described for upper half encoding as
13992 described above. The internal character code is the corresponding JIS
13993 character according to the standard algorithm for Shift-JIS
13994 conversion. Only characters defined in the JIS code set table can be
13995 used with this encoding method.
13998 A wide character is represented by a two character sequence 16#ab# and
13999 16#cd#, with both characters being in the upper half. The internal
14000 character code is the corresponding JIS character according to the EUC
14001 encoding algorithm. Only characters defined in the JIS code set table
14002 can be used with this encoding method.
14005 A wide character is represented using
14006 UCS Transformation Format 8 (UTF-8) as defined in Annex R of ISO
14007 10646-1/Am.2. Depending on the character value, the representation
14008 is a one, two, or three byte sequence:
14011 16#0000#-16#007f#: 2#0xxxxxxx#
14012 16#0080#-16#07ff#: 2#110xxxxx# 2#10xxxxxx#
14013 16#0800#-16#ffff#: 2#1110xxxx# 2#10xxxxxx# 2#10xxxxxx#
14017 where the @var{xxx} bits correspond to the left-padded bits of the
14018 16-bit character value. Note that all lower half ASCII characters
14019 are represented as ASCII bytes and all upper half characters and
14020 other wide characters are represented as sequences of upper-half
14021 (The full UTF-8 scheme allows for encoding 31-bit characters as
14022 6-byte sequences, but in this implementation, all UTF-8 sequences
14023 of four or more bytes length will raise a Constraint_Error, as
14024 will all invalid UTF-8 sequences.)
14026 @item Brackets Coding
14027 In this encoding, a wide character is represented by the following eight
14028 character sequence:
14035 where @code{a}, @code{b}, @code{c}, @code{d} are the four hexadecimal
14036 characters (using uppercase letters) of the wide character code. For
14037 example, @code{["A345"]} is used to represent the wide character with code
14039 This scheme is compatible with use of the full Wide_Character set.
14040 On input, brackets coding can also be used for upper half characters,
14041 e.g.@: @code{["C1"]} for lower case a. However, on output, brackets notation
14042 is only used for wide characters with a code greater than @code{16#FF#}.
14044 Note that brackets coding is not normally used in the context of
14045 Wide_Text_IO or Wide_Wide_Text_IO, since it is really just designed as
14046 a portable way of encoding source files. In the context of Wide_Text_IO
14047 or Wide_Wide_Text_IO, it can only be used if the file does not contain
14048 any instance of the left bracket character other than to encode wide
14049 character values using the brackets encoding method. In practice it is
14050 expected that some standard wide character encoding method such
14051 as UTF-8 will be used for text input output.
14053 If brackets notation is used, then any occurrence of a left bracket
14054 in the input file which is not the start of a valid wide character
14055 sequence will cause Constraint_Error to be raised. It is possible to
14056 encode a left bracket as ["5B"] and Wide_Text_IO and Wide_Wide_Text_IO
14057 input will interpret this as a left bracket.
14059 However, when a left bracket is output, it will be output as a left bracket
14060 and not as ["5B"]. We make this decision because for normal use of
14061 Wide_Text_IO for outputting messages, it is unpleasant to clobber left
14062 brackets. For example, if we write:
14065 Put_Line ("Start of output [first run]");
14069 we really do not want to have the left bracket in this message clobbered so
14070 that the output reads:
14073 Start of output ["5B"]first run]
14077 In practice brackets encoding is reasonably useful for normal Put_Line use
14078 since we won't get confused between left brackets and wide character
14079 sequences in the output. But for input, or when files are written out
14080 and read back in, it really makes better sense to use one of the standard
14081 encoding methods such as UTF-8.
14086 For the coding schemes other than UTF-8, Hex, or Brackets encoding,
14087 not all wide character
14088 values can be represented. An attempt to output a character that cannot
14089 be represented using the encoding scheme for the file causes
14090 Constraint_Error to be raised. An invalid wide character sequence on
14091 input also causes Constraint_Error to be raised.
14094 * Wide_Text_IO Stream Pointer Positioning::
14095 * Wide_Text_IO Reading and Writing Non-Regular Files::
14098 @node Wide_Text_IO Stream Pointer Positioning
14099 @subsection Stream Pointer Positioning
14102 @code{Ada.Wide_Text_IO} is similar to @code{Ada.Text_IO} in its handling
14103 of stream pointer positioning (@pxref{Text_IO}). There is one additional
14106 If @code{Ada.Wide_Text_IO.Look_Ahead} reads a character outside the
14107 normal lower ASCII set (i.e.@: a character in the range:
14109 @smallexample @c ada
14110 Wide_Character'Val (16#0080#) .. Wide_Character'Val (16#FFFF#)
14114 then although the logical position of the file pointer is unchanged by
14115 the @code{Look_Ahead} call, the stream is physically positioned past the
14116 wide character sequence. Again this is to avoid the need for buffering
14117 or backup, and all @code{Wide_Text_IO} routines check the internal
14118 indication that this situation has occurred so that this is not visible
14119 to a normal program using @code{Wide_Text_IO}. However, this discrepancy
14120 can be observed if the wide text file shares a stream with another file.
14122 @node Wide_Text_IO Reading and Writing Non-Regular Files
14123 @subsection Reading and Writing Non-Regular Files
14126 As in the case of Text_IO, when a non-regular file is read, it is
14127 assumed that the file contains no page marks (any form characters are
14128 treated as data characters), and @code{End_Of_Page} always returns
14129 @code{False}. Similarly, the end of file indication is not sticky, so
14130 it is possible to read beyond an end of file.
14132 @node Wide_Wide_Text_IO
14133 @section Wide_Wide_Text_IO
14136 @code{Wide_Wide_Text_IO} is similar in most respects to Text_IO, except that
14137 both input and output files may contain special sequences that represent
14138 wide wide character values. The encoding scheme for a given file may be
14139 specified using a FORM parameter:
14146 as part of the FORM string (WCEM = wide character encoding method),
14147 where @var{x} is one of the following characters
14153 Upper half encoding
14165 The encoding methods match those that
14166 can be used in a source
14167 program, but there is no requirement that the encoding method used for
14168 the source program be the same as the encoding method used for files,
14169 and different files may use different encoding methods.
14171 The default encoding method for the standard files, and for opened files
14172 for which no WCEM parameter is given in the FORM string matches the
14173 wide character encoding specified for the main program (the default
14174 being brackets encoding if no coding method was specified with -gnatW).
14179 A wide character is represented using
14180 UCS Transformation Format 8 (UTF-8) as defined in Annex R of ISO
14181 10646-1/Am.2. Depending on the character value, the representation
14182 is a one, two, three, or four byte sequence:
14185 16#000000#-16#00007f#: 2#0xxxxxxx#
14186 16#000080#-16#0007ff#: 2#110xxxxx# 2#10xxxxxx#
14187 16#000800#-16#00ffff#: 2#1110xxxx# 2#10xxxxxx# 2#10xxxxxx#
14188 16#010000#-16#10ffff#: 2#11110xxx# 2#10xxxxxx# 2#10xxxxxx# 2#10xxxxxx#
14192 where the @var{xxx} bits correspond to the left-padded bits of the
14193 21-bit character value. Note that all lower half ASCII characters
14194 are represented as ASCII bytes and all upper half characters and
14195 other wide characters are represented as sequences of upper-half
14198 @item Brackets Coding
14199 In this encoding, a wide wide character is represented by the following eight
14200 character sequence if is in wide character range
14206 and by the following ten character sequence if not
14209 [ " a b c d e f " ]
14213 where @code{a}, @code{b}, @code{c}, @code{d}, @code{e}, and @code{f}
14214 are the four or six hexadecimal
14215 characters (using uppercase letters) of the wide wide character code. For
14216 example, @code{["01A345"]} is used to represent the wide wide character
14217 with code @code{16#01A345#}.
14219 This scheme is compatible with use of the full Wide_Wide_Character set.
14220 On input, brackets coding can also be used for upper half characters,
14221 e.g.@: @code{["C1"]} for lower case a. However, on output, brackets notation
14222 is only used for wide characters with a code greater than @code{16#FF#}.
14227 If is also possible to use the other Wide_Character encoding methods,
14228 such as Shift-JIS, but the other schemes cannot support the full range
14229 of wide wide characters.
14230 An attempt to output a character that cannot
14231 be represented using the encoding scheme for the file causes
14232 Constraint_Error to be raised. An invalid wide character sequence on
14233 input also causes Constraint_Error to be raised.
14236 * Wide_Wide_Text_IO Stream Pointer Positioning::
14237 * Wide_Wide_Text_IO Reading and Writing Non-Regular Files::
14240 @node Wide_Wide_Text_IO Stream Pointer Positioning
14241 @subsection Stream Pointer Positioning
14244 @code{Ada.Wide_Wide_Text_IO} is similar to @code{Ada.Text_IO} in its handling
14245 of stream pointer positioning (@pxref{Text_IO}). There is one additional
14248 If @code{Ada.Wide_Wide_Text_IO.Look_Ahead} reads a character outside the
14249 normal lower ASCII set (i.e.@: a character in the range:
14251 @smallexample @c ada
14252 Wide_Wide_Character'Val (16#0080#) .. Wide_Wide_Character'Val (16#10FFFF#)
14256 then although the logical position of the file pointer is unchanged by
14257 the @code{Look_Ahead} call, the stream is physically positioned past the
14258 wide character sequence. Again this is to avoid the need for buffering
14259 or backup, and all @code{Wide_Wide_Text_IO} routines check the internal
14260 indication that this situation has occurred so that this is not visible
14261 to a normal program using @code{Wide_Wide_Text_IO}. However, this discrepancy
14262 can be observed if the wide text file shares a stream with another file.
14264 @node Wide_Wide_Text_IO Reading and Writing Non-Regular Files
14265 @subsection Reading and Writing Non-Regular Files
14268 As in the case of Text_IO, when a non-regular file is read, it is
14269 assumed that the file contains no page marks (any form characters are
14270 treated as data characters), and @code{End_Of_Page} always returns
14271 @code{False}. Similarly, the end of file indication is not sticky, so
14272 it is possible to read beyond an end of file.
14278 A stream file is a sequence of bytes, where individual elements are
14279 written to the file as described in the Ada Reference Manual. The type
14280 @code{Stream_Element} is simply a byte. There are two ways to read or
14281 write a stream file.
14285 The operations @code{Read} and @code{Write} directly read or write a
14286 sequence of stream elements with no control information.
14289 The stream attributes applied to a stream file transfer data in the
14290 manner described for stream attributes.
14293 @node Text Translation
14294 @section Text Translation
14297 @samp{Text_Translation=@var{xxx}} may be used as the Form parameter
14298 passed to Text_IO.Create and Text_IO.Open:
14299 @samp{Text_Translation=@var{Yes}} is the default, which means to
14300 translate LF to/from CR/LF on Windows systems.
14301 @samp{Text_Translation=@var{No}} disables this translation; i.e. it
14302 uses binary mode. For output files, @samp{Text_Translation=@var{No}}
14303 may be used to create Unix-style files on
14304 Windows. @samp{Text_Translation=@var{xxx}} has no effect on Unix
14308 @section Shared Files
14311 Section A.14 of the Ada Reference Manual allows implementations to
14312 provide a wide variety of behavior if an attempt is made to access the
14313 same external file with two or more internal files.
14315 To provide a full range of functionality, while at the same time
14316 minimizing the problems of portability caused by this implementation
14317 dependence, GNAT handles file sharing as follows:
14321 In the absence of a @samp{shared=@var{xxx}} form parameter, an attempt
14322 to open two or more files with the same full name is considered an error
14323 and is not supported. The exception @code{Use_Error} will be
14324 raised. Note that a file that is not explicitly closed by the program
14325 remains open until the program terminates.
14328 If the form parameter @samp{shared=no} appears in the form string, the
14329 file can be opened or created with its own separate stream identifier,
14330 regardless of whether other files sharing the same external file are
14331 opened. The exact effect depends on how the C stream routines handle
14332 multiple accesses to the same external files using separate streams.
14335 If the form parameter @samp{shared=yes} appears in the form string for
14336 each of two or more files opened using the same full name, the same
14337 stream is shared between these files, and the semantics are as described
14338 in Ada Reference Manual, Section A.14.
14342 When a program that opens multiple files with the same name is ported
14343 from another Ada compiler to GNAT, the effect will be that
14344 @code{Use_Error} is raised.
14346 The documentation of the original compiler and the documentation of the
14347 program should then be examined to determine if file sharing was
14348 expected, and @samp{shared=@var{xxx}} parameters added to @code{Open}
14349 and @code{Create} calls as required.
14351 When a program is ported from GNAT to some other Ada compiler, no
14352 special attention is required unless the @samp{shared=@var{xxx}} form
14353 parameter is used in the program. In this case, you must examine the
14354 documentation of the new compiler to see if it supports the required
14355 file sharing semantics, and form strings modified appropriately. Of
14356 course it may be the case that the program cannot be ported if the
14357 target compiler does not support the required functionality. The best
14358 approach in writing portable code is to avoid file sharing (and hence
14359 the use of the @samp{shared=@var{xxx}} parameter in the form string)
14362 One common use of file sharing in Ada 83 is the use of instantiations of
14363 Sequential_IO on the same file with different types, to achieve
14364 heterogeneous input-output. Although this approach will work in GNAT if
14365 @samp{shared=yes} is specified, it is preferable in Ada to use Stream_IO
14366 for this purpose (using the stream attributes)
14368 @node Filenames encoding
14369 @section Filenames encoding
14372 An encoding form parameter can be used to specify the filename
14373 encoding @samp{encoding=@var{xxx}}.
14377 If the form parameter @samp{encoding=utf8} appears in the form string, the
14378 filename must be encoded in UTF-8.
14381 If the form parameter @samp{encoding=8bits} appears in the form
14382 string, the filename must be a standard 8bits string.
14385 In the absence of a @samp{encoding=@var{xxx}} form parameter, the
14386 encoding is controlled by the @samp{GNAT_CODE_PAGE} environment
14387 variable. And if not set @samp{utf8} is assumed.
14391 The current system Windows ANSI code page.
14396 This encoding form parameter is only supported on the Windows
14397 platform. On the other Operating Systems the run-time is supporting
14401 @section Open Modes
14404 @code{Open} and @code{Create} calls result in a call to @code{fopen}
14405 using the mode shown in the following table:
14408 @center @code{Open} and @code{Create} Call Modes
14410 @b{OPEN } @b{CREATE}
14411 Append_File "r+" "w+"
14413 Out_File (Direct_IO) "r+" "w"
14414 Out_File (all other cases) "w" "w"
14415 Inout_File "r+" "w+"
14419 If text file translation is required, then either @samp{b} or @samp{t}
14420 is added to the mode, depending on the setting of Text. Text file
14421 translation refers to the mapping of CR/LF sequences in an external file
14422 to LF characters internally. This mapping only occurs in DOS and
14423 DOS-like systems, and is not relevant to other systems.
14425 A special case occurs with Stream_IO@. As shown in the above table, the
14426 file is initially opened in @samp{r} or @samp{w} mode for the
14427 @code{In_File} and @code{Out_File} cases. If a @code{Set_Mode} operation
14428 subsequently requires switching from reading to writing or vice-versa,
14429 then the file is reopened in @samp{r+} mode to permit the required operation.
14431 @node Operations on C Streams
14432 @section Operations on C Streams
14433 The package @code{Interfaces.C_Streams} provides an Ada program with direct
14434 access to the C library functions for operations on C streams:
14436 @smallexample @c adanocomment
14437 package Interfaces.C_Streams is
14438 -- Note: the reason we do not use the types that are in
14439 -- Interfaces.C is that we want to avoid dragging in the
14440 -- code in this unit if possible.
14441 subtype chars is System.Address;
14442 -- Pointer to null-terminated array of characters
14443 subtype FILEs is System.Address;
14444 -- Corresponds to the C type FILE*
14445 subtype voids is System.Address;
14446 -- Corresponds to the C type void*
14447 subtype int is Integer;
14448 subtype long is Long_Integer;
14449 -- Note: the above types are subtypes deliberately, and it
14450 -- is part of this spec that the above correspondences are
14451 -- guaranteed. This means that it is legitimate to, for
14452 -- example, use Integer instead of int. We provide these
14453 -- synonyms for clarity, but in some cases it may be
14454 -- convenient to use the underlying types (for example to
14455 -- avoid an unnecessary dependency of a spec on the spec
14457 type size_t is mod 2 ** Standard'Address_Size;
14458 NULL_Stream : constant FILEs;
14459 -- Value returned (NULL in C) to indicate an
14460 -- fdopen/fopen/tmpfile error
14461 ----------------------------------
14462 -- Constants Defined in stdio.h --
14463 ----------------------------------
14464 EOF : constant int;
14465 -- Used by a number of routines to indicate error or
14467 IOFBF : constant int;
14468 IOLBF : constant int;
14469 IONBF : constant int;
14470 -- Used to indicate buffering mode for setvbuf call
14471 SEEK_CUR : constant int;
14472 SEEK_END : constant int;
14473 SEEK_SET : constant int;
14474 -- Used to indicate origin for fseek call
14475 function stdin return FILEs;
14476 function stdout return FILEs;
14477 function stderr return FILEs;
14478 -- Streams associated with standard files
14479 --------------------------
14480 -- Standard C functions --
14481 --------------------------
14482 -- The functions selected below are ones that are
14483 -- available in UNIX (but not necessarily in ANSI C).
14484 -- These are very thin interfaces
14485 -- which copy exactly the C headers. For more
14486 -- documentation on these functions, see the Microsoft C
14487 -- "Run-Time Library Reference" (Microsoft Press, 1990,
14488 -- ISBN 1-55615-225-6), which includes useful information
14489 -- on system compatibility.
14490 procedure clearerr (stream : FILEs);
14491 function fclose (stream : FILEs) return int;
14492 function fdopen (handle : int; mode : chars) return FILEs;
14493 function feof (stream : FILEs) return int;
14494 function ferror (stream : FILEs) return int;
14495 function fflush (stream : FILEs) return int;
14496 function fgetc (stream : FILEs) return int;
14497 function fgets (strng : chars; n : int; stream : FILEs)
14499 function fileno (stream : FILEs) return int;
14500 function fopen (filename : chars; Mode : chars)
14502 -- Note: to maintain target independence, use
14503 -- text_translation_required, a boolean variable defined in
14504 -- a-sysdep.c to deal with the target dependent text
14505 -- translation requirement. If this variable is set,
14506 -- then b/t should be appended to the standard mode
14507 -- argument to set the text translation mode off or on
14509 function fputc (C : int; stream : FILEs) return int;
14510 function fputs (Strng : chars; Stream : FILEs) return int;
14527 function ftell (stream : FILEs) return long;
14534 function isatty (handle : int) return int;
14535 procedure mktemp (template : chars);
14536 -- The return value (which is just a pointer to template)
14538 procedure rewind (stream : FILEs);
14539 function rmtmp return int;
14547 function tmpfile return FILEs;
14548 function ungetc (c : int; stream : FILEs) return int;
14549 function unlink (filename : chars) return int;
14550 ---------------------
14551 -- Extra functions --
14552 ---------------------
14553 -- These functions supply slightly thicker bindings than
14554 -- those above. They are derived from functions in the
14555 -- C Run-Time Library, but may do a bit more work than
14556 -- just directly calling one of the Library functions.
14557 function is_regular_file (handle : int) return int;
14558 -- Tests if given handle is for a regular file (result 1)
14559 -- or for a non-regular file (pipe or device, result 0).
14560 ---------------------------------
14561 -- Control of Text/Binary Mode --
14562 ---------------------------------
14563 -- If text_translation_required is true, then the following
14564 -- functions may be used to dynamically switch a file from
14565 -- binary to text mode or vice versa. These functions have
14566 -- no effect if text_translation_required is false (i.e.@: in
14567 -- normal UNIX mode). Use fileno to get a stream handle.
14568 procedure set_binary_mode (handle : int);
14569 procedure set_text_mode (handle : int);
14570 ----------------------------
14571 -- Full Path Name support --
14572 ----------------------------
14573 procedure full_name (nam : chars; buffer : chars);
14574 -- Given a NUL terminated string representing a file
14575 -- name, returns in buffer a NUL terminated string
14576 -- representing the full path name for the file name.
14577 -- On systems where it is relevant the drive is also
14578 -- part of the full path name. It is the responsibility
14579 -- of the caller to pass an actual parameter for buffer
14580 -- that is big enough for any full path name. Use
14581 -- max_path_len given below as the size of buffer.
14582 max_path_len : integer;
14583 -- Maximum length of an allowable full path name on the
14584 -- system, including a terminating NUL character.
14585 end Interfaces.C_Streams;
14588 @node Interfacing to C Streams
14589 @section Interfacing to C Streams
14592 The packages in this section permit interfacing Ada files to C Stream
14595 @smallexample @c ada
14596 with Interfaces.C_Streams;
14597 package Ada.Sequential_IO.C_Streams is
14598 function C_Stream (F : File_Type)
14599 return Interfaces.C_Streams.FILEs;
14601 (File : in out File_Type;
14602 Mode : in File_Mode;
14603 C_Stream : in Interfaces.C_Streams.FILEs;
14604 Form : in String := "");
14605 end Ada.Sequential_IO.C_Streams;
14607 with Interfaces.C_Streams;
14608 package Ada.Direct_IO.C_Streams is
14609 function C_Stream (F : File_Type)
14610 return Interfaces.C_Streams.FILEs;
14612 (File : in out File_Type;
14613 Mode : in File_Mode;
14614 C_Stream : in Interfaces.C_Streams.FILEs;
14615 Form : in String := "");
14616 end Ada.Direct_IO.C_Streams;
14618 with Interfaces.C_Streams;
14619 package Ada.Text_IO.C_Streams is
14620 function C_Stream (F : File_Type)
14621 return Interfaces.C_Streams.FILEs;
14623 (File : in out File_Type;
14624 Mode : in File_Mode;
14625 C_Stream : in Interfaces.C_Streams.FILEs;
14626 Form : in String := "");
14627 end Ada.Text_IO.C_Streams;
14629 with Interfaces.C_Streams;
14630 package Ada.Wide_Text_IO.C_Streams is
14631 function C_Stream (F : File_Type)
14632 return Interfaces.C_Streams.FILEs;
14634 (File : in out File_Type;
14635 Mode : in File_Mode;
14636 C_Stream : in Interfaces.C_Streams.FILEs;
14637 Form : in String := "");
14638 end Ada.Wide_Text_IO.C_Streams;
14640 with Interfaces.C_Streams;
14641 package Ada.Wide_Wide_Text_IO.C_Streams is
14642 function C_Stream (F : File_Type)
14643 return Interfaces.C_Streams.FILEs;
14645 (File : in out File_Type;
14646 Mode : in File_Mode;
14647 C_Stream : in Interfaces.C_Streams.FILEs;
14648 Form : in String := "");
14649 end Ada.Wide_Wide_Text_IO.C_Streams;
14651 with Interfaces.C_Streams;
14652 package Ada.Stream_IO.C_Streams is
14653 function C_Stream (F : File_Type)
14654 return Interfaces.C_Streams.FILEs;
14656 (File : in out File_Type;
14657 Mode : in File_Mode;
14658 C_Stream : in Interfaces.C_Streams.FILEs;
14659 Form : in String := "");
14660 end Ada.Stream_IO.C_Streams;
14664 In each of these six packages, the @code{C_Stream} function obtains the
14665 @code{FILE} pointer from a currently opened Ada file. It is then
14666 possible to use the @code{Interfaces.C_Streams} package to operate on
14667 this stream, or the stream can be passed to a C program which can
14668 operate on it directly. Of course the program is responsible for
14669 ensuring that only appropriate sequences of operations are executed.
14671 One particular use of relevance to an Ada program is that the
14672 @code{setvbuf} function can be used to control the buffering of the
14673 stream used by an Ada file. In the absence of such a call the standard
14674 default buffering is used.
14676 The @code{Open} procedures in these packages open a file giving an
14677 existing C Stream instead of a file name. Typically this stream is
14678 imported from a C program, allowing an Ada file to operate on an
14681 @node The GNAT Library
14682 @chapter The GNAT Library
14685 The GNAT library contains a number of general and special purpose packages.
14686 It represents functionality that the GNAT developers have found useful, and
14687 which is made available to GNAT users. The packages described here are fully
14688 supported, and upwards compatibility will be maintained in future releases,
14689 so you can use these facilities with the confidence that the same functionality
14690 will be available in future releases.
14692 The chapter here simply gives a brief summary of the facilities available.
14693 The full documentation is found in the spec file for the package. The full
14694 sources of these library packages, including both spec and body, are provided
14695 with all GNAT releases. For example, to find out the full specifications of
14696 the SPITBOL pattern matching capability, including a full tutorial and
14697 extensive examples, look in the @file{g-spipat.ads} file in the library.
14699 For each entry here, the package name (as it would appear in a @code{with}
14700 clause) is given, followed by the name of the corresponding spec file in
14701 parentheses. The packages are children in four hierarchies, @code{Ada},
14702 @code{Interfaces}, @code{System}, and @code{GNAT}, the latter being a
14703 GNAT-specific hierarchy.
14705 Note that an application program should only use packages in one of these
14706 four hierarchies if the package is defined in the Ada Reference Manual,
14707 or is listed in this section of the GNAT Programmers Reference Manual.
14708 All other units should be considered internal implementation units and
14709 should not be directly @code{with}'ed by application code. The use of
14710 a @code{with} statement that references one of these internal implementation
14711 units makes an application potentially dependent on changes in versions
14712 of GNAT, and will generate a warning message.
14715 * Ada.Characters.Latin_9 (a-chlat9.ads)::
14716 * Ada.Characters.Wide_Latin_1 (a-cwila1.ads)::
14717 * Ada.Characters.Wide_Latin_9 (a-cwila9.ads)::
14718 * Ada.Characters.Wide_Wide_Latin_1 (a-chzla1.ads)::
14719 * Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads)::
14720 * Ada.Containers.Formal_Doubly_Linked_Lists (a-cfdlli.ads)::
14721 * Ada.Containers.Formal_Hashed_Maps (a-cfhama.ads)::
14722 * Ada.Containers.Formal_Hashed_Sets (a-cfhase.ads)::
14723 * Ada.Containers.Formal_Ordered_Maps (a-cforma.ads)::
14724 * Ada.Containers.Formal_Ordered_Sets (a-cforse.ads)::
14725 * Ada.Containers.Formal_Vectors (a-cofove.ads)::
14726 * Ada.Command_Line.Environment (a-colien.ads)::
14727 * Ada.Command_Line.Remove (a-colire.ads)::
14728 * Ada.Command_Line.Response_File (a-clrefi.ads)::
14729 * Ada.Direct_IO.C_Streams (a-diocst.ads)::
14730 * Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads)::
14731 * Ada.Exceptions.Last_Chance_Handler (a-elchha.ads)::
14732 * Ada.Exceptions.Traceback (a-exctra.ads)::
14733 * Ada.Sequential_IO.C_Streams (a-siocst.ads)::
14734 * Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads)::
14735 * Ada.Strings.Unbounded.Text_IO (a-suteio.ads)::
14736 * Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads)::
14737 * Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads)::
14738 * Ada.Text_IO.C_Streams (a-tiocst.ads)::
14739 * Ada.Text_IO.Reset_Standard_Files (a-tirsfi.ads)::
14740 * Ada.Wide_Characters.Unicode (a-wichun.ads)::
14741 * Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads)::
14742 * Ada.Wide_Text_IO.Reset_Standard_Files (a-wrstfi.ads)::
14743 * Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads)::
14744 * Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads)::
14745 * Ada.Wide_Wide_Text_IO.Reset_Standard_Files (a-zrstfi.ads)::
14746 * GNAT.Altivec (g-altive.ads)::
14747 * GNAT.Altivec.Conversions (g-altcon.ads)::
14748 * GNAT.Altivec.Vector_Operations (g-alveop.ads)::
14749 * GNAT.Altivec.Vector_Types (g-alvety.ads)::
14750 * GNAT.Altivec.Vector_Views (g-alvevi.ads)::
14751 * GNAT.Array_Split (g-arrspl.ads)::
14752 * GNAT.AWK (g-awk.ads)::
14753 * GNAT.Bounded_Buffers (g-boubuf.ads)::
14754 * GNAT.Bounded_Mailboxes (g-boumai.ads)::
14755 * GNAT.Bubble_Sort (g-bubsor.ads)::
14756 * GNAT.Bubble_Sort_A (g-busora.ads)::
14757 * GNAT.Bubble_Sort_G (g-busorg.ads)::
14758 * GNAT.Byte_Order_Mark (g-byorma.ads)::
14759 * GNAT.Byte_Swapping (g-bytswa.ads)::
14760 * GNAT.Calendar (g-calend.ads)::
14761 * GNAT.Calendar.Time_IO (g-catiio.ads)::
14762 * GNAT.Case_Util (g-casuti.ads)::
14763 * GNAT.CGI (g-cgi.ads)::
14764 * GNAT.CGI.Cookie (g-cgicoo.ads)::
14765 * GNAT.CGI.Debug (g-cgideb.ads)::
14766 * GNAT.Command_Line (g-comlin.ads)::
14767 * GNAT.Compiler_Version (g-comver.ads)::
14768 * GNAT.Ctrl_C (g-ctrl_c.ads)::
14769 * GNAT.CRC32 (g-crc32.ads)::
14770 * GNAT.Current_Exception (g-curexc.ads)::
14771 * GNAT.Debug_Pools (g-debpoo.ads)::
14772 * GNAT.Debug_Utilities (g-debuti.ads)::
14773 * GNAT.Decode_String (g-decstr.ads)::
14774 * GNAT.Decode_UTF8_String (g-deutst.ads)::
14775 * GNAT.Directory_Operations (g-dirope.ads)::
14776 * GNAT.Directory_Operations.Iteration (g-diopit.ads)::
14777 * GNAT.Dynamic_HTables (g-dynhta.ads)::
14778 * GNAT.Dynamic_Tables (g-dyntab.ads)::
14779 * GNAT.Encode_String (g-encstr.ads)::
14780 * GNAT.Encode_UTF8_String (g-enutst.ads)::
14781 * GNAT.Exception_Actions (g-excact.ads)::
14782 * GNAT.Exception_Traces (g-exctra.ads)::
14783 * GNAT.Exceptions (g-except.ads)::
14784 * GNAT.Expect (g-expect.ads)::
14785 * GNAT.Expect.TTY (g-exptty.ads)::
14786 * GNAT.Float_Control (g-flocon.ads)::
14787 * GNAT.Heap_Sort (g-heasor.ads)::
14788 * GNAT.Heap_Sort_A (g-hesora.ads)::
14789 * GNAT.Heap_Sort_G (g-hesorg.ads)::
14790 * GNAT.HTable (g-htable.ads)::
14791 * GNAT.IO (g-io.ads)::
14792 * GNAT.IO_Aux (g-io_aux.ads)::
14793 * GNAT.Lock_Files (g-locfil.ads)::
14794 * GNAT.MBBS_Discrete_Random (g-mbdira.ads)::
14795 * GNAT.MBBS_Float_Random (g-mbflra.ads)::
14796 * GNAT.MD5 (g-md5.ads)::
14797 * GNAT.Memory_Dump (g-memdum.ads)::
14798 * GNAT.Most_Recent_Exception (g-moreex.ads)::
14799 * GNAT.OS_Lib (g-os_lib.ads)::
14800 * GNAT.Perfect_Hash_Generators (g-pehage.ads)::
14801 * GNAT.Random_Numbers (g-rannum.ads)::
14802 * GNAT.Regexp (g-regexp.ads)::
14803 * GNAT.Registry (g-regist.ads)::
14804 * GNAT.Regpat (g-regpat.ads)::
14805 * GNAT.Secondary_Stack_Info (g-sestin.ads)::
14806 * GNAT.Semaphores (g-semaph.ads)::
14807 * GNAT.Serial_Communications (g-sercom.ads)::
14808 * GNAT.SHA1 (g-sha1.ads)::
14809 * GNAT.SHA224 (g-sha224.ads)::
14810 * GNAT.SHA256 (g-sha256.ads)::
14811 * GNAT.SHA384 (g-sha384.ads)::
14812 * GNAT.SHA512 (g-sha512.ads)::
14813 * GNAT.Signals (g-signal.ads)::
14814 * GNAT.Sockets (g-socket.ads)::
14815 * GNAT.Source_Info (g-souinf.ads)::
14816 * GNAT.Spelling_Checker (g-speche.ads)::
14817 * GNAT.Spelling_Checker_Generic (g-spchge.ads)::
14818 * GNAT.Spitbol.Patterns (g-spipat.ads)::
14819 * GNAT.Spitbol (g-spitbo.ads)::
14820 * GNAT.Spitbol.Table_Boolean (g-sptabo.ads)::
14821 * GNAT.Spitbol.Table_Integer (g-sptain.ads)::
14822 * GNAT.Spitbol.Table_VString (g-sptavs.ads)::
14823 * GNAT.SSE (g-sse.ads)::
14824 * GNAT.SSE.Vector_Types (g-ssvety.ads)::
14825 * GNAT.Strings (g-string.ads)::
14826 * GNAT.String_Split (g-strspl.ads)::
14827 * GNAT.Table (g-table.ads)::
14828 * GNAT.Task_Lock (g-tasloc.ads)::
14829 * GNAT.Threads (g-thread.ads)::
14830 * GNAT.Time_Stamp (g-timsta.ads)::
14831 * GNAT.Traceback (g-traceb.ads)::
14832 * GNAT.Traceback.Symbolic (g-trasym.ads)::
14833 * GNAT.UTF_32 (g-utf_32.ads)::
14834 * GNAT.UTF_32_Spelling_Checker (g-u3spch.ads)::
14835 * GNAT.Wide_Spelling_Checker (g-wispch.ads)::
14836 * GNAT.Wide_String_Split (g-wistsp.ads)::
14837 * GNAT.Wide_Wide_Spelling_Checker (g-zspche.ads)::
14838 * GNAT.Wide_Wide_String_Split (g-zistsp.ads)::
14839 * Interfaces.C.Extensions (i-cexten.ads)::
14840 * Interfaces.C.Streams (i-cstrea.ads)::
14841 * Interfaces.CPP (i-cpp.ads)::
14842 * Interfaces.Packed_Decimal (i-pacdec.ads)::
14843 * Interfaces.VxWorks (i-vxwork.ads)::
14844 * Interfaces.VxWorks.IO (i-vxwoio.ads)::
14845 * System.Address_Image (s-addima.ads)::
14846 * System.Assertions (s-assert.ads)::
14847 * System.Memory (s-memory.ads)::
14848 * System.Partition_Interface (s-parint.ads)::
14849 * System.Pool_Global (s-pooglo.ads)::
14850 * System.Pool_Local (s-pooloc.ads)::
14851 * System.Restrictions (s-restri.ads)::
14852 * System.Rident (s-rident.ads)::
14853 * System.Strings.Stream_Ops (s-ststop.ads)::
14854 * System.Task_Info (s-tasinf.ads)::
14855 * System.Wch_Cnv (s-wchcnv.ads)::
14856 * System.Wch_Con (s-wchcon.ads)::
14859 @node Ada.Characters.Latin_9 (a-chlat9.ads)
14860 @section @code{Ada.Characters.Latin_9} (@file{a-chlat9.ads})
14861 @cindex @code{Ada.Characters.Latin_9} (@file{a-chlat9.ads})
14862 @cindex Latin_9 constants for Character
14865 This child of @code{Ada.Characters}
14866 provides a set of definitions corresponding to those in the
14867 RM-defined package @code{Ada.Characters.Latin_1} but with the
14868 few modifications required for @code{Latin-9}
14869 The provision of such a package
14870 is specifically authorized by the Ada Reference Manual
14873 @node Ada.Characters.Wide_Latin_1 (a-cwila1.ads)
14874 @section @code{Ada.Characters.Wide_Latin_1} (@file{a-cwila1.ads})
14875 @cindex @code{Ada.Characters.Wide_Latin_1} (@file{a-cwila1.ads})
14876 @cindex Latin_1 constants for Wide_Character
14879 This child of @code{Ada.Characters}
14880 provides a set of definitions corresponding to those in the
14881 RM-defined package @code{Ada.Characters.Latin_1} but with the
14882 types of the constants being @code{Wide_Character}
14883 instead of @code{Character}. The provision of such a package
14884 is specifically authorized by the Ada Reference Manual
14887 @node Ada.Characters.Wide_Latin_9 (a-cwila9.ads)
14888 @section @code{Ada.Characters.Wide_Latin_9} (@file{a-cwila1.ads})
14889 @cindex @code{Ada.Characters.Wide_Latin_9} (@file{a-cwila1.ads})
14890 @cindex Latin_9 constants for Wide_Character
14893 This child of @code{Ada.Characters}
14894 provides a set of definitions corresponding to those in the
14895 GNAT defined package @code{Ada.Characters.Latin_9} but with the
14896 types of the constants being @code{Wide_Character}
14897 instead of @code{Character}. The provision of such a package
14898 is specifically authorized by the Ada Reference Manual
14901 @node Ada.Characters.Wide_Wide_Latin_1 (a-chzla1.ads)
14902 @section @code{Ada.Characters.Wide_Wide_Latin_1} (@file{a-chzla1.ads})
14903 @cindex @code{Ada.Characters.Wide_Wide_Latin_1} (@file{a-chzla1.ads})
14904 @cindex Latin_1 constants for Wide_Wide_Character
14907 This child of @code{Ada.Characters}
14908 provides a set of definitions corresponding to those in the
14909 RM-defined package @code{Ada.Characters.Latin_1} but with the
14910 types of the constants being @code{Wide_Wide_Character}
14911 instead of @code{Character}. The provision of such a package
14912 is specifically authorized by the Ada Reference Manual
14915 @node Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads)
14916 @section @code{Ada.Characters.Wide_Wide_Latin_9} (@file{a-chzla9.ads})
14917 @cindex @code{Ada.Characters.Wide_Wide_Latin_9} (@file{a-chzla9.ads})
14918 @cindex Latin_9 constants for Wide_Wide_Character
14921 This child of @code{Ada.Characters}
14922 provides a set of definitions corresponding to those in the
14923 GNAT defined package @code{Ada.Characters.Latin_9} but with the
14924 types of the constants being @code{Wide_Wide_Character}
14925 instead of @code{Character}. The provision of such a package
14926 is specifically authorized by the Ada Reference Manual
14929 @node Ada.Containers.Formal_Doubly_Linked_Lists (a-cfdlli.ads)
14930 @section @code{Ada.Containers.Formal_Doubly_Linked_Lists} (@file{a-cfdlli.ads})
14931 @cindex @code{Ada.Containers.Formal_Doubly_Linked_Lists} (@file{a-cfdlli.ads})
14932 @cindex Formal container for doubly linked lists
14935 This child of @code{Ada.Containers} defines a modified version of the Ada 2005
14936 container for doubly linked lists, meant to facilitate formal verification of
14937 code using such containers.
14939 @node Ada.Containers.Formal_Hashed_Maps (a-cfhama.ads)
14940 @section @code{Ada.Containers.Formal_Hashed_Maps} (@file{a-cfhama.ads})
14941 @cindex @code{Ada.Containers.Formal_Hashed_Maps} (@file{a-cfhama.ads})
14942 @cindex Formal container for hashed maps
14945 This child of @code{Ada.Containers} defines a modified version of the Ada 2005
14946 container for hashed maps, meant to facilitate formal verification of
14947 code using such containers.
14949 @node Ada.Containers.Formal_Hashed_Sets (a-cfhase.ads)
14950 @section @code{Ada.Containers.Formal_Hashed_Sets} (@file{a-cfhase.ads})
14951 @cindex @code{Ada.Containers.Formal_Hashed_Sets} (@file{a-cfhase.ads})
14952 @cindex Formal container for hashed sets
14955 This child of @code{Ada.Containers} defines a modified version of the Ada 2005
14956 container for hashed sets, meant to facilitate formal verification of
14957 code using such containers.
14959 @node Ada.Containers.Formal_Ordered_Maps (a-cforma.ads)
14960 @section @code{Ada.Containers.Formal_Ordered_Maps} (@file{a-cforma.ads})
14961 @cindex @code{Ada.Containers.Formal_Ordered_Maps} (@file{a-cforma.ads})
14962 @cindex Formal container for ordered maps
14965 This child of @code{Ada.Containers} defines a modified version of the Ada 2005
14966 container for ordered maps, meant to facilitate formal verification of
14967 code using such containers.
14969 @node Ada.Containers.Formal_Ordered_Sets (a-cforse.ads)
14970 @section @code{Ada.Containers.Formal_Ordered_Sets} (@file{a-cforse.ads})
14971 @cindex @code{Ada.Containers.Formal_Ordered_Sets} (@file{a-cforse.ads})
14972 @cindex Formal container for ordered sets
14975 This child of @code{Ada.Containers} defines a modified version of the Ada 2005
14976 container for ordered sets, meant to facilitate formal verification of
14977 code using such containers.
14979 @node Ada.Containers.Formal_Vectors (a-cofove.ads)
14980 @section @code{Ada.Containers.Formal_Vectors} (@file{a-cofove.ads})
14981 @cindex @code{Ada.Containers.Formal_Vectors} (@file{a-cofove.ads})
14982 @cindex Formal container for vectors
14985 This child of @code{Ada.Containers} defines a modified version of the Ada 2005
14986 container for vectors, meant to facilitate formal verification of
14987 code using such containers.
14989 @node Ada.Command_Line.Environment (a-colien.ads)
14990 @section @code{Ada.Command_Line.Environment} (@file{a-colien.ads})
14991 @cindex @code{Ada.Command_Line.Environment} (@file{a-colien.ads})
14992 @cindex Environment entries
14995 This child of @code{Ada.Command_Line}
14996 provides a mechanism for obtaining environment values on systems
14997 where this concept makes sense.
14999 @node Ada.Command_Line.Remove (a-colire.ads)
15000 @section @code{Ada.Command_Line.Remove} (@file{a-colire.ads})
15001 @cindex @code{Ada.Command_Line.Remove} (@file{a-colire.ads})
15002 @cindex Removing command line arguments
15003 @cindex Command line, argument removal
15006 This child of @code{Ada.Command_Line}
15007 provides a mechanism for logically removing
15008 arguments from the argument list. Once removed, an argument is not visible
15009 to further calls on the subprograms in @code{Ada.Command_Line} will not
15010 see the removed argument.
15012 @node Ada.Command_Line.Response_File (a-clrefi.ads)
15013 @section @code{Ada.Command_Line.Response_File} (@file{a-clrefi.ads})
15014 @cindex @code{Ada.Command_Line.Response_File} (@file{a-clrefi.ads})
15015 @cindex Response file for command line
15016 @cindex Command line, response file
15017 @cindex Command line, handling long command lines
15020 This child of @code{Ada.Command_Line} provides a mechanism facilities for
15021 getting command line arguments from a text file, called a "response file".
15022 Using a response file allow passing a set of arguments to an executable longer
15023 than the maximum allowed by the system on the command line.
15025 @node Ada.Direct_IO.C_Streams (a-diocst.ads)
15026 @section @code{Ada.Direct_IO.C_Streams} (@file{a-diocst.ads})
15027 @cindex @code{Ada.Direct_IO.C_Streams} (@file{a-diocst.ads})
15028 @cindex C Streams, Interfacing with Direct_IO
15031 This package provides subprograms that allow interfacing between
15032 C streams and @code{Direct_IO}. The stream identifier can be
15033 extracted from a file opened on the Ada side, and an Ada file
15034 can be constructed from a stream opened on the C side.
15036 @node Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads)
15037 @section @code{Ada.Exceptions.Is_Null_Occurrence} (@file{a-einuoc.ads})
15038 @cindex @code{Ada.Exceptions.Is_Null_Occurrence} (@file{a-einuoc.ads})
15039 @cindex Null_Occurrence, testing for
15042 This child subprogram provides a way of testing for the null
15043 exception occurrence (@code{Null_Occurrence}) without raising
15046 @node Ada.Exceptions.Last_Chance_Handler (a-elchha.ads)
15047 @section @code{Ada.Exceptions.Last_Chance_Handler} (@file{a-elchha.ads})
15048 @cindex @code{Ada.Exceptions.Last_Chance_Handler} (@file{a-elchha.ads})
15049 @cindex Null_Occurrence, testing for
15052 This child subprogram is used for handling otherwise unhandled
15053 exceptions (hence the name last chance), and perform clean ups before
15054 terminating the program. Note that this subprogram never returns.
15056 @node Ada.Exceptions.Traceback (a-exctra.ads)
15057 @section @code{Ada.Exceptions.Traceback} (@file{a-exctra.ads})
15058 @cindex @code{Ada.Exceptions.Traceback} (@file{a-exctra.ads})
15059 @cindex Traceback for Exception Occurrence
15062 This child package provides the subprogram (@code{Tracebacks}) to
15063 give a traceback array of addresses based on an exception
15066 @node Ada.Sequential_IO.C_Streams (a-siocst.ads)
15067 @section @code{Ada.Sequential_IO.C_Streams} (@file{a-siocst.ads})
15068 @cindex @code{Ada.Sequential_IO.C_Streams} (@file{a-siocst.ads})
15069 @cindex C Streams, Interfacing with Sequential_IO
15072 This package provides subprograms that allow interfacing between
15073 C streams and @code{Sequential_IO}. The stream identifier can be
15074 extracted from a file opened on the Ada side, and an Ada file
15075 can be constructed from a stream opened on the C side.
15077 @node Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads)
15078 @section @code{Ada.Streams.Stream_IO.C_Streams} (@file{a-ssicst.ads})
15079 @cindex @code{Ada.Streams.Stream_IO.C_Streams} (@file{a-ssicst.ads})
15080 @cindex C Streams, Interfacing with Stream_IO
15083 This package provides subprograms that allow interfacing between
15084 C streams and @code{Stream_IO}. The stream identifier can be
15085 extracted from a file opened on the Ada side, and an Ada file
15086 can be constructed from a stream opened on the C side.
15088 @node Ada.Strings.Unbounded.Text_IO (a-suteio.ads)
15089 @section @code{Ada.Strings.Unbounded.Text_IO} (@file{a-suteio.ads})
15090 @cindex @code{Ada.Strings.Unbounded.Text_IO} (@file{a-suteio.ads})
15091 @cindex @code{Unbounded_String}, IO support
15092 @cindex @code{Text_IO}, extensions for unbounded strings
15095 This package provides subprograms for Text_IO for unbounded
15096 strings, avoiding the necessity for an intermediate operation
15097 with ordinary strings.
15099 @node Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads)
15100 @section @code{Ada.Strings.Wide_Unbounded.Wide_Text_IO} (@file{a-swuwti.ads})
15101 @cindex @code{Ada.Strings.Wide_Unbounded.Wide_Text_IO} (@file{a-swuwti.ads})
15102 @cindex @code{Unbounded_Wide_String}, IO support
15103 @cindex @code{Text_IO}, extensions for unbounded wide strings
15106 This package provides subprograms for Text_IO for unbounded
15107 wide strings, avoiding the necessity for an intermediate operation
15108 with ordinary wide strings.
15110 @node Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads)
15111 @section @code{Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO} (@file{a-szuzti.ads})
15112 @cindex @code{Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO} (@file{a-szuzti.ads})
15113 @cindex @code{Unbounded_Wide_Wide_String}, IO support
15114 @cindex @code{Text_IO}, extensions for unbounded wide wide strings
15117 This package provides subprograms for Text_IO for unbounded
15118 wide wide strings, avoiding the necessity for an intermediate operation
15119 with ordinary wide wide strings.
15121 @node Ada.Text_IO.C_Streams (a-tiocst.ads)
15122 @section @code{Ada.Text_IO.C_Streams} (@file{a-tiocst.ads})
15123 @cindex @code{Ada.Text_IO.C_Streams} (@file{a-tiocst.ads})
15124 @cindex C Streams, Interfacing with @code{Text_IO}
15127 This package provides subprograms that allow interfacing between
15128 C streams and @code{Text_IO}. The stream identifier can be
15129 extracted from a file opened on the Ada side, and an Ada file
15130 can be constructed from a stream opened on the C side.
15132 @node Ada.Text_IO.Reset_Standard_Files (a-tirsfi.ads)
15133 @section @code{Ada.Text_IO.Reset_Standard_Files} (@file{a-tirsfi.ads})
15134 @cindex @code{Ada.Text_IO.Reset_Standard_Files} (@file{a-tirsfi.ads})
15135 @cindex @code{Text_IO} resetting standard files
15138 This procedure is used to reset the status of the standard files used
15139 by Ada.Text_IO. This is useful in a situation (such as a restart in an
15140 embedded application) where the status of the files may change during
15141 execution (for example a standard input file may be redefined to be
15144 @node Ada.Wide_Characters.Unicode (a-wichun.ads)
15145 @section @code{Ada.Wide_Characters.Unicode} (@file{a-wichun.ads})
15146 @cindex @code{Ada.Wide_Characters.Unicode} (@file{a-wichun.ads})
15147 @cindex Unicode categorization, Wide_Character
15150 This package provides subprograms that allow categorization of
15151 Wide_Character values according to Unicode categories.
15153 @node Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads)
15154 @section @code{Ada.Wide_Text_IO.C_Streams} (@file{a-wtcstr.ads})
15155 @cindex @code{Ada.Wide_Text_IO.C_Streams} (@file{a-wtcstr.ads})
15156 @cindex C Streams, Interfacing with @code{Wide_Text_IO}
15159 This package provides subprograms that allow interfacing between
15160 C streams and @code{Wide_Text_IO}. The stream identifier can be
15161 extracted from a file opened on the Ada side, and an Ada file
15162 can be constructed from a stream opened on the C side.
15164 @node Ada.Wide_Text_IO.Reset_Standard_Files (a-wrstfi.ads)
15165 @section @code{Ada.Wide_Text_IO.Reset_Standard_Files} (@file{a-wrstfi.ads})
15166 @cindex @code{Ada.Wide_Text_IO.Reset_Standard_Files} (@file{a-wrstfi.ads})
15167 @cindex @code{Wide_Text_IO} resetting standard files
15170 This procedure is used to reset the status of the standard files used
15171 by Ada.Wide_Text_IO. This is useful in a situation (such as a restart in an
15172 embedded application) where the status of the files may change during
15173 execution (for example a standard input file may be redefined to be
15176 @node Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads)
15177 @section @code{Ada.Wide_Wide_Characters.Unicode} (@file{a-zchuni.ads})
15178 @cindex @code{Ada.Wide_Wide_Characters.Unicode} (@file{a-zchuni.ads})
15179 @cindex Unicode categorization, Wide_Wide_Character
15182 This package provides subprograms that allow categorization of
15183 Wide_Wide_Character values according to Unicode categories.
15185 @node Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads)
15186 @section @code{Ada.Wide_Wide_Text_IO.C_Streams} (@file{a-ztcstr.ads})
15187 @cindex @code{Ada.Wide_Wide_Text_IO.C_Streams} (@file{a-ztcstr.ads})
15188 @cindex C Streams, Interfacing with @code{Wide_Wide_Text_IO}
15191 This package provides subprograms that allow interfacing between
15192 C streams and @code{Wide_Wide_Text_IO}. The stream identifier can be
15193 extracted from a file opened on the Ada side, and an Ada file
15194 can be constructed from a stream opened on the C side.
15196 @node Ada.Wide_Wide_Text_IO.Reset_Standard_Files (a-zrstfi.ads)
15197 @section @code{Ada.Wide_Wide_Text_IO.Reset_Standard_Files} (@file{a-zrstfi.ads})
15198 @cindex @code{Ada.Wide_Wide_Text_IO.Reset_Standard_Files} (@file{a-zrstfi.ads})
15199 @cindex @code{Wide_Wide_Text_IO} resetting standard files
15202 This procedure is used to reset the status of the standard files used
15203 by Ada.Wide_Wide_Text_IO. This is useful in a situation (such as a
15204 restart in an embedded application) where the status of the files may
15205 change during execution (for example a standard input file may be
15206 redefined to be interactive).
15208 @node GNAT.Altivec (g-altive.ads)
15209 @section @code{GNAT.Altivec} (@file{g-altive.ads})
15210 @cindex @code{GNAT.Altivec} (@file{g-altive.ads})
15214 This is the root package of the GNAT AltiVec binding. It provides
15215 definitions of constants and types common to all the versions of the
15218 @node GNAT.Altivec.Conversions (g-altcon.ads)
15219 @section @code{GNAT.Altivec.Conversions} (@file{g-altcon.ads})
15220 @cindex @code{GNAT.Altivec.Conversions} (@file{g-altcon.ads})
15224 This package provides the Vector/View conversion routines.
15226 @node GNAT.Altivec.Vector_Operations (g-alveop.ads)
15227 @section @code{GNAT.Altivec.Vector_Operations} (@file{g-alveop.ads})
15228 @cindex @code{GNAT.Altivec.Vector_Operations} (@file{g-alveop.ads})
15232 This package exposes the Ada interface to the AltiVec operations on
15233 vector objects. A soft emulation is included by default in the GNAT
15234 library. The hard binding is provided as a separate package. This unit
15235 is common to both bindings.
15237 @node GNAT.Altivec.Vector_Types (g-alvety.ads)
15238 @section @code{GNAT.Altivec.Vector_Types} (@file{g-alvety.ads})
15239 @cindex @code{GNAT.Altivec.Vector_Types} (@file{g-alvety.ads})
15243 This package exposes the various vector types part of the Ada binding
15244 to AltiVec facilities.
15246 @node GNAT.Altivec.Vector_Views (g-alvevi.ads)
15247 @section @code{GNAT.Altivec.Vector_Views} (@file{g-alvevi.ads})
15248 @cindex @code{GNAT.Altivec.Vector_Views} (@file{g-alvevi.ads})
15252 This package provides public 'View' data types from/to which private
15253 vector representations can be converted via
15254 GNAT.Altivec.Conversions. This allows convenient access to individual
15255 vector elements and provides a simple way to initialize vector
15258 @node GNAT.Array_Split (g-arrspl.ads)
15259 @section @code{GNAT.Array_Split} (@file{g-arrspl.ads})
15260 @cindex @code{GNAT.Array_Split} (@file{g-arrspl.ads})
15261 @cindex Array splitter
15264 Useful array-manipulation routines: given a set of separators, split
15265 an array wherever the separators appear, and provide direct access
15266 to the resulting slices.
15268 @node GNAT.AWK (g-awk.ads)
15269 @section @code{GNAT.AWK} (@file{g-awk.ads})
15270 @cindex @code{GNAT.AWK} (@file{g-awk.ads})
15275 Provides AWK-like parsing functions, with an easy interface for parsing one
15276 or more files containing formatted data. The file is viewed as a database
15277 where each record is a line and a field is a data element in this line.
15279 @node GNAT.Bounded_Buffers (g-boubuf.ads)
15280 @section @code{GNAT.Bounded_Buffers} (@file{g-boubuf.ads})
15281 @cindex @code{GNAT.Bounded_Buffers} (@file{g-boubuf.ads})
15283 @cindex Bounded Buffers
15286 Provides a concurrent generic bounded buffer abstraction. Instances are
15287 useful directly or as parts of the implementations of other abstractions,
15290 @node GNAT.Bounded_Mailboxes (g-boumai.ads)
15291 @section @code{GNAT.Bounded_Mailboxes} (@file{g-boumai.ads})
15292 @cindex @code{GNAT.Bounded_Mailboxes} (@file{g-boumai.ads})
15297 Provides a thread-safe asynchronous intertask mailbox communication facility.
15299 @node GNAT.Bubble_Sort (g-bubsor.ads)
15300 @section @code{GNAT.Bubble_Sort} (@file{g-bubsor.ads})
15301 @cindex @code{GNAT.Bubble_Sort} (@file{g-bubsor.ads})
15303 @cindex Bubble sort
15306 Provides a general implementation of bubble sort usable for sorting arbitrary
15307 data items. Exchange and comparison procedures are provided by passing
15308 access-to-procedure values.
15310 @node GNAT.Bubble_Sort_A (g-busora.ads)
15311 @section @code{GNAT.Bubble_Sort_A} (@file{g-busora.ads})
15312 @cindex @code{GNAT.Bubble_Sort_A} (@file{g-busora.ads})
15314 @cindex Bubble sort
15317 Provides a general implementation of bubble sort usable for sorting arbitrary
15318 data items. Move and comparison procedures are provided by passing
15319 access-to-procedure values. This is an older version, retained for
15320 compatibility. Usually @code{GNAT.Bubble_Sort} will be preferable.
15322 @node GNAT.Bubble_Sort_G (g-busorg.ads)
15323 @section @code{GNAT.Bubble_Sort_G} (@file{g-busorg.ads})
15324 @cindex @code{GNAT.Bubble_Sort_G} (@file{g-busorg.ads})
15326 @cindex Bubble sort
15329 Similar to @code{Bubble_Sort_A} except that the move and sorting procedures
15330 are provided as generic parameters, this improves efficiency, especially
15331 if the procedures can be inlined, at the expense of duplicating code for
15332 multiple instantiations.
15334 @node GNAT.Byte_Order_Mark (g-byorma.ads)
15335 @section @code{GNAT.Byte_Order_Mark} (@file{g-byorma.ads})
15336 @cindex @code{GNAT.Byte_Order_Mark} (@file{g-byorma.ads})
15337 @cindex UTF-8 representation
15338 @cindex Wide characte representations
15341 Provides a routine which given a string, reads the start of the string to
15342 see whether it is one of the standard byte order marks (BOM's) which signal
15343 the encoding of the string. The routine includes detection of special XML
15344 sequences for various UCS input formats.
15346 @node GNAT.Byte_Swapping (g-bytswa.ads)
15347 @section @code{GNAT.Byte_Swapping} (@file{g-bytswa.ads})
15348 @cindex @code{GNAT.Byte_Swapping} (@file{g-bytswa.ads})
15349 @cindex Byte swapping
15353 General routines for swapping the bytes in 2-, 4-, and 8-byte quantities.
15354 Machine-specific implementations are available in some cases.
15356 @node GNAT.Calendar (g-calend.ads)
15357 @section @code{GNAT.Calendar} (@file{g-calend.ads})
15358 @cindex @code{GNAT.Calendar} (@file{g-calend.ads})
15359 @cindex @code{Calendar}
15362 Extends the facilities provided by @code{Ada.Calendar} to include handling
15363 of days of the week, an extended @code{Split} and @code{Time_Of} capability.
15364 Also provides conversion of @code{Ada.Calendar.Time} values to and from the
15365 C @code{timeval} format.
15367 @node GNAT.Calendar.Time_IO (g-catiio.ads)
15368 @section @code{GNAT.Calendar.Time_IO} (@file{g-catiio.ads})
15369 @cindex @code{Calendar}
15371 @cindex @code{GNAT.Calendar.Time_IO} (@file{g-catiio.ads})
15373 @node GNAT.CRC32 (g-crc32.ads)
15374 @section @code{GNAT.CRC32} (@file{g-crc32.ads})
15375 @cindex @code{GNAT.CRC32} (@file{g-crc32.ads})
15377 @cindex Cyclic Redundancy Check
15380 This package implements the CRC-32 algorithm. For a full description
15381 of this algorithm see
15382 ``Computation of Cyclic Redundancy Checks via Table Look-Up'',
15383 @cite{Communications of the ACM}, Vol.@: 31 No.@: 8, pp.@: 1008-1013,
15384 Aug.@: 1988. Sarwate, D.V@.
15386 @node GNAT.Case_Util (g-casuti.ads)
15387 @section @code{GNAT.Case_Util} (@file{g-casuti.ads})
15388 @cindex @code{GNAT.Case_Util} (@file{g-casuti.ads})
15389 @cindex Casing utilities
15390 @cindex Character handling (@code{GNAT.Case_Util})
15393 A set of simple routines for handling upper and lower casing of strings
15394 without the overhead of the full casing tables
15395 in @code{Ada.Characters.Handling}.
15397 @node GNAT.CGI (g-cgi.ads)
15398 @section @code{GNAT.CGI} (@file{g-cgi.ads})
15399 @cindex @code{GNAT.CGI} (@file{g-cgi.ads})
15400 @cindex CGI (Common Gateway Interface)
15403 This is a package for interfacing a GNAT program with a Web server via the
15404 Common Gateway Interface (CGI)@. Basically this package parses the CGI
15405 parameters, which are a set of key/value pairs sent by the Web server. It
15406 builds a table whose index is the key and provides some services to deal
15409 @node GNAT.CGI.Cookie (g-cgicoo.ads)
15410 @section @code{GNAT.CGI.Cookie} (@file{g-cgicoo.ads})
15411 @cindex @code{GNAT.CGI.Cookie} (@file{g-cgicoo.ads})
15412 @cindex CGI (Common Gateway Interface) cookie support
15413 @cindex Cookie support in CGI
15416 This is a package to interface a GNAT program with a Web server via the
15417 Common Gateway Interface (CGI). It exports services to deal with Web
15418 cookies (piece of information kept in the Web client software).
15420 @node GNAT.CGI.Debug (g-cgideb.ads)
15421 @section @code{GNAT.CGI.Debug} (@file{g-cgideb.ads})
15422 @cindex @code{GNAT.CGI.Debug} (@file{g-cgideb.ads})
15423 @cindex CGI (Common Gateway Interface) debugging
15426 This is a package to help debugging CGI (Common Gateway Interface)
15427 programs written in Ada.
15429 @node GNAT.Command_Line (g-comlin.ads)
15430 @section @code{GNAT.Command_Line} (@file{g-comlin.ads})
15431 @cindex @code{GNAT.Command_Line} (@file{g-comlin.ads})
15432 @cindex Command line
15435 Provides a high level interface to @code{Ada.Command_Line} facilities,
15436 including the ability to scan for named switches with optional parameters
15437 and expand file names using wild card notations.
15439 @node GNAT.Compiler_Version (g-comver.ads)
15440 @section @code{GNAT.Compiler_Version} (@file{g-comver.ads})
15441 @cindex @code{GNAT.Compiler_Version} (@file{g-comver.ads})
15442 @cindex Compiler Version
15443 @cindex Version, of compiler
15446 Provides a routine for obtaining the version of the compiler used to
15447 compile the program. More accurately this is the version of the binder
15448 used to bind the program (this will normally be the same as the version
15449 of the compiler if a consistent tool set is used to compile all units
15452 @node GNAT.Ctrl_C (g-ctrl_c.ads)
15453 @section @code{GNAT.Ctrl_C} (@file{g-ctrl_c.ads})
15454 @cindex @code{GNAT.Ctrl_C} (@file{g-ctrl_c.ads})
15458 Provides a simple interface to handle Ctrl-C keyboard events.
15460 @node GNAT.Current_Exception (g-curexc.ads)
15461 @section @code{GNAT.Current_Exception} (@file{g-curexc.ads})
15462 @cindex @code{GNAT.Current_Exception} (@file{g-curexc.ads})
15463 @cindex Current exception
15464 @cindex Exception retrieval
15467 Provides access to information on the current exception that has been raised
15468 without the need for using the Ada 95 / Ada 2005 exception choice parameter
15469 specification syntax.
15470 This is particularly useful in simulating typical facilities for
15471 obtaining information about exceptions provided by Ada 83 compilers.
15473 @node GNAT.Debug_Pools (g-debpoo.ads)
15474 @section @code{GNAT.Debug_Pools} (@file{g-debpoo.ads})
15475 @cindex @code{GNAT.Debug_Pools} (@file{g-debpoo.ads})
15477 @cindex Debug pools
15478 @cindex Memory corruption debugging
15481 Provide a debugging storage pools that helps tracking memory corruption
15482 problems. @xref{The GNAT Debug Pool Facility,,, gnat_ugn,
15483 @value{EDITION} User's Guide}.
15485 @node GNAT.Debug_Utilities (g-debuti.ads)
15486 @section @code{GNAT.Debug_Utilities} (@file{g-debuti.ads})
15487 @cindex @code{GNAT.Debug_Utilities} (@file{g-debuti.ads})
15491 Provides a few useful utilities for debugging purposes, including conversion
15492 to and from string images of address values. Supports both C and Ada formats
15493 for hexadecimal literals.
15495 @node GNAT.Decode_String (g-decstr.ads)
15496 @section @code{GNAT.Decode_String} (@file{g-decstr.ads})
15497 @cindex @code{GNAT.Decode_String} (@file{g-decstr.ads})
15498 @cindex Decoding strings
15499 @cindex String decoding
15500 @cindex Wide character encoding
15505 A generic package providing routines for decoding wide character and wide wide
15506 character strings encoded as sequences of 8-bit characters using a specified
15507 encoding method. Includes validation routines, and also routines for stepping
15508 to next or previous encoded character in an encoded string.
15509 Useful in conjunction with Unicode character coding. Note there is a
15510 preinstantiation for UTF-8. See next entry.
15512 @node GNAT.Decode_UTF8_String (g-deutst.ads)
15513 @section @code{GNAT.Decode_UTF8_String} (@file{g-deutst.ads})
15514 @cindex @code{GNAT.Decode_UTF8_String} (@file{g-deutst.ads})
15515 @cindex Decoding strings
15516 @cindex Decoding UTF-8 strings
15517 @cindex UTF-8 string decoding
15518 @cindex Wide character decoding
15523 A preinstantiation of GNAT.Decode_Strings for UTF-8 encoding.
15525 @node GNAT.Directory_Operations (g-dirope.ads)
15526 @section @code{GNAT.Directory_Operations} (@file{g-dirope.ads})
15527 @cindex @code{GNAT.Directory_Operations} (@file{g-dirope.ads})
15528 @cindex Directory operations
15531 Provides a set of routines for manipulating directories, including changing
15532 the current directory, making new directories, and scanning the files in a
15535 @node GNAT.Directory_Operations.Iteration (g-diopit.ads)
15536 @section @code{GNAT.Directory_Operations.Iteration} (@file{g-diopit.ads})
15537 @cindex @code{GNAT.Directory_Operations.Iteration} (@file{g-diopit.ads})
15538 @cindex Directory operations iteration
15541 A child unit of GNAT.Directory_Operations providing additional operations
15542 for iterating through directories.
15544 @node GNAT.Dynamic_HTables (g-dynhta.ads)
15545 @section @code{GNAT.Dynamic_HTables} (@file{g-dynhta.ads})
15546 @cindex @code{GNAT.Dynamic_HTables} (@file{g-dynhta.ads})
15547 @cindex Hash tables
15550 A generic implementation of hash tables that can be used to hash arbitrary
15551 data. Provided in two forms, a simple form with built in hash functions,
15552 and a more complex form in which the hash function is supplied.
15555 This package provides a facility similar to that of @code{GNAT.HTable},
15556 except that this package declares a type that can be used to define
15557 dynamic instances of the hash table, while an instantiation of
15558 @code{GNAT.HTable} creates a single instance of the hash table.
15560 @node GNAT.Dynamic_Tables (g-dyntab.ads)
15561 @section @code{GNAT.Dynamic_Tables} (@file{g-dyntab.ads})
15562 @cindex @code{GNAT.Dynamic_Tables} (@file{g-dyntab.ads})
15563 @cindex Table implementation
15564 @cindex Arrays, extendable
15567 A generic package providing a single dimension array abstraction where the
15568 length of the array can be dynamically modified.
15571 This package provides a facility similar to that of @code{GNAT.Table},
15572 except that this package declares a type that can be used to define
15573 dynamic instances of the table, while an instantiation of
15574 @code{GNAT.Table} creates a single instance of the table type.
15576 @node GNAT.Encode_String (g-encstr.ads)
15577 @section @code{GNAT.Encode_String} (@file{g-encstr.ads})
15578 @cindex @code{GNAT.Encode_String} (@file{g-encstr.ads})
15579 @cindex Encoding strings
15580 @cindex String encoding
15581 @cindex Wide character encoding
15586 A generic package providing routines for encoding wide character and wide
15587 wide character strings as sequences of 8-bit characters using a specified
15588 encoding method. Useful in conjunction with Unicode character coding.
15589 Note there is a preinstantiation for UTF-8. See next entry.
15591 @node GNAT.Encode_UTF8_String (g-enutst.ads)
15592 @section @code{GNAT.Encode_UTF8_String} (@file{g-enutst.ads})
15593 @cindex @code{GNAT.Encode_UTF8_String} (@file{g-enutst.ads})
15594 @cindex Encoding strings
15595 @cindex Encoding UTF-8 strings
15596 @cindex UTF-8 string encoding
15597 @cindex Wide character encoding
15602 A preinstantiation of GNAT.Encode_Strings for UTF-8 encoding.
15604 @node GNAT.Exception_Actions (g-excact.ads)
15605 @section @code{GNAT.Exception_Actions} (@file{g-excact.ads})
15606 @cindex @code{GNAT.Exception_Actions} (@file{g-excact.ads})
15607 @cindex Exception actions
15610 Provides callbacks when an exception is raised. Callbacks can be registered
15611 for specific exceptions, or when any exception is raised. This
15612 can be used for instance to force a core dump to ease debugging.
15614 @node GNAT.Exception_Traces (g-exctra.ads)
15615 @section @code{GNAT.Exception_Traces} (@file{g-exctra.ads})
15616 @cindex @code{GNAT.Exception_Traces} (@file{g-exctra.ads})
15617 @cindex Exception traces
15621 Provides an interface allowing to control automatic output upon exception
15624 @node GNAT.Exceptions (g-except.ads)
15625 @section @code{GNAT.Exceptions} (@file{g-expect.ads})
15626 @cindex @code{GNAT.Exceptions} (@file{g-expect.ads})
15627 @cindex Exceptions, Pure
15628 @cindex Pure packages, exceptions
15631 Normally it is not possible to raise an exception with
15632 a message from a subprogram in a pure package, since the
15633 necessary types and subprograms are in @code{Ada.Exceptions}
15634 which is not a pure unit. @code{GNAT.Exceptions} provides a
15635 facility for getting around this limitation for a few
15636 predefined exceptions, and for example allow raising
15637 @code{Constraint_Error} with a message from a pure subprogram.
15639 @node GNAT.Expect (g-expect.ads)
15640 @section @code{GNAT.Expect} (@file{g-expect.ads})
15641 @cindex @code{GNAT.Expect} (@file{g-expect.ads})
15644 Provides a set of subprograms similar to what is available
15645 with the standard Tcl Expect tool.
15646 It allows you to easily spawn and communicate with an external process.
15647 You can send commands or inputs to the process, and compare the output
15648 with some expected regular expression. Currently @code{GNAT.Expect}
15649 is implemented on all native GNAT ports except for OpenVMS@.
15650 It is not implemented for cross ports, and in particular is not
15651 implemented for VxWorks or LynxOS@.
15653 @node GNAT.Expect.TTY (g-exptty.ads)
15654 @section @code{GNAT.Expect.TTY} (@file{g-exptty.ads})
15655 @cindex @code{GNAT.Expect.TTY} (@file{g-exptty.ads})
15658 As GNAT.Expect but using pseudo-terminal.
15659 Currently @code{GNAT.Expect.TTY} is implemented on all native GNAT
15660 ports except for OpenVMS@. It is not implemented for cross ports, and
15661 in particular is not implemented for VxWorks or LynxOS@.
15663 @node GNAT.Float_Control (g-flocon.ads)
15664 @section @code{GNAT.Float_Control} (@file{g-flocon.ads})
15665 @cindex @code{GNAT.Float_Control} (@file{g-flocon.ads})
15666 @cindex Floating-Point Processor
15669 Provides an interface for resetting the floating-point processor into the
15670 mode required for correct semantic operation in Ada. Some third party
15671 library calls may cause this mode to be modified, and the Reset procedure
15672 in this package can be used to reestablish the required mode.
15674 @node GNAT.Heap_Sort (g-heasor.ads)
15675 @section @code{GNAT.Heap_Sort} (@file{g-heasor.ads})
15676 @cindex @code{GNAT.Heap_Sort} (@file{g-heasor.ads})
15680 Provides a general implementation of heap sort usable for sorting arbitrary
15681 data items. Exchange and comparison procedures are provided by passing
15682 access-to-procedure values. The algorithm used is a modified heap sort
15683 that performs approximately N*log(N) comparisons in the worst case.
15685 @node GNAT.Heap_Sort_A (g-hesora.ads)
15686 @section @code{GNAT.Heap_Sort_A} (@file{g-hesora.ads})
15687 @cindex @code{GNAT.Heap_Sort_A} (@file{g-hesora.ads})
15691 Provides a general implementation of heap sort usable for sorting arbitrary
15692 data items. Move and comparison procedures are provided by passing
15693 access-to-procedure values. The algorithm used is a modified heap sort
15694 that performs approximately N*log(N) comparisons in the worst case.
15695 This differs from @code{GNAT.Heap_Sort} in having a less convenient
15696 interface, but may be slightly more efficient.
15698 @node GNAT.Heap_Sort_G (g-hesorg.ads)
15699 @section @code{GNAT.Heap_Sort_G} (@file{g-hesorg.ads})
15700 @cindex @code{GNAT.Heap_Sort_G} (@file{g-hesorg.ads})
15704 Similar to @code{Heap_Sort_A} except that the move and sorting procedures
15705 are provided as generic parameters, this improves efficiency, especially
15706 if the procedures can be inlined, at the expense of duplicating code for
15707 multiple instantiations.
15709 @node GNAT.HTable (g-htable.ads)
15710 @section @code{GNAT.HTable} (@file{g-htable.ads})
15711 @cindex @code{GNAT.HTable} (@file{g-htable.ads})
15712 @cindex Hash tables
15715 A generic implementation of hash tables that can be used to hash arbitrary
15716 data. Provides two approaches, one a simple static approach, and the other
15717 allowing arbitrary dynamic hash tables.
15719 @node GNAT.IO (g-io.ads)
15720 @section @code{GNAT.IO} (@file{g-io.ads})
15721 @cindex @code{GNAT.IO} (@file{g-io.ads})
15723 @cindex Input/Output facilities
15726 A simple preelaborable input-output package that provides a subset of
15727 simple Text_IO functions for reading characters and strings from
15728 Standard_Input, and writing characters, strings and integers to either
15729 Standard_Output or Standard_Error.
15731 @node GNAT.IO_Aux (g-io_aux.ads)
15732 @section @code{GNAT.IO_Aux} (@file{g-io_aux.ads})
15733 @cindex @code{GNAT.IO_Aux} (@file{g-io_aux.ads})
15735 @cindex Input/Output facilities
15737 Provides some auxiliary functions for use with Text_IO, including a test
15738 for whether a file exists, and functions for reading a line of text.
15740 @node GNAT.Lock_Files (g-locfil.ads)
15741 @section @code{GNAT.Lock_Files} (@file{g-locfil.ads})
15742 @cindex @code{GNAT.Lock_Files} (@file{g-locfil.ads})
15743 @cindex File locking
15744 @cindex Locking using files
15747 Provides a general interface for using files as locks. Can be used for
15748 providing program level synchronization.
15750 @node GNAT.MBBS_Discrete_Random (g-mbdira.ads)
15751 @section @code{GNAT.MBBS_Discrete_Random} (@file{g-mbdira.ads})
15752 @cindex @code{GNAT.MBBS_Discrete_Random} (@file{g-mbdira.ads})
15753 @cindex Random number generation
15756 The original implementation of @code{Ada.Numerics.Discrete_Random}. Uses
15757 a modified version of the Blum-Blum-Shub generator.
15759 @node GNAT.MBBS_Float_Random (g-mbflra.ads)
15760 @section @code{GNAT.MBBS_Float_Random} (@file{g-mbflra.ads})
15761 @cindex @code{GNAT.MBBS_Float_Random} (@file{g-mbflra.ads})
15762 @cindex Random number generation
15765 The original implementation of @code{Ada.Numerics.Float_Random}. Uses
15766 a modified version of the Blum-Blum-Shub generator.
15768 @node GNAT.MD5 (g-md5.ads)
15769 @section @code{GNAT.MD5} (@file{g-md5.ads})
15770 @cindex @code{GNAT.MD5} (@file{g-md5.ads})
15771 @cindex Message Digest MD5
15774 Implements the MD5 Message-Digest Algorithm as described in RFC 1321.
15776 @node GNAT.Memory_Dump (g-memdum.ads)
15777 @section @code{GNAT.Memory_Dump} (@file{g-memdum.ads})
15778 @cindex @code{GNAT.Memory_Dump} (@file{g-memdum.ads})
15779 @cindex Dump Memory
15782 Provides a convenient routine for dumping raw memory to either the
15783 standard output or standard error files. Uses GNAT.IO for actual
15786 @node GNAT.Most_Recent_Exception (g-moreex.ads)
15787 @section @code{GNAT.Most_Recent_Exception} (@file{g-moreex.ads})
15788 @cindex @code{GNAT.Most_Recent_Exception} (@file{g-moreex.ads})
15789 @cindex Exception, obtaining most recent
15792 Provides access to the most recently raised exception. Can be used for
15793 various logging purposes, including duplicating functionality of some
15794 Ada 83 implementation dependent extensions.
15796 @node GNAT.OS_Lib (g-os_lib.ads)
15797 @section @code{GNAT.OS_Lib} (@file{g-os_lib.ads})
15798 @cindex @code{GNAT.OS_Lib} (@file{g-os_lib.ads})
15799 @cindex Operating System interface
15800 @cindex Spawn capability
15803 Provides a range of target independent operating system interface functions,
15804 including time/date management, file operations, subprocess management,
15805 including a portable spawn procedure, and access to environment variables
15806 and error return codes.
15808 @node GNAT.Perfect_Hash_Generators (g-pehage.ads)
15809 @section @code{GNAT.Perfect_Hash_Generators} (@file{g-pehage.ads})
15810 @cindex @code{GNAT.Perfect_Hash_Generators} (@file{g-pehage.ads})
15811 @cindex Hash functions
15814 Provides a generator of static minimal perfect hash functions. No
15815 collisions occur and each item can be retrieved from the table in one
15816 probe (perfect property). The hash table size corresponds to the exact
15817 size of the key set and no larger (minimal property). The key set has to
15818 be know in advance (static property). The hash functions are also order
15819 preserving. If w2 is inserted after w1 in the generator, their
15820 hashcode are in the same order. These hashing functions are very
15821 convenient for use with realtime applications.
15823 @node GNAT.Random_Numbers (g-rannum.ads)
15824 @section @code{GNAT.Random_Numbers} (@file{g-rannum.ads})
15825 @cindex @code{GNAT.Random_Numbers} (@file{g-rannum.ads})
15826 @cindex Random number generation
15829 Provides random number capabilities which extend those available in the
15830 standard Ada library and are more convenient to use.
15832 @node GNAT.Regexp (g-regexp.ads)
15833 @section @code{GNAT.Regexp} (@file{g-regexp.ads})
15834 @cindex @code{GNAT.Regexp} (@file{g-regexp.ads})
15835 @cindex Regular expressions
15836 @cindex Pattern matching
15839 A simple implementation of regular expressions, using a subset of regular
15840 expression syntax copied from familiar Unix style utilities. This is the
15841 simples of the three pattern matching packages provided, and is particularly
15842 suitable for ``file globbing'' applications.
15844 @node GNAT.Registry (g-regist.ads)
15845 @section @code{GNAT.Registry} (@file{g-regist.ads})
15846 @cindex @code{GNAT.Registry} (@file{g-regist.ads})
15847 @cindex Windows Registry
15850 This is a high level binding to the Windows registry. It is possible to
15851 do simple things like reading a key value, creating a new key. For full
15852 registry API, but at a lower level of abstraction, refer to the Win32.Winreg
15853 package provided with the Win32Ada binding
15855 @node GNAT.Regpat (g-regpat.ads)
15856 @section @code{GNAT.Regpat} (@file{g-regpat.ads})
15857 @cindex @code{GNAT.Regpat} (@file{g-regpat.ads})
15858 @cindex Regular expressions
15859 @cindex Pattern matching
15862 A complete implementation of Unix-style regular expression matching, copied
15863 from the original V7 style regular expression library written in C by
15864 Henry Spencer (and binary compatible with this C library).
15866 @node GNAT.Secondary_Stack_Info (g-sestin.ads)
15867 @section @code{GNAT.Secondary_Stack_Info} (@file{g-sestin.ads})
15868 @cindex @code{GNAT.Secondary_Stack_Info} (@file{g-sestin.ads})
15869 @cindex Secondary Stack Info
15872 Provide the capability to query the high water mark of the current task's
15875 @node GNAT.Semaphores (g-semaph.ads)
15876 @section @code{GNAT.Semaphores} (@file{g-semaph.ads})
15877 @cindex @code{GNAT.Semaphores} (@file{g-semaph.ads})
15881 Provides classic counting and binary semaphores using protected types.
15883 @node GNAT.Serial_Communications (g-sercom.ads)
15884 @section @code{GNAT.Serial_Communications} (@file{g-sercom.ads})
15885 @cindex @code{GNAT.Serial_Communications} (@file{g-sercom.ads})
15886 @cindex Serial_Communications
15889 Provides a simple interface to send and receive data over a serial
15890 port. This is only supported on GNU/Linux and Windows.
15892 @node GNAT.SHA1 (g-sha1.ads)
15893 @section @code{GNAT.SHA1} (@file{g-sha1.ads})
15894 @cindex @code{GNAT.SHA1} (@file{g-sha1.ads})
15895 @cindex Secure Hash Algorithm SHA-1
15898 Implements the SHA-1 Secure Hash Algorithm as described in FIPS PUB 180-3
15901 @node GNAT.SHA224 (g-sha224.ads)
15902 @section @code{GNAT.SHA224} (@file{g-sha224.ads})
15903 @cindex @code{GNAT.SHA224} (@file{g-sha224.ads})
15904 @cindex Secure Hash Algorithm SHA-224
15907 Implements the SHA-224 Secure Hash Algorithm as described in FIPS PUB 180-3.
15909 @node GNAT.SHA256 (g-sha256.ads)
15910 @section @code{GNAT.SHA256} (@file{g-sha256.ads})
15911 @cindex @code{GNAT.SHA256} (@file{g-sha256.ads})
15912 @cindex Secure Hash Algorithm SHA-256
15915 Implements the SHA-256 Secure Hash Algorithm as described in FIPS PUB 180-3.
15917 @node GNAT.SHA384 (g-sha384.ads)
15918 @section @code{GNAT.SHA384} (@file{g-sha384.ads})
15919 @cindex @code{GNAT.SHA384} (@file{g-sha384.ads})
15920 @cindex Secure Hash Algorithm SHA-384
15923 Implements the SHA-384 Secure Hash Algorithm as described in FIPS PUB 180-3.
15925 @node GNAT.SHA512 (g-sha512.ads)
15926 @section @code{GNAT.SHA512} (@file{g-sha512.ads})
15927 @cindex @code{GNAT.SHA512} (@file{g-sha512.ads})
15928 @cindex Secure Hash Algorithm SHA-512
15931 Implements the SHA-512 Secure Hash Algorithm as described in FIPS PUB 180-3.
15933 @node GNAT.Signals (g-signal.ads)
15934 @section @code{GNAT.Signals} (@file{g-signal.ads})
15935 @cindex @code{GNAT.Signals} (@file{g-signal.ads})
15939 Provides the ability to manipulate the blocked status of signals on supported
15942 @node GNAT.Sockets (g-socket.ads)
15943 @section @code{GNAT.Sockets} (@file{g-socket.ads})
15944 @cindex @code{GNAT.Sockets} (@file{g-socket.ads})
15948 A high level and portable interface to develop sockets based applications.
15949 This package is based on the sockets thin binding found in
15950 @code{GNAT.Sockets.Thin}. Currently @code{GNAT.Sockets} is implemented
15951 on all native GNAT ports except for OpenVMS@. It is not implemented
15952 for the LynxOS@ cross port.
15954 @node GNAT.Source_Info (g-souinf.ads)
15955 @section @code{GNAT.Source_Info} (@file{g-souinf.ads})
15956 @cindex @code{GNAT.Source_Info} (@file{g-souinf.ads})
15957 @cindex Source Information
15960 Provides subprograms that give access to source code information known at
15961 compile time, such as the current file name and line number.
15963 @node GNAT.Spelling_Checker (g-speche.ads)
15964 @section @code{GNAT.Spelling_Checker} (@file{g-speche.ads})
15965 @cindex @code{GNAT.Spelling_Checker} (@file{g-speche.ads})
15966 @cindex Spell checking
15969 Provides a function for determining whether one string is a plausible
15970 near misspelling of another string.
15972 @node GNAT.Spelling_Checker_Generic (g-spchge.ads)
15973 @section @code{GNAT.Spelling_Checker_Generic} (@file{g-spchge.ads})
15974 @cindex @code{GNAT.Spelling_Checker_Generic} (@file{g-spchge.ads})
15975 @cindex Spell checking
15978 Provides a generic function that can be instantiated with a string type for
15979 determining whether one string is a plausible near misspelling of another
15982 @node GNAT.Spitbol.Patterns (g-spipat.ads)
15983 @section @code{GNAT.Spitbol.Patterns} (@file{g-spipat.ads})
15984 @cindex @code{GNAT.Spitbol.Patterns} (@file{g-spipat.ads})
15985 @cindex SPITBOL pattern matching
15986 @cindex Pattern matching
15989 A complete implementation of SNOBOL4 style pattern matching. This is the
15990 most elaborate of the pattern matching packages provided. It fully duplicates
15991 the SNOBOL4 dynamic pattern construction and matching capabilities, using the
15992 efficient algorithm developed by Robert Dewar for the SPITBOL system.
15994 @node GNAT.Spitbol (g-spitbo.ads)
15995 @section @code{GNAT.Spitbol} (@file{g-spitbo.ads})
15996 @cindex @code{GNAT.Spitbol} (@file{g-spitbo.ads})
15997 @cindex SPITBOL interface
16000 The top level package of the collection of SPITBOL-style functionality, this
16001 package provides basic SNOBOL4 string manipulation functions, such as
16002 Pad, Reverse, Trim, Substr capability, as well as a generic table function
16003 useful for constructing arbitrary mappings from strings in the style of
16004 the SNOBOL4 TABLE function.
16006 @node GNAT.Spitbol.Table_Boolean (g-sptabo.ads)
16007 @section @code{GNAT.Spitbol.Table_Boolean} (@file{g-sptabo.ads})
16008 @cindex @code{GNAT.Spitbol.Table_Boolean} (@file{g-sptabo.ads})
16009 @cindex Sets of strings
16010 @cindex SPITBOL Tables
16013 A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table}
16014 for type @code{Standard.Boolean}, giving an implementation of sets of
16017 @node GNAT.Spitbol.Table_Integer (g-sptain.ads)
16018 @section @code{GNAT.Spitbol.Table_Integer} (@file{g-sptain.ads})
16019 @cindex @code{GNAT.Spitbol.Table_Integer} (@file{g-sptain.ads})
16020 @cindex Integer maps
16022 @cindex SPITBOL Tables
16025 A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table}
16026 for type @code{Standard.Integer}, giving an implementation of maps
16027 from string to integer values.
16029 @node GNAT.Spitbol.Table_VString (g-sptavs.ads)
16030 @section @code{GNAT.Spitbol.Table_VString} (@file{g-sptavs.ads})
16031 @cindex @code{GNAT.Spitbol.Table_VString} (@file{g-sptavs.ads})
16032 @cindex String maps
16034 @cindex SPITBOL Tables
16037 A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table} for
16038 a variable length string type, giving an implementation of general
16039 maps from strings to strings.
16041 @node GNAT.SSE (g-sse.ads)
16042 @section @code{GNAT.SSE} (@file{g-sse.ads})
16043 @cindex @code{GNAT.SSE} (@file{g-sse.ads})
16046 Root of a set of units aimed at offering Ada bindings to a subset of
16047 the Intel(r) Streaming SIMD Extensions with GNAT on the x86 family of
16048 targets. It exposes vector component types together with a general
16049 introduction to the binding contents and use.
16051 @node GNAT.SSE.Vector_Types (g-ssvety.ads)
16052 @section @code{GNAT.SSE.Vector_Types} (@file{g-ssvety.ads})
16053 @cindex @code{GNAT.SSE.Vector_Types} (@file{g-ssvety.ads})
16056 SSE vector types for use with SSE related intrinsics.
16058 @node GNAT.Strings (g-string.ads)
16059 @section @code{GNAT.Strings} (@file{g-string.ads})
16060 @cindex @code{GNAT.Strings} (@file{g-string.ads})
16063 Common String access types and related subprograms. Basically it
16064 defines a string access and an array of string access types.
16066 @node GNAT.String_Split (g-strspl.ads)
16067 @section @code{GNAT.String_Split} (@file{g-strspl.ads})
16068 @cindex @code{GNAT.String_Split} (@file{g-strspl.ads})
16069 @cindex String splitter
16072 Useful string manipulation routines: given a set of separators, split
16073 a string wherever the separators appear, and provide direct access
16074 to the resulting slices. This package is instantiated from
16075 @code{GNAT.Array_Split}.
16077 @node GNAT.Table (g-table.ads)
16078 @section @code{GNAT.Table} (@file{g-table.ads})
16079 @cindex @code{GNAT.Table} (@file{g-table.ads})
16080 @cindex Table implementation
16081 @cindex Arrays, extendable
16084 A generic package providing a single dimension array abstraction where the
16085 length of the array can be dynamically modified.
16088 This package provides a facility similar to that of @code{GNAT.Dynamic_Tables},
16089 except that this package declares a single instance of the table type,
16090 while an instantiation of @code{GNAT.Dynamic_Tables} creates a type that can be
16091 used to define dynamic instances of the table.
16093 @node GNAT.Task_Lock (g-tasloc.ads)
16094 @section @code{GNAT.Task_Lock} (@file{g-tasloc.ads})
16095 @cindex @code{GNAT.Task_Lock} (@file{g-tasloc.ads})
16096 @cindex Task synchronization
16097 @cindex Task locking
16101 A very simple facility for locking and unlocking sections of code using a
16102 single global task lock. Appropriate for use in situations where contention
16103 between tasks is very rarely expected.
16105 @node GNAT.Time_Stamp (g-timsta.ads)
16106 @section @code{GNAT.Time_Stamp} (@file{g-timsta.ads})
16107 @cindex @code{GNAT.Time_Stamp} (@file{g-timsta.ads})
16109 @cindex Current time
16112 Provides a simple function that returns a string YYYY-MM-DD HH:MM:SS.SS that
16113 represents the current date and time in ISO 8601 format. This is a very simple
16114 routine with minimal code and there are no dependencies on any other unit.
16116 @node GNAT.Threads (g-thread.ads)
16117 @section @code{GNAT.Threads} (@file{g-thread.ads})
16118 @cindex @code{GNAT.Threads} (@file{g-thread.ads})
16119 @cindex Foreign threads
16120 @cindex Threads, foreign
16123 Provides facilities for dealing with foreign threads which need to be known
16124 by the GNAT run-time system. Consult the documentation of this package for
16125 further details if your program has threads that are created by a non-Ada
16126 environment which then accesses Ada code.
16128 @node GNAT.Traceback (g-traceb.ads)
16129 @section @code{GNAT.Traceback} (@file{g-traceb.ads})
16130 @cindex @code{GNAT.Traceback} (@file{g-traceb.ads})
16131 @cindex Trace back facilities
16134 Provides a facility for obtaining non-symbolic traceback information, useful
16135 in various debugging situations.
16137 @node GNAT.Traceback.Symbolic (g-trasym.ads)
16138 @section @code{GNAT.Traceback.Symbolic} (@file{g-trasym.ads})
16139 @cindex @code{GNAT.Traceback.Symbolic} (@file{g-trasym.ads})
16140 @cindex Trace back facilities
16142 @node GNAT.UTF_32 (g-utf_32.ads)
16143 @section @code{GNAT.UTF_32} (@file{g-table.ads})
16144 @cindex @code{GNAT.UTF_32} (@file{g-table.ads})
16145 @cindex Wide character codes
16148 This is a package intended to be used in conjunction with the
16149 @code{Wide_Character} type in Ada 95 and the
16150 @code{Wide_Wide_Character} type in Ada 2005 (available
16151 in @code{GNAT} in Ada 2005 mode). This package contains
16152 Unicode categorization routines, as well as lexical
16153 categorization routines corresponding to the Ada 2005
16154 lexical rules for identifiers and strings, and also a
16155 lower case to upper case fold routine corresponding to
16156 the Ada 2005 rules for identifier equivalence.
16158 @node GNAT.UTF_32_Spelling_Checker (g-u3spch.ads)
16159 @section @code{GNAT.Wide_Spelling_Checker} (@file{g-u3spch.ads})
16160 @cindex @code{GNAT.Wide_Spelling_Checker} (@file{g-u3spch.ads})
16161 @cindex Spell checking
16164 Provides a function for determining whether one wide wide string is a plausible
16165 near misspelling of another wide wide string, where the strings are represented
16166 using the UTF_32_String type defined in System.Wch_Cnv.
16168 @node GNAT.Wide_Spelling_Checker (g-wispch.ads)
16169 @section @code{GNAT.Wide_Spelling_Checker} (@file{g-wispch.ads})
16170 @cindex @code{GNAT.Wide_Spelling_Checker} (@file{g-wispch.ads})
16171 @cindex Spell checking
16174 Provides a function for determining whether one wide string is a plausible
16175 near misspelling of another wide string.
16177 @node GNAT.Wide_String_Split (g-wistsp.ads)
16178 @section @code{GNAT.Wide_String_Split} (@file{g-wistsp.ads})
16179 @cindex @code{GNAT.Wide_String_Split} (@file{g-wistsp.ads})
16180 @cindex Wide_String splitter
16183 Useful wide string manipulation routines: given a set of separators, split
16184 a wide string wherever the separators appear, and provide direct access
16185 to the resulting slices. This package is instantiated from
16186 @code{GNAT.Array_Split}.
16188 @node GNAT.Wide_Wide_Spelling_Checker (g-zspche.ads)
16189 @section @code{GNAT.Wide_Wide_Spelling_Checker} (@file{g-zspche.ads})
16190 @cindex @code{GNAT.Wide_Wide_Spelling_Checker} (@file{g-zspche.ads})
16191 @cindex Spell checking
16194 Provides a function for determining whether one wide wide string is a plausible
16195 near misspelling of another wide wide string.
16197 @node GNAT.Wide_Wide_String_Split (g-zistsp.ads)
16198 @section @code{GNAT.Wide_Wide_String_Split} (@file{g-zistsp.ads})
16199 @cindex @code{GNAT.Wide_Wide_String_Split} (@file{g-zistsp.ads})
16200 @cindex Wide_Wide_String splitter
16203 Useful wide wide string manipulation routines: given a set of separators, split
16204 a wide wide string wherever the separators appear, and provide direct access
16205 to the resulting slices. This package is instantiated from
16206 @code{GNAT.Array_Split}.
16208 @node Interfaces.C.Extensions (i-cexten.ads)
16209 @section @code{Interfaces.C.Extensions} (@file{i-cexten.ads})
16210 @cindex @code{Interfaces.C.Extensions} (@file{i-cexten.ads})
16213 This package contains additional C-related definitions, intended
16214 for use with either manually or automatically generated bindings
16217 @node Interfaces.C.Streams (i-cstrea.ads)
16218 @section @code{Interfaces.C.Streams} (@file{i-cstrea.ads})
16219 @cindex @code{Interfaces.C.Streams} (@file{i-cstrea.ads})
16220 @cindex C streams, interfacing
16223 This package is a binding for the most commonly used operations
16226 @node Interfaces.CPP (i-cpp.ads)
16227 @section @code{Interfaces.CPP} (@file{i-cpp.ads})
16228 @cindex @code{Interfaces.CPP} (@file{i-cpp.ads})
16229 @cindex C++ interfacing
16230 @cindex Interfacing, to C++
16233 This package provides facilities for use in interfacing to C++. It
16234 is primarily intended to be used in connection with automated tools
16235 for the generation of C++ interfaces.
16237 @node Interfaces.Packed_Decimal (i-pacdec.ads)
16238 @section @code{Interfaces.Packed_Decimal} (@file{i-pacdec.ads})
16239 @cindex @code{Interfaces.Packed_Decimal} (@file{i-pacdec.ads})
16240 @cindex IBM Packed Format
16241 @cindex Packed Decimal
16244 This package provides a set of routines for conversions to and
16245 from a packed decimal format compatible with that used on IBM
16248 @node Interfaces.VxWorks (i-vxwork.ads)
16249 @section @code{Interfaces.VxWorks} (@file{i-vxwork.ads})
16250 @cindex @code{Interfaces.VxWorks} (@file{i-vxwork.ads})
16251 @cindex Interfacing to VxWorks
16252 @cindex VxWorks, interfacing
16255 This package provides a limited binding to the VxWorks API.
16256 In particular, it interfaces with the
16257 VxWorks hardware interrupt facilities.
16259 @node Interfaces.VxWorks.IO (i-vxwoio.ads)
16260 @section @code{Interfaces.VxWorks.IO} (@file{i-vxwoio.ads})
16261 @cindex @code{Interfaces.VxWorks.IO} (@file{i-vxwoio.ads})
16262 @cindex Interfacing to VxWorks' I/O
16263 @cindex VxWorks, I/O interfacing
16264 @cindex VxWorks, Get_Immediate
16265 @cindex Get_Immediate, VxWorks
16268 This package provides a binding to the ioctl (IO/Control)
16269 function of VxWorks, defining a set of option values and
16270 function codes. A particular use of this package is
16271 to enable the use of Get_Immediate under VxWorks.
16273 @node System.Address_Image (s-addima.ads)
16274 @section @code{System.Address_Image} (@file{s-addima.ads})
16275 @cindex @code{System.Address_Image} (@file{s-addima.ads})
16276 @cindex Address image
16277 @cindex Image, of an address
16280 This function provides a useful debugging
16281 function that gives an (implementation dependent)
16282 string which identifies an address.
16284 @node System.Assertions (s-assert.ads)
16285 @section @code{System.Assertions} (@file{s-assert.ads})
16286 @cindex @code{System.Assertions} (@file{s-assert.ads})
16288 @cindex Assert_Failure, exception
16291 This package provides the declaration of the exception raised
16292 by an run-time assertion failure, as well as the routine that
16293 is used internally to raise this assertion.
16295 @node System.Memory (s-memory.ads)
16296 @section @code{System.Memory} (@file{s-memory.ads})
16297 @cindex @code{System.Memory} (@file{s-memory.ads})
16298 @cindex Memory allocation
16301 This package provides the interface to the low level routines used
16302 by the generated code for allocation and freeing storage for the
16303 default storage pool (analogous to the C routines malloc and free.
16304 It also provides a reallocation interface analogous to the C routine
16305 realloc. The body of this unit may be modified to provide alternative
16306 allocation mechanisms for the default pool, and in addition, direct
16307 calls to this unit may be made for low level allocation uses (for
16308 example see the body of @code{GNAT.Tables}).
16310 @node System.Partition_Interface (s-parint.ads)
16311 @section @code{System.Partition_Interface} (@file{s-parint.ads})
16312 @cindex @code{System.Partition_Interface} (@file{s-parint.ads})
16313 @cindex Partition interfacing functions
16316 This package provides facilities for partition interfacing. It
16317 is used primarily in a distribution context when using Annex E
16320 @node System.Pool_Global (s-pooglo.ads)
16321 @section @code{System.Pool_Global} (@file{s-pooglo.ads})
16322 @cindex @code{System.Pool_Global} (@file{s-pooglo.ads})
16323 @cindex Storage pool, global
16324 @cindex Global storage pool
16327 This package provides a storage pool that is equivalent to the default
16328 storage pool used for access types for which no pool is specifically
16329 declared. It uses malloc/free to allocate/free and does not attempt to
16330 do any automatic reclamation.
16332 @node System.Pool_Local (s-pooloc.ads)
16333 @section @code{System.Pool_Local} (@file{s-pooloc.ads})
16334 @cindex @code{System.Pool_Local} (@file{s-pooloc.ads})
16335 @cindex Storage pool, local
16336 @cindex Local storage pool
16339 This package provides a storage pool that is intended for use with locally
16340 defined access types. It uses malloc/free for allocate/free, and maintains
16341 a list of allocated blocks, so that all storage allocated for the pool can
16342 be freed automatically when the pool is finalized.
16344 @node System.Restrictions (s-restri.ads)
16345 @section @code{System.Restrictions} (@file{s-restri.ads})
16346 @cindex @code{System.Restrictions} (@file{s-restri.ads})
16347 @cindex Run-time restrictions access
16350 This package provides facilities for accessing at run time
16351 the status of restrictions specified at compile time for
16352 the partition. Information is available both with regard
16353 to actual restrictions specified, and with regard to
16354 compiler determined information on which restrictions
16355 are violated by one or more packages in the partition.
16357 @node System.Rident (s-rident.ads)
16358 @section @code{System.Rident} (@file{s-rident.ads})
16359 @cindex @code{System.Rident} (@file{s-rident.ads})
16360 @cindex Restrictions definitions
16363 This package provides definitions of the restrictions
16364 identifiers supported by GNAT, and also the format of
16365 the restrictions provided in package System.Restrictions.
16366 It is not normally necessary to @code{with} this generic package
16367 since the necessary instantiation is included in
16368 package System.Restrictions.
16370 @node System.Strings.Stream_Ops (s-ststop.ads)
16371 @section @code{System.Strings.Stream_Ops} (@file{s-ststop.ads})
16372 @cindex @code{System.Strings.Stream_Ops} (@file{s-ststop.ads})
16373 @cindex Stream operations
16374 @cindex String stream operations
16377 This package provides a set of stream subprograms for standard string types.
16378 It is intended primarily to support implicit use of such subprograms when
16379 stream attributes are applied to string types, but the subprograms in this
16380 package can be used directly by application programs.
16382 @node System.Task_Info (s-tasinf.ads)
16383 @section @code{System.Task_Info} (@file{s-tasinf.ads})
16384 @cindex @code{System.Task_Info} (@file{s-tasinf.ads})
16385 @cindex Task_Info pragma
16388 This package provides target dependent functionality that is used
16389 to support the @code{Task_Info} pragma
16391 @node System.Wch_Cnv (s-wchcnv.ads)
16392 @section @code{System.Wch_Cnv} (@file{s-wchcnv.ads})
16393 @cindex @code{System.Wch_Cnv} (@file{s-wchcnv.ads})
16394 @cindex Wide Character, Representation
16395 @cindex Wide String, Conversion
16396 @cindex Representation of wide characters
16399 This package provides routines for converting between
16400 wide and wide wide characters and a representation as a value of type
16401 @code{Standard.String}, using a specified wide character
16402 encoding method. It uses definitions in
16403 package @code{System.Wch_Con}.
16405 @node System.Wch_Con (s-wchcon.ads)
16406 @section @code{System.Wch_Con} (@file{s-wchcon.ads})
16407 @cindex @code{System.Wch_Con} (@file{s-wchcon.ads})
16410 This package provides definitions and descriptions of
16411 the various methods used for encoding wide characters
16412 in ordinary strings. These definitions are used by
16413 the package @code{System.Wch_Cnv}.
16415 @node Interfacing to Other Languages
16416 @chapter Interfacing to Other Languages
16418 The facilities in annex B of the Ada Reference Manual are fully
16419 implemented in GNAT, and in addition, a full interface to C++ is
16423 * Interfacing to C::
16424 * Interfacing to C++::
16425 * Interfacing to COBOL::
16426 * Interfacing to Fortran::
16427 * Interfacing to non-GNAT Ada code::
16430 @node Interfacing to C
16431 @section Interfacing to C
16434 Interfacing to C with GNAT can use one of two approaches:
16438 The types in the package @code{Interfaces.C} may be used.
16440 Standard Ada types may be used directly. This may be less portable to
16441 other compilers, but will work on all GNAT compilers, which guarantee
16442 correspondence between the C and Ada types.
16446 Pragma @code{Convention C} may be applied to Ada types, but mostly has no
16447 effect, since this is the default. The following table shows the
16448 correspondence between Ada scalar types and the corresponding C types.
16453 @item Short_Integer
16455 @item Short_Short_Integer
16459 @item Long_Long_Integer
16467 @item Long_Long_Float
16468 This is the longest floating-point type supported by the hardware.
16472 Additionally, there are the following general correspondences between Ada
16476 Ada enumeration types map to C enumeration types directly if pragma
16477 @code{Convention C} is specified, which causes them to have int
16478 length. Without pragma @code{Convention C}, Ada enumeration types map to
16479 8, 16, or 32 bits (i.e.@: C types @code{signed char}, @code{short},
16480 @code{int}, respectively) depending on the number of values passed.
16481 This is the only case in which pragma @code{Convention C} affects the
16482 representation of an Ada type.
16485 Ada access types map to C pointers, except for the case of pointers to
16486 unconstrained types in Ada, which have no direct C equivalent.
16489 Ada arrays map directly to C arrays.
16492 Ada records map directly to C structures.
16495 Packed Ada records map to C structures where all members are bit fields
16496 of the length corresponding to the @code{@var{type}'Size} value in Ada.
16499 @node Interfacing to C++
16500 @section Interfacing to C++
16503 The interface to C++ makes use of the following pragmas, which are
16504 primarily intended to be constructed automatically using a binding generator
16505 tool, although it is possible to construct them by hand. No suitable binding
16506 generator tool is supplied with GNAT though.
16508 Using these pragmas it is possible to achieve complete
16509 inter-operability between Ada tagged types and C++ class definitions.
16510 See @ref{Implementation Defined Pragmas}, for more details.
16513 @item pragma CPP_Class ([Entity =>] @var{LOCAL_NAME})
16514 The argument denotes an entity in the current declarative region that is
16515 declared as a tagged or untagged record type. It indicates that the type
16516 corresponds to an externally declared C++ class type, and is to be laid
16517 out the same way that C++ would lay out the type.
16519 Note: Pragma @code{CPP_Class} is currently obsolete. It is supported
16520 for backward compatibility but its functionality is available
16521 using pragma @code{Import} with @code{Convention} = @code{CPP}.
16523 @item pragma CPP_Constructor ([Entity =>] @var{LOCAL_NAME})
16524 This pragma identifies an imported function (imported in the usual way
16525 with pragma @code{Import}) as corresponding to a C++ constructor.
16528 @node Interfacing to COBOL
16529 @section Interfacing to COBOL
16532 Interfacing to COBOL is achieved as described in section B.4 of
16533 the Ada Reference Manual.
16535 @node Interfacing to Fortran
16536 @section Interfacing to Fortran
16539 Interfacing to Fortran is achieved as described in section B.5 of the
16540 Ada Reference Manual. The pragma @code{Convention Fortran}, applied to a
16541 multi-dimensional array causes the array to be stored in column-major
16542 order as required for convenient interface to Fortran.
16544 @node Interfacing to non-GNAT Ada code
16545 @section Interfacing to non-GNAT Ada code
16547 It is possible to specify the convention @code{Ada} in a pragma
16548 @code{Import} or pragma @code{Export}. However this refers to
16549 the calling conventions used by GNAT, which may or may not be
16550 similar enough to those used by some other Ada 83 / Ada 95 / Ada 2005
16551 compiler to allow interoperation.
16553 If arguments types are kept simple, and if the foreign compiler generally
16554 follows system calling conventions, then it may be possible to integrate
16555 files compiled by other Ada compilers, provided that the elaboration
16556 issues are adequately addressed (for example by eliminating the
16557 need for any load time elaboration).
16559 In particular, GNAT running on VMS is designed to
16560 be highly compatible with the DEC Ada 83 compiler, so this is one
16561 case in which it is possible to import foreign units of this type,
16562 provided that the data items passed are restricted to simple scalar
16563 values or simple record types without variants, or simple array
16564 types with fixed bounds.
16566 @node Specialized Needs Annexes
16567 @chapter Specialized Needs Annexes
16570 Ada 95 and Ada 2005 define a number of Specialized Needs Annexes, which are not
16571 required in all implementations. However, as described in this chapter,
16572 GNAT implements all of these annexes:
16575 @item Systems Programming (Annex C)
16576 The Systems Programming Annex is fully implemented.
16578 @item Real-Time Systems (Annex D)
16579 The Real-Time Systems Annex is fully implemented.
16581 @item Distributed Systems (Annex E)
16582 Stub generation is fully implemented in the GNAT compiler. In addition,
16583 a complete compatible PCS is available as part of the GLADE system,
16584 a separate product. When the two
16585 products are used in conjunction, this annex is fully implemented.
16587 @item Information Systems (Annex F)
16588 The Information Systems annex is fully implemented.
16590 @item Numerics (Annex G)
16591 The Numerics Annex is fully implemented.
16593 @item Safety and Security / High-Integrity Systems (Annex H)
16594 The Safety and Security Annex (termed the High-Integrity Systems Annex
16595 in Ada 2005) is fully implemented.
16598 @node Implementation of Specific Ada Features
16599 @chapter Implementation of Specific Ada Features
16602 This chapter describes the GNAT implementation of several Ada language
16606 * Machine Code Insertions::
16607 * GNAT Implementation of Tasking::
16608 * GNAT Implementation of Shared Passive Packages::
16609 * Code Generation for Array Aggregates::
16610 * The Size of Discriminated Records with Default Discriminants::
16611 * Strict Conformance to the Ada Reference Manual::
16614 @node Machine Code Insertions
16615 @section Machine Code Insertions
16616 @cindex Machine Code insertions
16619 Package @code{Machine_Code} provides machine code support as described
16620 in the Ada Reference Manual in two separate forms:
16623 Machine code statements, consisting of qualified expressions that
16624 fit the requirements of RM section 13.8.
16626 An intrinsic callable procedure, providing an alternative mechanism of
16627 including machine instructions in a subprogram.
16631 The two features are similar, and both are closely related to the mechanism
16632 provided by the asm instruction in the GNU C compiler. Full understanding
16633 and use of the facilities in this package requires understanding the asm
16634 instruction, see @ref{Extended Asm,, Assembler Instructions with C Expression
16635 Operands, gcc, Using the GNU Compiler Collection (GCC)}.
16637 Calls to the function @code{Asm} and the procedure @code{Asm} have identical
16638 semantic restrictions and effects as described below. Both are provided so
16639 that the procedure call can be used as a statement, and the function call
16640 can be used to form a code_statement.
16642 The first example given in the GCC documentation is the C @code{asm}
16645 asm ("fsinx %1 %0" : "=f" (result) : "f" (angle));
16649 The equivalent can be written for GNAT as:
16651 @smallexample @c ada
16652 Asm ("fsinx %1 %0",
16653 My_Float'Asm_Output ("=f", result),
16654 My_Float'Asm_Input ("f", angle));
16658 The first argument to @code{Asm} is the assembler template, and is
16659 identical to what is used in GNU C@. This string must be a static
16660 expression. The second argument is the output operand list. It is
16661 either a single @code{Asm_Output} attribute reference, or a list of such
16662 references enclosed in parentheses (technically an array aggregate of
16665 The @code{Asm_Output} attribute denotes a function that takes two
16666 parameters. The first is a string, the second is the name of a variable
16667 of the type designated by the attribute prefix. The first (string)
16668 argument is required to be a static expression and designates the
16669 constraint for the parameter (e.g.@: what kind of register is
16670 required). The second argument is the variable to be updated with the
16671 result. The possible values for constraint are the same as those used in
16672 the RTL, and are dependent on the configuration file used to build the
16673 GCC back end. If there are no output operands, then this argument may
16674 either be omitted, or explicitly given as @code{No_Output_Operands}.
16676 The second argument of @code{@var{my_float}'Asm_Output} functions as
16677 though it were an @code{out} parameter, which is a little curious, but
16678 all names have the form of expressions, so there is no syntactic
16679 irregularity, even though normally functions would not be permitted
16680 @code{out} parameters. The third argument is the list of input
16681 operands. It is either a single @code{Asm_Input} attribute reference, or
16682 a list of such references enclosed in parentheses (technically an array
16683 aggregate of such references).
16685 The @code{Asm_Input} attribute denotes a function that takes two
16686 parameters. The first is a string, the second is an expression of the
16687 type designated by the prefix. The first (string) argument is required
16688 to be a static expression, and is the constraint for the parameter,
16689 (e.g.@: what kind of register is required). The second argument is the
16690 value to be used as the input argument. The possible values for the
16691 constant are the same as those used in the RTL, and are dependent on
16692 the configuration file used to built the GCC back end.
16694 If there are no input operands, this argument may either be omitted, or
16695 explicitly given as @code{No_Input_Operands}. The fourth argument, not
16696 present in the above example, is a list of register names, called the
16697 @dfn{clobber} argument. This argument, if given, must be a static string
16698 expression, and is a space or comma separated list of names of registers
16699 that must be considered destroyed as a result of the @code{Asm} call. If
16700 this argument is the null string (the default value), then the code
16701 generator assumes that no additional registers are destroyed.
16703 The fifth argument, not present in the above example, called the
16704 @dfn{volatile} argument, is by default @code{False}. It can be set to
16705 the literal value @code{True} to indicate to the code generator that all
16706 optimizations with respect to the instruction specified should be
16707 suppressed, and that in particular, for an instruction that has outputs,
16708 the instruction will still be generated, even if none of the outputs are
16709 used. @xref{Extended Asm,, Assembler Instructions with C Expression Operands,
16710 gcc, Using the GNU Compiler Collection (GCC)}, for the full description.
16711 Generally it is strongly advisable to use Volatile for any ASM statement
16712 that is missing either input or output operands, or when two or more ASM
16713 statements appear in sequence, to avoid unwanted optimizations. A warning
16714 is generated if this advice is not followed.
16716 The @code{Asm} subprograms may be used in two ways. First the procedure
16717 forms can be used anywhere a procedure call would be valid, and
16718 correspond to what the RM calls ``intrinsic'' routines. Such calls can
16719 be used to intersperse machine instructions with other Ada statements.
16720 Second, the function forms, which return a dummy value of the limited
16721 private type @code{Asm_Insn}, can be used in code statements, and indeed
16722 this is the only context where such calls are allowed. Code statements
16723 appear as aggregates of the form:
16725 @smallexample @c ada
16726 Asm_Insn'(Asm (@dots{}));
16727 Asm_Insn'(Asm_Volatile (@dots{}));
16731 In accordance with RM rules, such code statements are allowed only
16732 within subprograms whose entire body consists of such statements. It is
16733 not permissible to intermix such statements with other Ada statements.
16735 Typically the form using intrinsic procedure calls is more convenient
16736 and more flexible. The code statement form is provided to meet the RM
16737 suggestion that such a facility should be made available. The following
16738 is the exact syntax of the call to @code{Asm}. As usual, if named notation
16739 is used, the arguments may be given in arbitrary order, following the
16740 normal rules for use of positional and named arguments)
16744 [Template =>] static_string_EXPRESSION
16745 [,[Outputs =>] OUTPUT_OPERAND_LIST ]
16746 [,[Inputs =>] INPUT_OPERAND_LIST ]
16747 [,[Clobber =>] static_string_EXPRESSION ]
16748 [,[Volatile =>] static_boolean_EXPRESSION] )
16750 OUTPUT_OPERAND_LIST ::=
16751 [PREFIX.]No_Output_Operands
16752 | OUTPUT_OPERAND_ATTRIBUTE
16753 | (OUTPUT_OPERAND_ATTRIBUTE @{,OUTPUT_OPERAND_ATTRIBUTE@})
16755 OUTPUT_OPERAND_ATTRIBUTE ::=
16756 SUBTYPE_MARK'Asm_Output (static_string_EXPRESSION, NAME)
16758 INPUT_OPERAND_LIST ::=
16759 [PREFIX.]No_Input_Operands
16760 | INPUT_OPERAND_ATTRIBUTE
16761 | (INPUT_OPERAND_ATTRIBUTE @{,INPUT_OPERAND_ATTRIBUTE@})
16763 INPUT_OPERAND_ATTRIBUTE ::=
16764 SUBTYPE_MARK'Asm_Input (static_string_EXPRESSION, EXPRESSION)
16768 The identifiers @code{No_Input_Operands} and @code{No_Output_Operands}
16769 are declared in the package @code{Machine_Code} and must be referenced
16770 according to normal visibility rules. In particular if there is no
16771 @code{use} clause for this package, then appropriate package name
16772 qualification is required.
16774 @node GNAT Implementation of Tasking
16775 @section GNAT Implementation of Tasking
16778 This chapter outlines the basic GNAT approach to tasking (in particular,
16779 a multi-layered library for portability) and discusses issues related
16780 to compliance with the Real-Time Systems Annex.
16783 * Mapping Ada Tasks onto the Underlying Kernel Threads::
16784 * Ensuring Compliance with the Real-Time Annex::
16787 @node Mapping Ada Tasks onto the Underlying Kernel Threads
16788 @subsection Mapping Ada Tasks onto the Underlying Kernel Threads
16791 GNAT's run-time support comprises two layers:
16794 @item GNARL (GNAT Run-time Layer)
16795 @item GNULL (GNAT Low-level Library)
16799 In GNAT, Ada's tasking services rely on a platform and OS independent
16800 layer known as GNARL@. This code is responsible for implementing the
16801 correct semantics of Ada's task creation, rendezvous, protected
16804 GNARL decomposes Ada's tasking semantics into simpler lower level
16805 operations such as create a thread, set the priority of a thread,
16806 yield, create a lock, lock/unlock, etc. The spec for these low-level
16807 operations constitutes GNULLI, the GNULL Interface. This interface is
16808 directly inspired from the POSIX real-time API@.
16810 If the underlying executive or OS implements the POSIX standard
16811 faithfully, the GNULL Interface maps as is to the services offered by
16812 the underlying kernel. Otherwise, some target dependent glue code maps
16813 the services offered by the underlying kernel to the semantics expected
16816 Whatever the underlying OS (VxWorks, UNIX, Windows, etc.) the
16817 key point is that each Ada task is mapped on a thread in the underlying
16818 kernel. For example, in the case of VxWorks, one Ada task = one VxWorks task.
16820 In addition Ada task priorities map onto the underlying thread priorities.
16821 Mapping Ada tasks onto the underlying kernel threads has several advantages:
16825 The underlying scheduler is used to schedule the Ada tasks. This
16826 makes Ada tasks as efficient as kernel threads from a scheduling
16830 Interaction with code written in C containing threads is eased
16831 since at the lowest level Ada tasks and C threads map onto the same
16832 underlying kernel concept.
16835 When an Ada task is blocked during I/O the remaining Ada tasks are
16839 On multiprocessor systems Ada tasks can execute in parallel.
16843 Some threads libraries offer a mechanism to fork a new process, with the
16844 child process duplicating the threads from the parent.
16846 support this functionality when the parent contains more than one task.
16847 @cindex Forking a new process
16849 @node Ensuring Compliance with the Real-Time Annex
16850 @subsection Ensuring Compliance with the Real-Time Annex
16851 @cindex Real-Time Systems Annex compliance
16854 Although mapping Ada tasks onto
16855 the underlying threads has significant advantages, it does create some
16856 complications when it comes to respecting the scheduling semantics
16857 specified in the real-time annex (Annex D).
16859 For instance the Annex D requirement for the @code{FIFO_Within_Priorities}
16860 scheduling policy states:
16863 @emph{When the active priority of a ready task that is not running
16864 changes, or the setting of its base priority takes effect, the
16865 task is removed from the ready queue for its old active priority
16866 and is added at the tail of the ready queue for its new active
16867 priority, except in the case where the active priority is lowered
16868 due to the loss of inherited priority, in which case the task is
16869 added at the head of the ready queue for its new active priority.}
16873 While most kernels do put tasks at the end of the priority queue when
16874 a task changes its priority, (which respects the main
16875 FIFO_Within_Priorities requirement), almost none keep a thread at the
16876 beginning of its priority queue when its priority drops from the loss
16877 of inherited priority.
16879 As a result most vendors have provided incomplete Annex D implementations.
16881 The GNAT run-time, has a nice cooperative solution to this problem
16882 which ensures that accurate FIFO_Within_Priorities semantics are
16885 The principle is as follows. When an Ada task T is about to start
16886 running, it checks whether some other Ada task R with the same
16887 priority as T has been suspended due to the loss of priority
16888 inheritance. If this is the case, T yields and is placed at the end of
16889 its priority queue. When R arrives at the front of the queue it
16892 Note that this simple scheme preserves the relative order of the tasks
16893 that were ready to execute in the priority queue where R has been
16896 @node GNAT Implementation of Shared Passive Packages
16897 @section GNAT Implementation of Shared Passive Packages
16898 @cindex Shared passive packages
16901 GNAT fully implements the pragma @code{Shared_Passive} for
16902 @cindex pragma @code{Shared_Passive}
16903 the purpose of designating shared passive packages.
16904 This allows the use of passive partitions in the
16905 context described in the Ada Reference Manual; i.e., for communication
16906 between separate partitions of a distributed application using the
16907 features in Annex E.
16909 @cindex Distribution Systems Annex
16911 However, the implementation approach used by GNAT provides for more
16912 extensive usage as follows:
16915 @item Communication between separate programs
16917 This allows separate programs to access the data in passive
16918 partitions, using protected objects for synchronization where
16919 needed. The only requirement is that the two programs have a
16920 common shared file system. It is even possible for programs
16921 running on different machines with different architectures
16922 (e.g.@: different endianness) to communicate via the data in
16923 a passive partition.
16925 @item Persistence between program runs
16927 The data in a passive package can persist from one run of a
16928 program to another, so that a later program sees the final
16929 values stored by a previous run of the same program.
16934 The implementation approach used is to store the data in files. A
16935 separate stream file is created for each object in the package, and
16936 an access to an object causes the corresponding file to be read or
16939 The environment variable @code{SHARED_MEMORY_DIRECTORY} should be
16940 @cindex @code{SHARED_MEMORY_DIRECTORY} environment variable
16941 set to the directory to be used for these files.
16942 The files in this directory
16943 have names that correspond to their fully qualified names. For
16944 example, if we have the package
16946 @smallexample @c ada
16948 pragma Shared_Passive (X);
16955 and the environment variable is set to @code{/stemp/}, then the files created
16956 will have the names:
16964 These files are created when a value is initially written to the object, and
16965 the files are retained until manually deleted. This provides the persistence
16966 semantics. If no file exists, it means that no partition has assigned a value
16967 to the variable; in this case the initial value declared in the package
16968 will be used. This model ensures that there are no issues in synchronizing
16969 the elaboration process, since elaboration of passive packages elaborates the
16970 initial values, but does not create the files.
16972 The files are written using normal @code{Stream_IO} access.
16973 If you want to be able
16974 to communicate between programs or partitions running on different
16975 architectures, then you should use the XDR versions of the stream attribute
16976 routines, since these are architecture independent.
16978 If active synchronization is required for access to the variables in the
16979 shared passive package, then as described in the Ada Reference Manual, the
16980 package may contain protected objects used for this purpose. In this case
16981 a lock file (whose name is @file{___lock} (three underscores)
16982 is created in the shared memory directory.
16983 @cindex @file{___lock} file (for shared passive packages)
16984 This is used to provide the required locking
16985 semantics for proper protected object synchronization.
16987 As of January 2003, GNAT supports shared passive packages on all platforms
16988 except for OpenVMS.
16990 @node Code Generation for Array Aggregates
16991 @section Code Generation for Array Aggregates
16994 * Static constant aggregates with static bounds::
16995 * Constant aggregates with unconstrained nominal types::
16996 * Aggregates with static bounds::
16997 * Aggregates with non-static bounds::
16998 * Aggregates in assignment statements::
17002 Aggregates have a rich syntax and allow the user to specify the values of
17003 complex data structures by means of a single construct. As a result, the
17004 code generated for aggregates can be quite complex and involve loops, case
17005 statements and multiple assignments. In the simplest cases, however, the
17006 compiler will recognize aggregates whose components and constraints are
17007 fully static, and in those cases the compiler will generate little or no
17008 executable code. The following is an outline of the code that GNAT generates
17009 for various aggregate constructs. For further details, you will find it
17010 useful to examine the output produced by the -gnatG flag to see the expanded
17011 source that is input to the code generator. You may also want to examine
17012 the assembly code generated at various levels of optimization.
17014 The code generated for aggregates depends on the context, the component values,
17015 and the type. In the context of an object declaration the code generated is
17016 generally simpler than in the case of an assignment. As a general rule, static
17017 component values and static subtypes also lead to simpler code.
17019 @node Static constant aggregates with static bounds
17020 @subsection Static constant aggregates with static bounds
17023 For the declarations:
17024 @smallexample @c ada
17025 type One_Dim is array (1..10) of integer;
17026 ar0 : constant One_Dim := (1, 2, 3, 4, 5, 6, 7, 8, 9, 0);
17030 GNAT generates no executable code: the constant ar0 is placed in static memory.
17031 The same is true for constant aggregates with named associations:
17033 @smallexample @c ada
17034 Cr1 : constant One_Dim := (4 => 16, 2 => 4, 3 => 9, 1 => 1, 5 .. 10 => 0);
17035 Cr3 : constant One_Dim := (others => 7777);
17039 The same is true for multidimensional constant arrays such as:
17041 @smallexample @c ada
17042 type two_dim is array (1..3, 1..3) of integer;
17043 Unit : constant two_dim := ( (1,0,0), (0,1,0), (0,0,1));
17047 The same is true for arrays of one-dimensional arrays: the following are
17050 @smallexample @c ada
17051 type ar1b is array (1..3) of boolean;
17052 type ar_ar is array (1..3) of ar1b;
17053 None : constant ar1b := (others => false); -- fully static
17054 None2 : constant ar_ar := (1..3 => None); -- fully static
17058 However, for multidimensional aggregates with named associations, GNAT will
17059 generate assignments and loops, even if all associations are static. The
17060 following two declarations generate a loop for the first dimension, and
17061 individual component assignments for the second dimension:
17063 @smallexample @c ada
17064 Zero1: constant two_dim := (1..3 => (1..3 => 0));
17065 Zero2: constant two_dim := (others => (others => 0));
17068 @node Constant aggregates with unconstrained nominal types
17069 @subsection Constant aggregates with unconstrained nominal types
17072 In such cases the aggregate itself establishes the subtype, so that
17073 associations with @code{others} cannot be used. GNAT determines the
17074 bounds for the actual subtype of the aggregate, and allocates the
17075 aggregate statically as well. No code is generated for the following:
17077 @smallexample @c ada
17078 type One_Unc is array (natural range <>) of integer;
17079 Cr_Unc : constant One_Unc := (12,24,36);
17082 @node Aggregates with static bounds
17083 @subsection Aggregates with static bounds
17086 In all previous examples the aggregate was the initial (and immutable) value
17087 of a constant. If the aggregate initializes a variable, then code is generated
17088 for it as a combination of individual assignments and loops over the target
17089 object. The declarations
17091 @smallexample @c ada
17092 Cr_Var1 : One_Dim := (2, 5, 7, 11, 0, 0, 0, 0, 0, 0);
17093 Cr_Var2 : One_Dim := (others > -1);
17097 generate the equivalent of
17099 @smallexample @c ada
17105 for I in Cr_Var2'range loop
17110 @node Aggregates with non-static bounds
17111 @subsection Aggregates with non-static bounds
17114 If the bounds of the aggregate are not statically compatible with the bounds
17115 of the nominal subtype of the target, then constraint checks have to be
17116 generated on the bounds. For a multidimensional array, constraint checks may
17117 have to be applied to sub-arrays individually, if they do not have statically
17118 compatible subtypes.
17120 @node Aggregates in assignment statements
17121 @subsection Aggregates in assignment statements
17124 In general, aggregate assignment requires the construction of a temporary,
17125 and a copy from the temporary to the target of the assignment. This is because
17126 it is not always possible to convert the assignment into a series of individual
17127 component assignments. For example, consider the simple case:
17129 @smallexample @c ada
17134 This cannot be converted into:
17136 @smallexample @c ada
17142 So the aggregate has to be built first in a separate location, and then
17143 copied into the target. GNAT recognizes simple cases where this intermediate
17144 step is not required, and the assignments can be performed in place, directly
17145 into the target. The following sufficient criteria are applied:
17149 The bounds of the aggregate are static, and the associations are static.
17151 The components of the aggregate are static constants, names of
17152 simple variables that are not renamings, or expressions not involving
17153 indexed components whose operands obey these rules.
17157 If any of these conditions are violated, the aggregate will be built in
17158 a temporary (created either by the front-end or the code generator) and then
17159 that temporary will be copied onto the target.
17161 @node The Size of Discriminated Records with Default Discriminants
17162 @section The Size of Discriminated Records with Default Discriminants
17165 If a discriminated type @code{T} has discriminants with default values, it is
17166 possible to declare an object of this type without providing an explicit
17169 @smallexample @c ada
17171 type Size is range 1..100;
17173 type Rec (D : Size := 15) is record
17174 Name : String (1..D);
17182 Such an object is said to be @emph{unconstrained}.
17183 The discriminant of the object
17184 can be modified by a full assignment to the object, as long as it preserves the
17185 relation between the value of the discriminant, and the value of the components
17188 @smallexample @c ada
17190 Word := (3, "yes");
17192 Word := (5, "maybe");
17194 Word := (5, "no"); -- raises Constraint_Error
17199 In order to support this behavior efficiently, an unconstrained object is
17200 given the maximum size that any value of the type requires. In the case
17201 above, @code{Word} has storage for the discriminant and for
17202 a @code{String} of length 100.
17203 It is important to note that unconstrained objects do not require dynamic
17204 allocation. It would be an improper implementation to place on the heap those
17205 components whose size depends on discriminants. (This improper implementation
17206 was used by some Ada83 compilers, where the @code{Name} component above
17208 been stored as a pointer to a dynamic string). Following the principle that
17209 dynamic storage management should never be introduced implicitly,
17210 an Ada compiler should reserve the full size for an unconstrained declared
17211 object, and place it on the stack.
17213 This maximum size approach
17214 has been a source of surprise to some users, who expect the default
17215 values of the discriminants to determine the size reserved for an
17216 unconstrained object: ``If the default is 15, why should the object occupy
17218 The answer, of course, is that the discriminant may be later modified,
17219 and its full range of values must be taken into account. This is why the
17224 type Rec (D : Positive := 15) is record
17225 Name : String (1..D);
17233 is flagged by the compiler with a warning:
17234 an attempt to create @code{Too_Large} will raise @code{Storage_Error},
17235 because the required size includes @code{Positive'Last}
17236 bytes. As the first example indicates, the proper approach is to declare an
17237 index type of ``reasonable'' range so that unconstrained objects are not too
17240 One final wrinkle: if the object is declared to be @code{aliased}, or if it is
17241 created in the heap by means of an allocator, then it is @emph{not}
17243 it is constrained by the default values of the discriminants, and those values
17244 cannot be modified by full assignment. This is because in the presence of
17245 aliasing all views of the object (which may be manipulated by different tasks,
17246 say) must be consistent, so it is imperative that the object, once created,
17249 @node Strict Conformance to the Ada Reference Manual
17250 @section Strict Conformance to the Ada Reference Manual
17253 The dynamic semantics defined by the Ada Reference Manual impose a set of
17254 run-time checks to be generated. By default, the GNAT compiler will insert many
17255 run-time checks into the compiled code, including most of those required by the
17256 Ada Reference Manual. However, there are three checks that are not enabled
17257 in the default mode for efficiency reasons: arithmetic overflow checking for
17258 integer operations (including division by zero), checks for access before
17259 elaboration on subprogram calls, and stack overflow checking (most operating
17260 systems do not perform this check by default).
17262 Strict conformance to the Ada Reference Manual can be achieved by adding
17263 three compiler options for overflow checking for integer operations
17264 (@option{-gnato}), dynamic checks for access-before-elaboration on subprogram
17265 calls and generic instantiations (@option{-gnatE}), and stack overflow
17266 checking (@option{-fstack-check}).
17268 Note that the result of a floating point arithmetic operation in overflow and
17269 invalid situations, when the @code{Machine_Overflows} attribute of the result
17270 type is @code{False}, is to generate IEEE NaN and infinite values. This is the
17271 case for machines compliant with the IEEE floating-point standard, but on
17272 machines that are not fully compliant with this standard, such as Alpha, the
17273 @option{-mieee} compiler flag must be used for achieving IEEE confirming
17274 behavior (although at the cost of a significant performance penalty), so
17275 infinite and NaN values are properly generated.
17278 @node Implementation of Ada 2012 Features
17279 @chapter Implementation of Ada 2012 Features
17280 @cindex Ada 2012 implementation status
17282 This chapter contains a complete list of Ada 2012 features that have been
17283 implemented as of GNAT version 6.4. Generally, these features are only
17284 available if the @option{-gnat12} (Ada 2012 features enabled) flag is set
17285 @cindex @option{-gnat12} option
17286 or if the configuration pragma @code{Ada_2012} is used.
17287 @cindex pragma @code{Ada_2012}
17288 @cindex configuration pragma @code{Ada_2012}
17289 @cindex @code{Ada_2012} configuration pragma
17290 However, new pragmas, attributes, and restrictions are
17291 unconditionally available, since the Ada 95 standard allows the addition of
17292 new pragmas, attributes, and restrictions (there are exceptions, which are
17293 documented in the individual descriptions), and also certain packages
17294 were made available in earlier versions of Ada.
17296 An ISO date (YYYY-MM-DD) appears in parentheses on the description line.
17297 This date shows the implementation date of the feature. Any wavefront
17298 subsequent to this date will contain the indicated feature, as will any
17299 subsequent releases. A date of 0000-00-00 means that GNAT has always
17300 implemented the feature, or implemented it as soon as it appeared as a
17301 binding interpretation.
17303 Each feature corresponds to an Ada Issue (``AI'') approved by the Ada
17304 standardization group (ISO/IEC JTC1/SC22/WG9) for inclusion in Ada 2012.
17305 The features are ordered based on the relevant sections of the Ada
17306 Reference Manual (``RM''). When a given AI relates to multiple points
17307 in the RM, the earliest is used.
17309 A complete description of the AIs may be found in
17310 @url{www.ada-auth.org/ai05-summary.html}.
17315 @emph{AI-0176 Quantified expressions (2010-09-29)}
17316 @cindex AI-0176 (Ada 2012 feature)
17319 Both universally and existentially quantified expressions are implemented.
17320 They use the new syntax for iterators proposed in AI05-139-2, as well as
17321 the standard Ada loop syntax.
17324 RM References: 1.01.04 (12) 2.09 (2/2) 4.04 (7) 4.05.09 (0)
17327 @emph{AI-0079 Allow @i{other_format} characters in source (2010-07-10)}
17328 @cindex AI-0079 (Ada 2012 feature)
17331 Wide characters in the unicode category @i{other_format} are now allowed in
17332 source programs between tokens, but not within a token such as an identifier.
17335 RM References: 2.01 (4/2) 2.02 (7)
17338 @emph{AI-0091 Do not allow @i{other_format} in identifiers (0000-00-00)}
17339 @cindex AI-0091 (Ada 2012 feature)
17342 Wide characters in the unicode category @i{other_format} are not permitted
17343 within an identifier, since this can be a security problem. The error
17344 message for this case has been improved to be more specific, but GNAT has
17345 never allowed such characters to appear in identifiers.
17348 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)
17351 @emph{AI-0100 Placement of pragmas (2010-07-01)}
17352 @cindex AI-0100 (Ada 2012 feature)
17355 This AI is an earlier version of AI-163. It simplifies the rules
17356 for legal placement of pragmas. In the case of lists that allow pragmas, if
17357 the list may have no elements, then the list may consist solely of pragmas.
17360 RM References: 2.08 (7)
17363 @emph{AI-0163 Pragmas in place of null (2010-07-01)}
17364 @cindex AI-0163 (Ada 2012 feature)
17367 A statement sequence may be composed entirely of pragmas. It is no longer
17368 necessary to add a dummy @code{null} statement to make the sequence legal.
17371 RM References: 2.08 (7) 2.08 (16)
17375 @emph{AI-0080 ``View of'' not needed if clear from context (0000-00-00)}
17376 @cindex AI-0080 (Ada 2012 feature)
17379 This is an editorial change only, described as non-testable in the AI.
17382 RM References: 3.01 (7)
17386 @emph{AI-0183 Aspect specifications (2010-08-16)}
17387 @cindex AI-0183 (Ada 2012 feature)
17390 Aspect specifications have been fully implemented except for pre and post-
17391 conditions, and type invariants, which have their own separate AI's. All
17392 forms of declarations listed in the AI are supported. The following is a
17393 list of the aspects supported (with GNAT implementation aspects marked)
17395 @multitable {@code{Preelaborable_Initialization}} {--GNAT}
17396 @item @code{Ada_2005} @tab -- GNAT
17397 @item @code{Ada_2012} @tab -- GNAT
17398 @item @code{Address} @tab
17399 @item @code{Alignment} @tab
17400 @item @code{Atomic} @tab
17401 @item @code{Atomic_Components} @tab
17402 @item @code{Bit_Order} @tab
17403 @item @code{Component_Size} @tab
17404 @item @code{Discard_Names} @tab
17405 @item @code{External_Tag} @tab
17406 @item @code{Favor_Top_Level} @tab -- GNAT
17407 @item @code{Inline} @tab
17408 @item @code{Inline_Always} @tab -- GNAT
17409 @item @code{Invariant} @tab
17410 @item @code{Machine_Radix} @tab
17411 @item @code{No_Return} @tab
17412 @item @code{Object_Size} @tab -- GNAT
17413 @item @code{Pack} @tab
17414 @item @code{Persistent_BSS} @tab -- GNAT
17415 @item @code{Post} @tab
17416 @item @code{Pre} @tab
17417 @item @code{Predicate} @tab
17418 @item @code{Preelaborable_Initialization} @tab
17419 @item @code{Pure_Function} @tab -- GNAT
17420 @item @code{Remote_Access_Type} @tab -- GNAT
17421 @item @code{Shared} @tab -- GNAT
17422 @item @code{Size} @tab
17423 @item @code{Storage_Pool} @tab
17424 @item @code{Storage_Size} @tab
17425 @item @code{Stream_Size} @tab
17426 @item @code{Suppress} @tab
17427 @item @code{Suppress_Debug_Info} @tab -- GNAT
17428 @item @code{Test_Case} @tab -- GNAT
17429 @item @code{Unchecked_Union} @tab
17430 @item @code{Universal_Aliasing} @tab -- GNAT
17431 @item @code{Unmodified} @tab -- GNAT
17432 @item @code{Unreferenced} @tab -- GNAT
17433 @item @code{Unreferenced_Objects} @tab -- GNAT
17434 @item @code{Unsuppress} @tab
17435 @item @code{Value_Size} @tab -- GNAT
17436 @item @code{Volatile} @tab
17437 @item @code{Volatile_Components}
17438 @item @code{Warnings} @tab -- GNAT
17442 Note that for aspects with an expression, e.g. @code{Size}, the expression is
17443 treated like a default expression (visibility is analyzed at the point of
17444 occurrence of the aspect, but evaluation of the expression occurs at the
17445 freeze point of the entity involved.
17448 RM References: 3.02.01 (3) 3.02.02 (2) 3.03.01 (2/2) 3.08 (6)
17449 3.09.03 (1.1/2) 6.01 (2/2) 6.07 (2/2) 9.05.02 (2/2) 7.01 (3) 7.03
17450 (2) 7.03 (3) 9.01 (2/2) 9.01 (3/2) 9.04 (2/2) 9.04 (3/2)
17451 9.05.02 (2/2) 11.01 (2) 12.01 (3) 12.03 (2/2) 12.04 (2/2) 12.05 (2)
17452 12.06 (2.1/2) 12.06 (2.2/2) 12.07 (2) 13.01 (0.1/2) 13.03 (5/1)
17457 @emph{AI-0128 Inequality is a primitive operation (0000-00-00)}
17458 @cindex AI-0128 (Ada 2012 feature)
17461 If an equality operator ("=") is declared for a type, then the implicitly
17462 declared inequality operator ("/=") is a primitive operation of the type.
17463 This is the only reasonable interpretation, and is the one always implemented
17464 by GNAT, but the RM was not entirely clear in making this point.
17467 RM References: 3.02.03 (6) 6.06 (6)
17470 @emph{AI-0003 Qualified expressions as names (2010-07-11)}
17471 @cindex AI-0003 (Ada 2012 feature)
17474 In Ada 2012, a qualified expression is considered to be syntactically a name,
17475 meaning that constructs such as @code{A'(F(X)).B} are now legal. This is
17476 useful in disambiguating some cases of overloading.
17479 RM References: 3.03 (11) 3.03 (21) 4.01 (2) 4.04 (7) 4.07 (3)
17483 @emph{AI-0120 Constant instance of protected object (0000-00-00)}
17484 @cindex AI-0120 (Ada 2012 feature)
17487 This is an RM editorial change only. The section that lists objects that are
17488 constant failed to include the current instance of a protected object
17489 within a protected function. This has always been treated as a constant
17493 RM References: 3.03 (21)
17496 @emph{AI-0008 General access to constrained objects (0000-00-00)}
17497 @cindex AI-0008 (Ada 2012 feature)
17500 The wording in the RM implied that if you have a general access to a
17501 constrained object, it could be used to modify the discriminants. This was
17502 obviously not intended. @code{Constraint_Error} should be raised, and GNAT
17503 has always done so in this situation.
17506 RM References: 3.03 (23) 3.10.02 (26/2) 4.01 (9) 6.04.01 (17) 8.05.01 (5/2)
17510 @emph{AI-0093 Additional rules use immutably limited (0000-00-00)}
17511 @cindex AI-0093 (Ada 2012 feature)
17514 This is an editorial change only, to make more widespread use of the Ada 2012
17515 ``immutably limited''.
17518 RM References: 3.03 (23.4/3)
17523 @emph{AI-0096 Deriving from formal private types (2010-07-20)}
17524 @cindex AI-0096 (Ada 2012 feature)
17527 In general it is illegal for a type derived from a formal limited type to be
17528 nonlimited. This AI makes an exception to this rule: derivation is legal
17529 if it appears in the private part of the generic, and the formal type is not
17530 tagged. If the type is tagged, the legality check must be applied to the
17531 private part of the package.
17534 RM References: 3.04 (5.1/2) 6.02 (7)
17538 @emph{AI-0181 Soft hyphen is a non-graphic character (2010-07-23)}
17539 @cindex AI-0181 (Ada 2012 feature)
17542 From Ada 2005 on, soft hyphen is considered a non-graphic character, which
17543 means that it has a special name (@code{SOFT_HYPHEN}) in conjunction with the
17544 @code{Image} and @code{Value} attributes for the character types. Strictly
17545 speaking this is an inconsistency with Ada 95, but in practice the use of
17546 these attributes is so obscure that it will not cause problems.
17549 RM References: 3.05.02 (2/2) A.01 (35/2) A.03.03 (21)
17553 @emph{AI-0182 Additional forms for @code{Character'Value} (0000-00-00)}
17554 @cindex AI-0182 (Ada 2012 feature)
17557 This AI allows @code{Character'Value} to accept the string @code{'?'} where
17558 @code{?} is any character including non-graphic control characters. GNAT has
17559 always accepted such strings. It also allows strings such as
17560 @code{HEX_00000041} to be accepted, but GNAT does not take advantage of this
17561 permission and raises @code{Constraint_Error}, as is certainly still
17565 RM References: 3.05 (56/2)
17569 @emph{AI-0214 Defaulted discriminants for limited tagged (2010-10-01)}
17570 @cindex AI-0214 (Ada 2012 feature)
17573 Ada 2012 relaxes the restriction that forbids discriminants of tagged types
17574 to have default expressions by allowing them when the type is limited. It
17575 is often useful to define a default value for a discriminant even though
17576 it can't be changed by assignment.
17579 RM References: 3.07 (9.1/2) 3.07.02 (3)
17583 @emph{AI-0102 Some implicit conversions are illegal (0000-00-00)}
17584 @cindex AI-0102 (Ada 2012 feature)
17587 It is illegal to assign an anonymous access constant to an anonymous access
17588 variable. The RM did not have a clear rule to prevent this, but GNAT has
17589 always generated an error for this usage.
17592 RM References: 3.07 (16) 3.07.01 (9) 6.04.01 (6) 8.06 (27/2)
17596 @emph{AI-0158 Generalizing membership tests (2010-09-16)}
17597 @cindex AI-0158 (Ada 2012 feature)
17600 This AI extends the syntax of membership tests to simplify complex conditions
17601 that can be expressed as membership in a subset of values of any type. It
17602 introduces syntax for a list of expressions that may be used in loop contexts
17606 RM References: 3.08.01 (5) 4.04 (3) 4.05.02 (3) 4.05.02 (5) 4.05.02 (27)
17610 @emph{AI-0173 Testing if tags represent abstract types (2010-07-03)}
17611 @cindex AI-0173 (Ada 2012 feature)
17614 The function @code{Ada.Tags.Type_Is_Abstract} returns @code{True} if invoked
17615 with the tag of an abstract type, and @code{False} otherwise.
17618 RM References: 3.09 (7.4/2) 3.09 (12.4/2)
17623 @emph{AI-0076 function with controlling result (0000-00-00)}
17624 @cindex AI-0076 (Ada 2012 feature)
17627 This is an editorial change only. The RM defines calls with controlling
17628 results, but uses the term ``function with controlling result'' without an
17629 explicit definition.
17632 RM References: 3.09.02 (2/2)
17636 @emph{AI-0126 Dispatching with no declared operation (0000-00-00)}
17637 @cindex AI-0126 (Ada 2012 feature)
17640 This AI clarifies dispatching rules, and simply confirms that dispatching
17641 executes the operation of the parent type when there is no explicitly or
17642 implicitly declared operation for the descendant type. This has always been
17643 the case in all versions of GNAT.
17646 RM References: 3.09.02 (20/2) 3.09.02 (20.1/2) 3.09.02 (20.2/2)
17650 @emph{AI-0097 Treatment of abstract null extension (2010-07-19)}
17651 @cindex AI-0097 (Ada 2012 feature)
17654 The RM as written implied that in some cases it was possible to create an
17655 object of an abstract type, by having an abstract extension inherit a non-
17656 abstract constructor from its parent type. This mistake has been corrected
17657 in GNAT and in the RM, and this construct is now illegal.
17660 RM References: 3.09.03 (4/2)
17664 @emph{AI-0203 Extended return cannot be abstract (0000-00-00)}
17665 @cindex AI-0203 (Ada 2012 feature)
17668 A return_subtype_indication cannot denote an abstract subtype. GNAT has never
17669 permitted such usage.
17672 RM References: 3.09.03 (8/3)
17676 @emph{AI-0198 Inheriting abstract operators (0000-00-00)}
17677 @cindex AI-0198 (Ada 2012 feature)
17680 This AI resolves a conflict between two rules involving inherited abstract
17681 operations and predefined operators. If a derived numeric type inherits
17682 an abstract operator, it overrides the predefined one. This interpretation
17683 was always the one implemented in GNAT.
17686 RM References: 3.09.03 (4/3)
17689 @emph{AI-0073 Functions returning abstract types (2010-07-10)}
17690 @cindex AI-0073 (Ada 2012 feature)
17693 This AI covers a number of issues regarding returning abstract types. In
17694 particular generic functions cannot have abstract result types or access
17695 result types designated an abstract type. There are some other cases which
17696 are detailed in the AI. Note that this binding interpretation has not been
17697 retrofitted to operate before Ada 2012 mode, since it caused a significant
17698 number of regressions.
17701 RM References: 3.09.03 (8) 3.09.03 (10) 6.05 (8/2)
17705 @emph{AI-0070 Elaboration of interface types (0000-00-00)}
17706 @cindex AI-0070 (Ada 2012 feature)
17709 This is an editorial change only, there are no testable consequences short of
17710 checking for the absence of generated code for an interface declaration.
17713 RM References: 3.09.04 (18/2)
17717 @emph{AI-0208 Characteristics of incomplete views (0000-00-00)}
17718 @cindex AI-0208 (Ada 2012 feature)
17721 The wording in the Ada 2005 RM concerning characteristics of incomplete views
17722 was incorrect and implied that some programs intended to be legal were now
17723 illegal. GNAT had never considered such programs illegal, so it has always
17724 implemented the intent of this AI.
17727 RM References: 3.10.01 (2.4/2) 3.10.01 (2.6/2)
17731 @emph{AI-0162 Incomplete type completed by partial view (2010-09-15)}
17732 @cindex AI-0162 (Ada 2012 feature)
17735 Incomplete types are made more useful by allowing them to be completed by
17736 private types and private extensions.
17739 RM References: 3.10.01 (2.5/2) 3.10.01 (2.6/2) 3.10.01 (3) 3.10.01 (4/2)
17744 @emph{AI-0098 Anonymous subprogram access restrictions (0000-00-00)}
17745 @cindex AI-0098 (Ada 2012 feature)
17748 An unintentional omission in the RM implied some inconsistent restrictions on
17749 the use of anonymous access to subprogram values. These restrictions were not
17750 intentional, and have never been enforced by GNAT.
17753 RM References: 3.10.01 (6) 3.10.01 (9.2/2)
17757 @emph{AI-0199 Aggregate with anonymous access components (2010-07-14)}
17758 @cindex AI-0199 (Ada 2012 feature)
17761 A choice list in a record aggregate can include several components of
17762 (distinct) anonymous access types as long as they have matching designated
17766 RM References: 4.03.01 (16)
17770 @emph{AI-0220 Needed components for aggregates (0000-00-00)}
17771 @cindex AI-0220 (Ada 2012 feature)
17774 This AI addresses a wording problem in the RM that appears to permit some
17775 complex cases of aggregates with non-static discriminants. GNAT has always
17776 implemented the intended semantics.
17779 RM References: 4.03.01 (17)
17782 @emph{AI-0147 Conditional expressions (2009-03-29)}
17783 @cindex AI-0147 (Ada 2012 feature)
17786 Conditional expressions are permitted. The form of such an expression is:
17789 (@b{if} @i{expr} @b{then} @i{expr} @{@b{elsif} @i{expr} @b{then} @i{expr}@} [@b{else} @i{expr}])
17792 The parentheses can be omitted in contexts where parentheses are present
17793 anyway, such as subprogram arguments and pragma arguments. If the @b{else}
17794 clause is omitted, @b{else True} is assumed;
17795 thus @code{(@b{if} A @b{then} B)} is a way to conveniently represent
17796 @emph{(A implies B)} in standard logic.
17799 RM References: 4.03.03 (15) 4.04 (1) 4.04 (7) 4.05.07 (0) 4.07 (2)
17800 4.07 (3) 4.09 (12) 4.09 (33) 5.03 (3) 5.03 (4) 7.05 (2.1/2)
17804 @emph{AI-0037 Out-of-range box associations in aggregate (0000-00-00)}
17805 @cindex AI-0037 (Ada 2012 feature)
17808 This AI confirms that an association of the form @code{Indx => <>} in an
17809 array aggregate must raise @code{Constraint_Error} if @code{Indx}
17810 is out of range. The RM specified a range check on other associations, but
17811 not when the value of the association was defaulted. GNAT has always inserted
17812 a constraint check on the index value.
17815 RM References: 4.03.03 (29)
17819 @emph{AI-0123 Composability of equality (2010-04-13)}
17820 @cindex AI-0123 (Ada 2012 feature)
17823 Equality of untagged record composes, so that the predefined equality for a
17824 composite type that includes a component of some untagged record type
17825 @code{R} uses the equality operation of @code{R} (which may be user-defined
17826 or predefined). This makes the behavior of untagged records identical to that
17827 of tagged types in this respect.
17829 This change is an incompatibility with previous versions of Ada, but it
17830 corrects a non-uniformity that was often a source of confusion. Analysis of
17831 a large number of industrial programs indicates that in those rare cases
17832 where a composite type had an untagged record component with a user-defined
17833 equality, either there was no use of the composite equality, or else the code
17834 expected the same composability as for tagged types, and thus had a bug that
17835 would be fixed by this change.
17838 RM References: 4.05.02 (9.7/2) 4.05.02 (14) 4.05.02 (15) 4.05.02 (24)
17843 @emph{AI-0088 The value of exponentiation (0000-00-00)}
17844 @cindex AI-0088 (Ada 2012 feature)
17847 This AI clarifies the equivalence rule given for the dynamic semantics of
17848 exponentiation: the value of the operation can be obtained by repeated
17849 multiplication, but the operation can be implemented otherwise (for example
17850 using the familiar divide-by-two-and-square algorithm, even if this is less
17851 accurate), and does not imply repeated reads of a volatile base.
17854 RM References: 4.05.06 (11)
17857 @emph{AI-0188 Case expressions (2010-01-09)}
17858 @cindex AI-0188 (Ada 2012 feature)
17861 Case expressions are permitted. This allows use of constructs such as:
17863 X := (@b{case} Y @b{is when} 1 => 2, @b{when} 2 => 3, @b{when others} => 31)
17867 RM References: 4.05.07 (0) 4.05.08 (0) 4.09 (12) 4.09 (33)
17870 @emph{AI-0104 Null exclusion and uninitialized allocator (2010-07-15)}
17871 @cindex AI-0104 (Ada 2012 feature)
17874 The assignment @code{Ptr := @b{new not null} Some_Ptr;} will raise
17875 @code{Constraint_Error} because the default value of the allocated object is
17876 @b{null}. This useless construct is illegal in Ada 2012.
17879 RM References: 4.08 (2)
17882 @emph{AI-0157 Allocation/Deallocation from empty pool (2010-07-11)}
17883 @cindex AI-0157 (Ada 2012 feature)
17886 Allocation and Deallocation from an empty storage pool (i.e. allocation or
17887 deallocation of a pointer for which a static storage size clause of zero
17888 has been given) is now illegal and is detected as such. GNAT
17889 previously gave a warning but not an error.
17892 RM References: 4.08 (5.3/2) 13.11.02 (4) 13.11.02 (17)
17895 @emph{AI-0179 Statement not required after label (2010-04-10)}
17896 @cindex AI-0179 (Ada 2012 feature)
17899 It is not necessary to have a statement following a label, so a label
17900 can appear at the end of a statement sequence without the need for putting a
17901 null statement afterwards, but it is not allowable to have only labels and
17902 no real statements in a statement sequence.
17905 RM References: 5.01 (2)
17909 @emph{AI-139-2 Syntactic sugar for iterators (2010-09-29)}
17910 @cindex AI-139-2 (Ada 2012 feature)
17913 The new syntax for iterating over arrays and containers is now implemented.
17914 Iteration over containers is for now limited to read-only iterators. Only
17915 default iterators are supported, with the syntax: @code{@b{for} Elem @b{of} C}.
17918 RM References: 5.05
17921 @emph{AI-0134 Profiles must match for full conformance (0000-00-00)}
17922 @cindex AI-0134 (Ada 2012 feature)
17925 For full conformance, the profiles of anonymous-access-to-subprogram
17926 parameters must match. GNAT has always enforced this rule.
17929 RM References: 6.03.01 (18)
17932 @emph{AI-0207 Mode conformance and access constant (0000-00-00)}
17933 @cindex AI-0207 (Ada 2012 feature)
17936 This AI confirms that access_to_constant indication must match for mode
17937 conformance. This was implemented in GNAT when the qualifier was originally
17938 introduced in Ada 2005.
17941 RM References: 6.03.01 (16/2)
17945 @emph{AI-0046 Null exclusion match for full conformance (2010-07-17)}
17946 @cindex AI-0046 (Ada 2012 feature)
17949 For full conformance, in the case of access parameters, the null exclusion
17950 must match (either both or neither must have @code{@b{not null}}).
17953 RM References: 6.03.02 (18)
17957 @emph{AI-0118 The association of parameter associations (0000-00-00)}
17958 @cindex AI-0118 (Ada 2012 feature)
17961 This AI clarifies the rules for named associations in subprogram calls and
17962 generic instantiations. The rules have been in place since Ada 83.
17965 RM References: 6.04.01 (2) 12.03 (9)
17969 @emph{AI-0196 Null exclusion tests for out parameters (0000-00-00)}
17970 @cindex AI-0196 (Ada 2012 feature)
17973 Null exclusion checks are not made for @code{@b{out}} parameters when
17974 evaluating the actual parameters. GNAT has never generated these checks.
17977 RM References: 6.04.01 (13)
17980 @emph{AI-0015 Constant return objects (0000-00-00)}
17981 @cindex AI-0015 (Ada 2012 feature)
17984 The return object declared in an @i{extended_return_statement} may be
17985 declared constant. This was always intended, and GNAT has always allowed it.
17988 RM References: 6.05 (2.1/2) 3.03 (10/2) 3.03 (21) 6.05 (5/2)
17993 @emph{AI-0032 Extended return for class-wide functions (0000-00-00)}
17994 @cindex AI-0032 (Ada 2012 feature)
17997 If a function returns a class-wide type, the object of an extended return
17998 statement can be declared with a specific type that is covered by the class-
17999 wide type. This has been implemented in GNAT since the introduction of
18000 extended returns. Note AI-0103 complements this AI by imposing matching
18001 rules for constrained return types.
18004 RM References: 6.05 (5.2/2) 6.05 (5.3/2) 6.05 (5.6/2) 6.05 (5.8/2)
18008 @emph{AI-0103 Static matching for extended return (2010-07-23)}
18009 @cindex AI-0103 (Ada 2012 feature)
18012 If the return subtype of a function is an elementary type or a constrained
18013 type, the subtype indication in an extended return statement must match
18014 statically this return subtype.
18017 RM References: 6.05 (5.2/2)
18021 @emph{AI-0058 Abnormal completion of an extended return (0000-00-00)}
18022 @cindex AI-0058 (Ada 2012 feature)
18025 The RM had some incorrect wording implying wrong treatment of abnormal
18026 completion in an extended return. GNAT has always implemented the intended
18027 correct semantics as described by this AI.
18030 RM References: 6.05 (22/2)
18034 @emph{AI-0050 Raising Constraint_Error early for function call (0000-00-00)}
18035 @cindex AI-0050 (Ada 2012 feature)
18038 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
18039 not take advantage of these incorrect permissions in any case.
18042 RM References: 6.05 (24/2)
18046 @emph{AI-0125 Nonoverridable operations of an ancestor (2010-09-28)}
18047 @cindex AI-0125 (Ada 2012 feature)
18050 In Ada 2012, the declaration of a primitive operation of a type extension
18051 or private extension can also override an inherited primitive that is not
18052 visible at the point of this declaration.
18055 RM References: 7.03.01 (6) 8.03 (23) 8.03.01 (5/2) 8.03.01 (6/2)
18058 @emph{AI-0062 Null exclusions and deferred constants (0000-00-00)}
18059 @cindex AI-0062 (Ada 2012 feature)
18062 A full constant may have a null exclusion even if its associated deferred
18063 constant does not. GNAT has always allowed this.
18066 RM References: 7.04 (6/2) 7.04 (7.1/2)
18070 @emph{AI-0178 Incomplete views are limited (0000-00-00)}
18071 @cindex AI-0178 (Ada 2012 feature)
18074 This AI clarifies the role of incomplete views and plugs an omission in the
18075 RM. GNAT always correctly restricted the use of incomplete views and types.
18078 RM References: 7.05 (3/2) 7.05 (6/2)
18081 @emph{AI-0087 Actual for formal nonlimited derived type (2010-07-15)}
18082 @cindex AI-0087 (Ada 2012 feature)
18085 The actual for a formal nonlimited derived type cannot be limited. In
18086 particular, a formal derived type that extends a limited interface but which
18087 is not explicitly limited cannot be instantiated with a limited type.
18090 RM References: 7.05 (5/2) 12.05.01 (5.1/2)
18093 @emph{AI-0099 Tag determines whether finalization needed (0000-00-00)}
18094 @cindex AI-0099 (Ada 2012 feature)
18097 This AI clarifies that ``needs finalization'' is part of dynamic semantics,
18098 and therefore depends on the run-time characteristics of an object (i.e. its
18099 tag) and not on its nominal type. As the AI indicates: ``we do not expect
18100 this to affect any implementation''.
18103 RM References: 7.06.01 (6) 7.06.01 (7) 7.06.01 (8) 7.06.01 (9/2)
18108 @emph{AI-0064 Redundant finalization rule (0000-00-00)}
18109 @cindex AI-0064 (Ada 2012 feature)
18112 This is an editorial change only. The intended behavior is already checked
18113 by an existing ACATS test, which GNAT has always executed correctly.
18116 RM References: 7.06.01 (17.1/1)
18119 @emph{AI-0026 Missing rules for Unchecked_Union (2010-07-07)}
18120 @cindex AI-0026 (Ada 2012 feature)
18123 Record representation clauses concerning Unchecked_Union types cannot mention
18124 the discriminant of the type. The type of a component declared in the variant
18125 part of an Unchecked_Union cannot be controlled, have controlled components,
18126 nor have protected or task parts. If an Unchecked_Union type is declared
18127 within the body of a generic unit or its descendants, then the type of a
18128 component declared in the variant part cannot be a formal private type or a
18129 formal private extension declared within the same generic unit.
18132 RM References: 7.06 (9.4/2) B.03.03 (9/2) B.03.03 (10/2)
18136 @emph{AI-0205 Extended return declares visible name (0000-00-00)}
18137 @cindex AI-0205 (Ada 2012 feature)
18140 This AI corrects a simple omission in the RM. Return objects have always
18141 been visible within an extended return statement.
18144 RM References: 8.03 (17)
18148 @emph{AI-0042 Overriding versus implemented-by (0000-00-00)}
18149 @cindex AI-0042 (Ada 2012 feature)
18152 This AI fixes a wording gap in the RM. An operation of a synchronized
18153 interface can be implemented by a protected or task entry, but the abstract
18154 operation is not being overridden in the usual sense, and it must be stated
18155 separately that this implementation is legal. This has always been the case
18159 RM References: 9.01 (9.2/2) 9.04 (11.1/2)
18162 @emph{AI-0030 Requeue on synchronized interfaces (2010-07-19)}
18163 @cindex AI-0030 (Ada 2012 feature)
18166 Requeue is permitted to a protected, synchronized or task interface primitive
18167 providing it is known that the overriding operation is an entry. Otherwise
18168 the requeue statement has the same effect as a procedure call. Use of pragma
18169 @code{Implemented} provides a way to impose a static requirement on the
18170 overriding operation by adhering to one of the implementation kinds: entry,
18171 protected procedure or any of the above.
18174 RM References: 9.05 (9) 9.05.04 (2) 9.05.04 (3) 9.05.04 (5)
18175 9.05.04 (6) 9.05.04 (7) 9.05.04 (12)
18179 @emph{AI-0201 Independence of atomic object components (2010-07-22)}
18180 @cindex AI-0201 (Ada 2012 feature)
18183 If an Atomic object has a pragma @code{Pack} or a @code{Component_Size}
18184 attribute, then individual components may not be addressable by independent
18185 tasks. However, if the representation clause has no effect (is confirming),
18186 then independence is not compromised. Furthermore, in GNAT, specification of
18187 other appropriately addressable component sizes (e.g. 16 for 8-bit
18188 characters) also preserves independence. GNAT now gives very clear warnings
18189 both for the declaration of such a type, and for any assignment to its components.
18192 RM References: 9.10 (1/3) C.06 (22/2) C.06 (23/2)
18195 @emph{AI-0009 Pragma Independent[_Components] (2010-07-23)}
18196 @cindex AI-0009 (Ada 2012 feature)
18199 This AI introduces the new pragmas @code{Independent} and
18200 @code{Independent_Components},
18201 which control guaranteeing independence of access to objects and components.
18202 The AI also requires independence not unaffected by confirming rep clauses.
18205 RM References: 9.10 (1) 13.01 (15/1) 13.02 (9) 13.03 (13) C.06 (2)
18206 C.06 (4) C.06 (6) C.06 (9) C.06 (13) C.06 (14)
18210 @emph{AI-0072 Task signalling using 'Terminated (0000-00-00)}
18211 @cindex AI-0072 (Ada 2012 feature)
18214 This AI clarifies that task signalling for reading @code{'Terminated} only
18215 occurs if the result is True. GNAT semantics has always been consistent with
18216 this notion of task signalling.
18219 RM References: 9.10 (6.1/1)
18222 @emph{AI-0108 Limited incomplete view and discriminants (0000-00-00)}
18223 @cindex AI-0108 (Ada 2012 feature)
18226 This AI confirms that an incomplete type from a limited view does not have
18227 discriminants. This has always been the case in GNAT.
18230 RM References: 10.01.01 (12.3/2)
18233 @emph{AI-0129 Limited views and incomplete types (0000-00-00)}
18234 @cindex AI-0129 (Ada 2012 feature)
18237 This AI clarifies the description of limited views: a limited view of a
18238 package includes only one view of a type that has an incomplete declaration
18239 and a full declaration (there is no possible ambiguity in a client package).
18240 This AI also fixes an omission: a nested package in the private part has no
18241 limited view. GNAT always implemented this correctly.
18244 RM References: 10.01.01 (12.2/2) 10.01.01 (12.3/2)
18249 @emph{AI-0077 Limited withs and scope of declarations (0000-00-00)}
18250 @cindex AI-0077 (Ada 2012 feature)
18253 This AI clarifies that a declaration does not include a context clause,
18254 and confirms that it is illegal to have a context in which both a limited
18255 and a nonlimited view of a package are accessible. Such double visibility
18256 was always rejected by GNAT.
18259 RM References: 10.01.02 (12/2) 10.01.02 (21/2) 10.01.02 (22/2)
18262 @emph{AI-0122 Private with and children of generics (0000-00-00)}
18263 @cindex AI-0122 (Ada 2012 feature)
18266 This AI clarifies the visibility of private children of generic units within
18267 instantiations of a parent. GNAT has always handled this correctly.
18270 RM References: 10.01.02 (12/2)
18275 @emph{AI-0040 Limited with clauses on descendant (0000-00-00)}
18276 @cindex AI-0040 (Ada 2012 feature)
18279 This AI confirms that a limited with clause in a child unit cannot name
18280 an ancestor of the unit. This has always been checked in GNAT.
18283 RM References: 10.01.02 (20/2)
18286 @emph{AI-0132 Placement of library unit pragmas (0000-00-00)}
18287 @cindex AI-0132 (Ada 2012 feature)
18290 This AI fills a gap in the description of library unit pragmas. The pragma
18291 clearly must apply to a library unit, even if it does not carry the name
18292 of the enclosing unit. GNAT has always enforced the required check.
18295 RM References: 10.01.05 (7)
18299 @emph{AI-0034 Categorization of limited views (0000-00-00)}
18300 @cindex AI-0034 (Ada 2012 feature)
18303 The RM makes certain limited with clauses illegal because of categorization
18304 considerations, when the corresponding normal with would be legal. This is
18305 not intended, and GNAT has always implemented the recommended behavior.
18308 RM References: 10.02.01 (11/1) 10.02.01 (17/2)
18312 @emph{AI-0035 Inconsistencies with Pure units (0000-00-00)}
18313 @cindex AI-0035 (Ada 2012 feature)
18316 This AI remedies some inconsistencies in the legality rules for Pure units.
18317 Derived access types are legal in a pure unit (on the assumption that the
18318 rule for a zero storage pool size has been enforced on the ancestor type).
18319 The rules are enforced in generic instances and in subunits. GNAT has always
18320 implemented the recommended behavior.
18323 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)
18327 @emph{AI-0219 Pure permissions and limited parameters (2010-05-25)}
18328 @cindex AI-0219 (Ada 2012 feature)
18331 This AI refines the rules for the cases with limited parameters which do not
18332 allow the implementations to omit ``redundant''. GNAT now properly conforms
18333 to the requirements of this binding interpretation.
18336 RM References: 10.02.01 (18/2)
18339 @emph{AI-0043 Rules about raising exceptions (0000-00-00)}
18340 @cindex AI-0043 (Ada 2012 feature)
18343 This AI covers various omissions in the RM regarding the raising of
18344 exceptions. GNAT has always implemented the intended semantics.
18347 RM References: 11.04.01 (10.1/2) 11 (2)
18351 @emph{AI-0200 Mismatches in formal package declarations (0000-00-00)}
18352 @cindex AI-0200 (Ada 2012 feature)
18355 This AI plugs a gap in the RM which appeared to allow some obviously intended
18356 illegal instantiations. GNAT has never allowed these instantiations.
18359 RM References: 12.07 (16)
18363 @emph{AI-0112 Detection of duplicate pragmas (2010-07-24)}
18364 @cindex AI-0112 (Ada 2012 feature)
18367 This AI concerns giving names to various representation aspects, but the
18368 practical effect is simply to make the use of duplicate
18369 @code{Atomic}[@code{_Components}],
18370 @code{Volatile}[@code{_Components}] and
18371 @code{Independent}[@code{_Components}] pragmas illegal, and GNAT
18372 now performs this required check.
18375 RM References: 13.01 (8)
18378 @emph{AI-0106 No representation pragmas on generic formals (0000-00-00)}
18379 @cindex AI-0106 (Ada 2012 feature)
18382 The RM appeared to allow representation pragmas on generic formal parameters,
18383 but this was not intended, and GNAT has never permitted this usage.
18386 RM References: 13.01 (9.1/1)
18390 @emph{AI-0012 Pack/Component_Size for aliased/atomic (2010-07-15)}
18391 @cindex AI-0012 (Ada 2012 feature)
18394 It is now illegal to give an inappropriate component size or a pragma
18395 @code{Pack} that attempts to change the component size in the case of atomic
18396 or aliased components. Previously GNAT ignored such an attempt with a
18400 RM References: 13.02 (6.1/2) 13.02 (7) C.06 (10) C.06 (11) C.06 (21)
18404 @emph{AI-0039 Stream attributes cannot be dynamic (0000-00-00)}
18405 @cindex AI-0039 (Ada 2012 feature)
18408 The RM permitted the use of dynamic expressions (such as @code{ptr.@b{all})}
18409 for stream attributes, but these were never useful and are now illegal. GNAT
18410 has always regarded such expressions as illegal.
18413 RM References: 13.03 (4) 13.03 (6) 13.13.02 (38/2)
18417 @emph{AI-0095 Address of intrinsic subprograms (0000-00-00)}
18418 @cindex AI-0095 (Ada 2012 feature)
18421 The prefix of @code{'Address} cannot statically denote a subprogram with
18422 convention @code{Intrinsic}. The use of the @code{Address} attribute raises
18423 @code{Program_Error} if the prefix denotes a subprogram with convention
18427 RM References: 13.03 (11/1)
18431 @emph{AI-0116 Alignment of class-wide objects (0000-00-00)}
18432 @cindex AI-0116 (Ada 2012 feature)
18435 This AI requires that the alignment of a class-wide object be no greater
18436 than the alignment of any type in the class. GNAT has always followed this
18440 RM References: 13.03 (29) 13.11 (16)
18444 @emph{AI-0146 Type invariants (2009-09-21)}
18445 @cindex AI-0146 (Ada 2012 feature)
18448 Type invariants may be specified for private types using the aspect notation.
18449 Aspect @code{Invariant} may be specified for any private type,
18450 @code{Invariant'Class} can
18451 only be specified for tagged types, and is inherited by any descendent of the
18452 tagged types. The invariant is a boolean expression that is tested for being
18453 true in the following situations: conversions to the private type, object
18454 declarations for the private type that are default initialized, and
18456 parameters and returned result on return from any primitive operation for
18457 the type that is visible to a client.
18460 RM References: 13.03.03 (00)
18463 @emph{AI-0078 Relax Unchecked_Conversion alignment rules (0000-00-00)}
18464 @cindex AI-0078 (Ada 2012 feature)
18467 In Ada 2012, compilers are required to support unchecked conversion where the
18468 target alignment is a multiple of the source alignment. GNAT always supported
18469 this case (and indeed all cases of differing alignments, doing copies where
18470 required if the alignment was reduced).
18473 RM References: 13.09 (7)
18477 @emph{AI-0195 Invalid value handling is implementation defined (2010-07-03)}
18478 @cindex AI-0195 (Ada 2012 feature)
18481 The handling of invalid values is now designated to be implementation
18482 defined. This is a documentation change only, requiring Annex M in the GNAT
18483 Reference Manual to document this handling.
18484 In GNAT, checks for invalid values are made
18485 only when necessary to avoid erroneous behavior. Operations like assignments
18486 which cannot cause erroneous behavior ignore the possibility of invalid
18487 values and do not do a check. The date given above applies only to the
18488 documentation change, this behavior has always been implemented by GNAT.
18491 RM References: 13.09.01 (10)
18494 @emph{AI-0193 Alignment of allocators (2010-09-16)}
18495 @cindex AI-0193 (Ada 2012 feature)
18498 This AI introduces a new attribute @code{Max_Alignment_For_Allocation},
18499 analogous to @code{Max_Size_In_Storage_Elements}, but for alignment instead
18503 RM References: 13.11 (16) 13.11 (21) 13.11.01 (0) 13.11.01 (1)
18504 13.11.01 (2) 13.11.01 (3)
18508 @emph{AI-0177 Parameterized expressions (2010-07-10)}
18509 @cindex AI-0177 (Ada 2012 feature)
18512 The new Ada 2012 notion of parameterized expressions is implemented. The form
18515 @i{function specification} @b{is} (@i{expression})
18519 This is exactly equivalent to the
18520 corresponding function body that returns the expression, but it can appear
18521 in a package spec. Note that the expression must be parenthesized.
18524 RM References: 13.11.01 (3/2)
18527 @emph{AI-0033 Attach/Interrupt_Handler in generic (2010-07-24)}
18528 @cindex AI-0033 (Ada 2012 feature)
18531 Neither of these two pragmas may appear within a generic template, because
18532 the generic might be instantiated at other than the library level.
18535 RM References: 13.11.02 (16) C.03.01 (7/2) C.03.01 (8/2)
18539 @emph{AI-0161 Restriction No_Default_Stream_Attributes (2010-09-11)}
18540 @cindex AI-0161 (Ada 2012 feature)
18543 A new restriction @code{No_Default_Stream_Attributes} prevents the use of any
18544 of the default stream attributes for elementary types. If this restriction is
18545 in force, then it is necessary to provide explicit subprograms for any
18546 stream attributes used.
18549 RM References: 13.12.01 (4/2) 13.13.02 (40/2) 13.13.02 (52/2)
18552 @emph{AI-0194 Value of Stream_Size attribute (0000-00-00)}
18553 @cindex AI-0194 (Ada 2012 feature)
18556 The @code{Stream_Size} attribute returns the default number of bits in the
18557 stream representation of the given type.
18558 This value is not affected by the presence
18559 of stream subprogram attributes for the type. GNAT has always implemented
18560 this interpretation.
18563 RM References: 13.13.02 (1.2/2)
18566 @emph{AI-0109 Redundant check in S'Class'Input (0000-00-00)}
18567 @cindex AI-0109 (Ada 2012 feature)
18570 This AI is an editorial change only. It removes the need for a tag check
18571 that can never fail.
18574 RM References: 13.13.02 (34/2)
18577 @emph{AI-0007 Stream read and private scalar types (0000-00-00)}
18578 @cindex AI-0007 (Ada 2012 feature)
18581 The RM as written appeared to limit the possibilities of declaring read
18582 attribute procedures for private scalar types. This limitation was not
18583 intended, and has never been enforced by GNAT.
18586 RM References: 13.13.02 (50/2) 13.13.02 (51/2)
18590 @emph{AI-0065 Remote access types and external streaming (0000-00-00)}
18591 @cindex AI-0065 (Ada 2012 feature)
18594 This AI clarifies the fact that all remote access types support external
18595 streaming. This fixes an obvious oversight in the definition of the
18596 language, and GNAT always implemented the intended correct rules.
18599 RM References: 13.13.02 (52/2)
18602 @emph{AI-0019 Freezing of primitives for tagged types (0000-00-00)}
18603 @cindex AI-0019 (Ada 2012 feature)
18606 The RM suggests that primitive subprograms of a specific tagged type are
18607 frozen when the tagged type is frozen. This would be an incompatible change
18608 and is not intended. GNAT has never attempted this kind of freezing and its
18609 behavior is consistent with the recommendation of this AI.
18612 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)
18615 @emph{AI-0017 Freezing and incomplete types (0000-00-00)}
18616 @cindex AI-0017 (Ada 2012 feature)
18619 So-called ``Taft-amendment types'' (i.e., types that are completed in package
18620 bodies) are not frozen by the occurrence of bodies in the
18621 enclosing declarative part. GNAT always implemented this properly.
18624 RM References: 13.14 (3/1)
18628 @emph{AI-0060 Extended definition of remote access types (0000-00-00)}
18629 @cindex AI-0060 (Ada 2012 feature)
18632 This AI extends the definition of remote access types to include access
18633 to limited, synchronized, protected or task class-wide interface types.
18634 GNAT already implemented this extension.
18637 RM References: A (4) E.02.02 (9/1) E.02.02 (9.2/1) E.02.02 (14/2) E.02.02 (18)
18640 @emph{AI-0114 Classification of letters (0000-00-00)}
18641 @cindex AI-0114 (Ada 2012 feature)
18644 The code points 170 (@code{FEMININE ORDINAL INDICATOR}),
18645 181 (@code{MICRO SIGN}), and
18646 186 (@code{MASCULINE ORDINAL INDICATOR}) are technically considered
18647 lower case letters by Unicode.
18648 However, they are not allowed in identifiers, and they
18649 return @code{False} to @code{Ada.Characters.Handling.Is_Letter/Is_Lower}.
18650 This behavior is consistent with that defined in Ada 95.
18653 RM References: A.03.02 (59) A.04.06 (7)
18657 @emph{AI-0185 Ada.Wide_[Wide_]Characters.Handling (2010-07-06)}
18658 @cindex AI-0185 (Ada 2012 feature)
18661 Two new packages @code{Ada.Wide_[Wide_]Characters.Handling} provide
18662 classification functions for @code{Wide_Character} and
18663 @code{Wide_Wide_Character}, as well as providing
18664 case folding routines for @code{Wide_[Wide_]Character} and
18665 @code{Wide_[Wide_]String}.
18668 RM References: A.03.05 (0) A.03.06 (0)
18672 @emph{AI-0031 Add From parameter to Find_Token (2010-07-25)}
18673 @cindex AI-0031 (Ada 2012 feature)
18676 A new version of @code{Find_Token} is added to all relevant string packages,
18677 with an extra parameter @code{From}. Instead of starting at the first
18678 character of the string, the search for a matching Token starts at the
18679 character indexed by the value of @code{From}.
18680 These procedures are available in all versions of Ada
18681 but if used in versions earlier than Ada 2012 they will generate a warning
18682 that an Ada 2012 subprogram is being used.
18685 RM References: A.04.03 (16) A.04.03 (67) A.04.03 (68/1) A.04.04 (51)
18690 @emph{AI-0056 Index on null string returns zero (0000-00-00)}
18691 @cindex AI-0056 (Ada 2012 feature)
18694 The wording in the Ada 2005 RM implied an incompatible handling of the
18695 @code{Index} functions, resulting in raising an exception instead of
18696 returning zero in some situations.
18697 This was not intended and has been corrected.
18698 GNAT always returned zero, and is thus consistent with this AI.
18701 RM References: A.04.03 (56.2/2) A.04.03 (58.5/2)
18705 @emph{AI-0137 String encoding package (2010-03-25)}
18706 @cindex AI-0137 (Ada 2012 feature)
18709 The packages @code{Ada.Strings.UTF_Encoding}, together with its child
18710 packages, @code{Conversions}, @code{Strings}, @code{Wide_Strings},
18711 and @code{Wide_Wide_Strings} have been
18712 implemented. These packages (whose documentation can be found in the spec
18713 files @file{a-stuten.ads}, @file{a-suenco.ads}, @file{a-suenst.ads},
18714 @file{a-suewst.ads}, @file{a-suezst.ads}) allow encoding and decoding of
18715 @code{String}, @code{Wide_String}, and @code{Wide_Wide_String}
18716 values using UTF coding schemes (including UTF-8, UTF-16LE, UTF-16BE, and
18717 UTF-16), as well as conversions between the different UTF encodings. With
18718 the exception of @code{Wide_Wide_Strings}, these packages are available in
18719 Ada 95 and Ada 2005 mode as well as Ada 2012 mode.
18720 The @code{Wide_Wide_Strings package}
18721 is available in Ada 2005 mode as well as Ada 2012 mode (but not in Ada 95
18722 mode since it uses @code{Wide_Wide_Character}).
18725 RM References: A.04.11
18728 @emph{AI-0038 Minor errors in Text_IO (0000-00-00)}
18729 @cindex AI-0038 (Ada 2012 feature)
18732 These are minor errors in the description on three points. The intent on
18733 all these points has always been clear, and GNAT has always implemented the
18734 correct intended semantics.
18737 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)
18740 @emph{AI-0044 Restrictions on container instantiations (0000-00-00)}
18741 @cindex AI-0044 (Ada 2012 feature)
18744 This AI places restrictions on allowed instantiations of generic containers.
18745 These restrictions are not checked by the compiler, so there is nothing to
18746 change in the implementation. This affects only the RM documentation.
18749 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)
18752 @emph{AI-0127 Adding Locale Capabilities (2010-09-29)}
18753 @cindex AI-0127 (Ada 2012 feature)
18756 This package provides an interface for identifying the current locale.
18759 RM References: A.19 A.19.01 A.19.02 A.19.03 A.19.05 A.19.06
18760 A.19.07 A.19.08 A.19.09 A.19.10 A.19.11 A.19.12 A.19.13
18765 @emph{AI-0002 Export C with unconstrained arrays (0000-00-00)}
18766 @cindex AI-0002 (Ada 2012 feature)
18769 The compiler is not required to support exporting an Ada subprogram with
18770 convention C if there are parameters or a return type of an unconstrained
18771 array type (such as @code{String}). GNAT allows such declarations but
18772 generates warnings. It is possible, but complicated, to write the
18773 corresponding C code and certainly such code would be specific to GNAT and
18777 RM References: B.01 (17) B.03 (62) B.03 (71.1/2)
18781 @emph{AI-0216 No_Task_Hierarchy forbids local tasks (0000-00-00)}
18782 @cindex AI05-0216 (Ada 2012 feature)
18785 It is clearly the intention that @code{No_Task_Hierarchy} is intended to
18786 forbid tasks declared locally within subprograms, or functions returning task
18787 objects, and that is the implementation that GNAT has always provided.
18788 However the language in the RM was not sufficiently clear on this point.
18789 Thus this is a documentation change in the RM only.
18792 RM References: D.07 (3/3)
18795 @emph{AI-0211 No_Relative_Delays forbids Set_Handler use (2010-07-09)}
18796 @cindex AI-0211 (Ada 2012 feature)
18799 The restriction @code{No_Relative_Delays} forbids any calls to the subprogram
18800 @code{Ada.Real_Time.Timing_Events.Set_Handler}.
18803 RM References: D.07 (5) D.07 (10/2) D.07 (10.4/2) D.07 (10.7/2)
18806 @emph{AI-0190 pragma Default_Storage_Pool (2010-09-15)}
18807 @cindex AI-0190 (Ada 2012 feature)
18810 This AI introduces a new pragma @code{Default_Storage_Pool}, which can be
18811 used to control storage pools globally.
18812 In particular, you can force every access
18813 type that is used for allocation (@b{new}) to have an explicit storage pool,
18814 or you can declare a pool globally to be used for all access types that lack
18818 RM References: D.07 (8)
18821 @emph{AI-0189 No_Allocators_After_Elaboration (2010-01-23)}
18822 @cindex AI-0189 (Ada 2012 feature)
18825 This AI introduces a new restriction @code{No_Allocators_After_Elaboration},
18826 which says that no dynamic allocation will occur once elaboration is
18828 In general this requires a run-time check, which is not required, and which
18829 GNAT does not attempt. But the static cases of allocators in a task body or
18830 in the body of the main program are detected and flagged at compile or bind
18834 RM References: D.07 (19.1/2) H.04 (23.3/2)
18837 @emph{AI-0171 Pragma CPU and Ravenscar Profile (2010-09-24)}
18838 @cindex AI-0171 (Ada 2012 feature)
18841 A new package @code{System.Multiprocessors} is added, together with the
18842 definition of pragma @code{CPU} for controlling task affinity. A new no
18843 dependence restriction, on @code{System.Multiprocessors.Dispatching_Domains},
18844 is added to the Ravenscar profile.
18847 RM References: D.13.01 (4/2) D.16
18851 @emph{AI-0210 Correct Timing_Events metric (0000-00-00)}
18852 @cindex AI-0210 (Ada 2012 feature)
18855 This is a documentation only issue regarding wording of metric requirements,
18856 that does not affect the implementation of the compiler.
18859 RM References: D.15 (24/2)
18863 @emph{AI-0206 Remote types packages and preelaborate (2010-07-24)}
18864 @cindex AI-0206 (Ada 2012 feature)
18867 Remote types packages are now allowed to depend on preelaborated packages.
18868 This was formerly considered illegal.
18871 RM References: E.02.02 (6)
18876 @emph{AI-0152 Restriction No_Anonymous_Allocators (2010-09-08)}
18877 @cindex AI-0152 (Ada 2012 feature)
18880 Restriction @code{No_Anonymous_Allocators} prevents the use of allocators
18881 where the type of the returned value is an anonymous access type.
18884 RM References: H.04 (8/1)
18888 @node Obsolescent Features
18889 @chapter Obsolescent Features
18892 This chapter describes features that are provided by GNAT, but are
18893 considered obsolescent since there are preferred ways of achieving
18894 the same effect. These features are provided solely for historical
18895 compatibility purposes.
18898 * pragma No_Run_Time::
18899 * pragma Ravenscar::
18900 * pragma Restricted_Run_Time::
18903 @node pragma No_Run_Time
18904 @section pragma No_Run_Time
18906 The pragma @code{No_Run_Time} is used to achieve an affect similar
18907 to the use of the "Zero Foot Print" configurable run time, but without
18908 requiring a specially configured run time. The result of using this
18909 pragma, which must be used for all units in a partition, is to restrict
18910 the use of any language features requiring run-time support code. The
18911 preferred usage is to use an appropriately configured run-time that
18912 includes just those features that are to be made accessible.
18914 @node pragma Ravenscar
18915 @section pragma Ravenscar
18917 The pragma @code{Ravenscar} has exactly the same effect as pragma
18918 @code{Profile (Ravenscar)}. The latter usage is preferred since it
18919 is part of the new Ada 2005 standard.
18921 @node pragma Restricted_Run_Time
18922 @section pragma Restricted_Run_Time
18924 The pragma @code{Restricted_Run_Time} has exactly the same effect as
18925 pragma @code{Profile (Restricted)}. The latter usage is
18926 preferred since the Ada 2005 pragma @code{Profile} is intended for
18927 this kind of implementation dependent addition.
18930 @c GNU Free Documentation License
18932 @node Index,,GNU Free Documentation License, Top