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.2 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 Advice::
75 * Implementation Defined Characteristics::
76 * Intrinsic Subprograms::
77 * Representation Clauses and Pragmas::
78 * Standard Library Routines::
79 * The Implementation of Standard I/O::
81 * Interfacing to Other Languages::
82 * Specialized Needs Annexes::
83 * Implementation of Specific Ada Features::
84 * Project File Reference::
85 * Obsolescent Features::
86 * GNU Free Documentation License::
89 --- The Detailed Node Listing ---
93 * What This Reference Manual Contains::
94 * Related Information::
96 Implementation Defined Pragmas
98 * Pragma Abort_Defer::
105 * Pragma Assume_No_Invalid_Values::
107 * Pragma C_Pass_By_Copy::
109 * Pragma Check_Name::
110 * Pragma Check_Policy::
112 * Pragma Common_Object::
113 * Pragma Compile_Time_Error::
114 * Pragma Compile_Time_Warning::
115 * Pragma Compiler_Unit::
116 * Pragma Complete_Representation::
117 * Pragma Complex_Representation::
118 * Pragma Component_Alignment::
119 * Pragma Convention_Identifier::
121 * Pragma CPP_Constructor::
122 * Pragma CPP_Virtual::
123 * Pragma CPP_Vtable::
125 * Pragma Debug_Policy::
126 * Pragma Detect_Blocking::
127 * Pragma Elaboration_Checks::
129 * Pragma Export_Exception::
130 * Pragma Export_Function::
131 * Pragma Export_Object::
132 * Pragma Export_Procedure::
133 * Pragma Export_Value::
134 * Pragma Export_Valued_Procedure::
135 * Pragma Extend_System::
137 * Pragma External_Name_Casing::
139 * Pragma Favor_Top_Level::
140 * Pragma Finalize_Storage_Only::
141 * Pragma Float_Representation::
143 * Pragma Implemented_By_Entry::
144 * Pragma Implicit_Packing::
145 * Pragma Import_Exception::
146 * Pragma Import_Function::
147 * Pragma Import_Object::
148 * Pragma Import_Procedure::
149 * Pragma Import_Valued_Procedure::
150 * Pragma Initialize_Scalars::
151 * Pragma Inline_Always::
152 * Pragma Inline_Generic::
154 * Pragma Interface_Name::
155 * Pragma Interrupt_Handler::
156 * Pragma Interrupt_State::
157 * Pragma Keep_Names::
160 * Pragma Linker_Alias::
161 * Pragma Linker_Constructor::
162 * Pragma Linker_Destructor::
163 * Pragma Linker_Section::
164 * Pragma Long_Float::
165 * Pragma Machine_Attribute::
167 * Pragma Main_Storage::
170 * Pragma No_Strict_Aliasing ::
171 * Pragma Normalize_Scalars::
172 * Pragma Obsolescent::
173 * Pragma Optimize_Alignment::
175 * Pragma Persistent_BSS::
177 * Pragma Postcondition::
178 * Pragma Precondition::
179 * Pragma Profile (Ravenscar)::
180 * Pragma Profile (Restricted)::
181 * Pragma Psect_Object::
182 * Pragma Pure_Function::
183 * Pragma Restriction_Warnings::
185 * Pragma Source_File_Name::
186 * Pragma Source_File_Name_Project::
187 * Pragma Source_Reference::
188 * Pragma Stream_Convert::
189 * Pragma Style_Checks::
192 * Pragma Suppress_All::
193 * Pragma Suppress_Exception_Locations::
194 * Pragma Suppress_Initialization::
197 * Pragma Task_Storage::
198 * Pragma Thread_Local_Storage::
199 * Pragma Time_Slice::
201 * Pragma Unchecked_Union::
202 * Pragma Unimplemented_Unit::
203 * Pragma Universal_Aliasing ::
204 * Pragma Universal_Data::
205 * Pragma Unmodified::
206 * Pragma Unreferenced::
207 * Pragma Unreferenced_Objects::
208 * Pragma Unreserve_All_Interrupts::
209 * Pragma Unsuppress::
210 * Pragma Use_VADS_Size::
211 * Pragma Validity_Checks::
214 * Pragma Weak_External::
215 * Pragma Wide_Character_Encoding::
217 Implementation Defined Attributes
228 * Default_Bit_Order::
238 * Has_Access_Values::
239 * Has_Discriminants::
246 * Max_Interrupt_Priority::
248 * Maximum_Alignment::
253 * Passed_By_Reference::
266 * Unconstrained_Array::
267 * Universal_Literal_String::
268 * Unrestricted_Access::
274 The Implementation of Standard I/O
276 * Standard I/O Packages::
282 * Wide_Wide_Text_IO::
286 * Filenames encoding::
288 * Operations on C Streams::
289 * Interfacing to C Streams::
293 * Ada.Characters.Latin_9 (a-chlat9.ads)::
294 * Ada.Characters.Wide_Latin_1 (a-cwila1.ads)::
295 * Ada.Characters.Wide_Latin_9 (a-cwila9.ads)::
296 * Ada.Characters.Wide_Wide_Latin_1 (a-chzla1.ads)::
297 * Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads)::
298 * Ada.Command_Line.Environment (a-colien.ads)::
299 * Ada.Command_Line.Remove (a-colire.ads)::
300 * Ada.Command_Line.Response_File (a-clrefi.ads)::
301 * Ada.Direct_IO.C_Streams (a-diocst.ads)::
302 * Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads)::
303 * Ada.Exceptions.Last_Chance_Handler (a-elchha.ads)::
304 * Ada.Exceptions.Traceback (a-exctra.ads)::
305 * Ada.Sequential_IO.C_Streams (a-siocst.ads)::
306 * Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads)::
307 * Ada.Strings.Unbounded.Text_IO (a-suteio.ads)::
308 * Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads)::
309 * Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads)::
310 * Ada.Text_IO.C_Streams (a-tiocst.ads)::
311 * Ada.Text_IO.Reset_Standard_Files (a-tirsfi.ads)::
312 * Ada.Wide_Characters.Unicode (a-wichun.ads)::
313 * Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads)::
314 * Ada.Wide_Text_IO.Reset_Standard_Files (a-wrstfi.ads)::
315 * Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads)::
316 * Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads)::
317 * Ada.Wide_Wide_Text_IO.Reset_Standard_Files (a-zrstfi.ads)::
318 * GNAT.Altivec (g-altive.ads)::
319 * GNAT.Altivec.Conversions (g-altcon.ads)::
320 * GNAT.Altivec.Vector_Operations (g-alveop.ads)::
321 * GNAT.Altivec.Vector_Types (g-alvety.ads)::
322 * GNAT.Altivec.Vector_Views (g-alvevi.ads)::
323 * GNAT.Array_Split (g-arrspl.ads)::
324 * GNAT.AWK (g-awk.ads)::
325 * GNAT.Bounded_Buffers (g-boubuf.ads)::
326 * GNAT.Bounded_Mailboxes (g-boumai.ads)::
327 * GNAT.Bubble_Sort (g-bubsor.ads)::
328 * GNAT.Bubble_Sort_A (g-busora.ads)::
329 * GNAT.Bubble_Sort_G (g-busorg.ads)::
330 * GNAT.Byte_Order_Mark (g-byorma.ads)::
331 * GNAT.Byte_Swapping (g-bytswa.ads)::
332 * GNAT.Calendar (g-calend.ads)::
333 * GNAT.Calendar.Time_IO (g-catiio.ads)::
334 * GNAT.Case_Util (g-casuti.ads)::
335 * GNAT.CGI (g-cgi.ads)::
336 * GNAT.CGI.Cookie (g-cgicoo.ads)::
337 * GNAT.CGI.Debug (g-cgideb.ads)::
338 * GNAT.Command_Line (g-comlin.ads)::
339 * GNAT.Compiler_Version (g-comver.ads)::
340 * GNAT.Ctrl_C (g-ctrl_c.ads)::
341 * GNAT.CRC32 (g-crc32.ads)::
342 * GNAT.Current_Exception (g-curexc.ads)::
343 * GNAT.Debug_Pools (g-debpoo.ads)::
344 * GNAT.Debug_Utilities (g-debuti.ads)::
345 * GNAT.Decode_String (g-decstr.ads)::
346 * GNAT.Decode_UTF8_String (g-deutst.ads)::
347 * GNAT.Directory_Operations (g-dirope.ads)::
348 * GNAT.Directory_Operations.Iteration (g-diopit.ads)::
349 * GNAT.Dynamic_HTables (g-dynhta.ads)::
350 * GNAT.Dynamic_Tables (g-dyntab.ads)::
351 * GNAT.Encode_String (g-encstr.ads)::
352 * GNAT.Encode_UTF8_String (g-enutst.ads)::
353 * GNAT.Exception_Actions (g-excact.ads)::
354 * GNAT.Exception_Traces (g-exctra.ads)::
355 * GNAT.Exceptions (g-except.ads)::
356 * GNAT.Expect (g-expect.ads)::
357 * GNAT.Float_Control (g-flocon.ads)::
358 * GNAT.Heap_Sort (g-heasor.ads)::
359 * GNAT.Heap_Sort_A (g-hesora.ads)::
360 * GNAT.Heap_Sort_G (g-hesorg.ads)::
361 * GNAT.HTable (g-htable.ads)::
362 * GNAT.IO (g-io.ads)::
363 * GNAT.IO_Aux (g-io_aux.ads)::
364 * GNAT.Lock_Files (g-locfil.ads)::
365 * GNAT.MD5 (g-md5.ads)::
366 * GNAT.Memory_Dump (g-memdum.ads)::
367 * GNAT.Most_Recent_Exception (g-moreex.ads)::
368 * GNAT.OS_Lib (g-os_lib.ads)::
369 * GNAT.Perfect_Hash_Generators (g-pehage.ads)::
370 * GNAT.Random_Numbers (g-rannum.ads)::
371 * GNAT.Regexp (g-regexp.ads)::
372 * GNAT.Registry (g-regist.ads)::
373 * GNAT.Regpat (g-regpat.ads)::
374 * GNAT.Secondary_Stack_Info (g-sestin.ads)::
375 * GNAT.Semaphores (g-semaph.ads)::
376 * GNAT.Serial_Communications (g-sercom.ads)::
377 * GNAT.SHA1 (g-sha1.ads)::
378 * GNAT.Signals (g-signal.ads)::
379 * GNAT.Sockets (g-socket.ads)::
380 * GNAT.Source_Info (g-souinf.ads)::
381 * GNAT.Spelling_Checker (g-speche.ads)::
382 * GNAT.Spelling_Checker_Generic (g-spchge.ads)::
383 * GNAT.Spitbol.Patterns (g-spipat.ads)::
384 * GNAT.Spitbol (g-spitbo.ads)::
385 * GNAT.Spitbol.Table_Boolean (g-sptabo.ads)::
386 * GNAT.Spitbol.Table_Integer (g-sptain.ads)::
387 * GNAT.Spitbol.Table_VString (g-sptavs.ads)::
388 * GNAT.SSE (g-sse.ads)::
389 * GNAT.SSE.Vector_Types (g-ssvety.ads)::
390 * GNAT.Strings (g-string.ads)::
391 * GNAT.String_Split (g-strspl.ads)::
392 * GNAT.Table (g-table.ads)::
393 * GNAT.Task_Lock (g-tasloc.ads)::
394 * GNAT.Threads (g-thread.ads)::
395 * GNAT.Time_Stamp (g-timsta.ads)::
396 * GNAT.Traceback (g-traceb.ads)::
397 * GNAT.Traceback.Symbolic (g-trasym.ads)::
398 * GNAT.UTF_32 (g-utf_32.ads)::
399 * GNAT.UTF_32_Spelling_Checker (g-u3spch.ads)::
400 * GNAT.Wide_Spelling_Checker (g-wispch.ads)::
401 * GNAT.Wide_String_Split (g-wistsp.ads)::
402 * GNAT.Wide_Wide_Spelling_Checker (g-zspche.ads)::
403 * GNAT.Wide_Wide_String_Split (g-zistsp.ads)::
404 * Interfaces.C.Extensions (i-cexten.ads)::
405 * Interfaces.C.Streams (i-cstrea.ads)::
406 * Interfaces.CPP (i-cpp.ads)::
407 * Interfaces.Packed_Decimal (i-pacdec.ads)::
408 * Interfaces.VxWorks (i-vxwork.ads)::
409 * Interfaces.VxWorks.IO (i-vxwoio.ads)::
410 * System.Address_Image (s-addima.ads)::
411 * System.Assertions (s-assert.ads)::
412 * System.Memory (s-memory.ads)::
413 * System.Partition_Interface (s-parint.ads)::
414 * System.Pool_Global (s-pooglo.ads)::
415 * System.Pool_Local (s-pooloc.ads)::
416 * System.Restrictions (s-restri.ads)::
417 * System.Rident (s-rident.ads)::
418 * System.Strings.Stream_Ops (s-ststop.ads)::
419 * System.Task_Info (s-tasinf.ads)::
420 * System.Wch_Cnv (s-wchcnv.ads)::
421 * System.Wch_Con (s-wchcon.ads)::
425 * Text_IO Stream Pointer Positioning::
426 * Text_IO Reading and Writing Non-Regular Files::
428 * Treating Text_IO Files as Streams::
429 * Text_IO Extensions::
430 * Text_IO Facilities for Unbounded Strings::
434 * Wide_Text_IO Stream Pointer Positioning::
435 * Wide_Text_IO Reading and Writing Non-Regular Files::
439 * Wide_Wide_Text_IO Stream Pointer Positioning::
440 * Wide_Wide_Text_IO Reading and Writing Non-Regular Files::
442 Interfacing to Other Languages
445 * Interfacing to C++::
446 * Interfacing to COBOL::
447 * Interfacing to Fortran::
448 * Interfacing to non-GNAT Ada code::
450 Specialized Needs Annexes
452 Implementation of Specific Ada Features
453 * Machine Code Insertions::
454 * GNAT Implementation of Tasking::
455 * GNAT Implementation of Shared Passive Packages::
456 * Code Generation for Array Aggregates::
457 * The Size of Discriminated Records with Default Discriminants::
458 * Strict Conformance to the Ada Reference Manual::
460 Project File Reference
464 GNU Free Documentation License
471 @node About This Guide
472 @unnumbered About This Guide
475 This manual contains useful information in writing programs using the
476 @value{EDITION} compiler. It includes information on implementation dependent
477 characteristics of @value{EDITION}, including all the information required by
478 Annex M of the Ada language standard.
480 @value{EDITION} implements Ada 95 and Ada 2005, and it may also be invoked in
481 Ada 83 compatibility mode.
482 By default, @value{EDITION} assumes @value{DEFAULTLANGUAGEVERSION},
483 but you can override with a compiler switch
484 to explicitly specify the language version.
485 (Please refer to @ref{Compiling Different Versions of Ada,,, gnat_ugn,
486 @value{EDITION} User's Guide}, for details on these switches.)
487 Throughout this manual, references to ``Ada'' without a year suffix
488 apply to both the Ada 95 and Ada 2005 versions of the language.
490 Ada is designed to be highly portable.
491 In general, a program will have the same effect even when compiled by
492 different compilers on different platforms.
493 However, since Ada is designed to be used in a
494 wide variety of applications, it also contains a number of system
495 dependent features to be used in interfacing to the external world.
496 @cindex Implementation-dependent features
499 Note: Any program that makes use of implementation-dependent features
500 may be non-portable. You should follow good programming practice and
501 isolate and clearly document any sections of your program that make use
502 of these features in a non-portable manner.
505 For ease of exposition, ``GNAT Pro'' will be referred to simply as
506 ``GNAT'' in the remainder of this document.
510 * What This Reference Manual Contains::
512 * Related Information::
515 @node What This Reference Manual Contains
516 @unnumberedsec What This Reference Manual Contains
519 This reference manual contains the following chapters:
523 @ref{Implementation Defined Pragmas}, lists GNAT implementation-dependent
524 pragmas, which can be used to extend and enhance the functionality of the
528 @ref{Implementation Defined Attributes}, lists GNAT
529 implementation-dependent attributes which can be used to extend and
530 enhance the functionality of the compiler.
533 @ref{Implementation Advice}, provides information on generally
534 desirable behavior which are not requirements that all compilers must
535 follow since it cannot be provided on all systems, or which may be
536 undesirable on some systems.
539 @ref{Implementation Defined Characteristics}, provides a guide to
540 minimizing implementation dependent features.
543 @ref{Intrinsic Subprograms}, describes the intrinsic subprograms
544 implemented by GNAT, and how they can be imported into user
545 application programs.
548 @ref{Representation Clauses and Pragmas}, describes in detail the
549 way that GNAT represents data, and in particular the exact set
550 of representation clauses and pragmas that is accepted.
553 @ref{Standard Library Routines}, provides a listing of packages and a
554 brief description of the functionality that is provided by Ada's
555 extensive set of standard library routines as implemented by GNAT@.
558 @ref{The Implementation of Standard I/O}, details how the GNAT
559 implementation of the input-output facilities.
562 @ref{The GNAT Library}, is a catalog of packages that complement
563 the Ada predefined library.
566 @ref{Interfacing to Other Languages}, describes how programs
567 written in Ada using GNAT can be interfaced to other programming
570 @ref{Specialized Needs Annexes}, describes the GNAT implementation of all
571 of the specialized needs annexes.
574 @ref{Implementation of Specific Ada Features}, discusses issues related
575 to GNAT's implementation of machine code insertions, tasking, and several
579 @ref{Project File Reference}, presents the syntax and semantics
583 @ref{Obsolescent Features} documents implementation dependent features,
584 including pragmas and attributes, which are considered obsolescent, since
585 there are other preferred ways of achieving the same results. These
586 obsolescent forms are retained for backwards compatibility.
590 @cindex Ada 95 Language Reference Manual
591 @cindex Ada 2005 Language Reference Manual
593 This reference manual assumes a basic familiarity with the Ada 95 language, as
594 described in the International Standard ANSI/ISO/IEC-8652:1995,
596 It does not require knowledge of the new features introduced by Ada 2005,
597 (officially known as ISO/IEC 8652:1995 with Technical Corrigendum 1
599 Both reference manuals are included in the GNAT documentation
603 @unnumberedsec Conventions
604 @cindex Conventions, typographical
605 @cindex Typographical conventions
608 Following are examples of the typographical and graphic conventions used
613 @code{Functions}, @code{utility program names}, @code{standard names},
620 @file{File names}, @samp{button names}, and @samp{field names}.
623 @code{Variables}, @env{environment variables}, and @var{metasyntactic
630 [optional information or parameters]
633 Examples are described by text
635 and then shown this way.
640 Commands that are entered by the user are preceded in this manual by the
641 characters @samp{$ } (dollar sign followed by space). If your system uses this
642 sequence as a prompt, then the commands will appear exactly as you see them
643 in the manual. If your system uses some other prompt, then the command will
644 appear with the @samp{$} replaced by whatever prompt character you are using.
646 @node Related Information
647 @unnumberedsec Related Information
649 See the following documents for further information on GNAT:
653 @xref{Top, @value{EDITION} User's Guide, About This Guide, gnat_ugn,
654 @value{EDITION} User's Guide}, which provides information on how to use the
655 GNAT compiler system.
658 @cite{Ada 95 Reference Manual}, which contains all reference
659 material for the Ada 95 programming language.
662 @cite{Ada 95 Annotated Reference Manual}, which is an annotated version
663 of the Ada 95 standard. The annotations describe
664 detailed aspects of the design decision, and in particular contain useful
665 sections on Ada 83 compatibility.
668 @cite{Ada 2005 Reference Manual}, which contains all reference
669 material for the Ada 2005 programming language.
672 @cite{Ada 2005 Annotated Reference Manual}, which is an annotated version
673 of the Ada 2005 standard. The annotations describe
674 detailed aspects of the design decision, and in particular contain useful
675 sections on Ada 83 and Ada 95 compatibility.
678 @cite{DEC Ada, Technical Overview and Comparison on DIGITAL Platforms},
679 which contains specific information on compatibility between GNAT and
683 @cite{DEC Ada, Language Reference Manual, part number AA-PYZAB-TK} which
684 describes in detail the pragmas and attributes provided by the DEC Ada 83
689 @node Implementation Defined Pragmas
690 @chapter Implementation Defined Pragmas
693 Ada defines a set of pragmas that can be used to supply additional
694 information to the compiler. These language defined pragmas are
695 implemented in GNAT and work as described in the Ada Reference Manual.
697 In addition, Ada allows implementations to define additional pragmas
698 whose meaning is defined by the implementation. GNAT provides a number
699 of these implementation-defined pragmas, which can be used to extend
700 and enhance the functionality of the compiler. This section of the GNAT
701 Reference Manual describes these additional pragmas.
703 Note that any program using these pragmas might not be portable to other
704 compilers (although GNAT implements this set of pragmas on all
705 platforms). Therefore if portability to other compilers is an important
706 consideration, the use of these pragmas should be minimized.
709 * Pragma Abort_Defer::
716 * Pragma Assume_No_Invalid_Values::
718 * Pragma C_Pass_By_Copy::
720 * Pragma Check_Name::
721 * Pragma Check_Policy::
723 * Pragma Common_Object::
724 * Pragma Compile_Time_Error::
725 * Pragma Compile_Time_Warning::
726 * Pragma Compiler_Unit::
727 * Pragma Complete_Representation::
728 * Pragma Complex_Representation::
729 * Pragma Component_Alignment::
730 * Pragma Convention_Identifier::
732 * Pragma CPP_Constructor::
733 * Pragma CPP_Virtual::
734 * Pragma CPP_Vtable::
736 * Pragma Debug_Policy::
737 * Pragma Detect_Blocking::
738 * Pragma Elaboration_Checks::
740 * Pragma Export_Exception::
741 * Pragma Export_Function::
742 * Pragma Export_Object::
743 * Pragma Export_Procedure::
744 * Pragma Export_Value::
745 * Pragma Export_Valued_Procedure::
746 * Pragma Extend_System::
748 * Pragma External_Name_Casing::
750 * Pragma Favor_Top_Level::
751 * Pragma Finalize_Storage_Only::
752 * Pragma Float_Representation::
754 * Pragma Implemented_By_Entry::
755 * Pragma Implicit_Packing::
756 * Pragma Import_Exception::
757 * Pragma Import_Function::
758 * Pragma Import_Object::
759 * Pragma Import_Procedure::
760 * Pragma Import_Valued_Procedure::
761 * Pragma Initialize_Scalars::
762 * Pragma Inline_Always::
763 * Pragma Inline_Generic::
765 * Pragma Interface_Name::
766 * Pragma Interrupt_Handler::
767 * Pragma Interrupt_State::
768 * Pragma Keep_Names::
771 * Pragma Linker_Alias::
772 * Pragma Linker_Constructor::
773 * Pragma Linker_Destructor::
774 * Pragma Linker_Section::
775 * Pragma Long_Float::
776 * Pragma Machine_Attribute::
778 * Pragma Main_Storage::
781 * Pragma No_Strict_Aliasing::
782 * Pragma Normalize_Scalars::
783 * Pragma Obsolescent::
784 * Pragma Optimize_Alignment::
786 * Pragma Persistent_BSS::
788 * Pragma Postcondition::
789 * Pragma Precondition::
790 * Pragma Profile (Ravenscar)::
791 * Pragma Profile (Restricted)::
792 * Pragma Psect_Object::
793 * Pragma Pure_Function::
794 * Pragma Restriction_Warnings::
796 * Pragma Source_File_Name::
797 * Pragma Source_File_Name_Project::
798 * Pragma Source_Reference::
799 * Pragma Stream_Convert::
800 * Pragma Style_Checks::
803 * Pragma Suppress_All::
804 * Pragma Suppress_Exception_Locations::
805 * Pragma Suppress_Initialization::
808 * Pragma Task_Storage::
809 * Pragma Thread_Local_Storage::
810 * Pragma Time_Slice::
812 * Pragma Unchecked_Union::
813 * Pragma Unimplemented_Unit::
814 * Pragma Universal_Aliasing ::
815 * Pragma Universal_Data::
816 * Pragma Unmodified::
817 * Pragma Unreferenced::
818 * Pragma Unreferenced_Objects::
819 * Pragma Unreserve_All_Interrupts::
820 * Pragma Unsuppress::
821 * Pragma Use_VADS_Size::
822 * Pragma Validity_Checks::
825 * Pragma Weak_External::
826 * Pragma Wide_Character_Encoding::
829 @node Pragma Abort_Defer
830 @unnumberedsec Pragma Abort_Defer
832 @cindex Deferring aborts
840 This pragma must appear at the start of the statement sequence of a
841 handled sequence of statements (right after the @code{begin}). It has
842 the effect of deferring aborts for the sequence of statements (but not
843 for the declarations or handlers, if any, associated with this statement
847 @unnumberedsec Pragma Ada_83
856 A configuration pragma that establishes Ada 83 mode for the unit to
857 which it applies, regardless of the mode set by the command line
858 switches. In Ada 83 mode, GNAT attempts to be as compatible with
859 the syntax and semantics of Ada 83, as defined in the original Ada
860 83 Reference Manual as possible. In particular, the keywords added by Ada 95
861 and Ada 2005 are not recognized, optional package bodies are allowed,
862 and generics may name types with unknown discriminants without using
863 the @code{(<>)} notation. In addition, some but not all of the additional
864 restrictions of Ada 83 are enforced.
866 Ada 83 mode is intended for two purposes. Firstly, it allows existing
867 Ada 83 code to be compiled and adapted to GNAT with less effort.
868 Secondly, it aids in keeping code backwards compatible with Ada 83.
869 However, there is no guarantee that code that is processed correctly
870 by GNAT in Ada 83 mode will in fact compile and execute with an Ada
871 83 compiler, since GNAT does not enforce all the additional checks
875 @unnumberedsec Pragma Ada_95
884 A configuration pragma that establishes Ada 95 mode for the unit to which
885 it applies, regardless of the mode set by the command line switches.
886 This mode is set automatically for the @code{Ada} and @code{System}
887 packages and their children, so you need not specify it in these
888 contexts. This pragma is useful when writing a reusable component that
889 itself uses Ada 95 features, but which is intended to be usable from
890 either Ada 83 or Ada 95 programs.
893 @unnumberedsec Pragma Ada_05
902 A configuration pragma that establishes Ada 2005 mode for the unit to which
903 it applies, regardless of the mode set by the command line switches.
904 This mode is set automatically for the @code{Ada} and @code{System}
905 packages and their children, so you need not specify it in these
906 contexts. This pragma is useful when writing a reusable component that
907 itself uses Ada 2005 features, but which is intended to be usable from
908 either Ada 83 or Ada 95 programs.
910 @node Pragma Ada_2005
911 @unnumberedsec Pragma Ada_2005
920 This configuration pragma is a synonym for pragma Ada_05 and has the
921 same syntax and effect.
923 @node Pragma Annotate
924 @unnumberedsec Pragma Annotate
929 pragma Annotate (IDENTIFIER @{, ARG@});
931 ARG ::= NAME | EXPRESSION
935 This pragma is used to annotate programs. @var{identifier} identifies
936 the type of annotation. GNAT verifies that it is an identifier, but does
937 not otherwise analyze it. The @var{arg} argument
938 can be either a string literal or an
939 expression. String literals are assumed to be of type
940 @code{Standard.String}. Names of entities are simply analyzed as entity
941 names. All other expressions are analyzed as expressions, and must be
944 The analyzed pragma is retained in the tree, but not otherwise processed
945 by any part of the GNAT compiler. This pragma is intended for use by
946 external tools, including ASIS@.
949 @unnumberedsec Pragma Assert
956 [, string_EXPRESSION]);
960 The effect of this pragma depends on whether the corresponding command
961 line switch is set to activate assertions. The pragma expands into code
962 equivalent to the following:
965 if assertions-enabled then
966 if not boolean_EXPRESSION then
967 System.Assertions.Raise_Assert_Failure
974 The string argument, if given, is the message that will be associated
975 with the exception occurrence if the exception is raised. If no second
976 argument is given, the default message is @samp{@var{file}:@var{nnn}},
977 where @var{file} is the name of the source file containing the assert,
978 and @var{nnn} is the line number of the assert. A pragma is not a
979 statement, so if a statement sequence contains nothing but a pragma
980 assert, then a null statement is required in addition, as in:
985 pragma Assert (K > 3, "Bad value for K");
991 Note that, as with the @code{if} statement to which it is equivalent, the
992 type of the expression is either @code{Standard.Boolean}, or any type derived
993 from this standard type.
995 If assertions are disabled (switch @option{-gnata} not used), then there
996 is no run-time effect (and in particular, any side effects from the
997 expression will not occur at run time). (The expression is still
998 analyzed at compile time, and may cause types to be frozen if they are
999 mentioned here for the first time).
1001 If assertions are enabled, then the given expression is tested, and if
1002 it is @code{False} then @code{System.Assertions.Raise_Assert_Failure} is called
1003 which results in the raising of @code{Assert_Failure} with the given message.
1005 You should generally avoid side effects in the expression arguments of
1006 this pragma, because these side effects will turn on and off with the
1007 setting of the assertions mode, resulting in assertions that have an
1008 effect on the program. However, the expressions are analyzed for
1009 semantic correctness whether or not assertions are enabled, so turning
1010 assertions on and off cannot affect the legality of a program.
1012 @node Pragma Assume_No_Invalid_Values
1013 @unnumberedsec Pragma Assume_No_Invalid_Values
1014 @findex Assume_No_Invalid_Values
1015 @cindex Invalid representations
1016 @cindex Invalid values
1019 @smallexample @c ada
1020 pragma Assume_No_Invalid_Values (On | Off);
1024 This is a configuration pragma that controls the assumptions made by the
1025 compiler about the occurrence of invalid representations (invalid values)
1028 The default behavior (corresponding to an Off argument for this pragma), is
1029 to assume that values may in general be invalid unless the compiler can
1030 prove they are valid. Consider the following example:
1032 @smallexample @c ada
1033 V1 : Integer range 1 .. 10;
1034 V2 : Integer range 11 .. 20;
1036 for J in V2 .. V1 loop
1042 if V1 and V2 have valid values, then the loop is known at compile
1043 time not to execute since the lower bound must be greater than the
1044 upper bound. However in default mode, no such assumption is made,
1045 and the loop may execute. If @code{Assume_No_Invalid_Values (On)}
1046 is given, the compiler will assume that any occurrence of a variable
1047 other than in an explicit @code{'Valid} test always has a valid
1048 value, and the loop above will be optimized away.
1050 The use of @code{Assume_No_Invalid_Values (On)} is appropriate if
1051 you know your code is free of uninitialized variables and other
1052 possible sources of invalid representations, and may result in
1053 more efficient code. A program that accesses an invalid representation
1054 with this pragma in effect is erroneous, so no guarantees can be made
1057 It is peculiar though permissible to use this pragma in conjunction
1058 with validity checking (-gnatVa). In such cases, accessing invalid
1059 values will generally give an exception, though formally the program
1060 is erroneous so there are no guarantees that this will always be the
1061 case, and it is recommended that these two options not be used together.
1063 @node Pragma Ast_Entry
1064 @unnumberedsec Pragma Ast_Entry
1069 @smallexample @c ada
1070 pragma AST_Entry (entry_IDENTIFIER);
1074 This pragma is implemented only in the OpenVMS implementation of GNAT@. The
1075 argument is the simple name of a single entry; at most one @code{AST_Entry}
1076 pragma is allowed for any given entry. This pragma must be used in
1077 conjunction with the @code{AST_Entry} attribute, and is only allowed after
1078 the entry declaration and in the same task type specification or single task
1079 as the entry to which it applies. This pragma specifies that the given entry
1080 may be used to handle an OpenVMS asynchronous system trap (@code{AST})
1081 resulting from an OpenVMS system service call. The pragma does not affect
1082 normal use of the entry. For further details on this pragma, see the
1083 DEC Ada Language Reference Manual, section 9.12a.
1085 @node Pragma C_Pass_By_Copy
1086 @unnumberedsec Pragma C_Pass_By_Copy
1087 @cindex Passing by copy
1088 @findex C_Pass_By_Copy
1091 @smallexample @c ada
1092 pragma C_Pass_By_Copy
1093 ([Max_Size =>] static_integer_EXPRESSION);
1097 Normally the default mechanism for passing C convention records to C
1098 convention subprograms is to pass them by reference, as suggested by RM
1099 B.3(69). Use the configuration pragma @code{C_Pass_By_Copy} to change
1100 this default, by requiring that record formal parameters be passed by
1101 copy if all of the following conditions are met:
1105 The size of the record type does not exceed the value specified for
1108 The record type has @code{Convention C}.
1110 The formal parameter has this record type, and the subprogram has a
1111 foreign (non-Ada) convention.
1115 If these conditions are met the argument is passed by copy, i.e.@: in a
1116 manner consistent with what C expects if the corresponding formal in the
1117 C prototype is a struct (rather than a pointer to a struct).
1119 You can also pass records by copy by specifying the convention
1120 @code{C_Pass_By_Copy} for the record type, or by using the extended
1121 @code{Import} and @code{Export} pragmas, which allow specification of
1122 passing mechanisms on a parameter by parameter basis.
1125 @unnumberedsec Pragma Check
1127 @cindex Named assertions
1131 @smallexample @c ada
1133 [Name =>] Identifier,
1134 [Check =>] Boolean_EXPRESSION
1135 [, [Message =>] string_EXPRESSION] );
1139 This pragma is similar to the predefined pragma @code{Assert} except that an
1140 extra identifier argument is present. In conjunction with pragma
1141 @code{Check_Policy}, this can be used to define groups of assertions that can
1142 be independently controlled. The identifier @code{Assertion} is special, it
1143 refers to the normal set of pragma @code{Assert} statements. The identifiers
1144 @code{Precondition} and @code{Postcondition} correspond to the pragmas of these
1145 names, so these three names would normally not be used directly in a pragma
1148 Checks introduced by this pragma are normally deactivated by default. They can
1149 be activated either by the command line option @option{-gnata}, which turns on
1150 all checks, or individually controlled using pragma @code{Check_Policy}.
1152 @node Pragma Check_Name
1153 @unnumberedsec Pragma Check_Name
1154 @cindex Defining check names
1155 @cindex Check names, defining
1159 @smallexample @c ada
1160 pragma Check_Name (check_name_IDENTIFIER);
1164 This is a configuration pragma that defines a new implementation
1165 defined check name (unless IDENTIFIER matches one of the predefined
1166 check names, in which case the pragma has no effect). Check names
1167 are global to a partition, so if two or more configuration pragmas
1168 are present in a partition mentioning the same name, only one new
1169 check name is introduced.
1171 An implementation defined check name introduced with this pragma may
1172 be used in only three contexts: @code{pragma Suppress},
1173 @code{pragma Unsuppress},
1174 and as the prefix of a @code{Check_Name'Enabled} attribute reference. For
1175 any of these three cases, the check name must be visible. A check
1176 name is visible if it is in the configuration pragmas applying to
1177 the current unit, or if it appears at the start of any unit that
1178 is part of the dependency set of the current unit (e.g., units that
1179 are mentioned in @code{with} clauses).
1181 @node Pragma Check_Policy
1182 @unnumberedsec Pragma Check_Policy
1183 @cindex Controlling assertions
1184 @cindex Assertions, control
1185 @cindex Check pragma control
1186 @cindex Named assertions
1190 @smallexample @c ada
1192 ([Name =>] Identifier,
1193 [Policy =>] POLICY_IDENTIFIER);
1195 POLICY_IDENTIFIER ::= On | Off | Check | Ignore
1199 This pragma is similar to the predefined pragma @code{Assertion_Policy},
1200 except that it controls sets of named assertions introduced using the
1201 @code{Check} pragmas. It can be used as a configuration pragma or (unlike
1202 @code{Assertion_Policy}) can be used within a declarative part, in which case
1203 it controls the status to the end of the corresponding construct (in a manner
1204 identical to pragma @code{Suppress)}.
1206 The identifier given as the first argument corresponds to a name used in
1207 associated @code{Check} pragmas. For example, if the pragma:
1209 @smallexample @c ada
1210 pragma Check_Policy (Critical_Error, Off);
1214 is given, then subsequent @code{Check} pragmas whose first argument is also
1215 @code{Critical_Error} will be disabled. The special identifier @code{Assertion}
1216 controls the behavior of normal @code{Assert} pragmas (thus a pragma
1217 @code{Check_Policy} with this identifier is similar to the normal
1218 @code{Assertion_Policy} pragma except that it can appear within a
1221 The special identifiers @code{Precondition} and @code{Postcondition} control
1222 the status of preconditions and postconditions. If a @code{Precondition} pragma
1223 is encountered, it is ignored if turned off by a @code{Check_Policy} specifying
1224 that @code{Precondition} checks are @code{Off} or @code{Ignored}. Similarly use
1225 of the name @code{Postcondition} controls whether @code{Postcondition} pragmas
1228 The check policy is @code{Off} to turn off corresponding checks, and @code{On}
1229 to turn on corresponding checks. The default for a set of checks for which no
1230 @code{Check_Policy} is given is @code{Off} unless the compiler switch
1231 @option{-gnata} is given, which turns on all checks by default.
1233 The check policy settings @code{Check} and @code{Ignore} are also recognized
1234 as synonyms for @code{On} and @code{Off}. These synonyms are provided for
1235 compatibility with the standard @code{Assertion_Policy} pragma.
1237 @node Pragma Comment
1238 @unnumberedsec Pragma Comment
1243 @smallexample @c ada
1244 pragma Comment (static_string_EXPRESSION);
1248 This is almost identical in effect to pragma @code{Ident}. It allows the
1249 placement of a comment into the object file and hence into the
1250 executable file if the operating system permits such usage. The
1251 difference is that @code{Comment}, unlike @code{Ident}, has
1252 no limitations on placement of the pragma (it can be placed
1253 anywhere in the main source unit), and if more than one pragma
1254 is used, all comments are retained.
1256 @node Pragma Common_Object
1257 @unnumberedsec Pragma Common_Object
1258 @findex Common_Object
1262 @smallexample @c ada
1263 pragma Common_Object (
1264 [Internal =>] LOCAL_NAME
1265 [, [External =>] EXTERNAL_SYMBOL]
1266 [, [Size =>] EXTERNAL_SYMBOL] );
1270 | static_string_EXPRESSION
1274 This pragma enables the shared use of variables stored in overlaid
1275 linker areas corresponding to the use of @code{COMMON}
1276 in Fortran. The single
1277 object @var{LOCAL_NAME} is assigned to the area designated by
1278 the @var{External} argument.
1279 You may define a record to correspond to a series
1280 of fields. The @var{Size} argument
1281 is syntax checked in GNAT, but otherwise ignored.
1283 @code{Common_Object} is not supported on all platforms. If no
1284 support is available, then the code generator will issue a message
1285 indicating that the necessary attribute for implementation of this
1286 pragma is not available.
1288 @node Pragma Compile_Time_Error
1289 @unnumberedsec Pragma Compile_Time_Error
1290 @findex Compile_Time_Error
1294 @smallexample @c ada
1295 pragma Compile_Time_Error
1296 (boolean_EXPRESSION, static_string_EXPRESSION);
1300 This pragma can be used to generate additional compile time
1302 is particularly useful in generics, where errors can be issued for
1303 specific problematic instantiations. The first parameter is a boolean
1304 expression. The pragma is effective only if the value of this expression
1305 is known at compile time, and has the value True. The set of expressions
1306 whose values are known at compile time includes all static boolean
1307 expressions, and also other values which the compiler can determine
1308 at compile time (e.g., the size of a record type set by an explicit
1309 size representation clause, or the value of a variable which was
1310 initialized to a constant and is known not to have been modified).
1311 If these conditions are met, an error message is generated using
1312 the value given as the second argument. This string value may contain
1313 embedded ASCII.LF characters to break the message into multiple lines.
1315 @node Pragma Compile_Time_Warning
1316 @unnumberedsec Pragma Compile_Time_Warning
1317 @findex Compile_Time_Warning
1321 @smallexample @c ada
1322 pragma Compile_Time_Warning
1323 (boolean_EXPRESSION, static_string_EXPRESSION);
1327 Same as pragma Compile_Time_Error, except a warning is issued instead
1328 of an error message. Note that if this pragma is used in a package that
1329 is with'ed by a client, the client will get the warning even though it
1330 is issued by a with'ed package (normally warnings in with'ed units are
1331 suppressed, but this is a special exception to that rule).
1333 One typical use is within a generic where compile time known characteristics
1334 of formal parameters are tested, and warnings given appropriately. Another use
1335 with a first parameter of True is to warn a client about use of a package,
1336 for example that it is not fully implemented.
1338 @node Pragma Compiler_Unit
1339 @unnumberedsec Pragma Compiler_Unit
1340 @findex Compiler_Unit
1344 @smallexample @c ada
1345 pragma Compiler_Unit;
1349 This pragma is intended only for internal use in the GNAT run-time library.
1350 It indicates that the unit is used as part of the compiler build. The effect
1351 is to disallow constructs (raise with message, conditional expressions etc)
1352 that would cause trouble when bootstrapping using an older version of GNAT.
1353 For the exact list of restrictions, see the compiler sources and references
1354 to Is_Compiler_Unit.
1356 @node Pragma Complete_Representation
1357 @unnumberedsec Pragma Complete_Representation
1358 @findex Complete_Representation
1362 @smallexample @c ada
1363 pragma Complete_Representation;
1367 This pragma must appear immediately within a record representation
1368 clause. Typical placements are before the first component clause
1369 or after the last component clause. The effect is to give an error
1370 message if any component is missing a component clause. This pragma
1371 may be used to ensure that a record representation clause is
1372 complete, and that this invariant is maintained if fields are
1373 added to the record in the future.
1375 @node Pragma Complex_Representation
1376 @unnumberedsec Pragma Complex_Representation
1377 @findex Complex_Representation
1381 @smallexample @c ada
1382 pragma Complex_Representation
1383 ([Entity =>] LOCAL_NAME);
1387 The @var{Entity} argument must be the name of a record type which has
1388 two fields of the same floating-point type. The effect of this pragma is
1389 to force gcc to use the special internal complex representation form for
1390 this record, which may be more efficient. Note that this may result in
1391 the code for this type not conforming to standard ABI (application
1392 binary interface) requirements for the handling of record types. For
1393 example, in some environments, there is a requirement for passing
1394 records by pointer, and the use of this pragma may result in passing
1395 this type in floating-point registers.
1397 @node Pragma Component_Alignment
1398 @unnumberedsec Pragma Component_Alignment
1399 @cindex Alignments of components
1400 @findex Component_Alignment
1404 @smallexample @c ada
1405 pragma Component_Alignment (
1406 [Form =>] ALIGNMENT_CHOICE
1407 [, [Name =>] type_LOCAL_NAME]);
1409 ALIGNMENT_CHOICE ::=
1417 Specifies the alignment of components in array or record types.
1418 The meaning of the @var{Form} argument is as follows:
1421 @findex Component_Size
1422 @item Component_Size
1423 Aligns scalar components and subcomponents of the array or record type
1424 on boundaries appropriate to their inherent size (naturally
1425 aligned). For example, 1-byte components are aligned on byte boundaries,
1426 2-byte integer components are aligned on 2-byte boundaries, 4-byte
1427 integer components are aligned on 4-byte boundaries and so on. These
1428 alignment rules correspond to the normal rules for C compilers on all
1429 machines except the VAX@.
1431 @findex Component_Size_4
1432 @item Component_Size_4
1433 Naturally aligns components with a size of four or fewer
1434 bytes. Components that are larger than 4 bytes are placed on the next
1437 @findex Storage_Unit
1439 Specifies that array or record components are byte aligned, i.e.@:
1440 aligned on boundaries determined by the value of the constant
1441 @code{System.Storage_Unit}.
1445 Specifies that array or record components are aligned on default
1446 boundaries, appropriate to the underlying hardware or operating system or
1447 both. For OpenVMS VAX systems, the @code{Default} choice is the same as
1448 the @code{Storage_Unit} choice (byte alignment). For all other systems,
1449 the @code{Default} choice is the same as @code{Component_Size} (natural
1454 If the @code{Name} parameter is present, @var{type_LOCAL_NAME} must
1455 refer to a local record or array type, and the specified alignment
1456 choice applies to the specified type. The use of
1457 @code{Component_Alignment} together with a pragma @code{Pack} causes the
1458 @code{Component_Alignment} pragma to be ignored. The use of
1459 @code{Component_Alignment} together with a record representation clause
1460 is only effective for fields not specified by the representation clause.
1462 If the @code{Name} parameter is absent, the pragma can be used as either
1463 a configuration pragma, in which case it applies to one or more units in
1464 accordance with the normal rules for configuration pragmas, or it can be
1465 used within a declarative part, in which case it applies to types that
1466 are declared within this declarative part, or within any nested scope
1467 within this declarative part. In either case it specifies the alignment
1468 to be applied to any record or array type which has otherwise standard
1471 If the alignment for a record or array type is not specified (using
1472 pragma @code{Pack}, pragma @code{Component_Alignment}, or a record rep
1473 clause), the GNAT uses the default alignment as described previously.
1475 @node Pragma Convention_Identifier
1476 @unnumberedsec Pragma Convention_Identifier
1477 @findex Convention_Identifier
1478 @cindex Conventions, synonyms
1482 @smallexample @c ada
1483 pragma Convention_Identifier (
1484 [Name =>] IDENTIFIER,
1485 [Convention =>] convention_IDENTIFIER);
1489 This pragma provides a mechanism for supplying synonyms for existing
1490 convention identifiers. The @code{Name} identifier can subsequently
1491 be used as a synonym for the given convention in other pragmas (including
1492 for example pragma @code{Import} or another @code{Convention_Identifier}
1493 pragma). As an example of the use of this, suppose you had legacy code
1494 which used Fortran77 as the identifier for Fortran. Then the pragma:
1496 @smallexample @c ada
1497 pragma Convention_Identifier (Fortran77, Fortran);
1501 would allow the use of the convention identifier @code{Fortran77} in
1502 subsequent code, avoiding the need to modify the sources. As another
1503 example, you could use this to parametrize convention requirements
1504 according to systems. Suppose you needed to use @code{Stdcall} on
1505 windows systems, and @code{C} on some other system, then you could
1506 define a convention identifier @code{Library} and use a single
1507 @code{Convention_Identifier} pragma to specify which convention
1508 would be used system-wide.
1510 @node Pragma CPP_Class
1511 @unnumberedsec Pragma CPP_Class
1513 @cindex Interfacing with C++
1517 @smallexample @c ada
1518 pragma CPP_Class ([Entity =>] LOCAL_NAME);
1522 The argument denotes an entity in the current declarative region that is
1523 declared as a record type. It indicates that the type corresponds to an
1524 externally declared C++ class type, and is to be laid out the same way
1525 that C++ would lay out the type. If the C++ class has virtual primitives
1526 then the record must be declared as a tagged record type.
1528 Types for which @code{CPP_Class} is specified do not have assignment or
1529 equality operators defined (such operations can be imported or declared
1530 as subprograms as required). Initialization is allowed only by constructor
1531 functions (see pragma @code{CPP_Constructor}). Such types are implicitly
1532 limited if not explicitly declared as limited or derived from a limited
1533 type, and an error is issued in that case.
1535 Pragma @code{CPP_Class} is intended primarily for automatic generation
1536 using an automatic binding generator tool.
1537 See @ref{Interfacing to C++} for related information.
1539 Note: Pragma @code{CPP_Class} is currently obsolete. It is supported
1540 for backward compatibility but its functionality is available
1541 using pragma @code{Import} with @code{Convention} = @code{CPP}.
1543 @node Pragma CPP_Constructor
1544 @unnumberedsec Pragma CPP_Constructor
1545 @cindex Interfacing with C++
1546 @findex CPP_Constructor
1550 @smallexample @c ada
1551 pragma CPP_Constructor ([Entity =>] LOCAL_NAME
1552 [, [External_Name =>] static_string_EXPRESSION ]
1553 [, [Link_Name =>] static_string_EXPRESSION ]);
1557 This pragma identifies an imported function (imported in the usual way
1558 with pragma @code{Import}) as corresponding to a C++ constructor. If
1559 @code{External_Name} and @code{Link_Name} are not specified then the
1560 @code{Entity} argument is a name that must have been previously mentioned
1561 in a pragma @code{Import} with @code{Convention} = @code{CPP}. Such name
1562 must be of one of the following forms:
1566 @code{function @var{Fname} return @var{T}}
1570 @code{function @var{Fname} return @var{T}'Class}
1573 @code{function @var{Fname} (@dots{}) return @var{T}}
1577 @code{function @var{Fname} (@dots{}) return @var{T}'Class}
1581 where @var{T} is a limited record type imported from C++ with pragma
1582 @code{Import} and @code{Convention} = @code{CPP}.
1584 The first two forms import the default constructor, used when an object
1585 of type @var{T} is created on the Ada side with no explicit constructor.
1586 The latter two forms cover all the non-default constructors of the type.
1587 See the GNAT users guide for details.
1589 If no constructors are imported, it is impossible to create any objects
1590 on the Ada side and the type is implicitly declared abstract.
1592 Pragma @code{CPP_Constructor} is intended primarily for automatic generation
1593 using an automatic binding generator tool.
1594 See @ref{Interfacing to C++} for more related information.
1596 Note: The use of functions returning class-wide types for constructors is
1597 currently obsolete. They are supported for backward compatibility. The
1598 use of functions returning the type T leave the Ada sources more clear
1599 because the imported C++ constructors always return an object of type T;
1600 that is, they never return an object whose type is a descendant of type T.
1602 @node Pragma CPP_Virtual
1603 @unnumberedsec Pragma CPP_Virtual
1604 @cindex Interfacing to C++
1607 This pragma is now obsolete has has no effect because GNAT generates
1608 the same object layout than the G++ compiler.
1610 See @ref{Interfacing to C++} for related information.
1612 @node Pragma CPP_Vtable
1613 @unnumberedsec Pragma CPP_Vtable
1614 @cindex Interfacing with C++
1617 This pragma is now obsolete has has no effect because GNAT generates
1618 the same object layout than the G++ compiler.
1620 See @ref{Interfacing to C++} for related information.
1623 @unnumberedsec Pragma Debug
1628 @smallexample @c ada
1629 pragma Debug ([CONDITION, ]PROCEDURE_CALL_WITHOUT_SEMICOLON);
1631 PROCEDURE_CALL_WITHOUT_SEMICOLON ::=
1633 | PROCEDURE_PREFIX ACTUAL_PARAMETER_PART
1637 The procedure call argument has the syntactic form of an expression, meeting
1638 the syntactic requirements for pragmas.
1640 If debug pragmas are not enabled or if the condition is present and evaluates
1641 to False, this pragma has no effect. If debug pragmas are enabled, the
1642 semantics of the pragma is exactly equivalent to the procedure call statement
1643 corresponding to the argument with a terminating semicolon. Pragmas are
1644 permitted in sequences of declarations, so you can use pragma @code{Debug} to
1645 intersperse calls to debug procedures in the middle of declarations. Debug
1646 pragmas can be enabled either by use of the command line switch @option{-gnata}
1647 or by use of the configuration pragma @code{Debug_Policy}.
1649 @node Pragma Debug_Policy
1650 @unnumberedsec Pragma Debug_Policy
1651 @findex Debug_Policy
1655 @smallexample @c ada
1656 pragma Debug_Policy (CHECK | IGNORE);
1660 If the argument is @code{CHECK}, then pragma @code{DEBUG} is enabled.
1661 If the argument is @code{IGNORE}, then pragma @code{DEBUG} is ignored.
1662 This pragma overrides the effect of the @option{-gnata} switch on the
1665 @node Pragma Detect_Blocking
1666 @unnumberedsec Pragma Detect_Blocking
1667 @findex Detect_Blocking
1671 @smallexample @c ada
1672 pragma Detect_Blocking;
1676 This is a configuration pragma that forces the detection of potentially
1677 blocking operations within a protected operation, and to raise Program_Error
1680 @node Pragma Elaboration_Checks
1681 @unnumberedsec Pragma Elaboration_Checks
1682 @cindex Elaboration control
1683 @findex Elaboration_Checks
1687 @smallexample @c ada
1688 pragma Elaboration_Checks (Dynamic | Static);
1692 This is a configuration pragma that provides control over the
1693 elaboration model used by the compilation affected by the
1694 pragma. If the parameter is @code{Dynamic},
1695 then the dynamic elaboration
1696 model described in the Ada Reference Manual is used, as though
1697 the @option{-gnatE} switch had been specified on the command
1698 line. If the parameter is @code{Static}, then the default GNAT static
1699 model is used. This configuration pragma overrides the setting
1700 of the command line. For full details on the elaboration models
1701 used by the GNAT compiler, see @ref{Elaboration Order Handling in GNAT,,,
1702 gnat_ugn, @value{EDITION} User's Guide}.
1704 @node Pragma Eliminate
1705 @unnumberedsec Pragma Eliminate
1706 @cindex Elimination of unused subprograms
1711 @smallexample @c ada
1713 [Unit_Name =>] IDENTIFIER |
1714 SELECTED_COMPONENT);
1717 [Unit_Name =>] IDENTIFIER |
1719 [Entity =>] IDENTIFIER |
1720 SELECTED_COMPONENT |
1722 [,OVERLOADING_RESOLUTION]);
1724 OVERLOADING_RESOLUTION ::= PARAMETER_AND_RESULT_TYPE_PROFILE |
1727 PARAMETER_AND_RESULT_TYPE_PROFILE ::= PROCEDURE_PROFILE |
1730 PROCEDURE_PROFILE ::= Parameter_Types => PARAMETER_TYPES
1732 FUNCTION_PROFILE ::= [Parameter_Types => PARAMETER_TYPES,]
1733 Result_Type => result_SUBTYPE_NAME]
1735 PARAMETER_TYPES ::= (SUBTYPE_NAME @{, SUBTYPE_NAME@})
1736 SUBTYPE_NAME ::= STRING_VALUE
1738 SOURCE_LOCATION ::= Source_Location => SOURCE_TRACE
1739 SOURCE_TRACE ::= STRING_VALUE
1741 STRING_VALUE ::= STRING_LITERAL @{& STRING_LITERAL@}
1745 This pragma indicates that the given entity is not used outside the
1746 compilation unit it is defined in. The entity must be an explicitly declared
1747 subprogram; this includes generic subprogram instances and
1748 subprograms declared in generic package instances.
1750 If the entity to be eliminated is a library level subprogram, then
1751 the first form of pragma @code{Eliminate} is used with only a single argument.
1752 In this form, the @code{Unit_Name} argument specifies the name of the
1753 library level unit to be eliminated.
1755 In all other cases, both @code{Unit_Name} and @code{Entity} arguments
1756 are required. If item is an entity of a library package, then the first
1757 argument specifies the unit name, and the second argument specifies
1758 the particular entity. If the second argument is in string form, it must
1759 correspond to the internal manner in which GNAT stores entity names (see
1760 compilation unit Namet in the compiler sources for details).
1762 The remaining parameters (OVERLOADING_RESOLUTION) are optionally used
1763 to distinguish between overloaded subprograms. If a pragma does not contain
1764 the OVERLOADING_RESOLUTION parameter(s), it is applied to all the overloaded
1765 subprograms denoted by the first two parameters.
1767 Use PARAMETER_AND_RESULT_TYPE_PROFILE to specify the profile of the subprogram
1768 to be eliminated in a manner similar to that used for the extended
1769 @code{Import} and @code{Export} pragmas, except that the subtype names are
1770 always given as strings. At the moment, this form of distinguishing
1771 overloaded subprograms is implemented only partially, so we do not recommend
1772 using it for practical subprogram elimination.
1774 Note that in case of a parameterless procedure its profile is represented
1775 as @code{Parameter_Types => ("")}
1777 Alternatively, the @code{Source_Location} parameter is used to specify
1778 which overloaded alternative is to be eliminated by pointing to the
1779 location of the DEFINING_PROGRAM_UNIT_NAME of this subprogram in the
1780 source text. The string literal (or concatenation of string literals)
1781 given as SOURCE_TRACE must have the following format:
1783 @smallexample @c ada
1784 SOURCE_TRACE ::= SOURCE_LOCATION@{LBRACKET SOURCE_LOCATION RBRACKET@}
1789 SOURCE_LOCATION ::= FILE_NAME:LINE_NUMBER
1790 FILE_NAME ::= STRING_LITERAL
1791 LINE_NUMBER ::= DIGIT @{DIGIT@}
1794 SOURCE_TRACE should be the short name of the source file (with no directory
1795 information), and LINE_NUMBER is supposed to point to the line where the
1796 defining name of the subprogram is located.
1798 For the subprograms that are not a part of generic instantiations, only one
1799 SOURCE_LOCATION is used. If a subprogram is declared in a package
1800 instantiation, SOURCE_TRACE contains two SOURCE_LOCATIONs, the first one is
1801 the location of the (DEFINING_PROGRAM_UNIT_NAME of the) instantiation, and the
1802 second one denotes the declaration of the corresponding subprogram in the
1803 generic package. This approach is recursively used to create SOURCE_LOCATIONs
1804 in case of nested instantiations.
1806 The effect of the pragma is to allow the compiler to eliminate
1807 the code or data associated with the named entity. Any reference to
1808 an eliminated entity outside the compilation unit it is defined in,
1809 causes a compile time or link time error.
1811 The intention of pragma @code{Eliminate} is to allow a program to be compiled
1812 in a system independent manner, with unused entities eliminated, without
1813 the requirement of modifying the source text. Normally the required set
1814 of @code{Eliminate} pragmas is constructed automatically using the gnatelim
1815 tool. Elimination of unused entities local to a compilation unit is
1816 automatic, without requiring the use of pragma @code{Eliminate}.
1818 Note that the reason this pragma takes string literals where names might
1819 be expected is that a pragma @code{Eliminate} can appear in a context where the
1820 relevant names are not visible.
1822 Note that any change in the source files that includes removing, splitting of
1823 adding lines may make the set of Eliminate pragmas using SOURCE_LOCATION
1826 It is legal to use pragma Eliminate where the referenced entity is a
1827 dispatching operation, but it is not clear what this would mean, since
1828 in general the call does not know which entity is actually being called.
1829 Consequently, a pragma Eliminate for a dispatching operation is ignored.
1831 @node Pragma Export_Exception
1832 @unnumberedsec Pragma Export_Exception
1834 @findex Export_Exception
1838 @smallexample @c ada
1839 pragma Export_Exception (
1840 [Internal =>] LOCAL_NAME
1841 [, [External =>] EXTERNAL_SYMBOL]
1842 [, [Form =>] Ada | VMS]
1843 [, [Code =>] static_integer_EXPRESSION]);
1847 | static_string_EXPRESSION
1851 This pragma is implemented only in the OpenVMS implementation of GNAT@. It
1852 causes the specified exception to be propagated outside of the Ada program,
1853 so that it can be handled by programs written in other OpenVMS languages.
1854 This pragma establishes an external name for an Ada exception and makes the
1855 name available to the OpenVMS Linker as a global symbol. For further details
1856 on this pragma, see the
1857 DEC Ada Language Reference Manual, section 13.9a3.2.
1859 @node Pragma Export_Function
1860 @unnumberedsec Pragma Export_Function
1861 @cindex Argument passing mechanisms
1862 @findex Export_Function
1867 @smallexample @c ada
1868 pragma Export_Function (
1869 [Internal =>] LOCAL_NAME
1870 [, [External =>] EXTERNAL_SYMBOL]
1871 [, [Parameter_Types =>] PARAMETER_TYPES]
1872 [, [Result_Type =>] result_SUBTYPE_MARK]
1873 [, [Mechanism =>] MECHANISM]
1874 [, [Result_Mechanism =>] MECHANISM_NAME]);
1878 | static_string_EXPRESSION
1883 | TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@}
1887 | subtype_Name ' Access
1891 | (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@})
1893 MECHANISM_ASSOCIATION ::=
1894 [formal_parameter_NAME =>] MECHANISM_NAME
1899 | Descriptor [([Class =>] CLASS_NAME)]
1900 | Short_Descriptor [([Class =>] CLASS_NAME)]
1902 CLASS_NAME ::= ubs | ubsb | uba | s | sb | a
1906 Use this pragma to make a function externally callable and optionally
1907 provide information on mechanisms to be used for passing parameter and
1908 result values. We recommend, for the purposes of improving portability,
1909 this pragma always be used in conjunction with a separate pragma
1910 @code{Export}, which must precede the pragma @code{Export_Function}.
1911 GNAT does not require a separate pragma @code{Export}, but if none is
1912 present, @code{Convention Ada} is assumed, which is usually
1913 not what is wanted, so it is usually appropriate to use this
1914 pragma in conjunction with a @code{Export} or @code{Convention}
1915 pragma that specifies the desired foreign convention.
1916 Pragma @code{Export_Function}
1917 (and @code{Export}, if present) must appear in the same declarative
1918 region as the function to which they apply.
1920 @var{internal_name} must uniquely designate the function to which the
1921 pragma applies. If more than one function name exists of this name in
1922 the declarative part you must use the @code{Parameter_Types} and
1923 @code{Result_Type} parameters is mandatory to achieve the required
1924 unique designation. @var{subtype_mark}s in these parameters must
1925 exactly match the subtypes in the corresponding function specification,
1926 using positional notation to match parameters with subtype marks.
1927 The form with an @code{'Access} attribute can be used to match an
1928 anonymous access parameter.
1931 @cindex Passing by descriptor
1932 Passing by descriptor is supported only on the OpenVMS ports of GNAT@.
1933 The default behavior for Export_Function is to accept either 64bit or
1934 32bit descriptors unless short_descriptor is specified, then only 32bit
1935 descriptors are accepted.
1937 @cindex Suppressing external name
1938 Special treatment is given if the EXTERNAL is an explicit null
1939 string or a static string expressions that evaluates to the null
1940 string. In this case, no external name is generated. This form
1941 still allows the specification of parameter mechanisms.
1943 @node Pragma Export_Object
1944 @unnumberedsec Pragma Export_Object
1945 @findex Export_Object
1949 @smallexample @c ada
1950 pragma Export_Object
1951 [Internal =>] LOCAL_NAME
1952 [, [External =>] EXTERNAL_SYMBOL]
1953 [, [Size =>] EXTERNAL_SYMBOL]
1957 | static_string_EXPRESSION
1961 This pragma designates an object as exported, and apart from the
1962 extended rules for external symbols, is identical in effect to the use of
1963 the normal @code{Export} pragma applied to an object. You may use a
1964 separate Export pragma (and you probably should from the point of view
1965 of portability), but it is not required. @var{Size} is syntax checked,
1966 but otherwise ignored by GNAT@.
1968 @node Pragma Export_Procedure
1969 @unnumberedsec Pragma Export_Procedure
1970 @findex Export_Procedure
1974 @smallexample @c ada
1975 pragma Export_Procedure (
1976 [Internal =>] LOCAL_NAME
1977 [, [External =>] EXTERNAL_SYMBOL]
1978 [, [Parameter_Types =>] PARAMETER_TYPES]
1979 [, [Mechanism =>] MECHANISM]);
1983 | static_string_EXPRESSION
1988 | TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@}
1992 | subtype_Name ' Access
1996 | (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@})
1998 MECHANISM_ASSOCIATION ::=
1999 [formal_parameter_NAME =>] MECHANISM_NAME
2004 | Descriptor [([Class =>] CLASS_NAME)]
2005 | Short_Descriptor [([Class =>] CLASS_NAME)]
2007 CLASS_NAME ::= ubs | ubsb | uba | s | sb | a
2011 This pragma is identical to @code{Export_Function} except that it
2012 applies to a procedure rather than a function and the parameters
2013 @code{Result_Type} and @code{Result_Mechanism} are not permitted.
2014 GNAT does not require a separate pragma @code{Export}, but if none is
2015 present, @code{Convention Ada} is assumed, which is usually
2016 not what is wanted, so it is usually appropriate to use this
2017 pragma in conjunction with a @code{Export} or @code{Convention}
2018 pragma that specifies the desired foreign convention.
2021 @cindex Passing by descriptor
2022 Passing by descriptor is supported only on the OpenVMS ports of GNAT@.
2023 The default behavior for Export_Procedure is to accept either 64bit or
2024 32bit descriptors unless short_descriptor is specified, then only 32bit
2025 descriptors are accepted.
2027 @cindex Suppressing external name
2028 Special treatment is given if the EXTERNAL is an explicit null
2029 string or a static string expressions that evaluates to the null
2030 string. In this case, no external name is generated. This form
2031 still allows the specification of parameter mechanisms.
2033 @node Pragma Export_Value
2034 @unnumberedsec Pragma Export_Value
2035 @findex Export_Value
2039 @smallexample @c ada
2040 pragma Export_Value (
2041 [Value =>] static_integer_EXPRESSION,
2042 [Link_Name =>] static_string_EXPRESSION);
2046 This pragma serves to export a static integer value for external use.
2047 The first argument specifies the value to be exported. The Link_Name
2048 argument specifies the symbolic name to be associated with the integer
2049 value. This pragma is useful for defining a named static value in Ada
2050 that can be referenced in assembly language units to be linked with
2051 the application. This pragma is currently supported only for the
2052 AAMP target and is ignored for other targets.
2054 @node Pragma Export_Valued_Procedure
2055 @unnumberedsec Pragma Export_Valued_Procedure
2056 @findex Export_Valued_Procedure
2060 @smallexample @c ada
2061 pragma Export_Valued_Procedure (
2062 [Internal =>] LOCAL_NAME
2063 [, [External =>] EXTERNAL_SYMBOL]
2064 [, [Parameter_Types =>] PARAMETER_TYPES]
2065 [, [Mechanism =>] MECHANISM]);
2069 | static_string_EXPRESSION
2074 | TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@}
2078 | subtype_Name ' Access
2082 | (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@})
2084 MECHANISM_ASSOCIATION ::=
2085 [formal_parameter_NAME =>] MECHANISM_NAME
2090 | Descriptor [([Class =>] CLASS_NAME)]
2091 | Short_Descriptor [([Class =>] CLASS_NAME)]
2093 CLASS_NAME ::= ubs | ubsb | uba | s | sb | a
2097 This pragma is identical to @code{Export_Procedure} except that the
2098 first parameter of @var{LOCAL_NAME}, which must be present, must be of
2099 mode @code{OUT}, and externally the subprogram is treated as a function
2100 with this parameter as the result of the function. GNAT provides for
2101 this capability to allow the use of @code{OUT} and @code{IN OUT}
2102 parameters in interfacing to external functions (which are not permitted
2104 GNAT does not require a separate pragma @code{Export}, but if none is
2105 present, @code{Convention Ada} is assumed, which is almost certainly
2106 not what is wanted since the whole point of this pragma is to interface
2107 with foreign language functions, so it is usually appropriate to use this
2108 pragma in conjunction with a @code{Export} or @code{Convention}
2109 pragma that specifies the desired foreign convention.
2112 @cindex Passing by descriptor
2113 Passing by descriptor is supported only on the OpenVMS ports of GNAT@.
2114 The default behavior for Export_Valued_Procedure is to accept either 64bit or
2115 32bit descriptors unless short_descriptor is specified, then only 32bit
2116 descriptors are accepted.
2118 @cindex Suppressing external name
2119 Special treatment is given if the EXTERNAL is an explicit null
2120 string or a static string expressions that evaluates to the null
2121 string. In this case, no external name is generated. This form
2122 still allows the specification of parameter mechanisms.
2124 @node Pragma Extend_System
2125 @unnumberedsec Pragma Extend_System
2126 @cindex @code{system}, extending
2128 @findex Extend_System
2132 @smallexample @c ada
2133 pragma Extend_System ([Name =>] IDENTIFIER);
2137 This pragma is used to provide backwards compatibility with other
2138 implementations that extend the facilities of package @code{System}. In
2139 GNAT, @code{System} contains only the definitions that are present in
2140 the Ada RM@. However, other implementations, notably the DEC Ada 83
2141 implementation, provide many extensions to package @code{System}.
2143 For each such implementation accommodated by this pragma, GNAT provides a
2144 package @code{Aux_@var{xxx}}, e.g.@: @code{Aux_DEC} for the DEC Ada 83
2145 implementation, which provides the required additional definitions. You
2146 can use this package in two ways. You can @code{with} it in the normal
2147 way and access entities either by selection or using a @code{use}
2148 clause. In this case no special processing is required.
2150 However, if existing code contains references such as
2151 @code{System.@var{xxx}} where @var{xxx} is an entity in the extended
2152 definitions provided in package @code{System}, you may use this pragma
2153 to extend visibility in @code{System} in a non-standard way that
2154 provides greater compatibility with the existing code. Pragma
2155 @code{Extend_System} is a configuration pragma whose single argument is
2156 the name of the package containing the extended definition
2157 (e.g.@: @code{Aux_DEC} for the DEC Ada case). A unit compiled under
2158 control of this pragma will be processed using special visibility
2159 processing that looks in package @code{System.Aux_@var{xxx}} where
2160 @code{Aux_@var{xxx}} is the pragma argument for any entity referenced in
2161 package @code{System}, but not found in package @code{System}.
2163 You can use this pragma either to access a predefined @code{System}
2164 extension supplied with the compiler, for example @code{Aux_DEC} or
2165 you can construct your own extension unit following the above
2166 definition. Note that such a package is a child of @code{System}
2167 and thus is considered part of the implementation. To compile
2168 it you will have to use the appropriate switch for compiling
2169 system units. @xref{Top, @value{EDITION} User's Guide, About This
2170 Guide,, gnat_ugn, @value{EDITION} User's Guide}, for details.
2172 @node Pragma External
2173 @unnumberedsec Pragma External
2178 @smallexample @c ada
2180 [ Convention =>] convention_IDENTIFIER,
2181 [ Entity =>] LOCAL_NAME
2182 [, [External_Name =>] static_string_EXPRESSION ]
2183 [, [Link_Name =>] static_string_EXPRESSION ]);
2187 This pragma is identical in syntax and semantics to pragma
2188 @code{Export} as defined in the Ada Reference Manual. It is
2189 provided for compatibility with some Ada 83 compilers that
2190 used this pragma for exactly the same purposes as pragma
2191 @code{Export} before the latter was standardized.
2193 @node Pragma External_Name_Casing
2194 @unnumberedsec Pragma External_Name_Casing
2195 @cindex Dec Ada 83 casing compatibility
2196 @cindex External Names, casing
2197 @cindex Casing of External names
2198 @findex External_Name_Casing
2202 @smallexample @c ada
2203 pragma External_Name_Casing (
2204 Uppercase | Lowercase
2205 [, Uppercase | Lowercase | As_Is]);
2209 This pragma provides control over the casing of external names associated
2210 with Import and Export pragmas. There are two cases to consider:
2213 @item Implicit external names
2214 Implicit external names are derived from identifiers. The most common case
2215 arises when a standard Ada Import or Export pragma is used with only two
2218 @smallexample @c ada
2219 pragma Import (C, C_Routine);
2223 Since Ada is a case-insensitive language, the spelling of the identifier in
2224 the Ada source program does not provide any information on the desired
2225 casing of the external name, and so a convention is needed. In GNAT the
2226 default treatment is that such names are converted to all lower case
2227 letters. This corresponds to the normal C style in many environments.
2228 The first argument of pragma @code{External_Name_Casing} can be used to
2229 control this treatment. If @code{Uppercase} is specified, then the name
2230 will be forced to all uppercase letters. If @code{Lowercase} is specified,
2231 then the normal default of all lower case letters will be used.
2233 This same implicit treatment is also used in the case of extended DEC Ada 83
2234 compatible Import and Export pragmas where an external name is explicitly
2235 specified using an identifier rather than a string.
2237 @item Explicit external names
2238 Explicit external names are given as string literals. The most common case
2239 arises when a standard Ada Import or Export pragma is used with three
2242 @smallexample @c ada
2243 pragma Import (C, C_Routine, "C_routine");
2247 In this case, the string literal normally provides the exact casing required
2248 for the external name. The second argument of pragma
2249 @code{External_Name_Casing} may be used to modify this behavior.
2250 If @code{Uppercase} is specified, then the name
2251 will be forced to all uppercase letters. If @code{Lowercase} is specified,
2252 then the name will be forced to all lowercase letters. A specification of
2253 @code{As_Is} provides the normal default behavior in which the casing is
2254 taken from the string provided.
2258 This pragma may appear anywhere that a pragma is valid. In particular, it
2259 can be used as a configuration pragma in the @file{gnat.adc} file, in which
2260 case it applies to all subsequent compilations, or it can be used as a program
2261 unit pragma, in which case it only applies to the current unit, or it can
2262 be used more locally to control individual Import/Export pragmas.
2264 It is primarily intended for use with OpenVMS systems, where many
2265 compilers convert all symbols to upper case by default. For interfacing to
2266 such compilers (e.g.@: the DEC C compiler), it may be convenient to use
2269 @smallexample @c ada
2270 pragma External_Name_Casing (Uppercase, Uppercase);
2274 to enforce the upper casing of all external symbols.
2276 @node Pragma Fast_Math
2277 @unnumberedsec Pragma Fast_Math
2282 @smallexample @c ada
2287 This is a configuration pragma which activates a mode in which speed is
2288 considered more important for floating-point operations than absolutely
2289 accurate adherence to the requirements of the standard. Currently the
2290 following operations are affected:
2293 @item Complex Multiplication
2294 The normal simple formula for complex multiplication can result in intermediate
2295 overflows for numbers near the end of the range. The Ada standard requires that
2296 this situation be detected and corrected by scaling, but in Fast_Math mode such
2297 cases will simply result in overflow. Note that to take advantage of this you
2298 must instantiate your own version of @code{Ada.Numerics.Generic_Complex_Types}
2299 under control of the pragma, rather than use the preinstantiated versions.
2302 @node Pragma Favor_Top_Level
2303 @unnumberedsec Pragma Favor_Top_Level
2304 @findex Favor_Top_Level
2308 @smallexample @c ada
2309 pragma Favor_Top_Level (type_NAME);
2313 The named type must be an access-to-subprogram type. This pragma is an
2314 efficiency hint to the compiler, regarding the use of 'Access or
2315 'Unrestricted_Access on nested (non-library-level) subprograms. The
2316 pragma means that nested subprograms are not used with this type, or
2317 are rare, so that the generated code should be efficient in the
2318 top-level case. When this pragma is used, dynamically generated
2319 trampolines may be used on some targets for nested subprograms.
2320 See also the No_Implicit_Dynamic_Code restriction.
2322 @node Pragma Finalize_Storage_Only
2323 @unnumberedsec Pragma Finalize_Storage_Only
2324 @findex Finalize_Storage_Only
2328 @smallexample @c ada
2329 pragma Finalize_Storage_Only (first_subtype_LOCAL_NAME);
2333 This pragma allows the compiler not to emit a Finalize call for objects
2334 defined at the library level. This is mostly useful for types where
2335 finalization is only used to deal with storage reclamation since in most
2336 environments it is not necessary to reclaim memory just before terminating
2337 execution, hence the name.
2339 @node Pragma Float_Representation
2340 @unnumberedsec Pragma Float_Representation
2342 @findex Float_Representation
2346 @smallexample @c ada
2347 pragma Float_Representation (FLOAT_REP[, float_type_LOCAL_NAME]);
2349 FLOAT_REP ::= VAX_Float | IEEE_Float
2353 In the one argument form, this pragma is a configuration pragma which
2354 allows control over the internal representation chosen for the predefined
2355 floating point types declared in the packages @code{Standard} and
2356 @code{System}. On all systems other than OpenVMS, the argument must
2357 be @code{IEEE_Float} and the pragma has no effect. On OpenVMS, the
2358 argument may be @code{VAX_Float} to specify the use of the VAX float
2359 format for the floating-point types in Standard. This requires that
2360 the standard runtime libraries be recompiled. @xref{The GNAT Run-Time
2361 Library Builder gnatlbr,,, gnat_ugn, @value{EDITION} User's Guide
2362 OpenVMS}, for a description of the @code{GNAT LIBRARY} command.
2364 The two argument form specifies the representation to be used for
2365 the specified floating-point type. On all systems other than OpenVMS,
2367 be @code{IEEE_Float} and the pragma has no effect. On OpenVMS, the
2368 argument may be @code{VAX_Float} to specify the use of the VAX float
2373 For digits values up to 6, F float format will be used.
2375 For digits values from 7 to 9, G float format will be used.
2377 For digits values from 10 to 15, F float format will be used.
2379 Digits values above 15 are not allowed.
2383 @unnumberedsec Pragma Ident
2388 @smallexample @c ada
2389 pragma Ident (static_string_EXPRESSION);
2393 This pragma provides a string identification in the generated object file,
2394 if the system supports the concept of this kind of identification string.
2395 This pragma is allowed only in the outermost declarative part or
2396 declarative items of a compilation unit. If more than one @code{Ident}
2397 pragma is given, only the last one processed is effective.
2399 On OpenVMS systems, the effect of the pragma is identical to the effect of
2400 the DEC Ada 83 pragma of the same name. Note that in DEC Ada 83, the
2401 maximum allowed length is 31 characters, so if it is important to
2402 maintain compatibility with this compiler, you should obey this length
2405 @node Pragma Implemented_By_Entry
2406 @unnumberedsec Pragma Implemented_By_Entry
2407 @findex Implemented_By_Entry
2411 @smallexample @c ada
2412 pragma Implemented_By_Entry (LOCAL_NAME);
2416 This is a representation pragma which applies to protected, synchronized and
2417 task interface primitives. If the pragma is applied to primitive operation Op
2418 of interface Iface, it is illegal to override Op in a type that implements
2419 Iface, with anything other than an entry.
2421 @smallexample @c ada
2422 type Iface is protected interface;
2423 procedure Do_Something (Object : in out Iface) is abstract;
2424 pragma Implemented_By_Entry (Do_Something);
2426 protected type P is new Iface with
2427 procedure Do_Something; -- Illegal
2430 task type T is new Iface with
2431 entry Do_Something; -- Legal
2436 NOTE: The pragma is still in its design stage by the Ada Rapporteur Group. It
2437 is intended to be used in conjunction with dispatching requeue statements as
2438 described in AI05-0030. Should the ARG decide on an official name and syntax,
2439 this pragma will become language-defined rather than GNAT-specific.
2441 @node Pragma Implicit_Packing
2442 @unnumberedsec Pragma Implicit_Packing
2443 @findex Implicit_Packing
2447 @smallexample @c ada
2448 pragma Implicit_Packing;
2452 This is a configuration pragma that requests implicit packing for packed
2453 arrays for which a size clause is given but no explicit pragma Pack or
2454 specification of Component_Size is present. It also applies to records
2455 where no record representation clause is present. Consider this example:
2457 @smallexample @c ada
2458 type R is array (0 .. 7) of Boolean;
2463 In accordance with the recommendation in the RM (RM 13.3(53)), a Size clause
2464 does not change the layout of a composite object. So the Size clause in the
2465 above example is normally rejected, since the default layout of the array uses
2466 8-bit components, and thus the array requires a minimum of 64 bits.
2468 If this declaration is compiled in a region of code covered by an occurrence
2469 of the configuration pragma Implicit_Packing, then the Size clause in this
2470 and similar examples will cause implicit packing and thus be accepted. For
2471 this implicit packing to occur, the type in question must be an array of small
2472 components whose size is known at compile time, and the Size clause must
2473 specify the exact size that corresponds to the length of the array multiplied
2474 by the size in bits of the component type.
2475 @cindex Array packing
2477 Similarly, the following example shows the use in the record case
2479 @smallexample @c ada
2481 a, b, c, d, e, f, g, h : boolean;
2488 Without a pragma Pack, each Boolean field requires 8 bits, so the
2489 minimum size is 72 bits, but with a pragma Pack, 16 bits would be
2490 sufficient. The use of pragma Implciit_Packing allows this record
2491 declaration to compile without an explicit pragma Pack.
2492 @node Pragma Import_Exception
2493 @unnumberedsec Pragma Import_Exception
2495 @findex Import_Exception
2499 @smallexample @c ada
2500 pragma Import_Exception (
2501 [Internal =>] LOCAL_NAME
2502 [, [External =>] EXTERNAL_SYMBOL]
2503 [, [Form =>] Ada | VMS]
2504 [, [Code =>] static_integer_EXPRESSION]);
2508 | static_string_EXPRESSION
2512 This pragma is implemented only in the OpenVMS implementation of GNAT@.
2513 It allows OpenVMS conditions (for example, from OpenVMS system services or
2514 other OpenVMS languages) to be propagated to Ada programs as Ada exceptions.
2515 The pragma specifies that the exception associated with an exception
2516 declaration in an Ada program be defined externally (in non-Ada code).
2517 For further details on this pragma, see the
2518 DEC Ada Language Reference Manual, section 13.9a.3.1.
2520 @node Pragma Import_Function
2521 @unnumberedsec Pragma Import_Function
2522 @findex Import_Function
2526 @smallexample @c ada
2527 pragma Import_Function (
2528 [Internal =>] LOCAL_NAME,
2529 [, [External =>] EXTERNAL_SYMBOL]
2530 [, [Parameter_Types =>] PARAMETER_TYPES]
2531 [, [Result_Type =>] SUBTYPE_MARK]
2532 [, [Mechanism =>] MECHANISM]
2533 [, [Result_Mechanism =>] MECHANISM_NAME]
2534 [, [First_Optional_Parameter =>] IDENTIFIER]);
2538 | static_string_EXPRESSION
2542 | TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@}
2546 | subtype_Name ' Access
2550 | (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@})
2552 MECHANISM_ASSOCIATION ::=
2553 [formal_parameter_NAME =>] MECHANISM_NAME
2558 | Descriptor [([Class =>] CLASS_NAME)]
2559 | Short_Descriptor [([Class =>] CLASS_NAME)]
2561 CLASS_NAME ::= ubs | ubsb | uba | s | sb | a | nca
2565 This pragma is used in conjunction with a pragma @code{Import} to
2566 specify additional information for an imported function. The pragma
2567 @code{Import} (or equivalent pragma @code{Interface}) must precede the
2568 @code{Import_Function} pragma and both must appear in the same
2569 declarative part as the function specification.
2571 The @var{Internal} argument must uniquely designate
2572 the function to which the
2573 pragma applies. If more than one function name exists of this name in
2574 the declarative part you must use the @code{Parameter_Types} and
2575 @var{Result_Type} parameters to achieve the required unique
2576 designation. Subtype marks in these parameters must exactly match the
2577 subtypes in the corresponding function specification, using positional
2578 notation to match parameters with subtype marks.
2579 The form with an @code{'Access} attribute can be used to match an
2580 anonymous access parameter.
2582 You may optionally use the @var{Mechanism} and @var{Result_Mechanism}
2583 parameters to specify passing mechanisms for the
2584 parameters and result. If you specify a single mechanism name, it
2585 applies to all parameters. Otherwise you may specify a mechanism on a
2586 parameter by parameter basis using either positional or named
2587 notation. If the mechanism is not specified, the default mechanism
2591 @cindex Passing by descriptor
2592 Passing by descriptor is supported only on the OpenVMS ports of GNAT@.
2593 The default behavior for Import_Function is to pass a 64bit descriptor
2594 unless short_descriptor is specified, then a 32bit descriptor is passed.
2596 @code{First_Optional_Parameter} applies only to OpenVMS ports of GNAT@.
2597 It specifies that the designated parameter and all following parameters
2598 are optional, meaning that they are not passed at the generated code
2599 level (this is distinct from the notion of optional parameters in Ada
2600 where the parameters are passed anyway with the designated optional
2601 parameters). All optional parameters must be of mode @code{IN} and have
2602 default parameter values that are either known at compile time
2603 expressions, or uses of the @code{'Null_Parameter} attribute.
2605 @node Pragma Import_Object
2606 @unnumberedsec Pragma Import_Object
2607 @findex Import_Object
2611 @smallexample @c ada
2612 pragma Import_Object
2613 [Internal =>] LOCAL_NAME
2614 [, [External =>] EXTERNAL_SYMBOL]
2615 [, [Size =>] EXTERNAL_SYMBOL]);
2619 | static_string_EXPRESSION
2623 This pragma designates an object as imported, and apart from the
2624 extended rules for external symbols, is identical in effect to the use of
2625 the normal @code{Import} pragma applied to an object. Unlike the
2626 subprogram case, you need not use a separate @code{Import} pragma,
2627 although you may do so (and probably should do so from a portability
2628 point of view). @var{size} is syntax checked, but otherwise ignored by
2631 @node Pragma Import_Procedure
2632 @unnumberedsec Pragma Import_Procedure
2633 @findex Import_Procedure
2637 @smallexample @c ada
2638 pragma Import_Procedure (
2639 [Internal =>] LOCAL_NAME
2640 [, [External =>] EXTERNAL_SYMBOL]
2641 [, [Parameter_Types =>] PARAMETER_TYPES]
2642 [, [Mechanism =>] MECHANISM]
2643 [, [First_Optional_Parameter =>] IDENTIFIER]);
2647 | static_string_EXPRESSION
2651 | TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@}
2655 | subtype_Name ' Access
2659 | (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@})
2661 MECHANISM_ASSOCIATION ::=
2662 [formal_parameter_NAME =>] MECHANISM_NAME
2667 | Descriptor [([Class =>] CLASS_NAME)]
2668 | Short_Descriptor [([Class =>] CLASS_NAME)]
2670 CLASS_NAME ::= ubs | ubsb | uba | s | sb | a | nca
2674 This pragma is identical to @code{Import_Function} except that it
2675 applies to a procedure rather than a function and the parameters
2676 @code{Result_Type} and @code{Result_Mechanism} are not permitted.
2678 @node Pragma Import_Valued_Procedure
2679 @unnumberedsec Pragma Import_Valued_Procedure
2680 @findex Import_Valued_Procedure
2684 @smallexample @c ada
2685 pragma Import_Valued_Procedure (
2686 [Internal =>] LOCAL_NAME
2687 [, [External =>] EXTERNAL_SYMBOL]
2688 [, [Parameter_Types =>] PARAMETER_TYPES]
2689 [, [Mechanism =>] MECHANISM]
2690 [, [First_Optional_Parameter =>] IDENTIFIER]);
2694 | static_string_EXPRESSION
2698 | TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@}
2702 | subtype_Name ' Access
2706 | (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@})
2708 MECHANISM_ASSOCIATION ::=
2709 [formal_parameter_NAME =>] MECHANISM_NAME
2714 | Descriptor [([Class =>] CLASS_NAME)]
2715 | Short_Descriptor [([Class =>] CLASS_NAME)]
2717 CLASS_NAME ::= ubs | ubsb | uba | s | sb | a | nca
2721 This pragma is identical to @code{Import_Procedure} except that the
2722 first parameter of @var{LOCAL_NAME}, which must be present, must be of
2723 mode @code{OUT}, and externally the subprogram is treated as a function
2724 with this parameter as the result of the function. The purpose of this
2725 capability is to allow the use of @code{OUT} and @code{IN OUT}
2726 parameters in interfacing to external functions (which are not permitted
2727 in Ada functions). You may optionally use the @code{Mechanism}
2728 parameters to specify passing mechanisms for the parameters.
2729 If you specify a single mechanism name, it applies to all parameters.
2730 Otherwise you may specify a mechanism on a parameter by parameter
2731 basis using either positional or named notation. If the mechanism is not
2732 specified, the default mechanism is used.
2734 Note that it is important to use this pragma in conjunction with a separate
2735 pragma Import that specifies the desired convention, since otherwise the
2736 default convention is Ada, which is almost certainly not what is required.
2738 @node Pragma Initialize_Scalars
2739 @unnumberedsec Pragma Initialize_Scalars
2740 @findex Initialize_Scalars
2741 @cindex debugging with Initialize_Scalars
2745 @smallexample @c ada
2746 pragma Initialize_Scalars;
2750 This pragma is similar to @code{Normalize_Scalars} conceptually but has
2751 two important differences. First, there is no requirement for the pragma
2752 to be used uniformly in all units of a partition, in particular, it is fine
2753 to use this just for some or all of the application units of a partition,
2754 without needing to recompile the run-time library.
2756 In the case where some units are compiled with the pragma, and some without,
2757 then a declaration of a variable where the type is defined in package
2758 Standard or is locally declared will always be subject to initialization,
2759 as will any declaration of a scalar variable. For composite variables,
2760 whether the variable is initialized may also depend on whether the package
2761 in which the type of the variable is declared is compiled with the pragma.
2763 The other important difference is that you can control the value used
2764 for initializing scalar objects. At bind time, you can select several
2765 options for initialization. You can
2766 initialize with invalid values (similar to Normalize_Scalars, though for
2767 Initialize_Scalars it is not always possible to determine the invalid
2768 values in complex cases like signed component fields with non-standard
2769 sizes). You can also initialize with high or
2770 low values, or with a specified bit pattern. See the users guide for binder
2771 options for specifying these cases.
2773 This means that you can compile a program, and then without having to
2774 recompile the program, you can run it with different values being used
2775 for initializing otherwise uninitialized values, to test if your program
2776 behavior depends on the choice. Of course the behavior should not change,
2777 and if it does, then most likely you have an erroneous reference to an
2778 uninitialized value.
2780 It is even possible to change the value at execution time eliminating even
2781 the need to rebind with a different switch using an environment variable.
2782 See the GNAT users guide for details.
2784 Note that pragma @code{Initialize_Scalars} is particularly useful in
2785 conjunction with the enhanced validity checking that is now provided
2786 in GNAT, which checks for invalid values under more conditions.
2787 Using this feature (see description of the @option{-gnatV} flag in the
2788 users guide) in conjunction with pragma @code{Initialize_Scalars}
2789 provides a powerful new tool to assist in the detection of problems
2790 caused by uninitialized variables.
2792 Note: the use of @code{Initialize_Scalars} has a fairly extensive
2793 effect on the generated code. This may cause your code to be
2794 substantially larger. It may also cause an increase in the amount
2795 of stack required, so it is probably a good idea to turn on stack
2796 checking (see description of stack checking in the GNAT users guide)
2797 when using this pragma.
2799 @node Pragma Inline_Always
2800 @unnumberedsec Pragma Inline_Always
2801 @findex Inline_Always
2805 @smallexample @c ada
2806 pragma Inline_Always (NAME [, NAME]);
2810 Similar to pragma @code{Inline} except that inlining is not subject to
2811 the use of option @option{-gnatn} and the inlining happens regardless of
2812 whether this option is used.
2814 @node Pragma Inline_Generic
2815 @unnumberedsec Pragma Inline_Generic
2816 @findex Inline_Generic
2820 @smallexample @c ada
2821 pragma Inline_Generic (generic_package_NAME);
2825 This is implemented for compatibility with DEC Ada 83 and is recognized,
2826 but otherwise ignored, by GNAT@. All generic instantiations are inlined
2827 by default when using GNAT@.
2829 @node Pragma Interface
2830 @unnumberedsec Pragma Interface
2835 @smallexample @c ada
2837 [Convention =>] convention_identifier,
2838 [Entity =>] local_NAME
2839 [, [External_Name =>] static_string_expression]
2840 [, [Link_Name =>] static_string_expression]);
2844 This pragma is identical in syntax and semantics to
2845 the standard Ada pragma @code{Import}. It is provided for compatibility
2846 with Ada 83. The definition is upwards compatible both with pragma
2847 @code{Interface} as defined in the Ada 83 Reference Manual, and also
2848 with some extended implementations of this pragma in certain Ada 83
2851 @node Pragma Interface_Name
2852 @unnumberedsec Pragma Interface_Name
2853 @findex Interface_Name
2857 @smallexample @c ada
2858 pragma Interface_Name (
2859 [Entity =>] LOCAL_NAME
2860 [, [External_Name =>] static_string_EXPRESSION]
2861 [, [Link_Name =>] static_string_EXPRESSION]);
2865 This pragma provides an alternative way of specifying the interface name
2866 for an interfaced subprogram, and is provided for compatibility with Ada
2867 83 compilers that use the pragma for this purpose. You must provide at
2868 least one of @var{External_Name} or @var{Link_Name}.
2870 @node Pragma Interrupt_Handler
2871 @unnumberedsec Pragma Interrupt_Handler
2872 @findex Interrupt_Handler
2876 @smallexample @c ada
2877 pragma Interrupt_Handler (procedure_LOCAL_NAME);
2881 This program unit pragma is supported for parameterless protected procedures
2882 as described in Annex C of the Ada Reference Manual. On the AAMP target
2883 the pragma can also be specified for nonprotected parameterless procedures
2884 that are declared at the library level (which includes procedures
2885 declared at the top level of a library package). In the case of AAMP,
2886 when this pragma is applied to a nonprotected procedure, the instruction
2887 @code{IERET} is generated for returns from the procedure, enabling
2888 maskable interrupts, in place of the normal return instruction.
2890 @node Pragma Interrupt_State
2891 @unnumberedsec Pragma Interrupt_State
2892 @findex Interrupt_State
2896 @smallexample @c ada
2897 pragma Interrupt_State
2899 [State =>] SYSTEM | RUNTIME | USER);
2903 Normally certain interrupts are reserved to the implementation. Any attempt
2904 to attach an interrupt causes Program_Error to be raised, as described in
2905 RM C.3.2(22). A typical example is the @code{SIGINT} interrupt used in
2906 many systems for an @kbd{Ctrl-C} interrupt. Normally this interrupt is
2907 reserved to the implementation, so that @kbd{Ctrl-C} can be used to
2908 interrupt execution. Additionally, signals such as @code{SIGSEGV},
2909 @code{SIGABRT}, @code{SIGFPE} and @code{SIGILL} are often mapped to specific
2910 Ada exceptions, or used to implement run-time functions such as the
2911 @code{abort} statement and stack overflow checking.
2913 Pragma @code{Interrupt_State} provides a general mechanism for overriding
2914 such uses of interrupts. It subsumes the functionality of pragma
2915 @code{Unreserve_All_Interrupts}. Pragma @code{Interrupt_State} is not
2916 available on OS/2, Windows or VMS. On all other platforms than VxWorks,
2917 it applies to signals; on VxWorks, it applies to vectored hardware interrupts
2918 and may be used to mark interrupts required by the board support package
2921 Interrupts can be in one of three states:
2925 The interrupt is reserved (no Ada handler can be installed), and the
2926 Ada run-time may not install a handler. As a result you are guaranteed
2927 standard system default action if this interrupt is raised.
2931 The interrupt is reserved (no Ada handler can be installed). The run time
2932 is allowed to install a handler for internal control purposes, but is
2933 not required to do so.
2937 The interrupt is unreserved. The user may install a handler to provide
2942 These states are the allowed values of the @code{State} parameter of the
2943 pragma. The @code{Name} parameter is a value of the type
2944 @code{Ada.Interrupts.Interrupt_ID}. Typically, it is a name declared in
2945 @code{Ada.Interrupts.Names}.
2947 This is a configuration pragma, and the binder will check that there
2948 are no inconsistencies between different units in a partition in how a
2949 given interrupt is specified. It may appear anywhere a pragma is legal.
2951 The effect is to move the interrupt to the specified state.
2953 By declaring interrupts to be SYSTEM, you guarantee the standard system
2954 action, such as a core dump.
2956 By declaring interrupts to be USER, you guarantee that you can install
2959 Note that certain signals on many operating systems cannot be caught and
2960 handled by applications. In such cases, the pragma is ignored. See the
2961 operating system documentation, or the value of the array @code{Reserved}
2962 declared in the spec of package @code{System.OS_Interface}.
2964 Overriding the default state of signals used by the Ada runtime may interfere
2965 with an application's runtime behavior in the cases of the synchronous signals,
2966 and in the case of the signal used to implement the @code{abort} statement.
2968 @node Pragma Keep_Names
2969 @unnumberedsec Pragma Keep_Names
2974 @smallexample @c ada
2975 pragma Keep_Names ([On =>] enumeration_first_subtype_LOCAL_NAME);
2979 The @var{LOCAL_NAME} argument
2980 must refer to an enumeration first subtype
2981 in the current declarative part. The effect is to retain the enumeration
2982 literal names for use by @code{Image} and @code{Value} even if a global
2983 @code{Discard_Names} pragma applies. This is useful when you want to
2984 generally suppress enumeration literal names and for example you therefore
2985 use a @code{Discard_Names} pragma in the @file{gnat.adc} file, but you
2986 want to retain the names for specific enumeration types.
2988 @node Pragma License
2989 @unnumberedsec Pragma License
2991 @cindex License checking
2995 @smallexample @c ada
2996 pragma License (Unrestricted | GPL | Modified_GPL | Restricted);
3000 This pragma is provided to allow automated checking for appropriate license
3001 conditions with respect to the standard and modified GPL@. A pragma
3002 @code{License}, which is a configuration pragma that typically appears at
3003 the start of a source file or in a separate @file{gnat.adc} file, specifies
3004 the licensing conditions of a unit as follows:
3008 This is used for a unit that can be freely used with no license restrictions.
3009 Examples of such units are public domain units, and units from the Ada
3013 This is used for a unit that is licensed under the unmodified GPL, and which
3014 therefore cannot be @code{with}'ed by a restricted unit.
3017 This is used for a unit licensed under the GNAT modified GPL that includes
3018 a special exception paragraph that specifically permits the inclusion of
3019 the unit in programs without requiring the entire program to be released
3023 This is used for a unit that is restricted in that it is not permitted to
3024 depend on units that are licensed under the GPL@. Typical examples are
3025 proprietary code that is to be released under more restrictive license
3026 conditions. Note that restricted units are permitted to @code{with} units
3027 which are licensed under the modified GPL (this is the whole point of the
3033 Normally a unit with no @code{License} pragma is considered to have an
3034 unknown license, and no checking is done. However, standard GNAT headers
3035 are recognized, and license information is derived from them as follows.
3039 A GNAT license header starts with a line containing 78 hyphens. The following
3040 comment text is searched for the appearance of any of the following strings.
3042 If the string ``GNU General Public License'' is found, then the unit is assumed
3043 to have GPL license, unless the string ``As a special exception'' follows, in
3044 which case the license is assumed to be modified GPL@.
3046 If one of the strings
3047 ``This specification is adapted from the Ada Semantic Interface'' or
3048 ``This specification is derived from the Ada Reference Manual'' is found
3049 then the unit is assumed to be unrestricted.
3053 These default actions means that a program with a restricted license pragma
3054 will automatically get warnings if a GPL unit is inappropriately
3055 @code{with}'ed. For example, the program:
3057 @smallexample @c ada
3060 procedure Secret_Stuff is
3066 if compiled with pragma @code{License} (@code{Restricted}) in a
3067 @file{gnat.adc} file will generate the warning:
3072 >>> license of withed unit "Sem_Ch3" is incompatible
3074 2. with GNAT.Sockets;
3075 3. procedure Secret_Stuff is
3079 Here we get a warning on @code{Sem_Ch3} since it is part of the GNAT
3080 compiler and is licensed under the
3081 GPL, but no warning for @code{GNAT.Sockets} which is part of the GNAT
3082 run time, and is therefore licensed under the modified GPL@.
3084 @node Pragma Link_With
3085 @unnumberedsec Pragma Link_With
3090 @smallexample @c ada
3091 pragma Link_With (static_string_EXPRESSION @{,static_string_EXPRESSION@});
3095 This pragma is provided for compatibility with certain Ada 83 compilers.
3096 It has exactly the same effect as pragma @code{Linker_Options} except
3097 that spaces occurring within one of the string expressions are treated
3098 as separators. For example, in the following case:
3100 @smallexample @c ada
3101 pragma Link_With ("-labc -ldef");
3105 results in passing the strings @code{-labc} and @code{-ldef} as two
3106 separate arguments to the linker. In addition pragma Link_With allows
3107 multiple arguments, with the same effect as successive pragmas.
3109 @node Pragma Linker_Alias
3110 @unnumberedsec Pragma Linker_Alias
3111 @findex Linker_Alias
3115 @smallexample @c ada
3116 pragma Linker_Alias (
3117 [Entity =>] LOCAL_NAME,
3118 [Target =>] static_string_EXPRESSION);
3122 @var{LOCAL_NAME} must refer to an object that is declared at the library
3123 level. This pragma establishes the given entity as a linker alias for the
3124 given target. It is equivalent to @code{__attribute__((alias))} in GNU C
3125 and causes @var{LOCAL_NAME} to be emitted as an alias for the symbol
3126 @var{static_string_EXPRESSION} in the object file, that is to say no space
3127 is reserved for @var{LOCAL_NAME} by the assembler and it will be resolved
3128 to the same address as @var{static_string_EXPRESSION} by the linker.
3130 The actual linker name for the target must be used (e.g.@: the fully
3131 encoded name with qualification in Ada, or the mangled name in C++),
3132 or it must be declared using the C convention with @code{pragma Import}
3133 or @code{pragma Export}.
3135 Not all target machines support this pragma. On some of them it is accepted
3136 only if @code{pragma Weak_External} has been applied to @var{LOCAL_NAME}.
3138 @smallexample @c ada
3139 -- Example of the use of pragma Linker_Alias
3143 pragma Export (C, i);
3145 new_name_for_i : Integer;
3146 pragma Linker_Alias (new_name_for_i, "i");
3150 @node Pragma Linker_Constructor
3151 @unnumberedsec Pragma Linker_Constructor
3152 @findex Linker_Constructor
3156 @smallexample @c ada
3157 pragma Linker_Constructor (procedure_LOCAL_NAME);
3161 @var{procedure_LOCAL_NAME} must refer to a parameterless procedure that
3162 is declared at the library level. A procedure to which this pragma is
3163 applied will be treated as an initialization routine by the linker.
3164 It is equivalent to @code{__attribute__((constructor))} in GNU C and
3165 causes @var{procedure_LOCAL_NAME} to be invoked before the entry point
3166 of the executable is called (or immediately after the shared library is
3167 loaded if the procedure is linked in a shared library), in particular
3168 before the Ada run-time environment is set up.
3170 Because of these specific contexts, the set of operations such a procedure
3171 can perform is very limited and the type of objects it can manipulate is
3172 essentially restricted to the elementary types. In particular, it must only
3173 contain code to which pragma Restrictions (No_Elaboration_Code) applies.
3175 This pragma is used by GNAT to implement auto-initialization of shared Stand
3176 Alone Libraries, which provides a related capability without the restrictions
3177 listed above. Where possible, the use of Stand Alone Libraries is preferable
3178 to the use of this pragma.
3180 @node Pragma Linker_Destructor
3181 @unnumberedsec Pragma Linker_Destructor
3182 @findex Linker_Destructor
3186 @smallexample @c ada
3187 pragma Linker_Destructor (procedure_LOCAL_NAME);
3191 @var{procedure_LOCAL_NAME} must refer to a parameterless procedure that
3192 is declared at the library level. A procedure to which this pragma is
3193 applied will be treated as a finalization routine by the linker.
3194 It is equivalent to @code{__attribute__((destructor))} in GNU C and
3195 causes @var{procedure_LOCAL_NAME} to be invoked after the entry point
3196 of the executable has exited (or immediately before the shared library
3197 is unloaded if the procedure is linked in a shared library), in particular
3198 after the Ada run-time environment is shut down.
3200 See @code{pragma Linker_Constructor} for the set of restrictions that apply
3201 because of these specific contexts.
3203 @node Pragma Linker_Section
3204 @unnumberedsec Pragma Linker_Section
3205 @findex Linker_Section
3209 @smallexample @c ada
3210 pragma Linker_Section (
3211 [Entity =>] LOCAL_NAME,
3212 [Section =>] static_string_EXPRESSION);
3216 @var{LOCAL_NAME} must refer to an object that is declared at the library
3217 level. This pragma specifies the name of the linker section for the given
3218 entity. It is equivalent to @code{__attribute__((section))} in GNU C and
3219 causes @var{LOCAL_NAME} to be placed in the @var{static_string_EXPRESSION}
3220 section of the executable (assuming the linker doesn't rename the section).
3222 The compiler normally places library-level objects in standard sections
3223 depending on their type: procedures and functions generally go in the
3224 @code{.text} section, initialized variables in the @code{.data} section
3225 and uninitialized variables in the @code{.bss} section.
3227 Other, special sections may exist on given target machines to map special
3228 hardware, for example I/O ports or flash memory. This pragma is a means to
3229 defer the final layout of the executable to the linker, thus fully working
3230 at the symbolic level with the compiler.
3232 Some file formats do not support arbitrary sections so not all target
3233 machines support this pragma. The use of this pragma may cause a program
3234 execution to be erroneous if it is used to place an entity into an
3235 inappropriate section (e.g.@: a modified variable into the @code{.text}
3236 section). See also @code{pragma Persistent_BSS}.
3238 @smallexample @c ada
3239 -- Example of the use of pragma Linker_Section
3243 pragma Volatile (Port_A);
3244 pragma Linker_Section (Port_A, ".bss.port_a");
3247 pragma Volatile (Port_B);
3248 pragma Linker_Section (Port_B, ".bss.port_b");
3252 @node Pragma Long_Float
3253 @unnumberedsec Pragma Long_Float
3259 @smallexample @c ada
3260 pragma Long_Float (FLOAT_FORMAT);
3262 FLOAT_FORMAT ::= D_Float | G_Float
3266 This pragma is implemented only in the OpenVMS implementation of GNAT@.
3267 It allows control over the internal representation chosen for the predefined
3268 type @code{Long_Float} and for floating point type representations with
3269 @code{digits} specified in the range 7 through 15.
3270 For further details on this pragma, see the
3271 @cite{DEC Ada Language Reference Manual}, section 3.5.7b. Note that to use
3272 this pragma, the standard runtime libraries must be recompiled.
3273 @xref{The GNAT Run-Time Library Builder gnatlbr,,, gnat_ugn,
3274 @value{EDITION} User's Guide OpenVMS}, for a description of the
3275 @code{GNAT LIBRARY} command.
3277 @node Pragma Machine_Attribute
3278 @unnumberedsec Pragma Machine_Attribute
3279 @findex Machine_Attribute
3283 @smallexample @c ada
3284 pragma Machine_Attribute (
3285 [Entity =>] LOCAL_NAME,
3286 [Attribute_Name =>] static_string_EXPRESSION
3287 [, [Info =>] static_EXPRESSION] );
3291 Machine-dependent attributes can be specified for types and/or
3292 declarations. This pragma is semantically equivalent to
3293 @code{__attribute__((@var{attribute_name}))} (if @var{info} is not
3294 specified) or @code{__attribute__((@var{attribute_name}(@var{info})))}
3295 in GNU C, where @code{@var{attribute_name}} is recognized by the
3296 compiler middle-end or the @code{TARGET_ATTRIBUTE_TABLE} machine
3297 specific macro. A string literal for the optional parameter @var{info}
3298 is transformed into an identifier, which may make this pragma unusable
3299 for some attributes. @xref{Target Attributes,, Defining target-specific
3300 uses of @code{__attribute__}, gccint, GNU Compiler Collection (GCC)
3301 Internals}, further information.
3304 @unnumberedsec Pragma Main
3310 @smallexample @c ada
3312 (MAIN_OPTION [, MAIN_OPTION]);
3315 [Stack_Size =>] static_integer_EXPRESSION
3316 | [Task_Stack_Size_Default =>] static_integer_EXPRESSION
3317 | [Time_Slicing_Enabled =>] static_boolean_EXPRESSION
3321 This pragma is provided for compatibility with OpenVMS VAX Systems. It has
3322 no effect in GNAT, other than being syntax checked.
3324 @node Pragma Main_Storage
3325 @unnumberedsec Pragma Main_Storage
3327 @findex Main_Storage
3331 @smallexample @c ada
3333 (MAIN_STORAGE_OPTION [, MAIN_STORAGE_OPTION]);
3335 MAIN_STORAGE_OPTION ::=
3336 [WORKING_STORAGE =>] static_SIMPLE_EXPRESSION
3337 | [TOP_GUARD =>] static_SIMPLE_EXPRESSION
3341 This pragma is provided for compatibility with OpenVMS VAX Systems. It has
3342 no effect in GNAT, other than being syntax checked. Note that the pragma
3343 also has no effect in DEC Ada 83 for OpenVMS Alpha Systems.
3345 @node Pragma No_Body
3346 @unnumberedsec Pragma No_Body
3351 @smallexample @c ada
3356 There are a number of cases in which a package spec does not require a body,
3357 and in fact a body is not permitted. GNAT will not permit the spec to be
3358 compiled if there is a body around. The pragma No_Body allows you to provide
3359 a body file, even in a case where no body is allowed. The body file must
3360 contain only comments and a single No_Body pragma. This is recognized by
3361 the compiler as indicating that no body is logically present.
3363 This is particularly useful during maintenance when a package is modified in
3364 such a way that a body needed before is no longer needed. The provision of a
3365 dummy body with a No_Body pragma ensures that there is no interference from
3366 earlier versions of the package body.
3368 @node Pragma No_Return
3369 @unnumberedsec Pragma No_Return
3374 @smallexample @c ada
3375 pragma No_Return (procedure_LOCAL_NAME @{, procedure_LOCAL_NAME@});
3379 Each @var{procedure_LOCAL_NAME} argument must refer to one or more procedure
3380 declarations in the current declarative part. A procedure to which this
3381 pragma is applied may not contain any explicit @code{return} statements.
3382 In addition, if the procedure contains any implicit returns from falling
3383 off the end of a statement sequence, then execution of that implicit
3384 return will cause Program_Error to be raised.
3386 One use of this pragma is to identify procedures whose only purpose is to raise
3387 an exception. Another use of this pragma is to suppress incorrect warnings
3388 about missing returns in functions, where the last statement of a function
3389 statement sequence is a call to such a procedure.
3391 Note that in Ada 2005 mode, this pragma is part of the language, and is
3392 identical in effect to the pragma as implemented in Ada 95 mode.
3394 @node Pragma No_Strict_Aliasing
3395 @unnumberedsec Pragma No_Strict_Aliasing
3396 @findex No_Strict_Aliasing
3400 @smallexample @c ada
3401 pragma No_Strict_Aliasing [([Entity =>] type_LOCAL_NAME)];
3405 @var{type_LOCAL_NAME} must refer to an access type
3406 declaration in the current declarative part. The effect is to inhibit
3407 strict aliasing optimization for the given type. The form with no
3408 arguments is a configuration pragma which applies to all access types
3409 declared in units to which the pragma applies. For a detailed
3410 description of the strict aliasing optimization, and the situations
3411 in which it must be suppressed, see @ref{Optimization and Strict
3412 Aliasing,,, gnat_ugn, @value{EDITION} User's Guide}.
3414 @node Pragma Normalize_Scalars
3415 @unnumberedsec Pragma Normalize_Scalars
3416 @findex Normalize_Scalars
3420 @smallexample @c ada
3421 pragma Normalize_Scalars;
3425 This is a language defined pragma which is fully implemented in GNAT@. The
3426 effect is to cause all scalar objects that are not otherwise initialized
3427 to be initialized. The initial values are implementation dependent and
3431 @item Standard.Character
3433 Objects whose root type is Standard.Character are initialized to
3434 Character'Last unless the subtype range excludes NUL (in which case
3435 NUL is used). This choice will always generate an invalid value if
3438 @item Standard.Wide_Character
3440 Objects whose root type is Standard.Wide_Character are initialized to
3441 Wide_Character'Last unless the subtype range excludes NUL (in which case
3442 NUL is used). This choice will always generate an invalid value if
3445 @item Standard.Wide_Wide_Character
3447 Objects whose root type is Standard.Wide_Wide_Character are initialized to
3448 the invalid value 16#FFFF_FFFF# unless the subtype range excludes NUL (in
3449 which case NUL is used). This choice will always generate an invalid value if
3454 Objects of an integer type are treated differently depending on whether
3455 negative values are present in the subtype. If no negative values are
3456 present, then all one bits is used as the initial value except in the
3457 special case where zero is excluded from the subtype, in which case
3458 all zero bits are used. This choice will always generate an invalid
3459 value if one exists.
3461 For subtypes with negative values present, the largest negative number
3462 is used, except in the unusual case where this largest negative number
3463 is in the subtype, and the largest positive number is not, in which case
3464 the largest positive value is used. This choice will always generate
3465 an invalid value if one exists.
3467 @item Floating-Point Types
3468 Objects of all floating-point types are initialized to all 1-bits. For
3469 standard IEEE format, this corresponds to a NaN (not a number) which is
3470 indeed an invalid value.
3472 @item Fixed-Point Types
3473 Objects of all fixed-point types are treated as described above for integers,
3474 with the rules applying to the underlying integer value used to represent
3475 the fixed-point value.
3478 Objects of a modular type are initialized to all one bits, except in
3479 the special case where zero is excluded from the subtype, in which
3480 case all zero bits are used. This choice will always generate an
3481 invalid value if one exists.
3483 @item Enumeration types
3484 Objects of an enumeration type are initialized to all one-bits, i.e.@: to
3485 the value @code{2 ** typ'Size - 1} unless the subtype excludes the literal
3486 whose Pos value is zero, in which case a code of zero is used. This choice
3487 will always generate an invalid value if one exists.
3491 @node Pragma Obsolescent
3492 @unnumberedsec Pragma Obsolescent
3497 @smallexample @c ada
3500 pragma Obsolescent (
3501 [Message =>] static_string_EXPRESSION
3502 [,[Version =>] Ada_05]]);
3504 pragma Obsolescent (
3506 [,[Message =>] static_string_EXPRESSION
3507 [,[Version =>] Ada_05]] );
3511 This pragma can occur immediately following a declaration of an entity,
3512 including the case of a record component. If no Entity argument is present,
3513 then this declaration is the one to which the pragma applies. If an Entity
3514 parameter is present, it must either match the name of the entity in this
3515 declaration, or alternatively, the pragma can immediately follow an enumeration
3516 type declaration, where the Entity argument names one of the enumeration
3519 This pragma is used to indicate that the named entity
3520 is considered obsolescent and should not be used. Typically this is
3521 used when an API must be modified by eventually removing or modifying
3522 existing subprograms or other entities. The pragma can be used at an
3523 intermediate stage when the entity is still present, but will be
3526 The effect of this pragma is to output a warning message on a reference to
3527 an entity thus marked that the subprogram is obsolescent if the appropriate
3528 warning option in the compiler is activated. If the Message parameter is
3529 present, then a second warning message is given containing this text. In
3530 addition, a reference to the eneity is considered to be a violation of pragma
3531 Restrictions (No_Obsolescent_Features).
3533 This pragma can also be used as a program unit pragma for a package,
3534 in which case the entity name is the name of the package, and the
3535 pragma indicates that the entire package is considered
3536 obsolescent. In this case a client @code{with}'ing such a package
3537 violates the restriction, and the @code{with} statement is
3538 flagged with warnings if the warning option is set.
3540 If the Version parameter is present (which must be exactly
3541 the identifier Ada_05, no other argument is allowed), then the
3542 indication of obsolescence applies only when compiling in Ada 2005
3543 mode. This is primarily intended for dealing with the situations
3544 in the predefined library where subprograms or packages
3545 have become defined as obsolescent in Ada 2005
3546 (e.g.@: in Ada.Characters.Handling), but may be used anywhere.
3548 The following examples show typical uses of this pragma:
3550 @smallexample @c ada
3552 pragma Obsolescent (p, Message => "use pp instead of p");
3557 pragma Obsolescent ("use q2new instead");
3559 type R is new integer;
3562 Message => "use RR in Ada 2005",
3572 type E is (a, bc, 'd', quack);
3573 pragma Obsolescent (Entity => bc)
3574 pragma Obsolescent (Entity => 'd')
3577 (a, b : character) return character;
3578 pragma Obsolescent (Entity => "+");
3583 Note that, as for all pragmas, if you use a pragma argument identifier,
3584 then all subsequent parameters must also use a pragma argument identifier.
3585 So if you specify "Entity =>" for the Entity argument, and a Message
3586 argument is present, it must be preceded by "Message =>".
3588 @node Pragma Optimize_Alignment
3589 @unnumberedsec Pragma Optimize_Alignment
3590 @findex Optimize_Alignment
3591 @cindex Alignment, default settings
3595 @smallexample @c ada
3596 pragma Optimize_Alignment (TIME | SPACE | OFF);
3600 This is a configuration pragma which affects the choice of default alignments
3601 for types where no alignment is explicitly specified. There is a time/space
3602 trade-off in the selection of these values. Large alignments result in more
3603 efficient code, at the expense of larger data space, since sizes have to be
3604 increased to match these alignments. Smaller alignments save space, but the
3605 access code is slower. The normal choice of default alignments (which is what
3606 you get if you do not use this pragma, or if you use an argument of OFF),
3607 tries to balance these two requirements.
3609 Specifying SPACE causes smaller default alignments to be chosen in two cases.
3610 First any packed record is given an alignment of 1. Second, if a size is given
3611 for the type, then the alignment is chosen to avoid increasing this size. For
3614 @smallexample @c ada
3624 In the default mode, this type gets an alignment of 4, so that access to the
3625 Integer field X are efficient. But this means that objects of the type end up
3626 with a size of 8 bytes. This is a valid choice, since sizes of objects are
3627 allowed to be bigger than the size of the type, but it can waste space if for
3628 example fields of type R appear in an enclosing record. If the above type is
3629 compiled in @code{Optimize_Alignment (Space)} mode, the alignment is set to 1.
3631 Specifying TIME causes larger default alignments to be chosen in the case of
3632 small types with sizes that are not a power of 2. For example, consider:
3634 @smallexample @c ada
3646 The default alignment for this record is normally 1, but if this type is
3647 compiled in @code{Optimize_Alignment (Time)} mode, then the alignment is set
3648 to 4, which wastes space for objects of the type, since they are now 4 bytes
3649 long, but results in more efficient access when the whole record is referenced.
3651 As noted above, this is a configuration pragma, and there is a requirement
3652 that all units in a partition be compiled with a consistent setting of the
3653 optimization setting. This would normally be achieved by use of a configuration
3654 pragma file containing the appropriate setting. The exception to this rule is
3655 that units with an explicit configuration pragma in the same file as the source
3656 unit are excluded from the consistency check, as are all predefined units. The
3657 latter are compiled by default in pragma Optimize_Alignment (Off) mode if no
3658 pragma appears at the start of the file.
3660 @node Pragma Passive
3661 @unnumberedsec Pragma Passive
3666 @smallexample @c ada
3667 pragma Passive [(Semaphore | No)];
3671 Syntax checked, but otherwise ignored by GNAT@. This is recognized for
3672 compatibility with DEC Ada 83 implementations, where it is used within a
3673 task definition to request that a task be made passive. If the argument
3674 @code{Semaphore} is present, or the argument is omitted, then DEC Ada 83
3675 treats the pragma as an assertion that the containing task is passive
3676 and that optimization of context switch with this task is permitted and
3677 desired. If the argument @code{No} is present, the task must not be
3678 optimized. GNAT does not attempt to optimize any tasks in this manner
3679 (since protected objects are available in place of passive tasks).
3681 @node Pragma Persistent_BSS
3682 @unnumberedsec Pragma Persistent_BSS
3683 @findex Persistent_BSS
3687 @smallexample @c ada
3688 pragma Persistent_BSS [(LOCAL_NAME)]
3692 This pragma allows selected objects to be placed in the @code{.persistent_bss}
3693 section. On some targets the linker and loader provide for special
3694 treatment of this section, allowing a program to be reloaded without
3695 affecting the contents of this data (hence the name persistent).
3697 There are two forms of usage. If an argument is given, it must be the
3698 local name of a library level object, with no explicit initialization
3699 and whose type is potentially persistent. If no argument is given, then
3700 the pragma is a configuration pragma, and applies to all library level
3701 objects with no explicit initialization of potentially persistent types.
3703 A potentially persistent type is a scalar type, or a non-tagged,
3704 non-discriminated record, all of whose components have no explicit
3705 initialization and are themselves of a potentially persistent type,
3706 or an array, all of whose constraints are static, and whose component
3707 type is potentially persistent.
3709 If this pragma is used on a target where this feature is not supported,
3710 then the pragma will be ignored. See also @code{pragma Linker_Section}.
3712 @node Pragma Polling
3713 @unnumberedsec Pragma Polling
3718 @smallexample @c ada
3719 pragma Polling (ON | OFF);
3723 This pragma controls the generation of polling code. This is normally off.
3724 If @code{pragma Polling (ON)} is used then periodic calls are generated to
3725 the routine @code{Ada.Exceptions.Poll}. This routine is a separate unit in the
3726 runtime library, and can be found in file @file{a-excpol.adb}.
3728 Pragma @code{Polling} can appear as a configuration pragma (for example it
3729 can be placed in the @file{gnat.adc} file) to enable polling globally, or it
3730 can be used in the statement or declaration sequence to control polling
3733 A call to the polling routine is generated at the start of every loop and
3734 at the start of every subprogram call. This guarantees that the @code{Poll}
3735 routine is called frequently, and places an upper bound (determined by
3736 the complexity of the code) on the period between two @code{Poll} calls.
3738 The primary purpose of the polling interface is to enable asynchronous
3739 aborts on targets that cannot otherwise support it (for example Windows
3740 NT), but it may be used for any other purpose requiring periodic polling.
3741 The standard version is null, and can be replaced by a user program. This
3742 will require re-compilation of the @code{Ada.Exceptions} package that can
3743 be found in files @file{a-except.ads} and @file{a-except.adb}.
3745 A standard alternative unit (in file @file{4wexcpol.adb} in the standard GNAT
3746 distribution) is used to enable the asynchronous abort capability on
3747 targets that do not normally support the capability. The version of
3748 @code{Poll} in this file makes a call to the appropriate runtime routine
3749 to test for an abort condition.
3751 Note that polling can also be enabled by use of the @option{-gnatP} switch.
3752 @xref{Switches for gcc,,, gnat_ugn, @value{EDITION} User's Guide}, for
3755 @node Pragma Postcondition
3756 @unnumberedsec Pragma Postcondition
3757 @cindex Postconditions
3758 @cindex Checks, postconditions
3759 @findex Postconditions
3763 @smallexample @c ada
3764 pragma Postcondition (
3765 [Check =>] Boolean_Expression
3766 [,[Message =>] String_Expression]);
3770 The @code{Postcondition} pragma allows specification of automatic
3771 postcondition checks for subprograms. These checks are similar to
3772 assertions, but are automatically inserted just prior to the return
3773 statements of the subprogram with which they are associated (including
3774 implicit returns at the end of procedure bodies and associated
3775 exception handlers).
3777 In addition, the boolean expression which is the condition which
3778 must be true may contain references to function'Result in the case
3779 of a function to refer to the returned value.
3781 @code{Postcondition} pragmas may appear either immediate following the
3782 (separate) declaration of a subprogram, or at the start of the
3783 declarations of a subprogram body. Only other pragmas may intervene
3784 (that is appear between the subprogram declaration and its
3785 postconditions, or appear before the postcondition in the
3786 declaration sequence in a subprogram body). In the case of a
3787 postcondition appearing after a subprogram declaration, the
3788 formal arguments of the subprogram are visible, and can be
3789 referenced in the postcondition expressions.
3791 The postconditions are collected and automatically tested just
3792 before any return (implicit or explicit) in the subprogram body.
3793 A postcondition is only recognized if postconditions are active
3794 at the time the pragma is encountered. The compiler switch @option{gnata}
3795 turns on all postconditions by default, and pragma @code{Check_Policy}
3796 with an identifier of @code{Postcondition} can also be used to
3797 control whether postconditions are active.
3799 The general approach is that postconditions are placed in the spec
3800 if they represent functional aspects which make sense to the client.
3801 For example we might have:
3803 @smallexample @c ada
3804 function Direction return Integer;
3805 pragma Postcondition
3806 (Direction'Result = +1
3808 Direction'Result = -1);
3812 which serves to document that the result must be +1 or -1, and
3813 will test that this is the case at run time if postcondition
3816 Postconditions within the subprogram body can be used to
3817 check that some internal aspect of the implementation,
3818 not visible to the client, is operating as expected.
3819 For instance if a square root routine keeps an internal
3820 counter of the number of times it is called, then we
3821 might have the following postcondition:
3823 @smallexample @c ada
3824 Sqrt_Calls : Natural := 0;
3826 function Sqrt (Arg : Float) return Float is
3827 pragma Postcondition
3828 (Sqrt_Calls = Sqrt_Calls'Old + 1);
3834 As this example, shows, the use of the @code{Old} attribute
3835 is often useful in postconditions to refer to the state on
3836 entry to the subprogram.
3838 Note that postconditions are only checked on normal returns
3839 from the subprogram. If an abnormal return results from
3840 raising an exception, then the postconditions are not checked.
3842 If a postcondition fails, then the exception
3843 @code{System.Assertions.Assert_Failure} is raised. If
3844 a message argument was supplied, then the given string
3845 will be used as the exception message. If no message
3846 argument was supplied, then the default message has
3847 the form "Postcondition failed at file:line". The
3848 exception is raised in the context of the subprogram
3849 body, so it is possible to catch postcondition failures
3850 within the subprogram body itself.
3852 Within a package spec, normal visibility rules
3853 in Ada would prevent forward references within a
3854 postcondition pragma to functions defined later in
3855 the same package. This would introduce undesirable
3856 ordering constraints. To avoid this problem, all
3857 postcondition pragmas are analyzed at the end of
3858 the package spec, allowing forward references.
3860 The following example shows that this even allows
3861 mutually recursive postconditions as in:
3863 @smallexample @c ada
3864 package Parity_Functions is
3865 function Odd (X : Natural) return Boolean;
3866 pragma Postcondition
3870 (x /= 0 and then Even (X - 1))));
3872 function Even (X : Natural) return Boolean;
3873 pragma Postcondition
3877 (x /= 1 and then Odd (X - 1))));
3879 end Parity_Functions;
3883 There are no restrictions on the complexity or form of
3884 conditions used within @code{Postcondition} pragmas.
3885 The following example shows that it is even possible
3886 to verify performance behavior.
3888 @smallexample @c ada
3891 Performance : constant Float;
3892 -- Performance constant set by implementation
3893 -- to match target architecture behavior.
3895 procedure Treesort (Arg : String);
3896 -- Sorts characters of argument using N*logN sort
3897 pragma Postcondition
3898 (Float (Clock - Clock'Old) <=
3899 Float (Arg'Length) *
3900 log (Float (Arg'Length)) *
3906 Note: postcondition pragmas associated with subprograms that are
3907 marked as Inline_Always, or those marked as Inline with front-end
3908 inlining (-gnatN option set) are accepted and legality-checked
3909 by the compiler, but are ignored at run-time even if postcondition
3910 checking is enabled.
3912 @node Pragma Precondition
3913 @unnumberedsec Pragma Precondition
3914 @cindex Preconditions
3915 @cindex Checks, preconditions
3916 @findex Preconditions
3920 @smallexample @c ada
3921 pragma Precondition (
3922 [Check =>] Boolean_Expression
3923 [,[Message =>] String_Expression]);
3927 The @code{Precondition} pragma is similar to @code{Postcondition}
3928 except that the corresponding checks take place immediately upon
3929 entry to the subprogram, and if a precondition fails, the exception
3930 is raised in the context of the caller, and the attribute 'Result
3931 cannot be used within the precondition expression.
3933 Otherwise, the placement and visibility rules are identical to those
3934 described for postconditions. The following is an example of use
3935 within a package spec:
3937 @smallexample @c ada
3938 package Math_Functions is
3940 function Sqrt (Arg : Float) return Float;
3941 pragma Precondition (Arg >= 0.0)
3947 @code{Precondition} pragmas may appear either immediate following the
3948 (separate) declaration of a subprogram, or at the start of the
3949 declarations of a subprogram body. Only other pragmas may intervene
3950 (that is appear between the subprogram declaration and its
3951 postconditions, or appear before the postcondition in the
3952 declaration sequence in a subprogram body).
3954 Note: postcondition pragmas associated with subprograms that are
3955 marked as Inline_Always, or those marked as Inline with front-end
3956 inlining (-gnatN option set) are accepted and legality-checked
3957 by the compiler, but are ignored at run-time even if postcondition
3958 checking is enabled.
3962 @node Pragma Profile (Ravenscar)
3963 @unnumberedsec Pragma Profile (Ravenscar)
3968 @smallexample @c ada
3969 pragma Profile (Ravenscar);
3973 A configuration pragma that establishes the following set of configuration
3977 @item Task_Dispatching_Policy (FIFO_Within_Priorities)
3978 [RM D.2.2] Tasks are dispatched following a preemptive
3979 priority-ordered scheduling policy.
3981 @item Locking_Policy (Ceiling_Locking)
3982 [RM D.3] While tasks and interrupts execute a protected action, they inherit
3983 the ceiling priority of the corresponding protected object.
3985 @c @item Detect_Blocking
3986 @c This pragma forces the detection of potentially blocking operations within a
3987 @c protected operation, and to raise Program_Error if that happens.
3991 plus the following set of restrictions:
3994 @item Max_Entry_Queue_Length = 1
3995 Defines the maximum number of calls that are queued on a (protected) entry.
3996 Note that this restrictions is checked at run time. Violation of this
3997 restriction results in the raising of Program_Error exception at the point of
3998 the call. For the Profile (Ravenscar) the value of Max_Entry_Queue_Length is
3999 always 1 and hence no task can be queued on a protected entry.
4001 @item Max_Protected_Entries = 1
4002 [RM D.7] Specifies the maximum number of entries per protected type. The
4003 bounds of every entry family of a protected unit shall be static, or shall be
4004 defined by a discriminant of a subtype whose corresponding bound is static.
4005 For the Profile (Ravenscar) the value of Max_Protected_Entries is always 1.
4007 @item Max_Task_Entries = 0
4008 [RM D.7] Specifies the maximum number of entries
4009 per task. The bounds of every entry family
4010 of a task unit shall be static, or shall be
4011 defined by a discriminant of a subtype whose
4012 corresponding bound is static. A value of zero
4013 indicates that no rendezvous are possible. For
4014 the Profile (Ravenscar), the value of Max_Task_Entries is always
4017 @item No_Abort_Statements
4018 [RM D.7] There are no abort_statements, and there are
4019 no calls to Task_Identification.Abort_Task.
4021 @item No_Asynchronous_Control
4022 There are no semantic dependences on the package
4023 Asynchronous_Task_Control.
4026 There are no semantic dependencies on the package Ada.Calendar.
4028 @item No_Dynamic_Attachment
4029 There is no call to any of the operations defined in package Ada.Interrupts
4030 (Is_Reserved, Is_Attached, Current_Handler, Attach_Handler, Exchange_Handler,
4031 Detach_Handler, and Reference).
4033 @item No_Dynamic_Priorities
4034 [RM D.7] There are no semantic dependencies on the package Dynamic_Priorities.
4036 @item No_Implicit_Heap_Allocations
4037 [RM D.7] No constructs are allowed to cause implicit heap allocation.
4039 @item No_Local_Protected_Objects
4040 Protected objects and access types that designate
4041 such objects shall be declared only at library level.
4043 @item No_Local_Timing_Events
4044 [RM D.7] All objects of type Ada.Timing_Events.Timing_Event are
4045 declared at the library level.
4047 @item No_Protected_Type_Allocators
4048 There are no allocators for protected types or
4049 types containing protected subcomponents.
4051 @item No_Relative_Delay
4052 There are no delay_relative statements.
4054 @item No_Requeue_Statements
4055 Requeue statements are not allowed.
4057 @item No_Select_Statements
4058 There are no select_statements.
4060 @item No_Specific_Termination_Handlers
4061 [RM D.7] There are no calls to Ada.Task_Termination.Set_Specific_Handler
4062 or to Ada.Task_Termination.Specific_Handler.
4064 @item No_Task_Allocators
4065 [RM D.7] There are no allocators for task types
4066 or types containing task subcomponents.
4068 @item No_Task_Attributes_Package
4069 There are no semantic dependencies on the Ada.Task_Attributes package.
4071 @item No_Task_Hierarchy
4072 [RM D.7] All (non-environment) tasks depend
4073 directly on the environment task of the partition.
4075 @item No_Task_Termination
4076 Tasks which terminate are erroneous.
4078 @item No_Unchecked_Conversion
4079 There are no semantic dependencies on the Ada.Unchecked_Conversion package.
4081 @item No_Unchecked_Deallocation
4082 There are no semantic dependencies on the Ada.Unchecked_Deallocation package.
4084 @item Simple_Barriers
4085 Entry barrier condition expressions shall be either static
4086 boolean expressions or boolean objects which are declared in
4087 the protected type which contains the entry.
4091 This set of configuration pragmas and restrictions correspond to the
4092 definition of the ``Ravenscar Profile'' for limited tasking, devised and
4093 published by the @cite{International Real-Time Ada Workshop}, 1997,
4094 and whose most recent description is available at
4095 @url{http://www-users.cs.york.ac.uk/~burns/ravenscar.ps}.
4097 The original definition of the profile was revised at subsequent IRTAW
4098 meetings. It has been included in the ISO
4099 @cite{Guide for the Use of the Ada Programming Language in High
4100 Integrity Systems}, and has been approved by ISO/IEC/SC22/WG9 for inclusion in
4101 the next revision of the standard. The formal definition given by
4102 the Ada Rapporteur Group (ARG) can be found in two Ada Issues (AI-249 and
4103 AI-305) available at
4104 @url{http://www.ada-auth.org/cgi-bin/cvsweb.cgi/AIs/AI-00249.TXT} and
4105 @url{http://www.ada-auth.org/cgi-bin/cvsweb.cgi/AIs/AI-00305.TXT}
4108 The above set is a superset of the restrictions provided by pragma
4109 @code{Profile (Restricted)}, it includes six additional restrictions
4110 (@code{Simple_Barriers}, @code{No_Select_Statements},
4111 @code{No_Calendar}, @code{No_Implicit_Heap_Allocations},
4112 @code{No_Relative_Delay} and @code{No_Task_Termination}). This means
4113 that pragma @code{Profile (Ravenscar)}, like the pragma
4114 @code{Profile (Restricted)},
4115 automatically causes the use of a simplified,
4116 more efficient version of the tasking run-time system.
4118 @node Pragma Profile (Restricted)
4119 @unnumberedsec Pragma Profile (Restricted)
4120 @findex Restricted Run Time
4124 @smallexample @c ada
4125 pragma Profile (Restricted);
4129 A configuration pragma that establishes the following set of restrictions:
4132 @item No_Abort_Statements
4133 @item No_Entry_Queue
4134 @item No_Task_Hierarchy
4135 @item No_Task_Allocators
4136 @item No_Dynamic_Priorities
4137 @item No_Terminate_Alternatives
4138 @item No_Dynamic_Attachment
4139 @item No_Protected_Type_Allocators
4140 @item No_Local_Protected_Objects
4141 @item No_Requeue_Statements
4142 @item No_Task_Attributes_Package
4143 @item Max_Asynchronous_Select_Nesting = 0
4144 @item Max_Task_Entries = 0
4145 @item Max_Protected_Entries = 1
4146 @item Max_Select_Alternatives = 0
4150 This set of restrictions causes the automatic selection of a simplified
4151 version of the run time that provides improved performance for the
4152 limited set of tasking functionality permitted by this set of restrictions.
4154 @node Pragma Psect_Object
4155 @unnumberedsec Pragma Psect_Object
4156 @findex Psect_Object
4160 @smallexample @c ada
4161 pragma Psect_Object (
4162 [Internal =>] LOCAL_NAME,
4163 [, [External =>] EXTERNAL_SYMBOL]
4164 [, [Size =>] EXTERNAL_SYMBOL]);
4168 | static_string_EXPRESSION
4172 This pragma is identical in effect to pragma @code{Common_Object}.
4174 @node Pragma Pure_Function
4175 @unnumberedsec Pragma Pure_Function
4176 @findex Pure_Function
4180 @smallexample @c ada
4181 pragma Pure_Function ([Entity =>] function_LOCAL_NAME);
4185 This pragma appears in the same declarative part as a function
4186 declaration (or a set of function declarations if more than one
4187 overloaded declaration exists, in which case the pragma applies
4188 to all entities). It specifies that the function @code{Entity} is
4189 to be considered pure for the purposes of code generation. This means
4190 that the compiler can assume that there are no side effects, and
4191 in particular that two calls with identical arguments produce the
4192 same result. It also means that the function can be used in an
4195 Note that, quite deliberately, there are no static checks to try
4196 to ensure that this promise is met, so @code{Pure_Function} can be used
4197 with functions that are conceptually pure, even if they do modify
4198 global variables. For example, a square root function that is
4199 instrumented to count the number of times it is called is still
4200 conceptually pure, and can still be optimized, even though it
4201 modifies a global variable (the count). Memo functions are another
4202 example (where a table of previous calls is kept and consulted to
4203 avoid re-computation).
4206 Note: Most functions in a @code{Pure} package are automatically pure, and
4207 there is no need to use pragma @code{Pure_Function} for such functions. One
4208 exception is any function that has at least one formal of type
4209 @code{System.Address} or a type derived from it. Such functions are not
4210 considered pure by default, since the compiler assumes that the
4211 @code{Address} parameter may be functioning as a pointer and that the
4212 referenced data may change even if the address value does not.
4213 Similarly, imported functions are not considered to be pure by default,
4214 since there is no way of checking that they are in fact pure. The use
4215 of pragma @code{Pure_Function} for such a function will override these default
4216 assumption, and cause the compiler to treat a designated subprogram as pure
4219 Note: If pragma @code{Pure_Function} is applied to a renamed function, it
4220 applies to the underlying renamed function. This can be used to
4221 disambiguate cases of overloading where some but not all functions
4222 in a set of overloaded functions are to be designated as pure.
4224 If pragma @code{Pure_Function} is applied to a library level function, the
4225 function is also considered pure from an optimization point of view, but the
4226 unit is not a Pure unit in the categorization sense. So for example, a function
4227 thus marked is free to @code{with} non-pure units.
4229 @node Pragma Restriction_Warnings
4230 @unnumberedsec Pragma Restriction_Warnings
4231 @findex Restriction_Warnings
4235 @smallexample @c ada
4236 pragma Restriction_Warnings
4237 (restriction_IDENTIFIER @{, restriction_IDENTIFIER@});
4241 This pragma allows a series of restriction identifiers to be
4242 specified (the list of allowed identifiers is the same as for
4243 pragma @code{Restrictions}). For each of these identifiers
4244 the compiler checks for violations of the restriction, but
4245 generates a warning message rather than an error message
4246 if the restriction is violated.
4249 @unnumberedsec Pragma Shared
4253 This pragma is provided for compatibility with Ada 83. The syntax and
4254 semantics are identical to pragma Atomic.
4256 @node Pragma Source_File_Name
4257 @unnumberedsec Pragma Source_File_Name
4258 @findex Source_File_Name
4262 @smallexample @c ada
4263 pragma Source_File_Name (
4264 [Unit_Name =>] unit_NAME,
4265 Spec_File_Name => STRING_LITERAL,
4266 [Index => INTEGER_LITERAL]);
4268 pragma Source_File_Name (
4269 [Unit_Name =>] unit_NAME,
4270 Body_File_Name => STRING_LITERAL,
4271 [Index => INTEGER_LITERAL]);
4275 Use this to override the normal naming convention. It is a configuration
4276 pragma, and so has the usual applicability of configuration pragmas
4277 (i.e.@: it applies to either an entire partition, or to all units in a
4278 compilation, or to a single unit, depending on how it is used.
4279 @var{unit_name} is mapped to @var{file_name_literal}. The identifier for
4280 the second argument is required, and indicates whether this is the file
4281 name for the spec or for the body.
4283 The optional Index argument should be used when a file contains multiple
4284 units, and when you do not want to use @code{gnatchop} to separate then
4285 into multiple files (which is the recommended procedure to limit the
4286 number of recompilation that are needed when some sources change).
4287 For instance, if the source file @file{source.ada} contains
4289 @smallexample @c ada
4301 you could use the following configuration pragmas:
4303 @smallexample @c ada
4304 pragma Source_File_Name
4305 (B, Spec_File_Name => "source.ada", Index => 1);
4306 pragma Source_File_Name
4307 (A, Body_File_Name => "source.ada", Index => 2);
4310 Note that the @code{gnatname} utility can also be used to generate those
4311 configuration pragmas.
4313 Another form of the @code{Source_File_Name} pragma allows
4314 the specification of patterns defining alternative file naming schemes
4315 to apply to all files.
4317 @smallexample @c ada
4318 pragma Source_File_Name
4319 ( [Spec_File_Name =>] STRING_LITERAL
4320 [,[Casing =>] CASING_SPEC]
4321 [,[Dot_Replacement =>] STRING_LITERAL]);
4323 pragma Source_File_Name
4324 ( [Body_File_Name =>] STRING_LITERAL
4325 [,[Casing =>] CASING_SPEC]
4326 [,[Dot_Replacement =>] STRING_LITERAL]);
4328 pragma Source_File_Name
4329 ( [Subunit_File_Name =>] STRING_LITERAL
4330 [,[Casing =>] CASING_SPEC]
4331 [,[Dot_Replacement =>] STRING_LITERAL]);
4333 CASING_SPEC ::= Lowercase | Uppercase | Mixedcase
4337 The first argument is a pattern that contains a single asterisk indicating
4338 the point at which the unit name is to be inserted in the pattern string
4339 to form the file name. The second argument is optional. If present it
4340 specifies the casing of the unit name in the resulting file name string.
4341 The default is lower case. Finally the third argument allows for systematic
4342 replacement of any dots in the unit name by the specified string literal.
4344 A pragma Source_File_Name cannot appear after a
4345 @ref{Pragma Source_File_Name_Project}.
4347 For more details on the use of the @code{Source_File_Name} pragma,
4348 @xref{Using Other File Names,,, gnat_ugn, @value{EDITION} User's Guide},
4349 and @ref{Alternative File Naming Schemes,,, gnat_ugn, @value{EDITION}
4352 @node Pragma Source_File_Name_Project
4353 @unnumberedsec Pragma Source_File_Name_Project
4354 @findex Source_File_Name_Project
4357 This pragma has the same syntax and semantics as pragma Source_File_Name.
4358 It is only allowed as a stand alone configuration pragma.
4359 It cannot appear after a @ref{Pragma Source_File_Name}, and
4360 most importantly, once pragma Source_File_Name_Project appears,
4361 no further Source_File_Name pragmas are allowed.
4363 The intention is that Source_File_Name_Project pragmas are always
4364 generated by the Project Manager in a manner consistent with the naming
4365 specified in a project file, and when naming is controlled in this manner,
4366 it is not permissible to attempt to modify this naming scheme using
4367 Source_File_Name pragmas (which would not be known to the project manager).
4369 @node Pragma Source_Reference
4370 @unnumberedsec Pragma Source_Reference
4371 @findex Source_Reference
4375 @smallexample @c ada
4376 pragma Source_Reference (INTEGER_LITERAL, STRING_LITERAL);
4380 This pragma must appear as the first line of a source file.
4381 @var{integer_literal} is the logical line number of the line following
4382 the pragma line (for use in error messages and debugging
4383 information). @var{string_literal} is a static string constant that
4384 specifies the file name to be used in error messages and debugging
4385 information. This is most notably used for the output of @code{gnatchop}
4386 with the @option{-r} switch, to make sure that the original unchopped
4387 source file is the one referred to.
4389 The second argument must be a string literal, it cannot be a static
4390 string expression other than a string literal. This is because its value
4391 is needed for error messages issued by all phases of the compiler.
4393 @node Pragma Stream_Convert
4394 @unnumberedsec Pragma Stream_Convert
4395 @findex Stream_Convert
4399 @smallexample @c ada
4400 pragma Stream_Convert (
4401 [Entity =>] type_LOCAL_NAME,
4402 [Read =>] function_NAME,
4403 [Write =>] function_NAME);
4407 This pragma provides an efficient way of providing stream functions for
4408 types defined in packages. Not only is it simpler to use than declaring
4409 the necessary functions with attribute representation clauses, but more
4410 significantly, it allows the declaration to made in such a way that the
4411 stream packages are not loaded unless they are needed. The use of
4412 the Stream_Convert pragma adds no overhead at all, unless the stream
4413 attributes are actually used on the designated type.
4415 The first argument specifies the type for which stream functions are
4416 provided. The second parameter provides a function used to read values
4417 of this type. It must name a function whose argument type may be any
4418 subtype, and whose returned type must be the type given as the first
4419 argument to the pragma.
4421 The meaning of the @var{Read}
4422 parameter is that if a stream attribute directly
4423 or indirectly specifies reading of the type given as the first parameter,
4424 then a value of the type given as the argument to the Read function is
4425 read from the stream, and then the Read function is used to convert this
4426 to the required target type.
4428 Similarly the @var{Write} parameter specifies how to treat write attributes
4429 that directly or indirectly apply to the type given as the first parameter.
4430 It must have an input parameter of the type specified by the first parameter,
4431 and the return type must be the same as the input type of the Read function.
4432 The effect is to first call the Write function to convert to the given stream
4433 type, and then write the result type to the stream.
4435 The Read and Write functions must not be overloaded subprograms. If necessary
4436 renamings can be supplied to meet this requirement.
4437 The usage of this attribute is best illustrated by a simple example, taken
4438 from the GNAT implementation of package Ada.Strings.Unbounded:
4440 @smallexample @c ada
4441 function To_Unbounded (S : String)
4442 return Unbounded_String
4443 renames To_Unbounded_String;
4445 pragma Stream_Convert
4446 (Unbounded_String, To_Unbounded, To_String);
4450 The specifications of the referenced functions, as given in the Ada
4451 Reference Manual are:
4453 @smallexample @c ada
4454 function To_Unbounded_String (Source : String)
4455 return Unbounded_String;
4457 function To_String (Source : Unbounded_String)
4462 The effect is that if the value of an unbounded string is written to a stream,
4463 then the representation of the item in the stream is in the same format that
4464 would be used for @code{Standard.String'Output}, and this same representation
4465 is expected when a value of this type is read from the stream. Note that the
4466 value written always includes the bounds, even for Unbounded_String'Write,
4467 since Unbounded_String is not an array type.
4469 @node Pragma Style_Checks
4470 @unnumberedsec Pragma Style_Checks
4471 @findex Style_Checks
4475 @smallexample @c ada
4476 pragma Style_Checks (string_LITERAL | ALL_CHECKS |
4477 On | Off [, LOCAL_NAME]);
4481 This pragma is used in conjunction with compiler switches to control the
4482 built in style checking provided by GNAT@. The compiler switches, if set,
4483 provide an initial setting for the switches, and this pragma may be used
4484 to modify these settings, or the settings may be provided entirely by
4485 the use of the pragma. This pragma can be used anywhere that a pragma
4486 is legal, including use as a configuration pragma (including use in
4487 the @file{gnat.adc} file).
4489 The form with a string literal specifies which style options are to be
4490 activated. These are additive, so they apply in addition to any previously
4491 set style check options. The codes for the options are the same as those
4492 used in the @option{-gnaty} switch to @command{gcc} or @command{gnatmake}.
4493 For example the following two methods can be used to enable
4498 @smallexample @c ada
4499 pragma Style_Checks ("l");
4504 gcc -c -gnatyl @dots{}
4509 The form ALL_CHECKS activates all standard checks (its use is equivalent
4510 to the use of the @code{gnaty} switch with no options. @xref{Top,
4511 @value{EDITION} User's Guide, About This Guide, gnat_ugn,
4512 @value{EDITION} User's Guide}, for details.
4514 The forms with @code{Off} and @code{On}
4515 can be used to temporarily disable style checks
4516 as shown in the following example:
4518 @smallexample @c ada
4522 pragma Style_Checks ("k"); -- requires keywords in lower case
4523 pragma Style_Checks (Off); -- turn off style checks
4524 NULL; -- this will not generate an error message
4525 pragma Style_Checks (On); -- turn style checks back on
4526 NULL; -- this will generate an error message
4530 Finally the two argument form is allowed only if the first argument is
4531 @code{On} or @code{Off}. The effect is to turn of semantic style checks
4532 for the specified entity, as shown in the following example:
4534 @smallexample @c ada
4538 pragma Style_Checks ("r"); -- require consistency of identifier casing
4540 Rf1 : Integer := ARG; -- incorrect, wrong case
4541 pragma Style_Checks (Off, Arg);
4542 Rf2 : Integer := ARG; -- OK, no error
4545 @node Pragma Subtitle
4546 @unnumberedsec Pragma Subtitle
4551 @smallexample @c ada
4552 pragma Subtitle ([Subtitle =>] STRING_LITERAL);
4556 This pragma is recognized for compatibility with other Ada compilers
4557 but is ignored by GNAT@.
4559 @node Pragma Suppress
4560 @unnumberedsec Pragma Suppress
4565 @smallexample @c ada
4566 pragma Suppress (Identifier [, [On =>] Name]);
4570 This is a standard pragma, and supports all the check names required in
4571 the RM. It is included here because GNAT recognizes one additional check
4572 name: @code{Alignment_Check} which can be used to suppress alignment checks
4573 on addresses used in address clauses. Such checks can also be suppressed
4574 by suppressing range checks, but the specific use of @code{Alignment_Check}
4575 allows suppression of alignment checks without suppressing other range checks.
4577 Note that pragma Suppress gives the compiler permission to omit
4578 checks, but does not require the compiler to omit checks. The compiler
4579 will generate checks if they are essentially free, even when they are
4580 suppressed. In particular, if the compiler can prove that a certain
4581 check will necessarily fail, it will generate code to do an
4582 unconditional ``raise'', even if checks are suppressed. The compiler
4585 Of course, run-time checks are omitted whenever the compiler can prove
4586 that they will not fail, whether or not checks are suppressed.
4588 @node Pragma Suppress_All
4589 @unnumberedsec Pragma Suppress_All
4590 @findex Suppress_All
4594 @smallexample @c ada
4595 pragma Suppress_All;
4599 This pragma can only appear immediately following a compilation
4600 unit. The effect is to apply @code{Suppress (All_Checks)} to the unit
4601 which it follows. This pragma is implemented for compatibility with DEC
4602 Ada 83 usage. The use of pragma @code{Suppress (All_Checks)} as a normal
4603 configuration pragma is the preferred usage in GNAT@.
4605 @node Pragma Suppress_Exception_Locations
4606 @unnumberedsec Pragma Suppress_Exception_Locations
4607 @findex Suppress_Exception_Locations
4611 @smallexample @c ada
4612 pragma Suppress_Exception_Locations;
4616 In normal mode, a raise statement for an exception by default generates
4617 an exception message giving the file name and line number for the location
4618 of the raise. This is useful for debugging and logging purposes, but this
4619 entails extra space for the strings for the messages. The configuration
4620 pragma @code{Suppress_Exception_Locations} can be used to suppress the
4621 generation of these strings, with the result that space is saved, but the
4622 exception message for such raises is null. This configuration pragma may
4623 appear in a global configuration pragma file, or in a specific unit as
4624 usual. It is not required that this pragma be used consistently within
4625 a partition, so it is fine to have some units within a partition compiled
4626 with this pragma and others compiled in normal mode without it.
4628 @node Pragma Suppress_Initialization
4629 @unnumberedsec Pragma Suppress_Initialization
4630 @findex Suppress_Initialization
4631 @cindex Suppressing initialization
4632 @cindex Initialization, suppression of
4636 @smallexample @c ada
4637 pragma Suppress_Initialization ([Entity =>] type_Name);
4641 This pragma suppresses any implicit or explicit initialization
4642 associated with the given type name for all variables of this type.
4644 @node Pragma Task_Info
4645 @unnumberedsec Pragma Task_Info
4650 @smallexample @c ada
4651 pragma Task_Info (EXPRESSION);
4655 This pragma appears within a task definition (like pragma
4656 @code{Priority}) and applies to the task in which it appears. The
4657 argument must be of type @code{System.Task_Info.Task_Info_Type}.
4658 The @code{Task_Info} pragma provides system dependent control over
4659 aspects of tasking implementation, for example, the ability to map
4660 tasks to specific processors. For details on the facilities available
4661 for the version of GNAT that you are using, see the documentation
4662 in the spec of package System.Task_Info in the runtime
4665 @node Pragma Task_Name
4666 @unnumberedsec Pragma Task_Name
4671 @smallexample @c ada
4672 pragma Task_Name (string_EXPRESSION);
4676 This pragma appears within a task definition (like pragma
4677 @code{Priority}) and applies to the task in which it appears. The
4678 argument must be of type String, and provides a name to be used for
4679 the task instance when the task is created. Note that this expression
4680 is not required to be static, and in particular, it can contain
4681 references to task discriminants. This facility can be used to
4682 provide different names for different tasks as they are created,
4683 as illustrated in the example below.
4685 The task name is recorded internally in the run-time structures
4686 and is accessible to tools like the debugger. In addition the
4687 routine @code{Ada.Task_Identification.Image} will return this
4688 string, with a unique task address appended.
4690 @smallexample @c ada
4691 -- Example of the use of pragma Task_Name
4693 with Ada.Task_Identification;
4694 use Ada.Task_Identification;
4695 with Text_IO; use Text_IO;
4698 type Astring is access String;
4700 task type Task_Typ (Name : access String) is
4701 pragma Task_Name (Name.all);
4704 task body Task_Typ is
4705 Nam : constant String := Image (Current_Task);
4707 Put_Line ("-->" & Nam (1 .. 14) & "<--");
4710 type Ptr_Task is access Task_Typ;
4711 Task_Var : Ptr_Task;
4715 new Task_Typ (new String'("This is task 1"));
4717 new Task_Typ (new String'("This is task 2"));
4721 @node Pragma Task_Storage
4722 @unnumberedsec Pragma Task_Storage
4723 @findex Task_Storage
4726 @smallexample @c ada
4727 pragma Task_Storage (
4728 [Task_Type =>] LOCAL_NAME,
4729 [Top_Guard =>] static_integer_EXPRESSION);
4733 This pragma specifies the length of the guard area for tasks. The guard
4734 area is an additional storage area allocated to a task. A value of zero
4735 means that either no guard area is created or a minimal guard area is
4736 created, depending on the target. This pragma can appear anywhere a
4737 @code{Storage_Size} attribute definition clause is allowed for a task
4740 @node Pragma Thread_Local_Storage
4741 @unnumberedsec Pragma Thread_Local_Storage
4742 @findex Thread_Local_Storage
4743 @cindex Task specific storage
4744 @cindex TLS (Thread Local Storage)
4747 @smallexample @c ada
4748 pragma Thread_Local_Storage ([Entity =>] LOCAL_NAME);
4752 This pragma specifies that the specified entity, which must be
4753 a variable declared in a library level package, is to be marked as
4754 "Thread Local Storage" (@code{TLS}). On systems supporting this (which
4755 include Solaris, GNU/Linux and VxWorks 6), this causes each thread
4756 (and hence each Ada task) to see a distinct copy of the variable.
4758 The variable may not have default initialization, and if there is
4759 an explicit initialization, it must be either @code{null} for an
4760 access variable, or a static expression for a scalar variable.
4761 This provides a low level mechanism similar to that provided by
4762 the @code{Ada.Task_Attributes} package, but much more efficient
4763 and is also useful in writing interface code that will interact
4764 with foreign threads.
4766 If this pragma is used on a system where @code{TLS} is not supported,
4767 then an error message will be generated and the program will be rejected.
4769 @node Pragma Time_Slice
4770 @unnumberedsec Pragma Time_Slice
4775 @smallexample @c ada
4776 pragma Time_Slice (static_duration_EXPRESSION);
4780 For implementations of GNAT on operating systems where it is possible
4781 to supply a time slice value, this pragma may be used for this purpose.
4782 It is ignored if it is used in a system that does not allow this control,
4783 or if it appears in other than the main program unit.
4785 Note that the effect of this pragma is identical to the effect of the
4786 DEC Ada 83 pragma of the same name when operating under OpenVMS systems.
4789 @unnumberedsec Pragma Title
4794 @smallexample @c ada
4795 pragma Title (TITLING_OPTION [, TITLING OPTION]);
4798 [Title =>] STRING_LITERAL,
4799 | [Subtitle =>] STRING_LITERAL
4803 Syntax checked but otherwise ignored by GNAT@. This is a listing control
4804 pragma used in DEC Ada 83 implementations to provide a title and/or
4805 subtitle for the program listing. The program listing generated by GNAT
4806 does not have titles or subtitles.
4808 Unlike other pragmas, the full flexibility of named notation is allowed
4809 for this pragma, i.e.@: the parameters may be given in any order if named
4810 notation is used, and named and positional notation can be mixed
4811 following the normal rules for procedure calls in Ada.
4813 @node Pragma Unchecked_Union
4814 @unnumberedsec Pragma Unchecked_Union
4816 @findex Unchecked_Union
4820 @smallexample @c ada
4821 pragma Unchecked_Union (first_subtype_LOCAL_NAME);
4825 This pragma is used to specify a representation of a record type that is
4826 equivalent to a C union. It was introduced as a GNAT implementation defined
4827 pragma in the GNAT Ada 95 mode. Ada 2005 includes an extended version of this
4828 pragma, making it language defined, and GNAT fully implements this extended
4829 version in all language modes (Ada 83, Ada 95, and Ada 2005). For full
4830 details, consult the Ada 2005 Reference Manual, section B.3.3.
4832 @node Pragma Unimplemented_Unit
4833 @unnumberedsec Pragma Unimplemented_Unit
4834 @findex Unimplemented_Unit
4838 @smallexample @c ada
4839 pragma Unimplemented_Unit;
4843 If this pragma occurs in a unit that is processed by the compiler, GNAT
4844 aborts with the message @samp{@var{xxx} not implemented}, where
4845 @var{xxx} is the name of the current compilation unit. This pragma is
4846 intended to allow the compiler to handle unimplemented library units in
4849 The abort only happens if code is being generated. Thus you can use
4850 specs of unimplemented packages in syntax or semantic checking mode.
4852 @node Pragma Universal_Aliasing
4853 @unnumberedsec Pragma Universal_Aliasing
4854 @findex Universal_Aliasing
4858 @smallexample @c ada
4859 pragma Universal_Aliasing [([Entity =>] type_LOCAL_NAME)];
4863 @var{type_LOCAL_NAME} must refer to a type declaration in the current
4864 declarative part. The effect is to inhibit strict type-based aliasing
4865 optimization for the given type. In other words, the effect is as though
4866 access types designating this type were subject to pragma No_Strict_Aliasing.
4867 For a detailed description of the strict aliasing optimization, and the
4868 situations in which it must be suppressed, @xref{Optimization and Strict
4869 Aliasing,,, gnat_ugn, @value{EDITION} User's Guide}.
4871 @node Pragma Universal_Data
4872 @unnumberedsec Pragma Universal_Data
4873 @findex Universal_Data
4877 @smallexample @c ada
4878 pragma Universal_Data [(library_unit_Name)];
4882 This pragma is supported only for the AAMP target and is ignored for
4883 other targets. The pragma specifies that all library-level objects
4884 (Counter 0 data) associated with the library unit are to be accessed
4885 and updated using universal addressing (24-bit addresses for AAMP5)
4886 rather than the default of 16-bit Data Environment (DENV) addressing.
4887 Use of this pragma will generally result in less efficient code for
4888 references to global data associated with the library unit, but
4889 allows such data to be located anywhere in memory. This pragma is
4890 a library unit pragma, but can also be used as a configuration pragma
4891 (including use in the @file{gnat.adc} file). The functionality
4892 of this pragma is also available by applying the -univ switch on the
4893 compilations of units where universal addressing of the data is desired.
4895 @node Pragma Unmodified
4896 @unnumberedsec Pragma Unmodified
4898 @cindex Warnings, unmodified
4902 @smallexample @c ada
4903 pragma Unmodified (LOCAL_NAME @{, LOCAL_NAME@});
4907 This pragma signals that the assignable entities (variables,
4908 @code{out} parameters, @code{in out} parameters) whose names are listed are
4909 deliberately not assigned in the current source unit. This
4910 suppresses warnings about the
4911 entities being referenced but not assigned, and in addition a warning will be
4912 generated if one of these entities is in fact assigned in the
4913 same unit as the pragma (or in the corresponding body, or one
4916 This is particularly useful for clearly signaling that a particular
4917 parameter is not modified, even though the spec suggests that it might
4920 @node Pragma Unreferenced
4921 @unnumberedsec Pragma Unreferenced
4922 @findex Unreferenced
4923 @cindex Warnings, unreferenced
4927 @smallexample @c ada
4928 pragma Unreferenced (LOCAL_NAME @{, LOCAL_NAME@});
4929 pragma Unreferenced (library_unit_NAME @{, library_unit_NAME@});
4933 This pragma signals that the entities whose names are listed are
4934 deliberately not referenced in the current source unit. This
4935 suppresses warnings about the
4936 entities being unreferenced, and in addition a warning will be
4937 generated if one of these entities is in fact referenced in the
4938 same unit as the pragma (or in the corresponding body, or one
4941 This is particularly useful for clearly signaling that a particular
4942 parameter is not referenced in some particular subprogram implementation
4943 and that this is deliberate. It can also be useful in the case of
4944 objects declared only for their initialization or finalization side
4947 If @code{LOCAL_NAME} identifies more than one matching homonym in the
4948 current scope, then the entity most recently declared is the one to which
4949 the pragma applies. Note that in the case of accept formals, the pragma
4950 Unreferenced may appear immediately after the keyword @code{do} which
4951 allows the indication of whether or not accept formals are referenced
4952 or not to be given individually for each accept statement.
4954 The left hand side of an assignment does not count as a reference for the
4955 purpose of this pragma. Thus it is fine to assign to an entity for which
4956 pragma Unreferenced is given.
4958 Note that if a warning is desired for all calls to a given subprogram,
4959 regardless of whether they occur in the same unit as the subprogram
4960 declaration, then this pragma should not be used (calls from another
4961 unit would not be flagged); pragma Obsolescent can be used instead
4962 for this purpose, see @xref{Pragma Obsolescent}.
4964 The second form of pragma @code{Unreferenced} is used within a context
4965 clause. In this case the arguments must be unit names of units previously
4966 mentioned in @code{with} clauses (similar to the usage of pragma
4967 @code{Elaborate_All}. The effect is to suppress warnings about unreferenced
4968 units and unreferenced entities within these units.
4970 @node Pragma Unreferenced_Objects
4971 @unnumberedsec Pragma Unreferenced_Objects
4972 @findex Unreferenced_Objects
4973 @cindex Warnings, unreferenced
4977 @smallexample @c ada
4978 pragma Unreferenced_Objects (local_subtype_NAME @{, local_subtype_NAME@});
4982 This pragma signals that for the types or subtypes whose names are
4983 listed, objects which are declared with one of these types or subtypes may
4984 not be referenced, and if no references appear, no warnings are given.
4986 This is particularly useful for objects which are declared solely for their
4987 initialization and finalization effect. Such variables are sometimes referred
4988 to as RAII variables (Resource Acquisition Is Initialization). Using this
4989 pragma on the relevant type (most typically a limited controlled type), the
4990 compiler will automatically suppress unwanted warnings about these variables
4991 not being referenced.
4993 @node Pragma Unreserve_All_Interrupts
4994 @unnumberedsec Pragma Unreserve_All_Interrupts
4995 @findex Unreserve_All_Interrupts
4999 @smallexample @c ada
5000 pragma Unreserve_All_Interrupts;
5004 Normally certain interrupts are reserved to the implementation. Any attempt
5005 to attach an interrupt causes Program_Error to be raised, as described in
5006 RM C.3.2(22). A typical example is the @code{SIGINT} interrupt used in
5007 many systems for a @kbd{Ctrl-C} interrupt. Normally this interrupt is
5008 reserved to the implementation, so that @kbd{Ctrl-C} can be used to
5009 interrupt execution.
5011 If the pragma @code{Unreserve_All_Interrupts} appears anywhere in any unit in
5012 a program, then all such interrupts are unreserved. This allows the
5013 program to handle these interrupts, but disables their standard
5014 functions. For example, if this pragma is used, then pressing
5015 @kbd{Ctrl-C} will not automatically interrupt execution. However,
5016 a program can then handle the @code{SIGINT} interrupt as it chooses.
5018 For a full list of the interrupts handled in a specific implementation,
5019 see the source code for the spec of @code{Ada.Interrupts.Names} in
5020 file @file{a-intnam.ads}. This is a target dependent file that contains the
5021 list of interrupts recognized for a given target. The documentation in
5022 this file also specifies what interrupts are affected by the use of
5023 the @code{Unreserve_All_Interrupts} pragma.
5025 For a more general facility for controlling what interrupts can be
5026 handled, see pragma @code{Interrupt_State}, which subsumes the functionality
5027 of the @code{Unreserve_All_Interrupts} pragma.
5029 @node Pragma Unsuppress
5030 @unnumberedsec Pragma Unsuppress
5035 @smallexample @c ada
5036 pragma Unsuppress (IDENTIFIER [, [On =>] NAME]);
5040 This pragma undoes the effect of a previous pragma @code{Suppress}. If
5041 there is no corresponding pragma @code{Suppress} in effect, it has no
5042 effect. The range of the effect is the same as for pragma
5043 @code{Suppress}. The meaning of the arguments is identical to that used
5044 in pragma @code{Suppress}.
5046 One important application is to ensure that checks are on in cases where
5047 code depends on the checks for its correct functioning, so that the code
5048 will compile correctly even if the compiler switches are set to suppress
5051 @node Pragma Use_VADS_Size
5052 @unnumberedsec Pragma Use_VADS_Size
5053 @cindex @code{Size}, VADS compatibility
5054 @findex Use_VADS_Size
5058 @smallexample @c ada
5059 pragma Use_VADS_Size;
5063 This is a configuration pragma. In a unit to which it applies, any use
5064 of the 'Size attribute is automatically interpreted as a use of the
5065 'VADS_Size attribute. Note that this may result in incorrect semantic
5066 processing of valid Ada 95 or Ada 2005 programs. This is intended to aid in
5067 the handling of existing code which depends on the interpretation of Size
5068 as implemented in the VADS compiler. See description of the VADS_Size
5069 attribute for further details.
5071 @node Pragma Validity_Checks
5072 @unnumberedsec Pragma Validity_Checks
5073 @findex Validity_Checks
5077 @smallexample @c ada
5078 pragma Validity_Checks (string_LITERAL | ALL_CHECKS | On | Off);
5082 This pragma is used in conjunction with compiler switches to control the
5083 built-in validity checking provided by GNAT@. The compiler switches, if set
5084 provide an initial setting for the switches, and this pragma may be used
5085 to modify these settings, or the settings may be provided entirely by
5086 the use of the pragma. This pragma can be used anywhere that a pragma
5087 is legal, including use as a configuration pragma (including use in
5088 the @file{gnat.adc} file).
5090 The form with a string literal specifies which validity options are to be
5091 activated. The validity checks are first set to include only the default
5092 reference manual settings, and then a string of letters in the string
5093 specifies the exact set of options required. The form of this string
5094 is exactly as described for the @option{-gnatVx} compiler switch (see the
5095 GNAT users guide for details). For example the following two methods
5096 can be used to enable validity checking for mode @code{in} and
5097 @code{in out} subprogram parameters:
5101 @smallexample @c ada
5102 pragma Validity_Checks ("im");
5107 gcc -c -gnatVim @dots{}
5112 The form ALL_CHECKS activates all standard checks (its use is equivalent
5113 to the use of the @code{gnatva} switch.
5115 The forms with @code{Off} and @code{On}
5116 can be used to temporarily disable validity checks
5117 as shown in the following example:
5119 @smallexample @c ada
5123 pragma Validity_Checks ("c"); -- validity checks for copies
5124 pragma Validity_Checks (Off); -- turn off validity checks
5125 A := B; -- B will not be validity checked
5126 pragma Validity_Checks (On); -- turn validity checks back on
5127 A := C; -- C will be validity checked
5130 @node Pragma Volatile
5131 @unnumberedsec Pragma Volatile
5136 @smallexample @c ada
5137 pragma Volatile (LOCAL_NAME);
5141 This pragma is defined by the Ada Reference Manual, and the GNAT
5142 implementation is fully conformant with this definition. The reason it
5143 is mentioned in this section is that a pragma of the same name was supplied
5144 in some Ada 83 compilers, including DEC Ada 83. The Ada 95 / Ada 2005
5145 implementation of pragma Volatile is upwards compatible with the
5146 implementation in DEC Ada 83.
5148 @node Pragma Warnings
5149 @unnumberedsec Pragma Warnings
5154 @smallexample @c ada
5155 pragma Warnings (On | Off);
5156 pragma Warnings (On | Off, LOCAL_NAME);
5157 pragma Warnings (static_string_EXPRESSION);
5158 pragma Warnings (On | Off, static_string_EXPRESSION);
5162 Normally warnings are enabled, with the output being controlled by
5163 the command line switch. Warnings (@code{Off}) turns off generation of
5164 warnings until a Warnings (@code{On}) is encountered or the end of the
5165 current unit. If generation of warnings is turned off using this
5166 pragma, then no warning messages are output, regardless of the
5167 setting of the command line switches.
5169 The form with a single argument may be used as a configuration pragma.
5171 If the @var{LOCAL_NAME} parameter is present, warnings are suppressed for
5172 the specified entity. This suppression is effective from the point where
5173 it occurs till the end of the extended scope of the variable (similar to
5174 the scope of @code{Suppress}).
5176 The form with a single static_string_EXPRESSION argument provides more precise
5177 control over which warnings are active. The string is a list of letters
5178 specifying which warnings are to be activated and which deactivated. The
5179 code for these letters is the same as the string used in the command
5180 line switch controlling warnings. The following is a brief summary. For
5181 full details see @ref{Warning Message Control,,, gnat_ugn, @value{EDITION}
5185 a turn on all optional warnings (except d h l .o)
5186 A turn off all optional warnings
5187 .a* turn on warnings for failing assertions
5188 .A turn off warnings for failing assertions
5189 b turn on warnings for bad fixed value (not multiple of small)
5190 B* turn off warnings for bad fixed value (not multiple of small)
5191 .b* turn on warnings for biased representation
5192 .B turn off warnings for biased representation
5193 c turn on warnings for constant conditional
5194 C* turn off warnings for constant conditional
5195 .c turn on warnings for unrepped components
5196 .C* turn off warnings for unrepped components
5197 d turn on warnings for implicit dereference
5198 D* turn off warnings for implicit dereference
5199 e treat all warnings as errors
5200 .e turn on every optional warning
5201 f turn on warnings for unreferenced formal
5202 F* turn off warnings for unreferenced formal
5203 g* turn on warnings for unrecognized pragma
5204 G turn off warnings for unrecognized pragma
5205 h turn on warnings for hiding variable
5206 H* turn off warnings for hiding variable
5207 i* turn on warnings for implementation unit
5208 I turn off warnings for implementation unit
5209 j turn on warnings for obsolescent (annex J) feature
5210 J* turn off warnings for obsolescent (annex J) feature
5211 k turn on warnings on constant variable
5212 K* turn off warnings on constant variable
5213 l turn on warnings for missing elaboration pragma
5214 L* turn off warnings for missing elaboration pragma
5215 m turn on warnings for variable assigned but not read
5216 M* turn off warnings for variable assigned but not read
5217 n* normal warning mode (cancels -gnatws/-gnatwe)
5218 o* turn on warnings for address clause overlay
5219 O turn off warnings for address clause overlay
5220 .o turn on warnings for out parameters assigned but not read
5221 .O* turn off warnings for out parameters assigned but not read
5222 p turn on warnings for ineffective pragma Inline in frontend
5223 P* turn off warnings for ineffective pragma Inline in frontend
5224 .p turn on warnings for parameter ordering
5225 .P* turn off warnings for parameter ordering
5226 q* turn on warnings for questionable missing parentheses
5227 Q turn off warnings for questionable missing parentheses
5228 r turn on warnings for redundant construct
5229 R* turn off warnings for redundant construct
5230 .r turn on warnings for object renaming function
5231 .R* turn off warnings for object renaming function
5232 s suppress all warnings
5233 t turn on warnings for tracking deleted code
5234 T* turn off warnings for tracking deleted code
5235 u turn on warnings for unused entity
5236 U* turn off warnings for unused entity
5237 v* turn on warnings for unassigned variable
5238 V turn off warnings for unassigned variable
5239 w* turn on warnings for wrong low bound assumption
5240 W turn off warnings for wrong low bound assumption
5241 .w turn on warnings for unnecessary Warnings Off pragmas
5242 .W* turn off warnings for unnecessary Warnings Off pragmas
5243 x* turn on warnings for export/import
5244 X turn off warnings for export/import
5245 .x turn on warnings for non-local exceptions
5246 .X* turn off warnings for non-local exceptions
5247 y* turn on warnings for Ada 2005 incompatibility
5248 Y turn off warnings for Ada 2005 incompatibility
5249 z* turn on convention/size/align warnings for unchecked conversion
5250 Z turn off convention/size/align warnings for unchecked conversion
5251 * indicates default in above list
5255 The specified warnings will be in effect until the end of the program
5256 or another pragma Warnings is encountered. The effect of the pragma is
5257 cumulative. Initially the set of warnings is the standard default set
5258 as possibly modified by compiler switches. Then each pragma Warning
5259 modifies this set of warnings as specified. This form of the pragma may
5260 also be used as a configuration pragma.
5262 The fourth form, with an On|Off parameter and a string, is used to
5263 control individual messages, based on their text. The string argument
5264 is a pattern that is used to match against the text of individual
5265 warning messages (not including the initial "warning: " tag).
5267 The pattern may contain asterisks, which match zero or more characters in
5268 the message. For example, you can use
5269 @code{pragma Warnings (Off, "*bits of*unused")} to suppress the warning
5270 message @code{warning: 960 bits of "a" unused}. No other regular
5271 expression notations are permitted. All characters other than asterisk in
5272 these three specific cases are treated as literal characters in the match.
5274 There are two ways to use this pragma. The OFF form can be used as a
5275 configuration pragma. The effect is to suppress all warnings (if any)
5276 that match the pattern string throughout the compilation.
5278 The second usage is to suppress a warning locally, and in this case, two
5279 pragmas must appear in sequence:
5281 @smallexample @c ada
5282 pragma Warnings (Off, Pattern);
5283 @dots{} code where given warning is to be suppressed
5284 pragma Warnings (On, Pattern);
5288 In this usage, the pattern string must match in the Off and On pragmas,
5289 and at least one matching warning must be suppressed.
5291 @node Pragma Weak_External
5292 @unnumberedsec Pragma Weak_External
5293 @findex Weak_External
5297 @smallexample @c ada
5298 pragma Weak_External ([Entity =>] LOCAL_NAME);
5302 @var{LOCAL_NAME} must refer to an object that is declared at the library
5303 level. This pragma specifies that the given entity should be marked as a
5304 weak symbol for the linker. It is equivalent to @code{__attribute__((weak))}
5305 in GNU C and causes @var{LOCAL_NAME} to be emitted as a weak symbol instead
5306 of a regular symbol, that is to say a symbol that does not have to be
5307 resolved by the linker if used in conjunction with a pragma Import.
5309 When a weak symbol is not resolved by the linker, its address is set to
5310 zero. This is useful in writing interfaces to external modules that may
5311 or may not be linked in the final executable, for example depending on
5312 configuration settings.
5314 If a program references at run time an entity to which this pragma has been
5315 applied, and the corresponding symbol was not resolved at link time, then
5316 the execution of the program is erroneous. It is not erroneous to take the
5317 Address of such an entity, for example to guard potential references,
5318 as shown in the example below.
5320 Some file formats do not support weak symbols so not all target machines
5321 support this pragma.
5323 @smallexample @c ada
5324 -- Example of the use of pragma Weak_External
5326 package External_Module is
5328 pragma Import (C, key);
5329 pragma Weak_External (key);
5330 function Present return boolean;
5331 end External_Module;
5333 with System; use System;
5334 package body External_Module is
5335 function Present return boolean is
5337 return key'Address /= System.Null_Address;
5339 end External_Module;
5342 @node Pragma Wide_Character_Encoding
5343 @unnumberedsec Pragma Wide_Character_Encoding
5344 @findex Wide_Character_Encoding
5348 @smallexample @c ada
5349 pragma Wide_Character_Encoding (IDENTIFIER | CHARACTER_LITERAL);
5353 This pragma specifies the wide character encoding to be used in program
5354 source text appearing subsequently. It is a configuration pragma, but may
5355 also be used at any point that a pragma is allowed, and it is permissible
5356 to have more than one such pragma in a file, allowing multiple encodings
5357 to appear within the same file.
5359 The argument can be an identifier or a character literal. In the identifier
5360 case, it is one of @code{HEX}, @code{UPPER}, @code{SHIFT_JIS},
5361 @code{EUC}, @code{UTF8}, or @code{BRACKETS}. In the character literal
5362 case it is correspondingly one of the characters @samp{h}, @samp{u},
5363 @samp{s}, @samp{e}, @samp{8}, or @samp{b}.
5365 Note that when the pragma is used within a file, it affects only the
5366 encoding within that file, and does not affect withed units, specs,
5369 @node Implementation Defined Attributes
5370 @chapter Implementation Defined Attributes
5371 Ada defines (throughout the Ada reference manual,
5372 summarized in Annex K),
5373 a set of attributes that provide useful additional functionality in all
5374 areas of the language. These language defined attributes are implemented
5375 in GNAT and work as described in the Ada Reference Manual.
5377 In addition, Ada allows implementations to define additional
5378 attributes whose meaning is defined by the implementation. GNAT provides
5379 a number of these implementation-dependent attributes which can be used
5380 to extend and enhance the functionality of the compiler. This section of
5381 the GNAT reference manual describes these additional attributes.
5383 Note that any program using these attributes may not be portable to
5384 other compilers (although GNAT implements this set of attributes on all
5385 platforms). Therefore if portability to other compilers is an important
5386 consideration, you should minimize the use of these attributes.
5396 * Compiler_Version::
5398 * Default_Bit_Order::
5408 * Has_Access_Values::
5409 * Has_Discriminants::
5416 * Max_Interrupt_Priority::
5418 * Maximum_Alignment::
5423 * Passed_By_Reference::
5436 * Unconstrained_Array::
5437 * Universal_Literal_String::
5438 * Unrestricted_Access::
5446 @unnumberedsec Abort_Signal
5447 @findex Abort_Signal
5449 @code{Standard'Abort_Signal} (@code{Standard} is the only allowed
5450 prefix) provides the entity for the special exception used to signal
5451 task abort or asynchronous transfer of control. Normally this attribute
5452 should only be used in the tasking runtime (it is highly peculiar, and
5453 completely outside the normal semantics of Ada, for a user program to
5454 intercept the abort exception).
5457 @unnumberedsec Address_Size
5458 @cindex Size of @code{Address}
5459 @findex Address_Size
5461 @code{Standard'Address_Size} (@code{Standard} is the only allowed
5462 prefix) is a static constant giving the number of bits in an
5463 @code{Address}. It is the same value as System.Address'Size,
5464 but has the advantage of being static, while a direct
5465 reference to System.Address'Size is non-static because Address
5469 @unnumberedsec Asm_Input
5472 The @code{Asm_Input} attribute denotes a function that takes two
5473 parameters. The first is a string, the second is an expression of the
5474 type designated by the prefix. The first (string) argument is required
5475 to be a static expression, and is the constraint for the parameter,
5476 (e.g.@: what kind of register is required). The second argument is the
5477 value to be used as the input argument. The possible values for the
5478 constant are the same as those used in the RTL, and are dependent on
5479 the configuration file used to built the GCC back end.
5480 @ref{Machine Code Insertions}
5483 @unnumberedsec Asm_Output
5486 The @code{Asm_Output} attribute denotes a function that takes two
5487 parameters. The first is a string, the second is the name of a variable
5488 of the type designated by the attribute prefix. The first (string)
5489 argument is required to be a static expression and designates the
5490 constraint for the parameter (e.g.@: what kind of register is
5491 required). The second argument is the variable to be updated with the
5492 result. The possible values for constraint are the same as those used in
5493 the RTL, and are dependent on the configuration file used to build the
5494 GCC back end. If there are no output operands, then this argument may
5495 either be omitted, or explicitly given as @code{No_Output_Operands}.
5496 @ref{Machine Code Insertions}
5499 @unnumberedsec AST_Entry
5503 This attribute is implemented only in OpenVMS versions of GNAT@. Applied to
5504 the name of an entry, it yields a value of the predefined type AST_Handler
5505 (declared in the predefined package System, as extended by the use of
5506 pragma @code{Extend_System (Aux_DEC)}). This value enables the given entry to
5507 be called when an AST occurs. For further details, refer to the @cite{DEC Ada
5508 Language Reference Manual}, section 9.12a.
5513 @code{@var{obj}'Bit}, where @var{obj} is any object, yields the bit
5514 offset within the storage unit (byte) that contains the first bit of
5515 storage allocated for the object. The value of this attribute is of the
5516 type @code{Universal_Integer}, and is always a non-negative number not
5517 exceeding the value of @code{System.Storage_Unit}.
5519 For an object that is a variable or a constant allocated in a register,
5520 the value is zero. (The use of this attribute does not force the
5521 allocation of a variable to memory).
5523 For an object that is a formal parameter, this attribute applies
5524 to either the matching actual parameter or to a copy of the
5525 matching actual parameter.
5527 For an access object the value is zero. Note that
5528 @code{@var{obj}.all'Bit} is subject to an @code{Access_Check} for the
5529 designated object. Similarly for a record component
5530 @code{@var{X}.@var{C}'Bit} is subject to a discriminant check and
5531 @code{@var{X}(@var{I}).Bit} and @code{@var{X}(@var{I1}..@var{I2})'Bit}
5532 are subject to index checks.
5534 This attribute is designed to be compatible with the DEC Ada 83 definition
5535 and implementation of the @code{Bit} attribute.
5538 @unnumberedsec Bit_Position
5539 @findex Bit_Position
5541 @code{@var{R.C}'Bit}, where @var{R} is a record object and C is one
5542 of the fields of the record type, yields the bit
5543 offset within the record contains the first bit of
5544 storage allocated for the object. The value of this attribute is of the
5545 type @code{Universal_Integer}. The value depends only on the field
5546 @var{C} and is independent of the alignment of
5547 the containing record @var{R}.
5549 @node Compiler_Version
5550 @unnumberedsec Compiler_Version
5551 @findex Compiler_Version
5553 @code{Standard'Compiler_Version} (@code{Standard} is the only allowed
5554 prefix) yields a static string identifying the version of the compiler
5555 being used to compile the unit containing the attribute reference. A
5556 typical result would be something like "GNAT Pro 6.3.0w (20090221)".
5559 @unnumberedsec Code_Address
5560 @findex Code_Address
5561 @cindex Subprogram address
5562 @cindex Address of subprogram code
5565 attribute may be applied to subprograms in Ada 95 and Ada 2005, but the
5566 intended effect seems to be to provide
5567 an address value which can be used to call the subprogram by means of
5568 an address clause as in the following example:
5570 @smallexample @c ada
5571 procedure K is @dots{}
5574 for L'Address use K'Address;
5575 pragma Import (Ada, L);
5579 A call to @code{L} is then expected to result in a call to @code{K}@.
5580 In Ada 83, where there were no access-to-subprogram values, this was
5581 a common work-around for getting the effect of an indirect call.
5582 GNAT implements the above use of @code{Address} and the technique
5583 illustrated by the example code works correctly.
5585 However, for some purposes, it is useful to have the address of the start
5586 of the generated code for the subprogram. On some architectures, this is
5587 not necessarily the same as the @code{Address} value described above.
5588 For example, the @code{Address} value may reference a subprogram
5589 descriptor rather than the subprogram itself.
5591 The @code{'Code_Address} attribute, which can only be applied to
5592 subprogram entities, always returns the address of the start of the
5593 generated code of the specified subprogram, which may or may not be
5594 the same value as is returned by the corresponding @code{'Address}
5597 @node Default_Bit_Order
5598 @unnumberedsec Default_Bit_Order
5600 @cindex Little endian
5601 @findex Default_Bit_Order
5603 @code{Standard'Default_Bit_Order} (@code{Standard} is the only
5604 permissible prefix), provides the value @code{System.Default_Bit_Order}
5605 as a @code{Pos} value (0 for @code{High_Order_First}, 1 for
5606 @code{Low_Order_First}). This is used to construct the definition of
5607 @code{Default_Bit_Order} in package @code{System}.
5610 @unnumberedsec Elaborated
5613 The prefix of the @code{'Elaborated} attribute must be a unit name. The
5614 value is a Boolean which indicates whether or not the given unit has been
5615 elaborated. This attribute is primarily intended for internal use by the
5616 generated code for dynamic elaboration checking, but it can also be used
5617 in user programs. The value will always be True once elaboration of all
5618 units has been completed. An exception is for units which need no
5619 elaboration, the value is always False for such units.
5622 @unnumberedsec Elab_Body
5625 This attribute can only be applied to a program unit name. It returns
5626 the entity for the corresponding elaboration procedure for elaborating
5627 the body of the referenced unit. This is used in the main generated
5628 elaboration procedure by the binder and is not normally used in any
5629 other context. However, there may be specialized situations in which it
5630 is useful to be able to call this elaboration procedure from Ada code,
5631 e.g.@: if it is necessary to do selective re-elaboration to fix some
5635 @unnumberedsec Elab_Spec
5638 This attribute can only be applied to a program unit name. It returns
5639 the entity for the corresponding elaboration procedure for elaborating
5640 the spec of the referenced unit. This is used in the main
5641 generated elaboration procedure by the binder and is not normally used
5642 in any other context. However, there may be specialized situations in
5643 which it is useful to be able to call this elaboration procedure from
5644 Ada code, e.g.@: if it is necessary to do selective re-elaboration to fix
5649 @cindex Ada 83 attributes
5652 The @code{Emax} attribute is provided for compatibility with Ada 83. See
5653 the Ada 83 reference manual for an exact description of the semantics of
5657 @unnumberedsec Enabled
5660 The @code{Enabled} attribute allows an application program to check at compile
5661 time to see if the designated check is currently enabled. The prefix is a
5662 simple identifier, referencing any predefined check name (other than
5663 @code{All_Checks}) or a check name introduced by pragma Check_Name. If
5664 no argument is given for the attribute, the check is for the general state
5665 of the check, if an argument is given, then it is an entity name, and the
5666 check indicates whether an @code{Suppress} or @code{Unsuppress} has been
5667 given naming the entity (if not, then the argument is ignored).
5669 Note that instantiations inherit the check status at the point of the
5670 instantiation, so a useful idiom is to have a library package that
5671 introduces a check name with @code{pragma Check_Name}, and then contains
5672 generic packages or subprograms which use the @code{Enabled} attribute
5673 to see if the check is enabled. A user of this package can then issue
5674 a @code{pragma Suppress} or @code{pragma Unsuppress} before instantiating
5675 the package or subprogram, controlling whether the check will be present.
5678 @unnumberedsec Enum_Rep
5679 @cindex Representation of enums
5682 For every enumeration subtype @var{S}, @code{@var{S}'Enum_Rep} denotes a
5683 function with the following spec:
5685 @smallexample @c ada
5686 function @var{S}'Enum_Rep (Arg : @var{S}'Base)
5687 return @i{Universal_Integer};
5691 It is also allowable to apply @code{Enum_Rep} directly to an object of an
5692 enumeration type or to a non-overloaded enumeration
5693 literal. In this case @code{@var{S}'Enum_Rep} is equivalent to
5694 @code{@var{typ}'Enum_Rep(@var{S})} where @var{typ} is the type of the
5695 enumeration literal or object.
5697 The function returns the representation value for the given enumeration
5698 value. This will be equal to value of the @code{Pos} attribute in the
5699 absence of an enumeration representation clause. This is a static
5700 attribute (i.e.@: the result is static if the argument is static).
5702 @code{@var{S}'Enum_Rep} can also be used with integer types and objects,
5703 in which case it simply returns the integer value. The reason for this
5704 is to allow it to be used for @code{(<>)} discrete formal arguments in
5705 a generic unit that can be instantiated with either enumeration types
5706 or integer types. Note that if @code{Enum_Rep} is used on a modular
5707 type whose upper bound exceeds the upper bound of the largest signed
5708 integer type, and the argument is a variable, so that the universal
5709 integer calculation is done at run time, then the call to @code{Enum_Rep}
5710 may raise @code{Constraint_Error}.
5713 @unnumberedsec Enum_Val
5714 @cindex Representation of enums
5717 For every enumeration subtype @var{S}, @code{@var{S}'Enum_Rep} denotes a
5718 function with the following spec:
5720 @smallexample @c ada
5721 function @var{S}'Enum_Rep (Arg : @i{Universal_Integer)
5722 return @var{S}'Base};
5726 The function returns the enumeration value whose representation matches the
5727 argument, or raises Constraint_Error if no enumeration literal of the type
5728 has the matching value.
5729 This will be equal to value of the @code{Val} attribute in the
5730 absence of an enumeration representation clause. This is a static
5731 attribute (i.e.@: the result is static if the argument is static).
5734 @unnumberedsec Epsilon
5735 @cindex Ada 83 attributes
5738 The @code{Epsilon} attribute is provided for compatibility with Ada 83. See
5739 the Ada 83 reference manual for an exact description of the semantics of
5743 @unnumberedsec Fixed_Value
5746 For every fixed-point type @var{S}, @code{@var{S}'Fixed_Value} denotes a
5747 function with the following specification:
5749 @smallexample @c ada
5750 function @var{S}'Fixed_Value (Arg : @i{Universal_Integer})
5755 The value returned is the fixed-point value @var{V} such that
5757 @smallexample @c ada
5758 @var{V} = Arg * @var{S}'Small
5762 The effect is thus similar to first converting the argument to the
5763 integer type used to represent @var{S}, and then doing an unchecked
5764 conversion to the fixed-point type. The difference is
5765 that there are full range checks, to ensure that the result is in range.
5766 This attribute is primarily intended for use in implementation of the
5767 input-output functions for fixed-point values.
5769 @node Has_Access_Values
5770 @unnumberedsec Has_Access_Values
5771 @cindex Access values, testing for
5772 @findex Has_Access_Values
5774 The prefix of the @code{Has_Access_Values} attribute is a type. The result
5775 is a Boolean value which is True if the is an access type, or is a composite
5776 type with a component (at any nesting depth) that is an access type, and is
5778 The intended use of this attribute is in conjunction with generic
5779 definitions. If the attribute is applied to a generic private type, it
5780 indicates whether or not the corresponding actual type has access values.
5782 @node Has_Discriminants
5783 @unnumberedsec Has_Discriminants
5784 @cindex Discriminants, testing for
5785 @findex Has_Discriminants
5787 The prefix of the @code{Has_Discriminants} attribute is a type. The result
5788 is a Boolean value which is True if the type has discriminants, and False
5789 otherwise. The intended use of this attribute is in conjunction with generic
5790 definitions. If the attribute is applied to a generic private type, it
5791 indicates whether or not the corresponding actual type has discriminants.
5797 The @code{Img} attribute differs from @code{Image} in that it may be
5798 applied to objects as well as types, in which case it gives the
5799 @code{Image} for the subtype of the object. This is convenient for
5802 @smallexample @c ada
5803 Put_Line ("X = " & X'Img);
5807 has the same meaning as the more verbose:
5809 @smallexample @c ada
5810 Put_Line ("X = " & @var{T}'Image (X));
5814 where @var{T} is the (sub)type of the object @code{X}.
5817 @unnumberedsec Integer_Value
5818 @findex Integer_Value
5820 For every integer type @var{S}, @code{@var{S}'Integer_Value} denotes a
5821 function with the following spec:
5823 @smallexample @c ada
5824 function @var{S}'Integer_Value (Arg : @i{Universal_Fixed})
5829 The value returned is the integer value @var{V}, such that
5831 @smallexample @c ada
5832 Arg = @var{V} * @var{T}'Small
5836 where @var{T} is the type of @code{Arg}.
5837 The effect is thus similar to first doing an unchecked conversion from
5838 the fixed-point type to its corresponding implementation type, and then
5839 converting the result to the target integer type. The difference is
5840 that there are full range checks, to ensure that the result is in range.
5841 This attribute is primarily intended for use in implementation of the
5842 standard input-output functions for fixed-point values.
5845 @unnumberedsec Invalid_Value
5846 @findex Invalid_Value
5848 For every scalar type S, S'Invalid_Value returns an undefined value of the
5849 type. If possible this value is an invalid representation for the type. The
5850 value returned is identical to the value used to initialize an otherwise
5851 uninitialized value of the type if pragma Initialize_Scalars is used,
5852 including the ability to modify the value with the binder -Sxx flag and
5853 relevant environment variables at run time.
5856 @unnumberedsec Large
5857 @cindex Ada 83 attributes
5860 The @code{Large} attribute is provided for compatibility with Ada 83. See
5861 the Ada 83 reference manual for an exact description of the semantics of
5865 @unnumberedsec Machine_Size
5866 @findex Machine_Size
5868 This attribute is identical to the @code{Object_Size} attribute. It is
5869 provided for compatibility with the DEC Ada 83 attribute of this name.
5872 @unnumberedsec Mantissa
5873 @cindex Ada 83 attributes
5876 The @code{Mantissa} attribute is provided for compatibility with Ada 83. See
5877 the Ada 83 reference manual for an exact description of the semantics of
5880 @node Max_Interrupt_Priority
5881 @unnumberedsec Max_Interrupt_Priority
5882 @cindex Interrupt priority, maximum
5883 @findex Max_Interrupt_Priority
5885 @code{Standard'Max_Interrupt_Priority} (@code{Standard} is the only
5886 permissible prefix), provides the same value as
5887 @code{System.Max_Interrupt_Priority}.
5890 @unnumberedsec Max_Priority
5891 @cindex Priority, maximum
5892 @findex Max_Priority
5894 @code{Standard'Max_Priority} (@code{Standard} is the only permissible
5895 prefix) provides the same value as @code{System.Max_Priority}.
5897 @node Maximum_Alignment
5898 @unnumberedsec Maximum_Alignment
5899 @cindex Alignment, maximum
5900 @findex Maximum_Alignment
5902 @code{Standard'Maximum_Alignment} (@code{Standard} is the only
5903 permissible prefix) provides the maximum useful alignment value for the
5904 target. This is a static value that can be used to specify the alignment
5905 for an object, guaranteeing that it is properly aligned in all
5908 @node Mechanism_Code
5909 @unnumberedsec Mechanism_Code
5910 @cindex Return values, passing mechanism
5911 @cindex Parameters, passing mechanism
5912 @findex Mechanism_Code
5914 @code{@var{function}'Mechanism_Code} yields an integer code for the
5915 mechanism used for the result of function, and
5916 @code{@var{subprogram}'Mechanism_Code (@var{n})} yields the mechanism
5917 used for formal parameter number @var{n} (a static integer value with 1
5918 meaning the first parameter) of @var{subprogram}. The code returned is:
5926 by descriptor (default descriptor class)
5928 by descriptor (UBS: unaligned bit string)
5930 by descriptor (UBSB: aligned bit string with arbitrary bounds)
5932 by descriptor (UBA: unaligned bit array)
5934 by descriptor (S: string, also scalar access type parameter)
5936 by descriptor (SB: string with arbitrary bounds)
5938 by descriptor (A: contiguous array)
5940 by descriptor (NCA: non-contiguous array)
5944 Values from 3 through 10 are only relevant to Digital OpenVMS implementations.
5947 @node Null_Parameter
5948 @unnumberedsec Null_Parameter
5949 @cindex Zero address, passing
5950 @findex Null_Parameter
5952 A reference @code{@var{T}'Null_Parameter} denotes an imaginary object of
5953 type or subtype @var{T} allocated at machine address zero. The attribute
5954 is allowed only as the default expression of a formal parameter, or as
5955 an actual expression of a subprogram call. In either case, the
5956 subprogram must be imported.
5958 The identity of the object is represented by the address zero in the
5959 argument list, independent of the passing mechanism (explicit or
5962 This capability is needed to specify that a zero address should be
5963 passed for a record or other composite object passed by reference.
5964 There is no way of indicating this without the @code{Null_Parameter}
5968 @unnumberedsec Object_Size
5969 @cindex Size, used for objects
5972 The size of an object is not necessarily the same as the size of the type
5973 of an object. This is because by default object sizes are increased to be
5974 a multiple of the alignment of the object. For example,
5975 @code{Natural'Size} is
5976 31, but by default objects of type @code{Natural} will have a size of 32 bits.
5977 Similarly, a record containing an integer and a character:
5979 @smallexample @c ada
5987 will have a size of 40 (that is @code{Rec'Size} will be 40. The
5988 alignment will be 4, because of the
5989 integer field, and so the default size of record objects for this type
5990 will be 64 (8 bytes).
5994 @cindex Capturing Old values
5995 @cindex Postconditions
5997 The attribute Prefix'Old can be used within a
5998 subprogram to refer to the value of the prefix on entry. So for
5999 example if you have an argument of a record type X called Arg1,
6000 you can refer to Arg1.Field'Old which yields the value of
6001 Arg1.Field on entry. The implementation simply involves generating
6002 an object declaration which captures the value on entry. Any
6003 prefix is allowed except one of a limited type (since limited
6004 types cannot be copied to capture their values) or a local variable
6005 (since it does not exist at subprogram entry time).
6007 The following example shows the use of 'Old to implement
6008 a test of a postcondition:
6010 @smallexample @c ada
6021 package body Old_Pkg is
6022 Count : Natural := 0;
6026 ... code manipulating the value of Count
6028 pragma Assert (Count = Count'Old + 1);
6034 Note that it is allowed to apply 'Old to a constant entity, but this will
6035 result in a warning, since the old and new values will always be the same.
6037 @node Passed_By_Reference
6038 @unnumberedsec Passed_By_Reference
6039 @cindex Parameters, when passed by reference
6040 @findex Passed_By_Reference
6042 @code{@var{type}'Passed_By_Reference} for any subtype @var{type} returns
6043 a value of type @code{Boolean} value that is @code{True} if the type is
6044 normally passed by reference and @code{False} if the type is normally
6045 passed by copy in calls. For scalar types, the result is always @code{False}
6046 and is static. For non-scalar types, the result is non-static.
6049 @unnumberedsec Pool_Address
6050 @cindex Parameters, when passed by reference
6051 @findex Pool_Address
6053 @code{@var{X}'Pool_Address} for any object @var{X} returns the address
6054 of X within its storage pool. This is the same as
6055 @code{@var{X}'Address}, except that for an unconstrained array whose
6056 bounds are allocated just before the first component,
6057 @code{@var{X}'Pool_Address} returns the address of those bounds,
6058 whereas @code{@var{X}'Address} returns the address of the first
6061 Here, we are interpreting ``storage pool'' broadly to mean ``wherever
6062 the object is allocated'', which could be a user-defined storage pool,
6063 the global heap, on the stack, or in a static memory area. For an
6064 object created by @code{new}, @code{@var{Ptr.all}'Pool_Address} is
6065 what is passed to @code{Allocate} and returned from @code{Deallocate}.
6068 @unnumberedsec Range_Length
6069 @findex Range_Length
6071 @code{@var{type}'Range_Length} for any discrete type @var{type} yields
6072 the number of values represented by the subtype (zero for a null
6073 range). The result is static for static subtypes. @code{Range_Length}
6074 applied to the index subtype of a one dimensional array always gives the
6075 same result as @code{Range} applied to the array itself.
6078 @unnumberedsec Safe_Emax
6079 @cindex Ada 83 attributes
6082 The @code{Safe_Emax} attribute is provided for compatibility with Ada 83. See
6083 the Ada 83 reference manual for an exact description of the semantics of
6087 @unnumberedsec Safe_Large
6088 @cindex Ada 83 attributes
6091 The @code{Safe_Large} attribute is provided for compatibility with Ada 83. See
6092 the Ada 83 reference manual for an exact description of the semantics of
6096 @unnumberedsec Small
6097 @cindex Ada 83 attributes
6100 The @code{Small} attribute is defined in Ada 95 (and Ada 2005) only for
6102 GNAT also allows this attribute to be applied to floating-point types
6103 for compatibility with Ada 83. See
6104 the Ada 83 reference manual for an exact description of the semantics of
6105 this attribute when applied to floating-point types.
6108 @unnumberedsec Storage_Unit
6109 @findex Storage_Unit
6111 @code{Standard'Storage_Unit} (@code{Standard} is the only permissible
6112 prefix) provides the same value as @code{System.Storage_Unit}.
6115 @unnumberedsec Stub_Type
6118 The GNAT implementation of remote access-to-classwide types is
6119 organized as described in AARM section E.4 (20.t): a value of an RACW type
6120 (designating a remote object) is represented as a normal access
6121 value, pointing to a "stub" object which in turn contains the
6122 necessary information to contact the designated remote object. A
6123 call on any dispatching operation of such a stub object does the
6124 remote call, if necessary, using the information in the stub object
6125 to locate the target partition, etc.
6127 For a prefix @code{T} that denotes a remote access-to-classwide type,
6128 @code{T'Stub_Type} denotes the type of the corresponding stub objects.
6130 By construction, the layout of @code{T'Stub_Type} is identical to that of
6131 type @code{RACW_Stub_Type} declared in the internal implementation-defined
6132 unit @code{System.Partition_Interface}. Use of this attribute will create
6133 an implicit dependency on this unit.
6136 @unnumberedsec Target_Name
6139 @code{Standard'Target_Name} (@code{Standard} is the only permissible
6140 prefix) provides a static string value that identifies the target
6141 for the current compilation. For GCC implementations, this is the
6142 standard gcc target name without the terminating slash (for
6143 example, GNAT 5.0 on windows yields "i586-pc-mingw32msv").
6149 @code{Standard'Tick} (@code{Standard} is the only permissible prefix)
6150 provides the same value as @code{System.Tick},
6153 @unnumberedsec To_Address
6156 The @code{System'To_Address}
6157 (@code{System} is the only permissible prefix)
6158 denotes a function identical to
6159 @code{System.Storage_Elements.To_Address} except that
6160 it is a static attribute. This means that if its argument is
6161 a static expression, then the result of the attribute is a
6162 static expression. The result is that such an expression can be
6163 used in contexts (e.g.@: preelaborable packages) which require a
6164 static expression and where the function call could not be used
6165 (since the function call is always non-static, even if its
6166 argument is static).
6169 @unnumberedsec Type_Class
6172 @code{@var{type}'Type_Class} for any type or subtype @var{type} yields
6173 the value of the type class for the full type of @var{type}. If
6174 @var{type} is a generic formal type, the value is the value for the
6175 corresponding actual subtype. The value of this attribute is of type
6176 @code{System.Aux_DEC.Type_Class}, which has the following definition:
6178 @smallexample @c ada
6180 (Type_Class_Enumeration,
6182 Type_Class_Fixed_Point,
6183 Type_Class_Floating_Point,
6188 Type_Class_Address);
6192 Protected types yield the value @code{Type_Class_Task}, which thus
6193 applies to all concurrent types. This attribute is designed to
6194 be compatible with the DEC Ada 83 attribute of the same name.
6197 @unnumberedsec UET_Address
6200 The @code{UET_Address} attribute can only be used for a prefix which
6201 denotes a library package. It yields the address of the unit exception
6202 table when zero cost exception handling is used. This attribute is
6203 intended only for use within the GNAT implementation. See the unit
6204 @code{Ada.Exceptions} in files @file{a-except.ads} and @file{a-except.adb}
6205 for details on how this attribute is used in the implementation.
6207 @node Unconstrained_Array
6208 @unnumberedsec Unconstrained_Array
6209 @findex Unconstrained_Array
6211 The @code{Unconstrained_Array} attribute can be used with a prefix that
6212 denotes any type or subtype. It is a static attribute that yields
6213 @code{True} if the prefix designates an unconstrained array,
6214 and @code{False} otherwise. In a generic instance, the result is
6215 still static, and yields the result of applying this test to the
6218 @node Universal_Literal_String
6219 @unnumberedsec Universal_Literal_String
6220 @cindex Named numbers, representation of
6221 @findex Universal_Literal_String
6223 The prefix of @code{Universal_Literal_String} must be a named
6224 number. The static result is the string consisting of the characters of
6225 the number as defined in the original source. This allows the user
6226 program to access the actual text of named numbers without intermediate
6227 conversions and without the need to enclose the strings in quotes (which
6228 would preclude their use as numbers). This is used internally for the
6229 construction of values of the floating-point attributes from the file
6230 @file{ttypef.ads}, but may also be used by user programs.
6232 For example, the following program prints the first 50 digits of pi:
6234 @smallexample @c ada
6235 with Text_IO; use Text_IO;
6239 Put (Ada.Numerics.Pi'Universal_Literal_String);
6243 @node Unrestricted_Access
6244 @unnumberedsec Unrestricted_Access
6245 @cindex @code{Access}, unrestricted
6246 @findex Unrestricted_Access
6248 The @code{Unrestricted_Access} attribute is similar to @code{Access}
6249 except that all accessibility and aliased view checks are omitted. This
6250 is a user-beware attribute. It is similar to
6251 @code{Address}, for which it is a desirable replacement where the value
6252 desired is an access type. In other words, its effect is identical to
6253 first applying the @code{Address} attribute and then doing an unchecked
6254 conversion to a desired access type. In GNAT, but not necessarily in
6255 other implementations, the use of static chains for inner level
6256 subprograms means that @code{Unrestricted_Access} applied to a
6257 subprogram yields a value that can be called as long as the subprogram
6258 is in scope (normal Ada accessibility rules restrict this usage).
6260 It is possible to use @code{Unrestricted_Access} for any type, but care
6261 must be exercised if it is used to create pointers to unconstrained
6262 objects. In this case, the resulting pointer has the same scope as the
6263 context of the attribute, and may not be returned to some enclosing
6264 scope. For instance, a function cannot use @code{Unrestricted_Access}
6265 to create a unconstrained pointer and then return that value to the
6269 @unnumberedsec VADS_Size
6270 @cindex @code{Size}, VADS compatibility
6273 The @code{'VADS_Size} attribute is intended to make it easier to port
6274 legacy code which relies on the semantics of @code{'Size} as implemented
6275 by the VADS Ada 83 compiler. GNAT makes a best effort at duplicating the
6276 same semantic interpretation. In particular, @code{'VADS_Size} applied
6277 to a predefined or other primitive type with no Size clause yields the
6278 Object_Size (for example, @code{Natural'Size} is 32 rather than 31 on
6279 typical machines). In addition @code{'VADS_Size} applied to an object
6280 gives the result that would be obtained by applying the attribute to
6281 the corresponding type.
6284 @unnumberedsec Value_Size
6285 @cindex @code{Size}, setting for not-first subtype
6287 @code{@var{type}'Value_Size} is the number of bits required to represent
6288 a value of the given subtype. It is the same as @code{@var{type}'Size},
6289 but, unlike @code{Size}, may be set for non-first subtypes.
6292 @unnumberedsec Wchar_T_Size
6293 @findex Wchar_T_Size
6294 @code{Standard'Wchar_T_Size} (@code{Standard} is the only permissible
6295 prefix) provides the size in bits of the C @code{wchar_t} type
6296 primarily for constructing the definition of this type in
6297 package @code{Interfaces.C}.
6300 @unnumberedsec Word_Size
6302 @code{Standard'Word_Size} (@code{Standard} is the only permissible
6303 prefix) provides the value @code{System.Word_Size}.
6305 @c ------------------------
6306 @node Implementation Advice
6307 @chapter Implementation Advice
6309 The main text of the Ada Reference Manual describes the required
6310 behavior of all Ada compilers, and the GNAT compiler conforms to
6313 In addition, there are sections throughout the Ada Reference Manual headed
6314 by the phrase ``Implementation advice''. These sections are not normative,
6315 i.e., they do not specify requirements that all compilers must
6316 follow. Rather they provide advice on generally desirable behavior. You
6317 may wonder why they are not requirements. The most typical answer is
6318 that they describe behavior that seems generally desirable, but cannot
6319 be provided on all systems, or which may be undesirable on some systems.
6321 As far as practical, GNAT follows the implementation advice sections in
6322 the Ada Reference Manual. This chapter contains a table giving the
6323 reference manual section number, paragraph number and several keywords
6324 for each advice. Each entry consists of the text of the advice followed
6325 by the GNAT interpretation of this advice. Most often, this simply says
6326 ``followed'', which means that GNAT follows the advice. However, in a
6327 number of cases, GNAT deliberately deviates from this advice, in which
6328 case the text describes what GNAT does and why.
6330 @cindex Error detection
6331 @unnumberedsec 1.1.3(20): Error Detection
6334 If an implementation detects the use of an unsupported Specialized Needs
6335 Annex feature at run time, it should raise @code{Program_Error} if
6338 Not relevant. All specialized needs annex features are either supported,
6339 or diagnosed at compile time.
6342 @unnumberedsec 1.1.3(31): Child Units
6345 If an implementation wishes to provide implementation-defined
6346 extensions to the functionality of a language-defined library unit, it
6347 should normally do so by adding children to the library unit.
6351 @cindex Bounded errors
6352 @unnumberedsec 1.1.5(12): Bounded Errors
6355 If an implementation detects a bounded error or erroneous
6356 execution, it should raise @code{Program_Error}.
6358 Followed in all cases in which the implementation detects a bounded
6359 error or erroneous execution. Not all such situations are detected at
6363 @unnumberedsec 2.8(16): Pragmas
6366 Normally, implementation-defined pragmas should have no semantic effect
6367 for error-free programs; that is, if the implementation-defined pragmas
6368 are removed from a working program, the program should still be legal,
6369 and should still have the same semantics.
6371 The following implementation defined pragmas are exceptions to this
6383 @item CPP_Constructor
6387 @item Interface_Name
6389 @item Machine_Attribute
6391 @item Unimplemented_Unit
6393 @item Unchecked_Union
6398 In each of the above cases, it is essential to the purpose of the pragma
6399 that this advice not be followed. For details see the separate section
6400 on implementation defined pragmas.
6402 @unnumberedsec 2.8(17-19): Pragmas
6405 Normally, an implementation should not define pragmas that can
6406 make an illegal program legal, except as follows:
6410 A pragma used to complete a declaration, such as a pragma @code{Import};
6414 A pragma used to configure the environment by adding, removing, or
6415 replacing @code{library_items}.
6417 See response to paragraph 16 of this same section.
6419 @cindex Character Sets
6420 @cindex Alternative Character Sets
6421 @unnumberedsec 3.5.2(5): Alternative Character Sets
6424 If an implementation supports a mode with alternative interpretations
6425 for @code{Character} and @code{Wide_Character}, the set of graphic
6426 characters of @code{Character} should nevertheless remain a proper
6427 subset of the set of graphic characters of @code{Wide_Character}. Any
6428 character set ``localizations'' should be reflected in the results of
6429 the subprograms defined in the language-defined package
6430 @code{Characters.Handling} (see A.3) available in such a mode. In a mode with
6431 an alternative interpretation of @code{Character}, the implementation should
6432 also support a corresponding change in what is a legal
6433 @code{identifier_letter}.
6435 Not all wide character modes follow this advice, in particular the JIS
6436 and IEC modes reflect standard usage in Japan, and in these encoding,
6437 the upper half of the Latin-1 set is not part of the wide-character
6438 subset, since the most significant bit is used for wide character
6439 encoding. However, this only applies to the external forms. Internally
6440 there is no such restriction.
6442 @cindex Integer types
6443 @unnumberedsec 3.5.4(28): Integer Types
6447 An implementation should support @code{Long_Integer} in addition to
6448 @code{Integer} if the target machine supports 32-bit (or longer)
6449 arithmetic. No other named integer subtypes are recommended for package
6450 @code{Standard}. Instead, appropriate named integer subtypes should be
6451 provided in the library package @code{Interfaces} (see B.2).
6453 @code{Long_Integer} is supported. Other standard integer types are supported
6454 so this advice is not fully followed. These types
6455 are supported for convenient interface to C, and so that all hardware
6456 types of the machine are easily available.
6457 @unnumberedsec 3.5.4(29): Integer Types
6461 An implementation for a two's complement machine should support
6462 modular types with a binary modulus up to @code{System.Max_Int*2+2}. An
6463 implementation should support a non-binary modules up to @code{Integer'Last}.
6467 @cindex Enumeration values
6468 @unnumberedsec 3.5.5(8): Enumeration Values
6471 For the evaluation of a call on @code{@var{S}'Pos} for an enumeration
6472 subtype, if the value of the operand does not correspond to the internal
6473 code for any enumeration literal of its type (perhaps due to an
6474 un-initialized variable), then the implementation should raise
6475 @code{Program_Error}. This is particularly important for enumeration
6476 types with noncontiguous internal codes specified by an
6477 enumeration_representation_clause.
6482 @unnumberedsec 3.5.7(17): Float Types
6485 An implementation should support @code{Long_Float} in addition to
6486 @code{Float} if the target machine supports 11 or more digits of
6487 precision. No other named floating point subtypes are recommended for
6488 package @code{Standard}. Instead, appropriate named floating point subtypes
6489 should be provided in the library package @code{Interfaces} (see B.2).
6491 @code{Short_Float} and @code{Long_Long_Float} are also provided. The
6492 former provides improved compatibility with other implementations
6493 supporting this type. The latter corresponds to the highest precision
6494 floating-point type supported by the hardware. On most machines, this
6495 will be the same as @code{Long_Float}, but on some machines, it will
6496 correspond to the IEEE extended form. The notable case is all ia32
6497 (x86) implementations, where @code{Long_Long_Float} corresponds to
6498 the 80-bit extended precision format supported in hardware on this
6499 processor. Note that the 128-bit format on SPARC is not supported,
6500 since this is a software rather than a hardware format.
6502 @cindex Multidimensional arrays
6503 @cindex Arrays, multidimensional
6504 @unnumberedsec 3.6.2(11): Multidimensional Arrays
6507 An implementation should normally represent multidimensional arrays in
6508 row-major order, consistent with the notation used for multidimensional
6509 array aggregates (see 4.3.3). However, if a pragma @code{Convention}
6510 (@code{Fortran}, @dots{}) applies to a multidimensional array type, then
6511 column-major order should be used instead (see B.5, ``Interfacing with
6516 @findex Duration'Small
6517 @unnumberedsec 9.6(30-31): Duration'Small
6520 Whenever possible in an implementation, the value of @code{Duration'Small}
6521 should be no greater than 100 microseconds.
6523 Followed. (@code{Duration'Small} = 10**(@minus{}9)).
6527 The time base for @code{delay_relative_statements} should be monotonic;
6528 it need not be the same time base as used for @code{Calendar.Clock}.
6532 @unnumberedsec 10.2.1(12): Consistent Representation
6535 In an implementation, a type declared in a pre-elaborated package should
6536 have the same representation in every elaboration of a given version of
6537 the package, whether the elaborations occur in distinct executions of
6538 the same program, or in executions of distinct programs or partitions
6539 that include the given version.
6541 Followed, except in the case of tagged types. Tagged types involve
6542 implicit pointers to a local copy of a dispatch table, and these pointers
6543 have representations which thus depend on a particular elaboration of the
6544 package. It is not easy to see how it would be possible to follow this
6545 advice without severely impacting efficiency of execution.
6547 @cindex Exception information
6548 @unnumberedsec 11.4.1(19): Exception Information
6551 @code{Exception_Message} by default and @code{Exception_Information}
6552 should produce information useful for
6553 debugging. @code{Exception_Message} should be short, about one
6554 line. @code{Exception_Information} can be long. @code{Exception_Message}
6555 should not include the
6556 @code{Exception_Name}. @code{Exception_Information} should include both
6557 the @code{Exception_Name} and the @code{Exception_Message}.
6559 Followed. For each exception that doesn't have a specified
6560 @code{Exception_Message}, the compiler generates one containing the location
6561 of the raise statement. This location has the form ``file:line'', where
6562 file is the short file name (without path information) and line is the line
6563 number in the file. Note that in the case of the Zero Cost Exception
6564 mechanism, these messages become redundant with the Exception_Information that
6565 contains a full backtrace of the calling sequence, so they are disabled.
6566 To disable explicitly the generation of the source location message, use the
6567 Pragma @code{Discard_Names}.
6569 @cindex Suppression of checks
6570 @cindex Checks, suppression of
6571 @unnumberedsec 11.5(28): Suppression of Checks
6574 The implementation should minimize the code executed for checks that
6575 have been suppressed.
6579 @cindex Representation clauses
6580 @unnumberedsec 13.1 (21-24): Representation Clauses
6583 The recommended level of support for all representation items is
6584 qualified as follows:
6588 An implementation need not support representation items containing
6589 non-static expressions, except that an implementation should support a
6590 representation item for a given entity if each non-static expression in
6591 the representation item is a name that statically denotes a constant
6592 declared before the entity.
6594 Followed. In fact, GNAT goes beyond the recommended level of support
6595 by allowing nonstatic expressions in some representation clauses even
6596 without the need to declare constants initialized with the values of
6600 @smallexample @c ada
6603 for Y'Address use X'Address;>>
6609 An implementation need not support a specification for the @code{Size}
6610 for a given composite subtype, nor the size or storage place for an
6611 object (including a component) of a given composite subtype, unless the
6612 constraints on the subtype and its composite subcomponents (if any) are
6613 all static constraints.
6615 Followed. Size Clauses are not permitted on non-static components, as
6620 An aliased component, or a component whose type is by-reference, should
6621 always be allocated at an addressable location.
6625 @cindex Packed types
6626 @unnumberedsec 13.2(6-8): Packed Types
6629 If a type is packed, then the implementation should try to minimize
6630 storage allocated to objects of the type, possibly at the expense of
6631 speed of accessing components, subject to reasonable complexity in
6632 addressing calculations.
6636 The recommended level of support pragma @code{Pack} is:
6638 For a packed record type, the components should be packed as tightly as
6639 possible subject to the Sizes of the component subtypes, and subject to
6640 any @code{record_representation_clause} that applies to the type; the
6641 implementation may, but need not, reorder components or cross aligned
6642 word boundaries to improve the packing. A component whose @code{Size} is
6643 greater than the word size may be allocated an integral number of words.
6645 Followed. Tight packing of arrays is supported for all component sizes
6646 up to 64-bits. If the array component size is 1 (that is to say, if
6647 the component is a boolean type or an enumeration type with two values)
6648 then values of the type are implicitly initialized to zero. This
6649 happens both for objects of the packed type, and for objects that have a
6650 subcomponent of the packed type.
6654 An implementation should support Address clauses for imported
6658 @cindex @code{Address} clauses
6659 @unnumberedsec 13.3(14-19): Address Clauses
6663 For an array @var{X}, @code{@var{X}'Address} should point at the first
6664 component of the array, and not at the array bounds.
6670 The recommended level of support for the @code{Address} attribute is:
6672 @code{@var{X}'Address} should produce a useful result if @var{X} is an
6673 object that is aliased or of a by-reference type, or is an entity whose
6674 @code{Address} has been specified.
6676 Followed. A valid address will be produced even if none of those
6677 conditions have been met. If necessary, the object is forced into
6678 memory to ensure the address is valid.
6682 An implementation should support @code{Address} clauses for imported
6689 Objects (including subcomponents) that are aliased or of a by-reference
6690 type should be allocated on storage element boundaries.
6696 If the @code{Address} of an object is specified, or it is imported or exported,
6697 then the implementation should not perform optimizations based on
6698 assumptions of no aliases.
6702 @cindex @code{Alignment} clauses
6703 @unnumberedsec 13.3(29-35): Alignment Clauses
6706 The recommended level of support for the @code{Alignment} attribute for
6709 An implementation should support specified Alignments that are factors
6710 and multiples of the number of storage elements per word, subject to the
6717 An implementation need not support specified @code{Alignment}s for
6718 combinations of @code{Size}s and @code{Alignment}s that cannot be easily
6719 loaded and stored by available machine instructions.
6725 An implementation need not support specified @code{Alignment}s that are
6726 greater than the maximum @code{Alignment} the implementation ever returns by
6733 The recommended level of support for the @code{Alignment} attribute for
6736 Same as above, for subtypes, but in addition:
6742 For stand-alone library-level objects of statically constrained
6743 subtypes, the implementation should support all @code{Alignment}s
6744 supported by the target linker. For example, page alignment is likely to
6745 be supported for such objects, but not for subtypes.
6749 @cindex @code{Size} clauses
6750 @unnumberedsec 13.3(42-43): Size Clauses
6753 The recommended level of support for the @code{Size} attribute of
6756 A @code{Size} clause should be supported for an object if the specified
6757 @code{Size} is at least as large as its subtype's @code{Size}, and
6758 corresponds to a size in storage elements that is a multiple of the
6759 object's @code{Alignment} (if the @code{Alignment} is nonzero).
6763 @unnumberedsec 13.3(50-56): Size Clauses
6766 If the @code{Size} of a subtype is specified, and allows for efficient
6767 independent addressability (see 9.10) on the target architecture, then
6768 the @code{Size} of the following objects of the subtype should equal the
6769 @code{Size} of the subtype:
6771 Aliased objects (including components).
6777 @code{Size} clause on a composite subtype should not affect the
6778 internal layout of components.
6780 Followed. But note that this can be overridden by use of the implementation
6781 pragma Implicit_Packing in the case of packed arrays.
6785 The recommended level of support for the @code{Size} attribute of subtypes is:
6789 The @code{Size} (if not specified) of a static discrete or fixed point
6790 subtype should be the number of bits needed to represent each value
6791 belonging to the subtype using an unbiased representation, leaving space
6792 for a sign bit only if the subtype contains negative values. If such a
6793 subtype is a first subtype, then an implementation should support a
6794 specified @code{Size} for it that reflects this representation.
6800 For a subtype implemented with levels of indirection, the @code{Size}
6801 should include the size of the pointers, but not the size of what they
6806 @cindex @code{Component_Size} clauses
6807 @unnumberedsec 13.3(71-73): Component Size Clauses
6810 The recommended level of support for the @code{Component_Size}
6815 An implementation need not support specified @code{Component_Sizes} that are
6816 less than the @code{Size} of the component subtype.
6822 An implementation should support specified @code{Component_Size}s that
6823 are factors and multiples of the word size. For such
6824 @code{Component_Size}s, the array should contain no gaps between
6825 components. For other @code{Component_Size}s (if supported), the array
6826 should contain no gaps between components when packing is also
6827 specified; the implementation should forbid this combination in cases
6828 where it cannot support a no-gaps representation.
6832 @cindex Enumeration representation clauses
6833 @cindex Representation clauses, enumeration
6834 @unnumberedsec 13.4(9-10): Enumeration Representation Clauses
6837 The recommended level of support for enumeration representation clauses
6840 An implementation need not support enumeration representation clauses
6841 for boolean types, but should at minimum support the internal codes in
6842 the range @code{System.Min_Int.System.Max_Int}.
6846 @cindex Record representation clauses
6847 @cindex Representation clauses, records
6848 @unnumberedsec 13.5.1(17-22): Record Representation Clauses
6851 The recommended level of support for
6852 @*@code{record_representation_clauses} is:
6854 An implementation should support storage places that can be extracted
6855 with a load, mask, shift sequence of machine code, and set with a load,
6856 shift, mask, store sequence, given the available machine instructions
6863 A storage place should be supported if its size is equal to the
6864 @code{Size} of the component subtype, and it starts and ends on a
6865 boundary that obeys the @code{Alignment} of the component subtype.
6871 If the default bit ordering applies to the declaration of a given type,
6872 then for a component whose subtype's @code{Size} is less than the word
6873 size, any storage place that does not cross an aligned word boundary
6874 should be supported.
6880 An implementation may reserve a storage place for the tag field of a
6881 tagged type, and disallow other components from overlapping that place.
6883 Followed. The storage place for the tag field is the beginning of the tagged
6884 record, and its size is Address'Size. GNAT will reject an explicit component
6885 clause for the tag field.
6889 An implementation need not support a @code{component_clause} for a
6890 component of an extension part if the storage place is not after the
6891 storage places of all components of the parent type, whether or not
6892 those storage places had been specified.
6894 Followed. The above advice on record representation clauses is followed,
6895 and all mentioned features are implemented.
6897 @cindex Storage place attributes
6898 @unnumberedsec 13.5.2(5): Storage Place Attributes
6901 If a component is represented using some form of pointer (such as an
6902 offset) to the actual data of the component, and this data is contiguous
6903 with the rest of the object, then the storage place attributes should
6904 reflect the place of the actual data, not the pointer. If a component is
6905 allocated discontinuously from the rest of the object, then a warning
6906 should be generated upon reference to one of its storage place
6909 Followed. There are no such components in GNAT@.
6911 @cindex Bit ordering
6912 @unnumberedsec 13.5.3(7-8): Bit Ordering
6915 The recommended level of support for the non-default bit ordering is:
6919 If @code{Word_Size} = @code{Storage_Unit}, then the implementation
6920 should support the non-default bit ordering in addition to the default
6923 Followed. Word size does not equal storage size in this implementation.
6924 Thus non-default bit ordering is not supported.
6926 @cindex @code{Address}, as private type
6927 @unnumberedsec 13.7(37): Address as Private
6930 @code{Address} should be of a private type.
6934 @cindex Operations, on @code{Address}
6935 @cindex @code{Address}, operations of
6936 @unnumberedsec 13.7.1(16): Address Operations
6939 Operations in @code{System} and its children should reflect the target
6940 environment semantics as closely as is reasonable. For example, on most
6941 machines, it makes sense for address arithmetic to ``wrap around''.
6942 Operations that do not make sense should raise @code{Program_Error}.
6944 Followed. Address arithmetic is modular arithmetic that wraps around. No
6945 operation raises @code{Program_Error}, since all operations make sense.
6947 @cindex Unchecked conversion
6948 @unnumberedsec 13.9(14-17): Unchecked Conversion
6951 The @code{Size} of an array object should not include its bounds; hence,
6952 the bounds should not be part of the converted data.
6958 The implementation should not generate unnecessary run-time checks to
6959 ensure that the representation of @var{S} is a representation of the
6960 target type. It should take advantage of the permission to return by
6961 reference when possible. Restrictions on unchecked conversions should be
6962 avoided unless required by the target environment.
6964 Followed. There are no restrictions on unchecked conversion. A warning is
6965 generated if the source and target types do not have the same size since
6966 the semantics in this case may be target dependent.
6970 The recommended level of support for unchecked conversions is:
6974 Unchecked conversions should be supported and should be reversible in
6975 the cases where this clause defines the result. To enable meaningful use
6976 of unchecked conversion, a contiguous representation should be used for
6977 elementary subtypes, for statically constrained array subtypes whose
6978 component subtype is one of the subtypes described in this paragraph,
6979 and for record subtypes without discriminants whose component subtypes
6980 are described in this paragraph.
6984 @cindex Heap usage, implicit
6985 @unnumberedsec 13.11(23-25): Implicit Heap Usage
6988 An implementation should document any cases in which it dynamically
6989 allocates heap storage for a purpose other than the evaluation of an
6992 Followed, the only other points at which heap storage is dynamically
6993 allocated are as follows:
6997 At initial elaboration time, to allocate dynamically sized global
7001 To allocate space for a task when a task is created.
7004 To extend the secondary stack dynamically when needed. The secondary
7005 stack is used for returning variable length results.
7010 A default (implementation-provided) storage pool for an
7011 access-to-constant type should not have overhead to support deallocation of
7018 A storage pool for an anonymous access type should be created at the
7019 point of an allocator for the type, and be reclaimed when the designated
7020 object becomes inaccessible.
7024 @cindex Unchecked deallocation
7025 @unnumberedsec 13.11.2(17): Unchecked De-allocation
7028 For a standard storage pool, @code{Free} should actually reclaim the
7033 @cindex Stream oriented attributes
7034 @unnumberedsec 13.13.2(17): Stream Oriented Attributes
7037 If a stream element is the same size as a storage element, then the
7038 normal in-memory representation should be used by @code{Read} and
7039 @code{Write} for scalar objects. Otherwise, @code{Read} and @code{Write}
7040 should use the smallest number of stream elements needed to represent
7041 all values in the base range of the scalar type.
7044 Followed. By default, GNAT uses the interpretation suggested by AI-195,
7045 which specifies using the size of the first subtype.
7046 However, such an implementation is based on direct binary
7047 representations and is therefore target- and endianness-dependent.
7048 To address this issue, GNAT also supplies an alternate implementation
7049 of the stream attributes @code{Read} and @code{Write},
7050 which uses the target-independent XDR standard representation
7052 @cindex XDR representation
7053 @cindex @code{Read} attribute
7054 @cindex @code{Write} attribute
7055 @cindex Stream oriented attributes
7056 The XDR implementation is provided as an alternative body of the
7057 @code{System.Stream_Attributes} package, in the file
7058 @file{s-strxdr.adb} in the GNAT library.
7059 There is no @file{s-strxdr.ads} file.
7060 In order to install the XDR implementation, do the following:
7062 @item Replace the default implementation of the
7063 @code{System.Stream_Attributes} package with the XDR implementation.
7064 For example on a Unix platform issue the commands:
7066 $ mv s-stratt.adb s-strold.adb
7067 $ mv s-strxdr.adb s-stratt.adb
7071 Rebuild the GNAT run-time library as documented in
7072 @ref{GNAT and Libraries,,, gnat_ugn, @value{EDITION} User's Guide}.
7075 @unnumberedsec A.1(52): Names of Predefined Numeric Types
7078 If an implementation provides additional named predefined integer types,
7079 then the names should end with @samp{Integer} as in
7080 @samp{Long_Integer}. If an implementation provides additional named
7081 predefined floating point types, then the names should end with
7082 @samp{Float} as in @samp{Long_Float}.
7086 @findex Ada.Characters.Handling
7087 @unnumberedsec A.3.2(49): @code{Ada.Characters.Handling}
7090 If an implementation provides a localized definition of @code{Character}
7091 or @code{Wide_Character}, then the effects of the subprograms in
7092 @code{Characters.Handling} should reflect the localizations. See also
7095 Followed. GNAT provides no such localized definitions.
7097 @cindex Bounded-length strings
7098 @unnumberedsec A.4.4(106): Bounded-Length String Handling
7101 Bounded string objects should not be implemented by implicit pointers
7102 and dynamic allocation.
7104 Followed. No implicit pointers or dynamic allocation are used.
7106 @cindex Random number generation
7107 @unnumberedsec A.5.2(46-47): Random Number Generation
7110 Any storage associated with an object of type @code{Generator} should be
7111 reclaimed on exit from the scope of the object.
7117 If the generator period is sufficiently long in relation to the number
7118 of distinct initiator values, then each possible value of
7119 @code{Initiator} passed to @code{Reset} should initiate a sequence of
7120 random numbers that does not, in a practical sense, overlap the sequence
7121 initiated by any other value. If this is not possible, then the mapping
7122 between initiator values and generator states should be a rapidly
7123 varying function of the initiator value.
7125 Followed. The generator period is sufficiently long for the first
7126 condition here to hold true.
7128 @findex Get_Immediate
7129 @unnumberedsec A.10.7(23): @code{Get_Immediate}
7132 The @code{Get_Immediate} procedures should be implemented with
7133 unbuffered input. For a device such as a keyboard, input should be
7134 @dfn{available} if a key has already been typed, whereas for a disk
7135 file, input should always be available except at end of file. For a file
7136 associated with a keyboard-like device, any line-editing features of the
7137 underlying operating system should be disabled during the execution of
7138 @code{Get_Immediate}.
7140 Followed on all targets except VxWorks. For VxWorks, there is no way to
7141 provide this functionality that does not result in the input buffer being
7142 flushed before the @code{Get_Immediate} call. A special unit
7143 @code{Interfaces.Vxworks.IO} is provided that contains routines to enable
7147 @unnumberedsec B.1(39-41): Pragma @code{Export}
7150 If an implementation supports pragma @code{Export} to a given language,
7151 then it should also allow the main subprogram to be written in that
7152 language. It should support some mechanism for invoking the elaboration
7153 of the Ada library units included in the system, and for invoking the
7154 finalization of the environment task. On typical systems, the
7155 recommended mechanism is to provide two subprograms whose link names are
7156 @code{adainit} and @code{adafinal}. @code{adainit} should contain the
7157 elaboration code for library units. @code{adafinal} should contain the
7158 finalization code. These subprograms should have no effect the second
7159 and subsequent time they are called.
7165 Automatic elaboration of pre-elaborated packages should be
7166 provided when pragma @code{Export} is supported.
7168 Followed when the main program is in Ada. If the main program is in a
7169 foreign language, then
7170 @code{adainit} must be called to elaborate pre-elaborated
7175 For each supported convention @var{L} other than @code{Intrinsic}, an
7176 implementation should support @code{Import} and @code{Export} pragmas
7177 for objects of @var{L}-compatible types and for subprograms, and pragma
7178 @code{Convention} for @var{L}-eligible types and for subprograms,
7179 presuming the other language has corresponding features. Pragma
7180 @code{Convention} need not be supported for scalar types.
7184 @cindex Package @code{Interfaces}
7186 @unnumberedsec B.2(12-13): Package @code{Interfaces}
7189 For each implementation-defined convention identifier, there should be a
7190 child package of package Interfaces with the corresponding name. This
7191 package should contain any declarations that would be useful for
7192 interfacing to the language (implementation) represented by the
7193 convention. Any declarations useful for interfacing to any language on
7194 the given hardware architecture should be provided directly in
7197 Followed. An additional package not defined
7198 in the Ada Reference Manual is @code{Interfaces.CPP}, used
7199 for interfacing to C++.
7203 An implementation supporting an interface to C, COBOL, or Fortran should
7204 provide the corresponding package or packages described in the following
7207 Followed. GNAT provides all the packages described in this section.
7209 @cindex C, interfacing with
7210 @unnumberedsec B.3(63-71): Interfacing with C
7213 An implementation should support the following interface correspondences
7220 An Ada procedure corresponds to a void-returning C function.
7226 An Ada function corresponds to a non-void C function.
7232 An Ada @code{in} scalar parameter is passed as a scalar argument to a C
7239 An Ada @code{in} parameter of an access-to-object type with designated
7240 type @var{T} is passed as a @code{@var{t}*} argument to a C function,
7241 where @var{t} is the C type corresponding to the Ada type @var{T}.
7247 An Ada access @var{T} parameter, or an Ada @code{out} or @code{in out}
7248 parameter of an elementary type @var{T}, is passed as a @code{@var{t}*}
7249 argument to a C function, where @var{t} is the C type corresponding to
7250 the Ada type @var{T}. In the case of an elementary @code{out} or
7251 @code{in out} parameter, a pointer to a temporary copy is used to
7252 preserve by-copy semantics.
7258 An Ada parameter of a record type @var{T}, of any mode, is passed as a
7259 @code{@var{t}*} argument to a C function, where @var{t} is the C
7260 structure corresponding to the Ada type @var{T}.
7262 Followed. This convention may be overridden by the use of the C_Pass_By_Copy
7263 pragma, or Convention, or by explicitly specifying the mechanism for a given
7264 call using an extended import or export pragma.
7268 An Ada parameter of an array type with component type @var{T}, of any
7269 mode, is passed as a @code{@var{t}*} argument to a C function, where
7270 @var{t} is the C type corresponding to the Ada type @var{T}.
7276 An Ada parameter of an access-to-subprogram type is passed as a pointer
7277 to a C function whose prototype corresponds to the designated
7278 subprogram's specification.
7282 @cindex COBOL, interfacing with
7283 @unnumberedsec B.4(95-98): Interfacing with COBOL
7286 An Ada implementation should support the following interface
7287 correspondences between Ada and COBOL@.
7293 An Ada access @var{T} parameter is passed as a @samp{BY REFERENCE} data item of
7294 the COBOL type corresponding to @var{T}.
7300 An Ada in scalar parameter is passed as a @samp{BY CONTENT} data item of
7301 the corresponding COBOL type.
7307 Any other Ada parameter is passed as a @samp{BY REFERENCE} data item of the
7308 COBOL type corresponding to the Ada parameter type; for scalars, a local
7309 copy is used if necessary to ensure by-copy semantics.
7313 @cindex Fortran, interfacing with
7314 @unnumberedsec B.5(22-26): Interfacing with Fortran
7317 An Ada implementation should support the following interface
7318 correspondences between Ada and Fortran:
7324 An Ada procedure corresponds to a Fortran subroutine.
7330 An Ada function corresponds to a Fortran function.
7336 An Ada parameter of an elementary, array, or record type @var{T} is
7337 passed as a @var{T} argument to a Fortran procedure, where @var{T} is
7338 the Fortran type corresponding to the Ada type @var{T}, and where the
7339 INTENT attribute of the corresponding dummy argument matches the Ada
7340 formal parameter mode; the Fortran implementation's parameter passing
7341 conventions are used. For elementary types, a local copy is used if
7342 necessary to ensure by-copy semantics.
7348 An Ada parameter of an access-to-subprogram type is passed as a
7349 reference to a Fortran procedure whose interface corresponds to the
7350 designated subprogram's specification.
7354 @cindex Machine operations
7355 @unnumberedsec C.1(3-5): Access to Machine Operations
7358 The machine code or intrinsic support should allow access to all
7359 operations normally available to assembly language programmers for the
7360 target environment, including privileged instructions, if any.
7366 The interfacing pragmas (see Annex B) should support interface to
7367 assembler; the default assembler should be associated with the
7368 convention identifier @code{Assembler}.
7374 If an entity is exported to assembly language, then the implementation
7375 should allocate it at an addressable location, and should ensure that it
7376 is retained by the linking process, even if not otherwise referenced
7377 from the Ada code. The implementation should assume that any call to a
7378 machine code or assembler subprogram is allowed to read or update every
7379 object that is specified as exported.
7383 @unnumberedsec C.1(10-16): Access to Machine Operations
7386 The implementation should ensure that little or no overhead is
7387 associated with calling intrinsic and machine-code subprograms.
7389 Followed for both intrinsics and machine-code subprograms.
7393 It is recommended that intrinsic subprograms be provided for convenient
7394 access to any machine operations that provide special capabilities or
7395 efficiency and that are not otherwise available through the language
7398 Followed. A full set of machine operation intrinsic subprograms is provided.
7402 Atomic read-modify-write operations---e.g.@:, test and set, compare and
7403 swap, decrement and test, enqueue/dequeue.
7405 Followed on any target supporting such operations.
7409 Standard numeric functions---e.g.@:, sin, log.
7411 Followed on any target supporting such operations.
7415 String manipulation operations---e.g.@:, translate and test.
7417 Followed on any target supporting such operations.
7421 Vector operations---e.g.@:, compare vector against thresholds.
7423 Followed on any target supporting such operations.
7427 Direct operations on I/O ports.
7429 Followed on any target supporting such operations.
7431 @cindex Interrupt support
7432 @unnumberedsec C.3(28): Interrupt Support
7435 If the @code{Ceiling_Locking} policy is not in effect, the
7436 implementation should provide means for the application to specify which
7437 interrupts are to be blocked during protected actions, if the underlying
7438 system allows for a finer-grain control of interrupt blocking.
7440 Followed. The underlying system does not allow for finer-grain control
7441 of interrupt blocking.
7443 @cindex Protected procedure handlers
7444 @unnumberedsec C.3.1(20-21): Protected Procedure Handlers
7447 Whenever possible, the implementation should allow interrupt handlers to
7448 be called directly by the hardware.
7452 This is never possible under IRIX, so this is followed by default.
7454 Followed on any target where the underlying operating system permits
7459 Whenever practical, violations of any
7460 implementation-defined restrictions should be detected before run time.
7462 Followed. Compile time warnings are given when possible.
7464 @cindex Package @code{Interrupts}
7466 @unnumberedsec C.3.2(25): Package @code{Interrupts}
7470 If implementation-defined forms of interrupt handler procedures are
7471 supported, such as protected procedures with parameters, then for each
7472 such form of a handler, a type analogous to @code{Parameterless_Handler}
7473 should be specified in a child package of @code{Interrupts}, with the
7474 same operations as in the predefined package Interrupts.
7478 @cindex Pre-elaboration requirements
7479 @unnumberedsec C.4(14): Pre-elaboration Requirements
7482 It is recommended that pre-elaborated packages be implemented in such a
7483 way that there should be little or no code executed at run time for the
7484 elaboration of entities not already covered by the Implementation
7487 Followed. Executable code is generated in some cases, e.g.@: loops
7488 to initialize large arrays.
7490 @unnumberedsec C.5(8): Pragma @code{Discard_Names}
7494 If the pragma applies to an entity, then the implementation should
7495 reduce the amount of storage used for storing names associated with that
7500 @cindex Package @code{Task_Attributes}
7501 @findex Task_Attributes
7502 @unnumberedsec C.7.2(30): The Package Task_Attributes
7505 Some implementations are targeted to domains in which memory use at run
7506 time must be completely deterministic. For such implementations, it is
7507 recommended that the storage for task attributes will be pre-allocated
7508 statically and not from the heap. This can be accomplished by either
7509 placing restrictions on the number and the size of the task's
7510 attributes, or by using the pre-allocated storage for the first @var{N}
7511 attribute objects, and the heap for the others. In the latter case,
7512 @var{N} should be documented.
7514 Not followed. This implementation is not targeted to such a domain.
7516 @cindex Locking Policies
7517 @unnumberedsec D.3(17): Locking Policies
7521 The implementation should use names that end with @samp{_Locking} for
7522 locking policies defined by the implementation.
7524 Followed. A single implementation-defined locking policy is defined,
7525 whose name (@code{Inheritance_Locking}) follows this suggestion.
7527 @cindex Entry queuing policies
7528 @unnumberedsec D.4(16): Entry Queuing Policies
7531 Names that end with @samp{_Queuing} should be used
7532 for all implementation-defined queuing policies.
7534 Followed. No such implementation-defined queuing policies exist.
7536 @cindex Preemptive abort
7537 @unnumberedsec D.6(9-10): Preemptive Abort
7540 Even though the @code{abort_statement} is included in the list of
7541 potentially blocking operations (see 9.5.1), it is recommended that this
7542 statement be implemented in a way that never requires the task executing
7543 the @code{abort_statement} to block.
7549 On a multi-processor, the delay associated with aborting a task on
7550 another processor should be bounded; the implementation should use
7551 periodic polling, if necessary, to achieve this.
7555 @cindex Tasking restrictions
7556 @unnumberedsec D.7(21): Tasking Restrictions
7559 When feasible, the implementation should take advantage of the specified
7560 restrictions to produce a more efficient implementation.
7562 GNAT currently takes advantage of these restrictions by providing an optimized
7563 run time when the Ravenscar profile and the GNAT restricted run time set
7564 of restrictions are specified. See pragma @code{Profile (Ravenscar)} and
7565 pragma @code{Profile (Restricted)} for more details.
7567 @cindex Time, monotonic
7568 @unnumberedsec D.8(47-49): Monotonic Time
7571 When appropriate, implementations should provide configuration
7572 mechanisms to change the value of @code{Tick}.
7574 Such configuration mechanisms are not appropriate to this implementation
7575 and are thus not supported.
7579 It is recommended that @code{Calendar.Clock} and @code{Real_Time.Clock}
7580 be implemented as transformations of the same time base.
7586 It is recommended that the @dfn{best} time base which exists in
7587 the underlying system be available to the application through
7588 @code{Clock}. @dfn{Best} may mean highest accuracy or largest range.
7592 @cindex Partition communication subsystem
7594 @unnumberedsec E.5(28-29): Partition Communication Subsystem
7597 Whenever possible, the PCS on the called partition should allow for
7598 multiple tasks to call the RPC-receiver with different messages and
7599 should allow them to block until the corresponding subprogram body
7602 Followed by GLADE, a separately supplied PCS that can be used with
7607 The @code{Write} operation on a stream of type @code{Params_Stream_Type}
7608 should raise @code{Storage_Error} if it runs out of space trying to
7609 write the @code{Item} into the stream.
7611 Followed by GLADE, a separately supplied PCS that can be used with
7614 @cindex COBOL support
7615 @unnumberedsec F(7): COBOL Support
7618 If COBOL (respectively, C) is widely supported in the target
7619 environment, implementations supporting the Information Systems Annex
7620 should provide the child package @code{Interfaces.COBOL} (respectively,
7621 @code{Interfaces.C}) specified in Annex B and should support a
7622 @code{convention_identifier} of COBOL (respectively, C) in the interfacing
7623 pragmas (see Annex B), thus allowing Ada programs to interface with
7624 programs written in that language.
7628 @cindex Decimal radix support
7629 @unnumberedsec F.1(2): Decimal Radix Support
7632 Packed decimal should be used as the internal representation for objects
7633 of subtype @var{S} when @var{S}'Machine_Radix = 10.
7635 Not followed. GNAT ignores @var{S}'Machine_Radix and always uses binary
7639 @unnumberedsec G: Numerics
7642 If Fortran (respectively, C) is widely supported in the target
7643 environment, implementations supporting the Numerics Annex
7644 should provide the child package @code{Interfaces.Fortran} (respectively,
7645 @code{Interfaces.C}) specified in Annex B and should support a
7646 @code{convention_identifier} of Fortran (respectively, C) in the interfacing
7647 pragmas (see Annex B), thus allowing Ada programs to interface with
7648 programs written in that language.
7652 @cindex Complex types
7653 @unnumberedsec G.1.1(56-58): Complex Types
7656 Because the usual mathematical meaning of multiplication of a complex
7657 operand and a real operand is that of the scaling of both components of
7658 the former by the latter, an implementation should not perform this
7659 operation by first promoting the real operand to complex type and then
7660 performing a full complex multiplication. In systems that, in the
7661 future, support an Ada binding to IEC 559:1989, the latter technique
7662 will not generate the required result when one of the components of the
7663 complex operand is infinite. (Explicit multiplication of the infinite
7664 component by the zero component obtained during promotion yields a NaN
7665 that propagates into the final result.) Analogous advice applies in the
7666 case of multiplication of a complex operand and a pure-imaginary
7667 operand, and in the case of division of a complex operand by a real or
7668 pure-imaginary operand.
7674 Similarly, because the usual mathematical meaning of addition of a
7675 complex operand and a real operand is that the imaginary operand remains
7676 unchanged, an implementation should not perform this operation by first
7677 promoting the real operand to complex type and then performing a full
7678 complex addition. In implementations in which the @code{Signed_Zeros}
7679 attribute of the component type is @code{True} (and which therefore
7680 conform to IEC 559:1989 in regard to the handling of the sign of zero in
7681 predefined arithmetic operations), the latter technique will not
7682 generate the required result when the imaginary component of the complex
7683 operand is a negatively signed zero. (Explicit addition of the negative
7684 zero to the zero obtained during promotion yields a positive zero.)
7685 Analogous advice applies in the case of addition of a complex operand
7686 and a pure-imaginary operand, and in the case of subtraction of a
7687 complex operand and a real or pure-imaginary operand.
7693 Implementations in which @code{Real'Signed_Zeros} is @code{True} should
7694 attempt to provide a rational treatment of the signs of zero results and
7695 result components. As one example, the result of the @code{Argument}
7696 function should have the sign of the imaginary component of the
7697 parameter @code{X} when the point represented by that parameter lies on
7698 the positive real axis; as another, the sign of the imaginary component
7699 of the @code{Compose_From_Polar} function should be the same as
7700 (respectively, the opposite of) that of the @code{Argument} parameter when that
7701 parameter has a value of zero and the @code{Modulus} parameter has a
7702 nonnegative (respectively, negative) value.
7706 @cindex Complex elementary functions
7707 @unnumberedsec G.1.2(49): Complex Elementary Functions
7710 Implementations in which @code{Complex_Types.Real'Signed_Zeros} is
7711 @code{True} should attempt to provide a rational treatment of the signs
7712 of zero results and result components. For example, many of the complex
7713 elementary functions have components that are odd functions of one of
7714 the parameter components; in these cases, the result component should
7715 have the sign of the parameter component at the origin. Other complex
7716 elementary functions have zero components whose sign is opposite that of
7717 a parameter component at the origin, or is always positive or always
7722 @cindex Accuracy requirements
7723 @unnumberedsec G.2.4(19): Accuracy Requirements
7726 The versions of the forward trigonometric functions without a
7727 @code{Cycle} parameter should not be implemented by calling the
7728 corresponding version with a @code{Cycle} parameter of
7729 @code{2.0*Numerics.Pi}, since this will not provide the required
7730 accuracy in some portions of the domain. For the same reason, the
7731 version of @code{Log} without a @code{Base} parameter should not be
7732 implemented by calling the corresponding version with a @code{Base}
7733 parameter of @code{Numerics.e}.
7737 @cindex Complex arithmetic accuracy
7738 @cindex Accuracy, complex arithmetic
7739 @unnumberedsec G.2.6(15): Complex Arithmetic Accuracy
7743 The version of the @code{Compose_From_Polar} function without a
7744 @code{Cycle} parameter should not be implemented by calling the
7745 corresponding version with a @code{Cycle} parameter of
7746 @code{2.0*Numerics.Pi}, since this will not provide the required
7747 accuracy in some portions of the domain.
7751 @c -----------------------------------------
7752 @node Implementation Defined Characteristics
7753 @chapter Implementation Defined Characteristics
7756 In addition to the implementation dependent pragmas and attributes, and
7757 the implementation advice, there are a number of other Ada features
7758 that are potentially implementation dependent. These are mentioned
7759 throughout the Ada Reference Manual, and are summarized in Annex M@.
7761 A requirement for conforming Ada compilers is that they provide
7762 documentation describing how the implementation deals with each of these
7763 issues. In this chapter, you will find each point in Annex M listed
7764 followed by a description in italic font of how GNAT
7768 implementation on IRIX 5.3 operating system or greater
7770 handles the implementation dependence.
7772 You can use this chapter as a guide to minimizing implementation
7773 dependent features in your programs if portability to other compilers
7774 and other operating systems is an important consideration. The numbers
7775 in each section below correspond to the paragraph number in the Ada
7781 @strong{2}. Whether or not each recommendation given in Implementation
7782 Advice is followed. See 1.1.2(37).
7785 @xref{Implementation Advice}.
7790 @strong{3}. Capacity limitations of the implementation. See 1.1.3(3).
7793 The complexity of programs that can be processed is limited only by the
7794 total amount of available virtual memory, and disk space for the
7795 generated object files.
7800 @strong{4}. Variations from the standard that are impractical to avoid
7801 given the implementation's execution environment. See 1.1.3(6).
7804 There are no variations from the standard.
7809 @strong{5}. Which @code{code_statement}s cause external
7810 interactions. See 1.1.3(10).
7813 Any @code{code_statement} can potentially cause external interactions.
7818 @strong{6}. The coded representation for the text of an Ada
7819 program. See 2.1(4).
7822 See separate section on source representation.
7827 @strong{7}. The control functions allowed in comments. See 2.1(14).
7830 See separate section on source representation.
7835 @strong{8}. The representation for an end of line. See 2.2(2).
7838 See separate section on source representation.
7843 @strong{9}. Maximum supported line length and lexical element
7844 length. See 2.2(15).
7847 The maximum line length is 255 characters and the maximum length of a
7848 lexical element is also 255 characters.
7853 @strong{10}. Implementation defined pragmas. See 2.8(14).
7857 @xref{Implementation Defined Pragmas}.
7862 @strong{11}. Effect of pragma @code{Optimize}. See 2.8(27).
7865 Pragma @code{Optimize}, if given with a @code{Time} or @code{Space}
7866 parameter, checks that the optimization flag is set, and aborts if it is
7872 @strong{12}. The sequence of characters of the value returned by
7873 @code{@var{S}'Image} when some of the graphic characters of
7874 @code{@var{S}'Wide_Image} are not defined in @code{Character}. See
7878 The sequence of characters is as defined by the wide character encoding
7879 method used for the source. See section on source representation for
7885 @strong{13}. The predefined integer types declared in
7886 @code{Standard}. See 3.5.4(25).
7890 @item Short_Short_Integer
7893 (Short) 16 bit signed
7897 64 bit signed (Alpha OpenVMS only)
7898 32 bit signed (all other targets)
7899 @item Long_Long_Integer
7906 @strong{14}. Any nonstandard integer types and the operators defined
7907 for them. See 3.5.4(26).
7910 There are no nonstandard integer types.
7915 @strong{15}. Any nonstandard real types and the operators defined for
7919 There are no nonstandard real types.
7924 @strong{16}. What combinations of requested decimal precision and range
7925 are supported for floating point types. See 3.5.7(7).
7928 The precision and range is as defined by the IEEE standard.
7933 @strong{17}. The predefined floating point types declared in
7934 @code{Standard}. See 3.5.7(16).
7941 (Short) 32 bit IEEE short
7944 @item Long_Long_Float
7945 64 bit IEEE long (80 bit IEEE long on x86 processors)
7951 @strong{18}. The small of an ordinary fixed point type. See 3.5.9(8).
7954 @code{Fine_Delta} is 2**(@minus{}63)
7959 @strong{19}. What combinations of small, range, and digits are
7960 supported for fixed point types. See 3.5.9(10).
7963 Any combinations are permitted that do not result in a small less than
7964 @code{Fine_Delta} and do not result in a mantissa larger than 63 bits.
7965 If the mantissa is larger than 53 bits on machines where Long_Long_Float
7966 is 64 bits (true of all architectures except ia32), then the output from
7967 Text_IO is accurate to only 53 bits, rather than the full mantissa. This
7968 is because floating-point conversions are used to convert fixed point.
7973 @strong{20}. The result of @code{Tags.Expanded_Name} for types declared
7974 within an unnamed @code{block_statement}. See 3.9(10).
7977 Block numbers of the form @code{B@var{nnn}}, where @var{nnn} is a
7978 decimal integer are allocated.
7983 @strong{21}. Implementation-defined attributes. See 4.1.4(12).
7986 @xref{Implementation Defined Attributes}.
7991 @strong{22}. Any implementation-defined time types. See 9.6(6).
7994 There are no implementation-defined time types.
7999 @strong{23}. The time base associated with relative delays.
8002 See 9.6(20). The time base used is that provided by the C library
8003 function @code{gettimeofday}.
8008 @strong{24}. The time base of the type @code{Calendar.Time}. See
8012 The time base used is that provided by the C library function
8013 @code{gettimeofday}.
8018 @strong{25}. The time zone used for package @code{Calendar}
8019 operations. See 9.6(24).
8022 The time zone used by package @code{Calendar} is the current system time zone
8023 setting for local time, as accessed by the C library function
8029 @strong{26}. Any limit on @code{delay_until_statements} of
8030 @code{select_statements}. See 9.6(29).
8033 There are no such limits.
8038 @strong{27}. Whether or not two non-overlapping parts of a composite
8039 object are independently addressable, in the case where packing, record
8040 layout, or @code{Component_Size} is specified for the object. See
8044 Separate components are independently addressable if they do not share
8045 overlapping storage units.
8050 @strong{28}. The representation for a compilation. See 10.1(2).
8053 A compilation is represented by a sequence of files presented to the
8054 compiler in a single invocation of the @command{gcc} command.
8059 @strong{29}. Any restrictions on compilations that contain multiple
8060 compilation_units. See 10.1(4).
8063 No single file can contain more than one compilation unit, but any
8064 sequence of files can be presented to the compiler as a single
8070 @strong{30}. The mechanisms for creating an environment and for adding
8071 and replacing compilation units. See 10.1.4(3).
8074 See separate section on compilation model.
8079 @strong{31}. The manner of explicitly assigning library units to a
8080 partition. See 10.2(2).
8083 If a unit contains an Ada main program, then the Ada units for the partition
8084 are determined by recursive application of the rules in the Ada Reference
8085 Manual section 10.2(2-6). In other words, the Ada units will be those that
8086 are needed by the main program, and then this definition of need is applied
8087 recursively to those units, and the partition contains the transitive
8088 closure determined by this relationship. In short, all the necessary units
8089 are included, with no need to explicitly specify the list. If additional
8090 units are required, e.g.@: by foreign language units, then all units must be
8091 mentioned in the context clause of one of the needed Ada units.
8093 If the partition contains no main program, or if the main program is in
8094 a language other than Ada, then GNAT
8095 provides the binder options @option{-z} and @option{-n} respectively, and in
8096 this case a list of units can be explicitly supplied to the binder for
8097 inclusion in the partition (all units needed by these units will also
8098 be included automatically). For full details on the use of these
8099 options, refer to @ref{The GNAT Make Program gnatmake,,, gnat_ugn,
8100 @value{EDITION} User's Guide}.
8105 @strong{32}. The implementation-defined means, if any, of specifying
8106 which compilation units are needed by a given compilation unit. See
8110 The units needed by a given compilation unit are as defined in
8111 the Ada Reference Manual section 10.2(2-6). There are no
8112 implementation-defined pragmas or other implementation-defined
8113 means for specifying needed units.
8118 @strong{33}. The manner of designating the main subprogram of a
8119 partition. See 10.2(7).
8122 The main program is designated by providing the name of the
8123 corresponding @file{ALI} file as the input parameter to the binder.
8128 @strong{34}. The order of elaboration of @code{library_items}. See
8132 The first constraint on ordering is that it meets the requirements of
8133 Chapter 10 of the Ada Reference Manual. This still leaves some
8134 implementation dependent choices, which are resolved by first
8135 elaborating bodies as early as possible (i.e., in preference to specs
8136 where there is a choice), and second by evaluating the immediate with
8137 clauses of a unit to determine the probably best choice, and
8138 third by elaborating in alphabetical order of unit names
8139 where a choice still remains.
8144 @strong{35}. Parameter passing and function return for the main
8145 subprogram. See 10.2(21).
8148 The main program has no parameters. It may be a procedure, or a function
8149 returning an integer type. In the latter case, the returned integer
8150 value is the return code of the program (overriding any value that
8151 may have been set by a call to @code{Ada.Command_Line.Set_Exit_Status}).
8156 @strong{36}. The mechanisms for building and running partitions. See
8160 GNAT itself supports programs with only a single partition. The GNATDIST
8161 tool provided with the GLADE package (which also includes an implementation
8162 of the PCS) provides a completely flexible method for building and running
8163 programs consisting of multiple partitions. See the separate GLADE manual
8169 @strong{37}. The details of program execution, including program
8170 termination. See 10.2(25).
8173 See separate section on compilation model.
8178 @strong{38}. The semantics of any non-active partitions supported by the
8179 implementation. See 10.2(28).
8182 Passive partitions are supported on targets where shared memory is
8183 provided by the operating system. See the GLADE reference manual for
8189 @strong{39}. The information returned by @code{Exception_Message}. See
8193 Exception message returns the null string unless a specific message has
8194 been passed by the program.
8199 @strong{40}. The result of @code{Exceptions.Exception_Name} for types
8200 declared within an unnamed @code{block_statement}. See 11.4.1(12).
8203 Blocks have implementation defined names of the form @code{B@var{nnn}}
8204 where @var{nnn} is an integer.
8209 @strong{41}. The information returned by
8210 @code{Exception_Information}. See 11.4.1(13).
8213 @code{Exception_Information} returns a string in the following format:
8216 @emph{Exception_Name:} nnnnn
8217 @emph{Message:} mmmmm
8219 @emph{Call stack traceback locations:}
8220 0xhhhh 0xhhhh 0xhhhh ... 0xhhh
8228 @code{nnnn} is the fully qualified name of the exception in all upper
8229 case letters. This line is always present.
8232 @code{mmmm} is the message (this line present only if message is non-null)
8235 @code{ppp} is the Process Id value as a decimal integer (this line is
8236 present only if the Process Id is nonzero). Currently we are
8237 not making use of this field.
8240 The Call stack traceback locations line and the following values
8241 are present only if at least one traceback location was recorded.
8242 The values are given in C style format, with lower case letters
8243 for a-f, and only as many digits present as are necessary.
8247 The line terminator sequence at the end of each line, including
8248 the last line is a single @code{LF} character (@code{16#0A#}).
8253 @strong{42}. Implementation-defined check names. See 11.5(27).
8256 The implementation defined check name Alignment_Check controls checking of
8257 address clause values for proper alignment (that is, the address supplied
8258 must be consistent with the alignment of the type).
8260 In addition, a user program can add implementation-defined check names
8261 by means of the pragma Check_Name.
8266 @strong{43}. The interpretation of each aspect of representation. See
8270 See separate section on data representations.
8275 @strong{44}. Any restrictions placed upon representation items. See
8279 See separate section on data representations.
8284 @strong{45}. The meaning of @code{Size} for indefinite subtypes. See
8288 Size for an indefinite subtype is the maximum possible size, except that
8289 for the case of a subprogram parameter, the size of the parameter object
8295 @strong{46}. The default external representation for a type tag. See
8299 The default external representation for a type tag is the fully expanded
8300 name of the type in upper case letters.
8305 @strong{47}. What determines whether a compilation unit is the same in
8306 two different partitions. See 13.3(76).
8309 A compilation unit is the same in two different partitions if and only
8310 if it derives from the same source file.
8315 @strong{48}. Implementation-defined components. See 13.5.1(15).
8318 The only implementation defined component is the tag for a tagged type,
8319 which contains a pointer to the dispatching table.
8324 @strong{49}. If @code{Word_Size} = @code{Storage_Unit}, the default bit
8325 ordering. See 13.5.3(5).
8328 @code{Word_Size} (32) is not the same as @code{Storage_Unit} (8) for this
8329 implementation, so no non-default bit ordering is supported. The default
8330 bit ordering corresponds to the natural endianness of the target architecture.
8335 @strong{50}. The contents of the visible part of package @code{System}
8336 and its language-defined children. See 13.7(2).
8339 See the definition of these packages in files @file{system.ads} and
8340 @file{s-stoele.ads}.
8345 @strong{51}. The contents of the visible part of package
8346 @code{System.Machine_Code}, and the meaning of
8347 @code{code_statements}. See 13.8(7).
8350 See the definition and documentation in file @file{s-maccod.ads}.
8355 @strong{52}. The effect of unchecked conversion. See 13.9(11).
8358 Unchecked conversion between types of the same size
8359 results in an uninterpreted transmission of the bits from one type
8360 to the other. If the types are of unequal sizes, then in the case of
8361 discrete types, a shorter source is first zero or sign extended as
8362 necessary, and a shorter target is simply truncated on the left.
8363 For all non-discrete types, the source is first copied if necessary
8364 to ensure that the alignment requirements of the target are met, then
8365 a pointer is constructed to the source value, and the result is obtained
8366 by dereferencing this pointer after converting it to be a pointer to the
8367 target type. Unchecked conversions where the target subtype is an
8368 unconstrained array are not permitted. If the target alignment is
8369 greater than the source alignment, then a copy of the result is
8370 made with appropriate alignment
8375 @strong{53}. The manner of choosing a storage pool for an access type
8376 when @code{Storage_Pool} is not specified for the type. See 13.11(17).
8379 There are 3 different standard pools used by the compiler when
8380 @code{Storage_Pool} is not specified depending whether the type is local
8381 to a subprogram or defined at the library level and whether
8382 @code{Storage_Size}is specified or not. See documentation in the runtime
8383 library units @code{System.Pool_Global}, @code{System.Pool_Size} and
8384 @code{System.Pool_Local} in files @file{s-poosiz.ads},
8385 @file{s-pooglo.ads} and @file{s-pooloc.ads} for full details on the
8391 @strong{54}. Whether or not the implementation provides user-accessible
8392 names for the standard pool type(s). See 13.11(17).
8396 See documentation in the sources of the run time mentioned in paragraph
8397 @strong{53} . All these pools are accessible by means of @code{with}'ing
8403 @strong{55}. The meaning of @code{Storage_Size}. See 13.11(18).
8406 @code{Storage_Size} is measured in storage units, and refers to the
8407 total space available for an access type collection, or to the primary
8408 stack space for a task.
8413 @strong{56}. Implementation-defined aspects of storage pools. See
8417 See documentation in the sources of the run time mentioned in paragraph
8418 @strong{53} for details on GNAT-defined aspects of storage pools.
8423 @strong{57}. The set of restrictions allowed in a pragma
8424 @code{Restrictions}. See 13.12(7).
8427 All RM defined Restriction identifiers are implemented. The following
8428 additional restriction identifiers are provided. There are two separate
8429 lists of implementation dependent restriction identifiers. The first
8430 set requires consistency throughout a partition (in other words, if the
8431 restriction identifier is used for any compilation unit in the partition,
8432 then all compilation units in the partition must obey the restriction.
8436 @item Simple_Barriers
8437 @findex Simple_Barriers
8438 This restriction ensures at compile time that barriers in entry declarations
8439 for protected types are restricted to either static boolean expressions or
8440 references to simple boolean variables defined in the private part of the
8441 protected type. No other form of entry barriers is permitted. This is one
8442 of the restrictions of the Ravenscar profile for limited tasking (see also
8443 pragma @code{Profile (Ravenscar)}).
8445 @item Max_Entry_Queue_Length => Expr
8446 @findex Max_Entry_Queue_Length
8447 This restriction is a declaration that any protected entry compiled in
8448 the scope of the restriction has at most the specified number of
8449 tasks waiting on the entry
8450 at any one time, and so no queue is required. This restriction is not
8451 checked at compile time. A program execution is erroneous if an attempt
8452 is made to queue more than the specified number of tasks on such an entry.
8456 This restriction ensures at compile time that there is no implicit or
8457 explicit dependence on the package @code{Ada.Calendar}.
8459 @item No_Default_Initialization
8460 @findex No_Default_Initialization
8462 This restriction prohibits any instance of default initialization of variables.
8463 The binder implements a consistency rule which prevents any unit compiled
8464 without the restriction from with'ing a unit with the restriction (this allows
8465 the generation of initialization procedures to be skipped, since you can be
8466 sure that no call is ever generated to an initialization procedure in a unit
8467 with the restriction active). If used in conjunction with Initialize_Scalars or
8468 Normalize_Scalars, the effect is to prohibit all cases of variables declared
8469 without a specific initializer (including the case of OUT scalar parameters).
8471 @item No_Direct_Boolean_Operators
8472 @findex No_Direct_Boolean_Operators
8473 This restriction ensures that no logical (and/or/xor) are used on
8474 operands of type Boolean (or any type derived
8475 from Boolean). This is intended for use in safety critical programs
8476 where the certification protocol requires the use of short-circuit
8477 (and then, or else) forms for all composite boolean operations.
8479 @item No_Dispatching_Calls
8480 @findex No_Dispatching_Calls
8481 This restriction ensures at compile time that the code generated by the
8482 compiler involves no dispatching calls. The use of this restriction allows the
8483 safe use of record extensions, classwide membership tests and other classwide
8484 features not involving implicit dispatching. This restriction ensures that
8485 the code contains no indirect calls through a dispatching mechanism. Note that
8486 this includes internally-generated calls created by the compiler, for example
8487 in the implementation of class-wide objects assignments. The
8488 membership test is allowed in the presence of this restriction, because its
8489 implementation requires no dispatching.
8490 This restriction is comparable to the official Ada restriction
8491 @code{No_Dispatch} except that it is a bit less restrictive in that it allows
8492 all classwide constructs that do not imply dispatching.
8493 The following example indicates constructs that violate this restriction.
8497 type T is tagged record
8500 procedure P (X : T);
8502 type DT is new T with record
8503 More_Data : Natural;
8505 procedure Q (X : DT);
8509 procedure Example is
8510 procedure Test (O : T'Class) is
8511 N : Natural := O'Size;-- Error: Dispatching call
8512 C : T'Class := O; -- Error: implicit Dispatching Call
8514 if O in DT'Class then -- OK : Membership test
8515 Q (DT (O)); -- OK : Type conversion plus direct call
8517 P (O); -- Error: Dispatching call
8523 P (Obj); -- OK : Direct call
8524 P (T (Obj)); -- OK : Type conversion plus direct call
8525 P (T'Class (Obj)); -- Error: Dispatching call
8527 Test (Obj); -- OK : Type conversion
8529 if Obj in T'Class then -- OK : Membership test
8535 @item No_Dynamic_Attachment
8536 @findex No_Dynamic_Attachment
8537 This restriction ensures that there is no call to any of the operations
8538 defined in package Ada.Interrupts.
8540 @item No_Enumeration_Maps
8541 @findex No_Enumeration_Maps
8542 This restriction ensures at compile time that no operations requiring
8543 enumeration maps are used (that is Image and Value attributes applied
8544 to enumeration types).
8546 @item No_Entry_Calls_In_Elaboration_Code
8547 @findex No_Entry_Calls_In_Elaboration_Code
8548 This restriction ensures at compile time that no task or protected entry
8549 calls are made during elaboration code. As a result of the use of this
8550 restriction, the compiler can assume that no code past an accept statement
8551 in a task can be executed at elaboration time.
8553 @item No_Exception_Handlers
8554 @findex No_Exception_Handlers
8555 This restriction ensures at compile time that there are no explicit
8556 exception handlers. It also indicates that no exception propagation will
8557 be provided. In this mode, exceptions may be raised but will result in
8558 an immediate call to the last chance handler, a routine that the user
8559 must define with the following profile:
8561 @smallexample @c ada
8562 procedure Last_Chance_Handler
8563 (Source_Location : System.Address; Line : Integer);
8564 pragma Export (C, Last_Chance_Handler,
8565 "__gnat_last_chance_handler");
8568 The parameter is a C null-terminated string representing a message to be
8569 associated with the exception (typically the source location of the raise
8570 statement generated by the compiler). The Line parameter when nonzero
8571 represents the line number in the source program where the raise occurs.
8573 @item No_Exception_Propagation
8574 @findex No_Exception_Propagation
8575 This restriction guarantees that exceptions are never propagated to an outer
8576 subprogram scope). The only case in which an exception may be raised is when
8577 the handler is statically in the same subprogram, so that the effect of a raise
8578 is essentially like a goto statement. Any other raise statement (implicit or
8579 explicit) will be considered unhandled. Exception handlers are allowed, but may
8580 not contain an exception occurrence identifier (exception choice). In addition
8581 use of the package GNAT.Current_Exception is not permitted, and reraise
8582 statements (raise with no operand) are not permitted.
8584 @item No_Exception_Registration
8585 @findex No_Exception_Registration
8586 This restriction ensures at compile time that no stream operations for
8587 types Exception_Id or Exception_Occurrence are used. This also makes it
8588 impossible to pass exceptions to or from a partition with this restriction
8589 in a distributed environment. If this exception is active, then the generated
8590 code is simplified by omitting the otherwise-required global registration
8591 of exceptions when they are declared.
8593 @item No_Implicit_Conditionals
8594 @findex No_Implicit_Conditionals
8595 This restriction ensures that the generated code does not contain any
8596 implicit conditionals, either by modifying the generated code where possible,
8597 or by rejecting any construct that would otherwise generate an implicit
8598 conditional. Note that this check does not include run time constraint
8599 checks, which on some targets may generate implicit conditionals as
8600 well. To control the latter, constraint checks can be suppressed in the
8601 normal manner. Constructs generating implicit conditionals include comparisons
8602 of composite objects and the Max/Min attributes.
8604 @item No_Implicit_Dynamic_Code
8605 @findex No_Implicit_Dynamic_Code
8607 This restriction prevents the compiler from building ``trampolines''.
8608 This is a structure that is built on the stack and contains dynamic
8609 code to be executed at run time. On some targets, a trampoline is
8610 built for the following features: @code{Access},
8611 @code{Unrestricted_Access}, or @code{Address} of a nested subprogram;
8612 nested task bodies; primitive operations of nested tagged types.
8613 Trampolines do not work on machines that prevent execution of stack
8614 data. For example, on windows systems, enabling DEP (data execution
8615 protection) will cause trampolines to raise an exception.
8616 Trampolines are also quite slow at run time.
8618 On many targets, trampolines have been largely eliminated. Look at the
8619 version of system.ads for your target --- if it has
8620 Always_Compatible_Rep equal to False, then trampolines are largely
8621 eliminated. In particular, a trampoline is built for the following
8622 features: @code{Address} of a nested subprogram;
8623 @code{Access} or @code{Unrestricted_Access} of a nested subprogram,
8624 but only if pragma Favor_Top_Level applies, or the access type has a
8625 foreign-language convention; primitive operations of nested tagged
8628 @item No_Implicit_Loops
8629 @findex No_Implicit_Loops
8630 This restriction ensures that the generated code does not contain any
8631 implicit @code{for} loops, either by modifying
8632 the generated code where possible,
8633 or by rejecting any construct that would otherwise generate an implicit
8634 @code{for} loop. If this restriction is active, it is possible to build
8635 large array aggregates with all static components without generating an
8636 intermediate temporary, and without generating a loop to initialize individual
8637 components. Otherwise, a loop is created for arrays larger than about 5000
8640 @item No_Initialize_Scalars
8641 @findex No_Initialize_Scalars
8642 This restriction ensures that no unit in the partition is compiled with
8643 pragma Initialize_Scalars. This allows the generation of more efficient
8644 code, and in particular eliminates dummy null initialization routines that
8645 are otherwise generated for some record and array types.
8647 @item No_Local_Protected_Objects
8648 @findex No_Local_Protected_Objects
8649 This restriction ensures at compile time that protected objects are
8650 only declared at the library level.
8652 @item No_Protected_Type_Allocators
8653 @findex No_Protected_Type_Allocators
8654 This restriction ensures at compile time that there are no allocator
8655 expressions that attempt to allocate protected objects.
8657 @item No_Secondary_Stack
8658 @findex No_Secondary_Stack
8659 This restriction ensures at compile time that the generated code does not
8660 contain any reference to the secondary stack. The secondary stack is used
8661 to implement functions returning unconstrained objects (arrays or records)
8664 @item No_Select_Statements
8665 @findex No_Select_Statements
8666 This restriction ensures at compile time no select statements of any kind
8667 are permitted, that is the keyword @code{select} may not appear.
8668 This is one of the restrictions of the Ravenscar
8669 profile for limited tasking (see also pragma @code{Profile (Ravenscar)}).
8671 @item No_Standard_Storage_Pools
8672 @findex No_Standard_Storage_Pools
8673 This restriction ensures at compile time that no access types
8674 use the standard default storage pool. Any access type declared must
8675 have an explicit Storage_Pool attribute defined specifying a
8676 user-defined storage pool.
8680 This restriction ensures at compile/bind time that there are no
8681 stream objects created and no use of stream attributes.
8682 This restriction does not forbid dependences on the package
8683 @code{Ada.Streams}. So it is permissible to with
8684 @code{Ada.Streams} (or another package that does so itself)
8685 as long as no actual stream objects are created and no
8686 stream attributes are used.
8688 Note that the use of restriction allows optimization of tagged types,
8689 since they do not need to worry about dispatching stream operations.
8690 To take maximum advantage of this space-saving optimization, any
8691 unit declaring a tagged type should be compiled with the restriction,
8692 though this is not required.
8694 @item No_Task_Attributes_Package
8695 @findex No_Task_Attributes_Package
8696 This restriction ensures at compile time that there are no implicit or
8697 explicit dependencies on the package @code{Ada.Task_Attributes}.
8699 @item No_Task_Termination
8700 @findex No_Task_Termination
8701 This restriction ensures at compile time that no terminate alternatives
8702 appear in any task body.
8706 This restriction prevents the declaration of tasks or task types throughout
8707 the partition. It is similar in effect to the use of @code{Max_Tasks => 0}
8708 except that violations are caught at compile time and cause an error message
8709 to be output either by the compiler or binder.
8711 @item Static_Priorities
8712 @findex Static_Priorities
8713 This restriction ensures at compile time that all priority expressions
8714 are static, and that there are no dependencies on the package
8715 @code{Ada.Dynamic_Priorities}.
8717 @item Static_Storage_Size
8718 @findex Static_Storage_Size
8719 This restriction ensures at compile time that any expression appearing
8720 in a Storage_Size pragma or attribute definition clause is static.
8725 The second set of implementation dependent restriction identifiers
8726 does not require partition-wide consistency.
8727 The restriction may be enforced for a single
8728 compilation unit without any effect on any of the
8729 other compilation units in the partition.
8733 @item No_Elaboration_Code
8734 @findex No_Elaboration_Code
8735 This restriction ensures at compile time that no elaboration code is
8736 generated. Note that this is not the same condition as is enforced
8737 by pragma @code{Preelaborate}. There are cases in which pragma
8738 @code{Preelaborate} still permits code to be generated (e.g.@: code
8739 to initialize a large array to all zeroes), and there are cases of units
8740 which do not meet the requirements for pragma @code{Preelaborate},
8741 but for which no elaboration code is generated. Generally, it is
8742 the case that preelaborable units will meet the restrictions, with
8743 the exception of large aggregates initialized with an others_clause,
8744 and exception declarations (which generate calls to a run-time
8745 registry procedure). This restriction is enforced on
8746 a unit by unit basis, it need not be obeyed consistently
8747 throughout a partition.
8749 In the case of aggregates with others, if the aggregate has a dynamic
8750 size, there is no way to eliminate the elaboration code (such dynamic
8751 bounds would be incompatible with @code{Preelaborate} in any case). If
8752 the bounds are static, then use of this restriction actually modifies
8753 the code choice of the compiler to avoid generating a loop, and instead
8754 generate the aggregate statically if possible, no matter how many times
8755 the data for the others clause must be repeatedly generated.
8757 It is not possible to precisely document
8758 the constructs which are compatible with this restriction, since,
8759 unlike most other restrictions, this is not a restriction on the
8760 source code, but a restriction on the generated object code. For
8761 example, if the source contains a declaration:
8764 Val : constant Integer := X;
8768 where X is not a static constant, it may be possible, depending
8769 on complex optimization circuitry, for the compiler to figure
8770 out the value of X at compile time, in which case this initialization
8771 can be done by the loader, and requires no initialization code. It
8772 is not possible to document the precise conditions under which the
8773 optimizer can figure this out.
8775 Note that this the implementation of this restriction requires full
8776 code generation. If it is used in conjunction with "semantics only"
8777 checking, then some cases of violations may be missed.
8779 @item No_Entry_Queue
8780 @findex No_Entry_Queue
8781 This restriction is a declaration that any protected entry compiled in
8782 the scope of the restriction has at most one task waiting on the entry
8783 at any one time, and so no queue is required. This restriction is not
8784 checked at compile time. A program execution is erroneous if an attempt
8785 is made to queue a second task on such an entry.
8787 @item No_Implementation_Attributes
8788 @findex No_Implementation_Attributes
8789 This restriction checks at compile time that no GNAT-defined attributes
8790 are present. With this restriction, the only attributes that can be used
8791 are those defined in the Ada Reference Manual.
8793 @item No_Implementation_Pragmas
8794 @findex No_Implementation_Pragmas
8795 This restriction checks at compile time that no GNAT-defined pragmas
8796 are present. With this restriction, the only pragmas that can be used
8797 are those defined in the Ada Reference Manual.
8799 @item No_Implementation_Restrictions
8800 @findex No_Implementation_Restrictions
8801 This restriction checks at compile time that no GNAT-defined restriction
8802 identifiers (other than @code{No_Implementation_Restrictions} itself)
8803 are present. With this restriction, the only other restriction identifiers
8804 that can be used are those defined in the Ada Reference Manual.
8806 @item No_Wide_Characters
8807 @findex No_Wide_Characters
8808 This restriction ensures at compile time that no uses of the types
8809 @code{Wide_Character} or @code{Wide_String} or corresponding wide
8811 appear, and that no wide or wide wide string or character literals
8812 appear in the program (that is literals representing characters not in
8813 type @code{Character}.
8820 @strong{58}. The consequences of violating limitations on
8821 @code{Restrictions} pragmas. See 13.12(9).
8824 Restrictions that can be checked at compile time result in illegalities
8825 if violated. Currently there are no other consequences of violating
8831 @strong{59}. The representation used by the @code{Read} and
8832 @code{Write} attributes of elementary types in terms of stream
8833 elements. See 13.13.2(9).
8836 The representation is the in-memory representation of the base type of
8837 the type, using the number of bits corresponding to the
8838 @code{@var{type}'Size} value, and the natural ordering of the machine.
8843 @strong{60}. The names and characteristics of the numeric subtypes
8844 declared in the visible part of package @code{Standard}. See A.1(3).
8847 See items describing the integer and floating-point types supported.
8852 @strong{61}. The accuracy actually achieved by the elementary
8853 functions. See A.5.1(1).
8856 The elementary functions correspond to the functions available in the C
8857 library. Only fast math mode is implemented.
8862 @strong{62}. The sign of a zero result from some of the operators or
8863 functions in @code{Numerics.Generic_Elementary_Functions}, when
8864 @code{Float_Type'Signed_Zeros} is @code{True}. See A.5.1(46).
8867 The sign of zeroes follows the requirements of the IEEE 754 standard on
8873 @strong{63}. The value of
8874 @code{Numerics.Float_Random.Max_Image_Width}. See A.5.2(27).
8877 Maximum image width is 649, see library file @file{a-numran.ads}.
8882 @strong{64}. The value of
8883 @code{Numerics.Discrete_Random.Max_Image_Width}. See A.5.2(27).
8886 Maximum image width is 80, see library file @file{a-nudira.ads}.
8891 @strong{65}. The algorithms for random number generation. See
8895 The algorithm is documented in the source files @file{a-numran.ads} and
8896 @file{a-numran.adb}.
8901 @strong{66}. The string representation of a random number generator's
8902 state. See A.5.2(38).
8905 See the documentation contained in the file @file{a-numran.adb}.
8910 @strong{67}. The minimum time interval between calls to the
8911 time-dependent Reset procedure that are guaranteed to initiate different
8912 random number sequences. See A.5.2(45).
8915 The minimum period between reset calls to guarantee distinct series of
8916 random numbers is one microsecond.
8921 @strong{68}. The values of the @code{Model_Mantissa},
8922 @code{Model_Emin}, @code{Model_Epsilon}, @code{Model},
8923 @code{Safe_First}, and @code{Safe_Last} attributes, if the Numerics
8924 Annex is not supported. See A.5.3(72).
8927 See the source file @file{ttypef.ads} for the values of all numeric
8933 @strong{69}. Any implementation-defined characteristics of the
8934 input-output packages. See A.7(14).
8937 There are no special implementation defined characteristics for these
8943 @strong{70}. The value of @code{Buffer_Size} in @code{Storage_IO}. See
8947 All type representations are contiguous, and the @code{Buffer_Size} is
8948 the value of @code{@var{type}'Size} rounded up to the next storage unit
8954 @strong{71}. External files for standard input, standard output, and
8955 standard error See A.10(5).
8958 These files are mapped onto the files provided by the C streams
8959 libraries. See source file @file{i-cstrea.ads} for further details.
8964 @strong{72}. The accuracy of the value produced by @code{Put}. See
8968 If more digits are requested in the output than are represented by the
8969 precision of the value, zeroes are output in the corresponding least
8970 significant digit positions.
8975 @strong{73}. The meaning of @code{Argument_Count}, @code{Argument}, and
8976 @code{Command_Name}. See A.15(1).
8979 These are mapped onto the @code{argv} and @code{argc} parameters of the
8980 main program in the natural manner.
8985 @strong{74}. Implementation-defined convention names. See B.1(11).
8988 The following convention names are supported
8996 Synonym for Assembler
8998 Synonym for Assembler
9001 @item C_Pass_By_Copy
9002 Allowed only for record types, like C, but also notes that record
9003 is to be passed by copy rather than reference.
9006 @item C_Plus_Plus (or CPP)
9009 Treated the same as C
9011 Treated the same as C
9015 For support of pragma @code{Import} with convention Intrinsic, see
9016 separate section on Intrinsic Subprograms.
9018 Stdcall (used for Windows implementations only). This convention correspond
9019 to the WINAPI (previously called Pascal convention) C/C++ convention under
9020 Windows. A function with this convention cleans the stack before exit.
9026 Stubbed is a special convention used to indicate that the body of the
9027 subprogram will be entirely ignored. Any call to the subprogram
9028 is converted into a raise of the @code{Program_Error} exception. If a
9029 pragma @code{Import} specifies convention @code{stubbed} then no body need
9030 be present at all. This convention is useful during development for the
9031 inclusion of subprograms whose body has not yet been written.
9035 In addition, all otherwise unrecognized convention names are also
9036 treated as being synonymous with convention C@. In all implementations
9037 except for VMS, use of such other names results in a warning. In VMS
9038 implementations, these names are accepted silently.
9043 @strong{75}. The meaning of link names. See B.1(36).
9046 Link names are the actual names used by the linker.
9051 @strong{76}. The manner of choosing link names when neither the link
9052 name nor the address of an imported or exported entity is specified. See
9056 The default linker name is that which would be assigned by the relevant
9057 external language, interpreting the Ada name as being in all lower case
9063 @strong{77}. The effect of pragma @code{Linker_Options}. See B.1(37).
9066 The string passed to @code{Linker_Options} is presented uninterpreted as
9067 an argument to the link command, unless it contains ASCII.NUL characters.
9068 NUL characters if they appear act as argument separators, so for example
9070 @smallexample @c ada
9071 pragma Linker_Options ("-labc" & ASCII.NUL & "-ldef");
9075 causes two separate arguments @code{-labc} and @code{-ldef} to be passed to the
9076 linker. The order of linker options is preserved for a given unit. The final
9077 list of options passed to the linker is in reverse order of the elaboration
9078 order. For example, linker options for a body always appear before the options
9079 from the corresponding package spec.
9084 @strong{78}. The contents of the visible part of package
9085 @code{Interfaces} and its language-defined descendants. See B.2(1).
9088 See files with prefix @file{i-} in the distributed library.
9093 @strong{79}. Implementation-defined children of package
9094 @code{Interfaces}. The contents of the visible part of package
9095 @code{Interfaces}. See B.2(11).
9098 See files with prefix @file{i-} in the distributed library.
9103 @strong{80}. The types @code{Floating}, @code{Long_Floating},
9104 @code{Binary}, @code{Long_Binary}, @code{Decimal_ Element}, and
9105 @code{COBOL_Character}; and the initialization of the variables
9106 @code{Ada_To_COBOL} and @code{COBOL_To_Ada}, in
9107 @code{Interfaces.COBOL}. See B.4(50).
9114 (Floating) Long_Float
9119 @item Decimal_Element
9121 @item COBOL_Character
9126 For initialization, see the file @file{i-cobol.ads} in the distributed library.
9131 @strong{81}. Support for access to machine instructions. See C.1(1).
9134 See documentation in file @file{s-maccod.ads} in the distributed library.
9139 @strong{82}. Implementation-defined aspects of access to machine
9140 operations. See C.1(9).
9143 See documentation in file @file{s-maccod.ads} in the distributed library.
9148 @strong{83}. Implementation-defined aspects of interrupts. See C.3(2).
9151 Interrupts are mapped to signals or conditions as appropriate. See
9153 @code{Ada.Interrupt_Names} in source file @file{a-intnam.ads} for details
9154 on the interrupts supported on a particular target.
9159 @strong{84}. Implementation-defined aspects of pre-elaboration. See
9163 GNAT does not permit a partition to be restarted without reloading,
9164 except under control of the debugger.
9169 @strong{85}. The semantics of pragma @code{Discard_Names}. See C.5(7).
9172 Pragma @code{Discard_Names} causes names of enumeration literals to
9173 be suppressed. In the presence of this pragma, the Image attribute
9174 provides the image of the Pos of the literal, and Value accepts
9180 @strong{86}. The result of the @code{Task_Identification.Image}
9181 attribute. See C.7.1(7).
9184 The result of this attribute is a string that identifies
9185 the object or component that denotes a given task. If a variable @code{Var}
9186 has a task type, the image for this task will have the form @code{Var_@var{XXXXXXXX}},
9188 is the hexadecimal representation of the virtual address of the corresponding
9189 task control block. If the variable is an array of tasks, the image of each
9190 task will have the form of an indexed component indicating the position of a
9191 given task in the array, e.g.@: @code{Group(5)_@var{XXXXXXX}}. If the task is a
9192 component of a record, the image of the task will have the form of a selected
9193 component. These rules are fully recursive, so that the image of a task that
9194 is a subcomponent of a composite object corresponds to the expression that
9195 designates this task.
9197 If a task is created by an allocator, its image depends on the context. If the
9198 allocator is part of an object declaration, the rules described above are used
9199 to construct its image, and this image is not affected by subsequent
9200 assignments. If the allocator appears within an expression, the image
9201 includes only the name of the task type.
9203 If the configuration pragma Discard_Names is present, or if the restriction
9204 No_Implicit_Heap_Allocation is in effect, the image reduces to
9205 the numeric suffix, that is to say the hexadecimal representation of the
9206 virtual address of the control block of the task.
9210 @strong{87}. The value of @code{Current_Task} when in a protected entry
9211 or interrupt handler. See C.7.1(17).
9214 Protected entries or interrupt handlers can be executed by any
9215 convenient thread, so the value of @code{Current_Task} is undefined.
9220 @strong{88}. The effect of calling @code{Current_Task} from an entry
9221 body or interrupt handler. See C.7.1(19).
9224 The effect of calling @code{Current_Task} from an entry body or
9225 interrupt handler is to return the identification of the task currently
9231 @strong{89}. Implementation-defined aspects of
9232 @code{Task_Attributes}. See C.7.2(19).
9235 There are no implementation-defined aspects of @code{Task_Attributes}.
9240 @strong{90}. Values of all @code{Metrics}. See D(2).
9243 The metrics information for GNAT depends on the performance of the
9244 underlying operating system. The sources of the run-time for tasking
9245 implementation, together with the output from @option{-gnatG} can be
9246 used to determine the exact sequence of operating systems calls made
9247 to implement various tasking constructs. Together with appropriate
9248 information on the performance of the underlying operating system,
9249 on the exact target in use, this information can be used to determine
9250 the required metrics.
9255 @strong{91}. The declarations of @code{Any_Priority} and
9256 @code{Priority}. See D.1(11).
9259 See declarations in file @file{system.ads}.
9264 @strong{92}. Implementation-defined execution resources. See D.1(15).
9267 There are no implementation-defined execution resources.
9272 @strong{93}. Whether, on a multiprocessor, a task that is waiting for
9273 access to a protected object keeps its processor busy. See D.2.1(3).
9276 On a multi-processor, a task that is waiting for access to a protected
9277 object does not keep its processor busy.
9282 @strong{94}. The affect of implementation defined execution resources
9283 on task dispatching. See D.2.1(9).
9288 Tasks map to IRIX threads, and the dispatching policy is as defined by
9289 the IRIX implementation of threads.
9291 Tasks map to threads in the threads package used by GNAT@. Where possible
9292 and appropriate, these threads correspond to native threads of the
9293 underlying operating system.
9298 @strong{95}. Implementation-defined @code{policy_identifiers} allowed
9299 in a pragma @code{Task_Dispatching_Policy}. See D.2.2(3).
9302 There are no implementation-defined policy-identifiers allowed in this
9308 @strong{96}. Implementation-defined aspects of priority inversion. See
9312 Execution of a task cannot be preempted by the implementation processing
9313 of delay expirations for lower priority tasks.
9318 @strong{97}. Implementation defined task dispatching. See D.2.2(18).
9323 Tasks map to IRIX threads, and the dispatching policy is as defined by
9324 the IRIX implementation of threads.
9326 The policy is the same as that of the underlying threads implementation.
9331 @strong{98}. Implementation-defined @code{policy_identifiers} allowed
9332 in a pragma @code{Locking_Policy}. See D.3(4).
9335 The only implementation defined policy permitted in GNAT is
9336 @code{Inheritance_Locking}. On targets that support this policy, locking
9337 is implemented by inheritance, i.e.@: the task owning the lock operates
9338 at a priority equal to the highest priority of any task currently
9339 requesting the lock.
9344 @strong{99}. Default ceiling priorities. See D.3(10).
9347 The ceiling priority of protected objects of the type
9348 @code{System.Interrupt_Priority'Last} as described in the Ada
9349 Reference Manual D.3(10),
9354 @strong{100}. The ceiling of any protected object used internally by
9355 the implementation. See D.3(16).
9358 The ceiling priority of internal protected objects is
9359 @code{System.Priority'Last}.
9364 @strong{101}. Implementation-defined queuing policies. See D.4(1).
9367 There are no implementation-defined queuing policies.
9372 @strong{102}. On a multiprocessor, any conditions that cause the
9373 completion of an aborted construct to be delayed later than what is
9374 specified for a single processor. See D.6(3).
9377 The semantics for abort on a multi-processor is the same as on a single
9378 processor, there are no further delays.
9383 @strong{103}. Any operations that implicitly require heap storage
9384 allocation. See D.7(8).
9387 The only operation that implicitly requires heap storage allocation is
9393 @strong{104}. Implementation-defined aspects of pragma
9394 @code{Restrictions}. See D.7(20).
9397 There are no such implementation-defined aspects.
9402 @strong{105}. Implementation-defined aspects of package
9403 @code{Real_Time}. See D.8(17).
9406 There are no implementation defined aspects of package @code{Real_Time}.
9411 @strong{106}. Implementation-defined aspects of
9412 @code{delay_statements}. See D.9(8).
9415 Any difference greater than one microsecond will cause the task to be
9416 delayed (see D.9(7)).
9421 @strong{107}. The upper bound on the duration of interrupt blocking
9422 caused by the implementation. See D.12(5).
9425 The upper bound is determined by the underlying operating system. In
9426 no cases is it more than 10 milliseconds.
9431 @strong{108}. The means for creating and executing distributed
9435 The GLADE package provides a utility GNATDIST for creating and executing
9436 distributed programs. See the GLADE reference manual for further details.
9441 @strong{109}. Any events that can result in a partition becoming
9442 inaccessible. See E.1(7).
9445 See the GLADE reference manual for full details on such events.
9450 @strong{110}. The scheduling policies, treatment of priorities, and
9451 management of shared resources between partitions in certain cases. See
9455 See the GLADE reference manual for full details on these aspects of
9456 multi-partition execution.
9461 @strong{111}. Events that cause the version of a compilation unit to
9465 Editing the source file of a compilation unit, or the source files of
9466 any units on which it is dependent in a significant way cause the version
9467 to change. No other actions cause the version number to change. All changes
9468 are significant except those which affect only layout, capitalization or
9474 @strong{112}. Whether the execution of the remote subprogram is
9475 immediately aborted as a result of cancellation. See E.4(13).
9478 See the GLADE reference manual for details on the effect of abort in
9479 a distributed application.
9484 @strong{113}. Implementation-defined aspects of the PCS@. See E.5(25).
9487 See the GLADE reference manual for a full description of all implementation
9488 defined aspects of the PCS@.
9493 @strong{114}. Implementation-defined interfaces in the PCS@. See
9497 See the GLADE reference manual for a full description of all
9498 implementation defined interfaces.
9503 @strong{115}. The values of named numbers in the package
9504 @code{Decimal}. See F.2(7).
9516 @item Max_Decimal_Digits
9523 @strong{116}. The value of @code{Max_Picture_Length} in the package
9524 @code{Text_IO.Editing}. See F.3.3(16).
9532 @strong{117}. The value of @code{Max_Picture_Length} in the package
9533 @code{Wide_Text_IO.Editing}. See F.3.4(5).
9541 @strong{118}. The accuracy actually achieved by the complex elementary
9542 functions and by other complex arithmetic operations. See G.1(1).
9545 Standard library functions are used for the complex arithmetic
9546 operations. Only fast math mode is currently supported.
9551 @strong{119}. The sign of a zero result (or a component thereof) from
9552 any operator or function in @code{Numerics.Generic_Complex_Types}, when
9553 @code{Real'Signed_Zeros} is True. See G.1.1(53).
9556 The signs of zero values are as recommended by the relevant
9557 implementation advice.
9562 @strong{120}. The sign of a zero result (or a component thereof) from
9563 any operator or function in
9564 @code{Numerics.Generic_Complex_Elementary_Functions}, when
9565 @code{Real'Signed_Zeros} is @code{True}. See G.1.2(45).
9568 The signs of zero values are as recommended by the relevant
9569 implementation advice.
9574 @strong{121}. Whether the strict mode or the relaxed mode is the
9575 default. See G.2(2).
9578 The strict mode is the default. There is no separate relaxed mode. GNAT
9579 provides a highly efficient implementation of strict mode.
9584 @strong{122}. The result interval in certain cases of fixed-to-float
9585 conversion. See G.2.1(10).
9588 For cases where the result interval is implementation dependent, the
9589 accuracy is that provided by performing all operations in 64-bit IEEE
9590 floating-point format.
9595 @strong{123}. The result of a floating point arithmetic operation in
9596 overflow situations, when the @code{Machine_Overflows} attribute of the
9597 result type is @code{False}. See G.2.1(13).
9600 Infinite and NaN values are produced as dictated by the IEEE
9601 floating-point standard.
9603 Note that on machines that are not fully compliant with the IEEE
9604 floating-point standard, such as Alpha, the @option{-mieee} compiler flag
9605 must be used for achieving IEEE confirming behavior (although at the cost
9606 of a significant performance penalty), so infinite and NaN values are
9612 @strong{124}. The result interval for division (or exponentiation by a
9613 negative exponent), when the floating point hardware implements division
9614 as multiplication by a reciprocal. See G.2.1(16).
9617 Not relevant, division is IEEE exact.
9622 @strong{125}. The definition of close result set, which determines the
9623 accuracy of certain fixed point multiplications and divisions. See
9627 Operations in the close result set are performed using IEEE long format
9628 floating-point arithmetic. The input operands are converted to
9629 floating-point, the operation is done in floating-point, and the result
9630 is converted to the target type.
9635 @strong{126}. Conditions on a @code{universal_real} operand of a fixed
9636 point multiplication or division for which the result shall be in the
9637 perfect result set. See G.2.3(22).
9640 The result is only defined to be in the perfect result set if the result
9641 can be computed by a single scaling operation involving a scale factor
9642 representable in 64-bits.
9647 @strong{127}. The result of a fixed point arithmetic operation in
9648 overflow situations, when the @code{Machine_Overflows} attribute of the
9649 result type is @code{False}. See G.2.3(27).
9652 Not relevant, @code{Machine_Overflows} is @code{True} for fixed-point
9658 @strong{128}. The result of an elementary function reference in
9659 overflow situations, when the @code{Machine_Overflows} attribute of the
9660 result type is @code{False}. See G.2.4(4).
9663 IEEE infinite and Nan values are produced as appropriate.
9668 @strong{129}. The value of the angle threshold, within which certain
9669 elementary functions, complex arithmetic operations, and complex
9670 elementary functions yield results conforming to a maximum relative
9671 error bound. See G.2.4(10).
9674 Information on this subject is not yet available.
9679 @strong{130}. The accuracy of certain elementary functions for
9680 parameters beyond the angle threshold. See G.2.4(10).
9683 Information on this subject is not yet available.
9688 @strong{131}. The result of a complex arithmetic operation or complex
9689 elementary function reference in overflow situations, when the
9690 @code{Machine_Overflows} attribute of the corresponding real type is
9691 @code{False}. See G.2.6(5).
9694 IEEE infinite and Nan values are produced as appropriate.
9699 @strong{132}. The accuracy of certain complex arithmetic operations and
9700 certain complex elementary functions for parameters (or components
9701 thereof) beyond the angle threshold. See G.2.6(8).
9704 Information on those subjects is not yet available.
9709 @strong{133}. Information regarding bounded errors and erroneous
9710 execution. See H.2(1).
9713 Information on this subject is not yet available.
9718 @strong{134}. Implementation-defined aspects of pragma
9719 @code{Inspection_Point}. See H.3.2(8).
9722 Pragma @code{Inspection_Point} ensures that the variable is live and can
9723 be examined by the debugger at the inspection point.
9728 @strong{135}. Implementation-defined aspects of pragma
9729 @code{Restrictions}. See H.4(25).
9732 There are no implementation-defined aspects of pragma @code{Restrictions}. The
9733 use of pragma @code{Restrictions [No_Exceptions]} has no effect on the
9734 generated code. Checks must suppressed by use of pragma @code{Suppress}.
9739 @strong{136}. Any restrictions on pragma @code{Restrictions}. See
9743 There are no restrictions on pragma @code{Restrictions}.
9745 @node Intrinsic Subprograms
9746 @chapter Intrinsic Subprograms
9747 @cindex Intrinsic Subprograms
9750 * Intrinsic Operators::
9751 * Enclosing_Entity::
9752 * Exception_Information::
9753 * Exception_Message::
9761 * Shift_Right_Arithmetic::
9766 GNAT allows a user application program to write the declaration:
9768 @smallexample @c ada
9769 pragma Import (Intrinsic, name);
9773 providing that the name corresponds to one of the implemented intrinsic
9774 subprograms in GNAT, and that the parameter profile of the referenced
9775 subprogram meets the requirements. This chapter describes the set of
9776 implemented intrinsic subprograms, and the requirements on parameter profiles.
9777 Note that no body is supplied; as with other uses of pragma Import, the
9778 body is supplied elsewhere (in this case by the compiler itself). Note
9779 that any use of this feature is potentially non-portable, since the
9780 Ada standard does not require Ada compilers to implement this feature.
9782 @node Intrinsic Operators
9783 @section Intrinsic Operators
9784 @cindex Intrinsic operator
9787 All the predefined numeric operators in package Standard
9788 in @code{pragma Import (Intrinsic,..)}
9789 declarations. In the binary operator case, the operands must have the same
9790 size. The operand or operands must also be appropriate for
9791 the operator. For example, for addition, the operands must
9792 both be floating-point or both be fixed-point, and the
9793 right operand for @code{"**"} must have a root type of
9794 @code{Standard.Integer'Base}.
9795 You can use an intrinsic operator declaration as in the following example:
9797 @smallexample @c ada
9798 type Int1 is new Integer;
9799 type Int2 is new Integer;
9801 function "+" (X1 : Int1; X2 : Int2) return Int1;
9802 function "+" (X1 : Int1; X2 : Int2) return Int2;
9803 pragma Import (Intrinsic, "+");
9807 This declaration would permit ``mixed mode'' arithmetic on items
9808 of the differing types @code{Int1} and @code{Int2}.
9809 It is also possible to specify such operators for private types, if the
9810 full views are appropriate arithmetic types.
9812 @node Enclosing_Entity
9813 @section Enclosing_Entity
9814 @cindex Enclosing_Entity
9816 This intrinsic subprogram is used in the implementation of the
9817 library routine @code{GNAT.Source_Info}. The only useful use of the
9818 intrinsic import in this case is the one in this unit, so an
9819 application program should simply call the function
9820 @code{GNAT.Source_Info.Enclosing_Entity} to obtain the name of
9821 the current subprogram, package, task, entry, or protected subprogram.
9823 @node Exception_Information
9824 @section Exception_Information
9825 @cindex Exception_Information'
9827 This intrinsic subprogram is used in the implementation of the
9828 library routine @code{GNAT.Current_Exception}. The only useful
9829 use of the intrinsic import in this case is the one in this unit,
9830 so an application program should simply call the function
9831 @code{GNAT.Current_Exception.Exception_Information} to obtain
9832 the exception information associated with the current exception.
9834 @node Exception_Message
9835 @section Exception_Message
9836 @cindex Exception_Message
9838 This intrinsic subprogram is used in the implementation of the
9839 library routine @code{GNAT.Current_Exception}. The only useful
9840 use of the intrinsic import in this case is the one in this unit,
9841 so an application program should simply call the function
9842 @code{GNAT.Current_Exception.Exception_Message} to obtain
9843 the message associated with the current exception.
9845 @node Exception_Name
9846 @section Exception_Name
9847 @cindex Exception_Name
9849 This intrinsic subprogram is used in the implementation of the
9850 library routine @code{GNAT.Current_Exception}. The only useful
9851 use of the intrinsic import in this case is the one in this unit,
9852 so an application program should simply call the function
9853 @code{GNAT.Current_Exception.Exception_Name} to obtain
9854 the name of the current exception.
9860 This intrinsic subprogram is used in the implementation of the
9861 library routine @code{GNAT.Source_Info}. The only useful use of the
9862 intrinsic import in this case is the one in this unit, so an
9863 application program should simply call the function
9864 @code{GNAT.Source_Info.File} to obtain the name of the current
9871 This intrinsic subprogram is used in the implementation of the
9872 library routine @code{GNAT.Source_Info}. The only useful use of the
9873 intrinsic import in this case is the one in this unit, so an
9874 application program should simply call the function
9875 @code{GNAT.Source_Info.Line} to obtain the number of the current
9879 @section Rotate_Left
9882 In standard Ada, the @code{Rotate_Left} function is available only
9883 for the predefined modular types in package @code{Interfaces}. However, in
9884 GNAT it is possible to define a Rotate_Left function for a user
9885 defined modular type or any signed integer type as in this example:
9887 @smallexample @c ada
9889 (Value : My_Modular_Type;
9891 return My_Modular_Type;
9895 The requirements are that the profile be exactly as in the example
9896 above. The only modifications allowed are in the formal parameter
9897 names, and in the type of @code{Value} and the return type, which
9898 must be the same, and must be either a signed integer type, or
9899 a modular integer type with a binary modulus, and the size must
9900 be 8. 16, 32 or 64 bits.
9903 @section Rotate_Right
9904 @cindex Rotate_Right
9906 A @code{Rotate_Right} function can be defined for any user defined
9907 binary modular integer type, or signed integer type, as described
9908 above for @code{Rotate_Left}.
9914 A @code{Shift_Left} function can be defined for any user defined
9915 binary modular integer type, or signed integer type, as described
9916 above for @code{Rotate_Left}.
9919 @section Shift_Right
9922 A @code{Shift_Right} function can be defined for any user defined
9923 binary modular integer type, or signed integer type, as described
9924 above for @code{Rotate_Left}.
9926 @node Shift_Right_Arithmetic
9927 @section Shift_Right_Arithmetic
9928 @cindex Shift_Right_Arithmetic
9930 A @code{Shift_Right_Arithmetic} function can be defined for any user
9931 defined binary modular integer type, or signed integer type, as described
9932 above for @code{Rotate_Left}.
9934 @node Source_Location
9935 @section Source_Location
9936 @cindex Source_Location
9938 This intrinsic subprogram is used in the implementation of the
9939 library routine @code{GNAT.Source_Info}. The only useful use of the
9940 intrinsic import in this case is the one in this unit, so an
9941 application program should simply call the function
9942 @code{GNAT.Source_Info.Source_Location} to obtain the current
9943 source file location.
9945 @node Representation Clauses and Pragmas
9946 @chapter Representation Clauses and Pragmas
9947 @cindex Representation Clauses
9950 * Alignment Clauses::
9952 * Storage_Size Clauses::
9953 * Size of Variant Record Objects::
9954 * Biased Representation ::
9955 * Value_Size and Object_Size Clauses::
9956 * Component_Size Clauses::
9957 * Bit_Order Clauses::
9958 * Effect of Bit_Order on Byte Ordering::
9959 * Pragma Pack for Arrays::
9960 * Pragma Pack for Records::
9961 * Record Representation Clauses::
9962 * Enumeration Clauses::
9964 * Effect of Convention on Representation::
9965 * Determining the Representations chosen by GNAT::
9969 @cindex Representation Clause
9970 @cindex Representation Pragma
9971 @cindex Pragma, representation
9972 This section describes the representation clauses accepted by GNAT, and
9973 their effect on the representation of corresponding data objects.
9975 GNAT fully implements Annex C (Systems Programming). This means that all
9976 the implementation advice sections in chapter 13 are fully implemented.
9977 However, these sections only require a minimal level of support for
9978 representation clauses. GNAT provides much more extensive capabilities,
9979 and this section describes the additional capabilities provided.
9981 @node Alignment Clauses
9982 @section Alignment Clauses
9983 @cindex Alignment Clause
9986 GNAT requires that all alignment clauses specify a power of 2, and all
9987 default alignments are always a power of 2. The default alignment
9988 values are as follows:
9991 @item @emph{Primitive Types}.
9992 For primitive types, the alignment is the minimum of the actual size of
9993 objects of the type divided by @code{Storage_Unit},
9994 and the maximum alignment supported by the target.
9995 (This maximum alignment is given by the GNAT-specific attribute
9996 @code{Standard'Maximum_Alignment}; see @ref{Maximum_Alignment}.)
9997 @cindex @code{Maximum_Alignment} attribute
9998 For example, for type @code{Long_Float}, the object size is 8 bytes, and the
9999 default alignment will be 8 on any target that supports alignments
10000 this large, but on some targets, the maximum alignment may be smaller
10001 than 8, in which case objects of type @code{Long_Float} will be maximally
10004 @item @emph{Arrays}.
10005 For arrays, the alignment is equal to the alignment of the component type
10006 for the normal case where no packing or component size is given. If the
10007 array is packed, and the packing is effective (see separate section on
10008 packed arrays), then the alignment will be one for long packed arrays,
10009 or arrays whose length is not known at compile time. For short packed
10010 arrays, which are handled internally as modular types, the alignment
10011 will be as described for primitive types, e.g.@: a packed array of length
10012 31 bits will have an object size of four bytes, and an alignment of 4.
10014 @item @emph{Records}.
10015 For the normal non-packed case, the alignment of a record is equal to
10016 the maximum alignment of any of its components. For tagged records, this
10017 includes the implicit access type used for the tag. If a pragma @code{Pack}
10018 is used and all components are packable (see separate section on pragma
10019 @code{Pack}), then the resulting alignment is 1, unless the layout of the
10020 record makes it profitable to increase it.
10022 A special case is when:
10025 the size of the record is given explicitly, or a
10026 full record representation clause is given, and
10028 the size of the record is 2, 4, or 8 bytes.
10031 In this case, an alignment is chosen to match the
10032 size of the record. For example, if we have:
10034 @smallexample @c ada
10035 type Small is record
10038 for Small'Size use 16;
10042 then the default alignment of the record type @code{Small} is 2, not 1. This
10043 leads to more efficient code when the record is treated as a unit, and also
10044 allows the type to specified as @code{Atomic} on architectures requiring
10050 An alignment clause may specify a larger alignment than the default value
10051 up to some maximum value dependent on the target (obtainable by using the
10052 attribute reference @code{Standard'Maximum_Alignment}). It may also specify
10053 a smaller alignment than the default value for enumeration, integer and
10054 fixed point types, as well as for record types, for example
10056 @smallexample @c ada
10061 for V'alignment use 1;
10065 @cindex Alignment, default
10066 The default alignment for the type @code{V} is 4, as a result of the
10067 Integer field in the record, but it is permissible, as shown, to
10068 override the default alignment of the record with a smaller value.
10071 @section Size Clauses
10072 @cindex Size Clause
10075 The default size for a type @code{T} is obtainable through the
10076 language-defined attribute @code{T'Size} and also through the
10077 equivalent GNAT-defined attribute @code{T'Value_Size}.
10078 For objects of type @code{T}, GNAT will generally increase the type size
10079 so that the object size (obtainable through the GNAT-defined attribute
10080 @code{T'Object_Size})
10081 is a multiple of @code{T'Alignment * Storage_Unit}.
10084 @smallexample @c ada
10085 type Smallint is range 1 .. 6;
10094 In this example, @code{Smallint'Size} = @code{Smallint'Value_Size} = 3,
10095 as specified by the RM rules,
10096 but objects of this type will have a size of 8
10097 (@code{Smallint'Object_Size} = 8),
10098 since objects by default occupy an integral number
10099 of storage units. On some targets, notably older
10100 versions of the Digital Alpha, the size of stand
10101 alone objects of this type may be 32, reflecting
10102 the inability of the hardware to do byte load/stores.
10104 Similarly, the size of type @code{Rec} is 40 bits
10105 (@code{Rec'Size} = @code{Rec'Value_Size} = 40), but
10106 the alignment is 4, so objects of this type will have
10107 their size increased to 64 bits so that it is a multiple
10108 of the alignment (in bits). This decision is
10109 in accordance with the specific Implementation Advice in RM 13.3(43):
10112 A @code{Size} clause should be supported for an object if the specified
10113 @code{Size} is at least as large as its subtype's @code{Size}, and corresponds
10114 to a size in storage elements that is a multiple of the object's
10115 @code{Alignment} (if the @code{Alignment} is nonzero).
10119 An explicit size clause may be used to override the default size by
10120 increasing it. For example, if we have:
10122 @smallexample @c ada
10123 type My_Boolean is new Boolean;
10124 for My_Boolean'Size use 32;
10128 then values of this type will always be 32 bits long. In the case of
10129 discrete types, the size can be increased up to 64 bits, with the effect
10130 that the entire specified field is used to hold the value, sign- or
10131 zero-extended as appropriate. If more than 64 bits is specified, then
10132 padding space is allocated after the value, and a warning is issued that
10133 there are unused bits.
10135 Similarly the size of records and arrays may be increased, and the effect
10136 is to add padding bits after the value. This also causes a warning message
10139 The largest Size value permitted in GNAT is 2**31@minus{}1. Since this is a
10140 Size in bits, this corresponds to an object of size 256 megabytes (minus
10141 one). This limitation is true on all targets. The reason for this
10142 limitation is that it improves the quality of the code in many cases
10143 if it is known that a Size value can be accommodated in an object of
10146 @node Storage_Size Clauses
10147 @section Storage_Size Clauses
10148 @cindex Storage_Size Clause
10151 For tasks, the @code{Storage_Size} clause specifies the amount of space
10152 to be allocated for the task stack. This cannot be extended, and if the
10153 stack is exhausted, then @code{Storage_Error} will be raised (if stack
10154 checking is enabled). Use a @code{Storage_Size} attribute definition clause,
10155 or a @code{Storage_Size} pragma in the task definition to set the
10156 appropriate required size. A useful technique is to include in every
10157 task definition a pragma of the form:
10159 @smallexample @c ada
10160 pragma Storage_Size (Default_Stack_Size);
10164 Then @code{Default_Stack_Size} can be defined in a global package, and
10165 modified as required. Any tasks requiring stack sizes different from the
10166 default can have an appropriate alternative reference in the pragma.
10168 You can also use the @option{-d} binder switch to modify the default stack
10171 For access types, the @code{Storage_Size} clause specifies the maximum
10172 space available for allocation of objects of the type. If this space is
10173 exceeded then @code{Storage_Error} will be raised by an allocation attempt.
10174 In the case where the access type is declared local to a subprogram, the
10175 use of a @code{Storage_Size} clause triggers automatic use of a special
10176 predefined storage pool (@code{System.Pool_Size}) that ensures that all
10177 space for the pool is automatically reclaimed on exit from the scope in
10178 which the type is declared.
10180 A special case recognized by the compiler is the specification of a
10181 @code{Storage_Size} of zero for an access type. This means that no
10182 items can be allocated from the pool, and this is recognized at compile
10183 time, and all the overhead normally associated with maintaining a fixed
10184 size storage pool is eliminated. Consider the following example:
10186 @smallexample @c ada
10188 type R is array (Natural) of Character;
10189 type P is access all R;
10190 for P'Storage_Size use 0;
10191 -- Above access type intended only for interfacing purposes
10195 procedure g (m : P);
10196 pragma Import (C, g);
10207 As indicated in this example, these dummy storage pools are often useful in
10208 connection with interfacing where no object will ever be allocated. If you
10209 compile the above example, you get the warning:
10212 p.adb:16:09: warning: allocation from empty storage pool
10213 p.adb:16:09: warning: Storage_Error will be raised at run time
10217 Of course in practice, there will not be any explicit allocators in the
10218 case of such an access declaration.
10220 @node Size of Variant Record Objects
10221 @section Size of Variant Record Objects
10222 @cindex Size, variant record objects
10223 @cindex Variant record objects, size
10226 In the case of variant record objects, there is a question whether Size gives
10227 information about a particular variant, or the maximum size required
10228 for any variant. Consider the following program
10230 @smallexample @c ada
10231 with Text_IO; use Text_IO;
10233 type R1 (A : Boolean := False) is record
10235 when True => X : Character;
10236 when False => null;
10244 Put_Line (Integer'Image (V1'Size));
10245 Put_Line (Integer'Image (V2'Size));
10250 Here we are dealing with a variant record, where the True variant
10251 requires 16 bits, and the False variant requires 8 bits.
10252 In the above example, both V1 and V2 contain the False variant,
10253 which is only 8 bits long. However, the result of running the
10262 The reason for the difference here is that the discriminant value of
10263 V1 is fixed, and will always be False. It is not possible to assign
10264 a True variant value to V1, therefore 8 bits is sufficient. On the
10265 other hand, in the case of V2, the initial discriminant value is
10266 False (from the default), but it is possible to assign a True
10267 variant value to V2, therefore 16 bits must be allocated for V2
10268 in the general case, even fewer bits may be needed at any particular
10269 point during the program execution.
10271 As can be seen from the output of this program, the @code{'Size}
10272 attribute applied to such an object in GNAT gives the actual allocated
10273 size of the variable, which is the largest size of any of the variants.
10274 The Ada Reference Manual is not completely clear on what choice should
10275 be made here, but the GNAT behavior seems most consistent with the
10276 language in the RM@.
10278 In some cases, it may be desirable to obtain the size of the current
10279 variant, rather than the size of the largest variant. This can be
10280 achieved in GNAT by making use of the fact that in the case of a
10281 subprogram parameter, GNAT does indeed return the size of the current
10282 variant (because a subprogram has no way of knowing how much space
10283 is actually allocated for the actual).
10285 Consider the following modified version of the above program:
10287 @smallexample @c ada
10288 with Text_IO; use Text_IO;
10290 type R1 (A : Boolean := False) is record
10292 when True => X : Character;
10293 when False => null;
10299 function Size (V : R1) return Integer is
10305 Put_Line (Integer'Image (V2'Size));
10306 Put_Line (Integer'IMage (Size (V2)));
10308 Put_Line (Integer'Image (V2'Size));
10309 Put_Line (Integer'IMage (Size (V2)));
10314 The output from this program is
10324 Here we see that while the @code{'Size} attribute always returns
10325 the maximum size, regardless of the current variant value, the
10326 @code{Size} function does indeed return the size of the current
10329 @node Biased Representation
10330 @section Biased Representation
10331 @cindex Size for biased representation
10332 @cindex Biased representation
10335 In the case of scalars with a range starting at other than zero, it is
10336 possible in some cases to specify a size smaller than the default minimum
10337 value, and in such cases, GNAT uses an unsigned biased representation,
10338 in which zero is used to represent the lower bound, and successive values
10339 represent successive values of the type.
10341 For example, suppose we have the declaration:
10343 @smallexample @c ada
10344 type Small is range -7 .. -4;
10345 for Small'Size use 2;
10349 Although the default size of type @code{Small} is 4, the @code{Size}
10350 clause is accepted by GNAT and results in the following representation
10354 -7 is represented as 2#00#
10355 -6 is represented as 2#01#
10356 -5 is represented as 2#10#
10357 -4 is represented as 2#11#
10361 Biased representation is only used if the specified @code{Size} clause
10362 cannot be accepted in any other manner. These reduced sizes that force
10363 biased representation can be used for all discrete types except for
10364 enumeration types for which a representation clause is given.
10366 @node Value_Size and Object_Size Clauses
10367 @section Value_Size and Object_Size Clauses
10369 @findex Object_Size
10370 @cindex Size, of objects
10373 In Ada 95 and Ada 2005, @code{T'Size} for a type @code{T} is the minimum
10374 number of bits required to hold values of type @code{T}.
10375 Although this interpretation was allowed in Ada 83, it was not required,
10376 and this requirement in practice can cause some significant difficulties.
10377 For example, in most Ada 83 compilers, @code{Natural'Size} was 32.
10378 However, in Ada 95 and Ada 2005,
10379 @code{Natural'Size} is
10380 typically 31. This means that code may change in behavior when moving
10381 from Ada 83 to Ada 95 or Ada 2005. For example, consider:
10383 @smallexample @c ada
10384 type Rec is record;
10390 at 0 range 0 .. Natural'Size - 1;
10391 at 0 range Natural'Size .. 2 * Natural'Size - 1;
10396 In the above code, since the typical size of @code{Natural} objects
10397 is 32 bits and @code{Natural'Size} is 31, the above code can cause
10398 unexpected inefficient packing in Ada 95 and Ada 2005, and in general
10399 there are cases where the fact that the object size can exceed the
10400 size of the type causes surprises.
10402 To help get around this problem GNAT provides two implementation
10403 defined attributes, @code{Value_Size} and @code{Object_Size}. When
10404 applied to a type, these attributes yield the size of the type
10405 (corresponding to the RM defined size attribute), and the size of
10406 objects of the type respectively.
10408 The @code{Object_Size} is used for determining the default size of
10409 objects and components. This size value can be referred to using the
10410 @code{Object_Size} attribute. The phrase ``is used'' here means that it is
10411 the basis of the determination of the size. The backend is free to
10412 pad this up if necessary for efficiency, e.g.@: an 8-bit stand-alone
10413 character might be stored in 32 bits on a machine with no efficient
10414 byte access instructions such as the Alpha.
10416 The default rules for the value of @code{Object_Size} for
10417 discrete types are as follows:
10421 The @code{Object_Size} for base subtypes reflect the natural hardware
10422 size in bits (run the compiler with @option{-gnatS} to find those values
10423 for numeric types). Enumeration types and fixed-point base subtypes have
10424 8, 16, 32 or 64 bits for this size, depending on the range of values
10428 The @code{Object_Size} of a subtype is the same as the
10429 @code{Object_Size} of
10430 the type from which it is obtained.
10433 The @code{Object_Size} of a derived base type is copied from the parent
10434 base type, and the @code{Object_Size} of a derived first subtype is copied
10435 from the parent first subtype.
10439 The @code{Value_Size} attribute
10440 is the (minimum) number of bits required to store a value
10442 This value is used to determine how tightly to pack
10443 records or arrays with components of this type, and also affects
10444 the semantics of unchecked conversion (unchecked conversions where
10445 the @code{Value_Size} values differ generate a warning, and are potentially
10448 The default rules for the value of @code{Value_Size} are as follows:
10452 The @code{Value_Size} for a base subtype is the minimum number of bits
10453 required to store all values of the type (including the sign bit
10454 only if negative values are possible).
10457 If a subtype statically matches the first subtype of a given type, then it has
10458 by default the same @code{Value_Size} as the first subtype. This is a
10459 consequence of RM 13.1(14) (``if two subtypes statically match,
10460 then their subtype-specific aspects are the same''.)
10463 All other subtypes have a @code{Value_Size} corresponding to the minimum
10464 number of bits required to store all values of the subtype. For
10465 dynamic bounds, it is assumed that the value can range down or up
10466 to the corresponding bound of the ancestor
10470 The RM defined attribute @code{Size} corresponds to the
10471 @code{Value_Size} attribute.
10473 The @code{Size} attribute may be defined for a first-named subtype. This sets
10474 the @code{Value_Size} of
10475 the first-named subtype to the given value, and the
10476 @code{Object_Size} of this first-named subtype to the given value padded up
10477 to an appropriate boundary. It is a consequence of the default rules
10478 above that this @code{Object_Size} will apply to all further subtypes. On the
10479 other hand, @code{Value_Size} is affected only for the first subtype, any
10480 dynamic subtypes obtained from it directly, and any statically matching
10481 subtypes. The @code{Value_Size} of any other static subtypes is not affected.
10483 @code{Value_Size} and
10484 @code{Object_Size} may be explicitly set for any subtype using
10485 an attribute definition clause. Note that the use of these attributes
10486 can cause the RM 13.1(14) rule to be violated. If two access types
10487 reference aliased objects whose subtypes have differing @code{Object_Size}
10488 values as a result of explicit attribute definition clauses, then it
10489 is erroneous to convert from one access subtype to the other.
10491 At the implementation level, Esize stores the Object_Size and the
10492 RM_Size field stores the @code{Value_Size} (and hence the value of the
10493 @code{Size} attribute,
10494 which, as noted above, is equivalent to @code{Value_Size}).
10496 To get a feel for the difference, consider the following examples (note
10497 that in each case the base is @code{Short_Short_Integer} with a size of 8):
10500 Object_Size Value_Size
10502 type x1 is range 0 .. 5; 8 3
10504 type x2 is range 0 .. 5;
10505 for x2'size use 12; 16 12
10507 subtype x3 is x2 range 0 .. 3; 16 2
10509 subtype x4 is x2'base range 0 .. 10; 8 4
10511 subtype x5 is x2 range 0 .. dynamic; 16 3*
10513 subtype x6 is x2'base range 0 .. dynamic; 8 3*
10518 Note: the entries marked ``3*'' are not actually specified by the Ada
10519 Reference Manual, but it seems in the spirit of the RM rules to allocate
10520 the minimum number of bits (here 3, given the range for @code{x2})
10521 known to be large enough to hold the given range of values.
10523 So far, so good, but GNAT has to obey the RM rules, so the question is
10524 under what conditions must the RM @code{Size} be used.
10525 The following is a list
10526 of the occasions on which the RM @code{Size} must be used:
10530 Component size for packed arrays or records
10533 Value of the attribute @code{Size} for a type
10536 Warning about sizes not matching for unchecked conversion
10540 For record types, the @code{Object_Size} is always a multiple of the
10541 alignment of the type (this is true for all types). In some cases the
10542 @code{Value_Size} can be smaller. Consider:
10552 On a typical 32-bit architecture, the X component will be four bytes, and
10553 require four-byte alignment, and the Y component will be one byte. In this
10554 case @code{R'Value_Size} will be 40 (bits) since this is the minimum size
10555 required to store a value of this type, and for example, it is permissible
10556 to have a component of type R in an outer array whose component size is
10557 specified to be 48 bits. However, @code{R'Object_Size} will be 64 (bits),
10558 since it must be rounded up so that this value is a multiple of the
10559 alignment (4 bytes = 32 bits).
10562 For all other types, the @code{Object_Size}
10563 and Value_Size are the same (and equivalent to the RM attribute @code{Size}).
10564 Only @code{Size} may be specified for such types.
10566 @node Component_Size Clauses
10567 @section Component_Size Clauses
10568 @cindex Component_Size Clause
10571 Normally, the value specified in a component size clause must be consistent
10572 with the subtype of the array component with regard to size and alignment.
10573 In other words, the value specified must be at least equal to the size
10574 of this subtype, and must be a multiple of the alignment value.
10576 In addition, component size clauses are allowed which cause the array
10577 to be packed, by specifying a smaller value. A first case is for
10578 component size values in the range 1 through 63. The value specified
10579 must not be smaller than the Size of the subtype. GNAT will accurately
10580 honor all packing requests in this range. For example, if we have:
10582 @smallexample @c ada
10583 type r is array (1 .. 8) of Natural;
10584 for r'Component_Size use 31;
10588 then the resulting array has a length of 31 bytes (248 bits = 8 * 31).
10589 Of course access to the components of such an array is considerably
10590 less efficient than if the natural component size of 32 is used.
10591 A second case is when the subtype of the component is a record type
10592 padded because of its default alignment. For example, if we have:
10594 @smallexample @c ada
10601 type a is array (1 .. 8) of r;
10602 for a'Component_Size use 72;
10606 then the resulting array has a length of 72 bytes, instead of 96 bytes
10607 if the alignment of the record (4) was obeyed.
10609 Note that there is no point in giving both a component size clause
10610 and a pragma Pack for the same array type. if such duplicate
10611 clauses are given, the pragma Pack will be ignored.
10613 @node Bit_Order Clauses
10614 @section Bit_Order Clauses
10615 @cindex Bit_Order Clause
10616 @cindex bit ordering
10617 @cindex ordering, of bits
10620 For record subtypes, GNAT permits the specification of the @code{Bit_Order}
10621 attribute. The specification may either correspond to the default bit
10622 order for the target, in which case the specification has no effect and
10623 places no additional restrictions, or it may be for the non-standard
10624 setting (that is the opposite of the default).
10626 In the case where the non-standard value is specified, the effect is
10627 to renumber bits within each byte, but the ordering of bytes is not
10628 affected. There are certain
10629 restrictions placed on component clauses as follows:
10633 @item Components fitting within a single storage unit.
10635 These are unrestricted, and the effect is merely to renumber bits. For
10636 example if we are on a little-endian machine with @code{Low_Order_First}
10637 being the default, then the following two declarations have exactly
10640 @smallexample @c ada
10643 B : Integer range 1 .. 120;
10647 A at 0 range 0 .. 0;
10648 B at 0 range 1 .. 7;
10653 B : Integer range 1 .. 120;
10656 for R2'Bit_Order use High_Order_First;
10659 A at 0 range 7 .. 7;
10660 B at 0 range 0 .. 6;
10665 The useful application here is to write the second declaration with the
10666 @code{Bit_Order} attribute definition clause, and know that it will be treated
10667 the same, regardless of whether the target is little-endian or big-endian.
10669 @item Components occupying an integral number of bytes.
10671 These are components that exactly fit in two or more bytes. Such component
10672 declarations are allowed, but have no effect, since it is important to realize
10673 that the @code{Bit_Order} specification does not affect the ordering of bytes.
10674 In particular, the following attempt at getting an endian-independent integer
10677 @smallexample @c ada
10682 for R2'Bit_Order use High_Order_First;
10685 A at 0 range 0 .. 31;
10690 This declaration will result in a little-endian integer on a
10691 little-endian machine, and a big-endian integer on a big-endian machine.
10692 If byte flipping is required for interoperability between big- and
10693 little-endian machines, this must be explicitly programmed. This capability
10694 is not provided by @code{Bit_Order}.
10696 @item Components that are positioned across byte boundaries
10698 but do not occupy an integral number of bytes. Given that bytes are not
10699 reordered, such fields would occupy a non-contiguous sequence of bits
10700 in memory, requiring non-trivial code to reassemble. They are for this
10701 reason not permitted, and any component clause specifying such a layout
10702 will be flagged as illegal by GNAT@.
10707 Since the misconception that Bit_Order automatically deals with all
10708 endian-related incompatibilities is a common one, the specification of
10709 a component field that is an integral number of bytes will always
10710 generate a warning. This warning may be suppressed using @code{pragma
10711 Warnings (Off)} if desired. The following section contains additional
10712 details regarding the issue of byte ordering.
10714 @node Effect of Bit_Order on Byte Ordering
10715 @section Effect of Bit_Order on Byte Ordering
10716 @cindex byte ordering
10717 @cindex ordering, of bytes
10720 In this section we will review the effect of the @code{Bit_Order} attribute
10721 definition clause on byte ordering. Briefly, it has no effect at all, but
10722 a detailed example will be helpful. Before giving this
10723 example, let us review the precise
10724 definition of the effect of defining @code{Bit_Order}. The effect of a
10725 non-standard bit order is described in section 15.5.3 of the Ada
10729 2 A bit ordering is a method of interpreting the meaning of
10730 the storage place attributes.
10734 To understand the precise definition of storage place attributes in
10735 this context, we visit section 13.5.1 of the manual:
10738 13 A record_representation_clause (without the mod_clause)
10739 specifies the layout. The storage place attributes (see 13.5.2)
10740 are taken from the values of the position, first_bit, and last_bit
10741 expressions after normalizing those values so that first_bit is
10742 less than Storage_Unit.
10746 The critical point here is that storage places are taken from
10747 the values after normalization, not before. So the @code{Bit_Order}
10748 interpretation applies to normalized values. The interpretation
10749 is described in the later part of the 15.5.3 paragraph:
10752 2 A bit ordering is a method of interpreting the meaning of
10753 the storage place attributes. High_Order_First (known in the
10754 vernacular as ``big endian'') means that the first bit of a
10755 storage element (bit 0) is the most significant bit (interpreting
10756 the sequence of bits that represent a component as an unsigned
10757 integer value). Low_Order_First (known in the vernacular as
10758 ``little endian'') means the opposite: the first bit is the
10763 Note that the numbering is with respect to the bits of a storage
10764 unit. In other words, the specification affects only the numbering
10765 of bits within a single storage unit.
10767 We can make the effect clearer by giving an example.
10769 Suppose that we have an external device which presents two bytes, the first
10770 byte presented, which is the first (low addressed byte) of the two byte
10771 record is called Master, and the second byte is called Slave.
10773 The left most (most significant bit is called Control for each byte, and
10774 the remaining 7 bits are called V1, V2, @dots{} V7, where V7 is the rightmost
10775 (least significant) bit.
10777 On a big-endian machine, we can write the following representation clause
10779 @smallexample @c ada
10780 type Data is record
10781 Master_Control : Bit;
10789 Slave_Control : Bit;
10799 for Data use record
10800 Master_Control at 0 range 0 .. 0;
10801 Master_V1 at 0 range 1 .. 1;
10802 Master_V2 at 0 range 2 .. 2;
10803 Master_V3 at 0 range 3 .. 3;
10804 Master_V4 at 0 range 4 .. 4;
10805 Master_V5 at 0 range 5 .. 5;
10806 Master_V6 at 0 range 6 .. 6;
10807 Master_V7 at 0 range 7 .. 7;
10808 Slave_Control at 1 range 0 .. 0;
10809 Slave_V1 at 1 range 1 .. 1;
10810 Slave_V2 at 1 range 2 .. 2;
10811 Slave_V3 at 1 range 3 .. 3;
10812 Slave_V4 at 1 range 4 .. 4;
10813 Slave_V5 at 1 range 5 .. 5;
10814 Slave_V6 at 1 range 6 .. 6;
10815 Slave_V7 at 1 range 7 .. 7;
10820 Now if we move this to a little endian machine, then the bit ordering within
10821 the byte is backwards, so we have to rewrite the record rep clause as:
10823 @smallexample @c ada
10824 for Data use record
10825 Master_Control at 0 range 7 .. 7;
10826 Master_V1 at 0 range 6 .. 6;
10827 Master_V2 at 0 range 5 .. 5;
10828 Master_V3 at 0 range 4 .. 4;
10829 Master_V4 at 0 range 3 .. 3;
10830 Master_V5 at 0 range 2 .. 2;
10831 Master_V6 at 0 range 1 .. 1;
10832 Master_V7 at 0 range 0 .. 0;
10833 Slave_Control at 1 range 7 .. 7;
10834 Slave_V1 at 1 range 6 .. 6;
10835 Slave_V2 at 1 range 5 .. 5;
10836 Slave_V3 at 1 range 4 .. 4;
10837 Slave_V4 at 1 range 3 .. 3;
10838 Slave_V5 at 1 range 2 .. 2;
10839 Slave_V6 at 1 range 1 .. 1;
10840 Slave_V7 at 1 range 0 .. 0;
10845 It is a nuisance to have to rewrite the clause, especially if
10846 the code has to be maintained on both machines. However,
10847 this is a case that we can handle with the
10848 @code{Bit_Order} attribute if it is implemented.
10849 Note that the implementation is not required on byte addressed
10850 machines, but it is indeed implemented in GNAT.
10851 This means that we can simply use the
10852 first record clause, together with the declaration
10854 @smallexample @c ada
10855 for Data'Bit_Order use High_Order_First;
10859 and the effect is what is desired, namely the layout is exactly the same,
10860 independent of whether the code is compiled on a big-endian or little-endian
10863 The important point to understand is that byte ordering is not affected.
10864 A @code{Bit_Order} attribute definition never affects which byte a field
10865 ends up in, only where it ends up in that byte.
10866 To make this clear, let us rewrite the record rep clause of the previous
10869 @smallexample @c ada
10870 for Data'Bit_Order use High_Order_First;
10871 for Data use record
10872 Master_Control at 0 range 0 .. 0;
10873 Master_V1 at 0 range 1 .. 1;
10874 Master_V2 at 0 range 2 .. 2;
10875 Master_V3 at 0 range 3 .. 3;
10876 Master_V4 at 0 range 4 .. 4;
10877 Master_V5 at 0 range 5 .. 5;
10878 Master_V6 at 0 range 6 .. 6;
10879 Master_V7 at 0 range 7 .. 7;
10880 Slave_Control at 0 range 8 .. 8;
10881 Slave_V1 at 0 range 9 .. 9;
10882 Slave_V2 at 0 range 10 .. 10;
10883 Slave_V3 at 0 range 11 .. 11;
10884 Slave_V4 at 0 range 12 .. 12;
10885 Slave_V5 at 0 range 13 .. 13;
10886 Slave_V6 at 0 range 14 .. 14;
10887 Slave_V7 at 0 range 15 .. 15;
10892 This is exactly equivalent to saying (a repeat of the first example):
10894 @smallexample @c ada
10895 for Data'Bit_Order use High_Order_First;
10896 for Data use record
10897 Master_Control at 0 range 0 .. 0;
10898 Master_V1 at 0 range 1 .. 1;
10899 Master_V2 at 0 range 2 .. 2;
10900 Master_V3 at 0 range 3 .. 3;
10901 Master_V4 at 0 range 4 .. 4;
10902 Master_V5 at 0 range 5 .. 5;
10903 Master_V6 at 0 range 6 .. 6;
10904 Master_V7 at 0 range 7 .. 7;
10905 Slave_Control at 1 range 0 .. 0;
10906 Slave_V1 at 1 range 1 .. 1;
10907 Slave_V2 at 1 range 2 .. 2;
10908 Slave_V3 at 1 range 3 .. 3;
10909 Slave_V4 at 1 range 4 .. 4;
10910 Slave_V5 at 1 range 5 .. 5;
10911 Slave_V6 at 1 range 6 .. 6;
10912 Slave_V7 at 1 range 7 .. 7;
10917 Why are they equivalent? Well take a specific field, the @code{Slave_V2}
10918 field. The storage place attributes are obtained by normalizing the
10919 values given so that the @code{First_Bit} value is less than 8. After
10920 normalizing the values (0,10,10) we get (1,2,2) which is exactly what
10921 we specified in the other case.
10923 Now one might expect that the @code{Bit_Order} attribute might affect
10924 bit numbering within the entire record component (two bytes in this
10925 case, thus affecting which byte fields end up in), but that is not
10926 the way this feature is defined, it only affects numbering of bits,
10927 not which byte they end up in.
10929 Consequently it never makes sense to specify a starting bit number
10930 greater than 7 (for a byte addressable field) if an attribute
10931 definition for @code{Bit_Order} has been given, and indeed it
10932 may be actively confusing to specify such a value, so the compiler
10933 generates a warning for such usage.
10935 If you do need to control byte ordering then appropriate conditional
10936 values must be used. If in our example, the slave byte came first on
10937 some machines we might write:
10939 @smallexample @c ada
10940 Master_Byte_First constant Boolean := @dots{};
10942 Master_Byte : constant Natural :=
10943 1 - Boolean'Pos (Master_Byte_First);
10944 Slave_Byte : constant Natural :=
10945 Boolean'Pos (Master_Byte_First);
10947 for Data'Bit_Order use High_Order_First;
10948 for Data use record
10949 Master_Control at Master_Byte range 0 .. 0;
10950 Master_V1 at Master_Byte range 1 .. 1;
10951 Master_V2 at Master_Byte range 2 .. 2;
10952 Master_V3 at Master_Byte range 3 .. 3;
10953 Master_V4 at Master_Byte range 4 .. 4;
10954 Master_V5 at Master_Byte range 5 .. 5;
10955 Master_V6 at Master_Byte range 6 .. 6;
10956 Master_V7 at Master_Byte range 7 .. 7;
10957 Slave_Control at Slave_Byte range 0 .. 0;
10958 Slave_V1 at Slave_Byte range 1 .. 1;
10959 Slave_V2 at Slave_Byte range 2 .. 2;
10960 Slave_V3 at Slave_Byte range 3 .. 3;
10961 Slave_V4 at Slave_Byte range 4 .. 4;
10962 Slave_V5 at Slave_Byte range 5 .. 5;
10963 Slave_V6 at Slave_Byte range 6 .. 6;
10964 Slave_V7 at Slave_Byte range 7 .. 7;
10969 Now to switch between machines, all that is necessary is
10970 to set the boolean constant @code{Master_Byte_First} in
10971 an appropriate manner.
10973 @node Pragma Pack for Arrays
10974 @section Pragma Pack for Arrays
10975 @cindex Pragma Pack (for arrays)
10978 Pragma @code{Pack} applied to an array has no effect unless the component type
10979 is packable. For a component type to be packable, it must be one of the
10986 Any type whose size is specified with a size clause
10988 Any packed array type with a static size
10990 Any record type padded because of its default alignment
10994 For all these cases, if the component subtype size is in the range
10995 1 through 63, then the effect of the pragma @code{Pack} is exactly as though a
10996 component size were specified giving the component subtype size.
10997 For example if we have:
10999 @smallexample @c ada
11000 type r is range 0 .. 17;
11002 type ar is array (1 .. 8) of r;
11007 Then the component size of @code{ar} will be set to 5 (i.e.@: to @code{r'size},
11008 and the size of the array @code{ar} will be exactly 40 bits.
11010 Note that in some cases this rather fierce approach to packing can produce
11011 unexpected effects. For example, in Ada 95 and Ada 2005,
11012 subtype @code{Natural} typically has a size of 31, meaning that if you
11013 pack an array of @code{Natural}, you get 31-bit
11014 close packing, which saves a few bits, but results in far less efficient
11015 access. Since many other Ada compilers will ignore such a packing request,
11016 GNAT will generate a warning on some uses of pragma @code{Pack} that it guesses
11017 might not be what is intended. You can easily remove this warning by
11018 using an explicit @code{Component_Size} setting instead, which never generates
11019 a warning, since the intention of the programmer is clear in this case.
11021 GNAT treats packed arrays in one of two ways. If the size of the array is
11022 known at compile time and is less than 64 bits, then internally the array
11023 is represented as a single modular type, of exactly the appropriate number
11024 of bits. If the length is greater than 63 bits, or is not known at compile
11025 time, then the packed array is represented as an array of bytes, and the
11026 length is always a multiple of 8 bits.
11028 Note that to represent a packed array as a modular type, the alignment must
11029 be suitable for the modular type involved. For example, on typical machines
11030 a 32-bit packed array will be represented by a 32-bit modular integer with
11031 an alignment of four bytes. If you explicitly override the default alignment
11032 with an alignment clause that is too small, the modular representation
11033 cannot be used. For example, consider the following set of declarations:
11035 @smallexample @c ada
11036 type R is range 1 .. 3;
11037 type S is array (1 .. 31) of R;
11038 for S'Component_Size use 2;
11040 for S'Alignment use 1;
11044 If the alignment clause were not present, then a 62-bit modular
11045 representation would be chosen (typically with an alignment of 4 or 8
11046 bytes depending on the target). But the default alignment is overridden
11047 with the explicit alignment clause. This means that the modular
11048 representation cannot be used, and instead the array of bytes
11049 representation must be used, meaning that the length must be a multiple
11050 of 8. Thus the above set of declarations will result in a diagnostic
11051 rejecting the size clause and noting that the minimum size allowed is 64.
11053 @cindex Pragma Pack (for type Natural)
11054 @cindex Pragma Pack warning
11056 One special case that is worth noting occurs when the base type of the
11057 component size is 8/16/32 and the subtype is one bit less. Notably this
11058 occurs with subtype @code{Natural}. Consider:
11060 @smallexample @c ada
11061 type Arr is array (1 .. 32) of Natural;
11066 In all commonly used Ada 83 compilers, this pragma Pack would be ignored,
11067 since typically @code{Natural'Size} is 32 in Ada 83, and in any case most
11068 Ada 83 compilers did not attempt 31 bit packing.
11070 In Ada 95 and Ada 2005, @code{Natural'Size} is required to be 31. Furthermore,
11071 GNAT really does pack 31-bit subtype to 31 bits. This may result in a
11072 substantial unintended performance penalty when porting legacy Ada 83 code.
11073 To help prevent this, GNAT generates a warning in such cases. If you really
11074 want 31 bit packing in a case like this, you can set the component size
11077 @smallexample @c ada
11078 type Arr is array (1 .. 32) of Natural;
11079 for Arr'Component_Size use 31;
11083 Here 31-bit packing is achieved as required, and no warning is generated,
11084 since in this case the programmer intention is clear.
11086 @node Pragma Pack for Records
11087 @section Pragma Pack for Records
11088 @cindex Pragma Pack (for records)
11091 Pragma @code{Pack} applied to a record will pack the components to reduce
11092 wasted space from alignment gaps and by reducing the amount of space
11093 taken by components. We distinguish between @emph{packable} components and
11094 @emph{non-packable} components.
11095 Components of the following types are considered packable:
11098 All primitive types are packable.
11101 Small packed arrays, whose size does not exceed 64 bits, and where the
11102 size is statically known at compile time, are represented internally
11103 as modular integers, and so they are also packable.
11108 All packable components occupy the exact number of bits corresponding to
11109 their @code{Size} value, and are packed with no padding bits, i.e.@: they
11110 can start on an arbitrary bit boundary.
11112 All other types are non-packable, they occupy an integral number of
11114 are placed at a boundary corresponding to their alignment requirements.
11116 For example, consider the record
11118 @smallexample @c ada
11119 type Rb1 is array (1 .. 13) of Boolean;
11122 type Rb2 is array (1 .. 65) of Boolean;
11137 The representation for the record x2 is as follows:
11139 @smallexample @c ada
11140 for x2'Size use 224;
11142 l1 at 0 range 0 .. 0;
11143 l2 at 0 range 1 .. 64;
11144 l3 at 12 range 0 .. 31;
11145 l4 at 16 range 0 .. 0;
11146 l5 at 16 range 1 .. 13;
11147 l6 at 18 range 0 .. 71;
11152 Studying this example, we see that the packable fields @code{l1}
11154 of length equal to their sizes, and placed at specific bit boundaries (and
11155 not byte boundaries) to
11156 eliminate padding. But @code{l3} is of a non-packable float type, so
11157 it is on the next appropriate alignment boundary.
11159 The next two fields are fully packable, so @code{l4} and @code{l5} are
11160 minimally packed with no gaps. However, type @code{Rb2} is a packed
11161 array that is longer than 64 bits, so it is itself non-packable. Thus
11162 the @code{l6} field is aligned to the next byte boundary, and takes an
11163 integral number of bytes, i.e.@: 72 bits.
11165 @node Record Representation Clauses
11166 @section Record Representation Clauses
11167 @cindex Record Representation Clause
11170 Record representation clauses may be given for all record types, including
11171 types obtained by record extension. Component clauses are allowed for any
11172 static component. The restrictions on component clauses depend on the type
11175 @cindex Component Clause
11176 For all components of an elementary type, the only restriction on component
11177 clauses is that the size must be at least the 'Size value of the type
11178 (actually the Value_Size). There are no restrictions due to alignment,
11179 and such components may freely cross storage boundaries.
11181 Packed arrays with a size up to and including 64 bits are represented
11182 internally using a modular type with the appropriate number of bits, and
11183 thus the same lack of restriction applies. For example, if you declare:
11185 @smallexample @c ada
11186 type R is array (1 .. 49) of Boolean;
11192 then a component clause for a component of type R may start on any
11193 specified bit boundary, and may specify a value of 49 bits or greater.
11195 For packed bit arrays that are longer than 64 bits, there are two
11196 cases. If the component size is a power of 2 (1,2,4,8,16,32 bits),
11197 including the important case of single bits or boolean values, then
11198 there are no limitations on placement of such components, and they
11199 may start and end at arbitrary bit boundaries.
11201 If the component size is not a power of 2 (e.g.@: 3 or 5), then
11202 an array of this type longer than 64 bits must always be placed on
11203 on a storage unit (byte) boundary and occupy an integral number
11204 of storage units (bytes). Any component clause that does not
11205 meet this requirement will be rejected.
11207 Any aliased component, or component of an aliased type, must
11208 have its normal alignment and size. A component clause that
11209 does not meet this requirement will be rejected.
11211 The tag field of a tagged type always occupies an address sized field at
11212 the start of the record. No component clause may attempt to overlay this
11213 tag. When a tagged type appears as a component, the tag field must have
11216 In the case of a record extension T1, of a type T, no component clause applied
11217 to the type T1 can specify a storage location that would overlap the first
11218 T'Size bytes of the record.
11220 For all other component types, including non-bit-packed arrays,
11221 the component can be placed at an arbitrary bit boundary,
11222 so for example, the following is permitted:
11224 @smallexample @c ada
11225 type R is array (1 .. 10) of Boolean;
11234 G at 0 range 0 .. 0;
11235 H at 0 range 1 .. 1;
11236 L at 0 range 2 .. 81;
11237 R at 0 range 82 .. 161;
11242 Note: the above rules apply to recent releases of GNAT 5.
11243 In GNAT 3, there are more severe restrictions on larger components.
11244 For non-primitive types, including packed arrays with a size greater than
11245 64 bits, component clauses must respect the alignment requirement of the
11246 type, in particular, always starting on a byte boundary, and the length
11247 must be a multiple of the storage unit.
11249 @node Enumeration Clauses
11250 @section Enumeration Clauses
11252 The only restriction on enumeration clauses is that the range of values
11253 must be representable. For the signed case, if one or more of the
11254 representation values are negative, all values must be in the range:
11256 @smallexample @c ada
11257 System.Min_Int .. System.Max_Int
11261 For the unsigned case, where all values are nonnegative, the values must
11264 @smallexample @c ada
11265 0 .. System.Max_Binary_Modulus;
11269 A @emph{confirming} representation clause is one in which the values range
11270 from 0 in sequence, i.e.@: a clause that confirms the default representation
11271 for an enumeration type.
11272 Such a confirming representation
11273 is permitted by these rules, and is specially recognized by the compiler so
11274 that no extra overhead results from the use of such a clause.
11276 If an array has an index type which is an enumeration type to which an
11277 enumeration clause has been applied, then the array is stored in a compact
11278 manner. Consider the declarations:
11280 @smallexample @c ada
11281 type r is (A, B, C);
11282 for r use (A => 1, B => 5, C => 10);
11283 type t is array (r) of Character;
11287 The array type t corresponds to a vector with exactly three elements and
11288 has a default size equal to @code{3*Character'Size}. This ensures efficient
11289 use of space, but means that accesses to elements of the array will incur
11290 the overhead of converting representation values to the corresponding
11291 positional values, (i.e.@: the value delivered by the @code{Pos} attribute).
11293 @node Address Clauses
11294 @section Address Clauses
11295 @cindex Address Clause
11297 The reference manual allows a general restriction on representation clauses,
11298 as found in RM 13.1(22):
11301 An implementation need not support representation
11302 items containing nonstatic expressions, except that
11303 an implementation should support a representation item
11304 for a given entity if each nonstatic expression in the
11305 representation item is a name that statically denotes
11306 a constant declared before the entity.
11310 In practice this is applicable only to address clauses, since this is the
11311 only case in which a non-static expression is permitted by the syntax. As
11312 the AARM notes in sections 13.1 (22.a-22.h):
11315 22.a Reason: This is to avoid the following sort of thing:
11317 22.b X : Integer := F(@dots{});
11318 Y : Address := G(@dots{});
11319 for X'Address use Y;
11321 22.c In the above, we have to evaluate the
11322 initialization expression for X before we
11323 know where to put the result. This seems
11324 like an unreasonable implementation burden.
11326 22.d The above code should instead be written
11329 22.e Y : constant Address := G(@dots{});
11330 X : Integer := F(@dots{});
11331 for X'Address use Y;
11333 22.f This allows the expression ``Y'' to be safely
11334 evaluated before X is created.
11336 22.g The constant could be a formal parameter of mode in.
11338 22.h An implementation can support other nonstatic
11339 expressions if it wants to. Expressions of type
11340 Address are hardly ever static, but their value
11341 might be known at compile time anyway in many
11346 GNAT does indeed permit many additional cases of non-static expressions. In
11347 particular, if the type involved is elementary there are no restrictions
11348 (since in this case, holding a temporary copy of the initialization value,
11349 if one is present, is inexpensive). In addition, if there is no implicit or
11350 explicit initialization, then there are no restrictions. GNAT will reject
11351 only the case where all three of these conditions hold:
11356 The type of the item is non-elementary (e.g.@: a record or array).
11359 There is explicit or implicit initialization required for the object.
11360 Note that access values are always implicitly initialized, and also
11361 in GNAT, certain bit-packed arrays (those having a dynamic length or
11362 a length greater than 64) will also be implicitly initialized to zero.
11365 The address value is non-static. Here GNAT is more permissive than the
11366 RM, and allows the address value to be the address of a previously declared
11367 stand-alone variable, as long as it does not itself have an address clause.
11369 @smallexample @c ada
11370 Anchor : Some_Initialized_Type;
11371 Overlay : Some_Initialized_Type;
11372 for Overlay'Address use Anchor'Address;
11376 However, the prefix of the address clause cannot be an array component, or
11377 a component of a discriminated record.
11382 As noted above in section 22.h, address values are typically non-static. In
11383 particular the To_Address function, even if applied to a literal value, is
11384 a non-static function call. To avoid this minor annoyance, GNAT provides
11385 the implementation defined attribute 'To_Address. The following two
11386 expressions have identical values:
11390 @smallexample @c ada
11391 To_Address (16#1234_0000#)
11392 System'To_Address (16#1234_0000#);
11396 except that the second form is considered to be a static expression, and
11397 thus when used as an address clause value is always permitted.
11400 Additionally, GNAT treats as static an address clause that is an
11401 unchecked_conversion of a static integer value. This simplifies the porting
11402 of legacy code, and provides a portable equivalent to the GNAT attribute
11405 Another issue with address clauses is the interaction with alignment
11406 requirements. When an address clause is given for an object, the address
11407 value must be consistent with the alignment of the object (which is usually
11408 the same as the alignment of the type of the object). If an address clause
11409 is given that specifies an inappropriately aligned address value, then the
11410 program execution is erroneous.
11412 Since this source of erroneous behavior can have unfortunate effects, GNAT
11413 checks (at compile time if possible, generating a warning, or at execution
11414 time with a run-time check) that the alignment is appropriate. If the
11415 run-time check fails, then @code{Program_Error} is raised. This run-time
11416 check is suppressed if range checks are suppressed, or if the special GNAT
11417 check Alignment_Check is suppressed, or if
11418 @code{pragma Restrictions (No_Elaboration_Code)} is in effect.
11420 Finally, GNAT does not permit overlaying of objects of controlled types or
11421 composite types containing a controlled component. In most cases, the compiler
11422 can detect an attempt at such overlays and will generate a warning at compile
11423 time and a Program_Error exception at run time.
11426 An address clause cannot be given for an exported object. More
11427 understandably the real restriction is that objects with an address
11428 clause cannot be exported. This is because such variables are not
11429 defined by the Ada program, so there is no external object to export.
11432 It is permissible to give an address clause and a pragma Import for the
11433 same object. In this case, the variable is not really defined by the
11434 Ada program, so there is no external symbol to be linked. The link name
11435 and the external name are ignored in this case. The reason that we allow this
11436 combination is that it provides a useful idiom to avoid unwanted
11437 initializations on objects with address clauses.
11439 When an address clause is given for an object that has implicit or
11440 explicit initialization, then by default initialization takes place. This
11441 means that the effect of the object declaration is to overwrite the
11442 memory at the specified address. This is almost always not what the
11443 programmer wants, so GNAT will output a warning:
11453 for Ext'Address use System'To_Address (16#1234_1234#);
11455 >>> warning: implicit initialization of "Ext" may
11456 modify overlaid storage
11457 >>> warning: use pragma Import for "Ext" to suppress
11458 initialization (RM B(24))
11464 As indicated by the warning message, the solution is to use a (dummy) pragma
11465 Import to suppress this initialization. The pragma tell the compiler that the
11466 object is declared and initialized elsewhere. The following package compiles
11467 without warnings (and the initialization is suppressed):
11469 @smallexample @c ada
11477 for Ext'Address use System'To_Address (16#1234_1234#);
11478 pragma Import (Ada, Ext);
11483 A final issue with address clauses involves their use for overlaying
11484 variables, as in the following example:
11485 @cindex Overlaying of objects
11487 @smallexample @c ada
11490 for B'Address use A'Address;
11494 or alternatively, using the form recommended by the RM:
11496 @smallexample @c ada
11498 Addr : constant Address := A'Address;
11500 for B'Address use Addr;
11504 In both of these cases, @code{A}
11505 and @code{B} become aliased to one another via the
11506 address clause. This use of address clauses to overlay
11507 variables, achieving an effect similar to unchecked
11508 conversion was erroneous in Ada 83, but in Ada 95 and Ada 2005
11509 the effect is implementation defined. Furthermore, the
11510 Ada RM specifically recommends that in a situation
11511 like this, @code{B} should be subject to the following
11512 implementation advice (RM 13.3(19)):
11515 19 If the Address of an object is specified, or it is imported
11516 or exported, then the implementation should not perform
11517 optimizations based on assumptions of no aliases.
11521 GNAT follows this recommendation, and goes further by also applying
11522 this recommendation to the overlaid variable (@code{A}
11523 in the above example) in this case. This means that the overlay
11524 works "as expected", in that a modification to one of the variables
11525 will affect the value of the other.
11527 @node Effect of Convention on Representation
11528 @section Effect of Convention on Representation
11529 @cindex Convention, effect on representation
11532 Normally the specification of a foreign language convention for a type or
11533 an object has no effect on the chosen representation. In particular, the
11534 representation chosen for data in GNAT generally meets the standard system
11535 conventions, and for example records are laid out in a manner that is
11536 consistent with C@. This means that specifying convention C (for example)
11539 There are four exceptions to this general rule:
11543 @item Convention Fortran and array subtypes
11544 If pragma Convention Fortran is specified for an array subtype, then in
11545 accordance with the implementation advice in section 3.6.2(11) of the
11546 Ada Reference Manual, the array will be stored in a Fortran-compatible
11547 column-major manner, instead of the normal default row-major order.
11549 @item Convention C and enumeration types
11550 GNAT normally stores enumeration types in 8, 16, or 32 bits as required
11551 to accommodate all values of the type. For example, for the enumeration
11554 @smallexample @c ada
11555 type Color is (Red, Green, Blue);
11559 8 bits is sufficient to store all values of the type, so by default, objects
11560 of type @code{Color} will be represented using 8 bits. However, normal C
11561 convention is to use 32 bits for all enum values in C, since enum values
11562 are essentially of type int. If pragma @code{Convention C} is specified for an
11563 Ada enumeration type, then the size is modified as necessary (usually to
11564 32 bits) to be consistent with the C convention for enum values.
11566 Note that this treatment applies only to types. If Convention C is given for
11567 an enumeration object, where the enumeration type is not Convention C, then
11568 Object_Size bits are allocated. For example, for a normal enumeration type,
11569 with less than 256 elements, only 8 bits will be allocated for the object.
11570 Since this may be a surprise in terms of what C expects, GNAT will issue a
11571 warning in this situation. The warning can be suppressed by giving an explicit
11572 size clause specifying the desired size.
11574 @item Convention C/Fortran and Boolean types
11575 In C, the usual convention for boolean values, that is values used for
11576 conditions, is that zero represents false, and nonzero values represent
11577 true. In Ada, the normal convention is that two specific values, typically
11578 0/1, are used to represent false/true respectively.
11580 Fortran has a similar convention for @code{LOGICAL} values (any nonzero
11581 value represents true).
11583 To accommodate the Fortran and C conventions, if a pragma Convention specifies
11584 C or Fortran convention for a derived Boolean, as in the following example:
11586 @smallexample @c ada
11587 type C_Switch is new Boolean;
11588 pragma Convention (C, C_Switch);
11592 then the GNAT generated code will treat any nonzero value as true. For truth
11593 values generated by GNAT, the conventional value 1 will be used for True, but
11594 when one of these values is read, any nonzero value is treated as True.
11596 @item Access types on OpenVMS
11597 For 64-bit OpenVMS systems, access types (other than those for unconstrained
11598 arrays) are 64-bits long. An exception to this rule is for the case of
11599 C-convention access types where there is no explicit size clause present (or
11600 inherited for derived types). In this case, GNAT chooses to make these
11601 pointers 32-bits, which provides an easier path for migration of 32-bit legacy
11602 code. size clause specifying 64-bits must be used to obtain a 64-bit pointer.
11606 @node Determining the Representations chosen by GNAT
11607 @section Determining the Representations chosen by GNAT
11608 @cindex Representation, determination of
11609 @cindex @option{-gnatR} switch
11612 Although the descriptions in this section are intended to be complete, it is
11613 often easier to simply experiment to see what GNAT accepts and what the
11614 effect is on the layout of types and objects.
11616 As required by the Ada RM, if a representation clause is not accepted, then
11617 it must be rejected as illegal by the compiler. However, when a
11618 representation clause or pragma is accepted, there can still be questions
11619 of what the compiler actually does. For example, if a partial record
11620 representation clause specifies the location of some components and not
11621 others, then where are the non-specified components placed? Or if pragma
11622 @code{Pack} is used on a record, then exactly where are the resulting
11623 fields placed? The section on pragma @code{Pack} in this chapter can be
11624 used to answer the second question, but it is often easier to just see
11625 what the compiler does.
11627 For this purpose, GNAT provides the option @option{-gnatR}. If you compile
11628 with this option, then the compiler will output information on the actual
11629 representations chosen, in a format similar to source representation
11630 clauses. For example, if we compile the package:
11632 @smallexample @c ada
11634 type r (x : boolean) is tagged record
11636 when True => S : String (1 .. 100);
11637 when False => null;
11641 type r2 is new r (false) with record
11646 y2 at 16 range 0 .. 31;
11653 type x1 is array (1 .. 10) of x;
11654 for x1'component_size use 11;
11656 type ia is access integer;
11658 type Rb1 is array (1 .. 13) of Boolean;
11661 type Rb2 is array (1 .. 65) of Boolean;
11677 using the switch @option{-gnatR} we obtain the following output:
11680 Representation information for unit q
11681 -------------------------------------
11684 for r'Alignment use 4;
11686 x at 4 range 0 .. 7;
11687 _tag at 0 range 0 .. 31;
11688 s at 5 range 0 .. 799;
11691 for r2'Size use 160;
11692 for r2'Alignment use 4;
11694 x at 4 range 0 .. 7;
11695 _tag at 0 range 0 .. 31;
11696 _parent at 0 range 0 .. 63;
11697 y2 at 16 range 0 .. 31;
11701 for x'Alignment use 1;
11703 y at 0 range 0 .. 7;
11706 for x1'Size use 112;
11707 for x1'Alignment use 1;
11708 for x1'Component_Size use 11;
11710 for rb1'Size use 13;
11711 for rb1'Alignment use 2;
11712 for rb1'Component_Size use 1;
11714 for rb2'Size use 72;
11715 for rb2'Alignment use 1;
11716 for rb2'Component_Size use 1;
11718 for x2'Size use 224;
11719 for x2'Alignment use 4;
11721 l1 at 0 range 0 .. 0;
11722 l2 at 0 range 1 .. 64;
11723 l3 at 12 range 0 .. 31;
11724 l4 at 16 range 0 .. 0;
11725 l5 at 16 range 1 .. 13;
11726 l6 at 18 range 0 .. 71;
11731 The Size values are actually the Object_Size, i.e.@: the default size that
11732 will be allocated for objects of the type.
11733 The ?? size for type r indicates that we have a variant record, and the
11734 actual size of objects will depend on the discriminant value.
11736 The Alignment values show the actual alignment chosen by the compiler
11737 for each record or array type.
11739 The record representation clause for type r shows where all fields
11740 are placed, including the compiler generated tag field (whose location
11741 cannot be controlled by the programmer).
11743 The record representation clause for the type extension r2 shows all the
11744 fields present, including the parent field, which is a copy of the fields
11745 of the parent type of r2, i.e.@: r1.
11747 The component size and size clauses for types rb1 and rb2 show
11748 the exact effect of pragma @code{Pack} on these arrays, and the record
11749 representation clause for type x2 shows how pragma @code{Pack} affects
11752 In some cases, it may be useful to cut and paste the representation clauses
11753 generated by the compiler into the original source to fix and guarantee
11754 the actual representation to be used.
11756 @node Standard Library Routines
11757 @chapter Standard Library Routines
11760 The Ada Reference Manual contains in Annex A a full description of an
11761 extensive set of standard library routines that can be used in any Ada
11762 program, and which must be provided by all Ada compilers. They are
11763 analogous to the standard C library used by C programs.
11765 GNAT implements all of the facilities described in annex A, and for most
11766 purposes the description in the Ada Reference Manual, or appropriate Ada
11767 text book, will be sufficient for making use of these facilities.
11769 In the case of the input-output facilities,
11770 @xref{The Implementation of Standard I/O},
11771 gives details on exactly how GNAT interfaces to the
11772 file system. For the remaining packages, the Ada Reference Manual
11773 should be sufficient. The following is a list of the packages included,
11774 together with a brief description of the functionality that is provided.
11776 For completeness, references are included to other predefined library
11777 routines defined in other sections of the Ada Reference Manual (these are
11778 cross-indexed from Annex A).
11782 This is a parent package for all the standard library packages. It is
11783 usually included implicitly in your program, and itself contains no
11784 useful data or routines.
11786 @item Ada.Calendar (9.6)
11787 @code{Calendar} provides time of day access, and routines for
11788 manipulating times and durations.
11790 @item Ada.Characters (A.3.1)
11791 This is a dummy parent package that contains no useful entities
11793 @item Ada.Characters.Handling (A.3.2)
11794 This package provides some basic character handling capabilities,
11795 including classification functions for classes of characters (e.g.@: test
11796 for letters, or digits).
11798 @item Ada.Characters.Latin_1 (A.3.3)
11799 This package includes a complete set of definitions of the characters
11800 that appear in type CHARACTER@. It is useful for writing programs that
11801 will run in international environments. For example, if you want an
11802 upper case E with an acute accent in a string, it is often better to use
11803 the definition of @code{UC_E_Acute} in this package. Then your program
11804 will print in an understandable manner even if your environment does not
11805 support these extended characters.
11807 @item Ada.Command_Line (A.15)
11808 This package provides access to the command line parameters and the name
11809 of the current program (analogous to the use of @code{argc} and @code{argv}
11810 in C), and also allows the exit status for the program to be set in a
11811 system-independent manner.
11813 @item Ada.Decimal (F.2)
11814 This package provides constants describing the range of decimal numbers
11815 implemented, and also a decimal divide routine (analogous to the COBOL
11816 verb DIVIDE @dots{} GIVING @dots{} REMAINDER @dots{})
11818 @item Ada.Direct_IO (A.8.4)
11819 This package provides input-output using a model of a set of records of
11820 fixed-length, containing an arbitrary definite Ada type, indexed by an
11821 integer record number.
11823 @item Ada.Dynamic_Priorities (D.5)
11824 This package allows the priorities of a task to be adjusted dynamically
11825 as the task is running.
11827 @item Ada.Exceptions (11.4.1)
11828 This package provides additional information on exceptions, and also
11829 contains facilities for treating exceptions as data objects, and raising
11830 exceptions with associated messages.
11832 @item Ada.Finalization (7.6)
11833 This package contains the declarations and subprograms to support the
11834 use of controlled types, providing for automatic initialization and
11835 finalization (analogous to the constructors and destructors of C++)
11837 @item Ada.Interrupts (C.3.2)
11838 This package provides facilities for interfacing to interrupts, which
11839 includes the set of signals or conditions that can be raised and
11840 recognized as interrupts.
11842 @item Ada.Interrupts.Names (C.3.2)
11843 This package provides the set of interrupt names (actually signal
11844 or condition names) that can be handled by GNAT@.
11846 @item Ada.IO_Exceptions (A.13)
11847 This package defines the set of exceptions that can be raised by use of
11848 the standard IO packages.
11851 This package contains some standard constants and exceptions used
11852 throughout the numerics packages. Note that the constants pi and e are
11853 defined here, and it is better to use these definitions than rolling
11856 @item Ada.Numerics.Complex_Elementary_Functions
11857 Provides the implementation of standard elementary functions (such as
11858 log and trigonometric functions) operating on complex numbers using the
11859 standard @code{Float} and the @code{Complex} and @code{Imaginary} types
11860 created by the package @code{Numerics.Complex_Types}.
11862 @item Ada.Numerics.Complex_Types
11863 This is a predefined instantiation of
11864 @code{Numerics.Generic_Complex_Types} using @code{Standard.Float} to
11865 build the type @code{Complex} and @code{Imaginary}.
11867 @item Ada.Numerics.Discrete_Random
11868 This package provides a random number generator suitable for generating
11869 random integer values from a specified range.
11871 @item Ada.Numerics.Float_Random
11872 This package provides a random number generator suitable for generating
11873 uniformly distributed floating point values.
11875 @item Ada.Numerics.Generic_Complex_Elementary_Functions
11876 This is a generic version of the package that provides the
11877 implementation of standard elementary functions (such as log and
11878 trigonometric functions) for an arbitrary complex type.
11880 The following predefined instantiations of this package are provided:
11884 @code{Ada.Numerics.Short_Complex_Elementary_Functions}
11886 @code{Ada.Numerics.Complex_Elementary_Functions}
11888 @code{Ada.Numerics.Long_Complex_Elementary_Functions}
11891 @item Ada.Numerics.Generic_Complex_Types
11892 This is a generic package that allows the creation of complex types,
11893 with associated complex arithmetic operations.
11895 The following predefined instantiations of this package exist
11898 @code{Ada.Numerics.Short_Complex_Complex_Types}
11900 @code{Ada.Numerics.Complex_Complex_Types}
11902 @code{Ada.Numerics.Long_Complex_Complex_Types}
11905 @item Ada.Numerics.Generic_Elementary_Functions
11906 This is a generic package that provides the implementation of standard
11907 elementary functions (such as log an trigonometric functions) for an
11908 arbitrary float type.
11910 The following predefined instantiations of this package exist
11914 @code{Ada.Numerics.Short_Elementary_Functions}
11916 @code{Ada.Numerics.Elementary_Functions}
11918 @code{Ada.Numerics.Long_Elementary_Functions}
11921 @item Ada.Real_Time (D.8)
11922 This package provides facilities similar to those of @code{Calendar}, but
11923 operating with a finer clock suitable for real time control. Note that
11924 annex D requires that there be no backward clock jumps, and GNAT generally
11925 guarantees this behavior, but of course if the external clock on which
11926 the GNAT runtime depends is deliberately reset by some external event,
11927 then such a backward jump may occur.
11929 @item Ada.Sequential_IO (A.8.1)
11930 This package provides input-output facilities for sequential files,
11931 which can contain a sequence of values of a single type, which can be
11932 any Ada type, including indefinite (unconstrained) types.
11934 @item Ada.Storage_IO (A.9)
11935 This package provides a facility for mapping arbitrary Ada types to and
11936 from a storage buffer. It is primarily intended for the creation of new
11939 @item Ada.Streams (13.13.1)
11940 This is a generic package that provides the basic support for the
11941 concept of streams as used by the stream attributes (@code{Input},
11942 @code{Output}, @code{Read} and @code{Write}).
11944 @item Ada.Streams.Stream_IO (A.12.1)
11945 This package is a specialization of the type @code{Streams} defined in
11946 package @code{Streams} together with a set of operations providing
11947 Stream_IO capability. The Stream_IO model permits both random and
11948 sequential access to a file which can contain an arbitrary set of values
11949 of one or more Ada types.
11951 @item Ada.Strings (A.4.1)
11952 This package provides some basic constants used by the string handling
11955 @item Ada.Strings.Bounded (A.4.4)
11956 This package provides facilities for handling variable length
11957 strings. The bounded model requires a maximum length. It is thus
11958 somewhat more limited than the unbounded model, but avoids the use of
11959 dynamic allocation or finalization.
11961 @item Ada.Strings.Fixed (A.4.3)
11962 This package provides facilities for handling fixed length strings.
11964 @item Ada.Strings.Maps (A.4.2)
11965 This package provides facilities for handling character mappings and
11966 arbitrarily defined subsets of characters. For instance it is useful in
11967 defining specialized translation tables.
11969 @item Ada.Strings.Maps.Constants (A.4.6)
11970 This package provides a standard set of predefined mappings and
11971 predefined character sets. For example, the standard upper to lower case
11972 conversion table is found in this package. Note that upper to lower case
11973 conversion is non-trivial if you want to take the entire set of
11974 characters, including extended characters like E with an acute accent,
11975 into account. You should use the mappings in this package (rather than
11976 adding 32 yourself) to do case mappings.
11978 @item Ada.Strings.Unbounded (A.4.5)
11979 This package provides facilities for handling variable length
11980 strings. The unbounded model allows arbitrary length strings, but
11981 requires the use of dynamic allocation and finalization.
11983 @item Ada.Strings.Wide_Bounded (A.4.7)
11984 @itemx Ada.Strings.Wide_Fixed (A.4.7)
11985 @itemx Ada.Strings.Wide_Maps (A.4.7)
11986 @itemx Ada.Strings.Wide_Maps.Constants (A.4.7)
11987 @itemx Ada.Strings.Wide_Unbounded (A.4.7)
11988 These packages provide analogous capabilities to the corresponding
11989 packages without @samp{Wide_} in the name, but operate with the types
11990 @code{Wide_String} and @code{Wide_Character} instead of @code{String}
11991 and @code{Character}.
11993 @item Ada.Strings.Wide_Wide_Bounded (A.4.7)
11994 @itemx Ada.Strings.Wide_Wide_Fixed (A.4.7)
11995 @itemx Ada.Strings.Wide_Wide_Maps (A.4.7)
11996 @itemx Ada.Strings.Wide_Wide_Maps.Constants (A.4.7)
11997 @itemx Ada.Strings.Wide_Wide_Unbounded (A.4.7)
11998 These packages provide analogous capabilities to the corresponding
11999 packages without @samp{Wide_} in the name, but operate with the types
12000 @code{Wide_Wide_String} and @code{Wide_Wide_Character} instead
12001 of @code{String} and @code{Character}.
12003 @item Ada.Synchronous_Task_Control (D.10)
12004 This package provides some standard facilities for controlling task
12005 communication in a synchronous manner.
12008 This package contains definitions for manipulation of the tags of tagged
12011 @item Ada.Task_Attributes
12012 This package provides the capability of associating arbitrary
12013 task-specific data with separate tasks.
12016 This package provides basic text input-output capabilities for
12017 character, string and numeric data. The subpackages of this
12018 package are listed next.
12020 @item Ada.Text_IO.Decimal_IO
12021 Provides input-output facilities for decimal fixed-point types
12023 @item Ada.Text_IO.Enumeration_IO
12024 Provides input-output facilities for enumeration types.
12026 @item Ada.Text_IO.Fixed_IO
12027 Provides input-output facilities for ordinary fixed-point types.
12029 @item Ada.Text_IO.Float_IO
12030 Provides input-output facilities for float types. The following
12031 predefined instantiations of this generic package are available:
12035 @code{Short_Float_Text_IO}
12037 @code{Float_Text_IO}
12039 @code{Long_Float_Text_IO}
12042 @item Ada.Text_IO.Integer_IO
12043 Provides input-output facilities for integer types. The following
12044 predefined instantiations of this generic package are available:
12047 @item Short_Short_Integer
12048 @code{Ada.Short_Short_Integer_Text_IO}
12049 @item Short_Integer
12050 @code{Ada.Short_Integer_Text_IO}
12052 @code{Ada.Integer_Text_IO}
12054 @code{Ada.Long_Integer_Text_IO}
12055 @item Long_Long_Integer
12056 @code{Ada.Long_Long_Integer_Text_IO}
12059 @item Ada.Text_IO.Modular_IO
12060 Provides input-output facilities for modular (unsigned) types
12062 @item Ada.Text_IO.Complex_IO (G.1.3)
12063 This package provides basic text input-output capabilities for complex
12066 @item Ada.Text_IO.Editing (F.3.3)
12067 This package contains routines for edited output, analogous to the use
12068 of pictures in COBOL@. The picture formats used by this package are a
12069 close copy of the facility in COBOL@.
12071 @item Ada.Text_IO.Text_Streams (A.12.2)
12072 This package provides a facility that allows Text_IO files to be treated
12073 as streams, so that the stream attributes can be used for writing
12074 arbitrary data, including binary data, to Text_IO files.
12076 @item Ada.Unchecked_Conversion (13.9)
12077 This generic package allows arbitrary conversion from one type to
12078 another of the same size, providing for breaking the type safety in
12079 special circumstances.
12081 If the types have the same Size (more accurately the same Value_Size),
12082 then the effect is simply to transfer the bits from the source to the
12083 target type without any modification. This usage is well defined, and
12084 for simple types whose representation is typically the same across
12085 all implementations, gives a portable method of performing such
12088 If the types do not have the same size, then the result is implementation
12089 defined, and thus may be non-portable. The following describes how GNAT
12090 handles such unchecked conversion cases.
12092 If the types are of different sizes, and are both discrete types, then
12093 the effect is of a normal type conversion without any constraint checking.
12094 In particular if the result type has a larger size, the result will be
12095 zero or sign extended. If the result type has a smaller size, the result
12096 will be truncated by ignoring high order bits.
12098 If the types are of different sizes, and are not both discrete types,
12099 then the conversion works as though pointers were created to the source
12100 and target, and the pointer value is converted. The effect is that bits
12101 are copied from successive low order storage units and bits of the source
12102 up to the length of the target type.
12104 A warning is issued if the lengths differ, since the effect in this
12105 case is implementation dependent, and the above behavior may not match
12106 that of some other compiler.
12108 A pointer to one type may be converted to a pointer to another type using
12109 unchecked conversion. The only case in which the effect is undefined is
12110 when one or both pointers are pointers to unconstrained array types. In
12111 this case, the bounds information may get incorrectly transferred, and in
12112 particular, GNAT uses double size pointers for such types, and it is
12113 meaningless to convert between such pointer types. GNAT will issue a
12114 warning if the alignment of the target designated type is more strict
12115 than the alignment of the source designated type (since the result may
12116 be unaligned in this case).
12118 A pointer other than a pointer to an unconstrained array type may be
12119 converted to and from System.Address. Such usage is common in Ada 83
12120 programs, but note that Ada.Address_To_Access_Conversions is the
12121 preferred method of performing such conversions in Ada 95 and Ada 2005.
12123 unchecked conversion nor Ada.Address_To_Access_Conversions should be
12124 used in conjunction with pointers to unconstrained objects, since
12125 the bounds information cannot be handled correctly in this case.
12127 @item Ada.Unchecked_Deallocation (13.11.2)
12128 This generic package allows explicit freeing of storage previously
12129 allocated by use of an allocator.
12131 @item Ada.Wide_Text_IO (A.11)
12132 This package is similar to @code{Ada.Text_IO}, except that the external
12133 file supports wide character representations, and the internal types are
12134 @code{Wide_Character} and @code{Wide_String} instead of @code{Character}
12135 and @code{String}. It contains generic subpackages listed next.
12137 @item Ada.Wide_Text_IO.Decimal_IO
12138 Provides input-output facilities for decimal fixed-point types
12140 @item Ada.Wide_Text_IO.Enumeration_IO
12141 Provides input-output facilities for enumeration types.
12143 @item Ada.Wide_Text_IO.Fixed_IO
12144 Provides input-output facilities for ordinary fixed-point types.
12146 @item Ada.Wide_Text_IO.Float_IO
12147 Provides input-output facilities for float types. The following
12148 predefined instantiations of this generic package are available:
12152 @code{Short_Float_Wide_Text_IO}
12154 @code{Float_Wide_Text_IO}
12156 @code{Long_Float_Wide_Text_IO}
12159 @item Ada.Wide_Text_IO.Integer_IO
12160 Provides input-output facilities for integer types. The following
12161 predefined instantiations of this generic package are available:
12164 @item Short_Short_Integer
12165 @code{Ada.Short_Short_Integer_Wide_Text_IO}
12166 @item Short_Integer
12167 @code{Ada.Short_Integer_Wide_Text_IO}
12169 @code{Ada.Integer_Wide_Text_IO}
12171 @code{Ada.Long_Integer_Wide_Text_IO}
12172 @item Long_Long_Integer
12173 @code{Ada.Long_Long_Integer_Wide_Text_IO}
12176 @item Ada.Wide_Text_IO.Modular_IO
12177 Provides input-output facilities for modular (unsigned) types
12179 @item Ada.Wide_Text_IO.Complex_IO (G.1.3)
12180 This package is similar to @code{Ada.Text_IO.Complex_IO}, except that the
12181 external file supports wide character representations.
12183 @item Ada.Wide_Text_IO.Editing (F.3.4)
12184 This package is similar to @code{Ada.Text_IO.Editing}, except that the
12185 types are @code{Wide_Character} and @code{Wide_String} instead of
12186 @code{Character} and @code{String}.
12188 @item Ada.Wide_Text_IO.Streams (A.12.3)
12189 This package is similar to @code{Ada.Text_IO.Streams}, except that the
12190 types are @code{Wide_Character} and @code{Wide_String} instead of
12191 @code{Character} and @code{String}.
12193 @item Ada.Wide_Wide_Text_IO (A.11)
12194 This package is similar to @code{Ada.Text_IO}, except that the external
12195 file supports wide character representations, and the internal types are
12196 @code{Wide_Character} and @code{Wide_String} instead of @code{Character}
12197 and @code{String}. It contains generic subpackages listed next.
12199 @item Ada.Wide_Wide_Text_IO.Decimal_IO
12200 Provides input-output facilities for decimal fixed-point types
12202 @item Ada.Wide_Wide_Text_IO.Enumeration_IO
12203 Provides input-output facilities for enumeration types.
12205 @item Ada.Wide_Wide_Text_IO.Fixed_IO
12206 Provides input-output facilities for ordinary fixed-point types.
12208 @item Ada.Wide_Wide_Text_IO.Float_IO
12209 Provides input-output facilities for float types. The following
12210 predefined instantiations of this generic package are available:
12214 @code{Short_Float_Wide_Wide_Text_IO}
12216 @code{Float_Wide_Wide_Text_IO}
12218 @code{Long_Float_Wide_Wide_Text_IO}
12221 @item Ada.Wide_Wide_Text_IO.Integer_IO
12222 Provides input-output facilities for integer types. The following
12223 predefined instantiations of this generic package are available:
12226 @item Short_Short_Integer
12227 @code{Ada.Short_Short_Integer_Wide_Wide_Text_IO}
12228 @item Short_Integer
12229 @code{Ada.Short_Integer_Wide_Wide_Text_IO}
12231 @code{Ada.Integer_Wide_Wide_Text_IO}
12233 @code{Ada.Long_Integer_Wide_Wide_Text_IO}
12234 @item Long_Long_Integer
12235 @code{Ada.Long_Long_Integer_Wide_Wide_Text_IO}
12238 @item Ada.Wide_Wide_Text_IO.Modular_IO
12239 Provides input-output facilities for modular (unsigned) types
12241 @item Ada.Wide_Wide_Text_IO.Complex_IO (G.1.3)
12242 This package is similar to @code{Ada.Text_IO.Complex_IO}, except that the
12243 external file supports wide character representations.
12245 @item Ada.Wide_Wide_Text_IO.Editing (F.3.4)
12246 This package is similar to @code{Ada.Text_IO.Editing}, except that the
12247 types are @code{Wide_Character} and @code{Wide_String} instead of
12248 @code{Character} and @code{String}.
12250 @item Ada.Wide_Wide_Text_IO.Streams (A.12.3)
12251 This package is similar to @code{Ada.Text_IO.Streams}, except that the
12252 types are @code{Wide_Character} and @code{Wide_String} instead of
12253 @code{Character} and @code{String}.
12258 @node The Implementation of Standard I/O
12259 @chapter The Implementation of Standard I/O
12262 GNAT implements all the required input-output facilities described in
12263 A.6 through A.14. These sections of the Ada Reference Manual describe the
12264 required behavior of these packages from the Ada point of view, and if
12265 you are writing a portable Ada program that does not need to know the
12266 exact manner in which Ada maps to the outside world when it comes to
12267 reading or writing external files, then you do not need to read this
12268 chapter. As long as your files are all regular files (not pipes or
12269 devices), and as long as you write and read the files only from Ada, the
12270 description in the Ada Reference Manual is sufficient.
12272 However, if you want to do input-output to pipes or other devices, such
12273 as the keyboard or screen, or if the files you are dealing with are
12274 either generated by some other language, or to be read by some other
12275 language, then you need to know more about the details of how the GNAT
12276 implementation of these input-output facilities behaves.
12278 In this chapter we give a detailed description of exactly how GNAT
12279 interfaces to the file system. As always, the sources of the system are
12280 available to you for answering questions at an even more detailed level,
12281 but for most purposes the information in this chapter will suffice.
12283 Another reason that you may need to know more about how input-output is
12284 implemented arises when you have a program written in mixed languages
12285 where, for example, files are shared between the C and Ada sections of
12286 the same program. GNAT provides some additional facilities, in the form
12287 of additional child library packages, that facilitate this sharing, and
12288 these additional facilities are also described in this chapter.
12291 * Standard I/O Packages::
12297 * Wide_Wide_Text_IO::
12299 * Text Translation::
12301 * Filenames encoding::
12303 * Operations on C Streams::
12304 * Interfacing to C Streams::
12307 @node Standard I/O Packages
12308 @section Standard I/O Packages
12311 The Standard I/O packages described in Annex A for
12317 Ada.Text_IO.Complex_IO
12319 Ada.Text_IO.Text_Streams
12323 Ada.Wide_Text_IO.Complex_IO
12325 Ada.Wide_Text_IO.Text_Streams
12327 Ada.Wide_Wide_Text_IO
12329 Ada.Wide_Wide_Text_IO.Complex_IO
12331 Ada.Wide_Wide_Text_IO.Text_Streams
12341 are implemented using the C
12342 library streams facility; where
12346 All files are opened using @code{fopen}.
12348 All input/output operations use @code{fread}/@code{fwrite}.
12352 There is no internal buffering of any kind at the Ada library level. The only
12353 buffering is that provided at the system level in the implementation of the
12354 library routines that support streams. This facilitates shared use of these
12355 streams by mixed language programs. Note though that system level buffering is
12356 explicitly enabled at elaboration of the standard I/O packages and that can
12357 have an impact on mixed language programs, in particular those using I/O before
12358 calling the Ada elaboration routine (e.g.@: adainit). It is recommended to call
12359 the Ada elaboration routine before performing any I/O or when impractical,
12360 flush the common I/O streams and in particular Standard_Output before
12361 elaborating the Ada code.
12364 @section FORM Strings
12367 The format of a FORM string in GNAT is:
12370 "keyword=value,keyword=value,@dots{},keyword=value"
12374 where letters may be in upper or lower case, and there are no spaces
12375 between values. The order of the entries is not important. Currently
12376 the following keywords defined.
12379 TEXT_TRANSLATION=[YES|NO]
12381 WCEM=[n|h|u|s|e|8|b]
12382 ENCODING=[UTF8|8BITS]
12386 The use of these parameters is described later in this section.
12392 Direct_IO can only be instantiated for definite types. This is a
12393 restriction of the Ada language, which means that the records are fixed
12394 length (the length being determined by @code{@var{type}'Size}, rounded
12395 up to the next storage unit boundary if necessary).
12397 The records of a Direct_IO file are simply written to the file in index
12398 sequence, with the first record starting at offset zero, and subsequent
12399 records following. There is no control information of any kind. For
12400 example, if 32-bit integers are being written, each record takes
12401 4-bytes, so the record at index @var{K} starts at offset
12402 (@var{K}@minus{}1)*4.
12404 There is no limit on the size of Direct_IO files, they are expanded as
12405 necessary to accommodate whatever records are written to the file.
12407 @node Sequential_IO
12408 @section Sequential_IO
12411 Sequential_IO may be instantiated with either a definite (constrained)
12412 or indefinite (unconstrained) type.
12414 For the definite type case, the elements written to the file are simply
12415 the memory images of the data values with no control information of any
12416 kind. The resulting file should be read using the same type, no validity
12417 checking is performed on input.
12419 For the indefinite type case, the elements written consist of two
12420 parts. First is the size of the data item, written as the memory image
12421 of a @code{Interfaces.C.size_t} value, followed by the memory image of
12422 the data value. The resulting file can only be read using the same
12423 (unconstrained) type. Normal assignment checks are performed on these
12424 read operations, and if these checks fail, @code{Data_Error} is
12425 raised. In particular, in the array case, the lengths must match, and in
12426 the variant record case, if the variable for a particular read operation
12427 is constrained, the discriminants must match.
12429 Note that it is not possible to use Sequential_IO to write variable
12430 length array items, and then read the data back into different length
12431 arrays. For example, the following will raise @code{Data_Error}:
12433 @smallexample @c ada
12434 package IO is new Sequential_IO (String);
12439 IO.Write (F, "hello!")
12440 IO.Reset (F, Mode=>In_File);
12447 On some Ada implementations, this will print @code{hell}, but the program is
12448 clearly incorrect, since there is only one element in the file, and that
12449 element is the string @code{hello!}.
12451 In Ada 95 and Ada 2005, this kind of behavior can be legitimately achieved
12452 using Stream_IO, and this is the preferred mechanism. In particular, the
12453 above program fragment rewritten to use Stream_IO will work correctly.
12459 Text_IO files consist of a stream of characters containing the following
12460 special control characters:
12463 LF (line feed, 16#0A#) Line Mark
12464 FF (form feed, 16#0C#) Page Mark
12468 A canonical Text_IO file is defined as one in which the following
12469 conditions are met:
12473 The character @code{LF} is used only as a line mark, i.e.@: to mark the end
12477 The character @code{FF} is used only as a page mark, i.e.@: to mark the
12478 end of a page and consequently can appear only immediately following a
12479 @code{LF} (line mark) character.
12482 The file ends with either @code{LF} (line mark) or @code{LF}-@code{FF}
12483 (line mark, page mark). In the former case, the page mark is implicitly
12484 assumed to be present.
12488 A file written using Text_IO will be in canonical form provided that no
12489 explicit @code{LF} or @code{FF} characters are written using @code{Put}
12490 or @code{Put_Line}. There will be no @code{FF} character at the end of
12491 the file unless an explicit @code{New_Page} operation was performed
12492 before closing the file.
12494 A canonical Text_IO file that is a regular file (i.e., not a device or a
12495 pipe) can be read using any of the routines in Text_IO@. The
12496 semantics in this case will be exactly as defined in the Ada Reference
12497 Manual, and all the routines in Text_IO are fully implemented.
12499 A text file that does not meet the requirements for a canonical Text_IO
12500 file has one of the following:
12504 The file contains @code{FF} characters not immediately following a
12505 @code{LF} character.
12508 The file contains @code{LF} or @code{FF} characters written by
12509 @code{Put} or @code{Put_Line}, which are not logically considered to be
12510 line marks or page marks.
12513 The file ends in a character other than @code{LF} or @code{FF},
12514 i.e.@: there is no explicit line mark or page mark at the end of the file.
12518 Text_IO can be used to read such non-standard text files but subprograms
12519 to do with line or page numbers do not have defined meanings. In
12520 particular, a @code{FF} character that does not follow a @code{LF}
12521 character may or may not be treated as a page mark from the point of
12522 view of page and line numbering. Every @code{LF} character is considered
12523 to end a line, and there is an implied @code{LF} character at the end of
12527 * Text_IO Stream Pointer Positioning::
12528 * Text_IO Reading and Writing Non-Regular Files::
12530 * Treating Text_IO Files as Streams::
12531 * Text_IO Extensions::
12532 * Text_IO Facilities for Unbounded Strings::
12535 @node Text_IO Stream Pointer Positioning
12536 @subsection Stream Pointer Positioning
12539 @code{Ada.Text_IO} has a definition of current position for a file that
12540 is being read. No internal buffering occurs in Text_IO, and usually the
12541 physical position in the stream used to implement the file corresponds
12542 to this logical position defined by Text_IO@. There are two exceptions:
12546 After a call to @code{End_Of_Page} that returns @code{True}, the stream
12547 is positioned past the @code{LF} (line mark) that precedes the page
12548 mark. Text_IO maintains an internal flag so that subsequent read
12549 operations properly handle the logical position which is unchanged by
12550 the @code{End_Of_Page} call.
12553 After a call to @code{End_Of_File} that returns @code{True}, if the
12554 Text_IO file was positioned before the line mark at the end of file
12555 before the call, then the logical position is unchanged, but the stream
12556 is physically positioned right at the end of file (past the line mark,
12557 and past a possible page mark following the line mark. Again Text_IO
12558 maintains internal flags so that subsequent read operations properly
12559 handle the logical position.
12563 These discrepancies have no effect on the observable behavior of
12564 Text_IO, but if a single Ada stream is shared between a C program and
12565 Ada program, or shared (using @samp{shared=yes} in the form string)
12566 between two Ada files, then the difference may be observable in some
12569 @node Text_IO Reading and Writing Non-Regular Files
12570 @subsection Reading and Writing Non-Regular Files
12573 A non-regular file is a device (such as a keyboard), or a pipe. Text_IO
12574 can be used for reading and writing. Writing is not affected and the
12575 sequence of characters output is identical to the normal file case, but
12576 for reading, the behavior of Text_IO is modified to avoid undesirable
12577 look-ahead as follows:
12579 An input file that is not a regular file is considered to have no page
12580 marks. Any @code{Ascii.FF} characters (the character normally used for a
12581 page mark) appearing in the file are considered to be data
12582 characters. In particular:
12586 @code{Get_Line} and @code{Skip_Line} do not test for a page mark
12587 following a line mark. If a page mark appears, it will be treated as a
12591 This avoids the need to wait for an extra character to be typed or
12592 entered from the pipe to complete one of these operations.
12595 @code{End_Of_Page} always returns @code{False}
12598 @code{End_Of_File} will return @code{False} if there is a page mark at
12599 the end of the file.
12603 Output to non-regular files is the same as for regular files. Page marks
12604 may be written to non-regular files using @code{New_Page}, but as noted
12605 above they will not be treated as page marks on input if the output is
12606 piped to another Ada program.
12608 Another important discrepancy when reading non-regular files is that the end
12609 of file indication is not ``sticky''. If an end of file is entered, e.g.@: by
12610 pressing the @key{EOT} key,
12612 is signaled once (i.e.@: the test @code{End_Of_File}
12613 will yield @code{True}, or a read will
12614 raise @code{End_Error}), but then reading can resume
12615 to read data past that end of
12616 file indication, until another end of file indication is entered.
12618 @node Get_Immediate
12619 @subsection Get_Immediate
12620 @cindex Get_Immediate
12623 Get_Immediate returns the next character (including control characters)
12624 from the input file. In particular, Get_Immediate will return LF or FF
12625 characters used as line marks or page marks. Such operations leave the
12626 file positioned past the control character, and it is thus not treated
12627 as having its normal function. This means that page, line and column
12628 counts after this kind of Get_Immediate call are set as though the mark
12629 did not occur. In the case where a Get_Immediate leaves the file
12630 positioned between the line mark and page mark (which is not normally
12631 possible), it is undefined whether the FF character will be treated as a
12634 @node Treating Text_IO Files as Streams
12635 @subsection Treating Text_IO Files as Streams
12636 @cindex Stream files
12639 The package @code{Text_IO.Streams} allows a Text_IO file to be treated
12640 as a stream. Data written to a Text_IO file in this stream mode is
12641 binary data. If this binary data contains bytes 16#0A# (@code{LF}) or
12642 16#0C# (@code{FF}), the resulting file may have non-standard
12643 format. Similarly if read operations are used to read from a Text_IO
12644 file treated as a stream, then @code{LF} and @code{FF} characters may be
12645 skipped and the effect is similar to that described above for
12646 @code{Get_Immediate}.
12648 @node Text_IO Extensions
12649 @subsection Text_IO Extensions
12650 @cindex Text_IO extensions
12653 A package GNAT.IO_Aux in the GNAT library provides some useful extensions
12654 to the standard @code{Text_IO} package:
12657 @item function File_Exists (Name : String) return Boolean;
12658 Determines if a file of the given name exists.
12660 @item function Get_Line return String;
12661 Reads a string from the standard input file. The value returned is exactly
12662 the length of the line that was read.
12664 @item function Get_Line (File : Ada.Text_IO.File_Type) return String;
12665 Similar, except that the parameter File specifies the file from which
12666 the string is to be read.
12670 @node Text_IO Facilities for Unbounded Strings
12671 @subsection Text_IO Facilities for Unbounded Strings
12672 @cindex Text_IO for unbounded strings
12673 @cindex Unbounded_String, Text_IO operations
12676 The package @code{Ada.Strings.Unbounded.Text_IO}
12677 in library files @code{a-suteio.ads/adb} contains some GNAT-specific
12678 subprograms useful for Text_IO operations on unbounded strings:
12682 @item function Get_Line (File : File_Type) return Unbounded_String;
12683 Reads a line from the specified file
12684 and returns the result as an unbounded string.
12686 @item procedure Put (File : File_Type; U : Unbounded_String);
12687 Writes the value of the given unbounded string to the specified file
12688 Similar to the effect of
12689 @code{Put (To_String (U))} except that an extra copy is avoided.
12691 @item procedure Put_Line (File : File_Type; U : Unbounded_String);
12692 Writes the value of the given unbounded string to the specified file,
12693 followed by a @code{New_Line}.
12694 Similar to the effect of @code{Put_Line (To_String (U))} except
12695 that an extra copy is avoided.
12699 In the above procedures, @code{File} is of type @code{Ada.Text_IO.File_Type}
12700 and is optional. If the parameter is omitted, then the standard input or
12701 output file is referenced as appropriate.
12703 The package @code{Ada.Strings.Wide_Unbounded.Wide_Text_IO} in library
12704 files @file{a-swuwti.ads} and @file{a-swuwti.adb} provides similar extended
12705 @code{Wide_Text_IO} functionality for unbounded wide strings.
12707 The package @code{Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO} in library
12708 files @file{a-szuzti.ads} and @file{a-szuzti.adb} provides similar extended
12709 @code{Wide_Wide_Text_IO} functionality for unbounded wide wide strings.
12712 @section Wide_Text_IO
12715 @code{Wide_Text_IO} is similar in most respects to Text_IO, except that
12716 both input and output files may contain special sequences that represent
12717 wide character values. The encoding scheme for a given file may be
12718 specified using a FORM parameter:
12725 as part of the FORM string (WCEM = wide character encoding method),
12726 where @var{x} is one of the following characters
12732 Upper half encoding
12744 The encoding methods match those that
12745 can be used in a source
12746 program, but there is no requirement that the encoding method used for
12747 the source program be the same as the encoding method used for files,
12748 and different files may use different encoding methods.
12750 The default encoding method for the standard files, and for opened files
12751 for which no WCEM parameter is given in the FORM string matches the
12752 wide character encoding specified for the main program (the default
12753 being brackets encoding if no coding method was specified with -gnatW).
12757 In this encoding, a wide character is represented by a five character
12765 where @var{a}, @var{b}, @var{c}, @var{d} are the four hexadecimal
12766 characters (using upper case letters) of the wide character code. For
12767 example, ESC A345 is used to represent the wide character with code
12768 16#A345#. This scheme is compatible with use of the full
12769 @code{Wide_Character} set.
12771 @item Upper Half Coding
12772 The wide character with encoding 16#abcd#, where the upper bit is on
12773 (i.e.@: a is in the range 8-F) is represented as two bytes 16#ab# and
12774 16#cd#. The second byte may never be a format control character, but is
12775 not required to be in the upper half. This method can be also used for
12776 shift-JIS or EUC where the internal coding matches the external coding.
12778 @item Shift JIS Coding
12779 A wide character is represented by a two character sequence 16#ab# and
12780 16#cd#, with the restrictions described for upper half encoding as
12781 described above. The internal character code is the corresponding JIS
12782 character according to the standard algorithm for Shift-JIS
12783 conversion. Only characters defined in the JIS code set table can be
12784 used with this encoding method.
12787 A wide character is represented by a two character sequence 16#ab# and
12788 16#cd#, with both characters being in the upper half. The internal
12789 character code is the corresponding JIS character according to the EUC
12790 encoding algorithm. Only characters defined in the JIS code set table
12791 can be used with this encoding method.
12794 A wide character is represented using
12795 UCS Transformation Format 8 (UTF-8) as defined in Annex R of ISO
12796 10646-1/Am.2. Depending on the character value, the representation
12797 is a one, two, or three byte sequence:
12800 16#0000#-16#007f#: 2#0xxxxxxx#
12801 16#0080#-16#07ff#: 2#110xxxxx# 2#10xxxxxx#
12802 16#0800#-16#ffff#: 2#1110xxxx# 2#10xxxxxx# 2#10xxxxxx#
12806 where the @var{xxx} bits correspond to the left-padded bits of the
12807 16-bit character value. Note that all lower half ASCII characters
12808 are represented as ASCII bytes and all upper half characters and
12809 other wide characters are represented as sequences of upper-half
12810 (The full UTF-8 scheme allows for encoding 31-bit characters as
12811 6-byte sequences, but in this implementation, all UTF-8 sequences
12812 of four or more bytes length will raise a Constraint_Error, as
12813 will all invalid UTF-8 sequences.)
12815 @item Brackets Coding
12816 In this encoding, a wide character is represented by the following eight
12817 character sequence:
12824 where @code{a}, @code{b}, @code{c}, @code{d} are the four hexadecimal
12825 characters (using uppercase letters) of the wide character code. For
12826 example, @code{["A345"]} is used to represent the wide character with code
12828 This scheme is compatible with use of the full Wide_Character set.
12829 On input, brackets coding can also be used for upper half characters,
12830 e.g.@: @code{["C1"]} for lower case a. However, on output, brackets notation
12831 is only used for wide characters with a code greater than @code{16#FF#}.
12833 Note that brackets coding is not normally used in the context of
12834 Wide_Text_IO or Wide_Wide_Text_IO, since it is really just designed as
12835 a portable way of encoding source files. In the context of Wide_Text_IO
12836 or Wide_Wide_Text_IO, it can only be used if the file does not contain
12837 any instance of the left bracket character other than to encode wide
12838 character values using the brackets encoding method. In practice it is
12839 expected that some standard wide character encoding method such
12840 as UTF-8 will be used for text input output.
12842 If brackets notation is used, then any occurrence of a left bracket
12843 in the input file which is not the start of a valid wide character
12844 sequence will cause Constraint_Error to be raised. It is possible to
12845 encode a left bracket as ["5B"] and Wide_Text_IO and Wide_Wide_Text_IO
12846 input will interpret this as a left bracket.
12848 However, when a left bracket is output, it will be output as a left bracket
12849 and not as ["5B"]. We make this decision because for normal use of
12850 Wide_Text_IO for outputting messages, it is unpleasant to clobber left
12851 brackets. For example, if we write:
12854 Put_Line ("Start of output [first run]");
12858 we really do not want to have the left bracket in this message clobbered so
12859 that the output reads:
12862 Start of output ["5B"]first run]
12866 In practice brackets encoding is reasonably useful for normal Put_Line use
12867 since we won't get confused between left brackets and wide character
12868 sequences in the output. But for input, or when files are written out
12869 and read back in, it really makes better sense to use one of the standard
12870 encoding methods such as UTF-8.
12875 For the coding schemes other than UTF-8, Hex, or Brackets encoding,
12876 not all wide character
12877 values can be represented. An attempt to output a character that cannot
12878 be represented using the encoding scheme for the file causes
12879 Constraint_Error to be raised. An invalid wide character sequence on
12880 input also causes Constraint_Error to be raised.
12883 * Wide_Text_IO Stream Pointer Positioning::
12884 * Wide_Text_IO Reading and Writing Non-Regular Files::
12887 @node Wide_Text_IO Stream Pointer Positioning
12888 @subsection Stream Pointer Positioning
12891 @code{Ada.Wide_Text_IO} is similar to @code{Ada.Text_IO} in its handling
12892 of stream pointer positioning (@pxref{Text_IO}). There is one additional
12895 If @code{Ada.Wide_Text_IO.Look_Ahead} reads a character outside the
12896 normal lower ASCII set (i.e.@: a character in the range:
12898 @smallexample @c ada
12899 Wide_Character'Val (16#0080#) .. Wide_Character'Val (16#FFFF#)
12903 then although the logical position of the file pointer is unchanged by
12904 the @code{Look_Ahead} call, the stream is physically positioned past the
12905 wide character sequence. Again this is to avoid the need for buffering
12906 or backup, and all @code{Wide_Text_IO} routines check the internal
12907 indication that this situation has occurred so that this is not visible
12908 to a normal program using @code{Wide_Text_IO}. However, this discrepancy
12909 can be observed if the wide text file shares a stream with another file.
12911 @node Wide_Text_IO Reading and Writing Non-Regular Files
12912 @subsection Reading and Writing Non-Regular Files
12915 As in the case of Text_IO, when a non-regular file is read, it is
12916 assumed that the file contains no page marks (any form characters are
12917 treated as data characters), and @code{End_Of_Page} always returns
12918 @code{False}. Similarly, the end of file indication is not sticky, so
12919 it is possible to read beyond an end of file.
12921 @node Wide_Wide_Text_IO
12922 @section Wide_Wide_Text_IO
12925 @code{Wide_Wide_Text_IO} is similar in most respects to Text_IO, except that
12926 both input and output files may contain special sequences that represent
12927 wide wide character values. The encoding scheme for a given file may be
12928 specified using a FORM parameter:
12935 as part of the FORM string (WCEM = wide character encoding method),
12936 where @var{x} is one of the following characters
12942 Upper half encoding
12954 The encoding methods match those that
12955 can be used in a source
12956 program, but there is no requirement that the encoding method used for
12957 the source program be the same as the encoding method used for files,
12958 and different files may use different encoding methods.
12960 The default encoding method for the standard files, and for opened files
12961 for which no WCEM parameter is given in the FORM string matches the
12962 wide character encoding specified for the main program (the default
12963 being brackets encoding if no coding method was specified with -gnatW).
12968 A wide character is represented using
12969 UCS Transformation Format 8 (UTF-8) as defined in Annex R of ISO
12970 10646-1/Am.2. Depending on the character value, the representation
12971 is a one, two, three, or four byte sequence:
12974 16#000000#-16#00007f#: 2#0xxxxxxx#
12975 16#000080#-16#0007ff#: 2#110xxxxx# 2#10xxxxxx#
12976 16#000800#-16#00ffff#: 2#1110xxxx# 2#10xxxxxx# 2#10xxxxxx#
12977 16#010000#-16#10ffff#: 2#11110xxx# 2#10xxxxxx# 2#10xxxxxx# 2#10xxxxxx#
12981 where the @var{xxx} bits correspond to the left-padded bits of the
12982 21-bit character value. Note that all lower half ASCII characters
12983 are represented as ASCII bytes and all upper half characters and
12984 other wide characters are represented as sequences of upper-half
12987 @item Brackets Coding
12988 In this encoding, a wide wide character is represented by the following eight
12989 character sequence if is in wide character range
12995 and by the following ten character sequence if not
12998 [ " a b c d e f " ]
13002 where @code{a}, @code{b}, @code{c}, @code{d}, @code{e}, and @code{f}
13003 are the four or six hexadecimal
13004 characters (using uppercase letters) of the wide wide character code. For
13005 example, @code{["01A345"]} is used to represent the wide wide character
13006 with code @code{16#01A345#}.
13008 This scheme is compatible with use of the full Wide_Wide_Character set.
13009 On input, brackets coding can also be used for upper half characters,
13010 e.g.@: @code{["C1"]} for lower case a. However, on output, brackets notation
13011 is only used for wide characters with a code greater than @code{16#FF#}.
13016 If is also possible to use the other Wide_Character encoding methods,
13017 such as Shift-JIS, but the other schemes cannot support the full range
13018 of wide wide characters.
13019 An attempt to output a character that cannot
13020 be represented using the encoding scheme for the file causes
13021 Constraint_Error to be raised. An invalid wide character sequence on
13022 input also causes Constraint_Error to be raised.
13025 * Wide_Wide_Text_IO Stream Pointer Positioning::
13026 * Wide_Wide_Text_IO Reading and Writing Non-Regular Files::
13029 @node Wide_Wide_Text_IO Stream Pointer Positioning
13030 @subsection Stream Pointer Positioning
13033 @code{Ada.Wide_Wide_Text_IO} is similar to @code{Ada.Text_IO} in its handling
13034 of stream pointer positioning (@pxref{Text_IO}). There is one additional
13037 If @code{Ada.Wide_Wide_Text_IO.Look_Ahead} reads a character outside the
13038 normal lower ASCII set (i.e.@: a character in the range:
13040 @smallexample @c ada
13041 Wide_Wide_Character'Val (16#0080#) .. Wide_Wide_Character'Val (16#10FFFF#)
13045 then although the logical position of the file pointer is unchanged by
13046 the @code{Look_Ahead} call, the stream is physically positioned past the
13047 wide character sequence. Again this is to avoid the need for buffering
13048 or backup, and all @code{Wide_Wide_Text_IO} routines check the internal
13049 indication that this situation has occurred so that this is not visible
13050 to a normal program using @code{Wide_Wide_Text_IO}. However, this discrepancy
13051 can be observed if the wide text file shares a stream with another file.
13053 @node Wide_Wide_Text_IO Reading and Writing Non-Regular Files
13054 @subsection Reading and Writing Non-Regular Files
13057 As in the case of Text_IO, when a non-regular file is read, it is
13058 assumed that the file contains no page marks (any form characters are
13059 treated as data characters), and @code{End_Of_Page} always returns
13060 @code{False}. Similarly, the end of file indication is not sticky, so
13061 it is possible to read beyond an end of file.
13067 A stream file is a sequence of bytes, where individual elements are
13068 written to the file as described in the Ada Reference Manual. The type
13069 @code{Stream_Element} is simply a byte. There are two ways to read or
13070 write a stream file.
13074 The operations @code{Read} and @code{Write} directly read or write a
13075 sequence of stream elements with no control information.
13078 The stream attributes applied to a stream file transfer data in the
13079 manner described for stream attributes.
13082 @node Text Translation
13083 @section Text Translation
13086 @samp{Text_Translation=@var{xxx}} may be used as the Form parameter
13087 passed to Text_IO.Create and Text_IO.Open:
13088 @samp{Text_Translation=@var{Yes}} is the default, which means to
13089 translate LF to/from CR/LF on Windows systems.
13090 @samp{Text_Translation=@var{No}} disables this translation; i.e. it
13091 uses binary mode. For output files, @samp{Text_Translation=@var{No}}
13092 may be used to create Unix-style files on
13093 Windows. @samp{Text_Translation=@var{xxx}} has no effect on Unix
13097 @section Shared Files
13100 Section A.14 of the Ada Reference Manual allows implementations to
13101 provide a wide variety of behavior if an attempt is made to access the
13102 same external file with two or more internal files.
13104 To provide a full range of functionality, while at the same time
13105 minimizing the problems of portability caused by this implementation
13106 dependence, GNAT handles file sharing as follows:
13110 In the absence of a @samp{shared=@var{xxx}} form parameter, an attempt
13111 to open two or more files with the same full name is considered an error
13112 and is not supported. The exception @code{Use_Error} will be
13113 raised. Note that a file that is not explicitly closed by the program
13114 remains open until the program terminates.
13117 If the form parameter @samp{shared=no} appears in the form string, the
13118 file can be opened or created with its own separate stream identifier,
13119 regardless of whether other files sharing the same external file are
13120 opened. The exact effect depends on how the C stream routines handle
13121 multiple accesses to the same external files using separate streams.
13124 If the form parameter @samp{shared=yes} appears in the form string for
13125 each of two or more files opened using the same full name, the same
13126 stream is shared between these files, and the semantics are as described
13127 in Ada Reference Manual, Section A.14.
13131 When a program that opens multiple files with the same name is ported
13132 from another Ada compiler to GNAT, the effect will be that
13133 @code{Use_Error} is raised.
13135 The documentation of the original compiler and the documentation of the
13136 program should then be examined to determine if file sharing was
13137 expected, and @samp{shared=@var{xxx}} parameters added to @code{Open}
13138 and @code{Create} calls as required.
13140 When a program is ported from GNAT to some other Ada compiler, no
13141 special attention is required unless the @samp{shared=@var{xxx}} form
13142 parameter is used in the program. In this case, you must examine the
13143 documentation of the new compiler to see if it supports the required
13144 file sharing semantics, and form strings modified appropriately. Of
13145 course it may be the case that the program cannot be ported if the
13146 target compiler does not support the required functionality. The best
13147 approach in writing portable code is to avoid file sharing (and hence
13148 the use of the @samp{shared=@var{xxx}} parameter in the form string)
13151 One common use of file sharing in Ada 83 is the use of instantiations of
13152 Sequential_IO on the same file with different types, to achieve
13153 heterogeneous input-output. Although this approach will work in GNAT if
13154 @samp{shared=yes} is specified, it is preferable in Ada to use Stream_IO
13155 for this purpose (using the stream attributes)
13157 @node Filenames encoding
13158 @section Filenames encoding
13161 An encoding form parameter can be used to specify the filename
13162 encoding @samp{encoding=@var{xxx}}.
13166 If the form parameter @samp{encoding=utf8} appears in the form string, the
13167 filename must be encoded in UTF-8.
13170 If the form parameter @samp{encoding=8bits} appears in the form
13171 string, the filename must be a standard 8bits string.
13174 In the absence of a @samp{encoding=@var{xxx}} form parameter, the
13175 encoding is controlled by the @samp{GNAT_CODE_PAGE} environment
13176 variable. And if not set @samp{utf8} is assumed.
13180 The current system Windows ANSI code page.
13185 This encoding form parameter is only supported on the Windows
13186 platform. On the other Operating Systems the run-time is supporting
13190 @section Open Modes
13193 @code{Open} and @code{Create} calls result in a call to @code{fopen}
13194 using the mode shown in the following table:
13197 @center @code{Open} and @code{Create} Call Modes
13199 @b{OPEN } @b{CREATE}
13200 Append_File "r+" "w+"
13202 Out_File (Direct_IO) "r+" "w"
13203 Out_File (all other cases) "w" "w"
13204 Inout_File "r+" "w+"
13208 If text file translation is required, then either @samp{b} or @samp{t}
13209 is added to the mode, depending on the setting of Text. Text file
13210 translation refers to the mapping of CR/LF sequences in an external file
13211 to LF characters internally. This mapping only occurs in DOS and
13212 DOS-like systems, and is not relevant to other systems.
13214 A special case occurs with Stream_IO@. As shown in the above table, the
13215 file is initially opened in @samp{r} or @samp{w} mode for the
13216 @code{In_File} and @code{Out_File} cases. If a @code{Set_Mode} operation
13217 subsequently requires switching from reading to writing or vice-versa,
13218 then the file is reopened in @samp{r+} mode to permit the required operation.
13220 @node Operations on C Streams
13221 @section Operations on C Streams
13222 The package @code{Interfaces.C_Streams} provides an Ada program with direct
13223 access to the C library functions for operations on C streams:
13225 @smallexample @c adanocomment
13226 package Interfaces.C_Streams is
13227 -- Note: the reason we do not use the types that are in
13228 -- Interfaces.C is that we want to avoid dragging in the
13229 -- code in this unit if possible.
13230 subtype chars is System.Address;
13231 -- Pointer to null-terminated array of characters
13232 subtype FILEs is System.Address;
13233 -- Corresponds to the C type FILE*
13234 subtype voids is System.Address;
13235 -- Corresponds to the C type void*
13236 subtype int is Integer;
13237 subtype long is Long_Integer;
13238 -- Note: the above types are subtypes deliberately, and it
13239 -- is part of this spec that the above correspondences are
13240 -- guaranteed. This means that it is legitimate to, for
13241 -- example, use Integer instead of int. We provide these
13242 -- synonyms for clarity, but in some cases it may be
13243 -- convenient to use the underlying types (for example to
13244 -- avoid an unnecessary dependency of a spec on the spec
13246 type size_t is mod 2 ** Standard'Address_Size;
13247 NULL_Stream : constant FILEs;
13248 -- Value returned (NULL in C) to indicate an
13249 -- fdopen/fopen/tmpfile error
13250 ----------------------------------
13251 -- Constants Defined in stdio.h --
13252 ----------------------------------
13253 EOF : constant int;
13254 -- Used by a number of routines to indicate error or
13256 IOFBF : constant int;
13257 IOLBF : constant int;
13258 IONBF : constant int;
13259 -- Used to indicate buffering mode for setvbuf call
13260 SEEK_CUR : constant int;
13261 SEEK_END : constant int;
13262 SEEK_SET : constant int;
13263 -- Used to indicate origin for fseek call
13264 function stdin return FILEs;
13265 function stdout return FILEs;
13266 function stderr return FILEs;
13267 -- Streams associated with standard files
13268 --------------------------
13269 -- Standard C functions --
13270 --------------------------
13271 -- The functions selected below are ones that are
13272 -- available in DOS, OS/2, UNIX and Xenix (but not
13273 -- necessarily in ANSI C). These are very thin interfaces
13274 -- which copy exactly the C headers. For more
13275 -- documentation on these functions, see the Microsoft C
13276 -- "Run-Time Library Reference" (Microsoft Press, 1990,
13277 -- ISBN 1-55615-225-6), which includes useful information
13278 -- on system compatibility.
13279 procedure clearerr (stream : FILEs);
13280 function fclose (stream : FILEs) return int;
13281 function fdopen (handle : int; mode : chars) return FILEs;
13282 function feof (stream : FILEs) return int;
13283 function ferror (stream : FILEs) return int;
13284 function fflush (stream : FILEs) return int;
13285 function fgetc (stream : FILEs) return int;
13286 function fgets (strng : chars; n : int; stream : FILEs)
13288 function fileno (stream : FILEs) return int;
13289 function fopen (filename : chars; Mode : chars)
13291 -- Note: to maintain target independence, use
13292 -- text_translation_required, a boolean variable defined in
13293 -- a-sysdep.c to deal with the target dependent text
13294 -- translation requirement. If this variable is set,
13295 -- then b/t should be appended to the standard mode
13296 -- argument to set the text translation mode off or on
13298 function fputc (C : int; stream : FILEs) return int;
13299 function fputs (Strng : chars; Stream : FILEs) return int;
13316 function ftell (stream : FILEs) return long;
13323 function isatty (handle : int) return int;
13324 procedure mktemp (template : chars);
13325 -- The return value (which is just a pointer to template)
13327 procedure rewind (stream : FILEs);
13328 function rmtmp return int;
13336 function tmpfile return FILEs;
13337 function ungetc (c : int; stream : FILEs) return int;
13338 function unlink (filename : chars) return int;
13339 ---------------------
13340 -- Extra functions --
13341 ---------------------
13342 -- These functions supply slightly thicker bindings than
13343 -- those above. They are derived from functions in the
13344 -- C Run-Time Library, but may do a bit more work than
13345 -- just directly calling one of the Library functions.
13346 function is_regular_file (handle : int) return int;
13347 -- Tests if given handle is for a regular file (result 1)
13348 -- or for a non-regular file (pipe or device, result 0).
13349 ---------------------------------
13350 -- Control of Text/Binary Mode --
13351 ---------------------------------
13352 -- If text_translation_required is true, then the following
13353 -- functions may be used to dynamically switch a file from
13354 -- binary to text mode or vice versa. These functions have
13355 -- no effect if text_translation_required is false (i.e.@: in
13356 -- normal UNIX mode). Use fileno to get a stream handle.
13357 procedure set_binary_mode (handle : int);
13358 procedure set_text_mode (handle : int);
13359 ----------------------------
13360 -- Full Path Name support --
13361 ----------------------------
13362 procedure full_name (nam : chars; buffer : chars);
13363 -- Given a NUL terminated string representing a file
13364 -- name, returns in buffer a NUL terminated string
13365 -- representing the full path name for the file name.
13366 -- On systems where it is relevant the drive is also
13367 -- part of the full path name. It is the responsibility
13368 -- of the caller to pass an actual parameter for buffer
13369 -- that is big enough for any full path name. Use
13370 -- max_path_len given below as the size of buffer.
13371 max_path_len : integer;
13372 -- Maximum length of an allowable full path name on the
13373 -- system, including a terminating NUL character.
13374 end Interfaces.C_Streams;
13377 @node Interfacing to C Streams
13378 @section Interfacing to C Streams
13381 The packages in this section permit interfacing Ada files to C Stream
13384 @smallexample @c ada
13385 with Interfaces.C_Streams;
13386 package Ada.Sequential_IO.C_Streams is
13387 function C_Stream (F : File_Type)
13388 return Interfaces.C_Streams.FILEs;
13390 (File : in out File_Type;
13391 Mode : in File_Mode;
13392 C_Stream : in Interfaces.C_Streams.FILEs;
13393 Form : in String := "");
13394 end Ada.Sequential_IO.C_Streams;
13396 with Interfaces.C_Streams;
13397 package Ada.Direct_IO.C_Streams is
13398 function C_Stream (F : File_Type)
13399 return Interfaces.C_Streams.FILEs;
13401 (File : in out File_Type;
13402 Mode : in File_Mode;
13403 C_Stream : in Interfaces.C_Streams.FILEs;
13404 Form : in String := "");
13405 end Ada.Direct_IO.C_Streams;
13407 with Interfaces.C_Streams;
13408 package Ada.Text_IO.C_Streams is
13409 function C_Stream (F : File_Type)
13410 return Interfaces.C_Streams.FILEs;
13412 (File : in out File_Type;
13413 Mode : in File_Mode;
13414 C_Stream : in Interfaces.C_Streams.FILEs;
13415 Form : in String := "");
13416 end Ada.Text_IO.C_Streams;
13418 with Interfaces.C_Streams;
13419 package Ada.Wide_Text_IO.C_Streams is
13420 function C_Stream (F : File_Type)
13421 return Interfaces.C_Streams.FILEs;
13423 (File : in out File_Type;
13424 Mode : in File_Mode;
13425 C_Stream : in Interfaces.C_Streams.FILEs;
13426 Form : in String := "");
13427 end Ada.Wide_Text_IO.C_Streams;
13429 with Interfaces.C_Streams;
13430 package Ada.Wide_Wide_Text_IO.C_Streams is
13431 function C_Stream (F : File_Type)
13432 return Interfaces.C_Streams.FILEs;
13434 (File : in out File_Type;
13435 Mode : in File_Mode;
13436 C_Stream : in Interfaces.C_Streams.FILEs;
13437 Form : in String := "");
13438 end Ada.Wide_Wide_Text_IO.C_Streams;
13440 with Interfaces.C_Streams;
13441 package Ada.Stream_IO.C_Streams is
13442 function C_Stream (F : File_Type)
13443 return Interfaces.C_Streams.FILEs;
13445 (File : in out File_Type;
13446 Mode : in File_Mode;
13447 C_Stream : in Interfaces.C_Streams.FILEs;
13448 Form : in String := "");
13449 end Ada.Stream_IO.C_Streams;
13453 In each of these six packages, the @code{C_Stream} function obtains the
13454 @code{FILE} pointer from a currently opened Ada file. It is then
13455 possible to use the @code{Interfaces.C_Streams} package to operate on
13456 this stream, or the stream can be passed to a C program which can
13457 operate on it directly. Of course the program is responsible for
13458 ensuring that only appropriate sequences of operations are executed.
13460 One particular use of relevance to an Ada program is that the
13461 @code{setvbuf} function can be used to control the buffering of the
13462 stream used by an Ada file. In the absence of such a call the standard
13463 default buffering is used.
13465 The @code{Open} procedures in these packages open a file giving an
13466 existing C Stream instead of a file name. Typically this stream is
13467 imported from a C program, allowing an Ada file to operate on an
13470 @node The GNAT Library
13471 @chapter The GNAT Library
13474 The GNAT library contains a number of general and special purpose packages.
13475 It represents functionality that the GNAT developers have found useful, and
13476 which is made available to GNAT users. The packages described here are fully
13477 supported, and upwards compatibility will be maintained in future releases,
13478 so you can use these facilities with the confidence that the same functionality
13479 will be available in future releases.
13481 The chapter here simply gives a brief summary of the facilities available.
13482 The full documentation is found in the spec file for the package. The full
13483 sources of these library packages, including both spec and body, are provided
13484 with all GNAT releases. For example, to find out the full specifications of
13485 the SPITBOL pattern matching capability, including a full tutorial and
13486 extensive examples, look in the @file{g-spipat.ads} file in the library.
13488 For each entry here, the package name (as it would appear in a @code{with}
13489 clause) is given, followed by the name of the corresponding spec file in
13490 parentheses. The packages are children in four hierarchies, @code{Ada},
13491 @code{Interfaces}, @code{System}, and @code{GNAT}, the latter being a
13492 GNAT-specific hierarchy.
13494 Note that an application program should only use packages in one of these
13495 four hierarchies if the package is defined in the Ada Reference Manual,
13496 or is listed in this section of the GNAT Programmers Reference Manual.
13497 All other units should be considered internal implementation units and
13498 should not be directly @code{with}'ed by application code. The use of
13499 a @code{with} statement that references one of these internal implementation
13500 units makes an application potentially dependent on changes in versions
13501 of GNAT, and will generate a warning message.
13504 * Ada.Characters.Latin_9 (a-chlat9.ads)::
13505 * Ada.Characters.Wide_Latin_1 (a-cwila1.ads)::
13506 * Ada.Characters.Wide_Latin_9 (a-cwila9.ads)::
13507 * Ada.Characters.Wide_Wide_Latin_1 (a-chzla1.ads)::
13508 * Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads)::
13509 * Ada.Command_Line.Environment (a-colien.ads)::
13510 * Ada.Command_Line.Remove (a-colire.ads)::
13511 * Ada.Command_Line.Response_File (a-clrefi.ads)::
13512 * Ada.Direct_IO.C_Streams (a-diocst.ads)::
13513 * Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads)::
13514 * Ada.Exceptions.Last_Chance_Handler (a-elchha.ads)::
13515 * Ada.Exceptions.Traceback (a-exctra.ads)::
13516 * Ada.Sequential_IO.C_Streams (a-siocst.ads)::
13517 * Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads)::
13518 * Ada.Strings.Unbounded.Text_IO (a-suteio.ads)::
13519 * Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads)::
13520 * Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads)::
13521 * Ada.Text_IO.C_Streams (a-tiocst.ads)::
13522 * Ada.Text_IO.Reset_Standard_Files (a-tirsfi.ads)::
13523 * Ada.Wide_Characters.Unicode (a-wichun.ads)::
13524 * Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads)::
13525 * Ada.Wide_Text_IO.Reset_Standard_Files (a-wrstfi.ads)::
13526 * Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads)::
13527 * Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads)::
13528 * Ada.Wide_Wide_Text_IO.Reset_Standard_Files (a-zrstfi.ads)::
13529 * GNAT.Altivec (g-altive.ads)::
13530 * GNAT.Altivec.Conversions (g-altcon.ads)::
13531 * GNAT.Altivec.Vector_Operations (g-alveop.ads)::
13532 * GNAT.Altivec.Vector_Types (g-alvety.ads)::
13533 * GNAT.Altivec.Vector_Views (g-alvevi.ads)::
13534 * GNAT.Array_Split (g-arrspl.ads)::
13535 * GNAT.AWK (g-awk.ads)::
13536 * GNAT.Bounded_Buffers (g-boubuf.ads)::
13537 * GNAT.Bounded_Mailboxes (g-boumai.ads)::
13538 * GNAT.Bubble_Sort (g-bubsor.ads)::
13539 * GNAT.Bubble_Sort_A (g-busora.ads)::
13540 * GNAT.Bubble_Sort_G (g-busorg.ads)::
13541 * GNAT.Byte_Order_Mark (g-byorma.ads)::
13542 * GNAT.Byte_Swapping (g-bytswa.ads)::
13543 * GNAT.Calendar (g-calend.ads)::
13544 * GNAT.Calendar.Time_IO (g-catiio.ads)::
13545 * GNAT.Case_Util (g-casuti.ads)::
13546 * GNAT.CGI (g-cgi.ads)::
13547 * GNAT.CGI.Cookie (g-cgicoo.ads)::
13548 * GNAT.CGI.Debug (g-cgideb.ads)::
13549 * GNAT.Command_Line (g-comlin.ads)::
13550 * GNAT.Compiler_Version (g-comver.ads)::
13551 * GNAT.Ctrl_C (g-ctrl_c.ads)::
13552 * GNAT.CRC32 (g-crc32.ads)::
13553 * GNAT.Current_Exception (g-curexc.ads)::
13554 * GNAT.Debug_Pools (g-debpoo.ads)::
13555 * GNAT.Debug_Utilities (g-debuti.ads)::
13556 * GNAT.Decode_String (g-decstr.ads)::
13557 * GNAT.Decode_UTF8_String (g-deutst.ads)::
13558 * GNAT.Directory_Operations (g-dirope.ads)::
13559 * GNAT.Directory_Operations.Iteration (g-diopit.ads)::
13560 * GNAT.Dynamic_HTables (g-dynhta.ads)::
13561 * GNAT.Dynamic_Tables (g-dyntab.ads)::
13562 * GNAT.Encode_String (g-encstr.ads)::
13563 * GNAT.Encode_UTF8_String (g-enutst.ads)::
13564 * GNAT.Exception_Actions (g-excact.ads)::
13565 * GNAT.Exception_Traces (g-exctra.ads)::
13566 * GNAT.Exceptions (g-except.ads)::
13567 * GNAT.Expect (g-expect.ads)::
13568 * GNAT.Float_Control (g-flocon.ads)::
13569 * GNAT.Heap_Sort (g-heasor.ads)::
13570 * GNAT.Heap_Sort_A (g-hesora.ads)::
13571 * GNAT.Heap_Sort_G (g-hesorg.ads)::
13572 * GNAT.HTable (g-htable.ads)::
13573 * GNAT.IO (g-io.ads)::
13574 * GNAT.IO_Aux (g-io_aux.ads)::
13575 * GNAT.Lock_Files (g-locfil.ads)::
13576 * GNAT.MD5 (g-md5.ads)::
13577 * GNAT.Memory_Dump (g-memdum.ads)::
13578 * GNAT.Most_Recent_Exception (g-moreex.ads)::
13579 * GNAT.OS_Lib (g-os_lib.ads)::
13580 * GNAT.Perfect_Hash_Generators (g-pehage.ads)::
13581 * GNAT.Random_Numbers (g-rannum.ads)::
13582 * GNAT.Regexp (g-regexp.ads)::
13583 * GNAT.Registry (g-regist.ads)::
13584 * GNAT.Regpat (g-regpat.ads)::
13585 * GNAT.Secondary_Stack_Info (g-sestin.ads)::
13586 * GNAT.Semaphores (g-semaph.ads)::
13587 * GNAT.Serial_Communications (g-sercom.ads)::
13588 * GNAT.SHA1 (g-sha1.ads)::
13589 * GNAT.Signals (g-signal.ads)::
13590 * GNAT.Sockets (g-socket.ads)::
13591 * GNAT.Source_Info (g-souinf.ads)::
13592 * GNAT.Spelling_Checker (g-speche.ads)::
13593 * GNAT.Spelling_Checker_Generic (g-spchge.ads)::
13594 * GNAT.Spitbol.Patterns (g-spipat.ads)::
13595 * GNAT.Spitbol (g-spitbo.ads)::
13596 * GNAT.Spitbol.Table_Boolean (g-sptabo.ads)::
13597 * GNAT.Spitbol.Table_Integer (g-sptain.ads)::
13598 * GNAT.Spitbol.Table_VString (g-sptavs.ads)::
13599 * GNAT.SSE (g-sse.ads)::
13600 * GNAT.SSE.Vector_Types (g-ssvety.ads)::
13601 * GNAT.Strings (g-string.ads)::
13602 * GNAT.String_Split (g-strspl.ads)::
13603 * GNAT.Table (g-table.ads)::
13604 * GNAT.Task_Lock (g-tasloc.ads)::
13605 * GNAT.Threads (g-thread.ads)::
13606 * GNAT.Time_Stamp (g-timsta.ads)::
13607 * GNAT.Traceback (g-traceb.ads)::
13608 * GNAT.Traceback.Symbolic (g-trasym.ads)::
13609 * GNAT.UTF_32 (g-utf_32.ads)::
13610 * GNAT.UTF_32_Spelling_Checker (g-u3spch.ads)::
13611 * GNAT.Wide_Spelling_Checker (g-wispch.ads)::
13612 * GNAT.Wide_String_Split (g-wistsp.ads)::
13613 * GNAT.Wide_Wide_Spelling_Checker (g-zspche.ads)::
13614 * GNAT.Wide_Wide_String_Split (g-zistsp.ads)::
13615 * Interfaces.C.Extensions (i-cexten.ads)::
13616 * Interfaces.C.Streams (i-cstrea.ads)::
13617 * Interfaces.CPP (i-cpp.ads)::
13618 * Interfaces.Packed_Decimal (i-pacdec.ads)::
13619 * Interfaces.VxWorks (i-vxwork.ads)::
13620 * Interfaces.VxWorks.IO (i-vxwoio.ads)::
13621 * System.Address_Image (s-addima.ads)::
13622 * System.Assertions (s-assert.ads)::
13623 * System.Memory (s-memory.ads)::
13624 * System.Partition_Interface (s-parint.ads)::
13625 * System.Pool_Global (s-pooglo.ads)::
13626 * System.Pool_Local (s-pooloc.ads)::
13627 * System.Restrictions (s-restri.ads)::
13628 * System.Rident (s-rident.ads)::
13629 * System.Strings.Stream_Ops (s-ststop.ads)::
13630 * System.Task_Info (s-tasinf.ads)::
13631 * System.Wch_Cnv (s-wchcnv.ads)::
13632 * System.Wch_Con (s-wchcon.ads)::
13635 @node Ada.Characters.Latin_9 (a-chlat9.ads)
13636 @section @code{Ada.Characters.Latin_9} (@file{a-chlat9.ads})
13637 @cindex @code{Ada.Characters.Latin_9} (@file{a-chlat9.ads})
13638 @cindex Latin_9 constants for Character
13641 This child of @code{Ada.Characters}
13642 provides a set of definitions corresponding to those in the
13643 RM-defined package @code{Ada.Characters.Latin_1} but with the
13644 few modifications required for @code{Latin-9}
13645 The provision of such a package
13646 is specifically authorized by the Ada Reference Manual
13649 @node Ada.Characters.Wide_Latin_1 (a-cwila1.ads)
13650 @section @code{Ada.Characters.Wide_Latin_1} (@file{a-cwila1.ads})
13651 @cindex @code{Ada.Characters.Wide_Latin_1} (@file{a-cwila1.ads})
13652 @cindex Latin_1 constants for Wide_Character
13655 This child of @code{Ada.Characters}
13656 provides a set of definitions corresponding to those in the
13657 RM-defined package @code{Ada.Characters.Latin_1} but with the
13658 types of the constants being @code{Wide_Character}
13659 instead of @code{Character}. The provision of such a package
13660 is specifically authorized by the Ada Reference Manual
13663 @node Ada.Characters.Wide_Latin_9 (a-cwila9.ads)
13664 @section @code{Ada.Characters.Wide_Latin_9} (@file{a-cwila1.ads})
13665 @cindex @code{Ada.Characters.Wide_Latin_9} (@file{a-cwila1.ads})
13666 @cindex Latin_9 constants for Wide_Character
13669 This child of @code{Ada.Characters}
13670 provides a set of definitions corresponding to those in the
13671 GNAT defined package @code{Ada.Characters.Latin_9} but with the
13672 types of the constants being @code{Wide_Character}
13673 instead of @code{Character}. The provision of such a package
13674 is specifically authorized by the Ada Reference Manual
13677 @node Ada.Characters.Wide_Wide_Latin_1 (a-chzla1.ads)
13678 @section @code{Ada.Characters.Wide_Wide_Latin_1} (@file{a-chzla1.ads})
13679 @cindex @code{Ada.Characters.Wide_Wide_Latin_1} (@file{a-chzla1.ads})
13680 @cindex Latin_1 constants for Wide_Wide_Character
13683 This child of @code{Ada.Characters}
13684 provides a set of definitions corresponding to those in the
13685 RM-defined package @code{Ada.Characters.Latin_1} but with the
13686 types of the constants being @code{Wide_Wide_Character}
13687 instead of @code{Character}. The provision of such a package
13688 is specifically authorized by the Ada Reference Manual
13691 @node Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads)
13692 @section @code{Ada.Characters.Wide_Wide_Latin_9} (@file{a-chzla9.ads})
13693 @cindex @code{Ada.Characters.Wide_Wide_Latin_9} (@file{a-chzla9.ads})
13694 @cindex Latin_9 constants for Wide_Wide_Character
13697 This child of @code{Ada.Characters}
13698 provides a set of definitions corresponding to those in the
13699 GNAT defined package @code{Ada.Characters.Latin_9} but with the
13700 types of the constants being @code{Wide_Wide_Character}
13701 instead of @code{Character}. The provision of such a package
13702 is specifically authorized by the Ada Reference Manual
13705 @node Ada.Command_Line.Environment (a-colien.ads)
13706 @section @code{Ada.Command_Line.Environment} (@file{a-colien.ads})
13707 @cindex @code{Ada.Command_Line.Environment} (@file{a-colien.ads})
13708 @cindex Environment entries
13711 This child of @code{Ada.Command_Line}
13712 provides a mechanism for obtaining environment values on systems
13713 where this concept makes sense.
13715 @node Ada.Command_Line.Remove (a-colire.ads)
13716 @section @code{Ada.Command_Line.Remove} (@file{a-colire.ads})
13717 @cindex @code{Ada.Command_Line.Remove} (@file{a-colire.ads})
13718 @cindex Removing command line arguments
13719 @cindex Command line, argument removal
13722 This child of @code{Ada.Command_Line}
13723 provides a mechanism for logically removing
13724 arguments from the argument list. Once removed, an argument is not visible
13725 to further calls on the subprograms in @code{Ada.Command_Line} will not
13726 see the removed argument.
13728 @node Ada.Command_Line.Response_File (a-clrefi.ads)
13729 @section @code{Ada.Command_Line.Response_File} (@file{a-clrefi.ads})
13730 @cindex @code{Ada.Command_Line.Response_File} (@file{a-clrefi.ads})
13731 @cindex Response file for command line
13732 @cindex Command line, response file
13733 @cindex Command line, handling long command lines
13736 This child of @code{Ada.Command_Line} provides a mechanism facilities for
13737 getting command line arguments from a text file, called a "response file".
13738 Using a response file allow passing a set of arguments to an executable longer
13739 than the maximum allowed by the system on the command line.
13741 @node Ada.Direct_IO.C_Streams (a-diocst.ads)
13742 @section @code{Ada.Direct_IO.C_Streams} (@file{a-diocst.ads})
13743 @cindex @code{Ada.Direct_IO.C_Streams} (@file{a-diocst.ads})
13744 @cindex C Streams, Interfacing with Direct_IO
13747 This package provides subprograms that allow interfacing between
13748 C streams and @code{Direct_IO}. The stream identifier can be
13749 extracted from a file opened on the Ada side, and an Ada file
13750 can be constructed from a stream opened on the C side.
13752 @node Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads)
13753 @section @code{Ada.Exceptions.Is_Null_Occurrence} (@file{a-einuoc.ads})
13754 @cindex @code{Ada.Exceptions.Is_Null_Occurrence} (@file{a-einuoc.ads})
13755 @cindex Null_Occurrence, testing for
13758 This child subprogram provides a way of testing for the null
13759 exception occurrence (@code{Null_Occurrence}) without raising
13762 @node Ada.Exceptions.Last_Chance_Handler (a-elchha.ads)
13763 @section @code{Ada.Exceptions.Last_Chance_Handler} (@file{a-elchha.ads})
13764 @cindex @code{Ada.Exceptions.Last_Chance_Handler} (@file{a-elchha.ads})
13765 @cindex Null_Occurrence, testing for
13768 This child subprogram is used for handling otherwise unhandled
13769 exceptions (hence the name last chance), and perform clean ups before
13770 terminating the program. Note that this subprogram never returns.
13772 @node Ada.Exceptions.Traceback (a-exctra.ads)
13773 @section @code{Ada.Exceptions.Traceback} (@file{a-exctra.ads})
13774 @cindex @code{Ada.Exceptions.Traceback} (@file{a-exctra.ads})
13775 @cindex Traceback for Exception Occurrence
13778 This child package provides the subprogram (@code{Tracebacks}) to
13779 give a traceback array of addresses based on an exception
13782 @node Ada.Sequential_IO.C_Streams (a-siocst.ads)
13783 @section @code{Ada.Sequential_IO.C_Streams} (@file{a-siocst.ads})
13784 @cindex @code{Ada.Sequential_IO.C_Streams} (@file{a-siocst.ads})
13785 @cindex C Streams, Interfacing with Sequential_IO
13788 This package provides subprograms that allow interfacing between
13789 C streams and @code{Sequential_IO}. The stream identifier can be
13790 extracted from a file opened on the Ada side, and an Ada file
13791 can be constructed from a stream opened on the C side.
13793 @node Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads)
13794 @section @code{Ada.Streams.Stream_IO.C_Streams} (@file{a-ssicst.ads})
13795 @cindex @code{Ada.Streams.Stream_IO.C_Streams} (@file{a-ssicst.ads})
13796 @cindex C Streams, Interfacing with Stream_IO
13799 This package provides subprograms that allow interfacing between
13800 C streams and @code{Stream_IO}. The stream identifier can be
13801 extracted from a file opened on the Ada side, and an Ada file
13802 can be constructed from a stream opened on the C side.
13804 @node Ada.Strings.Unbounded.Text_IO (a-suteio.ads)
13805 @section @code{Ada.Strings.Unbounded.Text_IO} (@file{a-suteio.ads})
13806 @cindex @code{Ada.Strings.Unbounded.Text_IO} (@file{a-suteio.ads})
13807 @cindex @code{Unbounded_String}, IO support
13808 @cindex @code{Text_IO}, extensions for unbounded strings
13811 This package provides subprograms for Text_IO for unbounded
13812 strings, avoiding the necessity for an intermediate operation
13813 with ordinary strings.
13815 @node Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads)
13816 @section @code{Ada.Strings.Wide_Unbounded.Wide_Text_IO} (@file{a-swuwti.ads})
13817 @cindex @code{Ada.Strings.Wide_Unbounded.Wide_Text_IO} (@file{a-swuwti.ads})
13818 @cindex @code{Unbounded_Wide_String}, IO support
13819 @cindex @code{Text_IO}, extensions for unbounded wide strings
13822 This package provides subprograms for Text_IO for unbounded
13823 wide strings, avoiding the necessity for an intermediate operation
13824 with ordinary wide strings.
13826 @node Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads)
13827 @section @code{Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO} (@file{a-szuzti.ads})
13828 @cindex @code{Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO} (@file{a-szuzti.ads})
13829 @cindex @code{Unbounded_Wide_Wide_String}, IO support
13830 @cindex @code{Text_IO}, extensions for unbounded wide wide strings
13833 This package provides subprograms for Text_IO for unbounded
13834 wide wide strings, avoiding the necessity for an intermediate operation
13835 with ordinary wide wide strings.
13837 @node Ada.Text_IO.C_Streams (a-tiocst.ads)
13838 @section @code{Ada.Text_IO.C_Streams} (@file{a-tiocst.ads})
13839 @cindex @code{Ada.Text_IO.C_Streams} (@file{a-tiocst.ads})
13840 @cindex C Streams, Interfacing with @code{Text_IO}
13843 This package provides subprograms that allow interfacing between
13844 C streams and @code{Text_IO}. The stream identifier can be
13845 extracted from a file opened on the Ada side, and an Ada file
13846 can be constructed from a stream opened on the C side.
13848 @node Ada.Text_IO.Reset_Standard_Files (a-tirsfi.ads)
13849 @section @code{Ada.Text_IO.Reset_Standard_Files} (@file{a-tirsfi.ads})
13850 @cindex @code{Ada.Text_IO.Reset_Standard_Files} (@file{a-tirsfi.ads})
13851 @cindex @code{Text_IO} resetting standard files
13854 This procedure is used to reset the status of the standard files used
13855 by Ada.Text_IO. This is useful in a situation (such as a restart in an
13856 embedded application) where the status of the files may change during
13857 execution (for example a standard input file may be redefined to be
13860 @node Ada.Wide_Characters.Unicode (a-wichun.ads)
13861 @section @code{Ada.Wide_Characters.Unicode} (@file{a-wichun.ads})
13862 @cindex @code{Ada.Wide_Characters.Unicode} (@file{a-wichun.ads})
13863 @cindex Unicode categorization, Wide_Character
13866 This package provides subprograms that allow categorization of
13867 Wide_Character values according to Unicode categories.
13869 @node Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads)
13870 @section @code{Ada.Wide_Text_IO.C_Streams} (@file{a-wtcstr.ads})
13871 @cindex @code{Ada.Wide_Text_IO.C_Streams} (@file{a-wtcstr.ads})
13872 @cindex C Streams, Interfacing with @code{Wide_Text_IO}
13875 This package provides subprograms that allow interfacing between
13876 C streams and @code{Wide_Text_IO}. The stream identifier can be
13877 extracted from a file opened on the Ada side, and an Ada file
13878 can be constructed from a stream opened on the C side.
13880 @node Ada.Wide_Text_IO.Reset_Standard_Files (a-wrstfi.ads)
13881 @section @code{Ada.Wide_Text_IO.Reset_Standard_Files} (@file{a-wrstfi.ads})
13882 @cindex @code{Ada.Wide_Text_IO.Reset_Standard_Files} (@file{a-wrstfi.ads})
13883 @cindex @code{Wide_Text_IO} resetting standard files
13886 This procedure is used to reset the status of the standard files used
13887 by Ada.Wide_Text_IO. This is useful in a situation (such as a restart in an
13888 embedded application) where the status of the files may change during
13889 execution (for example a standard input file may be redefined to be
13892 @node Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads)
13893 @section @code{Ada.Wide_Wide_Characters.Unicode} (@file{a-zchuni.ads})
13894 @cindex @code{Ada.Wide_Wide_Characters.Unicode} (@file{a-zchuni.ads})
13895 @cindex Unicode categorization, Wide_Wide_Character
13898 This package provides subprograms that allow categorization of
13899 Wide_Wide_Character values according to Unicode categories.
13901 @node Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads)
13902 @section @code{Ada.Wide_Wide_Text_IO.C_Streams} (@file{a-ztcstr.ads})
13903 @cindex @code{Ada.Wide_Wide_Text_IO.C_Streams} (@file{a-ztcstr.ads})
13904 @cindex C Streams, Interfacing with @code{Wide_Wide_Text_IO}
13907 This package provides subprograms that allow interfacing between
13908 C streams and @code{Wide_Wide_Text_IO}. The stream identifier can be
13909 extracted from a file opened on the Ada side, and an Ada file
13910 can be constructed from a stream opened on the C side.
13912 @node Ada.Wide_Wide_Text_IO.Reset_Standard_Files (a-zrstfi.ads)
13913 @section @code{Ada.Wide_Wide_Text_IO.Reset_Standard_Files} (@file{a-zrstfi.ads})
13914 @cindex @code{Ada.Wide_Wide_Text_IO.Reset_Standard_Files} (@file{a-zrstfi.ads})
13915 @cindex @code{Wide_Wide_Text_IO} resetting standard files
13918 This procedure is used to reset the status of the standard files used
13919 by Ada.Wide_Wide_Text_IO. This is useful in a situation (such as a
13920 restart in an embedded application) where the status of the files may
13921 change during execution (for example a standard input file may be
13922 redefined to be interactive).
13924 @node GNAT.Altivec (g-altive.ads)
13925 @section @code{GNAT.Altivec} (@file{g-altive.ads})
13926 @cindex @code{GNAT.Altivec} (@file{g-altive.ads})
13930 This is the root package of the GNAT AltiVec binding. It provides
13931 definitions of constants and types common to all the versions of the
13934 @node GNAT.Altivec.Conversions (g-altcon.ads)
13935 @section @code{GNAT.Altivec.Conversions} (@file{g-altcon.ads})
13936 @cindex @code{GNAT.Altivec.Conversions} (@file{g-altcon.ads})
13940 This package provides the Vector/View conversion routines.
13942 @node GNAT.Altivec.Vector_Operations (g-alveop.ads)
13943 @section @code{GNAT.Altivec.Vector_Operations} (@file{g-alveop.ads})
13944 @cindex @code{GNAT.Altivec.Vector_Operations} (@file{g-alveop.ads})
13948 This package exposes the Ada interface to the AltiVec operations on
13949 vector objects. A soft emulation is included by default in the GNAT
13950 library. The hard binding is provided as a separate package. This unit
13951 is common to both bindings.
13953 @node GNAT.Altivec.Vector_Types (g-alvety.ads)
13954 @section @code{GNAT.Altivec.Vector_Types} (@file{g-alvety.ads})
13955 @cindex @code{GNAT.Altivec.Vector_Types} (@file{g-alvety.ads})
13959 This package exposes the various vector types part of the Ada binding
13960 to AltiVec facilities.
13962 @node GNAT.Altivec.Vector_Views (g-alvevi.ads)
13963 @section @code{GNAT.Altivec.Vector_Views} (@file{g-alvevi.ads})
13964 @cindex @code{GNAT.Altivec.Vector_Views} (@file{g-alvevi.ads})
13968 This package provides public 'View' data types from/to which private
13969 vector representations can be converted via
13970 GNAT.Altivec.Conversions. This allows convenient access to individual
13971 vector elements and provides a simple way to initialize vector
13974 @node GNAT.Array_Split (g-arrspl.ads)
13975 @section @code{GNAT.Array_Split} (@file{g-arrspl.ads})
13976 @cindex @code{GNAT.Array_Split} (@file{g-arrspl.ads})
13977 @cindex Array splitter
13980 Useful array-manipulation routines: given a set of separators, split
13981 an array wherever the separators appear, and provide direct access
13982 to the resulting slices.
13984 @node GNAT.AWK (g-awk.ads)
13985 @section @code{GNAT.AWK} (@file{g-awk.ads})
13986 @cindex @code{GNAT.AWK} (@file{g-awk.ads})
13991 Provides AWK-like parsing functions, with an easy interface for parsing one
13992 or more files containing formatted data. The file is viewed as a database
13993 where each record is a line and a field is a data element in this line.
13995 @node GNAT.Bounded_Buffers (g-boubuf.ads)
13996 @section @code{GNAT.Bounded_Buffers} (@file{g-boubuf.ads})
13997 @cindex @code{GNAT.Bounded_Buffers} (@file{g-boubuf.ads})
13999 @cindex Bounded Buffers
14002 Provides a concurrent generic bounded buffer abstraction. Instances are
14003 useful directly or as parts of the implementations of other abstractions,
14006 @node GNAT.Bounded_Mailboxes (g-boumai.ads)
14007 @section @code{GNAT.Bounded_Mailboxes} (@file{g-boumai.ads})
14008 @cindex @code{GNAT.Bounded_Mailboxes} (@file{g-boumai.ads})
14013 Provides a thread-safe asynchronous intertask mailbox communication facility.
14015 @node GNAT.Bubble_Sort (g-bubsor.ads)
14016 @section @code{GNAT.Bubble_Sort} (@file{g-bubsor.ads})
14017 @cindex @code{GNAT.Bubble_Sort} (@file{g-bubsor.ads})
14019 @cindex Bubble sort
14022 Provides a general implementation of bubble sort usable for sorting arbitrary
14023 data items. Exchange and comparison procedures are provided by passing
14024 access-to-procedure values.
14026 @node GNAT.Bubble_Sort_A (g-busora.ads)
14027 @section @code{GNAT.Bubble_Sort_A} (@file{g-busora.ads})
14028 @cindex @code{GNAT.Bubble_Sort_A} (@file{g-busora.ads})
14030 @cindex Bubble sort
14033 Provides a general implementation of bubble sort usable for sorting arbitrary
14034 data items. Move and comparison procedures are provided by passing
14035 access-to-procedure values. This is an older version, retained for
14036 compatibility. Usually @code{GNAT.Bubble_Sort} will be preferable.
14038 @node GNAT.Bubble_Sort_G (g-busorg.ads)
14039 @section @code{GNAT.Bubble_Sort_G} (@file{g-busorg.ads})
14040 @cindex @code{GNAT.Bubble_Sort_G} (@file{g-busorg.ads})
14042 @cindex Bubble sort
14045 Similar to @code{Bubble_Sort_A} except that the move and sorting procedures
14046 are provided as generic parameters, this improves efficiency, especially
14047 if the procedures can be inlined, at the expense of duplicating code for
14048 multiple instantiations.
14050 @node GNAT.Byte_Order_Mark (g-byorma.ads)
14051 @section @code{GNAT.Byte_Order_Mark} (@file{g-byorma.ads})
14052 @cindex @code{GNAT.Byte_Order_Mark} (@file{g-byorma.ads})
14053 @cindex UTF-8 representation
14054 @cindex Wide characte representations
14057 Provides a routine which given a string, reads the start of the string to
14058 see whether it is one of the standard byte order marks (BOM's) which signal
14059 the encoding of the string. The routine includes detection of special XML
14060 sequences for various UCS input formats.
14062 @node GNAT.Byte_Swapping (g-bytswa.ads)
14063 @section @code{GNAT.Byte_Swapping} (@file{g-bytswa.ads})
14064 @cindex @code{GNAT.Byte_Swapping} (@file{g-bytswa.ads})
14065 @cindex Byte swapping
14069 General routines for swapping the bytes in 2-, 4-, and 8-byte quantities.
14070 Machine-specific implementations are available in some cases.
14072 @node GNAT.Calendar (g-calend.ads)
14073 @section @code{GNAT.Calendar} (@file{g-calend.ads})
14074 @cindex @code{GNAT.Calendar} (@file{g-calend.ads})
14075 @cindex @code{Calendar}
14078 Extends the facilities provided by @code{Ada.Calendar} to include handling
14079 of days of the week, an extended @code{Split} and @code{Time_Of} capability.
14080 Also provides conversion of @code{Ada.Calendar.Time} values to and from the
14081 C @code{timeval} format.
14083 @node GNAT.Calendar.Time_IO (g-catiio.ads)
14084 @section @code{GNAT.Calendar.Time_IO} (@file{g-catiio.ads})
14085 @cindex @code{Calendar}
14087 @cindex @code{GNAT.Calendar.Time_IO} (@file{g-catiio.ads})
14089 @node GNAT.CRC32 (g-crc32.ads)
14090 @section @code{GNAT.CRC32} (@file{g-crc32.ads})
14091 @cindex @code{GNAT.CRC32} (@file{g-crc32.ads})
14093 @cindex Cyclic Redundancy Check
14096 This package implements the CRC-32 algorithm. For a full description
14097 of this algorithm see
14098 ``Computation of Cyclic Redundancy Checks via Table Look-Up'',
14099 @cite{Communications of the ACM}, Vol.@: 31 No.@: 8, pp.@: 1008-1013,
14100 Aug.@: 1988. Sarwate, D.V@.
14102 @node GNAT.Case_Util (g-casuti.ads)
14103 @section @code{GNAT.Case_Util} (@file{g-casuti.ads})
14104 @cindex @code{GNAT.Case_Util} (@file{g-casuti.ads})
14105 @cindex Casing utilities
14106 @cindex Character handling (@code{GNAT.Case_Util})
14109 A set of simple routines for handling upper and lower casing of strings
14110 without the overhead of the full casing tables
14111 in @code{Ada.Characters.Handling}.
14113 @node GNAT.CGI (g-cgi.ads)
14114 @section @code{GNAT.CGI} (@file{g-cgi.ads})
14115 @cindex @code{GNAT.CGI} (@file{g-cgi.ads})
14116 @cindex CGI (Common Gateway Interface)
14119 This is a package for interfacing a GNAT program with a Web server via the
14120 Common Gateway Interface (CGI)@. Basically this package parses the CGI
14121 parameters, which are a set of key/value pairs sent by the Web server. It
14122 builds a table whose index is the key and provides some services to deal
14125 @node GNAT.CGI.Cookie (g-cgicoo.ads)
14126 @section @code{GNAT.CGI.Cookie} (@file{g-cgicoo.ads})
14127 @cindex @code{GNAT.CGI.Cookie} (@file{g-cgicoo.ads})
14128 @cindex CGI (Common Gateway Interface) cookie support
14129 @cindex Cookie support in CGI
14132 This is a package to interface a GNAT program with a Web server via the
14133 Common Gateway Interface (CGI). It exports services to deal with Web
14134 cookies (piece of information kept in the Web client software).
14136 @node GNAT.CGI.Debug (g-cgideb.ads)
14137 @section @code{GNAT.CGI.Debug} (@file{g-cgideb.ads})
14138 @cindex @code{GNAT.CGI.Debug} (@file{g-cgideb.ads})
14139 @cindex CGI (Common Gateway Interface) debugging
14142 This is a package to help debugging CGI (Common Gateway Interface)
14143 programs written in Ada.
14145 @node GNAT.Command_Line (g-comlin.ads)
14146 @section @code{GNAT.Command_Line} (@file{g-comlin.ads})
14147 @cindex @code{GNAT.Command_Line} (@file{g-comlin.ads})
14148 @cindex Command line
14151 Provides a high level interface to @code{Ada.Command_Line} facilities,
14152 including the ability to scan for named switches with optional parameters
14153 and expand file names using wild card notations.
14155 @node GNAT.Compiler_Version (g-comver.ads)
14156 @section @code{GNAT.Compiler_Version} (@file{g-comver.ads})
14157 @cindex @code{GNAT.Compiler_Version} (@file{g-comver.ads})
14158 @cindex Compiler Version
14159 @cindex Version, of compiler
14162 Provides a routine for obtaining the version of the compiler used to
14163 compile the program. More accurately this is the version of the binder
14164 used to bind the program (this will normally be the same as the version
14165 of the compiler if a consistent tool set is used to compile all units
14168 @node GNAT.Ctrl_C (g-ctrl_c.ads)
14169 @section @code{GNAT.Ctrl_C} (@file{g-ctrl_c.ads})
14170 @cindex @code{GNAT.Ctrl_C} (@file{g-ctrl_c.ads})
14174 Provides a simple interface to handle Ctrl-C keyboard events.
14176 @node GNAT.Current_Exception (g-curexc.ads)
14177 @section @code{GNAT.Current_Exception} (@file{g-curexc.ads})
14178 @cindex @code{GNAT.Current_Exception} (@file{g-curexc.ads})
14179 @cindex Current exception
14180 @cindex Exception retrieval
14183 Provides access to information on the current exception that has been raised
14184 without the need for using the Ada 95 / Ada 2005 exception choice parameter
14185 specification syntax.
14186 This is particularly useful in simulating typical facilities for
14187 obtaining information about exceptions provided by Ada 83 compilers.
14189 @node GNAT.Debug_Pools (g-debpoo.ads)
14190 @section @code{GNAT.Debug_Pools} (@file{g-debpoo.ads})
14191 @cindex @code{GNAT.Debug_Pools} (@file{g-debpoo.ads})
14193 @cindex Debug pools
14194 @cindex Memory corruption debugging
14197 Provide a debugging storage pools that helps tracking memory corruption
14198 problems. @xref{The GNAT Debug Pool Facility,,, gnat_ugn,
14199 @value{EDITION} User's Guide}.
14201 @node GNAT.Debug_Utilities (g-debuti.ads)
14202 @section @code{GNAT.Debug_Utilities} (@file{g-debuti.ads})
14203 @cindex @code{GNAT.Debug_Utilities} (@file{g-debuti.ads})
14207 Provides a few useful utilities for debugging purposes, including conversion
14208 to and from string images of address values. Supports both C and Ada formats
14209 for hexadecimal literals.
14211 @node GNAT.Decode_String (g-decstr.ads)
14212 @section @code{GNAT.Decode_String} (@file{g-decstr.ads})
14213 @cindex @code{GNAT.Decode_String} (@file{g-decstr.ads})
14214 @cindex Decoding strings
14215 @cindex String decoding
14216 @cindex Wide character encoding
14221 A generic package providing routines for decoding wide character and wide wide
14222 character strings encoded as sequences of 8-bit characters using a specified
14223 encoding method. Includes validation routines, and also routines for stepping
14224 to next or previous encoded character in an encoded string.
14225 Useful in conjunction with Unicode character coding. Note there is a
14226 preinstantiation for UTF-8. See next entry.
14228 @node GNAT.Decode_UTF8_String (g-deutst.ads)
14229 @section @code{GNAT.Decode_UTF8_String} (@file{g-deutst.ads})
14230 @cindex @code{GNAT.Decode_UTF8_String} (@file{g-deutst.ads})
14231 @cindex Decoding strings
14232 @cindex Decoding UTF-8 strings
14233 @cindex UTF-8 string decoding
14234 @cindex Wide character decoding
14239 A preinstantiation of GNAT.Decode_Strings for UTF-8 encoding.
14241 @node GNAT.Directory_Operations (g-dirope.ads)
14242 @section @code{GNAT.Directory_Operations} (@file{g-dirope.ads})
14243 @cindex @code{GNAT.Directory_Operations} (@file{g-dirope.ads})
14244 @cindex Directory operations
14247 Provides a set of routines for manipulating directories, including changing
14248 the current directory, making new directories, and scanning the files in a
14251 @node GNAT.Directory_Operations.Iteration (g-diopit.ads)
14252 @section @code{GNAT.Directory_Operations.Iteration} (@file{g-diopit.ads})
14253 @cindex @code{GNAT.Directory_Operations.Iteration} (@file{g-diopit.ads})
14254 @cindex Directory operations iteration
14257 A child unit of GNAT.Directory_Operations providing additional operations
14258 for iterating through directories.
14260 @node GNAT.Dynamic_HTables (g-dynhta.ads)
14261 @section @code{GNAT.Dynamic_HTables} (@file{g-dynhta.ads})
14262 @cindex @code{GNAT.Dynamic_HTables} (@file{g-dynhta.ads})
14263 @cindex Hash tables
14266 A generic implementation of hash tables that can be used to hash arbitrary
14267 data. Provided in two forms, a simple form with built in hash functions,
14268 and a more complex form in which the hash function is supplied.
14271 This package provides a facility similar to that of @code{GNAT.HTable},
14272 except that this package declares a type that can be used to define
14273 dynamic instances of the hash table, while an instantiation of
14274 @code{GNAT.HTable} creates a single instance of the hash table.
14276 @node GNAT.Dynamic_Tables (g-dyntab.ads)
14277 @section @code{GNAT.Dynamic_Tables} (@file{g-dyntab.ads})
14278 @cindex @code{GNAT.Dynamic_Tables} (@file{g-dyntab.ads})
14279 @cindex Table implementation
14280 @cindex Arrays, extendable
14283 A generic package providing a single dimension array abstraction where the
14284 length of the array can be dynamically modified.
14287 This package provides a facility similar to that of @code{GNAT.Table},
14288 except that this package declares a type that can be used to define
14289 dynamic instances of the table, while an instantiation of
14290 @code{GNAT.Table} creates a single instance of the table type.
14292 @node GNAT.Encode_String (g-encstr.ads)
14293 @section @code{GNAT.Encode_String} (@file{g-encstr.ads})
14294 @cindex @code{GNAT.Encode_String} (@file{g-encstr.ads})
14295 @cindex Encoding strings
14296 @cindex String encoding
14297 @cindex Wide character encoding
14302 A generic package providing routines for encoding wide character and wide
14303 wide character strings as sequences of 8-bit characters using a specified
14304 encoding method. Useful in conjunction with Unicode character coding.
14305 Note there is a preinstantiation for UTF-8. See next entry.
14307 @node GNAT.Encode_UTF8_String (g-enutst.ads)
14308 @section @code{GNAT.Encode_UTF8_String} (@file{g-enutst.ads})
14309 @cindex @code{GNAT.Encode_UTF8_String} (@file{g-enutst.ads})
14310 @cindex Encoding strings
14311 @cindex Encoding UTF-8 strings
14312 @cindex UTF-8 string encoding
14313 @cindex Wide character encoding
14318 A preinstantiation of GNAT.Encode_Strings for UTF-8 encoding.
14320 @node GNAT.Exception_Actions (g-excact.ads)
14321 @section @code{GNAT.Exception_Actions} (@file{g-excact.ads})
14322 @cindex @code{GNAT.Exception_Actions} (@file{g-excact.ads})
14323 @cindex Exception actions
14326 Provides callbacks when an exception is raised. Callbacks can be registered
14327 for specific exceptions, or when any exception is raised. This
14328 can be used for instance to force a core dump to ease debugging.
14330 @node GNAT.Exception_Traces (g-exctra.ads)
14331 @section @code{GNAT.Exception_Traces} (@file{g-exctra.ads})
14332 @cindex @code{GNAT.Exception_Traces} (@file{g-exctra.ads})
14333 @cindex Exception traces
14337 Provides an interface allowing to control automatic output upon exception
14340 @node GNAT.Exceptions (g-except.ads)
14341 @section @code{GNAT.Exceptions} (@file{g-expect.ads})
14342 @cindex @code{GNAT.Exceptions} (@file{g-expect.ads})
14343 @cindex Exceptions, Pure
14344 @cindex Pure packages, exceptions
14347 Normally it is not possible to raise an exception with
14348 a message from a subprogram in a pure package, since the
14349 necessary types and subprograms are in @code{Ada.Exceptions}
14350 which is not a pure unit. @code{GNAT.Exceptions} provides a
14351 facility for getting around this limitation for a few
14352 predefined exceptions, and for example allow raising
14353 @code{Constraint_Error} with a message from a pure subprogram.
14355 @node GNAT.Expect (g-expect.ads)
14356 @section @code{GNAT.Expect} (@file{g-expect.ads})
14357 @cindex @code{GNAT.Expect} (@file{g-expect.ads})
14360 Provides a set of subprograms similar to what is available
14361 with the standard Tcl Expect tool.
14362 It allows you to easily spawn and communicate with an external process.
14363 You can send commands or inputs to the process, and compare the output
14364 with some expected regular expression. Currently @code{GNAT.Expect}
14365 is implemented on all native GNAT ports except for OpenVMS@.
14366 It is not implemented for cross ports, and in particular is not
14367 implemented for VxWorks or LynxOS@.
14369 @node GNAT.Float_Control (g-flocon.ads)
14370 @section @code{GNAT.Float_Control} (@file{g-flocon.ads})
14371 @cindex @code{GNAT.Float_Control} (@file{g-flocon.ads})
14372 @cindex Floating-Point Processor
14375 Provides an interface for resetting the floating-point processor into the
14376 mode required for correct semantic operation in Ada. Some third party
14377 library calls may cause this mode to be modified, and the Reset procedure
14378 in this package can be used to reestablish the required mode.
14380 @node GNAT.Heap_Sort (g-heasor.ads)
14381 @section @code{GNAT.Heap_Sort} (@file{g-heasor.ads})
14382 @cindex @code{GNAT.Heap_Sort} (@file{g-heasor.ads})
14386 Provides a general implementation of heap sort usable for sorting arbitrary
14387 data items. Exchange and comparison procedures are provided by passing
14388 access-to-procedure values. The algorithm used is a modified heap sort
14389 that performs approximately N*log(N) comparisons in the worst case.
14391 @node GNAT.Heap_Sort_A (g-hesora.ads)
14392 @section @code{GNAT.Heap_Sort_A} (@file{g-hesora.ads})
14393 @cindex @code{GNAT.Heap_Sort_A} (@file{g-hesora.ads})
14397 Provides a general implementation of heap sort usable for sorting arbitrary
14398 data items. Move and comparison procedures are provided by passing
14399 access-to-procedure values. The algorithm used is a modified heap sort
14400 that performs approximately N*log(N) comparisons in the worst case.
14401 This differs from @code{GNAT.Heap_Sort} in having a less convenient
14402 interface, but may be slightly more efficient.
14404 @node GNAT.Heap_Sort_G (g-hesorg.ads)
14405 @section @code{GNAT.Heap_Sort_G} (@file{g-hesorg.ads})
14406 @cindex @code{GNAT.Heap_Sort_G} (@file{g-hesorg.ads})
14410 Similar to @code{Heap_Sort_A} except that the move and sorting procedures
14411 are provided as generic parameters, this improves efficiency, especially
14412 if the procedures can be inlined, at the expense of duplicating code for
14413 multiple instantiations.
14415 @node GNAT.HTable (g-htable.ads)
14416 @section @code{GNAT.HTable} (@file{g-htable.ads})
14417 @cindex @code{GNAT.HTable} (@file{g-htable.ads})
14418 @cindex Hash tables
14421 A generic implementation of hash tables that can be used to hash arbitrary
14422 data. Provides two approaches, one a simple static approach, and the other
14423 allowing arbitrary dynamic hash tables.
14425 @node GNAT.IO (g-io.ads)
14426 @section @code{GNAT.IO} (@file{g-io.ads})
14427 @cindex @code{GNAT.IO} (@file{g-io.ads})
14429 @cindex Input/Output facilities
14432 A simple preelaborable input-output package that provides a subset of
14433 simple Text_IO functions for reading characters and strings from
14434 Standard_Input, and writing characters, strings and integers to either
14435 Standard_Output or Standard_Error.
14437 @node GNAT.IO_Aux (g-io_aux.ads)
14438 @section @code{GNAT.IO_Aux} (@file{g-io_aux.ads})
14439 @cindex @code{GNAT.IO_Aux} (@file{g-io_aux.ads})
14441 @cindex Input/Output facilities
14443 Provides some auxiliary functions for use with Text_IO, including a test
14444 for whether a file exists, and functions for reading a line of text.
14446 @node GNAT.Lock_Files (g-locfil.ads)
14447 @section @code{GNAT.Lock_Files} (@file{g-locfil.ads})
14448 @cindex @code{GNAT.Lock_Files} (@file{g-locfil.ads})
14449 @cindex File locking
14450 @cindex Locking using files
14453 Provides a general interface for using files as locks. Can be used for
14454 providing program level synchronization.
14456 @node GNAT.MD5 (g-md5.ads)
14457 @section @code{GNAT.MD5} (@file{g-md5.ads})
14458 @cindex @code{GNAT.MD5} (@file{g-md5.ads})
14459 @cindex Message Digest MD5
14462 Implements the MD5 Message-Digest Algorithm as described in RFC 1321.
14464 @node GNAT.Memory_Dump (g-memdum.ads)
14465 @section @code{GNAT.Memory_Dump} (@file{g-memdum.ads})
14466 @cindex @code{GNAT.Memory_Dump} (@file{g-memdum.ads})
14467 @cindex Dump Memory
14470 Provides a convenient routine for dumping raw memory to either the
14471 standard output or standard error files. Uses GNAT.IO for actual
14474 @node GNAT.Most_Recent_Exception (g-moreex.ads)
14475 @section @code{GNAT.Most_Recent_Exception} (@file{g-moreex.ads})
14476 @cindex @code{GNAT.Most_Recent_Exception} (@file{g-moreex.ads})
14477 @cindex Exception, obtaining most recent
14480 Provides access to the most recently raised exception. Can be used for
14481 various logging purposes, including duplicating functionality of some
14482 Ada 83 implementation dependent extensions.
14484 @node GNAT.OS_Lib (g-os_lib.ads)
14485 @section @code{GNAT.OS_Lib} (@file{g-os_lib.ads})
14486 @cindex @code{GNAT.OS_Lib} (@file{g-os_lib.ads})
14487 @cindex Operating System interface
14488 @cindex Spawn capability
14491 Provides a range of target independent operating system interface functions,
14492 including time/date management, file operations, subprocess management,
14493 including a portable spawn procedure, and access to environment variables
14494 and error return codes.
14496 @node GNAT.Perfect_Hash_Generators (g-pehage.ads)
14497 @section @code{GNAT.Perfect_Hash_Generators} (@file{g-pehage.ads})
14498 @cindex @code{GNAT.Perfect_Hash_Generators} (@file{g-pehage.ads})
14499 @cindex Hash functions
14502 Provides a generator of static minimal perfect hash functions. No
14503 collisions occur and each item can be retrieved from the table in one
14504 probe (perfect property). The hash table size corresponds to the exact
14505 size of the key set and no larger (minimal property). The key set has to
14506 be know in advance (static property). The hash functions are also order
14507 preserving. If w2 is inserted after w1 in the generator, their
14508 hashcode are in the same order. These hashing functions are very
14509 convenient for use with realtime applications.
14511 @node GNAT.Random_Numbers (g-rannum.ads)
14512 @section @code{GNAT.Random_Numbers} (@file{g-rannum.ads})
14513 @cindex @code{GNAT.Random_Numbers} (@file{g-rannum.ads})
14514 @cindex Random number generation
14517 Provides random number capabilities which extend those available in the
14518 standard Ada library and are more convenient to use.
14520 @node GNAT.Regexp (g-regexp.ads)
14521 @section @code{GNAT.Regexp} (@file{g-regexp.ads})
14522 @cindex @code{GNAT.Regexp} (@file{g-regexp.ads})
14523 @cindex Regular expressions
14524 @cindex Pattern matching
14527 A simple implementation of regular expressions, using a subset of regular
14528 expression syntax copied from familiar Unix style utilities. This is the
14529 simples of the three pattern matching packages provided, and is particularly
14530 suitable for ``file globbing'' applications.
14532 @node GNAT.Registry (g-regist.ads)
14533 @section @code{GNAT.Registry} (@file{g-regist.ads})
14534 @cindex @code{GNAT.Registry} (@file{g-regist.ads})
14535 @cindex Windows Registry
14538 This is a high level binding to the Windows registry. It is possible to
14539 do simple things like reading a key value, creating a new key. For full
14540 registry API, but at a lower level of abstraction, refer to the Win32.Winreg
14541 package provided with the Win32Ada binding
14543 @node GNAT.Regpat (g-regpat.ads)
14544 @section @code{GNAT.Regpat} (@file{g-regpat.ads})
14545 @cindex @code{GNAT.Regpat} (@file{g-regpat.ads})
14546 @cindex Regular expressions
14547 @cindex Pattern matching
14550 A complete implementation of Unix-style regular expression matching, copied
14551 from the original V7 style regular expression library written in C by
14552 Henry Spencer (and binary compatible with this C library).
14554 @node GNAT.Secondary_Stack_Info (g-sestin.ads)
14555 @section @code{GNAT.Secondary_Stack_Info} (@file{g-sestin.ads})
14556 @cindex @code{GNAT.Secondary_Stack_Info} (@file{g-sestin.ads})
14557 @cindex Secondary Stack Info
14560 Provide the capability to query the high water mark of the current task's
14563 @node GNAT.Semaphores (g-semaph.ads)
14564 @section @code{GNAT.Semaphores} (@file{g-semaph.ads})
14565 @cindex @code{GNAT.Semaphores} (@file{g-semaph.ads})
14569 Provides classic counting and binary semaphores using protected types.
14571 @node GNAT.Serial_Communications (g-sercom.ads)
14572 @section @code{GNAT.Serial_Communications} (@file{g-sercom.ads})
14573 @cindex @code{GNAT.Serial_Communications} (@file{g-sercom.ads})
14574 @cindex Serial_Communications
14577 Provides a simple interface to send and receive data over a serial
14578 port. This is only supported on GNU/Linux and Windows.
14580 @node GNAT.SHA1 (g-sha1.ads)
14581 @section @code{GNAT.SHA1} (@file{g-sha1.ads})
14582 @cindex @code{GNAT.SHA1} (@file{g-sha1.ads})
14583 @cindex Secure Hash Algorithm SHA-1
14586 Implements the SHA-1 Secure Hash Algorithm as described in RFC 3174.
14588 @node GNAT.Signals (g-signal.ads)
14589 @section @code{GNAT.Signals} (@file{g-signal.ads})
14590 @cindex @code{GNAT.Signals} (@file{g-signal.ads})
14594 Provides the ability to manipulate the blocked status of signals on supported
14597 @node GNAT.Sockets (g-socket.ads)
14598 @section @code{GNAT.Sockets} (@file{g-socket.ads})
14599 @cindex @code{GNAT.Sockets} (@file{g-socket.ads})
14603 A high level and portable interface to develop sockets based applications.
14604 This package is based on the sockets thin binding found in
14605 @code{GNAT.Sockets.Thin}. Currently @code{GNAT.Sockets} is implemented
14606 on all native GNAT ports except for OpenVMS@. It is not implemented
14607 for the LynxOS@ cross port.
14609 @node GNAT.Source_Info (g-souinf.ads)
14610 @section @code{GNAT.Source_Info} (@file{g-souinf.ads})
14611 @cindex @code{GNAT.Source_Info} (@file{g-souinf.ads})
14612 @cindex Source Information
14615 Provides subprograms that give access to source code information known at
14616 compile time, such as the current file name and line number.
14618 @node GNAT.Spelling_Checker (g-speche.ads)
14619 @section @code{GNAT.Spelling_Checker} (@file{g-speche.ads})
14620 @cindex @code{GNAT.Spelling_Checker} (@file{g-speche.ads})
14621 @cindex Spell checking
14624 Provides a function for determining whether one string is a plausible
14625 near misspelling of another string.
14627 @node GNAT.Spelling_Checker_Generic (g-spchge.ads)
14628 @section @code{GNAT.Spelling_Checker_Generic} (@file{g-spchge.ads})
14629 @cindex @code{GNAT.Spelling_Checker_Generic} (@file{g-spchge.ads})
14630 @cindex Spell checking
14633 Provides a generic function that can be instantiated with a string type for
14634 determining whether one string is a plausible near misspelling of another
14637 @node GNAT.Spitbol.Patterns (g-spipat.ads)
14638 @section @code{GNAT.Spitbol.Patterns} (@file{g-spipat.ads})
14639 @cindex @code{GNAT.Spitbol.Patterns} (@file{g-spipat.ads})
14640 @cindex SPITBOL pattern matching
14641 @cindex Pattern matching
14644 A complete implementation of SNOBOL4 style pattern matching. This is the
14645 most elaborate of the pattern matching packages provided. It fully duplicates
14646 the SNOBOL4 dynamic pattern construction and matching capabilities, using the
14647 efficient algorithm developed by Robert Dewar for the SPITBOL system.
14649 @node GNAT.Spitbol (g-spitbo.ads)
14650 @section @code{GNAT.Spitbol} (@file{g-spitbo.ads})
14651 @cindex @code{GNAT.Spitbol} (@file{g-spitbo.ads})
14652 @cindex SPITBOL interface
14655 The top level package of the collection of SPITBOL-style functionality, this
14656 package provides basic SNOBOL4 string manipulation functions, such as
14657 Pad, Reverse, Trim, Substr capability, as well as a generic table function
14658 useful for constructing arbitrary mappings from strings in the style of
14659 the SNOBOL4 TABLE function.
14661 @node GNAT.Spitbol.Table_Boolean (g-sptabo.ads)
14662 @section @code{GNAT.Spitbol.Table_Boolean} (@file{g-sptabo.ads})
14663 @cindex @code{GNAT.Spitbol.Table_Boolean} (@file{g-sptabo.ads})
14664 @cindex Sets of strings
14665 @cindex SPITBOL Tables
14668 A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table}
14669 for type @code{Standard.Boolean}, giving an implementation of sets of
14672 @node GNAT.Spitbol.Table_Integer (g-sptain.ads)
14673 @section @code{GNAT.Spitbol.Table_Integer} (@file{g-sptain.ads})
14674 @cindex @code{GNAT.Spitbol.Table_Integer} (@file{g-sptain.ads})
14675 @cindex Integer maps
14677 @cindex SPITBOL Tables
14680 A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table}
14681 for type @code{Standard.Integer}, giving an implementation of maps
14682 from string to integer values.
14684 @node GNAT.Spitbol.Table_VString (g-sptavs.ads)
14685 @section @code{GNAT.Spitbol.Table_VString} (@file{g-sptavs.ads})
14686 @cindex @code{GNAT.Spitbol.Table_VString} (@file{g-sptavs.ads})
14687 @cindex String maps
14689 @cindex SPITBOL Tables
14692 A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table} for
14693 a variable length string type, giving an implementation of general
14694 maps from strings to strings.
14696 @node GNAT.SSE (g-sse.ads)
14697 @section @code{GNAT.SSE} (@file{g-sse.ads})
14698 @cindex @code{GNAT.SSE} (@file{g-sse.ads})
14701 Root of a set of units aimed at offering Ada bindings to a subset of
14702 the Intel(r) Streaming SIMD Extensions with GNAT on the x86 family of
14703 targets. It exposes vector component types together with a general
14704 introduction to the binding contents and use.
14706 @node GNAT.SSE.Vector_Types (g-ssvety.ads)
14707 @section @code{GNAT.SSE.Vector_Types} (@file{g-ssvety.ads})
14708 @cindex @code{GNAT.SSE.Vector_Types} (@file{g-ssvety.ads})
14711 SSE vector types for use with SSE related intrinsics.
14713 @node GNAT.Strings (g-string.ads)
14714 @section @code{GNAT.Strings} (@file{g-string.ads})
14715 @cindex @code{GNAT.Strings} (@file{g-string.ads})
14718 Common String access types and related subprograms. Basically it
14719 defines a string access and an array of string access types.
14721 @node GNAT.String_Split (g-strspl.ads)
14722 @section @code{GNAT.String_Split} (@file{g-strspl.ads})
14723 @cindex @code{GNAT.String_Split} (@file{g-strspl.ads})
14724 @cindex String splitter
14727 Useful string manipulation routines: given a set of separators, split
14728 a string wherever the separators appear, and provide direct access
14729 to the resulting slices. This package is instantiated from
14730 @code{GNAT.Array_Split}.
14732 @node GNAT.Table (g-table.ads)
14733 @section @code{GNAT.Table} (@file{g-table.ads})
14734 @cindex @code{GNAT.Table} (@file{g-table.ads})
14735 @cindex Table implementation
14736 @cindex Arrays, extendable
14739 A generic package providing a single dimension array abstraction where the
14740 length of the array can be dynamically modified.
14743 This package provides a facility similar to that of @code{GNAT.Dynamic_Tables},
14744 except that this package declares a single instance of the table type,
14745 while an instantiation of @code{GNAT.Dynamic_Tables} creates a type that can be
14746 used to define dynamic instances of the table.
14748 @node GNAT.Task_Lock (g-tasloc.ads)
14749 @section @code{GNAT.Task_Lock} (@file{g-tasloc.ads})
14750 @cindex @code{GNAT.Task_Lock} (@file{g-tasloc.ads})
14751 @cindex Task synchronization
14752 @cindex Task locking
14756 A very simple facility for locking and unlocking sections of code using a
14757 single global task lock. Appropriate for use in situations where contention
14758 between tasks is very rarely expected.
14760 @node GNAT.Time_Stamp (g-timsta.ads)
14761 @section @code{GNAT.Time_Stamp} (@file{g-timsta.ads})
14762 @cindex @code{GNAT.Time_Stamp} (@file{g-timsta.ads})
14764 @cindex Current time
14767 Provides a simple function that returns a string YYYY-MM-DD HH:MM:SS.SS that
14768 represents the current date and time in ISO 8601 format. This is a very simple
14769 routine with minimal code and there are no dependencies on any other unit.
14771 @node GNAT.Threads (g-thread.ads)
14772 @section @code{GNAT.Threads} (@file{g-thread.ads})
14773 @cindex @code{GNAT.Threads} (@file{g-thread.ads})
14774 @cindex Foreign threads
14775 @cindex Threads, foreign
14778 Provides facilities for dealing with foreign threads which need to be known
14779 by the GNAT run-time system. Consult the documentation of this package for
14780 further details if your program has threads that are created by a non-Ada
14781 environment which then accesses Ada code.
14783 @node GNAT.Traceback (g-traceb.ads)
14784 @section @code{GNAT.Traceback} (@file{g-traceb.ads})
14785 @cindex @code{GNAT.Traceback} (@file{g-traceb.ads})
14786 @cindex Trace back facilities
14789 Provides a facility for obtaining non-symbolic traceback information, useful
14790 in various debugging situations.
14792 @node GNAT.Traceback.Symbolic (g-trasym.ads)
14793 @section @code{GNAT.Traceback.Symbolic} (@file{g-trasym.ads})
14794 @cindex @code{GNAT.Traceback.Symbolic} (@file{g-trasym.ads})
14795 @cindex Trace back facilities
14797 @node GNAT.UTF_32 (g-utf_32.ads)
14798 @section @code{GNAT.UTF_32} (@file{g-table.ads})
14799 @cindex @code{GNAT.UTF_32} (@file{g-table.ads})
14800 @cindex Wide character codes
14803 This is a package intended to be used in conjunction with the
14804 @code{Wide_Character} type in Ada 95 and the
14805 @code{Wide_Wide_Character} type in Ada 2005 (available
14806 in @code{GNAT} in Ada 2005 mode). This package contains
14807 Unicode categorization routines, as well as lexical
14808 categorization routines corresponding to the Ada 2005
14809 lexical rules for identifiers and strings, and also a
14810 lower case to upper case fold routine corresponding to
14811 the Ada 2005 rules for identifier equivalence.
14813 @node GNAT.UTF_32_Spelling_Checker (g-u3spch.ads)
14814 @section @code{GNAT.Wide_Spelling_Checker} (@file{g-u3spch.ads})
14815 @cindex @code{GNAT.Wide_Spelling_Checker} (@file{g-u3spch.ads})
14816 @cindex Spell checking
14819 Provides a function for determining whether one wide wide string is a plausible
14820 near misspelling of another wide wide string, where the strings are represented
14821 using the UTF_32_String type defined in System.Wch_Cnv.
14823 @node GNAT.Wide_Spelling_Checker (g-wispch.ads)
14824 @section @code{GNAT.Wide_Spelling_Checker} (@file{g-wispch.ads})
14825 @cindex @code{GNAT.Wide_Spelling_Checker} (@file{g-wispch.ads})
14826 @cindex Spell checking
14829 Provides a function for determining whether one wide string is a plausible
14830 near misspelling of another wide string.
14832 @node GNAT.Wide_String_Split (g-wistsp.ads)
14833 @section @code{GNAT.Wide_String_Split} (@file{g-wistsp.ads})
14834 @cindex @code{GNAT.Wide_String_Split} (@file{g-wistsp.ads})
14835 @cindex Wide_String splitter
14838 Useful wide string manipulation routines: given a set of separators, split
14839 a wide string wherever the separators appear, and provide direct access
14840 to the resulting slices. This package is instantiated from
14841 @code{GNAT.Array_Split}.
14843 @node GNAT.Wide_Wide_Spelling_Checker (g-zspche.ads)
14844 @section @code{GNAT.Wide_Wide_Spelling_Checker} (@file{g-zspche.ads})
14845 @cindex @code{GNAT.Wide_Wide_Spelling_Checker} (@file{g-zspche.ads})
14846 @cindex Spell checking
14849 Provides a function for determining whether one wide wide string is a plausible
14850 near misspelling of another wide wide string.
14852 @node GNAT.Wide_Wide_String_Split (g-zistsp.ads)
14853 @section @code{GNAT.Wide_Wide_String_Split} (@file{g-zistsp.ads})
14854 @cindex @code{GNAT.Wide_Wide_String_Split} (@file{g-zistsp.ads})
14855 @cindex Wide_Wide_String splitter
14858 Useful wide wide string manipulation routines: given a set of separators, split
14859 a wide wide string wherever the separators appear, and provide direct access
14860 to the resulting slices. This package is instantiated from
14861 @code{GNAT.Array_Split}.
14863 @node Interfaces.C.Extensions (i-cexten.ads)
14864 @section @code{Interfaces.C.Extensions} (@file{i-cexten.ads})
14865 @cindex @code{Interfaces.C.Extensions} (@file{i-cexten.ads})
14868 This package contains additional C-related definitions, intended
14869 for use with either manually or automatically generated bindings
14872 @node Interfaces.C.Streams (i-cstrea.ads)
14873 @section @code{Interfaces.C.Streams} (@file{i-cstrea.ads})
14874 @cindex @code{Interfaces.C.Streams} (@file{i-cstrea.ads})
14875 @cindex C streams, interfacing
14878 This package is a binding for the most commonly used operations
14881 @node Interfaces.CPP (i-cpp.ads)
14882 @section @code{Interfaces.CPP} (@file{i-cpp.ads})
14883 @cindex @code{Interfaces.CPP} (@file{i-cpp.ads})
14884 @cindex C++ interfacing
14885 @cindex Interfacing, to C++
14888 This package provides facilities for use in interfacing to C++. It
14889 is primarily intended to be used in connection with automated tools
14890 for the generation of C++ interfaces.
14892 @node Interfaces.Packed_Decimal (i-pacdec.ads)
14893 @section @code{Interfaces.Packed_Decimal} (@file{i-pacdec.ads})
14894 @cindex @code{Interfaces.Packed_Decimal} (@file{i-pacdec.ads})
14895 @cindex IBM Packed Format
14896 @cindex Packed Decimal
14899 This package provides a set of routines for conversions to and
14900 from a packed decimal format compatible with that used on IBM
14903 @node Interfaces.VxWorks (i-vxwork.ads)
14904 @section @code{Interfaces.VxWorks} (@file{i-vxwork.ads})
14905 @cindex @code{Interfaces.VxWorks} (@file{i-vxwork.ads})
14906 @cindex Interfacing to VxWorks
14907 @cindex VxWorks, interfacing
14910 This package provides a limited binding to the VxWorks API.
14911 In particular, it interfaces with the
14912 VxWorks hardware interrupt facilities.
14914 @node Interfaces.VxWorks.IO (i-vxwoio.ads)
14915 @section @code{Interfaces.VxWorks.IO} (@file{i-vxwoio.ads})
14916 @cindex @code{Interfaces.VxWorks.IO} (@file{i-vxwoio.ads})
14917 @cindex Interfacing to VxWorks' I/O
14918 @cindex VxWorks, I/O interfacing
14919 @cindex VxWorks, Get_Immediate
14920 @cindex Get_Immediate, VxWorks
14923 This package provides a binding to the ioctl (IO/Control)
14924 function of VxWorks, defining a set of option values and
14925 function codes. A particular use of this package is
14926 to enable the use of Get_Immediate under VxWorks.
14928 @node System.Address_Image (s-addima.ads)
14929 @section @code{System.Address_Image} (@file{s-addima.ads})
14930 @cindex @code{System.Address_Image} (@file{s-addima.ads})
14931 @cindex Address image
14932 @cindex Image, of an address
14935 This function provides a useful debugging
14936 function that gives an (implementation dependent)
14937 string which identifies an address.
14939 @node System.Assertions (s-assert.ads)
14940 @section @code{System.Assertions} (@file{s-assert.ads})
14941 @cindex @code{System.Assertions} (@file{s-assert.ads})
14943 @cindex Assert_Failure, exception
14946 This package provides the declaration of the exception raised
14947 by an run-time assertion failure, as well as the routine that
14948 is used internally to raise this assertion.
14950 @node System.Memory (s-memory.ads)
14951 @section @code{System.Memory} (@file{s-memory.ads})
14952 @cindex @code{System.Memory} (@file{s-memory.ads})
14953 @cindex Memory allocation
14956 This package provides the interface to the low level routines used
14957 by the generated code for allocation and freeing storage for the
14958 default storage pool (analogous to the C routines malloc and free.
14959 It also provides a reallocation interface analogous to the C routine
14960 realloc. The body of this unit may be modified to provide alternative
14961 allocation mechanisms for the default pool, and in addition, direct
14962 calls to this unit may be made for low level allocation uses (for
14963 example see the body of @code{GNAT.Tables}).
14965 @node System.Partition_Interface (s-parint.ads)
14966 @section @code{System.Partition_Interface} (@file{s-parint.ads})
14967 @cindex @code{System.Partition_Interface} (@file{s-parint.ads})
14968 @cindex Partition interfacing functions
14971 This package provides facilities for partition interfacing. It
14972 is used primarily in a distribution context when using Annex E
14975 @node System.Pool_Global (s-pooglo.ads)
14976 @section @code{System.Pool_Global} (@file{s-pooglo.ads})
14977 @cindex @code{System.Pool_Global} (@file{s-pooglo.ads})
14978 @cindex Storage pool, global
14979 @cindex Global storage pool
14982 This package provides a storage pool that is equivalent to the default
14983 storage pool used for access types for which no pool is specifically
14984 declared. It uses malloc/free to allocate/free and does not attempt to
14985 do any automatic reclamation.
14987 @node System.Pool_Local (s-pooloc.ads)
14988 @section @code{System.Pool_Local} (@file{s-pooloc.ads})
14989 @cindex @code{System.Pool_Local} (@file{s-pooloc.ads})
14990 @cindex Storage pool, local
14991 @cindex Local storage pool
14994 This package provides a storage pool that is intended for use with locally
14995 defined access types. It uses malloc/free for allocate/free, and maintains
14996 a list of allocated blocks, so that all storage allocated for the pool can
14997 be freed automatically when the pool is finalized.
14999 @node System.Restrictions (s-restri.ads)
15000 @section @code{System.Restrictions} (@file{s-restri.ads})
15001 @cindex @code{System.Restrictions} (@file{s-restri.ads})
15002 @cindex Run-time restrictions access
15005 This package provides facilities for accessing at run time
15006 the status of restrictions specified at compile time for
15007 the partition. Information is available both with regard
15008 to actual restrictions specified, and with regard to
15009 compiler determined information on which restrictions
15010 are violated by one or more packages in the partition.
15012 @node System.Rident (s-rident.ads)
15013 @section @code{System.Rident} (@file{s-rident.ads})
15014 @cindex @code{System.Rident} (@file{s-rident.ads})
15015 @cindex Restrictions definitions
15018 This package provides definitions of the restrictions
15019 identifiers supported by GNAT, and also the format of
15020 the restrictions provided in package System.Restrictions.
15021 It is not normally necessary to @code{with} this generic package
15022 since the necessary instantiation is included in
15023 package System.Restrictions.
15025 @node System.Strings.Stream_Ops (s-ststop.ads)
15026 @section @code{System.Strings.Stream_Ops} (@file{s-ststop.ads})
15027 @cindex @code{System.Strings.Stream_Ops} (@file{s-ststop.ads})
15028 @cindex Stream operations
15029 @cindex String stream operations
15032 This package provides a set of stream subprograms for standard string types.
15033 It is intended primarily to support implicit use of such subprograms when
15034 stream attributes are applied to string types, but the subprograms in this
15035 package can be used directly by application programs.
15037 @node System.Task_Info (s-tasinf.ads)
15038 @section @code{System.Task_Info} (@file{s-tasinf.ads})
15039 @cindex @code{System.Task_Info} (@file{s-tasinf.ads})
15040 @cindex Task_Info pragma
15043 This package provides target dependent functionality that is used
15044 to support the @code{Task_Info} pragma
15046 @node System.Wch_Cnv (s-wchcnv.ads)
15047 @section @code{System.Wch_Cnv} (@file{s-wchcnv.ads})
15048 @cindex @code{System.Wch_Cnv} (@file{s-wchcnv.ads})
15049 @cindex Wide Character, Representation
15050 @cindex Wide String, Conversion
15051 @cindex Representation of wide characters
15054 This package provides routines for converting between
15055 wide and wide wide characters and a representation as a value of type
15056 @code{Standard.String}, using a specified wide character
15057 encoding method. It uses definitions in
15058 package @code{System.Wch_Con}.
15060 @node System.Wch_Con (s-wchcon.ads)
15061 @section @code{System.Wch_Con} (@file{s-wchcon.ads})
15062 @cindex @code{System.Wch_Con} (@file{s-wchcon.ads})
15065 This package provides definitions and descriptions of
15066 the various methods used for encoding wide characters
15067 in ordinary strings. These definitions are used by
15068 the package @code{System.Wch_Cnv}.
15070 @node Interfacing to Other Languages
15071 @chapter Interfacing to Other Languages
15073 The facilities in annex B of the Ada Reference Manual are fully
15074 implemented in GNAT, and in addition, a full interface to C++ is
15078 * Interfacing to C::
15079 * Interfacing to C++::
15080 * Interfacing to COBOL::
15081 * Interfacing to Fortran::
15082 * Interfacing to non-GNAT Ada code::
15085 @node Interfacing to C
15086 @section Interfacing to C
15089 Interfacing to C with GNAT can use one of two approaches:
15093 The types in the package @code{Interfaces.C} may be used.
15095 Standard Ada types may be used directly. This may be less portable to
15096 other compilers, but will work on all GNAT compilers, which guarantee
15097 correspondence between the C and Ada types.
15101 Pragma @code{Convention C} may be applied to Ada types, but mostly has no
15102 effect, since this is the default. The following table shows the
15103 correspondence between Ada scalar types and the corresponding C types.
15108 @item Short_Integer
15110 @item Short_Short_Integer
15114 @item Long_Long_Integer
15122 @item Long_Long_Float
15123 This is the longest floating-point type supported by the hardware.
15127 Additionally, there are the following general correspondences between Ada
15131 Ada enumeration types map to C enumeration types directly if pragma
15132 @code{Convention C} is specified, which causes them to have int
15133 length. Without pragma @code{Convention C}, Ada enumeration types map to
15134 8, 16, or 32 bits (i.e.@: C types @code{signed char}, @code{short},
15135 @code{int}, respectively) depending on the number of values passed.
15136 This is the only case in which pragma @code{Convention C} affects the
15137 representation of an Ada type.
15140 Ada access types map to C pointers, except for the case of pointers to
15141 unconstrained types in Ada, which have no direct C equivalent.
15144 Ada arrays map directly to C arrays.
15147 Ada records map directly to C structures.
15150 Packed Ada records map to C structures where all members are bit fields
15151 of the length corresponding to the @code{@var{type}'Size} value in Ada.
15154 @node Interfacing to C++
15155 @section Interfacing to C++
15158 The interface to C++ makes use of the following pragmas, which are
15159 primarily intended to be constructed automatically using a binding generator
15160 tool, although it is possible to construct them by hand. No suitable binding
15161 generator tool is supplied with GNAT though.
15163 Using these pragmas it is possible to achieve complete
15164 inter-operability between Ada tagged types and C++ class definitions.
15165 See @ref{Implementation Defined Pragmas}, for more details.
15168 @item pragma CPP_Class ([Entity =>] @var{LOCAL_NAME})
15169 The argument denotes an entity in the current declarative region that is
15170 declared as a tagged or untagged record type. It indicates that the type
15171 corresponds to an externally declared C++ class type, and is to be laid
15172 out the same way that C++ would lay out the type.
15174 Note: Pragma @code{CPP_Class} is currently obsolete. It is supported
15175 for backward compatibility but its functionality is available
15176 using pragma @code{Import} with @code{Convention} = @code{CPP}.
15178 @item pragma CPP_Constructor ([Entity =>] @var{LOCAL_NAME})
15179 This pragma identifies an imported function (imported in the usual way
15180 with pragma @code{Import}) as corresponding to a C++ constructor.
15183 @node Interfacing to COBOL
15184 @section Interfacing to COBOL
15187 Interfacing to COBOL is achieved as described in section B.4 of
15188 the Ada Reference Manual.
15190 @node Interfacing to Fortran
15191 @section Interfacing to Fortran
15194 Interfacing to Fortran is achieved as described in section B.5 of the
15195 Ada Reference Manual. The pragma @code{Convention Fortran}, applied to a
15196 multi-dimensional array causes the array to be stored in column-major
15197 order as required for convenient interface to Fortran.
15199 @node Interfacing to non-GNAT Ada code
15200 @section Interfacing to non-GNAT Ada code
15202 It is possible to specify the convention @code{Ada} in a pragma
15203 @code{Import} or pragma @code{Export}. However this refers to
15204 the calling conventions used by GNAT, which may or may not be
15205 similar enough to those used by some other Ada 83 / Ada 95 / Ada 2005
15206 compiler to allow interoperation.
15208 If arguments types are kept simple, and if the foreign compiler generally
15209 follows system calling conventions, then it may be possible to integrate
15210 files compiled by other Ada compilers, provided that the elaboration
15211 issues are adequately addressed (for example by eliminating the
15212 need for any load time elaboration).
15214 In particular, GNAT running on VMS is designed to
15215 be highly compatible with the DEC Ada 83 compiler, so this is one
15216 case in which it is possible to import foreign units of this type,
15217 provided that the data items passed are restricted to simple scalar
15218 values or simple record types without variants, or simple array
15219 types with fixed bounds.
15221 @node Specialized Needs Annexes
15222 @chapter Specialized Needs Annexes
15225 Ada 95 and Ada 2005 define a number of Specialized Needs Annexes, which are not
15226 required in all implementations. However, as described in this chapter,
15227 GNAT implements all of these annexes:
15230 @item Systems Programming (Annex C)
15231 The Systems Programming Annex is fully implemented.
15233 @item Real-Time Systems (Annex D)
15234 The Real-Time Systems Annex is fully implemented.
15236 @item Distributed Systems (Annex E)
15237 Stub generation is fully implemented in the GNAT compiler. In addition,
15238 a complete compatible PCS is available as part of the GLADE system,
15239 a separate product. When the two
15240 products are used in conjunction, this annex is fully implemented.
15242 @item Information Systems (Annex F)
15243 The Information Systems annex is fully implemented.
15245 @item Numerics (Annex G)
15246 The Numerics Annex is fully implemented.
15248 @item Safety and Security / High-Integrity Systems (Annex H)
15249 The Safety and Security Annex (termed the High-Integrity Systems Annex
15250 in Ada 2005) is fully implemented.
15253 @node Implementation of Specific Ada Features
15254 @chapter Implementation of Specific Ada Features
15257 This chapter describes the GNAT implementation of several Ada language
15261 * Machine Code Insertions::
15262 * GNAT Implementation of Tasking::
15263 * GNAT Implementation of Shared Passive Packages::
15264 * Code Generation for Array Aggregates::
15265 * The Size of Discriminated Records with Default Discriminants::
15266 * Strict Conformance to the Ada Reference Manual::
15269 @node Machine Code Insertions
15270 @section Machine Code Insertions
15271 @cindex Machine Code insertions
15274 Package @code{Machine_Code} provides machine code support as described
15275 in the Ada Reference Manual in two separate forms:
15278 Machine code statements, consisting of qualified expressions that
15279 fit the requirements of RM section 13.8.
15281 An intrinsic callable procedure, providing an alternative mechanism of
15282 including machine instructions in a subprogram.
15286 The two features are similar, and both are closely related to the mechanism
15287 provided by the asm instruction in the GNU C compiler. Full understanding
15288 and use of the facilities in this package requires understanding the asm
15289 instruction, see @ref{Extended Asm,, Assembler Instructions with C Expression
15290 Operands, gcc, Using the GNU Compiler Collection (GCC)}.
15292 Calls to the function @code{Asm} and the procedure @code{Asm} have identical
15293 semantic restrictions and effects as described below. Both are provided so
15294 that the procedure call can be used as a statement, and the function call
15295 can be used to form a code_statement.
15297 The first example given in the GCC documentation is the C @code{asm}
15300 asm ("fsinx %1 %0" : "=f" (result) : "f" (angle));
15304 The equivalent can be written for GNAT as:
15306 @smallexample @c ada
15307 Asm ("fsinx %1 %0",
15308 My_Float'Asm_Output ("=f", result),
15309 My_Float'Asm_Input ("f", angle));
15313 The first argument to @code{Asm} is the assembler template, and is
15314 identical to what is used in GNU C@. This string must be a static
15315 expression. The second argument is the output operand list. It is
15316 either a single @code{Asm_Output} attribute reference, or a list of such
15317 references enclosed in parentheses (technically an array aggregate of
15320 The @code{Asm_Output} attribute denotes a function that takes two
15321 parameters. The first is a string, the second is the name of a variable
15322 of the type designated by the attribute prefix. The first (string)
15323 argument is required to be a static expression and designates the
15324 constraint for the parameter (e.g.@: what kind of register is
15325 required). The second argument is the variable to be updated with the
15326 result. The possible values for constraint are the same as those used in
15327 the RTL, and are dependent on the configuration file used to build the
15328 GCC back end. If there are no output operands, then this argument may
15329 either be omitted, or explicitly given as @code{No_Output_Operands}.
15331 The second argument of @code{@var{my_float}'Asm_Output} functions as
15332 though it were an @code{out} parameter, which is a little curious, but
15333 all names have the form of expressions, so there is no syntactic
15334 irregularity, even though normally functions would not be permitted
15335 @code{out} parameters. The third argument is the list of input
15336 operands. It is either a single @code{Asm_Input} attribute reference, or
15337 a list of such references enclosed in parentheses (technically an array
15338 aggregate of such references).
15340 The @code{Asm_Input} attribute denotes a function that takes two
15341 parameters. The first is a string, the second is an expression of the
15342 type designated by the prefix. The first (string) argument is required
15343 to be a static expression, and is the constraint for the parameter,
15344 (e.g.@: what kind of register is required). The second argument is the
15345 value to be used as the input argument. The possible values for the
15346 constant are the same as those used in the RTL, and are dependent on
15347 the configuration file used to built the GCC back end.
15349 If there are no input operands, this argument may either be omitted, or
15350 explicitly given as @code{No_Input_Operands}. The fourth argument, not
15351 present in the above example, is a list of register names, called the
15352 @dfn{clobber} argument. This argument, if given, must be a static string
15353 expression, and is a space or comma separated list of names of registers
15354 that must be considered destroyed as a result of the @code{Asm} call. If
15355 this argument is the null string (the default value), then the code
15356 generator assumes that no additional registers are destroyed.
15358 The fifth argument, not present in the above example, called the
15359 @dfn{volatile} argument, is by default @code{False}. It can be set to
15360 the literal value @code{True} to indicate to the code generator that all
15361 optimizations with respect to the instruction specified should be
15362 suppressed, and that in particular, for an instruction that has outputs,
15363 the instruction will still be generated, even if none of the outputs are
15364 used. @xref{Extended Asm,, Assembler Instructions with C Expression Operands,
15365 gcc, Using the GNU Compiler Collection (GCC)}, for the full description.
15366 Generally it is strongly advisable to use Volatile for any ASM statement
15367 that is missing either input or output operands, or when two or more ASM
15368 statements appear in sequence, to avoid unwanted optimizations. A warning
15369 is generated if this advice is not followed.
15371 The @code{Asm} subprograms may be used in two ways. First the procedure
15372 forms can be used anywhere a procedure call would be valid, and
15373 correspond to what the RM calls ``intrinsic'' routines. Such calls can
15374 be used to intersperse machine instructions with other Ada statements.
15375 Second, the function forms, which return a dummy value of the limited
15376 private type @code{Asm_Insn}, can be used in code statements, and indeed
15377 this is the only context where such calls are allowed. Code statements
15378 appear as aggregates of the form:
15380 @smallexample @c ada
15381 Asm_Insn'(Asm (@dots{}));
15382 Asm_Insn'(Asm_Volatile (@dots{}));
15386 In accordance with RM rules, such code statements are allowed only
15387 within subprograms whose entire body consists of such statements. It is
15388 not permissible to intermix such statements with other Ada statements.
15390 Typically the form using intrinsic procedure calls is more convenient
15391 and more flexible. The code statement form is provided to meet the RM
15392 suggestion that such a facility should be made available. The following
15393 is the exact syntax of the call to @code{Asm}. As usual, if named notation
15394 is used, the arguments may be given in arbitrary order, following the
15395 normal rules for use of positional and named arguments)
15399 [Template =>] static_string_EXPRESSION
15400 [,[Outputs =>] OUTPUT_OPERAND_LIST ]
15401 [,[Inputs =>] INPUT_OPERAND_LIST ]
15402 [,[Clobber =>] static_string_EXPRESSION ]
15403 [,[Volatile =>] static_boolean_EXPRESSION] )
15405 OUTPUT_OPERAND_LIST ::=
15406 [PREFIX.]No_Output_Operands
15407 | OUTPUT_OPERAND_ATTRIBUTE
15408 | (OUTPUT_OPERAND_ATTRIBUTE @{,OUTPUT_OPERAND_ATTRIBUTE@})
15410 OUTPUT_OPERAND_ATTRIBUTE ::=
15411 SUBTYPE_MARK'Asm_Output (static_string_EXPRESSION, NAME)
15413 INPUT_OPERAND_LIST ::=
15414 [PREFIX.]No_Input_Operands
15415 | INPUT_OPERAND_ATTRIBUTE
15416 | (INPUT_OPERAND_ATTRIBUTE @{,INPUT_OPERAND_ATTRIBUTE@})
15418 INPUT_OPERAND_ATTRIBUTE ::=
15419 SUBTYPE_MARK'Asm_Input (static_string_EXPRESSION, EXPRESSION)
15423 The identifiers @code{No_Input_Operands} and @code{No_Output_Operands}
15424 are declared in the package @code{Machine_Code} and must be referenced
15425 according to normal visibility rules. In particular if there is no
15426 @code{use} clause for this package, then appropriate package name
15427 qualification is required.
15429 @node GNAT Implementation of Tasking
15430 @section GNAT Implementation of Tasking
15433 This chapter outlines the basic GNAT approach to tasking (in particular,
15434 a multi-layered library for portability) and discusses issues related
15435 to compliance with the Real-Time Systems Annex.
15438 * Mapping Ada Tasks onto the Underlying Kernel Threads::
15439 * Ensuring Compliance with the Real-Time Annex::
15442 @node Mapping Ada Tasks onto the Underlying Kernel Threads
15443 @subsection Mapping Ada Tasks onto the Underlying Kernel Threads
15446 GNAT's run-time support comprises two layers:
15449 @item GNARL (GNAT Run-time Layer)
15450 @item GNULL (GNAT Low-level Library)
15454 In GNAT, Ada's tasking services rely on a platform and OS independent
15455 layer known as GNARL@. This code is responsible for implementing the
15456 correct semantics of Ada's task creation, rendezvous, protected
15459 GNARL decomposes Ada's tasking semantics into simpler lower level
15460 operations such as create a thread, set the priority of a thread,
15461 yield, create a lock, lock/unlock, etc. The spec for these low-level
15462 operations constitutes GNULLI, the GNULL Interface. This interface is
15463 directly inspired from the POSIX real-time API@.
15465 If the underlying executive or OS implements the POSIX standard
15466 faithfully, the GNULL Interface maps as is to the services offered by
15467 the underlying kernel. Otherwise, some target dependent glue code maps
15468 the services offered by the underlying kernel to the semantics expected
15471 Whatever the underlying OS (VxWorks, UNIX, OS/2, Windows NT, etc.) the
15472 key point is that each Ada task is mapped on a thread in the underlying
15473 kernel. For example, in the case of VxWorks, one Ada task = one VxWorks task.
15475 In addition Ada task priorities map onto the underlying thread priorities.
15476 Mapping Ada tasks onto the underlying kernel threads has several advantages:
15480 The underlying scheduler is used to schedule the Ada tasks. This
15481 makes Ada tasks as efficient as kernel threads from a scheduling
15485 Interaction with code written in C containing threads is eased
15486 since at the lowest level Ada tasks and C threads map onto the same
15487 underlying kernel concept.
15490 When an Ada task is blocked during I/O the remaining Ada tasks are
15494 On multiprocessor systems Ada tasks can execute in parallel.
15498 Some threads libraries offer a mechanism to fork a new process, with the
15499 child process duplicating the threads from the parent.
15501 support this functionality when the parent contains more than one task.
15502 @cindex Forking a new process
15504 @node Ensuring Compliance with the Real-Time Annex
15505 @subsection Ensuring Compliance with the Real-Time Annex
15506 @cindex Real-Time Systems Annex compliance
15509 Although mapping Ada tasks onto
15510 the underlying threads has significant advantages, it does create some
15511 complications when it comes to respecting the scheduling semantics
15512 specified in the real-time annex (Annex D).
15514 For instance the Annex D requirement for the @code{FIFO_Within_Priorities}
15515 scheduling policy states:
15518 @emph{When the active priority of a ready task that is not running
15519 changes, or the setting of its base priority takes effect, the
15520 task is removed from the ready queue for its old active priority
15521 and is added at the tail of the ready queue for its new active
15522 priority, except in the case where the active priority is lowered
15523 due to the loss of inherited priority, in which case the task is
15524 added at the head of the ready queue for its new active priority.}
15528 While most kernels do put tasks at the end of the priority queue when
15529 a task changes its priority, (which respects the main
15530 FIFO_Within_Priorities requirement), almost none keep a thread at the
15531 beginning of its priority queue when its priority drops from the loss
15532 of inherited priority.
15534 As a result most vendors have provided incomplete Annex D implementations.
15536 The GNAT run-time, has a nice cooperative solution to this problem
15537 which ensures that accurate FIFO_Within_Priorities semantics are
15540 The principle is as follows. When an Ada task T is about to start
15541 running, it checks whether some other Ada task R with the same
15542 priority as T has been suspended due to the loss of priority
15543 inheritance. If this is the case, T yields and is placed at the end of
15544 its priority queue. When R arrives at the front of the queue it
15547 Note that this simple scheme preserves the relative order of the tasks
15548 that were ready to execute in the priority queue where R has been
15551 @node GNAT Implementation of Shared Passive Packages
15552 @section GNAT Implementation of Shared Passive Packages
15553 @cindex Shared passive packages
15556 GNAT fully implements the pragma @code{Shared_Passive} for
15557 @cindex pragma @code{Shared_Passive}
15558 the purpose of designating shared passive packages.
15559 This allows the use of passive partitions in the
15560 context described in the Ada Reference Manual; i.e., for communication
15561 between separate partitions of a distributed application using the
15562 features in Annex E.
15564 @cindex Distribution Systems Annex
15566 However, the implementation approach used by GNAT provides for more
15567 extensive usage as follows:
15570 @item Communication between separate programs
15572 This allows separate programs to access the data in passive
15573 partitions, using protected objects for synchronization where
15574 needed. The only requirement is that the two programs have a
15575 common shared file system. It is even possible for programs
15576 running on different machines with different architectures
15577 (e.g.@: different endianness) to communicate via the data in
15578 a passive partition.
15580 @item Persistence between program runs
15582 The data in a passive package can persist from one run of a
15583 program to another, so that a later program sees the final
15584 values stored by a previous run of the same program.
15589 The implementation approach used is to store the data in files. A
15590 separate stream file is created for each object in the package, and
15591 an access to an object causes the corresponding file to be read or
15594 The environment variable @code{SHARED_MEMORY_DIRECTORY} should be
15595 @cindex @code{SHARED_MEMORY_DIRECTORY} environment variable
15596 set to the directory to be used for these files.
15597 The files in this directory
15598 have names that correspond to their fully qualified names. For
15599 example, if we have the package
15601 @smallexample @c ada
15603 pragma Shared_Passive (X);
15610 and the environment variable is set to @code{/stemp/}, then the files created
15611 will have the names:
15619 These files are created when a value is initially written to the object, and
15620 the files are retained until manually deleted. This provides the persistence
15621 semantics. If no file exists, it means that no partition has assigned a value
15622 to the variable; in this case the initial value declared in the package
15623 will be used. This model ensures that there are no issues in synchronizing
15624 the elaboration process, since elaboration of passive packages elaborates the
15625 initial values, but does not create the files.
15627 The files are written using normal @code{Stream_IO} access.
15628 If you want to be able
15629 to communicate between programs or partitions running on different
15630 architectures, then you should use the XDR versions of the stream attribute
15631 routines, since these are architecture independent.
15633 If active synchronization is required for access to the variables in the
15634 shared passive package, then as described in the Ada Reference Manual, the
15635 package may contain protected objects used for this purpose. In this case
15636 a lock file (whose name is @file{___lock} (three underscores)
15637 is created in the shared memory directory.
15638 @cindex @file{___lock} file (for shared passive packages)
15639 This is used to provide the required locking
15640 semantics for proper protected object synchronization.
15642 As of January 2003, GNAT supports shared passive packages on all platforms
15643 except for OpenVMS.
15645 @node Code Generation for Array Aggregates
15646 @section Code Generation for Array Aggregates
15649 * Static constant aggregates with static bounds::
15650 * Constant aggregates with unconstrained nominal types::
15651 * Aggregates with static bounds::
15652 * Aggregates with non-static bounds::
15653 * Aggregates in assignment statements::
15657 Aggregates have a rich syntax and allow the user to specify the values of
15658 complex data structures by means of a single construct. As a result, the
15659 code generated for aggregates can be quite complex and involve loops, case
15660 statements and multiple assignments. In the simplest cases, however, the
15661 compiler will recognize aggregates whose components and constraints are
15662 fully static, and in those cases the compiler will generate little or no
15663 executable code. The following is an outline of the code that GNAT generates
15664 for various aggregate constructs. For further details, you will find it
15665 useful to examine the output produced by the -gnatG flag to see the expanded
15666 source that is input to the code generator. You may also want to examine
15667 the assembly code generated at various levels of optimization.
15669 The code generated for aggregates depends on the context, the component values,
15670 and the type. In the context of an object declaration the code generated is
15671 generally simpler than in the case of an assignment. As a general rule, static
15672 component values and static subtypes also lead to simpler code.
15674 @node Static constant aggregates with static bounds
15675 @subsection Static constant aggregates with static bounds
15678 For the declarations:
15679 @smallexample @c ada
15680 type One_Dim is array (1..10) of integer;
15681 ar0 : constant One_Dim := (1, 2, 3, 4, 5, 6, 7, 8, 9, 0);
15685 GNAT generates no executable code: the constant ar0 is placed in static memory.
15686 The same is true for constant aggregates with named associations:
15688 @smallexample @c ada
15689 Cr1 : constant One_Dim := (4 => 16, 2 => 4, 3 => 9, 1 => 1, 5 .. 10 => 0);
15690 Cr3 : constant One_Dim := (others => 7777);
15694 The same is true for multidimensional constant arrays such as:
15696 @smallexample @c ada
15697 type two_dim is array (1..3, 1..3) of integer;
15698 Unit : constant two_dim := ( (1,0,0), (0,1,0), (0,0,1));
15702 The same is true for arrays of one-dimensional arrays: the following are
15705 @smallexample @c ada
15706 type ar1b is array (1..3) of boolean;
15707 type ar_ar is array (1..3) of ar1b;
15708 None : constant ar1b := (others => false); -- fully static
15709 None2 : constant ar_ar := (1..3 => None); -- fully static
15713 However, for multidimensional aggregates with named associations, GNAT will
15714 generate assignments and loops, even if all associations are static. The
15715 following two declarations generate a loop for the first dimension, and
15716 individual component assignments for the second dimension:
15718 @smallexample @c ada
15719 Zero1: constant two_dim := (1..3 => (1..3 => 0));
15720 Zero2: constant two_dim := (others => (others => 0));
15723 @node Constant aggregates with unconstrained nominal types
15724 @subsection Constant aggregates with unconstrained nominal types
15727 In such cases the aggregate itself establishes the subtype, so that
15728 associations with @code{others} cannot be used. GNAT determines the
15729 bounds for the actual subtype of the aggregate, and allocates the
15730 aggregate statically as well. No code is generated for the following:
15732 @smallexample @c ada
15733 type One_Unc is array (natural range <>) of integer;
15734 Cr_Unc : constant One_Unc := (12,24,36);
15737 @node Aggregates with static bounds
15738 @subsection Aggregates with static bounds
15741 In all previous examples the aggregate was the initial (and immutable) value
15742 of a constant. If the aggregate initializes a variable, then code is generated
15743 for it as a combination of individual assignments and loops over the target
15744 object. The declarations
15746 @smallexample @c ada
15747 Cr_Var1 : One_Dim := (2, 5, 7, 11, 0, 0, 0, 0, 0, 0);
15748 Cr_Var2 : One_Dim := (others > -1);
15752 generate the equivalent of
15754 @smallexample @c ada
15760 for I in Cr_Var2'range loop
15765 @node Aggregates with non-static bounds
15766 @subsection Aggregates with non-static bounds
15769 If the bounds of the aggregate are not statically compatible with the bounds
15770 of the nominal subtype of the target, then constraint checks have to be
15771 generated on the bounds. For a multidimensional array, constraint checks may
15772 have to be applied to sub-arrays individually, if they do not have statically
15773 compatible subtypes.
15775 @node Aggregates in assignment statements
15776 @subsection Aggregates in assignment statements
15779 In general, aggregate assignment requires the construction of a temporary,
15780 and a copy from the temporary to the target of the assignment. This is because
15781 it is not always possible to convert the assignment into a series of individual
15782 component assignments. For example, consider the simple case:
15784 @smallexample @c ada
15789 This cannot be converted into:
15791 @smallexample @c ada
15797 So the aggregate has to be built first in a separate location, and then
15798 copied into the target. GNAT recognizes simple cases where this intermediate
15799 step is not required, and the assignments can be performed in place, directly
15800 into the target. The following sufficient criteria are applied:
15804 The bounds of the aggregate are static, and the associations are static.
15806 The components of the aggregate are static constants, names of
15807 simple variables that are not renamings, or expressions not involving
15808 indexed components whose operands obey these rules.
15812 If any of these conditions are violated, the aggregate will be built in
15813 a temporary (created either by the front-end or the code generator) and then
15814 that temporary will be copied onto the target.
15817 @node The Size of Discriminated Records with Default Discriminants
15818 @section The Size of Discriminated Records with Default Discriminants
15821 If a discriminated type @code{T} has discriminants with default values, it is
15822 possible to declare an object of this type without providing an explicit
15825 @smallexample @c ada
15827 type Size is range 1..100;
15829 type Rec (D : Size := 15) is record
15830 Name : String (1..D);
15838 Such an object is said to be @emph{unconstrained}.
15839 The discriminant of the object
15840 can be modified by a full assignment to the object, as long as it preserves the
15841 relation between the value of the discriminant, and the value of the components
15844 @smallexample @c ada
15846 Word := (3, "yes");
15848 Word := (5, "maybe");
15850 Word := (5, "no"); -- raises Constraint_Error
15855 In order to support this behavior efficiently, an unconstrained object is
15856 given the maximum size that any value of the type requires. In the case
15857 above, @code{Word} has storage for the discriminant and for
15858 a @code{String} of length 100.
15859 It is important to note that unconstrained objects do not require dynamic
15860 allocation. It would be an improper implementation to place on the heap those
15861 components whose size depends on discriminants. (This improper implementation
15862 was used by some Ada83 compilers, where the @code{Name} component above
15864 been stored as a pointer to a dynamic string). Following the principle that
15865 dynamic storage management should never be introduced implicitly,
15866 an Ada compiler should reserve the full size for an unconstrained declared
15867 object, and place it on the stack.
15869 This maximum size approach
15870 has been a source of surprise to some users, who expect the default
15871 values of the discriminants to determine the size reserved for an
15872 unconstrained object: ``If the default is 15, why should the object occupy
15874 The answer, of course, is that the discriminant may be later modified,
15875 and its full range of values must be taken into account. This is why the
15880 type Rec (D : Positive := 15) is record
15881 Name : String (1..D);
15889 is flagged by the compiler with a warning:
15890 an attempt to create @code{Too_Large} will raise @code{Storage_Error},
15891 because the required size includes @code{Positive'Last}
15892 bytes. As the first example indicates, the proper approach is to declare an
15893 index type of ``reasonable'' range so that unconstrained objects are not too
15896 One final wrinkle: if the object is declared to be @code{aliased}, or if it is
15897 created in the heap by means of an allocator, then it is @emph{not}
15899 it is constrained by the default values of the discriminants, and those values
15900 cannot be modified by full assignment. This is because in the presence of
15901 aliasing all views of the object (which may be manipulated by different tasks,
15902 say) must be consistent, so it is imperative that the object, once created,
15905 @node Strict Conformance to the Ada Reference Manual
15906 @section Strict Conformance to the Ada Reference Manual
15909 The dynamic semantics defined by the Ada Reference Manual impose a set of
15910 run-time checks to be generated. By default, the GNAT compiler will insert many
15911 run-time checks into the compiled code, including most of those required by the
15912 Ada Reference Manual. However, there are three checks that are not enabled
15913 in the default mode for efficiency reasons: arithmetic overflow checking for
15914 integer operations (including division by zero), checks for access before
15915 elaboration on subprogram calls, and stack overflow checking (most operating
15916 systems do not perform this check by default).
15918 Strict conformance to the Ada Reference Manual can be achieved by adding
15919 three compiler options for overflow checking for integer operations
15920 (@option{-gnato}), dynamic checks for access-before-elaboration on subprogram
15921 calls and generic instantiations (@option{-gnatE}), and stack overflow
15922 checking (@option{-fstack-check}).
15924 Note that the result of a floating point arithmetic operation in overflow and
15925 invalid situations, when the @code{Machine_Overflows} attribute of the result
15926 type is @code{False}, is to generate IEEE NaN and infinite values. This is the
15927 case for machines compliant with the IEEE floating-point standard, but on
15928 machines that are not fully compliant with this standard, such as Alpha, the
15929 @option{-mieee} compiler flag must be used for achieving IEEE confirming
15930 behavior (although at the cost of a significant performance penalty), so
15931 infinite and and NaN values are properly generated.
15934 @node Project File Reference
15935 @chapter Project File Reference
15938 This chapter describes the syntax and semantics of project files.
15939 Project files specify the options to be used when building a system.
15940 Project files can specify global settings for all tools,
15941 as well as tool-specific settings.
15942 @xref{Examples of Project Files,,, gnat_ugn, @value{EDITION} User's Guide},
15943 for examples of use.
15947 * Lexical Elements::
15949 * Empty declarations::
15950 * Typed string declarations::
15954 * Project Attributes::
15955 * Attribute References::
15956 * External Values::
15957 * Case Construction::
15959 * Package Renamings::
15961 * Project Extensions::
15962 * Project File Elaboration::
15965 @node Reserved Words
15966 @section Reserved Words
15969 All Ada reserved words are reserved in project files, and cannot be used
15970 as variable names or project names. In addition, the following are
15971 also reserved in project files:
15974 @item @code{extends}
15976 @item @code{external}
15978 @item @code{project}
15982 @node Lexical Elements
15983 @section Lexical Elements
15986 Rules for identifiers are the same as in Ada. Identifiers
15987 are case-insensitive. Strings are case sensitive, except where noted.
15988 Comments have the same form as in Ada.
15998 simple_name @{. simple_name@}
16002 @section Declarations
16005 Declarations introduce new entities that denote types, variables, attributes,
16006 and packages. Some declarations can only appear immediately within a project
16007 declaration. Others can appear within a project or within a package.
16011 declarative_item ::=
16012 simple_declarative_item |
16013 typed_string_declaration |
16014 package_declaration
16016 simple_declarative_item ::=
16017 variable_declaration |
16018 typed_variable_declaration |
16019 attribute_declaration |
16020 case_construction |
16024 @node Empty declarations
16025 @section Empty declarations
16028 empty_declaration ::=
16032 An empty declaration is allowed anywhere a declaration is allowed.
16035 @node Typed string declarations
16036 @section Typed string declarations
16039 Typed strings are sequences of string literals. Typed strings are the only
16040 named types in project files. They are used in case constructions, where they
16041 provide support for conditional attribute definitions.
16045 typed_string_declaration ::=
16046 @b{type} <typed_string_>_simple_name @b{is}
16047 ( string_literal @{, string_literal@} );
16051 A typed string declaration can only appear immediately within a project
16054 All the string literals in a typed string declaration must be distinct.
16060 Variables denote values, and appear as constituents of expressions.
16063 typed_variable_declaration ::=
16064 <typed_variable_>simple_name : <typed_string_>name := string_expression ;
16066 variable_declaration ::=
16067 <variable_>simple_name := expression;
16071 The elaboration of a variable declaration introduces the variable and
16072 assigns to it the value of the expression. The name of the variable is
16073 available after the assignment symbol.
16076 A typed_variable can only be declare once.
16079 a non-typed variable can be declared multiple times.
16082 Before the completion of its first declaration, the value of variable
16083 is the null string.
16086 @section Expressions
16089 An expression is a formula that defines a computation or retrieval of a value.
16090 In a project file the value of an expression is either a string or a list
16091 of strings. A string value in an expression is either a literal, the current
16092 value of a variable, an external value, an attribute reference, or a
16093 concatenation operation.
16106 attribute_reference
16112 ( <string_>expression @{ , <string_>expression @} )
16115 @subsection Concatenation
16117 The following concatenation functions are defined:
16119 @smallexample @c ada
16120 function "&" (X : String; Y : String) return String;
16121 function "&" (X : String_List; Y : String) return String_List;
16122 function "&" (X : String_List; Y : String_List) return String_List;
16126 @section Attributes
16129 An attribute declaration defines a property of a project or package. This
16130 property can later be queried by means of an attribute reference.
16131 Attribute values are strings or string lists.
16133 Some attributes are associative arrays. These attributes are mappings whose
16134 domain is a set of strings. These attributes are declared one association
16135 at a time, by specifying a point in the domain and the corresponding image
16136 of the attribute. They may also be declared as a full associative array,
16137 getting the same associations as the corresponding attribute in an imported
16138 or extended project.
16140 Attributes that are not associative arrays are called simple attributes.
16144 attribute_declaration ::=
16145 full_associative_array_declaration |
16146 @b{for} attribute_designator @b{use} expression ;
16148 full_associative_array_declaration ::=
16149 @b{for} <associative_array_attribute_>simple_name @b{use}
16150 <project_>simple_name [ . <package_>simple_Name ] ' <attribute_>simple_name ;
16152 attribute_designator ::=
16153 <simple_attribute_>simple_name |
16154 <associative_array_attribute_>simple_name ( string_literal )
16158 Some attributes are project-specific, and can only appear immediately within
16159 a project declaration. Others are package-specific, and can only appear within
16160 the proper package.
16162 The expression in an attribute definition must be a string or a string_list.
16163 The string literal appearing in the attribute_designator of an associative
16164 array attribute is case-insensitive.
16166 @node Project Attributes
16167 @section Project Attributes
16170 The following attributes apply to a project. All of them are simple
16175 Expression must be a path name. The attribute defines the
16176 directory in which the object files created by the build are to be placed. If
16177 not specified, object files are placed in the project directory.
16180 Expression must be a path name. The attribute defines the
16181 directory in which the executables created by the build are to be placed.
16182 If not specified, executables are placed in the object directory.
16185 Expression must be a list of path names. The attribute
16186 defines the directories in which the source files for the project are to be
16187 found. If not specified, source files are found in the project directory.
16188 If a string in the list ends with "/**", then the directory that precedes
16189 "/**" and all of its subdirectories (recursively) are included in the list
16190 of source directories.
16192 @item Excluded_Source_Dirs
16193 Expression must be a list of strings. Each entry designates a directory that
16194 is not to be included in the list of source directories of the project.
16195 This is normally used when there are strings ending with "/**" in the value
16196 of attribute Source_Dirs.
16199 Expression must be a list of file names. The attribute
16200 defines the individual files, in the project directory, which are to be used
16201 as sources for the project. File names are path_names that contain no directory
16202 information. If the project has no sources the attribute must be declared
16203 explicitly with an empty list.
16205 @item Excluded_Source_Files (Locally_Removed_Files)
16206 Expression must be a list of strings that are legal file names.
16207 Each file name must designate a source that would normally be a source file
16208 in the source directories of the project or, if the project file is an
16209 extending project file, inherited by the current project file. It cannot
16210 designate an immediate source that is not inherited. Each of the source files
16211 in the list are not considered to be sources of the project file: they are not
16212 inherited. Attribute Locally_Removed_Files is obsolescent, attribute
16213 Excluded_Source_Files is preferred.
16215 @item Source_List_File
16216 Expression must a single path name. The attribute
16217 defines a text file that contains a list of source file names to be used
16218 as sources for the project
16221 Expression must be a path name. The attribute defines the
16222 directory in which a library is to be built. The directory must exist, must
16223 be distinct from the project's object directory, and must be writable.
16226 Expression must be a string that is a legal file name,
16227 without extension. The attribute defines a string that is used to generate
16228 the name of the library to be built by the project.
16231 Argument must be a string value that must be one of the
16232 following @code{"static"}, @code{"dynamic"} or @code{"relocatable"}. This
16233 string is case-insensitive. If this attribute is not specified, the library is
16234 a static library. Otherwise, the library may be dynamic or relocatable. This
16235 distinction is operating-system dependent.
16237 @item Library_Version
16238 Expression must be a string value whose interpretation
16239 is platform dependent. On UNIX, it is used only for dynamic/relocatable
16240 libraries as the internal name of the library (the @code{"soname"}). If the
16241 library file name (built from the @code{Library_Name}) is different from the
16242 @code{Library_Version}, then the library file will be a symbolic link to the
16243 actual file whose name will be @code{Library_Version}.
16245 @item Library_Interface
16246 Expression must be a string list. Each element of the string list
16247 must designate a unit of the project.
16248 If this attribute is present in a Library Project File, then the project
16249 file is a Stand-alone Library_Project_File.
16251 @item Library_Auto_Init
16252 Expression must be a single string "true" or "false", case-insensitive.
16253 If this attribute is present in a Stand-alone Library Project File,
16254 it indicates if initialization is automatic when the dynamic library
16257 @item Library_Options
16258 Expression must be a string list. Indicates additional switches that
16259 are to be used when building a shared library.
16262 Expression must be a single string. Designates an alternative to "gcc"
16263 for building shared libraries.
16265 @item Library_Src_Dir
16266 Expression must be a path name. The attribute defines the
16267 directory in which the sources of the interfaces of a Stand-alone Library will
16268 be copied. The directory must exist, must be distinct from the project's
16269 object directory and source directories of all projects in the project tree,
16270 and must be writable.
16272 @item Library_Src_Dir
16273 Expression must be a path name. The attribute defines the
16274 directory in which the ALI files of a Library will
16275 be copied. The directory must exist, must be distinct from the project's
16276 object directory and source directories of all projects in the project tree,
16277 and must be writable.
16279 @item Library_Symbol_File
16280 Expression must be a single string. Its value is the single file name of a
16281 symbol file to be created when building a stand-alone library when the
16282 symbol policy is either "compliant", "controlled" or "restricted",
16283 on platforms that support symbol control, such as VMS. When symbol policy
16284 is "direct", then a file with this name must exist in the object directory.
16286 @item Library_Reference_Symbol_File
16287 Expression must be a single string. Its value is the path name of a
16288 reference symbol file that is read when the symbol policy is either
16289 "compliant" or "controlled", on platforms that support symbol control,
16290 such as VMS, when building a stand-alone library. The path may be an absolute
16291 path or a path relative to the project directory.
16293 @item Library_Symbol_Policy
16294 Expression must be a single string. Its case-insensitive value can only be
16295 "autonomous", "default", "compliant", "controlled", "restricted" or "direct".
16297 This attribute is not taken into account on all platforms. It controls the
16298 policy for exported symbols and, on some platforms (like VMS) that have the
16299 notions of major and minor IDs built in the library files, it controls
16300 the setting of these IDs.
16302 "autonomous" or "default": exported symbols are not controlled.
16304 "compliant": if attribute Library_Reference_Symbol_File is not defined, then
16305 it is equivalent to policy "autonomous". If there are exported symbols in
16306 the reference symbol file that are not in the object files of the interfaces,
16307 the major ID of the library is increased. If there are symbols in the
16308 object files of the interfaces that are not in the reference symbol file,
16309 these symbols are put at the end of the list in the newly created symbol file
16310 and the minor ID is increased.
16312 "controlled": the attribute Library_Reference_Symbol_File must be defined.
16313 The library will fail to build if the exported symbols in the object files of
16314 the interfaces do not match exactly the symbol in the symbol file.
16316 "restricted": The attribute Library_Symbol_File must be defined. The library
16317 will fail to build if there are symbols in the symbol file that are not in
16318 the exported symbols of the object files of the interfaces. Additional symbols
16319 in the object files are not added to the symbol file.
16321 "direct": The attribute Library_Symbol_File must be defined and must designate
16322 an existing file in the object directory. This symbol file is passed directly
16323 to the underlying linker without any symbol processing.
16326 Expression must be a list of strings that are legal file names.
16327 These file names designate existing compilation units in the source directory
16328 that are legal main subprograms.
16330 When a project file is elaborated, as part of the execution of a gnatmake
16331 command, one or several executables are built and placed in the Exec_Dir.
16332 If the gnatmake command does not include explicit file names, the executables
16333 that are built correspond to the files specified by this attribute.
16335 @item Externally_Built
16336 Expression must be a single string. Its value must be either "true" of "false",
16337 case-insensitive. The default is "false". When the value of this attribute is
16338 "true", no attempt is made to compile the sources or to build the library,
16339 when the project is a library project.
16341 @item Main_Language
16342 This is a simple attribute. Its value is a string that specifies the
16343 language of the main program.
16346 Expression must be a string list. Each string designates
16347 a programming language that is known to GNAT. The strings are case-insensitive.
16351 @node Attribute References
16352 @section Attribute References
16355 Attribute references are used to retrieve the value of previously defined
16356 attribute for a package or project.
16359 attribute_reference ::=
16360 attribute_prefix ' <simple_attribute_>simple_name [ ( string_literal ) ]
16362 attribute_prefix ::=
16364 <project_simple_name | package_identifier |
16365 <project_>simple_name . package_identifier
16369 If an attribute has not been specified for a given package or project, its
16370 value is the null string or the empty list.
16372 @node External Values
16373 @section External Values
16376 An external value is an expression whose value is obtained from the command
16377 that invoked the processing of the current project file (typically a
16383 @b{external} ( string_literal [, string_literal] )
16387 The first string_literal is the string to be used on the command line or
16388 in the environment to specify the external value. The second string_literal,
16389 if present, is the default to use if there is no specification for this
16390 external value either on the command line or in the environment.
16392 @node Case Construction
16393 @section Case Construction
16396 A case construction supports attribute and variable declarations that depend
16397 on the value of a previously declared variable.
16401 case_construction ::=
16402 @b{case} <typed_variable_>name @b{is}
16407 @b{when} discrete_choice_list =>
16408 @{case_construction |
16409 attribute_declaration |
16410 variable_declaration |
16411 empty_declaration@}
16413 discrete_choice_list ::=
16414 string_literal @{| string_literal@} |
16419 Inside a case construction, variable declarations must be for variables that
16420 have already been declared before the case construction.
16422 All choices in a choice list must be distinct. The choice lists of two
16423 distinct alternatives must be disjoint. Unlike Ada, the choice lists of all
16424 alternatives do not need to include all values of the type. An @code{others}
16425 choice must appear last in the list of alternatives.
16431 A package provides a grouping of variable declarations and attribute
16432 declarations to be used when invoking various GNAT tools. The name of
16433 the package indicates the tool(s) to which it applies.
16437 package_declaration ::=
16438 package_spec | package_renaming
16441 @b{package} package_identifier @b{is}
16442 @{simple_declarative_item@}
16443 @b{end} package_identifier ;
16445 package_identifier ::=
16446 @code{Naming} | @code{Builder} | @code{Compiler} | @code{Binder} |
16447 @code{Linker} | @code{Finder} | @code{Cross_Reference} |
16448 @code{gnatls} | @code{IDE} | @code{Pretty_Printer}
16451 @subsection Package Naming
16454 The attributes of a @code{Naming} package specifies the naming conventions
16455 that apply to the source files in a project. When invoking other GNAT tools,
16456 they will use the sources in the source directories that satisfy these
16457 naming conventions.
16459 The following attributes apply to a @code{Naming} package:
16463 This is a simple attribute whose value is a string. Legal values of this
16464 string are @code{"lowercase"}, @code{"uppercase"} or @code{"mixedcase"}.
16465 These strings are themselves case insensitive.
16468 If @code{Casing} is not specified, then the default is @code{"lowercase"}.
16470 @item Dot_Replacement
16471 This is a simple attribute whose string value satisfies the following
16475 @item It must not be empty
16476 @item It cannot start or end with an alphanumeric character
16477 @item It cannot be a single underscore
16478 @item It cannot start with an underscore followed by an alphanumeric
16479 @item It cannot contain a dot @code{'.'} if longer than one character
16483 If @code{Dot_Replacement} is not specified, then the default is @code{"-"}.
16486 This is an associative array attribute, defined on language names,
16487 whose image is a string that must satisfy the following
16491 @item It must not be empty
16492 @item It cannot start with an alphanumeric character
16493 @item It cannot start with an underscore followed by an alphanumeric character
16497 For Ada, the attribute denotes the suffix used in file names that contain
16498 library unit declarations, that is to say units that are package and
16499 subprogram declarations. If @code{Spec_Suffix ("Ada")} is not
16500 specified, then the default is @code{".ads"}.
16502 For C and C++, the attribute denotes the suffix used in file names that
16503 contain prototypes.
16506 This is an associative array attribute defined on language names,
16507 whose image is a string that must satisfy the following
16511 @item It must not be empty
16512 @item It cannot start with an alphanumeric character
16513 @item It cannot start with an underscore followed by an alphanumeric character
16514 @item It cannot be a suffix of @code{Spec_Suffix}
16518 For Ada, the attribute denotes the suffix used in file names that contain
16519 library bodies, that is to say units that are package and subprogram bodies.
16520 If @code{Body_Suffix ("Ada")} is not specified, then the default is
16523 For C and C++, the attribute denotes the suffix used in file names that contain
16526 @item Separate_Suffix
16527 This is a simple attribute whose value satisfies the same conditions as
16528 @code{Body_Suffix}.
16530 This attribute is specific to Ada. It denotes the suffix used in file names
16531 that contain separate bodies. If it is not specified, then it defaults to same
16532 value as @code{Body_Suffix ("Ada")}.
16535 This is an associative array attribute, specific to Ada, defined over
16536 compilation unit names. The image is a string that is the name of the file
16537 that contains that library unit. The file name is case sensitive if the
16538 conventions of the host operating system require it.
16541 This is an associative array attribute, specific to Ada, defined over
16542 compilation unit names. The image is a string that is the name of the file
16543 that contains the library unit body for the named unit. The file name is case
16544 sensitive if the conventions of the host operating system require it.
16546 @item Specification_Exceptions
16547 This is an associative array attribute defined on language names,
16548 whose value is a list of strings.
16550 This attribute is not significant for Ada.
16552 For C and C++, each string in the list denotes the name of a file that
16553 contains prototypes, but whose suffix is not necessarily the
16554 @code{Spec_Suffix} for the language.
16556 @item Implementation_Exceptions
16557 This is an associative array attribute defined on language names,
16558 whose value is a list of strings.
16560 This attribute is not significant for Ada.
16562 For C and C++, each string in the list denotes the name of a file that
16563 contains source code, but whose suffix is not necessarily the
16564 @code{Body_Suffix} for the language.
16567 The following attributes of package @code{Naming} are obsolescent. They are
16568 kept as synonyms of other attributes for compatibility with previous versions
16569 of the Project Manager.
16572 @item Specification_Suffix
16573 This is a synonym of @code{Spec_Suffix}.
16575 @item Implementation_Suffix
16576 This is a synonym of @code{Body_Suffix}.
16578 @item Specification
16579 This is a synonym of @code{Spec}.
16581 @item Implementation
16582 This is a synonym of @code{Body}.
16585 @subsection package Compiler
16588 The attributes of the @code{Compiler} package specify the compilation options
16589 to be used by the underlying compiler.
16592 @item Default_Switches
16593 This is an associative array attribute. Its
16594 domain is a set of language names. Its range is a string list that
16595 specifies the compilation options to be used when compiling a component
16596 written in that language, for which no file-specific switches have been
16600 This is an associative array attribute. Its domain is
16601 a set of file names. Its range is a string list that specifies the
16602 compilation options to be used when compiling the named file. If a file
16603 is not specified in the Switches attribute, it is compiled with the
16604 options specified by Default_Switches of its language, if defined.
16606 @item Local_Configuration_Pragmas.
16607 This is a simple attribute, whose
16608 value is a path name that designates a file containing configuration pragmas
16609 to be used for all invocations of the compiler for immediate sources of the
16613 @subsection package Builder
16616 The attributes of package @code{Builder} specify the compilation, binding, and
16617 linking options to be used when building an executable for a project. The
16618 following attributes apply to package @code{Builder}:
16621 @item Default_Switches
16622 This is an associative array attribute. Its
16623 domain is a set of language names. Its range is a string list that
16624 specifies options to be used when building a main
16625 written in that language, for which no file-specific switches have been
16629 This is an associative array attribute. Its domain is
16630 a set of file names. Its range is a string list that specifies
16631 options to be used when building the named main file. If a main file
16632 is not specified in the Switches attribute, it is built with the
16633 options specified by Default_Switches of its language, if defined.
16635 @item Global_Configuration_Pragmas
16636 This is a simple attribute, whose
16637 value is a path name that designates a file that contains configuration pragmas
16638 to be used in every build of an executable. If both local and global
16639 configuration pragmas are specified, a compilation makes use of both sets.
16643 This is an associative array attribute. Its domain is
16644 a set of main source file names. Its range is a simple string that specifies
16645 the executable file name to be used when linking the specified main source.
16646 If a main source is not specified in the Executable attribute, the executable
16647 file name is deducted from the main source file name.
16648 This attribute has no effect if its value is the empty string.
16650 @item Executable_Suffix
16651 This is a simple attribute whose value is the suffix to be added to
16652 the executables that don't have an attribute Executable specified.
16655 @subsection package Gnatls
16658 The attributes of package @code{Gnatls} specify the tool options to be used
16659 when invoking the library browser @command{gnatls}.
16660 The following attributes apply to package @code{Gnatls}:
16664 This is a single attribute with a string list value. Each nonempty string
16665 in the list is an option when invoking @code{gnatls}.
16668 @subsection package Binder
16671 The attributes of package @code{Binder} specify the options to be used
16672 when invoking the binder in the construction of an executable.
16673 The following attributes apply to package @code{Binder}:
16676 @item Default_Switches
16677 This is an associative array attribute. Its
16678 domain is a set of language names. Its range is a string list that
16679 specifies options to be used when binding a main
16680 written in that language, for which no file-specific switches have been
16684 This is an associative array attribute. Its domain is
16685 a set of file names. Its range is a string list that specifies
16686 options to be used when binding the named main file. If a main file
16687 is not specified in the Switches attribute, it is bound with the
16688 options specified by Default_Switches of its language, if defined.
16691 @subsection package Linker
16694 The attributes of package @code{Linker} specify the options to be used when
16695 invoking the linker in the construction of an executable.
16696 The following attributes apply to package @code{Linker}:
16699 @item Default_Switches
16700 This is an associative array attribute. Its
16701 domain is a set of language names. Its range is a string list that
16702 specifies options to be used when linking a main
16703 written in that language, for which no file-specific switches have been
16707 This is an associative array attribute. Its domain is
16708 a set of file names. Its range is a string list that specifies
16709 options to be used when linking the named main file. If a main file
16710 is not specified in the Switches attribute, it is linked with the
16711 options specified by Default_Switches of its language, if defined.
16713 @item Linker_Options
16714 This is a string list attribute. Its value specifies additional options that
16715 be given to the linker when linking an executable. This attribute is not
16716 used in the main project, only in projects imported directly or indirectly.
16720 @subsection package Cross_Reference
16723 The attributes of package @code{Cross_Reference} specify the tool options
16725 when invoking the library tool @command{gnatxref}.
16726 The following attributes apply to package @code{Cross_Reference}:
16729 @item Default_Switches
16730 This is an associative array attribute. Its
16731 domain is a set of language names. Its range is a string list that
16732 specifies options to be used when calling @command{gnatxref} on a source
16733 written in that language, for which no file-specific switches have been
16737 This is an associative array attribute. Its domain is
16738 a set of file names. Its range is a string list that specifies
16739 options to be used when calling @command{gnatxref} on the named main source.
16740 If a source is not specified in the Switches attribute, @command{gnatxref} will
16741 be called with the options specified by Default_Switches of its language,
16745 @subsection package Finder
16748 The attributes of package @code{Finder} specify the tool options to be used
16749 when invoking the search tool @command{gnatfind}.
16750 The following attributes apply to package @code{Finder}:
16753 @item Default_Switches
16754 This is an associative array attribute. Its
16755 domain is a set of language names. Its range is a string list that
16756 specifies options to be used when calling @command{gnatfind} on a source
16757 written in that language, for which no file-specific switches have been
16761 This is an associative array attribute. Its domain is
16762 a set of file names. Its range is a string list that specifies
16763 options to be used when calling @command{gnatfind} on the named main source.
16764 If a source is not specified in the Switches attribute, @command{gnatfind} will
16765 be called with the options specified by Default_Switches of its language,
16769 @subsection package Pretty_Printer
16772 The attributes of package @code{Pretty_Printer}
16773 specify the tool options to be used
16774 when invoking the formatting tool @command{gnatpp}.
16775 The following attributes apply to package @code{Pretty_Printer}:
16778 @item Default_switches
16779 This is an associative array attribute. Its
16780 domain is a set of language names. Its range is a string list that
16781 specifies options to be used when calling @command{gnatpp} on a source
16782 written in that language, for which no file-specific switches have been
16786 This is an associative array attribute. Its domain is
16787 a set of file names. Its range is a string list that specifies
16788 options to be used when calling @command{gnatpp} on the named main source.
16789 If a source is not specified in the Switches attribute, @command{gnatpp} will
16790 be called with the options specified by Default_Switches of its language,
16794 @subsection package gnatstub
16797 The attributes of package @code{gnatstub}
16798 specify the tool options to be used
16799 when invoking the tool @command{gnatstub}.
16800 The following attributes apply to package @code{gnatstub}:
16803 @item Default_switches
16804 This is an associative array attribute. Its
16805 domain is a set of language names. Its range is a string list that
16806 specifies options to be used when calling @command{gnatstub} on a source
16807 written in that language, for which no file-specific switches have been
16811 This is an associative array attribute. Its domain is
16812 a set of file names. Its range is a string list that specifies
16813 options to be used when calling @command{gnatstub} on the named main source.
16814 If a source is not specified in the Switches attribute, @command{gnatpp} will
16815 be called with the options specified by Default_Switches of its language,
16819 @subsection package Eliminate
16822 The attributes of package @code{Eliminate}
16823 specify the tool options to be used
16824 when invoking the tool @command{gnatelim}.
16825 The following attributes apply to package @code{Eliminate}:
16828 @item Default_switches
16829 This is an associative array attribute. Its
16830 domain is a set of language names. Its range is a string list that
16831 specifies options to be used when calling @command{gnatelim} on a source
16832 written in that language, for which no file-specific switches have been
16836 This is an associative array attribute. Its domain is
16837 a set of file names. Its range is a string list that specifies
16838 options to be used when calling @command{gnatelim} on the named main source.
16839 If a source is not specified in the Switches attribute, @command{gnatelim} will
16840 be called with the options specified by Default_Switches of its language,
16844 @subsection package Metrics
16847 The attributes of package @code{Metrics}
16848 specify the tool options to be used
16849 when invoking the tool @command{gnatmetric}.
16850 The following attributes apply to package @code{Metrics}:
16853 @item Default_switches
16854 This is an associative array attribute. Its
16855 domain is a set of language names. Its range is a string list that
16856 specifies options to be used when calling @command{gnatmetric} on a source
16857 written in that language, for which no file-specific switches have been
16861 This is an associative array attribute. Its domain is
16862 a set of file names. Its range is a string list that specifies
16863 options to be used when calling @command{gnatmetric} on the named main source.
16864 If a source is not specified in the Switches attribute, @command{gnatmetric}
16865 will be called with the options specified by Default_Switches of its language,
16869 @subsection package IDE
16872 The attributes of package @code{IDE} specify the options to be used when using
16873 an Integrated Development Environment such as @command{GPS}.
16877 This is a simple attribute. Its value is a string that designates the remote
16878 host in a cross-compilation environment, to be used for remote compilation and
16879 debugging. This field should not be specified when running on the local
16883 This is a simple attribute. Its value is a string that specifies the
16884 name of IP address of the embedded target in a cross-compilation environment,
16885 on which the program should execute.
16887 @item Communication_Protocol
16888 This is a simple string attribute. Its value is the name of the protocol
16889 to use to communicate with the target in a cross-compilation environment,
16890 e.g.@: @code{"wtx"} or @code{"vxworks"}.
16892 @item Compiler_Command
16893 This is an associative array attribute, whose domain is a language name. Its
16894 value is string that denotes the command to be used to invoke the compiler.
16895 The value of @code{Compiler_Command ("Ada")} is expected to be compatible with
16896 gnatmake, in particular in the handling of switches.
16898 @item Debugger_Command
16899 This is simple attribute, Its value is a string that specifies the name of
16900 the debugger to be used, such as gdb, powerpc-wrs-vxworks-gdb or gdb-4.
16902 @item Default_Switches
16903 This is an associative array attribute. Its indexes are the name of the
16904 external tools that the GNAT Programming System (GPS) is supporting. Its
16905 value is a list of switches to use when invoking that tool.
16908 This is a simple attribute. Its value is a string that specifies the name
16909 of the @command{gnatls} utility to be used to retrieve information about the
16910 predefined path; e.g., @code{"gnatls"}, @code{"powerpc-wrs-vxworks-gnatls"}.
16913 This is a simple attribute. Its value is a string used to specify the
16914 Version Control System (VCS) to be used for this project, e.g.@: CVS, RCS
16915 ClearCase or Perforce.
16917 @item VCS_File_Check
16918 This is a simple attribute. Its value is a string that specifies the
16919 command used by the VCS to check the validity of a file, either
16920 when the user explicitly asks for a check, or as a sanity check before
16921 doing the check-in.
16923 @item VCS_Log_Check
16924 This is a simple attribute. Its value is a string that specifies
16925 the command used by the VCS to check the validity of a log file.
16927 @item VCS_Repository_Root
16928 The VCS repository root path. This is used to create tags or branches
16929 of the repository. For subversion the value should be the @code{URL}
16930 as specified to check-out the working copy of the repository.
16932 @item VCS_Patch_Root
16933 The local root directory to use for building patch file. All patch chunks
16934 will be relative to this path. The root project directory is used if
16935 this value is not defined.
16939 @node Package Renamings
16940 @section Package Renamings
16943 A package can be defined by a renaming declaration. The new package renames
16944 a package declared in a different project file, and has the same attributes
16945 as the package it renames.
16948 package_renaming ::==
16949 @b{package} package_identifier @b{renames}
16950 <project_>simple_name.package_identifier ;
16954 The package_identifier of the renamed package must be the same as the
16955 package_identifier. The project whose name is the prefix of the renamed
16956 package must contain a package declaration with this name. This project
16957 must appear in the context_clause of the enclosing project declaration,
16958 or be the parent project of the enclosing child project.
16964 A project file specifies a set of rules for constructing a software system.
16965 A project file can be self-contained, or depend on other project files.
16966 Dependencies are expressed through a context clause that names other projects.
16972 context_clause project_declaration
16974 project_declaration ::=
16975 simple_project_declaration | project_extension
16977 simple_project_declaration ::=
16978 @b{project} <project_>simple_name @b{is}
16979 @{declarative_item@}
16980 @b{end} <project_>simple_name;
16986 [@b{limited}] @b{with} path_name @{ , path_name @} ;
16993 A path name denotes a project file. A path name can be absolute or relative.
16994 An absolute path name includes a sequence of directories, in the syntax of
16995 the host operating system, that identifies uniquely the project file in the
16996 file system. A relative path name identifies the project file, relative
16997 to the directory that contains the current project, or relative to a
16998 directory listed in the environment variable ADA_PROJECT_PATH.
16999 Path names are case sensitive if file names in the host operating system
17000 are case sensitive.
17002 The syntax of the environment variable ADA_PROJECT_PATH is a list of
17003 directory names separated by colons (semicolons on Windows).
17005 A given project name can appear only once in a context_clause.
17007 It is illegal for a project imported by a context clause to refer, directly
17008 or indirectly, to the project in which this context clause appears (the
17009 dependency graph cannot contain cycles), except when one of the with_clause
17010 in the cycle is a @code{limited with}.
17012 @node Project Extensions
17013 @section Project Extensions
17016 A project extension introduces a new project, which inherits the declarations
17017 of another project.
17021 project_extension ::=
17022 @b{project} <project_>simple_name @b{extends} path_name @b{is}
17023 @{declarative_item@}
17024 @b{end} <project_>simple_name;
17028 The project extension declares a child project. The child project inherits
17029 all the declarations and all the files of the parent project, These inherited
17030 declaration can be overridden in the child project, by means of suitable
17033 @node Project File Elaboration
17034 @section Project File Elaboration
17037 A project file is processed as part of the invocation of a gnat tool that
17038 uses the project option. Elaboration of the process file consists in the
17039 sequential elaboration of all its declarations. The computed values of
17040 attributes and variables in the project are then used to establish the
17041 environment in which the gnat tool will execute.
17043 @node Obsolescent Features
17044 @chapter Obsolescent Features
17047 This chapter describes features that are provided by GNAT, but are
17048 considered obsolescent since there are preferred ways of achieving
17049 the same effect. These features are provided solely for historical
17050 compatibility purposes.
17053 * pragma No_Run_Time::
17054 * pragma Ravenscar::
17055 * pragma Restricted_Run_Time::
17058 @node pragma No_Run_Time
17059 @section pragma No_Run_Time
17061 The pragma @code{No_Run_Time} is used to achieve an affect similar
17062 to the use of the "Zero Foot Print" configurable run time, but without
17063 requiring a specially configured run time. The result of using this
17064 pragma, which must be used for all units in a partition, is to restrict
17065 the use of any language features requiring run-time support code. The
17066 preferred usage is to use an appropriately configured run-time that
17067 includes just those features that are to be made accessible.
17069 @node pragma Ravenscar
17070 @section pragma Ravenscar
17072 The pragma @code{Ravenscar} has exactly the same effect as pragma
17073 @code{Profile (Ravenscar)}. The latter usage is preferred since it
17074 is part of the new Ada 2005 standard.
17076 @node pragma Restricted_Run_Time
17077 @section pragma Restricted_Run_Time
17079 The pragma @code{Restricted_Run_Time} has exactly the same effect as
17080 pragma @code{Profile (Restricted)}. The latter usage is
17081 preferred since the Ada 2005 pragma @code{Profile} is intended for
17082 this kind of implementation dependent addition.
17085 @c GNU Free Documentation License
17087 @node Index,,GNU Free Documentation License, Top