1 \input texinfo @c -*-texinfo-*-
5 @c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo
7 @c GNAT DOCUMENTATION o
11 @c Copyright (C) 1995-2005 Free Software Foundation o
14 @c GNAT is maintained by Ada Core Technologies Inc (http://www.gnat.com). o
16 @c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo
18 @setfilename gnat_rm.info
22 @settitle GNAT Reference Manual
24 @setchapternewpage odd
27 @include gcc-common.texi
29 @dircategory GNU Ada tools
31 * GNAT Reference Manual: (gnat_rm). Reference Manual for GNU Ada tools.
35 Copyright @copyright{} 1995-2004, Free Software Foundation
37 Permission is granted to copy, distribute and/or modify this document
38 under the terms of the GNU Free Documentation License, Version 1.2
39 or any later version published by the Free Software Foundation;
40 with the Invariant Sections being ``GNU Free Documentation License'',
41 with the Front-Cover Texts being ``GNAT Reference Manual'', and with
42 no Back-Cover Texts. A copy of the license is included in the section
43 entitled ``GNU Free Documentation License''.
48 @title GNAT Reference Manual
49 @subtitle GNAT, The GNU Ada 95 Compiler
50 @subtitle GCC version @value{version-GCC}
51 @author Ada Core Technologies, Inc.
54 @vskip 0pt plus 1filll
61 @node Top, About This Guide, (dir), (dir)
62 @top GNAT Reference Manual
68 GNAT, The GNU Ada 95 Compiler@*
69 GCC version @value{version-GCC}@*
76 * Implementation Defined Pragmas::
77 * Implementation Defined Attributes::
78 * Implementation Advice::
79 * Implementation Defined Characteristics::
80 * Intrinsic Subprograms::
81 * Representation Clauses and Pragmas::
82 * Standard Library Routines::
83 * The Implementation of Standard I/O::
85 * Interfacing to Other Languages::
86 * Specialized Needs Annexes::
87 * Implementation of Specific Ada Features::
88 * Project File Reference::
89 * Obsolescent Features::
90 * GNU Free Documentation License::
93 --- The Detailed Node Listing ---
97 * What This Reference Manual Contains::
98 * Related Information::
100 Implementation Defined Pragmas
102 * Pragma Abort_Defer::
109 * Pragma C_Pass_By_Copy::
111 * Pragma Common_Object::
112 * Pragma Compile_Time_Warning::
113 * Pragma Complex_Representation::
114 * Pragma Component_Alignment::
115 * Pragma Convention_Identifier::
117 * Pragma CPP_Constructor::
118 * Pragma CPP_Virtual::
119 * Pragma CPP_Vtable::
121 * Pragma Debug_Policy::
122 * Pragma Detect_Blocking::
123 * Pragma Elaboration_Checks::
125 * Pragma Export_Exception::
126 * Pragma Export_Function::
127 * Pragma Export_Object::
128 * Pragma Export_Procedure::
129 * Pragma Export_Value::
130 * Pragma Export_Valued_Procedure::
131 * Pragma Extend_System::
133 * Pragma External_Name_Casing::
134 * Pragma Finalize_Storage_Only::
135 * Pragma Float_Representation::
137 * Pragma Import_Exception::
138 * Pragma Import_Function::
139 * Pragma Import_Object::
140 * Pragma Import_Procedure::
141 * Pragma Import_Valued_Procedure::
142 * Pragma Initialize_Scalars::
143 * Pragma Inline_Always::
144 * Pragma Inline_Generic::
146 * Pragma Interface_Name::
147 * Pragma Interrupt_Handler::
148 * Pragma Interrupt_State::
149 * Pragma Keep_Names::
152 * Pragma Linker_Alias::
153 * Pragma Linker_Constructor::
154 * Pragma Linker_Destructor::
155 * Pragma Linker_Section::
156 * Pragma Long_Float::
157 * Pragma Machine_Attribute::
158 * Pragma Main_Storage::
160 * Pragma No_Strict_Aliasing ::
161 * Pragma Normalize_Scalars::
162 * Pragma Obsolescent::
164 * Pragma Persistent_BSS::
166 * Pragma Profile (Ravenscar)::
167 * Pragma Profile (Restricted)::
168 * Pragma Propagate_Exceptions::
169 * Pragma Psect_Object::
170 * Pragma Pure_Function::
171 * Pragma Restriction_Warnings::
172 * Pragma Source_File_Name::
173 * Pragma Source_File_Name_Project::
174 * Pragma Source_Reference::
175 * Pragma Stream_Convert::
176 * Pragma Style_Checks::
178 * Pragma Suppress_All::
179 * Pragma Suppress_Exception_Locations::
180 * Pragma Suppress_Initialization::
183 * Pragma Task_Storage::
184 * Pragma Thread_Body::
185 * Pragma Time_Slice::
187 * Pragma Unchecked_Union::
188 * Pragma Unimplemented_Unit::
189 * Pragma Universal_Data::
190 * Pragma Unreferenced::
191 * Pragma Unreserve_All_Interrupts::
192 * Pragma Unsuppress::
193 * Pragma Use_VADS_Size::
194 * Pragma Validity_Checks::
197 * Pragma Weak_External::
199 Implementation Defined Attributes
209 * Default_Bit_Order::
217 * Has_Access_Values::
218 * Has_Discriminants::
224 * Max_Interrupt_Priority::
226 * Maximum_Alignment::
230 * Passed_By_Reference::
241 * Unconstrained_Array::
242 * Universal_Literal_String::
243 * Unrestricted_Access::
249 The Implementation of Standard I/O
251 * Standard I/O Packages::
257 * Wide_Wide_Text_IO::
261 * Operations on C Streams::
262 * Interfacing to C Streams::
266 * Ada.Characters.Latin_9 (a-chlat9.ads)::
267 * Ada.Characters.Wide_Latin_1 (a-cwila1.ads)::
268 * Ada.Characters.Wide_Latin_9 (a-cwila9.ads)::
269 * Ada.Characters.Wide_Wide_Latin_1 (a-czila1.ads)::
270 * Ada.Characters.Wide_Wide_Latin_9 (a-czila9.ads)::
271 * Ada.Command_Line.Remove (a-colire.ads)::
272 * Ada.Command_Line.Environment (a-colien.ads)::
273 * Ada.Direct_IO.C_Streams (a-diocst.ads)::
274 * Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads)::
275 * Ada.Exceptions.Traceback (a-exctra.ads)::
276 * Ada.Sequential_IO.C_Streams (a-siocst.ads)::
277 * Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads)::
278 * Ada.Strings.Unbounded.Text_IO (a-suteio.ads)::
279 * Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads)::
280 * Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads)::
281 * Ada.Text_IO.C_Streams (a-tiocst.ads)::
282 * Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads)::
283 * Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads)::
284 * GNAT.Array_Split (g-arrspl.ads)::
285 * GNAT.AWK (g-awk.ads)::
286 * GNAT.Bounded_Buffers (g-boubuf.ads)::
287 * GNAT.Bounded_Mailboxes (g-boumai.ads)::
288 * GNAT.Bubble_Sort (g-bubsor.ads)::
289 * GNAT.Bubble_Sort_A (g-busora.ads)::
290 * GNAT.Bubble_Sort_G (g-busorg.ads)::
291 * GNAT.Calendar (g-calend.ads)::
292 * GNAT.Calendar.Time_IO (g-catiio.ads)::
293 * GNAT.Case_Util (g-casuti.ads)::
294 * GNAT.CGI (g-cgi.ads)::
295 * GNAT.CGI.Cookie (g-cgicoo.ads)::
296 * GNAT.CGI.Debug (g-cgideb.ads)::
297 * GNAT.Command_Line (g-comlin.ads)::
298 * GNAT.Compiler_Version (g-comver.ads)::
299 * GNAT.Ctrl_C (g-ctrl_c.ads)::
300 * GNAT.CRC32 (g-crc32.ads)::
301 * GNAT.Current_Exception (g-curexc.ads)::
302 * GNAT.Debug_Pools (g-debpoo.ads)::
303 * GNAT.Debug_Utilities (g-debuti.ads)::
304 * GNAT.Directory_Operations (g-dirope.ads)::
305 * GNAT.Dynamic_HTables (g-dynhta.ads)::
306 * GNAT.Dynamic_Tables (g-dyntab.ads)::
307 * GNAT.Exception_Actions (g-excact.ads)::
308 * GNAT.Exception_Traces (g-exctra.ads)::
309 * GNAT.Exceptions (g-except.ads)::
310 * GNAT.Expect (g-expect.ads)::
311 * GNAT.Float_Control (g-flocon.ads)::
312 * GNAT.Heap_Sort (g-heasor.ads)::
313 * GNAT.Heap_Sort_A (g-hesora.ads)::
314 * GNAT.Heap_Sort_G (g-hesorg.ads)::
315 * GNAT.HTable (g-htable.ads)::
316 * GNAT.IO (g-io.ads)::
317 * GNAT.IO_Aux (g-io_aux.ads)::
318 * GNAT.Lock_Files (g-locfil.ads)::
319 * GNAT.MD5 (g-md5.ads)::
320 * GNAT.Memory_Dump (g-memdum.ads)::
321 * GNAT.Most_Recent_Exception (g-moreex.ads)::
322 * GNAT.OS_Lib (g-os_lib.ads)::
323 * GNAT.Perfect_Hash_Generators (g-pehage.ads)::
324 * GNAT.Regexp (g-regexp.ads)::
325 * GNAT.Registry (g-regist.ads)::
326 * GNAT.Regpat (g-regpat.ads)::
327 * GNAT.Secondary_Stack_Info (g-sestin.ads)::
328 * GNAT.Semaphores (g-semaph.ads)::
329 * GNAT.Signals (g-signal.ads)::
330 * GNAT.Sockets (g-socket.ads)::
331 * GNAT.Source_Info (g-souinf.ads)::
332 * GNAT.Spell_Checker (g-speche.ads)::
333 * GNAT.Spitbol.Patterns (g-spipat.ads)::
334 * GNAT.Spitbol (g-spitbo.ads)::
335 * GNAT.Spitbol.Table_Boolean (g-sptabo.ads)::
336 * GNAT.Spitbol.Table_Integer (g-sptain.ads)::
337 * GNAT.Spitbol.Table_VString (g-sptavs.ads)::
338 * GNAT.Strings (g-string.ads)::
339 * GNAT.String_Split (g-strspl.ads)::
340 * GNAT.Table (g-table.ads)::
341 * GNAT.Task_Lock (g-tasloc.ads)::
342 * GNAT.Threads (g-thread.ads)::
343 * GNAT.Traceback (g-traceb.ads)::
344 * GNAT.Traceback.Symbolic (g-trasym.ads)::
345 * GNAT.Wide_String_Split (g-wistsp.ads)::
346 * GNAT.Wide_Wide_String_Split (g-zistsp.ads)::
347 * Interfaces.C.Extensions (i-cexten.ads)::
348 * Interfaces.C.Streams (i-cstrea.ads)::
349 * Interfaces.CPP (i-cpp.ads)::
350 * Interfaces.Os2lib (i-os2lib.ads)::
351 * Interfaces.Os2lib.Errors (i-os2err.ads)::
352 * Interfaces.Os2lib.Synchronization (i-os2syn.ads)::
353 * Interfaces.Os2lib.Threads (i-os2thr.ads)::
354 * Interfaces.Packed_Decimal (i-pacdec.ads)::
355 * Interfaces.VxWorks (i-vxwork.ads)::
356 * Interfaces.VxWorks.IO (i-vxwoio.ads)::
357 * System.Address_Image (s-addima.ads)::
358 * System.Assertions (s-assert.ads)::
359 * System.Memory (s-memory.ads)::
360 * System.Partition_Interface (s-parint.ads)::
361 * System.Restrictions (s-restri.ads)::
362 * System.Rident (s-rident.ads)::
363 * System.Task_Info (s-tasinf.ads)::
364 * System.Wch_Cnv (s-wchcnv.ads)::
365 * System.Wch_Con (s-wchcon.ads)::
369 * Text_IO Stream Pointer Positioning::
370 * Text_IO Reading and Writing Non-Regular Files::
372 * Treating Text_IO Files as Streams::
373 * Text_IO Extensions::
374 * Text_IO Facilities for Unbounded Strings::
378 * Wide_Text_IO Stream Pointer Positioning::
379 * Wide_Text_IO Reading and Writing Non-Regular Files::
383 * Wide_Wide_Text_IO Stream Pointer Positioning::
384 * Wide_Wide_Text_IO Reading and Writing Non-Regular Files::
386 Interfacing to Other Languages
389 * Interfacing to C++::
390 * Interfacing to COBOL::
391 * Interfacing to Fortran::
392 * Interfacing to non-GNAT Ada code::
394 Specialized Needs Annexes
396 Implementation of Specific Ada Features
397 * Machine Code Insertions::
398 * GNAT Implementation of Tasking::
399 * GNAT Implementation of Shared Passive Packages::
400 * Code Generation for Array Aggregates::
401 * The Size of Discriminated Records with Default Discriminants::
403 Project File Reference
407 GNU Free Documentation License
414 @node About This Guide
415 @unnumbered About This Guide
419 This manual contains useful information in writing programs using the
420 GNAT compiler. It includes information on implementation dependent
421 characteristics of GNAT, including all the information required by Annex
427 This manual contains useful information in writing programs using the
428 GNAT Pro compiler. It includes information on implementation dependent
429 characteristics of GNAT Pro, including all the information required by Annex
433 Ada 95 is designed to be highly portable.
434 In general, a program will have the same effect even when compiled by
435 different compilers on different platforms.
436 However, since Ada 95 is designed to be used in a
437 wide variety of applications, it also contains a number of system
438 dependent features to be used in interfacing to the external world.
439 @cindex Implementation-dependent features
442 Note: Any program that makes use of implementation-dependent features
443 may be non-portable. You should follow good programming practice and
444 isolate and clearly document any sections of your program that make use
445 of these features in a non-portable manner.
448 For ease of exposition, ``GNAT Pro'' will be referred to simply as
449 ``GNAT'' in the remainder of this document.
453 * What This Reference Manual Contains::
455 * Related Information::
458 @node What This Reference Manual Contains
459 @unnumberedsec What This Reference Manual Contains
462 This reference manual contains the following chapters:
466 @ref{Implementation Defined Pragmas}, lists GNAT implementation-dependent
467 pragmas, which can be used to extend and enhance the functionality of the
471 @ref{Implementation Defined Attributes}, lists GNAT
472 implementation-dependent attributes which can be used to extend and
473 enhance the functionality of the compiler.
476 @ref{Implementation Advice}, provides information on generally
477 desirable behavior which are not requirements that all compilers must
478 follow since it cannot be provided on all systems, or which may be
479 undesirable on some systems.
482 @ref{Implementation Defined Characteristics}, provides a guide to
483 minimizing implementation dependent features.
486 @ref{Intrinsic Subprograms}, describes the intrinsic subprograms
487 implemented by GNAT, and how they can be imported into user
488 application programs.
491 @ref{Representation Clauses and Pragmas}, describes in detail the
492 way that GNAT represents data, and in particular the exact set
493 of representation clauses and pragmas that is accepted.
496 @ref{Standard Library Routines}, provides a listing of packages and a
497 brief description of the functionality that is provided by Ada's
498 extensive set of standard library routines as implemented by GNAT@.
501 @ref{The Implementation of Standard I/O}, details how the GNAT
502 implementation of the input-output facilities.
505 @ref{The GNAT Library}, is a catalog of packages that complement
506 the Ada predefined library.
509 @ref{Interfacing to Other Languages}, describes how programs
510 written in Ada using GNAT can be interfaced to other programming
513 @ref{Specialized Needs Annexes}, describes the GNAT implementation of all
514 of the specialized needs annexes.
517 @ref{Implementation of Specific Ada Features}, discusses issues related
518 to GNAT's implementation of machine code insertions, tasking, and several
522 @ref{Project File Reference}, presents the syntax and semantics
526 @ref{Obsolescent Features} documents implementation dependent features,
527 including pragmas and attributes, which are considered obsolescent, since
528 there are other preferred ways of achieving the same results. These
529 obsolescent forms are retained for backwards compatibility.
533 @cindex Ada 95 ISO/ANSI Standard
535 This reference manual assumes that you are familiar with Ada 95
536 language, as described in the International Standard
537 ANSI/ISO/IEC-8652:1995, Jan 1995.
540 @unnumberedsec Conventions
541 @cindex Conventions, typographical
542 @cindex Typographical conventions
545 Following are examples of the typographical and graphic conventions used
550 @code{Functions}, @code{utility program names}, @code{standard names},
557 @file{File Names}, @samp{button names}, and @samp{field names}.
566 [optional information or parameters]
569 Examples are described by text
571 and then shown this way.
576 Commands that are entered by the user are preceded in this manual by the
577 characters @samp{$ } (dollar sign followed by space). If your system uses this
578 sequence as a prompt, then the commands will appear exactly as you see them
579 in the manual. If your system uses some other prompt, then the command will
580 appear with the @samp{$} replaced by whatever prompt character you are using.
582 @node Related Information
583 @unnumberedsec Related Information
585 See the following documents for further information on GNAT:
589 @cite{GNAT User's Guide}, which provides information on how to use
590 the GNAT compiler system.
593 @cite{Ada 95 Reference Manual}, which contains all reference
594 material for the Ada 95 programming language.
597 @cite{Ada 95 Annotated Reference Manual}, which is an annotated version
598 of the standard reference manual cited above. The annotations describe
599 detailed aspects of the design decision, and in particular contain useful
600 sections on Ada 83 compatibility.
603 @cite{DEC Ada, Technical Overview and Comparison on DIGITAL Platforms},
604 which contains specific information on compatibility between GNAT and
608 @cite{DEC Ada, Language Reference Manual, part number AA-PYZAB-TK} which
609 describes in detail the pragmas and attributes provided by the DEC Ada 83
614 @node Implementation Defined Pragmas
615 @chapter Implementation Defined Pragmas
618 Ada 95 defines a set of pragmas that can be used to supply additional
619 information to the compiler. These language defined pragmas are
620 implemented in GNAT and work as described in the Ada 95 Reference
623 In addition, Ada 95 allows implementations to define additional pragmas
624 whose meaning is defined by the implementation. GNAT provides a number
625 of these implementation-dependent pragmas which can be used to extend
626 and enhance the functionality of the compiler. This section of the GNAT
627 Reference Manual describes these additional pragmas.
629 Note that any program using these pragmas may not be portable to other
630 compilers (although GNAT implements this set of pragmas on all
631 platforms). Therefore if portability to other compilers is an important
632 consideration, the use of these pragmas should be minimized.
635 * Pragma Abort_Defer::
642 * Pragma C_Pass_By_Copy::
644 * Pragma Common_Object::
645 * Pragma Compile_Time_Warning::
646 * Pragma Complex_Representation::
647 * Pragma Component_Alignment::
648 * Pragma Convention_Identifier::
650 * Pragma CPP_Constructor::
651 * Pragma CPP_Virtual::
652 * Pragma CPP_Vtable::
654 * Pragma Debug_Policy::
655 * Pragma Detect_Blocking::
656 * Pragma Elaboration_Checks::
658 * Pragma Export_Exception::
659 * Pragma Export_Function::
660 * Pragma Export_Object::
661 * Pragma Export_Procedure::
662 * Pragma Export_Value::
663 * Pragma Export_Valued_Procedure::
664 * Pragma Extend_System::
666 * Pragma External_Name_Casing::
667 * Pragma Finalize_Storage_Only::
668 * Pragma Float_Representation::
670 * Pragma Import_Exception::
671 * Pragma Import_Function::
672 * Pragma Import_Object::
673 * Pragma Import_Procedure::
674 * Pragma Import_Valued_Procedure::
675 * Pragma Initialize_Scalars::
676 * Pragma Inline_Always::
677 * Pragma Inline_Generic::
679 * Pragma Interface_Name::
680 * Pragma Interrupt_Handler::
681 * Pragma Interrupt_State::
682 * Pragma Keep_Names::
685 * Pragma Linker_Alias::
686 * Pragma Linker_Constructor::
687 * Pragma Linker_Destructor::
688 * Pragma Linker_Section::
689 * Pragma Long_Float::
690 * Pragma Machine_Attribute::
691 * Pragma Main_Storage::
693 * Pragma No_Strict_Aliasing::
694 * Pragma Normalize_Scalars::
695 * Pragma Obsolescent::
697 * Pragma Persistent_BSS::
699 * Pragma Profile (Ravenscar)::
700 * Pragma Profile (Restricted)::
701 * Pragma Propagate_Exceptions::
702 * Pragma Psect_Object::
703 * Pragma Pure_Function::
704 * Pragma Restriction_Warnings::
705 * Pragma Source_File_Name::
706 * Pragma Source_File_Name_Project::
707 * Pragma Source_Reference::
708 * Pragma Stream_Convert::
709 * Pragma Style_Checks::
711 * Pragma Suppress_All::
712 * Pragma Suppress_Exception_Locations::
713 * Pragma Suppress_Initialization::
716 * Pragma Task_Storage::
717 * Pragma Thread_Body::
718 * Pragma Time_Slice::
720 * Pragma Unchecked_Union::
721 * Pragma Unimplemented_Unit::
722 * Pragma Universal_Data::
723 * Pragma Unreferenced::
724 * Pragma Unreserve_All_Interrupts::
725 * Pragma Unsuppress::
726 * Pragma Use_VADS_Size::
727 * Pragma Validity_Checks::
730 * Pragma Weak_External::
733 @node Pragma Abort_Defer
734 @unnumberedsec Pragma Abort_Defer
736 @cindex Deferring aborts
744 This pragma must appear at the start of the statement sequence of a
745 handled sequence of statements (right after the @code{begin}). It has
746 the effect of deferring aborts for the sequence of statements (but not
747 for the declarations or handlers, if any, associated with this statement
751 @unnumberedsec Pragma Ada_83
760 A configuration pragma that establishes Ada 83 mode for the unit to
761 which it applies, regardless of the mode set by the command line
762 switches. In Ada 83 mode, GNAT attempts to be as compatible with
763 the syntax and semantics of Ada 83, as defined in the original Ada
764 83 Reference Manual as possible. In particular, the new Ada 95
765 keywords are not recognized, optional package bodies are allowed,
766 and generics may name types with unknown discriminants without using
767 the @code{(<>)} notation. In addition, some but not all of the additional
768 restrictions of Ada 83 are enforced.
770 Ada 83 mode is intended for two purposes. Firstly, it allows existing
771 legacy Ada 83 code to be compiled and adapted to GNAT with less effort.
772 Secondly, it aids in keeping code backwards compatible with Ada 83.
773 However, there is no guarantee that code that is processed correctly
774 by GNAT in Ada 83 mode will in fact compile and execute with an Ada
775 83 compiler, since GNAT does not enforce all the additional checks
779 @unnumberedsec Pragma Ada_95
788 A configuration pragma that establishes Ada 95 mode for the unit to which
789 it applies, regardless of the mode set by the command line switches.
790 This mode is set automatically for the @code{Ada} and @code{System}
791 packages and their children, so you need not specify it in these
792 contexts. This pragma is useful when writing a reusable component that
793 itself uses Ada 95 features, but which is intended to be usable from
794 either Ada 83 or Ada 95 programs.
797 @unnumberedsec Pragma Ada_05
806 A configuration pragma that establishes Ada 2005 mode for the unit to which
807 it applies, regardless of the mode set by the command line switches.
808 This mode is set automatically for the @code{Ada} and @code{System}
809 packages and their children, so you need not specify it in these
810 contexts. This pragma is useful when writing a reusable component that
811 itself uses Ada 2005 features, but which is intended to be usable from
812 either Ada 83 or Ada 95 programs.
814 @node Pragma Annotate
815 @unnumberedsec Pragma Annotate
820 pragma Annotate (IDENTIFIER @{, ARG@});
822 ARG ::= NAME | EXPRESSION
826 This pragma is used to annotate programs. @var{identifier} identifies
827 the type of annotation. GNAT verifies this is an identifier, but does
828 not otherwise analyze it. The @var{arg} argument
829 can be either a string literal or an
830 expression. String literals are assumed to be of type
831 @code{Standard.String}. Names of entities are simply analyzed as entity
832 names. All other expressions are analyzed as expressions, and must be
835 The analyzed pragma is retained in the tree, but not otherwise processed
836 by any part of the GNAT compiler. This pragma is intended for use by
837 external tools, including ASIS@.
840 @unnumberedsec Pragma Assert
847 [, static_string_EXPRESSION]);
851 The effect of this pragma depends on whether the corresponding command
852 line switch is set to activate assertions. The pragma expands into code
853 equivalent to the following:
856 if assertions-enabled then
857 if not boolean_EXPRESSION then
858 System.Assertions.Raise_Assert_Failure
865 The string argument, if given, is the message that will be associated
866 with the exception occurrence if the exception is raised. If no second
867 argument is given, the default message is @samp{@var{file}:@var{nnn}},
868 where @var{file} is the name of the source file containing the assert,
869 and @var{nnn} is the line number of the assert. A pragma is not a
870 statement, so if a statement sequence contains nothing but a pragma
871 assert, then a null statement is required in addition, as in:
876 pragma Assert (K > 3, "Bad value for K");
882 Note that, as with the @code{if} statement to which it is equivalent, the
883 type of the expression is either @code{Standard.Boolean}, or any type derived
884 from this standard type.
886 If assertions are disabled (switch @code{-gnata} not used), then there
887 is no effect (and in particular, any side effects from the expression
888 are suppressed). More precisely it is not quite true that the pragma
889 has no effect, since the expression is analyzed, and may cause types
890 to be frozen if they are mentioned here for the first time.
892 If assertions are enabled, then the given expression is tested, and if
893 it is @code{False} then @code{System.Assertions.Raise_Assert_Failure} is called
894 which results in the raising of @code{Assert_Failure} with the given message.
896 If the boolean expression has side effects, these side effects will turn
897 on and off with the setting of the assertions mode, resulting in
898 assertions that have an effect on the program. You should generally
899 avoid side effects in the expression arguments of this pragma. However,
900 the expressions are analyzed for semantic correctness whether or not
901 assertions are enabled, so turning assertions on and off cannot affect
902 the legality of a program.
904 @node Pragma Ast_Entry
905 @unnumberedsec Pragma Ast_Entry
911 pragma AST_Entry (entry_IDENTIFIER);
915 This pragma is implemented only in the OpenVMS implementation of GNAT@. The
916 argument is the simple name of a single entry; at most one @code{AST_Entry}
917 pragma is allowed for any given entry. This pragma must be used in
918 conjunction with the @code{AST_Entry} attribute, and is only allowed after
919 the entry declaration and in the same task type specification or single task
920 as the entry to which it applies. This pragma specifies that the given entry
921 may be used to handle an OpenVMS asynchronous system trap (@code{AST})
922 resulting from an OpenVMS system service call. The pragma does not affect
923 normal use of the entry. For further details on this pragma, see the
924 DEC Ada Language Reference Manual, section 9.12a.
926 @node Pragma C_Pass_By_Copy
927 @unnumberedsec Pragma C_Pass_By_Copy
928 @cindex Passing by copy
929 @findex C_Pass_By_Copy
933 pragma C_Pass_By_Copy
934 ([Max_Size =>] static_integer_EXPRESSION);
938 Normally the default mechanism for passing C convention records to C
939 convention subprograms is to pass them by reference, as suggested by RM
940 B.3(69). Use the configuration pragma @code{C_Pass_By_Copy} to change
941 this default, by requiring that record formal parameters be passed by
942 copy if all of the following conditions are met:
946 The size of the record type does not exceed@*@var{static_integer_expression}.
948 The record type has @code{Convention C}.
950 The formal parameter has this record type, and the subprogram has a
951 foreign (non-Ada) convention.
955 If these conditions are met the argument is passed by copy, i.e.@: in a
956 manner consistent with what C expects if the corresponding formal in the
957 C prototype is a struct (rather than a pointer to a struct).
959 You can also pass records by copy by specifying the convention
960 @code{C_Pass_By_Copy} for the record type, or by using the extended
961 @code{Import} and @code{Export} pragmas, which allow specification of
962 passing mechanisms on a parameter by parameter basis.
965 @unnumberedsec Pragma Comment
971 pragma Comment (static_string_EXPRESSION);
975 This is almost identical in effect to pragma @code{Ident}. It allows the
976 placement of a comment into the object file and hence into the
977 executable file if the operating system permits such usage. The
978 difference is that @code{Comment}, unlike @code{Ident}, has
979 no limitations on placement of the pragma (it can be placed
980 anywhere in the main source unit), and if more than one pragma
981 is used, all comments are retained.
983 @node Pragma Common_Object
984 @unnumberedsec Pragma Common_Object
985 @findex Common_Object
990 pragma Common_Object (
991 [Internal =>] local_NAME,
992 [, [External =>] EXTERNAL_SYMBOL]
993 [, [Size =>] EXTERNAL_SYMBOL] );
997 | static_string_EXPRESSION
1001 This pragma enables the shared use of variables stored in overlaid
1002 linker areas corresponding to the use of @code{COMMON}
1003 in Fortran. The single
1004 object @var{local_NAME} is assigned to the area designated by
1005 the @var{External} argument.
1006 You may define a record to correspond to a series
1007 of fields. The @var{size} argument
1008 is syntax checked in GNAT, but otherwise ignored.
1010 @code{Common_Object} is not supported on all platforms. If no
1011 support is available, then the code generator will issue a message
1012 indicating that the necessary attribute for implementation of this
1013 pragma is not available.
1015 @node Pragma Compile_Time_Warning
1016 @unnumberedsec Pragma Compile_Time_Warning
1017 @findex Compile_Time_Warning
1021 @smallexample @c ada
1022 pragma Compile_Time_Warning
1023 (boolean_EXPRESSION, static_string_EXPRESSION);
1027 This pragma can be used to generate additional compile time warnings. It
1028 is particularly useful in generics, where warnings can be issued for
1029 specific problematic instantiations. The first parameter is a boolean
1030 expression. The pragma is effective only if the value of this expression
1031 is known at compile time, and has the value True. The set of expressions
1032 whose values are known at compile time includes all static boolean
1033 expressions, and also other values which the compiler can determine
1034 at compile time (e.g. the size of a record type set by an explicit
1035 size representation clause, or the value of a variable which was
1036 initialized to a constant and is known not to have been modified).
1037 If these conditions are met, a warning message is generated using
1038 the value given as the second argument. This string value may contain
1039 embedded ASCII.LF characters to break the message into multiple lines.
1041 @node Pragma Complex_Representation
1042 @unnumberedsec Pragma Complex_Representation
1043 @findex Complex_Representation
1047 @smallexample @c ada
1048 pragma Complex_Representation
1049 ([Entity =>] local_NAME);
1053 The @var{Entity} argument must be the name of a record type which has
1054 two fields of the same floating-point type. The effect of this pragma is
1055 to force gcc to use the special internal complex representation form for
1056 this record, which may be more efficient. Note that this may result in
1057 the code for this type not conforming to standard ABI (application
1058 binary interface) requirements for the handling of record types. For
1059 example, in some environments, there is a requirement for passing
1060 records by pointer, and the use of this pragma may result in passing
1061 this type in floating-point registers.
1063 @node Pragma Component_Alignment
1064 @unnumberedsec Pragma Component_Alignment
1065 @cindex Alignments of components
1066 @findex Component_Alignment
1070 @smallexample @c ada
1071 pragma Component_Alignment (
1072 [Form =>] ALIGNMENT_CHOICE
1073 [, [Name =>] type_local_NAME]);
1075 ALIGNMENT_CHOICE ::=
1083 Specifies the alignment of components in array or record types.
1084 The meaning of the @var{Form} argument is as follows:
1087 @findex Component_Size
1088 @item Component_Size
1089 Aligns scalar components and subcomponents of the array or record type
1090 on boundaries appropriate to their inherent size (naturally
1091 aligned). For example, 1-byte components are aligned on byte boundaries,
1092 2-byte integer components are aligned on 2-byte boundaries, 4-byte
1093 integer components are aligned on 4-byte boundaries and so on. These
1094 alignment rules correspond to the normal rules for C compilers on all
1095 machines except the VAX@.
1097 @findex Component_Size_4
1098 @item Component_Size_4
1099 Naturally aligns components with a size of four or fewer
1100 bytes. Components that are larger than 4 bytes are placed on the next
1103 @findex Storage_Unit
1105 Specifies that array or record components are byte aligned, i.e.@:
1106 aligned on boundaries determined by the value of the constant
1107 @code{System.Storage_Unit}.
1111 Specifies that array or record components are aligned on default
1112 boundaries, appropriate to the underlying hardware or operating system or
1113 both. For OpenVMS VAX systems, the @code{Default} choice is the same as
1114 the @code{Storage_Unit} choice (byte alignment). For all other systems,
1115 the @code{Default} choice is the same as @code{Component_Size} (natural
1120 If the @code{Name} parameter is present, @var{type_local_NAME} must
1121 refer to a local record or array type, and the specified alignment
1122 choice applies to the specified type. The use of
1123 @code{Component_Alignment} together with a pragma @code{Pack} causes the
1124 @code{Component_Alignment} pragma to be ignored. The use of
1125 @code{Component_Alignment} together with a record representation clause
1126 is only effective for fields not specified by the representation clause.
1128 If the @code{Name} parameter is absent, the pragma can be used as either
1129 a configuration pragma, in which case it applies to one or more units in
1130 accordance with the normal rules for configuration pragmas, or it can be
1131 used within a declarative part, in which case it applies to types that
1132 are declared within this declarative part, or within any nested scope
1133 within this declarative part. In either case it specifies the alignment
1134 to be applied to any record or array type which has otherwise standard
1137 If the alignment for a record or array type is not specified (using
1138 pragma @code{Pack}, pragma @code{Component_Alignment}, or a record rep
1139 clause), the GNAT uses the default alignment as described previously.
1141 @node Pragma Convention_Identifier
1142 @unnumberedsec Pragma Convention_Identifier
1143 @findex Convention_Identifier
1144 @cindex Conventions, synonyms
1148 @smallexample @c ada
1149 pragma Convention_Identifier (
1150 [Name =>] IDENTIFIER,
1151 [Convention =>] convention_IDENTIFIER);
1155 This pragma provides a mechanism for supplying synonyms for existing
1156 convention identifiers. The @code{Name} identifier can subsequently
1157 be used as a synonym for the given convention in other pragmas (including
1158 for example pragma @code{Import} or another @code{Convention_Identifier}
1159 pragma). As an example of the use of this, suppose you had legacy code
1160 which used Fortran77 as the identifier for Fortran. Then the pragma:
1162 @smallexample @c ada
1163 pragma Convention_Identifier (Fortran77, Fortran);
1167 would allow the use of the convention identifier @code{Fortran77} in
1168 subsequent code, avoiding the need to modify the sources. As another
1169 example, you could use this to parametrize convention requirements
1170 according to systems. Suppose you needed to use @code{Stdcall} on
1171 windows systems, and @code{C} on some other system, then you could
1172 define a convention identifier @code{Library} and use a single
1173 @code{Convention_Identifier} pragma to specify which convention
1174 would be used system-wide.
1176 @node Pragma CPP_Class
1177 @unnumberedsec Pragma CPP_Class
1179 @cindex Interfacing with C++
1183 @smallexample @c ada
1184 pragma CPP_Class ([Entity =>] local_NAME);
1188 The argument denotes an entity in the current declarative region
1189 that is declared as a tagged or untagged record type. It indicates that
1190 the type corresponds to an externally declared C++ class type, and is to
1191 be laid out the same way that C++ would lay out the type.
1193 If (and only if) the type is tagged, at least one component in the
1194 record must be of type @code{Interfaces.CPP.Vtable_Ptr}, corresponding
1195 to the C++ Vtable (or Vtables in the case of multiple inheritance) used
1198 Types for which @code{CPP_Class} is specified do not have assignment or
1199 equality operators defined (such operations can be imported or declared
1200 as subprograms as required). Initialization is allowed only by
1201 constructor functions (see pragma @code{CPP_Constructor}).
1203 Pragma @code{CPP_Class} is intended primarily for automatic generation
1204 using an automatic binding generator tool.
1205 See @ref{Interfacing to C++} for related information.
1207 @node Pragma CPP_Constructor
1208 @unnumberedsec Pragma CPP_Constructor
1209 @cindex Interfacing with C++
1210 @findex CPP_Constructor
1214 @smallexample @c ada
1215 pragma CPP_Constructor ([Entity =>] local_NAME);
1219 This pragma identifies an imported function (imported in the usual way
1220 with pragma @code{Import}) as corresponding to a C++
1221 constructor. The argument is a name that must have been
1222 previously mentioned in a pragma @code{Import}
1223 with @code{Convention} = @code{CPP}, and must be of one of the following
1228 @code{function @var{Fname} return @var{T}'Class}
1231 @code{function @var{Fname} (@dots{}) return @var{T}'Class}
1235 where @var{T} is a tagged type to which the pragma @code{CPP_Class} applies.
1237 The first form is the default constructor, used when an object of type
1238 @var{T} is created on the Ada side with no explicit constructor. Other
1239 constructors (including the copy constructor, which is simply a special
1240 case of the second form in which the one and only argument is of type
1241 @var{T}), can only appear in two contexts:
1245 On the right side of an initialization of an object of type @var{T}.
1247 In an extension aggregate for an object of a type derived from @var{T}.
1251 Although the constructor is described as a function that returns a value
1252 on the Ada side, it is typically a procedure with an extra implicit
1253 argument (the object being initialized) at the implementation
1254 level. GNAT issues the appropriate call, whatever it is, to get the
1255 object properly initialized.
1257 In the case of derived objects, you may use one of two possible forms
1258 for declaring and creating an object:
1261 @item @code{New_Object : Derived_T}
1262 @item @code{New_Object : Derived_T := (@var{constructor-call with} @dots{})}
1266 In the first case the default constructor is called and extension fields
1267 if any are initialized according to the default initialization
1268 expressions in the Ada declaration. In the second case, the given
1269 constructor is called and the extension aggregate indicates the explicit
1270 values of the extension fields.
1272 If no constructors are imported, it is impossible to create any objects
1273 on the Ada side. If no default constructor is imported, only the
1274 initialization forms using an explicit call to a constructor are
1277 Pragma @code{CPP_Constructor} is intended primarily for automatic generation
1278 using an automatic binding generator tool.
1279 See @ref{Interfacing to C++} for more related information.
1281 @node Pragma CPP_Virtual
1282 @unnumberedsec Pragma CPP_Virtual
1283 @cindex Interfacing to C++
1288 @smallexample @c ada
1291 [, [Vtable_Ptr =>] vtable_ENTITY,]
1292 [, [Position =>] static_integer_EXPRESSION]);
1296 This pragma serves the same function as pragma @code{Import} in that
1297 case of a virtual function imported from C++. The @var{Entity} argument
1299 primitive subprogram of a tagged type to which pragma @code{CPP_Class}
1300 applies. The @var{Vtable_Ptr} argument specifies
1301 the Vtable_Ptr component which contains the
1302 entry for this virtual function. The @var{Position} argument
1303 is the sequential number
1304 counting virtual functions for this Vtable starting at 1.
1306 The @code{Vtable_Ptr} and @code{Position} arguments may be omitted if
1307 there is one Vtable_Ptr present (single inheritance case) and all
1308 virtual functions are imported. In that case the compiler can deduce both
1311 No @code{External_Name} or @code{Link_Name} arguments are required for a
1312 virtual function, since it is always accessed indirectly via the
1313 appropriate Vtable entry.
1315 Pragma @code{CPP_Virtual} is intended primarily for automatic generation
1316 using an automatic binding generator tool.
1317 See @ref{Interfacing to C++} for related information.
1319 @node Pragma CPP_Vtable
1320 @unnumberedsec Pragma CPP_Vtable
1321 @cindex Interfacing with C++
1326 @smallexample @c ada
1329 [Vtable_Ptr =>] vtable_ENTITY,
1330 [Entry_Count =>] static_integer_EXPRESSION);
1334 Given a record to which the pragma @code{CPP_Class} applies,
1335 this pragma can be specified for each component of type
1336 @code{CPP.Interfaces.Vtable_Ptr}.
1337 @var{Entity} is the tagged type, @var{Vtable_Ptr}
1338 is the record field of type @code{Vtable_Ptr}, and @var{Entry_Count} is
1339 the number of virtual functions on the C++ side. Not all of these
1340 functions need to be imported on the Ada side.
1342 You may omit the @code{CPP_Vtable} pragma if there is only one
1343 @code{Vtable_Ptr} component in the record and all virtual functions are
1344 imported on the Ada side (the default value for the entry count in this
1345 case is simply the total number of virtual functions).
1347 Pragma @code{CPP_Vtable} is intended primarily for automatic generation
1348 using an automatic binding generator tool.
1349 See @ref{Interfacing to C++} for related information.
1352 @unnumberedsec Pragma Debug
1357 @smallexample @c ada
1358 pragma Debug (PROCEDURE_CALL_WITHOUT_SEMICOLON);
1360 PROCEDURE_CALL_WITHOUT_SEMICOLON ::=
1362 | PROCEDURE_PREFIX ACTUAL_PARAMETER_PART
1366 The argument has the syntactic form of an expression, meeting the
1367 syntactic requirements for pragmas.
1369 If debug pragmas are not enabled, this pragma has no
1370 effect. If debug pragmas are enabled, the semantics of the pragma is exactly
1371 equivalent to the procedure call statement corresponding to the argument
1372 with a terminating semicolon. Pragmas are permitted in sequences of
1373 declarations, so you can use pragma @code{Debug} to intersperse calls to
1374 debug procedures in the middle of declarations. Debug pragmas can be
1375 enabled either by use of the command line switch @code{-gnata} or by use
1376 of the configuration pragma @code{Debug_Policy}.
1379 @node Pragma Debug_Policy
1380 @unnumberedsec Pragma Debug_Policy
1381 @findex Debug_Policy
1385 @smallexample @c ada
1386 pragma Debug_Policy (CHECK | IGNORE);
1390 If the argument is @code{CHECK}, then pragma @code{DEBUG} is enabled.
1391 If the argument is @code{IGNORE}, then pragma @code{DEBUG} is ignored.
1392 This pragma overrides the effect of the @code{-gnata} switch on the
1395 If debug pragmas are not enabled, this pragma has no
1396 effect. If debug pragmas are enabled, the semantics of the pragma is exactly
1397 equivalent to the procedure call statement corresponding to the argument
1398 with a terminating semicolon. Pragmas are permitted in sequences of
1399 declarations, so you can use pragma @code{Debug} to intersperse calls to
1400 debug procedures in the middle of declarations. Debug pragmas can be
1401 enabled either by use of the command line switch @code{-gnata} or by use
1402 of the configuration pragma @code{Debug_Policy}.
1409 @node Pragma Detect_Blocking
1410 @unnumberedsec Pragma Detect_Blocking
1411 @findex Detect_Blocking
1415 @smallexample @c ada
1416 pragma Detect_Blocking;
1420 This is a configuration pragma that forces the detection of potentially
1421 blocking operations within a protected operation, and to raise Program_Error
1424 @node Pragma Elaboration_Checks
1425 @unnumberedsec Pragma Elaboration_Checks
1426 @cindex Elaboration control
1427 @findex Elaboration_Checks
1431 @smallexample @c ada
1432 pragma Elaboration_Checks (Dynamic | Static);
1436 This is a configuration pragma that provides control over the
1437 elaboration model used by the compilation affected by the
1438 pragma. If the parameter is @code{Dynamic},
1439 then the dynamic elaboration
1440 model described in the Ada Reference Manual is used, as though
1441 the @code{-gnatE} switch had been specified on the command
1442 line. If the parameter is @code{Static}, then the default GNAT static
1443 model is used. This configuration pragma overrides the setting
1444 of the command line. For full details on the elaboration models
1445 used by the GNAT compiler, see section ``Elaboration Order
1446 Handling in GNAT'' in the @cite{GNAT User's Guide}.
1448 @node Pragma Eliminate
1449 @unnumberedsec Pragma Eliminate
1450 @cindex Elimination of unused subprograms
1455 @smallexample @c ada
1457 [Unit_Name =>] IDENTIFIER |
1458 SELECTED_COMPONENT);
1461 [Unit_Name =>] IDENTIFIER |
1463 [Entity =>] IDENTIFIER |
1464 SELECTED_COMPONENT |
1466 [,OVERLOADING_RESOLUTION]);
1468 OVERLOADING_RESOLUTION ::= PARAMETER_AND_RESULT_TYPE_PROFILE |
1471 PARAMETER_AND_RESULT_TYPE_PROFILE ::= PROCEDURE_PROFILE |
1474 PROCEDURE_PROFILE ::= Parameter_Types => PARAMETER_TYPES
1476 FUNCTION_PROFILE ::= [Parameter_Types => PARAMETER_TYPES,]
1477 Result_Type => result_SUBTYPE_NAME]
1479 PARAMETER_TYPES ::= (SUBTYPE_NAME @{, SUBTYPE_NAME@})
1480 SUBTYPE_NAME ::= STRING_VALUE
1482 SOURCE_LOCATION ::= Source_Location => SOURCE_TRACE
1483 SOURCE_TRACE ::= STRING_VALUE
1485 STRING_VALUE ::= STRING_LITERAL @{& STRING_LITERAL@}
1489 This pragma indicates that the given entity is not used outside the
1490 compilation unit it is defined in. The entity must be an explicitly declared
1491 subprogram; this includes generic subprogram instances and
1492 subprograms declared in generic package instances.
1494 If the entity to be eliminated is a library level subprogram, then
1495 the first form of pragma @code{Eliminate} is used with only a single argument.
1496 In this form, the @code{Unit_Name} argument specifies the name of the
1497 library level unit to be eliminated.
1499 In all other cases, both @code{Unit_Name} and @code{Entity} arguments
1500 are required. If item is an entity of a library package, then the first
1501 argument specifies the unit name, and the second argument specifies
1502 the particular entity. If the second argument is in string form, it must
1503 correspond to the internal manner in which GNAT stores entity names (see
1504 compilation unit Namet in the compiler sources for details).
1506 The remaining parameters (OVERLOADING_RESOLUTION) are optionally used
1507 to distinguish between overloaded subprograms. If a pragma does not contain
1508 the OVERLOADING_RESOLUTION parameter(s), it is applied to all the overloaded
1509 subprograms denoted by the first two parameters.
1511 Use PARAMETER_AND_RESULT_TYPE_PROFILE to specify the profile of the subprogram
1512 to be eliminated in a manner similar to that used for the extended
1513 @code{Import} and @code{Export} pragmas, except that the subtype names are
1514 always given as strings. At the moment, this form of distinguishing
1515 overloaded subprograms is implemented only partially, so we do not recommend
1516 using it for practical subprogram elimination.
1518 Note, that in case of a parameterless procedure its profile is represented
1519 as @code{Parameter_Types => ("")}
1521 Alternatively, the @code{Source_Location} parameter is used to specify
1522 which overloaded alternative is to be eliminated by pointing to the
1523 location of the DEFINING_PROGRAM_UNIT_NAME of this subprogram in the
1524 source text. The string literal (or concatenation of string literals)
1525 given as SOURCE_TRACE must have the following format:
1527 @smallexample @c ada
1528 SOURCE_TRACE ::= SOURCE_LOCATION@{LBRACKET SOURCE_LOCATION RBRACKET@}
1533 SOURCE_LOCATION ::= FILE_NAME:LINE_NUMBER
1534 FILE_NAME ::= STRING_LITERAL
1535 LINE_NUMBER ::= DIGIT @{DIGIT@}
1538 SOURCE_TRACE should be the short name of the source file (with no directory
1539 information), and LINE_NUMBER is supposed to point to the line where the
1540 defining name of the subprogram is located.
1542 For the subprograms that are not a part of generic instantiations, only one
1543 SOURCE_LOCATION is used. If a subprogram is declared in a package
1544 instantiation, SOURCE_TRACE contains two SOURCE_LOCATIONs, the first one is
1545 the location of the (DEFINING_PROGRAM_UNIT_NAME of the) instantiation, and the
1546 second one denotes the declaration of the corresponding subprogram in the
1547 generic package. This approach is recursively used to create SOURCE_LOCATIONs
1548 in case of nested instantiations.
1550 The effect of the pragma is to allow the compiler to eliminate
1551 the code or data associated with the named entity. Any reference to
1552 an eliminated entity outside the compilation unit it is defined in,
1553 causes a compile time or link time error.
1555 The intention of pragma @code{Eliminate} is to allow a program to be compiled
1556 in a system independent manner, with unused entities eliminated, without
1557 the requirement of modifying the source text. Normally the required set
1558 of @code{Eliminate} pragmas is constructed automatically using the gnatelim
1559 tool. Elimination of unused entities local to a compilation unit is
1560 automatic, without requiring the use of pragma @code{Eliminate}.
1562 Note that the reason this pragma takes string literals where names might
1563 be expected is that a pragma @code{Eliminate} can appear in a context where the
1564 relevant names are not visible.
1566 Note that any change in the source files that includes removing, splitting of
1567 adding lines may make the set of Eliminate pragmas using SOURCE_LOCATION
1570 @node Pragma Export_Exception
1571 @unnumberedsec Pragma Export_Exception
1573 @findex Export_Exception
1577 @smallexample @c ada
1578 pragma Export_Exception (
1579 [Internal =>] local_NAME,
1580 [, [External =>] EXTERNAL_SYMBOL,]
1581 [, [Form =>] Ada | VMS]
1582 [, [Code =>] static_integer_EXPRESSION]);
1586 | static_string_EXPRESSION
1590 This pragma is implemented only in the OpenVMS implementation of GNAT@. It
1591 causes the specified exception to be propagated outside of the Ada program,
1592 so that it can be handled by programs written in other OpenVMS languages.
1593 This pragma establishes an external name for an Ada exception and makes the
1594 name available to the OpenVMS Linker as a global symbol. For further details
1595 on this pragma, see the
1596 DEC Ada Language Reference Manual, section 13.9a3.2.
1598 @node Pragma Export_Function
1599 @unnumberedsec Pragma Export_Function
1600 @cindex Argument passing mechanisms
1601 @findex Export_Function
1606 @smallexample @c ada
1607 pragma Export_Function (
1608 [Internal =>] local_NAME,
1609 [, [External =>] EXTERNAL_SYMBOL]
1610 [, [Parameter_Types =>] PARAMETER_TYPES]
1611 [, [Result_Type =>] result_SUBTYPE_MARK]
1612 [, [Mechanism =>] MECHANISM]
1613 [, [Result_Mechanism =>] MECHANISM_NAME]);
1617 | static_string_EXPRESSION
1622 | TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@}
1626 | subtype_Name ' Access
1630 | (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@})
1632 MECHANISM_ASSOCIATION ::=
1633 [formal_parameter_NAME =>] MECHANISM_NAME
1641 Use this pragma to make a function externally callable and optionally
1642 provide information on mechanisms to be used for passing parameter and
1643 result values. We recommend, for the purposes of improving portability,
1644 this pragma always be used in conjunction with a separate pragma
1645 @code{Export}, which must precede the pragma @code{Export_Function}.
1646 GNAT does not require a separate pragma @code{Export}, but if none is
1647 present, @code{Convention Ada} is assumed, which is usually
1648 not what is wanted, so it is usually appropriate to use this
1649 pragma in conjunction with a @code{Export} or @code{Convention}
1650 pragma that specifies the desired foreign convention.
1651 Pragma @code{Export_Function}
1652 (and @code{Export}, if present) must appear in the same declarative
1653 region as the function to which they apply.
1655 @var{internal_name} must uniquely designate the function to which the
1656 pragma applies. If more than one function name exists of this name in
1657 the declarative part you must use the @code{Parameter_Types} and
1658 @code{Result_Type} parameters is mandatory to achieve the required
1659 unique designation. @var{subtype_ mark}s in these parameters must
1660 exactly match the subtypes in the corresponding function specification,
1661 using positional notation to match parameters with subtype marks.
1662 The form with an @code{'Access} attribute can be used to match an
1663 anonymous access parameter.
1666 @cindex Passing by descriptor
1667 Note that passing by descriptor is not supported, even on the OpenVMS
1670 @cindex Suppressing external name
1671 Special treatment is given if the EXTERNAL is an explicit null
1672 string or a static string expressions that evaluates to the null
1673 string. In this case, no external name is generated. This form
1674 still allows the specification of parameter mechanisms.
1676 @node Pragma Export_Object
1677 @unnumberedsec Pragma Export_Object
1678 @findex Export_Object
1682 @smallexample @c ada
1683 pragma Export_Object
1684 [Internal =>] local_NAME,
1685 [, [External =>] EXTERNAL_SYMBOL]
1686 [, [Size =>] EXTERNAL_SYMBOL]
1690 | static_string_EXPRESSION
1694 This pragma designates an object as exported, and apart from the
1695 extended rules for external symbols, is identical in effect to the use of
1696 the normal @code{Export} pragma applied to an object. You may use a
1697 separate Export pragma (and you probably should from the point of view
1698 of portability), but it is not required. @var{Size} is syntax checked,
1699 but otherwise ignored by GNAT@.
1701 @node Pragma Export_Procedure
1702 @unnumberedsec Pragma Export_Procedure
1703 @findex Export_Procedure
1707 @smallexample @c ada
1708 pragma Export_Procedure (
1709 [Internal =>] local_NAME
1710 [, [External =>] EXTERNAL_SYMBOL]
1711 [, [Parameter_Types =>] PARAMETER_TYPES]
1712 [, [Mechanism =>] MECHANISM]);
1716 | static_string_EXPRESSION
1721 | TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@}
1725 | subtype_Name ' Access
1729 | (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@})
1731 MECHANISM_ASSOCIATION ::=
1732 [formal_parameter_NAME =>] MECHANISM_NAME
1740 This pragma is identical to @code{Export_Function} except that it
1741 applies to a procedure rather than a function and the parameters
1742 @code{Result_Type} and @code{Result_Mechanism} are not permitted.
1743 GNAT does not require a separate pragma @code{Export}, but if none is
1744 present, @code{Convention Ada} is assumed, which is usually
1745 not what is wanted, so it is usually appropriate to use this
1746 pragma in conjunction with a @code{Export} or @code{Convention}
1747 pragma that specifies the desired foreign convention.
1750 @cindex Passing by descriptor
1751 Note that passing by descriptor is not supported, even on the OpenVMS
1754 @cindex Suppressing external name
1755 Special treatment is given if the EXTERNAL is an explicit null
1756 string or a static string expressions that evaluates to the null
1757 string. In this case, no external name is generated. This form
1758 still allows the specification of parameter mechanisms.
1760 @node Pragma Export_Value
1761 @unnumberedsec Pragma Export_Value
1762 @findex Export_Value
1766 @smallexample @c ada
1767 pragma Export_Value (
1768 [Value =>] static_integer_EXPRESSION,
1769 [Link_Name =>] static_string_EXPRESSION);
1773 This pragma serves to export a static integer value for external use.
1774 The first argument specifies the value to be exported. The Link_Name
1775 argument specifies the symbolic name to be associated with the integer
1776 value. This pragma is useful for defining a named static value in Ada
1777 that can be referenced in assembly language units to be linked with
1778 the application. This pragma is currently supported only for the
1779 AAMP target and is ignored for other targets.
1781 @node Pragma Export_Valued_Procedure
1782 @unnumberedsec Pragma Export_Valued_Procedure
1783 @findex Export_Valued_Procedure
1787 @smallexample @c ada
1788 pragma Export_Valued_Procedure (
1789 [Internal =>] local_NAME
1790 [, [External =>] EXTERNAL_SYMBOL]
1791 [, [Parameter_Types =>] PARAMETER_TYPES]
1792 [, [Mechanism =>] MECHANISM]);
1796 | static_string_EXPRESSION
1801 | TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@}
1805 | subtype_Name ' Access
1809 | (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@})
1811 MECHANISM_ASSOCIATION ::=
1812 [formal_parameter_NAME =>] MECHANISM_NAME
1820 This pragma is identical to @code{Export_Procedure} except that the
1821 first parameter of @var{local_NAME}, which must be present, must be of
1822 mode @code{OUT}, and externally the subprogram is treated as a function
1823 with this parameter as the result of the function. GNAT provides for
1824 this capability to allow the use of @code{OUT} and @code{IN OUT}
1825 parameters in interfacing to external functions (which are not permitted
1827 GNAT does not require a separate pragma @code{Export}, but if none is
1828 present, @code{Convention Ada} is assumed, which is almost certainly
1829 not what is wanted since the whole point of this pragma is to interface
1830 with foreign language functions, so it is usually appropriate to use this
1831 pragma in conjunction with a @code{Export} or @code{Convention}
1832 pragma that specifies the desired foreign convention.
1835 @cindex Passing by descriptor
1836 Note that passing by descriptor is not supported, even on the OpenVMS
1839 @cindex Suppressing external name
1840 Special treatment is given if the EXTERNAL is an explicit null
1841 string or a static string expressions that evaluates to the null
1842 string. In this case, no external name is generated. This form
1843 still allows the specification of parameter mechanisms.
1845 @node Pragma Extend_System
1846 @unnumberedsec Pragma Extend_System
1847 @cindex @code{system}, extending
1849 @findex Extend_System
1853 @smallexample @c ada
1854 pragma Extend_System ([Name =>] IDENTIFIER);
1858 This pragma is used to provide backwards compatibility with other
1859 implementations that extend the facilities of package @code{System}. In
1860 GNAT, @code{System} contains only the definitions that are present in
1861 the Ada 95 RM@. However, other implementations, notably the DEC Ada 83
1862 implementation, provide many extensions to package @code{System}.
1864 For each such implementation accommodated by this pragma, GNAT provides a
1865 package @code{Aux_@var{xxx}}, e.g.@: @code{Aux_DEC} for the DEC Ada 83
1866 implementation, which provides the required additional definitions. You
1867 can use this package in two ways. You can @code{with} it in the normal
1868 way and access entities either by selection or using a @code{use}
1869 clause. In this case no special processing is required.
1871 However, if existing code contains references such as
1872 @code{System.@var{xxx}} where @var{xxx} is an entity in the extended
1873 definitions provided in package @code{System}, you may use this pragma
1874 to extend visibility in @code{System} in a non-standard way that
1875 provides greater compatibility with the existing code. Pragma
1876 @code{Extend_System} is a configuration pragma whose single argument is
1877 the name of the package containing the extended definition
1878 (e.g.@: @code{Aux_DEC} for the DEC Ada case). A unit compiled under
1879 control of this pragma will be processed using special visibility
1880 processing that looks in package @code{System.Aux_@var{xxx}} where
1881 @code{Aux_@var{xxx}} is the pragma argument for any entity referenced in
1882 package @code{System}, but not found in package @code{System}.
1884 You can use this pragma either to access a predefined @code{System}
1885 extension supplied with the compiler, for example @code{Aux_DEC} or
1886 you can construct your own extension unit following the above
1887 definition. Note that such a package is a child of @code{System}
1888 and thus is considered part of the implementation. To compile
1889 it you will have to use the appropriate switch for compiling
1890 system units. See the GNAT User's Guide for details.
1892 @node Pragma External
1893 @unnumberedsec Pragma External
1898 @smallexample @c ada
1900 [ Convention =>] convention_IDENTIFIER,
1901 [ Entity =>] local_NAME
1902 [, [External_Name =>] static_string_EXPRESSION ]
1903 [, [Link_Name =>] static_string_EXPRESSION ]);
1907 This pragma is identical in syntax and semantics to pragma
1908 @code{Export} as defined in the Ada Reference Manual. It is
1909 provided for compatibility with some Ada 83 compilers that
1910 used this pragma for exactly the same purposes as pragma
1911 @code{Export} before the latter was standardized.
1913 @node Pragma External_Name_Casing
1914 @unnumberedsec Pragma External_Name_Casing
1915 @cindex Dec Ada 83 casing compatibility
1916 @cindex External Names, casing
1917 @cindex Casing of External names
1918 @findex External_Name_Casing
1922 @smallexample @c ada
1923 pragma External_Name_Casing (
1924 Uppercase | Lowercase
1925 [, Uppercase | Lowercase | As_Is]);
1929 This pragma provides control over the casing of external names associated
1930 with Import and Export pragmas. There are two cases to consider:
1933 @item Implicit external names
1934 Implicit external names are derived from identifiers. The most common case
1935 arises when a standard Ada 95 Import or Export pragma is used with only two
1938 @smallexample @c ada
1939 pragma Import (C, C_Routine);
1943 Since Ada is a case insensitive language, the spelling of the identifier in
1944 the Ada source program does not provide any information on the desired
1945 casing of the external name, and so a convention is needed. In GNAT the
1946 default treatment is that such names are converted to all lower case
1947 letters. This corresponds to the normal C style in many environments.
1948 The first argument of pragma @code{External_Name_Casing} can be used to
1949 control this treatment. If @code{Uppercase} is specified, then the name
1950 will be forced to all uppercase letters. If @code{Lowercase} is specified,
1951 then the normal default of all lower case letters will be used.
1953 This same implicit treatment is also used in the case of extended DEC Ada 83
1954 compatible Import and Export pragmas where an external name is explicitly
1955 specified using an identifier rather than a string.
1957 @item Explicit external names
1958 Explicit external names are given as string literals. The most common case
1959 arises when a standard Ada 95 Import or Export pragma is used with three
1962 @smallexample @c ada
1963 pragma Import (C, C_Routine, "C_routine");
1967 In this case, the string literal normally provides the exact casing required
1968 for the external name. The second argument of pragma
1969 @code{External_Name_Casing} may be used to modify this behavior.
1970 If @code{Uppercase} is specified, then the name
1971 will be forced to all uppercase letters. If @code{Lowercase} is specified,
1972 then the name will be forced to all lowercase letters. A specification of
1973 @code{As_Is} provides the normal default behavior in which the casing is
1974 taken from the string provided.
1978 This pragma may appear anywhere that a pragma is valid. In particular, it
1979 can be used as a configuration pragma in the @file{gnat.adc} file, in which
1980 case it applies to all subsequent compilations, or it can be used as a program
1981 unit pragma, in which case it only applies to the current unit, or it can
1982 be used more locally to control individual Import/Export pragmas.
1984 It is primarily intended for use with OpenVMS systems, where many
1985 compilers convert all symbols to upper case by default. For interfacing to
1986 such compilers (e.g.@: the DEC C compiler), it may be convenient to use
1989 @smallexample @c ada
1990 pragma External_Name_Casing (Uppercase, Uppercase);
1994 to enforce the upper casing of all external symbols.
1996 @node Pragma Finalize_Storage_Only
1997 @unnumberedsec Pragma Finalize_Storage_Only
1998 @findex Finalize_Storage_Only
2002 @smallexample @c ada
2003 pragma Finalize_Storage_Only (first_subtype_local_NAME);
2007 This pragma allows the compiler not to emit a Finalize call for objects
2008 defined at the library level. This is mostly useful for types where
2009 finalization is only used to deal with storage reclamation since in most
2010 environments it is not necessary to reclaim memory just before terminating
2011 execution, hence the name.
2013 @node Pragma Float_Representation
2014 @unnumberedsec Pragma Float_Representation
2016 @findex Float_Representation
2020 @smallexample @c ada
2021 pragma Float_Representation (FLOAT_REP[, float_type_LOCAL_NAME]);
2023 FLOAT_REP ::= VAX_Float | IEEE_Float
2027 In the one argument form, this pragma is a configuration pragma which
2028 allows control over the internal representation chosen for the predefined
2029 floating point types declared in the packages @code{Standard} and
2030 @code{System}. On all systems other than OpenVMS, the argument must
2031 be @code{IEEE_Float} and the pragma has no effect. On OpenVMS, the
2032 argument may be @code{VAX_Float} to specify the use of the VAX float
2033 format for the floating-point types in Standard. This requires that
2034 the standard runtime libraries be recompiled. See the
2035 description of the @code{GNAT LIBRARY} command in the OpenVMS version
2036 of the GNAT Users Guide for details on the use of this command.
2038 The two argument form specifies the representation to be used for
2039 the specified floating-poin type. On all systems other than OpenVMS,
2041 be @code{IEEE_Float} and the pragma has no effect. On OpenVMS, the
2042 argument may be @code{VAX_Float} to specify the use of the VAX float
2047 For digits values up to 6, F float format will be used.
2049 For digits values from 7 to 9, G float format will be used.
2051 For digits values from 10 to 15, F float format will be used.
2053 Digits values above 15 are not allowed.
2057 @unnumberedsec Pragma Ident
2062 @smallexample @c ada
2063 pragma Ident (static_string_EXPRESSION);
2067 This pragma provides a string identification in the generated object file,
2068 if the system supports the concept of this kind of identification string.
2069 This pragma is allowed only in the outermost declarative part or
2070 declarative items of a compilation unit. If more than one @code{Ident}
2071 pragma is given, only the last one processed is effective.
2073 On OpenVMS systems, the effect of the pragma is identical to the effect of
2074 the DEC Ada 83 pragma of the same name. Note that in DEC Ada 83, the
2075 maximum allowed length is 31 characters, so if it is important to
2076 maintain compatibility with this compiler, you should obey this length
2079 @node Pragma Import_Exception
2080 @unnumberedsec Pragma Import_Exception
2082 @findex Import_Exception
2086 @smallexample @c ada
2087 pragma Import_Exception (
2088 [Internal =>] local_NAME,
2089 [, [External =>] EXTERNAL_SYMBOL,]
2090 [, [Form =>] Ada | VMS]
2091 [, [Code =>] static_integer_EXPRESSION]);
2095 | static_string_EXPRESSION
2099 This pragma is implemented only in the OpenVMS implementation of GNAT@.
2100 It allows OpenVMS conditions (for example, from OpenVMS system services or
2101 other OpenVMS languages) to be propagated to Ada programs as Ada exceptions.
2102 The pragma specifies that the exception associated with an exception
2103 declaration in an Ada program be defined externally (in non-Ada code).
2104 For further details on this pragma, see the
2105 DEC Ada Language Reference Manual, section 13.9a.3.1.
2107 @node Pragma Import_Function
2108 @unnumberedsec Pragma Import_Function
2109 @findex Import_Function
2113 @smallexample @c ada
2114 pragma Import_Function (
2115 [Internal =>] local_NAME,
2116 [, [External =>] EXTERNAL_SYMBOL]
2117 [, [Parameter_Types =>] PARAMETER_TYPES]
2118 [, [Result_Type =>] SUBTYPE_MARK]
2119 [, [Mechanism =>] MECHANISM]
2120 [, [Result_Mechanism =>] MECHANISM_NAME]
2121 [, [First_Optional_Parameter =>] IDENTIFIER]);
2125 | static_string_EXPRESSION
2129 | TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@}
2133 | subtype_Name ' Access
2137 | (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@})
2139 MECHANISM_ASSOCIATION ::=
2140 [formal_parameter_NAME =>] MECHANISM_NAME
2145 | Descriptor [([Class =>] CLASS_NAME)]
2147 CLASS_NAME ::= ubs | ubsb | uba | s | sb | a | nca
2151 This pragma is used in conjunction with a pragma @code{Import} to
2152 specify additional information for an imported function. The pragma
2153 @code{Import} (or equivalent pragma @code{Interface}) must precede the
2154 @code{Import_Function} pragma and both must appear in the same
2155 declarative part as the function specification.
2157 The @var{Internal} argument must uniquely designate
2158 the function to which the
2159 pragma applies. If more than one function name exists of this name in
2160 the declarative part you must use the @code{Parameter_Types} and
2161 @var{Result_Type} parameters to achieve the required unique
2162 designation. Subtype marks in these parameters must exactly match the
2163 subtypes in the corresponding function specification, using positional
2164 notation to match parameters with subtype marks.
2165 The form with an @code{'Access} attribute can be used to match an
2166 anonymous access parameter.
2168 You may optionally use the @var{Mechanism} and @var{Result_Mechanism}
2169 parameters to specify passing mechanisms for the
2170 parameters and result. If you specify a single mechanism name, it
2171 applies to all parameters. Otherwise you may specify a mechanism on a
2172 parameter by parameter basis using either positional or named
2173 notation. If the mechanism is not specified, the default mechanism
2177 @cindex Passing by descriptor
2178 Passing by descriptor is supported only on the OpenVMS ports of GNAT@.
2180 @code{First_Optional_Parameter} applies only to OpenVMS ports of GNAT@.
2181 It specifies that the designated parameter and all following parameters
2182 are optional, meaning that they are not passed at the generated code
2183 level (this is distinct from the notion of optional parameters in Ada
2184 where the parameters are passed anyway with the designated optional
2185 parameters). All optional parameters must be of mode @code{IN} and have
2186 default parameter values that are either known at compile time
2187 expressions, or uses of the @code{'Null_Parameter} attribute.
2189 @node Pragma Import_Object
2190 @unnumberedsec Pragma Import_Object
2191 @findex Import_Object
2195 @smallexample @c ada
2196 pragma Import_Object
2197 [Internal =>] local_NAME,
2198 [, [External =>] EXTERNAL_SYMBOL],
2199 [, [Size =>] EXTERNAL_SYMBOL]);
2203 | static_string_EXPRESSION
2207 This pragma designates an object as imported, and apart from the
2208 extended rules for external symbols, is identical in effect to the use of
2209 the normal @code{Import} pragma applied to an object. Unlike the
2210 subprogram case, you need not use a separate @code{Import} pragma,
2211 although you may do so (and probably should do so from a portability
2212 point of view). @var{size} is syntax checked, but otherwise ignored by
2215 @node Pragma Import_Procedure
2216 @unnumberedsec Pragma Import_Procedure
2217 @findex Import_Procedure
2221 @smallexample @c ada
2222 pragma Import_Procedure (
2223 [Internal =>] local_NAME,
2224 [, [External =>] EXTERNAL_SYMBOL]
2225 [, [Parameter_Types =>] PARAMETER_TYPES]
2226 [, [Mechanism =>] MECHANISM]
2227 [, [First_Optional_Parameter =>] IDENTIFIER]);
2231 | static_string_EXPRESSION
2235 | TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@}
2239 | subtype_Name ' Access
2243 | (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@})
2245 MECHANISM_ASSOCIATION ::=
2246 [formal_parameter_NAME =>] MECHANISM_NAME
2251 | Descriptor [([Class =>] CLASS_NAME)]
2253 CLASS_NAME ::= ubs | ubsb | uba | s | sb | a | nca
2257 This pragma is identical to @code{Import_Function} except that it
2258 applies to a procedure rather than a function and the parameters
2259 @code{Result_Type} and @code{Result_Mechanism} are not permitted.
2261 @node Pragma Import_Valued_Procedure
2262 @unnumberedsec Pragma Import_Valued_Procedure
2263 @findex Import_Valued_Procedure
2267 @smallexample @c ada
2268 pragma Import_Valued_Procedure (
2269 [Internal =>] local_NAME,
2270 [, [External =>] EXTERNAL_SYMBOL]
2271 [, [Parameter_Types =>] PARAMETER_TYPES]
2272 [, [Mechanism =>] MECHANISM]
2273 [, [First_Optional_Parameter =>] IDENTIFIER]);
2277 | static_string_EXPRESSION
2281 | TYPE_DESIGNATOR @{, TYPE_DESIGNATOR@}
2285 | subtype_Name ' Access
2289 | (MECHANISM_ASSOCIATION @{, MECHANISM_ASSOCIATION@})
2291 MECHANISM_ASSOCIATION ::=
2292 [formal_parameter_NAME =>] MECHANISM_NAME
2297 | Descriptor [([Class =>] CLASS_NAME)]
2299 CLASS_NAME ::= ubs | ubsb | uba | s | sb | a | nca
2303 This pragma is identical to @code{Import_Procedure} except that the
2304 first parameter of @var{local_NAME}, which must be present, must be of
2305 mode @code{OUT}, and externally the subprogram is treated as a function
2306 with this parameter as the result of the function. The purpose of this
2307 capability is to allow the use of @code{OUT} and @code{IN OUT}
2308 parameters in interfacing to external functions (which are not permitted
2309 in Ada functions). You may optionally use the @code{Mechanism}
2310 parameters to specify passing mechanisms for the parameters.
2311 If you specify a single mechanism name, it applies to all parameters.
2312 Otherwise you may specify a mechanism on a parameter by parameter
2313 basis using either positional or named notation. If the mechanism is not
2314 specified, the default mechanism is used.
2316 Note that it is important to use this pragma in conjunction with a separate
2317 pragma Import that specifies the desired convention, since otherwise the
2318 default convention is Ada, which is almost certainly not what is required.
2320 @node Pragma Initialize_Scalars
2321 @unnumberedsec Pragma Initialize_Scalars
2322 @findex Initialize_Scalars
2323 @cindex debugging with Initialize_Scalars
2327 @smallexample @c ada
2328 pragma Initialize_Scalars;
2332 This pragma is similar to @code{Normalize_Scalars} conceptually but has
2333 two important differences. First, there is no requirement for the pragma
2334 to be used uniformly in all units of a partition, in particular, it is fine
2335 to use this just for some or all of the application units of a partition,
2336 without needing to recompile the run-time library.
2338 In the case where some units are compiled with the pragma, and some without,
2339 then a declaration of a variable where the type is defined in package
2340 Standard or is locally declared will always be subject to initialization,
2341 as will any declaration of a scalar variable. For composite variables,
2342 whether the variable is initialized may also depend on whether the package
2343 in which the type of the variable is declared is compiled with the pragma.
2345 The other important difference is that you can control the value used
2346 for initializing scalar objects. At bind time, you can select several
2347 options for initialization. You can
2348 initialize with invalid values (similar to Normalize_Scalars, though for
2349 Initialize_Scalars it is not always possible to determine the invalid
2350 values in complex cases like signed component fields with non-standard
2351 sizes). You can also initialize with high or
2352 low values, or with a specified bit pattern. See the users guide for binder
2353 options for specifying these cases.
2355 This means that you can compile a program, and then without having to
2356 recompile the program, you can run it with different values being used
2357 for initializing otherwise uninitialized values, to test if your program
2358 behavior depends on the choice. Of course the behavior should not change,
2359 and if it does, then most likely you have an erroneous reference to an
2360 uninitialized value.
2362 It is even possible to change the value at execution time eliminating even
2363 the need to rebind with a different switch using an environment variable.
2364 See the GNAT users guide for details.
2366 Note that pragma @code{Initialize_Scalars} is particularly useful in
2367 conjunction with the enhanced validity checking that is now provided
2368 in GNAT, which checks for invalid values under more conditions.
2369 Using this feature (see description of the @code{-gnatV} flag in the
2370 users guide) in conjunction with pragma @code{Initialize_Scalars}
2371 provides a powerful new tool to assist in the detection of problems
2372 caused by uninitialized variables.
2374 Note: the use of @code{Initialize_Scalars} has a fairly extensive
2375 effect on the generated code. This may cause your code to be
2376 substantially larger. It may also cause an increase in the amount
2377 of stack required, so it is probably a good idea to turn on stack
2378 checking (see description of stack checking in the GNAT users guide)
2379 when using this pragma.
2381 @node Pragma Inline_Always
2382 @unnumberedsec Pragma Inline_Always
2383 @findex Inline_Always
2387 @smallexample @c ada
2388 pragma Inline_Always (NAME [, NAME]);
2392 Similar to pragma @code{Inline} except that inlining is not subject to
2393 the use of option @code{-gnatn} and the inlining happens regardless of
2394 whether this option is used.
2396 @node Pragma Inline_Generic
2397 @unnumberedsec Pragma Inline_Generic
2398 @findex Inline_Generic
2402 @smallexample @c ada
2403 pragma Inline_Generic (generic_package_NAME);
2407 This is implemented for compatibility with DEC Ada 83 and is recognized,
2408 but otherwise ignored, by GNAT@. All generic instantiations are inlined
2409 by default when using GNAT@.
2411 @node Pragma Interface
2412 @unnumberedsec Pragma Interface
2417 @smallexample @c ada
2419 [Convention =>] convention_identifier,
2420 [Entity =>] local_NAME
2421 [, [External_Name =>] static_string_expression],
2422 [, [Link_Name =>] static_string_expression]);
2426 This pragma is identical in syntax and semantics to
2427 the standard Ada 95 pragma @code{Import}. It is provided for compatibility
2428 with Ada 83. The definition is upwards compatible both with pragma
2429 @code{Interface} as defined in the Ada 83 Reference Manual, and also
2430 with some extended implementations of this pragma in certain Ada 83
2433 @node Pragma Interface_Name
2434 @unnumberedsec Pragma Interface_Name
2435 @findex Interface_Name
2439 @smallexample @c ada
2440 pragma Interface_Name (
2441 [Entity =>] local_NAME
2442 [, [External_Name =>] static_string_EXPRESSION]
2443 [, [Link_Name =>] static_string_EXPRESSION]);
2447 This pragma provides an alternative way of specifying the interface name
2448 for an interfaced subprogram, and is provided for compatibility with Ada
2449 83 compilers that use the pragma for this purpose. You must provide at
2450 least one of @var{External_Name} or @var{Link_Name}.
2452 @node Pragma Interrupt_Handler
2453 @unnumberedsec Pragma Interrupt_Handler
2454 @findex Interrupt_Handler
2458 @smallexample @c ada
2459 pragma Interrupt_Handler (procedure_local_NAME);
2463 This program unit pragma is supported for parameterless protected procedures
2464 as described in Annex C of the Ada Reference Manual. On the AAMP target
2465 the pragma can also be specified for nonprotected parameterless procedures
2466 that are declared at the library level (which includes procedures
2467 declared at the top level of a library package). In the case of AAMP,
2468 when this pragma is applied to a nonprotected procedure, the instruction
2469 @code{IERET} is generated for returns from the procedure, enabling
2470 maskable interrupts, in place of the normal return instruction.
2472 @node Pragma Interrupt_State
2473 @unnumberedsec Pragma Interrupt_State
2474 @findex Interrupt_State
2478 @smallexample @c ada
2479 pragma Interrupt_State (Name => value, State => SYSTEM | RUNTIME | USER);
2483 Normally certain interrupts are reserved to the implementation. Any attempt
2484 to attach an interrupt causes Program_Error to be raised, as described in
2485 RM C.3.2(22). A typical example is the @code{SIGINT} interrupt used in
2486 many systems for an @kbd{Ctrl-C} interrupt. Normally this interrupt is
2487 reserved to the implementation, so that @kbd{Ctrl-C} can be used to
2488 interrupt execution. Additionally, signals such as @code{SIGSEGV},
2489 @code{SIGABRT}, @code{SIGFPE} and @code{SIGILL} are often mapped to specific
2490 Ada exceptions, or used to implement run-time functions such as the
2491 @code{abort} statement and stack overflow checking.
2493 Pragma @code{Interrupt_State} provides a general mechanism for overriding
2494 such uses of interrupts. It subsumes the functionality of pragma
2495 @code{Unreserve_All_Interrupts}. Pragma @code{Interrupt_State} is not
2496 available on OS/2, Windows or VMS. On all other platforms than VxWorks,
2497 it applies to signals; on VxWorks, it applies to vectored hardware interrupts
2498 and may be used to mark interrupts required by the board support package
2501 Interrupts can be in one of three states:
2505 The interrupt is reserved (no Ada handler can be installed), and the
2506 Ada run-time may not install a handler. As a result you are guaranteed
2507 standard system default action if this interrupt is raised.
2511 The interrupt is reserved (no Ada handler can be installed). The run time
2512 is allowed to install a handler for internal control purposes, but is
2513 not required to do so.
2517 The interrupt is unreserved. The user may install a handler to provide
2522 These states are the allowed values of the @code{State} parameter of the
2523 pragma. The @code{Name} parameter is a value of the type
2524 @code{Ada.Interrupts.Interrupt_ID}. Typically, it is a name declared in
2525 @code{Ada.Interrupts.Names}.
2527 This is a configuration pragma, and the binder will check that there
2528 are no inconsistencies between different units in a partition in how a
2529 given interrupt is specified. It may appear anywhere a pragma is legal.
2531 The effect is to move the interrupt to the specified state.
2533 By declaring interrupts to be SYSTEM, you guarantee the standard system
2534 action, such as a core dump.
2536 By declaring interrupts to be USER, you guarantee that you can install
2539 Note that certain signals on many operating systems cannot be caught and
2540 handled by applications. In such cases, the pragma is ignored. See the
2541 operating system documentation, or the value of the array @code{Reserved}
2542 declared in the specification of package @code{System.OS_Interface}.
2544 Overriding the default state of signals used by the Ada runtime may interfere
2545 with an application's runtime behavior in the cases of the synchronous signals,
2546 and in the case of the signal used to implement the @code{abort} statement.
2548 @node Pragma Keep_Names
2549 @unnumberedsec Pragma Keep_Names
2554 @smallexample @c ada
2555 pragma Keep_Names ([On =>] enumeration_first_subtype_local_NAME);
2559 The @var{local_NAME} argument
2560 must refer to an enumeration first subtype
2561 in the current declarative part. The effect is to retain the enumeration
2562 literal names for use by @code{Image} and @code{Value} even if a global
2563 @code{Discard_Names} pragma applies. This is useful when you want to
2564 generally suppress enumeration literal names and for example you therefore
2565 use a @code{Discard_Names} pragma in the @file{gnat.adc} file, but you
2566 want to retain the names for specific enumeration types.
2568 @node Pragma License
2569 @unnumberedsec Pragma License
2571 @cindex License checking
2575 @smallexample @c ada
2576 pragma License (Unrestricted | GPL | Modified_GPL | Restricted);
2580 This pragma is provided to allow automated checking for appropriate license
2581 conditions with respect to the standard and modified GPL@. A pragma
2582 @code{License}, which is a configuration pragma that typically appears at
2583 the start of a source file or in a separate @file{gnat.adc} file, specifies
2584 the licensing conditions of a unit as follows:
2588 This is used for a unit that can be freely used with no license restrictions.
2589 Examples of such units are public domain units, and units from the Ada
2593 This is used for a unit that is licensed under the unmodified GPL, and which
2594 therefore cannot be @code{with}'ed by a restricted unit.
2597 This is used for a unit licensed under the GNAT modified GPL that includes
2598 a special exception paragraph that specifically permits the inclusion of
2599 the unit in programs without requiring the entire program to be released
2600 under the GPL@. This is the license used for the GNAT run-time which ensures
2601 that the run-time can be used freely in any program without GPL concerns.
2604 This is used for a unit that is restricted in that it is not permitted to
2605 depend on units that are licensed under the GPL@. Typical examples are
2606 proprietary code that is to be released under more restrictive license
2607 conditions. Note that restricted units are permitted to @code{with} units
2608 which are licensed under the modified GPL (this is the whole point of the
2614 Normally a unit with no @code{License} pragma is considered to have an
2615 unknown license, and no checking is done. However, standard GNAT headers
2616 are recognized, and license information is derived from them as follows.
2620 A GNAT license header starts with a line containing 78 hyphens. The following
2621 comment text is searched for the appearance of any of the following strings.
2623 If the string ``GNU General Public License'' is found, then the unit is assumed
2624 to have GPL license, unless the string ``As a special exception'' follows, in
2625 which case the license is assumed to be modified GPL@.
2627 If one of the strings
2628 ``This specification is adapted from the Ada Semantic Interface'' or
2629 ``This specification is derived from the Ada Reference Manual'' is found
2630 then the unit is assumed to be unrestricted.
2634 These default actions means that a program with a restricted license pragma
2635 will automatically get warnings if a GPL unit is inappropriately
2636 @code{with}'ed. For example, the program:
2638 @smallexample @c ada
2641 procedure Secret_Stuff is
2647 if compiled with pragma @code{License} (@code{Restricted}) in a
2648 @file{gnat.adc} file will generate the warning:
2653 >>> license of withed unit "Sem_Ch3" is incompatible
2655 2. with GNAT.Sockets;
2656 3. procedure Secret_Stuff is
2660 Here we get a warning on @code{Sem_Ch3} since it is part of the GNAT
2661 compiler and is licensed under the
2662 GPL, but no warning for @code{GNAT.Sockets} which is part of the GNAT
2663 run time, and is therefore licensed under the modified GPL@.
2665 @node Pragma Link_With
2666 @unnumberedsec Pragma Link_With
2671 @smallexample @c ada
2672 pragma Link_With (static_string_EXPRESSION @{,static_string_EXPRESSION@});
2676 This pragma is provided for compatibility with certain Ada 83 compilers.
2677 It has exactly the same effect as pragma @code{Linker_Options} except
2678 that spaces occurring within one of the string expressions are treated
2679 as separators. For example, in the following case:
2681 @smallexample @c ada
2682 pragma Link_With ("-labc -ldef");
2686 results in passing the strings @code{-labc} and @code{-ldef} as two
2687 separate arguments to the linker. In addition pragma Link_With allows
2688 multiple arguments, with the same effect as successive pragmas.
2690 @node Pragma Linker_Alias
2691 @unnumberedsec Pragma Linker_Alias
2692 @findex Linker_Alias
2696 @smallexample @c ada
2697 pragma Linker_Alias (
2698 [Entity =>] local_NAME
2699 [Target =>] static_string_EXPRESSION);
2703 @var{local_NAME} must refer to an object that is declared at the library
2704 level. This pragma establishes the given entity as a linker alias for the
2705 given target. It is equivalent to @code{__attribute__((alias))} in GNU C
2706 and causes @var{local_NAME} to be emitted as an alias for the symbol
2707 @var{static_string_EXPRESSION} in the object file, that is to say no space
2708 is reserved for @var{local_NAME} by the assembler and it will be resolved
2709 to the same address as @var{static_string_EXPRESSION} by the linker.
2711 The actual linker name for the target must be used (e.g. the fully
2712 encoded name with qualification in Ada, or the mangled name in C++),
2713 or it must be declared using the C convention with @code{pragma Import}
2714 or @code{pragma Export}.
2716 Not all target machines support this pragma. On some of them it is accepted
2717 only if @code{pragma Weak_External} has been applied to @var{local_NAME}.
2719 @smallexample @c ada
2720 -- Example of the use of pragma Linker_Alias
2724 pragma Export (C, i);
2726 new_name_for_i : Integer;
2727 pragma Linker_Alias (new_name_for_i, "i");
2731 @node Pragma Linker_Constructor
2732 @unnumberedsec Pragma Linker_Constructor
2733 @findex Linker_Constructor
2737 @smallexample @c ada
2738 pragma Linker_Constructor (procedure_LOCAL_NAME);
2742 @var{procedure_local_NAME} must refer to a parameterless procedure that
2743 is declared at the library level. A procedure to which this pragma is
2744 applied will be treated as an initialization routine by the linker.
2745 It is equivalent to @code{__attribute__((constructor))} in GNU C and
2746 causes @var{procedure_LOCAL_NAME} to be invoked before the entry point
2747 of the executable is called (or immediately after the shared library is
2748 loaded if the procedure is linked in a shared library), in particular
2749 before the Ada run-time environment is set up.
2751 Because of these specific contexts, the set of operations such a procedure
2752 can perform is very limited and the type of objects it can manipulate is
2753 essentially restricted to the elementary types. In particular, it must only
2754 contain code to which pragma Restrictions (No_Elaboration_Code) applies.
2756 This pragma is used by GNAT to implement auto-initialization of shared Stand
2757 Alone Libraries, which provides a related capability without the restrictions
2758 listed above. Where possible, the use of Stand Alone Libraries is preferable
2759 to the use of this pragma.
2761 @node Pragma Linker_Destructor
2762 @unnumberedsec Pragma Linker_Destructor
2763 @findex Linker_Destructor
2767 @smallexample @c ada
2768 pragma Linker_Destructor (procedure_LOCAL_NAME);
2772 @var{procedure_local_NAME} must refer to a parameterless procedure that
2773 is declared at the library level. A procedure to which this pragma is
2774 applied will be treated as a finalization routine by the linker.
2775 It is equivalent to @code{__attribute__((destructor))} in GNU C and
2776 causes @var{procedure_LOCAL_NAME} to be invoked after the entry point
2777 of the executable has exited (or immediately before the shared library
2778 is unloaded if the procedure is linked in a shared library), in particular
2779 after the Ada run-time environment is shut down.
2781 See @code{pragma Linker_Constructor} for the set of restrictions that apply
2782 because of these specific contexts.
2784 @node Pragma Linker_Section
2785 @unnumberedsec Pragma Linker_Section
2786 @findex Linker_Section
2790 @smallexample @c ada
2791 pragma Linker_Section (
2792 [Entity =>] local_NAME
2793 [Section =>] static_string_EXPRESSION);
2797 @var{local_NAME} must refer to an object that is declared at the library
2798 level. This pragma specifies the name of the linker section for the given
2799 entity. It is equivalent to @code{__attribute__((section))} in GNU C and
2800 causes @var{local_NAME} to be placed in the @var{static_string_EXPRESSION}
2801 section of the executable (assuming the linker doesn't rename the section).
2803 The compiler normally places library-level objects in standard sections
2804 depending on their type: procedures and functions generally go in the
2805 @code{.text} section, initialized variables in the @code{.data} section
2806 and uninitialized variables in the @code{.bss} section.
2808 Other, special sections may exist on given target machines to map special
2809 hardware, for example I/O ports or flash memory. This pragma is a means to
2810 defer the final layout of the executable to the linker, thus fully working
2811 at the symbolic level with the compiler.
2813 Some file formats do not support arbitrary sections so not all target
2814 machines support this pragma. The use of this pragma may cause a program
2815 execution to be erroneous if it is used to place an entity into an
2816 inappropriate section (e.g. a modified variable into the @code{.text}
2817 section). See also @code{pragma Persistent_BSS}.
2819 @smallexample @c ada
2820 -- Example of the use of pragma Linker_Section
2824 pragma Volatile (Port_A);
2825 pragma Linker_Section (Port_A, ".bss.port_a");
2828 pragma Volatile (Port_B);
2829 pragma Linker_Section (Port_B, ".bss.port_b");
2833 @node Pragma Long_Float
2834 @unnumberedsec Pragma Long_Float
2840 @smallexample @c ada
2841 pragma Long_Float (FLOAT_FORMAT);
2843 FLOAT_FORMAT ::= D_Float | G_Float
2847 This pragma is implemented only in the OpenVMS implementation of GNAT@.
2848 It allows control over the internal representation chosen for the predefined
2849 type @code{Long_Float} and for floating point type representations with
2850 @code{digits} specified in the range 7 through 15.
2851 For further details on this pragma, see the
2852 @cite{DEC Ada Language Reference Manual}, section 3.5.7b. Note that to use
2853 this pragma, the standard runtime libraries must be recompiled. See the
2854 description of the @code{GNAT LIBRARY} command in the OpenVMS version
2855 of the GNAT User's Guide for details on the use of this command.
2857 @node Pragma Machine_Attribute
2858 @unnumberedsec Pragma Machine_Attribute
2859 @findex Machine_Attribute
2863 @smallexample @c ada
2864 pragma Machine_Attribute (
2865 [Attribute_Name =>] string_EXPRESSION,
2866 [Entity =>] local_NAME);
2870 Machine-dependent attributes can be specified for types and/or
2871 declarations. This pragma is semantically equivalent to
2872 @code{__attribute__((@var{string_expression}))} in GNU C,
2873 where @code{@var{string_expression}} is
2874 recognized by the target macro @code{TARGET_ATTRIBUTE_TABLE} which is
2875 defined for each machine. See the GCC manual for further information.
2876 It is not possible to specify attributes defined by other languages,
2877 only attributes defined by the machine the code is intended to run on.
2879 @node Pragma Main_Storage
2880 @unnumberedsec Pragma Main_Storage
2882 @findex Main_Storage
2886 @smallexample @c ada
2888 (MAIN_STORAGE_OPTION [, MAIN_STORAGE_OPTION]);
2890 MAIN_STORAGE_OPTION ::=
2891 [WORKING_STORAGE =>] static_SIMPLE_EXPRESSION
2892 | [TOP_GUARD =>] static_SIMPLE_EXPRESSION
2897 This pragma is provided for compatibility with OpenVMS VAX Systems. It has
2898 no effect in GNAT, other than being syntax checked. Note that the pragma
2899 also has no effect in DEC Ada 83 for OpenVMS Alpha Systems.
2901 @node Pragma No_Return
2902 @unnumberedsec Pragma No_Return
2907 @smallexample @c ada
2908 pragma No_Return (procedure_local_NAME);
2912 @var{procedure_local_NAME} must refer to one or more procedure
2913 declarations in the current declarative part. A procedure to which this
2914 pragma is applied may not contain any explicit @code{return} statements,
2915 and also may not contain any implicit return statements from falling off
2916 the end of a statement sequence. One use of this pragma is to identify
2917 procedures whose only purpose is to raise an exception.
2919 Another use of this pragma is to suppress incorrect warnings about
2920 missing returns in functions, where the last statement of a function
2921 statement sequence is a call to such a procedure.
2923 @node Pragma No_Strict_Aliasing
2924 @unnumberedsec Pragma No_Strict_Aliasing
2925 @findex No_Strict_Aliasing
2929 @smallexample @c ada
2930 ppragma No_Strict_Aliasing [([Entity =>] type_LOCAL_NAME)];
2934 @var{type_LOCAL_NAME} must refer to an access type
2935 declaration in the current declarative part. The effect is to inhibit
2936 strict aliasing optimization for the given type. The form with no
2937 arguments is a configuration pragma which applies to all access types
2938 declared in units to which the pragma applies. For a detailed
2939 description of the strict aliasing optimization, and the situations
2940 in which it must be suppressed, see section "Optimization and Strict Aliasing"
2941 in the @value{EDITION} User's Guide.
2943 @node Pragma Normalize_Scalars
2944 @unnumberedsec Pragma Normalize_Scalars
2945 @findex Normalize_Scalars
2949 @smallexample @c ada
2950 pragma Normalize_Scalars;
2954 This is a language defined pragma which is fully implemented in GNAT@. The
2955 effect is to cause all scalar objects that are not otherwise initialized
2956 to be initialized. The initial values are implementation dependent and
2960 @item Standard.Character
2962 Objects whose root type is Standard.Character are initialized to
2963 Character'Last unless the subtype range excludes NUL (in which case
2964 NUL is used). This choice will always generate an invalid value if
2967 @item Standard.Wide_Character
2969 Objects whose root type is Standard.Wide_Character are initialized to
2970 Wide_Character'Last unless the subtype range excludes NUL (in which case
2971 NUL is used). This choice will always generate an invalid value if
2974 @item Standard.Wide_Wide_Character
2976 Objects whose root type is Standard.Wide_Wide_Character are initialized to
2977 the invalid value 16#FFFF_FFFF# unless the subtype range excludes NUL (in
2978 which case NUL is used). This choice will always generate an invalid value if
2983 Objects of an integer type are treated differently depending on whether
2984 negative values are present in the subtype. If no negative values are
2985 present, then all one bits is used as the initial value except in the
2986 special case where zero is excluded from the subtype, in which case
2987 all zero bits are used. This choice will always generate an invalid
2988 value if one exists.
2990 For subtypes with negative values present, the largest negative number
2991 is used, except in the unusual case where this largest negative number
2992 is in the subtype, and the largest positive number is not, in which case
2993 the largest positive value is used. This choice will always generate
2994 an invalid value if one exists.
2996 @item Floating-Point Types
2997 Objects of all floating-point types are initialized to all 1-bits. For
2998 standard IEEE format, this corresponds to a NaN (not a number) which is
2999 indeed an invalid value.
3001 @item Fixed-Point Types
3002 Objects of all fixed-point types are treated as described above for integers,
3003 with the rules applying to the underlying integer value used to represent
3004 the fixed-point value.
3007 Objects of a modular type are initialized to all one bits, except in
3008 the special case where zero is excluded from the subtype, in which
3009 case all zero bits are used. This choice will always generate an
3010 invalid value if one exists.
3012 @item Enumeration types
3013 Objects of an enumeration type are initialized to all one-bits, i.e.@: to
3014 the value @code{2 ** typ'Size - 1} unless the subtype excludes the literal
3015 whose Pos value is zero, in which case a code of zero is used. This choice
3016 will always generate an invalid value if one exists.
3020 @node Pragma Obsolescent
3021 @unnumberedsec Pragma Obsolescent
3026 @smallexample @c ada
3027 pragma Obsolescent [(static_string_EXPRESSION [,Ada_05])];
3031 This pragma must occur immediately following a subprogram
3032 declaration. It indicates that the associated function or procedure
3033 is considered obsolescent and should not be used. Typically this is
3034 used when an API must be modified by eventually removing or modifying
3035 existing subprograms. The pragma can be used at an intermediate stage
3036 when the subprogram is still present, but will be removed later.
3038 The effect of this pragma is to output a warning message that the
3039 subprogram is obsolescent if the appropriate warning option in the
3040 compiler is activated. If a parameter is present, then a second
3041 warning message is given containing this text.
3043 In addition, a call to such a program is considered a violation of
3044 pragma Restrictions (No_Obsolescent_Features).
3046 If the optional second parameter is present (which must be exactly
3047 the identifier Ada_05, no other argument is allowed), then the
3048 indication of obsolescence applies only when compiling in Ada 2005
3049 mode. This is primarily intended for dealing with the situations
3050 in the predefined library where subprograms have become defined
3051 as obsolescent in Ada 2005 (e.g. in Ada.Characters.Handling), but
3052 may be used anywhere.
3054 @node Pragma Passive
3055 @unnumberedsec Pragma Passive
3060 @smallexample @c ada
3061 pragma Passive ([Semaphore | No]);
3065 Syntax checked, but otherwise ignored by GNAT@. This is recognized for
3066 compatibility with DEC Ada 83 implementations, where it is used within a
3067 task definition to request that a task be made passive. If the argument
3068 @code{Semaphore} is present, or the argument is omitted, then DEC Ada 83
3069 treats the pragma as an assertion that the containing task is passive
3070 and that optimization of context switch with this task is permitted and
3071 desired. If the argument @code{No} is present, the task must not be
3072 optimized. GNAT does not attempt to optimize any tasks in this manner
3073 (since protected objects are available in place of passive tasks).
3075 @node Pragma Persistent_BSS
3076 @unnumberedsec Pragma Persistent_BSS
3077 @findex Persistent_BSS
3081 @smallexample @c ada
3082 pragma Persistent_BSS [local_NAME]
3086 This pragma allows selected objects to be placed in the @code{.persistent_bss}
3087 section. On some targets the linker and loader provide for special
3088 treatment of this section, allowing a program to be reloaded without
3089 affecting the contents of this data (hence the name persistent).
3091 There are two forms of usage. If an argument is given, it must be the
3092 local name of a library level object, with no explicit initialization
3093 and whose type is potentially persistent. If no argument is given, then
3094 the pragma is a configuration pragma, and applies to all library level
3095 objects with no explicit initialization of potentially persistent types.
3097 A potentially persistent type is a scalar type, or a non-tagged,
3098 non-discriminated record, all of whose components have no explicit
3099 initialization and are themselves of a potentially persistent type,
3100 or an array, all of whose constraints are static, and whose component
3101 type is potentially persistent.
3103 If this pragma is used on a target where this feature is not supported,
3104 then the pragma will be ignored. See also @code{pragma Linker_Section}.
3106 @node Pragma Polling
3107 @unnumberedsec Pragma Polling
3112 @smallexample @c ada
3113 pragma Polling (ON | OFF);
3117 This pragma controls the generation of polling code. This is normally off.
3118 If @code{pragma Polling (ON)} is used then periodic calls are generated to
3119 the routine @code{Ada.Exceptions.Poll}. This routine is a separate unit in the
3120 runtime library, and can be found in file @file{a-excpol.adb}.
3122 Pragma @code{Polling} can appear as a configuration pragma (for example it
3123 can be placed in the @file{gnat.adc} file) to enable polling globally, or it
3124 can be used in the statement or declaration sequence to control polling
3127 A call to the polling routine is generated at the start of every loop and
3128 at the start of every subprogram call. This guarantees that the @code{Poll}
3129 routine is called frequently, and places an upper bound (determined by
3130 the complexity of the code) on the period between two @code{Poll} calls.
3132 The primary purpose of the polling interface is to enable asynchronous
3133 aborts on targets that cannot otherwise support it (for example Windows
3134 NT), but it may be used for any other purpose requiring periodic polling.
3135 The standard version is null, and can be replaced by a user program. This
3136 will require re-compilation of the @code{Ada.Exceptions} package that can
3137 be found in files @file{a-except.ads} and @file{a-except.adb}.
3139 A standard alternative unit (in file @file{4wexcpol.adb} in the standard GNAT
3140 distribution) is used to enable the asynchronous abort capability on
3141 targets that do not normally support the capability. The version of
3142 @code{Poll} in this file makes a call to the appropriate runtime routine
3143 to test for an abort condition.
3145 Note that polling can also be enabled by use of the @code{-gnatP} switch. See
3146 the @cite{GNAT User's Guide} for details.
3148 @node Pragma Profile (Ravenscar)
3149 @unnumberedsec Pragma Profile (Ravenscar)
3154 @smallexample @c ada
3155 pragma Profile (Ravenscar);
3159 A configuration pragma that establishes the following set of configuration
3163 @item Task_Dispatching_Policy (FIFO_Within_Priorities)
3164 [RM D.2.2] Tasks are dispatched following a preemptive
3165 priority-ordered scheduling policy.
3167 @item Locking_Policy (Ceiling_Locking)
3168 [RM D.3] While tasks and interrupts execute a protected action, they inherit
3169 the ceiling priority of the corresponding protected object.
3171 @c @item Detect_Blocking
3172 @c This pragma forces the detection of potentially blocking operations within a
3173 @c protected operation, and to raise Program_Error if that happens.
3177 plus the following set of restrictions:
3180 @item Max_Entry_Queue_Length = 1
3181 Defines the maximum number of calls that are queued on a (protected) entry.
3182 Note that this restrictions is checked at run time. Violation of this
3183 restriction results in the raising of Program_Error exception at the point of
3184 the call. For the Profile (Ravenscar) the value of Max_Entry_Queue_Length is
3185 always 1 and hence no task can be queued on a protected entry.
3187 @item Max_Protected_Entries = 1
3188 [RM D.7] Specifies the maximum number of entries per protected type. The
3189 bounds of every entry family of a protected unit shall be static, or shall be
3190 defined by a discriminant of a subtype whose corresponding bound is static.
3191 For the Profile (Ravenscar) the value of Max_Protected_Entries is always 1.
3193 @item Max_Task_Entries = 0
3194 [RM D.7] Specifies the maximum number of entries
3195 per task. The bounds of every entry family
3196 of a task unit shall be static, or shall be
3197 defined by a discriminant of a subtype whose
3198 corresponding bound is static. A value of zero
3199 indicates that no rendezvous are possible. For
3200 the Profile (Ravenscar), the value of Max_Task_Entries is always
3203 @item No_Abort_Statements
3204 [RM D.7] There are no abort_statements, and there are
3205 no calls to Task_Identification.Abort_Task.
3207 @item No_Asynchronous_Control
3208 [RM D.7] There are no semantic dependences on the package
3209 Asynchronous_Task_Control.
3212 There are no semantic dependencies on the package Ada.Calendar.
3214 @item No_Dynamic_Attachment
3215 There is no call to any of the operations defined in package Ada.Interrupts
3216 (Is_Reserved, Is_Attached, Current_Handler, Attach_Handler, Exchange_Handler,
3217 Detach_Handler, and Reference).
3219 @item No_Dynamic_Priorities
3220 [RM D.7] There are no semantic dependencies on the package Dynamic_Priorities.
3222 @item No_Implicit_Heap_Allocations
3223 [RM D.7] No constructs are allowed to cause implicit heap allocation.
3225 @item No_Local_Protected_Objects
3226 Protected objects and access types that designate
3227 such objects shall be declared only at library level.
3229 @item No_Protected_Type_Allocators
3230 There are no allocators for protected types or
3231 types containing protected subcomponents.
3233 @item No_Relative_Delay
3234 There are no delay_relative statements.
3236 @item No_Requeue_Statements
3237 Requeue statements are not allowed.
3239 @item No_Select_Statements
3240 There are no select_statements.
3242 @item No_Task_Allocators
3243 [RM D.7] There are no allocators for task types
3244 or types containing task subcomponents.
3246 @item No_Task_Attributes_Package
3247 There are no semantic dependencies on the Ada.Task_Attributes package.
3249 @item No_Task_Hierarchy
3250 [RM D.7] All (non-environment) tasks depend
3251 directly on the environment task of the partition.
3253 @item No_Task_Termination
3254 Tasks which terminate are erroneous.
3256 @item Simple_Barriers
3257 Entry barrier condition expressions shall be either static
3258 boolean expressions or boolean objects which are declared in
3259 the protected type which contains the entry.
3263 This set of configuration pragmas and restrictions correspond to the
3264 definition of the ``Ravenscar Profile'' for limited tasking, devised and
3265 published by the @cite{International Real-Time Ada Workshop}, 1997,
3266 and whose most recent description is available at
3267 @url{ftp://ftp.openravenscar.org/openravenscar/ravenscar00.pdf}.
3269 The original definition of the profile was revised at subsequent IRTAW
3270 meetings. It has been included in the ISO
3271 @cite{Guide for the Use of the Ada Programming Language in High
3272 Integrity Systems}, and has been approved by ISO/IEC/SC22/WG9 for inclusion in
3273 the next revision of the standard. The formal definition given by
3274 the Ada Rapporteur Group (ARG) can be found in two Ada Issues (AI-249 and
3275 AI-305) available at
3276 @url{http://www.ada-auth.org/cgi-bin/cvsweb.cgi/AIs/AI-00249.TXT} and
3277 @url{http://www.ada-auth.org/cgi-bin/cvsweb.cgi/AIs/AI-00305.TXT}
3280 The above set is a superset of the restrictions provided by pragma
3281 @code{Profile (Restricted)}, it includes six additional restrictions
3282 (@code{Simple_Barriers}, @code{No_Select_Statements},
3283 @code{No_Calendar}, @code{No_Implicit_Heap_Allocations},
3284 @code{No_Relative_Delay} and @code{No_Task_Termination}). This means
3285 that pragma @code{Profile (Ravenscar)}, like the pragma
3286 @code{Profile (Restricted)},
3287 automatically causes the use of a simplified,
3288 more efficient version of the tasking run-time system.
3290 @node Pragma Profile (Restricted)
3291 @unnumberedsec Pragma Profile (Restricted)
3292 @findex Restricted Run Time
3296 @smallexample @c ada
3297 pragma Profile (Restricted);
3301 A configuration pragma that establishes the following set of restrictions:
3304 @item No_Abort_Statements
3305 @item No_Entry_Queue
3306 @item No_Task_Hierarchy
3307 @item No_Task_Allocators
3308 @item No_Dynamic_Priorities
3309 @item No_Terminate_Alternatives
3310 @item No_Dynamic_Attachment
3311 @item No_Protected_Type_Allocators
3312 @item No_Local_Protected_Objects
3313 @item No_Requeue_Statements
3314 @item No_Task_Attributes_Package
3315 @item Max_Asynchronous_Select_Nesting = 0
3316 @item Max_Task_Entries = 0
3317 @item Max_Protected_Entries = 1
3318 @item Max_Select_Alternatives = 0
3322 This set of restrictions causes the automatic selection of a simplified
3323 version of the run time that provides improved performance for the
3324 limited set of tasking functionality permitted by this set of restrictions.
3326 @node Pragma Propagate_Exceptions
3327 @unnumberedsec Pragma Propagate_Exceptions
3328 @findex Propagate_Exceptions
3329 @cindex Zero Cost Exceptions
3333 @smallexample @c ada
3334 pragma Propagate_Exceptions (subprogram_local_NAME);
3338 This pragma indicates that the given entity, which is the name of an
3339 imported foreign-language subprogram may receive an Ada exception,
3340 and that the exception should be propagated. It is relevant only if
3341 zero cost exception handling is in use, and is thus never needed if
3342 the alternative @code{longjmp} / @code{setjmp} implementation of
3343 exceptions is used (although it is harmless to use it in such cases).
3345 The implementation of fast exceptions always properly propagates
3346 exceptions through Ada code, as described in the Ada Reference Manual.
3347 However, this manual is silent about the propagation of exceptions
3348 through foreign code. For example, consider the
3349 situation where @code{P1} calls
3350 @code{P2}, and @code{P2} calls @code{P3}, where
3351 @code{P1} and @code{P3} are in Ada, but @code{P2} is in C@.
3352 @code{P3} raises an Ada exception. The question is whether or not
3353 it will be propagated through @code{P2} and can be handled in
3356 For the @code{longjmp} / @code{setjmp} implementation of exceptions,
3357 the answer is always yes. For some targets on which zero cost exception
3358 handling is implemented, the answer is also always yes. However, there
3359 are some targets, notably in the current version all x86 architecture
3360 targets, in which the answer is that such propagation does not
3361 happen automatically. If such propagation is required on these
3362 targets, it is mandatory to use @code{Propagate_Exceptions} to
3363 name all foreign language routines through which Ada exceptions
3366 @node Pragma Psect_Object
3367 @unnumberedsec Pragma Psect_Object
3368 @findex Psect_Object
3372 @smallexample @c ada
3373 pragma Psect_Object (
3374 [Internal =>] local_NAME,
3375 [, [External =>] EXTERNAL_SYMBOL]
3376 [, [Size =>] EXTERNAL_SYMBOL]);
3380 | static_string_EXPRESSION
3384 This pragma is identical in effect to pragma @code{Common_Object}.
3386 @node Pragma Pure_Function
3387 @unnumberedsec Pragma Pure_Function
3388 @findex Pure_Function
3392 @smallexample @c ada
3393 pragma Pure_Function ([Entity =>] function_local_NAME);
3397 This pragma appears in the same declarative part as a function
3398 declaration (or a set of function declarations if more than one
3399 overloaded declaration exists, in which case the pragma applies
3400 to all entities). It specifies that the function @code{Entity} is
3401 to be considered pure for the purposes of code generation. This means
3402 that the compiler can assume that there are no side effects, and
3403 in particular that two calls with identical arguments produce the
3404 same result. It also means that the function can be used in an
3407 Note that, quite deliberately, there are no static checks to try
3408 to ensure that this promise is met, so @code{Pure_Function} can be used
3409 with functions that are conceptually pure, even if they do modify
3410 global variables. For example, a square root function that is
3411 instrumented to count the number of times it is called is still
3412 conceptually pure, and can still be optimized, even though it
3413 modifies a global variable (the count). Memo functions are another
3414 example (where a table of previous calls is kept and consulted to
3415 avoid re-computation).
3418 Note: Most functions in a @code{Pure} package are automatically pure, and
3419 there is no need to use pragma @code{Pure_Function} for such functions. One
3420 exception is any function that has at least one formal of type
3421 @code{System.Address} or a type derived from it. Such functions are not
3422 considered pure by default, since the compiler assumes that the
3423 @code{Address} parameter may be functioning as a pointer and that the
3424 referenced data may change even if the address value does not.
3425 Similarly, imported functions are not considered to be pure by default,
3426 since there is no way of checking that they are in fact pure. The use
3427 of pragma @code{Pure_Function} for such a function will override these default
3428 assumption, and cause the compiler to treat a designated subprogram as pure
3431 Note: If pragma @code{Pure_Function} is applied to a renamed function, it
3432 applies to the underlying renamed function. This can be used to
3433 disambiguate cases of overloading where some but not all functions
3434 in a set of overloaded functions are to be designated as pure.
3436 @node Pragma Restriction_Warnings
3437 @unnumberedsec Pragma Restriction_Warnings
3438 @findex Restriction_Warnings
3442 @smallexample @c ada
3443 pragma Restriction_Warnings
3444 (restriction_IDENTIFIER @{, restriction_IDENTIFIER@});
3448 This pragma allows a series of restriction identifiers to be
3449 specified (the list of allowed identifiers is the same as for
3450 pragma @code{Restrictions}). For each of these identifiers
3451 the compiler checks for violations of the restriction, but
3452 generates a warning message rather than an error message
3453 if the restriction is violated.
3455 @node Pragma Source_File_Name
3456 @unnumberedsec Pragma Source_File_Name
3457 @findex Source_File_Name
3461 @smallexample @c ada
3462 pragma Source_File_Name (
3463 [Unit_Name =>] unit_NAME,
3464 Spec_File_Name => STRING_LITERAL);
3466 pragma Source_File_Name (
3467 [Unit_Name =>] unit_NAME,
3468 Body_File_Name => STRING_LITERAL);
3472 Use this to override the normal naming convention. It is a configuration
3473 pragma, and so has the usual applicability of configuration pragmas
3474 (i.e.@: it applies to either an entire partition, or to all units in a
3475 compilation, or to a single unit, depending on how it is used.
3476 @var{unit_name} is mapped to @var{file_name_literal}. The identifier for
3477 the second argument is required, and indicates whether this is the file
3478 name for the spec or for the body.
3480 Another form of the @code{Source_File_Name} pragma allows
3481 the specification of patterns defining alternative file naming schemes
3482 to apply to all files.
3484 @smallexample @c ada
3485 pragma Source_File_Name
3486 (Spec_File_Name => STRING_LITERAL
3487 [,Casing => CASING_SPEC]
3488 [,Dot_Replacement => STRING_LITERAL]);
3490 pragma Source_File_Name
3491 (Body_File_Name => STRING_LITERAL
3492 [,Casing => CASING_SPEC]
3493 [,Dot_Replacement => STRING_LITERAL]);
3495 pragma Source_File_Name
3496 (Subunit_File_Name => STRING_LITERAL
3497 [,Casing => CASING_SPEC]
3498 [,Dot_Replacement => STRING_LITERAL]);
3500 CASING_SPEC ::= Lowercase | Uppercase | Mixedcase
3504 The first argument is a pattern that contains a single asterisk indicating
3505 the point at which the unit name is to be inserted in the pattern string
3506 to form the file name. The second argument is optional. If present it
3507 specifies the casing of the unit name in the resulting file name string.
3508 The default is lower case. Finally the third argument allows for systematic
3509 replacement of any dots in the unit name by the specified string literal.
3511 A pragma Source_File_Name cannot appear after a
3512 @ref{Pragma Source_File_Name_Project}.
3514 For more details on the use of the @code{Source_File_Name} pragma,
3515 see the sections ``Using Other File Names'' and
3516 ``Alternative File Naming Schemes'' in the @cite{GNAT User's Guide}.
3518 @node Pragma Source_File_Name_Project
3519 @unnumberedsec Pragma Source_File_Name_Project
3520 @findex Source_File_Name_Project
3523 This pragma has the same syntax and semantics as pragma Source_File_Name.
3524 It is only allowed as a stand alone configuration pragma.
3525 It cannot appear after a @ref{Pragma Source_File_Name}, and
3526 most importantly, once pragma Source_File_Name_Project appears,
3527 no further Source_File_Name pragmas are allowed.
3529 The intention is that Source_File_Name_Project pragmas are always
3530 generated by the Project Manager in a manner consistent with the naming
3531 specified in a project file, and when naming is controlled in this manner,
3532 it is not permissible to attempt to modify this naming scheme using
3533 Source_File_Name pragmas (which would not be known to the project manager).
3535 @node Pragma Source_Reference
3536 @unnumberedsec Pragma Source_Reference
3537 @findex Source_Reference
3541 @smallexample @c ada
3542 pragma Source_Reference (INTEGER_LITERAL, STRING_LITERAL);
3546 This pragma must appear as the first line of a source file.
3547 @var{integer_literal} is the logical line number of the line following
3548 the pragma line (for use in error messages and debugging
3549 information). @var{string_literal} is a static string constant that
3550 specifies the file name to be used in error messages and debugging
3551 information. This is most notably used for the output of @code{gnatchop}
3552 with the @code{-r} switch, to make sure that the original unchopped
3553 source file is the one referred to.
3555 The second argument must be a string literal, it cannot be a static
3556 string expression other than a string literal. This is because its value
3557 is needed for error messages issued by all phases of the compiler.
3559 @node Pragma Stream_Convert
3560 @unnumberedsec Pragma Stream_Convert
3561 @findex Stream_Convert
3565 @smallexample @c ada
3566 pragma Stream_Convert (
3567 [Entity =>] type_local_NAME,
3568 [Read =>] function_NAME,
3569 [Write =>] function_NAME);
3573 This pragma provides an efficient way of providing stream functions for
3574 types defined in packages. Not only is it simpler to use than declaring
3575 the necessary functions with attribute representation clauses, but more
3576 significantly, it allows the declaration to made in such a way that the
3577 stream packages are not loaded unless they are needed. The use of
3578 the Stream_Convert pragma adds no overhead at all, unless the stream
3579 attributes are actually used on the designated type.
3581 The first argument specifies the type for which stream functions are
3582 provided. The second parameter provides a function used to read values
3583 of this type. It must name a function whose argument type may be any
3584 subtype, and whose returned type must be the type given as the first
3585 argument to the pragma.
3587 The meaning of the @var{Read}
3588 parameter is that if a stream attribute directly
3589 or indirectly specifies reading of the type given as the first parameter,
3590 then a value of the type given as the argument to the Read function is
3591 read from the stream, and then the Read function is used to convert this
3592 to the required target type.
3594 Similarly the @var{Write} parameter specifies how to treat write attributes
3595 that directly or indirectly apply to the type given as the first parameter.
3596 It must have an input parameter of the type specified by the first parameter,
3597 and the return type must be the same as the input type of the Read function.
3598 The effect is to first call the Write function to convert to the given stream
3599 type, and then write the result type to the stream.
3601 The Read and Write functions must not be overloaded subprograms. If necessary
3602 renamings can be supplied to meet this requirement.
3603 The usage of this attribute is best illustrated by a simple example, taken
3604 from the GNAT implementation of package Ada.Strings.Unbounded:
3606 @smallexample @c ada
3607 function To_Unbounded (S : String)
3608 return Unbounded_String
3609 renames To_Unbounded_String;
3611 pragma Stream_Convert
3612 (Unbounded_String, To_Unbounded, To_String);
3616 The specifications of the referenced functions, as given in the Ada 95
3617 Reference Manual are:
3619 @smallexample @c ada
3620 function To_Unbounded_String (Source : String)
3621 return Unbounded_String;
3623 function To_String (Source : Unbounded_String)
3628 The effect is that if the value of an unbounded string is written to a
3629 stream, then the representation of the item in the stream is in the same
3630 format used for @code{Standard.String}, and this same representation is
3631 expected when a value of this type is read from the stream.
3633 @node Pragma Style_Checks
3634 @unnumberedsec Pragma Style_Checks
3635 @findex Style_Checks
3639 @smallexample @c ada
3640 pragma Style_Checks (string_LITERAL | ALL_CHECKS |
3641 On | Off [, local_NAME]);
3645 This pragma is used in conjunction with compiler switches to control the
3646 built in style checking provided by GNAT@. The compiler switches, if set,
3647 provide an initial setting for the switches, and this pragma may be used
3648 to modify these settings, or the settings may be provided entirely by
3649 the use of the pragma. This pragma can be used anywhere that a pragma
3650 is legal, including use as a configuration pragma (including use in
3651 the @file{gnat.adc} file).
3653 The form with a string literal specifies which style options are to be
3654 activated. These are additive, so they apply in addition to any previously
3655 set style check options. The codes for the options are the same as those
3656 used in the @code{-gnaty} switch to @code{gcc} or @code{gnatmake}.
3657 For example the following two methods can be used to enable
3662 @smallexample @c ada
3663 pragma Style_Checks ("l");
3668 gcc -c -gnatyl @dots{}
3673 The form ALL_CHECKS activates all standard checks (its use is equivalent
3674 to the use of the @code{gnaty} switch with no options. See GNAT User's
3677 The forms with @code{Off} and @code{On}
3678 can be used to temporarily disable style checks
3679 as shown in the following example:
3681 @smallexample @c ada
3685 pragma Style_Checks ("k"); -- requires keywords in lower case
3686 pragma Style_Checks (Off); -- turn off style checks
3687 NULL; -- this will not generate an error message
3688 pragma Style_Checks (On); -- turn style checks back on
3689 NULL; -- this will generate an error message
3693 Finally the two argument form is allowed only if the first argument is
3694 @code{On} or @code{Off}. The effect is to turn of semantic style checks
3695 for the specified entity, as shown in the following example:
3697 @smallexample @c ada
3701 pragma Style_Checks ("r"); -- require consistency of identifier casing
3703 Rf1 : Integer := ARG; -- incorrect, wrong case
3704 pragma Style_Checks (Off, Arg);
3705 Rf2 : Integer := ARG; -- OK, no error
3708 @node Pragma Subtitle
3709 @unnumberedsec Pragma Subtitle
3714 @smallexample @c ada
3715 pragma Subtitle ([Subtitle =>] STRING_LITERAL);
3719 This pragma is recognized for compatibility with other Ada compilers
3720 but is ignored by GNAT@.
3722 @node Pragma Suppress_All
3723 @unnumberedsec Pragma Suppress_All
3724 @findex Suppress_All
3728 @smallexample @c ada
3729 pragma Suppress_All;
3733 This pragma can only appear immediately following a compilation
3734 unit. The effect is to apply @code{Suppress (All_Checks)} to the unit
3735 which it follows. This pragma is implemented for compatibility with DEC
3736 Ada 83 usage. The use of pragma @code{Suppress (All_Checks)} as a normal
3737 configuration pragma is the preferred usage in GNAT@.
3739 @node Pragma Suppress_Exception_Locations
3740 @unnumberedsec Pragma Suppress_Exception_Locations
3741 @findex Suppress_Exception_Locations
3745 @smallexample @c ada
3746 pragma Suppress_Exception_Locations;
3750 In normal mode, a raise statement for an exception by default generates
3751 an exception message giving the file name and line number for the location
3752 of the raise. This is useful for debugging and logging purposes, but this
3753 entails extra space for the strings for the messages. The configuration
3754 pragma @code{Suppress_Exception_Locations} can be used to suppress the
3755 generation of these strings, with the result that space is saved, but the
3756 exception message for such raises is null. This configuration pragma may
3757 appear in a global configuration pragma file, or in a specific unit as
3758 usual. It is not required that this pragma be used consistently within
3759 a partition, so it is fine to have some units within a partition compiled
3760 with this pragma and others compiled in normal mode without it.
3762 @node Pragma Suppress_Initialization
3763 @unnumberedsec Pragma Suppress_Initialization
3764 @findex Suppress_Initialization
3765 @cindex Suppressing initialization
3766 @cindex Initialization, suppression of
3770 @smallexample @c ada
3771 pragma Suppress_Initialization ([Entity =>] type_Name);
3775 This pragma suppresses any implicit or explicit initialization
3776 associated with the given type name for all variables of this type.
3778 @node Pragma Task_Info
3779 @unnumberedsec Pragma Task_Info
3784 @smallexample @c ada
3785 pragma Task_Info (EXPRESSION);
3789 This pragma appears within a task definition (like pragma
3790 @code{Priority}) and applies to the task in which it appears. The
3791 argument must be of type @code{System.Task_Info.Task_Info_Type}.
3792 The @code{Task_Info} pragma provides system dependent control over
3793 aspects of tasking implementation, for example, the ability to map
3794 tasks to specific processors. For details on the facilities available
3795 for the version of GNAT that you are using, see the documentation
3796 in the specification of package System.Task_Info in the runtime
3799 @node Pragma Task_Name
3800 @unnumberedsec Pragma Task_Name
3805 @smallexample @c ada
3806 pragma Task_Name (string_EXPRESSION);
3810 This pragma appears within a task definition (like pragma
3811 @code{Priority}) and applies to the task in which it appears. The
3812 argument must be of type String, and provides a name to be used for
3813 the task instance when the task is created. Note that this expression
3814 is not required to be static, and in particular, it can contain
3815 references to task discriminants. This facility can be used to
3816 provide different names for different tasks as they are created,
3817 as illustrated in the example below.
3819 The task name is recorded internally in the run-time structures
3820 and is accessible to tools like the debugger. In addition the
3821 routine @code{Ada.Task_Identification.Image} will return this
3822 string, with a unique task address appended.
3824 @smallexample @c ada
3825 -- Example of the use of pragma Task_Name
3827 with Ada.Task_Identification;
3828 use Ada.Task_Identification;
3829 with Text_IO; use Text_IO;
3832 type Astring is access String;
3834 task type Task_Typ (Name : access String) is
3835 pragma Task_Name (Name.all);
3838 task body Task_Typ is
3839 Nam : constant String := Image (Current_Task);
3841 Put_Line ("-->" & Nam (1 .. 14) & "<--");
3844 type Ptr_Task is access Task_Typ;
3845 Task_Var : Ptr_Task;
3849 new Task_Typ (new String'("This is task 1"));
3851 new Task_Typ (new String'("This is task 2"));
3855 @node Pragma Task_Storage
3856 @unnumberedsec Pragma Task_Storage
3857 @findex Task_Storage
3860 @smallexample @c ada
3861 pragma Task_Storage (
3862 [Task_Type =>] local_NAME,
3863 [Top_Guard =>] static_integer_EXPRESSION);
3867 This pragma specifies the length of the guard area for tasks. The guard
3868 area is an additional storage area allocated to a task. A value of zero
3869 means that either no guard area is created or a minimal guard area is
3870 created, depending on the target. This pragma can appear anywhere a
3871 @code{Storage_Size} attribute definition clause is allowed for a task
3874 @node Pragma Thread_Body
3875 @unnumberedsec Pragma Thread_Body
3879 @smallexample @c ada
3880 pragma Thread_Body (
3881 [Entity =>] local_NAME,
3882 [[Secondary_Stack_Size =>] static_integer_EXPRESSION)];
3886 This pragma specifies that the subprogram whose name is given as the
3887 @code{Entity} argument is a thread body, which will be activated
3888 by being called via its Address from foreign code. The purpose is
3889 to allow execution and registration of the foreign thread within the
3890 Ada run-time system.
3892 See the library unit @code{System.Threads} for details on the expansion of
3893 a thread body subprogram, including the calls made to subprograms
3894 within System.Threads to register the task. This unit also lists the
3895 targets and runtime systems for which this pragma is supported.
3897 A thread body subprogram may not be called directly from Ada code, and
3898 it is not permitted to apply the Access (or Unrestricted_Access) attributes
3899 to such a subprogram. The only legitimate way of calling such a subprogram
3900 is to pass its Address to foreign code and then make the call from the
3903 A thread body subprogram may have any parameters, and it may be a function
3904 returning a result. The convention of the thread body subprogram may be
3905 set in the usual manner using @code{pragma Convention}.
3907 The secondary stack size parameter, if given, is used to set the size
3908 of secondary stack for the thread. The secondary stack is allocated as
3909 a local variable of the expanded thread body subprogram, and thus is
3910 allocated out of the main thread stack size. If no secondary stack
3911 size parameter is present, the default size (from the declaration in
3912 @code{System.Secondary_Stack} is used.
3914 @node Pragma Time_Slice
3915 @unnumberedsec Pragma Time_Slice
3920 @smallexample @c ada
3921 pragma Time_Slice (static_duration_EXPRESSION);
3925 For implementations of GNAT on operating systems where it is possible
3926 to supply a time slice value, this pragma may be used for this purpose.
3927 It is ignored if it is used in a system that does not allow this control,
3928 or if it appears in other than the main program unit.
3930 Note that the effect of this pragma is identical to the effect of the
3931 DEC Ada 83 pragma of the same name when operating under OpenVMS systems.
3934 @unnumberedsec Pragma Title
3939 @smallexample @c ada
3940 pragma Title (TITLING_OPTION [, TITLING OPTION]);
3943 [Title =>] STRING_LITERAL,
3944 | [Subtitle =>] STRING_LITERAL
3948 Syntax checked but otherwise ignored by GNAT@. This is a listing control
3949 pragma used in DEC Ada 83 implementations to provide a title and/or
3950 subtitle for the program listing. The program listing generated by GNAT
3951 does not have titles or subtitles.
3953 Unlike other pragmas, the full flexibility of named notation is allowed
3954 for this pragma, i.e.@: the parameters may be given in any order if named
3955 notation is used, and named and positional notation can be mixed
3956 following the normal rules for procedure calls in Ada.
3958 @node Pragma Unchecked_Union
3959 @unnumberedsec Pragma Unchecked_Union
3961 @findex Unchecked_Union
3965 @smallexample @c ada
3966 pragma Unchecked_Union (first_subtype_local_NAME);
3970 This pragma is used to declare that the specified type should be represented
3972 equivalent to a C union type, and is intended only for use in
3973 interfacing with C code that uses union types. In Ada terms, the named
3974 type must obey the following rules:
3978 It is a non-tagged non-limited record type.
3980 It has a single discrete discriminant with a default value.
3982 The component list consists of a single variant part.
3984 Each variant has a component list with a single component.
3986 No nested variants are allowed.
3988 No component has an explicit default value.
3990 No component has a non-static constraint.
3994 In addition, given a type that meets the above requirements, the
3995 following restrictions apply to its use throughout the program:
3999 The discriminant name can be mentioned only in an aggregate.
4001 No subtypes may be created of this type.
4003 The type may not be constrained by giving a discriminant value.
4005 The type cannot be passed as the actual for a generic formal with a
4010 Equality and inequality operations on @code{unchecked_unions} are not
4011 available, since there is no discriminant to compare and the compiler
4012 does not even know how many bits to compare. It is implementation
4013 dependent whether this is detected at compile time as an illegality or
4014 whether it is undetected and considered to be an erroneous construct. In
4015 GNAT, a direct comparison is illegal, but GNAT does not attempt to catch
4016 the composite case (where two composites are compared that contain an
4017 unchecked union component), so such comparisons are simply considered
4020 The layout of the resulting type corresponds exactly to a C union, where
4021 each branch of the union corresponds to a single variant in the Ada
4022 record. The semantics of the Ada program is not changed in any way by
4023 the pragma, i.e.@: provided the above restrictions are followed, and no
4024 erroneous incorrect references to fields or erroneous comparisons occur,
4025 the semantics is exactly as described by the Ada reference manual.
4026 Pragma @code{Suppress (Discriminant_Check)} applies implicitly to the
4027 type and the default convention is C.
4029 @node Pragma Unimplemented_Unit
4030 @unnumberedsec Pragma Unimplemented_Unit
4031 @findex Unimplemented_Unit
4035 @smallexample @c ada
4036 pragma Unimplemented_Unit;
4040 If this pragma occurs in a unit that is processed by the compiler, GNAT
4041 aborts with the message @samp{@var{xxx} not implemented}, where
4042 @var{xxx} is the name of the current compilation unit. This pragma is
4043 intended to allow the compiler to handle unimplemented library units in
4046 The abort only happens if code is being generated. Thus you can use
4047 specs of unimplemented packages in syntax or semantic checking mode.
4049 @node Pragma Universal_Data
4050 @unnumberedsec Pragma Universal_Data
4051 @findex Universal_Data
4055 @smallexample @c ada
4056 pragma Universal_Data [(library_unit_Name)];
4060 This pragma is supported only for the AAMP target and is ignored for
4061 other targets. The pragma specifies that all library-level objects
4062 (Counter 0 data) associated with the library unit are to be accessed
4063 and updated using universal addressing (24-bit addresses for AAMP5)
4064 rather than the default of 16-bit Data Environment (DENV) addressing.
4065 Use of this pragma will generally result in less efficient code for
4066 references to global data associated with the library unit, but
4067 allows such data to be located anywhere in memory. This pragma is
4068 a library unit pragma, but can also be used as a configuration pragma
4069 (including use in the @file{gnat.adc} file). The functionality
4070 of this pragma is also available by applying the -univ switch on the
4071 compilations of units where universal addressing of the data is desired.
4073 @node Pragma Unreferenced
4074 @unnumberedsec Pragma Unreferenced
4075 @findex Unreferenced
4076 @cindex Warnings, unreferenced
4080 @smallexample @c ada
4081 pragma Unreferenced (local_NAME @{, local_NAME@});
4085 This pragma signals that the entities whose names are listed are
4086 deliberately not referenced in the current source unit. This
4087 suppresses warnings about the
4088 entities being unreferenced, and in addition a warning will be
4089 generated if one of these entities is in fact referenced in the
4090 same unit as the pragma (or in the corresponding body, or one
4093 This is particularly useful for clearly signaling that a particular
4094 parameter is not referenced in some particular subprogram implementation
4095 and that this is deliberate. It can also be useful in the case of
4096 objects declared only for their initialization or finalization side
4099 If @code{local_NAME} identifies more than one matching homonym in the
4100 current scope, then the entity most recently declared is the one to which
4103 The left hand side of an assignment does not count as a reference for the
4104 purpose of this pragma. Thus it is fine to assign to an entity for which
4105 pragma Unreferenced is given.
4107 Note that if a warning is desired for all calls to a given subprogram,
4108 regardless of whether they occur in the same unit as the subprogram
4109 declaration, then this pragma should not be used (calls from another
4110 unit would not be flagged); pragma Obsolescent can be used instead
4111 for this purpose, see @xref{Pragma Obsolescent}.
4113 @node Pragma Unreserve_All_Interrupts
4114 @unnumberedsec Pragma Unreserve_All_Interrupts
4115 @findex Unreserve_All_Interrupts
4119 @smallexample @c ada
4120 pragma Unreserve_All_Interrupts;
4124 Normally certain interrupts are reserved to the implementation. Any attempt
4125 to attach an interrupt causes Program_Error to be raised, as described in
4126 RM C.3.2(22). A typical example is the @code{SIGINT} interrupt used in
4127 many systems for a @kbd{Ctrl-C} interrupt. Normally this interrupt is
4128 reserved to the implementation, so that @kbd{Ctrl-C} can be used to
4129 interrupt execution.
4131 If the pragma @code{Unreserve_All_Interrupts} appears anywhere in any unit in
4132 a program, then all such interrupts are unreserved. This allows the
4133 program to handle these interrupts, but disables their standard
4134 functions. For example, if this pragma is used, then pressing
4135 @kbd{Ctrl-C} will not automatically interrupt execution. However,
4136 a program can then handle the @code{SIGINT} interrupt as it chooses.
4138 For a full list of the interrupts handled in a specific implementation,
4139 see the source code for the specification of @code{Ada.Interrupts.Names} in
4140 file @file{a-intnam.ads}. This is a target dependent file that contains the
4141 list of interrupts recognized for a given target. The documentation in
4142 this file also specifies what interrupts are affected by the use of
4143 the @code{Unreserve_All_Interrupts} pragma.
4145 For a more general facility for controlling what interrupts can be
4146 handled, see pragma @code{Interrupt_State}, which subsumes the functionality
4147 of the @code{Unreserve_All_Interrupts} pragma.
4149 @node Pragma Unsuppress
4150 @unnumberedsec Pragma Unsuppress
4155 @smallexample @c ada
4156 pragma Unsuppress (IDENTIFIER [, [On =>] NAME]);
4160 This pragma undoes the effect of a previous pragma @code{Suppress}. If
4161 there is no corresponding pragma @code{Suppress} in effect, it has no
4162 effect. The range of the effect is the same as for pragma
4163 @code{Suppress}. The meaning of the arguments is identical to that used
4164 in pragma @code{Suppress}.
4166 One important application is to ensure that checks are on in cases where
4167 code depends on the checks for its correct functioning, so that the code
4168 will compile correctly even if the compiler switches are set to suppress
4171 @node Pragma Use_VADS_Size
4172 @unnumberedsec Pragma Use_VADS_Size
4173 @cindex @code{Size}, VADS compatibility
4174 @findex Use_VADS_Size
4178 @smallexample @c ada
4179 pragma Use_VADS_Size;
4183 This is a configuration pragma. In a unit to which it applies, any use
4184 of the 'Size attribute is automatically interpreted as a use of the
4185 'VADS_Size attribute. Note that this may result in incorrect semantic
4186 processing of valid Ada 95 programs. This is intended to aid in the
4187 handling of legacy code which depends on the interpretation of Size
4188 as implemented in the VADS compiler. See description of the VADS_Size
4189 attribute for further details.
4191 @node Pragma Validity_Checks
4192 @unnumberedsec Pragma Validity_Checks
4193 @findex Validity_Checks
4197 @smallexample @c ada
4198 pragma Validity_Checks (string_LITERAL | ALL_CHECKS | On | Off);
4202 This pragma is used in conjunction with compiler switches to control the
4203 built-in validity checking provided by GNAT@. The compiler switches, if set
4204 provide an initial setting for the switches, and this pragma may be used
4205 to modify these settings, or the settings may be provided entirely by
4206 the use of the pragma. This pragma can be used anywhere that a pragma
4207 is legal, including use as a configuration pragma (including use in
4208 the @file{gnat.adc} file).
4210 The form with a string literal specifies which validity options are to be
4211 activated. The validity checks are first set to include only the default
4212 reference manual settings, and then a string of letters in the string
4213 specifies the exact set of options required. The form of this string
4214 is exactly as described for the @code{-gnatVx} compiler switch (see the
4215 GNAT users guide for details). For example the following two methods
4216 can be used to enable validity checking for mode @code{in} and
4217 @code{in out} subprogram parameters:
4221 @smallexample @c ada
4222 pragma Validity_Checks ("im");
4227 gcc -c -gnatVim @dots{}
4232 The form ALL_CHECKS activates all standard checks (its use is equivalent
4233 to the use of the @code{gnatva} switch.
4235 The forms with @code{Off} and @code{On}
4236 can be used to temporarily disable validity checks
4237 as shown in the following example:
4239 @smallexample @c ada
4243 pragma Validity_Checks ("c"); -- validity checks for copies
4244 pragma Validity_Checks (Off); -- turn off validity checks
4245 A := B; -- B will not be validity checked
4246 pragma Validity_Checks (On); -- turn validity checks back on
4247 A := C; -- C will be validity checked
4250 @node Pragma Volatile
4251 @unnumberedsec Pragma Volatile
4256 @smallexample @c ada
4257 pragma Volatile (local_NAME);
4261 This pragma is defined by the Ada 95 Reference Manual, and the GNAT
4262 implementation is fully conformant with this definition. The reason it
4263 is mentioned in this section is that a pragma of the same name was supplied
4264 in some Ada 83 compilers, including DEC Ada 83. The Ada 95 implementation
4265 of pragma Volatile is upwards compatible with the implementation in
4268 @node Pragma Warnings
4269 @unnumberedsec Pragma Warnings
4274 @smallexample @c ada
4275 pragma Warnings (On | Off [, local_NAME]);
4279 Normally warnings are enabled, with the output being controlled by
4280 the command line switch. Warnings (@code{Off}) turns off generation of
4281 warnings until a Warnings (@code{On}) is encountered or the end of the
4282 current unit. If generation of warnings is turned off using this
4283 pragma, then no warning messages are output, regardless of the
4284 setting of the command line switches.
4286 The form with a single argument is a configuration pragma.
4288 If the @var{local_NAME} parameter is present, warnings are suppressed for
4289 the specified entity. This suppression is effective from the point where
4290 it occurs till the end of the extended scope of the variable (similar to
4291 the scope of @code{Suppress}).
4293 @node Pragma Weak_External
4294 @unnumberedsec Pragma Weak_External
4295 @findex Weak_External
4299 @smallexample @c ada
4300 pragma Weak_External ([Entity =>] local_NAME);
4304 @var{local_NAME} must refer to an object that is declared at the library
4305 level. This pragma specifies that the given entity should be marked as a
4306 weak symbol for the linker. It is equivalent to @code{__attribute__((weak))}
4307 in GNU C and causes @var{local_NAME} to be emitted as a weak symbol instead
4308 of a regular symbol, that is to say a symbol that does not have to be
4309 resolved by the linker if used in conjunction with a pragma Import.
4311 When a weak symbol is not resolved by the linker, its address is set to
4312 zero. This is useful in writing interfaces to external modules that may
4313 or may not be linked in the final executable, for example depending on
4314 configuration settings.
4316 If a program references at run time an entity to which this pragma has been
4317 applied, and the corresponding symbol was not resolved at link time, then
4318 the execution of the program is erroneous. It is not erroneous to take the
4319 Address of such an entity, for example to guard potential references,
4320 as shown in the example below.
4322 Some file formats do not support weak symbols so not all target machines
4323 support this pragma.
4325 @smallexample @c ada
4326 -- Example of the use of pragma Weak_External
4328 package External_Module is
4330 pragma Import (C, key);
4331 pragma Weak_External (key);
4332 function Present return boolean;
4333 end External_Module;
4335 with System; use System;
4336 package body External_Module is
4337 function Present return boolean is
4339 return key'Address /= System.Null_Address;
4341 end External_Module;
4344 @node Implementation Defined Attributes
4345 @chapter Implementation Defined Attributes
4346 Ada 95 defines (throughout the Ada 95 reference manual,
4347 summarized in annex K),
4348 a set of attributes that provide useful additional functionality in all
4349 areas of the language. These language defined attributes are implemented
4350 in GNAT and work as described in the Ada 95 Reference Manual.
4352 In addition, Ada 95 allows implementations to define additional
4353 attributes whose meaning is defined by the implementation. GNAT provides
4354 a number of these implementation-dependent attributes which can be used
4355 to extend and enhance the functionality of the compiler. This section of
4356 the GNAT reference manual describes these additional attributes.
4358 Note that any program using these attributes may not be portable to
4359 other compilers (although GNAT implements this set of attributes on all
4360 platforms). Therefore if portability to other compilers is an important
4361 consideration, you should minimize the use of these attributes.
4372 * Default_Bit_Order::
4380 * Has_Access_Values::
4381 * Has_Discriminants::
4387 * Max_Interrupt_Priority::
4389 * Maximum_Alignment::
4393 * Passed_By_Reference::
4404 * Unconstrained_Array::
4405 * Universal_Literal_String::
4406 * Unrestricted_Access::
4414 @unnumberedsec Abort_Signal
4415 @findex Abort_Signal
4417 @code{Standard'Abort_Signal} (@code{Standard} is the only allowed
4418 prefix) provides the entity for the special exception used to signal
4419 task abort or asynchronous transfer of control. Normally this attribute
4420 should only be used in the tasking runtime (it is highly peculiar, and
4421 completely outside the normal semantics of Ada, for a user program to
4422 intercept the abort exception).
4425 @unnumberedsec Address_Size
4426 @cindex Size of @code{Address}
4427 @findex Address_Size
4429 @code{Standard'Address_Size} (@code{Standard} is the only allowed
4430 prefix) is a static constant giving the number of bits in an
4431 @code{Address}. It is the same value as System.Address'Size,
4432 but has the advantage of being static, while a direct
4433 reference to System.Address'Size is non-static because Address
4437 @unnumberedsec Asm_Input
4440 The @code{Asm_Input} attribute denotes a function that takes two
4441 parameters. The first is a string, the second is an expression of the
4442 type designated by the prefix. The first (string) argument is required
4443 to be a static expression, and is the constraint for the parameter,
4444 (e.g.@: what kind of register is required). The second argument is the
4445 value to be used as the input argument. The possible values for the
4446 constant are the same as those used in the RTL, and are dependent on
4447 the configuration file used to built the GCC back end.
4448 @ref{Machine Code Insertions}
4451 @unnumberedsec Asm_Output
4454 The @code{Asm_Output} attribute denotes a function that takes two
4455 parameters. The first is a string, the second is the name of a variable
4456 of the type designated by the attribute prefix. The first (string)
4457 argument is required to be a static expression and designates the
4458 constraint for the parameter (e.g.@: what kind of register is
4459 required). The second argument is the variable to be updated with the
4460 result. The possible values for constraint are the same as those used in
4461 the RTL, and are dependent on the configuration file used to build the
4462 GCC back end. If there are no output operands, then this argument may
4463 either be omitted, or explicitly given as @code{No_Output_Operands}.
4464 @ref{Machine Code Insertions}
4467 @unnumberedsec AST_Entry
4471 This attribute is implemented only in OpenVMS versions of GNAT@. Applied to
4472 the name of an entry, it yields a value of the predefined type AST_Handler
4473 (declared in the predefined package System, as extended by the use of
4474 pragma @code{Extend_System (Aux_DEC)}). This value enables the given entry to
4475 be called when an AST occurs. For further details, refer to the @cite{DEC Ada
4476 Language Reference Manual}, section 9.12a.
4481 @code{@var{obj}'Bit}, where @var{obj} is any object, yields the bit
4482 offset within the storage unit (byte) that contains the first bit of
4483 storage allocated for the object. The value of this attribute is of the
4484 type @code{Universal_Integer}, and is always a non-negative number not
4485 exceeding the value of @code{System.Storage_Unit}.
4487 For an object that is a variable or a constant allocated in a register,
4488 the value is zero. (The use of this attribute does not force the
4489 allocation of a variable to memory).
4491 For an object that is a formal parameter, this attribute applies
4492 to either the matching actual parameter or to a copy of the
4493 matching actual parameter.
4495 For an access object the value is zero. Note that
4496 @code{@var{obj}.all'Bit} is subject to an @code{Access_Check} for the
4497 designated object. Similarly for a record component
4498 @code{@var{X}.@var{C}'Bit} is subject to a discriminant check and
4499 @code{@var{X}(@var{I}).Bit} and @code{@var{X}(@var{I1}..@var{I2})'Bit}
4500 are subject to index checks.
4502 This attribute is designed to be compatible with the DEC Ada 83 definition
4503 and implementation of the @code{Bit} attribute.
4506 @unnumberedsec Bit_Position
4507 @findex Bit_Position
4509 @code{@var{R.C}'Bit}, where @var{R} is a record object and C is one
4510 of the fields of the record type, yields the bit
4511 offset within the record contains the first bit of
4512 storage allocated for the object. The value of this attribute is of the
4513 type @code{Universal_Integer}. The value depends only on the field
4514 @var{C} and is independent of the alignment of
4515 the containing record @var{R}.
4518 @unnumberedsec Code_Address
4519 @findex Code_Address
4520 @cindex Subprogram address
4521 @cindex Address of subprogram code
4524 attribute may be applied to subprograms in Ada 95, but the
4525 intended effect from the Ada 95 reference manual seems to be to provide
4526 an address value which can be used to call the subprogram by means of
4527 an address clause as in the following example:
4529 @smallexample @c ada
4530 procedure K is @dots{}
4533 for L'Address use K'Address;
4534 pragma Import (Ada, L);
4538 A call to @code{L} is then expected to result in a call to @code{K}@.
4539 In Ada 83, where there were no access-to-subprogram values, this was
4540 a common work around for getting the effect of an indirect call.
4541 GNAT implements the above use of @code{Address} and the technique
4542 illustrated by the example code works correctly.
4544 However, for some purposes, it is useful to have the address of the start
4545 of the generated code for the subprogram. On some architectures, this is
4546 not necessarily the same as the @code{Address} value described above.
4547 For example, the @code{Address} value may reference a subprogram
4548 descriptor rather than the subprogram itself.
4550 The @code{'Code_Address} attribute, which can only be applied to
4551 subprogram entities, always returns the address of the start of the
4552 generated code of the specified subprogram, which may or may not be
4553 the same value as is returned by the corresponding @code{'Address}
4556 @node Default_Bit_Order
4557 @unnumberedsec Default_Bit_Order
4559 @cindex Little endian
4560 @findex Default_Bit_Order
4562 @code{Standard'Default_Bit_Order} (@code{Standard} is the only
4563 permissible prefix), provides the value @code{System.Default_Bit_Order}
4564 as a @code{Pos} value (0 for @code{High_Order_First}, 1 for
4565 @code{Low_Order_First}). This is used to construct the definition of
4566 @code{Default_Bit_Order} in package @code{System}.
4569 @unnumberedsec Elaborated
4572 The prefix of the @code{'Elaborated} attribute must be a unit name. The
4573 value is a Boolean which indicates whether or not the given unit has been
4574 elaborated. This attribute is primarily intended for internal use by the
4575 generated code for dynamic elaboration checking, but it can also be used
4576 in user programs. The value will always be True once elaboration of all
4577 units has been completed. An exception is for units which need no
4578 elaboration, the value is always False for such units.
4581 @unnumberedsec Elab_Body
4584 This attribute can only be applied to a program unit name. It returns
4585 the entity for the corresponding elaboration procedure for elaborating
4586 the body of the referenced unit. This is used in the main generated
4587 elaboration procedure by the binder and is not normally used in any
4588 other context. However, there may be specialized situations in which it
4589 is useful to be able to call this elaboration procedure from Ada code,
4590 e.g.@: if it is necessary to do selective re-elaboration to fix some
4594 @unnumberedsec Elab_Spec
4597 This attribute can only be applied to a program unit name. It returns
4598 the entity for the corresponding elaboration procedure for elaborating
4599 the specification of the referenced unit. This is used in the main
4600 generated elaboration procedure by the binder and is not normally used
4601 in any other context. However, there may be specialized situations in
4602 which it is useful to be able to call this elaboration procedure from
4603 Ada code, e.g.@: if it is necessary to do selective re-elaboration to fix
4608 @cindex Ada 83 attributes
4611 The @code{Emax} attribute is provided for compatibility with Ada 83. See
4612 the Ada 83 reference manual for an exact description of the semantics of
4616 @unnumberedsec Enum_Rep
4617 @cindex Representation of enums
4620 For every enumeration subtype @var{S}, @code{@var{S}'Enum_Rep} denotes a
4621 function with the following spec:
4623 @smallexample @c ada
4624 function @var{S}'Enum_Rep (Arg : @var{S}'Base)
4625 return @i{Universal_Integer};
4629 It is also allowable to apply @code{Enum_Rep} directly to an object of an
4630 enumeration type or to a non-overloaded enumeration
4631 literal. In this case @code{@var{S}'Enum_Rep} is equivalent to
4632 @code{@var{typ}'Enum_Rep(@var{S})} where @var{typ} is the type of the
4633 enumeration literal or object.
4635 The function returns the representation value for the given enumeration
4636 value. This will be equal to value of the @code{Pos} attribute in the
4637 absence of an enumeration representation clause. This is a static
4638 attribute (i.e.@: the result is static if the argument is static).
4640 @code{@var{S}'Enum_Rep} can also be used with integer types and objects,
4641 in which case it simply returns the integer value. The reason for this
4642 is to allow it to be used for @code{(<>)} discrete formal arguments in
4643 a generic unit that can be instantiated with either enumeration types
4644 or integer types. Note that if @code{Enum_Rep} is used on a modular
4645 type whose upper bound exceeds the upper bound of the largest signed
4646 integer type, and the argument is a variable, so that the universal
4647 integer calculation is done at run-time, then the call to @code{Enum_Rep}
4648 may raise @code{Constraint_Error}.
4651 @unnumberedsec Epsilon
4652 @cindex Ada 83 attributes
4655 The @code{Epsilon} attribute is provided for compatibility with Ada 83. See
4656 the Ada 83 reference manual for an exact description of the semantics of
4660 @unnumberedsec Fixed_Value
4663 For every fixed-point type @var{S}, @code{@var{S}'Fixed_Value} denotes a
4664 function with the following specification:
4666 @smallexample @c ada
4667 function @var{S}'Fixed_Value (Arg : @i{Universal_Integer})
4672 The value returned is the fixed-point value @var{V} such that
4674 @smallexample @c ada
4675 @var{V} = Arg * @var{S}'Small
4679 The effect is thus similar to first converting the argument to the
4680 integer type used to represent @var{S}, and then doing an unchecked
4681 conversion to the fixed-point type. The difference is
4682 that there are full range checks, to ensure that the result is in range.
4683 This attribute is primarily intended for use in implementation of the
4684 input-output functions for fixed-point values.
4686 @node Has_Access_Values
4687 @unnumberedsec Has_Access_Values
4688 @cindex Access values, testing for
4689 @findex Has_Access_Values
4691 The prefix of the @code{Has_Access_Values} attribute is a type. The result
4692 is a Boolean value which is True if the is an access type, or is a composite
4693 type with a component (at any nesting depth) that is an access type, and is
4695 The intended use of this attribute is in conjunction with generic
4696 definitions. If the attribute is applied to a generic private type, it
4697 indicates whether or not the corresponding actual type has access values.
4699 @node Has_Discriminants
4700 @unnumberedsec Has_Discriminants
4701 @cindex Discriminants, testing for
4702 @findex Has_Discriminants
4704 The prefix of the @code{Has_Discriminants} attribute is a type. The result
4705 is a Boolean value which is True if the type has discriminants, and False
4706 otherwise. The intended use of this attribute is in conjunction with generic
4707 definitions. If the attribute is applied to a generic private type, it
4708 indicates whether or not the corresponding actual type has discriminants.
4714 The @code{Img} attribute differs from @code{Image} in that it may be
4715 applied to objects as well as types, in which case it gives the
4716 @code{Image} for the subtype of the object. This is convenient for
4719 @smallexample @c ada
4720 Put_Line ("X = " & X'Img);
4724 has the same meaning as the more verbose:
4726 @smallexample @c ada
4727 Put_Line ("X = " & @var{T}'Image (X));
4731 where @var{T} is the (sub)type of the object @code{X}.
4734 @unnumberedsec Integer_Value
4735 @findex Integer_Value
4737 For every integer type @var{S}, @code{@var{S}'Integer_Value} denotes a
4738 function with the following spec:
4740 @smallexample @c ada
4741 function @var{S}'Integer_Value (Arg : @i{Universal_Fixed})
4746 The value returned is the integer value @var{V}, such that
4748 @smallexample @c ada
4749 Arg = @var{V} * @var{T}'Small
4753 where @var{T} is the type of @code{Arg}.
4754 The effect is thus similar to first doing an unchecked conversion from
4755 the fixed-point type to its corresponding implementation type, and then
4756 converting the result to the target integer type. The difference is
4757 that there are full range checks, to ensure that the result is in range.
4758 This attribute is primarily intended for use in implementation of the
4759 standard input-output functions for fixed-point values.
4762 @unnumberedsec Large
4763 @cindex Ada 83 attributes
4766 The @code{Large} attribute is provided for compatibility with Ada 83. See
4767 the Ada 83 reference manual for an exact description of the semantics of
4771 @unnumberedsec Machine_Size
4772 @findex Machine_Size
4774 This attribute is identical to the @code{Object_Size} attribute. It is
4775 provided for compatibility with the DEC Ada 83 attribute of this name.
4778 @unnumberedsec Mantissa
4779 @cindex Ada 83 attributes
4782 The @code{Mantissa} attribute is provided for compatibility with Ada 83. See
4783 the Ada 83 reference manual for an exact description of the semantics of
4786 @node Max_Interrupt_Priority
4787 @unnumberedsec Max_Interrupt_Priority
4788 @cindex Interrupt priority, maximum
4789 @findex Max_Interrupt_Priority
4791 @code{Standard'Max_Interrupt_Priority} (@code{Standard} is the only
4792 permissible prefix), provides the same value as
4793 @code{System.Max_Interrupt_Priority}.
4796 @unnumberedsec Max_Priority
4797 @cindex Priority, maximum
4798 @findex Max_Priority
4800 @code{Standard'Max_Priority} (@code{Standard} is the only permissible
4801 prefix) provides the same value as @code{System.Max_Priority}.
4803 @node Maximum_Alignment
4804 @unnumberedsec Maximum_Alignment
4805 @cindex Alignment, maximum
4806 @findex Maximum_Alignment
4808 @code{Standard'Maximum_Alignment} (@code{Standard} is the only
4809 permissible prefix) provides the maximum useful alignment value for the
4810 target. This is a static value that can be used to specify the alignment
4811 for an object, guaranteeing that it is properly aligned in all
4814 @node Mechanism_Code
4815 @unnumberedsec Mechanism_Code
4816 @cindex Return values, passing mechanism
4817 @cindex Parameters, passing mechanism
4818 @findex Mechanism_Code
4820 @code{@var{function}'Mechanism_Code} yields an integer code for the
4821 mechanism used for the result of function, and
4822 @code{@var{subprogram}'Mechanism_Code (@var{n})} yields the mechanism
4823 used for formal parameter number @var{n} (a static integer value with 1
4824 meaning the first parameter) of @var{subprogram}. The code returned is:
4832 by descriptor (default descriptor class)
4834 by descriptor (UBS: unaligned bit string)
4836 by descriptor (UBSB: aligned bit string with arbitrary bounds)
4838 by descriptor (UBA: unaligned bit array)
4840 by descriptor (S: string, also scalar access type parameter)
4842 by descriptor (SB: string with arbitrary bounds)
4844 by descriptor (A: contiguous array)
4846 by descriptor (NCA: non-contiguous array)
4850 Values from 3 through 10 are only relevant to Digital OpenVMS implementations.
4853 @node Null_Parameter
4854 @unnumberedsec Null_Parameter
4855 @cindex Zero address, passing
4856 @findex Null_Parameter
4858 A reference @code{@var{T}'Null_Parameter} denotes an imaginary object of
4859 type or subtype @var{T} allocated at machine address zero. The attribute
4860 is allowed only as the default expression of a formal parameter, or as
4861 an actual expression of a subprogram call. In either case, the
4862 subprogram must be imported.
4864 The identity of the object is represented by the address zero in the
4865 argument list, independent of the passing mechanism (explicit or
4868 This capability is needed to specify that a zero address should be
4869 passed for a record or other composite object passed by reference.
4870 There is no way of indicating this without the @code{Null_Parameter}
4874 @unnumberedsec Object_Size
4875 @cindex Size, used for objects
4878 The size of an object is not necessarily the same as the size of the type
4879 of an object. This is because by default object sizes are increased to be
4880 a multiple of the alignment of the object. For example,
4881 @code{Natural'Size} is
4882 31, but by default objects of type @code{Natural} will have a size of 32 bits.
4883 Similarly, a record containing an integer and a character:
4885 @smallexample @c ada
4893 will have a size of 40 (that is @code{Rec'Size} will be 40. The
4894 alignment will be 4, because of the
4895 integer field, and so the default size of record objects for this type
4896 will be 64 (8 bytes).
4898 The @code{@var{type}'Object_Size} attribute
4899 has been added to GNAT to allow the
4900 default object size of a type to be easily determined. For example,
4901 @code{Natural'Object_Size} is 32, and
4902 @code{Rec'Object_Size} (for the record type in the above example) will be
4903 64. Note also that, unlike the situation with the
4904 @code{Size} attribute as defined in the Ada RM, the
4905 @code{Object_Size} attribute can be specified individually
4906 for different subtypes. For example:
4908 @smallexample @c ada
4909 type R is new Integer;
4910 subtype R1 is R range 1 .. 10;
4911 subtype R2 is R range 1 .. 10;
4912 for R2'Object_Size use 8;
4916 In this example, @code{R'Object_Size} and @code{R1'Object_Size} are both
4917 32 since the default object size for a subtype is the same as the object size
4918 for the parent subtype. This means that objects of type @code{R}
4920 by default be 32 bits (four bytes). But objects of type
4921 @code{R2} will be only
4922 8 bits (one byte), since @code{R2'Object_Size} has been set to 8.
4924 @node Passed_By_Reference
4925 @unnumberedsec Passed_By_Reference
4926 @cindex Parameters, when passed by reference
4927 @findex Passed_By_Reference
4929 @code{@var{type}'Passed_By_Reference} for any subtype @var{type} returns
4930 a value of type @code{Boolean} value that is @code{True} if the type is
4931 normally passed by reference and @code{False} if the type is normally
4932 passed by copy in calls. For scalar types, the result is always @code{False}
4933 and is static. For non-scalar types, the result is non-static.
4936 @unnumberedsec Range_Length
4937 @findex Range_Length
4939 @code{@var{type}'Range_Length} for any discrete type @var{type} yields
4940 the number of values represented by the subtype (zero for a null
4941 range). The result is static for static subtypes. @code{Range_Length}
4942 applied to the index subtype of a one dimensional array always gives the
4943 same result as @code{Range} applied to the array itself.
4946 @unnumberedsec Safe_Emax
4947 @cindex Ada 83 attributes
4950 The @code{Safe_Emax} attribute is provided for compatibility with Ada 83. See
4951 the Ada 83 reference manual for an exact description of the semantics of
4955 @unnumberedsec Safe_Large
4956 @cindex Ada 83 attributes
4959 The @code{Safe_Large} attribute is provided for compatibility with Ada 83. See
4960 the Ada 83 reference manual for an exact description of the semantics of
4964 @unnumberedsec Small
4965 @cindex Ada 83 attributes
4968 The @code{Small} attribute is defined in Ada 95 only for fixed-point types.
4969 GNAT also allows this attribute to be applied to floating-point types
4970 for compatibility with Ada 83. See
4971 the Ada 83 reference manual for an exact description of the semantics of
4972 this attribute when applied to floating-point types.
4975 @unnumberedsec Storage_Unit
4976 @findex Storage_Unit
4978 @code{Standard'Storage_Unit} (@code{Standard} is the only permissible
4979 prefix) provides the same value as @code{System.Storage_Unit}.
4982 @unnumberedsec Target_Name
4985 @code{Standard'Target_Name} (@code{Standard} is the only permissible
4986 prefix) provides a static string value that identifies the target
4987 for the current compilation. For GCC implementations, this is the
4988 standard gcc target name without the terminating slash (for
4989 example, GNAT 5.0 on windows yields "i586-pc-mingw32msv").
4995 @code{Standard'Tick} (@code{Standard} is the only permissible prefix)
4996 provides the same value as @code{System.Tick},
4999 @unnumberedsec To_Address
5002 The @code{System'To_Address}
5003 (@code{System} is the only permissible prefix)
5004 denotes a function identical to
5005 @code{System.Storage_Elements.To_Address} except that
5006 it is a static attribute. This means that if its argument is
5007 a static expression, then the result of the attribute is a
5008 static expression. The result is that such an expression can be
5009 used in contexts (e.g.@: preelaborable packages) which require a
5010 static expression and where the function call could not be used
5011 (since the function call is always non-static, even if its
5012 argument is static).
5015 @unnumberedsec Type_Class
5018 @code{@var{type}'Type_Class} for any type or subtype @var{type} yields
5019 the value of the type class for the full type of @var{type}. If
5020 @var{type} is a generic formal type, the value is the value for the
5021 corresponding actual subtype. The value of this attribute is of type
5022 @code{System.Aux_DEC.Type_Class}, which has the following definition:
5024 @smallexample @c ada
5026 (Type_Class_Enumeration,
5028 Type_Class_Fixed_Point,
5029 Type_Class_Floating_Point,
5034 Type_Class_Address);
5038 Protected types yield the value @code{Type_Class_Task}, which thus
5039 applies to all concurrent types. This attribute is designed to
5040 be compatible with the DEC Ada 83 attribute of the same name.
5043 @unnumberedsec UET_Address
5046 The @code{UET_Address} attribute can only be used for a prefix which
5047 denotes a library package. It yields the address of the unit exception
5048 table when zero cost exception handling is used. This attribute is
5049 intended only for use within the GNAT implementation. See the unit
5050 @code{Ada.Exceptions} in files @file{a-except.ads} and @file{a-except.adb}
5051 for details on how this attribute is used in the implementation.
5053 @node Unconstrained_Array
5054 @unnumberedsec Unconstrained_Array
5055 @findex Unconstrained_Array
5057 The @code{Unconstrained_Array} attribute can be used with a prefix that
5058 denotes any type or subtype. It is a static attribute that yields
5059 @code{True} if the prefix designates an unconstrained array,
5060 and @code{False} otherwise. In a generic instance, the result is
5061 still static, and yields the result of applying this test to the
5064 @node Universal_Literal_String
5065 @unnumberedsec Universal_Literal_String
5066 @cindex Named numbers, representation of
5067 @findex Universal_Literal_String
5069 The prefix of @code{Universal_Literal_String} must be a named
5070 number. The static result is the string consisting of the characters of
5071 the number as defined in the original source. This allows the user
5072 program to access the actual text of named numbers without intermediate
5073 conversions and without the need to enclose the strings in quotes (which
5074 would preclude their use as numbers). This is used internally for the
5075 construction of values of the floating-point attributes from the file
5076 @file{ttypef.ads}, but may also be used by user programs.
5078 @node Unrestricted_Access
5079 @unnumberedsec Unrestricted_Access
5080 @cindex @code{Access}, unrestricted
5081 @findex Unrestricted_Access
5083 The @code{Unrestricted_Access} attribute is similar to @code{Access}
5084 except that all accessibility and aliased view checks are omitted. This
5085 is a user-beware attribute. It is similar to
5086 @code{Address}, for which it is a desirable replacement where the value
5087 desired is an access type. In other words, its effect is identical to
5088 first applying the @code{Address} attribute and then doing an unchecked
5089 conversion to a desired access type. In GNAT, but not necessarily in
5090 other implementations, the use of static chains for inner level
5091 subprograms means that @code{Unrestricted_Access} applied to a
5092 subprogram yields a value that can be called as long as the subprogram
5093 is in scope (normal Ada 95 accessibility rules restrict this usage).
5095 It is possible to use @code{Unrestricted_Access} for any type, but care
5096 must be exercised if it is used to create pointers to unconstrained
5097 objects. In this case, the resulting pointer has the same scope as the
5098 context of the attribute, and may not be returned to some enclosing
5099 scope. For instance, a function cannot use @code{Unrestricted_Access}
5100 to create a unconstrained pointer and then return that value to the
5104 @unnumberedsec VADS_Size
5105 @cindex @code{Size}, VADS compatibility
5108 The @code{'VADS_Size} attribute is intended to make it easier to port
5109 legacy code which relies on the semantics of @code{'Size} as implemented
5110 by the VADS Ada 83 compiler. GNAT makes a best effort at duplicating the
5111 same semantic interpretation. In particular, @code{'VADS_Size} applied
5112 to a predefined or other primitive type with no Size clause yields the
5113 Object_Size (for example, @code{Natural'Size} is 32 rather than 31 on
5114 typical machines). In addition @code{'VADS_Size} applied to an object
5115 gives the result that would be obtained by applying the attribute to
5116 the corresponding type.
5119 @unnumberedsec Value_Size
5120 @cindex @code{Size}, setting for not-first subtype
5122 @code{@var{type}'Value_Size} is the number of bits required to represent
5123 a value of the given subtype. It is the same as @code{@var{type}'Size},
5124 but, unlike @code{Size}, may be set for non-first subtypes.
5127 @unnumberedsec Wchar_T_Size
5128 @findex Wchar_T_Size
5129 @code{Standard'Wchar_T_Size} (@code{Standard} is the only permissible
5130 prefix) provides the size in bits of the C @code{wchar_t} type
5131 primarily for constructing the definition of this type in
5132 package @code{Interfaces.C}.
5135 @unnumberedsec Word_Size
5137 @code{Standard'Word_Size} (@code{Standard} is the only permissible
5138 prefix) provides the value @code{System.Word_Size}.
5140 @c ------------------------
5141 @node Implementation Advice
5142 @chapter Implementation Advice
5144 The main text of the Ada 95 Reference Manual describes the required
5145 behavior of all Ada 95 compilers, and the GNAT compiler conforms to
5148 In addition, there are sections throughout the Ada 95
5149 reference manual headed
5150 by the phrase ``implementation advice''. These sections are not normative,
5151 i.e.@: they do not specify requirements that all compilers must
5152 follow. Rather they provide advice on generally desirable behavior. You
5153 may wonder why they are not requirements. The most typical answer is
5154 that they describe behavior that seems generally desirable, but cannot
5155 be provided on all systems, or which may be undesirable on some systems.
5157 As far as practical, GNAT follows the implementation advice sections in
5158 the Ada 95 Reference Manual. This chapter contains a table giving the
5159 reference manual section number, paragraph number and several keywords
5160 for each advice. Each entry consists of the text of the advice followed
5161 by the GNAT interpretation of this advice. Most often, this simply says
5162 ``followed'', which means that GNAT follows the advice. However, in a
5163 number of cases, GNAT deliberately deviates from this advice, in which
5164 case the text describes what GNAT does and why.
5166 @cindex Error detection
5167 @unnumberedsec 1.1.3(20): Error Detection
5170 If an implementation detects the use of an unsupported Specialized Needs
5171 Annex feature at run time, it should raise @code{Program_Error} if
5174 Not relevant. All specialized needs annex features are either supported,
5175 or diagnosed at compile time.
5178 @unnumberedsec 1.1.3(31): Child Units
5181 If an implementation wishes to provide implementation-defined
5182 extensions to the functionality of a language-defined library unit, it
5183 should normally do so by adding children to the library unit.
5187 @cindex Bounded errors
5188 @unnumberedsec 1.1.5(12): Bounded Errors
5191 If an implementation detects a bounded error or erroneous
5192 execution, it should raise @code{Program_Error}.
5194 Followed in all cases in which the implementation detects a bounded
5195 error or erroneous execution. Not all such situations are detected at
5199 @unnumberedsec 2.8(16): Pragmas
5202 Normally, implementation-defined pragmas should have no semantic effect
5203 for error-free programs; that is, if the implementation-defined pragmas
5204 are removed from a working program, the program should still be legal,
5205 and should still have the same semantics.
5207 The following implementation defined pragmas are exceptions to this
5219 @item CPP_Constructor
5227 @item Interface_Name
5229 @item Machine_Attribute
5231 @item Unimplemented_Unit
5233 @item Unchecked_Union
5238 In each of the above cases, it is essential to the purpose of the pragma
5239 that this advice not be followed. For details see the separate section
5240 on implementation defined pragmas.
5242 @unnumberedsec 2.8(17-19): Pragmas
5245 Normally, an implementation should not define pragmas that can
5246 make an illegal program legal, except as follows:
5250 A pragma used to complete a declaration, such as a pragma @code{Import};
5254 A pragma used to configure the environment by adding, removing, or
5255 replacing @code{library_items}.
5257 See response to paragraph 16 of this same section.
5259 @cindex Character Sets
5260 @cindex Alternative Character Sets
5261 @unnumberedsec 3.5.2(5): Alternative Character Sets
5264 If an implementation supports a mode with alternative interpretations
5265 for @code{Character} and @code{Wide_Character}, the set of graphic
5266 characters of @code{Character} should nevertheless remain a proper
5267 subset of the set of graphic characters of @code{Wide_Character}. Any
5268 character set ``localizations'' should be reflected in the results of
5269 the subprograms defined in the language-defined package
5270 @code{Characters.Handling} (see A.3) available in such a mode. In a mode with
5271 an alternative interpretation of @code{Character}, the implementation should
5272 also support a corresponding change in what is a legal
5273 @code{identifier_letter}.
5275 Not all wide character modes follow this advice, in particular the JIS
5276 and IEC modes reflect standard usage in Japan, and in these encoding,
5277 the upper half of the Latin-1 set is not part of the wide-character
5278 subset, since the most significant bit is used for wide character
5279 encoding. However, this only applies to the external forms. Internally
5280 there is no such restriction.
5282 @cindex Integer types
5283 @unnumberedsec 3.5.4(28): Integer Types
5287 An implementation should support @code{Long_Integer} in addition to
5288 @code{Integer} if the target machine supports 32-bit (or longer)
5289 arithmetic. No other named integer subtypes are recommended for package
5290 @code{Standard}. Instead, appropriate named integer subtypes should be
5291 provided in the library package @code{Interfaces} (see B.2).
5293 @code{Long_Integer} is supported. Other standard integer types are supported
5294 so this advice is not fully followed. These types
5295 are supported for convenient interface to C, and so that all hardware
5296 types of the machine are easily available.
5297 @unnumberedsec 3.5.4(29): Integer Types
5301 An implementation for a two's complement machine should support
5302 modular types with a binary modulus up to @code{System.Max_Int*2+2}. An
5303 implementation should support a non-binary modules up to @code{Integer'Last}.
5307 @cindex Enumeration values
5308 @unnumberedsec 3.5.5(8): Enumeration Values
5311 For the evaluation of a call on @code{@var{S}'Pos} for an enumeration
5312 subtype, if the value of the operand does not correspond to the internal
5313 code for any enumeration literal of its type (perhaps due to an
5314 un-initialized variable), then the implementation should raise
5315 @code{Program_Error}. This is particularly important for enumeration
5316 types with noncontiguous internal codes specified by an
5317 enumeration_representation_clause.
5322 @unnumberedsec 3.5.7(17): Float Types
5325 An implementation should support @code{Long_Float} in addition to
5326 @code{Float} if the target machine supports 11 or more digits of
5327 precision. No other named floating point subtypes are recommended for
5328 package @code{Standard}. Instead, appropriate named floating point subtypes
5329 should be provided in the library package @code{Interfaces} (see B.2).
5331 @code{Short_Float} and @code{Long_Long_Float} are also provided. The
5332 former provides improved compatibility with other implementations
5333 supporting this type. The latter corresponds to the highest precision
5334 floating-point type supported by the hardware. On most machines, this
5335 will be the same as @code{Long_Float}, but on some machines, it will
5336 correspond to the IEEE extended form. The notable case is all ia32
5337 (x86) implementations, where @code{Long_Long_Float} corresponds to
5338 the 80-bit extended precision format supported in hardware on this
5339 processor. Note that the 128-bit format on SPARC is not supported,
5340 since this is a software rather than a hardware format.
5342 @cindex Multidimensional arrays
5343 @cindex Arrays, multidimensional
5344 @unnumberedsec 3.6.2(11): Multidimensional Arrays
5347 An implementation should normally represent multidimensional arrays in
5348 row-major order, consistent with the notation used for multidimensional
5349 array aggregates (see 4.3.3). However, if a pragma @code{Convention}
5350 (@code{Fortran}, @dots{}) applies to a multidimensional array type, then
5351 column-major order should be used instead (see B.5, ``Interfacing with
5356 @findex Duration'Small
5357 @unnumberedsec 9.6(30-31): Duration'Small
5360 Whenever possible in an implementation, the value of @code{Duration'Small}
5361 should be no greater than 100 microseconds.
5363 Followed. (@code{Duration'Small} = 10**(@minus{}9)).
5367 The time base for @code{delay_relative_statements} should be monotonic;
5368 it need not be the same time base as used for @code{Calendar.Clock}.
5372 @unnumberedsec 10.2.1(12): Consistent Representation
5375 In an implementation, a type declared in a pre-elaborated package should
5376 have the same representation in every elaboration of a given version of
5377 the package, whether the elaborations occur in distinct executions of
5378 the same program, or in executions of distinct programs or partitions
5379 that include the given version.
5381 Followed, except in the case of tagged types. Tagged types involve
5382 implicit pointers to a local copy of a dispatch table, and these pointers
5383 have representations which thus depend on a particular elaboration of the
5384 package. It is not easy to see how it would be possible to follow this
5385 advice without severely impacting efficiency of execution.
5387 @cindex Exception information
5388 @unnumberedsec 11.4.1(19): Exception Information
5391 @code{Exception_Message} by default and @code{Exception_Information}
5392 should produce information useful for
5393 debugging. @code{Exception_Message} should be short, about one
5394 line. @code{Exception_Information} can be long. @code{Exception_Message}
5395 should not include the
5396 @code{Exception_Name}. @code{Exception_Information} should include both
5397 the @code{Exception_Name} and the @code{Exception_Message}.
5399 Followed. For each exception that doesn't have a specified
5400 @code{Exception_Message}, the compiler generates one containing the location
5401 of the raise statement. This location has the form ``file:line'', where
5402 file is the short file name (without path information) and line is the line
5403 number in the file. Note that in the case of the Zero Cost Exception
5404 mechanism, these messages become redundant with the Exception_Information that
5405 contains a full backtrace of the calling sequence, so they are disabled.
5406 To disable explicitly the generation of the source location message, use the
5407 Pragma @code{Discard_Names}.
5409 @cindex Suppression of checks
5410 @cindex Checks, suppression of
5411 @unnumberedsec 11.5(28): Suppression of Checks
5414 The implementation should minimize the code executed for checks that
5415 have been suppressed.
5419 @cindex Representation clauses
5420 @unnumberedsec 13.1 (21-24): Representation Clauses
5423 The recommended level of support for all representation items is
5424 qualified as follows:
5428 An implementation need not support representation items containing
5429 non-static expressions, except that an implementation should support a
5430 representation item for a given entity if each non-static expression in
5431 the representation item is a name that statically denotes a constant
5432 declared before the entity.
5434 Followed. In fact, GNAT goes beyond the recommended level of support
5435 by allowing nonstatic expressions in some representation clauses even
5436 without the need to declare constants initialized with the values of
5440 @smallexample @c ada
5443 for Y'Address use X'Address;>>
5449 An implementation need not support a specification for the @code{Size}
5450 for a given composite subtype, nor the size or storage place for an
5451 object (including a component) of a given composite subtype, unless the
5452 constraints on the subtype and its composite subcomponents (if any) are
5453 all static constraints.
5455 Followed. Size Clauses are not permitted on non-static components, as
5460 An aliased component, or a component whose type is by-reference, should
5461 always be allocated at an addressable location.
5465 @cindex Packed types
5466 @unnumberedsec 13.2(6-8): Packed Types
5469 If a type is packed, then the implementation should try to minimize
5470 storage allocated to objects of the type, possibly at the expense of
5471 speed of accessing components, subject to reasonable complexity in
5472 addressing calculations.
5476 The recommended level of support pragma @code{Pack} is:
5478 For a packed record type, the components should be packed as tightly as
5479 possible subject to the Sizes of the component subtypes, and subject to
5480 any @code{record_representation_clause} that applies to the type; the
5481 implementation may, but need not, reorder components or cross aligned
5482 word boundaries to improve the packing. A component whose @code{Size} is
5483 greater than the word size may be allocated an integral number of words.
5485 Followed. Tight packing of arrays is supported for all component sizes
5486 up to 64-bits. If the array component size is 1 (that is to say, if
5487 the component is a boolean type or an enumeration type with two values)
5488 then values of the type are implicitly initialized to zero. This
5489 happens both for objects of the packed type, and for objects that have a
5490 subcomponent of the packed type.
5494 An implementation should support Address clauses for imported
5498 @cindex @code{Address} clauses
5499 @unnumberedsec 13.3(14-19): Address Clauses
5503 For an array @var{X}, @code{@var{X}'Address} should point at the first
5504 component of the array, and not at the array bounds.
5510 The recommended level of support for the @code{Address} attribute is:
5512 @code{@var{X}'Address} should produce a useful result if @var{X} is an
5513 object that is aliased or of a by-reference type, or is an entity whose
5514 @code{Address} has been specified.
5516 Followed. A valid address will be produced even if none of those
5517 conditions have been met. If necessary, the object is forced into
5518 memory to ensure the address is valid.
5522 An implementation should support @code{Address} clauses for imported
5529 Objects (including subcomponents) that are aliased or of a by-reference
5530 type should be allocated on storage element boundaries.
5536 If the @code{Address} of an object is specified, or it is imported or exported,
5537 then the implementation should not perform optimizations based on
5538 assumptions of no aliases.
5542 @cindex @code{Alignment} clauses
5543 @unnumberedsec 13.3(29-35): Alignment Clauses
5546 The recommended level of support for the @code{Alignment} attribute for
5549 An implementation should support specified Alignments that are factors
5550 and multiples of the number of storage elements per word, subject to the
5557 An implementation need not support specified @code{Alignment}s for
5558 combinations of @code{Size}s and @code{Alignment}s that cannot be easily
5559 loaded and stored by available machine instructions.
5565 An implementation need not support specified @code{Alignment}s that are
5566 greater than the maximum @code{Alignment} the implementation ever returns by
5573 The recommended level of support for the @code{Alignment} attribute for
5576 Same as above, for subtypes, but in addition:
5582 For stand-alone library-level objects of statically constrained
5583 subtypes, the implementation should support all @code{Alignment}s
5584 supported by the target linker. For example, page alignment is likely to
5585 be supported for such objects, but not for subtypes.
5589 @cindex @code{Size} clauses
5590 @unnumberedsec 13.3(42-43): Size Clauses
5593 The recommended level of support for the @code{Size} attribute of
5596 A @code{Size} clause should be supported for an object if the specified
5597 @code{Size} is at least as large as its subtype's @code{Size}, and
5598 corresponds to a size in storage elements that is a multiple of the
5599 object's @code{Alignment} (if the @code{Alignment} is nonzero).
5603 @unnumberedsec 13.3(50-56): Size Clauses
5606 If the @code{Size} of a subtype is specified, and allows for efficient
5607 independent addressability (see 9.10) on the target architecture, then
5608 the @code{Size} of the following objects of the subtype should equal the
5609 @code{Size} of the subtype:
5611 Aliased objects (including components).
5617 @code{Size} clause on a composite subtype should not affect the
5618 internal layout of components.
5624 The recommended level of support for the @code{Size} attribute of subtypes is:
5628 The @code{Size} (if not specified) of a static discrete or fixed point
5629 subtype should be the number of bits needed to represent each value
5630 belonging to the subtype using an unbiased representation, leaving space
5631 for a sign bit only if the subtype contains negative values. If such a
5632 subtype is a first subtype, then an implementation should support a
5633 specified @code{Size} for it that reflects this representation.
5639 For a subtype implemented with levels of indirection, the @code{Size}
5640 should include the size of the pointers, but not the size of what they
5645 @cindex @code{Component_Size} clauses
5646 @unnumberedsec 13.3(71-73): Component Size Clauses
5649 The recommended level of support for the @code{Component_Size}
5654 An implementation need not support specified @code{Component_Sizes} that are
5655 less than the @code{Size} of the component subtype.
5661 An implementation should support specified @code{Component_Size}s that
5662 are factors and multiples of the word size. For such
5663 @code{Component_Size}s, the array should contain no gaps between
5664 components. For other @code{Component_Size}s (if supported), the array
5665 should contain no gaps between components when packing is also
5666 specified; the implementation should forbid this combination in cases
5667 where it cannot support a no-gaps representation.
5671 @cindex Enumeration representation clauses
5672 @cindex Representation clauses, enumeration
5673 @unnumberedsec 13.4(9-10): Enumeration Representation Clauses
5676 The recommended level of support for enumeration representation clauses
5679 An implementation need not support enumeration representation clauses
5680 for boolean types, but should at minimum support the internal codes in
5681 the range @code{System.Min_Int.System.Max_Int}.
5685 @cindex Record representation clauses
5686 @cindex Representation clauses, records
5687 @unnumberedsec 13.5.1(17-22): Record Representation Clauses
5690 The recommended level of support for
5691 @*@code{record_representation_clauses} is:
5693 An implementation should support storage places that can be extracted
5694 with a load, mask, shift sequence of machine code, and set with a load,
5695 shift, mask, store sequence, given the available machine instructions
5702 A storage place should be supported if its size is equal to the
5703 @code{Size} of the component subtype, and it starts and ends on a
5704 boundary that obeys the @code{Alignment} of the component subtype.
5710 If the default bit ordering applies to the declaration of a given type,
5711 then for a component whose subtype's @code{Size} is less than the word
5712 size, any storage place that does not cross an aligned word boundary
5713 should be supported.
5719 An implementation may reserve a storage place for the tag field of a
5720 tagged type, and disallow other components from overlapping that place.
5722 Followed. The storage place for the tag field is the beginning of the tagged
5723 record, and its size is Address'Size. GNAT will reject an explicit component
5724 clause for the tag field.
5728 An implementation need not support a @code{component_clause} for a
5729 component of an extension part if the storage place is not after the
5730 storage places of all components of the parent type, whether or not
5731 those storage places had been specified.
5733 Followed. The above advice on record representation clauses is followed,
5734 and all mentioned features are implemented.
5736 @cindex Storage place attributes
5737 @unnumberedsec 13.5.2(5): Storage Place Attributes
5740 If a component is represented using some form of pointer (such as an
5741 offset) to the actual data of the component, and this data is contiguous
5742 with the rest of the object, then the storage place attributes should
5743 reflect the place of the actual data, not the pointer. If a component is
5744 allocated discontinuously from the rest of the object, then a warning
5745 should be generated upon reference to one of its storage place
5748 Followed. There are no such components in GNAT@.
5750 @cindex Bit ordering
5751 @unnumberedsec 13.5.3(7-8): Bit Ordering
5754 The recommended level of support for the non-default bit ordering is:
5758 If @code{Word_Size} = @code{Storage_Unit}, then the implementation
5759 should support the non-default bit ordering in addition to the default
5762 Followed. Word size does not equal storage size in this implementation.
5763 Thus non-default bit ordering is not supported.
5765 @cindex @code{Address}, as private type
5766 @unnumberedsec 13.7(37): Address as Private
5769 @code{Address} should be of a private type.
5773 @cindex Operations, on @code{Address}
5774 @cindex @code{Address}, operations of
5775 @unnumberedsec 13.7.1(16): Address Operations
5778 Operations in @code{System} and its children should reflect the target
5779 environment semantics as closely as is reasonable. For example, on most
5780 machines, it makes sense for address arithmetic to ``wrap around''.
5781 Operations that do not make sense should raise @code{Program_Error}.
5783 Followed. Address arithmetic is modular arithmetic that wraps around. No
5784 operation raises @code{Program_Error}, since all operations make sense.
5786 @cindex Unchecked conversion
5787 @unnumberedsec 13.9(14-17): Unchecked Conversion
5790 The @code{Size} of an array object should not include its bounds; hence,
5791 the bounds should not be part of the converted data.
5797 The implementation should not generate unnecessary run-time checks to
5798 ensure that the representation of @var{S} is a representation of the
5799 target type. It should take advantage of the permission to return by
5800 reference when possible. Restrictions on unchecked conversions should be
5801 avoided unless required by the target environment.
5803 Followed. There are no restrictions on unchecked conversion. A warning is
5804 generated if the source and target types do not have the same size since
5805 the semantics in this case may be target dependent.
5809 The recommended level of support for unchecked conversions is:
5813 Unchecked conversions should be supported and should be reversible in
5814 the cases where this clause defines the result. To enable meaningful use
5815 of unchecked conversion, a contiguous representation should be used for
5816 elementary subtypes, for statically constrained array subtypes whose
5817 component subtype is one of the subtypes described in this paragraph,
5818 and for record subtypes without discriminants whose component subtypes
5819 are described in this paragraph.
5823 @cindex Heap usage, implicit
5824 @unnumberedsec 13.11(23-25): Implicit Heap Usage
5827 An implementation should document any cases in which it dynamically
5828 allocates heap storage for a purpose other than the evaluation of an
5831 Followed, the only other points at which heap storage is dynamically
5832 allocated are as follows:
5836 At initial elaboration time, to allocate dynamically sized global
5840 To allocate space for a task when a task is created.
5843 To extend the secondary stack dynamically when needed. The secondary
5844 stack is used for returning variable length results.
5849 A default (implementation-provided) storage pool for an
5850 access-to-constant type should not have overhead to support deallocation of
5857 A storage pool for an anonymous access type should be created at the
5858 point of an allocator for the type, and be reclaimed when the designated
5859 object becomes inaccessible.
5863 @cindex Unchecked deallocation
5864 @unnumberedsec 13.11.2(17): Unchecked De-allocation
5867 For a standard storage pool, @code{Free} should actually reclaim the
5872 @cindex Stream oriented attributes
5873 @unnumberedsec 13.13.2(17): Stream Oriented Attributes
5876 If a stream element is the same size as a storage element, then the
5877 normal in-memory representation should be used by @code{Read} and
5878 @code{Write} for scalar objects. Otherwise, @code{Read} and @code{Write}
5879 should use the smallest number of stream elements needed to represent
5880 all values in the base range of the scalar type.
5883 Followed. By default, GNAT uses the interpretation suggested by AI-195,
5884 which specifies using the size of the first subtype.
5885 However, such an implementation is based on direct binary
5886 representations and is therefore target- and endianness-dependent.
5887 To address this issue, GNAT also supplies an alternate implementation
5888 of the stream attributes @code{Read} and @code{Write},
5889 which uses the target-independent XDR standard representation
5891 @cindex XDR representation
5892 @cindex @code{Read} attribute
5893 @cindex @code{Write} attribute
5894 @cindex Stream oriented attributes
5895 The XDR implementation is provided as an alternative body of the
5896 @code{System.Stream_Attributes} package, in the file
5897 @file{s-strxdr.adb} in the GNAT library.
5898 There is no @file{s-strxdr.ads} file.
5899 In order to install the XDR implementation, do the following:
5901 @item Replace the default implementation of the
5902 @code{System.Stream_Attributes} package with the XDR implementation.
5903 For example on a Unix platform issue the commands:
5905 $ mv s-stratt.adb s-strold.adb
5906 $ mv s-strxdr.adb s-stratt.adb
5910 Rebuild the GNAT run-time library as documented in the
5911 @cite{GNAT User's Guide}
5914 @unnumberedsec A.1(52): Names of Predefined Numeric Types
5917 If an implementation provides additional named predefined integer types,
5918 then the names should end with @samp{Integer} as in
5919 @samp{Long_Integer}. If an implementation provides additional named
5920 predefined floating point types, then the names should end with
5921 @samp{Float} as in @samp{Long_Float}.
5925 @findex Ada.Characters.Handling
5926 @unnumberedsec A.3.2(49): @code{Ada.Characters.Handling}
5929 If an implementation provides a localized definition of @code{Character}
5930 or @code{Wide_Character}, then the effects of the subprograms in
5931 @code{Characters.Handling} should reflect the localizations. See also
5934 Followed. GNAT provides no such localized definitions.
5936 @cindex Bounded-length strings
5937 @unnumberedsec A.4.4(106): Bounded-Length String Handling
5940 Bounded string objects should not be implemented by implicit pointers
5941 and dynamic allocation.
5943 Followed. No implicit pointers or dynamic allocation are used.
5945 @cindex Random number generation
5946 @unnumberedsec A.5.2(46-47): Random Number Generation
5949 Any storage associated with an object of type @code{Generator} should be
5950 reclaimed on exit from the scope of the object.
5956 If the generator period is sufficiently long in relation to the number
5957 of distinct initiator values, then each possible value of
5958 @code{Initiator} passed to @code{Reset} should initiate a sequence of
5959 random numbers that does not, in a practical sense, overlap the sequence
5960 initiated by any other value. If this is not possible, then the mapping
5961 between initiator values and generator states should be a rapidly
5962 varying function of the initiator value.
5964 Followed. The generator period is sufficiently long for the first
5965 condition here to hold true.
5967 @findex Get_Immediate
5968 @unnumberedsec A.10.7(23): @code{Get_Immediate}
5971 The @code{Get_Immediate} procedures should be implemented with
5972 unbuffered input. For a device such as a keyboard, input should be
5973 @dfn{available} if a key has already been typed, whereas for a disk
5974 file, input should always be available except at end of file. For a file
5975 associated with a keyboard-like device, any line-editing features of the
5976 underlying operating system should be disabled during the execution of
5977 @code{Get_Immediate}.
5979 Followed on all targets except VxWorks. For VxWorks, there is no way to
5980 provide this functionality that does not result in the input buffer being
5981 flushed before the @code{Get_Immediate} call. A special unit
5982 @code{Interfaces.Vxworks.IO} is provided that contains routines to enable
5986 @unnumberedsec B.1(39-41): Pragma @code{Export}
5989 If an implementation supports pragma @code{Export} to a given language,
5990 then it should also allow the main subprogram to be written in that
5991 language. It should support some mechanism for invoking the elaboration
5992 of the Ada library units included in the system, and for invoking the
5993 finalization of the environment task. On typical systems, the
5994 recommended mechanism is to provide two subprograms whose link names are
5995 @code{adainit} and @code{adafinal}. @code{adainit} should contain the
5996 elaboration code for library units. @code{adafinal} should contain the
5997 finalization code. These subprograms should have no effect the second
5998 and subsequent time they are called.
6004 Automatic elaboration of pre-elaborated packages should be
6005 provided when pragma @code{Export} is supported.
6007 Followed when the main program is in Ada. If the main program is in a
6008 foreign language, then
6009 @code{adainit} must be called to elaborate pre-elaborated
6014 For each supported convention @var{L} other than @code{Intrinsic}, an
6015 implementation should support @code{Import} and @code{Export} pragmas
6016 for objects of @var{L}-compatible types and for subprograms, and pragma
6017 @code{Convention} for @var{L}-eligible types and for subprograms,
6018 presuming the other language has corresponding features. Pragma
6019 @code{Convention} need not be supported for scalar types.
6023 @cindex Package @code{Interfaces}
6025 @unnumberedsec B.2(12-13): Package @code{Interfaces}
6028 For each implementation-defined convention identifier, there should be a
6029 child package of package Interfaces with the corresponding name. This
6030 package should contain any declarations that would be useful for
6031 interfacing to the language (implementation) represented by the
6032 convention. Any declarations useful for interfacing to any language on
6033 the given hardware architecture should be provided directly in
6036 Followed. An additional package not defined
6037 in the Ada 95 Reference Manual is @code{Interfaces.CPP}, used
6038 for interfacing to C++.
6042 An implementation supporting an interface to C, COBOL, or Fortran should
6043 provide the corresponding package or packages described in the following
6046 Followed. GNAT provides all the packages described in this section.
6048 @cindex C, interfacing with
6049 @unnumberedsec B.3(63-71): Interfacing with C
6052 An implementation should support the following interface correspondences
6059 An Ada procedure corresponds to a void-returning C function.
6065 An Ada function corresponds to a non-void C function.
6071 An Ada @code{in} scalar parameter is passed as a scalar argument to a C
6078 An Ada @code{in} parameter of an access-to-object type with designated
6079 type @var{T} is passed as a @code{@var{t}*} argument to a C function,
6080 where @var{t} is the C type corresponding to the Ada type @var{T}.
6086 An Ada access @var{T} parameter, or an Ada @code{out} or @code{in out}
6087 parameter of an elementary type @var{T}, is passed as a @code{@var{t}*}
6088 argument to a C function, where @var{t} is the C type corresponding to
6089 the Ada type @var{T}. In the case of an elementary @code{out} or
6090 @code{in out} parameter, a pointer to a temporary copy is used to
6091 preserve by-copy semantics.
6097 An Ada parameter of a record type @var{T}, of any mode, is passed as a
6098 @code{@var{t}*} argument to a C function, where @var{t} is the C
6099 structure corresponding to the Ada type @var{T}.
6101 Followed. This convention may be overridden by the use of the C_Pass_By_Copy
6102 pragma, or Convention, or by explicitly specifying the mechanism for a given
6103 call using an extended import or export pragma.
6107 An Ada parameter of an array type with component type @var{T}, of any
6108 mode, is passed as a @code{@var{t}*} argument to a C function, where
6109 @var{t} is the C type corresponding to the Ada type @var{T}.
6115 An Ada parameter of an access-to-subprogram type is passed as a pointer
6116 to a C function whose prototype corresponds to the designated
6117 subprogram's specification.
6121 @cindex COBOL, interfacing with
6122 @unnumberedsec B.4(95-98): Interfacing with COBOL
6125 An Ada implementation should support the following interface
6126 correspondences between Ada and COBOL@.
6132 An Ada access @var{T} parameter is passed as a @samp{BY REFERENCE} data item of
6133 the COBOL type corresponding to @var{T}.
6139 An Ada in scalar parameter is passed as a @samp{BY CONTENT} data item of
6140 the corresponding COBOL type.
6146 Any other Ada parameter is passed as a @samp{BY REFERENCE} data item of the
6147 COBOL type corresponding to the Ada parameter type; for scalars, a local
6148 copy is used if necessary to ensure by-copy semantics.
6152 @cindex Fortran, interfacing with
6153 @unnumberedsec B.5(22-26): Interfacing with Fortran
6156 An Ada implementation should support the following interface
6157 correspondences between Ada and Fortran:
6163 An Ada procedure corresponds to a Fortran subroutine.
6169 An Ada function corresponds to a Fortran function.
6175 An Ada parameter of an elementary, array, or record type @var{T} is
6176 passed as a @var{T} argument to a Fortran procedure, where @var{T} is
6177 the Fortran type corresponding to the Ada type @var{T}, and where the
6178 INTENT attribute of the corresponding dummy argument matches the Ada
6179 formal parameter mode; the Fortran implementation's parameter passing
6180 conventions are used. For elementary types, a local copy is used if
6181 necessary to ensure by-copy semantics.
6187 An Ada parameter of an access-to-subprogram type is passed as a
6188 reference to a Fortran procedure whose interface corresponds to the
6189 designated subprogram's specification.
6193 @cindex Machine operations
6194 @unnumberedsec C.1(3-5): Access to Machine Operations
6197 The machine code or intrinsic support should allow access to all
6198 operations normally available to assembly language programmers for the
6199 target environment, including privileged instructions, if any.
6205 The interfacing pragmas (see Annex B) should support interface to
6206 assembler; the default assembler should be associated with the
6207 convention identifier @code{Assembler}.
6213 If an entity is exported to assembly language, then the implementation
6214 should allocate it at an addressable location, and should ensure that it
6215 is retained by the linking process, even if not otherwise referenced
6216 from the Ada code. The implementation should assume that any call to a
6217 machine code or assembler subprogram is allowed to read or update every
6218 object that is specified as exported.
6222 @unnumberedsec C.1(10-16): Access to Machine Operations
6225 The implementation should ensure that little or no overhead is
6226 associated with calling intrinsic and machine-code subprograms.
6228 Followed for both intrinsics and machine-code subprograms.
6232 It is recommended that intrinsic subprograms be provided for convenient
6233 access to any machine operations that provide special capabilities or
6234 efficiency and that are not otherwise available through the language
6237 Followed. A full set of machine operation intrinsic subprograms is provided.
6241 Atomic read-modify-write operations---e.g.@:, test and set, compare and
6242 swap, decrement and test, enqueue/dequeue.
6244 Followed on any target supporting such operations.
6248 Standard numeric functions---e.g.@:, sin, log.
6250 Followed on any target supporting such operations.
6254 String manipulation operations---e.g.@:, translate and test.
6256 Followed on any target supporting such operations.
6260 Vector operations---e.g.@:, compare vector against thresholds.
6262 Followed on any target supporting such operations.
6266 Direct operations on I/O ports.
6268 Followed on any target supporting such operations.
6270 @cindex Interrupt support
6271 @unnumberedsec C.3(28): Interrupt Support
6274 If the @code{Ceiling_Locking} policy is not in effect, the
6275 implementation should provide means for the application to specify which
6276 interrupts are to be blocked during protected actions, if the underlying
6277 system allows for a finer-grain control of interrupt blocking.
6279 Followed. The underlying system does not allow for finer-grain control
6280 of interrupt blocking.
6282 @cindex Protected procedure handlers
6283 @unnumberedsec C.3.1(20-21): Protected Procedure Handlers
6286 Whenever possible, the implementation should allow interrupt handlers to
6287 be called directly by the hardware.
6291 This is never possible under IRIX, so this is followed by default.
6293 Followed on any target where the underlying operating system permits
6298 Whenever practical, violations of any
6299 implementation-defined restrictions should be detected before run time.
6301 Followed. Compile time warnings are given when possible.
6303 @cindex Package @code{Interrupts}
6305 @unnumberedsec C.3.2(25): Package @code{Interrupts}
6309 If implementation-defined forms of interrupt handler procedures are
6310 supported, such as protected procedures with parameters, then for each
6311 such form of a handler, a type analogous to @code{Parameterless_Handler}
6312 should be specified in a child package of @code{Interrupts}, with the
6313 same operations as in the predefined package Interrupts.
6317 @cindex Pre-elaboration requirements
6318 @unnumberedsec C.4(14): Pre-elaboration Requirements
6321 It is recommended that pre-elaborated packages be implemented in such a
6322 way that there should be little or no code executed at run time for the
6323 elaboration of entities not already covered by the Implementation
6326 Followed. Executable code is generated in some cases, e.g.@: loops
6327 to initialize large arrays.
6329 @unnumberedsec C.5(8): Pragma @code{Discard_Names}
6333 If the pragma applies to an entity, then the implementation should
6334 reduce the amount of storage used for storing names associated with that
6339 @cindex Package @code{Task_Attributes}
6340 @findex Task_Attributes
6341 @unnumberedsec C.7.2(30): The Package Task_Attributes
6344 Some implementations are targeted to domains in which memory use at run
6345 time must be completely deterministic. For such implementations, it is
6346 recommended that the storage for task attributes will be pre-allocated
6347 statically and not from the heap. This can be accomplished by either
6348 placing restrictions on the number and the size of the task's
6349 attributes, or by using the pre-allocated storage for the first @var{N}
6350 attribute objects, and the heap for the others. In the latter case,
6351 @var{N} should be documented.
6353 Not followed. This implementation is not targeted to such a domain.
6355 @cindex Locking Policies
6356 @unnumberedsec D.3(17): Locking Policies
6360 The implementation should use names that end with @samp{_Locking} for
6361 locking policies defined by the implementation.
6363 Followed. A single implementation-defined locking policy is defined,
6364 whose name (@code{Inheritance_Locking}) follows this suggestion.
6366 @cindex Entry queuing policies
6367 @unnumberedsec D.4(16): Entry Queuing Policies
6370 Names that end with @samp{_Queuing} should be used
6371 for all implementation-defined queuing policies.
6373 Followed. No such implementation-defined queuing policies exist.
6375 @cindex Preemptive abort
6376 @unnumberedsec D.6(9-10): Preemptive Abort
6379 Even though the @code{abort_statement} is included in the list of
6380 potentially blocking operations (see 9.5.1), it is recommended that this
6381 statement be implemented in a way that never requires the task executing
6382 the @code{abort_statement} to block.
6388 On a multi-processor, the delay associated with aborting a task on
6389 another processor should be bounded; the implementation should use
6390 periodic polling, if necessary, to achieve this.
6394 @cindex Tasking restrictions
6395 @unnumberedsec D.7(21): Tasking Restrictions
6398 When feasible, the implementation should take advantage of the specified
6399 restrictions to produce a more efficient implementation.
6401 GNAT currently takes advantage of these restrictions by providing an optimized
6402 run time when the Ravenscar profile and the GNAT restricted run time set
6403 of restrictions are specified. See pragma @code{Profile (Ravenscar)} and
6404 pragma @code{Profile (Restricted)} for more details.
6406 @cindex Time, monotonic
6407 @unnumberedsec D.8(47-49): Monotonic Time
6410 When appropriate, implementations should provide configuration
6411 mechanisms to change the value of @code{Tick}.
6413 Such configuration mechanisms are not appropriate to this implementation
6414 and are thus not supported.
6418 It is recommended that @code{Calendar.Clock} and @code{Real_Time.Clock}
6419 be implemented as transformations of the same time base.
6425 It is recommended that the @dfn{best} time base which exists in
6426 the underlying system be available to the application through
6427 @code{Clock}. @dfn{Best} may mean highest accuracy or largest range.
6431 @cindex Partition communication subsystem
6433 @unnumberedsec E.5(28-29): Partition Communication Subsystem
6436 Whenever possible, the PCS on the called partition should allow for
6437 multiple tasks to call the RPC-receiver with different messages and
6438 should allow them to block until the corresponding subprogram body
6441 Followed by GLADE, a separately supplied PCS that can be used with
6446 The @code{Write} operation on a stream of type @code{Params_Stream_Type}
6447 should raise @code{Storage_Error} if it runs out of space trying to
6448 write the @code{Item} into the stream.
6450 Followed by GLADE, a separately supplied PCS that can be used with
6453 @cindex COBOL support
6454 @unnumberedsec F(7): COBOL Support
6457 If COBOL (respectively, C) is widely supported in the target
6458 environment, implementations supporting the Information Systems Annex
6459 should provide the child package @code{Interfaces.COBOL} (respectively,
6460 @code{Interfaces.C}) specified in Annex B and should support a
6461 @code{convention_identifier} of COBOL (respectively, C) in the interfacing
6462 pragmas (see Annex B), thus allowing Ada programs to interface with
6463 programs written in that language.
6467 @cindex Decimal radix support
6468 @unnumberedsec F.1(2): Decimal Radix Support
6471 Packed decimal should be used as the internal representation for objects
6472 of subtype @var{S} when @var{S}'Machine_Radix = 10.
6474 Not followed. GNAT ignores @var{S}'Machine_Radix and always uses binary
6478 @unnumberedsec G: Numerics
6481 If Fortran (respectively, C) is widely supported in the target
6482 environment, implementations supporting the Numerics Annex
6483 should provide the child package @code{Interfaces.Fortran} (respectively,
6484 @code{Interfaces.C}) specified in Annex B and should support a
6485 @code{convention_identifier} of Fortran (respectively, C) in the interfacing
6486 pragmas (see Annex B), thus allowing Ada programs to interface with
6487 programs written in that language.
6491 @cindex Complex types
6492 @unnumberedsec G.1.1(56-58): Complex Types
6495 Because the usual mathematical meaning of multiplication of a complex
6496 operand and a real operand is that of the scaling of both components of
6497 the former by the latter, an implementation should not perform this
6498 operation by first promoting the real operand to complex type and then
6499 performing a full complex multiplication. In systems that, in the
6500 future, support an Ada binding to IEC 559:1989, the latter technique
6501 will not generate the required result when one of the components of the
6502 complex operand is infinite. (Explicit multiplication of the infinite
6503 component by the zero component obtained during promotion yields a NaN
6504 that propagates into the final result.) Analogous advice applies in the
6505 case of multiplication of a complex operand and a pure-imaginary
6506 operand, and in the case of division of a complex operand by a real or
6507 pure-imaginary operand.
6513 Similarly, because the usual mathematical meaning of addition of a
6514 complex operand and a real operand is that the imaginary operand remains
6515 unchanged, an implementation should not perform this operation by first
6516 promoting the real operand to complex type and then performing a full
6517 complex addition. In implementations in which the @code{Signed_Zeros}
6518 attribute of the component type is @code{True} (and which therefore
6519 conform to IEC 559:1989 in regard to the handling of the sign of zero in
6520 predefined arithmetic operations), the latter technique will not
6521 generate the required result when the imaginary component of the complex
6522 operand is a negatively signed zero. (Explicit addition of the negative
6523 zero to the zero obtained during promotion yields a positive zero.)
6524 Analogous advice applies in the case of addition of a complex operand
6525 and a pure-imaginary operand, and in the case of subtraction of a
6526 complex operand and a real or pure-imaginary operand.
6532 Implementations in which @code{Real'Signed_Zeros} is @code{True} should
6533 attempt to provide a rational treatment of the signs of zero results and
6534 result components. As one example, the result of the @code{Argument}
6535 function should have the sign of the imaginary component of the
6536 parameter @code{X} when the point represented by that parameter lies on
6537 the positive real axis; as another, the sign of the imaginary component
6538 of the @code{Compose_From_Polar} function should be the same as
6539 (respectively, the opposite of) that of the @code{Argument} parameter when that
6540 parameter has a value of zero and the @code{Modulus} parameter has a
6541 nonnegative (respectively, negative) value.
6545 @cindex Complex elementary functions
6546 @unnumberedsec G.1.2(49): Complex Elementary Functions
6549 Implementations in which @code{Complex_Types.Real'Signed_Zeros} is
6550 @code{True} should attempt to provide a rational treatment of the signs
6551 of zero results and result components. For example, many of the complex
6552 elementary functions have components that are odd functions of one of
6553 the parameter components; in these cases, the result component should
6554 have the sign of the parameter component at the origin. Other complex
6555 elementary functions have zero components whose sign is opposite that of
6556 a parameter component at the origin, or is always positive or always
6561 @cindex Accuracy requirements
6562 @unnumberedsec G.2.4(19): Accuracy Requirements
6565 The versions of the forward trigonometric functions without a
6566 @code{Cycle} parameter should not be implemented by calling the
6567 corresponding version with a @code{Cycle} parameter of
6568 @code{2.0*Numerics.Pi}, since this will not provide the required
6569 accuracy in some portions of the domain. For the same reason, the
6570 version of @code{Log} without a @code{Base} parameter should not be
6571 implemented by calling the corresponding version with a @code{Base}
6572 parameter of @code{Numerics.e}.
6576 @cindex Complex arithmetic accuracy
6577 @cindex Accuracy, complex arithmetic
6578 @unnumberedsec G.2.6(15): Complex Arithmetic Accuracy
6582 The version of the @code{Compose_From_Polar} function without a
6583 @code{Cycle} parameter should not be implemented by calling the
6584 corresponding version with a @code{Cycle} parameter of
6585 @code{2.0*Numerics.Pi}, since this will not provide the required
6586 accuracy in some portions of the domain.
6590 @c -----------------------------------------
6591 @node Implementation Defined Characteristics
6592 @chapter Implementation Defined Characteristics
6595 In addition to the implementation dependent pragmas and attributes, and
6596 the implementation advice, there are a number of other features of Ada
6597 95 that are potentially implementation dependent. These are mentioned
6598 throughout the Ada 95 Reference Manual, and are summarized in annex M@.
6600 A requirement for conforming Ada compilers is that they provide
6601 documentation describing how the implementation deals with each of these
6602 issues. In this chapter, you will find each point in annex M listed
6603 followed by a description in italic font of how GNAT
6607 implementation on IRIX 5.3 operating system or greater
6609 handles the implementation dependence.
6611 You can use this chapter as a guide to minimizing implementation
6612 dependent features in your programs if portability to other compilers
6613 and other operating systems is an important consideration. The numbers
6614 in each section below correspond to the paragraph number in the Ada 95
6620 @strong{2}. Whether or not each recommendation given in Implementation
6621 Advice is followed. See 1.1.2(37).
6624 @xref{Implementation Advice}.
6629 @strong{3}. Capacity limitations of the implementation. See 1.1.3(3).
6632 The complexity of programs that can be processed is limited only by the
6633 total amount of available virtual memory, and disk space for the
6634 generated object files.
6639 @strong{4}. Variations from the standard that are impractical to avoid
6640 given the implementation's execution environment. See 1.1.3(6).
6643 There are no variations from the standard.
6648 @strong{5}. Which @code{code_statement}s cause external
6649 interactions. See 1.1.3(10).
6652 Any @code{code_statement} can potentially cause external interactions.
6657 @strong{6}. The coded representation for the text of an Ada
6658 program. See 2.1(4).
6661 See separate section on source representation.
6666 @strong{7}. The control functions allowed in comments. See 2.1(14).
6669 See separate section on source representation.
6674 @strong{8}. The representation for an end of line. See 2.2(2).
6677 See separate section on source representation.
6682 @strong{9}. Maximum supported line length and lexical element
6683 length. See 2.2(15).
6686 The maximum line length is 255 characters an the maximum length of a
6687 lexical element is also 255 characters.
6692 @strong{10}. Implementation defined pragmas. See 2.8(14).
6696 @xref{Implementation Defined Pragmas}.
6701 @strong{11}. Effect of pragma @code{Optimize}. See 2.8(27).
6704 Pragma @code{Optimize}, if given with a @code{Time} or @code{Space}
6705 parameter, checks that the optimization flag is set, and aborts if it is
6711 @strong{12}. The sequence of characters of the value returned by
6712 @code{@var{S}'Image} when some of the graphic characters of
6713 @code{@var{S}'Wide_Image} are not defined in @code{Character}. See
6717 The sequence of characters is as defined by the wide character encoding
6718 method used for the source. See section on source representation for
6724 @strong{13}. The predefined integer types declared in
6725 @code{Standard}. See 3.5.4(25).
6729 @item Short_Short_Integer
6732 (Short) 16 bit signed
6736 64 bit signed (Alpha OpenVMS only)
6737 32 bit signed (all other targets)
6738 @item Long_Long_Integer
6745 @strong{14}. Any nonstandard integer types and the operators defined
6746 for them. See 3.5.4(26).
6749 There are no nonstandard integer types.
6754 @strong{15}. Any nonstandard real types and the operators defined for
6758 There are no nonstandard real types.
6763 @strong{16}. What combinations of requested decimal precision and range
6764 are supported for floating point types. See 3.5.7(7).
6767 The precision and range is as defined by the IEEE standard.
6772 @strong{17}. The predefined floating point types declared in
6773 @code{Standard}. See 3.5.7(16).
6780 (Short) 32 bit IEEE short
6783 @item Long_Long_Float
6784 64 bit IEEE long (80 bit IEEE long on x86 processors)
6790 @strong{18}. The small of an ordinary fixed point type. See 3.5.9(8).
6793 @code{Fine_Delta} is 2**(@minus{}63)
6798 @strong{19}. What combinations of small, range, and digits are
6799 supported for fixed point types. See 3.5.9(10).
6802 Any combinations are permitted that do not result in a small less than
6803 @code{Fine_Delta} and do not result in a mantissa larger than 63 bits.
6804 If the mantissa is larger than 53 bits on machines where Long_Long_Float
6805 is 64 bits (true of all architectures except ia32), then the output from
6806 Text_IO is accurate to only 53 bits, rather than the full mantissa. This
6807 is because floating-point conversions are used to convert fixed point.
6812 @strong{20}. The result of @code{Tags.Expanded_Name} for types declared
6813 within an unnamed @code{block_statement}. See 3.9(10).
6816 Block numbers of the form @code{B@var{nnn}}, where @var{nnn} is a
6817 decimal integer are allocated.
6822 @strong{21}. Implementation-defined attributes. See 4.1.4(12).
6825 @xref{Implementation Defined Attributes}.
6830 @strong{22}. Any implementation-defined time types. See 9.6(6).
6833 There are no implementation-defined time types.
6838 @strong{23}. The time base associated with relative delays.
6841 See 9.6(20). The time base used is that provided by the C library
6842 function @code{gettimeofday}.
6847 @strong{24}. The time base of the type @code{Calendar.Time}. See
6851 The time base used is that provided by the C library function
6852 @code{gettimeofday}.
6857 @strong{25}. The time zone used for package @code{Calendar}
6858 operations. See 9.6(24).
6861 The time zone used by package @code{Calendar} is the current system time zone
6862 setting for local time, as accessed by the C library function
6868 @strong{26}. Any limit on @code{delay_until_statements} of
6869 @code{select_statements}. See 9.6(29).
6872 There are no such limits.
6877 @strong{27}. Whether or not two non overlapping parts of a composite
6878 object are independently addressable, in the case where packing, record
6879 layout, or @code{Component_Size} is specified for the object. See
6883 Separate components are independently addressable if they do not share
6884 overlapping storage units.
6889 @strong{28}. The representation for a compilation. See 10.1(2).
6892 A compilation is represented by a sequence of files presented to the
6893 compiler in a single invocation of the @code{gcc} command.
6898 @strong{29}. Any restrictions on compilations that contain multiple
6899 compilation_units. See 10.1(4).
6902 No single file can contain more than one compilation unit, but any
6903 sequence of files can be presented to the compiler as a single
6909 @strong{30}. The mechanisms for creating an environment and for adding
6910 and replacing compilation units. See 10.1.4(3).
6913 See separate section on compilation model.
6918 @strong{31}. The manner of explicitly assigning library units to a
6919 partition. See 10.2(2).
6922 If a unit contains an Ada main program, then the Ada units for the partition
6923 are determined by recursive application of the rules in the Ada Reference
6924 Manual section 10.2(2-6). In other words, the Ada units will be those that
6925 are needed by the main program, and then this definition of need is applied
6926 recursively to those units, and the partition contains the transitive
6927 closure determined by this relationship. In short, all the necessary units
6928 are included, with no need to explicitly specify the list. If additional
6929 units are required, e.g.@: by foreign language units, then all units must be
6930 mentioned in the context clause of one of the needed Ada units.
6932 If the partition contains no main program, or if the main program is in
6933 a language other than Ada, then GNAT
6934 provides the binder options @code{-z} and @code{-n} respectively, and in
6935 this case a list of units can be explicitly supplied to the binder for
6936 inclusion in the partition (all units needed by these units will also
6937 be included automatically). For full details on the use of these
6938 options, refer to the @cite{GNAT User's Guide} sections on Binding
6944 @strong{32}. The implementation-defined means, if any, of specifying
6945 which compilation units are needed by a given compilation unit. See
6949 The units needed by a given compilation unit are as defined in
6950 the Ada Reference Manual section 10.2(2-6). There are no
6951 implementation-defined pragmas or other implementation-defined
6952 means for specifying needed units.
6957 @strong{33}. The manner of designating the main subprogram of a
6958 partition. See 10.2(7).
6961 The main program is designated by providing the name of the
6962 corresponding @file{ALI} file as the input parameter to the binder.
6967 @strong{34}. The order of elaboration of @code{library_items}. See
6971 The first constraint on ordering is that it meets the requirements of
6972 chapter 10 of the Ada 95 Reference Manual. This still leaves some
6973 implementation dependent choices, which are resolved by first
6974 elaborating bodies as early as possible (i.e.@: in preference to specs
6975 where there is a choice), and second by evaluating the immediate with
6976 clauses of a unit to determine the probably best choice, and
6977 third by elaborating in alphabetical order of unit names
6978 where a choice still remains.
6983 @strong{35}. Parameter passing and function return for the main
6984 subprogram. See 10.2(21).
6987 The main program has no parameters. It may be a procedure, or a function
6988 returning an integer type. In the latter case, the returned integer
6989 value is the return code of the program (overriding any value that
6990 may have been set by a call to @code{Ada.Command_Line.Set_Exit_Status}).
6995 @strong{36}. The mechanisms for building and running partitions. See
6999 GNAT itself supports programs with only a single partition. The GNATDIST
7000 tool provided with the GLADE package (which also includes an implementation
7001 of the PCS) provides a completely flexible method for building and running
7002 programs consisting of multiple partitions. See the separate GLADE manual
7008 @strong{37}. The details of program execution, including program
7009 termination. See 10.2(25).
7012 See separate section on compilation model.
7017 @strong{38}. The semantics of any non-active partitions supported by the
7018 implementation. See 10.2(28).
7021 Passive partitions are supported on targets where shared memory is
7022 provided by the operating system. See the GLADE reference manual for
7028 @strong{39}. The information returned by @code{Exception_Message}. See
7032 Exception message returns the null string unless a specific message has
7033 been passed by the program.
7038 @strong{40}. The result of @code{Exceptions.Exception_Name} for types
7039 declared within an unnamed @code{block_statement}. See 11.4.1(12).
7042 Blocks have implementation defined names of the form @code{B@var{nnn}}
7043 where @var{nnn} is an integer.
7048 @strong{41}. The information returned by
7049 @code{Exception_Information}. See 11.4.1(13).
7052 @code{Exception_Information} returns a string in the following format:
7055 @emph{Exception_Name:} nnnnn
7056 @emph{Message:} mmmmm
7058 @emph{Call stack traceback locations:}
7059 0xhhhh 0xhhhh 0xhhhh ... 0xhhh
7067 @code{nnnn} is the fully qualified name of the exception in all upper
7068 case letters. This line is always present.
7071 @code{mmmm} is the message (this line present only if message is non-null)
7074 @code{ppp} is the Process Id value as a decimal integer (this line is
7075 present only if the Process Id is non-zero). Currently we are
7076 not making use of this field.
7079 The Call stack traceback locations line and the following values
7080 are present only if at least one traceback location was recorded.
7081 The values are given in C style format, with lower case letters
7082 for a-f, and only as many digits present as are necessary.
7086 The line terminator sequence at the end of each line, including
7087 the last line is a single @code{LF} character (@code{16#0A#}).
7092 @strong{42}. Implementation-defined check names. See 11.5(27).
7095 No implementation-defined check names are supported.
7100 @strong{43}. The interpretation of each aspect of representation. See
7104 See separate section on data representations.
7109 @strong{44}. Any restrictions placed upon representation items. See
7113 See separate section on data representations.
7118 @strong{45}. The meaning of @code{Size} for indefinite subtypes. See
7122 Size for an indefinite subtype is the maximum possible size, except that
7123 for the case of a subprogram parameter, the size of the parameter object
7129 @strong{46}. The default external representation for a type tag. See
7133 The default external representation for a type tag is the fully expanded
7134 name of the type in upper case letters.
7139 @strong{47}. What determines whether a compilation unit is the same in
7140 two different partitions. See 13.3(76).
7143 A compilation unit is the same in two different partitions if and only
7144 if it derives from the same source file.
7149 @strong{48}. Implementation-defined components. See 13.5.1(15).
7152 The only implementation defined component is the tag for a tagged type,
7153 which contains a pointer to the dispatching table.
7158 @strong{49}. If @code{Word_Size} = @code{Storage_Unit}, the default bit
7159 ordering. See 13.5.3(5).
7162 @code{Word_Size} (32) is not the same as @code{Storage_Unit} (8) for this
7163 implementation, so no non-default bit ordering is supported. The default
7164 bit ordering corresponds to the natural endianness of the target architecture.
7169 @strong{50}. The contents of the visible part of package @code{System}
7170 and its language-defined children. See 13.7(2).
7173 See the definition of these packages in files @file{system.ads} and
7174 @file{s-stoele.ads}.
7179 @strong{51}. The contents of the visible part of package
7180 @code{System.Machine_Code}, and the meaning of
7181 @code{code_statements}. See 13.8(7).
7184 See the definition and documentation in file @file{s-maccod.ads}.
7189 @strong{52}. The effect of unchecked conversion. See 13.9(11).
7192 Unchecked conversion between types of the same size
7193 and results in an uninterpreted transmission of the bits from one type
7194 to the other. If the types are of unequal sizes, then in the case of
7195 discrete types, a shorter source is first zero or sign extended as
7196 necessary, and a shorter target is simply truncated on the left.
7197 For all non-discrete types, the source is first copied if necessary
7198 to ensure that the alignment requirements of the target are met, then
7199 a pointer is constructed to the source value, and the result is obtained
7200 by dereferencing this pointer after converting it to be a pointer to the
7206 @strong{53}. The manner of choosing a storage pool for an access type
7207 when @code{Storage_Pool} is not specified for the type. See 13.11(17).
7210 There are 3 different standard pools used by the compiler when
7211 @code{Storage_Pool} is not specified depending whether the type is local
7212 to a subprogram or defined at the library level and whether
7213 @code{Storage_Size}is specified or not. See documentation in the runtime
7214 library units @code{System.Pool_Global}, @code{System.Pool_Size} and
7215 @code{System.Pool_Local} in files @file{s-poosiz.ads},
7216 @file{s-pooglo.ads} and @file{s-pooloc.ads} for full details on the
7222 @strong{54}. Whether or not the implementation provides user-accessible
7223 names for the standard pool type(s). See 13.11(17).
7227 See documentation in the sources of the run time mentioned in paragraph
7228 @strong{53} . All these pools are accessible by means of @code{with}'ing
7234 @strong{55}. The meaning of @code{Storage_Size}. See 13.11(18).
7237 @code{Storage_Size} is measured in storage units, and refers to the
7238 total space available for an access type collection, or to the primary
7239 stack space for a task.
7244 @strong{56}. Implementation-defined aspects of storage pools. See
7248 See documentation in the sources of the run time mentioned in paragraph
7249 @strong{53} for details on GNAT-defined aspects of storage pools.
7254 @strong{57}. The set of restrictions allowed in a pragma
7255 @code{Restrictions}. See 13.12(7).
7258 All RM defined Restriction identifiers are implemented. The following
7259 additional restriction identifiers are provided. There are two separate
7260 lists of implementation dependent restriction identifiers. The first
7261 set requires consistency throughout a partition (in other words, if the
7262 restriction identifier is used for any compilation unit in the partition,
7263 then all compilation units in the partition must obey the restriction.
7267 @item Simple_Barriers
7268 @findex Simple_Barriers
7269 This restriction ensures at compile time that barriers in entry declarations
7270 for protected types are restricted to either static boolean expressions or
7271 references to simple boolean variables defined in the private part of the
7272 protected type. No other form of entry barriers is permitted. This is one
7273 of the restrictions of the Ravenscar profile for limited tasking (see also
7274 pragma @code{Profile (Ravenscar)}).
7276 @item Max_Entry_Queue_Length => Expr
7277 @findex Max_Entry_Queue_Length
7278 This restriction is a declaration that any protected entry compiled in
7279 the scope of the restriction has at most the specified number of
7280 tasks waiting on the entry
7281 at any one time, and so no queue is required. This restriction is not
7282 checked at compile time. A program execution is erroneous if an attempt
7283 is made to queue more than the specified number of tasks on such an entry.
7287 This restriction ensures at compile time that there is no implicit or
7288 explicit dependence on the package @code{Ada.Calendar}.
7290 @item No_Direct_Boolean_Operators
7291 @findex No_Direct_Boolean_Operators
7292 This restriction ensures that no logical (and/or/xor) or comparison
7293 operators are used on operands of type Boolean (or any type derived
7294 from Boolean). This is intended for use in safety critical programs
7295 where the certification protocol requires the use of short-circuit
7296 (and then, or else) forms for all composite boolean operations.
7298 @item No_Dynamic_Attachment
7299 @findex No_Dynamic_Attachment
7300 This restriction ensures that there is no call to any of the operations
7301 defined in package Ada.Interrupts.
7303 @item No_Enumeration_Maps
7304 @findex No_Enumeration_Maps
7305 This restriction ensures at compile time that no operations requiring
7306 enumeration maps are used (that is Image and Value attributes applied
7307 to enumeration types).
7309 @item No_Entry_Calls_In_Elaboration_Code
7310 @findex No_Entry_Calls_In_Elaboration_Code
7311 This restriction ensures at compile time that no task or protected entry
7312 calls are made during elaboration code. As a result of the use of this
7313 restriction, the compiler can assume that no code past an accept statement
7314 in a task can be executed at elaboration time.
7316 @item No_Exception_Handlers
7317 @findex No_Exception_Handlers
7318 This restriction ensures at compile time that there are no explicit
7319 exception handlers. It also indicates that no exception propagation will
7320 be provided. In this mode, exceptions may be raised but will result in
7321 an immediate call to the last chance handler, a routine that the user
7322 must define with the following profile:
7324 procedure Last_Chance_Handler
7325 (Source_Location : System.Address; Line : Integer);
7326 pragma Export (C, Last_Chance_Handler,
7327 "__gnat_last_chance_handler");
7329 The parameter is a C null-terminated string representing a message to be
7330 associated with the exception (typically the source location of the raise
7331 statement generated by the compiler). The Line parameter when non-zero
7332 represents the line number in the source program where the raise occurs.
7334 @item No_Exception_Streams
7335 @findex No_Exception_Streams
7336 This restriction ensures at compile time that no stream operations for
7337 types Exception_Id or Exception_Occurrence are used. This also makes it
7338 impossible to pass exceptions to or from a partition with this restriction
7339 in a distributed environment. If this exception is active, then the generated
7340 code is simplified by omitting the otherwise-required global registration
7341 of exceptions when they are declared.
7343 @item No_Implicit_Conditionals
7344 @findex No_Implicit_Conditionals
7345 This restriction ensures that the generated code does not contain any
7346 implicit conditionals, either by modifying the generated code where possible,
7347 or by rejecting any construct that would otherwise generate an implicit
7348 conditional. Note that this check does not include run time constraint
7349 checks, which on some targets may generate implicit conditionals as
7350 well. To control the latter, constraint checks can be suppressed in the
7353 @item No_Implicit_Dynamic_Code
7354 @findex No_Implicit_Dynamic_Code
7355 This restriction prevents the compiler from building ``trampolines''.
7356 This is a structure that is built on the stack and contains dynamic
7357 code to be executed at run time. A trampoline is needed to indirectly
7358 address a nested subprogram (that is a subprogram that is not at the
7359 library level). The restriction prevents the use of any of the
7360 attributes @code{Address}, @code{Access} or @code{Unrestricted_Access}
7361 being applied to a subprogram that is not at the library level.
7363 @item No_Implicit_Loops
7364 @findex No_Implicit_Loops
7365 This restriction ensures that the generated code does not contain any
7366 implicit @code{for} loops, either by modifying
7367 the generated code where possible,
7368 or by rejecting any construct that would otherwise generate an implicit
7371 @item No_Initialize_Scalars
7372 @findex No_Initialize_Scalars
7373 This restriction ensures that no unit in the partition is compiled with
7374 pragma Initialize_Scalars. This allows the generation of more efficient
7375 code, and in particular eliminates dummy null initialization routines that
7376 are otherwise generated for some record and array types.
7378 @item No_Local_Protected_Objects
7379 @findex No_Local_Protected_Objects
7380 This restriction ensures at compile time that protected objects are
7381 only declared at the library level.
7383 @item No_Protected_Type_Allocators
7384 @findex No_Protected_Type_Allocators
7385 This restriction ensures at compile time that there are no allocator
7386 expressions that attempt to allocate protected objects.
7388 @item No_Secondary_Stack
7389 @findex No_Secondary_Stack
7390 This restriction ensures at compile time that the generated code does not
7391 contain any reference to the secondary stack. The secondary stack is used
7392 to implement functions returning unconstrained objects (arrays or records)
7395 @item No_Select_Statements
7396 @findex No_Select_Statements
7397 This restriction ensures at compile time no select statements of any kind
7398 are permitted, that is the keyword @code{select} may not appear.
7399 This is one of the restrictions of the Ravenscar
7400 profile for limited tasking (see also pragma @code{Profile (Ravenscar)}).
7402 @item No_Standard_Storage_Pools
7403 @findex No_Standard_Storage_Pools
7404 This restriction ensures at compile time that no access types
7405 use the standard default storage pool. Any access type declared must
7406 have an explicit Storage_Pool attribute defined specifying a
7407 user-defined storage pool.
7411 This restriction ensures at compile/bind time that there are no
7412 stream objects created (and therefore no actual stream operations).
7413 This restriction does not forbid dependences on the package
7414 @code{Ada.Streams}. So it is permissible to with
7415 @code{Ada.Streams} (or another package that does so itself)
7416 as long as no actual stream objects are created.
7418 @item No_Task_Attributes_Package
7419 @findex No_Task_Attributes_Package
7420 This restriction ensures at compile time that there are no implicit or
7421 explicit dependencies on the package @code{Ada.Task_Attributes}.
7423 @item No_Task_Termination
7424 @findex No_Task_Termination
7425 This restriction ensures at compile time that no terminate alternatives
7426 appear in any task body.
7430 This restriction prevents the declaration of tasks or task types throughout
7431 the partition. It is similar in effect to the use of @code{Max_Tasks => 0}
7432 except that violations are caught at compile time and cause an error message
7433 to be output either by the compiler or binder.
7435 @item No_Wide_Characters
7436 @findex No_Wide_Characters
7437 This restriction ensures at compile time that no uses of the types
7438 @code{Wide_Character} or @code{Wide_String} or corresponding wide
7440 appear, and that no wide or wide wide string or character literals
7441 appear in the program (that is literals representing characters not in
7442 type @code{Character}.
7444 @item Static_Priorities
7445 @findex Static_Priorities
7446 This restriction ensures at compile time that all priority expressions
7447 are static, and that there are no dependencies on the package
7448 @code{Ada.Dynamic_Priorities}.
7450 @item Static_Storage_Size
7451 @findex Static_Storage_Size
7452 This restriction ensures at compile time that any expression appearing
7453 in a Storage_Size pragma or attribute definition clause is static.
7458 The second set of implementation dependent restriction identifiers
7459 does not require partition-wide consistency.
7460 The restriction may be enforced for a single
7461 compilation unit without any effect on any of the
7462 other compilation units in the partition.
7466 @item No_Elaboration_Code
7467 @findex No_Elaboration_Code
7468 This restriction ensures at compile time that no elaboration code is
7469 generated. Note that this is not the same condition as is enforced
7470 by pragma @code{Preelaborate}. There are cases in which pragma
7471 @code{Preelaborate} still permits code to be generated (e.g.@: code
7472 to initialize a large array to all zeroes), and there are cases of units
7473 which do not meet the requirements for pragma @code{Preelaborate},
7474 but for which no elaboration code is generated. Generally, it is
7475 the case that preelaborable units will meet the restrictions, with
7476 the exception of large aggregates initialized with an others_clause,
7477 and exception declarations (which generate calls to a run-time
7478 registry procedure). Note that this restriction is enforced on
7479 a unit by unit basis, it need not be obeyed consistently
7480 throughout a partition.
7482 @item No_Entry_Queue
7483 @findex No_Entry_Queue
7484 This restriction is a declaration that any protected entry compiled in
7485 the scope of the restriction has at most one task waiting on the entry
7486 at any one time, and so no queue is required. This restriction is not
7487 checked at compile time. A program execution is erroneous if an attempt
7488 is made to queue a second task on such an entry.
7490 @item No_Implementation_Attributes
7491 @findex No_Implementation_Attributes
7492 This restriction checks at compile time that no GNAT-defined attributes
7493 are present. With this restriction, the only attributes that can be used
7494 are those defined in the Ada 95 Reference Manual.
7496 @item No_Implementation_Pragmas
7497 @findex No_Implementation_Pragmas
7498 This restriction checks at compile time that no GNAT-defined pragmas
7499 are present. With this restriction, the only pragmas that can be used
7500 are those defined in the Ada 95 Reference Manual.
7502 @item No_Implementation_Restrictions
7503 @findex No_Implementation_Restrictions
7504 This restriction checks at compile time that no GNAT-defined restriction
7505 identifiers (other than @code{No_Implementation_Restrictions} itself)
7506 are present. With this restriction, the only other restriction identifiers
7507 that can be used are those defined in the Ada 95 Reference Manual.
7514 @strong{58}. The consequences of violating limitations on
7515 @code{Restrictions} pragmas. See 13.12(9).
7518 Restrictions that can be checked at compile time result in illegalities
7519 if violated. Currently there are no other consequences of violating
7525 @strong{59}. The representation used by the @code{Read} and
7526 @code{Write} attributes of elementary types in terms of stream
7527 elements. See 13.13.2(9).
7530 The representation is the in-memory representation of the base type of
7531 the type, using the number of bits corresponding to the
7532 @code{@var{type}'Size} value, and the natural ordering of the machine.
7537 @strong{60}. The names and characteristics of the numeric subtypes
7538 declared in the visible part of package @code{Standard}. See A.1(3).
7541 See items describing the integer and floating-point types supported.
7546 @strong{61}. The accuracy actually achieved by the elementary
7547 functions. See A.5.1(1).
7550 The elementary functions correspond to the functions available in the C
7551 library. Only fast math mode is implemented.
7556 @strong{62}. The sign of a zero result from some of the operators or
7557 functions in @code{Numerics.Generic_Elementary_Functions}, when
7558 @code{Float_Type'Signed_Zeros} is @code{True}. See A.5.1(46).
7561 The sign of zeroes follows the requirements of the IEEE 754 standard on
7567 @strong{63}. The value of
7568 @code{Numerics.Float_Random.Max_Image_Width}. See A.5.2(27).
7571 Maximum image width is 649, see library file @file{a-numran.ads}.
7576 @strong{64}. The value of
7577 @code{Numerics.Discrete_Random.Max_Image_Width}. See A.5.2(27).
7580 Maximum image width is 80, see library file @file{a-nudira.ads}.
7585 @strong{65}. The algorithms for random number generation. See
7589 The algorithm is documented in the source files @file{a-numran.ads} and
7590 @file{a-numran.adb}.
7595 @strong{66}. The string representation of a random number generator's
7596 state. See A.5.2(38).
7599 See the documentation contained in the file @file{a-numran.adb}.
7604 @strong{67}. The minimum time interval between calls to the
7605 time-dependent Reset procedure that are guaranteed to initiate different
7606 random number sequences. See A.5.2(45).
7609 The minimum period between reset calls to guarantee distinct series of
7610 random numbers is one microsecond.
7615 @strong{68}. The values of the @code{Model_Mantissa},
7616 @code{Model_Emin}, @code{Model_Epsilon}, @code{Model},
7617 @code{Safe_First}, and @code{Safe_Last} attributes, if the Numerics
7618 Annex is not supported. See A.5.3(72).
7621 See the source file @file{ttypef.ads} for the values of all numeric
7627 @strong{69}. Any implementation-defined characteristics of the
7628 input-output packages. See A.7(14).
7631 There are no special implementation defined characteristics for these
7637 @strong{70}. The value of @code{Buffer_Size} in @code{Storage_IO}. See
7641 All type representations are contiguous, and the @code{Buffer_Size} is
7642 the value of @code{@var{type}'Size} rounded up to the next storage unit
7648 @strong{71}. External files for standard input, standard output, and
7649 standard error See A.10(5).
7652 These files are mapped onto the files provided by the C streams
7653 libraries. See source file @file{i-cstrea.ads} for further details.
7658 @strong{72}. The accuracy of the value produced by @code{Put}. See
7662 If more digits are requested in the output than are represented by the
7663 precision of the value, zeroes are output in the corresponding least
7664 significant digit positions.
7669 @strong{73}. The meaning of @code{Argument_Count}, @code{Argument}, and
7670 @code{Command_Name}. See A.15(1).
7673 These are mapped onto the @code{argv} and @code{argc} parameters of the
7674 main program in the natural manner.
7679 @strong{74}. Implementation-defined convention names. See B.1(11).
7682 The following convention names are supported
7690 Synonym for Assembler
7692 Synonym for Assembler
7695 @item C_Pass_By_Copy
7696 Allowed only for record types, like C, but also notes that record
7697 is to be passed by copy rather than reference.
7703 Treated the same as C
7705 Treated the same as C
7709 For support of pragma @code{Import} with convention Intrinsic, see
7710 separate section on Intrinsic Subprograms.
7712 Stdcall (used for Windows implementations only). This convention correspond
7713 to the WINAPI (previously called Pascal convention) C/C++ convention under
7714 Windows. A function with this convention cleans the stack before exit.
7720 Stubbed is a special convention used to indicate that the body of the
7721 subprogram will be entirely ignored. Any call to the subprogram
7722 is converted into a raise of the @code{Program_Error} exception. If a
7723 pragma @code{Import} specifies convention @code{stubbed} then no body need
7724 be present at all. This convention is useful during development for the
7725 inclusion of subprograms whose body has not yet been written.
7729 In addition, all otherwise unrecognized convention names are also
7730 treated as being synonymous with convention C@. In all implementations
7731 except for VMS, use of such other names results in a warning. In VMS
7732 implementations, these names are accepted silently.
7737 @strong{75}. The meaning of link names. See B.1(36).
7740 Link names are the actual names used by the linker.
7745 @strong{76}. The manner of choosing link names when neither the link
7746 name nor the address of an imported or exported entity is specified. See
7750 The default linker name is that which would be assigned by the relevant
7751 external language, interpreting the Ada name as being in all lower case
7757 @strong{77}. The effect of pragma @code{Linker_Options}. See B.1(37).
7760 The string passed to @code{Linker_Options} is presented uninterpreted as
7761 an argument to the link command, unless it contains Ascii.NUL characters.
7762 NUL characters if they appear act as argument separators, so for example
7764 @smallexample @c ada
7765 pragma Linker_Options ("-labc" & ASCII.Nul & "-ldef");
7769 causes two separate arguments @code{-labc} and @code{-ldef} to be passed to the
7770 linker. The order of linker options is preserved for a given unit. The final
7771 list of options passed to the linker is in reverse order of the elaboration
7772 order. For example, linker options fo a body always appear before the options
7773 from the corresponding package spec.
7778 @strong{78}. The contents of the visible part of package
7779 @code{Interfaces} and its language-defined descendants. See B.2(1).
7782 See files with prefix @file{i-} in the distributed library.
7787 @strong{79}. Implementation-defined children of package
7788 @code{Interfaces}. The contents of the visible part of package
7789 @code{Interfaces}. See B.2(11).
7792 See files with prefix @file{i-} in the distributed library.
7797 @strong{80}. The types @code{Floating}, @code{Long_Floating},
7798 @code{Binary}, @code{Long_Binary}, @code{Decimal_ Element}, and
7799 @code{COBOL_Character}; and the initialization of the variables
7800 @code{Ada_To_COBOL} and @code{COBOL_To_Ada}, in
7801 @code{Interfaces.COBOL}. See B.4(50).
7808 (Floating) Long_Float
7813 @item Decimal_Element
7815 @item COBOL_Character
7820 For initialization, see the file @file{i-cobol.ads} in the distributed library.
7825 @strong{81}. Support for access to machine instructions. See C.1(1).
7828 See documentation in file @file{s-maccod.ads} in the distributed library.
7833 @strong{82}. Implementation-defined aspects of access to machine
7834 operations. See C.1(9).
7837 See documentation in file @file{s-maccod.ads} in the distributed library.
7842 @strong{83}. Implementation-defined aspects of interrupts. See C.3(2).
7845 Interrupts are mapped to signals or conditions as appropriate. See
7847 @code{Ada.Interrupt_Names} in source file @file{a-intnam.ads} for details
7848 on the interrupts supported on a particular target.
7853 @strong{84}. Implementation-defined aspects of pre-elaboration. See
7857 GNAT does not permit a partition to be restarted without reloading,
7858 except under control of the debugger.
7863 @strong{85}. The semantics of pragma @code{Discard_Names}. See C.5(7).
7866 Pragma @code{Discard_Names} causes names of enumeration literals to
7867 be suppressed. In the presence of this pragma, the Image attribute
7868 provides the image of the Pos of the literal, and Value accepts
7874 @strong{86}. The result of the @code{Task_Identification.Image}
7875 attribute. See C.7.1(7).
7878 The result of this attribute is an 8-digit hexadecimal string
7879 representing the virtual address of the task control block.
7884 @strong{87}. The value of @code{Current_Task} when in a protected entry
7885 or interrupt handler. See C.7.1(17).
7888 Protected entries or interrupt handlers can be executed by any
7889 convenient thread, so the value of @code{Current_Task} is undefined.
7894 @strong{88}. The effect of calling @code{Current_Task} from an entry
7895 body or interrupt handler. See C.7.1(19).
7898 The effect of calling @code{Current_Task} from an entry body or
7899 interrupt handler is to return the identification of the task currently
7905 @strong{89}. Implementation-defined aspects of
7906 @code{Task_Attributes}. See C.7.2(19).
7909 There are no implementation-defined aspects of @code{Task_Attributes}.
7914 @strong{90}. Values of all @code{Metrics}. See D(2).
7917 The metrics information for GNAT depends on the performance of the
7918 underlying operating system. The sources of the run-time for tasking
7919 implementation, together with the output from @code{-gnatG} can be
7920 used to determine the exact sequence of operating systems calls made
7921 to implement various tasking constructs. Together with appropriate
7922 information on the performance of the underlying operating system,
7923 on the exact target in use, this information can be used to determine
7924 the required metrics.
7929 @strong{91}. The declarations of @code{Any_Priority} and
7930 @code{Priority}. See D.1(11).
7933 See declarations in file @file{system.ads}.
7938 @strong{92}. Implementation-defined execution resources. See D.1(15).
7941 There are no implementation-defined execution resources.
7946 @strong{93}. Whether, on a multiprocessor, a task that is waiting for
7947 access to a protected object keeps its processor busy. See D.2.1(3).
7950 On a multi-processor, a task that is waiting for access to a protected
7951 object does not keep its processor busy.
7956 @strong{94}. The affect of implementation defined execution resources
7957 on task dispatching. See D.2.1(9).
7962 Tasks map to IRIX threads, and the dispatching policy is as defined by
7963 the IRIX implementation of threads.
7965 Tasks map to threads in the threads package used by GNAT@. Where possible
7966 and appropriate, these threads correspond to native threads of the
7967 underlying operating system.
7972 @strong{95}. Implementation-defined @code{policy_identifiers} allowed
7973 in a pragma @code{Task_Dispatching_Policy}. See D.2.2(3).
7976 There are no implementation-defined policy-identifiers allowed in this
7982 @strong{96}. Implementation-defined aspects of priority inversion. See
7986 Execution of a task cannot be preempted by the implementation processing
7987 of delay expirations for lower priority tasks.
7992 @strong{97}. Implementation defined task dispatching. See D.2.2(18).
7997 Tasks map to IRIX threads, and the dispatching policy is as defied by
7998 the IRIX implementation of threads.
8000 The policy is the same as that of the underlying threads implementation.
8005 @strong{98}. Implementation-defined @code{policy_identifiers} allowed
8006 in a pragma @code{Locking_Policy}. See D.3(4).
8009 The only implementation defined policy permitted in GNAT is
8010 @code{Inheritance_Locking}. On targets that support this policy, locking
8011 is implemented by inheritance, i.e.@: the task owning the lock operates
8012 at a priority equal to the highest priority of any task currently
8013 requesting the lock.
8018 @strong{99}. Default ceiling priorities. See D.3(10).
8021 The ceiling priority of protected objects of the type
8022 @code{System.Interrupt_Priority'Last} as described in the Ada 95
8023 Reference Manual D.3(10),
8028 @strong{100}. The ceiling of any protected object used internally by
8029 the implementation. See D.3(16).
8032 The ceiling priority of internal protected objects is
8033 @code{System.Priority'Last}.
8038 @strong{101}. Implementation-defined queuing policies. See D.4(1).
8041 There are no implementation-defined queueing policies.
8046 @strong{102}. On a multiprocessor, any conditions that cause the
8047 completion of an aborted construct to be delayed later than what is
8048 specified for a single processor. See D.6(3).
8051 The semantics for abort on a multi-processor is the same as on a single
8052 processor, there are no further delays.
8057 @strong{103}. Any operations that implicitly require heap storage
8058 allocation. See D.7(8).
8061 The only operation that implicitly requires heap storage allocation is
8067 @strong{104}. Implementation-defined aspects of pragma
8068 @code{Restrictions}. See D.7(20).
8071 There are no such implementation-defined aspects.
8076 @strong{105}. Implementation-defined aspects of package
8077 @code{Real_Time}. See D.8(17).
8080 There are no implementation defined aspects of package @code{Real_Time}.
8085 @strong{106}. Implementation-defined aspects of
8086 @code{delay_statements}. See D.9(8).
8089 Any difference greater than one microsecond will cause the task to be
8090 delayed (see D.9(7)).
8095 @strong{107}. The upper bound on the duration of interrupt blocking
8096 caused by the implementation. See D.12(5).
8099 The upper bound is determined by the underlying operating system. In
8100 no cases is it more than 10 milliseconds.
8105 @strong{108}. The means for creating and executing distributed
8109 The GLADE package provides a utility GNATDIST for creating and executing
8110 distributed programs. See the GLADE reference manual for further details.
8115 @strong{109}. Any events that can result in a partition becoming
8116 inaccessible. See E.1(7).
8119 See the GLADE reference manual for full details on such events.
8124 @strong{110}. The scheduling policies, treatment of priorities, and
8125 management of shared resources between partitions in certain cases. See
8129 See the GLADE reference manual for full details on these aspects of
8130 multi-partition execution.
8135 @strong{111}. Events that cause the version of a compilation unit to
8139 Editing the source file of a compilation unit, or the source files of
8140 any units on which it is dependent in a significant way cause the version
8141 to change. No other actions cause the version number to change. All changes
8142 are significant except those which affect only layout, capitalization or
8148 @strong{112}. Whether the execution of the remote subprogram is
8149 immediately aborted as a result of cancellation. See E.4(13).
8152 See the GLADE reference manual for details on the effect of abort in
8153 a distributed application.
8158 @strong{113}. Implementation-defined aspects of the PCS@. See E.5(25).
8161 See the GLADE reference manual for a full description of all implementation
8162 defined aspects of the PCS@.
8167 @strong{114}. Implementation-defined interfaces in the PCS@. See
8171 See the GLADE reference manual for a full description of all
8172 implementation defined interfaces.
8177 @strong{115}. The values of named numbers in the package
8178 @code{Decimal}. See F.2(7).
8190 @item Max_Decimal_Digits
8197 @strong{116}. The value of @code{Max_Picture_Length} in the package
8198 @code{Text_IO.Editing}. See F.3.3(16).
8206 @strong{117}. The value of @code{Max_Picture_Length} in the package
8207 @code{Wide_Text_IO.Editing}. See F.3.4(5).
8215 @strong{118}. The accuracy actually achieved by the complex elementary
8216 functions and by other complex arithmetic operations. See G.1(1).
8219 Standard library functions are used for the complex arithmetic
8220 operations. Only fast math mode is currently supported.
8225 @strong{119}. The sign of a zero result (or a component thereof) from
8226 any operator or function in @code{Numerics.Generic_Complex_Types}, when
8227 @code{Real'Signed_Zeros} is True. See G.1.1(53).
8230 The signs of zero values are as recommended by the relevant
8231 implementation advice.
8236 @strong{120}. The sign of a zero result (or a component thereof) from
8237 any operator or function in
8238 @code{Numerics.Generic_Complex_Elementary_Functions}, when
8239 @code{Real'Signed_Zeros} is @code{True}. See G.1.2(45).
8242 The signs of zero values are as recommended by the relevant
8243 implementation advice.
8248 @strong{121}. Whether the strict mode or the relaxed mode is the
8249 default. See G.2(2).
8252 The strict mode is the default. There is no separate relaxed mode. GNAT
8253 provides a highly efficient implementation of strict mode.
8258 @strong{122}. The result interval in certain cases of fixed-to-float
8259 conversion. See G.2.1(10).
8262 For cases where the result interval is implementation dependent, the
8263 accuracy is that provided by performing all operations in 64-bit IEEE
8264 floating-point format.
8269 @strong{123}. The result of a floating point arithmetic operation in
8270 overflow situations, when the @code{Machine_Overflows} attribute of the
8271 result type is @code{False}. See G.2.1(13).
8274 Infinite and Nan values are produced as dictated by the IEEE
8275 floating-point standard.
8280 @strong{124}. The result interval for division (or exponentiation by a
8281 negative exponent), when the floating point hardware implements division
8282 as multiplication by a reciprocal. See G.2.1(16).
8285 Not relevant, division is IEEE exact.
8290 @strong{125}. The definition of close result set, which determines the
8291 accuracy of certain fixed point multiplications and divisions. See
8295 Operations in the close result set are performed using IEEE long format
8296 floating-point arithmetic. The input operands are converted to
8297 floating-point, the operation is done in floating-point, and the result
8298 is converted to the target type.
8303 @strong{126}. Conditions on a @code{universal_real} operand of a fixed
8304 point multiplication or division for which the result shall be in the
8305 perfect result set. See G.2.3(22).
8308 The result is only defined to be in the perfect result set if the result
8309 can be computed by a single scaling operation involving a scale factor
8310 representable in 64-bits.
8315 @strong{127}. The result of a fixed point arithmetic operation in
8316 overflow situations, when the @code{Machine_Overflows} attribute of the
8317 result type is @code{False}. See G.2.3(27).
8320 Not relevant, @code{Machine_Overflows} is @code{True} for fixed-point
8326 @strong{128}. The result of an elementary function reference in
8327 overflow situations, when the @code{Machine_Overflows} attribute of the
8328 result type is @code{False}. See G.2.4(4).
8331 IEEE infinite and Nan values are produced as appropriate.
8336 @strong{129}. The value of the angle threshold, within which certain
8337 elementary functions, complex arithmetic operations, and complex
8338 elementary functions yield results conforming to a maximum relative
8339 error bound. See G.2.4(10).
8342 Information on this subject is not yet available.
8347 @strong{130}. The accuracy of certain elementary functions for
8348 parameters beyond the angle threshold. See G.2.4(10).
8351 Information on this subject is not yet available.
8356 @strong{131}. The result of a complex arithmetic operation or complex
8357 elementary function reference in overflow situations, when the
8358 @code{Machine_Overflows} attribute of the corresponding real type is
8359 @code{False}. See G.2.6(5).
8362 IEEE infinite and Nan values are produced as appropriate.
8367 @strong{132}. The accuracy of certain complex arithmetic operations and
8368 certain complex elementary functions for parameters (or components
8369 thereof) beyond the angle threshold. See G.2.6(8).
8372 Information on those subjects is not yet available.
8377 @strong{133}. Information regarding bounded errors and erroneous
8378 execution. See H.2(1).
8381 Information on this subject is not yet available.
8386 @strong{134}. Implementation-defined aspects of pragma
8387 @code{Inspection_Point}. See H.3.2(8).
8390 Pragma @code{Inspection_Point} ensures that the variable is live and can
8391 be examined by the debugger at the inspection point.
8396 @strong{135}. Implementation-defined aspects of pragma
8397 @code{Restrictions}. See H.4(25).
8400 There are no implementation-defined aspects of pragma @code{Restrictions}. The
8401 use of pragma @code{Restrictions [No_Exceptions]} has no effect on the
8402 generated code. Checks must suppressed by use of pragma @code{Suppress}.
8407 @strong{136}. Any restrictions on pragma @code{Restrictions}. See
8411 There are no restrictions on pragma @code{Restrictions}.
8413 @node Intrinsic Subprograms
8414 @chapter Intrinsic Subprograms
8415 @cindex Intrinsic Subprograms
8418 * Intrinsic Operators::
8419 * Enclosing_Entity::
8420 * Exception_Information::
8421 * Exception_Message::
8429 * Shift_Right_Arithmetic::
8434 GNAT allows a user application program to write the declaration:
8436 @smallexample @c ada
8437 pragma Import (Intrinsic, name);
8441 providing that the name corresponds to one of the implemented intrinsic
8442 subprograms in GNAT, and that the parameter profile of the referenced
8443 subprogram meets the requirements. This chapter describes the set of
8444 implemented intrinsic subprograms, and the requirements on parameter profiles.
8445 Note that no body is supplied; as with other uses of pragma Import, the
8446 body is supplied elsewhere (in this case by the compiler itself). Note
8447 that any use of this feature is potentially non-portable, since the
8448 Ada standard does not require Ada compilers to implement this feature.
8450 @node Intrinsic Operators
8451 @section Intrinsic Operators
8452 @cindex Intrinsic operator
8455 All the predefined numeric operators in package Standard
8456 in @code{pragma Import (Intrinsic,..)}
8457 declarations. In the binary operator case, the operands must have the same
8458 size. The operand or operands must also be appropriate for
8459 the operator. For example, for addition, the operands must
8460 both be floating-point or both be fixed-point, and the
8461 right operand for @code{"**"} must have a root type of
8462 @code{Standard.Integer'Base}.
8463 You can use an intrinsic operator declaration as in the following example:
8465 @smallexample @c ada
8466 type Int1 is new Integer;
8467 type Int2 is new Integer;
8469 function "+" (X1 : Int1; X2 : Int2) return Int1;
8470 function "+" (X1 : Int1; X2 : Int2) return Int2;
8471 pragma Import (Intrinsic, "+");
8475 This declaration would permit ``mixed mode'' arithmetic on items
8476 of the differing types @code{Int1} and @code{Int2}.
8477 It is also possible to specify such operators for private types, if the
8478 full views are appropriate arithmetic types.
8480 @node Enclosing_Entity
8481 @section Enclosing_Entity
8482 @cindex Enclosing_Entity
8484 This intrinsic subprogram is used in the implementation of the
8485 library routine @code{GNAT.Source_Info}. The only useful use of the
8486 intrinsic import in this case is the one in this unit, so an
8487 application program should simply call the function
8488 @code{GNAT.Source_Info.Enclosing_Entity} to obtain the name of
8489 the current subprogram, package, task, entry, or protected subprogram.
8491 @node Exception_Information
8492 @section Exception_Information
8493 @cindex Exception_Information'
8495 This intrinsic subprogram is used in the implementation of the
8496 library routine @code{GNAT.Current_Exception}. The only useful
8497 use of the intrinsic import in this case is the one in this unit,
8498 so an application program should simply call the function
8499 @code{GNAT.Current_Exception.Exception_Information} to obtain
8500 the exception information associated with the current exception.
8502 @node Exception_Message
8503 @section Exception_Message
8504 @cindex Exception_Message
8506 This intrinsic subprogram is used in the implementation of the
8507 library routine @code{GNAT.Current_Exception}. The only useful
8508 use of the intrinsic import in this case is the one in this unit,
8509 so an application program should simply call the function
8510 @code{GNAT.Current_Exception.Exception_Message} to obtain
8511 the message associated with the current exception.
8513 @node Exception_Name
8514 @section Exception_Name
8515 @cindex Exception_Name
8517 This intrinsic subprogram is used in the implementation of the
8518 library routine @code{GNAT.Current_Exception}. The only useful
8519 use of the intrinsic import in this case is the one in this unit,
8520 so an application program should simply call the function
8521 @code{GNAT.Current_Exception.Exception_Name} to obtain
8522 the name of the current exception.
8528 This intrinsic subprogram is used in the implementation of the
8529 library routine @code{GNAT.Source_Info}. The only useful use of the
8530 intrinsic import in this case is the one in this unit, so an
8531 application program should simply call the function
8532 @code{GNAT.Source_Info.File} to obtain the name of the current
8539 This intrinsic subprogram is used in the implementation of the
8540 library routine @code{GNAT.Source_Info}. The only useful use of the
8541 intrinsic import in this case is the one in this unit, so an
8542 application program should simply call the function
8543 @code{GNAT.Source_Info.Line} to obtain the number of the current
8547 @section Rotate_Left
8550 In standard Ada 95, the @code{Rotate_Left} function is available only
8551 for the predefined modular types in package @code{Interfaces}. However, in
8552 GNAT it is possible to define a Rotate_Left function for a user
8553 defined modular type or any signed integer type as in this example:
8555 @smallexample @c ada
8557 (Value : My_Modular_Type;
8559 return My_Modular_Type;
8563 The requirements are that the profile be exactly as in the example
8564 above. The only modifications allowed are in the formal parameter
8565 names, and in the type of @code{Value} and the return type, which
8566 must be the same, and must be either a signed integer type, or
8567 a modular integer type with a binary modulus, and the size must
8568 be 8. 16, 32 or 64 bits.
8571 @section Rotate_Right
8572 @cindex Rotate_Right
8574 A @code{Rotate_Right} function can be defined for any user defined
8575 binary modular integer type, or signed integer type, as described
8576 above for @code{Rotate_Left}.
8582 A @code{Shift_Left} function can be defined for any user defined
8583 binary modular integer type, or signed integer type, as described
8584 above for @code{Rotate_Left}.
8587 @section Shift_Right
8590 A @code{Shift_Right} function can be defined for any user defined
8591 binary modular integer type, or signed integer type, as described
8592 above for @code{Rotate_Left}.
8594 @node Shift_Right_Arithmetic
8595 @section Shift_Right_Arithmetic
8596 @cindex Shift_Right_Arithmetic
8598 A @code{Shift_Right_Arithmetic} function can be defined for any user
8599 defined binary modular integer type, or signed integer type, as described
8600 above for @code{Rotate_Left}.
8602 @node Source_Location
8603 @section Source_Location
8604 @cindex Source_Location
8606 This intrinsic subprogram is used in the implementation of the
8607 library routine @code{GNAT.Source_Info}. The only useful use of the
8608 intrinsic import in this case is the one in this unit, so an
8609 application program should simply call the function
8610 @code{GNAT.Source_Info.Source_Location} to obtain the current
8611 source file location.
8613 @node Representation Clauses and Pragmas
8614 @chapter Representation Clauses and Pragmas
8615 @cindex Representation Clauses
8618 * Alignment Clauses::
8620 * Storage_Size Clauses::
8621 * Size of Variant Record Objects::
8622 * Biased Representation ::
8623 * Value_Size and Object_Size Clauses::
8624 * Component_Size Clauses::
8625 * Bit_Order Clauses::
8626 * Effect of Bit_Order on Byte Ordering::
8627 * Pragma Pack for Arrays::
8628 * Pragma Pack for Records::
8629 * Record Representation Clauses::
8630 * Enumeration Clauses::
8632 * Effect of Convention on Representation::
8633 * Determining the Representations chosen by GNAT::
8637 @cindex Representation Clause
8638 @cindex Representation Pragma
8639 @cindex Pragma, representation
8640 This section describes the representation clauses accepted by GNAT, and
8641 their effect on the representation of corresponding data objects.
8643 GNAT fully implements Annex C (Systems Programming). This means that all
8644 the implementation advice sections in chapter 13 are fully implemented.
8645 However, these sections only require a minimal level of support for
8646 representation clauses. GNAT provides much more extensive capabilities,
8647 and this section describes the additional capabilities provided.
8649 @node Alignment Clauses
8650 @section Alignment Clauses
8651 @cindex Alignment Clause
8654 GNAT requires that all alignment clauses specify a power of 2, and all
8655 default alignments are always a power of 2. The default alignment
8656 values are as follows:
8659 @item @emph{Primitive Types}.
8660 For primitive types, the alignment is the minimum of the actual size of
8661 objects of the type divided by @code{Storage_Unit},
8662 and the maximum alignment supported by the target.
8663 (This maximum alignment is given by the GNAT-specific attribute
8664 @code{Standard'Maximum_Alignment}; see @ref{Maximum_Alignment}.)
8665 @cindex @code{Maximum_Alignment} attribute
8666 For example, for type @code{Long_Float}, the object size is 8 bytes, and the
8667 default alignment will be 8 on any target that supports alignments
8668 this large, but on some targets, the maximum alignment may be smaller
8669 than 8, in which case objects of type @code{Long_Float} will be maximally
8672 @item @emph{Arrays}.
8673 For arrays, the alignment is equal to the alignment of the component type
8674 for the normal case where no packing or component size is given. If the
8675 array is packed, and the packing is effective (see separate section on
8676 packed arrays), then the alignment will be one for long packed arrays,
8677 or arrays whose length is not known at compile time. For short packed
8678 arrays, which are handled internally as modular types, the alignment
8679 will be as described for primitive types, e.g.@: a packed array of length
8680 31 bits will have an object size of four bytes, and an alignment of 4.
8682 @item @emph{Records}.
8683 For the normal non-packed case, the alignment of a record is equal to
8684 the maximum alignment of any of its components. For tagged records, this
8685 includes the implicit access type used for the tag. If a pragma @code{Pack} is
8686 used and all fields are packable (see separate section on pragma @code{Pack}),
8687 then the resulting alignment is 1.
8689 A special case is when:
8692 the size of the record is given explicitly, or a
8693 full record representation clause is given, and
8695 the size of the record is 2, 4, or 8 bytes.
8698 In this case, an alignment is chosen to match the
8699 size of the record. For example, if we have:
8701 @smallexample @c ada
8702 type Small is record
8705 for Small'Size use 16;
8709 then the default alignment of the record type @code{Small} is 2, not 1. This
8710 leads to more efficient code when the record is treated as a unit, and also
8711 allows the type to specified as @code{Atomic} on architectures requiring
8717 An alignment clause may
8718 always specify a larger alignment than the default value, up to some
8719 maximum value dependent on the target (obtainable by using the
8720 attribute reference @code{Standard'Maximum_Alignment}).
8722 it is permissible to specify a smaller alignment than the default value
8723 is for a record with a record representation clause.
8724 In this case, packable fields for which a component clause is
8725 given still result in a default alignment corresponding to the original
8726 type, but this may be overridden, since these components in fact only
8727 require an alignment of one byte. For example, given
8729 @smallexample @c ada
8735 A at 0 range 0 .. 31;
8738 for V'alignment use 1;
8742 @cindex Alignment, default
8743 The default alignment for the type @code{V} is 4, as a result of the
8744 Integer field in the record, but since this field is placed with a
8745 component clause, it is permissible, as shown, to override the default
8746 alignment of the record with a smaller value.
8749 @section Size Clauses
8753 The default size for a type @code{T} is obtainable through the
8754 language-defined attribute @code{T'Size} and also through the
8755 equivalent GNAT-defined attribute @code{T'Value_Size}.
8756 For objects of type @code{T}, GNAT will generally increase the type size
8757 so that the object size (obtainable through the GNAT-defined attribute
8758 @code{T'Object_Size})
8759 is a multiple of @code{T'Alignment * Storage_Unit}.
8762 @smallexample @c ada
8763 type Smallint is range 1 .. 6;
8772 In this example, @code{Smallint'Size} = @code{Smallint'Value_Size} = 3,
8773 as specified by the RM rules,
8774 but objects of this type will have a size of 8
8775 (@code{Smallint'Object_Size} = 8),
8776 since objects by default occupy an integral number
8777 of storage units. On some targets, notably older
8778 versions of the Digital Alpha, the size of stand
8779 alone objects of this type may be 32, reflecting
8780 the inability of the hardware to do byte load/stores.
8782 Similarly, the size of type @code{Rec} is 40 bits
8783 (@code{Rec'Size} = @code{Rec'Value_Size} = 40), but
8784 the alignment is 4, so objects of this type will have
8785 their size increased to 64 bits so that it is a multiple
8786 of the alignment (in bits). This decision is
8787 in accordance with the specific Implementation Advice in RM 13.3(43):
8790 A @code{Size} clause should be supported for an object if the specified
8791 @code{Size} is at least as large as its subtype's @code{Size}, and corresponds
8792 to a size in storage elements that is a multiple of the object's
8793 @code{Alignment} (if the @code{Alignment} is nonzero).
8797 An explicit size clause may be used to override the default size by
8798 increasing it. For example, if we have:
8800 @smallexample @c ada
8801 type My_Boolean is new Boolean;
8802 for My_Boolean'Size use 32;
8806 then values of this type will always be 32 bits long. In the case of
8807 discrete types, the size can be increased up to 64 bits, with the effect
8808 that the entire specified field is used to hold the value, sign- or
8809 zero-extended as appropriate. If more than 64 bits is specified, then
8810 padding space is allocated after the value, and a warning is issued that
8811 there are unused bits.
8813 Similarly the size of records and arrays may be increased, and the effect
8814 is to add padding bits after the value. This also causes a warning message
8817 The largest Size value permitted in GNAT is 2**31@minus{}1. Since this is a
8818 Size in bits, this corresponds to an object of size 256 megabytes (minus
8819 one). This limitation is true on all targets. The reason for this
8820 limitation is that it improves the quality of the code in many cases
8821 if it is known that a Size value can be accommodated in an object of
8824 @node Storage_Size Clauses
8825 @section Storage_Size Clauses
8826 @cindex Storage_Size Clause
8829 For tasks, the @code{Storage_Size} clause specifies the amount of space
8830 to be allocated for the task stack. This cannot be extended, and if the
8831 stack is exhausted, then @code{Storage_Error} will be raised (if stack
8832 checking is enabled). Use a @code{Storage_Size} attribute definition clause,
8833 or a @code{Storage_Size} pragma in the task definition to set the
8834 appropriate required size. A useful technique is to include in every
8835 task definition a pragma of the form:
8837 @smallexample @c ada
8838 pragma Storage_Size (Default_Stack_Size);
8842 Then @code{Default_Stack_Size} can be defined in a global package, and
8843 modified as required. Any tasks requiring stack sizes different from the
8844 default can have an appropriate alternative reference in the pragma.
8846 For access types, the @code{Storage_Size} clause specifies the maximum
8847 space available for allocation of objects of the type. If this space is
8848 exceeded then @code{Storage_Error} will be raised by an allocation attempt.
8849 In the case where the access type is declared local to a subprogram, the
8850 use of a @code{Storage_Size} clause triggers automatic use of a special
8851 predefined storage pool (@code{System.Pool_Size}) that ensures that all
8852 space for the pool is automatically reclaimed on exit from the scope in
8853 which the type is declared.
8855 A special case recognized by the compiler is the specification of a
8856 @code{Storage_Size} of zero for an access type. This means that no
8857 items can be allocated from the pool, and this is recognized at compile
8858 time, and all the overhead normally associated with maintaining a fixed
8859 size storage pool is eliminated. Consider the following example:
8861 @smallexample @c ada
8863 type R is array (Natural) of Character;
8864 type P is access all R;
8865 for P'Storage_Size use 0;
8866 -- Above access type intended only for interfacing purposes
8870 procedure g (m : P);
8871 pragma Import (C, g);
8882 As indicated in this example, these dummy storage pools are often useful in
8883 connection with interfacing where no object will ever be allocated. If you
8884 compile the above example, you get the warning:
8887 p.adb:16:09: warning: allocation from empty storage pool
8888 p.adb:16:09: warning: Storage_Error will be raised at run time
8892 Of course in practice, there will not be any explicit allocators in the
8893 case of such an access declaration.
8895 @node Size of Variant Record Objects
8896 @section Size of Variant Record Objects
8897 @cindex Size, variant record objects
8898 @cindex Variant record objects, size
8901 In the case of variant record objects, there is a question whether Size gives
8902 information about a particular variant, or the maximum size required
8903 for any variant. Consider the following program
8905 @smallexample @c ada
8906 with Text_IO; use Text_IO;
8908 type R1 (A : Boolean := False) is record
8910 when True => X : Character;
8919 Put_Line (Integer'Image (V1'Size));
8920 Put_Line (Integer'Image (V2'Size));
8925 Here we are dealing with a variant record, where the True variant
8926 requires 16 bits, and the False variant requires 8 bits.
8927 In the above example, both V1 and V2 contain the False variant,
8928 which is only 8 bits long. However, the result of running the
8937 The reason for the difference here is that the discriminant value of
8938 V1 is fixed, and will always be False. It is not possible to assign
8939 a True variant value to V1, therefore 8 bits is sufficient. On the
8940 other hand, in the case of V2, the initial discriminant value is
8941 False (from the default), but it is possible to assign a True
8942 variant value to V2, therefore 16 bits must be allocated for V2
8943 in the general case, even fewer bits may be needed at any particular
8944 point during the program execution.
8946 As can be seen from the output of this program, the @code{'Size}
8947 attribute applied to such an object in GNAT gives the actual allocated
8948 size of the variable, which is the largest size of any of the variants.
8949 The Ada Reference Manual is not completely clear on what choice should
8950 be made here, but the GNAT behavior seems most consistent with the
8951 language in the RM@.
8953 In some cases, it may be desirable to obtain the size of the current
8954 variant, rather than the size of the largest variant. This can be
8955 achieved in GNAT by making use of the fact that in the case of a
8956 subprogram parameter, GNAT does indeed return the size of the current
8957 variant (because a subprogram has no way of knowing how much space
8958 is actually allocated for the actual).
8960 Consider the following modified version of the above program:
8962 @smallexample @c ada
8963 with Text_IO; use Text_IO;
8965 type R1 (A : Boolean := False) is record
8967 when True => X : Character;
8974 function Size (V : R1) return Integer is
8980 Put_Line (Integer'Image (V2'Size));
8981 Put_Line (Integer'IMage (Size (V2)));
8983 Put_Line (Integer'Image (V2'Size));
8984 Put_Line (Integer'IMage (Size (V2)));
8989 The output from this program is
8999 Here we see that while the @code{'Size} attribute always returns
9000 the maximum size, regardless of the current variant value, the
9001 @code{Size} function does indeed return the size of the current
9004 @node Biased Representation
9005 @section Biased Representation
9006 @cindex Size for biased representation
9007 @cindex Biased representation
9010 In the case of scalars with a range starting at other than zero, it is
9011 possible in some cases to specify a size smaller than the default minimum
9012 value, and in such cases, GNAT uses an unsigned biased representation,
9013 in which zero is used to represent the lower bound, and successive values
9014 represent successive values of the type.
9016 For example, suppose we have the declaration:
9018 @smallexample @c ada
9019 type Small is range -7 .. -4;
9020 for Small'Size use 2;
9024 Although the default size of type @code{Small} is 4, the @code{Size}
9025 clause is accepted by GNAT and results in the following representation
9029 -7 is represented as 2#00#
9030 -6 is represented as 2#01#
9031 -5 is represented as 2#10#
9032 -4 is represented as 2#11#
9036 Biased representation is only used if the specified @code{Size} clause
9037 cannot be accepted in any other manner. These reduced sizes that force
9038 biased representation can be used for all discrete types except for
9039 enumeration types for which a representation clause is given.
9041 @node Value_Size and Object_Size Clauses
9042 @section Value_Size and Object_Size Clauses
9045 @cindex Size, of objects
9048 In Ada 95, @code{T'Size} for a type @code{T} is the minimum number of bits
9049 required to hold values of type @code{T}. Although this interpretation was
9050 allowed in Ada 83, it was not required, and this requirement in practice
9051 can cause some significant difficulties. For example, in most Ada 83
9052 compilers, @code{Natural'Size} was 32. However, in Ada 95,
9053 @code{Natural'Size} is
9054 typically 31. This means that code may change in behavior when moving
9055 from Ada 83 to Ada 95. For example, consider:
9057 @smallexample @c ada
9064 at 0 range 0 .. Natural'Size - 1;
9065 at 0 range Natural'Size .. 2 * Natural'Size - 1;
9070 In the above code, since the typical size of @code{Natural} objects
9071 is 32 bits and @code{Natural'Size} is 31, the above code can cause
9072 unexpected inefficient packing in Ada 95, and in general there are
9073 cases where the fact that the object size can exceed the
9074 size of the type causes surprises.
9076 To help get around this problem GNAT provides two implementation
9077 defined attributes, @code{Value_Size} and @code{Object_Size}. When
9078 applied to a type, these attributes yield the size of the type
9079 (corresponding to the RM defined size attribute), and the size of
9080 objects of the type respectively.
9082 The @code{Object_Size} is used for determining the default size of
9083 objects and components. This size value can be referred to using the
9084 @code{Object_Size} attribute. The phrase ``is used'' here means that it is
9085 the basis of the determination of the size. The backend is free to
9086 pad this up if necessary for efficiency, e.g.@: an 8-bit stand-alone
9087 character might be stored in 32 bits on a machine with no efficient
9088 byte access instructions such as the Alpha.
9090 The default rules for the value of @code{Object_Size} for
9091 discrete types are as follows:
9095 The @code{Object_Size} for base subtypes reflect the natural hardware
9096 size in bits (run the compiler with @option{-gnatS} to find those values
9097 for numeric types). Enumeration types and fixed-point base subtypes have
9098 8, 16, 32 or 64 bits for this size, depending on the range of values
9102 The @code{Object_Size} of a subtype is the same as the
9103 @code{Object_Size} of
9104 the type from which it is obtained.
9107 The @code{Object_Size} of a derived base type is copied from the parent
9108 base type, and the @code{Object_Size} of a derived first subtype is copied
9109 from the parent first subtype.
9113 The @code{Value_Size} attribute
9114 is the (minimum) number of bits required to store a value
9116 This value is used to determine how tightly to pack
9117 records or arrays with components of this type, and also affects
9118 the semantics of unchecked conversion (unchecked conversions where
9119 the @code{Value_Size} values differ generate a warning, and are potentially
9122 The default rules for the value of @code{Value_Size} are as follows:
9126 The @code{Value_Size} for a base subtype is the minimum number of bits
9127 required to store all values of the type (including the sign bit
9128 only if negative values are possible).
9131 If a subtype statically matches the first subtype of a given type, then it has
9132 by default the same @code{Value_Size} as the first subtype. This is a
9133 consequence of RM 13.1(14) (``if two subtypes statically match,
9134 then their subtype-specific aspects are the same''.)
9137 All other subtypes have a @code{Value_Size} corresponding to the minimum
9138 number of bits required to store all values of the subtype. For
9139 dynamic bounds, it is assumed that the value can range down or up
9140 to the corresponding bound of the ancestor
9144 The RM defined attribute @code{Size} corresponds to the
9145 @code{Value_Size} attribute.
9147 The @code{Size} attribute may be defined for a first-named subtype. This sets
9148 the @code{Value_Size} of
9149 the first-named subtype to the given value, and the
9150 @code{Object_Size} of this first-named subtype to the given value padded up
9151 to an appropriate boundary. It is a consequence of the default rules
9152 above that this @code{Object_Size} will apply to all further subtypes. On the
9153 other hand, @code{Value_Size} is affected only for the first subtype, any
9154 dynamic subtypes obtained from it directly, and any statically matching
9155 subtypes. The @code{Value_Size} of any other static subtypes is not affected.
9157 @code{Value_Size} and
9158 @code{Object_Size} may be explicitly set for any subtype using
9159 an attribute definition clause. Note that the use of these attributes
9160 can cause the RM 13.1(14) rule to be violated. If two access types
9161 reference aliased objects whose subtypes have differing @code{Object_Size}
9162 values as a result of explicit attribute definition clauses, then it
9163 is erroneous to convert from one access subtype to the other.
9165 At the implementation level, Esize stores the Object_Size and the
9166 RM_Size field stores the @code{Value_Size} (and hence the value of the
9167 @code{Size} attribute,
9168 which, as noted above, is equivalent to @code{Value_Size}).
9170 To get a feel for the difference, consider the following examples (note
9171 that in each case the base is @code{Short_Short_Integer} with a size of 8):
9174 Object_Size Value_Size
9176 type x1 is range 0 .. 5; 8 3
9178 type x2 is range 0 .. 5;
9179 for x2'size use 12; 16 12
9181 subtype x3 is x2 range 0 .. 3; 16 2
9183 subtype x4 is x2'base range 0 .. 10; 8 4
9185 subtype x5 is x2 range 0 .. dynamic; 16 3*
9187 subtype x6 is x2'base range 0 .. dynamic; 8 3*
9192 Note: the entries marked ``3*'' are not actually specified by the Ada 95 RM,
9193 but it seems in the spirit of the RM rules to allocate the minimum number
9194 of bits (here 3, given the range for @code{x2})
9195 known to be large enough to hold the given range of values.
9197 So far, so good, but GNAT has to obey the RM rules, so the question is
9198 under what conditions must the RM @code{Size} be used.
9199 The following is a list
9200 of the occasions on which the RM @code{Size} must be used:
9204 Component size for packed arrays or records
9207 Value of the attribute @code{Size} for a type
9210 Warning about sizes not matching for unchecked conversion
9214 For record types, the @code{Object_Size} is always a multiple of the
9215 alignment of the type (this is true for all types). In some cases the
9216 @code{Value_Size} can be smaller. Consider:
9226 On a typical 32-bit architecture, the X component will be four bytes, and
9227 require four-byte alignment, and the Y component will be one byte. In this
9228 case @code{R'Value_Size} will be 40 (bits) since this is the minimum size
9229 required to store a value of this type, and for example, it is permissible
9230 to have a component of type R in an outer record whose component size is
9231 specified to be 48 bits. However, @code{R'Object_Size} will be 64 (bits),
9232 since it must be rounded up so that this value is a multiple of the
9233 alignment (4 bytes = 32 bits).
9236 For all other types, the @code{Object_Size}
9237 and Value_Size are the same (and equivalent to the RM attribute @code{Size}).
9238 Only @code{Size} may be specified for such types.
9240 @node Component_Size Clauses
9241 @section Component_Size Clauses
9242 @cindex Component_Size Clause
9245 Normally, the value specified in a component size clause must be consistent
9246 with the subtype of the array component with regard to size and alignment.
9247 In other words, the value specified must be at least equal to the size
9248 of this subtype, and must be a multiple of the alignment value.
9250 In addition, component size clauses are allowed which cause the array
9251 to be packed, by specifying a smaller value. The cases in which this
9252 is allowed are for component size values in the range 1 through 63. The value
9253 specified must not be smaller than the Size of the subtype. GNAT will
9254 accurately honor all packing requests in this range. For example, if
9257 @smallexample @c ada
9258 type r is array (1 .. 8) of Natural;
9259 for r'Component_Size use 31;
9263 then the resulting array has a length of 31 bytes (248 bits = 8 * 31).
9264 Of course access to the components of such an array is considerably
9265 less efficient than if the natural component size of 32 is used.
9267 Note that there is no point in giving both a component size clause
9268 and a pragma Pack for the same array type. if such duplicate
9269 clauses are given, the pragma Pack will be ignored.
9271 @node Bit_Order Clauses
9272 @section Bit_Order Clauses
9273 @cindex Bit_Order Clause
9274 @cindex bit ordering
9275 @cindex ordering, of bits
9278 For record subtypes, GNAT permits the specification of the @code{Bit_Order}
9279 attribute. The specification may either correspond to the default bit
9280 order for the target, in which case the specification has no effect and
9281 places no additional restrictions, or it may be for the non-standard
9282 setting (that is the opposite of the default).
9284 In the case where the non-standard value is specified, the effect is
9285 to renumber bits within each byte, but the ordering of bytes is not
9286 affected. There are certain
9287 restrictions placed on component clauses as follows:
9291 @item Components fitting within a single storage unit.
9293 These are unrestricted, and the effect is merely to renumber bits. For
9294 example if we are on a little-endian machine with @code{Low_Order_First}
9295 being the default, then the following two declarations have exactly
9298 @smallexample @c ada
9301 B : Integer range 1 .. 120;
9305 A at 0 range 0 .. 0;
9306 B at 0 range 1 .. 7;
9311 B : Integer range 1 .. 120;
9314 for R2'Bit_Order use High_Order_First;
9317 A at 0 range 7 .. 7;
9318 B at 0 range 0 .. 6;
9323 The useful application here is to write the second declaration with the
9324 @code{Bit_Order} attribute definition clause, and know that it will be treated
9325 the same, regardless of whether the target is little-endian or big-endian.
9327 @item Components occupying an integral number of bytes.
9329 These are components that exactly fit in two or more bytes. Such component
9330 declarations are allowed, but have no effect, since it is important to realize
9331 that the @code{Bit_Order} specification does not affect the ordering of bytes.
9332 In particular, the following attempt at getting an endian-independent integer
9335 @smallexample @c ada
9340 for R2'Bit_Order use High_Order_First;
9343 A at 0 range 0 .. 31;
9348 This declaration will result in a little-endian integer on a
9349 little-endian machine, and a big-endian integer on a big-endian machine.
9350 If byte flipping is required for interoperability between big- and
9351 little-endian machines, this must be explicitly programmed. This capability
9352 is not provided by @code{Bit_Order}.
9354 @item Components that are positioned across byte boundaries
9356 but do not occupy an integral number of bytes. Given that bytes are not
9357 reordered, such fields would occupy a non-contiguous sequence of bits
9358 in memory, requiring non-trivial code to reassemble. They are for this
9359 reason not permitted, and any component clause specifying such a layout
9360 will be flagged as illegal by GNAT@.
9365 Since the misconception that Bit_Order automatically deals with all
9366 endian-related incompatibilities is a common one, the specification of
9367 a component field that is an integral number of bytes will always
9368 generate a warning. This warning may be suppressed using
9369 @code{pragma Suppress} if desired. The following section contains additional
9370 details regarding the issue of byte ordering.
9372 @node Effect of Bit_Order on Byte Ordering
9373 @section Effect of Bit_Order on Byte Ordering
9374 @cindex byte ordering
9375 @cindex ordering, of bytes
9378 In this section we will review the effect of the @code{Bit_Order} attribute
9379 definition clause on byte ordering. Briefly, it has no effect at all, but
9380 a detailed example will be helpful. Before giving this
9381 example, let us review the precise
9382 definition of the effect of defining @code{Bit_Order}. The effect of a
9383 non-standard bit order is described in section 15.5.3 of the Ada
9387 2 A bit ordering is a method of interpreting the meaning of
9388 the storage place attributes.
9392 To understand the precise definition of storage place attributes in
9393 this context, we visit section 13.5.1 of the manual:
9396 13 A record_representation_clause (without the mod_clause)
9397 specifies the layout. The storage place attributes (see 13.5.2)
9398 are taken from the values of the position, first_bit, and last_bit
9399 expressions after normalizing those values so that first_bit is
9400 less than Storage_Unit.
9404 The critical point here is that storage places are taken from
9405 the values after normalization, not before. So the @code{Bit_Order}
9406 interpretation applies to normalized values. The interpretation
9407 is described in the later part of the 15.5.3 paragraph:
9410 2 A bit ordering is a method of interpreting the meaning of
9411 the storage place attributes. High_Order_First (known in the
9412 vernacular as ``big endian'') means that the first bit of a
9413 storage element (bit 0) is the most significant bit (interpreting
9414 the sequence of bits that represent a component as an unsigned
9415 integer value). Low_Order_First (known in the vernacular as
9416 ``little endian'') means the opposite: the first bit is the
9421 Note that the numbering is with respect to the bits of a storage
9422 unit. In other words, the specification affects only the numbering
9423 of bits within a single storage unit.
9425 We can make the effect clearer by giving an example.
9427 Suppose that we have an external device which presents two bytes, the first
9428 byte presented, which is the first (low addressed byte) of the two byte
9429 record is called Master, and the second byte is called Slave.
9431 The left most (most significant bit is called Control for each byte, and
9432 the remaining 7 bits are called V1, V2, @dots{} V7, where V7 is the rightmost
9433 (least significant) bit.
9435 On a big-endian machine, we can write the following representation clause
9437 @smallexample @c ada
9439 Master_Control : Bit;
9447 Slave_Control : Bit;
9458 Master_Control at 0 range 0 .. 0;
9459 Master_V1 at 0 range 1 .. 1;
9460 Master_V2 at 0 range 2 .. 2;
9461 Master_V3 at 0 range 3 .. 3;
9462 Master_V4 at 0 range 4 .. 4;
9463 Master_V5 at 0 range 5 .. 5;
9464 Master_V6 at 0 range 6 .. 6;
9465 Master_V7 at 0 range 7 .. 7;
9466 Slave_Control at 1 range 0 .. 0;
9467 Slave_V1 at 1 range 1 .. 1;
9468 Slave_V2 at 1 range 2 .. 2;
9469 Slave_V3 at 1 range 3 .. 3;
9470 Slave_V4 at 1 range 4 .. 4;
9471 Slave_V5 at 1 range 5 .. 5;
9472 Slave_V6 at 1 range 6 .. 6;
9473 Slave_V7 at 1 range 7 .. 7;
9478 Now if we move this to a little endian machine, then the bit ordering within
9479 the byte is backwards, so we have to rewrite the record rep clause as:
9481 @smallexample @c ada
9483 Master_Control at 0 range 7 .. 7;
9484 Master_V1 at 0 range 6 .. 6;
9485 Master_V2 at 0 range 5 .. 5;
9486 Master_V3 at 0 range 4 .. 4;
9487 Master_V4 at 0 range 3 .. 3;
9488 Master_V5 at 0 range 2 .. 2;
9489 Master_V6 at 0 range 1 .. 1;
9490 Master_V7 at 0 range 0 .. 0;
9491 Slave_Control at 1 range 7 .. 7;
9492 Slave_V1 at 1 range 6 .. 6;
9493 Slave_V2 at 1 range 5 .. 5;
9494 Slave_V3 at 1 range 4 .. 4;
9495 Slave_V4 at 1 range 3 .. 3;
9496 Slave_V5 at 1 range 2 .. 2;
9497 Slave_V6 at 1 range 1 .. 1;
9498 Slave_V7 at 1 range 0 .. 0;
9503 It is a nuisance to have to rewrite the clause, especially if
9504 the code has to be maintained on both machines. However,
9505 this is a case that we can handle with the
9506 @code{Bit_Order} attribute if it is implemented.
9507 Note that the implementation is not required on byte addressed
9508 machines, but it is indeed implemented in GNAT.
9509 This means that we can simply use the
9510 first record clause, together with the declaration
9512 @smallexample @c ada
9513 for Data'Bit_Order use High_Order_First;
9517 and the effect is what is desired, namely the layout is exactly the same,
9518 independent of whether the code is compiled on a big-endian or little-endian
9521 The important point to understand is that byte ordering is not affected.
9522 A @code{Bit_Order} attribute definition never affects which byte a field
9523 ends up in, only where it ends up in that byte.
9524 To make this clear, let us rewrite the record rep clause of the previous
9527 @smallexample @c ada
9528 for Data'Bit_Order use High_Order_First;
9530 Master_Control at 0 range 0 .. 0;
9531 Master_V1 at 0 range 1 .. 1;
9532 Master_V2 at 0 range 2 .. 2;
9533 Master_V3 at 0 range 3 .. 3;
9534 Master_V4 at 0 range 4 .. 4;
9535 Master_V5 at 0 range 5 .. 5;
9536 Master_V6 at 0 range 6 .. 6;
9537 Master_V7 at 0 range 7 .. 7;
9538 Slave_Control at 0 range 8 .. 8;
9539 Slave_V1 at 0 range 9 .. 9;
9540 Slave_V2 at 0 range 10 .. 10;
9541 Slave_V3 at 0 range 11 .. 11;
9542 Slave_V4 at 0 range 12 .. 12;
9543 Slave_V5 at 0 range 13 .. 13;
9544 Slave_V6 at 0 range 14 .. 14;
9545 Slave_V7 at 0 range 15 .. 15;
9550 This is exactly equivalent to saying (a repeat of the first example):
9552 @smallexample @c ada
9553 for Data'Bit_Order use High_Order_First;
9555 Master_Control at 0 range 0 .. 0;
9556 Master_V1 at 0 range 1 .. 1;
9557 Master_V2 at 0 range 2 .. 2;
9558 Master_V3 at 0 range 3 .. 3;
9559 Master_V4 at 0 range 4 .. 4;
9560 Master_V5 at 0 range 5 .. 5;
9561 Master_V6 at 0 range 6 .. 6;
9562 Master_V7 at 0 range 7 .. 7;
9563 Slave_Control at 1 range 0 .. 0;
9564 Slave_V1 at 1 range 1 .. 1;
9565 Slave_V2 at 1 range 2 .. 2;
9566 Slave_V3 at 1 range 3 .. 3;
9567 Slave_V4 at 1 range 4 .. 4;
9568 Slave_V5 at 1 range 5 .. 5;
9569 Slave_V6 at 1 range 6 .. 6;
9570 Slave_V7 at 1 range 7 .. 7;
9575 Why are they equivalent? Well take a specific field, the @code{Slave_V2}
9576 field. The storage place attributes are obtained by normalizing the
9577 values given so that the @code{First_Bit} value is less than 8. After
9578 normalizing the values (0,10,10) we get (1,2,2) which is exactly what
9579 we specified in the other case.
9581 Now one might expect that the @code{Bit_Order} attribute might affect
9582 bit numbering within the entire record component (two bytes in this
9583 case, thus affecting which byte fields end up in), but that is not
9584 the way this feature is defined, it only affects numbering of bits,
9585 not which byte they end up in.
9587 Consequently it never makes sense to specify a starting bit number
9588 greater than 7 (for a byte addressable field) if an attribute
9589 definition for @code{Bit_Order} has been given, and indeed it
9590 may be actively confusing to specify such a value, so the compiler
9591 generates a warning for such usage.
9593 If you do need to control byte ordering then appropriate conditional
9594 values must be used. If in our example, the slave byte came first on
9595 some machines we might write:
9597 @smallexample @c ada
9598 Master_Byte_First constant Boolean := @dots{};
9600 Master_Byte : constant Natural :=
9601 1 - Boolean'Pos (Master_Byte_First);
9602 Slave_Byte : constant Natural :=
9603 Boolean'Pos (Master_Byte_First);
9605 for Data'Bit_Order use High_Order_First;
9607 Master_Control at Master_Byte range 0 .. 0;
9608 Master_V1 at Master_Byte range 1 .. 1;
9609 Master_V2 at Master_Byte range 2 .. 2;
9610 Master_V3 at Master_Byte range 3 .. 3;
9611 Master_V4 at Master_Byte range 4 .. 4;
9612 Master_V5 at Master_Byte range 5 .. 5;
9613 Master_V6 at Master_Byte range 6 .. 6;
9614 Master_V7 at Master_Byte range 7 .. 7;
9615 Slave_Control at Slave_Byte range 0 .. 0;
9616 Slave_V1 at Slave_Byte range 1 .. 1;
9617 Slave_V2 at Slave_Byte range 2 .. 2;
9618 Slave_V3 at Slave_Byte range 3 .. 3;
9619 Slave_V4 at Slave_Byte range 4 .. 4;
9620 Slave_V5 at Slave_Byte range 5 .. 5;
9621 Slave_V6 at Slave_Byte range 6 .. 6;
9622 Slave_V7 at Slave_Byte range 7 .. 7;
9627 Now to switch between machines, all that is necessary is
9628 to set the boolean constant @code{Master_Byte_First} in
9629 an appropriate manner.
9631 @node Pragma Pack for Arrays
9632 @section Pragma Pack for Arrays
9633 @cindex Pragma Pack (for arrays)
9636 Pragma @code{Pack} applied to an array has no effect unless the component type
9637 is packable. For a component type to be packable, it must be one of the
9644 Any type whose size is specified with a size clause
9646 Any packed array type with a static size
9650 For all these cases, if the component subtype size is in the range
9651 1 through 63, then the effect of the pragma @code{Pack} is exactly as though a
9652 component size were specified giving the component subtype size.
9653 For example if we have:
9655 @smallexample @c ada
9656 type r is range 0 .. 17;
9658 type ar is array (1 .. 8) of r;
9663 Then the component size of @code{ar} will be set to 5 (i.e.@: to @code{r'size},
9664 and the size of the array @code{ar} will be exactly 40 bits.
9666 Note that in some cases this rather fierce approach to packing can produce
9667 unexpected effects. For example, in Ada 95, type Natural typically has a
9668 size of 31, meaning that if you pack an array of Natural, you get 31-bit
9669 close packing, which saves a few bits, but results in far less efficient
9670 access. Since many other Ada compilers will ignore such a packing request,
9671 GNAT will generate a warning on some uses of pragma @code{Pack} that it guesses
9672 might not be what is intended. You can easily remove this warning by
9673 using an explicit @code{Component_Size} setting instead, which never generates
9674 a warning, since the intention of the programmer is clear in this case.
9676 GNAT treats packed arrays in one of two ways. If the size of the array is
9677 known at compile time and is less than 64 bits, then internally the array
9678 is represented as a single modular type, of exactly the appropriate number
9679 of bits. If the length is greater than 63 bits, or is not known at compile
9680 time, then the packed array is represented as an array of bytes, and the
9681 length is always a multiple of 8 bits.
9683 Note that to represent a packed array as a modular type, the alignment must
9684 be suitable for the modular type involved. For example, on typical machines
9685 a 32-bit packed array will be represented by a 32-bit modular integer with
9686 an alignment of four bytes. If you explicitly override the default alignment
9687 with an alignment clause that is too small, the modular representation
9688 cannot be used. For example, consider the following set of declarations:
9690 @smallexample @c ada
9691 type R is range 1 .. 3;
9692 type S is array (1 .. 31) of R;
9693 for S'Component_Size use 2;
9695 for S'Alignment use 1;
9699 If the alignment clause were not present, then a 62-bit modular
9700 representation would be chosen (typically with an alignment of 4 or 8
9701 bytes depending on the target). But the default alignment is overridden
9702 with the explicit alignment clause. This means that the modular
9703 representation cannot be used, and instead the array of bytes
9704 representation must be used, meaning that the length must be a multiple
9705 of 8. Thus the above set of declarations will result in a diagnostic
9706 rejecting the size clause and noting that the minimum size allowed is 64.
9708 @cindex Pragma Pack (for type Natural)
9709 @cindex Pragma Pack warning
9711 One special case that is worth noting occurs when the base type of the
9712 component size is 8/16/32 and the subtype is one bit less. Notably this
9713 occurs with subtype @code{Natural}. Consider:
9715 @smallexample @c ada
9716 type Arr is array (1 .. 32) of Natural;
9721 In all commonly used Ada 83 compilers, this pragma Pack would be ignored,
9722 since typically @code{Natural'Size} is 32 in Ada 83, and in any case most
9723 Ada 83 compilers did not attempt 31 bit packing.
9725 In Ada 95, @code{Natural'Size} is required to be 31. Furthermore, GNAT really
9726 does pack 31-bit subtype to 31 bits. This may result in a substantial
9727 unintended performance penalty when porting legacy Ada 83 code. To help
9728 prevent this, GNAT generates a warning in such cases. If you really want 31
9729 bit packing in a case like this, you can set the component size explicitly:
9731 @smallexample @c ada
9732 type Arr is array (1 .. 32) of Natural;
9733 for Arr'Component_Size use 31;
9737 Here 31-bit packing is achieved as required, and no warning is generated,
9738 since in this case the programmer intention is clear.
9740 @node Pragma Pack for Records
9741 @section Pragma Pack for Records
9742 @cindex Pragma Pack (for records)
9745 Pragma @code{Pack} applied to a record will pack the components to reduce
9746 wasted space from alignment gaps and by reducing the amount of space
9747 taken by components. We distinguish between @emph{packable} components and
9748 @emph{non-packable} components.
9749 Components of the following types are considered packable:
9752 All primitive types are packable.
9755 Small packed arrays, whose size does not exceed 64 bits, and where the
9756 size is statically known at compile time, are represented internally
9757 as modular integers, and so they are also packable.
9762 All packable components occupy the exact number of bits corresponding to
9763 their @code{Size} value, and are packed with no padding bits, i.e.@: they
9764 can start on an arbitrary bit boundary.
9766 All other types are non-packable, they occupy an integral number of
9768 are placed at a boundary corresponding to their alignment requirements.
9770 For example, consider the record
9772 @smallexample @c ada
9773 type Rb1 is array (1 .. 13) of Boolean;
9776 type Rb2 is array (1 .. 65) of Boolean;
9791 The representation for the record x2 is as follows:
9793 @smallexample @c ada
9794 for x2'Size use 224;
9796 l1 at 0 range 0 .. 0;
9797 l2 at 0 range 1 .. 64;
9798 l3 at 12 range 0 .. 31;
9799 l4 at 16 range 0 .. 0;
9800 l5 at 16 range 1 .. 13;
9801 l6 at 18 range 0 .. 71;
9806 Studying this example, we see that the packable fields @code{l1}
9808 of length equal to their sizes, and placed at specific bit boundaries (and
9809 not byte boundaries) to
9810 eliminate padding. But @code{l3} is of a non-packable float type, so
9811 it is on the next appropriate alignment boundary.
9813 The next two fields are fully packable, so @code{l4} and @code{l5} are
9814 minimally packed with no gaps. However, type @code{Rb2} is a packed
9815 array that is longer than 64 bits, so it is itself non-packable. Thus
9816 the @code{l6} field is aligned to the next byte boundary, and takes an
9817 integral number of bytes, i.e.@: 72 bits.
9819 @node Record Representation Clauses
9820 @section Record Representation Clauses
9821 @cindex Record Representation Clause
9824 Record representation clauses may be given for all record types, including
9825 types obtained by record extension. Component clauses are allowed for any
9826 static component. The restrictions on component clauses depend on the type
9829 @cindex Component Clause
9830 For all components of an elementary type, the only restriction on component
9831 clauses is that the size must be at least the 'Size value of the type
9832 (actually the Value_Size). There are no restrictions due to alignment,
9833 and such components may freely cross storage boundaries.
9835 Packed arrays with a size up to and including 64 bits are represented
9836 internally using a modular type with the appropriate number of bits, and
9837 thus the same lack of restriction applies. For example, if you declare:
9839 @smallexample @c ada
9840 type R is array (1 .. 49) of Boolean;
9846 then a component clause for a component of type R may start on any
9847 specified bit boundary, and may specify a value of 49 bits or greater.
9849 For packed bit arrays that are longer than 64 bits, there are two
9850 cases. If the component size is a power of 2 (1,2,4,8,16,32 bits),
9851 including the important case of single bits or boolean values, then
9852 there are no limitations on placement of such components, and they
9853 may start and end at arbitrary bit boundaries.
9855 If the component size is not a power of 2 (e.g. 3 or 5), then
9856 an array of this type longer than 64 bits must always be placed on
9857 on a storage unit (byte) boundary and occupy an integral number
9858 of storage units (bytes). Any component clause that does not
9859 meet this requirement will be rejected.
9861 Any aliased component, or component of an aliased type, must
9862 have its normal alignment and size. A component clause that
9863 does not meet this requirement will be rejected.
9865 The tag field of a tagged type always occupies an address sized field at
9866 the start of the record. No component clause may attempt to overlay this
9867 tag. When a tagged type appears as a component, the tag field must have
9870 In the case of a record extension T1, of a type T, no component clause applied
9871 to the type T1 can specify a storage location that would overlap the first
9872 T'Size bytes of the record.
9874 For all other component types, including non-bit-packed arrays,
9875 the component can be placed at an arbitrary bit boundary,
9876 so for example, the following is permitted:
9878 @smallexample @c ada
9879 type R is array (1 .. 10) of Boolean;
9888 G at 0 range 0 .. 0;
9889 H at 0 range 1 .. 1;
9890 L at 0 range 2 .. 81;
9891 R at 0 range 82 .. 161;
9896 Note: the above rules apply to recent releases of GNAT 5.
9897 In GNAT 3, there are more severe restrictions on larger components.
9898 For non-primitive types, including packed arrays with a size greater than
9899 64 bits, component clauses must respect the alignment requirement of the
9900 type, in particular, always starting on a byte boundary, and the length
9901 must be a multiple of the storage unit.
9903 @node Enumeration Clauses
9904 @section Enumeration Clauses
9906 The only restriction on enumeration clauses is that the range of values
9907 must be representable. For the signed case, if one or more of the
9908 representation values are negative, all values must be in the range:
9910 @smallexample @c ada
9911 System.Min_Int .. System.Max_Int
9915 For the unsigned case, where all values are non negative, the values must
9918 @smallexample @c ada
9919 0 .. System.Max_Binary_Modulus;
9923 A @emph{confirming} representation clause is one in which the values range
9924 from 0 in sequence, i.e.@: a clause that confirms the default representation
9925 for an enumeration type.
9926 Such a confirming representation
9927 is permitted by these rules, and is specially recognized by the compiler so
9928 that no extra overhead results from the use of such a clause.
9930 If an array has an index type which is an enumeration type to which an
9931 enumeration clause has been applied, then the array is stored in a compact
9932 manner. Consider the declarations:
9934 @smallexample @c ada
9935 type r is (A, B, C);
9936 for r use (A => 1, B => 5, C => 10);
9937 type t is array (r) of Character;
9941 The array type t corresponds to a vector with exactly three elements and
9942 has a default size equal to @code{3*Character'Size}. This ensures efficient
9943 use of space, but means that accesses to elements of the array will incur
9944 the overhead of converting representation values to the corresponding
9945 positional values, (i.e.@: the value delivered by the @code{Pos} attribute).
9947 @node Address Clauses
9948 @section Address Clauses
9949 @cindex Address Clause
9951 The reference manual allows a general restriction on representation clauses,
9952 as found in RM 13.1(22):
9955 An implementation need not support representation
9956 items containing nonstatic expressions, except that
9957 an implementation should support a representation item
9958 for a given entity if each nonstatic expression in the
9959 representation item is a name that statically denotes
9960 a constant declared before the entity.
9964 In practice this is applicable only to address clauses, since this is the
9965 only case in which a non-static expression is permitted by the syntax. As
9966 the AARM notes in sections 13.1 (22.a-22.h):
9969 22.a Reason: This is to avoid the following sort of thing:
9971 22.b X : Integer := F(@dots{});
9972 Y : Address := G(@dots{});
9973 for X'Address use Y;
9975 22.c In the above, we have to evaluate the
9976 initialization expression for X before we
9977 know where to put the result. This seems
9978 like an unreasonable implementation burden.
9980 22.d The above code should instead be written
9983 22.e Y : constant Address := G(@dots{});
9984 X : Integer := F(@dots{});
9985 for X'Address use Y;
9987 22.f This allows the expression ``Y'' to be safely
9988 evaluated before X is created.
9990 22.g The constant could be a formal parameter of mode in.
9992 22.h An implementation can support other nonstatic
9993 expressions if it wants to. Expressions of type
9994 Address are hardly ever static, but their value
9995 might be known at compile time anyway in many
10000 GNAT does indeed permit many additional cases of non-static expressions. In
10001 particular, if the type involved is elementary there are no restrictions
10002 (since in this case, holding a temporary copy of the initialization value,
10003 if one is present, is inexpensive). In addition, if there is no implicit or
10004 explicit initialization, then there are no restrictions. GNAT will reject
10005 only the case where all three of these conditions hold:
10010 The type of the item is non-elementary (e.g.@: a record or array).
10013 There is explicit or implicit initialization required for the object.
10014 Note that access values are always implicitly initialized, and also
10015 in GNAT, certain bit-packed arrays (those having a dynamic length or
10016 a length greater than 64) will also be implicitly initialized to zero.
10019 The address value is non-static. Here GNAT is more permissive than the
10020 RM, and allows the address value to be the address of a previously declared
10021 stand-alone variable, as long as it does not itself have an address clause.
10023 @smallexample @c ada
10024 Anchor : Some_Initialized_Type;
10025 Overlay : Some_Initialized_Type;
10026 for Overlay'Address use Anchor'Address;
10030 However, the prefix of the address clause cannot be an array component, or
10031 a component of a discriminated record.
10036 As noted above in section 22.h, address values are typically non-static. In
10037 particular the To_Address function, even if applied to a literal value, is
10038 a non-static function call. To avoid this minor annoyance, GNAT provides
10039 the implementation defined attribute 'To_Address. The following two
10040 expressions have identical values:
10044 @smallexample @c ada
10045 To_Address (16#1234_0000#)
10046 System'To_Address (16#1234_0000#);
10050 except that the second form is considered to be a static expression, and
10051 thus when used as an address clause value is always permitted.
10054 Additionally, GNAT treats as static an address clause that is an
10055 unchecked_conversion of a static integer value. This simplifies the porting
10056 of legacy code, and provides a portable equivalent to the GNAT attribute
10059 Another issue with address clauses is the interaction with alignment
10060 requirements. When an address clause is given for an object, the address
10061 value must be consistent with the alignment of the object (which is usually
10062 the same as the alignment of the type of the object). If an address clause
10063 is given that specifies an inappropriately aligned address value, then the
10064 program execution is erroneous.
10066 Since this source of erroneous behavior can have unfortunate effects, GNAT
10067 checks (at compile time if possible, generating a warning, or at execution
10068 time with a run-time check) that the alignment is appropriate. If the
10069 run-time check fails, then @code{Program_Error} is raised. This run-time
10070 check is suppressed if range checks are suppressed, or if
10071 @code{pragma Restrictions (No_Elaboration_Code)} is in effect.
10074 An address clause cannot be given for an exported object. More
10075 understandably the real restriction is that objects with an address
10076 clause cannot be exported. This is because such variables are not
10077 defined by the Ada program, so there is no external object to export.
10080 It is permissible to give an address clause and a pragma Import for the
10081 same object. In this case, the variable is not really defined by the
10082 Ada program, so there is no external symbol to be linked. The link name
10083 and the external name are ignored in this case. The reason that we allow this
10084 combination is that it provides a useful idiom to avoid unwanted
10085 initializations on objects with address clauses.
10087 When an address clause is given for an object that has implicit or
10088 explicit initialization, then by default initialization takes place. This
10089 means that the effect of the object declaration is to overwrite the
10090 memory at the specified address. This is almost always not what the
10091 programmer wants, so GNAT will output a warning:
10101 for Ext'Address use System'To_Address (16#1234_1234#);
10103 >>> warning: implicit initialization of "Ext" may
10104 modify overlaid storage
10105 >>> warning: use pragma Import for "Ext" to suppress
10106 initialization (RM B(24))
10112 As indicated by the warning message, the solution is to use a (dummy) pragma
10113 Import to suppress this initialization. The pragma tell the compiler that the
10114 object is declared and initialized elsewhere. The following package compiles
10115 without warnings (and the initialization is suppressed):
10117 @smallexample @c ada
10125 for Ext'Address use System'To_Address (16#1234_1234#);
10126 pragma Import (Ada, Ext);
10131 A final issue with address clauses involves their use for overlaying
10132 variables, as in the following example:
10133 @cindex Overlaying of objects
10135 @smallexample @c ada
10138 for B'Address use A'Address;
10142 or alternatively, using the form recommended by the RM:
10144 @smallexample @c ada
10146 Addr : constant Address := A'Address;
10148 for B'Address use Addr;
10152 In both of these cases, @code{A}
10153 and @code{B} become aliased to one another via the
10154 address clause. This use of address clauses to overlay
10155 variables, achieving an effect similar to unchecked
10156 conversion was erroneous in Ada 83, but in Ada 95
10157 the effect is implementation defined. Furthermore, the
10158 Ada 95 RM specifically recommends that in a situation
10159 like this, @code{B} should be subject to the following
10160 implementation advice (RM 13.3(19)):
10163 19 If the Address of an object is specified, or it is imported
10164 or exported, then the implementation should not perform
10165 optimizations based on assumptions of no aliases.
10169 GNAT follows this recommendation, and goes further by also applying
10170 this recommendation to the overlaid variable (@code{A}
10171 in the above example) in this case. This means that the overlay
10172 works "as expected", in that a modification to one of the variables
10173 will affect the value of the other.
10175 @node Effect of Convention on Representation
10176 @section Effect of Convention on Representation
10177 @cindex Convention, effect on representation
10180 Normally the specification of a foreign language convention for a type or
10181 an object has no effect on the chosen representation. In particular, the
10182 representation chosen for data in GNAT generally meets the standard system
10183 conventions, and for example records are laid out in a manner that is
10184 consistent with C@. This means that specifying convention C (for example)
10187 There are three exceptions to this general rule:
10191 @item Convention Fortran and array subtypes
10192 If pragma Convention Fortran is specified for an array subtype, then in
10193 accordance with the implementation advice in section 3.6.2(11) of the
10194 Ada Reference Manual, the array will be stored in a Fortran-compatible
10195 column-major manner, instead of the normal default row-major order.
10197 @item Convention C and enumeration types
10198 GNAT normally stores enumeration types in 8, 16, or 32 bits as required
10199 to accommodate all values of the type. For example, for the enumeration
10202 @smallexample @c ada
10203 type Color is (Red, Green, Blue);
10207 8 bits is sufficient to store all values of the type, so by default, objects
10208 of type @code{Color} will be represented using 8 bits. However, normal C
10209 convention is to use 32 bits for all enum values in C, since enum values
10210 are essentially of type int. If pragma @code{Convention C} is specified for an
10211 Ada enumeration type, then the size is modified as necessary (usually to
10212 32 bits) to be consistent with the C convention for enum values.
10214 @item Convention C/Fortran and Boolean types
10215 In C, the usual convention for boolean values, that is values used for
10216 conditions, is that zero represents false, and nonzero values represent
10217 true. In Ada, the normal convention is that two specific values, typically
10218 0/1, are used to represent false/true respectively.
10220 Fortran has a similar convention for @code{LOGICAL} values (any nonzero
10221 value represents true).
10223 To accommodate the Fortran and C conventions, if a pragma Convention specifies
10224 C or Fortran convention for a derived Boolean, as in the following example:
10226 @smallexample @c ada
10227 type C_Switch is new Boolean;
10228 pragma Convention (C, C_Switch);
10232 then the GNAT generated code will treat any nonzero value as true. For truth
10233 values generated by GNAT, the conventional value 1 will be used for True, but
10234 when one of these values is read, any nonzero value is treated as True.
10238 @node Determining the Representations chosen by GNAT
10239 @section Determining the Representations chosen by GNAT
10240 @cindex Representation, determination of
10241 @cindex @code{-gnatR} switch
10244 Although the descriptions in this section are intended to be complete, it is
10245 often easier to simply experiment to see what GNAT accepts and what the
10246 effect is on the layout of types and objects.
10248 As required by the Ada RM, if a representation clause is not accepted, then
10249 it must be rejected as illegal by the compiler. However, when a
10250 representation clause or pragma is accepted, there can still be questions
10251 of what the compiler actually does. For example, if a partial record
10252 representation clause specifies the location of some components and not
10253 others, then where are the non-specified components placed? Or if pragma
10254 @code{Pack} is used on a record, then exactly where are the resulting
10255 fields placed? The section on pragma @code{Pack} in this chapter can be
10256 used to answer the second question, but it is often easier to just see
10257 what the compiler does.
10259 For this purpose, GNAT provides the option @code{-gnatR}. If you compile
10260 with this option, then the compiler will output information on the actual
10261 representations chosen, in a format similar to source representation
10262 clauses. For example, if we compile the package:
10264 @smallexample @c ada
10266 type r (x : boolean) is tagged record
10268 when True => S : String (1 .. 100);
10269 when False => null;
10273 type r2 is new r (false) with record
10278 y2 at 16 range 0 .. 31;
10285 type x1 is array (1 .. 10) of x;
10286 for x1'component_size use 11;
10288 type ia is access integer;
10290 type Rb1 is array (1 .. 13) of Boolean;
10293 type Rb2 is array (1 .. 65) of Boolean;
10309 using the switch @code{-gnatR} we obtain the following output:
10312 Representation information for unit q
10313 -------------------------------------
10316 for r'Alignment use 4;
10318 x at 4 range 0 .. 7;
10319 _tag at 0 range 0 .. 31;
10320 s at 5 range 0 .. 799;
10323 for r2'Size use 160;
10324 for r2'Alignment use 4;
10326 x at 4 range 0 .. 7;
10327 _tag at 0 range 0 .. 31;
10328 _parent at 0 range 0 .. 63;
10329 y2 at 16 range 0 .. 31;
10333 for x'Alignment use 1;
10335 y at 0 range 0 .. 7;
10338 for x1'Size use 112;
10339 for x1'Alignment use 1;
10340 for x1'Component_Size use 11;
10342 for rb1'Size use 13;
10343 for rb1'Alignment use 2;
10344 for rb1'Component_Size use 1;
10346 for rb2'Size use 72;
10347 for rb2'Alignment use 1;
10348 for rb2'Component_Size use 1;
10350 for x2'Size use 224;
10351 for x2'Alignment use 4;
10353 l1 at 0 range 0 .. 0;
10354 l2 at 0 range 1 .. 64;
10355 l3 at 12 range 0 .. 31;
10356 l4 at 16 range 0 .. 0;
10357 l5 at 16 range 1 .. 13;
10358 l6 at 18 range 0 .. 71;
10363 The Size values are actually the Object_Size, i.e.@: the default size that
10364 will be allocated for objects of the type.
10365 The ?? size for type r indicates that we have a variant record, and the
10366 actual size of objects will depend on the discriminant value.
10368 The Alignment values show the actual alignment chosen by the compiler
10369 for each record or array type.
10371 The record representation clause for type r shows where all fields
10372 are placed, including the compiler generated tag field (whose location
10373 cannot be controlled by the programmer).
10375 The record representation clause for the type extension r2 shows all the
10376 fields present, including the parent field, which is a copy of the fields
10377 of the parent type of r2, i.e.@: r1.
10379 The component size and size clauses for types rb1 and rb2 show
10380 the exact effect of pragma @code{Pack} on these arrays, and the record
10381 representation clause for type x2 shows how pragma @code{Pack} affects
10384 In some cases, it may be useful to cut and paste the representation clauses
10385 generated by the compiler into the original source to fix and guarantee
10386 the actual representation to be used.
10388 @node Standard Library Routines
10389 @chapter Standard Library Routines
10392 The Ada 95 Reference Manual contains in Annex A a full description of an
10393 extensive set of standard library routines that can be used in any Ada
10394 program, and which must be provided by all Ada compilers. They are
10395 analogous to the standard C library used by C programs.
10397 GNAT implements all of the facilities described in annex A, and for most
10398 purposes the description in the Ada 95
10399 reference manual, or appropriate Ada
10400 text book, will be sufficient for making use of these facilities.
10402 In the case of the input-output facilities, @xref{The Implementation of
10403 Standard I/O}, gives details on exactly how GNAT interfaces to the
10404 file system. For the remaining packages, the Ada 95 reference manual
10405 should be sufficient. The following is a list of the packages included,
10406 together with a brief description of the functionality that is provided.
10408 For completeness, references are included to other predefined library
10409 routines defined in other sections of the Ada 95 reference manual (these are
10410 cross-indexed from annex A).
10414 This is a parent package for all the standard library packages. It is
10415 usually included implicitly in your program, and itself contains no
10416 useful data or routines.
10418 @item Ada.Calendar (9.6)
10419 @code{Calendar} provides time of day access, and routines for
10420 manipulating times and durations.
10422 @item Ada.Characters (A.3.1)
10423 This is a dummy parent package that contains no useful entities
10425 @item Ada.Characters.Handling (A.3.2)
10426 This package provides some basic character handling capabilities,
10427 including classification functions for classes of characters (e.g.@: test
10428 for letters, or digits).
10430 @item Ada.Characters.Latin_1 (A.3.3)
10431 This package includes a complete set of definitions of the characters
10432 that appear in type CHARACTER@. It is useful for writing programs that
10433 will run in international environments. For example, if you want an
10434 upper case E with an acute accent in a string, it is often better to use
10435 the definition of @code{UC_E_Acute} in this package. Then your program
10436 will print in an understandable manner even if your environment does not
10437 support these extended characters.
10439 @item Ada.Command_Line (A.15)
10440 This package provides access to the command line parameters and the name
10441 of the current program (analogous to the use of @code{argc} and @code{argv}
10442 in C), and also allows the exit status for the program to be set in a
10443 system-independent manner.
10445 @item Ada.Decimal (F.2)
10446 This package provides constants describing the range of decimal numbers
10447 implemented, and also a decimal divide routine (analogous to the COBOL
10448 verb DIVIDE .. GIVING .. REMAINDER ..)
10450 @item Ada.Direct_IO (A.8.4)
10451 This package provides input-output using a model of a set of records of
10452 fixed-length, containing an arbitrary definite Ada type, indexed by an
10453 integer record number.
10455 @item Ada.Dynamic_Priorities (D.5)
10456 This package allows the priorities of a task to be adjusted dynamically
10457 as the task is running.
10459 @item Ada.Exceptions (11.4.1)
10460 This package provides additional information on exceptions, and also
10461 contains facilities for treating exceptions as data objects, and raising
10462 exceptions with associated messages.
10464 @item Ada.Finalization (7.6)
10465 This package contains the declarations and subprograms to support the
10466 use of controlled types, providing for automatic initialization and
10467 finalization (analogous to the constructors and destructors of C++)
10469 @item Ada.Interrupts (C.3.2)
10470 This package provides facilities for interfacing to interrupts, which
10471 includes the set of signals or conditions that can be raised and
10472 recognized as interrupts.
10474 @item Ada.Interrupts.Names (C.3.2)
10475 This package provides the set of interrupt names (actually signal
10476 or condition names) that can be handled by GNAT@.
10478 @item Ada.IO_Exceptions (A.13)
10479 This package defines the set of exceptions that can be raised by use of
10480 the standard IO packages.
10483 This package contains some standard constants and exceptions used
10484 throughout the numerics packages. Note that the constants pi and e are
10485 defined here, and it is better to use these definitions than rolling
10488 @item Ada.Numerics.Complex_Elementary_Functions
10489 Provides the implementation of standard elementary functions (such as
10490 log and trigonometric functions) operating on complex numbers using the
10491 standard @code{Float} and the @code{Complex} and @code{Imaginary} types
10492 created by the package @code{Numerics.Complex_Types}.
10494 @item Ada.Numerics.Complex_Types
10495 This is a predefined instantiation of
10496 @code{Numerics.Generic_Complex_Types} using @code{Standard.Float} to
10497 build the type @code{Complex} and @code{Imaginary}.
10499 @item Ada.Numerics.Discrete_Random
10500 This package provides a random number generator suitable for generating
10501 random integer values from a specified range.
10503 @item Ada.Numerics.Float_Random
10504 This package provides a random number generator suitable for generating
10505 uniformly distributed floating point values.
10507 @item Ada.Numerics.Generic_Complex_Elementary_Functions
10508 This is a generic version of the package that provides the
10509 implementation of standard elementary functions (such as log and
10510 trigonometric functions) for an arbitrary complex type.
10512 The following predefined instantiations of this package are provided:
10516 @code{Ada.Numerics.Short_Complex_Elementary_Functions}
10518 @code{Ada.Numerics.Complex_Elementary_Functions}
10520 @code{Ada.Numerics.
10521 Long_Complex_Elementary_Functions}
10524 @item Ada.Numerics.Generic_Complex_Types
10525 This is a generic package that allows the creation of complex types,
10526 with associated complex arithmetic operations.
10528 The following predefined instantiations of this package exist
10531 @code{Ada.Numerics.Short_Complex_Complex_Types}
10533 @code{Ada.Numerics.Complex_Complex_Types}
10535 @code{Ada.Numerics.Long_Complex_Complex_Types}
10538 @item Ada.Numerics.Generic_Elementary_Functions
10539 This is a generic package that provides the implementation of standard
10540 elementary functions (such as log an trigonometric functions) for an
10541 arbitrary float type.
10543 The following predefined instantiations of this package exist
10547 @code{Ada.Numerics.Short_Elementary_Functions}
10549 @code{Ada.Numerics.Elementary_Functions}
10551 @code{Ada.Numerics.Long_Elementary_Functions}
10554 @item Ada.Real_Time (D.8)
10555 This package provides facilities similar to those of @code{Calendar}, but
10556 operating with a finer clock suitable for real time control. Note that
10557 annex D requires that there be no backward clock jumps, and GNAT generally
10558 guarantees this behavior, but of course if the external clock on which
10559 the GNAT runtime depends is deliberately reset by some external event,
10560 then such a backward jump may occur.
10562 @item Ada.Sequential_IO (A.8.1)
10563 This package provides input-output facilities for sequential files,
10564 which can contain a sequence of values of a single type, which can be
10565 any Ada type, including indefinite (unconstrained) types.
10567 @item Ada.Storage_IO (A.9)
10568 This package provides a facility for mapping arbitrary Ada types to and
10569 from a storage buffer. It is primarily intended for the creation of new
10572 @item Ada.Streams (13.13.1)
10573 This is a generic package that provides the basic support for the
10574 concept of streams as used by the stream attributes (@code{Input},
10575 @code{Output}, @code{Read} and @code{Write}).
10577 @item Ada.Streams.Stream_IO (A.12.1)
10578 This package is a specialization of the type @code{Streams} defined in
10579 package @code{Streams} together with a set of operations providing
10580 Stream_IO capability. The Stream_IO model permits both random and
10581 sequential access to a file which can contain an arbitrary set of values
10582 of one or more Ada types.
10584 @item Ada.Strings (A.4.1)
10585 This package provides some basic constants used by the string handling
10588 @item Ada.Strings.Bounded (A.4.4)
10589 This package provides facilities for handling variable length
10590 strings. The bounded model requires a maximum length. It is thus
10591 somewhat more limited than the unbounded model, but avoids the use of
10592 dynamic allocation or finalization.
10594 @item Ada.Strings.Fixed (A.4.3)
10595 This package provides facilities for handling fixed length strings.
10597 @item Ada.Strings.Maps (A.4.2)
10598 This package provides facilities for handling character mappings and
10599 arbitrarily defined subsets of characters. For instance it is useful in
10600 defining specialized translation tables.
10602 @item Ada.Strings.Maps.Constants (A.4.6)
10603 This package provides a standard set of predefined mappings and
10604 predefined character sets. For example, the standard upper to lower case
10605 conversion table is found in this package. Note that upper to lower case
10606 conversion is non-trivial if you want to take the entire set of
10607 characters, including extended characters like E with an acute accent,
10608 into account. You should use the mappings in this package (rather than
10609 adding 32 yourself) to do case mappings.
10611 @item Ada.Strings.Unbounded (A.4.5)
10612 This package provides facilities for handling variable length
10613 strings. The unbounded model allows arbitrary length strings, but
10614 requires the use of dynamic allocation and finalization.
10616 @item Ada.Strings.Wide_Bounded (A.4.7)
10617 @itemx Ada.Strings.Wide_Fixed (A.4.7)
10618 @itemx Ada.Strings.Wide_Maps (A.4.7)
10619 @itemx Ada.Strings.Wide_Maps.Constants (A.4.7)
10620 @itemx Ada.Strings.Wide_Unbounded (A.4.7)
10621 These packages provide analogous capabilities to the corresponding
10622 packages without @samp{Wide_} in the name, but operate with the types
10623 @code{Wide_String} and @code{Wide_Character} instead of @code{String}
10624 and @code{Character}.
10626 @item Ada.Strings.Wide_Wide_Bounded (A.4.7)
10627 @itemx Ada.Strings.Wide_Wide_Fixed (A.4.7)
10628 @itemx Ada.Strings.Wide_Wide_Maps (A.4.7)
10629 @itemx Ada.Strings.Wide_Wide_Maps.Constants (A.4.7)
10630 @itemx Ada.Strings.Wide_Wide_Unbounded (A.4.7)
10631 These packages provide analogous capabilities to the corresponding
10632 packages without @samp{Wide_} in the name, but operate with the types
10633 @code{Wide_Wide_String} and @code{Wide_Wide_Character} instead
10634 of @code{String} and @code{Character}.
10636 @item Ada.Synchronous_Task_Control (D.10)
10637 This package provides some standard facilities for controlling task
10638 communication in a synchronous manner.
10641 This package contains definitions for manipulation of the tags of tagged
10644 @item Ada.Task_Attributes
10645 This package provides the capability of associating arbitrary
10646 task-specific data with separate tasks.
10649 This package provides basic text input-output capabilities for
10650 character, string and numeric data. The subpackages of this
10651 package are listed next.
10653 @item Ada.Text_IO.Decimal_IO
10654 Provides input-output facilities for decimal fixed-point types
10656 @item Ada.Text_IO.Enumeration_IO
10657 Provides input-output facilities for enumeration types.
10659 @item Ada.Text_IO.Fixed_IO
10660 Provides input-output facilities for ordinary fixed-point types.
10662 @item Ada.Text_IO.Float_IO
10663 Provides input-output facilities for float types. The following
10664 predefined instantiations of this generic package are available:
10668 @code{Short_Float_Text_IO}
10670 @code{Float_Text_IO}
10672 @code{Long_Float_Text_IO}
10675 @item Ada.Text_IO.Integer_IO
10676 Provides input-output facilities for integer types. The following
10677 predefined instantiations of this generic package are available:
10680 @item Short_Short_Integer
10681 @code{Ada.Short_Short_Integer_Text_IO}
10682 @item Short_Integer
10683 @code{Ada.Short_Integer_Text_IO}
10685 @code{Ada.Integer_Text_IO}
10687 @code{Ada.Long_Integer_Text_IO}
10688 @item Long_Long_Integer
10689 @code{Ada.Long_Long_Integer_Text_IO}
10692 @item Ada.Text_IO.Modular_IO
10693 Provides input-output facilities for modular (unsigned) types
10695 @item Ada.Text_IO.Complex_IO (G.1.3)
10696 This package provides basic text input-output capabilities for complex
10699 @item Ada.Text_IO.Editing (F.3.3)
10700 This package contains routines for edited output, analogous to the use
10701 of pictures in COBOL@. The picture formats used by this package are a
10702 close copy of the facility in COBOL@.
10704 @item Ada.Text_IO.Text_Streams (A.12.2)
10705 This package provides a facility that allows Text_IO files to be treated
10706 as streams, so that the stream attributes can be used for writing
10707 arbitrary data, including binary data, to Text_IO files.
10709 @item Ada.Unchecked_Conversion (13.9)
10710 This generic package allows arbitrary conversion from one type to
10711 another of the same size, providing for breaking the type safety in
10712 special circumstances.
10714 If the types have the same Size (more accurately the same Value_Size),
10715 then the effect is simply to transfer the bits from the source to the
10716 target type without any modification. This usage is well defined, and
10717 for simple types whose representation is typically the same across
10718 all implementations, gives a portable method of performing such
10721 If the types do not have the same size, then the result is implementation
10722 defined, and thus may be non-portable. The following describes how GNAT
10723 handles such unchecked conversion cases.
10725 If the types are of different sizes, and are both discrete types, then
10726 the effect is of a normal type conversion without any constraint checking.
10727 In particular if the result type has a larger size, the result will be
10728 zero or sign extended. If the result type has a smaller size, the result
10729 will be truncated by ignoring high order bits.
10731 If the types are of different sizes, and are not both discrete types,
10732 then the conversion works as though pointers were created to the source
10733 and target, and the pointer value is converted. The effect is that bits
10734 are copied from successive low order storage units and bits of the source
10735 up to the length of the target type.
10737 A warning is issued if the lengths differ, since the effect in this
10738 case is implementation dependent, and the above behavior may not match
10739 that of some other compiler.
10741 A pointer to one type may be converted to a pointer to another type using
10742 unchecked conversion. The only case in which the effect is undefined is
10743 when one or both pointers are pointers to unconstrained array types. In
10744 this case, the bounds information may get incorrectly transferred, and in
10745 particular, GNAT uses double size pointers for such types, and it is
10746 meaningless to convert between such pointer types. GNAT will issue a
10747 warning if the alignment of the target designated type is more strict
10748 than the alignment of the source designated type (since the result may
10749 be unaligned in this case).
10751 A pointer other than a pointer to an unconstrained array type may be
10752 converted to and from System.Address. Such usage is common in Ada 83
10753 programs, but note that Ada.Address_To_Access_Conversions is the
10754 preferred method of performing such conversions in Ada 95. Neither
10755 unchecked conversion nor Ada.Address_To_Access_Conversions should be
10756 used in conjunction with pointers to unconstrained objects, since
10757 the bounds information cannot be handled correctly in this case.
10759 @item Ada.Unchecked_Deallocation (13.11.2)
10760 This generic package allows explicit freeing of storage previously
10761 allocated by use of an allocator.
10763 @item Ada.Wide_Text_IO (A.11)
10764 This package is similar to @code{Ada.Text_IO}, except that the external
10765 file supports wide character representations, and the internal types are
10766 @code{Wide_Character} and @code{Wide_String} instead of @code{Character}
10767 and @code{String}. It contains generic subpackages listed next.
10769 @item Ada.Wide_Text_IO.Decimal_IO
10770 Provides input-output facilities for decimal fixed-point types
10772 @item Ada.Wide_Text_IO.Enumeration_IO
10773 Provides input-output facilities for enumeration types.
10775 @item Ada.Wide_Text_IO.Fixed_IO
10776 Provides input-output facilities for ordinary fixed-point types.
10778 @item Ada.Wide_Text_IO.Float_IO
10779 Provides input-output facilities for float types. The following
10780 predefined instantiations of this generic package are available:
10784 @code{Short_Float_Wide_Text_IO}
10786 @code{Float_Wide_Text_IO}
10788 @code{Long_Float_Wide_Text_IO}
10791 @item Ada.Wide_Text_IO.Integer_IO
10792 Provides input-output facilities for integer types. The following
10793 predefined instantiations of this generic package are available:
10796 @item Short_Short_Integer
10797 @code{Ada.Short_Short_Integer_Wide_Text_IO}
10798 @item Short_Integer
10799 @code{Ada.Short_Integer_Wide_Text_IO}
10801 @code{Ada.Integer_Wide_Text_IO}
10803 @code{Ada.Long_Integer_Wide_Text_IO}
10804 @item Long_Long_Integer
10805 @code{Ada.Long_Long_Integer_Wide_Text_IO}
10808 @item Ada.Wide_Text_IO.Modular_IO
10809 Provides input-output facilities for modular (unsigned) types
10811 @item Ada.Wide_Text_IO.Complex_IO (G.1.3)
10812 This package is similar to @code{Ada.Text_IO.Complex_IO}, except that the
10813 external file supports wide character representations.
10815 @item Ada.Wide_Text_IO.Editing (F.3.4)
10816 This package is similar to @code{Ada.Text_IO.Editing}, except that the
10817 types are @code{Wide_Character} and @code{Wide_String} instead of
10818 @code{Character} and @code{String}.
10820 @item Ada.Wide_Text_IO.Streams (A.12.3)
10821 This package is similar to @code{Ada.Text_IO.Streams}, except that the
10822 types are @code{Wide_Character} and @code{Wide_String} instead of
10823 @code{Character} and @code{String}.
10825 @item Ada.Wide_Wide_Text_IO (A.11)
10826 This package is similar to @code{Ada.Text_IO}, except that the external
10827 file supports wide character representations, and the internal types are
10828 @code{Wide_Character} and @code{Wide_String} instead of @code{Character}
10829 and @code{String}. It contains generic subpackages listed next.
10831 @item Ada.Wide_Wide_Text_IO.Decimal_IO
10832 Provides input-output facilities for decimal fixed-point types
10834 @item Ada.Wide_Wide_Text_IO.Enumeration_IO
10835 Provides input-output facilities for enumeration types.
10837 @item Ada.Wide_Wide_Text_IO.Fixed_IO
10838 Provides input-output facilities for ordinary fixed-point types.
10840 @item Ada.Wide_Wide_Text_IO.Float_IO
10841 Provides input-output facilities for float types. The following
10842 predefined instantiations of this generic package are available:
10846 @code{Short_Float_Wide_Wide_Text_IO}
10848 @code{Float_Wide_Wide_Text_IO}
10850 @code{Long_Float_Wide_Wide_Text_IO}
10853 @item Ada.Wide_Wide_Text_IO.Integer_IO
10854 Provides input-output facilities for integer types. The following
10855 predefined instantiations of this generic package are available:
10858 @item Short_Short_Integer
10859 @code{Ada.Short_Short_Integer_Wide_Wide_Text_IO}
10860 @item Short_Integer
10861 @code{Ada.Short_Integer_Wide_Wide_Text_IO}
10863 @code{Ada.Integer_Wide_Wide_Text_IO}
10865 @code{Ada.Long_Integer_Wide_Wide_Text_IO}
10866 @item Long_Long_Integer
10867 @code{Ada.Long_Long_Integer_Wide_Wide_Text_IO}
10870 @item Ada.Wide_Wide_Text_IO.Modular_IO
10871 Provides input-output facilities for modular (unsigned) types
10873 @item Ada.Wide_Wide_Text_IO.Complex_IO (G.1.3)
10874 This package is similar to @code{Ada.Text_IO.Complex_IO}, except that the
10875 external file supports wide character representations.
10877 @item Ada.Wide_Wide_Text_IO.Editing (F.3.4)
10878 This package is similar to @code{Ada.Text_IO.Editing}, except that the
10879 types are @code{Wide_Character} and @code{Wide_String} instead of
10880 @code{Character} and @code{String}.
10882 @item Ada.Wide_Wide_Text_IO.Streams (A.12.3)
10883 This package is similar to @code{Ada.Text_IO.Streams}, except that the
10884 types are @code{Wide_Character} and @code{Wide_String} instead of
10885 @code{Character} and @code{String}.
10890 @node The Implementation of Standard I/O
10891 @chapter The Implementation of Standard I/O
10894 GNAT implements all the required input-output facilities described in
10895 A.6 through A.14. These sections of the Ada 95 reference manual describe the
10896 required behavior of these packages from the Ada point of view, and if
10897 you are writing a portable Ada program that does not need to know the
10898 exact manner in which Ada maps to the outside world when it comes to
10899 reading or writing external files, then you do not need to read this
10900 chapter. As long as your files are all regular files (not pipes or
10901 devices), and as long as you write and read the files only from Ada, the
10902 description in the Ada 95 reference manual is sufficient.
10904 However, if you want to do input-output to pipes or other devices, such
10905 as the keyboard or screen, or if the files you are dealing with are
10906 either generated by some other language, or to be read by some other
10907 language, then you need to know more about the details of how the GNAT
10908 implementation of these input-output facilities behaves.
10910 In this chapter we give a detailed description of exactly how GNAT
10911 interfaces to the file system. As always, the sources of the system are
10912 available to you for answering questions at an even more detailed level,
10913 but for most purposes the information in this chapter will suffice.
10915 Another reason that you may need to know more about how input-output is
10916 implemented arises when you have a program written in mixed languages
10917 where, for example, files are shared between the C and Ada sections of
10918 the same program. GNAT provides some additional facilities, in the form
10919 of additional child library packages, that facilitate this sharing, and
10920 these additional facilities are also described in this chapter.
10923 * Standard I/O Packages::
10929 * Wide_Wide_Text_IO::
10933 * Operations on C Streams::
10934 * Interfacing to C Streams::
10937 @node Standard I/O Packages
10938 @section Standard I/O Packages
10941 The Standard I/O packages described in Annex A for
10947 Ada.Text_IO.Complex_IO
10949 Ada.Text_IO.Text_Streams
10953 Ada.Wide_Text_IO.Complex_IO
10955 Ada.Wide_Text_IO.Text_Streams
10957 Ada.Wide_Wide_Text_IO
10959 Ada.Wide_Wide_Text_IO.Complex_IO
10961 Ada.Wide_Wide_Text_IO.Text_Streams
10971 are implemented using the C
10972 library streams facility; where
10976 All files are opened using @code{fopen}.
10978 All input/output operations use @code{fread}/@code{fwrite}.
10982 There is no internal buffering of any kind at the Ada library level. The
10983 only buffering is that provided at the system level in the
10984 implementation of the C library routines that support streams. This
10985 facilitates shared use of these streams by mixed language programs.
10988 @section FORM Strings
10991 The format of a FORM string in GNAT is:
10994 "keyword=value,keyword=value,@dots{},keyword=value"
10998 where letters may be in upper or lower case, and there are no spaces
10999 between values. The order of the entries is not important. Currently
11000 there are two keywords defined.
11008 The use of these parameters is described later in this section.
11014 Direct_IO can only be instantiated for definite types. This is a
11015 restriction of the Ada language, which means that the records are fixed
11016 length (the length being determined by @code{@var{type}'Size}, rounded
11017 up to the next storage unit boundary if necessary).
11019 The records of a Direct_IO file are simply written to the file in index
11020 sequence, with the first record starting at offset zero, and subsequent
11021 records following. There is no control information of any kind. For
11022 example, if 32-bit integers are being written, each record takes
11023 4-bytes, so the record at index @var{K} starts at offset
11024 (@var{K}@minus{}1)*4.
11026 There is no limit on the size of Direct_IO files, they are expanded as
11027 necessary to accommodate whatever records are written to the file.
11029 @node Sequential_IO
11030 @section Sequential_IO
11033 Sequential_IO may be instantiated with either a definite (constrained)
11034 or indefinite (unconstrained) type.
11036 For the definite type case, the elements written to the file are simply
11037 the memory images of the data values with no control information of any
11038 kind. The resulting file should be read using the same type, no validity
11039 checking is performed on input.
11041 For the indefinite type case, the elements written consist of two
11042 parts. First is the size of the data item, written as the memory image
11043 of a @code{Interfaces.C.size_t} value, followed by the memory image of
11044 the data value. The resulting file can only be read using the same
11045 (unconstrained) type. Normal assignment checks are performed on these
11046 read operations, and if these checks fail, @code{Data_Error} is
11047 raised. In particular, in the array case, the lengths must match, and in
11048 the variant record case, if the variable for a particular read operation
11049 is constrained, the discriminants must match.
11051 Note that it is not possible to use Sequential_IO to write variable
11052 length array items, and then read the data back into different length
11053 arrays. For example, the following will raise @code{Data_Error}:
11055 @smallexample @c ada
11056 package IO is new Sequential_IO (String);
11061 IO.Write (F, "hello!")
11062 IO.Reset (F, Mode=>In_File);
11069 On some Ada implementations, this will print @code{hell}, but the program is
11070 clearly incorrect, since there is only one element in the file, and that
11071 element is the string @code{hello!}.
11073 In Ada 95, this kind of behavior can be legitimately achieved using
11074 Stream_IO, and this is the preferred mechanism. In particular, the above
11075 program fragment rewritten to use Stream_IO will work correctly.
11081 Text_IO files consist of a stream of characters containing the following
11082 special control characters:
11085 LF (line feed, 16#0A#) Line Mark
11086 FF (form feed, 16#0C#) Page Mark
11090 A canonical Text_IO file is defined as one in which the following
11091 conditions are met:
11095 The character @code{LF} is used only as a line mark, i.e.@: to mark the end
11099 The character @code{FF} is used only as a page mark, i.e.@: to mark the
11100 end of a page and consequently can appear only immediately following a
11101 @code{LF} (line mark) character.
11104 The file ends with either @code{LF} (line mark) or @code{LF}-@code{FF}
11105 (line mark, page mark). In the former case, the page mark is implicitly
11106 assumed to be present.
11110 A file written using Text_IO will be in canonical form provided that no
11111 explicit @code{LF} or @code{FF} characters are written using @code{Put}
11112 or @code{Put_Line}. There will be no @code{FF} character at the end of
11113 the file unless an explicit @code{New_Page} operation was performed
11114 before closing the file.
11116 A canonical Text_IO file that is a regular file, i.e.@: not a device or a
11117 pipe, can be read using any of the routines in Text_IO@. The
11118 semantics in this case will be exactly as defined in the Ada 95 reference
11119 manual and all the routines in Text_IO are fully implemented.
11121 A text file that does not meet the requirements for a canonical Text_IO
11122 file has one of the following:
11126 The file contains @code{FF} characters not immediately following a
11127 @code{LF} character.
11130 The file contains @code{LF} or @code{FF} characters written by
11131 @code{Put} or @code{Put_Line}, which are not logically considered to be
11132 line marks or page marks.
11135 The file ends in a character other than @code{LF} or @code{FF},
11136 i.e.@: there is no explicit line mark or page mark at the end of the file.
11140 Text_IO can be used to read such non-standard text files but subprograms
11141 to do with line or page numbers do not have defined meanings. In
11142 particular, a @code{FF} character that does not follow a @code{LF}
11143 character may or may not be treated as a page mark from the point of
11144 view of page and line numbering. Every @code{LF} character is considered
11145 to end a line, and there is an implied @code{LF} character at the end of
11149 * Text_IO Stream Pointer Positioning::
11150 * Text_IO Reading and Writing Non-Regular Files::
11152 * Treating Text_IO Files as Streams::
11153 * Text_IO Extensions::
11154 * Text_IO Facilities for Unbounded Strings::
11157 @node Text_IO Stream Pointer Positioning
11158 @subsection Stream Pointer Positioning
11161 @code{Ada.Text_IO} has a definition of current position for a file that
11162 is being read. No internal buffering occurs in Text_IO, and usually the
11163 physical position in the stream used to implement the file corresponds
11164 to this logical position defined by Text_IO@. There are two exceptions:
11168 After a call to @code{End_Of_Page} that returns @code{True}, the stream
11169 is positioned past the @code{LF} (line mark) that precedes the page
11170 mark. Text_IO maintains an internal flag so that subsequent read
11171 operations properly handle the logical position which is unchanged by
11172 the @code{End_Of_Page} call.
11175 After a call to @code{End_Of_File} that returns @code{True}, if the
11176 Text_IO file was positioned before the line mark at the end of file
11177 before the call, then the logical position is unchanged, but the stream
11178 is physically positioned right at the end of file (past the line mark,
11179 and past a possible page mark following the line mark. Again Text_IO
11180 maintains internal flags so that subsequent read operations properly
11181 handle the logical position.
11185 These discrepancies have no effect on the observable behavior of
11186 Text_IO, but if a single Ada stream is shared between a C program and
11187 Ada program, or shared (using @samp{shared=yes} in the form string)
11188 between two Ada files, then the difference may be observable in some
11191 @node Text_IO Reading and Writing Non-Regular Files
11192 @subsection Reading and Writing Non-Regular Files
11195 A non-regular file is a device (such as a keyboard), or a pipe. Text_IO
11196 can be used for reading and writing. Writing is not affected and the
11197 sequence of characters output is identical to the normal file case, but
11198 for reading, the behavior of Text_IO is modified to avoid undesirable
11199 look-ahead as follows:
11201 An input file that is not a regular file is considered to have no page
11202 marks. Any @code{Ascii.FF} characters (the character normally used for a
11203 page mark) appearing in the file are considered to be data
11204 characters. In particular:
11208 @code{Get_Line} and @code{Skip_Line} do not test for a page mark
11209 following a line mark. If a page mark appears, it will be treated as a
11213 This avoids the need to wait for an extra character to be typed or
11214 entered from the pipe to complete one of these operations.
11217 @code{End_Of_Page} always returns @code{False}
11220 @code{End_Of_File} will return @code{False} if there is a page mark at
11221 the end of the file.
11225 Output to non-regular files is the same as for regular files. Page marks
11226 may be written to non-regular files using @code{New_Page}, but as noted
11227 above they will not be treated as page marks on input if the output is
11228 piped to another Ada program.
11230 Another important discrepancy when reading non-regular files is that the end
11231 of file indication is not ``sticky''. If an end of file is entered, e.g.@: by
11232 pressing the @key{EOT} key,
11234 is signaled once (i.e.@: the test @code{End_Of_File}
11235 will yield @code{True}, or a read will
11236 raise @code{End_Error}), but then reading can resume
11237 to read data past that end of
11238 file indication, until another end of file indication is entered.
11240 @node Get_Immediate
11241 @subsection Get_Immediate
11242 @cindex Get_Immediate
11245 Get_Immediate returns the next character (including control characters)
11246 from the input file. In particular, Get_Immediate will return LF or FF
11247 characters used as line marks or page marks. Such operations leave the
11248 file positioned past the control character, and it is thus not treated
11249 as having its normal function. This means that page, line and column
11250 counts after this kind of Get_Immediate call are set as though the mark
11251 did not occur. In the case where a Get_Immediate leaves the file
11252 positioned between the line mark and page mark (which is not normally
11253 possible), it is undefined whether the FF character will be treated as a
11256 @node Treating Text_IO Files as Streams
11257 @subsection Treating Text_IO Files as Streams
11258 @cindex Stream files
11261 The package @code{Text_IO.Streams} allows a Text_IO file to be treated
11262 as a stream. Data written to a Text_IO file in this stream mode is
11263 binary data. If this binary data contains bytes 16#0A# (@code{LF}) or
11264 16#0C# (@code{FF}), the resulting file may have non-standard
11265 format. Similarly if read operations are used to read from a Text_IO
11266 file treated as a stream, then @code{LF} and @code{FF} characters may be
11267 skipped and the effect is similar to that described above for
11268 @code{Get_Immediate}.
11270 @node Text_IO Extensions
11271 @subsection Text_IO Extensions
11272 @cindex Text_IO extensions
11275 A package GNAT.IO_Aux in the GNAT library provides some useful extensions
11276 to the standard @code{Text_IO} package:
11279 @item function File_Exists (Name : String) return Boolean;
11280 Determines if a file of the given name exists.
11282 @item function Get_Line return String;
11283 Reads a string from the standard input file. The value returned is exactly
11284 the length of the line that was read.
11286 @item function Get_Line (File : Ada.Text_IO.File_Type) return String;
11287 Similar, except that the parameter File specifies the file from which
11288 the string is to be read.
11292 @node Text_IO Facilities for Unbounded Strings
11293 @subsection Text_IO Facilities for Unbounded Strings
11294 @cindex Text_IO for unbounded strings
11295 @cindex Unbounded_String, Text_IO operations
11298 The package @code{Ada.Strings.Unbounded.Text_IO}
11299 in library files @code{a-suteio.ads/adb} contains some GNAT-specific
11300 subprograms useful for Text_IO operations on unbounded strings:
11304 @item function Get_Line (File : File_Type) return Unbounded_String;
11305 Reads a line from the specified file
11306 and returns the result as an unbounded string.
11308 @item procedure Put (File : File_Type; U : Unbounded_String);
11309 Writes the value of the given unbounded string to the specified file
11310 Similar to the effect of
11311 @code{Put (To_String (U))} except that an extra copy is avoided.
11313 @item procedure Put_Line (File : File_Type; U : Unbounded_String);
11314 Writes the value of the given unbounded string to the specified file,
11315 followed by a @code{New_Line}.
11316 Similar to the effect of @code{Put_Line (To_String (U))} except
11317 that an extra copy is avoided.
11321 In the above procedures, @code{File} is of type @code{Ada.Text_IO.File_Type}
11322 and is optional. If the parameter is omitted, then the standard input or
11323 output file is referenced as appropriate.
11325 The package @code{Ada.Strings.Wide_Unbounded.Wide_Text_IO} in library
11326 files @file{a-swuwti.ads} and @file{a-swuwti.adb} provides similar extended
11327 @code{Wide_Text_IO} functionality for unbounded wide strings.
11329 The package @code{Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO} in library
11330 files @file{a-szuzti.ads} and @file{a-szuzti.adb} provides similar extended
11331 @code{Wide_Wide_Text_IO} functionality for unbounded wide wide strings.
11334 @section Wide_Text_IO
11337 @code{Wide_Text_IO} is similar in most respects to Text_IO, except that
11338 both input and output files may contain special sequences that represent
11339 wide character values. The encoding scheme for a given file may be
11340 specified using a FORM parameter:
11347 as part of the FORM string (WCEM = wide character encoding method),
11348 where @var{x} is one of the following characters
11354 Upper half encoding
11366 The encoding methods match those that
11367 can be used in a source
11368 program, but there is no requirement that the encoding method used for
11369 the source program be the same as the encoding method used for files,
11370 and different files may use different encoding methods.
11372 The default encoding method for the standard files, and for opened files
11373 for which no WCEM parameter is given in the FORM string matches the
11374 wide character encoding specified for the main program (the default
11375 being brackets encoding if no coding method was specified with -gnatW).
11379 In this encoding, a wide character is represented by a five character
11387 where @var{a}, @var{b}, @var{c}, @var{d} are the four hexadecimal
11388 characters (using upper case letters) of the wide character code. For
11389 example, ESC A345 is used to represent the wide character with code
11390 16#A345#. This scheme is compatible with use of the full
11391 @code{Wide_Character} set.
11393 @item Upper Half Coding
11394 The wide character with encoding 16#abcd#, where the upper bit is on
11395 (i.e.@: a is in the range 8-F) is represented as two bytes 16#ab# and
11396 16#cd#. The second byte may never be a format control character, but is
11397 not required to be in the upper half. This method can be also used for
11398 shift-JIS or EUC where the internal coding matches the external coding.
11400 @item Shift JIS Coding
11401 A wide character is represented by a two character sequence 16#ab# and
11402 16#cd#, with the restrictions described for upper half encoding as
11403 described above. The internal character code is the corresponding JIS
11404 character according to the standard algorithm for Shift-JIS
11405 conversion. Only characters defined in the JIS code set table can be
11406 used with this encoding method.
11409 A wide character is represented by a two character sequence 16#ab# and
11410 16#cd#, with both characters being in the upper half. The internal
11411 character code is the corresponding JIS character according to the EUC
11412 encoding algorithm. Only characters defined in the JIS code set table
11413 can be used with this encoding method.
11416 A wide character is represented using
11417 UCS Transformation Format 8 (UTF-8) as defined in Annex R of ISO
11418 10646-1/Am.2. Depending on the character value, the representation
11419 is a one, two, or three byte sequence:
11422 16#0000#-16#007f#: 2#0xxxxxxx#
11423 16#0080#-16#07ff#: 2#110xxxxx# 2#10xxxxxx#
11424 16#0800#-16#ffff#: 2#1110xxxx# 2#10xxxxxx# 2#10xxxxxx#
11428 where the xxx bits correspond to the left-padded bits of the
11429 16-bit character value. Note that all lower half ASCII characters
11430 are represented as ASCII bytes and all upper half characters and
11431 other wide characters are represented as sequences of upper-half
11432 (The full UTF-8 scheme allows for encoding 31-bit characters as
11433 6-byte sequences, but in this implementation, all UTF-8 sequences
11434 of four or more bytes length will raise a Constraint_Error, as
11435 will all invalid UTF-8 sequences.)
11437 @item Brackets Coding
11438 In this encoding, a wide character is represented by the following eight
11439 character sequence:
11446 where @code{a}, @code{b}, @code{c}, @code{d} are the four hexadecimal
11447 characters (using uppercase letters) of the wide character code. For
11448 example, @code{["A345"]} is used to represent the wide character with code
11450 This scheme is compatible with use of the full Wide_Character set.
11451 On input, brackets coding can also be used for upper half characters,
11452 e.g.@: @code{["C1"]} for lower case a. However, on output, brackets notation
11453 is only used for wide characters with a code greater than @code{16#FF#}.
11458 For the coding schemes other than Hex and Brackets encoding,
11459 not all wide character
11460 values can be represented. An attempt to output a character that cannot
11461 be represented using the encoding scheme for the file causes
11462 Constraint_Error to be raised. An invalid wide character sequence on
11463 input also causes Constraint_Error to be raised.
11466 * Wide_Text_IO Stream Pointer Positioning::
11467 * Wide_Text_IO Reading and Writing Non-Regular Files::
11470 @node Wide_Text_IO Stream Pointer Positioning
11471 @subsection Stream Pointer Positioning
11474 @code{Ada.Wide_Text_IO} is similar to @code{Ada.Text_IO} in its handling
11475 of stream pointer positioning (@pxref{Text_IO}). There is one additional
11478 If @code{Ada.Wide_Text_IO.Look_Ahead} reads a character outside the
11479 normal lower ASCII set (i.e.@: a character in the range:
11481 @smallexample @c ada
11482 Wide_Character'Val (16#0080#) .. Wide_Character'Val (16#FFFF#)
11486 then although the logical position of the file pointer is unchanged by
11487 the @code{Look_Ahead} call, the stream is physically positioned past the
11488 wide character sequence. Again this is to avoid the need for buffering
11489 or backup, and all @code{Wide_Text_IO} routines check the internal
11490 indication that this situation has occurred so that this is not visible
11491 to a normal program using @code{Wide_Text_IO}. However, this discrepancy
11492 can be observed if the wide text file shares a stream with another file.
11494 @node Wide_Text_IO Reading and Writing Non-Regular Files
11495 @subsection Reading and Writing Non-Regular Files
11498 As in the case of Text_IO, when a non-regular file is read, it is
11499 assumed that the file contains no page marks (any form characters are
11500 treated as data characters), and @code{End_Of_Page} always returns
11501 @code{False}. Similarly, the end of file indication is not sticky, so
11502 it is possible to read beyond an end of file.
11504 @node Wide_Wide_Text_IO
11505 @section Wide_Wide_Text_IO
11508 @code{Wide_Wide_Text_IO} is similar in most respects to Text_IO, except that
11509 both input and output files may contain special sequences that represent
11510 wide wide character values. The encoding scheme for a given file may be
11511 specified using a FORM parameter:
11518 as part of the FORM string (WCEM = wide character encoding method),
11519 where @var{x} is one of the following characters
11525 Upper half encoding
11537 The encoding methods match those that
11538 can be used in a source
11539 program, but there is no requirement that the encoding method used for
11540 the source program be the same as the encoding method used for files,
11541 and different files may use different encoding methods.
11543 The default encoding method for the standard files, and for opened files
11544 for which no WCEM parameter is given in the FORM string matches the
11545 wide character encoding specified for the main program (the default
11546 being brackets encoding if no coding method was specified with -gnatW).
11551 A wide character is represented using
11552 UCS Transformation Format 8 (UTF-8) as defined in Annex R of ISO
11553 10646-1/Am.2. Depending on the character value, the representation
11554 is a one, two, three, or four byte sequence:
11557 16#000000#-16#00007f#: 2#0xxxxxxx#
11558 16#000080#-16#0007ff#: 2#110xxxxx# 2#10xxxxxx#
11559 16#000800#-16#00ffff#: 2#1110xxxx# 2#10xxxxxx# 2#10xxxxxx#
11560 16#010000#-16#10ffff#: 2#11110xxx# 2#10xxxxxx# 2#10xxxxxx# 2#10xxxxxx#
11564 where the xxx bits correspond to the left-padded bits of the
11565 21-bit character value. Note that all lower half ASCII characters
11566 are represented as ASCII bytes and all upper half characters and
11567 other wide characters are represented as sequences of upper-half
11570 @item Brackets Coding
11571 In this encoding, a wide wide character is represented by the following eight
11572 character sequence if is in wide character range
11578 and by the following ten character sequence if not
11581 [ " a b c d e f " ]
11585 where @code{a}, @code{b}, @code{c}, @code{d}, @code{e}, and @code{f}
11586 are the four or six hexadecimal
11587 characters (using uppercase letters) of the wide wide character code. For
11588 example, @code{["01A345"]} is used to represent the wide wide character
11589 with code @code{16#01A345#}.
11591 This scheme is compatible with use of the full Wide_Wide_Character set.
11592 On input, brackets coding can also be used for upper half characters,
11593 e.g.@: @code{["C1"]} for lower case a. However, on output, brackets notation
11594 is only used for wide characters with a code greater than @code{16#FF#}.
11599 If is also possible to use the other Wide_Character encoding methods,
11600 such as Shift-JIS, but the other schemes cannot support the full range
11601 of wide wide characters.
11602 An attempt to output a character that cannot
11603 be represented using the encoding scheme for the file causes
11604 Constraint_Error to be raised. An invalid wide character sequence on
11605 input also causes Constraint_Error to be raised.
11608 * Wide_Wide_Text_IO Stream Pointer Positioning::
11609 * Wide_Wide_Text_IO Reading and Writing Non-Regular Files::
11612 @node Wide_Wide_Text_IO Stream Pointer Positioning
11613 @subsection Stream Pointer Positioning
11616 @code{Ada.Wide_Wide_Text_IO} is similar to @code{Ada.Text_IO} in its handling
11617 of stream pointer positioning (@pxref{Text_IO}). There is one additional
11620 If @code{Ada.Wide_Wide_Text_IO.Look_Ahead} reads a character outside the
11621 normal lower ASCII set (i.e.@: a character in the range:
11623 @smallexample @c ada
11624 Wide_Wide_Character'Val (16#0080#) .. Wide_Wide_Character'Val (16#10FFFF#)
11628 then although the logical position of the file pointer is unchanged by
11629 the @code{Look_Ahead} call, the stream is physically positioned past the
11630 wide character sequence. Again this is to avoid the need for buffering
11631 or backup, and all @code{Wide_Wide_Text_IO} routines check the internal
11632 indication that this situation has occurred so that this is not visible
11633 to a normal program using @code{Wide_Wide_Text_IO}. However, this discrepancy
11634 can be observed if the wide text file shares a stream with another file.
11636 @node Wide_Wide_Text_IO Reading and Writing Non-Regular Files
11637 @subsection Reading and Writing Non-Regular Files
11640 As in the case of Text_IO, when a non-regular file is read, it is
11641 assumed that the file contains no page marks (any form characters are
11642 treated as data characters), and @code{End_Of_Page} always returns
11643 @code{False}. Similarly, the end of file indication is not sticky, so
11644 it is possible to read beyond an end of file.
11650 A stream file is a sequence of bytes, where individual elements are
11651 written to the file as described in the Ada 95 reference manual. The type
11652 @code{Stream_Element} is simply a byte. There are two ways to read or
11653 write a stream file.
11657 The operations @code{Read} and @code{Write} directly read or write a
11658 sequence of stream elements with no control information.
11661 The stream attributes applied to a stream file transfer data in the
11662 manner described for stream attributes.
11666 @section Shared Files
11669 Section A.14 of the Ada 95 Reference Manual allows implementations to
11670 provide a wide variety of behavior if an attempt is made to access the
11671 same external file with two or more internal files.
11673 To provide a full range of functionality, while at the same time
11674 minimizing the problems of portability caused by this implementation
11675 dependence, GNAT handles file sharing as follows:
11679 In the absence of a @samp{shared=@var{xxx}} form parameter, an attempt
11680 to open two or more files with the same full name is considered an error
11681 and is not supported. The exception @code{Use_Error} will be
11682 raised. Note that a file that is not explicitly closed by the program
11683 remains open until the program terminates.
11686 If the form parameter @samp{shared=no} appears in the form string, the
11687 file can be opened or created with its own separate stream identifier,
11688 regardless of whether other files sharing the same external file are
11689 opened. The exact effect depends on how the C stream routines handle
11690 multiple accesses to the same external files using separate streams.
11693 If the form parameter @samp{shared=yes} appears in the form string for
11694 each of two or more files opened using the same full name, the same
11695 stream is shared between these files, and the semantics are as described
11696 in Ada 95 Reference Manual, Section A.14.
11700 When a program that opens multiple files with the same name is ported
11701 from another Ada compiler to GNAT, the effect will be that
11702 @code{Use_Error} is raised.
11704 The documentation of the original compiler and the documentation of the
11705 program should then be examined to determine if file sharing was
11706 expected, and @samp{shared=@var{xxx}} parameters added to @code{Open}
11707 and @code{Create} calls as required.
11709 When a program is ported from GNAT to some other Ada compiler, no
11710 special attention is required unless the @samp{shared=@var{xxx}} form
11711 parameter is used in the program. In this case, you must examine the
11712 documentation of the new compiler to see if it supports the required
11713 file sharing semantics, and form strings modified appropriately. Of
11714 course it may be the case that the program cannot be ported if the
11715 target compiler does not support the required functionality. The best
11716 approach in writing portable code is to avoid file sharing (and hence
11717 the use of the @samp{shared=@var{xxx}} parameter in the form string)
11720 One common use of file sharing in Ada 83 is the use of instantiations of
11721 Sequential_IO on the same file with different types, to achieve
11722 heterogeneous input-output. Although this approach will work in GNAT if
11723 @samp{shared=yes} is specified, it is preferable in Ada 95 to use Stream_IO
11724 for this purpose (using the stream attributes)
11727 @section Open Modes
11730 @code{Open} and @code{Create} calls result in a call to @code{fopen}
11731 using the mode shown in the following table:
11734 @center @code{Open} and @code{Create} Call Modes
11736 @b{OPEN } @b{CREATE}
11737 Append_File "r+" "w+"
11739 Out_File (Direct_IO) "r+" "w"
11740 Out_File (all other cases) "w" "w"
11741 Inout_File "r+" "w+"
11745 If text file translation is required, then either @samp{b} or @samp{t}
11746 is added to the mode, depending on the setting of Text. Text file
11747 translation refers to the mapping of CR/LF sequences in an external file
11748 to LF characters internally. This mapping only occurs in DOS and
11749 DOS-like systems, and is not relevant to other systems.
11751 A special case occurs with Stream_IO@. As shown in the above table, the
11752 file is initially opened in @samp{r} or @samp{w} mode for the
11753 @code{In_File} and @code{Out_File} cases. If a @code{Set_Mode} operation
11754 subsequently requires switching from reading to writing or vice-versa,
11755 then the file is reopened in @samp{r+} mode to permit the required operation.
11757 @node Operations on C Streams
11758 @section Operations on C Streams
11759 The package @code{Interfaces.C_Streams} provides an Ada program with direct
11760 access to the C library functions for operations on C streams:
11762 @smallexample @c adanocomment
11763 package Interfaces.C_Streams is
11764 -- Note: the reason we do not use the types that are in
11765 -- Interfaces.C is that we want to avoid dragging in the
11766 -- code in this unit if possible.
11767 subtype chars is System.Address;
11768 -- Pointer to null-terminated array of characters
11769 subtype FILEs is System.Address;
11770 -- Corresponds to the C type FILE*
11771 subtype voids is System.Address;
11772 -- Corresponds to the C type void*
11773 subtype int is Integer;
11774 subtype long is Long_Integer;
11775 -- Note: the above types are subtypes deliberately, and it
11776 -- is part of this spec that the above correspondences are
11777 -- guaranteed. This means that it is legitimate to, for
11778 -- example, use Integer instead of int. We provide these
11779 -- synonyms for clarity, but in some cases it may be
11780 -- convenient to use the underlying types (for example to
11781 -- avoid an unnecessary dependency of a spec on the spec
11783 type size_t is mod 2 ** Standard'Address_Size;
11784 NULL_Stream : constant FILEs;
11785 -- Value returned (NULL in C) to indicate an
11786 -- fdopen/fopen/tmpfile error
11787 ----------------------------------
11788 -- Constants Defined in stdio.h --
11789 ----------------------------------
11790 EOF : constant int;
11791 -- Used by a number of routines to indicate error or
11793 IOFBF : constant int;
11794 IOLBF : constant int;
11795 IONBF : constant int;
11796 -- Used to indicate buffering mode for setvbuf call
11797 SEEK_CUR : constant int;
11798 SEEK_END : constant int;
11799 SEEK_SET : constant int;
11800 -- Used to indicate origin for fseek call
11801 function stdin return FILEs;
11802 function stdout return FILEs;
11803 function stderr return FILEs;
11804 -- Streams associated with standard files
11805 --------------------------
11806 -- Standard C functions --
11807 --------------------------
11808 -- The functions selected below are ones that are
11809 -- available in DOS, OS/2, UNIX and Xenix (but not
11810 -- necessarily in ANSI C). These are very thin interfaces
11811 -- which copy exactly the C headers. For more
11812 -- documentation on these functions, see the Microsoft C
11813 -- "Run-Time Library Reference" (Microsoft Press, 1990,
11814 -- ISBN 1-55615-225-6), which includes useful information
11815 -- on system compatibility.
11816 procedure clearerr (stream : FILEs);
11817 function fclose (stream : FILEs) return int;
11818 function fdopen (handle : int; mode : chars) return FILEs;
11819 function feof (stream : FILEs) return int;
11820 function ferror (stream : FILEs) return int;
11821 function fflush (stream : FILEs) return int;
11822 function fgetc (stream : FILEs) return int;
11823 function fgets (strng : chars; n : int; stream : FILEs)
11825 function fileno (stream : FILEs) return int;
11826 function fopen (filename : chars; Mode : chars)
11828 -- Note: to maintain target independence, use
11829 -- text_translation_required, a boolean variable defined in
11830 -- a-sysdep.c to deal with the target dependent text
11831 -- translation requirement. If this variable is set,
11832 -- then b/t should be appended to the standard mode
11833 -- argument to set the text translation mode off or on
11835 function fputc (C : int; stream : FILEs) return int;
11836 function fputs (Strng : chars; Stream : FILEs) return int;
11853 function ftell (stream : FILEs) return long;
11860 function isatty (handle : int) return int;
11861 procedure mktemp (template : chars);
11862 -- The return value (which is just a pointer to template)
11864 procedure rewind (stream : FILEs);
11865 function rmtmp return int;
11873 function tmpfile return FILEs;
11874 function ungetc (c : int; stream : FILEs) return int;
11875 function unlink (filename : chars) return int;
11876 ---------------------
11877 -- Extra functions --
11878 ---------------------
11879 -- These functions supply slightly thicker bindings than
11880 -- those above. They are derived from functions in the
11881 -- C Run-Time Library, but may do a bit more work than
11882 -- just directly calling one of the Library functions.
11883 function is_regular_file (handle : int) return int;
11884 -- Tests if given handle is for a regular file (result 1)
11885 -- or for a non-regular file (pipe or device, result 0).
11886 ---------------------------------
11887 -- Control of Text/Binary Mode --
11888 ---------------------------------
11889 -- If text_translation_required is true, then the following
11890 -- functions may be used to dynamically switch a file from
11891 -- binary to text mode or vice versa. These functions have
11892 -- no effect if text_translation_required is false (i.e. in
11893 -- normal UNIX mode). Use fileno to get a stream handle.
11894 procedure set_binary_mode (handle : int);
11895 procedure set_text_mode (handle : int);
11896 ----------------------------
11897 -- Full Path Name support --
11898 ----------------------------
11899 procedure full_name (nam : chars; buffer : chars);
11900 -- Given a NUL terminated string representing a file
11901 -- name, returns in buffer a NUL terminated string
11902 -- representing the full path name for the file name.
11903 -- On systems where it is relevant the drive is also
11904 -- part of the full path name. It is the responsibility
11905 -- of the caller to pass an actual parameter for buffer
11906 -- that is big enough for any full path name. Use
11907 -- max_path_len given below as the size of buffer.
11908 max_path_len : integer;
11909 -- Maximum length of an allowable full path name on the
11910 -- system, including a terminating NUL character.
11911 end Interfaces.C_Streams;
11914 @node Interfacing to C Streams
11915 @section Interfacing to C Streams
11918 The packages in this section permit interfacing Ada files to C Stream
11921 @smallexample @c ada
11922 with Interfaces.C_Streams;
11923 package Ada.Sequential_IO.C_Streams is
11924 function C_Stream (F : File_Type)
11925 return Interfaces.C_Streams.FILEs;
11927 (File : in out File_Type;
11928 Mode : in File_Mode;
11929 C_Stream : in Interfaces.C_Streams.FILEs;
11930 Form : in String := "");
11931 end Ada.Sequential_IO.C_Streams;
11933 with Interfaces.C_Streams;
11934 package Ada.Direct_IO.C_Streams is
11935 function C_Stream (F : File_Type)
11936 return Interfaces.C_Streams.FILEs;
11938 (File : in out File_Type;
11939 Mode : in File_Mode;
11940 C_Stream : in Interfaces.C_Streams.FILEs;
11941 Form : in String := "");
11942 end Ada.Direct_IO.C_Streams;
11944 with Interfaces.C_Streams;
11945 package Ada.Text_IO.C_Streams is
11946 function C_Stream (F : File_Type)
11947 return Interfaces.C_Streams.FILEs;
11949 (File : in out File_Type;
11950 Mode : in File_Mode;
11951 C_Stream : in Interfaces.C_Streams.FILEs;
11952 Form : in String := "");
11953 end Ada.Text_IO.C_Streams;
11955 with Interfaces.C_Streams;
11956 package Ada.Wide_Text_IO.C_Streams is
11957 function C_Stream (F : File_Type)
11958 return Interfaces.C_Streams.FILEs;
11960 (File : in out File_Type;
11961 Mode : in File_Mode;
11962 C_Stream : in Interfaces.C_Streams.FILEs;
11963 Form : in String := "");
11964 end Ada.Wide_Text_IO.C_Streams;
11966 with Interfaces.C_Streams;
11967 package Ada.Wide_Wide_Text_IO.C_Streams is
11968 function C_Stream (F : File_Type)
11969 return Interfaces.C_Streams.FILEs;
11971 (File : in out File_Type;
11972 Mode : in File_Mode;
11973 C_Stream : in Interfaces.C_Streams.FILEs;
11974 Form : in String := "");
11975 end Ada.Wide_Wide_Text_IO.C_Streams;
11977 with Interfaces.C_Streams;
11978 package Ada.Stream_IO.C_Streams is
11979 function C_Stream (F : File_Type)
11980 return Interfaces.C_Streams.FILEs;
11982 (File : in out File_Type;
11983 Mode : in File_Mode;
11984 C_Stream : in Interfaces.C_Streams.FILEs;
11985 Form : in String := "");
11986 end Ada.Stream_IO.C_Streams;
11990 In each of these six packages, the @code{C_Stream} function obtains the
11991 @code{FILE} pointer from a currently opened Ada file. It is then
11992 possible to use the @code{Interfaces.C_Streams} package to operate on
11993 this stream, or the stream can be passed to a C program which can
11994 operate on it directly. Of course the program is responsible for
11995 ensuring that only appropriate sequences of operations are executed.
11997 One particular use of relevance to an Ada program is that the
11998 @code{setvbuf} function can be used to control the buffering of the
11999 stream used by an Ada file. In the absence of such a call the standard
12000 default buffering is used.
12002 The @code{Open} procedures in these packages open a file giving an
12003 existing C Stream instead of a file name. Typically this stream is
12004 imported from a C program, allowing an Ada file to operate on an
12007 @node The GNAT Library
12008 @chapter The GNAT Library
12011 The GNAT library contains a number of general and special purpose packages.
12012 It represents functionality that the GNAT developers have found useful, and
12013 which is made available to GNAT users. The packages described here are fully
12014 supported, and upwards compatibility will be maintained in future releases,
12015 so you can use these facilities with the confidence that the same functionality
12016 will be available in future releases.
12018 The chapter here simply gives a brief summary of the facilities available.
12019 The full documentation is found in the spec file for the package. The full
12020 sources of these library packages, including both spec and body, are provided
12021 with all GNAT releases. For example, to find out the full specifications of
12022 the SPITBOL pattern matching capability, including a full tutorial and
12023 extensive examples, look in the @file{g-spipat.ads} file in the library.
12025 For each entry here, the package name (as it would appear in a @code{with}
12026 clause) is given, followed by the name of the corresponding spec file in
12027 parentheses. The packages are children in four hierarchies, @code{Ada},
12028 @code{Interfaces}, @code{System}, and @code{GNAT}, the latter being a
12029 GNAT-specific hierarchy.
12031 Note that an application program should only use packages in one of these
12032 four hierarchies if the package is defined in the Ada Reference Manual,
12033 or is listed in this section of the GNAT Programmers Reference Manual.
12034 All other units should be considered internal implementation units and
12035 should not be directly @code{with}'ed by application code. The use of
12036 a @code{with} statement that references one of these internal implementation
12037 units makes an application potentially dependent on changes in versions
12038 of GNAT, and will generate a warning message.
12041 * Ada.Characters.Latin_9 (a-chlat9.ads)::
12042 * Ada.Characters.Wide_Latin_1 (a-cwila1.ads)::
12043 * Ada.Characters.Wide_Latin_9 (a-cwila9.ads)::
12044 * Ada.Characters.Wide_Wide_Latin_1 (a-czila1.ads)::
12045 * Ada.Characters.Wide_Wide_Latin_9 (a-czila9.ads)::
12046 * Ada.Command_Line.Remove (a-colire.ads)::
12047 * Ada.Command_Line.Environment (a-colien.ads)::
12048 * Ada.Direct_IO.C_Streams (a-diocst.ads)::
12049 * Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads)::
12050 * Ada.Exceptions.Traceback (a-exctra.ads)::
12051 * Ada.Sequential_IO.C_Streams (a-siocst.ads)::
12052 * Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads)::
12053 * Ada.Strings.Unbounded.Text_IO (a-suteio.ads)::
12054 * Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads)::
12055 * Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads)::
12056 * Ada.Text_IO.C_Streams (a-tiocst.ads)::
12057 * Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads)::
12058 * Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads)::
12059 * GNAT.Array_Split (g-arrspl.ads)::
12060 * GNAT.AWK (g-awk.ads)::
12061 * GNAT.Bounded_Buffers (g-boubuf.ads)::
12062 * GNAT.Bounded_Mailboxes (g-boumai.ads)::
12063 * GNAT.Bubble_Sort (g-bubsor.ads)::
12064 * GNAT.Bubble_Sort_A (g-busora.ads)::
12065 * GNAT.Bubble_Sort_G (g-busorg.ads)::
12066 * GNAT.Calendar (g-calend.ads)::
12067 * GNAT.Calendar.Time_IO (g-catiio.ads)::
12068 * GNAT.CRC32 (g-crc32.ads)::
12069 * GNAT.Case_Util (g-casuti.ads)::
12070 * GNAT.CGI (g-cgi.ads)::
12071 * GNAT.CGI.Cookie (g-cgicoo.ads)::
12072 * GNAT.CGI.Debug (g-cgideb.ads)::
12073 * GNAT.Command_Line (g-comlin.ads)::
12074 * GNAT.Compiler_Version (g-comver.ads)::
12075 * GNAT.Ctrl_C (g-ctrl_c.ads)::
12076 * GNAT.Current_Exception (g-curexc.ads)::
12077 * GNAT.Debug_Pools (g-debpoo.ads)::
12078 * GNAT.Debug_Utilities (g-debuti.ads)::
12079 * GNAT.Directory_Operations (g-dirope.ads)::
12080 * GNAT.Dynamic_HTables (g-dynhta.ads)::
12081 * GNAT.Dynamic_Tables (g-dyntab.ads)::
12082 * GNAT.Exception_Actions (g-excact.ads)::
12083 * GNAT.Exception_Traces (g-exctra.ads)::
12084 * GNAT.Exceptions (g-except.ads)::
12085 * GNAT.Expect (g-expect.ads)::
12086 * GNAT.Float_Control (g-flocon.ads)::
12087 * GNAT.Heap_Sort (g-heasor.ads)::
12088 * GNAT.Heap_Sort_A (g-hesora.ads)::
12089 * GNAT.Heap_Sort_G (g-hesorg.ads)::
12090 * GNAT.HTable (g-htable.ads)::
12091 * GNAT.IO (g-io.ads)::
12092 * GNAT.IO_Aux (g-io_aux.ads)::
12093 * GNAT.Lock_Files (g-locfil.ads)::
12094 * GNAT.MD5 (g-md5.ads)::
12095 * GNAT.Memory_Dump (g-memdum.ads)::
12096 * GNAT.Most_Recent_Exception (g-moreex.ads)::
12097 * GNAT.OS_Lib (g-os_lib.ads)::
12098 * GNAT.Perfect_Hash_Generators (g-pehage.ads)::
12099 * GNAT.Regexp (g-regexp.ads)::
12100 * GNAT.Registry (g-regist.ads)::
12101 * GNAT.Regpat (g-regpat.ads)::
12102 * GNAT.Secondary_Stack_Info (g-sestin.ads)::
12103 * GNAT.Semaphores (g-semaph.ads)::
12104 * GNAT.Signals (g-signal.ads)::
12105 * GNAT.Sockets (g-socket.ads)::
12106 * GNAT.Source_Info (g-souinf.ads)::
12107 * GNAT.Spell_Checker (g-speche.ads)::
12108 * GNAT.Spitbol.Patterns (g-spipat.ads)::
12109 * GNAT.Spitbol (g-spitbo.ads)::
12110 * GNAT.Spitbol.Table_Boolean (g-sptabo.ads)::
12111 * GNAT.Spitbol.Table_Integer (g-sptain.ads)::
12112 * GNAT.Spitbol.Table_VString (g-sptavs.ads)::
12113 * GNAT.Strings (g-string.ads)::
12114 * GNAT.String_Split (g-strspl.ads)::
12115 * GNAT.UTF_32 (g-utf_32.ads)::
12116 * GNAT.Table (g-table.ads)::
12117 * GNAT.Task_Lock (g-tasloc.ads)::
12118 * GNAT.Threads (g-thread.ads)::
12119 * GNAT.Traceback (g-traceb.ads)::
12120 * GNAT.Traceback.Symbolic (g-trasym.ads)::
12121 * GNAT.Wide_String_Split (g-wistsp.ads)::
12122 * GNAT.Wide_Wide_String_Split (g-zistsp.ads)::
12123 * Interfaces.C.Extensions (i-cexten.ads)::
12124 * Interfaces.C.Streams (i-cstrea.ads)::
12125 * Interfaces.CPP (i-cpp.ads)::
12126 * Interfaces.Os2lib (i-os2lib.ads)::
12127 * Interfaces.Os2lib.Errors (i-os2err.ads)::
12128 * Interfaces.Os2lib.Synchronization (i-os2syn.ads)::
12129 * Interfaces.Os2lib.Threads (i-os2thr.ads)::
12130 * Interfaces.Packed_Decimal (i-pacdec.ads)::
12131 * Interfaces.VxWorks (i-vxwork.ads)::
12132 * Interfaces.VxWorks.IO (i-vxwoio.ads)::
12133 * System.Address_Image (s-addima.ads)::
12134 * System.Assertions (s-assert.ads)::
12135 * System.Memory (s-memory.ads)::
12136 * System.Partition_Interface (s-parint.ads)::
12137 * System.Restrictions (s-restri.ads)::
12138 * System.Rident (s-rident.ads)::
12139 * System.Task_Info (s-tasinf.ads)::
12140 * System.Wch_Cnv (s-wchcnv.ads)::
12141 * System.Wch_Con (s-wchcon.ads)::
12144 @node Ada.Characters.Latin_9 (a-chlat9.ads)
12145 @section @code{Ada.Characters.Latin_9} (@file{a-chlat9.ads})
12146 @cindex @code{Ada.Characters.Latin_9} (@file{a-chlat9.ads})
12147 @cindex Latin_9 constants for Character
12150 This child of @code{Ada.Characters}
12151 provides a set of definitions corresponding to those in the
12152 RM-defined package @code{Ada.Characters.Latin_1} but with the
12153 few modifications required for @code{Latin-9}
12154 The provision of such a package
12155 is specifically authorized by the Ada Reference Manual
12158 @node Ada.Characters.Wide_Latin_1 (a-cwila1.ads)
12159 @section @code{Ada.Characters.Wide_Latin_1} (@file{a-cwila1.ads})
12160 @cindex @code{Ada.Characters.Wide_Latin_1} (@file{a-cwila1.ads})
12161 @cindex Latin_1 constants for Wide_Character
12164 This child of @code{Ada.Characters}
12165 provides a set of definitions corresponding to those in the
12166 RM-defined package @code{Ada.Characters.Latin_1} but with the
12167 types of the constants being @code{Wide_Character}
12168 instead of @code{Character}. The provision of such a package
12169 is specifically authorized by the Ada Reference Manual
12172 @node Ada.Characters.Wide_Latin_9 (a-cwila9.ads)
12173 @section @code{Ada.Characters.Wide_Latin_9} (@file{a-cwila1.ads})
12174 @cindex @code{Ada.Characters.Wide_Latin_9} (@file{a-cwila1.ads})
12175 @cindex Latin_9 constants for Wide_Character
12178 This child of @code{Ada.Characters}
12179 provides a set of definitions corresponding to those in the
12180 GNAT defined package @code{Ada.Characters.Latin_9} but with the
12181 types of the constants being @code{Wide_Character}
12182 instead of @code{Character}. The provision of such a package
12183 is specifically authorized by the Ada Reference Manual
12186 @node Ada.Characters.Wide_Wide_Latin_1 (a-czila1.ads)
12187 @section @code{Ada.Characters.Wide_Wide_Latin_1} (@file{a-czila1.ads})
12188 @cindex @code{Ada.Characters.Wide_Wide_Latin_1} (@file{a-czila1.ads})
12189 @cindex Latin_1 constants for Wide_Wide_Character
12192 This child of @code{Ada.Characters}
12193 provides a set of definitions corresponding to those in the
12194 RM-defined package @code{Ada.Characters.Latin_1} but with the
12195 types of the constants being @code{Wide_Wide_Character}
12196 instead of @code{Character}. The provision of such a package
12197 is specifically authorized by the Ada Reference Manual
12200 @node Ada.Characters.Wide_Wide_Latin_9 (a-czila9.ads)
12201 @section @code{Ada.Characters.Wide_Wide_Latin_9} (@file{a-czila9.ads})
12202 @cindex @code{Ada.Characters.Wide_Wide_Latin_9} (@file{a-czila9.ads})
12203 @cindex Latin_9 constants for Wide_Wide_Character
12206 This child of @code{Ada.Characters}
12207 provides a set of definitions corresponding to those in the
12208 GNAT defined package @code{Ada.Characters.Latin_9} but with the
12209 types of the constants being @code{Wide_Wide_Character}
12210 instead of @code{Character}. The provision of such a package
12211 is specifically authorized by the Ada Reference Manual
12214 @node Ada.Command_Line.Remove (a-colire.ads)
12215 @section @code{Ada.Command_Line.Remove} (@file{a-colire.ads})
12216 @cindex @code{Ada.Command_Line.Remove} (@file{a-colire.ads})
12217 @cindex Removing command line arguments
12218 @cindex Command line, argument removal
12221 This child of @code{Ada.Command_Line}
12222 provides a mechanism for logically removing
12223 arguments from the argument list. Once removed, an argument is not visible
12224 to further calls on the subprograms in @code{Ada.Command_Line} will not
12225 see the removed argument.
12227 @node Ada.Command_Line.Environment (a-colien.ads)
12228 @section @code{Ada.Command_Line.Environment} (@file{a-colien.ads})
12229 @cindex @code{Ada.Command_Line.Environment} (@file{a-colien.ads})
12230 @cindex Environment entries
12233 This child of @code{Ada.Command_Line}
12234 provides a mechanism for obtaining environment values on systems
12235 where this concept makes sense.
12237 @node Ada.Direct_IO.C_Streams (a-diocst.ads)
12238 @section @code{Ada.Direct_IO.C_Streams} (@file{a-diocst.ads})
12239 @cindex @code{Ada.Direct_IO.C_Streams} (@file{a-diocst.ads})
12240 @cindex C Streams, Interfacing with Direct_IO
12243 This package provides subprograms that allow interfacing between
12244 C streams and @code{Direct_IO}. The stream identifier can be
12245 extracted from a file opened on the Ada side, and an Ada file
12246 can be constructed from a stream opened on the C side.
12248 @node Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads)
12249 @section @code{Ada.Exceptions.Is_Null_Occurrence} (@file{a-einuoc.ads})
12250 @cindex @code{Ada.Exceptions.Is_Null_Occurrence} (@file{a-einuoc.ads})
12251 @cindex Null_Occurrence, testing for
12254 This child subprogram provides a way of testing for the null
12255 exception occurrence (@code{Null_Occurrence}) without raising
12258 @node Ada.Exceptions.Traceback (a-exctra.ads)
12259 @section @code{Ada.Exceptions.Traceback} (@file{a-exctra.ads})
12260 @cindex @code{Ada.Exceptions.Traceback} (@file{a-exctra.ads})
12261 @cindex Traceback for Exception Occurrence
12264 This child package provides the subprogram (@code{Tracebacks}) to
12265 give a traceback array of addresses based on an exception
12268 @node Ada.Sequential_IO.C_Streams (a-siocst.ads)
12269 @section @code{Ada.Sequential_IO.C_Streams} (@file{a-siocst.ads})
12270 @cindex @code{Ada.Sequential_IO.C_Streams} (@file{a-siocst.ads})
12271 @cindex C Streams, Interfacing with Sequential_IO
12274 This package provides subprograms that allow interfacing between
12275 C streams and @code{Sequential_IO}. The stream identifier can be
12276 extracted from a file opened on the Ada side, and an Ada file
12277 can be constructed from a stream opened on the C side.
12279 @node Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads)
12280 @section @code{Ada.Streams.Stream_IO.C_Streams} (@file{a-ssicst.ads})
12281 @cindex @code{Ada.Streams.Stream_IO.C_Streams} (@file{a-ssicst.ads})
12282 @cindex C Streams, Interfacing with Stream_IO
12285 This package provides subprograms that allow interfacing between
12286 C streams and @code{Stream_IO}. The stream identifier can be
12287 extracted from a file opened on the Ada side, and an Ada file
12288 can be constructed from a stream opened on the C side.
12290 @node Ada.Strings.Unbounded.Text_IO (a-suteio.ads)
12291 @section @code{Ada.Strings.Unbounded.Text_IO} (@file{a-suteio.ads})
12292 @cindex @code{Ada.Strings.Unbounded.Text_IO} (@file{a-suteio.ads})
12293 @cindex @code{Unbounded_String}, IO support
12294 @cindex @code{Text_IO}, extensions for unbounded strings
12297 This package provides subprograms for Text_IO for unbounded
12298 strings, avoiding the necessity for an intermediate operation
12299 with ordinary strings.
12301 @node Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads)
12302 @section @code{Ada.Strings.Wide_Unbounded.Wide_Text_IO} (@file{a-swuwti.ads})
12303 @cindex @code{Ada.Strings.Wide_Unbounded.Wide_Text_IO} (@file{a-swuwti.ads})
12304 @cindex @code{Unbounded_Wide_String}, IO support
12305 @cindex @code{Text_IO}, extensions for unbounded wide strings
12308 This package provides subprograms for Text_IO for unbounded
12309 wide strings, avoiding the necessity for an intermediate operation
12310 with ordinary wide strings.
12312 @node Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads)
12313 @section @code{Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO} (@file{a-szuzti.ads})
12314 @cindex @code{Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO} (@file{a-szuzti.ads})
12315 @cindex @code{Unbounded_Wide_Wide_String}, IO support
12316 @cindex @code{Text_IO}, extensions for unbounded wide wide strings
12319 This package provides subprograms for Text_IO for unbounded
12320 wide wide strings, avoiding the necessity for an intermediate operation
12321 with ordinary wide wide strings.
12323 @node Ada.Text_IO.C_Streams (a-tiocst.ads)
12324 @section @code{Ada.Text_IO.C_Streams} (@file{a-tiocst.ads})
12325 @cindex @code{Ada.Text_IO.C_Streams} (@file{a-tiocst.ads})
12326 @cindex C Streams, Interfacing with @code{Text_IO}
12329 This package provides subprograms that allow interfacing between
12330 C streams and @code{Text_IO}. The stream identifier can be
12331 extracted from a file opened on the Ada side, and an Ada file
12332 can be constructed from a stream opened on the C side.
12334 @node Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads)
12335 @section @code{Ada.Wide_Text_IO.C_Streams} (@file{a-wtcstr.ads})
12336 @cindex @code{Ada.Wide_Text_IO.C_Streams} (@file{a-wtcstr.ads})
12337 @cindex C Streams, Interfacing with @code{Wide_Text_IO}
12340 This package provides subprograms that allow interfacing between
12341 C streams and @code{Wide_Text_IO}. The stream identifier can be
12342 extracted from a file opened on the Ada side, and an Ada file
12343 can be constructed from a stream opened on the C side.
12345 @node Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads)
12346 @section @code{Ada.Wide_Wide_Text_IO.C_Streams} (@file{a-ztcstr.ads})
12347 @cindex @code{Ada.Wide_Wide_Text_IO.C_Streams} (@file{a-ztcstr.ads})
12348 @cindex C Streams, Interfacing with @code{Wide_Wide_Text_IO}
12351 This package provides subprograms that allow interfacing between
12352 C streams and @code{Wide_Wide_Text_IO}. The stream identifier can be
12353 extracted from a file opened on the Ada side, and an Ada file
12354 can be constructed from a stream opened on the C side.
12357 @node GNAT.Array_Split (g-arrspl.ads)
12358 @section @code{GNAT.Array_Split} (@file{g-arrspl.ads})
12359 @cindex @code{GNAT.Array_Split} (@file{g-arrspl.ads})
12360 @cindex Array splitter
12363 Useful array-manipulation routines: given a set of separators, split
12364 an array wherever the separators appear, and provide direct access
12365 to the resulting slices.
12367 @node GNAT.AWK (g-awk.ads)
12368 @section @code{GNAT.AWK} (@file{g-awk.ads})
12369 @cindex @code{GNAT.AWK} (@file{g-awk.ads})
12374 Provides AWK-like parsing functions, with an easy interface for parsing one
12375 or more files containing formatted data. The file is viewed as a database
12376 where each record is a line and a field is a data element in this line.
12378 @node GNAT.Bounded_Buffers (g-boubuf.ads)
12379 @section @code{GNAT.Bounded_Buffers} (@file{g-boubuf.ads})
12380 @cindex @code{GNAT.Bounded_Buffers} (@file{g-boubuf.ads})
12382 @cindex Bounded Buffers
12385 Provides a concurrent generic bounded buffer abstraction. Instances are
12386 useful directly or as parts of the implementations of other abstractions,
12389 @node GNAT.Bounded_Mailboxes (g-boumai.ads)
12390 @section @code{GNAT.Bounded_Mailboxes} (@file{g-boumai.ads})
12391 @cindex @code{GNAT.Bounded_Mailboxes} (@file{g-boumai.ads})
12396 Provides a thread-safe asynchronous intertask mailbox communication facility.
12398 @node GNAT.Bubble_Sort (g-bubsor.ads)
12399 @section @code{GNAT.Bubble_Sort} (@file{g-bubsor.ads})
12400 @cindex @code{GNAT.Bubble_Sort} (@file{g-bubsor.ads})
12402 @cindex Bubble sort
12405 Provides a general implementation of bubble sort usable for sorting arbitrary
12406 data items. Exchange and comparison procedures are provided by passing
12407 access-to-procedure values.
12409 @node GNAT.Bubble_Sort_A (g-busora.ads)
12410 @section @code{GNAT.Bubble_Sort_A} (@file{g-busora.ads})
12411 @cindex @code{GNAT.Bubble_Sort_A} (@file{g-busora.ads})
12413 @cindex Bubble sort
12416 Provides a general implementation of bubble sort usable for sorting arbitrary
12417 data items. Move and comparison procedures are provided by passing
12418 access-to-procedure values. This is an older version, retained for
12419 compatibility. Usually @code{GNAT.Bubble_Sort} will be preferable.
12421 @node GNAT.Bubble_Sort_G (g-busorg.ads)
12422 @section @code{GNAT.Bubble_Sort_G} (@file{g-busorg.ads})
12423 @cindex @code{GNAT.Bubble_Sort_G} (@file{g-busorg.ads})
12425 @cindex Bubble sort
12428 Similar to @code{Bubble_Sort_A} except that the move and sorting procedures
12429 are provided as generic parameters, this improves efficiency, especially
12430 if the procedures can be inlined, at the expense of duplicating code for
12431 multiple instantiations.
12433 @node GNAT.Calendar (g-calend.ads)
12434 @section @code{GNAT.Calendar} (@file{g-calend.ads})
12435 @cindex @code{GNAT.Calendar} (@file{g-calend.ads})
12436 @cindex @code{Calendar}
12439 Extends the facilities provided by @code{Ada.Calendar} to include handling
12440 of days of the week, an extended @code{Split} and @code{Time_Of} capability.
12441 Also provides conversion of @code{Ada.Calendar.Time} values to and from the
12442 C @code{timeval} format.
12444 @node GNAT.Calendar.Time_IO (g-catiio.ads)
12445 @section @code{GNAT.Calendar.Time_IO} (@file{g-catiio.ads})
12446 @cindex @code{Calendar}
12448 @cindex @code{GNAT.Calendar.Time_IO} (@file{g-catiio.ads})
12450 @node GNAT.CRC32 (g-crc32.ads)
12451 @section @code{GNAT.CRC32} (@file{g-crc32.ads})
12452 @cindex @code{GNAT.CRC32} (@file{g-crc32.ads})
12454 @cindex Cyclic Redundancy Check
12457 This package implements the CRC-32 algorithm. For a full description
12458 of this algorithm see
12459 ``Computation of Cyclic Redundancy Checks via Table Look-Up'',
12460 @cite{Communications of the ACM}, Vol.@: 31 No.@: 8, pp.@: 1008-1013,
12461 Aug.@: 1988. Sarwate, D.V@.
12464 Provides an extended capability for formatted output of time values with
12465 full user control over the format. Modeled on the GNU Date specification.
12467 @node GNAT.Case_Util (g-casuti.ads)
12468 @section @code{GNAT.Case_Util} (@file{g-casuti.ads})
12469 @cindex @code{GNAT.Case_Util} (@file{g-casuti.ads})
12470 @cindex Casing utilities
12471 @cindex Character handling (@code{GNAT.Case_Util})
12474 A set of simple routines for handling upper and lower casing of strings
12475 without the overhead of the full casing tables
12476 in @code{Ada.Characters.Handling}.
12478 @node GNAT.CGI (g-cgi.ads)
12479 @section @code{GNAT.CGI} (@file{g-cgi.ads})
12480 @cindex @code{GNAT.CGI} (@file{g-cgi.ads})
12481 @cindex CGI (Common Gateway Interface)
12484 This is a package for interfacing a GNAT program with a Web server via the
12485 Common Gateway Interface (CGI)@. Basically this package parses the CGI
12486 parameters, which are a set of key/value pairs sent by the Web server. It
12487 builds a table whose index is the key and provides some services to deal
12490 @node GNAT.CGI.Cookie (g-cgicoo.ads)
12491 @section @code{GNAT.CGI.Cookie} (@file{g-cgicoo.ads})
12492 @cindex @code{GNAT.CGI.Cookie} (@file{g-cgicoo.ads})
12493 @cindex CGI (Common Gateway Interface) cookie support
12494 @cindex Cookie support in CGI
12497 This is a package to interface a GNAT program with a Web server via the
12498 Common Gateway Interface (CGI). It exports services to deal with Web
12499 cookies (piece of information kept in the Web client software).
12501 @node GNAT.CGI.Debug (g-cgideb.ads)
12502 @section @code{GNAT.CGI.Debug} (@file{g-cgideb.ads})
12503 @cindex @code{GNAT.CGI.Debug} (@file{g-cgideb.ads})
12504 @cindex CGI (Common Gateway Interface) debugging
12507 This is a package to help debugging CGI (Common Gateway Interface)
12508 programs written in Ada.
12510 @node GNAT.Command_Line (g-comlin.ads)
12511 @section @code{GNAT.Command_Line} (@file{g-comlin.ads})
12512 @cindex @code{GNAT.Command_Line} (@file{g-comlin.ads})
12513 @cindex Command line
12516 Provides a high level interface to @code{Ada.Command_Line} facilities,
12517 including the ability to scan for named switches with optional parameters
12518 and expand file names using wild card notations.
12520 @node GNAT.Compiler_Version (g-comver.ads)
12521 @section @code{GNAT.Compiler_Version} (@file{g-comver.ads})
12522 @cindex @code{GNAT.Compiler_Version} (@file{g-comver.ads})
12523 @cindex Compiler Version
12524 @cindex Version, of compiler
12527 Provides a routine for obtaining the version of the compiler used to
12528 compile the program. More accurately this is the version of the binder
12529 used to bind the program (this will normally be the same as the version
12530 of the compiler if a consistent tool set is used to compile all units
12533 @node GNAT.Ctrl_C (g-ctrl_c.ads)
12534 @section @code{GNAT.Ctrl_C} (@file{g-ctrl_c.ads})
12535 @cindex @code{GNAT.Ctrl_C} (@file{g-ctrl_c.ads})
12539 Provides a simple interface to handle Ctrl-C keyboard events.
12541 @node GNAT.Current_Exception (g-curexc.ads)
12542 @section @code{GNAT.Current_Exception} (@file{g-curexc.ads})
12543 @cindex @code{GNAT.Current_Exception} (@file{g-curexc.ads})
12544 @cindex Current exception
12545 @cindex Exception retrieval
12548 Provides access to information on the current exception that has been raised
12549 without the need for using the Ada-95 exception choice parameter specification
12550 syntax. This is particularly useful in simulating typical facilities for
12551 obtaining information about exceptions provided by Ada 83 compilers.
12553 @node GNAT.Debug_Pools (g-debpoo.ads)
12554 @section @code{GNAT.Debug_Pools} (@file{g-debpoo.ads})
12555 @cindex @code{GNAT.Debug_Pools} (@file{g-debpoo.ads})
12557 @cindex Debug pools
12558 @cindex Memory corruption debugging
12561 Provide a debugging storage pools that helps tracking memory corruption
12562 problems. See section ``Finding memory problems with GNAT Debug Pool'' in
12563 the @cite{GNAT User's Guide}.
12565 @node GNAT.Debug_Utilities (g-debuti.ads)
12566 @section @code{GNAT.Debug_Utilities} (@file{g-debuti.ads})
12567 @cindex @code{GNAT.Debug_Utilities} (@file{g-debuti.ads})
12571 Provides a few useful utilities for debugging purposes, including conversion
12572 to and from string images of address values. Supports both C and Ada formats
12573 for hexadecimal literals.
12575 @node GNAT.Directory_Operations (g-dirope.ads)
12576 @section @code{GNAT.Directory_Operations} (g-dirope.ads)
12577 @cindex @code{GNAT.Directory_Operations} (g-dirope.ads)
12578 @cindex Directory operations
12581 Provides a set of routines for manipulating directories, including changing
12582 the current directory, making new directories, and scanning the files in a
12585 @node GNAT.Dynamic_HTables (g-dynhta.ads)
12586 @section @code{GNAT.Dynamic_HTables} (@file{g-dynhta.ads})
12587 @cindex @code{GNAT.Dynamic_HTables} (@file{g-dynhta.ads})
12588 @cindex Hash tables
12591 A generic implementation of hash tables that can be used to hash arbitrary
12592 data. Provided in two forms, a simple form with built in hash functions,
12593 and a more complex form in which the hash function is supplied.
12596 This package provides a facility similar to that of @code{GNAT.HTable},
12597 except that this package declares a type that can be used to define
12598 dynamic instances of the hash table, while an instantiation of
12599 @code{GNAT.HTable} creates a single instance of the hash table.
12601 @node GNAT.Dynamic_Tables (g-dyntab.ads)
12602 @section @code{GNAT.Dynamic_Tables} (@file{g-dyntab.ads})
12603 @cindex @code{GNAT.Dynamic_Tables} (@file{g-dyntab.ads})
12604 @cindex Table implementation
12605 @cindex Arrays, extendable
12608 A generic package providing a single dimension array abstraction where the
12609 length of the array can be dynamically modified.
12612 This package provides a facility similar to that of @code{GNAT.Table},
12613 except that this package declares a type that can be used to define
12614 dynamic instances of the table, while an instantiation of
12615 @code{GNAT.Table} creates a single instance of the table type.
12617 @node GNAT.Exception_Actions (g-excact.ads)
12618 @section @code{GNAT.Exception_Actions} (@file{g-excact.ads})
12619 @cindex @code{GNAT.Exception_Actions} (@file{g-excact.ads})
12620 @cindex Exception actions
12623 Provides callbacks when an exception is raised. Callbacks can be registered
12624 for specific exceptions, or when any exception is raised. This
12625 can be used for instance to force a core dump to ease debugging.
12627 @node GNAT.Exception_Traces (g-exctra.ads)
12628 @section @code{GNAT.Exception_Traces} (@file{g-exctra.ads})
12629 @cindex @code{GNAT.Exception_Traces} (@file{g-exctra.ads})
12630 @cindex Exception traces
12634 Provides an interface allowing to control automatic output upon exception
12637 @node GNAT.Exceptions (g-except.ads)
12638 @section @code{GNAT.Exceptions} (@file{g-expect.ads})
12639 @cindex @code{GNAT.Exceptions} (@file{g-expect.ads})
12640 @cindex Exceptions, Pure
12641 @cindex Pure packages, exceptions
12644 Normally it is not possible to raise an exception with
12645 a message from a subprogram in a pure package, since the
12646 necessary types and subprograms are in @code{Ada.Exceptions}
12647 which is not a pure unit. @code{GNAT.Exceptions} provides a
12648 facility for getting around this limitation for a few
12649 predefined exceptions, and for example allow raising
12650 @code{Constraint_Error} with a message from a pure subprogram.
12652 @node GNAT.Expect (g-expect.ads)
12653 @section @code{GNAT.Expect} (@file{g-expect.ads})
12654 @cindex @code{GNAT.Expect} (@file{g-expect.ads})
12657 Provides a set of subprograms similar to what is available
12658 with the standard Tcl Expect tool.
12659 It allows you to easily spawn and communicate with an external process.
12660 You can send commands or inputs to the process, and compare the output
12661 with some expected regular expression. Currently @code{GNAT.Expect}
12662 is implemented on all native GNAT ports except for OpenVMS@.
12663 It is not implemented for cross ports, and in particular is not
12664 implemented for VxWorks or LynxOS@.
12666 @node GNAT.Float_Control (g-flocon.ads)
12667 @section @code{GNAT.Float_Control} (@file{g-flocon.ads})
12668 @cindex @code{GNAT.Float_Control} (@file{g-flocon.ads})
12669 @cindex Floating-Point Processor
12672 Provides an interface for resetting the floating-point processor into the
12673 mode required for correct semantic operation in Ada. Some third party
12674 library calls may cause this mode to be modified, and the Reset procedure
12675 in this package can be used to reestablish the required mode.
12677 @node GNAT.Heap_Sort (g-heasor.ads)
12678 @section @code{GNAT.Heap_Sort} (@file{g-heasor.ads})
12679 @cindex @code{GNAT.Heap_Sort} (@file{g-heasor.ads})
12683 Provides a general implementation of heap sort usable for sorting arbitrary
12684 data items. Exchange and comparison procedures are provided by passing
12685 access-to-procedure values. The algorithm used is a modified heap sort
12686 that performs approximately N*log(N) comparisons in the worst case.
12688 @node GNAT.Heap_Sort_A (g-hesora.ads)
12689 @section @code{GNAT.Heap_Sort_A} (@file{g-hesora.ads})
12690 @cindex @code{GNAT.Heap_Sort_A} (@file{g-hesora.ads})
12694 Provides a general implementation of heap sort usable for sorting arbitrary
12695 data items. Move and comparison procedures are provided by passing
12696 access-to-procedure values. The algorithm used is a modified heap sort
12697 that performs approximately N*log(N) comparisons in the worst case.
12698 This differs from @code{GNAT.Heap_Sort} in having a less convenient
12699 interface, but may be slightly more efficient.
12701 @node GNAT.Heap_Sort_G (g-hesorg.ads)
12702 @section @code{GNAT.Heap_Sort_G} (@file{g-hesorg.ads})
12703 @cindex @code{GNAT.Heap_Sort_G} (@file{g-hesorg.ads})
12707 Similar to @code{Heap_Sort_A} except that the move and sorting procedures
12708 are provided as generic parameters, this improves efficiency, especially
12709 if the procedures can be inlined, at the expense of duplicating code for
12710 multiple instantiations.
12712 @node GNAT.HTable (g-htable.ads)
12713 @section @code{GNAT.HTable} (@file{g-htable.ads})
12714 @cindex @code{GNAT.HTable} (@file{g-htable.ads})
12715 @cindex Hash tables
12718 A generic implementation of hash tables that can be used to hash arbitrary
12719 data. Provides two approaches, one a simple static approach, and the other
12720 allowing arbitrary dynamic hash tables.
12722 @node GNAT.IO (g-io.ads)
12723 @section @code{GNAT.IO} (@file{g-io.ads})
12724 @cindex @code{GNAT.IO} (@file{g-io.ads})
12726 @cindex Input/Output facilities
12729 A simple preelaborable input-output package that provides a subset of
12730 simple Text_IO functions for reading characters and strings from
12731 Standard_Input, and writing characters, strings and integers to either
12732 Standard_Output or Standard_Error.
12734 @node GNAT.IO_Aux (g-io_aux.ads)
12735 @section @code{GNAT.IO_Aux} (@file{g-io_aux.ads})
12736 @cindex @code{GNAT.IO_Aux} (@file{g-io_aux.ads})
12738 @cindex Input/Output facilities
12740 Provides some auxiliary functions for use with Text_IO, including a test
12741 for whether a file exists, and functions for reading a line of text.
12743 @node GNAT.Lock_Files (g-locfil.ads)
12744 @section @code{GNAT.Lock_Files} (@file{g-locfil.ads})
12745 @cindex @code{GNAT.Lock_Files} (@file{g-locfil.ads})
12746 @cindex File locking
12747 @cindex Locking using files
12750 Provides a general interface for using files as locks. Can be used for
12751 providing program level synchronization.
12753 @node GNAT.MD5 (g-md5.ads)
12754 @section @code{GNAT.MD5} (@file{g-md5.ads})
12755 @cindex @code{GNAT.MD5} (@file{g-md5.ads})
12756 @cindex Message Digest MD5
12759 Implements the MD5 Message-Digest Algorithm as described in RFC 1321.
12761 @node GNAT.Memory_Dump (g-memdum.ads)
12762 @section @code{GNAT.Memory_Dump} (@file{g-memdum.ads})
12763 @cindex @code{GNAT.Memory_Dump} (@file{g-memdum.ads})
12764 @cindex Dump Memory
12767 Provides a convenient routine for dumping raw memory to either the
12768 standard output or standard error files. Uses GNAT.IO for actual
12771 @node GNAT.Most_Recent_Exception (g-moreex.ads)
12772 @section @code{GNAT.Most_Recent_Exception} (@file{g-moreex.ads})
12773 @cindex @code{GNAT.Most_Recent_Exception} (@file{g-moreex.ads})
12774 @cindex Exception, obtaining most recent
12777 Provides access to the most recently raised exception. Can be used for
12778 various logging purposes, including duplicating functionality of some
12779 Ada 83 implementation dependent extensions.
12781 @node GNAT.OS_Lib (g-os_lib.ads)
12782 @section @code{GNAT.OS_Lib} (@file{g-os_lib.ads})
12783 @cindex @code{GNAT.OS_Lib} (@file{g-os_lib.ads})
12784 @cindex Operating System interface
12785 @cindex Spawn capability
12788 Provides a range of target independent operating system interface functions,
12789 including time/date management, file operations, subprocess management,
12790 including a portable spawn procedure, and access to environment variables
12791 and error return codes.
12793 @node GNAT.Perfect_Hash_Generators (g-pehage.ads)
12794 @section @code{GNAT.Perfect_Hash_Generators} (@file{g-pehage.ads})
12795 @cindex @code{GNAT.Perfect_Hash_Generators} (@file{g-pehage.ads})
12796 @cindex Hash functions
12799 Provides a generator of static minimal perfect hash functions. No
12800 collisions occur and each item can be retrieved from the table in one
12801 probe (perfect property). The hash table size corresponds to the exact
12802 size of the key set and no larger (minimal property). The key set has to
12803 be know in advance (static property). The hash functions are also order
12804 preserving. If w2 is inserted after w1 in the generator, their
12805 hashcode are in the same order. These hashing functions are very
12806 convenient for use with realtime applications.
12808 @node GNAT.Regexp (g-regexp.ads)
12809 @section @code{GNAT.Regexp} (@file{g-regexp.ads})
12810 @cindex @code{GNAT.Regexp} (@file{g-regexp.ads})
12811 @cindex Regular expressions
12812 @cindex Pattern matching
12815 A simple implementation of regular expressions, using a subset of regular
12816 expression syntax copied from familiar Unix style utilities. This is the
12817 simples of the three pattern matching packages provided, and is particularly
12818 suitable for ``file globbing'' applications.
12820 @node GNAT.Registry (g-regist.ads)
12821 @section @code{GNAT.Registry} (@file{g-regist.ads})
12822 @cindex @code{GNAT.Registry} (@file{g-regist.ads})
12823 @cindex Windows Registry
12826 This is a high level binding to the Windows registry. It is possible to
12827 do simple things like reading a key value, creating a new key. For full
12828 registry API, but at a lower level of abstraction, refer to the Win32.Winreg
12829 package provided with the Win32Ada binding
12831 @node GNAT.Regpat (g-regpat.ads)
12832 @section @code{GNAT.Regpat} (@file{g-regpat.ads})
12833 @cindex @code{GNAT.Regpat} (@file{g-regpat.ads})
12834 @cindex Regular expressions
12835 @cindex Pattern matching
12838 A complete implementation of Unix-style regular expression matching, copied
12839 from the original V7 style regular expression library written in C by
12840 Henry Spencer (and binary compatible with this C library).
12842 @node GNAT.Secondary_Stack_Info (g-sestin.ads)
12843 @section @code{GNAT.Secondary_Stack_Info} (@file{g-sestin.ads})
12844 @cindex @code{GNAT.Secondary_Stack_Info} (@file{g-sestin.ads})
12845 @cindex Secondary Stack Info
12848 Provide the capability to query the high water mark of the current task's
12851 @node GNAT.Semaphores (g-semaph.ads)
12852 @section @code{GNAT.Semaphores} (@file{g-semaph.ads})
12853 @cindex @code{GNAT.Semaphores} (@file{g-semaph.ads})
12857 Provides classic counting and binary semaphores using protected types.
12859 @node GNAT.Signals (g-signal.ads)
12860 @section @code{GNAT.Signals} (@file{g-signal.ads})
12861 @cindex @code{GNAT.Signals} (@file{g-signal.ads})
12865 Provides the ability to manipulate the blocked status of signals on supported
12868 @node GNAT.Sockets (g-socket.ads)
12869 @section @code{GNAT.Sockets} (@file{g-socket.ads})
12870 @cindex @code{GNAT.Sockets} (@file{g-socket.ads})
12874 A high level and portable interface to develop sockets based applications.
12875 This package is based on the sockets thin binding found in
12876 @code{GNAT.Sockets.Thin}. Currently @code{GNAT.Sockets} is implemented
12877 on all native GNAT ports except for OpenVMS@. It is not implemented
12878 for the LynxOS@ cross port.
12880 @node GNAT.Source_Info (g-souinf.ads)
12881 @section @code{GNAT.Source_Info} (@file{g-souinf.ads})
12882 @cindex @code{GNAT.Source_Info} (@file{g-souinf.ads})
12883 @cindex Source Information
12886 Provides subprograms that give access to source code information known at
12887 compile time, such as the current file name and line number.
12889 @node GNAT.Spell_Checker (g-speche.ads)
12890 @section @code{GNAT.Spell_Checker} (@file{g-speche.ads})
12891 @cindex @code{GNAT.Spell_Checker} (@file{g-speche.ads})
12892 @cindex Spell checking
12895 Provides a function for determining whether one string is a plausible
12896 near misspelling of another string.
12898 @node GNAT.Spitbol.Patterns (g-spipat.ads)
12899 @section @code{GNAT.Spitbol.Patterns} (@file{g-spipat.ads})
12900 @cindex @code{GNAT.Spitbol.Patterns} (@file{g-spipat.ads})
12901 @cindex SPITBOL pattern matching
12902 @cindex Pattern matching
12905 A complete implementation of SNOBOL4 style pattern matching. This is the
12906 most elaborate of the pattern matching packages provided. It fully duplicates
12907 the SNOBOL4 dynamic pattern construction and matching capabilities, using the
12908 efficient algorithm developed by Robert Dewar for the SPITBOL system.
12910 @node GNAT.Spitbol (g-spitbo.ads)
12911 @section @code{GNAT.Spitbol} (@file{g-spitbo.ads})
12912 @cindex @code{GNAT.Spitbol} (@file{g-spitbo.ads})
12913 @cindex SPITBOL interface
12916 The top level package of the collection of SPITBOL-style functionality, this
12917 package provides basic SNOBOL4 string manipulation functions, such as
12918 Pad, Reverse, Trim, Substr capability, as well as a generic table function
12919 useful for constructing arbitrary mappings from strings in the style of
12920 the SNOBOL4 TABLE function.
12922 @node GNAT.Spitbol.Table_Boolean (g-sptabo.ads)
12923 @section @code{GNAT.Spitbol.Table_Boolean} (@file{g-sptabo.ads})
12924 @cindex @code{GNAT.Spitbol.Table_Boolean} (@file{g-sptabo.ads})
12925 @cindex Sets of strings
12926 @cindex SPITBOL Tables
12929 A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table}
12930 for type @code{Standard.Boolean}, giving an implementation of sets of
12933 @node GNAT.Spitbol.Table_Integer (g-sptain.ads)
12934 @section @code{GNAT.Spitbol.Table_Integer} (@file{g-sptain.ads})
12935 @cindex @code{GNAT.Spitbol.Table_Integer} (@file{g-sptain.ads})
12936 @cindex Integer maps
12938 @cindex SPITBOL Tables
12941 A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table}
12942 for type @code{Standard.Integer}, giving an implementation of maps
12943 from string to integer values.
12945 @node GNAT.Spitbol.Table_VString (g-sptavs.ads)
12946 @section @code{GNAT.Spitbol.Table_VString} (@file{g-sptavs.ads})
12947 @cindex @code{GNAT.Spitbol.Table_VString} (@file{g-sptavs.ads})
12948 @cindex String maps
12950 @cindex SPITBOL Tables
12953 A library level of instantiation of @code{GNAT.Spitbol.Patterns.Table} for
12954 a variable length string type, giving an implementation of general
12955 maps from strings to strings.
12957 @node GNAT.Strings (g-string.ads)
12958 @section @code{GNAT.Strings} (@file{g-string.ads})
12959 @cindex @code{GNAT.Strings} (@file{g-string.ads})
12962 Common String access types and related subprograms. Basically it
12963 defines a string access and an array of string access types.
12965 @node GNAT.String_Split (g-strspl.ads)
12966 @section @code{GNAT.String_Split} (@file{g-strspl.ads})
12967 @cindex @code{GNAT.String_Split} (@file{g-strspl.ads})
12968 @cindex String splitter
12971 Useful string manipulation routines: given a set of separators, split
12972 a string wherever the separators appear, and provide direct access
12973 to the resulting slices. This package is instantiated from
12974 @code{GNAT.Array_Split}.
12976 @node GNAT.UTF_32 (g-utf_32.ads)
12977 @section @code{GNAT.UTF_32} (@file{g-table.ads})
12978 @cindex @code{GNAT.UTF_32} (@file{g-table.ads})
12979 @cindex Wide character codes
12982 This is a package intended to be used in conjunction with the
12983 @code{Wide_Character} type in Ada 95 and the
12984 @code{Wide_Wide_Character} type in Ada 2005 (available
12985 in @code{GNAT} in Ada 2005 mode). This package contains
12986 Unicode categorization routines, as well as lexical
12987 categorization routines corresponding to the Ada 2005
12988 lexical rules for identifiers and strings, and also a
12989 lower case to upper case fold routine corresponding to
12990 the Ada 2005 rules for identifier equivalence.
12992 @node GNAT.Table (g-table.ads)
12993 @section @code{GNAT.Table} (@file{g-table.ads})
12994 @cindex @code{GNAT.Table} (@file{g-table.ads})
12995 @cindex Table implementation
12996 @cindex Arrays, extendable
12999 A generic package providing a single dimension array abstraction where the
13000 length of the array can be dynamically modified.
13003 This package provides a facility similar to that of @code{GNAT.Dynamic_Tables},
13004 except that this package declares a single instance of the table type,
13005 while an instantiation of @code{GNAT.Dynamic_Tables} creates a type that can be
13006 used to define dynamic instances of the table.
13008 @node GNAT.Task_Lock (g-tasloc.ads)
13009 @section @code{GNAT.Task_Lock} (@file{g-tasloc.ads})
13010 @cindex @code{GNAT.Task_Lock} (@file{g-tasloc.ads})
13011 @cindex Task synchronization
13012 @cindex Task locking
13016 A very simple facility for locking and unlocking sections of code using a
13017 single global task lock. Appropriate for use in situations where contention
13018 between tasks is very rarely expected.
13020 @node GNAT.Threads (g-thread.ads)
13021 @section @code{GNAT.Threads} (@file{g-thread.ads})
13022 @cindex @code{GNAT.Threads} (@file{g-thread.ads})
13023 @cindex Foreign threads
13024 @cindex Threads, foreign
13027 Provides facilities for creating and destroying threads with explicit calls.
13028 These threads are known to the GNAT run-time system. These subprograms are
13029 exported C-convention procedures intended to be called from foreign code.
13030 By using these primitives rather than directly calling operating systems
13031 routines, compatibility with the Ada tasking run-time is provided.
13033 @node GNAT.Traceback (g-traceb.ads)
13034 @section @code{GNAT.Traceback} (@file{g-traceb.ads})
13035 @cindex @code{GNAT.Traceback} (@file{g-traceb.ads})
13036 @cindex Trace back facilities
13039 Provides a facility for obtaining non-symbolic traceback information, useful
13040 in various debugging situations.
13042 @node GNAT.Traceback.Symbolic (g-trasym.ads)
13043 @section @code{GNAT.Traceback.Symbolic} (@file{g-trasym.ads})
13044 @cindex @code{GNAT.Traceback.Symbolic} (@file{g-trasym.ads})
13045 @cindex Trace back facilities
13048 Provides symbolic traceback information that includes the subprogram
13049 name and line number information.
13051 @node GNAT.Wide_String_Split (g-wistsp.ads)
13052 @section @code{GNAT.Wide_String_Split} (@file{g-wistsp.ads})
13053 @cindex @code{GNAT.Wide_String_Split} (@file{g-wistsp.ads})
13054 @cindex Wide_String splitter
13057 Useful wide string manipulation routines: given a set of separators, split
13058 a wide string wherever the separators appear, and provide direct access
13059 to the resulting slices. This package is instantiated from
13060 @code{GNAT.Array_Split}.
13062 @node GNAT.Wide_Wide_String_Split (g-zistsp.ads)
13063 @section @code{GNAT.Wide_Wide_String_Split} (@file{g-zistsp.ads})
13064 @cindex @code{GNAT.Wide_Wide_String_Split} (@file{g-zistsp.ads})
13065 @cindex Wide_Wide_String splitter
13068 Useful wide wide string manipulation routines: given a set of separators, split
13069 a wide wide string wherever the separators appear, and provide direct access
13070 to the resulting slices. This package is instantiated from
13071 @code{GNAT.Array_Split}.
13073 @node Interfaces.C.Extensions (i-cexten.ads)
13074 @section @code{Interfaces.C.Extensions} (@file{i-cexten.ads})
13075 @cindex @code{Interfaces.C.Extensions} (@file{i-cexten.ads})
13078 This package contains additional C-related definitions, intended
13079 for use with either manually or automatically generated bindings
13082 @node Interfaces.C.Streams (i-cstrea.ads)
13083 @section @code{Interfaces.C.Streams} (@file{i-cstrea.ads})
13084 @cindex @code{Interfaces.C.Streams} (@file{i-cstrea.ads})
13085 @cindex C streams, interfacing
13088 This package is a binding for the most commonly used operations
13091 @node Interfaces.CPP (i-cpp.ads)
13092 @section @code{Interfaces.CPP} (@file{i-cpp.ads})
13093 @cindex @code{Interfaces.CPP} (@file{i-cpp.ads})
13094 @cindex C++ interfacing
13095 @cindex Interfacing, to C++
13098 This package provides facilities for use in interfacing to C++. It
13099 is primarily intended to be used in connection with automated tools
13100 for the generation of C++ interfaces.
13102 @node Interfaces.Os2lib (i-os2lib.ads)
13103 @section @code{Interfaces.Os2lib} (@file{i-os2lib.ads})
13104 @cindex @code{Interfaces.Os2lib} (@file{i-os2lib.ads})
13105 @cindex Interfacing, to OS/2
13106 @cindex OS/2 interfacing
13109 This package provides interface definitions to the OS/2 library.
13110 It is a thin binding which is a direct translation of the
13111 various @file{<bse@.h>} files.
13113 @node Interfaces.Os2lib.Errors (i-os2err.ads)
13114 @section @code{Interfaces.Os2lib.Errors} (@file{i-os2err.ads})
13115 @cindex @code{Interfaces.Os2lib.Errors} (@file{i-os2err.ads})
13116 @cindex OS/2 Error codes
13117 @cindex Interfacing, to OS/2
13118 @cindex OS/2 interfacing
13121 This package provides definitions of the OS/2 error codes.
13123 @node Interfaces.Os2lib.Synchronization (i-os2syn.ads)
13124 @section @code{Interfaces.Os2lib.Synchronization} (@file{i-os2syn.ads})
13125 @cindex @code{Interfaces.Os2lib.Synchronization} (@file{i-os2syn.ads})
13126 @cindex Interfacing, to OS/2
13127 @cindex Synchronization, OS/2
13128 @cindex OS/2 synchronization primitives
13131 This is a child package that provides definitions for interfacing
13132 to the @code{OS/2} synchronization primitives.
13134 @node Interfaces.Os2lib.Threads (i-os2thr.ads)
13135 @section @code{Interfaces.Os2lib.Threads} (@file{i-os2thr.ads})
13136 @cindex @code{Interfaces.Os2lib.Threads} (@file{i-os2thr.ads})
13137 @cindex Interfacing, to OS/2
13138 @cindex Thread control, OS/2
13139 @cindex OS/2 thread interfacing
13142 This is a child package that provides definitions for interfacing
13143 to the @code{OS/2} thread primitives.
13145 @node Interfaces.Packed_Decimal (i-pacdec.ads)
13146 @section @code{Interfaces.Packed_Decimal} (@file{i-pacdec.ads})
13147 @cindex @code{Interfaces.Packed_Decimal} (@file{i-pacdec.ads})
13148 @cindex IBM Packed Format
13149 @cindex Packed Decimal
13152 This package provides a set of routines for conversions to and
13153 from a packed decimal format compatible with that used on IBM
13156 @node Interfaces.VxWorks (i-vxwork.ads)
13157 @section @code{Interfaces.VxWorks} (@file{i-vxwork.ads})
13158 @cindex @code{Interfaces.VxWorks} (@file{i-vxwork.ads})
13159 @cindex Interfacing to VxWorks
13160 @cindex VxWorks, interfacing
13163 This package provides a limited binding to the VxWorks API.
13164 In particular, it interfaces with the
13165 VxWorks hardware interrupt facilities.
13167 @node Interfaces.VxWorks.IO (i-vxwoio.ads)
13168 @section @code{Interfaces.VxWorks.IO} (@file{i-vxwoio.ads})
13169 @cindex @code{Interfaces.VxWorks.IO} (@file{i-vxwoio.ads})
13170 @cindex Interfacing to VxWorks' I/O
13171 @cindex VxWorks, I/O interfacing
13172 @cindex VxWorks, Get_Immediate
13173 @cindex Get_Immediate, VxWorks
13176 This package provides a binding to the ioctl (IO/Control)
13177 function of VxWorks, defining a set of option values and
13178 function codes. A particular use of this package is
13179 to enable the use of Get_Immediate under VxWorks.
13181 @node System.Address_Image (s-addima.ads)
13182 @section @code{System.Address_Image} (@file{s-addima.ads})
13183 @cindex @code{System.Address_Image} (@file{s-addima.ads})
13184 @cindex Address image
13185 @cindex Image, of an address
13188 This function provides a useful debugging
13189 function that gives an (implementation dependent)
13190 string which identifies an address.
13192 @node System.Assertions (s-assert.ads)
13193 @section @code{System.Assertions} (@file{s-assert.ads})
13194 @cindex @code{System.Assertions} (@file{s-assert.ads})
13196 @cindex Assert_Failure, exception
13199 This package provides the declaration of the exception raised
13200 by an run-time assertion failure, as well as the routine that
13201 is used internally to raise this assertion.
13203 @node System.Memory (s-memory.ads)
13204 @section @code{System.Memory} (@file{s-memory.ads})
13205 @cindex @code{System.Memory} (@file{s-memory.ads})
13206 @cindex Memory allocation
13209 This package provides the interface to the low level routines used
13210 by the generated code for allocation and freeing storage for the
13211 default storage pool (analogous to the C routines malloc and free.
13212 It also provides a reallocation interface analogous to the C routine
13213 realloc. The body of this unit may be modified to provide alternative
13214 allocation mechanisms for the default pool, and in addition, direct
13215 calls to this unit may be made for low level allocation uses (for
13216 example see the body of @code{GNAT.Tables}).
13218 @node System.Partition_Interface (s-parint.ads)
13219 @section @code{System.Partition_Interface} (@file{s-parint.ads})
13220 @cindex @code{System.Partition_Interface} (@file{s-parint.ads})
13221 @cindex Partition interfacing functions
13224 This package provides facilities for partition interfacing. It
13225 is used primarily in a distribution context when using Annex E
13228 @node System.Restrictions (s-restri.ads)
13229 @section @code{System.Restrictions} (@file{s-restri.ads})
13230 @cindex @code{System.Restrictions} (@file{s-restri.ads})
13231 @cindex Run-time restrictions access
13234 This package provides facilities for accessing at run-time
13235 the status of restrictions specified at compile time for
13236 the partition. Information is available both with regard
13237 to actual restrictions specified, and with regard to
13238 compiler determined information on which restrictions
13239 are violated by one or more packages in the partition.
13241 @node System.Rident (s-rident.ads)
13242 @section @code{System.Rident} (@file{s-rident.ads})
13243 @cindex @code{System.Rident} (@file{s-rident.ads})
13244 @cindex Restrictions definitions
13247 This package provides definitions of the restrictions
13248 identifiers supported by GNAT, and also the format of
13249 the restrictions provided in package System.Restrictions.
13250 It is not normally necessary to @code{with} this generic package
13251 since the necessary instantiation is included in
13252 package System.Restrictions.
13254 @node System.Task_Info (s-tasinf.ads)
13255 @section @code{System.Task_Info} (@file{s-tasinf.ads})
13256 @cindex @code{System.Task_Info} (@file{s-tasinf.ads})
13257 @cindex Task_Info pragma
13260 This package provides target dependent functionality that is used
13261 to support the @code{Task_Info} pragma
13263 @node System.Wch_Cnv (s-wchcnv.ads)
13264 @section @code{System.Wch_Cnv} (@file{s-wchcnv.ads})
13265 @cindex @code{System.Wch_Cnv} (@file{s-wchcnv.ads})
13266 @cindex Wide Character, Representation
13267 @cindex Wide String, Conversion
13268 @cindex Representation of wide characters
13271 This package provides routines for converting between
13272 wide and wide wide characters and a representation as a value of type
13273 @code{Standard.String}, using a specified wide character
13274 encoding method. It uses definitions in
13275 package @code{System.Wch_Con}.
13277 @node System.Wch_Con (s-wchcon.ads)
13278 @section @code{System.Wch_Con} (@file{s-wchcon.ads})
13279 @cindex @code{System.Wch_Con} (@file{s-wchcon.ads})
13282 This package provides definitions and descriptions of
13283 the various methods used for encoding wide characters
13284 in ordinary strings. These definitions are used by
13285 the package @code{System.Wch_Cnv}.
13287 @node Interfacing to Other Languages
13288 @chapter Interfacing to Other Languages
13290 The facilities in annex B of the Ada 95 Reference Manual are fully
13291 implemented in GNAT, and in addition, a full interface to C++ is
13295 * Interfacing to C::
13296 * Interfacing to C++::
13297 * Interfacing to COBOL::
13298 * Interfacing to Fortran::
13299 * Interfacing to non-GNAT Ada code::
13302 @node Interfacing to C
13303 @section Interfacing to C
13306 Interfacing to C with GNAT can use one of two approaches:
13310 The types in the package @code{Interfaces.C} may be used.
13312 Standard Ada types may be used directly. This may be less portable to
13313 other compilers, but will work on all GNAT compilers, which guarantee
13314 correspondence between the C and Ada types.
13318 Pragma @code{Convention C} may be applied to Ada types, but mostly has no
13319 effect, since this is the default. The following table shows the
13320 correspondence between Ada scalar types and the corresponding C types.
13325 @item Short_Integer
13327 @item Short_Short_Integer
13331 @item Long_Long_Integer
13339 @item Long_Long_Float
13340 This is the longest floating-point type supported by the hardware.
13344 Additionally, there are the following general correspondences between Ada
13348 Ada enumeration types map to C enumeration types directly if pragma
13349 @code{Convention C} is specified, which causes them to have int
13350 length. Without pragma @code{Convention C}, Ada enumeration types map to
13351 8, 16, or 32 bits (i.e.@: C types @code{signed char}, @code{short},
13352 @code{int}, respectively) depending on the number of values passed.
13353 This is the only case in which pragma @code{Convention C} affects the
13354 representation of an Ada type.
13357 Ada access types map to C pointers, except for the case of pointers to
13358 unconstrained types in Ada, which have no direct C equivalent.
13361 Ada arrays map directly to C arrays.
13364 Ada records map directly to C structures.
13367 Packed Ada records map to C structures where all members are bit fields
13368 of the length corresponding to the @code{@var{type}'Size} value in Ada.
13371 @node Interfacing to C++
13372 @section Interfacing to C++
13375 The interface to C++ makes use of the following pragmas, which are
13376 primarily intended to be constructed automatically using a binding generator
13377 tool, although it is possible to construct them by hand. No suitable binding
13378 generator tool is supplied with GNAT though.
13380 Using these pragmas it is possible to achieve complete
13381 inter-operability between Ada tagged types and C class definitions.
13382 See @ref{Implementation Defined Pragmas}, for more details.
13385 @item pragma CPP_Class ([Entity =>] @var{local_NAME})
13386 The argument denotes an entity in the current declarative region that is
13387 declared as a tagged or untagged record type. It indicates that the type
13388 corresponds to an externally declared C++ class type, and is to be laid
13389 out the same way that C++ would lay out the type.
13391 @item pragma CPP_Constructor ([Entity =>] @var{local_NAME})
13392 This pragma identifies an imported function (imported in the usual way
13393 with pragma @code{Import}) as corresponding to a C++ constructor.
13395 @item pragma CPP_Vtable @dots{}
13396 One @code{CPP_Vtable} pragma can be present for each component of type
13397 @code{CPP.Interfaces.Vtable_Ptr} in a record to which pragma @code{CPP_Class}
13401 @node Interfacing to COBOL
13402 @section Interfacing to COBOL
13405 Interfacing to COBOL is achieved as described in section B.4 of
13406 the Ada 95 reference manual.
13408 @node Interfacing to Fortran
13409 @section Interfacing to Fortran
13412 Interfacing to Fortran is achieved as described in section B.5 of the
13413 reference manual. The pragma @code{Convention Fortran}, applied to a
13414 multi-dimensional array causes the array to be stored in column-major
13415 order as required for convenient interface to Fortran.
13417 @node Interfacing to non-GNAT Ada code
13418 @section Interfacing to non-GNAT Ada code
13420 It is possible to specify the convention @code{Ada} in a pragma
13421 @code{Import} or pragma @code{Export}. However this refers to
13422 the calling conventions used by GNAT, which may or may not be
13423 similar enough to those used by some other Ada 83 or Ada 95
13424 compiler to allow interoperation.
13426 If arguments types are kept simple, and if the foreign compiler generally
13427 follows system calling conventions, then it may be possible to integrate
13428 files compiled by other Ada compilers, provided that the elaboration
13429 issues are adequately addressed (for example by eliminating the
13430 need for any load time elaboration).
13432 In particular, GNAT running on VMS is designed to
13433 be highly compatible with the DEC Ada 83 compiler, so this is one
13434 case in which it is possible to import foreign units of this type,
13435 provided that the data items passed are restricted to simple scalar
13436 values or simple record types without variants, or simple array
13437 types with fixed bounds.
13439 @node Specialized Needs Annexes
13440 @chapter Specialized Needs Annexes
13443 Ada 95 defines a number of specialized needs annexes, which are not
13444 required in all implementations. However, as described in this chapter,
13445 GNAT implements all of these special needs annexes:
13448 @item Systems Programming (Annex C)
13449 The Systems Programming Annex is fully implemented.
13451 @item Real-Time Systems (Annex D)
13452 The Real-Time Systems Annex is fully implemented.
13454 @item Distributed Systems (Annex E)
13455 Stub generation is fully implemented in the GNAT compiler. In addition,
13456 a complete compatible PCS is available as part of the GLADE system,
13457 a separate product. When the two
13458 products are used in conjunction, this annex is fully implemented.
13460 @item Information Systems (Annex F)
13461 The Information Systems annex is fully implemented.
13463 @item Numerics (Annex G)
13464 The Numerics Annex is fully implemented.
13466 @item Safety and Security (Annex H)
13467 The Safety and Security annex is fully implemented.
13470 @node Implementation of Specific Ada Features
13471 @chapter Implementation of Specific Ada Features
13474 This chapter describes the GNAT implementation of several Ada language
13478 * Machine Code Insertions::
13479 * GNAT Implementation of Tasking::
13480 * GNAT Implementation of Shared Passive Packages::
13481 * Code Generation for Array Aggregates::
13482 * The Size of Discriminated Records with Default Discriminants::
13485 @node Machine Code Insertions
13486 @section Machine Code Insertions
13489 Package @code{Machine_Code} provides machine code support as described
13490 in the Ada 95 Reference Manual in two separate forms:
13493 Machine code statements, consisting of qualified expressions that
13494 fit the requirements of RM section 13.8.
13496 An intrinsic callable procedure, providing an alternative mechanism of
13497 including machine instructions in a subprogram.
13501 The two features are similar, and both are closely related to the mechanism
13502 provided by the asm instruction in the GNU C compiler. Full understanding
13503 and use of the facilities in this package requires understanding the asm
13504 instruction as described in @cite{Using the GNU Compiler Collection (GCC)}
13505 by Richard Stallman. The relevant section is titled ``Extensions to the C
13506 Language Family'' -> ``Assembler Instructions with C Expression Operands''.
13508 Calls to the function @code{Asm} and the procedure @code{Asm} have identical
13509 semantic restrictions and effects as described below. Both are provided so
13510 that the procedure call can be used as a statement, and the function call
13511 can be used to form a code_statement.
13513 The first example given in the GCC documentation is the C @code{asm}
13516 asm ("fsinx %1 %0" : "=f" (result) : "f" (angle));
13520 The equivalent can be written for GNAT as:
13522 @smallexample @c ada
13523 Asm ("fsinx %1 %0",
13524 My_Float'Asm_Output ("=f", result),
13525 My_Float'Asm_Input ("f", angle));
13529 The first argument to @code{Asm} is the assembler template, and is
13530 identical to what is used in GNU C@. This string must be a static
13531 expression. The second argument is the output operand list. It is
13532 either a single @code{Asm_Output} attribute reference, or a list of such
13533 references enclosed in parentheses (technically an array aggregate of
13536 The @code{Asm_Output} attribute denotes a function that takes two
13537 parameters. The first is a string, the second is the name of a variable
13538 of the type designated by the attribute prefix. The first (string)
13539 argument is required to be a static expression and designates the
13540 constraint for the parameter (e.g.@: what kind of register is
13541 required). The second argument is the variable to be updated with the
13542 result. The possible values for constraint are the same as those used in
13543 the RTL, and are dependent on the configuration file used to build the
13544 GCC back end. If there are no output operands, then this argument may
13545 either be omitted, or explicitly given as @code{No_Output_Operands}.
13547 The second argument of @code{@var{my_float}'Asm_Output} functions as
13548 though it were an @code{out} parameter, which is a little curious, but
13549 all names have the form of expressions, so there is no syntactic
13550 irregularity, even though normally functions would not be permitted
13551 @code{out} parameters. The third argument is the list of input
13552 operands. It is either a single @code{Asm_Input} attribute reference, or
13553 a list of such references enclosed in parentheses (technically an array
13554 aggregate of such references).
13556 The @code{Asm_Input} attribute denotes a function that takes two
13557 parameters. The first is a string, the second is an expression of the
13558 type designated by the prefix. The first (string) argument is required
13559 to be a static expression, and is the constraint for the parameter,
13560 (e.g.@: what kind of register is required). The second argument is the
13561 value to be used as the input argument. The possible values for the
13562 constant are the same as those used in the RTL, and are dependent on
13563 the configuration file used to built the GCC back end.
13565 If there are no input operands, this argument may either be omitted, or
13566 explicitly given as @code{No_Input_Operands}. The fourth argument, not
13567 present in the above example, is a list of register names, called the
13568 @dfn{clobber} argument. This argument, if given, must be a static string
13569 expression, and is a space or comma separated list of names of registers
13570 that must be considered destroyed as a result of the @code{Asm} call. If
13571 this argument is the null string (the default value), then the code
13572 generator assumes that no additional registers are destroyed.
13574 The fifth argument, not present in the above example, called the
13575 @dfn{volatile} argument, is by default @code{False}. It can be set to
13576 the literal value @code{True} to indicate to the code generator that all
13577 optimizations with respect to the instruction specified should be
13578 suppressed, and that in particular, for an instruction that has outputs,
13579 the instruction will still be generated, even if none of the outputs are
13580 used. See the full description in the GCC manual for further details.
13582 The @code{Asm} subprograms may be used in two ways. First the procedure
13583 forms can be used anywhere a procedure call would be valid, and
13584 correspond to what the RM calls ``intrinsic'' routines. Such calls can
13585 be used to intersperse machine instructions with other Ada statements.
13586 Second, the function forms, which return a dummy value of the limited
13587 private type @code{Asm_Insn}, can be used in code statements, and indeed
13588 this is the only context where such calls are allowed. Code statements
13589 appear as aggregates of the form:
13591 @smallexample @c ada
13592 Asm_Insn'(Asm (@dots{}));
13593 Asm_Insn'(Asm_Volatile (@dots{}));
13597 In accordance with RM rules, such code statements are allowed only
13598 within subprograms whose entire body consists of such statements. It is
13599 not permissible to intermix such statements with other Ada statements.
13601 Typically the form using intrinsic procedure calls is more convenient
13602 and more flexible. The code statement form is provided to meet the RM
13603 suggestion that such a facility should be made available. The following
13604 is the exact syntax of the call to @code{Asm}. As usual, if named notation
13605 is used, the arguments may be given in arbitrary order, following the
13606 normal rules for use of positional and named arguments)
13610 [Template =>] static_string_EXPRESSION
13611 [,[Outputs =>] OUTPUT_OPERAND_LIST ]
13612 [,[Inputs =>] INPUT_OPERAND_LIST ]
13613 [,[Clobber =>] static_string_EXPRESSION ]
13614 [,[Volatile =>] static_boolean_EXPRESSION] )
13616 OUTPUT_OPERAND_LIST ::=
13617 [PREFIX.]No_Output_Operands
13618 | OUTPUT_OPERAND_ATTRIBUTE
13619 | (OUTPUT_OPERAND_ATTRIBUTE @{,OUTPUT_OPERAND_ATTRIBUTE@})
13621 OUTPUT_OPERAND_ATTRIBUTE ::=
13622 SUBTYPE_MARK'Asm_Output (static_string_EXPRESSION, NAME)
13624 INPUT_OPERAND_LIST ::=
13625 [PREFIX.]No_Input_Operands
13626 | INPUT_OPERAND_ATTRIBUTE
13627 | (INPUT_OPERAND_ATTRIBUTE @{,INPUT_OPERAND_ATTRIBUTE@})
13629 INPUT_OPERAND_ATTRIBUTE ::=
13630 SUBTYPE_MARK'Asm_Input (static_string_EXPRESSION, EXPRESSION)
13634 The identifiers @code{No_Input_Operands} and @code{No_Output_Operands}
13635 are declared in the package @code{Machine_Code} and must be referenced
13636 according to normal visibility rules. In particular if there is no
13637 @code{use} clause for this package, then appropriate package name
13638 qualification is required.
13640 @node GNAT Implementation of Tasking
13641 @section GNAT Implementation of Tasking
13644 This chapter outlines the basic GNAT approach to tasking (in particular,
13645 a multi-layered library for portability) and discusses issues related
13646 to compliance with the Real-Time Systems Annex.
13649 * Mapping Ada Tasks onto the Underlying Kernel Threads::
13650 * Ensuring Compliance with the Real-Time Annex::
13653 @node Mapping Ada Tasks onto the Underlying Kernel Threads
13654 @subsection Mapping Ada Tasks onto the Underlying Kernel Threads
13657 GNAT's run-time support comprises two layers:
13660 @item GNARL (GNAT Run-time Layer)
13661 @item GNULL (GNAT Low-level Library)
13665 In GNAT, Ada's tasking services rely on a platform and OS independent
13666 layer known as GNARL@. This code is responsible for implementing the
13667 correct semantics of Ada's task creation, rendezvous, protected
13670 GNARL decomposes Ada's tasking semantics into simpler lower level
13671 operations such as create a thread, set the priority of a thread,
13672 yield, create a lock, lock/unlock, etc. The spec for these low-level
13673 operations constitutes GNULLI, the GNULL Interface. This interface is
13674 directly inspired from the POSIX real-time API@.
13676 If the underlying executive or OS implements the POSIX standard
13677 faithfully, the GNULL Interface maps as is to the services offered by
13678 the underlying kernel. Otherwise, some target dependent glue code maps
13679 the services offered by the underlying kernel to the semantics expected
13682 Whatever the underlying OS (VxWorks, UNIX, OS/2, Windows NT, etc.) the
13683 key point is that each Ada task is mapped on a thread in the underlying
13684 kernel. For example, in the case of VxWorks, one Ada task = one VxWorks task.
13686 In addition Ada task priorities map onto the underlying thread priorities.
13687 Mapping Ada tasks onto the underlying kernel threads has several advantages:
13691 The underlying scheduler is used to schedule the Ada tasks. This
13692 makes Ada tasks as efficient as kernel threads from a scheduling
13696 Interaction with code written in C containing threads is eased
13697 since at the lowest level Ada tasks and C threads map onto the same
13698 underlying kernel concept.
13701 When an Ada task is blocked during I/O the remaining Ada tasks are
13705 On multiprocessor systems Ada tasks can execute in parallel.
13709 Some threads libraries offer a mechanism to fork a new process, with the
13710 child process duplicating the threads from the parent.
13712 support this functionality when the parent contains more than one task.
13713 @cindex Forking a new process
13715 @node Ensuring Compliance with the Real-Time Annex
13716 @subsection Ensuring Compliance with the Real-Time Annex
13717 @cindex Real-Time Systems Annex compliance
13720 Although mapping Ada tasks onto
13721 the underlying threads has significant advantages, it does create some
13722 complications when it comes to respecting the scheduling semantics
13723 specified in the real-time annex (Annex D).
13725 For instance the Annex D requirement for the @code{FIFO_Within_Priorities}
13726 scheduling policy states:
13729 @emph{When the active priority of a ready task that is not running
13730 changes, or the setting of its base priority takes effect, the
13731 task is removed from the ready queue for its old active priority
13732 and is added at the tail of the ready queue for its new active
13733 priority, except in the case where the active priority is lowered
13734 due to the loss of inherited priority, in which case the task is
13735 added at the head of the ready queue for its new active priority.}
13739 While most kernels do put tasks at the end of the priority queue when
13740 a task changes its priority, (which respects the main
13741 FIFO_Within_Priorities requirement), almost none keep a thread at the
13742 beginning of its priority queue when its priority drops from the loss
13743 of inherited priority.
13745 As a result most vendors have provided incomplete Annex D implementations.
13747 The GNAT run-time, has a nice cooperative solution to this problem
13748 which ensures that accurate FIFO_Within_Priorities semantics are
13751 The principle is as follows. When an Ada task T is about to start
13752 running, it checks whether some other Ada task R with the same
13753 priority as T has been suspended due to the loss of priority
13754 inheritance. If this is the case, T yields and is placed at the end of
13755 its priority queue. When R arrives at the front of the queue it
13758 Note that this simple scheme preserves the relative order of the tasks
13759 that were ready to execute in the priority queue where R has been
13762 @node GNAT Implementation of Shared Passive Packages
13763 @section GNAT Implementation of Shared Passive Packages
13764 @cindex Shared passive packages
13767 GNAT fully implements the pragma @code{Shared_Passive} for
13768 @cindex pragma @code{Shared_Passive}
13769 the purpose of designating shared passive packages.
13770 This allows the use of passive partitions in the
13771 context described in the Ada Reference Manual; i.e. for communication
13772 between separate partitions of a distributed application using the
13773 features in Annex E.
13775 @cindex Distribution Systems Annex
13777 However, the implementation approach used by GNAT provides for more
13778 extensive usage as follows:
13781 @item Communication between separate programs
13783 This allows separate programs to access the data in passive
13784 partitions, using protected objects for synchronization where
13785 needed. The only requirement is that the two programs have a
13786 common shared file system. It is even possible for programs
13787 running on different machines with different architectures
13788 (e.g. different endianness) to communicate via the data in
13789 a passive partition.
13791 @item Persistence between program runs
13793 The data in a passive package can persist from one run of a
13794 program to another, so that a later program sees the final
13795 values stored by a previous run of the same program.
13800 The implementation approach used is to store the data in files. A
13801 separate stream file is created for each object in the package, and
13802 an access to an object causes the corresponding file to be read or
13805 The environment variable @code{SHARED_MEMORY_DIRECTORY} should be
13806 @cindex @code{SHARED_MEMORY_DIRECTORY} environment variable
13807 set to the directory to be used for these files.
13808 The files in this directory
13809 have names that correspond to their fully qualified names. For
13810 example, if we have the package
13812 @smallexample @c ada
13814 pragma Shared_Passive (X);
13821 and the environment variable is set to @code{/stemp/}, then the files created
13822 will have the names:
13830 These files are created when a value is initially written to the object, and
13831 the files are retained until manually deleted. This provides the persistence
13832 semantics. If no file exists, it means that no partition has assigned a value
13833 to the variable; in this case the initial value declared in the package
13834 will be used. This model ensures that there are no issues in synchronizing
13835 the elaboration process, since elaboration of passive packages elaborates the
13836 initial values, but does not create the files.
13838 The files are written using normal @code{Stream_IO} access.
13839 If you want to be able
13840 to communicate between programs or partitions running on different
13841 architectures, then you should use the XDR versions of the stream attribute
13842 routines, since these are architecture independent.
13844 If active synchronization is required for access to the variables in the
13845 shared passive package, then as described in the Ada Reference Manual, the
13846 package may contain protected objects used for this purpose. In this case
13847 a lock file (whose name is @file{___lock} (three underscores)
13848 is created in the shared memory directory.
13849 @cindex @file{___lock} file (for shared passive packages)
13850 This is used to provide the required locking
13851 semantics for proper protected object synchronization.
13853 As of January 2003, GNAT supports shared passive packages on all platforms
13854 except for OpenVMS.
13856 @node Code Generation for Array Aggregates
13857 @section Code Generation for Array Aggregates
13860 * Static constant aggregates with static bounds::
13861 * Constant aggregates with an unconstrained nominal types::
13862 * Aggregates with static bounds::
13863 * Aggregates with non-static bounds::
13864 * Aggregates in assignment statements::
13868 Aggregate have a rich syntax and allow the user to specify the values of
13869 complex data structures by means of a single construct. As a result, the
13870 code generated for aggregates can be quite complex and involve loops, case
13871 statements and multiple assignments. In the simplest cases, however, the
13872 compiler will recognize aggregates whose components and constraints are
13873 fully static, and in those cases the compiler will generate little or no
13874 executable code. The following is an outline of the code that GNAT generates
13875 for various aggregate constructs. For further details, the user will find it
13876 useful to examine the output produced by the -gnatG flag to see the expanded
13877 source that is input to the code generator. The user will also want to examine
13878 the assembly code generated at various levels of optimization.
13880 The code generated for aggregates depends on the context, the component values,
13881 and the type. In the context of an object declaration the code generated is
13882 generally simpler than in the case of an assignment. As a general rule, static
13883 component values and static subtypes also lead to simpler code.
13885 @node Static constant aggregates with static bounds
13886 @subsection Static constant aggregates with static bounds
13889 For the declarations:
13890 @smallexample @c ada
13891 type One_Dim is array (1..10) of integer;
13892 ar0 : constant One_Dim := ( 1, 2, 3, 4, 5, 6, 7, 8, 9, 0);
13896 GNAT generates no executable code: the constant ar0 is placed in static memory.
13897 The same is true for constant aggregates with named associations:
13899 @smallexample @c ada
13900 Cr1 : constant One_Dim := (4 => 16, 2 => 4, 3 => 9, 1=> 1);
13901 Cr3 : constant One_Dim := (others => 7777);
13905 The same is true for multidimensional constant arrays such as:
13907 @smallexample @c ada
13908 type two_dim is array (1..3, 1..3) of integer;
13909 Unit : constant two_dim := ( (1,0,0), (0,1,0), (0,0,1));
13913 The same is true for arrays of one-dimensional arrays: the following are
13916 @smallexample @c ada
13917 type ar1b is array (1..3) of boolean;
13918 type ar_ar is array (1..3) of ar1b;
13919 None : constant ar1b := (others => false); -- fully static
13920 None2 : constant ar_ar := (1..3 => None); -- fully static
13924 However, for multidimensional aggregates with named associations, GNAT will
13925 generate assignments and loops, even if all associations are static. The
13926 following two declarations generate a loop for the first dimension, and
13927 individual component assignments for the second dimension:
13929 @smallexample @c ada
13930 Zero1: constant two_dim := (1..3 => (1..3 => 0));
13931 Zero2: constant two_dim := (others => (others => 0));
13934 @node Constant aggregates with an unconstrained nominal types
13935 @subsection Constant aggregates with an unconstrained nominal types
13938 In such cases the aggregate itself establishes the subtype, so that
13939 associations with @code{others} cannot be used. GNAT determines the
13940 bounds for the actual subtype of the aggregate, and allocates the
13941 aggregate statically as well. No code is generated for the following:
13943 @smallexample @c ada
13944 type One_Unc is array (natural range <>) of integer;
13945 Cr_Unc : constant One_Unc := (12,24,36);
13948 @node Aggregates with static bounds
13949 @subsection Aggregates with static bounds
13952 In all previous examples the aggregate was the initial (and immutable) value
13953 of a constant. If the aggregate initializes a variable, then code is generated
13954 for it as a combination of individual assignments and loops over the target
13955 object. The declarations
13957 @smallexample @c ada
13958 Cr_Var1 : One_Dim := (2, 5, 7, 11);
13959 Cr_Var2 : One_Dim := (others > -1);
13963 generate the equivalent of
13965 @smallexample @c ada
13971 for I in Cr_Var2'range loop
13972 Cr_Var2 (I) := =-1;
13976 @node Aggregates with non-static bounds
13977 @subsection Aggregates with non-static bounds
13980 If the bounds of the aggregate are not statically compatible with the bounds
13981 of the nominal subtype of the target, then constraint checks have to be
13982 generated on the bounds. For a multidimensional array, constraint checks may
13983 have to be applied to sub-arrays individually, if they do not have statically
13984 compatible subtypes.
13986 @node Aggregates in assignment statements
13987 @subsection Aggregates in assignment statements
13990 In general, aggregate assignment requires the construction of a temporary,
13991 and a copy from the temporary to the target of the assignment. This is because
13992 it is not always possible to convert the assignment into a series of individual
13993 component assignments. For example, consider the simple case:
13995 @smallexample @c ada
14000 This cannot be converted into:
14002 @smallexample @c ada
14008 So the aggregate has to be built first in a separate location, and then
14009 copied into the target. GNAT recognizes simple cases where this intermediate
14010 step is not required, and the assignments can be performed in place, directly
14011 into the target. The following sufficient criteria are applied:
14015 The bounds of the aggregate are static, and the associations are static.
14017 The components of the aggregate are static constants, names of
14018 simple variables that are not renamings, or expressions not involving
14019 indexed components whose operands obey these rules.
14023 If any of these conditions are violated, the aggregate will be built in
14024 a temporary (created either by the front-end or the code generator) and then
14025 that temporary will be copied onto the target.
14028 @node The Size of Discriminated Records with Default Discriminants
14029 @section The Size of Discriminated Records with Default Discriminants
14032 If a discriminated type @code{T} has discriminants with default values, it is
14033 possible to declare an object of this type without providing an explicit
14036 @smallexample @c ada
14038 type Size is range 1..100;
14040 type Rec (D : Size := 15) is record
14041 Name : String (1..D);
14049 Such an object is said to be @emph{unconstrained}.
14050 The discriminant of the object
14051 can be modified by a full assignment to the object, as long as it preserves the
14052 relation between the value of the discriminant, and the value of the components
14055 @smallexample @c ada
14057 Word := (3, "yes");
14059 Word := (5, "maybe");
14061 Word := (5, "no"); -- raises Constraint_Error
14066 In order to support this behavior efficiently, an unconstrained object is
14067 given the maximum size that any value of the type requires. In the case
14068 above, @code{Word} has storage for the discriminant and for
14069 a @code{String} of length 100.
14070 It is important to note that unconstrained objects do not require dynamic
14071 allocation. It would be an improper implementation to place on the heap those
14072 components whose size depends on discriminants. (This improper implementation
14073 was used by some Ada83 compilers, where the @code{Name} component above
14075 been stored as a pointer to a dynamic string). Following the principle that
14076 dynamic storage management should never be introduced implicitly,
14077 an Ada95 compiler should reserve the full size for an unconstrained declared
14078 object, and place it on the stack.
14080 This maximum size approach
14081 has been a source of surprise to some users, who expect the default
14082 values of the discriminants to determine the size reserved for an
14083 unconstrained object: ``If the default is 15, why should the object occupy
14085 The answer, of course, is that the discriminant may be later modified,
14086 and its full range of values must be taken into account. This is why the
14091 type Rec (D : Positive := 15) is record
14092 Name : String (1..D);
14100 is flagged by the compiler with a warning:
14101 an attempt to create @code{Too_Large} will raise @code{Storage_Error},
14102 because the required size includes @code{Positive'Last}
14103 bytes. As the first example indicates, the proper approach is to declare an
14104 index type of ``reasonable'' range so that unconstrained objects are not too
14107 One final wrinkle: if the object is declared to be @code{aliased}, or if it is
14108 created in the heap by means of an allocator, then it is @emph{not}
14110 it is constrained by the default values of the discriminants, and those values
14111 cannot be modified by full assignment. This is because in the presence of
14112 aliasing all views of the object (which may be manipulated by different tasks,
14113 say) must be consistent, so it is imperative that the object, once created,
14119 @node Project File Reference
14120 @chapter Project File Reference
14123 This chapter describes the syntax and semantics of project files.
14124 Project files specify the options to be used when building a system.
14125 Project files can specify global settings for all tools,
14126 as well as tool-specific settings.
14127 See the chapter on project files in the GNAT Users guide for examples of use.
14131 * Lexical Elements::
14133 * Empty declarations::
14134 * Typed string declarations::
14138 * Project Attributes::
14139 * Attribute References::
14140 * External Values::
14141 * Case Construction::
14143 * Package Renamings::
14145 * Project Extensions::
14146 * Project File Elaboration::
14149 @node Reserved Words
14150 @section Reserved Words
14153 All Ada95 reserved words are reserved in project files, and cannot be used
14154 as variable names or project names. In addition, the following are
14155 also reserved in project files:
14158 @item @code{extends}
14160 @item @code{external}
14162 @item @code{project}
14166 @node Lexical Elements
14167 @section Lexical Elements
14170 Rules for identifiers are the same as in Ada95. Identifiers
14171 are case-insensitive. Strings are case sensitive, except where noted.
14172 Comments have the same form as in Ada95.
14182 simple_name @{. simple_name@}
14186 @section Declarations
14189 Declarations introduce new entities that denote types, variables, attributes,
14190 and packages. Some declarations can only appear immediately within a project
14191 declaration. Others can appear within a project or within a package.
14195 declarative_item ::=
14196 simple_declarative_item |
14197 typed_string_declaration |
14198 package_declaration
14200 simple_declarative_item ::=
14201 variable_declaration |
14202 typed_variable_declaration |
14203 attribute_declaration |
14204 case_construction |
14208 @node Empty declarations
14209 @section Empty declarations
14212 empty_declaration ::=
14216 An empty declaration is allowed anywhere a declaration is allowed.
14219 @node Typed string declarations
14220 @section Typed string declarations
14223 Typed strings are sequences of string literals. Typed strings are the only
14224 named types in project files. They are used in case constructions, where they
14225 provide support for conditional attribute definitions.
14229 typed_string_declaration ::=
14230 @b{type} <typed_string_>_simple_name @b{is}
14231 ( string_literal @{, string_literal@} );
14235 A typed string declaration can only appear immediately within a project
14238 All the string literals in a typed string declaration must be distinct.
14244 Variables denote values, and appear as constituents of expressions.
14247 typed_variable_declaration ::=
14248 <typed_variable_>simple_name : <typed_string_>name := string_expression ;
14250 variable_declaration ::=
14251 <variable_>simple_name := expression;
14255 The elaboration of a variable declaration introduces the variable and
14256 assigns to it the value of the expression. The name of the variable is
14257 available after the assignment symbol.
14260 A typed_variable can only be declare once.
14263 a non typed variable can be declared multiple times.
14266 Before the completion of its first declaration, the value of variable
14267 is the null string.
14270 @section Expressions
14273 An expression is a formula that defines a computation or retrieval of a value.
14274 In a project file the value of an expression is either a string or a list
14275 of strings. A string value in an expression is either a literal, the current
14276 value of a variable, an external value, an attribute reference, or a
14277 concatenation operation.
14290 attribute_reference
14296 ( <string_>expression @{ , <string_>expression @} )
14299 @subsection Concatenation
14301 The following concatenation functions are defined:
14303 @smallexample @c ada
14304 function "&" (X : String; Y : String) return String;
14305 function "&" (X : String_List; Y : String) return String_List;
14306 function "&" (X : String_List; Y : String_List) return String_List;
14310 @section Attributes
14313 An attribute declaration defines a property of a project or package. This
14314 property can later be queried by means of an attribute reference.
14315 Attribute values are strings or string lists.
14317 Some attributes are associative arrays. These attributes are mappings whose
14318 domain is a set of strings. These attributes are declared one association
14319 at a time, by specifying a point in the domain and the corresponding image
14320 of the attribute. They may also be declared as a full associative array,
14321 getting the same associations as the corresponding attribute in an imported
14322 or extended project.
14324 Attributes that are not associative arrays are called simple attributes.
14328 attribute_declaration ::=
14329 full_associative_array_declaration |
14330 @b{for} attribute_designator @b{use} expression ;
14332 full_associative_array_declaration ::=
14333 @b{for} <associative_array_attribute_>simple_name @b{use}
14334 <project_>simple_name [ . <package_>simple_Name ] ' <attribute_>simple_name ;
14336 attribute_designator ::=
14337 <simple_attribute_>simple_name |
14338 <associative_array_attribute_>simple_name ( string_literal )
14342 Some attributes are project-specific, and can only appear immediately within
14343 a project declaration. Others are package-specific, and can only appear within
14344 the proper package.
14346 The expression in an attribute definition must be a string or a string_list.
14347 The string literal appearing in the attribute_designator of an associative
14348 array attribute is case-insensitive.
14350 @node Project Attributes
14351 @section Project Attributes
14354 The following attributes apply to a project. All of them are simple
14359 Expression must be a path name. The attribute defines the
14360 directory in which the object files created by the build are to be placed. If
14361 not specified, object files are placed in the project directory.
14364 Expression must be a path name. The attribute defines the
14365 directory in which the executables created by the build are to be placed.
14366 If not specified, executables are placed in the object directory.
14369 Expression must be a list of path names. The attribute
14370 defines the directories in which the source files for the project are to be
14371 found. If not specified, source files are found in the project directory.
14374 Expression must be a list of file names. The attribute
14375 defines the individual files, in the project directory, which are to be used
14376 as sources for the project. File names are path_names that contain no directory
14377 information. If the project has no sources the attribute must be declared
14378 explicitly with an empty list.
14380 @item Source_List_File
14381 Expression must a single path name. The attribute
14382 defines a text file that contains a list of source file names to be used
14383 as sources for the project
14386 Expression must be a path name. The attribute defines the
14387 directory in which a library is to be built. The directory must exist, must
14388 be distinct from the project's object directory, and must be writable.
14391 Expression must be a string that is a legal file name,
14392 without extension. The attribute defines a string that is used to generate
14393 the name of the library to be built by the project.
14396 Argument must be a string value that must be one of the
14397 following @code{"static"}, @code{"dynamic"} or @code{"relocatable"}. This
14398 string is case-insensitive. If this attribute is not specified, the library is
14399 a static library. Otherwise, the library may be dynamic or relocatable. This
14400 distinction is operating-system dependent.
14402 @item Library_Version
14403 Expression must be a string value whose interpretation
14404 is platform dependent. On UNIX, it is used only for dynamic/relocatable
14405 libraries as the internal name of the library (the @code{"soname"}). If the
14406 library file name (built from the @code{Library_Name}) is different from the
14407 @code{Library_Version}, then the library file will be a symbolic link to the
14408 actual file whose name will be @code{Library_Version}.
14410 @item Library_Interface
14411 Expression must be a string list. Each element of the string list
14412 must designate a unit of the project.
14413 If this attribute is present in a Library Project File, then the project
14414 file is a Stand-alone Library_Project_File.
14416 @item Library_Auto_Init
14417 Expression must be a single string "true" or "false", case-insensitive.
14418 If this attribute is present in a Stand-alone Library Project File,
14419 it indicates if initialization is automatic when the dynamic library
14422 @item Library_Options
14423 Expression must be a string list. Indicates additional switches that
14424 are to be used when building a shared library.
14427 Expression must be a single string. Designates an alternative to "gcc"
14428 for building shared libraries.
14430 @item Library_Src_Dir
14431 Expression must be a path name. The attribute defines the
14432 directory in which the sources of the interfaces of a Stand-alone Library will
14433 be copied. The directory must exist, must be distinct from the project's
14434 object directory and source directories, and must be writable.
14437 Expression must be a list of strings that are legal file names.
14438 These file names designate existing compilation units in the source directory
14439 that are legal main subprograms.
14441 When a project file is elaborated, as part of the execution of a gnatmake
14442 command, one or several executables are built and placed in the Exec_Dir.
14443 If the gnatmake command does not include explicit file names, the executables
14444 that are built correspond to the files specified by this attribute.
14446 @item Main_Language
14447 This is a simple attribute. Its value is a string that specifies the
14448 language of the main program.
14451 Expression must be a string list. Each string designates
14452 a programming language that is known to GNAT. The strings are case-insensitive.
14454 @item Locally_Removed_Files
14455 This attribute is legal only in a project file that extends another.
14456 Expression must be a list of strings that are legal file names.
14457 Each file name must designate a source that would normally be inherited
14458 by the current project file. It cannot designate an immediate source that is
14459 not inherited. Each of the source files in the list are not considered to
14460 be sources of the project file: they are not inherited.
14463 @node Attribute References
14464 @section Attribute References
14467 Attribute references are used to retrieve the value of previously defined
14468 attribute for a package or project.
14471 attribute_reference ::=
14472 attribute_prefix ' <simple_attribute_>simple_name [ ( string_literal ) ]
14474 attribute_prefix ::=
14476 <project_simple_name | package_identifier |
14477 <project_>simple_name . package_identifier
14481 If an attribute has not been specified for a given package or project, its
14482 value is the null string or the empty list.
14484 @node External Values
14485 @section External Values
14488 An external value is an expression whose value is obtained from the command
14489 that invoked the processing of the current project file (typically a
14495 @b{external} ( string_literal [, string_literal] )
14499 The first string_literal is the string to be used on the command line or
14500 in the environment to specify the external value. The second string_literal,
14501 if present, is the default to use if there is no specification for this
14502 external value either on the command line or in the environment.
14504 @node Case Construction
14505 @section Case Construction
14508 A case construction supports attribute declarations that depend on the value of
14509 a previously declared variable.
14513 case_construction ::=
14514 @b{case} <typed_variable_>name @b{is}
14519 @b{when} discrete_choice_list =>
14520 @{case_construction | attribute_declaration | empty_declaration@}
14522 discrete_choice_list ::=
14523 string_literal @{| string_literal@} |
14528 All choices in a choice list must be distinct. The choice lists of two
14529 distinct alternatives must be disjoint. Unlike Ada, the choice lists of all
14530 alternatives do not need to include all values of the type. An @code{others}
14531 choice must appear last in the list of alternatives.
14537 A package provides a grouping of variable declarations and attribute
14538 declarations to be used when invoking various GNAT tools. The name of
14539 the package indicates the tool(s) to which it applies.
14543 package_declaration ::=
14544 package_specification | package_renaming
14546 package_specification ::=
14547 @b{package} package_identifier @b{is}
14548 @{simple_declarative_item@}
14549 @b{end} package_identifier ;
14551 package_identifier ::=
14552 @code{Naming} | @code{Builder} | @code{Compiler} | @code{Binder} |
14553 @code{Linker} | @code{Finder} | @code{Cross_Reference} |
14554 @code{gnatls} | @code{IDE} | @code{Pretty_Printer}
14557 @subsection Package Naming
14560 The attributes of a @code{Naming} package specifies the naming conventions
14561 that apply to the source files in a project. When invoking other GNAT tools,
14562 they will use the sources in the source directories that satisfy these
14563 naming conventions.
14565 The following attributes apply to a @code{Naming} package:
14569 This is a simple attribute whose value is a string. Legal values of this
14570 string are @code{"lowercase"}, @code{"uppercase"} or @code{"mixedcase"}.
14571 These strings are themselves case insensitive.
14574 If @code{Casing} is not specified, then the default is @code{"lowercase"}.
14576 @item Dot_Replacement
14577 This is a simple attribute whose string value satisfies the following
14581 @item It must not be empty
14582 @item It cannot start or end with an alphanumeric character
14583 @item It cannot be a single underscore
14584 @item It cannot start with an underscore followed by an alphanumeric
14585 @item It cannot contain a dot @code{'.'} if longer than one character
14589 If @code{Dot_Replacement} is not specified, then the default is @code{"-"}.
14592 This is an associative array attribute, defined on language names,
14593 whose image is a string that must satisfy the following
14597 @item It must not be empty
14598 @item It cannot start with an alphanumeric character
14599 @item It cannot start with an underscore followed by an alphanumeric character
14603 For Ada, the attribute denotes the suffix used in file names that contain
14604 library unit declarations, that is to say units that are package and
14605 subprogram declarations. If @code{Spec_Suffix ("Ada")} is not
14606 specified, then the default is @code{".ads"}.
14608 For C and C++, the attribute denotes the suffix used in file names that
14609 contain prototypes.
14612 This is an associative array attribute defined on language names,
14613 whose image is a string that must satisfy the following
14617 @item It must not be empty
14618 @item It cannot start with an alphanumeric character
14619 @item It cannot start with an underscore followed by an alphanumeric character
14620 @item It cannot be a suffix of @code{Spec_Suffix}
14624 For Ada, the attribute denotes the suffix used in file names that contain
14625 library bodies, that is to say units that are package and subprogram bodies.
14626 If @code{Body_Suffix ("Ada")} is not specified, then the default is
14629 For C and C++, the attribute denotes the suffix used in file names that contain
14632 @item Separate_Suffix
14633 This is a simple attribute whose value satisfies the same conditions as
14634 @code{Body_Suffix}.
14636 This attribute is specific to Ada. It denotes the suffix used in file names
14637 that contain separate bodies. If it is not specified, then it defaults to same
14638 value as @code{Body_Suffix ("Ada")}.
14641 This is an associative array attribute, specific to Ada, defined over
14642 compilation unit names. The image is a string that is the name of the file
14643 that contains that library unit. The file name is case sensitive if the
14644 conventions of the host operating system require it.
14647 This is an associative array attribute, specific to Ada, defined over
14648 compilation unit names. The image is a string that is the name of the file
14649 that contains the library unit body for the named unit. The file name is case
14650 sensitive if the conventions of the host operating system require it.
14652 @item Specification_Exceptions
14653 This is an associative array attribute defined on language names,
14654 whose value is a list of strings.
14656 This attribute is not significant for Ada.
14658 For C and C++, each string in the list denotes the name of a file that
14659 contains prototypes, but whose suffix is not necessarily the
14660 @code{Spec_Suffix} for the language.
14662 @item Implementation_Exceptions
14663 This is an associative array attribute defined on language names,
14664 whose value is a list of strings.
14666 This attribute is not significant for Ada.
14668 For C and C++, each string in the list denotes the name of a file that
14669 contains source code, but whose suffix is not necessarily the
14670 @code{Body_Suffix} for the language.
14673 The following attributes of package @code{Naming} are obsolescent. They are
14674 kept as synonyms of other attributes for compatibility with previous versions
14675 of the Project Manager.
14678 @item Specification_Suffix
14679 This is a synonym of @code{Spec_Suffix}.
14681 @item Implementation_Suffix
14682 This is a synonym of @code{Body_Suffix}.
14684 @item Specification
14685 This is a synonym of @code{Spec}.
14687 @item Implementation
14688 This is a synonym of @code{Body}.
14691 @subsection package Compiler
14694 The attributes of the @code{Compiler} package specify the compilation options
14695 to be used by the underlying compiler.
14698 @item Default_Switches
14699 This is an associative array attribute. Its
14700 domain is a set of language names. Its range is a string list that
14701 specifies the compilation options to be used when compiling a component
14702 written in that language, for which no file-specific switches have been
14706 This is an associative array attribute. Its domain is
14707 a set of file names. Its range is a string list that specifies the
14708 compilation options to be used when compiling the named file. If a file
14709 is not specified in the Switches attribute, it is compiled with the
14710 settings specified by Default_Switches.
14712 @item Local_Configuration_Pragmas.
14713 This is a simple attribute, whose
14714 value is a path name that designates a file containing configuration pragmas
14715 to be used for all invocations of the compiler for immediate sources of the
14719 This is an associative array attribute. Its domain is
14720 a set of main source file names. Its range is a simple string that specifies
14721 the executable file name to be used when linking the specified main source.
14722 If a main source is not specified in the Executable attribute, the executable
14723 file name is deducted from the main source file name.
14726 @subsection package Builder
14729 The attributes of package @code{Builder} specify the compilation, binding, and
14730 linking options to be used when building an executable for a project. The
14731 following attributes apply to package @code{Builder}:
14734 @item Default_Switches
14740 @item Global_Configuration_Pragmas
14741 This is a simple attribute, whose
14742 value is a path name that designates a file that contains configuration pragmas
14743 to be used in every build of an executable. If both local and global
14744 configuration pragmas are specified, a compilation makes use of both sets.
14747 This is an associative array attribute, defined over
14748 compilation unit names. The image is a string that is the name of the
14749 executable file corresponding to the main source file index.
14750 This attribute has no effect if its value is the empty string.
14752 @item Executable_Suffix
14753 This is a simple attribute whose value is a suffix to be added to
14754 the executables that don't have an attribute Executable specified.
14757 @subsection package Gnatls
14760 The attributes of package @code{Gnatls} specify the tool options to be used
14761 when invoking the library browser @command{gnatls}.
14762 The following attributes apply to package @code{Gnatls}:
14769 @subsection package Binder
14772 The attributes of package @code{Binder} specify the options to be used
14773 when invoking the binder in the construction of an executable.
14774 The following attributes apply to package @code{Binder}:
14777 @item Default_Switches
14783 @subsection package Linker
14786 The attributes of package @code{Linker} specify the options to be used when
14787 invoking the linker in the construction of an executable.
14788 The following attributes apply to package @code{Linker}:
14791 @item Default_Switches
14797 @subsection package Cross_Reference
14800 The attributes of package @code{Cross_Reference} specify the tool options
14802 when invoking the library tool @command{gnatxref}.
14803 The following attributes apply to package @code{Cross_Reference}:
14806 @item Default_Switches
14812 @subsection package Finder
14815 The attributes of package @code{Finder} specify the tool options to be used
14816 when invoking the search tool @command{gnatfind}.
14817 The following attributes apply to package @code{Finder}:
14820 @item Default_Switches
14826 @subsection package Pretty_Printer
14829 The attributes of package @code{Pretty_Printer}
14830 specify the tool options to be used
14831 when invoking the formatting tool @command{gnatpp}.
14832 The following attributes apply to package @code{Pretty_Printer}:
14835 @item Default_switches
14841 @subsection package IDE
14844 The attributes of package @code{IDE} specify the options to be used when using
14845 an Integrated Development Environment such as @command{GPS}.
14849 This is a simple attribute. Its value is a string that designates the remote
14850 host in a cross-compilation environment, to be used for remote compilation and
14851 debugging. This field should not be specified when running on the local
14855 This is a simple attribute. Its value is a string that specifies the
14856 name of IP address of the embedded target in a cross-compilation environment,
14857 on which the program should execute.
14859 @item Communication_Protocol
14860 This is a simple string attribute. Its value is the name of the protocol
14861 to use to communicate with the target in a cross-compilation environment,
14862 e.g. @code{"wtx"} or @code{"vxworks"}.
14864 @item Compiler_Command
14865 This is an associative array attribute, whose domain is a language name. Its
14866 value is string that denotes the command to be used to invoke the compiler.
14867 The value of @code{Compiler_Command ("Ada")} is expected to be compatible with
14868 gnatmake, in particular in the handling of switches.
14870 @item Debugger_Command
14871 This is simple attribute, Its value is a string that specifies the name of
14872 the debugger to be used, such as gdb, powerpc-wrs-vxworks-gdb or gdb-4.
14874 @item Default_Switches
14875 This is an associative array attribute. Its indexes are the name of the
14876 external tools that the GNAT Programming System (GPS) is supporting. Its
14877 value is a list of switches to use when invoking that tool.
14880 This is a simple attribute. Its value is a string that specifies the name
14881 of the @command{gnatls} utility to be used to retrieve information about the
14882 predefined path; e.g., @code{"gnatls"}, @code{"powerpc-wrs-vxworks-gnatls"}.
14885 This is a simple attribute. Its value is a string used to specify the
14886 Version Control System (VCS) to be used for this project, e.g CVS, RCS
14887 ClearCase or Perforce.
14889 @item VCS_File_Check
14890 This is a simple attribute. Its value is a string that specifies the
14891 command used by the VCS to check the validity of a file, either
14892 when the user explicitly asks for a check, or as a sanity check before
14893 doing the check-in.
14895 @item VCS_Log_Check
14896 This is a simple attribute. Its value is a string that specifies
14897 the command used by the VCS to check the validity of a log file.
14901 @node Package Renamings
14902 @section Package Renamings
14905 A package can be defined by a renaming declaration. The new package renames
14906 a package declared in a different project file, and has the same attributes
14907 as the package it renames.
14910 package_renaming ::==
14911 @b{package} package_identifier @b{renames}
14912 <project_>simple_name.package_identifier ;
14916 The package_identifier of the renamed package must be the same as the
14917 package_identifier. The project whose name is the prefix of the renamed
14918 package must contain a package declaration with this name. This project
14919 must appear in the context_clause of the enclosing project declaration,
14920 or be the parent project of the enclosing child project.
14926 A project file specifies a set of rules for constructing a software system.
14927 A project file can be self-contained, or depend on other project files.
14928 Dependencies are expressed through a context clause that names other projects.
14934 context_clause project_declaration
14936 project_declaration ::=
14937 simple_project_declaration | project_extension
14939 simple_project_declaration ::=
14940 @b{project} <project_>simple_name @b{is}
14941 @{declarative_item@}
14942 @b{end} <project_>simple_name;
14948 [@b{limited}] @b{with} path_name @{ , path_name @} ;
14955 A path name denotes a project file. A path name can be absolute or relative.
14956 An absolute path name includes a sequence of directories, in the syntax of
14957 the host operating system, that identifies uniquely the project file in the
14958 file system. A relative path name identifies the project file, relative
14959 to the directory that contains the current project, or relative to a
14960 directory listed in the environment variable ADA_PROJECT_PATH.
14961 Path names are case sensitive if file names in the host operating system
14962 are case sensitive.
14964 The syntax of the environment variable ADA_PROJECT_PATH is a list of
14965 directory names separated by colons (semicolons on Windows).
14967 A given project name can appear only once in a context_clause.
14969 It is illegal for a project imported by a context clause to refer, directly
14970 or indirectly, to the project in which this context clause appears (the
14971 dependency graph cannot contain cycles), except when one of the with_clause
14972 in the cycle is a @code{limited with}.
14974 @node Project Extensions
14975 @section Project Extensions
14978 A project extension introduces a new project, which inherits the declarations
14979 of another project.
14983 project_extension ::=
14984 @b{project} <project_>simple_name @b{extends} path_name @b{is}
14985 @{declarative_item@}
14986 @b{end} <project_>simple_name;
14990 The project extension declares a child project. The child project inherits
14991 all the declarations and all the files of the parent project, These inherited
14992 declaration can be overridden in the child project, by means of suitable
14995 @node Project File Elaboration
14996 @section Project File Elaboration
14999 A project file is processed as part of the invocation of a gnat tool that
15000 uses the project option. Elaboration of the process file consists in the
15001 sequential elaboration of all its declarations. The computed values of
15002 attributes and variables in the project are then used to establish the
15003 environment in which the gnat tool will execute.
15005 @node Obsolescent Features
15006 @chapter Obsolescent Features
15009 This chapter describes features that are provided by GNAT, but are
15010 considered obsolescent since there are preferred ways of achieving
15011 the same effect. These features are provided solely for historical
15012 compatibility purposes.
15015 * pragma No_Run_Time::
15016 * pragma Ravenscar::
15017 * pragma Restricted_Run_Time::
15020 @node pragma No_Run_Time
15021 @section pragma No_Run_Time
15023 The pragma @code{No_Run_Time} is used to achieve an affect similar
15024 to the use of the "Zero Foot Print" configurable run time, but without
15025 requiring a specially configured run time. The result of using this
15026 pragma, which must be used for all units in a partition, is to restrict
15027 the use of any language features requiring run-time support code. The
15028 preferred usage is to use an appropriately configured run-time that
15029 includes just those features that are to be made accessible.
15031 @node pragma Ravenscar
15032 @section pragma Ravenscar
15034 The pragma @code{Ravenscar} has exactly the same effect as pragma
15035 @code{Profile (Ravenscar)}. The latter usage is preferred since it
15036 is part of the new Ada 2005 standard.
15038 @node pragma Restricted_Run_Time
15039 @section pragma Restricted_Run_Time
15041 The pragma @code{Restricted_Run_Time} has exactly the same effect as
15042 pragma @code{Profile (Restricted)}. The latter usage is
15043 preferred since the Ada 2005 pragma @code{Profile} is intended for
15044 this kind of implementation dependent addition.
15047 @c GNU Free Documentation License
15049 @node Index,,GNU Free Documentation License, Top